Upgrade ai coding ok

升级 ai-coding-ok

升级分两层：先升级 skill 本身（全局），再升级各个项目里的框架文件（项目）。

---

第一步：升级 skill 本身

1a. 拉取最新代码

cd ~/ai-coding-ok && git pull

1b. 更新全局 skill（Claude Code / Codex / OpenCode 用户）

bash ~/ai-coding-ok/install.sh --claude-code --force   # Claude Code
bash ~/ai-coding-ok/install.sh --codex --force          # Codex
bash ~/ai-coding-ok/install.sh --opencode --force       # OpenCode

Copilot / Cursor 用户跳过这步——你们没有全局 skill，直接做第二步。

---

第二步：升级各个项目

进入每个已安装 ai-coding-ok 的项目，对 AI 说：

升级 ai-coding-ok

AI 会：

1. 检测你安装的版本
2. 与最新模板对比
3. 展示将要变更的内容
4. 请求确认
5. 应用变更，保留你的项目定制
6. 在 task-history.md 中记录升级

---

升级过程中发生了什么

第 1 步：版本检测

AI 从已安装文件读取版本标记：

AGENTS.md：               <!-- ai-coding-ok: v4.0.0 -->
copilot-instructions.md： <!-- ai-coding-ok: v4.0.0 -->
system-prompt.md：        <!-- ai-coding-ok: v4.0.0 -->
...

报告："检测到 ai-coding-ok v4.0.0。最新版本：v4.1.0。"

第 2 步：变更识别

AI 将你的已安装文件与最新模板 diff，识别三种变更：

类型	示例	操作
新增章节	新增 Codex 安装说明	插入到你的文件中
删除章节	模板中不再存在的旧章节	删除前询问
修改章节	PDCA 强制要求从 3 步扩展到 7 步	智能合并

第 3 步：确认

AI 展示变更清单并询问是否继续。

第 4 步：应用变更

对每个变更文件，AI：

1. 读取你当前的文件
2. 只应用框架变更
3. 保留你的项目特定内容（名称、技术栈、架构、自定义 ADR）
4. 更新版本标记

第 5 步：记录

### [TASK-XXX] 升级 ai-coding-ok v4.0.0 → v4.1.0
- **日期**：2026-07-25
- **类型**：chore
- **摘要**：升级框架。新增 Codex 支持。所有项目定制已保留。
- **变更文件**：AGENTS.md、CLAUDE.md、.codex/skills/ 等

---

升级路径

如果你在较旧版本上，升级按顺序应用：

当前	目标	主要变更
v1.0	v2.0	AGENTS.md + copilot-instructions.md 获得 PDCA 强制要求；版本标记新增
v2.0	v2.1.0	Cursor 支持；OpenCode 支持
v2.1.0	v2.2.0	CLAUDE.md 自动加载 shim
v2.2.0	v3.0.0	插件打包；双语模板（en/zh）
v3.0.x	v3.1.0	五层防御体系；Claude Code hooks
v3.1.0	v4.0.0	删除英文模板；全文中文化；install.sh 中文化
v4.0.0	v4.1.0	Codex 支持；安装文档全面修正

每步依次应用。可以在一条命令中跨多个版本升级。

---

升级保留的内容

AI 明确保留：

• 项目标识： 名称、描述、类型
• 技术栈： 语言、框架、数据库、测试框架
• 架构： 图表、模块列表、数据流描述
• 自定义约束： 你的项目特定规则
• 自定义 ADR： decisions-log.md 中的决策
• 任务历史： task-history.md 中的所有条目
• 已知问题： project-memory.md 中的条目
• 自定义工作流： workflows.md 中添加的场景
• 编码规范： 你的语言特定约定

---

手动升级（Copilot / Cursor）

非 Claude Code 用户：

1. 拉取最新 ai-coding-ok：

   cd ~/ai-coding-ok && git pull

2. 打开 scripts/upgrade-prompt.md，复制全部内容粘贴给 AI 工具

3. AI 会检测版本、展示变更并应用

---

升级后

验证

bash ~/ai-coding-ok/scripts/verify.sh

检查版本标记

head -1 AGENTS.md
# 应显示：<!-- ai-coding-ok: v4.1.0 -->

审查变更

git diff

聚焦新增或修改了章节的文件。确认你的项目定制完整。

测试 PDCA

做一个小改动，确认 AI 仍然：

1. 编码前读取记忆文件
2. 响应中包含 ## 记忆更新 章节

---

回滚

如果升级导致问题：

# 回退到升级前的 commit
git checkout HEAD~1 -- AGENTS.md CLAUDE.md .github/

# 重新仔细升级
# 对 AI 说：升级 ai-coding-ok
# 仔细审查每个变更

---

常见升级问题

"升级显示'无需变更'但我知道我是旧版本"

版本标记可能缺失或损坏。检查：

head -1 AGENTS.md
head -1 .github/copilot-instructions.md

如果标记缺失，手动添加（如 <!-- ai-coding-ok: v2.0 -->）然后重试。

"升级想删除我定制的章节"

在确认步骤对该章节选择"跳过"。升级是交互式的——可以接受/拒绝单个变更。

---

下一步

• Changelog — 完整版本历史
• 版本管理 — 版本机制原理
• 定制化指南 — 升级后如何安全定制