sanguo_moziplus_v3/docs/deployment-v0.5.md

# 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