@shgroup/dsh-serenity-hooks 1.26.14 → 1.26.16

package/lib/seams/guards.d.ts

@@ -0,0 +1,72 @@
+/**
+ * guards.ts — 拦截缝：安全模式 + 路径守卫（P3 语义的机械层）
+ *
+ * 纯决策逻辑（decideGuard）与 DSH 注册（registerGuards）分离：
+ * 前者零 DSH 依赖可单测，后者把决策接到 tools/pre-execute 瀑布 + ctx.tools.guard 终局。
+ *
+ * 对应 opencode-serenity-plugin 的 tool.execute.before 路径守卫 + bash 开关 + 黑名单。
+ */
+import type { Context } from 'cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import { type BlacklistRule } from '../ccc.js';
+export interface GuardInput {
+    root: string;
+    toolName: string;
+    safeModeOn: boolean;
+    blacklist: BlacklistRule[];
+    /** 工具参数中可能携带的路径（write/edit 等）；无则 undefined */
+    pathArg?: string;
+    /** cc_fs 等复合工具的子命令 action（只读子命令不查黑名单） */
+    action?: string;
+    /** 当前 agent 的 dsh 会话 id（Skiff 角色白名单判定；非 skiff 会话不判定） */
+    skiffSessionId?: string;
+}
+/**
+ * 凭据文件硬名单（数据面守卫，v1.26.3，S142 用户：localstore.json 需要在 read 工具的黑名单里）：
+ * **任何工具**（含 read/grep/glob/cc_fs 只读子命令）命中这些相对 CCC 根的路径 → deny。
+ *
+ * 与 safeMode.blacklist（写黑名单，v1.18.5 决策只拦写）语义独立：
+ * - 黑名单 = 用户可配置的写保护（REPOSITORIES/ 等只读参考源不误伤读）
+ * - 凭据硬名单 = **结构性数据面边界**（不依赖 safe-mode 开关，凭据文件任何时候不可读）——
+ *   对齐 CCE Bounded Space + wardn "structural guarantee, not policy"：localstore.json
+ *   含 API keys/tokens/SSH 密码，即使 prompt 纪律失败也无值可吐（机械保证）。
+ */
+export declare const SENSITIVE_CREDENTIAL_FILES: Set<string>;
+/** 判定工具是否为读类（read/grep/glob + cc_fs 只读子命令）：凭据文件对读工具同样 deny */
+export declare function isReadTool(toolName: string, action?: string): boolean;
+/** 判定工具是否为写类：普通工具按名；cc_fs 复合工具按子命令 action */
+export declare function isWriteTool(toolName: string, action?: string): boolean;
+export interface GuardDecisionResult {
+    deny?: string;
+    kind: 'allow' | 'deny';
+}
+/**
+ * 安全模式 + 黑名单 + P3 路径守卫的纯决策。
+ * 对齐 opencode-serenity-plugin 标准：安全模式 = **bash 禁用** + 写入黑名单；
+ * write/edit 等工具仅受路径逃逸与黑名单约束（不整体禁用）。
+ * 优先级：safe-mode bash > 路径越界 > 黑名单命中。
+ */
+export declare function decideGuard(input: GuardInput): GuardDecisionResult;
+/** restrict 诊断状态（status API 暴露；排查 restrict 未生效问题） */
+export interface RestrictDiagnostics {
+    lastKey: string | null;
+    lastAttemptAt: string | null;
+    lastSuccess: boolean | null;
+    lastError: string | null;
+    activeKeys: string[];
+}
+export declare function getRestrictDiagnostics(): RestrictDiagnostics;
+/**
+ * 同步安全模式工具隐藏：标记存在 → agent.ctx.tools.restrict deny 隐藏写工具；
+ * 标记消失 → 解除。pre-step 每步调用 → 切换实时生效。
+ */
+export declare function syncSafeModeRestriction(agent: Agent, root: string): void;
+export interface GuardRegistration {
+    /** 配置路径；缺省用 DEFAULT_SERENITY_CONFIG_PATHS */
+    configPaths?: string[];
+}
+/**
+ * 注册守卫：tools/pre-execute 瀑布 + ctx.tools.guard 终局。
+ * 两者都从 CCC 根实时读取配置（无状态、无缓存）。
+ */
+export declare function registerGuards(ctx: Context, opts?: GuardRegistration): void;

package/lib/seams/keeper.d.ts

@@ -0,0 +1,61 @@
+/**
+ * keeper.ts — 拦截缝：session-keeper（DCP 提醒，post-execute observe-and-enrich）
+ *
+ * 照 dsh-external/tool-failure-guard 模式：先检测计分，`next()` 委托，
+ * 再把提醒折叠到返回决策的 additionalContexts（绝不 veto）。
+ *
+ * 计分（对齐 opencode-serenity-plugin session-keeper）：
+ *   write/edit=3, task=10, read/grep/glob/msm=1, 经过时间 +1 分/分钟
+ * 阈值：.opencode/serenity.json sessionKeeper.threshold（规范位置，.dsh 回退；缺省 150）
+ * 提醒要求模型回应 [SESSION-KEEPER-recorded-{code}] 确认（DCP 模式）。
+ */
+import type { Context } from 'cordis';
+export declare function scoreTool(toolName: string): number;
+export declare class KeeperTracker {
+    private threshold;
+    private now;
+    private score;
+    private lastTs;
+    private counter;
+    constructor(threshold: number, now?: () => number);
+    /** 记录一次工具调用 + 经过时间；返回是否应触发提醒 */
+    step(toolName: string): boolean;
+    /** 生成确认码并清零积分 */
+    ack(): string;
+    get currentScore(): number;
+}
+export declare function reminderText(code: string, score: number): string;
+/**
+ * F2 rebuild 提示（v1.21；v1.22.1 对齐"轨迹跟踪器"概念；v1.23.0 英化 + 载体关系；
+ * v1.23.3 行动指令化——用户反馈"一直在触发为啥没执行"：旧文案是状态播报式
+ * （"[TRAJECTORY] Context usage at N%..."），模型当成系统状态而非行动请求，可一直忽略。
+ * 新文案 = 明确的行动指令（ACT NOW + 何时执行 + 必须执行），对齐 steward ACK 协议风格。
+ *
+ * v1.24.12 沉淀协议（S142 用户需求）：rebuild 前若掌握值得沉淀的认知——修订 CCC 现有
+ * skill（eap 结构化）；若需新建 skill——**不自行创建**，写提案进 SESSION.md 供用户参考。
+ * 简短留自由度（不提"加载 eap 工具"，模型自知；只说修订 skill + 新建 skill 落 SESSION）。
+ *
+ * escalated=true（v1.23.3）：连续多轮超阈值仍未 rebuild → 升级强制语气
+ * （STOP and rebuild now，持续注入直到调用 session_rebuild）。
+ */
+export declare function rebuildReminderText(ratio: number, threshold: number, escalated?: boolean): string;
+/** 读取会话 contextPressure 投影（sessionProjections 可选服务；未装配返回 null） */
+export declare function readContextPressure(ctx: Context, session: unknown): {
+    projectedTokens: number;
+    contextWindow: number | undefined;
+} | null;
+export interface KeeperRegistration {
+    /** 缺省阈值（serenity.json sessionKeeper.threshold 优先，其次此值） */
+    defaultThreshold?: number;
+    /** CCC 配置相对路径 */
+    configPaths?: string[];
+}
+/** v1.23.3 重建提醒状态：agentId → 连续超阈值累计轮数（进程内存态） */
+interface RebuildReminderState {
+    /** 连续超阈值未 rebuild 的累计轮数（达阈值 → 升级强制提醒） */
+    consecutive: number;
+}
+/** 测试/调试：查看重建提醒状态 */
+export declare function rebuildReminderStateSnapshot(): ReadonlyMap<string, RebuildReminderState>;
+export declare function registerKeeper(ctx: Context, opts?: KeeperRegistration): void;
+export {};

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

@@ -0,0 +1,14 @@
+/**
+ * opencode-skills.ts — opencode skill 标准兼容 provider
+ *
+ * 通过 ctx.skills.registerProvider 把 CCC 的 `.opencode/skills/*`（opencode 标准
+ * skill：SKILL.md + frontmatter + references/ + scripts/）注册为 DSH 可加载技能。
+ * 按 agent 会话 cwd 解析 CCC 根 → 自动发现；resourceBase 指向 skill 目录，
+ * 使 references/scripts 相对引用可解析。
+ *
+ * rank = 250：低于 project-dsh（100）与 custom（300）之间——本地 .dsh/skills 优先。
+ */
+import type { Context } from 'cordis';
+export declare const OPENCODE_PROVIDER = "opencode-skills";
+export declare const OPENCODE_RANK = 250;
+export declare function registerOpencodeSkills(ctx: Context): void;

package/lib/seams/system-prompt.d.ts

@@ -0,0 +1,113 @@
+/**
+ * system-prompt.ts — 顶层入口 skill 全文 + ACC/CCE/Constraints/Session 系统提示词注入
+ *
+ * **完全对齐 opencode-serenity-plugin 的 system.transform 注入内容**（compacting.ts）：
+ * 结构（v1.19.8 精简，S142 重建视角 R↓）：
+ *   1. `=== Serenity ACC ===`        — 身份（ACC/CCC 模型 + 工具清单）
+ *   2. `=== Serenity Metaphor ===`   — 世界模型（三层隐喻域：船/航行/船员）
+ *   3. `=== Serenity Principles ===` — 信念/边界（认知容器本体论 + 操作边界，v1.19.8 合并原 Constraints）
+ *   4. `=== Serenity CCE ===`        — 时间约束（5 行为约束 + H_op，逐字对齐 osp）
+ *   5. `=== Serenity EAP ===`        — 质量（E↑ R↓ S↑ 自检）
+ *   6. 状态块（条件）                — Safe Mode / Localstore
+ *   7. SKILL.md 全文                 — 该 CCC 顶层入口 skill 全量原文（不截断）
+ *   8. `=== Serenity Session ===`    — 活跃会话（id + dirName + mdPath + todowrite 首位约定）
+ *
+ * 注册：**全局** ctx `systemPrompt.section`（对齐 plan-mode 官方惯例），text 回调按
+ * `context.agent` 的 cwd 动态解析 CCC 根 → 返回完整注入文本；非 CCC/无 agent 返回空。
+ * 任何会话（主 agent / subagent / 后台 agent）装配系统提示词时自动获得。
+ *
+ * order = -50：位于 harness 身份（-100）之后、部署 persona（0）之前。
+ */
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { Context } from 'cordis';
+/** 读取 persona 彩蛋配置（plugin 全局；未配置 → mode='' 彩蛋关闭） */
+export declare function readPersonaSettings(): {
+    mode: string;
+    overrideText: string;
+};
+/** 1) ACC 块：身份 + CCC 名/Root + 内置工具清单（工具名换本插件真实 11 工具） */
+export declare function accBlock(root: string): string;
+/** 2) CCE 块：逐字对齐 osp（CCE 5 行为约束 + H_op 操作熵） */
+export declare function cceBlock(): string;
+/**
+ * Principles 块（v1.19.8 合并，S142）：认知容器本体论（why）+ 操作边界（operational
+ * boundaries）。原独立 Principles 与 Constraints 合并——同属容器约束体系，先原则
+ * 后边界（从抽象到具体，重建视角 R↓）。**注意：Constraints 不再作为独立对齐块存在
+ * （spec 修订：同步 osp compacting.ts——Constraints 内容并入本块，工具名仍为平台真实名）。**
+ *
+ * v1.23.1 persona：`omitMsmPrinciples=true` 时剥离 MSM 原则段（彩蛋替换面）——
+ * 用户 persona 文本承接"指令遵循风格"，本体论/关系段/操作边界（安全硬约束）永远保留。
+ */
+export declare function principlesBlock(root: string, omitMsmPrinciples?: boolean): string;
+/**
+ * 彩蛋 persona 块（v1.23.1，S142 用户需求）：
+ * 用户配置的替换文本替代 EAP 块 + MSM 原则段（输出约束/指令遵循约束）。
+ * 独立标记头 `=== Serenity Persona ===`（幂等检测兼容）；装配位置 = EAP 原位。
+ * mode 空 = 彩蛋关闭 → 返回空串（装配层回退默认 EAP + 完整 Principles）。
+ */
+export declare function personaBlock(mode: string, overrideText: string): string;
+/**
+ * EAP 自检提示块（DSH 扩展，无 osp 对应——osp 无此块）。
+ * 每次输出前的机械自检清单，强化 EAP 表现（E↑ 显式/R↓ 可重建/S↑ 稳定）。
+ * 独立块而非塞进 CCE/Constraints：后两者受 osp-alignment 逐字节断言约束。
+ */
+export declare function eapBlock(): string;
+/**
+ * Metaphor 强化块（v1.19.6，S142）：宁静号宇宙隐喻域（船/海/罗盘/日志/船员）。
+ * 隐喻是记忆钩子——形象唤起约束，前述块保持规则精确。每条隐喻 = 一个不可违背的
+ * 物理事实 + 行为判据（verdict）。全英文（与 CCE/Constraints 一致）；独立块可
+ * 回退；无 osp 对应（dsp 扩展，不进对齐断言参照）。
+ */
+export declare function metaphorBlock(): string;
+/**
+ * 运行时状态块 1) safe-mode（S134 v1.16.12）：ON 时告知 agent。
+ * v1.19.8 结构重排（S142 用户设计思路）：语义（为什么——无人值守自由）→
+ * 机制（什么被禁用）→ 约束（不可做什么）。文案与实现逐项对应（guards.ts）：
+ * bash 禁用（restrict deny + decideGuard）、黑名单路径拦截、CCC 治理文件保护；
+ * write/edit 等其余工具保留（受路径逃逸/黑名单约束）。
+ */
+export declare function safeModeBlock(root: string): string;
+/**
+ * 运行时状态块 2) localstore git 策略（S134 v1.16.12）：localstore.json 存在时按 gitTrack
+ * 提示敏感行为约束。deny（缺省）= 本地私有不提交；allow = 进 git（个人私有仓）但敏感数据
+ * 只限于该文件内（不外泄到其他文件/对话/日志）。
+ */
+export declare function localstoreBlock(root: string): string;
+/** 4) SKILL.md 全文：该 CCC 顶层入口 skill 原文（对齐 osp：原文直推，无包裹头；仅过滤治理内容） */
+export declare function entrySkillSectionText(root: string): string;
+/**
+ * 5) Session 块：对齐 osp（活跃会话 + todowrite 首位约定）；scope = dsh 会话维度。
+ * **平台适配（v1.17.2）**：osp 的 todowrite 首项含 `priority: "low"`（opencode todo 支持），
+ * 但 DSH 平台 todowrite schema 无 priority（additionalProperties: false 拒绝）→ agent 照做报
+ * `todos[0].priority is not a declared property`。DSH 版去掉 priority 字段（其余逐字对齐 osp）。
+ */
+export declare function sessionBlock(root: string, scope?: string): string;
+/**
+ * 完整系统提示词注入文本（v1.19.8 结构精简，S142 重建视角 R↓）：
+ * 身份（ACC）→ 世界模型（Metaphor）→ 信念/边界（Principles）→ 时间约束（CCE）
+ * → 质量（EAP）→ 状态（SafeMode/Localstore）→ CCC 上下文（SKILL）→ 会话（Session）。
+ * 认知展开顺序：我是谁 → 我所在的世界 → 为什么 → 如何一致 → 产物标准 → 当前状态 → 上下文。
+ *
+ * v1.23.1 persona（彩蛋）：persona.mode 配置 → EAP 块替换为 Persona 块（输出约束），
+ * Principles 剥离 MSM 原则段（指令遵循约束）——用户文本承接两处风格；本体论/关系段/
+ * 操作边界（安全硬约束）永远保留。未配置 → 与 v1.23.0 逐字节一致（零影响）。
+ */
+export declare function serenitySystemPrompt(root: string, scope?: string): string;
+/**
+ * Code Mode 适配行：当前 scope 以 Code Mode 呈现工具时（run_code 可见），
+ * ACC 块按 native 语义指引"直接调用工具"会与"只有 run_code 可直接调用"的执行
+ * 塌缩冲突（模型直呼工具名 → UNKNOWN_TOOL，拒绝信息误导）。追加一行说明，
+ * 引导经 run_code 程序内 tools.* 调用。both 模式不塌缩，该行不误导（程序内
+ * 调用同样合法），故按 run_code 可见性（code|both）统一附加。
+ * @param ctx - 插件 ctx（读 tools 注册表）。
+ * @param scope - 装配 scope（agent）；无则按全局视图判断。
+ * @returns 适配行（含换行前缀）；非 code/both 返回空串。
+ */
+export declare function codeModeAdaptationLine(ctx: Context, scope?: unknown): string;
+/**
+ * 全局注册系统提示词 section（osp system.transform 的 DSH 等价）。
+ * text 回调按 context.agent 的 cwd 上溯 .serenity → 返回该 CCC 的完整注入文本；
+ * 非 CCC / 无 agent 返回空（不注入）。
+ */
+export declare function registerEntrySkillSectionGlobal(ctx: Context): void;
+export declare function registerEntrySkillSection(agent: Agent, root: string): boolean;

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;