@kiwifruit/dsh-context-pro

Readme

# DSH-Context-Pro

[![npm version](https://img.shields.io/npm/v/@kiwifruit/dsh-context-pro)](https://www.npmjs.com/package/@kiwifruit/dsh-context-pro)
[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](LICENSE)
![ecosystem](https://img.shields.io/badge/ecosystem-dsh--plugin-2563eb)

**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`](./docs/insight-engine-design.md)

## 安装与装配

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

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

```bash
# 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/dsh-context-pro@0.5.2`）；注意新发布的版本有约 24 小时供应链冷却期，期间精确版本号是唯一立即可装的方式。

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

```bash
npm install @kiwifruit/dsh-context-pro
```

在 `cordis.patch.yml` 中添加：

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

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

```bash
# 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 直装（跟踪主线 / 冷却期绕行）

```bash
# 锁定发布标签安装（推荐）
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    构建配置
```

## 验证

```bash
# 一键质量门禁（八套件 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 上的旧版）：

```powershell
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

```bash
npm run build
npm publish --access public
```

---

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