@shgroup/dsh-serenity-hooks 1.26.15 → 1.26.17

package/lib/session-ops.d.ts

@@ -0,0 +1,127 @@
+/**
+ * session-ops.ts — session 工具纯操作层（零 DSH 依赖，可独立单测）
+ *
+ * 行为对齐 osp（opencode-serenity-plugin/src/session/lib.ts）——osp 是 ACC 工具 spec：
+ *   - create：--desc / --issue 二选一（互斥、缺省报错）；issue 模式目录 YYYY-MM-DD--<issue>
+ *     （无 S###，sessionId=issue）；desc 模式 YYYY-MM-DD--S###--<desc>；goal 写入目标段；dry-run 预览
+ *   - close：需 name + confirm=true；标记 [x] 已完成+已关闭 + 进度记录"关闭"
+ *   - archive：name 缺省 → 批量归档（completed + ≥7 天 → 移动 _archived/）；单会话需 completed + grace
+ *   - list/show/health/qa/summary：文本输出格式与 osp 一致
+ * 保留 dsp S134 活跃会话机制（内存 Map + events 恢复，不落盘）——osp 同为内存 active-state。
+ */
+import type { JsonValue } from './json.js';
+export type SessionAction = 'list' | 'show' | 'create' | 'use' | 'close' | 'health' | 'qa' | 'archive' | 'summary' | 'hook-develop-guide';
+export declare const SESSION_ACTIONS: readonly SessionAction[];
+export declare function sessionsRoot(root: string): string;
+interface SessionStatus {
+    hasSessionMd: boolean;
+    completed: boolean;
+    completedCount: number;
+    pendingCount: number;
+    unresolvedCount: number;
+}
+export interface SessionEntry {
+    dirName: string;
+    path: string;
+    mtime: Date;
+    status: SessionStatus;
+}
+/**
+ * 根据 key 查找会话（对齐 osp findSession）：
+ * 精确目录名 → S### ID（允许 S31→031）→ 唯一模糊子串匹配（多个则报错）
+ */
+export declare function findSession(sessionsDir: string, key: string): SessionEntry | null;
+/** list 子命令（对齐 osp listSessions 文本格式 + active 标记） */
+export declare function listSessions(root: string, activeId?: string): string;
+/** show 子命令（对齐 osp showSession：`# dirName\n\n` + SESSION.md 内容） */
+export declare function showSession(root: string, key: string): string;
+export interface CreateSessionOptions {
+    root: string;
+    /** --desc 模式的描述（与 issue 互斥） */
+    desc?: string;
+    /** --issue 模式的工单号（与 desc 互斥） */
+    issue?: string;
+    goal?: string;
+    dryRun: boolean;
+}
+export interface CreateSessionResult {
+    message: string;
+    dirName: string;
+    sessionPath: string;
+    sessionId: string;
+}
+/** create 子命令（对齐 osp createSession：--desc/--issue 二选一 + dry-run + 长度限制） */
+/** 目录名脱敏（Windows 审计问题 10）：非法字符 → '-', 去尾点/空格, 保留名（CON/NUL 等）加前缀 */
+export declare function sanitizeDirName(s: string): string;
+export declare function createSession(opts: CreateSessionOptions): CreateSessionResult;
+/**
+ * 活动会话跟踪（S134 v1.16.14 内存化，对齐 osp active-state）：
+ * **不落盘**——活跃会话状态在内存 Map（key = scope = dsh 会话 id），避免落盘标记
+ * 文件累积与跨会话串台（落盘版 `.dsh/active-sessions/<scope>` 已被此方案取代）。
+ * 进程重启恢复：从**当前会话历史（events）**解析 `[SESSION CONTEXT]` 标记（use 时注入），
+ * 只扫自己会话——无全局扫描、无跨会话污染。
+ */
+export declare const DEFAULT_SESSION_SCOPE = "default";
+/** [SESSION CONTEXT] 恢复标记（use 时注入 events 历史；进程重启后从 events 解析） */
+export declare const SESSION_CONTEXT_MARKER = "[SESSION CONTEXT] Activated:";
+export interface ActiveSessionInfo {
+    sessionId: string;
+    dirName: string;
+    mdPath: string;
+}
+export declare function getActiveSessionInfo(scope: string): ActiveSessionInfo | null;
+export declare function getLastActiveSessionInfo(): ActiveSessionInfo | null;
+export declare function setActiveSessionInfo(scope: string, info: ActiveSessionInfo): void;
+export declare function clearActiveSessionInfo(scope: string): void;
+/** 重置内存活跃会话（测试用；进程重启即天然清空） */
+export declare function resetActiveSessionStore(): void;
+/** 当前 scope 的活跃会话 SESSION.md 绝对路径；无激活返回 null（读内存，不落盘） */
+export declare function readActiveSessionMd(_root: string, scope?: string): string | null;
+/**
+ * use 子命令：激活会话（写内存 Map）+ 返回对齐 osp 的输出文本
+ * （含 [SESSION CONTEXT] 标记 + todowrite 指令；标记随工具结果进 events 历史，
+ *  进程重启后从当前会话 events 解析恢复）。
+ */
+export declare function useSession(root: string, key: string, scope?: string): {
+    dir: string;
+    mdPath: string;
+    context: string;
+};
+/**
+ * close 子命令（对齐 osp closeSession）：需 name + confirm=true；
+ * 标记 SESSION.md 为 [x] 已完成 + [x] 已关闭 + 进度记录"关闭"；清除该会话的活跃状态。
+ */
+export declare function closeSession(root: string, key: string, confirm: boolean, scope?: string): string;
+/**
+ * 从会话历史（events）解析会话身份（进程重启恢复；只扫**当前会话**自己的历史——无跨会话串台）。
+ *
+ * v1.24.11 稳固化（S142 用户需求：重建后新会话必须准确知道从哪个 SESSION 恢复）：
+ * **路径规范行即可，不再要求 [SESSION CONTEXT] 标记**——`session use` 上下文与重建锚点
+ * （buildRebuildAnchor 的 `- Persistent trajectory — SESSION.md path: <rel>` 行）同格式，
+ * 因此**仅靠重建锚点的会话（从未显式 use）同样可恢复**。从**尾到头**扫描，最后一条
+ * 合法路径胜出（时间序最新）；会话目录名/ID 从路径本身派生（单一真相源，不猜）。
+ * 路径可为相对（重建锚点存 rel）——绝对化与存在性校验在调用方（知道 root）执行。
+ */
+export declare function parseSessionContextFromEvents(events: readonly unknown[]): ActiveSessionInfo | null;
+/** 从文本提取 SESSION.md 路径（use 上下文 / 重建锚点规范行通用；无匹配返回 null）。
+ *  同行已知尾注（如系统提示词 Session 块的 persistent-body 注释）剥除——规范行只取路径本体。 */
+export declare function extractSessionMdPathFromText(text: string): string | null;
+/**
+ * 约定回退（v1.24.11）：AGENT_SESSIONS 下最新修改的**未完成**会话的 SESSION.md。
+ * readAllSessions 已按「未完成优先 + mtime 降序」排序 → 首个未完成且含 SESSION.md 即最新活动。
+ * 只作最后手段（内存/events/锚点全缺时），保证重建锚点至少指向一个真实存在的轨迹。
+ */
+export declare function findLatestActiveSessionMd(root: string): string | null;
+/** health 子命令（对齐 osp healthCheck：stale/stalled/ghost/drift 四类检查，文本输出） */
+export declare function healthCheck(root: string): string;
+/** archive 子命令（对齐 osp archiveSessions：移动 _archived/；name 缺省批量） */
+export declare function archiveSessions(root: string, opts: {
+    name?: string;
+    dryRun: boolean;
+}): string;
+/** summary 子命令（对齐 osp sessionSummary 文本仪表盘） */
+export declare function summarize(root: string): string;
+/** 事实核对：SESSION.md 声明 vs 实际情况（结构/一致性/新鲜度/决策质量/产出物） */
+export declare function qaCheck(root: string, key: string): string;
+export type SessionInfo = SessionEntry;
+export type { JsonValue };

package/lib/settings-section.d.ts

@@ -0,0 +1,113 @@
+/**
+ * settings-section.ts — 简单配置注册（dsh 原生设置面板，v1.21 分层）
+ *
+ * 分层决策（S142）：**简单配置（开关/阈值）→ dsh 原生设置面板**；
+ * **复杂配置（账号列表）→ 宁静号高级面板**（localstore + /serenity/config）。
+ *
+ * 本模块承载简单配置层：`installSettingsSection(ctx, settingsNamespace('serenity-hooks'), schema, entry)`
+ * 注册 `serenity-hooks` namespace——三功能总开关 + F2 阈值。
+ *
+ * 运行时降级守卫（版本鲁棒性）：旧 RC（staging 架构）api-proxy 有
+ * `WEB_SETTINGS_NAMESPACES` 静态白名单，第三方 ns 会收到 settings-not-exposed
+ * ——client 面板读不到。新 RC（官方 master）已删除白名单（全量 describe）。
+ * 本模块不依赖白名单状态：register 总是执行（host 侧零成本）；
+ * **client 侧**（SettingsSection 组件）以 describe 结果为据——ns 不在描述列表
+ * 则显示降级提示（引导去宁静号面板），在则渲染 schema 表单。零配置自动适配。
+ */
+import type { Context } from 'cordis';
+import z from '@deepseek-ai/schemastery';
+/** 插件 Config 的简单配置片段（index.ts Config 组合；settings entry base） */
+export interface SimpleConfigFragment {
+    gateway?: {
+        enabled?: boolean;
+    };
+    rebuild?: {
+        enabled?: boolean;
+        thresholdRatio?: number;
+    };
+    naming?: {
+        enabled?: boolean;
+    };
+    /** F4 Skiff（实验性）：调试服务启停（人工） */
+    skiff?: {
+        enabled?: boolean;
+        debugPort?: number;
+    };
+    /** F4c ACP（实验性）：HTTP JSON-RPC 端点启停（人工） */
+    acp?: {
+        enabled?: boolean;
+        httpPort?: number;
+    };
+    /** F4d 建议问答页（实验性）：按认知容器暴露问答页供他人验证（全局开关；与 ACP 共用端口） */
+    publicAsk?: {
+        enabled?: boolean;
+    };
+}
+/** 简单配置命名空间（dsh 设置面板的 section id / settings.yaml section） */
+export declare const SERENITY_SETTINGS_NS = "serenity-hooks";
+/**
+ * 简单配置 schema（schemastery）：三功能总开关 + F2 阈值 + F4 Skiff 启停。
+ * 与 DSH settings 的 schema 语义一致（z.object 布尔/数字）。
+ */
+export interface SerenitySimpleSettings {
+    /** F1 双端口网关总开关 */
+    gatewayEnabled: boolean;
+    /** F2 超限重建总开关 */
+    rebuildEnabled: boolean;
+    /** F2 contextPressure 触发比例（0~1） */
+    rebuildThreshold: number;
+    /** F3 会话命名总开关 */
+    namingEnabled: boolean;
+    /** F4 Skiff 调试服务总开关（实验性；默认关——不随插件加载自动启动，人工开启） */
+    skiffEnabled: boolean;
+    /** F4 Skiff 调试端口（默认 3099，仅 127.0.0.1） */
+    skiffDebugPort: number;
+    /** F4c ACP HTTP JSON-RPC 端点总开关（实验性；默认关——人工开启） */
+    acpEnabled: boolean;
+    /** F4c ACP HTTP 端口（默认 3100，仅 127.0.0.1） */
+    acpHttpPort: number;
+    /** F4d 建议问答页总开关（实验性；默认关——按认知容器暴露问答页，key 认证） */
+    publicAskEnabled: boolean;
+}
+/** schemastery schema（与 DSH 各插件 Config 同款） */
+export declare const simpleSettingsSchema: z<Schemastery.ObjectS<{
+    gatewayEnabled: z<boolean, boolean>;
+    rebuildEnabled: z<boolean, boolean>;
+    rebuildThreshold: z<number, number>;
+    namingEnabled: z<boolean, boolean>;
+    skiffEnabled: z<boolean, boolean>;
+    skiffDebugPort: z<number, number>;
+    acpEnabled: z<boolean, boolean>;
+    acpHttpPort: z<number, number>;
+    publicAskEnabled: z<boolean, boolean>;
+}>, Schemastery.ObjectT<{
+    gatewayEnabled: z<boolean, boolean>;
+    rebuildEnabled: z<boolean, boolean>;
+    rebuildThreshold: z<number, number>;
+    namingEnabled: z<boolean, boolean>;
+    skiffEnabled: z<boolean, boolean>;
+    skiffDebugPort: z<number, number>;
+    acpEnabled: z<boolean, boolean>;
+    acpHttpPort: z<number, number>;
+    publicAskEnabled: z<boolean, boolean>;
+}>>;
+/** 从插件 Config 提取 entry 默认（settings base 层） */
+export declare function entryDefaults(config: SimpleConfigFragment): SerenitySimpleSettings;
+/** 进程级默认（无 settings 服务时的兜底） */
+export declare function defaultSimpleSettings(): SerenitySimpleSettings;
+/**
+ * 读取当前简单配置（settings 解析值；无 provider/未注册 → entry 默认）。
+ * 各功能（gateway/rebuild/naming）启动与运行时判断开关都经此函数。
+ */
+export declare function readSimpleSettings(): SerenitySimpleSettings;
+/**
+ * 测试注入钩子（生产零调用）：替换/恢复运行时源，便于单测各功能门控
+ * （registerSettingsSection 的 setSource 回调在 mock dsh-settings 时不会触发）。
+ */
+export declare function __setSimpleSourceForTest(source: (() => SerenitySimpleSettings) | null): void;
+/**
+ * 注册简单配置到 DSH settings（零改 DSH；settings.yaml 持久化 + 原生面板渲染）。
+ * 注：插件 Config（cordis.yml 组合层）作为 base；用户文档层叠加其上。
+ * 运行时读取简单配置统一经 `readSimpleSettings()`。
+ */
+export declare function registerSettingsSection(ctx: Context, config: SimpleConfigFragment): void;

package/lib/skiff-core.d.ts

@@ -0,0 +1,78 @@
+/**
+ * skiff-core.ts — Skiff 会话核心（F4，v1.25.0 实验性）
+ *
+ * Skiff agent = 标准 DSH agent（ctx.agents.create，跑 DSH agent-loop）：
+ * 一次提问（followup）→ 模型自主循环调用工具直到 turn 结束（idle）→
+ * 读 session.events 取 committed 答案 + 完整轨迹（与 dsh WebUI 同源数据）。
+ *
+ * 实验性质：仅当 Skiff 调试服务开启（设置面板人工开关）且 CCC 配置了角色时才创建
+ * agent；未启用时本模块零副作用（无监听、无 agent、无会话注册）。
+ */
+import type { Context } from 'cordis';
+import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent';
+import { type SkiffRoleConfig } from './skiff-role.js';
+/** 查 sessionId 的 Skiff 角色名（无 → null） */
+export declare function skiffRoleFor(sessionId: string): string | null;
+/** 查 sessionId 的会话绑定（role + ccc；无 → null）——v1.25.10 追问校验 */
+export declare function skiffSessionInfo(sessionId: string): {
+    role: string;
+    ccc: string;
+} | null;
+/** 查 sessionId 的活体 agent（进程内会话延续用；未注册/已清理 → undefined） */
+export declare function getSkiffAgent(sessionId: string): Agent | undefined;
+export declare function registerSkiffSession(sessionId: string, role: string, ccc: string, agent: Agent): void;
+export declare function unregisterSkiffSession(sessionId: string): void;
+/** 测试/调试：注册表快照（sessionId → {role} 兼容展示） */
+export declare function skiffSessionSnapshot(): ReadonlyMap<string, {
+    role: string;
+    ccc: string;
+}>;
+export interface SkiffAgentRef {
+    handle: AgentHandle;
+    agent: Agent;
+    sessionId: string;
+}
+/**
+ * 创建 Skiff agent：标准 DSH agent + cwd=CCC root + 角色模型 +
+ * standard preset（平台工具面）+ scoped 系统提示词（基础提示词 + CCC 定义段，全替换 ACC 默认注入）。
+ */
+export declare function createSkiffAgent(ctx: Context, root: string, roleName: string, role: SkiffRoleConfig, defaultModel?: string): Promise<SkiffAgentRef>;
+export interface SkiffTrajectoryEntry {
+    role: 'user' | 'assistant' | 'tool';
+    text: string;
+    /** assistant 的工具调用名（有则填） */
+    tool?: string;
+}
+export interface SkiffAskResult {
+    answer: string;
+    sessionId: string;
+    trajectory: SkiffTrajectoryEntry[];
+}
+/**
+ * 提问一轮：followup → 等 idle → 读答案 + 轨迹。
+ * @param eventsStart 轨迹起点：显式传 0 = 全量轨迹（会话追问时页面重绘完整时间线，
+ *   v1.25.10 用户拍板）；不传（undefined）= 本轮增量（followup 前 events 之后）
+ * @param options.includeTrajectory 是否计算轨迹（v1.26.10：**3100 对外只提供问答**——
+ *   公开问答页 / ACP JSON-RPC 不返回 trajectory，传 false 跳过计算；3099 调试页默认 true 保留）
+ */
+export declare function askSkiff(ctx: Context, agent: Agent, question: string, eventsStart?: number, options?: {
+    includeTrajectory?: boolean;
+}): Promise<SkiffAskResult>;
+/**
+ * Skiff 会话的轨迹纪律参与判定：非 skiff 会话恒 true（正常参与）；
+ * skiff 会话按角色 trajectory 子集（session/keeper/rebuild）决定；
+ * 注册表缺失（进程重启遗留等）→ 保守旁路（false，完全独立）。
+ */
+export declare function skiffTrajectoryEnabled(root: string, sessionId: string | undefined, key: 'session' | 'keeper' | 'rebuild'): boolean;
+export interface SkiffMsmGate {
+    /** 拒绝原因（有则拒绝执行） */
+    reject?: string;
+    /** list 显示白名单（msms）；仅 action==='list' 时有值 */
+    whitelist?: Set<string>;
+}
+/**
+ * acc_msm 的 Skiff 门控：非 skiff 会话恒放行；skiff 会话——
+ * exec 非白名单 MSM 拒绝（不列名单）、register/deregister 必拒、
+ * list 白名单过滤、check/guide/ccc-config 只读放行。
+ */
+export declare function skiffMsmGate(root: string, sessionId: string | undefined, action: string, name?: string): SkiffMsmGate;

package/lib/skiff-debug.d.ts

@@ -0,0 +1,86 @@
+/**
+ * skiff-debug.ts — Skiff 调试问答页（F4a'，v1.25.x 实验性）
+ *
+ * node:http 调试端口（默认关，仅监听 127.0.0.1；启停 = 人工——设置面板「Serenity」
+ * 页 Skiff 区块开关，不随插件加载自动启动）。
+ *
+ * - GET  /        → 问答 HTML 页（**CCC 选择器** + 角色下拉 + 输入框 + 答案区 + 轨迹区 + WebUI 链接）
+ * - POST /ask     → {ccc?, role, question} → 走会话核心（skiff-core）→ {answer, sessionId, trajectory}
+ *
+ * **多 CCC 手工切换（v1.25.4，S142 用户）**：dsh 管理多个 CCC 时，调试页顶部 CCC
+ * 下拉列出全部候选（live 会话 cwd 上溯 .serenity 去重 + 默认绑定 root 兜底），
+ * 切换后角色下拉联动（各 CCC 的 skiff.roles 实时读取），提问按所选 CCC 创建 agent。
+ *
+ * 与 ACP stdio 协议（F4c 后续）共用同一会话核心（createSkiffAgent + askSkiff），
+ * 协议层后加不返工。轨迹 = session.events 结构化返回（与 dsh WebUI 同源数据），
+ * 页面 JS 渲染成对话时间线；同时保留原生 WebUI 会话链接供完整交互。
+ *
+ * 实验性质：未开启时零资源占用（无监听、无 agent 创建）。
+ */
+import type { Context } from 'cordis';
+import { type SkiffTrajectoryEntry } from './skiff-core.js';
+export declare function skiffDebugActive(): boolean;
+export declare function skiffDebugPort(): number | null;
+/** 候选 CCC 条目（调试页 CCC 切换器数据） */
+export interface SkiffCccEntry {
+    /** CCC 根（绝对路径） */
+    root: string;
+    /** 目录名（展示用） */
+    name: string;
+    /** 该 CCC 的 skiff 角色名列表（实时读取） */
+    roles: string[];
+}
+/**
+ * 发现候选 CCC 列表（多 CCC 手工切换，v1.25.6）：
+ * ① **dsh 工作区注册表**（workspaceRegistry.list，持久化——所有工作目录即使无 live 会话；
+ *    S142 用户 2026-08-29：应直接拉 dsh 工作区，且只列具体 CCC）
+ * ② **sessionPersistence 兜底**（持久化会话 headers——必装配服务，覆盖所有历史会话工作目录；
+ *    用户实测 workspaceRegistry 拉取仍空时兜底）
+ * ③ live 会话兜底
+ * ④ 默认绑定 root 兜底（不在列表时放首位）
+ */
+export declare function discoverCccs(ctx: Context, defaultRoot: string): Promise<SkiffCccEntry[]>;
+/** 问答页 HTML：CCC 切换器 + 角色下拉 + 输入 + 答案区 + 轨迹区（JS 渲染）+ WebUI 链接 */
+export declare function skiffDebugPage(cccs: SkiffCccEntry[], defaultRoot: string, webPort: number): string;
+/**
+ * JSC (Safari/iOS) JSON.parse 快速路径正则兼容化（v1.26.9，S142 调研定稿）。
+ *
+ * 背景：WebKit bug 200190「JavaScriptCore's Regex can't match the content」——JSC 的
+ * JSON.parse 用**内部正则**预校验字符串；内容含**原始** `\u2028`（行分隔符）/`\u2029`
+ * （段分隔符）时正则无法匹配 → 对**合法 JSON** 也抛
+ * `SyntaxError: The string did not match the expected pattern`（sentry-javascript #2487 同源）。
+ * JSON.stringify **不转义** `\u2028`/`\u2029`/`\uFEFF`（它们都是合法 JSON 字符串字符）→
+ * 在 JSON **文本层**把它们替换为 `\uXXXX` 转义序列：JSON.parse 后语义完全一致（还原原字符），
+ * 且 JSC 正则看到的是常规 ASCII 转义（与 JSON.stringify 对控制字符的输出同形态，安全）。
+ *
+ * 3100 问答页客户端 `await res.json()`（acp-http.ts）与页面内嵌 JSON（skiff-debug/acp-http）
+ * 均需此兼容层——iOS Safari 用户实测"复杂回答"触发。
+ *
+ * @param jsonText JSON.stringify 的输出文本；原地等价替换，返回 JSC 安全文本
+ */
+export declare function jscSafeJsonText(jsonText: string): string;
+/**
+ * Markdown 渲染（v1.25.9，正经库 marked 服务端渲染——替代手写正则渲染器，S142 用户要求）：
+ * ① 提取 `<think>…</think>` 块（v1.26.8 状态机扫描，占位符 \u0001T<idx>\u0001）
+ * ② 正文与 think 内容**先 escapeHtml 再 marked.parse**（GFM + breaks）——markdown 语法不受
+ *    转义影响，原始 HTML 注入被消除（安全）；代码块内 `<` 显示为实体（可接受）
+ * ③ think 占位符：默认还原为 `<details class="think">` 折叠卡（🧠 思考过程，默认收起）；
+ *    **hideThink=true（v1.26.4，public 口）→ 直接移除**（思考过程对普通用户不展示）
+ * @param hideThink 为 true 时 `<think>` 内容完全不渲染（public 问答页体验）
+ */
+export declare function renderSkiffMarkdown(raw: string, hideThink?: boolean): string;
+/**
+ * 启动调试问答服务（单实例；重复启动幂等返回既有实例）。
+ *
+ * **CCC 绑定（v1.25.2 用户指出）**：服务绑定一个默认 CCC root（调用方 resolveSkiffRoot
+ * 解析：live 会话中**含 skiff.roles 的 CCC 优先**）；v1.25.4 起页面可**手工切换**到
+ * 其它候选 CCC（live 会话发现的全部 CCC）；角色配置**每次请求实时读取**（不缓存快照）。
+ *
+ * @param root 默认绑定的 CCC 根（首次加载选中；角色配置读取 + skiff agent cwd）
+ * @param port 调试端口（仅 127.0.0.1）
+ * @param webPort 主 WebUI 端口（WebUI 链接）
+ */
+export declare function startSkiffDebugServer(ctx: Context, root: string, port: number, webPort: number): Promise<void>;
+export declare function stopSkiffDebugServer(): void;
+/** 导出类型引用（测试断言轨迹结构） */
+export type { SkiffTrajectoryEntry };

package/lib/skiff-registry.d.ts

@@ -0,0 +1,25 @@
+/**
+ * skiff-registry.ts — Skiff 会话注册表（sessionId → {role, ccc}；零 DSH 依赖，可被任何 seams 安全 import）
+ *
+ * F4b 会话映射：Skiff agent 创建时注册（skiff-core），guards/seams 按 sessionId 查角色。
+ * 独立成模块的原因：guards.ts 等拦截缝需要查角色而不引入 skiff-core 的运行时依赖
+ * （skiff-core 依赖 @deepseek-ai/dsh-llm，测试/装配级联成本高）——注册表本身纯内存 Map。
+ *
+ * 值结构 v1.25.10 扩展：role（guards/seams 依赖，向后兼容）+ ccc（会话追问时
+ * 角色/容器绑定校验——同 sessionId 复用必须同 (role, ccc)，防串角色污染）。
+ *
+ * 生命周期：进程内存态；连接/页面关闭时 unregister；进程重启自然清空（skiff 会话不复存在）。
+ */
+/** 注册表值：会话绑定的角色 + CCC 根（追问延续校验用） */
+export interface SkiffSessionBinding {
+    role: string;
+    ccc: string;
+}
+/** 查 sessionId 的 Skiff 角色名（无 → null）——向后兼容（guards/seams 依赖） */
+export declare function skiffRoleFor(sessionId: string): string | null;
+/** 查 sessionId 的完整绑定（role + ccc；无 → null）——v1.25.10 会话追问校验 */
+export declare function skiffSessionInfo(sessionId: string): SkiffSessionBinding | null;
+export declare function registerSkiffSession(sessionId: string, role: string, ccc: string): void;
+export declare function unregisterSkiffSession(sessionId: string): void;
+/** 测试/调试：注册表快照（sessionId → {role, ccc}） */
+export declare function skiffSessionSnapshot(): ReadonlyMap<string, SkiffSessionBinding>;

package/lib/skiff-role.d.ts

@@ -0,0 +1,50 @@
+/**
+ * skiff-role.ts — Skiff（F4，v1.25.0 实验性）角色层纯逻辑（零 DSH 依赖，可独立单测）
+ *
+ * 概念（S142 用户拍板）：Skiff = 完整宁静号 trajectory（在宁静号内全知全能）的
+ * **任意子集**——CCC 通过角色配置定义：能力面（tools 非 MSM 工具白名单 + msms
+ * MSM 白名单，双白名单独立，白名单外全隐藏）+ 轨迹纪律面（trajectory 子集）+
+ * 系统提示词（CCC 完整定义，dsp 只给基础部分）。
+ *
+ * 实验性质：未配置任何角色 → Skiff 完全零影响（无监听、无 agent 创建、guard 无规则）。
+ */
+import { type SkiffRoleConfig } from './ccc.js';
+export type { SkiffRoleConfig };
+/** Skiff agent 会话 id 前缀（agents.create 生成；seams 旁路/白名单判定用） */
+export declare const SKIFF_SESSION_PREFIX = "skiff-";
+/** 判定 sessionId 是否为 Skiff 会话（仿 handyman- 前缀排除模式） */
+export declare function isSkiffSessionId(sessionId: string | undefined): boolean;
+/**
+ * 读取 CCC 的 Skiff 角色配置（.opencode/serenity.json skiff.roles）。
+ * @returns 名 → 角色配置 的 Map；未配置（无 skiff 段/空 roles）返回空 Map（Skiff 未启用）
+ */
+export declare function readSkiffRoles(root: string, paths?: string[]): Map<string, SkiffRoleConfig>;
+/** 某角色的轨迹纪律子集（缺省全 false = 完全独立） */
+export interface SkiffTrajectorySubset {
+    session: boolean;
+    keeper: boolean;
+    rebuild: boolean;
+}
+export declare function trajectorySubset(role: SkiffRoleConfig | undefined): SkiffTrajectorySubset;
+/** 角色可用工具面（白名单并集）：tools + acc_msm（msms 非空时作为 MSM 通道自动可用） */
+export declare function roleToolWhitelist(role: SkiffRoleConfig | undefined): Set<string>;
+/** 角色允许的 MSM 白名单（acc_msm exec 校验 / msm_list 过滤用；独立于 tools 白名单） */
+export declare function roleMsmWhitelist(role: SkiffRoleConfig | undefined): Set<string>;
+/**
+ * 解析角色的系统提示词全文（v1.25.10，S142 用户：超长提示词 JSON 内嵌不可读）：
+ * ① `systemPromptFile` 存在 → 读取文件内容（**推荐配置方法**；相对 CCC 根，
+ *    路径逃逸拒绝（resolveInside）+ BOM 剥除（readUtf8）+ 存在性校验）
+ * ② 否则 → 内嵌 `systemPrompt`（兼容旧配置）
+ * ③ 都无 → 空字符串
+ * 文件缺失/逃逸 → 抛错（调用方 catch 降级 + validate 报 issue）。
+ * 懒读取：readSkiffRoles 不读文件（guards/seams 每次工具调用查询的热路径零 IO），
+ * 仅在本函数（创建 agent / validate / list 时）读取。
+ */
+export declare function resolveRoleSystemPrompt(root: string, role: SkiffRoleConfig | undefined): string;
+/** 角色系统提示词来源（validate/list 展示用） */
+export declare function systemPromptSource(role: SkiffRoleConfig | undefined): 'file' | 'inline' | 'none';
+/**
+ * Skiff 基础提示词（dsp 只给这部分；CCC 的 systemPrompt 段由调用方拼接）：
+ * 身份 + 可用 MSM/工具清单 + 调用协议 + 边界声明。动态生成（清单来自角色白名单）。
+ */
+export declare function buildSkiffBasePrompt(roleName: string, role: SkiffRoleConfig | undefined): string;

package/lib/skills/opencode-scan.d.ts

@@ -0,0 +1,27 @@
+/**
+ * opencode-scan.ts — opencode skill 标准扫描（纯逻辑，零 DSH 依赖）
+ *
+ * 兼容 opencode 的 skill 标准：`.opencode/skills/<name>/SKILL.md`
+ * （frontmatter: name/description/whenToUse；结构含 references/、scripts/）。
+ */
+export interface OpencodeSkillMeta {
+    name: string;
+    description: string;
+    whenToUse?: string;
+}
+export interface OpencodeSkill {
+    name: string;
+    dir: string;
+    meta: OpencodeSkillMeta;
+    content: string;
+    path: string;
+}
+/** 解析 --- 分隔的 YAML frontmatter（只需 name/description/whenToUse） */
+export declare function parseFrontmatter(raw: string): {
+    meta: OpencodeSkillMeta;
+    content: string;
+};
+/** 扫描 CCC 的 .opencode/skills（一级目录 + SKILL.md 存在性） */
+export declare function listOpencodeSkillDirs(root: string): string[];
+/** 加载一个 opencode skill（frontmatter 解析 + 正文）；读失败（EPERM/占用等）返回 null，单目录容错 */
+export declare function loadOpencodeSkill(skillDir: string): OpencodeSkill | null;

package/lib/skills-discovery.d.ts

@@ -0,0 +1,25 @@
+/**
+ * skills-discovery.ts — CCC 入口 skill 自动发现（纯逻辑，零 DSH 依赖）
+ *
+ * 发现全部入口技能（原文全量，不截断）：
+ *   0. **`.serenity` 记号文件内容 = 顶层入口 skill 名**（CCC 记号文件的权威语义，
+ *      tiangong-serenity 的 .serenity 内容为 `tg-serenity`）—— 最高优先
+ *   1. `.dsh/entry-skill` 指针文件（内容 = skill 名）—— 兼容旧约定
+ *   2. `.opencode/skills/*-serenity/SKILL.md` —— 自动扫描该 CCC 的顶层入口
+ *      （home-serenity / tg-serenity / pangu-serenity …，命名模式 `*-serenity`）
+ *   3. `.dsh/skills/*-serenity/SKILL.md` —— 自动扫描 ACC/harness 入口（acc-serenity 等）
+ * 按名去重；顺序 = 记号文件 → 指针 → opencode 入口 → dsh 入口。
+ *
+ * 任何 CCC 都能自动注入其顶层入口 skill 全文（不硬编码名字）。
+ */
+export type EntrySkillSource = 'serenity-marker' | 'pointer' | 'opencode' | 'dsh';
+export interface EntrySkill {
+    name: string;
+    content: string;
+    source: EntrySkillSource;
+}
+/** 发现全部入口技能（原文全量，不截断） */
+export declare function findEntrySkills(root: string): EntrySkill[];
+/** 兼容旧接口：第一个入口（或 null） */
+export declare function findEntrySkill(root: string): EntrySkill | null;
+export declare function truncateContent(content: string, maxChars: number): string;

package/lib/status.d.ts

@@ -0,0 +1,38 @@
+/**
+ * status.ts — 状态与安全模式操作（纯逻辑，零 DSH 依赖，可独立单测）
+ *
+ * WebUI 停靠栏的数据源：ACC 版本 / CCC 根 / safe-mode 状态 / 黑名单 / keeper 阈值 / handyman 模型。
+ * setSafeMode 直接读写 .serenity-safe-on 标记（守卫实时读取，写即生效）。
+ */
+/**
+ * 读取已安装 DSH CLI 版本；读不到返回 null。
+ * 跨平台（Windows 审计问题 13）：Windows npm 全局装在 %APPDATA%\npm（非 ~/.npm-global）——
+ * 依次尝试 npm_config_prefix / APPDATA\npm / ~/.npm-global。
+ */
+export declare function readDshVersion(): string | null;
+export interface SerenityStatus {
+    root: string | null;
+    accVersion: string;
+    dshVersion: string | null;
+    nodeVersion: string;
+    safeModeOn: boolean;
+    /** 黑名单条目（string 或 {pattern, message}，对齐 osp） */
+    blacklist: {
+        pattern: string;
+        message?: string;
+    }[];
+    threshold: number | null;
+    handymanModel: string | null;
+    restrict: {
+        lastKey: string | null;
+        lastAttemptAt: string | null;
+        lastSuccess: boolean | null;
+        lastError: string | null;
+        activeKeys: string[];
+    };
+}
+export declare function getStatus(cwd: string, configPaths?: string[]): SerenityStatus;
+/** 切换安全模式（写/删标记文件）；返回实际生效状态 */
+export declare function setSafeMode(root: string, on: boolean): {
+    on: boolean;
+};

package/lib/tools/autotrajectory-exp.d.ts

@@ -0,0 +1,24 @@
+/**
+ * autotrajectory-exp.ts — 自主轨迹实验一站式管理工具（v1.26.12 实验提案，默认关）
+ *
+ * 定位：dsp **只提供工具与知识**，不向 CCC 自动安装任何东西（实验可能失败，不污染 CCC）——
+ * 实验是 CCC 的自选动作：agent 调本工具（doc/全报告）即懂实验，init/random/check 辅助，
+ * 实际执行（写配置/写偏见脚本/标记会话）由 CCC 自己决定、自己用现有工具完成。
+ *
+ * 实现：薄封装——exec 包内静态脚本（npm files 含 experiments/），脚本是单一真相源。
+ * 环境注入 SERENITY_ROOT（当前 CCC 根）供脚本定位；bun 优先（可直跑 TS）。
+ * diag-live：**进程内诊断**（v1.26.14 用户"排查访问不到"）——闭包捕获 ctx，
+ * 直接读 live 会话/标题/agent（脚本 diag 看不到运行时），输出实例级诊断报告。
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import type { Context } from 'cordis';
+/**
+ * 定位包内实验脚本（npm files 分发 experiments/autotrajectory/）。
+ * 布局差异：tsdown bundle 后 import.meta.url 指向 lib/index.js（lib → 包根 1 层）；
+ * vitest 源码直跑时指向 src/tools/x.ts（src/tools → 包根 2 层）——逐级上溯查找，
+ * 两种布局都稳（找到 experiments/autotrajectory/scripts/autotrajectory-exp.ts 即止）。
+ */
+export declare function findExpScript(startDir: string): string | null;
+export declare const AUTO_TRAJECTORY_EXP_ACTIONS: readonly ["all", "init", "random", "diag", "doc", "check", "status", "guide", "diag-live"];
+/** 创建 autotrajectory-exp 工具（闭包捕获 ctx → diag-live 进程内诊断；v1.26.14） */
+export declare function createAutoTrajectoryExpTool(ctx: Context): ReturnType<typeof defineTool>;

package/lib/tools/cc-fs.d.ts

@@ -0,0 +1,7 @@
+/**
+ * cc-fs.ts — cc_fs 真实 DSH 工具定义（defineTool）
+ *
+ * 进程内注册（取代 v0.1 的 bash spawn runner）：zod/schemastery 参数校验、
+ * 规范 JSON 输出、纯 render 投影。逻辑在 fs-ops.ts（可单测）。
+ */
+export declare const ccFsTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/tools/cce.d.ts

@@ -0,0 +1,9 @@
+/**
+ * cce.ts — CCE 认知连续性工程工具（渐进式披露，ACC 标准工具化）
+ *
+ * 内容：认知连续性工程（Cognitive Continuity Engineering）——在有限资源与
+ * 不可逆不确定性约束下，维持认知实体身份、可达性与演化能力的工程学科。
+ * 来源：home-serenity `.opencode/skills/cce/SKILL.md` + CCE 理论。
+ */
+export declare const CCE_CONTENT = "# CCE \u2014 Cognitive Continuity Engineering\n\n> **Cognitive Continuity Engineering is the engineering discipline of maintaining a cognitive entity's identity, accessibility, and capacity to evolve under the constraints of bounded resources and irreversible uncertainty.**\n> CCE does not optimize cognition. It preserves the conditions under which cognition can continue. \u2014 Persistence Engineering, not performance engineering\n\n## Core Propositions\n- **Continuity belongs to the container, not to any individual participant** \u2014 agents come and go, but the CCC's cognitive trajectory persists\n- **Organization must at minimum keep pace with accumulation** \u2014 otherwise operational cognitive entropy (H_op) grows unboundedly and accessibility is lost\n- **Reconstruction over preservation** \u2014 an artifact's value is determined by its ability to let future agents rebuild the original reasoning\n\n## Cognitive Container\nA bounded cognitive space in which cognition can accumulate, reorganize, and evolve. 5 defining properties:\n| Property | Function |\n|----------|----------|\n| Identity | Distinguishes this cognitive system from others |\n| Boundaries | Define what is inside/outside the cognitive space |\n| Persistent Memory | Retains accumulated cognition across time |\n| Operational Constraints | Define which operations are allowed inside the container |\n| Evolutionary History | Records the trajectory of cognitive change, making reconstruction possible |\n\n## Operational Cognitive Entropy (H_op)\nDoes not measure total entropy (not operational); it measures only the **excess cognitive cost** for agents to complete tasks inside the container:\n> H_op(C, t) = cost(task | C, t) \u2212 cost(task | ideal)\nContinuity condition: **H_op(C, t) \u2264 H_critical** \u2014 agents can still complete tasks at reasonable cost\n\n## Continuity Maintenance Condition\n> **\u0394H_org \u2265 \u0394H_in** \u2014 organization must at minimum keep pace with accumulation\n\n## Six-Phase Lifecycle\nExperience \u2192 Accumulation \u2192 Organization \u2192 Abstraction \u2192 Reconstruction \u2192 Evolution \u2192\uFF08loop\uFF09\n| Phase | Engineering Concern |\n|-------|---------------------|\n| Experience | Does input carry enough structure |\n| Accumulation | Is information stored losslessly |\n| Organization | Entropy management \u2014 \u0394H_org offsets \u0394H_in |\n| Abstraction | Is abstraction explicitly encoded |\n| Reconstruction | Can reasoning structure be recovered from artifacts |\n| Evolution | Does evolution stay coherent or introduce drift |\n\n## Relationship with EAP\nEAP answers \"how a piece of knowledge should be structured\" (explicitness E\u2191 / reconstructability R\u2193 / stability S\u2191);\nCCE answers \"how structured knowledge should keep evolving across time without losing coherence\". They complement each other: EAP is static quality, CCE is dynamic persistence.\n\n## Relationship with Serenity\nSerenity's session system, session tracking, and entropy management mechanisms (SQC quality loop) are all engineering implementations of CCE;\nthe behavioral constraints embedded in CCC system prompts come from CCE.";
+export declare const cceTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/tools/eap.d.ts

@@ -0,0 +1,7 @@
+/**
+ * eap.ts — EAP 认知质量框架工具（渐进式披露，ACC 标准工具化）
+ *
+ * 内嵌框架内容（自包含，不依赖已安装技能）；可选 section 参数聚焦某原则。
+ */
+export declare const EAP_CONTENT = "# EAP Cognitive Quality Framework (Explicit Abstraction Principle)\n\n> \"The functional value of a thought is proportional to its external reconstructability.\"\n\n## Three Variables\n| Variable | Meaning | How to improve |\n|----------|---------|----------------|\n| E\u2191 Explicitness | Degree to which variables/entities/relations are clearly defined | Define variables, state relationship direction & cardinality, draw boundaries |\n| R\u2193 Reconstructability | Cost of rebuilding the original reasoning later | Record decision rationale, context, constraints, alternatives |\n| S\u2191 Stability | Degree to which the same input repeatedly produces consistent output | Fix structures, protocolize, avoid relying on implicit context |\n\n## Pre-Output Self-Check Checklist\n- [ ] Variables/entities clearly defined (E\u2191)\n- [ ] Relationships state direction/cardinality (E\u2191)\n- [ ] Boundaries drawn \u2014 what is in scope / what is not (E\u2191)\n- [ ] No ambiguous words: \"handle\" \"optimize\" \"problem\" \u2192 be specific (E\u2191)\n- [ ] Key decisions record rationale and alternatives (R\u2193)\n- [ ] No level-skipping \u2014 align the upper layer before descending (R\u2193)\n- [ ] Structures can be regenerated repeatably (S\u2191)\n\n## Relationship with ACC\nACC (plugin/template) encodes structure as code (E\u2191); generating a CCC from ACC is deterministic (R\u2193); consistent across multiple CCCs (S\u2191).\nCCC (home-serenity etc.) encodes cognitive content as skills/SESSIONs/design docs. Use this checklist to self-check outputs.\n\n## Reference\nhttps://github.com/tellmewhattodo/theory-eap";
+export declare const eapTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/tools/git.d.ts

@@ -0,0 +1,4 @@
+/**
+ * git.ts — cc_git 真实 DSH 工具定义（defineTool）
+ */
+export declare const gitTool: import("@deepseek-ai/dsh-tools").ToolDefinition;