@shgroup/dsh-serenity-hooks 1.26.14 → 1.26.16

package/lib/config-ops.d.ts

@@ -0,0 +1,166 @@
+/**
+ * config-ops.ts — plugin 全局配置读写（结构化，`~/.dsh/serenity-hooks.json`）
+ *
+ * 归属原则（S142 用户拍板，v1.22）：**plugin 是全局的，CCC 是具体的**——
+ * 账号密码/gateway 监听配置是 plugin 级能力，归 plugin 全局文件；
+ * CCC 的 localstore.json 只管 CCC 自己的凭据/配置。v1.21.x 曾把
+ * `serenityAdvanced` 存进 CCC localstore（归属错误 + 与 DSH settings 开关割裂），
+ * 本版本迁移到 plugin 全局文件（migrateLegacyLocalstore 一次性迁移）。
+ *
+ * 文件：$DSH_HOME/serenity-hooks.json（缺省 ~/.dsh/serenity-hooks.json；
+ * env SERENITY_HOOKS_CONFIG 可覆盖——测试/部署注入）。
+ * 权限：0600（含账号密码 hash，敏感）。
+ *
+ * 安全：密码仅存 scrypt hash（node:crypto 内置，零依赖）；wire 层永不返回 hash
+ * （GET 只回 user/id，设置面板"密码"字段提交空串 = 不修改）。
+ */
+/** 高级设定节名（localstore.json 顶层） */
+export declare const ADVANCED_SECTION = "serenityAdvanced";
+/** 一个外部访问账号（密码只存 hash，永不落 wire） */
+export interface GatewayAccount {
+    /** 稳定键（UI CRUD 定位） */
+    id: string;
+    /** 登录用户名 */
+    user: string;
+    /** scrypt hash（salt:hex） */
+    passHash: string;
+    /** TOTP 第二因素 secret（v1.22.4；可选；base32 无填充。缺省/空 = 该账号仅密码登录） */
+    totpSecret?: string;
+}
+/** F1 双端口网关配置 */
+export interface GatewaySettings {
+    enabled: boolean;
+    host: string;
+    port: number;
+    accounts: GatewayAccount[];
+    /** 外部可访问的工作区路径前缀白名单（v1.22；空数组 = 全部允许） */
+    workspaces: string[];
+    /** Cookie Secure 属性（v1.22.4；反代 TLS 时开启，明文 HTTP 下必须关） */
+    cookieSecure: boolean;
+    /** 是否允许外部（gateway）新建工作区（v1.22.4；false = workspace.create 一律 403） */
+    allowWorkspaceCreate: boolean;
+    /** 是否启用 Authenticator 第二因素（v1.22.4；false = TOTP 完全禁用——登录不要求、绑定入口隐藏） */
+    totpEnabled: boolean;
+}
+/** F2 超限重建配置 */
+export interface RebuildSettings {
+    enabled: boolean;
+    /** contextPressure 触发比例（0~1） */
+    thresholdRatio: number;
+}
+/** F3 会话命名配置 */
+export interface NamingSettings {
+    enabled: boolean;
+}
+/** 彩蛋功能：persona 模式（v1.23.1，S142 用户需求）
+ * 配置后替换 ACC 系统提示词中"输出约束/指令遵循约束"部分（EAP 块 + MSM 原则段）；
+ * 未配置（mode 空）→ 完全默认行为，零影响。 */
+export interface PersonaSettings {
+    /** 彩蛋模式名（显示用；空 = 彩蛋关闭） */
+    mode: string;
+    /** 用户替换文本（替代 EAP 块 + MSM 原则段的原文） */
+    overrideText: string;
+}
+/** F4d 建议问答页（v1.26.1，S142 用户：按认知容器暴露问答页供他人验证）：
+ * 与 ACP HTTP 共用 3100 端口；key 首次启用自动生成（plugin 全局文件固定），无 key 不工作。
+ * v1.26.2：按容器权限控制——allowed 白名单（容器名）；空 = 全部开放（向后兼容 v1.26.1 全局开放） */
+export interface PublicAskSettings {
+    /** 访问 key（空 = 未生成；首次启用时 ensurePublicAskKey 自动生成随机 key 写回固定） */
+    key: string;
+    /** 开放容器白名单（CCC 目录名，如 home-serenity）；空数组 = 全部容器开放 */
+    allowed: string[];
+}
+/** 高级设定全量（localstore.json 持久化形态；passHash 含 hash） */
+export interface AdvancedSettings {
+    gateway: GatewaySettings;
+    rebuild: RebuildSettings;
+    naming: NamingSettings;
+    persona: PersonaSettings;
+    publicAsk: PublicAskSettings;
+}
+/** 默认值（工厂——每次返回新对象，防止调用方意外共享引用） */
+export declare function defaultAdvancedSettings(): AdvancedSettings;
+/** 生成 scrypt hash（格式 `salt:hex`）；salt 16 字节随机 */
+export declare function hashPassword(password: string): string;
+/** 校验密码与存储 hash（timing-safe） */
+export declare function verifyPassword(password: string, stored: string): boolean;
+/** 全局配置文件路径：env SERENITY_HOOKS_CONFIG 覆盖（测试注入）→ $DSH_HOME → ~/.dsh */
+export declare function globalConfigPath(): string;
+/** 读取全局配置（文件缺失/坏 JSON → 默认值） */
+export declare function readAdvancedSettings(): AdvancedSettings;
+/** 写入全局配置（整体替换） */
+export declare function writeAdvancedSettings(settings: AdvancedSettings): void;
+/**
+ * 部分更新：传入 Partial，深合并到现有值。
+ * accounts 传入数组 → 整体替换；accounts 未传 → 保留现有。
+ */
+export declare function updateAdvancedSettings(patch: Partial<AdvancedSettings>): AdvancedSettings;
+/**
+ * 确保问答页访问 key 存在（首次启用自动生成 + 写回固定，用户拍板"配置时生成"）：
+ * 读取全局配置 publicAsk.key；为空 → 生成 32 字节随机 hex（64 字符）→ 写回持久化。
+ * @returns 当前固定 key（已生成则返回既有值——**幂等**，不会覆盖用户手改的 key）
+ */
+export declare function ensurePublicAskKey(): string;
+/** 校验问答页访问 key（timing-safe；key 未生成 → 恒 false——没有 key 不工作） */
+export declare function verifyPublicAskKey(provided: string | undefined): boolean;
+/**
+ * 轮换问答页访问 key（v1.26.5，S142 用户：公网开放 + 不好说要换 key 呢）：
+ * 生成新 32 字节随机 hex（64 字符）→ 覆盖写回（**强制替换**——旧 key 立即失效）。
+ * @returns 新 key（面板展示给管理员，重新分享给使用者）
+ */
+export declare function rotatePublicAskKey(): string;
+/** 失败锁定阈值（连续失败次数） */
+export declare const PUBLIC_ASK_FAIL_THRESHOLD = 5;
+/** 首次锁定基础时长（指数退避底数） */
+export declare const PUBLIC_ASK_LOCK_BASE_MS: number;
+/** 锁定上限 */
+export declare const PUBLIC_ASK_LOCK_MAX_MS: number;
+/** 重置 IP 失败状态（测试/管理员解封） */
+export declare function resetPublicAskIpFail(ip: string): void;
+/** IP 当前是否锁定（到期自动解锁） */
+export declare function isPublicAskIpLocked(ip: string): boolean;
+/** 记录一次 key 校验失败；达到阈值 → 锁定（指数退避）。返回锁定剩余毫秒（0 = 未锁定） */
+export declare function recordPublicAskFail(ip: string): number;
+/**
+ * 一次性迁移（v1.21.x → v1.22）：旧版把 `serenityAdvanced` 存在 CCC localstore.json；
+ * 新版归 plugin 全局文件。全局文件已存在 → 跳过（幂等）；localstore 无旧节 → 跳过。
+ * @param root - CCC 根（localstore.json 所在目录）
+ * @returns true = 已迁移（旧节保留在 localstore 供回滚，读取方以全局文件为准）
+ */
+export declare function migrateLegacyLocalstore(root: string | null): boolean;
+/** 账号的 wire 形态：只有 id/user + hasPassword/hasTotp（无 hash/secret） */
+export interface GatewayAccountWire {
+    id: string;
+    user: string;
+    hasPassword: boolean;
+    /** 该账号是否已绑定 TOTP（v1.22.4） */
+    hasTotp: boolean;
+}
+/** 设定 wire 形态（GET /serenity/config 返回；rebuild/naming 同持久化，gateway 去 hash） */
+export interface AdvancedSettingsWire {
+    gateway: {
+        enabled: boolean;
+        host: string;
+        port: number;
+        accounts: GatewayAccountWire[];
+        workspaces: string[];
+        cookieSecure: boolean;
+        allowWorkspaceCreate: boolean;
+        totpEnabled: boolean;
+    };
+    rebuild: RebuildSettings;
+    naming: NamingSettings;
+    persona: PersonaSettings;
+    publicAsk: {
+        /** 开放容器白名单（v1.26.2：容器名数组；空 = 全部开放） */
+        allowed: string[];
+    };
+}
+/** 持久化 → wire（剥离 passHash/totpSecret；只留布尔） */
+export declare function toWire(settings: AdvancedSettings): AdvancedSettingsWire;
+/**
+ * wire → 持久化（面板 PUT 用）：
+ * accounts 元素可选带 `pass`：非空 → 重新 hash；空/缺省 → 保留现有 hash（按 id 匹配）。
+ * 新账号（id 不在现有）必须带非空 pass，否则抛错（无法生成 hash）。
+ */
+export declare function applyWirePatch(wire: Partial<AdvancedSettingsWire>): AdvancedSettings;

package/lib/constants.d.ts

@@ -0,0 +1,8 @@
+/** 常量（纯模块，零 DSH 依赖） */
+/** 插件 ID */
+export declare const PLUGIN_ID = "dsh-serenity-hooks";
+/**
+ * ACC 版本：自动从 package.json 读取（单一真相源，消除与 CHANGELOG 的漂移）。
+ * 发布时只需改 package.json 的 version。
+ */
+export declare const ACC_VERSION: string;

package/lib/fs-ops.d.ts

@@ -0,0 +1,36 @@
+/**
+ * fs-ops.ts — cc_fs 纯操作层（零 DSH 依赖，可独立单测）
+ *
+ * 行为对齐 osp（opencode-serenity-plugin/src/fs/file-system-tool.ts）——osp 是 ACC 工具 spec：
+ *   - rm：目录需 recursive 才删除；非空目录无 recursive → [SKIP]；保护 .serenity 与 CCC 根；dry-run 预览
+ *   - cp：目录需 recursive；dst 已存在报错；自动建父目录
+ *   - mv：dst 已存在报错；自动建父目录
+ *   - list/tree/exists/info/find：输出结构与 osp 一致（JSON 元数据 / 嵌套树 / glob+fuzzy 搜索）
+ *   - touch：存在更新 mtime、不存在创建（自动建父目录）；append：自动建父目录 + 返回字节数
+ * 保留 dsp 增强：win32 reveal 用 spawn+unref（explorer GUI 进程退出码不可靠，fire-and-forget）。
+ */
+import type { JsonValue } from './json.js';
+export type CcFsAction = 'root' | 'resolve' | 'exists' | 'list' | 'tree' | 'relative' | 'mkdir' | 'rm' | 'mv' | 'cp' | 'touch' | 'append' | 'reveal' | 'info' | 'find';
+export declare const CC_FS_ACTIONS: readonly CcFsAction[];
+export interface CcFsArgs {
+    action: CcFsAction;
+    path?: string;
+    paths?: string[];
+    src?: string;
+    dst?: string;
+    content?: string;
+    pattern?: string;
+    depth?: number;
+    dryRun?: boolean;
+    /** 对齐 osp：rm 删目录 / cp 复制目录需 recursive */
+    recursive?: boolean;
+    /** 对齐 osp：tree files-only / dirs-only（互斥） */
+    filesOnly?: boolean;
+    dirsOnly?: boolean;
+    /** 对齐 osp：find 返回绝对路径 */
+    absolute?: boolean;
+    /** 对齐 osp：find 最大递归深度（缺省不限） */
+    maxDepth?: number;
+}
+export type CcFsResult = JsonValue;
+export declare function runCcFs(root: string, args: CcFsArgs): CcFsResult;

package/lib/gateway-auth.d.ts

@@ -0,0 +1,89 @@
+/**
+ * gateway-auth.ts — F1 双端口网关：认证域纯逻辑（v1.22.4 安全加固）
+ *
+ * 从 gateway.ts 拆分（S142 熵点治理，v1.22.8）：认证纯逻辑独立成模块——
+ * 登录验证（scrypt）/ 会话 token（滑动 TTL + 吊销）/ 失败锁定（账号维度指数退避）/
+ * CSRF（双提交 + Origin 校验）/ cookie 解析 / 登录页 HTML。
+ * gateway.ts 保留 HTTP 装配（startGateway/registerGateway）并从本模块 import。
+ *
+ * 纯函数设计（可单测）：无 socket/无 HTTP 依赖，全部导出可注入测试。
+ */
+import type { IncomingMessage } from 'node:http';
+export declare function verifyGatewayLogin(accounts: readonly {
+    user: string;
+    passHash: string;
+}[], user: string, password: string): boolean;
+/** 会话滑动过期时长（毫秒）：24h 无活动 → 失效（用户重新登录） */
+export declare const SESSION_TTL_MS: number;
+export interface GatewaySession {
+    token: string;
+    /** 最后活动时间（滑动续期：每次校验通过刷新） */
+    lastActiveAt: number;
+    /** 绑定账号（审计/登出定位） */
+    user: string;
+}
+/** 颁发会话 token（Hex 32 字节） */
+export declare function issueToken(user: string): string;
+/** 主动吊销会话（登出）；返回是否确实存在 */
+export declare function revokeToken(token: string): boolean;
+/**
+ * 校验 token 有效性（滑动过期：有效则刷新 lastActiveAt）。
+ * @returns 有效会话或 undefined
+ */
+export declare function validateToken(token: string | undefined): GatewaySession | undefined;
+/** 失败锁定阈值：连续失败 N 次进入锁定 */
+export declare const FAIL_LOCK_THRESHOLD = 5;
+/** 首次锁定时长（毫秒） */
+export declare const FAIL_LOCK_BASE_MS: number;
+/** 锁定时长指数退避上限 */
+export declare const FAIL_LOCK_MAX_MS: number;
+export interface FailState {
+    /** 连续失败计数（成功登录后清零） */
+    count: number;
+    /** 当前锁定截止时间（0 = 未锁定） */
+    lockedUntil: number;
+    /** 已连续锁定次数（退避指数） */
+    lockRound: number;
+}
+/** 获取账号失败状态（纯逻辑，供测试注入） */
+export declare function getFailState(user: string): FailState;
+/** 重置失败状态（登录成功/管理员解封） */
+export declare function resetFailState(user: string): void;
+/** 账号当前是否锁定（含锁定到期自动解锁——到期后读取即解锁） */
+export declare function isAccountLocked(user: string): boolean;
+/** 记录一次失败；达到阈值 → 锁定（指数退避）。返回锁定剩余毫秒（0 = 未锁定） */
+export declare function recordLoginFailure(user: string): number;
+/** 剩余锁定毫秒（0 = 未锁定） */
+export declare function accountLockRemaining(user: string): number;
+/** CSRF token 有效期（毫秒）：10 分钟窗口（扫码/多标签场景留足时间） */
+export declare const CSRF_TTL_MS: number;
+/** CSRF token 集合上限（防内存膨胀；超限清理最旧） */
+export declare const CSRF_MAX_TOKENS = 50;
+/** 生成 CSRF token（随机 32B hex）并入集合 */
+export declare function newCsrfToken(): string;
+/** token 是否有效（在集合且未过期；过期自动清理） */
+export declare function isCsrfValid(token: string): boolean;
+/** 从请求头取 CSRF token（X-CSRF-Token 或表单字段） */
+export declare function csrfFromRequest(req: IncomingMessage, body: URLSearchParams): string | null;
+/** 常量时间比较（token 校验用） */
+export declare function safeEqual(a: string, b: string): boolean;
+/**
+ * Origin 校验（S3）：跨站 POST 被浏览器强制带 Origin（同源 GET/导航除外）。
+ * 允许：① 同源（Origin.host === 网关自身 host）② 主端口 loopback（127.0.0.1:mainPort）。
+ * 无 Origin（curl/非浏览器直连）→ 仅当携带有效 CSRF 双提交时放行（脚本无 cookie 无法伪造）。
+ * @returns 是否通过
+ */
+export declare function originAllowed(originHeader: string | undefined, reqHost: string, mainPort: number): boolean;
+/** 从 Cookie 头解析指定 cookie 值（纯逻辑，可单测） */
+export declare function cookieValue(header: string | undefined, name: string): string | undefined;
+/**
+ * 登录页：内嵌 HTML 无外部资源——适配任何部署。
+ * 移动端关键点：
+ *  - viewport meta（防止移动浏览器按 980px 视口缩放）
+ *  - 触控目标 ≥ 44px（Apple HIG）；输入字号 ≥ 16px（iOS 聚焦不自动放大）
+ *  - env(safe-area-inset-*) 适配刘海屏/底部手势条
+ *  - color-scheme: dark + 明暗自适应
+ * @param extra - 错误提示文案
+ * @param csrf - CSRF token（隐藏字段随表单双提交；无 = 旧调用方兼容）
+ */
+export declare function loginPageHtml(extra: string, csrf?: string): string;

package/lib/gateway-proxy.d.ts

@@ -0,0 +1,39 @@
+/**
+ * gateway-proxy.ts — F1 双端口网关：代理辅助纯逻辑（v1.22.1-1.22.3 稳定性修复）
+ *
+ * 从 gateway.ts 拆分（S142 熵点治理，v1.22.8）：
+ *  - crypto.randomUUID polyfill（非安全上下文修复，v1.22.0）
+ *  - 反代请求头构造（信任栅栏修复：Host + Origin 同步改写 loopback，v1.22.1）
+ *  - workspace 白名单过滤（响应 items 前缀过滤 + create 校验 + 403 RPC 响应，v1.22）
+ *  - HTML polyfill 注入（幂等 marker）
+ * 纯函数设计（可单测）；gateway.ts 装配层 import 使用。
+ */
+/**
+ * 经第二端口 http://LAN-IP:3081 访问 = 非安全上下文 → DSH client 的
+ * `crypto.randomUUID()`（ui-conversation/service.ts 等）抛错，provider 目录加载失败。
+ * 用 `crypto.getRandomValues` 实现（与 DSH 官方 random-uuid.ts 同算法），
+ * 零改 DSH——gateway 反代 HTML 时注入。
+ */
+export declare const RANDOM_UUID_POLYFILL = "<script>\n(function () {\n  if (typeof crypto === 'undefined' || typeof crypto.randomUUID === 'function') return\n  try {\n    crypto.randomUUID = function () {\n      var bytes = crypto.getRandomValues(new Uint8Array(16))\n      bytes[6] = (bytes[6] & 0x0f) | 0x40\n      bytes[8] = (bytes[8] & 0x3f) | 0x80\n      var hex = Array.from(bytes, function (b) { return b.toString(16).padStart(2, '0') }).join('')\n      return hex.slice(0, 8) + '-' + hex.slice(8, 12) + '-' + hex.slice(12, 16) + '-' + hex.slice(16, 20) + '-' + hex.slice(20)\n    }\n  } catch (e) { /* getRandomValues \u4E5F\u4E0D\u53EF\u7528\u5219\u653E\u5F03 */ }\n})()\n</script>";
+/**
+ * workspace.list 响应过滤（v1.22 白名单）：
+ * DSH client→server RPC 全部走 HTTP JSON（`POST /api/workspace.list`，WS 仅下行推送）。
+ * 白名单（workspaces 路径前缀）非空 → 只保留匹配前缀的 items；
+ * 空 = 全部允许（默认，向后兼容）。
+ */
+export declare function filterWorkspaceList(body: string, allowPrefixes: readonly string[]): string;
+/**
+ * 校验 workspace.create 请求路径是否在白名单内（v1.22）：
+ * 白名单非空且路径不匹配 → 拒绝（由调用方构造 403 RPC 响应）。
+ */
+export declare function workspaceAllowed(allowPrefixes: readonly string[], path: string | undefined): boolean;
+/** 构造 workspace.create 拒绝的 JSON RPC 响应体（code=forbidden） */
+export declare function workspaceDenyResponse(rpcId: string): string;
+/** 在 HTML 的 </head> 前注入 polyfill（幂等：含 marker 则跳过） */
+export declare function injectPolyfillHtml(html: string): string;
+/**
+ * 反代请求头构造（v1.22.1 信任栅栏修复，纯逻辑可测）：
+ * DSH isTrustedApiRequest 要求 Origin.host === Host.host——Host 改写为 loopback 后
+ * Origin 必须同步改写（浏览器 POST 必带 Origin，透传外部地址 → 403）。
+ */
+export declare function buildProxyHeaders(reqHeaders: Record<string, string | string[] | undefined>, mainPort: number, bodyOverride?: string): Record<string, string | number | string[]>;

package/lib/gateway.d.ts

@@ -0,0 +1,80 @@
+/**
+ * gateway.ts — F1 双端口网关（v1.21）+ 安全加固（v1.22.4）——**装配层**
+ *
+ * 需求（S142 用户拍板）：dsh web 维持 127.0.0.1 主端口现状不变，**额外监听一个端口**；
+ * 额外端口需网页登录（账号+密码），登录后即原生 Web UI 使用；适应任何部署情况。
+ *
+ * 实现（零改 DSH）：
+ *   - 插件自起第二 node:http server（host/port 走 localstore 配置，默认 0.0.0.0:3081）
+ *   - 未登录 → 返回内嵌极简登录页（user + pass + submit）
+ *   - POST /serenity/login → 验证账号（localstore accounts，scrypt hash）→ Set-Cookie（HttpOnly）
+ *   - 已登录 → 反向代理到 http://127.0.0.1:${ctx.webServer.port}
+ *     （Host 头改写成 127.0.0.1:<主端口> → 过信任栅栏；WS upgrade 转发握手 + pipe socket）
+ *   - token 内存表 + HttpOnly cookie（重启即失效——用户决策"重启重新登录"）
+ *
+ * v1.22.4 安全加固（S142 公网审计，用户原则：不体验影响直接修/体验影响改方案/不限制 IP）：
+ *   - S5：token 带过期时间（滑动 24h）+ POST /serenity/logout 主动吊销
+ *   - S3：登录 POST 与配置写操作校验 Origin（同源/loopback 主端口）+ 双提交 CSRF cookie
+ *   - S2：账号维度失败锁定（5 次失败 → 15 分钟，指数退避）——不按 IP（用户要求随时随地访问）
+ *   - S1：可选 TOTP 第二因素（账号绑定后登录需 6 位码；Authenticator 兼容，RFC 6238）
+ *   - S7：cookieSecure 配置项（反代 TLS 时开启；默认关保持明文 HTTP 可用）
+ *   - S9：登录失败审计日志（时间/IP/账号/原因，console.warn）
+ *
+ * v1.22.8 熵点治理（S142）：认证域纯逻辑拆到 gateway-auth.ts（会话/锁定/CSRF/Origin/
+ * cookie/登录页），代理辅助纯逻辑拆到 gateway-proxy.ts（polyfill/headers/workspace 过滤）；
+ * 本文件只保留 HTTP 装配（startGateway/registerGateway/readBody）——re-export 两模块
+ * 保持既有 import 面兼容（tests/gateway.test.ts 直接 import 两模块导出）。
+ */
+import type { Context } from 'cordis';
+import { type Server } from 'node:http';
+export { RANDOM_UUID_POLYFILL, injectPolyfillHtml, filterWorkspaceList, workspaceAllowed, workspaceDenyResponse, buildProxyHeaders, } from './gateway-proxy.js';
+export { loginPageHtml, verifyGatewayLogin, SESSION_TTL_MS, issueToken, revokeToken, validateToken, FAIL_LOCK_THRESHOLD, FAIL_LOCK_BASE_MS, FAIL_LOCK_MAX_MS, getFailState, resetFailState, isAccountLocked, recordLoginFailure, accountLockRemaining, newCsrfToken, isCsrfValid, csrfFromRequest, safeEqual, originAllowed, cookieValue, } from './gateway-auth.js';
+declare module 'cordis' {
+    interface Events {
+        /** /serenity/config PUT（账号/监听/白名单变化）→ 强制重建 gateway（lastSig=null） */
+        'serenity/config-updated'(): void;
+        /** DSH settings 简单配置变化（开关/阈值）→ 重新 sync（sig 判断，无实质变化不重建） */
+        'serenity/settings-changed'(): void;
+    }
+}
+export interface GatewayConfig {
+    host: string;
+    port: number;
+    /** 登录态 cookie 名 */
+    cookieName: string;
+    /** 主端口（ctx.webServer.port） */
+    mainPort: number;
+    /** 登录失败后的重定向延迟（秒） */
+    loginDelayMs: number;
+    /** 外部可访问的工作区路径前缀白名单（v1.22；空 = 全部允许） */
+    allowWorkspaces?: string[];
+    /** Cookie Secure 属性（v1.22.4；反代 TLS 时开启；明文 HTTP 下必须关，否则 cookie 不落） */
+    cookieSecure?: boolean;
+    /** 允许外部新建工作区（v1.22.4；false = workspace.create 一律 403 RPC error） */
+    allowWorkspaceCreate?: boolean;
+    /** 启用 Authenticator 第二因素（v1.22.4；false = TOTP 完全禁用） */
+    totpEnabled?: boolean;
+}
+/**
+ * 启动第二监听器。返回 { server, dispose }——dispose 关 server（**不清 token**：
+ * token 模块级，进程重启自然清空；热重建清 token → 已登录用户 WS 断 + 重连 cookie 无效）。
+ * @param config - 监听/代理配置。
+ * @param getAccounts - 运行时读取账号列表（plugin 全局文件；gateway.enabled 开关在调用方判）。
+ */
+export declare function startGateway(config: GatewayConfig, getAccounts: () => readonly {
+    id: string;
+    user: string;
+    passHash: string;
+    totpSecret?: string;
+}[]): {
+    server: Server;
+    dispose: () => void;
+};
+/** 注册 gateway（index.ts apply 调用）。
+ * 归属原则（v1.22）：gateway 是 plugin 全局能力——enabled 开关读 DSH settings
+ * （readSimpleSettings().gatewayEnabled），host/port/accounts 读 plugin 全局文件
+ * （readAdvancedSettings()，~/.dsh/serenity-hooks.json）。**不依赖任何具体 CCC**。
+ * 幂等 sync：仅当 配置/端口/开关 变化时重建监听器。
+ * 事件驱动：config-updated（/serenity/config PUT 后 emit）+ DSH settings 变化（onChange emit）触发重新 sync。
+ */
+export declare function registerGateway(ctx: Context): void;

package/lib/git-ops.d.ts

@@ -0,0 +1,28 @@
+/**
+ * git-ops.ts — cc_git 纯操作层（零 DSH 依赖）
+ *
+ * 行为对齐 osp（opencode-serenity-plugin/src/git/cc-git-tool.ts）——osp 是 ACC 工具 spec：
+ *   - status：JSON {clean, files:[{status,file}], summary}
+ *   - commit：git add -A + commit -m；clean 返回 '(nothing to commit — working tree clean)'
+ *   - push：无 remote 报错；非快进 → [REJECTED] + 操作建议（绝不自动 force）
+ *   - pull：git fetch + merge --ff-only；up-to-date / [REJECTED] 建议
+ *   - log：--oneline [-n <count>]
+ *   - diff：git diff [--cached] [<ref>] [-- <path>]
+ * 保留 dsp 增强：localstore git 合规联动（S134：deny 且 .gitignore 未覆盖 → status 提示 / commit 拒绝）。
+ */
+import type { JsonValue } from './json.js';
+export type GitAction = 'status' | 'commit' | 'push' | 'log' | 'pull' | 'diff';
+export declare const GIT_ACTIONS: readonly GitAction[];
+export interface GitArgs {
+    action: GitAction;
+    message?: string;
+    /** log 条数（对齐 osp 参数 n，默认 10，max 100） */
+    count?: number;
+    /** diff: 显示暂存区变更（--cached） */
+    staged?: boolean;
+    /** diff: 对比 ref（如 HEAD~1 / main / origin/main） */
+    ref?: string;
+    /** diff: 限定路径 */
+    path?: string;
+}
+export declare function runGit(root: string, args: GitArgs): JsonValue;

package/lib/handyman-ops.d.ts

@@ -0,0 +1,68 @@
+/**
+ * handyman-ops.ts — handyman（杂工）纯逻辑层（零 DSH 依赖，可独立单测）
+ *
+ * v1.24.0：loop（牛马）→ handyman（杂工）重命名。语义对齐 osp loop：
+ * 进度文件（handyman-<label>.md/.json）、续跑、轮次 prompt 结构、stop token。
+ * 不兼容旧 loop- 进度文件（用户拍板：仅新 handyman- 前缀）。
+ */
+export interface HandymanProgress {
+    round: number;
+    done: boolean;
+    label: string;
+    model: string;
+    updated: string;
+    lastResponse: string;
+    /** 对齐 osp writeFailedStatus：failed 时 done=true + status=failed + errorCode */
+    status?: 'running' | 'done' | 'failed';
+    errorCode?: string;
+    errorMessage?: string;
+}
+/** label 脱敏（Windows 审计问题 17）：非法字符 → '-'，去尾点/空格，限长（按码点截断，修复代理对切散 U+FFFD） */
+export declare function sanitizeLabel(label: string): string;
+export declare function handymanProgressPaths(root: string, label: string): {
+    md: string;
+    json: string;
+};
+/** 读取进度（续跑）；无文件返回 round 0 */
+export declare function readProgress(root: string, label: string): HandymanProgress | null;
+export declare function writeProgress(root: string, label: string, p: HandymanProgress): void;
+/** 失败状态落盘（对齐 osp writeFailedStatus：done=true / status=failed / errorCode） */
+export declare function writeFailedStatus(root: string, label: string, info: {
+    errorCode: string;
+    errorMessage?: string;
+}): void;
+export declare function newStopToken(): string;
+/** 解析 model 字符串（provider/model）→ {provider, model}；无 / 视为 model-only */
+export declare function splitModel(model: string): {
+    provider: string | undefined;
+    model: string;
+};
+/** 校验模型在白名单内；不在 → 抛错（用户拍板：只能使用 CCC 配置的模型） */
+export declare function requireWhitelistedModel(model: string, models: string[]): void;
+/** 轮次 prompt（对齐老 loop 结构：回顾进度 → 自由工作 → 汇报；S134 EAP 化：固定详尽） */
+export declare function buildRoundPrompt(opts: {
+    root: string;
+    session?: string;
+    label: string;
+    round: number;
+    stopToken: string;
+    progress?: HandymanProgress | null;
+    task?: string;
+}): string;
+/**
+ * handyman 规模化使用指引（guide 子命令输出；S134 继承 + v1.24.0 更新）：
+ * 使用 handyman 前必须先加载 eap 设计方案；并行策略（jobs 编排）；提示词规范（详尽固定 EAP）；
+ * 阅读/文字编写类 handyman 内部也加载 eap。
+ */
+export declare const HANDYMAN_GUIDE = "# handyman \u2014 Scale-Up Usage Guide (guide)\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\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- 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- Recursive subagents inside a handyman inherit the handyman's model automatically (DSH native)\n- Keep the subagent tool instance free of a fixed agentOptions, or model inheritance breaks\n\n### 4. Parallel strategy (jobs orchestration, workflow capability)\n- Independent subtasks can run in parallel via handyman(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 (osp loop standard)\n- The only completion condition = the handyman-internal agent echoes this round's random verification 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 handymen's progress (label / round / last response), one line per parallel job, ~3s refresh\n";
+/** handyman 运行状态（进度文件摘要；WebUI 等待界面数据源） */
+export interface HandymanRunInfo {
+    label: string;
+    round: number;
+    done: boolean;
+    model: string;
+    updated: string;
+    lastResponse: string;
+}
+/** 列出 AGENT_SESSIONS/handyman-*.json 的全部进度（按 updated 倒序；坏文件跳过） */
+export declare function listActiveHandymen(root: string): HandymanRunInfo[];

package/lib/handyman-preset-inherit.d.ts

@@ -0,0 +1,34 @@
+/**
+ * handyman-preset-inherit.ts — handyman worker 的 preset 继承 + 工具面收窄（纯函数，可单测）
+ *
+ * v1.24.0：loop → handyman 重命名。对齐 subagent 先例（applyChildComposition →
+ * agentPresets.composeFrom）：handyman worker 在创建窗口内 join 发起方 agent 的 standing
+ * preset 组合，从而获得 preset 层工具（read/write/edit 等）。
+ *
+ * **工具面收窄（用户拍板）**：worker 内部**不含 handyman 工具本身**——递归编排归主
+ * agent，worker 内部只走 subagent（模型继承 worker，同样低能）。实现：setup 钩子
+ * composeFrom 后对子 scope `tools.restrict({ deny: ['handyman'] })`（同 scope 注册的
+ * 规则，最近 scope 胜出——worker 看不到 handyman，主 agent 不受影响）。
+ *
+ * agentPresets 是可选服务（ctx.get 读取）：
+ *   - 无该服务 / 父未 join preset → 返回空（worker 落全局工具层 + deny handyman）；
+ *   - 有且父已 join → 返回 preset id（写入 session meta 供重建）+ setup 钩子
+ *     （在 agent 未发布前执行 composeFrom + restrict，失败由创建事务回滚）。
+ *
+ * 仅依赖 cordis 的 Context 类型（type-only，运行时擦除）——保持可被 vitest
+ * 直接加载（与 ccc.ts / handyman-ops.ts 同级的纯模块约定）。
+ */
+import type { Context } from 'cordis';
+/** 从父 agent ctx 解析 preset 继承的创建期组合。 */
+export interface HandymanPresetInheritance {
+    /** 父 agent 的 preset id（写入子 session meta.agentPreset，供持久化重建）；无则不写。 */
+    readonly agentPreset?: string;
+    /** 创建 setup 钩子：子 scope join 父的 standing preset + deny handyman 工具；无 preset 继承时仅 deny。 */
+    readonly setup?: (childCtx: Context) => void;
+}
+/**
+ * 解析 handyman worker 从父 agent 继承的 preset，并组装创建 setup 钩子。
+ * @param parentCtx - 发起 handyman 的 agent 的 scope ctx；无（headless/非 agent 上下文）时为 undefined。
+ * @returns 继承结果：meta 用的 agentPreset 与创建 setup 钩子。
+ */
+export declare function handymanPresetInheritance(parentCtx: Context | undefined): HandymanPresetInheritance;

package/lib/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * dsh-serenity-hooks — 宁静号 ACC harness（Native Cordis 插件，DSH 运行时）
+ *
+ * 形态（DSH 官方 native hook 约定）：name / inject / Config / apply，无 default export。
+ *
+ * 能力：
+ *   1. 真实 DSH 工具注册：cc_fs（文件系统 15 子命令，含 reveal）、session（会话全周期 7 子命令）
+ *   2. 拦截缝机械约束：tools/pre-execute + ctx.tools.guard（安全模式/黑名单/路径守卫）
+ *
+ * 加载：~/.dsh/config.yaml 加 insert 行（免改 DSH 源码），插件包装入 DSH node_modules。
+ *
+ * 配置：进程级 Config（cordis.yml 提供）+ 运行时读取 CCC 的 .opencode/serenity.json（规范位置，.dsh 回退）。
+ */
+import type { Context } from 'cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "dsh-serenity-hooks";
+/** 主动调用的服务；其余（agent 事件）随 harness 装配必然存在 */
+export declare const inject: string[];
+/** 插件配置（cordis.yml 提供；进程级） */
+export interface Config {
+    /** CCC 配置相对路径（运行时从根读取）；缺省 .opencode/serenity.json（规范）+ .dsh/serenity.json（回退） */
+    serenityConfigPaths?: string[];
+    /** 注册真实工具 */
+    tools?: boolean;
+    /** 注册拦截缝守卫 */
+    guards?: boolean;
+    /** 注册 session-keeper DCP 提醒 */
+    keeper?: boolean;
+    /** keeper 缺省阈值 */
+    keeperThreshold?: number;
+    /** 注册 ACC 上下文注入（session-start + prompt-submit） */
+    context?: boolean;
+    /** 注册压缩保留（compaction/end 后重注入 ACC 身份） */
+    compactRetention?: boolean;
+    /** 注册 HTTP 状态接口（WebUI 停靠栏） */
+    api?: boolean;
+    /** 身份注入时并入 CCC 入口 skill 内容（0 = 不注入） */
+    entrySkillMaxChars?: number;
+    /** 注册 shell.env（DSH_SERENITY_* 环境事实） */
+    env?: boolean;
+    /** 兼容 opencode skill 标准（provider：.opencode/skills 扫描注册） */
+    opencodeSkills?: boolean;
+    /** F1 双端口网关（简单配置；entry 默认值，运行时经 DSH settings） */
+    gateway?: {
+        enabled?: boolean;
+    };
+    /** F2 超限重建（entry 默认值，运行时经 DSH settings） */
+    rebuild?: {
+        enabled?: boolean;
+        thresholdRatio?: number;
+    };
+    /** F3 会话命名（entry 默认值，运行时经 DSH settings） */
+    naming?: {
+        enabled?: boolean;
+    };
+    /** F4 Skiff（实验性）：调试服务启停（entry 默认值，运行时经 DSH settings） */
+    skiff?: {
+        enabled?: boolean;
+        debugPort?: number;
+    };
+    /** F4c ACP（实验性）：HTTP JSON-RPC 端点启停（entry 默认值，运行时经 DSH settings） */
+    acp?: {
+        enabled?: boolean;
+        httpPort?: number;
+    };
+}
+export declare const Config: z<Config>;
+export declare function apply(ctx: Context, config: Config): void;