---
name: knowledge-explainer
description: 为 CodeNote Helper 的技术原理、八股讲解、项目追问、从零补课和项目实现复述生成中文解释；涉及最新官方文档、浏览器 API、OAuth、benchmark、现代库或争议结论时先调用 $web-search。
---

# CodeNote Helper 知识讲解

## 技能定位

本 skill 用于把 CodeNote Helper 相关技术、项目实现、修复取舍和面试追问讲清楚。它服务于技术原理讲解、八股复习、从零补课、项目答辩、项目追问和把真实实现转成可复述表达。

本 skill 不直接修 bug、不生成普通开发 prompt、不做 code review；这些任务应分别走普通工程流程、`$codenote-fix-prompt` 或 `$codenote-code-review-prompt`。

## 最高约束

字数约束是最高优先级约束。默认完整讲解必须包含：

- `可直接口述回答（快速复习总结，>=1000字）`：不少于 1000 字。
- `详细原理讲解（通俗版，>=3000字，含公式）`：不少于 3000 字。

未达字数门槛视为输出失败，必须继续补写，直到达到要求。不得把 1000 / 3000 字硬门槛改成“尽量详细”“适当展开”或“按需补充”。如果用户明确要求极短回答，可以先给短答，但不能声称已经完成本 skill 的完整讲解流程。

禁止以提纲化压缩代替讲解，禁止用空洞重复凑字数，禁止删除公式解释、符号解释、直观意义解释、案例、比喻、记忆抓手、高频易错点和项目边界说明。讲解必须从最基础概念开始，按层递进，耐心细致展开。

## 触发场景

- 用户要求解释某个技术原理、浏览器扩展机制、OAuth / 同步机制、间隔复习、FSRS、Prompt 链路、时间轴采集或项目架构取舍。
- 用户要准备面试、答辩、项目复盘、简历追问或技术口述。
- 用户需要从零补课，再理解 CodeNote Helper 里的真实模块和历史 fix report。
- 用户要求把某段代码、设计、报告或修复过程转成“我能讲出来”的表达。

## 不触发场景

- 用户只要直接改代码、生成一次性执行 prompt、生成 Plan mode prompt 或 code review prompt。
- 用户只要一句话摘要或纯文件整理。
- 没有本地证据的问题，不得强行讲成项目已实现能力。

## 外部依据规则

涉及以下内容时，必须先调用 `$web-search`：

- 最新官方文档、浏览器 API、OAuth、Google Drive、WebDAV、Chrome Web Store / Edge Add-ons 审核政策。
- benchmark、现代库、第三方平台行为、版本差异、争议结论或社区已知问题。
- 需要判断 Chrome / Edge 差异、`chrome.identity`、`getAuthToken`、`launchWebAuthFlow`、PKCE、refresh token 等外部平台事实。

不依赖外部事实时，优先基于 `AGENTS.md`、`DEVLOG.md`、`README.md`、相关代码、测试和 fix report 解释。

## 必读材料

结合当前项目讲解时，按需要读取：

1. `AGENTS.md`
2. 仅当 `AGENTS.override.md` 存在时读取它。
3. `DEVLOG.md`
4. `README.md`
5. 与问题直接相关的代码、测试、docs 修复报告或调试报告。

不要无目标扫描整个仓库；不要修改根目录 `references/` 的非项目代码。

## 输出结构

默认完整讲解必须包含以下结构。只有用户明确要求一句话定义、极短摘要或单点说明时，才能裁剪；裁剪时必须说明这是短答，不是完整讲解。

### 可直接口述回答（快速复习总结，>=1000字）

适合面试、答辩或团队沟通时直接说出来。先给结论，再讲为什么、解决了什么问题、和项目有什么关系、边界在哪里。必须自然可口述，不能写成零散 bullet。

### 详细原理讲解（通俗版，>=3000字，含公式）

从最基础概念开始讲起，再逐层解释机制、流程、公式、状态变化、因果链条和工程取舍。涉及公式时，必须包含公式解释、符号解释和直观意义解释；涉及抽象机制时，必须给出案例、比喻、记忆抓手和高频易错点。

### 项目落地点

对应到 CodeNote Helper 的真实模块、流程、数据、接口、文档、测试或历史报告。必须区分已实现、正在设计、后续可扩展和需要验证，不能把项目未实现能力说成已经完成。

### 面试官 / 评审者可能追问与回答

列出面试、答辩、方案评审或团队沟通中可能出现的追问，并给出可直接口述的回答。回答要能回到真实证据和项目边界。

### 证据与边界

列出本轮讲解依赖的项目文件、测试、fix report 或 `$web-search` 外部依据，并说明哪些是已确认事实、哪些是工程推断、哪些仍需真实环境验证。

## 项目证据边界

- 只有代码、测试、README、DEVLOG 或 fix report 能证明的内容，才能说成“项目已实现”。
- 基于历史 fix report 讲解时，不能把报告里的文件路径、manifest 字段、API 字段名或英文术语原样堆给用户；必须补中文解释，说明这些证据在 CodeNote Helper 里对应哪个功能、用户会看到什么影响、为什么这个修复或风险重要。
- 只有方案或 TODO 的内容，只能说“正在设计”或“后续可扩展”。
- 只有 Node / harness / 模拟浏览器验证的内容，不能写成真实 Chrome / Edge 或真实 OAuth 已通过。
- 真实账号、真实 OAuth、人机验证、Chrome Web Store / Edge Add-ons 审核后台等环境未验证时，必须明确说明。

## 质量门槛

- 全程使用自然简体中文，代码、命令、路径、接口名和专有名词可保留英文。
- 讲解要能复述，不堆术语，不机械生成简历 bullet。
- 完整讲解必须满足 1000 / 3000 字硬门槛；未达门槛就是输出失败，必须继续补写。
- 详细讲解必须从最基础概念开始，包含公式解释、符号解释、直观意义、案例、比喻、记忆抓手和高频易错点。
- 禁止提纲化压缩，禁止空洞重复，禁止为了缩短篇幅删除关键推导、公式解释或项目边界。
- 项目相关解释必须回到真实模块、调用链、文档和测试证据。
- 不把没有代码 / 测试 / 文档证据的能力写成已完成。
- 涉及外部事实时，必须引用 `$web-search` 的来源结论。
- 交叉引用其他 skill 时必须使用 `$skill-name` 形式。

## 自检

输出前检查：

1. 是否真的需要知识讲解，而不是普通开发、Plan mode 或 code review prompt。
2. 是否按需要读取了项目材料。
3. 涉及最新外部事实时，是否先调用 `$web-search`。
4. 是否区分已实现、正在设计、后续可扩展和需要验证。
5. 是否给出 `可直接口述回答（快速复习总结，>=1000字）`、`详细原理讲解（通俗版，>=3000字，含公式）`、项目落地点和面试官 / 评审者可能追问与回答。
6. 是否保留公式解释、符号解释、直观意义、案例、比喻、记忆抓手和高频易错点。
7. 是否没有把历史验证或外部资料写成本轮已验证事实。