# 更新日志 本文档记录 CraftKit 对使用者有明显影响的功能、工作流和兼容性变化。版本号遵循 [Semantic Versioning 2.0.0](https://semver.org/lang/zh-CN/)：主版本表示不兼容变化，次版本表示向后兼容的新能力，修订版本表示向后兼容的问题修复。 历史版本根据 Git 提交倒推，只保留重要里程碑，不逐条复述全部提交。各版本对应的 Git 历史通过 `v<版本号>` 标签标记。 这里的版本号表示 CraftKit 仓库整体发布版本。`dev`、`doc`、`git`、`knowledge` 和 `skill` 的插件清单版本仍按各插件实际变化独立维护，不要求与仓库版本保持一致。 ## [Unreleased] ### Added - `knowledge:document-output` 增加 `register` 与 `close` 模式，使用 `workRoot//task.json` 记录任务状态、文件归属、可见性和关闭处置。 - 增加“保留、沉淀、归档、删除、延后”五类关闭清单，以及共享文件逐项评审、断链检查和精确路径删除门禁。 - 增加长期文档 `pending`、`approved`、`outdated` 审核状态，以及项目级文档持续维护规范。 - 增加 `profile`、`java` 和 `python` 插件骨架，以统一契约提供多语言技术能力。 - 增加 Profile manifest、版本范围、能力状态、引用安全规则和标准库校验器。 - 增加 `python:review-python`，按项目版本审查类型、异常、资源、异步、事务和测试隔离问题。 ### Planned - 建设 Skill 评测基线，支持固定场景、验收规则和更新前后回归比较。 - 保持 `dev` 插件的通用设计、实现、测试和审查核心，不按 Java、Python、React 或 Vue 复制整套工作流；仅当专项能力具备独立安装、发布或维护需求时再评估拆分插件。 - 补充前端工程质量专项支持，增加 `test-frontend` 和 `review-typescript`，分别覆盖单元、组件与集成测试，以及 TypeScript 类型安全与模块契约。 - 增加命令环境探测与指令适配辅助 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 清理按任务状态联动。 - 需求与设计 Skill 优先更新已有权威文档；实现、升级和代码审核流程检查留存文档是否因代码或契约变化而需要同步。 - `task.json` 使用 `created`、`updated`、`referenced` 区分任务关系，关联旧文档不转移所有权，也不产生删除权限。 - README 的 Skill 说明同步覆盖文档创建、审核、持续更新、历史归档和关闭职责。 - `design-backend`、`implement-backend`、`test-backend` 和 `review-java` 接入可选语言 Profile，并在提供方缺失时保留通用回退。 - 项目画像模板升级到 Schema 2，保留顶层兼容概要并支持模块级技术栈；插件安装状态不写入共享画像。 - 多语言架构文档收敛为单一设计依据和阶段跟踪计划，并记录 Codex 当前没有 Skill 运行时依赖接口的约束。 ## [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` 五个插件区域。 - 建立插件清单、仓库说明和基础维护结构。