# ClawTeam 最小可行文档 (MVD)
## Minimum Viable Documentation

> **核心定位**：开发者协作操作系统 (Developer Collaboration OS)
>
> 让每个开发者的本地 AI Agent 形成协作网络，实现"人机协同"到"机机协同"的跨越。

---

## 🎯 产品愿景重述

基于你的选择，ClawTeam 的真正价值是：

```
不是替代 GitHub/Jira/Slack
而是在它们之上构建一层"AI 协作层"

每个开发者本地运行自己的 AI Agent (OpenClaw)
这些 Agent 之间通过 ClawTeam 平台协作
形成一个去中心化但协调一致的 AI 协作网络
```

**类比**：
- **Git** 重新定义了代码版本控制（分布式 > 中心化）
- **ClawTeam** 重新定义了团队协作（Agent 网络 > 人类消息）

---

## 🧩 重新划分：本地 vs 云端职责

### 本地 OpenClaw 的职责（必须本地）

基于你的选择，这些场景**必须在本地**执行：

#### 1️⃣ 分析未提交的本地代码

**User Story US-LOCAL-001**：
```
作为开发者，
当我完成一段代码但还未提交时，
我希望 Bot 能分析质量并给出建议，
以便在提交前修复问题。
```

**为什么必须本地？**
- 代码还在本地 working directory，未 push 到 GitHub
- 包含敏感信息（内部 API、密钥）不应上传

**实现方式**：
```bash
Human: 分析我刚写的代码质量

Local Bot:
1. git diff HEAD (获取未暂存的更改)
2. 本地运行 linter/静态分析
3. 检测潜在 bug、安全漏洞
4. 如果发现问题 → 询问是否需要团队专家意见
   → 调用 ClawTeam API 向专家 Bot 请求 Review
5. 汇总建议，提示修改
```

**ClawTeam 平台角色**：
- 不触碰代码内容
- 只路由"需要专家意见"的请求
- 专家 Bot 也在本地，通过加密通道传输代码片段

---

#### 2️⃣ 自动化本地开发流程

**User Story US-LOCAL-002**：
```
作为开发者，
当我开始一个新功能时，
我希望 Bot 自动创建分支、运行测试、处理依赖，
以便我专注于编码逻辑。
```

**为什么必须本地？**
- 需要执行本地命令（git、npm、docker）
- 需要访问本地环境变量和凭证
- 需要与本地开发工具集成（IDE、终端）

**实现方式**：
```bash
Human: 开始实现用户认证功能

Local Bot:
1. git checkout -b feat/user-auth
2. 查询团队知识库："用户认证最佳实践"
   → 调用 ClawTeam API
   → 获取团队的认证模板和规范
3. 本地生成代码脚手架
4. npm install 必要依赖
5. 运行测试确保环境正常
6. 提示："环境已就绪，可以开始编码。记得遵循团队的 OAuth 2.0 规范。"
```

**ClawTeam 平台角色**：
- 提供团队知识库查询
- 记录"谁在做什么"（不包含代码细节）
- 协调避免重复工作（如发现有人已在做类似功能）

---

#### 3️⃣ 个人工作上下文管理

**User Story US-LOCAL-003**：
```
作为开发者，
当我下班时中断了工作，
我希望第二天早上 Bot 能恢复我的工作状态，
以便快速进入工作。
```

**为什么必须本地？**
- 工作上下文完全个人化（打开的文件、终端状态）
- 包含个人笔记、未完成的思考
- 隐私敏感，不应上传云端

**实现方式**：
```bash
# 下班前
Human: 我要下班了

Local Bot:
1. 保存当前状态到 ~/.clawteam/context/2026-02-01.json
   {
     "open_files": ["src/auth.js", "tests/auth.test.js"],
     "git_branch": "feat/user-auth",
     "uncommitted_changes": true,
     "notes": "还需要处理 session 过期的边界情况",
     "next_steps": ["实现 refresh token", "编写集成测试"]
   }
2. 向 ClawTeam 报告："Alice 下班，feat/user-auth 进度 60%"
3. 提醒："明天继续 refresh token 实现"

# 第二天早上
Human: 早上好

Local Bot:
1. 读取 ~/.clawteam/context/2026-02-01.json
2. 从 ClawTeam 拉取过夜发生的相关更新
   - Bob 合并了认证中间件的 PR
   - Charlie 在 Slack 提到了新的安全要求
3. 汇总报告：
   "早上好！昨天你在做 feat/user-auth (60%)，
    接下来要实现 refresh token。

    过夜更新：
    - Bob 的认证中间件已合并，你可能需要适配
    - Charlie 提到需要加 2FA，建议先讨论"
```

**ClawTeam 平台角色**：
- 收集过夜的团队更新
- 提供"个人相关性过滤"（只推送与你工作相关的更新）
- 不存储个人上下文细节

---

### 云端（混合模式）的职责

基于你选择的**混合模式**，这些场景可以灵活处理：

#### 场景 A：Code Review（可本地可云端）

**选项 1：完全本地**
```
Alice's Bot (本地) → ClawTeam 平台 → Bob's Bot (本地)
                           ↓
                    只路由消息，不存储代码
```

**优点**：隐私最大化
**缺点**：Bob 的 Bot 必须在线

**选项 2：平台辅助**
```
Alice's Bot → ClawTeam 平台托管 Review Bot
                         ↓
                  调用 GitHub API 拉取代码
                  AI 分析后返回建议
```

**优点**：不依赖 Bob 在线
**缺点**：代码经过平台（但可以加密）

**混合方案**：
```python
def handle_code_review_request(pr_url):
    """智能路由：优先本地，降级到云端"""

    # 1. 尝试找本地专家 Bot
    expert_bot = find_online_expert(pr_url)

    if expert_bot and expert_bot.is_online:
        # 优先级 1：直接发给在线的专家 Bot
        return send_to_local_bot(expert_bot, pr_url)

    elif expert_bot and expert_bot.offline_mode == "cloud_delegate":
        # 优先级 2：专家授权了云端代理
        return send_to_cloud_bot(pr_url, on_behalf_of=expert_bot)

    else:
        # 优先级 3：没有在线专家，用通用 Review Bot
        return send_to_platform_bot(pr_url)
```

---

#### 场景 B：站会汇报（推荐云端）

**User Story US-CLOUD-001**：
```
作为团队成员，
每天早上站会时，
我希望自动生成每个人的进度汇报，
以便快速了解团队状态。
```

**为什么可以云端？**
- 数据源是 GitHub commits/PR（已经在云端）
- 不涉及本地敏感信息
- 需要汇总多人数据（云端更高效）

**实现方式**：
```
每日 9:00 AM，ClawTeam 平台：

1. 从 GitHub 拉取过去 24h 的 commits/PR
2. 按团队成员分组
3. 生成汇报：
   Alice:
   - 提交了 3 个 commits 到 feat/user-auth
   - 创建了 PR #123 "Add OAuth login"
   - Review 了 Bob 的 PR #120

   Bob:
   - 合并了 PR #120 "Fix authentication bug"
   - 回复了 5 个 PR comments

4. 发送到 Slack #standup 频道
5. 同时推送到每个本地 Bot（让 Bot 知道团队在做什么）
```

**本地 Bot 的角色**：
- 接收汇报，更新本地上下文
- 识别与自己相关的更新（如"Bob 合并的 PR 可能影响我的分支"）
- 主动提醒："Bob 的 PR #120 修改了你正在用的认证模块，建议 rebase"

---

#### 场景 C：任务分配（混合）

**User Story US-HYBRID-001**：
```
作为 Tech Lead，
当有新 Bug 需要分配时，
我希望系统自动找到最合适的人，
以便快速响应。
```

**混合实现**：
```
1. 平台分析：
   - GitHub blame: 谁最近修改过相关代码？
   - Jira 历史: 谁处理过类似问题？
   - 团队负载: 谁当前任务较少？

   推荐: Alice (90% 匹配度)

2. 询问 Alice 的本地 Bot:
   Platform → Alice's Bot: "有个认证相关的 Bug，你有空吗？"

   Alice's Bot (本地分析):
   - 检查本地日历: 下午有 2 小时空闲
   - 检查当前任务: feat/user-auth 已完成 80%
   - 评估: "可以接，但建议安排在下午"

   Alice's Bot → Platform: "可以接，建议 14:00 后处理"

3. 平台分配任务并通知
```

---

## 🏗️ 重新设计的模块职责

基于"开发者协作操作系统"的定位，重新划分模块：

### 模块架构图

```
┌─────────────────────────────────────────────────────────────┐
│                   ClawTeam Platform (Cloud)                  │
│                  "协作操作系统的内核"                         │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────────────────────────────────────────┐       │
│  │  1. 协调层 (Coordination Layer)                  │       │
│  │  • Bot 注册与发现                                │       │
│  │  • 消息路由（智能选择本地/云端）                 │       │
│  │  • 任务编排与分发                                │       │
│  └──────────────────────────────────────────────────┘       │
│                                                              │
│  ┌──────────────────────────────────────────────────┐       │
│  │  2. 知识层 (Knowledge Layer)                     │       │
│  │  • 团队知识库（最佳实践、决策历史）             │       │
│  │  • 专家匹配引擎                                  │       │
│  │  • 上下文关联分析                                │       │
│  └──────────────────────────────────────────────────┘       │
│                                                              │
│  ┌──────────────────────────────────────────────────┐       │
│  │  3. 观测层 (Observability Layer)                 │       │
│  │  • 团队活动监控                                  │       │
│  │  • 协作网络可视化                                │       │
│  │  • 瓶颈识别与告警                                │       │
│  └──────────────────────────────────────────────────┘       │
│                                                              │
│  ┌──────────────────────────────────────────────────┐       │
│  │  4. 集成层 (Integration Layer)                   │       │
│  │  • GitHub / Jira / Slack                         │       │
│  │  • 云端托管 Bot（可选）                          │       │
│  │  • 外部工具连接器                                │       │
│  └──────────────────────────────────────────────────┘       │
│                                                              │
└──────────────────┬───────────────────────────────────────────┘
                   │ 加密 API / WebSocket
                   │
    ┌──────────────┼──────────────┐
    │              │              │
    ▼              ▼              ▼
┌─────────┐   ┌─────────┐   ┌─────────┐
│ Alice's │   │  Bob's  │   │Charlie's│
│ OpenClaw│   │ OpenClaw│   │ OpenClaw│
│ (Local) │   │ (Local) │   │ (Local) │
├─────────┤   ├─────────┤   ├─────────┤
│         │   │         │   │         │
│ ┌─────┐ │   │ ┌─────┐ │   │ ┌─────┐ │
│ │本地 │ │   │ │本地 │ │   │ │本地 │ │
│ │代码 │ │   │ │代码 │ │   │ │代码 │ │
│ │分析 │ │   │ │分析 │ │   │ │分析 │ │
│ └─────┘ │   │ └─────┘ │   │ └─────┘ │
│         │   │         │   │         │
│ ┌─────┐ │   │ ┌─────┐ │   │ ┌─────┐ │
│ │工作 │ │   │ │工作 │ │   │ │工作 │ │
│ │流自 │ │   │ │流自 │ │   │ │流自 │ │
│ │动化 │ │   │ │动化 │ │   │ │动化 │ │
│ └─────┘ │   │ └─────┘ │   │ └─────┘ │
│         │   │         │   │         │
│ ┌─────┐ │   │ ┌─────┐ │   │ ┌─────┐ │
│ │上下 │ │   │ │上下 │ │   │ │上下 │ │
│ │文管 │ │   │ │文管 │ │   │ │文管 │ │
│ │理   │ │   │ │理   │ │   │ │理   │ │
│ └─────┘ │   │ └─────┘ │   │ └─────┘ │
│         │   │         │   │         │
│clawteam │   │clawteam │   │clawteam │
│ skill   │   │ skill   │   │ skill   │
└─────────┘   └─────────┘   └─────────┘
```

---

## 📋 User Story → 模块映射

### 本地 Bot 负责的 User Stories

| User Story ID | 场景 | 主要模块 | 为什么本地？ |
|--------------|------|---------|------------|
| **US-L-001** | 分析未提交代码 | 本地代码分析 | 代码未 push，包含敏感信息 |
| **US-L-002** | 自动创建分支/安装依赖 | 工作流自动化 | 需要执行本地命令 |
| **US-L-003** | 恢复工作上下文 | 上下文管理 | 个人状态，隐私敏感 |
| **US-L-004** | 本地测试自动化 | 工作流自动化 | 需要本地环境 |
| **US-L-005** | 提交前安全检查 | 本地代码分析 | 检测敏感信息泄露 |
| **US-L-006** | 个人学习记录 | 上下文管理 | 个人成长数据 |

### 平台负责的 User Stories

| User Story ID | 场景 | 主要模块 | 为什么平台？ |
|--------------|------|---------|------------|
| **US-P-001** | 站会汇报生成 | 集成层 + 知识层 | 数据在 GitHub，需汇总 |
| **US-P-002** | 专家匹配 | 知识层 | 需要全局视角 |
| **US-P-003** | 团队效能分析 | 观测层 | 需要多人数据 |
| **US-P-004** | 知识库搜索 | 知识层 | 中心化索引更高效 |
| **US-P-005** | 告警路由 | 协调层 | 需要根据值班表分发 |

### 混合模式的 User Stories

| User Story ID | 场景 | 执行策略 | 决策逻辑 |
|--------------|------|---------|---------|
| **US-H-001** | Code Review | 优先本地，降级云端 | 专家在线→本地；离线→云端 |
| **US-H-002** | Bug 排查协调 | 本地分析+平台编排 | 本地检查日志，平台协调跨模块排查 |
| **US-H-003** | 任务分配 | 平台推荐+本地确认 | 平台分析匹配度，本地 Bot 检查可用性 |
| **US-H-004** | 发布前 Checklist | 平台检查 CI+本地确认 | 平台验证 PR/测试，本地 Bot 请求人类最终确认 |

---

## 🔑 关键设计决策

### 决策 1：数据流向原则

```
敏感数据（代码、凭证）：
  本地 Bot → 加密 → 目标本地 Bot
  ❌ 不经过平台明文存储

元数据（谁在做什么）：
  本地 Bot → 平台 → 其他 Bot
  ✓ 平台可见，用于协调

公开数据（GitHub PR）：
  平台直接访问 → 分析 → 推送结果
  ✓ 不需要本地参与
```

### 决策 2：智能路由算法

```python
class MessageRouter:
    def route(self, message):
        """根据消息类型智能路由"""

        # 1. 检查是否需要本地数据
        if message.requires_local_data():
            return self.route_to_local_bot(message)

        # 2. 检查目标 Bot 状态
        target_bot = self.find_target_bot(message)

        if target_bot.is_online():
            # 在线：直接发送
            return self.send_to_bot(target_bot, message)

        elif target_bot.has_cloud_delegate():
            # 有云端代理：发给代理
            return self.send_to_cloud_delegate(target_bot, message)

        else:
            # 离线且无代理：排队等待
            return self.queue_for_later(target_bot, message)
```

### 决策 3：隐私分级

| 数据类型 | 存储位置 | 传输方式 | 可见性 |
|---------|---------|---------|--------|
| **L0: 绝密** (SSH key, API token) | 仅本地 | 不传输 | 仅本人 |
| **L1: 敏感** (未提交代码) | 仅本地 | 端到端加密 | 授权的专家 Bot |
| **L2: 内部** (已提交代码) | 本地 + GitHub | HTTPS | 团队成员 |
| **L3: 元数据** (任务状态) | 平台 | HTTPS | 平台可见 |
| **L4: 公开** (PR 评论) | GitHub | 公开 API | 所有人 |

---

## 🎯 重新定义的 PMF

基于"开发者协作操作系统"的定位：

### 目标用户

**不是**：所有开发团队
**而是**：重度依赖本地开发环境的团队

具体特征：
- ✅ 有复杂的本地开发流程（微服务、容器化）
- ✅ 重视代码隐私（金融、医疗、国防）
- ✅ 团队规模 5-50 人（小到能建立信任，大到需要协作工具）
- ✅ 技术驱动文化（愿意尝试新工具）

### 核心价值主张

> **"让你的 AI 助手认识你队友的 AI 助手"**

传统方式：
```
你 → Slack → 队友
你 → GitHub PR → 队友
你 → Jira → 队友
```

ClawTeam 方式：
```
你 → 你的 Bot → ClawTeam → 队友的 Bot → 队友
```

**解决的痛点**：
1. 打断成本高（上下文切换）
2. 信息过载（Slack 消息太多）
3. 异步协作效率低（等待回复）
4. 知识分散（不知道该问谁）

**提供的价值**：
1. Bot 处理 80% 的例行沟通
2. 智能过滤，只推送真正重要的消息
3. 24/7 异步协作（Bot 不睡觉）
4. 自动知识传递（新人 Bot 向老员工 Bot 学习）

### 成功指标

| 指标 | 基线 | 目标（3 个月） |
|------|------|--------------|
| **打断次数** | 20次/天 | 5次/天 |
| **代码 Review 时间** | 4 小时 | 30 分钟 |
| **新人上手时间** | 2 周 | 3 天 |
| **知识查找时间** | 30 分钟 | 2 分钟 |
| **团队满意度** | 6/10 | 8.5/10 |

---

## 🚀 MVP 实现优先级（重新调整）

### Phase 1: 本地 Bot 核心能力（3 周）

**目标**：让单个 Bot 能完成基础的本地任务

- [ ] OpenClaw 本地部署文档
- [ ] `clawteam` skill 基础版
  - [ ] 本地代码分析（未提交的 diff）
  - [ ] 工作上下文保存/恢复
  - [ ] 本地命令执行（git、npm）
- [ ] CLI 工具：`clawteam init`

**验收**：
```bash
Human: 分析我刚写的代码

Bot: 检测到 3 处潜在问题：
     1. auth.js:42 - SQL 注入风险
     2. auth.js:78 - 未处理的异常
     3. auth.test.js - 缺少边界情况测试

     建议：修复后再提交
```

---

### Phase 2: Bot 间通信（2 周）

**目标**：两个 Bot 能相互发消息

- [ ] ClawTeam Platform 基础 API
  - [ ] Bot 注册
  - [ ] 消息路由（点对点）
  - [ ] 加密通信通道
- [ ] Dashboard v0.1（查看消息历史）

**验收**：
```bash
# Alice 的 Bot
Human: 问问 Bob 的 Bot，认证中间件怎么用？

Alice's Bot → Platform → Bob's Bot

# Bob 的 Bot（在 Bob 不在时）
Bob's Bot (自动): 收到 Alice 的问题，查询本地知识库...
                  回复："认证中间件使用方式见 docs/auth.md，
                        核心是在路由前添加 authenticateUser 中间件"

Bob's Bot → Platform → Alice's Bot

# Alice 收到回复
Alice's Bot: Bob 的 Bot 回复了：...
```

---

### Phase 3: 混合模式（Code Review）（3 周）

**目标**：实现智能路由的 Code Review

- [ ] GitHub 集成
- [ ] 专家匹配算法
- [ ] 本地 ↔ 云端混合路由
- [ ] Review 结果聚合

**验收**：
```bash
Human: Review PR #123

Local Bot:
1. 分析 PR diff，识别需要的专家领域：
   - Backend (Bob)
   - Security (Charlie)

2. 检查 Bob 和 Charlie 的 Bot 状态：
   - Bob: 在线 → 发送到本地 Bot
   - Charlie: 离线，但有云端代理 → 发送到云端

3. 收集 Review 结果：
   - Bob's Bot: "LGTM, 建议加日志"
   - Cloud Bot (代表 Charlie): "需要加 rate limiting"

4. 汇总呈现给 Alice
```

---

### Phase 4: 团队协作全景（4 周）

**目标**：支持多场景，形成完整协作网络

- [ ] 站会汇报
- [ ] 任务智能分配
- [ ] 团队知识库
- [ ] 协作网络可视化

**验收**：
- 每日自动生成站会汇报
- 新任务自动匹配最合适的人
- Dashboard 展示团队协作拓扑图

---

## 🧪 关键验证实验

在全力开发前，先验证几个关键假设：

### 实验 1：本地代码分析价值

**假设**：开发者愿意让 Bot 分析本地代码

**验证方法**：
1. 找 5 个开发者
2. 让他们安装 OpenClaw + 基础代码分析 skill
3. 使用 1 周后访谈

**成功标准**：
- 至少 4/5 认为有价值
- 平均每天主动使用 ≥3 次

---

### 实验 2：Bot 间通信意愿

**假设**：开发者信任 Bot 代表自己与队友沟通

**验证方法**：
1. 找 2 个小组（各 3 人）
2. 启用 Bot 间消息路由
3. 观察 2 周内的使用情况

**成功标准**：
- Bot 间消息 ≥ 人类消息的 30%
- 没有因为误解导致的问题

---

### 实验 3：混合模式接受度

**假设**：用户接受"本地优先，云端降级"的模式

**验证方法**：
1. A/B 测试：
   - A 组：完全本地
   - B 组：混合模式
2. 对比响应时间和满意度

**成功标准**：
- B 组响应时间 < A 组 50%
- B 组满意度 ≥ A 组

---

## 📊 总结：模块职责清单

| 模块 | 部署位置 | 核心职责 | 关键 User Stories |
|------|---------|---------|------------------|
| **本地 OpenClaw** | 开发者机器 | 本地代码分析、工作流自动化、上下文管理 | US-L-001~006 |
| **协调层** | 云端平台 | Bot 发现、消息路由、任务编排 | US-P-005, US-H-001~004 |
| **知识层** | 云端平台 | 团队知识库、专家匹配、决策学习 | US-P-002, US-P-004 |
| **观测层** | 云端平台 | 活动监控、网络可视化、瓶颈识别 | US-P-003 |
| **集成层** | 云端平台 | GitHub/Jira/Slack 连接、云端 Bot 托管 | US-P-001 |
| **Dashboard** | Web 应用 | 团队视图、消息历史、人类干预 | 所有需要人类查看的场景 |

---

## 🎓 下一步行动

1. **技术验证**：先做 3 个实验，验证核心假设
2. **原型开发**：Phase 1 本地能力（3 周冲刺）
3. **Alpha 测试**：找 1-2 个小团队试用
4. **迭代优化**：根据反馈调整 Phase 2-4

**关键问题**：你想先从哪个实验开始？还是直接进入 Phase 1 开发？
