scaffold-cli

Scaffold CLI

• 适用： 使用 references/ 中固定版本的模板，从头搭建 TypeScript CLI 或 npm 包（Node 24、TypeScript 7），直至首次 CI 运行成功，并使 npm 包能够通过 OIDC 发布。
• 不适用： Next.js Web 应用（使用 scaffold-nextjs）、现有代码库的文件夹结构或模块契约（使用 codebase-architecture）、审查现有 CLI 的易用性（使用 dx-audit），或发布现有包的版本（使用 autoship）。

这些模板规定了项目的工具链。替换项目相关值，并根据已安装的包版本验证模板 API；确认存在不兼容时，应修复，而不是盲目照搬。工具链就是规范：用 tsdown 而非 tsup，用 vitest 而非 jest，通过 ultracite 使用 oxlint 和 oxfmt 而非 eslint 或 prettier，用 node:util 的 styleText 而非 chalk，用 @clack/prompts 而非 ora。替换其中任何一项或重组布局，都会导致模板附带的说明不再适用于该代码库。

参考文件

文件	阅读时机
references/scaffold-configs.md	步骤 3：package.json、tsconfig、tsdown、gitignore、许可证、changeset 配置、GitHub Actions
references/scaffold-source.md	步骤 4–5：src/cli.ts、src/index.ts、src/types.ts、AGENTS.md、README.md、skills/SKILL.md
references/agent-friendly-cli.md	步骤 4，仅当命令接受标识符、路径或 URL，或会改变状态时：输入验证、试运行、确认、架构
references/post-scaffold.md	步骤 6–8：脚手架搭建后的命令、替换 lefthook.yml、验证清单、GitHub 和 npm 初始化、故障排除

脚手架搭建工作流

复制此清单以跟踪进度：

Scaffold progress:
- [ ] Step 1: Gather project info
- [ ] Step 2: Create directory structure
- [ ] Step 3: Generate config files
- [ ] Step 4: Generate source files
- [ ] Step 5: Generate docs and skill
- [ ] Step 6: Run post-scaffold commands
- [ ] Step 7: Validate scaffold
- [ ] Step 8: Bootstrap GitHub and npm (with the user's go-ahead)

步骤 1：收集项目信息

仅询问用户尚未提供的信息：

变量	示例	默认值	用途
{{name}}	md-tools	必填	package.json 名称、README 标题、npm 包
{{description}}	CLI tool to convert content to markdown	必填	package.json、README、SKILL.md
{{bin}}	md	与 {{name}} 相同	package.json 的 bin 字段、CLI 示例、skills 文件夹
{{repo}}	acme/md-tools	必填	package.json 仓库信息、GitHub 仓库、npm 可信发布者
{{author}}	Your Name	必填	package.json、LICENSE
{{year}}	2026	当前年份	LICENSE

{{repo}} 必须是准确的 GitHub owner/name：如果 repository.url 与发布来源仓库不一致，npm provenance 会拒绝此次发布。

步骤 2：创建目录结构

{{name}}/
  .changeset/
  .github/
    workflows/
  src/
  skills/{{bin}}/

步骤 3：生成配置文件

加载 references/scaffold-configs.md。生成其中的所有文件，并替换每个 {{placeholder}}：

package.json、tsconfig.json、tsdown.config.ts、.gitignore、LICENSE.md、.changeset/config.json、.changeset/README.md、.github/workflows/ci.yml、.github/workflows/npm-publish.yml

步骤 4：生成源文件

加载 references/scaffold-source.md。生成：

• src/cli.ts：采用便于 Agent 使用的默认设置的 Commander 入口点（--output text|json、--no-input、标准输出数据与标准错误日志分离、JSON 错误封装）
• src/index.ts：公共 API 导出
• src/types.ts：共享类型定义

当命令接受标识符、路径或 URL，或会改变状态时，还要加载 references/agent-friendly-cli.md，并复制对应的固定模式。对于不包含此类命令的 CLI，跳过此步骤。

步骤 5：生成文档和技能

使用同一份 references/scaffold-source.md，生成：

• AGENTS.md：命令、架构、注意事项、Agent 不变量
• README.md：安装、用法、API、Agent 技能安装、许可证
• skills/{{bin}}/SKILL.md：Agent 技能定义

直接使用 AGENTS.md；不要创建 CLAUDE.md 包装文件或符号链接。

步骤 6：运行脚手架搭建后的命令

加载 references/post-scaffold.md。按给定顺序运行命令序列，包括在 ultracite init 与首次提交之间覆盖 lefthook.yml。

步骤 7：验证脚手架

运行 references/post-scaffold.md 中的验证清单。每一项都是一条命令，其输出就是证据；清单包括 publint、arethetypeswrong、针对真实文件运行钩子，以及占位符扫描。

步骤 8：初始化 GitHub 和 npm

对于本地脚手架，到步骤 7 为止。如果用户已请求设置远程环境或发布，请执行获准的操作范围。否则，在询问是否创建或发布之前，先展示准备好的仓库／软件包标识。否则，按 references/post-scaffold.md 中的“初始化 GitHub 和 npm”操作：创建并推送仓库，启用由 Actions 创建的 PR，先手动发布一次 0.0.1 以创建软件包，然后将工作流注册为可信发布者。终端证据是推送的提交对应一次绿色 CI 运行，且 npm view {{name}} version 输出 0.0.1。从此以后，每次发布都交由 autoship 处理。

依赖项

运行时： @clack/prompts、commander

开发依赖（在 package.json 模板中）： @changesets/cli、@types/node、tsdown、typescript、vitest

由 ultracite init 添加，切勿手动列出： ultracite（由 init 固定为精确版本）、oxlint、oxfmt、lefthook，以及 check、fix 和 prepare 脚本。手动添加会导致脚本重复，且版本与 init 安装的内容不一致。

注意事项

• tsdown 默认会输出 .mjs。 使用 platform: node（默认值）时，fixedExtension 会启用，因此如果配置中没有 outputOptions.entryFileNames: "[name].js"，构建会生成 dist/cli.mjs、dist/index.mjs 和 dist/index.d.mts，而 bin 和 exports 指向的文件并不存在。模板中的 outputOptions 块会确保输出为 .js；不要把它当作无用内容删掉。
• 不要在 src/cli.ts 中加入 shebang。 tsdown 的 banner 会注入 #!/usr/bin/env node；在源码中加入 shebang 会导致 dist/cli.js 中出现两次。两个构建入口应保持分开：CLI 入口使用 banner 且 dts: false，库入口使用 dts: true 且不带 banner。
• 在没有测试文件的仓库中，"test": "vitest run" 若不带 --passWithNoTests，会以 1 退出，导致首次 CI 运行失败。
• @changesets/cli@3 应搭配 changesets/action@v2 和 publish-script: 输入。 @v1 无法驱动 changesets v3；若给 @v2 传入 v1 的 publish: 输入，它会为软件包生成版本，然后以成功状态结束，却不会发布。模板包含匹配的一对；不要单独降级其中一方。
• npm 无法为尚不存在的软件包注册可信发布者。 在步骤 8 中手动运行一次 pnpm publish 创建软件包并注册工作流之前，首次发布运行会因 E404 或 ENEEDAUTH 失败。此次发布发生在创建任何 changeset 之前，因此这是 autoship 规则允许的一次手动发布。
• Node 22 附带 npm 10.9.x；OIDC 发布需要 npm 11.5.1 或更高版本。 Node 24 附带 npm 11.19，因此两个工作流都固定使用 node-version: 24。降至 22 会导致发布因 ENEEDAUTH 失败。即使项目使用 pnpm，发布工作流也会升级 npm：pnpm publish 可以将上传交给 PATH 中的 npm CLI，而该处较旧的 npm 会导致 OIDC 失败。
• 面向 Agent 的输出是一项格式约定。 数据写入 stdout，日志和进度写入 stderr；多余的 console.log 会破坏解析 --output json 的使用方。stdin 不是 TTY 时，绝不要显示提示词：遵循 --no-input，并将所有值作为标志传入，否则进程会在管道环境中挂起。

相关技能

• autoship：完成初始发布后的每次发布，包括变更集、CI 监控、Version Packages PR、发布验证，以及诊断未能发布的版本。
• dx-audit：实际命令就绪后，审查 CLI 的标志、错误和类型。
• agents-md：随着代码库逐渐形成结构，扩充生成的 AGENTS.md。
• ghostwriter：有实际使用场景可供介绍后，重写 README。

仅用于维护：evals/evals.json 包含针对本技能变更的回归场景；用户执行任务时不会加载它。