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

Ouverte Adaptée aux débutants
#1,084 2 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

@wcy12378 y travaille déjà.

Depuis le 19/11/2026.

  • #1095 par @wcy12378 — ouverte

Évaluation

Difficulté
2/5
Temps estimé
1-3 heures
Accessibilité débutants
76/100
Type d'issue
Bug
Clarté
Clairement spécifiée
Activité
Active
Stack technique
go
Domaine
api, backend, devtools

Piste de recherche

Commence par les descriptions des outils dans internal/application/operations.go et par la façon dont ils sont assemblés dans internal/httpapi/agent_tool_catalog.go ; compare-les au schéma d’entrée dans internal/mcpserver/schema.go. Vérifie comment les prompts existants décrivent les wrappers query, path et body. Le travail est terminé lorsqu’un premier appel utilisant la forme de paramètres documentée passe la validation pour les outils en lecture seule.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

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

原因链(代码定位)

  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,未发现重复。
Langage dominant
Go
Étoiles
711
Forks
114
Merge moyen
15 h
PR mergées (30 j)
134

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de Tencent/LoopForge

Toutes les issues de Tencent/LoopForge

Issues similaires

Plus d'issues Go

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.