企业官网建设流程全解析

REA 这套东西第一次出现在我视野里，是因为一个很具体的场景：手头有一批自家设备导出的数据目录，层级混乱、命名没有规律、还夹着一堆未知格式的附属文件，需要把它们还原成一张可查询的结构表。市面上的成品工具要么把逻辑全封在图形界面里，改一个字段映射都费劲；要么只解决单一格式，剩下的还得自己写胶水代码。后来有人丢给我一个 npm 包名——rea-agents，说这套链路的编排层是开源的，真正干活的分析引擎在本地跑。

于是就有了这次拆解。我把整套东西分成两段看：一段是rea-agents 这套 agent 编排包，负责把任务拆解、参数校验、上下文传递做完；另一段是本地分析引擎，负责真正的解析、索引和规则匹配。中间靠一层极简的进程间协议连接。这篇文章会从包结构一路讲到引擎骨架，重点放在“为什么这样设计”和“联调时那些不报错但结果不对”的地方。适合已经能跑通示例、想把整条链路吃透并且落地成日常工具的人看。基础一般也没关系，我会把每个环节的动机讲清楚。

1. rea-agents 的定位：它是编排层，不是解析器

1.1 从“全家桶”这个词说开去

标题里用了“全家桶”，这个词容易让人误以为装一个包就能把所有事情干完。实际情况恰恰相反：rea-agents 的设计哲学是尽量少做事。它不做二进制解析，不做特征匹配，不做索引落盘，它只做三件事——把一次分析任务拆成若干个可独立执行的 agent 调用、维护这些调用之间的上下文、把结果聚合成调用方需要的形状。

这个定位如果没搞清楚，后面会非常痛苦。我见过有人直接去翻 rea-agents 的源码找“解析某某格式”的实现，翻了半天发现根本没有，然后得出结论说这个包是空壳。它不是空壳，它是把重活外包出去了。用个生活化的比喻：它是餐厅的前厅和服务流程，负责接单、分单、传菜、上菜；后厨那口锅在本地引擎那边。前厅再豪华，菜还是后厨炒的。

这个切分带来的直接好处是可替换性。想把解析核心从 A 语言换到 B 语言，只要协议不变，编排层一行代码都不用改。反过来，想加一个新的分析步骤，也只需要写一个新的 agent 并注册进去，不用碰引擎。这是典型的“变的部分和不变的部分分开”。

代价也很明确：两段之间的边界一旦设计得不好，调试成本会翻倍。因为你看到的错误现象在 A 端，根因可能在 B 端，中间还隔着一层序列化。这也是为什么第 4 节我花了整整一章讲静默失败。

1.2 编排层与执行层的能力边界

把边界画清楚，最好用一张表。下面这张表是我根据实际使用和翻阅源码整理出来的职责划分，不是官方文档原文，但基本能覆盖日常遇到的所有情况。

看清这张表之后，很多困惑就自然消解了。比如你想调整索引的分片大小，去改 agent 的参数是没用的，那是引擎侧的配置；你想让输出多带一个字段，去改引擎反而绕远了，agent 层聚合的时候加就行。

我个人的经验是：遇到问题先判断它属于哪一栏。属于左栏的问题，改 JS 代码、看 Node 日志；属于右栏的问题，改引擎配置、看引擎日志。判断错了方向，能在原地打转一整天。

提示：不要试图让编排层去“顺手”做一点解析。短期看省事，长期看会把两层的耦合做死，后面换引擎或者换协议时全是坑。

1.3 一个反直觉的建议：先别急着读源码

大多数人拿到一个陌生的包，第一反应是 clone 下来从头读。对 rea-agents 这类编排框架，我不建议这么做。原因是它的源码里充斥着大量的抽象和类型体操，读起来进度极慢，而且读完了你也不知道它实际跑起来是什么样。

更高效的路子是从运行痕迹反推。具体做法是：把示例跑起来，打开 debug 级别的日志，看它依次调用了哪些 agent、每个 agent 收到的入参长什么样、返回的结构是什么形状、上下文对象在调用之间保留了什么。跑两三个不同的任务之后，你对这套框架的理解会比读一周源码还扎实。

我当时的做法是写了一个极简的“探针 agent”，它什么都不做，只是把收到的 ctx 和 input 原样打印出来然后返回。把它插到链路中间，前后各放一个，就能看清上下文是怎么流转的。这种做法在调试任何插件式框架时都好使，成本极低，收益极高。

等你对运行时行为有了直觉，再去读源码，会发现那些抽象突然都变得合理了——因为你已经知道它们在解决什么问题。顺序反过来，就是纯粹的自虐。

2. 拆包：从 package.json 到 agent 注册表

2.1 exports 字段暴露出来的模块边界

判断一个 npm 包的内部结构，最快的入口不是 README，是package.json的exports字段。作者愿意把哪些路径暴露出来，等于在告诉你“哪些是给外部用的、哪些是内部实现别碰”。rea-agents 的导出大致是这样的形状：

{ "name": "rea-agents", "type": "module", "main": "./dist/index.cjs", "exports": { ".": { "import": "./dist/index.js", "require": "./dist/index.cjs" }, "./agents": "./dist/agents/index.js", "./registry": "./dist/registry.js", "./protocol": "./dist/protocol/index.js" }, "bin": { "rea": "./bin/rea.js" } }

四个导出路径，信息量其实很大。.是主入口，通常导出run、createPipeline这类高层 API；./agents是内置 agent 的集合，说明作者预期你会单独引用某个 agent；./registry单独暴露，说明注册机制是可扩展的，你要写自定义 agent 就得用它；./protocol暴露协议层，意味着你可以绕过内置的传输实现，自己接一套通信方式。

同时type: "module"加main指向 cjs，说明这是一个双格式发布的包。这一点在实战中很关键：如果你的项目是 CommonJS 且用了动态require，某些深层路径可能会加载失败，报的是ERR_REQUIRE_ESM之类看起来莫名其妙的错。我的建议是统一用 ESM 接入，Node 版本不低于 18，能省掉大量边界情况。

bin字段说明它还带了个命令行入口。这个入口在排查问题时特别好用——GUI 或 SDK 调用出问题时，先用 CLI 跑一遍同样的任务，能快速区分是“引擎的问题”还是“你的调用代码的问题”。

2.2 注册表与能力声明：为什么要有这一层

rea-agents 里每个 agent 都需要声明自己的元信息，大致长这样：

// 一个典型 agent 的声明形状 export const scanAgent = { id: 'scan', version: '0.3.1', capabilities: ['fs.walk', 'hash.sha256'], inputSchema: { root: { type: 'string', required: true }, depth: { type: 'number', default: 8 }, followSymlink: { type: 'boolean', default: false } }, async run(ctx, input) { // ctx 提供 logger / engine / cache / signal // input 已经过 schema 校验和默认值填充 } }

capabilities这个字段值得单独说。它不是装饰性的，注册表会用它来做依赖解析和冲突检测。举个例子，如果你注册了两个都声明hash.sha256的 agent，但实现不同（一个用 Node 内置 crypto，一个调引擎侧的实现），注册表在初始化阶段就能发现并告警。这个机制在多人协作时非常有用，能避免“同一个任务在不同机器上跑出不同结果”这种最难查的问题。

inputSchema也不只是为了文档。它承担了默认值填充和类型收敛的工作。我踩过一个坑：某个参数声明成number，我在调用时传了字符串"8"，编排层没有做强转，直接透传给了引擎，引擎侧用严格类型断言，报了一个跟参数名完全对不上的错。后来我把所有参数在调用前手动收敛一遍，问题消失。这个教训是：schema 是契约，不是转换器，别指望它帮你做类型体操。

注册的动作本身很简单，一般在入口处调一次：

import { createRegistry } from 'rea-agents/registry' import { scanAgent } from 'rea-agents/agents' import { myCustomAgent } from './agents/custom.js' const registry = createRegistry() registry.register(scanAgent) registry.register(myCustomAgent, { override: true })

override这个选项要慎用。它能覆盖同名 agent，很方便，但也意味着一旦有人误用，行为就静默改变了。我的做法是在 CI 里加一条检查：启动时打印最终注册表里所有 agent 的 id 和 version，落到日志里，出问题时一对时间戳就知道当时跑的是哪个版本。

2.3 上下文对象的序列化边界

上下文（ctx）是整套编排的核心抽象，也是最容易出问题的地方。它一般包含这几样东西：

• logger：带 taskId 的结构化日志器
• engine：指向本地引擎的客户端，封装了协议调用
• cache：跨 agent 共享的键值存储
• signal：取消信号，用于中断长任务
• state：本次任务的中间状态

关键在于，state里放什么是有讲究的。只放可序列化的数据，这是铁律。我见过有人在 state 里塞了一个打开的 socket 或者一个类实例，单进程跑得好好的，一换成 worker 模式或者一加上持久化就炸。原因很简单：跨进程边界的时候，这些东西没法传。

更深一层的问题是大对象放不放 state。直觉上放进去方便，下一个 agent 直接拿来用。但如果这个对象是几百 MB 的缓冲区，它会一直占着内存不释放，而且每次跨边界传递都要复制一次。我的经验是设置一个阈值，比如单个对象超过 8MB 就不要进 state，改成写临时文件，state 里只存路径。这个改动看着麻烦，但在处理大批量样本时，内存曲线会从“锯齿状爬升”变成“平稳”。

还有个隐蔽的坑：state 里放了可变引用，下游 agent 修改了它，上游还在用。这种情况在异步并发时特别容易出事。稳妥的做法是约定 state 只增不改，每次写入用一个新的键，或者干脆在写入前做一次浅拷贝。这条约定写进团队规范，能省掉大量“数据明明是对的为什么结果不对”的排查。

3. 本地分析引擎：协议、索引与缓存

3.1 为什么是 stdio 上的 JSON-RPC，而不是本地 HTTP

这套链路最常见的通信方式是：编排层用child_process.spawn拉起引擎进程，通过 stdin 写请求、stdout 读响应，每行一条 JSON。第一次看到这个设计的人经常会问：为什么不直接起个本地 HTTP 服务，用起来不是更直观吗？

理由有三个，都很实在。

第一是生命周期绑定。stdio 模式下，引擎是编排层的子进程，编排层退出，子进程自动收到 EOF 然后退出，不会留下僵尸进程占着端口。HTTP 服务就不一样了，进程崩了端口可能还被占着，下次启动直接EADDRINUSE，运维上很烦。

第二是没有端口冲突。多实例并行跑的时候，stdio 天然隔离，每个实例一对管道，互不干扰。HTTP 就得动态分配端口，还要处理分配冲突和端口回收。

第三是启动开销。管道建立是瞬时的，HTTP 服务要监听、要握手，虽然单次差别不大，但如果你的使用模式是“跑一次就退出”，累积起来差距明显。

代价当然也有。stdio 模式没有请求路由，多路复用要自己做；没有内建的背压控制（其实有，但需要正确处理）；调试时不能直接用浏览器或 curl 打。所以我的做法是：生产链路走 stdio，调试时额外开一个 HTTP 适配层，两者共用同一套 handler 实现。这样既拿到了 stdio 的好处，又不失去调试便利。

协议帧的处理有个细节要注意。用 JSON Lines（每行一条完整 JSON）比用 Content-Length 头简单，但要求序列化时必须把内部换行转义掉。JSON.stringify默认就会转义换行符，所以正常情况没问题；但如果你为了性能用了自定义的序列化，或者手动拼字符串，就容易漏。漏了的后果是引擎把一条消息当成两条解析，报一个位置完全不对的语法错误。

// 编排层侧的调用封装，注意 backpressure 处理 import { spawn } from 'node:child_process' import { createInterface } from 'node:readline' export function createEngineClient(binPath, args = []) { const child = spawn(binPath, args, { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true }) const pending = new Map() let seq = 0 const rl = createInterface({ input: child.stdout }) rl.on('line', (line) => { if (!line.trim()) return let msg try { msg = JSON.parse(line) } catch (e) { // 解析失败说明帧被破坏，直接把原始行打出来方便定位 console.error('[engine] bad frame:', line.slice(0, 200)) return } const resolver = pending.get(msg.id) if (!resolver) return pending.delete(msg.id) if (msg.error) resolver.reject(new Error(msg.error.message)) else resolver.resolve(msg.result) }) child.stderr.on('data', (buf) => { // 引擎的日志走 stderr，不要混进 stdout process.stderr.write(buf) }) function call(method, params, { timeout = 30000 } = {}) { const id = ++seq return new Promise((resolve, reject) => { const timer = setTimeout(() => { pending.delete(id) reject(new Error(`engine timeout: ${method} (${id})`)) }, timeout) pending.set(id, { resolve: (v) => { clearTimeout(timer); resolve(v) }, reject: (e) => { clearTimeout(timer); reject(e) } }) const ok = child.stdin.write(JSON.stringify({ id, method, params }) + '\n') if (!ok) { // 管道写满时等待 drain，避免消息被截断 child.stdin.once('drain', () => {}) } }) } return { call, close: () => new Promise((r) => { child.once('exit', r) child.stdin.end() }) } }

上面这段代码里，child.stdin.write的返回值判断是最容易被省略、也最容易出问题的一行。写入量小的时候永远返回 true，一旦单条消息超过管道缓冲区（Linux 上通常 64KB），就会返回 false，此时不处理背压继续写，消息就可能被截断或者顺序错乱。这个问题在本地跑小样本时完全不会暴露，一上大批量就集中爆发。

3.2 两级索引：粗筛与精定位

引擎侧最核心的数据结构是索引。我见过的实现大多采用两级结构，这个设计不是拍脑袋来的。

第一级是粗筛桶，按文件类型或魔数分类。目的是快速排除明显不相关的样本，把候选集从几万个缩到几百个。这一级的判断必须极快，通常只看文件头的前若干个字节，不读全文件。实现上就是一张特征码表，查找复杂度 O(1)。

第二级是精定位表，记录每个样本内部的结构偏移。比如某个字段在第几个块的第多少字节开始、长度多少、编码是什么。这一级的数据量比第一级大两个数量级，所以通常不常驻内存，而是按需加载或者用内存映射。

两级之间靠一个稳定的样本 ID 关联。这个 ID 一般用内容哈希，而不是路径。原因很实际：同一份内容可能出现在不同路径下，用路径做 ID 会导致重复索引；而路径会变，内容不会。

设计上有个权衡点值得说：第二级索引是构建时全量生成，还是查询时按需生成。全量生成的好处是查询快，坏处是首次构建慢、占用磁盘多；按需生成反过来。我的选择是混合——常用字段全量生成，冷门字段按需，并且把按需生成的结果缓存下来。判断冷热的标准很简单：看最近 N 次查询里哪些字段被访问过。

这套逻辑落到参数上，就是几个可调项：

这些值不是绝对的，跟样本规模、磁盘类型、查询模式都有关。但如果你完全没概念，从上表起步，再根据实测调整，比从零猜要快得多。

3.3 缓存键的设计与失效策略

缓存这事，做对了收益巨大，做错了就是“明明改了代码结果没变”的噩梦源头。核心在于缓存键的设计。

一个能用的缓存键至少要包含四个维度：内容哈希、agent 版本、引擎版本、参数摘要。少任何一个都会出问题。

只放内容哈希，改了 agent 逻辑但缓存没失效，你拿到的是旧结果；只放内容哈希加 agent 版本，升级了引擎（比如修正了某个解析 bug）缓存还是旧的；参数摘要漏了，改了depth或者followSymlink这种影响结果的参数，缓存依然命中。

实现上我建议把这四项拼成一个字符串再做一次哈希，作为最终的 key：

import { createHash } from 'node:crypto' function buildCacheKey({ contentHash, agentId, agentVersion, engineVersion, params }) { // 参数要排序后序列化，保证键的稳定性 const stableParams = JSON.stringify(params, Object.keys(params).sort()) const raw = [contentHash, agentId, agentVersion, engineVersion, stableParams].join('|') return createHash('sha1').update(raw).digest('hex') }

那个“排序后序列化”是必须的。JSON 对象的键顺序在 JS 里虽然一般稳定，但跨语言序列化时不保证，而且不同代码路径构造出来的对象顺序可能不同。不排序的话，同样的参数会算出不同的键，缓存命中率直接腰斩。

失效策略上，我倾向不做主动失效，只做版本号推进。也就是升级时手动改版本号，旧缓存自然变成孤儿，定期清理。主动失效（比如监听文件变化去删缓存）看着聪明，实际会引入一堆竞态，收益不抵成本。

还有一点：缓存要设上限。我见过因为缓存目录无限增长把磁盘写满的情况。简单的做法是按总量做 LRU，超过阈值就删最久未访问的。这个逻辑不复杂，但一定要有。

4. 联调阶段四类静默失败的真实排查链路

这一节是全文我最想写的部分。前面那些设计讲得再清楚，真正让人熬夜的都是“程序没报错但结果不对”。下面四类问题我都实际遇到过，把排查链路完整还原出来，方便你按图索骥。

4.1 退出码是 0，结果却是空的

这是最经典的一种。你跑一个任务，进程正常退出，退出码 0，日志里没有任何 ERROR，但输出是空数组。

我的排查顺序是这样的：

第一步，确认请求到底有没有发出去。在编排层的call函数里加一行日志，打印方法名和参数摘要。如果这行没打出来，说明问题在你的业务代码，根本没走到调用；如果打出来了但引擎侧没反应，那就是传输层的问题。

第二步，看引擎侧有没有收到。引擎的入口一般是一个读 stdin 的循环，在这个循环的第一行加日志，把收到的原始字节数打出来。这里有个高频原因：stdin 没有被正确关闭，引擎在等 EOF。有些引擎实现是“读到 EOF 才开始处理”，如果你的编排层写完请求后没有end()，引擎就一直等。现象就是进程挂着不退出，或者被上层超时杀掉返回空。

第三步，如果引擎收到了也处理了，检查 stdout 有没有被 flush。Node 里process.stdout.write在管道模式下是异步的，进程如果立刻退出，缓冲区里的内容可能丢失。修法是在退出前等一次回调，或者用process.exitCode而不是process.exit()。

第四步，检查结果聚合那一步。有时候引擎返回了数据，但 agent 的聚合函数里有个条件判断把它过滤掉了。这种情况最容易漏，因为每一步单看都正常。我的做法是在聚合前后各打一次数组长度，长度对不上就说明过滤逻辑有问题。

这四步走完，绝大多数“空结果”都能定位。如果还没有，那就上 strace 或者类似的系统调用跟踪，看看到底卡在哪个 read 上。

4.2 大 payload 被悄悄截断

小样本跑得好好的，换成一个稍大的文件，结果就少了一截。没有异常，没有警告，就是数据不全。

根因通常有两个。第一个是管道缓冲区背压没处理，前面 3.1 节已经提过，write返回 false 时继续写会导致数据丢失。第二个是读取端用了固定大小的缓冲区，比如readline在某些配置下对超长行有限制，或者引擎侧用了read(1024)这种定长读。

验证方法很直接：把同一个 payload 从 1KB 开始，每次翻倍，一直试到 100MB，看哪个尺寸开始出问题。这个二分过程很快，能精确定位到阈值。定位到之后，对照 64KB、1MB 这些常见缓冲区大小，基本就能猜到是哪里。

修法上，发送端要正确处理背压：

async function writeLine(stream, obj) { const line = JSON.stringify(obj) + '\n' if (!stream.write(line)) { await new Promise((resolve, reject) => { stream.once('drain', resolve) stream.once('error', reject) }) } }

接收端则要考虑分块读取再拼接，而不是假设一次 read 就是一条完整消息。

还有一个更隐蔽的情况：消息本身没问题，是序列化时被截断了。比如你在对象里放了一个 Buffer，JSON.stringify会把它变成{"type":"Buffer","data":[...]}，体积膨胀好几倍；如果中间有环节做了长度限制，就会静默截断。我的建议是大二进制数据一律走临时文件或者 base64 之外的独立通道，不要塞进 JSON。

4.3 并发下的结果错位

串行跑一切正常，一开并发，结果就开始串。A 任务的结果出现在 B 任务的输出里，或者同一个任务的部分结果丢失。

第一个要查的是共享可变状态。编排层的 ctx 如果被多个并发任务共用，里面的 state 就会互相污染。这个错误很常见，因为 ctx 通常是在 pipeline 创建时生成一次，然后传给所有任务。修法是每个任务创建独立的子 ctx，公共的只读部分用原型链或者浅拷贝继承。

第二个要查的是异步遍历的写法。array.forEach(async ...)是最经典的陷阱，它不会等待，所有回调同时启动，然后函数立刻返回。你以为拿到了完整结果，实际上拿到的是空数组或者部分结果。改用for...of加await，或者Promise.all配合map。

第三个要查的是响应的 id 匹配。前面 3.1 的代码里用了pending这个 Map 来管，如果 id 生成有重复（比如用了时间戳），并发时就会张冠李戴。用自增序号最稳妥。

第四个是引擎侧的状态残留。如果引擎在两次请求之间没有清理临时文件或者内存里的状态，并发时就会互相干扰。判断方法是在引擎侧每个请求处理前后各打一次状态快照，对比是否干净。

排查这类问题的通用手法是：给每个任务一个唯一 traceId，从编排层一路透传到引擎日志，然后按 traceId 过滤日志，看单个任务的完整轨迹。这一步做完，错位问题基本一目了然。

4.4 编码与路径：跨平台时的高发区

同一份代码，在 Linux 上跑得好好的，拿到 Windows 上就各种找不到文件或者乱码。

路径问题有两层。第一层是分隔符，反斜杠在 JSON 字符串里是转义符，直接拼进消息里会变成非法 JSON 或者被吃掉。稳妥做法是内部统一用正斜杠，只在真正调系统 API 前转换，或者直接用path.join生成，序列化时它会变成\\，反序列化后恢复，不会丢。

第二层是大小写敏感性。Linux 上Foo和foo是两个文件，Windows 上是一个。如果索引里用路径做键，跨平台迁移时可能命中错误条目。这也是我前面强调用内容哈希做 ID 的原因之一。

编码问题更麻烦一些。文件名如果不是 ASCII，在不同系统上的表示可能不同（比如某些系统用 NFC 归一化，某些用 NFD）。表现是同一个文件，用肉眼看着一样的名字去读，读不到。修法是在读取前做一次 Unicode 归一化，统一成 NFC：

function normalizeName(name) { return name.normalize('NFC') }

如果是文件名本身存的是非 UTF-8 编码（在一些老系统上很常见），Node 读出来会是乱码。这种情况需要用 Buffer 读取原始字节，再用对应的编码解码。判断依据是：打印Buffer.from(name, 'utf8')和实际字节对比，对不上就说明有编码转换。

我的做法是在扫描阶段就把所有文件名统一处理一遍，归一化加原始字节备份，后面的环节只用处理过的版本，避免问题在不同模块里反复出现。

5. 从能跑到好用：吞吐、内存与可观测性

5.1 批处理粒度怎么定

跑通 Demo 之后，第一个要调的就是批处理粒度。粒度太小，进程间往返开销占比高；粒度太大，单个任务失败影响范围大，内存峰值也高。

我的经验是分两步定。先测单条处理耗时，再测一次往返的固定开销（大致就是 spawn、序列化、IPC 的时间）。如果固定开销占到单条总耗时的 10% 以上，就应该合并批处理；低于 1%，就没必要折腾。

实际数值上，本地引擎的往返开销通常在几毫秒量级，单条处理如果是几十毫秒，那批量设在 10 到 50 条之间比较合适。设得更大收益递减，反而增加内存和失败重试的成本。

还有个细节：批次内要允许部分失败。如果一批 50 条里有一条格式不对导致整批回滚，效率就崩了。正确做法是引擎侧逐条捕获异常，把失败的那条单独返回错误信息，其它正常返回。编排层拿到 mixed 结果后决定是重试还是跳过。

5.2 内存峰值的三个来源

跑大批量时最怕 OOM。以我的观察，峰值通常来自三个地方。

第一个是待处理数据的持有。如果你一次性把所有样本读进内存再分发，峰值就是全量数据的大小。改成流式读取、边读边发，峰值就降到批大小乘以单条大小。

第二个是索引常驻。第二级索引如果全量加载，几万个样本就是几个 GB。用内存映射或者按需加载能压下来，代价是查询稍慢。这个取舍要看你的查询模式，如果是少量多次，常驻划算；如果是一次性跑完就退出，按需更好。

第三个是缓存无上限。前面提过，缓存不设上限就是等着爆。除了磁盘上设上限，内存里的热缓存也要设，用 LRU 或者带 TTL 的 Map。

监控上，我习惯在每批处理前后打一次process.memoryUsage()，记录 heapUsed 和 external。external 增长快但 heapUsed 平稳，通常是 Buffer 没释放；两个都涨，可能是对象引用没断开。这种粗粒度的观测成本极低，但能提前发现趋势。

5.3 日志与 trace 的最小集合

可观测性这事容易走两个极端：要么什么都不打，出问题两眼一抹黑；要么什么都打，日志几十个 G 没人看。

我认定的最小集合是四项：traceId、阶段名、耗时、结果状态。有这四项，任何一个任务都能被完整还原。traceId 从编排层生成，透传到引擎，所有日志都带上；阶段名标识当前在做什么，比如scan、index、extract；耗时用于发现性能退化；结果状态用于快速统计成功率。

实现上不需要引入重型框架，一个几十行的 logger 就够：

function createLogger(traceId, sink = console) { const start = Date.now() return { span(stage, fn) { const t0 = Date.now() return Promise.resolve() .then(fn) .then((r) => { sink.error(JSON.stringify({ traceId, stage, ms: Date.now() - t0, ok: true })) return r }) .catch((e) => { sink.error(JSON.stringify({ traceId, stage, ms: Date.now() - t0, ok: false, msg: e.message })) throw e }) }, total: () => Date.now() - start } }

注意这里日志输出到 stderr，不是 stdout。stdout 被协议占用，混进日志会直接破坏帧格式，这是新手最常犯的错误之一。

另外，日志里不要把完整路径和完整内容打出来。路径可能很长，内容可能是二进制的乱码，都会把日志撑爆。打摘要就够了，比如取哈希的前 8 位，需要详情时再用哈希去查。

最后再分享一个小技巧。这套链路我现在的用法是：日常跑的时候用一个极薄的 wrapper 脚本，它只做三件事——读配置、起引擎、把 traceId 打到终端标题栏。看起来不起眼，但当你同时开五六个终端跑不同任务时，能一眼看出哪个窗口在跑什么，省下的时间比想象中多。真正的分析逻辑全部沉在 agent 和引擎里，wrapper 永远不改，这样升级组件时不用动它，反过来也一样。