sanguo/sanguo_moziplus_v3
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 完成 v0.4 所有文档

Browse Source 
新增:
- DEPLOYMENT.md - 完整部署指南
- README.md - 项目说明和快速开始

更新内容:
- 部署步骤详解
- tmux 操作指南
- Web 访问配置
- 故障排查指南
- 高级配置选项
- 生产部署方案 (systemd/launchd)
- 安全注意事项

v0.4 完整交付:
✅ 设计文档 (04-design-v0.4.md)
✅ 快速参考 (04-quick-reference.md)
✅ 示例工作流 (05-example-workflows.md)
✅ 部署指南 (DEPLOYMENT.md)
✅ 项目说明 (README.md)
✅ 三实例项目结构
✅ 角色 Skills
✅ 系统脚本 (tmux/启动/消息/测试)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Dev
2026-06-30 22:40:38 +08:00
parent a8ac23f699
commit ddccd8fbfa
2 changed files with 585 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DEPLOYMENT.md
+343
View File
@@ -0,0 +1,343 @@
# sanguo_moziplus_v3 v0.4 部署指南
## 快速开始
### 1. 一键启动
```bash
# 启动三实例 tmux 环境
~/.claude/messages/sanguo/start-sanguo-env.sh
# 在各 pane 中分别执行:
# pane 0: cd ~/.claude/projects/sanguo-main && claude
# pane 1: cd ~/.claude/projects/sanguo-backend && claude
# pane 2: cd ~/.claude/projects/sanguo-frontend && claude
```
### 2. Web 访问 (可选)
```bash
# 启动 Web 终端 (在另一个终端)
ttyd -p 8088 tmux attach -t sanguo_dev
# 访问: http://YOUR_LAN_IP:8088
```
## 详细步骤
### 步骤 1: 验证环境
```bash
~/.claude/messages/sanguo/test-sanguo-env.sh
```
预期输出:
```
=== sanguo 环境测试 ===
✅ 18/18 测试通过
```
### 步骤 2: 启动 tmux 会话
```bash
~/.claude/messages/sanguo/start-sanguo-env.sh
```
这将创建:
- pane 0: architect (架构师)
- pane 1: backend (后端开发)
- pane 2: frontend (前端开发)
### 步骤 3: 启动 Claude Code 实例
**在 pane 0 (architect)**:
```bash
cd ~/.claude/projects/sanguo-main
claude
```
**在 pane 1 (backend)**:
```bash
cd ~/.claude/projects/sanguo-backend
claude
```
**在 pane 2 (frontend)**:
```bash
cd ~/.claude/projects/sanguo-frontend
claude
```
### 步骤 4: 验证角色加载
在每个实例中，确认 CLAUDE.md 角色定义已加载:
```bash
# 在 Claude Code 中输入
角色定义
```
应该看到对应角色的描述。
### 步骤 5: 测试 SendMessage
**在 architect (pane 0)**:
```javascript
SendMessage({
to: "backend",
summary: "测试消息",
message: "这是一条测试消息，请确认收到。"
})
```
**在 backend (pane 1)**:
应该收到通知并显示消息内容。
**在 backend (pane 1) 回复**:
```javascript
SendMessage({
to: "main",
summary: "收到测试",
message: "已收到测试消息，backend 实例正常运行。"
})
```
## tmux 操作指南
### 快捷键
| 快捷键 | 功能 |
|--------|------|
| `Ctrl+B 0` | 切换到 pane 0 (architect) |
| `Ctrl+B 1` | 切换到 pane 1 (backend) |
| `Ctrl+B 2` | 切换到 pane 2 (frontend) |
| `Ctrl+B o` | 在 pane 间循环切换 |
| `Ctrl+B 方向键` | 切换到指定方向 pane |
| `Ctrl+B d` | 分离会话 (detach) |
| `Ctrl+B $` | 重命名当前窗口 |
### 会话管理
```bash
# 查看所有会话
tmux ls
# 附加到会话
tmux attach-session -t sanguo_dev
# 杀死会话
tmux kill-session -t sanguo_dev
```
## Web 访问配置
### 启动 ttyd
```bash
# 启动 Web 终端
ttyd -p 8088 tmux attach -t sanguo_dev
# 后台运行
nohup ttyd -p 8088 tmux attach -t sanguo_dev > /tmp/ttyd.log 2>&1 &
```
### 查看本机 IP
```bash
# macOS
ifconfig | grep "inet " | grep -v 127.0.0.1
# Linux
ip addr show | grep "inet " | grep -v 127.0.0.1
```
### 访问地址
```
http://YOUR_LAN_IP:8088
```
### 停止 ttyd
```bash
# 查找进程
ps aux | grep ttyd
# 杀死进程
kill <PID>
```
## 故障排查
### 问题 1: tmux 会话已存在
```bash
# 附加到现有会话
tmux attach-session -t sanguo_dev
# 或删除后重建
tmux kill-session -t sanguo_dev
~/.claude/messages/sanguo/start-sanguo-env.sh
```
### 问题 2: SendMessage 不工作
**检查**:
1. 确认各实例都在运行
2. 确认实例名称正确 (main, backend, frontend)
3. 查看 Claude Code 版本 (需要 v2.1.166+)
**备选方案**: 使用文件消息队列
```bash
# 发送消息
~/.claude/messages/sanguo/message.sh send backend "任务内容"
# 读取消息
~/.claude/messages/sanguo/message.sh read
```
### 问题 3: 角色定义未生效
**检查**:
```bash
# 确认 CLAUDE.md 存在
ls -la ~/.claude/projects/sanguo-*/.claude/CLAUDE.md
# 查看内容
cat ~/.claude/projects/sanguo-main/.claude/CLAUDE.md
```
**解决**: 重新启动 Claude Code
### 问题 4: 端口被占用
```bash
# 查找占用进程
lsof -i :8088
# 更换端口
ttyd -p 8089 tmux attach -t sanguo_dev
```
## 高级配置
### 自定义 tmux 布局
编辑 `~/.tmux-sanguo.conf`:
```bash
# 调整 pane 大小
split-window -h -p 60 # 水平分割，右侧占 60%
# 调整颜色
set - pane-active-border-style "fg=brightgreen"
# 添加状态栏信息
set - status-right "%H:%M | %Y-%m-%d"
```
### 添加更多实例
编辑启动脚本，添加更多 pane:
```bash
# 在 pane 2 之后添加
tmux selectp -t 2
tmux split-window -v -p 50
tmux selectp -t 3
tmux split-window -h -p 50
```
### 环境变量配置
添加到 `~/.zshrc` 或 `~/.bashrc`:
```bash
# sanguo 环境变量
export SANGUO_SESSION="sanguo_dev"
export SANGUO_WEB_PORT="8088"
export SANGUO_PROJECTS_BASE="$HOME/.claude/projects"
# 快捷命令
alias sanguo-start="$HOME/.claude/messages/sanguo/start-sanguo-env.sh"
alias sanguo-test="$HOME/.claude/messages/sanguo/test-sanguo-env.sh"
alias sanguo-msg="$HOME/.claude/messages/sanguo/message.sh"
```
## 生产部署
### 使用 systemd (Linux)
创建 `/etc/systemd/system/sanguo.service`:
```ini
[Unit]
Description=sanguo Three-Instance Development Environment
After=network.target
[Service]
Type=forking
User=your-user
ExecStart=/usr/bin/tmux new-session -d -s sanguo_dev
ExecStartPost=/bin/sleep 2
ExecStartPost=/usr/bin/ttyd -p 8088 tmux attach -t sanguo_dev
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/tmux</string>
<string>new-session</string>
<string>-d</string>
<string>-s</string>
<string>sanguo_dev</string>
</array>
<key>RunAtLoad</key>
<true/>
</dict>
</plist>
```
加载服务:
```bash
launchctl load ~/Library/LaunchAgents/com.sanguo.dev.plist
```
## 安全注意事项
### Web 访问安全
1. **不要暴露到公网** - 仅在内网使用
2. **使用防火墙** - 限制访问来源
3. **添加认证** - ttyd 支持基本认证
```bash
# 启用基本认证
ttyd -c username:password -p 8088 tmux attach -t sanguo_dev
```
### 数据安全
1. 定期备份项目目录
2. 不要在 CLAUDE.md 中存储敏感信息
3. 使用环境变量管理 API Keys
## 相关文档
- [完整设计文档](./docs/design/04-design-v0.4.md)
- [快速参考](./docs/04-quick-reference.md)
- [示例工作流](./docs/05-example-workflows.md)
README.md
+242 -1
View File
@@ -1,3 +1,244 @@
# sanguo_moziplus_v3 # sanguo_moziplus_v3
多agent框架和基础设施 **三实例 AI 协作开发环境** - 基于 Claude Code + GLM-5.2
## 版本
**v0.4** - 设计和基础设施完成 (2026-06-30)
## 概述
sanguo_moziplus_v3 是一个多实例 AI 协作开发环境，通过三个独立的 Claude Code 实例协同工作，模拟真实开发团队中的不同角色：
```
┌─────────────────────────────────────────────┐
│ tmux sanguo_dev 会话 │
│ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ architect │ │ backend │ │ frontend │ │
│ │ 架构师 │ │ 后端开发 │ │ 前端开发 │ │
│ │ pane #0 │ │ pane #1 │ │ pane #2 │ │
│ └───────────┘ └───────────┘ └───────────┘ │
│ │
│ 共享 Superpowers Skills (~/.claude/skills/) │
│ 共享 GLM-5.2 后端 │
└─────────────────────────────────────────────┘
```
## 特性
- **三实例协作**: 架构师、后端、前端三个角色独立运行
- **角色隔离**: 通过 CLAUDE.md 定义清晰的角色边界
- **共享技能库**: 所有实例共享 Superpowers skills
- **跨实例通信**: SendMessage + 文件消息队列
- **Web 访问**: 通过 ttyd 实现浏览器访问
## 快速开始
### 1. 验证环境
```bash
~/.claude/messages/sanguo/test-sanguo-env.sh
```
### 2. 启动环境
```bash
~/.claude/messages/sanguo/start-sanguo-env.sh
```
### 3. 启动实例
在各 tmux pane 中分别执行：
```bash
# pane 0
cd ~/.claude/projects/sanguo-main && claude
# pane 1
cd ~/.claude/projects/sanguo-backend && claude
# pane 2
cd ~/.claude/projects/sanguo-frontend && claude
```
## 文档
| 文档 | 描述 |
|------|------|
| [DEPLOYMENT.md](./DEPLOYMENT.md) | 部署指南 |
| [docs/design/04-design-v0.4.md](./docs/design/04-design-v0.4.md) | 完整设计文档 |
| [docs/04-quick-reference.md](./docs/04-quick-reference.md) | 快速参考 |
| [docs/05-example-workflows.md](./docs/05-example-workflows.md) | 示例工作流 |
## 项目结构
```
sanguo_moziplus_v3/
├── DEPLOYMENT.md # 部署指南
├── README.md # 本文件
├── docs/
│ ├── design/
│ │ ├── 02-design-v0.2.md # v0.2 设计 (CCB 方案)
│ │ ├── 03-design-v0.3.md # v0.3 设计 (内置 Agent)
│ │ └── 04-design-v0.4.md # v0.4 设计 (三实例方案) ✅
│ ├── 04-quick-reference.md # 快速参考
│ └── 05-example-workflows.md # 示例工作流
│
├── ~/.claude/projects/ # 项目目录
│ ├── sanguo-main/ # 架构师项目
│ │ └── .claude/CLAUDE.md # 架构师角色定义
│ ├── sanguo-backend/ # 后端项目
│ │ └── .claude/CLAUDE.md # 后端角色定义
│ └── sanguo-frontend/ # 前端项目
│ └── .claude/CLAUDE.md # 前端角色定义
│
├── ~/.claude/skills/ # 角色 Skills
│ ├── architect-role/ # 架构师 skill
│ ├── backend-dev/ # 后端 skill
│ └── frontend-dev/ # 前端 skill
│
└── ~/.claude/messages/sanguo/ # 系统脚本
├── start-sanguo-env.sh # 启动脚本
├── message.sh # 消息队列
└── test-sanguo-env.sh # 测试脚本
```
## 角色
### architect (架构师/项目经理)
**项目**: `~/.claude/projects/sanguo-main`
**职责**:
- 需求分析和理解
- 架构设计和技术选型
- 任务拆分和优先级排序
- 代码审核和质量把关
- 最终验收和 Git 提交管理
**限制**: 绝对不亲自编写代码
### backend (后端开发)
**项目**: `~/.claude/projects/sanguo-backend`
**职责**:
- 服务端代码实现
- API 设计和实现
- 数据库设计和 Migration
- 单元测试和集成测试
**限制**: 只处理后端任务，拒绝前端任务
### frontend (前端开发)
**项目**: `~/.claude/projects/sanguo-frontend`
**职责**:
- 前端组件开发
- 页面布局和样式
- 用户交互逻辑
- 浏览器兼容性
**限制**: 只处理前端任务，拒绝后端任务
## 协作方式
### SendMessage 跨实例通信
```javascript
// architect → backend
SendMessage({
to: "backend",
summary: "实现用户 API",
message: "需要实现用户查询 API，包括..."
})
// backend → architect
SendMessage({
to: "main",
summary: "后端完成",
message: "已完成用户 API，文件包括..."
})
```
### 备选方案: 文件消息队列
```bash
# 发送消息
~/.claude/messages/sanguo/message.sh send backend "任务内容"
# 读取消息
~/.claude/messages/sanguo/message.sh read
```
## 技术栈
| 组件 | 技术/版本 |
|------|----------|
| **Claude Code** | v2.1.187+ |
| **Superpowers** | Marketplace |
| **GLM-5.2** | 智谱 AI |
| **ttyd** | v1.7.7 |
| **tmux** | v3.7 |
## 环境要求
- macOS 或 Linux
- Claude Code v2.1.166+
- tmux
- ttyd
- Bash
## 安装
### 1. 克隆仓库
```bash
git clone http://192.168.2.154:3000/sanguo/sanguo_moziplus_v3.git
cd sanguo_moziplus_v3
```
### 2. 运行测试
```bash
~/.claude/messages/sanguo/test-sanguo-env.sh
```
### 3. 启动环境
```bash
~/.claude/messages/sanguo/start-sanguo-env.sh
```
详细步骤见 [DEPLOYMENT.md](./DEPLOYMENT.md)
## 状态
**v0.4 设计和基础设施: ✅ 完成**
- ✅ 完整设计文档
- ✅ 快速参考文档
- ✅ 示例工作流文档
- ✅ 部署指南
- ✅ 三实例项目结构
- ✅ 角色 Skills
- ✅ tmux 配置
- ✅ 启动脚本
- ✅ 消息队列系统
- ✅ 环境测试脚本
**待用户操作**:
- ⏳ 启动 tmux 环境
- ⏳ 在各 pane 启动 Claude Code
- ⏳ 测试 SendMessage 协作
## 许可证
[待定]
## 联系方式
- 仓库: http://192.168.2.154:3000/sanguo/sanguo_moziplus_v3