企业官网建设流程全解析

Sim 仓库 council 技能深度解析：多智能体并行探索（Fan-out Exploration）模式实战指南

【免费下载链接】simSim is the collaborative workspace to build, deploy, and monitor AI agents and workflows. Used by 100,000+ builders.项目地址: https://gitcode.com/GitHub_Trending/sim16/sim

本指南围绕 Sim 仓库中的.agents/skills/council/SKILL.md展开，系统讲解"council（议事会）"这一元探索技能的设计意图、Frontmatter 规范、三步执行协议与 Plan Mode 分支，并结合仓库内 scripts/sync-skills.ts、cleanup、ship 等源码佐证其底层机制。读完你将掌握：如何在跨大量文件的宽泛任务中，通过"初探 → 并行 fan-out 任务智能体 → 汇聚收敛"的协议高效组织多智能体协作，以及 Sim 仓库如何通过技能同步脚本将 SKILL.md 分发给 Claude 与 Cursor 等不同 Agent 客户端。

council 是什么：定位为"元探索工具"而非服务集成器

在 Sim 仓库的.agents/skills/目录下，共维护了 40 个技能（skill），按用途可分为三类：

• 功能构建型技能：如add-tools、add-block、add-connector、add-trigger、add-model，用于为 Sim 集成创建工具、块、触发器、模型等具体产物，多数带有agents/openai.yaml独立 Agent 卡片；
• 质量审查型技能：如you-might-not-need-state、you-might-not-need-an-effect、memory-load-check、react-query-best-practices，针对具体反模式做分析与修复；
• 元（meta）技能：如council、cleanup、ship、you-might-not-need-*系列，它们不直接产出业务代码，而是编排其他技能或智能体的协作流程。

council属于典型的元技能。其 Frontmatter 中的description给出了精确定义：

Spawn parallel task agents to explore a given area of the codebase from multiple angles, then use their findings to answer the question or build a plan. Use when a task needs broad fan-out exploration across many files before acting.

翻译过来即：并行派生出多个任务智能体，从多个角度探索代码库中给定的兴趣区域，再用它们的发现回答问题或构建计划。适用场景是"行动之前需要在大量文件间做宽泛扇形展开（fan-out）探索"的任务——例如"这个错误可能由哪些模块导致""重构某个核心流程会影响哪些调用方""新功能应该落在架构的哪一层"这类需要覆盖面广、视角多元的问题。

值得注意的是，council的 Frontmatter 里有一段设计注释，直接点明了它的定位：

No agents/openai.yaml by design: council is a meta/exploration utility (like cleanup, ship, you-might-not-need-*), not a service-integration builder, so it intentionally ships no standalone agent card.

即：council 有意不提供agents/openai.yaml，因为它与cleanup、ship、you-might-not-need-*一样是元/探索工具，而非服务集成构建器，因此刻意不随附独立 Agent 卡片。这一点是理解其定位的关键。

Frontmatter 规范：name、description、argument-hint

与仓库中所有 SKILL.md 一样，council使用 YAML Frontmatter 声明元数据。完整的 Frontmatter 如下：

--- name: council description: Spawn parallel task agents to explore a given area of the codebase from multiple angles, then use their findings to answer the question or build a plan. Use when a task needs broad fan-out exploration across many files before acting. argument-hint: <area-of-interest> # No agents/openai.yaml by design: council is a meta/exploration utility (like cleanup, ship, you-might-not-need-*), not a service-integration builder, so it intentionally ships no standalone agent card. ---

对照 scripts/sync-skills.ts 中loadCanonicalSkills与parseSkill的解析逻辑，可以看出这套 Frontmatter 是被脚本强制校验的：

• name：必须与技能目录名完全一致，否则脚本直接抛错（frontmatter 'name' must equal the directory name），council目录因此必须声明name: council；
• description：必填字段，缺失即报错（missing 'description' in frontmatter）。它同时充当两个角色——人类可读的功能摘要，以及sync-skills.ts同步时被完整保留的投影内容；
• argument-hint：可选，为调用方提示技能参数形式。council的提示为<area-of-interest>，即用户需要提供一个"兴趣区域"（例如某个功能模块、某段错误日志、某个待重构的子系统）；
• #注释：Frontmatter 块内的注释行同样会被解析器保留。sync-skills.ts的parseSkill仅要求文件以---\n开头并找到结束的\n---\n，中间行不强制键值结构，因此这段设计说明注释会原样保留在投影中，成为分发到各客户端后的上下文说明。

三步执行协议：初探 → fan-out → 汇聚

council的执行流程由正文中的三段指令定义，构成一个完整的"探索-并行-收敛"协议：

Based on the given area of interest, please: 1. Dig around the codebase in terms of that given area of interest, gather general information such as keywords and architecture overview. 2. Spawn off n=10 (unless specified otherwise) task agents to dig deeper into the codebase in terms of that given area of interest, some of them should be out of the box for variance. 3. Once the task agents are done, use the information to do what the user wants. If user is in plan mode, use the information to create the plan.

第一步：主智能体初探（Dig Around）

在派发任何子智能体之前，主智能体先围绕用户给定的<area-of-interest>亲自在代码库中"挖一圈"，目标是建立关键词集合与架构概览两级粗粒度认知：

• 关键词（keywords）：从兴趣区域中提取与代码库内标识符（函数名、类型名、目录名、常量名）可对应的检索词，为后续子智能体的定向搜索提供锚点；
• 架构概览（architecture overview）：判断该区域在 Sim 整体架构中的位置。仓库根目录的 AGENTS.md 给出了顶层结构（apps/sim为 Next.js 应用，含app/、blocks/、executor/、lib/、tools/、triggers/等子目录；packages/下为@sim/db、@sim/utils等共享包），这一步的价值是让主智能体先形成"兴趣区域落在哪一层、可能涉及哪些包边界"的判断，再决定 fan-out 的方向与数量。

这一步与sync-skills.ts无关，属于技能运行时行为；但它决定了第二步 fan-out 的质量——初探越准确，子智能体的分工越有效。

第二步：并行派发 n=10 个任务智能体（Fan-out）

这是council的核心机制，也是最值得展开的设计点：

• 默认并发数为 10：Spawn off n=10 (unless specified otherwise)。调用方可通过显式指定覆盖默认值，例如在参数中声明更小或更大的并发数，以适配任务规模与上下文预算；
• 强调多样性（variance）：some of them should be out of the box for variance——要求部分子智能体"跳出常规视角"（out of the box），刻意采用非典型切入角度。这是为了避免 10 个智能体从同一角度出发、产出高度同质化的重复发现，牺牲探索覆盖面换取答案的多样性；
• 并行执行：所有子智能体在同一轮中并发运行，互不等待、互不依赖，各自独立深挖兴趣区域的某一侧面，最后统一汇总结果。

这一"多角度并行、刻意混入异质视角"的模式，与仓库中另一个元技能cleanup的"并行分析"阶段异曲同工——cleanup会在单条消息里同时派发 8 个 pass（effects、memo、callbacks、state、React Query、emcn、url-state、comments）作为子智能体并行分析同一 scope，再进入汇聚与应用阶段。两者的差异在于：cleanup的并行体是固定编排的 8 个预定义 pass，council的并行体则是根据兴趣区域动态生成的 n 个自由探索智能体。

第三步：汇聚收敛与应用

所有任务智能体完成后，主智能体收集全部发现，据此执行用户的实际诉求：

• 用户提出的是问题 → 用汇聚后的信息回答问题；
• 用户提出的是任务 → 用汇聚后的信息构建行动计划；
• 用户处于Plan Mode（规划模式）→ 用汇聚后的信息创建计划（If user is in plan mode, use the information to create the plan）。

Plan Mode 分支是一个显式的行为开关：同样的探索流程，在普通模式下输出答案或方案，在 Plan Mode 下则输出结构化的实施计划，供用户确认后再进入执行阶段。这与cleanup的fix=true|false参数设计思路一致——把"分析"与"动手"分离，探索/分析阶段只读、不修改，是否落地由调用方决定。

参数化与调用约定：argument-hint 与 $ARGUMENTS

council通过argument-hint: <area-of-interest>声明其唯一参数：兴趣区域。调用形态如：

/council <area-of-interest>

<area-of-interest>可以是任意可定位的探索范围描述，例如：

• 一个功能模块名："undo-redo 功能";
• 一段架构问题："工作流执行引擎中 DAG 的依赖解析";
• 一个待排查的现象："知识库连接器下载超大文件时的内存行为";
• 一个重构目标："把工具执行边界迁移到 InternalToolConfig.operation"。

对比仓库中其他技能的参数约定可以看出其设计差异：cleanup使用[scope] [fix=true|false]结构并在正文中用$ARGUMENTS解析（.agents/skills/cleanup/SKILL.md），而council保持极简——一个兴趣区域即可驱动整套 fan-out 流程，n值仅在用户显式指定时覆盖默认的 10。

设计决策：为什么 council 刻意不带独立 Agent 卡片

在.agents/skills/下，功能构建型技能普遍携带agents/openai.yaml。例如 .agents/skills/add-tools/agents/openai.yaml 的内容为：

interface: display_name: "Add Tools" short_description: "Build Sim tools from API docs" brand_color: "#EA580C" default_prompt: "Use $add-tools to create or update Sim tool definitions from service API docs."

这类 Agent 卡片为技能提供面向 LLM 平台的独立展示（显示名、短描述、品牌色、默认提示词），使其可以作为独立 Agent 被直接调用。

而council明确不提供该文件，理由在 Frontmatter 注释中写得很清楚：它是元/探索工具（与cleanup、ship、you-might-not-need-*同类），不是服务集成构建器。从仓库结构可以推断其深层逻辑：

1. 元技能的价值在于被编排，而非被独立部署：council由主智能体在任务开始时调用，作为"探索前置阶段"存在，本身不产出可交付的集成产物，因此不需要以独立 Agent 形态面向用户；
2. 避免 Agent 卡片的语义错配：add-tools的 Agent 卡片描述的是"构建工具配置"这一具体产出；若为council配备卡片，会暗示它可独立完成某项业务交付，与其"探索辅助"的真实角色冲突；
3. 与姊妹元技能保持一致的仓库约定：同样作为元技能的cleanup、ship、you-might-not-need-*系列均无agents/openai.yaml，council遵循同一约定。

技能分发机制：sync-skills.ts 如何让 council 到达各客户端

理解council的另一个关键维度，是 Sim 仓库如何管理技能文件的分发。scripts/sync-skills.ts 定义了完整的投影（projection）机制：

• 规范源（canonical source）：.agents/skills/<name>/SKILL.md是唯一权威来源，Frontmatter 只允许name、description、可选argument-hint及正文；
• Claude 投影：.claude/skills/<name>是指向完整规范技能目录的符号链接（symlink），这样 Claude 客户端能拿到完整技能目录，包括council这类技能可能附带的所有资源；
• Cursor 投影：Cursor 直接发现.agents/skills，因此无需投影，这也是council等技能在 Cursor 侧零成本可用的原因；
• 废弃清理：旧的.claude/commands/<name>.md与.cursor/commands/<name>.md投影在同步时被删除，在--check模式下视为过期；
• 孤儿链接清理：findOrphanedClaudeLinks会找出规范技能已不存在但.claude/skills中残留的符号链接并移除。

实际使用命令（定义于仓库根目录 package.json）：

# 写入/修复所有技能投影 bun run skills:sync # 只检查投影是否过期（过期则 exit 1，供 CI 使用） bun run skills:sync --check # 或 bun run check:skills

对应脚本内部实现：

bun run scripts/sync-skills.ts # write projections bun run scripts/sync-skills.ts --check # fail (exit 1) if any projection is stale

校验逻辑还包含一条强约束：每个 SKILL.md 必须以---\n开头且包含终止的\n---\n，name必须等于目录名，description必须存在——council的 SKILL.md 正是完全符合此规范的示例（.agents/skills/council/SKILL.md）。

实战场景与使用建议

综合上述机制，council在 Sim 仓库中的典型使用方式可归纳如下：

何时用 council：

• 任务涉及跨多个目录/包的理解，单一线性检索容易遗漏关联（如"评估把 X 模块迁移到 Y 架构的影响面"）；
• 需要多视角交叉验证结论（如排查一个可能由前端、执行引擎或持久化层共同导致的问题）；
• 行动前需要一份基于全库证据的探索报告或实施计划，尤其是用户处于 Plan Mode 时。

何时不用 council：

• 任务目标明确、范围集中在单文件或单目录，直接阅读与编辑即可；
• 任务需要的是确定性产物（如新增一个工具配置），应使用add-tools等功能构建型技能；
• 任务是对既有改动做质量审查，应使用cleanup（固定 8-pass 并行分析 + 顺序应用）而非自由探索。

调用模板：

/council 兴趣区域描述 [可选: 指定子智能体数量 n]

例如：/council knowledge-connector 文件下载的字节上限与失败处理会触发主智能体先建立关键词（CONNECTOR_MAX_FILE_BYTES、readBodyWithLimit、stubOrSkipBySize等）与架构概览，再并行派发 10 个智能体从不同角度深挖（默认值 10，可覆盖），最后汇聚成一份完整分析或行动计划——这正是仓库内memory-load-check等技能所关注的内存边界问题在探索阶段的理想前置步骤。

小结

council是 Sim 仓库中一个设计精炼的元探索技能：它以极简的 Frontmatter（name/description/argument-hint）声明接口，以"初探 → 并行 fan-out n=10 个智能体（含异质视角）→ 汇聚收敛"的三步协议组织多智能体协作，并通过 Plan Mode 分支将探索结果与执行决策解耦。它刻意不配备独立 Agent 卡片，与cleanup、ship等元技能共同构成仓库的"编排层"；而 scripts/sync-skills.ts 则保证council的规范源能通过符号链接投影到 Claude、被 Cursor 直接发现，并在 CI（bun run check:skills）中保持各客户端技能面一致。理解这套机制，你就掌握了 Sim 仓库中"大规模探索任务"的标准打开方式，也能将其中的 fan-out 模式复用到自己的多智能体工作流设计中。

【免费下载链接】simSim is the collaborative workspace to build, deploy, and monitor AI agents and workflows. Used by 100,000+ builders.项目地址: https://gitcode.com/GitHub_Trending/sim16/sim