feat(plugin): 增加闭环单入口 build_model 的说明与使用示例
This commit is contained in:
ringo
@@ -21,6 +21,7 @@ description: 以 AML 为唯一事实源读写建筑模型并编译校验。当
|
||||
|----------|--------|
|
||||
| 读取 / 修改 / 搜索 AML 与其它设计源文件（`aml.xml`、`bss.md`、`rules.yml`、`behaviors.yml`、`design-brief.md`） | **宿主原生工具**：read / patch / grep / shell（直接改文件，不走 MCP 编辑工具） |
|
||||
| 云端编译（AML → building.json） | MCP `apply_design` |
|
||||
| **改模型并让它出现在云项目/Studio（闭环单入口）** | **MCP `build_model`**（写工作区 → 编译 → 校验 → 云同步，一次调用完成） |
|
||||
| 语法与几何校验 / 规则检查 | MCP `validate_model`、`analyze_gsa_issues`、`analyze_rules_compliance` |
|
||||
| 围护结构统计 | MCP `envelope_stats` |
|
||||
| 空间邻接、交通空间合并 | MCP `query_spatial_graph`、`apply_design(merge_traffic_spaces=…)` |
|
||||
@@ -28,9 +29,30 @@ description: 以 AML 为唯一事实源读写建筑模型并编译校验。当
|
||||
| 把本地改动送上云端、取回云端工作区 | MCP `push_project`、`pull_project` |
|
||||
| 语法规则与生成上下文 | MCP `get_aml_schema`、`generate_aml` |
|
||||
|
||||
固定顺序：**本地编辑 → `push_project` → 引擎校验 → Studio 查看**。
|
||||
引擎工具读的是**服务端工作区**的文件，没推送过就读不到你的最新改动——
|
||||
改完不 push 直接校验，校验结果对应的是上一版。
|
||||
固定顺序（工具面里有 `build_model` 时）：**本地写 AML → `build_model` → 看 gate →（Studio 里看效果）**。
|
||||
`build_model` 一次完成「写服务端工作区 → 编译 → 校验 → 写进云项目工作区」，Studio 里立即可见。
|
||||
工具面里没有 `build_model`（本机全量形态）时才退化为：本地编辑 → `push_project` → `apply_design` →
|
||||
`validate_model` → Studio 查看。引擎工具读的是**服务端工作区**的文件，没推送过就读不到你的最新改动。
|
||||
|
||||
**工具检索结果条数有限**：一次搜索没看到某个工具，不代表它不存在。闭环工具名固定是
|
||||
`build_model` / `push_project` / `apply_design` / `validate_model`，直接按名字调用。
|
||||
|
||||
### 闭环单入口 build_model
|
||||
|
||||
```
|
||||
build_model({ aml?: "<AML 全文>", files?: { "aml.xml": "…" }, projectId?: "24", force?: false })
|
||||
```
|
||||
|
||||
- `aml` 给出则先写入服务端工作区 `aml.xml`；`files` 可一并写其它工作区文件（路径规则同 `push_project`）。
|
||||
- `projectId` 缺省取工作区 `deta.json` 绑定的云项目；没有绑定就先
|
||||
`push_project({ files, projectId })` 绑一次。
|
||||
- 返回：`gate`（`passed` / `failed`）、编译摘要、校验明细、`cloud.headSha`、`studioUrl`。
|
||||
- `gate: failed` → 按 warning/error 改 AML，再调一次 `build_model`，直到 `passed`。
|
||||
- `status: conflict`（`version_conflict`）→ 云项目工作区被其它会话改过（例如 Studio 面板里编辑过），
|
||||
确认要覆盖再传 `force: true` 重跑一次。
|
||||
- `status: unavailable` → 该形态没有云同步通道（例如本机全量形态），改用
|
||||
`apply_design` + `validate_model`。
|
||||
- **禁止**把 AML 拷进 Studio 的代码编辑器手工点编译：那是没有闭环工具时的兜底，不是正常路径。
|
||||
|
||||
### push 与 Studio 深链
|
||||
|
||||
@@ -51,14 +73,21 @@ Studio 就是 ant-model（deta.city 上的建筑性能应用）。在 Codex 右
|
||||
|
||||
打开步骤（用宿主内置浏览器 = browser 插件的 `iab`）：
|
||||
|
||||
1. 取 `studioUrl`：本机项目目录 `deta.json` 里的 `projectId`，或 `push_project(…, projectId)` 的返回值。
|
||||
形如 `https://deta.city/design/<projectId>`（门户页负责登录态同步，再以 `cloudProjectId` 内嵌 Studio）。
|
||||
1. **先调 `studio_link` 拿一次性链接**（推荐路径，免手工登录）：返回 `url`
|
||||
（`https://deta.city/mcp-api/portal-session/landing?ticket=…&next=/design/<id>`）、
|
||||
`studioUrl`、`expiresInSeconds`（180）。该链接在面板内会自动完成 deta.city 登录并跳到 Studio。
|
||||
若返回 `auth_required` → 先让用户完成 MCP 授权（`codex mcp login deta_mcp`）再重试；
|
||||
若 `url` 报「票据无效或已过期」→ 重新调一次 `studio_link`，不要改成手工登录。
|
||||
2. 按 browser 插件技能（`control-in-app-browser`）的 Bootstrap 初始化，再取内置浏览器句柄：
|
||||
`const iab = await agent.browsers.get("iab");`，并先读一次 `await iab.documentation()`。
|
||||
3. 先 `await iab.tabs.list()` 看是否已有该 URL 的标签：**有就复用，不要调 `goto` 重载**
|
||||
（重载会丢面板里正在进行的操作）；没有才 `const tab = await iab.tabs.new(); await tab.goto(studioUrl);`
|
||||
（重载会丢面板里正在进行的操作）；没有才 `const tab = await iab.tabs.new(); await tab.goto(url);`
|
||||
4. 打开后告诉用户「Studio 已在右侧面板打开（项目名/ID）」，并说明模拟在面板里运行。
|
||||
|
||||
旧路径（工具面里没有 `studio_link` 时）：自己拼 `studioUrl`
|
||||
（本机项目目录 `deta.json` 的 `projectId`，或 `push_project(…, projectId)` 的返回值，
|
||||
形如 `https://deta.city/design/<projectId>`），按上面第 2–4 步打开——但需面板已登录。
|
||||
|
||||
在面板里跑模拟：
|
||||
|
||||
- 模拟入口在 Studio 界面内（分析/模拟面板、GH 模板等）。**默认交给用户在面板里操作**——
|
||||
@@ -69,11 +98,16 @@ Studio 就是 ant-model（deta.city 上的建筑性能应用）。在 Codex 右
|
||||
|
||||
前置与故障：
|
||||
|
||||
- 面板未登录 deta.city：**面板是独立的浏览器上下文**，系统浏览器里的登录态带不过来。处置：
|
||||
在面板里打开 `https://deta.city/login` 完成一次登录（登录态写入该浏览器的 `ant_token` cookie 与
|
||||
`ant-model-auth` localStorage，之后长期有效）；若宿主的 MCP 授权页恰好开在面板里，
|
||||
`codex mcp login deta_mcp` 一步即可同时建立门户会话（授权成功时授权页会写入该浏览器）。
|
||||
- 面板未登录 deta.city：用 `studio_link` 的一次性链接即可免手工登录（见上）；只有拿不到
|
||||
`studio_link` 时才退化为手工：在面板里打开 `https://deta.city/login` 完成一次登录
|
||||
（登录态写入该浏览器的 `ant_token` cookie 与 `ant-model-auth` localStorage，之后长期有效），
|
||||
登录完成后重新打开 `studioUrl` 即自动加载项目。
|
||||
- **宿主把 MCP 授权页开在哪个浏览器由宿主决定**（实测 Codex Desktop 走系统默认浏览器），
|
||||
且**那一页的登录态不会进入面板**——所以别把"MCP 已授权"当成"面板已登录"，两者要分别确认：
|
||||
MCP 授权只解决 Codex↔服务端；面板登录解决 Studio 在面板里的会话（`studio_link` 正是两者的桥）。
|
||||
实测口径：授权页在系统浏览器完成换码后停留在宿主的回调页（"Authentication complete. You may close
|
||||
this window."），该页不归我们控制；授权页自身已改为**在隐藏框架内完成换码**并给出「打开 deta.city」
|
||||
与「关闭本页」，不再顶层跳走。
|
||||
- 没有 `projectId`：Studio 打开的是空项目。先在门户创建云项目拿到 ID，再 `push_project(…, projectId)` 绑定。
|
||||
- 宿主没有内置浏览器（CLI 等形态）：直接把 `studioUrl` 给用户，让他自己打开，不要假装已经打开。
|
||||
|
||||
@@ -119,8 +153,10 @@ Studio 就是 ant-model（deta.city 上的建筑性能应用）。在 Codex 右
|
||||
|
||||
设计源码读写/搜索：**宿主原生工具**（read / patch / grep / shell），不经 MCP
|
||||
生成与语法：`generate_aml`、`get_aml_schema`
|
||||
闭环单入口：`build_model`（写工作区 → 编译 → 校验 → 云同步；见「闭环单入口 build_model」一节）
|
||||
编译与校验：`apply_design`、`validate_model`、`envelope_stats`、`query_spatial_graph`、
|
||||
`generate_candidates`、`analyze_gsa_issues`、`analyze_rules_compliance`
|
||||
同步：`push_project`、`pull_project`
|
||||
脚本与参考：`run_script`、`run_scripts`、`read_reference`
|
||||
项目与查询：`list_projects`、`list_buildings`、`query_knowledge`、`parameter_sweep`
|
||||
面板与 Studio：`studio_link`（面板免密登录链接，见「在右侧面板打开 Studio」一节）
|
||||
|
||||
Reference in New Issue
Block a user