dev-playbooks-cn 1.0.13 → 1.0.15

package/README.md

@@ -177,7 +177,6 @@ DevBooks 使用两个目录根：
 | `devbooks-proposal-debate-workflow` | 三角对辩（Author/Challenger/Judge） |
 | `devbooks-design-doc` | 创建设计文档 |
 | `devbooks-spec-contract` | 定义规格与契约 |
-| `devbooks-c4-map` | 生成 C4 架构地图 |
 | `devbooks-implementation-plan` | 创建实现计划 |
 
 ### Apply 阶段

package/bin/devbooks.js

@@ -334,6 +334,18 @@ function installSkills(toolIds, update = false) {
 
       fs.mkdirSync(skillsDestDir, { recursive: true });
 
+      // 先安装共享目录 _shared（如果存在）
+      const sharedSrcDir = path.join(skillsSrcDir, '_shared');
+      if (fs.existsSync(sharedSrcDir)) {
+        const sharedDestDir = path.join(skillsDestDir, '_shared');
+        if (update || !fs.existsSync(sharedDestDir)) {
+          if (fs.existsSync(sharedDestDir)) {
+            fs.rmSync(sharedDestDir, { recursive: true, force: true });
+          }
+          copyDirSync(sharedSrcDir, sharedDestDir);
+        }
+      }
+
       let installedCount = 0;
       for (const skillName of skillDirs) {
         const srcPath = path.join(skillsSrcDir, skillName);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-playbooks-cn",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "description": "AI-driven spec-based development workflow",
   "keywords": [
     "devbooks",

package/skills/Skills/344/275/277/347/224/250/350/257/264/346/230/216.md

@@ -171,28 +171,6 @@
 
 ---
 
-## `devbooks-c4-map`（C4 Map Maintainer）
-
-- 作用：维护/更新项目的权威 C4 架构地图（当前真理），并按变更输出 C4 Delta。
-- 使用场景：
-  - **Proposal 阶段**：需要在 `design.md` 里写清“边界/依赖方向变化”（只写 **C4 Delta**，不改当前真理）
-  - **Review/Archive 阶段**：变更已实现并准备合并当前真理，更新权威地图 `(<truth-root>/architecture/c4.md)`
-- 使用话术：
-  - Proposal（只写 C4 Delta，不改当前真理）：
-    ```text
-    你现在是 C4 Map Maintainer。请点名使用 `devbooks-c4-map`，但在 proposal 阶段**不要修改** `dev-playbooks/specs/architecture/c4.md`（当前真理）。
-    先读：`dev-playbooks/specs/architecture/c4.md`（如存在）+ 本次 `dev-playbooks/changes/<change-id>/proposal.md` + `dev-playbooks/changes/<change-id>/design.md`
-    请输出：一段可直接粘贴进 `dev-playbooks/changes/<change-id>/design.md` 的 **C4 Delta** 小节（C1/C2/C3 新增/修改/移除 + 依赖方向变化 + 建议的 Architecture Guardrails/fitness tests 条目）。
-    ```
-  - Review/Archive（更新当前真理的权威地图）：
-  ```text
-  你现在是 C4 Map Maintainer。请点名使用 `devbooks-c4-map`。
-  先读：`dev-playbooks/specs/architecture/c4.md`（如存在）+ 本次 `dev-playbooks/changes/<change-id>/design.md` + 相关代码改动（用于确认变更已真实落地）
-  请更新（或创建最小骨架并标 TODO）：`dev-playbooks/specs/architecture/c4.md`。
-  ```
-
----
-
 ## `devbooks-implementation-plan`（Planner / tasks.md）
 
 - 作用：从 `design.md` 推导编码计划 `tasks.md`（主线计划/临时计划/断点区），并绑定验收锚点（不得参考 tests/）。

package/skills/_shared/mcp-enhancement-template.md

@@ -91,7 +91,6 @@
 | devbooks-index-bootstrap | mcp__ckb__getStatus | 索引状态检测 |
 | devbooks-federation | mcp__ckb__*, mcp__github__* | 跨仓库分析 |
 | devbooks-router | mcp__ckb__getStatus | 索引可用性检测 |
-| devbooks-c4-map | mcp__ckb__getArchitecture | 模块依赖图 |
 | devbooks-spec-contract | mcp__ckb__findReferences | 引用检测 |
 | devbooks-entropy-monitor | mcp__ckb__getHotspots | 热点趋势分析 |
 | devbooks-delivery-workflow | mcp__ckb__getStatus | 索引检测 |

package/skills/devbooks-brownfield-bootstrap/SKILL.md

@@ -74,8 +74,12 @@ tools:
 
 | 产物 | 路径 | 数据来源 |
 |------|------|----------|
+| **C4 架构地图** | `architecture/c4.md` | 综合分析 + CKB（增强模式） |
 | 模块依赖图 | `architecture/module-graph.md` | `mcp__ckb__getArchitecture` |
 | 技术债热点 | `architecture/hotspots.md` | `mcp__ckb__getHotspots` |
+| 分层约束 | `architecture/layering-constraints.md` | 代码分析（可选） |
+
+> **设计决策**：C4 架构地图现在由 brownfield-bootstrap 在初始化时生成，后续架构变更通过 design.md 的 Architecture Impact 章节记录，由 spec-gardener 在归档时合并。
 
 ### 4. 基线变更包
 
@@ -98,11 +102,52 @@ tools:
 
 | 产物 | 路径 | 数据来源 |
 |------|------|----------|
+| **C4 架构地图** | `<truth-root>/architecture/c4.md` | 综合分析 |
 | 模块依赖图 | `<truth-root>/architecture/module-graph.md` | `mcp__ckb__getArchitecture` |
 | 技术债热点 | `<truth-root>/architecture/hotspots.md` | `mcp__ckb__getHotspots` |
 | 领域概念 | `<truth-root>/_meta/key-concepts.md` | `mcp__ckb__listKeyConcepts` |
 | 项目画像 | `<truth-root>/_meta/project-profile.md` | 综合分析 |
 
+### C4 架构地图生成规则
+
+初始化时生成的 C4 地图应包含：
+
+1. **Context 层**：系统与外部参与者（用户、外部系统）的关系
+2. **Container 层**：系统内的容器（应用、数据库、服务）
+3. **Component 层**：主要容器内的组件（模块、类）
+
+**输出格式**：
+
+```markdown
+# C4 Architecture Map
+
+## System Context
+
+[描述系统边界与外部交互]
+
+## Container Diagram
+
+| Container | 技术栈 | 职责 |
+|-----------|--------|------|
+| <name> | <tech> | <responsibility> |
+
+## Component Diagram
+
+### <Container Name>
+
+| Component | 职责 | 依赖 |
+|-----------|------|------|
+| <name> | <responsibility> | <dependencies> |
+
+## Architecture Guardrails
+
+### Layering Constraints
+
+| 层级 | 可依赖 | 禁止依赖 |
+|------|--------|----------|
+| <layer> | <allowed> | <forbidden> |
+```
+
 ### 热点计算公式
 
 ```

package/skills/devbooks-code-review/SKILL.md

@@ -35,7 +35,7 @@ tools:
 - 代码格式化
 
 ### 2. 依赖健康审查
-- 分层约束遵守（参见 devbooks-c4-map）
+- 分层约束遵守（参见 `<truth-root>/architecture/c4.md`）
 - 循环依赖检测
 - 内部模块封装（禁止深度导入 *Internal 文件）
 - 依赖方向正确性

package/skills/devbooks-design-doc/SKILL.md

@@ -74,6 +74,81 @@ tools:
 | 新增命令/CLI 参数 | 使用说明 |
 | 对外 API 变更 | API 文档 |
 
+## 架构影响声明（Architecture Impact）（必填）
+
+设计文档中**必须**包含「架构影响」章节，声明本次变更对系统架构的影响。这是确保架构变更走验证闭环的关键机制。
+
+> **设计决策**：C4 架构变更不再由独立的 `devbooks-c4-map` skill 直接写入真理目录，而是作为 design.md 的一部分，在变更验收通过后由 `devbooks-spec-gardener` 合并到真理。
+
+### 模板
+
+```markdown
+## Architecture Impact（架构影响）
+
+<!-- 必填：选择以下之一 -->
+
+### 无架构变更
+
+- [x] 本次变更不影响模块边界、依赖方向或组件结构
+- 原因说明：<简要说明为什么无架构影响>
+
+### 有架构变更
+
+#### C4 层级影响
+
+| 层级 | 变更类型 | 影响描述 |
+|------|----------|----------|
+| Context | 无变更 / 新增 / 修改 / 删除 | <描述> |
+| Container | 无变更 / 新增 / 修改 / 删除 | <描述> |
+| Component | 无变更 / 新增 / 修改 / 删除 | <描述> |
+
+#### Container 变更详情
+
+- [新增/修改/删除] `<container-name>`: <变更描述>
+
+#### Component 变更详情
+
+- [新增/修改/删除] `<component-name>` in `<container>`: <变更描述>
+
+#### 依赖变更
+
+| 源 | 目标 | 变更类型 | 说明 |
+|----|------|----------|------|
+| `<source>` | `<target>` | 新增/删除/方向改变 | <说明> |
+
+#### 分层约束影响
+
+- [ ] 本次变更遵守现有分层约束
+- [ ] 本次变更需要修改分层约束（需在下方说明）
+
+分层约束修改说明：<如有>
+```
+
+### 判断规则
+
+执行 design-doc skill 时，**必须检测**以下条件判断是否有架构变更：
+
+| 检测项 | 检测方法 | 有架构变更 |
+|--------|----------|------------|
+| 新增/删除目录 | 检查变更文件路径 | 可能影响模块边界 |
+| 跨模块 import | 检查 import 语句变化 | 可能影响依赖方向 |
+| 新外部依赖 | 检查 package.json/go.mod 等 | 影响 Container 层 |
+| 新服务/进程 | 检查 Dockerfile/docker-compose | 影响 Container 层 |
+| 新 API 端点组 | 检查路由定义 | 可能影响 Component 层 |
+
+### 触发规则
+
+以下变更类型**强制要求**填写架构变更详情：
+
+| 变更类型 | 要求 |
+|----------|------|
+| 新增模块/目录 | 必须描述 Component 变更 |
+| 新增服务/容器 | 必须描述 Container 变更 |
+| 修改模块间依赖 | 必须描述依赖变更 |
+| 引入新外部系统 | 必须描述 Context 变更 |
+
+---
+
 ## 执行方式
 
 1) 先阅读并遵守：`_shared/references/通用守门协议.md`（可验证性 + 结构质量守门）。

package/skills/devbooks-router/SKILL.md

@@ -108,7 +108,7 @@ impact_profile:
 | Impact 字段 | 值 | 自动追加 Skill |
 |-------------|-----|---------------|
 | `external_api: true` | - | `devbooks-spec-contract` |
-| `architecture_boundary: true` | - | `devbooks-c4-map` |
+| `architecture_boundary: true` | - | `devbooks-design-doc`（确保 Architecture Impact 章节完整） |
 | `cross_repo: true` | - | `devbooks-federation` |
 | `risk_level: high` | - | `devbooks-proposal-debate-workflow` |
 | `affected_modules` 数量 > 5 | - | `devbooks-impact-analysis`（深度分析） |
@@ -125,7 +125,7 @@ impact_profile:
 
 ### 建议执行（基于 Impact 分析）
 4. `devbooks-spec-contract skill` → specs/**（检测到 external_api: true）
-5. `devbooks-c4-map skill` → architecture/c4.md（检测到 architecture_boundary: true）
+5. `devbooks-design-doc skill` → design.md Architecture Impact 章节（检测到 architecture_boundary: true）
 
 ### 可选执行
 6. `devbooks-impact-analysis skill` → 深度影响分析（affected_modules > 5）
@@ -182,7 +182,7 @@ skill 列表：
 - **风险/争议/取舍明显**：`devbooks-proposal-debate-workflow`（Author/Challenger/Judge，对辩后写回 Decision Log）
 - **对外行为/契约/数据不变量变化**：`devbooks-spec-contract` → `(<change-root>/<change-id>/specs/**)` + `design.md` Contract 章节
   - 若需要"确定性创建 spec delta 文件/避免路径写错"：`change-spec-delta-scaffold.sh <change-id> <capability> ...`
-- **模块边界/依赖方向/架构形态变化**：`devbooks-c4-map` → `(<truth-root>/architecture/c4.md)`
+- **模块边界/依赖方向/架构形态变化**：确保 `devbooks-design-doc` 输出完整的 Architecture Impact 章节 → 归档时由 `devbooks-spec-gardener` 合并到 `(<truth-root>/architecture/c4.md)`
 
 硬约束提醒：
 - proposal 阶段禁止写实现代码；实现发生在 apply 阶段并以测试/闸门为完成判据。

package/skills/devbooks-spec-gardener/SKILL.md

@@ -27,6 +27,62 @@ tools:
 - 禁止猜测目录根
 - 禁止跳过规则文档阅读
 
+---
+
+## 核心职责
+
+### 1. 规格合并与维护
+
+在归档阶段，将变更包中的规格产物合并到 `<truth-root>`：
+
+| 源路径 | 目标路径 | 合并策略 |
+|--------|----------|----------|
+| `<change-root>/<change-id>/specs/**` | `<truth-root>/specs/**` | 增量合并 |
+| `<change-root>/<change-id>/contracts/**` | `<truth-root>/contracts/**` | 版本化合并 |
+
+### 2. C4 架构地图合并（新增）
+
+> **设计决策**：C4 架构变更现在通过 design.md 的 Architecture Impact 章节记录，由 spec-gardener 在归档时合并到真理。
+
+在归档阶段，检测并合并架构变更：
+
+| 检测源 | 目标路径 | 合并逻辑 |
+|--------|----------|----------|
+| `<change-root>/<change-id>/design.md` 的 "Architecture Impact" 章节 | `<truth-root>/architecture/c4.md` | 增量更新 |
+
+**C4 合并流程**：
+
+1. **检测架构变更**：解析 `design.md` 中的 "Architecture Impact" 章节
+2. **判断是否需要合并**：
+   - 若 "无架构变更" 被勾选 → 跳过合并
+   - 若 "有架构变更" → 执行合并
+3. **执行合并**：
+   - 读取 `<truth-root>/architecture/c4.md`（若不存在则创建）
+   - 根据 Architecture Impact 中的变更描述更新对应章节
+   - 更新 Container/Component 表格
+   - 更新依赖关系
+   - 更新分层约束（如有变更）
+4. **记录合并日志**：在 c4.md 末尾添加变更记录
+
+**合并输出格式**（追加到 c4.md）：
+
+```markdown
+## Change History
+
+| Date | Change ID | Impact Summary |
+|------|-----------|----------------|
+| <date> | <change-id> | <brief description of architecture changes> |
+```
+
+### 3. 去重与清理
+
+在维护模式下执行：
+
+- 检测重复的规格定义
+- 清理过时/废弃的规格
+- 整理目录结构
+- 修复一致性问题
+
 ## 执行方式
 
 1) 先阅读并遵守：`_shared/references/通用守门协议.md`（可验证性 + 结构质量守门）。

package/templates/dev-playbooks/README.md

@@ -177,7 +177,6 @@ DevBooks 使用两个目录根：
 | `devbooks-proposal-debate-workflow` | 三角对辩（Author/Challenger/Judge） |
 | `devbooks-design-doc` | 创建设计文档 |
 | `devbooks-spec-contract` | 定义规格与契约 |
-| `devbooks-c4-map` | 生成 C4 架构地图 |
 | `devbooks-implementation-plan` | 创建实现计划 |
 
 ### Apply 阶段

package/templates/dev-playbooks/docs/DevBooks/351/205/215/347/275/256/346/214/207/345/215/227.md

@@ -132,8 +132,7 @@ change_root: dev-playbooks/changes/ # 变更包目录根
 | Test Owner | `devbooks-test-owner` | `verification.md` + `tests/` |
 | Coder | `devbooks-coder` | 按 tasks 实现（禁止改 tests） |
 | Reviewer | `devbooks-code-review` | 评审意见 |
-| Spec Gardener | `devbooks-spec-gardener` | 归档修剪 |
-| C4 Map | `devbooks-c4-map` | `architecture/c4.md` |
+| Spec Gardener | `devbooks-spec-gardener` | 归档修剪 + C4 合并 |
 | Design Backport | `devbooks-design-backport` | 回写设计缺口 |
 
 ### 按工作流

package/skills/devbooks-c4-map/SKILL.md

@@ -1,151 +0,0 @@
----
-name: devbooks-c4-map
-description: devbooks-c4-map：维护/更新项目的 C4 架构地图（当前真理），并按变更输出 C4 Delta。用户说"画架构图/C4/边界/依赖方向/模块地图/架构地图维护"等时使用。
-tools:
-  - Glob
-  - Grep
-  - Read
-  - Write
-  - Edit
----
-
-# DevBooks：C4 架构地图
-
-## 前置：配置发现（协议无关）
-
-- `<truth-root>`：当前真理目录根
-- `<change-root>`：变更包目录根
-
-执行前**必须**按以下顺序查找配置（找到后停止）：
-1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
-2. `dev-playbooks/project.md`（如存在）→ DevBooks 2.0 协议，使用默认映射
-4. `project.md`（如存在）→ template 协议，使用默认映射
-5. 若仍无法确定 → **停止并询问用户**
-
-**关键约束**：
-- 如果配置中指定了 `agents_doc`（规则文档），**必须先阅读该文档**再执行任何操作
-- 禁止猜测目录根
-- 禁止跳过规则文档阅读
-
-## 产物落点
-
-- 权威 C4 地图：`<truth-root>/architecture/c4.md`
-- 分层约束定义：`<truth-root>/architecture/layering-constraints.md`（可选）
-
-## 分层依赖约束（Layering Constraints）
-
-借鉴 VS Code 的分层架构强制机制，C4 地图应包含**分层约束**章节：
-
-### 分层约束定义规则
-
-1. **单向依赖原则**：上层可依赖下层，下层禁止依赖上层
-   - 示例：`base ← platform ← domain ← application ← ui`
-   - 箭头方向表示"被依赖方向"
-
-2. **环境隔离原则**：`common` 层只能被 `browser`/`node` 层引用，不能反向
-   - `common`：平台无关代码
-   - `browser`：浏览器特定代码（DOM API）
-   - `node`：Node.js 特定代码（fs、process）
-
-3. **contrib 反向隔离**：贡献模块只能依赖核心，核心禁止依赖贡献模块
-   - 示例：`workbench/contrib/*` → `workbench/core`（允许）
-   - 示例：`workbench/core` → `workbench/contrib/*`（禁止）
-
-### 分层约束输出格式
-
-在 `c4.md` 的 `## Architecture Guardrails` 部分必须包含：
-
-```markdown
-### Layering Constraints
-
-| 层级 | 可依赖 | 禁止依赖 |
-|------|--------|----------|
-| base | （无） | platform, domain, application, ui |
-| platform | base | domain, application, ui |
-| domain | base, platform | application, ui |
-| application | base, platform, domain | ui |
-| ui | base, platform, domain, application | （无） |
-
-### Environment Constraints
-
-| 环境 | 可引用 | 禁止引用 |
-|------|--------|----------|
-| common | （平台无关库） | browser/*, node/* |
-| browser | common/* | node/* |
-| node | common/* | browser/* |
-```
-
-## 执行方式
-
-1) 先阅读并遵守：`_shared/references/通用守门协议.md`（可验证性 + 结构质量守门）。
-2) 严格按完整提示词输出：`references/C4架构地图提示词.md`。
-3) 参考分层约束检查清单：`references/分层约束检查清单.md`。
-
----
-
-## 上下文感知
-
-本 Skill 在执行前自动检测上下文，选择合适的运行模式。
-
-检测规则参考：`skills/_shared/context-detection-template.md`
-
-### 检测流程
-
-1. 检测 `<truth-root>/architecture/c4.md` 是否存在
-2. 若提供 change-id，检测是否有 C4 相关变更
-3. 根据检测结果选择运行模式
-
-### 本 Skill 支持的模式
-
-| 模式 | 触发条件 | 行为 |
-|------|----------|------|
-| **创建模式** | `c4.md` 不存在 | 分析代码库，生成完整 C4 各层级图（Context/Container/Component） |
-| **更新模式** | `c4.md` 存在，有变更需要反映 | 读取变更内容，输出 C4 Delta，更新架构图 |
-
-### 检测输出示例
-
-```
-检测结果：
-- 产物存在性：c4.md 存在
-- 变更影响：检测到组件级变更（新增 templates/claude-commands/devbooks/ 15 个文件）
-- 运行模式：更新模式
-```
-
----
-
-## MCP 增强
-
-本 Skill 支持 MCP 运行时增强，自动检测并启用高级功能。
-
-MCP 增强规则参考：`skills/_shared/mcp-enhancement-template.md`
-
-### 依赖的 MCP 服务
-
-| 服务 | 用途 | 超时 |
-|------|------|------|
-| `mcp__ckb__getArchitecture` | 获取模块依赖图 | 2s |
-| `mcp__ckb__getStatus` | 检测 CKB 索引可用性 | 2s |
-
-### 检测流程
-
-1. 调用 `mcp__ckb__getStatus`（2s 超时）
-2. 若 CKB 可用 → 调用 `mcp__ckb__getArchitecture` 获取精确模块依赖
-3. 若超时或失败 → 降级到基于目录结构的推断
-
-### 增强模式 vs 基础模式
-
-| 功能 | 增强模式 | 基础模式 |
-|------|----------|----------|
-| 模块识别 | CKB 精确边界 | 目录结构推断 |
-| 依赖方向 | 符号级分析 | import 语句匹配 |
-| 循环检测 | 精确检测 | 启发式检测 |
-
-### 降级提示
-
-当 MCP 不可用时，输出以下提示：
-
-```
-⚠️ CKB 不可用，使用目录结构推断架构。
-生成的 C4 图可能不够精确，建议运行 devbooks-index-bootstrap skill 生成索引。
-```
-

package/skills/devbooks-c4-map/references/C4/346/236/266/346/236/204/345/234/260/345/233/276/346/217/220/347/244/272/350/257/215.md

@@ -1,33 +0,0 @@
-# C4架构地图提示词
-
-> **角色设定**：你是架构可视化领域的**最强大脑**——融合了 Simon Brown（C4 模型创始人）、Martin Fowler（架构模式）、Gregor Hohpe（企业集成模式）的智慧。你的架构地图必须达到这些大师级专家的水准。
-
-最高指示（优先级最高）：
-- 在执行本提示词前，先阅读 `_shared/references/通用守门协议.md` 并遵循其中所有协议。
-
-你是"架构地图维护者（C4 Map Maintainer）"。你的目标是用 C4（Context/Container/Component）为大型项目维护一份**稳定的架构地图（Current Truth）**，并确保它能为影响分析、任务拆解与架构闸门（fitness tests）提供可操作的输入。
-
-关键观点（与你的直觉对齐）：
-- C4 的“权威版本”不应散落在每次变更的设计里；它是跨变更的“当前真理地图”
-- 每次变更的设计文档里只写 **C4 Delta**（本次新增/修改/移除什么），并在变更包里安排任务去更新权威地图
-
-推荐落点（不放对外 docs）：
-- 将权威 C4 地图放在“当前真理源”里，例如：
-  - `<truth-root>/architecture/c4.md`（或你指定的等价位置）
-
-输入材料（由我提供）：
-- 当前 C4 地图（如已有）
-- 当前规格：`<truth-root>/`
-- 本次变更设计：`<change-root>/<change-id>/design.md`（若是在做架构变更）
-
-输出格式（MECE）：
-1) C1：System Context（系统边界、外部系统、主要用户）
-2) C2：Container（主要容器/服务/应用，接口与依赖方向）
-3) C3：Component（只对关键容器展开，保持最小）
-4) Architecture Guardrails（建议的架构适配测试条目，例：分层/禁止循环/禁止越界依赖）
-
-图示要求：
-- 允许用 Mermaid；优先用文本可读的方式表达（避免过度美化）
-- 不需要覆盖一切细节；目标是“对齐边界与依赖方向”
-
-现在开始输出 C4 地图 Markdown，不要输出额外解释。

package/skills/devbooks-c4-map/references//345/210/206/345/261/202/347/272/246/346/235/237/346/243/200/346/237/245/346/270/205/345/215/225.md

@@ -1,185 +0,0 @@
-# 分层约束检查清单
-
-借鉴 VS Code 的 `code-layering.ts` 和 `layersChecker.ts`，本文档定义了分层架构的检查规则。
-
----
-
-## 1) 分层依赖检查规则
-
-### 1.1 单向依赖违规检测
-
-**检查方式**：扫描 import/require 语句，验证依赖方向
-
-```typescript
-// 违规示例：base 层引用 platform 层
-// src/base/utils.ts
-import { ConfigService } from '../platform/config';  // 违规！
-
-// 正确示例：platform 层引用 base 层
-// src/platform/config.ts
-import { deepClone } from '../base/utils';  // 合法
-```
-
-**检查命令示例**（使用 grep/rg）：
-
-```bash
-# 检查 base 层是否违规引用 platform
-rg "from ['\"].*platform" src/base/ --type ts
-
-# 检查 common 层是否违规引用 browser/node
-rg "from ['\"].*(browser|node)" src/common/ --type ts
-```
-
-### 1.2 环境隔离违规检测
-
-| 环境 | 禁止的 API | 检测正则 |
-|------|-----------|---------|
-| common | DOM API | `document\.|window\.|navigator\.` |
-| common | Node API | `require\(['"]fs['"]\)|process\.|__dirname` |
-| browser | Node API | `require\(['"]fs['"]\)|child_process` |
-| node | DOM API | `document\.|window\.|DOM\.` |
-
-### 1.3 contrib 反向依赖检测
-
-```bash
-# 检查 core 是否违规引用 contrib
-rg "from ['\"].*contrib" src/core/ --type ts
-rg "from ['\"].*contrib" src/workbench/services/ --type ts
-```
-
----
-
-## 2) 分层约束定义模板
-
-在 `<truth-root>/architecture/c4.md` 中添加：
-
-```markdown
-## Architecture Guardrails
-
-### Layering Constraints
-
-本项目采用 N 层架构，依赖方向为：base ← platform ← domain ← application ← ui
-
-| 层级 | 目录 | 职责 | 可依赖 | 禁止依赖 |
-|------|------|------|--------|----------|
-| base | src/base/ | 基础工具、跨平台抽象 | （无） | 所有其他层 |
-| platform | src/platform/ | 平台服务、依赖注入 | base | domain, app, ui |
-| domain | src/domain/ | 业务逻辑、领域模型 | base, platform | app, ui |
-| application | src/app/ | 应用服务、用例编排 | base, platform, domain | ui |
-| ui | src/ui/ | 用户界面、交互逻辑 | 所有层 | （无） |
-
-### Environment Constraints
-
-| 环境目录 | 可引用 | 禁止引用 |
-|----------|--------|----------|
-| */common/ | 平台无关库 | */browser/*, */node/* |
-| */browser/ | */common/* | */node/* |
-| */node/ | */common/* | */browser/* |
-
-### Validation Commands
-
-```bash
-# 分层违规检查
-npm run valid-layers-check
-
-# 或手动检查
-rg "from ['\"].*platform" src/base/ --type ts && echo "FAIL: base→platform" || echo "OK"
-```
-```
-
----
-
-## 3) 分层违规的严重程度
-
-| 违规类型 | 严重程度 | 处理方式 |
-|----------|----------|----------|
-| 下层引用上层 | **Critical** | 必须立即修复，阻止合并 |
-| common 引用 browser/node | **Critical** | 必须立即修复 |
-| 跨层深度导入 Internal 模块 | **High** | 应使用公共 API |
-| contrib 被 core 引用 | **High** | 违反扩展点设计 |
-| 循环依赖 | **High** | 需要重构解耦 |
-
----
-
-## 4) 分层检查集成
-
-### 4.1 在 ESLint 中配置（推荐）
-
-```javascript
-// eslint.config.js
-module.exports = {
-  rules: {
-    'import/no-restricted-paths': ['error', {
-      zones: [
-        // base 禁止引用 platform
-        { target: './src/base', from: './src/platform', message: 'base cannot import platform' },
-        // platform 禁止引用 domain
-        { target: './src/platform', from: './src/domain', message: 'platform cannot import domain' },
-        // common 禁止引用 browser/node
-        { target: './src/**/common', from: './src/**/browser', message: 'common cannot import browser' },
-        { target: './src/**/common', from: './src/**/node', message: 'common cannot import node' },
-      ]
-    }]
-  }
-};
-```
-
-### 4.2 在 TypeScript 中配置
-
-为每个层创建独立的 tsconfig：
-
-```json
-// tsconfig.base.json
-{
-  "compilerOptions": {
-    "paths": {
-      // base 层只能看到自己
-    }
-  },
-  "include": ["src/base/**/*"],
-  "exclude": ["src/platform/**/*", "src/domain/**/*"]
-}
-```
-
-### 4.3 在 CI 中配置
-
-```yaml
-# .github/workflows/pr.yml
-- name: Check layer constraints
-  run: |
-    # 检查分层违规
-    ./scripts/valid-layers-check.sh || exit 1
-```
-
----
-
-## 5) 分层重构指南
-
-当发现分层违规时：
-
-1. **识别违规原因**
-   - 是否是合理的依赖？（可能需要调整分层定义）
-   - 是否可以通过接口抽象解耦？
-   - 是否应该将代码移动到正确的层？
-
-2. **解耦策略**
-   - **依赖注入**：上层通过接口注入，下层不直接依赖实现
-   - **事件机制**：下层发布事件，上层订阅
-   - **回调传递**：下层接收回调函数，不关心调用者
-
-3. **代码移动**
-   - 如果代码确实属于下层，移动到正确位置
-   - 更新所有引用路径
-   - 运行分层检查确认修复
-
----
-
-## 6) 审查检查项
-
-在 Code Review 时，检查以下项目：
-
-- [ ] 新增的 import 是否遵守分层约束？
-- [ ] 是否引入了 Internal 模块的深度导入？
-- [ ] common 目录下的代码是否使用了平台特定 API？
-- [ ] contrib 模块是否被 core 模块引用？
-- [ ] 是否存在循环依赖？