ttsc 维护者 Wiki

    平台二进制包

    packages/ttsc-{platform}-{arch} 是七个按平台分发的包，携带原生 ttsc/ttscserver/ttscgraph 二进制与打包的 Go SDK。它们作为 ttsc 的 optionalDependencies，按 os/cpu 自动安装当前平台那一个。

    七个平台包

    包平台
    @ttsc/darwin-arm64macOS arm64
    @ttsc/darwin-x64macOS x64
    @ttsc/linux-x64Linux x64
    @ttsc/linux-arm64Linux arm64
    @ttsc/linux-armLinux arm
    @ttsc/win32-x64Windows x64
    @ttsc/win32-arm64Windows arm64

    每个 package.json 声明 os/cpu 约束（如 @ttsc/darwin-arm64 的 "os": ["darwin"], "cpu": ["arm64"]），npm/pnpm 据此只装匹配当前平台的那个。ttsc 把全部七个列为 optionalDependencies。

    包内容

    每个平台包 ship 预构建的平台产物（README，packages/ttsc-darwin-arm64/README.md）：

    文件作用
    bin/ttsc原生命令 helper
    bin/ttscserver原生 LSP 包装
    bin/ttscgraph原生 MCP 代码图谱服务器（@ttsc/graph 用）
    bin/go/修剪过的 Go SDK，用于把源插件编译成缓存插件二进制

    没有 postinstall 下载步骤——二进制直接 ship 在包里。供应链扫描器可能把原生可执行或打包 Go SDK 报成 opaque/obfuscated（它们不是可读 JS 源），README 解释了这一点供分诊。

    关键设计：自带 Go SDK

    bin/go/ 是 ttsc 不依赖用户机器装没装 Go 的根本（见 go build 缓存 的 resolveGoCompiler）。resolveGoCompiler 优先解析 @ttsc/{platform}-{arch}/bin/go/bin/go，让 npx ttsc 在干净环境也能构建插件。

    这是 ttsc 插件模型成立的前提：插件是 Go 源、按需编译，但用户不必装 Go。

    构建

    packages/ttsc-{platform}/
├── bin/              # 构建产物 (CI 填充)
├── package.json      # os/cpu 约束 + build script
└── README.md

    package.json 的 build script 是 node ../../scripts/build-platform-package.cjs。源与构建入口是 packages/ttsc 与 scripts/build-platform-package.cjs。根 pnpm build → scripts/build-platforms.cjs 构建全部平台包。

    构建顺序约束

    scripts/build-current.cjs 固定：平台包（携带原生 ttsc 编译器二进制）必须在 @ttsc/graph 之前构建，因为 graph 的构建会跑 ttsc（带 typia 插件），需要那个二进制在场。

    二进制解析

    src/compiler/internal/resolveBinary.ts 解析平台 helper（ttsc demo 等命令用，见 依赖与进程拓扑）。找不到时报清晰错误：

    ttsc: platform-specific helper binary not found (@ttsc/<platform>-<arch>).
Set TTSC_BINARY to an absolute helper path or reinstall with optional dependencies enabled.

    不变量

    • 每个平台包按 os/cpu 自动安装，应用项目装 ttsc 而非直接装平台包。
    • 无 postinstall，二进制直接 ship。
    • 平台包须在 @ttsc/graph 前构建。
    • bin/go/ 让 ttsc 不依赖系统 Go。

    维护者提示

    • 加平台 = 加一个 packages/ttsc-{platform}-{arch}，在 ttsc 的 optionalDependencies 加一行，在构建脚本加平台。
    • 别假设系统有 Go——ttsc 自带 SDK 是契约。
    • 供应链扫描误报原生二进制时，引 README 的解释段。

    接下来