Files

T

ringo 71a31dc112 feat(plugin): 技能改写为「编辑归宿主、MCP 只做引擎与同步」（v0.2.2）

- SKILL.md 新增「编辑与校验分工」：AML 与设计源文件用宿主原生 read/patch/grep 编辑，
  编译/规范校验/规则检查/围护统计/空间邻接走 MCP 引擎工具；固定顺序
  本地编辑 → push_project → 引擎校验 → Studio 查看；studioUrl 用内置浏览器打开且复用已有标签
- README 新增「工具面」说明、本地项目目录约定（可选 deta.json 绑定 projectId）
  与端到端工作流示例
- plugin.json 版本 0.2.1 → 0.2.2

2026-09-10 13:29:33 +08:00

6.0 KiB

Raw Blame History

name, description

name	description
aml-design	以 AML 为唯一事实源读写建筑模型并编译校验。当用户要求创建/修改建筑方案、房间布局、层高、开洞、围护结构或做建筑性能相关的模型准备时使用。

DETA 建筑性能设计（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/<projectId>）：用内置浏览器打开，已有相同 URL 的标签优先复用，不要重复开新标签。
反向核对 / 拉回云端工作区用 pull_project（返回 { files, projectId?, studioUrl? }，工作区为空时 files 为 {}）。

铁律

AML 是建筑语义的唯一事实源。任何几何或属性变更都必须落到 AML 文本，不得用中间 JSON 表达修改意图。
禁止凭记忆编写 AML 结构。动手前必须先取真实语法：
- 已有模型：用宿主原生 read 工具读项目里的 aml.xml（远程形态没有 read_source）
- 语法规则：get_aml_schema（从编译服务实时获取，唯一权威）
属性知识不硬编码：房间用途、构造材料、洞口参数等可选值从工具返回中获取，不要凭经验列举。
局部修改优于整体重写：改单个空间属性时只改该空间，不重写整个模型。
控制单会话工具调用量。编码代理在会话累积较多本插件工具调用后，会在请求里重复声明 deta 命名空间，上游模型服务（Responses 兼容层）直接拒绝： Duplicate namespace name 'deta'; Namespace names must be unique。实测触发点随会话长度前移（并发调用会显著提前触发）。规程：
- 同一轮只调用一个本插件工具，不要并发；
- 单会话保持轻量，完成任务后另起会话继续；
- 一旦出现该错误，停止重试并告知用户重开会话（工作区文件不会丢失）。

标准工作流

读：用宿主原生工具读本地项目里的设计源码（aml.xml 等）。模型为空时先用 generate_aml 取生成上下文，再用 get_aml_schema 核对语法，然后在本地写出 AML。
改：在本地用 read / patch / grep 直接改 AML 文本（局部修改优于整体重写）。
推：push_project({ files: { "aml.xml": … } }) 把改好的源码送到服务端工作区（要绑云项目就带上 projectId）。
编：apply_design 提交编译 → 编译为建筑模型，产物落盘 building.json。
校：validate_model 做语法与规则校验，逐条读取错误码并修复，不得跳过；规则类问题用 analyze_gsa_issues / analyze_rules_compliance。
看：需要几何指标用 envelope_stats（围护结构/外窗面积）或 query_spatial_graph （空间邻接与查询）；要在浏览器看效果就用返回的 studioUrl（复用已有标签）。

错误处理

编译服务未在线时，编译/校验类工具会返回明确错误文本。此时不要伪造结果，直接报告「编译服务未接入」，改用宿主原生文件工具（read / patch）核对与编辑本地 AML。
编译报错必须逐条修复后重新 apply_design，禁止在报错状态下声称完成。

工具一览

设计源码读写/搜索：宿主原生工具（read / patch / grep / shell），不经 MCP 生成与语法：generate_aml、get_aml_schema 编译与校验：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

6.0 KiB Raw Blame History Unescape Escape