# CraftKit

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

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

## 全流程自动化

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

需要从项目上下文初始化推进到应用边界识别、拆分设计和实施规划时，请使用[项目初始化到应用拆分工作流](PROJECT-INITIALIZATION-AND-APPLICATION-SPLIT.md)，并根据项目现状选择：

- [新项目初始化与应用拆分工作流](NEW-PROJECT-INITIALIZATION-AND-APPLICATION-SPLIT.md)：适用于空目录、新仓库或尚未形成有效源码结构的项目。
- [已有项目初始化与应用拆分工作流](EXISTING-PROJECT-INITIALIZATION-AND-APPLICATION-SPLIT.md)：适用于已有源码、数据、接口和部署形态，需要基于现状渐进拆分的项目。

## 文档维护流程

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` 合并。

## 目录结构

```text
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` 插件。

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