浏览 AI 知识库

第一次打开陌生仓库,先找规则、入口、构建和测试命令

用一个真实形态的 Node.js 内容站任务演示:先保护未提交改动,再从页面文案追到路由、数据源和生成命令,最后交付带路径、命令与未知项的项目地图。

从案例现场看到最终结果

先看真实输入和失败现场,再跟着处理过程核对中间结果与最终输出。

现场

任务只有一句“把搜索空状态改清楚”,仓库里却有 1,400 多个文件

查看这一段
输入

先把用户任务、仓库状态和规则放到同一张表

查看这一段
处理

交付的不是目录树,而是一张能指导下一步的项目地图

查看这一段
结果

从一个页面文案追到路由、源文件、生成器和校验命令

查看这一段
案例现场

任务只有一句“把搜索空状态改清楚”,仓库里却有 1,400 多个文件

以下是教学用仓库现场:一个 Node.js 静态内容站,页面由 scripts/build-site.mjs 生成,源数据在 content/search-copy.mjs,public/ 是输出目录。接手时 git status 显示 content/search-copy.mjs 已有他人修改;用户只允许先审查,不允许写文件。

目标不是读完所有文件,而是回答四件事:页面从哪里生成、这句文案的唯一来源在哪里、改动会影响哪些输出、用什么现有命令验证。每个判断都必须有路径、符号或命令输出。

  • 一张可核对的项目地图
  • 本次任务的源文件与生成物边界
  • 不会覆盖现有改动的验证计划
实际输入

先把用户任务、仓库状态和规则放到同一张表

输入现场内容决定
用户任务搜索无结果时,把“暂无数据”改成能引导用户继续搜索的文案只追搜索空状态,不顺带改搜索算法
工作区M content/search-copy.mjs;M public/search.html两个文件都可能含既有改动,禁止覆盖
项目规则AGENTS.md:源文件优先;生成页不得手改;Footer 禁止顺带修改先读生成器和源数据,Footer 排除在范围外
项目清单package.json:build、verify:search、verify:footer只记录仓库真实存在的命令
当前权限只读审查不安装依赖、不运行部署、不编辑文件

案例路径和输出为教学样例,但工作方法可直接用于真实仓库。真实执行时必须替换成当前项目的实际状态。

第一轮只读

五条命令足够把搜索范围从全仓库收窄到一个功能链

从仓库根目录运行。任何命令不存在或失败时保留原始错误,不把“工具缺失”误判为“项目损坏”。

PowerShell

规则、状态、文案和真实脚本

Get-Location
rg --files -g "AGENTS.md" -g "README*" -g "package.json"
git status --short
rg -n "暂无数据|没有结果|emptyState" . -g "!public/**" -g "!node_modules/**"
node -e "const p=require('./package.json'); console.log(p.scripts)"
案例命中

搜索结果不是结论,还要追导入关系

content/search-copy.mjs:12: export const emptyState = { ... }
scripts/build-site.mjs:8: import { emptyState } from '../content/search-copy.mjs'
scripts/build-site.mjs:144: renderSearchEmptyState(emptyState)
public/search.html:317: <section data-search-empty>...

如果只搜索生成后的 public/search.html,就会把输出误当源文件;排除生成目录后再沿 import 追踪。

中间过程

沿页面状态、渲染函数、内容源和构建命令走一遍

  1. 01

    确认页面状态

    浏览 search.html 的空结果分支,确认目标是 data-search-empty,而不是首次进入、加载中或请求失败。

    证据:页面状态选择器与触发条件。
  2. 02

    定位渲染函数

    在 build-site.mjs 找到 renderSearchEmptyState,记录它读取的字段和输出位置。

    证据:函数名、导入和调用行。
  3. 03

    确认唯一内容源

    emptyState 来自 content/search-copy.mjs;public/search.html 带生成标记,因此不直接编辑输出。

    证据:导入关系与生成文件头。
  4. 04

    读取验证入口

    verify:search 检查空状态字段和 DOM 标记;build 会重写 public/search.html;verify:footer 只做回归,不授权改 Footer。

    证据:package.json 的实际 scripts。
  5. 05

    划定影响范围

    预计只改内容源并重新生成搜索页;现有未提交差异要逐行保留,具体编辑仍等待用户确认。

    证据:git diff 与生成清单。
AI 介入点

让编程 Agent 先画仓库地图,不要一上来改代码

适合第一次打开陌生项目时使用,目标是找到规则、入口和验证命令。

可复制使用

让编程 Agent 先画仓库地图,不要一上来改代码

只读调查这个仓库里与【功能/报错】直接相关的部分。不要先改代码,也不要仅凭目录名推断职责。

仓库根目录【】;我要理解的功能/错误【】;允许执行的只读命令和现有验证【】。

从适用的项目规则和 Git 状态开始。用唯一文案、路由、命令或符号追踪:用户入口 -> 调用链 -> 真正读写逻辑 -> 输出。确认源文件/生成物边界、现有测试以及仓库实际定义的启动和构建命令。

每个结论附路径、符号或命令原始输出;没有证据写“未定位”。交付项目地图、相关文件清单、建议的最小验证顺序、风险和未知项后停止。不要编辑文件、安装依赖、访问无关目录或把未运行的命令写成已验证。

使用范围:适合第一次打开陌生项目时使用,目标是找到规则、入口和验证命令。本轮不修改文件、不安装依赖、不运行会改变外部状态的命令。

最终输出

交付的不是目录树,而是一张能指导下一步的项目地图

项目地图字段案例结论依据
规则根目录 AGENTS.md 适用;生成页不可手改;Footer 不在范围内AGENTS.md
功能入口search.html 的 data-search-empty 状态public/search.html + 状态逻辑
渲染路径emptyState -> renderSearchEmptyState() -> public/search.htmlimport 与调用关系
应改源文件content/search-copy.mjs,但已有用户改动git status + 导入关系
生成物public/search.html,只能由构建更新生成标记 + build 脚本
验证npm run build;npm run verify:search;npm run verify:footerpackage.json scripts
未知项现有两处修改是否属于同一任务,需用户确认后才能编辑git diff 尚未获授权处理
最小代码现场

从源文件改一处文案,再确认生成物确实跟着变化

下面是教学仓库的最小 diff,用来说明怎样把页面现象、内容源和生成结果连起来。它不是当前项目的实际改动;真实接手时要替换成当前仓库的路径和命令。

git diff

源文件与生成物边界

diff --git a/content/search-copy.mjs b/content/search-copy.mjs
@@
- emptyTitle: "暂无数据"
+ emptyTitle: "没有找到匹配结果,请换一个关键词"

$ npm run build
$ npm run verify:search
通过:public/search.html 的 data-search-empty 与源文案一致

如果 diff 显示生成目录被直接编辑,先停下来追回源文件;如果验证命令不存在,保留原始错误,不凭经验补命令。

常见失败

项目地图看起来完整,仍可能在三处误导后续修改

把 public/search.html 列为编辑入口

原因
只按页面文件名判断,没有寻找生成标记和构建脚本。
怎么改
追到数据源与渲染函数,生成物只列为受影响输出。

给出 npm test,但 package.json 没有这个脚本

原因
用技术栈经验替代仓库事实。
怎么改
命令必须逐字来自项目清单、CI 或文档;不存在就写未找到。

地图没提到未提交改动

原因
跳过 git status,后续很可能覆盖别人的工作。
怎么改
把每个重叠文件标成风险,编辑前先读 diff 并取得范围确认。

读了全仓库仍说不清这次改哪里

原因
按目录平均浏览,没有从具体状态或报错追调用链。
怎么改
回到唯一文案、选择器、路由或错误,从入口逐跳记录证据。
验收方式

允许修改前,项目地图必须通过这六项检查

实际仓库现场

从一个页面文案追到路由、源文件、生成器和校验命令

线索实际发现证据未知项
URL/knowledge/visual/product-images/v09.html本地浏览器可打开生产缓存是否同步
唯一文案服装图先确认版型和颜色容许误差rg 命中 recipe 源文件是否还有旧版页面
生成入口scripts/build-stage-b.mjs --only=knowledge-v2package.json 与构建输出其他站区是否共用模板
验收verify:knowledge-v2-content、verify:footer脚本输出 237 页 / 0 issue浏览器真实用户路径需抽查
停止条件

找不到生成源时不直接编辑 HTML

本页依据

规则发现和工作区判断回到官方文档核对