dev-playbooks-cn 1.0.0

package/skills/devbooks-brownfield-bootstrap/templates/project-profile-template.md

@@ -0,0 +1,172 @@
+# 项目画像模板（Project Profile Template）
+
+---
+
+## A) 语法层（Syntax Layer）
+
+**目标**：建立代码的结构认知——技术栈、目录布局、构建命令。
+
+### A.1 技术栈概览
+
+| 维度 | 值 |
+|------|-----|
+| 主语言 | `<language>` |
+| 框架 | `<framework>` |
+| 运行时 | `<runtime>` |
+| 包管理器 | `<package-manager>` |
+| 构建工具 | `<build-tool>` |
+
+### A.2 目录结构
+
+```
+<project-root>/
+├── src/                    # 源代码
+│   ├── base/               # 基础层（平台无关）
+│   ├── platform/           # 平台层（平台服务）
+│   ├── domain/             # 领域层（业务逻辑）
+│   ├── application/        # 应用层（用例编排）
+│   └── ui/                 # UI 层（用户交互）
+├── tests/                  # 测试代码
+├── docs/                   # 文档
+└── scripts/                # 脚本
+```
+
+### A.3 关键命令
+
+| 命令 | 用途 |
+|------|------|
+| `<install-cmd>` | 安装依赖 |
+| `<build-cmd>` | 编译构建 |
+| `<test-cmd>` | 运行测试 |
+| `<lint-cmd>` | 代码检查 |
+| `<start-cmd>` | 启动服务 |
+
+---
+
+## B) 语义层（Semantics Layer）
+
+**目标**：理解代码的逻辑关系——模块依赖、API 边界、数据流向。
+
+### B.1 模块依赖图
+
+> 由 `mcp__ckb__getArchitecture` 生成，或手动维护
+
+```
+[base] ← [platform] ← [domain] ← [application] ← [ui]
+           ↑
+       [external-libs]
+```
+
+**分层约束**（Layering Constraints）：
+
+| 层级 | 可依赖 | 禁止依赖 |
+|------|--------|----------|
+| base | （无） | 所有上层 |
+| platform | base | domain, application, ui |
+| domain | base, platform | application, ui |
+| application | base, platform, domain | ui |
+| ui | 所有层 | （无） |
+
+### B.2 核心能力（Capabilities）
+
+| 能力 | 入口 | 负责模块 | 依赖 |
+|------|------|----------|------|
+| `<capability-1>` | `<entry-point>` | `<module>` | `<deps>` |
+| `<capability-2>` | `<entry-point>` | `<module>` | `<deps>` |
+
+### B.3 对外契约
+
+| 类型 | 位置 | 格式 |
+|------|------|------|
+| REST API | `src/api/` | OpenAPI 3.0 |
+| 事件 | `src/events/` | CloudEvents |
+| 数据 Schema | `src/schemas/` | JSON Schema |
+| 配置 | `config/` | YAML |
+
+### B.4 边界识别
+
+| 区域 | 路径模式 | 属性 |
+|------|----------|------|
+| **用户代码** | `src/**`, `lib/**` | 可修改 |
+| **库代码** | `node_modules/**`, `vendor/**` | 不可变接口 |
+| **生成代码** | `dist/**`, `*.generated.*` | 禁止手动修改 |
+| **配置文件** | `*.config.*`, `.*rc` | 需要声明变更 |
+
+---
+
+## C) 上下文层（Context Layer）
+
+**目标**：捕获项目的隐性知识——历史决策、团队约定、技术债务。
+
+### C.1 技术债热点
+
+> 由 `mcp__ckb__getHotspots` 生成，或从 Git 历史计算
+
+| 文件 | 变更频率 | 复杂度 | 热点分数 | 风险等级 |
+|------|----------|--------|----------|----------|
+| `<file-1>` | 高 | 高 | `<score>` | 🔴 Critical |
+| `<file-2>` | 中 | 高 | `<score>` | 🟡 High |
+| `<file-3>` | 高 | 低 | `<score>` | 🟢 Normal |
+
+### C.2 领域概念（Glossary）
+
+> 由 `mcp__ckb__listKeyConcepts` 生成，或手动维护
+
+| 术语 | 定义 | 代码位置 |
+|------|------|----------|
+| `<term-1>` | `<definition>` | `<location>` |
+| `<term-2>` | `<definition>` | `<location>` |
+
+### C.3 架构决策记录（ADRs）
+
+| 编号 | 标题 | 状态 | 日期 |
+|------|------|------|------|
+| ADR-001 | `<title>` | Accepted | `<date>` |
+| ADR-002 | `<title>` | Superseded | `<date>` |
+
+### C.4 已知约束与限制
+
+| 约束 | 原因 | 影响范围 |
+|------|------|----------|
+| `<constraint-1>` | `<reason>` | `<scope>` |
+| `<constraint-2>` | `<reason>` | `<scope>` |
+
+### C.5 团队约定
+
+| 类别 | 约定 | 强制程度 |
+|------|------|----------|
+| 命名规范 | `<convention>` | 必须 |
+| 提交规范 | `<convention>` | 必须 |
+| 分支策略 | `<convention>` | 必须 |
+| 代码风格 | `<convention>` | Lint 强制 |
+
+---
+
+## D) 质量闸门（Quality Gates）
+
+### D.1 合并前检查
+
+- [ ] 编译通过：`<build-cmd>`
+- [ ] Lint 通过：`<lint-cmd>`
+- [ ] 测试通过：`<test-cmd>`
+- [ ] 分层约束通过：`guardrail-check.sh --check-layers`
+- [ ] 无循环依赖：`guardrail-check.sh --check-cycles`
+
+### D.2 热点变更额外检查
+
+当变更触及热点文件时：
+
+- [ ] 测试覆盖率 ≥ 80%
+- [ ] 代码评审重点关注
+- [ ] 圈复杂度未增加
+
+---
+
+## E) 元数据
+
+| 字段 | 值 |
+|------|-----|
+| 创建日期 | `<date>` |
+| 最后更新 | `<date>` |
+| 维护者 | `<maintainer>` |
+| 版本 | `<version>` |

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

@@ -0,0 +1,151 @@
+---
+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 生成索引。
+```
+

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

@@ -0,0 +1,33 @@
+# 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

@@ -0,0 +1,185 @@
+# 分层约束检查清单
+
+借鉴 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 模块引用？
+- [ ] 是否存在循环依赖？