浏览 AI 知识库
第一次打开陌生仓库,先找规则、入口、构建和测试命令
用一个真实形态的 Node.js 内容站任务演示:先保护未提交改动,再从页面文案追到路由、数据源和生成命令,最后交付带路径、命令与未知项的项目地图。
从案例现场看到最终结果
先看真实输入和失败现场,再跟着处理过程核对中间结果与最终输出。
任务只有一句“把搜索空状态改清楚”,仓库里却有 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 | 只记录仓库真实存在的命令 |
| 当前权限 | 只读审查 | 不安装依赖、不运行部署、不编辑文件 |
案例路径和输出为教学样例,但工作方法可直接用于真实仓库。真实执行时必须替换成当前项目的实际状态。
五条命令足够把搜索范围从全仓库收窄到一个功能链
从仓库根目录运行。任何命令不存在或失败时保留原始错误,不把“工具缺失”误判为“项目损坏”。
规则、状态、文案和真实脚本
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 追踪。
沿页面状态、渲染函数、内容源和构建命令走一遍
- 01
确认页面状态
浏览 search.html 的空结果分支,确认目标是 data-search-empty,而不是首次进入、加载中或请求失败。
证据:页面状态选择器与触发条件。 - 02
定位渲染函数
在 build-site.mjs 找到 renderSearchEmptyState,记录它读取的字段和输出位置。
证据:函数名、导入和调用行。 - 03
确认唯一内容源
emptyState 来自 content/search-copy.mjs;public/search.html 带生成标记,因此不直接编辑输出。
证据:导入关系与生成文件头。 - 04
读取验证入口
verify:search 检查空状态字段和 DOM 标记;build 会重写 public/search.html;verify:footer 只做回归,不授权改 Footer。
证据:package.json 的实际 scripts。 - 05
划定影响范围
预计只改内容源并重新生成搜索页;现有未提交差异要逐行保留,具体编辑仍等待用户确认。
证据:git diff 与生成清单。
让编程 Agent 先画仓库地图,不要一上来改代码
适合第一次打开陌生项目时使用,目标是找到规则、入口和验证命令。
让编程 Agent 先画仓库地图,不要一上来改代码
只读调查这个仓库里与【功能/报错】直接相关的部分。不要先改代码,也不要仅凭目录名推断职责。 仓库根目录【】;我要理解的功能/错误【】;允许执行的只读命令和现有验证【】。 从适用的项目规则和 Git 状态开始。用唯一文案、路由、命令或符号追踪:用户入口 -> 调用链 -> 真正读写逻辑 -> 输出。确认源文件/生成物边界、现有测试以及仓库实际定义的启动和构建命令。 每个结论附路径、符号或命令原始输出;没有证据写“未定位”。交付项目地图、相关文件清单、建议的最小验证顺序、风险和未知项后停止。不要编辑文件、安装依赖、访问无关目录或把未运行的命令写成已验证。
使用范围:适合第一次打开陌生项目时使用,目标是找到规则、入口和验证命令。本轮不修改文件、不安装依赖、不运行会改变外部状态的命令。
交付的不是目录树,而是一张能指导下一步的项目地图
| 项目地图字段 | 案例结论 | 依据 |
|---|---|---|
| 规则 | 根目录 AGENTS.md 适用;生成页不可手改;Footer 不在范围内 | AGENTS.md |
| 功能入口 | search.html 的 data-search-empty 状态 | public/search.html + 状态逻辑 |
| 渲染路径 | emptyState -> renderSearchEmptyState() -> public/search.html | import 与调用关系 |
| 应改源文件 | content/search-copy.mjs,但已有用户改动 | git status + 导入关系 |
| 生成物 | public/search.html,只能由构建更新 | 生成标记 + build 脚本 |
| 验证 | npm run build;npm run verify:search;npm run verify:footer | package.json scripts |
| 未知项 | 现有两处修改是否属于同一任务,需用户确认后才能编辑 | git diff 尚未获授权处理 |
从源文件改一处文案,再确认生成物确实跟着变化
下面是教学仓库的最小 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-v2 | package.json 与构建输出 | 其他站区是否共用模板 |
| 验收 | verify:knowledge-v2-content、verify:footer | 脚本输出 237 页 / 0 issue | 浏览器真实用户路径需抽查 |
