Agent DX
AI Agent 作为开发者的开发体验——一套 SDK、工具、结构化输出、错误封装或遥测数据，供 Agent 消费以进行构建或执行操作。出处信息存储在 skill.json 中；本文件仅用于运行时路由。
产出物： change-plan.md（DO）、audit-report.md 以及发现记录 + 工作流状态（当需要追踪时，REVIEW）、design-doc.md / refactor-runbook.md / explanation.md（DESIGN）。
核心原则
Agent 独自、以机器速度消费此表面，没有任何工具提示可以依赖。 因此，任何 SDK、工具、错误或遥测片段的准则是：一个随机的消费模型能否解析它、从中恢复，并且不受其伤害：使用类型化合约而非自然语言；恢复机制经过设计，而非寄希望于偶然；信任边界默认封闭。它位于 dx-audit / dx-design 所拥有的 HTTP 客户端基础之上，并且永远不会取代它。
激活
- 裸调用（
"use agent-dx"、"start"）：显示一个紧凑菜单：模式选择（引导 / 自动驾驶 / 质问我？）和来自路由器的编号意图。等待。不检查文件、不进行网络调用、不写入。 - 具体调用（意图和表面可推断）：直接跳到步骤 3。
- 模糊调用：提问一次——例如：“您是在审计 SDK、工具模式、结构化输出封装还是遥测表面？” 或 “这是合同/恢复审查还是信任边界审计？”
工作流
- 选择意图。 加载
references/intent-router.csv；匹配到do、review或design。 模糊→提问一次。 - 选择表面。 加载
references/intents/<intent>.csv；匹配一个或多个sdk-design、tools-and-mcp、structured-output、errors-and-retry、sdk-telemetry——或all（用于 REVIEW 级联）。模糊→询问一次并显示菜单。 - 加载接地上下文。 只加载所选行的
playbook及其core_refs。不加载其他 playbook（review/all行没有携带任何 playbook——每个表面 Agent 加载自己的 playbook；见步骤 6）。 - 识别目标角色 从
references/core/personas.md。 - 然后根据项目规模进行校准（REVIEW / DESIGN）按照
references/calibration.md：低于承重级别时，缩小范围，将相同机制的问题合并为一个系统性发现，并拆分 现在 和 以后（随着增长）。层级影响输出，而非严重性。 - 并行分发展开（默认 REVIEW，当允许时）：对于
all每个表面一个 Agent；否则使用下面三个透镜。如果不能使用委托原语，则顺序执行。 - 应用 Playbook。 使用为意图标记的启发式规则。对于 REVIEW，为每个表面打分 0–10（
references/core/score-rubric.md）；综合各透镜的发现，将分歧保留为开放问题。应用严重性和稳定的AGENT-DX-<表面>-NNNID（references/core/severity-rubric.md）：AGENT-DX-SDK、AGENT-DX-TOOL、AGENT-DX-OUT、AGENT-DX-ERR、AGENT-DX-TEL。 - 输出。 DO →
templates/change-plan.md。REVIEW →templates/audit-report.md。DESIGN →templates/design-doc.md（结构）、templates/refactor-runbook.md（加固流程）或templates/explanation.md（解释原理）。 - 创建、恢复或关闭追踪状态（REVIEW）。对于包含 7 个及以上发现、任何严重性为 3–4 的审计，或收到保存/追踪/关停请求时，加载
references/trackable-findings.md。如果请求指定了现有记录、工作流状态、PR 或AGENT-DX-*ID，则首先读取已保存状态；仅当每条验证规则通过后才更新状态。否则，在docs/audits/agent-dx-findings-ledger-<YYYY-MM-DD>-<scope-slug>.md写入发现记录，在docs/audits/agent-dx-workflow-state-<YYYY-MM-DD>-<scope-slug>.json写入工作流状态（如果docs/audits/不可写，则回退到audit-artifacts/agent-dx-...）。报告两个路径；路线图、问题和非追踪性编辑保持可选。
方向错了？ 如果用户表示这不是他们的意图，请返回步骤 1（选择意图）——不要在错误的方向上打补丁。重申更正后的理解并重新规划。
模式
引导草稿（默认）、自动驾驶、质问模式——参见 references/modes.md。在裸调用时提供；对于具体调用默认使用引导草稿。
输出要求
每个输出需注明意图、表面、角色、应用的 Playbook 以及 skill.json 中的接地来源；REVIEW 还需为每个发现添加严重性 + 验证结果以及项目层级。请说明您有意不添加的 Agent 消费能力保证（YAGNI），而不仅仅是您添加的那些。
子代理分发
当允许委托且任务并非微小或涉密时，默认采用 REVIEW。并行派生三个透镜——合同与模式（来自代码的类型化模式、稳定的错误封装、验证后的输出）、Agent 恢复（停止 + 验证、面向重试的错误、语义重试、有界循环）、信任与隔离（工具元数据注入、防护栏检查点、凭据墙、内容审查）——按照 references/subagent-dispatch.md 执行，然后综合，按严重性排序。
参考映射
references/intent-router.csv+references/intents/<intent>.csv——两层路由。references/playbooks/<surface>.md——sdk-design、tools-and-mcp、structured-output、errors-and-retry、sdk-telemetry。references/subagent-dispatch.md——三个透镜的提示和综合。references/core/*.md——严重性、评分、角色、词汇表。references/{calibration,trackable-findings,modes}.md——共享（符号链接）。templates/*.md——变更计划、审计报告、设计文档、重构手册、解释文档，以及共享的追踪工件。evals/、skill.json——关卡和出处。