人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载本文以 IronClaw 仓库中的 tests/e2e/LIVE_TOOL_FAILURES.md 为核心素材系统复盘在 20 轮活体livepersona 工作流中反复出现的七类工具误用模式——从声称已记录但根本没有写入到patch 模式参数错用再到用 CodeAct 脚本干本可以用内存工具完成的活。读完本文你将掌握如何基于真实 LLM 轨迹定位 Agent 工具选择缺陷如何把修复动作正确分层到工具描述、Skill/Persona 契约与运行时一致性校验三个层面以及如何把这类声称-效果不一致的问题变成可诊断、可回收的工程流程。一、素材来源与观测范围这份失败笔记的诞生背景是团队在迭代tests/e2e_live_personas.rs中的长程 persona 工作流CEO、内容创作者、交易员等角色单会话 20 轮以上时发现测试失败并不总是代码 bug——很多时候是模型系统性地选错了动作或者在落盘之前就向用户宣告成功。笔记开宗明义目标不只是让测试通过。这些失败暴露了工具描述与路由提示affordance弱到让模型频繁选错动作、或在持久化之前声称成功的位置。观测样本来自已提交的活体 persona 轨迹与本地生成的日志。笔记中点名的三份关键轨迹在当前仓库中对应 tests/fixtures/llm_traces/live/ 目录下提交的 JSON 轨迹文件例如tests/fixtures/llm_traces/live/ceo_full_workflow.jsontests/fixtures/llm_traces/live/content_creator_full_workflow.jsontests/fixtures/llm_traces/live/trader_full_workflow.json该目录中还有developer_full_workflow.json、mission_daily_news_digest.json等更多活体轨迹构成同一观测面的样本集。这些轨迹的可获取性本身就是这套方法的前提tests/e2e/README.md 在 Live Persona Failure Notes 一节中显式指向本笔记作为 E2E 文档体系的组成部分。二、七类反复出现的工具误用模式以下逐一展开笔记记录的七类模式每类的现场表现、成因分析和当时有效的缓解手段均继承自原文档并补充仓库中可核验的实现证据。2.1 模式一未写入就声称成功最常见现场助手回答中出现了 tracked已跟踪、created已创建、parked已停放、recorded已记录等措辞但轨迹里找不到对应的memory_write调用——暗示要写入的 workspace 文件实际并未持久化。出现在 CEO 后期轮次的承诺记录提示词收紧之前、创作者的趋势承诺、停放想法、赞助/临近到期内容跟踪等场景。成因笔记归因模型把一句听起来合理的自然语言确认当成了足够工具描述没有让先写后确认产生强制感早期 persona bundle 指令对持久化要求过软。被证明有效的缓解收紧 skill 指令显式禁止在memory_write成功之前给出确认把提示词中抽象的 note this 改写为明确的 track this commitment / park this idea。这一模式的本质是运行时一致性问题而非措辞问题助手宣称的效果与工具实际产生的效果之间出现了缺口详见第四节运行时护栏部分。2.2 模式二memory_writepatch 模式误用现场模型经常尝试 patch 模式但参数不合规笔记中记录了真实出现的错误信息new_string is required when old_string is providedold_string cannot be emptyPatch failed ... old_string not found in document出现在创作者流水线更新与交易员历史轨迹中。成因在不知道文件确切现有文本时模型猜了 patch 模式而简单覆写/追加会更安全工具描述对不确定现有文本时请整写这一点强调不足。仓库佐证IronClaw 的内存工具参数契约定义在 crates/extensions/packages/memory-native/schemas/memory/document-write.input.v1.json可以看到 patch 机制的完整参数面old_stringExact text to replace; switches to patch mode、new_stringReplacement text for patch mode、replace_allpatch 模式下是否替换全部出现默认false以及content/append追加模式默认true这条全量写入路径。也就是说 schema 层面同时提供了整写/追加与精确替换两条路笔记推荐的正是让模型在拿不准时优先走前者。这些校验行为在宿主运行时测试中有直接对应用例crates/kernel/ironclaw_host_runtime/tests/first_party_builtin_tools.rs 中的memory_write_patches_existing_document_and_rejects_missing_old_string覆盖了patch 成功替换与 old_string 缺失被拒两条路径memory_write_rejects_empty_new_string_replacement同文件 #L3496则覆盖了空new_string的拒绝逻辑——即笔记中记录的那些错误字符串确实来自这套校验实现。2.3 模式三用memory_read探测尚不存在的文件现场memory_read(commitments/README.md)之类的先读后建探测在交易员和创作者的 setup 阶段反复出现。成因模型把memory_read当作存在性检查使用而工具对不存在的文档返回硬错误而非更柔和的 not-found 哨兵值。现状与改进方向harness 目前将这类错误视为良性可恢复错误处理。笔记建议的memory_read描述增补是文档缺失在 setup 期很常见。not-found 错误通常意味着你该用memory_write创建这个文件。2.4 模式四用户只要求跟踪却触发了创意生成工具现场创作者工作流中用户只想跟踪截止日期模型却调用了image_generate(...)缩略图截止日期轮次、生成了 TikTok/Twitter 文案而非仅跟踪分发期限。成因内容创作者 persona 天然诱导动手做创意类工具描述没有把制作资产与跟踪制作义务区分开。被证明有效的缓解提示词显式写 Track this commitment only / Do not create assets.persona bundle 层面加规则——未被明确要求时不生成资产。笔记给创意工具的推荐描述是当用户只是要跟踪截止日期、义务或工作流阶段时不要使用本工具。2.5 模式五工作流跟踪任务上误触发__codeact__脚本执行现场出现 SyntaxError 轨迹、Monty 中不支持的 Python 语法、CodeAct 脚本里被 OS 限制的操作。成因从源码结构看模型把结构化 workspace 更新当成了小型编程任务而它其实只是普通持久化。推荐改进加在工具发现/元引导面上workspace 跟踪优先使用memory_read/memory_write/memory_tree除非用户明确要求 memory 工具做不了的计算或转换否则不要动用 CodeAct 或 shell 脚本。2.6 模式六写错命名空间 / 路径族现场写入路径与预期 commitments workspace 结构语义上接近但不对例如content/...而非commitments/content-pipeline/...commitments/signals/...而非commitments/open/...。成因路径约定存在于 skill 中但工具描述没有强化 workspace 契约模型从自己在散文里发明的文件名做泛化。推荐改进memory_write可加一句当 skill 或工作流指定了目标目录就精确写到那里不要发明平行的顶层命名空间。2.7 模式七限流与可选后端缺口带来的响亮但可恢复错误现场真实环境中的临时工具限流、图像生成模型不可用flux-1.1-pronot found等。这些确实是环境问题但观测中它们并不总是使业务结果失效。现状harness 在运行明确恢复时会把这些错误过滤为良性。产品级建议临时故障的工具返回文本应当明确表达可重试性与推荐回退路径例如temporary rate limit; retry later临时限流稍后重试optional creative backend unavailable; continue with tracking-only flow可选创意后端不可用继续走仅跟踪流程三、责任分层改动应该落在哪一层这是整份笔记方法论价值最高的部分。笔记在对照#2025coding/file-tools PR后给出明确的三层分工层职责例子工具描述讲清工具机制与边界patch 模式何时可用、not-found 语义、tracking vs creation 的区分Skill / persona bundle定义工作流义务persist before confirm先持久化再确认运行时检查捕获高置信度的声称-效果错配说 tracked 却没有对应memory_write#2025通过让文件/编码工具的操作契约更清晰write_file与 workspace memory 的区分、apply_patch精确性、文件历史改进了文件工具但它没有让工具描述承担更高层的工作流策略。笔记据此做了一个重要的自我修正早期让memory_write自己声明本工具成功前任务未完成”的建议过强。那条规则属于 skill 层和可能的运行时校验不属于通用内存工具描述。并给出反例清单——以下内容不应靠往memory_write里塞策略解决除非写入成功否则不要声称 tracked停放想法在持久化之前不算完成决策捕获只有当决策文档与 intel 文档都写入才算成功这些是 skill 级契约而仓库已经朝这个方向演进IronClaw 的 skills/ 目录下就包含笔记点名的 decision-capture、commitment-triage、idea-parking 等 skill 包持久化策略的正主就是它们的SKILL.md文案。分层原则总结为四句话文件工具讲文件机制内存工具讲 workspace 机制skill 讲任务工作流运行时在需要处强制执行声称/效果一致性。四、具体的工具描述改进建议可直接落地笔记给出了按工具切分的描述改稿全部聚焦机制与安全用法刻意剥离工作流策略memory_writePrefer fullcontentwrites unless you have just read the file and know the exact text to replace.优先全量content写入除非你刚读过文件且知道要替换的确切文本。Do not use patch mode with an emptyold_string.不要以空old_string用 patch 模式。Do not invent alternate workspace roots when the skill specifies a path.skill 指定了路径时不要发明平行的 workspace 根。memory_readMissing documents are common during setup. A not-found error often means you should create the file withmemory_write.image_generateUse only when the user wants an image asset created or edited. Not for deadline tracking, workflow updates, or commitment capture.工具发现 / 元引导面For commitment/workflow tracking, default to memory tools.Do not use CodeAct or shell for simple workspace updates.笔记强调这类内容仍属于工具选择引导不是工作流策略——这是与第三节分层原则一致的。五、产品级修复运行时声称-效果护栏笔记把模式一声称成功未写入定性为这是运行时一致性问题而不是工具描述问题。推荐方案是一个轻量的工具循环后校验post-tool-loop check在助手回复中检测高置信度的跟踪类措辞tracked、recorded、parked、created commitment若命中这些措辞但本回合没有对应的memory_write则不直接把该回复返回用户而是强制再走一轮修复repair pass这属于可恢复的工具循环失误recoverable tool-loop miss而非直接失败。这个设计的巧妙之处在于它没有试图让 LLM 自觉而是把声称与效果的一致性变成可程序化检测的不变量——措辞命中而写入缺失是一个可以机械判定的信号。六、推荐跟进清单笔记原文的 5 条 follow-up收紧memory_write的 patch 模式引导而不是它的工作流策略给创意类工具加一条简短的 tracking-only vs creation仅跟踪 vs 创建警告为高置信跟踪措辞增加运行时护栏助手说 tracked/recorded/parked 却没有对应写入时视为可恢复的工具循环失误强制再跑一轮持久化规则留在 skill / persona bundle 层持续在活体会话日志中记录 skill 激活与轮内工具事件——正是这些日志让上述失败变得可诊断。七、方法论小结把活体轨迹当作一等测试资产IronClaw 这套做法的可复用要点在于流程而非结论活体轨迹提交进仓库tests/fixtures/llm_traces/live/使模型选错工具这类非确定性现象变成可反复回放的证据失败笔记按模式归类而非按测试用例归类每条模式附带现场证据、成因归因、已验证缓解手段与推荐改稿天然形成回归清单修复动作先分层再动手机制问题改工具描述义务问题改 skill 契约一致性问题交给运行时护栏避免把策略塞进通用工具描述造成跨 persona 的副作用日志即诊断基础设施skill 激活与工具事件的轮内日志是把感觉模型在瞎搞变成第 N 轮调用 X 而 Y 未发生的关键。对于任何在构建长程 Agent 工作流的团队这份 314 行的失败笔记比十条通用最佳实践更值钱——它每一条都对应一段真实轨迹里可复现的错误。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐agno 工具调用轨迹数据生成实战从真实工具 Schema 到多轮轨迹的 SFT 数据流水线agno 工具调用轨迹数据生成实战从真实工具 Schema 到多轮轨迹的 SFT 数据流水线 本文围绕 agno 仓库中 cookbook/data_labe人工智能大模型AI AgentAgent 框架多智能体工具调用RAGAgent 工作流Agent 记忆静态工具描述测试的运行时代价OpenClaw Agent Tools 轻量发现架构与性能护栏静态工具描述测试的运行时代价OpenClaw Agent Tools 轻量发现架构与性能护栏 本篇面向 OpenClaw原 lobster仓库内 src/AI 应用AI Agent交互助手后端即时通讯网关Dify AI 工作流平台开源贡献完整指南从本地跑通到 PR 合并路线图Dify AI 工作流平台开源贡献完整指南从本地跑通到 PR 合并路线图 这篇 Dify 开源贡献指南带你走完闭环读完你能独立做到——把 Dify 前后端跑人工智能大模型LLMOpsAI 应用RAGAI Agent低代码上一篇Qwen Code 多文件读取机制全解析read_many_files 的演进与 read_file / glob / grep_search 组合实践下一篇CSS Vars Ponyfill 项目常见问题解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考