代码库入门导航

中文简介

代码库入门导航：把陌生仓库变成足以支持下一步决定的、可追溯的地图。它以任务和阅读预算约束探索，记录目录、入口、数据流、配置与测试拓扑，并把已知、推测、未知和命令状态严格分开。

使用背景

在接手服务、Web 应用、库、CLI 或 monorepo，或在修改局部功能前需要找到正确入口、契约、测试和风险时使用。产出可交给 spec-to-implementation-plan、issue-to-pr、bug-debugging-playbook、test-generator 或 code-review-assistant；它不是完整安全审计、性能压测或替代真实运行验证。

核心原则

• 先写要支持的决定和非目标，再读文件；阅读是为任务服务，不是仓库导览竞赛。
• 每项结论都标记为 [已知]、[推测] 或 [未知]，并给出文件、命令或用户材料证据；推测不能伪装成架构事实。
• 命令只可标为 [已运行-通过]、[已运行-失败] 或 [未运行]。前两者必须有工作目录、执行时间、退出码、脱敏关键输出和可定位证据；[未运行] 只能说明计划工作目录与阻断原因，绝不能填造执行证据。脚本定义、README 或 CI 配置只能证明“存在该命令”，不能证明本地可用。
• 目录、入口、请求/事件、数据、配置和测试必须在同一条关键路径上相互指向；孤立的文件清单不是架构地图。
• 配置与秘密只记录键名、来源和边界，绝不输出 .env 值、令牌、私钥、连接串或完整敏感日志。

适用场景

• 新成员需要了解完整 Web 仓库的启动路径、前后端边界、迁移、CI 和风险热区。
• 仓库缺少 README、依赖服务或环境变量，需用最小尝试说明为什么无法启动及应先补什么。
• 只改一个路由、组件、任务或规则，需沿调用链找到最小相关文件集和回归测试。
• 在编写计划、修复 Bug、审查改动或拆分模块前，需要有证据的入口和测试地图。

不适用场景

• 已有明确文件、行为和测试的微小改动，不要借机完整遍历仓库；只做局部路径核验。
• 需要证明漏洞、合规性、许可证或生产安全性时，转交相应安全/合规流程；本 Skill 只标记可见的风险线索。
• 需要执行数据库写入、部署、生产请求或导出敏感配置时，先取得明确授权；默认只读、最小化和脱敏。

输入要求

先收集并原样保留可用输入；缺失项写 [未知]，不要补造：

1. 任务：要回答的决定、目标行为、受影响用户、截止时间和明确非目标。
2. 边界：仓库/分支/工作树、可读目录、可运行权限、禁止触碰的环境和可接受的阅读时间。
3. 线索：错误、路径、Issue、PR、日志、README、命令、接口名、页面或业务术语。
4. 运行条件：系统、包管理器、凭据/服务可用性、允许的本地命令和不可执行原因。
5. 交付深度：局部改动、一个服务、完整 Web 仓库或只需启动诊断。

信息不足时的处理

• 没有任务： 只输出澄清问题和最小仓库概览；不宣称“关键模块”或完整架构。
• 没有文档或无法启动： 读取清单、锁文件、脚本、容器/CI 和配置样例；最多做一次最小、只读的启动/测试尝试。记录原始失败类别、退出码和缺失前提，停止重复猜测。
• 只有局部需求： 从命名入口、路由、组件、错误或最近测试反向追踪；设定局部阅读预算，只有调用链、契约或测试阻断时才扩展一跳。
• 发现秘密： 停止展示内容，只记录文件类型、键名模式或秘密管理引用；对输出和命令日志脱敏，并建议轮换已暴露的凭据。
• 证据互相矛盾： 并列记录来源和范围，结论写 [未知] 或 [推测]，给出能判别差异的下一次阅读或安全命令。

工作流

1. 建立任务卡和阅读预算。 写决策、目标路径、非目标、允许命令和停止条件。局部改动优先 15-30 分钟/一条调用链；启动诊断优先 20-40 分钟/一个运行面；完整 Web 仓库先用 45-90 分钟建立关键路径。预算耗尽时先交付已知与缺口，只有被当前决定阻断才扩展。
2. 取得最小仓库骨架。 用快速文件搜索和根目录清单确认包管理器、工作区、应用/服务边界、文档、配置样例、容器和 CI；不递归阅读生成物、依赖目录、构建产物、二进制或无关历史。
3. 定位入口与目录责任。 从任务入口和清单脚本找到浏览器/CLI/worker/API 入口、路由/命令注册、组合根和共享包。为每个目录只写与任务有关的责任、证据和是否进入阅读范围。
4. 追踪一条关键路径。 顺序记录触发 -> 入口 -> 校验/鉴权 -> 业务模块 -> 外部 API/队列/存储 -> 响应或副作用；同时标记数据契约、异步边界、失败恢复和尚未读到的跳点。
5. 映射配置、秘密与运行边界。 从 manifest、样例、schema、容器、CI 或部署文件记录配置键名、提供者、默认值来源和环境差异。只读配置结构，不读取或复制秘密值。
6. 建立测试拓扑和命令证据。 找到单元、集成、端到端、契约、fixture、mock、测试初始化与 CI 触发点。对每个命令记录目的、命令、工作目录、前提和状态；仅已运行状态再记录执行时间、退出码、脱敏关键输出和可定位证据（日志路径、终端记录或 CI URL 加 job step）。未运行时只写阻断原因，不填执行字段或证据。
7. 排序风险与下一步。 以证据列出认证/授权、支付、迁移、公开接口、并发任务、缓存、跨包依赖、未覆盖路径和配置漂移等热区；按“能减少当前不确定性”的价值给出下一步阅读顺序。最后读取 references/checklists.md，用模板完成交付。

专业判断规则

任务驱动的范围控制

任务深度	先读	停止或扩展条件
局部功能	任务入口、直接调用者/被调用者、契约、最近测试和相关配置	调用链闭合且能定位测试就停止；仅在跨边界、共享契约或失败证据要求时扩展一跳
启动诊断	根清单、锁文件、脚本、容器/CI、配置样例和启动入口	已定位首个阻断前提就停止反复运行；改读提供该前提的文件
完整 Web 仓库	工作区、应用入口、路由、服务组合根、数据访问、配置、测试和 CI	关键用户路径、运行面和测试面都有证据后停止；不逐文件讲解

证据、命令与已知边界

• 文件证据使用可定位路径和必要时行号；[已运行-通过] 与 [已运行-失败] 的命令证据记录完整命令、工作目录、执行时间、退出码、简短脱敏摘要和可定位证据（日志路径、终端记录，或 CI URL 与 job step）。
• [已知] 只由直接阅读、命令输出或用户提供材料支持；[推测] 必须写推断依据与验证动作；[未知] 写明它阻断的决定。
• [未运行] 的命令可作为“建议尝试”，只填计划工作目录与阻断原因；执行时间、退出码、关键输出和证据定位必须留空/写“未运行，不填”。不可写“可启动”“测试通过”或“已验证”。[已运行-失败] 只证明该环境中的该次失败，不自动证明系统故障。
• 文件名含 test 或 CI 中有命令不等于覆盖充分；测试拓扑必须说明覆盖层级、目标路径、隔离/fixture 和缺口。

风险热区与秘密边界

• 优先标记：鉴权/权限、个人或支付数据、数据库迁移、公开 API/事件、队列/定时任务、缓存一致性、第三方回调、部署/回滚、生成代码和跨包共享契约。
• 风险条目必须含影响路径、证据、当前置信度和下一次检查；“复杂”“旧”“大”不是独立风险证据。
• 可以阅读 .env.example、schema、变量名和秘密管理引用；不要读取 .env、凭据文件、私钥、令牌、生产导出或把它们放入终端输出。

输出契约

按 references/templates.md 输出以下 13 项，且每项都服务于当前任务：

1. 任务卡与阅读预算：决定、范围、非目标、停止条件。
2. 证据账本：[已知]、[推测]、[未知] 与可定位来源。
3. 仓库与目录地图：责任、是否已读和任务相关性。
4. 入口地图：用户/API/CLI/worker 入口、组合根和路由/命令注册。
5. 关键数据/控制流：触发、模块、契约、存储/外部服务、失败路径。
6. 配置与秘密边界：键名/来源/环境差异/安全处理，绝不含值。
7. 命令证据表：命令、工作目录、前提、状态、执行时间、退出码、关键输出摘要、可定位证据和阻断原因。
8. 测试拓扑：层级、位置、关键路径、fixture/mock、CI 和缺口。
9. 风险热区：影响、证据、置信度和最小缓解/检查。
10. 已排除区域：未读范围和不读理由。
11. 当前可作出的决定及仍被阻断的决定。
12. 下一步阅读顺序：每一步的目的、文件/命令和停止条件。
13. 给下一位协作者的最小交接：入口、测试、风险、未知和请求。

质量门槛

• 不交付没有任务、阅读预算、非目标和停止条件的“全仓库概览”。
• 不以目录树或依赖清单替代入口、数据流、配置和测试之间的关系。
• 不把 README、脚本或 CI 中出现的命令写成已成功运行；每个命令都有三态状态。已运行状态必须具有工作目录、时间、退出码、摘要和可定位证据；未运行状态不得填证据，必须解释阻断原因。
• 不把推测架构、缺失配置或单一文件线索写成事实；已知、推测和未知必须可分辨。
• 不输出秘密、令牌、连接串、私有数据或未脱敏日志；发现时只说明边界和后续安全动作。
• 不为局部改动阅读无关应用、包、生成物或历史；扩展范围必须说明当前路径为何被阻断。
• 不把风险写成形容词；每条风险都可回到文件、命令或明确缺失的证据。
• 交付前用 references/checklists.md 检查，并使模板、清单和至少一个相关场景示例闭环。

常见失败与修正

失败	修正
先遍历所有目录，再想任务	先写决定、入口线索和阅读预算；只扩展阻断当前路径的一跳。
把 package.json 脚本写成“项目可启动”	标为 [未运行]，或运行后记录通过/失败、退出码与环境前提。
用“应该是 MVC/微服务”解释架构	标为 [推测]，列出入口、组合根和跨边界证据，或保持未知。
因启动失败反复换命令	记录第一次最小失败，转读配置样例、容器、CI 和依赖服务说明。
复制 .env 或完整错误日志	只记录键名/错误类别并脱敏；把秘密处理留给授权流程。
只列测试目录	说明每层测试覆盖的关键路径、fixture/mock、CI 触发和未覆盖风险。
风险写成“文件很大”	指出它处于哪条关键路径、为什么影响修改和先读哪个边界。

参考资料

• references/usage-guide.zh.md：中文调用顺序、阅读预算、命令状态和协作方式。
• references/templates.md：13 项入门简报、证据账本和命令表模板。
• references/checklists.md：范围、证据、秘密、测试和交付质量门。
• references/examples.md：完整 Web、无文档无法启动、局部功能三种闭环示例。