From 71a31dc112da775761f335bb3d3e12790f85c317 Mon Sep 17 00:00:00 2001 From: ringo Date: Thu, 10 Sep 2026 13:29:33 +0800 Subject: [PATCH] =?UTF-8?q?feat(plugin):=20=E6=8A=80=E8=83=BD=E6=94=B9?= =?UTF-8?q?=E5=86=99=E4=B8=BA=E3=80=8C=E7=BC=96=E8=BE=91=E5=BD=92=E5=AE=BF?= =?UTF-8?q?=E4=B8=BB=E3=80=81MCP=20=E5=8F=AA=E5=81=9A=E5=BC=95=E6=93=8E?= =?UTF-8?q?=E4=B8=8E=E5=90=8C=E6=AD=A5=E3=80=8D=EF=BC=88v0.2.2=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - SKILL.md 新增「编辑与校验分工」：AML 与设计源文件用宿主原生 read/patch/grep 编辑， 编译/规范校验/规则检查/围护统计/空间邻接走 MCP 引擎工具；固定顺序 本地编辑 → push_project → 引擎校验 → Studio 查看；studioUrl 用内置浏览器打开且复用已有标签 - README 新增「工具面」说明、本地项目目录约定（可选 deta.json 绑定 projectId） 与端到端工作流示例 - plugin.json 版本 0.2.1 → 0.2.2 --- plugins/deta/.codex-plugin/plugin.json | 2 +- plugins/deta/README.md | 58 +++++++++++++++++++++++ plugins/deta/skills/aml-design/SKILL.md | 63 ++++++++++++++++++++----- 3 files changed, 110 insertions(+), 13 deletions(-) diff --git a/plugins/deta/.codex-plugin/plugin.json b/plugins/deta/.codex-plugin/plugin.json index fd2a4a8..f952917 100644 --- a/plugins/deta/.codex-plugin/plugin.json +++ b/plugins/deta/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "deta", - "version": "0.2.1", + "version": "0.2.2", "description": "DETA \u5efa\u7b51\u6027\u80fd\u8bbe\u8ba1\u63d2\u4ef6\uff1a\u4ee5 AML \u4e3a\u552f\u4e00\u4e8b\u5b9e\u6e90\u7f16\u8f91\u5efa\u7b51\u6a21\u578b\uff0c\u7ecf GSA \u7f16\u8bd1\u4e3a\u5efa\u7b51\u6a21\u578b\u5e76\u505a\u89c4\u5219\u6821\u9a8c\u3002", "author": { "name": "DETA", diff --git a/plugins/deta/README.md b/plugins/deta/README.md index 558e477..f797fdf 100644 --- a/plugins/deta/README.md +++ b/plugins/deta/README.md @@ -24,6 +24,64 @@ DETA 领域能力（AML 建筑模型读写、编译校验、围护结构统计 账号的工作区在服务端按账号隔离（`<工作区根>/<账号 ID>`）， 不同账号的设计源码互不可见；同一账号的新会话继续使用自己的工作区。 +## 工具面：编辑归宿主，MCP 只做引擎与同步 + +AML 是纯文本 DSL，读写、搜索、重构一律由**宿主原生的文件工具**完成 +（Codex 的 read / patch / grep、shell；dsh 的同名能力），MCP 不再是编辑入口： + +| 分工 | 谁做 | +|------|------| +| 读取 / 修改 / 搜索 `aml.xml`、`bss.md`、`rules.yml`、`behaviors.yml`、`design-brief.md` | 宿主原生工具（本地项目目录里的文件） | +| 编译、规范校验、规则检查、围护结构统计、空间邻接、领域脚本 | MCP 引擎工具（`apply_design` / `validate_model` / `analyze_gsa_issues` / `analyze_rules_compliance` / `envelope_stats` / `query_spatial_graph` / `run_script` …） | +| 本地改动送上云端、取回云端工作区 | MCP `push_project` / `pull_project` | + +远程 HTTP 形态的工具面按部署形态裁剪：编辑类工具 +（`read_source` / `edit_source` / `list_workspace` / `search_workspace` / `workspace_diff` +等依赖宿主 AML、工作区文件清单、画布或计算回调的工具）**不出现在 `tools/list`**； +引擎类工具与 `push_project` / `pull_project` 保留。本机 stdio 开发形态仍是全量面 +（`DETA_TOOL_SURFACE=full`，缺省即 full；远程形态缺省 engine，可用同名环境变量覆盖）。 + +## 本地项目目录约定 + +一个 DETA 项目就是一个普通目录，引擎工具读的是**服务端工作区**，因此改动要先 push： + +``` +my-project/ +├── deta.json # 可选：项目绑定（{ "projectId": "...", "name": "..." }） +├── aml.xml # 必需：建筑模型唯一事实源 +├── bss.md # 可选：样式/构造附属文档 +├── rules.yml # 可选：校验规则 +├── behaviors.yml # 可选：声明式行为规则 +└── design-brief.md # 可选：设计任务书 +``` + +- `deta.json` 里的 `projectId` 是 deta.city 云项目 ID；带上它的 `push_project` + 会把同一个 ID 绑定到服务端工作区（写 `deta.json`），之后 `generate_aml` / + `pull_project` 会带上同一个 Studio 深链 `https://deta.city/design/`。 +- 文件名沿用服务端约定（`aml` ↔ `aml.xml`、`brief` ↔ `design-brief.md` 等）， + 本地目录与服务端工作区结构一致，`pull_project` 的结果可直接落盘回本地目录。 + +## 端到端工作流：本地编辑 → push → 校验 → Studio 查看 + +```text +1. 本地编辑 read/patch/grep 直接改 aml.xml（MCP 不参与编辑） +2. 推送 push_project({ files: { "aml.xml": "<全文>", "rules.yml": "…" }, + projectId: "<云项目 ID>" }) + → { ok: true, files: ["aml.xml", "rules.yml"], + projectId: "<云项目 ID>", studioUrl: "https://deta.city/design/" } + （带 projectId 时同时在服务端工作区写入 deta.json 绑定） +3. 引擎校验 apply_design() → 编译 AML 为建筑模型（服务端工作区内的最新版本） + validate_model() → 语法/几何问题，逐条修复后重新 push + 编译 + envelope_stats() / query_spatial_graph() → 围护结构与空间邻接 +4. Studio 查看 打开返回的 studioUrl；已有相同 URL 的标签优先复用， + 不要为同一项目重复开新标签 +5. 反向核对 pull_project({ projectId }) → { files, projectId, studioUrl } + （工作区为空时 files 为 {}） +``` + +路径安全：`push_project` 只接受工作区相对路径，绝对路径与 `..` 穿越会被拒绝， +单次载荷上限 1 MiB（与请求体上限一致）。 + ## 安装与登录（Codex） ```bash diff --git a/plugins/deta/skills/aml-design/SKILL.md b/plugins/deta/skills/aml-design/SKILL.md index cf78a02..e8823eb 100644 --- a/plugins/deta/skills/aml-design/SKILL.md +++ b/plugins/deta/skills/aml-design/SKILL.md @@ -10,12 +10,46 @@ description: 以 AML 为唯一事实源读写建筑模型并编译校验。当 用户提到建筑方案、房间/空间布局、层高、墙体开洞（门窗）、围护结构、体形系数、 建筑模型校验，或需要为后续能耗/日照/CFD 模拟准备模型时使用本技能。 +## 编辑与校验分工（MCP 是引擎，不是编辑器） + +远程 MCP 服务只暴露**引擎**能力：编译、规范校验、规则检查、围护结构统计、 +空间邻接，以及 push/pull 同步。编辑类工具（`read_source` / `edit_source` / +`list_workspace` / `search_workspace` / `workspace_diff` 等）不在远程工具面里—— +看不到就不要去找，更不要用它们替代宿主的文件工具。 + +| 要做的事 | 用什么 | +|----------|--------| +| 读取 / 修改 / 搜索 AML 与其它设计源文件（`aml.xml`、`bss.md`、`rules.yml`、`behaviors.yml`、`design-brief.md`） | **宿主原生工具**：read / patch / grep / shell（直接改文件，不走 MCP 编辑工具） | +| 云端编译（AML → building.json） | MCP `apply_design` | +| 语法与几何校验 / 规则检查 | MCP `validate_model`、`analyze_gsa_issues`、`analyze_rules_compliance` | +| 围护结构统计 | MCP `envelope_stats` | +| 空间邻接、交通空间合并 | MCP `query_spatial_graph`、`apply_design(merge_traffic_spaces=…)` | +| 领域脚本（面积预算 / 轴网 / 布局建议 / 校核） | MCP `run_script`、`run_scripts` | +| 把本地改动送上云端、取回云端工作区 | MCP `push_project`、`pull_project` | +| 语法规则与生成上下文 | MCP `get_aml_schema`、`generate_aml` | + +固定顺序：**本地编辑 → `push_project` → 引擎校验 → Studio 查看**。 +引擎工具读的是**服务端工作区**的文件，没推送过就读不到你的最新改动—— +改完不 push 直接校验，校验结果对应的是上一版。 + +### push 与 Studio 深链 + +- 需要云端校验、或想在 Studio 里看效果时，先 + `push_project({ files: { "aml.xml": "<全文>", "rules.yml": "…" }, projectId?: "…" })`。 + `files` 至少含 `aml.xml`；路径必须是工作区相对路径（绝对路径、`..` 穿越会被拒绝）； + 单次载荷上限 1 MiB。传 `projectId` 会同时把本项目绑定到云项目 + （写入服务端工作区 `deta.json`，之后 `generate_aml` / `pull_project` 也带同一深链）。 +- 返回的 `studioUrl`（`https://deta.city/design/`）：**用内置浏览器打开， + 已有相同 URL 的标签优先复用，不要重复开新标签**。 +- 反向核对 / 拉回云端工作区用 `pull_project`（返回 `{ files, projectId?, studioUrl? }`， + 工作区为空时 `files` 为 `{}`）。 + ## 铁律 1. **AML 是建筑语义的唯一事实源**。任何几何或属性变更都必须落到 AML 文本， 不得用中间 JSON 表达修改意图。 2. **禁止凭记忆编写 AML 结构**。动手前必须先取真实语法： - - 已有模型：`read_source`（读当前 AML） + - 已有模型：用宿主原生 read 工具读项目里的 `aml.xml`（远程形态没有 `read_source`） - 语法规则：`get_aml_schema`（从编译服务实时获取，唯一权威） 3. **属性知识不硬编码**：房间用途、构造材料、洞口参数等可选值从工具返回中获取， 不要凭经验列举。 @@ -30,24 +64,29 @@ description: 以 AML 为唯一事实源读写建筑模型并编译校验。当 ## 标准工作流 -1. `read_source` 读取当前设计源码（`aml.xml`）。模型为空时先用 `generate_aml` - 按需求生成骨架，再用 `get_aml_schema` 核对语法。 -2. 编辑：直接修改 AML 文本（工作区文件的 edit/write），或使用领域工具。 -3. `apply_design` 提交编译 → 编译为建筑模型，产物落盘 `building.json`。 -4. `validate_model` 做语法与规则校验，逐条读取错误码并修复，不得跳过。 -5. 需要几何指标时用 `envelope_stats`（围护结构/外窗面积）或 `query_spatial_graph` - （空间邻接与查询）。 +1. **读**：用宿主原生工具读本地项目里的设计源码（`aml.xml` 等）。模型为空时先用 + `generate_aml` 取生成上下文，再用 `get_aml_schema` 核对语法，然后在本地写出 AML。 +2. **改**：在本地用 read / patch / grep 直接改 AML 文本（局部修改优于整体重写）。 +3. **推**：`push_project({ files: { "aml.xml": … } })` 把改好的源码送到服务端工作区 + （要绑云项目就带上 `projectId`）。 +4. **编**：`apply_design` 提交编译 → 编译为建筑模型，产物落盘 `building.json`。 +5. **校**：`validate_model` 做语法与规则校验，逐条读取错误码并修复，不得跳过； + 规则类问题用 `analyze_gsa_issues` / `analyze_rules_compliance`。 +6. **看**：需要几何指标用 `envelope_stats`（围护结构/外窗面积）或 `query_spatial_graph` + （空间邻接与查询）；要在浏览器看效果就用返回的 `studioUrl`（复用已有标签）。 ## 错误处理 - 编译服务未在线时，编译/校验类工具会返回明确错误文本。此时**不要伪造结果**， - 直接报告「编译服务未接入」，只使用可离线工作的读写类工具。 + 直接报告「编译服务未接入」，改用宿主原生文件工具（read / patch）核对与编辑本地 AML。 - 编译报错必须逐条修复后重新 `apply_design`，禁止在报错状态下声称完成。 ## 工具一览 -设计源码：`read_source`、`edit_source`、`get_design_params`、`read_reference`、`run_script` +设计源码读写/搜索：**宿主原生工具**（read / patch / grep / shell），不经 MCP 生成与语法：`generate_aml`、`get_aml_schema` 编译与校验：`apply_design`、`validate_model`、`envelope_stats`、`query_spatial_graph`、 -`generate_candidates` -项目与计算：`list_projects`、`list_buildings`、`analyze_building`、`parameter_sweep` +`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`