内容
# 创建启动器
> 脚手架和审计启动器系列项目 — MCP 服务器、Claude 代码技能和 CLI 集成在一个软件包中。
作为 **人类控制的 AI 系统** 的一部分：脚手架是容易的部分。保持已发布的代码仓库可信赖才是关键。审计原始功能（`audit`、`audit-cd`、`audit-security`）验证发布、持续集成（CD）和安全卫生状况，与已知的基准进行对比 — 在每次合并之前进行检查，而不是要求人类手动重新检查。
韩语文档在 [`docs/ko/README.md`](docs/ko/README.md) 中维护；根目录 README 仅保留英文。
## 当前实现
- **CLI** — 软件包和二进制标识均为 `starter-series`；在无作用域的 npm 软件包发布后，`npx starter-series my-bot --template discord-bot` 可以搭建 11 个模板之一，输入由 Zod 验证，原子重命名成功，重试 + 超时 + 50 MB 下载上限。
- **MCP 服务器** — 九个标准输入输出工具：`list_templates`、`create_project`、`audit_release`、`audit_cd`、`audit_security`、`audit_instructions`、`generate_launch_proof_report`、`seed_security_guidance`、`add_component`。一个二进制文件通过 argv（位置参数 -> CLI，无参数 -> MCP 标准输入输出）选择模式。
- **Claude 桌面扩展** — 每次发布都带有 `.mcpb` 包；拖放到 Claude 桌面设置窗口中。
- **Claude 代码插件 + 技能** — `/plugin install create-starter@starter-series` 将 MCP 服务器和对话式 `create` 技能一起发布。
- **MCP 注册表元数据** — `io.github.starter-series/create-starter`；注册表提交以无作用域的 npm 软件包上线和 tarball 验证为条件。
- **`audit_release`** — 检测匹配的启动器、版本与上次标签漂移、CHANGELOG 漂移与合并的 PR（`git log <tag>..HEAD`）、发布工作流类型（release-please / publish-on-tag / auto-release）。
- **`audit_cd`** — 探测 npm、PyPI、Open VSX、VS 市场、AMO、GitHub Releases 的每个目标发布漂移（同步 / 需要发布 / 本地陈旧 / 未找到 / 不支持）。
- **`audit_security`** — 检查 9 项：8 个核心 CI 原始功能（gitleaks 带有 pin 检查、CodeQL、依赖审计、许可证检查、`--ignore-scripts`、Dependabot 分组、机密扫描提示、claude-code-security-review 操作）+ 可选的存储库作者 `claude-security-guidance.md`。8 个核心检查控制 HARDENED 判决；此存储库通过 8/8 个核心检查。
- **`audit_instructions`** / `audit-instructions`** — 审查代理指令文件（`AGENTS.md`、`CLAUDE.md`、`GEMINI.md`、Copilot 指令）是否存在完全相同的重复文件、跨文件表面重叠和基于关键字的风险提醒。重复/重叠发现需要审查；基于关键字的风险总结仅为建议，不用于穷尽的安全性或语义漂移检测。
- **`proof-report`** / `generate_launch_proof_report`** — 运行发布、CD、安全性和指令审查审计，并写入客户端就绪的 [`发布证明报告`](docs/launch-proof-report.md)。这是可货币化的交接面：证据优先，无“认证”声明，除非存储库实际准备好发布，否则退出代码为 1。
- **`add_component`** — 审计循环的补救部分：将启动器的 CI/CD 层（ci / security / dependabot / maintenance / all）提升到现有的存储库中，而无需重新脚手架。默认情况下为干运行，并带有每个文件的计划（创建 / 相同 / 跳过存在 / 覆盖）；拒绝脏 git 树，除非强制；从不触摸应用程序代码或带有秘密的 CD 工作流。干运行计划也是与启动器的漂移报告。
## 计划中
- `audit_cd` 支持 Chrome 网上应用商店、EAS、Railway、Fly 和 GHCR。目前报告为“不支持”，因为这些目标需要身份验证或没有公共读取 API。
## 设计意图
- **一个二进制文件，两个界面。** CLI 和 MCP 标准输入输出共享一个脚手架引擎。argv 决定哪个界面回答。没有重复的逻辑来处理“同一个东西从人类调用与从代理调用”。
- **失败时的原子性。** 提取发生在同级 `.<name>-incomplete-<rand>` 目录中；仅在成功时重命名为最终路径。网络失败、损坏的存档、部分写入 — 都不会留下半搭建的目录。
- **审计是一等公民。** 模板发布安全基准（gitleaks 固定为 SHA、CodeQL、Dependabot 分组、`--ignore-scripts`、claude-code-security-review）。审计命令检查下游存储库是否仍与该基准匹配 — 将基准从一次性脚手架转变为持续的关卡。
- **自己吃自己的狗粮。** 此存储库通过 `audit_security` 的 8/8 个核心检查（HARDENED）；第 9 个是可选的 `claude-security-guidance.md`。如果审计其他存储库的工具无法通过自己的基准，那么基准就不是真正的基准。
- **在其沙盒外只读。** 下载量上限为 50 MB，超时为 30 秒，重试 3 次。相对输出路径不能逃离 cwd；绝对路径仅在明确的用户意图下接受。`git init` 失败记录到 stderr 但不致命。
## 非目标
- **`audit_cd` 中的全供应商对等。** 没有公共读取 API 的目标保持“不支持”而不是报告错误状态。
- **重写应用程序代码。** 毕业流程从匹配的启动器中提升 CI/CD；它从不触摸应用程序代码。
- **通用项目生成器。** 模板是启动器系列的 11 个。新堆栈作为新启动器落地，而不是作为 `create_project` 的标志。
- **语义指令漂移或 AI 安全强制执行。** `audit_instructions` 是重复/表面重叠和关键字提醒的审查辅助工具。它不是语义相似性引擎、运行时护栏、红队工具或详尽的安全性/安全性检查工具。
## 快速入门 — CLI
```bash
# 在无作用域的 npm 软件包发布后：
npx starter-series my-bot --template discord-bot
# 在 npm 发布之前，从源代码运行：
npm ci
npm run build
node dist/index.js my-bot --template discord-bot
```
```
starter-series — 从启动器系列中搭建项目。
用法
starter-series <name> --template <id> [选项]
starter-series audit [path]
starter-series audit-cd [path]
starter-series audit-security [path]
starter-series audit-instructions [path]
starter-series proof-report [path] [--output <file>] [--stdout]
starter-series seed-security-guidance [path] [--force]
starter-series add-component [path] [--component <g>] [--starter <id>] [--apply] [--force]
starter-series --list
starter-series --help
选项
-t, --template <id> 模板 ID（参见 --list）
-d, --description <text> 项目描述（一行）
-o, --output-dir <path> 输出目录（默认：./<name>）
--no-git 在脚手架后跳过“git init”
--output <file> proof-report 输出（默认：<path>/launch-proof-report.md）
--stdout 打印 proof-report Markdown；如果 --output 也写入文件
--component <group> add-component 组：ci, security, dependabot, maintenance, all
--starter <id> add-component 源启动器覆盖
--apply 写入 add-component 计划（默认是干运行）
--force 覆盖不同的组件文件或指导
--list 列出模板并退出
-h, --help 显示帮助并退出
-v, --version 打印版本并退出
环境
CREATE_STARTER_DEBUG=1 发出详细 stderr 日志
```
## 可用模板
| ID | 堆栈 |
|----|-------|
| `mcp-server` | TypeScript + `@modelcontextprotocol/sdk` + Zod |
| `mcp-server-python` | Python + FastMCP |
| `npm-package` | Jest + ESLint + OIDC 发布 |
| `discord-bot` | discord.js v14 + Docker |
| `telegram-bot` | grammY + Docker |
| `browser-extension` | Chrome/Firefox MV3 |
| `vscode-extension` | VS 市场 + Open VSX |
| `electron-app` | 跨平台 + 代码签名 |
| `react-native` | Expo + EAS |
| `cloudflare-pages` | Wrangler + 页面 |
| `docker-deploy` | 任意语言 + GHCR + SSH |
运行 `starter-series --list`（CLI）或调用 `list_templates`（MCP）以获取权威的最新列表。
## 从 Lovable / Bolt / v0 毕业
已经有一个在 vibe-coding 平台上运行良好的应用程序，并想升级到 GitHub Actions + 您自己的部署目标？阅读 [`docs/graduation-from-vibe-coding.md`](docs/graduation-from-vibe-coding.md)（[한국어](docs/graduation-from-vibe-coding.ko.md)）— 一条 5 步的路径，使用 `audit`、`audit-cd` 和 `audit-security` 来诊断您的存储库，然后从匹配的启动器中提升 CI/CD，而无需重写您的应用程序代码。
## 从源代码安装
```bash
git clone https://github.com/starter-series/create-starter
cd create-starter
npm install
npm run build
```
需要 Node.js ≥22。
## Claude 桌面的一键安装
从 [Releases 页面](https://github.com/starter-series/create-starter/releases/latest) 抓取最新的 `.mcpb` 包，并将其拖放到 Claude 桌面设置窗口中。Claude 桌面解包捆绑的 `dist/` 和 `node_modules/`，并将 `create-starter` 注册为 MCP 服务器 — 无需 `npm`、无需配置文件，也无需绝对路径。
> `.mcpb`（MCP 包，前身 `.dxt`）是 Anthropic 的 MCP 服务器的打包扩展格式。参见 [桌面扩展](https://www.anthropic.com/engineering/desktop-extensions)。
要在本地重建包：
```bash
npm ci
npm run bundle:mcpb # 生成 create-starter-<version>.mcpb
```
## 作为 MCP 服务器使用
在您的 MCP 客户端（Claude Desktop、Cursor 等）中注册构建的二进制文件：
```json
{
"mcpServers": {
"create-starter": {
"command": "node",
"args": ["/absolute/path/to/create-starter/dist/index.js"]
}
}
}
```
然后询问您的代理：*“使用 create-starter 搭建一个名为 `my-bot` 的新 discord 机器人。”* 代理将调用 `list_templates`（如果需要），然后调用 `create_project`。
> 二进制文件在没有额外参数的情况下会讲 **MCP 标准输入输出**，并在给定任何位置参数或标志时切换到 **CLI 模式**。两种模式共享相同的脚手架引擎。
## 作为 Claude 代码插件使用
插件捆绑了 MCP 服务器和 `create` 技能 — 一次安装将它们连接起来。
从 Claude 代码 REPL：
```
/plugin marketplace add starter-series/create-starter
/plugin install create-starter@starter-series
```
然后询问 Claude：*“搭建一个名为 `my-bot` 的新 discord 机器人”*，`create-starter:create` 技能将引导对话进入 MCP 工具。
对于本地开发（无需市场往返）：
```bash
claude --plugin-dir /path/to/create-starter
```
指向 git 克隆，以便在 `skills/create/SKILL.md` 或 `dist/index.js` 中编辑后立即生效。
## 通过 MCP 注册表使用
注册发布后，此服务器使用 [官方 MCP 注册表](https://registry.modelcontextprotocol.io/) 命名空间：
```
io.github.starter-series/create-starter
```
MCP 兼容的客户端集成注册表发现可以安装它，而无需手动线路连接。注册表条目指向 npm 软件包 `starter-series`，因此注册表步骤必须在 npm 软件包发布并验证后运行。
所有权通过 GitHub OIDC（命名空间 `io.github.starter-series/*`）和 npm tarball 检查（`package.json#mcpName`）验证。参见 [.github/workflows/publish-mcp-registry.yml](https://github.com/starter-series/create-starter/blob/main/.github/workflows/publish-mcp-registry.yml) 以获取发布流程。
有关 npm 发布设置（受信任的发布者注册，包括 2026-05-20 后的允许操作步骤），请参见 [`docs/RELEASING.md`](docs/RELEASING.md)。
## 工具
脚手架：
- **`list_templates`** — 以 JSON 形式返回完整的模板表。
- **`create_project`** — 参数：
- `template` *(必填)* — 上面表格中的模板 ID。
- `name` *(必填)* — 项目名称，匹配 `^[A-Za-z0-9][A-Za-z0-9_-]*$`。
- `description` *(可选)* — 一行描述。
- `output_dir` *(可选)* — 默认 `./<name>` 相对 MCP 服务器的 cwd。相对路径必须在 cwd 内；绝对路径作为明确的用户意图接受。
- `init_git` *(可选，默认为 `true`)* — 在脚手架后运行 `git init`。
审计（每个都带有一个可选的 `path` 参数，默认为 MCP 服务器 cwd；所有只读）：
- **`audit_release`** — 发布就绪诊断。CLI 镜像：`starter-series audit [path]`。
- **`audit_cd`** — 每个目标发布漂移探针。CLI 镜像：`starter-series audit-cd [path]`。
- **`audit_security`** — 基线 CI 安全卫生检查。CLI 镜像：`starter-series audit-security [path]`。
- **`audit_instructions`** — 代理指令重复和表面重叠审查，并带有建议的关键字风险摘要。CLI 镜像：`starter-series audit-instructions [path]`。
- **`generate_launch_proof_report`** — 发布、CD、安全性和指令审查审计的组合 Markdown 发布交接。CLI 镜像：`starter-series proof-report [path] [--output <file>] [--stdout]`。
- **`seed_security_guidance`** — 生成启动器感知的 `claude-security-guidance.md` 草稿。CLI 镜像：`starter-series seed-security-guidance [path] [--force]`。
- **`add_component`** — 为现有存储库提出或应用启动器 CI/CD 组件的干运行计划。CLI 镜像：`starter-series add-component [path] [--component <g>] [--starter <id>] [--apply] [--force]`。
## 安全性和可靠性
- 项目名称在任何文件系统触摸之前都会进行正则表达式验证；如果相对输出路径逃离工作目录，则拒绝。
- 下载强制执行 30 秒超时、3 次尝试的指数退避和 50 MB 大小上限。
- 提取发生在同级 `.<name>-incomplete-<rand>` 目录中；在任何失败（网络、损坏的存档、提取错误）后，临时目录将被删除。只有在成功后，最终路径才会通过原子 `rename` 出现。
- `git init` 失败记录到 stderr 但不会使脚手架失败；项目在没有 `.git` 目录的情况下仍然可用。
## 预置供应链安全性
每个启动器系列模板都带有 `audit_security` 查找的 9 个检查 — 无需选择：
| 检查 | 它捕获的内容 |
|---|---|
| **gitleaks**（SHA256 固定手动安装） | 代码或历史记录中的提交秘密 |
| **CodeQL**（每周 + PR） | JS/TS/Python 的静态分析 |
| **依赖审计**（`npm audit --audit-level=moderate` / `pip-audit`） | 传输依赖中的已知 CVEs |
| **许可证检查** | GPL/AGPL 污染 |
| **`--ignore-scripts`** 在每次 `npm/pnpm/yarn install` | 恶意 postinstall 脚本 |
| **Dependabot 分组更新** | lockfile 冲突风暴来自一次更新 |
| **GitHub 机密扫描 + 推送保护** | 在推送时泄露令牌 |
| **anthropic/claude-code-security-review** 操作在 PR 上 | AI 基础的差异审查 |
| **`claude-security-guidance.md`** *(这是唯一您编写的)* | Anthropic 的会话式 [Claude Code Security Guidance 插件](https://www.anthropic.com/news/claude-code-plugins)（于 2026-05-26 发布）所消费的组织特定规则 |
这是 Vercel 在 2026-04-21 的 npm 供应链事件期间使用的堆栈 — 他们通过与 Socket/npm/GitHub 协调的相同预置检查来预防泄露。启动器系列在每个启动器中预置这些检查。## 许可证
MIT © heznpc
