huuthuan-nguyen/dsh-knowcode

⚡ DSH-KnowCode：面向 DeepSeek Harness 的统一代码图谱与知识库

npm version
GitHub release
License: MIT
DeepSeek Harness plugin
topic: dsh-plugin

面向 DeepSeek Harness 智能体的最强大代码库导航、重构与知识智能插件。
将 AST 符号图谱与 Markdown 知识库的精华融合进一个内嵌的 FalkorDB Cypher 图数据库，并配备 tgrep 风格的客户端-服务器守护进程与增量文件监视器。

🌟 为什么选择 DSH-KnowCode？

传统 AI 智能体搜索工具依赖朴素的词法搜索（grep）或扁平的 SQLite FTS 表，缺乏语义图谱感知能力。在处理大型代码库（>10 万行代码、monorepo、多包架构）时，智能体常常会：
- 幻觉出函数/方法签名或调用参数。
- 在重命名或修改共享符号时遗漏传递性连锁影响（高回归风险）。
- 在模块之间引入循环依赖。
- 忘记运行或更新受影响的测试套件。
- 由于隐藏依赖而难以将复杂模块移植到另一种编程语言。

DSH-KnowCode 通过统一以下内容来解决这些问题：
1. 代码图谱：经 AST 解析的符号（类、函数、方法、接口、类型）、导入树、调用层级、继承关系以及测试关系。
2. 知识图谱：架构决策记录（ADR）、README、设计文档以及编码规范。
3. 跨实体链接：文档与代码符号之间自动建立双向边（(:DocSection)-[:DOCUMENTS]->(:Symbol) 和 (:Rule)-[:GOVERNS]->(:File)）。
4. 内嵌 FalkorDB 引擎：高性能稀疏矩阵 GraphBLAS 引擎，可在亚毫秒级执行 Cypher 查询，无需 Docker 或云依赖。
5. tgrep 风格架构：一次性索引器（knowcode index .）与持久化守护进程（knowcode serve），并配备防抖增量文件监视器。

🚀 核心亮点与对比

| 功能 | dsh-tool-codegraph | dsh-knowledge-base | dsh-knowcode |
|---|---|---|---|
| 数据库 | 外部 C 二进制文件 | SQLite FTS5 | 内嵌 FalkorDB（Cypher 图） |
| 代码 AST 图谱 | ✅ 是 | ❌ 否 | ✅ 是（多语言） |
| 知识 / 文档 | ❌ 否 | ✅ 文档 | ✅ 统一（ADR + 文档 + 规则） |
| 跨链接 | ❌ 否 | ❌ 否 | ✅ 文档链接到代码符号 |
| 重构影响范围 | 基础深度 | ❌ 无 | ✅ 传递性风险评分 + 测试映射 |
| 循环依赖检查 | ❌ 无 | ❌ 无 | ✅ 图循环检测（DAG 审计） |
| 语言移植契约 | ❌ 无 | ❌ 无 | ✅ API 契约与依赖蓝图 |
| 客户端-服务器架构 | 每次调用 CLI 子进程 | 无头 / 进程内 | ✅ Microsoft tgrep 风格守护进程 + 监视器 |
| 增量重新索引 | 需要陈旧同步 | 导入时更新插入 | ✅ 实时防抖文件监视器 + SHA 哈希 |

📦 安装与快速开始

前置条件

| 要求 | 说明 |
|---|---|
| Node.js ^22.19.0 \|\| >=24.0.0 | 与 DeepSeek Harness 要求的范围相同。 |
| pnpm | 仅用于开发工作流（pnpm run build、pnpm run test）。 |
| Git LFS | 仅在从克隆仓库安装时需要——该仓库通过 LFS 存储内嵌的 FalkorDB 二进制文件。从 npm 安装的包已包含真实二进制文件，无需额外操作。参见下文平台支持与执行指南。 |

knowcode 命令从何而来？

无需下载单独的二进制文件。knowcode 是本包内附带的 CLI 入口点，并在其 package.json 中声明：

"bin": { "knowcode": "./bin/knowcode.js" }

每当该包被安装或链接时，npm/pnpm 都会将该文件作为 knowcode 符号链接暴露在 node_modules/.bin/ 中。该文件本身是一个普通的 Node.js 脚本（#!/usr/bin/env node），因此只要安装了运行时依赖，它就能在任何地方运行。

请根据你的情况选择以下任一选项。

选项 1 — 从克隆仓库运行（无需安装步骤）

git clone git@github.com:huuthuan-nguyen/dsh-knowcode.git
cd dsh-knowcode
pnpm install            # 运行时依赖：commander、falkordb、chokidar、fast-glob、ignore
./bin/knowcode.js index .

如果你更倾向于显式调用，node bin/knowcode.js index . 的行为完全相同。编译后的 lib/ 目录已提交，因此无需构建。

编辑 src/ 下的任何内容后，使用 CLI 前请重新构建——bin/knowcode.js 以及整个 CLI 都从 ../lib/ 导入：
pnpm run build

选项 2 — 使用 npm link 获得全局 knowcode 命令

最适合本地开发，这样 knowcode 可以在任何目录下使用：

cd dsh-knowcode
pnpm install && pnpm run build
npm link
knowcode index .

npm link 会读取 bin 字段，并将 knowcode 符号链接到全局 bin 目录（可通过 npm prefix -g 查看）。要撤销该操作：

npm unlink -g dsh-knowcode

选项 3 — 安装到 DeepSeek Harness 配置文件

一步将已发布的包安装到 ~/.dsh/profiles//node_modules/ 并向 harness 注册：

dsh plugin add --profile web dsh-knowcode

CLI 在该配置文件内也可用：

~/.dsh/profiles/web/node_modules/.bin/knowcode index .
正在开发插件本身？那就把 profile 指向你的检出目录，这样测试框架就会加载你的构建：

dsh plugin add --profile web link:/absolute/path/to/dsh-knowcode

更倾向于手动配置 profile？使用下方 DeepSeek Harness Plugin Setup 中展示的 bundle patch，然后重启测试框架。

选项 4 — 从 npm 安装

已作为 dsh-knowcode 发布在公共 registry 上，因此无需克隆：

Try it without installing anything
npx dsh-knowcode index .
npx dsh-knowcode serve .

…or install the CLI globally
npm install -g dsh-knowcode
knowcode index .

…or add it to a project
pnpm add dsh-knowcode
pnpm exec knowcode index .

该包为 macOS（Apple Silicon）和 Linux x64 捆绑了嵌入式 FalkorDB 引擎——压缩后约 35 MB，安装后 92.8 MB。在没有捆绑二进制文件的平台上，请将 FALKORDB_URL 指向外部实例；参见下方 Platform Support & Execution Guide。

验证安装

knowcode --version     # prints the package version
knowcode --help        # lists: index, serve, status, query, stop

然后为你的仓库构建图谱并启动守护进程：

knowcode index .                # one-shot index of code + docs
knowcode serve .                # background daemon + live file watcher
knowcode serve . --trace        # …with tgrep-style [trace] diagnostics
knowcode status .               # health, file counts and daemon state

完整命令参考见下方 CLI Usage 部分，各操作系统的说明（包括 Windows/WSL2 和 Linux ARM64）见 Platform Support & Execution Guide。

🧰 25 个 Agent 工具

每个工具都为在大型代码库上进行 LLM 函数调用和语义意图匹配 而精心设计：

🧭 1. 架构探索与定位
- code_get_architecture_overview （别名：code_explore）
- 用途：主要的定位工具。查询 FalkorDB 代码图谱，返回顶层入口点（0 个内部调用者的导出符号）、中心枢纽符号（按传入调用入度 / PageRank 排名）以及语言分布，而不会用原始代码淹没 LLM 的上下文窗口。
- 何时使用：在接手新任务或探索不熟悉的子系统时的第一步。

- code_get_symbol_definition_and_signature （别名：code_symbol_definition）
- 用途：检索任何函数、方法、类、结构体或接口的精确 AST 定义、完整类型签名、参数列表、返回类型、docstring、文件路径以及起始/结束行号。
- 何时使用：在实现或接口一致性检查期间，消除签名幻觉和参数猜测。

💥 2. 安全重构与影响分析
- code_analyze_refactor_blast_radius （别名：code_blast_radius）
- 用途：关键安全重构工具。执行最多 $N$ 跳的传递图遍历，以发现所有间接调用者，计算定量风险评估分数（低/中/高/严重），识别所有受影响的文件，并列出覆盖受影响路径的自动化测试文件。
- 何时使用：在修改、重命名或删除任何共享函数、类方法或导出的 API 之前，务必运行。

- code_find_function_callers （别名：code_callers、code_function_callers）
- 用途：在整个代码库中查找调用特定函数或类方法的所有直接调用点。返回调用者名称、限定调用者标识符、文件路径和准确行号。
- 何时使用：在修改函数参数、参数顺序或返回类型时，更新每个调用点。

- code_find_function_callees （别名：code_callees、code_function_callees）
- 用途：查找由特定函数或方法直接调用的所有子例程、辅助函数和方法（向下执行轨迹）。
- 何时使用：在修改函数之前，检查依赖项、子调用和错误检查分支，以理解实现逻辑和前置条件。

- code_detect_circular_dependencies （别名：code_detect_cycles）
- 用途：使用 FalkorDB 循环遍历检测文件、包和模块之间的循环导入或调用依赖循环。
- 何时使用：将单体代码库模块化、打破紧耦合，或为语言移植做准备（例如 Go 和 Rust 严格禁止循环包导入）。

- code_find_affected_test_files （别名：code_affected_tests）
- 用途：发现覆盖或导入指定源文件的所有自动化单元测试和集成测试文件。同时使用图导入依赖关系和命名约定（.test.ts、_test.go、test_.py）。
- 何时使用：在完成代码编辑或错误修复后，验证零回归。

- code_find_similar_duplicate_functions （别名：code_find_duplicates、code_code_clones）*
- 用途：语义与结构代码克隆猎手。使用规范化 AST 令牌流指纹识别，检测代码库中的重复或近似重复函数（Type-1 精确克隆和 Type-2 变量重命名克隆）。揭示逻辑和控制流相同但变量名不同的复制粘贴“脏代码”，并提出统一抽象以消除技术债务。
- 何时使用：代码库去重、技术债务清理和重构共享子例程。

🔄 3. 跨语言与范式移植
- code_extract_symbol_porting_contract （别名：code_porting_contract）
- 用途：跨语言移植加速器。提取类、结构体或模块的完整语言无关接口蓝图：导出的签名、成员字段、包含的方法、外部被调用方依赖项、主导的 ADR 架构规则和测试套件。
- 何时使用：将代码从一种语言移植到另一种语言（例如，从 Python 到 Go、从 TypeScript 到 Rust），并保持 100% 的语义保真度。

- code_generate_cross_paradigm_porting_blueprint （别名：code_oop_to_rust、code_port_to_rust）
- 用途：面向对象到 Rust/Go 的专用加速器。将复杂的 OOP 类继承层次结构扁平化为 trait 和 struct，将运行时异常（throws Exception）转换为符合惯用法的代数式 Result 类型，并提供明确的借用检查器所有权指南（避免循环 Rc/RefCell 陷阱）。
- 何时使用：将 Java/C#/C++ 面向对象模块移植到 Rust 或 Go。

- code_extract_third_party_usage_slice （别名：code_library_slice、code_slim_polyfill）
- 用途：零依赖精简 polyfill 加速器。识别代码库实际调用的第三方库的确切子集。消除 95% 未使用的库表面，并输出最小功能规范和方法契约，使 AI Agent 或开发者能够从零开始在目标语言中重新实现必要功能，而无需臃肿的外部依赖。
- 何时使用：当目标语言缺少等效的第三方库时迁移代码。

📚 4. 双向规范 🔁 代码可追溯性与知识
- spec_find_code_flow_for_feature （别名：spec_to_code_flow、feature_code_flow、code_feature_flow）
- 用途：双向可追溯性（规范 ➔ 代码流）。发现代码库中实现 .md 文档、PRD 或架构规范中指定功能的所有函数、类和下游调用流。从入口点遍历到叶子服务的执行流，并生成 ASCII / Mermaid 执行图。
- 何时使用：熟悉某项功能、验证 .md 中的规范是否已在代码中完全实现，或定位用户故事的完整执行路径。

- code_find_spec_features_for_symbol （别名：code_to_spec_features、symbol_feature_specs、feature_for_symbol）
- 用途：双向可追溯性（代码 ➔ 功能规范）。识别特定函数、方法或类所属或所服务的所有功能、.md 中的规范、PRD 部分和架构规则。追踪直接文档链接和上游调用方执行路径。
- 何时使用：在重构或删除某段代码之前，回答“这个函数为什么存在？哪些业务功能或规范依赖这个类？”

- knowledge_search_documentation_and_rules （别名：knowledge_search）*
- 用途：在项目文档、架构决策记录（ADR）、规范和编码标准中进行搜索。返回带有优先级（MUST / SHOULD / AVOID）的匹配章节，并自动交叉链接到图中相关的代码符号。
- 何时使用：在引入新抽象之前，检查现有的架构模式或需求。
- knowledge_get_document_content_and_rules (别名：knowledge_doc)
- 用途：检索特定文档文件或 ADR 标题的完整内容、标题层级结构和架构规则。
- 何时使用：在重构现有代码模式之前，理解为何做出某项架构决策（即“为什么”）。

🗄️ 5. 多语言契约与存储可追溯性
- schema_map_contract_to_storage (别名：schema_map_contract、contract_to_db、map_contract_to_storage)
- 用途：多语言契约到存储的对齐。将任何外部数据契约（XML XSD、JSON OpenAPI/Swagger、gRPC Protobuf）映射到跨 7 个数据库系列（SQL、MongoDB、Redis、Elasticsearch、Vector DB、TSDB、Graph DB）的多语言存储后端。生成字段级映射矩阵，检测类型差异（例如数值溢出、BSON ObjectId 与 UUID、稠密向量维度），并标记未映射/孤立的属性。
- 何时使用：验证从 API 契约到存储的端到端数据血缘，发现未持久化的字段，或验证跨微服务边界的类型安全性。

- schema_analyze_storage_migration_impact (别名：schema_migration_impact、db_migration_blast_radius)
- 用途：多语言存储迁移爆炸半径。分析在 SQL 表、MongoDB 集合、Elasticsearch 索引或 Vector DB 集合中更改、删除或重命名属性所带来的破坏性影响。检测所有受影响的外部契约（XML/JSON/gRPC）、应用程序 DAO/查询以及映射的测试套件。
- 何时使用：执行模式迁移、数据库重构或删除列时，以防止破坏移动端/Web 客户端或合作伙伴集成。

🔍 6. 高级调用路径、架构与搜索
- code_find_call_path_between_symbols (别名：code_call_path、code_trace_call_path)
- 用途：在整个代码库图（最多 12 跳）中追踪两个函数或方法之间的最短调用路径。追踪从入口点到下游服务的多跳执行流，帮助验证架构分层、安全边界和数据流路径。
- 何时使用：验证某个 API 路由是否到达关键的下游函数（例如 chargePayment 或 deleteUser），并观察所有中间经过点。

- code_find_implementations_and_subtypes (别名：code_subtypes、code_implementations)
- 用途：查找所有扩展或实现给定接口、抽象类或基类的子类、结构体和类。
- 何时使用：探索多态、实现依赖注入绑定，或为单元测试编写模拟实现。

- code_search_symbols_by_pattern (别名：code_search_symbols)
- 用途：按名称模式、不区分大小写的子字符串或关键字在代码库中搜索符号。
- 何时使用：当你只记得部分关键词（例如“Token”、“Auth”、“Payment”）时，用于发现精确的限定符号名称。

- code_find_unused_dead_symbols （别名：code_dead_code、code_unused_symbols）
- 用途：识别代码库图中入站调用为 0 的未被引用的内部/私有符号。
- 何时使用：执行技术债务清理并安全地修剪过时的死代码。

- code_analyze_git_diff_semantic_impact （别名：code_git_diff_impact、code_audit_git_diff）
- 用途：一键回归审计。分析未提交的 git 工作区变更（或相对于基线提交/分支的变更），将变更行范围映射到 AST 符号，计算存在风险的传递调用方，并识别在提交或创建 PR 之前应运行的所有自动化测试套件。
- 何时使用：在结束编码任务前进行提交前安全检查，以验证零回归。

⚡ 7. 诊断与高级查询
- knowcode_check_index_health_and_stats （别名：knowcode_status）
- 用途：检查图健康状况、已索引文件/符号/调用/文档的数量、守护进程新鲜度以及内存统计信息。
- 何时使用：每个会话运行一次，以确认索引新鲜度。

- knowcode_trigger_incremental_reindex （别名：knowcode_sync）
- 用途：按需触发对整个工作区中任何已修改或新增文件的增量重新索引。
- 何时使用：在进行大批量编辑后，使图与磁盘同步。

- knowcode_execute_custom_cypher_query （别名：knowcode_cypher）
- 用途：针对 FalkorDB 的直接 Cypher 查询逃生通道。
- 何时使用：高级多跳图查询（例如，查找实现接口 X 但不调用方法 Y 的类）。

🛠 CLI 用法（Microsoft tgrep 风格）

dsh-knowcode 附带 knowcode 可执行 CLI，用于终端使用和 CI/CD 流水线。

还不确定你是否已经有 knowcode 命令？ 它不是单独下载的——获取它的四种方式请参见上文的 安装与快速开始。快速检查：knowcode --version。

在本节中，当从克隆仓库运行时，knowcode … 始终可以替换为 ./bin/knowcode.js …。

我需要哪个命令？

serve 会自行索引工作区——index 是可选的。 无需在 serve 之前先索引。

在启动时，并且在宣布就绪之前，serve 会将图与文件系统进行协调：

| 工作区状态 | serve 会做什么 |
|---|---|
| 从未索引 | 遍历工作区并索引所有内容——Index stale: N added, 0 changed, 0 deleted. Re-indexing... |
| 索引已是最新 | Index is up-to-date (N files checked)——得益于修改时间快速路径，不会读取任何文件 |
| 文件已添加、更改或删除 | 仅重新索引这些文件 |
| --force-index | 忽略过期检查，重新解析所有内容 |
两条路径构建的是同一个图，包括 TESTS_FOR 和 DOCUMENTS 链接，因此提供一个新的工作区并对其进行索引会产生相同的结果。

| 你想要… | 使用 |
|---|---|
| 直接使用它 | serve —— 或者让插件的 autoStartDaemon 为你启动一个 |
| 在 CI 中索引一次而不留下进程 | index（它会启动一个守护进程、进行索引，然后停止它） |
| 预热，这样第一次工具调用就不会花时间等待 | index 然后 serve —— serve 会复用结果 |
| 重建一个你怀疑已过时或错误的图 | serve --force-index |

⚠️ 过时检查比较的是文件内容哈希，因此它无法判断现有图是由旧版解析器构建的。升级后，请使用 --force-index（或删除 /falkordb.rdb）—— 否则会信任之前的图。

1. 一次性索引（knowcode index）
将代码库及其文档索引到嵌入式 FalkorDB 数据库中。如果你打算 serve，则不需要这样做 —— 它会自行索引：
索引当前目录
knowcode index .

使用自定义数据目录索引特定目录
knowcode index ./my-repo --data-dir .knowcode

2. 带实时监视器的后台守护进程（knowcode serve）
启动服务器守护进程，加载嵌入式 FalkorDB，如果工作区尚未索引则对其进行索引，监视更改，并实时增量重新索引文件。无需先运行 index：
knowcode serve .
- 监听 http://127.0.0.1:48123。
- 文件修改会触发防抖的 SHA-256 差异比较和即时增量图更新。
- DeepSeek Harness 工具通过 HTTP/IPC 连接，实现 ** trace.log   # 将跟踪信息保存到单独的文件中

示例输出：

[trace] db: embedded FalkorDB opened (dir=/repo/.knowcode) in 42.6ms
[trace] schema: indexes ensured in 4.2ms
[trace] opened index: 148 files, 1240 symbols, 3892 calls, 18 docs
[trace] serve ready in 52.7ms. HTTP on port 48123. Graph: 1240 symbols / 3892 calls / 18 docs / 64 sections. Data dir: /repo/.knowcode.
[trace] refresh mode: auto, debounce=300ms, awaitWriteFinish=200ms
[trace] watch: ignore matcher ready (node_modules, .git, .knowcode, dist, lib, build, .next, bin)
[trace] watch: worker started (workspace=/repo, engine=chokidar, awaitWriteFinish=200ms, debounce=300ms)
[trace] stale check: comparing index against filesystem...
[trace] ignore matcher built from stale walk in 6.2ms (148 candidate files)
[trace] stale check: index is up-to-date (148 files checked in 8.8ms)
[trace] rpc: action=search_symbols elapsed=1.4ms result=1
[trace] search: pattern="VpbankEvent" case_insensitive=true raw_candidates=5 candidates=5 matches=19 elapsed=1.4ms
[trace] watch: batch 1 change(s), 0 deletion(s)
[trace] watch: update src/report.ts in 12.5ms (symbols=2)
[trace] watch: incremental reindex complete: 1 file(s) in 14.6ms (relink=1.6ms, skipped=0, removed=0)

跟踪信息告诉了你什么

| 行 | 含义 |
|---|---|
| opened index: | 启动时从嵌入式 FalkorDB 数据库加载的图内容。 |
| serve ready in … | 总启动延迟、HTTP 端口以及最终的图大小。 |
| refresh mode: / watch: | 监视器配置、忽略规则以及引擎。 |
| stale check: | 启动时与文件系统的对账——当索引已经是最新时，serve 会完全跳过重新解析。 |
| rpc: | 每次到达守护进程的工具调用一行，包含操作、延迟和结果大小。 |
| search: | 详细的 search_symbols 指标：模式、限制前的 raw_candidates、candidates、matches 以及耗时。 |
| watch: batch / update / incremental reindex complete | 由防抖监视器捕获的实时编辑，包含每个文件和重新链接的耗时。 |

跟踪是选择性启用的，禁用时零开销——热路径会在构建任何字符串之前通过一个布尔值短路。

要绕过陈旧检查并始终强制进行完整重新索引：bash
knowcode serve . --force-index

如果 --trace 关闭，knowcode serve . 的输出与普通运行相比没有变化。

💻 平台支持与执行指南

dsh-knowcode 旨在所有主流操作系统和 CPU 架构上顺畅运行：

⚠️ 必需：克隆前安装 Git LFS
嵌入式 FalkorDB 二进制文件（.so、.dylib、redis-server）通过 Git LFS 存储，以保持 git 历史记录较小。
如果你在未安装 Git LFS 的情况下克隆，这些文件只是文本指针文件（约 130 字节），数据库将无法启动。
bash
macOS
brew install git-lfs
Ubuntu / Debian / WSL2
sudo apt-get install -y git-lfs
Windows (PowerShell)
winget install GitHub.GitLFS

git lfs install        # 每台机器需要执行一次
git clone git@github.com:huuthuan-nguyen/dsh-knowcode.git
已经克隆但缺少二进制文件？ 只需重新拉取它们：
bash
git lfs install && git lfs pull
快速检查：file bin/linux-x64/falkordb.so 必须报告 ELF 64-bit ... shared object。
如果它报告 ASCII text，说明 LFS 对象尚未被拉取。

| 平台（操作系统与架构） | bin/ 中的状态 | 执行路径 | 设置说明 |
|---|:---:|---|---|
| 🍏 macOS Apple Silicon（darwin-arm64 M1/M2/M3/M4） | ✅ 已捆绑 | 原生，100% 嵌入式 | 零配置。附带 redis-server、falkordb.so、libomp。 |
| 🐧 Linux x64（linux-x64 Intel/AMD 64 位） | ✅ 已捆绑 | 原生，100% 嵌入式 | 零配置。附带 redis-server 和 falkordb.so。 |
| 🐧 Linux ARM64（linux-arm64 Graviton、Pi 4/5） | 🔄 Docker / 外部 | Docker 或自定义二进制文件 | 通过 Docker 运行，或将二进制文件放入 bin/linux-arm64/。 |
| 🪟 Windows x64（Intel/AMD） | ⚠️ 需要 WSL2 或 Docker | WSL2（推荐）或 Docker | 在 WSL2 Ubuntu 或 Docker Desktop 中运行。 |
| 🪟 Windows ARM64（Snapdragon Copilot+ PC） | ⚠️ 需要 WSL2 或 Docker | WSL2 ARM64 或 Docker | 在 WSL2 Ubuntu ARM64 或 Docker Desktop 中运行。 |

1. macOS（M1/M2/M3/M4）与 Linux x64
完全自动，零配置：bash
Build and run the test suite
pnpm run build
pnpm run test

Index the workspace
knowcode index .

Start the background daemon
knowcode serve .

2. Linux ARM64（AWS Graviton、Raspberry Pi 4/5）
FalkorDB 发布官方多架构镜像（linux/arm64）：
- 选项 1：通过 Docker 运行（最快）：
bash
docker run -d -p 6379:6379 -v knowcode_data:/data falkordb/falkordb:latest
export FALKORDB_URL=redis://127.0.0.1:6379
knowcode serve .
- 选项 2：使用嵌入式二进制文件：
将 ARM64 的 redis-server 和 falkordb.so 编译或复制到 bin/linux-arm64/。KnowCode 会自动检测它们并完全以嵌入式方式运行——无需 Docker。

3. Windows（Windows x64 与 Windows ARM64 Snapdragon）

技术说明：FalkorDB 是一个用 C/Rust 编写、由 GraphBLAS 支持的 Redis 模块，构建于 POSIX 原语（pthreads、dlopen、sys/mman）之上。Redis 本身在 Redis 3.x 之后放弃了原生 Windows（.exe）移植版，而 FalkorDB 需要 Redis 7.2+ 模块 API。因此 FalkorDB 不提供可直接在 Windows 内核上运行的 .exe。

为了在 Windows 上获得最顺畅的体验，请从以下两个选项中选择一个：

🌟 选项 1：在 WSL2（适用于 Linux 的 Windows 子系统）中运行 — 推荐
WSL2 在 Windows 内提供了一个真正的 Linux 内核，因此你可以获得嵌入式 Linux 二进制文件的完整性能：bash
Inside your WSL2 Ubuntu terminal:
git clone
cd dsh-knowcode
pnpm install
pnpm run build

Run directly (using the bin/linux-x64 or bin/linux-arm64 binaries):
knowcode index .
knowcode serve .

🐳 选项 2：通过 Windows 版 Docker Desktop 运行
如果你希望将 Node 保留在原生 Windows（PowerShell/CMD）上而不使用 WSL2：
1. 打开 PowerShell 并启动 FalkorDB 容器：
powershell
docker run -d -p 6379:6379 -v knowcode_data:/data falkordb/falkordb:latest
2. 将环境变量指向该容器：
powershell
$env:FALKORDB_URL="redis://127.0.0.1:6379"
3. 启动 KnowCode 或 DeepSeek Harness：
powershell
knowcode index .

knowcode serve .
KnowCode detects FALKORDB_URL automatically and connects over loopback TCP without loading any local binary.

🔌 DeepSeek Harness Plugin Setup

Method 1: Via Cordis Bundle Patch (Recommended)

In your profile's cordis.patch.yml:yaml
- insert:
- id: knowcode
name: 'dsh-knowcode'
config:
daemonPort: 48123
dataDir: .knowcode
blastRadiusMaxDepth: 3
autoStartDaemon: true

Method 2: Via DSH CLIbash
dsh plugin add --profile web dsh-knowcode

Configuration options

| Option | Default | Description |
|---|---|---|
| daemonPort | 48123 | Preferred port for the workspace daemon. If it is taken, the daemon binds the next free port and records it in /daemon.json, so several workspaces can each run their own daemon. |
| dataDir | .knowcode | Directory holding the embedded database and daemon.json. |
| falkordbUrl | (empty) | Connect to an external FalkorDB (e.g. redis://127.0.0.1:6379) instead of the embedded engine. |
| blastRadiusMaxDepth | 3 | Default traversal depth for impact analysis (clamped to 1–10). |
| maxFileSize | 1048576 | Largest file read and indexed, in bytes. Enforced from the file's size before it is read, in both the indexer and the file watcher. Set it with knowcode serve . --max-file-size  when running the CLI by hand. |
| autoStartDaemon | true | Start a daemon automatically when a tool runs in a workspace that has none, instead of replying with a "run knowcode serve ." notice. The daemon is spawned detached from this package's own CLI and its output is appended to /serve.log. Concurrent calls share one start attempt; the first call may wait a few hundred milliseconds. |
| idleTimeoutMinutes | 0 | Stop a daemon after this many minutes without activity. 0 disables it. Any client contact — a tool call, a watcher event — resets the budget. Restarting later is cheap: the database persists and the stale check skips unchanged files. Set it per run with knowcode serve . --idle-timeout . |
| stopDaemonOnExit | true | Stop the daemons this process spawned when the harness exits. Detached daemons outlive a tool call, so without this, quitting DSH would leave one running per project — each holding an embedded FalkorDB process, an HTTP server, a file watcher and a database file. Cleanup runs from the plugin's disposal effect, which DSH triggers on SIGINT (Ctrl+C) and SIGTERM; SIGKILL bypasses disposal and is the one case that still orphans a daemon. Daemons you started yourself with knowcode serve . are never touched. |

Databases are never read

A running database is never contacted, and its files are never opened. Knowledge about storage is derived only from text committed to the repository — see Schema comes from source below.

Three layers enforce this, in order, before any content is read:

1. Extension allowlist. Discovery accepts only code (ts, tsx, js, jsx, mjs, cjs, py, go, rs, java, c, cpp, h, hpp), documentation (md, mdx, markdown, txt) and schema text. Everything else — including every extensionless data file — is out of scope by construction, never by name.
2. Non-text denylist. Database artifacts are named explicitly so the intent is testable and a future allowlist change cannot quietly admit one: SQLite (.db, .db3, .sqlite, .sqlite3 and their -wal/-shm/-journal sidecars), Redis (.rdb, .aof), MySQL/MariaDB (.ibd, .frm, .myd, .myi, .arm), MongoDB/WiredTiger (.wt, .bson, .ns, .turtle), Elasticsearch/Lucene (.cfs, .cfe, .si, .del, .fdt, .fdx, .fnm, .nvd, .nvm, .tim, .tip, .kdd, .kdi, .liv), LevelDB/RocksDB (.sst, .ldb), DuckDB (.duckdb) and archives, media and compiled objects.
3. Binary sniff. The first 512 bytes are checked for a NUL byte, the same heuristic git uses, so a database dumped behind an innocent name is still refused.

All three live in src/server/indexable.ts, shared by discovery, the stale check and the file watcher, so they cannot drift apart. The watcher in particular decides before reading: a SQLite database being written by a running application fires a change on every write, and each one used to be read into memory and hashed before being discarded.

Schema comes from source

Storage knowledge is read only from text in the repository, routed by file type:

| Source | Becomes |
|---|---|
| .sql, .cql migrations and DDL | StorageContainer (SQL) |
| .prisma | StorageContainer, engine taken from the datasource provider |
| Mongoose new Schema({…}) in .ts/.js model files | StorageContainer (MongoDB) |
| .proto | ContractEntity (gRPC) |
| .xsd | ContractEntity (XML) |
| .graphql, .gql | ContractEntity (SDL; Query/Mutation/Subscription skipped) |
| OpenAPI / JSON Schema (openapi.json, .schema.json, openapi.yaml) | ContractEntity |
| Elasticsearch mappings (mapping.json, mappings.properties) | StorageContainer (Elasticsearch) |

JSON and YAML are discovered but accepted only when the file name looks like a schema, so lockfiles and CI configuration are never read. Each file's definitions are replaced on re-index, so a model deleted from a schema disappears from the graph, and a malformed schema is skipped rather than aborting the run.

Workspaces, watchers and resource use

Nothing runs until you use it. The plugin registers its tools when DeepSeek Harness loads and starts no process at all; a daemon appears the first time a KnowCode tool runs in a given workspace.

- One daemon per workspace _you have used_. Workspaces you have not touched hold no daemon, no watcher and no .knowcode directory. Four workspaces in a session, two of them used, means two daemons.
- Watch scope is the session's working directory, recursively. Anything not in the ignored directories is watched, and the initial index covers the whole tree. Running the harness from a parent directory therefore watches every project beneath it — open it in the project itself when that matters.
- The first call in a workspace pays for the index. It is reported on that call: ⚙️ KnowCode daemon auto-started for … — indexed N files, M symbols in T s. That call waits for the index to settle, so the numbers it returns are complete; if the wait exceeds its budget (60s, or indexTimeoutMs for callers) the note says so instead.
- Idle costs almost nothing. The watcher is event-driven on macOS (FSEvents) and only receives changes; the embedded database writes at most once every 60 seconds, and only after a change.
- Nothing is left behind. Daemons the plugin started are stopped when the harness exits (see stopDaemonOnExit), and idleTimeoutMinutes lets an unused workspace stop sooner. SIGKILL skips that cleanup.

One daemon per workspace

Each workspace runs exactly one daemon at a time, guarded by a serve.lock claimed with an exclusive create before anything starts. A second serve for the same workspace exits with a notice instead of starting a rival — two would each run a watcher and an embedded FalkorDB over the same .rdb, and the second would overwrite daemon.json so clients flipped between them. A guard left behind by a crashed daemon is detected by pid and reclaimed, so a dead process never blocks a workspace.

The consequence is one database file per workspace. On startup the daemon also removes any temp-.rdb left by an interrupted background save, so a workspace holds exactly one .rdb.

🧯 Compatibility & Troubleshooting

Zero-dependency by design

dsh-knowcode declares no runtime dependency on any @deepseek-ai/ package. Its compiled output imports nothing but its own relative modules; harness types are pulled in with import type only, which TypeScript erases entirely. Tool definitions are plain objects, parameters and output.schema are standard JSON Schema, and Config is a hand-written Standard Schema v1 validator.

Third-party plugins should not load harness internals at runtime: the contract with the host is exactly the object passed to tools.register(), and a runtime import can add yet another evaluated copy of a package the host already owns.

Cannot read properties of undefined (reading 'prepare')

This is a DeepSeek Harness defect, not a dsh-knowcode defect. It was verified on a profile with zero plugins installed: every tool call (bash, read, grep, …) aborted the turn.

Root cause, in the harness:

- packages/core/agent-loop/src/tool-calls.ts reaches into the tool registry with ctx.tools[TOOL_RUNTIME_SCHEDULER].prepare(call.exec) and never checks the result.
- TOOL_RUNTIME_SCHEDULER is declared with Symbol(...) (packages/core/tools/src/index.ts), not Symbol.for(...), so the key is private to one module instance.
- Harness v0.1.6-alpha.2 changed the default resolutionMode from link to runtime (apps/cli/src/profile-boot.ts). When @deepseek-ai/dsh-tools is reachable through two resolution paths (the workspace copy and the profile install anchor's symlink), Node evaluates it twice, the two symbols differ, the lookup yields undefined, and the cryptic message aborts every tool call.

Workarounds until the harness ships a fix:
bash
1. One-line local harness patch, then rebuild the host libraries:
packages/core/tools/src/index.ts
- export const TOOL_RUNTIME_SCHEDULER: unique symbol = Symbol('@deepseek-ai/dsh-tools.scheduler')
+ export const TOOL_RUNTIME_SCHEDULER: unique symbol = Symbol.for('@deepseek-ai/dsh-tools.scheduler')
pnpm run build:lib:host

2. Or pin a harness release without the changed default:
dsh-v0.1.6-alpha.1

3. Or force the previous resolution mode, if your CLI exposes it:
dsh --help | grep -i resolution

⚠️ That local harness patch is not tracked by the harness repo — lib/ is gitignored there and the source edit stays uncommitted. Running git checkout, git pull, or git stash inside the harness checkout discards it, and the next pnpm run build:lib:host regenerates lib/ with the broken private Symbol(). Keep the patch on a local branch.

Other known failure modes

| Symptom | Cause |
|---|---|
| Provider rejects a tool schema, or the model cannot see a tool's parameters | The tool declared defineTool author shorthand (required: true inside a property) instead of standard JSON Schema — rejected by the registry's assertSupportedJsonSchema |
| A tool result renders an empty card in the Web GUI | A presenter returned a view field outside the declared union — e.g. output on TerminalCallView, which accepts only card, title, description?, cwd? |

How this plugin stays contract-correct

1. No runtime harness imports. Tool definitions are plain objects; verified by a regression test that scans every compiled .js file for harness imports.
2. Standard JSON Schema only. parameters and output.schema use required: [...] arrays of property names. The test suite additionally validates every registered schema with the harness's own assertSupportedJsonSchema.
3. Standard Schema v1 config. Config['~standard'].validate() is implemented by hand, so no @deepseek-ai/schemastery import is needed.
4. Hardened presenters. render/presentResult tolerate a missing value, and presentCall emits only fields the declared view accepts.

If you maintain another DSH plugin and hit the reading 'prepare' error: it is not caused by your plugin, so a source change will not fix it. Apply one of the harness workarounds above. Making your plugin dependency-free is still worthwhile hygiene, but it is not the remedy.

🏗 Safe Refactoring Protocol for Agents

The plugin automatically injects the KnowCode Safe Refactoring Protocol into the agent's system prompt:
mermaid
graph TD
A[Step 1: knowcode_check_index_health_and_stats] --> B[Step 2: code_get_architecture_overview]
B --> C[Step 3: code_get_symbol_definition_and_signature]
C --> D[Step 4: code_analyze_refactor_blast_radius]
D --> E[Step 5: code_find_function_callers]
E --> F[Step 6: code_detect_circular_dependencies]
F --> G[Step 7: Perform Code Modifications]
G --> H[Step 8: code_find_affected_test_files & Verify]

🧪 Testing & Verification

Run the full test suite (built-in Node test runner):bash
pnpm run build
pnpm run test

Runs:
- Multi-language AST parsing (TypeScript, Python, Go, Rust, C++)
- Document parsing, rule extraction, and symbol cross-linking
- Embedded FalkorDB startup, Cypher schema, and graph queries
- Daemon HTTP/JSON RPC server and debounced file watcher
- Cordis plugin registration and system prompt injection
- [trace] logging: daemon startup, index phases, stale check, RPC/search lines
- Tool-schema contract: every tool validated against the harness's own
assertSupportedJsonSchema, plus a guard asserting the compiled output has
zero runtime @deepseek-ai/* imports
- Auto-start contract: the first query in a workspace sees a settled index (verified
against a 300-file fixture, where a partial graph used to answer instead), the
starting call reports what it cost, and a concurrent sync shares the run rather
than failing
- Tool-output contract: every return branch of every action validated against
KNOWCODE_OUTPUT_SCHEMA with the harness's own validateJsonSchemaValue, so an
undeclared field can never reach the harness and fail with INVALID_TOOL_OUTPUT
- Graph integrity: multi-line signatures are indexed, relative imports produce real
:IMPORTS edges (and therefore TESTS_FOR / affected-test links, including
imports of compiled lib/ output that map back to src/), declaration
endLine covers the whole body even when the header contains braces, call
extraction ignores text inside strings and template literals, and Python class
scope does not leak
- Daemon isolation: a second workspace falls back to a free port instead of dying
with EADDRINUSE, a failed start never leaks the embedded FalkorDB process, a
client refuses a daemon that serves a different workspace, a second daemon for
one workspace is refused while a dead one's guard is reclaimed, autoStartDaemon
brings a daemon up on demand, and shutdown stops only the daemons this process
spawned so no knowcode serve is orphaned, and an idle budget lets an unused
workspace stop its daemon on its own
- Index scope: databases, archives and binaries are rejected from the path alone
(including SQLite -wal/-shm/-journal sidecars), and maxFileSize is
enforced before any read instead of being a documented no-op

License

MIT © Thuan Nguyen