企业官网建设流程全解析

最近半年我在给团队做 Agent Harness 集成，逐步意识到一个有些反直觉的现象：我们正在把早先接好的向量数据库从主链路里拆出去，换成一组更朴素的能力——目录扫描、文件搜索、按需读取全文。刚开始团队里也有人反对，觉得“放弃语义检索，技术栈是不是倒退了”，但跑完一千多条真实业务任务的评测之后，结论压倒性逆转：在 Harness 的场景里，向量数据库的使用频率确实在下降，这不是因为技术过期，而是因为 Agent 时代的知识获取方式和过去完全不一样了。

这篇文章我会把我们的复盘思路完整写出来，包括为什么当初会上向量数据库、后来遇到了哪些阻力、现在用替代方案后的实际变化，以及什么情况下我依然会坚定地保留向量数据库。如果你正在做 Agent Harness、DeepSeek Harness 这类工具层的落地，或者你正在纠结知识检索到底该用向量还是该直接读文件，这篇会是很直接的参考。

1. 先分清两个概念：Agent 是大脑，Harness 是脚手架

1.1 我们说的“harness 工程”到底在管什么事

先对齐一下定义。这个词在圈里火的背景，是大家在用 Claude Code、DeepSeek Harness 这一类编码代理时发现：光有一个强大的模型还不够，真正决定边界和稳定性的，是外面这层“壳”。

业界有个流传比较广的说法——Agent 是判断和行动的实体，Harness 是包裹着 Agent 的那套工程框架，它负责管提示词结构、工具调用权限、任务状态、上下文生命周期、技能包加载这些杂活。打个比方：Agent 像一个短跑运动员，Harness 是赛道规划、教练指令、安全绳和补给站的总和。运动员本身再强，没有这套东西，冲刺方向就容易失控。

我们做的 Harness 项目，核心目标只有一个：让模型能在限定边界内稳定地完成任务，每一步关键决策都可追溯、可回滚、可解释。就这个目标而言，知识获取环节就一定绕不开一个灵魂问题：模型要用到的领域知识，到底怎么塞进上下文。

1.2 向量数据库为什么曾经是 Harness 的标配

Joe 在一年前我们画架构图时，知识这块几乎是条件反射式地画了一个向量库。原因很简单：当时 RAG 的教科书路径就是“文档切块 -> 嵌入 -> 相似度检索 -> 拼接上下文”。

这套链路在传统问答场景里确实是神器。假设用户问“公司今年第二季度在华东区的营收波动原因”，关键词检索基本抓瞎，因为问题里没有一个能查原文的词；语义向量能把“营收”“波动”“华东区”映射到对应文档片段，是当时唯一可行的路子。再加上 Milvus、Qdrant、Chroma 这些项目把运维门槛压得很低，大部分团队也就是一个 docker-compose 的事。

但 Harness 场景有个致命差异：查询方不是天然的“人类提问者”，而是一个具备代码执行能力的智能体。它懂得组合工具，懂得连续行动，也懂得在权限范围内去翻文件。当智能体自己和向量库站在同一条知识检索链路上，原来那套“一步语义召回”的方案就不再是最优解了。

1.3 触发转折点：Agent 自己的检索能力变了

我印象最深的一次调整，是我们让 Agent 直接调用一个 grep 工具去代码仓库里找某个历史配置项。在此之前，同一份代码我们提前切块灌进了向量库，结果模型在回答时“看起来头头是道”，但引用的代码位置和实际逻辑完全对不上，还振振有词地补了一段不存在的上下文说明。

后来我们做了一次盲测：同样问题，A 组走向量库，B 组走“搜索工具 + 直接读原文件”。B 组在事实准确率上高出 18 个百分点，定位平均快了两秒。从那以后，我意识到一个关键变化——Harness 环境里，Agent 本身就具备“主动检索”的工具能力，我们真正要做的不是把知识提前嵌入进向量空间，而是把“怎么取知识”的决策权交给一个更可控的运行时工具链。

2. 为什么 Harness 开始少用向量数据库：五个真实原因

2.1 要的是“原文和证据”，不是“相似片段”

这可能是最核心的原因。传统 RAG 的目标是把“最相关的碎片”拼进上下文，给用户一个“语义上说得通”的回答。Harness 场景却不然，一旦涉及代码库阅读、配置排查、合同条款核对，模型必须给出可追溯到文件路径、行号、原始表述的答案。

向量检索的副作用恰好在这里放大了：它返回的是嵌入空间里的近邻片段，拼接后可能在“意思上接近”，但原文的上下文、段落边界、看问题的角度往往已经被切碎。用户在追问“你凭什么这样说”的时候，模型根本拿不出完整的原始依据。

我后来在公司内部总结过一句话：Harness 需要的是“原文呈现”，不是“语义缝合”。尤其在代码调试、配置审计、文档合规这一类任务里，一个字段的原始位置比一百个相似的向量更重要。向量库天然擅长“找相似”，但不擅长“给原话”，这正是它在 Harness 链路里被边缘化的深层原因。

2.2 长上下文让“整文件读取”成了更划算的方案

搁在两年以前，主流上下文窗口还停留在几万 token，走多轮问答时根本不敢把一个文件塞满。向量检索当时最大的优势，就是能把任意长度的文档压成少量片段送进上下文，省 token。

现在的变化是：主流模型普遍支持 128K 甚至 200K 的上下文窗口，编码类 Agent 在工具调用时也可以分页读取、按目录加载、按需加载局部文件。这个能力变化，直接把“提前切块嵌入”的必要性打没了。既然模型有能力在一个回合里读取 200 行以内的整个模块，我们何必在检索环节冒着上下文失真、索引过期的风险，只为了省下那几十 K token？

实际操作中我们发现，直接“整文件读取”还有一个额外收益：模型能完整看到文件内部的结构，比如函数的上下文、注释的关联、模块间的依赖。这些信息在碎片化摘取时几乎必然丢失。长上下文 + 完整读取，让 Agent 表现得既像在用 IDE，又像在思考，而不是在“剪报拼图”。

2.3 向量检索本质上是决策黑盒，Harness 没法观测

Harness 工程的底层追求之一是可观测性。模型每一步做了什么，为什么这么做，中间经过了哪些工具，都要能被完整记录和复盘。这也是为什么大量团队在引入 LangSmith 或者给 DeepSeek Harness 写插件时，第一件事就是记录工具调用日志。

向量检索在这方面的表现非常糟糕。它是一步“语义计算”过程，我们很难回答“这个片段为什么被选中”“为什么在问题 A 和问题 B 下返回了同一批向量”“刚才那次检索到底有多少噪声”。你只能看到花费了额外延迟，拿回了几个 top_k，但整个过程缺乏可解释的中间决策。

有人可能会说，向量库不是也支持元数据过滤、打分调试吗？实话讲，这些功能都是索引侧的，不是决策侧的。真正让工程师头疼的是在“问题不确定”时，向量检索的结果高度不稳定——同一个问题的换几个措辞，返回片段完全不同。这种随机性在 Harness 里是灾难：你无法稳定复现一次 Agent 行为的成败，也就无法定位故障根源。

2.4 嵌入、分块、索引更新的成本被严重低估

上向量库的隐形成本，远不只是“部署一个容器”那么简单。到生产阶段你会发现三件事：

• 分块策略要反复调。块太小会丢失语义，块太大检索粒度太粗，每换一次块大小，全部索引要重建。
• 嵌入需要持续更新。内部文档每月都在变，旧条目不删，检索结果就会带上过期内容；增量更新又容易和旧向量维度不一致。
• 延迟预算不稳定。一个 20 万的文档库，一次嵌入计算加上向量检索，平均耗时往往在 180ms 以上，实际线上抖动可能到 500ms。

对比之下，纯文件工具链的成本几乎可以忽略。grep 一个目录、扫描一个文件树、读取一个文件，毫秒级返回，不需要任何索引预热。用网上常说的那句话就是：向量数据库喂饱了“宠物”，却喂不饱“牲口”——线上 Agent 每天上万次工具调用，稳定、小开销、可预测才是刚需。

2.5 真实任务中，简单工具的精度往往更高

我们做的评测并不极端，回归测试里覆盖了错误提示分析、历史配置追溯、多文件交叉定位。结果很有意思：在 79% 的任务里，Agent 只需要“文件名 + 路径 + grep 关键词”就能完成定位；12% 的任务靠“目录结构分析”完成；真正非要语义联想才能解决的，不到 9%。

这个数据和很多人的直觉相反，但它符合一个规律：技术文档、代码注释、配置项都有一个共性——命名规范比想象中要好。变量名、函数名、文件名本身承载了大量语义信息，关键词匹配远比我们以为的更可靠。“找得到”靠路径，“找得对”靠上下文，“找得全”才轮到语义扩展。

向量数据库最强的一环是“模糊概念联想”，但在真实工程里，Agent 处理的问题大多是“具名实体定位”，比如“找到那个校验超参的函数”“查一下订单状态枚举的变化记录”。这些问题向量库不是不能做，但明显是杀鸡用牛刀，还容易带回一堆结构相近却语义跑偏的干扰片段。

3. 我们现在怎么取知识：一套可观测的文件工具链

3.1 核心思路：先把“取什么”的决策权交给工具

方向想清楚之后，我们把知识获取链路重构了一番。核心原则只有一条：让“取什么知识”这个决策发生在运行时，而不是在离线阶段。离线向量化最大的毛病，就是切块和嵌入是“猜”用户未来要问什么；而 Harness 既然拥有实时工具，完全可以直接在回答前先去探测知识结构。

新的流程长这样：Agent 接到任务 -> 先扫描目录树 -> 用文件名、扩展名、路径结构判断知识所在区域 -> 再通过关键词工具筛选候选文件 -> 最后整文件读取全文。

这一步最大的改变是：Agent 的行为变得有迹可循。每一步工具调用都自然成为日志，问题定位不再需要对着模型输出猜，你直接看它调用了哪个目录、匹配了哪些文件就行。这也让 Harness 层的回滚、暂停、重试策略变得好做得多。

3.2 工具栈与调用顺序

我直接把我认为最顺手的工具栈列出来，你可以在自己的 Harness 里按这个思路实现：

• 目录扫描工具：输入路径前缀，输出目录树，代价极小，用来做“全局定位”；
• 文件名匹配工具：支持通配符或正则，用来快速锁定目标文件的候选集；
• 内容搜索工具：grep/ripgrep 风格，支持多目录、忽略规则，用来做“精确线索”；
• 整文件读取工具：支持行号区间、跳过二进制，用来把原文完整送进上下文；
• 摘要生成工具：当文件太大时，先让模型读前 200 行生成摘要，再决定是否继续读全文。

调用顺序上，我们的实测经验是严格“先粗后精”：先目录，再文件名，再内容搜索，最后再全文。这个过程会和传统的“边检索边拼装”形成鲜明差异——传统方式是离线把所有知识塞进模型，在线只取片段；我们的方式是离线不塞任何东西，在线让模型按需“翻开”要用的页面。

如果你用的是 DeepSeek Harness 这类自定义插件机制，实现这套工具成本并不高，本质就是注册几个更精细的工具函数，然后把任务提示改成“先借助文件系统了解项目全貌，再读取具体文件”的工作流。这种把 skill 和工具声明写进 harness 的做法，和 Claude Code 里“脚本即工具”的解构思路是一致的。

3.3 必要的兜底：受限的稀疏检索与分层索引

我当然不是说语义检索彻底不该用。在兜底层，我们保留了一份“轻量索引”，但做得很克制。

后台为常用文档库生成一个小的元数据索引，内容包括：

• 文件路径与别名；
• 文档类型、标签、负责人；
• 关键术语表（人工维护少量核心词）；
• 定期用 BM25 或 TF-IDF 做一次稀疏检索，不进门级嵌入。

这么做的好处是，如果模型通过路径和关键词确实找不到线索，可以退一步用稀疏检索做“同义词扩展”和“术语联想”，又不需要承担全库向量化的成本和不可解释性。这个分层方案让我感到最舒服的地方是：每一层都有明确的触发条件，Agent 不会同时在一堆不可控的结果里瞎撞。

4. 一张表看清路线差异，什么场景下还该用向量库

4.1 对比表：向量数据库与文件工具链

与其抽象总结，不如直接上表。近半年我衡量过不少选型方案，最终把它压成两行关键结论：

这张表并不是说向量库全面落败。我很明确地讲，在两种场景下我仍然会优先选向量数据库：一类是海量非结构化文本的开放搜索，另一类是用户无法提供准确查询词的高模糊度问答。

比如做企业级知识库时，文档总量五百万篇，问题五花八门，用户又问得很随意，向量库仍然是集效率和效果于一体的方案。这种场景下没有“路径”可依赖，你必须靠语义空间去限缩范围。

4.2 混合方案的边界：向量库当“重排器”而不是“主力”

还有一个新趋势值得一提：不是“只用向量”或“不用向量”，而是把向量降级为“重排器”。我们内部也试过一版：先用关键词 + 路径拿回 50 篇候选，再用 embedding 对这批候选做一次相关度打散，最后只取 top 5。

这种做法的好处是，向量库的职责从“决定取什么”降级为“在有限范围内调整顺序”。黑盒影响被大幅压缩，因为候选集本来就是可解释的，向量只是在候选内部做排序。延迟也被控制在一个很小的窗口内。如果你既舍不得语义召回，又忍受不了向量主导链路的不确定性，这个折中方案很值得试。

5. 折腾半年，这些坑我自己都掉过

5.1 “先检索后问答”改成“先工具后拼装”的实操心得

切换初期，我们犯过一个典型的错误：光把工具加进了 harness，但提示词还保持旧的“先去向量库取上下文”逻辑，结果工具形同虚设。后来才意识到，工具链必须配合新的决策提示一起调整，否则模型会惯性依赖最熟悉的路径。现在我给团队定了个原则：凡是新增一个工具，就必须同时回答三个问题——它解决什么导航问题、它的触发条件写在哪、它失败后回退到哪一层。

另外，工具描述一定要写得“具体行动化”，不要写“获取项目信息”，要写“列出指定目录下的文件树，适合先了解整体结构”。模型能多准确地使用工具，很大程度取决于工具自己会不会说人话。这一步我们迭代了好几版，才找到合适的描述颗粒度。

5.2 嵌入和分块角度踩过的坑

早期版本里，我们为了“省 token”把文档切成 512 字符的小块，结果模型经常只看到零散代码片段，误判函数归属。后来改成“先整文件读，再让模型自己对长文件做分段摘要”，准确率明显提升。这说明了一个底层问题：Harness 不需要提前替模型做信息切块，真正优秀的方式是让模型根据当前任务动态决定“现在需要哪一段”。

另一个印象深刻的坑是“索引过期”。有一回索引里残留了三个月前的旧配置说明，模型引用了它，导致生产环境排查白白浪费半天。自此我们在方案里规定了一件事：凡是有“生命周期”的临时性文档，绝不进向量索引，只允许通过实时文件工具读取。这算是一条纪律，也是让我对向量库态度转向的一个重要细节。

5.3 常见问题速查表

我把这段时间后台被问得最多的问题整理成了一张速查表，你可以边做边自查：

6. 我看到的变化与个人建议

落到整个行业视角，这个趋势其实还有更深的原因。向量数据库是“给人类知识检索设计的”，而 Harness 是“给 AI Agent 自主决策设计的”，两者的根本逻辑不同。人类记不清关键词，需要模糊联想；Agent 永远不会“记不清”，它只是不会“找”。当我们给 Agent 配上精准的导航工具和判定规则，它在工程任务里表现得比向量化记忆更可靠。

从这个角度看，“少用”不是否定向量数据库本身的价值，而是把资源放回它该放的位置。做 Harness 时我的建议很简单：先默认直接读文件和检索路径；当模型确实遇到无关键词、无路径、高不确定性的开放问题时，再将其作为一种可选择性兜底手段引入，而不是把它放在主链路上做主角。这套策略我们实际稳定跑了两个多月，准确率没降，平均延迟反而降了一半。