@haaaiawd/loom 0.1.0 → 0.8.0

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）

package/dimensions/universal/COLLABORATION_PHILOSOPHY.md

@@ -0,0 +1,77 @@
+# 维度指引：协作哲学
+
+> 所有项目都需要。回答"怎么决策、怎么处理冲突、谁说了算"。
+> 产出融入 DECISION_RUBRIC.md 或独立文档。
+
+---
+
+## 触发条件
+
+**必跑**——通用层三个维度之一，所有项目都激活。
+
+---
+
+## 引导问题
+
+1. **谁做决策？** 单人决策？共识决策？权威决策？不同类型的决策（技术选型、接口变更、架构调整）分别由谁拍板？
+2. **冲突怎么处理？** 两个人对同一个设计有不同意见，怎么解决？投票？权威？数据驱动？
+3. **变更怎么管理？** 谁能发起变更？变更需要什么审批？变更的影响怎么评估？
+4. **代码审查的标准是什么？** 审查看什么——风格？逻辑？架构？安全？审查不通过怎么办？
+5. **文档和代码的关系？** 文档先行？代码先行？同步更新？文档过时了怎么办？
+
+---
+
+## 参考源指引
+
+### 决策哲学
+
+- **Amazon"Disagree and Commit"** — Jeff Bezos 的股东信。搜 "Amazon disagree and commit"。核心：分歧可以，但定了就全力执行。
+- **Google"Design Docs"** — 搜 "Google design doc culture"。核心：设计先行、文档驱动决策、异议记录在文档里。
+- **RFC 文化** — Rust/IETF 的 RFC 流程。搜 "Rust RFC process"。核心：提案-评审-决策的显式流程。
+
+### 代码审查哲学
+
+- **Linux Kernel Review 文化** — Linus Torvalds 的 review 风格（有争议，批判性阅读）。搜 "Linux kernel code review philosophy"。
+- **Google Code Review Guidelines** — 搜 "Google code review guide"。核心：事实 > 偏好、 kindness + technical rigor。
+- **Conventional Comments** — https://conventionalcomments.org/。核心：评论带标签（praise/nitpick/question/issue）。
+
+### 冲突处理
+
+- **Crucial Conversations** — Patterson 等（2011）。核心：安全氛围、事实先行、共同目标。
+- **Nonviolent Communication (NVC)** — Marshall Rosenberg。核心：观察-感受-需要-请求。适用于团队冲突。
+
+### 文档哲学
+
+- **Docs as Code** — 搜 "docs as code philosophy"。核心：文档和代码同生命周期、同审查流程。
+- **The Bitter Lesson of Documentation** — 搜 "documentation bitter lesson"。核心：文档过时比没有文档更危险。
+
+### ADR（架构决策记录）
+
+- **Michael Nygard"Documenting Architecture Decisions"** — 原文：https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions。ADR 的原始定义。
+- **ADR GitHub Organization** — https://adr.github.io/。ADR 的变体和实践。
+
+---
+
+## 落地要求
+
+织造出的协作哲学融入 DECISION_RUBRIC.md 或独立文档，必须包含：
+
+1. **决策权限矩阵**：哪些决策由谁做（单人/共识/权威）
+2. **冲突处理规则**：分歧升级路径、仲裁机制
+3. **变更管理流程**：变更发起、审批、影响评估
+4. **代码审查标准**：审查看什么、不通过怎么办
+5. **维度冲突取舍规则**：当产品哲学和工程哲学冲突时，谁优先？什么条件下可以覆盖？
+6. **灵感来源**：至少 2 个独立源，每个源说明"为什么选它"
+
+### DECISION_RUBRIC.md 的特殊要求
+
+- 维度冲突的取舍规则（如"性能 vs 体验冲突时，体验优先"）
+- 取舍规则的适用条件（什么时候规则生效）
+- 例外条件（什么时候规则可以被覆盖）
+- 覆盖规则需要什么（如"需要用户显式批准"）
+
+### 禁止
+
+- 禁止"共识决策"这种没有操作性的规则——必须说明"共识达不成怎么办"
+- 禁止冲突处理只有"讨论解决"——必须有升级路径和仲裁机制
+- 禁止维度冲突取舍规则没有例外条件——所有规则都应有可覆盖的场景

package/dimensions/universal/ENGINEERING_CREED.md

@@ -0,0 +1,74 @@
+# 维度指引：工程哲学
+
+> 所有项目都需要。回答"怎么写代码、什么不做、什么是好代码"。
+
+---
+
+## 触发条件
+
+**必跑**——通用层三个维度之一，所有项目都激活。
+
+---
+
+## 引导问题
+
+1. **什么是好代码？** 不是"能跑的代码"，是"五年后的人能看懂的代码"。具体到这个项目，好代码的标准是什么？
+2. **数据流是怎样的？** 单向还是双向？有状态还是无状态？纯函数还是有副作用？为什么这样选？
+3. **错误怎么处理？** 静默吞错？抛异常？返回错误码？透传？每种错误类型的处理策略是什么？
+4. **依赖策略是什么？** 零依赖？最小依赖？依赖什么、不依赖什么、为什么？
+5. **抽象到什么程度？** YAGNI 还是预留扩展？什么时候加抽象，什么时候不加？
+6. **测试策略是什么？** 单元测试？集成测试？契约测试？测什么、不测什么、为什么？
+
+---
+
+## 参考源指引
+
+### 通用工程哲学
+
+- **Clean Code** — Robert C. Martin（2008）。核心：函数短小、单一职责、命名清晰。但注意：Martin 的某些主张有争议（函数不超过 20 行等），需要批判性阅读。
+- **The Pragmatic Programmer** — Andy Hunt & Dave Thomas（1999/2019 修订）。核心：DRY、正交性、曳光弹、契约式设计。比 Clean Code 更务实。
+- **A Philosophy of Software Design** — John Ousterhout（2018）。核心：深模块 vs 浅模块、接口设计、复杂度管理。Ousterhout 和 Martin 在"函数大小"上有分歧——对比阅读。
+- **SICP** — Abelson & Sussman（MIT 经典）。核心：抽象、组合、元语言抽象。理论根基。
+
+### 函数式编程哲学
+
+- **Structure and Interpretation of Computer Programs** — 见上。
+- **Pure Function-based Architecture** — 搜 "pure function architecture"。核心：纯函数 + 不可变数据 + 副作用隔离。
+- **Haskell 设计哲学** — 搜 "Haskell philosophy pure functional"。核心：纯函数、惰性求值、类型系统。
+
+### 系统设计哲学
+
+- **A Philosophy of Software Design** — 见上（深模块部分）。
+- **Designing Data-Intensive Applications** — Martin Kleppmann（2017）。核心：数据流、一致性、容错。
+- **The Twelve-Factor App** — https://12factor.net/。核心：配置外置、无状态进程、一次性。
+
+### 错误处理哲学
+
+- **Joel Spolsky"Exceptions vs Error Codes"** — 搜 "Joel Spolsky exceptions"。经典争论。
+- **Go 的 error-as-value 哲学** — 搜 "Go error handling philosophy"。核心：错误是值，不是控制流。
+- **Rust 的 Result/Option** — 搜 "Rust error handling philosophy"。核心：类型系统强制错误处理。
+
+### 测试哲学
+
+- **TDD** — Kent Beck *Test-Driven Development*（2002）。核心：红-绿-重构。
+- **Property-based Testing** — 搜 "property based testing philosophy"。核心：测不变量，不测具体案例。
+- **The Way of Testivus** — 搜 "testivus testing philosophy"。核心：测试够用就好，不要过度。
+
+---
+
+## 落地要求
+
+织造出的 ENGINEERING_CREED.md 必须包含：
+
+1. **工程北极星**：一句话，工程层面的判断基准
+2. **代码原则**：编号（E1, E2...），每条有理由
+3. **工程反模式清单**：编号（EAP1, EAP2...），每条有"不做"和"为什么"
+4. **灵感来源**：至少 2 个独立源，每个源说明"为什么选它"
+5. **底线内化声明**：与 PRODUCT_PHILOSOPHY.md 一致
+6. **章节锚点**：每个章节有 `{#english-anchor}` 标识
+
+### 禁止
+
+- 禁止照搬 Clean Code 的条目不加工——必须转译为本项目的具体约束
+- 禁止"好代码是可读的"这种废话——必须具体到"什么场景下可读性优先于性能"
+- 禁止抽象层和产品层重复——工程哲学聚焦"怎么写"，产品哲学聚焦"为什么存在"

package/dimensions/universal/PRODUCT_PHILOSOPHY.md

@@ -0,0 +1,70 @@
+# 维度指引：产品哲学
+
+> 所有项目都需要。回答"这个产品为什么存在、北极星是什么、什么不能妥协"。
+
+---
+
+## 触发条件
+
+**必跑**——通用层三个维度之一，所有项目都激活。
+
+---
+
+## 引导问题
+
+织造时依次回答：
+
+1. **这个产品为什么存在？** 不是"它能做什么"，是"如果没有它会怎样"。如果答案是"用户会用别的工具"，那这个产品没有存在理由。
+2. **北极星是什么？** 一句话。不是愿景陈述，是判断基准——遇到冲突时，拿这句话量一下。
+3. **什么不能妥协？** 3-5 条。不是"想要"的，是"没有就不行"的。每条必须有理由——为什么这条不能妥协，妥协了会怎样。
+4. **反模式是什么？** 和"做什么"同样重要。每个反模式必须说明"不做"和"为什么不做"。
+5. **决策原则是什么？** 当价值冲突时怎么取舍。不是口号，是可执行的判断规则。
+
+---
+
+## 参考源指引
+
+### 实践驱动领域（CLI 工具、开发者工具、基础设施）
+
+- **Unix Philosophy** — Doug McIlroy, 1978。原著：*The UNIX Time-Sharing System*（论文）。延伸：Eric Raymond *The Art of UNIX Programming*（2003）、Mike Gancarz *The UNIX Philosophy*（1995）。不要只引 Wikipedia——读 Raymond 的书，里面有 17 条具体原则。
+- **Plan 9 设计原则** — Rob Pike, Ken Thompson。和 Unix Philosophy 有继承也有分歧（"一切皆文件"走得更远）。对比阅读能产生张力。
+- **Dieter Rams"好设计十诫"** — 原文在 Vitsoe 官网（https://www.vitsoe.com/eu/about/good-design），不是 Wikipedia 摘要。
+- **Stripe API 设计哲学** — Stripe 工程博客。搜 "Stripe API design philosophy"。核心：API 是产品契约、一致性 > 灵活性。
+- **Jeff Atwood / Joel Spolsky 的工具哲学** — Stack Overflow / Fog Creek 创始人。搜 "Joel Spolsky software philosophy"。
+
+### 2C 产品领域（面向终端用户）
+
+- **Steve Jobs 产品哲学** — 原著：Walter Isaacson *Steve Jobs*（2011）。核心：减法优先、体验 > 功能。
+- **John Maeda"减法法则"** — *The Laws of Simplicity*（2006）。MIT Press 出版。
+- **Don Norman"以用户为中心的设计"** — *The Design of Everyday Things*（1988/2013 修订版）。
+
+### 2B / 平台领域
+
+- **Amazon Working Backwards** — 搜 "Amazon working backwards document"。核心：从 PR/FAQ 倒推技术方案。
+- **Google Design Docs** — 搜 "Google design doc template"。核心：设计先行、文档驱动。
+
+### 学术建制化领域（如果有理论根基需求）
+
+- **SEP"Philosophy of Technology"** — 斯坦福哲学百科全书条目。搜 "SEP philosophy of technology"。
+- **Hubert Dreyfus** — *What Computers Still Can't Do*（技术哲学视角）。
+
+---
+
+## 落地要求
+
+织造出的 PRODUCT_PHILOSOPHY.md 必须包含：
+
+1. **北极星**：一句话，可被 Intent 的 `philosophy_anchors` 引用
+2. **不可妥协的价值**：3-5 条，每条有理由
+3. **反模式清单**：编号（AP1, AP2...），每条有"不做"和"为什么"
+4. **决策原则**：编号（P1, P2...），每条有适用条件和判断标准
+5. **灵感来源**：至少 3 个独立源，至少 2 个非 Wikipedia 链接，每个源说明"为什么选它"
+6. **底线内化声明**：显式声明已内化 BASELINE
+7. **章节锚点**：每个章节有 `{#english-anchor}` 标识
+
+### 禁止
+
+- 禁止只有 Wikipedia 链接——Wikipedia 是常识入口，不是深度源
+- 禁止"灵感来源"只有名字没有理由——必须说明萃取/转译关系
+- 禁止北极星是口号（如"做最好的工具"）——必须是判断基准
+- 禁止反模式没有"为什么"——"不做"和"为什么不做"同样重要