# Auto Convert Project To Open Source

> 自动将任意内部/私有项目转化为生产级开源项目。 触发词："open source", "开源", "开源化", "重构为开源项目", "prepare for open source"。 支持任何语言、任何框架、任何项目类型。

- Skill: `breath57/auto-convert-project-to-open-source` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add breath57/auto-convert-project-to-open-source`
- Raw SKILL.md: https://api.skillmd.com/api/skills/breath57/auto-convert-project-to-open-source/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: breath57 (https://skillmd.com/u/breath57)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/breath57/auto-convert-project-to-open-source

---


# 自动转换项目为开源项目

## 📏 回复格式（硬性要求）

**你的每一条消息，必须以下面这个进度条代码块开头。没有例外，没有跳过，没有省略。**

进度条是你的回忆锚——输出它就是在回顾"我做到哪了"。不输出就会跑题。

````
```
📊 开源化进度 [项目名] ─ 目标级别：L?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Phase 0 ⬜ 项目复制
Phase 1 ⬜ 深度分析           ← STOP：呈现报告，等用户确认
Phase 2 ⬜ 方案提议 & 用户确认 ← STOP：等用户选级别
Phase 3 ⬜ 重构计划           ← STOP：等用户审查计划
Phase 4 ⬜ 初始化追踪
Phase 5 ⬜ 执行重构           ← STOP：不确定项问用户
  ├─ 5.1 ⬜ 安全清理
  ├─ 5.2 ⬜ 深度瘦身
  ├─ 5.3 ⬜ 代码整理
  ├─ 5.4 ⬜ 结构规范化
  ├─ 5.5 ⬜ 依赖清理
  ├─ 5.6 ⬜ 文档（不含 README）
  ├─ 5.7 ⬜ CI/CD
  ├─ 5.8 ⬜ 测试补充
  └─ 5.9 ⬜ Git 准备
Phase 6 ⬜ 测试验证           ← STOP：报告结果，等用户确认
Phase 7 ⬜ README & 最终审查   ← STOP：收集素材，讨论风格
Phase 8 ⬜ 后续操作
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
进度：0/25 (0%) | 当前：未开始
```
````

图标：✅ 完成 | 🔄 进行中 | ⬜ 未开始 | ⏭️ 跳过 | ❌ 失败

随着工作推进，更新每行的图标。当前阶段用 `🔄`，当前步骤用 `← 当前`。

---

## 📋 核心规则

1. **绝不修改原项目** — 始终在副本上操作
2. **5 个 STOP 点必须停下等用户** — 不能替用户做任何决定
3. **进度追踪** — 全程维护 `.process.json` 和 `.checklist.json`
4. **测试驱动** — 改完必须测试通过
5. **.gitignore 保护** — 被 .gitignore 排除的文件无需删除
6. **极致瘦身** — 不确定的问用户，确认不要的坚决删

防遗忘机制详见 [references/anti-drift.md](references/anti-drift.md)。

---

## Phase 0: 项目复制

运行 `bash scripts/copy-project.sh` 复制项目（排除 .git/）。后续所有操作仅在副本中进行。

Phase 0 完成后你的回复必须像这样：

> ````
> ```
> 📊 开源化进度 [my-project] ─ 目标级别：待定
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> Phase 0 ✅ 项目复制
> Phase 1 🔄 深度分析           ← 当前
> ...其余 Phase 为 ⬜...
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> 进度：1/25 (4%) | 当前：Phase 1 深度分析
> ```
>
> 项目已复制到 `my-project-auto-convert-open-source/`，共 XX 个文件。原始项目不会被修改。
>
> 正在开始深度分析...
> ````

---

## Phase 1: 深度分析

### 1.1 项目识别
检测语言/框架、构建系统、项目类型、现有文档和测试。

### 1.2 文件清单
按类型统计文件，标记大文件（>1MB）、构建产物、日志、缓存、临时文件。

### 1.3 敏感信息扫描
运行 `bash scripts/scan-secrets.sh $TARGET_DIR`，详细模式见 [references/sensitive-patterns.md](references/sensitive-patterns.md)。

**.gitignore 保护规则：**
- 已被 .gitignore 保护 → 标注"无需删除"
- 未被 .gitignore 保护 → 标记"需处理"
- 代码中硬编码 → 标记"必须清理"

### 1.4 代码质量评估
死代码、重复、命名、错误处理、类型注解、依赖健康度。

### 1.5 结构评估
是否遵循语言约定、源码/测试/文档是否分离、入口点是否清晰。

### 1.6 测试状况评估
运行现有测试，记录覆盖率，标记缺失测试的关键模块。

### 1.7 深度瘦身扫描
按 [references/deep-pruning.md](references/deep-pruning.md) 执行地毯式扫描：
- **文件级**：逐目录审查，分为核心/明确丢弃/建议丢弃/不确定
- **代码逻辑级**：未引用代码、内部专用逻辑、冗余实现、注释代码块
- **测试级**：冗余测试、过时测试、内部集成测试

### 🚫 STOP-1：Phase 1 完成后，必须停下来

**完成 1.1-1.7 后，你这条消息到此结束，等用户回复。**

你的回复必须像这样：

> ````
> ```
> 📊 开源化进度 [my-project] ─ 目标级别：待定
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> Phase 0 ✅ 项目复制
> Phase 1 ✅ 深度分析           ← 刚完成，等待确认
> Phase 2 ⬜ 方案提议 & 用户确认
> ...其余为 ⬜...
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> 进度：2/25 (8%) | 等待用户确认分析报告
> ```
>
> ## 分析报告
>
> **项目概况：** Python 项目，使用 uv 管理依赖...
> **文件统计：** 共 120 个文件，其中 15 个大于 1MB...
> **敏感信息：** 发现 3 处硬编码密钥，2 个 .env 文件（已被 .gitignore 保护）...
> **代码质量：** 5 个未使用导入，2 段注释代码块...
> **测试状况：** 现有 23 个测试，通过 20 个，失败 3 个...
>
> ## 瘦身扫描结果
>
> | 分类 | 文件数 |
> |------|--------|
> | 核心保留 | 45 |
> | 明确丢弃 | 30 |
> | 建议丢弃 | 12 |
> | 待确认 | 5 |
>
> **建议丢弃清单：**
> 1. `scripts/internal_deploy.sh` — 内部部署脚本
> 2. `src/legacy/old_parser.py` — 已被 new_parser.py 替代
> ...
>
> **请审查以上分析报告和瘦身扫描结果。有问题随时提出，确认后我进入方案提议阶段。**
> ````

**❌ 禁止在这条消息之后继续写 Phase 2 的内容。必须等用户回复。**

---

## Phase 2: 方案提议 & 用户确认

### 确定目标级别

向用户展示三个级别，**让用户选**：

| 级别 | 范围 |
|------|------|
| **L1 基础** | 安全 + License + README + .gitignore |
| **L2 标准** | L1 + 代码整理 + 测试 + CI + CONTRIBUTING |
| **L3 专业** | L2 + API 文档 + 架构文档 + 示例 + 徽章 |

### 方案分组
1. **必须做** — 安全、License、README
2. **应该做** — 代码整理、结构规范化、测试
3. **可以做** — API 文档、徽章、高级 CI

### 项目命名推荐
评估当前项目名是否适合开源。如果不够好（太内部、太长、含公司名、不易搜索），推荐 3-5 个备选名，说明理由。考虑：
- 简洁好记、易拼写
- 体现项目核心功能
- 在 PyPI/npm/crates.io 上未被占用（如能检查）
- 不与知名项目重名

### 瘦身清单最终确认
基于 Phase 1.7 报告，列出所有"建议丢弃"和"不确定"项，让用户逐条确认。

### 🚫 STOP-2：等用户选级别、确认项目名和方案

你的回复必须像这样：

> ````
> ```
> 📊 开源化进度 [my-project] ─ 目标级别：待定
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> Phase 0 ✅ 项目复制
> Phase 1 ✅ 深度分析
> Phase 2 🔄 方案提议 & 用户确认 ← 等待用户选择
> ...其余为 ⬜...
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> 进度：3/25 (12%) | 等待用户选择目标级别
> ```
>
> ## 方案提议
>
> **必须做：** 清理 3 处硬编码密钥、添加 LICENSE、生成 README...
> **应该做：** 移除 5 个死代码文件、补充核心模块测试...
> **可以做：** API 文档、GitHub Actions CI...
>
> ## 需要您决定
>
> **1. 请选择目标级别：L1（基础）/ L2（标准）/ L3（专业）？**
>
> **2. 项目命名：** 当前项目名是 `my-project`。作为开源项目，建议考虑：
> - `fastparse` — 简洁，体现核心能力
> - `pyparse-x` — 带语言前缀，易检索
> - `streamparse` — 体现流式处理特点
> 您觉得哪个好？或者保留原名 / 告诉我您的想法。
>
> **3. 瘦身清单确认（逐条回复 ✅ 删 或 ❌ 留）：**
> - `scripts/internal_deploy.sh` — 内部部署脚本，删？
> - `src/legacy/old_parser.py` — 已被替代，删？
> - `utils/data_migration.py` — 不确定是否使用，删？
>
> **4. 测试策略：现有 23 个测试覆盖核心模块的 60%，是否需要补充？**
> ````

**❌ 禁止自己替用户选级别。必须等用户明确回复。**

---

## Phase 3: 重构计划 & 二次确认

生成 `$TARGET_DIR/.plan.md`，模板见 [references/tracking-templates.md](references/tracking-templates.md)。

包含：详细步骤（文件级细节）、文件操作摘要、风险评估、测试验证计划。

### 🚫 STOP-3：展示计划，等用户确认

你的回复必须像这样：

> ````
> ```
> 📊 开源化进度 [my-project] ─ 目标级别：L2
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> Phase 0 ✅ 项目复制
> Phase 1 ✅ 深度分析
> Phase 2 ✅ 方案确认（L2 标准）
> Phase 3 ✅ 重构计划           ← 刚完成，等待审查
> Phase 4 ⬜ 初始化追踪
> ...其余为 ⬜...
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> 进度：5/25 (20%) | 等待用户审查重构计划
> ```
>
> ## 重构计划摘要
>
> `.plan.md` 已生成，共 15 个步骤：
>
> **文件操作：**
> - 删除 30 个文件（构建产物、日志、内部脚本）
> - 创建 5 个文件（LICENSE, CONTRIBUTING.md, .env.example...）
> - 修改 12 个文件（清理密钥、移除死代码...）
>
> **风险点：**
> - `src/core.py` 重构可能影响 3 个测试
>
> **请审查以上重构计划。确认后我开始执行，需要调整什么？**
> ````

**❌ 禁止生成计划后直接开始执行。必须等用户说"确认"或"继续"。**

---

## Phase 4: 初始化追踪文件

运行 `bash scripts/init-tracking.sh $TARGET_DIR {用户选的级别}`，创建 `.process.json` 和 `.checklist.json`。

模板见 [references/tracking-templates.md](references/tracking-templates.md)。这一步是纯技术操作，不需要等用户确认，直接继续 Phase 5。

---

## Phase 5: 执行重构

每步完成后：更新 .process.json → 输出 "✅ 步骤 X.Y 完成"

Phase 5 执行过程中，你的每条回复必须像这样（进度条持续更新）：

> ````
> ```
> 📊 开源化进度 [my-project] ─ 目标级别：L2
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> Phase 0 ✅ 项目复制
> Phase 1 ✅ 深度分析
> Phase 2 ✅ 方案确认
> Phase 3 ✅ 重构计划
> Phase 4 ✅ 初始化追踪
> Phase 5 🔄 执行重构           ← 当前阶段
>   ├─ 5.1 ✅ 安全清理
>   ├─ 5.2 🔄 深度瘦身          ← 当前步骤
>   ├─ 5.3 ⬜ 代码整理
>   ...
> Phase 6 ⬜ 测试验证
> ...
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> 进度：12/25 (48%) | 当前：5.2 深度瘦身
> ```
>
> ✅ 步骤 5.1 完成：安全清理
> - 替换了 3 处硬编码密钥为占位符
> - 创建了 .env.example
> - 二次扫描确认无遗漏
>
> 🔄 开始步骤 5.2：深度瘦身...
> ````

### 5.1 安全清理（始终第一步）
- 硬编码密钥 → 替换为占位符（`YOUR_API_KEY_HERE`）
- 未被 .gitignore 的敏感文件 → 添加到 .gitignore + 创建 .env.example
- 已被 .gitignore 保护 → 不删除，仅标注
- 完成后重新运行 `scripts/scan-secrets.sh` 确认无遗漏

### 5.2 深度瘦身
按 [references/deep-pruning.md](references/deep-pruning.md) 分三层执行：
1. 文件级瘦身 → 2. 代码逻辑瘦身 → 3. 测试瘦身

**每批删除后立即运行测试验证。** 失败则检查是否误删。

### 🚫 STOP-4：遇到不确定项，停下来问用户

执行瘦身时，遇到"建议丢弃"或"不确定"的文件/代码，**必须停下来问用户**。

你的回复必须像这样：

> ````
> ```
> 📊 开源化进度 [my-project] ─ 目标级别：L2
> ...Phase 5 🔄 → 5.2 🔄 深度瘦身...
> 进度：13/25 (52%) | 等待用户确认瘦身项
> ```
>
> 瘦身进行中，发现以下不确定项需要您决定：
>
> 1. `utils/metrics_collector.py` — 似乎只被内部监控调用。**删还是留？**
> 2. `tests/test_performance.py` — 依赖内部基准服务器。**删还是留？**
> 3. `src/adapters/internal_auth.py` L45-L80 — 内部 SSO 对接逻辑。**移除还是保留？**
> ````

**❌ 禁止自行决定删除不确定文件。**

### 5.3 代码整理
死代码、未使用导入、调试打印、TODO/FIXME 注释。

### 5.4 结构规范化
按语言约定重组，修复导入路径，**重组后立即验证构建**。

### 5.5 依赖清理
移除未使用依赖，重新生成锁文件。

### 5.6 文档生成（不含 README）
按目标级别生成除 README 外的文档。模板见 [references/project-standards.md](references/project-standards.md)。

**⚠️ README.md 不在此步生成。** README 必须在所有重构完成、测试通过后，基于最终代码在 Phase 7 生成。

| 文件 | L1 | L2 | L3 |
|------|----|----|---- |
| LICENSE | 必须 | 必须 | 必须 |
| .gitignore | 必须 | 必须 | 必须 |
| CONTRIBUTING.md | — | 必须 | 必须 |
| CHANGELOG.md | — | 可选 | 必须 |
| CODE_OF_CONDUCT.md | — | 可选 | 必须 |
| SECURITY.md | — | — | 必须 |

### 5.7 CI/CD 配置（如在范围内）
GitHub Actions 工作流，模板见 [references/project-standards.md](references/project-standards.md)。

### 5.8 测试补充（如在计划中）
按 Phase 2 测试策略补充缺失测试。

### 5.9 Git 准备
完善 .gitignore，准备初始提交消息。不执行 `git init`。

### 不确定性处理
- 低风险（`__pycache__`、`.DS_Store`）→ 直接处理
- 中风险（可能被引用）→ **停下来问用户**
- 高风险（核心逻辑）→ **停下来讨论**

---

## Phase 6: 测试 & 验证

> 任何重构不通过测试验证都不算完成。

1. **运行全部测试** — 记录通过/失败/跳过数
2. **失败测试处理** — 分析原因，修复后重跑。**绝不跳过失败测试。**
3. **构建验证** — 从零安装/构建
4. **入口点验证** — 主入口和示例代码
5. **Lint 检查** — 运行 Linter（如有）
6. **敏感信息二次扫描** — 运行 `scripts/scan-secrets.sh`
7. **文档验证** — 链接有效、示例准确、安装步骤可用

### 🚫 STOP-5：报告测试结果，等用户确认

你的回复必须像这样：

> ````
> ```
> 📊 开源化进度 [my-project] ─ 目标级别：L2
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> Phase 0 ✅ 项目复制
> Phase 1 ✅ 深度分析
> Phase 2 ✅ 方案确认
> Phase 3 ✅ 重构计划
> Phase 4 ✅ 初始化追踪
> Phase 5 ✅ 执行重构
> Phase 6 ✅ 测试验证           ← 刚完成，等待确认
> Phase 7 ⬜ 最终审查
> Phase 8 ⬜ 后续操作
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> 进度：22/25 (88%) | 等待用户确认测试结果
> ```
>
> ## 测试 & 验证报告
>
> | 项目 | 结果 |
> |------|------|
> | 测试 | ✅ 20 通过 / 0 失败 / 2 跳过 |
> | 构建 | ✅ 从零安装成功 |
> | 入口点 | ✅ `python -m myproject` 正常 |
> | Lint | ✅ 无错误 |
> | 敏感信息 | ✅ 二次扫描干净 |
> | 文档 | ✅ 链接有效 |
>
> **测试和验证结果如上。是否需要补充测试或修复问题？确认后进入最终审查。**
> ````

**❌ 禁止测试跑完直接进入 Phase 7。必须等用户回复。**

---

## Phase 7: README 生成 & 最终审查

README 是开源项目的门面，必须基于**最终代码**生成，不能在重构中途提前写。

### 🚫 STOP-6：收集 README 素材，讨论风格

写 README 之前，先问用户要素材。你的回复必须像这样：

> ````
> ```
> 📊 开源化进度 [my-project] ─ 目标级别：L2
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> Phase 0-6 ✅ 全部完成
> Phase 7 🔄 README & 最终审查   ← 当前
> Phase 8 ⬜ 后续操作
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> 进度：23/27 (85%) | 等待用户提供 README 素材
> ```
>
> 所有重构已完成，测试已通过。现在来写 README——项目的门面。
>
> **在我开始之前，请提供以下素材（有多少给多少，没有也行）：**
>
> 1. **项目 Logo** — 放到 `assets/` 或 `docs/images/` 目录下
> 2. **截图 / 效果图** — 运行效果、界面截图、架构图等
> 3. **Demo GIF** — 使用演示的动图
> 4. **一句话介绍** — 您希望怎么描述这个项目的核心价值？
> 5. **README 风格偏好：**
>    - A. 简洁技术风（直奔主题，像 `httpx`、`ruff`）
>    - B. 完整文档风（详细说明，像 `fastapi`）
>    - C. 视觉吸引风（徽章+GIF+截图，像 `rich`）
>    - D. 参考某个具体项目？
>
> 没有素材也没关系，我会基于代码生成所有内容。
> ````

**❌ 禁止不问用户就直接写 README。**

### 7.1 生成 README

收到用户回复后，基于**最终代码**从零写 README.md：
- 旧 README 如果内容过时 → 直接删掉重写，不要修修补补
- 内容必须基于真实的目录结构、API、入口点、安装方式
- 用户提供了 logo/截图 → 在 README 中正确引用路径
- 安装步骤必须与 Phase 6 验证过的一致
- 如果 Phase 2 确定了新项目名 → README 使用新名称
- README 结构参考 [references/project-standards.md](references/project-standards.md)

### 7.2 最终检查清单

1. 遍历 `.checklist.json` 逐项验证
2. 审查 `.process.json` 确认所有步骤完成
3. 呈现最终报告（创建/删除/修改文件数、测试结果、安全扫描状态）

---

## Phase 8: 后续操作

询问用户需要哪些后续操作：
1. 新仓库初始化（`git init` + 初始提交）
2. 如果 Phase 2 确定了新项目名，重命名目录
3. 远程仓库设置（如 GitHub CLI 可用）
4. 清理追踪文件（.process.json、.checklist.json、.plan.md）

---

## 中断恢复

如果存在 `.process.json`：读取进度 → 报告给用户 → 确认后继续。

---

## 参考文件

| 文件 | 内容 |
|------|------|
| [references/anti-drift.md](references/anti-drift.md) | 6 大防遗忘 & 防跑题机制（含进度条模板） |
| [references/deep-pruning.md](references/deep-pruning.md) | 深度瘦身扫描指南（扫描项 + 报告模板 + 执行清单） |
| [references/tracking-templates.md](references/tracking-templates.md) | .process.json / .checklist.json / .plan.md 模板 |
| [references/sensitive-patterns.md](references/sensitive-patterns.md) | 敏感信息扫描模式大全 |
| [references/project-standards.md](references/project-standards.md) | 开源项目结构标准和 README/CI 模板 |
| [references/cleanup-checklist.md](references/cleanup-checklist.md) | 按类别的详细清理检查清单 |

## 脚本

| 脚本 | 用途 |
|------|------|
| [scripts/copy-project.sh](scripts/copy-project.sh) | 复制项目到工作目录（排除 .git） |
| [scripts/scan-secrets.sh](scripts/scan-secrets.sh) | 扫描敏感信息（密钥/路径/IP/连接串） |
| [scripts/init-tracking.sh](scripts/init-tracking.sh) | 初始化 .process.json 和 .checklist.json |