155 lines
8.7 KiB
Markdown
155 lines
8.7 KiB
Markdown
# 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 文件。
|
|
|
|
### 1. 阅读迁移计划和现状
|
|
|
|
- 完整阅读 `migration/MIGRATION_PLAN.md`、`migration/README.md` 和 `migration/source-lock.json`。
|
|
- 检查 Git 状态、目标插件目录和现有 Skill，避免覆盖未提交改动或重复实现。
|
|
- 只读检查相关来源 Skill 及其辅助资源，确认来源提交、文件哈希、依赖关系和变化范围。
|
|
- 区分首次迁移、上游更新、目标重构和排除项复核，不把不同类型混为一次迁移。
|
|
|
|
### 2. 列出来源 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 私有状态。
|
|
- 不使用破坏性历史改写，也不推送，除非用户明确授权。
|