# AI CLI 工程架构与迭代策略参考 ## 1. 渐进式开发阶段模型 ``` V1 → 跑通核心流程 + 类型检查通过 V2 → 工程化配套设施 V3 → 多层级解耦（模块独立优化） V4 → 大量的测试文件 → 稳定性 ``` ### 决策框架 | 阶段 | 验证目标 | 成功标准 | |------|----------|----------| | V1 | 核心假设可行 | 功能跑通，类型安全 | | V2 | 可维护性 | 配套工具齐全 | | V3 | 可扩展性 | 模块解耦清晰 | | V4 | 可靠性 | 测试覆盖充分 | --- ## 2. 产品定位：Agent Runtime Platform ### 核心认知 > Claude Code 的本质不是 Chat CLI，而是 **Agent Operating System (Runtime Platform)** ### 两种商业模式的差异 | 维度 | Chat CLI | Runtime Platform | |------|----------|-------------------| | **定位** | 对话工具 | 能力平台 | | **商业模型** | 消耗品（按token） | 基础设施（按授权） | | **壁垒来源** | 模型能力 | 生态+工作流 | | **扩展方式** | 功能堆叠 | 插件体系 | | **天花板** | token成本递减 | 平台网络效应 | **平台定位 = 商业模式选择** --- ## 3. 上下文构建层（值得重点学） ### 为什么重要 > "很多 agent 产品失败，不是模型差，而是：没有项目现场感、不知道当前分支、不知道工作区脏不脏" 上下文构建的本质：**减少模型幻觉，而不是给更多信息** ### 上下文分类 ``` ┌─────────────────────────────────────┐ │ 系统上下文（固定） │ │ - 平台信息、环境变量 │ │ - 当前时间、时区 │ └─────────────────────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ 工作区上下文（动态） │ │ - git status / branch / commits │ │ - CLAUDE.md / .claudeignore │ │ - 工作区脏状态 │ └─────────────────────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ 任务上下文（会话级） │ │ - 对话历史（已压缩） │ │ - 已执行工具链 │ │ - 当前任务目标 │ └─────────────────────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ 用户上下文（持久） │ │ - 用户偏好设置 │ │ - 认证信息 │ │ - 历史记忆/memory │ └─────────────────────────────────────┘ ``` ### 关键设计原则 **注入环境事实，而不是让模型猜测：** - ✅ 结构化注入当前分支名 - ❌ 让模型自己问"我现在在哪个分支" --- ## 4. QueryEngine + QueryLoop 分层（很值得学） ### 为什么分层是关键 很多 agent 系统写成"巨大的 ask()"，里面全塞： - prompt 拼接 - API 调用 - tool run - streaming - retry - compact - usage - session persistence **结果：后面必炸。** ### 正确分层 ``` ┌─────────────────────────────────────────┐ │ QueryEngine（会话引擎） │ │ - 管会话生命周期 │ │ - 管消息状态 │ │ - 管 usage │ │ - 管 permission denials │ │ - 管 submitMessage 的整体 turn │ └─────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────┐ │ query loop（回合推进器） │ │ - 循环执行：model → tool → model │ │ - 处理 compact │ │ - 处理 recover │ │ - 追踪 token │ └─────────────────────────────────────────┘ ``` **产品级结构 vs demo 级结构** | Demo级 | 产品级 | |--------|--------| | 一个巨大的 runAgent() | 状态管理层 + 回合推进层 | | 所有逻辑混在一起 | 模块边界清晰 | | 不可测试 | 各层独立可测 | | 无法恢复 | Checkpoint 支持 | --- ## 5. 工具系统：注册表化 + 条件启用（值得学） ### 核心原则 > "工具不是越多越好，而是要在当前上下文里'受控暴露'" ### 暴露控制矩阵 | 维度 | 控制方式 | |------|----------| | 功能存在性 | 基础注册 vs Feature Flag | | 环境启用 | 环境变量检测 | | 平台差异 | Windows/Linux/macOS 条件 | | 权限模式 | manual/plan/auto/yolo 过滤 | | 上下文 | 当前会话状态判断 | ### 工具暴露是任务阶段的函数 同样一个节点上下文： - 用户问"分析问题" → 暴露：诊断工具 - 用户问"帮我恢复" → 暴露：恢复工具 + 白名单 - 用户问"为什么崩了" → 暴露：日志工具 + 指标工具 **工具暴露是动态的，由任务阶段决定，不是静态权限矩阵。** --- ## 6. 权限系统：结构性兜底（原则必须坚持） ### 核心原则 > "安全边界不能靠模型自觉，必须落在产品结构上" ### 必须落在结构上的内容 ``` - 工具白名单 - 路径白名单 - 命令模板白名单 - 节点级权限 - 审批前后状态切换 - 危险动作双确认 ``` ### 信任链 > 权限链 | 维度 | 回答 | 用途 | |------|------|------| | 权限 | "能做什么" | 控制执行 | | 信任链 | "谁授权了这条链路" | 责任认定 | ``` 用户 → Session → Agent → 节点 ↑ 谁授权了这条链路？ ``` **没有信任链，出了事故无法追责。** --- ## 7. 长任务能力（一等公民） ### 核心认知 > "真正能跑长任务的 agent，瓶颈不是第一轮回答，而是第 20 轮以后怎么不崩" ### 必须提前考虑的问题 ``` - token budget - compact（压缩） - checkpoint（检查点） - replay（回放） - recover（恢复） - timeout（超时） - cancellation（取消） - partial result（部分结果） - background continuation（后台继续） ``` ### 长任务 = 主战场，不是边角料 未来不管是： - 健康检查 - 批量恢复 - 节点巡检 - 多步骤排障 都不该假设"这一轮就结束"。 --- ## 8. 中断/恢复/回放（原生支持） ### 核心认知 > "任何真实工作流都会中断。中断不是异常，而是正常状态。" ### 产品必须支持的状态 ``` - 运行中 - 等待审批 - 部分完成 - 已中断 - 可恢复 - 已回放 - 失败 - 成功 ``` ### 最低限度 不能只有： - ✅ 成功 - ❌ 失败 至少要有： - 🟡 运行中 - 🟡 等待审批 - 🟡 部分完成 - 🟡 可恢复 --- ## 9. 压缩机制（能力，不是补丁） ### 压缩策略分级 | 压缩类型 | 触发条件 | 方式 | |----------|----------|------| | micro-compact | 单次过长回复 | 摘要中间步骤 | | auto-compact | token 超阈值 | 选择性保留 | | reactive-compact | 模型主动请求 | 动态判断 | | api-compact | API 限制 | prompt 重构 | ### 平台任务的压缩设计 ``` 原始日志 → 结构化摘要 → 关键异常摘录 → 操作轨迹摘要 → 当前建议状态 ``` 这样 agent 能继续工作，用户也能读得懂。 --- ## 10. Feature Flag 设计（克制原则） ### 正确原则 - ✅ 提前为未来铺路 - ✅ 把产品路线图编码进结构 - ✅ 未完成功能先封好边界 ### 风险警示 - ❌ flag 太多会变成"架构迷宫" - ❌ 行为不可预测 - ❌ 开发者不知道"当前启用了什么" ### 推荐分层 | 层级 | 类型 | 默认 | |------|------|------| | 平台级稳定能力 | 常开 | 开 | | 实验能力 | 明确标实验 | 关 | | 高风险能力 | 审批/配置开启 | 关 | ### Flag 退出条件模板 ```typescript { name: 'NEW_FEATURE', status: 'beta', owner: 'team-xxx', exitConditions: { stable: 'NPS >= 30 且 bug率 < 1%', deprecated: '6个月内未达标则移除' } } ``` --- ## 11. 模块化扩展（不揉主系统） ### 核心原则 > "核心 runtime 要轻，扩展能力要外插" ### 避免 ``` ❌ 浏览器、远程、工作流、插件、MCP、语音、多agent 全揉进主系统 后果： - 理解成本爆炸 - 测试矩阵爆炸 - 风险边界不清 - 迭代速度变慢 ``` ### 正确做法 ``` ✅ 核心 runtime 轻 ✅ 扩展能力外插 ✅ 远程控制单独模块 ✅ workflow 单独模块 ✅ browser/node/recovery 各自解耦 ``` --- ## 12. 命令体系（服务高频，不服务炫技） ### 核心原则 > "一个 agent CLI 的核心不是命令多，而是：高频任务顺不顺、认知负担低不低" ### 应该优先的 | 优先级 | 命令类型 | 示例 | |--------|----------|------| | P0 | 查看状态 | /status, /health | | P0 | 定位异常 | /diagnose, /find | | P0 | 触发诊断 | /check, /scan | | P0 | 执行恢复 | /recover, /fix | | P1 | 查看历史 | /history, /logs | | P1 | 回放结果 | /replay, /trace | | P2 | 升级审批 | /escalate, /approve | | P3 | 调试命令 | /heapdump, /doctor | ### 避免"命令海洋" ``` ❌ 不好：80+ 命令，用户不知道用哪个 ✅ 好： - 高频 5-10 个：始终可见 - 中频按场景：branch 时出现相关 - 低频隐藏：/help 里折叠 ``` --- ## 13. 审计与追责（一等公民） ### 核心认知 > "能执行动作的 agent，如果没有审计链路，就不配进生产" ### 必须记录 ``` - 谁触发 - 为什么触发 - 用了什么上下文 - 调了什么工具 - 执行了什么动作 - 结果如何 - 是否人工审批 - 是否自动恢复 - 是否重试 - 是否造成副作用 ``` ### 操作页 = 执行证据页 不是"显示结果页"，而是： - 触发链路可追溯 - 上下文可回溯 - 决策可解释 --- ## 14. 可观测性（从 V1 开始） ### 核心认知 > "Agent runtime 的决策过程对用户是黑盒，一旦欠下技术债，很难还" ### 从 V1 开始每个 action 必须有 ``` - 触发原因（用户指令 / 自动规则 / 定时） - 用了什么上下文 - 产生了什么决策 ``` ### 出问题时 - 用户要知道"它做了什么" - 老板要知道"为什么这么操作" - 合规审计要知道"谁能解释这一步" **可观测性是技术债，一旦欠下还款成本极高。** --- ## 15. 状态机思维（不是页面集合） ### 核心认知 > "成熟产品不是页面拼图，而是状态流转系统" ### 任务状态机示例 ``` draft → queued → running → awaiting_approval → blocked ↓ ↓ partial_success ←────→ failed ↓ completed ↓ archived ``` ### 页面 vs 状态 | 思维 | 说明 | |------|------| | 页面集合 | 堆页面功能，按钮罗列 | | 状态机 | 先定义状态，再定义流转，再设计页面 | --- ## 16. V1 闭环（不做宇宙） ### 核心认知 > "没有闭环前，其他功能只是装饰" ### V1 闭环必须验证"用户真用" | 验证项 | 问题 | |--------|------| | 闭环能跑通 | ✅ 功能层面 | | 用户真的用 | ❌ 可能是伪需求 | | 用户信任结果 | ❌ 可能不敢用 | | 用户愿意付费 | ❌ 可能只是免费用 | ### V1 闭环示例（运维平台） ``` 发现异常 ↓ 解释异常（上下文注入） ↓ 提供建议（白名单动作） ↓ 审批后执行 ↓ 记录结果 ↓ 保留审计 ``` --- ## 17. 真正的智能（来自约束清晰） ### 核心认知 > "功能越多 = agent 越智能" 是误区 ### 让 agent 变强的是 ``` - 边界更清晰 - 上下文更准确 - 工具更干净 - 状态更明确 - 权限更可控 - 恢复更稳定 ``` ### 约束 = 能力 不是"给 agent 更多自由"，而是： - "在什么边界内行动" - "用什么工具箱" - "达到什么目标" --- ## 18. 架构检查清单 ### 新功能接入 - [ ] 确定功能状态：`✅`/`⚠️`/`❌` - [ ] 是否需要 Feature Flag 控制 - [ ] 是否需要 Hook 扩展点 - [ ] 平台兼容性检查 - [ ] 上下文需要哪些层？ - [ ] 工具暴露是动态还是静态？ ### 架构评审 - [ ] 分层是否清晰（状态 vs 推进）？ - [ ] 工具暴露是否受任务阶段控制？ - [ ] 错误恢复是否考虑？ - [ ] 压缩边界是否定义？ - [ ] Flag 是否有 owner 和退出条件？ - [ ] 信任链是否设计？ - [ ] 可观测性是否覆盖？ ### 发布前检查 - [ ] 所有 `✅` 功能测试通过 - [ ] `⚠️` 功能有条件说明 - [ ] 类型检查全部通过 - [ ] 文档与代码同步 - [ ] 暴露的命令是否真的有产品价值？ - [ ] 状态机是否完整？ - [ ] 审计链路是否完整？