create-starter

create-starter

为 Starter Series 项目搭建脚手架并进行审计 — 在同一个软件包中提供 MCP 服务、Claude Code 技能和 CLI。

属于：Human-Controlled AI Systems — 搭建脚手架只是容易的部分。让已发布的代码仓库值得信赖的，是审计原语（audit、audit-cd、audit-security）：它们依据已知标准核验发布、CD 和 CI 的安全规范，并在每次合并时进行门禁检查，而不是要求人工手动复查。

韩语文档维护在 docs/ko/README.md 下；根目录 README 仅使用英语。

安全检查会检查本地工作流定义，以及引用的 starter-series/.github 策略，包括复合操作和调用的脚本。证据包括源路径和内容哈希。无法读取或不受支持的可复用工作流会被报告为未经验证；此检查针对配置，而非最新的 Actions 运行情况或实时漏洞扫描。

当前已实现

• CLI — package 和 binary 的标识均为 starter-series；npx starter-series my-package --template npm-package 可使用经 Zod 验证的输入，从 6 个公开模板中生成一个项目，成功后原子重命名，并支持重试、超时和 50 MB 下载上限。
• MCP 服务 — 提供 9 个 stdio 工具：list_templates、create_project、audit_release、audit_cd、audit_security、audit_instructions、generate_launch_proof_report、seed_security_guidance、add_component。一个 binary 根据 argv 选择模式（有位置参数 -> CLI，无参数 -> MCP stdio）。
• Claude Desktop 扩展 — 每次发布都会生成 .mcpb bundle；将其拖到 Claude Desktop 设置窗口即可。
• Claude Code 插件 + skill — /plugin install create-starter@starter-series 会同时提供 MCP 服务和对话式 create skill。
• MCP Registry 元数据 — io.github.starter-series/create-starter；只有未限定作用域的 npm package 已上线且 tarball 已验证后，才会提交到 registry。
• audit_release — 检测匹配的 starter、版本与上一个 tag 的偏差、CHANGELOG 与已合并 PR 的偏差（git log <tag>..HEAD），以及发布工作流类型（release-please / publish-on-tag / auto-release）。
• audit_cd — 检查 npm、PyPI、Open VSX、VS Marketplace、AMO、GitHub Releases，检测各发布目标的发布偏差（in-sync / needs-publish / local-stale / not-found / unsupported）。
• audit_security — 检查 9 项内容：8 项核心 CI 基础措施（gitleaks 及 pin 检查、CodeQL、依赖审计、许可证检查、--ignore-scripts、Dependabot 分组、密钥扫描提示、claude-code-security-review Action），以及可选的仓库作者提供的 claude-security-guidance.md。8 项核心检查决定 HARDENED 结论；此仓库的核心检查通过率为 8/8。
• audit_instructions / audit-instructions — 审查 Agent 指令文件（AGENTS.md、CLAUDE.md、GEMINI.md、Copilot instructions），检查同一文件中的完全重复内容、跨文件表面重叠，以及基于关键词的风险提醒。重复/重叠发现需要人工审查；关键词风险摘要仅供参考，既不全面，也不能检测安全性或语义偏差。
• proof-report / generate_launch_proof_report — 一并运行发布、CD、安全和指令审查审计，并生成可交付给客户的 Launch Proof Report。这是可变现的交付环节：先提供证据，不声称“已认证”；只有仓库确实已准备好发布时才返回退出码 0，否则返回退出码 1。
• add_component — 审计闭环中的修复环节：将 starter 的 CI/CD 层（ci / security / dependabot / maintenance / all）移植到现有仓库，无需重新生成脚手架。默认采用试运行模式，并按文件提供计划（create / identical / skip-exists / overwrite）；除非强制执行，否则会拒绝操作存在未提交更改的 git 工作树；绝不修改应用代码或包含密钥的 CD 工作流。试运行计划还可作为与 starter 的偏差报告。
• 毕业指南 — docs/graduation-from-vibe-coding.md（+ 韩语版）：介绍从 Lovable/Bolt/v0 导出内容到 GitHub Actions + 实际部署目标的五步路径，并使用发布/CD/安全审计基础工具。

计划中

• audit_cd 支持 Chrome Web Store、EAS、Railway、Fly 和 GHCR。目前会报告为 unsupported，因为这些目标需要身份验证，或没有公开读取 API。

设计意图

• 一个二进制文件，两种使用方式。 CLI 和 MCP stdio 共用同一个脚手架引擎。由 Argv 决定响应方式。不会为“同一件事由人或 Agent 调用”重复实现逻辑。
• 失败时保持原子性。 提取操作在同级的 .<name>-incomplete-<rand> 目录中进行，只有成功后才重命名为最终路径。网络故障、压缩包损坏或写入不完整，都不会留下半成品目录。
• 将审计作为核心功能。 模板提供安全基线（固定到 SHA 的 gitleaks、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 失败会记录日志，但不会导致操作失败。

非目标

• 在 audit_cd 中完全兼容所有供应商。 没有公开读取 API 的目标会标记为 unsupported，而不是返回看似确定、实际错误的状态。
• 重写应用代码。 毕业流程从匹配的 Starter 中迁移 CI/CD，不会触碰应用代码。
• 通用项目生成器。 模板仅限 6 个公开的 Starter Series 模板。新技术栈会作为新的 Starter 提供，而不是作为 create_project 的标志参数。
• 语义指令偏移或 AI 安全强制执行。 audit_instructions 是一项辅助审查工具，用于检查完全重复、表层重叠和关键词提醒。它不是语义相似度引擎、运行时防护措施、红队测试框架，也不是全面的安全防护检查工具。

快速开始 — CLI

npx starter-series my-package --template npm-package

# Or build from a create-starter checkout:
npm ci
npm run build
node dist/index.js my-package --template npm-package

starter-series — scaffold a project from the Starter Series.

Usage
  starter-series <name> --template <id> [options]
  starter-series audit [path]
  starter-series audit-cd [path]
  starter-series audit-security [path]
  starter-series check [path] [--instructions]
  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

Options
  -t, --template <id>      Template ID (see --list)
  -d, --description <text> One-line project description
  -o, --output-dir <path>  Output directory (default: ./<name>)
      --no-git             Skip "git init" after scaffold
      --output <file>       proof-report output (default: <path>/launch-proof-report.md)
      --stdout              print proof-report Markdown; with --output, also writes the file
      --component <group>   add-component group: ci, security, dependabot, maintenance, all
      --starter <id>        add-component source starter override
      --apply               Write the add-component plan (default is dry-run)
      --force               Overwrite differing component files or guidance
      --list               List templates and exit
  -h, --help               Show help and exit
  -v, --version            Print version and exit

Environment
  CREATE_STARTER_DEBUG=1   Emit verbose stderr logs

可用模板

ID	技术栈
mcp-server	TypeScript + @modelcontextprotocol/sdk + Zod
mcp-server-python	Python + FastMCP
npm-package	Jest + ESLint + OIDC 发布
browser-extension	Chrome/Firefox MV3
vscode-extension	VS Marketplace + Open VSX
docker-deploy	任意语言 + GHCR + SSH

这里只列出的 6 个公开模板可用于生成项目和下载组件。基于旧模板的现有项目仍可接受审计。

运行 starter-series --list（CLI）或调用 list_templates（MCP）可获取权威的最新列表。

从 Lovable / Bolt / v0 毕业

已经在 vibe-coding 平台上构建了可运行的应用，想要迁移到 GitHub Actions 和自己的部署目标？请阅读 docs/graduation-from-vibe-coding.md (한국어) — 这是一条分为 5 步的路径：使用 audit、audit-cd 和 audit-security 诊断仓库，然后从匹配的 Starter 中迁移 CI/CD，而无需重写应用代码。

从源代码安装

git clone https://github.com/starter-series/create-starter
cd create-starter
npm install
npm run build

需要 Node.js ≥22。

在 Claude Desktop 中一键安装

从 Releases 页面 获取最新的 .mcpb 包，并将其拖到 Claude Desktop 设置窗口中。Claude Desktop 会解包其中的 dist/ 和 node_modules/，并将 create-starter 注册为 MCP 服务 — 无需 npm、配置文件或绝对路径。

.mcpb（MCP Bundle，原名 .dxt）是 Anthropic 为 MCP 服务提供的打包扩展格式。请参阅 桌面扩展。

要在本地重新构建该包：

npm ci
npm run bundle:mcpb   # produces create-starter-<version>.mcpb

用作 MCP 服务

在 MCP 客户端（Claude Desktop、Cursor 等）中注册已构建的二进制文件：

{
  "mcpServers": {
    "create-starter": {
      "command": "node",
      "args": ["/absolute/path/to/create-starter/dist/index.js"]
    }
  }
}

然后向 Agent 提出请求：“使用 create-starter 为名为 my-bot 的新 Discord 机器人搭建脚手架。” 如果需要，Agent 会调用 list_templates，然后调用 create_project。

不带额外参数调用时，二进制文件使用 MCP stdio；提供任意位置参数或标志时，则切换到 CLI 模式。两种模式共用同一套脚手架引擎。

用作 Claude Code 插件

该插件同时打包了 MCP 服务和 create 技能——安装一次即可将二者配置到一起。

在 Claude Code REPL 中：

/plugin marketplace add starter-series/create-starter
/plugin install create-starter@starter-series

然后让 Claude：“为名为 my-bot 的新 Discord 机器人搭建脚手架”，create-starter:create 技能会引导对话使用 MCP 工具。

本地开发（无需往返市场）：

claude --plugin-dir /path/to/create-starter

指向一个 Git 克隆，这样在会话启动时，skills/create/SKILL.md 或 dist/index.js 中的修改就会生效。

通过 MCP Registry 使用

发布到 Registry 后，此服务使用 Official MCP Registry 命名空间：

io.github.starter-series/create-starter

集成了 Registry 发现功能的 MCP 兼容客户端可以按名称安装，无需手动配置路径。Registry 条目指向 npm 软件包 starter-series，因此必须等 npm 软件包发布并通过验证后，才能执行 Registry 步骤。

所有权通过 GitHub OIDC（命名空间 io.github.starter-series/*）和 npm tarball 检查（package.json#mcpName）进行验证。有关发布流程，请参阅 .github/workflows/publish-mcp-registry.yml。

有关 npm 发布设置（可信发布者注册，包括 2026-05-20 之后的 allowed-action 步骤），请参阅 docs/RELEASING.md。

工具

脚手架：

• list_templates — 以 JSON 格式返回完整的模板表。
• create_project — 参数：
  • template （必需） — 上方表格中的模板 ID。
  • name （必需） — 项目名称，须匹配 ^[A-Za-z0-9][A-Za-z0-9_-]*$。
  • description （可选） — 单行描述。
  • output_dir （可选） — 默认为相对于 MCP 服务当前工作目录的 ./<name>。相对路径必须位于当前工作目录内；绝对路径视为用户明确指定的路径。
  • init_git （可选，默认值为 true） — 搭建脚手架后运行 git init。

审计（每项都接受可选的 path 参数，默认值为 MCP 服务当前工作目录；均为只读操作）：

• 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 — Agent 指令重复项和覆盖范围审查，并提供关键词风险摘要。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 s 超时、最多 3 次指数退避重试，以及 50 MB 大小上限。
• 解压操作会在同级的 .<name>-incomplete-<rand> 目录中进行；若发生任何故障（网络、压缩包损坏、解压错误），都会删除临时目录。只有全部成功后，才会通过原子 rename 操作使最终路径出现。
• git init 失败时会将错误记录到 stderr，但不会导致脚手架生成失败；即使没有 .git 目录，项目仍可使用。

预先配置的供应链安全措施

每个 Starter Series 模板都预先配置了 audit_security 检查的 9 项检查，无需选择启用：

检查项	检测内容
gitleaks（通过固定 SHA256 手动安装）	代码或历史记录中已提交的密钥
CodeQL（每周运行 + PR）	JS/TS/Python 静态分析
依赖项审计（npm audit --audit-level=moderate / pip-audit）	传递依赖中的已知 CVE
许可证检查	GPL/AGPL 污染
每次 npm/pnpm/yarn install 均使用 --ignore-scripts	恶意 postinstall 脚本
Dependabot 分组更新	逐个升级导致的锁文件冲突风暴
GitHub 密钥扫描 + 推送保护	推送时泄露的令牌
PR 上的 anthropics/claude-code-security-review Action	基于 AI 的差异审查
claude-security-guidance.md （这是唯一需要你编写的文件）	组织特定规则，由 Anthropic 的会话内 Claude Code Security Guidance Plugin（于 2026-05-26 发布）使用

这是 Vercel 在 2026-04-21 npm 供应链事件期间使用的技术栈——他们通过相同的预先配置检查以及 Socket/npm/GitHub 协作，提前防范了攻击。Starter Series 的每个 starter 都预先配置了这些检查。

许可证

MIT © heznpc

指令检查

starter-series check --instructions [path]
starter-series check --instructions [path] --json
starter-series check --instructions [path] --update-state

不带 --instructions 的 check 会运行现有的发布、CD、安全和指令审计。audit-instructions 仍是兼容别名。MCP 客户端继续使用 audit_instructions(path?, update_state?)；库入口仍为 auditInstructions(path?, { updateState? })。

一次扫描会检查 AGENTS/CLAUDE/GEMINI、覆盖规则、Copilot 指令、Cursor 规则、Claude 规则/技能以及 .agents 规则/技能/工作流。检查会报告导入和符号链接别名、逐字镜像、本地覆盖、完全重复内容和跨文件重叠。除非明确配置，否则会根据链接和文件名推断规范来源。不检测语义相似性。绝不会改写指令源文件。

可选的 .starter-series/instructions.json 用于选择规范来源并记录所有者的决定。将 JSON 报告中的确切 id、evidenceHash 和 paths 复制到决定的 id、evidenceHash 和 scope 中；然后明确提供所有者的理由、身份和批准日期：

{
  "schemaVersion": 1,
  "canonical": "AGENTS.md",
  "decisions": []
}

每项决定都需要 reason、approvedBy、approvedAt（YYYY-MM-DD），并且至少需要 reviewAfter、expiresAt（YYYY-MM-DD）或 reviewReason 中的一项。决定仅适用于完全匹配的发现和范围。证据发生变化、决定过期或需要复审时，决定会变为过期；检查器绝不会自动生成批准。已接受的发现仍会显示。此文件用于记录所有者批准，并非身份验证机制。

默认情况下，检查为只读。--update-state（或 MCP update_state: true）会显式保存 .starter-series/instructions-state.json，以便比较新增/变更/已知/已解决的差异。状态文件包含身份信息和证据哈希，不包含指令文本；只有团队需要共享基线时，才应提交该文件。元数据格式错误会导致检查失败。退出代码保持不变：干净结果/提示性结果或已接受的发现返回 0，待处理/需要复审的过期发现返回 1，用法或操作错误返回 2。