CraftKit/AGENTS.md

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。
• 自动发现保持默认开启；只有用户明确要求时才设置为仅显式调用。

推荐结构：

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

CraftKit 项目目录

• .craftkit/ 是项目级 Agent 配置、规范、知识和运行状态的统一目录，目录名固定为全小写；不能把整个目录视为本地缓存或整体排除。
• 可共享内容包括 project.json、agents/、standards/、knowledge/ 和 handoff/，可以根据用户确认正常提交和同步。
• project.json 记录项目类型、技术栈、源码与包边界、内部依赖标识、常用命令和规范入口；不得记录凭据、完整连接信息或个人机器绝对路径。
• 项目初始化区分成熟项目与空项目：成熟项目优先延续当前项目已有且有充分证据的风格；空项目根据需求、用户选择和已授权的参考项目建立最小上下文，不自行猜测框架、包名或内部依赖。
• 引用其他项目时先确认参考范围，只提炼结构、依赖、命名、测试、规范或工具约定；共享配置优先记录相对路径，不能共享的本地位置放入 local/。
• 公开框架版本差异由 CraftKit 公共 profile 基于官方资料独立维护；项目只在 project.json 选择实际版本和 profile，并在 standards/ 保存内部框架与覆盖规则。普通任务不得跨 profile 混读，升级或版本比较除外。
• 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 跟踪，或整个 .craftkit/ 被全局规则、.git/info/exclude 或项目规则忽略，应提示冲突并停止自动处理；不得自动修改索引或历史。
• .craftkit/ 不得保存凭据、令牌、私钥、个人机器绝对路径或无必要的个人信息。

迁移与知识产权边界

• 迁移采用“分析能力 → 编写中性规格 → 脱离原文独立实现”的方式，不做目录复制、批量替词或近义改写。
• 不复制来源 Skill 的正文、脚本、提示词、模板、示例、规则库、注释或独特文档结构。
• 不写入公司名称、产品名称、内部域名、内部包名、项目名、人员信息、业务规则或环境路径。
• 公司框架 API、组件契约、审批流程、版本矩阵和内部消息格式不得直接迁移；评估时应先抽象其通用问题，并优先设计基于项目配置、公开标准或用户显式输入的中性平替。只有不存在独立通用价值、无法安全替代或与 Codex 场景不成立时才排除。
• 通用技术规范必须根据公开标准或官方资料重新设计；需要引用时记录来源和许可证。
• 来源文件只用于人工分析和哈希追踪，不得进入 plugins/ 发布目录。
• 上游变化只触发复核，不自动覆盖已迁移 Skill。

详细顺序和门禁见 迁移计划。

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

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

Git 约定

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