CraftKit/README.md

CraftKit

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

版本发布与重要变更记录见 CHANGELOG.md。

全流程自动化

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

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

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

文档维护流程

CraftKit 按“初始化约定 → 创建或更新 → 审核生效 → 随实现持续维护 → 关闭时分类处置”管理项目文档。过程材料默认保存在本地任务目录；正式需求、生效设计、项目规范和长期知识保存审核状态，后续任务优先更新已有权威文档。

长期文档使用 pending、approved、outdated 表示待审核、当前有效和已知过期。任务关闭不结束文档维护；实现、接口、数据模型或业务行为变化时，需要检查并同步相关留存文档。详细规则由项目 .craftkit/standards/document-maintenance.md 维护。

插件组成

插件	用途
dev	软件需求分析、设计、实现、审查、测试、升级与估算
doc	文档转换、整理、归档与写作
git	分支、提交、变更提取、集成与发布准备
knowledge	项目初始化、任务交接、问题复盘与经验维护
skill	项目规范检索、维护与 Skill 辅助工具
profile	多语言技术能力契约、匹配规则与静态校验
java	Java、构建工具与 Spring 技术能力资料
python	Python、包管理、FastAPI、测试与专项审查资料

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	按仓库约定创建本地分支，并管理独立 Worktree 的创建与安全关闭。
commit-msg	根据工作区或暂存区的真实变更生成 Conventional Commit 信息。
identity	查看或设置 Git 提交用户名和邮箱及其作用域。
export	按提交、时间或工作区范围导出变更文件并生成分类清单。
integrate	评估分支集成风险，通过隔离 Worktree 准备、验证、发布和清理预集成分支。
release	准备版本号、变更摘要和发布检查，并按授权执行版本提交、标签或发布。

Knowledge

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

Skill	用途
init	初始化或更新项目上下文、文档目录和持续维护约定。
document-output	管理文档落盘、任务关联、审核状态、持续更新和关闭处置。
handoff	生成可持续更新的任务交接文档和新任务接续提示词。
distill	从任务证据提炼知识，并更新、替代或标记已有结论。
lessons	初始化、修订、标记过时和审计项目问题经验库。
trace	复盘 Agent 的偏离、漏读或规则失效，并提出改进建议。
worklog	根据指定日期、时区和作者的 Git 提交生成工作日志。

Skill

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

Skill	用途
guidance	检索当前有效的项目规则和知识，区分待审核、过时与历史材料。
guidance-edit	建立、检查和维护 .craftkit/standards/ 规范索引。

Profile、Java 与 Python

• profile:resolve：根据目标模块、项目事实和当前会话已发现的提供方解析技术能力；缺失时返回明确回退。
• java:profile：提供 Java、Maven/Gradle、Spring 设计、命令和审查资料。
• python:profile：提供 Python、包管理、FastAPI、实现、测试和审查资料。
• python:review-python：按项目版本专项审查 Python 类型、异常、资源、异步、事务和测试隔离问题。

跨插件逻辑标识只用于诊断。各提供方读取自身资料，核心 Skill 不扫描用户插件缓存；项目规范仍由 guidance 合并。

目录结构

CraftKit/
├─ .agents/plugins/marketplace.json  # 仓库级 Codex 插件市场清单
├─ AGENTS.md                         # 项目协作与维护约定
├─ CHANGELOG.md                      # SemVer 版本与重要变更记录
├─ 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/
│  ├─ profile/
│  ├─ java/
│  └─ python/
└─ README.md

设计原则

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

本地使用

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

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