# 基础能力治理与补强方案（提案）

> 2026-10-03 · 状态：待用户拍板
> 背景：用户提问"接着补基础能力，怎么加，也涉及以后基础能力如何增加调整"

---

## 一、诊断：能力体系已"半脱节"

### 已有基础（做得好的）

| 模块 | 位置 | 作用 |
|---|---|---|
| 能力登记 | `05_tools/09_ave/config/capabilities.yaml` | 25 个能力，含 io / params_schema / providers |
| 缺口声明 | `05_tools/09_ave/config/feasibility_rules.yaml` | 30 条可行性规则 + 10 个能力缺口映射 + 三色红线 |
| 匹配器 | `05_tools/09_ave/scripts/capability_matcher.py` | 需求→能力匹配 + 目录指纹 + 升级检测 |
| 前端 | 导演台技术预检弹窗 | 显示每个镜头的技术预检与缺口汇总 |

### ⚠️ 实测发现的 5 处"清单 ≠ 实际"

| 能力 | 清单写的 | 实际 | 影响 |
|---|---|---|---|
| `lipsync` 对口型 | providers: fal / volcano / d_id · partial | 已用**百炼 videoretalk** 跑通 | 清单 provider 错误，无法据此排障 |
| `person_swap` 人物置换 | partial | **已实测跑通** | 状态偏保守 |
| `vfx_apply` 特效 | planned | 可灵 `camera_control` **已可用** | 状态偏保守 |
| `frame_chain` 首尾帧 | **missing** | `kling_video.py:152` **已实现 image_tail** | **把已有能力报成缺口** |
| `voice_lock` 声线锁 | cap_id=**None** | 音色库已实现 | 未挂到能力，统计丢失 |

**根因**：能力登记、代码实现、缺口声明**三者无联动** ——
加了功能忘登记、登记了没实现、实现了却仍报"缺失"。

---

## 二、机制方案：能力生命周期（4 步 + 1 台账）

```
① 登记  capabilities.yaml（唯一真相源）
        新增字段：
          cost:        {unit: "元/秒", price: 0.08, note: "走免费额度优先"}
          limits:      ["正面近景 2~120s", "边长 640~2048"]
          self_test:   "python -m capabilities.selftest lipsync"
          last_verified: "2026-10-03"
          provider.state: ready | needs_key | broken

② 自检  scripts/capability_doctor.py（新）
        一条命令验证"清单说的 ready 是不是真能跑"
          --list          列出全部能力与最近验证状态
          --capability X  单查（api_key 配置 / provider 可达 / limits 校验）
          --live          真跑最小样例（产生费用，需显式开启）
          --update        把验证结果写回 capabilities.yaml 的 last_verified

③ 接入  标准 4 步（写成 docs/CAPABILITY_GUIDE.md）
          a. capabilities.yaml 登记（id/name/category/io/schema/provider/cost/limits）
          b. 实现 provider（scripts/capabilities/<name>.py 或既有模块）
          c. 写自检样例（让 doctor --live 能跑）
          d. feasibility_rules.yaml 声明"什么技术需求触发它"
        —— 与导演系统的"接新导演 3 步"对称

④ 台账  runtime/ave/capability_gaps.json（新）
         缺口不再散落在规则里，而是有状态：
           {id, name, first_seen, occurrences, affected_shots[], status,
            blocking, resolved_at, resolved_by}
         status: open → planned → in_progress → resolved
         + 能力升级 → 指纹变化 → 已出片方案自动提示"可重新生成更好版本"
```

**设计取舍**：先做 ①②（对账 + 体检），台账 ④ 可后置。
理由是 ①② 立刻消除"清单不可信"这个根本问题；④ 是统计增项。

---

## 三、本轮补什么（按性价比排序）

### 🥇 P0 能力对账 + 体检脚本（零成本 · 约 1 天）

- 修正上述 5 处脱节（尤其 `frame_chain` 从 missing → ready）
- 补 `cost` / `limits` 字段（为报价与预算打基础）
- 写 `capability_doctor.py`（`--list` 与单查；`--live` 可选）
- **产出**：一份可信的能力清单 + 一键体检

### 🥈 P1 首尾帧衔接 `frame_chain`（能力已有，只差接线）

- **前提**：可灵 `image_tail` 参数**代码已实现**（`capabilities/kling_video.py:143-152`）
- **做**：分镜 `tech_requirements.chain_from_prev` → 生成时自动把上一镜尾帧作为本镜尾帧/首帧
  - 抽尾帧：ffmpeg 取上一镜最后一帧 → 存 `chain/{shot_id}_tail.jpg`
  - 生成时：`tail_image_path=上镜尾帧`
- **效果**：长镜头分段生成无缝衔接；跨镜人物/光线不漂移
- **成本**：0（只多一个参数；抽帧是本地 ffmpeg）

### 🥉 P2 多角色同框一致性（已发现的真实问题）

现状：图生视频只喂**一张**参考图 → 双人同框时只有主角保脸，配角随机。

| 方案 | 做法 | 成本 | 我的评价 |
|---|---|---|---|
| **a. 首帧合成** | 生成前把多角色合成到一张首帧图 → 图生视频 | 一次图生图 | 效果最好，稍复杂 |
| **b. 导演层规避** | 提示词要求避免"多角色同框近景"，改用正反打/过肩 | **0** | **零成本先上**，且更符合真实拍摄 |
| c. 多参考图 | 查即梦/万相是否支持多图输入 | ? | 需先验证 |

**建议**：先 b（零成本、马上见效）→ 再评估 a。

### P3 表情微管理 `expression_consistency`

- 轻量：分镜 `expression_detail`（已有）+ 跨镜一致性提示词强化
- 中量：角色资产加"表情参考图"槽位 → 图生视频时带上

### P4 口型质检辅助（用户提过的"微表情口型核对"）

- 出片后自动抽关键帧 → 拼对比图 → 人工快速核对
- 进阶：接人脸检测，粗判嘴部开合与音频包络是否吻合

---

## 四、推荐执行顺序

```
P0 对账 + 体检脚本        ← 地基，零成本，先做
    ↓
P1 首尾帧接线             ← 能力已有，投入产出比最高
    ↓
P2b 多角色规避（提示词）→ P2a 首帧合成
    ↓
P3 表情 / P4 口型质检
```

---

## 五、待用户拍板

1. **P0 治理机制**是否认可？（登记 + 自检 + 台账三件套；可精简为"对账 + doctor"）
2. **P1 首尾帧**是否本轮做？
3. **P2 多角色**：先用提示词规避够不够，还是直接上首帧合成？

---

## 附：执行时需动的文件（预告）

- `05_tools/09_ave/config/capabilities.yaml`（对账 + 补字段）
- `05_tools/09_ave/config/feasibility_rules.yaml`（缺口状态修正）
- `05_tools/09_ave/scripts/capability_doctor.py`（新建）
- `05_tools/09_ave/scripts/capability_matcher.py`（缺口台账读写）
- `05_tools/09_ave/scripts/composer/pipeline.py`（首尾帧接线）
- `05_tools/09_ave/scripts/directors/*.py`（多角色规避提示词）
- `05_tools/10_dashboard/routes/ave.py` + 前端（缺口台账展示，可选）