agent-learner是一个学习控制系统，帮助AI编程助手捕获工作中学到的规则、分离项目本地与全局学习资产，并提供仪表盘UI进行规则审查和推广。

agent-learner：为AI编程助手打造的可复用自我学习引擎\n\n随着 AI 编程助手（如 GitHub Copilot、Claude Code、Codex）的广泛应用，一个被忽视的问题逐渐浮现：这些助手在每次对话中都会产生有价值的经验——项目特定的约束、最佳实践、常见陷阱——但这些知识往往随着会话结束而丢失。agent-learner 正是为解决这一问题而设计的学习控制系统。\n\n## 问题背景：AI助手的"金鱼记忆"\n\n当前主流 AI 编程助手的工作模式通常是：\n\n1. 用户开启一个新会话\n2. 助手根据系统提示和上下文进行推理\n3. 会话中产生一些有价值的发现（如"本项目使用 black 而非 ruff 进行格式化"）\n4. 会话结束，这些发现随之消失\n5. 下次会话，助手重蹈覆辙\n\n这种"金鱼记忆"模式导致：\n- 重复犯同样的错误\n- 无法积累项目特定的知识\n- 用户需要反复解释相同的约束\n\n## agent-learner 的核心定位\n\nagent-learner 明确不是一个统一的 wiki 层，也不是要取代现有的 agent 环境。它的定位是：\n\n> 一个可复用的学习控制平面，层叠在现有 agent 环境之上\n\n### 设计原则\n\n1. 本地优先，全局复用：项目本地知识与可复用的全局知识分离\n2. 人工审查：候选规则需要人工确认后才推广为正式规则\n3. 检索优化：通过索引实现高效的规则检索\n4. 适配器无关：支持 Codex、Claude 等多种 agent 的 hook 安装\n\n## 知识生命周期管理\n\nagent-learner 定义了清晰的知识生命周期：\n\n### 1. 捕获（Capture）\n\n当 AI 助手在工作中产生有价值的发现时，通过适配器 hook 将其记录为候选规则（candidate）。候选规则包含：\n- 规则内容（如"使用 poetry 而非 pip"）\n- 来源上下文（触发该发现的对话片段）\n- 适配器决策理由\n\n### 2. 审查（Review）\n\n候选规则不会自动生效。用户通过仪表盘 UI 审查候选规则，决定：\n- 推广（promote）：成为项目本地或全局的正式规则\n- 拒绝（reject）：不适合作为规则记录\n- 搁置（defer）：暂时不确定，后续再评估\n\n### 3. 索引与检索（Index & Retrieve）\n\n正式规则被索引到机器可读的 index/rules.json，同时生成人类可读的 index/index.md。检索时：\n- 优先检索项目本地规则\n- 其次检索全局规则\n- 默认只注入已批准的规则（approved 状态）\n- 需要时可显式请求待审查或已弃用规则\n\n### 4. 推广（Promote）\n\n当某个项目本地规则被判断为可复用时，可推广到全局层：~/.agent-learner/global/。这样，其他项目也能受益于这条经验。\n\n## 存储架构\n\nagent-learner 采用双层存储架构：\n\n\n项目目录/\n└── .agent-learner/\n ├── candidates/ # 待审查的候选规则\n ├── rules/ # 已批准的本地规则\n ├── history/ # 规则应用历史\n └── index/\n ├── rules.json # 机器可读索引\n └── index.md # 人类可读摘要\n\n用户目录/\n└── .agent-learner/\n └── global/\n ├── rules/ # 全局可复用规则\n └── index/ # 全局索引\n\n\n这种分离设计的好处：\n- 项目本地知识不会污染全局空间\n- 全局规则可以跨项目共享\n- 版本控制可以只跟踪项目本地规则\n\n## 安装与使用\n\n### 快速开始\n\nPython 方式（推荐）：\nbash\npipx install \"agent-learner[web]\"\nagent-learner dashboard --project-root \"$PWD\" --open\n\n\nNode 方式：\nbash\nnpx @cafitac/agent-learner@latest dashboard --project-root \"$PWD\" --open\n\n\n### 安装适配器 Hook\n\nCodex（用户范围）：\nbash\nagent-learner install-codex\n\n\nClaude Code（项目范围）：\nbash\nagent-learner install-claude --target \"$PWD\"\n\n\n### 常用命令\n\nbash\n# 健康检查\nagent-learner doctor --project-root /path/to/repo\n\n# 审查候选规则\nagent-learner review-candidates --project-root /path/to/repo\n\n# 查看规则历史\nagent-learner history --project-root /path/to/repo --latest-per-rule --last 10\n\n# 重建索引（手动编辑规则后）\nagent-learner rebuild-index --project-root /path/to/repo\n\n# 项目概览\nagent-learner overview --project-root /path/to/repo --format json\n\n\n## 仪表盘功能\n\n仪表盘（默认运行在 127.0.0.1:8766）提供：\n\n- 候选规则面板：查看、筛选、推广或拒绝候选\n- 规则浏览器：按项目或全局查看已批准规则\n- 历史追踪：查看规则的应用记录和效果\n- 推广工作流：将本地规则推广到全局的界面\n\n技术栈：\n- 后端：FastAPI\n- 前端：React + Vite\n\n## 与现有系统的集成\n\nagent-learner 的设计理念是不取代、只增强：\n\n- 外部 wiki/KB 系统：保持独立，不参与学习生命周期\n- 版本控制：项目本地规则可纳入 git，全局规则通常不纳入\n- CI/CD：可在流水线中运行 doctor 检查学习系统健康状态\n\n## 实际应用场景\n\n### 场景1：团队编码规范沉淀\n\n团队使用 Claude Code 进行开发。随着时间推移，agent-learner 积累了大量候选规则：\n- "本项目使用 ruff 而非 flake8"\n- "测试文件必须放在 tests/ 目录，而非内联"\n- "API 响应必须使用 Pydantic 模型验证"\n\n团队 lead 定期审查仪表盘，将通用规则推广到全局，项目特定规则保留在本地。\n\n### 场景2：个人跨项目知识复用\n\n个人开发者在多个 Python 项目中工作。通过全局规则层，"使用 uv 而非 pip"、"优先使用 pathlib 而非 os.path" 等个人偏好可以自动应用到新项目。\n\n### 场景3：AI助手行为调优\n\n发现 AI 助手经常在某个特定类型的任务上犯错（如"总是忘记给 Pydantic 模型添加 Config 类"）。记录为规则后，后续会话中助手会自动收到提醒。\n\n## 技术亮点\n\n1. 存储独立性：规则存储与检索逻辑解耦，便于扩展\n2. 来源可追溯：每条规则记录来源，便于验证和更新\n3. 增量索引：只重新索引变更的规则，性能友好\n4. Shell 补全：提供 zsh/bash 补全脚本\n\n## 局限与注意事项\n\n- 人工审查瓶颈：候选规则需要人工审查，在快速迭代场景可能成为瓶颈\n- 规则冲突：项目本地规则与全局规则可能冲突，目前本地优先\n- 语义检索：当前基于关键词索引，未来可能需要语义检索增强\n\n## 总结\n\nagent-learner 填补了 AI 编程助手生态中的一个重要空白：如何让助手"记住"并"复用"经验。通过清晰的生命周期管理、本地/全局分离、以及人工审查机制，它在自动化与可控性之间取得了平衡。\n\n对于重度使用 AI 编程助手的开发者和团队，agent-learner 提供了一种系统化的知识管理方式，有望减少重复劳动，提升协作效率。

agent-learner：为AI编程助手打造的可复用自我学习引擎\n\n随着 AI 编程助手（如 GitHub Copilot、Claude Code、Codex）的广泛应用，一个被忽视的问题逐渐浮现：这些助手在每次对话中都会产生有价值的经验——项目特定的约束、最佳实践、常见陷阱——但这些知识往往随着会话结束而丢失。agent-learner 正是为解决这一问题而设计的学习控制系统。\n\n问题背景：AI助手的"金鱼记忆"\n\n当前主流 AI 编程助手的工作模式通常是：\n\n1. 用户开启一个新会话\n2. 助手根据系统提示和上下文进行推理\n3. 会话中产生一些有价值的发现（如"本项目使用 black 而非 ruff 进行格式化"）\n4. 会话结束，这些发现随之消失\n5. 下次会话，助手重蹈覆辙\n\n这种"金鱼记忆"模式导致：\n- 重复犯同样的错误\n- 无法积累项目特定的知识\n- 用户需要反复解释相同的约束\n\nagent-learner 的核心定位\n\nagent-learner 明确不是一个统一的 wiki 层，也不是要取代现有的 agent 环境。它的定位是：\n\n> 一个可复用的学习控制平面，层叠在现有 agent 环境之上\n\n设计原则\n\n1. 本地优先，全局复用：项目本地知识与可复用的全局知识分离\n2. 人工审查：候选规则需要人工确认后才推广为正式规则\n3. 检索优化：通过索引实现高效的规则检索\n4. 适配器无关：支持 Codex、Claude 等多种 agent 的 hook 安装\n\n知识生命周期管理\n\nagent-learner 定义了清晰的知识生命周期：\n\n1. 捕获（Capture）\n\n当 AI 助手在工作中产生有价值的发现时，通过适配器 hook 将其记录为候选规则（candidate）。候选规则包含：\n- 规则内容（如"使用 poetry 而非 pip"）\n- 来源上下文（触发该发现的对话片段）\n- 适配器决策理由\n\n2. 审查（Review）\n\n候选规则不会自动生效。用户通过仪表盘 UI 审查候选规则，决定：\n- 推广（promote）：成为项目本地或全局的正式规则\n- 拒绝（reject）：不适合作为规则记录\n- 搁置（defer）：暂时不确定，后续再评估\n\n3. 索引与检索（Index & Retrieve）\n\n正式规则被索引到机器可读的 index/rules.json，同时生成人类可读的 index/index.md。检索时：\n- 优先检索项目本地规则\n- 其次检索全局规则\n- 默认只注入已批准的规则（approved 状态）\n- 需要时可显式请求待审查或已弃用规则\n\n4. 推广（Promote）\n\n当某个项目本地规则被判断为可复用时，可推广到全局层：~/.agent-learner/global/。这样，其他项目也能受益于这条经验。\n\n存储架构\n\nagent-learner 采用双层存储架构：\n\n\n项目目录/\n└── .agent-learner/\n ├── candidates/ 待审查的候选规则\n ├── rules/ 已批准的本地规则\n ├── history/ 规则应用历史\n └── index/\n ├── rules.json 机器可读索引\n └── index.md 人类可读摘要\n\n用户目录/\n└── .agent-learner/\n └── global/\n ├── rules/ 全局可复用规则\n └── index/ 全局索引\n\n\n这种分离设计的好处：\n- 项目本地知识不会污染全局空间\n- 全局规则可以跨项目共享\n- 版本控制可以只跟踪项目本地规则\n\n安装与使用\n\n快速开始\n\nPython 方式（推荐）：\nbash\npipx install \"agent-learner[web]\"\nagent-learner dashboard --project-root \"$PWD\" --open\n\n\nNode 方式：\nbash\nnpx @cafitac/agent-learner@latest dashboard --project-root \"$PWD\" --open\n\n\n安装适配器 Hook\n\nCodex（用户范围）：\nbash\nagent-learner install-codex\n\n\nClaude Code（项目范围）：\nbash\nagent-learner install-claude --target \"$PWD\"\n\n\n常用命令\n\nbash\n健康检查\nagent-learner doctor --project-root /path/to/repo\n\n审查候选规则\nagent-learner review-candidates --project-root /path/to/repo\n\n查看规则历史\nagent-learner history --project-root /path/to/repo --latest-per-rule --last 10\n\n重建索引（手动编辑规则后）\nagent-learner rebuild-index --project-root /path/to/repo\n\n项目概览\nagent-learner overview --project-root /path/to/repo --format json\n\n\n仪表盘功能\n\n仪表盘（默认运行在 127.0.0.1:8766）提供：\n\n- 候选规则面板：查看、筛选、推广或拒绝候选\n- 规则浏览器：按项目或全局查看已批准规则\n- 历史追踪：查看规则的应用记录和效果\n- 推广工作流：将本地规则推广到全局的界面\n\n技术栈：\n- 后端：FastAPI\n- 前端：React + Vite\n\n与现有系统的集成\n\nagent-learner 的设计理念是不取代、只增强：\n\n- 外部 wiki/KB 系统：保持独立，不参与学习生命周期\n- 版本控制：项目本地规则可纳入 git，全局规则通常不纳入\n- CI/CD：可在流水线中运行 doctor 检查学习系统健康状态\n\n实际应用场景\n\n场景1：团队编码规范沉淀\n\n团队使用 Claude Code 进行开发。随着时间推移，agent-learner 积累了大量候选规则：\n- "本项目使用 ruff 而非 flake8"\n- "测试文件必须放在 tests/ 目录，而非内联"\n- "API 响应必须使用 Pydantic 模型验证"\n\n团队 lead 定期审查仪表盘，将通用规则推广到全局，项目特定规则保留在本地。\n\n场景2：个人跨项目知识复用\n\n个人开发者在多个 Python 项目中工作。通过全局规则层，"使用 uv 而非 pip"、"优先使用 pathlib 而非 os.path" 等个人偏好可以自动应用到新项目。\n\n场景3：AI助手行为调优\n\n发现 AI 助手经常在某个特定类型的任务上犯错（如"总是忘记给 Pydantic 模型添加 Config 类"）。记录为规则后，后续会话中助手会自动收到提醒。\n\n技术亮点\n\n1. 存储独立性：规则存储与检索逻辑解耦，便于扩展\n2. 来源可追溯：每条规则记录来源，便于验证和更新\n3. 增量索引：只重新索引变更的规则，性能友好\n4. Shell 补全：提供 zsh/bash 补全脚本\n\n局限与注意事项\n\n- 人工审查瓶颈：候选规则需要人工审查，在快速迭代场景可能成为瓶颈\n- 规则冲突：项目本地规则与全局规则可能冲突，目前本地优先\n- 语义检索：当前基于关键词索引，未来可能需要语义检索增强\n\n总结\n\nagent-learner 填补了 AI 编程助手生态中的一个重要空白：如何让助手"记住"并"复用"经验。通过清晰的生命周期管理、本地/全局分离、以及人工审查机制，它在自动化与可控性之间取得了平衡。\n\n对于重度使用 AI 编程助手的开发者和团队，agent-learner 提供了一种系统化的知识管理方式，有望减少重复劳动，提升协作效率。