maka/docs/archive/expert-team-plan.md

专家团 (Expert Team) — 调研与实现方案

目标：在 maka-agent 中实现"专家团 / 数字同事"功能。 本文基于对 WorkBuddy（腾讯 CodeBuddy 换皮）与 QoderWork（阿里 Qoder）两款已安装应用的逆向， 加上对 maka-agent 自身架构的映射，给出可落地的设计。 逆向原始 spec：scratchpad/RE-workbuddy-experts.md、scratchpad/RE-qoderwork-agents.md、scratchpad/maka-architecture-map.md。

---

1. 调研结论：两家怎么做的

1.1 WorkBuddy —— 完整的"专家中心 + 数字同事"（最值得抄）

WorkBuddy 有两个不同层次，不要混为一谈：

1. 专家 / 专家中心 (Expert Center) —— 一个市场目录，331 个专家人格、13 个分类，托管在腾讯 COS。

   • Manifest：https://acc-1258344699.cos.accelerate.myqcloud.com/workbuddy/expert-marketplace/expert_center.json， 并行拉取 internalExpert.json / externalExpert.json 合并（企业内/外部专家隔离）， 缓存到 ~/.workbuddy/app/cache/experts/（sha256 + cacheFormatVersion:2）。
   • 每个专家 = 一个 plugin bundle（zip 懒加载解压），人格来自一个 agent markdown（promptFile）+ 头像 PNG。
   • expertType 两种：agent（285 个，单人格） 与 team（46 个，即"专家团"）。

2. 数字同事 / 云助理 (Digital Colleague) —— 用户自建的持久化助理，它"雇佣(hire)"一个专家/专家团作为能力来源， 拥有自己的昵称+头像+高级配置（专家/仓库/资料库/模型），可绑定 IM 渠道（QQ/微信/飞书/钉钉）、云端运行、被 @、被定时调度。 —— 这是把"专家"产品化的外壳。（注：collab-* 模块是人与人的工作区协作，与专家无关。）

专家条目 schema（关键字段）：

id, categoryId, displayName{en,zh}, profession{en,zh}, description{en,zh},
promptFile,                # COS 相对路径，指向人格 md，如 /plugins/content-creator/agents/content-creator.md
avatar,                    # /avatars/ContentCreator.png
defaultInitPrompt{en,zh},  # 召唤后自动注入的第一条消息
quickPrompts[{en,zh}],     # 组合框里的建议起手 prompt
tags[{en,zh}],             # 能力标签 chip
expertType: "agent"|"team",
agentName, plugin,         # 指向 plugin 内的 subagent id
isOPC, operationalTag, visibility, author,
members[]                  # 仅 team 有

专家团 (team) 的结构 —— 就是 orchestrator→worker 多智能体：

members: [
  { id, displayName, profession, avatar, promptFile, role: "lead" | "member" }
]

• team 顶层的 agentName/promptFile 指向 lead；每个 member 有自己独立的人格 md。
• 运行时：lead 作为唯一对话 agent，通过 Agent 工具（subagent_type = member.id）派生 member 子代理。
• 协作协议写在 lead 的人格 prompt 里：TeamCreate（建团，只能 lead 做）→ 顺序/并行调度成员 → 成员回传， 星型拓扑（所有跨成员信息经 lead 中转，成员之间不直连），lead 不模拟成员输出、只汇总。
• 没有服务端 router——编排完全靠 lead 的人格 prompt，跑在本地 Claude-Code 式 subagent runtime 上。

人格 md 格式（不内联在 manifest，激活时才拉取）：YAML frontmatter + markdown body。

• frontmatter：name, description, color(强调色), emoji, vibe；team lead 额外 maxTurns:200。
• body 是强身份覆盖模板：🚨 CRITICAL IDENTITY DIRECTIVE（"你是 X 且只是 X，绝不暴露底层模型"）+ Role Definition / Core Capabilities / 内置 Skill 使用场景（自动触发的技能）/ Final Identity Reminder。

持久化（sqlite ~/.workbuddy/workbuddy.db）：sessions 表带 expert_id / expert_locale / expert_runtime_identity（人格快照，manifest 变了会话也钉住）/ expert_marketplace；automations 也带 expert_id（定时任务可绑专家）。

1.2 QoderWork —— 没有"专家团"，但有可借鉴的分层

QoderWork 没有命名人格选择器。它的三层值得参考：

层	单元	说明
人格/性格	awareness/（SOUL.md 等 + soul-presets：果断/沉稳/高效/贴心）	单 agent 身份调优
能力打包	Plugin（专家套件） = Skills + Commands + Connectors(MCP)	"装一个角色的整个工具箱"，最接近"专家"
运行时编排	Sub-agents（agents/*.md，Agent(subagent_type,...) 派生）	真·多智能体

• plugin-creator skill 原话："Skill 是一件工具，Plugin 是一个角色的整个工具箱。"按角色/行业分类（电商/产品/法务/财税）。
• ai-slides LegoKit 是教科书式 orchestrator→worker 流水线：6 个命名 subagent（researcher/designer/reviewer/notes-writer）， 硬性委派边界，单轮多 tool_use 块并行，产物落盘 + JSON 指针交接（回传指针不回传大 payload）。
• 可借鉴的具体做法：Markdown+frontmatter 的 agent 按 description 自动路由；单轮 fan-out + 等待 fan-in（不要后台 detach）； 每个 worker 入口自校验；性格 preset；用 AskUserQuestion 引导"自建专家"。

---

2. maka-agent 现有可复用底座（三块几乎现成）

后端主轴（ARCHITECTURE.md）：Desktop/TUI/Headless → SessionManager → AgentRun → Model + Tool Runtime → 事件日志 → 投影。 存储是文件/JSON（无 sqlite）。

关注点	复用/扩展	位置
专家人格注入	mode: 标签 + prompt fragment（照抄 Deep Research）	apps/desktop/src/main/system-prompt-main.ts（已有 childInstruction seam）；packages/core/src/deep-research.ts（mode:deep_research 先例）
专家=带工具作用域的专业 agent	扩展 BUILTIN_AGENT_DEFINITIONS（每条已带 systemPrompt）	packages/runtime/src/agent-catalog.ts、subagent-tools.ts（agent_spawn/SessionManager.spawnChildAgent）
专家目录 + 按需安装	克隆 managed/bundled 技能目录	apps/desktop/src/main/managed-skill-sources.ts、bundled-skill-catalog.generated.ts、skills.ts（install→skill.lock.json→baseline→update diff，PR #842）
专家定义文件格式	复用 SKILL.md frontmatter 解析	packages/runtime/src/skills.ts（parseSkillFrontMatter）
专家选择器 + 中心 UI	克隆"市场/内置/已安装"三 tab	packages/ui/src/skills-panel.tsx、nav-selection.ts、session-sidebar-nav.tsx、module-pages.tsx
专家聊天界面	普通会话 + expert 标签	packages/ui/src/chat-view.tsx、composer.tsx
非 UI 一致性（CLI/headless）	共享 runtime prompt builder，自动继承	packages/cli/src/cli-system-prompt.ts、packages/headless/src/tools.ts

关键判断：

1. maka 的 agent-catalog.ts（每个 AgentDefinition 带 id/name/description/systemPrompt/tools/permissionMode） 与 WorkBuddy 的"专家 = 带人格的 subagent"结构同构。→ 单专家直接落在这里。
2. maka 的 subagent runtime（spawnChildAgent + agent_spawn 工具，父子 AgentRun） 与 WorkBuddy team 的"lead 通过 Agent 工具派生 member"结构同构。→ 专家团直接落在这里。
3. maka 的技能市场（远程/内置目录 + contentSha256 + install/lock/update） 是"专家中心目录"现成模板，只差一个 sourceType:'remote' HTTP 拉取。
4. ⚠️ 约束：worktree 隔离的子代理目前 fail closed（没有 worktree executor）。专家团 member 先用非隔离子代理跑。

---

3. 推荐方案

3.1 数据模型：专家 = 一份 EXPERT.md（SKILL.md 同族）

一个专家一个目录，EXPERT.md = frontmatter + 人格 body：

---
id: content-creator
displayName: { zh: 文博凯, en: Kai }
profession: { zh: 内容创作专家, en: Content Creator }
description: { zh: ..., en: ... }
category: 06-ContentCreative
avatar: avatar.png
color: teal            # 强调色（借 WorkBuddy）
expertType: agent      # agent | team
allowed-tools: [...]   # 声明式，不授予；PermissionEngine 仍是权威
quickPrompts: [{ zh, en }]
defaultInitPrompt: { zh, en }
# team 专用：
members:
  - { id, displayName, profession, promptFile, role: lead|member }
---
<身份指令 + Role / Capabilities / 内置技能触发场景 + 身份提醒>

• 复用 parseSkillFrontMatter（扩字段），复用技能的 install/lock/baseline/update 生命周期。
• 目录：内置 bundled-expert-catalog.generated.ts（复用 memory 里已逆向的 13 skills 那套种子流程）； managed ~/.maka/experts/<id>/EXPERT.md；后续加 sourceType:'remote' 拉远程 manifest（COS 那套）。

3.2 运行时：单专家 vs 专家团

• 单专家（expertType=agent）：给会话打 mode:expert:<id> 标签 → system-prompt-main.ts 按标签 gate 出人格 fragment， 经 childInstruction 边界注入（继承权限/隐私/工作区约束）。照抄 Deep Research 的 mode:deep_research 路径。 召唤时把 defaultInitPrompt 作为首条消息注入，quickPrompts 渲染成起手按钮。
• 专家团（expertType=team）：lead 作为对话 agent（mode:expert:<teamId> + lead 人格）， lead 人格 prompt 里写 orchestrator 协议（TeamCreate→派发→回传，星型）， member 作为 AgentDefinition 注册进 catalog，lead 用现有 agent_spawn 派生（subagent_type=member.id）。 不后台 detach：单轮 fan-out + 等待 fan-in（借 Qoder 教训）；member 回传落盘+指针。

3.3 UI

• 导航：nav-selection.ts 加 {section:'experts'}；session-sidebar-nav.tsx 加"专家团/同事"入口；module-pages.tsx 加 ExpertsPage。
• 专家中心：克隆 skills-panel.tsx 的 市场/内置/已安装 三 tab + 分类过滤 + 搜索 + 卡片"召唤"。
• 专家聊天：就是普通 chat-view.tsx 会话，带 expert 标签 + 头像 + color 强调色（借 use-expert-theme 思路，light/dark 感知）。

3.4 分期落地

阶段	交付	复用
P0 单专家 MVP	EXPERT.md 格式 + 内置目录 + mode:expert: 注入 + 专家中心 UI + 召唤即聊	Deep Research 注入路径、技能目录/UI、agent-catalog
P1 专家团	team schema + lead orchestrator 人格 + member 子代理派发（非隔离）+ 团队卡片	spawnChildAgent/agent_spawn、subagent runtime
P2 数字同事	持久化助理外壳（自建昵称/头像/雇佣专家/配置仓库·资料库·模型）+ 定时调度	会话标签、scheduled-task-store
P3 远程专家中心 + 分享	sourceType:'remote' 拉 COS 式 manifest + 缓存校验 + 自建专家导出/导入（安全扫描）	managed-skill-sources 远程化、lock/sha256
P4（可选）IM 绑定 / 云端 / @ 协作	绑 IM 渠道、云端运行、@ 数字同事	需新连接层，评估

3.5 待你拍板的分叉点

1. 专家人格的落点：（a）纯 overlay = 标签会话 + 人格 fragment（最轻，先做）vs（b）数据驱动 AgentDefinition = 带独立工具作用域/权限（重，给"真·工具受限同事"）。建议 P0 走 (a)，P1 team member 走 (b)。
2. 专家团 member 隔离：先接受非隔离（共享 cwd）还是先补 worktree executor？建议先非隔离，P1 后再评估隔离。
3. 目录来源：先只做内置 + 本地 managed（P0），远程 COS 式 manifest 放 P3；还是一开始就上远程？

---

4. 一句话总结

WorkBuddy 的"专家 = 带身份覆盖人格的 subagent，专家团 = 一个 lead 星型编排多个 member subagent，专家中心 = COS 上的 plugin 市场，数字同事 = 雇佣专家的持久化助理外壳"。这套模型和 maka-agent 的 agent-catalog（人格 subagent）+ spawnChildAgent（多智能体）+ 技能市场（目录/安装/锁）+ Deep Research（mode 注入） 四块现有底座几乎一一对应，可分 4~5 期低风险落地。