[Bug]: 只读平台工具的描述写 "Query: projectId",但 schema 要求包进 query 对象,首次调用必然失败
Maintainer antworten meist innerhalb von 1 Tag
Bewertung
- Schwierigkeit
- 2/5
- Geschätzter Aufwand
- 1-3 Stunden
- Anfängerfreundlichkeit
- 76/100
Rechercherichtung
Beginne mit den Tool-Beschreibungen in internal/application/operations.go und damit, wie sie in internal/httpapi/agent_tool_catalog.go zusammengestellt werden; vergleiche diese mit dem Eingabeschema in internal/mcpserver/schema.go. Prüfe, wie bestehende Prompts die Wrapper für Query, Path und Body beschreiben. Als abgeschlossen gilt die Arbeit, wenn ein erster Aufruf mit der dokumentierten Parameterform für schreibgeschützte Tools die Validierung besteht.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Beschreibung
[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,未发现重复。
- Vorherrschende Sprache
- Go
- Sterne
- 711
- Forks
- 114
- Ø Merge
- 15 Std.
- Gemergte PRs (30 T.)
- 134
Entwicklungsumgebung
- Enthält ein Dockerfile oder eine Docker-Compose-Datei
- Hat eine Pull-Request-Vorlage
- Beitragsleitfaden lesen
Erste Schritte
- Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
- Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
- Forken Sie das Repository und arbeiten Sie in einem Branch.
- Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.
Mehr aus Tencent/LoopForge
-
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 73/100
Tencent/LoopForge#1087 · 1 Kommentar ·
Maintainer antworten meist innerhalb von 1 Tag
-
[Bug]: AI 对话诊断的 process.state 恒为 not_started,同时累加 stdoutLines,且拿不到退出码Evtl. vergeben Ein verknüpfter Pull Request ist offen oder bereits gemergt. Offen
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 72/100
Tencent/LoopForge#1086 · 1 Kommentar ·
Maintainer antworten meist innerhalb von 1 Tag
-
Schwierigkeit 1/5 Unter einer Stunde Anfängerfreundlichkeit 90/100
Tencent/LoopForge#1075 · 1 Kommentar ·
Maintainer antworten meist innerhalb von 1 Tag
-
[Bug] AI 对话切换 Claude Code 必定 400「不支持的执行器」:assistantEngineClaude 与 executorModelCatalogs 键名不一致Evtl. vergeben @jiangjiang248 hat das vor 2 Tagen übernommen. Offen
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 74/100
Tencent/LoopForge#986 · 2 Kommentare ·
Maintainer antworten meist innerhalb von 1 Tag
-
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 69/100
Tencent/LoopForge#969 · 2 Kommentare ·
Maintainer antworten meist innerhalb von 1 Tag
Alle Issues in Tencent/LoopForge
Ähnliche Issues
-
benchmark
Schwierigkeit 1/5 1-3 Stunden Anfängerfreundlichkeit 72/100
Maintainer antworten meist innerhalb von 1 Tag
-
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 77/100
mozilla-ai/cq#601 ·
Maintainer antworten meist innerhalb von 1 Tag
-
documentation migration
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 75/100
Maintainer antworten meist innerhalb von 1 Tag
-
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 84/100
Maintainer antworten meist innerhalb von 1 Tag
-
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 78/100
Maintainer antworten meist innerhalb von 1 Tag