Yy Read Project

yy-read-project

描述

帮助 AI 用统一方法阅读两类项目：独立项目与 monorepo 项目。目标不是机械罗列文件，而是先识别项目形态和阅读范围，再基于整体把控回答项目做什么、核心模块分别负责什么、它们如何协作。

默认聚焦 7 个维度：项目形态、阅读范围、项目定位、结构分层、模块或子项目职责、技术栈边界与本地化方案、通信与依赖关系。

使用场景

• 用户说“先帮我看看这个项目是干嘛的”
• 用户说“帮我快速阅读这个项目”
• 用户要了解“项目整体怎么组织的”
• 用户要梳理“各个模块 / 子项目都是干嘛的”
• 用户要确认“项目里用了哪些编程语言，分别负责什么”
• 用户要确认“i18n 怎么做”“文案和语言包在哪里”
• 用户要确认“模块之间怎么通信”“子项目之间怎么协作”
• 用户接手存量项目，需要一份入项级别的整体概览

不应触发：

• 用户只想解释某一个函数、某一个文件或某一段代码
• 用户已经明确要求直接修改代码、修 bug 或实现功能
• 用户只想执行 lint、测试、构建或发布
• 用户要求输出 README、设计文档或交接文档正文（应使用对应技能）

指令

步骤 1. 识别项目形态与阅读范围

• 先提炼用户最关心的范围：整个项目、某一层目录、某个模块、某个子项目，或某个主题（如 i18n、通信、构建）。
• 从根目录和根配置判断当前属于以下哪一类：
  • 独立项目
  • monorepo 项目
• 根据用户意图把阅读模式归为以下三类之一：
  • 整体阅读：用户要理解整个项目或整个 monorepo
  • 局部阅读：用户只关心某个目录、模块、子项目或链路
  • 主题阅读：用户只关心 i18n、通信、构建、协议、依赖等主题
• 若用户未指定范围，默认按“整体项目概览”执行，并覆盖项目定位、结构分层、模块或子项目职责、技术栈边界、本地化方案、通信关系 6 个核心主题。
• 仅在以下情况主动追问：
  • 用户同时提出多个互相冲突的目标，无法判断优先级
  • monorepo 体量极大且用户额外要求对每个子项目展开到实现细节，需要确认输出深度

决策分支：

• 用户明确指定主题：优先深挖该主题，同时保留最小整体概览
• 用户只说“看看项目”：输出标准整体概览
• 用户只指定某个子目录、模块或子项目：围绕该范围分析，并补一段它在整体架构中的位置
• 局部阅读或主题阅读：只扫描目标对象、直接上下游、根级组织文件，以及理解该范围所必需的共享契约或公共模块
• 识别为独立项目：走独立项目分析分支
• 识别为 monorepo 项目：走 monorepo 全局分析分支

步骤 2. 判断组织方式与技术栈边界

• 从项目根目录识别组织工具与语言栈，优先读取：
  • JavaScript/TypeScript：package.json、pnpm-workspace.yaml、turbo.json、nx.json、lerna.json
  • Rust：根 Cargo.toml 中的 [workspace]
  • Go：go.work、多模块 go.mod
  • Python：pyproject.toml、requirements.txt
  • 其他：Makefile、Taskfile.yml、justfile、根 README、架构文档
• 判断项目是单语言、混合语言，还是多运行时协作结构，并记录不同技术栈承担的职责边界。
• 把“技术栈语言”与“产品多语言 / i18n”明确分开：
  • 技术栈语言：TypeScript、Rust、Go、Python 等编程语言及其职责分工
  • 产品多语言：界面文案、翻译资源、语言切换、地区化格式等本地化能力
• 不要一开始就全量遍历源码；先靠根配置和目录骨架建立地图。

决策分支：

• 检测到 monorepo 配置或明显多子项目结构：记录子项目组织规则、扫描入口和分层方式
• 未检测到 monorepo 特征：按独立项目处理，重点识别核心目录和主入口
• 检测到 Rust / Go / Python 等非前端子工程：把它们视为正式模块或正式子项目，不要只盯前端代码
• 用户问“多语言怎么做”但语义不清：先根据上下文判断是在问编程语言协作还是 i18n；若两种理解都成立，主动点明这两个方向并分别给最小结论

步骤 3. 盘点结构单元

• 盘点时优先基于 manifest、根配置和就近 README，而不是先深读业务代码。
• 若是独立项目，整体阅读时至少提取以下结构单元：
  • 核心目录或核心模块
  • 所属语言/框架
  • 职责定位
  • 运行形态：应用、库、服务、脚本、协议层、生成产物或工具
• 若是独立项目，局部阅读时至少提取以下结构单元：
  • 目标目录或目标模块
  • 它在整体中的上一级分层位置
  • 与它直接交互的关键模块
  • 为理解它必须读取的入口文件、配置文件或文档
• 若是 monorepo 项目，整体阅读时必须遍历全部子项目；每个子项目至少提取以下信息：
  • 名称或目录名
  • 所属语言/框架
  • 职责定位
  • 运行形态：应用、库、服务、脚本、协议包、生成产物或工具
  • 与其他子项目的主要依赖关系
• 若是 monorepo 项目，局部阅读时至少提取以下信息：
  • 目标子项目或目标目录
  • 它所属的分组或层级，如 apps/、packages/、services/
  • 与它直接相关的上游、下游和共享契约层
  • 用于解释其定位的最小全局信息，如工作区组织方式、主链路位置
• 发现 generated、dist、vendor、target、node_modules 等派生目录时，默认跳过，不把它们误判为正式模块或业务子项目。

决策分支：

• 独立项目：输出核心模块/目录职责，不强行虚构“子项目”
• monorepo 整体阅读且子项目数量较少：逐个说明全部子项目职责
• monorepo 整体阅读且子项目数量较多：仍需覆盖全部子项目，但可按 apps/packages/services/libs/tools 等分组呈现，避免无差别堆叠
• monorepo 局部阅读：不要求展开全部子项目，但必须说明目标对象在全局中的位置，并覆盖直接上下游

步骤 4. 判断项目定位与运行拓扑

• 结合根 README、docs/、AGENTS.md、ADR、启动入口和主配置文件，回答“项目是干什么的”。
• 梳理关键运行拓扑，例如：
  • 单体前端应用
  • 单体后端服务
  • 前端 + 后端服务
  • 桌面壳 + 本地核心 + 驱动适配层
  • 应用层 + 共享协议层 + 代码生成层
  • 控制面 + 数据面 + SDK / CLI / 管理台
• 当文档描述与代码组织不一致时，必须明确指出冲突，不能默认相信任一方。

步骤 5. 分析本地化方案与文案归属

• 搜索并识别 i18n 入口与资源形态，例如：
  • locales/、i18n/、messages/
  • vue-i18n、react-intl、i18next、lingui
  • 自定义语言包、后端翻译表、客户端枚举标签映射
• 说明以下信息：
  • 文案资源放在哪
  • 由谁加载与切换语言
  • Key 命名方式和语言文件组织方式
  • 是否有回退策略、默认语言和格式化逻辑
  • 哪一层负责把枚举值或状态码转成用户可读文案
• 若用户问题中的“多语言”实际指编程语言协作，先在步骤 2 交代技术栈职责边界，再在本步骤单独交代 i18n 是否存在，避免混写。

决策分支：

• 检测到成熟 i18n 框架：说明框架、入口文件、资源目录和调用方式
• 检测到自定义实现：说明自定义词典、映射层和使用边界
• 未检测到明显 i18n 机制：明确写“暂未发现系统化多语言方案”，并给出你检查过的证据位置

步骤 6. 分析依赖关系、共享契约与通信链路

• 把“源码级依赖/共享代码”和“运行时通信”分开分析，避免混为一谈。
• 独立项目重点检查：
  • 模块之间的 import / 调用关系
  • 内部事件、状态管理、服务层、数据访问层的边界
  • 是否存在本地协议层、适配层或插件桥
• monorepo 项目重点检查：
  • 子项目之间的本地依赖，如 workspace:*、路径依赖、Cargo workspace members
  • 共享协议、类型、SDK、生成代码目录
  • 跨进程、跨端、跨服务、跨壳层通信链路
• 运行时通信重点检查：
  • HTTP / RPC / WebSocket / gRPC / 消息队列 / 事件总线
  • 桌面桥接、WebView bridge、插件桥、进程间通信
  • 配置驱动或文件交换
• 对每条关键关系，尽量说明调用方向、边界层和关键文件位置。

决策分支：

• 存在 proto / contracts / openapi / schema / generated：优先把这些识别为契约层，说明谁生产、谁消费
• 存在前后端、多进程或多服务边界：明确请求入口、路由层、业务层、适配层分别在哪里
• 只发现源码级 import，没有明显运行时调用：说明当前主要是代码复用型关系，而非强运行时通信

步骤 7. 从整体视角归纳项目

• 基于前 6 步，不只罗列事实，还要给出整体判断：
  • 项目的核心目标是什么
  • 架构是如何分层的
  • 独立项目内部模块如何分工
  • monorepo 中各子项目如何协同完成完整能力
• 若是 monorepo，必须单独总结：
  • 全部子项目大致分为哪些类别
  • 哪些子项目处在主链路上
  • 哪些子项目承担共享契约、工具、协议或基础设施职责

步骤 8. 形成最小阅读路径

• 基于前 7 步，给出一个从根到局部的阅读顺序，帮助用户继续深入。
• 阅读路径至少包含：
  • 根目录优先文件
  • 独立项目下最关键的 2-5 个模块，或 monorepo 下最关键的 2-5 个子项目
  • 每个关键结构单元建议先看的入口文件或文档
• 若用户后续要接着看某一主题，优先把路径指向该主题的权威文件，而不是泛泛给目录。
• 若当前是局部阅读，阅读路径优先围绕目标对象、直接上下游和权威入口，不强行补齐全项目游览路径。

步骤 9. 输出结果

• 使用 templates/project-overview-template.md 的结构输出结果。
• 输出时必须区分“事实”“推断”“未确认项”，并尽量标注“依据位置”：
  • 事实：能从代码、配置或文档直接定位到
  • 推断：基于目录、命名或调用关系推出来的结论
  • 未确认项：证据不足但对架构理解重要的部分
• 对整体阅读的 monorepo，必须覆盖全部子项目；可用分组、表格或分段组织，避免遗漏。
• 对局部阅读的 monorepo，不要求逐个展开全部子项目，但必须交代目标对象的全局定位、直接上下游和必要共享层。
• 对每个关键判断尽量附文件或目录依据，方便用户继续追读。

输出约定

• 先给一句话项目定位，再给结构化概览。
• 必须先写清当前项目形态：独立项目或 monorepo。
• 必须单独写明当前阅读范围：整体阅读、局部阅读或主题阅读，以及目标对象是什么。
• 独立项目场景下，优先按“核心模块 / 目录职责”组织。
• monorepo 整体阅读场景下，必须覆盖全部子项目，并单独说明全局关系。
• monorepo 局部阅读场景下，优先按“目标子项目 / 直接上下游 / 所在分层位置”组织。
• 技术栈边界、本地化方案与通信必须单独成节，不能埋在其他段落里。
• 如果没有找到 i18n 或清晰通信链路，要明确写“未发现”或“待确认”，不要臆造结论。
• 如果项目明显是混合语言结构，要明确指出不同语言模块或子项目各自承担什么角色。

安全边界

• 默认只做阅读、归纳和定位，不主动修改代码。
• 默认不运行构建、测试、安装依赖、启动服务；仅当用户明确要求，或缺少生成文件导致无法理解结构时才考虑执行。
• 默认跳过 node_modules/、dist/、build/、coverage/、target/、.git/ 等派生目录，除非它们本身就是用户要分析的对象。
• 不把生成文件或缓存目录误当成架构主入口；若项目严重依赖代码生成，需回到生成配置和源契约分析。

相关资源

• templates/project-overview-template.md：项目整体概览输出模板
• examples/standalone-input.md：独立项目局部阅读输入示例
• examples/standalone-output.md：独立项目局部阅读输出示例
• examples/monorepo-input.md：monorepo 局部阅读输入示例
• examples/monorepo-output.md：monorepo 局部阅读输出示例