Files

T

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

- 完整的部署步骤文档
- 环境配置说明
- 工作流使用指南
- 故障排查说明
- 自动化初始化脚本

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-07-01 08:49:50 +08:00

8.6 KiB

Raw Blame History

sanguo_moziplus_v3 v0.5 部署指南

概述

v0.5 采用 Main + Sub Agent 动态编排架构，通过 Gitea 进行协作管理。

快速开始

前置要求

Claude Code v2.1.39+
Node.js v18+ (用于运行工作流脚本)
Git
Gitea 实例 (或 GitHub)

一键部署

# 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:

{
  "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:

{
  "gitea": {
    "baseUrl": "http://192.168.2.154:3000",
    "owner": "sanguo",
    "repo": "sanguo_moziplus_v3",
    "defaultBranch": "main"
  }
}

步骤 2: 安装依赖

# 确保项目目录正确
cd ~/.openclaw/sanguo_projects/sanguo_moziplus_v3

# 工作流脚本需要 Node.js (如需运行 JavaScript 工作流)
npm install --save-dev fs path

步骤 3: 创建 Main Agent 配置

创建 .claude/CLAUDE.md:

# 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:

# 查看已安装的 Skills
ls ~/.claude/skills/

# 如需安装 Superpowers
# 参考 Superpowers Marketplace

步骤 5: 验证部署

5.1 测试 Gitea 连接

# 在 Claude Code 中测试
claude "测试 Gitea 连接"

5.2 测试规则生成

// 在 Claude Code 中
import { generateGiteaRules } from '.claude/workflows/helpers/gitea-rules-generator.js'
console.log(generateGiteaRules())

5.3 测试工作流

// 在 Claude Code 中
Workflow({
  scriptPath: ".claude/workflows/gitea-orchestration.js",
  args: "实现用户登录功能"
})

工作流使用

基本用法

// 在 Claude Code 中
Workflow({
  scriptPath: ".claude/workflows/gitea-orchestration.js",
  args: "任务描述"
})

高级用法

// 自定义配置
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

{
  "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:

#!/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 连接失败

检查:

确认 gitea-config.json 配置正确
检查网络连接
验证 Gitea 服务器可访问

问题 2: 工作流无法运行

检查:

确认 Claude Code 版本支持 Workflow 工具
检查工作流文件路径
查看 Claude Code 日志

问题 3: Sub Agent 无法访问 Gitea

检查:

确认 Git 凭证配置
检查 Gitea 权限
验证 SSH/HTTPS 访问

升级指南

从 v0.4 升级

v0.4 使用三实例方案，v0.5 使用 Main + Sub Agent：

保留:
- GLM-5.2 配置
- Superpowers Skills
- 角色 Skills
移除:
- tmux 三实例配置
- 启动脚本 (如不需要)
新增:
- gitea-config.json
- gitea-orchestration.js
- gitea-rules-generator.js
迁移:
- 更新 CLAUDE.md 为 Main Agent 配置
- 使用 Gitea 协作替代 SendMessage

生产部署

使用 systemd (Linux)

创建 /etc/systemd/system/sanguo.service:

[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 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>

8.6 KiB Raw Blame History Unescape Escape