context-graph-deepseek-harness

Context Graph for DeepSeek Harness

这是一个给 DeepSeek Harness 用的工程上下文插件。它在 Harness 对话界面里增加 Context Graph 视图，并在请求模型前整理、审计和注入当前任务需要的项目上下文。

它不是独立软件，不启动额外网页，也不替换 Harness 的模型客户端。

为什么做这个插件

Coding Agent 工作时既要理解当前任务，也要记住项目约定，还要找到相关源码。把所有内容都塞进请求很浪费，只看眼前的一句话又很容易漏掉接口和依赖约束。

这个插件把它们整理成可以追溯的节点和关系：

用户任务
   ↓
语义功能 / 需求 / 约束 / 决策
   ↓
实现文件 / 类 / 函数 / 接口
   ↓
Context Compiler
   ↓
预算受控的模型上下文

特性

功能与任务

• 用功能、任务、需求、约束、决策、问题和备注记录“系统要做什么”。
• 一个功能可以关联多个实现文件，也可以随时合并、拆分或手动调整。
• 这个视图默认不展示 import、call 等代码细节，日常查看时不会被依赖线淹没。

实现与依赖图

• 扫描 Python、C 和 C++ 的模块、符号、调用、继承、接口和项目内依赖。
• 修改代码后可以增量更新，也能查询调用方、被调用方和接口定义。
• 只有源码证据明确时才会自动连线。宏展开、重载歧义和外部符号不会靠猜测补全。

C/C++ 解析

支持以下扩展名，无需安装 clang：

.c  .cc  .cpp  .cxx  .h  .hh  .hpp  .hxx

目前会提取：

• 项目内 #include 关系
• 类和结构体
• 函数定义与声明
• 唯一可确认的函数调用
• 继承关系

源文件和头文件使用独立模块 ID，避免同名冲突。无法唯一确认的关系会标记为未知。

按章节读取 PDF

• document_scan 读取 PDF 元数据和原生目录，建立文档与章节层级。
• document_find_sections 按当前任务匹配目录标题，不会先加载整本正文。
• document_extract_sections 提取选中章节，并保留文件名和页码引用。
• document_extract_layout 识别章节里的代码块与表格；表格会同时保存为 Markdown 和 JSON。
• 传入 apply=true 后，结果会写入对应的 documentation 节点，供 Context Compiler 后续选择。

布局结果会保存页码和 bbox，并作为章节的 contains 子节点加入图谱。目前不做 OCR。没有原生书签的 PDF 会返回 outlineAvailable: false，插件不会自行猜目录。

上下文编译与防火墙

• 从任务或功能目标出发，挑选相关的结构化上下文和实现文件。
• 可以控制单轮预算、文件数量、关联层数，也支持临时包含、排除和上下文复用。
• 在 agent/pre-step 编译 Context Snapshot，在最终 llm/stream 请求边界执行消息、快照、工具和 token 审计。
• FORCE_INCLUDE、FORCE_EXCLUDE 和用户确认的 MANUAL 关系优先于自动分析。
• 普通对话无法判断目标时会使用空的 context.none 快照，用户输入仍会正常发送。

原生 Harness 界面

• Context Graph 显示在 Harness 对话区域的视图标签中。
• 界面支持中文、明暗主题、节点拖动、画布平移、缩放、自动排布和属性编辑。
• 右下角输入框照常发送消息；“上下文”按钮用来创建持久任务、选择任务类型和调整当前会话的注入策略。
• Context Preview 可以检查包含项、排除项、来源、原因、token 统计和最终审计结果。

环境要求

• DeepSeek Harness 0.1.0-rc.6 或更新的 0.1.x
• Node.js ^22.19.0 或 >=24
• Python 3（用于 Python AST 和 C/C++ 依赖事实提取；缺失时使用轻量回退扫描）
• PyMuPDF 或 pypdf（PDF 目录和章节文本提取；优先使用 PyMuPDF）

启用 PDF 支持：

cd ~/context-graph-deepseek-harness
python3 -m venv .venv-pdf
.venv-pdf/bin/python -m pip install pymupdf pypdf pdfplumber

插件会依次查找显式配置、当前虚拟环境、项目 .venv-pdf / .venv、插件 .venv-pdf、用户目录下的插件源码环境和系统 Python。通常无需为 Harness 单独配置环境变量；如需强制指定，仍可设置 CONTEXT_GRAPH_PDF_PYTHON。

安装

本地源码安装

插件源码必须位于 WSL 文件系统中。可以将当前源码复制到 WSL，或在 WSL 中克隆后作为本地依赖使用：

cd ~/deepseek-harness
git clone https://github.com/Mshir0/context-graph-deepseek-harness.git ~/context-graph-deepseek-harness
pnpm dsh plugin --profile web add -w /home/mashiro/context-graph-deepseek-harness
pnpm dsh --profile web --dump-config
pnpm dsh web

修改 /home/mashiro/context-graph-deepseek-harness 中的源码后，重新执行 add -w 并重启 Harness。这个方式适合本地开发和验证修复，也能避开旧的 GitHub 包缓存。

从 GitHub 安装

cd ~/deepseek-harness
npx -y @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web add -w github:Mshir0/context-graph-deepseek-harness
npx -y @deepseek-ai/dsh@0.1.0-rc.6 --profile web --dump-config
npx -y @deepseek-ai/dsh@0.1.0-rc.6 web

--dump-config 中应出现 context-graph 和 dsh-context-graph。首次安装或升级后需要重启 Harness；浏览器仍显示旧界面时执行 Ctrl+Shift+R。

从源码运行 Harness

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build

git clone https://github.com/Mshir0/context-graph-deepseek-harness.git ~/context-graph-deepseek-harness
pnpm dsh plugin --profile web add -w ~/context-graph-deepseek-harness
pnpm dsh web

修改插件源码后重新执行 pnpm dsh plugin ... add -w，然后重启 pnpm dsh web。

其他本地开发路径

在 Harness 源码目录执行：

pnpm dsh plugin --profile web add -w /path/to/context-graph-deepseek-harness
pnpm dsh web

插件没有独立 Web 服务。Host 代码在 Harness 启动时加载，Client bundle 由插件 manifest 注册到 DSH 的 client loader。

在对话中使用

1. 打开 Harness 的 http://127.0.0.1:3080/。
2. 进入一个带工程工作区的会话。
3. 直接在右下角输入框发送普通消息，插件会尝试注入当前任务相关上下文。
4. 需要持久任务时，打开“上下文”，填写任务内容并选择任务类型；“添加到输入框”只整理文本，“创建任务并发送”会保存 Task 节点后发送。
5. 在“上下文图谱”视图中扫描代码、确认功能推断、查看实现映射或打开 Context Preview。

常用快捷键：

快捷键	作用
Ctrl/⌘ + S	保存图谱
Delete	删除选中节点或关系
F	适合画布
A	自动排布
Esc	取消当前操作

工具与 Skills

插件向 DSH 注册以下主要工具：

工具	用途
context_graph_scan	扫描工程并同步代码模块事实
functional_infer	生成待确认的功能节点和实现映射
context_compile	预览预算下最终上下文
context_select	设置当前会话目标、包含和排除项
context_session_config	设置自动注入、复用和单轮预算
context_audit	查看防火墙最终决策和 token 审计
dependency_discover_modules	发现 Python/C/C++ 模块、符号和依赖
dependency_analyze_module	查看模块关系、接口和证据
dependency_find_callers / dependency_find_callees	查询调用方和被调用方
dependency_extract_interface	提取函数/类的接口契约
dependency_check_consistency	按文件或模块检查一致性，默认最多返回 50 条明细
context_extract	从对话提取可确认的结构化记忆
document_scan	读取 PDF 原生目录并建立章节图谱，默认返回前 50 项
document_find_sections	按任务匹配目录章节，不读取正文
document_extract_sections	按页提取选中章节并可持久化到图谱
document_extract_layout	提取章节内代码块和 Markdown+JSON 表格

随插件发布的 Skills 按职责拆分为 module-discovery、dependency-analysis、interface-contract、document-analysis、context-extraction、context-routing、context-maintenance、context-compiler 和 context-firewall。

配置

默认 bundle 配置位于 cordis.patch.yml：

config:
  tokenBudget: 6000
  requestTokenBudget: 512000
  outputReserveTokens: 256000
  tokenSafetyRatio: 1.15
  autoScan: true
  autoInject: true
  firewallMode: enforce
  webUi: true

tokenBudget 控制选中的 Context Graph 条目；requestTokenBudget 控制最终模型请求；outputReserveTokens 为模型输出预留空间。它们不是供应商账单中的精确 tokenizer 数字，而是跨模型可用的保守估值。

如果关闭 autoInject，插件仍会在 firewallMode: enforce 下使用不含项目图谱的空快照替换会话表面。只有显式设置 firewallMode: off 才会完全停用边界控制。

卸载

先停止 Harness，再执行：

npx -y @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web remove dsh-context-graph

如果提示 ERR_PNPM_CANNOT_REMOVE_MISSING_DEPS，说明依赖位于 Harness workspace 或 profile 的其他层。检查：

grep -RniE 'dsh-context-graph|context-graph' \
  ~/deepseek-harness/package.json \
  ~/.dsh/profiles/web/package.json \
  ~/.dsh/profiles/web/cordis.patch.yml 2>/dev/null

从实际包含依赖的目录执行 pnpm remove dsh-context-graph；若 cordis.patch.yml 仍有 id: context-graph 的插件块，删除该块后重启 Harness。项目 .context/ 目录是图谱数据，不负责加载插件按钮。

开发与验证

pnpm install
pnpm run check
node --test test/context-firewall.test.js
node --test test/c-family.test.js

完整测试：

pnpm test

完整 DSH 生命周期测试需要 Harness 依赖和官方 runtime；如果本地 pnpm 需要清理 node_modules，请在交互式终端执行，不要在无 TTY 的 CI shell 中强制删除依赖目录。

设计边界

• Context Graph 不会自动修改业务源码。
• 扫描结果不会未经确认直接创建语义功能关系；functional_infer 只生成待确认提案。
• 原始对话节点默认保留来源追溯，但不会自动注入模型上下文。
• 代码调用关系属于实现图，不会直接冒充功能关系。
• Context Firewall 无法安全替换已有历史时会阻止请求，而不是静默把未选择的历史发送给模型。

贡献

问题和改进可以直接提交到 Issue 或 Pull Request。改到 Host 生命周期、防火墙、依赖扫描或 UI 时，请一并补上相应的回归测试。

许可证

MIT