企业官网建设流程全解析

1. 从终端到智能体：为什么我们需要重新理解命令行交互

命令行终端这东西，干了十几年开发的人对它都有种复杂的情感。一方面它高效、直接、可组合，一条管道能把几个小工具串成一套自动化流程；另一方面它又冷冰冰的，你得记住一堆参数、子命令、环境变量，稍微复杂点的操作就得翻文档。最近一两年冒出来一批所谓的 agentic 终端，思路就是把大语言模型的推理能力直接嵌进终端环境里，让终端不再只是被动执行命令，而是能理解意图、规划步骤、调用工具、甚至自我纠错。Herdr 和 Fresh 就是这类工具里比较有代表性的两个。

这篇文章不是那种泛泛而谈的“趋势解读”，而是我实际把这两个终端都跑起来、用了一段时间之后的拆解记录。我会讲清楚它们各自的设计哲学、核心机制、适用场景，以及一个很多人关心的问题：怎么让一个外部的 agent 通过 API 去调用 Fresh，把 Fresh 的能力当成一个可编程的服务来用。文章会附带一个可运行的 demo，代码可以直接抄。如果你是在做 AI 工具链、自动化运维、或者单纯想给自己的开发环境加一个“会思考的终端”，这篇内容应该能帮你省下不少摸索时间。

先说清楚定位。Herdr 更偏向“多智能体协作的终端编排器”，它的核心卖点是你能在一个终端会话里同时调度多个 agent，让它们分工干活，比如一个负责查资料、一个负责写代码、一个负责跑测试。Fresh 则更偏向“单 agent 深度交互的编辑器型终端”，它的强项在于对上下文的精细管理和对文件系统的深度操作，交互体验更接近一个懂你项目的结对伙伴。两者不是替代关系，更像是两种不同的工作流哲学。下面我会从架构、交互模型、扩展方式三个维度把它们拆开讲。

2. Herdr 深度拆解：多智能体编排到底怎么落地

2.1 Herdr 的核心设计哲学：把终端变成 agent 的调度台

Herdr 这个名字本身就暗示了它的思路——herd，放牧。它不把自己定位成一个“更聪明的终端”，而是定位成一个“管理一群 agent 的终端”。你打开 Herdr，看到的不是一个等待输入的命令行，而是一个可以同时容纳多个 agent 会话的工作区。每个 agent 有自己的角色定义、工具权限和上下文窗口，它们之间可以通过 Herdr 提供的消息总线互相通信。

这个设计解决了一个很实际的问题：单个 agent 在处理复杂任务时容易“迷失”。比如你让它重构一个模块，它可能改着改着就忘了最初的约束条件，或者在一个死胡同里反复打转。Herdr 的思路是把任务拆开，让不同的 agent 各自负责一小块，通过明确的接口交接。这有点像微服务架构对单体应用的改造，只不过这里的“服务”是 agent。

我实际用下来的感受是，Herdr 最适合的场景是那种步骤多、依赖外部信息、需要反复验证的任务。比如“把这个仓库的依赖升级到最新版本，跑通所有测试，如果有失败就分析原因并修复”。这种任务单 agent 做起来很容易顾此失彼，但在 Herdr 里你可以配置一个 agent 专门负责查依赖兼容性，一个负责改代码，一个负责跑测试并汇报，最后由一个协调者 agent 汇总。每个 agent 的上下文都保持干净，不会被无关信息污染。

2.2 配置一个多 agent 工作流的实操步骤

Herdr 的配置入口是一个 YAML 文件，通常放在项目根目录的.herdr/下面。我第一次配的时候踩了个坑：agent 之间的消息传递默认是异步的，如果你不显式声明依赖关系，协调者可能在工作者还没返回结果时就往下走了。正确的做法是在工作流定义里用depends_on字段把顺序锁死。

一个典型的三 agent 工作流配置大概长这样：

workflow: dependency-upgrade agents: - name: researcher role: "分析当前依赖树，找出可升级的包和潜在冲突" tools: [shell, file_read, web_search] output: research_report - name: implementer role: "根据研究报告修改配置文件并更新锁文件" tools: [shell, file_read, file_write] depends_on: [researcher] input: research_report output: change_log - name: verifier role: "运行测试套件，分析失败用例，给出修复建议" tools: [shell, file_read] depends_on: [implementer] input: change_log

这里的关键点是output和input的对接。Herdr 会把上一个 agent 的输出结构化之后传给下一个，而不是把原始文本一股脑塞过去。这个结构化过程是靠 agent 自己按照预定义的 schema 来生成的，所以你在写 role 描述的时候要尽量明确输出格式，否则下游 agent 拿到的可能是一堆没法解析的自然语言。

注意：Herdr 的 agent 默认没有文件写入权限，必须显式在tools里加上file_write。这个设计是为了防止 agent 误操作，但第一次用的人经常会忘了加，然后纳闷为什么 agent 说“已修改”但文件没变。

2.3 Herdr 的上下文隔离机制与性能取舍

Herdr 给每个 agent 分配独立的上下文窗口，这是它最大的优势，也是最大的成本来源。独立上下文意味着每个 agent 都要单独维护一份对话历史，如果你有五个 agent 在跑，token 消耗基本是单 agent 的五倍起步。我实测过一个中等复杂度的重构任务，单 agent 跑下来大概消耗 4 万 token，用 Herdr 三 agent 编排跑了 11 万 token。所以它不适合那种“随便问一句”的轻量场景，更适合那些你愿意为质量买单的重任务。

另一个需要注意的点是 agent 之间的通信延迟。Herdr 的消息总线是本地进程间通信，延迟本身很低，但每个 agent 在收到消息后都要重新做一轮推理，这个推理时间才是大头。如果你的工作流有五个串行步骤，端到端时间可能是单 agent 的三到四倍。我的建议是把能并行的步骤尽量并行，比如让 researcher 和另一个负责环境检查的 agent 同时跑，而不是串成一条线。

3. Fresh 深度拆解：单 agent 的深度交互体验

3.1 Fresh 的定位：一个懂你项目的结对终端

Fresh 走的是另一条路。它不搞多 agent 编排，而是把全部精力放在“单个 agent 怎么更好地理解你的项目上下文”上。你启动 Fresh 之后，它会先扫描当前目录，建立一份项目结构索引，包括文件类型、依赖关系、最近的 git 提交记录。这份索引不是静态的，你在会话过程中修改了文件，Fresh 会增量更新索引，保证 agent 看到的始终是最新状态。

这个设计带来的直接好处是，你不需要每次对话都重新解释“我这个项目是干什么的”。Fresh 的 agent 在第一次交互时就已经有了项目的基本认知。我试过在一个中等规模的 TypeScript 项目里直接问“这个模块的导出为什么在测试里报 undefined”，Fresh 没有让我贴任何代码，它自己定位到了对应的文件，读了导出语句和测试文件的导入语句，然后指出是循环依赖导致的初始化顺序问题。这个体验比传统的“复制粘贴代码到聊天窗口”要顺畅太多。

Fresh 的另一个特点是它对文件操作的精细控制。它不像有些工具那样直接覆盖整个文件，而是以 diff 的形式提出修改建议，你可以逐块接受或拒绝。这个交互模式在重构场景下特别有用，因为你可以只采纳其中一部分改动，剩下的自己手动调整。

3.2 Fresh 的上下文管理策略：滑动窗口加语义检索

Fresh 的上下文管理用了两层机制。第一层是滑动窗口，保留最近 N 轮对话的完整内容，N 默认是 20，可以在配置里调。第二层是语义检索，当对话历史超出窗口后，Fresh 会把旧内容做向量化存储，在需要的时候根据当前问题检索相关片段。这个设计比单纯的截断要聪明，因为它不会因为对话变长就丢失早期的重要约束。

但这里有个实操中的坑：语义检索的召回质量高度依赖 embedding 模型的选择。Fresh 默认用的模型对中文的支持一般，如果你的项目注释和文档是中文的，检索效果会打折扣。我建议在配置里换成对中文更友好的 embedding 模型，具体换哪个可以根据你的部署环境来定，原则是选一个在你领域语料上表现好的。

提示：Fresh 的索引文件默认存在.fresh/index/下面，这个目录建议加到.gitignore里。我见过有人不小心把它提交了，结果仓库里多了一堆二进制文件，而且每次换 embedding 模型都要重新生成，冲突起来很麻烦。

3.3 Fresh 的工具调用协议与扩展点

Fresh 的 agent 可以调用的工具是通过一个 JSON schema 注册的，内置的工具包括文件读写、shell 执行、git 操作、代码搜索。如果你想加自定义工具，比如调用内部 API 或者查询数据库，可以在.fresh/tools/下面放一个描述文件，Fresh 启动时会自动加载。

这个扩展机制是我觉得 Fresh 比 Herdr 更灵活的地方。Herdr 的 agent 工具集是工作流级别定义的，改起来要动 YAML；Fresh 的工具是全局注册的，加一个工具之后所有会话都能用。我给自己项目加了一个查询内部文档站的工具，写了个简单的 HTTP 请求封装，注册进去之后 agent 就能在回答问题时引用内部文档了。

工具调用的协议本身是标准的 function calling 格式，agent 输出一个 JSON 对象，包含工具名和参数，Fresh 的运行时负责执行并把结果回填到对话里。这个过程中如果工具执行出错，错误信息也会被回填，agent 有机会根据错误信息调整策略。我实测下来，对于 shell 命令执行失败的情况，agent 有大概七成的概率能自己纠正，比如路径写错了它会重新拼一个。

4. 让外部 agent 通过 API 调用 Fresh：完整 demo

4.1 为什么需要这个能力：把 Fresh 变成可编程的服务

Fresh 本身是个交互式终端，但很多时候我们希望它的能力能被其他程序调用。比如你有一个 CI 流水线，想在代码合并前让 Fresh 自动审查一遍 diff；或者你有一个 Slack 机器人，想让它在收到特定指令时调用 Fresh 去查项目里的某个实现。这些场景都需要 Fresh 暴露一个 API 接口。

Fresh 从某个版本开始提供了一个 headless 模式，可以通过 HTTP 接收请求，把 agent 的响应以流式或非流式的方式返回。下面我会写一个完整的 demo，展示怎么启动 Fresh 的 API 服务，以及怎么用一个 Python 脚本作为外部 agent 去调用它。

4.2 启动 Fresh 的 API 服务

首先确认你的 Fresh 版本支持 headless 模式。启动命令大概是这样的：

fresh serve --port 8787 --project-root /path/to/your/project --model gpt-4o

这里--project-root指定了 Fresh 要索引的项目目录，--model指定底层使用的模型。启动之后 Fresh 会在 8787 端口监听，接受 POST 请求。默认情况下它只绑定 localhost，如果你需要从其他机器访问，得加上--host 0.0.0.0，但生产环境建议放在反向代理后面并加上认证。

服务启动后，你可以先用 curl 测一下：

curl -X POST http://localhost:8787/v1/chat \ -H "Content-Type: application/json" \ -d '{"message": "这个项目的入口文件是哪个？", "stream": false}'

如果返回了包含文件路径的 JSON，说明服务正常。注意 Fresh 的 API 默认是无状态的，每次请求都是独立的会话。如果你想保持上下文，需要在请求里带上session_id，Fresh 会根据 session_id 维护对应的对话历史。

4.3 外部 agent 调用 Fresh 的 Python demo

下面这个 demo 展示了一个外部 agent 怎么调用 Fresh 的 API 来完成一个具体任务：审查当前 git diff 并给出改进建议。这个 agent 自己负责获取 diff，然后把 diff 内容发给 Fresh，Fresh 利用它对项目的理解给出有针对性的反馈。

import subprocess import requests import json FRESH_API = "http://localhost:8787/v1/chat" def get_git_diff(): """获取当前工作区未提交的改动""" result = subprocess.run( ["git", "diff", "HEAD"], capture_output=True, text=True, check=True ) return result.stdout def review_with_fresh(diff_text): """把 diff 发给 Fresh 进行审查""" prompt = f"""请审查以下代码改动，指出潜在问题并给出改进建议。 重点关注：逻辑错误、边界条件、性能隐患、可读性。 改动内容： {diff_text} """ payload = { "message": prompt, "stream": False, "session_id": "review-session-001" } response = requests.post(FRESH_API, json=payload, timeout=120) response.raise_for_status() return response.json()["reply"] def main(): diff = get_git_diff() if not diff.strip(): print("没有未提交的改动") return print("正在请求 Fresh 审查...") review = review_with_fresh(diff) print("=" * 60) print(review) if __name__ == "__main__": main()

这个 demo 的关键点在于session_id的使用。如果你连续调用多次，用同一个 session_id，Fresh 会记住之前的审查意见，后续的审查会参考之前的结论，避免重复提同样的问题。这在迭代开发场景下很有用，你改完一轮再审查，Fresh 会告诉你上次提的问题有没有解决。

4.4 流式响应的处理与超时控制

上面的 demo 用的是非流式模式，适合 diff 不大的场景。如果 diff 很大或者你想实时看到 Fresh 的思考过程，可以用流式模式。Fresh 的流式响应是 SSE 格式，每行一个 JSON 对象。处理方式大概是这样：

def review_stream(diff_text): payload = { "message": f"审查以下改动：\n{diff_text}", "stream": True, "session_id": "review-session-002" } with requests.post(FRESH_API, json=payload, stream=True, timeout=300) as r: for line in r.iter_lines(): if not line: continue if line.startswith(b"data: "): chunk = json.loads(line[6:]) if "delta" in chunk: print(chunk["delta"], end="", flush=True) if chunk.get("done"): break

超时设置需要根据你的模型响应速度来调。我实测下来，对于 500 行以内的 diff，非流式模式大概 30 到 60 秒返回，流式模式首字节延迟在 3 到 5 秒。如果你用的是推理能力更强的模型，时间会更长，建议把 timeout 设到 300 秒以上，并且加上重试逻辑。

注意：Fresh 的 API 在流式模式下如果客户端断开连接，服务端会继续跑完当前推理，不会立即停止。这在批量调用场景下可能导致资源浪费，建议在客户端做好并发控制，不要一次性发太多请求。

5. 两个终端的对比与选型建议

5.1 核心维度对比

5.2 什么情况下选哪个

如果你面对的是一个需要多步骤、多角色协作的任务，比如大型重构、依赖迁移、多模块联调，Herdr 的编排能力能帮你把复杂度拆开。它的价值在于让每个 agent 专注在自己擅长的环节，通过结构化接口交接，减少单 agent 的认知负担。

如果你更需要的是一个能理解项目全局、随时回答具体问题、帮你审查代码的伙伴，Fresh 更合适。它的项目索引和语义检索让它在回答“这个函数在哪里被调用”“这个配置项为什么这么设”这类问题时特别顺手。而且它的 API 能力让你能把它集成到现有的自动化流程里，这是 Herdr 目前比较欠缺的。

我个人的用法是两个都留着。日常写代码、查实现、审查 diff 用 Fresh；遇到那种需要反复试错、多步骤验证的任务，切到 Herdr 配一个工作流跑。它们不冲突，反而互补。

5.3 部署与资源规划的实操建议

Herdr 的资源规划核心是控制并发 agent 数量。我的经验是，在 16GB 内存的开发机上，同时跑三个 agent 是比较舒服的上限，超过之后上下文切换的开销会明显拖慢响应。如果你需要更多 agent，建议把 Herdr 部署到单独的机器上，通过远程终端连接。

Fresh 的资源消耗主要来自索引构建和向量存储。一个十万行左右的项目，首次索引大概需要两到三分钟，索引文件占几百 MB。如果你的项目更大，建议把索引目录放在 SSD 上，并且定期清理不再需要的旧索引。Fresh 支持增量索引，日常使用中只有文件变动时才会触发更新，开销可以接受。

提示：两个工具都支持自定义模型端点。如果你有本地部署的模型服务，可以在配置里把 endpoint 指过去，这样既能控制成本，又能保证代码不出内网。具体配置方式参考各自的文档，核心就是改 base_url 和 api_key 两个字段。

6. 实操中踩过的坑与排查技巧

6.1 Herdr 工作流卡死不动怎么办

这是我最开始用 Herdr 时遇到最多的问题。工作流启动后某个 agent 一直不返回，整个流程就卡在那里。排查思路是这样的：先看 Herdr 的日志，通常在.herdr/logs/下面，找到卡住的那个 agent 的日志文件，看它最后一条输出是什么。常见原因有三个：一是 agent 在等待一个永远不会到来的依赖，检查depends_on有没有形成循环；二是 agent 调用的工具执行超时但没有设置超时处理，检查工具配置里的 timeout 字段；三是模型端点响应慢或者挂了，用 curl 直接测一下端点。

如果是依赖循环导致的卡死，Herdr 在启动时其实会做一次检查，但如果你是在运行中动态修改了工作流定义，它不会重新检查。所以改完配置记得重启工作流。

6.2 Fresh 索引不更新或检索不准

Fresh 的索引更新是文件系统事件驱动的，如果你用的编辑器保存文件时不是原子写（比如先写临时文件再重命名），Fresh 可能捕获不到变更。表现就是你在编辑器里改了代码，但 Fresh 回答时还在引用旧内容。解决办法是手动触发一次重新索引，命令是fresh reindex，或者重启 Fresh 服务。

检索不准的问题前面提过，主要是 embedding 模型和语料不匹配。另外还有一个容易被忽略的点：Fresh 的语义检索默认只索引代码文件和 Markdown 文档，如果你项目里有大量注释在 YAML 或者 JSON 里，这些内容不会被索引。你可以在配置里加上额外的文件扩展名，让 Fresh 把这些文件也纳入索引范围。

6.3 API 调用的认证与限流

Fresh 的 headless 模式默认没有认证，任何能访问到端口的人都能调用。如果你把它暴露在非本地环境，一定要加一层认证。最简单的做法是在反向代理层加 Basic Auth，或者用 Fresh 支持的 token 认证，在启动时加上--auth-token参数，调用时在 header 里带上Authorization: Bearer <token>。

限流方面，Fresh 本身没有内置限流，需要你在调用端或者代理层控制。我的做法是在 Python 客户端里用一个简单的令牌桶，限制每秒最多发两个请求，避免把 Fresh 的推理队列打满。如果你是在 CI 里用，建议把审查任务串行化，不要并行发多个请求。

6.4 常见问题速查表

7. 把两者串起来：一个混合工作流的设想

既然 Herdr 擅长编排、Fresh 擅长项目理解，一个自然的想法是让 Herdr 的某个 agent 去调用 Fresh 的 API，把 Fresh 当成一个“项目知识查询工具”。这样 Herdr 的协调者 agent 在规划步骤时，可以先问 Fresh“这个模块的依赖关系是什么”，拿到准确信息后再分派任务给其他 agent。

实现方式是在 Herdr 的工具配置里加一个 HTTP 工具，指向 Fresh 的 API 端点。Herdr 的 agent 调用这个工具时，把问题作为参数传过去，Fresh 返回答案，Herdr 的 agent 拿到答案后继续推理。这个模式我试过，效果不错，尤其是在处理那种需要先理解代码结构再动手改的任务时，能明显减少 agent 走弯路的概率。

不过要注意的是，这种嵌套调用会增加端到端延迟。Fresh 的一次查询大概要几秒到十几秒，如果 Herdr 的工作流里频繁调用，整体时间会拉长。我的建议是只在关键决策点调用 Fresh，比如任务开始时的结构分析、以及修改后的验证阶段，中间的执行环节让 Herdr 的 agent 自己搞定。

这个混合模式目前还在摸索阶段，配置起来比单独用任何一个都要复杂一些，但方向是对的。工具的价值不在于它本身多强大，而在于它能不能被组合进你现有的工作流里，解决你实际遇到的问题。Herdr 和 Fresh 各自解决了不同层面的问题，把它们串起来用，算是把两者的优势都吃到了。