dsh-graft

把 Graft（代码库上下文图谱）以原生工具 + 提示注入 + 技能包的形式集成进 DeepSeek Harness（DSH）Cordis 插件体系。

Graft 把代码库预索引成一棵可读的 Markdown 知识图谱（graft/*.md + graft/.graph/wiring.json），查询前自动做 $0 结构级增量刷新。本插件让 DSH 的 agent 直接调用 graft_ask / graft_callers / graft_grep 等工具，自动定位当前会话工作区，首次使用自动建图，查询自动保鲜。

完整设计方案见 DESIGN.md。

功能

| 工具 | 作用 | |---|---| | graft_build | 构建/重建图谱（--deep 需要 LLM key） | | graft_ask | 针对任务返回排序节点 + 精确 file:line | | graft_callers | 符号调用者 / 被调者（blast radius） | | graft_grep | 按耦合排序的正则搜索 | | graft_map | 全局取向：目录簇、hub、热点 | | graft_skeleton | 单文件 API 签名视图 | | graft_check | 图谱新鲜度检查（exit 1 = drift） | | graft_viz | 交互式可视化（本地 URL） |

特性：

• 会话工作区感知：工具从 exec.agent.session.header.cwd 解析仓库根，多仓库会话切换自动跟随，不读插件进程 cwd；
• 首次自动建图 + 自动保鲜：默认 autoBuildOnFirstUse: true，无 graft/ 时先静默 graft build（$0 结构层，无需 key）；每次查询由 Graft CLI 内建 freshness 增量刷新；
• 取消 / 超时 / 并发：转发 exec.signal，Windows 上 taskkill /T /F 杀进程树；查询工具 isConcurrencySafe，build/viz 排他；
• 静态提示注入：graft:usage 工具指引 section（order 120，固定文本，KV-cache 友好），可关闭；
• 技能包：激活时自动安装 ~/.dsh/skills/graft/SKILL.md，模型可按需 skill("graft") 加载完整用法；
• 可选动态 repo map：repoMapInjection: true 时按会话 cwd 注入 graft/INDEX.md 摘要（默认关，token 有预算）；
• UI card：graft_build → terminal card，graft_grep → search card（按文件分组的命中视图）。

安装

# 开发期：本地路径安装进 web profile
cd E:\Project\dsh-graft
npm install
npm run build
dsh plugin --profile web add "E:\\Project\\dsh-graft"

在 ~/.dsh/profiles/web/cordis.patch.yml 追加（DSH 对 patch 文件做 HMR，保存即生效）：

- insert:
    - id: dsh-graft
      name: dsh-graft
      config:
        autoBuildOnFirstUse: true

发布后：

npm publish
dsh plugin --profile web add dsh-graft

配置

三层设置：schema 默认值 → patch base（上面 config:）→ ~/.dsh/settings.yaml 的 graft: 节（用户层，最高优先级，热生效）。

# ~/.dsh/settings.yaml —— 只写想覆盖的项
graft:
  autoBuildOnFirstUse: true
  buildDeep: false
  extensions: ['.ts', '.py']
  usageSection: true
  repoMapInjection: false
  toolTimeoutMs: 120000
  askMaxNodes: 10
  enabledTools:
    - graft_build
    - graft_ask
    - graft_callers
    - graft_grep
    - graft_map
    - graft_skeleton
    - graft_check
    - graft_viz

关键项：

| 键 | 默认 | 说明 | |---|---|---| | autoBuildOnFirstUse | true | 首次工具调用前自动 graft build（$0，无需 key） | | buildDeep | false | 自动 build 是否 --deep（需 LLM key，花钱） | | extensions | [] | 仅索引这些扩展名 | | includeDirs | [] | 覆盖默认跳过目录（裸目录名） | | followSubmodules | false | 包含 git 子模块（graft ≥ 0.11） | | llmProvider / llmModel / llmBaseUrl | — | 映射到 GRAFT_PROVIDER / GRAFT_MODEL / GRAFT_BASE_URL | | apiKeyEnv | GRAFT_API_KEY | key 从环境变量读取，不写进 settings.yaml 明文 | | enabledTools | 全部 | 裁剪注册的工具（省 schema token）；空 = 全部 | | toolTimeoutMs | 120000 | 查询超时（含杀进程树） | | deepBuildTimeoutMs | 600000 | --deep 构建超时 | | defaultDir | — | 兜底工作区（通常不需要） | | binPath | — | graft CLI 路径覆盖（默认解析本地安装，npx 兜底） | | resultMaxChars | 12000 | 工具结果文本截断上限 | | askMaxNodes | 10 | graft_ask 返回节点数上限 | | allowViz | true | 是否注册 graft_viz | | usageSection | true | 注入 graft:usage 静态指引 | | repoMapInjection | false | 会话首轮注入 repo map（动态文本，默认关） | | repoMapMaxLines | 40 | repo map 注入行数预算 | | installSkill | true | 激活时写 ~/.dsh/skills/graft/SKILL.md | | logLevel | info | debug / info / warn | | vizPort | 0 | graft_viz 端口（0 = 自动分配） |

开发

npm run typecheck   # tsc --noEmit
npm run build       # tsc → lib/
npm test            # tsx --test（单元 + 集成 + 插件加载冒烟）

测试覆盖：dir 解析优先级、argv/JSON 解析、错误映射、graft check 退出码 1 特判、超时/取消杀进程树、工具 schema 形状、search/terminal card 投影、插件加载（8 工具 + settings 命名空间 + prompt section + skill 安装）、真实 CLI 集成（fixture 仓库）。

里程碑状态

• [x] M0 脚手架：包结构、可加载 entry
• [x] M1 MVP：graft_build / graft_ask / graft_check + 会话 cwd 解析 + settings 命名空间
• [x] M2 全工具：8 个工具全量、usage section、skill 安装、全量设置、超时/取消/并发、单测
• [x] M3 深度融合：repo-map 动态注入（默认关）、graft_viz、结果裁剪、search/terminal card
• [ ] M4 发布：npm 包 + bundle 打包（dsh.bundle.patch 已声明）；可选 GUI 设置卡片

注意

• 依赖 @nanonets/graft CLI（运行时依赖）；CLI 缺失时回退 npx -y @nanonets/graft。
• --deep 需要 API key（环境变量 GRAFT_API_KEY），默认只做结构层。
• graft_check 不自动建图：它报告真实状态（无图 / drift），与查询工具语义不同。
• graft_viz 是长驻进程，插件卸载时统一清理。