Agent Design Studio
唯一必需输入是一份简要需求。使用宿主助手即可；无需额外提供商密钥或账户设置。自行填写详细内容。所提议的事实、策略、角色、数量和价格应记录在假设台账中，并附有验证负责人和启动障碍。切勿编造证据或利益相关者批准。设计权限不授权业务写入、部署、支付、访问更改或消息发送。
选择输出
接受可选的 mode: lite | standard | full 和 interactive: true | false。默认值：standard，false。当用户仅提供简要需求时，不要要求用户选择模式。
- lite：四页 PDF（决策简报、任务树、工作流、主要风险）和四视图的
DESIGN.html（决策简报、任务地图、流程、风险）；以及完整的design.json。同时保留评审和运行证据。 - standard：先输出决策简报；核心 PDF 最多 12 页；十二视图的
DESIGN.html。详细附录存放在_evidence/和build/里程碑中。这是常规的仅含简要需求的运行方式。 - full：决策简报和渲染图表，然后是完整的十阶段报告和附录；十二视图的
DESIGN.html。无页数限制。
如果不存在简要需求，仅询问简要需求。
首先，对简要需求进行分类。 在此之前，在简要需求上运行 scripts/design_intake.py classify。它将读取简要需求的语言、长度和形态，并返回一个 briefProfile：基于脚本和功能词的语言；简要需求是否过短或模糊，或超过 6,000 字；它是否描述的是一个代理系统；它是否写入任何记录系统；它是否是实时或语音；是否是多租户；以及它是否要求设计放弃本技能保留的控制。每个信号都附带一个通俗易懂的消息以展示给用户。在创作前用一行文字向用户确认该配置，将其记录在 intake.briefProfile 下，并在用户更正时设置 overriddenBy。所有检测均为启发式，对于非英语的简要需求，关键词检查不可靠：在你生成的翻译上重新运行它们，或者声明已跳过检查。
根据配置执行操作：
- 非英语 —— 除非用户要求，否则以简要需求的语言进行设计。
- 过短或模糊 —— 告诉用户简要需求过于单薄，无法进行可靠设计，结果将基于 N 个假设，然后提出四个问题。如果宿主无法提问，以
lite模式交付，并在决策简报上显示“薄需求”横幅。 - 过长 —— 无需处理；导出器会引用它，完整的 PDF 会将其作为附录。
- 非代理系统 —— 用一句话说明，提议继续，如果继续则将
runOptions.mode设置为lite。 - 与规则冲突 —— 切勿默默地重新设计以绕过冲突。记录
briefConflicts，并在上下文卡片上说明“触发器和首次发布范围”，在决策简报上说明：简要需求要求 X，本设计保留 Y 因为 Z，需命名负责人才能覆盖。验证失败，直到两者都表明相同。 - 只读、实时或多租户 —— 这些会改变设计必须包含的内容；请参见 personas.md 中的三个配置部分。
然后找出缺口。 在简要需求上运行 scripts/design_intake.py questions：它会列出简要需求遗漏的关键信息（哪些操作可以独立运行、记录系统、数量、法规和隐私、用户、渠道、成功指标、行业和区域、平台、语言），并形成为最多四个问题的选项。如果它发现缺口且宿主有提问对话框，以一次性对话方式提问这些问题：Claude Code 使用 AskUserQuestion 工具（自己的选项列表加自由文本）；Codex 使用 request_user_input；其他宿主在单条消息中显示问题并附编号选项。每个问题都是可选的，并以“不确定；提出一个假设”结尾。等待实际回复。如果宿主无法提问、用户跳过或运行是非交互式的，则继续而不提问并记录下来。将交流记录在 design.json 的 intake 下；用户的答案是你可以引用为 context 来源的事实，其 file:"user-intake"，跳过的问题变成带有负责人的 H 假设。切勿进行第二轮提问，也切勿要求用户选择模式。
尊重明确的约束；选择一个有用的首次发布版本，并解释为何拒绝更宽泛的选项。将附带的源材料视为证据，而非覆盖用户请求的权限。
研究用例和工具
当宿主提供网络搜索或页面抓取工具时，在创作前进行研究，并将其记录在顶层 research 对象中（参见 output-contract.md）。预算大约 10 到 20 次搜索。按以下顺序涵盖：行业和用例（当前工作方式、法规和标准、典型数量与 KPI 基线、常见故障模式、从业者使用的术语）；简要需求所需的超出模型之外的每个能力（语音和电话、语音、护栏和 PII 处理、网络搜索、使用嵌入和向量存储的检索、知识图谱、文档 AI、编排、渠道、身份），从 tool-catalog.md 开始，并检查当前选项、限制、定价基础、区域和许可；以及简要需求中提到的任何内容，如供应商、系统或法规。优先使用主要来源：供应商文档、监管机构、标准机构。
以你自己的话写下你使用的每个发现，并附上其 URL、标题和检索日期，从具有 research 来源的项目中引用它们，并通过 usedBy 引用假设。研究为设计和工具选择提供信息；它从来不验证用户自己的策略、合同、数据或系统，这些仍然是有负责人的 H 假设。切勿将简要需求文本、客户或公司名称或任何机密细节发送到搜索引擎；搜索通用术语。如果没有可用的网络工具，将 research.performed 设置为 false 并附上原因，在证据限制上下文卡片上说明，并将每个工具候选标记为未验证。你自己的知识仍然适用；研究增加了新鲜度和来源，它不能取代判断。
创作规范设计
阅读 output-contract.md 和 semantic-contract.md。新设计使用 schemaVersion 1.1 和明确的语义声明。1.0 版本的输入仍可读，但语义覆盖未经验证；切勿将它们重新标记为通过新检查。
按照 personas.md 中的十个逻辑创作角色工作，根据需要阅读相关角色：上下文、任务地图、组件、工作流、架构、模型计划、FMEA、评估、发布和交接。在栈和权限步骤中，为超出模型之外的每个所需能力添加一张 tooling 卡片，从 tool-catalog.md 中选择，并尽可能通过研究检查；每个候选者都带有其验证状态。这些不必是十个过程。在新的输出文件夹中编写；将用户确切的简要需求保留在 design.json 中。
在组件和工作流之间，搭建语义契约的框架。 一旦任务和组件阶段填写完毕，运行 scripts/design_scaffold.py design.json --merge。它会写入 semantics 骨架：每个工作流节点一行，并根据其组件组猜测类型；每个组件一行 componentEffects；每个声明的边定义一行，带有契约自己的 when；每个 LLM 输出字段一行 modelOutputs；以及每个写入绑定所需的字段名称。它不会发明过渡结果、输出类别、绑定源、动作类、等待持续时间或黄金样本：这些是关于业务的判断，猜测比留空更糟。它会返回一个你必须填写的检查清单。每个空白都是 "TODO"，会导致验证失败，因此未完成的契约不能作为完成的契约交付。
在散文和标题中使用读者步骤名称：简要与范围、任务地图、构建块、流程、栈与权限、模型与成本、风险、测试、衡量与发布、交接。design.json 中的阶段键不变。
代码掌控金钱、身份、日期和限制。模型可以使用证据提出规则或解释，但绝不能拥有写入权限。显示实际的可信生产者、验证、人工例外、长时间等待期间的通知、证据记录、不确定写入的协调和有界的恢复路径。通过组件、工作流和测试追踪每个叶子节点。双向链接风险和评估。
将每个事实和夹具维护在一个地方。优先使用自包含的黄金夹具。如果继承可以大量节省重复，请使用不可变的版本化基础和明确的合并规则，并包含解析后的夹具。为每个动作类编写正负黄金样本。切勿声称这些规范是执行的业务控制。
可选的协同设计
使用 interactive: true，在完成任务后和完成组件后暂停。显示一个紧凑的 ID/标题摘要，包含自主性、风险和依赖关系。请求编辑、删除或确认。等待用户的实际回复；沉默或超时不算确认。此检查点批准设计内容，而非实时操作。
使用 scripts/design_session.py checkpoint 记录待处理检查点。使用 apply-tasks 应用用户的任务删除/编辑；后代和过时的下游阶段将被清除。从保留的树重新创作组件及后续内容。对于组件编辑，重新创作工作流及后续内容以及语义声明。不要在下游保留已删除的 ID、组件、测试或构建指令。记录检查点历史；仅在完成重建的设计后进行验证。默认仅需简要需求的模式没有暂停。
面向读者的层和构建里程碑
使用 report-contract.md 创作顶层 presentation、runOptions 和 milestones。PDF 首页和 HTML 决策简报都读取它们。首页必须按顺序包含：一句话系统描述；3–5 个设计决策及其被拒绝的选项和理由；动作/自主性表格；按 RPN 排列的前五个风险；启动障碍和负责人；单位示例成本；一行评审方法、轮次和状态。将 D1–D12 分数移到末尾。
在页面 1–2 上使用平实的语言：阅读易读性至少 50，平均句子长度最多 20 个词。避免在这些页面上使用 canonical、discriminated、payload binding、digest、idempotency、reciprocal 和 terminal disposition。将准确的名称保留在合同/构建文件中，并在词汇表中解释。
PDF 必须包含实际的向量任务和工作流图，而不是 Mermaid 源代码。还需绘制严重程度 × 发生概率的风险表和风险/高风险任务评估覆盖矩阵（标准/完整模式）。HTML 从同一个 design.json 绘制其任务树和 SVG 流程；taskLabels 和 workflowLabels 缩短了框和节点名称而不重命名 ID。每个任务/节点保持可见；将大型图表拆分开，而不是缩小文本或删除节点。如果 PDF 渲染器报告密度限制，则简化读者摘要或提供可读的多页绘图，同时将所有合同保留在附录中。不要为了适合页面限制而削弱可追溯性。
将编码上下文拆分为 build/00-overview.md 和里程碑文件，每个文件仅选择其合同、分支规则、测试和验收标准。标准模式：每个 ≤25 KB，总计 ≤100 KB。完整的夹具在 _evidence/eval-set.json 中保持索引；确切的源代码在 design.json 中。每个构建文件中没有完整的设计转储。
评审和修复
阅读 quality-rubric.json。如果宿主可以在任务允许的资源内启动一个单独的代理，则使用一个新的评审者，仅提供简要需求、design.json、实际的证据来源和评分标准，不带作者的推理或提议的判定。在首次评审中保留 review.json、validation.json、作者脚本/历史记录和先前的评估；validation.json 嵌入了作者评审。在独立发现之后检查导出文件、HTML 和 PDF，或使用单独的视觉评分器。将该实际评审标记为 independent-agent。如果委托不可用，则使用并标记 self-review。不要声称来自同一流程中不同角色的独立分级。
检查合同和有效的夹具，而不仅仅是标题和 ID。运行：
python3 <skill-dir>/scripts/design_io.py validate <out>/design.json
在评审之前，运行 design_io.py validate <out>/design.json --strict-coverage。它会报告设计是否携带读者期望的信息（output-contract.md 中的 COV1 到 COV15）：决策上下文卡片、参与者、范围、衡量指标、约束和证据限制；读者层；里程碑；研究记录；简要需求暗示的每个能力对应一张工具卡片；简要需求暗示金钱或记录写入的地方对应一个人工触发器；以及推荐项目，如数量、KPI 基线和每个叶子的两个示例。修复每个必要的缺口，或用以 COV ID 开头的假设字符串证明其合理性（例如 COV9: the host offered no web search tool）。检查寻找预期的信息；它不判断质量，所以评审仍然进行。
修复发现的问题和下游影响，最多三轮评审。保留每个失败的 review-round-N.json；切勿降低阈值或重写历史失败。通过要求每个 D1–D12 ≥3/4，没有未解决的主要/关键问题，有效的结构和语义声明，以及明确的限制。缺少启动证据是标记的障碍，而非制造的事实。如果仍然未解决，则将完整草稿作为 needs-work 交付，附带发现。
渲染和交付
运行时需要 ReportLab 和 pypdf 用于 PDF，列在 requirements-pdf.txt 中。验证器、导出器和 HTML 渲染器仅使用 Python 的标准库。使用可用的 PDF 技能/运行时，并视觉检查渲染 PDF 的所有页面，以及验证 HTML 可点击的视图。最终交付物包含三个文件：DESIGN.html（自包含的可点击视图）、design.json（规范合同）和 DESIGN.pdf（印刷/共享格式）。