gjm
32d552f1f0
- 新增 project_agent_roadmap.md（总目标/多源分层/第一步/后续路线） - 新增 feedback_tool_layering.md（工具层正交分工，反对无休止加工具） - reference_environment.md 补 e:\desktop\agent_test.dwg 与 /p SHS-ENVI2026 启动方式 - 一并提交上次会话遗留的记忆更新
127 lines
5.4 KiB
Markdown
127 lines
5.4 KiB
Markdown
---
|
||
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
|
||
```
|