[Bug]: 只读平台工具的描述写 "Query: projectId",但 schema 要求包进 query 对象,首次调用必然失败
メンテナーはふだん 1 日以内に返信
まだ誰も着手していません。
評価
- 難易度
- 2/5
- 見積もり時間
- 1〜3時間
- 初心者へのやさしさ
- 76/100
調査の方向性
internal/application/operations.go のツールの説明から始め、それらが internal/httpapi/agent_tool_catalog.go でどのように組み立てられるかを確認し、internal/mcpserver/schema.go の入力スキーマと比較します。既存のプロンプトが query、path、body のラッパーをどのように説明しているか確認します。読み取り専用ツールについて、ドキュメントに記載されたパラメーター形式を使った最初の呼び出しが検証を通れば完了です。
索引モデルが issue の本文から書いたものです。
説明
[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,未发现重复。
- 主要言語
- Go
- スター
- 711
- フォーク
- 114
- 平均マージ
- 15時間
- マージ済み PR(30日)
- 134
環境構築
- Dockerfile または Docker Compose ファイルあり
- プルリクエストのテンプレートあり
- コントリビューションガイドを読む
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
Tencent/LoopForge のほかの issue
-
難易度 2/5 1〜3時間 初心者へのやさしさ 73/100
Tencent/LoopForge#1087 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 72/100
Tencent/LoopForge#1086 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信
-
難易度 1/5 1時間未満 初心者へのやさしさ 90/100
Tencent/LoopForge#1075 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信
-
[Bug] AI 对话切换 Claude Code 必定 400「不支持的执行器」:assistantEngineClaude 与 executorModelCatalogs 键名不一致対応中かも @jiangjiang248 が 2 日前に担当しました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 74/100
Tencent/LoopForge#986 · コメント 2 件 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 69/100
Tencent/LoopForge#969 · コメント 2 件 ·
メンテナーはふだん 1 日以内に返信
Tencent/LoopForge の issue をすべて見る
似ている issue
-
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
-
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
メンテナーはふだん 1 日以内に返信
-
Inconsistency between golang and cue in spec対応中かも このイシューにリンクされたプルリクエストがオープン中、またはマージ済みです。 オープン
難易度 1/5 1時間未満 初心者へのやさしさ 88/100
メンテナーはふだん 1 日以内に返信
-
security
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
-
Area/DeveloperPortal Aspect/UI Severity/Minor Type/Bug
難易度 1/5 1時間未満 初心者へのやさしさ 88/100
wso2/api-platform#4369 ·
メンテナーはふだん 1 日以内に返信