Node.js Agent Handoff 仓库扫描 MVP：忽略规则、include 通配与稳定输出实现

适用范围

本文对应 Agent Handoff M1（仓库扫描 MVP），运行环境为 Node.js 20+，实现采用 ESM 和 Node.js 内置模块，不依赖第三方包。

M1 的目标不是生成代码，而是扫描本地项目并输出：

.agent-handoff/REPO_MAP.md：目录树、统计、忽略路径和警告；
.agent-handoff/manifest.json：文件清单和生成信息。

当前测试结果：npm test 15 项通过，0 失败。

一、CLI 入口

bash 复制代码

node bin/agent-handoff.js /path/to/project

省略项目路径时默认扫描当前目录。CLI 还提供：

bash 复制代码

node bin/agent-handoff.js --help
node bin/agent-handoff.js --version

帮助和版本返回 0；不存在路径、文件路径和未知参数返回 2。

二、扫描结果结构

扫描器返回一个结构化对象：

javascript 复制代码

{
  root,
  files,      // relPath、type、size
  skipped,    // relPath、reason
  warnings,   // relPath、message
  stats,      // 文件、目录、链接、大小、扩展名统计
  config
}

文件类型至少区分 file、dir、symlink 和 other。所有列表最终按 relPath 排序，避免文件系统遍历顺序变化导致报告抖动。

三、默认忽略与配置覆盖

默认忽略包括：

text 复制代码

.git、node_modules、dist、build、coverage
.venv、venv、__pycache__、.cache、.pytest_cache
.tmp、tmp、日志、*.pyc、*.pyo 等

项目根目录可放置 .agent-handoff.json：

json 复制代码

{
  "ignore": ["generated", "*.tmp"],
  "include": ["node_modules/lodash/index.js"]
}

ignore 在默认规则上追加；include 优先级高于默认忽略和祖先忽略，但只恢复匹配路径，不等于把整个被忽略目录全部打开。

四、被忽略父目录的 include 穿越

普通的路径命中很容易实现，难点在于父目录先被忽略时，扫描器不能提前剪枝。例如：

json 复制代码

{ "include": ["node_modules/*/index.js"] }

扫描 node_modules 时，需要判断其下面是否"可能存在"匹配目标。当前实现将路径模式拆成段，用递归匹配 *（单段）和 **（跨段）：

javascript 复制代码

function couldMatchUnder(pattern, dirRelPath) {
  const patSegs = pattern.split('/');
  const dirSegs = dirRelPath.split('/');
  return underRec(patSegs, 0, dirSegs, 0, new Set());
}

判断结果只用于决定是否继续向下遍历；真正把文件加入 files 前，仍然要再次执行完整的 include 匹配。因此：

node_modules/lodash/index.js 可以恢复；
node_modules/*/index.js 可以恢复多个匹配目录下的目标文件；
node_modules/other/x.js 不会因为进入目录而自动恢复。

这是一种"必要时穿越、命中时收录"的两阶段策略。

工具会在项目根目录写入 .agent-handoff。如果它在下一次扫描中进入 files 或 skipped，重复运行结果就会变化。因此扫描时只对相对路径精确等于 .agent-handoff 的目录做静默排除：

javascript 复制代码

if (relPath === RESERVED_OUTPUT_DIR) {
  continue;
}

不能使用 basename === '.agent-handoff'，否则真实项目中的 packages/real/.agent-handoff 也会被误吞掉。

六、特殊文件和边界处理

符号链接使用 lstat，记录链接本身，不跟随目标；
超过 10 MB 的文件只记录大小并产生警告，不读取文件内容；
realpath 和目录读取失败会写入 warnings；
真实路径集合用于防止循环目录；
配置 JSON 无法解析时保留默认忽略，并记录 configError。

M1 明确不负责敏感字段脱敏、技术栈识别和 Git 状态，这些能力分别属于后续里程碑。当前版本也保留一个边界：纯文件名 include（例如 *.log）不会触发被忽略父目录的深入遍历，锚定路径模式才会执行祖先穿越。

七、测试覆盖

bash 复制代码

npm test

15 项测试覆盖：Node.js、Python、无 Git 夹具，默认忽略与配置覆盖，重复运行，路径通配符 include，根级/嵌套 .agent-handoff，符号链接，超大文件，错误配置，以及接力包输出。

八、为什么先做扫描，再做 Agent 总结？

仓库地图是事实层，Agent 总结是解释层。事实层如果不稳定，后面的技术栈识别、Git 状态和任务总结都会建立在错误输入上。

因此 M1 的工程重点不是页面效果，而是：

输出是否可重复；
忽略边界是否可解释；
include 是否只恢复目标；
异常是否记录而不是静默失败。

M1 验收通过后，M2 才会继续增加 Node.js、Python、Go、Rust 技术栈识别、启动/测试命令提取和 Git 状态报告。

#Node.js #AI编程 #Agent #代码扫描 #软件工程

Node.js Agent Handoff 仓库扫描 MVP：忽略规则、include 通配与稳定输出实现

适用范围

一、CLI 入口

二、扫描结果结构

三、默认忽略与配置覆盖

四、被忽略父目录的 include 穿越

五、根级输出目录与嵌套同名目录

六、特殊文件和边界处理

七、测试覆盖

八、为什么先做扫描，再做 Agent 总结？