# DavinciMcp 文档基线

本目录是新工程的产品、架构、实施与专业 Skills 基线。

## 先用大白话看当前版本

你在 Web 上传真实素材，写清楚想做什么片子并创建任务。任务建立唯一的 Codex 主聊天后，Web 立即提供该聊天的明确跳转链接；系统在该聊天中说明任务、持续展示真实正在执行的动作、剪辑方案和试看片，而不是用固定步骤猜进度。首条说明走可重试事件队列，投递慢或暂时失败不会阻止建单或打开同一聊天。你只在真的需要审片时在同一个聊天里确认声音或提出新的剪辑方向；确认后，系统生成**候选成片**。

这是首版要跑通的完整流程。当前 Web 正式委托入口已经接通，后台专业分析的 P0 启动问题也已修复并完成隔离运行验证；但尚未在最新 `main` 上用一条真实项目把从正式委托到候选成片的完整闭环重新跑通，因此整条流程还不能写成已经可用。

```mermaid
flowchart LR
    W["Web：素材库、动效库、创建任务"] --> C["冻结任务并创建唯一 Codex 主聊天"]
    C -->|主聊天已就绪| H["Codex 主聊天：进度、方案、试看片、反馈"]
    C -->|主聊天创建失败| R["Web：只显示失败原因与重试"]
    H --> M["项目 MCP：读取状态、提交受控决定"]
    M --> P["后端项目事实与事件"]
    P --> WK["Worker：分析、规划、Resolve、渲染"]
    WK --> O["可重试事件 Outbox"] --> H
```

- 自动检查发现“字幕可能偏小、节奏可能偏快”这类创作提醒时，会保存，但当前还没有稳定的用户查看入口；接通入口后只展示，不会拦住候选成片；
- 只有文件损坏、渲染失败、素材或已绑定资源发生变化、外部声音尚未确认、或检查结果本身损坏等技术问题，才会安全停下；
- 首版不会偷偷自动混音、降噪、调色、改剪辑或加 Look；
- Web 只负责素材、任务创建和重新打开主聊天；详细进度、方案、试看片和反馈均在 Codex 主聊天中完成。

## 当前开发状态（技术摘要）

| 用户看到的说法 | 内部技术名 |
|---|---|
| 第一份剪辑方案 | P1 / `edit_planning` |
| 第一版试看片 | E1 / `work_preview` |
| 候选成片 | `candidate_render` |

- P1 的自动生成链路已经接上，后台专业分析已通过启动与隔离验证；正式委托会在素材理解完成后自动生成 P1。是否能稳定从真实委托走完整条链路，仍待最新 `main` 的端到端实测。只有含真实可执行片段、通过无副作用校验的方案才能批准制作。批准后执行只读取这份冻结方案，不会暗中重新选片或替换资源；
- `videos/` 中的历史渲染只是**内部技术预览**，不是剪辑成片；
- `default-v1` 是首版唯一可自动使用的固定字体与配色。声音 Skill 只能根据已认证音效的受控资料做暂定选择，不能假装听过；用户只试听整条第一版试看片；
- 素材库运营与项目剪辑分开：项目只能检索已经发布、认证、并完成必要整理的素材，库里没有合适候选时会诚实不用，不会随意凑效果。

## 阅读顺序

0. `AGENTS.md`：开发原则、语言要求、范围控制和完成后汇报；
1. `docs/PRODUCT.md`：产品目标、用户流程、范围和验收；
2. `docs/ARCHITECTURE.md`：模块、进程、数据、任务和扩展边界；
3. `docs/CREATIVE_LIBRARY.md`：Nextcloud 创意素材库、目录、检索与本地缓存；
4. `docs/CREATIVE_LIBRARY_OPERATIONS.md`：素材整理、素材卡、认证与发布的独立运营流程；
5. `docs/MEDIA_INTELLIGENCE.md`：上传校验、FunASR、多模态证据和素材理解实现；
6. `docs/DAVINCI_ENGINE_MCP.md`：自研 Resolve 执行 MCP、参考仓库、能力迁移与验收合同；
7. `docs/CREATIVE_ADAPTER_DEVELOPMENT.md`：创意能力 Adapter 的当前实现、认证边界和新增方式；
8. `.agents/skills/*/SKILL.md`：各专业任务的判断方法与交接；
9. `docs/IMPLEMENTATION_PLAN.md`：本次开发的纵向切片；

## 权威范围

- 开发过程与交付说明以 `AGENTS.md` 为准；
- 产品需求以 `docs/PRODUCT.md` 为准；
- 系统实现边界以 `docs/ARCHITECTURE.md` 为准；
- 创意素材管理与检索以 `docs/CREATIVE_LIBRARY.md` 为准；
- 素材上架、整理与发布流程以 `docs/CREATIVE_LIBRARY_OPERATIONS.md` 为准；
- 媒体分析与素材理解输入以 `docs/MEDIA_INTELLIGENCE.md` 为准；
- Resolve 执行合同、外部实现参考和能力迁移边界以 `docs/DAVINCI_ENGINE_MCP.md` 为准；
- 专业判断方法以对应 `SKILL.md` 为准；
- 精确字段、枚举和接口参数以代码 Schema 与自动生成接口文档为准。

文档之间出现冲突时，不自行折中：先按以上权威范围定位责任，再向产品负责人确认。

## 本机配置

- `.env.example`：多模态反代、Nextcloud、缓存和工作区配置示例；`./workspace/` 仅是开发默认值。正式服务必须把 `WORKSPACE_ROOT`、`APP_DATA_ROOT` 与 `CREATIVE_CACHE_ROOT` 指向工作树外的长期本机运行目录；
- `models/manifest.example.yaml`：FunASR 本地模型配置示例；

真实密钥、模型权重、数据库、工作区和本地缓存不得提交 Git。


## 固定运行环境

本项目首期**复用现有 Conda 环境**，不得自动创建新的 Python 环境：

```text
Conda 环境名：unofficial-davinci-mcp-win
Python 版本：3.10.20
```

开发、安装依赖和启动前使用：

```powershell
conda activate unofficial-davinci-mcp-win
python --version
where python
```

API、Worker 和 `davinci-engine-mcp` 必须使用同一个解释器。未经产品负责人明确同意，不得执行 `conda create`、`python -m venv`、`uv venv`、Poetry 自动建环境或创建 `.venv`。项目采用 `src` 目录布局，`scripts/start.ps1` 会先设置必要的 `PYTHONPATH` 再调用统一启动器；手动执行模块命令时也应先设置该路径：

```powershell
$env:PYTHONPATH = "$PWD\src;$PWD\davinci-engine-mcp\src"
conda run --no-capture-output -n unofficial-davinci-mcp-win python -m davinci_app
```

启动时必须校验 `CONDA_DEFAULT_ENV`、Python 版本和 `sys.executable`；不符合时直接停止并提示激活现有环境，不能自行创建替代环境。

## 本机启动

在仓库根目录执行：

```powershell
.\scripts\start.ps1
```

该脚本只复用 `unofficial-davinci-mcp-win`，启动 API 与持久 Worker；Engine MCP 仅由 Worker 按需以 stdio 子进程启动。

若只验证仓库 `videos/` 中三组素材的上传、证据、转写与素材理解，而不创建时间线或渲染，可执行：

```powershell
$env:PYTHONPATH = "$PWD\src;$PWD\davinci-engine-mcp\src"
conda run --no-capture-output -n unofficial-davinci-mcp-win python -m davinci_app source-analysis-demo --execute
```

该命令会创建新的 `source_analysis` 项目，并在 `SourceUnderstanding` 完成后停止；它不能创建视频产物、`VideoVersion` 或 `ready_for_review`。