15-swarm — Swarm 全家深度拆解（第二轮 · 明星技能组）

← 返回主报告：Kimi Agent（云端沙箱）技术报告 ｜ GitHub 原文

合规与风险声明：本报告为安全研究与互操作学习目的的逆向分析，全程只读采集，未对目标系统做任何修改；文中所有密钥、token、账号级标识（chat_id / project_id / tenant_id 等）均已脱敏；沙箱内发现的默认弱口令（VNC/SSH）属平台侧配置，仅作安全发现披露，请勿用于访问任何不属于自己的系统。docx/pdf/xlsx/kimi-slides 等引擎二进制为 Moonshot 专有许可（禁再分发/逆向），本文仅作行为级描述。报告基于单次分析窗口（约 50 分钟生命周期），软件版本与技能库存随镜像更新可能变化。

采集时间：2026-08-18 ｜ 采集方式：HTTP 只读 http://127.0.0.1:18080/app/.agents/skills/（本轮 SSH 不可用） 范围：swarm-workspace、vibecoding-general-swarm、vibecoding-webapp-swarm、webapp-building-swarm、backend-building-swarm、skill-creator-swarm、deep-research-swarm、batch-download 共 8 个技能的全部关键文件（SKILL.md 全文、scripts 逐行、references/docs 全文、模板结构）。 与第一轮关系：sections/09-skills-d.md §2 已给出四层体系速写；本章为全文级深拆 + 移植评估，结论如有出入以本章为准。

0. 一句话结论

这套 swarm 体系的本体是一份”用 git 当消息总线”的多代理协作协议：基础设施只有 105 行 bash（setup-local.sh），其余全是提示词层纪律（角色模板逐字锁定、缝合点冻结、反验证螺旋）。真正的平台耦合点只有三个：/mnt/agents/output 共享盘、mshtools-website_version_manager 交付工具、http://localhost:8080/api/v1/apps portal 供应接口——三者都有清晰边界，替换后整套协议可原样搬走。

1. 分层关系（实测确认）

编排层   vibecoding-webapp-swarm (415行, 主乐谱) ──► vibecoding-general-swarm (73行, 泛化骨架)
         deep-research-swarm (509行, 研究编排)     batch-download (269行, 下载编排, type: capability)
基础设施层 swarm-workspace (68行 + setup-local.sh 105行)  ← 唯一权威 worktree 实现
制品层   webapp-building-swarm (98行, type: artifact + 13套模板zip + 预构建node_modules)
         backend-building-swarm (333行 + init.sh 674行 + 9个.mjs patcher + 6篇docs + base/db/auth三层模板)
评估层   skill-creator-swarm (490行 + init/validate/package 三脚本)  ← 用 swarm 评测 swarm 时代的技能

调用关系证据链：vibecoding-webapp-swarm 的 SKILL.md “Companion Skills” 段显式引用其余四个技能的绝对路径；backend-building-swarm SKILL.md 自述 “The end-to-end sequencing is owned by vibecoding-webapp-swarm (the backend graft is its Phase 4.5)”；webapp/backend 两个制品层 SKILL.md 都把 worktree 生命周期委托给 swarm-workspace（”This is the ONE canonical implementation — webapp-building-swarm and backend-building-swarm delegate to it via thin wrappers that only set NODE_MODULES_SRC” —— setup-local.sh 头部注释原文）。

2. swarm-workspace：双层文件系统契约（基础设施层）

2.1 契约本体（SKILL.md 68行全文已读）

路径角色规则
/mnt/agents/output/app共享协调 git 仓（无 remote）只做 branch/merge，禁止编辑/构建
$HOME/app-每子代理本地 worktree（快盘）每个并行子代理必须唯一路径

三条由布局直接推出的关键事实（原文摘录）：

  • “No remote, no push. All worktrees share the shared repo’s .git object store, so a commit on any branch is immediately visible to the main agent — it just git merge from inside the shared repo.” —— git 对象库替代 IPC/消息队列，这是全套机制的核心取巧点。
  • “node_modules, dist, and .env are gitignored… that is why setup-local.sh copies node_modules (and optionally .env) in.” —— gitignore 即隔离边界，git 不管的东西走文件复制管道。
  • “Never run git worktree prune” —— 所有代理的 worktree 元数据共享 .git/worktrees/，prune 会摧毁同伴。

2.2 setup-local.sh 105 行逐段解读

签名：[REPO_PATH=] [NODE_MODULES_SRC=] [ENV_SRC=] setup-local.sh [local-path]，set -euo pipefail 开局。

  • L47-55 参数与环境：REPO_PATH 默认 /mnt/agents/output/app；LOCAL_PATH 默认 $HOME/app-$BRANCH。最精巧的是 L51-55 ENV_SRC 的默认值设计：默认指向 $REPO_PATH/.env——即 backend graft 阶段”暂存”（staged）到共享仓的 .env。注释原文：”so any worktree — including ad-hoc backend passes that don’t pass ENV_SRC — inherits DATABASE_URL etc. Without this, npm run db:push in such a worktree fails with ‘DATABASE_URL is required’. copy_env() no-ops when the file is absent.” .env 是 gitignored 的，不走 git；把它放进共享仓（git 追踪之外）就变成一个”密钥信箱”，后续每个 worktree 自动继承——这是整套协议里最妙的一笔。
  • L57-62 copy_env()：ENV_SRC 非空且文件存在才 cp 到 $LOCAL_PATH/.env，否则静默跳过（纯前端项目无 .env 时不报错）。
  • L69-87 已存在目录的三态处理（重入语义，全部有代码佐证）：
  1. 是 worktree 且分支相同 → 复用、刷新 .env、跳过 npm install、exit 0（L73-78）；
  2. 是 worktree 但分支不同 → git worktree remove --force（失败则 rm -rf）后走重建（L80-82）；
  3. 非 git 残留目录 → rm -rf 重建（L84-85）。

注意 L71 的检测技巧：worktree 的 .git 是文件（gitdir 指针）不是目录，所以用 -e 而非 -d，并加 git rev-parse --git-dir 双保险。

  • L92 创建：git worktree add --force "$LOCAL_PATH" "$BRANCH"。--force 的理由写在 L90 注释：”handles stale entries from dead sandboxes”——子代理沙箱是易消亡的（ephemeral），死沙箱留下的 worktree 元数据残留被显式设计进恢复语义。
  • L98-103 依赖安装：有 NODE_MODULES_SRC 就 cp -r 覆盖（预构建 node_modules，镜像构建期准备，运行时零下载冷启动），然后仍然跑 npm install 对齐——因为页面代理可能各自加了包，最终 merge 后还需再 install 一次（见 Phase 7 step 4 的注释 “setup-local.sh installs before later branches are merged, so this final install reconciles subagent dependency changes”）。
  • 它不管的事：共享仓的创建（”Creating it … is the job of whatever workflow lays the first template — not this skill”，L64-68）——职责切得很干净。

工程质量评价：105 行覆盖了幂等重入、脏目录恢复、死沙箱残留、密钥继承、快盘/慢盘分层六个真实工程问题，无任何 LLM/runtime 依赖，纯 git+bash+npm 原语。

3. vibecoding-webapp-swarm：编排层主乐谱（SKILL.md 415行全文已读）

固定技术栈写死在 frontmatter 之后第一段：Node 20 / Tailwind v3.4.19 / Vite v7.2.4 / React 19+TS / shadcn/ui（版本钉死，且要求”communicate to all subagents”——每个子代理提示词都必须带版本号）。

3.1 七阶段流水线（Mode A）

  • Phase 1 主代理：跑 init-webapp.sh（PROJECT_PATH=$HOME/init REMOTE_PATH=/mnt/agents/output/app），研究结果写 /mnt/agents/output/info.md。硬约束：”Do NOT plan page structure, page count, visual direction, or design details in this phase. Those decisions belong entirely to the Designer.” —— 主代理在此阶段被明确剥夺创意权。
  • Phase 2 设计：创建名为 Pro_Designer 的子代理。关键证据：“name must contain ‘designer’ (case-insensitive) for model routing” —— 子代理名称字符串参与 runtime 的模型路由（设计师角色路由到不同/更强的模型），这是沙箱 runtime 的隐藏契约，提示词里被当成硬性约定使用。
  • Phase 4 脚手架代理（单个子代理）：提示词 16 条逐字条款，含 AI 媒体资产生成（”use the image generation tool… Save all generated media to $HOME/app-scaffold/public/“）、共享组件路径写死（src/components/Navbar.tsx|Footer.tsx|Layout.tsx）、Layout/路由契约（<Outlet/> 嵌套路由 vs {children} 包裹，二选一禁止混用）、全栈时 Login.tsx 只做占位 + Navbar 里埋 {/ AUTH-SLOT: rewired to useAuth() in Phase 5 /} 注释锚点。
  • Phase 5 backend graft 由主代理亲自跑（不开子代理）。原因写得很白：”because init.sh writes a gitignored .env that never travels through the merge: it survives only in the sandbox where it ran, which must be the main agent’s own”。跑完 cp $HOME/app-backend/.env /mnt/agents/output/app/.env 暂存，然后才从 master 派生页面分支——保证页面代理继承脚手架 + tRPC client。
  • Phase 6 并行页面代理：”Launch all subagents simultaneously (single message, multiple task tool calls)”。每代理 13 条硬性条款，核心是缝合点冻结清单：

> “Must NOT modify: src/App.tsx, src/index.css, shared components, public/. Full-stack: also must NOT modify api/router.ts or db/schema.ts — these are merge-conflict seams owned by the backend graft/product pass. *Auth apps: also must NOT create or modify src/pages/Login.tsx, src/hooks/useAuth.ts, src/const.ts, src/components/AuthLayout.tsx, src/providers/trpc.tsx, or anything under api/**”

  • Phase 7 主代理收口：final-build worktree 里 octopus merge（git merge g1 g2 ... --no-edit，失败则退化为逐个 merge）→ 手工接线 App.tsx 路由 → grep 契约检查（grep -nw "fixed" Navbar.tsx 查定位契约；全栈 auth 时 grep -rn "oauth/authorize" src/ | grep -v Login.tsx 必须为空、grep -n 'scope' Login.tsx 必须是 “profile”）→ npm install && npm run build 成功（最多 3 次重试）→ 才允许调 mshtools-website_version_manager 的 build_version。

3.2 反验证螺旋纪律（全套技能反复出现的失效模式对策）

  • 子代理条款第 16/13 条逐字：”After committing, return immediately. No need to run the dev server, open a browser, take screenshots, or verify your work.”
  • 主代理 Core Principle 7：”Create the version once per delivery and STOP. One build_version call per delivery, then no verification loop: do NOT open the URL, take screenshots, or review.”
  • 版本工具本身设计成 git-native 闭环：build_version = 把 project_dir 状态 commit（版本 ID = commit 短哈希）；rollback = 恢复树再 commit（roll-forward，不改写历史）——用 git 语义锁死”交付后不许再动”。

3.3 static vs dynamic 双交付路径

build_version 的 project_dir 指向随 type 分叉：static（纯前端）必须指向 /mnt/agents/output/app（平台从那里构建，merge 即交付）；dynamic（全栈）必须指向带 node_modules+.env 的 worktree（服务端构建并起 dev server 预览）。迭代纪律：master 是唯一持久谱系，修 bug/回滚一律从 master 新派分支+新 worktree，禁止复用旧 worktree（”a reused worktree is stale relative to master… can fold leftover debris into the version tool’s commits”）。

3.4 角色模板与”防污染”设计

Designer 的 system prompt 和 task prompt 都是逐字固定模板，只允许填 {USER_QUERY} 和 {RESEARCH} 两个占位符，且三条明令：”Do NOT add sections like ‘Key Context’…”、”Do NOT add your own creative interpretation…”、”Do NOT paraphrase the user request — copy it character-for-character.” —— 把所有创意决策压给 Designer 单一角色，防止主代理的规划冲动污染设计。这是多代理系统里”主代理职权最小化”的教科书式写法。

3.5 三个 references 文件（全文已读）

  • design-guide.md（90行）：Designer 专用。视觉能力清单（GSAP/Framer/Three.js/Lenis）、性能护栏（每视口 ≤8-10 个同时动画元素、每 section 只许一个重 shader）、设计文档格式（全局 design.md + 每页 [page].md，每 section 必须有具体参数的 Animation 字段）、Asset Manifest 契约（Designer 只写资产清单不生成资产，生成是 Scaffold 代理的活——职责分离写进文档 “What You Do NOT Do”）。
  • react-dev.md（216行）：所有实现代理（scaffold+页面）必读，Designer 和主代理不读——阅读权限也按角色分配。内容是被实战打磨过的 React 陷阱清单：GSAP/Framer 库隔离（同组件树禁止混用）、Framer 性能规则（高频动画禁 useState 用 MotionValue）、min-h-[100dvh] 替代 h-screen、canvas 尺寸必须 inline style、粒子交互用 lerp 位移衰减不改基准位置、Layout+路由契约专章（混用 <Outlet/> 与 {children} 会”renders a blank <main> with no error, and npm run build still passes”——静默空白页是运行时 bug 不是类型错误）、Full-Stack Auth Contract 表（useAuth/LOGIN_PATH 用法 vs 手写 OAuth URL 的禁令）。
  • product-knowledge.md（46行）：平台能力事实注入。核心事实：build_version 返回版本 ID 不返回 URL（”Never fabricate or guess a URL”）、preview≠publish（发布是用户手点按钮得 <name>.ok.kimi.link，agent 永远不能说”已上线”）、边界（不支持第三方支付/第三方 OAuth、导出代码不带 Kimi 登录和平台数据库）、排障话术（预览空白先查项目是否在 /mnt/agents/output/app 下）。这是防止模型幻觉平台能力的标准做法。

3.6 Mode B（单代理侧线）

网站是”副产品且简单（1-3页）”时降级为单代理：主代理 init → 单个子代理”设计+实现一肩挑”（写单个 design.md 然后实现全站）→ 主代理 build+static 交付。注意与 general-swarm 的模式选择哲学相反：webapp-swarm “When in doubt → Mode A”，general-swarm “When in doubt → Mode B”——因为两者的默认任务密度不同。

4. vibecoding-general-swarm：泛化骨架（SKILL.md 73行全文已读）

同一骨架抽掉 web 特例后的通用版，差异点：

  • SPEC.md 取代 design.md 作为单一事实源；”Spec fidelity: exact interfaces, exact module boundaries, exact data formats”。
  • 核心原则第 7 条换成 “Test before merge”（子代理跑模块测试、主代理 merge 后跑集成测试）——通用编码没有 npm run build 这一个天然闸门，所以显式补测试纪律。
  • worktree 用法退化为裸 git 命令（git worktree add $HOME/work- ），不调 setup-local.sh——因为通用项目没有统一的预构建 node_modules 可复制。共享仓路径也从 output/app 变为 output/project。
  • 覆盖范围自述极大：”Python tools, data pipelines, ML systems, APIs, games, bots, CLI apps, mobile apps”——73 行显然支撑不了这么多域，它是”兜底编排宪法”而非操作手册。frontmatter 用词是 “MANDATORY for ANY coding task not covered by vibecoding-webapp-swarm”。

5. webapp-building-swarm：制品层（前端）

  • SKILL.md（98行，type: artifact）：解释双层架构表、三个脚本的用法、13 套模板清单。模板表：0-origin（默认，40+ shadcn/ui 组件）+ airlens/exhibition/exvia/forest/kaleo/lipstick/modo/photographer/playza/shibumi/swiss-dada/villa 共 12 套风格模板（GSAP/Three.js 重度视觉站居多）。
  • templates/：每套模板一个目录含 <name>.zip（实测 0-origin.zip 129KB、airlens 153KB、exhibition 172KB、playza 157KB）+ info.md（0-origin 的 info.md 是初始化回显：组件清单 40+、目录结构、import 示例——给 agent 看的模板说明书）+ 一个日期目录（2026-03-11/，疑为版本快照）。
  • init-webapp.sh（120行逐行已读）：解 zip 到 /tmp → 拷 info.md → 便携 sed 替换 <title>（L21-25 特意写了 GNU/BSD sed 兼容函数，注释说旧版 OSTYPE 判断在装了 GNU sed 的机器上坏过——有实战修坑痕迹）→ 拷入项目 → 覆盖预构建 node_modules → 非默认模板才补跑 npm install → 有 REMOTE_PATH 时：git init && git add -A && git commit 后 git clone $PROJECT_PATH $REMOTE_PATH 再 git remote remove origin——本地 clone 当”共享仓”用，clone 是为了得到干净的 .git（clone 天然不含 node_modules 等 gitignored 内容），remove origin 是仪式性的”此仓无远端”声明。
  • .prepare-template.sh（27行）：镜像构建期跑一次——解 0-origin → npm install → 整体拷到 scripts/template/（含 node_modules）。运行时所有 cp -r node_modules 都来源于此，实现零下载冷启动。注释明确 “Run once at image build time, not at runtime.”。
  • 与非 swarm 版 webapp-building 的差异（第一轮 09 章已实测）：非 swarm 版模板改从 Portal 只读挂载 /mnt/agents/.websites-templates 读、带路径逃逸防护、且会向 portal POST /api/v1/apps 注册 app——swarm 版反而没有 portal 注册（注册由 backend graft 或平台侧完成）。

6. backend-building-swarm：制品层（后端，全套技术含量最高）

6.1 SKILL.md（333行）要点

  • 栈：tRPC 11 + Drizzle ORM + Hono + MySQL + OAuth 2.0（Kimi 登录）。嫁接物：api/、contracts/、可选 db/，“never replaces or modifies existing frontend files”。
  • 特性增量安装：base（Hono+tRPC+contracts）首跑必装；db（Drizzle+MySQL）；auth（Kimi OAuth，自动含 db）。默认无参数 = auth。
  • .backend-features.json manifest 门控重入：重复跑只装 delta；graft 自有文件（Login.tsx/useAuth/AuthLayout）每次权威覆盖（cp），用户可扩展文件（schema.ts/seed.ts/connection.ts/drizzle.config.ts）有则让位（safe_copy/cp -n）——所有权边界用 cp 的旗标语义实现，很巧。
  • 19 条 “Common Mistakes” 清单是踩坑日志的精华：serial() 是 bigint unsigned auto_increment（MySQL 每表只允许一个自增列，FK 必须 bigint(..., unsigned: true)）；禁手写 DB 实体 interface（typeof table.$inferSelect，因为 superjson 会给 Date 不是 string）；api 不是 tRPC client 名（是 trpc，from @/providers/trpc）；@/ 别名只到 src/（api 里要用 @db/、@contracts/）；NEVER db:push --force、NEVER drop tables 修 migration。

6.2 init.sh（674行逐段已读）——嫁接引擎

结构：参数解析（--features 与 --template 互斥）→ 校验（npm、src/ 存在）→ git 兜底（safe.directory、wip commit 保存现场）→ manifest 读写（含遗留检测：无 manifest 但有 api/ 就探针式推断已装特性并补写 manifest，L194-227）→ 特性安装（base/db/auth 三个函数）→ portal 供应 → npm install → 自动接线 → 写 manifest → commit。

  • portal 供应（L495-546，全脚本最关键的平台耦合段）：
  PORTAL_URL="${PORTAL_URL:-http://localhost:8080/api/v1/apps}"
  APP_INFO=$(curl -sf -X POST "$PORTAL_URL" -d "{\"name\":\"$APP_TITLE\",\"features\":$FEATURES_JSON}")

返回 {app_id, app_secret, credentials: {KEY: value}}，据此生成 .env：APP_ID、APP_SECRET、VITE_APP_ID、VITE_KIMI_AUTH_URL（从 KIMI_AUTH_URL 派生 Vite 前缀版）+ credentials 全量（含 DATABASE_URL、KIMI_AUTH_URL、KIMI_OPEN_URL、OWNER_UNION_ID 等）。MySQL 实例、OAuth app 注册、owner 身份全部由 portal 一键供应——沙箱里没有数据库，数据库在云端，portal 按 app 发连接串。有防御性检查：portal 返回非 JSON（502 HTML 错误页）时显式报错退出（L504-506 注释原文说明动机）。

  • *9 个 lib/.mjs 确定性 patcher**（Node 脚本，全部已读/抽样精读）：
    • merge-schema.mjs（105行）：把 users 表定义合并进 db/schema.ts——正则提取表名做幂等（已存在即 exit 0）、合并 import 语句（按 from 去重）、插入位置优先 // TODO: 注释锚点之前。
    • wire-app-tsx.mjs（51行）：正则找最后一个 page import 后插 Login/NotFound import，按既有 <Route 缩进对齐后在 </Routes> 前插两条路由；找不到锚点 exit 1 → 落到 docs/Post-Init-Wiring.md 的人工接线指引（”Auto-wired” vs “Wiring required” 两态输出）。已接线检测是 src.includes("Login")——粗但够用。
    • 其余 patch-vite-config（失败时整文件 fallback 重写，L310-339 内嵌完整替代配置）、merge-tsconfig、merge-package-json（读 package.json.feat 片段合并依赖）、patch-env-ts（给 env.ts 加 required("DATABASE_URL") 类声明）、patch-router-auth、patch-boot-auth（加 OAuth callback）、wire-main-tsx（包 TRPCProvider）。
    • 设计哲学：易错的手工编辑全部下沉为确定性 Node 脚本，LLM 只跑脚本不手写 patch——与第一轮报告”确定性引擎兜底”范式完全吻合。
  • –template 模式：fullstack 模板 zip 自带 .backend-features.json + 预铺 api/ db/ contracts/，init.sh 检测到 manifest 自动切 provision-only（跳过所有文件拷贝/patch，只做 portal 注册 + 写 .env + npm install）。
  • 错误兜底：trap ... ERR 在失败时提示 “Please abort the current task and let the user provide feedback to Kimi”（L3）——失败语义是”中止并上报”而非重试。

6.3 docs/ 六篇（全部已读/精读）

  • Authentication.md（242行）：完整 OAuth 2.0 实现说明。架构：api/kimi/{auth,session,platform}.ts（OAuth flow、jose JWT 1 年期 session、Kimi Open Platform API client）；users 表 schema（unionId 唯一、role enum user/admin）；Login.tsx 全文内嵌（getOAuthUrl() 拼 ${VITE_KIMI_AUTH_URL}/api/oauth/authorize?client_id=...&scope=profile，state = base64(redirectUri)）；admin 分配机制：portal 响应里的 creator_user_id 写入 OWNER_UNION_ID，登录时 unionId 匹配即 admin；三级 procedure 表 publicQuery/authedQuery/adminQuery。
  • Database.md（381行）：Drizzle 纪律——禁裸 SQL、MySQL 无 .returning() 用 .$returningId()、onDuplicateKeyUpdate upsert、db:push（开发）vs db:generate+db:migrate（生产）分流。
  • Project-Structure.md（147行）：完整目录树 + import 别名公约表（@/→src 前端专用、@contracts/→前后端共享、@db/→api 专用；api 内部用相对路径）。
  • tRPC.md（161行）、Development-Guide.md（260行）：zod input 校验强制、superjson 序列化语义、开发流程。
  • Post-Init-Wiring.md（38行）：auto-wire 失败时的人工接线两步骤——确定性脚本的失败有显式人工兜底文档，闭环完整。
  • 模板依赖快照（scripts/template/package.json 已读）：trpc 11.8.1、hono 4.8.3、drizzle-orm 0.45.1、mysql2 3.14.1、jose 6.1.3、@aws-sdk/client-s3 + s3-request-presigner（模板内置 S3 能力，凭证也来自 portal credentials）、react-router 7.6.1。

7. skill-creator-swarm：技能元工厂 + 盲评协议

7.1 本体（490行，Anthropic skill-creator 的 swarm 适配版）

三原则：简洁至上（”The context window is a public good”）、按任务脆弱度设自由度（高/中/低三档）、渐进披露（frontmatter→SKILL.md→references/ 三层）。技能解剖：scripts/（确定性操作）、references/（按需加载文档）、assets/（被消费不进上下文的产物）。七步流程，Step 5 为 swarm 评测（MANDATORY）。

7.2 盲评协议（Step 5，executor/grader/comparator/analyzer 四角色）

  • 成对执行铁律：”Do not run all with_skill cases first and come back for baseline later. Pair them in the same evaluation round”——同一轮内 with_skill 与 baseline（无技能=新技能评测；旧版技能=更新评测）成对启动。
  • 四角色全部用 create_subagent 显式 system_prompt 创建，零脚本（”These do not need dedicated scripts… they can be created via create_subagent with explicit system_prompts and used through task“）：
    • skill_executor：跑任务。提示词模板固定字段：Mode（with_skill|baseline）、Skill path（/mnt/agents/output/<skill>/SKILL.md 精确路径，baseline 无）、Task、Input files、Output directory。
    • skill_grader：对照 expectations 逐条 pass/fail + 证据，并反向指出弱 expectation（”point out weak expectations if they are non-discriminating”）。
    • skill_comparator：盲评——”review output A and output B without knowing which is which… Do not infer which one used the skill”，从 prompt 反推 rubric，输出 winner A/B/TIE + 各自优缺点。
    • skill_analyzer：读技能+评测笔记，找”ambiguous instructions / missing guidance / repeated wasted work”，产出具体修改建议。
  • expectation 写法指导：弱（”a file exists”）vs 强（”the output workbook includes a pivot table on sheet Summary”）；主观任务靠盲评+人审而非硬断言。
  • 反过度工程明令：”avoid building complex external orchestration scripts just to run evals… The implementation should stay lightweight.”
  • 工作区约定：<skill>-workspace/iteration-1/eval-N/{with_skill,without_skill,notes.md}——”The point is consistency, not strict tooling.”

7.3 三脚本（全部逐行已读）

  • init_skill.py（303行）：生成技能骨架。内置 SKILL.md 模板带四种结构模式指导（Workflow-Based / Task-Based / Reference-Guidelines / Capabilities-Based，各配一句话选型标准和结构示例），外加 scripts/references/assets 三个示例文件（示例文件本身写满”别的技能怎么用我”的交叉引用）。命名规范 kebab-case ≤64 字符。硬编码输出路径 /mnt/agents/output，并强调 /app/.user/skills/ NOT shared——/mnt/agents/output 是主子沙箱间唯一共享目录的又一实证。
  • quick_validate.py（103行）：frontmatter 校验。允许键白名单 {name, description, license, allowed-tools, metadata, compatibility}；name kebab-case≤64、description 禁尖括号≤1024 字符。注意：沙箱里 269 个技能的 frontmatter 方言远比这宽（type:、openclaw.requires.*、permissions: 等第一轮已观测），说明这个 validator 只约束”本工具产出的技能”，不管存量。
  • package_skill.py（110行）：先 validate 再打 zip 格式的 .skill 文件；SKILL.md 强制要求最终回复引用 .skill 文件路径供 UI 展示下载。
  • references/workflows.md（28行）+ output-patterns.md（82行）：顺序/条件工作流写法、严格 vs 弹性输出模板、input/output 示例对——给技能作者的模式小抄，轻量。

8. deep-research-swarm：研究编排（509行，frontmatter 用 YAML 列表式方言）

  • 四条路由（Phase 0 意图路由）：A 宽搜索（两段式 swarm：先 ≥5 个 wide 代理 × ≥10 搜索做广度，再 ≥10 个 deep 代理 × ≥20 搜索做深度）/ B 聚焦搜索（标准管线）/ C 纯文件（0 次外部搜索，禁偷偷搜索：”do NOT sneak in external searches. Fidelity to user intent is paramount”）/ D 文件增强（文件为主+外部补缺，≥150 搜索）。歧义默认规则：A 优先于 B、D 优先于 C。
  • 认识论设计（区别于普通”并行加速”）：”Swarm parallelism serves epistemic robustness — not merely speed”。维度间故意 ≥30% 概念重叠制造交叉验证压力；Phase 4 交叉验证把发现分四级置信（High=≥2 代理独立信源一致 / Medium / Low / Conflict Zone 冲突高亮绝不抹平——含时间维度冲突单列）；Phase 5 条件触发逐冲突派验证代理（每冲突 ≥3 次追加搜索，Route C 禁用）。
  • 证据模板（所有子代理输出强制）：Claim/Source/URL/Date/Excerpt(verbatim，禁转述)/Context/Confidence(high|medium|low) 七字段；全文 [^number^] 行内引用，与 pdf 技能的 citation.jsonl 衔接（09 章 §3.1）。
  • Epistemic Reset Rule：分析前必须 bash 查当前日期；搜索语言锁死跟随用户语言。
  • 收口不是写报告而是交接：Phase 7 把 research/ 下全部产物（dim 文件 ≥10、cross_verification、insight ≥5 条）显式路径清单交接给 report-writing 或 paper-writing 技能，并要求”明确告诉写作技能研究已完成、不需要再派研究代理”——技能间交接协议。
  • 输出目录铁律 /mnt/agents/output/research/（”non-negotiable”，禁止直接写 output/ 根）。

9. batch-download：纯提示词下载编排（269行，type: capability）

  • 四阶段：分解（Orchestrator 独占，”No execution in this phase”）→ 证据收集（URL 模式发现是灵魂：数字递增/目录结构/命名模板/分页参数，”verify the pattern holds by testing 2–3 instances” 后用 Python 程序化生成全量 URL）→ 并行下载（一原子单元一 task，同时发出）→ 整合校验。
  • 反幻觉条款密度最高：”Never fabricate URLs”（只许用户给的/搜索到的/验证过模式外推的/程序解析的四种来源）、”Do NOT download HTML and rename it as .pdf“、严格类型匹配失败要报”limitation / partial result”。
  • 子代理提示词五要素模板：目标范围、ATTENTION: 前缀关键约束、覆盖要求（”download ALL of them, not just the first one”）、验证要求、STRICT 输出格式（JSON schema 或 Markdown 表，”No extra commentary”，未知字段填 “-“）。
  • Orchestrator 侧校验四连：格式/字段/约束/细节级（”year 2021 but URL shows 2019″这类标签值不匹配单列）；失败重试用”clarified prompt 重跑或派专门 verify 代理换路线”。
  • 限流处理：429/403/CAPTCHA → 10-60s 随机抖动退避、敏感站点优先 Python 直连；最终铁律 “Never call tools after generating the final answer”。
  • 与 git 体系完全无关——证明 swarm 家族有两种并存实现：纯提示词契约（batch-download/deep-research）vs git worktree 实体隔离（vibecoding 系列）。

10. 运行时原语：create_subagent + task 调用约定汇总

从全套技能反推出的沙箱 runtime 编排 API：

约定证据
存在两个原语：create_subagent（带显式 system_prompt 创建命名角色）与 task（派任务执行）skill-creator-swarm L11、L276
子代理名称参与模型路由：名字含 “designer”（不区分大小写）路由到设计模型vibecoding-webapp-swarm L95 注释
并行 = 单条消息内多个 task 调用同时发出vw-swarm L206 “single message, multiple task tool calls”；batch-download L166
子代理跑在独立易消亡沙箱，跨沙箱唯一共享目录是 /mnt/agents/output；/app/.user/skills/ 不共享setup-local.sh L40 注释；skill-creator-swarm L146
子代理通过文件系统收上下文（提示词里写绝对路径让子代理自己读），不是参数注入所有 swarm 技能的子代理提示词模板（”Read /mnt/agents/output/design/design.md in full”）
交付工具 mshtools-website_version_manager（build_version/rollback），git-native，版本 ID=commit 短哈希vw-swarm Phase 7、L331
平台供应 API POST http://localhost:8080/api/v1/apps → {app_id, app_secret, credentials{DATABASE_URL, KIMI_AUTH_URL, ...}}backend init.sh L496-543
图像/视频生成工具对子代理可用（”the image generation tool”）vw-swarm Phase 4 条款 7

11. 密钥/凭证观测（脱敏记录）

  • backend graft 生成的 .env 含 APP_SECRET、DATABASE_URL（MySQL 连接串）、KIMI_AUTH_URL/KIMI_OPEN_URL、OWNER_UNION_ID——来源均为 portal POST /api/v1/apps 响应，位置 $PROJECT_PATH/.env（gitignored），经共享仓 .env 信箱分发给各 worktree。本轮未读取任何真实 .env 内容，仅记录机制。
  • .backend-features.json 含 app_id（非密）。
  • 模板内置 S3 client 依赖（@aws-sdk/client-s3），凭证同样预期来自 portal credentials。

12. 移植评估表

12.1 对 Hermes（自有多代理框架）

组件价值理由工作量硬依赖
swarm-workspace 双层契约 + setup-local.sh高105 行 bash 实现多代理代码隔离+合并+密钥继承，零 LLM 耦合，可直接当 Hermes 的 workspace 原语纯拷贝（改 REPO_PATH 默认值）git、npm（可选）
缝合点冻结 + grep 契约检查高“App.tsx/router.ts/schema.ts 冻结 + merge 后 grep 校验”是多代理并行改同仓冲突的最小工程解，与框架无关需适配（改成 Hermes 项目的缝合点清单）无
反验证螺旋纪律（commit 即返回 / build 一次即 STOP）高针对 LLM 代理真实失效模式，纯提示词条款纯拷贝（措辞可直接借用）无
vibecoding-webapp-swarm 七阶段乐谱中角色分工/分组策略可借鉴，但技术栈钉死 + 版本工具耦合，Hermes 需换成自己的构建交付需重写（保留骨架替换交付层）mshtools 版本工具、AI 媒体生成工具
backend init.sh 嫁接引擎（9 个 mjs patcher）中“LLM 不手写 patch，跑确定性脚本”的范式价值高于代码本身；patcher 与 tRPC/Hono 栈强绑定需重写（范式照搬，脚本重写）portal 供应 API（需替换为自有 provisioning）
skill-creator-swarm 盲评四角色高executor/grader/comparator/analyzer + 同轮成对 + 盲评，仅需两个子代理原语，Hermes 可直接用于提示词/技能回归评测需适配（映射到 Hermes 的子代理 API）子代理创建/任务原语
deep-research-swarm 路由+置信分级中四路由、Conflict Zone、证据七字段模板是高质量研究编排样本需适配（输出目录、交接的写作技能改名）搜索工具
batch-download低提示词纪律可摘抄（URL 模式发现、禁伪造 URL），但整体是单域 playbook需适配网络访问
Designer 名字路由模型低（对 Hermes）/ 参考依赖沙箱 runtime 隐藏特性；但启发 Hermes 可做”角色名→模型路由”显式机制需重写runtime 模型路由

12.2 对 Kimi Code（本机 CLI，SKILL.md 三级 scope + MCP + Agent/AgentSwarm）

组件价值理由工作量硬依赖
swarm-workspace + setup-local.sh高Kimi Code 有 Agent 子代理机制；worktree 契约可封装为一个 project scope 技能，脚本直接可用（REPO_PATH 改项目路径）纯拷贝+薄封装git；子代理需共享文件系统（本机 CLI 天然满足，比云端更简单）
skill-creator-swarm 本体（init/validate/package + 盲评协议）高格式同源（同一套 SKILL.md+frontmatter 约定，validator 白名单兼容 Kimi Code 技能格式）；/mnt/agents/output 改项目目录即可；盲评协议映射到 Agent 子代理调用需适配（路径 + 子代理 API 名）Agent 子代理原语
编排提示词范式（角色模板逐字锁定、Actor Reference 表、模式选择表）高与 runtime 无关的 prompt 工程资产，Kimi Code 技能可直接引用写法纯拷贝（作为写作范式）无
vibecoding 两个编排技能中骨架可移植，但依赖云端交付工具与 /mnt/agents 布局；Kimi Code 场景下交付=本地构建，可简化 Phase 7需适配—
backend-building-swarm低tRPC/Hono/Kimi OAuth 栈与 Kimi Code 用户场景错位，portal 供应完全不可用需重写portal API（硬耦合，不可用）
deep-research-swarm中Kimi Code 有 MCP 数据源与搜索；路由+交叉验证骨架可用，搜索预算需按 CLI 配额现实下调需适配搜索/取数 MCP
batch-download低单域 playbook，Kimi Code 用户少有此场景需适配网络
product-knowledge.md 写法中（范式）“把平台能力边界写成技能文档防幻觉”的做法值得 Kimi Code 技能作者效仿纯拷贝（范式）无

12.3 平台耦合点清单（移植时必须替换的三件事）

  1. /mnt/agents/output 共享盘：drive9 FUSE 挂载，主子沙箱唯一共享目录。Hermes 换成自己的共享卷/目录约定；Kimi Code 本机场景直接用项目目录。
  2. mshtools-website_version_manager：云端交付/预览/回滚工具，git-native 语义。替换为任意”commit + 部署记录”机制即可保持协议不变。
  3. portal POST /api/v1/apps 供应：app 注册 + MySQL/OAuth/S3 凭证下发，backend-building-swarm 的命门。无 portal 则 auth/db 特性整体不可用，需替换为自有 provisioning 或剥掉全栈路径。

次要耦合：子代理名称→模型路由（runtime 隐藏契约）、AI 图像/视频生成工具、静态站 project_dir 必须指向 /mnt/agents/output/app（平台构建路径键）。

13. 工程质量亮点与坑（速查）

亮点：① git 对象库当 IPC，无远端无 push；② .env 借 gitignore 边界 + 共享仓信箱实现密钥继承；③ --force + 三态重入把 ephemeral 沙箱恢复语义写进 105 行脚本；④ 确定性 .mjs patcher 替代 LLM 手工 patch，失败有人工兜底文档；⑤ 创意权单点化（Designer）+ 主代理职权最小化；⑥ 交付即 git commit（版本 ID=短哈希），回滚=roll-forward commit，无历史改写；⑦ 盲评协议零脚本，两个原语搞定。

坑/杂质：① git worktree prune 是全域禁令，任何自动化清理都可能误伤（协议靠人人遵守，无技术强制）；② 共享仓 .env 明文落盘在共享盘上——密钥信箱便利与暴露面一体两面；③ octopus merge 依赖缝合点冻结纪律，子代理越界改冻结文件没有硬阻断（只有提示词禁令+事后 grep）；④ wire-app-tsx.mjs 的已接线检测是 src.includes("Login") 这种粗匹配，极端命名下会误判；⑤ frontmatter validator 白名单与沙箱存量技能方言（type:/openclaw.* 等）不一致，skill-creator 产出的技能反而是”方言最窄”的；⑥ deep-research 的 ≥200 次搜索预算在非云端配额下不现实。