Refactor documentation for code commands and workflows

- Updated command syntax formatting to use code blocks for clarity in `prep.md`, `review.md`, and `spec.md`. - Enhanced architectural diagrams in `ch01-what-is-claude-dms3.md` and core concepts in `ch03-core-concepts.md` using mermaid syntax for better visualization. - Improved workflow diagrams in `ch04-workflow-basics.md` and `4-level.md` to provide clearer representations of processes. - Added troubleshooting section in `installation.md` to address common installation issues and provide quick start examples. - Revised skill documentation in `claude-meta.md` and `claude-workflow.md` to standardize command triggers and output structures. - Updated best practices and workflow index documentation to enhance readability and understanding of workflow levels and practices.
2026-03-02 15:23:19 +08:00 · 2026-02-28 19:53:24 +08:00
parent b0bfdb907a
commit 4a89f626fc
51 changed files with 741 additions and 619 deletions
--- a/docs/zh/commands/claude/cli.md
+++ b/docs/zh/commands/claude/cli.md
@@ -26,7 +26,7 @@
 **功能**: 根据工作空间技术检测生成 `.gemini/` 和 `.qwen/` 配置目录，包含 settings.json 和 ignore 文件。

 **语法**:
-```
+```bash
 /cli:cli-init [--tool gemini|qwen|all] [--output path] [--preview]
 ```

@@ -75,7 +75,7 @@
 **功能**: 使用 Codex CLI 通过 ccw 端点进行交互式代码审查，支持可配置的审查目标、模型和自定义指令。

 **语法**:
-```
+```bash
 /cli:codex-review [--uncommitted|--base <branch>|--commit <sha>] [--model <model>] [--title <title>] [prompt]
 ```

--- a/docs/zh/commands/claude/core-orchestration.md
+++ b/docs/zh/commands/claude/core-orchestration.md
@@ -18,7 +18,7 @@
 **功能**: 主工作流编排器 - 意图分析→工作流选择→命令链执行

 **语法**:
-```
+```bash
 /ccw "任务描述"
 ```

@@ -80,7 +80,7 @@ graph TD
 **功能**: 命令编排工具 - 分析任务、推荐命令链、顺序执行、状态持久化

 **语法**:
-```
+```bash
 /ccw-coordinator "任务描述"
 ```

--- a/docs/zh/commands/claude/index.md
+++ b/docs/zh/commands/claude/index.md
@@ -111,6 +111,110 @@
 /ccw "实现用户认证" --yes
 ```

+## 使用示例
+
+### 快速分析
+
+```bash
+# 分析代码库结构
+/ccw "分析认证模块的架构"
+
+# 快速 Bug 诊断
+/ccw "诊断登录超时问题发生的原因"
+```
+
+### 规划与实施
+
+```bash
+# 创建实施计划
+/workflow:plan "添加 OAuth2 认证，支持 Google 和 GitHub 提供商"
+
+# 使用自动模式执行
+/workflow:execute --yes
+```
+
+### 代码审查
+
+```bash
+# 审查当前变更
+/cli:codex-review
+
+# 专注于特定区域
+/cli:codex-review "重点关注认证模块中的安全漏洞"
+```
+
+### 会话管理
+
+```bash
+# 列出所有会话
+/workflow:session:list
+
+# 恢复暂停的会话
+/workflow:session:resume "WFS-001"
+
+# 标记会话为完成
+/workflow:session:complete "WFS-001"
+```
+
+### Issue 工作流
+
+```bash
+# 从代码库中发现 Issue
+/issue:discover
+
+# 为特定 Issue 创建计划
+/issue:plan "ISSUE-001"
+
+# 执行修复
+/issue:execute --commit
+```
+
+### Memory 管理
+
+```bash
+# 捕获当前会话的学习内容
+/memory:capture "认证重构的关键见解"
+
+# 列出所有记忆
+/memory:list
+
+# 搜索记忆
+/memory:search "认证模式"
+```
+
+### CLI 工具调用
+
+```bash
+# 初始化 CLI 配置
+/cli:cli-init
+
+# 运行 Gemini 分析
+ccw cli -p "分析 src/auth 中的代码模式" --tool gemini --mode analysis
+
+# 使用特定规则模板运行
+ccw cli -p "审查代码质量" --tool gemini --mode analysis --rule analysis-review-code-quality
+```
+
+### UI 设计工作流
+
+```bash
+# 从参考图片提取样式
+/workflow:ui-design:style-extract --input "path/to/reference.png"
+
+# 生成原型
+/workflow:ui-design:generate --layout "dashboard" --tokens "design-tokens.json"
+```
+
+## 使用技巧
+
+1. **谨慎使用自动模式**：仅在常规任务时使用 `--yes` 或 `-y`。对于复杂决策保持手动确认。
+
+2. **会话持久化**：始终使用 `/workflow:session:complete` 完成会话以保留学习内容。
+
+3. **记忆捕获**：定期使用 `/memory:capture` 捕获重要见解以构建项目知识。
+
+4. **CLI 工具选择**：让 `/ccw` 自动选择合适的工具，或使用 `--tool gemini|qwen|codex` 显式指定。
+
 ## 相关文档

 - [Skills 参考](../skills/)
--- a/docs/zh/commands/claude/issue.md
+++ b/docs/zh/commands/claude/issue.md
@@ -32,7 +32,7 @@
 **功能**: 从 GitHub URL 或文本描述创建结构化 Issue，支持需求清晰度检测。

 **语法**:
-```
+```bash
 /issue:new [-y|--yes] <github-url | 文本描述> [--priority 1-5]
 ```

@@ -92,7 +92,7 @@ interface Issue {
 **功能**: 从多个角度（Bug、UX、测试、质量、安全、性能、可维护性、最佳实践）发现潜在 Issue。

 **语法**:
-```
+```bash
 /issue:discover [-y|--yes] <路径模式> [--perspectives=bug,ux,...] [--external]
 ```

@@ -125,7 +125,7 @@ interface Issue {
 **功能**: 通过用户提示发现 Issue，使用 Gemini 规划的迭代多代理探索，支持跨模块比较。

 **语法**:
-```
+```bash
 /issue:discover-by-prompt [-y|--yes] <提示> [--scope=src/**] [--depth=standard|deep] [--max-iterations=5]
 ```

@@ -151,7 +151,7 @@ interface Issue {
 **功能**: 批量规划 Issue 解决方案，使用 issue-plan-agent（探索+规划闭环）。

 **语法**:
-```
+```bash
 /issue:plan [-y|--yes] --all-pending <issue-id>[,<issue-id>,...] [--batch-size 3]
 ```

@@ -176,7 +176,7 @@ interface Issue {
 **功能**: 从绑定解决方案形成执行队列，使用 issue-queue-agent（解决方案级别）。

 **语法**:
-```
+```bash
 /issue:queue [-y|--yes] [--queues <n>] [--issue <id>]
 ```

@@ -201,7 +201,7 @@ interface Issue {
 **功能**: 执行队列，使用 DAG 并行编排（每个解决方案一次提交）。

 **语法**:
-```
+```bash
 /issue:execute [-y|--yes] --queue <queue-id> [--worktree [<existing-path>]]
 ```

@@ -223,7 +223,7 @@ interface Issue {
 **功能**: 转换规划工件（lite-plan、工作流会话、markdown）为 Issue 解决方案。

 **语法**:
-```
+```bash
 /issue:convert-to-plan [-y|--yes] [--issue <id>] [--supplement] <来源>
 ```

@@ -253,7 +253,7 @@ interface Issue {
 **功能**: 从头脑风暴会话想法转换为 Issue 并生成可执行解决方案。

 **语法**:
-```
+```bash
 /issue:from-brainstorm SESSION="会话-id" [--idea=<索引>] [--auto] [-y|--yes]
 ```

--- a/docs/zh/commands/claude/memory.md
+++ b/docs/zh/commands/claude/memory.md
@@ -33,7 +33,7 @@
 **功能**: 压缩当前会话记忆为结构化文本，提取目标、计划、文件、决策、约束、状态，并通过 MCP core_memory 工具保存。

 **语法**:
-```
+```bash
 /memory:compact [可选: 会话描述]
 ```

@@ -59,7 +59,7 @@
 **功能**: 快速笔记记录命令，捕获想法、片段、提醒和洞察供后续参考。

 **语法**:
-```
+```bash
 /memory:tips <笔记内容> [--tag <标签1,标签2>] [--context <上下文>]
 ```

@@ -84,7 +84,7 @@
 **功能**: 委托给 universal-executor 代理，通过 Gemini/Qwen CLI 分析项目并返回 JSON 核心内容包用于任务上下文。

 **语法**:
-```
+```bash
 /memory:load [--tool gemini|qwen] "任务上下文描述"
 ```

@@ -107,7 +107,7 @@
 **功能**: 更新所有 CLAUDE.md 文件，使用基于层的执行（Layer 3→1），批量代理处理（4 模块/代理）和 gemini→qwen→codex 回退。

 **语法**:
-```
+```bash
 /memory:update-full [--tool gemini|qwen|codex] [--path <目录>]
 ```

@@ -137,7 +137,7 @@
 **功能**: 更新 git 变更模块的 CLAUDE.md 文件，使用批量代理执行（4 模块/代理）和 gemini→qwen→codex 回退。

 **语法**:
-```
+```bash
 /memory:update-related [--tool gemini|qwen|codex]
 ```

@@ -158,7 +158,7 @@
 **功能**: 使用 CLI 执行生成完整项目文档（Layer 3→1），批量代理处理（4 模块/代理）和 gemini→qwen→codex 回退，<20 模块使用直接并行。

 **语法**:
-```
+```bash
 /memory:docs-full-cli [路径] [--tool <gemini|qwen|codex>]
 ```

@@ -179,7 +179,7 @@
 **功能**: 使用 CLI 执行生成 git 变更模块文档，批量代理处理（4 模块/代理）和 gemini→qwen→codex 回退，<15 模块使用直接执行。

 **语法**:
-```
+```bash
 /memory:docs-related-cli [--tool <gemini|qwen|codex>]
 ```

@@ -197,7 +197,7 @@
 **功能**: 从样式参考生成 SKILL 记忆包，便于加载和一致的设计系统使用。

 **语法**:
-```
+```bash
 /memory:style-skill-memory [包名] [--regenerate]
 ```

--- a/docs/zh/commands/claude/session.md
+++ b/docs/zh/commands/claude/session.md
@@ -30,7 +30,7 @@
 **功能**: 发现现有会话或启动新工作流会话，支持智能会话管理和冲突检测。

 **语法**:
-```
+```bash
 /workflow:session:start [--type <workflow|review|tdd|test|docs>] [--auto|--new] [可选: 任务描述]
 ```

@@ -99,7 +99,7 @@ graph TD
 **功能**: 列出所有工作流会话，支持状态过滤，显示会话元数据和进度信息。

 **语法**:
-```
+```bash
 /workflow:session:list
 ```

@@ -122,7 +122,7 @@ graph TD
 **功能**: 恢复最近暂停的工作流会话，支持自动会话发现和状态更新。

 **语法**:
-```
+```bash
 /workflow:session:resume
 ```

@@ -149,7 +149,7 @@ graph TD
 **功能**: 标记活动工作流会话为完成，归档并学习经验，更新清单并移除活动标志。

 **语法**:
-```
+```bash
 /workflow:session:complete [-y|--yes] [--detailed]
 ```

@@ -189,7 +189,7 @@ graph TD
 **功能**: 将会话学习和用户定义的约束结晶为永久项目指南。

 **语法**:
-```
+```bash
 /workflow:session:solidify [-y|--yes] [--type <convention|constraint|learning>] [--category <类别>] "规则或洞察"
 ```

--- a/docs/zh/commands/claude/ui-design.md
+++ b/docs/zh/commands/claude/ui-design.md
@@ -47,7 +47,7 @@
 **功能**: 交互式探索性 UI 设计工作流，以样式为中心的批量生成，从提示/图片创建设计变体，支持并行执行和用户选择。

 **语法**:
-```
+```bash
 /workflow:ui-design:explore-auto [--input "<值>"] [--targets "<列表>"] [--target-type "page|component"] [--session <id>] [--style-variants <数量>] [--layout-variants <数量>]
 ```

@@ -76,7 +76,7 @@
 **功能**: UI 设计工作流，支持直接代码/图片输入进行设计令牌提取和原型生成。

 **语法**:
-```
+```bash
 /workflow:ui-design:imitate-auto [--input "<值>"] [--session <id>]
 ```

@@ -98,7 +98,7 @@
 **功能**: 从参考图片或文本提示使用 Claude 分析提取设计样式，支持变体生成或精化模式。

 **语法**:
-```
+```bash
 /workflow:ui-design:style-extract [-y|--yes] [--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<描述>"] [--variants <数量>] [--interactive] [--refine]
 ```

@@ -126,7 +126,7 @@
 **功能**: 从参考图片或文本提示使用 Claude 分析提取结构布局信息，支持变体生成或精化模式。

 **语法**:
-```
+```bash
 /workflow:ui-design:layout-extract [-y|--yes] [--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<描述>"] [--targets "<列表>"] [--variants <数量>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]
 ```

@@ -151,7 +151,7 @@
 **功能**: 从提示推断和图片引用提取动画和过渡模式，用于设计系统文档。

 **语法**:
-```
+```bash
 /workflow:ui-design:animation-extract [-y|--yes] [--design-id <id>] [--session <id>] [--images "<glob>"] [--focus "<类型>"] [--interactive] [--refine]
 ```

@@ -172,7 +172,7 @@
 **功能**: 从代码文件（CSS/JS/HTML/SCSS）导入设计系统，使用自动文件发现和并行代理分析。

 **语法**:
-```
+```bash
 /workflow:ui-design:import-from-code [--design-id <id>] [--session <id>] [--source <path>]
 ```

@@ -193,7 +193,7 @@
 **功能**: 编排器从代码提取样式并生成可共享引用包，支持预览（自动文件发现）。

 **语法**:
-```
+```bash
 /workflow:ui-design:codify-style <path> [--package-name <name>] [--output-dir <path>] [--overwrite]
 ```

@@ -216,7 +216,7 @@
 **功能**: 从设计运行提取生成多组件参考页面和文档。

 **语法**:
-```
+```bash
 /workflow:ui-design:reference-page-generator [--design-run <path>] [--package-name <name>] [--output-dir <path>]
 ```

@@ -234,7 +234,7 @@
 **功能**: 组装 UI 原型，将布局模板与设计令牌（默认动画支持）组合，纯组装器无新内容生成。

 **语法**:
-```
+```bash
 /workflow:ui-design:generate [--design-id <id>] [--session <id>]
 ```

@@ -252,7 +252,7 @@
 **功能**: 同步最终设计系统引用到头脑风暴工件，准备供 `/workflow:plan` 消费。

 **语法**:
-```
+```bash
 /workflow:ui-design:design-sync --session <session_id> [--selected-prototypes "<列表>"]
 ```

--- a/docs/zh/commands/claude/workflow.md
+++ b/docs/zh/commands/claude/workflow.md
@@ -72,7 +72,7 @@
 **功能**: 超轻量级多工具分析和直接执行。简单任务无工件，复杂任务自动在 `.workflow/.scratchpad/` 创建规划文档。

 **语法**:
-```
+```bash
 /workflow:lite-lite-lite [-y|--yes] <任务描述>
 ```

@@ -95,7 +95,7 @@
 **功能**: 轻量级交互式规划工作流，支持内存规划、代码探索和执行到 lite-execute。

 **语法**:
-```
+```bash
 /workflow:lite-plan [-y|--yes] [-e|--explore] "任务描述" | file.md
 ```

@@ -116,7 +116,7 @@
 **功能**: 基于内存计划、提示描述或文件内容执行任务。

 **语法**:
-```
+```bash
 /workflow:lite-execute [-y|--yes] [--in-memory] ["任务描述" | file-path]
 ```

@@ -137,7 +137,7 @@
 **功能**: 轻量级 Bug 诊断和修复工作流，支持智能严重程度评估和可选的热修复模式。

 **语法**:
-```
+```bash
 /workflow:lite-fix [-y|--yes] [--hotfix] "Bug 描述或 Issue 引用"
 ```

@@ -158,7 +158,7 @@
 **功能**: 5 阶段规划工作流，输出 IMPL_PLAN.md 和任务 JSON。

 **语法**:
-```
+```bash
 /workflow:plan [-y|--yes] "文本描述" | file.md
 ```

@@ -183,7 +183,7 @@
 **功能**: 协调代理执行工作流任务，支持自动会话发现、并行任务处理和状态跟踪。

 **语法**:
-```
+```bash
 /workflow:execute [-y|--yes] [--resume-session="session-id"]
 ```

@@ -201,7 +201,7 @@
 **功能**: 交互式工作流重新规划，支持会话级工件更新和边界澄清。

 **语法**:
-```
+```bash
 /workflow:replan [-y|--yes] [--session session-id] [task-id] "需求" | file.md [--interactive]
 ```

@@ -219,7 +219,7 @@
 **功能**: 多 CLI 协作规划工作流，使用 ACE 上下文收集和迭代交叉验证。

 **语法**:
-```
+```bash
 /workflow:multi-cli-plan [-y|--yes] <任务描述> [--max-rounds=3] [--tools=gemini,codex] [--mode=parallel|serial]
 ```

@@ -242,7 +242,7 @@
 **功能**: 交互式头脑风暴，多 CLI 协作、想法扩展和文档化思维演化。

 **语法**:
-```
+```bash
 /workflow:brainstorm-with-file [-y|--yes] [-c|--continue] [-m|--mode creative|structured] "想法或主题"
 ```

@@ -264,7 +264,7 @@
 **功能**: 交互式协作分析，有文档化的讨论、CLI 辅助探索和演化理解。

 **语法**:
-```
+```bash
 /workflow:analyze-with-file [-y|--yes] [-c|--continue] "主题或问题"
 ```

@@ -282,7 +282,7 @@
 **功能**: 交互式假设驱动调试，有文档化的探索、理解演化和 Gemini 辅助修正。

 **语法**:
-```
+```bash
 /workflow:debug-with-file [-y|--yes] "Bug 描述或错误信息"
 ```

@@ -300,7 +300,7 @@
 **功能**: 通用执行引擎，消费任何规划/头脑风暴/分析输出，支持最小进度跟踪、多代理协调和增量执行。

 **语法**:
-```
+```bash
 /workflow:unified-execute-with-file [-y|--yes] [-p|--plan <path>] [-m|--mode sequential|parallel] ["执行上下文"]
 ```

--- a/docs/zh/commands/codex/prep.md
+++ b/docs/zh/commands/codex/prep.md
@@ -38,7 +38,7 @@
 **功能**: 委托给 universal-executor 代理，通过 Gemini/Qwen CLI 分析项目并返回 JSON 核心内容包用于任务上下文。

 **语法**:
-```
+```bash
 /memory:prepare [--tool gemini|qwen] "任务上下文描述"
 ```

--- a/docs/zh/commands/codex/review.md
+++ b/docs/zh/commands/codex/review.md
@@ -19,7 +19,7 @@
 **功能**: 使用 Codex CLI 通过 ccw 端点进行交互式代码审查，支持可配置的审查目标、模型和自定义指令。

 **语法**:
-```
+```bash
 /cli:codex-review [--uncommitted|--base <分支>|--commit <sha>] [--model <模型>] [--title <标题>] [提示]
 ```

--- a/docs/zh/features/spec.md
+++ b/docs/zh/features/spec.md
@@ -80,7 +80,7 @@ ccw spec init
 ```

 **输出**:
-```
+```bash
 Initializing spec system...

 Directories created:
--- a/docs/zh/guide/ch01-what-is-claude-dms3.md
+++ b/docs/zh/guide/ch01-what-is-claude-dms3.md
@@ -50,32 +50,24 @@

 ## 1.4 架构概览

-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Claude_dms3 架构                          │
-├─────────────────────────────────────────────────────────────┤
-│                                                              │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
-│  │  CodexLens  │  │     CCW     │  │   Memory    │          │
-│  │  (语义索引)  │  │  (CLI调用   │  │  (持久化    │          │
-│  │             │  │   框架)     │  │   上下文)   │          │
-│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘          │
-│         │                │                │                  │
-│         └────────────────┼────────────────┘                  │
-│                          │                                   │
-│                    ┌─────┴─────┐                             │
-│                    │   Spec    │                             │
-│                    │  规范系统  │                             │
-│                    └─────┬─────┘                             │
-│                          │                                   │
-│         ┌────────────────┼────────────────┐                  │
-│         │                │                │                  │
-│    ┌────┴────┐     ┌─────┴─────┐    ┌────┴────┐             │
-│    │  Hooks  │     │  Skills   │    │ Agents  │             │
-│    │ (注入)  │     │ (可复用)  │    │ (角色)  │             │
-│    └─────────┘     └───────────┘    └─────────┘             │
-│                                                              │
-└─────────────────────────────────────────────────────────────┘
+```mermaid
+graph TB
+    subgraph Claude_dms3_Architecture[Claude_dms3 架构]
+        A[CodexLens<br/>语义索引]
+        B[CCW<br/>CLI调用框架]
+        C[Memory<br/>持久化上下文]
+        D[Spec 规范系统]
+        E[Hooks<br/>注入]
+        F[Skills<br/>可复用]
+        G[Agents<br/>角色]
+
+        A --> D
+        B --> D
+        C --> D
+        D --> E
+        D --> F
+        D --> G
+    end
 ```

 ---
--- a/docs/zh/guide/ch03-core-concepts.md
+++ b/docs/zh/guide/ch03-core-concepts.md
@@ -66,29 +66,15 @@ Codex Prompts 定义在 `.codex/prompts/` 目录，专为 Codex 模型优化。

 ## 3.2 三层关系

-```
-┌─────────────────────────────────────────────────────┐
-│                    用户请求                          │
-└────────────────────┬────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────┐
-│                  ccw (编排器)                        │
-│  意图分析 → 工作流选择 → 命令链执行                  │
-└────────────────────┬────────────────────────────────┘
-                     │
-         ┌───────────┼───────────┐
-         ▼           ▼           ▼
-    ┌────────┐  ┌────────┐  ┌────────┐
-    │ Command│  │ Skill  │  │ Prompt │
-    │ (原子) │  │ (复合) │  │(模板)  │
-    └────────┘  └────────┘  └────────┘
-         │           │           │
-         └───────────┼───────────┘
-                     ▼
-            ┌────────────────┐
-            │  AI 模型调用    │
-            └────────────────┘
+```mermaid
+graph TB
+    A[用户请求] --> B[ccw 编排器<br/>意图分析 → 工作流选择 → 命令链执行]
+    B --> C[Command 原子]
+    B --> D[Skill 复合]
+    B --> E[Prompt 模板]
+    C --> F[AI 模型调用]
+    D --> F
+    E --> F
 ```

 ### 3.2.1 调用路径
@@ -107,17 +93,13 @@ Codex Prompts 定义在 `.codex/prompts/` 目录，专为 Codex 模型优化。

 ### 3.3.1 会话生命周期

-```
-┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
-│  Start  │────▶│ Resume  │────▶│ Execute │────▶│Complete │
-│  启动   │     │  恢复   │     │  执行   │     │  完成   │
-└─────────┘     └─────────┘     └─────────┘     └─────────┘
-     │                                │
-     ▼                                ▼
-┌─────────┐                     ┌─────────┐
-│  List   │                     │ Solidify│
-│  列出   │                     │  固化   │
-└─────────┘                     └─────────┘
+```mermaid
+graph LR
+    A[Start<br/>启动] --> B[Resume<br/>恢复]
+    B --> C[Execute<br/>执行]
+    C --> D[Complete<br/>完成]
+    A --> E[List<br/>列出]
+    D --> F[Solidify<br/>固化]
 ```

 ### 3.3.2 会话命令
@@ -172,20 +154,11 @@ Claude_dms3 支持 8 种团队工作流，每种工作流定义了不同的角

 团队成员通过消息总线通信：

-```
-┌────────────┐                   ┌────────────┐
-│  Planner   │                   │ Executor   │
-└─────┬──────┘                   └──────┬─────┘
-      │                                 │
-      │  [plan_ready]                   │
-      ├────────────────────────────────▶
-      │                                 │
-      │                          [task_complete]
-      │◀────────────────────────────────┤
-      │                                 │
-      │   [plan_approved]               │
-      ├────────────────────────────────▶
-      │                                 │
+```mermaid
+graph LR
+    A[Planner] -->|plan_ready| B[Executor]
+    B -->|task_complete| A
+    A -->|plan_approved| B
 ```

 ### 3.4.3 工作流选择指南
@@ -221,38 +194,25 @@ Claude_dms3 支持 8 种团队工作流，每种工作流定义了不同的角

 ## 3.6 数据流

-```
-用户请求
-   │
-   ▼
-┌──────────────┐
-│  CCW 编排器   │ ──▶ 意图分析
-└──────────────┘
-   │
-   ├─▶ Workflow 选择
-   │      │
-   │      ├─▶ PlanEx
-   │      ├─▶ IterDev
-   │      ├─▶ Lifecycle
-   │      └─▶ ...
-   │
-   ├─▶ Command 执行
-   │      │
-   │      ├─▶ 内置命令
-   │      └─▶ Skill 调用
-   │
-   ├─▶ AI 模型调用
-   │      │
-   │      ├─▶ Gemini
-   │      ├─▶ Qwen
-   │      ├─▶ Codex
-   │      └─▶ Claude
-   │
-   └─▶ 结果返回
-          │
-          ├─▶ 文件修改
-          ├─▶ Memory 更新
-          └─▶ Dashboard 更新
+```mermaid
+graph TB
+    A[用户请求] --> B[CCW 编排器<br/>意图分析]
+    B --> C[Workflow 选择]
+    B --> D[Command 执行]
+    B --> E[AI 模型调用]
+    B --> F[结果返回]
+    C --> C1[PlanEx]
+    C --> C2[IterDev]
+    C --> C3[Lifecycle]
+    D --> D1[内置命令]
+    D --> D2[Skill 调用]
+    E --> E1[Gemini]
+    E --> E2[Qwen]
+    E --> E3[Codex]
+    E --> E4[Claude]
+    F --> F1[文件修改]
+    F --> F2[Memory 更新]
+    F --> F3[Dashboard 更新]
 ```

 ---
--- a/docs/zh/guide/ch04-workflow-basics.md
+++ b/docs/zh/guide/ch04-workflow-basics.md
@@ -29,30 +29,26 @@

 ### 4.2.2 启动方式

-```
+```shell
 /workflow:plan
 ```

 或直接描述需求：

-```
+```plaintext
 实现用户登录功能，支持邮箱和手机号登录
 ```

 ### 4.2.3 工作流程

-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│  Planner    │────▶│  Executor   │────▶│  Reviewer   │
-│  规划阶段    │     │  执行阶段    │     │  审查阶段    │
-└─────────────┘     └─────────────┘     └─────────────┘
-     │                  │                    │
-     ▼                  ▼                    ▼
-┌─────────────┐  ┌─────────────┐    ┌─────────────┐
-│ 需求分析    │  │ 任务执行    │    │ 代码审查    │
-│ 任务分解    │  │ 代码生成    │    │ 质量检查    │
-│ 计划生成    │  │ 测试编写    │    │ 反馈修复    │
-└─────────────┘  └─────────────┘    └─────────────┘
+```mermaid
+graph LR
+    A[Planner<br/>规划阶段] -->|plan_ready| B[Executor<br/>执行阶段]
+    B -->|task_complete| C[Reviewer<br/>审查阶段]
+
+    A --> A1[需求分析<br/>任务分解<br/>计划生成]
+    B --> B1[任务执行<br/>代码生成<br/>测试编写]
+    C --> C1[代码审查<br/>质量检查<br/>反馈修复]
 ```

 ### 4.2.4 输出产物
@@ -74,24 +70,20 @@

 ### 4.3.2 启动方式

-```
+```shell
 /refactor-cycle
 ```

 ### 4.3.3 工作流程

-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│  Discover   │────▶│   Plan      │────▶│  Refactor   │
-│  发现阶段    │     │  规划阶段    │     │  重构阶段    │
-└─────────────┘     └─────────────┘     └─────────────┘
-     │                  │                    │
-     ▼                  ▼                    ▼
-┌─────────────┐  ┌─────────────┐    ┌─────────────┐
-│ 代码分析    │  │ 重构策略    │    │ 代码修改    │
-│ 问题识别    │  │ 优先级排序  │    │ 测试验证    │
-│ 技术债记录  │  │ 任务分解    │    │ 文档更新    │
-└─────────────┘  └─────────────┘    └─────────────┘
+```mermaid
+graph LR
+    A[Discover<br/>发现阶段] -->|discoveries| B[Plan<br/>规划阶段]
+    B -->|plan| C[Refactor<br/>重构阶段]
+
+    A --> A1[代码分析<br/>问题识别<br/>技术债记录]
+    B --> B1[重构策略<br/>优先级排序<br/>任务分解]
+    C --> C1[代码修改<br/>测试验证<br/>文档更新]
 ```

 ### 4.3.4 使用场景
@@ -114,7 +106,7 @@

 ### 4.4.2 启动方式

-```
+```shell
 /unified-execute-with-file <file>
 ```

@@ -129,15 +121,16 @@

 ### 4.4.4 工作流程

-```
-┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
-│Analyzer │──▶│Developer│──▶│ Tester  │──▶│Reviewer │
-│ 分析    │   │ 开发    │   │ 测试    │   │ 审查    │
-└─────────┘   └─────────┘   └─────────┘   └─────────┘
-     │            │            │            │
-     ▼            ▼            ▼            ▼
- 需求分析      代码实现      测试验证      质量把关
- 代码探索      单元测试      回归测试      最终确认
+```mermaid
+graph LR
+    A[Analyzer<br/>分析] --> B[Developer<br/>开发]
+    B --> C[Tester<br/>测试]
+    C --> D[Reviewer<br/>审查]
+
+    A --> A1[需求分析<br/>代码探索]
+    B --> B1[代码实现<br/>单元测试]
+    C --> C1[测试验证<br/>回归测试]
+    D --> D1[质量把关<br/>最终确认]
 ```

 ---
@@ -161,15 +154,16 @@

 ### 4.5.3 工作流程

-```
-┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
-│Discover │──▶│  Plan   │──▶│  Queue  │──▶│ Execute │
-│ 发现    │   │ 规划    │   │ 排队    │   │ 执行    │
-└─────────┘   └─────────┘   └─────────┘   └─────────┘
-     │            │            │            │
-     ▼            ▼            ▼            ▼
- 识别问题      分析需求      优先级排序    实现方案
- 定义范围      制定计划      依赖关系      验证结果
+```mermaid
+graph LR
+    A[Discover<br/>发现] -->|issues| B[Plan<br/>规划]
+    B -->|plan| C[Queue<br/>排队]
+    C -->|queue| D[Execute<br/>执行]
+
+    A --> A1[识别问题<br/>定义范围]
+    B --> B1[分析需求<br/>制定计划]
+    C --> C1[优先级排序<br/>依赖关系]
+    D --> D1[实现方案<br/>验证结果]
 ```

 ---
@@ -182,21 +176,20 @@

 ### 4.6.2 启动方式

-```
+```shell
 /integration-test-cycle
 ```

 ### 4.6.3 工作流程

-```
-┌─────────┐   ┌─────────┐   ┌─────────┐
-│Generate │──▶│ Execute │──▶│ Verify  │
-│ 生成    │   │ 执行    │   │ 验证    │
-└─────────┘   └─────────┘   └─────────┘
-     │            │            │
-     ▼            ▼            ▼
- 测试用例      运行测试      覆盖率分析
- Mock 数据     失败分析      缺口补充
+```mermaid
+graph LR
+    A[Generate<br/>生成] --> B[Execute<br/>执行]
+    B --> C[Verify<br/>验证]
+
+    A --> A1[测试用例<br/>Mock 数据]
+    B --> B1[运行测试<br/>失败分析]
+    C --> C1[覆盖率分析<br/>缺口补充]
 ```

 ---
@@ -209,7 +202,7 @@

 ### 4.7.2 启动方式

-```
+```shell
 /review-cycle
 ```

@@ -234,7 +227,7 @@

 ### 4.8.2 启动方式

-```
+```shell
 /brainstorm-with-file <file>
 ```

--- a/docs/zh/guide/ch06-best-practices.md
+++ b/docs/zh/guide/ch06-best-practices.md
@@ -68,15 +68,16 @@

 ### 6.2.2 审查流程

-```
-┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
-│  提交   │──▶│  审查   │──▶│  反馈   │──▶│  修复   │
-│ 代码    │   │ 代码    │   │ 意见    │   │ 问题    │
-└─────────┘   └─────────┘   └─────────┘   └─────────┘
-     │            │            │            │
-     ▼            ▼            ▼            ▼
-  Push PR      自动审查      人工审查      修复验证
-  CI 检查      6 维度检查    代码走查      再次审查
+```mermaid
+graph LR
+    A[提交代码] --> B[审查代码]
+    B --> C[反馈意见]
+    C --> D[修复问题]
+
+    A --> A1[Push PR<br/>CI检查]
+    B --> B1[自动审查<br/>6维度检查]
+    C --> C1[人工审查<br/>代码走查]
+    D --> D1[修复验证<br/>再次审查]
 ```

 ### 6.2.3 审查清单
--- a/docs/zh/guide/installation.md
+++ b/docs/zh/guide/installation.md
@@ -113,6 +113,78 @@ npm uninstall -g claude-code-workflow
 rm -rf ~/.claude
 ```

+## 故障排除
+
+### 权限问题
+
+如果遇到权限错误：
+
+```bash
+# 使用 sudo（不推荐）
+sudo npm install -g claude-code-workflow
+
+# 或修复 npm 权限（推荐）
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+export PATH=~/.npm-global/bin:$PATH
+```
+
+### PATH 问题
+
+将 npm 全局 bin 添加到您的 PATH：
+
+```bash
+# 对于 bash/zsh
+echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.bashrc
+
+# 对于 fish
+echo 'set -gx PATH (npm config get prefix)/bin $PATH' >> ~/.config/fish/config.fish
+```
+
 ::: info 下一步
 安装完成后，查看[第一个工作流](./first-workflow.md)指南。
 :::
+
+## 快速开始示例
+
+安装完成后，尝试以下命令验证一切正常：
+
+```bash
+# 1. 在您的项目中初始化
+cd your-project
+ccw init
+
+# 2. 尝试简单的分析
+ccw cli -p "分析项目结构" --tool gemini --mode analysis
+
+# 3. 运行主编排器
+/ccw "总结代码库架构"
+
+# 4. 检查可用命令
+ccw --help
+```
+
+### 预期输出
+
+```
+$ ccw --version
+CCW v7.0.5
+
+$ ccw init
+✔ Created .claude/CLAUDE.md
+✔ Created .ccw/workflows/
+✔ Configuration complete
+
+$ ccw cli -p "Analyze project" --tool gemini --mode analysis
+Analyzing with Gemini...
+✔ Analysis complete
+```
+
+### 常见首次使用问题
+
+| 问题 | 解决方案 |
+|-------|----------|
+| `ccw: command not found` | 将 npm 全局 bin 添加到 PATH，或重新安装 |
+| `Permission denied` | 使用 `sudo` 或修复 npm 权限 |
+| `API key not found` | 在 `~/.claude/cli-tools.json` 中配置 API 密钥 |
+| `Node version mismatch` | 更新到 Node.js >= 18.0.0 |
--- a/docs/zh/skills/claude-meta.md
+++ b/docs/zh/skills/claude-meta.md
@@ -32,7 +32,7 @@
 **一句话定位**: 规范生成器 — 6 阶段文档链生成完整规范包（产品简报、PRD、架构、Epics）

 **触发**:
-```
+```shell
 /spec-generator <idea>
 /spec-generator --continue        # 从断点恢复
 /spec-generator -y <idea>        # 自动模式
@@ -46,7 +46,7 @@
 - 纯文档：无代码生成或执行 — 干净移交给现有执行工作流

 **架构概览**:
-```
+```plaintext
 Phase 0:   Specification Study (Read specs/ + templates/ - mandatory prerequisite)
           |
 Phase 1:   Discovery               -> spec-config.json + discovery-context.json
@@ -85,7 +85,7 @@ Phase 6:   Readiness Check         -> readiness-report.md + spec-summary.md
 | [templates/epics-template.md](templates/epics-template.md) | Epic/Story 文档模板 |

 **输出结构**:
-```
+```plaintext
 .workflow/.spec/SPEC-{slug}-{YYYY-MM-DD}/
 ├── spec-config.json              # 会话配置 + 阶段状态
 ├── discovery-context.json        # 代码库探索结果（可选）
@@ -119,7 +119,7 @@ Phase 6:   Readiness Check         -> readiness-report.md + spec-summary.md
 **一句话定位**: 头脑风暴 — 交互式框架生成、多角色并行分析和跨角色综合

 **触发**:
-```
+```shell
 /brainstorm <topic>
 /brainstorm --count 3 "Build platform"
 /brainstorm -y "GOAL: Build SCOPE: Users" --count 5
@@ -169,7 +169,7 @@ Artifacts  N×Role  Synthesis  1×Role
 | `ux-expert` | UX专家 | 用户研究、信息架构、旅程 |

 **输出结构**:
-```
+```plaintext
 .workflow/active/WFS-{topic}/
 ├── workflow-session.json              # 会话元数据
 ├── .process/
@@ -204,7 +204,7 @@ Artifacts  N×Role  Synthesis  1×Role
 **一句话定位**: Skill 生成器 — 元技能，用于创建新的 Claude Code Skills

 **触发**:
-```
+```shell
 /skill-generator
 /create skill
 /new skill
@@ -242,7 +242,7 @@ Artifacts  N×Role  Synthesis  1×Role
 | [templates/autonomous-action.md](templates/autonomous-action.md) | 自治动作模板 |

 **执行流程**:
-```
+```plaintext
 Phase 0: 规范研究（强制）
   - Read: ../_shared/SKILL-DESIGN-SPEC.md
   - Read: All templates/*.md files
@@ -269,7 +269,7 @@ Phase 5: 验证和文档
 ```

 **输出结构** (Sequential):
-```
+```plaintext
 .claude/skills/{skill-name}/
 ├── SKILL.md                        # 入口文件
 ├── phases/
@@ -294,7 +294,7 @@ Phase 5: 验证和文档
 **一句话定位**: CCW 命令帮助系统 — 命令搜索、推荐、文档查看

 **触发**:
-```
+```shell
 /ccw-help
 /ccw "task description"          # 自动选择工作流并执行
 /ccw-help search <keyword>       # 搜索命令
@@ -356,7 +356,7 @@ Phase 5: 验证和文档
 **一句话定位**: Skill 调优诊断 — 自动化诊断和优化建议

 **触发**:
-```
+```shell
 /skill-tuning <skill-name>
 ```

@@ -367,7 +367,7 @@ Phase 5: 验证和文档
 - 验证改进

 **诊断流程**:
-```
+```plaintext
 分析 Skill → 识别问题 → 生成建议 → 应用优化 → 验证效果
 ```

@@ -378,7 +378,7 @@ Phase 5: 验证和文档
 **一句话定位**: 命令生成器 — 生成 Claude 命令

 **触发**:
-```
+```shell
 /command-generator
 ```

@@ -394,7 +394,7 @@ Phase 5: 验证和文档
 **一句话定位**: Issue 管理 — Issue 创建、更新、状态管理

 **触发**:
-```
+```shell
 /issue-manage
 /issue:new
 ```
--- a/docs/zh/skills/claude-workflow.md
+++ b/docs/zh/skills/claude-workflow.md
@@ -33,7 +33,7 @@
 **一句话定位**: 统一规划技能 — 4 阶段工作流、计划验证、交互式重规划

 **触发**:
-```
+```shell
 /workflow:plan <task-description>
 /workflow:plan-verify --session <session-id>
 /workflow:replan --session <session-id> [task-id] "requirements"
@@ -61,7 +61,7 @@ default → 'plan'
 6. **累积状态**: planning-notes.md 跨阶段携带上下文用于 N+1 决策

 **计划模式数据流**:
-```
+```plaintext
 用户输入（任务描述）
    ↓
 [转换为结构化格式]
@@ -106,7 +106,7 @@ Phase 4: task-generate-agent --session sessionId
 **一句话定位**: 代理协调执行 — 系统化任务发现、代理协调和状态跟踪

 **触发**:
-```
+```shell
 /workflow:execute
 /workflow:execute --resume-session="WFS-auth"
 /workflow:execute --yes
@@ -125,7 +125,7 @@ Phase 4: task-generate-agent --session sessionId
 - **完成选择**: 自动完成会话（运行 `/workflow:session:complete --yes`）

 **执行过程**:
-```
+```plaintext
 Phase 1: 发现
   ├─ 计算活跃会话数
   └─ 决策:
@@ -188,7 +188,7 @@ Phase 5: 完成
 **一句话定位**: 轻量级快速规划 — 超简单任务的快速规划和执行

 **触发**:
-```
+```shell
 /workflow:lite-plan <simple-task>
 ```

@@ -210,7 +210,7 @@ Phase 5: 完成
 **一句话定位**: 多 CLI 协作规划 — 多个 CLI 工具协作的分析和规划

 **触发**:
-```
+```shell
 /workflow:multi-cli-plan <task>
 ```

@@ -231,7 +231,7 @@ Phase 5: 完成
 **一句话定位**: TDD 工作流 — 测试驱动的开发流程

 **触发**:
-```
+```shell
 /workflow:tdd <feature-description>
 ```

@@ -242,7 +242,7 @@ Phase 5: 完成
 - 循环直到通过

 **流水线**:
-```
+```plaintext
 规划测试 → 编写测试 → [失败] → 实现功能 → [通过] → 完成
                    ↑___________|
 ```
@@ -254,7 +254,7 @@ Phase 5: 完成
 **一句话定位**: 测试修复工作流 — 失败测试的诊断和修复

 **触发**:
-```
+```shell
 /workflow:test-fix <failing-tests>
 ```

@@ -265,7 +265,7 @@ Phase 5: 完成
 - 循环直到通过

 **流水线**:
-```
+```plaintext
 诊断失败 → 确定根因 → [代码问题] → 修复代码 → 验证
                          ↑___________|
 ```
@@ -277,7 +277,7 @@ Phase 5: 完成
 **一句话定位**: Skill 设计工作流 — 创建新的 Claude Code Skills

 **触发**:
-```
+```shell
 /workflow:skill-designer <skill-idea>
 ```

@@ -289,7 +289,7 @@ Phase 5: 完成
 - 验证和文档

 **输出结构**:
-```
+```plaintext
 .claude/skills/{skill-name}/
 ├── SKILL.md              # 入口文件
 ├── phases/
@@ -307,7 +307,7 @@ Phase 5: 完成
 **一句话定位**: Wave 批处理规划 — 批量 Issue 的并行处理规划

 **触发**:
-```
+```shell
 /workflow:wave-plan <issue-list>
 ```

@@ -318,7 +318,7 @@ Phase 5: 完成
 - 执行队列生成

 **Wave 模型**:
-```
+```plaintext
 Wave 1: Issue 1-5 → 并行规划 → 并行执行
 Wave 2: Issue 6-10 → 并行规划 → 并行执行
 ...
--- a/docs/zh/skills/codex-index.md
+++ b/docs/zh/skills/codex-index.md
@@ -40,7 +40,7 @@
 **一句话定位**: 全生命周期编排器 — 规范/实现/测试的 spawn-wait-close 流水线

 **触发**:
-```
+```shell
 /team-lifecycle <task-description>
 ```

@@ -65,7 +65,7 @@
 | fe-qa | 前端 QA、GC 循环 | 2.3 Deep Interaction |

 **流水线定义**:
-```
+```plaintext
 Spec-only (6 beats):
  RESEARCH-001(+D1) → DRAFT-001(+D2) → DRAFT-002(+D3) → DRAFT-003(+D4) → DRAFT-004(+D5) → QUALITY-001(+D6)

@@ -77,7 +77,7 @@ Full-lifecycle (9 beats):
 ```

 **Beat Cycle**:
-```
+```plaintext
 event (phase advance / user resume)
      ↓
  [Orchestrator]
@@ -93,7 +93,7 @@ event (phase advance / user resume)
 ```

 **会话目录**:
-```
+```plaintext
 .workflow/.team/TLS-<slug>-<date>/
 ├── team-session.json           # 流水线状态
 ├── spec/                       # 规范产物
@@ -112,7 +112,7 @@ event (phase advance / user resume)
 **一句话定位**: 多代理并行开发循环 — 需求分析、探索规划、代码开发、验证

 **触发**:
-```
+```shell
 /parallel-dev-cycle TASK="Implement feature"
 /parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123
 /parallel-dev-cycle --auto TASK="Add OAuth"
@@ -138,7 +138,7 @@ event (phase advance / user resume)
 - 消除冗余代码库探索

 **会话结构**:
-```
+```plaintext
 {projectRoot}/.workflow/.cycle/
 ├── {cycleId}.json                     # 主状态文件
 ├── {cycleId}.progress/
@@ -156,7 +156,7 @@ event (phase advance / user resume)
 ```

 **执行流程**:
-```
+```plaintext
 Phase 1: 会话初始化
    ↓ cycleId, state, progressDir

@@ -190,13 +190,13 @@ Phase 4: 完成和摘要
 **一句话定位**: 协作分析 — 文档化讨论、内联探索、理解演进的交互式分析

 **触发**:
-```
+```shell
 /analyze-with-file TOPIC="<question>"
 /analyze-with-file TOPIC="--depth=deep"
 ```

 **核心工作流**:
-```
+```plaintext
 Topic → Explore → Discuss → Document → Refine → Conclude → (Optional) Quick Execute
 ```

@@ -222,7 +222,7 @@ Topic → Explore → Discuss → Document → Refine → Conclude → (Optional
 **一句话定位**: 多视角头脑风暴 — 4 视角（Product、Technical、Risk、User）并行分析

 **触发**:
-```
+```shell
 /brainstorm-with-file TOPIC="<idea>"
 ```

@@ -246,12 +246,12 @@ Topic → Explore → Discuss → Document → Refine → Conclude → (Optional
 **一句话定位**: 假设驱动调试 — 文档化探索、理解演进、分析辅助修正

 **触发**:
-```
+```shell
 /debug-with-file BUG="<bug description>"
 ```

 **核心工作流**:
-```
+```plaintext
 Explore → Document → Log → Analyze → Correct Understanding → Fix → Verify
 ```

@@ -262,7 +262,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 - **学习保留**: 保留从失败尝试中学到的内容

 **会话文件夹结构**:
-```
+```plaintext
 {projectRoot}/.workflow/.debug/DBG-{slug}-{date}/
 ├── debug.log           # NDJSON 日志（执行证据）
 ├── understanding.md    # 探索时间线 + 整合理解
@@ -283,7 +283,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **一句话定位**: 协作规划 — 多代理协作规划（替代 team-planex）

 **触发**:
-```
+```shell
 /collaborative-plan-with-file <task>
 ```

@@ -299,7 +299,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **一句话定位**: 通用执行引擎 — 替代 workflow-execute

 **触发**:
-```
+```shell
 /unified-execute-with-file <session>
 ```

@@ -315,7 +315,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **一句话定位**: 需求路线图规划

 **触发**:
-```
+```shell
 /roadmap-with-file <requirements>
 ```

@@ -331,7 +331,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **一句话定位**: 审查循环（Codex 版本）

 **触发**:
-```
+```shell
 /review-cycle <target>
 ```

@@ -347,7 +347,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **一句话定位**: 测试修复工作流

 **触发**:
-```
+```shell
 /workflow-test-fix-cycle <failing-tests>
 ```

@@ -364,7 +364,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **一句话定位**: 智能代码清理

 **触发**:
-```
+```shell
 /clean <target>
 ```

@@ -380,7 +380,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **一句话定位**: CSV 波处理管道

 **触发**:
-```
+```shell
 /csv-wave-pipeline <csv-file>
 ```

@@ -396,7 +396,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **一句话定位**: Memory 压缩（Codex 版本）

 **触发**:
-```
+```shell
 /memory-compact
 ```

@@ -412,7 +412,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **一句话定位**: CLI 工具执行规范

 **触发**:
-```
+```shell
 /ccw-cli-tools <command>
 ```

@@ -428,7 +428,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **一句话定位**: Issue 发现

 **触发**:
-```
+```shell
 /issue-discover <context>
 ```

--- a/docs/zh/workflows/4-level.md
+++ b/docs/zh/workflows/4-level.md
@@ -4,7 +4,7 @@ CCW 四级工作流系统提供了一种从规格说明到部署的结构化软

 ## 概述

-```
+```text
 Level 1: 规格说明 → Level 2: 规划 → Level 3: 实现 → Level 4: 验证
 ```

@@ -38,7 +38,7 @@ Level 1: 规格说明 → Level 2: 规划 → Level 3: 实现 → Level 4: 验

 ### 示例任务

-```
+```text
 RESEARCH-001 → DRAFT-001 → DRAFT-002 → DRAFT-003 → DRAFT-004 → QUALITY-001
 ```

@@ -95,7 +95,7 @@ RESEARCH-001 → DRAFT-001 → DRAFT-002 → DRAFT-003 → DRAFT-004 → QUALITY

 任务根据依赖关系按拓扑顺序执行:

-```
+```text
 TASK-001 (无依赖) → TASK-002 (依赖 001) → TASK-003 (依赖 002)
 ```

@@ -142,7 +142,7 @@ TASK-001 (无依赖) → TASK-002 (依赖 001) → TASK-003 (依赖 002)

 事件驱动执行，由协调器编排:

-```
+```text
 Event           Coordinator              Workers
 ────────────────────────────────────────────────
 callback/resume → handleCallback ─────────────────┐
@@ -172,7 +172,7 @@ callback <───────────────────────

 对于简单的线性继任，工作器可以直接生成后继者:

-```
+```text
 [Worker A] complete
    → Check: 1 ready task? simple successor?
    → YES: Spawn Worker B directly
@@ -183,7 +183,7 @@ callback <───────────────────────

 某些史诗可以并行执行:

-```
+```text
 EPIC-003: Content Modules ──┐
                           ├──→ EPIC-005: Interaction Features
 EPIC-004: Search & Nav ────┘
--- a/docs/zh/workflows/best-practices.md
+++ b/docs/zh/workflows/best-practices.md
@@ -135,7 +135,7 @@

 ### 良好的工作流

-```
+```text
 [Specification]
  ↓ Clear requirements with acceptance criteria
 [Planning]
@@ -149,7 +149,7 @@

 ### 有问题的工作流

-```
+```text
 [Specification]
  ↓ Vague requirements, no acceptance criteria
 [Planning]
--- a/docs/zh/workflows/index.md
+++ b/docs/zh/workflows/index.md
@@ -4,7 +4,7 @@ CCW 的 4 级工作流系统编排从需求到部署代码的整个开发生命

 ## 工作流级别

-```
+```text
 Level 1: 规范
    ↓
 Level 2: 规划
@@ -105,7 +105,7 @@ Skill(skill="team-lifecycle-v4", args="构建用户身份验证系统")

 ## 工作流可视化

-```
+```text
 ┌─────────────────────────────────────────────────────────────┐
 │                    工作流编排                               │
 ├─────────────────────────────────────────────────────────────┤