项目画像与路线图

FilmMap 项目画像与方向

项目概述

FilmMap 把分散的媒体文件、分析能力和 Agent 观察结果组织成可复用、可检索、证据可追溯的剪辑素材索引。它面向剪辑师和负责素材整理/检索的 Agent，交付稳定的 profile、索引协议、Rust CLI、辅助工具脚本和专用 skill。

素材 + 外部分析工具/Agent → 能力 profile 与任务计划 → 带证据索引 → 时间范围/内容检索 → 剪辑交接

当前首次实现位于 CLI、capabilities/catalog.json、tools/ 和 skills/filmmap/；当前实现事实以仓库代码和可运行 E2E 为准。

项目画像（目标状态）

完成后，FilmMap 应让新的 Agent 不必依赖前次对话，就能识别环境能力、选择适合的抽帧/画面理解/定位工具、区分事实和推断、按原始媒体时间精准找到镜头，并将索引交接给后续剪辑。跨机器数据可交换、查询结果可回到源素材和证据；缺失能力和不确定结论明确可见。

质量优先级：证据和源时间准确性 → 可重复运行与可移交 → Agent 工作流效率 → 性能 → 表面简洁。Rust CLI 负责高频本地流程和稳定数据合同；FFmpeg、OCR、ASR、视觉模型、地理编码及剪辑器作为外部能力，通过 profile 声明，避免 FilmMap 绑定某个模型或重复实现成熟工具。

当前能力清单

CLI 工作区与能力词汇：filmmap init、filmmap capability list；入口 src/main.rs，词汇源 capabilities/catalog.json。
本机工具 profile：profile detect 检查外部可执行程序，Agent/服务能力标记为 unverified；profile 可校验。
需求规划：filmmap plan 支持 required/optional/if_available 能力级别，并为显式声明的本地处理和时间精度约束输出满足/缺失/未验证状态。当前不做模型服务的真实探测或质量基准。
素材与观察索引：素材 SHA-256 ID、派生 artifact 和同内容多源位置 occurrences；观察记录支持事实/测量/推断类别、候选状态、结构化 value、来源版本、毫秒点/半开区间、证据 artifact 引用。synthesize 生成带稳定 revision 的 canonical JSON，校验引用并报告重叠冲突；查询可按文本、素材、类型和毫秒范围过滤。
Agent 与外部工具扩展：独立 skill、批量目录扫描/ffprobe/抽帧脚本及安装入口；扫描会把 probe JSON 和抽取帧注册为证据 artifacts，并保留帧源时间映射。
分发与文档工作流：Rust CI、mdBook、Release 构建配置；是否真实发布以 GitHub Release 记录为准。

非目标（铁律）

FilmMap 不实现或内置视觉理解、OCR、ASR、地理编码等专有/通用 AI 服务；它定义能力合同并编排 Agent 可用能力。
FilmMap 不替代专业视频编辑器，也不自动做创作决策或生成最终剪辑成片。
FilmMap 不修改、转码或删除用户源素材；衍生媒体必须是显式新 artifact。
FilmMap 不把单一云服务、模型供应商或剪辑软件设为索引读取的前置条件。

方向与意图

高效定位镜头：让剪辑者以人物、动作、环境、地点、台词、时间等条件检索，并返回源文件和可直接复查的时间范围。服务于时间准确与可移交。
跨工具协作：稳定 schema、profile 与导出合同可供多种 Agent、索引器和编辑工具消费。服务于供应商无关和复用。
渐进式证据质量：从元数据到抽帧/转录/地点推断，每个结论能关联证据和置信度；遇到冲突保留多个候选。服务于事实可信。
可验证发行：各支持平台可安装相同 CLI 和 skill，发布资产可校验，并有 mdBook 使用说明。

完成的样子

不同 Agent/机器能用 profile 判断能力、针对任务生成可解释计划，分析后可按时间和语义定位到原始片段；索引的事实、推断、来源、未知与冲突均能区分。真实 CLI E2E 覆盖完整用户路径，打包产物和安装脚本能从干净环境验证。

验收矩阵（业务能力覆盖矩阵）

硬性覆盖底线：每个一级功能至少一条 happy-path E2E；高风险功能至少一条失败路径；涉及权限的功能至少两种角色；会修改系统状态的操作验证失败恢复或回滚；新增一级功能必须增加 E2E 并更新本表。完整证据列只填写真实存在的测试。

一级功能	风险	Happy path E2E	失败路径	权限角色覆盖	失败恢复/回滚	证据
工作区初始化与素材登记	中	✅	✅	不适用：本地 CLI 无角色权限模型	✅ CLI E2E 重新运行并验证已有项目完整；不可读文件失败后索引不变	`tests/e2e/cli.sh`, `tests/e2e/scan.sh`
Profile 探测、校验与需求规划	中	✅	✅	不适用：本地 CLI 无角色权限模型	不适用：profile 检查和 plan 只读	`tests/e2e/cli.sh`
观察写入、canonical 合成、证据引用与检索	中	✅	✅ 缺坏引用拒绝的独立断言待补	不适用：本地 CLI 无角色权限模型	冲突保留并显式报告；不可读素材失败后索引不变	`tests/e2e/cli.sh`
批量扫描、抽帧映射与同内容多位置	中	✅	❌ 部分 FFmpeg 失败恢复覆盖待补	不适用：本地 CLI 无角色权限模型	重复内容记录为 occurrence，不丢失时间点	`tests/e2e/scan.sh`
Skill/工具安装	中	✅ 自定义目录	✅ 冲突时拒绝覆盖	不适用：安装到调用者指定的本地目录	✅ 冲突失败后已有文件保持不变	`tests/e2e/cli.sh`
发布资产和平台安装	高	❌ 缺口：需在干净平台验证安装与 checksum	❌ 缺口	不适用：公开下载，无仓库内用户角色授权	不适用：当前无自动系统升级/卸载操作	`.github/workflows/release.yml`（配置，不代表已发布验收）

默认用户目录安装仍需在各 Agent 宿主中人工确认集成位置。实现成熟度以此表和每次验证更新。未覆盖项目保持缺口，不能因代码或工作流文件存在就标记为已验收。

Keyboard shortcuts

FilmMap