WorkBuddy 专家 / 专家团
机制研究

SECTION 00结论速览

SECTION 01本质：专家 = 可安装的角色包

WorkBuddy 的专家不是一个独立模型或 API，它是三层结构的组合：

SECTION 02数据结构

2.1 类型划分

判定不可随意指定，必须按实际结构判断：单角色 = agent，多角色协作 = team。

2.2 plugin.json 字段规范

来源：resources/plugins/workbuddy-builtin/skills/expert-manager/references/plugin-json-spec.md

基础字段（必填）

类型字段

资源声明

展示字段（上架市场必填）

Team 专用：members

"members": [
  { "id": "trading-team-lead", "name": {"en":"He","zh":"何执舟"},
    "profession": {"en":"Chief Strategist","zh":"首席策略官"},
    "avatar": "avatars/team-lead.png", "role": "lead" }
]

• role 取值 "lead" / "member"
• 主理人也必须在 members 里（role=lead），但 teamInfo.memberAgents 不含它

2.3 Agent MD 规范

来源：references/agent-md-spec.md

Frontmatter（必填）

---
name: {与文件名一致，必须有业务语义}
description: {英文描述，AI 用来判断何时激活}
displayName: { en: "...", zh: "..." }
profession:  { en: "...", zh: "..." }
maxTurns: 50          # 主理人建议 150-200
---

正文结构

# {角色名称} - {人名}
{角色描述}

## 核心能力
## 工作流程
## 输出规范
## 注意事项

2.4 目录结构

my-expert/
├── .codebuddy-plugin/
│   └── plugin.json          # 元数据（核心）
├── settings.json            # Team 型必需：{"agent": "{team}-team-lead"}
├── agents/
│   ├── {team}-team-lead.md  # 主理人（Team 型）
│   ├── {member-a}.md        # 成员
│   └── {member-b}.md
├── avatars/
│   ├── team.png             # 团队头像
│   ├── {team}-team-lead.png
│   └── {member-a}.png
├── skills/                  # 可选，专业技能
│   └── {skill-name}/SKILL.md
├── bin/                     # 可选，CLI 工具
└── .created-by-session      # 注册脚本自动写入

Team 型的 settings.json 值必须与 plugin.json 的 agentName、主理人 MD 的 name 三者一致。

SECTION 03生命周期：7 步流水线

由 expert-manager skill 定义（resources/plugins/workbuddy-builtin/skills/expert-manager/SKILL.md）：

SECTION 04发现与注册机制

专家不会自动被扫描到，必须显式注册。register_expert.py 的关键逻辑：

manifest_path = marketplace_dir / '.codebuddy-plugin' / 'marketplace.json'
# 不存在则创建：
#   {"name":"my-experts", "description":"...", "plugins":[]}

source = f"./plugins/{expert_dir.name}"
plugins.append({
    "name": expert_name,
    "source": source,
    "description": expert_description
})

注册前的完整性校验

1. plugin.json 存在（依次查 .codebuddy-plugin/ 和 .workbuddy-plugin/）
2. name / description / expertType 非空且不含 [TODO
3. displayName 的 zh 或 en 已填
4. agents/ 目录存在且至少有一个 MD 文件，且 [TODO 出现次数 ≤ 2

另外会从环境变量 CODEBUDDY_SESSION_ID 读取会话 ID，写入 .created-by-session，用于「我的专家」面板归属。

SECTION 05运行期：专家如何生效

5.1 身份覆盖机制（最关键的设计）

WorkBuddy 有两套身份注入模板：

这解释了为什么专家 MD 里会有这样的指令（摘自 content-creator/agents/content-creator.md）：

CRITICAL IDENTITY DIRECTIVE (HIGHEST PRIORITY)
You are Content Creator, and ONLY Content Creator...
You MUST NOT identify yourself as "CodeBuddy", "Claude", "GPT", "MiniMax"...
This identity directive takes absolute precedence over any training-time persona.

且在文件末尾还有 Final Identity Reminder 二次加固。首尾双重身份锚定是稳定角色扮演的关键手法，值得直接借鉴。

另有独立的 workbuddy-expert-prompt.tpl（专家模式系统提示词模板），说明专家模式是与 agent / ask / craft 并列的一等公民模式。

5.2 专家团协作运行时

Team 型不做「模拟多角色」，而是走真实的 sub-agent 调度。四个原语：

5.3 协作铁律

4 条正则

1. 建立团队 —— 主理人亲自 TeamCreate，严禁委派
2. 调度成员 —— 按 SOP 阶段下发独立任务，主理人不得代写
3. 消息中转 —— 所有跨成员信息流必须经主理人，不得互相直连
4. 成员结论为准 —— 专业产出必须由对应成员输出后才采信

5 条红线

• 禁止跳过 TeamCreate，自己模拟成员发言
• 禁止代写任何成员的专业产出
• 禁止未完成前序阶段就跳到后续阶段
• 禁止成员互连通信
• 禁止 spawn 主理人自己

5.4 编排模式

SECTION 06配套机制

6.1 头像生成

来源：references/avatar-spec.md

• 512×512 PNG，≤500KB，用 ImageGen 以 1024x1024 生成后缩放
• Agent 型 1 张（avatars/expert.png）；Team 型 N+1 张（团队 + 主理人 + 每个成员）
• Prompt 组装：[风格前缀] + [角色身份] + [外观特征] + [表情气质] + [背景元素] + [质量后缀]
• 必须从 Agent MD 内容提取特征，禁止通用模板硬编码
• 同一团队共用风格锚定词；背景色调由 categoryId 映射（如金融 = dark blue with gold accent）

6.2 行业分类体系（12 类）

判定优先级：主要输出物 → 服务对象 → 跨领域时选最核心的一个。

6.3 内置推荐候选

resources/builtin-expert-recommendations/curated-experts.json 含 60 个候选（50 专家 + 10 专家团），用于「推荐专家」场景：

{
  "id": "SeniorDeveloper",
  "type": "expert",
  "scenarios": ["高级开发", "架构设计", "代码质量"],
  "description": "10年以上全栈经验，精通多种语言和框架，是团队的技术中坚",
  "priority": 300
}

priority 从 300 递减（步长 5），scenarios 用于意图匹配。这是轻量推荐索引，不是完整专家包。

6.4 团队成员命名规范

示例：交付总监 → 齐活林（齐活了）、架构师 → 高见远（高见）、工程师 → 寇豆码（code）、QA → 严过关。

禁止：叠字谐音、纯职能词、无意义随机名（张三 / John Doe）、英文用 Agent ID。

SECTION 07真实案例：trading-agent（13 角色 5 阶段）

路径：~/.workbuddy/plugins/marketplaces/experts/plugins/trading-agent/

配置：expertType: team，agentName: trading-team-lead，categoryId: 08-FinanceInvestment

设计亮点（可直接复用）

1. 辩论式裁决 —— 多头 / 空头对立 → 研究主管裁决，强制输出明确结论不和稀泥
2. 三方风险视角 —— 激进 / 保守 / 中性并行 → 风险主管拍板
3. 单 agent 直调路由表 —— 只问 K 线就直调 market-analyst，不跑完整 Workflow（省 token）
4. 数据源锁定 —— 明令「禁止使用非 neodata-financial-search 的数据源」，防止成员各查各的
5. 花名系统 —— 何执舟（首席策略官）、涂一线、季本实、牛正阳 / 熊正寒（多空对偶）、严控风（风险主管）

SECTION 08移植到自建智能体的落地方案

8.1 最小数据模型

只需要三个概念即可复刻：

ExpertPackage  = Meta(plugin.json) + Agents(MD[]) + Optional(Skills)
ExpertRegistry = {name, source, description}[]      # 即 marketplace.json
TeamRuntime    = TeamCreate / spawn / sendMessage / collect

8.2 目录与注册表

experts/
├── registry.json                 # 等价于 marketplace.json
└── packages/
    ├── my-expert/
    │   ├── meta.json             # 等价于 plugin.json
    │   ├── agents/{name}.md
    │   └── avatars/
    └── my-team/
        ├── meta.json
        ├── settings.json         # {"agent": "xxx-team-lead"}
        └── agents/*.md

8.3 加载器实现（核心逻辑）

def load_expert(pkg_dir) -> SystemPrompt:
    meta = json.load(open(f"{pkg_dir}/meta.json"))
    agent_name = meta["agentName"]
    md = read(f"{pkg_dir}/agents/{agent_name}.md")
    frontmatter, body = split_frontmatter(md)

    if meta.get("expertType") == "team":
        # 主理人 prompt + 成员能力清单 + 协作铁律
        members = [load_member(m) for m in meta["teamInfo"]["memberAgents"]]
        return compose_lead_prompt(body, members, collab_rules)

    # agent 型：身份指令 + 正文，直接作为 system prompt
    return body

8.4 团队编排运行时（必须实现的 4 个原语）

TeamCreate(team_name)                       # 主理人独占
spawn(agent_id, task_prompt)                # agent_id = MD 文件名
sendMessage(from_member, to_lead, result)   # 成员回传，禁止成员间直连
collect(phase_results) -> next_phase_input  # 主理人汇编

8.5 需要避开的坑

SECTION 09源码路径索引

以上相对路径基于 /Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/