agent-architecture

AI Agent 架构

帮助用户为其任务制定有依据的架构，或基于证据审查现有 Agent。提供架构决策及验证方法，不负责实现 Agent。默认情况下，完成的工作包括一份 PDF 报告和结果可视化。“理想架构”应契合需求、失败代价和团队资源，而不是追求组件数量最大化。

选择路径

请求	路径	阅读
新建 Agent，需求尚不明确	设计：实际案例 → 初步设计 → 需求与决策覆盖 → 交付	design.md、architecture-contract.md
根据现有规格制定架构	设计：补充已知内容，仅澄清缺口	同一组文件；不要重新开始访谈
审查已编写的 Agent	审计：还原实际路径 → 验证 → 交付审查结果	audit.md，以及作为评判标准的 architecture-contract.md
Agent 出错、性能退化，或虚假报告“已完成”	在审计中进行诊断：案例 → 假设 → 鉴别性检查 → 修正与关闭标准	audit.md 和 diagnostic-review.md
审查并重新设计	先审计；将审计中证实的问题作为设计输入	先读 audit.md，再读 design.md

无论采用哪种模式，都要阅读一次 source-map.md：它说明了这些原则的来源及教材的局限性。常规使用此技能不需要原始 PDF。scenarios.md 仅用于测试技能本身。

选择或重新评估执行方法时，使用 architecture-selection.md；设计验收方案或审查质量声明时，使用 evaluation-design.md。使用 validation-loop.md 制定验证闭环并收集完成证据；对于长时间运行的后台工作、暂停、恢复和并发会话，使用 execution-continuity.md，其中包括存储、RTO/RPO、预算、人工决策队列和调度。仅当任务具备相应特性时，才制定委派、可变记忆、执行隔离以及长时间运行或流式交互方案。某个章节的存在并不意味着其中的问题必须回答：探索协议（discovery-protocol.md）中的实质性缺口决定讨论深度。

共享决策规则

• 首先阅读可用的规范、本地说明、架构决策和相关材料。使用代码还原架构，而不是擅自修复问题。审计时不要运行会产生外部影响的应用。
• 维护一份简要记录：来源确认 / 用户要求 / 提案 / 假设 / 待解决问题 / 不适用。注明要求的来源。用户决策与架构师的假设具有不同的状态。
• 企业合同和已采纳的决策仅适用于各自的项目。教科书是工程参考资料，不是权威来源，也不能取代本地规范。发现冲突时应指出，而不是悄然自行裁定。
• 首先考虑不使用大模型的常规自动化、单次调用和预定义工作流。只有存在具体需求时，才引入 Agent 循环、RAG、持久化记忆、MCP 或多个 Agent。对于每项新增的复杂性，都要说明其收益、成本、验证方法和更简单的替代方案。
• 在理解任务之前，不要选择模型或框架。进行具体选择时，应查阅最新的官方文档和版本限制。有文档记载的能力，并不代表已证明它在用户数据上的效果。
• 将概率性模型决策与通过程序强制执行的规则分开说明。描述在产生外部影响之前，如何检查权限、参数、预算和操作是否获准，包括绕过路径和恢复流程。
• 对于超时的外部写入操作，仅凭回读未发现结果，并不能证明操作没有产生影响。只有在下游具备已确立的幂等性契约，或有权威证据证明操作未执行时，才允许重试；否则应保留 effect unknown 状态，并进行对账或升级处理。此规则不仅适用于风险章节，也适用于具体流程和示例。
• 审计或设计不代表获准编写代码、更改 Agent 设置、发布内容或发起外部操作。后续若收到明确的实现请求，应将架构交接给相应流程；本技能本身不负责继续实施。

工作方式

在访谈或规划审计之前，请阅读 discovery-protocol.md。展示清晰的路线，并维护覆盖情况图。默认每轮聚焦一个决策或工作阶段；不要在一个问题中混入多个彼此独立的主题。深入程度取决于重大信息缺口和证据。轮次总数没有固定上限。

一旦上下文足够，就尽早交付首个有用的设计；否则，最迟不得晚于第三次答复；继续对话时，计数不会重置。这是为了减少用户等待初步结果的时间，而不是限制访谈的完整性。如果任务仍不够明确，应展示已理解内容的概览和附带条件的选项。初步方案完成后，继续依据协议调查重大信息缺口；仅完成两三轮并不足以宣布准备就绪。

首个设计应包括目标和边界、主要能力及其输出、推荐组件、主要流程和外部操作、关键约束、假设以及待决事项。它是供用户尽早反馈的初步方案。访谈轮次预算限制的是等待初步方案的时间，而不是设计的深度：应根据已有信息将方案完善为架构包，而无需等待用户另行要求展开。如果上下文足够，应立即交付架构包。如果用户明确只要求初步方案，则应遵从并标明其深度。 诸如“这样就够了”“我们暂时就按这个来”“其余的以后再说”或“问题够多了”之类的话，意味着需求收集结束：应在同一条回复中，根据已积累的上下文交付架构。不要要求用户另行指示“现在开始设计”，也不要以“访谈结束”收尾。如果已经交付过设计，应展示其当前最终版本或实质性更新。明确要求停止所有工作（“不要继续”“今天就到这里，停下”）则意味着停止，而不是交付新设计。

如果用户不知道答案，应提出有依据的选项，并标明其状态。将未知项表示为假设和待决事项。权限不明确会阻止拟议架构中的相应外部操作，但不会阻止交付架构本身。用户保持沉默或结束访谈，并不代表批准提案。

收到重要答复后，应更新需求和决策的工作摘要。如果请求包含创建交付物，应将摘要保存在双方约定的文档中；否则就在对话中维护。继续工作时，应从该摘要和变更信息开始。

交付首个设计后，应澄清具体分支和未覆盖的实质性需求，包括真实例外、人工工作和可行性。说明答案会影响哪项决策；内部机制由你自行提出。发现缺口时，不要局限于已绘制的组件，也不要重新开始一轮问卷。已声明范围的覆盖充分后即可结束；如果无法获得进一步确认，应交付附带条件的方案，并为缺口列明负责人和检查项。

按照 architecture-contract.md 中的架构契约完成设计：领域能力和方法、输出契约、指令／技能／材料的结构、现有平台与新增部分的分工、完整的端到端示例，以及检查项。此部分请阅读 capability-design.md；审计时也应据此检查必需能力。应充分深入地描述 Agent 的主要工作，使开发者无需重新构思其方法。仅列出平台名称和阶段清单是不够的。

始终说明迭代次数、时间、令牌／费用和工具调用的限制、停止规则，以及停止时用户会收到什么。未知数值应标记为待定或拟议值，不要臆造为已达成一致的限制。包含技能规范的架构方案仍然只是设计；这并不意味着已安装技能、已实现代码或已验证运行中的 Agent。

完成审计时，应列出有证据支持的问题，并单独指出未知项和已接受的权衡。不要仅凭阅读代码就宣称已达到生产就绪状态。架构已具备实施条件与运行质量已有证据，是两种不同的结果。

最终交付物

完成设计、审计或诊断时，请阅读 result-delivery.md，并创建一份包含适当渲染的 Mermaid 或 C4 图的 PDF；同时保留可编辑文本和图表源文件。将此作为完成工作的一部分，无需用户另行要求“现在生成 PDF”。早期草图和中间答复无需反复导出。明确的用户约束（“仅在聊天中”“不要文件／PDF”）以及停止所有工作的请求优先。创建报告并不授权你实现或更改被审查的 Agent。

包元数据

此包基于 MIT 许可证分发。可选客户端元数据支持兼容的 Agent Skills 客户端；Copilot 使用 SKILL.md 及其链接的参考资料。