Yy Learn Project

yy-learn-project

描述

从当前代码、配置、测试和权威文档中建立可核验的证据链，生成便于开发者学习陌生项目的 Markdown 文档。支持项目整体概览和单一功能专题两种模式，重点解释真实调用链、数据流、核心代码、实现边界与文档冲突。

使用场景

• 用户接手陌生项目，需要生成可持续阅读的项目学习文档
• 用户指定某个功能主题，要求解释实现流程、核心代码及文件行号
• 用户希望把连续分析结果保存到项目的学习目录

不应触发：

• 用户只要求解释单个函数或一小段代码，不需要生成学习文件
• 用户要求审核、修改、重构或测试代码
• 用户要求创建项目首页说明、任务交接材料或脱离当前源码的技术教程

指令

步骤 1. 确定学习目标与输出模式

提取目标项目、学习主题、输出目录、文件名和期望深度。用户没有指定输出目录时，默认使用项目根目录下的 learning/；没有指定文件名时，根据主题生成简短的中文 Markdown 文件名。

决策分支：

• 整体概览：覆盖项目定位、结构、技术栈、模块职责、主流程、配置、运行方式和推荐阅读路径
• 功能专题：围绕一个可描述的行为追踪入口、调度、核心实现、数据转换、输出和下游消费
• 目标同时包含多个独立主题：拆成多份文档；先生成总索引，再逐个完成专题
• 目标文件已存在且用户要求更新：读取现有内容后增量修订，保留仍然正确的结论
• 目标文件已存在但用户未授权覆盖：停止写入并询问是更新现有文件还是更换文件名

步骤 2. 读取项目规约与权威入口

先查找并读取目标范围内适用的 AGENTS.md、本地覆盖规则及其按需引用。再读取项目声明的文档索引、架构说明、模块说明、契约和根级配置，确认哪些资料是权威来源。

只读取理解目标所必需的内容。跳过依赖、构建产物、缓存、生成文件和大体积数据目录，除非它们正是用户指定的研究对象。

决策分支：

• 仓库声明文档单一真源：按声明顺序读取，并用源码核对当前实现
• 没有项目规约或文档入口：从根级 manifest、启动入口、源码目录和测试目录建立最小项目地图
• 文档与源码不一致：分别记录“约定行为”和“当前实现”，不静默选择其中一方

步骤 3. 识别技术栈并路由源码入口

读取 resources/language-routing.md，根据 manifest、扩展名和运行入口选择对应技术栈的定位方式。

通用规则始终生效；命中特定技术栈时，特定规则优先于通用规则。未列出的语言或框架使用资源中的通用兜底流程。混合语言项目分别定位各运行时边界，再追踪跨进程或跨服务通信点。

步骤 4. 建立证据地图

先列出待回答的问题，再为每个问题记录代码、配置、测试或文档证据。不要在证据不足时开始撰写正文。

整体概览至少核对：

1. 项目服务对象和核心目标
2. 独立项目或 monorepo 的组织方式
3. 主要语言、框架和运行时职责
4. 核心模块、入口和主数据流
5. 配置、持久化、外部通信和输出
6. 本地运行、测试及主要限制

功能专题至少核对：

1. 用户操作、命令、API 或内部事件入口
2. 参数解析、校验和配置来源
3. 调度层及其直接上游
4. 核心算法或业务实现
5. 中间数据结构及转换规则
6. 输出、落盘、响应或下游消费者
7. 失败处理、资源清理、并发或性能保护
8. 能证明关键行为的测试

只追踪目标的直接上下游和必要共享层。发现替代后端、兼容分支或历史实现时，先确认它是否能在当前配置下进入主链路，再决定是否写入正文。

步骤 5. 提取调用链、核心代码和行号

优先使用精确文本搜索定位符号、调用方、配置键和输出字段，再读取完整函数上下文。所有行号必须来自当前工作区文件，禁止凭记忆填写。

对每个关键阶段记录：

• 相对项目根目录的文件路径
• 符号名称或配置键
• 当前起止行号
• 上游调用者和下游消费者
• 输入、输出和副作用
• 能说明关键行为的最小源码片段

核心代码必须摘自当前源码，可省略无关分支，但不得改变变量含义、执行顺序或异常语义。省略内容时使用与目标语言匹配的注释标记。所有围栏代码块必须声明语言。

文档引用使用以下格式：

[文件名](../相对路径/文件名.ext#L123) 第 123-156 行

如果目标平台不支持行号锚点，仍保留 文件路径:行号 文本。引用目录、二进制文件或无法稳定编号的生成内容时，不伪造行号，并说明限制。

步骤 6. 区分事实、推断和冲突

对结论进行证据分级：

• 当前行为：由可执行源码、配置或测试直接证明
• 约定行为：由项目声明的契约、架构或权威文档定义
• 推断：由命名、依赖或调用关系推导，但没有直接断言
• 未确认项：缺少必要环境、生成文件、运行数据或外部服务证据

用户询问“当前如何实现”时，以当前可执行源码为行为依据；用户询问“应该如何工作”时，以项目声明的权威契约为依据。两者冲突时必须并列说明文件位置、具体差异和可能影响。

不得编造运行结果、性能数据、默认值或测试结论。没有实际运行验证时，明确写“未运行验证”。

步骤 7. 生成学习文档

使用 templates/topic-learning-doc-template.md 生成文档。整体概览可删除不适用的专题章节，但必须保留阅读范围、关键文件、证据状态和推荐阅读顺序。

写作要求：

• 面向刚接手项目的开发者，首次出现的项目术语要解释
• 先给整体调用链，再按执行顺序展开
• 代码示例之后紧跟用途、输入输出和关键判断说明
• 配置值同时说明来源、覆盖方式和当前默认值
• 坐标、单位、状态、并发和失败策略必须明确口径
• 重复路径集中到关键文件表，正文只在需要定位时再次引用
• 不使用故事化开头、宣传性表达或无信息量的过渡句

步骤 8. 校验文档

写入完成后执行以下检查，发现问题先修正文档再交付：

1. 以 UTF-8 读取文件，确认标题、首段和末段完整
2. 检查所有相对文件链接对应的目标存在
3. 重新核对每个关键引用的符号和当前行号
4. 抽查核心代码片段与源码一致
5. 检查调用链中的每条边都有调用、导入、契约或数据字段证据
6. 检查事实、推断、冲突和未确认项没有混写
7. 检查所有代码块包含语言标识，Markdown 结构符合目标仓库规范
8. 检查文档没有泄露密钥、令牌、本地敏感配置或业务隐私数据

如果项目已经提供 Markdown 检查命令，且仓库规约要求执行，则运行与本次文档相关的检查。不要为了生成学习文档安装新依赖或启动生产服务。

步骤 9. 输出结果

向用户说明：

1. 已创建或更新的文档路径
2. 文档覆盖的调用链和关键主题
3. 已完成的链接、行号、编码或 Markdown 校验
4. 未运行的测试、无法核实的外部行为和已发现的文档冲突

最终回复只总结结果，不重复粘贴整篇文档。

安全边界

• 默认只读取源码并写入用户授权的学习文档目录，不修改业务代码、配置、测试或权威项目文档
• 不运行部署、发布、数据库迁移、外部写入或真实业务请求
• 不把 .env、本地覆盖配置、日志中的凭证或用户数据写入学习文档
• 需要修改授权目录外的索引或导航文件时，先说明文件、原因和影响并获得授权

相关资源

• templates/topic-learning-doc-template.md：整体概览和功能专题共用的学习文档结构
• resources/language-routing.md：不同技术栈的源码入口、契约和测试定位规则