@shgroup/dsh-serenity-hooks 1.49.0 → 1.50.1

package/dsh.plugin.json

@@ -1,10 +1,10 @@
 {
   "id": "dsh-serenity-hooks",
-  "version": "1.49.0",
+  "version": "1.50.1",
   "main": "lib/index.js",
-  "description": "宁静号 ACC harness（Native Cordis 插件）：给 DSH 装一个「AI 工作区」——11 个工具（container_fs/container_trajectory/dashboard/container_git/msm/praxis/handyman/localstore/container_admin/im-bridge/acc-diag；后两个按配置条件出现）+ 机械约束（安全模式/工作区围墙/密钥守卫）+ 轨迹日志与原地重建 + 网页登录入口/微信桥/子角色/对外问答页/trajectory 唤醒注册表。适配 DSH 0.1.5-rc.2（deepseek-ai/deepseek-harness）。",
+  "description": "宁静号 ACC harness（Native Cordis 插件）：给 DSH 装一个「AI 工作区」——11 个工具（container_fs/container_trajectory/dashboard/container_git/msm/praxis/handyman/localstore/container_admin/im-bridge/acc-diag；后两个按配置条件出现）+ 机械约束（安全模式/工作区围墙/密钥守卫）+ 轨迹日志与原地重建 + 网页登录入口/微信桥/子角色/对外问答页/trajectory 唤醒注册表。适配 DSH 0.1.7-rc.1（deepseek-ai/deepseek-harness）。",
   "engines": {
-    "dsh": ">=0.1.5-rc.2"
+    "dsh": ">=0.1.7-rc.1"
   },
   "contributes": {
     "tools": [

package/lib/handyman-ops.d.ts

@@ -82,7 +82,7 @@ export declare function buildRoundPrompt(opts: {
  * 使用 handyman 前必须先加载 eap 设计方案；并行策略（jobs 编排）；提示词规范（详尽固定 EAP）；
  * 阅读/文字编写类 handyman 内部也加载 eap。
  */
-export declare const HANDYMAN_GUIDE = "# handyman \u2014 Scale-Up Usage Guide (guide)\n\n## Two modes (v1.31.3; default = foreground)\n| | foreground (default) | background |\n|---|---|---|\n| What | one serial child agent runs the task ONCE and returns its final text | loop-validated worker: hard while-loop + random completion code |\n| Use when | you need exactly one result back now (per-case testers, single conversions) | long/unattended work needing anti-early-finish, resumability, or parallel jobs |\n| Loop / validation | none | stop-token is the ONLY completion condition; round cap (default 100); auto-restart (\u2264100) |\n| Progress file | none | AGENT_SESSIONS/handyman-<label>.md/.json (same label resumes) |\n| Parallel jobs | no (call once per task) | yes (jobs=[...], handyman.maxParallel default 10) |\n| Mechanism | host delegation service ctx.subagents.start(\"spawn\") + agentOptions | ctx.agents.create + internal while-loop |\n| Model source | CCC handyman.models whitelist (same for both) | same |\n\n## \u26A0\uFE0F Before using: load eap and design the plan\nBefore calling handyman, load eap (acc-eap skill) and design the \"scale-up handyman plan\" based on the EAP framework.\n\n### 1. Task decomposition (E\u2191 Explicit)\n- Split large tasks into explicit subtasks: each subtask defines goal / input / boundaries (what to do, what not to do) / acceptance criteria\n- Make dependencies explicit: dependent tasks run serially, independent ones can run in parallel (background mode)\n\n### 2. Prompt design (handyman's task parameter)\n- task must be detailed, fixed, and EAP-compliant: clear goal, drawn boundaries, decidable acceptance criteria\n- foreground mode: the child does NOT share your conversation \u2014 restate everything it needs in task\n- Anti-example \"handle this file\" \u2014 ambiguous; good example \"read <path>, extract all rows of the\u300C\u5173\u952E\u51B3\u7B56\u300Dtable,\n  output a JSON array (fields id/conclusion/evidence), do not modify the original file\"\n- Reading/curating or text-writing work (extracting from files, summarizing, writing docs, generating text, etc.):\n  the handyman-internal agent is also required to load eap and organize output per the EAP standard\n\n### 3. Model whitelist (CCC-configured, mandatory)\n- handyman only uses models listed in .opencode/serenity.json \"handyman.models\" \u2014 never arbitrary models\n- The CCC is expected to point this whitelist at LOW-COST models: handyman is the bulk-execution channel\n- background mode: recursive subagents inside a worker inherit the worker's model automatically (DSH native)\n- foreground mode: the child is started through the host delegation service with the resolved model\n\n### 3b. \uD83D\uDD34 Provider availability (per-machine \u2014 the whitelist is NOT enough)\n- The whitelist lives in the **CCC** (\"serenity.json\", it **travels with the repository**), but provider\n  **adapters are registered per machine by the host** (profile config / settings namespace). An entry that\n  works on one machine can fail on another with: \"no adapter registered for provider <p>\".\n- Before spawning, handyman verifies the provider of the resolved model against the adapters registered\n  **on this machine**; if it is missing it reports the requested model, where it is configured, **the\n  providers that ARE available here**, any declared-but-dormant route (with its settings namespace), and the\n  exact fix \u2014 foreground puts this in \"diagnostic\", background throws it.\n- \u21D2 If you see \"has no adapter registered on this machine\": edit \".opencode/serenity.json\" \"handyman.models\"\n  (and \"handyman.defaultModel\") to a provider listed as available, or activate/register the provider on this\n  machine. **Do not retry the same call unchanged** \u2014 it fails identically.\n\n### 4. Parallel strategy (background mode only)\n- Independent subtasks can run in parallel via handyman(mode=\"background\", jobs=[...]): each job gets its own label + task + stop token + progress file\n- Concurrency safety guaranteed: unique sessionId (handyman-<label>-<uuid>), progress files isolated per label\n  (AGENT_SESSIONS/handyman-<label>.json) \u2014 same label resumes, different labels never interfere\n- Parallel cap: handyman.maxParallel (default 10 \u2014 cheap models are cheap)\n- Aggregation: after each parallel job produces progress, the main agent merges (or spawns one aggregation handyman)\n- For programmable pipeline/phase orchestration at scale, use the platform's workflow tool instead\n\n## Completion criteria\n- foreground: the child's run settles; done=true only when stopReason=\"completed\" (otherwise read diagnostic)\n- background (osp loop standard): the only completion condition = the worker echoes this round's random verification\n  code (stop token); dialogue round cap (default 100, osp fail-safe, forced stop beyond the cap, resumable);\n  automatic restart on abnormal agent stop (\u2264100 restarts, anti-infinite-loop)\n\n## Waiting UI\n- The WebUI session-header Serenity detail card shows running background handymen's progress\n  (label / round / last response), one line per parallel job, ~3s refresh (foreground mode writes no progress)\n";
+export declare const HANDYMAN_GUIDE = "# handyman \u2014 Scale-Up Usage Guide (guide)\n\n## Two modes (v1.31.3; default = foreground)\n| | foreground (default) | background |\n|---|---|---|\n| What | child agent(s) run the task ONCE and return their final text (jobs=[...] \u21D2 parallel, cap 5) | loop-validated worker: hard while-loop + random completion code |\n| Use when | you need result(s) back now (per-case testers, single conversions, parallel fan-out) | long/unattended work needing anti-early-finish, resumability, or parallel jobs |\n| Loop / validation | none | stop-token is the ONLY completion condition; round cap (default 100); auto-restart (\u2264100) |\n| Progress file | none | AGENT_SESSIONS/handyman-<label>.md/.json (same label resumes) |\n| Parallel jobs | **yes** \u2014 jobs=[{task,label?,model?},...], **cap 5 (fixed)** | yes (jobs=[...], handyman.maxParallel default 10) |\n| Mechanism | host delegation service ctx.subagents.start(\"spawn\") + agentOptions | ctx.agents.create + internal while-loop |\n| Model source | CCC handyman.models whitelist (same for both) | same |\n\n## \u26A0\uFE0F Before using: load eap and design the plan\nBefore calling handyman, load eap (acc-eap skill) and design the \"scale-up handyman plan\" based on the EAP framework.\n\n### 1. Task decomposition (E\u2191 Explicit)\n- Split large tasks into explicit subtasks: each subtask defines goal / input / boundaries (what to do, what not to do) / acceptance criteria\n- Make dependencies explicit: dependent tasks run serially, independent ones can run in parallel (both modes)\n\n### 2. Prompt design (handyman's task parameter)\n- task must be detailed, fixed, and EAP-compliant: clear goal, drawn boundaries, decidable acceptance criteria\n- foreground mode: the child does NOT share your conversation \u2014 restate everything it needs in task\n- Anti-example \"handle this file\" \u2014 ambiguous; good example \"read <path>, extract all rows of the\u300C\u5173\u952E\u51B3\u7B56\u300Dtable,\n  output a JSON array (fields id/conclusion/evidence), do not modify the original file\"\n- Reading/curating or text-writing work (extracting from files, summarizing, writing docs, generating text, etc.):\n  the handyman-internal agent is also required to load eap and organize output per the EAP standard\n\n### 3. Model whitelist (CCC-configured, mandatory)\n- handyman only uses models listed in .opencode/serenity.json \"handyman.models\" \u2014 never arbitrary models\n- The CCC is expected to point this whitelist at LOW-COST models: handyman is the bulk-execution channel\n- background mode: recursive subagents inside a worker inherit the worker's model automatically (DSH native)\n- foreground mode: the child is started through the host delegation service with the resolved model\n\n### 3b. \uD83D\uDD34 Provider availability (per-machine \u2014 the whitelist is NOT enough)\n- The whitelist lives in the **CCC** (\"serenity.json\", it **travels with the repository**), but provider\n  **adapters are registered per machine by the host** (profile config / settings namespace). An entry that\n  works on one machine can fail on another with: \"no adapter registered for provider <p>\".\n- Before spawning, handyman verifies the provider of the resolved model against the adapters registered\n  **on this machine**; if it is missing it reports the requested model, where it is configured, **the\n  providers that ARE available here**, any declared-but-dormant route (with its settings namespace), and the\n  exact fix \u2014 foreground puts this in \"diagnostic\", background throws it.\n- \u21D2 If you see \"has no adapter registered on this machine\": edit \".opencode/serenity.json\" \"handyman.models\"\n  (and \"handyman.defaultModel\") to a provider listed as available, or activate/register the provider on this\n  machine. **Do not retry the same call unchanged** \u2014 it fails identically.\n\n### 4. Parallel strategy (both modes)\n- Independent subtasks can run in parallel:\n  \u00B7 **foreground** \u2014 handyman(jobs=[{task,label?,model?},...]) \u21D2 fan-out of custom-model subagents, **cap 5**,\n    results come back **in the order you passed them** (label is only a display name here; per-job \"model\" allowed)\n  \u00B7 **background** \u2014 handyman(mode=\"background\", jobs=[...]): each job gets its own label + task + stop token + progress file\n- Concurrency safety guaranteed: unique sessionId (handyman-<label>-<uuid>), progress files isolated per label\n  (AGENT_SESSIONS/handyman-<label>.json) \u2014 same label resumes, different labels never interfere\n- Parallel cap: **foreground 5 (fixed)** / background handyman.maxParallel (default 10 \u2014 cheap models are cheap)\n- Aggregation: foreground returns all outputs in one result; background: after each parallel job produces progress, the main agent merges (or spawns one aggregation handyman)\n- For programmable pipeline/phase orchestration at scale, use the platform's workflow tool instead\n\n## Completion criteria\n- foreground: the child's run settles; done=true only when stopReason=\"completed\" (otherwise read diagnostic)\n- background (osp loop standard): the only completion condition = the worker echoes this round's random verification\n  code (stop token); dialogue round cap (default 100, osp fail-safe, forced stop beyond the cap, resumable);\n  automatic restart on abnormal agent stop (\u2264100 restarts, anti-infinite-loop)\n\n## Waiting UI\n- The WebUI session-header Serenity detail card shows running background handymen's progress\n  (label / round / last response), one line per parallel job, ~3s refresh (foreground mode writes no progress)\n";
 /** handyman 运行状态（进度文件摘要；WebUI 等待界面数据源） */
 interface HandymanRunInfo {
     label: string;

package/lib/host/contract.d.ts

@@ -61,8 +61,40 @@ type HostEventName = (typeof HOST_EVENT_NAMES)[number];
  * dsp 订阅的宿主事件清单（与 HOST_EVENT_NAMES 同源；impact/site 供 health 报告与文档）。
  */
 export declare const HOST_EVENTS: readonly HostEventContract[];
-/** dsp 被验证过的宿主版本范围（与 package.json peerDependencies 同源，单一真相源） */
-export declare const REQUIRED_HOST_RANGE = "^0.1.7-rc.1";
+/**
+ * dsp **被验证过的宿主版本档**（单一真相源）—— 每档 = 一个半开区间 `[floor, ceiling)`。
+ *
+ * 🔴 为什么是"档"而不是一条 caret 范围（R↓：2026-09-28 0.2.0-rc.1 适配轮实测得出）：
+ *  - **宿主门的判据是真 semver**（`@deepseek-ai/dsh-app-boot:evaluatePluginCompatibility`
+ *    = `semver.satisfies(runtime, range, { includePrerelease: true })`）⇒ **它支持 `||` 联合范围**；
+ *  - 而 **dsp 这边是手写比较器**（{@link compareSemver}），**不实现 semver 的 range 语义**：
+ *    旧写法"用正则从 `REQUIRED_HOST_RANGE` 剥前缀取 floor"在**联合范围上会取到垃圾**
+ *    （`^0.1.7-rc.1 || ^0.2.0-rc.1` 的预发布捕获组 `(.*)` 会**吞掉 `||` 之后整段**）
+ *    ⇒ 判定**变瞎**（既非"通过"也非"低于下限"，而是不可解释的值）。
+ *  ⇒ 故**档表是唯一被验证的真相**：`REQUIRED_HOST_RANGE`（给宿主门看的串）与
+ *    `checkHostVersion`（给自己的手写比较器）**都从它派生**，两者不可能互相漂移。
+ *
+ * 🔴 两档的由来（**实测，非推断**；判据表见插件仓 `docs/dsh-0.2.0-rc.1-adaptation-plan.md` §7.4）：
+ *  - `^0.1.7-rc.1` 在 `0.2.0-rc.1` 上被宿主**整包拒绝 ＋ 回滚**
+ *    （逐字 `installation rejected: … incompatible with dsh 0.2.0-rc.1` ＋ `restored package.json, …`）；
+ *  - 单档 `^0.2.0-rc.1` 会**同样硬拒本机正在跑的 `0.1.7-rc.2`**
+ *    ⇒ 发布后 deploy 必须先升宿主，**而升级会打断本容器**；
+ *  - ⇒ 双档是**唯一不把本机宿主堵死的写法**（两档在真 semver 下均 PASS）。
+ * 档上界取 `<0.2.0` / `<0.3.0`（即 `^0.2.0-rc.1` 的 caret 上界）：第二档同时覆盖
+ * `0.2.0` 正式版与后续 `0.2.0-rc.N`。
+ */
+export declare const VERIFIED_HOST_BANDS: readonly {
+    floor: string;
+    ceiling: string;
+}[];
+/**
+ * 与 `package.json` 的 `peerDependencies` **逐字同串**的宿主版本范围（由 {@link VERIFIED_HOST_BANDS} 派生）。
+ *
+ * 🔴 这个字符串**就是**宿主门（`evaluatePluginCompatibility`）拿去跑 `semver.satisfies` 的那个串
+ * ⇒ 它与档表**必须一致**（"声明 union、判定单档"是一种自相矛盾）。
+ * 一致性由 `tests/host-contract.test.ts` 的**跨文件对账用例**钉住（读 package.json 逐字比对）。
+ */
+export declare const REQUIRED_HOST_RANGE: string;
 interface HostContractIssue {
     id: string;
     kind: 'service' | 'member' | 'version';
@@ -80,13 +112,14 @@ export interface HostContractReport {
 /** 最小 semver 比较（无依赖）：返回 -1 / 0 / 1；解析失败返回 null */
 export declare function compareSemver(a: string, b: string): number | null;
 /**
- * 宿主版本是否落在 dsp 被验证的范围（`REQUIRED_HOST_RANGE`）。
+ * 宿主版本是否落在 dsp **被验证过的档**（{@link VERIFIED_HOST_BANDS}）之内。
  * 无版本信息 → 视为未知（ok=false，detail 说明），不猜测。
  *
- * floor/ceiling **从 `REQUIRED_HOST_RANGE` 派生**（v1.31.6，0.1.5-rc.1 适配轮）：
- * 此前 floor 是独立硬编码字面量——改 `REQUIRED_HOST_RANGE` 而忘改 floor 会造出
- * "常量说 0.1.5、判定用 0.1.2" 的双真相源。ceiling 无法从 caret 语义机械派生（手写比较器
- * 不实现 semver 的 caret 规则），故保留显式常量并在此声明其含义。
+ * 🔴 **逐档判**（v1.50.x，0.2.0-rc.1 适配轮）：判据 = "∃ 档：`version >= floor ∧ version < ceiling`"。
+ * 曾经的做法是"从 `REQUIRED_HOST_RANGE` 剥前缀取一个 floor ＋ 一个显式 ceiling"——
+ * **单档假设一旦不成立（改联合范围），那个正则就会取到垃圾**（详见 {@link VERIFIED_HOST_BANDS}
+ * 的注释）⇒ 故本函数**只读档表**，不再从范围串反推。
+ * ⚠️ 手写比较器**不实现 semver 的 range 语义**（本条只做"区间内/外"），这也是必须逐档判的原因。
  */
 export declare function checkHostVersion(version: string | null): {
     ok: boolean;

package/lib/human-channel.d.ts

@@ -0,0 +1,218 @@
+/**
+ * human-channel.ts — 人机信道的**机制层**（机器级；2026-09-26 owner 定案 ⇒ 方案 §2.6）
+ *
+ * ## 为什么单独一个模块（方案 §5-12）
+ * 今天"机制"与"渠道实现"混在 `weixin-bridge.ts` 里。P0-2 要立的这条不变量是**机器级**的 ——
+ * 它**跨 CCC**、且与"微信"无关（飞书桥／邮件桥同样要守）⇒ 抽到这里；`weixin-bridge` 只做接线。
+ *
+ * ## 本模块唯一的不变量
+ * 🔴 **一账号一 poller**：同一个**账号**（= 同一个 bot 身份）在**同一时刻只有一个轮询者**。
+ * 今天的形态是"**按 CCC 起桥**"（`for entry of listCccs ⇒ syncCccBridge`）⇒ 若两个 CCC 各自
+ * 配了**同一个**微信账号（同一份凭据），就会**两处轮询同一条消息** ⇒ 重复投递 ＋ 重复落盘
+ * （方案 §3.6 的"顺带解决"就是这一条）。
+ *
+ * ## 🔴 账号的"身份"是什么（本模块最容易写错的一处）
+ * **不是 `accountId`** —— 它是**每 CCC 的本地标签**（今天两处都叫 `wechat-1` 完全可能是两个
+ * 不同的微信号）。跨 CCC 能辨认同一个 bot 的**唯一**依据是**凭据内容**（token）。
+ * ⇒ `accountIdentity()` 以 **token 的哈希**为身份；**没有 token** 时才退回
+ * `ccc:<root>|<accountId>`（那时身份里带了 root ⇒ 跨 CCC 不可能撞车，也就不会误判成"同一账号"）。
+ *
+ * ## 边界
+ * 本模块做三件事（**都属机制**，与"哪个渠道"无关）：
+ *  ① **归属判定**（P0-2：谁能起 poller、谁被谁占着）—— 见下 §归属判定
+ *  ② **订阅表查询 ＋ 入站路由决策**（P0-3：`(账号, 用户) → (CCC, 角色)`）—— 见 §订阅表
+ *  ③ **机器级留痕**（P0-3：未投递 ／ 目标不存在 ／ 表残缺）—— 见 §留痕。
+ *     🔴 为什么这些必须机器级：它们**没有目标 CCC** ⇒ 落进任何 CCC 都是"编一个"目标。
+ * **不碰**：轮询循环、凭据解析、会话投递 —— 那些是**渠道实现**，留在 `weixin-bridge.ts`。
+ * ⇒ 本模块**零 DSH 依赖**（只有 `node:crypto` ／ `node:fs`），可独立单测。
+ */
+import type { HumanChannelSubscriptionSettings } from './settings-section.js';
+/** 一个"想为该账号起 poller"的请求（来自某 CCC） */
+export interface PollerRequest {
+    /** 发起方 CCC 根（绝对路径） */
+    root: string;
+    /** 该 CCC 本地账号键 */
+    accountId: string;
+    /** 账号的**机器级身份**（由 `accountIdentity()` 算得） */
+    identity: string;
+}
+/** 账号当前的拥有者 */
+export interface AccountOwner {
+    root: string;
+    accountId: string;
+}
+/** 已归属表（identity → 拥有者）；只读视图，供判定用 */
+export type AccountOwners = ReadonlyMap<string, AccountOwner>;
+export interface PollerClaimPlan {
+    /** 可以起 poller 的请求（去重后） */
+    claims: PollerRequest[];
+    /** 被跳过者 ＋ **谁占着**（供响亮登记：被跳过不能是静默的） */
+    skipped: Array<{
+        request: PollerRequest;
+        ownedBy: AccountOwner;
+    }>;
+}
+/**
+ * 算账号的**机器级身份**。
+ *
+ * - 有 token ⇒ `token:<sha256 前 16 位>`（**跨 CCC 可辨同一 bot**；不落原文，日志/状态面可安全展示）
+ * - 无 token（未扫码绑定等）⇒ `ccc:<root>|<accountId>`（**退化为每 CCC 唯一** ⇒ 不会误判撞车）
+ * @param root CCC 根
+ * @param accountId 该 CCC 本地账号键
+ * @param token 凭据 token（可缺省）
+ */
+export declare function accountIdentity(root: string, accountId: string, token: string | undefined): string;
+/**
+ * 归属判定（**纯函数**：不改任何状态）。
+ *
+ * 规则三条（**同批**与**跨批**刻意用不同判据，别合并——合并会放过"同一 CCC 里两个本地键绑同一个 bot"）：
+ *  ① **同批**内同身份重复 ⇒ **一律跳过**（后者）—— 与是哪个 CCC 无关。实例：某 CCC 的账号表里
+ *     `wechat-1` 与 `wechat-2` 绑的是同一个 bot ⇒ 若豁免"自己"，它就会为同一个 bot 起**两个**循环。
+ *  ② 身份已被**别的** CCC 占着 ⇒ 跳过（记 `ownedBy`）—— 这就是"一账号一 poller"的主判据。
+ *  ③ 身份被**自己**占着 ⇒ **照常 claim**（热重建语义：`syncCccBridge` 会先释放自己的旧归属再重新
+ *     claim；把"自己占着"也判成冲突会让**配置一变就再也起不来**）。
+ * @param requests 本批请求（顺序即优先级：先到先得）
+ * @param owners 当前归属表（`pollerOwners()`）
+ */
+export declare function planPollerClaims(requests: readonly PollerRequest[], owners: AccountOwners): PollerClaimPlan;
+/** 当前归属表（只读视图；供判定与状态面用） */
+export declare function pollerOwners(): AccountOwners;
+/** 落实一批 claim（调用方在**真正起了 poller 之后**调它） */
+export declare function commitPollerClaims(plan: PollerClaimPlan): void;
+/**
+ * 释放某 CCC 的**全部**归属（热重建/停止时先调它，再重新 claim）。
+ *
+ * 🔴 为什么"先全放再 claim"是安全的：`syncCccBridge` 内这一段是**同步**的（中间没有 await）
+ * ⇒ 不存在"刚放开就被别人抢走"的窗口；且**别人**在这次调用里本来就抢不到（它的请求会被
+ * 判成"被 <本 CCC> 占着"而跳过）⇒ 归属**粘在本 CCC**，不会在两个 CCC 之间来回漂。
+ * @param root 要释放的 CCC 根
+ * @returns 被释放的身份数（日志/判据用）
+ */
+export declare function releasePollersOf(root: string): number;
+/** 清空归属表（插件 dispose） */
+export declare function releaseAllPollers(): void;
+/** 测试专用：复位进程级归属表（生产零调用） */
+export declare function __resetPollersForTest(): void;
+/** 订阅表里**完好**的一行（四个字段全部非空） */
+export interface SubscriptionHit {
+    account: string;
+    user: string;
+    ccc: string;
+    role: string;
+}
+/**
+ * 订阅表里的**残缺行**（缺字段）。
+ * 🔴 它**不是**"未命中"（见上）；且**与是否命中无关** —— 表里只要有残缺行就要出声，
+ * 否则"命中了一条完好的"会让人以为整张表是干净的。
+ */
+export interface SubscriptionDefect {
+    /** 行序（0 基）—— 报错要指得出是**哪一行** */
+    index: number;
+    /** 缺哪些字段（`account` ／ `user` ／ `ccc` ／ `role`） */
+    missing: string[];
+    /** 行里**已有**的字段（残缺行的可见部分：让人认得出是哪一行） */
+    present: Record<string, string>;
+}
+export interface SubscriptionLookup {
+    /** 命中的行（未命中 ⇒ `null`） */
+    hit: SubscriptionHit | null;
+    /** 表里残缺的行（**与是否命中无关**，一律要出声） */
+    defects: SubscriptionDefect[];
+    /** 表里**完好**的行数（供调用方区分"表是空的"与"表里没有你"） */
+    usable: number;
+}
+/**
+ * 订阅表查询（**纯函数**）。
+ *
+ * 匹配两段式（**刻意对齐**旧 `matchWeixinRoute` 的 exact → `*` 兜底）：
+ *  ① `account` **精确** ∧ `user` **精确**
+ *  ② `account` **精确** ∧ `user === '*'`（通配兜底）
+ * 🔴 `account` **不设通配**：它是机器级账号的**显式身份**（表里写的就是账号 id）；
+ *   给账号也开 `*` 会让"这条订阅到底覆盖哪个 bot"变得不可读。
+ * 🔴 `user` 保留 `*`：这是**有意的**——存量 CCC 级 `routes` 用的就是 `{user:'*'}`，
+ *   迁移（P0-4）要能**逐字平移**它，否则"迁移"会悄悄改变行为。
+ *
+ * @param subscriptions 机器级订阅表（`readSimpleSettings().humanChannel.subscriptions`）
+ * @param account 收到的**账号 id**（poller 身份；不是 token）
+ * @param user 发信人 id
+ */
+export declare function lookupSubscription(subscriptions: readonly HumanChannelSubscriptionSettings[], account: string, user: string): SubscriptionLookup;
+/** 入站投递目标**从哪来**（判据用；也是"这条消息为什么被投到这里"的可重建依据） */
+export type InboundRouteSource = 'machine' | 'ccc-fallback';
+/** 未投递的原因（两档，措辞刻意不同 —— 见 `planInboundRoute`） */
+export type InboundSkipReason = 'no-subscription' | 'no-match';
+export interface InboundRoutePlan {
+    /** 投递目标（`null` ⇒ **不投递**） */
+    target: {
+        ccc: string;
+        role: string;
+    } | null;
+    /** 目标出处（`null` ⇔ `target === null`） */
+    source: InboundRouteSource | null;
+    /** 未投递的原因（`target !== null` ⇒ `null`） */
+    skipReason: InboundSkipReason | null;
+    /** 订阅表里残缺的行（**与是否命中无关**，一律要出声） */
+    defects: SubscriptionDefect[];
+}
+/**
+ * 入站路由决策（**纯函数**）。
+ *
+ * 顺序：**机器级订阅表优先** → 未命中时用 CCC 级回退。
+ *
+ * 🔴 **回退是过渡期的"不打断在用的微信"**（方案 §11.3 **Q5**）：机器级账号表为空时，
+ * 桥仍按 CCC 起、路由也仍认 CCC 级 `routes`。机器级一旦配起来，回退传 `null`
+ * ⇒ **未命中 = 不投递**（不是"投给默认角色"——那正是方案 §3.1 明令禁止的）。
+ * @param input.subscriptions 机器级订阅表
+ * @param input.account 收到的账号 id
+ * @param input.user 发信人 id
+ * @param input.fallback CCC 级回退目标（`{ccc, role}`）；无 ⇒ `null` ／ 省略
+ */
+export declare function planInboundRoute(input: {
+    subscriptions: readonly HumanChannelSubscriptionSettings[];
+    account: string;
+    user: string;
+    fallback?: {
+        ccc: string;
+        role: string;
+    } | null;
+}): InboundRoutePlan;
+/**
+ * 留痕落点：`$DSH_HOME/human-channel-audit.jsonl`（缺省 `~/.dsh/human-channel-audit.jsonl`）。
+ *
+ * 🔴 **为什么是机器级而不是某个 CCC 的 `_weixin-logs/`**：本文件记的事件（未投递 ／
+ * 目标不存在 ／ 表残缺）**恰恰是"没有目标 CCC"的那些** —— 落进任何一个 CCC 都是**编一个**目标。
+ * （投递成功的入站事件仍落**被路由到的那个 CCC** 的 `_weixin-logs/`，方案 §3.6 不变。）
+ * env `SERENITY_HUMAN_CHANNEL_AUDIT` 覆盖（测试注入；与 `SERENITY_HOOKS_CONFIG` 同款推导）。
+ */
+export declare function humanChannelAuditPath(): string;
+/**
+ * 留痕事件。
+ * 🔴 **刻意不记消息正文**：方案 §3.1 要的是"**谁**发的、**为什么**没投" —— 正文既不必要，
+ * 又会把人说的话抄进一个机器级文件（本该只落在他自己 CCC 的日志里）。
+ */
+export type HumanChannelAuditEvent = {
+    kind: 'inbound-unrouted';
+    account: string;
+    user: string;
+    reason: InboundSkipReason;
+    detail: string;
+} | {
+    kind: 'inbound-target-missing';
+    account: string;
+    user: string;
+    ccc: string;
+    role: string;
+    detail: string;
+} | {
+    kind: 'subscription-defect';
+    account: string;
+    index: number;
+    missing: string[];
+    present: Record<string, string>;
+};
+/**
+ * 追加一条留痕。**永不抛** ——
+ * 留痕失败绝不能反过来打断投递（它是**旁路**，与 `invokeWeixinHook` 的"旁路容忍"同款）。
+ * 🔴 **不静默的是它记的那件事**，不是它自己：所以调用方仍要**另行 `console` 出声**。
+ */
+export declare function appendHumanChannelAudit(event: HumanChannelAuditEvent): void;

package/lib/index.d.ts

@@ -17,6 +17,80 @@ export declare const name = "dsh-serenity-hooks";
 /** 主动调用的服务；其余（agent 事件）随 harness 装配必然存在
  *  （v1.28.0 适配 0.1.2-rc.1：+ 'settings'——B4 settings 服务由 provider 插件加载后才有） */
 export declare const inject: string[];
+/**
+ * human-channel（人机信道）的**机器级**配置形状（2026-09-26 owner 定案 ⇒ 实现方案 §2.2）。
+ *
+ * ## 为什么落在这里
+ * **插件 Config 本身就是机器级的**（宿主 `serenity-hooks` 命名空间，一个 dsh 进程一份），
+ * 而 human-channel 的三张表（账号 ／ 订阅 ／ 主控）天然是**跨 CCC** 的 ⇒ 不必新造文件。
+ *
+ * ## 为什么只有一种拼写（与 `gatewayEnabled` ／ `gateway.enabled` 那对刻意不同）
+ * 那一对是「面板层扁平键」与「部署层嵌套段」的分工；human-channel 是**结构化表**，
+ * 面板整块读写它 ⇒ **多一种拼写就多一个会漂的真相源**。
+ *
+ * ## 各字段为什么一律不 `.required()`
+ * schemastery 的「不 `.required()` 即可选」⇒ 手写 Config ／ 部署 bundle 里可以整段不给。
+ * 🔴 **实测更正（2026-09-26，真 schemastery）**：经宿主 Loader 解析后**本段恒存在** ——
+ *    `Config({}).humanChannel` = `{accounts:[],subscriptions:[],relay:{},sending:{allow:['*']}}`
+ *    （子段对象被**物化**、数组取各自缺省）。⇒ 「没设过」在**解析面上不可观测**；那与
+ *    「面板层扁平键刻意无缺省」（`gatewayEnabled` 那一类，为的是让位给部署层）是**两回事**。
+ * ⇒ 由此两条纪律：① 缺省值**只在 schema 写一次**（读取面的缺省与它同值，不各写一套）；
+ *    ② 读取面仍要能处理「整段不存在」（手写 Config ／ 未走宿主解析的调用方）。
+ *    ⚠️ 另实测：显式 `sending.allow: []` **穿过解析仍为 `[]`**（`.default()` 不吞显式空数组）——
+ *    这是「谁都不许」语义的地基。
+ *
+ * 🔴 **`relay.ccc` = 唯一主控**：人设（机器级），**CCC 不得自声明**（自声明 = 自己给自己发通行证）。
+ * 🔴 **`sending.allow` 缺省 `['*']`** = 所有 CCC 都能发给人（owner Q7 裁决）；显式 `[]` = 谁都不许
+ *    （**不是**"回退到 `*`" —— 见投影的 `??` 语义）。
+ */
+/**
+ * human-channel **账号表的一行**（机器级）。
+ * 🔴 声明成 `type` 而**不是** `interface`：`type` 的对象字面量形态带**隐式索引签名**
+ * ⇒ 才满足 schemastery 内部 `ObjectS<X extends Dict>` 对 `Dict` 的约束（`interface` 不带）。
+ */
+export type HumanChannelAccountConfig = {
+    /** 账号 id（机器内唯一；订阅表按它引用） */
+    id?: string;
+    /** 渠道实现名（注册表里的 id；`weixin` ／ 将来的 `feishu` ／ `mail`） */
+    channel?: string;
+    /** 该账号轮询开关（缺省 true —— 投影归一为定值布尔） */
+    enabled?: boolean;
+    /** 凭据（owner Q3：落插件 Config，机器级；面板可编辑） */
+    token?: string;
+    /** 渠道侧的用户标识（iLink 的 `ilink_user_id`） */
+    userId?: string;
+};
+/** human-channel **订阅表的一行**：`(账号, 用户) → (CCC, 角色)`（声明为 `type` 的理由同上） */
+export type HumanChannelSubscriptionConfig = {
+    /** 账号 id（∈ `accounts[].id`） */
+    account?: string;
+    /** 渠道侧的用户标识（如 `userA@im.wechat`；`*` = 通配兜底） */
+    user?: string;
+    /** 目标 CCC（别名） */
+    ccc?: string;
+    /** 目标 skiff 角色名（∈ 该 CCC 的 `skiff.roles`） */
+    role?: string;
+};
+export interface HumanChannelConfig {
+    /** 账号表（`id` 是订阅表引用它的键；`channel` 是渠道实现名，如 `weixin`） */
+    accounts?: HumanChannelAccountConfig[];
+    /**
+     * 订阅表：`(账号, 用户) → (CCC, 角色)` —— **收到**谁的消息。
+     * 🔴 机器级**显式表**，**不得**由"该 CCC 有没有 skiff 角色"推断（owner 2026-09-26 更正）：
+     * skiff 用途很多（传话员只是其一），推断会让**为别的目的建的 skiff 被静默误接上微信**。
+     */
+    subscriptions?: HumanChannelSubscriptionConfig[];
+    /** 主控（relay）：**唯一**可做跨 CCC 动作的 CCC */
+    relay?: {
+        /** CCC 别名（空白 ／ 缺省 ⇒ 无主控，投影归一为 `null`） */
+        ccc?: string;
+    };
+    /** 出站（CCC → 人）：谁能给人发消息 */
+    sending?: {
+        /** 白名单（`*` = 全体；缺省 `['*']`）；显式 `[]` = 谁都不许 */
+        allow?: string[];
+    };
+}
 /** 插件配置（cordis.yml 提供；进程级） */
 export interface Config {
     /** CCC 配置相对路径（运行时从根读取）；缺省 .opencode/serenity.json（规范）+ .dsh/serenity.json（回退） */
@@ -82,10 +156,10 @@ export interface Config {
     visionPatch?: {
         enabled?: boolean;
     };
+    /** human-channel（人机信道；**机器级**；2026-09-26 owner 定案）—— 见 `HumanChannelConfig` */
+    humanChannel?: HumanChannelConfig;
     /** F1 双端口网关总开关（面板层；部署层同义键 = `gateway.enabled`） */
     gatewayEnabled?: Volatile<boolean | undefined>;
-    /** F2 超限重建总开关（面板层；部署层同义键 = `rebuild.enabled`） */
-    rebuildEnabled?: Volatile<boolean | undefined>;
     /** F2 触发阈值（K token；面板层；部署层同义键 = `rebuild.thresholdK`） */
     rebuildThresholdK?: Volatile<number | undefined>;
     /** F4 Skiff 调试服务总开关（面板层；部署层同义键 = `skiff.enabled`） */
@@ -103,6 +177,12 @@ export interface Config {
     /** 无人值守代理回复总闸（面板层；无部署层同义键；缺省关） */
     unattendedEnabled?: Volatile<boolean | undefined>;
 }
+/** schemastery 的 schema 类型（别名只为可读；**名字取自全局命名空间**，见上方 TS2742 说明） */
+type SchemaOf<S, T = S> = Schemastery<S, T>;
+/** human-channel 账号行 schema（行形状 = `HumanChannelAccountConfig`） */
+export declare const humanChannelAccountSchema: SchemaOf<HumanChannelAccountConfig>;
+/** human-channel 订阅行 schema：`(账号, 用户) → (CCC, 角色)` */
+export declare const humanChannelSubscriptionSchema: SchemaOf<HumanChannelSubscriptionConfig>;
 export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     serenityConfigPaths: z<string[], string[], "defined">;
     tools: z<boolean, boolean, "defined">;
@@ -154,6 +234,33 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     }>>, Schemastery.ObjectT<NoInfer<{
         enabled: z<boolean, boolean, "defined">;
     }>>, "plain">;
+    humanChannel: z<Schemastery.ObjectS<NoInfer<{
+        accounts: z<HumanChannelAccountConfig[], HumanChannelAccountConfig[], "defined">;
+        subscriptions: z<HumanChannelSubscriptionConfig[], HumanChannelSubscriptionConfig[], "defined">;
+        relay: z<Schemastery.ObjectS<NoInfer<{
+            ccc: z<string, string, "plain">;
+        }>>, Schemastery.ObjectT<NoInfer<{
+            ccc: z<string, string, "plain">;
+        }>>, "plain">;
+        sending: z<Schemastery.ObjectS<NoInfer<{
+            allow: z<string[], string[], "defined">;
+        }>>, Schemastery.ObjectT<NoInfer<{
+            allow: z<string[], string[], "defined">;
+        }>>, "plain">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        accounts: z<HumanChannelAccountConfig[], HumanChannelAccountConfig[], "defined">;
+        subscriptions: z<HumanChannelSubscriptionConfig[], HumanChannelSubscriptionConfig[], "defined">;
+        relay: z<Schemastery.ObjectS<NoInfer<{
+            ccc: z<string, string, "plain">;
+        }>>, Schemastery.ObjectT<NoInfer<{
+            ccc: z<string, string, "plain">;
+        }>>, "plain">;
+        sending: z<Schemastery.ObjectS<NoInfer<{
+            allow: z<string[], string[], "defined">;
+        }>>, Schemastery.ObjectT<NoInfer<{
+            allow: z<string[], string[], "defined">;
+        }>>, "plain">;
+    }>>, "plain">;
     gatewayEnabled: z<boolean, boolean, "volatile">;
     rebuildThresholdK: z<number, number, "volatile">;
     skiffEnabled: z<boolean, boolean, "volatile">;
@@ -214,6 +321,33 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     }>>, Schemastery.ObjectT<NoInfer<{
         enabled: z<boolean, boolean, "defined">;
     }>>, "plain">;
+    humanChannel: z<Schemastery.ObjectS<NoInfer<{
+        accounts: z<HumanChannelAccountConfig[], HumanChannelAccountConfig[], "defined">;
+        subscriptions: z<HumanChannelSubscriptionConfig[], HumanChannelSubscriptionConfig[], "defined">;
+        relay: z<Schemastery.ObjectS<NoInfer<{
+            ccc: z<string, string, "plain">;
+        }>>, Schemastery.ObjectT<NoInfer<{
+            ccc: z<string, string, "plain">;
+        }>>, "plain">;
+        sending: z<Schemastery.ObjectS<NoInfer<{
+            allow: z<string[], string[], "defined">;
+        }>>, Schemastery.ObjectT<NoInfer<{
+            allow: z<string[], string[], "defined">;
+        }>>, "plain">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        accounts: z<HumanChannelAccountConfig[], HumanChannelAccountConfig[], "defined">;
+        subscriptions: z<HumanChannelSubscriptionConfig[], HumanChannelSubscriptionConfig[], "defined">;
+        relay: z<Schemastery.ObjectS<NoInfer<{
+            ccc: z<string, string, "plain">;
+        }>>, Schemastery.ObjectT<NoInfer<{
+            ccc: z<string, string, "plain">;
+        }>>, "plain">;
+        sending: z<Schemastery.ObjectS<NoInfer<{
+            allow: z<string[], string[], "defined">;
+        }>>, Schemastery.ObjectT<NoInfer<{
+            allow: z<string[], string[], "defined">;
+        }>>, "plain">;
+    }>>, "plain">;
     gatewayEnabled: z<boolean, boolean, "volatile">;
     rebuildThresholdK: z<number, number, "volatile">;
     skiffEnabled: z<boolean, boolean, "volatile">;
@@ -225,3 +359,4 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     unattendedEnabled: z<boolean, boolean, "volatile">;
 }>>, "plain">;
 export declare function apply(ctx: Context, config: Config): void;
+export {};