dsh-crwu-workbench 0.0.10

package/common/skills/crwu-dws/references/02-/347/274/223/345/255/230/344/270/216/345/205/234/345/272/225/346/237/245/346/211/276/350/247/204/350/214/203.md

@@ -0,0 +1,119 @@
+# crwu-dws references/02 —— 目录缓存与兜底查找规范（缓存层 / node-index / M3 协议）
+
+> 版本 v1.3（2026-09-15：随 crwu-dws v0.6，node-index 条目新增 `extension`/`contentType` 并作为 §5 正文取数通道判据）。
+> 版本 v1.2（2026-09-08：v1.1 随 crwu-dws v0.3.1 新增 §2 缓存身份与名一致性清理层，原 §2–6 顺移为 §3–7；v1.2 随 v0.4 新增 node-index 全路径键 `by_path`（M3 路径寻址）与路径命中报告口径）。
+> 本文档随技能安装（源仓与运行时双份）；
+> 改前先读本技能 `SKILL.md` §5.0 与 references/00（快照 schema）。
+
+## 1. 核心原则（用户口径，不可违反）
+
+1. **目录可缓存**：目录结构与 nodeId 映射变化低频 → 本地缓存。
+2. **正文不缓存**：正文内容永远现场从钉钉导出（下载时点=钉钉当前版）；M2 下载物仅供本次审核，跨审核必须重新下载。
+3. **缓存不是事实源**：事实源 = 钉钉实时。缓存只用于"少跑在线遍历"；任何"存在性"权威结论须来自一次成功刷新或如实降级。
+4. **未命中必刷新**：缓存查不到 → 自动在线刷新 → 重查；仍无 → 如实报告"没找到"，不编造。
+5. **防幻觉**：报告必须带结论依据标签（§6）；刷新失败不得用旧缓存冒充新鲜。
+6. **缓存名一致（v0.3.1）**：缓存目录只对与其身份一致的目标库有效；身份（§2）与 skill 目标库名不一致 → **先清理该缓存目录、在线重下后再用**，禁止把别的库的缓存当目标库索引（跨库误命中；SKILL.md §5.0）。
+
+## 2. 缓存身份与名一致性清理（缓存库名 ≠ 目标库名 → 清理重下）
+
+1. **身份**：每个缓存目录的身份 = `.cache-meta.json.space`：`{name, workspaceId}`（服务端真实返回；两字段齐备才可证实身份）。
+2. **一致性基准（目标库名）**：skill 默认目标名「中瑞世联评估审核知识库」或本次指定库名。M1 与 M3 刷新路径叠加 P1 解析结果，按 name+workspaceId 双匹配对账；M3 命中路径不发起在线遍历，以请求库名做名级对账（workspaceId 一致性在写缓存时已由 P1 校验并固化于 meta）。
+3. **判据与动作**：身份与目标不一致（名级或双匹配）→ **整体删除该缓存目录**（正式 4 文件 + 残留 `.tmp-*`），再**在线重下目标库目录结构**（= 一次成功完整遍历 → §4 写缓存原子替换 → 重查）。meta 缺失/损坏 → 身份不可证实：目录名 ≠ 目标库名 → 同前删除重建；目录名 == 目标库名 → 不删除，按 §7 缓存损坏走刷新覆盖重建。
+4. **范围与安全**：删除只作用于 `dws-dir-cache`——目录缓存 = 可再生中间产物、无正文，删除即清理协议、不违红线；不碰 M2 当前审核 `knowledge/` 工作集或远端。删除失败 → 该缓存按不可用处理并报告路径问题，不静默复用。
+5. **防跨库误命中**：node-index 查找只允许发生在与本次目标一致的缓存目录内；被清理目录禁止在清理前被查询。
+6. **清理报告**：删除动作与原因必须可见（"已清理不一致缓存：<目录>（缓存 space=<…>，目标=<…>）"）。
+
+## 3. 缓存布局与文件格式
+
+```
+~/.crwu/knowledge/dws-dir-cache/<库名>/            # 多库各一份；同名多空间 → 追加 -<spaceType>（身份见 §2）
+├── 目录快照.json       # crwu.kb-catalog.snapshot.v1（references/00）——目录元数据唯一事实文件
+├── 目录树.md           # 人读视图（快照渲染，不单独成为事实）
+├── node-index.json     # 查找索引（可由快照重建；写缓存时同步重建）
+└── .cache-meta.json    # 缓存元数据（last_successful_at/evidence/统计）
+```
+
+- 缓存目录内**禁止出现任何正文内容文件**（md 正文副本、导出文件等）；`.tmp-*` 只允许出现于原子替换的瞬时窗口，替换完即无。
+- 父目录 `~/.crwu/knowledge/` 不可写 → 报告路径问题，不静默改落点、不把正文改存他处绕过红线。
+
+### node-index.json（`crwu.kb-dir-cache.nodeindex.v1`）
+
+```jsonc
+{
+  "schema": "crwu.kb-dir-cache.nodeindex.v1",
+  "space": { "name": "…", "workspaceId": "…", "spaceType": "…" },
+  "built_from_snapshot_at": "ISO8601",
+  "by_node_id": { "<nodeId>": { "name": "…", "type": "file", "extension": "adoc", "contentType": "ALIDOC", "folderPath": "顶层folder/子folder…或空", "depth": 1, "parentNodeIds": ["…"] } },
+  "by_name": { "<精确名称>": ["<nodeId>", "…"] },  // 同名多命中 → 数组多条
+  "by_path": { "<目录链>/<名称>": ["<nodeId>"], "<目录链>/<文件夹>/": ["<nodeId>"] }  // 全路径键（v0.4，路径寻址）；folder 键尾带 "/"
+}
+```
+
+- `folderPath` = 从根到父的 folder 名称链（不含 node 自身），用于报告树路径上下文；由快照推导，快照缺字段则留空并在索引条目注 `path_partial:true`。
+- **`extension`/`contentType` 随快照同步落索引（v0.6）**：M2/M3 的取数通道由它判定，因此索引必须携带；由旧快照（v0.6 前）重建的索引该字段为 `null` → 取数前按 §5 第 2 步对该 nodeId 补一次 `wiki +node-get`，**不得按名称后缀猜**。
+- 名称索引 key 使用**原样精确名**（不折叠大小写/空白/全半角）；查找时同样精确比对——歧义宁可多命中消歧，不做模糊近似命中。
+- `by_path` 全路径键 = 从根起的完整层级链（`folder/…/名称`；folder 节点键尾加 `/`）：供 M3 文件级精确命中 / 目录前缀展开（键前缀匹配）；同层同名等罕见冲突 → 值可为 nodeId 数组并在报告全列消歧；由快照重建，写缓存时与 `by_name` 同步生成。
+
+### .cache-meta.json（`crwu.kb-dir-cache.meta.v1`）
+
+```jsonc
+{ "schema": "crwu.kb-dir-cache.meta.v1",
+  "space": { "name": "…", "workspaceId": "…", "spaceType": "…" },
+  "source": "dingtalk-live",
+  "last_successful_at": "ISO8601",      // 最近一次成功完整遍历并写缓存时刻
+  "last_refresh_attempt_at": "ISO8601",
+  "last_failure": null,                 // {at, error} 或 null
+  "stats": { "total_nodes": 0, "complete": true },
+  "profile": { "id": "…", "isOrgCurrent": true } }
+```
+
+## 4. 写缓存（原子替换；M1 与 M3 刷新共用）
+
+1. 遍历完成且 P4 计数一致（`failures=[]`、每页 `autoPageComplete=true`）才进入写缓存；
+2. 依次写 `.tmp-目录快照.json` / `.tmp-目录树.md` / `.tmp-node-index.json` / `.tmp-.cache-meta.json` → 全部成功后再逐个 rename 覆盖正式文件（顺序：meta 最后覆盖，保证 meta 落成即代表整套新缓存可见）；
+3. rename 失败 → 保留旧缓存，`last_failure` 记录，摘要说明"缓存未更新：<原因>"；
+4. `complete=false`（遍历不完整）→ **不写缓存**（保留旧缓存），并在报告标注。
+
+## 5. 正文实时拉取协议（M3 命中取正文 / 任何"要最新内容"场景）
+
+1. 目标 = 已知 nodeId（来自缓存命中或刷新后命中）。
+2. **判通道**：读缓存条目的 `extension`；缺失/`null`（旧缓存）→ 对该 nodeId 补一次节点元数据读取（只读；结果记入本次 evidence，不回写——回写由 §4 写缓存整批完成）。DSH 下这一步由 `crwu_audit_knowledge_materialize` 内部完成。
+3. **取正文（按 `extension` 分流，与 M2 §1 表一致）**：
+   - `adoc` → 走导出通道（manifest 里 `channel=export`）；
+   - `md` / `txt` → 走原样下载通道（`channel=download`；原件即正文，不转换）；
+   - 其余类型 → 如实报告"该类型（`<extension>`）不提供正文"，**不下载、不伪造、不改用 `doc +export` 硬试**。
+4. 导出/下载位置 = **本次审核工作目录或系统临时目录**（不属于缓存层）；回执 `sizeBytes>0` 即终态。
+5. 交付内容仅供本次审核推理；进入案例 `knowledge/` 时按 M2 单文件语义登记 manifest，进入临时目录时使用完即清理；两者都**不进缓存层且不得跨审核复用**。
+6. 取数失败 → 如实报告（失败原因 + 不提供任何"缓存正文"替代——因为缓存根本没有正文）。
+
+## 6. M3 报告口径（结论依据标签必含其一）
+
+| 情形 | 报告模板 |
+| --- | --- |
+| 缓存命中 | `缓存命中（generated_at=<…>）：<名称>（<type>），目录 <folderPath>，workspaceId=<…>（<spaceType>）`；要正文 → 转 §5 |
+| 名称/路径多命中 | `同名/同路径 <n> 个（缓存 generated_at=<…>）：逐一列 <folderPath>；请指定 nodeId`（不猜） |
+| 路径命中（文件级） | `路径命中（generated_at=<…>）：<名称>（<type>），目录 <folderPath>，workspaceId=<…>（<spaceType>）`；要正文 → 转 §5 |
+| 目录前缀命中 | `目录前缀命中（generated_at=<…>）：<目录> 下条目 <n> 个（folder/adoc/axls/… 分类列出）` |
+| 刷新后命中 | `刷新后命中（刷新于 <时间>）：…` |
+| 刷新后仍无 | `未找到：<名称/nodeId/路径>（目录已刷新至 <时间> 后仍不存在）；相近候选：<名称列表 ≤5>` |
+| 降级（刷新失败有旧缓存） | `缓存可能过期（generated_at=<…>，刷新失败：<原因>）：<按旧缓存作答>，结论不具权威性` |
+| 无法确认 | `无法确认（缓存缺失且在线刷新失败：<原因>）` |
+| 未找到且无候选 | `未找到：<名称/nodeId/路径>（目录已刷新至 <时间>，无相近候选）` |
+
+- "相近候选"来自刷新后快照的简单名称包含匹配（≤5），仅作提示，**不视为命中**。
+
+## 7. 校验与自查
+
+- 缓存完整性：`.cache-meta.json` 的 `last_successful_at` 与 `目录快照.json.generated_at` 一致；`node-index.json.built_from_snapshot_at` 一致；任一文件 JSON 解析失败/缺失 → 视为缓存缺失，M3 自动刷新重建。
+- 缓存身份自检：缓存目录名与其 `.cache-meta.json.space` 指向一致；身份与目标库名不一致的目录按 §2 清理重建（SKILL.md §5.0）。
+- 正文红线自查：缓存目录递归列出，只允许 4 个正式文件 + 瞬时 `.tmp-*`；出现其他文件 → 报"缓存目录被污染"并报告（不自动删除用户文件，提示人工处置）。
+- **通道判据自检（v0.6）**：node-index 中文档条目的 `extension` 覆盖率。v0.6 后新建/重建的缓存应为 100%（快照 §2 强制记录）；低于 100% 说明该缓存源自旧结构 → 取数前按 §5 第 2 步逐节点补查，并在报告注明"缓存为旧版结构，通道判据已按 `node-get` 补齐"（这是可接受的降级，不是缓存损坏）。
+
+<!-- crwu-cli-guard:legacy-compat-start -->
+> **非 DSH 宿主兼容层（legacy CLI）**：上面两步在非 DSH 宿主分别对应
+> `dws wiki +node-get --format json`（补 `extension`）、
+> `dws doc +export --node <nodeId> --export-format markdown`（adoc 导出）与
+> `dws drive +download --node <nodeId> --output <临时区相对路径>`（原生文本）。
+> DSH 环境下这些都由 `crwu_audit_knowledge_materialize` 内部完成。
+
+<!-- crwu-cli-guard:legacy-compat-end -->

package/common/skills/crwu-dws/scripts/test_dws_source_contract.py

@@ -0,0 +1,493 @@
+from pathlib import Path
+import glob
+import unittest
+
+
+# 源仓契约测试：据本文件位置上溯定位技能层与源仓根（不硬编码仓库布局）。
+# 运行时不需要本测试；已安装副本内缺少同级技能或源仓文档时显式 skip（不静默通过）。
+#
+# **技能在源仓按层组织**：DSH 把每个技能**层**注册成一个技能根 ——
+# `plugins/<插件>/skills/<层>/<技能>/`（本仓是 crwu / dws 两层）与公共层
+# `plugins/common/skills/<技能>/`。所以"同级技能"必须**跨层**查找；只在本技能所在的层里找，
+# 会把整个契约测试静默 skip 掉（2026-09 合并仓库时就发生过：8~12 条断言静默消失）。
+SKILLS_ROOT = Path(__file__).resolve().parents[2]  # skills/<层>/<技能>/scripts/<file> → 本技能所在的层
+
+
+def _has_skill_child(directory: Path) -> bool:
+    """目录里直接放着技能（`<子目录>/SKILL.md`）—— 按内容判定，不靠目录名约定。"""
+    return directory.is_dir() and any(
+        (child / "SKILL.md").is_file() for child in directory.iterdir() if child.is_dir()
+    )
+
+
+def _skill_roots(start: Path) -> tuple[Path, ...]:
+    """本技能所在的层 + 源仓里其它所有技能层（跨插件、跨层）。
+
+    DSH 运行时把每个层都注册成技能根，所以"同级技能"必须跨层查找（只在本技能所在的层里找，
+    整个契约测试会被静默 skip 掉）。安装副本里没有 `plugins/`，只剩本技能所在的层 ——
+    那时同级技能本来就不存在，记 skip 是对的。
+    """
+    roots = [start]
+    for candidate in start.parents:
+        plugins = candidate / "plugins"
+        if not plugins.is_dir():
+            continue
+        for skills in sorted(plugins.glob("*/skills")):
+            if not skills.is_dir():
+                continue
+            if _has_skill_child(skills):
+                roots.append(skills)  # 公共层：技能直接放在 skills/ 下
+            else:
+                roots.extend(sorted(layer for layer in skills.iterdir() if _has_skill_child(layer)))
+        break
+    return tuple(dict.fromkeys(root for root in roots if root.is_dir()))
+
+
+SKILLS_ROOTS = _skill_roots(SKILLS_ROOT)
+
+
+def has_skill(name: str) -> bool:
+    """两个技能根里任一存在该技能目录即为已安装（安装副本只装了单个技能时为 False）。"""
+    return any((root / name).is_dir() for root in SKILLS_ROOTS)
+
+
+def skill_path(rel: str) -> Path:
+    """按「技能名/技能内相对路径」在两个技能根里定位文件；都没有时回落到本技能所在的根。"""
+    for root in SKILLS_ROOTS:
+        candidate = root / rel
+        if candidate.exists():
+            return candidate
+    return SKILLS_ROOT / rel
+
+
+def skill_root_of(name: str) -> Path:
+    """技能 `name` 所属的技能根（安装副本里找不到时回落到本技能所在的根）。"""
+    for root in SKILLS_ROOTS:
+        if (root / name).is_dir():
+            return root
+    return SKILLS_ROOT
+
+
+def _source_repo_root(start: Path) -> Path:
+    """源仓根：向上找带 `go.mod` + `Makefile` 的那一层（安装副本里找不到就回落一层）。"""
+    for candidate in (start, *start.parents):
+        if (candidate / "go.mod").is_file() and (candidate / "Makefile").is_file():
+            return candidate
+    return start.parent
+
+
+REPO_ROOT = _source_repo_root(Path(__file__).resolve())
+
+# Active contracts that must never re-introduce a local knowledge-base root,
+# a downloaded-body mirror, or a "publish gate" style local fallback.
+# Router/DWS-side documents that are individually pinned.
+PINNED_CONTRACT_FILES = [
+    "crwu-dws/SKILL.md",
+    "crwu-dws/references/00-目录快照schema.md",
+    "crwu-dws/references/01-审核下载与manifest规范.md",
+    "crwu-dws/references/02-缓存与兜底查找规范.md",
+    "crwu-audit/SKILL.md",
+    "crwu-audit/references/10-capability-gap-proposal.md",
+    "crwu-audit/references/99-maintenance.md",
+    "crwu-audit/references/04-business-classification.md",
+    "crwu-audit/references/12-leaf-common-contract.md",
+    "crwu-audit-asset-realestate/SKILL.md",
+    "crwu-audit-asset-realestate/references/01-kb-assembly.md",
+    "crwu-audit-biz-asset-operation/SKILL.md",
+    "crwu-audit-biz-asset-operation/references/02-review-focus.md",
+    # Public-axis capabilities are not matched by _leaf_files() (which enumerates only
+    # crwu-audit-asset-* / crwu-audit-biz-*), so they must be pinned explicitly or the
+    # whole public axis would go unchecked.
+    "crwu-audit-public-general-standards/SKILL.md",
+    "crwu-audit-public-general-standards/references/00-applicability.md",
+    "crwu-audit-public-general-standards/references/01-kb-assembly.md",
+    "crwu-audit-public-general-standards/references/02-review-focus.md",
+    "crwu-audit-datacheck/SKILL.md",
+    "crwu-dev-audit-optimize/SKILL.md",
+    "crwu-dev-audit-optimize/references/00-优化规范与文件落点.md",
+    "crwu-dev-audit-optimize/references/01-反馈定位与画像流程.md",
+    "crwu-dev-audit-skill-maintainer/SKILL.md",
+    "crwu-dev-audit-skill-maintainer/references/01-kb-source-discovery.md",
+    "crwu-dev-audit-skill-maintainer/references/02-child-skill-contract.md",
+]
+# 源仓文档（不在 skills 内）：只有源仓维护环境存在；已安装副本内缺失 → 相关断言 skip。
+# 2026-09 合并仓库后，源仓设计文档归档到 `docs/v0.0.1/`（技能树移到 plugins/ 之下），
+# 原 `skills/README.md` 变成源仓文档 `docs/skills.md`。路径按现状钉住，缺失即 skip。
+PINNED_SOURCE_REPO_FILES = [
+    "docs/skills.md",
+    "docs/v0.0.1/design-audit-live-kb-protocol.md",
+    "docs/v0.0.1/design-crwu-dws.md",
+]
+
+
+def _display(path: Path) -> str:
+    """给断言消息用的短路径：技能内相对 skills 根，源仓文档相对源仓根。"""
+    for root in (*SKILLS_ROOTS, REPO_ROOT):
+        try:
+            return str(path.relative_to(root))
+        except ValueError:
+            continue
+    return str(path)
+
+
+def _source_repo_docs() -> list[Path]:
+    return [REPO_ROOT / rel for rel in PINNED_SOURCE_REPO_FILES if (REPO_ROOT / rel).is_file()]
+
+
+def _leaf_dirs() -> list[Path]:
+    """两个技能根下的全部资产/业务叶子技能目录（合并仓库后它们在插件技能根里）。"""
+    found = []
+    for root in SKILLS_ROOTS:
+        for pattern in ("crwu-audit-asset-*", "crwu-audit-biz-*"):
+            found.extend(leaf for leaf in root.glob(pattern) if leaf.is_dir())
+    return sorted(found)
+
+
+def _leaf_files():
+    """Every file of every asset/biz leaf, so the whole family is covered (not a sample)."""
+    found = []
+    for leaf in _leaf_dirs():
+        found.extend(sorted(leaf.rglob("*.md")))
+    return found
+
+
+ACTIVE_CONTRACT_FILES = [skill_path(rel) for rel in PINNED_CONTRACT_FILES] + _leaf_files()
+SOURCE_REPO_CONTRACT_FILES = _source_repo_docs()
+
+FORBIDDEN_TERMS = [
+    "CRWU_KB_ROOT",
+    "M2-B",
+    "全量镜像",
+    "本地静态副本",
+    "本地静态根",
+    "维护/离线归档",
+]
+
+# A contract still has to be able to *document* a retirement ("CRWU_KB_ROOT 已废止").
+# Only lines that present the term as a usable source are violations.
+RETIREMENT_NOTE_WORDS = (
+    "废止", "弃用", "废弃", "不再", "禁止", "不得", "红线", "三不写",
+    "字面", "lint", "协议", "硬编码", "旧树", "retired", "deprecated",
+)
+
+
+def _is_retirement_note(line):
+    return any(word in line for word in RETIREMENT_NOTE_WORDS)
+
+
+
+# 源仓契约测试所需的完整技能族：安装副本里缺任何一个 → 显式 skip（不失败、不静默通过）。
+_REQUIRED_SIBLINGS = (
+    "crwu-audit",
+    "crwu-audit-asset-realestate",
+    "crwu-audit-biz-asset-operation",
+    "crwu-audit-public-general-standards",
+    "crwu-audit-datacheck",
+    "crwu-dev-audit-optimize",
+    "crwu-dev-audit-skill-maintainer",
+    "crwu-dws",
+)
+
+
+def _requires_skill_tree(test):
+    """源仓契约测试前提：同级技能与源仓文档齐备。
+
+    技能以副本安装时这些内容可能不在（例如只装了单个技能）——此时**显式 skip**，
+    既不当成失败，也不静默通过。运行时不需要本测试。
+    """
+
+    def wrapper(self, *args, **kwargs):
+        missing = [name for name in _REQUIRED_SIBLINGS if not has_skill(name)]
+        if missing:
+            self.skipTest(f"非完整技能树（缺少同级技能 {', '.join(missing)}）：跳过源仓契约测试")
+        return test(self, *args, **kwargs)
+
+    return wrapper
+
+
+class DwsSourceContractTest(unittest.TestCase):
+    def test_source_repo_docs_are_optional_outside_the_source_repo(self):
+        """源仓文档（docs/）在已安装副本内不存在：显式 skip，不静默通过也不误报失败。"""
+        if (REPO_ROOT / "docs").is_dir():
+            self.assertEqual(
+                len(PINNED_SOURCE_REPO_FILES),
+                len(SOURCE_REPO_CONTRACT_FILES),
+                "源仓环境下设计文档必须齐备",
+            )
+        else:
+            self.skipTest("非源仓环境（无 docs/）：跳过源仓文档契约检查")
+
+    @_requires_skill_tree
+    def test_every_active_contract_file_exists(self):
+        missing = [str(path) for path in ACTIVE_CONTRACT_FILES if not path.is_file()]
+
+        self.assertEqual([], missing, f"active contract list points at missing files: {missing}")
+
+    @_requires_skill_tree
+    def test_active_contracts_do_not_offer_local_or_full_mirror_bodies(self):
+        violations = []
+
+        for contract_path in ACTIVE_CONTRACT_FILES + SOURCE_REPO_CONTRACT_FILES:
+            relative_path = _display(contract_path)
+            text = contract_path.read_text(encoding="utf-8")
+            for lineno, line in enumerate(text.splitlines(), start=1):
+                for term in FORBIDDEN_TERMS:
+                    if term not in line:
+                        continue
+                    if _is_retirement_note(line):
+                        continue
+                    violations.append(f"{relative_path}:{lineno}: {term}")
+
+        self.assertEqual([], violations, "\n".join(violations))
+
+    @_requires_skill_tree
+    def test_active_contracts_do_not_reference_a_local_kb_root_relative_path(self):
+        """`KB/<rel>` addressed the retired local root; kb_tool owns the precise rule.
+
+        `kb_tool.py validate --skill-root skills` distinguishes real `KB/<rel>` references
+        from prose such as 『KB/知识库』 and from prohibition notes. Re-implementing a cruder
+        text match here only produced false positives, so this test asserts the tool's
+        verdict on the repository instead of scanning the text itself.
+        """
+        import subprocess
+        import sys
+
+        result = subprocess.run(
+            [
+                sys.executable,
+                str(skill_path("crwu-dev-audit-skill-maintainer/scripts/kb_tool.py")),
+                "validate",
+                "--skill-root",
+                str(skill_root_of("crwu-dev-audit-skill-maintainer")),
+            ],
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+
+        self.assertEqual(
+            0,
+            result.returncode,
+            f"kb_tool validate reported reference violations:\n{result.stdout}{result.stderr}",
+        )
+
+    @_requires_skill_tree
+    def test_m2_supports_file_directory_and_mixed_manifest_entries(self):
+        text = (SKILLS_ROOT / "crwu-dws/SKILL.md").read_text(encoding="utf-8")
+        required_terms = [
+            "单文件路径",
+            "只下载该文件",
+            "目录路径",
+            "递归下载",
+            "同一清单",
+            "清单外零下载",
+        ]
+
+        for term in required_terms:
+            with self.subTest(term=term):
+                self.assertIn(term, text)
+
+    # ---- v0.6：按 extension 分流的双取数通道 ----------------------------------
+    #
+    # 缺陷背景（2026-09-15 实测）：知识库文档的 nodeType 恒为 `file`，格式只在
+    # `extension` 里；`dw. doc +export` 仅支持 `extension=adoc`。整改前 M2 对所有
+    # 文档一律调用 `doc +export`，于是 25 个原生 `.md` 正文（整个 `03-评估方法/`）
+    # 每次都必然失败、被记成 failure，且没有任何门禁发现——因为校验只看"路径键
+    # 是否存在"，不看节点类型。以下断言把整改口径钉死。
+
+    def _dws_docs(self) -> dict:
+        names = [
+            "SKILL.md",
+            "references/00-目录快照schema.md",
+            "references/01-审核下载与manifest规范.md",
+            "references/02-缓存与兜底查找规范.md",
+        ]
+        return {
+            name: (SKILLS_ROOT / "crwu-dws" / name).read_text(encoding="utf-8")
+            for name in names
+        }
+
+    @_requires_skill_tree
+    def test_whitelist_adds_read_only_drive_download(self):
+        """候选通道必须显式列入只读白名单，且仍禁止一切写命令。"""
+        text = self._dws_docs()["SKILL.md"]
+
+        self.assertIn("`+download`", text, "drive +download 未进入只读白名单")
+        self.assertIn("drive 域仅", text, "白名单未声明 drive 域边界")
+        # 白名单必须保持"仅"的排他语义：drive 域只放行 +download 一个命令。
+        drive_clause = next(
+            line for line in text.splitlines() if "drive 域仅" in line
+        )
+        self.assertIn("+download", drive_clause)
+        self.assertNotIn("+upload", drive_clause)
+        self.assertNotIn("+move", drive_clause)
+        self.assertNotIn("+delete", drive_clause)
+
+    @_requires_skill_tree
+    def test_channel_is_decided_by_extension_not_by_trial(self):
+        """通道由 extension 判定；明令禁止"先 export 试失败再换通道"的试错取数。"""
+        docs = self._dws_docs()
+        skill = docs["SKILL.md"]
+
+        # SKILL.md 必须给出分流表的三档判据。
+        for term in ("`adoc`", "`md`", "`txt`", "`skipped`"):
+            with self.subTest(term=term):
+                self.assertIn(term, skill)
+
+        # 试错取数必须被显式禁止（否则"必然失败"会被记成偶发 failure）。
+        self.assertIn("试错", skill, "SKILL.md 未禁止试错式取数")
+        self.assertRegex(
+            skill,
+            r"禁止[^\n]*试(错|一次)",
+            "SKILL.md 未写明禁止试错式通道选择",
+        )
+
+        # references/01 必须给出同一张分流表与展开范围口径。
+        m2 = docs["references/01-审核下载与manifest规范.md"]
+        self.assertIn("dws drive +download", m2)
+        self.assertIn("dws doc +export", m2)
+        self.assertIn("channel", m2)
+
+    @_requires_skill_tree
+    def test_unsupported_extension_is_skipped_not_failed(self):
+        """类型不支持是正常结论：必须记 skipped，禁止并入 failure。"""
+        docs = self._dws_docs()
+        skill = docs["SKILL.md"]
+        m2 = docs["references/01-审核下载与manifest规范.md"]
+
+        self.assertIn("skipped", skill)
+        self.assertRegex(
+            skill,
+            r"skipped[^\n]*不(得|是)[^\n]*failure|不(得|是)[^\n]*failure[^\n]*skipped",
+            "SKILL.md 未写明 skipped 不得计入 failure",
+        )
+        # 摘要口径必须把跳过与失败分开统计。
+        self.assertIn("跳过", skill)
+        self.assertIn("skipped", m2)
+        self.assertRegex(
+            m2,
+            r"(不得|禁止)[^\n]*failure",
+            "references/01 未写明 skipped 不得记为 failure",
+        )
+        # 明细表三态齐全：entry / skipped / failure。
+        for kind in ('"kind": "entry"', '"kind": "skipped"', '"kind": "failure"'):
+            with self.subTest(kind=kind):
+                self.assertIn(kind, m2)
+
+    @_requires_skill_tree
+    def test_snapshot_and_node_index_carry_the_channel_discriminator(self):
+        """extension/contentType 必须落快照与索引，否则 M2 快路径无法判通道。"""
+        docs = self._dws_docs()
+        snapshot = docs["references/00-目录快照schema.md"]
+        index = docs["references/02-缓存与兜底查找规范.md"]
+
+        for label, text in (("references/00", snapshot), ("references/02", index)):
+            with self.subTest(doc=label):
+                self.assertIn("extension", text, f"{label} 未记录 extension")
+                self.assertIn("contentType", text, f"{label} 未记录 contentType")
+
+        # 必须写明"缺失时补查 node-get、不按名称后缀猜"。
+        self.assertIn("node-get", index, "references/02 未给出 extension 缺失时的补查口径")
+        self.assertRegex(
+            snapshot + index,
+            r"不(推断|猜|按名称)",
+            "未写明 extension 缺失时不得推断/猜测",
+        )
+
+    @_requires_skill_tree
+    def test_type_field_is_not_used_as_a_format_discriminator(self):
+        """nodeType 恒为 file，不得再当格式判据（整改前的错误假设）。"""
+        snapshot = self._dws_docs()["references/00-目录快照schema.md"]
+
+        self.assertRegex(
+            snapshot,
+            r"type[^\n]*(不承载格式|只表示节点形态)",
+            "references/00 未写明 type 不承载格式信息",
+        )
+        # 渲染规则也必须按 extension 标注，而不是按 type。
+        self.assertIn("ext:", snapshot, "目录树渲染未按 extension 标注")
+
+    @_requires_skill_tree
+    def test_asset_and_business_leaves_declare_a_first_level_directory_root(self):
+        """Every asset/biz leaf must declare one exact recursive first-level root.
+
+        Parses the assembly table row (cell-level) rather than substring matching, and the
+        leaf must carry all four required references (not just the assembly table).
+        """
+        leaves = _leaf_dirs()
+        self.assertNotEqual([], leaves, "expected at least one asset/biz leaf skill")
+
+        required_references = (
+            "00-applicability.md",
+            "01-kb-assembly.md",
+            "02-review-focus.md",
+        )
+        problems = []
+        for leaf in leaves:
+            name = leaf.name
+            axis_root = "02-资产类型/" if name.startswith("crwu-audit-asset-") else "01-业务路线/"
+            for reference in required_references:
+                if not (leaf / "references" / reference).is_file():
+                    problems.append(f"{name}: missing references/{reference}")
+            assembly = leaf / "references" / "01-kb-assembly.md"
+            if not assembly.is_file():
+                continue
+
+            rows = [
+                [cell.strip().strip("`") for cell in line.strip().strip("|").split("|")]
+                for line in assembly.read_text(encoding="utf-8").splitlines()
+                if line.strip().startswith("|")
+            ]
+            header = next((r for r in rows if "kb_root" in r and "request_kind" in r), None)
+            if header is None:
+                problems.append(f"{name}: assembly has no first-level root table")
+                continue
+            index = {key: i for i, key in enumerate(header)}
+            data = [
+                r for r in rows
+                if len(r) == len(header) and r[index["request_kind"]] in {"directory"}
+            ]
+            if len(data) != 1:
+                problems.append(
+                    f"{name}: expected exactly one directory root row, found {len(data)}"
+                )
+                continue
+            row = data[0]
+            kb_root = row[index["kb_root"]]
+            label = row[index["canonical_label"]]
+            if not kb_root.startswith(axis_root) or not kb_root.endswith("/"):
+                problems.append(f"{name}: kb_root {kb_root!r} is not one {axis_root}<label>/ root")
+            if kb_root.count("/") != 2:
+                problems.append(f"{name}: kb_root {kb_root!r} is not a first-level root")
+            if row[index["recursive"]] != "true":
+                problems.append(f"{name}: recursive must be true")
+            if row[index["required"]] != "true":
+                problems.append(f"{name}: required must be true")
+            if label not in kb_root:
+                problems.append(f"{name}: canonical_label {label!r} not present in kb_root")
+            if ".md" in kb_root:
+                problems.append(f"{name}: kb_root must not carry the .md export suffix")
+
+        self.assertEqual([], problems, "\n".join(problems))
+
+    @_requires_skill_tree
+    def test_legacy_combined_and_business_prefixed_skills_are_gone(self):
+        offenders = sorted(
+            path.name
+            for root in SKILLS_ROOTS
+            for path in root.glob("crwu-audit-business-*")
+            if path.is_dir()
+        )
+        self.assertEqual(
+            [],
+            offenders,
+            f"legacy business-prefixed skill directories remain: {offenders}",
+        )
+        self.assertFalse(
+            (SKILLS_ROOT / "crwu-audit-realestate-rent").exists(),
+            "legacy combined skill crwu-audit-realestate-rent must stay deleted",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()