住宅设计通识指引
把住宅设计领域的公开通识（规范条文口径 + 行业惯例 + 常见场景索引）整理成一组可被 AI 在真实设计任务中调用的
方法论资产：设计心智模型、方案推进 SOP、跨专业协同决策框架、报建与汇报要点、常见坑点与自检清单。
定位与目标
- 面向：建筑设计从业者、方案设计负责人、需要建立系统工作方法的建筑师。
- 产出：不是课程逐字稿，而是可迁移的方法论——原则、框架、SOP、清单、判断句。
- 边界：仅提炼原作者公开表达的方法论；具体数字、规范条文号、人名、项目名等若来源不清，
一律标待核项，不臆造。
来源与授权边界（合规红线）
- 历史沿革（⚠️ 非当前内容来源）：本包早期版本曾参考用户合法持有的第三方建筑方案设计培训资料（版权归原作者）。
- 当前内容来源（2026-09-12 Plan B 起生效）：模块内容已全面改为公开源重建——行业通识 + 公开资料（规划技术规定、现行国标、公开行业文献）。随包发布的内容不依赖、不引用、不含任何课程转写稿；转写稿仅本地留存作溯源，不随包发布。
- 不绕过任何登录、会员、付费墙或 DRM 获取内容；不批量搬运任何版权逐字全文；只输出摘要、框架、学习笔记与方法论。
- 所有知识均带来源标注（文件名 + 覆盖段落），可追溯。
发布范围与来源声明（publish scope）
> 定性（2026-09-12 拍板：B 独立线 + 剥离转写稿层）：本包为独立产品线，非万工系列；slug zhuchuang-jianzhu-shejishi 与 displayName「住宅设计通识指引」均不含 wangong- / 万工- 前缀，不计入万工 9 包系列，治理自管。但仍须守 SkillHub 平台合规底线（去标识 + 版权来源声明）——独立线隔离的是品牌风险，不是合规豁免。
- 发布包范围：
- ✅ 随包发布：
SKILL.md+references/modules/（M01–M16 + INDEX）+scripts/（门禁脚本）+references/内容来源判定.md、knowledge-base/KB.md。 - ⚠️ 2026-09-30 更正：上版此处误将
source-coverage-report.md/web-arch-distill-20260910.md列为随包发布——二者早由.publishignore排除，实际不在包内。 - ❌ 不随包发布：
references/knowledge-part-*.md（共 718 份原始 ASR 转写稿，2026-09-30 实查口径：references/ 主目录 554 +_transcripts_raw/82 +_archived_truncated/74 +_dup_parts_20260911/8 = 718）——属作者内部溯源资料，仅本地留存，不发布。打包时由skillhub-publish-runbook的build_skill_zip.py读取本目录.publishignore（knowledge-part-*.md）自动排除（已 dry-build 验证：转写稿全数[publishignore]跳过，modules 全数收进包）。 - 悬空引用说明（2026-09-29 更新）：早期模块内的"来源 part-NNN"内部溯源指针已全部移除（末一处为 M15 的 13 处内联课程出处，已于 2026-09-29 去课程化清理，全包 modules 内联课程出处现为 0）。因此不再存在任何指向包外转写稿的悬空引用；用户无需、也无法取得任何包外原文。
- 来源声明（模块编排）：本包方法论模块整理自公开资料与行业常识；模块编排为独立整理，非课程逐字搬运。
合规证据件：references/内容来源判定.md（M01–M04 抽样 24/24 为 A 类行业通识，X 类课程独创 0 条）。
规格总纲：references/modules/M0-主题规格表.md（来源分级 A/B/C/X、七段结构模板、验收口径、合规红线）。 - ⚠️ 红线恢复 HOLD：本地
publish: hold（frontmatter 字段）保持。关于"v0.3.0 曾于 2026-09-13 发布"的本地记录已无法被平台数据佐证——2026-09-30 经 SkillHub API 核验：GET /api/v1/skills/zhuchuang-jianzhu-shejishi/versions→ HTTP 404（对照wangong-xiaofang-sheji→ 200，12 版）；GET /api/v1/download?slug=zhuchuang-jianzhu-shejishi→ HTTP 404 "Skill not found"。即平台无此 slug，所谓"线上 v0.3.0 待下架"不成立，无需下架动作（CLI 亦无 unpublish；若确曾发布则须 web UI 或授权删除 API，但当前 API 证据指向从未在平台落库）。重新发布前置条件（缺一不可）：① 跑 M3 独立性验证三项（逐段 ASR 转写稿相似度比对 / 20–30 条核心论断"独立找到 vs 事后匹配" / 新模块结构 vs M01–M04 重叠度），且结论达标；② 版权闸 + 质量闸仍满足；③ 三闸全过，方走四验闭环。严禁再以"版权风险降低"单闸论证解红线的偷换逻辑。
当前构建状态
- 状态：模块层 M01–M08 已全部建成（2026-09-12 Plan B 完成），规格总纲 M0 同批建立。
- 🔴 2026-09-12 Plan B：公开源重写完成（重大变更）
- 缘起：M01–M04 的方法论骨架本是行业通识，溯源却挂在第三方课程转写稿上 → 给通用知识凭空背上版权债。
- 做法：溯源整体切换为「行业通识（A 类）+ 公开资料（B 类）」；不是重写知识，是重写知识的出处（骨架原样保留）。
- 结果：M01–M04 重写完成；M05–M08 直接按公开源新建，不再依赖 61 个未转写的 .flv——原最大阻塞解除。
- 证据：
references/内容来源判定.md（抽样 24/24 = A 类，X 类 0 条）；规格见references/modules/M0-主题规格表.md。 - 遗留：八模块均为中置信——各模块【待核项】回现行规范后可升格高置信。
- ⚠️ 2026-09-11 流程纠正（重要）：此前 09-07~09-11 由夜间自动化连续跑了 4 夜，产物仅 ASR 转写稿、零方法论蒸馏（因自动化环境
XFYUN_API_KEY缺失，脚本按设计降级），等于"为蒸馏而蒸馏"。现改为：
1. 不再新建自动化任务（已停用住宅设计通识教程·夜间蒸馏-23点/-3点、CAD资料库夜间蒸馏）；
2. 蒸馏在会话内按批进行（AI 直接阅读转写稿 → 归纳方法/SOP/清单/判断句 → 写入references/modules/）；
3. 产物必须落成知识模块并进入本 skill，不允许只堆积转写稿。 - 三层资产（务必区分）：
references/modules/= 蒸馏后的方法论模块（可引用，SKILL.md 直接调用）；references/knowledge-base/KB.md= 知识库长期记忆（跨模块聚合索引：已知什么/待核什么/缺口在哪），每次会话内蒸馏升格模块时同步维护；references/knowledge-part-NNN.md= 原始 ASR 转写语料（仅溯源、禁止引用；⚠️ 本地留存，不随包发布）。- 主源（按下载进度自动拾取，多根）：用户本机百度网盘中的建筑方案设计培训课程资料（两个互补根，
均递归含子目录，内容互补——其一按「公开课/居住建筑设计技法」分章，另一为 001—099 概论系列）。
百度网盘下载中临时文件*.baiduyun.p.downloading自动跳过；下载完成改.flv即被自动拾取。
具体本地目录路径仅存于蒸馏管线配置（不随包发布），运行方以--incoming-dir/--root显式传入。 - 兜底源（手动投放）：运行方本机素材仓的
incoming/子目录（由--root指定，不写死绝对路径）。 - 剩余原料（Plan B 后已非阻塞）：源目录
01…实有 138 个完整.flv（第001–138节，2026-09-12 实查），已转写 77 个 → 尚余 61 个未转写。
⚠️ Plan B 之后，模块内容不再依赖这些转写稿：M05–M08 已按行业通识直接建成，故 61 个未转写 .flv 不构成任何阻塞。
转写稿仅作本地内部溯源留存，禁止引用、不随包发布；是否继续补转写属低优先级。
知识资产结构
references/
├── modules/ ← ① 蒸馏后的方法论模块（可引用，本 skill 的主资产）
│ ├── M0-主题规格表.md 规格总纲：来源分级 / 七段模板 / 验收口径 / 合规红线
│ ├── INDEX.md 模块清单 + Plan B 说明
│ ├── M01-方案设计流程与设计心智模型.md （A 类；09-11 骨架 / 09-12 Plan B 重写）
│ ├── M02-室内布局设计.md （A 类；09-11 骨架 / 09-12 Plan B 重写）
│ ├── M03-户型设计.md （A 类；09-11 骨架 / 09-12 Plan B 重写）
│ ├── M04-场地设计.md （A 类；09-11 骨架 / 09-12 Plan B 重写）
│ ├── M05-住区规划与实例.md （A 类；09-12 Plan B 新建）
│ ├── M06-别墅设计.md （A 类；09-12 Plan B 新建）
│ ├── M07-地下车库设计.md （A 类；09-12 Plan B 新建）
│ └── M08-办公楼方案设计.md （A 类；09-12 Plan B 新建）
├── 内容来源判定.md ← 合规证据件（抽样 24/24 = A 类；随包发布）
├── knowledge-part-001~085.md ← ② 原始 ASR 转写语料（⚠️ **禁止引用、本地留存、不随包发布**）
├── INDEX-transcripts-local.md 转写稿分片索引（脚本维护；❌ **不随包发布**）
├── source-coverage-report.md 运行覆盖报告（脚本维护）
├── web-arch-distill-20260910.md 公开源蒸馏（gooood + 搜建筑）← B 类可引用资产
└── knowledge-base/KB.md 长期记忆索引（已知什么/待核什么/缺口在哪）
> 引用纪律：一切对外答复先读 modules/；knowledge-part-* 只在需要回溯原话时才打开，且不得把转写稿语句当结论输出（ASR 数字误差率高）。
蒸馏管线（本技能如何生长）
两种模式，优先会话内蒸馏：
- A. 会话内按批蒸馏（当前主用，2026-09-11 起）：AI 直接读
knowledge-part-*→ 归纳 → 写references/modules/MNN-*.md→ 更新modules/INDEX.md。不依赖任何 API Key，不受降级影响（仍须跑门禁脚本做收尾断言，见第 7 步）。 - B. 脚本管线（仅用于"新增原料 → 转写"这一段）：
scripts/distill_pipeline.py负责抽音频 + 本地 ASR，产出knowledge-part-*；
该方法需XFYUN_API_KEY才能完成 LLM 蒸馏，缺失时只产出转写稿（必须随后走 A 模式补蒸馏）。
- 扫描来源：默认递归扫描
MONITOR_ROOTS（F 盘两个教程目录 +incoming/兜底），
自动跳过.downloading/.baiduyun临时文件与已登记文件；也可用
--incoming-dir <目录1> --incoming-dir <目录2>显式指定多根（覆盖默认）； - 视频/音频 → 用 imageio-ffmpeg 自带的 ffmpeg 抽音频 → 本地 faster-whisper 离线 ASR；
- 字幕/文稿 → 直接清洗读取；
- 调用讯飞 MaaS（OpenAI 兼容接口，凭证走
XFYUN_API_KEY）蒸馏为方法论资产；
Key 缺失时此步跳过，只落转写稿——此时必须走 A 模式（会话内蒸馏）补齐模块； - 写入
references/knowledge-part-NNN.md并更新INDEX.md； - 监控模式（
--keep-source）只登记done/processed.log不去重移动；默认模式将源文件移至done\，生成覆盖报告。 - 🚧 蒸馏门禁（必跑，反静默降级）：每次蒸馏运行结束，无论 A/B 模式，必须运行
scripts/verify_module_gate.py --transcripts-dir references --modules-dir references/modules
断言模块层非空。只要本轮产出了转写稿而modules/为空，脚本以exit code 1报警——0 模块 = 失败，非静默通过。
> 这是对旧根因的焊死：旧自动化 prompt 把"跳过 LLM 蒸馏"明文预批为"预期降级非失败"，导致 Key 缺失→0 模块→假成功；本门禁反向强制"缺模块即失败"，并附 dry-run 反事实对照（转写+0 模块→exit 1 报警；转写+模块→exit 0 通过）。门禁逻辑见scripts/verify_module_gate.py注释。
环境变量：
- XFYUN_API_KEY：（必填）讯飞 MaaS 凭证，缺失则仅保留转写稿并跳过蒸馏。
- XFYUN_API_BASE：（可选）默认 https://maas-api.cn-huabei-1.xf-yun.com/v2。
- XFYUN_MODEL：（可选）默认 xopdeepseekv4pro0813。
- WHISPER_MODEL：（可选）ASR 模型尺寸，默认 base。
> ⚠️ 本机必须显式设 WHISPER_MODEL=small（2026-09-08/09/10 三次实测）：
> 默认 base 未在本地缓存，faster-whisper 会尝试联网下载并被网络阻断
> （WinError 10054，5/5 失败）；本地仅缓存 faster-whisper-small。
> 标准启动式：
> WHISPER_MODEL=small PYTHONIOENCODING=utf-8 <venv-python> scripts/distill_pipeline.py --incoming-dir <dir1> --incoming-dir <dir2> --keep-source --domain zhuchuang
> 单文件（30–45 分钟视频）small 模型 CPU 转写实测 ≈16 分钟，大批量需后台跨检查点续跑。
调用方式
当用户咨询住宅设计相关工作方法、方案推进、设计决策、跨专业协同、汇报报建等话题时：
- 先读
references/modules/INDEX.md，按主题定位到模块：
M01 流程与心智 / M02 室内布局 / M03 户型 / M04 场地 / M05 住区规划 / M06 别墅 / M07 地下车库 / M08 办公楼；
模块的来源分级与写作规格见modules/M0-主题规格表.md。 - 读对应
modules/MNN-*.md，结合问题给出结构化建议（模块内已含 SOP、判断规则、参数口径、行动清单）； references/knowledge-part-*为禁止引用的原始转写语料（Plan B 后更不得作为内容来源）；- 模块内标
【待核项】的数值与规范条文号，一律提示"须回现行规范/当地条例核对"，不得当作结论输出； - 八模块均为中置信：内容属行业通识，但未经逐条回规范复核——对外答复时须提示置信级别。
