---
name: 工具需求格式（Tool Request Format）
description: 当 cad_mcp_frame 现有工具无法完成某能力时，agent 应主动输出的结构化「工具需求」模板——字段面向"由未来的 AI 自己实现"设计，含实现线索
type: reference
---

# 工具需求格式（Tool Request Format）

> 用途：当 `cad_mcp_frame` 的现有工具**无法完成**某项能力时，agent **不要硬凑、不要用不可靠的替代**，
> 而应主动输出一条结构化「工具需求」。
> 本格式**首先是给 agent 自己读的**——因为最终实现这个工具的人也是 AI（未来的会话），
> 所以字段要**自包含**（不依赖当时的对话上下文）且**可直接据此落地实现**。

## 何时提

- 需要的数据现有工具给不出（如自定义实体只返回 bbox、读不到几何）。
- 现有工具能勉强做但**精度/可靠性不够**（如用 bbox 相贴推断连通性会漏判）。
- 某类操作要**多次调用拼凑**才能完成，明显该有专用工具。

## 输出格式（我提需求时用这个模板）

```yaml
tool_request:
  id: <小写短横线 slug，唯一>            # 例: get-entity-geometry
  title: <一句话能力>
  date: <YYYY-MM-DD>
  context: <触发场景，一句话>

  problem: |
    <我在做什么、卡在哪>
  evidence: |                            # 具体证据：handle/坐标/工具返回，便于复现
    <...>
  tried:                                 # 现有工具为什么不够
    - {tool: <名>, result: <为什么不行>}

  proposed:
    name: <建议工具名，蛇形>
    summary: <做什么>
    inputs:                              # 对齐现有 inputSchema 风格
      - {name: <参数>, type: <类型>, required: <true/false>, desc: <说明>}
    outputs:                             # 我期望拿到的字段
      - <字段: 含义>
    example_call: |
      {"name":"<工具名>","arguments":{...}}
    example_output: |
      {"items":[...]}

  acceptance:                            # "做好了"的可验证标准
    - <条件>

  implementation_hints:                  # 给未来的我：怎么落地（可省，但强烈建议填）
    backend: c++_dll
    files: [<要新增/改动的源文件>]
    register: [<要同步注册的配置>]
    conventions:
      - 返回值用 makeJsonResult() 信封 {"result":{"content":[...]}}
      - 新增 .cpp/.h 必须 UTF-8 with BOM
      - 仅写库工具需文档锁；读工具不需要
      - 完成后跑对应 verify_* 回归

  workaround: <当前临时替代及其局限>
  priority: <high|medium|low>
  status: open                           # open | implementing | done
```

## 我（未来）实现时怎么用

0. **动手实现前，先与用户讨论确认**（接口/命名/范围），得到认可再落地。用户明确要求
   （2026-10-14）："实现这个工具之前，需要和我讨论一下。"
1. 直接按 `implementation_hints` 落地：源码放 `src/cad_mcp_plugins/`，并同步注册
   `src/cad_mcp_frame/cad-mcp-frame.json` 与 `bin/Debug-R230/mcp_config.json`。
2. 字段信息不足时**先向用户补问**，不要臆测接口。
3. 完成后把 `status` 改为 `done`，并记一句验证方式（哪个 `verify_*.py` / 实测结论）。

## 示例（当前真实需求，可直接实现）

```yaml
tool_request:
  id: get-entity-geometry
  title: 读取自定义实体（AECDBEWPIPE/FITTING/EQUIPMENT）的实际连接点/起止点坐标
  date: 2026-10-14
  context: 审查图纸时需判断管线连通性

  problem: |
    判断每个图框内管线是否连续时，只能拿到实体外包框，无法判断真实几何是否相接。
  evidence: |
    get_entity_detail("3A4") 返回 properties 为空；query_entities 只给 bbox。
    两条共线管段若 bbox 相贴但实际有缺口，会被误判为连通。
  tried:
    - {tool: get_entity_detail, result: 对 AECDBEWPIPE 返回空 properties}
    - {tool: query_entities, result: 只有 bbox，bbox 相贴≠几何相连，会漏判断口}

  proposed:
    name: get_entity_geometry
    summary: 返回实体的实际几何（直线段起止点 / 连接点数组 / 中心线走向）
    inputs:
      - {name: handles, type: array<string>, required: true,  desc: 实体句柄列表}
      - {name: window,  type: object,        required: false, desc: 范围过滤}
      - {name: space,   type: string,        required: false, desc: "Model 或布局名，默认 Model"}
    outputs:
      - "handle: 实体句柄"
      - "type: 实体类型"
      - "start/end: 起止点 [x,y]（直线段）"
      - "points: 连接点数组（多段/异形）"
    example_call: |
      {"name":"get_entity_geometry","arguments":{"handles":["3A4"]}}
    example_output: |
      {"items":[{"handle":"3A4","type":"AECDBEWPIPE","start":[25937.6,45779.3],"end":[29946.5,45779.3]}]}

  acceptance:
    - 对 AECDBEWPIPE/FITTING/EQUIPMENT 均能返回非空几何
    - 用其起止点可精确判定相邻实体是否真正相接（不再依赖 bbox）

  implementation_hints:
    backend: c++_dll
    files: [src/cad_mcp_plugins/dwg_review_query.cpp]
    register: [src/cad_mcp_frame/cad-mcp-frame.json, bin/Debug-R230/mcp_config.json]
    conventions:
      - 返回值用 makeJsonResult() 信封
      - 源文件 UTF-8 with BOM
      - 读工具无需文档锁

  workaround: 用 query_entities 的 bbox 做相邻推断，精度不足、会漏判断口
  priority: high
  status: open
```