Dependency Docs

---
name: dependency-docs
description: 设计前识别并整理第三方依赖文档：外部系统 / API / SDK 各成独立文档并存入需求目录，依赖 ≥ 2 个时并行收集。触发："整理第三方依赖"、"收集 API 文档"、"外部依赖梳理"。
---

# 第三方依赖文档整理器

## 概述

**目的**：在设计阶段前识别并整理第三方依赖文档，为技术设计提供完整的外部依赖信息。

**功能**：扫描需求中的外部系统、API、SDK 等依赖，每个依赖生成**独立文档**。依赖 ≥ 2 个时自动调用 `task-dispatch` 并行收集信息以加速。

**使用场景**：
- 需求涉及第三方 API、SDK、外部服务时
- 设计前需要梳理外部依赖关系时
- 需要整理第三方文档供后续设计参考时

## 核心原则

1. **前置整理**：在设计阶段前完成，为设计提供输入
2. **一依赖一文档**：每个第三方依赖独立成文，便于按需引用和维护
3. **并行加速**：依赖 ≥ 2 时自动用 task-dispatch 并行收集，I/O 密集型任务天然适合并行
4. **结构化输出**：统一模板，每个依赖文档结构一致
5. **索引优先于各自探索**：同一站点的结构**只探索一次**——由主 agent 建索引（或复用已有），再把路由表交给子 agent；否则 N 个子 agent 各摸索一遍，纯属重复劳动（见阶段 2.0）

---

## 工作流总览

```
阶段 1：依赖识别       → 扫描需求，识别所有第三方依赖
阶段 2：并行信息收集    → 依赖 ≥ 2 时 task-dispatch 并行收集，1 个时直接收集
阶段 3：索引生成 + 落盘 → 主 agent 写 README.md 索引 + 写入各依赖文档
```

**未得到用户对当前阶段的确认前，不进入下一阶段。**

---

## 阶段 1：依赖识别

### 输入

需求描述或需求挖掘报告。

### 识别维度

| 依赖类型 | 识别信号 | 示例 |
|----------|---------|------|
| 第三方 API | 调用外部 HTTP 接口 | OpenAI API、Stripe 支付 |
| 第三方 SDK | 引入外部库/包 | AWS SDK、Google Maps SDK |
| 外部服务 | 依赖外部系统能力 | Redis、消息队列、CDN |
| 数据源 | 连接外部数据库/数据源 | 第三方数据提供商 |

### 输出格式

```text
📦 第三方依赖清单
━━━━━━━━━━━━━━━━

| # | 依赖名称 | 类型 | 用途 | 文档查阅方式 | 信息完整度 |
|---|----------|------|------|--------------|-----------|
| 1 | OpenAI API | 第三方 API | 文本生成 | 建索引（.web-index/ 未收录） | 需补充 |
| 2 | Stripe | 第三方 API | 支付处理 | 消费已有索引 | 需补充 |
| 3 | 某内部工具 | 内部服务 | 数据同步 | 直接查（仅 1 页） | 需补充 |

**「文档查阅方式」怎么判**（判定表 SSOT 在 `web-index` 的「被其它 skill 集成」章节，此处不复制规则）：

| 信号 | 判定 |
|------|------|
| 已在 `.web-index/INDEX.md` 在册 | **消费**已有索引，不重建 |
| 多页文档站 + 设计/编码/测试会反复参考 | **建索引** |
| 单页 / 1-3 页 / 无结构 | **直接查**，不建 |
| 无明确入口 URL | 先确定官方入口（通常在依赖官网导航），再判是否值得建 |

> 未建过索引也不打算建的依赖照旧走子 agent 自行收集，不受影响。

共识别 N 个第三方依赖。

[若 N ≥ 2]
  → 将使用 task-dispatch 并行收集信息，预计加速 {N} 倍。

请确认清单是否完整？是否有遗漏的依赖？
```

---

## 阶段 2：并行信息收集

### 2.0 先判文档查阅方式，再分发子任务（主 agent 侧）

**在拆子任务之前**完成，顺序不能反——子 agent 一分发就各自开始探索，再补救就晚了：

1. 读 `.web-index/INDEX.md`，标记已收录的依赖 → **消费模式**
2. 对未收录的依赖按判定表决定**建 / 直接查**（判定表 SSOT 在 `web-index`，不在此复制）
3. 判定要建的：由主 agent 建（每次 1-2 次网络请求，很快），**不要并行让子 agent 各建各的**——同一站点会被重复采集
4. **不要为等索引而整体阻塞**：判定「消费 / 直接查」的依赖**立即分发出去**；只有判定「建」的那几个等索引就绪后再发（分批分发，保住并行收益）
5. 把结论写进子 agent prompt：`索引路径：.web-index/{slug}/index.md（先读它定位页面，再 web_fetch 取正文）`

**子 agent 侧纪律**：拿到索引路径就必须先读路由表定位页面，**不得再自行 `web_search` 摸索站点结构**；路由表未命中才现场查一次，并在 report.md 里记下"索引缺此页"，便于后续补录。

### 子任务拆分

每个依赖拆为一个子任务，编号 `D-{NN}`：

```text
| 编号 | 子任务 | 依赖 | 类型 | 信息收集目标 |
|------|--------|------|------|-------------|
| D-01 | OpenAI API 文档整理 | OpenAI API | 第三方 API | 官方文档、接口清单、认证方式 |
| D-02 | Stripe 文档整理 | Stripe | 第三方 API | 官方文档、接口清单、认证方式 |
```

独立性校验：各依赖之间完全独立（无文件冲突、无接口依赖、无共享资源），可同批并行。

### 执行策略

| 依赖数量 | 策略 |
|----------|------|
| 1 个 | 主 agent 直接收集，不走 task-dispatch |
| ≥ 2 个 | 调用 `task-dispatch` skill 并行收集 |

### task-dispatch 调度要点

**task-name**：`dependency-docs-{功能简称}`（如 `dependency-docs-user-auth`）

**子 agent prompt 要点**（每个子 agent 负责一个依赖）：

```
你是子 agent，负责整理第三方依赖 D-{NN}：{依赖名称}

## 任务目标
收集 {依赖名称} 的完整信息，生成结构化文档。

## 输出目录
代码/文档产出：.codebuddy/task-dispatch/dependency-docs-{功能简称}/subtasks/D-{NN}/code/
  - 产出文件：{依赖名称}.md（按下方模板生成）
执行报告：.codebuddy/task-dispatch/dependency-docs-{功能简称}/subtasks/D-{NN}/report.md

## 信息收集要求
1. **若提供了索引路径**：先读 `.web-index/{slug}/index.md` 与命中的 `topics/*.md`，按「我要…」列定位页面后再 WebFetch 取正文——**不要自行搜索站点结构**
2. 无索引时：优先使用 WebFetch 抓取官方文档页面获取最新信息
3. 若文档信息不足，使用 WebSearch 搜索补充
3. 按以下模板生成 {依赖名称}.md，所有必填字段不得为空：

## {依赖名称}

### 基本信息
| 字段 | 内容 |
|------|------|
| 类型 | API / SDK / 服务 / 数据源 |
| 官方文档 | 文档链接 |
| 索引位置 | `.web-index/{slug}/`（有则填；无填「未建索引」） |
| 用途 | 在本需求中的具体作用 |
| 版本要求 | 最低/推荐版本 |

### 接口清单
| 接口/方法 | 用途 | 请求方式 | 关键参数 | 返回格式 |
|-----------|------|----------|----------|----------|
| ... | ... | ... | ... | ... |

### 认证与配置
- 认证方式：API Key / OAuth / 其他
- 配置项：所需的环境变量、配置文件等

### 限流与配额
- 频率限制：
- 配额上限：

### 备选方案
- 可替代的其他服务及对比：

### 风险与注意事项
- 稳定性：
- 成本：
- 合规：

4. 完成后写 report.md，说明信息收集来源和关键发现
5. 遇到无法获取的信息，标注"待补充"，不编造
```

### task-dispatch 执行

按照 `task-dispatch` skill 的标准流程执行：
- 批次划分：所有子任务同批并行（无依赖关系）
- 并行执行：team_create + Task 并行启动各子 agent
- 合并集成：主 agent 收集各子 agent 产出的 `.md` 文件

### 合并后进入阶段 3

```text
🔨 依赖文档收集完成

| 依赖 | 状态 | 产出文件 |
|------|------|----------|
| OpenAI API | ✅ 完成 | openai-api.md |
| Stripe | ✅ 完成 | stripe.md |

进入阶段 3 生成索引并落盘。
```

---

## 阶段 3：索引生成 + 落盘

### 目录结构（固定多文档模式）

```
dependencies/
├── README.md              # 总览索引
├── {依赖1名称}.md          # 依赖1详情（子 agent 产出）
├── {依赖2名称}.md          # 依赖2详情（子 agent 产出）
└── verify/                # 可选：Demo 验证脚本
    ├── verify_{依赖名}.py
    └── README.md
```

### README.md（索引）

主 agent 写入，汇总所有依赖：

```markdown
# 第三方依赖文档索引

## 依赖总览

| 依赖名称 | 类型 | 用途 | 详情文档 | 索引 | 信息完整度 |
|----------|------|------|----------|------|-----------|
| OpenAI API | 第三方 API | 文本生成 | [详情](./openai-api.md) | `.web-index/openai/`（自仓库根起算） | ✅ 完整 |
| Stripe | 第三方 API | 支付处理 | [详情](./stripe.md) | 未建索引 | ✅ 完整 |

## 使用说明

- 每个依赖的详细信息见独立文档
- 设计时按需查阅相关依赖文档
- 如需 Demo 验证，参考 verify/ 目录
```

### 单个依赖文档

子 agent 已按模板生成，主 agent 校验完整性后直接落盘，不重新生成。

### 落盘

1. 创建目录：`dependencies/`（位于需求文档目录下）
2. 写入 README.md + 各依赖文档
3. 需求管理集成（如已配置 `.requirements/config`）：

```bash
req update {REQ-NNN} \
  --docs add dependencies/README.md,reference \
  --docs add dependencies/{依赖1}.md,reference \
  --docs add dependencies/{依赖2}.md,reference \
  --changelog "整理第三方依赖文档"
```

### 输出格式

```text
✅ 第三方依赖文档已生成

文档位置：{path}/dependencies/
文档数量：{N+1} 个文件（1 个索引 + N 个依赖文档）

| 文件 | 说明 |
|------|------|
| README.md | 依赖总览索引 |
| openai-api.md | OpenAI API 详情 |
| stripe.md | Stripe 详情 |

是否需要对外部依赖进行 Demo 验证？
  - 验证内容：编写验证脚本，确认第三方 API/SDK 的可用性
  - 安全要求：敏感信息从环境变量读取，不写入代码

请选择 [是/否]：
```

---

## 阶段 4（可选）：Demo 验证

当用户选择对依赖进行 Demo 验证时触发。

### 验证脚本规范

**安全要求（强制）**：
- **禁止硬编码**：API Key、Token、密码不写入脚本
- **环境变量读取**：所有敏感配置从环境变量获取

```python
import os
import requests

API_KEY = os.environ.get("SERVICE_API_KEY")
if not API_KEY:
    raise ValueError("请设置环境变量 SERVICE_API_KEY")

def test_api_connection():
    response = requests.get(
        "https://api.example.com/health",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    return response.status_code == 200
```

### 存储位置

```
dependencies/
├── README.md
├── {依赖}.md
└── verify/
    ├── verify_{依赖名}.py
    └── README.md（运行说明）
```

验证脚本存放于 `dependencies/verify/`，`verify/README.md` 包含运行说明。

---

## 反模式

- ❌ 只列名称不整理详情：文档必须包含接口清单、认证方式等关键信息
- ❌ 信息过时：优先使用 WebFetch 获取最新文档
- ❌ 遗漏依赖：设计阶段才发现未整理的依赖会打断流程
- ❌ 文档无结构：必须使用统一模板，便于后续引用
- ❌ 硬编码敏感信息：API Key、Token 不得写入脚本，必须从环境变量读取
- ❌ 多个依赖合成一个大文档：每个依赖独立成文，便于按需引用
- ❌ **让子 agent 各自摸索站点结构**：并行分发前主 agent 必须先判查阅方式、建好索引（见阶段 2.0）——否则 N 个子 agent 重复探索同一站点
- ❌ **已有索引仍重新探索**：`.web-index/INDEX.md` 在册的依赖一律走消费模式，不重建

---

## 需求管理集成

当项目配置了 `.requirements/config` 时自动执行：

### 存储路径映射

| 产出物 | 存储路径 | docs 类型 |
|--------|----------|----------|
| 依赖索引 | `dependencies/README.md` | `reference` |
| 单个依赖文档 | `dependencies/{名称}.md` | `reference` |
| 验证脚本 | `dependencies/verify/verify_{依赖名}.py` | `reference` |
| 验证说明 | `dependencies/verify/README.md` | `reference` |