name: super-agent-architect
displayName: Super Agent 架构师
display_name: Super Agent 架构师
display_name_en: Super Agent Architect
version: 1.6.1
skill_type: 知识/方法论型
risk_tier: R1
allowed-tools:
- file:read
- file:write
- shell:execute
- network:declared
allowed-domains:
- api.deepseek.com
- api.openai.com
- api.anthropic.com
- localhost
urls:
- https://mp.weixin.qq.com/s/zoS7GlReWPhfCjENGxXCdg
- https://mp.weixin.qq.com/s/2R9xtPdgYr3kF6L-LGr8aA
description: 把 Super Agent 的六模块架构转成可执行的设计流程、可打分的评审判据、可跑通的最小骨架，以及可套用的事件分发规则与决策门槛模板。适用于判断要不要上双层架构、设计六模块、评审已有方案、测算上下文预算、设计事件分发与去重、配置决策门槛、生成最小骨架。以下场景不适用于本 Skill：一次性脚本、纯提示词调优、离线批处理、模型训练侧优化、通用代码审查、文档转换。
author: 小浣熊肖恩
license: MIT-0
category: 开发工具
subcategory: AI 系统架构
tags:
- super-agent
- multi-agent
- router-worker
- agent-architecture
- event-driven
- watchdog
- context-engineering
triggerKeywords:
- Super Agent
- 超级智能体
- 双层架构
- Router Worker
- 多会话 Agent
- 事件驱动 Agent
- Agent 架构评审
- 反模式诊断
- 上下文预算
- 投机执行
- Watchdog
- 存算分离
modes:
- assess
- design
- review
- scaffold
compatibility:
- WorkBuddy
- Claude Code
- Codex CLI
entry: scripts/init_prototype.py
emoji: 🕸️
slug: super-agent-architect
user-invocable: true

Super Agent 架构师

不可突破的红线

1. 先判断该不该上，再谈怎么上。 单任务、单次、无并发、无事件源的需求，必须直接给"不需要 Super Agent"的结论并说明代价。把简单需求包装成六模块方案属于误用。
2. 六模块缺一不得标"设计完成"。 Router/Worker 分层、Trigger 生命周期、人机交互契约、上下文组织、存算与环境分离、Watchdog 自愈，六个都要有落点。可以标"本期不做"，但必须写明降级后果。
3. 不把 Session 当成交付给用户的认知负担。 任何要求用户自己记住"去哪个会话问"的设计判为不合格。Session 是系统实现细节。
4. Router 层不挂执行工具。 尤其不挂 shell。Router 一旦能动手，双层结构就退化回单层，上下文隔离与并发吞吐同时失效。
5. Worker 不直接对外发言。 所有对人类输出经 Router 统一出口。允许多信道格式差异，不允许一个事件触发多个会话各自回复。
6. 上下文必须给数字。 Inline/Spill 要给 token 预算、要算命中率。不接受"上下文够用""注意精简"这类定性表述。
7. 凭据不进模型上下文。 需要认证的动作走句柄或本地代理，让模型只知道"有一个可用凭据"，不知道值。云端路由 + 端侧 daemon 的部署形态下，这一条是硬门槛。
8. 评审只给可验证结论。 每条"通过"必须附判定依据（配置项、代码位置、实测数字）。无法取证的一律标"未验证"，不许折算成通过。

一、核心能力速查

何时使用

• 判断现有 Agent 系统要不要改成多会话双层架构
• 设计六模块架构，要一份含分层、事件流、交互契约的落地文档
• 评审已有 Agent 方案，要四维评分、反模式诊断与整改清单
• 上下文窗口不够用，要算 Inline 与 Spill 该怎么分配
• 设计事件怎么分发、重复推送怎么去重、什么情况该推给人拍板
• 生成一个能离线跑通的最小骨架，验证 Thread 直通与批处理到底省不省 token

二、标准工作流程

前置：三个必答问题

动手前先拿到这三个答案。用户没给就按最保守默认值假设，并在交付物里显式标注"假设值"。

1. 事件从哪来？ IM 群、GitHub PR、邮件、CI、日历、定时器。没有任何持续事件源的，直接判"不该上"。
2. 同时在跑几件事？ 稳定超过 3 件才具备双层架构的收益。低于 3 件，单会话加子代理就够。
3. 人在哪里验收？ 即时通信（要短、要快）还是异步信道（要完整、可追溯）。这决定交互契约，不决定架构。

步骤一：判定适配（mode: assess）

走 references/workflow.md 的四问判定树。输出三段：结论、依据、替代方案。结论只有三种：RECOMMENDED / DEFER / NOT_APPLICABLE。

步骤二：抽事件与 Thread 拓扑

把每个事件源映射成 Thread key（如 im:#group-42、github:pr-1287）。画一张"事件源 → Thread → 订阅关系"的表，标出哪些 Thread 会被高频更新（这些走直通），哪些是低频新事件（这些留在 Router 慢路径）。

步骤三：定分层与模型档位

Router 用轻量模型（它只做任务间关联与分派，不读实现细节）。Worker 用最强模型（它扛完整执行）。这一条直接决定成本结构，写进设计文档的成本表里。

步骤四：设计 Trigger 生命周期

四段全要落到配置项：两级过滤（代码级 allowlist/denylist + LLM 语义判断）、订阅直通（含退订回退）、上下文三步组织（含链式召回深度上限）、投机执行（触发信号 + 丢弃条件）。

再加一条：去重。幂等键用 source + object_id，同一幂等键在窗口内只允许一条 running，新到的事件合并进同一任务而不新开。去重不做，同一件事会有多个 Worker 并发改，互相覆盖。

规则分发的字段定义见 assets/templates/rules.example.json。

步骤五：定人机交互契约

按信道分别写死规格。IM 单次回复不超过 100 词，只在需要决策或验收时说话。异步信道用"背景/改动/验证"三段式。一份契约表，写清每个信道谁说话、说多长、带不带附件。

同时定打扰分级：silent 不主动说、needed 只在需决策时说、always 无条件上报。默认必须是 needed，默认打扰人是设计事故。什么算"需决策"不能凭感觉，要有枚举清单，见 assets/templates/decision-gates.example.json。

步骤六：存算分离与自愈

Agent Loop 无状态，状态全落 store（给出 session schema）。端侧只放不保存会话状态的轻量 daemon。Watchdog 独立于主系统，定时消息驱动，既查进程存活也查任务进展与目标偏离。

交付链路要补五步闭环：审查（只读、不报风格、最多 3 轮）→ 检查（一次性环境）→ 合并（硬规则，任何工具绕不过）→ 发布（独立环境）→ 核实（回线上确认版本真的包含本次改动）。少了第五步，等于把"以为上线了"当成"上线了"。详见 references/production-practice.md。

步骤七：评审打分（mode: review）

用 references/architecture-blueprint.md 的评分卡。四大特征各 25 分，逐项给依据。低于 60 分不给"可以上线"的结论。命中 P0 反模式的，无论总分多少一律打回。有未验证项的，结论最高给"有条件通过"。六模块整块缺失的，直接退回，不参与总分换算。

步骤八：生成骨架并跑通（mode: scaffold）

python scripts/init_prototype.py --out <目标目录> --name <项目名>
cd <目标目录> && python run_demo.py

demo 必须退出码 0，且能看到直通计数、批处理 batch_size、IM 回复字数校验、Watchdog 介入记录四项输出。看不到就是骨架没接对。

三、任务状态机

流转规则：

• ASSESSING 结论为 NOT_APPLICABLE 时直接进 DELIVERED，交付物换成"不该上的理由 + 替代方案"。
• REVIEWING 命中 P0 反模式必须退回 DESIGNING，不允许带伤进 SCAFFOLDING。
• 任意状态检出红线违反，立即回退到上一个稳定状态并在报告里记一条违规。

恢复规则：BLOCKED 状态超过一轮未解除，输出当前可得的部分结论并把缺口列成问题清单，不要空转等待。

四、数据合规与安全

权限声明

本 Skill 的运行时权限（见 front matter allowed-tools）：

不申请的能力：不读取家目录、不访问浏览器登录态、不安装依赖、不修改系统配置。

五、性能与容量

响应基线（源自公开消融实验，合成负载，仅作量级参考）

容量结论

• 直通机制不提升完成速度，但省 Router 推理开销。 数据上省下约四分之一到三分之一的 token，属于纯收益，没有理由不做。
• Router 批处理是吞吐杠杆。 触发速率从 1 条/分钟升到 40 条/分钟时，平均 batch 从 1.0 涨到 2.8，单次请求耗时仅从 2.5 秒涨到 3.9 秒，单决定分摊时间从 6.4 秒降到 1.6 秒。拥堵时合并积压，有效吞吐反而上升。
• Router 层不要过早水平切分。 在十余人规模下，切分换来的吞吐远小于丢失的全局上下文连续性。

响应矩阵

六、交付形态

标识规范：每个 Worker 用 w-<thread-slug>，每个 Thread 用 <source>:<raw-id>，每条 Trigger 用 t-<6位序号>。详见 references/naming-conventions.md。

对话式回复的格式契约

不管是"先聊两句"还是正式交付，同一套结构，避免长篇散文：

1. 第一行给结论或判断，一到两句，不铺垫。
2. 接着给要点，3 到 5 条，用列表，每条一句。
3. 需要人补信息时，一次只问 2 到 3 个问题，问最关键的，不列问卷。
4. 收尾给一行下一步动作，说明由谁做什么。

理由：结构化回复让人能跳读，也让后续归档能直接切分。散文式长段落既难扫读，也无法自动解析。

七、交付前自检

结构完整性
- [ ] 六模块全部有落点，"本期不做"的写明降级后果
- [ ] 三张图齐全：分层图、事件流图、状态图
- [ ] 配置项与设计条目一一对应，没有"文档里有、配置里没有"

数字可验证
- [ ] 上下文预算给了 token 数与 Spill 阈值
- [ ] 成本表给了 Router/Worker 的模型档位与调用量估算
- [ ] 评审打分每项附依据，无依据的标"未验证"

边界诚实
- [ ] 明确写了"不该上"的反向条件
- [ ] 明确写了已知简化点与未实现项
- [ ] 凭据与信任边界有单独一段

可运行性
- [ ] run_demo.py 退出码 0
- [ ] 四项关键输出可见：直通计数、batch_size、IM 字数校验、Watchdog 介入
- [ ] 零第三方依赖（grep 无 requests/yaml/openai）

八、不适用场景

以下六类请求不属于本 Skill 的范围，遇到应当直接说明并给出该走的路，不要硬套六模块：

• 帮我写个 Python 脚本批量重命名这批图片
• 这个提示词怎么写效果更好
• 帮我把这批文件跑一遍批处理，跑完要结果
• 帮我训练一个文本分类模型
• 帮我把这份 PDF 转成 Word
• 帮我查一下明天澳门的天气

需要注意区分的是「看起来像不适用、其实属本 Skill 范围」的情况：只有一两个人的团队问要不要上多会话架构，仍应走适配判定并给出 DEFER 结论与观察指标，不能因为规模小就劝退不接。

九、常见问题 FAQ

Q1：Router 也要用强模型吗？
不要。Router 只处理任务之间的关联与分派，不读实现细节。用轻量模型，成本能降一个量级。它一旦开始深入推理某个任务，说明分派边界画错了。

Q2：Worker 之间要不要互相通信？
默认不要。让多个 Worker 订阅同一个 Thread，各自收到相同事件，冲突自行收敛。真正需要跨任务协同的少数场景由 Router 中转并留痕，不要让 Worker 之间直连。

Q3：上下文窗口到底怎么省？
三步走：先只给 id 和摘要；再按局部性补紧密关联的对象 id 和时空相邻内容；超上限就截断，保留续读入口。每一步都要算 token。链式召回是这条路径上的导航，不是无限展开的许可证。

Q4：直通会不会让 Router 失去全局视野？
不会丢视野，只丢转发动作。Router 仍然观测所有事件用于决策，直通只是把"已经订阅的 Thread 的后续事件"直接投给 Worker，省掉一次路由往返。

Q5：投机执行会不会浪费算力？
会，但换的是人的等待时间。规则是"有价值就交付，无价值就丢弃"，且必须全程静默。典型配置是"静默复现并修复"：确认能复现且找到简单修法才开口，否则一句话都不说。

Q6：Watchdog 和普通健康检查有什么区别？
普通健康检查看进程活没活。Agent 的多数故障是进程活着但模型陷入无效循环或偏离目标，所以 Watchdog 必须判进展与方向。它由定时消息驱动，构成主系统之外的控制回路，不能做成主系统内部的一个定时任务。

Q7：异步 start/stop 是不是必须？
如果你的 Agent 要边跑长任务边接新指令，就是必须。经典同步 ReAct 会阻塞到工具返回，人在等。改成 start 立即返回、结果作为新事件回灌，前台对话和后台执行才解耦。

Q8：什么时候该给 Router 做水平切分？
规模信号而不是直觉信号：单次批处理已经压不住、Router 的排队延迟成为主瓶颈时才考虑。切分越细吞吐越高，全局上下文连续性越低，这个交换要拿数据支撑。

Q9：骨架能直接上生产吗？
不能。骨架里的工具全是 mock，模型是确定性桩，没有鉴权、没有限流、没有持久化迁移。它的用途是验证分层与事件流是否接对，生产化要重写工具层、存储层与部署层。

Q10：这套东西和 Agent Team 有什么区别？
Agent Team 解决单任务内的步骤拆解与角色协作，Lead 需要深入理解任务细节。Super Agent 的 Router 只解决任务之间的分派，不碰任务内部。两者不冲突，一个 Worker 内部完全可以是一个 Agent Team。

十、参考文件