FilmMap 工作流

FilmMap 为 Agent 提供素材索引协议，不替代视觉模型或剪辑软件。一次可靠的整理流程是：确认素材范围 → 探测工具并声明 profile → 按任务规划能力 → 抽取有时间戳的证据 → 写入观察结果 → 校验索引 → 按内容和时间查询并交给剪辑。

filmmap init ./filmmap-project
filmmap profile detect --output ./filmmap-project/profile.json
filmmap artifact add ./filmmap-project/index.jsonl /media/clip.mp4
filmmap-scan.sh /media ./filmmap-project --frames 2
filmmap synthesize ./filmmap-project/index.jsonl --out ./filmmap-project/index.json
filmmap validate ./filmmap-project/index.json

filmmap install skill 安装 Agent 工作指引；filmmap install tools 安装可选 FFmpeg 辅助脚本。目录素材可通过 filmmap-scan.sh <素材目录> <工作区> [--frames] [间隔秒数] 批量登记和探测。脚本把 probe JSON 与抽帧登记为 evidence artifacts，并保留帧的源毫秒位置。内容观察可用 filmmap observe add 记录结构化 value、状态、区间和证据引用；synthesize 可生成剪辑段索引。缺少模型能力时先标为 unverified 或 unavailable，不把没有抽样到的内容写成事实。

能力 profile 与证据模型

Architecture and capability contracts

media files (read-only)
   ├── FFmpeg / metadata scripts ──┐
   └── host Agent / external AI ───┤ evidence + observations
                                   ▼
FilmMap CLI: profile → plan → stable artifact IDs → evidence observations → canonical synthesize/validate/query
                                   ▼
JSONL evidence index + portable profile (editing handoff)

Profile capability set

capabilities/catalog.json is the stable vocabulary. Each capability declares an ID, purpose, outputs and optional executable used only for local detection. A Capability Profile says which capabilities are available, unavailable, unverified, or failed in a specific environment. available requires a usable provider/executable; unverified means the capability can be supplied by an Agent/service but FilmMap did not verify it. Profiles should add provider/version, input limits, precision, languages, privacy and provenance details as they evolve. Never infer availability from a package name alone.

Profile family	Capability IDs	Outputs used by editors
Media facts	`media.probe`, `media.scene.detect`, `asset.hash.sha256`	duration, streams, shot boundaries, stable identity
Visual sampling	`media.frame.extract`, `media.contact_sheet`, `image.describe`, `image.ocr`	time-mapped frames, descriptions, visible text
Audio	`audio.extract`, `audio.transcribe`	source-aligned speech segments
Capture location	`metadata.exif.read`, `metadata.gps.read`, `geolocation.infer`	camera facts, embedded coordinates, candidate place with evidence

These names define capability semantics, not service implementations. The plan command classifies required, optional and if-available capabilities and reports precision/privacy constraint checks as satisfied, missing or unverified; it does not execute the model or benchmark output quality.

Evidence and time

Assets and derived artifacts have content SHA-256 identities. A repeated byte-identical frame shares its artifact identity while occurrences preserve every source URI, parent asset and source time. Observations use the filmmap.observation envelope with a stable ID, class, kind, producer/version, structured value, evidence artifact references, status, confidence and source time in integer milliseconds (point or half-open interval). filmmap synthesize creates a canonical revisioned JSON index, scene segments derived from interval scene descriptions, and explicit overlap conflict issues. Location candidates remain distinct from embedded GPS facts and should preserve unknowns, alternatives, and direct/contextual evidence. Queries support text filtering, asset/kind filters and millisecond bounds; they are not semantic search.

Agent extensibility

The bundled skill describes when and how to use FilmMap. The tools/ manifest provides optional scripts. Agents choose them based on the active profile and task; FilmMap does not install packages, invoke network AI, mutate source media, or silently choose an external provider.

项目画像与路线图

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