@shgroup/dsh-serenity-hooks 1.26.15 → 1.26.17

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;

package/lib/index.js

@@ -7100,14 +7100,14 @@ async function fetchBiasContent(root, providerRel) {
 		error: "偏见内容提供者脚本无法运行（bun 与 node 均不可用）"
 	};
 }
-/** 唤起消息（三段式：身份锚定 / 先验偏见[自生动机+偏见内容] / 任务）——注入前台会话，用户可见 */
+/** 唤起消息（四段式：轨迹焦点[CCC 定义，稳定] / 身份锚定 / 先验偏见[自生动机+偏见内容] / 任务）——注入前台会话，用户可见 */
 function buildWakeMessage(opts) {
-	const lines = [
-		`[自主轨迹唤起] — 距上次轨迹活动已满 ${opts.intervalHours} 小时，自动继续。`,
-		"",
-		`身份锚定：继续 ${opts.sessionName} 的 trajectory（SESSION.md: ${opts.mdPath}）。`,
-		"先验偏见："
-	];
+	const lines = [];
+	if (opts.topPrompt) {
+		lines.push(`[轨迹焦点] ${opts.topPrompt}`);
+		lines.push("");
+	}
+	lines.push(`[自主轨迹唤起] — 距上次轨迹活动已满 ${opts.intervalHours} 小时，自动继续。`, "", `身份锚定：继续 ${opts.sessionName} 的 trajectory（SESSION.md: ${opts.mdPath}）。`, "先验偏见：");
 	if (opts.motivation) lines.push(`  · 自生动机：${opts.motivation}`);
 	if (opts.biasContent) lines.push(`  · 偏见内容：${opts.biasContent}`);
 	if (!opts.motivation && !opts.biasContent) lines.push("  · （无——本轮纯自主探索）");
@@ -7164,6 +7164,7 @@ async function performAutoTrajectoryWake(ctx, root, settings, opts = {}) {
 		sessionName: basename(dirname(mdPath)),
 		mdPath,
 		intervalHours: Math.max(1, settings.intervalHours ?? 12),
+		topPrompt: settings.topPrompt?.trim() || null,
 		motivation,
 		biasContent: biasRes.text
 	});
@@ -7321,6 +7322,7 @@ function getAutoTrajectoryStatus(root) {
 		enabled: cfg?.enabled ?? false,
 		intervalHours: Math.max(1, cfg?.intervalHours ?? 12),
 		biasProvider: cfg?.biasProvider?.trim() || "autotrajectory-bias.ts",
+		topPrompt: cfg?.topPrompt?.trim() || null,
 		session: cfg?.session ?? null,
 		avoidWakeHours: {
 			start: cfg?.avoidWakeHours?.start ?? DEFAULT_AVOID_HOURS.start,
@@ -7497,7 +7499,7 @@ function renderDiagLive(r) {
 function createAutoTrajectoryExpTool(ctx) {
 	return defineTool({
 		name: "autotrajectory-exp",
-		description: "自主轨迹实验（Self-Sustaining Trajectory）一站式管理——实验提案 v1.26.14，默认关。无参/action=all：全报告（背景摘要 + 就绪检查 + 状态 + 下一步）——CCC agent 看一次即完整理解实验并知道怎么开始；init：初始化辅助（写配置 + 生成偏见提供者脚本模板）；random：运行偏见提供者脚本输出当前偏见内容；diag：唤起条件链诊断（--ccc <path> 指定 CCC，无参递归扫描 /home/yh 两层——覆盖任意实验 CCC 位置；逐条件输出 + 阻断点 + 修复建议）；diag-live：**进程内诊断**（v1.26.14——live 会话清单/标题/agent 定位/面板解析目标；排查\"面板检测不到实验 CCC\"）；doc：实验定义全文；check/status/guide：单项。实验是 CCC 的自选动作——dsp 只提供工具与知识，不自动安装任何东西。",
+		description: "自主轨迹实验（Self-Sustaining Trajectory）一站式管理——实验提案 v1.26.14，默认关。无参/action=all：全报告（背景摘要 + 就绪检查 + 状态 + 下一步）——CCC agent 看一次即完整理解实验并知道怎么开始；init：初始化辅助（写配置 + 生成偏见提供者脚本模板）；random：运行偏见提供者脚本输出当前偏见内容；diag：唤起条件链诊断（--ccc <path> 指定 CCC，无参递归扫描 /home/yh 两层——覆盖任意实验 CCC 位置；逐条件输出 + 阻断点 + 修复建议）；diag-live：**进程内诊断**（v1.26.14——live 会话清单/标题/agent 定位/面板解析目标；排查\"面板检测不到实验 CCC\"）；doc：实验定义全文；check/status/guide：单项。**topPrompt（v1.26.17，轨迹焦点）**：CCC 定义 autotrajectory 时自己填写本轨迹核心焦点（顶层提示词），每次唤起最先注入——稳定焦点锚定防漂移（实验观察：无焦点多轮唤起轨迹腐化），与偏见内容（每轮随机探索）互补。实验是 CCC 的自选动作——dsp 只提供工具与知识，不自动安装任何东西。",
 		parameters: { action: {
 			type: "string",
 			enum: [...AUTO_TRAJECTORY_EXP_ACTIONS],

package/lib/invariant.d.ts

@@ -0,0 +1,29 @@
+/**
+ * invariant.ts — 包级不变量伴生（dsh-my-rsi creating-a-plugin 规范）
+ *
+ * 检查：dsh.plugin.json 的 contributes.tools 与代码实际注册的工具一致。
+ * 挂载时 plugin-local 会校验清单；本不变量让仓库内 `verify-package-invariants`
+ * 类门禁也可直接调用。
+ */
+export interface PluginManifest {
+    id: string;
+    version?: string;
+    main?: string;
+    description?: string;
+    engines?: {
+        dsh?: string;
+    };
+    contributes?: {
+        tools?: string[];
+        skills?: string[];
+    };
+}
+/** 读取插件清单；缺失/非法返回 null */
+export declare function readPluginManifest(manifestPath: string): PluginManifest | null;
+/**
+ * 校验清单声明的工具与代码注册的工具一致。
+ * 返回不一致项列表（空 = 通过）。
+ */
+export declare function verifyToolConsistency(manifestPath: string, registeredTools: readonly string[]): string[];
+/** 包级不变量：本插件注册的工具集合（与 dsh.plugin.json contributes.tools 一致） */
+export declare const REGISTERED_TOOLS: readonly ["cc_fs", "session", "acc_kit", "cc_git", "acc_msm", "eap", "neat", "cce", "handyman", "session_rebuild", "localstore", "skiff_admin"];

package/lib/json.d.ts

@@ -0,0 +1,9 @@
+/**
+ * json.ts — 本地 JsonValue 类型（与 DSH 的 JsonValue 同构）
+ *
+ * 纯层（fs-ops/session-ops）保持零 DSH 运行时依赖：仅用本地类型标注，
+ * 工具层（defineTool）要求 execute 返回 DSH JsonValue，二者结构等价。
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};

package/lib/kit-ops.d.ts

@@ -0,0 +1,23 @@
+/**
+ * kit-ops.ts — acc_kit 纯操作层（零 DSH 依赖）
+ *
+ * 行为对齐 osp（opencode-serenity-plugin/src/acc-kit.ts）——osp 是 ACC 工具 spec：
+ *   - health：{ccc, root, version, status: healthy|degraded, principles: {P1_rooted, P2_git_managed, P3_binary_permissions}}
+ *   - time：{now_iso, now_local, epoch_ms}
+ *   - wait：缺省 1s（正整数秒），返回 'waited Ns' 文本
+ * 平台适配：P3 在 osp 检查 opencode.json，DSH 无 opencode.json → 检查 DSH/opencode 配置路径
+ * （.opencode/serenity.json / .dsh/serenity.json 等，见 DEFAULT_SERENITY_CONFIG_PATHS）。
+ * CCC 缺失时返回 degraded 报告而非抛错（对齐 osp 未激活语义）。
+ * 保留 dsp 增强：accVersion/dshVersion 版本自省字段。
+ * wait 用纯 Node setTimeout——不依赖外部 sleep 可执行文件（Windows 无 GNU coreutils sleep）。
+ */
+import { loadSerenityConfig } from './ccc.js';
+import type { JsonValue } from './json.js';
+export type KitAction = 'health' | 'time' | 'wait';
+export declare const KIT_ACTIONS: readonly KitAction[];
+export interface KitArgs {
+    action: KitAction;
+    seconds?: number;
+}
+export declare function runKit(root: string | null, args: KitArgs): Promise<JsonValue>;
+export { loadSerenityConfig };

package/lib/localstore-ops.d.ts

@@ -0,0 +1,85 @@
+/**
+ * localstore-ops.ts — localstore 纯逻辑层（零 DSH 依赖，可独立单测）
+ *
+ * S134 重设计（v1.16.7）：存储从 ~/.serenity/ 迁到 **CCC 根根目录 localstore.json**
+ * （JSON 格式——方便 MSM 直接 read + JSON.parse 读取，零解析依赖）。
+ *
+ * git 提交策略（可靠机制 × 用户自由）：
+ *   - 配置：.opencode/serenity.json `localstore.gitTrack`: "allow"（可提交）| "deny"（禁提交）
+ *   - **缺省 deny（没配就是不提交）**；且 deny 的保证**不依赖 dsh 运行**——
+ *     写入时自动确保 .gitignore 含 localstore.json（物理保证：即使 dsh 不在、
+ *     用户手动 git commit 也不会误提交），cc_git 检查为第二道防线（拒绝 + 提示）
+ *   - allow：放行（文件可提交，用户自行管理 .gitignore）
+ *
+ * 存储结构（JSON 顶层分节）：
+ *   { "credentials": { "HOME_GITLAB_TOKEN": "xxx" }, "<config节>": { "<key>": "v" } }
+ *   credentials 为保留节（credential 命名空间，key 大写蛇形）；其余节归 config 命名空间
+ *   （path = section.key，如 handyman.models）。
+ */
+import type { JsonValue } from './json.js';
+/** 命名空间：credential（凭据）| config（配置） */
+export type LocalStoreScope = 'credential' | 'config';
+export declare const LOCALSTORE_SCOPES: readonly LocalStoreScope[];
+/** 存储文件名（CCC 根根目录） */
+export declare const LOCALSTORE_FILENAME = "localstore.json";
+/** 凭据保留节名（JSON 顶层） */
+export declare const CREDENTIALS_SECTION = "credentials";
+/** 凭据 key 规范：大写蛇形，如 HOME_GITLAB_TOKEN */
+export declare const CREDENTIAL_KEY_RE: RegExp;
+/** 配置节名规范：小写字母数字连字符 */
+export declare const CONFIG_SECTION_RE: RegExp;
+/** 配置 key 规范（节内）：小驼峰，如 defaultModel */
+export declare const CONFIG_KEY_RE: RegExp;
+/** git 提交策略 */
+export type GitTrack = 'allow' | 'deny';
+/** 存储文件绝对路径（CCC 根根目录） */
+export declare function localstorePath(root: string): string;
+/** git 策略：serenity.json localstore.gitTrack，缺省 deny（不提交） */
+export declare function readGitTrack(root: string, paths?: string[]): GitTrack;
+/** .gitignore 是否已覆盖 localstore 文件（非空非注释行含文件名即算） */
+export declare function isLocalstoreGitignored(root: string): boolean;
+/**
+ * 确保 .gitignore 含 localstore 文件（deny 时的物理保证，不依赖 dsh 运行）：
+ * 写入 localstore 时调用——deny（含缺省）且 .gitignore 未覆盖 → 自动追加一行。
+ * allow → 不写入（放行，文件可提交）。
+ */
+export declare function ensureLocalstoreGitignored(root: string): {
+    status: 'allow' | 'ignored' | 'appended';
+};
+/**
+ * cc_git 联动检查（第二道防线）：文件存在 && deny && .gitignore 未覆盖 → 不通过。
+ * 调用方（cc_git commit）据此拒绝提交；status 可输出 warning。
+ */
+export declare function checkLocalstoreGitCompliance(root: string): {
+    ok: boolean;
+    reason?: string;
+};
+/** 读取命名空间全部条目：credential → 扁平；config → 分节（剔除 credentials 保留节） */
+export declare function readStore(root: string, scope: LocalStoreScope): Record<string, string> | Record<string, Record<string, string>>;
+/** 校验凭据 key 合法（大写蛇形）；不合法抛错 */
+export declare function assertCredentialKey(key: string): void;
+/** 校验 config 路径（节.key）；不合法抛错 */
+export declare function assertConfigPath(path: string): {
+    section: string;
+    key: string;
+};
+/** 写入单个条目（自动建文件；deny 默认时同步确保 .gitignore 物理保证） */
+export declare function writeEntry(root: string, scope: LocalStoreScope, name: string, value: string): void;
+/** 删除单个条目（不存在返回 false）；空节自动移除 */
+export declare function unsetEntry(root: string, scope: LocalStoreScope, name: string): boolean;
+/** 读取单个条目值；不存在返回 null */
+export declare function getEntry(root: string, scope: LocalStoreScope, name: string): string | null;
+/** 列出 key（凭据只返回 key 名，不返回值） */
+export declare function listKeys(root: string, scope: LocalStoreScope): string[];
+/**
+ * doc 说明文本：输出存储位置/格式/key 规范/git 策略/读写方法。
+ * agent 据此可直接用 fs 工具（read/write）自己读写凭据/配置。
+ */
+export declare function docText(root: string): string;
+/** 运行 localstore 操作（纯逻辑；返回 JSON 值供工具 render） */
+export declare function runLocalStore(root: string, args: {
+    action: string;
+    name?: string;
+    value?: string;
+    scope?: string;
+}): JsonValue;

package/lib/msm-ops.d.ts

@@ -0,0 +1,78 @@
+/**
+ * msm-ops.ts — acc_msm 纯操作层（零 DSH 依赖）
+ *
+ * MSM（Mech & Semi-Mech）框架：list / exec / admin(register|deregister|check)。
+ * 复用 CCC 的 mech-registry.json（v1 或数组格式）。cwd 钉在 CCC 根。
+ */
+import type { JsonValue } from './json.js';
+export declare const MSM_TIMEOUT_MS = 600000;
+/** CCC 名：从 .serenity 首行解析（对齐 osp readSerenityCccName） */
+export declare function readCccName(root: string): string | null;
+export type MsmAction = 'list' | 'exec' | 'register' | 'deregister' | 'check' | 'guide' | 'ccc-config';
+export declare const MSM_ACTIONS: readonly MsmAction[];
+export declare const MSM_GUIDE = "MSM Development Manual (Mech & Semi-Mech framework)\n\n## What it is\nMSM = the executable-unit layer. Mech is pure TS with zero LLM reasoning; Semi-Mech is a TS framework + LLM decision points.\nMSM is ACC's deterministic executable-unit layer \u2014 all shell/exec operations go through MSM and cannot be bypassed.\n\n## Registering a new MSM (acc_msm register)\n1. Write the script under <skill>/scripts/ (runnable via tsx; must include a main() CLI guard with an import.meta.url check)\n2. acc_msm register <name> --skill <s> --path <script path relative to root> --category <mech|semi-mech> --description <desc>\n3. Auto-writes mech-registry.json (preserving the original format) + git commit (commits only the registry file)\n4. Validation: path must be inside root, script must exist, name must be globally unique\n\n## flag schema (v1)\nflags is a new-style object array for parameter validation and path-escape guarding:\n  [{\"name\":\"output\",\"type\":\"string\",\"description\":\"output path\"},\n   {\"name\":\"target\",\"type\":\"path\",\"description\":\"operation target (type:path enables in-root validation + symlink defense)\"},\n   {\"name\":\"force\",\"type\":\"boolean\",\"description\":\"force mode\",\"default\":false}]\n- {name, type} format \u2014 new style, type:\"path\" enables the path-escape guard\n- {flag, description} format \u2014 old style, CLI flag description string\n- On registration, flags are passed via acc_msm register --flags '<json>' (the tool currently parses the name style)\n\n## Script conventions\n- Top-of-file documentation: purpose / usage / exit codes\n- Exit codes: 0 success / 1 user / 2 system / 3 operator (per ACC protocol classification)\n- main() CLI guard (DC-M2): the script must start with\n    if (import.meta.url === `file://${process.argv[1]}`) { main() }\n  or an equivalent isMain / require.main === check \u2014 so vitest imports never trigger top-level code\n- A paired .test.ts or .spec.ts (DC-M1, vitest)\n- Business subprocess environment: SERENITY_ROOT / SERENITY_CCC / SERENITY_VERSION injected\n\n## Interaction & confirmation conventions (no blocking confirmation)\n- MSMs run in **user-less subprocesses** (spawn/execFile, 600s timeout) \u2014 **never** use\n  readline / prompt / process.stdin etc. to block waiting for user input (it would hang until killed by the timeout)\n- When a second confirmation is needed: **directly return the confirmation request** (list the operation to perform and its impact + how to retry with the confirmation flag),\n  returning a non-zero exit code (or an explicit hint)\n- After the agent confirms, **re-invoke the MSM with the confirmation flag** (e.g. --confirm / --yes / --force) to retry\n- Standard mode (two-phase):\n  1. First call: destructive/confirmation-requiring operation detected and no confirmation flag present \u2192 output the confirmation request (list operation/impact/rollback),\n     exit non-zero (e.g. 1 user), **perform no changes**\n  2. After the agent evaluates, re-invoke: with the confirmation flag \u2192 execute and output the result\n- Applies to: delete/overwrite/push/batch operations and other irreversible or wide-impact operations\n- Anti-example (forbidden): readline waiting for user input, process.stdin.on('data') blocking waits\n  (MSMs have no stdin interaction channel \u2014 they hang until the 600s timeout)\n\n## Quality checks (acc_msm check, DC-M1~M4)\nDC-M1 has .test.ts/.spec.ts; DC-M2 has a main() guard (function main( / isMain / require.main === / import.meta.url);\nDC-M3 bidirectional: scripts unregistered + registry references missing scripts; DC-M4 path-type flags marked type:\"path\"\n\n## Self-description (protocol flags, first argument only)\nacc_msm exec <name> --list        \u2014 list all MSMs\nacc_msm exec <name> --schema <n>   \u2014 view a specific MSM's parameter schema\nacc_msm exec <name> --format=json  \u2014 JSON output mode (remaining args passed through losslessly)\n";
+/** CCC 配置参考（对齐 osp ccc-config action） */
+export declare const CCC_CONFIG_REFERENCE = "\u2550\u2550\u2550 CCC Configuration Reference \u2550\u2550\u2550\n\nCCC-level features are configured in .opencode/serenity.json.\nBelow are all available configuration sections.\n\n\u2500\u2500 1. handyman.models \u2500\u2500\nhandyman\uFF08\u6742\u5DE5\uFF09\u5DE5\u5177\u53EF\u7528\u6A21\u578B\u767D\u540D\u5355\uFF08provider/model \u5217\u8868\uFF09\uFF1B\u672A\u914D\u7F6E\u65F6 handyman \u62A5\u9519\u8981\u6C42\u914D\u7F6E\u3002\n\u7F3A\u7701\u6A21\u578B = models[0]\uFF08\u53EF\u7528 handyman.defaultModel \u6307\u5B9A\uFF0C\u5FC5\u987B \u2208 models\uFF09\u3002\n\n  Config:\n    { \"handyman\": { \"models\": [\"provider/model-name\"] } }\n\n  Example:\n    { \"handyman\": { \"models\": [\"minimax-cn-coding-plan/MiniMax-M3\"], \"defaultModel\": \"minimax-cn-coding-plan/MiniMax-M3\", \"maxRounds\": 100, \"maxParallel\": 10 } }\n\n\u2500\u2500 2. sessionKeeper.threshold \u2500\u2500\nSESSION-KEEPER \u63D0\u9192\u673A\u5236\u7684\u79EF\u5206\u9608\u503C\uFF08\u975E headless \u4E3B agent\uFF09\u3002\n\u6309\u5DE5\u5177\u8C03\u7528\u52A0\u6743 + \u8017\u65F6\u8BA1\u5206\uFF1B\u8FBE\u5230\u9608\u503C\u6CE8\u5165\u63D0\u9192\uFF0C\u8981\u6C42\u6A21\u578B\u56DE\u590D ACK \u7801\u3002\n\n  Config:\n    { \"sessionKeeper\": { \"threshold\": 150 } }\n\n  \u8BA1\u5206\uFF1Awrite/edit = 3\uFF0Ctask = 10\uFF0Cread/grep/glob/msm \u7B49 = 1\uFF0C\u65F6\u95F4 = 1/\u5206\u949F\n  \u9ED8\u8BA4\uFF1A150\n\n\u2500\u2500 3. localstore.gitTrack \u2500\u2500\nlocalstore.json \u7684 git \u7B56\u7565\uFF1Aallow \u53EF\u63D0\u4EA4 / deny \u7981\u63D0\u4EA4\uFF08\u9ED8\u8BA4 deny\uFF09\u3002\ndeny \u65F6\u5199\u5165\u81EA\u52A8\u786E\u4FDD .gitignore \u542B\u8BE5\u6587\u4EF6\uFF08\u7269\u7406\u4FDD\u8BC1\uFF09\uFF0Ccc_git commit \u4F1A\u68C0\u67E5\u62D2\u7EDD\u3002\n\n  Config:\n    { \"localstore\": { \"gitTrack\": \"allow\" } }\n\n\u2500\u2500 4. hooks.autoRestoreSession \u2500\u2500\n\u4F1A\u8BDD\u81EA\u52A8\u6062\u590D\uFF08\u9ED8\u8BA4 true\uFF1B\u53D7 events \u95E8\u63A7\u2014\u2014\u4EC5\u6839\u4F1A\u8BDD + \u5DF2\u6709\u5BF9\u8BDD\u5386\u53F2\u624D\u6062\u590D\uFF09\u3002\n\n  Config:\n    { \"hooks\": { \"autoRestoreSession\": false } }\n\n\u2500\u2500 5. safeMode / blacklist \u2500\u2500\nsafe-mode \u7531 WebUI \u5F00\u5173\u63A7\u5236\uFF08\u5199 .serenity-safe-on \u6807\u8BB0\uFF09\uFF1B\u9ED1\u540D\u5355\u8DEF\u5F84\u53D7 guards seam \u62E6\u622A\u3002\n\n  Config:\n    { \"safeMode\": { \"blacklist\": [\".secrets/\"] } }\n";
+export interface MsmFlag {
+    name: string;
+    type?: string;
+    description?: string;
+    required?: boolean;
+    default?: unknown;
+}
+export interface MsmEntry {
+    name: string;
+    path: string;
+    skill?: string;
+    category?: string;
+    description?: string;
+    usage?: string;
+    flags?: MsmFlag[];
+}
+export interface MsmArgs {
+    action: MsmAction;
+    name?: string;
+    args?: string[];
+    skill?: string;
+    path?: string;
+    category?: string;
+    description?: string;
+    /** register: flags JSON 字符串（对齐 osp --flags 入参；如 '[{"name":"hook","type":"string",...}]'） */
+    flags?: string;
+    /** register: 自定义 usage（缺省 'acc_msm exec <name> [args...]'） */
+    usage?: string;
+}
+export declare function parseRegistry(raw: string): MsmEntry[];
+export declare function findRegistries(root: string): string[];
+export declare function loadMsmEntries(root: string): MsmEntry[];
+export declare function findEntry(root: string, name: string): MsmEntry | null;
+/** 扫描各 skill scripts/ 下的非测试脚本（DC-M3 正向基准，对齐 osp） */
+export declare function scanSkillScripts(root: string): string[];
+export declare function runMsm(root: string, args: MsmArgs): JsonValue;
+/** 解析并校验 exec 参数：返回可执行条目 + 业务参数（list/schema 协议 flag 已分流） */
+export interface PreparedExec {
+    entry: MsmEntry;
+    businessArgs: string[];
+    fmtJson: boolean;
+    /** 业务参数是否含 --help/-h（exit≠0 时不追加 TIP，对齐 osp） */
+    hasHelp: boolean;
+    /** 协议结果（--list / --schema）；非协议执行时为 undefined */
+    protocol?: {
+        list: {
+            name: string;
+            category: string | null;
+        }[];
+    } | {
+        schema: {
+            name: string;
+            path: string;
+            flags: {
+                name: string;
+                type: string | null;
+                description: string | null;
+            }[];
+        };
+    };
+}
+export declare function prepareExec(root: string, args: MsmArgs): PreparedExec;
+export declare function runMsmAsync(root: string, args: MsmArgs): Promise<JsonValue>;

package/lib/output-guard-seam.d.ts

@@ -0,0 +1,21 @@
+/**
+ * output-guard-seam.ts — 输出守卫拦截缝（v1.26.3，S142 用户需求）
+ *
+ * `agent/turn-stopping`（serial）时：取该 turn 最后 assistant 文本 → 敏感词表检测 →
+ * 命中 → `agent.steer(buildRebuke(hits))` 打回重生成（turn 不关闭，模型同轮重答）。
+ * 连续命中达 REBUKE_MAX_ROUNDS → 放弃打回（防死循环），输出保留 + 审计日志。
+ *
+ * 作用范围（v1.26.3 用户拍板）：**仅外部面**——skiff/ACP/问答页等对外输出会话
+ * （session id `skiff-`/`acp-`/`rebuild-` 前缀；v1.22.4 rebuild 新建会话同面）。
+ * **本地维护会话（普通 dsh 会话）不检测**——维护会话必然提及机制词
+ * （dsh-serenity-hooks/session_rebuild/mech-registry），打回会瘫痪自身工作。
+ */
+import type { Context } from 'cordis';
+/** 外部面会话判定（v1.26.3 用户拍板：仅外部面检测，本地维护会话豁免）：
+ *  skiff-（F4 问答）/ acp-（F4c 程序化）/ rebuild-（v1.22.4 重建会话）前缀 */
+export declare function isExternalFaceSession(sessionId: string | undefined): boolean;
+/**
+ * 注册输出守卫（index.ts apply 调用）：
+ * turn-stopping 时检测最终输出，命中敏感词 → steer 打回重生成（官方机制，零改 DSH）。
+ */
+export declare function registerOutputGuardHook(ctx: Context): void;