Skip to content

fix(skill): 修正 research-paper-writing 工具调用方式，修复 execute_code 不传 code#559

Open
ncw1992120 wants to merge 3 commits into
mateaix:devfrom
ncw1992120:fix/skill-execute-code-no-code-supplied
Open

fix(skill): 修正 research-paper-writing 工具调用方式，修复 execute_code 不传 code#559
ncw1992120 wants to merge 3 commits into
mateaix:devfrom
ncw1992120:fix/skill-execute-code-no-code-supplied

Conversation

@ncw1992120

@ncw1992120 ncw1992120 commented Jul 23, 2026

Copy link
Copy Markdown
Contributor

背景

Fixes #557

模型在调用 execute_code 工具时不传 code 参数，稳定报错 No code supplied。根因是 research-paper-writing 技能的 "Tool Usage Patterns" 段落教了错误的调用方式——这是仓库里唯一演示 execute_code 实际调用的地方，且被标注为「最常见模式」，模型会模仿。

改动

修正 research-paper-writing/SKILL.md 的 "Tool Usage Patterns" 整段（2159–2200 行），使所有工具调用使用真实的工具名和正确的参数签名：

原写法（错误） 改为 原因
execute_code("analyze results JSON, compute metrics") execute_code(language="python", code="...") schema 要求 language/code 为命名参数，单位置字符串会被绑定为 null → "No code supplied"
terminal(...) (×4) execute_shell_command(...) 无 terminal 工具（也无别名层），真实工具名为 execute_shell_command
send_message(...) 删除 无此工具
delegate_task("...") (×3) delegateToAgent(agentName="...", task="...") 无 delegate_task 工具；delegateToAgent 需两个必填位置参数，原写法漏了 agentName
web_extract（任务描述内） web_search 无 web_extract 工具
# In execute_code: # Pass this as the code= argument to: execute_code(language="python", code=...) 消除「这是工具调用语法」的歧义

所有引用的工具名均可对应到 mateclaw-server/src/main/java/vip/mate/tool/builtin/ 下的 @Tool 定义：execute_shell_command（ShellExecuteTool）、execute_code（CodeExecuteTool）、delegateToAgent（DelegateAgentTool）、web_search（WebSearchTool）。

关于 ISSUE 里的可选加固项（sanitizeToolCallArguments）

ISSUE 把「JSON 截断时保留已解析字段」列为可选项。调查后结论是不做——见 issue #557 的评论：部分解析会破坏下游截断检测（依赖参数是非法 JSON 才触发「缩短重发」指引）、有语义风险、且代码库无现成 lenient 解析器可复用。{} 替换是有意为之。

验证

  • git diff 确认改动仅限目标段落（2160–2192 行）
  • 逐个核对引用的工具名均有对应 @Tool 定义且参数签名一致

改动范围

单文件、纯文档修正，无逻辑变更：

 mateclaw-server/src/main/resources/skills/research-paper-writing/SKILL.md | 23 +++++++++++-----------
 1 file changed, 12 insertions(+), 11 deletions(-)

@ncw1992120
fix(skill): correct execute_code calling convention in research-paper…
fdaf0ba 
…-writing

The "Tool Usage Patterns" section taught the model wrong tool-call syntax
that caused it to call execute_code without the required `code` parameter,
producing "No code supplied" errors (issue mateaix#557).

- execute_code: single positional string -> named params
  (language="python", code="...") as the schema requires
- terminal(...) -> execute_shell_command(...) (no `terminal` tool exists)
- delegate_task(...) -> delegateToAgent(agentName=..., task=...) (no
  `delegate_task` tool; delegateToAgent requires a positional agentName)
- removed send_message(...) (no such tool)
- web_extract -> web_search in delegate task descriptions
- clarified the citation-verification code block as the code= body, not
  tool-call syntax

Refs: mateaix#557
@ncw1992120

ncw1992120 commented Jul 23, 2026

Copy link
Copy Markdown
Contributor Author

评审意见

方向正确、单一关注点、替换的工具名已逐一核实为真：

  • execute_shell_command — ShellExecuteTool.java:59 ✅
  • delegateToAgent(agentName=..., task=...) — DelegateAgentTool.java:214，参数名与必填性均正确 ✅
  • web_search — WebSearchTool.java:28 ✅
  • 新示例把 code= 写成实际代码、Citation verification 段补 # Pass this as the code= argument 注释，均直接对症 [Bug] 模型调用 execute_code 不传 code 参数，报错 No code supplied #557

必须修：改动不完整，同类误导源在同一文件里大量残留。

PR 只改了 2160-2192 行的两个 pattern 块，但对照 builtin 工具全量清单核查后，同文件还有以下残留（行号按 base）：

位置 残留内容 问题
2146-2157 工具表格（修复段落上方 3 行） terminal / web_extract / delegate_task / todo / memory / cronjob / clarify / send_message 8 个名字全部不是真实工具。cron 真名是 create_cron_job 等；memory 真名是 write_workspace_memory_file 等；todo/clarify/send_message/terminal 无任何对应物
2230-2232 terminal("git log --oneline -10") 等 3 处 与原 bug 完全相同的"单字符串位置参数"调用风格——这正是 #557 定性中教坏模型的模式本身
84 / 157 / 257 / 264-265 / 312 clarify / todo / web_extract / delegate_task 同上，散布在正文
2203-2216 / 2236-2238 / 2269 / 2295 memory+todo 小节 / cronjob / send_message / clarify 整节按不存在的工具展开

SKILL.md 是整篇进模型上下文的，表格离修复处只有几行，误导权重不低于已修掉的示例。这些残留与本 PR 标题"修正工具调用方式"是同一关注点，应补进本 PR：

  • 有真实对应物的逐个映射改名：terminal→execute_shell_command、delegate_task→delegateToAgent(agentName=..., task=...)、cronjob→create_cron_job/list_cron_jobs、memory→workspace memory 系列（write_workspace_memory_file 等）、web_extract→web_search（或现有文档抽取工具，按语义选）
  • 无对应物的（clarify/send_message/todo）删除该行，或改写为"直接在回复中询问/告知用户"之类的非工具表述
  • 2230-2232 的 terminal("...") 改为 execute_shell_command("...") 并保持具名参数风格与 2160 段一致

@ncw1992120
fix(skill): complete tool-name cleanup across research-paper-writing …
bc625ad 
…SKILL.md

Address PR review: the first commit only fixed the "Tool Usage Patterns"
block, but the same file referenced many more non-existent tools. Map every
tool reference to a real registered tool (verified against @tool definitions)
and drop tools that have no equivalent.

Tool table + Related Skills table:
- terminal/process -> execute_shell_command (folded background-process usage)
- patch -> edit_file
- delegate_task -> delegateToAgent(agentName=..., task=...)
- memory -> write_workspace_memory_file / search_workspace_memory
- cronjob -> create_cron_job / list_cron_jobs
- todo -> progress_update (closest real progress tracker)
- web_extract -> web_search (+ browser_use for a specific page)
- skill_view -> load_skill(skillName=...)
- removed clarify / send_message rows (no equivalent tools)

Body sections:
- State Management: memory()/todo()/terminal() rewritten to real tools
- Cron Monitoring: cronjob("create",{schedule,prompt}) ->
  create_cron_job(name=, cronExpression=, triggerMessage=)
- Communication/Decision: send_message/clarify -> direct response guidance
- scattered clarify/todo/web_extract/delegate_task refs corrected

Documentation only; no logic change. Every tool name now resolves to a real
@tool definition.

Refs: mateaix#557
@ncw1992120

ncw1992120 commented Jul 23, 2026

Copy link
Copy Markdown
Contributor Author

已按评审意见补全（新增 commit bc625add）

评审指出「改动不完整，同类误导源大量残留」。已对全文做彻底清理，所有工具引用逐一映射到真实注册工具（均核对到 @Tool 定义），无对应物者删除或改为非工具表述。

工具名映射（均验证存在）

原（不存在） 改为（真实工具）
terminal / process execute_shell_command（并入后台进程用法 nohup ... & / ps / kill）
patch edit_file
delegate_task delegateToAgent(agentName=..., task=...)（补回必填 agentName）
memory write_workspace_memory_file / search_workspace_memory
cronjob create_cron_job(name=, cronExpression=, triggerMessage=) / list_cron_jobs
todo progress_update(stepKey=, label=, status=, note=)（最接近的真实进度跟踪器）
web_extract web_search（+ browser_use 取特定页面）
skill_view load_skill(skillName=...)
clarify / send_message 删除（无对应工具），改为「直接在回复中提问/告知」

覆盖范围

  • 工具表格（Tools Reference）+ Related Skills 表
  • State Management 段（memory()/todo()/terminal() 全部改写）
  • Cron Monitoring 段（cronjob("create",{schedule,prompt}) → create_cron_job(...)）
  • Communication / Decision Points 段
  • 散布引用（:84 clarify、:157 todo、:248 terminal、:255 skill_view、:257/264 web_extract、:312 delegate_task）

验证

  • 全文 grep 伪工具调用模式（terminal(/delegate_task/web_extract/cronjob/send_message/skill_view/todo(/memory( 等）已无残留
  • 新引入的 15 个工具名逐一核对到 mateclaw-server/.../tool/builtin/ 下的 @Tool 定义

两处说明

  1. skill_manage("install", "qmd")（Related Skills 表 qmd 行）保留未动：skill_manage 是真实工具但用于 create/edit/patch/delete 技能内容，并无 "install" 动作；评审未列出此行，且我未核实到正确的「安装技能」写法，为避免引入新错误暂保留，欢迎指正。
  2. 代码类改动（@Tool 描述警告 + sanitize「第三选项」+ 补 WARN）不在本 PR：按单一关注点原则，这些属服务端参数处理/模型引导，与文档修复分离，将另开后续 PR（见 [Bug] 模型调用 execute_code 不传 code 参数，报错 No code supplied #557 评论的调查结论）。

仍为纯文档改动，无逻辑变更。

@ncw1992120 ncw1992120 mentioned this pull request Jul 23, 2026
Open
@ncw1992120

ncw1992120 commented Jul 23, 2026

Copy link
Copy Markdown
Contributor Author

复审（针对 bc625add）：清理完整性通过，剩两处

清理完整性 ✅：将本 PR diff 应用到 base 后全文 grep，此前列出的假工具名（terminal / delegate_task / web_extract / todo / memory / cronjob / clarify / send_message / skill_view / patch / process）已零残留。

新签名核对 ✅：progress_update(stepKey, label, status, note)、create_cron_job(name, cronExpression, triggerMessage)、load_skill(skillName)、edit_file、create_reminder、delegateToAgent(agentName, task) 均与 @Tool 定义一致。write_workspace_memory_file / search_workspace_memory 的 agentId 已核实确为 LLM 可见参数（WorkspaceMemoryTool.java:139/236，非 ToolContext 注入），SKILL.md 的 agentId=<id> 写法正确。

必须修：新引入的 browser_use 示例是错误写法

Step 1.2 新增的：

browser_use("navigate to https://arxiv.org/abs/2303.17651 and extract the abstract")

browser_use 是结构化工具（BrowserUseTool.java:213-223），第一参数 action 只接受 start|stop|open|snapshot|click|type|... 枚举，自然语言任务串会绑定到 action 上直接失败——这与本 PR 要修的原 bug 是同一类错误（把工具当自然语言单字符串位置参数调用）。应改为两步：

browser_use(action="open", url="https://arxiv.org/abs/2303.17651")
browser_use(action="snapshot")

（工具表格里对 browser_use 的泛述那行没问题，只需改这个示例。）

回答说明 1 的开放问题：skill_manage("install", "qmd") 确实无正确工具写法

skill_manage 只有 create | edit | patch | delete 四个 action（SkillManageTool.java:115）；ClawHub 技能安装走 REST /api/v1/skills/install（SkillInstallController），是管理端/UI 操作，不存在可供 LLM 调用的安装工具。建议该行改为：

Install from the skill marketplace (ask the user), then load_skill(skillName="qmd")

这两处修完即可合。

@ncw1992120
fix(skill): correct browser_use example and qmd install guidance
5b2e8a7 
Address PR review (复审) of the tool-name cleanup:

- browser_use is a structured tool whose first param `action` only accepts an
  enum (start|stop|open|snapshot|...). The previous natural-language single
  string bound to `action` and would fail — the same bug class this PR fixes.
  Replace with the correct two-step form:
    browser_use(action="open", url="...")
    browser_use(action="snapshot")

- skill_manage has no "install" action (only create|edit|patch|delete); skill
  installation is a marketplace/REST operation with no LLM-callable tool.
  Reword the qmd row to "Install from the skill marketplace (ask the user),
  then load_skill(skillName=\"qmd\")".

Documentation only.

Refs: mateaix#557
@ncw1992120

ncw1992120 commented Jul 23, 2026

Copy link
Copy Markdown
Contributor Author

复审两处必改已落实（commit 5b2e8a76）

1. browser_use 示例改为结构化两步调用

browser_use 第一参数 action 只接受 start|stop|open|snapshot|... 枚举，原自然语言单串会绑定到 action 上失败（与本 PR 修的原 bug 同类）。已改为：

browser_use(action="open", url="https://arxiv.org/abs/2303.17651")
browser_use(action="snapshot")

（工具表格里对 browser_use 的泛述行未动，符合复审意见。）

2. qmd 行安装写法

skill_manage 只有 create|edit|patch|delete，无 install 动作；技能安装走市场/REST，无 LLM 可调用工具。已按建议改为：

Install from the skill marketplace (ask the user), then load_skill(skillName="qmd")

仍为纯文档改动。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Bug] 模型调用 execute_code 不传 code 参数，报错 No code supplied

1 participant

@ncw1992120