Agent Learning Butler

Agent Learning Butler，简称 ALB，是一个本地优先的学习状态层和 MCP 连接器。

公开仓库：https://github.com/ljyoungs/agent-learning-butler

项目状态：

• 默认场景：AI Agent 开发通关路线
• 默认模式：Lite，本地 SQLite，第一次运行不需要 LLM Key
• 推荐入口：让 Codex / Claude Code / WorkBuddy 读取本仓库并帮你安装
• 授权协议：MIT

它解决的问题很具体：

你继续用 Codex、Claude Code、WorkBuddy 等 AI 工具聊天和写代码；
ALB 负责让这些 AI 工具知道：
你正在学哪条路线、今天该复习什么、哪里薄弱、哪些项目能变成作品证据。

ALB 不是另一个聊天机器人。它不和 Codex 抢“老师”的位置，也不内置强依赖 LLM。 它更像一个本地学习档案库：

Codex / Claude Code / WorkBuddy
        |
        | MCP 或 HTTP API
        v
Agent Learning Butler
        |
        | SQLite + 场景包 + FSRS + 知识库 + 项目证据包
        v
你的长期学习状态

默认开箱后会直接进入 AI Agent 开发通关路线，不用先回答一堆选择题。等你跑通 今日复习、项目证据包和 MCP 连接后，再用提示词切换到 AI 产品经理、英语学习、 编程学习、求职面试、读书研究等其他长期学习场景。

适合谁

• 想让 Codex / Claude Code / WorkBuddy 记住长期学习目标的人。
• 想把复习题、项目证据、知识库和外部资料统一接给 AI 助手的人。
• 想做 AI Agent 学习、AI 产品经理、英语、编程、面试等长期学习路线的人。
• 想本地运行，不想一上来就配置数据库、云服务和 LLM Key 的人。

不适合：

• 只想要一个网页聊天机器人。
• 只想做在线 SaaS 多用户平台。
• 不需要长期学习状态，只是偶尔问 AI 一个问题。

快速使用

推荐方式不是手动敲一堆命令，而是把安装任务交给你已经在用的 AI 编程工具。

1. 复制这段给 Codex / Claude Code

直接把下面的提示词发给 Codex、Claude Code、WorkBuddy 或其他能操作本地文件的 AI 工具：

最短版：

请帮我从 https://github.com/ljyoungs/agent-learning-butler 安装 Agent Learning Butler，启动本地 Lite 服务，配置 MCP，并返回访问地址、健康检查结果和第一条今日复习题测试指令。

更稳的详细版：

请帮我安装并启动 Agent Learning Butler。

GitHub 仓库：https://github.com/ljyoungs/agent-learning-butler
目标目录：C:\Agents\agent-learning-butler

请按下面要求完成，不要只给我命令：

1. 读取 GitHub 仓库的 README、pyproject.toml 和 scenario_packs 说明。
2. 检查本机是否有 Python 3.11+、Git 和 uv；缺少时先告诉我需要安装什么。
3. 下载或更新项目到目标目录。
4. 创建 .env，本地默认使用 SQLite，不要求我提供 OpenAI Key。
5. 初始化数据库。
6. 导入默认学习场景 ai-agent-development，不要在首次启动时要求我选择场景。
7. 启动 Lite 服务，优先使用 http://127.0.0.1:8000。
8. 验证 /health、/learning-path、/api/codex/capabilities 都能访问。
9. 输出最终结果：本地访问地址、健康检查结果、Codex MCP 配置片段、第一条测试指令。

如果 8000 端口被占用，请自动换一个可用端口，并在结果里告诉我。
如果你不能自动修改我的 MCP 配置，请把需要我粘贴的配置完整输出。

安装成功后，你应该得到：

ALB Lite 服务已启动
健康检查：ok
默认学习路线：AI Agent 开发通关路线
本地地址：http://127.0.0.1:8000

2. 让 AI 工具继续配置 MCP

安装完成后，再发这段：

请把 Agent Learning Butler 配成当前 AI 工具的 MCP Server。

要求：
1. 使用本地 stdio 模式连接，不要把 HTTP API 暴露到公网。
2. MCP Server 名称使用 agent-learning-butler。
3. 配置完成后调用 capabilities 和 context_get 做一次连通性验证。
4. 如果当前工具不能自动写配置，请输出我需要粘贴的配置内容和配置文件位置。

Codex MCP 配置大致长这样，AI 工具会根据你的真实安装路径替换目录：

[mcp_servers.agent-learning-butler]
command = "uv"
args = [
  "run",
  "--directory",
  "C:\\Agents\\agent-learning-butler",
  "python",
  "-c",
  "from alb.mcp_server import mcp; mcp.run(transport='stdio')"
]

3. 第一条测试指令

MCP 连上后，直接对 Codex / Claude Code / WorkBuddy 说：

请调用 agent-learning-butler 的 capabilities 和 context_get，
读取我当前的学习路线、到期复习和薄弱点。
然后基于当前 active learning path 给我出一张今日复习题。
我回答后，你负责批改，并调用 review_rate 写回 FSRS。

这就是 ALB 的核心闭环：

读取学习状态 -> 出题/讲解/批改 -> 写回复习结果 -> 更新下一次复习

手动备用启动

如果你不用 AI 工具安装，也可以手动运行：

git clone https://github.com/ljyoungs/agent-learning-butler agent-learning-butler
cd agent-learning-butler
uv sync
copy .env.example .env
uv run python scripts/init_db.py
uv run python scripts/import_scenario_pack.py ai-agent-development
uv run uvicorn alb.lite_main:app --reload

启动后打开：

• http://127.0.0.1:8000
• http://127.0.0.1:8000/health
• http://127.0.0.1:8000/learning-path
• http://127.0.0.1:8000/api/codex/capabilities

健康检查应该返回类似结果：

{"status":"ok","mode":"lite","version":"0.1.0"}

默认 Lite 模式使用 SQLite 和关键词检索。第一次运行不需要 Docker、Redis、 PostgreSQL、OpenAI Key、LangChain 或 LangGraph。

本地数据与隐私边界

ALB 的默认定位是“本地学习状态层”，不是在线 SaaS。

• 学习进度、复习记录、知识库和项目证据默认保存在本地 SQLite。
• .env、data/*、日志和私钥文件默认不会进入 Git。
• Lite 模式不要求配置 OpenAI Key，也不会主动调用外部 LLM。
• MCP 推荐使用 stdio 本地连接，让 AI 工具读写状态，而不是把 HTTP API 暴露公网。
• 如果要跨电脑访问，请放在 Tailscale、VPN 或 Cloudflare Access 后面。
• Hound 外部情报只适合采集公开来源，采集结果建议先人工判断质量，再沉淀为正式知识。

更完整的安全与隐私说明见 SECURITY.md。

马上能体验的 5 个功能

功能	你会看到什么	常用 MCP 工具
今日复习题	从当前学习路线抽一张到期卡片，AI 负责出题和批改	review_due, review_rate
学习路线切换	从默认 AI Agent 路线切到 AI 产品经理、英语、面试或自定义路线	scenario_list, scenario_get, scenario_activate
学习上下文	AI 先知道你当前路线、薄弱点、到期复习和今日任务	context_get, learning_next_action
项目证据包	把一个项目整理成架构说明、简历表达、面试追问和实验建议	project_list, project_get, project_evidence_pack
外部情报搜索	本地知识不够时，搜索公开来源并沉淀到学习状态	intelligence_search

功能总览

模块	作用	默认 Lite 可用
学习路线	保存当前 active learning path，控制复习、任务和推荐范围	是
FSRS 复习	记录卡片掌握度、稳定性、下次复习时间	是
知识库	保存学习内容，并支持本地检索	是
项目案例	保存项目详情、证据包、面试表达和实验建议	是
结构化记忆	记录偏好、薄弱点、进度、项目结论	是
今日计划	根据复习、路线、薄弱点生成下一步动作	是
场景包	导入不同学习场景，比如 AI Agent、RAG 工程	是
Hound 情报源	搜索 GitHub、网页、公开资料，补充新内容来源	是
Codex API	给 Codex 读取能力契约、上下文、项目证据包	是
MCP Server	给 Codex、Claude Code、WorkBuddy 通过 stdio 调用	是
内置 LLM Agent	直接在 ALB 内聊天、规划、问答	否，完整模式可选
pgvector 检索	PostgreSQL + 向量检索	否，完整模式可选

MCP 工具按场景理解

学习前先读状态：

capabilities
context_get
learning_next_action
learning_stats

切换学习场景：

scenario_list
scenario_get
scenario_activate

做 FSRS 复习：

review_due
review_rate

查知识和项目：

knowledge_search
knowledge_get
project_list
project_get
project_evidence_pack

执行学习任务：

daily_plan_show
daily_plan_generate
daily_plan_complete
daily_plan_skip
task_start
task_answer
task_complete

写入长期记忆和搜索外部资料：

memory_write
memory_list
intelligence_search

重要边界：

ALB 的 MCP Server 是纯数据层，不调用 LLM。Codex 或其他 AI 客户端负责讲解、 出题、批改和追问，然后把结构化结果写回 ALB。

学习场景包

场景包用于切换学习方向，不需要改代码。首次使用建议不要先切换，直接用默认 AI Agent 开发路线跑通完整闭环：

uv run python scripts/import_scenario_pack.py ai-agent-development

仓库内置的 RAG 工程路线是一个高级专题示例，可以用来验证场景切换机制：

uv run python scripts/import_scenario_pack.py rag-engineering

也可以直接从 MCP 客户端切换已有场景包：

scenario_list
scenario_get("rag-engineering")
scenario_activate("rag-engineering")

每个场景包包含：

• 初始文章、复习题和项目案例。
• 一条学习路线。
• 目标技能和默认薄弱点。
• Codex / Claude Code / WorkBuddy 的提示词模板。

场景包目录见 scenario_packs/。

场景切换提示词

ALB 默认只负责保存状态和提供工具。真正的场景切换建议交给 Codex、Claude Code、 WorkBuddy 这类 AI 客户端执行。

切换已有场景包：

请调用 agent-learning-butler 的 scenario_list 查看可用学习场景。
如果存在我指定的场景，请调用 scenario_activate 切换过去。
切换后请重新生成今日计划，并说明复习题、知识库搜索、项目证据包和 Hound 情报源会如何变化。

设计 AI 产品经理场景：

请帮我设计一个 AI 产品经理学习场景。
目标是提升 AI 产品判断、竞品分析、PRD 表达、用户洞察和增长实验能力。
请先用 memory_write 记录这个目标，再输出一份可加入 scenario_packs 的场景包方案。
方案需要包含：学习路线、复习卡类型、项目案例类型、推荐数据源、Hound 搜索策略和 MCP 使用提示词。

设计英语学习场景：

请帮我设计一个英语学习场景。
目标是提升技术英语阅读、口语表达和写作能力。
请规划每日复习方式、单词/句型/听力/写作卡片类型、资料来源和 ALB MCP 应该如何记录薄弱点。
如果当前仓库还没有这个场景包，请先给出场景包 JSON 结构和 prompts/codex.md 草案。

按当前场景获取数据源：

请读取 agent-learning-butler 当前 active learning path。
基于这个场景生成 5 个高质量资料搜索任务。
每个任务都要说明：为什么值得搜、适合补充哪类知识、搜到后应该转成文章/复习卡/项目案例/情报中的哪一种。
然后再调用 intelligence_search 采集候选资料，不要把低质量结果直接当成正式知识。

Hound 外部情报

Hound 是外部资料采集器，不是重型自主爬虫。

默认来源：

• DuckDuckGo HTML 搜索。
• 配置 GITHUB_TOKEN 后可搜索 GitHub 仓库和代码。
• 可选 Playwright 浏览器抓取，用于 JS 较重的网页。

适合在这些场景使用：

• 本地知识库不够，需要查新项目、新论文、新工具。
• 想把公开来源的标题、链接、摘要保存到学习状态里。
• 想让今日计划出现“情报阅读”任务。

uv run python -c "from alb.services.hound_sources import get_default_sources; print([s.name for s in get_default_sources()])"

完整模式

Lite 模式适合本地 MCP 使用，也是默认推荐方式。完整模式会开启内置 LLM 聊天、 简历优化、pgvector 检索、worker 和浏览器兜底等能力。

uv sync --extra full
uv run uvicorn alb.main:app --reload

按需安装更小的 extra：

uv sync --extra llm       # LangGraph/LangChain 内置聊天 Agent
uv sync --extra vector    # PostgreSQL + pgvector
uv sync --extra resume    # PDF/DOCX 简历解析
uv sync --extra browser   # Playwright 浏览器情报源
uv sync --extra worker    # Redis/Celery 后台任务
uv sync --extra mysql     # 旧 MySQL 项目迁移

远程电脑接入

如果 ALB 跑在一台电脑，Codex 跑在另一台电脑，建议把 ALB 放在 Tailscale、 Cloudflare Access 或 VPN 后面。另一台电脑本地运行一个 stdio MCP bridge， 把同名工具代理到 /api/codex/*。

不要把 ALB HTTP API 裸露到公网。

测试

核心 Lite 测试：

uv sync --extra dev
uv run pytest tests/test_embedding_service.py tests/test_lite_main.py tests/test_mcp_server.py -q

完整测试：

uv sync --extra full --extra dev
uv run pytest -q

目录结构

agent-learning-butler/
├── src/alb/
│   ├── lite_main.py      # 本地优先的轻量入口
│   ├── main.py           # 完整模式入口
│   ├── mcp_server.py     # 纯数据层 MCP 连接器
│   ├── api/              # HTTP API
│   ├── models/           # SQLAlchemy 数据模型
│   ├── services/         # 学习、复习、检索、记忆等服务
│   └── templates/        # 本地管理台页面
├── scenario_packs/       # 学习场景包和 AI 客户端提示词
├── scripts/              # 初始化、导入、迁移脚本
├── tests/                # 自动化测试
└── docker-compose.yml    # 可选 PostgreSQL + Redis 环境

许可证

本项目使用 MIT License。你可以自由使用、修改和分发，但请保留许可证和版权声明。