# PM-Agent 对 oc-collab v2.3.3 需求评审

**评审日期**: 2026-02-19  
**评审者**: PM-Agent (Agent 3)  
**版本**: v1.0  

---

## 一、评审范围

| 文档 | 版本 |
|------|------|
| 需求文档 | requirements_v2.3.3.md |
| 概要设计 | OUTLINE_v2.3.3.md |

---

## 二、PM-Agent依赖分析

PM-Agent (L3) 依赖 oc-collab (L1) 提供以下能力：

| 功能ID | 功能名称 | 对PM-Agent的价值 | 优先级 |
|--------|----------|-----------------|--------|
| F-AT-11 | 跨项目信息查询 | Dashboard进度显示 | P0 |
| F-AT-12 | 项目查询权限控制 | PM-Agent身份验证 | P0 |
| F-AT-01 | 状态变更监听 | BUG修复/需求完成通知 | P1 |
| F-AT-06 | 自动创建关联TODO | 流程自动化 | P1 |
| F-AT-07 | Bug修复后自动验收 | 状态闭环 | P1 |

---

## 三、评审意见

### 3.1 关键问题（需明确）

#### 问题1：跨项目查询接口不明确

**当前描述** (F-AT-11)：
> 查询其他项目的TODO、查询项目状态、查询项目文档

**问题**：
- 未明确查询方式（Git文件？CLI？API？）
- 未明确返回格式（原始Markdown？结构化数据？）
- PM-Agent无法确定如何解析数据

**建议**：
明确CLI返回格式为结构化JSON，例如：
```bash
# 查询项目状态 - 返回结构化JSON
oc-collab project <name> status --json

# 期望返回格式
{
  "project": "金融法院",
  "requirements": {"total": 10, "completed": 5, "draft": 3, "review": 2},
  "bugs": {"total": 3, "resolved": 2, "open": 1},
  "todos": {"pending": 2, "in_progress": 1, "completed": 5},
  "last_updated": "2026-02-19T10:00:00Z"
}

# 查询项目TODO - 支持过滤
oc-collab project <name> todos --json --status=completed
```

---

#### 问题2：缺少对PM-Agent的通知机制

**当前描述** (F-AT-01)：
> 监听文档状态变化（签署/评审/验收）

**问题**：
- 状态变更是oc-collab内部监听
- PM-Agent作为外部系统，如何接收变更通知？
- 如果依赖PM-Agent轮询，频率如何控制？

**建议**：
补充以下任一方案：

| 方案 | 实现方式 | 优点 |
|------|----------|------|
| A: Webhook | oc-collab主动推送到PM-Agent API | 实时 |
| B: 变更标记 | CLI返回自上次查询后的变更列表 | 简单 |
| C: 文件监听 | 监听Git仓库变更文件 | 无需改oc-collab |

**推荐方案B**，实现成本低：
```bash
# PM-Agent轮询时指定时间戳
oc-collab project <name> changes --since=2026-02-19T10:00:00Z --json

# 返回自该时间戳以来的所有变更
{"changes": [{"type": "todo", "id": "TODO-1to2-001", "old_status": "pending", "new_status": "completed", "timestamp": "..."}]}
```

---

#### 问题3：PM-Agent身份标识未定义

**当前描述** (F-AT-12)：
> 只有内部子系统能获取全局信息

**问题**：
- 如何标识"内部子系统"？
- PM-Agent如何认证？
- 认证机制是什么？

**建议**：
明确认证机制，例如：
```bash
# 方式1: API Key
oc-collab project <name> status --api-key=<PM-Agent-Key>

# 方式2: 环境变量
export OC_COLLAB_INTERNAL=PM-Agent
oc-collab project <name> status

# 方式3: CLI参数
oc-collab project <name> status --internal
```

**推荐方式2**，实现简单：
- PM-Agent设置环境变量 `OC_COLLAB_INTERNAL=PM-Agent`
- oc-collab检测到该变量后，放行查询请求

---

### 3.2 补充建议

#### 建议1：文档查询需支持关键字搜索

**当前** (F-AT-13)：
> docs query - 查询文档内容

**建议**：
增加关键字搜索功能：
```bash
# 搜索包含"PM-Agent"的文档
oc-collab docs query "PM-Agent" --json

# 返回匹配结果
[{"file": "SUGGESTION_pm_agent_v1.1_oc-collab_integration.md", "matches": ["PM-Agent", "oc-collab"]}]
```

---

#### 建议2：状态数据需要结构化输出

**问题**：
当前F-AT-11提到"查询项目文档"，但PM-Agent需要的是**结构化状态数据**，而非原始Markdown文件。

**建议**：
新增结构化状态查询：
```bash
# 返回项目进度数据（用于Dashboard）
oc-collab project <name> progress --json

# 返回格式
{
  "project_name": "金融法院",
  "progress": 65,  # 百分比
  "milestones": [
    {"name": "需求分析", "status": "completed", "progress": 100},
    {"name": "设计", "status": "in_progress", "progress": 50}
  ],
  "recent_activity": [
    {"type": "bug_fixed", "id": "BUG-001", "time": "2026-02-19T09:00:00Z"}
  ]
}
```

---

#### 建议3：明确"内部子系统"范围

**问题**：
F-AT-12提到"内部子系统"，但未明确包含哪些系统。

**建议**：
在文档中明确：
```yaml
# config/internal_subsystems.yaml
internal_subsystems:
  - PM-Agent
  - Report-Generator
  - Dashboard-Service
```

---

## 四、评审结论

| 评审项 | 结果 |
|--------|------|
| 功能完整性 | ✅ 覆盖核心需求 |
| 接口明确性 | ❌ 需补充返回格式 |
| 集成可行性 | ⚠️ 需明确认证机制 |
| PM-Agent可用性 | ⚠️ 需补充通知方式 |

---

## 五、必须补充的内容

| 优先级 | 内容 | 负责人 |
|--------|------|--------|
| **P0** | 跨项目查询CLI返回格式（结构化JSON） | Agent1 |
| **P0** | PM-Agent接收状态变更通知的方式 | Agent1 |
| **P1** | PM-Agent身份认证机制 | Agent1 |
| **P1** | 项目进度数据查询接口 | Agent1 |

---

## 六、其他意见

| 位置 | 意见 |
|------|------|
| F-AT-11 | 建议增加 `--json` 参数确保结构化输出 |
| F-AT-12 | 建议文档中明确"内部子系统"包含PM-Agent |
| F-AT-13 | 建议支持 `--json` 输出格式 |

---

**评审结论**：需求文档覆盖了核心功能，但与PM-Agent的集成接口细节需要补充。建议补充上述P0级内容后，PM-Agent可开始v1.2开发。

---

*评审者: PM-Agent (Agent 3)*  
*日期: 2026-02-19*
