Coze：低代码天花板#

Coze（扣子）是字节跳动推出的 Agent 构建平台，2024 年开源了核心引擎 Coze Studio。它的设计目标很明确：让非技术用户也能通过可视化界面搭建 AI Bot，快速部署到微信、飞书、Discord 等平台。

Coze 的 Workflow 编辑器用拖拽节点的方式编排流程，配合内置的插件市场和知识库，确实能在几分钟内搭出一个能用的客服机器人或知识问答助手。这是它真正擅长的领域。

但套进我们的场景就会碰壁。首先，Coze 的 Workflow 有明确限制：不支持在工作流中包含流式输出的结束节点，这意味着我们没办法在 token 级别做断句和 TTS 分发。整个语音合成环节就断了。其次，Coze 的插件体系虽然支持第三方 API 接入，但它的生命周期是”请求—响应”模式，没有 on_before_turn / on_after_turn 这样的钩子。我们的 OCR 主动触发和调用后的记忆图谱化，在 Coze 的架构里找不到挂载点。最后，Coze 的开源社区版和商业版存在功能差异，声音定制等能力仅限商业版，而我们需要的是完全可控的 TTS 管线。

一句话总结：Coze 是给”对话机器人”设计的，不是给”陪伴型 Agent”设计的。

Dify：工作流的表达力边界#

Dify 是一个优秀的 LLMOps 平台，它的核心价值在于可视化工作流编排和一站式 RAG 管理。通过拖拽节点，你可以快速搭建一个带知识库检索、多模型切换、条件分支的 Agent 应用。Dify 的 Agent Node 甚至支持自定义策略插件（ReAct、CoT、ToT 等），并且通过 Plugin Trigger 机制可以订阅外部事件来触发工作流。

从表面上看，Dify 的 Plugin Trigger 似乎能解决我们”OCR 主动触发”的需求——订阅一个外部的 OCR 事件，触发工作流就好了。但问题出在下游。

Dify 的 Agent Node 执行遵循”初始化—迭代循环—最终响应”三阶段模型，每一轮迭代都是一个完整的 LLM 调用。它的输出是结构化的 JSON 响应，而不是我们需要的 token 流。虽然 Dify 的 Chat API 支持 SSE 流式返回，但这个流式是”节点级”的——你能看到一个节点执行完了返回结果，但无法拿到 LLM 生成过程中的逐 token 输出来做实时断句。

更关键的限制在记忆。Dify 的 Agent Node 使用 TokenBufferMemory 管理上下文，这是一个 token 窗口滑动策略。它适合控制成本，但我们需要的是外部知识图谱的语义检索——根据当前对话内容从 Neo4j 中召回相关记忆片段，然后注入到用户 prompt 的特定位置。这种”调用前检索、调用后图谱化”的双向记忆流，不在 Dify Agent Node 的设计范围内。

Dify 适合什么？适合企业级 RAG 应用、客服工作流、内容生成管线——这些场景对流式粒度不敏感，对记忆的需求是”窗口内召回”而非”跨会话图谱关联”。

LangChain：抽象的代价#

LangChain 是 Agent 框架领域的先行者，它最大的贡献是定义了”Chain”这个概念——把 Prompt、LLM、Output Parser、Tool 串成一条可组合的管道。在 2023-2024 年，这个抽象极大地降低了构建 LLM 应用的门槛。

LangChain 的核心优势在于它的组合性和生态。它有最丰富的 Integration（数百个第三方工具和向量数据库的官方适配），有成熟的 Document Loader / Text Splitter / Retriever 体系做 RAG，有 LangSmith 做 Tracing 和 Eval。如果你在做一个标准的”检索增强问答”或”文档分析”应用，LangChain 可能仍然是最快的起步选择。

但 LangChain 的问题恰恰也出在它的核心抽象上。

Chain 是线性的。一个标准的 LangChain Agent 执行流程是：接收输入 → 构造 Prompt → 调用 LLM → 解析输出 → 如果需要工具就执行 → 再调 LLM → 最终输出。这是一条单向管道。但我们的场景需要的是：在 LLM 生成的过程中，token 流要同时被多个消费者处理（断句器、情绪提取器、TTS 过滤器、前端显示处理器），而且工具调用会打断文本流、插入工具状态标签、执行完后再恢复流式生成。

这不是一条链，这是一个有环的、有分叉的、有中断恢复的流。

更具体地说，LangChain 的 AgentExecutor（已在 2025 年底被标记为废弃）在执行工具调用时，会阻塞整个链直到工具返回。你没有机会在工具执行期间向前端流式输出状态信息。而我们的 AgentCore 在遇到工具调用时，会先 yield 一个 ToolCallEvent(status="running") 结构化事件让前端立刻展示工具运行状态，然后并发执行所有工具调用，完成后 yield ToolCallEvent(status="completed") 并继续流式生成。整个过程中文本 token 和工具事件在同一个 AsyncIterator 中分型流出，前端各自消费。

LangChain 的记忆抽象（ConversationBufferMemory、ConversationSummaryMemory 等）也是为简单场景设计的。它假设记忆是”对话历史的某种压缩形式”，塞进 Prompt 就行。但我们的记忆是一个独立服务，有自己的搜索 API 和写入 API，需要在对话开始前异步检索、在对话结束后异步写入。LangChain 没有为这种”外部异步记忆服务”提供原生的生命周期钩子。

最后，LangChain 的抽象层数太多了。一个工具调用要经过 Tool → ToolKit → AgentExecutor → OutputParser 多层包装，调试时你经常要在 LangSmith 里追踪五六层嵌套的 Trace 才能定位问题。对于我们这种需要毫秒级优化的实时流式场景，每一层抽象都是额外的延迟和调试负担。

LangGraph：最接近但仍然错位#

LangGraph 是 LangChain 团队对自身线性架构局限的回应。它引入了有向图（StateGraph）来编排 Agent 工作流，支持循环、分支、条件边、人工审批等复杂控制流。自 2025 年 10 月 LangChain 和 LangGraph 同时达到 1.0 里程碑以来，LangChain 的 create_react_agent() 底层实际上已经运行在 LangGraph 引擎之上。

LangGraph 的几个设计确实值得学习。它的 State 概念——一个在图节点之间流转的共享状态对象——提供了比 LangChain Chain 更灵活的数据传递方式。Time-Travel Debugging 让你可以回溯到图执行的任意节点重放，这在调试复杂工作流时非常有用。Human-in-the-Loop 机制让你可以在图的任意边上插入人工审批。

但 LangGraph 的图模型和我们的需求之间，存在一个根本性的错位：粒度。

LangGraph 的节点（Node）粒度是”一次完整的操作”——调用一次 LLM、执行一次工具、做一次判断。节点之间通过边（Edge）传递 State。这个设计非常适合编排”先检索文档，再总结，再生成报告，人工确认后发送”这类多步工作流。

但我们的核心需求不在”步骤之间的编排”，而在”一次 LLM 调用内部的 token 级处理”。当 LLM 正在流式生成文本时，每个 token 需要经过 sentence_divider → actions_extractor → tts_filter → display_processor 四层装饰器管线处理。这不是”图的一个节点执行完了传给下一个节点”，这是”在一个节点内部，输出流被实时分叉和处理”。LangGraph 的 State Graph 描述不了这个粒度的行为。

此外，我们的 Hook 系统需要的是”对话轮次的生命周期钩子”，而不是”图执行的节点钩子”。on_before_turn 在整个图开始前执行记忆检索，on_after_turn 在图完成后执行记忆写入，on_after_playback 在前端播放完成后才触发（因为有些后处理需要等 TTS 播完）。这三个钩子跨越了 LLM 调用、工具执行、前端播放三个完全不同的时间尺度。LangGraph 的图是围绕”LLM + Tool”的执行流设计的，它没有”前端播放完成”这个概念。

LangGraph 还有一个实际问题：规模化时的性能。随着图的节点和边增加，执行变慢，内存占用上升，调试难度增大。而且它与 LangChain 生态的紧密耦合意味着，如果你想用更轻量的 LLM 客户端（比如直接用 openai SDK），你需要写大量胶水代码来适配。

Harness Engineering：方向对了，但我们需要的不是控制平面#

2026 年最热门的概念是 Harness Engineering——“模型提供原始智能，harness 让智能变得可用”。Gartner 预测 2026 年底 40% 的企业应用将包含 AI Agent，而 65% 的 Agent 项目失败源于 harness 层面的缺陷，而非模型推理能力不足。

Microsoft Agent Framework（MAF）在 2026 年 4 月达到 1.0 GA，统一了 AutoGen 和 Semantic Kernel，提供了 Shell 访问、人工审批流、跨会话上下文管理等生产级能力。行业也在围绕 MCP（Model Context Protocol，Agent 到 Tool 的垂直交互）和 A2A（Agent-to-Agent，水平委派）两个协议标准化。

Harness Engineering 强调的五层——工具编排、验证循环、上下文与记忆、护栏、可观测性——和我们的实践高度吻合。但这些框架的典型假设是”单轮请求-响应”或”多步工作流”模式，核心关注点是安全、合规、可观测。它们是为企业 SRE、客服自动化、代码生成这类场景设计的控制平面。

我们需要的不是控制平面，而是一个”让 Agent 能像人一样陪你的表现层”——实时语音、表情、主动对话、情感记忆。这些需求在任何一个 Harness Engineering 框架的 Roadmap 上都看不到。

生命周期钩子（Hook System）#

我们定义了三个钩子点，覆盖对话轮次的完整生命周期：

1
class HookPlugin(ABC):
2
    async def on_before_turn(self, user_text, ctx) -> str | None:
3
        """调用前：记忆检索、上下文注入"""
4
    async def on_after_turn(self, user_text, assistant_text, ctx) -> None:
5
        """调用后：记忆写入、图谱更新"""
6
    async def on_after_playback(self, user_text, assistant_text, ctx) -> None:
7
        """播放后：等 TTS 播完再执行的后处理"""

MemoryPlugin 就是一个典型实现：on_before_turn 中向 Memory Bench 服务发起语义搜索，召回相关记忆片段注入上下文；on_after_turn 中将本轮对话异步写入 mem0 做记忆抽取，同时更新 Neo4j 知识图谱。

MoodChatPlugin 实现了另一种模式：它不是被动响应，而是根据情绪评分主动调度对话——高兴的时候话多，低落的时候安静。游戏伴玩模式下还会结合 OCR 变化检测来决定是否主动说话。

关键设计决策：钩子返回值被拼接注入到 user prompt 的 [memory context] 标签块中，而不是 system prompt。这避免了把瞬时信息当成稳定事实的问题。

流式 Tool Calling Loop#

AgentCore.run_turn() 实现了一个多轮流式工具调用循环，每轮上限 6 次迭代。返回值类型是 AsyncIterator[str | ToolCallEvent]——文本 token 以字符串形式流出，工具调用则以结构化事件的形式流出：

1
max_rounds = 6  # 安全护栏，不是技术上限
2

3
for _ in range(max_rounds):
4
    text_buf = ""
5
    async for chunk in chat_llm.stream_with_tools(messages, tools=schema):
6
        if delta.content:
7
            text_buf += delta.content
8
            yield delta.content              # 文本 token 立刻流出
9
        if delta.tool_calls:
10
            accumulate(tool_calls_buf)       # 收集工具调用片段
11

12
    ordered_tool_calls = _ordered_complete_tool_calls(tool_calls_buf)
13
    if not _should_execute_tool_calls(finish_reason, ordered_tool_calls):
14
        break   # 没有需要执行的工具，正常结束
15

16
    # 工具执行前：发出 running 状态事件
17
    for tc in ordered_tool_calls:
18
        yield ToolCallEvent(
19
            tool_id=tc["id"],
20
            tool_name=tc["name"],
21
            args=tc["arguments"],
22
            status="running",
23
        )
24

25
    # 所有工具并发执行
26
    results = await asyncio.gather(
27
        *(_exec_tool(tc, tool_manager, ctx) for tc in ordered_tool_calls)
28
    )
29

30
    # 工具执行后：发出 completed / error 状态事件
31
    for tc_info, result in zip(ordered_tool_calls, results):
32
        yield ToolCallEvent(
33
            tool_id=tc_info["id"],
34
            tool_name=tc_info["name"],
35
            args=tc_info["arguments"],
36
            status="completed" if result.ok else "error",
37
            result=result_text,
38
        )
39

40
    # 工具结果追加回消息列表，下一轮继续让 LLM 基于结果生成

6 轮上限是延迟与能力之间的一个经验取舍。 语音场景对响应速度敏感，同时绝大多数正常对话在 1-2 轮工具调用后就能结束（搜索→读文件→回答），6 轮给了充足的余量又不会让用户感知到明显的等待。

两个设计细节值得强调。

第一，工具调用事件是以结构化对象而非文本标签流出的。ToolCallEvent 是一个 dataclass，包含 tool_id、tool_name、args、status、result 等字段。这意味着前端——以及管线中下游的每一层——都无需用正则解析文本标签来识别工具事件，直接做类型判断即可。工具状态也拆成了两阶段事件：执行前 status="running"，执行后 status="completed" 或 "error"，前端可以根据状态切换 UI 展示。

第二，同一轮的多个工具调用通过 asyncio.gather() 并发执行，不是串行等待。

Token 级输出管线#

从 AgentCore 流出的 str | ToolCallEvent 混合流，进入 MemoryAgent 的装饰器管线：

1
@tts_filter(config)           # 过滤 TTS 不需要的内容（特殊符号等）
2
@display_processor(...)        # 处理前端显示的控制标签
3
@actions_extractor(live2d)     # 提取情绪/动作标签驱动 Live2D
4
@sentence_divider(...)         # 按自然语句切分，切出一句就立刻往下送
5
async def chat_with_memory(input_data):
6
    async for token in core.run_turn(...):
7
        yield token

每个装饰器层的处理逻辑中都做了一个关键判断：

1
async for chunk in stream:
2
    if isinstance(chunk, (AudioOutput, ToolCallEvent)):
3
        yield chunk         # 结构化事件透明穿透
4
        continue
5
    # 否则是文本 token，做本层处理

ToolCallEvent 作为结构化事件在管线中透明穿透——断句器不会把它切碎，TTS 过滤器不会尝试合成它，显示处理器不会给它加标签。每一层遇到 ToolCallEvent 就原样 yield 出去。最终前端收到的流包含两种消息：处理好的句子（含显示文本、TTS 文本、动作标签），以及结构化的工具调用事件。这比早期版本里用 <tool>[name]</tool> 文本标签混入对话流的设计（现已移除）要干净得多。

sentence_divider 是管线中对延迟最敏感的一环：它拿到足够的 token 组成一个自然句子后立刻 yield，不等整段话生成完。这样 TTS 引擎可以在 LLM 还在生成后半段时就开始合成前半段的语音，用户感知到的首句延迟大幅降低。

四类插件体系#

所有能力扩展都通过插件实现，我们定义了四种插件类型：

每个插件用一个 plugin.toml 声明身份和默认配置：

1
[plugin]
2
id = "memory"
3
type = "hook"
4

5
[config]
6
base_url = "http://localhost:12393"
7
user_id = "xnne"
8
agent_id = "congyin"
9
search_limit = 10

Profile TOML 文件决定启用哪些插件、覆盖哪些配置：

1
[plugins]
2
enabled = ["web_search_ddg", "web_fetch", "memory", "diary"]
3

4
[plugins.memory]
5
agent_id = "baoqiao"     # 切换角色就换一个 agent_id
6
search_limit = 5

这意味着同一套代码，换一个 Profile 文件就能切换完全不同的 Agent 人格——不同的角色 Prompt、不同的输出格式、不同的启用插件、不同的记忆空间。两个角色共存于同一个 Neo4j 图中，通过 agent_id 隔离，互不干扰。