diff --git a/connectors/deta/README.md b/connectors/deta/README.md new file mode 100644 index 0000000..fb38e5b --- /dev/null +++ b/connectors/deta/README.md @@ -0,0 +1,26 @@ +# DETA WorkBuddy 连接器 + +WorkBuddy 官方连接器格式（open.workbuddy.cn/docs/connector）：远程 streamableHttp MCP + 标准 OAuth。 + +## 结构 + +``` +connectors/deta/ +├── connector-meta.json # 元信息（source=deta，对应 OAuth 回调 workbuddy://…/connector%3Adeta/…） +├── mcp.json # 远程 MCP：deta.city/mcp-api/mcp，timeout 120s（长模拟） +├── icon.svg +└── skills/ # aml-design + report-authoring +``` + +## 认证 + +零配置：WB 连接时经 `401 + WWW-Authenticate` 发现 OAuth（deta.city 授权服务，PKCE S256， +DCR 动态注册回显 redirect_uris，access 24h / refresh 90 天），浏览器点一次授权，之后自动续期。 + +## 手动验证（上架前） + +WB → Settings → MCP → Add MCP Server → 填 `https://deta.city/mcp-api/mcp`， +类型 streamableHttp，保存后应自动弹浏览器授权；授权完成工具面出现即通。 + +> 注意：若本机还装有旧的本机 stdio 条目（~/.workbuddy/mcp.json 的 deta_studio）， +> 验证远程形态时先把它停用，避免双工具面。 diff --git a/connectors/deta/connector-meta.json b/connectors/deta/connector-meta.json new file mode 100644 index 0000000..9319310 --- /dev/null +++ b/connectors/deta/connector-meta.json @@ -0,0 +1,24 @@ +{ + "name": "DETA", + "name_zh": "DETA 建筑设计", + "name_en": "DETA Building Design", + "source": "deta", + "type": "mcp", + "version": "0.1.0", + "minWorkbuddyVersion": "4.24.0", + "description": "在 WorkBuddy 里完成建筑方案设计、模型编译校验与性能模拟。", + "description_zh": "用自然语言做建筑方案：生成候选平面、编译校验模型、能耗/采光/通风模拟，结果可在 DETA Studio 中三维查看。", + "description_en": "Design buildings in natural language: generate floor-plan candidates, compile and validate models, run energy/daylight/CFD simulations, and review results in DETA Studio.", + "examples_zh": [ + "新建一个办公楼项目并在 Studio 里打开", + "为 120 平米三居室生成几个户型候选方案", + "编译当前设计并列出需要修复的问题", + "对当前楼栋跑一次能耗模拟" + ], + "examples_en": [ + "Create an office building project and open it in Studio", + "Generate floor-plan candidates for a 120 m² three-bedroom unit", + "Compile the current design and list issues to fix", + "Run an energy simulation on the current building" + ] +} diff --git a/connectors/deta/icon.svg b/connectors/deta/icon.svg new file mode 100644 index 0000000..82c97ed --- /dev/null +++ b/connectors/deta/icon.svg @@ -0,0 +1,3 @@ + + + diff --git a/connectors/deta/mcp.json b/connectors/deta/mcp.json new file mode 100644 index 0000000..4ecba2c --- /dev/null +++ b/connectors/deta/mcp.json @@ -0,0 +1,9 @@ +{ + "mcpServers": { + "deta": { + "type": "streamableHttp", + "url": "https://deta.city/mcp-api/mcp", + "timeout": 120000 + } + } +} diff --git a/connectors/deta/skills/aml-design/SKILL.md b/connectors/deta/skills/aml-design/SKILL.md new file mode 100644 index 0000000..037b501 --- /dev/null +++ b/connectors/deta/skills/aml-design/SKILL.md @@ -0,0 +1,293 @@ +--- +name: aml-design +description: 以 AML 为唯一事实源读写建筑模型并编译校验；含设计流程决策闸门、阶段准入门槛与 GSA 端口口径。当用户要求创建/修改建筑方案、房间布局、层高、开洞、围护结构或做建筑性能相关的模型准备时使用。 +--- + +# DETA 建筑性能设计（AML） + +## ★ 先读：工具怎么找、模型怎么改（任意工作目录都适用） + +**工具发现规则（重要）**：宿主对插件类 MCP 工具做**懒加载检索**，一次检索只返回少量结果 +（实测 `Only 10 shown of 23`）。**搜不到不等于不存在**——不确定有哪些工具时，先调 +**`list_capabilities`**（能力目录）拿到当前形态的**完整工具名清单**，再按名字**直接调用**。 + +**改建筑模型只有一个标准动作**（能力目录里有 `build_model` 时）： + + `build_model({ aml, projectId })` —— 写服务端工作区 → 编译成建筑模型 → 规范校验 → 写进云项目， + 一次调用完成；返回 `gate`（校验是否通过）、编译摘要、校验明细、云工作区 `headSha`。 + + - **不要**把 AML 拷进 Studio 的代码编辑器手工点编译（那是没有闭环工具时的兜底，不是正常路径）； + - **不要**用脚本自绘模型图代替 Studio； + - 校验不通过（`gate: failed`）就按 `validation` 明细改 AML 后重跑，直到通过； + - 冲突（`version_conflict`）说明云工作区被其它会话改过：确认要覆盖才传 `force: true`。 + +**看模型 / 打开 Studio**：`open_studio` 拿一次性免密链接，再用宿主内置浏览器（`iab`）打开—— +不要手工在面板登录，也不要用 playwright 逐步点击。 + +**执行器在线是模拟类工具的前置条件**：`simulate` / `studio_command` / `query_simulation_db` / +`view_canvas` 的算力在 ant-model 浏览器里的执行器，经网关 host-call 中继干活；项目标签页一关 +就离线，工具会 fail fast 报「执行器离线」。`open_studio` 会回报 `executor_online`，遇到离线提示 +就再调一次它，不要改用手工登录。 + +## 何时使用 + +用户提到建筑方案、房间/空间布局、层高、墙体开洞（门窗）、围护结构、体形系数、 +建筑模型校验，或需要为后续能耗/日照/CFD 模拟准备模型时使用本技能。 + +## ★ 领域知识必须先加载（read_reference），不要凭记忆写设计 + +本技能只讲**工具怎么用、流程怎么走**；建筑设计本身的领域知识在其他文档里，**动手前按需读**： + +| 文档 | 什么时候必读 | +|:-----|:-------------| +| `workflow-stages` | **任何设计任务开始**：决策闸门 D0–D8 全套定义、三阶段流水线、脚本依赖链、用户确认点 | +| `tracks-and-gsa` | 搞不清「哪份文件是真值 / 该调哪个端口」时：设计源码四轨关系 + GSA 端口清单 | +| `dote-and-space` | 写 dote-bounds、切分房间、非正交轴网、场地红线前 | +| `combination-forms` | 排平面（户型/办公组合形式）前 | +| `candidate-generation` | 走 `generate_candidates` 前（顶层 program 构造、四步比选） | +| `door-placement` | 门窗阶段写任何 `` 前 | +| `editing-strategy` | 改已有 AML 时 | +| `unit-design` / `building-design` | 住宅单户 / 整栋（`skill_name: "residential-design"`） | +| `core-detail` / `dimensions` | 办公核心筒 / 尺寸（`skill_name: "office-design"`） | + +调用方式：`read_reference({ name: "workflow-stages" })`；`skill_name` 缺省全局搜索（同名多命中会全部返回）。 +**语法与属性拼写一律以 `get_aml_schema` 为准**（GSA 实时获取），领域规则读上面的文档——两者都不是"凭经验列举"。 + +## 设计流程：三阶段 + 决策闸门（谁决定什么） + +``` +SITE 约束确认(D0) → 形态/楼型(D1) → 场地轴网方案 → 落 AML +MASSING 面积分配(D2) → 核心筒(D3) → 结构/网格(D6) → 动线骨架(D4) → 交通骨架 → 分区块(D5) → 房间填充(D7) → 编译 massing +STRUCTURE 按动线落 flows → 核心筒细化 → 编译 structure +FULL 门窗(D8) → 品质优化 → 编译 full → 交付 +``` + +**必须让用户决策的节点**（一律用 `ask_user`，每题给 2–5 个具体方案 + 推荐度，**带 `gate` 字段标注闸门号**）： + +``` +D0 需求/约束 D1 形态/楼型 D2 面积分配 D3 核心筒策略 D4 动线骨架 +D5 分区/房间优先级 D6 结构选型/网格 D7 房间填充方案 D8 门窗方案 +``` + +- **决策前置**：改动线 = 重排全平面，所以 D1–D4 必须在排房间之前定下来。 +- **禁止替用户做这些决策**；也禁止用「是否合理？」这类确认代替方案选择。 +- `ask_user` 有两种回执形态：宿主支持交互表单（MCP elicitation）时**用户的选择直接随工具结果返回**（`via: "elicitation"` + `answers`），据此继续即可；不支持时返回结构化回执（`_ask_user`），此时必须停止、等宿主注入用户答复（【用户决策】…）再继续。多选题无法用表单表达，会自动走回执形态。 +- D0 的结论用 `manage_design_brief`（get/set/update）落成**项目级设计任务书**：用户已明确给出的字段直接写，没给的才问；后续补充用 update 增量合并。 +- **渐进生成**：每个阶段只生成下一层所需的最小信息（交通骨架 → 分区 → 房间填充 → 细部），每步之后停下来让用户确认；**禁止一次性生成全模型再让用户确认**。 +- 阶段之间、以及阶段内每个小步之后，都要等用户确认再继续。 + +## 阶段准入门槛：什么数据齐了才能进下一阶段 + +| 进入 | 必须先有 | 判据 | +|:-----|:---------|:-----| +| 任何设计 | **设计任务书**（D0：建筑类型/定位/目标客群/场地/硬约束/偏好） | `manage_design_brief({ action: "get" })` 有内容 | +| 排房间前 | 形态(D1) + 面积方案(D2) + 核心筒(D3) + 动线(D4) 已由用户选定 | `ask_user` 答复已落闸（流程状态段可见） | +| **手写 AML 前** | **面积预算** + **楼层/轴网规划** + **布局建议** + **邻接规则** 四份脚本产出 | `generate_aml` 会拒绝对缺项的场景直接生成 | +| 编译 massing 前 | AML 含完整轴网与空间（走廊必须显式写出），**不得含门窗** | `apply_design(level=massing)` 的 `verification.verdict` | +| 进 structure 前 | massing 档 `verification.verdict=pass` | 同上（状态机自动推进缺省档，不要手动跳） | +| 进 full 前 | structure 档 `verification.verdict=pass` | 同上 | +| **声称"完成"前** | **本次会话成功编译过**（拿到 N 层 / N 房间摘要与 `verdict`） | 编译摘要；没编译过不得宣称完成、不得输出成果汇总、不得把空画布当成果 | +| 进入模拟/性能评估 | full 档编译通过 + 面板执行器在线（`open_studio` 回报 `executor_online`） | — | + +## 四轨关系与 GSA 端口（速查） + +四轨：`aml.xml`（**建筑语义唯一事实源**，必参与编译）· `bss.md`（样式）· `rules.yml`（校验规则）· `behaviors.yml`（声明式行为）——后三者可选，缺省按「工具参数 > 宿主当前源码 > skill 默认附属源码 > 兜底」回落；`design-brief.md` 是设计任务书，**不参与编译**；`` 的几何脚本必须存在于工作区（内容随编译请求携带，取不到即**显式失败**）。 + +``` +GSA 默认 http://localhost:8000 + /health GET 存活探测（编译类异常第一步） + /api/v1/compile POST AML → building.json（compile_level 决定档位与门禁） + /api/v1/schema GET 语法指南（?full=1 全文） + /api/v1/schema.json GET 单标签/分组 schema + /api/v1/aml-guide GET 话题索引（阶段/模板/behaviors/轴网） + /api/v1/validate POST AuditEngine 深查（编译已带 issues，别重复调） + /api/v1/envelope-stats POST 围护结构统计 + /api/v1/analyze-adjacency POST 空间邻接拓扑 + /api/v1/generate(+ /schema) POST/GET 规则驱动候选平面生成 +``` + +错误码**没有**独立目录端点（实测 404）：按编译/校验响应里的 `code` 处理，不要凭记忆猜。细节读 `read_reference({ name: "tracks-and-gsa" })`。 + +## 脚本怎么用（run_script / run_scripts） + +- 命名用 kebab-case（写成下划线会自动归一）；**不确定归属就不传 `skill_name`**（全局搜索）。 +- **参数不确定就直接调**：缺必填参数时回执带 `params_hint`（完整参数表：类型/必填/默认/说明），按它补齐重调即可；脚本名不存在时回执会列出可用脚本。不要猜参数，也不要写一份参数副本进 AML。 +- 依赖链由 `depends_on` 声明（如 面积预算 → 楼层/轴网规划 → 布局建议），**先跑前置**；已算过的结果在会话语境里保留（`get_design_params` 可查），不要重复跑。 +- 评估/校验统一走 `design-review`（缺省全跑、数据不足的项自动跳过并给 note）。 + +## 候选平面比选（generate_candidates） + +- **预览图会随工具结果一起回来**（宿主在对话里显示；本形态已把 `preview_svg` 栅格化成 PNG 附加在结果上）。`ask_user` 的选项卡片**协议上装不下图**（MCP 表单只允许原始类型字段），所以比选时的正确做法是：选项文字写「候选 1 / 候选 2 / 候选 3（对应上方预览图）」，让用户按序号看图选。 +- 请求契约（实测踩点）：住宅 `program.boundary` 必填，且 `wall_roles` 是**对象列表** `[{"side":"N","role":"exterior"}, …]`（矩形要覆盖 N/S/E/W 四条边；角色取 exterior / party / corridor）；不是 `{"N":"exterior"}` 这种映射。`boundary.unit_door.offset` 是 **0~1 的比例**（不是米）；入户锚定求解超时时换入户侧（如 S/N）或去掉 `unit_door` 让服务自动选门。 +- 多配方 fan-out：住宅 candidates≥2 时自动跨 slicing / learned / hybrid 三配方；某配方不可用会如实进 `unavailable_recipes`，不影响其余候选产出。生成失败时按 GSA 返回的 `param_errors` / `constraint_report` 修正，不要静默放宽参数。 + +## 编辑与校验分工（先搞清"哪份文件是真值"） + +本插件挂的是**本机 MCP**：引擎工作区才是编译/校验/模拟读的真值（启动器 stderr 会回显路径）。 +两种用法： + +- **工作区 = 项目目录**（启动宿主前设 `DETA_WORKSPACE=<项目目录>`）：宿主原生文件工具与 MCP + 工作区工具看的是同一份文件，直接改完就能编译，不需要同步步骤。 +- **工作区 ≠ 项目目录**（缺省 `~/.deta/workspace`）：本地改动要先同步进引擎工作区， + 引擎工具读到的才是最新版本。 + +编辑手段按场景选：纯文本改动优先用宿主原生文件工具（read / patch / grep）；需要按元素定向 +读写 AML（按空间 ID 改属性、只取某实体块原文）时用 MCP 的工作区工具。编译、规范校验、 +规则检查、围护结构统计、空间邻接一律走引擎工具。 +当前形态到底有哪些工具、叫什么名字，以运行时调 `list_capabilities` 的结果为准。 + +| 要做的事 | 用什么 | +|----------|--------| +| 读取 / 修改 / 搜索 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`（`checks` 一次要齐几何 + issues + rules，三类共用同一次编译） | +| 围护结构统计 | 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` | + +固定顺序（工具面里有 `build_model` 时）：**本地写 AML → `build_model` → 看 gate →（Studio 里看效果）**。 +`build_model` 一次完成「写服务端工作区 → 编译 → 校验 → 写进云项目工作区」，Studio 里立即可见。 +工具面里没有 `build_model`（部分部署形态会裁掉它）时才退化为：本地编辑 → `push_project` → `apply_design` → +`validate_model` → Studio 查看。引擎工具读的是**服务端工作区**的文件，没推送过就读不到你的最新改动。 + +**工具检索结果条数有限**：一次搜索没看到某个工具，不代表它不存在——先调 +`list_capabilities` 拿当前形态的完整工具名，再按名字直接调用。 + +### 闭环单入口 build_model + +``` +build_model({ 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 深链 + +- 需要云端校验、或想在 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/`，例：云项目 11 → `https://deta.city/design/11`）： + **在宿主右侧的内置浏览器面板打开**（做法见下一节）；已有相同 URL 的标签优先复用，不要重复开新标签。 +- 反向核对 / 拉回云端工作区用 `pull_project`（返回 `{ files, projectId?, studioUrl? }`， + 工作区为空时 `files` 为 `{}`）。 + +## 在右侧面板打开 Studio，并在其中跑模拟 + +Studio 就是deta.city 上的建筑性能应用。在宿主内置浏览器面板打开它之后， +看模型、跑模拟、看结果图层都在面板里完成；本插件的 MCP 只负责把本地改动推上去，不执行模拟。 + +打开步骤（用宿主内置浏览器 = browser 插件的 `iab`）： + +1. **先调 `open_studio` 拿链接并确认执行器上线**（免手工登录）。返回 `url` + （`https://deta.city/mcp-api/portal-session/landing?ticket=…&next=/design/`）、 + `studioUrl`、`executor_online`、`expiresInSeconds`（180）。该链接在面板内会自动完成 + deta.city 登录并跳到 Studio。 + - 典型节奏：`open_studio()` 拿 `url` → 面板打开 → `open_studio({ waitSeconds: 20 })` + 确认 `executor_online: true` → 再调 `simulate` / `studio_command` 等执行器侧工具。 + - 若返回 `auth_required` → 未登录：**直接调 `login` 工具**（建议 `waitSeconds: 90`），把返回的 `url` + 交给用户在内置浏览器打开——首次输一次账号密码或邮箱验证码，之后只需点「登录并授权」按钮。 + **不需要终端，也不要去找宿主自己的 MCP 登录命令**；用户点完后本工具会自动换取令牌并写入当前会话 + （凭据过期时 `login` 会先用 refresh token 静默续期，用户完全无感）。 + 仅当当前形态没有 `login` 工具（CLI 等）时，才让用户在终端运行 `~/.deta/bin/deta login`； + 排查用 `~/.deta/bin/deta doctor`（自检运行时 / 凭据 / GSA / MCP 握手）。 + 若 `url` 报「票据无效或已过期」→ 重新调一次，不要改成手工登录。 +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(url);` +4. 打开后告诉用户「Studio 已在右侧面板打开（项目名/ID）」，并说明模拟在面板里运行。 + +旧路径（工具面里没有 `open_studio` 时）：自己拼 `studioUrl` +（本机项目目录 `deta.json` 的 `projectId`，或 `push_project(…, projectId)` 的返回值， +形如 `https://deta.city/design/`），按上面第 2–4 步打开——但需面板已登录。 + +在面板里跑模拟： + +- 模拟入口在 Studio 界面内（分析/模拟面板、GH 模板等）。**默认交给用户在面板里操作**—— + 模拟参数与结果解读属设计决策，不要代替用户点。 +- 用户明确要你代跑时：先 `await tab.ax.write()` 取当前界面元素，再 `await tab.ax.click(<元素序号>)` + 逐步操作；每一步后重新取一次状态确认，**不要凭记忆点坐标**。 +- 结果出来后用 `await tab.ax.write("both")` 或 `await tab.screenshot()` 确认图层与数值，再向用户汇报。 + +前置与故障： + +- 面板未登录 deta.city：用 `open_studio` 的一次性链接即可免手工登录（见上）；只有拿不到 + `open_studio` 时才退化为手工：在面板里打开 `https://deta.city/login` 完成一次登录 + （登录态写入该浏览器的 `ant_token` cookie 与 `ant-model-auth` localStorage，之后长期有效）， + 登录完成后重新打开 `studioUrl` 即自动加载项目。 +- **本机形态没有 MCP 授权**（进程在本机由宿主拉起，无 OAuth、无 401、无令牌续期），要分清的是两件事： + - **MCP 侧的云令牌**：只影响项目列表 / 项目同步 / `open_studio` 这类云工具，`auth_required` 的处置见上； + - **面板侧的 deta.city 登录**：靠 `open_studio` 的一次性链接自动完成，登录态写在该浏览器的 + `ant_token` cookie 与 `ant-model-auth` localStorage，之后长期有效。 + 两者互不替代——拿到云令牌不等于面板已登录，反之亦然。 +- 没有 `projectId`（用户要"新建项目"）：**先调 `create_project({ name })`** ——这是云端建项目的唯一工具入口， + 返回 `projectId` 与 Studio 深链（`studioUrl`）；随后用 `build_model`（写 AML → 编译 → 写入云项目工作区） + 或 `push_project(…, projectId)` 把模型放进去。**不要**拿 `push_project` 去绑定一个不存在的 ID， + 也不要让用户先去门户手工建项目。 +- 宿主没有内置浏览器（CLI 等形态）：直接把 `studioUrl` 给用户，让他自己打开，不要假装已经打开。 + +## 铁律 + +1. **AML 是建筑语义的唯一事实源**。任何几何或属性变更都必须落到 AML 文本， + 不得用中间 JSON 表达修改意图。 +2. **禁止凭记忆编写 AML 结构**。动手前必须先取真实语法： + - 已有模型：读工作区里的 `aml.xml`（宿主原生 read 工具，或 MCP 的 `read_source`） + - 语法规则：`get_aml_schema`（从编译服务实时获取，唯一权威） +3. **属性知识不硬编码**：房间用途、构造材料、洞口参数等可选值从工具返回中获取， + 不要凭经验列举。 +4. **局部修改优于整体重写**：改单个空间属性时只改该空间，不重写整个模型。 +5. **控制单会话工具调用量**。编码代理在会话累积较多本插件工具调用后，会在请求里重复 + 声明 `deta` 命名空间，上游模型服务（Responses 兼容层）直接拒绝： + `Duplicate namespace name 'deta'; Namespace names must be unique`。 + 实测触发点随会话长度前移（并发调用会显著提前触发）。规程： + - 同一轮只调用一个本插件工具，不要并发； + - 单会话保持轻量，完成任务后另起会话继续； + - 一旦出现该错误，**停止重试并告知用户重开会话**（工作区文件不会丢失）。 +6. **复杂形体（``）的脚本属于工作区文件，不是宿主本地文件**。 + 编译服务没有工作区访问权：编译前引擎会按 AML 声明的相对路径把脚本内容**随请求携带** + （键名必须与 AML 一字不差，含 `geometry/` 前缀）。因此： + - 脚本必须真实存在于**工作区**（用工作区文件工具读写，如 `geometry/shapes.py`）； + - 脚本取不到时编译会**显式失败并列出原因**（而不是"编译通过但形体丢失"）； + - 改动脚本内容后无需重命名或改 AML；若 AML 里写了 `version="sha256:…"`，脚本内容变了 + 必须同步更新该版本号，否则编译报「几何脚本版本不匹配」。 + +## 标准工作流 + +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` 做语法与规则校验，逐条读取错误码并修复，不得跳过； + 规则类问题用 `validate_model({ checks: ['issues','rules'] })` 一次查齐（info 级提示只在 issues 视图可见）。 +6. **看**：需要几何指标用 `envelope_stats`（围护结构/外窗面积）或 `query_spatial_graph` + （空间邻接与查询）；要看模型、**跑模拟**、看结果图层，就在右侧面板打开 `studioUrl` + （见「在右侧面板打开 Studio，并在其中跑模拟」一节），模拟在 Studio 界面里运行。 + +## 错误处理 + +- 编译服务未在线时，编译/校验类工具会返回明确错误文本。此时**不要伪造结果**， + 直接报告「编译服务未接入」，改用宿主原生文件工具（read / patch）核对与编辑本地 AML。 +- 编译报错必须逐条修复后重新 `apply_design`，禁止在报错状态下声称完成。 + +## 工具名从哪来 + +本技能**不列工具清单**：工具面随部署形态（引擎形态 / 全量形态）裁剪，任何手写清单都会过期。 + +不确定有哪些工具时，调 `list_capabilities` 拿当前形态的**完整工具名**，再按名字直接调用； +每个工具能做什么、参数怎么给，以它自身的 description 与返回为准。 diff --git a/connectors/deta/skills/report-authoring/SKILL.md b/connectors/deta/skills/report-authoring/SKILL.md new file mode 100644 index 0000000..d045235 --- /dev/null +++ b/connectors/deta/skills/report-authoring/SKILL.md @@ -0,0 +1,43 @@ +--- +name: report-authoring +description: 把建筑模型与模拟结果整理成报告/文档内容。当用户要求写节能专篇、性能报告、甲方汇报材料，或需要从当前项目取指标与结论成文时使用。 +--- + +# DETA Writer —— 报告与文档产出 + +## ★ 先读：能力边界与取数顺序 + +本插件负责**产出报告内容**（文本 / Markdown / 结构化数据），不负责排版与导出： + +- **报告模板、插槽填充、docx 导出在门户 Writer 页面**（`https://deta.city/writer?doc=`）—— + 不在本插件的工具面里，不要试图用 MCP 工具生成模板或导出文件。 +- 本插件能做的是：读模型与工作区文件、取统计数据、取模拟结果、查规范指标，然后把它们写成文字。 +- 不确定当前有哪些工具时，先调 **`list_capabilities`** 拿完整工具名再按名字调用 + （检索一次只回少量结果，搜不到不等于不存在）。 + +## 取数顺序（每步都可能缺数据，缺就如实标注） + +1. **模型真值**：工作区里的 `aml.xml` / `building.json`——用宿主原生文件工具或 `read_source` 读。 +2. **围护结构统计**：外墙/外窗面积、实际窗墙比、朝向分布——用 `envelope_stats` 取，不要手算。 +3. **性能分析**：能耗、舒适度等按需用 `analyze_building`；结果里的 `executor` / `backend` 标注要照抄进报告。 +4. **模拟结果缓存**：已跑过的采光/日照/通风等结果用 `query_simulation_db` 查，避免重复跑。 +5. **气象**：需要气候分区/月均/极值数据时先 `load_weather` 加载气象文件，再取结果。 +6. **规范与指标**：阈值、限值、技术策略必须用 `query_knowledge` 取原值，不得凭经验写数。 + +## 铁律 + +1. **不编造数值**。任何数字要么来自工具返回、要么来自工作区文件；没有就写 `--` 或删掉那句话， + 不要用"约/大约/典型值"填空。 +2. **区分设计值与限值**。设计值由模型算出；限值来自规范条文，缺失时留空并标注"待补规范限值"。 +3. **标注数据来源与执行位置**。同一指标可能来自本机引擎或 Studio 执行器，按工具返回的标注如实写。 +4. **写报告是只读过程**。不要顺手改模型；确需修正时明确告知用户并单独确认。 +5. **控制单会话工具调用量**。写报告是长流程，撞到命名空间重复类错误时不要重试，另起会话继续 + （工作区文件不会丢）。 + +## 标准工作流 + +1. 确认写什么：报告类型、范围（整栋/单栋/单专业）、读者（甲方/评审/内部）。 +2. 列"能写什么、缺什么"两栏，**先把缺项告诉用户**，不要写到一半才发现没数据。 +3. 按取数顺序补齐数据（能算的算、能查的查）。 +4. 成文：分章节写入工作区（Markdown），每段数据标注来源指标名；缺项如实留空。 +5. 交回用户：说明哪些章节已完稿、哪些等数据；需要在门户导出 docx 时给出 Writer 页面链接。