【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载本文以归档变更集 migration-batch-6-ts.md 为主体讲清 PR #537 依据 ADR-457 将graphify、install-profiles、intel、installer-migrations、worktree-safety五个模块从手写 CommonJS 迁移到 TypeScript 真源的完整机制编译管线如何配置、gitignored 产物如何保持行为逐字节不变、以及哪些守卫脚本确保迁移不引入用户可见变化。读完后你能够理解这套 build-at-publish 生成模型的设计取舍并在本地复现构建、验证产物同步。变更集原文说了什么migration-batch-6-ts.md 是一份标准的 per-PR CHANGELOG 片段frontmatter 与正文仅 7 行但其信息密度极高--- type: Changed pr: 537 --- Migrate 5 modules from hand-written CommonJS to TypeScript source of truth per ADR-457 (#537). Modules migrated: graphify, install-profiles, intel, installer-migrations, and worktree-safety. Each src/m.cts compiles to a gitignored get-shit-done/bin/lib/m.cjs with behaviour preserved byte-for-behaviour; only strict types are added. !-- docs-exempt: Internal ADR-457 build-at-publish source migration; behaviourally-identical gitignored artifacts at same require() paths; no user-facing change. --三个关键事实可以直接读出迁移对象五个模块全部是gsd-core/bin/lib/下的运行时逻辑文件迁移后对应src/下的.cts源文件当前仓库中为 src/graphify.cts、src/install-profiles.cts、src/intel.cts、src/installer-migrations.cts、src/worktree-safety.cts。行为承诺byte-for-behaviour —— 编译产物在运行时行为上与旧的手写.cjs完全一致only strict types are added即本次迁移只做加类型不改逻辑。豁免理由尾部 HTML 注释docs-exempt说明这是一次内部构建管线迁移产物路径require()入口不变、无用户可见变化因此不触发用户文档更新义务。这正是仓库 changeset 机制中 内部重构可豁免文档 的典型用法fragment 的格式约定见 .changeset/README.md。一个值得注意的历史细节变更集正文写的是get-shit-done/bin/lib/m.cjs而当前仓库的实际目录是gsd-core/bin/lib/。这不是文档过期而是命名演进——迁移清单 src/installer-migrations/003-rename-get-shit-done-to-gsd-core.cts 记录了get-shit-done到gsd-core的目录改名。背景ADR-457 为什么选择 build-at-publish第 6 批迁移不是孤立的它引用了 docs/adr/457-generated-cjs-single-source.md 确立的生成模型。该 ADR 的核心问题是类型检查 TS 源码是目标但生成的.cjs到底查进 git 还是作为构建产物ADR 给出三种模型并逐一裁决模型 1.ts源与.cjs产物都查进 git。会引入永恒的 两份必须一致 不变式需要 parity 测试、双份提交和 CI 漂移门禁。对纯转译而言运行时零收益却引入最大摩擦被拒。模型 2build-at-publish推荐已采纳。bin/lib/*.cjs成为 gitignored 构建产物由tsc从 TSsrc/树产出npm 发布时附带构建产物。ADR 原文指出这在采纳当时就可落地package.json 已经通过files数组发布gsd-core与scripts且已有 pre-publish 构建步骤见 ADR-457 决策段落。模型 3安装期构建。跨 Node 版本与平台脆弱、拖慢每次安装被拒。ADR 还刻意区分了两种都叫 generation 的技术package-identity.cjs属于值烘焙value baking安装树里读不到package.json的.name只能在构建期把字面量烤进去是强制的深接缝而本次迁移属于转译transpilationtsc产出的.cjs与手写.cjs运行时行为相同其全部价值在编写期与 CI 的类型检查。ADR 决策第 3 条要求增量迁移、低耦合模块优先——第 6 批正是这个逐批推进过程的一环。第 6 批五个模块的迁移落点五个模块在源码树中的规模与职责以当前仓库为准模块源文件规模职责源自模块头注释graphifysrc/graphify.cts约 815 行知识图谱集成配置门、子进程执行、图谱查询、状态/diff/构建流水线install-profilessrc/install-profiles.cts约 1316 行Skill Surface Budget决定哪些 skills/agents 写入运行时配置目录的单一真源ADR-0011intelsrc/intel.cts约 837 行Intel 存储与查询.planning/intel/下的项目元数据file-roles、api-map、dependency-graph、arch-decisions、stackinstaller-migrationssrc/installer-migrations.cts约 1278 行迁移引擎对运行时配置目录做计划、应用、回滚、加锁与日志记录worktree-safetysrc/worktree-safety.cts约 3142 行worktree 根解析与非破坏性 prune 策略判定注意installer-migrations不只是单个文件迁移条目本身是独立模块存放在 src/installer-migrations/ 目录000-first-time-baseline.cts至010-antigravity-retire-confighome-artifacts.ctstsconfig.build.json的include: [src/**/*.cts]会把它们一并编译这正是该 ADR 选择.cts扩展名的原因——让tsc按 nodenext 规则原生发射.cjs。每个模块头部的文件注释都是迁移的自证例如 src/worktree-safety.cts/** * Worktree Safety Policy Module * * Owns worktree-root resolution and non-destructive prune policy decisions. * * ADR-457 build-at-publish: the hand-written bin/lib/worktree-safety.cjs * collapsed to a TypeScript source of truth. Behaviour is preserved * byte-for-behaviour from the prior hand-written .cjs; only types are added. */从源码结构看迁移后模块间互引保持原样.cts源里以import ... from ./shell-command-projection.cjs这样的形式引用同批产物如 src/worktree-safety.cts 对security.cjs、shell-command-projection.cjs的引用与变更集承诺的 same require() paths 相互印证——消费方的require()入口完全不动。编译管线.cts到 gitignored.cjs整条管线由三个文件锚定1. 构建配置 tsconfig.build.json逐项对照rootDir: src/outDir: gsd-core/bin/lib源在仓库根src/产物落在安装树内与旧手写文件的物理路径重合require(.../bin/lib/graphify.cjs)这类入口因此无需任何改动module/moduleResolution均为nodenexttarget: ES2022产物仍是 CommonJS与仓库内其余require()消费方兼容ADR 中被拒的 ESM 全面重写选项正是因为它会破坏这一点strict: true对应变更集里 only strict types are added 的承诺noEmitOnError: true类型错误会阻止发射保证产物不会带着未检出的类型问题进入npm packincremental: truetsBuildInfoFile: tsconfig.build.tsbuildinfo增量编译缓存同样被 gitignore见 .gitignore 中的/tsconfig.build.tsbuildinfo条目。2. 编辑期类型检查 tsconfig.json它extends构建配置并加noEmit: true作为编辑器/CI 的纯类型检查配置。ADR 决策第 5 条要求 把 type-aware lint 接到真实 tsconfig.json 上直到最后一个手写.cjs消失才退役 tsconfig.lint.json这两个文件的分工即该条的落地形态。3. npm 生命周期钩子 package.json.cjs发射被织入既有发布链路build: npm run generate:identity npm run build:lib ... npm run build:hooks, build:lib: tsc -p tsconfig.build.json, prepack: npm run build:lib, prepare: npm run build:lib, prepublishOnly: npm run build:lib npm run build:hooks, pretest: npm run build:lib npm run lint:skill-deps这组钩子恰好覆盖 ADR Consequences / For testing 一节预警的行为变化测试导入bin/lib/*.cjs只有构建跑过才能工作因此pretest显式依赖build:libprepack/prepare保证npm pack与本地git clone后npm install都会先编译而 ADR 指出的 npm pack 会包含磁盘上的产物与 .gitignore 无关 正是发布侧的保证。4. 产物不入库.gitignore 逐条列出已迁移模块的发射路径/gsd-core/bin/lib/...cjs系列条目以及构建缓存。这消除了模型 1 的全部漂移治理机器——无漂移不变式、无 parity 测试、无双份提交。行为保真与防漂移守卫迁移承诺 byte-for-behaviour仓库用两层机制守住它第一层同一require()路径 只加类型。产物路径与旧文件重合gsd-core/bin/lib/m.cjs消费方零改动类型注解经tsc擦除后不改变运行时字节流中的任何可执行语义。noEmitOnError: true则保证 类型未过检查的产物 不可能被发射出去。第二层编译产物同步 lint scripts/lint-compiled-artifact-sync.cjs。该脚本的注释交代了一个真实事故背景#2653中某个.cjs曾落后于其.cts源四天把整块修复悄悄漏出而 CI 保持绿灯。此检查的策略值得注意——它对 当前被 git 追踪的已编译产物集合 断言属性而非硬编码文件清单只要产物仍被追踪就必须与一次新鲜编译逐字节一致--check模式下退出码 0/1当 ADR-457 的终态达成全部产物 gitignored、追踪集合为空时脚本平凡通过、无需再改。其回归测试见 tests/lint-compiled-artifact-sync.test.cjs。读者视角如何查看与复现验证迁移状态在src/下能看到五个.cts真源在 tsconfig.build.json 中确认outDir指向gsd-core/bin/lib.gitignore 中的逐条条目即是 该模块已完成 ADR-457 迁移 的清单式证据。本地构建执行npm run build:lib即tsc -p tsconfig.build.json即可重新发射全部产物npm test会经由pretest自动先构建。追踪同系列批次第 6 批前后还有同属 PR #537 的兄弟变更集如 code-review-leaf-batch-1-ts.md9 个纯叶模块与 migration-batch-10-ts.md9 个 command-router 模块它们与本文第 6 批共同构成 ADR-457 逐模块、低耦合优先 的增量迁移序列。适用前提该管线面向仓库贡献者与 CI对最终用户而言 npm 发布物已内含构建产物require()路径与行为均无变化——这也正是变更集标注no user-facing change的由来。小结migration-batch-6-ts.md 用一行变更集记录了一次结构性收敛五个运行时模块的真源从gsd-core/bin/lib/*.cjs移到src/*.cts由 tsconfig.build.json 驱动的tsc在发布前发射 gitignored 产物require()路径不变、行为逐字节保真、strict类型成为默认约束。这套 build-at-publish 模型的价值不在运行时而在于把 手写还是生成 的长期模糊地带收敛成唯一被强制执行的答案并以 lint-compiled-artifact-sync 这样的状态无关守卫堵住过渡期的漂移风险。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐gsd-core ADR-457 迁移系列 · 批次 56 个运行时模块从手写 CommonJS 迁移到 TypeScript 源码真源gsd core ADR 457 迁移系列 · 批次 56 个运行时模块从手写 CommonJS 迁移到 TypeScript 源码真源 本文以 migratgsd-core ADR-457 TypeScript 源码迁移实录10 个运行时模块从手写 CommonJS 到 tsc 构建产物gsd core ADR 457 TypeScript 源码迁移实录10 个运行时模块从手写 CommonJS 到 tsc 构建产物 本篇以归档 changegsd-core ADR-457 迁移实战phase、verify、init 三大模块从手写 CommonJS 转向 TypeScript 单一事实源gsd core ADR 457 迁移实战phase、verify、init 三大模块从手写 CommonJS 转向 TypeScript 单一事实源 本文围上一篇MemOS 记忆模块全景指南从轻量文本记忆到知识图谱与 KV-Cache 激活记忆的选型与实战下一篇突破性方案如何彻底解决GitHub访问与下载速度难题创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考