LoopX TypeScript 平行迁移指南：控制平面 TS 侧测试如何组织
【免费下载链接】loopxLong-horizon agent control plane for durable, governed work across Codex, Claude Code, and other harnesses.项目地址: https://gitcode.com/GitHub_Trending/lo/loopx
LoopX 是一个面向长程 Agent 的控制平面（control plane），负责在 Codex、Claude Code 等运行环境之上做持久化、可治理的工作调度。它的核心正在做TypeScript 平行迁移——把原本写在 Python 里的控制面事务逻辑，逐块替换为 TypeScript 实现。这篇文章讲清楚一件事：迁移期间，tests/control_plane_ts/ 这个 TS 侧测试目录是如何组织的，以及新手如何跑通它。
🧭 先理解"平行迁移"：替换优先，不留双份语义
LoopX 的迁移策略在官方 RFC 中称为replacement-first（替换优先），规则很简单：
- 每一块业务规则（如 Todo 事务、租约、配额结算）只能有一个语义 owner；
- TS 实现接管事务后，Python 侧对应的旧规则代码被删除，而不是"两份实现互相抄"；
- 兼容路径（如旧 Markdown 投影）可以保留，但不能静默形成第二套语义。
这意味着测试的核心职责是守住替换边界：旧实现的行为不能被悄悄改变，新实现的行为必须可回读、可重放。
迁移方向与当前检查点详见：docs/architecture/rfcs/typescript-control-plane-migration-v0.zh-CN.md。
📁 TS 侧代码与测试的物理布局
| 位置 | 内容 |
|---|---|
| loopx/control_plane/ | 被迁移的控制面源码，.ts与.py并存（如 turn_journal.ts） |
| tests/control_plane_ts/ | TS 侧全部测试，约 135 个文件 |
| tsconfig.control-plane.json | 显式列出每一个纳入编译的.ts源文件与测试文件，strict模式全开 |
| package.json | 提供test:control-plane等 npm 脚本，要求 Node ≥ 22.18 |
| tests/control_plane/ | 对应的 Python 侧测试，约 271 个文件，与 TS 侧互为镜像 |
一个值得注意的细节：tsconfig.control-plane.json 用白名单方式逐个列出被迁移的.ts文件，而不是用通配符。这样"迁移到哪一步"在配置层面就是可见的——没有列进去的模块还停留在 Python 侧。
🏷️ 命名约定：看文件名就知道测试类型
打开 tests/control_plane_ts/ 会看到大量文件，但它们遵循清晰的命名分层：
| 文件模式 | 含义 | 示例 |
|---|---|---|
*.test.ts | 单元测试主体，可被--test通配符直接发现 | turn_journal.test.ts |
*_conformance.ts | 一致性套件：同一套用例喂给多个存储后端 | authority_store_conformance.ts |
*_fixture.ts | 共享测试数据构造器，不是测试本身 | production_scale_coordination_fixture.ts |
*_cli.test.ts | 走真实 CLI 入口的端到端测试 | scheduler_heartbeat_commit_cli.test.ts |
*.integration.test.ts | 需要真实外部服务（如 PostgreSQL）的集成测试 | postgresql_authority_store.integration.test.ts |
*_process.ts | 跨进程协作者脚本（被测试主文件拉起） | sqlite_authority_process.ts |
*_probe.ts | 只读探查探针，用于特征化历史行为 | turn_journal_characterization_probe.mjs |
provider 套件是最典型的设计：同一个 authority 一致性套件，分别由 authority_store.test.ts（File 后端）、sqlite_authority_store.test.ts（SQLite 后端）、nokv_authority_store.test.ts（NoKV 后端）驱动，保证不同存储后端的逻辑头（logical head）与事件轨迹完全一致。
▶️ 如何运行 TS 侧测试
不需要安装任何测试框架——LoopX 直接使用Node.js 原生测试运行器（node:test）加--experimental-strip-types直接运行.ts文件。先克隆仓库：
git clone https://gitcode.com/GitHub_Trending/lo/loopx然后进入仓库执行：
| 命令 | 作用 |
|---|---|
npm run test:control-plane | 跑全部 TS 侧单元测试（开启--experimental-sqlite） |
npm run typecheck:control-plane | 用 tsconfig.control-plane.json 做严格类型检查（noEmit） |
npm run test:control-plane:coverage | 用 c8 生成覆盖率，覆盖loopx/control_plane/**/*.ts |
npm run test:postgresql-authority-store | 真实 PostgreSQL 集成测试，需设置LOOPX_TEST_POSTGRES_URL指向隔离实例 |
这里有个质量红线：PostgreSQL 集成测试被跳过不等于通过，只是证据缺口。完整规则见 docs/development/testing-and-quality.md。
🎯 三臂演练：迁移的"终极对拍"
TS 迁移中最重的验证手段是只读三臂演练（three-arm rehearsal）：
- 使用同一份只读的生产复杂度快照；
- 三个隔离臂分别运行：不可变的 legacy 基线、File provider、真实 PostgreSQL provider；
- 两个 provider 的 head 必须精确相等，legacy 臂按显式兼容投影做语义比较。
可复现脚本位于 examples/control_plane/authority-three-arm-rehearsal.py。配套的 production_scale_coordination_fixture.ts 提供确定性的规模用例，覆盖租约、重放、并发、归档压力等场景，是持久的回归覆盖，但不能替代对当前真实状态的三臂演练。
💡 测试哲学：先审规则，再审实现
LoopX 的质量体系（docs/development/testing-and-quality.md）有两条对新手很实用的原则：
- 预期值必须来自独立审阅的不变量，永远不能由被测实现或它的当前输出生成——防止"用旧代码校准新代码"的自证循环；
- 特征化 fixture 只记录历史行为，不为其背书——发现矛盾时应修复规则并补反例，而不是刷新 golden 文件让测试变绿。
此外，凡声称推进迁移的 PR 都必须遵守"production-scale fixture 维护契约"：声明 fixture 影响、覆盖所有受影响的 provider 臂，并把只读三臂演练保留为独立的 promotion 门禁。
✅ 小结：TS 侧测试组织的三个关键词
- 显式清单——tsconfig.control-plane.json 白名单让迁移进度可审计；
- 命名分层——
test / conformance / fixture / cli / integration / probe各司其职，一眼可辨； - 对拍优先——provider 一致性套件 + 三臂演练，确保 Python→TypeScript 替换前后语义严格一致。
想继续深入，建议按顺序阅读：RFC 迁移方向 → 测试与质量体系 → 直接浏览 tests/control_plane_ts/ 的任意一个 conformance 文件体会分层设计。
【免费下载链接】loopxLong-horizon agent control plane for durable, governed work across Codex, Claude Code, and other harnesses.项目地址: https://gitcode.com/GitHub_Trending/lo/loopx
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
