feat(knowledge): 新增分层项目交接 Skill

2026-08-25 13:56:50 +08:00
parent 27de7f3000
commit ac189b8395
13 changed files with 222 additions and 5 deletions
@@ -13,6 +13,7 @@ description: 根据当前仓库约定生成名称，并在用户确认准确命
 2. 读取当前仓库适用的 `AGENTS.md`、贡献指南或其他明确的分支约定；没有约定时再参考现有分支命名。
 3. 收集分支用途、简短描述和基准引用。不要默认 `main`、`master`、远程名称、版本分支或合并目标。
 4. 若工作区不干净，说明现有修改会随切换保留；在用户明确选择继续前不得创建分支，也不得自动暂存、提交、还原或清理。
+5. `.craftkit/local/**` 和 `.craftkit/cache/**` 不视为业务改动；若它们出现在普通状态中，提示检查 `.craftkit/.gitignore`。`.craftkit/agents/**`、`standards/**`、`knowledge/**`、`handoff/**` 和 `project.json` 属于普通项目改动，应与其他未提交内容一起展示。

 ## 生成和验证名称

@@ -14,6 +14,8 @@ description: 分析当前 Git 工作区或暂存区的真实变更，生成一
 3. 先根据文件名识别敏感路径，例如 `.env`、凭据、令牌、私钥和本地配置。对这些路径只报告风险，不读取或回显差异内容。
 4. 对其余相关路径分别读取 staged 或 unstaged diff。差异很大时先看 `--stat`，再按逻辑模块分段检查。
 5. 未跟踪文件默认不纳入建议范围；只有用户明确要求评估时，才读取已确认且不敏感的文件。
+6. `.craftkit/local/**` 和 `.craftkit/cache/**` 是本地内容，始终从提交建议、未跟踪文件评估和内容读取中排除。若这些路径已被跟踪，只提示风险，不自动修改索引。
+7. `.craftkit/agents/**`、`standards/**`、`knowledge/**`、`handoff/**` 和 `project.json` 是可共享项目资产，按真实变更正常评估，并与业务代码分组说明其 Agent、规范、知识或交接用途。

 ## 形成建议

@@ -22,7 +24,7 @@ description: 分析当前 Git 工作区或暂存区的真实变更，生成一
 - 描述应简洁说明本组变更实现的结果，使用用户或仓库约定的语言。
 - 互相依赖、共同完成一个目的的文件可归为一组；目的、模块或风险不同的变更应建议拆分。
 - staged 与 unstaged 都存在时，明确标注每条建议基于哪一种状态。
- 不把敏感文件、未确认的未跟踪文件或明显无关的改动列入建议范围。
+- 不把敏感文件、`.craftkit/local/**`、`.craftkit/cache/**`、未确认的未跟踪文件或明显无关的改动列入建议范围。

 ## 输出格式

@@ -1 +0,0 @@
-
@@ -0,0 +1,58 @@
+---
+name: handoff
+description: 基于当前任务和项目证据生成可持续更新的本地或共享交接文档，并输出新任务接续提示词。适用于任务暂停、切换会话或交接给他人；普通总结、长期知识库维护或自动提交不应触发本 Skill。
+---
+
+# 任务交接
+
+把当前任务的真实状态写入 `.craftkit/`，并输出一段可复制到新任务的接续提示词。交接只记录有证据的事实；未知、未测试或未确认的内容必须明确标记。
+
+## 选择可见性
+
+执行前确认交接范围、下一步目标和可见性：
+
+- 本地交接是默认选项，写入 `.craftkit/local/handoff/current.md`，不进入 Git。
+- 共享交接只有用户明确选择时使用，写入 `.craftkit/handoff/current.md`，可以作为项目资产提交。
+- 已有目标文件时先读取并更新，不因切换可见性自动移动或复制另一侧文件。
+
+## 初始化项目目录
+
+首次使用时，只创建 [目录说明模板](assets/craftkit-readme.md) 对应的 `.craftkit/README.md` 和 [排除规则模板](assets/craftkit-gitignore) 对应的 `.craftkit/.gitignore`，以及本次实际需要的交接目录。
+
+在 Git 仓库中执行以下检查：
+
+1. 使用 `git check-ignore --no-index -v .craftkit/README.md` 和 `.craftkit/.gitignore` 检查整个目录是否被项目规则、全局规则或 `.git/info/exclude` 错误排除。发现宽泛排除时停止并说明规则来源，不自动删除用户规则。
+2. 使用 `git ls-files -- .craftkit/local .craftkit/cache` 检查本地目录是否已经被跟踪。存在结果时停止本地写入并提示隐私风险，不自动修改索引。
+3. 初始化或修正 `.craftkit/.gitignore` 前展示内容并取得确认。规则只排除 `/local/` 和 `/cache/`，不得排除父目录。
+4. 初始化后使用 `git check-ignore --no-index -v .craftkit/local/handoff/current.md` 验证本地路径被排除；再检查 `.craftkit/README.md` 未被忽略。
+
+非 Git 目录也可以使用相同结构，但应说明没有 Git 机制区分共享与本地内容。
+
+## 收集交接证据
+
+- 确认本次交接的任务范围、当前状态和下一步目标；下一步不明确时向用户确认，不自行推断。
+- 读取项目内适用的 `AGENTS.md`、`.craftkit/README.md`、相关设计或说明文档，以及本次可见性对应的已有交接文件。
+- 在 Git 仓库中只读检查 `git status --short --branch`、必要的 `git diff --stat`、`git diff --cached --stat` 和与本任务相关的 `git log`。
+- 只把实际执行过的测试和观察到的结果写入“验证”；没有运行的验证写为“未验证”，不以静态检查代替运行结果。
+- 避免记录凭据、令牌、私钥、个人信息和不必要的内部地址。引用项目文件时优先使用相对路径。
+
+## 生成和更新文档
+
+按 [交接模板](assets/handoff-template.md) 生成文档。目标文件不存在时创建；已存在时先完整读取，再按章节更新：
+
+- 保留无法确认用途的既有章节和用户内容。
+- 合并重复待办，删除已完成项前必须有当前证据。
+- 被新证据推翻的旧结论应改写并说明依据，不保留互相矛盾的活跃结论。
+- 不整文件覆盖，不自动建立历史归档。只有用户明确要求保留历史时，才在当前可见性对应的 `handoff/history/` 创建带日期的副本。
+- 写入后重新读取关键章节，并运行 `git status --short --ignored`。本地交接必须处于 ignored 状态；共享交接应作为普通项目文件可见。
+
+## 接续提示词
+
+文档完成后直接输出一段简短提示词，至少包含：
+
+1. 先读取本次实际交接路径和其中明确引用的项目文件。
+2. 复述任务目标、已完成内容、限制、风险和待办。
+3. 给出下一步计划，并在发生写入或外部操作前遵循项目授权约定。
+4. 内联最多三条最容易重复踩到的风险；其余内容留在交接文档中。
+
+最后报告写入路径、可见性和主要更新，不执行 `git add`、`git commit` 或 `git push`。共享交接可由用户后续确认提交；本地交接不得交给其他 Git Skill 提交。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Task Handoff"
+  short_description: "生成本地任务交接文档和新任务接续提示词"
+  default_prompt: "使用 $handoff 总结当前任务，先确认交接内容保存在本地还是作为项目共享文件。"
@@ -0,0 +1,3 @@
+# Local CraftKit data
+/local/
+/cache/
@@ -0,0 +1,16 @@
+# CraftKit 项目资料
+
+本目录保存当前项目供 Agent 使用的配置、开发规范、可复用知识和交接内容。
+
+## 目录约定
+
+- `project.json`：可共享的项目元数据和默认参数。
+- `agents/`：项目对特定 Agent 的补充指令和示例。
+- `standards/`：项目编码、文档、Git 和测试规范。
+- `knowledge/pitfalls/`：经过验证的可复用问题经验。
+- `knowledge/decisions/`：重要技术决策及其依据。
+- `handoff/`：用户明确选择共享的任务交接。
+- `local/`：仅当前工作副本使用的交接、记忆和运行状态。
+- `cache/`：可重新生成的临时缓存。
+
+共享目录可以按项目提交纪律进入 Git；`local/` 和 `cache/` 必须由本目录的 `.gitignore` 排除。不得在本目录保存凭据、令牌、私钥、个人机器绝对路径或无必要的个人信息。
@@ -0,0 +1,42 @@
+# 任务交接
+
+## 任务概览
+
+- 目标：待确认
+- 当前分支或工作区：待确认
+- 当前状态：待确认
+
+## 已完成
+
+- 待确认
+
+## 关键改动
+
+- 待确认
+
+## 验证结果
+
+- 已验证：待确认
+- 未验证：待确认
+
+## 关键结论
+
+- 待确认
+
+## 风险与限制
+
+- 待确认
+
+## 待办
+
+- 待确认
+
+## 下一步任务
+
+- 目标：待确认
+- 建议入口：待确认
+- 完成条件：待确认
+
+## 接续提示词
+
+先读取 `.craftkit/handoff/current.md` 及其中引用的项目文件。复述任务目标、已完成内容、关键限制、风险和待办，然后给出下一步计划；执行写入或外部操作前遵循项目授权约定。