From ee4dc367d9430159506c5c41618c854db71ed59e Mon Sep 17 00:00:00 2001
From: catlog22 <catlog22@github.com>
Date: Sun, 1 Mar 2026 20:34:11 +0800
Subject: [PATCH] docs: fix 404 errors - add missing zh guide files and fix
 zh-CN config [IDAW-002]

- Add docs/zh/guide/first-workflow.md (Chinese translation)
- Add docs/zh/guide/cli-tools.md (Chinese translation)
- Fix zh-CN locale config to only show existing files (dashboard, terminal, queue)
- Remove non-existent zh-CN sidebar entries that caused 404 errors
---
 docs/.vitepress/config.ts       |  97 +--------------
 docs/zh/guide/cli-tools.md      | 212 ++++++++++++++++++++++++++++++++
 docs/zh/guide/first-workflow.md |  93 ++++++++++++++
 3 files changed, 307 insertions(+), 95 deletions(-)
 create mode 100644 docs/zh/guide/cli-tools.md
 create mode 100644 docs/zh/guide/first-workflow.md

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 87ca1398..792359bd 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -489,110 +489,17 @@ export default withMermaid(defineConfig({
           label: '本页目录'
         },
         nav: [
-          { text: '指南', link: '/zh-CN/guide/ch01-what-is-claude-dms3' },
-          { text: '命令', link: '/zh-CN/commands/claude/' },
-          { text: '技能', link: '/zh-CN/skills/claude-index' },
-          { text: '功能', link: '/zh-CN/features/spec' },
-          { text: '组件', link: '/zh-CN/components/' }
+          { text: '功能', link: '/zh-CN/features/dashboard' }
         ],
         sidebar: {
-          '/zh-CN/guide/': [
-            {
-              text: '📖 指南',
-              collapsible: false,
-              items: [
-                { text: 'Claude Code Workflow 是什么', link: '/zh-CN/guide/ch01-what-is-claude-dms3' },
-                { text: '快速开始', link: '/zh-CN/guide/ch02-getting-started' },
-                { text: '核心概念', link: '/zh-CN/guide/ch03-core-concepts' },
-                { text: '工作流基础', link: '/zh-CN/guide/ch04-workflow-basics' },
-                { text: '高级技巧', link: '/zh-CN/guide/ch05-advanced-tips' },
-                { text: '最佳实践', link: '/zh-CN/guide/ch06-best-practices' }
-              ]
-            },
-            {
-              text: '🚀 快速入口',
-              collapsible: true,
-              items: [
-                { text: '安装', link: '/zh-CN/guide/installation' },
-                { text: '第一个工作流', link: '/zh-CN/guide/first-workflow' },
-                { text: 'CLI 工具', link: '/zh-CN/guide/cli-tools' }
-              ]
-            }
-          ],
-          '/zh-CN/skills/': [
-            {
-              text: '概述',
-              collapsible: false,
-              items: [
-                { text: '技能指南', link: '/zh-CN/skills/' }
-              ]
-            },
-            {
-              text: '📚 规范',
-              collapsible: true,
-              items: [
-                { text: '命名规范', link: '/zh-CN/skills/naming-conventions' }
-              ]
-            },
-            {
-              text: '⚡ Claude Skills',
-              collapsible: true,
-              items: [
-                { text: '概述', link: '/zh-CN/skills/claude-index' },
-                { text: '协作', link: '/zh-CN/skills/claude-collaboration' },
-                { text: '工作流', link: '/zh-CN/skills/claude-workflow' },
-                { text: '记忆', link: '/zh-CN/skills/claude-memory' },
-                { text: '审查', link: '/zh-CN/skills/claude-review' },
-                { text: '元技能', link: '/zh-CN/skills/claude-meta' }
-              ]
-            },
-            {
-              text: '🔧 Codex Skills',
-              collapsible: true,
-              items: [
-                { text: '概述', link: '/zh-CN/skills/codex-index' },
-                { text: '生命周期', link: '/zh-CN/skills/codex-lifecycle' },
-                { text: '工作流', link: '/zh-CN/skills/codex-workflow' },
-                { text: '专项', link: '/zh-CN/skills/codex-specialized' }
-              ]
-            },
-            {
-              text: '🎨 自定义技能',
-              collapsible: true,
-              items: [
-                { text: '概述', link: '/zh-CN/skills/custom' },
-                { text: '核心技能', link: '/zh-CN/skills/core-skills' },
-                { text: '参考', link: '/zh-CN/skills/reference' }
-              ]
-            }
-          ],
           '/zh-CN/features/': [
             {
               text: '⚙️ 核心功能',
               collapsible: false,
               items: [
-                { text: 'Spec 规范系统', link: '/zh-CN/features/spec' },
-                { text: 'Memory 记忆系统', link: '/zh-CN/features/memory' },
-                { text: 'CLI 调用', link: '/zh-CN/features/cli' },
                 { text: 'Dashboard 面板', link: '/zh-CN/features/dashboard' },
                 { text: 'Terminal 终端监控', link: '/zh-CN/features/terminal' },
-                { text: 'Queue 队列管理', link: '/zh-CN/features/queue' },
-                { text: 'CodexLens', link: '/zh-CN/features/codexlens' }
-              ]
-            }
-          ],
-          '/zh-CN/components/': [
-            {
-              text: 'UI 组件',
-              collapsible: true,
-              items: [
-                { text: '概述', link: '/zh-CN/components/index' },
-                { text: 'Button 按钮', link: '/zh-CN/components/ui/button' },
-                { text: 'Card 卡片', link: '/zh-CN/components/ui/card' },
-                { text: 'Input 输入框', link: '/zh-CN/components/ui/input' },
-                { text: 'Select 选择器', link: '/zh-CN/components/ui/select' },
-                { text: 'Checkbox 复选框', link: '/zh-CN/components/ui/checkbox' },
-                { text: 'Badge 徽标', link: '/zh-CN/components/ui/badge' }
+                { text: 'Queue 队列管理', link: '/zh-CN/features/queue' }
               ]
             }
           ]
diff --git a/docs/zh/guide/cli-tools.md b/docs/zh/guide/cli-tools.md
new file mode 100644
index 00000000..ded86ce4
--- /dev/null
+++ b/docs/zh/guide/cli-tools.md
@@ -0,0 +1,212 @@
+# CLI 工具配置
+
+为你的开发工作流配置和自定义 CCW CLI 工具。
+
+## 配置文件
+
+CCW CLI 工具在 `~/.claude/cli-tools.json` 中配置：
+
+```json
+{
+  "version": "3.3.0",
+  "tools": {
+    "tool-id": {
+      "enabled": true,
+      "primaryModel": "model-name",
+      "secondaryModel": "fallback-model",
+      "tags": ["tag1", "tag2"],
+      "type": "builtin | api-endpoint | cli-wrapper"
+    }
+  }
+}
+```
+
+## 工具类型
+
+### 内置工具
+
+具有所有功能的完整工具：
+
+```json
+{
+  "gemini": {
+    "enabled": true,
+    "primaryModel": "gemini-2.5-flash",
+    "secondaryModel": "gemini-2.5-pro",
+    "tags": ["analysis", "debug"],
+    "type": "builtin"
+  }
+}
+```
+
+**功能**：分析 + 写入工具
+
+### API 端点工具
+
+用于专门任务的分析专用工具：
+
+```json
+{
+  "custom-api": {
+    "enabled": true,
+    "primaryModel": "custom-model",
+    "tags": ["specialized-analysis"],
+    "type": "api-endpoint"
+  }
+}
+```
+
+**功能**：仅分析
+
+## CLI 命令格式
+
+### 通用模板
+
+```bash
+ccw cli -p "PURPOSE: [目标] + [原因] + [成功标准]
+TASK: • [步骤 1] • [步骤 2] • [步骤 3]
+MODE: [analysis|write|review]
+CONTEXT: @[文件模式] | Memory: [上下文]
+EXPECTED: [输出格式]
+CONSTRAINTS: [约束]" --tool <tool-id> --mode <mode> --rule <template>
+```
+
+### 必需参数
+
+| 参数 | 描述 | 选项 |
+|-----------|-------------|---------|
+| `--mode <mode>` | **必需** - 执行权限级别 | `analysis`（只读） \| `write`（创建/修改） \| `review`（git 感知审查） |
+| `-p <prompt>` | **必需** - 带有结构化模板的任务提示 | - |
+
+### 可选参数
+
+| 参数 | 描述 | 示例 |
+|-----------|-------------|---------|
+| `--tool <tool>` | 显式工具选择 | `--tool gemini` |
+| `--rule <template>` | 加载规则模板以生成结构化提示 | `--rule analysis-review-architecture` |
+| `--resume [id]` | 恢复之前的会话 | `--resume` 或 `--resume session-id` |
+| `--cd <path>` | 设置工作目录 | `--cd src/auth` |
+| `--includeDirs <dirs>` | 包含额外目录（逗号分隔） | `--includeDirs ../shared,../types` |
+| `--model <model>` | 覆盖工具的主要模型 | `--model gemini-2.5-pro` |
+
+## 工具选择
+
+### 基于标签的路由
+
+根据任务要求选择工具：
+
+```bash
+# 带有 "analysis" 标签的任务路由到 gemini
+ccw cli -p "PURPOSE: 调试认证问题
+TASK: • 追踪认证流程 • 识别失败点
+MODE: analysis" --tool gemini --mode analysis
+
+# 无标签 - 使用第一个启用的工具
+ccw cli -p "PURPOSE: 实现功能 X
+TASK: • 创建组件 • 添加测试
+MODE: write" --mode write
+```
+
+### 显式选择
+
+覆盖自动选择：
+
+```bash
+ccw cli -p "任务描述" --tool codex --mode write
+```
+
+### 规则模板
+
+自动加载结构化提示模板：
+
+```bash
+# 架构审查模板
+ccw cli -p "分析系统架构" --mode analysis --rule analysis-review-architecture
+
+# 功能实现模板
+ccw cli -p "添加 OAuth2 认证" --mode write --rule development-implement-feature
+```
+
+## 模型配置
+
+### 主要 vs 备用
+
+```json
+{
+  "codex": {
+    "primaryModel": "gpt-5.2",
+    "secondaryModel": "gpt-5.2"
+  }
+}
+```
+
+- **primaryModel**：工具的默认模型
+- **secondaryModel**：主要模型失败时的备用
+
+### 可用模型
+
+| 工具 | 可用模型 |
+|------|------------------|
+| gemini | gemini-3-pro-preview, gemini-2.5-pro, gemini-2.5-flash, gemini-2.0-flash |
+| codex | gpt-5.2 |
+| claude | sonnet, haiku |
+| qwen | coder-model |
+
+## 工具标签
+
+标签启用自动工具选择：
+
+| 标签 | 用例 |
+|-----|----------|
+| analysis | 代码审查、架构分析 |
+| debug | 错误诊断、故障排除 |
+| implementation | 功能开发、代码生成 |
+| documentation | 文档生成、技术写作 |
+| testing | 测试生成、覆盖率分析 |
+
+## 验证
+
+要验证你的配置，直接检查配置文件：
+
+```bash
+cat ~/.claude/cli-tools.json
+```
+
+或测试工具可用性：
+
+```bash
+ccw cli -p "PURPOSE: 测试工具可用性
+TASK: 验证工具是否工作
+MODE: analysis" --mode analysis
+```
+
+## 故障排除
+
+### 工具不可用
+
+```bash
+Error: Tool 'custom-tool' not found
+```
+
+**解决方案**：检查工具在配置中是否启用：
+
+```json
+{
+  "custom-tool": {
+    "enabled": true
+  }
+}
+```
+
+### 模型未找到
+
+```bash
+Error: Model 'invalid-model' not available
+```
+
+**解决方案**：使用可用模型列表中的有效模型名称。
+
+::: info 另见
+- [CLI 参考](../cli/commands.md) - CLI 用法
+- [模式](#modes) - 执行模式
+:::
diff --git a/docs/zh/guide/first-workflow.md b/docs/zh/guide/first-workflow.md
new file mode 100644
index 00000000..d2f0d803
--- /dev/null
+++ b/docs/zh/guide/first-workflow.md
@@ -0,0 +1,93 @@
+# 第一个工作流：构建简单 API
+
+在 30 分钟内完成你的第一个 CCW 工作流。我们将从规范到实现构建一个简单的 REST API。
+
+## 我们要构建什么
+
+一个简单的用户 API，包含：
+- GET /users - 获取所有用户
+- GET /users/:id - 根据 ID 获取用户
+- POST /users - 创建新用户
+- PUT /users/:id - 更新用户
+- DELETE /users/:id - 删除用户
+
+## 前提条件
+
+- 已安装 CCW（[安装指南](./installation.md)）
+- Node.js >= 18.0.0
+- 代码编辑器（推荐 VS Code）
+
+## 步骤 1：创建项目（5 分钟）
+
+```bash
+# 创建项目目录
+mkdir user-api
+cd user-api
+
+# 初始化 npm 项目
+npm init -y
+
+# 安装依赖
+npm install express
+npm install --save-dev typescript @types/node @types/express
+```
+
+## 步骤 2：生成规范（5 分钟）
+
+```bash
+# 使用 CCW 生成 API 规范
+ccw cli -p "为用户资源的 CRUD 操作生成 REST API 规范" --mode analysis
+```
+
+CCW 将分析你的请求并生成规范文档。
+
+## 步骤 3：实现 API（15 分钟）
+
+```bash
+# 实现 API
+ccw cli -p "使用 Express 和 TypeScript 按照规范实现用户 API" --mode write
+```
+
+CCW 将：
+1. 创建项目结构
+2. 实现路由
+3. 添加类型定义
+4. 包含错误处理
+
+## 步骤 4：审查代码（5 分钟）
+
+```bash
+# 审查实现
+ccw cli -p "审查用户 API 代码的质量、安全性和最佳实践" --mode analysis
+```
+
+## 步骤 5：测试和运行
+
+```bash
+# 编译 TypeScript
+npx tsc
+
+# 运行服务器
+node dist/index.js
+
+# 测试 API
+curl http://localhost:3000/users
+```
+
+## 预期结果
+
+你应该拥有：
+- `src/index.ts` - 主服务器文件
+- `src/routes/users.ts` - 用户路由
+- `src/types/user.ts` - 用户类型
+- `src/middleware/error.ts` - 错误处理
+
+## 下一步
+
+- [CLI 参考](../cli/commands.md) - 学习所有 CLI 命令
+- [技能库](../skills/core-skills.md) - 探索内置技能
+- [工作流系统](../workflows/4-level.md) - 理解工作流编排
+
+::: tip 恭喜！🎉
+你已经完成了第一个 CCW 工作流。现在你可以将 CCW 用于更复杂的项目。
+:::