Contributing

贡献指南

如何为 ai-coding-ok 做贡献。Issue、PR、模板变更和开发工作流。

---

快速入门

ai-coding-ok 是一个 Markdown + Shell + Python 项目。无 Web 框架、无数据库、无前端。你可以贡献的主要领域：

领域	编辑什么	需要技能
模板	templates/en/ 和 templates/zh/	Markdown，写作
Skill 行为	skills/ai-coding-ok/SKILL.md	理解 AI agent 行为
安装脚本	install.sh、install.py	Bash / Python 3
文档	docs/、README.md、wiki	技术写作
验证	scripts/verify.sh	Bash

---

项目架构

ai-coding-ok/
├── templates/en/ + zh/          ← 产品：安装什么
├── skills/ai-coding-ok/SKILL.md ← 大脑：Skill 逻辑（Mode A/B/C/D）
├── scripts/                     ← 工具：安装、验证、提示
├── docs/                        ← 文档：用户指南
└── .github/agent/memory/        ← 自用：dogfooding 记忆

---

如何贡献

1. 找到或创建 Issue

查看已有 Issues 或开新的。描述：

• 你想改什么
• 为什么应该改
• 影响哪些文件

2. Fork 并 Clone

git clone https://github.com/YOUR_USERNAME/ai-coding-ok.git
cd ai-coding-ok

3. 做出你的变更

模板变更：

• 编辑 templates/en/ 和 templates/zh/ 中的文件（必须同步）
• 必要时才添加新占位符
• 如果新增内容，更新版本标记

Skill 行为变更：

• 编辑 skills/ai-coding-ok/SKILL.md
• 复制到根目录：cp skills/ai-coding-ok/SKILL.md SKILL.md

脚本变更：

• install.sh：仅 Bash，无外部依赖
• install.py：仅 Python 3.8+ 标准库
• verify.sh：仅 Bash

4. 测试

# 测试安装
mkdir /tmp/test-install && cd /tmp/test-install
bash /path/to/ai-coding-ok/install.sh --copilot

# 测试验证
bash /path/to/ai-coding-ok/scripts/verify.sh

5. 提交 PR

• 分支：feature/your-change 或 fix/your-fix
• PR 描述：改了什么 + 为什么 + 测试了什么
• 链接相关 Issue

---

模板变更指南

必须同步 en/ 和 zh/

每个模板变更必须在两个语言目录中同步。这是不可协商的（ADR-001）。

检查清单：

• templates/en/ 文件已更新
• templates/zh/ 文件已更新
• 两种语言的占位符一致
• 版本标记已更新

占位符规则

• 英文：{{kebab-case}}
• 中文：{{中文}}
• 尽量复用现有占位符
• 在 SKILL.md 第 6 步中记录新占位符

---

脚本指南

Bash（install.sh、verify.sh）

• 使用 POSIX 兼容语法
• 无外部依赖（无 jq、yq 等）
• 顶部 set -e
• 使用 cp -n 做安全默认（不覆盖）
• 覆盖前始终检查已有文件

Python（install.py）

• Python 3.8+ 标准库
• 无 pip 包、无 conda
• 使用 pathlib.Path 处理跨平台路径
• --dry-run 标志用于预览
• --force 标志用于覆盖

---

版本升级

当你的变更影响框架时：

变更类型	版本升级
新模板文件、新占位符、新模式	MINOR（如 v4.1.0 → v3.2.0）
模板内容修复、措辞改进	PATCH（如 v4.1.0 → v3.1.1）
结构性变更（文件重组、新语言）	MAJOR（如 v4.1.0 → v4.0.0）

更新所有模板文件中的版本标记。

---

审查流程

PR 审查的要点：

1. 正确性 — 变更是否按描述工作？
2. 双语一致性 — en/ 和 zh/ 模板是否同步？
3. 向后兼容 — 现有安装是否会破坏？
4. 文档 — SKILL.md、README 和 wiki 是否已更新？
5. 测试 — 变更是否已测试？

---

获取帮助

• GitHub Issues — 提问、报告 bug
• Discussions — 提议想法、获取反馈
• FAQ — 使用 ai-coding-ok 的常见问题