knowledge-digest-zh

name	knowledge-digest-zh
description	全面知识总结技能：全局可用，在任务完成后提炼垂直领域知识点、工作流方法论、AI协作技巧，用小白举例帮助真正学到东西。Use when: 总结知识点、学习总结、知识卡片、帮我学到东西、这次学到了什么、知识提炼。每次任务结束后自动触发（由全局指令驱动），也可在任意工作区手动调用。

全面知识总结技能

Project structure gate / 文件树结构门禁

只要本工作流将初始化或重组项目，或新建、移动应用、服务、包、模块、页面、API、研究步骤、实验、流水线、测试、文档或多文件产物树，必须先使用 project-structure-architect。

1. 开始前：读取适用的 AGENTS.md、PROJECT_STRUCTURE.md、.project-structure.yaml 和现有文件树，锁定项目类型、蓝图及唯一合理路径。
2. 运行中：每次新增或移动文件前先判断职责、所有者、复用范围和对应测试；禁止同义目录、根目录堆放、跨层混放及无关重组。
3. 阶段收口：纵向切片或阶段完成后检查结构漂移；新项目或重大重组更新结构文档，最终运行结构审计。出现 BLOCK 时停止结构性写入并先修正或询问用户。

纯内容编辑且目标路径已由用户或现有规范唯一确定时，可不重复调用。

技能目标

确保用户在每次 AI 协作后不只是"拿到结果"，而是真正学到：垂直领域知识、可迁移的工作流方法论、AI 协作技巧。通过小白举例和自测机制促进深度理解。

Markdown 交付要求

1. 使用本技能完成正式输出时，除聊天中的简要说明外，必须在当前工作区新建一个总结文件夹保存完整结果。
2. 默认保存位置为当前工作区 skill-outputs/knowledge-digest-zh/（与 artifact-curator-zh 按技能分子目录的规范一致；历史写在 skill-outputs/ 根下的交付为 legacy-flat，兼容并存）。若该子目录不存在须先创建。
3. 默认在上述目录下新建子文件夹，名格式为 中文主题_YYYYMMDD_HHMMSS/（文件夹名不再重复 skill 名）；若主题不明确，使用 学习总结_YYYYMMDD_HHMMSS/。
4. 总结文件夹至少包含 README.md，深度总结还应包含 知识总结.md、自测题.md 和 可复用工作流.md。
5. README.md 必须说明本次总结主题、包含文件、阅读顺序和一句话收获。
6. Markdown 内容必须包含完整知识总结、核心知识点、小白举例、工作流方法论、AI 协作技巧与自测内容（如有）。
7. 若用户明确指定保存路径或文件名，以用户要求为准；若用户明确要求只在对话中回答，可跳过创建文件。
8. 最终回复中要说明新建的总结文件夹路径（须含 skill-outputs/knowledge-digest-zh/ 前缀），以及文件夹里包含的主要文件。

总结文件夹结构

模式A 默认结构

skill-outputs/knowledge-digest-zh/中文主题_YYYYMMDD_HHMMSS/
  README.md
  学习摘要.md

模式B 默认结构

skill-outputs/knowledge-digest-zh/中文主题_YYYYMMDD_HHMMSS/
  README.md
  知识总结.md
  可复用工作流.md
  自测题.md

模式C 默认结构

skill-outputs/knowledge-digest-zh/中文主题_YYYYMMDD_HHMMSS/
  README.md
  自测题.md
  参考答案.md

如果任务同时包含代码链路分析，可额外增加 链路拆解.md；如果用户要求“知识卡片”，可额外增加 知识卡片.md。

全局可用声明

• 本技能位于 ~/.agents/skills/learning/knowledge-digest-zh/，属于用户级全局 skill
• 对所有工作区、项目、实验、问答、论文、翻译、开发任务可用
• 默认由 ~/.agents/.instructions.md 在任务结束时自动触发模式A
• 在任意对话中也可以手动触发模式B或模式C

分析开头字段解析规则

• 当本次输入包含表格、指标、配置项、数据列、接口字段、日志字段等结构化字段时，正式分析前必须先输出“字段解析”。
• 字段解析至少说明：字段名、字段含义、单位/取值范围（如有）、它在本次分析中的作用。
• 字段解析放在分析结果最开头，再进入任务全景、知识点、工作流等主体内容。
• 字段信息不完整时先标注“待确认”，不得猜测。

链路型代码任务附加规则

• 当本次任务涉及接口追踪、函数调用链、依赖注入、数据流传递、RAG 检索链路等代码链路问题时，必须按真实链路组织讲解，不能把函数写成彼此脱节的清单。
• 讲解顺序固定优先为“入口 → 中间节点 → 外部调用/落库 → 返回”，并在相邻节点之间明确写出传递了什么对象、参数、配置或中间结果。
• 每个函数/方法节点至少说明：文件路径和行号、当前职责、上游是谁、传入了什么、下游是谁、继续传了什么、最终返回了什么。
• 如果是工厂模式、依赖注入、策略分发或多实现分支，必须标明“选择条件 → 选中的实现 → 继续流向”，不能把候选实现误写成串行下游。
• 如果两个函数之间没有直接调用证据，只能写“并列依赖”或“待确认”，不得为了凑链路强行建立上下游关系。
• 对代码教学型内容，优先回答“这一跳为什么发生、这一跳把什么交给了下一跳”，而不是只回答“这个函数做了什么”。

触发模式

模式	触发方式	输出规模
A. 自动摘要	任务完成后自动附加（全局指令驱动）	精简卡片
B. 深度总结	用户主动说"帮我总结知识点""这次学到了什么"	完整知识报告
C. 自测检验	用户说"考考我""出几道题"	基于本次内容的测验题

---

模式A：自动摘要（任务结束后附加）

输出结构

文件：学习摘要.md

---
📚 **学习摘要**

**核心知识点**（本次最值得记住的 2-3 个）

1. **[知识点]**
   - 是什么：[一句话精确定义]
   - 小白版：[生活化类比，零基础能懂]
   - 本次怎么用的：[在任务中的具体体现]

2. ...

**带走三件套**
- 🧠 领域知识：[一句话概括学到的垂直知识]
- 🔧 工作流：[一句话概括可迁移的方法/流程]
- 🤖 AI技巧：[一句话概括和AI协作的经验]

💡 **想一想**：[一个引导深入思考的问题]
---

模式A质量标准

1. 知识点数量：2-3个，不贪多
2. 小白版必须用类比（做饭/快递/整理房间/排队/购物等）
3. 不超过 15 行——精简是核心
4. "想一想"要和本次任务直接相关，能引发思考

---

模式B：深度总结（主动触发）

输出结构

主文件：知识总结.md

# 📚 知识总结报告

## 零、字段解析

- [字段名]：[含义]；[单位/取值]；[本次作用]
- [字段名]：[含义]；[单位/取值]；[本次作用]

## 一、本次任务全景

**任务类型**：[开发/实验/分析/写作/...]
**核心目标**：[一句话]
**涉及技术栈/领域**：[列出]

## 二、垂直领域知识点

### 知识点1：[名称]

**精确定义**：[学术/技术层面的准确解释]

**小白理解**：
> [用一个完整的生活场景类比，不是一句话，而是一个小故事]
> 比如：想象你在整理衣柜...

**关键细节**：
- [细节1]
- [细节2]
- [容易搞混的地方]

**本次实战应用**：
- 在本次任务中，我们用它做了 [什么]
- 具体体现在 [哪行代码/哪个步骤]

**知识网络**：
- 前置知识：[理解这个需要先知道什么]
- 相关概念：[和什么概念经常一起出现]
- 进阶方向：[想深入可以学什么]

### 知识点2：...
（重复上述结构，3-6 个知识点）

### 链路型代码任务追加结构（仅在涉及代码/接口/调用链时启用）
```markdown
## X、链路传递拆解

**链路总览**：
入口函数/入口请求 → 函数A → 函数B → 外部依赖/数据库 → 返回

### 节点1：[函数名]
- 文件：[路径:行号]
- 上游：[谁调用它 / 从哪里进入]
- 当前动作：[本节点完成的动作]
- 传入：[参数 / 对象 / 配置 / 上下文]
- 下游：[调用了谁]
- 传出：[交给下一跳的内容]
- 返回：[返回给上游的结果]

### 节点2：[函数名]
- 文件：[路径:行号]
- 上游：[谁调用它]
- 当前动作：[本节点完成的动作]
- 传入：[参数 / 对象 / 配置 / 上下文]
- 下游：[调用了谁]
- 传出：[交给下一跳的内容]
- 返回：[返回给上游的结果]

三、工作流与方法论

本次用到的工作流

步骤1 → 步骤2 → 步骤3 → ...

这个工作流可以迁移到

• [场景1]：[怎么迁移]
• [场景2]：[怎么迁移]

方法论总结

• [原则1]：[解释]
• [原则2]：[解释]

四、AI 协作技巧

本次协作中的有效做法

1. [做法]：[为什么有效，可以复用到什么场景]
2. ...

本次协作中可以改进的地方

1. [问题]：[下次可以怎么做更好]

AI 协作通用经验

• [一条可复用的经验]

五、自测区

快速检验（回答这 3 个问题说明你真学会了）

1. [概念理解题]
2. [应用场景题]
3. [对比辨析题]

参考答案

1. [答案]
2. [答案]
3. [答案]

六、一句话总结

[用一句话概括本次最大的收获]

### 模式B质量标准

1. 知识点 3-6 个，每个都有完整的"定义→小白版→细节→实战→网络"结构
2. 小白理解用**完整场景故事**，不是一句类比
3. 工作流要画出步骤链，并给出至少 2 个迁移场景
4. AI 协作技巧要包含"有效做法"和"可改进的地方"——诚实反思
5. 自测区 3 道题，覆盖"理解→应用→辨析"三个层次
6. 所有内容基于本次任务实际涉及的知识，不扩展编造
7. 若输入含结构化字段，报告开头必须先做字段解析，再进入正文
8. 若任务属于代码链路分析，必须让读者一眼看出“上游函数 → 当前函数 → 下游函数”以及每一跳传递的对象，不能只列函数名和职责

---

## 模式C：自测检验（主动触发）

### 出题规则

根据本次任务内容出 5-8 道题，题型分布：

| 题型 | 数量 | 难度 | 考察 |
|------|------|------|------|
| 概念判断 | 1-2 | 基础 | 知道是什么 |
| 选择/填空 | 1-2 | 基础 | 记住关键细节 |
| 应用题 | 1-2 | 中等 | 能在新场景使用 |
| 对比辨析 | 1 | 中等 | 区分易混概念 |
| 开放思考 | 1 | 进阶 | 能举一反三 |

### 输出格式

文件：`自测题.md`

先出题，等用户作答后再给评分和解析。如果用户说"直接给答案"，则一次性给出题目+答案，并把答案写入 `参考答案.md`。

---

## 知识点质量红线

1. **不编造**——只总结本次任务实际涉及的知识
2. **不泛化**——"学会了数据库"不合格，"学会了用 LEFT JOIN 处理一对多关系"合格
3. **不抄定义**——小白版必须是自己的话，不是教科书原文
4. **不空洞**——"AI很有用"不合格，"把大任务拆成子任务逐步提问，AI 的准确率更高"合格
5. **不遗漏实战**——每个知识点必须关联到本次任务的具体操作

## 小白类比素材库（示例）

| 技术概念 | 生活类比 |
|----------|----------|
| API 接口 | 餐厅服务员——你告诉他要什么菜（请求），他去厨房拿（处理），端给你（响应） |
| 数据库索引 | 书的目录——没有目录就要一页页翻，有目录直接跳到对应页 |
| 缓存 | 书桌上放常用文具——不用每次都去柜子里翻 |
| 消融实验 | 拆零件看哪个重要——把机器零件一个个拆掉，看缺了哪个就不转了 |
| Git 分支 | 平行宇宙——在不同宇宙尝试不同选择，最后挑最好的合并回来 |
| 正则表达式 | 快递分拣规则——"所有以A开头、尾号是8的包裹放这边" |
| Docker 容器 | 打包好的行李箱——不管去哪个酒店，打开就能用 |
| 递归 | 套娃——打开一个娃娃里面还有一个，直到打开最小的那个 |

> 以上仅为参考，实际类比必须贴合具体场景，不能生搬硬套。

---

## 自我迭代模式

### 触发条件

当用户在使用本技能后给出反馈（如"知识点太浅了""小白举例不够生动""题目太简单"），或主动说"优化这个skill"时，进入自我迭代模式。

### 迭代工作流

1. **收集反馈**：明确用户不满意的具体环节（哪个模式 / 哪个步骤 / 什么问题）
2. **诊断根因**：是规则缺失、规则冲突、粒度不够、还是场景未覆盖？
3. **提出修改方案**：列出拟修改的条目（原文 → 修改后），说明修改理由
4. **用户确认**：修改方案经用户确认后才执行
5. **写入 SKILL.md**：将修改直接应用到本技能文件
6. **记录迭代日志**：在 `references/iteration-log.md` 追加本次迭代记录

### 迭代约束

- 不破坏现有模式结构——增量修改，不推倒重写
- 每次迭代只改一个关注点——不趁机大改
- 修改后 SKILL.md 总行数仍 < 500
- 重大结构变更（如新增/删除模式）必须用户明确同意