@hilariouhiss/dsh-codegraph 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-codegraph contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# @hilariouhiss/dsh-codegraph
+
+把 [codegraph](https://github.com/colbymchenry/codegraph)（本地优先的代码图 / 知识图谱，让 AI agent 用「预建的符号·调用边·依赖图」回答代码结构问题，而非逐文件 grep）接入 DeepSeek Harness。
+
+本插件以 DSH **bundle 插件**形式，通过 DSH 内置的 MCP 客户端桥（`@deepseek-ai/dsh-mcp-client`）连接 CodeGraph 的 MCP server，注册 `mcp__codegraph__*` 工具，并注入一条轻量使用引导。安装后对 `web`、`headless` 等任意 profile 的所有会话生效。
+
+## 功能
+
+- 注册 **`mcp__codegraph__codegraph_explore`** 工具：一次调用返回相关符号的逐字源码（按文件分组）、符号间调用链（含动态分派跳转）与影响范围（blast radius）。
+- 注入系统提示词引导，让智能体对结构性问题（「X 如何工作」「X 如何到达 Y」「改某处会影响什么」）**优先直接调 `codegraph_explore`**，而不是 grep/逐文件读，并**传 `projectPath`** 指向当前工作区。
+
+## 前置要求
+
+1. 全局安装 CodeGraph CLI（`codegraph` 需在 DSH 宿主进程的 PATH 上）：
+
+   ```powershell
+   npm i -g @colbymchenry/codegraph
+   # 或：irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
+   ```
+
+2. 每个项目首次建图（生成 `.codegraph/` 索引；之后 MCP server 的 watcher 自动增量同步）：
+
+   ```powershell
+   cd <your-project>
+   codegraph init
+   ```
+
+## 安装
+
+```powershell
+dsh plugin --profile web add @hilariouhiss/dsh-codegraph
+```
+
+把 `web` 换成你的 profile 名（例如 `headless`）。然后**重启 dsh**。
+
+`dsh plugin` 会把本包安装进 profile 的 `node_modules`；因为 `package.json` 声明了 `dsh.bundle.patch`，profile 的 bundle 列表会自动追加 `@hilariouhiss/dsh-codegraph`，重启后插件行自动激活。
+
+## 验证
+
+1. 重启后，让模型回答一个代码结构问题（如「这个请求是怎么到达数据库的」），观察它调用 `mcp__codegraph__codegraph_explore` 且返回源码 + 调用链。
+2. 若某项目尚未建图，工具会返回「无索引」提示——在该项目跑一次 `codegraph init` 即可。
+
+## 卸载
+
+```powershell
+dsh plugin --profile web remove @hilariouhiss/dsh-codegraph
+```
+
+然后重启 dsh。
+
+## 已知问题与限制
+
+当前实现是「MCP server 直连 + 静态引导」的最小可行集成，已知有以下问题：
+
+1. **模型必须每次手动传 `projectPath`（最大痛点）**：DSH 宿主是单实例、多会话（多工作区），而 mcp-client 的 `cwd` 是宿主面静态配置（`process.cwd()`）。`codegraph_explore` 无法默认指向「当前会话工作区」，模型每次调用都要自己填 `projectPath` = 当前工作区。若漏填，会查询 server 的默认目录（通常没有 `.codegraph/` 索引），返回误导性的「无索引/请用内置工具」提示。理想做法是包装一个能自动注入会话 `cwd` 的工具，或让 server 按会话定位项目。
+
+2. **自动同步只覆盖 server 默认目录的项目**：codegraph 的文件 watcher 只持续监视 MCP server 启动 `cwd` 对应的项目；经 `projectPath` 查询的其它项目没有持续 watcher，索引不会随编辑自动刷新，需手动 `codegraph sync` 保持最新（本插件未做任何同步封装）。
+
+3. **不自动建索引**：每个项目必须手动 `codegraph init` 一次；插件不代建。未初始化时工具返回「无索引」引导而非真实结果。
+
+4. **依赖全局 `codegraph` CLI**：插件只负责连 MCP，不安装、不校验 `codegraph`。若未全局安装，mcp-client 启动失败并重试后静默注销工具，模型看不到原因（只能查 DSH 日志）。
+
+5. **引导是静态文本**：`systemPrompt.section` 只能写死「传 `projectPath` = 你的工作区」，无法把当前工作区的绝对路径动态注入提示词。
+
+6. **未端到端验证**：尚未在真实 profile 里走完 `dsh plugin add` → 重启 → 实际调用 `mcp__codegraph__codegraph_explore` 的闭环（当前仅单元测试 + 按 codegraph 官方 stdio 配置对齐）。
+
+7. **遥测默认开启**：codegraph 的匿名遥测默认开（不采集代码/路径/查询内容）；本插件未关闭。可用 `codegraph telemetry off` 或环境变量 `CODEGRAPH_TELEMETRY=0` 关闭。
+
+## 开发
+
+```powershell
+pnpm install
+pnpm test
+```
+
+结构：
+
+```
+lib/index.js        插件入口：apply(ctx) 用 ctx.plugin 加载 mcp-client + 注入引导
+cordis.patch.yml    bundle patch：插入本插件的宿主行
+test/               node:test 单元测试（config 组装、plugin 加载、引导注册）
+```
+
+## 发布（给维护者）
+
+```powershell
+cd dsh-codegraph
+pnpm install
+pnpm test
+npm login       # 首次发布前登录 npm
+npm publish     # publishConfig.access 已设为 public
+```
+
+`prepublishOnly` 会在每次发布前自动运行 `npm test`；发布新版本前记得递增 `package.json` 的 `version`。
+
+## 许可与来源
+
+本插件为 MIT 许可。它只通过 MCP 连接外部的 `codegraph` CLI，未内置 codegraph 源码；codegraph 本身来自 [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph)（© Colby McHenry，MIT，其自身许可见上游仓库）。
+
+> 提示：若日后升级 dsh 后 `@deepseek-ai/dsh-mcp-client` 的公开 API 发生变化，需同步更新本插件的依赖版本。

package/cordis.patch.yml

@@ -0,0 +1,12 @@
+# @hilariouhiss/dsh-codegraph bundle patch: one self-referencing host row.
+#
+# `dsh plugin --profile <name> add @hilariouhiss/dsh-codegraph` installs this
+# package into the profile; because it declares `dsh.bundle.patch`, the profile
+# manifest appends it to the bundle list, and this patch is applied as a layer
+# on boot. The row resolves `@hilariouhiss/dsh-codegraph` from the profile's own
+# node_modules, so the plugin's `apply(ctx)` runs in the host plane: it loads
+# the DSH MCP client bridge for the CodeGraph server (registering
+# `mcp__codegraph__*` tools globally) and injects usage guidance.
+- insert:
+    - id: codegraph
+      name: '@hilariouhiss/dsh-codegraph'

package/lib/index.js

@@ -0,0 +1,45 @@
+import { apply as mcpClientApply, inject as mcpClientInject } from "@deepseek-ai/dsh-mcp-client";
+
+export const name = "codegraph";
+export const inject = ["systemPrompt"];
+
+const GUIDANCE = [
+	"CodeGraph (semantic code intelligence) is available through the `mcp__codegraph__codegraph_explore` tool. ",
+	"For structural questions about the codebase — how a component works, how X reaches Y, the blast radius of a change — ",
+	"call `mcp__codegraph__codegraph_explore` directly instead of grepping or reading files one by one; ",
+	"it returns the relevant symbols' source, call paths, and impact in one call. ",
+	"Always pass `projectPath` as the workspace directory you are working in (or a subdirectory that has a `.codegraph/` index). ",
+	"If the tool reports no index, tell the user to run `codegraph init` in that project first.",
+].join("");
+
+/**
+ * Stdio config for the CodeGraph MCP server. `command` resolves `codegraph`
+ * from the DSH host process's PATH (installed globally), and `cwd` is only the
+ * server's default project — the model always passes `projectPath` to target
+ * the actual workspace.
+ *
+ * @param {string} [cwd] default project directory for the spawned server.
+ * @returns {import("@deepseek-ai/dsh-mcp-client").StdioConfig}
+ */
+export function codegraphConfig(cwd = process.cwd()) {
+	return {
+		transport: "stdio",
+		serverName: "codegraph",
+		command: "codegraph",
+		args: ["serve", "--mcp"],
+		env: {},
+		cwd,
+		toolCallTimeoutMs: 120000,
+		failOnStartupError: false,
+	};
+}
+
+/**
+ * DSH plugin entry point. Loads the DSH MCP client bridge for the CodeGraph
+ * server (registering `mcp__codegraph__*` tools globally) and injects a small
+ * usage guidance section so agents prefer it and pass `projectPath`.
+ */
+export function apply(ctx) {
+	ctx.plugin({ inject: mcpClientInject, apply: mcpClientApply }, codegraphConfig());
+	ctx.systemPrompt.section({ name: "codegraph:guidance", order: 100, text: GUIDANCE });
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@hilariouhiss/dsh-codegraph",
+  "version": "1.0.0",
+  "description": "CodeGraph — semantic code intelligence (MCP) for DeepSeek Harness. Adds codegraph_explore so agents answer structural code questions from a pre-built code graph.",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "dsh-plugin",
+    "codegraph",
+    "code-graph",
+    "code-intelligence",
+    "mcp"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "dsh-codegraph contributors"
+  },
+  "homepage": "https://github.com/hilariouhiss/dsh-hiss-plugins/tree/main/dsh-codegraph",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hilariouhiss/dsh-hiss-plugins.git",
+    "directory": "dsh-codegraph"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@deepseek-ai/dsh-mcp-client": "0.1.1-rc.2"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}