Activepieces Chat 工具四文件架构解析为何丢失 Worker 端定义会静默失败【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepiecesap_remember这类 Chat/Agent 工具并非只在一个地方定义——它在 Activepieces 中横跨 Worker、API、Prompt 与前端渲染四层文件。本指南以该工具为解剖样本讲清四个文件各自的职责、删除 Worker 入口后编译通过、lint 通过、无测试覆盖、模型静默丢记忆的失败链路并给出跨分支合并时的检测配方与新增工具时的排查清单。读完你将掌握如何定位、核对与安全增删一个 Chat 工具的完整接线。背景一个 Chat 工具由四个文件共同定义Activepieces 中一个 Chat 工具参见 chat 与 agent 会话的完整机制并不是一个文件定义一个函数那么简单。以ap_remember把用户交代的持久事实写入记忆为例它由四个文件各负责一段职责文件历史分支布局职责worker/.../ee/chat/chat-worker-tools.tstool({ description, inputSchema, execute })入口直接交给streamText——唯一让工具真正可被模型调用的地方api/.../ee/chat/tools/chat-tools.tsexecuteTool的 switch case负责实际干活api/.../ee/chat/chat-rpc-handlers.ts系统提示词告诉模型有这个工具、何时该调用它web/.../chat-with-ai/lib/message-blocks.ts该工具调用结果在 UI 中的渲染方式四层之间唯一的胶水是工具名字符串如ap_remember。除此之外没有任何共享注册表或类型约束把它们拴在一起——这正是问题所在。当前仓库中四层实现的实际落点原文档描述的是feat/flowless-action-runs功能分支时代的文件布局。在当前仓库主干中这一职责拆分依然成立但对应文件已迁移重组四层分别落在Worker 端工具定义入口cross-project-tools.ts 中ap_remember: tool({...})以aiSDK 的tool()构造description提示模型何时保存记忆、inputSchemaz.object({ memory: z.string() })与execute转发给executeTool(ap_remember, toolInput)。文件整体返回一个ToolSet最终交给streamText——与文档所述唯一让工具可被调用的定位一致。API 端执行逻辑agent-tools.ts 的executeCrossProjectTool中case ap_remember校验memory非空后调用agentMemoryAi.applyInstruction({ platformId, userId, instruction, log })落库返回{ remembered: true }。这是一个典型的switch (toolName)分发结构——API 端只认字符串Worker 端是否注册了这个工具它无从知晓。API 端系统提示词agent-surface-notes.ts 在 surface notes 中写入 Save to memory withap_remember(silent) whenever it would spare the user from repeating themselves next time同时在 tool-execution-rpc.ts 中OWNER_SCOPED_TOOLS [ap_remember]还把它列入了仅限资源所有者owner作用域的工具集合用于 RPC 层的权限校验。Web 端渲染message-blocks.ts 按toolName ap_remember分支把输出为output-available状态且带memory文本的调用折叠成一个memory-saved消息块用户看到的是已记住 XXX的确认气泡。从源码结构可以清晰看到四层都以ap_remember这个裸字符串为唯一耦合点任意一层丢失其他三层都无法通过编译或类型检查发现。静默失败机制删掉 Worker 入口后发生了什么只删除 Worker 端那一个入口chat-worker-tools.ts中的tool()定义没有任何环节会大声报错编译通过Worker、API、Web 是相互独立的 TS 项目Worker 少导出一个对象不影响其他包的编译。Lint 通过没有 lint 规则去交叉核对提示词里提到的工具名与实际注册的工具集。无测试覆盖当时没有测试断言提示词中出现的每个工具名都存在于 streamText 的 ToolSet 中。API handler 仍然健在executeTool的 switch case、RPC 层、渲染层全都在服务端照常响应调用。于是链路变成系统提示词仍指示模型需要记住时就调用ap_remember但模型拿到的 ToolSet 里已经没有这个工具了——模型无法调用它也不会为此报错只会安静地跳过。用户那句 remember that I… 被模型礼貌地确认随后被丢弃记忆从未写入。唯一的外部信号是 memory eval 指标回归。当前仓库的 agent eval 侧仍然保留着这一层校验的痕迹memory-saves-when-asked.json 与 memory-saves-volunteered-fact.json 两个 fixture 正是用来评估用户要求记忆时 / 用户主动透露事实时Agent 是否正确产出ap_remember调用的场景。这类 eval 不检查编译结果只检查行为结果所以它能在 CI 全绿的情况下暴露此类回归——但也只有在 eval 覆盖到对应工具时才会报警。真实事故复盘一个干净 revert如何混入文档记录的案例发生在feat/flowless-action-runs分支上chat-worker-tools.ts是从一个更早被放弃的分支原样复制verbatim过来的。那个废弃分支的最后一个提交比ap_remember的 PR#14375早三个小时——也就是说这个文件里恰好不包含ap_remember于是复制过来的是一个内容上少了最新工具、但语法完全合法的文件由于它是完整文件覆盖而非逐行修改合并时不会产生任何冲突没有冲突 没有人工 review 的聚焦点改动就这样干净地进来了。这就是本 gotcha 想要强调的教训无冲突的合并 ≠ 正确的合并。文件级的整体覆盖可以把删除伪装成没改动过。检测配方比较 blob 而非肉眼审查当功能分支碰过像 chat tools 这样的高频共享文件时不要只盯着你想改的那一处做 review。用 git 直接把该分支该文件的实际内容与**合并基merge base**逐字节对比并要求差异恰好等于你预期的改动git diff merge-base branch-commit -- file # 必须只显示你预期的改动merge-base用git merge-base main branch求出分支分叉点而不是默认的HEADbranch-commit分支的最新提交或你要 review 的任一提交file需要核对的共享文件路径判断标准diff 输出里只能出现你计划中的变更。任何多出来的删除行、整体回退、与需求无关的差异都要当场追查来源——它们很可能就是带着旧代码回来了的静默 revert。若发现 diff 显示整个文件被替换成旧版本可以进一步用git log --follow -- file核对文件来源确认它是否继承自某个已废弃分支。增删 Chat 工具的排查清单无论新增还是移动一个 Chat 工具都不要相信我改了定义文件就够了。用工具名去 grep 全部四个文件逐一确认每个命中点仍然接线正确# 以 ap_remember 为例在仓库内全量搜索工具名 grep -rn ap_remember packages/server/worker packages/server/api packages/web/src对每个命中点核对Worker 端tool({...})入口是否存在execute是否仍指向正确的处理函数API 端执行层switch (toolName)中是否有对应 case且参数解析、权限校验、落库逻辑完好API 端提示词/RPC 层系统提示词是否仍指示模型调用它若该工具属于 owner 作用域OWNER_SCOPED_TOOLS之类的清单是否同步更新Web 端渲染层message-blocks.ts是否有对应分支输出状态与字段是否与新的返回结构匹配例如memory字段、output-available状态。同时留意工具名字符串是四层之间唯一的联动机制没有共享注册表可供类型检查兜底所以名字拼写不一致也是一种隐蔽的断线方式——grep 时建议连同命名变体如带ap_前缀与否一起核对。预防与改进方向从当前仓库代码可以推断社区已围绕这类风险做了部分缓解但核心缺口仍在eval 行为测试是最后防线agent-rpc-handlers相关单测见 agent-rpc-handlers.test.ts与 worker 侧 agent-eval fixture 能捕获提示词要求但工具集缺失的行为回归但它们只覆盖被纳入 eval 的工具新增工具若未配套 fixture 依然裸奔。提示词与工具集应可交叉验证理想做法是把系统提示词中提到的工具名做成常量集合并在构建 Worker ToolSet 时断言提示词引用的每个名字都在 ToolSet 中。当前代码中提示词文本agent-surface-notes.ts与 ToolSetcross-project-tools.ts分属两个进程的代码尚无这样的共享校验。合并纪律对共享文件坚持逐行修改 对比 merge-base的 review 流程杜绝整体文件覆盖进入主干。小结一个 Chat 工具在 Activepieces 中由 Worker 工具定义、API 执行分发、系统提示词与前端渲染四个文件共同构成工具名是它们之间唯一的契约。删除 Worker 入口不会触发任何编译、lint 或测试错误只会让模型在用户不知情的情况下丢记忆唯一的信号是 memory eval 回归。因此改动共享文件后必须对比 merge-base 确认差异纯净新增或移动工具后必须 grep 全部四个文件核对接线——这两条纪律是防止此类静默故障的最后屏障。【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/13 12:07:37 · 阅读 1.2k Activepieces Chat 工具四文件架构解析：为何丢失 Worker 端定义会静默失败
Activepieces Chat 工具四文件架构解析为何丢失 Worker 端定义会静默失败【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepiecesap_remember这类 Chat/Agent 工具并非只在一个地方定义——它在 Activepieces 中横跨 Worker、API、Prompt 与前端渲染四层文件。本指南以该工具为解剖样本讲清四个文件各自的职责、删除 Worker 入口后编译通过、lint 通过、无测试覆盖、模型静默丢记忆的失败链路并给出跨分支合并时的检测配方与新增工具时的排查清单。读完你将掌握如何定位、核对与安全增删一个 Chat 工具的完整接线。背景一个 Chat 工具由四个文件共同定义Activepieces 中一个 Chat 工具参见 chat 与 agent 会话的完整机制并不是一个文件定义一个函数那么简单。以ap_remember把用户交代的持久事实写入记忆为例它由四个文件各负责一段职责文件历史分支布局职责worker/.../ee/chat/chat-worker-tools.tstool({ description, inputSchema, execute })入口直接交给streamText——唯一让工具真正可被模型调用的地方api/.../ee/chat/tools/chat-tools.tsexecuteTool的 switch case负责实际干活api/.../ee/chat/chat-rpc-handlers.ts系统提示词告诉模型有这个工具、何时该调用它web/.../chat-with-ai/lib/message-blocks.ts该工具调用结果在 UI 中的渲染方式四层之间唯一的胶水是工具名字符串如ap_remember。除此之外没有任何共享注册表或类型约束把它们拴在一起——这正是问题所在。当前仓库中四层实现的实际落点原文档描述的是feat/flowless-action-runs功能分支时代的文件布局。在当前仓库主干中这一职责拆分依然成立但对应文件已迁移重组四层分别落在Worker 端工具定义入口cross-project-tools.ts 中ap_remember: tool({...})以aiSDK 的tool()构造description提示模型何时保存记忆、inputSchemaz.object({ memory: z.string() })与execute转发给executeTool(ap_remember, toolInput)。文件整体返回一个ToolSet最终交给streamText——与文档所述唯一让工具可被调用的定位一致。API 端执行逻辑agent-tools.ts 的executeCrossProjectTool中case ap_remember校验memory非空后调用agentMemoryAi.applyInstruction({ platformId, userId, instruction, log })落库返回{ remembered: true }。这是一个典型的switch (toolName)分发结构——API 端只认字符串Worker 端是否注册了这个工具它无从知晓。API 端系统提示词agent-surface-notes.ts 在 surface notes 中写入 Save to memory withap_remember(silent) whenever it would spare the user from repeating themselves next time同时在 tool-execution-rpc.ts 中OWNER_SCOPED_TOOLS [ap_remember]还把它列入了仅限资源所有者owner作用域的工具集合用于 RPC 层的权限校验。Web 端渲染message-blocks.ts 按toolName ap_remember分支把输出为output-available状态且带memory文本的调用折叠成一个memory-saved消息块用户看到的是已记住 XXX的确认气泡。从源码结构可以清晰看到四层都以ap_remember这个裸字符串为唯一耦合点任意一层丢失其他三层都无法通过编译或类型检查发现。静默失败机制删掉 Worker 入口后发生了什么只删除 Worker 端那一个入口chat-worker-tools.ts中的tool()定义没有任何环节会大声报错编译通过Worker、API、Web 是相互独立的 TS 项目Worker 少导出一个对象不影响其他包的编译。Lint 通过没有 lint 规则去交叉核对提示词里提到的工具名与实际注册的工具集。无测试覆盖当时没有测试断言提示词中出现的每个工具名都存在于 streamText 的 ToolSet 中。API handler 仍然健在executeTool的 switch case、RPC 层、渲染层全都在服务端照常响应调用。于是链路变成系统提示词仍指示模型需要记住时就调用ap_remember但模型拿到的 ToolSet 里已经没有这个工具了——模型无法调用它也不会为此报错只会安静地跳过。用户那句 remember that I… 被模型礼貌地确认随后被丢弃记忆从未写入。唯一的外部信号是 memory eval 指标回归。当前仓库的 agent eval 侧仍然保留着这一层校验的痕迹memory-saves-when-asked.json 与 memory-saves-volunteered-fact.json 两个 fixture 正是用来评估用户要求记忆时 / 用户主动透露事实时Agent 是否正确产出ap_remember调用的场景。这类 eval 不检查编译结果只检查行为结果所以它能在 CI 全绿的情况下暴露此类回归——但也只有在 eval 覆盖到对应工具时才会报警。真实事故复盘一个干净 revert如何混入文档记录的案例发生在feat/flowless-action-runs分支上chat-worker-tools.ts是从一个更早被放弃的分支原样复制verbatim过来的。那个废弃分支的最后一个提交比ap_remember的 PR#14375早三个小时——也就是说这个文件里恰好不包含ap_remember于是复制过来的是一个内容上少了最新工具、但语法完全合法的文件由于它是完整文件覆盖而非逐行修改合并时不会产生任何冲突没有冲突 没有人工 review 的聚焦点改动就这样干净地进来了。这就是本 gotcha 想要强调的教训无冲突的合并 ≠ 正确的合并。文件级的整体覆盖可以把删除伪装成没改动过。检测配方比较 blob 而非肉眼审查当功能分支碰过像 chat tools 这样的高频共享文件时不要只盯着你想改的那一处做 review。用 git 直接把该分支该文件的实际内容与**合并基merge base**逐字节对比并要求差异恰好等于你预期的改动git diff merge-base branch-commit -- file # 必须只显示你预期的改动merge-base用git merge-base main branch求出分支分叉点而不是默认的HEADbranch-commit分支的最新提交或你要 review 的任一提交file需要核对的共享文件路径判断标准diff 输出里只能出现你计划中的变更。任何多出来的删除行、整体回退、与需求无关的差异都要当场追查来源——它们很可能就是带着旧代码回来了的静默 revert。若发现 diff 显示整个文件被替换成旧版本可以进一步用git log --follow -- file核对文件来源确认它是否继承自某个已废弃分支。增删 Chat 工具的排查清单无论新增还是移动一个 Chat 工具都不要相信我改了定义文件就够了。用工具名去 grep 全部四个文件逐一确认每个命中点仍然接线正确# 以 ap_remember 为例在仓库内全量搜索工具名 grep -rn ap_remember packages/server/worker packages/server/api packages/web/src对每个命中点核对Worker 端tool({...})入口是否存在execute是否仍指向正确的处理函数API 端执行层switch (toolName)中是否有对应 case且参数解析、权限校验、落库逻辑完好API 端提示词/RPC 层系统提示词是否仍指示模型调用它若该工具属于 owner 作用域OWNER_SCOPED_TOOLS之类的清单是否同步更新Web 端渲染层message-blocks.ts是否有对应分支输出状态与字段是否与新的返回结构匹配例如memory字段、output-available状态。同时留意工具名字符串是四层之间唯一的联动机制没有共享注册表可供类型检查兜底所以名字拼写不一致也是一种隐蔽的断线方式——grep 时建议连同命名变体如带ap_前缀与否一起核对。预防与改进方向从当前仓库代码可以推断社区已围绕这类风险做了部分缓解但核心缺口仍在eval 行为测试是最后防线agent-rpc-handlers相关单测见 agent-rpc-handlers.test.ts与 worker 侧 agent-eval fixture 能捕获提示词要求但工具集缺失的行为回归但它们只覆盖被纳入 eval 的工具新增工具若未配套 fixture 依然裸奔。提示词与工具集应可交叉验证理想做法是把系统提示词中提到的工具名做成常量集合并在构建 Worker ToolSet 时断言提示词引用的每个名字都在 ToolSet 中。当前代码中提示词文本agent-surface-notes.ts与 ToolSetcross-project-tools.ts分属两个进程的代码尚无这样的共享校验。合并纪律对共享文件坚持逐行修改 对比 merge-base的 review 流程杜绝整体文件覆盖进入主干。小结一个 Chat 工具在 Activepieces 中由 Worker 工具定义、API 执行分发、系统提示词与前端渲染四个文件共同构成工具名是它们之间唯一的契约。删除 Worker 入口不会触发任何编译、lint 或测试错误只会让模型在用户不知情的情况下丢记忆唯一的信号是 memory eval 回归。因此改动共享文件后必须对比 merge-base 确认差异纯净新增或移动工具后必须 grep 全部四个文件核对接线——这两条纪律是防止此类静默故障的最后屏障。【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考