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（六套件 139 断言 + 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.4

# 跟随 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 编排（条件边路由 + 降级安全）
│       └── candidate.ts   链节点 → SELECT 候选（仅非链模式）
├── 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    构建配置

验证

# 一键质量门禁（六套件 139 断言 + 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.4 | 协议：GPL-3.0 | 仓库：https://github.com/kiwifruit13/dsh-context-pro