@haaaiawd/loom 0.7.0 → 0.8.0

package/dimensions/PART_DECOMPOSITION.md

@@ -0,0 +1,203 @@
+# 实现部分拆解方法论
+
+> 这份文档给 Agent 一套拆解方法，让它自己识别"这个项目由哪些实现部分组成"，
+> 然后对每个部分走搜索漏斗，织造该部分的哲学约束。
+>
+> 项目千变万化，预填维度文件覆盖不了所有情况。方法不会过时，清单会。
+
+---
+
+## 核心思路
+
+传统维度库靠预填——CLI 工具该有哪些维度、Agent 系统该有哪些维度、Web 前端该有哪些维度，全部写死在文件里。这样有三个问题：
+
+1. 项目类型太多，预填永远追不上
+2. 新项目类型出现时，维度库来不及更新
+3. 预设的"UX 哲学"对 CLI 工具没意义，预设的"CLI 美学"对 Agent 系统也没意义——错配
+
+LOOM 换了个方向：预设"怎么拆部分"，不预设"有哪些部分"。Agent 拿到项目特征后，自己拆解出实现部分，每个部分独立织造哲学。
+
+---
+
+## 拆解流程
+
+### Step 1：识别项目类型
+
+先判断项目属于哪个大类。判断结果用来确定拆解的起点，不用来查预设清单。
+
+常见类型（非穷举——Agent 自行判断）：
+
+| 类型 | 特征 | 用户接触面 |
+|---|---|---|
+| CLI 工具 | 命令行交互，输入→输出 | 终端输出、参数、退出码 |
+| Agent 系统 | 自主决策，工具调用 | 对话、工具调用结果、状态反馈 |
+| Web 前端 | 浏览器渲染，用户交互 | 页面、交互、视觉 |
+| 后端服务 | API 驱动，多客户端 | API 响应、错误码、文档 |
+| 游戏引擎 | 实时渲染，物理模拟 | 画面、操作反馈、性能 |
+| 嵌入式系统 | 资源受限，硬件交互 | 设备行为、指示灯、串口 |
+| 数据管道 | ETL/流处理，数据变换 | 数据质量、吞吐量、延迟 |
+| 混合型 | 以上多种组合 | 按子系统拆分，各走各的类型 |
+
+**判断方法**：看项目的用户接触面和核心交互方式。如果项目跨多个类型（如 Agent 系统 + Web 前端），按子系统分别判断。
+
+**用户提到的特殊类型**：上面这张表只列了常见类型。用户可能提出表里没有的系统——编译器、数据库、操作系统内核、游戏引擎、实时渲染管线、分布式共识系统、密码学库、嵌入式固件、区块链协议、消息队列、时序数据库……遇到表里没有的类型，按 Step 2 的三个问题自己拆，不要硬套。`examples/` 目录下有参考案例的才几个，没参考案例的类型更要认真走搜索漏斗——这类系统的实践知识往往在论文、标准文档、源码注释里，不在博客里。
+
+### Step 2：拆解实现部分
+
+对项目类型，问三个问题，每个答案是一个"实现部分"：
+
+**问题 A：用户接触面是什么？**
+- CLI 工具 → 终端输出、参数解析、帮助信息、错误呈现
+- Agent 系统 → 对话格式、工具调用展示、状态反馈、进度提示
+- Web 前端 → 页面布局、交互反馈、视觉风格、动效
+
+**问题 B：内部由哪些子系统组成？**
+- CLI 工具 → 转换引擎、文件 IO、配置管理（如果有）
+- Agent 系统 → 编排器、工具调度、上下文管理、提示词构造、验证器
+- Web 前端 → 路由、状态管理、组件层、数据获取、样式系统
+
+**问题 C：每个子系统的职责边界在哪？**
+- 问的是"每个模块该怎么做、什么标准"——"有哪些模块"是架构的事，不是哲学的事
+- 职责边界 = 这个部分"做什么"和"不做什么"的划分
+
+**拆解原则**：
+1. **按职责拆，不按文件拆**——"CLI 输出美学"是一个部分，"cli.js 这个文件"不是
+2. **粒度适中**——太粗（"整个 CLI"）没有约束力，太细（"每个函数"）变成架构了
+3. **每个部分能独立回答"该怎么做"**——如果一个部分的"怎么做"完全依赖另一个部分，合并它们
+4. **用户接触面优先**——用户能看到、能感知的部分，哲学约束最重要
+
+### Step 3：对每个部分走搜索漏斗
+
+每个识别出的实现部分，独立走"搜索 → 萃取 → 转译 → 落地"漏斗（见 PHILOSOPHY_WEAVER.md "织造漏斗"章节）。
+
+搜索时问的问题要具体：**"这个部分该怎么做、什么标准、有什么好实践"**。别问"这个领域的哲学是什么"——实践领域的知识很少叫"哲学"。
+
+例如对 CLI 工具的"帮助信息"部分：
+- 搜 "CLI help text design best practices"
+- 搜 "ripgrep --help output design"
+- 搜 "clap help formatting conventions"
+- 搜 "POSIX utility argument syntax conventions"
+- 从结果中萃取：帮助信息的结构、示例的放法、链接的放法、退出码的说明
+
+### Step 4：产出部分哲学文档
+
+每个实现部分产出一个哲学文档（或融入通用层文档的对应章节）。文档必须包含：
+
+1. **部分北极星**：这个部分的判断基准——"遇到冲突时，拿这句话量一下"
+2. **该做什么**：可执行原则，不是口号
+3. **不该做什么**：反模式清单，每条有"为什么"
+4. **参考实践**：至少 2 个真实工具/系统是怎么做这个部分的（要一手实践——源码、文档、工程博客，不要 Wikipedia）
+5. **灵感来源**：满足 LOOM 的源多样性校验
+
+---
+
+## 拆解示例
+
+### 示例 1：CLI 工具（md2html）
+
+```
+项目类型：CLI 工具
+用户接触面：终端
+
+拆解出的实现部分：
+├── CLI 交互设计 — 参数解析、--help、--version、用法提示
+├── CLI 输出美学 — 成功反馈格式、颜色策略、Rule of Silence 的正确理解
+├── CLI 错误呈现 — 错误结构、修复建议、退出码语义
+├── 转换引擎 — 纯函数、子集策略、透传 vs 报错
+└── 产物设计 — HTML 结构、CSS 内联、可预测性
+```
+
+每个部分独立搜索：
+- CLI 交互设计 → 搜 POSIX 参数约定、clap/cobra 设计、ripgrep/fd 的 --help
+- CLI 输出美学 → 搜 "CLI output design color"、bat/exa 的输出风格、Unix Rule of Silence 原文
+- CLI 错误呈现 → 搜 "CLI error message design"、Rust 的 error message 传统、Go 的 error-as-value
+- 转换引擎 → 搜 Markdown 解析策略、纯函数设计、子集 vs 全集
+- 产物设计 → 搜 "self-contained HTML"、CSS 内联策略、可预测输出
+
+### 示例 2：Agent 系统
+
+```
+项目类型：Agent 系统
+用户接触面：对话 + 工具调用结果
+
+拆解出的实现部分：
+├── 系统架构 — 编排 vs 控制、进程边界、IPC 机制
+├── 工具调用哲学 — 委托边界、失控收回、工具描述怎么写
+├── 上下文压缩 — 什么时候压缩、压缩什么、保留什么
+├── 提示词工程 — 角色激活、约束注入、上下文窗口管理
+├── 验证哲学 — 怎么信、怎么验、自动化 vs 人类
+└── 失败与恢复 — 崩溃恢复、状态一致性、回滚策略
+```
+
+每个部分独立搜索：
+- 系统架构 → 搜 "agent orchestration architecture"、LangChain/AutoGPT/CrewAI 架构设计
+- 工具调用 → 搜 "tool calling philosophy"、OpenAI function calling 设计、MCP 协议
+- 上下文压缩 → 搜 "LLM context window management"、conversation summarization 策略
+- 提示词工程 → 搜 "prompt engineering philosophy"、system prompt 设计、role activation
+- 验证哲学 → 搜 "AI agent verification"、human-in-the-loop 设计、automated verification
+- 失败与恢复 → 搜 "agent failure recovery"、state management、checkpoint 设计
+
+### 示例 3：Web 前端
+
+```
+项目类型：Web 前端
+用户接触面：浏览器
+
+拆解出的实现部分：
+├── 视觉设计哲学 — 排版、色彩、留白、层次
+├── 交互反馈哲学 — 加载状态、错误提示、成功反馈、动效
+├── 数据获取哲学 — 缓存策略、乐观更新、错误重试、loading 边界
+├── 组件设计哲学 — 组件粒度、状态边界、复用策略
+└── 性能哲学 — 首屏速度、包体积、渲染策略
+```
+
+---
+
+## 拆解的元原则
+
+1. **不预设结果**——拆解出的部分由 Agent 根据项目特征判断，不是查表
+2. **用户接触面优先**——用户能看到的部分，哲学约束最重要
+3. **每个部分独立可搜索**——"CLI 输出美学"能独立搜到好实践，"整个 CLI 的哲学"太泛搜不到有用的
+4. **部分之间可以有依赖**——"CLI 错误呈现"依赖"CLI 交互设计"的参数约定，这是正常的
+5. **部分数量适中**——小项目 3-5 个部分，大项目 6-10 个，超过 10 个考虑合并
+6. **拆解结果要记录**——在哲学文档里显式列出"本项目拆解出哪些实现部分"，供 Architect 和 Forge 引用
+
+---
+
+## 与通用层的关系
+
+通用层（产品哲学 / 工程哲学 / 协作哲学）回答"**为什么**"——产品为什么存在、代码怎么写、团队怎么协作。
+
+实现部分层回答"**怎么做**"——CLI 的帮助信息怎么做、Agent 的工具调用怎么做、前端的交互反馈怎么做。
+
+两层正交，缺一不可：
+- 通用层是地基。没有产品哲学，实现部分的哲学就没有判断基准
+- 实现部分层是落地。没有部分哲学，通用层就飘在空中，Forge 实现时不知道该对照什么
+
+---
+
+## 与 Architect 的接口
+
+Weaver 拆解出的实现部分，是 Architect 设计架构的输入：
+
+1. Weaver 产出"实现部分清单"（在哲学文档里显式列出）
+2. Architect 读这个清单，为每个部分设计对应的模块/子系统
+3. 每个模块的接口设计，对照该部分的哲学约束
+4. Forge 实现某个模块时，引用该部分的哲学文档作为约束
+
+从哲学到架构到实现，每个环节都有约束传递链。
+
+---
+
+## 搜索时的关键提醒
+
+对每个实现部分搜索时，别只搜"哲学"——实践领域的知识很少叫"哲学"，但就是哲学：
+
+- 搜 "best practices"
+- 搜 "design conventions"
+- 搜 具体工具名 + "design"（如 "ripgrep output design"）
+- 搜 具体库的文档（如 clap 的 README、cobra 的 design doc）
+- 搜 标准文档（如 POSIX、IEEE）
+- 搜 工程博客（如 Stripe engineering blog、Cloudflare blog）
+
+实践驱动的领域，知识在工具和标准里，在论文里的反而少。按 `SEARCH_METHODOLOGY.md` 的领域形态判断走对应路径。

package/dimensions/examples/AGENT_SYSTEM/README.md

@@ -0,0 +1,219 @@
+# 参考案例：Agent 系统
+
+> 这份文件提供搜索起点和好实践样本。Weaver 按 PART_DECOMPOSITION.md 自行拆解，
+> 拆解出的部分和这里不同时，以 Weaver 的拆解为准。
+
+---
+
+## Agent 系统通常拆解出的实现部分
+
+### 1. 系统架构
+**职责**：编排 vs 控制、进程边界、IPC 机制、状态管理、多 Agent 协调
+
+**该做什么**：
+- **编排而非控制**——设计可信赖的编排协议，把精力放在"哪些能力可以委托、边界在哪、失控时如何收回"这三个问题上，不要试图控制每一行执行
+- **区分 LLM 层和确定性层**——LLM 推理和可测试执行要分离（2389-research 的四层架构：reasoning / orchestration / tool bus / deterministic adapters）
+- **编排模式显式选择**：
+  - Sequential（流水线）：agent 链，前一个的输出是后一个的输入
+  - Concurrent（并行）：多 agent 同时处理同一任务，结果聚合（Fan-out/Fan-in）
+  - Handoff（交接）：triage agent 路由到 specialist，specialist 接管后续交互
+  - Agents-as-tools（工具化）：manager agent 调用 specialist 作为工具，自己保留最终回答权
+- **状态管理显式化**——agent 状态必须可序列化，非序列化状态破坏恢复能力
+- **IPC 机制要考虑进程边界**——子 agent 可能是独立进程，通信协议要显式（不是共享内存）
+
+**不该做什么**：
+- 不要让单个 agent 拿所有工具——工具过载导致选择质量下降（Microsoft Azure 架构指南）
+- 不要让 LLM 层直接做副作用——副作用必须在确定性层，带幂等键
+- 不要用共享可变状态做 agent 间通信——破坏可恢复性
+- 不要假设 agent 不会崩——长任务必须有 checkpoint
+
+**参考实践**：
+- **Azure Architecture Center — AI Agent Orchestration Patterns** — Sequential / Concurrent / Handoff / Agents-as-tools 四种编排模式 + 选择指南。https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/ai-agent-design-patterns
+- **OpenAI Agents SDK — Multi-Agent Orchestration** — Handoff vs Agents-as-tools 的选择标准、代码编排 vs LLM 编排。https://openai.github.io/openai-agents-python/multi_agent/
+- **Microsoft Multi-Agent Reference Architecture** — Orchestrator + Registry + Classifier + MCP Server 的完整参考架构。https://microsoft.github.io/multi-agent-reference-architecture/docs/reference-architecture/Reference-Architecture.html
+- **2389-research/building-multiagent-systems** — 四层架构 + 七种协调模式 + 生命周期管理（cascading stop / orphan detection / heartbeat）。https://github.com/2389-research/building-multiagent-systems
+- **"Control Plane as a Tool" (arXiv 2505.06817)** — 把控制平面暴露为单个工具接口，封装工具路由逻辑，解决规模化时的工具编排问题。https://arxiv.org/html/2505.06817
+
+**搜索起点**：
+- "agent orchestration architecture patterns"
+- "multi-agent coordination protocol"
+- "LLM agent system design four layer architecture"
+- "agent state machine workflow"
+
+---
+
+### 2. 工具调用哲学
+**职责**：委托边界、失控收回、工具描述怎么写、工具选择策略、按需加载
+
+**该做什么**：
+- **工具描述是给 LLM 看的契约**——schema 要清晰、类型要显式、副作用要声明
+- **按需加载工具定义**——不要把所有工具定义一次性塞进 context（MCP 的 code-execution 模式：agent 探索 filesystem 发现工具，按需加载，token 从 150K 降到 2K，节省 98.7%）
+- **人类在环作为安全网**——MCP 规范要求：工具调用 SHOULD 有人类在环，能拒绝调用（modelcontextprotocol.io §Tools）
+- **工具权限分级**——读操作自动批准，写操作需确认，不可逆操作需显式批准
+- **工具结果要过滤**——不要把原始 tool output 直接塞回 context，在执行环境里过滤后再返回模型
+
+**不该做什么**：
+- 不要给 agent 没有边界的工具——"能做什么"和"被允许做什么"是两件事
+- 不要让工具描述模糊——"处理文件"不行，"读取文件内容，参数：path，返回：string"才行
+- 不要把敏感工具和普通工具混在一起不加标记
+- 不要假设 LLM 会正确选择工具——工具越多选择质量越下降，要有工具数量上限或分域
+
+**参考实践**：
+- **MCP Specification — Tools** — JSON Schema 定义工具、`tools/list` 发现、`tools/call` 调用、人类在环要求。https://modelcontextprotocol.io/specification/2024-11-05/server/tools
+- **Anthropic — "Code execution with MCP"** — 把 MCP server 暴露为 code API 而非直接 tool call，agent 按需加载工具定义，token 节省 98.7%。https://www.anthropic.com/engineering/code-execution-with-mcp
+- **MCP Architecture Overview** — Tools / Resources / Prompts 三种 primitive，`*/list` 发现 + `*/get` 检索 + `tools/call` 执行。https://modelcontextprotocol.io/docs/learn/architecture
+- **2389-research — Schema-first tools** — typed contract 让 sub-agent 发现和验证工具 + permission inheritance + locking + rate limiting。https://github.com/2389-research/building-multiagent-systems
+
+**搜索起点**：
+- "MCP Model Context Protocol tool calling"
+- "agent tool description writing best practices"
+- "tool selection strategy LLM overload"
+- "agent tool permission boundary"
+
+---
+
+### 3. 上下文管理
+**职责**：上下文窗口管理、压缩策略、记忆持久化、信息保留优先级、预算感知
+
+**该做什么**：
+- **主动压缩 vs 被动保留**——agent 应该自主决定何时压缩，别等 context 满了才压缩（Focus Agent：模仿黏菌的探索-retract 策略，主动把关键学习固化到 Knowledge block，剪枝原始历史）
+- **压缩什么、保留什么要显式**——文件路径、API 参数、关键决策不能丢；中间错误、冗余输出可以压缩
+- **预算感知**——agent 要知道剩余 context headroom，据此决定压缩力度（ContextBudget：把压缩建模为预算约束的序列决策）
+- **语义无损压缩 > 截断**——SimpleMem 三阶段：语义结构化压缩 → 在线语义合成 → 意图感知检索规划，F1 提升 26.4%，token 降 30 倍
+- **区分短期 / 工作记忆 / 长期记忆**——不同记忆不同生命周期、不同检索策略
+
+**不该做什么**：
+- 不要被动保留全部历史——context bloat 导致成本爆炸、延迟增加、推理质量下降（"lost in the middle"）
+- 不要用固定规则压缩——"保留最近 N 轮"不够，信息相关性随任务进展动态变化（Acon：压缩指南优化，自然语言空间精炼 compressor prompt）
+- 不要压缩后丢失关键细节——一个文件路径丢了整个 workflow 就崩了（Acon 论文指出）
+- 不要把记忆和持久化执行混为一谈——session memory 不是 durable execution（Zylos Research）
+
+**参考实践**：
+- **Focus Agent (arXiv 2601.07190)** — agent-centric 主动压缩，模仿黏菌策略，6 次自主压缩/任务，token 节省 22.7%，精度不降。https://arxiv.org/html/2601.07190v1
+- **SimpleMem (arXiv 2601.02553)** — 语义无损压缩三阶段，F1 +26.4%，token -30x。https://arxiv.org/pdf/2601.02553
+- **ContextBudget (arXiv 2604.01664)** — 预算感知上下文管理，把压缩建模为预算约束序列决策。https://arxiv.org/pdf/2604.01664
+- **Acon (arXiv 2510.00615)** — Agent Context Optimization，自然语言空间优化压缩指南，model-agnostic。https://arxiv.org/html/2510.00615v3
+- **SUPO (ACL 2026)** — summarization-augmented policy optimization，RL 训练时同时优化工具使用和摘要策略。https://aclanthology.org/2026.acl-long.966/
+
+**搜索起点**：
+- "LLM context window management compression"
+- "agent memory architecture short term long term"
+- "context bloat agent performance degradation"
+- "what to keep what to compress agent context"
+
+---
+
+### 4. 提示词工程
+**职责**：角色激活、约束注入、系统提示词结构、上下文组装、角色边界
+
+**该做什么**：
+- **Role-Task-Constraints 三层结构**——系统提示词按这个顺序：Role（做什么类型的工作）→ Task（具体做什么）→ Constraints（不管什么任务都成立的不变式 + 禁忌）。缺任何一层都会 under-specify
+- **硬约束放最前和最后**——注意力在开头和结尾最强（attention anchoring），安全约束埋在第七段等于没有
+- **稳定 vs 可变分离**——稳定部分（role / 硬约束 / 行为风格）短而紧，可变部分（参考资料 / 示例 / 上下文）动态注入
+- **禁忌配正面替代**——LLM 对否定指令系统性表现更差（Truong et al. 2023，降 20-40 分），"不要编辑 vendor/" 要配 "vendor/ 的修改走 PR review 流程"
+- **约束作为可组合规则集**——核心 prompt 不变，约束按部署上下文动态注入（constraint injection pattern：scope + priority + content，运行时 resolver 合并）
+- **输出契约显式**——格式、长度、schema、要省略什么，都写清楚。被代码消费的输出要求 JSON against schema
+
+**不该做什么**：
+- 不要写长 preamble 再放关键指令——注意力衰减，关键约束掉进 attention shadow
+- 不要用 "be careful" 这种模糊约束——写成 concrete checkable rules："never run a statement that writes; refuse and explain"
+- 不要把 role 和 task 混在一起——role 定义"我是谁"，task 定义"现在做什么"
+- 不要假设 LLM 能从 context 推断 role 边界——role 边界要显式声明，否则 prompt injection 能越权
+
+**参考实践**：
+- **buecking/incontext — Role-Task-Constraints** — 系统提示词三层结构 + 禁忌配正面替代 + negation 性能下降证据。https://github.com/buecking/incontext/blob/main/docs/patterns/role-task-constraints.md
+- **contextpatterns.com — System Prompt Engineering** — Pyramid pattern（关键内容放最前）+ attention anchoring + 稳定/可变分离。https://contextpatterns.com/guides/system-prompt-engineering/
+- **llmbestpractices — System Prompt Design Patterns** — 命名块结构（role/capabilities/constraints/output/examples）+ 约束作为 explicit rules + 输出契约。https://llmbestpractices.com/prompt-engineering/system-prompt-design-patterns
+- **context-engineering-handbook — Constraint Injection** — 约束作为可组合规则集，运行时按部署上下文动态注入。https://github.com/ypollak2/context-engineering-handbook/blob/main/patterns/construction/constraint-injection.md
+- **LessWrong — "A Theory of Prompt Injection"** — role 边界失败机制 + role probes（CoTness / Userness）。https://www.lesswrong.com/posts/d8xDGzCEYE639qqEv/
+
+**搜索起点**：
+- "system prompt design patterns role task constraints"
+- "prompt engineering constraint injection dynamic"
+- "LLM negation performance drop negated instructions"
+- "prompt injection role boundary"
+
+---
+
+### 5. 验证哲学
+**职责**：怎么信、怎么验、自动化 vs 人类、验证维度设计、信任校准
+
+**该做什么**：
+- **验证嵌入执行循环，别做事后评估**——TrustBench：在 agent formulates action 之后、execution 之前做信任验证（pre-execution gate），事后打分来不及阻止错误
+- **信任分级 + capability gate**——skill manifest 带显式 verification level，HITL 只对 unverified 触发，verified 的自动放行（否则 HITL 退化为 rubber-stamping）
+- **双信号信任评分**——agent stated confidence（经 calibration curve 映射）+ 无 ground-truth 可计算的 metrics 子集，sub-200ms 出结果
+- **多维验证**——不只看功能正确性：correctness / informativeness / consistency（TrustBench）；reliability / grounding / attribution / policy-alignment（AEMA 统一框架）
+- **HITL 模式选择**：
+  - Workflow approval（durable，多步骤，可等数天）——用于合规/安全/高质量审查
+  - MCP elicitation（结构化用户输入）——用于工具执行中需要额外信息
+- **不可逆操作必须人类确认**——payments / deletions / external communications（Cloudflare HITL patterns）
+
+**不该做什么**：
+- 不要用 ROUGE 等 ground-truth overlap 指标评估 agent 推理质量——agentic task 没有确定性 reference（TrustBench 指出）
+- 不要让 HITL 对每个调用都触发——operationally untenable，degrades into rubber-stamping
+- 不要只做事后评估——reactive assessment 无法阻止执行中的错误
+- 不要混淆 capability 和 trustworthiness——能力强的不一定可靠
+
+**参考实践**：
+- **TrustBench (arXiv 2603.09157)** — 实时信任验证，pre-execution gate，双信号 sub-200ms 评分，dual-mode（benchmark + toolkit）。https://arxiv.org/abs/2603.09157v1
+- **Skills as Verifiable Artifacts (arXiv 2605.00424)** — trust schema + verification level + capability gate + biconditional correctness criterion。https://arxiv.org/html/2605.00424v1
+- **AEMA (arXiv 2601.11903)** — 多 agent 可验证评估框架，process-aware + auditable + human oversight。https://arxiv.org/pdf/2601.11903
+- **Unified Evaluation & Governance Framework** — ARS/RGC/ACR/PAAS 四指标 + 多层验证 + 治理审计层，hallucination -88%。https://doi.org/10.36227/techrxiv.176799772.28164151/v1
+- **Cloudflare Agents — Human-in-the-loop patterns** — Workflow approval vs MCP elicitation + timeout + audit trail。https://developers.cloudflare.com/agents/concepts/human-in-the-loop/
+
+**搜索起点**：
+- "AI agent verification trust benchmark"
+- "human-in-the-loop pattern agent approval"
+- "pre-execution verification agent safety"
+- "multi-dimensional agent evaluation"
+
+---
+
+### 6. 失败与恢复
+**职责**：崩溃恢复、状态一致性、回滚策略、降级方案、幂等性、熔断
+
+**该做什么**：
+- **每个副作用操作当事务边界**——record intent before execution → execute with idempotency wrapper → record durable receipt after success（Zylos Research）
+- **checkpoint + idempotent step 是恢复的基础**——checkpoint 让你从最后完成点恢复，idempotent 让你重试不产生重复副作用（AWS Well-Architected Agentic AI Lens）
+- **两种恢复方案选一种**：
+  - Deterministic replay（Temporal/Inngest 模式）：state = inputs + side-effect log，重放时跳过已 log 的副作用
+  - Checkpoint snapshot（LangGraph Cloud 模式）：周期性序列化 plan / working memory / partial outputs / pending tool calls
+- **idempotency key 传给每个副作用目标**——没有 idempotency key 的工具不能安全 resume（crash-between-effect-and-log 会产生重复）
+- **circuit breaker 防级联失败**——外部 API 连续失败 N 次后临时停止调用，避免浪费 latency 和 token（MightyBot）
+- **checkpoint 有 TTL + 显式清理**——不完成的 workflow 最终 aged out，完成的立即回收空间
+- **恢复后验证副作用是否真的完成了**——不要假设，查 idempotency key、查 API 状态
+
+**不该做什么**：
+- 不要假设 agent 不会崩——长任务一定会崩，问题是什么时候
+- 不要用 session memory 当 durable execution——chat history 不能证明哪个 shell 命令跑了、哪封邮件发了（Zylos Research）
+- 不要把恢复范围设得太大——"整个 pipeline 从头跑"浪费 token 和时间，scope 到最小可能单元
+- 不要在 interrupt 边界前放 mutating 操作——LangGraph 的 interrupt 后 code 可能重跑，approval boundary 要放对位置
+- 不要忽略 drifted external state——恢复后外部状态可能变了，要验证
+
+**参考实践**：
+- **Agent Resumption Pattern** — deterministic replay vs checkpoint snapshot + idempotency key。https://github.com/agentpatternscatalog/patterns/blob/main/patterns/agent-resumption.md
+- **AWS Well-Architected Agentic AI Lens — AGENTREL03-BP03** — checkpoint + idempotent step + TTL lifecycle。https://docs.aws.amazon.com/wellarchitected/latest/agentic-ai-lens/agentrel03-bp03.html
+- **MightyBot — Fault-Tolerant AI Agent Pipelines** — idempotency / checkpoint / state machine / circuit breaker / dead letter queue。https://mightybot.ai/blog/fault-tolerant-ai-agent-pipelines/
+- **Zylos Research — Durable Execution for AI Agent Runtimes** — execution journal + idempotent tool boundaries + versioned prompts + durable human approvals + recovery tests。https://zylos.ai/research/2026-04-24-durable-execution-agent-runtimes/
+- **LangGraph Persistence** — checkpointer 每 superstep 存 graph state，支持 memory / fault recovery / time travel / HITL。https://github.com/langchain-ai/langgraph
+
+**搜索起点**：
+- "agent failure recovery checkpoint pattern"
+- "durable execution AI agent runtime"
+- "idempotent agent operations side effect"
+- "circuit breaker pattern agent pipeline"
+
+---
+
+## 搜索时的关键提醒
+
+1. Agent 系统是实践驱动领域——知识在工程博客、开源项目、会议演讲里，传统学术论文里反而少。不过 arXiv 上 2025-2026 年的 agent 专项论文开始多了，值得关注
+2. 看真实系统的架构文档——LangChain / AutoGPT / CrewAI / OpenAI Agents SDK / Microsoft Multi-Agent Reference Architecture 的 README 和 design docs
+3. 关注失败案例——Agent 系统的哲学往往从"它怎么失败了"中提炼。issue tracker 和 postmortem 是金矿
+4. 区分 hype 和 practice——很多 Agent 框架的博客是营销文案，看代码和 issue tracker 才是真实状态
+5. 2025-2026 年的关键趋势：
+   - MCP 成为工具调用标准
+   - 主动上下文压缩取代被动保留
+   - pre-execution 验证取代事后评估
+   - durable execution + idempotency 成为生产级 agent 的硬要求
+   - constraint injection 取代静态 system prompt

package/dimensions/examples/CLI_TOOL/README.md

@@ -0,0 +1,163 @@
+# 参考案例：CLI 工具
+
+> 这份文件提供搜索起点和好实践样本。Weaver 按 PART_DECOMPOSITION.md 自行拆解，
+> 拆解出的部分和这里不同时，以 Weaver 的拆解为准。
+
+---
+
+## CLI 工具通常拆解出的实现部分
+
+### 1. CLI 交互设计
+**职责**：参数解析、--help、--version、用法提示、子命令组织
+
+**该做什么**：
+- 支持 `-h`/`--help` 和 `-V`/`--version`，这是 POSIX/GNU 强制要求（GNU Coding Standards §4.8）
+- 无参数运行时显示简洁帮助（clig.dev 原则：描述 + 1-2 个示例 + 常用 flag + 提示 `--help` 看更多）
+- `--help` 显示完整帮助：所有 flag、示例、链接到 web 文档
+- flag 用 dash-case（`--long-option`），短 flag 用单字母（`-h`），不要发明新语法
+- 输入文件用位置参数，输出文件用 `-o`/`--output`（GNU 约定）
+- `--` 表示参数结束，后续都当文件名（POSIX Guideline 10）
+- `-` 表示 stdin/stdout（POSIX Guideline 13）
+
+**不该做什么**：
+- 不要把 `--help` 当文件名处理（md2html 的真实 bug）
+- 不要用 camelCase 或 snake_case 命名 flag
+- 不要让 flag 顺序影响结果（除非显式声明互斥）
+- 不要重载 `-h` 做别的事
+
+**参考实践**：
+- **clig.dev** — Command Line Interface Guidelines，社区维护的 CLI 设计规范，覆盖 help/arguments/errors/output/documentation 全维度。https://clig.dev/
+- **POSIX Utility Conventions** — Guideline 1-13，CLI 参数语法的学术根基。https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
+- **GNU Coding Standards §4.8** — `--version`/`--help` 强制要求 + long-option 约定。https://www.gnu.org/prep/standards/html_node/Command_002dLine-Interfaces.html
+- **clap (Rust)** / **cobra (Go)** / **commander.js** — 主流参数解析库，看它们的默认 help 输出格式
+- **ripgrep --help** / **fd --help** / **bat --help** — 现代 CLI 工具的 help 文本样本，结构清晰、示例在前
+
+**搜索起点**：
+- "POSIX utility argument syntax conventions"
+- "GNU program argument syntax"
+- "clap help formatting conventions"
+- "CLI subcommand design patterns"
+
+---
+
+### 2. CLI 输出美学
+**职责**：成功反馈格式、颜色策略、表格/列表排版、Rule of Silence 的正确理解
+
+**该做什么**：
+- **Rule of Silence 的正确理解**：Eric Raymond 原文是 "When a program has nothing surprising to say, say nothing"——意思是"没意外时别废话"，不是"什么都不说"。转换成功对用户是有价值的信息（文件名、大小、位置），该说就说
+- 颜色策略遵循三约定（ripgrep/fd/bat 都遵守）：
+  - `NO_COLOR` 环境变量设了就禁用颜色（no-color.org，被 ripgrep/fd/bat/npm/cargo/gh/docker 等采纳）
+  - `--color auto`（默认）：TTY 时上色，管道时不上色
+  - `--color always`/`--color never`：强制开/关
+- 进度反馈：长任务显示进度条或 spinner，短任务静默
+- 输出结构：文件名在前，匹配内容在后（ripgrep 格式）
+- 表格输出用对齐排版，不用 ASCII art
+
+**不该做什么**：
+- 不要无脑上色——管道场景颜色码会污染下游工具
+- 不要把成功信息写到 stderr（clig.dev：stdout 是数据，stderr 是消息）
+- 不要输出时间戳/生成时间（破坏可预测性，违反 Unix 哲学）
+- 不要在成功时输出 "Done!" 之类废话——如果用户需要确认，输出有用的信息（文件名、行数、字节数）
+
+**参考实践**：
+- **ripgrep 输出设计** — `--color auto` + TTY 检测 + `--colors TYPE:STYLE:VALUE` 细粒度控制。https://github.com/BurntSushi/ripgrep
+- **bat 输出设计** — `--style` 组件化（numbers/changes/grid/header-filename 可组合），`--decorations=auto` TTY 检测。https://github.com/sharkdp/bat
+- **NO_COLOR 约定** — no-color.org，一个环境变量统一禁色，被整个生态采纳。https://no-color.org/
+- **Eric Raymond《The Art of Unix Programming》** — Rule of Silence 原文。https://www.catb.org/esr/writings/taoup/html/
+- **clig.dev "Output" 章节** — stdout vs stderr 的语义、信噪比原则。https://clig.dev/#output
+
+**搜索起点**：
+- "Unix Rule of Silence original text"
+- "CLI color output best practices NO_COLOR"
+- "bat exa ripgrep output design"
+- "terminal table formatting"
+
+---
+
+### 3. CLI 错误呈现
+**职责**：错误结构、修复建议、退出码语义、上下文信息
+
+**该做什么**：
+- 错误信息三要素（Azure CLI 规范）：**What**（什么错了）+ **Why**（为什么错）+ **How**（怎么修）
+- 退出码语义化（POSIX + agent-cli-guide 扩展）：
+  - `0` 成功
+  - `1` 一般错误
+  - `2` 用法错误（POSIX 约定）
+  - `3` 资源不存在 / `4` 权限拒绝 / `5` 冲突已存在（现代扩展，对 Agent 友好）
+- 错误写到 stderr，数据写到 stdout（clig.dev 强制）
+- 可修复的错误带 `suggested_fix`（Rust 编译器的 `Applicability` 标记：`MachineApplicable` / `MaybeIncorrect`）
+- 多个同类错误归组到一个标题下，不要刷屏（clig.dev：信噪比是关键）
+- 最重要的信息放最后——用户视线最后停留的位置（clig.dev）
+
+**不该做什么**：
+- 不要 dump stack trace 给用户（除非 `--verbose` 或 debug 模式）
+- 不要把错误信息写得像公式或编程表达式（Azure CLI 规范）
+- 不要在错误信息里加颜色或样式控制（Azure CLI：错误信息要纯文本）
+- 不要用 `resource group is missing, please provide` 这种模糊说法——用 `please provide a resource group name by --resource-group`（带具体 flag）
+- 不要用 exit code 1 涵盖所有错误——区分用法错误和运行时错误
+
+**参考实践**：
+- **Rust 编译器错误设计** — primary span（红）+ secondary span（蓝）+ `help:` 建议 + `Applicability` 标记。RFC 1644。https://rust-lang.github.io/rfcs/1644-default-and-expanded-rustc-errors.html
+- **Elm 编译器错误** — "Compiler Errors for Humans"，教育性错误信息范本。https://elm-lang.org/blog/compiler-errors-for-humans
+- **Azure CLI 错误处理规范** — What/Why/How 三要素 + actionable message。https://github.com/Azure/azure-cli/blob/dev/doc/error_handling_guidelines.md
+- **jmmv.dev "CLI design: Error reporting"** — usage error vs application error 的区分。https://jmmv.dev/2013/08/cli-design-error-reporting.html
+- **clig.dev "Errors" 章节** — 把错误变成文档、catch and rewrite for humans。https://clig.dev/#errors
+- **agent-cli-guide Principle 6** — 语义化退出码（对 Agent 消费者友好）。https://github.com/Johnixr/agent-cli-guide
+- **RFC 9457 Problem Details** — HTTP 错误结构，可移植到 CLI（zircote 博客）。https://zircote.com/blog/2026/04/cli-error-messages-are-a-dual-consumer-problem/
+
+**搜索起点**：
+- "CLI error message design best practices"
+- "Rust compiler error messages design Applicability"
+- "exit code conventions sysexits.h"
+- "error message actionable suggested fix"
+
+---
+
+### 4. 转换/处理引擎（如果是转换类工具）
+**职责**：核心逻辑、纯函数设计、子集 vs 全集策略、透传 vs 报错
+
+**该做什么**：
+- 核心层纯函数——`parse(input): output`，不 IO、不读全局状态、不调 `Date.now()`
+- IO 只在 CLI 层，核心层可独立测试、可被其他入口复用
+- 子集策略要显式声明——支持什么、不支持什么，文档里写清楚
+- 不支持的语法：报错（fail loud）还是透传（pass through）？显式选择，不要意外行为
+
+**不该做什么**：
+- 不要在核心层做 IO（破坏纯函数性 + 可测试性）
+- 不要用全局可变状态（破坏可预测性）
+- 不要"尽量支持"——要么支持要么不支持，模糊地带是 bug 工厂
+
+**参考实践**：
+- 取决于具体领域（Markdown 解析 / JSON 处理 / 文件转换）
+- "pure function design benefits"
+- "subset vs superset API design"
+
+---
+
+### 5. 产物设计（如果产出文件）
+**职责**：产物格式、自包含性、可预测性
+
+**该做什么**：
+- 产物自包含——不依赖外部 CSS/JS/字体（离线可用、可邮件发送、可存档）
+- 输出可预测——相同输入永远相同输出（byte-identical），不嵌时间戳、不嵌随机 ID
+- 产物格式稳定——格式是和用户的契约，不能随意变
+
+**不该做什么**：
+- 不要在产物里嵌生成时间/版本号（破坏 diff、破坏可复现）
+- 不要引用外部资源（CDN CSS、Google Fonts）——产物离线就坏
+- 不要输出"漂亮但不可预测"的产物——可预测 > 漂亮
+
+**参考实践**：
+- "self-contained output design"
+- "deterministic output reproducible builds"
+- Reproducible Builds 项目哲学。https://reproducible-builds.org/
+
+---
+
+## 搜索时的关键提醒
+
+1. 实践领域的知识在工具和标准里，搜 "best practices" / "design conventions" / 具体工具名，别只搜"哲学"
+2. 看真实工具的输出——`rg --help` / `fd --help` / `bat --help` 本身就是好实践的样本
+3. 读标准文档——POSIX / GNU Coding Standards 是 CLI 设计的根基
+4. 对比不同工具的做法——ripgrep vs grep、bat vs cat、fd vs find，差异里藏着设计决策
+5. 2026 年的新维度：CLI for Agents。CLI 的消费者现在还有 Agent，结构化输出（`--output json`）、语义化退出码、`schema` 命令正在成为新标准（clispec.dev、agent-cli-guide）