CraftKit/CHANGELOG.md

更新日志

本文档记录 CraftKit 对使用者有明显影响的功能、工作流和兼容性变化。版本号遵循 Semantic Versioning 2.0.0：主版本表示不兼容变化，次版本表示向后兼容的新能力，修订版本表示向后兼容的问题修复。

历史版本根据 Git 提交倒推，只保留重要里程碑，不逐条复述全部提交。各版本对应的 Git 历史通过 v<版本号> 标签标记。

这里的版本号表示 CraftKit 仓库整体发布版本。dev、doc、git、knowledge 和 skill 的插件清单版本仍按各插件实际变化独立维护，不要求与仓库版本保持一致。

[Unreleased]

Added

• knowledge:document-output 增加 register 与 close 模式，使用 workRoot/<task>/task.json 记录任务状态、文件归属、可见性和关闭处置。
• 增加“保留、沉淀、归档、删除、延后”五类关闭清单，以及共享文件逐项评审、断链检查和精确路径删除门禁。

Planned

• 建设 Skill 评测基线，支持固定场景、验收规则和更新前后回归比较。
• 保持 dev 插件的通用设计、实现、测试和审查核心，不按 Java、Python、React 或 Vue 复制整套工作流；仅当专项能力具备独立安装、发布或维护需求时再评估拆分插件。
• 补充 Python 专项支持，优先增加 review-python，并为现有后端实现与测试 Skill 建立 Python 版本、pyproject.toml、pytest、Ruff、mypy/pyright 及 FastAPI、Django、Flask 的按需资料路由。
• 补充前端工程质量专项支持，增加 test-frontend 和 review-typescript，分别覆盖单元、组件与集成测试，以及 TypeScript 类型安全与模块契约。
• 建立按项目真实依赖选择的语言与框架 profile，优先覆盖 Java、Python、React、Vue、Next.js、Nuxt 及相关构建、状态和测试工具；未确认精确版本时不默认最新版本，不跨版本混用规则。
• 增加命令环境探测与指令适配辅助 Skill：识别操作系统、Shell/终端类型及版本、Codex 可用功能工具、命令行工具来源与版本，生成当前任务的环境能力快照，并按探测结果选择经过验证的默认指令；覆盖 PowerShell、Windows PowerShell、CMD、Bash、Zsh 等环境中的路径、引号、转义、编码、管道、退出码和标准输出/错误流差异。
• 为 Git 建立版本与仓库状态 profile：根据 Git 版本选择 checkout、switch、restore、Worktree、分支跟踪和安全目录等命令形式，固定参数顺序并兼容含空格或非 ASCII 字符的路径与引用；复合操作按步骤检查退出码，区分“无输出的正常状态”、部分成功和真正失败，避免前置 fetch 失败后继续使用陈旧远端引用，也避免后置只读检查的非零退出码掩盖已经成功的写操作。
• 为 Maven、JDK 和项目构建工具建立版本 profile：优先识别 Maven Wrapper、Maven/JDK 实际版本、JAVA_HOME、Toolchains、父 POM、模块结构、激活 profile、settings.xml 入口及仓库镜像，再选择全量或 -pl/-am 等聚焦构建命令；将 Maven 版本不兼容、JDK 不匹配、插件或父 POM 无法解析、缓存问题、编译失败和测试失败分类处理，不用重复执行同一命令代替诊断。
• 增加私有 Git/Maven 仓库访问诊断与安全降级：区分沙箱或工具权限、VPN/内网、DNS、代理、TLS/证书、HTTP/HTTPS/SSH 协议、凭据助手、仓库镜像和服务端不可用等原因；只读取完成诊断所需的非敏感配置，不输出令牌、密码或完整凭据，访问受限时保留本地证据并明确远端引用或依赖缓存的新鲜度，获得既有授权后在正确执行环境重试。所有命令失败均输出已执行步骤、实际副作用、失败分类、可安全重试点、替代指令和验证结果。

Changed

• knowledge 插件增加项目文档落盘配置能力；项目初始化写入 documents.workRoot、documents.designRoot 与 documents.archiveRoot，区分本地过程文档、共享设计和历史归档。
• 需求、变更计划、技术设计与 Bug 分析 Skill 统一按项目文档配置选择任务目录；缺少配置时，过程文档回退到 .craftkit/local/tasks/，不再根据根目录说明文件推断落点。
• 项目初始化增加文档生命周期默认策略；本地保留天数只用于提示，任务完成默认生成关闭预览，不自动删除文件。
• 需求、计划、设计和分析 Skill 写入文档后登记本地任务记录；沉淀、交接、归档和 Worktree 清理按任务状态联动。

[1.3.0] - 2026-08-31

Added

• 增加 .craftkit/project.json、项目资料索引和本地内容忽略规则，为 Agent 提供可共享的项目上下文入口。
• 为 branch 增加当前工作区与独立 Worktree 两种分支创建方式，以及任务结束后的 close 清理模式。
• 为 integrate 增加预集成 Worktree 的 cleanup 阶段和完整生命周期状态。
• 增加 Worktree 分支占用诊断、安全移除门禁和清理后分支、提交及主工作区验证规则。

Changed

• 脏工作区、当前 checkout 被占用或用户要求隔离时，优先在独立 Worktree 创建需求或预集成分支。
• 预集成交付范围统一以目标分支到预集成 HEAD 的真实差异判断，不再以 merge 输出、分支名、提交数量或测试结果代替纯度检查。
• 全流程自动化在独立 Worktree 的分支任务完成后进入清理门禁，释放分支占用后再结束任务。
• 增加短生命周期开发分支和批量发布约定：相关完整变更累计发布，阻断性修复可单独发布修订版本。
• 所有 Skill 的界面显示名增加完整模块调用名，例如 代码审查（dev:review-code），便于在插件列表中识别并直接调用。

[1.2.0] - 2026-08-31

Added

• 增加项目初始化到应用拆分的共同工作流，明确应用边界、拆分判据、审批门和交付基线。
• 分别增加新项目与已有项目两种执行口径。
• 新项目流程覆盖项目上下文、需求基线、业务能力地图、应用拆分、契约设计和建设计划。
• 已有项目流程覆盖现状建模、耦合识别、目标与过渡架构、数据权威、渐进迁移和回滚。

Changed

• 明确应用拆分不等于强制微服务化，允许模块化单体或暂不拆分成为评审结论。
• README 增加项目初始化与应用拆分工作流入口。

[1.1.1] - 2026-08-31

Fixed

• 文档转换脚本改为按需加载 python-docx 和 openpyxl，缺少依赖时返回明确提示，不再影响帮助和参数探测。
• 缺少转换依赖时不创建输出目录或半成品。
• 为后端设计、后端实现和前端实现补充 guidance 未安装时的规范检索回退路径，降低插件间隐式耦合。

[1.1.0] - 2026-08-28

Added

• 增加从需求归集、技术设计、代码实现、测试审核到本地提交的全流程自动化指南。
• 建立 S0 至 S9 阶段状态机、G1 至 G5 人工审批门、验证矩阵、回退规则和任务台账。
• 提供可直接交给 Codex 或其他兼容智能体的总控提示词。

[1.0.0] - 2026-08-26

Added

• 建立由 dev、doc、git、knowledge 和 skill 组成的完整 CraftKit 插件体系。
• 提供 44 个可独立发现的 Skill，覆盖软件设计与实现、文档处理、Git 交付、项目知识和规范维护。
• README 增加完整 Skill 目录、插件用途和本地使用说明。

Changed

• 收敛插件元数据和能力描述，使 CraftKit 具备稳定、可理解的首个正式版本基线。
• 清理仅服务早期建设过程的资料，保留实际运行、维护和发布所需内容。

[0.3.0] - 2026-08-26

Added

• Skill 数量扩展到 44 个，形成首个完整能力集合。
• 补齐代码实现、审查、测试、升级、工作量评估和专项技术设计能力。
• 补齐版本发布、需求整理、报告和消息编写能力。

[0.2.0] - 2026-08-25

Added

• Skill 数量扩展到 25 个，形成可用的开发、文档、Git、知识和规范能力基础。
• 增加变更计划、后端设计和前端设计等开发分析能力。
• 建立项目初始化、规范检索、交接、复盘和经验维护的基础结构。

[0.1.0] - 2026-08-25

Added

• 初始化 CraftKit 仓库和 Codex 插件市场骨架。
• 建立 dev、doc、git、knowledge 和 skill 五个插件区域。
• 建立插件清单、仓库说明和基础维护结构。