Agent DX
智能体作为开发者的表面的开发者体验 —— SDK、工具、结构化输出、错误信封或遥测，智能体通过这些来构建或执行操作。Provenance 存储在 skill.json 中；此文件仅用于运行时路由。
产出： change-plan.md（DO）、audit-report.md 以及 findings-ledger + workflow-state（REVIEW 时）、或 design-doc.md / refactor-runbook.md / explanation.md（DESIGN 时）。
核心原则
智能体独自、以机器速度消费表面，没有工具提示可依赖。 因此，任何 SDK、工具、错误或跨度的门槛在于：随机消费者能否解析它、从中恢复，并且不被它伤害：类型化契约优于散文；恢复是设计出来的，而非指望的；信任边界默认关闭。它位于 dx-audit / dx-design 所拥有的 HTTP 客户端基础之上，而非取代它。
激活方式
- 裸调用（
"use agent-dx"、"review our MCP tool surface"、"start"）：加载references/intent-router.csv，显示意图菜单，提供模式。等待。不进行文件检查、网络调用或写入。 - 已推断意图和表面的具体调用：跳至第 3 步。
- 范围模糊：提出一个阻塞性问题，指明候选意图或表面；不要先检查私有系统。
工作流程
- 选择意图。 加载
references/intent-router.csv；匹配为do、review或design。模糊 → 询问一次。 - 选择表面。 加载
references/intents/<intent>.csv；匹配一个或多个sdk-design、tools-and-mcp、structured-output、errors-and-retry、sdk-telemetry—— 或对 REVIEW 分发表面时选择all。模糊 → 使用菜单询问一次。 - 加载接地上下文。 仅加载所选行对应的
playbook及其core_refs。不要加载其他 playbook（review/all行不携带 playbook —— 每个表面智能体会自行加载；见第 6 步）。 - 识别目标角色 来自
references/core/personas.md。 - 然后根据项目规模进行校准（REVIEW / DESIGN）依据
references/calibration.md：低于负载关键阈值时，缩小范围，折叠相同机制的间隙为一个系统性发现，并区分 现在 与 待扩展时（随着增长）。层级影响产出内容，但不影响严重性。 - 并行分派视角（REVIEW 默认允许时）：
all时每个表面一个智能体；否则为下面的三个视角。如果缺少委托原语，则回退为顺序执行。 - 应用 playbook。 使用标记给该意图的启发式方法。对于 REVIEW，对每个表面评分 0–10（
references/core/score-rubric.md）；综合各视角的发现，保留不同意见作为开放问题。应用严重性和稳定的AGENT-DX-<surface>-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。如果请求指定了现有的 ledger、workflow-state、PR 或AGENT-DX-*ID，则先读取已保存状态；每条验证规则通过后才更新状态。否则在docs/audits/agent-dx-findings-ledger-<YYYY-MM-DD>-<scope-slug>.md写入 ledger，在docs/audits/agent-dx-workflow-state-<YYYY-MM-DD>-<scope-slug>.json写入 workflow-state（如果docs/audits/不可写则回退到audit-artifacts/agent-dx-...）。报告两个路径；路线图、问题和非跟踪编辑保持可选。
模式
引导草稿（默认）、自动驾驶、拷问我 —— 详见 references/modes.md。在裸调用时提供；在具体调用时默认为引导草稿。
输出要求
每个输出指明意图、表面、角色、应用的 playbook 以及 skill.json 中的接地来源；REVIEW 增加每个发现的严重性和验证方式以及项目层级。明确指出你故意不添加的智能体可消费性保证（YAGNI），而不仅仅是你添加的那些。
子智能体分派
当委托被允许时默认用于 REVIEW；跳过小规模或机密性工作。并行生成三个视角 —— 合同与架构（来自代码的类型化 schema、稳定的错误信封、经过验证的输出）、智能体恢复（停止并验证、可重试形状的错误、语义重试、有界循环）、信任与隔离（工具元数据注入、护栏检查点、凭据墙、内容编辑）—— 依据 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/{severity-rubric,score-rubric,personas,glossary}.md— 规模、受众、术语。references/{calibration,trackable-findings,modes}.md— 共享（符号链接）。templates/*.md— change-plan、audit-report、design-doc、refactor-runbook、explanation，以及共享的跟踪工件。evals/、skill.json— 门控与溯源。