前言¶
在 DeepSeek Harness（DSH）里跑智能体改代码，常见检索仍是 grep 或扁平全文索引：能搜到字符串，却难以回答「改这个导出函数会影响谁」「文档里写的功能落在哪些调用链上」。仓库变大、单仓多包时，签名猜错、漏跑测试、改共享符号时低估连带修改，都是实际风险。
下面介绍社区插件 dsh-knowcode（维护者 huuthuan-nguyen）：把 Tree-sitter WebAssembly AST 代码图、Markdown 知识库和嵌入式 FalkorDB（Cypher）收进同一套图数据库，并通过 knowcode CLI 提供类似 tgrep 的守护进程与增量文件监听。DSH 侧通过 Cordis 插件暴露约 25 个工具，供智能体做符号检索、重构影响面、克隆检测与 spec-to-code 追溯。
这是什么¶
dsh-knowcode 是 npm 包名，GitHub 仓库为 huuthuan-nguyen/dsh-knowcode，许可证 MIT。在社区目录 SkillHub 中分类为「记忆」。SkillHub 是社区插件目录，与 DeepSeek / 幻方无官方从属关系；DSH 本身遵循「一切皆插件」的扩展方式。
一句话定位：在本地嵌入 FalkorDB，统一维护代码符号图（类、函数、调用、继承、测试关联等）与文档/规则知识，并在文档节点与代码符号之间建立双向边（例如 (:DocSection)-[:DOCUMENTS]->(:Symbol)、(:Rule)-[:GOVERNS]->(:File)）。
核心能力¶
代码图（Tree-sitter WASM）¶
解析引擎基于 Tree-sitter WebAssembly，README 说明没有固定语言白名单：内置常见语法，其余可按需加载，也可放入自定义 .wasm 语法。
内置覆盖包括 TypeScript/TSX、JavaScript/JSX、Go、Rust、C/C++、Java、C#、Python、Ruby、PHP、Lua、Shell、Kotlin、Scala、Swift、Zig、Elixir、OCaml、ReScript、Solidity 等；同一套图模型包含限定名、import 边、调用边、行号范围等。
扩展语法可放在：
- 项目内：
<workspace>/.knowcode/grammars/tree-sitter-<lang>.wasm - 用户目录：
~/.knowcode/grammars/tree-sitter-<lang>.wasm - 环境变量：
KNOWCODE_GRAMMARS_DIR=/path/to/grammars
知识图与交叉链接¶
索引 ADR、README、设计文档、编码规范等 Markdown 内容，并与代码符号自动关联，便于「从 spec 找实现」或「从符号反查文档」。
图查询与工程向分析¶
相对 README 中的 dsh-tool-codegraph、dsh-knowledge-base，本插件强调：
- 重构爆炸半径（传递调用、风险评分、关联测试）
- 环依赖检测（图上的 cycle 遍历）
- 代码克隆（基于 AST token 指纹）
- 跨语言移植相关的接口契约与依赖蓝图
- spec ↔ code 双向追溯
数据落在工作区默认目录 .knowcode（可通过配置或 CLI 的 --data-dir 调整）。
架构：index / serve 与守护进程¶
采用 Microsoft tgrep 风格：一次性索引 knowcode index .，或长期运行 knowcode serve .（带 debounce 的文件监听与 SHA 增量更新）。README 说明 serve 启动时会自行对账索引，多数场景不必先跑 index；CI 一次性建图可用 index（会起 daemon、索引后退出）。
守护进程默认监听 http://127.0.0.1:48123；Harness 工具经 HTTP/IPC 访问。
DSH 智能体工具（节选）¶
插件向 Cordis 注册多组工具，名称以 README 为准，例如：
| 方向 | 代表工具 | 用途 |
|---|---|---|
| 探索 | code_get_architecture_overview |
入口符号、调用 hub、语言分布 |
| 安全重构 | code_analyze_refactor_blast_radius |
修改前评估传递影响与测试 |
| 调用关系 | code_find_function_callers / code_find_function_callees |
上下游调用点与行号 |
| 质量 | code_detect_circular_dependencies、code_find_similar_duplicate_functions |
环依赖、克隆检测 |
| 追溯 | spec_find_code_flow_for_feature、code_find_spec_features_for_symbol |
文档功能 ↔ 代码流 |
| 知识 | knowledge_search_documentation_and_rules |
ADR/规范检索并链到符号 |
| 运维 | knowcode_check_index_health_and_stats、knowcode_execute_custom_cypher_query |
索引健康、Cypher 逃生舱 |
完整列表见仓库 README「The 25 Agent Tools」一节。
环境与依赖¶
| 项 | 说明 |
|---|---|
| Node.js | ^22.19.0 \|\| >=24.0.0（与 DSH 要求一致） |
| 平台 | macOS Apple Silicon、Linux x64 自带嵌入式 FalkorDB；其它平台可设 FALKORDB_URL 连接外部实例（见 README Platform Support） |
| peer | @deepseek-ai/cordis、@deepseek-ai/dsh-tools（optional） |
knowcode 不是独立下载的二进制，而是包内 CLI：package.json 中 "bin": { "knowcode": "./bin/knowcode.js" }。
安装与启用¶
安装到 DSH Profile（推荐）¶
在目标 profile 下一行安装并注册插件（README 示例 profile 名为 web，请换成你实际使用的 profile）：
dsh plugin add --profile web dsh-knowcode
安装后，该 profile 的 node_modules/.bin 中会有 knowcode，例如：
~/.dsh/profiles/web/node_modules/.bin/knowcode index .
本地开发插件源码时，可链接 checkout（路径改为本机绝对路径）：
dsh plugin add --profile web link:/absolute/path/to/dsh-knowcode
通过 Cordis patch 配置¶
在 profile 的 cordis.patch.yml 中插入 bundle（字段以 README 为准）：
- insert:
- id: knowcode
name: 'dsh-knowcode'
config:
daemonPort: 48123
dataDir: .knowcode
blastRadiusMaxDepth: 3
autoStartDaemon: true
常用配置项包括：daemonPort（默认 48123）、dataDir（默认 .knowcode）、falkordbUrl（空则嵌入式）、blastRadiusMaxDepth（默认 3）、autoStartDaemon（默认 true）、stopDaemonOnExit（默认 true）等，详见 README「Configuration options」。
仅用 npm 试用 CLI¶
不装 DSH 也可验证索引与守护进程：
npx dsh-knowcode index .
npx dsh-knowcode serve .
验证命令是否可用：
knowcode --version
knowcode --help
典型用法¶
1. 建图并启动守护进程¶
进入仓库根目录。日常开发通常只需 serve；需要强制全量重扫时使用 --force-index（升级解析器后 README 也建议强制重索引或删除 .knowcode/falkordb.rdb）。
knowcode serve .
可选：先一次性索引再常驻（预热身，首条工具调用更快）：
knowcode index .
knowcode serve .
调试 watcher 与 RPC 时：
knowcode serve . --trace
2. 查看图状态¶
knowcode status .
会输出 daemon 是否在线、.knowcode 路径、文件/符号/调用/文档计数及按语言分布等（具体字段以 CLI 输出为准）。
3. 直接跑 Cypher¶
适合脚本或人工探查图结构：
knowcode query "MATCH (s:Symbol {kind: 'class'}) RETURN s.name, s.file"
4. 在 DSH 会话中使用¶
- 按上文安装插件并启用
autoStartDaemon，或在项目根手动knowcode serve .。 - 在 Harness 中让智能体调用
code_get_symbol_definition_and_signature、code_analyze_refactor_blast_radius等工具；修改共享 API 前优先跑爆炸半径与受影响测试类工具。 - 对照 ADR/PRD 时用
spec_find_code_flow_for_feature或knowledge_search_documentation_and_rules。
停止本工作区 daemon：
knowcode stop .
适用场景与注意¶
更适合：中大型单仓或多包仓库、需要 AST 级符号与调用图、重构前要做影响面分析、文档与代码需要双向追溯的 DSH 工作流。
相对局限：README 明确索引层有扩展名白名单与二进制嗅探，不会读取运行中的数据库文件；存储结构知识来自仓库内 schema/SQL 等文本。Windows 原生环境需 WSL2 或 Docker + FALKORDB_URL，见 README 平台说明。
安全与权限：插件与 knowcode 以当前 DSH/终端用户权限运行，会读取工作区源码与文档、写入 .knowcode 并可能启动本地 HTTP 守护进程。安装前请阅读 源码 与 MIT 许可证，在可信仓库上使用；社区目录页星标为 0，不代表质量结论，需自行评估。
结尾¶
经过上面的步骤，你可以把 dsh-knowcode 理解为：在 DSH 智能体与仓库之间加一层本地图数据库，用 AST 与 Cypher 回答「谁调用谁、改哪里会波及测试、文档对应哪条调用链」，而不是只靠字符串搜索。
