project-guide

/project-guide：项目导学 + 项目面经

基于用户提供的项目仓库、项目描述、技术栈和求职方向，把真实项目整理成源码课程，或导学与面经材料。本技能关注“项目如何学、如何讲、如何被追问”，不替用户编造公司、职位、数据、上线结果或个人职责。

路由边界

• 需要从项目仓库或项目材料生成源码课程、配套理解题、学习路径、项目亮点或项目面经成稿：使用 /project-guide。
• 只需要把经历改成简历 bullet、岗位定位或 HR 开场白：使用 /great-resume。
• 已经有简历，需要模拟面试、预测问题或逐轮追问掌握度：使用 /interview。
• 需要生成可编辑 HTML/PDF 简历：使用 /make-resume；未指定模板时默认使用 ASu 模板，也可以在请求中指定其他模板。
• 需要寻找开源贡献候选、准备 diff 或提交 PR：使用 /contributor。

输入契约

优先从当前工作区读取项目事实，再结合用户材料。先按用户请求选择“源码课程”或“导学面经”模式；未指定时使用导学面经模式。缺少关键信息时最多追问 3 个高信号问题；用户要求先出初稿时，允许用 待补 标注缺口。

字段	必须	说明
项目源码	源码课程必需	本地仓库或当前工作区；只有项目描述时不能生成已核验的函数调用路线
项目描述	导学面经必需	背景、目标、职责、难点、结果；越具体越好
操作	源码课程必需	课程大纲、展开指定课程、配套练习，或用户明确要求的组合操作
课程编号	展开或练习时必需	必须能在现有课程文件中定位
简称	导学面经强烈建议	用于文件名 导学-{简称}.md、面经-{简称}.md
技术栈	否	语言、框架、中间件、观测、发布方式
求职方向	否	前端、后端、AI、数据、产品或交叉方向

导学面经材料不足时，优先追问：

1. 你在项目中的个人职责和协作边界是什么？
2. 项目最能展开的技术难点是什么，解决前后的现象如何验证？
3. 是否有指标、日志、PR、截图、上线记录或用户反馈可以作为证据？

可选脚本：

python3 scripts/project_guide.py check --file description.txt --tech "React, TypeScript" --role "前端"
python3 scripts/project_guide.py build-prompt --short-name "智能BI" --description "..." --tech "..." --role "..."

源码课程模式

用户要求把仓库分课学习、展开指定课程或生成课程练习时进入该模式。未指定具体操作时，先生成课程大纲，不自动展开全部课程或创建练习。

本模式维护课程文件（文件名由 tutorial 和 .md 拼接）与练习文件（文件名由 practice 和 .md 拼接）。

课程大纲

1. 读取课程大纲规范；
2. 检查项目入口、主要功能、模块边界和代表性运行流程；
3. 在课程文件中生成课程大纲，每课给出真实文件与符号的阅读顺序；
4. 记录源码版本、实际覆盖范围和尚未覆盖的模块。

展开指定课程

1. 读取现有课程文件与单课讲解规范；
2. 确认课程编号、主题、前后边界和源码范围；
3. 沿真实调用或事件顺序展开该课，并以完整流程串联收尾；
4. 只更新指定课程，保留其他课程和用户笔记。

配套理解题

1. 读取课程文件中的对应课程与配套练习规范；
2. 在练习文件中更新相同编号和标题的课程练习；
3. 默认只生成问题和必要的回答要求，不附标准答案；
4. 只考查课程已经讲过的内容，保留其他课程的练习与用户答案。

用户明确要求组合操作或同步时，按“大纲 → 展开 → 练习”的依赖顺序执行请求包含的操作，并只创建本次需要的文件。

源码事实与局部更新

• 每课围绕一个能从触发走到结果的项目场景组织，先给紧凑主链，再给编号阅读步骤。
• 文件、函数、方法、事件和配置位置必须能在当前源码中定位。文档与实现冲突时，以实现为准并指出差异。
• 直接调用与异步事件分别说明。队列、回调和依赖注入要追到注册、绑定或消费证据；无法确认的运行时目标标为 待确认，停在已证实的接口边界。
• 只讲源码已经实现的异常、恢复和清理路径。设计动机没有证据时标为分析，性能收益没有测量时不下结论。
• 编辑前读取完整目标文件，只替换用户请求的章节。重排、合并或删除课程时检查受影响的编号、标题与练习引用。
• 如果课程文件或练习文件已用于其他用途，保留原文件并说明冲突，改用不会覆盖原文的文件名。

简历 bullet 约束

生成 面经-{简称}.md 前，先对照 领域中立 Bullet few-shot。few-shot 只用于学习表达结构，不得复制其中的项目名、数字、领域名词或指标。

简历 bullet 必须先抽取 4-6 个架构支柱，再成稿。每条一级 bullet 必须以 **通用支柱名：** 开头，随后写清：

• 问题或演进：为什么原形态不够好。
• 机制：采用了什么通用工程机制，以及它如何工作。
• 约束或边界：超时、并发、幂等、降级、观测、扩展点等。
• 结果：可验证的架构变化或真实指标；没有证据时写测量计划，不编造数字。

支柱名必须是外部面试官能理解的架构或工程能力，例如分层容错、可扩展编排、请求可靠性治理。项目实现名不能直接充当支柱名；RunManager、Stream Bridge、execution id 这类实现名应改写为通用表达，或下沉到源码证据索引。

删除“提升性能 / 提高稳定性 / 优化体验”等不可验证结果；私有函数、路径、内部枚举和业务黑话只进入源码证据索引。

硬性交付

在用户指定的目标项目根目录或当前工作区，按所选模式写入对应文件：

模式	文件	内容
源码课程	课程文件	课程大纲与已经展开的课程内容
源码课程练习	练习文件	与课程编号和标题对应的理解题
导学面经	导学-{简称}.md	项目学习路径、源码阅读顺序、核心原理、设计决策和验证建议
导学面经	面经-{简称}.md	简历可用摘要、面试题、第一人称 STAR 口播、追问和源码证据索引

用户明确要求组合两种模式时才同时生成两组文件。{简称} 使用用户给定值；未给时从项目名称或描述中提炼 2-8 个字。不得包含 / \ : * ? " < > | 等路径非法字符。

如果当前环境无法写入文件，在对话中输出独立 Markdown 代码块，并标明目标文件名。

导学文件结构

导学-{简称}.md 按以下顺序输出：

1. 前置知识（面试高频标注）
   • 表格列：知识点 / 为何需要 / 在本项目中的位置 / 高频度。
2. 重点亮点与学习顺序（先看这个）
   • 3-6 条。
   • 表格列：亮点标题 / 为什么重要 / 通用技术关键词 / 先看哪些文件 / 建议学习顺序。
   • 亮点标题优先使用通用工程表达，例如状态建模、异步编排、缓存一致性、性能治理、容错降级、观测与定位。
3. 必备知识点
   • 精简 checklist。
4. 推荐阅读（结合仓库）
   • 表格列：主题 / 通用技术点 / 建议阅读位置 / 预计时间 / 读完能回答什么。
   • 每条建议阅读位置必须写项目相对路径；未知时写 仓库未提供路径，待补。
5. 自学提醒
   • 固定包含：若某文件或原理看不懂，请继续追问 AI；本技能负责给学习路径与题目，不提供逐行讲解。
6. 项目技术定位
   • 前端 / 后端 / AI / 数据 / 产品 / 交叉 + 一句依据。
7. 核心原理解析
   • 3-6 条，使用“问题 -> 机制 -> 在本项目中的落点”。
8. 关键设计决策
   • 备选 / 取舍 / 风险 / 验证。
9. 量化与验证（含待测，建议）
   • 用建议语气说明怎么测；暂无数据时写 待测。

面经文件结构

面经-{简称}.md 按以下顺序输出：

1. 项目简介（简历可用，1-2 句）
   • 说清“做什么 + 关键技术/形态 + 关键能力”。
   • 不堆叠内部私名。
2. 简历 bullet（4-6 条）
   • 每条一级 bullet 必须以 **通用支柱名：** 开头。
   • 先交代问题或演进与个人职责，再写机制、约束或边界、结果。
   • 每条只表达一个支柱，至少包含“问题或演进 + 机制 + 结果”。
   • 没有可靠数据时写定性架构结果或测量计划，不编造百分比、用户量、延迟或排名。
3. 面试问题（15-25 个主问题）
   • 主问题按频率从高到低组织。
   • 可按 3-6 个主题分组，每个主题至少 1 个主问和 2 个追问。
   • 15-25 只统计主问题，追问不计入。
   • 每个主问和追问都必须包含第一人称口播版，且不少于 150 个汉字。
   • 口播应覆盖 STAR：情境、任务、行动、结果。
   • 叙述顺序建议为：场景现象 -> 归因 -> 动作 -> 结果或兜底。
4. 源码证据索引
   • 表格列：主题 / 关键路径与内部符号 / 对应正文位置。
   • 具体文件名、函数名、私有字段、打点名和内部容器名集中放在这里。

内部名词约束

面经读者默认是外部面试官。正文应以通用工程语言为主，不把团队黑话直接堆给面试官。

以下内容在面经正文中要主动抽象：

• 私有框架、私有组件、自研 hook、内部 API。
• 项目内部函数名和工具函数名。
• 后端下划线字段、私有枚举、内部状态码。
• 打点事件名、动态配置键、灰度开关键。
• 端内容器私名、私有 JSBridge namespace。
• 3-5 字中文业务代号或团队内部俗称。

翻译方式：

• 私有 hook/action -> store 的 read hook / write action。
• 分层函数 -> 一级路由决策 / 二级视图状态机。
• 后端字段 -> 语义化业务含义。
• 打点事件 -> 某类生命周期或结果指标打点。
• 灰度开关 -> 配置中心下发的 feature toggle。
• 业务代号 -> 某活动、某子产品、某业务流程。

预算：

• 主问口播中黑名单内部名词最多 2 次，且每次必须紧跟通用抽象说明。
• 追问口播中黑名单内部名词最多 1 次。
• 违反预算时重写该题。

与 ASu 工作流交接

完成导学面经交付后，在最终回复中附两段交接摘要：

交给 /great-resume 的项目事实摘要

包括：

• 项目名称和目标岗位。
• 个人职责边界。
• 关键技术动作。
• 可核验证据。
• 可写入简历的候选表述。
• 待补指标或待确认事实。

交给 /interview 的高风险 Claim 清单

包括：

• Ownership Claim：主导、负责、Owner、0 到 1 等强表述。
• Metric Claim：百分比、延迟、用户数、准确率、覆盖率等指标。
• Architecture Claim：架构设计、核心链路、调度、状态机、缓存、容错等。
• Result Claim：上线、采用、效率提升、成本下降等结果。

质量门禁

落盘前逐项自检：

• 已按用户请求选择源码课程或导学面经模式，只创建本次需要的文件。
• 源码课程中的文件与符号均可定位，阅读路线按真实调用或事件顺序组织。
• 课程文件与练习文件的课程编号、标题和内容范围一致，未请求章节与用户笔记保持原样。
• 未确认行为、设计推断和未测量收益均已明确标注。
• 导学面经模式已生成 导学-{简称}.md 与 面经-{简称}.md，或已输出等价双文件内容。
• 导学包含重点亮点、学习顺序、推荐阅读和相对路径。
• 导学包含固定自学提醒。
• 面经项目简介可直接放入简历，不堆叠内部私名。
• 面经每条一级 bullet 以 **通用支柱名：** 开头，支柱名不是私有类名、函数名、路径、事件名或业务黑话。
• 面经每条一级 bullet 只表达一个支柱，至少具备“问题或演进 + 机制 + 结果”。
• 面经主问题数量为 15-25。
• 主问和追问口播均不少于 150 个汉字。
• 面经包含源码证据索引。
• 没有把团队成果冒领为个人成果。
• 没有编造指标、上线结果、公司、职位或技术栈。