@shgroup/dsh-serenity-hooks 1.26.15 → 1.26.17

package/lib/output-guard.d.ts

@@ -0,0 +1,68 @@
+/**
+ * output-guard.ts — 最终输出敏感词检测 + 打回重生成（v1.26.3，S142 用户需求）
+ *
+ * 认知容器对外提供认知结果时，**支撑宁静号自身的凭据与机制**不应透露给用户。
+ * 用户拍板方案（讨论稿定稿）：不做工具结果 redaction（那是模型工作内存），
+ * 改为**卡最终输出**——`agent/turn-stopping`（serial）时取 turn 最后 assistant 文本，
+ * 命中敏感词表 → `agent.steer()` 打回重生成，直到合规或达上限。
+ *
+ * 敏感词表（有限，ACC 立场，用户确认"这样比较全面了"）：
+ *   ① 凭据词  — localstore.json credentials 条目名 + 值精确匹配（运行时读）
+ *   ② 机制词  — 内部结构静态词（插件名/配置路径/端口/内部实现词）
+ *   ③ MSM 词  — mech-registry.json 注册的工具名（用户补充：msm_list 里的工具名）
+ *   **不含** 公开概念（宁静号/Serenity/认知容器/EAP/CCE/Neat——正常交流词，误伤灾难）
+ *
+ * 机制依据（DSH 官方）：agent/turn-stopping 注释 "a listener that objects steers and
+ * the machine re-reads its inbox: fresh steering runs another step, none closes the
+ * turn"——steer 打回是官方支持的"重生成"通道（v1.22.5 rebuild 自动继续同款先例）。
+ */
+/** 敏感词分类（v1.26.11：打回消息按类给规避指引——裸词不够，模型要知道词是什么/怎么规避） */
+export type SensitiveCategory = 'credential' | 'mechanism' | 'port' | 'msm';
+/** 一次命中（词 + 分类） */
+export interface SensitiveHit {
+    word: string;
+    category: SensitiveCategory;
+}
+export interface SensitiveWordTable {
+    /** 精确匹配词（条目名/值/工具名——命中即敏感） */
+    exact: Set<string>;
+    /** 子串匹配词（机制词——命中即敏感） */
+    substring: string[];
+    /** v1.26.11：分类词表（打回消息按类给规避指引；exact/substring 为聚合视图） */
+    credentialWords: string[];
+    mechanismWords: string[];
+    portWords: string[];
+    msmWords: string[];
+    /** 归一化后的全部精确词（供审计展示） */
+    sources: {
+        exact: string[];
+        substring: string[];
+    };
+}
+/**
+ * 构建敏感词表（每次调用实时构建——词源文件小，开销可接受）：
+ *   ① localstore.json credentials：条目名（UPPER_SNAKE）+ 值（精确匹配）
+ *   ② 静态机制词 + 端口
+ *   ③ mech-registry 注册的 MSM 工具名（loadMsmEntries 全注册表去重）
+ * @param root CCC 根（localstore.json / mech-registry 所在）
+ */
+export declare function buildSensitiveTable(root: string): SensitiveWordTable;
+/**
+ * 检测文本中命中的敏感词（v1.26.11：返回带分类的命中——credential/mechanism/port/msm，
+ * 打回消息据此给语义化规避指引；未命中返回空数组）
+ */
+export declare function detectSensitive(text: string, table: SensitiveWordTable): SensitiveHit[];
+/**
+ * 打回消息（steer 内容）：**逐词告知命中词 + 分类规避指引**（v1.26.11 用户调整——
+ * v1.26.10 只列裸词（如 "3080"）模型仍不知道是什么/怎么规避；现在按类说明：
+ * "3080" → 内部服务端口，不要提及内部端口/地址/端点）。
+ * R↓ 安全性：命中词本就已在被拦截回复中进入会话（已暴露面），打回重复一次不扩大暴露；
+ * steer 是 plugin source 消息不回显给用户（3100 对外响应已不含 trajectory → 打回文本不达外部用户）。
+ */
+export declare function buildRebuke(hits: SensitiveHit[]): string;
+/** 连续打回上限（防死循环；达到后放弃打回，最终输出替换为合规占位 + 审计） */
+export declare const REBUKE_MAX_ROUNDS = 3;
+/** 打回状态（按 agent 会话跟踪连续命中轮数） */
+export declare const rebukeStates: Map<string, {
+    consecutive: number;
+}>;

package/lib/rebuild.d.ts

@@ -0,0 +1,118 @@
+/**
+ * rebuild.ts — 轨迹跟踪器（Trajectory Tracker）超限重建：session_rebuild
+ *
+ * 概念（S142 用户拍板命名，v1.22.1 语义修正；v1.22.4 定稿语义）：
+ *   **SESSION.md = 持久 agent（轨迹）**——身份/决策/进度/未解决问题的本体，
+ *   永远留在 AGENT_SESSIONS/ 原位，**不归档、不移动**。
+ *   **自身 dsh 会话 = 临时可重建（工作副本）**——上下文超阈值时**完全清空重来**，
+ *   身份从 SESSION.md 自动延续。
+ *
+ * v1.22.4 定稿语义（用户明确：**复用旧会话 + 完全清空重来**，不要新建会话）：
+ *   ① rebuild 工具执行时**只排队**（pending map：sessionId → 锚点文本），不立即改 surface
+ *   ② `agent/turn-stopping`（turn 结束前 serial 触发）时真正执行：
+ *      surface replace 全部节点 → 锚点 user/message（「继续 {SESSION 名} 的工作」）
+ *   ③ 同一会话 id 不变 → 同工作区天然满足、无新/旧会话之分、无需销毁/切换/归档
+ *
+ * 为何不在工具执行时立即 replace（v1.22.2 方案废弃）：
+ *   S141 实测崩溃——rebuild 工具在 turn 中途执行 surface replace，把**当前 turn
+ *   的 assistant tool-call 节点**也 shadow 掉；工具返回后 agent-loop append
+ *   tool/result（sourceEventSeqs 引用被 shadow 的 callSeq），deriveMessages 折叠出
+ *   孤儿 tool 消息 → LLM API 报 "Messages with role 'tool' must be a response to
+ *   a preceding message with 'tool_calls'"（INVALID_REQUEST）。
+ *   **延迟到 turn 结束清空**：届时当前 turn 所有 tool/result 已完整 append，replace
+ *   一并 shadow，无孤儿。
+ *
+ * v1.22.5 增强（S142 用户需求）：
+ *   ① **自动继续**：turn-stopping 执行 replace 后 `agent.steer()` 注入自动继续指令
+ *      （DSH 官方先例：hooks-claude-code Stop hook 在 turn-stopping 里 steer 强制
+ *      再执行一步）——next-step 队列非空 → turn 循环不 break → 模型自动读取
+ *      SESSION.md 继续工作，无需用户手工输入。
+ *   ② **保留 first-anchor**：锚点消息并入 DEFAULT_ANCHOR_MESSAGES 正文（ACC 身份/
+ *      EAP/协作协议），去掉 acknowledge 尾句（重建后直接干活，不重走确认轮）——
+ *      系统提示词层身份未丢（每轮注入），bootstrap 晋升状态不受影响（surface
+ *      replace 不改 events，promoted 保持完整工具目录）。
+ *
+ * 触发：LLM 主动调用（keeper 超阈值后提示 [TRAJECTORY]，不自动执行——防误清空）。
+ * 门控：仅 CCC 内 + 简单配置 rebuild.enabled。
+ */
+import type { Context } from 'cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { Message } from '@deepseek-ai/dsh-llm';
+/**
+ * 剥离 first-anchor 消息的 acknowledge 尾句（rebuild 锚点保留协议正文但不要求确认回复）。
+ */
+export declare function stripAckSuffix(text: string): string;
+/**
+ * 构建重建锚点消息（v1.22.4 定稿语义 + v1.22.5 保留 first-anchor 正文）：
+ * 「[TRAJECTORY-REBUILD] + first-anchor 协议正文（去 acknowledge 尾句）+ 继续 {SESSION 名} 的工作」。
+ * @param root - CCC 根
+ * @param sessionName - 当前 use 的宁静号 SESSION 名（如 S142）；无激活则通用指令
+ * @param activeMdPath - 持久轨迹 SESSION.md 绝对路径（保持原位）
+ * @param anchorMessages - first-anchor 协议消息序列（缺省 DEFAULT_ANCHOR_MESSAGES；可注入测试）
+ */
+export declare function buildRebuildAnchor(root: string, sessionName: string, activeMdPath: string, anchorMessages?: string[]): string;
+export interface RebuildResult {
+    /** 是否成功排队（turn 结束时执行清空重建） */
+    queued: boolean;
+    /** 锚点消息文本（将在 turn 结束时注入） */
+    anchor: string;
+    /** 宁静号 SESSION.md（持久轨迹，保持原位） */
+    sessionMdPath: string | null;
+}
+/**
+ * 稳固的 SESSION.md 定位（多层候选 + 存在性校验，**绝不输出虚假路径**）：
+ * ① 内存活跃会话（本会话显式 use 过）→ ② events 恢复（use 标记 + 重建锚点规范行，进程重启后）
+ * → ③ surface 首条锚点（events 异常时兜底）→ ④ AGENT_SESSIONS 约定回退（最新未完成活动目录）。
+ * 每候选 resolve 后 existsSync 校验（相对路径按 root 解析）；全部失败返回 null → 调用方报错引导。
+ */
+export declare function resolveSessionMdPath(root: string, scope: string, session: Session): string | null;
+interface PendingRebuild {
+    /** 锚点消息文本 */
+    anchor: string;
+    /** 排队时间（防陈旧队列误清空——超时丢弃） */
+    queuedAt: number;
+}
+/** 测试/调试：查看 pending 队列内容 */
+export declare function pendingRebuildSnapshot(): ReadonlyMap<string, PendingRebuild>;
+/**
+ * 排队一次重建（v1.22.4 定稿语义第一步）：
+ * ① 门控校验（rebuild.enabled + 会话定位）
+ * ② 构建锚点（激活会话名 + 持久轨迹路径）
+ * ③ 写入 pending 队列——**不立即改 surface**（等 turn-stopping 执行）
+ * @returns 排队结果；rebuild.enabled=false 或非 CCC 抛错
+ */
+export declare function queueRebuild(ctx: Context, opts: {
+    root: string;
+    note?: string;
+    agentCwd: string;
+    dshSessionId: string;
+}): Promise<RebuildResult>;
+/**
+ * 执行真正的 surface replace（v1.22.4 定稿语义第二步，turn-stopping 时调用）：
+ * 当前 turn 已完整结束（所有 tool/result 已 append）→ 全部节点替换为锚点消息。
+ * 同一会话 id 原地重建——同工作区天然满足，无新/旧会话之分。
+ *
+ * **shadow-price 协议（v1.23.5 修复，S142 用户问询）**：DSH token-meter 的
+ * `foldSurfaceProjection` 对 surface `replace` 要求**紧邻其前的 metering 事件**
+ * （`compaction/summary` 或 `compaction/prune`）声明被替换范围的启发式 token 价，
+ * 否则 claim 缺失 → `deltaTokens=0` → `contextBreakdown.messageTokens` 永不扣减
+ * → UI「对话消息」虚高累计、往复 rebuild 计量爆炸（用户截图实证：总 15% 但
+ * 对话消息 ~1M）。官方先例 = `compaction-tool-result-pruner`（append
+ * `compaction/prune` → 紧接 replace）。此处同款：先 append `compaction/prune`
+ * （定价全部被替换节点，经 ctx.tokenMeter.estimateMessage 逐节点累加），再
+ * append 锚点 replace——meter 不可用时退化（无 claim，仅计量漂移，会话功能不受影响）。
+ *
+ * @returns 是否执行了 replace（false = 无 pending 或 surface 空）
+ */
+export declare function performRebuild(session: Session, pending: PendingRebuild, meter?: {
+    estimateMessage(message: Message): number;
+}): boolean;
+/**
+ * 注册 turn-stopping 钩子（index.ts apply 调用）：
+ * agent 每轮 turn 结束前（serial）检查 pending 队列——有该会话的重建请求 → 执行清空
+ * 并 **steer 自动继续**（v1.22.5：next-step 非空 → turn 不 break → 模型自动读取
+ * SESSION.md 继续，无需用户手工输入；DSH 官方先例 hooks-claude-code Stop hook）。
+ * 陈旧队列（超 TTL）丢弃防误清空；无 pending 零开销。
+ */
+export declare function registerRebuildTurnHook(ctx: Context): void;
+export {};

package/lib/seams/bootstrap.d.ts

@@ -0,0 +1,83 @@
+/**
+ * bootstrap.ts — Anchored Standard 两阶段工具目录（S137）
+ *
+ * 移植自 xiaobright/dsh-anchored-standard（preset/tool-bootstrap.mjs + compaction-epoch.mjs）：
+ * 首请求暴露最小工具集（锚定轨迹——V4 Pro 强依赖 API 可见工具目录选轨迹），
+ * 会话出现首次持久晋升信号（tool/call 或 assistant/message，先到者为准）后开放完整工具。
+ *
+ * 严格对齐 anchored 语义：
+ *  - 阶段从持久 session events 推导（resume/reload 不丢状态）
+ *  - epoch 感知：compaction/end 后回落受控阶段（bootstrap 集 + compactionTools），
+ *    需新的晋升信号才重新晋升（压缩后首请求 = "第二次首请求"）
+ *  - 子 agent（delegationDepth > 0）恒为 promoted（完整目录）
+ *  - bootstrap 阶段剥离自动注入上下文（suppressedContextSources，默认
+ *    skill-catalog + agent-instructions——即 Standard 比 Minimal 多出的两类注入）
+ *  - 降级：过滤器出错绝不吞上下文（pre-step 保留全部）/ 工具缺失降级完整目录 + 一次性告警
+ *
+ * 协议固有（用户原则 2026-08-24，S142）：first-anchor 属 ACC 协议层——任何 CCC
+ * 在抽象层都是宁静号/ACC，机制与内容均不可配置（零配置面）。旧版 serenity.json
+ * bootstrap 段（S137 引入的调参入口）已移除，遗留字段静默忽略。
+ */
+import type { Context } from 'cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+export interface BootstrapSettings {
+    /** 首请求（bootstrap 阶段）工具集（缺省 dsp 核心；zeroTools 时忽略——0 工具） */
+    bootstrapTools: string[];
+    /** 晋升信号类型集合 */
+    promoteEvents: Set<'tool/call' | 'assistant/message'>;
+    /** 晋升所需信号数（boundary 后累计；多轮锚定时 = 锚定轮数） */
+    requiredSignals: number;
+    /** bootstrap 阶段剥离的注入源 */
+    suppressedSources: Set<string>;
+    /** compaction 后（重新晋升前）额外保留的工具集 */
+    compactionTools: string[];
+    /** 锚定消息序列（v4 两轮递进：按序 prepend 到 next-turn 队列，每条一轮 0 工具回复） */
+    anchorMessages: string[];
+    /** Zero-Anchored 变体：首请求 0 工具（晋升信号仅 assistant/message，对齐 zero-anchored-standard） */
+    zeroTools: boolean;
+}
+/** 默认首请求工具集：dsp 平台 Minimal 等价核心（anchored 是 bash+str_replace_editor） */
+export declare const DEFAULT_BOOTSTRAP_TOOLS: string[];
+/** 默认剥离的自动注入源（anchored 默认：可用技能目录提醒 + 工作区指令摘要） */
+export declare const DEFAULT_SUPPRESSED_SOURCES: string[];
+/** 默认 compaction 恢复工作集（anchored 默认 read/write/edit/glob/grep/todo_write/ask_user_question） */
+export declare const DEFAULT_COMPACTION_TOOLS: string[];
+/**
+ * 协议级锚定消息序列（用户确认固化，2026-08-24 S142）：任何 CCC 在抽象层都是
+ * 宁静号/ACC——首轮锚定话语统一，无 CCC 配置面。两轮递进：
+ *  ① ACC 身份 + EAP 原则 + we/us 人称 + 先锚定后行动
+ *  ② 协作协议 5 条 + acknowledge 要求（只回确认，不做事）
+ * 文本 = 原 home-serenity CCC 配置（anchorMessages），随零配置化固化进代码。
+ */
+export declare const DEFAULT_ANCHOR_MESSAGES: string[];
+export interface PromotionStatus {
+    /** 最后一次 compaction/end 的 seq（-1 = 未压缩过） */
+    boundary: number;
+    /** 边界后是否存在持久晋升信号 */
+    promoted: boolean;
+}
+export interface PromotionTracker {
+    status(agent: Agent | undefined): PromotionStatus;
+    observe(session: unknown, event: unknown): void;
+}
+/**
+ * 构建一个 epoch 感知晋升跟踪器（纯逻辑，可单测）。
+ * requiredSignals：晋升所需信号数（boundary 后累计；默认 1）。
+ * 多轮锚定（v4）：两轮递进锚定时 requiredSignals = 锚定轮数——
+ * 每条锚定回复（assistant/message）计一次，最后一条回复后晋升。
+ *
+ * maxRoundsFallback：**轮次兜底**（v1.19.3 修复 responses API 兼容）。
+ * 某些模型/协议（如 opencode-go-responses）的会话可能不产生标准
+ * `assistant/message` 晋升信号 → 永不晋升 → bootstrap 阶段工具被裁空
+ * （zeroTools 首请求 0 工具，ACC 工具不可见）。兜底：无论晋升信号是否
+ * 到达，观察到的模型 step 数（`step/start` 事件计数，平台稳定事件，
+ * responses/completions 都触发，独立于 promoteEvents）达到 maxRoundsFallback
+ * 即强制 promoted（开放完整工具）。正常模型锚定轮数（requiredSignals）
+ * 通常 ≤ 2 < 默认兜底 3，不受影响。
+ */
+export declare function createEpochPromotion(promoteEvents: Set<'tool/call' | 'assistant/message'>, requiredSignals?: number, maxRoundsFallback?: number): PromotionTracker;
+/** 协议固有 bootstrap 设置：zeroTools=true（首请求 0 工具纯文字锚定轮）、
+ *  晋升信号仅 assistant/message（对齐 zero-anchored-standard）、
+ *  requiredSignals = 锚定轮数（2 条消息 → 2 条回复后晋升）。无参——零配置面。 */
+export declare function resolveBootstrapSettings(): BootstrapSettings;
+export declare function registerBootstrap(ctx: Context): void;

package/lib/seams/compact.d.ts

@@ -0,0 +1,31 @@
+/**
+ * compact.ts — 拦截缝：压缩保留（P2，osp session.compacting 的 DSH 等价）
+ *
+ * 问题（历史）：ACC 身份消息是早期注入的历史消息；上下文压缩会折叠它们，
+ * 模型上下文丢失 ACC 身份 → 后续行为偏离 CCC 约束。
+ *
+ * 现状（S134 去重）：完整身份由**系统提示词层**（systemPrompt.section）每轮自动注入，
+ * 不在对话历史里、不随压缩折叠 → 压缩无需恢复完整身份。压缩重注入改为
+ * 简短身份锚点（[ACC] 头，与 context.ts 共用 accMessage）——压缩后对话流
+ * 仍保留可追溯的身份标记（R↓），token 开销极小。
+ *
+ * session → agent 关联：session.id 即 agent id（goal-session 用 ctx.agents.get(session.id)）。
+ *
+ * 时机依据（DSH 公开版 compaction 类型，事件名 compact/* → compaction/*）：
+ * - `compaction/start`: { compactionId, sourceCommandId?, turn: number | null } — 压缩开始（log-only，持锁）
+ * - `compaction/summary`: { compactionId, summary, ... } — 摘要完成（log-only）
+ * - `compaction/end`: { compactionId, sourceCommandId?, turn, error? } — 压缩结束，error 记录失败
+ * 成功判定：compaction/end 无 error。
+ */
+import type { Context } from 'cordis';
+export interface CompactRegistration {
+    /** CCC 配置相对路径；缺省用 DEFAULT_SERENITY_CONFIG_PATHS */
+    configPaths?: string[];
+    /** 入口 skill 内容注入上限（与 context.ts 对齐） */
+    entrySkillMaxChars?: number;
+}
+/**
+ * 注册压缩保留：compact/end（成功）后重注入 ACC 身份。
+ * 仅当 agent 工作目录在 CCC 内时生效（激活门控）。
+ */
+export declare function registerCompactRetention(ctx: Context, opts?: CompactRegistration): void;

package/lib/seams/context.d.ts

@@ -0,0 +1,48 @@
+/**
+ * context.ts — 拦截缝：ACC 上下文注入（agent/session-start + agent/prompt-submit）
+ *
+ * 对应 opencode-serenity-plugin 的 system.transform（ACC 身份/约束注入）+ Phase 2 访谈提示。
+ *
+ * 设计：
+ * - session-start（emit）：CCC 内新会话一次性播种 ACC 身份（agent.inject）
+ * - prompt-submit（waterfall）：每 agent 首次进入 CCC 时附加紧凑身份提示；
+ *   只注入一次（Set 跟踪），避免每轮 token 膨胀；context-only 必须 next() 委托
+ *   （短路会跳过后续策略监听器，interception-seams 笔记明确警告）。
+ */
+import type { Context } from 'cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { UserMessage } from '@deepseek-ai/dsh-session';
+export declare const DEFAULT_ENTRY_SKILL_MAX_CHARS = 30000;
+export declare function accIdentityText(root: string, configPaths?: string[], entrySkillMaxChars?: number): string;
+/**
+ * ACC 注入消息（S134 去重）：**只含简短身份锚点**（[ACC] 已激活 + CCC 根 + 约束 + handyman 模型 + Phase 2）。
+ * 完整身份（ACC 5 块 + CCE + Constraints + EAP + SKILL 全文 + Session 块）由**系统提示词层**
+ * （systemPrompt.section，每轮 prompt 装配自动注入，含 subagent）承担——对话消息流/压缩重注入
+ * 不再重复注入同一内容（token 双倍浪费，见 S134 注入方案梳理）。
+ */
+export declare function accMessage(root: string, configPaths: string[], entrySkillMaxChars: number): UserMessage;
+/**
+ * 重启恢复的根会话判定（S134 需求）：
+ * 只有"conversation 根会话"才自动恢复最近激活的宁静号会话——
+ * - subagent：session header `origin === 'subagent'`（DSH 路由语义，agent-lookup.ts）
+ * - 派生会话：`parentSession` 存在（任何子会话）
+ * - handyman 杂工：sessionId 固定 `handyman-` 前缀（tools/handyman.ts 生成）
+ * 三者都不恢复（避免把主会话激活注入子上下文，违背 v1.16.2 scope 隔离）。
+ */
+export declare function shouldAutoRestore(agent: Agent): boolean;
+/**
+ * 恢复触发判定（S134 泄漏修复 v1.16.13）：根会话 **且已有对话历史**（续跑/恢复的会话）
+ * 才自动恢复上次激活的宁静号会话——全新会话（新任务，如 apaas-26116）无历史 → 不恢复，
+ * 避免把过去的 SESSION 上下文注入新任务（跨任务污染）。
+ */
+export declare function shouldRestoreActive(agent: Agent): boolean;
+export interface ContextRegistration {
+    configPaths?: string[];
+    /** session-start 播种 */
+    seedOnStart?: boolean;
+    /** prompt-submit 兜底注入 */
+    injectOnPrompt?: boolean;
+    /** 入口 skill 内容注入上限（字符）；0 = 不注入 skill 内容 */
+    entrySkillMaxChars?: number;
+}
+export declare function registerContext(ctx: Context, opts?: ContextRegistration): void;

package/lib/seams/env.d.ts

@@ -0,0 +1,16 @@
+/**
+ * env.ts — shell.env 环境变量注入（ACC 标准）
+ *
+ * 经 ctx.shellEnv（DSH shell-env 缝，公开版由 bash-env 改名）注册 DSH_* 事实：
+ *   DSH_SERENITY_ROOT    — CCC 根目录（agent 会话 cwd 上溯 .serenity）
+ *   DSH_SERENITY_CCC     — CCC 名称（根目录 basename）
+ *   DSH_SERENITY_VERSION — ACC 版本
+ *
+ * 每次模型 shell 调用都会重建 DSH_* 命名空间并注入（按当前执行解析）。
+ */
+import type { Context } from 'cordis';
+import type { DshEnvironmentKey } from '@deepseek-ai/dsh-shell';
+export type SerenityEnvFacts = Partial<Record<DshEnvironmentKey, string>>;
+/** 纯解析：给定 cwd，返回可注入的 DSH_SERENITY_* 事实（非 CCC 返回空） */
+export declare function resolveSerenityEnv(cwd: string): SerenityEnvFacts;
+export declare function registerEnv(ctx: Context): void;

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;