# revit-tunnel MCP（独立管片 V2）

这是一个独立于现有通用 Revit MCP 的专用 MCP。它通过 Node.js stdio MCP、仅限本机的 pyRevit Routes 接口和 Revit 2025 API，让 Agent 预览、创建并核验盾构隧道。旧版“每环一个整体族”仍完整保留；V2 新增“每块管片一个独立族构件”。

## 独立管片能力

- 默认布局为 `9A1K`：每环 9 块 A（各 37.5°）和 1 块 K（22.5°）。
- 默认 10 环会创建 100 个可单独选择、统计、过滤和排表的 `Generic Models` 族实例。
- 支持 1–50 环，但任何一次创建最多 500 块独立管片。
- 支持外径、厚度、环宽、三维起点、直线纵坡以及相邻环正负交替错缝。
- 每环只创建一个命名为 `RTM_SEG_HOST_*` 的工作基准面，同一环的全部管片共用它。
- 每块管片都有稳定标记，例如 `batch-R0001-A01`、`batch-R0001-K01`。
- 批次创建由一个 Revit 事务组包裹；任何族或构件失败时，实例、基准面和本次新载入的族会一起回滚。

## 可升级的族内容

族名由构件角色、尺寸、角度、内容配置和内容版本共同确定：

```text
RTM_Segment_{role}_OD{outer}_T{thickness}_W{width}_S{spanMilliDeg}_{profile}_V{version}
```

当前内容提供器是 `basic` 版本 `1`，为每种几何生成一个简单的环形扇区族。族类型的 `Type Comments` 保存 `RTM_CONTENT:<hash>`。同名族只有在内容哈希完全一致时才会复用；缺少哈希或哈希不同会报冲突，不会静默覆盖。

因此，未来给管片增加注浆孔、螺栓孔、手孔、沟槽或钢筋表现时，可以发布新的内容版本。旧批次继续冻结在原族版本；布局、构件编号和 Agent 调用流程不需要改写。

## 构件身份参数

所有独立管片族都使用 12 个固定 GUID 的实例共享参数：

- `RTM_BatchId`、`RTM_UniqueId`
- `RTM_RingIndex`、`RTM_SegmentIndex`
- `RTM_SegmentSlot`、`RTM_SegmentRole`
- `RTM_LayoutId`
- `RTM_ContentProfile`、`RTM_ContentVersion`
- `RTM_StartAngle`、`RTM_EndAngle`、`RTM_CenterAngle`

固定 GUID 使未来 A、B、K 族以及不同精度版本仍可使用同一套明细表、过滤器和标签。

## 八个 MCP 工具

独立管片 V2：

- `list_tunnel_segment_catalog`：列出布局和内容版本。
- `preview_tunnel_segments`：只读校验并返回完整的逐块计划与预览令牌。
- `create_tunnel_segments`：要求相同参数、`preview_token` 和 `confirm=true` 后创建。
- `inspect_tunnel_segment_batch`：只读反查每块构件的身份、族版本、位置、定向、体积和承载基准面。

保留的整体环 V1：

- `preview_tunnel_rings`
- `create_tunnel_rings`
- `inspect_tunnel_batch`
- `get_tunnel_backend_status`（V1/V2 共用）

推荐调用顺序是：检查后端 → 列目录 → 预览 → 用户确认 → 创建 → 检查批次。

## 后续切换 `6A＋2B＋1K`

布局与族内容已经分层。以后新增 `6A2B1K` 时，只需在版本化目录中增加 9 个槽位及 A/B/K 的角度规则；放置器、身份参数、MCP 工具和检查接口保持不变。如果 B 与 A 的几何不同，系统会按其角色和角度自动解析新的族规格。

## 安全边界

- Routes 只监听 `127.0.0.1:48884`，不暴露到局域网。
- Node 预览和 pyRevit 后端会分别校验完整计划；V2 还会重算布局摘要、逐环位置、逐块角度、标记、族名与内容哈希。
- 整体环与独立管片共用全局 `batch_id` 命名空间，任何一侧已存在都会拒绝重复创建。
- 当前没有删除、覆盖或升级既有批次的工具。
- 现有通用 Revit MCP 和 `ShieldTunnel.extension` 均未修改。

## 安装

- 源码：克隆本仓库后的项目目录
- pyRevit 扩展：`%USERPROFILE%\Documents\pyRevit Extensions\RevitTunnelMcp.extension`
- Codex 配置：`%USERPROFILE%\.codex\config.toml` 中的 `[mcp_servers.revit_tunnel]`

先安装 Node.js 22 和项目依赖：

```powershell
npm install
```

重新安装扩展：

```powershell
& '.\scripts\install.ps1' -RoutesPort 48884
```

安装或修改后需重新加载 pyRevit（或重启 Revit）。

## 验证与冒烟调用

```powershell
npm test
python -m pytest -q '.\pyrevit\tests'
node '.\scripts\smoke-test.mjs' --segments --inspect --batch-id=<批次>
```

创建两环独立管片测试批次：

```powershell
node '.\scripts\smoke-test.mjs' --segments --create --ring-count=2 --batch-id=segment-e2e-01
```

整体环旧版调用不加 `--segments`。`--create` 会真实修改当前 Revit 项目，只应在测试副本或确认过的项目中使用。