CraftKit/README.md

CraftKit

CraftKit 是面向 Codex 的通用插件工具集，覆盖软件开发、文档处理、Git 交付、项目知识维护和 Skill 管理。每个插件的核心能力均可独立安装；同时安装相关插件时可以获得跨 Skill 增强，缺少增强插件时按各 Skill 声明的回退流程执行。能力描述保持简洁、中性，并以当前 Codex 能力和公开标准为基础维护。

全流程自动化

需要根据原始需求和项目代码，串联需求分析、技术设计、开发分支、代码实现、测试审核与本地提交时，请使用 CraftKit 全流程自动化使用指南。该指南提供阶段状态机、人工审批门、自动推进规则和可直接交给 Codex 或其他已安装 CraftKit 工具的总控提示词。

需要从项目上下文初始化推进到应用边界识别、拆分设计和实施规划时，请使用项目初始化到应用拆分工作流，并根据项目现状选择：

• 新项目初始化与应用拆分工作流：适用于空目录、新仓库或尚未形成有效源码结构的项目。
• 已有项目初始化与应用拆分工作流：适用于已有源码、数据、接口和部署形态，需要基于现状渐进拆分的项目。

插件组成

插件	用途
dev	软件需求分析、设计、实现、审查、测试、升级与估算
doc	文档转换、整理、归档与写作
git	分支、提交、变更提取、集成与发布准备
knowledge	项目初始化、任务交接、问题复盘与经验维护
skill	项目规范检索、维护与 Skill 辅助工具

Skill 介绍

Dev

dev 插件覆盖从变更规划、技术设计、代码实现到专项审查和测试的软件开发流程。

Skill	用途
plan-change	分析需求或问题的影响范围、依赖、风险和验证方式，形成可执行的变更计划。
design-backend	设计后端模块边界、服务职责、事务、错误处理及数据影响。
design-frontend	设计前端页面、路由、状态、交互、组件组合和数据流。
design-api	设计或评审 HTTP API 的资源、方法、状态码和请求响应契约。
design-db	设计或评审数据库表、约束、索引及变更与回滚方案。
design-frontend-data	设计前端请求边界、视图模型、状态所有权、缓存和并发处理。
design-workflow	设计业务流程的任务、状态转换、权限、回退、撤回和审计规则。
prepare-api	整理前后端接口清单、字段映射、类型转换、缺失项和联调风险。
component	根据项目依赖和现有用法选择组件，查证 props、events 和 slots。
form	设计或检查表单分组、布局、条件字段、错误展示和可访问性。
style	根据项目视觉基线设计颜色、排版、间距、主题和响应式样式。
implement-backend	按项目语言、框架和规范编写或修改后端代码。
implement-frontend	按项目框架、组件契约和请求封装编写或修改前端代码。
review-code	审查工作区、提交或分支变更中的正确性、兼容、安全、性能和测试问题。
review-java	专项评审 Java 代码的资源管理、并发、异常和可维护性。
review-mybatis	专项评审 Mapper、动态 SQL、参数映射、事务边界和查询性能。
review-frontend	专项评审前端组件边界、状态、渲染、交互、可访问性和性能。
test-backend	设计、生成、修改或运行后端聚焦测试，覆盖正常、边界和失败路径。
test-ui	设计 UI 测试计划，并在具备条件时执行真实浏览器测试。
analyze-bugs	整理结构化 Bug 清单，完成去重、分类、趋势和风险分析。
upgrade	规划并实施前端、后端或依赖的大版本升级。
estimate	根据范围、依赖、未知项和验证成本给出工作量区间与假设。

Doc

doc 插件用于常见办公文档转换、Markdown 整理和项目写作。

Skill	用途
docx-to-md	将 Word .docx 转换为 Markdown，并提取表格、链接和图片。
md-to-docx	将 Markdown 转换为可编辑的 Word .docx 文档。
xlsx-to-md	将 Excel .xlsx 工作簿按工作表转换为 Markdown 表格。
format-md	修正 Markdown 的标题、空行、列表、代码块、表格和链接格式。
archive	按明确规则复制、重命名、清理或拆分项目文档并生成报告。
requirements	将技术说明、会议材料或问题描述整理成可确认的需求说明。
report	根据事实、Git 记录和任务状态撰写工作汇报或阶段总结。
message	根据事件、受众和行动要求起草通知、提醒、确认或故障沟通消息。

Git

git 插件提供可预览、可确认的版本控制与交付操作。

Skill	用途
branch	按仓库约定规划名称，并在确认后创建和切换本地分支。
commit-msg	根据工作区或暂存区的真实变更生成 Conventional Commit 信息。
identity	查看或设置 Git 提交用户名和邮箱及其作用域。
export	按提交、时间或工作区范围导出变更文件并生成分类清单。
integrate	评估分支集成风险，通过隔离 worktree 准备和验证预集成分支。
release	准备版本号、变更摘要和发布检查，并按授权执行版本提交、标签或发布。

Knowledge

knowledge 插件通过项目内 .craftkit/ 目录维护上下文、交接和可复用经验。

Skill	用途
init	初始化或更新项目的 AGENTS.md 与 .craftkit/ 项目资料。
handoff	生成可持续更新的任务交接文档和新任务接续提示词。
distill	从任务证据中提炼可复用结论、决策和问题经验。
lessons	初始化、维护和审计项目问题经验库。
trace	复盘 Agent 的偏离、漏读或规则失效，并提出改进建议。
worklog	根据指定日期、时区和作者的 Git 提交生成工作日志。

Skill

skill 插件负责项目规范的查询和维护。

Skill	用途
guidance	检索项目协作说明、项目资料和公共基线，返回可追溯的规则、冲突与缺口。
guidance-edit	建立、检查和维护 .craftkit/standards/ 规范索引。

目录结构

CraftKit/
├─ .agents/plugins/marketplace.json  # 仓库级 Codex 插件市场清单
├─ AGENTS.md                         # 项目协作与维护约定
├─ WORKFLOW.md                       # 需求到本地提交的研发交付工作流
├─ PROJECT-INITIALIZATION-AND-APPLICATION-SPLIT.md
│                                   # 项目初始化到应用拆分的共同入口
├─ NEW-PROJECT-INITIALIZATION-AND-APPLICATION-SPLIT.md
│                                   # 新项目口径
├─ EXISTING-PROJECT-INITIALIZATION-AND-APPLICATION-SPLIT.md
│                                   # 已有项目口径
├─ plugins/                          # 可独立安装的插件
│  ├─ dev/
│  ├─ doc/
│  ├─ git/
│  ├─ knowledge/
│  └─ skill/
└─ README.md

设计原则

• 每个 Skill 聚焦一个清晰能力，名称与触发描述准确，避免宽泛兜底或重复功能。
• 优先读取当前项目的代码、配置、规范和用户输入，使建议与实际环境保持一致。
• 公共技术规则基于适用版本的官方资料维护；项目专属规则保存在项目自己的 .craftkit/standards/ 中。
• 涉及写文件、Git 状态、外部系统或发布的操作必须明确边界，并按风险取得用户授权。
• 静态检查、脚本测试和真实场景验证分别记录，不用其中一种替代另一种。

本地使用

本仓库提供仓库级 marketplace。将仓库注册为本地 marketplace 后，可按需安装 dev、doc、git、knowledge 或 skill 插件。

正式公开发布前，还需补充许可证、公开仓库地址、作者信息、隐私政策和市场素材。