跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

agent-system-design-cn

单 Agent 与多 Agent 系统设计方法(中文)。从需求出发判断是否需要 Agent、选择架构档位(提示词、工作流、单 Agent、多 Agent),完成角色、任务契约、工具、上下文与记忆、编排模式、Agent 间交接、人类介入、可靠性与安全、评测的设计,产出结构固定的设计文档并按 21 个维度自检评分。融合 21 种 Agentic 设计模式。当用户需要:(1) 从零设计 Agent 或多智能体系统、智能体工作流、Agent 流水线;(2) 选择或组合设计模式(提示链、路由、并行、反思、编排者-工作者、规划等);(3) 设计 Agent 之间如何交接数据、拆分角色;(4) 评审、诊断、打分已有 Agent 设计;(5) 设计现有 LLM 应用的必要演进方案时使用。不负责运行时编排、业务代码重构、仓库 Harness 化、部署或发布。

geniusjia666 · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add geniusjia666/agent-system-design-cn --skill agent-system-design-cn

技能说明


name: agent-system-design-cn description: 单 Agent 与多 Agent 系统设计方法(中文)。从需求出发判断是否需要 Agent、选择架构档位(提示词、工作流、单 Agent、多 Agent),完成角色、任务契约、工具、上下文与记忆、编排模式、Agent 间交接、人类介入、可靠性与安全、评测的设计,产出结构固定的设计文档并按 21 个维度自检评分。融合 21 种 Agentic 设计模式。当用户需要:(1) 从零设计 Agent 或多智能体系统、智能体工作流、Agent 流水线;(2) 选择或组合设计模式(提示链、路由、并行、反思、编排者-工作者、规划等);(3) 设计 Agent 之间如何交接数据、拆分角色;(4) 评审、诊断、打分已有 Agent 设计;(5) 设计现有 LLM 应用的必要演进方案时使用。不负责运行时编排、业务代码重构、仓库 Harness 化、部署或发布。

Agent 系统设计

把一个业务需求变成一份可落地、可评审的 Agent 系统设计文档。提示词、工作流、单 Agent、多 Agent 四个档位共用同一套流程,按档位裁剪深度。仅交付设计或评审;运行业务、修改代码、部署和发布需用户另行要求。

目录

  1. 核心原则
  2. 三种入口
  3. 设计流程(第 1 至 7 步)
  4. 参考文件导航
  5. 常见错误

核心原则

  1. 从最简单的方案开始。 能用一次 LLM 调用解决的,不做工作流;固定步骤能解决的,不上自主 Agent;单 Agent 够用的,不拆多 Agent。每次增加步骤、自主性或 Agent 数量,都要写明理由、收益和代价(时延、成本、可控性)。
  2. 先设计交接数据,再选框架。 多 Agent 系统的大部分故障出在步骤之间:信息被层层转述而失真、约束丢失、下游拿不到需要的原始材料。框架只是实现手段。
  3. 用契约代替口头描述。 每个 Agent 有明确的角色和边界,每个任务有结构化的输出定义和完成标准,每次交接有可校验的字段。
  4. 上下文是有限预算。 每一步只给完成该步所需的最小高信号信息;先按需加载、剪枝、压缩或记笔记。大量独立探索确需隔离时再用子 Agent,回收结论、证据与缺口;长期记忆按需建立。
  5. 关键约束用代码保证。 权限、循环上限、成本上限、必填字段校验放在编排层或工具层强制执行,提示词只作说明。
  6. 设计必须可评测。 没有成功标准和评测方式的设计不算完成。

三种入口

先判断用户属于哪种情况,再进入流程:

入口用户给出的信息走法
新设计业务需求或想法第 1 步到第 7 步全流程
评审已有设计设计文档、提示词、工具清单、架构图或代码按模板结构还原已知现状,缺材料标待核实,候选设计与现有实现分开标注;按需读相关参考,再做第 7 步自检。只输出《Agent 设计评估报告》,开头用一小节写还原的现状与待核实项,完整设计模板留给新设计和改造入口
改造已有系统现有 LLM 应用或代码工程先还原现状并做第 7 步自检定位短板,再从第 2 步重新走,仅设计必要变化;输出完整设计模板,未改动的章节写「沿用现状」。实施代码或配置变更需另获授权,尊重现有架构

信息不足时先提问,一次最多问 3 个最关键的问题。只读材料能弄清的事情不要问用户。

设计流程

确认需要模型后走完 7 步;普通代码足够时按第 2 步提前结束,其余按档位裁剪第 3 至 5 步的深度:

1 需求澄清 → 2 架构选型 → 3 单 Agent 设计 → 4 编排与协作 → 5 介入与加固 → 6 评测 → 7 交付与自检
档位第 3 步第 4 步第 5 步
提示词只写任务契约:输入、输出结构、完成标准通常无编排;实际有前后处理或交接时写最小边界只写输入输出防护和成本上限;有对外动作时加确认点
工作流每个 LLM 步骤写任务契约;用到工具的写工具设计写步骤顺序、分支和交接校验全部
单 Agent全部只写内部循环与停止条件全部
多 Agent全部全部全部

被裁剪的章节或表格行,在设计文档节首写一句「按某档位裁剪,不适用」即可,不逐行填写。同时命中「工作流」和「多 Agent」时(如固定顺序的多 Agent 流水线),涉及角色隔离与交接的项按「多 Agent」行执行,没有自主循环的节点不写内部循环。

每一步的结论都写进设计文档对应章节(模板见 assets/设计文档模板.md)。

第 1 步:需求澄清

明确以下内容,缺失的标为「待确认」,不要当作用户已确认。用户允许先出候选或进行示例试用时,可注明临时假设与影响并集中列到第 11 节;假设不授予实际数据、工具或业务执行权限:

  • 输入:来源、格式、规模、质量。
  • 输出:交付物形态、消费者(人还是下游系统)。
  • 成功标准:可衡量的完成条件,最好能直接转成评测用例。
  • 约束:时延、单次成本、调用量、合规与数据安全、可接受的错误后果。
  • 现状:已有系统、数据、工具、人工流程。

同时用业务基线、实际价值、信息可用性、错误代价和总成本判断需求适用性,不以总分或统一频率门槛代替前提核实;缺少验证时标候选及待验证。详见 references/08-评测与迭代.md 的「需求适用性」部分。

第 2 步:架构选型

读 references/01-架构选型.md。普通代码足够时交付理由和必要的普通方案,结束 Agent 设计,无需完整 Agent 模板;否则选择控制方式(单次调用、固定工作流、模型自主决策),最后判断是否需要多个 Agent。以下四个是常用标签,可以同时成立;写明为什么更简单的候选不够用。

标签适用信号
提示词(单次调用)输入齐全,一次调用加预先检索或示例即可候选达标
工作流(代码编排固定步骤)步骤、分支和循环边界可以预先定义,路径由代码控制
单 Agent需要模型根据环境反馈自主选择下一步,默认先用一个 Agent
多 Agent有明确的上下文、工具或权限隔离理由,且简单做法不足;任务复杂或步骤多只是线索

性能约束(时延、成本、有效上下文预算)不满足时,收缩范围、降级或保留人工处理;需求范围变更需用户确认。尚未验证的选型标为候选,推演与实测分开写。

固定顺序的多 Agent 流水线(如生成、审查、重构)同时属于工作流,第 4 步仍按多 Agent 设计交接。只做单次调用或固定任务节点时,自主规划、长期记忆和 Agent 循环按需配置。

第 3 步:单 Agent 设计

对系统中的每个 Agent 完成以下设计;固定工作流中的 LLM 步骤按任务节点定义,可以只是受限的模型调用。提示词和工作流按上方裁剪表只做部分:

  • 角色:职责、通用目标、必要工作准则,以及能力边界和禁止事项;背景(Backstory)按需填写,人设故事可以省略。读 references/02-单Agent设计.md。
  • 任务契约:输入、输出结构、完成标准及检查机制、停止条件(次数或总时限至少一个,外部等待有超时)。读 references/02-单Agent设计.md。
  • 工具:必要工具清单、描述与参数约束、返回及继续读取方式、错误去向、读写权限与审批、超时;说明本地函数、MCP 与 Skill 的接入或组合理由。读 references/03-工具设计.md。
  • 上下文与记忆:有效预算、启动与按需加载、剪枝或压缩、必要任务笔记与恢复;按需决定长期记忆及检索,写清来源、作用域、更新与失效规则。读 references/04-上下文与记忆.md。

第 4 步:编排与协作设计

  • 选编排模式:读 references/05-编排模式.md。先选提示链、路由、并行、编排者-工作者、评估-优化或自主循环中的主模式;规划与探索按实际缺口加入。写清依赖、关卡、聚合条件、失败出口与跨节点总预算,评分与模式和 Agent 的数量无关。先验证主模式再加必要辅助能力,模式数量按需要定;所需安全、预算和成功检查从首次执行生效。按21模式名称、工程线索或六类场景寻找候选时读 references/10-设计模式索引.md,区分控制、能力、协议与保障,核对详细落点及不同序的自检维度编号,目录名只是线索。
  • 多 Agent 时额外设计(读 references/06-多Agent协作.md):
    • 角色划分:写实际上下文、工具或权限隔离及简单替代不足的理由,区分角色、节点与实例;负责人和接纳者明确,拆分依据隔离需求,与差异数量和岗位无关。
    • 派发与交接:沿用 assets/交接契约模板.json 的七要素 dispatch、handoff 和 gate;原始目标、更早产物可读,可信任务关联与版本接纳由宿主检查。
    • 共享状态与通信:选择所需直接调用、状态或消息方式,写作用域、版本、负责人及发布规则;A2A、优先级和嵌套按需,委派不扩大授权或重置预算。
    • 交接处校验:格式、关联、证据、业务及产物可用性;执行成功与业务通过分开。失败、重复和迟到结果有明确去向,修正、重试共用任务预算。
  • 单 Agent 时写清必要内部循环及所组合模式的控制边界;固定步骤即使由同一模型处理,也需定义交接、分支或聚合条件。
  • 要落到具体框架时读 references/09-框架落地映射.md。映射同一契约的输入、校验、停止计数、介入、恢复与权限;核对 SDK 版本、弃用/维护状态及实际验证范围;构建骨架和接口替身与真实运行验收分开表述,框架按需使用。

第 5 步:人类介入、可靠性与安全

读 references/07-人类介入与可靠性安全.md,设计:

  • 人类介入点:按风险设计澄清、阶段确认、动作审批和异常升级;写负责人、真实请求与决定绑定、期限和恢复。统一可信记录,接收入口可以有多个;已读与批准分开,批准与授权分开。
  • 可靠性:根据错误及动作是否发生选择有限处理;结果未知先核对,重试与修正共用上限。按需保存可信状态,恢复沿用已完成副作用的结果和累计预算,取消与补偿如实记录原动作已经发生。
  • 成本与资源:全部分支及重试共享预算,调用前预留、之后结算,超限安全结束;模型分级和回退按需,粗估明确标为估算。
  • 安全:可信身份与对象授权、最小权限、必要执行隔离、输入输出及敏感数据边界;ASK在批准前阻止,必需安全组件故障默认拒绝;提示词和正则只是辅助防线。
  • 可观测性:宿主记录真实动作、审批、检查、资源及必要状态;只存必要的正文,敏感内容和内部思维链按需管理;验证拒绝时实际工具未执行。

第 6 步:评测方案

读 references/08-评测与迭代.md,定义:

  • 评测用例:静态定义与执行/评分记录分开,写来源、版本、输入/夹具、必需标准和运行协议;至少覆盖主流程、边界、失败,参考答案可选,开发/回归与留出集按需分离。
  • 评测层级与方法:按任务检查输出、真实终态、必要过程和资源;代码、模型与人工各用在哪里,Mock/真实集成/UAT证明什么,评分器如何用正反例及人工校准验证。
  • 汇总与门禁:计划/已运行/有效评分的数量、分母、未运行/无效/失败及全部重跑;定义单次、pass@k或pass^k的协议与统计假设,版本可比,硬失败单独判定,待定或旧检查不得验收新版本。
  • 上线后与迭代:按实际需要写指标口径、窗口、采样、负责人和响应;信号核验成用例,根因驱动受控提案,授权/验证后生效,实时看板、A/B、自动学习和微调按需引入。

第 7 步:交付与自检

  1. 按 assets/设计文档模板.md 输出完整设计文档,每个章节都要有内容或写明「不适用」及原因;被裁剪表豁免的部分按上方裁剪写法处理。
  2. 按 assets/设计自检清单.md 先判定 Agent 类型,选出适用维度,逐项检查并打 0 至 5 分;区分设计、推演与实际验证依据,设计得分只评文档,与成功率和发布许可分开;未运行与无效评分分别记录,都不计入通过。
  3. 把发现的问题按严重、中等、轻微分级,列在文档末尾。严重问题必须修复;未修复时,文档标为「候选/未通过」,并把问题和所需决定列入第 11 节,不作为完成的设计交付。
  4. 给出不超过 5 条按优先级排序的后续建议,每条写明问题、原因、做法和预期收益。

参考文件导航

只在需要时读取,不要一次全部加载。

文件何时读取
references/01-架构选型.md第 2 步;用户问「要不要用 Agent」「单 Agent 还是多 Agent」
references/02-单Agent设计.md第 3 步;设计角色、任务契约、停止条件、推理方式
references/03-工具设计.md设计或评审工具、MCP、Skill 接入
references/04-上下文与记忆.md长任务、多轮对话、跨会话记忆、检索增强、上下文过长
references/05-编排模式.md第 4 步选择编排模式
references/06-多Agent协作.md多 Agent 的角色划分、交接、通信、派发子 Agent
[references/07-人类介入与可靠性安全.md](re
阅读完整来源 ↗