ttsc 维护者 Wiki

    ttsc 包

    packages/ttsc 是产品心脏，也是工作区里最大的单包（~36k Go LOC + ~12k TS LOC）。它聚合了 JS 启动层、公共 API、Go 原生宿主、shim 层。本页是这个包的导航总览；各子系统有专门深入页。

    包的对外契约

    package.json 暴露三个 CLI 与一个编程式 API：

    "bin": {
  "ttsc": "lib/launcher/ttsc.js",
  "ttscserver": "lib/launcher/ttscserver.js",
  "ttsx": "lib/launcher/ttsx.js"
}

    exports 与 types 指向 src/index.ts（开发）/ lib/index.d.ts（发布）。七个平台包列为 optionalDependencies，按 os/cpu 自动装当前平台那个。

    公共 API 表面刻意极小（src/index.ts）：

    export * from "./TtscCompiler";   // 编程式编译宿主
export * from "./TtscService";    // 常驻转换服务
export * from "./structures/index"; // 公共 DTO 契约

    CLI launcher、二进制解析、项目解析、原生构建辅助全部内部化，让公共契约稳定。

    包内分区与对应子系统页

    分区子系统页
    driver/driver 子系统
    src/plugin/ + src/compiler/插件宿主
    shim/ + tools/shim 子系统
    internal/lspserver/LSP 代理
    internal/graph/代码图谱
    src/launcher/internal/runtimeHooks.tsttsx 运行时
    src/flags/flag 解析器

    编程式 API：TtscCompiler 与 TtscService

    TtscCompiler

    TtscCompiler（src/TtscCompiler.ts:36）是根 JS API，代表一个已解析的项目上下文（cwd、可选 tsconfig、原生 toolchain 覆盖、env、缓存根、插件列表），构造时捕获且不可逐方法替换。方法：

    方法作用
    prepare()把配置的源插件构建进缓存（预热惰性构建成本）
    clean()删本实例上下文拥有的缓存
    compile()编译项目，返回结构化结果（含 emit 输出 in-memory）
    transform()源到源转换，返回 TypeScript 文本

    结果用 embed-typescript 风格判别联合：success/failure/exception。classifyException（TtscCompiler.ts:290）把异常归到 plugin/host/unknown——一段精心写的正则按 ttsc 内部抛出的真实前缀分类（ttsc: plugin、ttsc.transform、go toolchain 归 plugin；ttsc:/tsconfig/TypeScript-Go 归 host）。

    关键契约：compile() 不把 emit 文件写进调用方项目树。无插件项目用 tsgo host 的 WriteFile 回调把输出捕获进内存；有原生插件项目对临时输出目录跑插件管线、读回文本、删临时目录。

    TtscService

    TtscService（src/TtscService.ts）给"一个进程反复转换同一项目文件"的场景（watch server、编辑器、codegen）保持编译器宿主热。它编译项目一次，之后答 per-file transform 请求，经 updateFile 反映内存编辑。后端是 utility serve 常驻协议（见 增量 Session）。它走链接插件宿主，所以项目必须声明至少一个 transform 阶段插件。

    结构契约（structures/）

    src/structures/ 是公共 DTO，导出给插件作者与嵌入者：

    接口作用
    ITtscPlugin插件描述符（见 描述符协议）
    ITtscProjectPluginConfig项目侧插件配置
    ITtscPluginCapabilities宿主能力声明
    ITtscPluginContributor贡献者条目
    ITtscPluginFactoryContext工厂上下文（含 dirname/filename）
    ITtscCompilerContext/Result/Transformation/Diagnostic编译宿主 IO
    TtscPluginStage"transform" | "check"

    internal/ 子目录的结构（ITtscLoadedNativePlugin、ITtscParsedProjectConfig、TtscBuildOptions/Result 等）是内部 DTO。

    Go 命令入口

    命令作用子系统
    cmd/ttsc原生编译宿主（build/check/api-compile/api-transform/demo）driver
    cmd/ttscserverLSP 宿主入口LSP 代理
    cmd/ttscgraph图谱 dump CLI代码图谱
    cmd/utility-host链接插件通用宿主 + serve链接插件
    cmd/platform graphbench graphdump辅助命令—

    构建脚本

    package.json scripts：build（rimraf lib && tsc && cp README）、go:build（scripts/go.cjs build-native）、go:vet、shim:audit、shim:audit:test。@ttsc/station 根的 gen:flags（packages/ttsc/scripts/gen-flags.mts）生成 flag 表。

    维护者提示

    • 公共表面只该经 src/index.ts 扩展；其他都内部化，保持契约小而稳。
    • 改 Go 行为时同步更新 website/src/content/docs/ 对应页（.codex/skills/development/SKILL.md）。
    • 提交前 pnpm format（含 gen:flags 与 Go gofmt）。

    接下来