fix(dsh): 角色工具白名单先分区再 restrict,实现文档迁入插件目录
缺陷:dsh-ops 把 ops_* 注册在 agent 自己的作用域层
(inheritable:false),全局层名册里没有这些名字。角色白名单
一旦命中 ops_*,首次 restrict 就抛错,整份策略应用失败,成员
工具面完全不设防——四个专精角色此前实际没拿到过白名单。
修复:白名单改走「先分区、再 restrict」两步——作用域层名字由
分区器摘除交策略层,全局层一次性交 restrict。三条路径(初始
注入 / 降级重试 / rebind 重放)共用同一个分区器,行为逐字一致。
两条刻意设计:
- 白名单全被分区掉时 allow 集合为空,必须显式发 {"allow":[]}
(fail closed;省略即不限制,会静默放开全部工具)
- 未向任何提供方注册的名字报 not visible yet and not
restrictable,不得误报成「未注册」——注册时机问题不能把
将来能用的名字从白名单里丢掉
真机验收(宿主重启后取证):目标角色 doc-writer 走
applied in one pass (allow=35),白名单 43 项 = 4 作用域层 +
4 不可解析 + 35 进限制,与 diag 逐行自洽;成员工具面
qq_*/workbuddy_*/ImageGen 全部不可见;persona 逐字注入。
能力边界报备(未修,文档已写明):ops_discover_tools 可激活
写侧作用域工具绕过白名单——白名单是初始可见面裁剪,不是安全
边界;要封锁写权限须连它一起排除。
文档:实现说明从 docs/环境与部署 迁入插件自带 docs/(内容全部
是本插件内部实现,按知识各归其位原则);AGENTS.md 与 docs
索引同步改指向,全仓 doc-links 与 mermaid 门禁绿。
This commit is contained in:
@@ -259,7 +259,6 @@ docs/
|
||||
|---|---|
|
||||
| [`项目部署环境要求.md`](环境与部署/项目部署环境要求.md) | 开发机软件环境、目标板资源预算、现场部署与验收步骤 |
|
||||
| [`并行任务工作树方案.md`](环境与部署/并行任务工作树方案.md) | **多任务并行开发机制(单一模型)**:DSH 插件创建工作树,`task-worktree` 补共享环境、构建/台架锁、`bench-gate` 台架验收门禁与 `merge` 编排式合并;含目录联接、冲突规则与容量建议 |
|
||||
| [`子Agent角色自动注入实现说明.md`](环境与部署/子Agent角色自动注入实现说明.md) | **`spawn_teammate` 角色 persona 自动注入的实现参考 + 排障参照**(宿主 0.2.2-rc.1 + 2026-11-13 台架实证快照):事件面事实(两参回调/子会话时序/lead 侧接力)、工具白名单降级、兜底与去重、失败模式史、部署生效链(pnpm file: 拷贝陷阱)、诊断日志排障速查;使用侧在 `.dsh/roles/README.md` |
|
||||
| [`CI/README.md`](CI/README.md) | **远程 CI(Gitea Actions)唯一入口**:服务端开关 / runner 部署与保活 / workflow / 排障。**只涉及本机一台 runner `win-stm32-ci`,其他机器与项目都不涉及**;日常改代码用本地门禁 `scripts/ci_local.py`,不必读这里 |
|
||||
|
||||
### 9.3 台账与外部资料
|
||||
|
||||
@@ -1,272 +0,0 @@
|
||||
# 子Agent角色自动注入实现说明
|
||||
|
||||
> **定位**:`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.2-team-fork** 的台架实证快照(2026-11-13 探针实测;0.5.2 新增复活持久绑定,见 §5.1,2026-11-16 实测确认缺口后修复)。事件面是**观测行为,不是宿主 API 契约**——宿主升级后可能变化,出问题先按 §8 查诊断日志,再动插件代码。
|
||||
|
||||
---
|
||||
|
||||
## 1. 目的与本篇边界
|
||||
|
||||
这节说清该功能解决什么问题、本篇只覆盖哪条路径。读者读完应能判断自己的问题是否归本篇管。
|
||||
|
||||
**问题**:`spawn_teammate` 的 `prompt` 参数就是一段普通任务文本,宿主**不会**替它读取 `.dsh/roles/<角色id>.md`——不做任何处理时,teammate 子会话会以无角色 persona、无工具策略的裸 agent 起跑。而插件自带的 `subagent_role` 委派工具路径,上游本就自动应用角色(persona + 工具策略 + 调用预算),所以本篇讲的**只是 Agent Teams 路径的增量**:让 `prompt` **首行**的 `@role:<角色id>` 标记获得与 `subagent_role` 同等的自动注入。
|
||||
|
||||
**目标**(验收判据):子会话的**首轮模型请求组装之前**,其系统提示词已含角色 persona、工具白名单已生效——Lead 侧无需手工拼接 persona 文本。
|
||||
|
||||
**本篇不管的**:
|
||||
|
||||
| 内容 | 去处 |
|
||||
|---|---|
|
||||
| 有哪些角色、职责范围、怎么选 | `.dsh/roles/README.md`(使用侧) |
|
||||
| 委派策略总口径(Agent Teams 优先、首行必须写标记) | 根 `AGENTS.md`「委派策略」节 |
|
||||
| `tools` 字段的保留工具名单与容错口径(使用侧) | `.dsh/roles/README.md`「`tools` 字段说明」节 |
|
||||
| 工具调用预算(`maxToolCalls`)在 team 路径**不生效** | 见下文 §1.1 |
|
||||
|
||||
### 1.1 已知边界:注入路径不带预算
|
||||
|
||||
`lib/budget.js` 的预算监视器靠 `arm()` 挂账,而 `arm()` 只在 `subagent_role` 委派工具启动子会话时调用;`spawn_teammate` 起的子会话没有经过它,所以**角色文件 frontmatter 里的 `maxToolCalls` 当前只对 `subagent_role` 路径生效**,对 teammate 子会话不起约束作用(2026-11-13 读码确认,注入段落代码里也没有预算逻辑)。以后要给 team 路径补预算,这是显式的缺口。
|
||||
|
||||
### 1.2 代码落点
|
||||
|
||||
注入实现整体在 `.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 启动。
|
||||
|
||||
---
|
||||
|
||||
## 2. 注入时序:在 lead 会话侧接力
|
||||
|
||||
这节回答"persona 为什么能赶上子会话首轮"。关键结论:**不要等子会话把 prompt 吐出来**(那时首轮请求已经组装完),而是在 lead 会话上截获 spawn 调用、提前注册角色,等 `subagent/catalog` 事件把子 agent 身份送到手上再注入。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant L as lead会话事件流
|
||||
participant P as 插件 session/event 观察者
|
||||
participant C as 子会话事件流
|
||||
L->>P: tool/call name=spawn_teammate (prompt 首行 @role)
|
||||
P->>P: roleIdFromText 解析角色 id, 存入 pendingByLabel
|
||||
L->>P: subagent/catalog 带 childId 与 label(=description)
|
||||
P->>P: agents.get(childId) 取到子 agent 句柄
|
||||
P->>C: systemPrompt.section 注入 persona 到 deployment:persona-prefix
|
||||
P->>C: applyToolPolicy 应用工具白名单, 抛错则降级重试
|
||||
Note over C: 以下才轮到子会话首轮, 注入已完成
|
||||
Note over C: system/message 首轮请求组装, persona 已在其中
|
||||
Note over C: user/message 里 @role 标记出现, 兜底路径凭去重集合跳过
|
||||
```
|
||||
|
||||
三段接力(锚点都在 `lib/index.js` 尾部 `Agent Teams role injection` 段内的 `ctx.on('session/event', ...)` 单一观察者里):
|
||||
|
||||
1. **截获(lead 的 `tool/call` 事件)**:`data.name == "spawn_teammate"` 时取 `data.arguments`(对象或 JSON 串,两种都解析)里的 `{name, description, prompt}`。`roleIdFromText()` 只看 prompt **第一行**、且只在**前 200 字符**窗口内找——标记匹配模块级正则 `ROLE_MARKER_PATTERN`(`/^@role:([a-z0-9]+(?:-[a-z0-9]+)*)\s*$/m`:角色 id 只允许小写字母数字加连字符,行内 id 之后不允许再带其他词)。命中后以 `d:<description>` 和 `n:<name>` 两个键把 `{roleId, cwd, applied}` 存进 `pendingByLabel`。
|
||||
2. **识身份(lead 的 `subagent/catalog` 事件)**:payload 带 `data.childId` 与 `data.label`;台架实证 **label 就是 spawn 的 `description`**(同文本),所以先按 `d:` 键查、再按 `n:` 键兜底。拿到 childId 后 `ctx.get('agents').get(childId)` 取子 agent 句柄;失败再试 `findAgentBySession('session-<childId>')`(`agents.list()` 里按 `a.id` / `a.session.header.id` / `a.session.id` 三种字段匹配)。还取不到就记一行 `not live yet`,留给 §5 兜底路径追注。
|
||||
3. **注入(`installRoleOn()`)**:`agent.ctx.systemPrompt.section({ name: 'deployment:persona-prefix', order, text: persona })`——order 取该 agent 上 `getSectionOrder('DEPLOYMENT_PERSONA_PREFIX')`,拿不到回退 0,即落在宿主部署 persona 前缀区;persona 来自 `loader.loadSync(cwd)` 加载的角色文件(项目 `.dsh/roles/` 覆盖全局 `~/.dsh/roles/`,使用侧细节归 `.dsh/roles/README.md`)。随后 `applyToolPolicy()` 应用工具白名单(§4)。注入成功后把 `agent.id` 记入 `injectedAgents`、其会话 id 记入 `injectedSessions` 两个去重集合。
|
||||
|
||||
**时序为什么赶得上**:lead 的 `tool/call` 与 `subagent/catalog` 都发生在**子会话事件流开跑之前**。2026-11-13 探针实测:`spawn captured` → `catalog` 223 ms、`catalog` → `injected` 12 ms;代码注释口径 catalog 事件比子会话首轮组装早约 270 ms,探针取证口径注入早于首轮组装约 224 ms——两个口径同为"约 0.2~0.3 秒量级",结论一致:注入发生在子会话 `system/message`(首轮请求组装完成点)**之前**。
|
||||
|
||||
---
|
||||
|
||||
## 3. 宿主事件面事实(2026-11-13 台架快照)
|
||||
|
||||
这节是实现所依赖的主机行为清单。改插件前逐条对照;宿主升级后注入坏了,第一嫌疑就是这张表里的某条变了。
|
||||
|
||||
### 3.1 回调签名:session/event 是两参
|
||||
|
||||
`ctx.on('session/event', (sessionObject, event) => {...})`——**第一参是会话对象**(`header.id`、`header.cwd`、`eventsSnapshot` 即该会话既有事件列表的快照),**第二参才是事件本体** `{type, seq, time, data}`。把第一参当事件本体来读 `type` 是早期版本的失败根因(教训见 §6);插件从第一参取会话 id/cwd,从第二参取事件类型与载荷。
|
||||
|
||||
### 3.2 子会话的事件顺序
|
||||
|
||||
子会话从创建到首轮回复的事件流(台架观测,按 seq 递增):
|
||||
|
||||
```
|
||||
subagent/descriptor → sandbox/mode → approval/policy → permission/preset
|
||||
→ agent/inbox/spliced → turn/start → step/start
|
||||
→ system/message(首轮请求已组装完毕)
|
||||
→ user/message(spawn 的 prompt 在这里出现,含 @role: 首行)
|
||||
→ request/header → assistant/message
|
||||
```
|
||||
|
||||
关键约束:`system/message` 出现时首轮请求**已经组装完**,`user/message` 必然在它之后——**在子会话侧做任何基于 prompt 内容的注入都注定晚首轮一步**,这是 §2 整套 lead 侧接力的存在理由。
|
||||
|
||||
### 3.3 lead 会话上的两个关键事件
|
||||
|
||||
| 事件 | 载荷 | 台架实证口径 |
|
||||
|---|---|---|
|
||||
| `tool/call` | `data.name == "spawn_teammate"`;`data.arguments` 含 `{name, description, prompt}` | 工具参数在宿主提交调用时已成串,可直接拿到完整 prompt |
|
||||
| `subagent/catalog` | `data.childId`(子 agent id)+ `data.label` | **label == spawn 的 description**;实测比子会话 `step/start` 早数百毫秒(量级见 §2 末段) |
|
||||
|
||||
lead 会话上也会看到 `team/member`、`tool/result` 等后续事件,注入不需要它们。
|
||||
|
||||
### 3.4 用到的宿主服务面
|
||||
|
||||
| 触点 | 用途 | 备注 |
|
||||
|---|---|---|
|
||||
| `ctx.get('agents')` 的 `get(id)` / `list()` | childId → agent 句柄 | `get` 直接命中;`list` 供按会话 id 兜底匹配 |
|
||||
| `agent.ctx.systemPrompt.section({name, order, text})` | 注册 persona 段 | 名字固定 `deployment:persona-prefix`;order 对齐宿主 `DEPLOYMENT_PERSONA_PREFIX` 区 |
|
||||
| `agent.ctx.tools.restrict(filter)` | 应用工具白名单 | **只校验全局工具名**,见 §4 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 工具白名单降级
|
||||
|
||||
这节解释一个反直觉现象:把角色白名单整串交给 `restrict()` 会**整批抛错**,而且错得"无名无姓"。实现用"报错尾部反推全集再求交集"绕开。
|
||||
|
||||
**背景白话**:工具名册分两层。**全局工具**挂在宿主顶层名册上(本宿主如 `read` `edit` `write` `grep` `glob` `web_search`,完整名单见报错尾部);**作用域工具**由插件束(bundle)注册、只出现在特定 agent 的作用域里(本宿主主要是 OPS 插件的 `ops_bash` `ops_grep` `ops_inspect_local_file` `ops_discover_tools`,以及 `team_task_*` 协作工具)。`tools.restrict()` **只对全局层的名字表做校验**,白名单里混进任何一个它不认识的名字,整个调用直接抛错——不是逐个警告、更不是部分生效。
|
||||
|
||||
**降级算法**(`applyToolPolicy()`):
|
||||
|
||||
1. 先原样整批 `restrict(filter)`;成功即结束。
|
||||
2. 失败则再调一次只为**捕获错误文本**,用正则取尾部 `known global tools: ...`(宿主报错自带全部已知全局名,这是唯一能拿到的"合法名字全集")。
|
||||
3. 白名单与该全集**求交集**后重试。filter 形状认三种:裸数组、`.allow` 数组、`.allowedTools` 数组(角色 frontmatter 的 `tools:` 简写经 loader 归一为 `{allow: [...]}`,所以实测走 `.allow` 分支);`deny` 字段原样透传不进交集。
|
||||
4. 终态写诊断日志:`tool policy applied via reduced list` / `tool policy still failed after reduce` / `tool policy skipped (unparseable error/unknown filter shape)` / `tool policy reduce threw: ...`。
|
||||
|
||||
**实测效果**(台架确认为理想行为):交集后的**全局名白名单正常生效**(只读角色确实拿不到 `edit`/`write`);`ops_*`、`team_task_*` 等作用域工具**不在 restrict 的约束面内、保持可用**——restrict 本来就够不着作用域层,白名单里写没写它们都不改变这一点。因此角色文件的 `tools` 列表不需要按宿主机器裁剪。
|
||||
|
||||
真实报错样本(2026-11-13 台架 [示例],旧探针记录格式;`known global tools:` 尾部形态就是降级解析器的依赖面,列表过长处以省略号代):
|
||||
|
||||
```text
|
||||
tools.restrict() names unknown global tools "ops_bash", "ops_inspect_local_file",
|
||||
"ops_discover_tools", "team_task_get", "team_task_list", "team_task_update";
|
||||
known global tools: acp_cache, acp_status, compress, decompress, edit, glob, grep,
|
||||
read, ..., send_message, skill, subagent, ..., todo_write, web_fetch, web_search,
|
||||
..., working_directory, write
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 兜底路径与去重
|
||||
|
||||
这节讲主路径断链时的保险丝,以及怎么识别"只有兜底在起作用"。
|
||||
|
||||
**机制**:同一个事件观察者对**子会话**事件也解析标记——`deepText()` 从事件载荷的嵌套结构(`content`/`parts`/`text`,再深一层 `message`/`data`)里提取文本,命中首行 `@role:` 就记入 `pendingMarker`(会话 id → 角色 id),并用 `findAgentBySession()` 找 agent 注入;agent 暂时找不到就等该会话的下一个事件再试。因为 `user/message` 晚于首轮的 `system/message`,兜底注入的 persona **从第 2 步起才可见**。
|
||||
|
||||
**去重**:`injectedAgents`(按 `agent.id`)与 `injectedSessions`(按会话 id)两个集合。主路径注入成功后,子会话后续事件再带标记也会被跳过——防止同一 persona 被重复注册成多个同名 section。已 `injected` 但 agent 迟到的场景由 `pendingMarker` 分支追赶补注。
|
||||
|
||||
**台架实证"兜底必然晚一步"**(2026-11-13 早轮旧格式探针日志 [示例],该轮还没有主路径):
|
||||
|
||||
```text
|
||||
[2026-11-13T12:22:10.668Z] evt#9 s=ce3bf8 type=system/message ← 首轮请求已组装
|
||||
[2026-11-13T12:22:10.669Z] evt#10 s=ce3bf8 type=user/message head=@role:doc-writer ...
|
||||
[2026-11-13T12:22:10.672Z] injected role "doc-writer" (4739 chars) into agent b4194190-...-db66ffce3bf8
|
||||
```
|
||||
|
||||
注入落在首轮组装之后 4 ms——persona 从第 2 步才可见,这正是当初必须做 lead 侧接力的原因。
|
||||
|
||||
**识别法**:一次注入在诊断日志里若只出现 `injected role` 一行、前面没有 `spawn captured` 与 `catalog` 两行 = 主路径断链、兜底在干活——按 §8 修主路径,不要满足于"反正注入了"。
|
||||
|
||||
**一处未深究的观察**:兜底路径的事件匹配不分会话归属,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. 失败模式史:四条死路各换一条教训
|
||||
|
||||
这节记录定稿"纯事件观察"(段落头自称 v7)之前台架试错过的四条 hook 路径。升级宿主后想加新 hook,先读这节,别重蹈覆辙。
|
||||
|
||||
| 尝试 | 主机实际行为 | 教训 |
|
||||
|---|---|---|
|
||||
| 包装 `ctx.subagents.startActivation`,指望子会话启动时进 wrapper | wrapper 从未被调用 | **先实证功能真实入口再埋点**:`spawn_teammate` 根本不走 subagent 激活服务,宿主内部走 Agent Teams 自己的 spawn 路径(台架取证指向 `ctx.agentTeams.spawnTeammate`——内部实现名、非公开 API,不要依赖其存在,只作"它不在 subagents 面上"的指认) |
|
||||
| 直接给 ctx 拿到的服务对象属性赋值包 wrapper | 赋值"成功",但所有调用从不进 wrapper | **服务面改写在宿主侧走不通**:宿主交给插件的是它包的一层代理(白话:插件读写这份"对象"只是在对复印件写字,宿主内部真对象纹丝不动,属性写被静默吞掉)——此后定案:插件只做纯事件观察,不改任何服务 |
|
||||
| 在 `agent/created` 事件里从 `session.snapshotEvents` 读 prompt | 该 API 不存在;且该事件载荷的 header 里没有 name/teamId | **agent 创建事件自带的信息不足以识身份**:既拿不到 prompt,也无法把 created 关联到具体 teammate——关联只能靠 lead 侧 `subagent/catalog` 的 childId(§3.3) |
|
||||
| 只观察子会话 `user/message` 的标记 | 注入能成功,但晚首轮一步 | **时序仗只能在 lead 侧打**:子会话事件流开跑时首轮请求已在组装(§3.2),这条降级为 §5 兜底 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 部署与生效链
|
||||
|
||||
这节回答"我改了插件代码,何时生效、怎么确认生效"。换机复原时按本节顺序搭链。
|
||||
|
||||
```
|
||||
仓库 fork(唯一事实源,入库)
|
||||
.dsh/plugins/dsh-plugin-subagent-roles/
|
||||
│ pnpm file: 依赖 = 一次性拷贝(不是链接)
|
||||
▼
|
||||
web profile 运行时实际读的那份
|
||||
~/.dsh/profiles/web/node_modules/dsh-plugin-subagent-roles/
|
||||
▲
|
||||
│ 重启 dsh web 进程才重新加载
|
||||
核心树(@deepseek-ai/dsh 安装目录)——没有该插件副本,属正常
|
||||
```
|
||||
|
||||
- **拷贝而非链接,三处证据钉死**:profile 的 `package.json` dependencies 里该条目写 `"dsh-plugin-subagent-roles": "file:<仓库插件目录绝对路径>"`;同目录 `pnpm-lock.yaml` 的 specifier 同为该 `file:` 路径;`node_modules/` 下对应条目经 `ls -la` 确认是**真实目录不是符号链接**。后果:**改仓库里的插件文件不会自动反映到运行时**,每次改完必须手工同步。
|
||||
- **手工同步 + 重启(台架实走路径)**,改 `lib/index.js` 为例:
|
||||
|
||||
```bash
|
||||
cp "<repo>/.dsh/plugins/dsh-plugin-subagent-roles/lib/index.js" \
|
||||
"$HOME/.dsh/profiles/web/node_modules/dsh-plugin-subagent-roles/lib/index.js"
|
||||
# 回读确认(应能 grep 到段落头)
|
||||
grep -c "Agent Teams role injection" \
|
||||
"$HOME/.dsh/profiles/web/node_modules/dsh-plugin-subagent-roles/lib/index.js"
|
||||
```
|
||||
|
||||
然后重启该 profile 的宿主进程(`dsh web`)。改了 `lib/` 其他文件同理一并拷贝。
|
||||
- **生效判据(最硬的一条)**:重启后 `~/.dsh/role-inject-diag.log` 尾部出现新的一行
|
||||
`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 尾部段落。
|
||||
|
||||
---
|
||||
|
||||
## 8. 排障速查
|
||||
|
||||
这节给"症状 → 查哪一行 → 结论"的对照表。总原则:**先查诊断日志,再动插件**;宿主升级后先验证 §3 事件面快照哪条变了,不要凭记忆改代码。
|
||||
|
||||
### 8.1 诊断日志本体
|
||||
|
||||
插件的 `ctx.logger` 在会话侧不可见,全部取证靠 `diag()` 直接 `appendFileSync` 到 **`~/.dsh/role-inject-diag.log`**(= `os.homedir()/.dsh/`,Windows 本机形如 `C:/Users/<用户名>/.dsh/`)。每行 `[ISO时间戳(UTC)] 消息`;文件无上限增长,太大直接截断/删除(只损失历史取证)。注意 spawn 消息里的时间是 UTC,比对本地时刻要 +8。
|
||||
|
||||
一次健康注入 = 4 行(2026-11-13 实测原文):
|
||||
|
||||
```text
|
||||
[2026-11-13T12:27:17.104Z] spawn captured: role=doc-writer name=role-probe6 desc=六次注入探针
|
||||
[2026-11-13T12:27:17.327Z] catalog: label=六次注入探针 childId=fda63569-c689-4102-afad-d7322dbecc4d matched=true
|
||||
[2026-11-13T12:27:17.338Z] tool policy applied via reduced list
|
||||
[2026-11-13T12:27:17.339Z] injected role "doc-writer" (4739 chars) into agent fda63569-c689-4102-afad-d7322dbecc4d (pre=x)
|
||||
```
|
||||
|
||||
行尾 `(pre=x)` 只是诊断信息:注入时观察者**已经**在该子会话上数到过事件(`x`)与否(`?`),不代表成败。
|
||||
|
||||
### 8.2 症状对照表
|
||||
|
||||
排查顺序按注入生命周期走:装载行 → 截获行 → 识身份行 → 注入行 → 工具策略行,**第一处断在哪一环,问题就在哪一环**。
|
||||
|
||||
| 症状(diag 所见) | 结论 | 动作 |
|
||||
|---|---|---|
|
||||
| 重启后没有新的 `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 事件,永远不匹配 | 忽略 |
|
||||
| `catalog: child <id> not live yet` | `agents.get` 与 `list` 兜底都没拿到子 agent | 观察是否随后出现兜底 `injected` 行;频发则查 `agents` 服务面变化 |
|
||||
| `role "<id>" not found (cwd=...)` | 角色文件缺失/在别的目录树/frontmatter 解析失败 | 查 `<cwd>/.dsh/roles/<id>.md` 与 `~/.dsh/roles/<id>.md`;使用侧格式归 `.dsh/roles/README.md` |
|
||||
| `install skipped: no systemPrompt.section on agent ...` | 宿主 agent 句柄形状变了(`ctx.systemPrompt` 没了或不是 section 注册面) | 对照 §3.4 重新取证服务面 |
|
||||
| `tool policy skipped (unparseable error)` | `restrict()` 报错格式变了,降级解析器抓瞎 | persona 不受影响(先注入后策略);按新报错格式修 `applyToolPolicy()` 的尾部正则 |
|
||||
| `tool policy still failed after reduce` | 交集后的纯全局名名单仍被拒 | 查角色 `tools` 字段形状(认 数组/`.allow`/`.allowedTools` 三种)与宿主 restrict 契约 |
|
||||
| 有 `injected role` 行、无 `spawn captured`/`catalog` 行 | 主路径断链,兜底在干活(persona 第 2 步才可见) | 按 §5 识别法确认后回查截获/识身份两环 |
|
||||
| 有 `injected role` 行但子 agent 自报没有 persona | section 名字/order 与宿主装配面冲突,或注入到的不是被请求的那个会话对象 | 核对 `deployment:persona-prefix` 是否仍被宿主采纳;用 childId 与会话 id 对应关系核"注错对象" |
|
||||
| `session/event handler threw: ...` | 某事件载荷形状意外,被总 try 兜住 | 看尾部异常文本定位是哪条事件;修 `deepText`/字段假设 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 验收证据(2026-11-13 探针)
|
||||
|
||||
这节钉死最近一轮端到端验收的实况,日后升级后拿它当对照基线。
|
||||
|
||||
- **主路径 4 行**:即 §8.1 引用的 12:27 轮——`spawn captured`(12:27:17.104) → `catalog matched=true childId=fda63569`(12:27:17.327) → `tool policy applied via reduced list` → `injected role "doc-writer" (4739 chars)`(12:27:17.339);注入早于子会话首轮组装约 224 ms(探针取证口径)。
|
||||
- **persona 真实可见**:探针子会话首轮回复自报系统提示词中存在角色 persona,并准确引用 `.dsh/roles/doc-writer.md` persona 正文首句原文(「你是 STM32F4-Base 项目的**技术文档写手**」)——证明注入进的是它本轮在用的那份系统提示词,不是旁路。
|
||||
- **可复现性**:同日 12:31 与 12:49 两轮同链复跑均 4 行齐(后一轮即本篇写作会话 `doc-role-inject` 自己的出生记录,childId 5605001c)。
|
||||
- **降级路径实证**:`tool policy applied via reduced list` 行本身 + §4 报错样本;doc-writer 白名单中的 `ops_bash` 等被交集剔除后策略照常生效、这些作用域工具实测仍可用。
|
||||
|
||||
> 自查本篇链接与围栏的本地命令(门禁时机是提交期,全量留给 pre-commit):
|
||||
> `& '.venv\Scripts\python.exe' scripts/check_doc_links.py docs/环境与部署/子Agent角色自动注入实现说明.md` 与 `scripts/check_mermaid.py` 同法;两闸各自的详解 → `docs/门禁说明/doc-links.md`、`docs/门禁说明/mermaid-syntax.md`,章节引用口径 → `docs/文档规范.md` §3.5。
|
||||
Reference in New Issue
Block a user