唤醒组员 apherchin/dsh-sidefork-a-teammate

dsh-sidefork-a-teammate

中文 ｜ English

给 DeepSeek Harness 加一条由人手动触发的 /teammate 入口：不必先让模型去调 spawn_teammate，你自己就能从输入框拉起一个组员（teammate）。

命令面只有这一条 /teammate，选中后先选模式（new teammate / fork teammate），再填一行 名字 | 描述 | 任务 提交。
不进模型上下文、不计 token。

命令面板里的「唤醒组员 teammate」

选中后的两个模式：new teammate / fork teammate

☝️ 真实截图：左侧命令面板里这一行显示为 「唤醒组员 teammate」（本地化标题 + 命令名作别名）；选中后弹出两个模式，文案就是 new teammate 全新对话，不继承本会话历史 与 fork teammate 并行分支，继承本会话已完成的回合。

一条命令、两级入口

1. 输入框敲 /teammate —— 命令菜单里只有它；
2. 选中后弹模式选择：new teammate / fork teammate；
3. 选中模式后弹自绘输入弹窗，填一行 名字 | 描述 | 任务，提交即创建。

new teammate 与 fork teammate 到底差在哪（重点）

两者都是"拉起一个组员"，差别只有一个：新组员要不要继承你这边的对话历史。这一个差别决定了它们的适用场景完全不同。

| | new teammate | fork teammate |
| 官方文案（截图原文） | 全新对话，不继承本会话历史 | 并行分支，继承本会话已完成的回合 |
| 内部 context | fresh | fork |
| 映射到 provider | spawn | fork |
| 新组员能看到的历史 | 什么都看不到——全新会话 | 本会话里已完成的回合（Lead 侧的对话历史） |
| 它拿到的第一条消息（有任务时） | 一句"你是全新对话，不继承历史，别和主会话混在一起"的问候语 + 空行 + 任务：<你写的任务> | 只有任务本身（fork 的目的就是并行去做事，以你的指令为先） |
| 它拿到的第一条消息（没任务时） | 只有那句问候语 | 一句话自述"我是并行分支" |
| 适合用来干 | 一件与当前话题无关的新活；不想让它被上下文带偏 | 一件必须看懂当前上下文的活，例如"照我们刚讨论的方案去实现/去查" |
| 名字/描述/任务 | 同样一行三段，规矩一致 | 同样一致 |

身份前缀两者都有：任何组员的第一条消息前都固定带一段 You are teammate "…" + 怎么用 send_message / list_agents （那是运行时给的团队身份说明，不是可省的废话）。

一句话判别：

- 要"接着我们刚才说的往下做" ⇒ 用 fork teammate（它继承已完成的回合，能看懂你在说什么）；
- 要"另起一摊、别被我这边干扰" ⇒ 用 new teammate（它从零开始，上下文干净）。

⚠️ fork 继承的是 Lead 侧已完成的回合；你正在打、还没结束的这一轮不在继承范围内。
⚠️ 两者创建的都是发起请求那个会话（页面上打开的那个）的组员 ⇒ 先打开目标会话再敲命令。
⚠️ 名额受服务端 maxMembers 限制（本机 profile 为 8）；满了报 TEAM_MEMBER_LIMIT。

怎么填那一行

/teammate → 选 new / fork → 输入「名字 | 描述 | 任务」→ 提交

| 段 | 含义 | 省略 / 留空的行为 |
| 1 | 名字 | 可留空 ⇒ 从 24 个常用英文名里随机取（如 alice）；被占用就换下一个候选，最多试 6 个 |
| 2 | 描述 | 可省略；服务端上限 200 字符，超出被截断 |
| 3 | 初始任务 | 可省略；第 3 段之后再出现 | 一律并入任务文本（任务里可以写竖线） |

- 显式名字要求小写 kebab-case（a-z0-9 与中间单个连字符）、≤64 字符、不能叫 lead； 显式非法名在本地就拦下；显式重名不会偷偷换名，而是原样报 TEAM_MEMBER_NAME_TAKEN。
- 成功后弹窗不自动关闭，就地显示 已创建 teammate "<name>"（会话 <id>）（这是唯一能看到新会话 id 的地方），按钮从「取消」变「关闭」、同时「创建」键置灰。

架构（host 一条路由 + client 半边）

- host 半边 index.mjs：不注册任何命令，只提供一条路由 POST /api/team.spawn （inject = ["connection", "agents", "agentTeams"]）。内部用 ctx.agents.get(sessionId) 拿到接收 agent，再调 ctx.agentTeams.spawnTeammate(agent, {...}) —— 与模型侧 spawn_teammate 工具是同一个 host 服务，所以能力 1:1 复刻。缺 agentTeams 时只记一条 warn、不注册路由（不影响启动）。
- client 半边 client.js：注册 /teammate 的 commandUi 贡献项（kind: "popupSelect"），并在 shell.overlay 槽位挂自绘输入弹窗，用 fetch 调上面那条路由。

路由契约

POST /api/team.spawn content-type: application/json
{ "sessionId": "…", "context": "fresh" | "fork", "line": "名字 | 描述 | 任务" } 成功 200：{ "ok": true, "name": "alice", "sessionId": "session-…" } ｜ 失败：{ "ok": false, "code": "…", "message": "…" }

| code | HTTP | 含义 |
| BAD_JSON | 400 | body 不是合法 JSON |
| INVALID_INPUT | 400 | context 不是 fresh/fork、line 不是字符串、或名字不合法 |
| INVALID_SESSION_ID | 400 | sessionId 缺失 / 非字符串 / 空串 |
| AGENT_UNAVAILABLE | 409 | 该会话当前没有活动 agent（请先打开该会话再试） |
| TEAM_MEMBER_NAME_TAKEN | 409 | 显式名字已被占用（随机取名会换候选；连续 6 个都占用也报这个码） |
| TEAM_MEMBER_LIMIT | 409 | 名额已满 |
| TEAM_INVALID_MEMBER_NAME | 400 | 服务端名字校验拒绝 |
| 其它 TeamError | 500 | 原样透传 code/message（例如 TEAM_LEAD_REQUIRED） |

客户端侧：非 JSON 响应（含 5xx 的 HTML 错误页）统一归一成 HTTP_<status>。

安全边界

- 路由走浏览器 cookie 认证（未登录的 /api/ 一律 401/403，鉴权闸门先于路由分发）。
- ⚠️ sessionId 由页面提交，host 无法验证它属于发起请求的那个客户端 —— 一个已登录的浏览器可以要求"给任意 sessionId 创建 teammate"。
单操作者模型下可接受（本机 DSH 只有一个人用）；若将来出现多用户 / 多客户端共享一个 DSH 实例，必须补一层"sessionId 归属"绑定校验。

安装

dsh plugin --profile <你的 profile> add dsh-sidefork-a-teammate

包内声明了 dsh.bundle.patch，所以 dsh plugin 会自动把它记进 dsh.profile.bundles，无需手工编辑 profile。然后重启 DSH（打包版没有「刷新页面」）。

手工兜底：在 profile 的 cordis.patch.yml 追加

- insert:
- id: team-commands
name: dsh-sidefork-a-teammate

⚠️ name: 必须写包名，不要写绝对路径。实测（Win11 VM + dsh 0.2.0-rc.2）：写死本机路径时该行会被静默 disable （disabling profile plugin row "team-commands": its declared peer dependencies cannot be validated: … lstat 'D:\'），功能整体消失、stderr 只有一行。

兼容性

- 实测环境：DSH 桌面壳 0.1.7-rc.2（页面级验收见项目内报告）；host 依赖 connection / agents / agentTeams。
- host + client 双半边：client 半边参与渲染端「每条 client entry 必须 active」的全有全无启动门禁 ⇒ apply 全程 try/catch、不挂任何硬门禁（inject: []），服务一律走嵌套 ctx.inject。
- 零 npm 运行时依赖、无构建步骤。

合规（按官方 cordis-plugin-development 对齐）

- bundle 形态：package.json 声明 dsh.bundle.patch（官方交付单位；缺它 install_bundle 会回滚整次安装）。
- 不 require 任何 Harness Client 包：官方 practices 明文禁止 require("@deepseek-ai/dsh-client-ui-primitives") 等。
本插件的 Modal / Button / IconUsersOutlineRegular / IconCloseOutlineRegular / createSnapshotStore 全部是按官方行为照抄进来的自包含实现（SVG path、CSS 规则、--dsw-alias- token 与官方一致，类名统一 dstc- 前缀）；运行期只 require react / react/jsx-runtime / react-dom（后者缺失时静默降级为就地渲染）。
- 浏览器工件的 factory id 等于包名（window.__ModuleLoader__.load({ id: "dsh-sidefork-a-teammate", … })）。
- host 与 client 的 apply 绝不外抛：最坏只是"这块 UI 不出现"，不会让整机起不来。

测试

⚠️ 本机沙箱禁止命名管道 ⇒ node --test 会 spawn EPERM 并给出误导性的 # fail 1。逐文件跑（任意 cwd）：

node test/host-smoke.test.mjs # host 半边契约与错误码：99/99
node test/client-compliance.test.mjs # 客户端合规（依赖白名单）+ 自包含原语行为：73/73

合计 172 条断言全绿。其中 client-compliance 是防回归闸门：它断言源码里除 react / react/jsx-runtime / react-dom 之外不得出现任何 require（尤其 @deepseek-ai/），并逐条验证两档文案、命令注册、overlay 注册、postTeamSpawn 的错误归一与自包含 store 的接口语义。

卸载 / 回滚

dsh plugin --profile <你的 profile> remove dsh-sidefork-a-teammate
手工装的话：从 profile 的 cordis.patch.yml 删掉 id: team-commands 那条 insert，重启 DSH。

在 DeepSeek Harness 里手动触发生成队友的方式：不用让模型调用 spawn_teammate，你自己敲 /teammate。

一条命令，两个层级：/teammate → 选模式（new teammate / fork teammate）→ 填一行 name | description | task。
整个交互不会进入模型上下文，也不消耗 token。

命令面板里的「Spawn a teammate」一行

两种模式：new teammate / fork teammate

new teammate 与 fork teammate 的区别

两者都会生成队友，唯一区别是新成员是否继承本会话的历史——这决定了什么时候用哪个。

| | new teammate | fork teammate |
| UI 里显示 | 全新对话，不继承本会话历史 (fresh conversation, inherits nothing) | 并行分支，继承本会话已完成的回合 (parallel branch inheriting completed turns) |
| context / provider | fresh / spawn | fork / fork |
| 成员能看到的历史 | 没有——全新对话 | 本会话已完成的回合 |
| 首条消息，带任务 | 一句问候（「你是全新对话，不继承任何东西，别和主会话混在一起」）+ 空行 + 任务：<task> | 只有任务——fork 就是为了去干活 |
| 首条消息，不带任务 | 只有那句问候 | 一行说明它是并行分支 |
| 适用场景 | 与当前话题无关的全新工作 | 需要当前上下文的工作，比如「把我们刚讨论的方案实现一下」 |

经验法则：「接着我们刚聊的继续」→ fork teammate；「另起一件事，别让我的上下文带偏它」→ new teammate。 两者都带同一段固定身份前言（You are teammate "…" + 怎么用 send_message / list_agents），也都会创建你提交时所在会话的队友——先打开那个会话。

单行格式

| 段 | 含义 | 留空 / 省略 |
| 1 | name | 从 24 个常见英文名里随机挑一个（重名时最多重试 6 个候选） |
| 2 | description | 可选；服务端上限 200 字符 |
| 3 | 初始任务 | 可选；后面任何 | 都算任务正文的一部分 |

显式指定的名字必须是小写 kebab-case（a-z0-9，单个连字符），≤64 字符，且不能是 lead；显式重名会以 TEAM_MEMBER_NAME_TAKEN 失败，而不是悄悄改名。

安装

dsh plugin --profile <your-profile> add dsh-sidefork-a-teammate

之后重启 DSH。手工路线：往 profile 的 cordis.patch.yml 里加 - insert: [{ id: team-commands, name: dsh-sidefork-a-teammate }]——写包名，绝不要写绝对路径（写死路径会让这一行被静默禁用）。

兼容性与合规

已在 DSH desktop 0.1.7-rc.2 上测试。宿主服务：connection / agents / agentTeams。它既是宿主又是客户端，客户端这一半要参与渲染器的全有或全无启动门禁——每个客户端入口都必须激活——所以 apply 从不抛错，也没有使用硬性 inject 门禁。

客户端不 require 任何 Harness Client 包（官方实践禁止这么做）：Modal、Button、两个图标和 createSnapshotStore 都是官方行为的自包含副本（相同的 SVG 路径、CSS 规则和 --dsw-alias- token，类名改到 dstc- 前缀下）。运行时它只依赖 react、react/jsx-runtime 和 react-dom（最后一个会静默降级为原地渲染）。

测试

node test/host-smoke.test.mjs # host contract & error codes: 99/99
node test/client-compliance.test.mjs # dependency allow-list + self-contained primitives: 73/73

172 条断言，全部通过。 在禁止命名管道的 Windows 沙箱里，不要用 node --test。

许可证

MIT