Skip to content

template-cli.md

Latest commit

 

History

History
731 lines (496 loc) · 20.5 KB

template-cli.md

File metadata and controls

731 lines (496 loc) · 20.5 KB
Raw

模板 CLI

本项目提供一个无运行时依赖的模板 CLI，帮助用户快速找到模板并生成可填写的工作稿。

使用前准备

安装依赖：

npm install

CLI 会从本包读取模板，但把生成文件写入你运行命令时所在的当前目录。相对输出路径如 work/ci-debug.md 会落在当前项目下；绝对路径会按原路径写入。

npx 可用命令以 npm 当前已发布版本为准。运行前可以先查：

npm view ai-devtools-cn version

如果 npx ai-devtools-cn <command> 提示未知命令，说明 npm 包还没有同步到 GitHub main 的最新 CLI；此时请在仓库内使用对应 npm run templates:* 命令，或等维护者完成下一次 npm 发布。

查看可用模板

npm run templates:list

如果通过 npm 或 npx 使用，也可以运行：

npx ai-devtools-cn list

输出会包含：

  • slug：命令中使用的模板标识
  • title：模板名称
  • use case：适用场景
  • file：模板文件路径

查看示例和试用包

npm run templates:examples

等价的 npx 用法：

npx ai-devtools-cn examples

输出会按分组展示：

  • 基础示例
  • 真实维护案例
  • 第一批用户试用包

每条记录包含 slug、标题、适用场景、关联模板和文件路径，适合第一次进入项目时快速找到可复制案例。

查看真实试用配方

npm run templates:recipes

等价的 npx 用法：

npx ai-devtools-cn recipes

如果已经知道配方 slug，可以展开具体步骤：

npm run templates:recipes -- ci-failure

等价的 npx 用法：

npx ai-devtools-cn recipes ci-failure

配方会把模板、命令、步骤和可记录证据放在一起，适合外部试用者用 10-20 分钟完成一个公开安全的小场景。当前包含：

  • pr-review-docs
  • ci-failure
  • issue-triage
  • release-note

完整说明见 真实试用配方。

生成 30 分钟外部试用任务包

npm run templates:pilot -- ci-failure --output work/pilot-ci

等价的 npx 用法：

npx ai-devtools-cn pilot ci-failure --output work/pilot-ci

这个命令面向维护者邀请单个真实外部用户试用。它会生成：

  • README.md：30 分钟试用节奏和证据边界。
  • tester-task.md：可以直接发给外部试用者的任务说明。
  • maintainer-evidence.md：维护者记录 feedback issue、external PR 和后续动作的表格。

pilot 使用真实试用配方 slug，例如 ci-failure、pr-review-docs、issue-triage 或 release-note。本地生成文件不能计为外部采用；只有外部用户提交的公开反馈 issue 或外部 PR 才能计入申请证据。

pilot 任务包会指向专用反馈表单：

https://github.com/ONEISALL7/ai-devtools-cn/issues/new?template=external_pilot_feedback.yml

生成外部 pilot 邀请包

如果你准备同时邀请 2-3 位真实外部开发者试用，可以先生成一份可复制邀请和跟进表：

npm run templates:pilot-invite -- --output work/pilot-invites.md

等价的 npx 用法：

npx ai-devtools-cn pilot-invite --output work/pilot-invites.md

这个命令会生成：

  • 一对一邀请文案，适合发给认识的开发者或开源维护者。
  • 公开渠道邀请文案，适合 X、V2EX、微信群或技术社群。
  • 推荐的 pilot recipe 和本地生成命令。
  • 维护者跟进表，用于记录邀请对象、feedback issue 和后续动作。
  • 证据边界，明确 feedback issue、external merged PR 和 feedback-driven PR 的区别。

pilot-invite 不会自动发送消息，也不会创建 GitHub issue。它的价值是把“找真实外部用户试用”变成可执行的复制文本和记录表，避免后续公开证据混淆维护者自测与真实外部反馈。

查看外部贡献任务

npm run templates:contribute

等价的 npx 用法：

npx ai-devtools-cn contribute

这个命令会列出：

  • Good First PR Briefs 链接
  • 当前 #45-#49 可认领任务
  • 每个任务的 issue、brief 和建议 PR 标题
  • 每个任务可直接复制的 handoff、pr-pack、claim 和 starter 起步命令
  • 最小验证命令
  • 公开安全边界

这个命令面向真实外部贡献者。维护者自己完成的 PR 不能写成 external merged PR。

生成 good first issue 认领草稿

npm run templates:claim -- 45 --output work/claim-45.md

等价的 npx 用法：

npx ai-devtools-cn claim 45 --output work/claim-45.md

这个命令会根据 Good First PR Briefs 生成一份本地草稿，包含：

  • issue 链接
  • brief 链接
  • 建议 PR 标题
  • 公开安全检查
  • 最小验证命令
  • PR 描述草稿
  • 维护者合并后记录 external merged PR 的字段

当前支持 #45-#49。这个命令只帮助外部贡献者准备 PR，不会自动创建 PR，也不能把维护者自己生成的草稿计入 external merged PR。

生成 good first issue 内容起稿

npm run templates:starter -- 45 --output work/node-ci-starter.md

等价的 npx 用法：

npx ai-devtools-cn starter 45 --output work/node-ci-starter.md

这个命令会为指定 good first issue 生成一份可填写的案例或文档骨架，包含：

  • 推荐模板和目标产物位置
  • 场景背景填写提示
  • 输入材料填写提示
  • 建议输出结构
  • 公开安全检查
  • 本地验证命令
  • PR checklist

当前支持 #45-#49。生成的文件默认建议放在 work/ 下，适合作为本地草稿；只有真实外部贡献者把内容整理成 PR 并被合并后，才能计入 external merged PR。

查看社区发布入口

npm run templates:launch

等价的 npx 用法：

npx ai-devtools-cn launch

这个命令会列出：

  • 社区发布包链接
  • 当前可公开状态
  • 不用 clone 的试用命令
  • 反馈 issue 入口
  • Good First PR Briefs 链接
  • issue #51 发布后记录入口

这个命令面向准备发布项目、邀请真实试用者或邀请外部 PR 的维护者。它不会自动发布内容，也不会把维护者自己的 issue 或 PR 计入外部采用证据。

生成外部 PR 交接包

如果你要把一个小任务交给外部贡献者，可以先生成一份可转发交接包：

npm run templates:handoff -- --output work/external-pr-handoff.md

等价的 npx 用法：

npx ai-devtools-cn handoff --output work/external-pr-handoff.md

如果已经选定某个 good first issue，可以生成定向交接包：

npx ai-devtools-cn handoff --issue 45 --output work/handoff-45.md

如果不指定 --output，命令会直接在终端打印交接内容：

npx ai-devtools-cn handoff

交接包会包含：

  • 外部 PR 交接包和 Good First PR Briefs 链接
  • 可直接发送给外部贡献者的邀请
  • 可选的单 issue 定向邀请、issue 链接和建议 PR 标题
  • fork、认领、提交 PR 和验证步骤
  • PR 描述模板
  • 什么能算 external merged PR，什么不能算

这个命令不会创建 GitHub PR，也不会把维护者自己的草稿计入外部贡献。只有外部贡献者用自己的 GitHub 账号提交并合并的 PR，才能记录为 external merged PR。

生成外部贡献者 PR 包

如果你已经选定一个 good first issue，可以生成一份更具体的 PR 包，直接发给外部贡献者：

npm run templates:pr-pack -- 45 --output work/pr-pack-45.md

等价的 npx 用法：

npx ai-devtools-cn pr-pack 45 --output work/pr-pack-45.md

如果不指定 --output，命令会直接在终端打印内容：

npx ai-devtools-cn pr-pack 45

PR 包会包含：

  • issue、brief、建议 PR 标题和建议分支名
  • 建议修改文件清单
  • 可以直接发送给外部贡献者的邀请文案
  • 外部贡献者提交步骤
  • 可复制 PR 描述
  • 维护者 review 检查清单

这个命令适合“请别人帮忙提交一个真实 PR”的场景，但它只负责准备说明材料。贡献者必须用自己的 GitHub 账号理解、修改、验证并提交 PR；维护者不能把自己生成的本地草稿或代发补丁计入 external merged PR。

生成外部 PR review 清单

真实外部贡献者提交 PR 后，维护者可以生成 review 和证据记录清单：

npm run templates:review-pr -- --pr 123 --author external-dev --issue 45 --output work/review-pr-123.md

等价的 npx 用法：

npx ai-devtools-cn review-pr --pr 123 --author external-dev --issue 45 --output work/review-pr-123.md

清单会包含：

  • PR、作者和关联 issue 字段
  • 外部贡献真实性检查
  • 公开安全检查
  • 本地验证命令
  • review 决策字段
  • 可复制 review 评论
  • evidence ledger 记录格式

这个命令不会自动读取 GitHub，也不会自动把 PR 记为 external merged PR。只有真实外部贡献者提交、通过 review 并合并的 PR，才能进入 External merged PRs。

按任务推荐模板和案例

npm run templates:recommend -- ci

等价的 npx 用法：

npx ai-devtools-cn recommend ci

这个命令会同时搜索模板和示例，并输出：

  • 推荐模板
  • 推荐案例或试用包
  • 查看模板的下一步命令
  • 生成工作稿的下一步命令
  • 生成试用包的推荐命令

适合不确定该用哪个模板时先输入任务关键词，例如 ci、review、pytest、release。

搜索模板

npm run templates:search -- ci

等价的 npx 用法：

npx ai-devtools-cn search ci

可以搜索 slug、标题、文件名、使用场景和输出位置。

诊断本地环境

如果 CLI 无法生成文件，或者你想确认当前目录是否适合试用，可以运行：

npm run templates:doctor

等价的 npx 用法：

npx ai-devtools-cn doctor

这个命令会检查：

  • 当前 ai-devtools-cn 包版本
  • Node.js 版本是否满足 >=18
  • 当前目录是否可写
  • 模板注册和模板文件是否一致
  • 当前可用模板和工作包数量

查看单个模板

npm run templates:show -- pr-review

等价的 npx 用法：

npx ai-devtools-cn show pr-review

这个命令会显示模板路径、适用场景、输出位置和模板开头预览。

生成工作稿

npm run templates:new -- ci-troubleshooting --output work/ci-debug.md

等价的 npx 用法：

npx ai-devtools-cn new ci-troubleshooting --output work/ci-debug.md

生成的工作稿会包含：

  • 来源模板
  • 使用场景
  • 建议沉淀位置
  • 使用前需要填写的上下文
  • 原始模板正文

默认输出位置是 work/<slug>-draft.md。work/ 已加入 .gitignore，适合存放本地草稿。

如果文件已存在，命令会拒绝覆盖。确实需要覆盖时使用：

npm run templates:new -- ci-troubleshooting --output work/ci-debug.md --force

生成维护者工作包

如果你要给一个开源仓库建立一组基础维护工作流，可以运行：

npm run templates:kit -- oss-maintainer --output work/oss-maintainer-kit

等价的 npx 用法：

npx ai-devtools-cn kit oss-maintainer --output work/oss-maintainer-kit

工作包会生成一个目录，包含：

  • README.md：工作包索引和推荐使用顺序
  • pr-review.md
  • issue-triage.md
  • ci-troubleshooting.md
  • release-note.md
  • maintainer-weekly-checklist.md
  • contributor-onboarding.md
  • ai-output-evaluation.md

如果输出目录里的文件已存在，命令会拒绝覆盖。确实需要覆盖时使用：

npm run templates:kit -- oss-maintainer --output work/oss-maintainer-kit --force

生成 15 分钟试用包

邀请第一批用户试用时，可以生成一个包含模板工作稿和反馈草稿的目录：

npm run templates:trial -- --template pr-review --scenario "review a documentation PR" --output work/trial

等价的 npx 用法：

npx ai-devtools-cn trial --template pr-review --scenario "review a documentation PR" --output work/trial

试用包会包含：

  • README.md：15 分钟试用步骤和公开安全提醒
  • <template>.md：可填写的模板工作稿
  • feedback.md：可复制到 GitHub issue 的反馈草稿

如果不指定 --template，默认使用 pr-review。如果输出目录里的文件已存在，命令会拒绝覆盖；确实需要覆盖时使用 --force。

生成反馈 issue 草稿

邀请试用者反馈时，可以先生成一份公开安全的 issue 草稿：

npm run templates:feedback -- --template pr-review --scenario "review a documentation PR" --output work/feedback.md

等价的 npx 用法：

npx ai-devtools-cn feedback --template pr-review --scenario "review a documentation PR" --output work/feedback.md

生成的草稿会包含：

  • GitHub 反馈 issue 入口
  • 公开安全检查
  • 使用模板或功能
  • 使用场景
  • 遇到的困难
  • 希望补充的模板或案例

如果只想生成空白反馈草稿，也可以运行：

npm run templates:feedback -- --output work/feedback.md

生成外部试用邀请包

如果你准备邀请真实开发者试用模板，可以生成一份可直接发送的邀请包：

npm run templates:outreach -- --template pr-review --channel x --scenario "review a documentation PR" --output work/outreach.md

等价的 npx 用法：

npx ai-devtools-cn outreach --template pr-review --channel x --scenario "review a documentation PR" --output work/outreach.md

支持的 --channel 包括：

  • github
  • x
  • v2ex
  • wechat
  • email

生成的邀请包会包含：

  • 面向所选渠道的试用邀请文案
  • 试用前检查清单
  • 推荐试用命令和反馈草稿命令
  • GitHub feedback issue 入口
  • 维护者记录真实反馈的字段

这个命令适合收集第一批真实用户反馈。不要把维护者自己创建的测试 issue、占位 issue 或泛泛建议包装成外部用户反馈。

生成一周外部试用冲刺包

如果你准备集中一周邀请真实开发者试用，可以生成一份执行包：

npm run templates:adoption -- --template pr-review --scenario "review a documentation PR" --output work/adoption-sprint

等价的 npx 用法：

npx ai-devtools-cn adoption --template pr-review --scenario "review a documentation PR" --output work/adoption-sprint

冲刺包会生成一个目录，包含：

  • README.md：7 天试用节奏、目标和安全边界
  • outreach.md：GitHub、X、V2EX、微信和私信渠道邀请文案
  • feedback-log.md：外部 feedback issue、公开提及和外部 PR 记录表
  • contributor-invite.md：邀请外部贡献者认领 good first issue 的文案

这个命令用于把“找真实用户试用”变成可执行流程。它不会自动生成真实反馈，也不能把维护者自己的 issue 或 PR 计入外部采用证据。

生成外部采用证据台账

当你开始发布 npm、邀请外部用户试用、收到 feedback issue 或合并外部 PR 后，可以生成一份证据台账：

npm run templates:evidence -- --output work/external-evidence.md

等价的 npx 用法：

npx ai-devtools-cn evidence --output work/external-evidence.md

证据台账会包含：

  • 外部采用记录原则
  • 当前指标快照填写区
  • npm 发布、外部 feedback issue、反馈驱动 PR/release、外部 PR、公开提及和匿名案例记录表
  • 可公开核验的外部采用证据类型
  • 不应计入外部采用的内容

这个命令不会自动抓取外部数据，也不会把维护者自己的 issue 包装成外部反馈。它的用途是帮助维护者在真实外部信号出现后，用可核验链接记录下来。维护者基于外部反馈完成的 PR/release 可以作为反馈驱动改进证据，但不能写成 external merged PR。

生成 OpenAI Codex 资格申请材料

如果你准备提交 OpenAI Codex for Open Source 申请，这个命令会直接生成一份可提交的材料草稿：

npm run templates:readiness -- --output work/openai-readiness-2026-06-02.md

等价的 npx 用法：

npx ai-devtools-cn readiness --output work/openai-readiness-2026-06-02.md

默认输出到：

  • work/openai-readiness-YYYY-MM-DD.md

命令会生成一份包含以下内容的材料：

  • 项目定位和仓库状态
  • 核验文件清单（README、CONTRIBUTING、SECURITY、MAINTAINERS、CHANGELOG、LICENSE）
  • GitHub / npm 可核验指标（stars、forks、merged PRs、external merged PRs、feedback、releases 等）
  • 直接可粘贴到 OpenAI 表单的三段英文文本：
    • Describe your role
    • Why does this repository qualify?
    • How will you use API credits?
  • 外部反馈 / PR 边界说明（防止把 maintainer 自测当作外部采用）

命令优先使用环境变量快照（例如 AI_DEVTOOLS_CN_REPO_INFO_JSON），如未设置则尝试读取本地 GitHub / npm 命令与 npm 下载 API。若仍无法获取则显示 unknown/unavailable。文件有冲突时可加 --force 覆盖。

查看 npm 发布同步状态

发布或对外发送 npx 命令前，可以检查本地版本、npm 公开版本和 GitHub 最新 release 是否一致：

npm run templates:publish-status

等价的 npx 用法：

npx ai-devtools-cn publish-status

输出会包含：

  • package.json 本地版本
  • npm 当前公开版本
  • GitHub 最新 release tag
  • 当前源码是否领先最新 release tag
  • npm 是否落后本地版本
  • 发布前验证命令
  • 发布后的 npx smoke check

如果 npm 版本落后，不要把 GitHub main 上的新命令写成“外部用户已经能通过 npx 使用”。应先完成 npm 发布，或者让贡献者 clone 仓库后使用 npm run templates:* 命令。

如果输出显示 source is ahead of latest release tag，说明当前 main 已经包含最新 GitHub release 没有覆盖的提交。此时不要直接把当前 main 当成旧 release 发布；要么从已验证的 release tag 发布旧版本内容，要么先创建新的 GitHub release，再发布当前 main。

校验模板注册表

维护者或贡献者新增模板后，可以运行：

npm run templates:validate

等价的 npx 用法：

npx ai-devtools-cn validate

这个命令会检查：

  • CLI 注册的模板 slug 是否重复
  • 注册字段是否为空
  • 注册的模板文件是否存在
  • templates/ 下的模板文件是否已注册到 CLI
  • 模板文件是否以一级标题开头

检查 npm 发布准备状态

维护者准备发布 npm 包前，可以运行：

npm run templates:publish-check

等价的 npx 用法：

npx ai-devtools-cn publish-check

这个命令会检查：

  • package name、version、license、repository、bugs 和 engines
  • bin.ai-devtools-cn 是否指向 scripts/template-cli.mjs
  • files 白名单是否包含 README、LICENSE、CHANGELOG、docs、examples、templates 和 CLI 入口
  • 模板注册和模板文件是否一致
  • 案例注册和案例文件是否一致
  • 发布相关 npm scripts 是否存在

这个命令不会登录 npm，也不会发布包。真正发布前仍需要继续运行 npm run pack:dry-run 和 npm publish --dry-run --access public。

推荐流程

  1. 运行 npm run templates:list 找到模板 slug。
  2. 运行 npm run templates:examples 找到可复制案例或试用包。
  3. 如果想直接照着真实场景试用，运行 npm run templates:recipes 查看配方。
  4. 不确定时运行 npm run templates:recommend -- <keyword> 获取推荐。
  5. 运行 npm run templates:show -- <slug> 确认是否适合当前任务。
  6. 运行 npm run templates:new -- <slug> --output work/<task>.md 生成工作稿。
  7. 补齐工作稿中的项目背景、技术栈、日志、约束条件和期望输出。
  8. 把整理后的提示词复制到你的 AI 开发工具。

如果你是开源项目维护者，想先建立一整套基础流程，可以直接运行 npm run templates:kit -- oss-maintainer --output work/oss-maintainer-kit。

发布前检查

维护者发布 npm 包前应运行：

npm run test
npm run templates:validate
npm run templates:publish-check
npm run pack:dry-run

npm run templates:publish-check 只检查本地包结构；npm run pack:dry-run 只检查发布内容。两者都不会真正发布包。

注意事项

  • CLI 不会调用任何 AI API。
  • CLI 不会读取你的项目源码，除非你主动把内容写进工作稿。
  • 不要把密钥、客户数据、账号或未公开代码提交到仓库。
  • AI 输出仍需要人工 review，尤其是安全、依赖升级和生产变更。