Buddy 应用（专家包）技术内幕

这不是一份「点这里、填那个」的操作手册。它要回答的是：一个 Buddy 应用（专家 / 专家团）在磁盘上是什么、在进程里变成什么、以及中间那段代码在干什么。 读完你应当能独立于任何 UI，用文本编辑器从零造出一个能在 WorkBuddy 里真正跑起来的专家。

本文所有结论均来自对本机 WorkBuddy 安装包的实证取证 —— 包括逆向主进程 app.asar、命令行内核 codebuddy-lite-wb.mjs、创作脚本 expert-manager/scripts/*.py，以及对 16 个真实落盘专家包的统计。 凡与官方文档口径不一致处，均以代码证据为准，并在文中明确标出。

0 阅读前提与取证方法

在往下读之前，先交代本文的三条取证路径，方便你自己复核：

1 它到底是什么

1.1 四个容易混淆的概念

WorkBuddy 里有四套可插拔机制，它们共享「Markdown 定义 + 目录扫描」这一思路，但运行时待遇完全不同。 分不清这四者，是绝大多数困惑的源头。

1.2 一句话总纲

把这句话展开成三层管线，就是本文的骨架：

2 包体解剖：磁盘上长什么样

2.1 目录树

expected_path = get_expert_plugins_dir()
resolved_path = Path(output_path).expanduser().resolve()
if resolved_path != expected_path.resolve():
    print(f"❌ Error: --path 必须为专家目录: {expected_path}")
    print(f"   非专家目录下创建的专家无法被检测到。")
    sys.exit(1)

2.2 plugin.json 字段全解

这是整个包的中枢。下面按运行时实际如何使用来分类，而非按文档顺序 —— 标注为「展示态」的字段不参与运行时行为。

身份与类型（运行时强依赖）

资源声明（决定加载什么）

展示态字段（不参与运行时行为）

2.3 Agent MD 的格式

每个 agents/*.md 文件就是一个智能体定义。结构极简：YAML frontmatter 管元数据，正文就是 system prompt。

---
name: code-reviewer                    # 【必需】必须等于文件名（不含 .md）
description: Reviews code for bugs, security and performance issues.
displayName:
  en: "Code Review Expert"
  zh: "代码审查专家"
profession:
  en: "Senior Code Reviewer"
  zh: "资深代码审查师"
maxTurns: 50                           # 可选，正整数
skills: [ast-scan]                     # 可选，预加载的技能
---

# 代码审查专家 - 审稿人

你是一名资深代码审查师……（这段就是 system prompt）

## 核心能力
1. **缺陷识别**：……
2. **安全审计**：……

## 工作流程
1. 先通读 diff 全貌
2. 逐文件审查
3. 汇总输出

## 输出规范
- 按严重程度分级
- 每条给出行号与修改建议

## 注意事项
- 不做主观风格争论

frontmatter 字段的真实待遇

2.4 Team 型的额外约定

3 创建流水线：七个脚本

创作期由 expert-manager 这个技能驱动，共 5 个 Python 脚本（外加 2 个测试脚本）串成流水线。 它们全部是纯 stdlib 实现，无第三方依赖。

resources/plugins/workbuddy-builtin/skills/expert-manager/
├── SKILL.md                     179 行   # 流程与铁律
├── references/
│   ├── plugin-json-spec.md      184 行   # plugin.json 字段规范 + 两套模板
│   ├── agent-md-spec.md         179 行   # Agent MD 结构（普通 / 主理人）
│   ├── team-spec.md             120 行   # 协作铁律、命名、SOP 编排
│   └── avatar-spec.md           162 行   # 头像 prompt 构建策略
└── scripts/
    ├── init_expert.py           485 行   # ① 生成骨架
    ├── validate_expert.py       381 行   # ② 校验
    ├── register_expert.py       271 行   # ③ 注册
    ├── package_expert.py        121 行   # ④ 打包
    ├── batch_create.py          141 行   # 批量编排（模板）
    ├── test_register_expert.py   78 行
    └── test_package_expert.py    95 行

1. init_expert.py — 生成骨架 按 --type agent|team 生成目录 + 带 [TODO] 占位符的 plugin.json 与 MD 模板。 Agent 型产出 1 个 MD；Team 型产出 {team}-team-lead.md + 一个 member-placeholder.md（需自行改名）+ settings.json。 同时校验 --path 必须是专家目录、name 必须是 kebab-case。
2. 填充内容 把 [TODO] 换成真实内容。这一步由 AI 或人完成，是唯一有创造力含量的环节。 正文质量直接决定专家质量 —— 因为正文就是 system prompt，没有中间层。
3. ImageGen — 生成头像 按 avatar-spec.md 从 MD 内容反推 prompt：读角色定义 → 提核心能力关键词 → 转视觉元素 → 拼装。 Agent 型 1 张；Team 型 N+1 张（团队整体 + 主理人 + 每个团员）。同团队共用风格锚定词与背景色调。
4. validate_expert.py — 校验 会做五大类检查：位置（必须在 my-experts 目录下）、结构（禁止 hooks/、commands/、.lsp.json，禁止资源目录藏在 .codebuddy-plugin/ 内）、 字段（必填项、kebab-case、tags/quickPrompts 恰好 3 个、team 的 profession ≡ displayName）、 一致性（agentName 有对应 MD、frontmatter name ≡ 文件名）、 禁用项（frontmatter 不得有 tools）。
5. register_expert.py — 注册 二次校验（重点查 [TODO] 残留）后，向 marketplace.json 写入条目 {"name": ..., "source": "./plugins/<dir>", "description": ...}， 并向专家目录写入 .created-by-session 标记文件（值取自环境变量 CODEBUDDY_SESSION_ID）。
6. package_expert.py — 打包 先跑一遍完整校验，通过后打 zip。会自动跳过隐藏文件（.codebuddy-plugin 除外）、 __pycache__、node_modules、.gitkeep、.DS_Store。
7. 批量（可选） batch_create.py 提供模板：对每个专家串行执行 init → 填充 → validate → register， 任一步失败即停止。规范明令禁止「只写文件跳过校验注册」和「直接改 marketplace.json」。

3.1 注册脚本的关键片段

def register_expert(expert_dir, marketplace_dir, session_id=None):
    manifest_path = marketplace_dir / '.codebuddy-plugin' / 'marketplace.json'
    ...
    source = f"./plugins/{expert_dir.name}"

    # 已存在则更新，否则追加 —— 保证幂等
    for p in plugins:
        if p.get('source') == source or p.get('name') == expert_name:
            p['name'] = expert_name
            p['source'] = source
            p['description'] = expert_description
            ...
            return True

    plugins.append({"name": expert_name,
                    "source": source,
                    "description": expert_description})

    if session_id:
        _write_session_marker(expert_dir, session_id)   # 写 .created-by-session

4 分发与版本：市场包如何落到磁盘

本地自建专家跳过本节。但如果你要分发，或者想理解官方专家的行为，这一节解释它们从哪来。

4.1 两套落盘位置

4.2 下载与新鲜度判定

async ensureDownloaded(e, t, n){
  let r = this.getPluginDir(e);
  if (await this.deps.hasPluginManifestAsync(r)){
    if (t && await this.isLocalStale(r, t))
      console.log(`...Local cache stale, re-downloading: ${e}`);
    else return await this.logBundleSnapshot(`cache`, e, r), r
  }
  let o = this.downloadAndExtract(e, r, n);
  ...
}

async isLocalStale(e, t){
  let n = x.join(e, `.downloaded_at`),
      r = await O.readFile(n, `utf-8`),
      i = new Date(r.trim()).getTime();
  return new Date(t).getTime() > i        // 服务端 updatedAt > 本地时间戳 → 过期
}

流程要点：

• 命中缓存且未过期 → 直接用；过期 → 重新下载。
• 下载 → 先备份改名 → 解压（支持 tar/zip，含 zip-slip 路径穿越防护）→ normalizeExtractedPluginRoot（若清单在子目录则提升一层）→ 校验 plugin.json 存在 → 删除备份 → 写 .downloaded_at（ISO 时间戳）。
• 下载失败且有旧缓存 → 告警并回落使用陈旧缓存，不阻断使用。
• URL 选择：企业网关（operation-platform，需通过 isTrustedDownloadUrl 校验）优先，失败回落 COS /bundles/<name>.tar.gz。

{
  "ex_XoPVlmyOgAY9": "fullstack-dev",
  "SoftwareCompany": "software-company",
  "ex_jPdPfIC04OKD": "software-company",      // ← 两个市场 ID 指向同一目录
  "ex_NsJv0iGhmXQh": "up-stock-strategy-analyze"
}

5 激活：点击专家的那一瞬间发生了什么

这是全链路最精妙的一环。很多人以为「选中专家」只是记了个 UI 状态，实际上它触发了一次 跨进程的配置写入 + HTTP 调用。整个过程分四步。

5.1 第一步：主进程准备事实

点击后，主进程的 createConversationExpertRuntimePreparer 开始工作（app.asar 偏移 ~76308100）：

async function readPluginManifestFromDir(e){
  for (let t of Je){                    // Je = [".codebuddy-plugin", ".workbuddy-plugin", ...]
    let n = T.join(e, t, Ye);           // Ye = "plugin.json"
    try{
      let e = await E.readFile(n, `utf8`), t = JSON.parse(e);
      return {name:..., id:..., agentName:...,
              expertType: optionalExpertType(t.expertType),   // ← 类型在此被读取
              marketExpertId:..., sourceId:..., displayName:t.displayName}
    }catch(e){ if(e.code === `ENOENT`) continue; return }
  }
}

随后是落盘状态机，它定义了包的三态：

if (!a || !o) return { status: `incomplete-names` };   // 缺 name 或 agentName

return await hasMarketplaceBundleEntry(e, n)
  ? { status: `complete`,      candidate: s }          // 目录在 + 已注册
  : { status: `needs-register`, candidate: s };        // 目录在 + 未注册

同时，针对 team 型，主进程会先解析出主理人 MD 的路径用于提示词预览：

// resolveExpertAgentPromptSource
let o = a.expertType === `team`
      ? a.teamInfo?.leadAgent                          // team → 直接用 leadAgent
      : await this.resolveExpertAgentName(i, a, e);    // agent → 回退链

let s = await resolveExpertAgentMarkdownPath(i, o);
return s ? {agentName: o, filePath: s} : void 0

// resolveExpertAgentName 的回退链
async resolveExpertAgentName(e, t, n){
  if (t.agentName) return t.agentName;                                   // ① plugin.json
  if (t.expertType === `team` && t.teamInfo?.leadAgent) return t.teamInfo.leadAgent;  // ②
  let r = this.toKebabCase(n); return await this.resolveAgentNameFromPluginFiles(e, t, r)  // ③ 猜
}

5.2 第二步：写入会话配置

function applyPreparedExpertSettings(e, t, n){
  let r = e ?? {},
      i = asRecord(r.enabledPlugins),
      a = asRecord(r.extraKnownMarketplaces),
      o = asRecord(r.env),
      s = ...(o.CODEBUDDY_CUSTOM_HEADERS),
      c = [`X-Expert-Id: ${t.canonical.id}`,
           ...t.expertType === `team` ? [`X-Expert-Team-Task: true`] : []],
      l = t.canonical.marketplace;

  return {...r,
    enabledPlugins: d.w(i, `${t.pluginName}@${l}`),          // 启用 @
    extraKnownMarketplaces: {...a, [l]: {source: {source: `directory`,
                              url: n.pluginService.getExpertMarketplacePath(l)}}},
    env: {...o, CODEBUDDY_CUSTOM_HEADERS: [s, ...c].filter(Boolean).join(`\n`)}}
}

三件事：

• 启用插件：把 "<pluginName>@<marketplace>" 加入 enabledPlugins。这就是插件 ID 的形式，也是后面 CLI 认它的凭据。
• 声明额外市场：把该 marketplace 的目录路径告诉 CLI，让它知道去哪找包。
• 注入 HTTP 头：X-Expert-Id 标识当前专家，team 额外加 X-Expert-Team-Task: true（供后端识别团队任务）。

5.3 第三步：HTTP 切换（真正的激活）

let _ = `${s}/api/v1/plugins/switch`, v = {persist: !1};

g.length > 0 && (v.disable = g[0]);          // 关掉前一个
n && (v.enable = `${n}@${d}`);               // 启用这个包
r && (v.agentName = r);                      // ← 主理人 / 主 agent 名
let y = n ? `${n}@${d}` : ...;
y && (v.sourcePluginId = y);
a !== void 0 && (v.internalModelRequestHeaders = a);

await fetch(_, {method: `POST`, body: JSON.stringify(v)})

CLI 侧对应两个入口：

async setVolatilePluginAgent(t, i = {}){
  let n = this.normalizePluginAgentSetting(t), ...
  this.volatilePluginAgentName = n;
  this.volatilePluginSourcePluginId = s;
  this.volatilePluginInternalModelRequestHeaders = c;
  ...
}

5.4 第四步：settings.json 的真相

规范说 team 型必须有 settings.json（内容 {"agent": "xxx-team-lead"}）。CLI 确实读它，但待遇微妙：

let L = t.settings;
try{
  let t = ed.join(i, "settings.json");
  await ef.Sn.access(t);
  let n = JSON.parse(await ef.Sn.readFile(t, "utf-8")),
      s = {...n.agent ? {agent: n.agent} : {},
           ...void 0 !== n.subagentStatusLine
              ? {subagentStatusLine: n.subagentStatusLine} : {}};   // ← 只认这 2 个 key
  Object.keys(s).length > 0 && (L = {...L, ...s})
}catch{}
return {..., settings: L}

6 核心：Markdown 如何变成活的智能体

这是整个机制的心脏。前面所有流程都是为这一刻铺路：把 agents/*.md 这个纯文本文件， 变成模型可以 Agent({subagent_type: "xxx"}) 调度的真实智能体。

6.1 加载器：声明 + 兜底双通道

async loadPluginComponents(t, i){
  h.push(this.agentLoader.load(i, n, this.normalizePathConfig(t.agents), p) ...)
  h.push(this.skillLoader.load(i, n, this.normalizePathConfig(t.skills), p) ...)
  ...
}

// normalizePathConfig：string → [string]；Array → filter(string)；否则 undefined

进入 AgentExtensionLoader 后才是重点：

async load(t, i, n, s){                    // t=插件根目录, i="name@marketplace", n=agents路径列表
  if (n && n.length > 0)
    c.push(...await this.loadFromPaths(t, i, n, p, h));    // ① 按 plugin.json 声明加载

  let s = ed.join(t, tK);                                   // tK = "agents"
  if (await this.pathExists(s) && !p.has(s))
    c.push(...await this.scanAgentsDirectory(s, i, p, t, h));  // ② 兜底扫整个目录
}

6.2 解析：frontmatter → 配置对象

let n = await eu.MarkdownUtils.extractFrontMatterFull(i);      // 解析 YAML frontmatter
n.parseError && this.logger.warn(`[AgentLoader] Malformed YAML frontmatter ...`);

let E = n.data,
    R = ed.basename(A).replace(/\.md$/, ""),
    P = E.name || R,                          // name ← frontmatter，缺失回退文件名
    I = this.generateSourceLabel(A, S),
    O = E.description || P;
O.includes(I) || (O = `${O} ${I}`);           // description 自动追加来源标签

let M = eu.MarkdownUtils.parseListField(E.tools),
    L = ...parseListField(E.disallowedTools),
    $ = ...parseListField(E.skills),
    F = normalizeReasoningEffort(E.effort),
    U = "worktree" === E.isolation ? E.isolation : void 0,
    B = eu.MarkdownUtils.parsePositiveIntField(E.maxTurns),   // 非正整数 → 丢弃
    W = eu.MarkdownUtils.parseBooleanField(E.background),
    q = E.initialPrompt, G = tG.Ic(E.memory), z = E.model?.trim();

for (let t of ["permissionMode", "hooks", "mcpServers"]){     // 这三个被忽略
  ...this.logger.warn(`[AgentExtensionLoader] plugin agent '${P}' sets ${t},
      which is ignored for plugin agents.`)
}

let J = n.content.trim(),                     // ← MD 正文
    Y = c ? await tV.C(J, p, V, c) : tV.r(J, p, V);   // ← 变量替换

return {
  name: P, description: O, instructions: Y,   // ★ 正文 → instructions（system prompt）
  ...N && {tools: N}, ...L.length && {disallowedTools: L},
  models: z ? [z] : [],
  asTool: !0,                                // ★★ 关键开关
  color: E.color || generateColorFromName(P),
  tags: [ej.UxB, ej.HOt, tz.PLUGIN_TAG, S],  // ★ S = "pluginName@marketplace"
  ...F && {effort: F}, ...void 0 !== B && {maxTurns: B}, ...W && {background: W},
  ...q && {initialPrompt: q}, ...$.length && {skills: $},
  ...G && {memory: G}, ...U && {isolation: U}
}

变量替换紧跟其后：

E = E.replace(/\$\{CODEBUDDY_PLUGIN_ROOT\}/g, t)
     .replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, t)

6.3 三个关键产物

6.4 注册到 Agent 工具：可 spawn 的秘密

配置对象造出来后，还要过三关才能真正被模型调用。

let t = await this.pluginManager.getActivePlugins(); ...
for (let {components: i} of t){
  let {settings: t, ...n} = i;                      // ← settings 被剥离，其余并入
  s = await this.productMerger.merge(s, {...n, mergeStrategy: SmartMerge})
}

let c = s?.components.agents ?? [];
for (let t of c){
  let s = t?.name;
  if (s && !this.agentConfigMap.has(s)){     // ← 先到先得，重名不覆盖
    this.agentConfigMap.set(s, n);
    i.push(n)
  }
}

A = [
  "Launch a detached worker...",
  "",
  "Available agent types:",
  ...q.filter(t => !0 === t.asTool || t.name === nI.QYL.GENERAL_PURPOSE)
     .map(t => `- ${t.name}${i ? `: ${i}` : ""}${n}`),
  ...
].join("\n")

至此，模型看到的 Agent 工具描述里就有了 - security-reviewer: 安全审计专家 这一行， 于是它能发出 Agent({subagent_type: "security-reviewer", name: "security-reviewer", prompt: "..."})。

7 Team 的运行时保障：只有两个，都是硬编码

如果你以为专家团有什么精巧的编排引擎，会失望。运行时的全部贡献只有两点。

let l = `1`, u = `0`, d = `team`;
function resolveAgentTeamsEnv(e = {}){
  return e.expertType === d ? l : e.disableAgentTeams ?? !0 ? u : l
}
var f = `CODEBUDDY_CODE_EXPERIMENTAL_AGENT_TEAMS`;

7.1 这带来什么工程后果

8 技能、脚本与命名空间

8.1 技能：同样有声明 + 兜底双通道

async load(t, i, n, s){
  ...
  let s = ed.join(t, rr);                              // rr = "skills"
  if (await this.pathExists(s) && !p.has(s))
    n = await this.scanSkillsDirectory(s, i, p, void 0, 0, t, h);   // 兜底扫目录

  let S = ed.join(t, "SKILL.md");                      // 单文件技能形式
  if (!p.has(S) && await this.pathExists(S))
    n = await this.parseSkillFile(S, i, void 0, t, h);
}

8.2 命名空间前缀：一个容易搞错的机制

官方文档说 plugin.json 的 name 是「技能命名空间前缀」。这话在效果上对，但机制不是那样。

function relativeSkillDirSegments(t, i, n = s){
  return i ? n.relative(i, t).split(n.sep).filter(Boolean) : []
}

function deriveSkillNameFromPath(t, i, n = s){
  let c = n.dirname(t);
  return relativeSkillDirSegments(c, i, n).join(":") || n.basename(c)
}

技能名是相对插件根目录的路径段用 : 连接（如 skills:ast-scan）。而消费端解析时：

resolveSkillNameForPreload(t, i, n){
  let s = i.find(i => i.name === t); if (s) return s;                 // ① 原名直查

  if (!t.includes(":") && n?.tags?.includes(ey.PLUGIN_TAG)){
    let s = n.tags[n.tags.length - 1];      // ★ 取 tags 末位 = "pluginName@marketplace"
    if (s && s !== ey.PLUGIN_TAG){
      let n = s.split("@")[0], c = `${n}:${t}`;                       // ② 拼前缀
      let p = i.find(t => t.name === c); if (p) return p
    }
  }
  if (!t.includes(":")){                                              // ③ 唯一后缀匹配
    let s = i.filter(i => i.name.endsWith(`:${t}`));
    if (1 === s.length) return s[0];
    ...
  }
}

8.3 bin/：约定优于配置

async getPluginBinPaths(){
  let t = await this.getActivePlugins(), i = [];
  for (let {plugin: n} of t)
    if (n.installedPath){
      let t = ed.join(n.installedPath, "bin"),
          s = await ec.stat(t).catch(() => void 0);
      s?.isDirectory() && i.push(t)          // ← 目录存在就收，不看 plugin.json
    }
  return i
}

function buildPluginPathEnv(t){
  let i = process.env.PATH || "";
  if ("win32" !== process.platform)
    return [...t, i].filter(Boolean).join(":")
  ...
}
async function getBashPluginEnv(t){
  let i = [];
  if (t) try{ i.push(...await t.getPluginBinPaths()) }catch{}
  i.push(...(process.env.WORKBUDDY_EXTRA_PATHS ?? "").split(...).filter(Boolean));
  return i.length ? {PATH: buildPluginPathEnv(i)} : void 0
}

9 端到端时序图

把前面所有环节串成一条完整链路。建议对照这条链路来定位问题。

【渲染层】用户点选专家
   │  contexts-BNN7VV-R.js: setSelectedExpertForSession({expertId, expertMarketplace, runtimeIdentity})
   ▼
【主进程】createConversationExpertRuntimePreparer                    app.asar ~76308000
   ├─ resolveExpertLocation      → 定位包目录
   ├─ activateExpert / ensureDownloaded
   │     └─ 缓存命中? → 检查 .downloaded_at 新鲜度 → 过期则重下
   ├─ resolveExpertAgentMarkdownPath(<root>/agents/<leadAgent|agentName>.md)
   └─ assemblePreparedFacts → {pluginName, agentName, expertType, promptText}
   ▼
【主进程】applyPreparedExpertSettings                               app.asar ~76323000
   ├─ sessionSettings.enabledPlugins["<plugin>@<marketplace>"]
   ├─ extraKnownMarketplaces[marketplace] = {source: directory, url: ...}
   └─ env.CODEBUDDY_CUSTOM_HEADERS += "X-Expert-Id: ..."
                                     += "X-Expert-Team-Task: true"   (仅 team)
   ▼
【主进程】ExpertPluginActivation                                     app.asar ~89018600
   └─ POST <acp>/api/v1/plugins/switch
        {persist:false, enable:"<plugin>@<mk>", agentName:"...",
         sourcePluginId:"...", internalModelRequestHeaders:[...]}
   ▼
【CLI】switchPlugins + setVolatilePluginAgent                        mjs 964
   ▼
【CLI】loadPluginComponents                                          mjs 2511
   ├─ AgentExtensionLoader.load
   │    ├─ 读 plugin.json 的 agents[]                    ← 通道 ①
   │    ├─ 兜底扫 <plugin>/agents/ 目录（深度≤16）        ← 通道 ②
   │    └─ parseAgentFile
   │         ├─ extractFrontMatterFull → {name, description, maxTurns, skills, ...}
   │         ├─ 正文 → 变量替换 ${CODEBUDDY_PLUGIN_ROOT}
   │         └─ 产出 {name, instructions, asTool:true, tags:[...,"<plugin>@<mk>"]}
   ├─ SkillExtensionLoader.load（读 skills[] + 兜底扫 skills/）
   └─ 读 <plugin>/settings.json（仅 agent / subagentStatusLine 两个 key）
   ▼
【CLI】PluginsProductProvider.provide → product.agents               mjs 984
   ▼
【CLI】AgentManager.registerPluginAgents → agentConfigMap            mjs 970
   ▼
【CLI】applyPluginAgentSetting                                       mjs 970
   └─ 把该 agent 的 instructions 覆盖到 default agent（成为会话人格）
   ▼
【CLI】生成 Agent 工具描述                                            mjs 1852
   └─ "Available agent types:\n- security-reviewer: ...\n- ..."
   ▼
【模型】Agent({subagent_type:"security-reviewer", name:"security-reviewer", prompt:"..."})

10 动手：三种典型场景

10.1 先做选型决策

动手前先回答三个问题，它们决定包的形态：

10.2 场景 A：单领域专家（代码审查专家）

第一步：初始化

cd <技能目录>/scripts

python3 init_expert.py code-reviewer \
  --type agent \
  --path ~/.workbuddy/plugins/marketplaces/my-experts/plugins

# 产出：
#   ~/.workbuddy/plugins/marketplaces/my-experts/plugins/code-reviewer/
#   ├── .codebuddy-plugin/plugin.json     （全是 [TODO]）
#   ├── agents/code-reviewer.md           （全是 [TODO]）
#   ├── avatars/.gitkeep
#   └── README.md

第二步：填 plugin.json

{
  "name": "code-reviewer",
  "version": "1.0.0",
  "description": "Senior code reviewer covering correctness, security, performance and maintainability.",
  "author": { "name": "Your Name", "email": "you@example.com" },
  "agents": ["./agents/code-reviewer.md"],

  "expertType": "agent",
  "agentName": "code-reviewer",

  "displayName": {
    "en": "Senior Reviewer",
    "zh": "审稿人"
  },
  "profession": {
    "en": "Senior Code Reviewer",
    "zh": "资深代码审查师"
  },
  "displayDescription": {
    "en": "Senior code reviewer skilled at correctness, security and performance across languages. Delivers severity-ranked findings with concrete fixes.",
    "zh": "资深代码审查师，精通正确性与安全性能缺陷识别，按严重程度分级输出可直接落地的修改建议。"
  },
  "avatar": "avatars/expert.png",
  "categoryId": "02-Engineering",
  "defaultInitPrompt": {
    "en": "Review this diff and list issues by severity",
    "zh": "审查这段代码，按严重程度列出问题"
  },
  "plugin": "code-reviewer",
  "tags": [
    { "en": "Code Review", "zh": "代码审查" },
    { "en": "Security Audit", "zh": "安全审计" },
    { "en": "Performance", "zh": "性能分析" }
  ],
  "quickPrompts": [
    { "en": "Review this diff and list issues by severity",
      "zh": "审查这段代码，按严重程度列出问题" },
    { "en": "Check this code for security vulnerabilities like injection and XSS",
      "zh": "检查这段代码是否存在注入、XSS 等安全漏洞" },
    { "en": "Find performance bottlenecks in this hot path",
      "zh": "找出这段热点代码的性能瓶颈" }
  ]
}

第三步：写 Agent MD

---
name: code-reviewer
description: Reviews code for correctness, security, performance and maintainability issues, output severity-ranked findings with concrete fixes.
displayName:
  en: "Senior Reviewer"
  zh: "审稿人"
profession:
  en: "Senior Code Reviewer"
  zh: "资深代码审查师"
maxTurns: 50
---

# 资深代码审查师 - 审稿人

你是一名资深代码审查师。你的职责是从正确性、安全性、性能和可维护性四个维度审查代码，
输出可执行的修改建议，而不是主观风格评判。

## 核心能力

1. **正确性审查**：识别逻辑错误、边界条件缺失、空值处理不当、并发竞态、错误 swallowed。
2. **安全审计**：识别注入（SQL/命令/模板）、XSS、越权、敏感信息泄漏、依赖漏洞。
3. **性能分析**：识别 N+1 查询、循环内重复计算、不必要同步阻塞、内存泄漏风险。
4. **可维护性**：识别重复代码、过深嵌套、命名失义、缺少错误处理。

## 工作流程

1. **通读全貌**：先读完整段代码或 diff，理解意图，不急于下结论。
2. **逐项审查**：按上述四个维度各扫一遍，记录候选问题。
3. **去伪存真**：剔除误报与纯风格问题。只保留能说清危害的问题。
4. **定位与建议**：每条问题给出文件行号、危害说明、以及具体改法。
5. **汇总输出**：按下列模板输出。

## 输出规范

严格按以下结构输出，不要省略任何一节：

### 总体结论
一句话：这段代码是否可以合并，以及最关键的阻塞问题是什么。

### 问题清单
| 严重程度 | 位置 | 类别 | 问题描述 | 建议改法 |
|---------|------|------|---------|---------|
| 阻塞 | `path/to/file.ts:42` | 安全 | 用户输入直接拼接进 SQL | 改用参数化查询 |

严重程度只取四档：`阻塞` / `严重` / `一般` / `建议`。
类别只取四档：`正确性` / `安全` / `性能` / `可维护性`。

### 亮点
列出 1-3 处写得好的地方。不要为了凑数而编造。

## 注意事项

- **不做主观风格争论**：缩进、引号、分号这类交给 linter，不出现在报告里。
- **不确定的标注不确定**：疑似问题必须标注「待确认」，不得伪装成确定结论。
- **给出行号**：没有行号的问题视为无效。
- **代码必须通过工具读取**：不要凭印象推断代码内容。
- 输出语言与用户提问语言保持一致。

第四步：头像 → 校验 → 注册

# 4. 生成头像（用 ImageGen，size 设为 1024x1024）
#    prompt 从 MD 内容反推，例：
#    "Professional cartoon-style illustration avatar, a senior code reviewer,
#     wearing glasses, focused and meticulous expression,
#     code diff lines and warning badges floating in background.
#     Bust shot, facing forward. Clean simple blue-purple-toned background.
#     High quality, professional, natural."
#    → 保存到 avatars/expert.png

# 5. 校验
python3 validate_expert.py ~/.workbuddy/plugins/marketplaces/my-experts/plugins/code-reviewer

# 6. 注册（会二次校验 + 写 marketplace.json + 写 .created-by-session）
python3 register_expert.py ~/.workbuddy/plugins/marketplaces/my-experts/plugins/code-reviewer

# 7.（可选）打包分享
python3 package_expert.py ~/.workbuddy/plugins/marketplaces/my-experts/plugins/code-reviewer ./dist

10.3 场景 B：专家团（代码质量攻坚团）

Team 型的关键在于主理人 MD 的 SOP 与约束写得够不够硬 —— 因为这是唯一的保障。

目录结构

plugin.json 要点

{
  "name": "code-quality-team",
  "version": "1.0.0",
  "description": "Multi-role team that audits and fixes code quality issues through a SOP pipeline.",
  "agents": [
    "./agents/code-quality-team-lead.md",
    "./agents/cq-security-auditor.md",
    "./agents/cq-perf-analyst.md",
    "./agents/cq-maintain-reviewer.md",
    "./agents/cq-fix-writer.md"
  ],

  "expertType": "team",
  "agentName": "code-quality-team-lead",
  "teamInfo": {
    "leadAgent": "code-quality-team-lead",
    "memberAgents": [
      "cq-security-auditor",
      "cq-perf-analyst",
      "cq-maintain-reviewer",
      "cq-fix-writer"
    ]
  },

  "displayName": { "en": "Code Quality Team", "zh": "代码质量攻坚团" },
  "profession":  { "en": "Code Quality Team", "zh": "代码质量攻坚团" },   ← 必须与 displayName 一致
  ...
  "members": [
    { "id": "code-quality-team-lead", "name": {"en": "Shen", "zh": "沈把关"},
      "profession": {"en": "Quality Director", "zh": "质量总监"},
      "avatar": "avatars/code-quality-team-lead.png", "role": "lead" },
    { "id": "cq-security-auditor", "name": {"en": "Yu", "zh": "于无隙"},
      "profession": {"en": "Security Auditor", "zh": "安全审计师"},
      "avatar": "avatars/cq-security-auditor.png", "role": "member" },
    ...
  ]
}

主理人 MD 骨架（这是团队的灵魂）

---
name: code-quality-team-lead
description: Lead that orchestrates a code quality pipeline across security, performance, maintainability and fix implementation.
displayName:
  en: "Shen"
  zh: "沈把关"
profession:
  en: "Quality Director"
  zh: "质量总监"
maxTurns: 180
---

# 代码质量攻坚团 - 主理人

你是代码质量攻坚团的主理人沈把关 · 质量总监。你负责按 SOP 编排团队完成代码质量攻坚，
你是协调者，不是执行者。

## 团队成员

| Agent ID | 姓名 | 职责 | 什么时候调它 |
|---------|------|------|------------|
| cq-security-auditor | 于无隙 | 安全审计 | 需要找注入/XSS/越权/泄漏 |
| cq-perf-analyst | 马立行 | 性能分析 | 需要找瓶颈/慢查询/内存问题 |
| cq-maintain-reviewer | 易读通 | 可维护性 | 需要找重复/嵌套/命名问题 |
| cq-fix-writer | 何补拙 | 修复实施 | 拿到问题清单后要落地修改 |

## 工作流路由（收到请求时首先判断）

| 场景 | 判定条件 | 走哪条 |
|------|---------|--------|
| 全量攻坚 | 用户要求完整审查 + 修复 | 标准 SOP |
| 只查不改 | 用户只问「有什么问题」 | 并行审查，跳过 cq-fix-writer |
| 单一维度 | 用户只问安全 / 只问性能 | 直调单一成员 |
| 已知问题求修 | 用户已经列出问题清单 | 直调 cq-fix-writer |

## 标准 SOP

### Phase 1（并行，无数据依赖）
同一条消息内同时 spawn：
- cq-security-auditor → 安全问题清单
- cq-perf-analyst → 性能问题清单
- cq-maintain-reviewer → 可维护性问题清单

**三个成员互不通信，全部回传给你。**

### Phase 2（串行，依赖 Phase 1）
你把 Phase 1 的完整产出原文合并成一份问题清单，交给 cq-fix-writer：
- 按严重程度排序
- 标注哪些需要修、哪些仅建议
- 带上每个问题的原文位置信息

cq-fix-writer 输出修改方案 + 具体代码。

### Phase 3：最终报告
你汇总所有产出，向用户输出交付总结。

## 团队协作机制（铁律）

你必须走正式的团队协作流程，严禁简化或跳过：

1. **建立团队**：任务开始时由你亲自创建团队（TeamCreate），命名 `cq-<项目简称>`。
   团队创建必须且只能由你执行，严禁委派任何成员创建团队。
2. **调度成员**：按 SOP 阶段将成员拉入协作、下发独立任务。
   成员作为独立协作方输出专业产出，不得由你代写。
3. **消息中转**：成员产出回传给你，由你汇总、转交下一阶段。
   所有跨成员信息流必须经你中转，不得互相直连。
4. **成员结论为准**：任何专业产出必须由对应成员输出后再采信，你只做编排与汇编。

### 严禁行为

- ❌ 禁止跳过 TeamCreate，直接自己模拟成员发言或并行写出多角色内容
- ❌ 禁止自己代写任何团队成员的专业产出
- ❌ 禁止未完成前序阶段就跳到后续阶段
- ❌ 禁止让成员互相直连通信
- ❌ 禁止 spawn 主理人自己

### 子任务命名（CRITICAL）

调度每位成员时，必须在 Agent 工具的 `name` 参数传入该成员的 Agent ID，
`subagent_type` 也传入相同的值。禁止省略 name，禁止用中文名或自创名称：

- `name: "cq-security-auditor", subagent_type: "cq-security-auditor"`
- `name: "cq-perf-analyst", subagent_type: "cq-perf-analyst"`
- `name: "cq-maintain-reviewer", subagent_type: "cq-maintain-reviewer"`
- `name: "cq-fix-writer", subagent_type: "cq-fix-writer"`

## 协作规则

1. 每阶段结束后，将完整产出原文传递给下一阶段成员，不要只传摘要。
2. 每完成一个阶段向用户简要通报进度。
3. 所有输出使用与用户原始需求相同的语言。
4. 最终报告必须包含：TL;DR、问题清单、修改文件清单、遗留问题、用户下一步建议。

10.4 场景 C：带专属工具的专家

当任务里有确定性计算时，别让模型用自然语言硬算 —— 给它脚本。

---
name: db-guardian
description: Database health guardian that diagnoses slow queries, index issues and connection pool saturation.
displayName:
  en: "Guardian"
  zh: "守库人"
profession:
  en: "Database Reliability Engineer"
  zh: "数据库可靠性工程师"
maxTurns: 60
skills: [slowlog-scan]              # 预加载本包技能，会自动解析为 db-guardian:slowlog-scan
---

# 数据库可靠性工程师 - 守库人
...

## 数据获取方式

扫描慢日志时，必须调用脚本而非自己推算：

    ${CODEBUDDY_PLUGIN_ROOT}/skills/slowlog-scan/scripts/scan.py --top 20 --unit ms

执行计划分析使用 PATH 中已就绪的工具：

    dbstat --explain "<sql>"

诊断规则参考：

    ${CODEBUDDY_PLUGIN_ROOT}/references/rules.md

11 12 个反直觉的坑

以下每一条都是官方文档口径与代码实现不一致，或者文档没写但会咬人的地方。按踩坑频率排序。

12 排错手册

A 速查表

A.1 命令速查

SCRIPTS="<技能目录>/scripts"
XP="~/.workbuddy/plugins/marketplaces/my-experts/plugins"

# ① 初始化
python3 $SCRIPTS/init_expert.py <name> --type agent|team --path $XP

# ② 校验
python3 $SCRIPTS/validate_expert.py $XP/<name>

# ③ 注册（必经）
python3 $SCRIPTS/register_expert.py $XP/<name>

# ④ 打包
python3 $SCRIPTS/package_expert.py $XP/<name> ./dist

# ⑤ 批量
python3 $SCRIPTS/batch_create.py

A.2 关键路径速查

A.3 行业分类（categoryId）

A.4 头像背景色调映射

同一团队的头像必须共用风格锚定词，背景色调由 categoryId 决定：

B 本机实证数据

以下是对这台机器上 16 个真实落盘专家包的统计。它们是「别人怎么写」的一手参考， 也可用来校准自己的包规模。

B.1 包清单

B.2 从数据里读出的三条结论

1. 头像并非必需 —— 16 个包中 5 个没有 avatars 目录，仍能正常工作。说明市场包的头像走远程 URL 分发，落盘可省。
2. categoryId 可有可无 —— 至少 3 个包没写。它主要用于市场分类陈列，本地使用不影响功能。
3. 团队规模差异极大 —— 从 5 人到 13 人都有。结合 §11 的字符预算截断风险，5–7 人是更安全区间。

C 心智模型总结

如果只记住六句话：

C.1 给工程师的迁移建议

如果你要在自己的产品里实现类似机制，这套设计里最值得借鉴的三点：

1. 文件即配置：整个包无需一行代码、无需构建、无需 schema 注册，纯文本即可分发。 代价是没有编译期检查，所以才需要 validate_expert.py 这类外部校验来补位。
2. 把插件系统当作底座：专家不自建加载器、不自建市场、不自建生命周期， 而是复用插件基础设施换取版本、分发、命名空间、PATH 注入等能力。典型的复用优于新建。
3. 把编排留给模型：团队 SOP 不写进代码而写进 prompt，换来零开发成本的领域适配 —— 换个 MD 就从交易团变成开发团。代价是没有确定性保障，需要在 prompt 里用冗余约束来补偿。 这个取舍是这类系统的核心设计张力。