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
@@ -0,0 +1,96 @@
# Role delegation prompts (web verifier)
English | [中文](delegation-prompts.zh.md)
> This is a template: replace the angle-bracket placeholders with your own values.
> Roles are defined in `<project>/.dsh/roles/<id>.md` (frontmatter: `provider` / `model` / `reasoningEffort` / `tools` / `maxToolCalls`; body: persona).
> Editing a role file takes effect immediately — no `dsh web` restart.
---
## 0. What you say to the main agent
**Natural trigger** — the main agent picks the role from the catalog itself:
```text
Use web-verifier to verify the changes to "<page/feature>": run <your E2E command> and report against the full-coverage criteria in <your verification SOP>. Do not drive the browser yourself.
```
**Add boundaries when they matter:**
```text
The verifier only verifies: it does not modify files and does not touch the backend. If a service needs a restart, you (the main agent) do that first.
```
---
## 1. Dispatch template (main agent → subagent)
```text
TASK — state it first: verify with a real browser that <page/feature> still works, and report full coverage.
TARGET
- Project root: <project root>
- Frontend directory: <frontend directory> (dev URL <dev URL>)
- Backend: <backend URL> — read-only for you; do not start or stop it
- Verification SOP (read it first): <project root>/.dsh/skills/<your verification skill>/SKILL.md
STEPS
1. If the project has a lease or mutex convention for shared resources (dev servers, devices): take the lock, refresh its heartbeat after every step, and release it when done. Read-only probes need no lock.
2. Read the project's own instructions (AGENTS.md and friends) and the SOP above, then confirm service state: <status command>.
3. Run the cases: cd <frontend directory> && <E2E command>. Credentials come from the project docs.
4. If the SOP asks for a "feature list → test cases" mapping table, complete it before running, and cover every interactive control on the page: search, filter and reset, every row action, and every control inside drawers and dialogs.
5. Console guard: a [Global Error] or an uncaught exception fails the run. Rate-limit noise (for example 429) may be filtered, but report it when it affects an assertion.
6. If the project is localized: switch language with the real control, assert that the interface text changes, then switch back.
ACCEPTANCE
- The result of <E2E command>, plus a per-item coverage verdict (covered / not covered) in the project's own terms.
- Anything you could not cover must be listed as an explicit "not covered" item with status WAITING; "N passed" on its own is not acceptance.
- On failure, attach reproducible evidence: DOM state, logs, screenshots, or a trace path.
FORBIDDEN
- Modifying any project file — edit/write and shell redirection are out; only the lease directory may be created.
- Starting or stopping the backend, running migrations or database resets, reading or writing the database, seeding data through curl or API calls.
- Starting another dev server or changing ports; do not bypass the project's own start script.
- Calling tools unrelated to the task (other MCP tools, delegation tools, and so on).
REPORT: 1 what you did (start with the tool name and the target path) 2 what you observed (case names, pass/fail, coverage verdict) 3 problems and suggestions 4 status: DONE or WAITING
```
---
## 2. Budgeting a role (plugin >= 0.4.0)
A role file may cap how many tool calls its child gets. Give a read-only explorer
enough to finish the inventory, and a run-time verifier far less — it mostly waits
on commands:
```yaml
---
description: Inventory a cross-cutting change (read-only)
tools: [read, grep, glob, bash]
maxToolCalls: 30 # measured in CALLS, not turns: parallel calls each count
maxToolCallsScope: delegation
onToolCallBudget: wrap-up # inject "wrap up now", then tolerate graceToolCalls more
graceToolCalls: 1
---
You are a read-only explorer. Never modify a file; report findings and open questions.
```
Rules of thumb, from real runs (a 19-call inventory and a 25-call review both blew
through a verbal "8 steps" guard that nothing enforced):
| Role type | Suggested `maxToolCalls` |
|---|---|
| Read-only exploration (>= 5 files) | 30–40 |
| Static review | 40–60 |
| Run-time verification (mostly commands) | 15–20 |
| Omitted or `0` | unlimited — the escape hatch for a very large repository |
Two things worth knowing:
- **The unit is calls, not turns.** Three parallel reads in one step are three calls,
and a call refused by policy still counts — the child already spent the decision.
- **Crossing the limit triggers**, not reaching it, and that call is stopped before it
finishes. `graceToolCalls: 0` makes `wrap-up` behave exactly like `interrupt`.
@@ -0,0 +1,91 @@
# 角色委派 prompt 模板(web 验证者)
[English](delegation-prompts.md) | 中文
> 这是**模板**,尖括号处按你自己的项目替换。角色定义在 `<项目根>/.dsh/roles/<id>.md`
> (frontmatter 是 `provider`/`model`/`reasoningEffort`/`tools`/`maxToolCalls`,正文是 persona)。
> 角色文件改动**不需要重启 `dsh web`**(每次提示词组装按 mtime 读取)。
---
## 0. 主代理侧(你在项目会话里说的话)
**自然触发**(主代理会照角色目录自己选角色):
```text
用 web-verifier 验证「<页面/功能>」这次改动,跑 <你的 E2E 命令>,按 <你的验证 SOP> 的全覆盖口径给我结论;你不要自己跑浏览器。
```
**想同时明确边界时**加一句:
```text
验证者只做验证、不改文件、不碰后端;服务如果要重启由你(主代理)先做。
```
---
## 1. web-verifier 派发模板(主代理 → 子代理)
```text
【唯一任务】用真实浏览器验证 <页面/功能> 的这次改动是否可用,并给出全覆盖结论。
【目标】
- 项目根:<项目根>
- 前端目录:<前端目录>(dev 地址 <dev 地址>)
- 后端:<后端地址>(你只读观察,不启停)
- 验证 SOP(先读):<项目根>/.dsh/skills/<你的验证技能>/SKILL.md
【步骤】
1. 若项目对共享资源(dev server、设备等)有租约/互斥约定:先按约定取锁并在每步刷新心跳,任务结束立即释放;只读探活不需要锁。
2. 先读项目说明(AGENTS.md 之类)与上面的 SOP,确认服务状态:<状态检查命令>。
3. 跑用例:cd <前端目录> && <E2E 命令>;账号见项目说明。
4. 若 SOP 要求「功能清单 → 用例」映射表:先补齐再跑,逐项覆盖页面内每个可交互控件(搜索/筛选/重置、每个行操作、弹层与抽屉内每个控件)。
5. 浏览器 console 断言:出现 [Global Error] / 未捕获异常即判失败;限流类噪声(如 429)可过滤,但若影响断言须如实回报。
6. 若项目支持多语言:用真实控件切换语言,断言界面文案随之变化,再切回。
【验收】
- <E2E 命令> 的结果 + 按项目口径的**逐项**覆盖结论(覆盖/未覆盖)
- 覆盖不到的控件必须单列「未覆盖清单」并置 WAITING,不得以「N passed」收尾
- 失败时附上可复现的 DOM/日志/截图或 trace 路径
【禁止】
- 修改任何项目文件(edit/write/落盘全禁;仅租约协议自身的取锁目录例外)
- 启停/重启后端、跑迁移或重置数据库、直接读写数据库、用 curl/API 造数
- 另起 dev server 或改端口;不要绕过项目的启动脚本自己拉起服务
- 调用与本任务无关的工具(其它 MCP 工具、委派类工具等)
【回报】1 做了什么(以「工具名 + 目标路径」开头) 2 观察结果(用例名 + passed/failed + 覆盖结论) 3 问题与建议 4 状态:DONE 或 WAITING
```
---
## 2. 给角色加上调用额度(插件 >= 0.4.0)
角色文件可以限制子代理能用多少次工具。给只读探索者留够完成盘点的量,给运行时验证者留得少得多——后者主要在等命令返回:
```yaml
---
description: 盘点一次跨端改动(只读)
tools: [read, grep, glob, bash]
maxToolCalls: 30 # 单位是「次」不是「轮」:并行调用各计 1
maxToolCallsScope: delegation
onToolCallBudget: wrap-up # 先注入「请立即收尾」,再宽限 graceToolCalls 次
graceToolCalls: 1
---
你是只读探索者。不要修改任何文件;只汇报发现与未决问题。
```
依据实测的经验值(一次 19 次的盘点与一次 25 次的审查,都突破了没人强制的口头「8 步」护栏):
| 角色类型 | 建议 `maxToolCalls` |
|---|---|
| 只读探索(>= 5 个文件) | 30–40 |
| 静态审查 | 40–60 |
| 运行时验证(以跑命令为主) | 15–20 |
| 省略或 `0` | 不限——超大仓库的逃生口 |
两点值得记住:
- **单位是「次」不是「轮」。** 同一步里三次并行读取就是三次;被策略拒绝的调用同样计数——那次决策已经被消耗掉了。
- **跨过上限才触发**(等于上限不算),并且那一次调用会在结束前被停下。`graceToolCalls: 0` 让 `wrap-up` 与 `interrupt` 行为完全一致。