# 需求规格说明书：PM-Agent v1.2.0

**版本**: v1.2
**创建日期**: 2026-02-19
**作者**: Agent 3 (PM Agent产品经理)
**版本号**: v1.2.0
**状态**: DRAFT

---

## 变更历史

| 版本 | 日期 | 变更 |
|------|------|------|
| v1.1.0 | 2026-02-17 | 初始版本：多模态输入、材料处理、Git发布 |
| v1.2.0 | 2026-02-19 | Git数据同步、跨项目查询、状态反馈 |
| v1.2.1 | 2026-02-19 | 新增保密项目文档隔离功能（F-027~F-030） |

---

## 一、背景

v1.1.0已完成材料处理和Git发布功能，但：
1. Dashboard进度显示为0%（无数据源）
2. 无法接收oc-collab状态反馈
3. 跨项目信息需要手动查询

v1.2.0需要实现与oc-collab的深度集成，实现数据闭环。

---

## 二、目标

| 目标 | 说明 |
|------|------|
| 进度数据获取 | 从oc-collab项目获取需求/BUG/TODO状态 |
| 动态状态反馈 | 接收oc-collab状态变更通知 |
| Dashboard完善 | 显示真实的项目进度百分比 |

---

## 三、功能需求

### F-021: Git数据同步

**需求描述**：定期从oc-collab项目仓库拉取数据

**详细说明**：
1. 克隆/同步所有关联的oc-collab项目仓库
2. 定期git pull更新数据
3. 解析项目文档获取进度

**验收标准**：
- [ ] 支持配置多个项目仓库
- [ ] 自动定期同步（可配置间隔）
- [ ] 手动触发同步
- [ ] 同步状态记录

---

### F-022: 跨项目信息查询

**需求描述**：调用oc-collab CLI查询项目状态

**详细说明**：
1. 调用`oc-collab project <name> status --json`获取项目状态
2. 调用`oc-collab project <name> todos --json`获取TODO列表
3. 调用`oc-collab project <name> progress --json`获取进度数据
4. 调用`oc-collab project <name> changes --since=<time>`获取变更

**依赖**：oc-collab v2.3.3 F-AT-11

**验收标准**：
- [ ] 支持项目状态查询
- [ ] 支持TODO列表查询
- [ ] 支持进度数据查询
- [ ] 支持变更查询（带时间戳）
- [ ] 返回结构化JSON

---

### F-023: 动态状态反馈

**需求描述**：接收oc-collab状态变更通知

**详细说明**：
1. 接收BUG修复完成通知
2. 接收需求完成通知
3. 接收TODO状态变更通知
4. 自动更新PM-Agent中的状态

**依赖**：oc-collab v2.3.3 F-AT-01

**接收方式**：
- 选项A：轮询`oc-collab project changes --since=<timestamp>`
- 选项B：Webhook接收（需oc-collab支持）

**验收标准**：
- [ ] 定时轮询状态变更
- [ ] 状态变更后自动更新
- [ ] 通知记录可追溯

---

### F-024: Dashboard进度显示

**需求描述**：显示项目真实进度

**详细说明**：
1. 从oc-collab获取需求完成情况
2. 从oc-collab获取BUG修复情况
3. 从oc-collab获取TODO完成情况
4. 计算并显示项目进度百分比

**验收标准**：
- [ ] 显示项目进度百分比
- [ ] 显示需求统计（总数/完成/进行中）
- [ ] 显示BUG统计（总数/已解决/待解决）
- [ ] 显示TODO统计（总数/完成/待处理）
- [ ] 支持多项目汇总

---

### F-025: 问题跟踪状态同步

**需求描述**：问题跟踪页面显示真实状态

**详细说明**：
1. 从oc-collab获取BUG列表和状态
2. 从oc-collab获取需求列表和状态
3. 显示问题当前状态（待处理/处理中/已完成）
4. 支持手动刷新

**验收标准**：
- [ ] 显示BUG列表和状态
- [ ] 显示需求列表和状态
- [ ] 状态与oc-collab同步
- [ ] 支持手动刷新

---

### F-026: 项目文档汇总

**需求描述**：从oc-collab项目拉取开发文档

**详细说明**：
1. 从各项目仓库拉取文档
2. 按客户/项目分类
3. 支持文档搜索
4. 支持在线预览

**验收标准**：
- [ ] 自动拉取项目文档
- [ ] 按项目分类显示
- [ ] 支持关键字搜索
- [ ] 支持文档预览

---

### F-027: 项目保密级别配置

**需求描述**：配置项目保密级别，用于控制文档同步范围

**详细说明**：
1. 项目配置增加"保密级别"字段（普通/保密）
2. 区分可同步内容vs仅本地内容

**背景**：
- 某些项目由于保密要求，文档只能留在内网
- 文档通过加密文件离线传递，不走Git同步

**验收标准**：
- [x] 支持配置项目保密级别
- [x] 保密项目标记可查询

---

### F-028: 差异化同步规则

**需求描述**：根据项目保密级别，决定同步内容范围

**详细说明**：
1. 普通项目：全量同步（代码+文档）
2. 保密项目：仅同步代码/测试/Bug，跳过文档目录

**同步范围对比**：

| 内容 | 普通项目 | 保密项目 |
|------|---------|---------|
| 代码 src/ | ✅ | ✅ |
| 测试 tests/ | ✅ | ✅ |
| Bug报告 docs/bugs/ | ✅ | ✅ |
| 需求文档 docs/01-requirements/ | ✅ | ❌ 不同步 |
| 设计文档 docs/02-design/ | ✅ | ❌ 不同步 |

**验收标准**：
- [x] 保密项目同步时跳过docs/目录
- [x] 保密项目文档不显示在Git仓库中

---

### F-029: 保密项目自动同步控制

**需求描述**：当存在活跃的保密项目时，禁止自动同步

**详细说明**：
1. 检测当前是否有活跃的保密项目
2. 如有，禁用自动同步功能
3. 手动同步时提示确认

**原因**：保密项目存在时，自动化操作可能意外同步敏感文档

**验收标准**：
- [x] 检测保密项目活跃状态
- [x] 活跃保密项目存在时禁用自动同步
- [x] 手动同步前提示确认

---

### F-030: 保密信息同步检查

**需求描述**：保密项目每次Git同步时自动检查是否有保密信息被上传

**详细说明**：
1. 同步前扫描即将推送的文件
2. 检测关键词（如"保密"、"内部"、"confidential"）
3. 发现敏感信息时阻止推送并告警

**检查规则**：
```yaml
# config/secret_check_rules.yaml
sensitive_keywords:
  - "保密"
  - "内部"
  - "confidential"
  - "secret"
  - "private"

exclude_patterns:
  - "*.md"  # 可配置是否检查文档
```

**验收标准**：
- [x] 同步前自动扫描
- [x] 发现敏感信息阻止推送
- [x] 告警并提示处理方式

---

## 四、CLI接口设计（PM-Agent调用oc-collab）

```bash
# 1. 项目状态查询
pm-agent sync project <name> status

# 2. 项目进度查询
pm-agent sync project <name> progress

# 3. 项目TODO查询
pm-agent sync project <name> todos

# 4. 变更查询
pm-agent sync project <name> changes --since=2026-02-19T10:00:00Z

# 5. 全量同步
pm-agent sync all

# 6. 定时同步配置
pm-agent config set sync_interval 3600  # 秒
```

---

## 五、数据流设计

```
oc-collab项目仓库
      │
      │ git pull / CLI查询
      ▼
PM-Agent后端
      │
      ├──→ SQLite存储
      │     ├── projects表（项目信息）
      │     ├── requirements表（需求状态）
      │     ├── bugs表（BUG状态）
      │     └── todos表（TODO状态）
      │
      ▼
前端Dashboard
      ├── 进度百分比
      ├── 需求统计
      ├── BUG统计
      └── TODO统计
```

---

## 六、依赖关系

| 功能 | 依赖 |
|------|------|
| F-022 跨项目查询 | oc-collab v2.3.3 F-AT-11 |
| F-023 状态反馈 | oc-collab v2.3.3 F-AT-01 |
| F-024 Dashboard进度 | F-022 跨项目查询 |
| F-025 问题跟踪 | F-022 跨项目查询 |
| F-026 项目文档汇总 | F-021 Git数据同步 |

---

## 七、工时预估

| 功能 | 工时 | 说明 |
|------|------|------|
| F-021 Git数据同步 | 4h | 仓库克隆/同步 |
| F-022 跨项目查询 | 3h | CLI调用封装 |
| F-023 动态状态反馈 | 4h | 轮询/Webhook |
| F-024 Dashboard进度 | 3h | 前端展示 |
| F-025 问题跟踪同步 | 2h | 状态同步 |
| F-026 项目文档汇总 | 3h | 文档拉取 |
| F-027 项目保密级别配置 | 1h | 配置项增加 |
| F-028 差异化同步规则 | 2h | 根据级别决定同步范围 |
| F-029 保密项目自动同步控制 | 1h | 检测+禁用 |
| F-030 保密信息同步检查 | 2h | 关键词扫描 |
| 测试 + 修复（含错误处理） | 7h | 重点测试CLI失败处理 |
| **总计** | **32h** | |

---

## 七、评审补充建议

### 1. 实现顺序

**建议先实现M22（CLI封装）**，因为其他模块都依赖它。

### 2. 错误处理（重点）

需要处理以下异常场景：
- oc-collab CLI调用超时
- 网络异常
- 权限问题（未认证）
- 项目仓库不存在
- 返回数据格式错误

### 3. 配置管理

项目仓库配置纳入配置管理子系统（`config/projects.yaml`）：

```yaml
projects:
  - name: "金融法院"
    git_repo: "/path/to/金融法院"
    enabled: true
    sync_interval: 3600

  - name: "阳光执法"
    git_repo: "/path/to/阳光执法"
    enabled: true
    sync_interval: 3600
```

---

## 八、风险与应对

---

## 八、风险与应对

| 风险 | 可能性 | 影响 | 应对 |
|------|--------|------|------|
| oc-collab v2.3.3未完成 | 中 | 高 | 等待或先做独立功能 |
| Git仓库访问权限 | 低 | 高 | 配置正确的仓库路径 |
| 轮询频率控制 | 中 | 中 | 可配置间隔 |

---

## 十、参考文档

| 参考文档 | 用途 | 完整路径 |
|----------|------|----------|
| RESEARCH_oc-collab_capabilities_for_PM-Agent.md | oc-collab CLI命令参考 | dual-agent-collaboration-system/docs/07-research/RESEARCH_oc-collab_capabilities_for_PM-Agent.md |
| SUGGESTION_pm_agent_v1.1_oc-collab_integration.md | 协同逻辑和代码示例 | dual-agent-collaboration-system/docs/04-proposals/SUGGESTION_pm_agent_v1.1_oc-collab_integration.md |
| PROPOSAL_2026-02-031_confidential_project_docs_isolation.md | 保密项目功能设计 | dual-agent-collaboration-system/docs/04-proposals/PROPOSAL_2026-02-031_confidential_project_docs_isolation.md |
| CORE_ARCHITECTURE.md | 整体架构参考 | dual-agent-collaboration-system/docs/00-architecture/CORE_ARCHITECTURE.md |

---

## 十一、版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| v1.2.0 | 2026-02-19 | 初稿 |
| v1.2.1 | 2026-02-19 | 评审补充：实现顺序、错误处理、配置管理 |
| v1.2.1 | 2026-02-19 | 新增F-027~F-030保密项目文档隔离功能 |
| v1.2.2 | 2026-02-19 | 追加参考文档附录 |
| v2.0 | 2026-02-22 | 新增ConfMan集成、VersionClient、版本信息前端展示 |

---

# PM-Agent v2.0 新增功能需求

## F-031: ConfManClient集成

**需求描述**：开发conf-man CLI封装客户端，集成配置管理和版本管理能力

**详细说明**：
1. 封装conf-man CLI命令调用
2. 实现路径查询：data/config/log/temp目录
3. 实现文件路径查询：todo-db/state/lock文件
4. 实现环境信息查询：environment/test-mode

**验收标准**：
- [ ] 实现ConfManClient类
- [ ] 支持所有conf-man path命令
- [ ] 支持所有conf-man file命令
- [ ] 支持env和test-mode查询
- [ ] 错误处理和异常捕获

---

## F-032: VersionClient开发

**需求描述**：开发版本管理客户端，调用conf-man版本管理功能

**详细说明**：
1. 实现版本列表查询
2. 实现版本详情查询
3. 实现版本登记
4. 实现版本发布
5. 实现依赖查询

**验收标准**：
- [ ] list_versions() 返回版本列表
- [ ] show_version() 返回版本详情
- [ ] register_version() 登记新版本
- [ ] release_version() 发布版本
- [ ] get_dependencies() 返回依赖列表
- [ ] 项目管理：create/list/show

---

## F-033: 版本信息前端展示

**需求描述**：在PM-Agent前端展示版本信息

**详细说明**：
1. 创建版本信息页面/组件
2. 显示当前系统版本
3. 显示所有已登记版本列表
4. 显示版本详情（组件、依赖）
5. 支持版本切换查看

**验收标准**：
- [ ] 页面展示当前版本
- [ ] 版本列表展示
- [ ] 版本详情弹窗/页面
- [ ] 与ConfManClient API对接
- [ ] 响应式UI设计

---

## F-034: 集成测试

**需求描述**：验证ConfMan和VersionClient功能正确性

**详细说明**：
1. ConfManClient单元测试
2. VersionClient单元测试
3. API集成测试
4. 前端版本展示测试
5. 端到端测试

**验收标准**：
- [ ] 单元测试覆盖率 > 80%
- [ ] 所有API接口测试通过
- [ ] 前端组件测试通过
- [ ] E2E测试场景通过
