docs(memory): Agent 多源架构 + 工具分层；补真实测试图纸与启动方式

- 新增 project_agent_roadmap.md（总目标/多源分层/第一步/后续路线） - 新增 feedback_tool_layering.md（工具层正交分工，反对无休止加工具） - reference_environment.md 补 e:\desktop\agent_test.dwg 与 /p SHS-ENVI2026 启动方式 - 一并提交上次会话遗留的记忆更新
2026-10-15 19:48:56 +08:00
1 parent 1c9fc72839
commit 32d552f1f0
@@ -0,0 +1,126 @@
+---
+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
+```