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,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"