@pioneer_zmc/dsh-workbench 0.2.1

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@pioneer_zmc/dsh-workbench",
+  "version": "0.2.1",
+  "license": "MIT",
+  "type": "module",
+  "description": "SpecDev 工作台：浏览业务说明、流程图、建筑与独立房间，按 Git 附注标签阅读和登记历史版本；插件页面唯一写操作是给提交挂附注标签，不改业务项目的文件、分支与提交。",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./client": "./client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "web",
+    "vendor",
+    "skills",
+    "client.js",
+    "cordis.patch.yml",
+    "README.zh.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-sidebar"
+      ]
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "node scripts/build.mjs",
+    "pack:tgz": "npm run typecheck && npm run build && npm pack --pack-destination ."
+  },
+  "devDependencies": {
+    "@types/node": "26.5.1",
+    "esbuild": "0.28.2",
+    "typescript": "7.0.2"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pioneer666-user/specdev-workbench.git"
+  },
+  "homepage": "https://github.com/pioneer666-user/specdev-workbench#readme",
+  "bugs": {
+    "url": "https://github.com/pioneer666-user/specdev-workbench/issues"
+  }
+}

package/skills/specdev-building/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: specdev-building
+description: 在需要为某个已有 SpecDev 业务清单的项目生成或重建数字房蓝图时使用：读 docs/specdev 的项目与全部业务，按已有四种户型为每个业务安排房间，写出唯一的 docs/specdev/building.json，再用建筑诊断命令行逐项修正后交作者进房验收。也用于按作者要求调整项目级整栋 building.json 的房间数量、尺寸或户型；独立房间、家具及 room.json 用 specdev-room。写业务规格文档、workflow 图与节点详情用 specdev-business；业务关系（管道）、源码逆向推断业务、发明新房型、替作者决定业务取舍或面积分档都不在本技能范围。纯讨论、普通问答和只读审查不触发本技能。
+---
+
+# SpecDev Building（建筑布置）
+
+把**项目清单**变成**一栋能走进去的房子**：产出唯一一个文件 `docs/specdev/building.json`（建筑蓝图）。本文件是入口，只管顺序、纪律和交付边界；字段、户型算术、诊断修法在各参考文件里，按需读取，不在此重复。
+
+房子的内容（项目名、业务名、业务介绍、资料目录、门牌上的字）**不写在蓝图里**——由插件从项目清单注入。蓝图只安排空间：楼层、房间、门窗、楼梯、屋顶、入口。
+
+## 适用范围
+
+- **用本技能**：为已有 `docs/specdev/project.json` 与业务目录的项目建房，或按作者要求调整已有项目级整栋 building.json（加/减房间、改尺寸、换户型）；独立房间底座选择、家具布置和 room.json 交 specdev-room。
+- **不做的**：业务关系与管道界面；读源码推断业务重要性；发明样板之外的新户型；替作者决定业务取舍（哪个业务该在清单里）与面积分档；补清单缺件（缺 `project.json`／`business.json` 指向 `specdev-business` 或作者）；改插件代码与生成器。
+- **纯讨论交方案**：作者问"有没有办法／有什么建议"时交付方案，不动手。
+
+## 唯一产物与边界
+
+1. 只写 `docs/specdev/building.json` 一个文件，不新建、不改动清单里的任何其它文件。
+2. **改已有蓝图按授权走**：作者已经明确要求加房、改尺寸或换户型时，按授权范围直接改，并在报告里写明改了哪几处；**没有**这类明确要求而要重建或覆盖别人的蓝图时，先给方案等作者裁决。
+3. 蓝图里不写项目名、业务名、介绍、资料路径——那是清单的事，写进来只会与清单打架。
+4. 不代作者声明实现状态：`implementation: present`、`tests: passed`、`acceptance: passed` 都要有真实出处，否则留默认（样板的 `construction` 块就是安全默认）。
+
+## 主流程（按序执行）
+
+1. **确认目标**：项目仓库根（必须是 Git 仓库顶层）与分支状态。工作区标识不是开工前置，也**不是本技能能自己查到的信息**（它只出现在作者从 DSH 侧栏进管理页的链接里），只在交付页面入口时用到，见"交付报告"第 5 条。
+2. **勘察清单**：读 `docs/specdev/project.json` 和每个 `docs/specdev/<业务>/business.json`，列出「业务 id／名称／一句话职责／资料数（文档 × 图）」。
+   - **资料数怎么数**（与插件清单同一口径，不要另立数法）：**文档数**＝该业务 `business.json` 的 `docs` 数组里非空字符串的条数；**图数**＝该业务目录下的**子目录个数**（目录名就是图编号，`chart.json` 缺失或坏也照样算一张，只是诊断会另报 `MATERIAL_UNREADABLE`）。全部业务的「文档＋图」之和＝诊断输出里的「资料入口 N 条」，拿它对数。
+   - 清单缺件、`business.json` 坏、业务目录名含中文或其它写不进蓝图的字符（**业务 id 就是业务目录名**，而蓝图的 `businessId` 只接受 `^[A-Za-z0-9][A-Za-z0-9._-]*$`）→ **停下报告**，不自己补、不自造业务 id。
+3. **定户型**：按下方选型规则挑一份样板，说明理由（作者可否决）。
+4. **出设计表**：业务 → 房间 id → 面积档 → 所在层。房间 id 由业务 id **归一化**得到（转小写、`.`／`_` 换成 `-`、加 `room-` 前缀）；**不要直接拿 `businessId` 当房间 id**（业务 id 允许大写和点，蓝图 id 不允许）；归一化后若重名（如 `a.b` 与 `a-b`）就在后一个上加 `-2`／`-3`，保证全文件唯一。房间排列用**清单顺序**＝`docs/specdev/` 下业务目录名的字典序（`row` 一族从西到东、`tower` 按它分层），作者另有指定时从作者并在报告里写明。**面积档只写在报告里**——蓝图没有档位字段，档位不落盘。
+5. **写蓝图**：以样板为骨架，照抄结构、按递推表改数量与坐标（见 [layouts.md](references/layouts.md)）。风格取下方选型表的"风格"列；`defaults`／`prototype`／`wallType`／`accent` 这些可选字段**默认不写**——省略就是取契约里的缺省值，**显式写出与缺省相同的值才是等价的**；**改值就会改几何**（墙厚、楼板厚参与构件尺寸与楼层净空，门高参与门洞与漫游落点），别凭空填（取值范围见 [blueprint-contract.md](references/blueprint-contract.md)）。字段与取值按契约核对一遍再落盘。
+6. **跑诊断**，按码逐项修：
+   ```
+   node "<插件包根>/dist/check-building.js" <项目仓库根>
+   ```
+   退出码 `0` 通过（可含 warning）、`1` 有 error、`2` 读不了。每条 error 都带 `subject.path` 与「修复方向」；按 [diagnostics.md](references/diagnostics.md) 改，**一轮只修一类**，改完用同一条命令重跑。**同一问题两轮修不成**：停下，交证据与疑点给作者。
+7. **交付报告**（固定格式，见下），交作者进房验收。
+
+## 选型规则（区间不重叠；样板的业务 id 是演示值，必须逐个替换）
+
+| 业务数 | 户型 | 风格 | 说明 |
+|---|---|---|---|
+| 0 | **不建房** | — | 清单里没有业务目录：停下报告并指向 `specdev-business`；确实要空院子由作者明确要求 |
+| 1 | `single` 一间房＋前庭 | `warm-modern` | 不需要走廊——门直接开向前庭 |
+| 2 | `row` 两间房＋走廊＋前庭 | `warm-modern` | 同一套递推，房间宽度可放宽 |
+| 3–8 | `row` 一排房＋走廊＋前庭 | `warm-modern` | 默认 |
+| 9–16 | `tower` 两层 | `warm-modern` | 每层 ≤8 间，按清单顺序前 ⌈N/2⌉ 间放一层 |
+| >16 | **停下问作者** | — | 两层最多 16 间，超出 v1 户型能力 |
+| 4–10 任意 | `court` 合院 | `chinese-timber` | 只在作者指定"要中庭/围合"时用，不参与自动选型 |
+
+**风格只有两个取值**（`warm-modern`／`chinese-timber`），只影响配色与构件材质，**不影响布局、几何与诊断**；上表就是各户型样板的同款写法。作者另有指定时按作者指定，并在报告里写明。
+
+要因场地或观感改选，在报告里说明理由，由作者确认或否决。
+
+## 三条底线
+
+1. **面积档由作者定**：默认全部基础档，交付报告逐间标"待作者定档"，**不宣称房间已有特色、不暗示已按价值排序**；不按代码量、文件数、文档长度推断业务价值。
+2. **蓝图能生成 ≠ 房子能走通**：诊断通过只说明模型可生成。漫游手感、门牌点不点得开、观感如何，一律交作者在页面验收；不许把校验通过说成"已验收"。
+3. **不越权**：业务取舍、面积分档、是否覆盖已有蓝图，都是作者的裁决——**未获修改授权时只提方案与理由；已获修改授权时按授权范围实施**（口径同"唯一产物与边界"第 2 条）。
+
+## 按需读取
+
+| 要做什么 | 先读 |
+|---|---|
+| 写蓝图前核对字段、取值、默认值 | [references/blueprint-contract.md](references/blueprint-contract.md) |
+| 选定户型、算坐标、加房／改尺寸 | [references/layouts.md](references/layouts.md) ＋ `assets/layouts/*.json` |
+| 看懂诊断、按码修 | [references/diagnostics.md](references/diagnostics.md) |
+
+同一会话已读且未变化的内容直接复用；只展开当前步骤用到的文件。
+
+## 交付报告（固定格式）
+
+1. **文件路径**：`docs/specdev/building.json`（新建或修改；改了哪几处）。
+2. **设计表**：业务 ↔ 房间 id ↔ 面积档（逐间标"待作者定档"；蓝图里没有档位字段，档位只出现在这张表里）↔ 所在层；资料数（文档 × 图，数法见主流程第 2 步）；户型与风格的选择理由。
+3. **诊断结果**：命令原文、退出码、最终 error/warning 条数；保留的 warning 逐条写明理由；修了几轮、每轮改了什么。
+4. **未决项**：需要作者裁决的（面积档、是否保留某业务、是否覆盖旧蓝图），无则写"无"。
+5. **页面入口与检查点**：页面路径 `/specdev-workbench/building`。**工作区标识不在本技能能取到的信息里**——它只出现在作者从 DSH 侧栏进管理页时的链接 `?workspace=<id>` 中（命令行诊断 `--json` 里的 `repo.workspaceId` 恒为空串）。按拿没拿到分两种写法：
+   - 拿到（作者贴过含 `?workspace=` 的链接）→ 原样写全：`/specdev-workbench/building?workspace=<实际标识>`；
+   - 没拿到 → **只写不带参数的路径**，并写明"请从 DSH 侧栏打开本项目的工作区，标识由侧栏带出"；也可以请作者贴一次链接再补全。
+   - **不许编造标识，也不许把 `<工作区标识>` 这类占位符当成可点的链接交出去**——占位符只能出现在"待作者补"的说明里。
+   另附建议作者重点看什么（走进每间房、点门牌、切完整外观、上楼）。
+6. **提交状态**：分支与提交号，或注明"未提交，待验收"。
+7. **未验证项**：明确写"漫游与观感未由本技能验证，待作者页面验收"。

package/skills/specdev-building/assets/layouts/court.json

@@ -0,0 +1,53 @@
+{
+  "format": "specdev-building",
+  "schema": "specdev/building/1",
+  "units": "m",
+  "style": "chinese-timber",
+  "floors": [{ "id": "floor-ground", "name": "一层", "elevation": 0, "height": 3.8 }],
+  "spaces": [
+    { "id": "room-account", "kind": "room", "floorId": "floor-ground", "businessId": "account-access",
+      "rect": { "x": -19, "z": -4.5, "width": 6, "depth": 7 } },
+    { "id": "room-form", "kind": "room", "floorId": "floor-ground", "businessId": "form-design",
+      "rect": { "x": 19, "z": -4.5, "width": 6, "depth": 7 } },
+    { "id": "room-fill", "kind": "room", "floorId": "floor-ground", "businessId": "fill-submit",
+      "rect": { "x": -8, "z": -8, "width": 16, "depth": 7 } },
+    { "id": "room-review", "kind": "room", "floorId": "floor-ground", "businessId": "review-audit",
+      "rect": { "x": 8, "z": -8, "width": 16, "depth": 7 } },
+    { "id": "room-file", "kind": "room", "floorId": "floor-ground", "businessId": "file-material",
+      "rect": { "x": -19, "z": 2.5, "width": 6, "depth": 7 } },
+    { "id": "room-stats", "kind": "room", "floorId": "floor-ground", "businessId": "stats-export",
+      "rect": { "x": 19, "z": 2.5, "width": 6, "depth": 7 } },
+    { "id": "corridor-court", "name": "中庭", "kind": "corridor", "floorId": "floor-ground",
+      "rect": { "x": 0, "z": 1.25, "width": 32, "depth": 11.5 } },
+    { "id": "yard-entry", "name": "前庭", "kind": "yard", "floorId": "floor-ground",
+      "rect": { "x": 0, "z": 13, "width": 32, "depth": 12 } }
+  ],
+  "openings": [
+    { "id": "door-fill", "kind": "door", "spaceId": "room-fill", "side": "south", "offset": 0, "width": 2.2, "to": "corridor-court" },
+    { "id": "door-review", "kind": "door", "spaceId": "room-review", "side": "south", "offset": 0, "width": 2.2, "to": "corridor-court" },
+    { "id": "door-account", "kind": "door", "spaceId": "room-account", "side": "east", "offset": 1.75, "width": 1.6, "to": "corridor-court" },
+    { "id": "door-form", "kind": "door", "spaceId": "room-form", "side": "west", "offset": 1.75, "width": 1.6, "to": "corridor-court" },
+    { "id": "door-file", "kind": "door", "spaceId": "room-file", "side": "east", "offset": 0, "width": 1.6, "to": "corridor-court" },
+    { "id": "door-stats", "kind": "door", "spaceId": "room-stats", "side": "west", "offset": 0, "width": 1.6, "to": "corridor-court" },
+    { "id": "window-fill", "kind": "window", "spaceId": "room-fill", "side": "north", "offset": -3, "width": 2.4 },
+    { "id": "window-review", "kind": "window", "spaceId": "room-review", "side": "north", "offset": 3, "width": 2.4 },
+    { "id": "window-account", "kind": "window", "spaceId": "room-account", "side": "west", "offset": 0, "width": 2.4 },
+    { "id": "window-form", "kind": "window", "spaceId": "room-form", "side": "east", "offset": 0, "width": 2.4 },
+    { "id": "window-file", "kind": "window", "spaceId": "room-file", "side": "west", "offset": 0, "width": 2.4 },
+    { "id": "window-stats", "kind": "window", "spaceId": "room-stats", "side": "east", "offset": 0, "width": 2.4 }
+  ],
+  "stairs": [],
+  "roofs": [
+    { "id": "roof-fill", "spaceIds": ["room-fill"], "type": "gable", "rise": 2, "overhang": 0 },
+    { "id": "roof-review", "spaceIds": ["room-review"], "type": "gable", "rise": 2, "overhang": 0 },
+    { "id": "roof-account", "spaceIds": ["room-account"], "type": "gable", "rise": 1.6, "overhang": 0 },
+    { "id": "roof-form", "spaceIds": ["room-form"], "type": "gable", "rise": 1.6, "overhang": 0 },
+    { "id": "roof-file", "spaceIds": ["room-file"], "type": "gable", "rise": 1.6, "overhang": 0 },
+    { "id": "roof-stats", "spaceIds": ["room-stats"], "type": "gable", "rise": 1.6, "overhang": 0 }
+  ],
+  "construction": {
+    "phase": "design",
+    "status": { "design": "detailed", "approval": "pending", "implementation": "unknown", "tests": "pending", "acceptance": "pending", "evidence": {} }
+  },
+  "entry": { "spaceId": "yard-entry", "x": 0, "z": 12 }
+}

package/skills/specdev-building/assets/layouts/row.json

@@ -0,0 +1,48 @@
+{
+  "format": "specdev-building",
+  "schema": "specdev/building/1",
+  "units": "m",
+  "style": "warm-modern",
+  "floors": [{ "id": "floor-ground", "name": "一层", "elevation": 0, "height": 3.6 }],
+  "spaces": [
+    { "id": "room-account", "kind": "room", "floorId": "floor-ground", "businessId": "account-access",
+      "rect": { "x": -22.5, "z": -5, "width": 9, "depth": 8 } },
+    { "id": "room-form", "kind": "room", "floorId": "floor-ground", "businessId": "form-design",
+      "rect": { "x": -13.5, "z": -5, "width": 9, "depth": 8 } },
+    { "id": "room-fill", "kind": "room", "floorId": "floor-ground", "businessId": "fill-submit",
+      "rect": { "x": -4.5, "z": -5, "width": 9, "depth": 8 } },
+    { "id": "room-file", "kind": "room", "floorId": "floor-ground", "businessId": "file-material",
+      "rect": { "x": 4.5, "z": -5, "width": 9, "depth": 8 } },
+    { "id": "room-review", "kind": "room", "floorId": "floor-ground", "businessId": "review-audit",
+      "rect": { "x": 13.5, "z": -5, "width": 9, "depth": 8 } },
+    { "id": "room-stats", "kind": "room", "floorId": "floor-ground", "businessId": "stats-export",
+      "rect": { "x": 22.5, "z": -5, "width": 9, "depth": 8 } },
+    { "id": "corridor-main", "name": "南廊", "kind": "corridor", "floorId": "floor-ground",
+      "rect": { "x": 0, "z": 3, "width": 58, "depth": 8 } },
+    { "id": "yard-entry", "name": "前庭", "kind": "yard", "floorId": "floor-ground",
+      "rect": { "x": 0, "z": 13, "width": 58, "depth": 12 } }
+  ],
+  "openings": [
+    { "id": "door-account", "kind": "door", "spaceId": "room-account", "side": "south", "offset": 0, "width": 1.8, "to": "corridor-main" },
+    { "id": "door-form", "kind": "door", "spaceId": "room-form", "side": "south", "offset": 0, "width": 1.8, "to": "corridor-main" },
+    { "id": "door-fill", "kind": "door", "spaceId": "room-fill", "side": "south", "offset": 0, "width": 1.8, "to": "corridor-main" },
+    { "id": "door-file", "kind": "door", "spaceId": "room-file", "side": "south", "offset": 0, "width": 1.8, "to": "corridor-main" },
+    { "id": "door-review", "kind": "door", "spaceId": "room-review", "side": "south", "offset": 0, "width": 1.8, "to": "corridor-main" },
+    { "id": "door-stats", "kind": "door", "spaceId": "room-stats", "side": "south", "offset": 0, "width": 1.8, "to": "corridor-main" },
+    { "id": "window-account", "kind": "window", "spaceId": "room-account", "side": "north", "offset": 0, "width": 3 },
+    { "id": "window-form", "kind": "window", "spaceId": "room-form", "side": "north", "offset": 0, "width": 3 },
+    { "id": "window-fill", "kind": "window", "spaceId": "room-fill", "side": "north", "offset": 0, "width": 3 },
+    { "id": "window-file", "kind": "window", "spaceId": "room-file", "side": "north", "offset": 0, "width": 3 },
+    { "id": "window-review", "kind": "window", "spaceId": "room-review", "side": "north", "offset": 0, "width": 3 },
+    { "id": "window-stats", "kind": "window", "spaceId": "room-stats", "side": "north", "offset": 0, "width": 3 }
+  ],
+  "stairs": [],
+  "roofs": [
+    { "id": "roof-main", "spaceIds": ["room-account", "room-form", "room-fill", "room-file", "room-review", "room-stats"], "type": "gable", "rise": 1.8, "overhang": 0.35 }
+  ],
+  "construction": {
+    "phase": "design",
+    "status": { "design": "detailed", "approval": "pending", "implementation": "unknown", "tests": "pending", "acceptance": "pending", "evidence": {} }
+  },
+  "entry": { "spaceId": "yard-entry", "x": 0, "z": 17 }
+}

package/skills/specdev-building/assets/layouts/single.json

@@ -0,0 +1,27 @@
+{
+  "format": "specdev-building",
+  "schema": "specdev/building/1",
+  "units": "m",
+  "style": "warm-modern",
+  "defaults": { "wallThickness": 0.18, "slabThickness": 0.18, "doorHeight": 2.5 },
+  "floors": [{ "id": "floor-ground", "name": "一层", "elevation": 0, "height": 3.6 }],
+  "spaces": [
+    { "id": "room-sample", "kind": "room", "floorId": "floor-ground", "businessId": "sample-business",
+      "rect": { "x": 0, "z": -1, "width": 8, "depth": 6 } },
+    { "id": "yard-entry", "name": "前庭", "kind": "yard", "floorId": "floor-ground",
+      "rect": { "x": 0, "z": 6, "width": 14, "depth": 8 } }
+  ],
+  "openings": [
+    { "id": "door-sample", "kind": "door", "spaceId": "room-sample", "side": "south", "offset": 0, "width": 1.8, "to": "yard-entry" },
+    { "id": "window-sample", "kind": "window", "spaceId": "room-sample", "side": "north", "offset": 0, "width": 3 }
+  ],
+  "stairs": [],
+  "roofs": [
+    { "id": "roof-sample", "spaceIds": ["room-sample"], "type": "gable", "rise": 1.8, "overhang": 0.35 }
+  ],
+  "construction": {
+    "phase": "design",
+    "status": { "design": "detailed", "approval": "pending", "implementation": "unknown", "tests": "pending", "acceptance": "pending", "evidence": {} }
+  },
+  "entry": { "spaceId": "yard-entry", "x": 0, "z": 8 }
+}

package/skills/specdev-building/assets/layouts/tower-9.json

@@ -0,0 +1,71 @@
+{
+  "format": "specdev-building",
+  "schema": "specdev/building/1",
+  "units": "m",
+  "style": "warm-modern",
+  "floors": [
+    { "id": "floor-ground", "name": "一层", "elevation": 0, "height": 3.6 },
+    { "id": "floor-upper", "name": "二层", "elevation": 4.2, "height": 3.6 }
+  ],
+  "spaces": [
+    { "id": "room-alpha", "kind": "room", "floorId": "floor-ground", "businessId": "alpha",
+      "rect": { "x": -8, "z": -4, "width": 4, "depth": 6 } },
+    { "id": "room-beta", "kind": "room", "floorId": "floor-ground", "businessId": "beta",
+      "rect": { "x": -4, "z": -4, "width": 4, "depth": 6 } },
+    { "id": "room-gamma", "kind": "room", "floorId": "floor-ground", "businessId": "gamma",
+      "rect": { "x": 0, "z": -4, "width": 4, "depth": 6 } },
+    { "id": "room-delta", "kind": "room", "floorId": "floor-ground", "businessId": "delta",
+      "rect": { "x": 4, "z": -4, "width": 4, "depth": 6 } },
+    { "id": "room-epsilon", "kind": "room", "floorId": "floor-ground", "businessId": "epsilon",
+      "rect": { "x": 8, "z": -4, "width": 4, "depth": 6 } },
+    { "id": "corridor-ground", "name": "一层前廊", "kind": "corridor", "floorId": "floor-ground",
+      "rect": { "x": 0, "z": 0, "width": 20, "depth": 2 } },
+    { "id": "yard-entry", "name": "项目前庭", "kind": "yard", "floorId": "floor-ground",
+      "rect": { "x": 0, "z": 4, "width": 10, "depth": 6 } },
+    { "id": "room-zeta", "kind": "room", "floorId": "floor-upper", "businessId": "zeta",
+      "rect": { "x": -7.5, "z": -4, "width": 5, "depth": 6 } },
+    { "id": "room-eta", "kind": "room", "floorId": "floor-upper", "businessId": "eta",
+      "rect": { "x": -2.5, "z": -4, "width": 5, "depth": 6 } },
+    { "id": "room-theta", "kind": "room", "floorId": "floor-upper", "businessId": "theta",
+      "rect": { "x": 2.5, "z": -4, "width": 5, "depth": 6 } },
+    { "id": "room-iota", "kind": "room", "floorId": "floor-upper", "businessId": "iota",
+      "rect": { "x": 7.5, "z": -4, "width": 5, "depth": 6 } },
+    { "id": "corridor-upper", "name": "二层前廊", "kind": "corridor", "floorId": "floor-upper",
+      "rect": { "x": 0, "z": 0, "width": 20, "depth": 2 } },
+    { "id": "landing-upper", "name": "二层梯台", "kind": "terrace", "floorId": "floor-upper",
+      "rect": { "x": 17, "z": 1, "width": 2, "depth": 4 } },
+    { "id": "return-upper", "name": "二层回廊", "kind": "corridor", "floorId": "floor-upper",
+      "rect": { "x": 3, "z": 2, "width": 26, "depth": 2 } }
+  ],
+  "openings": [
+    { "id": "door-alpha", "kind": "door", "spaceId": "room-alpha", "side": "south", "offset": 0, "width": 1.8, "to": "corridor-ground" },
+    { "id": "door-beta", "kind": "door", "spaceId": "room-beta", "side": "south", "offset": 0, "width": 1.8, "to": "corridor-ground" },
+    { "id": "door-gamma", "kind": "door", "spaceId": "room-gamma", "side": "south", "offset": 0, "width": 1.8, "to": "corridor-ground" },
+    { "id": "door-delta", "kind": "door", "spaceId": "room-delta", "side": "south", "offset": 0, "width": 1.8, "to": "corridor-ground" },
+    { "id": "door-epsilon", "kind": "door", "spaceId": "room-epsilon", "side": "south", "offset": 0, "width": 1.8, "to": "corridor-ground" },
+    { "id": "door-zeta", "kind": "door", "spaceId": "room-zeta", "side": "south", "offset": 0, "width": 1.8, "to": "corridor-upper" },
+    { "id": "door-eta", "kind": "door", "spaceId": "room-eta", "side": "south", "offset": 0, "width": 1.8, "to": "corridor-upper" },
+    { "id": "door-theta", "kind": "door", "spaceId": "room-theta", "side": "south", "offset": 0, "width": 1.8, "to": "corridor-upper" },
+    { "id": "door-iota", "kind": "door", "spaceId": "room-iota", "side": "south", "offset": 0, "width": 1.8, "to": "corridor-upper" },
+    { "id": "window-alpha", "kind": "window", "spaceId": "room-alpha", "side": "north", "offset": 0, "width": 2.4 },
+    { "id": "window-beta", "kind": "window", "spaceId": "room-beta", "side": "north", "offset": 0, "width": 2.4 },
+    { "id": "window-gamma", "kind": "window", "spaceId": "room-gamma", "side": "north", "offset": 0, "width": 2.4 },
+    { "id": "window-delta", "kind": "window", "spaceId": "room-delta", "side": "north", "offset": 0, "width": 2.4 },
+    { "id": "window-epsilon", "kind": "window", "spaceId": "room-epsilon", "side": "north", "offset": 0, "width": 2.4 },
+    { "id": "window-zeta", "kind": "window", "spaceId": "room-zeta", "side": "north", "offset": 0, "width": 3 },
+    { "id": "window-eta", "kind": "window", "spaceId": "room-eta", "side": "north", "offset": 0, "width": 3 },
+    { "id": "window-theta", "kind": "window", "spaceId": "room-theta", "side": "north", "offset": 0, "width": 3 },
+    { "id": "window-iota", "kind": "window", "spaceId": "room-iota", "side": "north", "offset": 0, "width": 3 }
+  ],
+  "stairs": [
+    { "id": "stair-ground-upper", "from": { "spaceId": "corridor-ground", "x": 10, "z": 0 }, "to": { "spaceId": "landing-upper", "x": 16, "z": 0 }, "width": 1.4, "steps": 22 }
+  ],
+  "roofs": [
+    { "id": "roof-upper", "spaceIds": ["room-zeta", "room-eta", "room-theta", "room-iota"], "type": "gable", "rise": 1.8, "overhang": 0.35 }
+  ],
+  "construction": {
+    "phase": "design",
+    "status": { "design": "detailed", "approval": "pending", "implementation": "unknown", "tests": "pending", "acceptance": "pending", "evidence": {} }
+  },
+  "entry": { "spaceId": "yard-entry", "x": 0, "z": 5 }
+}

package/skills/specdev-building/assets/layouts/tower.json

@@ -0,0 +1,59 @@
+{
+  "format": "specdev-building",
+  "schema": "specdev/building/1",
+  "units": "m",
+  "style": "warm-modern",
+  "floors": [
+    { "id": "floor-ground", "name": "一层", "elevation": 0, "height": 3.6 },
+    { "id": "floor-upper", "name": "二层", "elevation": 4.2, "height": 3.6 }
+  ],
+  "spaces": [
+    { "id": "room-account", "kind": "room", "floorId": "floor-ground", "businessId": "account-access",
+      "rect": { "x": -5.5, "z": -4, "width": 5, "depth": 6 } },
+    { "id": "room-form", "kind": "room", "floorId": "floor-ground", "businessId": "form-design",
+      "rect": { "x": 0, "z": -4, "width": 6, "depth": 6 } },
+    { "id": "room-fill", "kind": "room", "floorId": "floor-ground", "businessId": "fill-submit",
+      "rect": { "x": 5.5, "z": -4, "width": 5, "depth": 6 } },
+    { "id": "corridor-ground", "name": "一层前廊", "kind": "corridor", "floorId": "floor-ground",
+      "rect": { "x": 0, "z": 0, "width": 16, "depth": 2 } },
+    { "id": "yard-entry", "name": "项目前庭", "kind": "yard", "floorId": "floor-ground",
+      "rect": { "x": 0, "z": 4, "width": 8, "depth": 6 } },
+    { "id": "room-file", "kind": "room", "floorId": "floor-upper", "businessId": "file-material",
+      "rect": { "x": -6, "z": -4, "width": 4, "depth": 6 } },
+    { "id": "room-review", "kind": "room", "floorId": "floor-upper", "businessId": "review-audit",
+      "rect": { "x": 0, "z": -4, "width": 8, "depth": 6 } },
+    { "id": "room-stats", "kind": "room", "floorId": "floor-upper", "businessId": "stats-export",
+      "rect": { "x": 6, "z": -4, "width": 4, "depth": 6 } },
+    { "id": "corridor-upper", "name": "二层前廊", "kind": "corridor", "floorId": "floor-upper",
+      "rect": { "x": 0, "z": 0, "width": 16, "depth": 2 } },
+    { "id": "landing-upper", "name": "二层梯台", "kind": "terrace", "floorId": "floor-upper",
+      "rect": { "x": 15, "z": 1, "width": 2, "depth": 4 } },
+    { "id": "return-upper", "name": "二层回廊", "kind": "corridor", "floorId": "floor-upper",
+      "rect": { "x": 3, "z": 2, "width": 22, "depth": 2 } }
+  ],
+  "openings": [
+    { "id": "door-account", "kind": "door", "spaceId": "room-account", "side": "south", "offset": 0, "width": 1.6, "to": "corridor-ground" },
+    { "id": "door-form", "kind": "door", "spaceId": "room-form", "side": "south", "offset": 0, "width": 1.8, "to": "corridor-ground" },
+    { "id": "door-fill", "kind": "door", "spaceId": "room-fill", "side": "south", "offset": 0, "width": 1.6, "to": "corridor-ground" },
+    { "id": "door-file", "kind": "door", "spaceId": "room-file", "side": "south", "offset": 0, "width": 1.6, "to": "corridor-upper" },
+    { "id": "door-review", "kind": "door", "spaceId": "room-review", "side": "south", "offset": 0, "width": 1.8, "to": "corridor-upper" },
+    { "id": "door-stats", "kind": "door", "spaceId": "room-stats", "side": "south", "offset": 0, "width": 1.6, "to": "corridor-upper" },
+    { "id": "window-account", "kind": "window", "spaceId": "room-account", "side": "north", "offset": 0, "width": 3 },
+    { "id": "window-form", "kind": "window", "spaceId": "room-form", "side": "north", "offset": 0, "width": 3 },
+    { "id": "window-fill", "kind": "window", "spaceId": "room-fill", "side": "north", "offset": 0, "width": 3 },
+    { "id": "window-file", "kind": "window", "spaceId": "room-file", "side": "north", "offset": 0, "width": 2.4 },
+    { "id": "window-review", "kind": "window", "spaceId": "room-review", "side": "north", "offset": 0, "width": 3 },
+    { "id": "window-stats", "kind": "window", "spaceId": "room-stats", "side": "north", "offset": 0, "width": 2.4 }
+  ],
+  "stairs": [
+    { "id": "stair-ground-upper", "from": { "spaceId": "corridor-ground", "x": 8, "z": 0 }, "to": { "spaceId": "landing-upper", "x": 14, "z": 0 }, "width": 1.4, "steps": 22 }
+  ],
+  "roofs": [
+    { "id": "roof-upper", "spaceIds": ["room-file", "room-review", "room-stats"], "type": "gable", "rise": 1.8, "overhang": 0.35 }
+  ],
+  "construction": {
+    "phase": "design",
+    "status": { "design": "detailed", "approval": "pending", "implementation": "unknown", "tests": "pending", "acceptance": "pending", "evidence": {} }
+  },
+  "entry": { "spaceId": "yard-entry", "x": 0, "z": 5 }
+}

package/skills/specdev-building/references/blueprint-contract.md

@@ -0,0 +1,126 @@
+# 蓝图契约（字段、取值、默认值）
+
+**以生成器为准，本表是索引**：字段行为的唯一来源是插件 `src/core/house.ts` 的 `blueprintRule` 与几何检查；本表与它不一致时以代码为准，并回报作者修订本文件。写蓝图前逐项对照一遍，比事后看诊断便宜得多。
+
+形状校验**不容错**：出现未定义字段（拼错一个字母也算）直接 `INPUT_UNKNOWN_FIELD`。
+
+## 1. 顶层
+
+| 字段 | 必填 | 取值 | 说明 |
+|---|---|---|---|
+| `format` | ✓ | `"specdev-building"` | 固定 |
+| `schema` | ✓ | `"specdev/building/1"` | 固定 |
+| `units` | ✓ | `"m"` | 固定，米 |
+| `style` | ✓ | `"warm-modern"`／`"chinese-timber"` | 影响配色与构件材质，**不影响几何与诊断**；怎么选见 SKILL.md 选型表的"风格"列（跟各户型样板同款：`single`／`row`／`tower` 一族 `warm-modern`，`court` `chinese-timber`） |
+| `defaults` | | `{wallThickness, slabThickness, doorHeight}` | 厚度 ∈ (0, 0.6] 米、门高 ∈ (0, 8]；**整块可以省略**，省略即 0.18／0.18／2.5（`single.json` 里那一块就是这个值——写它和省略**等价**）；也可以只写要改的字段。**只有"写与缺省相同的值"才等价**：改墙厚／楼板厚会改构件尺寸与楼层净空，改门高会改门洞与漫游落点 |
+| `floors` | ✓ | 数组，至少一条 | 见 §2 |
+| `spaces` | ✓ | 数组，至少一条 | 见 §3 |
+| `openings` | | 数组 | 见 §4 |
+| `stairs` | | 数组 | 见 §5 |
+| `roofs` | | 数组 | 见 §6 |
+| `construction` | | `{phase, status}` | 缺省 `design` ＋ 全 pending／unknown，见 §7 |
+| `entry` | ✓ | `{spaceId, x, z}` | 必须在已登记空间内，且离该空间边缘 ≥ 0.35 米 |
+
+规模上限：≤ 240 空间、≤ 24 层、≤ 2000 开口、≤ 96 跑楼梯、≤ 240 屋顶（`INPUT_LIMIT`）。
+
+可选数组（`openings`／`stairs`／`roofs`）不需要时**省略或写空数组都合法**、几何一样：照抄样板即可（`row.json` 里就写着 `"stairs": []`）。
+
+## 2. floors[]
+
+| 字段 | 必填 | 取值 |
+|---|---|---|
+| `id` | ✓ | `^[a-z][a-z0-9-]*$`，全文件唯一 |
+| `name` | ✓ | 非空字符串（如 `一层`） |
+| `elevation` | ✓ | 数字，该层楼板上表面标高；绝对值 ≤ 500 |
+| `height` | ✓ | 2.6—12（室内净高，不含楼板） |
+
+## 3. spaces[]
+
+| 字段 | 必填 | 取值 |
+|---|---|---|
+| `id` | ✓ | `^[a-z][a-z0-9-]*$`，全文件唯一 |
+| `kind` | ✓ | `room`／`corridor`／`terrace`／`yard` |
+| `floorId` | ✓ | 必须指向已登记楼层 |
+| `rect` | ✓ | `{x, z, width, depth}`：`x`／`z` 是**中心**坐标；边长 1.6—200 米；坐标绝对值 ≤ 1000 |
+| `businessId` | room 必填 | **只填业务目录名**（如 `account-access`），不带 `docs/specdev/` 前缀；一个业务只能绑一间房 |
+| `directory` | | 布尔；缺省＝开。`false` 会关掉该房间的资料目录 → 该业务的资料全部报 `MATERIAL_NO_ENTRY`，只在作者要求时用 |
+| `name` | | 非 room 空间的显示名（room 的显示名以清单为准）；可照抄样板（走廊「南廊」、前庭「前庭」），不影响校验 |
+| `prototype` | | `foyer`／`studio`／`archive`／`review`／`observatory`：只影响色调与标签，**不参与户型算术**；建房 v1 **一律省略**（省略即 `studio`，五份样板都没用它） |
+| `height` | | 2.6—12；缺省跟随所在楼层 |
+| `accent` | | `#rrggbb`；省略时随 `prototype` 取色——建房 v1 不写 |
+| `wallType` | | `plaster`／`brick`／`timber`，**省略即 `plaster`**；共墙两侧的房间必须同墙高、同墙材（否则 `SHARED_WALL_CONFLICT`）——比的是**两侧的最终取值**，所以两侧都不写＝两侧都 `plaster`（一致）；要写就两侧写同一个值 |
+| `status` | | 建造状态，见 §7 |
+
+几何硬约束：
+
+- `rect` 是**墙中心线**范围：室内净尺寸还要扣掉墙厚（`defaults.wallThickness`）。
+- 同层空间**不许内部重叠**，可以共边（差 0.1 米既不是共边也不算重叠，会各建一堵墙）。
+- 上下层空间重叠时，必须留出净空：下层顶 ≤ 上层地坪 − 楼板厚（`FLOOR_CLEARANCE`）。
+- 房间（`room`）必须有门；从入口经门、楼梯、相邻非房间空间要能走遍每个空间（`SPACE_UNREACHABLE`）。
+
+## 4. openings[]（门与窗）
+
+| 字段 | 必填 | 取值 |
+|---|---|---|
+| `id` | ✓ | `^[a-z][a-z0-9-]*$`，全文件唯一 |
+| `kind` | ✓ | `door`／`window` |
+| `spaceId` | ✓ | 必须是 `kind: "room"` 的空间（开口只挂在房间上） |
+| `side` | ✓ | `north`／`south`／`east`／`west`（世界坐标的四个方向） |
+| `offset` | ✓ | **相对该墙中心**的距离（米），不是"从左数第几块"；南北墙沿 +X 增大，东西墙沿 +Z 增大 |
+| `width` | ✓ | 门 ≥ 0.95；窗 ≥ 0.2；且 ≤ 房间该边长度 − 0.4（墙角各留 0.2 米） |
+| `height` | | 门省略时取 `defaults.doorHeight`（`defaults` 缺省 2.5，**必须 ≥ 2.2**，否则所有门报错）；窗缺省 1.2；`sill + height` ≤ 空间净高 − 0.12 |
+| `sill` | | 门缺省 0（**门不许有门槛**）；窗缺省 1（窗台高） |
+| `to` | 门必填 | 门通向的空间 id，见下 |
+
+门的额外要求（`DOOR_CONNECTION`）：
+
+- 必须落在**来源房间与 `to` 空间的共边**上，同一层，且整扇门都在共边范围内；
+- 跨房间的共墙只登记**一次**门，两边各写一扇会重叠（`OPENING_OVERLAP`）；
+- 门不许跨过共墙的分区端点（`OPENING_PARTITION`）：同一面墙线上，每个房间与走廊的共边是独立墙段，门要整扇落在其中一段里。
+
+窗：`to` 一律不写（`WINDOW_CONNECTION`）。
+
+## 5. stairs[]（只支持轴向直跑梯）
+
+| 字段 | 必填 | 取值 |
+|---|---|---|
+| `id` | ✓ | 同上 |
+| `from`／`to` | ✓ | `{spaceId, x, z}`；端点空间**不能是 room**（走廊／平台／庭院），必须不同层且 `to` 更高 |
+| `width` | ✓ | 1.2—8 米 |
+| `steps` | ✓ | 整数 2—120 |
+
+硬约束：
+
+- 只能沿 X 或 Z 一个方向（`dx`、`dz` 至多一个非零）；
+- 水平长度 ≥ 上升高度（≤ 45°）；
+- 两端要"落"在平台里：沿行进方向平台向外至少留 0.6 米，左右要容得下梯宽（`STAIR_LANDING`）；
+- 楼梯投影**不许与任何平层空间相交**：楼板要拆成避开梯井的矩形（`STAIR_SPACE_INTERSECTION`）；梯段之间头部净空 ≥ 2.2 米（`STAIR_INTERSECTION`）。
+
+## 6. roofs[]
+
+| 字段 | 必填 | 取值 |
+|---|---|---|
+| `id` | ✓ | 同上 |
+| `spaceIds` | ✓ | 不重复的现有空间 id 列表 |
+| `type` | ✓ | `flat`／`gable`（坡顶屋脊只沿 X） |
+| `rise` | | 坡顶可省略，缺省 1.8，取值 (0, 8]；平顶省略或显式写 `0`（写其它值报 `ROOF_SIZE`） |
+| `overhang` | | 0—2 米，缺省 0.35 |
+
+硬约束：同一个屋顶引用的空间必须**同层、同墙顶标高**，且并集正好是一个**完整矩形**（不能有空洞，不能用一个大矩形无意盖上中庭）。屋顶包络不许穿进上层空间（`ROOF_UPPER_FLOOR`）或与另一个屋顶相交（`ROOF_INTERSECTION`）。
+
+**每个房间上方都要有屋顶**，否则报 `ROOF_MISSING`（warning，不阻塞生成，但要在交付说明里写明理由）。第四种做法：一排等高等深的房间可以合成一个组合屋顶（见 `assets/layouts/row.json`）。
+
+## 7. construction 与 status
+
+| 字段 | 取值 |
+|---|---|
+| `phase` | `design`／`foundation`／`structure`／`enclosure`／`services`／`interior`／`accepted` |
+| `status.design` | `concept`／`detailed` |
+| `status.approval` | `pending`／`approved`（`approved` 要求 `design: detailed`） |
+| `status.implementation` | `absent`／`unknown`／`present` |
+| `status.tests`／`acceptance` | `pending`／`passed` |
+| `status.evidence` | `{implementation, tests, acceptance}`：声明 `present`／`passed` 时**必须**给出处，否则 `STATE_EVIDENCE_REQUIRED` |
+
+一致性：`tests`／`acceptance` 为 `passed` 时 `implementation` 必须是 `present`（`STATE_CONTRADICTION`）；`phase: "accepted"` 要求每间业务房四项齐备（`ACCEPTANCE_INCOMPLETE`）。
+
+**建房的默认写法**：整块照抄样板（`design` ＋ `detailed`／`pending`／`unknown`／`pending`／`pending`／空 `evidence`）。计划、实现、测试、验收是**四种不同的事实**——生成器诊断通过不是业务实现证据，本技能不替作者声明任何一项。