docs: 添加 v0.5 部署指南和初始化脚本

- 完整的部署步骤文档 - 环境配置说明 - 工作流使用指南 - 故障排查说明 - 自动化初始化脚本 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-01 08:49:50 +08:00
parent 02afe37412
commit 70c140f5a7
2 changed files with 679 additions and 0 deletions
@@ -0,0 +1,441 @@
+# sanguo_moziplus_v3 v0.5 部署指南
+
+## 概述
+
+v0.5 采用 Main + Sub Agent 动态编排架构，通过 Gitea 进行协作管理。
+
+## 快速开始
+
+### 前置要求
+
+- Claude Code v2.1.39+
+- Node.js v18+ (用于运行工作流脚本)
+- Git
+- Gitea 实例 (或 GitHub)
+
+### 一键部署
+
+```bash
+# 1. 克隆仓库
+git clone http://192.168.2.154:3000/sanguo/sanguo_moziplus_v3.git
+cd sanguo_moziplus_v3
+
+# 2. 运行初始化脚本
+./scripts/init.sh
+
+# 3. 配置 Gitea 连接
+# 编辑 .claude/gitea-config.json
+
+# 4. 启动 Claude Code
+cd ~/.openclaw/sanguo_projects/sanguo_moziplus_v3
+claude
+```
+
+---
+
+## 详细步骤
+
+### 步骤 1: 环境配置
+
+#### 1.1 配置 GLM-5.2
+
+创建 `~/.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
+    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
+    "ANTHROPIC_API_KEY": "你的智谱API_Key",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.2[1m]",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.2[1m]"
+  }
+}
+```
+
+#### 1.2 配置 Gitea
+
+编辑项目中的 `.claude/gitea-config.json`:
+
+```json
+{
+  "gitea": {
+    "baseUrl": "http://192.168.2.154:3000",
+    "owner": "sanguo",
+    "repo": "sanguo_moziplus_v3",
+    "defaultBranch": "main"
+  }
+}
+```
+
+### 步骤 2: 安装依赖
+
+```bash
+# 确保项目目录正确
+cd ~/.openclaw/sanguo_projects/sanguo_moziplus_v3
+
+# 工作流脚本需要 Node.js (如需运行 JavaScript 工作流)
+npm install --save-dev fs path
+```
+
+### 步骤 3: 创建 Main Agent 配置
+
+创建 `.claude/CLAUDE.md`:
+
+```markdown
+# sanguo_moziplus_v3 - Main Agent (编排者)
+
+## 角色
+
+你是任务编排者，负责通过 Gitea 协调 Sub Agents 完成开发任务。
+
+## 核心职责
+
+1. 分析任务需求
+2. 根据 Gitea 规则安排 Sub Agents
+3. 通过 Gitea 追踪进度
+4. 验收并合并 PR
+
+## Gitea 协作流程
+
+### 任务开始
+1. 创建 Issue 记录任务
+2. 安排 Execute Sub Agent
+3. 追踪 PR 创建
+
+### 任务执行
+- Execute Sub Agent: 实现代码 → Push → 创建 PR
+- Review Sub Agent: 审查 PR → 添加评论
+- Test Sub Agent: 测试功能 → 报告结果
+
+### 任务完成
+1. 所有 Review 通过
+2. 所有测试通过
+3. 合并 PR
+4. 关闭 Issue
+
+## Gitea 规则
+
+所有 Sub Agent 都需要遵循 Gitea 规则，规则从配置文件生成。
+
+查看当前规则: 读取 .claude/gitea-config.json
+
+## 严格限制
+
+- 不亲自编写代码
+- 所有编码任务通过 Sub Agents 在 Gitea 上完成
+
+## 可用能力
+
+- planning: 复杂任务规划
+- CODE-REVIEW: 代码审查
+- debugger: 问题调试
+- Agent 工具: 编排 Sub Agents
+```
+
+### 步骤 4: 配置 Superpowers Skills
+
+确保已安装以下 Skills:
+
+```bash
+# 查看已安装的 Skills
+ls ~/.claude/skills/
+
+# 如需安装 Superpowers
+# 参考 Superpowers Marketplace
+```
+
+### 步骤 5: 验证部署
+
+#### 5.1 测试 Gitea 连接
+
+```bash
+# 在 Claude Code 中测试
+claude "测试 Gitea 连接"
+```
+
+#### 5.2 测试规则生成
+
+```javascript
+// 在 Claude Code 中
+import { generateGiteaRules } from '.claude/workflows/helpers/gitea-rules-generator.js'
+console.log(generateGiteaRules())
+```
+
+#### 5.3 测试工作流
+
+```javascript
+// 在 Claude Code 中
+Workflow({
+  scriptPath: ".claude/workflows/gitea-orchestration.js",
+  args: "实现用户登录功能"
+})
+```
+
+---
+
+## 工作流使用
+
+### 基本用法
+
+```javascript
+// 在 Claude Code 中
+Workflow({
+  scriptPath: ".claude/workflows/gitea-orchestration.js",
+  args: "任务描述"
+})
+```
+
+### 高级用法
+
+```javascript
+// 自定义配置
+Workflow({
+  scriptPath: ".claude/workflows/gitea-orchestration.js",
+  args: {
+    task: "实现用户认证",
+    options: {
+      skipTest: false,
+      reviewers: 2
+    }
+  }
+})
+```
+
+---
+
+## 目录结构
+
+```
+sanguo_moziplus_v3/
+├── .claude/
+│   ├── CLAUDE.md              # Main Agent 配置
+│   ├── gitea-config.json      # Gitea 配置
+│   └── workflows/
+│       ├── gitea-orchestration.js        # 主工作流
+│       ├── helpers/
+│       │   └── gitea-rules-generator.js  # 规则生成器
+│       └── plan-execute-review.js       # 备用工作流
+├── docs/
+│   └── design/
+│       └── 06-design-v0.5-dynamic-orchestration.md
+└── scripts/
+    └── init.sh                # 初始化脚本
+```
+
+---
+
+## 配置文件详解
+
+### gitea-config.json
+
+```json
+{
+  "gitea": {
+    "baseUrl": "Gitea 服务器地址",
+    "owner": "仓库所有者",
+    "repo": "仓库名称",
+    "defaultBranch": "主分支"
+  },
+  "rules": {
+    "branchNaming": {
+      "feature": "feature/{任务名}",
+      "fix": "fix/{issue号}-{描述}",
+      "hotfix": "hotfix/{描述}"
+    },
+    "commitNaming": {
+      "feat": "feat: {描述}",
+      "fix": "fix: {描述}",
+      "refactor": "refactor: {描述}"
+    },
+    "prTemplate": {
+      "title": "{类型}: {描述}",
+      "description": "完整描述模板"
+    }
+  },
+  "review": {
+    "checklist": ["检查项1", "检查项2"],
+    "approval": "批准规则"
+  },
+  "agents": {
+    "main": { "role": "编排者" },
+    "execute": { "role": "执行者" },
+    "review": { "role": "审查者" },
+    "test": { "role": "测试者" }
+  }
+}
+```
+
+---
+
+## 初始化脚本
+
+创建 `scripts/init.sh`:
+
+```bash
+#!/bin/bash
+# sanguo_moziplus_v3 初始化脚本
+
+set -e
+
+echo "=== sanguo_moziplus_v3 v0.5 初始化 ==="
+
+# 1. 检查环境
+echo "检查环境..."
+command -v claude >/dev/null 2>&1 || { echo "❌ Claude Code 未安装"; exit 1; }
+command -v git >/dev/null 2>&1 || { echo "❌ Git 未安装"; exit 1; }
+command -v node >/dev/null 2>&1 || { echo "⚠️ Node.js 未安装 (可选)" }
+
+# 2. 创建必要目录
+echo "创建目录..."
+mkdir -p .claude/workflows/helpers
+mkdir -p scripts
+
+# 3. 检查配置文件
+echo "检查配置..."
+if [ ! -f .claude/gitea-config.json ]; then
+  echo "❌ gitea-config.json 不存在"
+  echo "请创建 .claude/gitea-config.json 配置文件"
+  exit 1
+fi
+
+# 4. 检查 Claude Code 配置
+echo "检查 Claude Code 配置..."
+if [ ! -f ~/.claude/settings.json ]; then
+  echo "❌ ~/.claude/settings.json 不存在"
+  echo "请配置 GLM-5.2 端点"
+  exit 1
+fi
+
+# 5. 验证 Gitea 连接
+echo "验证 Gitea 连接..."
+GITEA_URL=$(node -e "
+const fs = require('fs');
+const config = JSON.parse(fs.readFileSync('.claude/gitea-config.json', 'utf-8'));
+console.log(config.gitea.baseUrl);
+")
+echo "Gitea URL: $GITEA_URL"
+
+# 6. 测试 Git 连接
+echo "测试 Git 连接..."
+git remote -v
+
+echo "=== 初始化完成 ==="
+echo ""
+echo "下一步:"
+echo "1. 启动 Claude Code: claude"
+echo "2. 测试工作流: Workflow({ scriptPath: '.claude/workflows/gitea-orchestration.js', args: '测试任务' })"
+```
+
+---
+
+## 故障排查
+
+### 问题 1: Gitea 连接失败
+
+**检查**:
+1. 确认 gitea-config.json 配置正确
+2. 检查网络连接
+3. 验证 Gitea 服务器可访问
+
+### 问题 2: 工作流无法运行
+
+**检查**:
+1. 确认 Claude Code 版本支持 Workflow 工具
+2. 检查工作流文件路径
+3. 查看 Claude Code 日志
+
+### 问题 3: Sub Agent 无法访问 Gitea
+
+**检查**:
+1. 确认 Git 凭证配置
+2. 检查 Gitea 权限
+3. 验证 SSH/HTTPS 访问
+
+---
+
+## 升级指南
+
+### 从 v0.4 升级
+
+v0.4 使用三实例方案，v0.5 使用 Main + Sub Agent：
+
+1. **保留**:
+   - GLM-5.2 配置
+   - Superpowers Skills
+   - 角色 Skills
+
+2. **移除**:
+   - tmux 三实例配置
+   - 启动脚本 (如不需要)
+
+3. **新增**:
+   - gitea-config.json
+   - gitea-orchestration.js
+   - gitea-rules-generator.js
+
+4. **迁移**:
+   - 更新 CLAUDE.md 为 Main Agent 配置
+   - 使用 Gitea 协作替代 SendMessage
+
+---
+
+## 生产部署
+
+### 使用 systemd (Linux)
+
+创建 `/etc/systemd/system/sanguo.service`:
+
+```ini
+[Unit]
+Description=sanguo_moziplus_v3 Development Environment
+After=network.target
+
+[Service]
+Type=simple
+User=your-user
+WorkingDirectory=/path/to/sanguo_moziplus_v3
+ExecStart=/usr/local/bin/claude
+Restart=on-failure
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### 使用 launchd (macOS)
+
+创建 `~/Library/LaunchAgents/com.sanguo.dev.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.sanguo.dev</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/usr/local/bin/claude</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <string>/path/to/sanguo_moziplus_v3</string>
+    <key>RunAtLoad</key>
+    <true/>
+</dict>
+</plist>
+```
+
+---
+
+## 相关文档
+
+- [v0.5 设计文档](./docs/design/06-design-v0.5-dynamic-orchestration.md)
+- [Gitea 配置示例](./.claude/gitea-config.json)
+- [工作流脚本](./.claude/workflows/gitea-orchestration.js)
+
+---
+
+**文档版本**: v0.5
+**最后更新**: 2026-07-01
+**作者**: Claude Dev
+**状态**: Draft
@@ -0,0 +1,238 @@
+#!/bin/bash
+# sanguo_moziplus_v3 v0.5 初始化脚本
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+
+# 颜色定义
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+echo -e "${GREEN}=== sanguo_moziplus_v3 v0.5 初始化 ===${NC}"
+
+# 1. 检查环境
+echo -e "\n${BLUE}1. 检查环境...${NC}"
+
+if ! command -v claude &> /dev/null; then
+    echo -e "${RED}❌ Claude Code 未安装${NC}"
+    echo "请先安装 Claude Code: https://claude.ai/code"
+    exit 1
+fi
+echo -e "${GREEN}✅ Claude Code 已安装${NC}"
+
+if ! command -v git &> /dev/null; then
+    echo -e "${RED}❌ Git 未安装${NC}"
+    exit 1
+fi
+echo -e "${GREEN}✅ Git 已安装${NC}"
+
+# Node.js 是可选的（用于运行 JS 工作流）
+if command -v node &> /dev/null; then
+    echo -e "${GREEN}✅ Node.js 已安装: $(node --version)${NC}"
+else
+    echo -e "${YELLOW}⚠️  Node.js 未安装 (可选，用于运行 JavaScript 工作流)${NC}"
+fi
+
+# 2. 创建必要目录
+echo -e "\n${BLUE}2. 创建目录...${NC}"
+mkdir -p "$PROJECT_DIR/.claude/workflows/helpers"
+mkdir -p "$PROJECT_DIR/scripts"
+echo -e "${GREEN}✅ 目录创建完成${NC}"
+
+# 3. 检查配置文件
+echo -e "\n${BLUE}3. 检查配置文件...${NC}"
+
+if [ ! -f "$PROJECT_DIR/.claude/gitea-config.json" ]; then
+    echo -e "${YELLOW}⚠️  gitea-config.json 不存在${NC}"
+    echo "创建默认配置..."
+    cat > "$PROJECT_DIR/.claude/gitea-config.json" << 'EOF'
+{
+  "gitea": {
+    "baseUrl": "http://192.168.2.154:3000",
+    "owner": "sanguo",
+    "repo": "sanguo_moziplus_v3",
+    "defaultBranch": "main"
+  },
+  "rules": {
+    "branchNaming": {
+      "feature": "feature/{task-name}",
+      "fix": "fix/{issue-number}-{description}",
+      "hotfix": "hotfix/{description}"
+    },
+    "commitNaming": {
+      "feature": "feat: {description}",
+      "fix": "fix: {description}",
+      "refactor": "refactor: {description}",
+      "docs": "docs: {description}",
+      "test": "test: {description}"
+    },
+    "prTemplate": {
+      "title": "{task-type}: {description}",
+      "description": "## 任务\n\n{task-description}\n\n## 技术方案\n\n{approach}\n\n## 实现内容\n\n{changes}\n\n## 测试\n\n{tests}"
+    }
+  },
+  "review": {
+    "checklist": [
+      "代码质量",
+      "安全性",
+      "性能",
+      "测试覆盖",
+      "文档完整性"
+    ],
+    "approval": "至少 2 个 Reviewer 通过"
+  },
+  "agents": {
+    "main": {
+      "role": "编排者",
+      "responsibilities": [
+        "分析任务",
+        "安排 Sub Agents",
+        "验收整合",
+        "合并 PR"
+      ]
+    },
+    "execute": {
+      "role": "执行者",
+      "responsibilities": [
+        "实现功能",
+        "编写测试",
+        "创建 PR"
+      ],
+      "skills": ["backend-dev", "frontend-dev"]
+    },
+    "review": {
+      "role": "审查者",
+      "responsibilities": [
+        "代码审查",
+        "添加 Review 评论",
+        "提供修改建议"
+      ],
+      "skills": ["CODE-REVIEW", "security-reviewer"]
+    },
+    "test": {
+      "role": "测试者",
+      "responsibilities": [
+        "编写测试",
+        "执行测试",
+        "验证修复"
+      ],
+      "skills": ["test-engineer", "e2e-tester"]
+    }
+  }
+}
+EOF
+    echo -e "${GREEN}✅ 已创建默认配置${NC}"
+    echo -e "${YELLOW}⚠️  请编辑 .claude/gitea-config.json 配置你的 Gitea 信息${NC}"
+else
+    echo -e "${GREEN}✅ gitea-config.json 已存在${NC}"
+fi
+
+# 4. 检查 Claude Code 配置
+echo -e "\n${BLUE}4. 检查 Claude Code 配置...${NC}"
+
+if [ ! -f "$HOME/.claude/settings.json" ]; then
+    echo -e "${YELLOW}⚠️  ~/.claude/settings.json 不存在${NC}"
+    echo "请配置 GLM-5.2 端点:"
+    echo ""
+    cat << 'EOF'
+{
+  "env": {
+    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
+    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
+    "ANTHROPIC_API_KEY": "你的智谱API_Key",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.2[1m]",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.2[1m]"
+  }
+}
+EOF
+    echo ""
+    echo "创建配置文件:"
+    echo "  mkdir -p ~/.claude"
+    echo "  vim ~/.claude/settings.json"
+else
+    echo -e "${GREEN}✅ ~/.claude/settings.json 已存在${NC}"
+fi
+
+# 5. 读取并显示 Gitea 配置
+echo -e "\n${BLUE}5. Gitea 配置...${NC}"
+
+if [ -f "$PROJECT_DIR/.claude/gitea-config.json" ]; then
+    if command -v node &> /dev/null; then
+        GITEA_CONFIG=$(node -e "
+const fs = require('fs');
+const config = JSON.parse(fs.readFileSync('$PROJECT_DIR/.claude/gitea-config.json', 'utf-8'));
+console.log('  Base URL: ' + config.gitea.baseUrl);
+console.log('  Owner: ' + config.gitea.owner);
+console.log('  Repository: ' + config.gitea.repo);
+console.log('  主分支: ' + config.gitea.defaultBranch);
+" 2>/dev/null || echo "  无法解析配置文件")
+        echo -e "$GITEA_CONFIG"
+    else
+        echo -e "${YELLOW}⚠️  需要 Node.js 来解析配置${NC}"
+    fi
+fi
+
+# 6. 测试 Git 连接
+echo -e "\n${BLUE}6. 测试 Git 连接...${NC}"
+
+cd "$PROJECT_DIR"
+if git remote -v &> /dev/null; then
+    echo "Git 远程仓库:"
+    git remote -v
+else
+    echo -e "${YELLOW}⚠️  没有配置 Git 远程仓库${NC}"
+    echo "添加远程仓库:"
+    echo "  git remote add origin <your-gitea-url>"
+fi
+
+# 7. 检查 Superpowers Skills
+echo -e "\n${BLUE}7. 检查 Superpowers Skills...${NC}"
+
+SKILLS_DIR="$HOME/.claude/skills"
+if [ -d "$SKILLS_DIR" ]; then
+    SKILL_COUNT=$(ls -1 "$SKILLS_DIR" 2>/dev/null | wc -l)
+    echo -e "${GREEN}✅ Superpowers Skills 已安装: $SKILL_COUNT 个技能${NC}"
+else
+    echo -e "${YELLOW}⚠️  Superpowers Skills 未安装${NC}"
+    echo "请从 Superpowers Marketplace 安装所需技能"
+fi
+
+# 8. 验证工作流文件
+echo -e "\n${BLUE}8. 验证工作流文件...${NC}"
+
+WORKFLOW_FILES=(
+    ".claude/workflows/gitea-orchestration.js"
+    ".claude/workflows/helpers/gitea-rules-generator.js"
+)
+
+for file in "${WORKFLOW_FILES[@]}"; do
+    if [ -f "$PROJECT_DIR/$file" ]; then
+        echo -e "${GREEN}✅ $file${NC}"
+    else
+        echo -e "${RED}❌ $file 不存在${NC}"
+    fi
+done
+
+# 完成
+echo -e "\n${GREEN}=== 初始化完成 ===${NC}"
+echo ""
+echo -e "${BLUE}下一步操作:${NC}"
+echo "1. 编辑配置 (如需要):"
+echo "   vim .claude/gitea-config.json"
+echo ""
+echo "2. 启动 Claude Code:"
+echo "   cd $PROJECT_DIR"
+echo "   claude"
+echo ""
+echo "3. 测试工作流:"
+echo "   在 Claude Code 中运行:"
+echo "   Workflow({ scriptPath: '.claude/workflows/gitea-orchestration.js', args: '测试任务' })"
+echo ""
+echo -e "${BLUE}相关文档:${NC}"
+echo "- 部署指南: docs/deployment-v0.5.md"
+echo "- 设计文档: docs/design/06-design-v0.5-dynamic-orchestration.md"