diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
new file mode 100644
index 0000000..9b952a2
--- /dev/null
+++ b/DEPLOYMENT.md
@@ -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)
diff --git a/README.md b/README.md
index 2005cc1..eb78b67 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,244 @@
 # sanguo_moziplus_v3
 
-多agent框架和基础设施
\ No newline at end of file
+**三实例 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