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