# https://github.com/starter-series/create-starter 项目说明书

生成时间：2026-06-22 09:35:36 UTC

## 目录

- [项目概览与系统架构](#page-1)
- [核心功能、模板与脚手架流程](#page-2)
- [审计原语、安全基线与组件注入](#page-3)
- [分发、集成与运维](#page-4)

<a id='page-1'></a>

## 项目概览与系统架构

### 相关页面

相关主题：[核心功能、模板与脚手架流程](#page-2), [审计原语、安全基线与组件注入](#page-3), [分发、集成与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package.json](https://github.com/starter-series/create-starter/blob/main/package.json)
- [manifest.json](https://github.com/starter-series/create-starter/blob/main/manifest.json)
- [server.json](https://github.com/starter-series/create-starter/blob/main/server.json)
- [README.md](https://github.com/starter-series/create-starter/blob/main/README.md)
- [CHANGELOG.md](https://github.com/starter-series/create-starter/blob/main/CHANGELOG.md)
- [CONTRIBUTING.md](https://github.com/starter-series/create-starter/blob/main/CONTRIBUTING.md)
- [src/templates.ts](https://github.com/starter-series/create-starter/blob/main/src/templates.ts)
- [src/audit.ts](https://github.com/starter-series/create-starter/blob/main/src/audit.ts)
- [skills/create/SKILL.md](https://github.com/starter-series/create-starter/blob/main/skills/create/SKILL.md)
- [skills/deploy-setup/SKILL.md](https://github.com/starter-series/create-starter/blob/main/skills/deploy-setup/SKILL.md)
</details>

# 项目概览与系统架构

## 一、项目定位与目标

`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](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)

## 二、分发形态与统一入口

项目以"一份二进制，多种分发"为架构原则。`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](README.md)、[package.json:13-30](package.json)

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

| 分发形态 | 适用场景 | 关键文件 |
|---|---|---|
| CLI (`npx @starter-series/create`) | 终端直接调用 | `dist/index.js` |
| MCP Server (stdio) | Claude Desktop / Claude Code | `server.json`、`manifest.json` |
| `.mcpb` 桌面扩展 | Claude Desktop 拖拽安装 | `scripts/bundle-mcpb.mjs` |
| Claude Code 插件 | `/plugin install create-starter@starter-series` | `.claude-plugin/` |

资料来源：[manifest.json](manifest.json)、[server.json](server.json)

```mermaid
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](manifest.json)、[README.md](README.md)、[CHANGELOG.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](src/templates.ts)、[README.md](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/create/SKILL.md)、[skills/deploy-setup/SKILL.md](skills/deploy-setup/SKILL.md)

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

资料来源：[README.md](README.md)、[CONTRIBUTING.md](CONTRIBUTING.md)

## See Also

- [Claude Code `create` 技能参考](skills/create/SKILL.md)
- [Claude Code `deploy-setup` 技能参考](skills/deploy-setup/SKILL.md)
- [Starter Series 组织主页](https://github.com/starter-series)

---

<a id='page-2'></a>

## 核心功能、模板与脚手架流程

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [审计原语、安全基线与组件注入](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [manifest.json](https://github.com/starter-series/create-starter/blob/main/manifest.json)
- [package.json](https://github.com/starter-series/create-starter/blob/main/package.json)
- [skills/create/SKILL.md](https://github.com/starter-series/create-starter/blob/main/skills/create/SKILL.md)
- [skills/deploy-setup/SKILL.md](https://github.com/starter-series/create-starter/blob/main/skills/deploy-setup/SKILL.md)
- [README.md](https://github.com/starter-series/create-starter/blob/main/README.md)
- [server.json](https://github.com/starter-series/create-starter/blob/main/server.json)
- [CONTRIBUTING.md](https://github.com/starter-series/create-starter/blob/main/CONTRIBUTING.md)
- [src/audit.ts](https://github.com/starter-series/create-starter/blob/main/src/audit.ts)
</details>

# 核心功能、模板与脚手架流程

## 项目定位与核心功能

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

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

| 类别 | 工具 | 职责 |
|---|---|---|
| 脚手架 | `list_templates`、`create_project` | 模板查询与项目生成 |
| 审计 | `audit_release`、`audit_cd`、`audit_security` | 发布就绪、CD 漂移、安全基线诊断 |
| 辅助 | `seed_security_guidance`、`add_component` | 安全指引植入、CI/CD 组件按需迁移 |

资料来源：[manifest.json:1-50]()、[README.md:1-50]()

## 模板注册表

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

| ID | 名称 | 分类 |
|---|---|---|
| `mcp-server` | MCP Server (TypeScript) | mcp |
| `mcp-server-python` | MCP Server (Python) | mcp |
| `npm-package` | npm Package | package |
| `discord-bot` | Discord Bot | bot |
| `telegram-bot` | Telegram Bot | bot |
| `browser-extension` | Browser Extension (MV3) | extension |
| `vscode-extension` | VS Code Extension | extension |
| `electron-app` | Electron App | app |
| `react-native` | React Native (Expo) | app |
| `cloudflare-pages` | Cloudflare Pages | deploy |
| `docker-deploy` | Docker Deploy (language-agnostic) | deploy |

新模板以独立 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]()

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

```mermaid
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 平台毕业指南](docs/graduation-from-vibe-coding.md)

---

<a id='page-3'></a>

## 审计原语、安全基线与组件注入

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [核心功能、模板与脚手架流程](#page-2), [分发、集成与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/audit.ts](https://github.com/starter-series/create-starter/blob/main/src/audit.ts)
- [src/audit-cd.ts](https://github.com/starter-series/create-starter/blob/main/src/audit-cd.ts)
- [src/audit-security.ts](https://github.com/starter-series/create-starter/blob/main/src/audit-security.ts)
- [src/audit-helpers.ts](https://github.com/starter-series/create-starter/blob/main/src/audit-helpers.ts)
- [src/add-component.ts](https://github.com/starter-series/create-starter/blob/main/src/add-component.ts)
- [src/seed-security-guidance.ts](https://github.com/starter-series/create-starter/blob/main/src/seed-security-guidance.ts)
</details>

# 审计原语、安全基线与组件注入

## 设计意图与作用域

`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 或本地文件读取为基础，不修改仓库状态。

| 工具 | 诊断目标 | 关键信号 | CLI 镜像 |
|---|---|---|---|
| `audit_release` | 发布就绪度 | 匹配 starter、版本与最新 tag 漂移、CHANGELOG 与合并 PR 漂移、publish workflow 类型 | `create-starter audit [path]` |
| `audit_cd` | 各目的地发布漂移 | npm、PyPI、Open VSX、VS Marketplace、AMO、GitHub Releases 的公开 API 探测 | `create-starter audit-cd [path]` |
| `audit_security` | CI 安全卫生基线 | gitleaks、CodeQL、依赖审计、license 检查、`--ignore-scripts` 策略 | `create-starter audit-security [path]` |

`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]()

```mermaid
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`](../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) 分类，便于按需回填：

| 分组 | 落地文件 |
|---|---|
| `ci` | `.github/workflows/ci.yml` |
| `security` | `codeql.yml` + `SECURITY.md` |
| `dependabot` | `dependabot.yml` + 自动合并配置 |
| `maintenance` | stale 机器人 + 周度健康检查 |
| `all` | 上述所有 (按依赖顺序) |

其核心契约包括：

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

- [模板注册表与脚手架](templates-and-scaffolding.md)
- [MCP 工具与 CLI 双面](mcp-and-cli-surfaces.md)
- [毕业指南：从 Lovable / Bolt / v0 迁出](graduation-from-vibe-coding.md)

---

<a id='page-4'></a>

## 分发、集成与运维

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [审计原语、安全基线与组件注入](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package.json](https://github.com/starter-series/create-starter/blob/main/package.json)
- [manifest.json](https://github.com/starter-series/create-starter/blob/main/manifest.json)
- [server.json](https://github.com/starter-series/create-starter/blob/main/server.json)
- [scripts/bundle-mcpb.mjs](https://github.com/starter-series/create-starter/blob/main/scripts/bundle-mcpb.mjs)
- [scripts/mark-bin-executable.mjs](https://github.com/starter-series/create-starter/blob/main/scripts/mark-bin-executable.mjs)
- [.claude-plugin/marketplace.json](https://github.com/starter-series/create-starter/blob/main/.claude-plugin/marketplace.json)
- [.claude-plugin/plugin.json](https://github.com/starter-series/create-starter/blob/main/.claude-plugin/plugin.json)
- [.claude-plugin/commands/scaffold.md](https://github.com/starter-series/create-starter/blob/main/.claude-plugin/commands/scaffold.md)
- [.claude-plugin/commands/audit-release.md](https://github.com/starter-series/create-starter/blob/main/.claude-plugin/commands/audit-release.md)
- [skills/create/SKILL.md](https://github.com/starter-series/create-starter/blob/main/skills/create/SKILL.md)
- [skills/deploy-setup/SKILL.md](https://github.com/starter-series/create-starter/blob/main/skills/deploy-setup/SKILL.md)
- [README.md](https://github.com/starter-series/create-starter/blob/main/README.md)
- [CHANGELOG.md](https://github.com/starter-series/create-starter/blob/main/CHANGELOG.md)
- [CONTRIBUTING.md](https://github.com/starter-series/create-starter/blob/main/CONTRIBUTING.md)
</details>

# 分发、集成与运维

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

## 一、分发渠道与包边界

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

```text
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](https://modelcontextprotocol.io),使用 GitHub OIDC 命名空间 `io.github.starter-series/*` 作为可信来源,`transport.type=stdio`,`packages[0].identifier=@starter-series/create`,确保 Registry 拉到的就是 npm 上同一个包。资料来源：[server.json:9-18]()

## 二、客户端集成形态

```mermaid
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)](#)

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: starter-series/create-starter; human_manual_source: deepwiki_human_wiki -->