DSH-Context-Pro

DSH Agent 的链感知系统 + 洞察引擎——让模型内化五维认知结构（因果/逻辑/操作/叙事/时间），在回复末尾通过一行 JSON 快照隐式标记，系统在后台提取并维护会话内链图，并对每轮回复做洞察分析（带归因档案），用户全程无感。

定位：不是记忆引擎，不是注入器，是认知结构层。 核心哲学：CoT 放权——系统只做三件事：注入图鉴到 System Prompt + 解析 JSON 快照 + 在 ChainGraph 上做归因洞察（超然层）。

核心机制

链协议模式（主模式）

System Prompt（已含五链图鉴 + 情绪底色 + 末尾 JSON 快照指令）
    │
    ▼
模型 CoT 自由推理 → 生成自然语言正文 + 末尾 JSON 快照行
    │
    ▼
session/event → hook.ts 解析快照 + 更新 ChainGraph（数据零改动，不剥离）
    │
    ▼
Client 渲染层按保守签名隐藏快照行（视觉隐身）
    │
    ▼
用户看到纯自然语言回复

五链图鉴通过 ctx.systemPrompt.section() 注入 System Prompt，模型内化后自然运用。末尾 JSON 快照原样保留在消息中供提取（数据不剥离），由 Client 渲染层视觉隐身，用户不可见。

非链模式

当 chains.enabled=false 时，插件退化为简单的上下文整形器，通过 agent/pre-step 拦截消息流做 SELECT/INJECT/MEASURE。

五维认知图鉴

| 链 | 本质 | 触发 | |---|---|---| | 因果链《溯源者》 | 对抗混乱，寻找"第一因" | 异常/困境 + "为什么/怎么办" | | 逻辑链《架构师》 | 对抗片面，追求"绝对理性" | 权衡/假设/"如果…那么…" | | 操作链《手艺人》 | 对抗空谈，追求"落地执行" | 动作动词/"先…再…"/无从下手 | | 叙事链《说书人》 | 对抗碎片，构建"意义之弧" | 具体年月/状态反转/回顾唏嘘 | | 时间链《预言家》 | 对抗短视，建立"动态视野" | "以前/现在/以后"三段对比 |

图鉴细节见 docs/Architectural-Thinking.md（已注册为技能 architectural-thinking，模型可发现）。

链间化学反应

五链可相互催化：因果×时间 → 深层归因动力学，逻辑×操作 → 抗脆弱执行手册，叙事×因果 → 沉浸式深度诊断，时间×叙事 → 变革蓝图。详见 docs/Integrated-Catalysis.md（已注册为技能 integrated-catalysis）。

洞察引擎

洞察引擎是链感知系统之上的超然层——只观察、只建议、不干预 CoT。它解决一个核心问题：让 AI 真的越来越懂用户。

它在做什么

每轮模型回复后，洞察引擎在 ChainGraph（会话内的全局结构）上做四步归因：

ChainGraph（会话内的累积知识）
   ↓
     ▼
7 个分析器产出 InsightItem[]（链间化学反应/迁移预测/置信度趋势/缺口聚合/分歧收敛/快照趋势/操作链进度，LangGraph StateGraph 编排）
   ↓
attributeInsightsPure() 在 ChainGraph 上做归因
   ↓
每条 InsightItem 附带 ConfidenceProfile：
   • nodeEvidence：基于哪些 ChainNode（primary / supporting / contradicting）
   • edgeEvidence：基于哪些结构化关系（parent-child / divergence / cross-chain-link 等）
   • contradictingEvidence：反向证据
   • attributionScore：综合评分 0-1
   • rationale：人类可读的归因路径
   ↓
get_insights 工具暴露归因洞察（模型按需调取，参考非约束）

它解决的核心问题

| 旧版本（v0.2.0）的问题 | v0.3+ 的解决 | |---|---| | 洞察只是"我看到了 X"的现象报告 | 洞察升级为"我为什么这样判断"的归因诊断 | | 用户感受不到"AI 真的懂我" | 归因真实 + 引用真实 → 用户的"被理解"感自然涌现 |

关键设计原则

• 零新增存储：归因档案随返回值流转，不持久化
• 洞察千变万化，方法论稳定：评估方法（四步法）结构固定，洞察内容由 ChainGraph 实时生成
• 基于 ChainGraph 多轮对话：跨轮引用让"AI 真的懂我"的感受自然涌现，不需要额外机制
• 超然层纯粹：归因档案是"档案"，不参与 CoT 推理

完整设计文档

详细设计（契约、归因算法、生命周期、配置、测试）：docs/insight-engine-design.md

安装与装配

环境要求：Node.js ≥ 22。一键质量门禁：pnpm verify（八套件 229 断言 + lint）。

方式 A：DSH Web Profile 安装（推荐，已验证）

# 1. 安装 dsh CLI 到项目（提供 node_modules/.bin/dsh）
pnpm add @deepseek-ai/dsh

# 2. 添加插件到 web profile（写入 ~/.dsh/profiles/web/package.json）
pnpm exec dsh plugin --profile web add @kiwifruit/dsh-context-pro

# 3. 验证已生效
pnpm exec dsh plugin --profile web list

⚠️ dsh 不在全局 PATH 时必须用 pnpm exec；--profile web 会把依赖写入用户级 profile（~/.dsh/profiles/web），不改动工作区 cordis.yml。

💡 包名不带 @版本号 即安装最新版；升级 = 重跑同一条命令 + 重启 web 进程。锁定版本写具体号（如 @kiwifruit/[email protected]）；注意新发布的版本有约 24 小时供应链冷却期，期间精确版本号是唯一立即可装的方式。

方式 B：npm 包手动装配（工作区级）

npm install @kiwifruit/dsh-context-pro

在 cordis.patch.yml 中添加：

- insert:
    - id: context-pro
      name: '@kiwifruit/dsh-context-pro'
      config:
        chains:
          enabled: true
          injectProtocol: true
          maxNodesPerChain: 20
          insight:
            enabled: true

方式 C：全局 CLI 安装（最简两步）

# 1. 全局安装 dsh CLI（需确保 pnpm global bin 在 PATH，或先运行 pnpm setup）
npm install -g @deepseek-ai/dsh

# 2. 直接添加插件到 web profile
dsh plugin --profile web add @kiwifruit/dsh-context-pro@latest

⚠️ 若提示 dsh 命令未找到，请运行 pnpm setup 刷新 PATH，或改用方式 A（项目级 pnpm exec）。

💡 同方式 A：裸包名即装最新版；升级重跑同一条命令 + 重启 web 进程。

方式 D：Git 直装（跟踪主线 / 冷却期绕行）

# 锁定发布标签安装（推荐）
dsh plugin --profile web add github:kiwifruit13/dsh-context-pro#v0.6.7

# 跟随 main 主线（尝鲜）
dsh plugin --profile web add github:kiwifruit13/dsh-context-pro

💡 Git 直装会在安装时自动触发 prepare 构建脚本（数秒），产物与 npm 包一致——npm 供应链冷却期内装最新版的绕行通道。

配置完整参考

| 字段 | 默认值 | 说明 | |---|---|---| | chains.enabled | false | 开启链感知（五链图鉴 + JSON 快照提取） | | chains.injectProtocol | false | 注入宪法层提示词段（核心哲学 + 快照契约冻结区，v5） | | chains.driftRepair.enabled | true | 漂移守卫：连续 N 轮最终回复无有效快照时自动注入自愈便条（引导调用技能复习协议） | | chains.driftRepair.threshold | 3 | 连续无快照轮数阈值（{"chain":"null"} 也算履约清零） | | chains.driftRepair.cooldownMs | 300000 | 自愈便条触发后的冷却毫秒数（防连发） | | chains.snapshotHistory.* | true / 2 | ⚠️ 已休眠（约束符合性报告 F-1/F-5）：循环请求深度冻结只读，剥壳置换待表面置换重构；字段保留仅为配置兼容 | | chains.digest.enabled | false | 脉络总览注入：turn/end 若总览实质变更且过冷却，经收件箱注入跨轮接续备忘（非指令） | | chains.digest.cooldownMs | 60000 | 总览注入冷却毫秒数（防连发） | | chains.maxNodesPerChain | 20 | 每链节点上限（防演化失控） | | chains.insight.enabled | true | 启用洞察引擎（依赖 chains.enabled） | | chains.insight.similarityThreshold | 0.15 | Jaccard 相似度阈值，去重洞察 | | chains.insight.maxStaleRounds | 3 | 连续未确认轮次上限，过期淘汰 | | chains.insight.maxInsights | 20 | 洞察项总数上限 | | chains.insight.historyWindow | 40 | 历史累积窗口（最近 N 轮 = 2N 条消息） | | chains.insight.maxSessions | 100 | 会话总数上限 | | chains.insight.selectiveAnalysis | false | 启用选择性分析器（P1） | | chains.insight.auth.enabled | false | API Key 鉴权 | | chains.insight.rateLimit.maxRequests | 100 | 限流：窗口内最大请求数 | | chains.insight.rateLimit.windowMs | 60000 | 限流：窗口毫秒数 |

核心能力

| 能力 | 说明 | 接入方式 | |---|---|---| | 五链图鉴注入 | 因果/逻辑/操作/叙事/时间 + 情绪底色 + 融合法则 | chains.injectProtocol: true 自动注入 System Prompt | | JSON 快照提取 | 末尾一行 JSON 解析入链图（supersede/confidence/diverged），数据不剥离 | hook.ts 监听 session/event | | 快照视觉隐身 | 渲染层按保守签名隐藏快照行，用户不可见；导出/日志仍可见（可观测性） | client.js installSnapshotStealth | | 洞察引擎（超然层 + 归因） | 链间化学反应/迁移预测/置信度趋势/缺口聚合/分歧收敛，仅建议不干预；每条洞察附带归因档案（节点证据 + 边证据 + 反证 + 综合评分 attributionScore） | get_insights 工具 + HTTP API | | HTTP API | /api/context-pro/stats /api/context-pro/openapi.json | webServer 服务自动注册，支持鉴权/限流 | | 项目技能注册 | agent-principles api-contract-guide architectural-thinking integrated-catalysis chain-fusion-advanced insight-engine hook-tool-data-flow chain-guide chain-design-final | 启动时自动注册，模型可发现 |

HTTP API 端点

| 端点 | 方法 | 说明 | |---|---|---| | /api/context-pro/stats | GET | 全量可观测性指标（快照成功率/链健康度/洞察命中率） | | /api/context-pro/openapi.json | GET | OpenAPI 3.1 规范文档 |

文档导航

| 文档 | 用途 | |---|---| | docs/chain-design-final.md | 终局设计文档（五链图鉴/提取通道/架构/纪律） | | docs/chain-guide.md | 链感知使用与架构指南 | | docs/Architectural-Thinking.md | 五维认知结构图鉴（技能 architectural-thinking） | | docs/Integrated-Catalysis.md | 链间化学反应催化酶（技能 integrated-catalysis） | | docs/AGENTS.md | 智能体工作原则（技能 agent-principles） | | docs/CLAUDE.md | API/接口/胶水公约（技能 api-contract-guide） | | docs/洞察引擎.md | 洞察引擎架构与分析器详解（v0.2.0 历史版本） | | docs/insight-engine-design.md | 洞察引擎 v0.3+ 完整设计文档（归因档案 + 生命周期） | | docs/insight-architecture.md | 洞察引擎架构终局（超然层/协作图/归因四步法/生命周期/三条通道） |

目录结构

DSH-Context-Pro/
├── src/
│   ├── index.ts           入口（name/apply/inject）
│   ├── prestep.ts         agent/pre-step 拦截器（链协议模式零干预）
│   ├── config.ts          Config schema（契约先行）
│   ├── skills.ts          技能注册（7 个技能）
│   ├── session-id.ts      统一 session ID 获取工具
│   ├── metrics.ts         可观测性指标收集
│   ├── auth.ts            HTTP 鉴权/限流中间件
│   ├── openapi.ts         OpenAPI 3.1 规范生成
│   └── chains/
│       ├── types.ts       链契约（ChainNode/ChainGraph/ChainIndex/InsightReference）
│       ├── graph.ts       ChainGraph 演化实现（upsert/prune/supersede/ended）
│       ├── index.ts       ChainIndex 临时存储 + 生命周期
│       ├── hook.ts        session/event 监听（提取快照 + 链提取 + 洞察分析）
│       ├── snapshot.ts    快照 JSON 解析（容错修复 + confidence/diverged/supersede）
│       ├── prompt.ts      五链图鉴提示词段（注入 System Prompt）
│       ├── guide.ts       脉络导览（GPS/轨道图/缺口探测）
│       ├── insight.ts     洞察引擎 v2（双源数据 + 7 分析器 + 归因 + LRU 内存保护）
│       ├── orchestrator.ts LangGraph StateGraph 编排（条件边路由 + 降级安全）
├── scripts/
│   ├── verify-e2e.ts      端到端装配验证
│   ├── verify-chains.ts   链感知方案验证（40 用例）
│   ├── verify-protocol.ts 图鉴协议内容完整性验证
│   ├── verify-attribution.ts 归因算法验证（23 断言）
│   ├── verify-stealth.ts  快照视觉隐身签名识别（15 断言）
│   ├── verify-protocol-links.ts 协议↔技能一致性与发布白名单门禁
│   ├── verify-hardening.ts 安全加固回归（9 断言）
│   ├── verify-insight-v2.ts 洞察 v2 Gherkin 六场景验收（13 断言）
│   ├── verify-pack.ts     发布制品断言（11 断言，接入 prepublishOnly）
│   └── diag-*.ts          会话日志/崩溃诊断工具链
├── docs/                  设计文档 / 技能源文件 / 公约
├── cordis.yml             装配示例（npm 包模式）
├── cordis.patch.yml       发布包自动应用的 patch
└── tsconfig.build.json    构建配置

验证

# 一键质量门禁（八套件 229 断言 + lint）——CI 同款
pnpm verify

# 端到端装配验证（单列）
node --import tsx/esm scripts/verify-e2e.ts

# 发布制品断言（pack 后校验技能文档与 client 入口在包内树；已接入 prepublishOnly）
node --import tsx/esm scripts/verify-pack.ts

# 单套件按需运行示例
node --import tsx/esm scripts/verify-insight-v2.ts   # 洞察 v2 Gherkin 六场景

CI：.github/workflows/ci.yml——pnpm typecheck（全项目零容忍）+ pnpm verify 双门禁。

改动生效速查

核心规则：Host 半区（src/**/*.ts）跑的是编译产物 lib/，改完必须过编译；Client 半区与技能文档不需要 tsc。

| 你改了什么 | 生效动作 | |---|---| | src/**/*.ts（引擎/钩子/鉴权/提示词…） | pnpm build——或开发期常开 pnpm watch（保存即增量编译） | | src/client.js（视觉隐身源码） | pnpm build:client 生成 factory-form 产物 lib/client.bundle.js（浏览器 load 的是产物；协议见下） | | docs/*.md、技能正文 | 无需 build，插件重载/重启即生效 | | cordis.patch.yml 装配配置 | 保存后 watcher 事务性重装配，免重启 |

让 profile 指向工作区源码（否则重启加载的还是 npm 上的旧版）：

dsh plugin --profile web remove @kiwifruit/dsh-context-pro
dsh plugin --profile web add file:E:\Deepseek\DSH-Context-Pro

Client bundle factory-form 协议（坑 #42）：DSH 浏览器端把 exports["./client"] 指向的文件当 classic <script> 加载，执行后必须调用 window.__ModuleLoader__.load({ id, factory }) 注册 factory，否则 dsh-client-modules 的 arrive() 抛 loaded without registering。 lib/client.bundle.js 由 scripts/build-client.mjs 零依赖生成（源码 src/client.js 零 import）， 产物结构逐行对齐官方 @deepseek-ai/dsh-client-runtime 发布版。 注意：官方 @deepseek-ai/dsh-client/clientBundle() 预设仅存在于 DSH 平台 monorepo， 未发布到 npm，第三方不可用。

设计决策

| 决策 | 理由 | |---|---| | CoT 放权 | 模型通过 System Prompt 内化五链图鉴，系统不干预推理过程 | | 末尾 JSON 快照为主提取通道 | 正文自然表达；数据不剥离（提取与模型跨轮接续依赖），渲染层视觉隐身实现用户不可见 | | 链图跟会话生命周期 | 删对话即删链，非长期记忆，零残留 | | 纯 TS 无外部引擎 | 贴近 DSH 生态、HMR 友好、零依赖 | | 洞察引擎超然层 | 只观察、只建议、不干预 CoT，避免污染模型推理 | | 归因档案（v0.3+） | 让洞察从"结果评价"升级为"归因诊断"：节点证据 + 边证据 + 反证 + 综合评分。洞察本身千变万化，但评估方法稳定可复用 | | Client UI 走 HTTP | 持久化、重启不丢失、不依赖动态插件 RPC |

发布到 npm

npm run build
npm publish --access public

当前版本：0.6.7 | 协议：GPL-3.0 | 仓库：https://github.com/kiwifruit13/dsh-context-pro