[Bug]: 只读平台工具的描述写 "Query: projectId",但 schema 要求包进 query 对象,首次调用必然失败
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 76/100
Research direction
Start with the tool descriptions in internal/application/operations.go and how they are assembled in internal/httpapi/agent_tool_catalog.go; compare these with the input schema in internal/mcpserver/schema.go. Check how existing prompts describe the query, path, and body wrappers. Done means a first call using the documented parameter shape passes validation for read-only tools.
Written by the indexing model from the issue text.
Description
[Bug]: 只读平台工具的描述写 "Query: projectId",但 schema 要求包进 query 对象,首次调用必然失败
Component / host: Platform — web / API
Edition: Platform
LoopForge version: v0.4.0(自托管镜像,诊断中平台版本显示为 (devel))
What happened?
模型第一次调用任何只读平台工具(agentflow__*)时,必然先吃一次参数校验失败,第二次才成功。
实测片段(已脱敏):
tool: mcp__agentflow_session__agentflow__workflows_list
status: failed
Validation failed for tool "mcp__agentflow_session__agentflow__workflows_list":
- projectId: unknown field
Received arguments:
{ "projectId": "welcome" }
同一次调用把参数改为 {"query": {"projectId": "..."}} 后立即成功。另一个工具同样现象:
tool: mcp__agentflow_session__workbench_tool_schema
- name: missing
- tool: unknown field
Received arguments:
{ "tool": "issues_save" }
原因链(代码定位)
-
internal/application/operations.go:81这条只读操作的自述是:List SOP workflow definitions. Query: projectId (that project's SOPs plus generic templates), q (match id/name/description). Always pass projectId when a project is known.这句话在语义上明确要求"传 projectId",但没有说明要放在
query里。 -
internal/httpapi/agent_tool_catalog.go:361-376把描述拼成
op.Description + " (" + op.Method + " " + op.Path + ")"直接交给模型,
没有附加任何"参数需包在 query 对象内"的说明。 -
internal/mcpserver/schema.go:48-90生成的 inputSchema 顶层是
{"type": "object", "additionalProperties": false},属性只有path/query/body。
因此顶层出现projectId一定被判unknown field。 -
全仓库检索
body/path/query这组包装说明,只出现在写入草稿路径:internal/httpapi/assistant.go:1059("提交草稿前……按 body/path/query 包装参数")internal/httpapi/agent_tool_terminal.go:76
直接调用的只读工具没有任何等价提示。
也就是说:工具描述本身把模型引向了错误形状,而唯一正确的包装规则只写在另一条链路(写草稿)的提示里。模型不可能从只读工具的描述里推断出这层包装。
影响
- 每个只读工具在模型首次使用时都要浪费一轮调用,并成功前先在界面上留下一条"执行失败"。
- 一次实测对话里 13.4 秒内出现 12 次工具失败,其中 2 次属于这一类;叠加模型自身写脚本的错误后,用户看到的是连续红字,观感是"平台坏了",而这些错误其实都是可避免的契约模糊。
- 这类错误对用户没有信息量:
unknown field不告诉模型"应该放在 query 里",只能靠试错。
期望行为
任选其一即可显著改善:
- 在只读工具描述里直接写出包装形状,例如
query: {projectId?: string, q?: string},或在描述末尾统一加一句
"所有参数放入 query 对象,不要把参数放在顶层"。 - 在
platformToolInputSchema生成描述时,把query/path/body的可用字段展平进描述。 - 校验失败时返回可执行的纠正建议(例如
unknown field "projectId"; put it under "query"),而不是只回unknown field。
Reproduction
- 部署平台 v0.4.0,在 AI 对话中配置一个可用的自定义运行时与模型。
- 在对话里问"当前项目有哪些 SOP"。
- 观察模型第一次调用
agentflow__workflows_list时带{"projectId": "..."}并报
projectId: unknown field。 - 模型改为
{"query": {"projectId": "..."}}后成功。
Sanitized diagnostics
{
"kind": "tool.failed",
"source": "cli",
"tool": "mcp__agentflow_session__agentflow__workflows_list",
"message": "Validation failed for tool \"mcp__agentflow_session__agentflow__workflows_list\":\n - projectId: unknown field\n\nReceived arguments:\n{\n \"projectId\": \"welcome\"\n}"
}
{
"kind": "tool.failed",
"source": "cli",
"tool": "mcp__agentflow_session__workbench_tool_schema",
"message": "Validation failed for tool \"mcp__agentflow_session__workbench_tool_schema\":\n - name: missing\n - tool: unknown field\n\nReceived arguments:\n{\n \"tool\": \"issues_save\"\n}"
}
Safety checks
- 已移除凭证、私有端点、内部标识与个人数据。
- 已检索现有 issue,未发现重复。
- Dominant language
- Go
- Stars
- 711
- Forks
- 114
- Avg merge
- 15h
- Merged PRs (30d)
- 134
Getting set up
- Ships a Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from Tencent/LoopForge
-
Difficulty 2/5 1-3 hours Newbie friendliness 73/100
Tencent/LoopForge#1087 · 1 comment ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Tencent/LoopForge#1086 · 1 comment ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 90/100
Tencent/LoopForge#1075 · 1 comment ·
Maintainers usually reply within 1 day
-
[Bug] AI 对话切换 Claude Code 必定 400「不支持的执行器」:assistantEngineClaude 与 executorModelCatalogs 键名不一致Possibly taken @jiangjiang248 claimed this 2 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
Tencent/LoopForge#986 · 2 comments ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 69/100
Tencent/LoopForge#969 · 2 comments ·
Maintainers usually reply within 1 day
All issues in Tencent/LoopForge
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Inconsistency between golang and cue in specPossibly taken A pull request linked to this issue is open or already merged. Open
Difficulty 1/5 Under an hour Newbie friendliness 88/100
Maintainers usually reply within 1 day
-
security
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
Area/DeveloperPortal Aspect/UI Severity/Minor Type/Bug
Difficulty 1/5 Under an hour Newbie friendliness 88/100
wso2/api-platform#4369 ·
Maintainers usually reply within 1 day