@shgroup/dsh-serenity-hooks 1.26.15 → 1.26.17

package/lib/ccc-CfDrlfA7.js

@@ -0,0 +1,141 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+//#region src/ccc.ts
+/**
+* ccc.ts — CCC 纯逻辑层（零 DSH 依赖，可独立单测）
+*
+* 职责：CCC 根检测（P1）、git 检测（P2）、serenity.json 配置读取（.opencode 规范位置，.dsh 回退）、
+* 路径守卫（P3 语义）、安全模式黑名单匹配。
+*
+* 由 tools/ 与 seams/ 复用；逻辑移植自 dsh-serenity-plugin v0.1-v0.2
+* runner（本项目自有代码，非 opencode-serenity-plugin 源码）。
+*/
+function findSerenityRoot(cwd) {
+	let current = resolve(cwd);
+	while (true) {
+		const marker = resolve(current, ".serenity");
+		if (existsSync(marker) && statSync(marker).isFile()) return current;
+		const parent = dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+}
+function findGitRoot(cwd) {
+	let current = resolve(cwd);
+	while (true) {
+		if (existsSync(resolve(current, ".git"))) return current;
+		const parent = dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+}
+/**
+* 前缀判定：abs 是否位于 rootAbs 之内。
+* caseInsensitive（Windows 盘符/路径大小写不敏感）由调用方按平台传入；
+* 边界必须是路径分隔符（`\` 或 `/` 任一）——不依赖平台 sep，跨平台语义一致：
+*   - 跨盘符绝对路径（root 在 D:\、target 在 C:\）前缀不匹配 → outside
+*   - 兄弟目录前缀陷阱（home vs home2）边界非分隔符 → outside
+* （旧实现用 path.relative().startsWith('..')——跨盘时 relative 返回绝对路径原文，
+*   不以 `..` 开头 → 漏判放行，见 Windows 兼容审计问题 1。）
+*/
+function pathInside(rootAbs, abs, caseInsensitive = process.platform === "win32") {
+	const r = caseInsensitive ? rootAbs.toLowerCase() : rootAbs;
+	const a = caseInsensitive ? abs.toLowerCase() : abs;
+	if (a === r) return true;
+	if (!a.startsWith(r)) return false;
+	const next = a[r.length];
+	return next === "\\" || next === "/";
+}
+function classifyPath(p, root) {
+	const rootAbs = resolve(root);
+	const abs = resolve(p);
+	const ci = process.platform === "win32";
+	if (ci ? abs.toLowerCase() === rootAbs.toLowerCase() : abs === rootAbs) return "same";
+	return pathInside(rootAbs, abs, ci) ? "inside" : "outside";
+}
+function resolveInside(root, p) {
+	const abs = resolve(root, p);
+	if (classifyPath(abs, root) === "outside") throw new Error(`Path escape blocked: "${p}" resolves outside "${root}"`);
+	return abs;
+}
+/**
+* 解析 handyman 配置（v1.24.0：取代 loop.defaultModel；不兼容旧 loop 配置——用户拍板）。
+* @returns 白名单 + 缺省模型 + 上限；models 未配置返回 null（工具应报错要求配置）
+*/
+function readHandymanConfig(root, paths = DEFAULT_SERENITY_CONFIG_PATHS) {
+	const cfg = loadSerenityConfig(root, paths);
+	const models = cfg.handyman?.models;
+	if (!Array.isArray(models) || models.length === 0) return null;
+	const clean = models.map((m) => m.trim()).filter(Boolean);
+	if (clean.length === 0) return null;
+	const defaultModel = cfg.handyman?.defaultModel?.trim();
+	return {
+		models: clean,
+		defaultModel: defaultModel !== void 0 && clean.includes(defaultModel) ? defaultModel : clean[0],
+		maxRounds: cfg.handyman?.maxRounds ?? 100,
+		maxParallel: cfg.handyman?.maxParallel ?? 10
+	};
+}
+/**
+* ACC 依赖的 CCC 配置路径（S134 修正：兼容历史——历史在 .opencode，规范位置 = .opencode；
+* .dsh 仅作 dsh 运行时回退，不优先）。
+*/
+const DEFAULT_SERENITY_CONFIG_PATHS = [".opencode/serenity.json", ".dsh/serenity.json"];
+/**
+* 读取 UTF-8 文件并剥离 BOM（Windows 审计问题 16）：PowerShell/Windows 编辑器
+* 写出的 BOM（\uFEFF）会让 JSON.parse 抛错（配置静默变空）或 frontmatter 检测失败（技能被丢弃）。
+*/
+function readUtf8(path) {
+	return readFileSync(path, "utf-8").replace(/^\uFEFF/, "");
+}
+function loadSerenityConfig(root, paths = DEFAULT_SERENITY_CONFIG_PATHS) {
+	for (const candidate of paths) {
+		const p = resolve(root, candidate);
+		if (!existsSync(p)) continue;
+		try {
+			return JSON.parse(readUtf8(p));
+		} catch {
+			return {};
+		}
+	}
+	return {};
+}
+const SAFE_MODE_MARKER = ".serenity-safe-on";
+function isSafeModeOn(root) {
+	return existsSync(resolve(root, SAFE_MODE_MARKER));
+}
+/**
+* 读取黑名单（对齐 osp readBlacklist）：支持两种条目格式——
+*   string：".secrets/" 或 "regex:^..."（前缀 / 正则）
+*   object：{ "pattern": ".secrets/", "message": "自定义提示" }
+* dsp v1.17.4 前只支持 string（对象会被 String() 成 "[object Object]" → 规则失效，不拦截）。
+*/
+function readBlacklist(root, paths = DEFAULT_SERENITY_CONFIG_PATHS) {
+	const rules = loadSerenityConfig(root, paths).safeMode?.blacklist;
+	if (!Array.isArray(rules)) return [];
+	const out = [];
+	for (const item of rules) if (typeof item === "string") {
+		if (item) out.push({ pattern: item });
+	} else if (item && typeof item === "object" && typeof item.pattern === "string") {
+		const obj = item;
+		const p = obj.pattern;
+		if (p) out.push({
+			pattern: p,
+			message: typeof obj.message === "string" ? obj.message : void 0
+		});
+	}
+	return out;
+}
+/** 匹配黑名单规则；命中返回条目，未命中返回 null。前缀匹配 / regex: 前缀（对齐 osp）。Windows：规则反斜杠归一化为正斜杠与 rel 对齐 */
+function matchBlacklist(relPath, rules) {
+	for (const rule of rules) if (rule.pattern.startsWith("regex:")) try {
+		if (new RegExp(rule.pattern.slice(6)).test(relPath)) return rule;
+	} catch {}
+	else {
+		const pat = rule.pattern.split("\\").join("/");
+		if (relPath.startsWith(pat)) return rule;
+	}
+	return null;
+}
+//#endregion
+export { findSerenityRoot as a, matchBlacklist as c, readHandymanConfig as d, readUtf8 as f, findGitRoot as i, pathInside as l, SAFE_MODE_MARKER as n, isSafeModeOn as o, resolveInside as p, classifyPath as r, loadSerenityConfig as s, DEFAULT_SERENITY_CONFIG_PATHS as t, readBlacklist as u };

package/lib/ccc.d.ts

@@ -0,0 +1,162 @@
+/**
+ * ccc.ts — CCC 纯逻辑层（零 DSH 依赖，可独立单测）
+ *
+ * 职责：CCC 根检测（P1）、git 检测（P2）、serenity.json 配置读取（.opencode 规范位置，.dsh 回退）、
+ * 路径守卫（P3 语义）、安全模式黑名单匹配。
+ *
+ * 由 tools/ 与 seams/ 复用；逻辑移植自 dsh-serenity-plugin v0.1-v0.2
+ * runner（本项目自有代码，非 opencode-serenity-plugin 源码）。
+ */
+export declare function findSerenityRoot(cwd: string): string | null;
+export declare function findGitRoot(cwd: string): string | null;
+export type PathClass = 'inside' | 'outside' | 'same';
+/**
+ * 前缀判定：abs 是否位于 rootAbs 之内。
+ * caseInsensitive（Windows 盘符/路径大小写不敏感）由调用方按平台传入；
+ * 边界必须是路径分隔符（`\` 或 `/` 任一）——不依赖平台 sep，跨平台语义一致：
+ *   - 跨盘符绝对路径（root 在 D:\、target 在 C:\）前缀不匹配 → outside
+ *   - 兄弟目录前缀陷阱（home vs home2）边界非分隔符 → outside
+ * （旧实现用 path.relative().startsWith('..')——跨盘时 relative 返回绝对路径原文，
+ *   不以 `..` 开头 → 漏判放行，见 Windows 兼容审计问题 1。）
+ */
+export declare function pathInside(rootAbs: string, abs: string, caseInsensitive?: boolean): boolean;
+export declare function classifyPath(p: string, root: string): PathClass;
+export declare function resolveInside(root: string, p: string): string;
+export interface SerenityConfig {
+    /** handyman（杂工）配置：模型白名单（v1.24.0 取代 loop） */
+    handyman?: {
+        /** 可用模型白名单（provider/model 列表）——handyman 只能使用其中模型（用户拍板：CCC 配置控制） */
+        models?: string[];
+        /** 缺省模型（必须 ∈ models） */
+        defaultModel?: string;
+        /** 对话轮次上限（保险阀，缺省 100） */
+        maxRounds?: number;
+        /** jobs 编排并行上限（缺省 10——便宜模型便宜） */
+        maxParallel?: number;
+    };
+    sessionKeeper?: {
+        threshold?: number;
+    };
+    safeMode?: {
+        blacklist?: string[];
+    };
+    /** localstore git 提交策略（S134 重设计）：allow 可提交 / deny 禁提交（缺省 deny） */
+    localstore?: {
+        gitTrack?: 'allow' | 'deny';
+    };
+    hooks?: {
+        enabled?: boolean;
+        injectAccContext?: boolean;
+        enforceSafeMode?: boolean;
+        sessionKeeper?: boolean;
+        /** 重启自动恢复最近激活的宁静号会话（session-start 时，根会话且无自身标记 → 回退最近 use 的标记） */
+        autoRestoreSession?: boolean;
+    };
+    /** Skiff（F4，v1.25.0 实验性）认知子集角色配置——角色归 CCC 定义（S142 用户拍板） */
+    skiff?: {
+        /** 角色定义（名 → 角色配置）；缺省/空 = Skiff 未启用（零影响） */
+        roles?: Record<string, SkiffRoleConfig>;
+    };
+    /**
+     * 自主轨迹（v1.26.12 实验提案，specs self-sustaining-trajectory-hypothesis）：
+     * CCC 定义的一条自主 trajectory——时钟唤起 + 先验偏见（自生+随机）+ 前台运行。
+     * 未配置或 enabled=false → 机制完全不启动（零资源占用，零影响现有功能）。
+     */
+    autotrajectory?: AutoTrajectorySettings;
+}
+/**
+ * 自主轨迹配置（CCC 定义；S142 用户拍板 v0.5）：
+ * - 偏见内容提供者 = CCC 根目录下脚本（biasProvider，缺省 autotrajectory-bias.ts）——
+ *   tool 直接运行取 stdout 作为偏见内容；脚本缺失 → 报错要求实现（不再经 mech-registry 注册 MSM）
+ * - 会话标志 = 目录名后缀 `--auto`（验证用方便）：AGENT_SESSIONS/<date>--<desc>--auto/
+ * - **session 必填**（用户拍板：自动唤起不默认任何会话——CCC 日常有多条 trajectory 在跑，
+ *   未配置明确目标绝不唤起）；唤起窗口避开北京时间 8~18 点（用量峰谷省钱——用户拍板）
+ */
+export interface AutoTrajectorySettings {
+    /** 总开关（缺省 false——默认关，未开零资源占用） */
+    enabled?: boolean;
+    /** 无人类活动 N 小时后自动唤起（缺省 12） */
+    intervalHours?: number;
+    /** 偏见内容提供者脚本（相对 CCC 根；缺省 autotrajectory-bias.ts——缺失报错要求实现） */
+    biasProvider?: string;
+    /**
+     * 轨迹焦点（topPrompt，v1.26.17，用户"确保自动轨迹质量"）：**CCC 定义 autotrajectory 时
+     * 自己填写**的顶层提示词——本轨迹的核心目标/纪律/质量要求。**每次唤起最先注入**（位于
+     * 身份锚定之前，影响力最大），作为稳定焦点锚定 trajectory，防止多轮自主唤起中焦点丢失
+     * （腐化）。区别于偏见内容（每轮随机探索方向）：焦点=稳定锚，偏见=随机探索，两者互补。
+     * 实验经验：trajectory 在多轮中腐化严重（焦点丢失）——topPrompt 即为此而设。
+     */
+    topPrompt?: string;
+    /** **必填**：目标会话（S### / 目录名）——未配置绝不唤起（CCC 日常多轨迹并行，不默认） */
+    session?: string;
+    /** 避开唤起的高峰时段（北京时间，[start, end) 内不唤起；缺省 {8, 18}——用量峰谷省钱） */
+    avoidWakeHours?: {
+        start?: number;
+        end?: number;
+    };
+}
+/**
+ * Skiff 角色配置（CCC 定义：全知全能轨迹的一个子集）：
+ * 能力面 = tools（非 MSM 工具白名单）+ msms（MSM 白名单）双白名单，白名单外全隐藏；
+ * 轨迹纪律面 = trajectory 子集（session/keeper/rebuild 参与项，默认全关）。
+ * 实验性质：未配置任何角色时 Skiff 完全零影响（无监听、无 agent 创建）。
+ */
+export interface SkiffRoleConfig {
+    /** 角色模型（provider/model；CCC 直接指定，无白名单校验——用户拍板） */
+    model?: string;
+    /** MSM 白名单（独立）：该角色可 exec 的 MSM 名列表；缺省空 = 无 MSM 通道 */
+    msms?: string[];
+    /** 非 MSM 工具白名单（独立）：平台/ACC 工具名列表；缺省空 = 仅 MSM 通道 */
+    tools?: string[];
+    /** 轨迹纪律子集（缺省全 false = 完全独立，不参与 keeper/session/rebuild） */
+    trajectory?: {
+        session?: boolean;
+        keeper?: boolean;
+        rebuild?: boolean;
+    };
+    /** 角色系统提示词（CCC 完整定义：人格/认知边界/回答风格） */
+    systemPrompt?: string;
+    /** 角色系统提示词文件（推荐：相对 CCC 根引用 md 文件——超长提示词在 JSON 内嵌不可读；
+     *  优先于 systemPrompt；文件缺失/逃逸 → resolveRoleSystemPrompt 抛错） */
+    systemPromptFile?: string;
+}
+/**
+ * 解析 handyman 配置（v1.24.0：取代 loop.defaultModel；不兼容旧 loop 配置——用户拍板）。
+ * @returns 白名单 + 缺省模型 + 上限；models 未配置返回 null（工具应报错要求配置）
+ */
+export declare function readHandymanConfig(root: string, paths?: string[]): {
+    models: string[];
+    defaultModel: string;
+    maxRounds: number;
+    maxParallel: number;
+} | null;
+/**
+ * ACC 依赖的 CCC 配置路径（S134 修正：兼容历史——历史在 .opencode，规范位置 = .opencode；
+ * .dsh 仅作 dsh 运行时回退，不优先）。
+ */
+export declare const DEFAULT_SERENITY_CONFIG_PATHS: string[];
+/**
+ * 读取 UTF-8 文件并剥离 BOM（Windows 审计问题 16）：PowerShell/Windows 编辑器
+ * 写出的 BOM（\uFEFF）会让 JSON.parse 抛错（配置静默变空）或 frontmatter 检测失败（技能被丢弃）。
+ */
+export declare function readUtf8(path: string): string;
+export declare function loadSerenityConfig(root: string, paths?: string[]): SerenityConfig;
+export declare const SAFE_MODE_MARKER = ".serenity-safe-on";
+export declare function isSafeModeOn(root: string): boolean;
+/** 黑名单条目（对齐 osp BlacklistEntry）：pattern + 可选自定义拦截提示 message */
+export interface BlacklistRule {
+    pattern: string;
+    message?: string;
+}
+/**
+ * 读取黑名单（对齐 osp readBlacklist）：支持两种条目格式——
+ *   string：".secrets/" 或 "regex:^..."（前缀 / 正则）
+ *   object：{ "pattern": ".secrets/", "message": "自定义提示" }
+ * dsp v1.17.4 前只支持 string（对象会被 String() 成 "[object Object]" → 规则失效，不拦截）。
+ */
+export declare function readBlacklist(root: string, paths?: string[]): BlacklistRule[];
+/** 匹配黑名单规则；命中返回条目，未命中返回 null。前缀匹配 / regex: 前缀（对齐 osp）。Windows：规则反斜杠归一化为正斜杠与 rel 对齐 */
+export declare function matchBlacklist(relPath: string, rules: BlacklistRule[]): BlacklistRule | null;
+/** 写类工具名（safe-mode 下禁止） */
+export declare const WRITE_TOOLS: Set<string>;
+export declare function isWriteTool(toolName: string): boolean;

package/lib/client.js

@@ -4445,6 +4445,11 @@ Instruction-following style:
 						desc: status.biasProvider,
 						control: null
 					}) }),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("li", { children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(RowCard, {
+						title: "轨迹焦点 (topPrompt)",
+						desc: status.topPrompt ? status.topPrompt : "未定义——CCC 定义 autotrajectory 时应填写本轨迹核心焦点（防多轮唤起焦点丢失）",
+						control: null
+					}) }),
 					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("li", { children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(RowCard, {
 						title: "立即唤起",
 						desc: wakeResult ?? "调试：手动触发一次唤起（跳过窗口/间隔，仍校验配置与偏见脚本）",

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[]>;