Base + docs: DOS planner, P1–P6 timeline/media integration, docs module-tree reorg

AGENTS.md

@@ -10,23 +10,24 @@ PRIMARY-CN/
 ├── palmier-pro-upstream/   # 上游只读参考（Swift macOS 视频编辑器，GPL-3.0）
 │   └── Sources/PalmierPro/ # 209 .swift，~43K 行，编辑逻辑的真理来源
 └── OpenTake/               # 本项目
-    ├── docs/               # 架构 / 路线图 / 模块移植规格
-    │   └── _analysis/      # 上游拆解报告（4 份横切分析）
-    ├── crates/             # Rust workspace（待创建）
-    ├── src-tauri/          # Tauri 2 桌面壳（待创建）
-    ├── web/                # React + TypeScript 前端（待创建）
-    └── services/           # 可选后端服务（待创建）
+    ├── docs/               # 文档树（入口 docs/INDEX.md）
+    │   ├── modules/        # ★ 按 crate/前端的模块文档（总览+目录+子系统）
+    │   ├── architecture/   # 跨切面：架构/路线图/移植图/gap/bug/编辑自动化 DOS
+    │   └── upstream-analysis/  # 上游拆解报告
+    ├── crates/             # Rust workspace（9 个 crate，依赖只能向下）
+    ├── src-tauri/          # Tauri 2 桌面壳
+    └── web/                # React + TypeScript 前端
 ```
 
 ## 从何处开始
 
 | 你要做什么 | 先看这个 |
 |---|---|
 | 了解项目全局 | [README.md](README.md) |
-| 理解目标架构 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
-| 知道当前阶段 + 下一步做什么 | [docs/ROADMAP.md](docs/ROADMAP.md) |
-| 理解 Agent 如何与软件协作 | [docs/AGENT-CONTEXT-SIGNAL.md](docs/AGENT-CONTEXT-SIGNAL.md) |
-| 移植某个上游模块 | [docs/MODULE-PORT-MAP.md](docs/MODULE-PORT-MAP.md) |
+| 理解目标架构 | [docs/architecture/ARCHITECTURE.md](docs/architecture/ARCHITECTURE.md) |
+| 知道当前阶段 + 下一步做什么 | [docs/architecture/ROADMAP.md](docs/architecture/ROADMAP.md) |
+| 理解 Agent 如何与软件协作 | [docs/modules/opentake-agent/AGENT-CONTEXT-SIGNAL.md](docs/modules/opentake-agent/AGENT-CONTEXT-SIGNAL.md) |
+| 移植某个上游模块 | [docs/architecture/MODULE-PORT-MAP.md](docs/architecture/MODULE-PORT-MAP.md) |
 | 了解为何选了 Rust / Tauri / GPL-3.0 | [DECISIONS.md](DECISIONS.md) |
 | 查找某个上游模块的源码 | `palmier-pro-upstream/Sources/PalmierPro/` |
 
@@ -75,7 +76,7 @@ PRIMARY-CN/
 - 所有数值常量走 `AppTheme`，不硬编码。
 - 悬停态用 CSS `:hover` + 圆角背景，图标用 lucide-react。
 
-## 构建（Phase 0 完成后）
+## 构建（全部在 `OpenTake/` 内运行）
 
 ```bash
 # Rust core
@@ -90,7 +91,7 @@ cd web && pnpm install && pnpm build
 cargo tauri dev
 ```
 
-当前状态：**设计阶段**，代码尚未产生。ROADMAP Phase 0 为工程脚手架。
+当前状态：**MVP 编辑闭环已并入 main**——9 个 crate + Tauri 壳 + React 前端均已存在并通过 CI。最新进度与下一步见 `CLAUDE.md`（工作交接状态文档）与 `docs/architecture/PORT-1TO1-GAP.md`。
 
 ## 上游参考
 
@@ -112,4 +113,4 @@ OpenTake 的核心创新之一是 **软件主动向 Agent 发送剪辑指引**
 - 当前剪辑阶段和下一步建议
 - 该视频类型适用的剪辑规则
 
-这些指引内化自 ClipSkills 技能套件（[appergb/ClipSkills](https://github.com/appergb/ClipSkills)，MIT 许可）。详见 [docs/AGENT-CONTEXT-SIGNAL.md](docs/AGENT-CONTEXT-SIGNAL.md) 和 [docs/WORKFLOW-PLUGIN-SYSTEM.md](docs/WORKFLOW-PLUGIN-SYSTEM.md)。
+这些指引内化自 ClipSkills 技能套件（[appergb/ClipSkills](https://github.com/appergb/ClipSkills)，MIT 许可）。详见 [docs/modules/opentake-agent/AGENT-CONTEXT-SIGNAL.md](docs/modules/opentake-agent/AGENT-CONTEXT-SIGNAL.md) 和 [docs/modules/opentake-agent/WORKFLOW-PLUGIN-SYSTEM.md](docs/modules/opentake-agent/WORKFLOW-PLUGIN-SYSTEM.md)。

CLAUDE.md

@@ -1,6 +1,6 @@
 # OpenTake — 工作交接 / 状态文档（给压缩上下文后的自己）
 
-> 本文件是 OpenTake 开发的**权威状态 + 操作手册**。每次上下文压缩后先读它,再读 `docs/PORT-1TO1-GAP.md`(1:1 差距与实现计划,批次蓝图)。
+> 本文件是 OpenTake 开发的**权威状态 + 操作手册**。每次上下文压缩后先读它,再读 `docs/architecture/PORT-1TO1-GAP.md`(1:1 差距与实现计划,批次蓝图)。
 > 用户用中文沟通,回复用中文。用户要我**全自主**:自己开子 Agent / workflow,**绝不让用户开 agent / 不向用户提问要他操作**;**自己用真机 computer-use 测试**,做到能用再回报。
 
 > ⚠️ computer-use 点击本机被 Dock 遮挡全局拦截(报"会落在程序坞")。改用 `preview_start` dev server(浏览器 fallback `web/src/lib/fallback.ts` 有 demo 时间线)+ `preview_eval` 注入测量验证布局,绕开真机点击。详见 `memory/opentake-editing-parity.md`。
@@ -40,7 +40,7 @@
 
 ## 1. 目录
 - 仓库根 `OpenTake/`(在此跑 git/cargo/pnpm)。上游只读参考:`../palmier-pro-upstream/Sources/PalmierPro/`(**1:1 复刻唯一权威来源**)。
-- 计划/设计:`docs/PORT-1TO1-GAP.md`(必读)、`docs/`(ARCHITECTURE/ROADMAP/specs/*)。
+- 计划/设计:`docs/architecture/PORT-1TO1-GAP.md`(必读)、`docs/`(ARCHITECTURE/ROADMAP/specs/*)。
 
 ## 2. ✅ 已完成并入 main(CI 全绿)——MVP 编辑闭环已能用
 - 14 模块(domain/ops/project/render/media/agent/gen/core/前端#12/进阶A#13/motion#14)+ PR #41–#46。
@@ -80,4 +80,4 @@
 Streamable-HTTP `http://127.0.0.1:19789/mcp`(loopback+Origin 校验)。`claude mcp add --transport http opentake http://127.0.0.1:19789/mcp`;Cursor/Codex/Claude Desktop 同址。40 工具,返回附 context_signal。
 
 ## 7. 压缩后立即执行
-1. 读本文件 + `docs/PORT-1TO1-GAP.md`。2. `git -C OpenTake pull`(main)。3. 盘点 `gh issue list`,挑最高价值且可完整交付的:**首选 🔴 #53 播放引擎**(大,需专门会话),或 #48 片段编辑收尾、#49/#37 库与文件夹、剩余 MCP 工具 stub。4. 每项走 分支→写→自审→`cargo fmt`+clippy+test→真机/确定性验证→`gh run watch` 双绿→`--admin` 合并。5. 新依赖先读 `~/.cargo/registry/src` 真实源码核实 API(cosmic-text/rmcp 都这么做的),别照猜测写。
+1. 读本文件 + `docs/architecture/PORT-1TO1-GAP.md`。2. `git -C OpenTake pull`(main)。3. 盘点 `gh issue list`,挑最高价值且可完整交付的:**首选 🔴 #53 播放引擎**(大,需专门会话),或 #48 片段编辑收尾、#49/#37 库与文件夹、剩余 MCP 工具 stub。4. 每项走 分支→写→自审→`cargo fmt`+clippy+test→真机/确定性验证→`gh run watch` 双绿→`--admin` 合并。5. 新依赖先读 `~/.cargo/registry/src` 真实源码核实 API(cosmic-text/rmcp 都这么做的),别照猜测写。

README.ja.md

@@ -80,7 +80,7 @@ OpenTake は CapCut / DaVinci Resolve / Final Cut Pro の代替品ではあり
 
 ナレッジソース: [ClipSkills](https://github.com/appergb/ClipSkills) — 12巻のプロ編集ナレッジベース（MITライセンス）。
 
-📖 [Context Signal 設計](docs/AGENT-CONTEXT-SIGNAL.md)
+📖 [Context Signal 設計](docs/modules/opentake-agent/AGENT-CONTEXT-SIGNAL.md)
 
 ### 🔌 MCP Server — 31ツール
 
@@ -112,7 +112,7 @@ OpenTake は CapCut / DaVinci Resolve / Final Cut Pro の代替品ではあり
 
 レビュー / チュートリアル / ゲーム / ウェディング / トーキングヘッド — 各ジャンルのプロ編集手法を JSON + Markdown プラグインとしてパッケージ化。
 
-📖 [ワークフロープラグイン設計](docs/WORKFLOW-PLUGIN-SYSTEM.md)
+📖 [ワークフロープラグイン設計](docs/modules/opentake-agent/WORKFLOW-PLUGIN-SYSTEM.md)
 
 ---
 
@@ -164,23 +164,23 @@ crates/
 └──────────────────────────────────────────────────────┘
 ```
 
-📖 [アーキテクチャ詳細](docs/ARCHITECTURE.md)
+📖 [アーキテクチャ詳細](docs/architecture/ARCHITECTURE.md)
 
 ---
 
 ## 📚 ドキュメント
 
 | ドキュメント | 内容 |
 |:--|:--|
-| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | アーキテクチャ、レイヤリング、クレートレイアウト |
-| [ROADMAP.md](docs/ROADMAP.md) | Phase 0–10 ロードマップ |
-| [MODULE-PORT-MAP.md](docs/MODULE-PORT-MAP.md) | 20上流モジュール移植仕様 |
-| [AGENT-CONTEXT-SIGNAL.md](docs/AGENT-CONTEXT-SIGNAL.md) | Agent Context Signal 設計 |
-| [WORKFLOW-PLUGIN-SYSTEM.md](docs/WORKFLOW-PLUGIN-SYSTEM.md) | ワークフロープラグインシステム |
-| [ADVANCED-FEATURES.md](docs/ADVANCED-FEATURES.md) | CapCut対比の高度機能 |
-| [CAPCUT-GAP.md](docs/CAPCUT-GAP.md) | CapCutとの33項目ギャップ分析 |
+| [ARCHITECTURE.md](docs/architecture/ARCHITECTURE.md) | アーキテクチャ、レイヤリング、クレートレイアウト |
+| [ROADMAP.md](docs/architecture/ROADMAP.md) | Phase 0–10 ロードマップ |
+| [MODULE-PORT-MAP.md](docs/architecture/MODULE-PORT-MAP.md) | 20上流モジュール移植仕様 |
+| [AGENT-CONTEXT-SIGNAL.md](docs/modules/opentake-agent/AGENT-CONTEXT-SIGNAL.md) | Agent Context Signal 設計 |
+| [WORKFLOW-PLUGIN-SYSTEM.md](docs/modules/opentake-agent/WORKFLOW-PLUGIN-SYSTEM.md) | ワークフロープラグインシステム |
+| [ADVANCED-FEATURES.md](docs/architecture/ADVANCED-FEATURES.md) | CapCut対比の高度機能 |
+| [CAPCUT-GAP.md](docs/architecture/CAPCUT-GAP.md) | CapCutとの33項目ギャップ分析 |
 | [DECISIONS.md](DECISIONS.md) | 技術選定 / ライセンス ADR |
-| [PORT-1TO1-GAP.md](docs/PORT-1TO1-GAP.md) | 1:1移植ギャップ分析 |
+| [PORT-1TO1-GAP.md](docs/architecture/PORT-1TO1-GAP.md) | 1:1移植ギャップ分析 |
 
 ---
 ---
@@ -244,7 +244,7 @@ cd .. && cargo tauri dev
 | `0.1.0-dev` | 2026-06 | Phase 0+1: Cargo workspace + Domain models + Edit ops |
 | *(planned)* `1.0.0` | TBD | Phase 10: フルリリース |
 
-📖 [完全なロードマップ](docs/ROADMAP.md)
+📖 [完全なロードマップ](docs/architecture/ROADMAP.md)
 
 ---
 

README.md

@@ -92,7 +92,7 @@ Every MCP tool response carries a `context_signal`:
 
 Knowledge source: [ClipSkills](https://github.com/appergb/ClipSkills) — 12-volume professional editing knowledge base (MIT-licensed).
 
-📖 [Context Signal Design](docs/AGENT-CONTEXT-SIGNAL.md)
+📖 [Context Signal Design](docs/modules/opentake-agent/AGENT-CONTEXT-SIGNAL.md)
 
 ### 🔌 MCP Server — 31 Tools
 
@@ -126,7 +126,7 @@ Built-in Agent chat panel shares tool definitions and system prompt with MCP.
 
 Community-authored JSON + Markdown plugins per video genre — review / tutorial / gaming / wedding / talking-head — each encapsulating professional editing methodology. Agent activates, methodology loads.
 
-📖 [Workflow Plugin System Design](docs/WORKFLOW-PLUGIN-SYSTEM.md)
+📖 [Workflow Plugin System Design](docs/modules/opentake-agent/WORKFLOW-PLUGIN-SYSTEM.md)
 
 ---
 
@@ -200,23 +200,23 @@ plugins/
 └──────────────────────────────────────────────────────┘
 ```
 
-📖 [Architecture Docs](docs/ARCHITECTURE.md)
+📖 [Architecture Docs](docs/architecture/ARCHITECTURE.md)
 
 ---
 
 ## 📚 Docs
 
 | Document | Content |
 |:--|:--|
-| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Target architecture, layering, crate layout, command layer, render pipeline |
-| [ROADMAP.md](docs/ROADMAP.md) | Phase 0–10 roadmap with verification criteria and risk register |
-| [MODULE-PORT-MAP.md](docs/MODULE-PORT-MAP.md) | 20 upstream module port specs with core algorithms |
-| [AGENT-CONTEXT-SIGNAL.md](docs/AGENT-CONTEXT-SIGNAL.md) | Agent Context Signal system design |
-| [WORKFLOW-PLUGIN-SYSTEM.md](docs/WORKFLOW-PLUGIN-SYSTEM.md) | Workflow Plugin System (JSON + Markdown) |
-| [ADVANCED-FEATURES.md](docs/ADVANCED-FEATURES.md) | Advanced features vs CapCut |
-| [CAPCUT-GAP.md](docs/CAPCUT-GAP.md) | 33-item gap analysis vs CapCut |
+| [ARCHITECTURE.md](docs/architecture/ARCHITECTURE.md) | Target architecture, layering, crate layout, command layer, render pipeline |
+| [ROADMAP.md](docs/architecture/ROADMAP.md) | Phase 0–10 roadmap with verification criteria and risk register |
+| [MODULE-PORT-MAP.md](docs/architecture/MODULE-PORT-MAP.md) | 20 upstream module port specs with core algorithms |
+| [AGENT-CONTEXT-SIGNAL.md](docs/modules/opentake-agent/AGENT-CONTEXT-SIGNAL.md) | Agent Context Signal system design |
+| [WORKFLOW-PLUGIN-SYSTEM.md](docs/modules/opentake-agent/WORKFLOW-PLUGIN-SYSTEM.md) | Workflow Plugin System (JSON + Markdown) |
+| [ADVANCED-FEATURES.md](docs/architecture/ADVANCED-FEATURES.md) | Advanced features vs CapCut |
+| [CAPCUT-GAP.md](docs/architecture/CAPCUT-GAP.md) | 33-item gap analysis vs CapCut |
 | [DECISIONS.md](DECISIONS.md) | Tech stack / license / branding ADRs |
-| [PORT-1TO1-GAP.md](docs/PORT-1TO1-GAP.md) | 1:1 port gap analysis |
+| [PORT-1TO1-GAP.md](docs/architecture/PORT-1TO1-GAP.md) | 1:1 port gap analysis |
 
 ---
 ---
@@ -296,7 +296,7 @@ The sibling directory `palmier-pro-upstream/` contains upstream Swift sources fo
 | *(planned)* `0.4.0` | TBD | Phase 4: GPU Compositor (wgpu) + Text rasterization |
 | *(planned)* `1.0.0` | TBD | Phase 10: Full release — CapCut parity + deep Agent integration |
 
-📖 [Full Roadmap](docs/ROADMAP.md)
+📖 [Full Roadmap](docs/architecture/ROADMAP.md)
 
 ---
 

README.zh-CN.md

@@ -80,7 +80,7 @@ Agent 操作时间线时，每次工具返回附带 `context_signal`：
 
 知识来源: [ClipSkills](https://github.com/appergb/ClipSkills) — 12 册专业剪辑知识内核（MIT 许可），融合影视飓风等专业课程方法论。
 
-📖 [Context Signal 设计文档](docs/AGENT-CONTEXT-SIGNAL.md)
+📖 [Context Signal 设计文档](docs/modules/opentake-agent/AGENT-CONTEXT-SIGNAL.md)
 
 ### 🔌 MCP Server — 31 个工具
 
@@ -114,7 +114,7 @@ Agent 操作时间线时，每次工具返回附带 `context_signal`：
 
 社区为每种视频类型编写 JSON + Markdown 插件——评测 / 科普 / 游戏 / 婚礼 / 口播——每个插件封装专业剪辑方法论，Agent 激活即用。
 
-📖 [Workflow Plugin System 设计](docs/WORKFLOW-PLUGIN-SYSTEM.md)
+📖 [Workflow Plugin System 设计](docs/modules/opentake-agent/WORKFLOW-PLUGIN-SYSTEM.md)
 
 ---
 
@@ -181,23 +181,23 @@ plugins/
 └──────────────────────────────────────────────────────┘
 ```
 
-📖 [详细架构文档](docs/ARCHITECTURE.md)
+📖 [详细架构文档](docs/architecture/ARCHITECTURE.md)
 
 ---
 
 ## 📚 文档
 
 | 文档 | 内容 |
 |:--|:--|
-| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | 目标架构、分层、crate 布局、命令层、渲染管线 |
-| [ROADMAP.md](docs/ROADMAP.md) | Phase 0–10 路线图，含验证标准与风险登记 |
-| [MODULE-PORT-MAP.md](docs/MODULE-PORT-MAP.md) | 20 个上游模块逐项移植规格、核心算法 |
-| [AGENT-CONTEXT-SIGNAL.md](docs/AGENT-CONTEXT-SIGNAL.md) | Agent 上下文信号系统设计 |
-| [WORKFLOW-PLUGIN-SYSTEM.md](docs/WORKFLOW-PLUGIN-SYSTEM.md) | 工作流插件系统 (JSON + Markdown) |
-| [ADVANCED-FEATURES.md](docs/ADVANCED-FEATURES.md) | 对标剪映的进阶能力设计 |
-| [CAPCUT-GAP.md](docs/CAPCUT-GAP.md) | 与剪映的 33 项特性差距分析 |
+| [ARCHITECTURE.md](docs/architecture/ARCHITECTURE.md) | 目标架构、分层、crate 布局、命令层、渲染管线 |
+| [ROADMAP.md](docs/architecture/ROADMAP.md) | Phase 0–10 路线图，含验证标准与风险登记 |
+| [MODULE-PORT-MAP.md](docs/architecture/MODULE-PORT-MAP.md) | 20 个上游模块逐项移植规格、核心算法 |
+| [AGENT-CONTEXT-SIGNAL.md](docs/modules/opentake-agent/AGENT-CONTEXT-SIGNAL.md) | Agent 上下文信号系统设计 |
+| [WORKFLOW-PLUGIN-SYSTEM.md](docs/modules/opentake-agent/WORKFLOW-PLUGIN-SYSTEM.md) | 工作流插件系统 (JSON + Markdown) |
+| [ADVANCED-FEATURES.md](docs/architecture/ADVANCED-FEATURES.md) | 对标剪映的进阶能力设计 |
+| [CAPCUT-GAP.md](docs/architecture/CAPCUT-GAP.md) | 与剪映的 33 项特性差距分析 |
 | [DECISIONS.md](DECISIONS.md) | 技术栈 / 许可 / 品牌决策记录 (ADR) |
-| [PORT-1TO1-GAP.md](docs/PORT-1TO1-GAP.md) | 1:1 端口差距分析 |
+| [PORT-1TO1-GAP.md](docs/architecture/PORT-1TO1-GAP.md) | 1:1 端口差距分析 |
 
 ---
 ---
@@ -272,7 +272,7 @@ cd .. && cargo tauri dev
 | *(planned)* `0.4.0` | TBD | Phase 4: GPU Compositor (wgpu) + Text rasterization |
 | *(planned)* `1.0.0` | TBD | Phase 10: 全功能发布 — 对标剪映 + Agent 深度集成 |
 
-📖 [完整路线图](docs/ROADMAP.md)
+📖 [完整路线图](docs/architecture/ROADMAP.md)
 
 ---
 

crates/opentake-agent/Cargo.toml

@@ -11,6 +11,7 @@ opentake-domain = { workspace = true }
 opentake-ops = { workspace = true }
 opentake-core = { workspace = true }
 opentake-gen = { workspace = true }
+opentake-media = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 serde_path_to_error = "0.1"

crates/opentake-agent/src/mcp/core_handle.rs

@@ -11,7 +11,8 @@
 use std::path::PathBuf;
 
 use opentake_core::AppCore;
-use opentake_domain::{MediaManifest, Timeline};
+use opentake_domain::{MediaManifest, MediaResolver, Timeline};
+use opentake_media::{extract_pcm, PcmBuffer, PcmSpec};
 use opentake_ops::command::{EditCommand, EditResult};
 
 /// The narrow document surface the dispatch shell needs. `Send + Sync` so a
@@ -32,6 +33,29 @@ pub trait CoreHandle: Send + Sync {
 
     /// The open project's bundle directory, or `None` for an unsaved project.
     fn project_dir(&self) -> Option<PathBuf>;
+
+    /// Resolve an asset id to the local file path that media analysis can read.
+    /// The default implementation mirrors `MediaResolver.expected_path`.
+    fn media_path(&self, media_ref: &str) -> Option<PathBuf> {
+        let manifest = self.media();
+        let project_dir = self.project_dir();
+        MediaResolver::new(&manifest, project_dir.as_deref()).expected_path(media_ref)
+    }
+
+    /// Decode a media asset's first audio track into the PCM format requested by
+    /// an analysis tool. Test handles can override this to inject synthetic PCM
+    /// without invoking ffmpeg.
+    fn extract_analysis_pcm(
+        &self,
+        media_ref: &str,
+        spec: PcmSpec,
+        range: Option<(f64, f64)>,
+    ) -> anyhow::Result<PcmBuffer> {
+        let path = self
+            .media_path(media_ref)
+            .ok_or_else(|| anyhow::anyhow!("media path not found for mediaRef: {media_ref}"))?;
+        extract_pcm(&path, &spec, range).map_err(|e| anyhow::anyhow!("{e}"))
+    }
 }
 
 /// Production [`CoreHandle`] over the authoritative [`AppCore`]. A clone of the