---
name: auto-conclusion
description: >-
  对 bug/需求、指定 Git 分支或指定 commit 做完整性总结：检索相关对话，
  整理单仓/多项目分支或 commit diff，并将对话中与这些 Git 范围相关的更新
  一并并入总结；文档正文优先写开发主内容，分支/提交明细作附录；
  也支持对已有总结文档按需求从当前对话补充归位；安装时可配置文档仓，
  落盘时可选 commit+push（失败须回报原因）。
  也支持业务疑问归档模式与知识点总结模式；所有含对话的模式都同时扫描
  用户问题和 Agent 回答，从回答中拆出有独立价值的派生问题、取舍、风险、
  边界与验证结论，再去重、分类归档，避免只按用户原始问题总结，
  也避免把业务问答无结构地连续堆叠。
  Use when the user says「总结这个对话中解决的bug」「总结刚刚完成的需求」
  「总结xx需求」「总结这些分支」「总结这些 commit」「总结分支并带上对话」
  「补充这个总结文档」「在当前对话里更新某份 conclusion」
  「归档当前对话里的业务问题」「把还没记录的业务疑问归档」
  「总结知识点」「总结对话中学到的知识」,
  mentions 开发总结/分支总结/提交总结/文档补充/业务疑问归档/知识点总结,
  or explicitly selects this skill.
---

# Auto Conclusion — 开发完整性总结

对用户当前完成的 **bug 修复**、**需求开发**，指定的 **Git 分支** / **commit**，**Git 范围 + 对话合并**，**已有总结文档的对话补充**，以及 **对话中知识点的提取与归档** 做完整性整理，写入本地 Markdown 文档。
覆盖多轮对话中的相关内容，和/或单仓库/多项目的分支与提交 diff；穿插的无关话题与无关提交不收容。

**正文优先**：先写需求、改动、流程、提测、git comment 等开发主内容；分支范围、分支变化、commit 清单等仅作**文末附录**（补充信息），不得放在文档最前充当主体。

## 触发条件

以下任一情况立即启用本 skill：

- 用户说「总结这个对话中解决的bug」「总结刚刚解决的bug」
- 用户说「总结刚刚完成的需求」「总结xx需求」（某一特定需求，不一定是上一轮对话）
- 用户说「总结这些分支」「总结某分支」「对 xx 分支做总结」「整理分支 diff」
- 用户说「总结这些 commit」「总结某次提交」「整理这几个 git 提交」
- 用户给出一个或多个分支名或 commit hash（可跨多个项目/仓库）并要求总结
- 用户说「总结这些分支并带上对话」「分支 diff + 对话里相关内容」→ **分支+对话合并**
- 用户说「总结这些 commit 并带上对话」「提交 + 对话里相关更新」→ **提交+对话合并**
- 用户说「补充这个总结文档」「在当前对话里更新/补充某份 conclusion」「把对话里的内容补进这份总结」→ **文档补充模式**
- 用户点名或 @ 一份已有总结文件并要求补充
- 用户说「开发总结」「结论归档」「auto-conclusion」
- 用户显式选中或 @ 本 skill
- 用户说「对当前对话中所提到的有关业务的问题或者疑问，还未归档的做一下归档」
- 用户说「归档当前对话里的业务问题」「把还没记录的业务疑问归档」→ **业务疑问归档模式**
- 用户说「总结知识点」「总结对话中学到的知识」「整理知识点」「总结一下学到了什么」
- 用户说「把知识点记下来」「归档知识」「knowledge summary」

触发后解析：
1. **总结类型**：`bugfix` / `feat`（可从措辞推断；不明时用 AskQuestion）
2. **总结对象**：刚刚完成的事项 / 当前对话 / 用户点名的特定需求或 bug / 已有总结文件
3. **总结模式**（可组合）：
   - 对话/需求模式
   - **分支模式**
   - **提交模式**
   - **分支+对话合并**
   - **提交+对话合并**
   - **文档补充模式**
   - **业务疑问归档模式**
4. 分支模式下：分支名列表、各分支所属项目路径、对比基线（默认 main/master）
5. 提交模式下：commit hash 列表、所属项目路径
6. 合并模式：在对应 Git 范围之外，强制从对话收容与该范围相关的更新
7. 文档补充模式：已有总结文件路径；默认写回原文件
8. **保存地址**（见「保存地址」；文档补充默认原路径）

---

## 工作流程

```
Auto Conclusion Progress:
- [ ] Phase 1: 解析意图与范围
- [ ] Phase 2: 历史对话检索与筛选
- [ ] Phase 2a: 回答内容展开与覆盖审计（所有含对话模式）
- [ ] Phase 2b: Git Diff 整理（分支和/或提交模式；可与 Phase 2 并行）
- [ ] Phase 2c: 对话×Git 关联合并（分支+对话 / 提交+对话；可与 2b 衔接）
- [ ] Phase 2d: 已有文档补充（仅文档补充模式）
- [ ] Phase 2e: 知识点提取与归档（仅知识点总结模式）
- [ ] Phase 2f: 业务疑问去重、文档匹配与归档（仅业务疑问归档模式）
- [ ] Phase 3: 结构化整理
- [ ] Phase 4: 解析保存地址
- [ ] Phase 5: 写入文档、探测仓库并确认 Git 操作
- [ ] Phase 5b: 可选 commit + push（检测到 Git 仓库且用户选中时）
```

---

### Phase 1: 解析意图与范围

1. 判定类型：
   - 含「bug」「修复」「缺陷」等 → `bugfix`
   - 含「需求」「功能」「feat」「开发」等 → `feat`
   - 同时涉及两者 → 以用户主述为准；可用 AskQuestion 确认
2. 确定主题 slug（`xxx`）：一句话主题的中文或英文短名（可中英混合），连字符分隔，去特殊字符，≤40 字符；优先选择中文用户一眼能理解的命名
3. 明确检索范围提示词（需求名、模块、报错、接口、分支名、commit hash 等）
4. **分支模式**判定：用户点名分支 / 「总结分支」「整理分支 diff」→ 进入分支模式
5. **提交模式**判定：用户点名 commit / 「总结提交」→ 进入提交模式
6. **合并模式**判定：
   - 「分支 + 对话」类措辞 → **分支+对话合并**（分支模式 + Phase 2c）
   - 「提交 + 对话」类措辞 → **提交+对话合并**（提交模式 + Phase 2c）
   - 同时点名 Git 范围并要求带上对话相关更新 → 对应合并模式
7. **文档补充模式**判定：用户点名已有总结文件并要求用当前对话补充
   - 收集文件路径（用户给出或 @ 文件）
   - 沿用原文档主题 / slug，不强制新建文件名
   - 后续走 Phase 2d → 3 → 写回原文件（或用户指定另存路径）
7.5. **知识点总结模式**判定：用户要求总结对话中的知识点
   - 不需要 Git 范围，仅从当前对话提取
   - 收集用户指定的知识点保存目录（见「知识点保存路径」章节）
   - 后续走 Phase 2e → 写入知识文档（不走 Phase 3 正文模板）
7.6. **业务疑问归档模式**判定：用户要求归档当前对话中的业务问题、疑问或尚未归档内容
   - 未点名文件时，不直接新建；先按 Phase 4 解析存档目录并执行 Phase 2f
   - 点名已有文件时，仍优先进入文档补充模式
   - 该模式收录项目/需求特定的业务结论，不与 Phase 2e 的通用技术知识混放
8. 分支模式须收集：分支名列表；项目/仓库路径；对比基线（用户指定；否则各仓优先 `main` / `master` / `develop`；仍不明则 AskQuestion）
9. 提交模式须收集：commit hash（完整或可唯一解析的短 hash）；项目路径映射
10. 多项目时先列出「项目 ↔ 分支/commits」映射表，路径或缺项先补齐再 dig diff
11. 仅点名分支/提交、未提对话 → 可不跑 Phase 2c（仍建议跑 Phase 2；无相关对话则注明跳过）

**输出**：类型、主题 slug、模式、检索关键词；Git 模式下附项目映射；文档补充模式下附原文件路径；业务疑问归档模式下附存档目录。

---

### Phase 2: 历史对话检索与筛选

一次需求/修复常跨多轮对话，须主动检索，不只看上一轮。Git 模式下本阶段可与 Phase 2b 并行；若用户仅要求裸分支/提交总结且无相关对话，可注明「无对话上下文」后跳过收容。文档补充模式以 Phase 2d 的需求锚点为主过滤当前对话。

1. **检索来源**（按可用性）：
   - 当前对话全文
   - 当前项目的 agent-transcripts（按关键词、模块、报错、需求名搜索）
   - 用户点名的历史对话 / transcript
2. **收容标准**（满足任一则纳入）：
   - 用户问题和 Agent 回答中与目标需求/bug/分支/提交直接相关的分析、方案、因果解释、改动、验证、取舍、风险与适用边界
   - 开发过程中遇到的相关问题（尝试过的方案、失败原因、最终解法）
   - 相关的代码变更说明、配置调整、测试结果
3. **Git 范围下的额外关键词**（分支/提交/合并模式）：
   - commit hash、commit subject
   - diff 中的文件路径 / 类名 / 接口名 / 配置 key
4. **排除标准**（不收容）：
   - 对话中途插入的无关任务、闲聊、其他需求/bug
   - 与当前主题或所列 Git 范围无因果关系的讨论
5. **时间线整理**：按发生顺序梳理「尝试 → 问题 → 解决」，避免堆砌原文

**输出**：相关对话摘要时间线；已排除的无关段落说明（一两句即可）。

---

### Phase 2a: 回答内容展开与覆盖审计（所有含对话模式）

凡总结范围包含对话，不能只把用户消息当成归档目录。逐条扫描 Agent 回答，识别其中能够独立检索、独立复用的：

- 显式小标题或回答中主动提出的“为什么 / 为什么不 / 有什么风险”
- 原因链、方案对比、未采用方案、失败策略、限制条件和验收方法
- 虽未被用户单独提问，但对最终结论成立必不可少的说明

同一回答包含多个独立主题时分别建立候选；只是同一结论的修辞展开则合并。例如用户只问 `extractRequestBody`，回答中又解释“为何判断 Wrapper”“为何选择 `preHandle`”“为何不用 `postHandle/afterCompletion`”，应形成独立候选，而不是只归档用户原始问题。

将候选按内容路由：项目或需求特定内容进入业务/开发文档；跨项目可复用的技术原理进入 `knowledge/`。写入前生成覆盖矩阵：

| 来源 | 候选问题 / 结论 | 类型 | 处理 | 目标或排除原因 |
|------|-----------------|------|------|----------------|

每项必须标记为“新增”“合并已有”或“排除”并说明理由。父主题已存在不代表子主题已完整归档；已有文档只覆盖部分内容时，应补充而不是整体跳过。

**输出**：回答内容候选清单 + 覆盖矩阵；各模式后续只处理矩阵中应新增或应补充的项目。

---

### Phase 2b: Git Diff 整理（分支和/或提交模式）

用户点名分支或 commit、或要求对分支/提交做总结时**必须**执行。目标：把各项目在目标 Git 范围上的**新增/修改**整理清楚，再供 Phase 2c / Phase 3 使用。整理结果进入**正文业务叙述**与**文末附录**，附录不得抢占正文位置。

#### 分支模式（逐项目）

1. 确认仓库路径与分支存在（`git rev-parse` / `git show-ref`）
2. 解析基线：`git merge-base <base> <branch>`；取 `git log --oneline <base>..<branch>`
3. 取变更：`git diff --stat <base>...<branch>`，以及按需的 `git diff <base>...<branch>`（过大则按目录/模块摘要，禁止整篇无结构粘贴）
4. 记录：新增/修改/删除文件；关键接口 / 配置 / 表结构 / 任务变更

#### 提交模式（逐项目）

1. 校验 commit 存在：`git cat-file -t <hash>` / `git show --stat --oneline <hash>`
2. 多 commit：按时间排序；对每个 hash 用 `git show` / `git diff <hash>^..<hash>`；用户给出范围时可用 `git diff A^..B` 或等价范围
3. 记录每个 commit：subject、作者、触达文件、模块级变更要点
4. 禁止混入未点名的其它提交

#### 多项目汇总表

| 项目 | 范围（分支或 commits） | 基线（如有） | 提交数 | 主要改动模块 | 备注 |
|------|------------------------|--------------|--------|--------------|------|

#### 逻辑链路草图（跨项目）

- 按调用/依赖顺序梳理（如：网关 → 服务 A → 服务 B → 配置/任务）
- 标出跨仓契约变更（API、MQ、表、配置 key）
- 与 Phase 2 对话交叉验证；仅 diff 有、对话无的变更也要写入，标注来源为「分支 diff」或「commit diff」

#### 禁止

- 编造未出现在 diff / log / 对话中的改动
- 把无关分支或其它 feature 的提交混入
- 在未确认其它项目路径时猜测仓库位置

**输出**：分项目 diff 摘要 + 跨项目逻辑链路草图。

---

### Phase 2c: 对话×Git 关联合并（分支+对话 / 提交+对话）

当模式为 **分支+对话合并** 或 **提交+对话合并**，或用户明确要求「总结 Git 范围并带上对话相关更新」时**必须**执行。

1. **锚点**（来自 Phase 2b）：
   - 分支合并：分支范围内的文件 / 模块 / 接口 + 分支上 commit subject
   - 提交合并：所列 commit 的文件 / 模块 / 接口 + subject / hash
2. 以锚点回扫 Phase 2 对话摘要，将对话内容按分支/提交/模块挂靠：
   - 该改动的动机与取舍（对话有、diff 无）
   - 尝试失败的方案与最终原因
   - 验证步骤、环境刷新、已知限制
3. **合并规则**：
   - **diff 为准**描述「改了什么」；**对话补充**「为什么 / 怎么验证 / 踩了什么坑」
   - 对话与 diff 冲突时并列写出并标注来源（分支 diff / commit diff / 对话），不擅自抹掉任一侧
   - 无法挂靠到当前 Git 范围的对话内容不收容
4. 合并模式**禁止**只输出裸 diff 或只输出对话
5. 挂靠结果：业务叙述进入正文对应章节；明细表进入附录

**输出**：Git 范围↔对话关联表 + 合并后的变更叙述要点。

---

### Phase 2d: 已有文档补充（仅文档补充模式）

当用户提到某份**已经总结好的文件**，并要求在当前对话中补充该文档时**必须**执行。

1. **读取文档**：解析路径并 Read 全文；文件不存在则停止并提示
2. **提取需求锚点**（按优先级）：
   - 「需求 / 问题是什么」或等价章节
   - front matter 主题、标题 slug、提测功能点中的需求描述
3. **按需求检索当前对话**（及必要时 transcripts）：
   - 收容与该需求开发直接相关的分析、改动、踩坑、验证、提测说明
   - 排除与该需求无关的穿插话题
4. **归位映射**：将新内容挂到文档合适章节：
   - 思路 / 问题 / 方案 / 流程 / 经验 / 提测 / git comment → 正文对应节
   - 分支范围、分项目变更清单、commit 清单 → **附录**（不得插入正文最前）
5. **合并规则**：
   - 不删除文档已有有效结论，除非对话明确修正并注明
   - 新增段落标注来源（如「对话补充 · {YYYY-MM-DD}」）
   - 若原文件仍是旧版「Git 小节在前」版式，补充时可顺带按正文优先结构重排，**必须在预览中说明**
6. 先在对话中展示**补丁预览**（将改哪些节、增删要点），再按 Phase 4 解析出的路径直接写回

**输出**：需求锚点摘要 + 对话收容清单 + 章节归位草案（补丁预览）。

---

### Phase 2e: 知识点提取与归档（仅知识点总结模式）

当用户要求「总结知识点」「整理对话中学到的知识」时**必须**执行。目标：从对话中识别用户提问的知识点问题，整理后按分类写入知识文档。

#### 1. 知识点识别

遍历用户消息和 Agent 回答，识别以下模式为「知识点候选」：

- 用户主动提问的概念性、原理性、语法性问题（如「@Around 语法怎么用」「ThreadLocal 原理是什么」）
- 用户要求解释的技术细节（如「讲一下 XXX」「XX 是怎么工作的」）
- 对话中 Agent 做出的技术原理讲解（用户提问触发的解答）
- Agent 回答中主动展开的原理、替代方案、生命周期差异、风险与边界；即使用户没有逐项提问，只要可独立迁移也要建立候选

**粒度规则**：不得机械等同于“一个用户问题 = 一个知识点”。一个回答包含多个可独立检索的技术主题时分别归档；高度相关且拆分后失去上下文时再合并。使用 Phase 2a 覆盖矩阵逐项记录处理结果。

**收录标准**：知识点必须是**通用的、可迁移的技术知识**——换一个项目、换一个场景仍然适用。

**排除**（严格区分，不可混入）：

- **业务逻辑问答**：「这个接口为什么要删掉 401」「为什么操作人要从入参取」——这些是特定需求的业务决策分析，不是通用知识点
- **需求讨论与方案选择**：「应该走哪条链路」「这个改动目的是什么」——属于开发总结范畴
- **操作指令**：「帮我改这个文件」「把内容写到 XX」
- **Review 与代码审查**：「检查一下这个代码有没有问题」——属于开发流程
- 已在 auto-conclusion 其他模式中覆盖的开发总结内容

**判断原则**：如果一个问答的答案**只在当前项目/当前需求下成立**，它是业务知识而非技术知识点；如果答案**对任何同类技术场景都适用**，它才是应当记录的知识点。

#### 2. 知识点整理

对识别出的知识点：

1. **提炼标题**：用一句话概括该知识点（如「Spring AOP @Around 切面执行流程」）
2. **整理内容**：将对话中的解答精炼为**简洁、逻辑清晰**的知识条目
3. **分类归属**：确定该知识点属于哪个类目

**写作风格要求**：

- **简洁优先**：讲清楚知识点本身即可，不要啰嗦展开；用最少的文字传递最多的信息
- **逻辑清晰**：按「是什么 → 怎么工作 → 关键注意点」的脉络组织，读者能快速抓住要点
- **克制分点**：不要过度使用列表和分点，信息密度低的罗列会降低可读性；能用一段话讲清楚的就不要拆成五条
- **代码示例从简**：只有当概念比较抽象、纯文字难以讲清时才附代码示例；示例要精炼，展示核心用法即可
- **禁止模板化堆砌**：不要机械地写「概念/定义 + 核心要点 + 代码示例 + 注意事项」四段式；按知识点特性灵活组织

#### 3. 知识文档分类

知识文档按技术领域**粗粒度**分类，不要过细。推荐类目：

| 文件名 | 涵盖内容 |
|--------|----------|
| `后端-Java有关知识.md` | Java 语法、JVM、并发、集合、设计模式等 |
| `后端-SpringBoot有关知识.md` | Spring / SpringBoot / AOP / IoC / MVC 等框架知识 |
| `后端-中间件有关知识.md` | MQ、RPC、分布式锁、配置中心等 |
| `前端-Vue有关知识.md` | Vue / React / JS / TS / CSS 等前端知识 |
| `数据库-MySQL有关知识.md` | SQL、索引、事务、分库分表等 |
| `数据库-Redis有关知识.md` | Redis 数据结构、缓存策略、分布式锁等 |
| `运维-DevOps有关知识.md` | Docker / K8s / CI/CD / 监控等 |
| `通用-工程实践有关知识.md` | Git、代码规范、架构设计、接口设计等 |

- 若知识点不属于已有文档类目，可新建合适的类目文档
- 类目命名格式：`{领域}-{方向}有关知识.md`
- 不强制使用上表全部类目，按实际知识点按需创建

#### 4. 写入规则

**已有文档追加**：
1. 读取已有知识文档
2. 检查是否存在相同或高度相似的知识点（避免重复）
3. 在文档中找到合适的位置插入新知识点（按相关性或时间排列）
4. 保持文档整体结构与可读性

**新建文档**：
1. 创建分类文档
2. 写入文档头部（标题、说明）
3. 插入第一个知识点

#### 5. 知识文档格式

每份知识文档遵循以下格式：

```
# {类目名称}

> 本文档记录 {领域} 相关知识点，持续积累更新。

---

## {知识点标题}

> 记录时间：{YYYY-MM-DD}

{知识点内容：用连贯的段落或适度的分点讲清楚，不要堆砌}

---

## {下一个知识点标题}

...
```

**格式原则**：每个知识点的内容篇幅适中（通常 5-15 行正文），读完后能清楚理解这个知识点。避免过长（变成教程）或过短（只有标题没有内容）。

#### 6. 知识点保存路径

| 优先级 | 来源 | 路径 |
|--------|------|------|
| 1 | 用户本轮指定 | 使用用户指定路径 |
| 2 | 用户级 `config.json` 的 `defaultSaveDir` | `{defaultSaveDir}/knowledge/` |
| 3 | 均未指定 | `{Downloads}/knowledge/`（跨平台解析同 Phase 4） |

- `knowledge/` 子目录不存在则创建
- 不与 auto-conclusion 的开发总结文档混放

#### 7. 展示与确认

1. 在对话中先展示「发现 N 个知识点，分属 M 个类目」的概览
2. 列出每个知识点的标题和归属类目
3. 直接写入文件（落库即执行，与 auto-conclusion 主流程一致）
4. 写入后回显：各文件路径 + 新增/追加的知识点标题

---

### Phase 2f: 业务疑问去重、文档匹配与归档（仅业务疑问归档模式）

当用户要求归档当前对话中尚未记录的业务问题或疑问、但没有点名已有文件时，必须执行。目标是先复用现有归档，再在确实没有匹配文档时新建。

1. **整理问题单元**：遍历用户消息与 Agent 回答；除显式追问外，把回答中的原因、方案取舍、失败策略、适用边界和验证要求展开为候选问题单元。同一回答内可独立检索的子问题分别归档，重复解释才合并；保留最终结论，旧结论被修正时记录修正关系。
2. **过滤范围**：只收录项目或需求特定的业务逻辑、调用链、配置边界、接口行为和方案决策。排除 Skill / AskQuestion 等元讨论、纯操作指令、闲聊，以及应进入 Phase 2e 的通用技术知识。
3. **问题分类与排序**：
   - 写入前按实际业务语义聚类，分类名须能直接说明内容，例如“配置与注册”“请求执行链路”“审计数据来源”“异常与边界”；不得机械套用固定目录，也不得把大量问题塞进“其他”
   - 类目数量服从内容规模：少量强相关问题可归为一类；问题较多时拆成 2～6 个稳定类目，避免一问一类或单类堆叠
   - 类内按“背景/是什么 → 何时触发/怎么执行 → 为什么这样设计/方案取舍 → 异常、边界与验证”排序；存在依赖关系时以理解顺序优先
   - 覆盖矩阵增加“所属分类”列；先完成分类，再做文档匹配和补丁预览
4. **解析并检索存档目录**：按 Phase 4 的保存地址优先级解析目录，递归检索其中的 Markdown 文件；除非用户明确要求，默认排除 `knowledge/` 等知识点目录。
5. **检查是否已经归档**：使用问题主题、需求名、模块、接口路径、类名、配置 key 等锚点搜索候选文档。完整已有则跳过；只记录了部分结论则列为待补充，不重复创建相同问答。
6. **匹配已有文档**：综合文档标题/front matter、需求章节、Q&A 标题和正文锚点选择最匹配文档。确定候选后必须阅读全文，确认其主题确实能够承接该问题。
7. **归档决策**：
   - 一个问题簇有唯一强匹配文档 → 按原结构归位补充
   - 多个独立主题分别匹配不同文档 → 分别补充，不强塞进单一文档
   - 多个候选同等匹配且选择会改变归档语义 → 使用 AskQuestion；不可用时按既有降级规则文本确认
   - 没有强匹配文档 → 才允许新建 `feat-{slug}-业务逻辑QA-{timestamp}.md`
8. **覆盖审计**：按 Phase 2a 展示候选的新增 / 合并已有 / 排除结果，禁止只列用户显式提出的问题。
9. **预览与写入**：先展示“已归档 / 待补充 / 需新建”清单，以及每个目标文件的补丁预览，再按 Phase 4 直接写入。
10. **结果回显**：列出每个问题的处理结果、目标文件和新增章节；若全部问题均已归档，明确说明并且不修改文件。

#### 既有业务 QA 文档的分类保护

对已有文档做分类迁移或补充时，默认采用“内容不变、结构增强”：

1. 先阅读全文，记录既有标题、Q 编号、锚点和原始顺序；已有问答正文视为受保护内容。
2. 若不移动问答块即可分类，只插入分类标题，问答原文、顺序和编号保持不变。
3. 若同类问题分散、必须移动正文才能聚合，则不移动旧内容；新增“分类导航”，按“分类 → 既有 Q 编号/标题”建立索引，正文保持原位。
4. 新增问题放入对应分类；旧文档没有合适承载位置时，在文末新增“分类补充 · {YYYY-MM-DD}”，按分类写入，并延续既有 Q 编号。
5. 只有用户明确要求重构旧文档时，才允许移动完整问答块；仍不得改写、删减、拆分或重新编号，且预览中须列出迁移映射。

禁止为了版式统一而重写旧答案、批量改标题或重排编号；明确过时的结论按原规则追加修正说明，不直接覆盖历史内容。

**禁止**：只看文件名就决定归属；未检索存档目录便新建；把同一问题重复写入多份文档；因没有点名文件就默认进入新建文档流程。

**输出**：业务问题清单 + 分类结果 + 去重结果 + 文档匹配依据 + 补丁预览。

---

### Phase 3: 结构化整理

按下列模板组织内容（缺项写「无」或「未涉及」，禁止编造）。

**正文优先原则**：先写与开发直接相关的主内容（需求、思路、问题、方案、流程、经验、提测、git comment）；分支范围、分支变化、commit 清单等仅作**文末补充信息**。

- **分支模式**：须含附录 A / A.1 / A.2
- **提交模式**：须含附录 A.3（可与分支附录并存）
- **分支+对话 / 提交+对话合并**：须含附录 A.4
- 对话/需求模式可省略附录；无 Git 输入时不要硬造附录
- **文档补充模式**：以原文件结构做增量归位；预览中说明是否重排为正文优先
- **业务疑问归档模式**：匹配到已有文档时按原结构分类归位，并遵守“既有业务 QA 文档的分类保护”；无匹配而新建时采用“背景 + 分类导航 + 分类 Q&A + 结论边界”结构，不套用完整开发总结模板

```markdown
# {feat|bugfix}-{slug}

> 归档时间：{YYYY-MM-DD HH:mm:ss}
> 类型：需求开发 | Bug 修复 | 分支改动总结 | 提交改动总结 | 文档补充
> 主题：{一句话主题}
> 模式：对话/需求 | 分支 | 提交 | 分支+对话合并 | 提交+对话合并 | 文档补充

## 1. 需求 / 问题是什么
[要解决什么；背景、目标、验收点]

## 2. 解决思路
[总体思路与关键决策；为何选此方案；Git 相关结论用业务语言写入此处，细节见表放附录]

## 3. 解决过程中遇到的问题
[按条列出；含尝试过但未采纳的方案；合并/补充模式吸收对话踩坑]

## 4. 问题的解决方案
[每个问题对应如何解决；指向关键改动/文件]

## 5. 整体解决流程
[从发现问题/接到需求到完成的阶段顺序]

## 6. 开发流程
[实际开发步骤：改了哪些模块/仓库、如何验证、是否环境刷新等]

## 7. 问题点与经验总结
[可复用的经验、避坑点、下次可直接参考的结论]

## 8. 变更说明（提测用）
[给测试的变更清单：功能点、影响范围、分项目回归建议、已知限制]

## 9. Git Commit Message
```
<type>(<scope>): <中文描述>（必要的类名/接口名等可保持英文）
```

## 附录 A. 分支与项目范围（补充）
[项目路径、分支、基线、commit 范围；多项目逐条列出]

## 附录 A.1 分项目变更清单（补充）
[按项目：新增/修改/删除要点，模块级摘要，不堆原始 diff]

## 附录 A.2 跨项目逻辑链路（补充）
[端到端改动如何串起来；契约与依赖顺序]

## 附录 A.3 指定提交清单（补充）
[hash / subject / 项目]

## 附录 A.4 对话与 Git 范围的关联补充
[按分支或按提交/模块：动机、问题、验证；来源标注为对话]
```

Git / 合并模式下第 2 / 3 / 4 / 5 / 6 / 7 / 8 节**必须吸收** diff 与（若有）对话关联结论写成业务叙述；明细表放附录。不得以对话臆测替代已存在的 Git 改动，也不得在合并模式下丢掉对话补充。不得把附录章节挪到正文之前。

**Git Commit 规范**：
- conventional commits：`feat` 或 `fix`（与类型一致）
- `scope` 为主要模块；多项目时可写主导仓或 `multi`
- `<type>(<scope>):` 保持英文，冒号后描述用**中文**（必要的类名、接口名等可保持英文），可直接用于 `git commit`
- 每条 50 字以内
- 多仓库时可为每个主要项目各给一组 commit message

**输出**：完整 Markdown 正文或补丁预览（先在对话中展示，再写入文件）。

---

### Phase 4: 解析保存地址

按优先级解析保存目录/路径：

| 优先级 | 来源 | 行为 |
|--------|------|------|
| 1 | **文档补充模式**：用户点名的原文件 | 默认直接写回原文件；仅用户明确要求另存时使用指定路径 |
| 2 | 用户在本轮对话中明确给出路径 | 直接使用该路径并写入 |
| 3 | skill 安装配置中的默认路径（见「安装时配置」） | 配置路径有效时直接使用并写入 |
| 4 | 均未指定 | 解析系统「下载」文件夹并直接写入 |

**业务疑问归档模式**先按上表解析存档目录，再执行 Phase 2f：匹配成功后，以已有文档路径作为实际写入目标；没有匹配文档时，才在解析出的目录中新建业务 QA 文档。用户明确点名已有文件时，文档补充模式优先。

**默认下载目录（跨平台，禁止写死绝对路径）**：

| 系统 | 解析方式 |
|------|----------|
| macOS / Linux | `$HOME/Downloads`（若目录不存在，回退 `$HOME`） |
| Windows | `%USERPROFILE%\Downloads` 或 `$env:USERPROFILE\Downloads`（若不存在，回退 `%USERPROFILE%`） |

解析命令示例：

```bash
# macOS / Linux
DEFAULT_DIR="${HOME}/Downloads"
[ -d "$DEFAULT_DIR" ] || DEFAULT_DIR="$HOME"

# Windows PowerShell
$DEFAULT_DIR = Join-Path $env:USERPROFILE "Downloads"
if (-not (Test-Path $DEFAULT_DIR)) { $DEFAULT_DIR = $env:USERPROFILE }
```

**落库即执行**：解析出保存路径后立即进入 Phase 5 写入文件，无需 AskQuestion 确认写盘。禁止在文件写入成功前询问 Git 操作，也禁止把 Git 选择和代码修复、需求确认等无关决策合并。

---

### Phase 5: 写入文档并回显

1. **新建文件名**（verbatim 规则；文档补充写回原文件时不适用）：
   - 需求：`feat-{slug}-{timestamp}.md`
   - Bug：`bugfix-{slug}-{timestamp}.md`
   - 业务疑问归档且无匹配文档：`feat-{slug}-业务逻辑QA-{timestamp}.md`
   - `timestamp`：`YYYYMMDD-HHmmss`（本地时区）
2. 目录不存在则创建
3. 写入完整 Markdown（或文档补充后的全文）
4. 写入成功后，按下方优先级探测文档 Git 仓库并取得 Git 操作选择
5. 用户选择 commit+push 时执行 Phase 5b
6. 对话中告知**完整绝对路径**、Git Commit Message（若有）、以及 commit/push 结果（含失败原因）

**输出**：文件路径 + 是否写入成功 +（可选）commit/push 结果。

#### 写入后的 Git 仓库检测

| 优先级 | 检测方式 | 说明 |
|--------|----------|------|
| 1 | 用户级 `config.json` 中 `docsGitRepo` | 配置有效且目标文件位于其工作树内时使用 |
| 2 | 目标文件所在目录向上查找 Git 仓库 | 在目标文件目录执行 `git rev-parse --show-toplevel`，成功即为有效仓库 |

检测到仓库时，必须单独处理 Git 决策：

| 选项 | 行为 |
|------|------|
| **commit + push** | 只暂存本次新增或更新的总结文档，执行 commit 后 push |
| 仅落盘不推送 | 文件已写入，不执行 Git 操作 |

- 用户原话已经明确要求「提交 / commit / 推送 / push」时，按动作粒度视为已授权：明确 push 包含必要的本地 commit；无需重复询问
- 文档仓存在无关未提交改动时，先报告，但只 `git add` 本次目标文档；不得把无关文件带入提交，也不得因此静默跳过 Git 选项
- 目标文档无法与其它改动安全隔离时，停止 Git 操作并报告原因，保留已写入文件
- 两种检测方式都不命中时，明确说明「未检测到文档 Git 仓库」后完成
- 文档补充模式同样必须在写回后执行仓库检测
- 结构化提问工具不可用时，先提示「当前运行环境或会话模式未开放结构化提问工具（如 AskQuestion），将改用纯文本选项确认。」，再用文本编号只确认 Git 操作；文件已经写入，用户回复前不执行 commit/push

---

### Phase 5b: 可选 commit + push（检测到 Git 仓库时）

当 Phase 5 已写入文档，且用户选择或已明确授权 commit+push 时执行：

1. 解析仓库根：优先取有效且包含目标文件的 `docsGitRepo`；否则取目标文件目录 `git rev-parse --show-toplevel` 的结果
2. 确认保存文件位于该仓库工作树内；否则跳过 Git 并说明原因，不回滚已写入文件
3. 在该仓库内只暂存目标文档：
   - `git add <相对仓库根的目标文件路径>`
   - `git commit`：message 必须按下方「文档仓 commit message 规范」，禁止只贴文档 §9 或只写文件名
4. `git push`：推送到当前分支上游；无上游时尝试设置跟踪或报告需用户指定 remote/branch，不 force push
5. 超时、网络、认证或 non-fast-forward 等失败时，不回滚本地 commit 与已写入文件，并明确报告原因
6. 成功则回报 commit hash、远程、分支及完整 commit message

#### 文档仓 commit message 规范（Phase 5b 强制）

| 场景 | Subject 要求 |
|------|----------------|
| 新建总结 | 明确写出「新增需求开发文档」或 `docs(conclusion): add ...` |
| 文档补充 | 明确写出「补充需求开发文档」或 `docs(conclusion): update ...` |

推荐格式：

```
docs(conclusion): 新增需求开发文档 — {一句话主题}

新增需求开发文档：{文件名}

{文档主要内容摘要：需求要点 / 关键改动 / 提测要点}
{可选：附文档 §9 中英 commit 原文各一行}
```

- Subject 必须点明新增或补充需求开发文档，不能只有业务改动描述
- Body 先写动作与文件，再写新增或补充文档的内容摘要
- 文档补充模式用「补充」替代「新增」措辞
- commit 前在对话中展示完整 commit message

**输出**：push 成功 / 跳过（原因）/ 失败（原因）；本地 commit 是否已完成；所用 commit message。

---

## 安装时配置（默认保存地址与文档仓）

**安装或首次同步到全局 skills 时**，Agent 须用 AskQuestion 询问默认文档保存目录：

| 选项 | 行为 |
|------|------|
| 使用系统下载文件夹 | 将默认目录记为跨平台 Downloads 解析结果 |
| 自定义目录 | 用户提供路径并写入配置 |
| 跳过（不保存默认配置） | 不写配置；每次 Phase 4 按优先级解析保存路径 |

### 配置文件位置（强制：仓库外）

配置写入**用户级**路径，**禁止**写入 skills 仓库或技能源码目录（软链到全局 skills 时会污染 Git 工作树）：

| 系统 | 配置文件路径 |
|------|----------------|
| macOS / Linux | `$HOME/.config/auto-conclusion/config.json` |
| Windows | `%APPDATA%\auto-conclusion\config.json`（或 `$env:APPDATA\auto-conclusion\config.json`） |

目录不存在则创建。仓库内仅保留 `config.json.example` 作模板。

**兼容迁移**：若仍存在「技能目录下的旧 `config.json`」：

1. 读取旧文件
2. 写入上述用户级路径
3. 删除技能目录内旧文件（避免再次出现在 Git 状态里）
4. 之后只读写用户级路径

用户指定或确认 **存储目录** 后：

1. 将 `defaultSaveDir` 与 `configuredAt` 写入**用户级** `config.json`
2. **探测 git 仓库**（保存目录本身或其父目录）：

```bash
# 从 SAVE_DIR 起向上查找仓库根
git -C "$SAVE_DIR" rev-parse --show-toplevel 2>/dev/null
# 若失败，对 dirname 逐级上溯直至文件系统根，再次尝试
```

3. 若发现仓库根路径：
   - 用 AskQuestion / 文本确认：「是否将仓库 `<repo-root>` 配置到 json，便于总结落盘后 commit+push？」
   - 用户同意 → 写入 `"docsGitRepo": "<repo-root>"`
   - 用户拒绝或跳过 → `docsGitRepo` 置空或不写入
4. 未发现 git 仓库 → 不询问，`docsGitRepo` 留空

用户级 `config.json` 结构：

```json
{
  "defaultSaveDir": "<user-chosen-or-downloads-path>",
  "docsGitRepo": "",
  "configuredAt": "<ISO-8601>"
}
```

规则：
- 有用户级 `config.json` 且 `defaultSaveDir` 有效 → Phase 4 直接使用该路径
- 有有效 `docsGitRepo` → Phase 5 写入成功后**必须**提供「commit + push 到配置仓库」选项
- 无配置或路径失效 → 回退 Downloads 并直接写入
- **不要**把机器特定绝对路径写进 `SKILL.md` 或提交进 Skills 仓库；只写入**用户级** `config.json`
- Skills 仓库须 gitignore `auto-conclusion/config.json`
- push 失败不得 silent 跳过；必须把失败原因写进对话结果

---

## 注意事项

- **AskQuestion 不可用时**：若无法呼起 AskQuestion，**必须在对话中提示**：「当前运行环境或会话模式未开放结构化提问工具（如 AskQuestion），将改用纯文本选项确认。」；再用编号选项确认类型、项目路径、Git 操作、是否配置 `docsGitRepo` 等需要用户决策的事项，禁止静默跳过。
- **配置在仓库外**：本机 `defaultSaveDir` / `docsGitRepo` 只写 `$HOME/.config/auto-conclusion/config.json`（Windows 见上表），禁止写进技能源码目录
- **正文优先**：开发主内容（需求/改动/流程/提测/git comment）在前；分支/提交明细仅附录
- **文档补充**：须先提取原文档需求，再按需求过滤当前对话后归位写入；默认写回原文件
- **业务疑问先匹配后新建**：须先整理和去重当前对话的业务问题，再检索存档目录；有匹配文档就归位补充，没有强匹配文档才允许新建业务 QA 文档
- **业务问答先分类后写入**：不得把问题按对话顺序简单堆叠；按业务语义聚类并按理解顺序组织，分类结果须进入预览
- **分类迁移保护旧内容**：已有业务 QA 默认不改写、不删减、不重新编号、不移动问答块；无法原地分类时增加分类导航，只有用户明确要求重构才迁移完整块
- **安装探测 git**：指定保存目录后探测目录/父目录是否为 git 仓，经用户确认后写入用户级配置的 `docsGitRepo`
- **落盘后必探测仓库**：Phase 5 写入成功后，优先使用有效 `docsGitRepo`，否则从目标文件目录向上探测；检测到仓库必须单独处理 commit+push，push 超时/失败须回报原因且不回滚本地 commit
- **Git 决策独立**：禁止把文档 Git 选择和代码修复、需求确认等无关选项合并；工作树有无关改动时只暂存本次目标文档
- **文档仓 commit**：push 前的 message 须先写明「新增/补充需求开发文档」，再写文档内容摘要，禁止只贴 §9
- **分支模式 / 提交模式**：点名分支或 commit 时必须跑 Phase 2b；多项目分别整理 diff 后再做逻辑链路总结
- **分支+对话合并 / 提交+对话合并**：必须跑 Phase 2c；改动事实以 git 为准，过程与原因以相关对话补充
- **多仓库路径**：未给出其它项目路径时，先 AskQuestion/纯文本确认路径，禁止猜测仓库位置
- **只收容相关内容**：多轮、跨对话检索；无关穿插与无关提交一律排除
- **回答同样是归档源**：不得只扫描用户问题；必须检查 Agent 回答产生的独立问题、结论、取舍、风险与边界
- **子问题覆盖**：父主题已有不等于回答中的原因、替代方案、风险和边界已归档；写入前必须逐项给出新增、合并已有或排除结果
- **禁止编造**：对话或 diff 中未出现的方案、问题、变更不得写入
- **先展示后落盘**：Phase 3 正文或补丁预览须在对话中可见，再按 Phase 4 解析出的路径直接写入；检测到 Git 仓库后再确认是否 commit + push
- **AskQuestion 优先**：类型歧义、基线不明、项目路径缺失、Git 操作用对话内弹框，不另开纯追问
- **命名 verbatim**：`feat-{slug}-{timestamp}.md` / `bugfix-{slug}-{timestamp}.md`；slug 可用中文、英文或中英混合，优先让中文用户易于理解
- **跨平台路径**：用 `$HOME` / `%USERPROFILE%` / `%APPDATA%` 解析，禁止写死 `/Users/...` 或 `C:\Users\...` 进 SKILL.md
- **commit 中文描述**：§9 commit message 的 `<type>(<scope>):` 保持英文，描述用中文（必要类名等可英文）；提测与 commit 章节必填（文档补充若无新 commit 需求可保留原文），便于直接使用
- **知识点总结独立模式**：知识点模式不走 Phase 3 正文模板，直接按 Phase 2e 规则写入分类知识文档
- **知识文档粗粒度分类**：类目不要过细，一个类目涵盖一个技术领域，避免每个细分主题建一个文件
- **知识点去重**：写入前检查目标文档是否已有相同知识点，相同则跳过或合并补充，不重复写入
- **可读性优先**：知识点内容简洁有逻辑，不堆砌分点，不滥用代码示例；每次写入后文档结构清晰、排版工整，禁止只做简单 append 而不管上下文衔接
- **知识路径隔离**：知识文档存放在 `knowledge/` 子目录，与 feat/bugfix 总结文档目录隔离