自用 Agent 走向可移交：硬编码路径是第一批要拆的

2026-08-25

我自己搭了一个写公众号文章的 Agent，从收到链接或主题开始，一路走到分析素材、确认方向、确认提纲、核验资料、写正文、生成封面，最后把成果保存到本地。这套东西在我这台机器上跑了一段时间，我对质量基本满意。

后来我开始想一件事：这套流程如果不是只有我一个人用，还成立吗。一动这个念头，第一个卡住的不是模型、不是提示词、也不是哪一步判断依据写得不够细，而是一个我从来没觉得它是问题的东西——成果保存目录被写死成了我本机的绝对路径。下面写的是这一项的完整复盘。

现象：自用时它一次都没错过

这个 Agent 的交付物不是单独一篇终稿，而是一整个目录。目录里按顺序放着六个文件：原始链接与素材、备选方向与最终选择、确认后的提纲和主要观点、补充资料与引用来源、正文，以及封面图。每一个人工确认节点的输入和输出都单独落盘，闸门处的决定被固化成文件，而不是留在对话记录里。

这个设计我一直挺满意。它的副作用是：这六个文件全部挂在同一个根目录下面，那一个根路径是所有产物的共同前提。而它当时是一个常量，值就是我这台机器上的一串绝对路径。

自用状态下，这个常量永远为真。任务跑完，目录建好，六个文件老老实实躺在里面，我打开就能看。它从来没有报过错，也从来没有让任何一次运行失败过。在我关心的那些指标——正文有没有 AI 味、提纲能不能过删除测试、核心事实核没核过——里面，它一次都没出现过。

当时是怎么发现的：它不是跑出来的，是读出来的

这一段是我觉得整件事里最值得写的。

我那条线上其它几个坑，都是运行时自己撞出来的。封面文件名写着一种扩展名、文件头却是另一种格式，本地保存时不报错，要到接入下游接口之前才会暴露；确认提纲那一步，飞书上没显示出来，我得主动发一句「提纲我在飞书上没有看到，请显示出来」，流程才继续走；读一篇网页文章时浏览器 Daemon 启动失败，换用 curl 才拿到内容。这几件事的共同点是：它们都以「有东西不对劲」的形态出现过，我是被动接收到信号的。

硬编码路径这一条不一样。它不产生任何信号。

它是在我写使用说明书、整理一份已知问题清单的时候被列进去的。也就是说，发现它的动作不是运行，是阅读——是我坐下来把配置逐段读一遍，问自己「这一行换一台机器还成立吗」，才把它拎出来的。

这个发现方式我认为比问题本身更值得记住。一个设定如果在自用场景下永远不报错，那它就永远不会被测试发现，也不会被日志发现，更不会被 Agent 自己发现。它只能靠人主动读出来。而人愿意主动去读配置的时机，通常只有一个：当你打算把这套东西交给第二个人的时候。

换个说法：从自用走到可移交，缺的第一样东西不是文档、不是权限设计，而是有人肯把「我这台机器上碰巧成立的假设」一条条翻出来。硬编码路径只是这类假设里最显眼、最容易被抓到的那一条。

为什么会这样：它是唯一一条「本机为真」的假设

我事后想过，为什么偏偏是路径。

一部分原因在于它所处的位置。这个 Agent 的工序是被切开的，边界压在三类地方：需要人工确认的地方、产出物形态发生变化的地方、失败后回退目标不同的地方。「保存结构化成果」排在整条工序相当靠后的位置——方向确认过了，提纲确认过了，资料核验过了，正文写完了，封面也生成了，才轮到它。前面每一步都有明确的判断依据和失败回退，唯独最后这一步几乎没有判断可做：路径给定，写进去，完事。

正因为它简单到没有判断，它就没有被当成一个需要设计的环节。前面那些步骤我反复推敲过「什么情况下算做对了、什么情况下算做错了」，而落盘这一步我脑子里只有一个位置，因为在我这里它确实只有一个位置。

另一部分原因是它的失败形态。前面几个坑，失败都发生在我眼前：文件格式不对我能查出来，消息没送达我在等不到回复时会察觉，浏览器起不来会有明确的失败动作可以接降级。而写死的路径，换一台机器之后不成立，那个不成立发生在别人的机器上，不在我的视野里。我永远收不到这个反馈。

这两点叠加起来就成了一个盲区：位置在最末端、逻辑上最没有判断、失败在别人那边。所以它排到了第一位——不是因为它最难改，恰恰因为它最容易改，改起来就一行；而是因为在你真正开始考虑移交之前，没有任何一种机制会让你想起它。

改成了什么

改法本身很短：把默认目录从写死的本机绝对路径，改成环境变量或者 Profile 里的一个配置项。

我更在意的是这个改动带来的口径变化。改之前，「成果保存到哪里」是一个实现细节，藏在配置里，没人需要知道；改之后，它变成了一个必须由使用者提供的输入。这意味着我要在说明书里明确写出它是什么、不给会怎样、给错了会怎样。一个原本隐形的假设，被迫变成了一条对外可见的契约。

这也是我现在判断一项配置该不该外提的方式：看它在换人使用时是不是必须由对方决定。如果是，那它就不该以任何形式硬编码在流程内部，哪怕它在我这里从来只有一个取值。

可迁移的判断

我从这一次里带走的是这么一句：

自用 Agent 走向可移交，第一批要拆的就是硬编码路径。

它不是因为路径这个东西有多重要，而是因为它是「本机为真」这类假设的典型样本——在自用时零成本、零报错、零感知，在移交时全量失效。找到它，往往也就顺带找到了同一类的其它几条。

以及一条更一般的判断方式：**当你想知道一套自用流程离可移交还有多远时，不要去跑它，去读它。**跑多少次也跑不出这个问题，因为每一次跑的都是同一台机器、同一个人、同一组碰巧成立的前提。真正有用的动作是把配置和流程文档逐行读一遍，对每一处具体取值问一句「这个值凭什么是这个值」。答不上来的地方，就是下一条要拆的。

这篇写的是我自己那套流程里的一次实际情况，不是通行做法。你的场景、工具和团队规模不同，结论未必适用，判断方式可能比结论更值得拿走。