ttsc 维护者 Wiki

    ttsc 维护者 Wiki

    面向代码学习者与新维护者的仓库手册。本 Wiki 不重复 ttsc.dev 上面向使用者的指南，而是从源码出发，解释 ttsc 的体系结构、关键运行路径、各子系统的设计取舍、不变量、失败模式与安全修改点。

    这个仓库是什么

    ttsc 是一套构建在 typescript-go（tsgo，TypeScript 编译器的 Go 移植版） 之上的独立工具链。它把"编译器驱动的插件"和"带类型检查的执行"做成产品，对外提供三个 CLI、一套插件协议、一个 LSP 宿主和一个浏览器内编译宿主：

    • ttsc：构建、检查、监听，以及源到源转换，包装在原生 typescript（tsgo）之上。入口 packages/ttsc/src/launcher/ttsc.ts。
    • ttsx：在真正类型检查之后再执行 TypeScript 入口（一个有类型检查的 tsx/ts-node）。入口 packages/ttsc/src/launcher/ttsx.ts。
    • ttscserver：LSP 宿主，包装 tsgo --lsp --stdio，并把 ttsc 插件的诊断、code action 和 workspace/executeCommand 处理器代理到编辑器。入口 packages/ttsc/src/launcher/ttscserver.ts。
    • 插件：与 tsgo 共享 AST/Checker 的 Go 源码包。package main 源构建为可执行旁车（sidecar）；非 main 的 transform 包静态链接进通用原生宿主。

    产品契约是"通用目的"的。下游项目 typia、nestia 只是兼容性夹具（fixtures），不是产品定义本身（见 .codex/skills/project/SKILL.md）。

    一分钟心智模型

    三件事撑起整个系统，理解它们就理解了 ttsc：

    1. JS 编排 + Go 执行的两层结构。JavaScript 层只做参数解析、项目解析、插件发现、惰性 go build 和进程编排；真正的编译、转换、emit、lint 在 Go 原生二进制里完成。见 架构总览 与 三语言模型。
    2. shim 是唯一允许触碰 typescript-go internal/ 的地方。Go 禁止跨模块导入别的模块的 internal/，所以 ttsc 用 packages/ttsc/shim/<name> 逐个再导出。保持 shim 同步且完整是 ttsc 的核心职责。见 shim 子系统。
    3. 插件是 Go 源码，惰性按需构建并缓存。插件描述符是 JS，但 transform 逻辑是 Go；ttsc 用打包的 Go 工具链把源码编译成缓存里的二进制。见 插件宿主。

    推荐阅读路径

    你是谁 / 想做什么阅读顺序
    第一次接触本仓库架构总览 → 仓库地图 → 三语言模型
    想读懂一次 ttsc 构建怎么跑运行时流程 → driver 子系统 → 插件宿主：transform 派发
    要给插件协议加能力 / 调插件加载插件描述符协议 → 加载与发现 → go build 缓存
    缺一个 tsgo API（shim 报缺失）shim 设计 → shim 审计与同步
    调 LSP / 编辑器侧行为LSP 代理设计 → 诊断合并 → code action 与命令
    写 / 调 lint 规则或格式化lint 引擎 → 规则与注册表 → 格式化器
    接 @ttsc/graph / MCP代码图谱构建 → MCP 服务器
    要改任何代码开发流程 → 维护者操作手册

    页面索引

    架构

    子系统

    模块

    开发与参考

    一句话执行摘要

    ttsc 用一层薄薄的 JavaScript 编排（CLI、项目解析、插件惰性构建、进程编排），驱动一组用 Go 写的原生宿主进程；这些进程通过 shim/* 复用 typescript-go 的真实编译器表面，在同一次类型检查里跑插件 transform、lint 规则、代码图谱构建与 LSP 增强，从而把"编译 + 校验 + 格式化 + 代码地图"收敛进单一编译过程。所有声称的行为都在源码、测试或配置里有据可查；推断之处会显式标注。