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、截图、上线记录或用户反馈可以作为证据？ 可选脚本： ```bash 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. 读取[课程大纲规范](references/course-outline-design.md)； 2. 检查项目入口、主要功能、模块边界和代表性运行流程； 3. 在课程文件中生成课程大纲，每课给出真实文件与符号的阅读顺序； 4. 记录源码版本、实际覆盖范围和尚未覆盖的模块。 ### 展开指定课程 1. 读取现有课程文件与[单课讲解规范](references/course-lesson-design.md)； 2. 确认课程编号、主题、前后边界和源码范围； 3. 沿真实调用或事件顺序展开该课，并以完整流程串联收尾； 4. 只更新指定课程，保留其他课程和用户笔记。 ### 配套理解题 1. 读取课程文件中的对应课程与[配套练习规范](references/course-practice-design.md)； 2. 在练习文件中更新相同编号和标题的课程练习； 3. 默认只生成问题和必要的回答要求，不附标准答案； 4. 只考查课程已经讲过的内容，保留其他课程的练习与用户答案。 用户明确要求组合操作或同步时，按“大纲 → 展开 → 练习”的依赖顺序执行请求包含的操作，并只创建本次需要的文件。 ### 源码事实与局部更新 - 每课围绕一个能从触发走到结果的项目场景组织，先给紧凑主链，再给编号阅读步骤。 - 文件、函数、方法、事件和配置位置必须能在当前源码中定位。文档与实现冲突时，以实现为准并指出差异。 - 直接调用与异步事件分别说明。队列、回调和依赖注入要追到注册、绑定或消费证据；无法确认的运行时目标标为 `待确认`，停在已证实的接口边界。 - 只讲源码已经实现的异常、恢复和清理路径。设计动机没有证据时标为分析，性能收益没有测量时不下结论。 - 编辑前读取完整目标文件，只替换用户请求的章节。重排、合并或删除课程时检查受影响的编号、标题与练习引用。 - 如果课程文件或练习文件已用于其他用途，保留原文件并说明冲突，改用不会覆盖原文的文件名。 ## 简历 bullet 约束 生成 `面经-{简称}.md` 前，先对照 [领域中立 Bullet few-shot](references/examples/bullet-few-shots.md)。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 个汉字。 - 面经包含源码证据索引。 - 没有把团队成果冒领为个人成果。 - 没有编造指标、上线结果、公司、职位或技术栈。