前言¶

在 DSH（DeepSeek Harness）里跑 Agent 时，找文件、搜调用点、改代码往往各自调用 ls、cat、sed 或宿主内置工具，缺少统一的检索后端，也缺少带快照、台账和回滚的编辑路径。仓库没有 Git 时，一旦改错更难恢复。dsh-forge 是社区维护者 Asaiuta 发布的工作流类插件，把 fff 的 Rust 检索、Tree-sitter 符号解析和一套容错编辑引擎接到 DSH 工具面，让检索与「施工」走同一套可治理的工具，而不是零散脚本。

这是什么¶

dsh-forge 面向 DSH >=0.2.0-rc.2：全文与模糊检索（fff 预编译动态库）、11 种语言的 AST 符号与 Trace、以及带台账、快照、回滚的编辑与验证。运行时不需要本机安装 cargo / rustc；符号解析走 WASM，可选 Rust sidecar（rust_indexer/）加速扫描与 Trace。

• 维护者：Asaiuta
• 版本状态：v0.1.0，尚未发布到 npm，需按源码安装
• 许可证：MIT
• 目录页：https://www.skillhub.cn/plugins/Asaiuta/dsh-forge
• 源码：https://github.com/Asaiuta/dsh-forge

SkillHub 等社区目录与 DeepSeek / 幻方无官方从属关系；插件以当前 DSH 进程权限访问工作区与 ~/.dsh/forge，安装前请阅读源码与 LICENSE。

架构概览¶

不启用 sidecar 时全部工具仍可用，符号与 Trace 查询会走 WASM。启用 sidecar 需在 checkout 内用 Rust 1.88+ 执行 pnpm run build:indexer，产物位于 rust_indexer/bin。

核心功能¶

工具面：retrieval 与 full¶

默认只注册 retrieval 三个工具；在 profile 的 patch 里把 surface 设为 full 后，额外注册编辑、台账、文件操作与 Trace 等，共 10 个 canonical 工具（与 retrieval 合计为 README 所述「retrieval 3 / full 10」）。

只注册新公开名，无运行时旧名 alias。内置 read / grep / glob 仍保留原 schema；forge 在分发层增强，例如 read 支持 file_path=<文件>#<符号> 只读定义窗口。

AST 支持：JavaScript、TypeScript（含 TSX/MTS/CTS）、Python（含 PYI）、Rust、Go、C、C++、Java、C#、Lua。

数据与边界（节选）¶

快照与批次在 ~/.dsh/forge/snapshots/，票据在 tickets/，验证在 verification/；无 Git 也可回滚，整目录可删后由下次调用重建。单文件 AST 超过 2 MiB 会降级并提示改用 ff_grep。ff_find 在 Everything 索引命中时可返回带尾部 / 的目录；走 fff 模糊回退时只返回文件。

安装与启用¶

前置要求¶

• Node ^22.19 || >=24
• 已安装 DSH，版本 >=0.2.0-rc.2 且 <0.3.0
• pnpm

插件未上 npm，需从 GitHub checkout 后 link 到 profile。

步骤¶

1. 克隆并安装依赖（prepare 会构建 lib/）：

git clone https://github.com/Asaiuta/dsh-forge.git
cd dsh-forge
pnpm install

2. 编辑 ~/.dsh/profiles/desktop/package.json，在 dependencies 中 link 本地路径：

{
  "dependencies": {
    "dsh-forge": "link:<dsh-forge 的本地绝对路径>"
  }
}

3. 在同文件的 dsh.profile.bundles 中登记 bundle 名 dsh-forge：

{
  "dsh": {
    "profile": {
      "bundles": ["...", "dsh-forge"]
    }
  }
}

4. 安装依赖并重启 DSH：

pnpm -C ~/.dsh/profiles/desktop install

重启后可在宿主中使用 /forge-status 查看当前生效状态（含内置工具增强与交回内置的统计）。

启用完整工具面¶

开箱默认 surface: retrieval。需要编辑与回滚时，在用户 patch 中配置：

# ~/.dsh/profiles/<profile>/cordis.patch.yml
- id: dsh-forge
  name: dsh-forge
  config:
    surface: full

也可在 设置 → DSH-Forge 或 插件 → dsh-forge → 配置 中切换同一 surface 控件；保存写入当前 profile 的 cordis.patch.yml 并重载 bundle，无需重启应用（修改插件源码仍需 pnpm run build 后由宿主重载）。

常用环境变量（可选）¶

完整列表见仓库 README「配置」一节。

典型用法¶

下面步骤假设已启用 full surface，且 Agent 已挂载 forge 工具。

模糊找文件（拼写不确定）：

• 使用 ff_find，路径 glob 仍用内置 glob。

搜调用点或配置名：

• 不确定的文本或多关键字 OR 用 ff_grep；明确正则用内置 grep。

读单个函数定义（不必整文件 read）：

• 内置 read，参数形如 file_path=src/store.ts#Store.save。

带审计的修改：

• ff_edit 完成编辑；需要时用 ff_verify 单独验证（不新建批次）。
• 符号编辑参数包括 sourceSymbol、includeLeadingComment 等，详见接口迁移文档。

出错或需要对比历史：

• ff_history 查批次与 diff；ff_rollback 先预览再按批次恢复（可用 latest:true 或 throughBatch）。

静态依赖与影响：

• ff_trace；符号定义仍用 ff_symbols 或 read#Symbol，不要给 trace 传 symbol:。

安装 dsh-better-sidebar 时，侧栏「台账」与 ff_history 同源数据；HTTP 路由包括 GET /forge-ledger、/forge-config、/forge-projects（headless profile 无 webServer 时没有设置页，主插件仍加载）。

适用场景与注意¶

适合：希望在 DSH 里统一检索后端、用符号级 read/edit、并在无 Git 仓库仍保留快照与回滚的 Agent 工作流；Windows 上需要 Everything 加速文件名检索时可配置 FORGE_GLOBAL_INDEX。

注意：

• 插件以 DSH 进程权限读写工作区与 ~/.dsh/forge，安装前审查源码与 MIT 许可证。
• M0/M1 实现已在当前源码中，README 写明真实 DSH 集成验收仍依赖具备宿主模块的环境；M2 及之后在路线图中。
• grep 增强不走内容索引，是为保持 BOM、二进制与正则语义与内置一致；/forge-status 可核对 Rust 搜索是否接管。
• 社区目录星标与 npm 发布状态以仓库为准；当前为源码 link 安装，无 dsh plugin add 一类一键命令出现在官方 README 中。

结尾¶

dsh-forge 把 fff 检索、Tree-sitter 符号和带台账的编辑收进 DSH 工具面，默认轻量 retrieval，按需切到 full 做 Trace、验证与回滚。若要跟进接口变更与路线图，以 GitHub 仓库 README 与 docs/ 为准。

• 目录页：https://www.skillhub.cn/plugins/Asaiuta/dsh-forge
• 源码：https://github.com/Asaiuta/dsh-forge