docs(memory): Agent 多源架构 + 工具分层；补真实测试图纸与启动方式
- 新增 project_agent_roadmap.md（总目标/多源分层/第一步/后续路线） - 新增 feedback_tool_layering.md（工具层正交分工，反对无休止加工具） - reference_environment.md 补 e:\desktop\agent_test.dwg 与 /p SHS-ENVI2026 启动方式 - 一并提交上次会话遗留的记忆更新
This commit is contained in:
gjm committed
1 parent
1c9fc72839
commit
32d552f1f0
7 files changed
+261
-2
No files matched your search
@@ -11,3 +11,6 @@
|
||||
- [MCP 基座 c++_dll 加载与执行的坑](project_mcp_frame_dll_loader.md) — acrxGetApiVersion 有状态不可比对、写库需文档锁、同一 DLL 只加载一次
|
||||
- [用户协作偏好](feedback_preferences.md) — 调试用 Debug/R230、模型 deepseek-flash、DLL 集中在 cad_mcp_plugins 等
|
||||
- [环境与外部资源](reference_environment.md) — 构建/运行要点、CAD SDK 路径、测试脚本
|
||||
- [工具需求格式](tool_request_format.md) — 现有工具不够用时的结构化「工具需求」模板（面向 AI 自己实现）
|
||||
- [Agent 路线与多源架构](project_agent_roadmap.md) — 总目标（多格式图纸）、视觉为最大公约数、第一步多源证据层+多图、后续路线
|
||||
- [工具层与 agent 层的正交分工](feedback_tool_layering.md) — 反对无休止加工具；工具层正交稳定，业务规则进 agent 层
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
name: 工具层与 agent 层的正交分工
|
||||
description: 用户反对"无休止加工具"堆业务能力；工具层应正交稳定，业务规则进 agent 层
|
||||
type: feedback
|
||||
---
|
||||
|
||||
# 工具层与 agent 层的正交分工
|
||||
|
||||
**规则**：不要靠"无休止加工具"堆业务能力。判断一个需求该加工具、还是该在 agent 层做：
|
||||
|
||||
> 能由已有工具的**原始事实**组合出来的结论 → **agent 层（Python）**做；
|
||||
> 只能由 **CAD 侧**提供的原始事实/动作 → 才加工具，且必须**通用正交**。
|
||||
|
||||
**Why**：用户（2026-10-15）明确指出"需要的工具是动态的、不确定的，根据具体业务出现，
|
||||
无休止添加工具肯定不对"。工具层应**稳定正交**，业务层**高频可变**——业务变了只改 agent
|
||||
侧清单/规则，不碰工具、不重编 DLL。
|
||||
|
||||
**How to apply**：
|
||||
|
||||
- 业务规则（如"法兰数 == 2×阀门数"、管线连通性）→ 写进 agent 层 `checks.py`，
|
||||
**绝不做成工具**。
|
||||
- 通用感官（如读任意实体几何 `get_entity_geometry`）→ 该补，且要设计成对**任何图纸**通用，
|
||||
不为某个业务/格式定制（属"正交感官"，是 agent 迭代的前提）。
|
||||
- 只有 **CAD 进程内**才能提供的能力才考虑加 MCP 工具；PDF/图片等应在 agent 侧处理。
|
||||
- 这是"B 最小集"思想的延续：追求**最小正交基**，而非功能全集。
|
||||
@@ -0,0 +1,63 @@
|
||||
---
|
||||
name: Agent 路线与多源架构（2026-10-15）
|
||||
description: dwg_review agent 的总目标、多源图纸分层架构（视觉为最大公约数）、工具层与 agent 层的正交分工、第一步多源证据层与后续路线
|
||||
type: project
|
||||
---
|
||||
|
||||
# Agent 路线与多源架构
|
||||
|
||||
## 总目标（用户 2026-10-15 明确）
|
||||
|
||||
实现 **AI 自动识别 + 评审 DWG 图纸**。分阶段：**先 MCP（已完成），再 agent（进行中）**。
|
||||
最终要支持的图纸来源**不限于自家自定义实体**：
|
||||
|
||||
1. 自家软件的自定义实体 DWG；
|
||||
2. **其他软件出的 DWG**（各种自定义实体）；
|
||||
3. 将来 **PDF** 图纸；
|
||||
4. 将来**纯图片**图纸。
|
||||
|
||||
## 架构分层（用户认可）
|
||||
|
||||
**核心洞察：视觉模型（VLM）是"最大公约数"**。DWG 自定义实体 / PDF / 图片本质是
|
||||
"拿不到结构化数据时靠视觉理解"的同一件事——**任何图纸只要能渲染成图，VLM 就能审**。
|
||||
所以结构化数据（ARX 读普通实体）是**增强**，视觉是**兜底**。
|
||||
|
||||
```
|
||||
Agent 推理层（审查逻辑 / 清单 / 规则）
|
||||
▲ 统一 evidence schema
|
||||
感知适配层（能力从高到低降级）
|
||||
CAD结构化(ARX) → CAD几何 → 离线解析(DWG/PDF) → 视觉(VLM)
|
||||
```
|
||||
|
||||
- **MCP 工具层只管 CAD**（进程内能力）；**PDF / 图片在 agent 侧**（PyMuPDF / Pillow），
|
||||
**不塞进 MCP**、不编 DLL。
|
||||
- **统一证据模型 + 多源适配 + 能力降级**；agent 推理层不关心来源格式。
|
||||
|
||||
**How to apply**：新增"支持某格式"时，优先在 agent 侧感知层加适配器；只有"CAD 进程内的
|
||||
正交感知能力"才考虑加 MCP 工具。
|
||||
|
||||
## 第一步已落地（2026-10-15，提交 `1c9fc72`）
|
||||
|
||||
**取证层多源化 + 视觉多图**：
|
||||
|
||||
- 新增 `dwg_review/evidence_model.py`：统一证据模型（`source_type` +
|
||||
`images:[{b64,mime,label}]`），访问器 `evidence_images()` 兼容旧 `image_b64/image_mime`
|
||||
单图字段（历史 evidence.json 仍可读）。
|
||||
- `phases/evidence.py`：`collect()` 多源分发 seam（当前仅 CAD）、`capture_images()`
|
||||
整体 + 等分象限多图（结束**复位视口**）、`sub_windows()`。
|
||||
- 默认 `EVIDENCE_DETAIL_TILES=4` / `EVIDENCE_MAX_IMAGES=5`（每图框 5 图，**默认开启**）。
|
||||
- 实测：真实 Plant 3D 图纸上多图让审查更细（多报出线型误用 `CENTER2`、图签块属性为空、
|
||||
按 handle 定位的图层混用等）。
|
||||
|
||||
## 后续路线（未做）
|
||||
|
||||
1. **VLM 主动放大（自适应取证）**：复用受控只读取证子循环，让 VLM 请求放大看不清处。
|
||||
- 两条路径：① 按实体 `zoom_to_entity(handle)`（可靠）；② 按区域（需把 VLM 归一化坐标
|
||||
映射成 WCS，依赖 grounding，**需先实测 `deepseek-flash` 的 grounding**）。
|
||||
- 必须设**迭代上限 + 兜底**；**不把"看清没"完全交给 VLM**（会过度自信/幻觉）。
|
||||
- 现有 `zoom_to_window`/`zoom_to_entity`/`get_viewport_screenshot` 已在只读白名单，
|
||||
**无需新增工具**。
|
||||
2. **PDF / 图片源**：在 `phases/evidence.collect()` 加分支，产出**同形** evidence
|
||||
（`window=None`、结构化空信封、`images` 带 label）；规划阶段抽象"审查单元"
|
||||
（CAD=图框 / PDF=页 / 图片=单）；批注对非 CAD 源降级（`annotator` 已天然跳过无 handle 的 issue）。
|
||||
3. **审图规范接入**：清单升级为规范库。
|
||||
@@ -139,3 +139,26 @@ DLL 代理写锁改为 `ScopedDocumentWriteLock` RAII）。**插件作者无需
|
||||
`-32602/-32600/-32700`；工具内部类型异常被兜为 `result.isError=true`；反复注入 10 次后
|
||||
CAD 存活、写锁未泄漏）。回归 `verify_mcp_frame` 4/4、`verify_stdio_bridge` 24/24、
|
||||
`verify_annotate` 9/9、`dwg_review --check` 均正常。
|
||||
|
||||
## Plant 3D 图纸实体语义与圈注（2026-10-14 实机确认）
|
||||
|
||||
**这是 Plant 3D / AEC 自定义实体图，插件无法内省**——`get_entity_detail` 对它们返回
|
||||
**空 `properties`**，`query_entities` 也只给 `bbox`/`layer`/`type`。类型语义：
|
||||
|
||||
- `AECDBEWPIPE` = 管道（一根管子一个实体）。
|
||||
- `AECDBEWFITTING` = 管件，**两种形态靠 bbox 长宽比区分**：
|
||||
- 近正方（aspect = min/max ≥ 0.5，约 250×250）= **弯头**；
|
||||
- 细长条（aspect < 0.5，约 20×220）= **法兰**。
|
||||
- `AECDBEWEQUIPMENT` = 设备，本图中即**阀门**（蝶阀符号）。
|
||||
|
||||
**不变量（交叉校验用）**：法兰数 == 2 × 阀门数（阀门两侧各一法兰）。
|
||||
|
||||
**How to apply（识别/统计这类图）**：不要依赖属性，改用「`query_entities(type_filter=...)`
|
||||
取 bbox + 几何分类 + 不变量交叉校验 + `get_viewport_screenshot` 视觉复核」。图框用
|
||||
`detect_drawing_frames`（本图返回 3 个块图框 A0/A1/A2，`kind=block`）；把实体按「中心点落在
|
||||
哪个图框 bbox 内」归类到框。
|
||||
|
||||
**圈注配方（已验证）**：`draw_revision_cloud {shape:"circle", center:[cx,cy],
|
||||
radius:max_side*1.1, layer:"AI_REVIEW", color:3}`——center 取阀门 bbox 中心，半径取包围盒
|
||||
**长边 × 1.1**（本图阀门 bbox ≈230×220 → r≈253），绿色云线正好套住蝶阀符号。逐框
|
||||
`zoom_to_window(frame_bbox)` + 截图可验证。画前若要重来，`delete_entities` 按 handle 删旧圆。
|
||||
@@ -6,8 +6,18 @@ type: project
|
||||
|
||||
# stdio ↔ TCP 桥（`mcp_bridge/`）
|
||||
|
||||
**状态：已实现并验证通过**（2026-10-14）。这是「MCP 标准化」路线的第二步
|
||||
（第一步是基座 B 最小集，见 `project_review_agent_impl.md`）。
|
||||
**状态：已实现并验证通过**（2026-10-14），且**已注册进 CodeBuddy**（2026-10-14）。
|
||||
这是「MCP 标准化」路线的第二步（第一步是基座 B 最小集，见 `project_review_agent_impl.md`）。
|
||||
|
||||
## 已接入 CodeBuddy（用户级）
|
||||
|
||||
配置写在 `C:\Users\gjm\.codebuddy\.mcp.json`（user 作用域、推荐路径、免首连审批、
|
||||
不污染仓库）——服务名 `cad-autocad`，`type: stdio`，`command` = 本机 Python314，
|
||||
`args: ["-m","mcp_bridge"]`，`env` 带 `PYTHONPATH=D:\new-start\CadProject` +
|
||||
`CAD_MCP_HOST/PORT`。**改配置后需重启 CodeBuddy 才生效**；工具以 `mcp__cad-autocad__<工具名>`
|
||||
形式出现（26 个）。注意：同目录另有一个**空的**旧文件 `~/.codebuddy/mcp.json`（deprecated），
|
||||
按优先级被 `.mcp.json` 遮蔽、无害。**前提：CAD 必须在跑（8080 监听）**，否则工具调用报错。
|
||||
`codebuddy mcp list` 这个 CLI 子命令在本版本会去拉起主程序（撞端口 55187），别用它验证。
|
||||
|
||||
## 为什么需要它（非显而易见）
|
||||
|
||||
|
||||
@@ -75,3 +75,12 @@ type: reference
|
||||
旧密钥 `~/.ssh/id_ed25519`（`deploy@aly-db`）已被服务器移除，会 `Permission denied (publickey)`。
|
||||
本仓库已设置 `git config core.sshCommand "ssh -i ~/.ssh/id_ed25519_guojianming -o IdentitiesOnly=yes"`。
|
||||
换机器时需补该配置或加入 `~/.ssh/config`。
|
||||
|
||||
## 真实测试图纸（2026-10-15）
|
||||
|
||||
- 图纸：`e:\desktop\agent_test.dwg`（用户制作的真实 Plant 3D 图纸：3 个图框 A0/A1/A2，
|
||||
86 个实体：`AECDBEWFITTING` 40 / `AECDBEWPIPE` 29 / `AECDBEWEQUIPMENT` 14 / `INSERT` 3）。
|
||||
- **启动方式**：`acad.exe /p SHS-ENVI2026 e:\desktop\agent_test.dwg`
|
||||
—— 必须带 `/p SHS-ENVI2026` profile，否则**自定义实体无法显示**（该 profile 自动加载
|
||||
用户写的显示插件）。
|
||||
- 实测：`python -m dwg_review --frames 1` 端到端可跑通并出报告。
|
||||
@@ -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
|
||||
```
|
||||
Reference in new issue
Block a user