一、项目定位与目标

create-starter 是 Starter Series 体系下的脚手架与审计一体化工具，副标题为 "Scaffold and audit Starter Series projects — MCP server, Claude Code skill, and CLI in one package"。它的核心思路是：脚手架只是简单的一半，真正决定一个仓库能否长期可信的是审计原语——audit_release、audit_cd、audit_security——在每次合并前对照已知基线自动核对发布、CD、CI 安全卫生，而不是让人手动复查。

资料来源：README.md

包名 @starter-series/create、当前版本 0.4.0、MCP 注册名为 io.github.starter-series/create-starter，对 GitHub OIDC 命名空间与 npm tarball 双重校验。运行时要求 Node.js ≥ 22，依赖仅 @modelcontextprotocol/sdk、tar、zod 三个运行时包，依赖面刻意收窄以降低供应链风险。

资料来源：package.json:1-15

二、分发形态与统一入口

项目以"一份二进制，多种分发"为架构原则。package.json#bin 暴露 create-starter 可执行文件，主入口与 MCP 服务器入口都指向同一份 dist/index.js，由 argv 分发：

• 存在位置参数 → CLI 模式（create <name> --template <id>、audit、audit-cd、audit-security、seed-security-guidance、add-component 等子命令）。
• 无位置参数 → MCP stdio 服务器模式，对外暴露 list_templates、create_project、audit_release、audit_cd、audit_security、seed_security_guidance、add_component 七个工具。

资料来源：README.md、package.json:13-30

除 npm 之外，项目还提供三种分发：

资料来源：manifest.json、server.json

flowchart LR
    A[npm @starter-series/create] --> B[dist/index.js]
    C[.mcpb Bundle] --> B
    D[Claude Code Plugin] --> B
    B -->|argv present| E[CLI Mode]
    B -->|no argv| F[MCP stdio Mode]
    E --> G[create / audit / add-component]
    F --> H[list_templates / create_project / audit_*]
    G --> I[GitHub starter-series/* tarballs]
    H --> I
    G --> J[Local repo diagnostics]
    H --> J

三、核心工具矩阵与模板注册表

工具矩阵分为两半。脚手架半包含 list_templates 与 create_project：前者返回注册表的完整 JSON，后者负责下载、解压、占位符替换、Python 包重命名与 git init，并附带针对每个模板调优的 cd-then-install 后续步骤。审计半包含 audit_release（版本与 tag 漂移、CHANGELOG 与 git log <tag>..HEAD 漂移、publish workflow 类型识别）、audit_cd（npm / PyPI / Open VSX / VS Marketplace / AMO / GitHub Releases 的逐目的地发布漂移）、audit_security（gitleaks、CodeQL、依赖审计、license 检查、--ignore-scripts 等基线 CI 安全卫生）。

资料来源：manifest.json、README.md、CHANGELOG.md

模板注册表 src/templates.ts 由 Template 接口描述，每个条目含 id、name、repo、ref?、stack、category、默认 name/description 与按语言区分的 postSteps（JS 用 npm install && npm run dev，Python 用 python -m venv .venv && pip install -e '.[dev]'），分类涵盖 mcp / package / bot / app / extension / deploy 六类，共计 11 个模板：mcp-server、mcp-server-python、npm-package、discord-bot、telegram-bot、browser-extension、vscode-extension、electron-app、react-native、cloudflare-pages、docker-deploy。

资料来源：src/templates.ts、README.md

四、协作技能与安全可靠性

Claude Code 侧的 create 技能（skills/create/SKILL.md）约定了调用 create_project 的前置校验：项目名必须匹配 ^[A-Za-z0-9][A-Za-z0-9_-]*$、相对输出路径不得越过 cwd、严禁自行拼 tarball URL 或 git clone——所有下载必须经由 MCP 工具。deploy-setup 技能则接力把脚手架产物从"已生成"推到"首次发布"，按 package.json#mcpName、pyproject.toml 引用、discord.js / grammy 依赖、manifest_version === 3 等信号识别模板，再据此注册 GitHub Secrets 与 OIDC trusted publishing。

资料来源：skills/create/SKILL.md、skills/deploy-setup/SKILL.md

可靠性设计贯彻"失败可回滚"原则：项目名先 regex 校验再触碰文件系统；下载走 30 秒超时、3 次指数退避、50 MB 体积上限；解压在同级 .<name>-incomplete-<rand> 临时目录进行，任一阶段失败即清理，最终路径仅在全部成功后通过原子 rename 暴露。git init 失败仅以 stderr 警告，不阻断脚手架本身。

资料来源：README.md、CONTRIBUTING.md

See Also

• Claude Code create 技能参考
• Claude Code deploy-setup 技能参考
• Starter Series 组织主页

项目定位与核心功能

create-starter（npm 包名 @starter-series/create，当前版本 0.4.0）是一套三重入口的脚手架与审计工具集：单一 TypeScript 二进制根据 argv 自动在 CLI 模式与 MCP stdio 模式之间切换，再叠加 Claude Code 插件市场分发，使同一套引擎同时服务于命令行用户、AI 智能体和编辑器内嵌场景。资料来源：package.json:1-50

核心能力由七个 MCP 工具承载，按职责划分为两组：

资料来源：manifest.json:1-50、README.md:1-50

模板注册表

系统内置 11 个模板，覆盖 MCP 服务器、聊天机器人、浏览器/编辑器扩展、桌面/移动应用、纯前端与 Docker 部署场景。create 技能在文档中明确列出 ID、名称与分类，要求调用方不得自造 ID，必须通过 list_templates 或下表获取权威列表。资料来源：skills/create/SKILL.md:1-50

新模板以独立 starter 仓库的形式托管在 starter-series 组织下，而非作为 create_project 的额外标志位。资料来源：CONTRIBUTING.md:1-50

脚手架流程

create_project 工具的输入约束严格：项目名必须匹配 ^[A-Za-z0-9][A-Za-z0-9_-]*$（字母数字开头，随后仅允许字母数字、下划线、短横线），相对输出路径不得越出 MCP 服务器工作目录，绝对路径则作为显式用户意图被接受。资料来源：skills/create/SKILL.md:1-50、README.md:1-50

下图展示了从用户请求到仓库就绪的关键阶段：

flowchart LR
    A[用户/Agent 调用] --> B[list_templates]
    B --> C[校验 name 与 output_dir]
    C --> D{校验通过?}
    D -- 否 --> Z[返回 isError 错误]
    D -- 是 --> E[下载 tarball<br/>30s timeout · 3 次重试 · 50MB 上限]
    E --> F[解压至 .name-incomplete-rand]
    F --> G[占位符替换<br/>Python 包重命名]
    G --> H[git init]
    H --> I[原子 rename 到 output_dir]
    I --> J[返回 cd-then-install 指令]

任何阶段（网络失败、归档损坏、解压异常）失败都会清理临时目录，只有全部步骤成功后才通过原子 rename 暴露最终路径，避免半成品污染工作区。git init 失败仅以 stderr 警告形式呈现，不阻塞脚手架成功——这意味着即使没有 .git 目录，项目也能被正常使用。资料来源：README.md:1-50

双模式分发与可观测性

MCP 服务器的注册信息通过 server.json 暴露在 MCP Registry 上，命名空间为 io.github.starter-series/*，并通过 OIDC 与 npm tarball 的 package.json#mcpName 字段进行所有权交叉验证；运行时通过 npx @starter-series/create 拉起同一 stdio 进程。资料来源：server.json:1-20、README.md:1-50

Claude Code 插件路径则把 MCP 服务器和 create 技能打包在一起，用户执行 /plugin install create-starter@starter-series 后即可通过自然语言触发脚手架流程。资料来源：skills/create/SKILL.md:1-50

调试可通过环境变量 CREATE_STARTER_DEBUG=1 开启详细 stderr 日志，便于在 Agent 调用链中追踪每一阶段的状态。资料来源：README.md:1-50

安全与可靠性保证

• 输入校验前置：项目名与路径在任何文件系统操作之前完成正则与边界检查。
• 下载弹性：30 秒超时、3 次指数退避重试、50 MB 大小上限。
• 原子性：解压在兄弟目录 .<name>-incomplete-<rand> 中进行；任一阶段失败即清理临时目录。
• 审计闭环：除脚手架外，audit_release 会检测版本与最新 tag 漂移、CHANGELOG.md 的 Unreleased 与 git log <tag>..HEAD 的 PR 引用差异；audit_cd 通过公共只读 API 检查每个发布目的地（npm / PyPI / Open VSX / VS Marketplace / AMO / GitHub Releases）的漂移情况；audit_security 校验 gitleaks、CodeQL、依赖审计、许可证检查与 --ignore-scripts 等 CI 安全基线。资料来源：manifest.json:1-50、src/audit.ts:1-50

See Also

• 审计工具详解（audit_release / audit_cd / audit_security）
• 首次部署配置（deploy-setup 技能）
• 从 Vibe Coding 平台毕业指南

设计意图与作用域

create-starter 将自身定位为「一个二进制，两类交互面」(One binary, two surfaces)：argv 包含 positional 参数或标志时走 CLI，无参数时切换到 MCP stdio，二者共享同一套脚手架与审计引擎。在生成项目之后真正决定仓库是否值得信任的，是随包发布的审计原语 (audit primitives) 与 组件注入 (component injection) 配套工具。审计原语只读，组件注入则负责按需回填，使二者构成「诊断 → 修复」的闭环。

资料来源：README.md:25-39、README.ko.md:135-148

三大只读审计原语

manifest.json 中声明了三个核心审计工具，全部以公开 read API 或本地文件读取为基础，不修改仓库状态。

audit_release 在解析 CHANGELOG 时通过 ISSUE_CLOSE_RE 正则将 Closes #12、Fixes #9 等议题关闭引用排除，再使用 harvestPrRefs 从每一行中收集真正的 PR 编号，使 CHANGELOG Unreleased 段收集到的 PR 集合与 git log <tag>..HEAD 扫描得到的集合保持一一可比。

资料来源：manifest.json:24-38、README.md:74-83、src/audit.ts:9-32

flowchart LR
  A[已 scaffold 的仓库] --> B{audit_release<br/>发布就绪度}
  A --> C{audit_cd<br/>目的地漂移}
  A --> D{audit_security<br/>CI 安全卫生}
  B --> E{是否漂移?}
  C --> E
  D --> E
  E -- 是 --> F[add_component<br/>dry-run 计划]
  E -- 是 --> G[seed_security_guidance<br/>模板化 guidance]
  F --> H{--apply?}
  G --> H
  H -- 否 --> I[保持只读]
  H -- 是 --> J[受控写入]
  J --> K[再次审计，闭环]

安全基线生成

seed_security_guidance 工具 (CLI 镜像为 seed-security-guidance) 根据当前仓库所匹配的 starter 模板，草拟一份 claude-security-guidance.md。它是「诊断」与「修复」之间的桥——既承接 audit_security 暴露的缺口，又把修复方向固化为可在 PR 评审中引用的文档，避免每次都靠人工复述。

• 默认 dry-run：仅产出文档草案而不写入磁盘。
• --force 覆盖：当用户明确希望替换已有 guidance 时使用。
• 模板匹配：通过 package.json、pyproject.toml、manifest.json 等信号文件识别 starter，参见 skills/deploy-setup/SKILL.md 的检测矩阵。

资料来源：README.ko.md:170-178、skills/deploy-setup/SKILL.md:9-26

组件注入 (add_component)

add_component 是审计闭环的「修复」半部，它把 starter 的 CI/CD 组件层移植到现有仓库，而不重新脚手架。组件按组 (group) 分类，便于按需回填：

其核心契约包括：

1. 默认 dry-run：输出文件级计划 create / identical / skip-exists / overwrite，dry-run 报告同时充当与 starter 的漂移报告。
2. 脏工作树保护：存在未提交变更时拒绝执行，除非显式 --force，避免把审计修复与用户未保存的工作混在一起。
3. 冲突保护：已存在但内容不同的文件默认跳过，仅在 --force 时覆盖，强制用户对覆盖后果有意识。
4. 白名单边界：故意不移植 cd*.yml 等可能含 secret 的 CD workflow，攻击面仅限组件层。

CLI 形式：create-starter add-component [path] [--component <group>] [--starter <id>] [--apply] [--force]。--starter 允许显式指定源 starter，覆盖自动检测。

资料来源：CHANGELOG.md:13-22、README.ko.md:182-196

可靠性与未支持目标

所有审计与注入操作共享同一组安全保证：项目名在触碰文件系统前以 ^[A-Za-z0-9][A-Za-z0-9_-]*$ 正则校验；相对输出路径若逃离 cwd 直接拒绝；下载侧 30 秒超时、3 次指数退避、50 MB 大小上限；提取阶段在兄弟目录 .<name>-incomplete-<rand> 中进行，任意步骤失败立即清理 tmp，仅全部成功后以原子 rename 暴露最终路径。

audit_cd 当前已规划但未全部上线的目标包括 Chrome Web Store、EAS、Railway、Fly、GHCR——这些目的地要么需要认证，要么缺乏公开 read API，目前统一以 unsupported 报告，明确告知用户为何未被纳入漂移检测。

资料来源：README.md:87-94、README.ko.md:200-205

See Also

• 模板注册表与脚手架
• MCP 工具与 CLI 双面
• 毕业指南：从 Lovable / Bolt / v0 迁出

create-starter 在仓库内以单一 TypeScript 源码树存在,但对外同时承担 npm CLI、Claude Desktop / Cursor 等 MCP 客户端的 stdio 服务、Claude Code 插件市场条目、可独立分发的 .mcpb 桌面包 四种角色。本页解释这套"一份二进制、多种表层"的发行模型如何拼装、客户端如何集成,以及运维侧的脚本与安全策略。

一、分发渠道与包边界

仓库把"运行所需产物"显式枚举到 package.json#files,确保 npm tarball 不会夹带测试与 CI 配置:

dist, skills, docs/graduation-from-vibe-coding.md,
docs/graduation-from-vibe-coding.ko.md, .claude-plugin,
.mcp.json, README.md, README.ko.md, CHANGELOG.md,
LICENSE, server.json

资料来源：package.json:30-43

安装入口由 bin.create-starter 指向 dist/index.js,并通过 engines.node 强制要求 Node.js ≥ 22,以使用内置的 --no-warnings、fs.cp 等能力。资料来源：package.json:11-21

manifest.json 是 MCP 协议层的描述文件,声明 server.type=node、entry_point=dist/index.js,并把 mcp_config.command 同样指向该二进制,使任意 MCP 客户端可以直接通过 node ${__dirname}/dist/index.js 拉起服务。资料来源：manifest.json:13-25

server.json 则面向 MCP Registry,使用 GitHub OIDC 命名空间 io.github.starter-series/* 作为可信来源,transport.type=stdio,packages[0].identifier=@starter-series/create,确保 Registry 拉到的就是 npm 上同一个包。资料来源：server.json:9-18

二、客户端集成形态

flowchart LR
  A[源码 TypeScript] --> B[tsc 编译]
  B --> C[mark-bin-executable.mjs]
  C --> D[dist/index.js]
  D --> E1[npm @starter-series/create]
  D --> E2[.mcpb 桌面包]
  D --> E3[Claude Code 插件]
  E1 --> F1[CLI: create-starter ...]
  E1 --> F2[MCP stdio: 客户端注册]
  E2 --> F3[Claude Desktop 一键安装]
  E3 --> F4[/plugin install<br/>+ create 技能 + slash commands]

CLI 与 MCP 共用同一进程:无额外参数进入 stdio 模式,出现位置参数或 --template 等开关时进入 CLI 模式。资料来源：README.md:103-118

Claude Desktop 的"一键安装"路径是发布页提供的 .mcpb 文件,由 scripts/bundle-mcpb.mjs 打包,执行 npm run bundle:mcpb 即可生成。该脚本属于"重大改动需先讨论"的边界,因为它影响桌面分发格式。资料来源：CONTRIBUTING.md:23-30 package.json:25-31

Claude Code 端的集成则通过 .claude-plugin/plugin.json 声明插件元数据,.claude-plugin/marketplace.json 注册到 starter-series 市场。用户执行 /plugin marketplace add starter-series/create-starter 之后,create 技能与 scaffold、audit-release 等 slash command 同步生效。资料来源：README.md:118-130 skills/create/SKILL.md:5-18

skills/create/SKILL.md 与 skills/deploy-setup/SKILL.md 两份技能文档明确"绝不直接调用 curl / tar / git clone,只走 MCP 工具"——这是一种刻意约束,把分发与下载细节收敛到服务端二进制里,避免模型在客户端重新实现不安全的下载流程。资料来源：skills/create/SKILL.md:13-22

三、运维脚本与安全策略

构建脚本 scripts/mark-bin-executable.mjs 在 tsc 之后把 dist/index.js 标记为可执行,保证 npx @starter-series/create 在 Unix 系统无需 chmod +x 也能直接运行;npm run lint 即 tsc --noEmit,npm test 用 node --test --import tsx 跑 tests/*.test.ts,不引入额外测试框架。资料来源：package.json:23-31

运维层面的安全约束写在 README 中:项目名通过正则 ^[A-Za-z0-9][A-Za-z0-9_-]*$ 在任何文件系统操作之前验证;相对 output_dir 若逃逸工作目录会被拒绝;下载具备 30 秒超时、3 次指数退避、50 MB 大小上限;解压在同级 .<name>-incomplete-<rand> 临时目录进行,任一步失败即清理,只有全部成功才以原子 rename 暴露最终路径。git init 失败仅以 stderr 警告,不会回滚 scaffold。资料来源：README.md:154-164

publishConfig.access=public 与 publishConfig.provenance=true 配合 npm 的 OIDC trusted publishing,确保发布身份由 GitHub Actions 验证而非长期 token。资料来源：package.json:48-52

四、发布流水线

CHANGELOG.md 是只追加文件,真实权威源在 GitHub Releases:.github/workflows/update-changelog.yml 在每次发布时把新条目预置到文件顶部,使本地镜像与 release feed 不重复维护。audit_release 工具同时扫描此文件以检测 CHANGELOG 与版本号漂移。资料来源：CHANGELOG.md:7-13

MCP Registry 发布由 .github/workflows/publish-mcp-registry.yml 驱动,所有权验证结合 GitHub OIDC 命名空间与 npm tarball 的 package.json#mcpName 字段核对,确保 Registry 条目与 npm 包是同一来源。资料来源：README.md:96-103

See Also

• 快速开始与 CLI 用法
• 审计工具集 (audit / audit-cd / audit-security)
• Lovable/Bolt/v0 毕业指南 (docs/graduation-from-vibe-coding.md)

Pitfall Log / 踩坑日志

项目：starter-series/create-starter

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 create-starter 与安装入口 @starter-series/create 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 复现命令：npx @starter-series/create
• 证据：identity.distribution | https://github.com/starter-series/create-starter | repo=create-starter; install=@starter-series/create

2. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/starter-series/create-starter | host_targets=mcp_host, claude_code, claude

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/starter-series/create-starter | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/starter-series/create-starter | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/starter-series/create-starter | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/starter-series/create-starter | no_demo; severity=medium

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/starter-series/create-starter | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/starter-series/create-starter | release_recency=unknown