@stofone/dsh-agent-roster 0.6.2 → 0.7.0

package/README.zh.md

@@ -24,7 +24,7 @@
 @stofone/dsh-agent-roster
 ```
 
-包内带 `cordis.patch.yml`，安装即把插件插进 profile。装好后应看到五个工具（`roster_list`、`roster_show`、`roster_create`、`roster_verify`、`roster_index`）以及左侧栏里的 **Agent Roster** 面板（独立主面板，不再放设置页）。
+包内带 `cordis.patch.yml`，安装即把插件插进 profile。装好后应看到六个工具（`roster_list`、`roster_show`、`roster_create`、`roster_verify`、`roster_diff`、`roster_index`）以及左侧栏里的 **Agent Roster** 面板（独立主面板，不再放设置页）。
 
 ## 快速开始
 
@@ -117,6 +117,8 @@ npx dsh-agent-roster list
 
 成员键：`name`、`role`、`systemPrompt`（必填），以及 `provider`、`model`、`reasoningEffort`、`toolPolicy`、`fallback`、`toolScope`、`maxTokens`、`title`、`tags`、`notes`、`description`、`aliases`、`skills`、`examples`。
 
+档案目录里还可以有一个**可选的兄弟文件** `capabilities.yaml`，声明"建这支队伍前部署侧必须提供什么"——见「能力要求」一节。
+
 `systemPrompt` 上限 8000 字符。成员省略路由字段时从 `defaults` 继承，继承结果记入 `inherited` 列表，能看清"这个值哪来的"。
 
 机器可读的 JSON Schema 在 [`schema/roster.v1.schema.json`](./schema/roster.v1.schema.json)，供编辑器补全与外部工具校验；权威校验始终是 `lib/validate.js`，两者由 `test/schema.test.js` 对齐。
@@ -150,19 +152,66 @@ npx dsh-agent-roster list
 
 真正生效要改 profile 的 `cordis.patch.yml` 与 agent preset。面板里编辑队长段只是在记录意图——插件不会、也不能替你改会话。
 
+## 能力要求（`capabilities.yaml`）
+
+档案说的是**成员是谁**，说不了**这台机器到底能不能把他们跑起来**——技能目录与工具策略定义都在部署侧，不在档案里。档案目录里一个可选的兄弟文件只声明这件事，别的一律不写：
+
+```yaml
+kind: dsh-agent-roster-capabilities/v1
+roster: money-lab            # 必须等于目录名
+onMissing: refuse            # refuse（默认）| degraded
+asOf: 2026-11-02             # 只写日期
+requires:
+  skills: [frontend-skill, {name: dsh-chat-import, reason: 会话导出需要}]
+  toolPolicies: [member-safe]
+notes: 建队前先确认成员会话可用。
+```
+
+每一条要求只会落进**三种**状态之一，没有第四种：
+
+| 状态 | 含义 | 效果 |
+|---|---|---|
+| `present` | 证据源说有 | 无需处理 |
+| `missing` | 证据源明确说没有 | **唯一**会触发闸门的状态 |
+| `unknown` | 根本没有证据源 | 既不算过也不算错，但一定要写下来——沉默不等于批准 |
+
+证据源只有两个，因为宿主只答得出这两件事：`skills` 来自技能目录，`toolPolicies` 来自本插件的 `knownToolPolicies` 配置。其余一切——模型路由可用性、插件版本、凭据指针、业务前置条件——一律拒收（`unknown-field`）：没人核得了的要求，只是换一种方式发绿。
+
+行为：`onMissing: refuse`（默认）下，只要有一项 `missing`，`roster_create` **不产出任何** `agent_teams_add_member` 参数，并逐项告诉你该装到哪；`roster_verify` 状态行报 `requires=<缺>missing/<声明>` 与 `capabilityBlocked`，被能力拦下的档案会让 `ok` 为 false。`onMissing: degraded` 照样给参数，但这笔账每次核对都会记着。`roster_show` 直接打印这份声明。
+
+**面板也会显示它。** 每张档案卡片把这些要求作为诊断列出：缺 `toolPolicies` 时，`onMissing: refuse` 记 **error**（左侧栏角标因此变红），`degraded` 记 **warn**。技能要求一律记成 `capability-skills-unverified` / **info**——面板快照是同步的，列不出技能目录，所以它只说"这里不判定"而不猜；要真答案用 `roster_verify`。没配 `knownToolPolicies` 时只出一条 `capability-cross-check-skipped`，点名受影响的档案，而不是每份档案刷一遍。
+
+兄弟文件有自己的 JSON Schema：[`schema/capabilities.v1.schema.json`](./schema/capabilities.v1.schema.json)，由 `test/capabilities.test.js` 钉住与 `lib/capabilities.js` 一致。
+
 ## 工具
 
 | 工具 | 作用 |
 |---|---|
 | `roster_list` | 列出档案库里的档案与每份的校验结果 |
 | `roster_show` | 完整查看一份档案（或其中一名成员），含字段归宿 |
-| `roster_create` | 把成员翻译成 `agent_teams_add_member` 参数 / `plan.members` |
-| `roster_verify` | 与 `dsh-agent-teams` 的 `team.json` 比对；状态缺失时降级为「无法核对」 |
+| `roster_create` | 把成员翻译成 `agent_teams_add_member` 参数 / `plan.members`；声明的能力缺失时拒绝出参数 |
+| `roster_verify` | 与 `dsh-agent-teams` 的 `team.json` 比对；分「一致 / 未核实 / 降级 / 未部署」四桶，并报物化后的工具过滤器摘要、策略漂移、团队溯源与能力要求 |
+| `roster_diff` | 比较两代档案：成员按 name 对齐、比有效值、人设只比长度与哈希 |
 | `roster_index` | 列出公共档案源（registry）的索引状态与 collection；给定 collection 时只读地拉下来看 |
 
-五个工具都不写团队状态。`roster_create` 只产出参数，真正的建员仍由模型调用 `agent_teams_add_member`。
+六个工具都不写团队状态。`roster_create` 只产出参数，真正的建员仍由模型调用 `agent_teams_add_member`。
+
+带路径的工具（`roster_list` / `roster_show` / `roster_create` / `roster_verify` / `roster_diff`）都接受 `path` 参数：给了就只看那个目录，不会悄悄回落到配置目录。
+
+### 一目录一档案，一台机器可有两代
+
+`roster` 必须等于目录名，一座库里每个目录只有一份档案。所以同一份档案的两代就放在**两座库**里——
+这是预期用法，不是缺口：它保住了「位置即身份」（后续加载永远不会误取另一代），
+也让换代成为一个显式的 `path` 参数，而不是悄悄发生的副作用。
+
+```text
+~/.dsh/agent-roster/money-lab/roster.yaml           # 这一代
+/workspace/money/.dsh/rosters/money-lab/roster.yaml # 下一代
+```
 
-三个带路径的工具（`roster_list` / `roster_show` / `roster_create`）都接受 `path` 参数：给了就只看那个目录，不会悄悄回落到配置目录。
+`roster_diff({ from, to })` 回答「两代之间改了什么」；`roster_create` 会打印一行溯源串
+（`roster:money-lab@9.0.0#ab12cd34`），建团队时放进 description；`roster_verify` 再拿这一行
+与当前档案内容比对——档案在建团队之后被改过，就会报 `differ`，而不是静默通过。
 
 ### 队长核对
 
@@ -284,12 +333,12 @@ test/             单测
 
 本机已验证：
 
-- `npm test` —— 191/191 通过（格式、解析、校验、扫描、路径、桥接、核对、无损 JSON、写入计划与执行、六条路由、快照与提示、两本词典一致、工具契约、客户端加载器契约、包清单、配置视图、样式 token 约束、声明层字段与队长段、schema 与常量对齐）。
-- `npm run smoke` —— 用真实 DSH bundle 的 `defineTool` 注册五个工具，逐个调用：输出全部通过无损校验、`path` 覆盖生效、释放干净；同一条命令随后用桩模块表加载 `client.js`，断言三处槽位注册、样式只注入一次、effect 可回收。
+- `npm test` —— 223/223 通过（格式、解析、校验、扫描、路径、桥接、核对四桶、摘要与溯源、档案差异、能力要求与能力闸门、无损 JSON、写入计划与执行、六条路由、快照与提示、两本词典一致、工具契约、客户端加载器契约、包清单、配置视图、样式 token 约束、声明层字段与队长段、schema 与常量对齐）。
+- `npm run smoke` —— 用真实 DSH bundle 的 `defineTool` 注册六个工具，逐个调用：输出全部通过无损校验、`path` 覆盖生效、释放干净；同一条命令随后用桩模块表加载 `client.js`，断言三处槽位注册、样式只注入一次、effect 可回收。
 - CLI：`validate --dir examples` 对两座示例库退出码 0。
 - 用插件管理器真的装进了本机 profile（`plugin_manager install_bundle` 指向本仓库 → `link:` 依赖 + bundle 条目），重启后按链接读取本仓库文件。
 - 运行中的宿主已能应答只读路由：`GET /plugins/dsh-agent-roster/library` 返回 200，带插件版本与解析出的档案目录。
-- 另一个 agent 会话在工具清单里看到了五个工具，并实际调用了它们。
+- 另一个 agent 会话在工具清单里看到了六个工具，并实际调用了它们。
 - 左侧栏面板已在活页面里确认可见，并展示了真实档案。
 
 这一轮没验证到的：0.2.0 的管理界面（页签、编辑器、团队页、语言切换、`document` / `rosters` 路由）在活页面里的表现——这些改动要重启宿主才会被加载，重启后再验。

package/index.js

@@ -48,7 +48,7 @@ export const Config = z.object({
     .description(
       "档案库目录。留空 = 全局默认目录 $DSH_HOME/agent-roster（默认 ~/.dsh/agent-roster，" +
         "docker 下就是被挂载的数据卷），与工作区无关。填绝对路径或 ~ 开头路径同样是全局的；" +
-        "只有填相对路径（如 examples）才按工作区解析。第一项是四个工具默认读取的档案库。",
+        "只有填相对路径（如 examples）才按工作区解析。第一项是各工具默认读取的档案库。",
     )
     .volatile(),
   knownToolPolicies: z
@@ -102,7 +102,7 @@ export function apply(ctx, config) {
   const settings = configView(config);
 
   registerRosterTools(ctx, settings, { version: pkg.version });
-  ctx.logger?.info?.(`dsh-agent-roster ${pkg.version}: registered 5 tools`);
+  ctx.logger?.info?.(`dsh-agent-roster ${pkg.version}: registered 6 tools`);
 
   // 面板路由：读快照 / 读单份档案原文 / 保存 / 删除 / 导入。
   // 没有 webServer 也不影响工具可用性。

package/lib/bridge.js

@@ -5,14 +5,21 @@
  * `agent_teams_add_member`。原因是档案层不知道团队此刻处于什么阶段（暂存/运行/已归档），
  * 也不应该替运行时决定"现在创建一个成员"。工具只输出参数，模型原样传入，运行时决定成败。
  *
- * 三个诚实状态必须被区分，否则档案会给人"能力已被运行时保证"的错觉：
+ * 五个诚实状态必须被区分，否则档案会给人"能力已被运行时保证"的错觉：
  *
  * - `applied`：运行时状态里的值与档案一致（读取的是 team.json，不是我们的请求）；
- * - `overridden` / `omitted`：运行时最终采用了别的值，或根本没带这个字段；
+ * - `overridden`：运行时采用了别的值——真的降级；
+ * - `omitted`：档案本来就没声明（或运行时也没有），沿用默认——**预期内**，不算降级；
+ * - `not-persisted`：我们发出了值，但运行时状态里根本没有这个键——**无法核对**。
+ *   它与 `omitted` 的区别就是本插件曾经报假绿的地方：都叫"没有"，但一个是"本来没有"，
+ *   另一个是"发了却没留痕"。后者必须让 `faithful` 变红，并且单独计数，
+ *   否则"人设没被核对过"会被折叠进"一致"里（见 issue #2）。
  * - `not-carried`：agent-teams 没有对应承载（toolScope、maxTokens 等），档案只是声明。
  *
  * @module dsh-agent-roster/bridge
  */
+import { createHash } from "node:crypto";
+
 import { FIELD_BINDING } from "./format.js";
 
 /** 成员字段 → 调用参数名 / 运行时状态键。 */
@@ -31,7 +38,8 @@ export const BINDING_STATUS = {
   pending: "已生成参数，运行时尚未回执",
   applied: "运行时取值与档案一致",
   overridden: "运行时实际取值与档案不同",
-  omitted: "运行时未携带该字段",
+  omitted: "档案未声明，沿用运行时默认",
+  "not-persisted": "运行时状态不含该字段（已发出，无法核对）",
   unconfirmed: "缺少运行时状态，无法核对",
   "not-carried": "agent-teams 无承载，仅声明",
   "config-required": "需要落到部署配置才生效",
@@ -157,8 +165,22 @@ export function reconcileBinding(binding, teamMember) {
     const actual = found[entry.stateKey];
     entry.actual = actual ?? null;
     if (actual === undefined || actual === null || actual === "") {
+      // 两个方向都要分清，否则会同时制造假绿和假红：
+      // - 档案没声明、运行时也没记 → 沿用默认，预期内；
+      // - 档案声明了值、运行时状态里没有这个键 → 发了却没留痕，无法核对（issue #2）。
+      if (entry.requested === null) {
+        entry.status = "omitted";
+        entry.note = "档案未声明，运行时也未记录（沿用默认）";
+      } else {
+        entry.status = "not-persisted";
+        entry.note = "team.json 未持久化该字段，无法核对（不等于未生效）";
+      }
+      continue;
+    }
+    if (entry.requested === null) {
+      // 档案没声明路由，运行时取了队长默认：这不是"运行时改了我们的值"，不该报降级。
       entry.status = "omitted";
-      entry.note = "运行时没有记录该字段";
+      entry.note = "档案未声明，运行时取了默认值";
       continue;
     }
     entry.status = valueMatches(entry.field, entry.requested, actual) ? "applied" : "overridden";
@@ -170,8 +192,14 @@ export function reconcileBinding(binding, teamMember) {
 /**
  * 生成绑定摘要：按状态统计，供工具输出和索引里的 `binding` 段使用。
  *
+ * `degraded` 与 `faithful` 只在这里算一次——曾经 `isBindingFaithful` 自己另写了一份判据，
+ * 两份判据一旦不一致就会出现"摘要说降级、判定说忠实"的假绿（issue #2）。
+ *
  * @param {object} binding
- * @returns {{ counts: Record<string, number>, carried: number, applied: number, degraded: number }}
+ * @returns {{
+ *   counts: Record<string, number>, carried: number, applied: number,
+ *   degraded: number, unverified: number, absent: number, faithful: boolean,
+ * }}
  */
 export function summarizeBinding(binding) {
   const counts = {};
@@ -180,8 +208,21 @@ export function summarizeBinding(binding) {
   }
   const carried = binding.fields.filter((entry) => entry.param !== null).length;
   const applied = counts.applied ?? 0;
-  const degraded = (counts.overridden ?? 0) + (counts.omitted ?? 0) + (counts.unconfirmed ?? 0);
-  return { counts, carried, applied, degraded };
+  const notPersisted = counts["not-persisted"] ?? 0;
+  const overridden = counts.overridden ?? 0;
+  const unconfirmed = counts.unconfirmed ?? 0;
+  const degraded = overridden + notPersisted + unconfirmed;
+  return {
+    counts,
+    carried,
+    applied,
+    degraded,
+    /** 发出了值却拿不到运行时回执的字段数（今天只有 systemPrompt 会命中）。 */
+    unverified: notPersisted,
+    /** 档案本来就没声明、运行时也没记的字段数：预期内，不计入降级。 */
+    absent: counts.omitted ?? 0,
+    faithful: degraded === 0,
+  };
 }
 
 /** 人读的一行：`model          已应用  deepseek/deepseek-v4.1-flash（来源：member）`。 */
@@ -204,11 +245,49 @@ export function describeField(entry) {
 /**
  * 团队状态是否与档案一致：只统计"被运行时承载"的字段。
  *
- * 存在 overridden / omitted / unconfirmed 时返回 false——降级必须被看见。
+ * 三个真降级都会让这里变红：`overridden`（运行时换了值）、`unconfirmed`（查不到成员）、
+ * 以及 `not-persisted`（发了值但运行时状态里没留痕，无法核对）。
+ * `omitted` 不算——那是档案本来就没声明、运行时沿用默认，属预期内。
+ *
+ * 判据只有一份，就在 {@link summarizeBinding} 里：此处绝不重复实现，
+ * 否则两份判据一漂移就回到 issue #2 的假绿。
  */
 export function isBindingFaithful(binding) {
-  const summary = summarizeBinding(binding);
-  return (summary.counts.overridden ?? 0) === 0 && (summary.counts.unconfirmed ?? 0) === 0;
+  return summarizeBinding(binding).faithful;
+}
+
+/**
+ * 团队溯源串：`roster:<id>@<version>#<档案内容 sha256 前 8 位>`。
+ *
+ * `team.json` 没有"由哪一版档案建成"的字段，所以只能借 `description` 这一行把出处的**指针**带进去。
+ * 插件仍然不写团队状态——它只给出"建议写什么"，由队长模型传进 `agent_teams_create`。
+ *
+ * @param {object} roster 已校验档案
+ * @param {string} [contentSha] 档案文件内容的 sha256（十六进制）；缺省时省略 `#` 段
+ * @returns {string}
+ */
+export function provenanceLine(roster, contentSha) {
+  const short = typeof contentSha === "string" && contentSha !== "" ? `#${contentSha.slice(0, 8)}` : "";
+  return `roster:${roster.id}@${roster.version}${short}`;
+}
+
+/**
+ * 从任意文本里解析溯源串。
+ *
+ * @param {string} text 团队 description 或任意一行文字
+ * @returns {{ id: string, version: string, sha: string | null, raw: string } | null}
+ */
+export function parseProvenanceLine(text) {
+  if (typeof text !== "string") return null;
+  // 版本段必须是一个**完整**的 semver 词，且其后立刻是 `#<sha>` 或词边界。
+  // 否则 `roster:core-review@1.2.0+provider,model`（`provenanceOf` 产出的另一种写法，
+  // 带继承字段后缀）会被读成 version `1.2.0+provider`——一个根本不存在的版本，
+  // 比对时永远 differ，比"读不出来"更糟。
+  const match = /roster:([A-Za-z0-9][A-Za-z0-9._-]*)@(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)(?:#([0-9a-f]{8}))?(?![0-9A-Za-z.+,-])/.exec(
+    text,
+  );
+  if (match === null) return null;
+  return { id: match[1], version: match[2], sha: match[3] ?? null, raw: match[0] };
 }
 
 /** `roster:<id>@<version>`——出现在输出、提交信息与绑定记录里的出处标识。 */