Knowledge Explainer

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. 是否没有把历史验证或外部资料写成本轮已验证事实。