# 审批提示音插件 · DSH 契约调研（任务 t1 · api-scout）

> 交付物性质：只读侦察报告。**本次未修改任何 DSH 文件、未修改 profile、未安装任何 npm 包。**
> 唯一写入：本文件（工作区内新建目录 `dsh-approval-chime/docs/`）。
> 所有结论都带 `文件:行号` + 原文引用；查不到的一律标注「未证实」。

## 0. 取证环境（复核 captain 给的事实）

| 事实 | 复核结果 | 证据 |
| --- | --- | --- |
| DSH 包目录 | 存在，只读使用 | `<dsh-install>\node_modules\@deepseek-ai\*` |
| 正在运行的 `dsh` 就是这份 npx 安装 | **确认** | `Get-Command dsh` → `ExternalScript <dsh-install>\node_modules\.bin\dsh.ps1` |
| profile | `$DSH_HOME\profiles\web`（只读） | `package.json` / `cordis.patch.yml` / `cordis.yml` / `node_modules` |
| node / shell | node v24.21.0（PowerShell 5.1） | `node -v` |
| 设置文档 | `$DSH_HOME\settings.yaml`，**已含第三方命名空间** `ui-background`（deepseek-harness-background） | 见 §F |
| 工作区插件样例 | `dsh-quorum` / `dsh-quorum-panel` / `dsh-team-probe`（后两者含 `lib/client.js` 浏览器侧区） | 见 §D/§E |

DSH 的「不发布伴生入口」原则（`dsh-api-gateway/README.md:90`：*“No companion is published.”*）意味着下面所有 API 都只能通过 cordis 服务/事件拿到，不能靠 `import` DSH 内部私有模块。

---

## A. 审批触发点：能不能在 `ctx.remote.$on('approval/request')` 上插队？

### A.1 结论

| 问题 | 结论 |
| --- | --- |
| `ctx.remote.$on('approval/request', fn, {prepend:true})` 支持 prepend 吗？ | **不支持。`$on` 只有两个形参，第三个参数被静默丢弃。** |
| waterfall 顺序是注册序还是 prepend 优先？ | **两者都生效：带 `prepend` 的监听器插到最前，其余严格按注册顺序（先注册先执行）。** |
| 内置审批面板会不会把请求让给后面的监听器？ | **正常路径不会**——它 `return await pending.result`，不调用 `next()`，因此**在它之后注册的 `$on('approval/request')` 监听器永远不会被调用**。 |
| 推荐方案 | **不要用 `$on`。订阅 `ctx.uiSession.pendingInteractions`（HostObservable），按 `kind === 'approval'` 检测新出现的待审批条目来播放提示音。** |

### A.2 证据：`$on` 不接受 options

`@deepseek-ai/dsh-api-gateway/lib/client.js:1472-1474`：

```js
$on(event, listener) {
    return this.events.subscribe(this.ctx, event, listener);
}
```

`@deepseek-ai/dsh-api-gateway/lib/types/client/remote-events.js:32-35`：

```js
subscribe(callerCtx, event, listener) {
    const dispose = privateEvents(callerCtx).on(this.eventKey(event), listener);
    return () => { dispose(); };
}
```

→ 调用链里**没有任何地方**接收或转交第三个参数；`ctx.on` 的 `EventOptions`（`{prepend, global}`）到不了这里。类型面上也只有两个参数：`@deepseek-ai/dsh-api-gateway/lib/types/client/remote-events.d.ts:28`

```ts
subscribe<Event extends TypertRemoteEvent>(callerCtx: Context, event: Event, listener: TypertClientEventListener<Event>): () => void;
```

### A.3 证据：cordis 事件语义（prepend 优先，否则注册序）

`@deepseek-ai/cordis/src/events.ts:112-117`：

```ts
export interface EventOptions {
  /** Add the listener before existing listeners for the same event. */
  prepend?: boolean
  /** Receive the event regardless of context filter checks. */
  global?: boolean
}
```

`@deepseek-ai/cordis/src/events.ts:254-260`（注册即 append / unshift）：

```ts
register(label: string, hooks: Hook[], callback: any, options: EventOptions): () => void {
    const method = options.prepend ? 'unshift' : 'push'
    return this.ctx.fiber.effect(() => {
      hooks[method]({ ctx: this.ctx, callback, ...options })
```

`@deepseek-ai/cordis/src/events.ts:234-243`（waterfall 逐个 `shift`）：

```ts
waterfall(...args: any[]) {
    const cbs = this.dispatch('waterfall', args)
    const inner = args.pop()
    const next = () => {
      const cb = cbs.shift() ?? inner
      return cb(...args)
    }
```

**实测（本次运行，见 §I 探针 2/3，用 DSH 自带的 cordis 包真跑）**：

```
order: C(prepend) -> A(reg1) -> B(reg2) | return: B-answered
order2: builtin(uiapproval): never calls next -> (chime(late) 根本未被调用) | return: allowed-once
```

第二条正是本插件的风险现场：先注册、且不调用 `next()` 的监听器会把整条瀑布切断。

### A.4 证据：内置审批面板注册在「瀑布链前面」，且正常路径不让位

注册形态 `@deepseek-ai/dsh-client-ui-approval/lib/client.js:282-284`：

```js
ctx.remote.$on("approval/request", function(request, next) {
    return answerApproval(ctx, this, request, next, registerPendingInteraction);
});
```

正常路径不让位 `@deepseek-ai/dsh-client-ui-approval/lib/client.js:236-261`（节选，行号连续）：

```js
async function answerApproval(ctx, owner, request, next, registerPendingInteraction) {
    const sessionId = ctx.sessions.scopeOf(owner);
    if (sessionId === void 0) return next();                       // 局部退让之一（无 session）
    ...
    try {
        try {
            return await pending.result;                            // 正常路径：永不 next()
        } catch (error) {
            if (pending.isDelegation(error)) return await next();   // 局部退让之二（显式 delegate）
            throw error;
        }
```

**它的注册为什么一定在我们前面？** 行序由 bundle 层顺序决定：

1. `dsh-web-app` 的 patch 层里就插入了 `ui-approval` 行：`@deepseek-ai/dsh-web-app/cordis.patch.yml` 中
   ```yaml
    - id: ui-approval
      name: '@deepseek-ai/dsh-client-ui-approval'
   ```
2. 层按 `dsh.profile.bundles` 顺序叠加，`insert` 一律 **push 到列表尾部**：
   `@deepseek-ai/dsh-app-boot/lib/index.js:291-299`（模块文档 *“the tree is composed by applying each bundle's patch list in `dsh.profile.bundles` order over an empty entry list”*）+ `:70-86`
   ```js
   if (insert) {
       ...
       if (!Array.isArray(target.config)) target.config = [];
       target.config.push(...insert);
   } else data.push(...insert);
   ```
   而现 profile 的 bundles 顺序是 `[…] "@deepseek-ai/dsh-web-app", … 第三方 …`（`profiles/web/package.json`），即我们的行排在 `ui-approval` 之后。
3. 浏览器端 cordis 插件按 entry 树顺序激活（**推断**：客户端 boot 用同一份 loader entry 图构图，`dsh-client-modules/lib/index.js:586-593` 的 `compose()` 保持 entry 顺序；本任务无法启动浏览器实测激活次序）。
4. **更致命的一点**：即使把我们的 bundle 挪到 `dsh-web-app` 之前，我们的 `apply` 也要等 `inject` 的服务（`remote`/`uiSession`/…）就绪才执行，而这些服务由 `dsh-web-app` 里更靠后的行提供——注册时机并不由行序独占决定。**所以「靠行序抢在审批插件前注册」是不可靠的。**

### A.5 备选方案（推荐）：`ctx.uiSession.pendingInteractions`

类型定义 `@deepseek-ai/dsh-client-ui-session/lib/types/client/index.d.ts:96`：

```ts
/** Root source of pending UI interactions, independent from Controller snapshots. */
readonly pendingInteractions: HostObservable<SessionPendingInteractionSnapshot>;
```

`:29`：`export type SessionPendingInteractionSnapshot = ReadonlyMap<SessionId, SessionPendingInteraction>;`
`:117`：`registerPendingInteraction<T extends SessionPendingInteractionBase>(precedence: (interaction: T) => number): PendingInteractionPublisher<T>;`

**运行时形状（真实实现，可照抄）** `@deepseek-ai/dsh-client-ui-session/lib/client.js:80-90`：

```js
pendingSnapshot = /* @__PURE__ */ new Map();
pendingListeners = /* @__PURE__ */ new Set();
/** Root source of pending UI interactions, independent from Controller snapshots. */
pendingInteractions = {
    getSnapshot: () => this.pendingSnapshot,
    subscribe: (listener) => {
        this.pendingListeners.add(listener);
        return () => {
            this.pendingListeners.delete(listener);
        };
    }
};
```

→ 只需要 `getSnapshot()` / `subscribe(listener) → disposer` 两个方法，**不需要 React**。

`<SessionId, PendingInteraction>` 的**approval 条目如何判别**：内置审批面板发布的对象带 `kind`、`key`、`sessionId`（`@deepseek-ai/dsh-client-ui-approval/lib/client.js:114-142`）：

```js
var PendingApproval = class {
    sessionId;
    /** Domain discriminator used by Session pending-interaction consumers. */
    kind;
    /** Opaque render identity and one-shot remount axis. */
    key;
    ...
    constructor(sessionId, request) {
        this.sessionId = sessionId;
        this.kind = "approval";           // ← 判别依据（line 140）
        nextApprovalKey += 1;
        this.key = `approval:${String(nextApprovalKey)}`;   // ← 去重依据（line 142）
        this.toolName = request.toolName;
```

发布时机（`@deepseek-ai/dsh-client-ui-session/lib/client.js:213-227`）：

```js
publishPendingInteractions() {
    const next = /* @__PURE__ */ new Map();
    for (const domain of this.pendingDomains) for (const interaction of domain.valuesSnapshot()) {
        const precedence = domain.precedence(interaction);
        const previous = next.get(interaction.sessionId);
        if (previous === void 0 || precedence >= previous.precedence) next.set(interaction.sessionId, {
            interaction,
            precedence
        });
    }
    const projected = new Map([...next].map(([sessionId, value]) => [sessionId, value.interaction]));
    if (samePendingInteractions(this.pendingSnapshot, projected)) return;
    this.pendingSnapshot = projected;
    (0, _deepseek_ai_dsh_client_store.notifySubscribers)(this.pendingListeners, "[ui-session] pending interactions");
}
```

注意两个语义（写实现时必须照顾）：

* **每个 session 只暴露一个** pending interaction（按 `precedence` 取大者）。同一会话同时有待审批和待回答问题（`dsh-client-ui-user-questions`）时，只有一个会出现在 Map 里。
* Map 每次变化是**整体替换**，元素引用不变（`value.interaction`）。所以要用 `key`/引用做增量 diff，不能「变了就响」。

**为什么推荐它**（相比 `$on`）：

1. 与注册顺序完全无关——不受 §A.4 的行序/inject 时机问题影响。
2. **绝不触碰审批瀑布**：不需要调用 `next()`，不可能因为我们的异常或忘记 next 而卡死审批流程（这是 `$on` 方案的首要风险）。
3. 语义更准确：它在「审批面板真的被呈现给用户」那一刻触发；`$on` 在没有 session 的场合（`answerApproval` 第 238 行 `return next()`）也会触发，而那种情况用户根本看不到面板。
4. 只用公开的服务 + 两个方法（`getSnapshot`/`subscribe`），无 React 依赖。

**退路**（若 `pendingInteractions` 在实测中不可用/不可订阅）：
按优先级依次尝试——(a) `ctx.uiSession` 的服务名/属性若改变，改用 `ctx.remote.$on('approval/request')` 并把本 bundle 排在 `dsh-web-app` **之前**，同时在监听器里**无条件先 `next()` 再播音**（fire-and-forget），接受「可能不触发」而不是「可能卡死审批」；(b) 兜底改为监听 DOM 中审批面板出现（脆弱，不建议）。

---

## B. 设置命名空间：`ctx.settings.register` 与 schemastery 的获取

### B.1 结论

| 问题 | 结论 |
| --- | --- |
| 最小可用调用 | `ctx.settings.register('approval-chime', Schema, { applies: 'live' })`，`inject = ['settings']` |
| 命名空间命名约束 | 必须匹配 `/^[a-z][a-z0-9-]*$/` → `approval-chime` ✅ |
| schema 形状 | schemastery `z` 的任意 schema；值**必须是对象**（客户端 decode 强制 `typeof value === 'object'`） |
| link: 包能否裸导入 `@deepseek-ai/schemastery`？ | **不能，默认必失败**（实测：Node 把符号链接解析到 realpath，再从 `D:\...` 向上找 `node_modules`） |
| 可行路径 | ① 在插件目录内建 `node_modules/@deepseek-ai/schemastery` junction（**推荐，已实测**）；② 用 `ctx.baseUrl` + `createRequire` 在运行时解析（无链接，证据充分但未在真实插件里实测） |

### B.2 注册 API

`@deepseek-ai/dsh-settings/lib/types/index.d.ts:216`：

```ts
register<const Namespace extends string, T>(ns: Namespace & SettingsNamespaceInput<Namespace>, schema: z<T>, options?: SettingsRegisterOptions<T>): SettingsScope<T>;
```

`:23-48` options：

```ts
export interface SettingsRegisterOptions<T> {
    /** Composition-layer values resolved below the user layer (entry-config subset). */
    base?: Partial<T>;
    /** Owner's effect timing, surfaced to configuration UIs; defaults to `live`. */
    applies?: SettingsApplies;
    validate?: (value: T) => void;
}
```

`:84-110` DSH 端返回的 `SettingsScope<T>`：`get()` / `watch(cb)` / `update(patch)` / `replace(section)`。
`@deepseek-ai/dsh-settings/lib/types/index.d.ts:2-5`（解析顺序）：*“plugins register a namespace schema and read the resolved value, which layers schema defaults, the registrant's composition `base`, and the user document section, in that order.”*

命名空间校验 `@deepseek-ai/dsh-settings/lib/index.js:82-86`：

```js
const NAMESPACE_PATTERN = /^[a-z][a-z0-9-]*$/;
function parseSettingsNamespace(value) {
    if (!NAMESPACE_PATTERN.test(value)) throw new TypeError(`settings namespace "${value}" must match ${String(NAMESPACE_PATTERN)}`);
```

重复注册直接抛错（`:283`）：`if (this.registrations.has(parsedNs)) throw new Error('settings namespace "..." is already registered');`
→ 同一命名空间只能注册一次，重载时用 `ctx.settings.describe().some(d => d.ns === NS)` 先探测（第三方插件现成写法见 `deepseek-harness-background/lib/index.js:595`）。

**schema 必须真会「被调用」**：`@deepseek-ai/dsh-settings/lib/index.js:509-513`

```js
resolve(schema, base, section, validate) {
    const value = schema(mergeLayers(base, section));
```
`describe()` 另外要求 `schema.toJSON()`（`:363`）并做 `redactSecrets(schema, ...)` 的 `type`/`dict`/`inner` 遍历（`:30-53`）。**所以「自己手搓一个假 schema」风险很高，不推荐。**

### B.3 DSH/第三方插件的标准写法（可照抄的风格）

* `@deepseek-ai/dsh-bash-local/lib/index.js:1`：`import z from "@deepseek-ai/schemastery";`
* `deepseek-harness-background/lib/index.js:1`：`import z from "@deepseek-ai/schemastery";`（`profiles/web/node_modules` 里已装好的第三方插件，`package.json` 里 `"dependencies": {"@deepseek-ai/schemastery": "^3.18.1"}`）
* `deepseek-harness-background/lib/index.js:595`：
  ```js
  if (!hostCtx.settings.describe().some((descriptor) => descriptor.ns === "ui-background")) hostCtx.settings.register(BACKGROUND_SETTINGS_NAMESPACE, BackgroundSettingsSchema, { applies: "live" });
  ```

### B.4 加载器到底怎么 import 一个插件行

`@deepseek-ai/cordis-plugin-loader/src/config/entry.ts:280`：

```ts
plugin = this.loader.unwrapExports(await this.parent.tree.import(this.options.name, this.getOuterStack))
```

`@deepseek-ai/cordis-plugin-loader/src/config/tree.ts:144-162`：

```ts
import(name: string, getOuterStack?: () => string[]) {
    if (name.startsWith('cordis:')) {
      return this.ctx.loader.builtins[name.slice(7)]
    }
    return composeError(async (info) => {
      ...
      if (this.ctx.loader.internal) {
        return await this.ctx.loader.internal.import(name, this.ctx.baseUrl!, {})
      } else if (name.startsWith('.')) {
        return await import(/* @vite-ignore */new URL(name, this.ctx.baseUrl).href)
      } else {
        return await import(/* @vite-ignore */name)
      }
    }, getOuterStack)
```

* `baseUrl` 是 **profile 目录**的 file URL：`@deepseek-ai/dsh-app-boot/lib/index.js:1529`
  `ctx.baseUrl = pathToFileURL(dirname(absoluteConfigPath)).href + "/";`（`absoluteConfigPath` 即 `…\profiles\web\cordis.yml`）
* 行名 `dsh-approval-chime` 先按 **安装（dsh 本体）** 解析、再按 **profile 目录** 解析（`@deepseek-ai/dsh-app-boot/lib/index.js:301-308` 模块文档 + `:801-822` 的 `resolvePackageDir`）：
  > *“Module resolution is two-anchor by construction: a bundle name resolves first from the dsh installation (the launcher's own package), then from the profile directory.”*
* **但插件体内部的裸导入按「插件文件自己的真实路径」解析**，与行从哪儿解析无关。

### B.5 实测（本次运行，命令与输出见 §I 探针 1）

复现装置：`_probe-symlink/pkgs/fake-plugin`（模拟我们工作区里的 link: 包，实体位于 `D:\…\`），`_probe-symlink/profile`（模拟 profile 目录，`node_modules/fake-plugin` 是指向 `pkgs/fake-plugin` 的 **Junction**，`node_modules/@deepseek-ai/schemastery` 指向 DSH 副本），从 `profile/boot.mjs` 执行 `await import('fake-plugin')`：

**CASE 1（只在 profile/node_modules 有链接）→ 失败**：

```json
{
  "url": "file:///<workspace-drive>%20Harness%20Work%20area/DeepSeek%20Harness/_probe-symlink/pkgs/fake-plugin/lib/index.js",
  "schemaError": "Cannot find package '@deepseek-ai/schemastery' imported from <workspace>\\_probe-symlink\\pkgs\\fake-plugin\\"
}
```

→ **Node 把 junction 解析到 realpath**（`import.meta.url` 显示的是 `D:\...`），随后从 `D:\...` 向上找 `node_modules` 而不是从 profile 目录找。**「profile/node_modules 里已有 schemastery」帮不上忙。**

**CASE 2（在插件目录内再建一个 `node_modules/@deepseek-ai/schemastery` junction）→ 成功**：

```json
{
  "url": "file:///<workspace-drive>%20Harness%20Work%20area/DeepSeek%20Harness/_probe-symlink/pkgs/fake-plugin/lib/index.js",
  "schemaType": "function"
}
```

同一个 node 进程里对真实 schemastery 做的表面验证：

```
type= object keys= [ 'type', 'meta', 'toString', 'dict' ]
toJSON= {"uid":6,"refs":{"1":{"type":"boolean",...},"6":{"type":"object","meta":{"default":{}},"dict":{"enabled":1,"volume":5}}}}
resolve= {"enabled":true,"volume":0.3}
```

→ 与 `dsh-settings` 需要的 `schema()` 调用、`toJSON()`、`type`/`dict` 遍历完全吻合。

### B.6 两条可行路径 + 推荐

**路径 ①（推荐，已实测）：在插件目录里建 schemastery junction**

```powershell
# 目标选「DSH 自愈的安装依赖闭包」——它每次启动都会被 dsh-app-boot 重建（见下），
# 因此比 npx 缓存里的私有路径更稳定。
$ns = '<workspace>\dsh-approval-chime\node_modules\@deepseek-ai'
New-Item -ItemType Directory -Force -Path $ns | Out-Null
New-Item -ItemType Junction -Path "$ns\schemastery" `
  -Target '$DSH_HOME\profiles\node_modules\@deepseek-ai\schemastery'
```

* 该目标是**DSH 自己维护**的：`@deepseek-ai/dsh-app-boot/lib/index.js:645-676`
  > *“The shared `$DSH_HOME/profiles/node_modules` mirrors the dsh installation dependency closure. Plain Node writes symlinks…”*
  已确认存在且 `@deepseek-ai/schemastery` 在列（`Get-ChildItem $DSH_HOME\profiles\node_modules\@deepseek-ai` → `schemastery Junction`）。
* 两处副本版本一致：DSH 副本 3.18.2、profile hoisted 副本 3.18.2。
* 约束：**只允许在工作区内建这个链接**；指向的是 DSH 只读副本，不复制、不修改、不安装。

**路径 ②（无链接，证据充分但未在真实插件里跑过）：运行时按 `ctx.baseUrl` 解析**

```js
import { createRequire } from 'node:module';
import { pathToFileURL } from 'node:url';

/** Resolve the Host's own schemastery copy from the profile anchor. */
async function loadSchemastery(ctx) {
  const anchor = new URL('package.json', ctx.baseUrl);   // ctx.baseUrl = file:///$DSH_HOME/profiles/web/
  const resolved = createRequire(anchor).resolve('@deepseek-ai/schemastery');
  const mod = await import(pathToFileURL(resolved).href);
  return mod.default ?? mod;
}
```

证据：`ctx.baseUrl?: string`（`@deepseek-ai/cordis/lib/types/context.d.ts:23`）在 boot 时被设为 profile 目录 URL（`dsh-app-boot:1529`），且 loader 自己就是这么用的（`dsh-app-boot/lib/index.js:135`：`new URL(this.config.path, this.ctx.baseUrl)`）。
**未证实**：插件 `apply(ctx)` 里的 `ctx.baseUrl` 是否一定继承到（本任务无法启动 DSH 做真机验证）。若走这条路，**必须写成 try/catch + 明确日志**，不要静默降级。

**路径 ③（明确不推荐）**：手搓一个可调用 + `toJSON()` + `type`/`dict` 的假 schema。`dsh-settings` 对 schema 的用法虽只要求这些表面，但 `redactSecrets` 会遍历 `type`/`inner`/`dict` 结构（`lib/index.js:20-53`），任何一处不吻合都会在 `describe()`（即设置页）时报错，且错误路径离根因很远。

---

## C. 设置卡片：`settings.plugin.item`、`settingsScope`、以及「第三方能不能 require CardForm」

### C.1 结论

| 问题 | 结论 |
| --- | --- |
| 卡片注册形态 | `ctx.slots.inject('settings.plugin.item', () => ctx.slots.register({ name:'settings.plugin.item', key:<namespace>, locale:NS, inject:()=>({hooks:{…}}) }, Card))` |
| key | **= 设置命名空间**（tab 用它把 DSH 命名空间和卡片配对） |
| `CardForm` / `numberField` 能否跨包 require？ | **不能。**`dsh-client-ui-settings-plugins` 的浏览器 bundle **只导出 `apply` / `inject`**（`lib/client.js:1813-1814`）；`CardForm`/`numberField`/`ValueField`/`PluginCard` 只存在于类型声明和内部实现里。**卡片 UI 必须自己写。** |
| 浏览器端 require 的命名空间 | 静态种子表（`react`、`react/jsx-runtime`、`react-dom`、`react-dom/client`、`@deepseek-ai/cordis`、`@deepseek-ai/dsh-client-store`、`@deepseek-ai/dsh-client-ui-slots`、`@deepseek-ai/dsh-client-ui-primitives`、`@deepseek-ai/dsh-client-ui-dockkit`）+ 图上存在的行 id（`<包名>` 或 `<包名>/client`）|
| 卡片 `available = true` 的条件 | `scope.getSnapshot().status === 'ready'`；而「哪个命名空间会被派发」由 tab store 决定：卡片 slot 条目的 `key` **必须出现在 DSH `settings.describe` 的 `namespaces[].ns` 里** |

### C.2 slot 契约（原文）

`@deepseek-ai/dsh-client-ui-settings-plugins/lib/types/client/slot-contract.d.ts:1-30`（节选）：

```ts
/**
 * The `settings.plugin.item` slot type — one plugin's card inside the
 * configurable-plugins tab, keyed by the settings namespace the card edits.
 * Options: `key` (the namespace). A card draws its own internals; the tab only
 * decides which namespaces to dispatch and stacks what comes back.
 * ...
 * Keying on the namespace is what lets a plugin distributed outside this
 * repository contribute a card: it registers its own settings namespace on the
 * Host and its own card under that key in the browser, and the tab pairs the
 * two without ever learning what the namespace means.
 */
declare module '@deepseek-ai/dsh-client-ui-slots' {
    interface SlotMap {
        'settings.plugin.item': {
            kind: 'keyed';
            scope: 'root';
            owner: SettingsPluginItemOwnerProps;
        };
    }
}
```

**官方自己的卡片就是第三方要照抄的形态** `@deepseek-ai/dsh-client-ui-settings-plugins/lib/client.js:1785-1797`：

```js
ctx.slots.inject("settings.plugin.item", function* () {
    yield ctx.slots.register({
        name: "settings.plugin.item",
        key: SHELL_NS,
        locale: NS,
        inject: () => bash.inject()
    }, BashCard);
    yield ctx.slots.register({
        name: "settings.plugin.item",
        key: AGENT_LOOP_NS,
        locale: NS,
        inject: () => agentLoop.inject()
    }, AgentLoopCard);
    ...
```

工作区里 `dsh-quorum-panel/lib/client.js:1298-1306` 给出了同一套 API 的最小用法（含「注册前必须等 slot 被声明」的注释）：

```js
// `inject` waits for the slot to be DECLARED by its owner; registering
// against an undeclared slot throws at load time.
ctx.slots.inject('shell.overlay', function () {
  MOUNTED.push('shell.overlay');
  return ctx.slots.register(
    { name: 'shell.overlay', id: PLUGIN_ID + '.board', order: 88, locale: NS },
    Panel,
  );
});
```

### C.3 卡片何时出现：tab 的两道闸门

闸门一：**namespace 必须被 DSH served 给这个客户端** `@deepseek-ai/dsh-client-ui-settings-plugins/lib/client.js:1140-1152`：

```js
publish() {
    if (this.disposed) return;
    const mirrored = this.describeFace.getSnapshot();
    const loaded = mirrored.view !== void 0;
    const served = new Set(mirrored.view?.namespaces.map((view) => view.ns) ?? []);
    const namespaces = this.entries().flatMap((entry) => entry.options.key !== void 0 && served.has(entry.options.key) ? [entry.options.key] : []);
```

渲染（`:411-417`）：

```js
const { loaded, namespaces } = props.useConfigurablePlugins((snapshot) => snapshot);
if (namespaces.length > 0) return … children: namespaces.map((ns) => … renderSlot("settings.plugin.item", {}, { entryKey: ns }) …
```

即：**没有注册命名空间 → 卡片不出现；卡片 slot 条目的 `key` 与命名空间不一致 → 卡片不出现。** 两者都必须对。

闸门二：**`available` 由 scope 快照状态决定**（卡片自己判）`.../client.js:850` 与 `:1412`：

```js
available: snapshot.status === "ready",
```

官方卡片的渲染守卫（`.../lib/client.js:218`）：`if (!state.available) return null;`

### C.4 `settingsScope` 绑定

服务与绑定方法 `@deepseek-ai/dsh-client-ui-settings/lib/types/client/settings-scope.d.ts:88-92, 128-139`：

```ts
declare module '@deepseek-ai/cordis' {
    interface Context {
        settingsScope: SettingsScopeBinder;
    }
}
...
/** The shared mirror's read/fold face for cross-namespace surfaces … */
describe(): SettingsDescribeFace;
/** Bind one namespace scope on the CALLER's plugin lifecycle … */
bind<T>(spec: SettingsScopeSpec<T>): SettingsScope<T>;
```

**`bind` 的参数是对象，不是裸字符串**（任务书里写的 `bind({namespace})` 正确，但要注意 `spec` 的形状）`@deepseek-ai/dsh-client-ui-settings/lib/types/client/settings-contract.d.ts:33-43`：

```ts
export interface SettingsScopeSpec<T> {
    /** Settings namespace registered by the owning Host plugin. */
    namespace: string;
    /** Narrow one wire section; undefined keeps the last accepted value. … */
    decode?: (section: unknown) => T | undefined;
}
```

运行时实现（连续可引用）`@deepseek-ai/dsh-client-ui-settings/lib/client.js:1169-1179`：

```js
bind(spec) {
    const ctx = this.ctx;
    const controller = new SettingsScopeController(this.owner, spec, this.mirror, this.persistence, this.schema);
    ctx.effect(() => {
        this.mirror.ensure();
        return async () => {
            await controller.dispose();
        };
    }, `ui-settings: ${spec.namespace} settings scope`);
    return controller;
}
```

客户端 scope 读 API `.../settings-contract.d.ts:50-85`：`getSnapshot()` / `subscribe(listener)` / `set(field, value)` / `unset(field)` / `mutate(ops, expectedRevision?)`；
快照字段 `:6-32`：`{status, value, base, user, revision, writable, mode}`（`status: 'loading' | 'ready' | 'unavailable'`）。

### C.5 浏览器端 require 的真实命名空间（实测自 shell 产物）

`@deepseek-ai/dsh-web-frontend/dist/assets/index-BKQ_L1z6.js` 中的 `staticModules` 种子表（原文）：

```js
function by(){return{react:ec,"react/jsx-runtime":ic,"react-dom":cc,"react-dom/client":fc,"@deepseek-ai/cordis":Ha,"@deepseek-ai/dsh-client-store":Hc,"@deepseek-ai/dsh-client-ui-slots":Ac,"@deepseek-ai/dsh-client-ui-primitives":Zg,"@deepseek-ai/dsh-client-ui-dockkit":Ey}}
});
```

配套证据：`dsh-client-modules/lib/types/client/manifest.d.ts:150-156`（`ClientBundleRegistration.id` / `factory(require)`），以及第三方插件的实际 require 列表——`dshmarket/client/client.js:29-33` 与 `deepseek-harness-background/lib/client.js:29-31` **只 require 种子词**（`react`、`react/jsx-runtime`、`react-dom`、`@deepseek-ai/dsh-client-ui-primitives`），跨插件协作一律走 cordis 服务（`dsh-client-ui-settings/lib/client.js:1120-1124` 的注释明说 bundle purity gate 禁止跨插件值导入）。**我们的 client.js 只需要 `require('react')`。**

---

## D. 客户端装载：第三方包怎么被服务/加载

### D.1 声明要求

`@deepseek-ai/dsh-client-modules/lib/index.js:637-666`（`resolveMeta`，节选）：

```js
const dsh = pkg.dsh;
const decl = parseDshClient(packageName, dsh !== null && typeof dsh === "object" ? dsh.client : void 0);
if (decl === void 0 || decl.platform !== "web") {
    this.pkgMeta.set(sourceKey, null);
    return null;
}
const clientRel = clientExportOf(packageName, pkg.exports);
if (clientRel === void 0) throw new Error(`client-modules: ${packageName} declares dsh.client but exports no "./client" bundle`);
const resolved = {
    packageName,
    meta: {
        clientPath: join(dirname(pkgPath), clientRel),
        ...decl.inject !== void 0 ? { inject: decl.inject } : {},
        external: decl.external ?? [],
        immediately: decl.immediately === true
    }
};
```

* `dsh.client.platform` 必须是字符串 `"web"`（`:140-154`；缺失/非对象 → 该包**不参与**浏览器图）。
* `exports["./client"]` 必须是字符串，或对象里带字符串 `default`（`:155-166`）：
  ```js
  const client = exportsField["./client"];
  if (client === void 0) return void 0;
  if (typeof client === "string") return client;
  if (typeof client === "object" && client !== null) { const fallback = client.default; if (typeof fallback === "string") return fallback; }
  throw new Error(`client-modules: ${packageName} exports["./client"] must be a string or an object with a string default`);
  ```
* 文件必须真实存在，否则**启动直接失败**（`MissingClientBundleError` / `:750-764`）：
  ```js
  client-modules: client bundles not found; run `pnpm run build` before launch:
    package: <pkg>
    path: <clientPath>
  ```
* **包名必须有 Node 可解析的 DSH 入口**（行要能被 loader import）。工作区样例的原话 `dsh-quorum-panel/lib/index.js:8-11`：
  > *“It exists rather than being omitted because a bundle row needs a Node-resolvable package: the loader resolves the row's `name` and imports it, so a client-only package still needs a host entry to mount.”*

### D.2 为什么客户端模块 id 必须等于包名

* `@deepseek-ai/dsh-client-modules/lib/types/client/manifest.d.ts:46-49`：
  ```ts
  export interface WebBootEntry {
      /** Entry name == package name. */
      id: string;
  ```
* `:147-157`：
  ```ts
  export interface ClientBundleRegistration {
      /** Plugin id (package name) — the registration key; must match the graph row being executed. */
      id: string;
  ```
* 运行时也用它当表键与 URL：`lib/index.js:813-835`（`this.table.set(packageName, …)`）、`:182-184`（`comboUrl` → `/plugins/??<id>/client.js&rev=<rev>`）、`:857-871`（按该 URL 查响应，未命中 404）。注册 id 与图行不一致 ⇒ 该行找不到 factory（模块系统「anything else → throw」）。
* 工作区样例的注释同样强调：`dsh-quorum-panel/lib/client.js:5-7`
  > *“Loaded by the host as a CLASSIC script (a plain `<script src>`), so this file must contain no top-level `import`/`export`; everything lives inside the factory closure below. `id` must equal the package name, because the module graph keys rows by package name.”*

**因此 `lib/client.js` 的长相固定为**：

```js
(function () {
  if (typeof window === 'undefined' || !window.__ModuleLoader__) return;
  window.__ModuleLoader__.load({
    id: 'dsh-approval-chime',                  // ← 必须等于 package.json 的 name
    factory: function (require) {
      var React = require('react');
      ...
      return { name: 'dsh-approval-chime', inject: [...], apply: apply };
    },
  });
})();
```

### D.3 改了文件之后要不要刷新浏览器？

分两截说，**这两截的结论不同**：

* **DSH 侧 `lib/index.js`**：改完**必须重启 `dsh web`**。工作区自己的实测记录：`交接说明.md:84` —— *“→ 改插件后**必须重启** `dsh web` 才生效”*；`dsh-quorum-故障说明.md:400-401` —— *“必须重启 `dsh web` 才能加载 host 半区的新代码”*。
* **浏览器侧 `lib/client.js`**：**理论上不需要手工刷新**，因为 `dsh-web-app` 的 patch 里**无条件**挂载了 HMR 行（`@deepseek-ai/dsh-web-app/cordis.patch.yml`）：
  ```yaml
    # The client-plugin reload chain, always mounted: it is idle until a
    # rebuild watcher (pnpm run dev:web) actually rewrites client bundles. …
    - id: client-hmr
      name: '@deepseek-ai/dsh-client-hmr'
  ```
  它的 DSH 侧**自己 stat 轮询每个图行的 bundle**并触发重组：`@deepseek-ai/dsh-client-hmr/lib/index.js:8-22`
  > *“One interval stat-polls every graph row's client bundle … reports changes through `clientModuleHost.rebuilt(id)`, and serves the `/plugins/events` SSE channel broadcasting graph/rebuilt frames to the browser half.”*
  配置默认 `pollIntervalMs: 500`（`:22`：`const Config = z.object({ pollIntervalMs: z.number().step(1).min(1).default(500) });`），轮询实现见 `:44-89`。
  **未证实**：本任务不能启动浏览器实测「改 client.js → 面板自动换新」。工作区样板的注释更保守（`dsh-quorum-panel/lib/client.js:53-62`：*“a browser tab that was already open when this file changed keeps the old module forever”*），并自加了 `REVISION` 版本戳来区分「页面旧」和「功能缺失」——**建议我们的 client.js 也带一个 `REVISION` 常量并在卡片里显示**，验收时一眼可辨。
  另外注意：DSH 启动时就把 bundle 字节读进内存（`dsh-client-modules/lib/index.js:825-833`，`bundle: snapshot.bundle`），所以 HMR 未触发时**连浏览器强刷也拿不到新字节**，必须重启 DSH。

---

## E. 挂载步骤：把工作区插件挂进 web profile

### E.1 现状（只读复核）

`$DSH_HOME\profiles\web\package.json`（节选）：

```json
{
  "dependencies": {
    "dsh-quorum": "link:<workspace>/dsh-quorum",
    "dsh-quorum-panel": "link:<workspace>/dsh-quorum-panel",
    "dsh-team-probe": "link:<workspace>/dsh-team-probe",
    ...
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app",
        "deepseek-harness-background", "dsh-whale-widget", "dshmarket",
        "@nanmicoder/dsh-agent-teams", "dsh-team-probe", "dsh-quorum", "dsh-quorum-panel"
      ],
      "patchReload": "live"
    }
  }
}
```

`profiles/web/node_modules` 里 `dsh-quorum` / `dsh-quorum-panel` / `dsh-team-probe` 都是**指向工作区的 Junction**（`LinkType: Junction`）——即 `link:` 依赖由 pnpm 物化成 junction。

### E.2 挂载机制（证据）

* 层顺序 = `dsh.profile.bundles` 顺序，最后才是 profile 自己的 `cordis.patch.yml`：`@deepseek-ai/dsh-app-boot/lib/index.js:288-309` 模块文档（原文见 §B.4 引用）。
* bundle 名字解析双锚点（先 dsh 本体，再 profile 目录）：同上 `:301-308`；`resolvePackageDir` 实现 `:801-822`。
* 每个 bundle 的 patch 文件由 manifest 声明：`"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`（同 `:294-296`；工作区三个样例包都是这个写法）。
* **重复行 id 会炸启动**：`@deepseek-ai/cordis-plugin-loader/src/config/group.ts:59-66`
  ```ts
  async update(config: EntryOptions[]) {
      const oldConfig = this.data as EntryOptions[]
      const seen = new Set<string>()
      for (const options of config) {
        const id = this.tree.ensureId(options)
        if (seen.has(id)) throw new TypeError(`duplicate loader entry id: ${id}`)
        seen.add(id)
      }
  ```
  profile 的 `cordis.patch.yml` 自己也留了这条教训（原文）：
  > *“NOTE: dsh-team-probe and dsh-demo-panel are mounted through the profile's `dsh.profile.bundles` list (their own `dsh.bundle.patch` layers insert the rows), so they must NOT be inserted here as well — duplicate row ids break the boot.”*
* 现 `cordis.patch.yml` 只做两件事：`- id: agent-teams / config: …`、以及给 `dsh-team`/`dsh-quorum`/`dsh-team-probe`/`dsh-quorum-panel` 打 `disabled: true`。**注意 id 定向 patch 的匹配规则**：`@deepseek-ai/dsh-app-boot/lib/index.js:93-105`（`id` 必须命中已存在的行，否则 warning 并跳过；`disabled` 属于 overrides 之一，`patchReload: live` 下改它热生效）。

### E.3 确切步骤（交给 t5 执行；本任务不执行）

0. 前置：插件目录内有 `package.json`（`name`、`type: module`、`main`/`exports['.']`、`exports['./client']`、`dsh.bundle.patch`、`dsh.client.platform: 'web'`）、`lib/index.js`、`lib/client.js`、`cordis.patch.yml`；并按 §B.6 路径 ① 建好 `node_modules/@deepseek-ai/schemastery` junction。
1. 编辑 `$DSH_HOME\profiles\web\package.json`：
   * `dependencies` 增加 `"dsh-approval-chime": "link:<workspace>/dsh-approval-chime"`；
   * `dsh.profile.bundles` **追加** `"dsh-approval-chime"`（追加 = 最后一层 = 行插到根列表末尾。对我们的方案**没有顺序要求**；只是不要插到 `dsh-base` 之前）。
2. 让 profile 的 `node_modules` 出现该 junction：跑 `dsh plugin --profile web install`（`dsh/lib/bin.js:105-113`：*“manage a profile's plugins by forwarding the remaining arguments to pnpm in the profile directory”*）。
   —— 这对「行名解析」是**必需**的（`link:` 依赖不物化，Node 在 profile 目录下找不到包名）。若不愿动 pnpm，可退化为手工 `New-Item -ItemType Junction -Path "$DSH_HOME\profiles\web\node_modules\dsh-approval-chime" -Target "<workspace>\dsh-approval-chime"`。
3. 确认插件自带的 `cordis.patch.yml` 只做一次 insert（照抄 `dsh-quorum-panel/cordis.patch.yml`）：
   ```yaml
   - insert:
       - id: dsh-approval-chime
         name: dsh-approval-chime
   ```
   **不要**再往 `profiles/web/cordis.patch.yml` 里写同一 id 的 insert（重复 id → `duplicate loader entry id` → 启动失败）。若只是要临时停用，在 profile 的 `cordis.patch.yml` 写 `- id: dsh-approval-chime` + `disabled: true`。
4. 重启 `dsh web`（DSH 侧代码不会热加载），浏览器刷新一次。
5. 验收信号（可观测）：DSH 日志无 `failed to import loader entry dsh-approval-chime` / 无 `client-modules: … failed to compose`；浏览器 `window.__DSH_BOOT__.entries` 里出现 `{id: "dsh-approval-chime"}`；**设置导航出现独立一行「通知提醒」（rev-7 起，`settings.section`）**，且 **设置 → 插件 → 插件配置里不再出现本插件**；`$DSH_HOME\settings.yaml` 出现 `approval-chime:` 段。入口形态的合同与 `文件:行号` 见 §K（本节只讲挂载步骤，与入口位置无关）。

**回滚**：删掉 `dsh.profile.bundles` 里的 `"dsh-approval-chime"` 与 `dependencies` 里那一行 → 重启；可选删除 profile 的 junction、以及 `settings.yaml` 里的 `approval-chime:` 段。三层都是独立可回滚的，互不残留。

---

## F. 设置值通路：DSH 文档 → 客户端 scope

### F.1 结论

| 问题 | 结论 |
| --- | --- |
| 落盘位置 | `$DSH_HOME/settings.yaml`（默认），`dsh-settings-file` 提供 |
| DSH → 客户端 | 客户端 `settingsScope` 的镜像（`SettingsDescribeMirror`）读 `remote.settings.describe`；**失效信号** = `ctx.remote.$on('settings/document-updated')` + `connection/reset` |
| 卡片写回 | `scope.set/unset/mutate` → `remote.settings.update/…`（带 `revision` 栅栏）→ 写答复经 `acceptView` 折进镜像 |
| 首次读到之前 client 看到什么 | `status: 'loading'`，`value: undefined`，卡片 `available=false` 渲染 `null`；**schema 默认值只在 DSH 侧解析，客户端要等第一次 describe 答复** |
| 命名空间何时算 served | 当 `describe().namespaces[].ns` 含它（DSH 已注册该命名空间） |

### F.2 DSH 侧

* 落盘：`@deepseek-ai/dsh-settings-file/lib/index.js:27-36`
  ```js
  const filename = resolve(config.path ?? join(resolveDshHome(config.dshHome), "settings.yaml"));
  const format = FORMATS[extname(filename)];
  ```
  实测该文件已存在且含第三方段：
  ```yaml
  ui-background:
    enabled: true
    uploadId: "up-d14ea8954e07de99b3b021b5"
    opacity: 0.6
  ```
* 变更事件：`@deepseek-ai/dsh-settings/lib/types/types.d.ts:101`
  ```ts
  'settings/document-updated'(ns: SettingsNamespace, revision: number): void;
  ```
  （同文件 `:101` 上方注释：*“Listener containment matches `settings/updated`.”*，`@mode emit`。）
* 描述面（客户端拿到的就是它的红action 版本）`@deepseek-ai/dsh-api-settings-controller/lib/typert.host.js:523-524`：
  ```json
  "name": "SettingsNamespaceView",
  "declaration": "export interface SettingsNamespaceView {\n    ns: string;\n    schema: JsonValue;\n    value: JsonValue;\n    base?: JsonValue;\n    user?: JsonValue;\n    applies: 'live' | 'restart';\n …"
  ```
* `applies: 'live'` 意味着**改动立即对 owner 生效**（`SettingsRegisterOptions.applies` 默认也是 `live`）。

### F.3 客户端侧

* 镜像订阅（唯一 describe 读取者）`@deepseek-ai/dsh-client-ui-settings/lib/client.js:1333, 1343-1363`：
  ```js
  const inject = ["remote", "remote.settings"];
  ...
  function apply(ctx) {
      const schema = new SettingsSchemaService(ctx);
      const persistence = ctx.remote.$host.isLoopback ? "host" : "memory";
      const mirror = new SettingsDescribeMirror(ctx, persistence);
      ctx.effect(() => {
          const disposers = [ctx.remote.$on("settings/document-updated", () => {
              mirror.load();
          }), ctx.on("connection/reset", () => {
              mirror.load();
          })];
          mirror.ensure();
  ```
* scope 的状态机 `.../lib/client.js:1083-1117`：
  ```js
  derive() {
      if (this.disposed) return;
      const mirrored = this.mirror.getSnapshot();
      if (mirrored.view === void 0) return;                    // 还没拿到首个 describe → 维持 'loading'
      const { writable } = mirrored.view;
      const view = mirrored.view.namespaces.find((candidate) => candidate.ns === this.spec.namespace);
      if (view === void 0) {                                   // 命名空间未被 served → 'unavailable'
          this.store.update((draft) => { draft.status = "unavailable"; draft.writable = writable; });
          return;
      }
      const decoded = this.decode(view);                       // 默认校验：rehydrate(view.schema) + validate(view.value)
      this.store.update((draft) => {
          draft.revision = view.revision; draft.base = view.base; draft.user = view.user; draft.writable = writable;
          if (decoded === void 0) return;                      // 校验不过 → 保持 loading
          draft.status = "ready"; draft.value = decoded;
      });
  }
  ```
  ```js
  decode(view) {
      if (this.spec.decode !== void 0) return this.spec.decode(view.value);
      if (typeof view.value !== "object" || view.value === null || Array.isArray(view.value)) return void 0;
      let failure;
      try { failure = this.schema.validate(this.schema.rehydrate(view.schema), view.value); }
      catch (_malformedSchemaEnvelope) { return void 0; }
      return failure === void 0 ? view.value : void 0;
  }
  ```
* 非 loopback（远程浏览器）时 `persistence = 'memory'`，客户端 `status` 直接是 `'unavailable'`、写操作被丢弃（`.../client.js:1074-1082` 的 `enqueue`：`if (this.persistence === "memory" || this.disposed) return Promise.resolve();`）→ **本地 GUI（127.0.0.1）才有真正的持久化写入**。

### F.4 默认值的时间线（回答「客户端第一次读到之前是什么」）

1. DSH `apply` 注册命名空间 → `resolve()` 用 `schema(mergeLayers(base, section))` 立即得到含默认值的解析结果（`dsh-settings/lib/index.js:509-513`）。
2. 客户端首次 `describe` 答复到达前：`mirror.getSnapshot().view === undefined` → scope 维持 `status: 'loading'`、`value: undefined`。**卡片的 `available` 为 false，官方卡片此时渲染 `null`；建议我们同样渲染 null（不要显示占位卡）。**
3. 答复到达且命名空间在列 → `status: 'ready'`，`value` 是 DSH 解析后的完整对象（默认值已填）。`user` 字段的 **存在性**（不是值比较）才代表「用户覆盖过」——reset 语义靠它（`settings-contract.d.ts:20-25`）。

---

## G. 最小代码骨架（供 t2/t3 照抄）

### G.1 目录与 package.json

```
dsh-approval-chime/
  package.json
  cordis.patch.yml
  lib/index.js        # DSH 侧：注册设置命名空间
  lib/client.js       # 浏览器侧：监听审批 + 注册设置卡片
  node_modules/@deepseek-ai/schemastery   -> junction（见 B.6 路径①）
```

```json
{
  "name": "dsh-approval-chime",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "main": "lib/index.js",
  "exports": {
    ".": { "default": "./lib/index.js" },
    "./client": "./lib/client.js",
    "./cordis.patch.yml": "./cordis.patch.yml",
    "./package.json": "./package.json"
  },
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" },
    "client": { "platform": "web" }
  }
}
```

> `dsh.client.inject`（包名数组，控制模块工厂到达顺序）本插件**不需要**：client.js 只 require `react` 这个种子词。若日后要 require 别的插件行（如 `@deepseek-ai/dsh-client-ui-primitives` 已在种子表里），也仍然不需要。

`cordis.patch.yml`：

```yaml
# dsh-approval-chime bundle patch：把 DSH 行挂进 profile 的根 entry 列表。
# 只在这里 insert 一次；profile 的 cordis.patch.yml 再写同一 id 会因
# `duplicate loader entry id` 直接炸启动（cordis-plugin-loader/src/config/group.ts:64）。
- insert:
    - id: dsh-approval-chime
      name: dsh-approval-chime
```

### G.2 DSH 侧 `lib/index.js`

```js
/**
 * DSH 侧：注册 `approval-chime` 设置命名空间并持久化到 DSH 设置文档。
 * 依赖 @deepseek-ai/schemastery —— 必须能裸导入（见 docs/契约调研.md §B）。
 */
import z from '@deepseek-ai/schemastery';

export const name = 'dsh-approval-chime';

/** 只要设置服务：命名空间注册是它唯一的 DSH 侧职责。 */
export const inject = ['settings'];

/** 设置命名空间（必须匹配 /^[a-z][a-z0-9-]*$/）。 */
export const NS = 'approval-chime';

/** 音量 0..100 整数；音色三选一；enable 开关。 */
export const ChimeSettingsSchema = z.object({
  enabled: z.boolean().default(true),
  volume: z.number().min(0).max(100).default(70),
  tone: z.union([z.const('chime'), z.const('ping'), z.const('beep')]).default('chime'),
});

export function apply(ctx) {
  // 幂等：热重载/live patch 后命名空间已注册时不要重复注册（重复会抛错）。
  if (ctx.settings.describe().some((descriptor) => descriptor.ns === NS)) return;
  ctx.settings.register(NS, ChimeSettingsSchema, { applies: 'live' });
}
```

（schema 形状已实测：`{"enabled":true,"volume":70,"tone":"chime"}`；`volume:200` 报
`$.volume expected number <= 100 but got 200`；`tone:'nope'` 报 `$.tone expected "chime" | "ping" | "beep" but got "nope"`。）

### G.3 浏览器侧 `lib/client.js`（**历史骨架：入口形态以 §K 为准**；本骨架写的是 rev-1 的插件页卡片注册，真实实现见 t3 与 §K）

> ⚠️ **历史骨架**：下面这段代码演示的是 rev-1 的旧入口（插件页那张卡片的槽）；**rev-7 起的现行入口形态以 §K 为准**
> （`settings.section` + `{id:'approval-chime', order:16, label:<thunk>, locale:NS}`）。保留原文是为了让下游看到当时的骨架，
> 不是现行做法。

```js
/* 浏览器侧：审批出现即响，并注册设置卡片。经典脚本，不能有顶层 import/export。 */
(function () {
  if (typeof window === 'undefined' || !window.__ModuleLoader__) return;

  window.__ModuleLoader__.load({
    id: 'dsh-approval-chime',                     // 必须等于包名（见 §D.2）
    factory: function (require) {
      var React = require('react');

      var PLUGIN_ID = 'dsh-approval-chime';
      var NS = 'approval-chime';                  // = DSH 命名空间 = 卡片 slot 的 key
      var REVISION = 'rev-1';                     // 改行为就 +1：验收时一眼分辨「页面旧」

      /* ---------------------------------------------------------- 提示音 */

      var audio = null;                            // 惰性创建：首次真正要响时才 new
      /** 浏览器自动播放策略：未与页面交互前 AudioContext 处于 suspended。 */
      function ensureAudio() {
        if (audio !== null) return audio;
        var Ctor = window.AudioContext || window.webkitAudioContext;
        if (typeof Ctor !== 'function') return null;
        audio = new Ctor();
        return audio;
      }
      /** 用 WebAudio 合成音；volume 0..100。 */
      function play(tone, volume) {
        var ctxAudio = ensureAudio();
        if (ctxAudio === null) return;
        if (ctxAudio.state === 'suspended' && typeof ctxAudio.resume === 'function') ctxAudio.resume();
        var gain = ctxAudio.createGain();
        gain.gain.value = Math.max(0, Math.min(100, Number(volume) || 0)) / 100 * 0.6;
        gain.connect(ctxAudio.destination);
        var osc = ctxAudio.createOscillator();
        var FREQ = { chime: 880, ping: 1320, beep: 440 };
        osc.frequency.value = FREQ[tone] || FREQ.chime;
        osc.type = 'sine';
        osc.connect(gain);
        osc.start();
        osc.stop(ctxAudio.currentTime + 0.18);
      }

      /* ------------------------------------------------- 审批触发（推荐方案） */

      function watchApprovals(ctx, scope) {
        // ctx.uiSession.pendingInteractions: getSnapshot() / subscribe(listener)
        var source = ctx.uiSession.pendingInteractions;
        var seen = {};
        var sync = function () {
          var snapshot = source.getSnapshot();      // ReadonlyMap<SessionId, PendingInteraction>
          var next = {};
          snapshot.forEach(function (interaction, sessionId) {
            if (interaction === null || typeof interaction !== 'object') return;
            if (interaction.kind !== 'approval') return;      // ← 判别依据（内置实现里 kind === 'approval'）
            var key = typeof interaction.key === 'string' ? interaction.key : String(sessionId);
            next[key] = true;
            if (seen[key] === true) return;
            var value = scope.getSnapshot().value;            // DSH 解析后的设置（默认值已填）
            if (value !== undefined && value.enabled === false) return;
            play(value === undefined ? 'chime' : value.tone, value === undefined ? 70 : value.volume);
          });
          seen = next;
        };
        var off = source.subscribe(sync);
        sync();                                    // 订阅前可能已有待审批：先对齐一次
        return off;
      }

      /* ------------------------------------------------------------ 设置卡片 */

      function Card(props) {
        var t = props.t;
        var snapshot = props.useChime(function (value) { return value; });   // 由 slot 的 inject 提供
        var textState = React.useState(null);
        var draft = textState[0];
        var setDraft = textState[1];
        if (snapshot.available !== true) return null;       // 命名空间未 served/未 ready：什么都不画
        return React.createElement(
          'div',
          { className: 'dacCard' },
          React.createElement('div', { className: 'dacTitle' }, t('title')),
          React.createElement('label', null,
            React.createElement('input', {
              type: 'checkbox',
              checked: draft === null ? snapshot.enabled === true : draft.enabled === true,
              disabled: snapshot.writable !== true,
              onChange: function (event) { setDraft(Object.assign({}, draft || snapshot, { enabled: event.target.checked })); },
            }),
            t('enabled')),
          React.createElement('input', {
            type: 'range', min: 0, max: 100, step: 5,
            value: draft === null ? (snapshot.volume === undefined ? 70 : snapshot.volume) : draft.volume,
            disabled: snapshot.writable !== true,
            onChange: function (event) { setDraft(Object.assign({}, draft || snapshot, { volume: Number(event.target.value) })); },
          }),
          // 「试听」必须在用户手势里调用，才能解除 AudioContext 的 suspended。
          React.createElement('button', { onClick: function () { play(snapshot.tone, snapshot.volume); } }, t('preview')),
          React.createElement('button', {
            disabled: snapshot.writable !== true,
            onClick: function () {
              if (draft === null) return;
              if (draft.enabled !== undefined) scope.set('enabled', draft.enabled);
              if (draft.volume !== undefined) scope.set('volume', draft.volume);
              setDraft(null);
            },
          }, t('save')),
        );
      }

      /* ------------------------------------------------------------ lifecycle */

      var inject = ['slots', 'settingsScope', 'uiSession', 'locale'];

      function apply(ctx) {
        var scope = ctx.settingsScope.bind({ namespace: NS });   // ← spec 是对象（§C.4）
        ctx.effect(function () { return ctx.locale.register(NS, DICT); }, PLUGIN_ID + ': dictionaries');
        ctx.effect(function () { return watchApprovals(ctx, scope); }, PLUGIN_ID + ': approval chime');
        ctx.slots.inject('settings.plugin.item', function () {
          return ctx.slots.register(
            { name: 'settings.plugin.item', key: NS, locale: NS,
              inject: function () { return { hooks: { chime: chimeStore(scope) } }; } },
            Card,
          );
        });
      }

      return { name: PLUGIN_ID, inject: inject, apply: apply };
    },
  });
})();
```

> 说明：`chimeStore(scope)`（把 `scope.getSnapshot()` 投影成 `{available, writable, enabled, volume, tone}` 的快照 store）与 `DICT` 词典是 t3 的实现细节；上面的形状来自官方卡片控制器（`.../client.js:845-852` 的 `available: snapshot.status === "ready"`）与 `dsh-quorum-panel` 的 locale 用法（`:1094-1096`、`:1294-1296`）。
> **`react` 的 hook 约束**：官方卡片通过 slot 的 `inject()` 注入 `hooks`，再由渲染器以「快照选择器 hook」形式传进组件（`dsh-client-ui-settings-plugins/lib/client.js:1736-1760` 展示了 hooks 的 `getSnapshot`/`subscribe` 契约）。我们的卡片必须遵守同样的契约，否则 hook 数量在渲染间改变会崩。

---

## H. 未证实 / 风险清单

| # | 事项 | 现状 | 影响 / 处置 |
| --- | --- | --- | --- |
| H1 | 插件 `apply(ctx)` 里 `ctx.baseUrl` 是否可用（路径②） | **未证实**（只有间接证据：`dsh-app-boot:1529` 设置、`dsh-app-boot:135`/`dsh-client-modules:802` 使用） | 若选路径②，必须 try/catch；**首选路径①（junction），已实测** |
| H2 | `uiSession.pendingInteractions` 是否被官方视为第三方可用 API | **未证实**（类型公开、运行时有服务 `uiSession`，但官方文档未把它列为第三方扩展点） | 屏蔽式降级：若 `ctx.uiSession?.pendingInteractions?.subscribe` 不是函数，打印一条明确警告并停用提示音，不要抛 |
| H3 | 每个 session 只暴露一个 pending interaction | **已证实**（`ui-session/lib/client.js:213-227` 按 precedence 取大者） | 同一会话同时有审批与提问时，审批可能被 precedence 更高的域遮蔽 → 提示音漏响。测试时务必只挂审批场景；若需两者都响，需另找信号（或把本插件注册成一个更高 precedence 的域，属于另一条路线） |
| H4 | 改 `lib/client.js` 后是否真的自动热替换 | **未证实**（DSH 侧 `client-hmr` 500ms 轮询每条行 bundle，`dsh-client-hmr/lib/index.js:8-22,44-89`；但工作区旧文档认为必须刷新） | 验收脚本按「重启 DSH + 刷新页面 + 卡片显示 REVISION」执行，别依赖自动热替换 |
| H5 | 浏览器自动播放策略 | **未证实**（AudioContext 未交互时通常为 `suspended`） | 卡片「试听」按钮是用户手势，可 `resume()`；首次审批提示音可能在用户未交互过页面前静音 → 验收流程里先点一次「试听」 |
| H6 | 卡片组件能否直接用官方 `PluginCard`/`CardForm` 外观 | **已证伪为「不可 import」** | 自绘 UI（样式可用 host 的 CSS 变量 `var(--dsw-alias-*)`，见 `dsh-quorum-panel/lib/client.js:131-141`） |
| H7 | `settingsScope` 服务名在 inject 里书写正确性 | **已证实**（`super(ctx, "settingsScope")`，`dsh-client-ui-settings/lib/client.js:1143`） | 卡片插件必须 `inject: ['settingsScope']`，否则 `ctx.settingsScope` 读不到 |
| H8 | DSH 侧重启的必要性 | **已证实**（DSH 内存缓存 bundle 字节 `dsh-client-modules/lib/index.js:825-833`；工作区实测 `交接说明.md:84`） | 交付验收步骤必须包含重启 `dsh web` |
| H9 | profile 的 `node_modules` junction 是否由 `dsh plugin … install` 自动生成 | **未证实为「本次一定成功」**（历史上 pnpm 已为其他 link: 包生成 junction） | 若 pnpm 不动，手工建 junction（§E.3 步骤 2 的退化路径） |
| H10 | 「重复 id 炸启动」的机制 | **已证实**：所有层 patch 先被合并成一个数组，再交给**根 group** 一次性 update —— `@deepseek-ai/cordis-plugin-include/src/index.ts:209-210`（`const data = this.applyPatches(this.data!, config.patches); await this.root.update(data)`），而 `group.ts:64` 对同一数组内重复 id 直接 `throw new TypeError("duplicate loader entry id: …")`。跨层重复 insert 到同一 group 同样落在同一个数组里 | **任何情况下都不要重复 insert 同一 id**；临时停用请用 id 定向的 `disabled: true` |
| H11 | 客户端 scope 的 `decode` 要求值是**普通对象** | **已证实**（`.../client.js:1107-1117`） | 命名空间 schema 必须是 `z.object(...)`，不能是标量 |
| H12 | `settings.yaml` 在非 loopback 浏览器下只写内存 | **已证实**（`persistence = ctx.remote.$host.isLoopback ? "host" : "memory"`，`.../client.js:1345`） | 验收必须用 `http://127.0.0.1:3080` 本机访问 |

---

## I. 本次实测记录（探针与原始输出）

> 探针临时目录 `<workspace>\_probe-symlink\` 已在本任务结束时删除（保持工作区干净）；下面是可原样复现的命令。

### 探针 1：link: 包的裸导入解析（对应 §B.5）

```powershell
$ws="<workspace>"; $t="$ws\_probe-symlink"
New-Item -ItemType Directory -Force -Path "$t\pkgs\fake-plugin\lib","$t\profile\node_modules\@deepseek-ai" | Out-Null
Set-Content "$t\pkgs\fake-plugin\package.json" '{"name":"fake-plugin","version":"0.0.1","type":"module","main":"lib/index.js","exports":{".":"./lib/index.js"}}'
Set-Content "$t\pkgs\fake-plugin\lib\index.js" @'
export async function probe() {
  const out = { url: import.meta.url };
  try { const m = await import("@deepseek-ai/schemastery"); out.schemaType = typeof m.default; }
  catch (e) { out.schemaError = String(e.message).split("\n")[0].slice(0, 140); }
  return out;
}
'@
Set-Content "$t\profile\boot.mjs" @'
const m = await import("fake-plugin");
console.log(JSON.stringify(await m.probe(), null, 2));
'@
New-Item -ItemType Junction -Path "$t\profile\node_modules\fake-plugin" -Target "$t\pkgs\fake-plugin" | Out-Null
New-Item -ItemType Junction -Path "$t\profile\node_modules\@deepseek-ai\schemastery" -Target "<dsh-install>\node_modules\@deepseek-ai\schemastery" | Out-Null
node "$t\profile\boot.mjs"                       # ← CASE 1：schemaError: Cannot find package …
New-Item -ItemType Junction -Path "$t\pkgs\fake-plugin\node_modules\@deepseek-ai\schemastery" -Target "$DSH_HOME\profiles\node_modules\@deepseek-ai\schemastery" | Out-Null
node "$t\profile\boot.mjs"                       # ← CASE 2：schemaType: "function"（成功）
```

输出见 §B.5。

### 探针 2/3：cordis waterfall 顺序与「不调用 next()」的后果（对应 §A.3）

```javascript
import { Context } from "file:///<dsh-install>/node_modules/@deepseek-ai/cordis/lib/index.js";
const ctx = new Context();
const order = [];
ctx.on("approval/request", async (req, next) => { order.push("A(reg1)"); return next(); });
ctx.on("approval/request", async (req, next) => { order.push("B(reg2)"); return "B-answered"; });
ctx.on("approval/request", async (req, next) => { order.push("C(prepend)"); return next(); }, { prepend: true });
console.log(await ctx.waterfall("approval/request", {}, () => { order.push("inner"); return "inner"; }), order.join(" -> "));
// → B-answered  C(prepend) -> A(reg1) -> B(reg2)

const ctx2 = new Context(); const order2 = [];
ctx2.on("approval/request", async () => { order2.push("builtin: never calls next"); return "allowed-once"; });
ctx2.on("approval/request", async (req, next) => { order2.push("chime(late)"); return next(); });
console.log(await ctx2.waterfall("approval/request", {}, () => "inner"), order2.join(" -> "));
// → allowed-once  builtin: never calls next   （chime(late) 根本没进 order2）
```

### 探针 4：设置 schema 形状（对应 §B.6 / §G.2）

```
defaults: {"enabled":true,"volume":70,"tone":"chime"}
withUser: {"enabled":false,"volume":33,"tone":"ping"}
json: {"uid":11,"refs":{"1":{"type":"boolean","meta":{"default":true}},"5":{"type":"number","meta":{"min":0,"max":100,"default":70}},"6":{"type":"const",…}}}
reject volume=200: $.volume expected number <= 100 but got 200
reject tone=nope: $.tone expected "chime" | "ping" | "beep" but got "nope"
```

---

## J. 给下游的一页摘要

1. **触发**：用 `ctx.uiSession.pendingInteractions`（`getSnapshot()` / `subscribe()`）检测**新出现的 `kind === 'approval'`** 条目来响铃；**不要**用 `ctx.remote.$on('approval/request')`（`$on` 不支持 prepend，内置面板不让位，后注册者永不触发）。
2. **DSH 侧**：`inject=['settings']` + `ctx.settings.register('approval-chime', zSchema, {applies:'live'})`，schema 是 `z.object({enabled, volume, tone})`。
3. **schemastery**：工作区 link: 包必须自带 `node_modules/@deepseek-ai/schemastery` junction（指向 `$DSH_HOME\profiles\node_modules\@deepseek-ai\schemastery`），否则裸导入必然失败。
4. **设置入口（rev-7 起，取代 §C 的卡片形态）**：`ctx.slots.inject('settings.section', …)` + `slots.register({name:'settings.section', id:'approval-chime', order:16, label:<thunk>, locale:NS}, Section)` —— `label` 是 thunk、返回 `ctx.locale.bind(NS)` 绑定的 `'nav'` 文案；注册形态与 `文件:行号` 见 §K.2。**不再注册插件页那张卡片**（旧槽已从本 bundle 彻底移除，旧形态的历史记录保留在 §C）。`available` 仍是 `scope.getSnapshot().status === 'ready'`（不 ready 时分区组件返回 `null`，导航行仍在）；**官方 CardForm/numberField 无法 require，UI 自绘**。
5. **client.js 铁律**：经典脚本、只有 factory 闭包、`id` 必须等于包名、只需 `require('react')`。
6. **挂载**：profile `package.json` 的 `link:` + `dsh.profile.bundles` 追加 + 自带 patch 里 insert 一次（**不要**在 profile 的 patch 里重复同 id）+ 重启 `dsh web` + 刷新页面。
7. **落盘与生效**：`$DSH_HOME/settings.yaml` 的 `approval-chime:` 段；客户端经 `settings.describe` 镜像，收到 `settings/document-updated` 即刷新；首次 describe 答复前 `status='loading'`，**分区页不渲染**（`settings.section` 的导航行仍在）。

---

## K. `settings.section` 合同（rev-7 补充：设置入口改迁）

> 本节由 rev-7 实施（任务 t1）追加，记录**取代 §C 的入口路径**：本插件的设置不再注册到插件页那张卡片，
> 而是自己声明一个设置分区。§C 保留为「旧入口（卡片）」的历史记录；**本节是入口路径唯一生效的口径**。
>
> **取代范围（rev-7 文档修复 t4 扩写）**：本文中凡把本插件设置入口指向**插件页卡片**的陈述，一律以本节为准——
> 即 **§C**（设置卡片：`settings.plugin.item` 契约，`:404-565`）、**§E.3**（挂载步骤第 5 步的验收信号，`:729`）、
> **§G.3**（浏览器侧最小骨架，已标注「历史骨架」，`:911-1053`）与 **§J**（给下游的一页摘要第 4 条，`:1140`）。
> 这四节描述的都是 **rev-1 的旧形态**（当时确实如此），**注册形态与验收路径以 §K.1/§K.2 为现行口径**。
> 仓库里 `docs/rev4-*.md`、`docs/rev5-*.md`、`docs/rev6-*.md`、`docs/验证报告.md` 同属历史轮次记录，
> 其「设置 → 插件 / 可配置插件 / 卡片」措辞同样只描述当时的形态（`docs/验证报告.md` 另有 rev-7 横幅）。
>
> 取证锚点与 §0 相同：`<dsh-install>\node_modules\@deepseek-ai\*`（只读）。

### K.1 结论

| 问题 | 结论 | 证据 |
| --- | --- | --- |
| 槽的种类 / 作用域 | `list` / `root`；一个条目 = 导航里的一行 + 一个页面 | `dsh-client-ui-settings-general/lib/client.js:621-624`（在 `sidebar.settings` 条目的 `children` 里声明） |
| 谁声明这个槽 | 设置外壳自己（`SettingsRoot`），所以只要设置面板被挂载，槽就存在 | 同上 `:601-631`（`ctx.slots.inject("sidebar.settings", () => ctx.slots.register({ …, children: { …, "settings.section": {kind:"list", scope:"root"} } }, SettingsRoot))`） |
| 注册选项 | `id`（**必填**，行标识）、`order`（升序排序）、`label`（`string` 或 `() => string`，每次投影重读）、`locale`（绑定字典命名空间，令组件拿到 `props.t`） | `dsh-cordis-client-runner/lib/client.js:3871-3919`（slot 合同的机器可读导出：`id`/`order`/`label` 三个选项的 `type` 与 doc 原文，`example` 给出最小注册形态） |
| `id` 为什么不能复用官方 id | 行以 `id` 标识；复用 = 顶替那一行，而不是新增 | `dsh-client-ui-settings-general/lib/client.js:566-571`（nav store 逐条投影 `id`/`order`/`label`）；`dsh-client-ui-settings-plugins/lib/client.js:1761-1765`（官方 `id:"plugins"`、`order:15`） |
| 已占用 id / order | `general` 0、`models` 10、`plugins` 15、`agent-presets` 20 | `dsh-client-ui-settings-general/lib/client.js:651-661`（general）、`dsh-client-ui-settings-models/lib/client.js:2936-2940`（models）、`dsh-client-ui-settings-plugins/lib/client.js:1761-1765`（plugins）、**`dsh-client-ui-agent-preset/lib/client.js:1520-1522`（`name`/`id: "agent-presets"`/`order: 20` 三行原文，`label` 在 `:1523`；order 只在这里）**；occupants 清单 `dsh-cordis-client-runner/lib/client.js:3911-3916` 只作为 **id 的第二来源**（该行不含 order，OBS-R7-1） |
| label 何时被读 | 槽账本**或** locale revision 变化时重投影 | `dsh-client-ui-settings-general/lib/client.js:560-582`（`getSnapshot()` 里比对 `slots.getVersion("settings.section")` 与 `locale.getSnapshot().revision`，`subscribe` 同时订阅两者） |
| label 能不能本地化 | 能：thunk 里读活动语言即可；thunk **没有 props** | `dsh-cordis-client-runner/lib/client.js:3894`（原文：*“A thunk is re-read on every projection, so localized text follows the active locale without re-registering.”*）；翻译器来源 `dsh-client-locale/lib/client.js:1283-1304`（`bind(ns)` 返回的 `t` 每次调用都走 `fallbackChain(active)`） |
| 组件拿到什么 props | owner props `{close}` + 标准 props（`useResource`/`useSessions`/…）+（配了 `locale` 时）`props.t` | `dsh-cordis-client-runner/lib/client.js:3897`（`SettingsSectionOwnerProps`）、`:3899-3906`（standardProps） |
| 页面标题 | 外壳**不**画标题，分区自己画；官方分区的 `title` 与 `nav` 同文（下引两处） | 外壳只 `renderSlot("settings.section", {close}, {only: active})`（`dsh-client-ui-settings-general/lib/client.js:167`）；官方 `nav/title/intro` 三件套见 `dsh-client-ui-settings-models/lib/client.js:2649-2651`、`:2752-2754` 与 `dsh-client-ui-settings-plugins/lib/client.js:1566-1568`、`:1621-1623` |
| 排版规范（第三方照抄） | `.section{max-width:720px;color:var(--dsw-alias-label-primary);flex-direction:column;gap:12px;display:flex}`、`.title{…;font-size:16px;font-weight:500;line-height:24px}`、`.intro{color:var(--dsw-alias-label-tertiary);margin:0;font-size:14px;line-height:22px}` | `dsh-client-ui-settings-models/lib/client.js:58`（CSS 模块产物原文；用法在 `:1954-1962`） |
| 未知 id 的导航图标 | 回退到齿轮图标，不会出错 | `dsh-client-ui-settings-general/lib/client.js:75-93`（`navIcon(id)`：`models`/`agent-presets`/`plugins` 各一，其余 `IconSettingsOutline16`） |
| 现在插件页会怎样 | 「插件配置」标签页只派发「DSH 服务的命名空间 × 注册到卡片槽的条目」的交集；本插件不再注册、也不再有条目，于是**干净消失** | `dsh-client-ui-settings-plugins/lib/client.js:1140-1152`（`publish()` 里 `served.has(entry.options.key)` 过滤）、`:411-417`（无 namespace 时 `namespaces.length === 0`，不渲染任何卡片） |
| 要不要改 DSH 侧 | **不要**。DSH 侧只注册设置命名空间，与入口位置无关；入口完全由客户端半的注册决定 | `lib/index.js` 只调用 `ctx.settings.register(NS, Schema, {applies:'live'})`（rev-7 未改动该文件） |

> **一处「有意不改」的过期指针（OBS-R7-1 的处置，t4 记录）**：`lib/client.js:58`（文件头注释）与 `lib/client.js:1768`
> （注册处注释）里同样用 `dsh-cordis-client-runner/lib/client.js:3912` 作为「Agent 预设 = order 20」的证据，与本节上表原先的错误引用同源
> （该行不含 order；order 20 只写在 `dsh-client-ui-agent-preset/lib/client.js:1522`）。
> 该文件的字节是**已验证并冻结的锚点**（`80889 B / sha256 6b9c38ce738859c4d0007ee027b994353242d4c8c974b1e39a420cf48d54f5d1`，
> t2 的独立验证与 t3 的需求审查都锚在这份字节上；注释改动会让锚失效并被迫多跑一轮复验），
> 因此 **t4 有意不修改 `lib/**`**：正确引用以本节为准（`dsh-client-ui-agent-preset/lib/client.js:1520-1522`），
> `lib/client.js:58` / `:1768` 的旧指针保留为「已知的历史注释」。这是取舍，不是漏改。

### K.2 采用的注册形态（本仓库 rev-7 的实现）

```js
// lib/client.js（applyInner 内，字典注册之后）
ctx.slots.inject('settings.section', function () {
  return ctx.slots.register(
    {
      name: 'settings.section',
      id: 'approval-chime',   // 自用 id：不撞 general/models/plugins/agent-presets
      order: 16,              // 紧跟「插件」(15)，在「Agent 预设」(20) 之前
      label: navLabel,        // thunk：读 ctx.locale.bind(NS) → 'nav'（zh 通知提醒 / en Notifications）
      locale: NS,             // 令组件拿到 props.t（同一本字典）
    },
    ChimeSection,             // 分区页组件：<h2> + intro + 原控件
  );
});
```

要点：

1. **`inject('settings.section', …)` 等槽被声明**：槽由设置外壳声明，注册发生在回调里，因此「设置外壳尚未挂载」时不会抛错，而是等它出现（工作区先例 `dsh-quorum-panel/lib/client.js:1298-1306` 的注释同义）。
2. **`label` 用 thunk 而不是字符串**：字符串会让导航行冻结在注册时的语言；thunk 每次投影重读（K.1 第 6 行）。
   注意合同正文（`dsh-cordis-client-runner/lib/client.js:3876`）另有一句 *“the registrant re-registers with fresh text on
   locale change, so the shell never subscribes locale state”*——那是更早的写法约定；实现里的 nav store 同时订阅
   slot 账本与 locale revision（`dsh-client-ui-settings-general/lib/client.js:560-582`），因此 thunk 在两种读法下都成立。
3. **标题与导航同文**：字典里 `nav` 与 `title` 取同一文案，页面 `<h2>` 渲染 `t('title')`、导航行渲染 `label()`，两侧不可能漂移；这也是官方三个分区的写法。
4. **列表槽不留 `key`**：`key` 是 keyed 槽（原卡片槽）的配对轴，`settings.section` 用 `id`，不要写 `key`。
5. **降级**：注册整段包在 `try/catch` 里，失败只丢导航行并打印 `[dsh-approval-chime] section registration failed: …`，提示音与其它功能不受影响。

### K.3 未证实项（rev-7 新增）

| # | 事项 | 状态 |
| --- | --- | --- |
| K-U1 | `settings.section` 是否被官方文档明确列为「第三方扩展点」 | **未证实**。它是 DSH 设置外壳自己声明的槽（K.1 第 2 行），契约（`id`/`order`/`label`/`locale`、`kind:'list'`、`scope:'root'`）由 `dsh-cordis-client-runner` 的槽合同导出直接给出（`:3871-3919`），但未见「第三方可注册」的明文承诺 |
| K-U2 | 真实浏览器里导航行的插入位置、图标与滚动表现 | **未证实**（本任务不启动浏览器）。已知：排序是纯 `order` 升序（`:566-571`），未知 id 回退齿轮图标（`:75-93`） |
| K-U3 | 设置外壳未挂载时 `inject` 回调的等待语义 | 依据 `inject` 的既有语义与工作区先例（K.2 第 1 点），**未在本机浏览器实测** |

---

## L. 按会话独立的合同（rev-10 补充）

> 本节由 rev-10 实施（任务 t1）追加，记录三件 DSH 事实：**①会话头部动作槽**（小铃铛挂哪里）、
> **②待审批表以 `sessionId` 为键**（为什么「按会话判断」只要在既有循环里加判断）、
> **③home 解析规则**（覆盖表落盘到哪个路径）。与 §K 一样，取证锚点是
> `<dsh-install>\node_modules\@deepseek-ai\*`（只读），不修改任何 DSH 文件。
>
> rev-10 不取代本文任何旧结论：§K 的入口路径、§F 的设置值通路、§D 的装载方式全部照旧。

### L.1 `conversation.session.header.actions`（会话头部动作槽）

| 问题 | 结论 | 证据 |
| --- | --- | --- |
| 槽的种类 / 作用域 | `list` / `session`（每个会话各一份），标题旁的左对齐动作区，按 `order` 升序 | `dsh-cordis-client-runner/lib/client.js:3102-3106`（机器可读槽合同：`"kind":"list"`、`"scope":"session"`、`summary`「Title-adjacent Session actions in ascending order.」） |
| 注册选项 | `id`（**必填**，格子键）、`order`（升序，默认 0）、`label`（可选；本槽的 owner 不投影 label，故本插件不写） | 同文件 `:3107-3126`（三个 `registerOptions` 的 `type` 与 doc 原文） |
| 谁声明它 | `conversation.session.header` 里的一个条目（即会话头部组件），所以头部挂载期间它存在 | 同文件 `:3148`（`declaredBy`）、`:3156`（`example` 给出 `ctx.slots.inject('conversation.session.header.actions', …)` 的最小形态） |
| `id` 为什么必须自用 | 以 `id` 定位格子：复用官方 id 会**顶替**那一格而不是新增 | 同文件 `:3109-3112`（`id` 的 doc 原文：「a fresh id is added beside the shipped entries, while reusing a shipped id puts you in THAT cell and replaces it」）；`:3155` 记 `replaceRisk: "none"`（新增不冲突） |
| 已占用者与 order | `agent-preset` **-10**、`schedule-catalog` **10**、`job-list` **20**、`agent-team`（本机 profile 未装，order 未取证） | 占用者清单 `dsh-cordis-client-runner/lib/client.js:3149-3154`；order 逐处实测：`dsh-client-ui-agent-preset/lib/client.js:264-270`（`order: -10`）、`dsh-client-ui-schedule/lib/client.js:293-298`（`order: 10`）、`dsh-client-ui-jobs/lib/client.js:266-271`（`order: 20`） |
| 组件拿到什么 props | 会话作用域的标准 props：`sessionId: SessionId`、`t`（配了 `locale` 时）以及 `useSessions`/`useSessionPendingInteraction` 等钩子 | 同文件 `:3129-3144`（`standardProps` 列表含 `sessionId: SessionId`、`useSessionPendingInteraction`）；**用法证据**：`dsh-client-ui-jobs/lib/client.js:117` `function JobListAction({ sessionId, useSessions, t })`、`dsh-client-ui-agent-preset/lib/client.js:189` `function AgentPresetLabel({ sessionId, … })` |
| 头部怎么渲染它 | 标题行里的 `.headerActions` 容器内 `renderSlot("conversation.session.header.actions", {})`，右边紧接 `.headerUtilities`（`conversation.session.header.utilities`）、再右是 `.headerCorner` | `dsh-client-ui-conversation/lib/client.js:15071-15076`（`className: …headerActions` 的 div 的 children 就是 `renderSlot("conversation.session.header.actions", {})`；其后是 `headerUtilities` / `headerCorner`）；排版 `.headerActions{flex:none;align-items:center;gap:8px;display:flex}`、`.headerUtilities{…;margin-left:20px;…}` 在同一文件 `:14652`（CSS 模块产物单行原文） |
| 本插件采用的形态 | `id:'approval-chime'`、`order:30`（三处已占用 order 之外的最小安全值）、`locale:NS`；组件 `SessionChimeAction` 只读 `props.sessionId` 与 `props.t` | `lib/client.js` 的 `applyInner` 内 `ctx.slots.inject(SESSION_SLOT, …)`；自测 `verify/client-half.test.mjs` 断言 id/order/locale、两态 SVG、中英双语 title/aria-label、点击写 POST 的请求体 |

> **未证实（列为 OBS，不当成通过）**：`order` 的**视觉**落点（本机 profile 未装 `agent-team`，其 order 无法实测；只保证与已取证的
> -10/10/20 不相等且在它们之后）。真实浏览器里的图标大小/间距同样未实测（沙箱无浏览器引擎）。

### L.2 待审批表以 `sessionId` 为键（为什么「按会话」是零成本的）

| 问题 | 结论 | 证据 |
| --- | --- | --- |
| 快照是什么 | `ReadonlyMap<SessionId, PendingInteraction>`，整表替换并通知订阅者 | `dsh-client-ui-session/lib/client.js:213-227`（`publishPendingInteractions()`：`const next = new Map()` → `next.set(interaction.sessionId, …)` → `const projected = new Map([...next].map(([sessionId, value]) => [sessionId, value.interaction]))` → `this.pendingSnapshot = projected; notifySubscribers(this.pendingListeners, …)`） |
| 每会话能有几条 | **最多一条**：同会话多条时按 `precedence` 取大者（`precedence >= previous.precedence` 覆盖） | 同文件 `:215-222`；本插件文件头的「KNOWN HOST LIMITS」已记录该限制 |
| 订阅形态 | `getSnapshot()` / `subscribe(listener) => disposer`（HostObservable） | `dsh-client-ui-session/lib/client.js:80-90`（§A/§D 已引用）；本插件 `startApprovalWatch` 即在此形态上做 `key` 去重 |
| 本插件因此改了什么 | `snapshot.forEach(function (interaction, sessionId) { … })` 的**同一个循环**里，把这一批「新出现的 `kind === 'approval'`」收进数组，再逐个用 `sessionSettings(sessionId)` 求 `override ?? global`：可响的各响一次（相邻 180 ms），被静音的不响并计 `suppressedSession` | `lib/client.js` 的 `startApprovalWatch`；自测断言「4 条 pending → 3 响（1 条被本会话静音）+ 时间间隔」 |

### L.3 home 解析规则（覆盖表落盘路径）

| 规则 | 原文/结论 | 证据 |
| --- | --- | --- |
| 最高优先级 | 显式 `configured`（本插件不用：没有配置文件入口） | `@deepseek-ai/dsh-home-paths/lib/index.js:73-76`（`resolveDshHome(configured, env)`） |
| 其次 `$DSH_HOME` | **非空**（`fromEnv.trim().length > 0`）时用它；**纯空白视为未设置**，因此空白覆盖不会把 home 解析到当前工作目录 | 同文件 `:52-61`（`expandHomePath`：`~`/`~/`/`~\` 展开）、`:65-68`（doc 原文：「An empty or whitespace-only `$DSH_HOME` is treated as unset, so a blank override never resolves the home to the current working directory.」） |
| 兜底 | `join(homedir(), '.dsh')` | 同文件 `:11`（`DSH_HOME_DIR_NAME = ".dsh"`）、`:49-51`（`defaultDshHome()`） |
| 为什么不 import 这个包 | 本插件是 `link:` 安装，Node 会按**真实路径**解析它自己的裸导入；历史上 `@deepseek-ai/schemastery` 就踩过这个坑（§B.5/§B.6、`lib/index.js:16-28` 的注释） | 本仓库自测 1 的「包外副本 + 空 `DSH_HOME`」子进程用例就是这条降级的证据 |
| 本插件的实现 | `lib/index.js` 的 `dshHome()` 按同一规则重写（`$DSH_HOME` 去空白后非空则用，否则 `homedir()/.dsh`），覆盖表路径 = `<home>/approval-chime/sessions.json` | `lib/index.js` 的 `dshHome()` / `sessionsDirectory()` / `sessionsFile()`；自测断言「空白 `$DSH_HOME` → `homedir()/.dsh/...`」与「写盘落在 `$DSH_HOME/approval-chime/sessions.json`」 |

### L.4 覆盖文件自身的约束（本仓库自定，非 DSH 合同）

| 约束 | 理由 |
| --- | --- |
| 原子写：同目录临时文件（`.sessions.<pid>.<uuid>.tmp`）+ `rename()` | `rename` 只在同一文件系统内原子；读方要么看到旧文件、要么看到新文件，绝不会看到半截 JSON。写失败时临时文件会被清理 |
| 上限 `MAX_SESSIONS = 200`，按每条记录的 `updatedAt` 淘汰最旧（同刻按 id 定序） | 会话是用户数据、会无限增长；覆盖表不是日志，旧会话的偏好没有保留价值 |
| 空覆盖（三个字段都缺省）不落盘；`null` 表示「清除该字段」 | 「无覆盖」与「跟随全局」必须是磁盘上的同一个状态，否则会留下永远清不掉的行 |
| 非法值一律 400 且**先校验后落盘** | 被拒绝的补丁连文件都不该重写；`volume` 必须是 0..100 的**整数**，`tone` 只接受 `chime|bell|beep|custom:<小写 uuid>`（与 §F 的 schema 同一个闭集） |
| `sessions` 用无原型字典（`Object.create(null)`）读写 | 会话 id 是用户数据，`__proto__` 是合法 JSON 键；普通 `{}` 会把它当成原型赋值 |
| DSH 没注入 `webServer` 时只是不注册路由 | 与音频路由同一姿势（§G.2 的 `registerAudioRoutes` 注释）：硬 `inject:['webServer']` 会让条目在没有 web 服务器的 profile 里永久 pending，那是启动级故障 |

> **本机验收顺序（rev-10 新增）**：`lib/index.js` 变了（新路由 + 新文件），**必须重启 `dsh web`**；
> 只改 `lib/client.js` 时刷新页面即可。这一点与 §K 的「DSH 侧未动」结论不同，见 `docs/挂载与验收.md` §7.1。