Skip to content

Commit 32b457b

Browse files
i-stacki-stack
committed
docs: 可移植性与社区生态提升方法论 Playbook
- docs/playbooks/portability-ecosystem.md: P0-P3 完整方法论 - 问题诊断清单 / 优先级与 ROI 矩阵 / 里程碑模板 - 每阶段实施指南（含代码示例） - 常见反模式与适用场景判断 - docs/.vitepress/config.ts: 导航栏加入 Playbooks - .gitignore: 忽略 VitePress dist + .temp 构建产物
1 parent b2cad39 commit 32b457b

3 files changed

Lines changed: 251 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,5 +15,10 @@ env/secrets.json
1515
.codex/
1616
.claude/
1717
node_modules/
18+
19+
# VitePress build output (generated by CI)
20+
docs/.vitepress/dist/
21+
docs/.vitepress/.temp/
22+
1823
skills-engineering/ios-engineer/evolution/usage/*
1924
!skills-engineering/ios-engineer/evolution/usage/usage.jsonl

‎docs/.vitepress/config.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ export default defineConfig({
2323
nav: [
2424
{ text: 'Home', link: '/' },
2525
{ text: 'iOS Engineer', link: '/ios-engineer/' },
26+
{ text: 'Playbooks', link: '/playbooks/portability-ecosystem' },
2627
{ text: 'GitHub', link: 'https://github.com/i-stack/ai-coding-kit' },
2728
],
2829

@@ -38,6 +39,15 @@ export default defineConfig({
3839
],
3940
},
4041
],
42+
'/playbooks/': [
43+
{
44+
text: 'Playbooks',
45+
collapsed: false,
46+
items: [
47+
{ text: '可移植性与社区生态提升', link: '/playbooks/portability-ecosystem' },
48+
],
49+
},
50+
],
4151
},
4252

4353
socialLinks: [

‎docs/playbooks/portability-ecosystem.md‎

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
# 可移植性与社区生态提升方法论
2+
3+
> 本文档记录了 ai-coding-kit 从「内部工具」到「社区可复用项目」的 4 阶段实践（P0–P3）。
4+
> 其他项目可直接复用「优先级与 ROI 矩阵」「问题诊断清单」「里程碑模板」。
5+
6+
---
7+
8+
## 问题诊断清单
9+
10+
在开始改造前，用以下清单快速扫描项目薄弱点：
11+
12+
| 维度 | 检查项 | 诊断手段 |
13+
|------|--------|----------|
14+
| **平台覆盖** | 支持几个 AI 编码平台？目标用户用哪些？ | 统计 `SYNC_TARGETS` 或平台配置数 |
15+
| **语言锁定** | 内容是否强制单一语言？是否阻断了非母语用户？ | grep 输出语言相关规则 |
16+
| **安装体验** | 用户如何安装？是否有包管理器支持？ | 检查是否存在 `brew`/`npm`/`pip` 等入口 |
17+
| **版本管理** | 是否有 Git Tag / Release Notes？用户能否 pin 版本？ | `git tag --list` |
18+
| **CI/CD** | 是否有自动化质量门禁？每次变更是否自动校验？ | 检查 `.github/workflows/` |
19+
| **贡献体系** | 外部贡献者是否知道如何参与？ | 检查 `CONTRIBUTING.md` / `CODEOWNERS` |
20+
| **文档可发现性** | 用户能否通过搜索引擎找到文档？ | Google 搜索项目名 |
21+
| **硬编码路径** | 是否存在个人机器路径？其他人 clone 后能否直接运行？ | `grep -r '/Users/' --include="*.sh"` |
22+
23+
---
24+
25+
## 优先级与 ROI 矩阵
26+
27+
| 优先级 | 任务 | 工作量 | 影响面 | ROI | 适用于 |
28+
|--------|------|--------|--------|-----|--------|
29+
| **P0** | CI 自动验证流水线（规则一致性 / 场景校验 / 新鲜度审计 / 硬编码扫查） | 2h | 每次 PR 自动拦截回归 | 🔴 极高 | 所有含自动化脚本的项目 |
30+
| **P0** | 清理硬编码路径 + CI grep 守卫 | 0.5h | 消除"clone 后报错" | 🔴 极高 | 存在 shell 脚本或个人路径配置的项目 |
31+
| **P1** | CONTRIBUTING.md + CODEOWNERS | 1h | 打通社区参与通道 | 🟠 高 | 所有公开仓库 |
32+
| **P1** | i18n 分层：元指令层英文化 + 治理层翻译 | 4h | 解锁国际用户 | 🟠 高 | 内容驱动型项目（Agent Skill / 文档 / 规则体系） |
33+
| **P2** | Git Tag + Release Notes + CHANGELOG | 1h | 外部可 pin 版本 | 🟡 中 | 所有发布型项目 |
34+
| **P2** | Homebrew Formula / npm package / 包管理器分发 | 2h | 扩大安装渠道 | 🟡 中 | CLI 工具 / 可安装技能包 |
35+
| **P3** | VitePress / Docusaurus 文档站 + GitHub Pages 部署 | 3h | 搜索引擎可发现，降低学习曲线 | 🟢 锦上添花 | 含技术文档的公开仓库 |
36+
| **P3** | 多语言文档站（中/英） | 2h | 覆盖非英语开发群体 | 🟢 锦上添花 | 文档量大的项目 |
37+
38+
### ROI 计算逻辑
39+
40+
- **P0（立即止血）**：不改则持续漏血。CI 缺失 → 每个合并都可能引入回归；硬编码路径 → 每个新贡献者 clone 后第一步就失败。
41+
- **P1（快速见效）**：改动小但打开流量入口。国际化让潜在用户数放大 10–100 倍；CONTRIBUTING 让外部开发者从"看了不会做"变为"照着文档即可提交 PR"。
42+
- **P2（基础设施）**：不是紧急项但一旦上线就会持续产生价值（每个新用户都会走包管理器安装）。
43+
- **P3（放大收益）**：锦上添花，适合 P0+P1 完成后再做。文档站让内容可被 Google 索引，带来有机用户增长。
44+
45+
---
46+
47+
## 实施指南
48+
49+
### P0 — CI 自动验证
50+
51+
**核心原则**：每次 PR 都应触发自动化校验，无需人工介入。
52+
53+
```yaml
54+
# .github/workflows/validate.yml 关键 Job
55+
validate:
56+
- 规则 ID 双向一致性（定义文件 ↔ 入口文件）
57+
- 场景规格校验（JSON/Markdown schema）
58+
- 参考文件新鲜度审计（last-verified 日期扫描）
59+
- 使用台账校验
60+
- 演进流水线完整校验（跳过需运行时环境的步骤）
61+
62+
hardcoded-paths:
63+
- 扫描所有提交文件，正则匹配 '/Users/' 个人路径
64+
- 白名单排除模板路径（如 '/Users/you/...'）
65+
```
66+
67+
**适用条件**：项目有自动化脚本（shell/python）即可，不挑语言栈。
68+
69+
### P0 — 硬编码路径清理
70+
71+
**常见硬编码模式**：
72+
73+
```bash
74+
# ❌ 坏
75+
PROJECT_PATH="/Users/song/Desktop/iOS/MyApp"
76+
# ✅ 好
77+
PROJECT_PATH="${PROJECT_PATH:-~/path/to/your/project}"
78+
```
79+
80+
**CI 挡板**：
81+
82+
```bash
83+
find . -type f -not -path './.git/*' -print0 \
84+
| xargs -0 grep -n '/Users/' \
85+
| grep -v '/Users/you/' \
86+
| grep -v '/Users/YourName/'
87+
```
88+
89+
### P1 — i18n 分层架构
90+
91+
**核心设计**：不移动现有文件，以镜像层叠加。
92+
93+
```
94+
project/
95+
├── SKILL.md # 元指令层 → 英文（路由/优先级/判据）
96+
├── references/ # 中文源文件（不移动）
97+
│ └── rule_index.md
98+
└── i18n/
99+
└── en-US/ # 英文镜像层
100+
└── references/
101+
└── rule_index.md
102+
```
103+
104+
**翻译优先级**：
105+
1. 治理层文件（rule_index / self_evolution / cognitive_adversary_mode）—— 理解体系运作的入口
106+
2. 架构概述（architecture_and_network / architecture_analysis）—— 高频引用
107+
3. 其余领域 reference —— 按引用频率排序
108+
109+
**IR-001 语义升级**：
110+
```
111+
旧: 强制中文输出
112+
新: 输出语言与用户输入语言一致（auto-match）
113+
```
114+
115+
### P1 — 贡献指南
116+
117+
`CONTRIBUTING.md` 必备板块：
118+
119+
```markdown
120+
## 新增 Reference（提案驱动）
121+
1. 创建 proposal
122+
2. 实现 + 校验
123+
3. 提交 PR
124+
125+
## 翻译贡献
126+
1. 在 i18n/{locale}/ 创建对应文件
127+
2. 保持结构一致
128+
3. CI 自动校验中英文件数量
129+
130+
## Commit 规范
131+
feat / fix / ref / evolve / chore / docs
132+
```
133+
134+
### P2 — 包管理器分发
135+
136+
**Homebrew Formula 要素**：
137+
138+
```ruby
139+
class MyProject < Formula
140+
desc "One-line description"
141+
homepage "https://github.com/user/repo"
142+
url "https://github.com/user/repo/archive/refs/tags/v1.0.0.tar.gz"
143+
license "MIT"
144+
145+
def install
146+
prefix.install Dir["*"]
147+
bin.install_symlink prefix/"run.sh" => "myproject"
148+
end
149+
end
150+
```
151+
152+
**npm package.json 要素**：
153+
154+
```json
155+
{
156+
"name": "@scope/pkg",
157+
"version": "1.0.0",
158+
"bin": { "myproject": "./run.sh" },
159+
"files": ["src/", "run.sh", "README.md"],
160+
"keywords": ["relevant", "search", "terms"]
161+
}
162+
```
163+
164+
### P3 — 文档站
165+
166+
**VitePress 最小启动**：
167+
168+
```bash
169+
mkdir docs && cd docs
170+
# 创建 .vitepress/config.ts + index.md
171+
npm install -D vitepress
172+
npm run docs:dev # 本地预览
173+
npm run docs:build # 构建静态站
174+
```
175+
176+
**GitHub Pages 自动部署**：
177+
178+
```yaml
179+
# .github/workflows/deploy-docs.yml
180+
on:
181+
push:
182+
paths: ['docs/**', 'package.json']
183+
184+
jobs:
185+
build:
186+
steps:
187+
- uses: actions/setup-node@v4
188+
with: { node-version: 22 }
189+
- run: npm ci && npm run docs:build
190+
- uses: actions/upload-pages-artifact@v3
191+
192+
deploy:
193+
needs: build
194+
steps:
195+
- uses: actions/deploy-pages@v4
196+
```
197+
198+
**前置条件**：GitHub 仓库 Settings → Pages → Source → GitHub Actions（启用一次）。
199+
200+
---
201+
202+
## 里程碑模板
203+
204+
| 周 | 目标 | 产出 |
205+
|----|------|------|
206+
| **W1 — 止住出血点** | CI + 硬编码清理 + CONTRIBUTING | 每次 PR 自动校验 + 任何人 clone 后可直接运行 |
207+
| **W2 — 打开国际通道** | i18n 分层 + SKILL.md 英文化 | 非母语用户可直接使用 |
208+
| **W3 — 正式发布** | Git Tag + CHANGELOG + Homebrew + 文档站上线 | 通过 `brew install` 或 `npm i` 安装，文档可被搜索 |
209+
210+
---
211+
212+
## 常见反模式
213+
214+
| 反模式 | 为什么不行 | 正确做法 |
215+
|--------|-----------|----------|
216+
| 先做文档站再做 CI | 文档站引流的用户看到 broken 项目就流失了 | CI 先于文档站 |
217+
| 翻译全部 references 再发布 | 30+ 份文件翻译周期长，阻塞发布 | 先翻治理层 3 份，其余渐进 |
218+
| 只打 Tag 无 Release Notes | 用户不知道新版本有什么变化 | Tag + CHANGELOG 同时发布 |
219+
| Homebrew Formula 含硬编码 sha256 | 每个版本都要手动更新 | 首次留空，提示用户 `shasum` 补填 |
220+
221+
---
222+
223+
## 适用场景判断
224+
225+
| 项目特征 | 适用优先级 |
226+
|----------|-----------|
227+
| 只有 README 没有文档站 | **P3** 文档站，P3 多语言 |
228+
| 只有英文内容没有中文 | **P1** i18n 分层（反方向：en-US → zh-CN） |
229+
| 有 CI 但没有规则校验 | **P0** 补充业务规则校验 Job |
230+
| 无 CHANGELOG 无版本号 | **P2** Git Tag + CHANGELOG |
231+
| 有 shell 脚本但无包管理器 | **P2** Homebrew / npm |
232+
| 公开仓库无贡献指南 | **P1** CONTRIBUTING + CODEOWNERS |
233+
234+
---
235+
236+
> 最后更新：2026-07-05 · ai-coding-kit v3.0.0

0 commit comments

Comments
 (0)