[功能建议] Orca 协同 MCP 工具参数校验错误信息应更可行动:附正确调用形态示例、一次报全、明确 got 值
- Dominant language
- TypeScript
- Stars
- 2.7k
- Forks
- 395
- Avg merge
- 21h 48m
- Merged PRs (30d)
- 776
Description
**提交人**: yan
**客户端版本**: 0.1.38
---
## 使用场景
使用 Orca 协同开 worker 审核任务时,需要按工具 schema 构造 `create_workers` / `create_worker` 等工具的调用参数。这些工具的 schema 要求参数直接平铺在顶层(如 `create_workers({ workers: [...] })`),与部分其它 MCP 工具(`ghost_call`、`call_tool` 等走 `args` 包裹形态)不同。
在推理较弱(如 dsv4f)或多工具混用的场景下,调用方容易对参数形态形成错误心智模型——把 `args` 包裹错误套用到 Orca 平铺工具上。
## 诉求
当工具参数校验失败时,错误信息应足够「可行动」,让调用方(尤其是模型 agent)能一次定位并修正参数形态,而不是反复试错。
当前错误信息示例(脱敏):
```
MCP error -32602: Input validation error: Invalid arguments for tool create_workers: [
{
"expected": "array",
"code": "invalid_type",
"path": ["workers"],
"message": "Invalid input"
}
]
```
实际经历:用 `{args: {workers: [...]}}` 的错误形态调用 `create_workers`,连续 7 次重试均失败(错误信息未提示正确形态),最终放弃 Orca 改用其它审核通道;事后按平铺形态一次成功。同类错误也出现在 `create_worker`(`path: ["role"]`、`["agent"]`、`["label"]` 均报 `expected string / invalid_value`)。
## 建议方案
1. **错误信息附正确调用形态示例**:校验失败时在错误末尾附一行示例,如「正确形态: `create_workers({ workers: [{ role, agent, label, ... }] })`(参数直接平铺在顶层,不要包一层 args)」。
2. **明确显示 `got` 值**:当前错误只有 `expected` 和 `message: "Invalid input"`,没有 `got` 字段;显示 `got: undefined` 或 `got: object` 能直接暴露「整个对象被当成一个字段」的问题。
3. **对顶层多余的 `args` 包裹给出针对性提示**:检测到顶层出现意外 key(如 `args`)时提示「tools on this bridge expect flat params, not {args: {...}}」。
4. **一次报全所有失败字段**:同一批参数校验失败时一次列出全部问题字段(如 role/agent/label 同时报),让调用方看到「多个必填字段都没收到值」的规律,判断是整体形态错误。
5. **附工具 schema 引用**:错误信息带上工具 schema 的引用或必填字段清单,便于快速核对。
## 影响
错误信息不可行动会放大调用方的试错成本(尤其推理较弱的模型),甚至导致放弃使用该功能;改进后能显著降低同类问题的定位时间。
---
**版本区域**: CN
**OS**: win32 x64 (10.0.26100)
**界面语言**: zh-CN
Contributor guide
Research direction
Start by locating the validation and error-reporting entry points for the create_workers and create_worker MCP tools, then reproduce the flat-parameter and {args: {...}} calls described in the issue. Done means validation errors explain the expected call shape, show relevant got values, report all failed fields, flag an unexpected args wrapper, and include the required-field or schema reference.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- backend-api-design
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100