Vibe Coding Learning

> "You can outsource your thinking, but not your understanding." — Andrej Karpathy
>
> 把 AI 生成的代码变回你真正理解的知识。详见 references/vibe-coding-origin.md。

Transform AI coding sessions into structured learning notes. Help CS students actually learn from vibe coding instead of just generating code.

Use this skill when

• User just completed a coding task with AI and wants a learning summary
• User says "summarize today's learning", "explain this code", "extract knowledge points"
• User says "help me review", "what did I learn before", "review yesterday's notes"
• User says "learning progress", "what should I learn next", "learning calendar"
• User says "prepare for interview", "面试怎么讲", "帮我准备面试", "模拟面试"
• User references "vibe coding learning", "learning note", "knowledge card"

Do NOT use this skill when

• User is still in the middle of coding and has NOT asked for a summary
  > 反例："帮我在这个函数里加个 try-catch"（用户还在写代码，不是在总结学习）
• User only wants code review, bug fixing, or refactoring without learning context
  > 反例："review 一下我的 PR"（纯代码审查，不涉及学习总结）
• User asks about non-programming topics
  > 反例："今天天气怎么样"（与编程学习无关）
• User only wants formatting / renaming without understanding intent
  > 反例："帮我把变量名改成驼峰命名"（纯格式化，无学习价值）
• The coding session is trivial (e.g., only changed a CSS color, single-line fix)
  > 反例：只改了一行颜色值，无需生成学习笔记

执行策略 (Execution Strategy)

Skill 启动后先判断执行模式，而非无差别全量执行。

双模式路由

根据用户意图和上下文充分度自动选择：

意图识别 → 模式映射

详细路由规则见 references/mode-routing.md（包括意图标签定义、模式选择矩阵、最小提问规则）。

快速参考：

最小提问规则

协作模式下有提问需求时，遵守以下纪律（详见 references/mode-routing.md）：

1. 容量上限：每次交互最多 3 个关键问题
2. 可推断不提问：能从上下文推断的信息，直接采纳
3. 给出默认值：需要选择时先给推荐方案
4. 用户说"直接做"→ 切 Auto
5. 默认方案兜底：用户回复模糊时按推荐方案执行

Input

Output

Workflow

Mode 1: Generate Learning Note (after coding session)

执行前 — 确定执行深度

读取 config.yaml 中的 learning.depth 字段，确定本次执行深度：

自动判断逻辑（当 depth 未设置或设为 auto 时）：
- 运行 python3 scripts/analyze-session.py --quick 分析本次会话复杂度
- 脚本输出 light / standard / deep 建议，按建议执行
- 脚本逻辑：代码变更 < 50 行 → light；50-200 行 → standard；> 200 行或跨多个文件 → deep

深度覆盖：用户可在对话中直接说"轻量模式"、"详细一点"来临时覆盖配置。

Phase 1/5: 采集与识别 [所有深度均执行]

> 进度输出（仅 standard/deep 模式）: "正在分析你的代码结构..."

Step 1 — Collect Context
- Scan the project directory to identify files created or modified during this session
- If user provided coding_context, use it as the primary description
- Read the key source files to understand what was built
- 文件覆盖度硬性规则：
- 必须 Read ALL changed files（变更集中 ≥ 80% 的文件都要读）
- 还必须 Read 被 changed files import/call 的关联文件（如 api.py import 了 state.py，则 state.py 也必须读）
- import 链追踪：至少追踪一层（A import B → 必须读 B）
- 覆盖度不达标时在自检清单中标注 [自检：文件覆盖度不足，仅读了 X/Y 个文件]

Step 2 — Identify Technical Domain and Stack
- Analyze the code to determine which domain(s) and tech stack(s) it belongs to:
- Domains: backend, frontend, devops, ai-ml, mobile, data-engineering, security, testing, cloud
- Stacks (examples): fastapi, django, express, react, vue, vanilla-js, docker, kubernetes, langchain, pytorch
- A session may span multiple domains and stacks

Phase 2/5: 提炼与解读 [light 仅输出知识点列表；standard/deep 输出完整解读]

> 进度输出（仅 standard/deep 模式）: "已识别技术领域，正在提炼知识点..."

Step 3 — Extract Knowledge Points [所有深度均执行]
- From the code changes, identify 3-8 concrete knowledge points
- For each knowledge point, define:
- Name (e.g., "JWT Authentication", "React useState Hook")
- One-sentence definition
- Core concept / how it works
- Which file and line range implements it
- Common mistakes / pitfalls
- Knowledge points should be things a CS student would encounter in coursework or interviews
- light 模式：到此为止，直接输出知识点列表 + 知识卡片，跳过 Step 4-8

Step 4 — Write Code Explanation [standard/deep 执行]
- Determine the recommended reading order (which file first, which function first)
- For each key file, write:
- What this file does in plain language
- Line-by-line or section-by-section explanation
- Why it's designed this way (not just what it does). Answer: "为什么这里用这种结构而不是另一种？如果有替代方案，是什么？"
- What design pattern it uses (if any). For each pattern found, also explain what the code would look like without it
- [deep 模式才输出] How to write it from scratch without AI: step-by-step reconstruction guide

Phase 3/5: 陷阱与资源 [仅 standard/deep 执行；资源搜索仅 deep]

> 进度输出（仅 deep 模式）: "知识点已提取，正在整理常见陷阱..."

Step 5 — Compile Pitfalls [standard/deep 执行]
- List 3-5 common mistakes for this domain
- Format: table with columns [Pitfall, Correct Approach, Common Mistake]
- Base this on both the code analysis and general domain knowledge

Step 6 — Recommend Learning Resources [仅 deep 执行]
- Attempt WebSearch first to find relevant tutorials for each knowledge point
- Search queries: "[knowledge point] tutorial bilibili", "[knowledge point] official documentation"
- Prioritize: Bilibili video tutorials, official docs, well-known tech blogs
- Provide 1-3 resources per knowledge point with title and URL
- If WebSearch is unavailable or fails: mark the section explicitly as （基于通用知识推荐，非实时搜索结果） and skip URL links — never fabricate search results

Phase 4/5: 更新与归档 [standard/deep 执行]

> 进度输出（仅 deep 模式）: "正在更新学习日历和目录结构..."

Step 7 — Update Learning Calendar and Progress [standard/deep 执行]
- Check if learning-notes/calendar/YYYY-MM.md exists. If not, create it.
- Append today's entry to the calendar:
| YYYY-MM-DD | [domain] | [keywords] | [link to note] |
- Check if learning-notes/progress.md exists. If not, create it.
- Update domain progress bars and statistics. Use four mastery levels: 🟢🟢 teachable / 🟢 mastered / 🟡 understood / 🔴 exposed
- After updating, the progress.md should show per-domain breakdown with mastery ratios

Step 8 — Save to Three-Layer Structure [standard/deep 执行]

Save outputs to the appropriate locations in the three-layer directory structure.

每个笔记文件必须包含 YAML frontmatter（M1 Step 2 已识别 domain/stack，保存时自动设 status: processed）：

---
title: "[笔记标题]"
date: YYYY-MM-DD
domain: [backend/frontend/...]
stack: [fastapi/react/...]
status: processed          # 自动设置，无需用户确认
last_review_date: null
review_count: 0
mastery_level: "🔴 exposed"   # 初次创建默认 exposed；四级体系：🔴 exposed / 🟡 understood / 🟢 mastered / 🟢🟢 teachable
tags: [tag1, tag2]
---

1. topics/ — Save the daily learning note
   - Create a project-specific folder: topics/[project-name]/
   - Save note as: topics/[project-name]/YYYY-MM-DD-[title].md
   - Example: topics/fastapi-login-register/2026-06-11-fastapi-login-register.md
   - 必须包含上方 frontmatter

2. domains/ — Update the domain and stack indexes (MANDATORY — do NOT skip)
   - Determine the domain (e.g., backend) and stack (e.g., fastapi)
   - Create or update domains/[domain]/_index.md with knowledge checklist
   - Create or update domains/[domain]/[stack]/_index.md with stack-specific notes
   - Link back to the topic note from the domain index
   - After writing, verify: check that the domain index file exists and contains today's knowledge points

3. cards/ — Save extracted knowledge point cards
   - Determine the card category (e.g., auth, css, js, python)
   - Create the category folder if it doesn't exist: cards/[category]/
   - Save each card as: cards/[category]/[kebab-case-name].md
   - Example: cards/auth/jwt.md, cards/css/flexbox.md
   - Cards should be self-contained and reusable across any project
   - Cards should also include frontmatter with status: processed

Phase 5/5: 最终产出

> 进度输出: "正在生成学习笔记，马上就好..."

Step 9 — Generate Output Files
- Generate the daily learning note following the template at templates/daily-learning-note.md
- Save to the appropriate topic folder
- If preferred_format is html, generate an HTML version using the html-report skill

Step 10 — 费曼自评 [仅 standard/deep 模式，当 config.yaml 的 feynman_enabled: true 时]

> 形成"提取 → 整理 → 自评 → 调整"闭环。详见 references/feynman-assessment.md。

1. 列出刚才提取的所有知识点，问用户："哪个知识点你最不熟悉？"
2. 根据回答调整 mastery_level：
   - 用户说"第 X 个最陌生" → 降级为 🔴 exposed
   - 用户说"第 X 个我能给别人讲" → 升级为 🟢🟢 teachable
   - 用户说"全部熟悉" → 保持原 mastery_level，跳过
3. 根据自评结果给出后续分流建议（如"建议对 🔴 知识点做 Mode 2 互动复习"）

deep 模式两步流 [仅 deep 模式执行]

• Step 10A — 先生成简版 session log（当日学习日志）：
  ```markdown
  ## Session Log — YYYY-MM-DD
• 会话时长：~X 分钟
• 变更文件：[文件列表]
• 关键操作：[操作摘要]
• 初步感知：[用户直觉理解]
  ```
• Step 10B — 再提炼为完整主题笔记（即 Step 9 的输出）
  > light/standard 直接一步到位，不生成 session log

Mode 2: Review Previous Learning (on user request)

When user asks to review or recall previous learning:

1. Read learning-notes/progress.md to get the full learning overview
2. If user specifies a date/topic: read the corresponding note file from topics/
3. If user says "yesterday" or "recent": find the most recent calendar entry
4. Present a quiz-style review:
   - First, list the knowledge points WITHOUT code (test recall)
   - Ask the user to explain the core logic in their own words
   - Then reveal the code explanation for comparison
   - Mark knowledge points the user struggled with as 🔴 exposed in the mastery tracker (降级规则：🟢🟢 → 🟢 → 🟡 → 🔴，根据复习表现逐级降级), so Mode 3 reflects the true mastery level

Mode 3: Learning Progress Check (on user request)

When user asks about overall progress:

1. Read learning-notes/progress.md
2. Scan learning-notes/domains/ for domain-level status
3. Present:
   - Total learning days, domains covered, knowledge points count
   - Per-domain progress with four mastery levels:
   • 🟢🟢 可教学：能给别人讲清楚，举出类比和例子 → 对应 teachable
   • 🟢 已掌握：能不看代码讲清楚原理 → 对应 domain index 中标记为 mastered 的知识点
   • 🟡 理解了：知道怎么用但还不能脱离代码 → 对应 understood
   • 🔴 接触过：见过但还不会用 → 对应 exposed
   • Mastery ratio calculation: 可教学+已掌握 / (全部四级) × 100%
   • Recent learning calendar (last 7 days)
   • Suggested next topics based on gaps: prioritize 🔴 items with highest interview relevance

Mode 4: Interview Preparation (on user request)

IMPORTANT: Only trigger this mode when user explicitly mentions interview/job preparation. Do NOT include interview content in daily learning notes by default.

When user asks for interview preparation:

1. Gather context — Read learning-notes/progress.md and learning-notes/domains/ to understand what the user has learned
2. Identify relevant knowledge — Scan knowledge point cards in learning-notes/cards/ and recent topic notes for content that matches the user's target role
3. Generate interview output:
   - 30-second summary for each major project/domain: concise enough for a quick self-introduction
   - 90-second deep-dive for key technical choices: explain WHY you chose certain technologies
   - Common interview questions for the learned tech stack with suggested answers based on actual experience
   - Weakness analysis: identify gaps between what was learned and common interview expectations for the target role
4. If user says "模拟面试" (mock interview):
   - Randomly pick 3-5 knowledge points from their cards
   - Ask each as an interview question, wait for the user's response
   - Provide feedback: what was good, what was missing, how to improve

Interview question generation rules:
- Draw questions from the user's actual learned content, not generic lists
- For backend roles: focus on auth flows, database design, API design, error handling
- For frontend roles: focus on component design, state management, performance, responsive design
- For full-stack roles: ask about integration decisions, data flow, debugging approaches
- Always reference the user's specific project experience when formulating questions

Target role mapping (use when user specifies a target role):

Mode 5: 对话分析与提示词优化（新增 · v1.1.0）

IMPORTANT: 当用户说"分析一下我的对话记录"、"我的提示词写得怎么样"、"怎么问才能得到更好的回答"、"prompt 优化"时触发。可独立触发，也可在 Mode 1-4 执行后作为延伸功能触发。

执行步骤

Step 1 — 读取对话历史
- 从 learning-notes/ 或网页端导入的对话数据中读取最近 N 次对话（默认 N=10，用户可指定）
- 提取：用户的提示词模式、AI 的回答质量、反复追问的知识点

Step 2 — 分析提示词模式
- 分类统计以下维度（每项 1-10 分）：
- 具体程度：是否明确了技术栈、约束条件、预期输出格式
- 上下文完整性：是否提供了足够的背景信息
- 任务分解能力：复杂任务是否拆分成多步
- 迭代次数：平均几次交互达到目标
- 识别低效模式：
- 过于模糊（"帮我写个登录"→ 缺少技术栈和约束）
- 一次性抛多个问题（AI 难以逐一回答）
- 缺少输出格式指定（导致需要多轮澄清）

Step 3 — 生成优化建议
- 针对具体对话给出"改前 vs 改后"对比
- 引用公开 Prompt Engineering 资料作为依据：
- Anthropic Prompt Library: https://docs.anthropic.com/en/prompt-library
- OpenAI Prompt Engineering Guide: https://platform.openai.com/docs/guides/prompt-engineering
- Google Prompt Engineering Guide: https://ai.google.dev/docs/prompt_engineering
- 给出 1-3 条可操作的改进建议

Step 4 — 输出学习洞察（可选，用户主动询问时触发）
- 识别用户反复追问的知识点（= 未完全掌握）
- 推导技术栈掌握程度矩阵（基于对话内容，不依赖手动记录）
- 建议下一步学习重点（优先补强弱项）

输出格式

## 提示词优化分析报告

### 📊 你的提示词风格
| 维度 | 评分 | 说明 |
|------|------|------|
| 具体程度 | X/10 | ... |
| 上下文完整性 | X/10 | ... |
| 任务分解 | X/10 | ... |

### 💡 针对本次对话的优化建议

**原提示词**：
> "..."

**优化后**：
> "..."

**为什么更好**：
- ...

### 📚 参考资料
- [Anthropic Prompt Library](https://...)
- [OpenAI Prompt Engineering Guide](https://...)

与网页端（Web Hub）的集成

当 Skill 在网页端环境中运行时，Mode 5 的输出可额外包含：
- 可点击的"应用此优化"按钮（自动生成优化后的提示词供复制）
- 提示词历史对比视图
- 与 Obsidian 笔记联动（将优化建议保存为 cards/prompt-optimization/ 下的可复用卡片）

Mode 6: inbox-triage — 知识生命周期管理（新增 · v1.1.0）

IMPORTANT: 当用户说"有什么没整理的笔记吗"、"整理一下 inbox"、"批处理今天的会话"时触发。

执行步骤

Step 1 — 扫描待处理笔记
- 扫描 learning-notes/ 目录，找出：
- 文件名含 temp_ 或 session_ 的未整理笔记
- 最近 3 天内创建但未移动的笔记
- inbox/ 子目录下的所有笔记

Step 2 — 批处理分类
- 列出所有待处理笔记，建议归档路径
- 等待用户确认或修改分类

Step 3 — 关联检测
- 对刚分类的笔记，搜索同领域其他笔记
- 建议关联（详见 references/connection-review.md）

Step 4 — 晋升检查
- 检测已复习多次的笔记，提示标记为「已掌握」

输出格式

详见 references/inbox-triage.md。

Mode 7: connection-review — 知识关联（新增 · v1.1.0）

IMPORTANT: 当用户说"今天学的和之前有什么关联"、"帮我建立知识关联"时触发。也可在 Mode 1 写入新笔记后自动触发。

执行步骤

Step 1 — 关键词重叠检测
- 提取新笔记的 tags 和标题关键词
- 与已有笔记匹配，找出重叠度 ≥ 2 的主题

Step 2 — 时间邻近检测
- 同一天或连续几天内学习的主题，建议关联

Step 3 — 生成关联建议
- 强关联：建议立即建立双向链接
- 弱关联：可选建立链接
- 对比关联：建议生成对比笔记

Step 4 — 写入双向链接
- 经用户确认后，在笔记中插入 [[双向链接]]

输出格式

详见 references/connection-review.md。

Mode 8: weekly-synthesis — 深度周总结（新增 · v1.1.0）

IMPORTANT: 当用户说"周总结"、"生成本周学习报告"、"这周学了什么"时触发。替代 Mode 3 的浅层统计，生成深度报告。

执行步骤

Step 1 — 收集本周数据
- 读取 learning-notes/calendar/YYYY-MM.md
- 统计学习天数、笔记数、主要领域

Step 2 — 构建知识图谱
- 分析本周笔记的关联关系
- 生成 Mermaid 知识图谱（如配置了图表输出）

Step 3 — 掌握度评估
- 基于复习次数和笔记质量，评估每个主题的掌握度
- 输出掌握度雷达图数据（供网页端可视化）

Step 4 — 知识盲区检测
- 基于本周学习的主题，反向查找缺失的前置知识
- 给出补强建议

Step 5 — 下周学习计划
- 基于掌握度和盲区，生成下周学习重点
- 包含复习计划和实践项目建议

输出格式

详见 references/weekly-synthesis.md。

Mode 9: health-check — 知识健康诊断（新增 · v1.1.0）

IMPORTANT: 当用户说"检查学习健康度"、"我有没有忘记复习的"、"知识诊断"时触发。也可配置为每周自动运行。

执行步骤

Step 1 — 遗忘检测
- 扫描笔记的 last_review_date
- 超过 config.yaml 中设置的天数（默认 30 天）未复习的主题 → 提醒

Step 2 — 关联建议
- 检测同一时间窗口内学习但未建立关联的主题 → 建议链接

Step 3 — 学习盲区检测
- 基于本周学习的主题，反向查找缺失的前置知识

Step 4 — 学习疲劳检测
- 同一领域连续学习超过 7 天 → 建议切换

Step 5 — 笔记质量检查
- 检测内容过短或格式不规范的笔记 → 提示补充

输出格式

详见 references/health-check.md。

配置项

在 config.yaml 中：

health:
  auto_run: true
  auto_run_day: monday
  notification_method: chat

Writing Rules

• Write in plain Chinese. Explain technical terms the first time they appear.
• Target audience: CS undergraduate students who use AI coding tools
• Always include concrete file paths and line references from the actual project
• Include reading guidance: "read this function first, then see where it's called"
• Be honest about uncertainty — if something is ambiguous, say so
• Keep each daily note focused on ONE session, not a general overview
• 卡片层次规则：知识卡片分"主卡片"和"引用卡片"两个层次：
• 主卡片：首次完整解释某个概念的卡片，包含完整的"是什么 / 核心原理 / 怎么用"
• 引用卡片：后续卡片遇到同一概念时，用 > 详见 [[cards/category/primary-card-name]] 引用，不再重述
• 自检规则：如果两张卡片有 > 3 行内容重复，说明需要改为引用关系
• 行号引用规则：所有代码行号引用（如 state.py:15）必须在写入前通过 Read 工具实时验证，确保行号准确。不要靠记忆猜测行号——用户点击 IDE 跳转如果对不上，会很失望
• Knowledge point cards should be self-contained and reusable across sessions

Note Template

Follow the template structure defined in templates/daily-learning-note.md.

Directory Structure for Learning Notes

The learning notes use a three-layer architecture for scalability:

learning-notes/
├── README.md                    # Overview dashboard & usage guide
├── progress.md                  # Progress tracking across all domains
├── calendar/
│   └── YYYY-MM.md              # Monthly learning calendar
│
├── topics/                      # Layer 1: Project/session-based notes
│   └── [project-name]/          # One folder per coding project/session
│       └── YYYY-MM-DD-[title].md
│
├── domains/                     # Layer 2: Domain & stack indexes
│   └── [domain]/                # e.g., backend, frontend, devops, ai-ml
│       ├── _index.md            # Domain-level knowledge checklist
│       └── [stack]/             # e.g., fastapi, react, docker
│           └── _index.md        # Stack-specific notes & progress
│
└── cards/                       # Layer 3: Reusable knowledge cards
    └── [category]/              # e.g., auth, css, js, python, database
        └── [card-name].md       # Self-contained, cross-topic reusable

Three-Layer Design Rationale

This structure ensures:
- Scalability: Adding a new tech stack only requires creating a new domains/[domain]/[stack]/ folder
- Reusability: Knowledge cards in cards/ can be referenced by any future project
- Discoverability: Domain indexes provide a curated view of what you've learned per tech area
- No flat-folder bloat: Cards are categorized so no single folder grows too large

Card Category Guidelines

When saving knowledge point cards, use these standard categories (create new ones as needed):

输出后续分流

每次产出后，根据内容类型建议一步行动（详见 references/output-routing.md）。

快速参考：

> 注意：分流建议只输出一次，用户忽略则不重复。不支持的分流路径直接跳过。

On Failure

• If no code files can be found: ask the user to specify which files were created/modified
• If WebSearch returns no results: skip tutorial recommendations, use general knowledge instead
• If output directory is not writable: inform the user and suggest an alternative path
• If the session is too trivial (e.g., only changed a CSS color): suggest skipping note generation

输出自检清单

> 每次 Mode 执行完毕后，AI 应自行检查以下项目。如有未达标项，在输出末尾标注 [自检：X/Y 通过] 并说明未通过项。

Mode 1 输出自检

• [ ] 是否提取了 3-8 个知识点（不多不少）
• [ ] 每个知识点是否有"为什么这样设计"的解释
• [ ] 是否有"如何从头写"的逐步重构指南
• [ ] 代码讲解是否按推荐阅读顺序组织
• [ ] 是否更新了 learning-notes/progress.md（如已存在）
• [ ] 是否保存了知识卡片到 cards/（如用户确认）
• [ ] 教程推荐是否优先 Bilibili 和官方文档（如启用了 WebSearch）
• [ ] 文件覆盖度：是否读了 ≥ 80% 变更集中的文件 + 一层 import 链
• [ ] 行号验证：代码行号引用（如 state.py:15）是否通过 Read 工具实时验证，而非靠记忆猜测
• [ ] 费曼自评（standard/deep）：是否在 Step 10 询问了用户对知识点的不熟悉程度

Mode 2 输出自检

• [ ] 是否先让用户回忆，再揭晓答案（非直接给答案）
• [ ] 是否标记了用户卡壳的知识点（mastery 降级）
• [ ] 是否给出了具体的复习建议（非泛泛而谈）

Mode 3 输出自检

• [ ] 是否展示了四个掌握度层级（🟢🟢🟢🟡🔴）
• [ ] 是否计算了 mastery ratio（可教学+已掌握 / 全部四级）
• [ ] 是否给出了针对弱项的下一步建议

Mode 4 输出自检

• [ ] 面试话术是否基于用户的真实项目（非通用模板）
• [ ] 模拟面试问题是否从用户的 cards/ 中抽取（非网上抄的题）
• [ ] 是否标注了回答中的知识盲区

Mode 5 输出自检（新增）

• [ ] 提示词评分是否有具体维度（非只给总分）
• [ ] 优化建议是否有"改前 vs 改后"对比
• [ ] 参考资料链接是否真实可访问（非捏造）

Mode 6 输出自检（新增）

• [ ] 是否扫描了所有待处理笔记（inbox/、temp_、session_）
• [ ] 是否给出了明确的归档建议（含目标路径）
• [ ] 是否检测了新笔记与已有笔记的关联

Mode 7 输出自检（新增）

• [ ] 是否基于关键词重叠和时间邻近双重检测
• [ ] 关联建议是否区分了强/弱/对比三种类型
• [ ] 是否经用户确认后再写入双向链接

Mode 8 输出自检（新增）

• [ ] 是否包含知识图谱（Mermaid 或文字描述）
• [ ] 是否评估了每个主题的掌握度
• [ ] 是否检测了知识盲区（缺失的前置知识）
• [ ] 是否给出了下周学习计划（含复习和实践）

Mode 9 输出自检（新增）

• [ ] 是否检测了遗忘风险（超过 N 天未复习）
• [ ] 是否检测了未建立关联的笔记对
• [ ] 是否检测了学习盲区
• [ ] 是否给出了健康评分和优先处理建议

Troubleshooting

问题 1：Skill 触发了但输出质量差

可能原因：
- coding_context 未提供，AI 没有足够上下文
- 项目目录结构复杂，AI 无法正确识别变更文件

修复：

用户：帮我总结今天学的
AI：我看到你修改了多个文件，能告诉我你主要做了什么功能吗？

问题 2：知识卡片重复生成

可能原因：同一知识点在多个 session 中被重复提取。

修复：写入 cards/ 前，先搜索是否已存在同类卡片（按标题关键词匹配）。

问题 3：progress.md 数据不准确

可能原因：手动编辑 progress.md 时格式出错，或 Skill 写入时覆盖了他内容。

修复：运行 python3 scripts/validate-structure.py 检查目录结构一致性。

问题 4：WebSearch 失败导致无教程推荐

现象：输出中教程推荐部分为空或只有文字说明。

修复：Skill 已在 Step 6 中内置了 fallback（标注"基于通用知识推荐，非实时搜索结果"），不会捏造链接。如 WebSearch 持续失败，检查网络或使用 find-skills 安装替代搜索 Skill。

问题 5：Mode 5 提示词分析不准确

可能原因：对话历史读取不完整（只读了最近几条）。

修复：在触发 Mode 5 时明确指定范围，如"分析我最近 10 次与 AI 的对话"。

问题 6：Mode 6 inbox-triage 检测不到未整理笔记

可能原因：笔记已手动移动，或文件名不符合检测规则。

修复：检查 learning-notes/ 目录下是否还有 temp_ 或 session_ 前缀的文件；如无，说明已整理完毕。

问题 7：Mode 7 connection-review 关联建议不准确

可能原因：关键词提取不完整，或时间窗口设置过宽/过窄。

修复：手动指定关联检测范围，如"帮我检查 fastapi-login.md 与 jwt-auth.md 的关联"。

问题 8：Mode 8 weekly-synthesis 报告过于简单

可能原因：本周学习笔记过少，或笔记内容质量低（仅代码片段，无知识点提炼）。

修复：确保 Mode 1 执行时完整提取知识点；如笔记质量低，先重新执行 Mode 1。

问题 9：Mode 9 health-check 遗忘提醒不准确

可能原因：last_review_date 未正确更新，或 config.yaml 中 review_reminder_days 设置不合理。

修复：手动更新笔记的 last_review_date 字段；或在 config.yaml 中调整提醒天数。