# CraftKit 协作约定

本文件适用于 CraftKit 仓库及其全部子目录。更深层目录若存在自己的 `AGENTS.md`，以更具体的约定为准。

## 项目目标

CraftKit 面向 Codex 插件市场，提供简洁、中性、可独立安装的 Skill。所有能力必须能够脱离来源项目独立理解、验证和维护。

## 沟通与改动

- 所有回答、文档和代码注释使用中文；公开 API、标准名称和代码标识可以保留英文。
- 修改前先说明方案。简单改动可在说明后直接执行；复杂或高风险改动先明确范围、影响和验证方式。
- 阅读、分析和评审任务默认只读，不因发现问题自动扩大为修改任务。
- 未经明确要求，不提交、不推送、不安装插件，也不修改用户级 Codex 配置。
- 保留工作区已有改动；提交时只暂存本次确认范围内的文件。

## 目录职责

| 路径 | 职责 |
| --- | --- |
| `.agents/plugins/marketplace.json` | CraftKit 市场及插件入口 |
| `plugins/dev/` | 软件设计、编码、审查与测试 Skill |
| `plugins/doc/` | 文档转换、整理与写作 Skill |
| `plugins/git/` | Git 操作与交付 Skill |
| `plugins/knowledge/` | 交接、复盘与知识维护 Skill |
| `plugins/skill/` | Skill 创建、迁移、检查与同步工具 |
| `migration/` | 来源指纹、迁移计划和状态追踪，不进入插件发布内容 |

## Skill 设计规则

- Skill 名称使用小写字母、数字和连字符，简短且以动作或明确领域为中心。
- Skill 文件夹名必须与 `SKILL.md` frontmatter 的 `name` 完全一致。
- `description` 只说明能力和触发场景，避免大而全、宽泛兜底或堆砌关键词。
- `SKILL.md` 只保留共同目标、关键流程和必要边界；条件性细节放入 `references/`。
- 只有重复执行且确定性逻辑明显时才新增 `scripts/`；新增脚本必须有可运行验证。
- 只有产物确实需要模板、图片或样例文件时才新增 `assets/`。
- 不创建没有实际用途的空目录、占位文档或重复 README。
- 自动发现保持默认开启；只有用户明确要求时才设置为仅显式调用。

推荐结构：

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

## 迁移与知识产权边界

- 迁移采用“分析能力 → 编写中性规格 → 脱离原文独立实现”的方式，不做目录复制、批量替词或近义改写。
- 不复制来源 Skill 的正文、脚本、提示词、模板、示例、规则库、注释或独特文档结构。
- 不写入公司名称、产品名称、内部域名、内部包名、项目名、人员信息、业务规则或环境路径。
- 公司框架 API、组件契约、审批流程、版本矩阵和内部消息格式默认排除。
- 通用技术规范必须根据公开标准或官方资料重新设计；需要引用时记录来源和许可证。
- 来源文件只用于人工分析和哈希追踪，不得进入 `plugins/` 发布目录。
- 上游变化只触发复核，不自动覆盖已迁移 Skill。

详细顺序和门禁见 [迁移计划](migration/MIGRATION_PLAN.md)。

## Skill 迁移工作流

所有新增迁移、来源更新和已迁移 Skill 的重新评估，都必须按以下顺序处理。用户未明确确认前，只能进行只读分析，不得创建、复制、改写或删除目标 Skill 文件。

### 批次策略

- 迁移前期采用“特殊样本”方式，不以固定数量为目标，而是优先覆盖不同结构、依赖、权限和风险类型。
- 特殊样本至少覆盖纯指令、脚本与生成物、只读 Git、有副作用 Git、模板化文档、大型参考资料和复合工作流；缺少某一类型时不得宣告样本阶段完成。
- 每个特殊样本原则上单独完成迁移前确认、实现验证和提交确认，以便及时修正规则。
- 特殊样本全部通过后，应先总结可复用的命名、目录、改写、验证和状态同步规则，再进入批量阶段。
- 批量阶段按同一插件、相近能力和相同风险类型组织，每批建议 6～12 个 Skill；高度同质时可整组处理，但不得跨越不同权限边界强行合批。
- 批量迁移仍执行完整的两次确认。任何样本失败或出现新类型，都应暂停扩批并补充对应特殊样本。

### 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` 中的状态、目标路径和复核日期。

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

## Git 约定

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