[Bug]: 只读平台工具的描述写 "Query: projectId",但 schema 要求包进 query 对象,首次调用必然失败
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
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" }
原因链(代码定位)
-
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,未发现重复。
- 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
- Có Dockerfile hoặc tệp Docker Compose
- Có mẫu pull request
- Đọc hướng dẫn đóng góp
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- 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.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của Tencent/LoopForge
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 73/100
Tencent/LoopForge#1087 · 1 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 72/100
Tencent/LoopForge#1086 · 1 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 90/100
Tencent/LoopForge#1075 · 1 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
-
[Bug] AI 对话切换 Claude Code 必定 400「不支持的执行器」:assistantEngineClaude 与 executorModelCatalogs 键名不一致Có thể đã có người làm @jiangjiang248 đã nhận 2 ngày trước. Đang mở
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 74/100
Tencent/LoopForge#986 · 2 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 69/100
Tencent/LoopForge#969 · 2 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
Tất cả issue của Tencent/LoopForge
Issue tương tự
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
Maintainer thường phản hồi trong vòng 1 ngày
-
Inconsistency between golang and cue in specCó thể đã có người làm Có pull request liên kết đang mở hoặc đã được merge. Đang mở
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 88/100
Maintainer thường phản hồi trong vòng 1 ngày
-
security
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 68/100
-
Area/DeveloperPortal Aspect/UI Severity/Minor Type/Bug
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 88/100
wso2/api-platform#4369 ·
Maintainer thường phản hồi trong vòng 1 ngày