@pioneer_zmc/dsh-workbench 0.2.1

package/skills/specdev-building/references/diagnostics.md

@@ -0,0 +1,101 @@
+# 诊断目录（按码修，一轮只修一类）
+
+命令：`node "<插件包根>/dist/check-building.js" <项目仓库根>`（加 `--json` 给机器读的结构）。
+退出码：`0` 通过（可含 warning）、`1` 有 error、`2` 读不了（缺清单、坏 JSON、不是 Git 仓库顶层、路径不存在）。
+
+**修复对象**三档（与插件 `src/core/diagnosis.ts` 的 `FIX_TARGETS` 逐码一致，回归钉住）：
+
+- **改蓝图**——按 `subject.path` 回 `docs/specdev/building.json` 改；
+- **改清单或资料**——改蓝图改不好，报告作者或先修清单/资料（`specdev-business`）；
+- **按证据判**——对照 `subject.ids` 与项目清单核对，默认先核查蓝图，清单的取舍交作者决定。
+
+**修法**：一轮只修一类，改完用同一条命令重跑；**同一问题两轮修不成**，停下交证据与疑点给作者。诊断里的 `ids` 在 `subject.ids`（不是 `evidence`）；`evidence` 里是佐料（业务名、文件路径、冲突对象）。
+
+## 一、输入与形状
+
+| 诊断码 | 级别 | 修复对象 | 怎么改 |
+|---|---|---|---|
+| `INPUT_TYPE` | error | 改蓝图 | 字段类型写错（数值写成字符串、`rect` 写成数字等）→ 按契约改回类型 |
+| `INPUT_ENUM` | error | 改蓝图 | 取值不在允许集合里（`kind`／`side`／`type`／`phase`／`style`／`prototype`／`wallType`）→ 用契约里的允许值 |
+| `INPUT_PATTERN` | error | 改蓝图 | id 格式不合法：蓝图 id 只能小写字母开头、由小写字母/数字/连字符组成；`businessId` 另见契约 |
+| `INPUT_EMPTY` | error | 改蓝图 | 必填字符串是空的 |
+| `INPUT_UNKNOWN_FIELD` | error | 改蓝图 | 出现未定义字段（拼错一个字母也算）→ 删掉或改成契约里的字段名 |
+| `INPUT_REQUIRED` | error | 改蓝图 | 缺必填字段 → 按契约补 |
+| `DEFAULT_RANGE` | error | 改蓝图 | `defaults` 越界：厚度 (0, 0.6]、门高 (0, 8] |
+| `EMPTY_BUILDING` | error | 改蓝图 | 没有楼层或没有空间 → 至少一层、一个空间 |
+| `INPUT_LIMIT` | error | 改蓝图 | 超规模上限：240 空间／24 层／2000 开口／96 跑楼梯／240 屋顶 |
+| `ID_DUPLICATE` | error | 改蓝图 | id 在蓝图内重复（楼层、空间、开口、楼梯、屋顶共用一个命名空间）→ 改成唯一 |
+
+## 二、身份与绑定（清单 ↔ 蓝图）
+
+| 诊断码 | 级别 | 修复对象 | 怎么改 |
+|---|---|---|---|
+| `BLUEPRINT_SHAPE` | error | 改蓝图 | `spaces` 结构不对、缺非空 `id`、id 重复，或 `directory` 不是布尔（`"false"`／`0` 都不算关） |
+| `BUSINESS_REQUIRED` | error | 改蓝图 | 房间缺 `businessId` → 补上清单里的业务 id（`subject.path` 就指向该房间的 `businessId`） |
+| `BUSINESS_NOT_ROOM` | error | 改蓝图 | 非 `room` 空间带了 `businessId` → 删掉该字段，或把这个空间改成 `room`（业务身份只落在房间上） |
+| `BUSINESS_DUPLICATE` | error | 改蓝图 | 同一业务被两间房绑定 → 删掉多余那间，或改绑别的业务（`evidence.firstAt` 指首次绑定处） |
+| `BUSINESS_MISSING` | error | 按证据判 | `subject.ids` 是"没有房间的业务 id"：默认在蓝图里加一间房；这个业务该不该留在清单里由作者裁决 |
+| `BUSINESS_UNKNOWN` | error | 按证据判 | 蓝图写的业务 id 不在清单 → 对照 `subject.ids`（业务 id 与空间 id）与项目清单，先改蓝图指向清单里的真实 id；清单确实没登记该业务才交作者 |
+| `MATERIAL_NO_ENTRY` | error | 改蓝图 | 该业务**已绑房**却没有资料入口 → 用 `evidence.businessId` 找到对应房间，检查它的 `directory` 是否被关掉（`false` 就没有目录） |
+
+## 三、资料可读性
+
+| 诊断码 | 级别 | 修复对象 | 怎么改 |
+|---|---|---|---|
+| `MATERIAL_UNREADABLE` | error | 改清单或资料 | 登记的文档不存在或读不开（超过 2 MiB、权限）、`workflow.json` 缺失或读不开、业务/图说明文件坏、图编号冲突 → **改蓝图解决不了**：按 `evidence` 里的 `path`／`chartId`／`reason` 核对文件本身，报告作者或交 `specdev-business`。注意装配层只检查 `workflow.json` 能不能读、**不解析内容**，语法坏要到阅读页打开时才现形 |
+
+## 四、楼层、空间与排布
+
+| 诊断码 | 级别 | 修复对象 | 怎么改 |
+|---|---|---|---|
+| `FLOOR_REF` | error | 改蓝图 | 空间的 `floorId` 指向不存在的楼层 |
+| `FLOOR_RANGE` | error | 改蓝图 | 楼层净高不在 2.6—12 米，或标高绝对值超过 500 |
+| `SPACE_DIMENSION` | error | 改蓝图 | 空间边长不在 1.6—200 米，或坐标绝对值超过 1000 |
+| `SPACE_HEIGHT` | error | 改蓝图 | 空间墙高不在 2.6—12 米 |
+| `SPACE_OVERLAP` | error | 改蓝图 | 同层空间内部相交 → 改成贴边（共边可以，重叠不行；差 0.1 米既不是共边也会各建一堵墙） |
+| `FLOOR_CLEARANCE` | error | 改蓝图 | 上下层空间净空不足或楼板相交 → 上层地坪 ≥ 下层地坪 ＋ 下层墙高 ＋ 楼板厚 |
+| `SHARED_WALL_CONFLICT` | error | 改蓝图 | 共墙两侧房间的墙高与墙材必须一致（`evidence` 给出冲突的房间） |
+| `ENTRY_POSITION` | error | 改蓝图 | 入口必须落在已登记空间内、离边缘 ≥ 0.35 米；放置时还要留出人身半径，别贴着墙（贴墙会出现"生成合法但一进去就卡住"） |
+| `SPACE_UNREACHABLE` | error | 改蓝图 | 从入口走不到这个空间 → 补门、接楼梯，或让它与相邻非房间空间贴边 |
+
+## 五、开口（门与窗）
+
+| 诊断码 | 级别 | 修复对象 | 怎么改 |
+|---|---|---|---|
+| `OPENING_ROOM` | error | 改蓝图 | 开口只能挂在 `kind: "room"` 的空间上 |
+| `OPENING_SIZE` | error | 改蓝图 | 尺寸或位置越界：门宽 ≥ 0.95、门高 ≥ 2.2；窗宽 ≥ 0.2；墙角各留 0.2 米；`sill + height` ≤ 净高 − 0.12 |
+| `DOOR_CONNECTION` | error | 改蓝图 | 门必须落在来源房间与 `to` 空间**同层的共边**上，且没有门槛 → 先让两间贴边，再把门移进共边范围 |
+| `WINDOW_CONNECTION` | error | 改蓝图 | 窗不能声明 `to`（窗不做可通行连接） |
+| `OPENING_PARTITION` | error | 改蓝图 | 门跨过了共墙分区端点 → 挪门；或让房间与目标空间的共边更长（同一墙线上每段共边是独立墙段） |
+| `OPENING_OVERLAP` | error | 改蓝图 | 同一墙面开口重叠；跨房间共墙的门只登记一次（两边各写一扇会重叠） |
+
+## 六、楼梯
+
+| 诊断码 | 级别 | 修复对象 | 怎么改 |
+|---|---|---|---|
+| `STAIR_FLOORS` | error | 改蓝图 | 楼梯要从低层空间连到高层空间（不同层，`to` 更高） |
+| `STAIR_ENDPOINT_KIND` | error | 改蓝图 | 楼梯端点不能是房间 → 接走廊、平台或庭院 |
+| `STAIR_GEOMETRY` | error | 改蓝图 | 宽 1.2—8 米、坡度 ≤ 45°（水平长度 ≥ 上升高度）、2—120 级整数、只能沿 X 或 Z 一个方向 |
+| `STAIR_LANDING` | error | 改蓝图 | 端点要落在平台边界上：平台沿行进方向向外留 ≥ 0.6 米，左右容得下梯宽 |
+| `STAIR_SPACE_INTERSECTION` | error | 改蓝图 | 楼梯投影与平层空间相交 → 把楼板拆成避开梯井的矩形（别用一块大矩形盖满整层） |
+| `STAIR_INTERSECTION` | error | 改蓝图 | 楼梯之间头部净空不足 2.2 米 |
+| `STAIR_COMFORT` | warning | 改蓝图 | 踏步偏陡或偏窄（> 0.22 米高、< 0.24 米宽）→ 调步数与水平长度；可保留，但要在交付说明里写明 |
+
+## 七、屋顶
+
+| 诊断码 | 级别 | 修复对象 | 怎么改 |
+|---|---|---|---|
+| `ROOF_REFS` | error | 改蓝图 | 屋顶引用了不存在或重复的空间 id |
+| `ROOF_RECTANGLE` | error | 改蓝图 | 同一屋顶引用的空间必须同层、同墙顶标高，且并集正好是完整矩形（不能有空洞，也不能用一个大矩形无意盖上中庭） |
+| `ROOF_SIZE` | error | 改蓝图 | 挑檐 0—2 米；坡顶 `rise` ∈ (0, 8]（省略按 1.8）；平顶省略 `rise` 或写 `0`，写其它值才报错 |
+| `ROOF_UPPER_FLOOR` | error | 改蓝图 | 屋顶穿进了上层空间 → 只给顶层做屋顶，或缩小范围 |
+| `ROOF_INTERSECTION` | error | 改蓝图 | 两个屋顶的包络相交（本版不自动处理交接屋脊）→ 合并或错开 |
+| `ROOF_MISSING` | warning | 改蓝图 | 该房间上方没有完整覆盖的屋顶 → 补屋顶；确实不补要在交付说明里写明理由 |
+
+## 八、状态声明
+
+| 诊断码 | 级别 | 修复对象 | 怎么改 |
+|---|---|---|---|
+| `STATE_EVIDENCE_REQUIRED` | error | 改蓝图 | 声明 `implementation: present`／`tests: passed`／`acceptance: passed` 必须给出处 → 没出处就退回 `unknown`／`pending` |
+| `STATE_CONTRADICTION` | error | 改蓝图 | `tests`／`acceptance` 为 `passed` 但实现不是 `present`；或 `approval: approved` 但设计不是 `detailed` |
+| `ACCEPTANCE_INCOMPLETE` | error | 改蓝图 | `phase: "accepted"` 要求每间业务房设计批准、实现、测试、验收记录齐备 → 建房阶段不要写 `accepted`，这四种事实由作者裁决 |

package/skills/specdev-building/references/layouts.md

@@ -0,0 +1,112 @@
+# 户型与坐标算术（按样板递推，不另发明户型）
+
+五份样板在 `assets/layouts/`，与 `tests/fixtures/building-*.json` **逐字节同内容**——生成器回归与漫游连通性回归跑的就是这五份输入（含 `single` 与 9 房派生的 `tower-9`）。其中 `row`／`court`／`tower` 沿用已验收配置，`single` 与 `tower-9` 是本轮新写的样板：**漫游观感与页面验收待作者**。
+
+| 样板 | 结构 | 屋顶 | 适用 |
+|---|---|---|---|
+| `single.json` | 一间房＋前庭（无走廊） | 房间一个坡顶 | 1 个业务 |
+| `row.json` | 一排房＋通长走廊＋前庭 | **一个组合屋顶**盖全部房间 | 2—8 个业务（默认） |
+| `court.json` | 北排＋东西厢，三面围中庭 | **按间拆开**，每间一个 | 作者指定要中庭时（4—10 个） |
+| `tower.json` | 一层前廊＋二层前廊，外置直跑梯接梯台 | **只盖顶层**，顶层房间合成一个 | 两层户型的 6 间原型（3＋3） |
+| `tower-9.json` | 同上，按 §四 的递推规则派生 | 同上 | 9—16 个业务（9 间：一层 5＋二层 4） |
+
+**样板里的业务 id、房间 id、名称都是演示值**：必须逐个替换成本项目清单里的真实 `businessId`，房间 id 按归一化规则重取，`roofs[].spaceIds`、门的 `to`、入口 `spaceId` 一并跟着改。**照抄的是结构与坐标算术，不是内容。**
+
+网格约定：米；X 向东，Z 向南，Y 向上；`rect.x`／`rect.z` 是中心；南 = +Z 方向。
+
+## 一、通用写法（五份样板共有）
+
+1. 先排**非房间**空间（前庭／走廊／平台），再把房间排到它们旁边——门的 `to` 才有落点。
+2. 房间与它前面的走廊/前庭**贴边**：房间的南边 `z1` 正好等于走廊的北边 `z0`（差 0.1 米就既不是共边也不算重叠）。
+3. 每个房间一扇门，开向它正对的那个空间，`offset` 取"该墙中心对齐处"（居中就是 0）。
+4. 窗开在外墙（与门相对那一侧），`offset` 0，宽度 ≤ 边长 − 0.4。
+5. 入口放在前庭**内部、离边缘 ≥ 1 米**：别贴着墙放——完整外观下墙体加人身半径会压住入口，人一进去就卡住。
+6. 一层的 `elevation` 取 0，`height` 取 3.6 左右；`style` 用本户型样板同款（`single`／`row`／`tower` 是 `warm-modern`，`court` 是 `chinese-timber`）；样板的 `construction` 块照抄（不许自己声称已实现/已验收）；`defaults`／`prototype`／`wallType`／`accent` **一概不写**（样板也不写，缺省值见契约——省略等于写上同样的缺省值，**改值才会改几何**）。
+7. **房间排列用"清单顺序"＝`docs/specdev/` 下业务目录名的字典序**：`row` 一族从西到东依次排（序号 `i` 从 0 到 N−1，`x` 递增），`tower` 按它分层（前 ⌈N/2⌉ 间在一层）。作者另有指定顺序（比如按重要性）时从作者，并在报告的设计表里按同一顺序列出。
+
+## 二、`row`（一排房，默认户型）
+
+样板值：6 间房，房宽 `W=9`、房深 `D=8`；走廊深 `C=8`、中心 `z_c=3`；前庭深 `Y=12`；边距 `M=2`；风格 `warm-modern`。
+
+| 部位 | 写法 |
+|---|---|
+| 房间 i 的 x | `x_i = (i − (N−1)/2) × W`（6 间 → −22.5 … 22.5） |
+| 房间的 z | `(z_c − C/2) − D/2 = −5`（房间南边＝走廊北边） |
+| 走廊 | `{x: 0, z: z_c, width: N×W + 2M, depth: C}`（6 间 → 宽 58） |
+| 前庭 | `{x: 0, z: (z_c + C/2) + Y/2, width: 与走廊同宽, depth: Y}`（→ z 13） |
+| 组合屋顶 | `spaceIds = [全部房间]`，`gable`，`rise 1.8`，`overhang 0.35` |
+| 门 | 南墙 `offset: 0`，宽 1.8，`to` 指走廊 |
+| 窗 | 北墙 `offset: 0`，宽 3 |
+| 入口 | 前庭内、离边 ≥ 1 米（样板 `{x: 0, z: 17}`，前庭 z∈[7,19]） |
+
+**改 N 或改 W 时，下面是一批必改项，改完一起核对**：
+
+1. 全部房间的 `x` 重排（`x_i` 递推）；
+2. 走廊宽度 = `N×W + 4`；
+3. 前庭宽度 = 走廊宽度；
+4. 组合屋顶的 `spaceIds` 跟着增减；
+5. 门、窗与房间一一对应（加房＝加一条房间＋一扇门＋一扇窗）；
+6. 改 `W` 时核对门窗宽度上限（`≤ W − 0.4`）。
+
+> **为什么走廊宽度是必改项**：不跟着改时诊断**可能一条都不报**——最外侧房间的南边与走廊仍有 ≥ 门宽 的共边，`DOOR_CONNECTION` 照样通过，但房间会探出走廊之外，房子看着是坏的却"校验通过"。这一项不能指望诊断兜底。
+
+**单房改宽同理**：不是只改一条 `rect`，而是同排所有房间的 `x` 重排、走廊与前庭宽度、组合屋顶覆盖范围一起更新。
+
+**不等宽房间（只把某一间改宽）用总宽公式**——上面的 `x_i` 只适用于所有房间同宽：
+
+- 总宽 `T = Σ Wᵢ`；第 i 间中心 `xᵢ = −T/2 + Σ(j<i) Wⱼ + Wᵢ/2`；
+- 走廊宽 = `T + 4`，前庭宽与走廊同宽；
+- 门仍取 `offset: 0`（相对本房间该墙中心），门窗宽度仍受**本房间**宽度限制（≤ `Wᵢ − 0.4`）。
+
+不等宽时若沿用等距公式（`(i − (N−1)/2) × W`），相邻房间会重叠或留缝：差 0.1 米既不是共边、也不算重叠，生成器会各建一堵墙甚至报 `SPACE_OVERLAP`。
+
+## 三、`court`（合院，作者点选）
+
+样板（6 间、中庭用 `corridor` 承担）：北排两间 `16×7` 在 `z=-8`；东西厢各两间 `6×7`，`x=±19`，`z=-4.5` 与 `z=2.5`；中庭 `32×11.5` 中心 `(0, 1.25)`；前庭 `32×12` 中心 `(0, 13)`；层高 3.8；风格 `chinese-timber`。
+
+- 三面围合：**每个房间都要与中庭共边**，门开向中庭那一侧；
+- 侧翼房间的门在 `east`／`west` 墙上，`offset` 要**现算**：`共边中点 − 房间该墙中心`（样板里是 ±1.75），填 0 基本必错；
+- 屋顶**按间拆开**（围合形状拼不成一个完整矩形），样板 `overhang` 取 0；
+- 加/减房间时，中庭与对面厢房的位置要一起挪，否则共边断掉。
+
+## 四、`tower`（两层，9—16 个业务）
+
+样板 6 间（一层 3＋二层 3），`tests/fixtures/building-tower-9.json` 是同一套规则的 9 间派生（一层 5＋二层 4）——**下面是随房间数联动的规则**，照它算就能派生 9—16 间，别只改样板里的房间条目。
+
+设：一层 `Ng = ⌈N/2⌉` 间、二层 `Nu = ⌊N/2⌋` 间（按清单顺序分）；两层总宽取**同一个** `T`；房深 `D = 6`；廊深 2；层高 3.6、楼板 0.18、二层地坪 ≥ 3.6＋0.18（取 4.2）。
+
+| 部位 | 规则 | 样板（T=16，3＋3） | 9 房派生（T=20，5＋4） |
+|---|---|---|---|
+| 房间宽 | 同层 `Wᵢ = T / N层`（不等宽时同层求和必须等于 `T`；全层等宽时按下方"选宽下限"取 `T`） | 5、6、5 ／ 4、8、4 | 一层 4×5；二层 5×4 |
+| 房间 x | `xᵢ = −T/2 + Σ(j<i) Wⱼ + Wᵢ/2` | −5.5、0、5.5 | 一层 −8…8；二层 −7.5…7.5 |
+| 房间 z | `−1 − D/2 = −4`（南边 z=−1 就是本层前廊北边） | −4 | −4 |
+| 两层前廊 | `{x: 0, z: 0, width: T, depth: 2}`，**上下对齐**（同宽同位置） | 16×2 | 20×2 |
+| 前庭 | `{x: 0, z: 1 + Yd/2, width: ≤T, depth: Yd}`；入口在庭内、离边 ≥ 1 米 | 8×6 在 z=4 | 10×6 在 z=4 |
+| 楼梯 | 从**一层前廊东端** `(T/2, 0)` 直跑到**梯台西边** `(T/2 + L, 0)`；`L ≥ 上升高度`（取 6）；`width 1.4`；`steps ≈ 上升 / 0.19` | (8,0)→(14,0)，22 级 | (10,0)→(16,0)，22 级 |
+| 梯台 | `{x: T/2 + L + 1, z: 1, width: 2, depth: 4}`（x∈[T/2+L, T/2+L+2]、z∈[−1,3]） | x=15 | x=17 |
+| 回廊 | `{x: L/2, z: 2, width: T + L, depth: 2}`：西端与本层前廊西端对齐，东端顶到梯台西边 | 22×2 在 x=3 | 26×2 在 x=3 |
+| 顶层屋顶 | `spaceIds = 二层全部房间`（一间也要写上），合成一个完整矩形 | 3 间 | 4 间 |
+| 门 / 窗 | 每间房门开向本层前廊（南墙 `offset: 0`、宽 1.8）；窗开北墙 `offset: 0`，宽度 ≤ `Wᵢ − 0.4` | 窗 3 | 一层窗 2.4、二层窗 3 |
+
+三条不能破的联动：
+
+1. **两层总宽必须相同（`T`）**：屋顶只盖顶层那一排，下层房间要落在它的覆盖范围里——**下层一旦越过屋顶覆盖范围**（典型是下层比上层宽，或下层房间探出顶层那排之外）就报 `ROOF_MISSING`；两层同宽同位置时才逐间都对得上。
+2. **楼梯占的是"缺口"**：楼梯投影不许压到任何平层空间（`STAIR_SPACE_INTERSECTION`），所以一层前廊只铺到 `x = T/2`、梯台从 `x = T/2 + L` 起，中间 `L` 米谁也不占；两层前廊同宽，正好让缺口只在东端出现一次。
+3. **回廊必须两头接上**：它要与本层前廊共边（z=1、x 重叠 ≥ 0.9）才走得通，同时东端顶到梯台西边；少了回廊，人从梯台下来就进不了二层前廊。
+
+**选宽下限**：全层等宽时 **`T ≥ 2.2 × N层`**（取间数多的那层，即 `T ≥ 2.2 × Ng`；16 间时一层 8 间 → `T ≥ 17.6`）。门固定 1.8 米宽、居中，两侧各要留 0.2 米墙角，房宽不足 2.2 米就报 `OPENING_SIZE`；房子排窄了有两种改法——把门改窄（最小 0.95 米）或把 `T` 放宽。窗宽另受 `Wᵢ − 0.4` 限制，窄房间要把窗一起收窄。
+
+改房间数时按这个顺序重算：`Ng／Nu → T（两层一致，且 ≥ 2.2 × Ng）→ 每层房宽 → 房间 x 重排 → 楼梯起终点（T/2 与 T/2+L）→ 梯台与回廊的 x／z → 屋顶 spaceIds`。
+
+**两层最容易错的三处**：只改层数不改标高（上下贯通）；把楼梯端点接到房间上（`STAIR_ENDPOINT_KIND`）；忘记给梯井留空（`STAIR_SPACE_INTERSECTION`）。
+
+## 五、写完先自查（比诊断更早发现问题）
+
+- 每间业务房都绑了清单里的 `businessId`，且没有一间房绑两个业务；
+- 房间与走廊/前庭**贴边**（不是差一点）；
+- 每扇门都落在共边上、整扇在墙段内、门窗宽度不挤墙角；
+- 每个房间上方都有屋顶，组合屋顶引用的房间同层同高、并集是完整矩形；
+- 入口在前庭里、离墙 ≥ 1 米；
+- 加房后走廊、前庭、组合屋顶都跟着改了；
+- `construction` 与 `status` 还是默认的安全值（没替作者声明实现与验收）；
+- `style` 是本户型样板的风格，`defaults`／`prototype`／`wallType`／`accent` 一个都没写。

package/skills/specdev-business/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: specdev-business
+description: 在作者需要为 SpecDev 工作台制作或修改业务规格文档、workflow 图与节点详情时使用：把需求整理成带出处的业务规格，画成通过 Archify showcase 校验的 workflow 图，配节点详情与空证据清单，按 docs/specdev 约定登记落盘，交作者验收并手动保存。作者批准实现范围后，按实现段指引组织实现方案与任务拆解（引用规格编号，不重新定义规则），实现完成后补录源码证据并交付差异核对报告。已有业务再次修改（改规则、改实现、纠错、补出处）按修改段指引识别影响面并同步受影响产物。纯讨论、普通问答和只读审查不触发本技能。
+---
+
+# SpecDev Business（业务设计与维护）
+
+把一段业务需求做成管理页能读的一整套产物：**业务规格文档 → workflow 图 → 节点详情 → 管理页登记文件**。本文件是入口，只管顺序、纪律和交付边界；具体手艺在各参考文件里，按需读取，不在此重复。
+
+**分段交付**：设计段面向新建设计与已有设计稿的修订，图与详情描述拟定设计（带明确标记）；新建设计证据清单留空不伪造，已有证据不因进入本流程清空。实现段在作者批准范围后按 [implementation.md](references/implementation.md) 组织（开工三问＋按需落 plan／tasks 文件），完成后按 [evidence-review.md](references/evidence-review.md) 补录证据并核对差异——两段已在真实登录业务实跑验证。已有业务再次修改按 [change.md](references/change.md) 走——修改段亦经登录业务实跑验证。无论哪段，本 Skill 都不宣称未经作者验收的内容已通过。
+
+## 适用范围
+
+- **用本 Skill**：制作或修改管理页可读的业务文档、workflow 图与节点详情。第一版做新建设计或已有**设计稿**的修订；已授权的修改直接走「修改段入口」（[change.md](references/change.md)），从设计段主流程遇到已实现的图或已带真实证据的图时，保留原内容并与作者确认走向，不把已有实现重标成拟定设计、不清空已有证据。
+- **纯讨论交方案**：作者问"有没有办法／有什么建议"时交付的是方案，不动手；实施须作者明确同意。
+- **已批准的小功能**按授权执行，一次只做一个，不顺带扩大范围。
+- **不做的**：代点保存版本、直接打快照标签、运行 deliver／preview／visual-check、迁移旧图、workflow 以外的图种（边界见 [workflow.md](references/workflow.md) §5 与 [project-contract.md](references/project-contract.md) §4）。
+
+## 设计段主流程（按序执行）
+
+本流程做设计（规格、图、详情与管理页登记）；只做实现时走下方「实现段入口」，不重走本流程。
+
+1. **确认业务与仓库**：业务名称、目标仓库、可提交分支、管理页地址与 repoRoot。缺失先问作者，不替作者选。动文件前检查目标仓的分支与工作区状态：首次修改前已有未提交改动，或过程中发现来源不明的改动，先问作者怎么处理；作者已明确允许保留并继续的，按批准范围操作，不重复询问。
+2. **整理需求与未决项**：按 [specification.md](references/specification.md) §2 提取角色／动作／数据／约束并做歧义扫描；问题集中提出、附候选答案，等作者裁决，不吞掉问题自己猜。
+3. **写业务规格**：用 [spec-template.md](assets/spec-template.md) 起草，写法按 [specification.md](references/specification.md)；拟定设计带明确标记，未定事项标【待裁决】；交付前过其 §6 自查。
+4. **从文档制图**：按 [workflow.md](references/workflow.md) §3 画 workflow.json，守 §3.2 铁律（新图 v2、ID 稳定、每个节点与分支有文档出处、禁从 HTML 反向提取、示例只借形状、不降档）。主路径定不了说明规格还不够，先回去补规格，不硬画。
+5. **节点详情与证据**：details.md 按 [project-contract.md](references/project-contract.md) §2.5 写——分节覆盖图上全部节点、守写作约束八条、四类分开说（拟定设计／已有实现／未实现／未核实）；evidence.json：尚无实现证据的新建设计用空清单、不伪造（§2.6），已有图带真实证据 refs 的保留原内容，不因进入本流程清空。
+6. **登记管理页文件与业务文档**：按 [project-contract.md](references/project-contract.md) §1、§2.1–2.3 补齐或维护三份说明文件（project.json／business.json／chart.json），已有文件只改要改的字段、其余原样保留；再把业务规格等文档路径登记进 business.json 的 `docs` 数组（仓库根相对路径），文档留在原位，只引用不搬动（§2.2）。
+7. **校验与三条守恒自查**：跑 [workflow.md](references/workflow.md) §4 的校验命令，通过判据五条全过；失败按 §4.3 两档修、§4.4 两轮上限；再过 [project-contract.md](references/project-contract.md) §3 检查清单五项；最后逐条对照下方三条守恒关系。
+8. **交结果**：按"交付报告"格式向作者汇报，等验收。
+9. **按授权提交**：验收通过并确认分支后，只提交本功能相关内容。
+10. **提醒作者查看并手动保存设计版**：交页面入口与检查点，页面效果由作者本人查看验收；保存版本由作者在管理页亲手点，Skill 只提醒不代点（[project-contract.md](references/project-contract.md) §4）。
+
+## 实现段入口
+
+业务规格获批、作者明确批准实现范围后，按 [implementation.md](references/implementation.md) 进入实现段：
+
+- 开工三问（怎么实现、影响哪里、每步验收什么）答清并经作者同意；简单功能不强制增加文件。
+- 沿用主流程第 1 步（仓库／分支／工作区检查）与第 8–9 步（交付、按授权提交）的纪律，快照仍由作者手动、AI 不代点；**不重走第 2–7、10 步**——图未变化时复用已有校验证据，不重新画图、不默认走设计版保存提醒；规格需修订按 specification.md 走，受影响的图先列出影响（同步流程见 [change.md](references/change.md)）。
+- 方案与任务引用规格编号，不重新定义规则；关键约束逐字进任务描述。
+- 业务逻辑与缺陷修复必须带必要测试；差异如实报告，不代作者裁决。
+- 实现完成并提交后，按 [evidence-review.md](references/evidence-review.md) 补录证据、做规格／图／详情／源码核对并交付六列差异报告；核对只读，差异先报告、经作者裁决再改，保存实现版仍由作者亲手点。
+- 交付报告用实现段格式：任务完成情况（含失败与未验项）、测试命令与结果、差异与未决项、提交状态；页面类改动附入口与检查点。
+
+## 修改段入口
+
+要再改已有业务或其产物——改规则、改实现、纠错、补出处或缺件（不要求规格、图、详情、证据、快照齐备）——按 [change.md](references/change.md) 进入修改段：
+
+- 核心口径：识别本次影响范围，更新受影响的实现和说明，验证新行为与相关旧行为，保留可追溯的历史。
+- 先分清四样：文档现在怎么规定、代码实际怎么做、本次要改成什么、哪些还不清楚；旧文档可能过时，不当成实现事实。
+- 不要求每次改齐六类文件：按修改情况（文字纠错／行为不变重构／规则变化／补出处）取用；语义未变的 ID 稳定，未受影响的图不重做，旧证据不因代码变化自动失效——相关实现变了才更新引用。
+- 沿用主流程第 1 步（仓库／分支／工作区检查）的纪律；交付用 change.md §6 的四件事格式，不套设计段固定报告；按授权提交；确需登记版本时按实际阶段提醒保存（不默认提醒保存设计版），保存可能返回已有快照，以实际返回为准。
+- 规则分层：通用要求在 change.md；Archify 产品约束引用各约定文件；审批次数、修复轮数、页面验收等工作习惯按目标项目规则执行（在哪个项目，就用哪个项目自己的守则）。
+
+## 按需读取
+
+| 要做什么 | 先读 |
+|---|---|
+| 写或改业务规格 | [assets/spec-template.md](assets/spec-template.md) ＋ [references/specification.md](references/specification.md) |
+| 组织实现方案与任务拆解 | [references/implementation.md](references/implementation.md) ＋ [assets/plan-template.md](assets/plan-template.md) ＋ [assets/tasks-template.md](assets/tasks-template.md) |
+| 补录源码证据、核对差异并出差异报告 | [references/evidence-review.md](references/evidence-review.md) |
+| 修改已有业务（改规则、改实现、纠错、补出处） | [references/change.md](references/change.md) |
+| 画图、自检、修校验失败 | [references/workflow.md](references/workflow.md) |
+| 落盘文件、详情、证据、登记、保存边界 | [references/project-contract.md](references/project-contract.md) |
+| 追溯某约定借自哪个外部来源 | [references/source-map.md](references/source-map.md) |
+
+同一会话已读且未变化的内容直接复用；引用链接是索引，只展开当前步骤用到的文件，不递归读完全部引用。
+
+## 三条守恒关系（交付前逐条自查）
+
+1. **文档定义规则，图帮助阅读**：图上的业务判断与有含义的分支，须能对应文档规则编号或显式的待裁决标记；发现图有文档没说的规则要指出，不擅自补完当作已同意。
+2. **代码与设计不一致要摆出来由作者裁决**，不许改文案让三份内容表面一致。
+3. **有源码出处 ≠ 业务正确**：实现事实、测试结果、业务差异分别报告。
+
+## 阶段边界
+
+- 拟定设计可带明确标记（如【设计】前缀、标题行注明"设计版"）供讨论；带标记不等于已批准。
+- 待裁决事项不得当已批准规则进入实现。
+- 设计段、实现段、证据核对与修改指引均已就位；证据补录、差异核对与修改指引均已在真实登录业务实跑验证；节点级证据 UI 属后续扩展，另行裁决后再扩。
+
+## 交付报告（固定格式，设计段）
+
+实现段不套用本格式，按「实现段入口」的报告项交付。
+
+1. **文件路径**：新增／修改的每个文件。
+2. **规则出处**：图上节点与分支 ↔ 业务文档规则编号的对应；对不上的列为待裁决。
+3. **校验命令与结果**：validate 命令原文、五判据结果、检查清单五项结果。
+4. **未决项**：待裁决问题清单，无则写"无"。
+5. **页面入口和检查点**：管理页地址、业务／图位置、作者该重点看什么。
+6. **提交状态**：分支与提交号，或注明"未提交，待验收"。
+7. **手动保存提醒**：提醒作者在管理页亲手保存设计版。

package/skills/specdev-business/assets/plan-template.md

@@ -0,0 +1,66 @@
+# 实现方案：<业务名称>——<功能或改动名>
+
+<!--
+  用法提示（填写时可保留，交付前删除本注释块）：
+  - 本模板与《实现段指引》（references/implementation.md）配套使用。
+  - 「<…>」是占位符，交付前必须全部替换为真实内容；不适用的按需章节整节删除，不写「无」。
+  - 本文件只解释"怎么实现、为什么这么选、影响哪里"；业务规则一律引用规格编号（FR-xxx），
+    不在本文重新定义——规格没写清的回规格补或标【待裁决】。
+  - 简单功能可以不落本文件：把开工三问（怎么实现 §2.1、影响哪里 §2.3、每步验收什么 §5）
+    答清并获得作者同意即可（见指引 §1）。
+-->
+
+- 状态：<草案 / 已批准>
+- 日期：<YYYY-MM-DD 创建；YYYY-MM-DD 最近修订>
+- 规格：<业务规格文档路径>（本次涉及：<FR-xxx 清单>）
+- 分支：<获批分支名>
+
+## 1. 目标与范围
+
+<!-- 一段话说清本次实现交付什么、明确不做什么；范围以作者批准为准，规则依据引用编号。 -->
+
+## 2. 方案
+
+### 2.1 怎么实现
+
+<!-- 主要做法：动哪些模块、加什么机制、数据怎么流。写给看得懂代码的人，不贴大段代码。 -->
+
+### 2.2 为什么这么选
+
+<!--
+  候选方案逐个说"做法—为什么没选"；没有像样的候选时写为什么这条路是显然的。
+  关键设计决定按「决定／理由／放弃的替代」留痕，事后能追溯。
+-->
+
+### 2.3 影响面
+
+<!--
+  逐项列出会动到的文件、模块、接口，以及可能被波及的现有行为；
+  涉及已有图／详情／证据的注明是否需要同步（同步流程见 references/change.md，先如实列出）。
+-->
+
+## 3. 技术上下文（按需）
+
+<!--
+  只填与本次实现相关、照项目现状能直接写的项；不展开成调研报告。
+  有未定的技术前提标【待澄清】，集中问作者，不猜。
+-->
+
+- 语言／框架版本：
+- 关键依赖：
+- 存储与数据：
+- 测试方式：<跑什么命令、看什么结果>
+- 运行／部署环境：
+
+## 4. 风险与回退（按需）
+
+<!-- 可能出错的点、兼容性顾虑、出问题怎么退回；没风险就整节删除，不写"无"。 -->
+
+## 5. 验证计划
+
+<!--
+  总览每一步拿什么证明它对了：测试命令、检查点、作者亲验项；
+  业务逻辑与缺陷修复必须带必要的相关测试。逐任务的验收写在任务清单（或等价表达）里。
+-->
+
+- <验证项一：<命令／操作> → <预期结果>（覆盖 FR-xxx／AC-xxx）>

package/skills/specdev-business/assets/spec-template.md

@@ -0,0 +1,111 @@
+# <业务名称>
+
+<!--
+  用法提示（填写时可保留，交付前删除本注释块）：
+  - 本模板与《业务规格编写指引》（references/specification.md）配套使用。
+  - 「<…>」是占位符，交付前必须全部替换为真实内容；不适用的按需章节整节删除，不写「无」。
+  - 新业务的规则从 FR-001、验收从 AC-001 起编；已有业务沿用原编号，新增续编，不重编号。
+-->
+
+- 状态：<拟定设计 / 已裁决>
+- 日期：<YYYY-MM-DD 创建；YYYY-MM-DD 最近修订>
+
+## 目标
+
+<!-- 全文唯一允许写成段落的地方：这个业务为谁解决什么问题。一到三句，不写做法。 -->
+
+<这个业务为 <谁> 解决 <什么问题>；成功时 <有什么不同>。>
+
+## 业务原则
+
+<!-- 不可违反的底线，争议时用它裁决。只说"必须怎样/不得怎样"的立场，具体规则去「规则」节。 -->
+
+- <原则一，如：已完成的操作不可自动撤销>
+- <原则二，如：同一份数据同时只能有一个生效版本>
+
+## 规则
+
+<!--
+  每条规则一个稳定编号，断言式写法，能判对错（"必须…"、"…不得…"）。
+  规则在本节统一定义；验收、边界、场景可写具体条件与预期结果，但须引用规则编号，
+  不新增或改变规则。
+  尚未定案的写法：FR-004 <要求描述>【待裁决：<具体问题>】——不替裁决人拍板。
+-->
+
+- **FR-001**：<系统必须……>
+- **FR-002**：<……不得……>
+- **FR-003**：<要求描述>【待裁决：<具体问题与候选答案>】
+
+## 边界与失败情况
+
+<!--
+  篇幅优先给这里：中断、重复、并发、越权、缺数据、数据坏了的时候，系统应该怎样。
+  每条写「什么情况 → 应有什么结果」。结果若构成业务规则，规则编号进「规则」节、本条引用；
+  本节不另立规则。顺利路径少写——它的文档价值低。
+-->
+
+- <重复提交同一请求 → 不得产生两次副作用（FR-00x）>
+- <操作中途中断 → 重新进入能恢复到中断前状态（FR-00x）>
+- <输入为空或格式不对 → 明确指出问题所在，不静默失败（FR-00x）>
+
+## 验收
+
+<!--
+  什么算做到。验收判卷：让人能判断实现的对错，不是把实现步骤抄进来。
+  两种条目均可：场景式（给定…当…那么…）与度量式（可核实的指标）；
+  每条注明覆盖哪条规则编号；规则没写清的先回「规则」节补，不在验收里另立规则。
+-->
+
+- **AC-001**：给定 <条件>，当 <动作>，那么 <预期结果>（覆盖 FR-001）
+- **AC-002**：<可度量的判据，如：整个流程 X 分钟内可完成>（覆盖 FR-00x）
+
+## 场景与用法（按需）
+
+<!--
+  多角色、多步骤的复杂业务才保留本节；简单业务整节删除。
+  每个场景一段：谁、在什么情况下做什么、完成后得到什么、为什么重要。
+  场景不定义规则——规则去「规则」节编号，这里只叙述和引用。
+-->
+
+### 场景：<标题>（优先级 P1）
+
+<谁>在<什么情况下><做什么>，完成后<得到什么>。
+为什么重要：<一句话>。
+
+**验收场景**：
+
+1. 给定 <…>，当 <…>，那么 <…>（覆盖 FR-00x）
+
+## 领域词汇（按需）
+
+<!-- 同一个词在两处理解不同时保留本节；项目已有全局词汇表时优先引用，不重复定义。 -->
+
+### <术语>
+
+- **定义**：<这个词在本业务里精确指什么>
+- **不是什么**：<排除容易混淆的含义，如：不是指 X，那是另一个词>
+
+## 假设与默认（按需）
+
+<!--
+  编写者按行业惯例或上下文补的默认值，必须逐条列在这里，与已拍板的规则分开。
+  事后被追认的：构成规则的更新对应 FR；澄清记录保留原话、时间与关联编号；
+  其他决定更新相应正文。本节不残留已追认条目。
+-->
+
+- <假设：<填写内容与理由>（来源：行业惯例 / 上下文推断，尚未经业务方确认）>
+
+## 澄清记录（按需：仅业务决策场合）
+
+<!--
+  仅在开发新功能、修改原有业务逻辑时保留本节；日常开发问答不记录。
+  只记录影响业务的决策问题。每条标注三态之一：
+  作者已拍板（原话＋时间戳）/ AI 建议 / 待裁决。原话逐字引用，宁可与分析重复。
+-->
+
+### <YYYY-MM-DD> · <主题>
+
+- **问题**：<影响业务的决策问题>
+- **作者决定**（<YYYY-MM-DD> 原话）：「<逐字引用>」→ 落点：<FR-00x（构成规则时更新「规则」节）／相应正文章节>
+- 或 **AI 建议**（<YYYY-MM-DD>）：<建议内容，尚未经作者认可>
+- 或 **待裁决**：<问题与候选答案，正文相应处已标【待裁决】>

package/skills/specdev-business/assets/tasks-template.md

@@ -0,0 +1,36 @@
+# 任务清单：<业务名称>——<功能或改动名>
+
+<!--
+  用法提示（填写时可保留，交付前删除本注释块）：
+  - 本模板与《实现段指引》（references/implementation.md）配套，从**已批准**的方案拆解；
+    方案未获批不拆任务。
+  - 「<…>」是占位符，交付前必须全部替换；简单功能可以不落本文件，
+    把任务列在方案或交付报告里即可（见指引 §1）。
+-->
+
+- 输入：<plan.md 路径，或"方案见 <哪里>，已获作者批准（YYYY-MM-DD）">
+- 规格：<业务规格文档路径>（本次涉及：<FR-xxx 清单>）
+- 分支：<获批分支名>
+
+## 任务
+
+<!--
+  条目格式：- [ ] T001 <做什么，含文件路径>｜验：<怎么验>｜据：FR-xxx
+  规则：
+  1. 编号从 T001 连续分配，一经使用不改号；完成后勾选，失败不勾并注明原因。
+  2. 每条必须带「验」：完成后跑什么命令／看什么结果——写不出验收动作的任务不进清单。
+  3. 每条必须带「据」：引用规格编号；涉及关键约束（数量上限、格式、权限、时间窗）时，
+     把规格里的约束原文逐字抄进任务描述，不留实现期自由裁量。
+  4. 默认串行执行；确有依赖的在条目里注明（依赖 T00x），不标并行标记。
+  5. 业务逻辑与缺陷修复的「验」必须是真实测试或可重跑的检查，不拿"看起来对了"充数。
+-->
+
+- [ ] T001 <……>｜验：<……>｜据：FR-xxx
+- [ ] T002 <……>（依赖 T001）｜验：<……>｜据：FR-xxx
+
+## 完成标准
+
+<!--
+  全部任务完成且逐条验收结果如实（含失败与未验项）；实现与规格不一致处列为差异交作者裁决，
+  不改文案抹平；没有差异就写"无差异"，不硬凑。
+-->