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

Đang mở Phù hợp với người mới
#1,084 2 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
76/100
Loại issue
Lỗi
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
go
Lĩnh vực
api, backend, devtools

Hướng nghiên cứu

Bắt đầu với phần mô tả công cụ trong internal/application/operations.go và cách chúng được tập hợp trong internal/httpapi/agent_tool_catalog.go; so sánh với lược đồ đầu vào trong internal/mcpserver/schema.go. Kiểm tra cách các prompt hiện có mô tả các wrapper query, path và body. Công việc được xem là hoàn tất khi lời gọi đầu tiên dùng hình dạng tham số đã được tài liệu hóa vượt qua bước xác thực đối với các công cụ chỉ đọc.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

[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,未发现重复。
Ngôn ngữ chính
Go
Star
711
Fork
114
Merge trung bình
15 giờ
Pull request đã merge (30 ngày)
134

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của Tencent/LoopForge

Tất cả issue của Tencent/LoopForge

Issue tương tự

Thêm issue về Go

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.