From 32d552f1f038e63a5ef33620d9d0e551203ab335 Mon Sep 17 00:00:00 2001 From: LittleGuo Date: Thu, 15 Oct 2026 19:48:56 +0800 Subject: [PATCH] =?UTF-8?q?docs(memory):=20Agent=20=E5=A4=9A=E6=BA=90?= =?UTF-8?q?=E6=9E=B6=E6=9E=84=20+=20=E5=B7=A5=E5=85=B7=E5=88=86=E5=B1=82?= =?UTF-8?q?=EF=BC=9B=E8=A1=A5=E7=9C=9F=E5=AE=9E=E6=B5=8B=E8=AF=95=E5=9B=BE?= =?UTF-8?q?=E7=BA=B8=E4=B8=8E=E5=90=AF=E5=8A=A8=E6=96=B9=E5=BC=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 project_agent_roadmap.md（总目标/多源分层/第一步/后续路线） - 新增 feedback_tool_layering.md（工具层正交分工，反对无休止加工具） - reference_environment.md 补 e:\desktop\agent_test.dwg 与 /p SHS-ENVI2026 启动方式 - 一并提交上次会话遗留的记忆更新 --- ai.memory/MEMORY.md | 3 + ai.memory/feedback_tool_layering.md | 25 +++++ ai.memory/project_agent_roadmap.md | 63 +++++++++++++ ai.memory/project_review_agent_impl.md | 23 +++++ ai.memory/project_stdio_bridge.md | 14 ++- ai.memory/reference_environment.md | 9 ++ ai.memory/tool_request_format.md | 126 +++++++++++++++++++++++++ 7 files changed, 261 insertions(+), 2 deletions(-) create mode 100644 ai.memory/feedback_tool_layering.md create mode 100644 ai.memory/project_agent_roadmap.md create mode 100644 ai.memory/tool_request_format.md diff --git a/ai.memory/MEMORY.md b/ai.memory/MEMORY.md index 883805e..f8b0f36 100644 --- a/ai.memory/MEMORY.md +++ b/ai.memory/MEMORY.md @@ -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 层 diff --git a/ai.memory/feedback_tool_layering.md b/ai.memory/feedback_tool_layering.md new file mode 100644 index 0000000..bc4fc8f --- /dev/null +++ b/ai.memory/feedback_tool_layering.md @@ -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 最小集"思想的延续：追求**最小正交基**，而非功能全集。 diff --git a/ai.memory/project_agent_roadmap.md b/ai.memory/project_agent_roadmap.md new file mode 100644 index 0000000..d433f83 --- /dev/null +++ b/ai.memory/project_agent_roadmap.md @@ -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. **审图规范接入**：清单升级为规范库。 diff --git a/ai.memory/project_review_agent_impl.md b/ai.memory/project_review_agent_impl.md index 0036cd2..aeda3a3 100644 --- a/ai.memory/project_review_agent_impl.md +++ b/ai.memory/project_review_agent_impl.md @@ -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 删旧圆。 diff --git a/ai.memory/project_stdio_bridge.md b/ai.memory/project_stdio_bridge.md index a134ecc..fe68da6 100644 --- a/ai.memory/project_stdio_bridge.md +++ b/ai.memory/project_stdio_bridge.md @@ -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），别用它验证。 ## 为什么需要它（非显而易见） diff --git a/ai.memory/reference_environment.md b/ai.memory/reference_environment.md index 7a18f43..d2d4b8a 100644 --- a/ai.memory/reference_environment.md +++ b/ai.memory/reference_environment.md @@ -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` 端到端可跑通并出报告。 diff --git a/ai.memory/tool_request_format.md b/ai.memory/tool_request_format.md new file mode 100644 index 0000000..c6bcf99 --- /dev/null +++ b/ai.memory/tool_request_format.md @@ -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: + context: <触发场景，一句话> + + problem: | + <我在做什么、卡在哪> + evidence: | # 具体证据：handle/坐标/工具返回，便于复现 + <...> + tried: # 现有工具为什么不够 + - {tool: <名>, result: <为什么不行>} + + proposed: + name: <建议工具名，蛇形> + summary: <做什么> + inputs: # 对齐现有 inputSchema 风格 + - {name: <参数>, type: <类型>, required: , 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: + 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, 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 +```