chore: 清理 CraftKit 迁移资料

2026-08-26 11:13:52 +08:00
parent b43235db40
commit 9979a7c038
22 changed files with 47 additions and 2307 deletions
@@ -4,7 +4,7 @@

 ## 项目目标

-CraftKit 面向 Codex 插件市场，提供简洁、中性、可独立安装的 Skill。所有能力必须能够脱离来源项目独立理解、验证和维护。
+CraftKit 面向 Codex 插件市场，提供简洁、中性、可独立安装和维护的 Skill。每项能力都应具备清晰边界，并能够独立理解与验证。

 ## 沟通与改动

@@ -23,8 +23,7 @@ CraftKit 面向 Codex 插件市场，提供简洁、中性、可独立安装的
 | `plugins/doc/` | 文档转换、整理与写作 Skill |
 | `plugins/git/` | Git 操作与交付 Skill |
 | `plugins/knowledge/` | 交接、复盘与知识维护 Skill |
-| `plugins/skill/` | Skill 创建、迁移、检查与同步工具 |
-| `migration/` | 来源指纹、迁移计划和状态追踪，不进入插件发布内容 |
+| `plugins/skill/` | Skill 与项目规范辅助工具 |

 ## Skill 设计规则

@@ -44,143 +43,51 @@ plugins/<plugin>/skills/<skill>/
 ├─ SKILL.md
 ├─ agents/openai.yaml      # 有 UI 元数据时使用
 ├─ scripts/                # 有确定性自动化时使用
-├─ references/             # 有条件加载的详细资料时使用
+├─ references/             # 有条件加载的详细资料
 └─ assets/                 # 生成产物需要的素材
 ```

+## 维护原则
+
+- 以当前 Codex 能力、项目实际情况、公开标准和用户需求为依据设计 Skill。
+- 技术规则应注明适用版本；依赖外部资料时记录资料入口和验证日期。
+- 新增内容应具备明确用途，避免重复能力、过期说明和仅用于记录开发过程的文档。
+
+## 新增与修改流程
+
+1. 阅读目标插件、相邻 Skill、适用的 `AGENTS.md` 和当前 Git 状态，确认职责边界与已有改动。
+2. 明确用户目标、输入、输出、触发条件、副作用、权限和不包含事项。
+3. 检查是否应复用或扩展已有 Skill，避免名称不同但职责重复的实现。
+4. 修改前向用户说明目标文件、实现方式、风险和验证方法；高风险或范围不明确时等待确认。
+5. 按最小必要结构实现，优先使用项目证据和官方资料，不猜测接口、版本或运行行为。
+6. 完成结构、引用、插件清单及必要行为验证，并分别记录通过项和未验证边界。
+7. 展示实际变更、验证结果、剩余风险和建议提交信息；只有用户明确授权后才执行本地提交。
+
 ## CraftKit 项目目录

 - `.craftkit/` 是项目级 Agent 配置、规范、知识和运行状态的统一目录，目录名固定为全小写；不能把整个目录视为本地缓存或整体排除。
 - 可共享内容包括 `project.json`、`agents/`、`standards/`、`knowledge/` 和 `handoff/`，可以根据用户确认正常提交和同步。
 - `project.json` 记录项目类型、技术栈、源码与包边界、内部依赖标识、常用命令和规范入口；不得记录凭据、完整连接信息或个人机器绝对路径。
- 项目初始化区分成熟项目与空项目：成熟项目优先延续当前项目已有且有充分证据的风格；空项目根据需求、用户选择和已授权的参考项目建立最小上下文，不自行猜测框架、包名或内部依赖。
+- 成熟项目优先延续已有且有充分证据的风格；空项目根据需求、用户选择和已授权参考建立最小上下文，不自行猜测框架、包名或内部依赖。
 - 引用其他项目时先确认参考范围，只提炼结构、依赖、命名、测试、规范或工具约定；共享配置优先记录相对路径，不能共享的本地位置放入 `local/`。
- 公开框架版本差异由 CraftKit 公共 profile 基于官方资料独立维护；项目只在 `project.json` 选择实际版本和 profile，并在 `standards/` 保存内部框架与覆盖规则。普通任务不得跨 profile 混读，升级或版本比较除外。
+- 公共框架版本差异由 CraftKit 公共 profile 维护；项目在 `project.json` 选择实际版本和 profile，并在 `standards/` 保存项目补充规则。
 - `agents/` 保存项目对特定 Agent 的补充说明；`standards/` 保存项目开发规范；`knowledge/pitfalls/` 保存经验证且可复用的问题经验；`knowledge/decisions/` 保存重要技术决策。
 - 本地内容统一放入 `local/`，缓存统一放入 `cache/`。`.craftkit/.gitignore` 必须排除 `/local/` 和 `/cache/`，但不得排除整个 `.craftkit/`。
 - 本地交接默认位于 `.craftkit/local/handoff/current.md`；只有用户明确选择共享时才写入 `.craftkit/handoff/current.md`。
 - 只在实际需要时创建目录，不一次生成空的 `agents/`、`standards/`、`knowledge/`、`handoff/`、`local/` 或 `cache/`。
- Git Skill 默认排除 `.craftkit/local/**` 和 `.craftkit/cache/**`；其他 `.craftkit` 内容按普通项目资产评估，并在提交建议中单独标识为 Agent、规范或知识变更。
- Git 交付或变更导出默认排除环境配置、本地配置和机器配置。只有适用的 `AGENTS.md`、`.craftkit/agents/` 或 `.craftkit/standards/` 明确要求交付，并经用户查看预览后再次确认，才可纳入；私钥、真实密钥和检测到的凭据始终禁止导出。
+- Git Skill 默认排除 `.craftkit/local/**` 和 `.craftkit/cache/**`；其他 `.craftkit` 内容按普通项目资产评估，并在提交建议中单独标识。
 - 如果本地目录已经被 Git 跟踪，或整个 `.craftkit/` 被全局规则、`.git/info/exclude` 或项目规则忽略，应提示冲突并停止自动处理；不得自动修改索引或历史。
 - `.craftkit/` 不得保存凭据、令牌、私钥、个人机器绝对路径或无必要的个人信息。

-## 迁移与知识产权边界
-
- 迁移采用“分析能力 → 编写中性规格 → 脱离原文独立实现”的方式，不做目录复制、批量替词或近义改写。
- 不复制来源 Skill 的正文、脚本、提示词、模板、示例、规则库、注释或独特文档结构。
- 不写入公司名称、产品名称、内部域名、内部包名、项目名、人员信息、业务规则或环境路径。
- 公司框架 API、组件契约、审批流程、版本矩阵和内部消息格式不得直接迁移；评估时应先抽象其通用问题，并优先设计基于项目配置、公开标准或用户显式输入的中性平替。只有不存在独立通用价值、无法安全替代或与 Codex 场景不成立时才排除。
- 通用技术规范必须根据公开标准或官方资料重新设计；需要引用时记录来源和许可证。
- 来源文件只用于人工分析和哈希追踪，不得进入 `plugins/` 发布目录。
- 上游变化只触发复核，不自动覆盖已迁移 Skill。
-
-详细顺序和门禁见 [迁移计划](migration/MIGRATION_PLAN.md)。
-
-## Skill 迁移工作流
-
-所有新增迁移、来源更新和已迁移 Skill 的重新评估，都必须按以下顺序处理。用户未明确确认前，只能进行只读分析，不得创建、复制、改写或删除目标 Skill 文件。
-
-### 批次策略
-
- 迁移前期采用“特殊样本”方式，不以固定数量为目标，而是优先覆盖不同结构、依赖、权限和风险类型。
- 特殊样本至少覆盖纯指令、脚本与生成物、只读 Git、有副作用 Git、模板化文档、大型参考资料和复合工作流；缺少某一类型时不得宣告样本阶段完成。
- 每个特殊样本原则上单独完成迁移前确认、实现验证和提交确认，以便及时修正规则。
- 特殊样本全部通过后，应先总结可复用的命名、目录、改写、验证和状态同步规则，再进入批量阶段。
- 批量阶段按同一插件、相近能力和相同风险类型组织，每批建议 6～12 个 Skill；高度同质时可整组处理，但不得跨越不同权限边界强行合批。
- 批量迁移仍执行完整的两次确认。任何样本失败或出现新类型，都应暂停扩批并补充对应特殊样本。
-
-### 连续迁移波次
-
-当用户明确要求将一组已完整列明的剩余来源“按顺序一次迁移完，再统一确认提交”时，可以建立连续迁移波次：
-
- 迁移前必须一次性展示全部来源、目标映射、合并或排除关系、执行顺序、写入范围和总体验收门禁，并取得用户明确确认。
- 确认后可以按既定阶段连续实现，不再逐阶段请求迁移确认；不得加入方案外来源、目标 Skill 或新权限。
- 每个阶段仍须独立运行对应测试和敏感内容扫描。阶段失败时先在既定范围内修复；出现需扩大范围、改变目标或无法安全替代的情况时暂停并重新确认。
- 波次执行期间不创建 Git 提交。全部阶段完成后统一展示来源状态、目标文件、测试证据、未验证边界和建议提交序列，等待一次最终确认。
- 最终一次“确认提交”可以授权按已展示顺序创建多个逻辑清晰的本地提交；不得因此推送、发布、创建标签或修改远端历史。
-
-### 1. 阅读迁移计划和现状
-
- 完整阅读 `migration/MIGRATION_PLAN.md`、`migration/README.md` 和 `migration/source-lock.json`。
- 检查 Git 状态、目标插件目录和现有 Skill，避免覆盖未提交改动或重复实现。
- 只读检查相关来源 Skill 及其辅助资源，确认来源提交、文件哈希、依赖关系和变化范围。
- 区分首次迁移、上游更新、目标重构和排除项复核，不把不同类型混为一次迁移。
-
-### 2. 列出来源 Skill 和作用
-
-在任何写入前，向用户列出本批计划处理的来源 Skill：
-
-| 项目 | 内容 |
-| --- | --- |
-| 来源标识 | 使用本地迁移标识，不在发布目录写入公司品牌 |
-| 来源 Skill | 原始名称和相对路径 |
-| 当前作用 | 根据源码确认的能力、输入、输出和关键边界 |
-| 迁移类型 | 新增、更新、合并、中性平替、公开资料重建或排除 |
-| 风险 | 公司专属知识、内部依赖、重复能力和兼容性问题 |
-
-来源作用必须有文件依据；无法从静态内容确认的运行行为应明确标记为未验证。
-
-同一目标能力存在多个来源时，应在一个迁移方案中共同评估，明确合并、取舍、中性平替或排除关系，不按来源机械创建多个目标 Skill。来源含有大量专有规则时，不得只罗列删除项；必须说明通用问题如何由配置、标准接口、用户输入或项目资料替代。
-
-### 3. 给出目标名称、作用和组织结构
-
-针对每个来源 Skill，先给出建议方案：
-
-| 项目 | 内容 |
-| --- | --- |
-| 目标插件 | `dev`、`doc`、`git`、`knowledge` 或 `skill` |
-| 目标名称 | 简短、中性、动作或明确领域导向的名称 |
-| 目标作用 | 迁移后保留的通用能力和明确排除的内容 |
-| 组织结构 | `SKILL.md` 及确有需要的 `agents/`、`scripts/`、`references/`、`assets/` |
-| 合并关系 | 独立 Skill、合并到已有 Skill、替代旧 Skill 或排除 |
-| 验证方案 | 静态校验、脚本测试、真实请求和敏感内容扫描 |
-
-此阶段只输出设计，不创建目标目录。若多个来源能力可以合并，应优先给出合并方案，避免一一照搬来源结构。
-
-### 4. 与用户确认迁移方案
-
- 展示本批范围、目标映射、组织结构、排除内容和验证方式后，明确请求用户确认。
- 用户可以确认全部方案，也可以调整名称、拆分或合并方式、迁移顺序和排除项。
- 只有“确认执行”“按此方案迁移”等明确授权才允许进入写入阶段。
- 用户仅要求评估、查看方案或继续讨论时，不视为迁移授权。
- 确认后的授权只覆盖已展示范围；新增 Skill、扩大来源范围或改变组织方式必须重新确认。
-
-### 5. 执行迁移并更新文档
-
-获得确认后：
-
-1. 按中性能力规格独立实现目标 Skill，不复制来源目录或正文。
-2. 运行 `AGENTS.md` 中规定的全部验证，并记录真实结果和未验证边界。
-3. 更新 `migration/source-lock.json` 的来源哈希、目标路径、状态和复核日期。
-4. 更新 `migration/MIGRATION_PLAN.md` 的执行清单和批次进度。
-5. 更新根 `README.md`、所属插件说明或其他确实受影响的文档；不得创建重复状态文档。
-6. 向用户报告新增、更新、合并和排除结果，以及测试、扫描和剩余风险。
-7. 展示本批待提交文件清单和建议的 Conventional Commit 提交信息，进入第二次确认。
-
-### 6. 与用户确认并提交到本地
-
- 迁移前确认只授权执行迁移，不自动授权 Git 提交。
- 迁移和文档同步完成后，必须再次等待用户明确确认；“确认提交”“提交到本地”等表述才视为提交授权。
- 用户要求调整、补测或继续检查时，先完成相应工作并重新展示结果，不得沿用此前的提交确认。
- 获得确认后，只暂存本批迁移方案中已展示且验证通过的文件，不使用会混入其他改动的宽泛暂存命令。
- 暂存后执行 `git diff --cached --check`，并复核暂存文件清单；发现额外文件或敏感内容时停止提交并报告。
- 使用中文 Conventional Commit 信息创建本地提交，然后检查提交内容和工作区状态。
- 本地提交成功后向用户报告提交哈希、提交信息、文件范围和剩余未提交改动。
- 第二次确认只授权本地提交，不包含推送、创建标签、发布插件或修改远端历史；这些操作必须另行获得明确授权。
- 连续迁移波次按“连续迁移波次”约定执行一次最终确认；若计划创建多个本地提交，必须在确认前展示每个提交的范围和建议信息。
-
 ## 验证要求

 每个新增或修改的 Skill 至少完成：

-1. 检查目录名、frontmatter 和引用路径。
-2. 运行 Skill 校验器。
-3. 运行所属插件 manifest 校验器。
-4. 执行公司标识、内部路径、凭据和占位符扫描。
-5. 有脚本时运行核心行为测试；有生成物时检查实际产物。
-6. 用一个真实请求验证触发边界和输出结果。
-7. 更新 `migration/source-lock.json` 中的状态、目标路径和复核日期。
+1. 检查目录名、frontmatter、引用路径和工具名称。
+2. 运行仓库现有的 Skill 校验器及所属插件校验器。
+3. 检查凭据、无效路径、未替换占位符和无效工具名称。
+4. 有脚本时运行核心行为测试；有生成物时检查实际产物。
+5. 以真实请求检查触发边界、权限边界和输出是否符合描述。

 静态检查通过不代表真实行为已经验证，交付时应分别说明静态校验、脚本测试和实际场景验证结果。

@@ -189,5 +96,5 @@ plugins/<plugin>/skills/<skill>/
 - 使用 Conventional Commits，提交说明使用中文。
 - 推荐类型：`feat`、`fix`、`docs`、`refactor`、`test`、`chore`。
 - 提交前执行 `git status --short`、`git diff --cached --check` 并检查暂存文件清单。
- 不提交本地来源配置、凭据、缓存、运行产物和 IDE 私有状态。
+- 不提交本地配置、凭据、缓存、运行产物和 IDE 私有状态。
 - 不使用破坏性历史改写，也不推送，除非用户明确授权。