Skip to content

appendix.md

Latest commit

 

History

History
207 lines (155 loc) · 5.52 KB

appendix.md

File metadata and controls

207 lines (155 loc) · 5.52 KB

附录：概念速查与决策清单

A. 关键概念速查

Agent 循环

概念 含义
AgentStreamEvent Agent 向外发射的事件类型（文字/工具/完成/错误）
QueryOptions 启动一次 Agent 会话的配置项
AbortSignal 取消正在执行的 Agent 循环
querySource 标记 LLM 调用的来源（main/compact/memory 等）

工具系统

概念 含义
isReadOnly 工具不修改任何状态
isDestructive 工具有不可逆的副作用（删除、发送）
isConcurrencySafe 工具可以与其他工具并行执行
ToolContext 工具执行时的依赖注入上下文
maxResultSizeChars 工具输出大小上限，超出写文件

上下文管理

概念 含义
Snip 删除早期工具调用对（最轻量压缩）
MicroCompact 替换重复调用为说明（无 API 成本）
Collapse LLM 摘要 + 保留最近消息（中等成本）
AutoCompact 全量 LLM 压缩为 9 节结构（最重量级）

记忆系统

层 存储位置 适合什么
M1 在线上下文 内存 当前会话状态
M2 项目记忆 ALICE.md 文件 项目约定和规则
M3 向量记忆 向量数据库 语义相关的历史
M4 结构化存储 SQLite 会话历史和设置
M5 用户画像 identity/workflow/voice.md 长期用户偏好

权限系统

模式 含义
plan 只规划，不执行
default 危险操作弹窗确认
accept_edits 文件编辑自动接受
dont_ask AI 分类器自动判断
bypass_permissions 完全绕过，适合 CI

多 Agent

模式 适合场景
父子（Subagent） 主任务中动态分叉子任务
Coordinator 明确的并行工作流，需要综合
Swarm 大量独立同质任务，去中心化

B. 架构决策清单

在开始设计一个新功能前，逐项确认：

B1. 状态管理

  • 这个功能涉及哪些状态？
  • 这些状态的生命周期是什么（会话级/项目级/永久）？
  • 状态住在哪里（内存/文件/数据库/向量库）？
  • 谁能读这个状态？谁能写？
  • 并发读写时是否安全？

B2. 工具 vs 服务

  • "如果 AI 主动触发这个功能，是用户期望的行为吗？"
    • 是 → 做成工具
    • 否 → 做成服务，不暴露给 AI

B3. 工具设计检查

  • 名称唯一且有意义
  • description 包含四要素（是什么/何时用/何时不用/返回什么）
  • isReadOnly 正确标注
  • isConcurrencySafe 正确标注（不确定时默认 false）
  • isDestructive 正确标注
  • 大结果是否有大小限制？超出时是否写文件？
  • 子 Agent 是否应该能使用这个工具？

B4. 并发安全

  • 多个实例同时写同一个资源时，是否有冲突？
  • 读写操作是否分离（读并行，写串行或加锁）？
  • 定时任务/阈值触发机制是否有防递归守卫？

B5. 降级路径

  • 这个组件挂掉，系统是否崩溃？
  • 如果只是降质（不崩溃），降质的表现是什么？
  • 是否显式实现了降级 fallback？

B6. 可观测性

  • 关键操作是否有结构化日志？
  • 决策是否携带 reason？
  • 如果出了问题，现有日志能否帮助定位原因？

C. 权限规则配置示例

permissions:
  # 工作目录下的文件操作自动放行
  - action: allow
    tool: file_write
    pathPattern: "~/Projects/**"

  # 禁止强制推送
  - action: deny
    tool: bash
    pattern: "git push --force"

  # npm 安装需要确认
  - action: ask
    tool: bash
    pattern: "npm install"

  # 允许 wpsnote 相关的所有 MCP 工具
  - action: allow
    tool: "mcp_wpsnote_*"

D. 系统提示分层模板

[PROTECTED]
（核心身份和行为底线，永不修改）
[/PROTECTED]

[MUTABLE]
（可随使用情况演进的行为偏好）
[/MUTABLE]

---
工具使用最佳实践
...

---
项目记忆（ALICE.md 内容）
...

---
用户画像
...

---
当前激活的 Skills
...

---
[动态追加，每轮迭代更新]
当前时间：...
本次会话拒绝记录：...

E. 多 Agent 场景选型

需要任务并行吗？
    否 → 单 Agent
    是 ↓

任务之间有数据依赖吗？
    否，完全独立 → Swarm（去中心化任务队列）
    是，有依赖关系 ↓

需要综合多个子任务结果吗？
    否，结果独立使用 → 父子模式（fire and forget）
    是，需要综合 → Coordinator 模式

F. 本书十二个范式速查

# 范式名称 核心原则
1 声明式契约 能力单元带元数据，让框架自动决策
2 事件流边界 核心逻辑和消费层用事件流解耦
3 分层压缩 廉价策略先行，贵的策略后触发
4 互斥守卫 被动触发机制必须有防递归保护
5 最小权限 精确到操作粒度，每次决策带原因
6 懒加载 只在真正需要时才建立连接/加载
7 可撤销操作 执行前快照，提供撤销能力
8 细化可观测 记录"谁触发的"，而非只记"发生了"
9 读写分离 读并行，写串行，默认保守
10 分层记忆 生命周期不同的信息住在不同的存储层
11 接口稳定 确定接口，不断迭代实现
12 防呆设计 检测和纠正偏差，不依赖 AI 的正确性