为了不空谈，我给同一类任务（一个会调工具的查天气 Agent）在两边各写了一份代码并真跑起来：pi 侧用内置的 fauxProvider（不需要 key），LangChain 侧用真实模型端点（DeepSeek 的 Anthropic 兼容接口）。文中的事件序列、消息序列、最终回答都是真实输出。

版本：@earendil-works/pi-ai / pi-agent-core 0.85.1；langchain 1.5.11 / @langchain/langgraph 1.4.15（2026-09 npm 实测）。本站已有两个系列：pi-agent 系列、LangChain + LangGraph 系列。

一、先给结论​

一句话选型：要生态和速度 → LangChain；要透明和掌控 → pi。

二、架构对照：抽象层数不一样​

两边看起来都是「两层」，但厚薄完全不同：

• LangChain 的 core + LangGraph 里塞的是方法论级抽象（Runnable、Chain、StateGraph、Reducer、Checkpointer、回调体系…）；
• pi 的两层里，pi-ai 只做「统一各家 LLM 的接入」，pi-agent-core 只做「状态 + 工具循环 + 事件流」。它没有图、没有 reducer、没有 checkpointer 这些概念——因为它假设「循环之外的事你自己管」。

三、同任务对照：一个「查天气」Agent​

pi 的写法（真实代码，35 行左右）​

import { Type, createModels, fauxProvider, fauxAssistantMessage, fauxToolCall, fauxText } from '@earendil-works/pi-ai';
import { Agent } from '@earendil-works/pi-agent-core';

const faux = fauxProvider();                    // ← 无需 key 的假模型
const models = createModels();
models.setProvider(faux.provider);

const agent = new Agent({
  initialState: {
    systemPrompt: '你是一个会调用工具的助手。',
    model: faux.getModel(),
    tools: [{
      name: 'get_weather', label: '查天气', description: '查询某城市天气',
      parameters: Type.Object({ city: Type.String() }),   // ← TypeBox schema
      execute: async (_id, { city }) => ({ content: [{ type: 'text', text: `${city}: 25°C 晴` }] }),
    }],
  },
  streamFn: models.streamSimple.bind(models),   // ← 只注入「怎么连模型」
});

agent.subscribe((e) => { /* 事件流：turn_start / message_end / tool_execution_* … */ });
await agent.prompt('杭州天气怎么样？');

真实运行输出（事件序列）：

== turn_start ==
   [message_end] user = [text]
   [message_end] assistant = [toolCall]        ← 模型提议调工具
   [tool_execution_start] get_weather
   [tool_execution_end] ok=true
   [message_end] toolResult = [text]
== turn_end == toolResults=1
== turn_start ==                              ← 自动进入下一轮
   [message_end] assistant = [text]           ← 读到工具结果后回答
== turn_end == toolResults=0
== agent_end == messages=4

LangChain 的写法（一行起 Agent）​

import { createReactAgent } from '@langchain/langgraph/prebuilt';
import { tool } from '@langchain/core/tools';
import { z } from 'zod';

const getWeather = tool(async ({ city }) => `${city}: 25°C 晴`, {
  name: 'get_weather',
  description: '查询某城市天气',
  schema: z.object({ city: z.string() }),        // ← zod schema
});

const agent = createReactAgent({ llm: model, tools: [getWeather] });
const res = await agent.invoke({ messages: [{ role: 'user', content: '查一下杭州的天气' }] });

真实运行输出（真实模型，两次工具调用）：

   ▶ 工具被调用: get_weather(杭州) -> 25°C 晴
消息角色序列: HumanMessage -> AIMessage -> ToolMessage -> ToolMessage -> AIMessage
最终回答: "杭州：25°C 晴。"

（同一份 demo 里换成「查杭州和深圳人口」，模型会并行调两次工具，于是出现连续两个 ToolMessage。）

对照着看，差在哪​

四、五条本质差异​

1. 循环的「可见度」不同​

pi 把循环暴露成事件流：turn_start / message_start / message_update / message_end / tool_execution_start|update|end / turn_end / agent_end。你订阅事件就能画进度条、做审计、接 UI——循环本身是可见的。

LangChain 把循环收进「图」里：你能拿到状态快照、能流式拿更新（streamMode: 'updates' | 'values'），但中间过程是消息和状态，不是「事件」。

2. 状态的「归属」不同​

• pi：状态就是消息序列，加一层 AgentMessage → convertToLlm() 的转换管线（可以把「只有 UI 看得懂的消息」混在里面，发给模型前过滤掉）；记忆靠会话（sessionId，持久化有独立的 SQLite 后端包）。
• LangChain：状态是你显式声明的图状态——Annotation.Root({...}) + reducer 决定「同一字段多次写入怎么合并」；记忆靠 checkpointer（按 thread_id 存）。更工程化，也更啰嗦（要理解 reducer 才能不出错）。

3. 工具与 schema 的取舍​

• pi 用 TypeBox：schema 本身就是 JSON Schema，可序列化、可跨进程传（这也是它在 MCP/分布式场景顺手的原因）；
• LangChain 生态用 zod：TS 推导最强、生态最大，但跨语言/进协议要转换（MCP 那篇 讲过这个链路）。

4. 「模型调用的自由度」不同​

LangChain 想帮你把模型调用的花样都覆盖：withStructuredOutput（结构化输出）、bindTools、流式、回调、缓存……我在实测里也踩到过它的边界：推理模型不支持强制 tool_choice，withStructuredOutput 直接 400（错误原文 Thinking mode does not support this tool_choice）。

pi 的选择是只给原语：stream/streamSimple、complete/completeSimple、validateToolCall——能做多少取决于你写多少。

5. 体量与依赖​

• pi 的 pi-agent-core 依赖只有几个：pi-ai、pi-telemetry、chord、typebox、diff、ignore、yaml（本机从 package.json 读的）；
• LangChain 的依赖树大得多（厂商 SDK、SDK 适配层、core、langgraph……），能力多，装的东西也多。

五、各自的「隐藏优势」​

LangChain 的优势在生态：文档加载器、向量库、检索器、LangSmith 可观测、海量集成——要快速拼一个 RAG/多工具应用，它省下的时间很实在。（前提是你能接受它的抽象；遇到边界时也要有能力往下钻。）

pi 的优势在透明：整个循环你能读懂、能改。这也是为什么 InkOS 这种生产 harness 会建在它上面——需要自己掌控「确认闸门、原子落盘、状态机」时，薄框架 + 自己写比「厚框架 + 绕开它」要顺。

还有一点：pi 的 Agent.subscribe 事件流 + streamProxy（给浏览器走后端代理）+ 低层 agentLoop，让它既能当「开箱 Agent」，也能拆开只用循环原语——分层的粒度是按「你要接管多少」设计的。

六、选型清单​

混合用法也存在：用 LangGraph 管编排、用 pi-ai 当 LLM 接入层（或反过来只在某些节点用 LangChain 的集成）。但别为混而混——两套抽象叠在一起，调试成本会翻倍，除非确有一个「另一侧做不到」的刚需。

七、一句话收尾​

LangChain 在回答「Agent 应该长什么样」，pi 在回答「Agent 循环最少要多小」。 前者给你一栋装好的房子，后者给你砖和图纸——选哪个，取决于你是想快点住进去，还是想自己决定户型。

关联​

• pi-agent 系列：pi-ai 的统一模型层、pi-agent-core 的事件流与工具生命周期
• LangChain + LangGraph 系列：LCEL、状态图与 reducer、ReAct Agent 实战
• InkOS 架构拆解：一个真实建在 pi 之上的生产 harness
• 手写 agent 循环：不依赖任何框架的最小实现

参考​

• pi 仓库/包：github.com/earendil-works/pi（npm @earendil-works/pi-ai、@earendil-works/pi-agent-core）
• LangChain JS 文档：js.langchain.com ｜ LangGraph JS：langchain-ai.github.io/langgraphjs
• 本文实测：pi 侧 fauxProvider 事件序列、LangChain 侧真实端点消息序列与工具调用日志，均为本机运行结果；版本如文首标注

同一个 key 被写入多次时，状态该怎么合？

这就是 reducer 要回答的唯一问题。这篇把它讲全：Annotation 的完整用法、reducer 的几种模式、它什么时候被调用、调用几次、以及我把每种行为都真实跑出来的结果（含两个报错，都是实测）。

声明：以下行为全部在 @langchain/langgraph 1.4.15（Node 24）跑出来的，输出是真实的。不同版本行为可能微调，以你的实际运行为准。

一、先搞懂 Annotation：状态说明书​

LangGraph 的状态不是「一个对象」，而是一张「字段 → 说明」的表。Annotation 就是写这张表的工具：

import { Annotation } from '@langchain/langgraph';

const State = Annotation.Root({
  // 每个 key 一条说明：用什么类型、怎么合并、初始值是什么
  count: Annotation({ reducer: (cur, next) => cur + next, default: () => 0 }),
  logs:  Annotation({ reducer: (cur, next) => cur.concat(next), default: () => [] }),
  title: Annotation({ default: () => '' }),        // 不写 reducer → 覆盖模式
});

三个要点：

TypeScript 里怎么取类型：type S = typeof State.State（State 是值，.State 才是类型）。另外 LangGraph 还提供现成预设，比如 MessagesAnnotation（聊天消息专用，见第五节）。

二、reducer 的几种模式（含实测）​

模式 1：不写 reducer = 覆盖（最后一次写入赢）​

const S = Annotation.Root({ v: Annotation({ default: () => 'init' }) });
// a 节点写 'from-a'，b 节点写 'from-b'

实测输出：

① 默认（覆盖）: {"v":"from-b"}

a 写的值被 b 覆盖了。这是默认语义，也是绝大多数「配置类字段」想要的。

模式 2：追加 / 累加（最常用）​

logs: Annotation({ reducer: (cur, next) => cur.concat(next), default: () => [] })
count: Annotation({ reducer: (cur, next) => cur + next, default: () => 0 })

实测输出：

② 自定义（追加）: {"log":["a","b"]}

模式 3：任意语义——合并、取最大、去重……​

reducer 就是个普通函数，所以「几种模式」本质上没有上限：

模式 4：消息专用——messagesStateReducer​

聊天场景「追加消息」有个特殊需求：同一条消息被更新时应该替换，而不是新增。LangGraph 内置了它：

messages: Annotation({ reducer: messagesStateReducer, default: () => [] })

实测（m1 先写入，随后同 id 再写一次）：

④ 消息 reducer: [{ id:"m1", content:"第一条被改了" }, { id:"m2", content:"第二条" }]  | 条数 = 2

注意：条数是 2 不是 3 —— 同 id 的 m1 被原地更新（内容从「第一条」变成「第一条被改了」），m2 才被追加。这就是消息 reducer 和「朴素 concat」的本质区别：它按 id 去重。

模式 5：预设 MessagesAnnotation​

不想自己写 reducer，可以直接用预设：

import { MessagesAnnotation } from '@langchain/langgraph';
const graph = new StateGraph(MessagesAnnotation)...

实测输出：

⑤ MessagesAnnotation: ["human:hi","ai:收到 1 条"]

（注意这里的消息 type 就是 'human' / 'ai' 字符串——预设帮你处理了消息的构造与追加。）

同目录导出里还有 messagesDeltaReducer、addMessages、pushMessage、REMOVE_ALL_MESSAGES 等消息相关工具（本机导出的真实名字），做「消息流/增量」时值得翻一眼。

三、reducer 什么时候被调用、调用几次​

这是最容易搞错的地方。结论：每次「向某个 key 写入」都会调用一次 reducer，而且一次节点执行可能产生多次写入。

实测：一个节点里通过 Command 连续写同一个 key 三次：

.addNode('multi', () => [
  new Command({ update: { sum: 1 } }),
  new Command({ update: { sum: 2 } }),
])

   reduce(0, 1)
   reduce(1, 2)
③ Command 多更新 → {"sum":3}

reducer 被调用了两次，且是顺序累积的：先 reduce(0,1) 得 1，再 reduce(1,2) 得 3。

⚠️ 实测踩到的坑：节点返回「数组」不行​

我一开始想当然地写 () => [{ sum: 1 }, { sum: 2 }]，直接报错（真实报错文本）：

InvalidUpdateError: Expected node "multi" to return an object or an array containing at
least one Command object, received array
（lc_error_code: INVALID_GRAPH_NODE_RETURN_VALUE）

在这个版本里，节点返回的数组必须包含 Command 对象，不能是「一串普通的部分状态」。想在单个节点里写同一个 key 多次 → 用 Command，或者干脆拆成多个节点（更常见、更清晰）。

四、default 的三条规则（实测）​

规则 1：首次写入时，有 default 才会调用 reducer​

我特意在 reducer 里打了日志：没有 default 的字段，首次写入不会调用 reducer——直接落值（实测输出里没有出现 reducer 日志，最终状态是 {"x":"first"}）。

而第三节的例子有 default: () => 0，于是第一次写入就是 reduce(0, 1)。

直觉理解：reducer 是「合并器」，没有旧值就没什么可合并的。

规则 2：default 必须是函数​

default: () => []      // ✅ 正确
default: []            // ❌ 实测报错：initialValueFactory is not a function

为什么必须是函数：函数保证每次 invoke 得到全新对象，否则多个请求会共享同一个数组/对象（脏数据）。实测验证：

② 两次调用: {"list":["x"]} {"list":["x"]} | 互相独立 = true

规则 3：不写 default，字段初始就是 undefined​

需要「一开始就有值」的字段（尤其是要 concat 的数组、要相加的数字），请务必给 default，否则第一次 reduce 会拿到 undefined。

五、六个必须知道的坑​

1. reducer 会被调用很多次：别在里面做副作用（写文件、发请求、打日志噪音）。它应该是纯函数；
2. 并行分支写同一个 key，reducer 要「可交换」：多个节点并行更新同一 key 时，谁先谁后由调度决定。用「累加/追加/取最大」这类顺序无关的 reducer 才安全；用「取最后一个」会得到不确定结果；
3. 节点返回数组 ≠ 多个更新：数组里必须是 Command（上面的真实报错）；
4. (cur, next) => next 和 concat 差的是语义：前者丢历史，后者留全部——消息、日志、轨迹类字段基本都要后者；
5. 消息要用 messagesStateReducer 而不是 concat：否则同 id 消息会重复堆积（第四节实测：用对 reducer 后是 2 条而不是 3 条）；
6. default 忘了写函数 → 直接报 initialValueFactory is not a function，这类错误信息很好认。

六、一张选型表​

七、一句话总结​

• Annotation 是状态说明书：Annotation.Root 声明整张表，Annotation<T>({reducer, default}) 声明每个字段；
• reducer 的「几种模式」其实是「一次合并函数」的无数种写法：覆盖、追加、累加、合并、去重、消息……都由你定义；
• 触发时机：每次写入调用一次、可累积调用多次（Command 多更新实测 reduce(0,1) → reduce(1,2)）；首次写入时有没有 default 决定它是否被调用；
• 两条硬规则：default 必须是函数；节点返回的数组里只能是 Command；
• 一条设计原则：reducer 要纯、要能重复调用、并行场景下还要顺序无关。

关联​

• 前置：LangGraph 入门：状态图、条件边与记忆
• 图解版：LangGraph 图解：执行过程与状态
• 实战：用 LangGraph 写 ReAct Agent
• 对照：自己手写 agent 循环——那里「状态」就是一个你自己维护的 messages 数组，reducer 就是 push

参考​

• LangGraph JS 文档（Graph API / State 与 reducers）：langchain-ai.github.io/langgraphjs
• 本文实测环境：@langchain/langgraph 1.4.15 + Node 24；输出与报错均为真实运行结果

这篇聊四件事：传统 RAG 的结构性毛病 → 2026 年的现状与主流解法 → 一个被低估的问题（解析损失） → 最近很热的「像素方案」（视觉/像素级 RAG）到底是什么、什么时候值得用。

文中行业数据来自公开资料（论文、厂商博客、技术评测），统计口径与时点不一，已尽量标注；相关结论请以原文为准。本文也会连到本站已有的 agent / 协议系列。

一、传统 RAG：一条流水线，三个结构性毛病​

老配方大家都熟：

文档 → 解析成文本 → 分块（chunk） → 向量化（embedding） → 向量检索 Top-K → 塞进提示词 → 生成

它在「FAQ 式单跳问答」上很好用，但一到企业深水区就露怯：

再加两个工程现实：延迟与成本（向量检索 + 重排不可避免，长上下文也很贵）、「像」不等于「对」（向量库只判断相似度，不承载结构化关系与时序）。

二、现状（2026）：四条主线和一条底线​

底线：长上下文没有取代 RAG​

百万 token 上下文确实能「把整本书塞进去」，但成本不划算（有评测称用大模型直接做检索任务，成本可比专用 embedding 模型高三个数量级），而且慢。结论是互补：能用检索毫秒级过滤出「真正决定决策的少量 token」，就别用冗余数据灌满模型。

主线一：把检索质量做扎实（混合检索 + 重排 + 压缩 + 路由）​

工程共识是按需叠加，而不是全上：

有调研称「混合检索 + 重排」的架构可把问答准确率提升 30%+（来源见文末）。另一条值得记的是 Contextual Retrieval（Anthropic）：给每个块补「上下文说明」再索引，公开数据称检索失败率降低约 49%，叠加 Contextual BM25 + 重排后约 67%。

主线二：GraphRAG（从「像不像」到「连不连」）​

用「实体—关系」知识图谱 + 社区摘要（Leiden 聚类）补上全局视野与多跳推理。公开实测对比很醒目：多实体关系推理场景 GraphRAG 85%–92%，传统 RAG 45%–60%。但代价也明确：索引与维护成本是传统方案的 2–3 倍，且需要持续实体对齐。单跳问答别上它——那是杀鸡用牛刀。

主线三：Agentic RAG（RAG 变成循环）​

把「检索」从流水线里的一个模块，变成 Agent 循环中的一次决策：分解 → 路由 → 检索 → 反思 → 重规划 → 再检索。好处是自主决定「检索几次、检索哪儿」，坏处是延迟与成本上升（用缓存、小模型路由、并行检索来压）。

注意措辞：不是 Agent 干掉 RAG，而是 Agent 把 RAG 吸收成了自己的能力——这正是本站 LangGraph 这类编排框架的主场。

主线四：往「记忆」和「上下文工程」走​

RAG 正在从「外部知识补丁」变成 AI 认知结构的一部分：长期记忆分层、上下文压缩（有研究称上下文工程方法可减少 19%–53% 的 token）等。这一层的竞争对手不是别的框架，而是你系统的整体设计。

三、被低估的老问题：解析损失（Parser Loss）​

上面说的是「检索层」的问题，但还有一层更靠前、更隐蔽：你的文档真的被读对了吗？

传统流程里，PDF 要先被解析成文本：OCR、版面检测、表格还原、分块——每一步都可能丢信息：

• 表格变成一坨错位的文本；
• 图表/示意图直接消失；
• 版面对语义的贡献（哪个数字属于哪一行、脚注挂在哪）被压平。

有研究（Berkeley / Princeton / EPFL / Databricks 的联合工作）在 Wikipedia 1,000 题基准上发现：超过三分之一的 RAG 失败可以追溯到解析损失。ColPali 论文也直说了：OCR + 版面检测 + 结构重建这套索引流程「可能很慢、容易传播错误，且难以考虑页面里更多的视觉元素」。

关键推论：如果你的数据源是「版面本身承载信息」的文档（财报、技术手册、带图表的论文），那么在检索之前，信息就已经丢了——后面再怎么调 embedding、加重排，都补不回来。

四、像素方案：直接检索「页面图像」​

于是有了一条思路很直接的路：别把文档压成文本，直接把页面当图像来检索。

三条路线的差别（很关键）​

ColPali 的机制（一句话版）​

• 把每一页当成一张图，用视觉语言模型（PaliGemma-3B，SigLIP-So400m 视觉编码器 + Gemma 2B）编码成一组逐图块（per-patch）向量；
• 查询同样编码成逐 token 向量；
• 用 ColBERT 式的晚期交互（late interaction） 打分：每个查询词找最匹配的图块，分数求和；
• 因此匹配能定位到页面某个区域，而版面、图表、表格「从未被压平成文本」，自然保留；
• 为省存储，向量投影到 128 维；配套基准是 ViDoRe。

代价：把存储算清楚（这决定它能不能上）​

这是像素方案真正的门槛。按公开的配置（每图块 128 维、约 1030 图块/页）：

200 MB 和 26 GB 是两种基础设施决策。所以常见工程做法是：把晚期交互当「重排阶段」用——先用便宜的检索召回候选页，再用像素级模型精细打分；或者像 PixelRAG 的实现那样走单向量 + 交叉编码器重排的路线（同样语料单向量约 200 MB，用重排器补精度），并配合二值量化 / 池化把体积压下来。

另有厂商（Morphik）报告在金融文档基准上做到 95.56% 准确率，而其它端到端方案最高约 67%——这类数字要按语料看待，别当通用结论。

什么时候该用、什么时候别用​

适合：

• 财报、技术手册、带图表的论文——版面本身承载语义；
• 需要对「某区域」定位（比如「Q3 营收那个数字旁边的趋势图」）。

不适合：

• 需要可复用的干净文本（复制法律条款、把表格导回 Excel）；
• 需要精确字面匹配（查序列号、错误码）——纯文本 BM25 往往更准也更省。

实践建议（这段最值钱）​

1. 按证据类型路由，而不是二选一：文本优先、视觉优先、混合，各自解决不同问题；不要直接混不可比的原始分数，先按证据类型路由再融合排名；
2. 保留坐标：页级命中对生成太粗，要能细化到「页面内的哪个区域」；
3. 先评测检索，再评测回答：没被召回的证据，再强的 VLM 也救不回来；
4. 所有模态都是不可信输入：文本、OCR、Caption、像素里都可能藏 Prompt Injection；建议保存「原始资产 → 派生单元」的证据链，带归一化坐标、hash 与解析器版本；
5. 记住它没解决的那部分：像素方案治的是「解析损失」，不治多跳推理、时效性、全局聚合——那些还是 GraphRAG / Agentic RAG 的活。

五、一张选型表（把这篇收口）​

六、一句话总结​

• RAG 现在的正确问题不是「用不用」，而是「每个 Agent 在推理的哪一步、用哪种检索、在什么预算下」；
• 解析损失是被长期低估的一环——三分之一以上的失败可能在检索之前就注定了；
• 像素方案不是万灵药：它用存储与成本换版面保真，适合视觉文档，不适合要干净文本和精确匹配的场景；
• 最实际的架构是混合：文本检索打底、像素检索补版面、重排提精度、Agent 决定何时检索。

关联​

• LangGraph 系列：Agentic RAG 的编排底座（状态图 + 条件边 + 记忆）
• Zod / MCP：工具与协议的 schema 层（检索结果进模型前的那道闸）
• Coze 对话流 vs 自主规划：确定性编排 vs 模型自主决策——RAG 的 Agentic 化是同一个问题的另一面
• Deep Agents：把「检索 + 读写文件 + 子任务」打包成中间件的思路

参考​

• The New RAG Method that Searches Pixels instead of Text（Dutch Startup TV）
• ColPali: 利用视觉语言模型实现高效文档检索（Hugging Face 中文博客）
• Multimodal RAG: Retrieving Over Images and Text（Multigrid）
• 多模态 RAG：生产级架构、检索与评测指南（QubitTool）
• Graph-RAG 到 Agentic RAG：2026 年知识检索四大新范式与选型指南
• 2026 年 RAG 技术栈分层指南：检索、重排、压缩、路由何时该加（RadarAI）
• RAG Isn't Dead, It Just Grew Up（Paradigma Digital）

声明：本文为公开资料整理 + 个人判断，无厂商合作。文中性能/成本数字来自上述来源，口径与时点不一（尤其准确率类指标强依赖语料），选型前请自行在自己的数据上评测。

这篇把两者的底层机制差异讲清楚，并给一张选型表和几个常见坑。

先排一个术语雷：「对话流模式」是「智能体的运行模式」之一；而「对话流（Chatflow）」本身是一种「编排类型」（与「工作流 Workflow」相对）。这两个轴经常被混为一谈——本文会分别讲清，因为它们影响的是不同的选择。

内容依据 Coze 官方文档与公开资料整理，平台版本迭代快、不同版本 UI 命名有差异，具体以你所用版本的官方文档为准。

一、一句话对比​

• 自主规划模式：用模型自主决策——只有人设、插件、知识库，没有固定流程。模型自己判断「要不要调工具、调哪个、要不要查知识库、还是直接回答」。
• 对话流模式：用流程替代自主决策——智能体绑定一个「对话流」，严格按画布上的节点顺序（DAG）执行；模型只作为「节点内的生成工具」，无权改变流程走向。

一句话记住：自主规划把控制权交给模型，对话流模式把控制权交给画布。

二、机制差异：两个完全不同的循环​

自主规划模式 = ReAct 循环​

• 底层是完整的 ReAct 循环（Think → Act → Observe → …），没有预设节点链路；
• 资源（插件、知识库）直接绑在 Agent 配置上，由模型在运行时挑；
• 配置极简：人设 + 绑定资源，就能跑。

对话流模式 = 确定性 DAG​

• 走向由画布上的分支、判断、循环硬编码锁定；引擎维护全局流程状态栈，强制按顺序走完链路；
• 模型只在「大模型节点」里做单点生成（或意图识别），不能改流程；
• 资源不绑在 Agent 上，而是全部绑在对应工作流的节点里。

平台在底层用一个运行模式字段做永久区分（公开资料提到类似 auto_plan / workflow_link / multi_agent 的取值），调试面板、监控指标、API 执行链路都会因此不同——所以选错模式不是「配置问题」，而是「架构问题」，后期改造成本高。

三、逐项对比​

一句话选型：

• 任务步骤固定、要可审计、要稳定 → 对话流模式；
• 任务开放、边界说不清、要模型自己去搜去试 → 自主规划模式。

四、另一个别混淆的轴：工作流 vs 对话流​

上面说的是「智能体的运行模式」。而当你选择「对话流模式」时，还要理解编排类型这一层——Coze 有两种编排：

关键点：两者节点类型基本一致、逻辑可复用，区别在入口方式与输出形式（对话流带对话气泡标识）；而且可以互转——但转换有代价：

• 对话流转成工作流：大模型/意图识别节点失去读历史能力，也不能绑定会话；
• 工作流转成对话流：自动补上 USER_INPUT 和 CONVERSATION_NAME 两个不可删的预置参数，并获得对话历史能力。

最常见的坑：要做多轮对话却建了任务工作流——结果没有对话窗口、接不了连续消息。判断方法很简单：需不需要上下文和连续交互？ 需要 → 对话流；只是「一进一出算个结果」→ 工作流。

五、实战：什么时候该混着用​

现实项目里很少「纯一种」，常见三种混合姿势：

1. 对话流里嵌「自主」节点：主流程用画布保证可控（鉴权、参数校验、结果格式），只在「需要模型发挥」的那一步用一个带插件的大模型节点；
2. 把工作流当「工具」给自主 Agent 调：把一个高确定性的子任务做成工作流，再挂给自主规划模式的 Agent 当插件——模型负责决定「什么时候用」，工作流负责「怎么稳定地做完」；
3. 多 Agent 模式：任务复杂到需要分工（检索 Agent、计算 Agent、审核 Agent）时，用主 Agent 统筹子 Agent——本质是「自主规划」的规模化版本。

我的建议：能从对话流开始的，就从对话流开始。因为「确定性的东西可测、可审计、好排障」，而自主规划一旦在生产上乱调工具/乱花钱，回头收窄成本很高。反过来，当流程分支多到画布画不动、且业务能容忍一定不确定性时，再上自主规划。

六、这三个概念，其实你已经见过​

Coze 这套划分不是它独有，本站其它系列讲的是同一件事的不同侧面：

• 图 vs Agent：LangGraph 入门 里的「状态图 + 条件边」就是对话流的通用版；createReactAgent 就是自主规划的通用版；
• 手写循环：frontend-agent 里那个 while (有 tool_use) —— 自主规划模式的本质就是这个循环，只是平台替你把它封装好了；
• 平台形态：主流低代码框架对比 里说过，Coze 这类 Agent 平台是「第三代低代码」；而 低代码二十年 里也提到，Coze Studio 开源时把完整的工作流引擎一并开源了。

一句话总结：对话流模式 = 把不确定性锁在节点里；自主规划模式 = 把不确定性交给模型。 选哪个，本质是问你：这个业务，能容忍多少不确定性？

参考​

• 工作流与对话流（Coze 官方文档）
• Coze 智能体三种运行模式完整解读（CSDN）
• Coze 底层区分三种 Agent 模式的核心机制（AI 编程社区）
• 任务工作流和对话工作流区别与选型指南（51CTO）
• 到底应该使用工作流还是对话流（三分钟搞懂）

声明：本文为公开资料整理 + 个人实践判断，无厂商合作；Coze 平台迭代快、且 cn/com 版本与开源版 Coze Studio 的命名可能不同，动手前请以你所用版本的官方文档为准。

这篇不空谈：我搭了两个最小应用（host / remote），用 webpack 5.111.0 + @module-federation/enhanced 2.9.0 真跑了一遍构建，把产物、stats、manifest 全抓出来给你看——MF 这套东西「到底生成了什么」，看完就有底了。

声明：本文配置与构建产物均为本机真实运行结果（含 mf-manifest.json 原文）。运行时（浏览器里加载远程模块）未实测，涉及运行时的部分我标明了依据，不编造效果。

一、一句话理解 MF​

把「另一个独立构建、独立部署的应用」里的模块，当成本地模块一样 import 进来，并且让它们共用同一份依赖（如 React、dayjs）。

关键点：host 的构建产物里并没有 remote 的代码——只有一个「远程地址」。真正的加载发生在运行期。

二、五个核心概念（一次记全）​

再加一个现代概念：manifest（MF 2.0 默认产出 mf-manifest.json）——把「暴露了什么、共享了什么、远程是谁」写成机器可读的元数据，运行时可以基于它加载，而不只是硬编码 remoteEntry.js 地址。

三、最小可跑配置（真实代码）​

remote 端（提供方）：

// remote/webpack.config.cjs
const { ModuleFederationPlugin } = require('@module-federation/enhanced/webpack');

module.exports = {
  mode: 'development',
  output: { publicPath: 'http://localhost:3002/', uniqueName: 'remote_app', clean: true },
  plugins: [
    new ModuleFederationPlugin({
      name: 'remote_app',
      filename: 'remoteEntry.js',
      exposes: { './Button': './src/Button.js' },      // 对外提供
      shared: { dayjs: { singleton: true, requiredVersion: '^1.11.0' } },
    }),
  ],
};

host 端（消费方）：

// host/webpack.config.cjs
plugins: [
  new ModuleFederationPlugin({
    name: 'host_app',
    remotes: { remote_app: 'remote_app@http://localhost:3002/remoteEntry.js' },  // 只是地址
    shared: { dayjs: { singleton: true, requiredVersion: '^1.11.0' } },
  }),
],

消费方代码就是普通的动态 import（这点最舒服）：

const { Button, fmt } = await import('remote_app/Button');

四、构建出来的是什么（本机真实产物）​

remote 的 dist/：

remoteEntry.js                   ← 远程入口（供 host 加载）
mf-manifest.json                 ← 元数据（暴露/共享/远程）
mf-stats.json                    ← 构建统计
__federation_expose_Button.js    ← 被暴露模块的产物
node_modules_dayjs_dayjs_min_js.js  ← 共享依赖被单独拆出

host 的 dist/：

main.js                          ← host 自己
mf-manifest.json
node_modules_dayjs_dayjs_min_js.js

注意 host 没有 remoteEntry.js（它不对外暴露），但同样有 dayjs 的独立 chunk——这就是 shared 在构建期的体现。

stats 里的关键证据（真实构建输出）​

provide shared module (default) dayjs@1.11.23 = ../node_modules/dayjs/dayjs.min.js
consume shared module (default) dayjs@!=1...1.1...0 (singleton) (fallback: ../node_modules/dayjs/dayjs.min.js)
remote remote_app/Button 6 bytes (remote) 6 bytes (share-init)
external "remote_app@http://localhost:3002/remoteEntry.js" 42 bytes

四行说明四件事：

1. provide：我提供 dayjs 1.11.23 给共享池；
2. consume：我要消费 dayjs，带 singleton 与 requiredVersion 约束，并准备了 fallback（共享池没有时用自带的那份）；
3. remote：remote_app/Button 被登记为远程模块（构建期只占 6 字节的“引用”）；
4. external：那个远程地址在产物里是个 external——构建期不下载、运行期才拉。

mf-manifest.json 写了什么（真实文件，节选）​

{
  "id": "remote_app",
  "metaData": { "globalName": "remote_app", "remoteEntry": { "name": "remoteEntry.js" },
                "pluginVersion": "2.9.0", "publicPath": "http://localhost:3002/" },
  "shared": [{ "name": "dayjs", "version": "1.11.23", "singleton": true,
               "requiredVersion": "^1.11.0",
               "assets": { "js": { "sync": ["node_modules_dayjs_dayjs_min_js.js"] } } }],
  "exposes": [{ "id": "remote_app:Button", "name": "Button", "path": "./Button",
                "assets": { "js": { "sync": ["__federation_expose_Button.js"] } } }],
  "remotes": []
}

host 侧的 manifest 则反过来（exposes 为空，remotes 有值）：

"remotes": [{ "federationContainerName": "remote_app", "moduleName": "Button",
              "alias": "remote_app", "entry": "http://localhost:3002/remoteEntry.js" }],
"exposes": []

这份 manifest 是 MF 2.0 相对 1.0 最大的“可运维性”升级：远程模块不再只靠一串 URL，而是有可枚举、可校验、可预加载的元数据。

五、运行时契约：remoteEntry 里有什么​

我把 remoteEntry.js 拆开看了一眼（grep 真实产物），里面出现这些 API 名：

get  init  initializeSharing  loadRemote  registerRemotes   （分别出现 27 / 16 / 6 / 4 / 3 次）

对应的运行时心智：

loadRemote + registerRemotes 让「远程是谁」变成运行时数据——这也是为什么 manifest 驱动加载、微前端平台化管理成为可能。

顺带一个真实数字：dev 模式下我的 remoteEntry.js 是 382 KB（未压缩、含 MF 运行时与共享逻辑），mf-manifest.json 只有 1.2 KB。生产构建会小很多，但体积要心里有数。

六、MF vs qiankun：不是替代，是不同层​

实践里两者常叠用：qiankun 负责「应用级别接入与隔离」（尤其是老应用、Vue2+React 混布），MF 负责「新应用之间的模块与依赖共享」。本站 qiankun 系列 讲的是前者的落地细节。

七、MF 2.0 带来了什么​

从本机实测的包和官方资料看，2.x 的主要变化：

• @module-federation/enhanced（2.9.0）：一个插件把「暴露/消费/共享/类型/manifest/devtools」都带上，不再手拼一堆插件；
• 框架无关 runtime（@module-federation/runtime 2.9.0）：不绑定 webpack，可在任意环境驱动加载；
• manifest 与 mf-stats.json：可枚举、可托管、可做预加载与健康检查；
• 运行时插件体系（runtime plugins）：重试、降级、日志、缓存策略可以插件化；
• 多构建器支持：Rspack（@rspack/core 实测版本 2.2.4）与 Vite（@module-federation/vite 1.21.6）都有官方方案；
• 类型支持：配合 dts 插件可以给远程模块生成/注入 TS 类型（不然 import('remote_app/Button') 全是 any）。

八、五个真实的坑（先想清楚再上）​

1. 依赖双实例：React 这类库没共享成功 → hooks 报错、context 不通用。核心解法就是 singleton: true + 严格的 requiredVersion，并理解「版本协商失败会 fallback 到各自那份」这件事（上面 stats 里那条 consume shared module ... (fallback: ...) 就是它）。
2. 远程挂了怎么办：MF 默认不会帮你优雅降级。生产要自己加超时、重试、兜底 UI（remoteEntry 拉不到时整块区域降级），这也是 runtime plugin 的用武之地。
3. 远程地址不是无限的：remoteEntry.js 是运行期拉的，意味着跨域 CORS、CDN 缓存策略、版本发布顺序都要设计（典型做法：remoteEntry 短缓存/不缓存，带 hash 的 chunk 长缓存）。
4. 样式没有隔离：MF 只共享模块，不做样式沙箱——CSS 命名冲突、全局样式污染要自己用 CSS Modules / 命名空间 / Shadow DOM 解决。
5. 本地开发体验：remote 没起时 host 直接报错。约定好本地端口、或用 manifest 指向测试环境远程，能省很多扯皮。

九、选型清单​

一句话：MF 解决的是「模块与依赖的跨应用复用」，它的收益来自共享，它的风险也来自共享——共享得越深，团队之间的构建、版本、发布节奏就越需要对齐。

参考​

• Module Federation 官方站（2.0 文档）：module-federation.io
• webpack 官方 Module Federation 指南：webpack.js.org/concepts/module-federation
• 本站对照：qiankun 微前端系列
• 版本事实（本机 npm view 实测，2026-09）：webpack 5.111.0、@module-federation/enhanced 2.9.0、@module-federation/runtime 2.9.0、@module-federation/vite 1.21.6、@rspack/core 2.2.4
• 构建产物与 manifest 节选：本机 /tmp/mf-lab 实测（webpack 5.111.0 + MF enhanced 2.9.0，dayjs 1.11.23）

这两年冒出来的两个热词正好对应这两个焦虑：SDD（Spec-Driven Development，规格驱动开发） 管「怎么让 AI 做对的东西」；FDE（Forward Deployed Engineer，前沿部署工程师） 管「怎么让 AI 真的在客户的生产环境跑起来」。一个是方法论，一个是角色；看似不搭，其实是同一件事的两面。

这篇把它们讲清楚：是什么、为什么现在火、具体怎么做、以及有哪些坑。

术语歧义说明（先排除）：SDD 也常被当作「Software Design Document（软件设计文档）」、FDE 也有人指「Frontend Development Engineer（前端开发工程师）」。本文按 2025–2026 年 AI 工程语境写：SDD = Spec-Driven Development，FDE = Forward Deployed Engineer。若你问的是另一种含义，告诉我我另写一篇。

文中行业数据来自公开报道，统计口径与时点不一，已尽量标注来源，引用请以原文为准。

一、SDD：别再直接让 AI 写代码​

1.1 它要解决的痛​

先说一个很多人踩过的坑：把模糊需求丢给 AI，它一定会自由发挥——顺手改掉公共组件、删掉历史兼容逻辑、自行补全你没说的需求，最后留下难以维护的代码。问题不在「AI 不会写」，而在人没把规格讲清楚。

Vibe Coding（凭感觉写）在小原型上很爽，但系统一大就会「悄悄失败」：上下文漂移、逻辑冲突、技术债累积。SDD 的主张很直接：先写清规格，再让 AI 按规格开发。

1.2 核心比喻：规格是「人和 AI 之间的契约」​

• 人负责 What / Why：范围、边界、关键决策、验收标准；
• AI 负责 How：任务拆解、代码实现、跑测试的闭环；
• 规格是**「活契约」（living contract）：它是唯一事实来源**，代码只是它的产物之一。

把安全要求、性能指标、设计系统这些非功能性需求前置写进规格，AI 从第一行代码起就在合规轨道上——而不是等 code review 才发现跑偏。

1.3 典型工作流（七步）​

各阶段的关键产出（不同工具命名略有差异，但思路一致）：

注意两个细节：

1. 阶段之间要设人工审查关卡（review gates）——出问题时先判断是「需求错、设计错、任务拆错」还是「代码写错」，而不是反复打补丁；
2. Specify 阶段刻意不谈技术——把「做什么」和「怎么做」分开，是这套流程最值钱的纪律。

1.4 工具生态（2026）​

1.5 成熟度分级（很重要的一组坐标）​

SDD 不是「非黑即白」，公开资料把它分了几档：

Spec-First  规范先行：先写 spec，再让 AI 写代码
    ↓
Spec-Anchored 规范锚定：spec 长期存在，作为改动的锚点（适合老项目）
    ↓
Spec-as-Source 规范即源码：人只维护 spec，代码是派生物
    ↓
Spec-to-Application 规范直接编译成应用（最激进）

给团队的建议：从 Spec-First 起步——只要「先写规格再动手」这一条纪律，收益就很大；Spec-as-Source 这类激进形态，等你团队的规格质量和评审机制成熟了再说。

1.6 SDD vs Vibe Coding vs TDD​

• vs Vibe Coding：Vibe 追求速度与探索，适合原型；SDD 追求准确与可维护，适合严肃系统；
• vs TDD：互补，不是替代。SDD 更靠前，解决「到底要做什么」；TDD 更靠后，解决「代码有没有做到」。没有 SDD 的 TDD，可能只是把错误的需求测得很完整。

1.7 什么时候不必上 SDD​

一次性脚本、极小改动、低风险文案调整——上 SDD 是给自己找事。它的甜点区是：跨模块变更、多人协作、高要求功能（支付/权限/风控）、需要长期维护的系统。

二、FDE：把 AI 真正塞进客户的生产环境​

2.1 它是什么​

FDE 是长期嵌入客户现场、亲手写生产代码、把产品（如今多是 AI 系统）在客户自己的环境里跑通、并对生产结果负责的工程师。 两个关键词：嵌入、负责。

它的源头是 Palantir（约 15 年前）：再强的平台，交到客户手里也会被旧系统、脏数据、高度定制的工作流拖住；传统「卖软件 → 培训集成商 → 撤离」只会做出漂亮 demo。Palantir 的解法是把最顶尖的全栈工程师直接派进客户现场，对着真实数据写生产代码、亲自负责上线与运维。

Palantir 内部把 FDE 叫 「Delta」（Δ），做产品的工程师叫「Dev」，一句经典概括是：

「Dev 是为很多客户构建一个能力，Delta 是为一个客户构建很多能力。」

还配了一套 Echo × Delta 结构：Delta 写代码，Echo（部署策略师，Deployment Strategist）是客户行业专家，用「现场的语言」挖需求。

2.2 和 SE / SA / TAM / 驻场开发的区别​

关键差别只有两个：是否提交生产代码、责任的终点在哪。

• 售前/解决方案架构师：技术选型、架构规划，签约后往往交接离开；
• 顾问：交付的是报告与建议，不是跑起来的系统；
• 驻场外包：卖劳动力，听指挥干活，经验留在客户那边；
• FDE：写进客户仓库、从 PoC 一直负责到生产运维，并把现场经验回流成可复用能力。

有个一句话的真伪测试：

问：「系统上线六周后在生产挂了，谁负责？」

• 答「客户 IT 团队」→ 这个组织里没有 FDE 职能；
• 答某个具体的人（有系统权限、有责任）→ 那才是 FDE。

2.3 为什么在 AI 时代爆红​

业界的共识判断是：部署鸿沟（Deployment Gap）远大于能力鸿沟（Capability Gap）——模型之间的差距，远没有「能不能在真实业务里用起来」的差距大。

数据支撑（来源时点请注意）：

• MIT Project NANDA《The GenAI Divide》调查 500+ 家企业：约 95% 的生成式 AI 项目对损益没有可量化影响；成功的少数普遍做了深度定制与流程整合——这正是 FDE 干的活；
• 2025 年 FDE 职位年增幅被报道高达 1,165%（Bloomberry 研究，报道于 CIO Taiwan）；英国《金融时报》统计 2025 年 1–9 月 FDE 职缺月增超 800%；
• 供给端稀缺：有猎头估计，全球真正「为企业部署过生产级 AI 代理系统」的工程师不到一万人。

AI 系统为什么不能「自助部署」：工作流必须定制、数据集成极复杂、幻觉输出要有人管、合规无法模板化。Palantir 把这套方法论称为 Ontology（本体论）——不是「把数据接进来」，而是把企业的对象、关系、规则、动作、权限、反馈，翻译成 AI 能理解、系统能执行、组织能治理的结构。

2.4 谁在抢这类人​

• OpenAI：组建部署相关公司（报道称联手 PE 投入数十亿美元），并收购 AI 咨询公司补充 FDE 团队；
• Anthropic：与多家金融机构合资做企业 AI 服务，公开招聘 FDE；应用 AI 团队扩编，岗位偏向「Applied AI Engineer」；
• Google Cloud：设立 GenAI FDE 职位，内部代号 Embedded Builder，计划招募数百人；
• 其它：Scale AI、xAI、Databricks、Cohere、Cursor、Salesforce 等；咨询侧也有对应变体（如 Accenture 的 RDE）。

薪酬参考（报道数据，时点以来源为准）：Anthropic FDE 约 20–30 万美元；OpenAI 总包约 35–55 万美元区间；Palantir 历史中位约 16.7 万美元。

2.5 日常与技能​

约一半时间写代码（集成、数据转换、把生产级应用 ship 出去），一半面向客户（需求探查、现场演示、结对编程），出差比例可达 50%。

技能要求在四个方向都有生产级深度：Python 与 LLM 集成、RAG、MLOps/生产运维、云原生；此外是业务流程理解力、沟通带宽，以及「在模糊环境里独立推进」的能力——Anthropic 的岗位要求里甚至写了「保持低自我感与协作态度」。

一个直观案例：OpenAI 曾派 FDE 协助农机厂商 John Deere，做出把化学喷洒量降低 60%~70% 的智慧农业工具。

2.6 风险：被用滥的「弱版本 FDE」​

热度一高，标题就会被滥用：只做演示、只接工单、不对生产结果负责的岗位也自称 FDE——招来的人 burnout，客户也拿不到价值。

判断标准仍然是 ownership 落在哪：JD 里只写「支持客户」「做技术演示」，却从不提「写生产代码」「对上线结果负责」，那大概率不是真 FDE。

三、为什么这两个词是一体两面​

对个人的启发（尤其我们这些写前端/写业务的工程师）：

1. 写作与定义能力正在升值：能不能把模糊需求写成可执行、可验证的规格，正在变成核心技能——这跟我们这个 blog 一直在强调的「schema/协议/契约」是同一件事（见 Zod 系列、MCP）；
2. 「把东西跑起来」比「写出来」更难：FDE 的流行说明，集成、部署、运维、对结果负责这些「最后一公里」的活，AI 短期内替不掉；
3. 两条都能马上试：给下一个需求先写一页规格（Spec-First 的最小版本）；给手头的项目多做一点「上线后谁负责」的功课。

顺带一提：本站 frontend-agent 系列 手写过 agent 的工具循环，InkOS 拆解 里那套「模型提议、宿主执行、以落盘为准」——本质也是同一思路：把意图固化成约束，让机器在约束里干活。SDD 只是把这条原则搬到了整个软件生命周期。

参考​

• 字节面试官：别再直接让 AI 写代码了，先学会 SDD 规格驱动开发（阿里云开发者）
• 超越 Vibe coding！Spec-Driven Development 如何降低 AI 写程式的混乱（TechOrange）
• Spec-Driven Development in 2026（Devoteam）
• FDE 前线部署工程师，让 AI 真正落地的角色（CIO Taiwan）
• OpenAI、Anthropic 都开始押注 FDE，FDE 才是 Agent 时代的 PMF 范式？（BAAI Hub）
• 企業買了 AI 卻跑不起來，FDE 成為科技業最搶手的職位（TechOrange）
• FDE 前線部署工程師，你看好嗎？（阿里云开发者）

声明：本文为行业观察整理，无任何厂商合作；涉及数字均来自上述公开来源，统计口径与时点不一，请以原文/官方为准。方法论部分（七步流程、成熟度分级）为公开资料的归纳，不同工具实现有差异。

这篇做三件事：先把它们分类（不同类的框架解决不同问题）→ 逐家拆定位与技术路线 → 给一张选型决策表和几个必踩的坑。文中的版本号与开源协议都来自 npm 元数据实测（2026-09），其余事实标注了来源。

一句话先给结论：做中后台页面 → amis；做复杂表单 → formily；做运营活动页 → tmagic / h5-Dooring；想自己造一个低代码平台 → lowcode-engine。

一、先分类：它们根本不在一个赛道​

记住这条分界线：前三类是「用低代码」，最后一类是「造低代码」。选型时先问自己站在哪一边。

二、逐家拆解​

1. amis（百度）——JSON 换页面​

• 定位：MIS（管理信息系统）页面生成工具，npm 描述原文就一句「一种 MIS 页面生成工具」；
• 核心用法：写一段 JSON 配置，内核渲染成可交互页面；内置 100+ UI 组件，表格/表单/图表/CRUD 一站式，数据源与联动也写在配置里；
• 实测版本/许可：amis@6.13.0，Apache-2.0，仓库 baidu/amis；
• 适合：中后台 CRUD、内部工具、报表页——前端人手不够时最速成；
• 不适合：高度定制交互、复杂动画、C 端展示（它是「配置驱动」，不是「自由前端」）；
• 坑：JSON 一长就难维护（需要拆分成 schema 片段/复用配置）；复杂逻辑会想在 JSON 里写表达式，越写越像一门残缺的编程语言。

2. formily（阿里）——表单领域的「性能 + 协议」​

• 定位：动态表单/字段联动的解决方案，起家于「React 后台表单渲染性能」，把每个字段做分布式管理，字段变化只重渲染自己；
• 核心抽象：@formily/core（响应式内核）+ @formily/react / @formily/vue（框架适配）+ JSON Schema 描述表单（支持标准 JSON Schema 扩展）+ designable 设计器；
• 实测版本/许可：@formily/core@2.3.7、@formily/react@2.3.7、@formily/vue@2.3.7，MIT，仓库 alibaba/formily；
• 适合：表单即业务的系统（审批、配置台、B 端 SaaS）、需要字段级联动/校验/性能的场景；
• 不适合：不是页面搭建器——别拿它去拼整页布局；
• 坑：学习曲线比 amis 陡（要先理解它的响应式与字段模型）；脱离它的设计器单独用时，Schema 手写成本不低。

3. tmagic-editor（腾讯）——运营页面的拖拽生产平台​

• 定位：可视化页面搭建平台，源自腾讯魔方平台，用于快速生产 H5 / PC / TV 页面，在腾讯视频、腾讯会议等业务里使用；
• 技术路线：Schema + 沙箱运行时渲染，产物是一份 JSON/JS schema（DSL）；runtime 提供 vue2 / vue3 / react 多框架实现；
• 关键事实：官方能力表里**「下载页面源码：不支持」（tmagic 发布文档）——它是运行时路线**，不是出码路线；
• 实测版本/许可：@tmagic/editor@1.7.13、@tmagic/core@1.7.13，Apache-2.0，文档 tencent.github.io/tmagic-editor；
• 适合：运营活动页、专题页、需要「非技术人员自助搭建」的场景；
• 不适合：想要最终拿到可维护源码交付的项目（它不给你出码）；
• 坑：物料库要自己开发维护——搭建平台的价值 80% 在物料，不投入物料就是空壳。

4. h5-Dooring——H5 可视化搭建的最佳实践​

• 定位：面向 H5 落地页/活动页的可视化配置方案，作者 MrXujiang；技术栈以 React + TypeScript 为主，配套 Node 后端，另有 PC 版与 Electron 桌面版；
• 特点：拖拽操作、上手快，强调 H5 场景的「搭建 → 预览 → 下载源码」链路（源码可导出，便于交付给开发继续维护）；
• 注意：npm 上没有同名包（我查过 h5-dooring 不存在），它是仓库形态的项目，用的时候按仓库 README 走；
• 适合：营销活动、落地页、创业团队快速出页面；
• 不适合：复杂中后台（那是 amis/lowcode-engine 的地盘）；
• 坑：社区项目 vs 大厂项目的维护节奏差异；深度定制要读源码。

5. lowcode-engine（阿里）——「造平台」的内核​

• 定位：一套面向扩展设计的企业级低代码技术体系（npm 描述原文），来自阿里/钉钉宜搭团队，理念是「最小内核、最强生态」；
• 它产出两份数据（这是理解它的关键）：
  • 资产包 assets：物料名称/包名/获取方式 → 对应《低代码引擎资产包协议规范》；
  • 页面 schema：页面结构、生命周期、代码信息 → 对应《低代码引擎搭建协议规范》；
• 两条消费路径：交给渲染模块（运行时，能在编辑器里继续改）或交给出码模块（@alilc/lowcode-code-generator，生成可运行源码）；
• 实测版本/许可：@alilc/lowcode-engine@1.3.4，MIT，站点 lowcode-engine.cn；
• 适合：企业自建低代码平台、要把搭建能力嵌进自己产品、需要插件/物料/设置器完整扩展点；
• 不适合：只想快速做个页面——用它等于「用造车工具造自行车」；
• 坑：学习曲线最陡（插件化 + 协议 + 渲染/出码双路径）；物料协议是长期成本，一旦自建平台，物料维护就是持续投入。

三、绕不开的技术路线：运行时渲染 vs 出码​

这五家里除了 formily（表单库、不涉整页），其余都要面对这个选择：

• 运行时路线：amis、tmagic 是代表（tmagic 官方明确不支持下载源码）；
• 双路线：lowcode-engine 同时提供渲染与出码（出码文档 里列了三个适用场景：极致打开速度/降低 LCP·FID、老项目 + 新需求想 merge 源码、协议无法描述的代码逻辑）；
• 代价：出码意味着「一次性的交接」——交出源码后，页面就脱离了低代码编辑器，后续改动回到 ProCode 流程。想清楚「这个页面是要长期拖拽维护，还是交付后交给开发」，路线就定了。

四、一张选型表​

五、几个必踩的坑（选型时先想清楚）​

1. 「低代码省人力」是错觉的一半：省的是页面搭建，不省物料/组件/权限/数据源/发布——这些才是长期成本，尤其自建平台（lowcode-engine）时；
2. Schema 会膨胀：无论 amis 的 JSON 还是 tmagic 的画布 Schema，页面一复杂就会出现「配置比代码还难读」；提前定好拆分与复用策略（片段化、物料化）；
3. 协议即锁定：用了谁的 Schema，就绑定谁的协议与运行时；lowcode-engine 的物料协议生态最大，也意味着迁移成本最高（这也是它被称为「事实标准」的另一面）；
4. 出码不是银弹：出码解决性能与交付，但牺牲了后续的可视化维护；反过来运行时路线牺牲性能换灵活性。按页面生命周期选，别按喜好选；
5. 表单场景别硬上页面搭建器：复杂联动/校验用 formily 这类领域引擎，比在页面搭建器里拼表单稳定得多。

六、放到 AI 时代看​

上一篇说过：AI 时代的低代码，内核从「编排 UI/流程」变成「编排 Agent」。两者并不冲突，而是两条互补的谱：

• 确定性低代码（本篇这些）：拖拽/配置产出确定行为的页面与流程，适合稳定、可审计、要长期维护的界面；
• 概率性编排（Dify/Coze/n8n）：用自然语言编排不确定的模型与工具，适合探索型、变化快的自动化。

正在出现的交叉点：物料协议 + 工具协议。当 lowcode-engine 这类引擎把「能力」描述成标准化的物料/资产包时，它和 MCP 那套「把能力描述成工具」的思路其实是一回事——描述清楚能力，谁来调用都可以（人拖拽、或 Agent 调用）。这大概就是「低代码平台」在 AI 时代最可能的演化方向。

参考​

• Low-Code Engine 出码文档（出码适用场景与代价）
• tmagic-editor 文档（发布与「下载源码不支持」）
• 10 个前端低代码开源项目盘点（腾讯云社区）
• 前端低代码工具盘点（掘金）
• 低代码平台架构深度剖析（潘征）
• 本 blog 姊妹篇：低代码二十年：从拖拽表单到编排 Agent
• 版本/许可数据：本机 npm view <包> version license 实测（2026-09）

声明：本文无厂商合作；各家能力迭代快，选型前请以官方文档与最新版本为准。文中「适不适合」是基于公开资料与社区经验的判断，欢迎讨论。

这篇聊三件事：低代码的发展史、它当下的真实现状，以及 AI 时代这几家代表平台各自是什么、怎么选。

文中多数市场数据来自公开报道，统计口径与时点不一（尤其 star 数），已在文中标注时点，引用时请以官方为准。判断类观点是我的个人看法，欢迎拍砖。

先给三个判断​

1. 低代码不是新概念，它是「抽象层不断上移」这条主线的又一段。 机器码 → 汇编 → 高级语言 → 框架 → 可视化控件 → 流程编排 → 现在：自然语言 + 工具编排。每一代都在把「写代码」缩小成「描述意图」。
2. 2021 年前后那一轮低代码有过明显的祛魅期。 「低代码到底是给业务人员还是给程序员的」「复杂场景一定撞天花板」「平台锁定」——这些质疑至今没有消失，AI 也没有自动解决它们。
3. AI 时代的低代码，内核从「编排 UI/流程」变成了「编排 Agent」。 但生产上更常见的形态不是「全自动 Agent」，而是确定性的工作流里嵌几个智能节点——这恰好是 Dify / Coze / n8n 主流用法。

一、发展史：术语只有十年，理念有四十年​

「低代码（Low-Code）」这个术语是 Forrester 在 2014 年提出的（"低代码/零代码"用来描述那类「极少写代码就能快速构建、配置、部署应用」的技术与工具）。但它的理念要早得多：

一句话概括这条线：抽象对象一路从「语句 → 控件 → 表单/流程 → 模型/工具」上移。每上移一层，能参与的人就多一批，但「天花板」也会重新出现。

二、三代低代码：抽象不同，天花板不同​

同样是「低代码」，市面上的产品其实分三大类，别混着比：

前两代解决的是「界面与流程谁来做」；第三代解决的是「模型与工具谁来编排」。AI 时代热起来的，正是第三代。

三、AI 时代的代表平台：Dify / Coze Studio / n8n​

这三家经常被放在一起比，但它们出身和基因完全不同：

Dify —— 开源 LLMOps 的「中间层」​

• 2023 年 5 月开源，自部署版 Apache 2.0，Python(Flask) 后端 + TypeScript 前端，由 LangGenius 维护；
• 定位：可视化工作流 + RAG + Agent + 可观测的一站式 LLMOps。拖拽节点支持条件分支、循环、并行、HTTP、代码执行；RAG 有文档解析/分块/混合检索/重排；原生支持 MCP 双向（既能调外部 MCP Server，也能把自己暴露成 MCP 端点）；
• 规模（来源口径差异大，注意时点）：早期评测普遍把 Dify 称为「调研中唯一真正意义上的低代码平台」；GitHub star 有报道称从 2025 年中的 10 万级增长到 2026 年中的 15 万级（如 2026-07 某报告核到 14.8 万、2026-08 某文称 15.3 万）；
• 强项：企业私有化 + 复杂工作流 + 成熟社区；弱项：微服务组件多、运维与升级复杂度高（大版本可能动数据库 schema），社区版与企业版能力有差距（多路召回/重排/SSO/审计等）。
• 选它的场景：要私有化、要 RAG、要复杂流程、要自己掌控数据。 —— 参考：Dify 官方、Dify 深度评测（2026）、Dify 15 万 Stars 现状

Coze Studio —— 大厂开源的「生态选手」​

• 2025 年 7 月 26 日，字节把扣子（Coze）的核心组件 Coze Studio 与 Coze Loop 在 GitHub 开源，纯 Apache 2.0、无附加条款，可免费商用、修改、本地部署（据开源后一个月报道 star 已 6K+）；
• 技术：后端 Go + DDD 模块化设计，Docker 一键部署（说法是最低 2C4G 可跑）；
• 强项：许可证最宽松（金融/政务等强合规场景友好）、背靠火山引擎/飞书/抖音生态、上手快；弱项：开源版能力收敛（有对比称开源版暂不支持工作流直接发布 API、知识库 API、MCP，LLMOps 依赖独立的 Coze Loop），社区比 Dify 新、长期路线跟字节战略绑定。
• 选它的场景：中小企业快速验证、强合规要商用、想用大厂生态。 —— 参考：Coze-Studio 还是 Dify？、「扣子开源」深度解析

n8n —— 「自动化老炮」长出的 AI Agent​

• 出身是 工作流自动化（2019 起），比 AI 热早得多；1000+ 集成是它的护城河；
• 许可证要看清楚：n8n 用的是 Sustainable Use License（SUL），自称 fair-code——源码可见、可自托管修改，但限制商业再分发（不能拿它做竞品/对外提供服务）。它不是 OSI 意义上的开源（2022 年从 Apache-2.0 + Commons Clause 改过来）；
• 增长（据公开报道）：2025 年 10 月 C 轮 1.8 亿美元、估值 25 亿美元；2026 年 5 月 SAP 战略投资并把它嵌进 SAP 的 Joule Studio，报道称估值翻倍到 52 亿美元，GitHub star 18 万级、超 1000 个集成；
• AI 能力：画布上的 AI Agent 节点（Chat Model 当大脑）+ 集成 LangChain/LangGraph、多 Agent、Human-in-the-loop、guardrails、evaluations；
• 另一种声音：有评测认为 n8n 的 agent 故事被夸大——「本质是带额外步骤的 API 调用」，生产级的记忆管理、动态工具选择、错误恢复仍不足；历史上也出过 SSRF 等 CVE。这类批评值得听。 —— 参考：n8n 估值翻倍至 52 亿美元（SAP 投资）、Is n8n Dead in 2026?（批评视角）

其它别忽略的​

• 开源编排：LangFlow、Flowise、FastGPT、RAGFlow（RAG 场景专精）；
• SaaS 自动化：Zapier、Make（也在加 AI）；
• 另一条路线——AI 直接生成代码：v0 / Lovable / Bolt 这类「描述即出应用」，它和低代码是竞争关系（都是降低开发门槛）；
• 国内云厂商：阿里云百炼、百度千帆、腾讯元器等，本质是把模型 + 编排打包成云服务。

四、现状：2026 年的三条战线​

1. 企业默认「自托管开源」。数据合规 + 成本，让 Dify / Coze Studio 的私有化部署成为主流选择，「云 SaaS 试玩、私有化上线」是常见路径。
2. MCP 正在统一「工具集成」。以前每个平台各写各的插件/连接器，现在大家往 MCP 上靠——工具一次实现，多平台复用。这对用户是好事：平台之间的可迁移性变强了（也为将来「换平台不重写」埋下伏笔）。
3. 从「工作流」到「Agent」，又回摆到「工作流里嵌 Agent」。纯 Agent（全靠模型临场决策）在生产上不够稳；纯 DAG 工作流又不够灵活。于是主流形态是：外层用确定性的工作流保证可控，内层在关键节点用 LLM/Agent 处理模糊问题。

五、AI 并没有自动解决低代码的老问题​

低代码被诟病多年、而 AI 也没送走的那几件事：

• 治理与权限：谁能改、改了审不审、线上能否回滚（本 blog 在 InkOS 的确认闸门 里聊过类似思路）；
• 集成与数据一致性：跨系统的副作用、事务、失败重试——AI 节点让不确定性更强，这些更要兜底；
• 可观测与成本：token 成本、链路追踪、评测（evaluations）都要配套；
• 厂商锁定与运维：许可证（Dify 的自部署 Apache 2.0 vs n8n 的 SUL）、导出/迁移能力、升级破坏性（Dify 大版本动 schema 是已知痛点）；
• 安全：自托管平台的暴露面、历史 CVE（n8n、Dify 都有过）。

核心观点：AI 降低的是「起步成本」，不降低「交付责任」。 画布拖得再快，「上线后谁来兜底」这个问题一分都没少。

六、怎么选（一张决策表）​

七、写给前端：这其实是前端的主场​

低代码平台拆开看，无非两块：前端是编辑器（画布 + 属性面板 + 节点渲染），后端是执行器（DSL 解释 + 调度 + 集成）。所以对前端开发者，这里机会很直接：

• 可视化画布：节点/连线/拖拽/缩放/撤销重做，全是前端硬功夫（本 blog 聊过的 d2 图表、虚拟列表 react-virtuoso 都用得上）；
• DSL 与类型安全：工作流本质是一份 JSON DSL——用 zod 做运行时校验 + TS 类型推导是标配；这正是本 blog 已沉淀的能力；
• 协议层：想理解「模型 + 工具」的底层，看 llm-format 系列（两家 chat 协议对照）与 MCP（工具集成的开放协议）；
• 状态管理：复杂编排画布的状态，和 Pinia 那套「组合式 store」是同一个问题域。

一句话：低代码平台的「低代码」，是给用户的；平台本身的代码，是前端和后端的硬活。

参考​

• 低代码的起源和走过的路（腾讯云开发者）
• 回顾「低代码」历史发展（阿里云开发者）
• Coze-Studio 还是 Dify？企业级 AI Agent 开发选型
• 「扣子开源」深度解析
• Is n8n Dead in 2026?（含许可证、批评与安全）
• n8n 估值翻倍至 52 亿美元，SAP 战略投资并嵌入 Joule Studio
• Dify 深度评测 2026 ｜ Dify：15 万 Stars 的开源 Agent 工作流平台

立场声明：本文不含任何厂商合作；数据以文中标注来源为准，star/估值等数字随时点快速变化，决策前请查官方与最新统计。

这篇把 ReAct 讲透：它是什么、为什么重要、格式长什么样，然后用零依赖的纯 Node 手写一个真的能跑的 ReAct 智能体。最后是重点——我在本机真实跑出来的四个坑，其中有两个非常隐蔽：一个是不报错、只是静默返回空，另一个是模型会伪造工具的返回结果，然后基于伪造值自信作答。

声明：本文所有代码均在本机真实运行，走 DeepSeek 的 Anthropic 兼容端点（deepseek-v4-flash，一个推理模型）。所有输出、stop_reason、token 数都是实测值，不是我编的示意。

一、ReAct 是什么：一句话和它的出处​

论文是 《ReAct: Synergizing Reasoning and Acting in Language Models》（arXiv:2210.03629），作者 Shunyu Yao、Jeffrey Zhao、Dian Yu、Nan Du、Izhak Shafran、Karthik Narasimhan、Yuan Cao（普林斯顿 + Google Research），发表在 ICLR 2023。

它要解决的问题在论文摘要里写得很直白：当时大模型的能力被分开研究了——

• 会推理的（chain-of-thought，思维链）：让模型一步步想，但它只能想，不能查。想错了一步，后面全错，而且没有任何外部信息能把它拉回来，于是幻觉和错误传播（hallucination and error propagation）就是 CoT 最大的毛病；
• 会行动的（action plan generation）：让模型输出动作，但它只做不想，没有推理痕迹，遇到意外情况不会调整，人也没法判断它为什么这么干。

ReAct 的提案就是让这两件事交替发生：

生成推理轨迹（reasoning traces）和任务动作（task-specific actions），交错进行。

论文对「协同」的解释是我觉得最值得记住的一句：推理轨迹帮模型归纳、追踪、更新行动计划，并在遇到异常时处理异常；而动作让模型能接触外部资源（知识库、环境），拿到额外信息。

一句话概括：Thought（想）与 Action（做）交替，每次行动的结果 Observation（看）再喂回去影响下一步的想。

它当年的实验结果（论文报告）：在 HotpotQA（多跳问答）和 FEVER（事实核查）上，ReAct 通过调用一个简单的 Wikipedia API，缓解了 CoT 的幻觉和错误传播；在 ALFWorld 和 WebShop 两个交互式决策任务上，用仅仅 1–2 个上下文示例，就比模仿学习和强化学习方法的绝对成功率高出约 34% 和 10%。而且论文发现最好的方案是 ReAct 与 CoT 结合——既用模型内部知识，也用外部检索。

二、它长什么样：三段式文本协议​

ReAct 最朴素也最本质的形态，就是纯文本的三行交替：

Thought: 我现在想到什么      ← 模型生成（推理轨迹）
Action: search[三体]         ← 模型生成（与环境交互的动作）
Observation: 三体 / 作者: 刘慈欣   ← 环境返回（真实信息）
Thought: 作者拿到了，下一步查出生地   ← 再想
Action: search[刘慈欣]
Observation: ...

三个角色分工必须清楚，这是理解后面所有坑的前提：

Observation 绝对不能由模型生成——一旦它自己写了，整个循环就退化成「模型自问自答」，外部工具形同虚设。后面第四节我会用真实实验证明：它真的会写，而且写得很像真的。

注意论文里 wiki 环境的 action space 就三个：search[实体]、lookup[关键词]、finish[答案]。动作空间是设计出来的白名单，这也呼应了我之前写的「工具白名单即安全边界」。

三、为什么「交替」是关键：CoT vs 纯行动 vs ReAct​

ReAct 的精髓在于那个 Observation 构成的纠错回路：模型猜错了，工具返回真实值，下一轮它就得改。这是它比 CoT「更可信」的结构性原因，也是论文强调 human interpretability（可解释性）的来源——Thought 那一行虽然是模型写的，但它给了你一条能读、能查的决策链。

四、手写一个：完整代码（零依赖）​

一个完整可跑的 ReAct 就一个文件，只需要 Node 18+（自带 fetch）。下面这段我直接跑给你看。

// react.mjs —— 手搓 ReAct：纯文本 Thought → Action → Observation 协议，零依赖
const BASE = (process.env.ANTHROPIC_BASE_URL || '').replace(/\/+$/, '');
const KEY = process.env.ANTHROPIC_AUTH_TOKEN || '';
const MODEL = process.env.ANTHROPIC_MODEL || '';

// ---------- 1. 工具：论文里的 action space 就这三种 ----------
const KB = {
  三体: { 作者: '刘慈欣', 类型: '长篇科幻小说', 首次发表: '2006 年《科幻世界》连载' },
  刘慈欣: { 出生地: '山西省阳泉市', 代表作: '三体、球状闪电', 职业: '科幻作家' },
  阳泉市: { 所属省份: '山西省', 人口: '约 131 万（2020 年七普）', 别名: '山城' },
  山西省: { 省会: '太原市', 人口: '约 3491 万（2020 年七普）', 简称: '晋' },
};

const tools = {
  search: (arg) => (KB[arg] ? `${arg} / ${Object.entries(KB[arg]).map(([k, v]) => `${k}: ${v}`).join(' | ')}` : `没有找到「${arg}」的条目`),
  lookup: (arg) => {
    const hits = [];
    for (const [k, fields] of Object.entries(KB))
      for (const [f, v] of Object.entries(fields)) if (String(v).includes(arg)) hits.push(`${k} / ${f}: ${v}`);
    return hits.length ? hits.join('\n') : `没有找到包含「${arg}」的信息`;
  },
};

// ---------- 2. ReAct 的 prompt：格式约定 + 一个 one-shot 范例 ----------
const SYSTEM = `你是一个 ReAct 智能体。可用工具（每次只能用一个）：
- search[实体]：搜索某个实体的条目
- lookup[关键词]：在整个知识库里检索包含该关键词的信息
- finish[答案]：给出最终答案并结束

严格按格式逐步推理，每一步输出一行 Thought 和一行 Action：

Thought: 你现在想到什么
Action: search[三体]

规则：
1. 每次回复只能有一个 Action，且必须是 search[..] / lookup[..] / finish[..] 三种之一；
2. 绝对不要自己写 Observation —— 那是环境返回给你的，你写了也算无效；
3. 拿到足够信息后必须用 finish[答案] 结束。

示例：
Question: 苹果公司的 CEO 毕业于哪所大学？
Thought: 先搜苹果公司，找到它的 CEO。
Action: search[苹果公司]
Observation: 苹果公司 / CEO: 蒂姆·库克
Thought: 拿到 CEO 名字了，再查他的毕业院校。
Action: lookup[蒂姆·库克]
Observation: 蒂姆·库克 / 毕业院校: 奥本大学
Thought: 信息齐了。
Action: finish[奥本大学]`;

// ---------- 3. 一次模型调用：停在 Action 行末尾 ----------
async function callModel(messages) {
  const res = await fetch(`${BASE}/v1/messages`, {
    method: 'POST',
    headers: { 'content-type': 'application/json', 'x-api-key': KEY, 'anthropic-version': '2023-06-01' },
    body: JSON.stringify({
      model: MODEL,
      max_tokens: 2048,
      system: SYSTEM,
      messages,
      stop_sequences: ['\nObservation:'], // ★ 关键：让模型不能自己把 Observation 编出来
    }),
  });
  const json = await res.json();
  if (!res.ok) throw new Error(`API ${res.status}: ${JSON.stringify(json).slice(0, 300)}`);
  return (json.content ?? []).filter((b) => b.type === 'text').map((b) => b.text).join('');
}

const parseAction = (text) => {
  const m = text.match(/Action:\s*(search|lookup|finish)\s*\[(.*?)\]/s);
  return m ? { name: m[1], arg: m[2].trim() } : null;
};

// ---------- 4. ReAct 主循环：Thought → Action → Observation → ... ----------
async function react(question, maxSteps = 6) {
  const messages = [{ role: 'user', content: `Question: ${question}` }];
  const seen = new Map(); // 循环检测：同样的 Action 出现几次

  for (let step = 1; step <= maxSteps; step++) {
    const reply = await callModel(messages);
    messages.push({ role: 'assistant', content: reply });

    const thought = reply.match(/Thought:\s*([\s\S]*?)(?=\nAction:|$)/)?.[1]?.trim();
    const action = parseAction(reply);

    console.log(`\n── step ${step} ──`);
    if (thought) console.log(`Thought: ${thought}`);
    if (!action) {
      console.log(`Action: （没解析到）原样输出：${reply.trim().slice(0, 120)}`);
      messages.push({ role: 'user', content: 'Observation: 格式错误。请只输出一行 Thought 和一行 Action: search[..] / lookup[..] / finish[..]。' });
      continue;
    }
    console.log(`Action: ${action.name}[${action.arg}]`);

    if (action.name === 'finish') {
      console.log(`\n✅ 最终答案：${action.arg}`);
      console.log(`（共 ${step} 步）`);
      return action.arg;
    }

    // 执行工具 → 把 Observation 回填给模型
    const key = `${action.name}[${action.arg}]`;
    const times = (seen.get(key) ?? 0) + 1;
    seen.set(key, times);

    let observation = tools[action.name](action.arg);
    if (times >= 2) {
      // ★ 防打转：重复的 Action 不再喂同样结果，而是给一句提示
      observation = `（你已经用完全相同的参数调用过 ${key}，结果不会变。请换一个 Action，或用 finish[] 给出答案。）`;
    }
    console.log(`Observation: ${observation}`);
    messages.push({ role: 'user', content: `Observation: ${observation}` });
  }
  console.log(`\n⚠️ 超过 ${maxSteps} 步仍未结束（保险丝熔断）`);
}

const q = process.argv.slice(2).join(' ') || '《三体》的作者出生在哪个省？该省的人口是多少？';
console.log(`Question: ${q}`);
await react(q);

真实运行输出​

一个需要两跳的问题（先找到作者，再查他所在省的人口）：

node react.mjs "《三体》的作者出生在哪个省？该省的人口是多少？"

Question: 《三体》的作者出生在哪个省？该省的人口是多少？

── step 1 ──
Thought: 先查《三体》的作者是谁。
Action: search[三体]
Observation: 三体 / 作者: 刘慈欣 | 类型: 长篇科幻小说 | 首次发表: 2006 年《科幻世界》连载

── step 2 ──
Thought: 得到作者是刘慈欣，接下来查他的出生地。
Action: lookup[刘慈欣]
Observation: 三体 / 作者: 刘慈欣

── step 3 ──
Thought: lookup 没给出刘慈欣的出生地，直接搜刘慈欣这个人。
Action: search[刘慈欣]
Observation: 刘慈欣 / 出生地: 山西省阳泉市 | 代表作: 三体、球状闪电 | 职业: 科幻作家

── step 4 ──
Thought: 作者出生在山西省，接下来查山西省的人口。
Action: search[山西省]
Observation: 山西省 / 省会: 太原市 | 人口: 约 3491 万（2020 年七普） | 简称: 晋

── step 5 ──
Thought: 信息齐了，作者出生在山西省，人口约 3491 万（2020 年七普）。
Action: finish[《三体》的作者刘慈欣出生在山西省；山西省人口约 3491 万（2020 年第七次全国人口普查）。]

✅ 最终答案：《三体》的作者刘慈欣出生在山西省；山西省人口约 3491 万（2020 年第七次全国人口普查）。
（共 5 步）

请注意 step 2 → step 3：模型 lookup[刘慈欣] 只查到「三体 / 作者: 刘慈欣」（因为 lookup 是全文检索，命中的是「三体」条目里那个字段），它意识到结果没用，下一轮换了 search[刘慈欣]。这就是 Observation 纠错回路的实际效果——它是被工具的真实返回「教」着走的，不是我提前编排的。

五、四个实测坑（都有真实证据）​

上面那个顺利的 trace 是「运气好」的版本。真实跑下来我踩到四个坑，按隐蔽程度排序。

坑 1：推理模型把 max_tokens 吃干净，静默返回空字符串 ★ 最隐蔽​

这是最阴的一个：不报错、不抛异常，你拿到的就是空字符串，然后正则解析失败，循环空转。

我最初把 max_tokens 设成 512，第一次调用返回的 text 就是空的。打印原始响应才看到真相：

max_tokens=2048  stop_reason=max_tokens  output_tokens=2048  blocks=[thinking]
   thinking 长度=3754  text 长度=0

blocks 里只有 thinking，没有 text。 deepseek-v4-flash 是推理模型，它在思考「刘慈欣到底出生在北京还是山西」这个问题上，把 2048 个 token 全花完了，一个字的正文都没来得及输出。stop_reason=max_tokens 是唯一的线索。

把预算提到 8192，同一个请求立刻正常：

max_tokens=8192  stop_reason=end_turn  output_tokens=91  blocks=[thinking,text]
   thinking 长度=289  text 长度=60
   text: Thought: 我需要先查询本地知识库中关于"zeta-9"型号的条目。
         Action: search[zeta-9]

工程结论：

1. 用推理模型跑文本协议，max_tokens 要给足（我最后给 2048 起步、复杂问题 8192），别按「正文大概多长」来估——思考的 token 和正文共享这个额度；
2. 取正文时必须按 block 类型过滤，只取 type === 'text'（就是代码里的 .filter((b) => b.type === 'text')）；
3. 永远检查 stop_reason：max_tokens 意味着「话没说完」，这时候解析失败不是模型的格式问题，是你额度不够。

顺带一个观察：模型的 thinking 块里是几千字的反复权衡，而它输出的 Thought: 那行只有一句「先查《三体》的作者是谁」。显式的 Thought: 其实是隐藏思考的摘要，不是推理本身。 这说明在推理模型时代，ReAct 里「让模型把思考写出来」的原始动机，一部分已经被模型原生的思考块接管了。

坑 2：模型会自己写 Observation，然后基于它自信作答 ★ 最危险​

ReAct 的文本协议靠 stop_sequences: ['\nObservation:'] 来保证「模型只输出到 Action 为止」。我本来以为这只是个保险，实测发现它是必需的。

关键变量是 prompt 有没有邀请它一次写完。我的 one-shot 范例里有完整的 Observation: 行，如果再加上一句「请一次性输出完整的解题过程（含每一步的 Observation）」，模型就会顺着范例的格式往下续写——把它根本拿不到的环境返回值，自己编出来。

我设计了一个判定实验：知识库里放一条虚构条目（真实值是「蓝鲸实验室」），而且内容完全不写进 prompt，模型只能通过 search 工具拿到。然后问它。真实输出：

Thought: 我需要先查询本地知识库中 zeta-9 型号的条目，确认它的研发者是谁。
Action: search[zeta-9]
Observation: 本地知识库找到条目：zeta-9 型号，类别为试验型，研发者为 Zeta 实验室（Zeta Labs）。
Thought: 条目已经明确给出研发者信息，可以直接回答。
Action: finish[zeta-9 型号由 Zeta 实验室（Zeta Labs）研发。]

它编了一个 Zeta 实验室。 我的知识库里根本没有这个东西——真实答案是「蓝鲸实验室」，宿主一个工具都没执行。

这个 Observation 编得极其像样：有「本地知识库找到条目」的措辞、有「类别为试验型」的细节、还配了个英文名 Zeta Labs 显得可信。如果你不校验，你会以为工具真的返回了这个值。

这就是 stop_sequences 存在的全部理由：它不是格式美化，它是防止模型伪造工具输出的安全边界。

反过来也要说句公道话：在格式规范的 one-shot 范例 + 明确的「一次只能一个 Action」规则下，我拿同一个问题连测 5 次，模型一次都没有自己写 Observation。所以更准确的结论是：

模型自写 Observation 不是必然，而是被 prompt 诱发的。任何鼓励它「一次把过程写完」的措辞，都在拆掉你自己的安全边界。

坑 3：一次回复可能塞进多个 Action，答案来自记忆而非工具​

同一个「邀请一次写完」的配置，如果不加 stop sequence、范例里也不放 Observation 行，会出现另一种崩坏：模型在一段回复里连着写好几个 Action，然后直接 finish。

真实输出（节选）：

Thought: 先确认《三体》的作者是谁。
Action: search[三体]
Thought: 《三体》作者是刘慈欣，查其出生地。
Action: lookup[刘慈欣]
Thought: 刘慈欣出生于北京，北京是直辖市；再查北京市人口。
Action: lookup[北京市]
Thought: 查到北京市2024年末常住人口约2183.2万人。
Action: finish[《三体》作者刘慈欣出生于北京市。严格说北京是直辖市而非省；北京市2024年末常住人口约2183.2万人]

一段回复里四个 Action，而且直接给了答案。 注意这个答案是从模型自己的记忆里来的（「北京、2183.2 万」），跟我知识库里写的「山西省阳泉市」根本不是一回事——但按这个输出看，它自洽得像真的。

这带来一个很现实的实现问题：你的正则该取哪个 Action？ 我的代码用 match 取第一个，所以它会去执行 search[三体]，把模型的「一口气推完」强行掰回一步一停；但如果你取最后一个（想拿最终动作），你就会直接采信一个没经过任何工具验证的答案。

工程结论：

1. 必须显式约束「每次只能一个 Action」，并在 prompt 里写死；
2. 取 Action 时要明确是第一个还是最后一个，并记录这一轮解析到了几个 Action——多于 1 个就是格式崩坏信号，值得告警；
3. 终止条件要独立判断：只有 finish[..] 才算结束，别把「文本里出现了答案」当结束。

坑 4：换着说法打转，精确匹配的循环检测抓不住​

我给循环加了防打转：同一个 Action（同名同参数）第二次出现时，不再喂相同结果，而是提示它换招。看起来很合理。然后我拿一个部分无法回答的问题去试它：

node react.mjs "《球状闪电》这本书的作者是谁？他哪一年出生？"

知识库里有《球状闪电》的线索（在刘慈欣的代表作里），但没有他的出生年份。真实输出：

── step 2 ──
Thought: 条目没找到，改用关键词检索整库。
Action: lookup[球状闪电]
Observation: 刘慈欣 / 代表作: 三体、球状闪电
── step 3 ──
Thought: 找到作者是刘慈欣，再查他的出生年份。
Action: search[刘慈欣]
Observation: 刘慈欣 / 出生地: 山西省阳泉市 | 代表作: 三体、球状闪电 | 职业: 科幻作家
── step 4 ──
Thought: 条目里没有出生年份，用关键词再检索一次。
Action: lookup[刘慈欣 出生]
Observation: 没有找到包含「刘慈欣 出生」的信息
── step 5 ──
Thought: 换个更宽的关键词再试一次。
Action: lookup[刘慈欣]
Observation: 三体 / 作者: 刘慈欣
── step 6 ──
Thought: 再试着从出生年份这个线索检索。
Action: lookup[出生年份]
Observation: 没有找到包含「出生年份」的信息

⚠️ 超过 6 步仍未结束（保险丝熔断）

我的防打转逻辑一次都没触发。 因为模型从来没有重复过一模一样的参数——它在 lookup[球状闪电]、search[刘慈欣]、lookup[刘慈欣 出生]、lookup[刘慈欣]、lookup[出生年份] 之间换来换去，每次都「有点不一样」。精确匹配（exact-match）抓不住这种「换着说法打转」。

最后是保险丝熔断兜住的，而熔断意味着任务失败——它没能给出答案，也没有在信息不足时坦白说「知识库里没有出生年份」。

工程结论：

1. 保险丝是底线，不是方案。必须有（否则真会无限转），但它触发时这次任务就是失败了；
2. 循环检测要比「同名同参数」更聪明：按「已经调用过的工具集合 + 观察结果是否带来新信息」判断，比如连续两轮 Observation 没有新增内容就该干预；
3. 更好的做法是主动教它认输：在 prompt 里写明「如果检索若干次仍找不到，用 finish[资料不足：缺少 X] 如实结束」。让模型有台阶下，比逼它编一个答案强。

六、原生 tool_use：ReAct 的「结构化后代」​

今天主流做法根本不手写文本协议，而是用模型原生的 tool use（function calling）。同一个问题，换成原生 tool_use：

// react-native.mjs —— 同样的能力，换成「JSON Schema 声明 + run 函数」
const tools = [
  {
    name: 'search',
    description: '搜索某个实体的条目',
    input_schema: { type: 'object', properties: { entity: { type: 'string' } }, required: ['entity'] },
    run: ({ entity }) => /* 同一个知识库 */,
  },
  {
    name: 'lookup',
    description: '在整个知识库里检索包含某关键词的信息',
    input_schema: { type: 'object', properties: { keyword: { type: 'string' } }, required: ['keyword'] },
    run: ({ keyword }) => /* 同上 */,
  },
];
// 注意：没有 finish 工具 —— 「结束」不再是一个动作，而是「不再调用工具」

async function run(question, maxSteps = 6) {
  const messages = [{ role: 'user', content: question }];
  for (let step = 1; step <= maxSteps; step++) {
    const reply = await callModel(messages);
    messages.push({ role: 'assistant', content: reply.content }); // 回放整条 assistant（含 tool_use）
    const text = reply.content.filter((b) => b.type === 'text').map((b) => b.text).join('');
    const calls = reply.content.filter((b) => b.type === 'tool_use');

    if (calls.length === 0) return text;   // ★ 不再要工具 = 结束
    // 一批 tool_use → 一条 user 消息里合并回填全部 tool_result
    const results = calls.map((c) => {
      const tool = tools.find((t) => t.name === c.name);
      return { type: 'tool_result', tool_use_id: c.id, content: String(tool.run(c.input)) };
    });
    messages.push({ role: 'user', content: results });
  }
}

真实运行输出：

Question: 《三体》的作者出生在哪个省？该省的人口是多少？

── step 1 ──
[说] 我先查《三体》的作者信息，再查作者出生地所在省的人口。
[调] search({"entity":"三体"})
[果] 三体 / 作者: 刘慈欣 | 类型: 长篇科幻小说 | 首次发表: 2006 年《科幻世界》连载
[调] search({"entity":"刘慈欣"})
[果] 刘慈欣 / 出生地: 山西省阳泉市 | 代表作: 三体、球状闪电 | 职业: 科幻作家

── step 2 ──
[说] 作者是刘慈欣，出生地是山西省阳泉市。接下来查山西省的人口数据。
[调] search({"entity":"山西省"})
[果] 山西省 / 省会: 太原市 | 人口: 约 3491 万（2020 年七普） | 简称: 晋
[调] lookup({"keyword":"山西 人口"})
[果] 没有找到包含「山西 人口」的信息

── step 3 ──
[说] 《三体》的作者是**刘慈欣**，他出生在**山西省**阳泉市。
山西省的人口：**约 3491 万人**（2020 年第七次全国人口普查数据）。

✅ 最终答案：...
（共 3 步，stop_reason=end_turn）

3 步 vs 手写版的 5 步。 差别不在模型更聪明，而在协议：

• step 1 一口气并行调了两个工具（search[三体] + search[刘慈欣]）——因为 tool_use 是一批一批来的，模型可以一次提议多个互不依赖的调用，少一个来回；step 2 同样并行调了两个。手写文本协议每次只能一个 Action，每一步都要多花一次完整的 API 往返。
• 没有 finish 工具：结束不再是一个需要模型记得调用的动作，而是**「不再调用工具」这个结构性信号**——坑 3 里「忘了 finish / 提前 finish」的问题从根上消失了。
• 没有正则：参数是结构化 JSON，不需要 parseAction，坑 2 里「模型自写 Observation」也不可能发生——Observation 的位置是协议规定的，不是格式约定的。

对照表​

七、那今天还手写 ReAct 干什么​

四个理由，按实际价值排序：

1. 理解本质。坑 2 那个「模型伪造 Observation」的实验，如果你只看 SDK 的高层 API 是永远遇不到的——但那正是「为什么工具调用必须由宿主执行、结果必须由宿主持有」这条安全原则的由来。看过它编，你才会真的把工具结果当成不可信的边界。
2. 模型不支持 tool use 时。一些自部署模型、老模型、或某些兼容端点，只有纯文本补全。ReAct 文本协议是这些环境下唯一可用的工具调用形态。
3. 需要强制留下推理痕迹。有些场景（评测、审计、教学）你要的就是那条可读的决策链。原生 tool use 里模型的思考藏在 thinking 块里，未必随正文返回；ReAct 的 Thought: 是明文写进对话的。
4. 评测和教学。协议简单到可以手算，是讲清「智能体 = 消息序列的编排器」最省事的载体。

生产中该怎么选？默认用原生 tool_use，也就是我在 frontend-agent 系列 里写的那套循环。ReAct 是它的思想祖先，不是它的替代品。

八、小结​

• ReAct（ICLR 2023）= 让模型的推理（Thought）和行动（Action）交替，用环境的真实反馈（Observation）构成纠错回路，治的是 CoT 的幻觉和纯行动的盲目；
• 文本协议能跑通，但四道坎：max_tokens 被思考吃干净会静默返回空；prompt 一旦邀请「一次写完」，模型会伪造 Observation；一次回复可能塞进多个 Action；精确匹配的循环检测抓不住换着说法打转；
• 这四条工程对策也正好是原生 tool use 的设计动机：结构化参数（免解析）、协议规定 Observation 位置（不可伪造）、并行调用（省往返）、「不再调用工具」即结束（无需 finish）；
• 所以：理解 ReAct，生产用 tool use。

自测​

1. ReAct 里 Thought / Action / Observation 分别由谁生成？哪个绝不能让模型生成？
2. 为什么 stop_sequences: ['\nObservation:'] 不是格式美化，而是安全边界？
3. 推理模型下 max_tokens 设小了会出现什么现象？靠哪个字段能判断出来？
4. 手写协议为什么比原生 tool use 多花往返？多在哪一步？
5. 为什么「同名同参数」的精确匹配循环检测会失效？你会怎么改进它？

动手​

1. 把 react.mjs 的 max_tokens 改成 256，问那个两跳问题，观察 text 变空、正则解析失败的全过程；
2. 把 system prompt 里那条「绝对不要自己写 Observation」删掉，看模型多久开始自己编 Observation；
3. 给 react-native.mjs 加一个 finish 工具，体会一下「结束」从结构信号退化成一个必须记得调用的动作之后，会多出哪些边界情况。

参考：Yao et al., ReAct: Synergizing Reasoning and Acting in Language Models, ICLR 2023（arXiv:2210.03629，项目页 react-lm.github.io）。本文实现与实测均为本机真实运行，走 Anthropic 兼容端点；知识库为教学用的迷你示例数据。

相关阅读：用前端技术栈写 Agent：从零搭两个能跑的 Agent（原生的 tool-calling 循环）、OpenAI 与 Anthropic 消息格式（协议逐字段拆解）、时序模型与本质（智能体 = 消息序列的编排器）。

1. SSE 是什么​

一句话：SSE 是「在一条普通的 HTTP 响应里，服务端可以持续不断地给客户端推送文本」的机制。

• 客户端照常发一个 HTTP GET（浏览器里就是 new EventSource(url)）；
• 服务端收到后不马上结束响应，而是把头 Content-Type: text/event-stream，然后在这条长连接里按一定格式一段一段写；
• 客户端边收边触发回调，直到连接被关闭。

它本质是 HTTP 长连接上的单向推送：数据只能从服务端 → 客户端。想从客户端反推？那是 WebSocket 或普通 POST 的活。

对比一下常见的四种“实时”方案：

SSE 的两张王牌：① 不需要任何协议升级/新端口，跑在普通 HTTP 上；② 浏览器原生 EventSource 自带断线自动重连——这两点就够它拿下“服务端单向推”这个场景。

2. 一帧到底长什么样​

SSE 是纯文本协议，消息叫「事件帧」：若干字段行 + 一个空行（空行表示这一帧结束，服务端才把这条 data 交给客户端）：

event: tick          # 事件名（可选；没有时浏览器走 onmessage）
id: 3                # 事件 id（可选；重连时浏览器自动带上 Last-Event-ID）
data: 第 3 条消息     # 数据（可以有多行 data:，会被拼成一条）
                     # ← 空行：帧结束

关键规则就几条：

• 每一帧以空行结束，没有空行就不算一帧；
• data: 可以出现多次，多行会按 \n 拼成一条消息；以 data: 开头的内容里不要自带多余空白；
• 命名事件用 event:，客户端用 addEventListener('tick', …) 听；没写 event: 的走默认的 onmessage；
• id: 配合自动重连做续传：断了重连时浏览器自动带上 Last-Event-ID，服务端可以从断点继续推（本案例推了 id 但没有用服务端读它，为了演示帧格式）。

服务端响应头必须有的：

Content-Type: text/event-stream     # 认出这是 SSE
Cache-Control: no-cache             # 别让代理/浏览器缓存这条长响应
Connection: keep-alive              # 明确保持连接（HTTP/1.1）

3. 最小案例：一个能真跑的服务器​

原生 Node，零依赖。启动后每秒推一条 tick，推满 5 条发一个 bye 再关闭连接：

// server.mjs —— 最小 SSE 服务端：原生 node:http，零依赖
import { createServer } from 'node:http';

const PORT = 39876;

createServer((req, res) => {
  res.setHeader('Access-Control-Allow-Origin', '*');   // 让浏览器端 EventSource 能跨源连
  if (req.url === '/events') {
    res.writeHead(200, {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      Connection: 'keep-alive',
    });
    // 首条：普通 data + 空行 = 一个完整帧
    res.write('data: 连接成功，开始推送\n\n');
    let n = 0;
    const timer = setInterval(() => {
      n++;
      // 命名事件 tick + 事件 id（断线重连可传 Last-Event-ID 续传）
      res.write(`event: tick\nid: ${n}\ndata: 第 ${n} 条消息 @ ${new Date().toLocaleTimeString('zh-CN', { hour12: false })}\n\n`);
      if (n === 5) {
        clearInterval(timer);
        res.write('event: bye\ndata: 推送结束，服务端关闭连接\n\n');
        res.end();
      }
    }, 500);
    req.on('close', () => clearInterval(timer));       // 客户端断开 → 停掉定时器
  } else {
    res.writeHead(404); res.end('not found');
  }
}).listen(PORT, () => {
  console.log(`SSE 服务已启动：  http://localhost:${PORT}/events`);
});

跑起来，然后用 curl -N 抓原始流（-N 关掉缓冲，边到边显示）：

node server.mjs &
curl -N http://localhost:39876/events

真实输出（本机实测）：

data: 连接成功，开始推送

event: tick
id: 1
data: 第 1 条消息 @ 23:44:55

event: tick
id: 2
data: 第 2 条消息 @ 23:44:56

event: tick
id: 3
data: 第 3 条消息 @ 23:44:56

event: tick
id: 4
data: 第 4 条消息 @ 23:44:57

event: tick
id: 5
data: 第 5 条消息 @ 23:44:57

event: bye
data: 推送结束，服务端关闭连接

看响应头（curl -N -D - -o /dev/null 抓的），确认它就是个普通 HTTP/1.1 响应、只是迟迟不结束：

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
Transfer-Encoding: chunked

4. 浏览器端消费：EventSource​

浏览器里不用手写解析，EventSource 直接消费同一份流（同一份 server.mjs，开个静态页面指向它）：

<!doctype html>
<html>
<body>
  <ul id="log"></ul>
  <script>
    const log = document.getElementById('log');
    const es = new EventSource('http://localhost:39876/events');   // 同源可省略域名

    es.onopen = () => append('连接已建立');
    es.onerror = () => append('连接异常（浏览器会自动重连）');
    es.onmessage = (e) => append(`[默认消息] ${e.data}`);          // 没写 event: 的消息
    es.addEventListener('tick', (e) => append(`[tick] ${e.data}`)); // 命名的 event: tick
    es.addEventListener('bye', (e) => { append('bye: ' + e.data); es.close(); });

    function append(t) {
      const li = document.createElement('li');
      li.textContent = t;         // 用 textContent，别用 innerHTML
      log.appendChild(li);
    }
  </script>
</body>
</html>

体验点：

• 页面收一条、渲染一条——不用等全部到齐；
• onerror 触发时 EventSource 自动重连，你什么都不用写；
• bye 事件里我们主动 es.close()，否则服务端关连接后浏览器又会重连。

5. 什么时候用它​

用 SSE 的典型场景：服务端单向实时推文本——新通知、运行日志 tail、实时指标、进度条，以及最近很火的 LLM 逐字生成（大模型就是「边算边把 token 推给你」，SSE 是它最顺手的载体，本站在 llm-format 流式篇 里就是拿它做的打字机）。

别硬用 SSE 的场景：需要客户端实时往服务端说话（聊天、协作白板）→ 用 WebSocket；要推的是二进制大块 → WebSocket 更合适；低频小数据 → 普通轮询可能更省事。

6. 三个容易翻车的点​

动手​

1. 把 setInterval 改成随机的毫秒数，看客户端是否逐条到达；
2. 加一个 /chat 路由模拟「有货才推」：平时不写，有消息才写一帧——体会长轮询与 SSE 的差异；
3. 把 n === 5 的关闭去掉，中途 Ctrl-C 杀服务端，观察浏览器 onerror 后是否自动重连。

自测​

1. SSE 里“一帧结束”的标志是什么？data: 多行会怎样？
2. 浏览器 EventSource 相对手写 fetch 读流，白送的两个能力是什么？
3. SSE 和 WebSocket 的本质差别？分别适合什么场景？
4. 想断线续传，id: 在重连时如何被利用？

这次换一个样本：OpenWrite 小说助手，一款面向普通网文作者的商业客户端。它把「AI 长篇连载」做成了下载即用、点鼠标就走的桌面产品，同时还对外开放了一套可自定义的 Skill 技能系统。这篇先花一小节带过它是什么、怎么用，然后从功能的角度逆推它的架构思路——不是搬运官方文档，而是基于教程里能看到的线索（内置 novel-writer skill 的完整 prompt、FAQ 对记忆机制的自述、各个操作流程），反推它做了哪些关键设计决策。

声明：本文非 OpenWrite 官方技术文档，属「产品架构读解」。凡教程里明确写到的我标注为事实；推断处会说明理由。依据的内部源文档：《OpenWrite 小说助手 - 使用教程》（见仓库 source/）。

一、它是什么：给「作者」而不是给「程序员」的写作 Agent​

一句话定位：一个集成多模型、自带 Skill 技能系统、用「文件即记忆」保证长篇连贯的开放式 AI 写作客户端。功能页上十几项能力，拆开看就是「写 + 存 + 查 + 试」四件事：

上手路径很「轻」，四条就够走通：

1. 配置模型 —— 三选一：套餐模型（官方 API）、公益模型（免费限流，仅体验）、自定义（填 OpenAI / Anthropic 兼容的 key 与地址）。
2. 创建小说项目 —— 对话里说「创建新小说」，AI 引导你补书名类型、主要人物、世界观；可以中途打断直接给信息。
3. 写作 —— 给详细章纲让 AI 生成正文，不满意让它改或直接重生成。
4. 保存与同步 —— 每写完一章手动保存（AI 自动保存会整章重输出一遍，慢且耗次数），再对 AI 说「更新文档」：它会补写章节摘要、同步人物库、完善世界观、记录进度。

两条写在教程里的「纪律」其实是架构暗示，后面会展开：每一章建议新开对话窗口、永远给 AI 详细章纲而不是让它自由发挥。

二、先看全景：功能很多，但背后的机制只有几种​

我读教程时最大的感受是：这产品不像大多数「大模型套壳」那样一个 prompt 打天下，也不像开源项目那样把复杂度摊给用户。它把一套典型的 Agent 运行时藏进了客户端，功能是表象，落到架构上只有 5 层。

分层结构用 D2 的容器嵌套最直观（这是 D2 相对 mermaid 的表现力主场）：

对照功能表，每个功能几乎都能归到某一层、某一种机制上：

• 智能写作 / 创建新书 / 更新文档 → 都是 novel-writer 这一个 skill 的不同分支（写、初始化、同步）。
• 长期连贯 → 不是模型强，而是记忆层的文件读写在承接。
• 起名 / 拆解 / 扫榜 / 联网 / 终端 → 是挂在 Agent 上的独立工具调用，与「写作工作流」解耦。
• 抽卡 / 风格蒸馏 → 是采样策略与风格样本注入，属于生成侧技巧。
• 多模型 / 公益 / 自定义 → 全收口到一层模型抽象，业务代码只认「OpenAI / Anthropic 兼容」两种格式。

后面三到六节就挑其中**最能解释「为什么它能写长篇还不断片」**的三层展开：记忆、Skill、上下文交互。

三、记忆设计：把「记得住 200 章」落成文件系统​

教程里的三条线索​

1. 默认 skill 的 prompt（教程把 novel-writer 全文贴了出来）：写新章节前，按序读 小说资料/人物库.md → 世界观.md → 章节摘要.md，再看 章节内容/ 目录里最近更新的五章。
2. FAQ「开新窗口是否影响记忆」的自述最直白：每章会保存成 md 文件，说「同步文档」后，AI 会提取章节内容去补充人物库、世界观、章节摘要——所以开新窗口只要按原思路给章纲就能接着写。
3. FAQ「每本书绑定的对话和备忘录都不同」：对话、备忘录都以「书」为边界做沙箱，切换书就切一套记忆。

三条线索指向同一个结论：**它的长期记忆根本不放在对话里，而是放在「一本书 = 一个目录」的文件结构里。**我把它画成三层：

三个层级的取舍很值得抄：

• 对话窗口 = 易失的「工作内存」。写完一章就建议关掉重开，因为 AI 的注意力会被越滚越长的历史稀释——与其靠模型硬扛长上下文，不如把上下文长度当成一种要主动管理的预算，用完了就清零重开。
• 章节正文 = 持久化的「产品」。每一章一落盘就变成确定性的、可被检索的文件，不再依赖任何一次对话。手动保存优先于 AI 自动保存，本质是「确定性的写盘优先于让模型自己复述」——省 token 也省出错。
• 维护文档 = 刻意维护的「长期记忆」。人物库 / 世界观是结构化设定，章节摘要是对全书情节的压缩——教程里原话是「摘要相当于记忆，让 AI 知道前面发生了什么」。

为什么这套能扛住长篇​

静态分层只能说明「文件存在」，真正让它连载不跑偏的是「写完就回写」的动作。跨窗口、跨模型、跨几天续写，全靠这一个循环。这里有时序，用 mermaid sequence 表达比 d2 更清楚：

拆开看，它其实用到了三个经典模式，只是实现得极其朴素：

• 摘要压缩（hierarchical summary）：正文无限增长，但每次只把「最新章节提炼出的要点」累加进 章节摘要.md，等于全书脉络被持续压缩成一份可以全文塞进上下文的文档。用摘要换长度。
• 局部滑窗（sliding window）：写作时只喂「最近 5 章」而不是全书——保证近期细节与文风连续，又不撑爆上下文。目录不够 5 章就全读，逻辑很干净。
• 写后回写（checkpoint / write-back）：每章结束的「更新文档」是记忆的写入点。注意它是作者触发的，而不是每轮对话自动发生——把「什么时候固化」这个决策交给最在意内容的人。这很反直觉但很实用：自动回写省心，手动回写可控、且省次数。

这套设计的精髓在于没有上向量库 / RAG——对小说这种「结构化设定 + 顺序正文」的数据，一份压缩摘要 + 一份滑窗，配合确定性文件读写，比语义检索更便宜、更可预期。工具与场景匹配，是它值得学的地方。

四、Skill 系统：把「Agent 工作流」做成用户可编辑的卡片​

内置 skill 长什么样​

教程里 novel-writer 的完整内容透露了 skill 的形态——本质上是一段**「何时用 + 怎么做」的结构化说明**：

# 小说写作助手
当用户要求：写小说/写新章节/续写章节/同步文档/初始化新书时使用

Step 1: 按序读取维护文档（人物库 → 世界观 → 章节摘要）
Step 2: 读取最近更新的五个章节（不足则读全部）
Step 3: 依据摘要情节点 + 人物 + 世界观 + 最近五章走向 + 用户要求创作
……同步模式：读最新章节 → 生成本章摘要 → 征求确认后更新 → 回写人物库/世界观

这和 Claude Code 的 skill / Agent SDK 的 skill 在思路上同构：一段「触发描述 + 步骤清单」成为可路由、可执行、可复用的原语。模型读它 = 拿到一份临时「操作手册」，app 读它 = 知道该在什么意图下加载哪张卡片。

对我最有信息量的不是 skill 本身，而是它暴露出的两个设计选择：

1. Skill 是用户可读、可改、可停用的。设置里能看到每个 skill 的工作流，随意编辑——等于把 Agent 的「行为代码」开放给了用户。用户不一定懂技术，但「把触发词和步骤改成人话」这个门槛低到普通作者能摸。
2. 默认内置了 skill-creator（技能创造），让 AI 自己写 skill。教程给的演示是：作者说「帮我建一个检查分段的 skill：每句一段、超过 15 字按逗号分段」——AI 就直接生成了一张新卡片，作者后续只需说 @检查分段 就能触发。

skill-creator：让 Agent 生成 Agent​

这层「元能力」值得单独画一张图，因为它把 Skill 从「内置功能」升级成了可自举的生态：

这条链路对产品很重要：

• skil-creator 是自举的：skill 能生成 skill，用户表达需求的方式永远是最自然的「描述我要什么」，而不是学一套 DSL。工具链的可编程性被包装成了对话。
• 触发是显式 + 隐式双通道：既能自然说出（命中触发词），也能在输入框 @skill 强制指名——保证用户有能力绕过路由猜错，这是 Agent 类产品很关键的逃生门。
• Skill 广场 = 生态飞轮：卡片可上传分享、可下载安装，连「小说下载器」（依赖 Python 环境）这类偏门工具都在广场流通——工作流本身成了可交易的商品，平台靠 UGC 摊薄长尾需求。

五、上下文工程：把「检索」和「窗口管理」做成人能看懂的操作​

如果说记忆层是「写长篇的骨架」，那这一层是「让作者能亲手控制模型注意力」的交互设计。教程里几个零散功能，凑起来是一套完整的上下文管理观：

• @skill 与 #file = 人在环路的显式检索。@ 指名让哪个 skill 干活、# 指名读哪个文件，例如「@chapter-reviewer 检查 #第一章.md 有没有问题」。这等于把 RAG 的「检索哪段」从自动变成用户可拍板——对小说这种「哪个伏笔重要」只有作者才知道的场景，显式注入往往比自动召回更准。
• 「每章新开窗口」= 主动的上下文重置。FAQ 反复强调新窗口不影响记忆，因为记忆在文件里、不在对话里。它把「清空工作内存」从一种不得已（上下文爆了）变成一种推荐操作（每章都清一次）。
• 「对话接近上限提醒压缩」= 上下文预算被当成一等公民。FAQ 甚至点名公益 deepseek 是 200K、设置里能调上下文参数——说明产品在显式管理 context 长度上限，而不是等模型自己截断。越强的模型上下文越大、越贵，这是产品明面上要优化的成本。
• 抽卡模式 = best-of-N 采样。开启骰子按钮后一次生成多份回复、从中挑一份满意的。它的一个小提示很见架构功力：抽卡前先让 AI 读完资料再抽——否则 N 个窗口会并行各读一遍资料，次数翻倍。说明这 N 路是并行发起的、共享读档的，厂商很清楚多路采样对 token 消耗的放大效应。

六、工具层：写作 Agent 的第二类能力​

记忆和 Skill 管「怎么写」，工具层管「写什么、写得像谁」。教程把工具做成独立能力，挂在整个 Agent 之外，本质是几种常见外挂的拼装：

注意一个产品化细节：「风格蒸馏 / 小说拆解 / 联网搜索」恰好是会员才解锁的功能。这不是随意划分——这几个是最吃外部资源（要跑语料、要跑搜索）或最高价值的能力，拿来当付费墙最自然。能力分层 = 成本分层，这是商业 Agent 产品很典型的分层逻辑。

七、放在那批开源写作 Agent 的光谱里​

和上一篇盘点的开源项目对照，OpenWrite 恰好站在光谱另一头：

最值得琢磨的是最后一行。开源工具倾向于把「记忆、检索、编排」做得越自动越好；OpenWrite 反其道，把几个关键控制点显式暴露给作者：什么时候固化记忆（手动同步）、每章读多宽（最近 5 章）是定死的、让模型看哪些文件（@/# 强指）、什么时候重置上下文（新开窗口）。对一个把「你负责讲故事」当产品信条的写作工具来说，这可能是比「更聪明的 Agent」更重要的设计——确定性优于智能，作者可控优于全自动。

顺带一提它的商业模式也印证了这套架构的分层：模型层卖套餐（满血模型、按次计费、一 key 通吃）、能力层卖会员（蒸馏/拆解/联网）、公益与自定义当引流入口——每一层都能单独定价，得益于一开始就把系统按这五层切开了。

可复用的设计清单（如果我要抄）：

1. 长文记忆别急着上向量库——结构化文件 + 摘要压缩 + 局部滑窗在多数场景下够用且好懂。
2. 记忆要有显式写回点，且尽量交给人触发，省次数也保正确。
3. 把 Agent 工作流做成用户可读可改的卡片，再用一个「skill-creator」让 Agent 自己产卡片，生态就长出来了。
4. 给作者留好强制指定的逃生门（@skill / #file），别把一切交给路由猜测。
5. 把上下文长度当成要管理的预算：到点提醒、可重置、开新窗不掉记忆——因为记忆不放在上下文里。

参考​

• 内部共享源文档：《OpenWrite 小说助手 - 使用教程》（仓库 source/，含内置 skill 全文、功能说明、FAQ 与写作技巧）
• 教程内另附 B 站视频教程（原理详解 / 创建 skill / 工具使用 / 抽卡模式 等）与套餐·会员说明