[Bug]: 只读平台工具的描述写 "Query: projectId",但 schema 要求包进 query 对象,首次调用必然失败

オープン 初心者向け
#1,084 コメント 2 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
2/5
見積もり時間
1〜3時間
初心者へのやさしさ
76/100
issue の種類
バグ
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
go
領域
api, backend, devtools

調査の方向性

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" }

原因链(代码定位)

  1. 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 里。

  2. internal/httpapi/agent_tool_catalog.go:361-376 把描述拼成
    op.Description + " (" + op.Method + " " + op.Path + ")" 直接交给模型,
    没有附加任何"参数需包在 query 对象内"的说明。

  3. internal/mcpserver/schema.go:48-90 生成的 inputSchema 顶层是
    {"type": "object", "additionalProperties": false},属性只有 path / query / body。
    因此顶层出现 projectId 一定被判 unknown field。

  4. 全仓库检索 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 里",只能靠试错。

期望行为

任选其一即可显著改善:

  1. 在只读工具描述里直接写出包装形状,例如
    query: {projectId?: string, q?: string},或在描述末尾统一加一句
    "所有参数放入 query 对象,不要把参数放在顶层"。
  2. 在 platformToolInputSchema 生成描述时,把 query / path / body 的可用字段展平进描述。
  3. 校验失败时返回可执行的纠正建议(例如
    unknown field "projectId"; put it under "query"),而不是只回 unknown field。

Reproduction

  1. 部署平台 v0.4.0,在 AI 对话中配置一个可用的自定义运行时与模型。
  2. 在对话里问"当前项目有哪些 SOP"。
  3. 观察模型第一次调用 agentflow__workflows_list 时带 {"projectId": "..."} 并报
    projectId: unknown field。
  4. 模型改为 {"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

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

Tencent/LoopForge のほかの issue

Tencent/LoopForge の issue をすべて見る

似ている issue

Go の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。