101 lines
6.6 KiB
Markdown
101 lines
6.6 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 与项目规范辅助工具 |
|
|
|
|
## 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/ # 生成产物需要的素材
|
|
```
|
|
|
|
## 维护原则
|
|
|
|
- 以当前 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/` 保存项目补充规则。
|
|
- `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` 内容按普通项目资产评估，并在提交建议中单独标识。
|
|
- 如果本地目录已经被 Git 跟踪，或整个 `.craftkit/` 被全局规则、`.git/info/exclude` 或项目规则忽略，应提示冲突并停止自动处理；不得自动修改索引或历史。
|
|
- `.craftkit/` 不得保存凭据、令牌、私钥、个人机器绝对路径或无必要的个人信息。
|
|
|
|
## 验证要求
|
|
|
|
每个新增或修改的 Skill 至少完成：
|
|
|
|
1. 检查目录名、frontmatter、引用路径和工具名称。
|
|
2. 运行仓库现有的 Skill 校验器及所属插件校验器。
|
|
3. 检查凭据、无效路径、未替换占位符和无效工具名称。
|
|
4. 有脚本时运行核心行为测试；有生成物时检查实际产物。
|
|
5. 以真实请求检查触发边界、权限边界和输出是否符合描述。
|
|
|
|
静态检查通过不代表真实行为已经验证，交付时应分别说明静态校验、脚本测试和实际场景验证结果。
|
|
|
|
## Git 约定
|
|
|
|
- 使用 Conventional Commits，提交说明使用中文。
|
|
- 推荐类型：`feat`、`fix`、`docs`、`refactor`、`test`、`chore`。
|
|
- 提交前执行 `git status --short`、`git diff --cached --check` 并检查暂存文件清单。
|
|
- 不提交本地配置、凭据、缓存、运行产物和 IDE 私有状态。
|
|
- 不使用破坏性历史改写，也不推送，除非用户明确授权。
|