feat(dsh): 门禁账本插件接入 + 角色绑定跨重启还原
CI / 静态门禁 (pre-commit) (push) Failing after 43s
CI / 主机侧单测 (MSVC) (push) Failing after 24s

二、门禁与唤醒(新插件 dsh-plugin-team-ledger 0.2.0)
宿主 Agent Teams 缺两块能力,补在独立仓
D:/Code/AI/dsh-plugin-team-ledger:

- 状态存放:<工作区>/.dsh/team/gate.jsonl 追加账本,记验收
  清单、实测证据、认领历史,跨重启存活;canonical JSON +
  fsync,坏尾行截断恢复。
- 唤醒模型:门禁推进后按事件计划唤醒下一责任人,借活体
  Lead 作 caller 走宿主 sendMessage;无定时器;30 分钟滑动
  窗口限 4 次防复活风暴。
- 验收独立性由机器强制:执行人/历史认领者不能 accept,
  checklist 逐项 passed=true 缺一不可。
- team_member_revive(Lead 专用):成员模型路由死亡后的
  复活通道——可换 provider/model,再经 subagents.sendMessage
  冷恢复唤醒,绕过宿主 roster 的 phase=active 门禁。

二、角色绑定跨重启还原(roles fork 0.5.2)
persona 与工具白名单只有运行中 agent 的内存态,宿主重启后
冷恢复的成员既无 persona 也无白名单——实测出现 doc-writer
成员带全量工具面(qq_*/ImageGen),属静默权限放大。改为
注入成功时持久化 childId -> {roleId, cwd} 到
~/.dsh/role-inject-bindings.json,并在 agent/created 时重放。
追加 team_member_rebind 补绑定,覆盖 0.5.2 之前已存在的成员。

三、配套
- .dsh/roles 八个角色白名单加入门禁工具;AGENTS.md 委派策略
  补门禁/复活/重绑三套操作口径。
- docs/环境与部署/子Agent角色自动注入实现说明.md 新增
  §5.1,记录绑定机制、存量成员缺口与「成员自省不可全信」的
  台架教训。
This commit is contained in:
2026-11-16 00:42:51 +08:00
parent 384ad5a80d
commit 9e538d2809
31 changed files with 5616 additions and 12 deletions
@@ -2,7 +2,7 @@
> **定位**:`spawn_teammate` 的 `@role:<角色id>` persona 自动注入功能的**实现参考 + 排障参照**——换机、升级宿主、或再次调试注入问题时照本篇复原。使用侧口径(可用角色清单、`@role:` 怎么写、`tools` 字段怎么填)归 `.dsh/roles/README.md`;宿主侧「委派策略」一句话口径归根 `AGENTS.md`「委派策略(Agent Teams 优先)」节。三处分工:同一事实只在一处详述。
>
> **版本事实**:本篇全部事件面与时序结论 = 宿主 `@deepseek-ai/dsh` **0.2.2-rc.1** + fork 插件 `dsh-plugin-subagent-roles` **0.5.1-team-fork** 的台架实证快照(2026-11-13 探针实测)。事件面是**观测行为,不是宿主 API 契约**——宿主升级后可能变化,出问题先按 §8 查诊断日志,再动插件代码。
> **版本事实**:本篇全部事件面与时序结论 = 宿主 `@deepseek-ai/dsh` **0.2.2-rc.1** + fork 插件 `dsh-plugin-subagent-roles` **0.5.2-team-fork** 的台架实证快照(2026-11-13 探针实测;0.5.2 新增复活持久绑定,见 §5.1,2026-11-16 实测确认缺口后修复)。事件面是**观测行为,不是宿主 API 契约**——宿主升级后可能变化,出问题先按 §8 查诊断日志,再动插件代码。
---
@@ -29,7 +29,7 @@
### 1.2 代码落点
注入实现整体在 `.dsh/plugins/dsh-plugin-subagent-roles/lib/index.js` **尾部**以标记注释 `// ---- Agent Teams role injection (team fork v7, ...)` 起始的段落里(含段落头的主机事实注释块);该文件前半是上游原有的目录/委派工具/预算/裁剪逻辑,与本篇无关。段落内关键函数(均在下文按名字锚定,本文不写行号):`roleIdFromText()` 解析标记、`findAgentBySession()` 按会话 id 找 agent、`applyToolPolicy()` 工具白名单降级、`installRoleOn()` 真正注入。整段注册包在插件的 `safely()` 里——注册期抛异常只失去注入能力,不会拖垮 profile 启动。
注入实现整体在 `.dsh/plugins/dsh-plugin-subagent-roles/lib/index.js` **尾部**以标记注释 `// ---- Agent Teams role injection (team fork v8, ...)` 起始的段落里(含段落头的主机事实注释块);该文件前半是上游原有的目录/委派工具/预算/裁剪逻辑,与本篇无关。段落内关键函数(均在下文按名字锚定,本文不写行号):`roleIdFromText()` 解析标记、`findAgentBySession()` 按会话 id 找 agent、`applyToolPolicy()` 工具白名单降级、`installRoleOn()` 真正注入、`persistBindings()` + `agent/created` 还原观察者(§5.1)。整段注册包在插件的 `safely()` 里——注册期抛异常只失去注入能力,不会拖垮 profile 启动。
---
@@ -153,6 +153,22 @@ read, ..., send_message, skill, subagent, ..., todo_write, web_fetch, web_search
**一处未深究的观察**:兜底路径的事件匹配不分会话归属,lead 自己会话里若出现首行 `@role:` 的文本理论上也进该路径,但台架多轮实测**没有发生向 lead 注入**(诊断日志无此类行;机制未深究,可能与 `agents` 服务不含顶层交互会话有关)。不要把标记写进给 Lead 的消息里,此行为不可依赖。
### 5.1 复活持久绑定(0.5.2 新增)
**为什么必须有它**:persona 的 section 与工具白名单都只是**运行中 agent 对象的状态**,不落盘。宿主重启后把老成员冷恢复出来,得到的是一个**既没有 persona、也没有白名单**的全新 agent——2026-11-16 实测:一个 doc-writer 成员被唤醒后能看到全量工具面(含 qq_* / workbuddy_* / ImageGen),**这比"成员死了"更危险**,是一次静默的权限放大。
**机制**:主路径或兜底路径成功注入时,把 `childId → { roleId, cwd }` 写进 `~/.dsh/role-inject-bindings.json`(`persistBindings()` 去抖 500 ms 落盘)。再注册一个 `agent/created` 观察者:每个 agent 对象物化时(冷恢复必然经过这里)按规范化 id(剥 `session-` 前缀)查绑定,命中就重放 persona + 白名单。
**判据**:诊断日志出现 `loaded N spawn bindings`(启动时)与 `restored role "<id>" on materialization of <agentId>`(复活时)两行。
**边界**:绑定表只增不减(成员可复活,历史绑定必须留着);角色文件被删或改名时,复活那一侧会打 `role "..." not found` 并**退回无 persona 状态**——此时应显式处理该成员,而不是放任它带着全量工具干活。
**已知缺口:只管"上线之后"新派的成员**。绑定是在注入成功那一刻才写盘的,所以 0.5.2 上线**之前**就已存在的成员,重启后表里没有它们,还原无从谈起(2026-11-16 实测:`doc-role-inject` 冷恢复后工具面含 `qq_send_message`/`ImageGen` 等全量工具,诊断日志无 `restored role` 行、绑定文件为空)。
**补救通道 `team_member_rebind`**(同版本新增,Lead 专用):给一个存量成员补绑定——按名查 roster 拿到会话 id,如果它的 agent 正驻留就当场重放 persona + 白名单,**无论是否驻留都写盘**(不驻留的等下次物化还原)。参数 `{ target, roleId? }`:省略 `roleId` 时用表里已有的记录,表里也没有就必须显式给。返回 `{ ok, roleId, live, injected }`——`live:false` 表示当前不驻留,绑定已排队。对本项目而言,那批存量成员都是注入调试期的临时探针,**直接弃用比补救划算**,这个工具主要是给真实工作成员的意外失配兜底。
**自省的边界(台架教训)**:成员自报"我的提示词里有没有 persona"不可全信——可见上下文可能被压缩代理重写过,运行期注入的稳定前缀段不一定回显。**判 persona 在不在,看诊断日志与宿主侧请求 dump;成员自报可信的只有"我当前能调用哪些工具"**(那是本回合真实装配的函数清单)。2026-11-16 那次两面结论不一致,就是先按成员自报下了"persona 没了"的判断,实际主路径注入是成功的。
---
## 6. 失败模式史:四条死路各换一条教训
@@ -197,7 +213,7 @@ web profile 运行时实际读的那份
然后重启该 profile 的宿主进程(`dsh web`)。改了 `lib/` 其他文件同理一并拷贝。
- **生效判据(最硬的一条)**:重启后 `~/.dsh/role-inject-diag.log` 尾部出现新的一行
`event-path injection v7 registered (spawn-capture pre-step + tool-restrict fallback)`——
`event-path injection v8 registered (spawn-capture + tool-restrict fallback + durable bindings restore)`——
没有它,后面一切免谈(插件没装载/拷错文件/没重启)。
- **一次性开发工具(存在即可,不要求长期保留)**:注入段早期不是手改 index.js,而是维护在独立段落文件里由拼接脚本幂等写入——`ci-artifacts/role_inject_section.txt`(v7 段全文)与 `ci-artifacts/splice_role_inject.py`(把该段拼进 `lib/index.js`:缺 `node:fs`/`node:os` 两行 import 才插、缺模块级 `ROLE_MARKER_PATTERN` 常量才插、从 `// ---- Agent Teams role injection` 标记起替换到文件末尾)。`ci-artifacts/` 在 gitignore 内,工具丢了不影响复原——照本篇读码重建,或直接编辑 fork 尾部段落。
@@ -228,7 +244,7 @@ web profile 运行时实际读的那份
| 症状(diag 所见) | 结论 | 动作 |
|---|---|---|
| 重启后没有新的 `event-path injection v7 registered` | 插件没装载:profile 没重启 / 同步拷错或没拷 | 走 §7 生效链重做一遍 |
| 重启后没有新的 `event-path injection v8 registered` | 插件没装载:profile 没重启 / 同步拷错或没拷 | 走 §7 生效链重做一遍 |
| 有 registered,但 spawn 后无 `spawn captured` | 标记没被认出:不在 prompt 第一行 / 角色 id 含大写或非法字符 / 首行有额外词 / 标记落在前 200 字符窗口外 / 宿主 `tool/call` 事件面变了 | 先核对写法(正则见 §2 步骤 1),再对照 §3 验事件名 |
| `catalog: ... matched=false`(伴随你的 spawn) | catalog 的 label 与 `pendingByLabel` 对不上:多半 `tool/call` 那环没截获(回上一行查) | 若同时有 `spawn captured`,说明宿主 label 不再等于 description——事件面变了 |
| 后台任务频出 `catalog: ... matched=false`(如 label=Mnemon idle checkpoint review) | **无害噪声**:非本插件发起的 catalog 事件,永远不匹配 | 忽略 |