skill

personalized-learning-agent

私人技术学习助教Agent

SUERYET/personalized_learning_agentcommunitylistedunreviewed

Set up

Skills are installed by placing their folder where your agent loads skills.

Download ZIP from GitHub Open the repository

The download comes from github.com/SUERYET/personalized_learning_agent itself, not from our server, so what you get is exactly what its author published.

Install instructions come from the README

Skills do not use an MCP config. Follow the steps in the README below.

README

synced Oct 26, 2026

StudyAgent · 私人技术学习助教

自研通用智能体 —— 对标 Claude Code 的交互体验与可扩展性，但不局限于代码编写。覆盖计算机科学与技术的学习、CV/深度学习、数学建模、编程开发、网络安全实验、Obsidian 知识库管理等场景。

设计哲学：核心极小化 + Skill 插件化 —— 一切能力通过 Tool / Skill 插件扩展，新增能力不改核心代码。

✨ 核心特性

领域	能力
🧠 推理	ReAct 循环 · 流式输出 · 工具并行执行 · 同工具失败熔断 · 迭代上限防死循环
💾 记忆	短期记忆（前缀冻结 + 分块压缩 + LLM 压缩摘要，长会话不失忆）· 长期记忆（SQLite 知识点/偏好/会话存档）· 任务进度记录
🧩 Skill 系统	Python Skill 插件 + SKILL.md 渐进式披露（25 个生态 Skill 按需加载，不占上下文预算）
🔌 MCP	stdio + Streamable HTTP 双传输 · Playwright 浏览器自动化开箱即用
📚 知识库	Obsidian 关键词 + 语义向量混合检索（numpy + bge-m3，失败自动回退）
🖼 多模态	SiliconFlow Qwen-VL 图片分析 · CLI Alt+V / Web Ctrl+V 粘贴图片
🔒 安全	危险操作分级确认：Shell/删除/笔记写入逐次确认（CLI 弹窗 / Web 确认卡片 / API 待确认队列）
🚀 双端	终端 CLI（prompt-toolkit + rich）+ Web 深色界面（FastAPI）

Web 前端：Markdown + LaTeX（KaTeX） + 代码高亮 · 斜杠命令补全 · 思考/工具/确认卡片 · 停止生成 · 会话分组/历史 · CherryStudio 式图片附件（悬停预览）· 计划模式横幅

🚀 快速开始

环境要求

Python 3.11+
（可选，Web 图片分析）SiliconFlow 账号：https://cloud.siliconflow.cn/account/ak

安装

pip install -e .
cp .env.example .env   # Windows: copy .env.example .env

编辑 .env，至少填写：

LLM_API_KEY=sk-...                # 主模型 Key（DeepSeek / 任何 OpenAI 兼容服务）
LLM_API_KEY_BACKUP=sk-...         # 备用 Key（可选）
WEB_SEARCH_API_KEY=               # 火山引擎豆包搜索 Key（可选）
SILICONFLOW_API_KEY=              # 多模态图片分析 Key（可选）

启动 CLI

study

启动 Web

study serve        # 自动打开浏览器 → http://127.0.0.1:8600

端口可在 .env 修改：API_PORT=8600。设置 API_TOKEN 后 API 请求需携带 X-API-Token 头。

🖥 使用指南

界面预览

Web 端（study serve → http://127.0.0.1:8600）

Web 界面

终端 CLI（study）

CLI 界面

CLI 键位

键位	功能
`Enter`	发送
`Alt+Enter` / `Ctrl+J`	换行
`Alt+V`	粘贴图片（剪贴板 → 文件选择 → 输入框三级回退）
`Ctrl+O`	展开本轮思考过程
`↑ / ↓`	历史输入
`Tab`	补全斜杠指令
`Ctrl+D`	退出

斜杠指令

指令	功能
`/help`	查看所有指令
`/plan on\|off`	计划模式：先出计划待确认再执行
`/think on\|off`	思考过程显隐
`/memorize <知识点> [掌握度]`	标记已掌握
`/forget <知识点>`	移除记忆
`/memory list\|search <词>`	查看/搜索长期记忆
`/resume [id\|#序号\|last]`	恢复历史会话（`/resume delete #2` 删除）
`/save [标题]`	保存并命名会话
`/usage`	上下文占用与缓存命中率
`/model [名称]`	查看/切换模型（含 `@backup` 备用渠道）
`/skills` `/tools`	查看技能与工具
`/clear`	清空会话上下文

Web 界面

侧边栏：会话按「今天/昨天/更早」分组，hover 删除
输入框：/ 命令补全（↑↓ 选择 / Enter 应用）、Ctrl+V / Alt+V 粘贴图片（附件块 + 悬停预览）
消息区：思考折叠块、工具卡片（参数/耗时/结果）、⚠️ 危险操作确认卡片（在线批准/拒绝）、■ 停止 按钮、代码块复制、整条回答复制
历史消息显示真实时间（今天 HH:MM，更早 MM-DD HH:MM）

🧩 Skill 能力矩阵

分类	Skill	说明
基础	`utility`	当前时间 / 安全表达式计算
代码	`code_executor`	Python 沙箱（超时 + 密钥窃取检测）/ Shell（每次确认）
文件	`file_operations`	读写删列，路径锁定工作区
知识库	`obsidian_knowledge`	搜索/读取/双链/反向链接，写入需确认
检索	`vector_index`	语义检索（numpy + bge-m3），与关键词混合
笔记	`note_generator`	网课/知识点笔记模板
联网	`web_search`	火山引擎豆包搜索（网页/图片/时间过滤）+ 网页抓取
多模态	`multimodal`	图片分析（本地路径 / URL / base64）
自测	`self_test`	出题/批改指令模板
进度	`progress_tracker`	任务进度记录，自动注入会话
并行	`subagents`	派发独立子任务（独立记忆 + 循环，危险操作自动拒绝）
按需加载	`skill_loader`	`read_skill` 渐进式披露入口
MCP	`mcp`	外部 MCP 服务器接入（`.mcp.json` 配置）

生态 Skill（来自 Claude Code，纯 SKILL.md）

superpowers 方法论 ×14：systematic-debugging、test-driven-development、writing-plans、verification-before-completion、brainstorming 等
planning-with-files：Manus 风格文件规划系统（24 脚本 + 模板）
ui-ux-pro-max ×7：banner-design、brand、design、design-system、slides、ui-styling 等
officecli：Office 文档（.docx/.xlsx/.pptx）处理
sillytavern-web：SillyTavern 生态集成
通用对话归档总结：会话归档

所有 MD Skill 默认只注入一行路由描述，正文经 read_skill 按需加载 —— 几十个 Skill 共存不撑爆上下文预算。

🔌 MCP（Playwright 浏览器自动化）

.mcp.json 已内置配置，首次使用需全局安装：

npm install -g @playwright/mcp

启动后自动注册 24 个浏览器工具（导航/点击/填表/截图/网络请求等），browser_navigate 等真实调用已验证。

自定义 MCP 服务器：编辑 .mcp.json（Claude Code 兼容格式），支持 stdio（command+args）与 HTTP（url，可选 command 自启服务器）两种传输。

🏗 架构概览

┌─────────────────────────────────────────────────────┐
│ 交互层                                               │
│   CLI（prompt-toolkit + rich）    Web（FastAPI + JS） │
└────────────────────────┬────────────────────────────┘
┌────────────────────────▼────────────────────────────┐
│ 核心层 agent_core                                    │
│   runtime（门面）→ ReAct 循环 → LLM 客户端 → 工具调度 │
│   短期记忆（压缩+摘要） 长期记忆（SQLite） 确认队列   │
└────────────────────────┬────────────────────────────┘
┌────────────────────────▼────────────────────────────┐
│ 扩展层                                               │
│   skills/（Python + SKILL.md 渐进式披露）  MCP 服务器 │
└─────────────────────────────────────────────────────┘

agent_core/   核心：runtime / agent_loop / llm_client / memory / tool_registry / skill_manager
skills/       扩展：12 个内置 Skill + 25 个生态 MD Skill + skill_md 解析器
cli/          CLI 交互层
server/       Web：FastAPI + 静态前端（vendor 本地化，离线可用）
memory/       长期记忆 SQLite
data/         运行时数据（上传图片、向量索引）

⚙️ 配置参考（`.env`）

分组	变量	说明
LLM	`LLM_PRIMARY_MODEL` / `LLM_API_BASE` / `LLM_API_KEY`	主模型（OpenAI 兼容）
	`LLM_API_KEY_BACKUP` / `LLM_MAX_RETRIES` / `LLM_TIMEOUT`	备用 Key / 重试 / 超时
	`LLM_MODELS`	可切换模型列表（`/model`），`@backup` 后缀走备用渠道
路径	`OBSIDIAN_VAULT_PATH` / `MEMORY_DB_PATH` / `LOG_DIR`	知识库 / 记忆库 / 日志
安全	`SECURITY_CONFIRM_SHELL` / `SECURITY_CONFIRM_DELETE` / `SECURITY_OBSIDIAN_READONLY`	危险操作确认开关
	`SECURITY_PYTHON_TIMEOUT` / `SECURITY_CONFIRM_TIMEOUT`	沙箱超时 / 确认等待
Agent	`AGENT_MAX_ITERATIONS` / `AGENT_CONTEXT_TOKEN_BUDGET` / `AGENT_COMPACT_RATIO`	循环上限 / 预算 / 压缩比例
	`AGENT_SUMMARIZE_ON_COMPACT`	压缩时 LLM 摘要
CLI	`CLI_SHOW_THINKING` / `CLI_THEME`	思考显隐 / 主题
搜索	`WEB_SEARCH_API_KEY`	火山引擎豆包搜索
多模态	`SILICONFLOW_API_KEY` / `MULTIMODAL_MODEL`	SiliconFlow 视觉模型
向量	`VECTOR_ENABLED` / `VECTOR_EMBEDDING_MODEL`	语义检索开关（默认关）
API	`API_HOST` / `API_PORT` / `API_TOKEN` / `API_CONFIRM_TIMEOUT`	Web 服务 / 鉴权 / 确认超时

📡 HTTP API

端点	功能
`POST /api/v1/chat`	单轮对话 `{message, session_id?}`
`POST /api/v1/chat/stream`	SSE 流式（thinking/delta/tool_call/tool_result/confirmation/done）
`GET /api/v1/sessions` · `DELETE /api/v1/sessions/{id}`	会话管理
`GET /api/v1/sessions/{id}/messages`	历史消息（含 created_at）
`GET /api/v1/confirmations` · `POST /api/v1/confirmations/{id}`	待确认操作列表/裁决
`POST /api/v1/command`	斜杠指令（`/help` `/memorize` `/plan` 等）
`POST /api/v1/images`	图片上传（base64 → `data/uploads/`）
`GET /api/v1/health`	健康检查

鉴权：配置 API_TOKEN 后，请求需带 X-API-Token: <token> 或 Authorization: Bearer <token>。

🧪 开发指南

测试

pytest                    # 397 个测试，全部离线可跑（FakeLLM 注入，不烧 token）

覆盖：ReAct 循环、记忆压缩/摘要、缓存前缀稳定性、LLM 重试/降级、Skill 加载、MCP 双传输、HTTP API、Web E2E（Playwright 真浏览器：LaTeX 渲染、确认卡片、图片粘贴、命令补全）。

新增一个 Skill

# skills/my_skill/skill.py
from agent_core.tool_spec import SafetyLevel, ToolDefinition, ToolResult
from skills.base_skill import BaseSkill

class MySkill(BaseSkill):
    name = "my_skill"
    description = "触发词密集的路由描述"

    @property
    def tools(self) -> list[ToolDefinition]:
        return [ToolDefinition(name="my_tool", description="...",
                               parameters={...}, safety_level=SafetyLevel.SAFE)]

    async def execute(self, tool_name: str, params: dict) -> ToolResult:
        return ToolResult.success("结果")

在 skills/my_skill/__init__.py 导出后重启即可自动发现。纯指令型 Skill 只需放一个 SKILL.md（支持 YAML frontmatter 与折叠块），经 read_skill 按需加载。

🗺 路线图

阶段 0-5：核心循环 / Skill 系统 / 知识库 / 代码执行 / 长期记忆 / Web 体验打磨
阶段 6：AgentRuntime 门面 · HTTP API · Web 前端 · 待确认队列 · 语义检索
NoneBot（QQ）渠道 —— API 已就绪，可直接对接
P2：ruff + mypy + CI · README 配图 · 版本 bump · Web 深浅色切换

personalized-learning-agent

Set up

README

StudyAgent · 私人技术学习助教

✨ 核心特性

🚀 快速开始

环境要求

安装

启动 CLI

启动 Web

🖥 使用指南

界面预览

CLI 键位

斜杠指令

Web 界面

🧩 Skill 能力矩阵

生态 Skill（来自 Claude Code，纯 SKILL.md）

🔌 MCP（Playwright 浏览器自动化）

🏗 架构概览

⚙️ 配置参考（.env）

📡 HTTP API

🧪 开发指南

测试

新增一个 Skill

🗺 路线图

📄 License

⚙️ 配置参考（`.env`）