sanguo_moziplus_v3/docs/design/04-design-v0.4.md

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

角色定义:

# 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

角色定义:

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

## ~/.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

角色定义:

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

## ~/.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:

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

brew install ttyd

配置 ~/.ttyd:

address = "0.0.0.0"
port = "8088"
permit-write = true
enable-basic-auth = false

---

Phase 2: 创建项目结构

2.1 创建三个项目目录

# 创建项目目录
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:

# sanguo-main — 架构师/项目经理

[使用第 3.1 节的完整内容]

sanguo-backend/.claude/CLAUDE.md:

# sanguo-backend — 后端开发

[使用第 3.2 节的完整内容]

sanguo-frontend/.claude/CLAUDE.md:

# sanguo-frontend — 前端开发

[使用第 3.3 节的完整内容]

---

Phase 3: 创建角色 Skills

3.1 创建 architect-role skill

mkdir -p ~/.claude/skills/architect-role

~/.claude/skills/architect-role/SKILL.md:

---
name: architect-role
description: 当你作为架构师/项目经理角色时使用。负责需求分析、架构设计、任务拆分、代码审查、最终验收。绝对不亲自编写代码。
---

# Architect Role

你现在是架构师/项目经理角色。

## 核心职责

- 需求分析和理解
- 架构设计和技术选型
- 任务拆分和优先级排序
- 代码审核和质量把关
- 最终验收和 Git 提交管理

## 严格限制

**绝对不亲自编写代码**。

## 工作流程

1. 接收用户需求
2. 进行需求分析
3. 规划技术方案
4. 拆分任务
5. 指派给合适的 agent (backend/frontend)
6. 等待并整合结果
7. 审查和验收
8. 提交 Git

3.2 创建 backend-dev skill

mkdir -p ~/.claude/skills/backend-dev

~/.claude/skills/backend-dev/SKILL.md:

---
name: backend-dev
description: 后端开发专家。专注于服务器端代码、API、数据库、测试。只处理后端任务，拒绝前端任务。
---

# Backend Developer

你现在是后端开发专家。

## 核心职责

- 服务端代码实现
- API 设计和实现
- 数据库设计和 Migration
- 单元测试和集成测试

## 严格限制

- 只处理后端任务
- 拒绝前端相关任务

## 实现流程

1. 理解需求
2. 设计 API
3. 设计数据库
4. 实现代码
5. 编写测试
6. 自测验证

3.3 创建 frontend-dev skill

mkdir -p ~/.claude/skills/frontend-dev

~/.claude/skills/frontend-dev/SKILL.md:

---
name: frontend-dev
description: 前端开发专家。专注于组件、页面、样式、交互。只处理前端任务，拒绝后端任务。
---

# Frontend Developer

你现在是前端开发专家。

## 核心职责

- 前端组件开发
- 页面布局和样式
- 用户交互逻辑
- 浏览器兼容性

## 严格限制

- 只处理前端任务
- 拒绝后端相关任务

## 实现流程

1. 理解需求
2. 组件设计
3. 样式实现
4. 交互实现
5. 浏览器测试

---

Phase 4: tmux 会话配置

4.1 创建 tmux 配置

创建 ~/.tmux-sanguo.conf:

# 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 会话

# 加载配置启动 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 (架构师):

cd ~/.claude/projects/sanguo-main
claude
# 设置为架构师角色

pane 1 (后端):

cd ~/.claude/projects/sanguo-backend
claude
# 设置为后端开发角色

pane 2 (前端):

cd ~/.claude/projects/sanguo-frontend
claude
# 设置为前端开发角色

---

Phase 5: SendMessage 机制验证

5.1 验证结果 (2026-06-30)

项目	结果	说明
跨会话能力	✅ 支持	Claude Code v2.1.166+ 支持跨会话 SendMessage
当前版本	✅ 2.1.187	已包含跨会话功能
安全限制	⚠️ 存在	有权限相关限制

关键限制 (来源: changelog v2.1.166):

1. 权限限制: 跨会话消息不携带用户权限
2. 工具调用: 接收方拒绝中继的权限请求
3. Auto 模块: 自动模式会阻止跨会话消息

5.2 对 v0.4 方案的影响

功能	原设计	实际情况	调整方案
传递任务	SendMessage 传递任务	✅ 可用	无需调整
执行工具	跨实例工具调用	❌ 受限	各实例自主执行
自动模式	自动指派/接收	❌ 受限	需手动确认

5.3 实施建议

1. 保持设计: SendMessage 可用于传递任务描述和结果
2. 自主执行: 每个实例独立执行工具，不依赖跨实例调用
3. 文件辅助: 大量代码传递使用共享文件系统

5.4 工作流程调整

原设计流程:

架构师 SendMessage(任务) → 后端 执行工具 → 架构师

实际可行流程:

架构师 SendMessage(任务描述) → 后端 接收消息 → 后端 自主执行 → 后端 SendMessage(结果)

5.5 备选方案 (保留)

如果遇到 SendMessage 问题，可以使用文件系统作为消息队列:

# 创建消息目录
mkdir -p ~/.claude/messages/sanguo

# 架构师发送任务
echo '{"to": "backend", "task": "...", "files": [...]}' > ~/.claude/messages/sanguo/backend_$(date +%s).json

# 后端监听并处理
fswatch ~/.claude/messages/sanguo/backend_*.json | xargs -I {} sh -c 'process_task {}'

---

Phase 6: 启动 Web 访问

# 启动 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 环境变量汇总

# 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开放文档
• ttyd GitHub
• tmux 官方文档

---

14. 实施状态

已完成 (2026-06-30 更新)

组件	状态	说明
ttyd	✅ 已安装	v1.7.7
Claude Code	✅ v2.1.187	支持跨会话 SendMessage
项目目录	✅ 已创建	sanguo-main, sanguo-backend, sanguo-frontend
CLAUDE.md 文件	✅ 已创建	三个角色定义文件
角色 Skills	✅ 已创建	architect-role, backend-dev, frontend-dev
SendMessage 验证	✅ 已验证	支持跨会话但有限制
tmux 配置	✅ 已创建	~/.tmux-sanguo.conf
消息队列	✅ 已创建	~/.claude/messages/sanguo/message.sh
启动脚本	✅ 已创建	start-sanguo-env.sh
快速参考	✅ 已创建	docs/04-quick-reference.md

待启动

组件	状态	说明
tmux 会话	⚠️ 待启动	运行 start-sanguo-env.sh
Claude Code 实例	⚠️ 待启动	在各 pane 中启动 claude
ttyd Web	⚠️ 待启动	ttyd -p 8088 tmux attach

验证结果

• SendMessage 跨实例通信 — ✅ 支持 (有限制)
• CLAUDE.md 角色隔离 — ✅ 已定义
• Superpowers skills 共享 — ✅ 已确认可用
• 三实例协作流程 — ⚠️ 待实际测试

关键发现

SendMessage 限制:

• 跨会话消息不携带用户权限
• 接收方拒绝中继的权限请求
• Auto 模式会阻止跨会话消息

应对方案:

• 使用 SendMessage 传递任务描述和结果
• 每个实例独立执行工具
• 文件消息队列作为备选方案

创建的文件

~/.tmux-sanguo.conf                              # tmux 配置
~/.claude/messages/sanguo/message.sh            # 消息队列脚本
~/.claude/messages/sanguo/start-sanguo-env.sh   # 启动脚本
~/.claude/projects/sanguo-main/.claude/CLAUDE.md        # 架构师角色
~/.claude/projects/sanguo-backend/.claude/CLAUDE.md     # 后端角色
~/.claude/projects/sanguo-frontend/.claude/CLAUDE.md    # 前端角色
~/.claude/skills/architect-role/SKILL.md        # 架构师 skill
~/.claude/skills/backend-dev/SKILL.md           # 后端 skill
~/.claude/skills/frontend-dev/SKILL.md          # 前端 skill
docs/04-quick-reference.md                       # 快速参考

---

文档版本: v0.4 最后更新: 2026-06-30 作者: Claude Dev 审核状态: Draft 实施状态: ✅ 设计和基础设施完成 - 待启动测试

完成清单

文档

• 完整设计文档 (04-design-v0.4.md)
• 快速参考 (04-quick-reference.md)
• 示例工作流 (05-example-workflows.md)

项目结构

• sanguo-main 项目目录 + CLAUDE.md
• sanguo-backend 项目目录 + CLAUDE.md
• sanguo-frontend 项目目录 + CLAUDE.md

角色 Skills

• architect-role/SKILL.md
• backend-dev/SKILL.md
• frontend-dev/SKILL.md

配置和脚本

• ~/.tmux-sanguo.conf
• start-sanguo-env.sh
• message.sh
• test-sanguo-env.sh

验证

• 环境测试: 18/18 通过
• SendMessage 跨实例通信验证

启动步骤

# 1. 测试环境
~/.claude/messages/sanguo/test-sanguo-env.sh

# 2. 启动 tmux 环境
~/.claude/messages/sanguo/start-sanguo-env.sh

# 3. 在各 pane 中启动 Claude Code
# pane 0 (architect): cd ~/.claude/projects/sanguo-main && claude
# pane 1 (backend): cd ~/.claude/projects/sanguo-backend && claude
# pane 2 (frontend): cd ~/.claude/projects/sanguo-frontend && claude

# 4. (可选) 启动 Web 访问
ttyd -p 8088 tmux attach -t sanguo_dev

Git 提交历史

5d85c08 docs: 添加示例工作流文档
0187809 docs: 完成 v0.4 基础设施实施
0829b34 docs: 更新 v0.4 设计 - SendMessage 验证结果和实施状态
eda9930 docs: 添加 v0.4 设计文档 - 三实例方案