diff --git a/docs/design/04-design-v0.4.md b/docs/design/04-design-v0.4.md new file mode 100644 index 0000000..ca57c8b --- /dev/null +++ b/docs/design/04-design-v0.4.md @@ -0,0 +1,980 @@ +# sanguo_moziplus_v3 设计文档 v0.4 + +**项目名称**: sanguo_moziplus_v3 +**版本**: v0.4 +**创建日期**: 2026-06-30 +**状态**: Draft +**基于**: v0.3 + 三实例方案 + +--- + +## 1. 版本变更 + +| 版本 | 变更说明 | 日期 | +|------|---------|------| +| v0.1 | 初始设计 | 2026-06-29 | +| v0.2 | 基于 videotext 调研更新，集成 GLM-5.2、Web 访问 | 2026-06-29 | +| v0.3 | 移除 CCB，采用 Claude Code 内置多 Agent 能力 | 2026-06-30 | +| **v0.4** | **三实例方案：所有 Agent 共享 Superpowers skills** | **2026-06-30** | + +### v0.4 核心变化 + +| 变更项 | v0.3 | v0.4 | 原因 | +|--------|------|------|------| +| **Agent 数量** | 1 个主 Agent | **3 个独立实例** | 清晰的角色隔离 | +| **实例类型** | Claude Code 主实例 | **3 个 Claude Code 实例** | 统一的技术栈 | +| **Skills 访问** | 主实例访问 | **所有实例共享 Superpowers** | 统一的能力库 | +| **角色定义** | 通过 Agent 类型 | **通过 CLAUDE.md** | 更清晰的角色隔离 | +| **协作方式** | Agent 工具调用 | **SendMessage 跨实例** | 更灵活的协作 | + +--- + +## 2. 架构概述 + +### 2.1 系统架构图 + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ tmux sanguo_dev 会话 │ +│ │ +│ ┌───────────────────────────────────────────────────────────────┐ │ +│ │ tmux pane #0: Claude (架构师/项目经理) │ │ +│ │ 项目: ~/.claude/projects/sanguo-main │ │ +│ │ 配置: sanguo-main/.claude/CLAUDE.md │ │ +│ │ 职责: 需求分析、架构设计、任务拆分、审查、验收 │ │ +│ │ 限制: 绝对不亲自编写代码 │ │ +│ └───────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌───────────────────────────────────────────────────────────────┐ │ +│ │ tmux pane #1: Codex (后端开发) │ │ +│ │ 项目: ~/.claude/projects/sanguo-backend │ │ +│ │ 配置: sanguo-backend/.claude/CLAUDE.md │ │ +│ │ 职责: 服务端代码、API、数据库、Migration、测试 │ │ +│ │ 限制: 只处理后端任务 │ │ +│ └───────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌───────────────────────────────────────────────────────────────┐ │ +│ │ tmux pane #2: Gemini (前端开发) │ │ +│ │ 项目: ~/.claude/projects/sanguo-frontend │ │ +│ │ 配置: sanguo-frontend/.claude/CLAUDE.md │ │ +│ │ 职责: 前端组件、页面、样式、交互逻辑、审查 │ │ +│ │ 限制: 只处理前端任务 │ │ +│ └───────────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────────────┐ +│ Superpowers Skills (共享) │ +│ 路径: ~/.claude/skills/ │ +│ 所有三个实例都可以访问 │ +│ │ +│ ┌───────────────────────────────────────────────────────────────┐ │ +│ │ • CODE-REVIEW (代码审查专业知识) │ │ +│ │ • test-engineer (测试专业知识) │ │ +│ │ • copywriting-base (营销文案等47个技能) │ │ +│ │ • debugger (调试技能) │ │ +│ │ • ... (100+ 专业技能) │ │ +│ └───────────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────────────┐ +│ GLM-5.2 (统一后端) │ +│ 端点: https://api.z.ai/api/anthropic │ +│ 所有三个实例通过同一模型执行 │ +└─────────────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────────────┐ +│ Web 访问层 (ttyd) │ +│ 端口: 8088 │ +│ 访问: http://YOUR_LAN_IP:8088 │ +│ 共享 tmux sanguo_dev 会话 │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +### 2.2 完整链路 + +``` +用户输入需求 + ↓ +Claude (架构师) 接收 + ↓ +加载 planning skill 进行规划 + ↓ +SendMessage 指派任务: + → backend: "实现后端 API" + → frontend: "实现前端页面" + ↓ +Codex (后端) 加载 backend-dev skill +Gemini (前端) 加载 frontend-dev skill + ↓ +各自执行任务 (通过 GLM-5.2) + ↓ +SendMessage 返回结果给架构师 + ↓ +Claude (架构师) 加载 CODE-REVIEW skill 审查 + ↓ +Git 提交 +``` + +--- + +## 3. 三实例角色定义 + +### 3.1 Claude — 架构师/项目经理 + +**项目配置**: +- 项目路径: `~/.claude/projects/sanguo-main` +- CLAUDE.md: `sanguo-main/.claude/CLAUDE.md` + +**角色定义**: +```markdown +# sanguo-main/.claude/CLAUDE.md + +## 角色定义 + +你是架构师/项目经理，负责项目的整体规划和协调。 + +### 核心职责 + +- 需求分析和理解 +- 架构设计和技术选型 +- 任务拆分和优先级排序 +- 代码审核和质量把关 +- 最终验收和 Git 提交管理 + +### 严格限制 + +**绝对不亲自编写代码**。所有编码任务必须通过 SendMessage 指派给 backend 或 frontend agent。 + +### 工作流程 + +1. 接收用户需求 +2. 加载 planning skill 进行规划 +3. 拆分任务为后端和前端两部分 +4. 通过 SendMessage 指派任务: + - SendMessage({ to: "backend", message: "..." }) + - SendMessage({ to: "frontend", message: "..." }) +5. 等待 agents 返回结果 +6. 加载 CODE-REVIEW skill 审查代码 +7. 整合结果并提交 Git + +### 协作规范 + +- 使用 Superpowers skills 进行: + - 规划: planning skill + - 审查: CODE-REVIEW skill + - 调试: debugger skill + - 验收: test-engineer skill + +- 向 backend/frontend 指派任务时，提供: + - 清晰的任务描述 + - 技术要求和约束 + - 预期输出格式 + - 验收标准 + +### 决策框架 (Linus 三问) + +1. 这是现实问题还是想象问题？ → 拒绝过度设计 +2. 这个问题真的需要解决吗？ → 拒绝伪需求 +3. 这个方案真的能解决问题吗？ → 拒绝自嗨 +``` + +**Superpowers 使用**: +- `planning` — 技术方案规划 +- `CODE-REVIEW` — 代码审查 +- `debugger` — 问题调试 +- `test-engineer` — 测试策略 + +--- + +### 3.2 Codex — 后端开发 + +**项目配置**: +- 项目路径: `~/.claude/projects/sanguo-backend` +- CLAUDE.md: `sanguo-backend/.claude/CLAUDE.md` + +**角色定义**: +```markdown +# sanguo-backend/.claude/CLAUDE.md + +## 角色定义 + +你是后端开发专家，专注于服务器端代码实现。 + +### 核心职责 + +- 服务端代码实现 (Node.js/Python/Go 等) +- API 设计和实现 (REST/GraphQL/gRPC) +- 数据库设计和 Migration +- 单元测试和集成测试 +- 性能优化和错误处理 + +### 严格限制 + +- 只处理后端任务 +- 拒绝前端相关任务 (组件、页面、样式) +- 如果收到前端任务，明确拒绝并告知转给 frontend agent + +### 工作流程 + +1. 从架构师接收任务 (通过 SendMessage) +2. 加载 backend-dev skill 进行分析 +3. 设计实现方案 +4. 编写代码 +5. 编写测试 +6. 自测验证 +7. 返回结果给架构师 (通过 SendMessage) + +### 技术标准 + +- 代码规范: 遵循项目约定的代码风格 +- API 设计: RESTful 原则，清晰的错误码 +- 数据库: 规范化设计，适当的索引 +- 测试: 单元测试覆盖率 > 80% +- 文档: API 文档 (OpenAPI/Swagger) + +### Superpowers 使用 + +- `CODE-REVIEW` — 自我审查代码 +- `debugger` — 调试后端问题 +- `test-engineer` — 编写测试 + +### 输出格式 + +完成任务后，通过 SendMessage 返回: +- 实现的文件列表 +- API 端点说明 +- 数据库变更 (如有) +- 测试结果 +- 已知问题或限制 +``` + +**backend-dev Skill**: +```markdown +## ~/.claude/skills/backend-dev/SKILL.md + +你现在是后端开发专家。专注于服务器端代码实现。 + +### 核心原则 + +1. **API First**: 先设计 API，再实现逻辑 +2. **测试驱动**: 先写测试，再写代码 +3. **安全优先**: 输入验证、输出编码、权限检查 +4. **性能意识**: 避免N+1查询、适当缓存、异步处理 + +### 实现流程 + +1. **理解需求**: 确认功能、约束、验收标准 +2. **设计 API**: 端点、方法、参数、响应 +3. **设计数据库**: 表结构、索引、关系 +4. **实现逻辑**: 按照最佳实践编写代码 +5. **编写测试**: 单元测试、集成测试 +6. **自测验证**: 确保功能正常 + +### 拒绝任务 + +如果任务涉及: +- 前端组件 +- 页面样式 +- UI 交互 +- 浏览器兼容性 + +明确拒绝并告知转给 frontend agent。 +``` + +--- + +### 3.3 Gemini — 前端开发 + +**项目配置**: +- 项目路径: `~/.claude/projects/sanguo-frontend` +- CLAUDE.md: `sanguo-frontend/.claude/CLAUDE.md` + +**角色定义**: +```markdown +# sanguo-frontend/.claude/CLAUDE.md + +## 角色定义 + +你是前端开发专家，专注于用户界面实现。 + +### 核心职责 + +- 前端组件开发 (React/Vue/等) +- 页面布局和样式实现 +- 用户交互逻辑 +- 前端性能优化 +- 浏览器兼容性处理 +- 代码审查和安全审计 + +### 严格限制 + +- 只处理前端任务 +- 拒绝后端相关任务 (API、数据库、服务器逻辑) +- 如果收到后端任务，明确拒绝并告知转给 backend agent + +### 工作流程 + +1. 从架构师接收任务 (通过 SendMessage) +2. 加载 frontend-dev skill 进行分析 +3. 设计组件结构 +4. 实现页面和样式 +5. 实现交互逻辑 +6. 浏览器测试 +7. 返回结果给架构师 (通过 SendMessage) + +### 技术标准 + +- 组件化: 可复用的组件设计 +- 响应式: 适配不同设备和屏幕 +- 性能: 懒加载、代码分割、缓存优化 +- 可访问性: ARIA 标准、键盘导航 +- 兼容性: 支持主流浏览器 + +### Superpowers 使用 + +- `CODE-REVIEW` — 审查前端代码 +- `ui-ux-pro-max` — UI/UX 设计指导 +- `debugger` — 调试前端问题 + +### 输出格式 + +完成任务后，通过 SendMessage 返回: +- 实现的组件列表 +- 页面预览或截图 +- 交互说明 +- 性能优化措施 +- 兼容性问题 (如有) +``` + +**frontend-dev Skill**: +```markdown +## ~/.claude/skills/frontend-dev/SKILL.md + +你现在是前端开发专家。专注于用户界面实现。 + +### 核心原则 + +1. **组件优先**: 可复用的组件设计 +2. **移动优先**: 响应式设计，移动设备优先 +3. **渐进增强**: 基础功能优先，逐步增强 +4. **性能第一**: 懒加载、代码分割、资源优化 + +### 实现流程 + +1. **理解需求**: 确认功能、UI设计、交互要求 +2. **组件设计**: 拆分为可复用的组件 +3. **样式实现**: 响应式布局、动画效果 +4. **交互实现**: 事件处理、状态管理 +5. **测试验证**: 浏览器测试、性能测试 +6. **优化改进**: 性能优化、兼容性处理 + +### 拒绝任务 + +如果任务涉及: +- API 端点实现 +- 数据库设计 +- 服务器逻辑 +- 后端性能优化 + +明确拒绝并告知转给 backend agent。 +``` + +--- + +## 4. Superpowers Skills 共享 + +### 4.1 共享机制 + +**所有三个实例共享同一套 Superpowers skills**: + +``` +~/.claude/skills/ +├── CODE-REVIEW/ ← 三实例共享 +├── test-engineer/ ← 三实例共享 +├── copywriting-base/ ← 三实例共享 +│ ├── skills/ +│ │ ├── copywriting/ ← 三实例共享 +│ │ ├── seo-audit/ ← 三实例共享 +│ │ └── ... (47 skills) +├── debugger/ ← 三实例共享 +├── ui-ux-pro-max/ ← 三实例共享 +└── ... (100+ skills) +``` + +### 4.2 使用差异 + +**虽然共享同一套 skills，但使用方式因角色而异**: + +| Skill | Claude (架构师) | Codex (后端) | Gemini (前端) | +|-------|----------------|-------------|---------------| +| **planning** | ✅ 主要使用 | ⚠️ 仅规划自己的实现 | ⚠️ 仅规划自己的实现 | +| **CODE-REVIEW** | ✅ 审查所有代码 | ✅ 自我审查 | ✅ 自我审查 + 审查前端 | +| **debugger** | ✅ 调试整体问题 | ✅ 调试后端问题 | ✅ 调试前端问题 | +| **test-engineer** | ✅ 设计测试策略 | ✅ 编写后端测试 | ✅ 编写前端测试 | +| **ui-ux-pro-max** | ❌ 不使用 | ❌ 不使用 | ✅ 主要使用 | +| **copywriting** | ❌ 不使用 | ❌ 不使用 | ⚠️ 仅文案相关 | + +### 4.3 角色 Skills + +**新增三个角色专属 skills**: + +``` +~/.claude/skills/ +├── architect-role/ ← 架构师专属 +├── backend-dev/ ← 后端开发专属 +└── frontend-dev/ ← 前端开发专属 +``` + +--- + +## 5. 协作流程 + +### 5.1 SendMessage 机制 + +**跨实例通信**: + +``` +Claude (架构师) Codex (后端) + │ │ + │─── SendMessage ──────────────>│ + │ to: "backend" │ + │ message: "实现用户 API" │ + │ │ + │ │ + │<──── SendMessage ─────────────│ + │ to: "main" │ + │ message: "后端完成，返回..." │ + │ │ +``` + +**验证需求**: 需要验证 Claude Code 的 SendMessage 是否支持跨实例通信。 + +### 5.2 典型工作流 + +**场景：实现用户认证系统** + +``` +1. 用户: "实现用户认证系统" + ↓ +2. Claude (架构师) 接收 + - 加载 planning skill + - 规划任务: JWT认证 + 登录页面 + ↓ +3. Claude 指派任务 + - SendMessage({ to: "backend", message: "实现JWT认证API" }) + - SendMessage({ to: "frontend", message: "实现登录注册页面" }) + ↓ +4. Codex (后端) 执行 + - 加载 backend-dev skill + - 设计API: /auth/login, /auth/register + - 实现JWT逻辑 + - 编写测试 + - SendMessage({ to: "main", message: "后端完成" }) + ↓ +5. Gemini (前端) 执行 + - 加载 frontend-dev skill + - 设计登录页面组件 + - 实现表单验证 + - 调用后端API + - SendMessage({ to: "main", message: "前端完成" }) + ↓ +6. Claude (架构师) 整合 + - 加载 CODE-REVIEW skill + - 审查后端代码 + - 审查前端代码 + - 集成测试 + - Git 提交 +``` + +### 5.3 错误处理 + +**任务拒绝流程**: + +``` +Codex (后端) 收到前端任务 + ↓ +加载 backend-dev skill + ↓ +识别为前端任务 + ↓ +SendMessage({ to: "main", message: "这不是后端任务，请转给 frontend" }) + ↓ +Claude (架构师) 重新指派 + ↓ +SendMessage({ to: "frontend", message: "原任务..." }) +``` + +--- + +## 6. 实施步骤 + +### Phase 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": "6903e83faf454106aa7529c9e18e2ea5.gYMSjWwk1XDN0U5h", + "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.2[1m]", + "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.2[1m]" + } +} +``` + +#### 1.2 安装 ttyd + +```bash +brew install ttyd +``` + +**配置 `~/.ttyd`**: +``` +address = "0.0.0.0" +port = "8088" +permit-write = true +enable-basic-auth = false +``` + +--- + +### Phase 2: 创建项目结构 + +#### 2.1 创建三个项目目录 + +```bash +# 创建项目目录 +mkdir -p ~/.claude/projects/sanguo-main/.claude +mkdir -p ~/.claude/projects/sanguo-backend/.claude +mkdir -p ~/.claude/projects/sanguo-frontend/.claude +``` + +#### 2.2 创建 CLAUDE.md 文件 + +**sanguo-main/.claude/CLAUDE.md**: +```markdown +# sanguo-main — 架构师/项目经理 + +[使用第 3.1 节的完整内容] +``` + +**sanguo-backend/.claude/CLAUDE.md**: +```markdown +# sanguo-backend — 后端开发 + +[使用第 3.2 节的完整内容] +``` + +**sanguo-frontend/.claude/CLAUDE.md**: +```markdown +# sanguo-frontend — 前端开发 + +[使用第 3.3 节的完整内容] +``` + +--- + +### Phase 3: 创建角色 Skills + +#### 3.1 创建 architect-role skill + +```bash +mkdir -p ~/.claude/skills/architect-role +``` + +**`~/.claude/skills/architect-role/SKILL.md`**: +```markdown +--- +name: architect-role +description: 当你作为架构师/项目经理角色时使用。负责需求分析、架构设计、任务拆分、代码审查、最终验收。绝对不亲自编写代码。 +--- + +# Architect Role + +你现在是架构师/项目经理角色。 + +## 核心职责 + +- 需求分析和理解 +- 架构设计和技术选型 +- 任务拆分和优先级排序 +- 代码审核和质量把关 +- 最终验收和 Git 提交管理 + +## 严格限制 + +**绝对不亲自编写代码**。 + +## 工作流程 + +1. 接收用户需求 +2. 进行需求分析 +3. 规划技术方案 +4. 拆分任务 +5. 指派给合适的 agent (backend/frontend) +6. 等待并整合结果 +7. 审查和验收 +8. 提交 Git +``` + +#### 3.2 创建 backend-dev skill + +```bash +mkdir -p ~/.claude/skills/backend-dev +``` + +**`~/.claude/skills/backend-dev/SKILL.md`**: +```markdown +--- +name: backend-dev +description: 后端开发专家。专注于服务器端代码、API、数据库、测试。只处理后端任务，拒绝前端任务。 +--- + +# Backend Developer + +你现在是后端开发专家。 + +## 核心职责 + +- 服务端代码实现 +- API 设计和实现 +- 数据库设计和 Migration +- 单元测试和集成测试 + +## 严格限制 + +- 只处理后端任务 +- 拒绝前端相关任务 + +## 实现流程 + +1. 理解需求 +2. 设计 API +3. 设计数据库 +4. 实现代码 +5. 编写测试 +6. 自测验证 +``` + +#### 3.3 创建 frontend-dev skill + +```bash +mkdir -p ~/.claude/skills/frontend-dev +``` + +**`~/.claude/skills/frontend-dev/SKILL.md`**: +```markdown +--- +name: frontend-dev +description: 前端开发专家。专注于组件、页面、样式、交互。只处理前端任务，拒绝后端任务。 +--- + +# Frontend Developer + +你现在是前端开发专家。 + +## 核心职责 + +- 前端组件开发 +- 页面布局和样式 +- 用户交互逻辑 +- 浏览器兼容性 + +## 严格限制 + +- 只处理前端任务 +- 拒绝后端相关任务 + +## 实现流程 + +1. 理解需求 +2. 组件设计 +3. 样式实现 +4. 交互实现 +5. 浏览器测试 +``` + +--- + +### Phase 4: tmux 会话配置 + +#### 4.1 创建 tmux 配置 + +**创建 `~/.tmux-sanguo.conf`**: +```bash +# sanguo tmux 配置 +new-session -d -s sanguo_dev -n "main" + +# pane 0: main (架构师) +selectp -t 0 +split-window -h -p 50 + +# pane 1: backend (后端开发) +selectp -t 1 +split-window -v -p 50 + +# pane 2: frontend (前端开发) +selectp -t 2 + +# 回到 main pane +selectp -t 0 + +# 设置 pane 标题 +select-pane -t 0 -T "Claude (架构师)" +select-pane -t 1 -T "Codex (后端)" +select-pane -t 2 -T "Gemini (前端)" +``` + +#### 4.2 启动 tmux 会话 + +```bash +# 加载配置启动 tmux +tmux new -f ~/.tmux-sanguo.conf + +# 或手动创建 +tmux new -s sanguo_dev +tmux split-window -h +tmux split-window -v +``` + +#### 4.3 在各 pane 中启动 Claude Code + +**pane 0 (架构师)**: +```bash +cd ~/.claude/projects/sanguo-main +claude +# 设置为架构师角色 +``` + +**pane 1 (后端)**: +```bash +cd ~/.claude/projects/sanguo-backend +claude +# 设置为后端开发角色 +``` + +**pane 2 (前端)**: +```bash +cd ~/.claude/projects/sanguo-frontend +claude +# 设置为前端开发角色 +``` + +--- + +### Phase 5: 验证 SendMessage 机制 + +#### 5.1 验证步骤 + +**在 pane 0 (架构师) 中**: +```bash +# 测试发送消息到 backend +SendMessage({ to: "backend", message: "测试消息" }) +``` + +**在 pane 1 (后端) 中**: +```bash +# 检查是否收到消息 +# 如果收到，说明 SendMessage 工作正常 +``` + +#### 5.2 备选方案 + +**如果 SendMessage 不支持跨实例**: + +使用文件系统作为消息队列: +```bash +# 创建消息目录 +mkdir -p ~/.claude/messages/sanguo + +# 架构师发送消息 +echo '{"to": "backend", "message": "实现API"}' > ~/.claude/messages/sanguo/backend_$(date +%s).json + +# 后端监听消息 +# 使用 inotifywait 或 fswatch 监听消息目录 +``` + +--- + +### Phase 6: 启动 Web 访问 + +```bash +# 启动 ttyd 共享 tmux 会话 +ttyd -p 8088 tmux attach -t sanguo_dev + +# 访问: http://YOUR_LAN_IP:8088 +``` + +--- + +## 7. 端口规划 + +| 服务 | 端口 | 说明 | +|------|------|------| +| **ttyd Web** | 8088 | tmux Web 访问 | +| **Claude Code** | 默认 | 由 Claude Code 管理 (每个实例) | + +**已占用端口（避开）**: 3001, 6379, 18789, 19999 + +--- + +## 8. 配置文件汇总 + +### 8.1 配置文件位置 + +| 文件 | 路径 | 用途 | +|------|------|------| +| **settings.json** | `~/.claude/settings.json` | GLM-5.2 端点配置 | +| **ttyd 配置** | `~/.ttyd` | Web 访问配置 | +| **tmux 配置** | `~/.tmux-sanguo.conf` | tmux 会话配置 | +| **main CLAUDE.md** | `sanguo-main/.claude/CLAUDE.md` | 架构师角色定义 | +| **backend CLAUDE.md** | `sanguo-backend/.claude/CLAUDE.md` | 后端角色定义 | +| **frontend CLAUDE.md** | `sanguo-frontend/.claude/CLAUDE.md` | 前端角色定义 | +| **角色 Skills** | `~/.claude/skills/{architect-role,backend-dev,frontend-dev}/` | 角色专属技能 | + +### 8.2 环境变量汇总 + +```bash +# GLM-5.2 (Anthropic 兼容) +export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic" +export ANTHROPIC_API_KEY="你的智谱API_Key" +``` + +--- + +## 9. 技术栈 + +| 组件 | 技术/版本 | 说明 | +|------|----------|------| +| **Claude Code** | v2.1.39+ | 主控 CLI (三个实例) | +| **Superpowers** | Marketplace | 共享技能库 | +| **GLM-5.2** | 智谱 AI | 统一后端 | +| **ttyd** | v1.7.7 | Web 终端 | +| **tmux** | 系统包管理器 | 终端复用 (三 pane) | + +--- + +## 10. 成本估算 + +| 组件 | 用量 | 单价 | 预估成本占比 | +|------|------|------|-------------| +| **Claude (架构师)** | 规划+审查+验收（中） | 低 | ~30% | +| **Codex (后端)** | 代码实现（高） | 低 | ~50% | +| **Gemini (前端)** | 页面实现（中） | 低 | ~20% | + +**v0.4 成本优势**: +- 统一使用 GLM-5.2，成本最低 +- 三个实例按需消耗 token +- 1M 上下文减少频繁请求 + +--- + +## 11. 检查清单 + +### 环境检查 + +- [ ] Claude Code 已安装 +- [ ] tmux 已安装 +- [ ] ttyd 已安装 + +### 配置验证 + +- [ ] `~/.claude/settings.json` 已配置 GLM-5.2 端点 +- [ ] 智谱 API Key 已设置 +- [ ] ttyd 配置 8088 端口 +- [ ] tmux 配置文件已创建 + +### 项目创建 + +- [ ] sanguo-main 项目目录已创建 +- [ ] sanguo-backend 项目目录已创建 +- [ ] sanguo-frontend 项目目录已创建 +- [ ] 三个 CLAUDE.md 文件已创建 + +### Skills 创建 + +- [ ] architect-role skill 已创建 +- [ ] backend-dev skill 已创建 +- [ ] frontend-dev skill 已创建 + +### 功能验证 + +- [ ] tmux 三 pane 会话正常启动 +- [ ] 三个 Claude Code 实例正常启动 +- [ ] SendMessage 跨实例通信正常 +- [ ] 各实例能正确加载角色定义 +- [ ] 各实例能访问 Superpowers skills +- [ ] ttyd web 访问正常 + +--- + +## 12. 故障排查 + +### 12.1 SendMessage 不工作 + +**问题**: 跨实例 SendMessage 无法传递消息 + +**解决**: +1. 验证 Claude Code SendMessage 能力 +2. 使用文件系统作为备选消息队列 +3. 实现简单的轮询机制 + +### 12.2 角色隔离不生效 + +**问题**: 实例没有按照 CLAUDE.md 定义的角色执行 + +**解决**: +1. 确认 CLAUDE.md 文件位置正确 +2. 确认 Claude Code 加载了正确的 CLAUDE.md +3. 在启动 Claude Code 时明确指定角色 + +### 12.3 Skills 访问问题 + +**问题**: 某个实例无法访问 Superpowers skills + +**解决**: +1. 确认 `~/.claude/skills/` 目录存在 +2. 确认技能文件权限正确 +3. 重新安装 Superpowers + +--- + +## 13. 参考资料 + +- [GLM-5.2 - 智谱AI开放文档](https://docs.bigmodel.cn/cn/guide/models/text/glm-5.2) +- [ttyd GitHub](https://github.com/tsl0922/ttyd) +- [tmux 官方文档](https://github.com/tmux/tmux/wiki) + +--- + +## 14. 实施状态 + +### 待实施 + +| 组件 | 状态 | 说明 | +|------|------|------| +| **GLM-5.2 配置** | ⚠️ 待配置 | settings.json | +| **ttyd** | ✅ 已安装 | v1.7.7 | +| **项目目录** | ❌ 未创建 | 三个项目目录 | +| **CLAUDE.md 文件** | ❌ 未创建 | 三个角色定义 | +| **角色 Skills** | ❌ 未创建 | architect/backend/frontend | +| **tmux 配置** | ❌ 未创建 | 三 pane 配置 | +| **SendMessage 验证** | ❌ 未验证 | 需要测试跨实例通信 | + +### 需要验证 + +- [ ] SendMessage 跨实例通信是否可用 +- [ ] CLAUDE.md 角色隔离是否生效 +- [ ] Superpowers skills 共享是否正常 +- [ ] 三实例协作流程是否顺畅 + +--- + +**文档版本**: v0.4 +**最后更新**: 2026-06-30 +**作者**: Claude Dev +**审核状态**: Draft +**实施状态**: 待实施