@shgroup/dsh-serenity-hooks 1.26.14 → 1.26.16

package/dsh.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "dsh-serenity-hooks",
-  "version": "1.26.14",
+  "version": "1.26.16",
   "main": "lib/index.js",
   "description": "宁静号 ACC harness（Native Cordis 插件）：真实 DSH 工具 cc_fs/session/acc_msm/eap/neat/cce/handyman/session_rebuild/skiff_admin + 拦截缝机械约束（safe-mode/路径守卫）+ 高级设定面板（双端口网关/账号管理）+ Skiff 认知子集角色（实验性）。适配 DSH 公开版（0.1.0-rc，deepseek-ai/deepseek-harness）。",
   "engines": {

package/lib/acp-core.d.ts

@@ -0,0 +1,100 @@
+/**
+ * acp-core.ts — ACP 会话管理层（F4c，v1.26.0 实验性）
+ *
+ * **传输无关**：方法处理器（initialize/session/new/prompt/cancel/list/close/request_permission）
+ * 不依赖任何传输（stdio/HTTP/直调）——企业微信桥同进程直调处理器函数，
+ * acp-http 端点（外部程序化面）与未来 stdio 独立进程复用同一处理器。
+ *
+ * Skiff 映射（S142 用户拍板：指定 认知容器+角色+会话（可选）进行对话）：
+ *   - session/new { ccc, role, sessionId? } → createSkiffAgent / getSkiffAgent 复用
+ *     （无 sessionId → 新建；有 → 进程内延续——与 v1.25.10 调试页同语义）
+ *   - session/prompt → askSkiff(agent, question, 0)（全量轨迹）
+ *   - session/cancel → agent.interrupt（DSH 能力）
+ *   - session/close → unregisterSkiffSession（释放 agent + 注册表清理）
+ *   - session/request_permission → 恒 allow（G9：白名单即授权）
+ *
+ * 实验性质：仅当 ACP 服务装配（settings acpEnabled）且 CCC 配置了角色时才创建 agent；
+ * 未启用时本模块零副作用（无监听、无 agent）。
+ */
+import type { Context } from 'cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: string | number;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export interface JsonRpcNotification {
+    jsonrpc: '2.0';
+    method: string;
+    params?: Record<string, unknown>;
+}
+/** JSON-RPC 错误码（对齐标准） */
+export declare const RPC_ERROR: {
+    readonly PARSE: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL: -32603;
+};
+export interface AcpSessionHandle {
+    sessionId: string;
+    role: string;
+    ccc: string;
+    /** 会话是否可复用（进程内延续） */
+    continued: boolean;
+}
+/**
+ * ACP 会话管理器：持有 skiff agent 会话（与 skiff-core 注册表同源——
+ * 创建走 createSkiffAgent（自动注册），关闭走 unregisterSkiffSession）。
+ * 传输无关：HTTP 端点/企业微信桥/未来 stdio 都调 handle(method, params)。
+ */
+export declare class AcpServer {
+    private readonly ctx;
+    constructor(ctx: Context);
+    /** 实现级方法调度（返回 result 或抛 JSON-RPC 语义错误） */
+    handle(method: string, params: Record<string, unknown> | undefined): Promise<unknown>;
+    private initialize;
+    /**
+     * session/new：{ ccc, role, sessionId? } → 创建或延续 skiff 会话。
+     * 无 sessionId → createSkiffAgent（新会话，continued:false）；
+     * 有 → 进程内延续（getSkiffAgent 命中 + role/ccc 绑定校验；未命中 → 错误）。
+     */
+    private newSession;
+    private listSessions;
+    /**
+     * session/prompt：{ sessionId, question } → 答案（**v1.26.10：不返回 trajectory**——
+     * 3100 对外只提供问答，轨迹含工具结果等内部信息；3099 调试页另走 /ask 保留）
+     */
+    private prompt;
+    /** session/cancel：{ sessionId } → 中断当前 prompt（DSH interrupt） */
+    private cancel;
+    /** session/close：{ sessionId } → 释放 agent + 注册表清理（进程内） */
+    private closeSession;
+}
+/** 方法不存在错误（JSON-RPC -32601） */
+export declare class RpcMethodError extends Error {
+    constructor(message: string);
+}
+/** 参数错误（JSON-RPC -32602） */
+export declare class RpcInvalidParams extends Error {
+    constructor(message: string);
+}
+/**
+ * JSON-RPC 2.0 批处理（单帧）：解析请求/通知 → 调 AcpServer.handle → 响应。
+ * 传输无关：acp-http 端点 / 未来 stdio 共用。
+ * @returns 响应帧数组（请求有响应；通知无；解析失败 → 单错误响应）
+ */
+export declare function dispatchRpc(server: AcpServer, frame: unknown): Promise<JsonRpcResponse[]>;
+/** 断言 SessionId 类型（ACP 会话 id 即 skiff sessionId） */
+export type { SessionId };

package/lib/acp-http.d.ts

@@ -0,0 +1,29 @@
+/**
+ * acp-http.ts — ACP HTTP JSON-RPC + 建议问答页（F4c/F4d，v1.26.x 实验性）
+ *
+ * node:http 服务（默认关，仅监听 127.0.0.1；启停 = 人工——设置面板「Serenity」
+ * 页 ACP 区块开关 / 问答页开关，不随插件加载自动启动；仿 skiff 调试服务模式）。
+ *
+ * - POST /          → JSON-RPC 2.0 单帧/批处理（acpEnabled 门控；ACP 程序化面）
+ * - GET  /          → 容器列表页（publicAskEnabled 门控；v1.26.2：只列已开放容器）
+ * - GET  /c/<name>  → 单容器问答页（v1.26.2：URL 体现容器名，用户只输 key）
+ * - POST /c/<name>/ask → 该容器问答（key 校验 + allowed 白名单校验）
+ * - POST /ask       → 兼容旧形态 { key, ccc, ... }（key 校验 + allowed 校验）
+ *
+ * 与 skiff 调试页（人工测试面）共享同一会话核心（acp-core → skiff-core）；
+ * 企业微信桥（F4c-2）同进程直调 acp-core 处理器函数，不经本端点。
+ * stdio 形态（独立进程部署）后续复用同一 acp-core（官方 NDJSON 帧格式）。
+ *
+ * 实验性质：未开启时零资源占用（无监听、无 agent 创建）。
+ */
+import type { Context } from 'cordis';
+export declare function acpHttpActive(): boolean;
+export declare function acpHttpPort(): number | null;
+/**
+ * 启动 ACP HTTP JSON-RPC + 建议问答页服务（单实例；重复启动幂等返回既有实例）。
+ * @param ctx 插件上下文（AcpServer 内部经 skiff-core 创建 agent）
+ * @param port 监听端口（仅 127.0.0.1）
+ * @param defaultRoot 默认 CCC 根（问答页候选发现兜底；resolveSkiffRoot 传入）
+ */
+export declare function startAcpHttpServer(ctx: Context, port: number, defaultRoot?: string): Promise<void>;
+export declare function stopAcpHttpServer(): void;

package/lib/api.d.ts

@@ -0,0 +1,47 @@
+/**
+ * api.ts — HTTP 状态接口（WebUI 停靠栏数据源/开关通道 + 图片落盘）
+ *
+ * 路由：
+ *   GET  /serenity/status            ?workspace=<路径>  → 状态（root/accVersion/safeModeOn/...）
+ *   POST /serenity/status            { workspace, on }  → 切换安全模式（WebUI 专属头）
+ *   GET  /serenity/handymen          → handyman 运行状态（v1.24.0：loop → handyman）
+ *   POST /serenity/image-upload      { workspace?, mediaType, data(base64) } → 图片写 _tmp/images_from_user/（client 专属）
+ *
+ * 经 ctx.webServer（webserver 服务，公开版由 httpServer 改名）注册；客户端与服务器同源，调用无信任围栏问题。
+ */
+import type { Context } from 'cordis';
+/** 图片落盘目录（CCC 根相对；S142 图片自动识别基础设施——粘贴图片落盘供 agent 经 CCC vlm MSM 自主处理） */
+export declare const IMAGE_UPLOAD_DIR = "_tmp/images_from_user";
+export declare const IMAGE_MEDIA_TYPES: Set<string>;
+/** 文件落盘目录（CCC 根相对；v1.24.1 粘贴任意文件自动落盘——agent 经 CCC 既有 MSM（pdf-extract/archive-extract 等）自主处理） */
+export declare const FILE_UPLOAD_DIR = "_tmp/files_from_user";
+/** 拒绝的可执行/危险扩展名（安全边界：不落盘可执行文件，防 agent 被诱导执行） */
+export declare const BLOCKED_FILE_EXTS: Set<string>;
+/**
+ * 图片落盘核心逻辑（可测）：校验 mediaType 白名单 + base64 解码 + 大小上限 →
+ * 写 CCC 根 _tmp/images_from_user/<ts>-<rand>.<ext>，返回相对路径。
+ * 校验失败抛 Error（handler 转 400）。
+ */
+export declare function saveImageToTmp(root: string, mediaType: string, data: string): string;
+/**
+ * 文件名脱敏（路径逃逸 + 非法字符）：取 basename（去 / 与 \），剥离前导点/空，
+ * 非法字符 → '-',限长。返回空则 'file'。
+ */
+export declare function sanitizeFileName(name: string): string;
+/**
+ * 任意文件落盘核心逻辑（可测）：文件名校验 + 可执行扩展名拒绝 + base64 解码 +
+ * 大小上限（10MB）→ 写 CCC 根 _tmp/files_from_user/<ts>-<rand>-<safeName>，返回相对路径。
+ * 校验失败抛 Error（handler 转 400）。
+ */
+export declare function saveFileToTmp(root: string, fileName: string, data: string): string;
+export interface StatusApiRegistration {
+    configPaths?: string[];
+}
+/**
+ * 从请求参数解析 workspace：优先 sessionId → 会话 header.cwd；其次 workspace 参数；
+ * 无参 → 遍历 live sessions 找第一个 CCC 会话的 cwd（远程访问时 sessionId 可能缺失，
+ * 回退 process.cwd()=$HOME 会错误显示"未激活"——v1.22.2 修复）；最后进程 cwd。
+ * 纯逻辑（可单测）：resolveWorkspaceCore(sessionCwd, workspaceParam, listCwds)。
+ */
+export declare function resolveWorkspaceCore(sessionCwd: string | undefined, workspaceParam: string | undefined, listCwds: () => string[], fallback: string): string;
+export declare function registerStatusApi(ctx: Context, opts?: StatusApiRegistration): void;

package/lib/autotrajectory.d.ts

@@ -0,0 +1,186 @@
+/**
+ * autotrajectory.ts — 自主轨迹（Self-Sustaining Trajectory）验证机制（v1.26.12）
+ *
+ * 依据：serenity-acc-specs/docs/self-sustaining-trajectory-hypothesis.md（v0.1 实验提案；
+ * S142 2026-08-30 用户提出猜想 + 三项裁决：① 时钟驱动 ② 先验偏见自生+随机（随机充分引入）
+ * ③ 人类=反馈来源（不直接参与））。
+ *
+ * 形态（用户审核定稿 v0.5）：
+ *   · **前台运行**：时钟唤起 = 向活跃会话注入唤起消息（agent.steer，v1.22.5 自动继续同款
+ *     通道）→ 模型自动继续 → 用户全程可见、随时可介入（人类反馈天然并入——同会话）。
+ *   · **偏见内容提供者 = CCC 根目录下脚本**（用户拍板：不再让 CCC 注册 MSM；tool 直接运行脚本；
+ *     命名修正：它不是"随机脚本"，本质是**偏见内容提供者**——biasProvider）：
+ *     配置 biasProvider（相对 CCC 根，缺省 autotrajectory-bias.ts）——tool 直接运行取
+ *     stdout 作为偏见内容；脚本缺失 → **报错要求实现**（偏见内容归 CCC，实现 = 根目录放脚本）。
+ *   · **会话标志 = 目录名后缀 --auto**（用户拍板：后缀，验证用方便）：
+ *     AGENT_SESSIONS/<date>--<desc>--auto/ → 该轨迹为自主形态；无标志会话不受影响。
+ *   · **唤起窗口避开北京时间 8~18 点**（用户拍板：用量峰谷省钱）——avoidWakeHours 可覆盖。
+ *   · **默认关**：serenity.json autotrajectory.enabled=false → 定时器不启动，零资源占用。
+ *   · **零影响**：不修改任何现有工具 / seams / 外部面；新增独立模块 + ccc.ts 纯类型扩展。
+ */
+import type { Context } from 'cordis';
+import { type AutoTrajectorySettings } from './ccc.js';
+/** 偏见内容提供者脚本缺省名（CCC 根目录下；用户拍板：tool 直接运行，缺失报错要求实现） */
+export declare const DEFAULT_BIAS_PROVIDER = "autotrajectory-bias.ts";
+/** 自主轨迹会话目录后缀标志（用户拍板：后缀） */
+export declare const AUTO_DIR_SUFFIX = "--auto";
+/** 调度 tick 周期（10min——验证形态"一个就够"） */
+export declare const TICK_MS: number;
+/** SESSION.md 内「下一轮动机」段标记（自生偏见载体——轨迹预设自己的未来） */
+export declare const MOTIVATION_MARKER = "\u4E0B\u4E00\u8F6E\u52A8\u673A";
+/** 缺省避开的高峰时段（北京时间 [start, end) 不唤起——用量峰谷省钱） */
+export declare const DEFAULT_AVOID_HOURS: {
+    start: number;
+    end: number;
+};
+export declare function readAutoTrajectorySettings(root: string): AutoTrajectorySettings | null;
+/**
+ * 北京时间（UTC+8）当前小时——不依赖服务器时区（服务器可能 UTC/本地任意）。
+ */
+export declare function beijingHour(nowMs: number): number;
+/**
+ * 唤起窗口判定：北京时间 [avoidStart, avoidEnd) 内不唤起（缺省 8~18）。
+ * 单段避开（start<=end）：窗口 = [0,start) ∪ [end,24)；跨零点避开（start>end）：窗口 = [end,start)。
+ */
+export declare function inAllowedWakeWindow(nowMs: number, avoid?: {
+    start?: number;
+    end?: number;
+}): boolean;
+/** 标志位判定：SESSION.md 所在目录名以 --auto 结尾 → 自主轨迹形态 */
+export declare function isAutoTrajectorySession(mdPath: string): boolean;
+/**
+ * 目标会话定位：**必须配置 cfg.session**（S###/目录名）——CCC 日常有多条 trajectory 在跑，
+ * 绝不默认唤起（缺省最近活跃会误伤其他正在运行的轨迹；用户拍板：必须配置才生效）。
+ * 未配置 session 或未命中 → null（不唤起）。
+ */
+export declare function resolveTargetMd(root: string, cfg: AutoTrajectorySettings): string | null;
+/**
+ * 唤起条件（纯逻辑，可测）：enabled + 未在运行 + 目录标志 + mtime 超间隔 + 窗口允许。
+ */
+export declare function shouldWake(settings: AutoTrajectorySettings, mdPath: string | null, nowMs: number, running: boolean): boolean;
+/** 自生动机读取：SESSION.md「下一轮动机」段内容（到下一个二级标题或文件尾；无 → null） */
+export declare function readSelfGeneratedMotivation(mdPath: string): string | null;
+/**
+ * 偏见内容：直接运行 CCC 根目录下偏见提供者脚本（biasProvider，缺省 autotrajectory-bias.ts）→ stdout。
+ * 脚本缺失 → 返回 { text: null, error: 提示实现 }（唤起侧报错要求实现，不静默跳过）。
+ * 路径逃逸校验（resolveInside）；bun 优先，node 兜底；600s 超时。
+ */
+export declare function fetchBiasContent(root: string, providerRel: string): Promise<{
+    text: string | null;
+    error: string | null;
+}>;
+/** 唤起消息（三段式：身份锚定 / 先验偏见[自生动机+偏见内容] / 任务）——注入前台会话，用户可见 */
+export declare function buildWakeMessage(opts: {
+    sessionName: string;
+    mdPath: string;
+    intervalHours: number;
+    motivation: string | null;
+    biasContent: string | null;
+}): string;
+/**
+ * 执行一次唤起（时钟 tick 与面板「立即唤起」共用）：
+ * - force=false（时钟）：完整校验——enabled / 目标命中 / --auto 标志 / 窗口 / 间隔 / 偏见脚本
+ * - force=true（手动调试，用户在场）：跳过窗口与间隔，仍校验 enabled / 目标命中 / --auto / 偏见脚本
+ * 成功 → 注入前台会话（agent.steer，用户可见）；返回结果供调用方（tick 打日志 / 面板显示）。
+ */
+export interface WakeResult {
+    ok: boolean;
+    detail: string;
+}
+export declare function performAutoTrajectoryWake(ctx: Context, root: string, settings: AutoTrajectorySettings, opts?: {
+    force?: boolean;
+}): Promise<WakeResult>;
+/**
+ * 装配（index.ts apply 调用）。时钟唤起（v1.26.14 修复——用户"手动唤起正常，时钟唤起不工作"）：
+ *
+ * 根因：旧实现启动时一次性 `resolveAutoTrajectoryRoot(ctx)`——web 进程启动时 live 会话
+ * 往往为空（用户尚未打开实验 CCC 会话）→ root=null → settings=null → **定时器根本不启动**；
+ * 手动唤起走 HTTP 端点（点击时重新解析 root）→ 正常。
+ *
+ * 修复：
+ * ① **动态解析**：每次 tick 重新解析 root + settings（不绑定启动时值）——live 会话变化即跟上；
+ * ② **事件驱动启动**：监听 `session/created`（live 会话出现）→ 启动定时器（进程启动时若
+ *    已有实验 CCC 会话则立即启动）；
+ * ③ **优先实验 CCC**：resolveAutoTrajectoryCcc（配置了 autotrajectory 的 live CCC）优先于
+ *    进程 cwd/任一 live（多 CCC 同实例时时钟唤起绑定实验 CCC，而非当前维护会话 CCC）。
+ *
+ * 零资源占用语义保留：未配置/未启用 → tick 内直接 return（定时器存在但每 10min 一次空检查，
+ * unref 不阻塞进程退出）。
+ */
+export declare function registerAutoTrajectory(ctx: Context): void;
+/**
+ * 面板状态（GET /serenity/autotrajectory 数据源；纯逻辑，可单测）——
+ * WebUI 设置面板「自主轨迹」只读区块展示的完整状态：配置摘要 + 目标会话
+ * 命中/标志/空闲时长 + 当前窗口/可唤起判定（唤起逻辑同 registerAutoTrajectory）。
+ * 不运行偏见脚本（只报脚本是否就绪——运行验证走 autotrajectory-exp random）。
+ */
+export interface AutoTrajectoryStatus {
+    /** 是否配置了 autotrajectory 段（.opencode/serenity.json） */
+    configured: boolean;
+    /** 总开关（缺省 false——未开零资源占用） */
+    enabled: boolean;
+    /** 无人类活动 N 小时后自动唤起（缺省 12） */
+    intervalHours: number;
+    /** 偏见内容提供者脚本（相对 CCC 根；缺省 autotrajectory-bias.ts） */
+    biasProvider: string;
+    /** 目标会话（S###/目录名；未配置 = 不唤起） */
+    session: string | null;
+    /** 避开唤起的高峰时段（北京时间） */
+    avoidWakeHours: {
+        start: number;
+        end: number;
+    };
+    /** 目标会话状态（未配置/未命中 → null） */
+    target: {
+        /** 目录名（含 --auto 后缀时为自主形态） */
+        dirName: string;
+        /** 目录名是否带 --auto 标志 */
+        autoFlag: boolean;
+        /** 距上次轨迹活动（小时） */
+        idleHours: number;
+        /** 当前时刻是否满足唤起条件（标志+间隔+窗口，未运行中） */
+        wakeable: boolean;
+    } | null;
+    /** 当前北京时间小时 */
+    beijingHour: number;
+    /** 当前是否在唤起窗口内（避开高峰之外） */
+    windowAllowed: boolean;
+}
+export declare function getAutoTrajectoryStatus(root: string): AutoTrajectoryStatus;
+/** live 会话条目（诊断/面板解析用；标题从 events 读） */
+export interface LiveSessionEntry {
+    id: string;
+    cwd: string | null;
+    cccRoot: string | null;
+    title: string | null;
+}
+/** 遍历 live 会话（sessions.list()）+ 补标题（events session/title latest-wins）+ ccc 归属 */
+export declare function listLiveSessions(ctx: Context): LiveSessionEntry[];
+/**
+ * 面板解析：GET /serenity/autotrajectory 无 workspace 参数时——
+ * **优先「配置了 autotrajectory 的 live CCC」**（用户实验状态所在；v1.26.14 修复：
+ * 原 resolveWorkspace 解析到第一个 live 会话（如 home-serenity）→ 面板显示"未配置"，
+ * 用户实验 CCC（pangu）检测不到）。优先级：已启用 → 已配置（未启用）→ null。
+ */
+export declare function resolveAutoTrajectoryCcc(ctx: Context): string | null;
+/**
+ * 进程内诊断（autotrajectory-exp diag-live 数据源；用户"排查访问不到 pangu 写个 msm"）——
+ * 输出当前实例 live 会话清单（id/cwd/ccc/标题）+ 每个配置了 autotrajectory 的 CCC
+ * 状态（配置摘要/目标命中/可唤起）+ 目标 agent 定位结果。脚本 diag 看不到运行时，
+ * 本函数在插件进程内运行（能读 sessions/agents）。
+ */
+export interface DiagLiveReport {
+    processCwd: string;
+    processCcc: string | null;
+    liveSessions: LiveSessionEntry[];
+    autotrajectoryCccs: Array<{
+        root: string;
+        enabled: boolean;
+        session: string | null;
+        target: AutoTrajectoryStatus['target'];
+        agentResolved: boolean;
+        agentDiagnosis: string | null;
+    }>;
+    panelResolved: string | null;
+}
+export declare function diagLive(ctx: Context): DiagLiveReport;

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,154 @@
+/**
+ * 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;
+    /** **必填**：目标会话（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;