{"id":"f06e8410-c5de-4fde-8d23-bfc39b6a8352","slug":"sueryet-personalized-learning-agent","kind":"skill","name":"personalized-learning-agent","summary":"私人技术学习助教Agent","owner":"SUERYET","repoUrl":"https://github.com/SUERYET/personalized_learning_agent","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-08-08T06:15:10.000Z","addedAt":"2026-10-22T03:24:02.975Z","logoUrl":"https://avatars.githubusercontent.com/u/63184270?u=1d47ebec3f6c1cc502ff8c38fa1e0aaaf9f2cab8&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["writing"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T04:32:09.475Z","sample":false,"url":"https://conduits.dev/tools/sueryet-personalized-learning-agent","language":"Python","transports":["stdio"],"install":{"pypi":"studyagent"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# StudyAgent · 私人技术学习助教\n\n> 自研通用智能体 —— 对标 Claude Code 的交互体验与可扩展性，但不局限于代码编写。\n> 覆盖计算机科学与技术的学习、CV/深度学习、数学建模、编程开发、网络安全实验、Obsidian 知识库管理等场景。\n\n**设计哲学：核心极小化 + Skill 插件化** —— 一切能力通过 Tool / Skill 插件扩展，新增能力不改核心代码。\n\n---\n\n## ✨ 核心特性\n\n| 领域 | 能力 |\n|---|---|\n| 🧠 推理 | ReAct 循环 · 流式输出 · **工具并行执行** · 同工具失败熔断 · 迭代上限防死循环 |\n| 💾 记忆 | 短期记忆（前缀冻结 + 分块压缩 + **LLM 压缩摘要**，长会话不失忆）· 长期记忆（SQLite 知识点/偏好/会话存档）· 任务进度记录 |\n| 🧩 Skill 系统 | Python Skill 插件 + **SKILL.md 渐进式披露**（25 个生态 Skill 按需加载，不占上下文预算） |\n| 🔌 MCP | stdio + Streamable HTTP 双传输 · **Playwright 浏览器自动化**开箱即用 |\n| 📚 知识库 | Obsidian 关键词 + **语义向量混合检索**（numpy + bge-m3，失败自动回退） |\n| 🖼 多模态 | SiliconFlow Qwen-VL 图片分析 · CLI Alt+V / Web Ctrl+V 粘贴图片 |\n| 🔒 安全 | 危险操作分级确认：Shell/删除/笔记写入逐次确认（CLI 弹窗 / Web 确认卡片 / API 待确认队列） |\n| 🚀 双端 | 终端 CLI（prompt-toolkit + rich）+ Web 深色界面（FastAPI） |\n\n**Web 前端**：Markdown + **LaTeX（KaTeX）** + 代码高亮 · 斜杠命令补全 · 思考/工具/确认卡片 · 停止生成 · 会话分组/历史 · CherryStudio 式图片附件（悬停预览）· 计划模式横幅\n\n---\n\n## 🚀 快速开始\n\n### 环境要求\n- Python 3.11+\n- （可选，Web 图片分析）SiliconFlow 账号：https://cloud.siliconflow.cn/account/ak\n\n### 安装\n\n```bash\npip install -e .\ncp .env.example .env   # Windows: copy .env.example .env\n```\n\n编辑 `.env`，至少填写：\n\n```ini\nLLM_API_KEY=sk-...                # 主模型 Key（DeepSeek / 任何 OpenAI 兼容服务）\nLLM_API_KEY_BACKUP=sk-...         # 备用 Key（可选）\nWEB_SEARCH_API_KEY=               # 火山引擎豆包搜索 Key（可选）\nSILICONFLOW_API_KEY=              # 多模态图片分析 Key（可选）\n```\n\n### 启动 CLI\n\n```bash\nstudy\n```\n\n### 启动 Web\n\n```bash\nstudy serve        # 自动打开浏览器 → http://127.0.0.1:8600\n```\n\n> 端口可在 `.env` 修改：`API_PORT=8600`。设置 `API_TOKEN` 后 API 请求需携带 `X-API-Token` 头。\n\n---\n\n## 🖥 使用指南\n\n### 界面预览\n\n**Web 端**（`study serve` → http://127.0.0.1:8600）\n\n![Web 界面](https://images.sueryeto.cn/images/20260808143733525.webp)\n\n**终端 CLI**（`study`）\n\n![CLI 界面](https://images.sueryeto.cn/images/20260808143804191.webp)\n\n### CLI 键位\n\n| 键位 | 功能 |\n|---|---|\n| `Enter` | 发送 |\n| `Alt+Enter` / `Ctrl+J` | 换行 |\n| `Alt+V` | 粘贴图片（剪贴板 → 文件选择 → 输入框三级回退） |\n| `Ctrl+O` | 展开本轮思考过程 |\n| `↑ / ↓` | 历史输入 |\n| `Tab` | 补全斜杠指令 |\n| `Ctrl+D` | 退出 |\n\n### 斜杠指令\n\n| 指令 | 功能 |\n|---|---|\n| `/help` | 查看所有指令 |\n| `/plan on\\|off` | **计划模式**：先出计划待确认再执行 |\n| `/think on\\|off` | 思考过程显隐 |\n| `/memorize <知识点> [掌握度]` | 标记已掌握 |\n| `/forget <知识点>` | 移除记忆 |\n| `/memory list\\|search <词>` | 查看/搜索长期记忆 |\n| `/resume [id\\|#序号\\|last]` | 恢复历史会话（`/resume delete #2` 删除） |\n| `/save [标题]` | 保存并命名会话 |\n| `/usage` | 上下文占用与**缓存命中率** |\n| `/model [名称]` | 查看/切换模型（含 `@backup` 备用渠道） |\n| `/skills` `/tools` | 查看技能与工具 |\n| `/clear` | 清空会话上下文 |\n\n### Web 界面\n\n- 侧边栏：会话按「今天/昨天/更早」分组，hover 删除\n- 输入框：`/` 命令补全（↑↓ 选择 / Enter 应用）、**Ctrl+V / Alt+V 粘贴图片**（附件块 + 悬停预览）\n- 消息区：思考折叠块、工具卡片（参数/耗时/结果）、⚠️ 危险操作确认卡片（在线批准/拒绝）、`■ 停止` 按钮、代码块复制、整条回答复制\n- 历史消息显示真实时间（今天 `HH:MM`，更早 `MM-DD HH:MM`）\n\n---\n\n## 🧩 Skill 能力矩阵\n\n| 分类 | Skill | 说明 |\n|---|---|---|\n| 基础 | `utility` | 当前时间 / 安全表达式计算 |\n| 代码 | `code_executor` | Python 沙箱（超时 + **密钥窃取检测**）/ Shell（每次确认） |\n| 文件 | `file_operations` | 读写删列，路径锁定工作区 |\n| 知识库 | `obsidian_knowledge` | 搜索/读取/双链/反向链接，写入需确认 |\n| 检索 | `vector_index` | 语义检索（numpy + bge-m3），与关键词混合 |\n| 笔记 | `note_generator` | 网课/知识点笔记模板 |\n| 联网 | `web_search` | 火山引擎豆包搜索（网页/图片/时间过滤）+ 网页抓取 |\n| 多模态 | `multimodal` | 图片分析（本地路径 / URL / base64） |\n| 自测 | `self_test` | 出题/批改指令模板 |\n| 进度 | `progress_tracker` | 任务进度记录，自动注入会话 |\n| 并行 | `subagents` | 派发独立子任务（独立记忆 + 循环，危险操作自动拒绝） |\n| 按需加载 | `skill_loader` | `read_skill` 渐进式披露入口 |\n| MCP | `mcp` | 外部 MCP 服务器接入（`.mcp.json` 配置） |\n\n### 生态 Skill（来自 Claude Code，纯 SKILL.md）\n\n- **superpowers 方法论 ×14**：systematic-debugging、test-driven-development、writing-plans、verification-before-completion、brainstorming 等\n- **planning-with-files**：Manus 风格文件规划系统（24 脚本 + 模板）\n- **ui-ux-pro-max ×7**：banner-design、brand、design、design-system、slides、ui-styling 等\n- **officecli**：Office 文档（.docx/.xlsx/.pptx）处理\n- **sillytavern-web**：SillyTavern 生态集成\n- **通用对话归档总结**：会话归档\n\n> 所有 MD Skill 默认只注入一行路由描述，正文经 `read_skill` 按需加载 —— 几十个 Skill 共存不撑爆上下文预算。\n\n---\n\n## 🔌 MCP（Playwright 浏览器自动化）\n\n`.mcp.json` 已内置配置，首次使用需全局安装：\n\n```bash\nnpm install -g @playwright/mcp\n```\n\n启动后自动注册 **24 个浏览器工具**（导航/点击/填表/截图/网络请求等），`browser_navigate` 等真实调用已验证。\n\n自定义 MCP 服务器：编辑 `.mcp.json`（Claude Code 兼容格式），支持 stdio（`command`+`args`）与 HTTP（`url`，可选 `command` 自启服务器）两种传输。\n\n---\n\n## 🏗 架构概览\n\n```\n┌─────────────────────────────────────────────────────┐\n│ 交互层                                               │\n│   CLI（prompt-toolkit + rich）    Web（FastAPI + JS） │\n└────────────────────────┬────────────────────────────┘\n┌────────────────────────▼────────────────────────────┐\n│ 核心层 agent_core                                    │\n│   runtime（门面）→ ReAct 循环 → LLM 客户端 → 工具调度 │\n│   短期记忆（压缩+摘要） 长期记忆（SQLite） 确认队列   │\n└────────────────────────┬────────────────────────────┘\n┌────────────────────────▼────────────────────────────┐\n│ 扩展层                                               │\n│   skills/（Python + SKILL.md 渐进式披露）  MCP 服务器 │\n└─────────────────────────────────────────────────────┘\n```\n\n```\nagent_core/   核心：runtime / agent_loop / llm_client / memory / tool_registry / skill_manager\nskills/       扩展：12 个内置 Skill + 25 个生态 MD Skill + skill_md 解析器\ncli/          CLI 交互层\nserver/       Web：FastAPI + 静态前端（vendor 本地化，离线可用）\nmemory/       长期记忆 SQLite\ndata/         运行时数据（上传图片、向量索引）\n```\n\n---\n\n## ⚙️ 配置参考（`.env`）\n\n| 分组 | 变量 | 说明 |\n|---|---|---|\n| LLM | `LLM_PRIMARY_MODEL` / `LLM_API_BASE` / `LLM_API_KEY` | 主模型（OpenAI 兼容） |\n| | `LLM_API_KEY_BACKUP` / `LLM_MAX_RETRIES` / `LLM_TIMEOUT` | 备用 Key / 重试 / 超时 |\n| | `LLM_MODELS` | 可切换模型列表（`/model`），`@backup` 后缀走备用渠道 |\n| 路径 | `OBSIDIAN_VAULT_PATH` / `MEMORY_DB_PATH` / `LOG_DIR` | 知识库 / 记忆库 / 日志 |\n| 安全 | `SECURITY_CONFIRM_SHELL` / `SECURITY_CONFIRM_DELETE` / `SECURITY_OBSIDIAN_READONLY` | 危险操作确认开关 |\n| | `SECURITY_PYTHON_TIMEOUT` / `SECURITY_CONFIRM_TIMEOUT` | 沙箱超时 / 确认等待 |\n| Agent | `AGENT_MAX_ITERATIONS` / `AGENT_CONTEXT_TOKEN_BUDGET` / `AGENT_COMPACT_RATIO` | 循环上限 / 预算 / 压缩比例 |\n| | `AGENT_SUMMARIZE_ON_COMPACT` | 压缩时 LLM 摘要 |\n| CLI | `CLI_SHOW_THINKING` / `CLI_THEME` | 思考显隐 / 主题 |\n| 搜索 | `WEB_SEARCH_API_KEY` | 火山引擎豆包搜索 |\n| 多模态 | `SILICONFLOW_API_KEY` / `MULTIMODAL_MODEL` | SiliconFlow 视觉模型 |\n| 向量 | `VECTOR_ENABLED` / `VECTOR_EMBEDDING_MODEL` | 语义检索开关（默认关） |\n| API | `API_HOST` / `API_PORT` / `API_TOKEN` / `API_CONFIRM_TIMEOUT` | Web 服务 / 鉴权 / 确认超时 |\n\n---\n\n## 📡 HTTP API\n\n| 端点 | 功能 |\n|---|---|\n| `POST /api/v1/chat` | 单轮对话 `{message, session_id?}` |\n| `POST /api/v1/chat/stream` | **SSE 流式**（thinking/delta/tool_call/tool_result/confirmation/done） |\n| `GET /api/v1/sessions` · `DELETE /api/v1/sessions/{id}` | 会话管理 |\n| `GET /api/v1/sessions/{id}/messages` | 历史消息（含 created_at） |\n| `GET /api/v1/confirmations` · `POST /api/v1/confirmations/{id}` | 待确认操作列表/裁决 |\n| `POST /api/v1/command` | 斜杠指令（`/help` `/memorize` `/plan` 等） |\n| `POST /api/v1/images` | 图片上传（base64 → `data/uploads/`） |\n| `GET /api/v1/health` | 健康检查 |\n\n鉴权：配置 `API_TOKEN` 后，请求需带 `X-API-Token: <token>` 或 `Authorization: Bearer <token>`。\n\n---\n\n## 🧪 开发指南\n\n### 测试\n\n```bash\npytest                    # 397 个测试，全部离线可跑（FakeLLM 注入，不烧 token）\n```\n\n覆盖：ReAct 循环、记忆压缩/摘要、缓存前缀稳定性、LLM 重试/降级、Skill 加载、MCP 双传输、HTTP API、Web E2E（Playwright 真浏览器：LaTeX 渲染、确认卡片、图片粘贴、命令补全）。\n\n### 新增一个 Skill\n\n```python\n# skills/my_skill/skill.py\nfrom agent_core.tool_spec import SafetyLevel, ToolDefinition, ToolResult\nfrom skills.base_skill import BaseSkill\n\nclass MySkill(BaseSkill):\n    name = \"my_skill\"\n    description = \"触发词密集的路由描述\"\n\n    @property\n    def tools(self) -> list[ToolDefinition]:\n        return [ToolDefinition(name=\"my_tool\", description=\"...\",\n                               parameters={...}, safety_level=SafetyLevel.SAFE)]\n\n    async def execute(self, tool_name: str, params: dict) -> ToolResult:\n        return ToolResult.success(\"结果\")\n```\n\n在 `skills/my_skill/__init__.py` 导出后重启即可自动发现。纯指令型 Skill 只需放一个 `SKILL.md`（支持 YAML frontmatter 与折叠块），经 `read_skill` 按需加载。\n\n---\n\n## 🗺 路线图\n\n- [x] 阶段 0-5：核心循环 / Skill 系统 / 知识库 / 代码执行 / 长期记忆 / Web 体验打磨\n- [x] 阶段 6：AgentRuntime 门面 · HTTP API · Web 前端 · 待确认队列 · 语义检索\n- [ ] NoneBot（QQ）渠道 —— API 已就绪，可直接对接\n- [ ] P2：ruff + mypy + CI · README 配图 · 版本 bump · Web 深浅色切换\n\n## 📄 License\n\n[MIT](LICENSE) © 2026 SUERYET\n"}