diff --git a/plugins/studio/.codex-plugin/plugin.json b/plugins/studio/.codex-plugin/plugin.json
index ecb5bc0..86da5e1 100644
--- a/plugins/studio/.codex-plugin/plugin.json
+++ b/plugins/studio/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "studio",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "DETA Studio 插件：以 AML 为唯一事实源编辑建筑模型，编译为建筑模型并执行规则校验。",
   "author": {
     "name": "DETA",
diff --git a/plugins/studio/package-lock.json b/plugins/studio/package-lock.json
index 70d1632..922ea09 100644
--- a/plugins/studio/package-lock.json
+++ b/plugins/studio/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "deta-studio-plugin",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "deta-studio-plugin",
-      "version": "0.3.8",
+      "version": "0.3.9",
       "license": "Proprietary"
     }
   }
diff --git a/plugins/studio/package.json b/plugins/studio/package.json
index 422f76b..e11eb80 100644
--- a/plugins/studio/package.json
+++ b/plugins/studio/package.json
@@ -1,6 +1,6 @@
 {
   "name": "deta-studio-plugin",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "DETA Studio：AML 建筑模型读写与编译校验（Codex 插件 / dsh 组合包 双壳）",
   "type": "module",
   "license": "Proprietary",
diff --git a/plugins/studio/skills/aml-design/SKILL.md b/plugins/studio/skills/aml-design/SKILL.md
index 1b5a6e5..ce44328 100644
--- a/plugins/studio/skills/aml-design/SKILL.md
+++ b/plugins/studio/skills/aml-design/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: aml-design
-description: 以 AML 为唯一事实源读写建筑模型并编译校验。当用户要求创建/修改建筑方案、房间布局、层高、开洞、围护结构或做建筑性能相关的模型准备时使用。
+description: 以 AML 为唯一事实源读写建筑模型并编译校验；含设计流程决策闸门、阶段准入门槛与 GSA 端口口径。当用户要求创建/修改建筑方案、房间布局、层高、开洞、围护结构或做建筑性能相关的模型准备时使用。
 ---
 
 # DETA 建筑性能设计（AML）
@@ -34,6 +34,86 @@ description: 以 AML 为唯一事实源读写建筑模型并编译校验。当
 用户提到建筑方案、房间/空间布局、层高、墙体开洞（门窗）、围护结构、体形系数、
 建筑模型校验，或需要为后续能耗/日照/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` | 门窗阶段写任何 `<aperture>` 前 |
+| `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 必须在排房间之前定下来。
+- **禁止替用户做这些决策**；也禁止用「是否合理？」这类确认代替方案选择。
+- 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` 是设计任务书，**不参与编译**；`<solid script="…">` 的几何脚本必须存在于工作区（内容随编译请求携带，取不到即**显式失败**）。
+
+```
+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）。
+
 ## 编辑与校验分工（先搞清"哪份文件是真值"）
 
 本插件挂的是**本机 MCP**：引擎工作区才是编译/校验/模拟读的真值（启动器 stderr 会回显路径）。