@atlisp/mcp 1.8.10 → 1.8.12

package/README.md

@@ -1,22 +1,67 @@
 # @lisp MCP Server
 
-MCP (Model Context Protocol) Server for @lisp on CAD - 为 CAD 环境提供 @lisp 包管理服务的 MCP 服务器，同时为 AI AGENT 操控 CAD 提供调用工具和通道。
+MCP (Model Context Protocol) Server for @lisp on CAD — 为 CAD 环境提供 @lisp 包管理服务的 MCP 服务器，同时为 AI Agent 操控 CAD 提供 **220+ 个调用工具**和通道。
+
+支持 **AutoCAD / ZWCAD / GStarCAD / BricsCAD**，通过 COM 互操作与 CAD 通信。
+
+---
+
+## 目录
+
+- [功能特性](#功能特性)
+- [快速安装](#快速安装)
+- [配置 AI Agent](#配置-ai-agent)
+- [启动服务](#启动服务)
+- [连接 CAD](#连接-cad)
+- [工具列表](#工具列表)
+- [MCP 资源](#mcp-资源)
+- [MCP Prompts](#mcp-prompts)
+- [HTTP API 端点](#http-api-端点)
+- [环境变量](#环境变量)
+- [命令行参数](#命令行参数)
+- [配置文件](#配置文件)
+- [工作原理](#工作原理)
+- [Docker](#docker)
+- [开发指南](#开发指南)
+- [故障排除](#故障排除)
+- [许可证](#许可证)
+
+---
 
 ## 功能特性
 
-- 连接 AutoCAD/ZWCAD/GStarCAD/BricsCAD
-- 执行 AutoLISP 代码，支持绘图、查询、标注
-- AI Agent 可通过 MCP 协议控制 CAD 绘图
-- 管理 @lisp 包（列出、搜索、安装）
-- CAD 未运行自动启动
-- 实体/图层/块 CRUD 操作
-- DWG 文件操作（打开/保存/导出）
-- MCP 资源订阅推送
-- MCP 根目录支持
+- **连接多平台 CAD** — AutoCAD / ZWCAD / GStarCAD / BricsCAD
+- **执行 AutoLISP** — 执行 LISP 代码并获取结果
+- **AI Agent 控制 CAD** — 220+ MCP 工具，涵盖绘图、编辑、查询、管理
+- **包管理** — 列出、搜索、安装 @lisp 包
+- **批量操作** — 批量复制/移动/旋转/缩放/镜像/偏移/改名/改色/改图层
+- **3D 建模** — 创建 Box/Sphere/Cylinder/Cone/Torus/Wedge，布尔运算，拉伸/旋转
+- **图纸集管理** — 创建/发布/归档/比较/打包图纸集
+- **动态块** — 获取/设置参数、可见性状态
+- **几何约束与标注约束** — 添加/删除/列出约束
+- **外部参照** — 附着/拆离/绑定/裁剪/路径管理/批量相对化
+- **PDF/DGN/DWF 底图** — 附着/拆离/重载/批量附着
+- **扩展数据 (Xdata)** — 读写/复制/搜索/导入/导出
+- **管道 (Pipeline)** — 编排多步工具调用链
+- **触发器 (Watch)** — 注册 CAD 变更触发器，等待条件满足
+- **Webhook** — 事件驱动回调（工具执行/包安装/CAD 连接等）
+- **REPL** — 交互式 Lisp 执行会话
+- **流式读取** — 分页流式读取实体/文字/块参照
+- **外部数据** — 查询/导入/导出 CSV/JSON 数据源
+- **审计日志** — 查询和统计工具调用历史
+- **CAD 连接池** — 发现/切换/健康检查多 CAD 实例
+- **沙箱** — 验证 LISP 代码安全性
+- **资源订阅** — 实时推送 CAD/DWG/包变更
+- **LLM Sampling** — 通过配置的 LLM 提供采样能力
+- **Prometheus 指标** — 导出 /metrics 端点
+- **SSL/TLS** — 支持 HTTPS 加密通信
+- **API Key 认证与速率限制**
+- **配置热重载** — 配置文件变更自动加载
+- **多种传输模式** — HTTP / SSE / stdio / WebSocket
 
 ---
 
-## 一、安装
+## 快速安装
 
 ### Windows (PowerShell)
 
@@ -25,21 +70,27 @@ iwr -useb https://atlisp.cn/install.ps1 | iex
 ```
 
 安装脚本会自动：
-- 安装 Node.js（如未安装）
+- 安装 Node.js（如未安装，支持 winget/choco/scoop/MSI）
 - 全局安装 `@atlisp/mcp` 包
-- 创建命令 `atlisp-mcp`
+- 注册命令 `atlisp-mcp`
+
+### 手动安装 (npm)
+
+```bash
+npm install -g @atlisp/mcp
+```
 
 ### 验证安装
 
-```powershell
+```bash
 atlisp-mcp --version
 ```
 
 ---
 
-## 二、配置 AI Agent (WorkBuddy / Claude Desktop)
+## 配置 AI Agent
 
-### WorkBuddy 配置
+### WorkBuddy
 
 在 `~/.workbuddy/.mcp.json` 中添加:
 
@@ -53,7 +104,7 @@ atlisp-mcp --version
 }
 ```
 
-### Claude Desktop 配置
+### Claude Desktop
 
 在 `~/AppData/Roaming/Claude/claude_desktop_config.json` 中添加:
 
@@ -70,7 +121,7 @@ atlisp-mcp --version
 }
 ```
 
-### 其他 AI Agent (Cline / Cursor / Windsurf)
+### Cline / Cursor / Windsurf
 
 ```json
 {
@@ -86,9 +137,24 @@ atlisp-mcp --version
 }
 ```
 
+### opencode / Goose / 其他支持 stdio 的 Agent
+
+```json
+{
+  "mcpServers": {
+    "atlisp-mcp": {
+      "command": "atlisp-mcp",
+      "env": {
+        "TRANSPORT": "stdio"
+      }
+    }
+  }
+}
+```
+
 ---
 
-## 三、启动服务
+## 启动服务
 
 ### HTTP 模式（默认，端口 8110）
 
@@ -96,17 +162,29 @@ atlisp-mcp --version
 atlisp-mcp
 ```
 
-服务启动后输出:
+输出:
 ```
 @lisp MCP Server 启动 - http://0.0.0.0:8110 - Streamable HTTP
 ```
 
-### stdio 模式（AI Agent 直接调用）
+### stdio 模式
 
 ```bash
-atlisp-mcp
-# 环境变量
-TRANSPORT=stdio
+TRANSPORT=stdio atlisp-mcp
+```
+
+### WebSocket 模式
+
+```bash
+TRANSPORT=ws atlisp-mcp
+# 或
+atlisp-mcp --ws
+```
+
+### 指定端口/主机
+
+```bash
+atlisp-mcp --port 9000 --host 127.0.0.1
 ```
 
 ### 健康检查
@@ -117,28 +195,31 @@ curl http://localhost:8110/health
 
 返回 `{"status":"ok","cad":"connected"}` 表示服务正常。
 
-### HTTP 端点
+### 查看指标
 
-| 端点 | 方法 | 说明 |
-|------|------|------|
-| `/health` | GET | 健康检查 |
-| `/sse` | GET | SSE 长连接端点（需 ENABLE_SSE=true） |
-| `/mcp/sse` | GET/POST | SSE MCP 端点（需 ENABLE_SSE=true） |
-| `/mcp` | POST | MCP JSON-RPC 端点（主要接口） |
+```bash
+curl http://localhost:8110/metrics
+```
+
+### 调试面板
+
+打开浏览器访问 `http://localhost:8110/debug`
+
+### 工具游乐场
+
+打开浏览器访问 `http://localhost:8110/playground`
 
 ---
 
-## 四、连接 CAD
+## 连接 CAD
 
 ### 前置条件
 
 - Windows 系统
-- CAD 软件已安装（AutoCAD / ZWCAD / GStarCAD / BricsCAD）
-- CAD 已启动（或配置为自动启动）
-
-### 连接方式
+- CAD 软件已安装
+- CAD 已启动或允许自动启动
 
-使用 MCP 工具 `connect_cad` 连接 CAD：
+### 使用 MCP 工具连接
 
 ```json
 {
@@ -147,349 +228,604 @@ curl http://localhost:8110/health
 }
 ```
 
+或指定平台:
+
+```json
+{
+  "name": "connect_cad",
+  "arguments": {
+    "platform": "AutoCAD"
+  }
+}
+```
+
 **自动行为**:
 - 如果 CAD 已运行，连接现有实例
 - 如果 CAD 未运行，通过 COM 自动创建新实例
 
-连接成功返回: `已连接到 AutoCAD 2021`
+连接成功返回类似: `已连接到 AutoCAD 2025`
 
 ---
 
-## 五、绘图示例
+## 工具列表 (220+)
 
-### 1. 画直线
+### 系统与 CAD 连接 (11)
 
-```json
-{
-  "name": "eval_lisp",
-  "arguments": {
-    "code": "(command \"_.LINE\" \"0,0\" \"100,100\" \"\")"
-  }
-}
-```
+| 工具 | 说明 | 参数 |
+|------|------|------|
+| `connect_cad` | 连接 CAD | `platform` (可选) |
+| `eval_lisp` | 执行 LISP 代码（无返回值） | `code` (必填) |
+| `eval_lisp_with_result` | 执行 LISP 并返回结果 | `code` (必填), `encoding` (可选) |
+| `get_cad_info` | 获取 CAD 信息 | — |
+| `get_platform_info` | 获取平台信息 | — |
+| `at_command` | 执行 @lisp 命令 | `command` (必填) |
+| `new_document` | 新建空白文档 | — |
+| `bring_to_front` | 切换 CAD 到前台 | — |
+| `install_atlisp` | 安装 @lisp | — |
+| `init_atlisp` | 初始化 @lisp 环境 | — |
+| `get_system_status` | 获取系统诊断信息 | — |
 
-### 2. 画矩形
+### LISP 执行
 
-```json
-{
-  "name": "eval_lisp",
-  "arguments": {
-    "code": "(command \"_.RECTANG\" \"0,0\" \"100,100\")"
-  }
-}
-```
+| 工具 | 说明 |
+|------|------|
+| `eval_lisp` | 执行 LISP 代码，不返回结果 |
+| `eval_lisp_with_result` | 执行 LISP 代码并返回结果，支持 `encoding: utf-8/gbk/gb2312/gb18030` |
+| `lisp_repl` | REPL 会话执行，自动追踪变量和历史 |
+| `lisp_repl_history` | 获取 REPL 会话历史 |
+| `lisp_repl_list` | 列出活跃 REPL 会话 |
+| `lisp_repl_close` | 关闭 REPL 会话 |
 
-### 3. 画圆
+### 包管理 (3)
 
-```json
-{
-  "name": "eval_lisp",
-  "arguments": {
-    "code": "(command \"_.CIRCLE\" \"50,50\" \"25\")"
-  }
-}
-```
+| 工具 | 说明 | 参数 |
+|------|------|------|
+| `list_packages` | 列出已安装包 | — |
+| `search_packages` | 搜索包 | `query` (必填) |
+| `install_package` | 安装包到 CAD | `packageName` (必填) |
 
-### 4. 写文字
+### 信息与函数 (5)
 
-```json
-{
-  "name": "eval_lisp",
-  "arguments": {
-    "code": "(entmake (list (cons 0 \"TEXT\") (cons 10 (list 0 0 0)) (cons 40 5) (cons 1 \"标题\")))"
-  }
-}
-```
+| 工具 | 说明 |
+|------|------|
+| `get_function_usage` | 获取 @lisp 函数用法 |
+| `list_symbols` | 列出所有符号（函数/变量） |
+| `import_funlib` | 导入函数库数据到 AI Agent |
+| `list_prompts` | 列出提示模板 |
+| `get_prompt` | 获取指定提示模板 |
 
-### 5. 获取查询结果
+### 实体操作 (4)
 
-```json
-{
-  "name": "eval_lisp_with_result",
-  "arguments": {
-    "code": "(getvar \"acadver\")"
-  }
-}
-```
+| 工具 | 说明 |
+|------|------|
+| `get_entity` | 获取实体属性（句柄/类型/图层/颜色等） |
+| `set_entity` | 设置实体属性（layer/color/linetype/elevation） |
+| `delete_entity` | 删除实体 |
+| `select_entities` | 按条件选择实体（type/layer 过滤） |
+| `get_entity_info` | 获取实体详细信息 |
 
-返回 CAD 版本号，如 "AC1027"
+### 图层操作 (4)
 
-### 6. 统计图形数量
+| 工具 | 说明 |
+|------|------|
+| `create_layer` | 创建图层 |
+| `delete_layer` | 删除图层 |
+| `set_layer` | 设置图层属性（color/linetype/freeze/thaw/lock/unlock） |
+| `set_current_layer` | 设置当前图层 |
 
-```json
-{
-  "name": "eval_lisp_with_result",
-  "arguments": {
-    "code": "(sslength (ssget \"_X\"))"
-  }
-}
-```
+### 块操作 (6)
 
-### 7. 切换 CAD 到前台
+| 工具 | 说明 |
+|------|------|
+| `create_block` | 创建块定义 |
+| `insert_block` | 插入块参照 |
+| `get_blocks` | 获取所有块定义 |
+| `explode_block` | 炸开块参照 |
+| `batch_get_block_attributes` | 批量获取块属性 |
+| `batch_set_block_attributes` | 批量设置块属性 |
 
-当 CAD 在后台运行时，唤醒到前台:
+### 动态块与参数化 (6)
 
-```json
-{
-  "name": "bring_to_front",
-  "arguments": {}
-}
-```
+| 工具 | 说明 |
+|------|------|
+| `get_dynamic_block_properties` | 获取动态块所有属性 |
+| `set_dynamic_block_property` | 设置动态块属性值 |
+| `get_block_parameters` | 获取块参数值 |
+| `set_block_parameter` | 设置块参数值 |
+| `list_visibility_states` | 列出可见性状态 |
+| `set_visibility_state` | 切换可见性状态 |
 
----
+### 文件/DWG 操作 (5)
 
-## 六、可用工具列表 (35 个)
+| 工具 | 说明 |
+|------|------|
+| `open_dwg` | 打开 DWG 文件 |
+| `save_dwg` | 保存图形 |
+| `export_pdf` | 导出 PDF |
+| `export_dxf` | 导出 DXF |
+| `export_dwf` | 导出 DWF |
+| `close_dwg` | 关闭图形 |
+| `import_dxf` | 导入 DXF 文件 |
+| `import_dgn` | 导入 DGN 文件 |
+| `export_dgn` | 导出 DGN 文件 |
+
+### 标注与填充 (7)
+
+| 工具 | 说明 |
+|------|------|
+| `create_dimension` | 创建标注（ALIGNED/LINEAR/ORDINATE/RADIAL/DIAMETER/ANGULAR） |
+| `get_dimension` | 获取标注值 |
+| `create_hatch` | 创建图案填充 |
+| `set_hatch` | 设置填充属性 |
+| `get_block_attributes` | 获取块属性值 |
+| `set_block_attribute` | 设置块属性值 |
+| `dimension_style` | 创建和管理标注样式 |
+
+### 样式管理 (11)
 
-### CAD 连接
+| 工具 | 说明 |
+|------|------|
+| `create_dimension_style` | 创建标注样式 |
+| `set_dimstyle_var` | 设置标注样式变量 |
+| `list_dimension_styles` | 列出所有标注样式 |
+| `create_text_style` | 创建文字样式 |
+| `list_text_styles` | 列出所有文字样式 |
+| `create_linetype` | 创建线型 |
+| `load_linetype` | 加载线型文件 |
+| `list_linetypes` | 列出所有线型 |
+| `create_mleader_style` | 创建多重引线样式 |
+| `set_mleader_style_prop` | 设置多重引线样式属性 |
+| `list_mleader_styles` | 列出多重引线样式 |
+
+### 视图与缩放 (5)
+
+| 工具 | 说明 |
+|------|------|
+| `zoom_extents` | 缩放到图形范围 |
+| `zoom_window` | 缩放到窗口 |
+| `create_named_view` | 创建命名视图 |
+| `restore_named_view` | 恢复命名视图 |
+| `list_named_views` | 列出所有命名视图 |
 
-| 工具名称 | 描述 | 参数 |
-|---------|------|------|
-| `connect_cad` | 连接到 CAD | `platform`: AutoCAD/ZWCAD/GStarCAD/BricsCAD |
-| `get_cad_info` | 获取 CAD 信息 | 无 |
-| `bring_to_front` | 切换 CAD 到前台 | 无 |
-| `new_document` | 新建空白文档 | 无 |
-| `get_system_status` | 获取系统诊断信息 | 无 |
+### UCS 与布局 (11)
 
-### LISP 执行
+| 工具 | 说明 |
+|------|------|
+| `create_ucs` | 创建 UCS |
+| `set_ucs` | 切换到 UCS |
+| `list_ucs` | 列出所有 UCS |
+| `delete_ucs` | 删除 UCS |
+| `get_current_ucs` | 获取当前 UCS 名称 |
+| `create_layout` | 创建布局 |
+| `set_layout` | 切换布局 |
+| `list_layouts` | 列出所有布局 |
+| `delete_layout` | 删除布局 |
+| `get_current_layout` | 获取当前布局 |
+| `rename_layout` | 重命名布局 |
+
+### 查询与测量 (5)
+
+| 工具 | 说明 |
+|------|------|
+| `measure_distance` | 测量两点距离 |
+| `measure_area` | 测量多边形面积 |
+| `get_3d_solid_info` | 获取 3D 实体信息 |
+| `list_groups` | 列出所有组 |
+| `get_group_entities` | 获取组内实体 |
+
+### 组操作 (4)
+
+| 工具 | 说明 |
+|------|------|
+| `create_group` | 创建组 |
+| `delete_group` | 删除组 |
+| `list_groups` | 列出所有组 |
+| `get_group_entities` | 获取组内实体句柄 |
+
+### 批量操作 (14)
+
+| 工具 | 说明 |
+|------|------|
+| `batch_copy` | 批量复制实体到指定偏移 |
+| `batch_move` | 批量移动到指定图层 |
+| `batch_delete` | 批量删除实体 |
+| `batch_rename` | 批量重命名实体 |
+| `batch_set_color` | 批量设置颜色 |
+| `batch_set_layer` | 批量设置图层 |
+| `batch_set_linetype` | 批量设置线型 |
+| `batch_explode` | 批量炸开 |
+| `batch_mirror` | 批量镜像 |
+| `batch_offset` | 批量偏移 |
+| `batch_rotate` | 批量旋转 |
+| `batch_scale` | 批量缩放 |
+| `batch_match_properties` | 批量匹配属性（格式刷） |
+| `batch_create_group` | 批量创建组 |
+| `batch_add_to_group` | 批量添加到组 |
+
+### 3D 建模 (20)
+
+| 工具 | 说明 |
+|------|------|
+| `create_box` | 创建立方体 |
+| `create_sphere` | 创建球体 |
+| `create_cylinder` | 创建圆柱体 |
+| `create_cone` | 创建圆锥体 |
+| `create_torus` | 创建圆环体 |
+| `create_wedge` | 创建楔体 |
+| `create_3d_face` | 创建 3D 面 |
+| `create_3d_polyline` | 创建 3D 多段线 |
+| `create_mesh` | 创建网格 |
+| `extrude_solid` | 拉伸成实体 |
+| `revolve_solid` | 旋转成实体 |
+| `create_region` | 创建面域 |
+| `boolean_union` | 并集 |
+| `boolean_subtract` | 差集 |
+| `boolean_intersect` | 交集 |
+| `slice_solid` | 剖切实体 |
+| `create_loft_surface` | 创建放样曲面 |
+| `thicken_surface` | 曲面加厚 |
+| `offset_surface` | 曲面偏移 |
+| `convert_to_cloud_line` | 转为修订云线 |
+| `create_cloud_line` | 创建修订云线 |
+
+### 约束 (4)
+
+| 工具 | 说明 |
+|------|------|
+| `add_geom_constraint` | 添加几何约束（平行/垂直/相切/共线/同心/固定/对称/相等等） |
+| `add_dim_constraint` | 添加标注约束（水平/垂直/对齐/半径/直径/角度） |
+| `del_constraint` | 删除实体上所有约束 |
+| `list_constraints` | 列出所有约束 |
+
+### 扩展数据 Xdata (9)
+
+| 工具 | 说明 |
+|------|------|
+| `get_xdata` | 获取实体扩展数据 |
+| `set_xdata` | 设置实体扩展数据 |
+| `delete_xdata` | 删除扩展数据 |
+| `list_xdata_apps` | 列出所有注册的扩展数据应用名 |
+| `get_all_entity_xdata` | 获取所有扩展数据 |
+| `copy_xdata` | 复制扩展数据到另一实体 |
+| `search_by_xdata` | 按扩展数据搜索实体 |
+| `export_xdata_to_file` | 导出扩展数据到 JSON |
+| `import_xdata_from_file` | 从 JSON 导入扩展数据 |
+
+### PDF/底图 (14)
+
+| 工具 | 说明 |
+|------|------|
+| `attach_pdf` | 附着 PDF 底图 |
+| `detach_pdf` | 拆离 PDF 底图 |
+| `reload_pdf` | 重载 PDF 底图 |
+| `list_attached_pdfs` | 列出已附着的 PDF |
+| `get_pdf_info` | 获取 PDF 底图信息 |
+| `batch_attach_pdfs` | 批量附着 PDF |
+| `create_dgn_underlay` | 附着 DGN 底图 |
+| `create_dwf_underlay` | 附着 DWF 底图 |
+| `create_hyperlink` | 创建超链接 |
+| `remove_hyperlink` | 删除超链接 |
+
+### 外部参照 Xref (14)
+
+| 工具 | 说明 |
+|------|------|
+| `attach_xref` | 附着外部参照 |
+| `detach_xref` | 拆离外部参照 |
+| `reload_xref` | 重载外部参照 |
+| `unload_xref` | 卸载外部参照 |
+| `list_xrefs` | 列出所有外部参照 |
+| `bind_xref` | 绑定外部参照 |
+| `clip_xref` | 裁剪外部参照 |
+| `path_xref` | 修改外部参照路径 |
+| `xref_notifications` | 配置/查询外部参照变更通知 |
+| `xref_compare` | 比较外部参照 |
+| `xref_convert_to_block` | 外部参照转为块 |
+| `xref_demote` | 嵌套参照降级 |
+| `xref_path_relative` | 批量转换路径为相对路径 |
+
+### 图纸集 (18)
+
+| 工具 | 说明 |
+|------|------|
+| `create_sheet_set` | 创建图纸集 |
+| `open_sheet_set` | 打开图纸集文件 |
+| `list_sheet_sets` | 列出所有图纸集 |
+| `add_sheet` | 添加图纸 |
+| `list_sheets` | 列出图纸 |
+| `delete_sheet` | 删除图纸 |
+| `reorder_sheet` | 重新排序图纸 |
+| `create_subset` | 创建子集 |
+| `list_subsets` | 列出子集 |
+| `set_sheet_property` | 设置图纸属性 |
+| `get_sheet_set_property` | 获取图纸集属性 |
+| `publish_sheet_set` | 发布图纸集 |
+| `create_sheet_set_archive` | 归档图纸集 |
+| `sheet_set_publish_options` | 发布选项配置 |
+| `sheet_set_transmit` | eTransmit 打包 |
+| `sheet_set_compare` | 比较图纸集 |
+| `sheet_list_views` | 列出图纸视图 |
+| `sheet_import_layouts` | 从 DWG 导入布局 |
+
+### 打印 (8)
+
+| 工具 | 说明 |
+|------|------|
+| `plot_to_pdf` | 打印到 PDF |
+| `plot_to_printer` | 打印到打印机 |
+| `save_pdf_layout` | 布局另存为 PDF |
+| `publish_layouts` | 批量发布布局到 PDF |
+| `batch_plot_wizard` | 批量打印向导 |
+| `plot_device_management` | 打印设备管理 |
+| `plot_log` | 查询打印历史 |
+| `plot_from_file_list` | 从文件列表批量打印 |
+
+### 管道 Pipeline (5)
+
+| 工具 | 说明 |
+|------|------|
+| `pipeline_execute` | 执行管道链（多步工具顺序执行） |
+| `pipeline_save` | 保存管道定义 |
+| `pipeline_list` | 列出已保存管道 |
+| `pipeline_run` | 运行已保存管道 |
+| `pipeline_delete` | 删除管道 |
+
+### 触发器 Watch (5)
+
+| 工具 | 说明 |
+|------|------|
+| `watch_register` | 注册 CAD 变更触发器 |
+| `watch_remove` | 移除触发器 |
+| `watch_list` | 列出所有触发器 |
+| `watch_wait` | 等待触发器触发 |
+| `watch_create_and_wait` | 注册并等待（合并操作） |
+
+### Webhook (4)
+
+| 工具 | 说明 |
+|------|------|
+| `webhook_register` | 注册 webhook |
+| `webhook_list` | 列出所有 webhook |
+| `webhook_remove` | 移除 webhook |
+| `webhook_log` | 获取 webhook 日志 |
+
+### 流式读取 (4)
+
+| 工具 | 说明 |
+|------|------|
+| `stream_entities` | 分页流式读取实体数据 |
+| `stream_text` | 分页流式读取文字内容 |
+| `stream_block_refs` | 分页流式读取块参照 |
+| `combine_text` | 碎片文本按位置组合为完整段落 |
 
-| 工具名称 | 描述 | 参数 |
-|---------|------|------|
-| `eval_lisp` | 执行 LISP 代码（无返回值） | `code`: LISP 代码 |
-| `eval_lisp_with_result` | 执行 LISP 并返回结果 | `code`, `encoding`: utf-8/gbk |
-| `at_command` | 执行 @lisp 命令 | `command`: 命令 |
-
-### 包管理
-
-| 工具名称 | 描述 | 参数 |
-|---------|------|------|
-| `list_packages` | 列出已安装的包 | 无 |
-| `search_packages` | 搜索包 | `query`: 关键词 |
-| `install_package` | 安装包 | `packageName`: 包名 |
-
-### 实体操作
-
-| 工具名称 | 描述 | 参数 |
-|---------|------|------|
-| `get_entity` | 获取实体属性 | `handle`: 句柄 |
-| `set_entity` | 设置实体属性 | `handle`, `property`: layer/color/linetype/elevation, `value` |
-| `delete_entity` | 删除实体 | `handle`: 句柄 |
-| `select_entities` | 按条件选择实体 | `filter`: {type, layer} |
-
-### 图层操作
-
-| 工具名称 | 描述 | 参数 |
-|---------|------|------|
-| `create_layer` | 创建图层 | `name`, `color`: 1-255, `linetype`: 线型名 |
-| `delete_layer` | 删除图层 | `name` |
-| `set_layer` | 设置图层属性 | `name`, `property`: color/linetype/freeze/thaw/lock/unlock |
-| `set_current_layer` | 设置当前图层 | `name` |
-
-### 块操作
-
-| 工具名称 | 描述 | 参数 |
-|---------|------|------|
-| `create_block` | 创建块定义 | `name`, `entities`: 实体代码 |
-| `insert_block` | 插入块 | `blockName`, `point`: x,y, `scale`: 1, `rotation`: 0 |
-| `get_blocks` | 获取所有块定义 | 无 |
-| `explode_block` | 炸开块 | `handle`: 句柄 |
-
-### 文件操作
-
-| 工具名称 | 描述 | 参数 |
-|---------|------|------|
-| `open_dwg` | 打开 DWG 文件 | `filePath`: 完整路径 |
-| `save_dwg` | 保存图形 | `filePath`: 另存路径（可选） |
-| `export_pdf` | 导出 PDF | `outputPath`, `layout`: Model/Layout1 |
-| `close_dwg` | 关闭图形 | `save`: true/false |
-
-### @lisp 系统
-
-| 工具名称 | 描述 | 参数 |
-|---------|------|------|
-| `install_atlisp` | 安装 @lisp | 无 |
-| `init_atlisp` | 初始化 @lisp 环境 | 无 |
-| `get_function_usage` | 获取函数用法 | `name`: 函数名, `package`: 包名 |
-| `list_symbols` | 列出所有符号 | `package`: 包名（可选） |
-| `import_funlib` | 导入函数库到 AI | `format`: json/list |
-| `get_platform_info` | 获取平台信息 | 无 |
-| `list_prompts` | 列出提示模板 | 无 |
-| `get_prompt` | 获取提示模板 | `name`, `args`: 参数 |
+### 外部数据 (4)
+
+| 工具 | 说明 |
+|------|------|
+| `external_db_query` | 查询外部数据源 (CSV/JSON) |
+| `import_external_data` | 从外部数据源导入实体到 CAD |
+| `export_to_external` | 导出 CAD 实体到外部文件 |
+| `list_data_sources` | 列出可用数据源 |
+
+### 沙箱 (3)
+
+| 工具 | 说明 |
+|------|------|
+| `sandbox_validate` | 验证 Lisp 代码安全规则 |
+| `sandbox_allowlist_add` | 添加规则到会话白名单 |
+| `sandbox_allowlist_clear` | 清除会话白名单 |
+
+### 审计日志 (2)
+
+| 工具 | 说明 |
+|------|------|
+| `audit_log_query` | 查询审计日志（支持分页和筛选） |
+| `audit_log_stats` | 获取审计日志统计 |
+
+### CAD 连接池 (4)
+
+| 工具 | 说明 |
+|------|------|
+| `cad_pool_discover` | 发现所有 CAD 实例 |
+| `cad_pool_switch` | 切换活动 CAD 实例 |
+| `cad_pool_health` | 检查所有实例健康状态 |
+| `cad_pool_stats` | 获取连接池统计 |
 
 ---
 
-## 七、MCP 资源 (11 个)
+## MCP 资源
+
+### 静态资源 (13)
 
 | URI | 名称 | 说明 | 可订阅 |
 |-----|------|------|--------|
 | `atlisp://cad/info` | CAD Info | CAD 连接信息 | ✓ |
-| `atlisp://dwg/layers` | Layers | 图层列表 | ✓ |
 | `atlisp://dwg/entities` | Entities | 实体列表/统计 | ✓ |
-| `atlisp://dwg/texts` | Texts | 文本实体列表 | ✓ |
+| `atlisp://dwg/text-content` | Text Content | 文字内容与位置 | ✓ |
+| `atlisp://dwg/text-combined` | Combined Text | 合并后的段落文本 | ✓ |
 | `atlisp://dwg/name` | DWG Name | 当前文件名 | ✓ |
 | `atlisp://dwg/path` | DWG Path | 文件完整路径 | ✓ |
+| `atlisp://dwg/block-refs` | Block References | 块参照与属性 | ✓ |
+| `atlisp://dwg/tbl` | Tables | CAD 表数据 | ✓ |
 | `atlisp://cad/dwgs` | DWG List | 所有打开的 DWG | ✓ |
 | `atlisp://packages` | Packages | 已安装包列表 | ✓ |
-| `atlisp://platforms` | Platforms | 支持的平台信息 | ✗ |
-| `atlisp://standards/drafting` | Drafting Standards | CAD 制图规范 | ✗ |
-| `atlisp://standards/coding` | Coding Standards | @lisp 编码规范 | ✗ |
+| `atlisp://platforms` | Platforms | 支持的平台 | ✗ |
+| `atlisp://standards/drafting` | Drafting | CAD 制图规范 | ✗ |
+| `atlisp://standards/coding` | Coding | @lisp 编码规范 | ✗ |
 
-### 资源参数过滤
-
-```
-atlisp://dwg/entities                    # 返回实体统计（类型+数量）
-atlisp://dwg/entities?type=LINE         # 返回 LINE 类型实体列表
-atlisp://dwg/entities?layer=0            # 返回 0 图层实体列表
-atlisp://dwg/entities?bbox=0,0,100,100   # 返回区域内的实体列表
-atlisp://dwg/texts?layer=0&limit=100     # 分页获取文本
-atlisp://dwg/layers?name=0               # 查询特定图层
-atlisp://packages?name=base              # 过滤包列表
-```
-
-### 资源模板 (5 个)
+### 资源模板
 
 | URI 模板 | 说明 |
-|---------|------|
-| `atlisp://dwg/entity/{handle}` | 按句柄查询实体详情 |
-| `atlisp://dwg/entities?type={type}` | 按类型查询实体 |
-| `atlisp://dwg/layers?name={name}` | 按名称查询图层 |
+|----------|------|
+| `atlisp://dwg/entity/{handle}` | 按句柄查实体详情 |
+| `atlisp://dwg/entities?type={type}&layer={layer}&bbox={bbox}` | 过滤实体 |
+| `atlisp://dwg/block-refs/{blockName}` | 按块名过滤块参照 |
+| `atlisp://dwg/tbl/{table}` | 查询表（layer/block/textstyle/dimstyle/linetype/ucs/view/viewport/regapp/plotstyle） |
+| `atlisp://dwg/text-content?bbox={bbox}&layer={layer}&offset={offset}&limit={limit}` | 分页文字 |
 | `atlisp://packages?search={query}` | 搜索包 |
-| `atlisp://dwg/texts?layer={layer}&offset={offset}&limit={limit}` | 分页获取文本 |
 
-### MCP 根目录 (Roots) - 2 个
+### MCP 根目录 (Roots)
 
-| URI | 名称 | 说明 |
-|-----|------|------|
-| `file://~/@lisp` | @lisp 根目录 | @lisp 工作目录 |
-| `file://~/@lisp/projects` | 项目目录 | 存放 DWG 文件的项目文件夹 |
+| URI | 说明 |
+|-----|------|
+| `file://~/.atlisp` | @lisp 工作目录 |
+| `file://~/.atlisp/projects` | 项目目录 |
 
-### MCP 方法
+---
 
-| 方法 | 说明 |
-|------|------|
-| `initialize` | 初始化连接 |
-| `roots/list` | 列出根目录 |
-| `tools/list` | 列出工具 |
-| `tools/call` | 调用工具 |
-| `resources/list` | 列出资源 |
-| `resources/read` | 读取资源 |
-| `resources/subscribe` | 订阅资源变更 |
-| `resources/unsubscribe` | 取消订阅 |
-| `prompts/list` | 列出提示模板 |
-| `prompts/get` | 获取提示模板 |
-
-### 资源访问示例
+## MCP Prompts (16)
+
+| Prompt | 功能 | 参数 |
+|--------|------|------|
+| `excel-report` | Excel 报表导出 | visible, savePath |
+| `geometry-calc` | 几何计算 | action, points |
+| `generate-dimension` | 生成尺寸标注 | style |
+| `analyze-drawing` | 分析当前图纸统计 | — |
+| `coding-conventions` | AutoLISP 编码规范 | — |
+| `string-process` | 字符串处理 | action, input |
+| `json-exchange` | JSON 数据交换 | action, data |
+| `color-convert` | 颜色转换 | action, value |
+| `pickset-filter` | 选择集操作 | action, dxfType, layerName |
+| `text-process` | 文本处理 | action, markdown |
+| `curve-analysis` | 曲线分析 | action, distance |
+| `manage-blocks` | 块操作 | action, blockName |
+| `manage-layers` | 图层管理 | action, layers |
+| `export-entities` | 导出实体统计 | format |
+| `batch-draw-lines` | 批量画线段 | count, length |
+| `draw-residential` | 农村民居平面图 | width, depth, rooms |
+| `draw-floor-plan` | 建筑楼层平面图 | floor, scale |
 
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 1,
-  "method": "resources/read",
-  "params": {
-    "uri": "atlisp://dwg/entities"
-  }
-}
-```
+---
 
-返回实体统计：
-```json
-{
-  "contents": [{
-    "uri": "atlisp://dwg/entities",
-    "mimeType": "application/json",
-    "text": "{\"total\":150,\"summary\":[{\"type\":\"LWPOLYLINE\",\"count\":45},{\"type\":\"LINE\",\"count\":32}]}"
-  }]
-}
-```
+## HTTP API 端点
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| `GET` | `/health` | 健康检查 |
+| `GET` | `/metrics` | Prometheus 指标 |
+| `POST` | `/mcp` | MCP JSON-RPC |
+| `GET` | `/mcp` | MCP 信息 |
+| `GET` | `/sse` | SSE 长连接端点 |
+| `POST` | `/message` | SSE 消息发送 |
+| `WS` | `/ws` | WebSocket 端点 |
+| `POST` | `/config/reload` | 热重载配置 |
+| `GET` | `/rate-limit/status` | 速率限制状态 |
+| `POST` | `/rate-limit/reset` | 重置速率限制 |
+| `GET` | `/api/docs` | API 文档页面 |
+| `GET` | `/debug` | 调试面板 |
+| `GET` | `/playground` | 工具游乐场 |
 
 ---
 
-## 八、环境变量
+## 环境变量
 
 | 变量 | 默认值 | 说明 |
 |------|--------|------|
-| `TRANSPORT` | `http` | 传输模式：`http` 或 `stdio` |
-| `PORT` | `8110` | HTTP 模式监听端口 |
-| `HOST` | `0.0.0.0` | HTTP 模式监听地址 |
-| `MESSAGE_TIMEOUT` | `60000` | 消息超时（毫秒） |
-| `MCP_API_KEY` | (无) | API Key 认证（可选） |
-| `ENABLE_SSE` | `true` | 启用 SSE 模式（默认启用） |
-
-### 启用 SSE 模式
-
-SSE (Server-Sent Events) 模式默认启用，提供长连接推送能力，适合需要实时响应的场景。
+| `PORT` | `8110` | HTTP 端口 |
+| `HOST` | `0.0.0.0` | HTTP 监听地址 |
+| `TRANSPORT` | `http` | 传输模式: http/stdio/ws |
+| `MCP_API_KEY` | — | API Key 认证 |
+| `ENABLE_SSE` | `true` | 启用 SSE |
+| `MESSAGE_TIMEOUT` | `60000` | 消息超时 (ms) |
+| `HEARTBEAT_INTERVAL` | `30000` | 心跳间隔 (ms) |
+| `BUSY_RETRIES` | `10` | CAD 忙重试次数 |
+| `BUSY_DELAY` | `500` | 重试延迟 (ms) |
+| `ENABLE_CORS` | `true` | 启用 CORS |
+| `CORS_ORIGIN` | `*` | CORS 源 |
+| `RATE_LIMIT_WINDOW` | `60000` | 速率限制窗口 (ms) |
+| `RATE_LIMIT_MAX` | `100` | 窗口内最大请求数 |
+| `RESOURCE_CACHE_TTL` | `5000` | 资源缓存 TTL (ms) |
+| `FUNCTION_LIB_CACHE_TTL` | `300000` | 函数库缓存 TTL (ms) |
+| `DEBUG` | `false` | 调试模式 |
+| `DEBUG_FILE` | — | 调试日志文件路径 |
+| `FUNCTION_LIB_URL` | `http://s3.atlisp.cn/json/functions.json` | 函数库 URL |
+| `CONFIG_FILE` | `~/.atlisp/atlisp.config.json` | 配置文件路径 |
+| `METRICS_ENABLED` | `true` | 启用 /metrics 端点 |
+| `REQUEST_LOG_ENABLED` | `true` | 启用请求日志 |
+| `SSL_KEY_PATH` | — | SSL 私钥文件 |
+| `SSL_CERT_PATH` | — | SSL 证书文件 |
+| `LLM_API_KEY` | — | LLM API Key (sampling) |
+| `LLM_API_URL` | `https://api.openai.com/v1/chat/completions` | LLM API URL |
+| `LLM_MODEL` | `gpt-4o-mini` | LLM 模型 |
+| `LLM_MAX_TOKENS` | `4096` | LLM 最大 tokens |
+| `LLM_TEMPERATURE` | `0.7` | LLM 温度 |
+| `API_KEY_RATE_LIMIT` | `1000` | API Key 速率限制 |
 
-**禁用 SSE：**
+---
 
-```bash
-# Windows PowerShell
-$env:ENABLE_SSE="false"; atlisp-mcp
+## 命令行参数
 
-# 或命令行
-ENABLE_SSE=false atlisp-mcp
-```
+| 参数 | 说明 |
+|------|------|
+| `--port <number>` | HTTP 端口 |
+| `--host <address>` | HTTP 主机地址 |
+| `--transport <mode>` | 传输模式 (http/stdio/ws) |
+| `--stdio` | 等价于 `--transport stdio` |
+| `--ws` | 等价于 `--transport ws` |
+| `--config <path>` | 配置文件路径 |
+| `--ssl-key <path>` | SSL 私钥文件 |
+| `--ssl-cert <path>` | SSL 证书文件 |
 
-**SSE 端点：**
+---
 
-| 端点 | 方法 | 说明 |
-|------|------|------|
-| `/sse` | GET | 建立 SSE 连接，返回消息端点 `/message` |
-| `/mcp/sse` | GET | 同上 |
-| `/message` | POST | 发送 JSON-RPC 请求，响应通过 SSE 推送 |
+## 配置文件
 
-**SSE 连接流程：**
+配置文件位于 `~/.atlisp/atlisp.config.json`，支持以下字段：
 
+```json
+{
+  "port": 8110,
+  "host": "0.0.0.0",
+  "transport": "http",
+  "apiKey": "your-api-key",
+  "enableSse": true,
+  "messageTimeout": 60000,
+  "heartbeatInterval": 30000,
+  "enableCors": true,
+  "corsOrigin": "*",
+  "rateLimitWindow": 60000,
+  "rateLimitMax": 100,
+  "debug": false,
+  "metricsEnabled": true,
+  "requestLogEnabled": true,
+  "maxPoolSize": 3,
+  "apiKeys": [
+    { "key": "key1", "limit": 100, "name": "user1", "role": "admin" }
+  ],
+  "sslKey": "/path/to/key.pem",
+  "sslCert": "/path/to/cert.pem",
+  "llmApiKey": "sk-xxx",
+  "llmApiUrl": "https://api.openai.com/v1/chat/completions",
+  "llmModel": "gpt-4o-mini",
+  "llmMaxTokens": 4096,
+  "llmTemperature": 0.7
+}
 ```
-1. 客户端 → GET /sse
-   Header: Accept: text/event-stream
-
-2. 服务器 → 返回 SSE 流，包含:
-   event: endpoint
-   data: {"path": "/message"}
-   event: capabilities
-   data: {...}
-
-3. 客户端 → POST /message
-   Header: mcp-session-id: <session-id>
-   Body: {"jsonrpc":"2.0","id":1,"method":"tools/call",...}
-
-4. 服务器 → 通过 SSE 推送响应:
-   event: message
-   data: {"jsonrpc":"2.0","id":1,"result":{...}}
-```
-
----
-
-## 九、支持平台
 
-- **AutoCAD** (扩展名: `.fas`, `.vlx`)
-- **ZWCAD** (扩展名: `.zelx`, `.vls`)
-- **GStarCAD** (扩展名: `.des`)
-- **BricsCAD** (扩展名: `.des`)
+配置变更会自动热重载。
 
 ---
 
-## 十、工作原理
+## 架构与开发
 
-1. MCP Server 通过 `edge-js` 调用 .NET 代码
-2. .NET 通过 COM 互操作连接 CAD 应用程序
-3. 支持获取运行中的 CAD 或自动启动
-4. 通过 `SendCommand` 向 CAD 发送 LISP 代码
-5. 执行前自动检测 CAD 状态（IsQuiescent）
-6. CAD 忙碌时自动等待（最多 10 次重试）
+架构图、项目结构、开发指南请参见 [`DEV.md`](DEV.md)。
 
 ---
 
-## 十一、故障排除
+## 故障排除
 
 | 问题 | 解决方案 |
 |------|---------|
 | 连接失败 | 确保 CAD 已启动并启用 COM 接口 |
-| 工具调用超时 | CAD 可能繁忙，稍后重试 |
-| 中文乱码 | 使用 `vl-prin1-to-string` 处理 |
+| 工具调用超时 | CAD 可能繁忙，稍后重试；增大 `MESSAGE_TIMEOUT` |
+| 中文乱码 | 使用 `encoding: gbk` 参数或用 `vl-prin1-to-string` 处理 |
 | 括号错误 | MCP Server 会自动检查并提示 |
+| CAD 未自动启动 | 检查 COM 权限，以管理员身份运行 |
+| 端口被占用 | 使用 `--port` 指定其他端口 |
+| 全局命令找不到 | 检查 npm 全局安装路径是否在 PATH 中 |
 
 ---
 
 ## 许可证
 
-ISC
+ISC