[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-11176":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":14,"stars30d":15,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":16,"rankGlobal":9,"rankLanguage":9,"license":9,"archived":17,"fork":17,"defaultBranch":18,"hasWiki":19,"hasPages":17,"topics":20,"createdAt":9,"pushedAt":9,"updatedAt":21,"readmeContent":22,"aiSummary":23,"trendingCount":14,"starSnapshotCount":14,"syncStatus":24,"lastSyncTime":25,"discoverSource":26},11176,"controllable-agent","Yang1999code\u002Fcontrollable-agent","Yang1999code","20-interface AI agent framework with 3-layer architecture, multi-agent delegation, and self-evolution.",null,"Python",104,1,29,0,35,41.4,false,"master",true,[],"2026-06-12 04:00:54","# Controllable Agent\n\n> 一个能自己组织团队、自己记忆、自己进化的 AI Agent 框架。\n> 5 个 Agent 角色分工协作 + Wiki 式记忆系统 + 实时终端可视化。\n\n---\n\n## 它能做什么？\n\n想象你给 AI 一个复杂任务，比如\"帮我从零搭建一个认证系统\"。\n\n普通 Agent 会怎么做？一个模型从头干到尾，边写边忘，写到后面忘了前面。\n\n**Controllable Agent 会这么做**：\n\n```\n你：\"帮我实现用户认证模块\"\n\n1. Planner 先分析需求，拆成 3 个子任务，写好计划\n2. 3 组 Coder + Reviewer 配对并行开工\n   - Coder 写 JWT → Reviewer 验证 → 通过\n   - Coder 写路由 → Reviewer 验证 → 有 bug → 修复 → 再验 → 通过\n   - Coder 写中间件 → Reviewer 验证 → 通过\n3. Coordinator 全程监控，谁卡了就拉一把\n4. 总体集成测试 → 通过\n5. Memorizer 提炼经验，下次更快\n\n全程你可以随时插话，Coordinator 会接住你的补充信息。\n```\n\n**不需要你指挥，5 个 Agent 自己协商、并行、互相审查。**\n\n---\n\n## 两大创新\n\n### 创新 1：5 角色分工的多 Agent 协作\n\n不是把任务丢给一个 Agent，而是像软件团队一样分工：\n\n| 角色 | 干什么 | 一句话 |\n|------|--------|--------|\n| **Coordinator** | 管理者 | 不干活，专门管人。谁能创建、谁越权了、谁卡住了 |\n| **Planner** | 设计师 | 写计划但不走人，全程动态调整，永远记住用户原话 |\n| **Coder** | 开发 | 写代码、跑测试，按计划执行 |\n| **Reviewer** | 审查 | 和 Coder 配对，写完一个模块立马验，边写边审 |\n| **Memorizer** | 记录员 | 记事 + 从经验中提炼可复用技能 |\n\n关键设计：\n\n- **Coder + Reviewer 配对**：不是写完再审查，而是写一个小模块就验一个，快速迭代。多组配对可以并行跑。\n- **两层打回**：模块级打回不限次数（配对内自己解决），总体集成测试最多 3 轮。超了就升级给你处理。\n- **用户随时插话**：你中途补充的信息由 Coordinator 接收，按紧急度分级处理，不中断主流程。\n- **嵌套深度控制**：最多 2 层（主 Agent → Coordinator → 工作 Agent），防止套娃。\n- **无硬编码上限**：任务拆得越细，配对越多，并行度越高。用 Semaphore 控制并发。\n\n详见 [多智能体设计.md](多智能体设计.md)。\n\n### 创新 2：Wiki 式记忆系统\n\nAgent 的记忆不是混沌的聊天记录，而是像 Wikipedia 一样结构化：\n\n```\n你做了几次任务\n    ↓\n每次完成后，自动提取摘要（digest）—— 标题 + 3-5 个要点\n    ↓\n积累 5+ 个同主题的摘要后，合并成知识页（wiki）\n    ↓\n下次遇到类似问题，先查 wiki（最完整），再查 digest（更细粒度）\n查不到 = 没说过 = 不编造（抗幻觉）\n```\n\n**核心特点**：\n\n- **digest → wiki 两层就够**：大部分信息一个摘要 + 一个知识页就覆盖了\n- **Markdown + YAML frontmatter 存储**：人可读，用任何编辑器都能看\n- **四域分类**：对话记忆、个人档案、Agent 视角、任务状态，各有分工\n- **专用轻量模型提取**：主 Agent 不分心，用便宜的小模型做记忆提取\n- **批量而非逐轮**：一个任务单元完成后才提取，不是每句话都存\n- **多 Agent 隔离**：每个 Agent 有独立记忆空间，通过共享区交流，互不干扰\n\n详见 [我的记忆改进.md](我的记忆改进.md)。\n\n---\n\n## 技术架构\n\n三层单向依赖，绝不反向：\n\n```\nai\u002F          ← 核心类型（Message, Tool, Context），零依赖\nagent\u002F       ← 20 个接口实现（循环, 工具, 记忆, Hook, 运行时...）\napp\u002F         ← CLI + 15 内置工具 + 模型适配器 + 配置 + TUI\n```\n\n**核心信条**：\n- **分层单向依赖** -- `ai\u002F` 零依赖 -> `agent\u002F` 核心逻辑 -> `app\u002F` 具体实现，绝不反向\n- **接口先于实现** -- 每个模块先定义 ABC\u002FProtocol，再写具体类\n- **安全网内建而非外挂** -- 工具预算、API 重试、Hook 隔离、token 预算从第一行代码就在\n- **进化靠结晶而非训练** -- 成功任务自动提取工具序列 -> 质量评分 -> 持久化为可复用技能\n\n### 20 接口全景\n\n| 接口 | 职责 | 状态 |\n|------|------|------|\n| **ITool** | 工具注册 \u002F 并发安全 \u002F 结果预算 | V1 |\n| **IModelProvider** | 模型流式推理 (OpenAI 兼容 + Anthropic) | V1 |\n| **IMemoryBackend** | L0-L4 分层记忆, 关键词检索, jieba 分词 | V1 |\n| **IHook** | 22 事件链, 优先级排序, 异常隔离 | V1 |\n| **ISkill** \u002F **ISkillConfig** | 技能注册 \u002F YAML 加载 \u002F 关键词匹配 | V1 |\n| **IFlowInspector** | AsyncQueue 旁路, 滑动窗口统计 | V1 |\n| **ICapabilityCatalog** \u002F **ICapabilityRegistry** | Tier 渐进式披露, copy-on-read | V2 |\n| **IPluginAdapter** | 4 层发现 \u002F yaml manifest \u002F 热重载 | V2 |\n| **IPromptBuilder** | 片段式动态组装, token 预算 | V2 |\n| **IWebAutomation** | fetch + search + browser (httpx + Playwright) | V2 |\n| **IAgentRuntime** | spawn\u002Fspawn_parallel, 并发控制, Agent 通信 | V3 |\n| **IAutonomousMemory** | 检查点 + 结晶 + Nudge + 长期更新 | V3 |\n| **ISelfModification** | quality_score 三维评分 | V3 |\n| **IToolErrorPolicy** | 工具异常策略 | 预留 V2 |\n| **IHotLoader** | 运行时热加载 | 预留 V2 |\n| **IDiscovery** | 自动发现 | 预留 V2 |\n| **IMultiModelOrchestrator** | 多模型协同 | 预留 V3 |\n| **IPluginMarketplace** | 插件市场 | 预留 V3 |\n| **IMetaAgent** | 元 Agent 自优化 | 预留 V4 |\n\n### 15 内置工具\n\n| 工具 | 说明 | 图标 |\n|------|------|------|\n| read | 文件读取 | R |\n| write | 文件写入 | W |\n| edit | 文件编辑（字符串替换） | E |\n| bash | Shell 命令执行 | $ |\n| glob | 文件名模式搜索 | G |\n| grep | 文件内容搜索 | S |\n| web_fetch | HTTP 请求 | H |\n| web_search | 网页搜索 | Q |\n| web_browser_* | 浏览器自动化 (6 个子工具) | - |\n| delegate_task | 多 Agent 任务委托 | D |\n| agent_message | Agent 间通信 | M |\n| cross_agent_read | 跨 Agent 只读访问 | X |\n| memory_store | 记忆存储 | - |\n| memory_search | 记忆搜索 | - |\n| skill_lookup | 技能查找 | - |\n\n**支持任意 OpenAI 兼容模型**：DeepSeek \u002F 通义千问 \u002F 智谱 \u002F OpenAI \u002F Anthropic 都行。\n\n---\n\n## 快速开始\n\n### 1. 下载安装\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FYang1999code\u002Fcontrollable-agent.git\ncd controllable-agent\npip install -e .\n```\n\n> 需要 Python 3.12+，建议使用 conda 或 venv 隔离环境。\n\n### 2. 配置 API Key\n\n```bash\n# 复制配置模板\ncp app\u002Fconfig\u002Fagent.yaml.example app\u002Fconfig\u002Fagent.yaml\n```\n\n编辑 `app\u002Fconfig\u002Fagent.yaml`，填入你的 API Key：\n\n```yaml\nproviders:\n  default: openai_compat\n  openai_compat:\n    base_url: https:\u002F\u002Fapi.deepseek.com\u002Fv1    # 或其他 OpenAI 兼容 API\n    model: deepseek-chat\n    api_key_env: DEEPSEEK_API_KEY             # 从环境变量读取\n    # api_key: sk-xxx                         # 或直接填（不要提交到 git）\n```\n\n设置环境变量：\n\n```bash\n# Linux \u002F macOS\nexport DEEPSEEK_API_KEY=sk-your-key-here\n\n# Windows PowerShell\n$env:DEEPSEEK_API_KEY = \"sk-your-key-here\"\n\n# Windows CMD\nset DEEPSEEK_API_KEY=sk-your-key-here\n```\n\n> 支持 **DeepSeek \u002F 通义千问 \u002F 智谱 \u002F OpenAI \u002F Anthropic** 等任何 OpenAI 兼容模型。\n\n### 3. 启动\n\n```bash\npython -m app.cli\n```\n\n你会看到欢迎界面：\n\n```\n+==================================================+\n|  my-agent v0.1.0                                 |\n|  Empire Code -- 可控多智能体自迭代 Agent 框架     |\n+==================================================+\n\n  底层模型: deepseek-chat\n  可用工具: 15 个\n  \u002Fhelp | \u002Fflowchart | \u002Fexit | \u002F多智能体\n  运行中随时可输入补充信息\n```\n\n其他启动方式：\n\n```bash\n# 单次执行（非交互）\npython -m app.cli --one-shot \"你的问题\"\n\n# 指定模型\npython -m app.cli --model gpt-4o\n\n# 详细日志（调试用）\npython -m app.cli -v\n\n# 旧版简单 REPL\npython -m app.cli --legacy\n```\n\n### 4. 使用多智能体协作\n\n进入 TUI 后，输入 `\u002F多智能体` 启动多 Agent 模式：\n\n```\n> \u002F多智能体\n\n  === 多智能体协作模式 ===\n\n  已注册角色 (5):\n    [C] coordinator    协调者 — 多 Agent 调度、流程监控\n    [P] planner        规划者 — 任务分解、步骤规划\n    [X] coder          编码者 — 代码实现、文件操作\n    [R] reviewer       审查者 — 代码审查、测试验证\n    [M] memorizer      记忆者 — 经验总结、知识提取\n\n  请描述你要多智能体协作完成的任务：\n  任务> 写一个 Python 文本统计工具，统计字符数、词数、行数，并写测试\n```\n\n然后 5 个 Agent 自动分工：\n\n```\n  [Agents: ~planner -coordinator -coder -reviewer -memorizer]\n    > planner started (planner_001)\n    OK planner finished (2.3s)\n  [Agents: *planner ~coordinator ~coder ~reviewer ~memorizer]\n    > coordinator started (coordinator_001)\n    > coder started (coder_001)\n    ...\n```\n\n面板图标含义：`~` 运行中、`*` 已完成、`!` 出错、`-` 等待中。\n\n也可以让模型自动调用——在普通对话中描述复杂任务，模型会自行决定是否使用多 Agent。\n\n### 5. 记忆系统管理\n\nAgent 会自动从对话中提取记忆，存储在 `~\u002F.agent-memory\u002F` 目录下：\n\n```\n~\u002F.agent-memory\u002F\n├── digest\u002F           # 任务摘要（每次完成后自动提取）\n│   ├── d_001.md\n│   ├── d_002.md\n│   └── ...\n├── wiki\u002F             # 知识页面（同主题摘要自动合并）\n│   ├── python_stack.md\n│   └── ...\n├── domain\u002F           # 四域分类索引\n│   ├── conversational\u002F\n│   ├── personal\u002F\n│   ├── agent\u002F\n│   └── task\u002F\n└── index.md          # 倒排索引（关键词 → 摘要\u002F知识页）\n```\n\n**查看记忆内容**：直接用任何编辑器打开 Markdown 文件，人可读。\n\n```\n---\nid: d_001\nlevel: digest\ntags: [python, file-io]\ndomains: [conversational]\nconfidence: 0.85\n---\n\n## 实现了文本统计工具\n\n- 使用 collections.Counter 统计字符频率\n- 支持自定义编码检测\n- 写了 10 个 unittest 用例全部通过\n```\n\n**搜索记忆**：在对话中提问，Agent 会自动检索相关记忆。\n\n**记忆生命周期**：\n\n```\n对话完成 → 自动提取 digest（任务摘要）\n    ↓ 积累 5+ 个同主题 digest\n自动合并为 wiki（知识页面，更完整）\n    ↓ 下次遇到类似问题\n优先查 wiki → 查不到再查 digest → 都没有就不编造\n```\n\n### 6. 常用命令速查\n\n| 命令 | 说明 |\n|------|------|\n| `\u002Fhelp` | 显示所有命令 |\n| `\u002F多智能体` | 启动多 Agent 协作模式 |\n| `\u002Ftools` | 列出所有工具 |\n| `\u002Ftokens` | 查看 Token 使用统计 |\n| `\u002Fstatus` | 查看 Agent 运行状态 |\n| `\u002Fmodel` | 显示当前模型 |\n| `\u002Fflowchart` | 查看控制流程图 |\n| `\u002Fclear` | 清屏 |\n| `\u002Fexit` | 退出 |\n\n运行中随时可以直接打字输入补充信息，Agent 下一轮会看到。\n\n---\n\n## 终端体验\n\n实时终端 UI，对标 Claude Code \u002F OpenCode：\n\n| 功能 | 说明 |\n|------|------|\n| 流式输出 | 逐字显示，不再黑屏等半天 |\n| 思考状态 | `... 思考中 ...` 实时指示 |\n| 工具调用 | 彩色图标徽章 + 折叠预览，不再几十行乱码 |\n| 多 Agent 面板 | 实时显示子 Agent 运行状态 |\n| 上下文监控 | 状态栏显示模型名、turn 数、token、上下文占用% |\n| 斜杠命令 | \u002Fhelp \u002Ftools \u002Ftokens \u002Fstatus \u002Fclear \u002Fexit |\n\n---\n\n## 设计参考\n\n融合了 10 个开源 AI Agent 项目的设计精华：\n\n| 项目 | 借鉴了什么 |\n|------|-----------|\n| Claude Code | 双层循环、CLAUDE.md 层级、实时终端 UI |\n| Pi Agent | 子 Agent 进程隔离、类型系统 |\n| Hermes Agent | 线程池委托、多记忆后端 |\n| GenericAgent | L0-L4 记忆公理、技能结晶 |\n| oh-my-opencode | Hook 事件系统、Agent 角色系统 |\n| OpenCode | 终端 TUI、上下文压缩 |\n| everything-claude-code | 48 Agent + 183 Skill 生态设计 |\n| multica | 信号量并发控制 |\n| Synthius-Mem 论文 | 记忆提取 pipeline |\n| Karpathy Wiki 思想 | Wiki 式知识组织 |\n\n---\n\n## 实现进度\n\n### Phase 1 -- 基座 (已完成)\n- 双层 Agent 循环 (外层 followUp + 内层 tool_calls)\n- 6 个文件操作工具 (read\u002Fwrite\u002Fedit\u002Fbash\u002Fglob\u002Fgrep) + 流式并行执行\n- L0-L4 分层记忆 (文件系统后端, jieba 中文分词, bigram 回退)\n- 7 基础 Hook 事件 + 异常隔离\n- CLAUDE.md 层级发现\n\n### Phase 2 -- 扩展 (已完成)\n- 能力渐进式披露 (Tier 0 始终可见, Tier 1 按需)\n- 动态 Prompt 片段组装 (优先级 0-100, token 预算裁剪)\n- 插件系统 (4 层发现: 内置->用户->项目->pip)\n- Web 工具 (fetch + search + browser navigate\u002Fclick\u002Ftype\u002Fsnapshot)\n- Digest + Wiki 记忆存储引擎 + 倒排索引检索 (DomainIndex)\n- LLM 记忆提取引擎 (自动从对话提取 digest\u002Fwiki)\n- 三层上下文压缩 (Prune -> Summary -> Emergency Truncation)\n\n### Phase 3 -- 多 Agent + 自进化 (已完成)\n- 5 角色协作 (Coordinator \u002F Planner \u002F Coder \u002F Reviewer \u002F Memorizer)\n- 隔离存储 (每个 Agent 独立的 MemoryStore + FactStore + DomainIndex)\n- 共享区 (plan.md \u002F status\u002F \u002F decisions.md \u002F issues.md \u002F skills\u002F)\n- 跨 Agent 读取 (CrossAgentReadTool + 路径白名单 + 安全校验)\n- 编排引擎 (orchestrate() 分阶段串并行 + 打回机制)\n- Agent 自动选择 (Overlap Coefficient 匹配 + 中文分词)\n- Agent 间通信 (asyncio.Queue 收件箱)\n- 技能结晶 (成功任务 -> quality_score 评估 -> 持久化 YAML)\n- Nudge 提醒 (每 10 轮自动提醒使用记忆\u002F技能)\n\n### Phase 3.5 -- 终端可视化 (已完成)\n- 流式 Hook 事件驱动实时渲染\n- 逐字流式文本显示\n- 工具调用彩色图标徽章 + 折叠输出\n- 多 Agent 状态面板\n- 上下文占用% 实时计算 + 压缩通知\n\n---\n\n## 安全网\n\n- 工具异常不中断循环 (ToolResult(success=False) -> LLM 自行处理)\n- API 重试 (指数退避, max 3 次)\n- Hook 异常隔离 (单 handler 失败不影响其他)\n- Prompt token 预算 (低优先级片段优先裁剪)\n- 工具结果预算 (50K 字符截断)\n- 子 Agent 超时 + 深度限制 (max_depth=2)\n- 跨 Agent 读取路径白名单 + `..` 穿越防护\n- API Key 不入库 (agent.yaml 在 .gitignore 中)\n\n---\n\n## 测试\n\n```bash\npytest tests\u002F -v\n# 449 tests, 0 failures\n```\n\n---\n\n## 文档\n\n| 文档 | 内容 |\n|------|------|\n| [多智能体设计.md](多智能体设计.md) | Phase 3 多 Agent 系统完整设计 |\n| [我的记忆改进.md](我的记忆改进.md) | Wiki 式记忆系统设计 |\n| [多智能实现记录.md](多智能实现记录.md) | Phase 3 实现过程 (449 tests) |\n| [可视化.md](可视化.md) | 终端 UI 设计文档 |\n| [架构总结.md](架构总结.md) | 三层架构分析 |\n\n---\n\n## License\n\nMIT\n","Controllable Agent 是一个能够自我组织、记忆和进化的 AI 代理框架，采用三层架构设计，支持多代理协作。其核心功能包括五个角色的分工合作（Planner、Coder、Reviewer、Coordinator 和 Memorizer），以及Wiki式的记忆系统，确保任务执行过程中的高效沟通与知识积累。该框架特别适合处理复杂且需要多步骤完成的任务场景，如软件开发中的模块构建等。通过并行处理和实时反馈机制，提高了任务完成的质量和速度。项目使用Python语言编写，具有良好的扩展性和可维护性。",2,"2026-06-11 03:31:18","CREATED_QUERY"]