Go 版 TS 编译器 hy-sde/dsh-tool-tsfork

[!NOTE]
📦 本插件位于 dsh-plugins monorepo —— 请在那边提 issue 和 pull request。
npm：@hy-sde-org/dsh-tool-tsfork

dsh-tool-tsfork —— 面向 DeepSeek Harness 的 Go 原生 TypeScript 编译器设备

独立包，可作为一个插件安装（内含两个设备工具），服务于 DeepSeek Harness：这些设备面向模型，背后是一个常驻的 Go 原生 TypeScript 编译器 —— can1357/TypeScript 性能分支（perf/checker-speedups-v3，TS 7.1.0-dev）。tsfork_status 报告二进制文件、版本横幅和构建戳；tsfork_check 执行一次性的 -b 项目图检查，返回解析后的诊断信息、实际耗时和 GOMAXPROCS 上限。编译器二进制只构建一次，常驻在主机上；插件只对接 harness 的设备接缝 —— 上游 harness 零改动。

| 标识 | 值 |
| 包 | @hy-sde-org/dsh-tool-tsfork |
| 插件 id | hy-sde-tsfork |
| 设备 | tsfork_status · tsfork_check（通过 dyn 提供的设备目录工具） |

基于 can1357/TypeScript （perf/checker-speedups-v3，microsoft/TypeScript 的 Go 重写版，Apache-2.0 血统）：没有移植或修改任何编译器代码 —— 本包是原创插件代码，每次调用时按稳定的命令行契约（tsc -b，默认输出不含 JSON）启动该二进制。属于适配，而非移植：harness 的设备接缝（通过 ctx.tools + ctx.systemPrompt 提供的 device: true 工具）存在的意义，是让部署能暴露一个快速编译器，而不用碰仓库里锁定的工具链。见 THIRD-PARTY-NOTICES.md。

为什么

大型工作区上的类型门禁，一直是拿原版 tsc -b 跑整个解决方案图 —— 在 fork harness 那台 337 个项目的主机图上，冷启动要 54.25s（CPU 91.6s，峰值内存 4.6GB），每个想做类型检查的智能体都得排队等。Go 编译器检查同一张图，结果逐字节一致（项目列表、14/14 植入错误、输出确定），冷启动只要 7.05s / 热启动约 0.6s —— 实际耗时少 7.7 倍，CPU 少 3.4 倍。但 harness 里没有任何地方能把它暴露出来：门禁走的是锁定 typescript@6.0.3 的 pnpm 脚本，而插件没法替换仓库自己的工具链 —— 也不该替换，因为 oxlint 的 typeAware 和 typert 生成器需要 TS 7（Go 二进制）不提供的 JS API。智能体真正需要的，是一个指向常驻二进制的设备：可按部署加载，切换一行就能卸载，输出结构化，不用折腾 PATH，不动上游 —— 同时锁定的工具链保持原样。

前置条件

- Node.js 22.19 或更新（包的 engines 下限），且 PATH 上有 pnpm；
- 一套带设备目录的 DeepSeek Harness 安装（包的 peer 基线是 @deepseek-ai/cordis ~4.0.5-alpha.1、 @deepseek-ai/dsh-tools / @deepseek-ai/dsh-system-prompt ^0.2.1-alpha.2；没有设备概念的注册表会直接提前呈现工具）；
- 主机上放一个 tsfork 编译器二进制（默认 ~/.dsh/tsfork/tsc），旁边配一个 VERSION 标记 —— 从 fork 的检出里构建一次：

git clone https://github.com/can1357/TypeScript.ts.git typescript.ts # or your fork
cd typescript.ts && git checkout perf/checker-speedups-v3
go build -o ~/.dsh/tsfork/tsc ./cmd/tsc # inside the tsc/ dir of the checkout
printf 'source: can1357/TypeScript perf/checker-speedups-v3 @ <commit>\n' > ~/.dsh/tsfork/VERSION

（Go 源码树自带生成文件 —— 无需 generate 步骤；Go 1.27+）

快速开始

路线 A —— 已发布的 npm 包（推荐）

dsh plugin --profile web add @hy-sde-org/dsh-tool-tsfork

等 Shape-A 试用之后再发布 —— 在那之前走路线 B。

路线 B —— 从源码（验证这份检出，或在插件上折腾）

git clone git@github.com:hy-sde/dsh-plugins.git
cd dsh-plugins/dsh-tool-tsfork/packages/tool-tsfork
pnpm install
PACKAGE_TARBALL="$(pnpm pack | tail -n 1)"
dsh plugin --profile web add "$PWD/$PACKAGE_TARBALL"
cd ../../../..

试用时用的部署变体（PATH 上没有 dsh 命令行，配置档手工管理）：用绝对 file: 路径把构建好的包链接进配置档 —— 在配置档目录里执行 pnpm add file:<abs-path-to-package>，再把 @hy-sde-org/dsh-tool-tsfork 加到 dsh.profile.bundles。包自己的 dsh.bundle.patch 会挂载 hy-sde-tsfork 行。

验证合成后的配置

dsh web --dump-config

运行

启动 harness（dsh web），让智能体检查或探测某个图。
面向模型的调用（设备目录 —— dyn search tsfork）：

- tsfork_status（无参数）—— 解析出的二进制、Version 7.1.0-dev 横幅、来自 <binaryDir>/VERSION 的构建标记、20s 健康探测。
- tsfork_check —— tsc -b <project>；返回 exitCode、wallMs、 errorCount/warningCount、解析后的 diagnostics（file:line:col TSxxxx）、 outputTail，以及可复现的 command。dry: true 会在前面加上 --dry（列出一次构建会跑哪些项目，但不真正构建）。在部署默认检出之外，要显式传入 cwd（以及 project）。

卸载

dsh plugin --profile web remove @hy-sde-org/dsh-tool-tsfork

这个 bundle 做什么

插件的 cordis.patch.yml 挂载一行普通的 agent-plane 行 （hy-sde-tsfork），它消费部署的主机服务 —— tools 和 systemPrompt（标准 agent bundle 两者都提供）。它没有自己的服务、领域或文件系统接缝：每次调用都启动一次停放的编译器，所以并发的智能体通道天然隔离，唯一共享的机器旋钮是 GOMAXPROCS。它还注册了 tsfork:tools 提示词区段，每个挂载该设备的会话都会看到这段文档，其中记录了 buildinfo 的坑与接入边界。

引擎行为

- 一次性启动，stdin 关闭。 每次调用都是 spawn(binary, argv)，配 stdio: ['ignore', 'pipe', 'pipe'] —— 编译器从不读 stdin，而管道一直开着正是命令行包装器卡死的经典原因。
- 参数顺序。 Go 解析器要求 -b/--build 排在项目路径前面；项目路径之后的参数（--dry 等）可以接受。只写 tsc <tsconfig>（不带 -b）会报 TS5112 —— 插件始终把 -b 放在最前。
- 超时语义。 到 timeoutMs 发 SIGTERM，再过 5s 发 SIGKILL —— 升级动作由超时触发，绝不在 spawn 时安排。超时的运行以 timedOut: true 加部分输出 resolve，而不是 reject。
- 输出上限。 stdout/stderr 各自最多捕获 maxOutputBytes（默认 4 MiB，超出时标记 outputTruncated）；诊断信息上限 500 条，超出后仍保留精确计数（diagnosticsTruncated）。
- .tsbuildinfo 带编译器版本标记。 交替使用 tsfork_check 和仓库自带的 tsc -b，会让另一方的增量缓存失效 —— 运行转冷。提示词段落会提醒智能体；选一个主力，接受另一方付一次冷启动的代价。
- 接入边界。 tsfork 不替换固定的 typescript@6.0.3 工具链：oxlint 的 typeAware 和 typert 需要 JS API（TS 7 的 npm 包只是个启动壳，没有 lib/typescript.js）。如果试用验证通过，正式启用应该是用 pnpm override 替换门禁二进制 —— 而不是这个插件。

配置

| 选项 | 默认值 | 用途 |
| binary | ~/.dsh/tsfork/tsc | 编译器二进制（~ 可展开），必须可执行 |
| defaultProject | — | 调用未提供 project 时使用的 -b 项目 |
| defaultCwd | — | 调用未提供 cwd 时使用的工作目录 |
| timeoutMs | 900000 | 每次调用的进程超时 |
| gomaxprocs | — | 写入子进程环境的 GOMAXPROCS（便于按 lane 限制并行度） |
| maxOutputBytes | 4000000 | 每侧捕获的 stdout/stderr 字节上限 |

- id: hy-sde-tsfork
config:
binary: ~/.dsh/tsfork/tsc
defaultProject: tsconfig.host.json
defaultCwd: /path/to/your/checkout
timeoutMs: 900000
gomaxprocs: 4

错误

| 代码 | 含义 |
| binary_missing | 解析出的 binary 路径上没有文件 |
| binary_not_executable | 文件存在，但没有执行位 |
| project_missing | 解析出的项目路径上没有 tsconfig（目录内也没有 tsconfig.json） |
| spawn_failed | 操作系统拒绝 spawn（ENOENT、EACCES）—— 消息里带 errno |
| timeout / timedOut: true | 运行超过 timeoutMs；返回部分输出，不丢弃 |

编译器诊断本身不算插件的错误 —— 检查失败是合法结果（ok: false、exitCode 1/2、解析出的诊断信息）。

隐私与安全说明

- 无网络。 插件只启动本地二进制，不向主机外发送任何数据，也不保存任何凭据。
- 无 shell 层。 每个输入（项目、额外参数）都各自作为 argv 元素传入——恶意字符串也只会保持惰性。project 必须解析到已存在的 tsconfig（或包含 tsconfig 的目录），否则调用会被拒绝。
- 环境。 子进程继承宿主环境，最多覆盖一项（GOMAXPROCS）；插件不添加也不屏蔽任何密钥。

兼容性

- Node.js ≥ 22.19.0。
- DeepSeek Harness 对等依赖范围：@deepseek-ai/cordis ~4.0.5-alpha.1、@deepseek-ai/dsh-tools ^0.2.1-alpha.2、@deepseek-ai/dsh-system-prompt ^0.2.1-alpha.2。
- 接缝契约：device: true 工具注册（tsfork_status、tsfork_check）+ 一个 systemPrompt 段；没有 device 概念的注册表会以急切方式呈现同样的工具。

开发

pnpm install
pnpm -r check # strict typecheck (tsc --noEmit)
pnpm -r test # unit tests + real-binary integration suite (skips without ~/.dsh/tsfork/tsc)
pnpm -r build # tsc -> dist

集成测试套件会针对真实的临时 fixture 项目运行真实的 parked 编译器——不 mock 引擎；在没有该二进制的主机上会干净地跳过。

目录结构

packages/tool-tsfork/ @hy-sde-org/dsh-tool-tsfork — the plugin (both devices) cordis.patch.yml the installable harness bundle (row hy-sde-tsfork) src/core.ts the engine: binary/project resolution, spawn, parse, stamp src/tools.ts the tsfork_status / tsfork_check device bodies src/prompt.ts the tsfork:tools system-prompt section

许可证与署名

本包采用 MIT 许可证——见 LICENSE。它不包含任何编译器源码：tsfork 二进制由部署者从 can1357/TypeScript（perf/checker-speedups-v3）构建，后者是 microsoft/TypeScript 的 Go 重写版（Apache License 2.0，© Microsoft 及上游贡献者；fork 改动 © fork 作者）。来源与完整署名见 THIRD-PARTY-NOTICES.md。harness 仍归其各自项目所有。