From 72398c9f89ee060347adf3b437948a60cd462af2 Mon Sep 17 00:00:00 2001 From: "zhiye.sun" Date: Wed, 26 Aug 2026 10:15:09 +0800 Subject: [PATCH] =?UTF-8?q?docs(migration):=20=E5=BB=BA=E7=AB=8B=E5=89=A9?= =?UTF-8?q?=E4=BD=99=20Skill=20=E8=BF=9E=E7=BB=AD=E8=BF=81=E7=A7=BB?= =?UTF-8?q?=E6=B3=A2=E6=AC=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 11 ++++ migration/MIGRATION_PLAN.md | 109 ++++++++++++++++++++++++++++-------- 2 files changed, 97 insertions(+), 23 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index fd7b8f1..2b2894f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -90,6 +90,16 @@ plugins//skills// - 批量阶段按同一插件、相近能力和相同风险类型组织，每批建议 6～12 个 Skill；高度同质时可整组处理，但不得跨越不同权限边界强行合批。 - 批量迁移仍执行完整的两次确认。任何样本失败或出现新类型，都应暂停扩批并补充对应特殊样本。 +### 连续迁移波次 + +当用户明确要求将一组已完整列明的剩余来源“按顺序一次迁移完，再统一确认提交”时，可以建立连续迁移波次： + +- 迁移前必须一次性展示全部来源、目标映射、合并或排除关系、执行顺序、写入范围和总体验收门禁，并取得用户明确确认。 +- 确认后可以按既定阶段连续实现，不再逐阶段请求迁移确认；不得加入方案外来源、目标 Skill 或新权限。 +- 每个阶段仍须独立运行对应测试和敏感内容扫描。阶段失败时先在既定范围内修复；出现需扩大范围、改变目标或无法安全替代的情况时暂停并重新确认。 +- 波次执行期间不创建 Git 提交。全部阶段完成后统一展示来源状态、目标文件、测试证据、未验证边界和建议提交序列，等待一次最终确认。 +- 最终一次“确认提交”可以授权按已展示顺序创建多个逻辑清晰的本地提交；不得因此推送、发布、创建标签或修改远端历史。 + ### 1. 阅读迁移计划和现状 - 完整阅读 `migration/MIGRATION_PLAN.md`、`migration/README.md` 和 `migration/source-lock.json`。 @@ -158,6 +168,7 @@ plugins//skills// - 使用中文 Conventional Commit 信息创建本地提交，然后检查提交内容和工作区状态。 - 本地提交成功后向用户报告提交哈希、提交信息、文件范围和剩余未提交改动。 - 第二次确认只授权本地提交，不包含推送、创建标签、发布插件或修改远端历史；这些操作必须另行获得明确授权。 +- 连续迁移波次按“连续迁移波次”约定执行一次最终确认；若计划创建多个本地提交，必须在确认前展示每个提交的范围和建议信息。 ## 验证要求 diff --git a/migration/MIGRATION_PLAN.md b/migration/MIGRATION_PLAN.md index 9bd57e9..6aaea3f 100644 --- a/migration/MIGRATION_PLAN.md +++ b/migration/MIGRATION_PLAN.md @@ -125,12 +125,12 @@ plan-change 2. `design-backend`（已完成） 3. `design-frontend`（已完成） 4. `prepare-api`（已完成） -5. `implement-backend` -6. `implement-frontend` -7. `review-code` -8. `test-backend` -9. `test-ui` -10. `analyze-bugs` +5. `implement-backend`（已完成） +6. `implement-frontend`（已完成） +7. `review-code`（已完成） +8. `test-backend`（已完成） +9. `test-ui`（已完成） +10. `analyze-bugs`（已完成） 多个来源中的代码检查、代码审查能力合并为 `review-code`，通过工作区、提交和分支三种模式覆盖。 @@ -149,30 +149,93 @@ plan-change 以下能力不从来源文本改写，而是根据官方资料重新设计： -1. `dev/design-api` -2. `dev/design-db` -3. `dev/review-java` -4. `dev/review-frontend` -5. `dev/design-frontend-data` -6. `dev/review-mybatis` +1. `dev/design-api`（已完成） +2. `dev/design-db`（已完成） +3. `dev/review-java`（已完成） +4. `dev/review-frontend`（已完成） +5. `dev/design-frontend-data`（已完成） +6. `dev/review-mybatis`（已完成） +7. `dev/design-workflow`（已完成） 中性规格必须记录所采用的公开标准、官方文档和许可证信息。 -### 暂缓或排除 +### 平替或排除结果 -默认排除： +- 公司框架知识与专属规范由 `skill/guidance`、项目源码和 `.craftkit/standards/` 平替。 +- 内部组件契约、审批规则和消息格式不迁移，目标 Skill 只读取项目证据和用户输入。 +- 升级、估算与发布已重建为通用能力，不携带内部版本矩阵和仓库流程。 +- 浏览器代理配置由 Codex 浏览器或计算机操作能力平替。 +- Skill 路由依靠精确触发描述和 Codex 自动发现，不增加独立路由器。 +- 非 Codex 平台转换能力保持排除。 -- 公司框架知识查询与专属代码规范。 -- 内部组件契约、审批流程和消息格式。 -- 内部仓库发布流程和框架版本升级矩阵。 +### 剩余迁移波次 -暂缓评估： +截至 2026-08-26，原有 29 个 `pending` 来源已在一个连续波次内全部处理完成。所有来源均已闭合为 `migrated`、`superseded` 或 `excluded`；本波次完成验证后统一等待本地提交确认。 -- 浏览器代理配置。 -- 通用大版本升级工具。 -- Skill 路由器。 -- 工作量评估。 -- 非 Codex 平台的迁移工具。 +#### 阶段 1：公开基线与专项设计 + +| 来源能力 | 目标 Skill | 处理方式 | +| --- | --- | --- | +| API 约定 | `dev/design-api` | 基于 HTTP、OpenAPI 等官方资料独立重建 | +| 数据库约定 | `dev/design-db` | 基于目标数据库官方资料和项目证据独立重建 | +| Java 约定 | `dev/review-java` | 基于 Java 与所用框架对应版本官方资料独立重建 | +| 前端约定 | `dev/review-frontend` | 基于当前框架版本官方资料独立重建 | +| 前端数据约定 | `dev/design-frontend-data` | 建立请求、状态与视图模型的通用设计边界 | +| MyBatis 约定 | `dev/review-mybatis` | 基于 MyBatis 官方资料独立重建 | +| 工作流约定 | `dev/design-workflow` | 以项目工作流契约和用户输入平替内部审批规则 | + +公开资料只采用一级官方来源，记录适用版本、重建日期和许可证或引用边界；不得改写来源规范正文。 + +#### 阶段 2：代码实现 + +| 来源 Skill | 目标 Skill | 状态关系 | +| --- | --- | --- | +| `back-code`、同类后端编码来源 | `dev/implement-backend` | 两个来源合并，一个迁移、一个 `superseded` | +| `front-code`、同类前端编码来源 | `dev/implement-frontend` | 两个来源合并，一个迁移、一个 `superseded` | + +实现 Skill 直接修改业务源码，必须保护脏工作区、使用项目真实版本与规范、执行风险相称的验证，且不自动提交或推送。 + +#### 阶段 3：审查、测试与问题分析 + +| 来源能力 | 目标 Skill | 处理方式 | +| --- | --- | --- | +| 两套代码检查与一套代码审查 | `dev/review-code` | 合并为工作区、提交和分支审查模式 | +| 后端单元测试 | `dev/test-backend` | 按当前测试框架和项目模式生成或修改测试 | +| UI 测试 | `dev/test-ui` | 按用户可观察行为设计并执行浏览器测试 | +| Bug 列表分析 | `dev/analyze-bugs` | 解析通用结构化问题清单并形成证据化报告 | + +本阶段不得把静态检查、单元测试、浏览器测试和真实环境验收混为同一结论。 + +#### 阶段 4：交付、升级与估算 + +| 来源能力 | 目标 Skill 或处理结果 | 处理方式 | +| --- | --- | --- | +| 后端升级、前端升级 | `dev/upgrade` | 合并为基于源版本、目标版本和官方迁移资料的通用升级流程 | +| 版本发布 | `git/release` | 只准备版本、变更摘要、标签和发布检查；远端动作单独授权 | +| 工作量评估 | `dev/estimate` | 基于范围、依赖、风险和假设输出区间估算 | +| 框架约定 | `skill/guidance` | `superseded`，内部规则由项目 `.craftkit/standards/` 提供 | +| 框架知识查询 | `skill/guidance` | `superseded`，改为检索项目证据和公开官方资料 | + +#### 阶段 5：写作与平台工具收尾 + +| 来源能力 | 目标 Skill 或处理结果 | 处理方式 | +| --- | --- | --- | +| 领导汇报 | `doc/report` | 中性化为面向不同受众的事实型工作汇报 | +| 消息模板 | `doc/message` | 中性化为项目消息与通知草稿 | +| 技术内容转需求 | `doc/requirements` | 将技术输入转换为可确认的需求说明 | +| 能力创建器 | 官方 `skill-creator` | `superseded`，不重复发布同类 CraftKit Skill | +| 浏览器代理配置 | Codex 浏览器或计算机操作能力 | `superseded`，不迁移宿主专属代理配置 | +| Skill 转 Cursor | 无 | `excluded`，CraftKit 只面向 Codex | + +#### 波次总门禁 + +1. 29 个来源全部更新为 `migrated`、`superseded` 或 `excluded`，不得遗留 `pending`。 +2. 所有目标 Skill 通过结构、引用、敏感内容和真实请求边界测试。 +3. 公开基线记录官方来源、适用版本和重建边界。 +4. 有脚本的 Skill 完成隔离行为测试；有外部工具的 Skill 明确权限和未验证边界。 +5. README、插件版本、迁移计划和来源锁同步一致。 +6. 全量测试、JSON 校验和 `git diff --check` 通过。 +7. 波次完成后只展示提交方案，不创建提交；用户统一确认后按逻辑范围创建本地提交。 ## 5. 合并原则