campfire-cli 0.1.25__tar.gz → 0.2.0a2__tar.gz

{campfire_cli-0.1.25 → campfire_cli-0.2.0a2}/.github/workflows/ci.yml

@@ -6,6 +6,20 @@ on:
   pull_request:
 
 jobs:
+  video:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    env:
+      PYTHONUTF8: "1"
+      HF_HUB_OFFLINE: "1"
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v10.1.0
+      - run: uv sync --frozen --extra video
+      - run: uv run --no-sync python -m pytest tests/unit/test_video.py tests/unit/test_video_runtime.py
   test:
     concurrency:
       group: ci-${{ github.workflow }}-${{ github.ref }}

{campfire_cli-0.1.25 → campfire_cli-0.2.0a2}/.github/workflows/release.yml

@@ -6,6 +6,20 @@ on:
     tags: ["v*"]
 
 jobs:
+  video:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    env:
+      PYTHONUTF8: "1"
+      HF_HUB_OFFLINE: "1"
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v10.1.0
+      - run: uv sync --frozen --extra video
+      - run: uv run --no-sync python -m pytest tests/unit/test_video.py tests/unit/test_video_runtime.py
   quality:
     strategy:
       fail-fast: false
@@ -38,7 +52,7 @@ jobs:
 
   publish:
     if: github.event_name == 'push'
-    needs: quality
+    needs: [quality, video]
     runs-on: ubuntu-latest
     permissions:
       id-token: write

{campfire_cli-0.1.25 → campfire_cli-0.2.0a2}/ARCHITECTURE.md

@@ -46,6 +46,8 @@ Task Channel 是未来演进设想，借鉴 Go 的原则：**Do not communicate
 
 ## 4. 系统架构
 
+本地视频能力由 `app/video` 承担素材准备与交付校验，`common/media` 提供模型下载、媒体解码与抽帧机制；可选原生处理依赖在独立子进程中延迟加载。`AppContainer.deliver_video` 组合文档治理检查与视频交付，不让 Video Service 调用 Document Service。文档结构仍由 `document apply` 创建，正文和二进制图片复用文件变更集及乐观锁；没有新的数据库、独立下载服务或模型调度器。语义整理留给宿主 Agent 与内置 Skill，结构检查不等于语义保真验收。
+
 ```text
 人类 / Codex / Claude Code / 其他 Agent
                   │
@@ -59,19 +61,62 @@ Task Channel 是未来演进设想，借鉴 Go 的原则：**Do not communicate
         │ document          │
         │ maintenance       │
         │ skill / base      │
+        │ video (实验能力)  │
         └─────────┬─────────┘
                   │
         Common 治理与原子能力
       schema / documents / links /
-      filesystem / database / reports
+      filesystem / database / reports / media
                   │
       ┌───────────┴───────────┐
 Markdown Workspace Adapter   用户级状态
  文档事实、任务、知识、项目    ~/.campfire/
                               campfire.db + config.yml
                               batches/reports/locks
+                              models/faster-whisper-small
+```
+
+### 本地视频模型与运行边界
+
+```text
+video setup：统一初始化预览，不联网、不落盘
+    +-- Python 环境 -> 列出 video extra 缺失依赖
+    +-- 本地模型可用 -> 计划复用，不检查远端更新
+    +-- 默认模型缺失 -> 计划列出来源、固定版本、约 486 MB 与路径
+    +-- 已有目录不完整 -> 报错，不覆盖
+    |
+    v
+一次授权 -> --expected-plan + --confirm -> 复核环境与模型计划
+    |
+    +-- 缺依赖 -> uv / 环境内 pip -> 安装到当前隔离环境
+    |
+    +-- 需下载 -> huggingface-hub -> Hugging Face（仅下载模型）
+    |                |
+    |          临时目录 -> 必要文件非空检查 -> 锁内安装
+    |                |
+    |          <CAMPFIRE_HOME>/models/faster-whisper-small
+    |                |
+    +-- 直接复用 ----+--> 离线验证依赖与模型加载 -> ready
+
+日常：本地视频 -> video prepare（预览 / 确认）
+    |
+    v
+离线媒体子进程（复用已就绪环境）
+    +-- PyAV + Pillow：解码与截图
+    +-- faster-whisper + CTranslate2：CPU int8 转写
+    |
+    v
+素材包 -> Agent 核验与整理 -> 文档 + assets
 ```
 
+`CAMPFIRE_HOME` 默认是各平台用户目录下的 `.campfire`，统一相对布局而非绝对路径；显式 `--model` 可覆盖模型位置。模型权重是用户级本地资源，Python 依赖属于 Campfire 安装环境，两者都不随 Vault 同步。公开模型下载不需要 Hugging Face Token，转写不调用云端模型；Agent 整理内容仍使用宿主自身的模型服务，不能把整条链路称为完全离线。
+
+下载失败或正常取消时清理本次临时目录，已有目录不覆盖；下载成功但后续转写失败时保留模型供重试。文件非空检查不等于模型可用性验证，实际加载由转写引擎完成。强制杀进程可能遗留临时目录，实验阶段不承诺自动恢复。
+
+Python 依赖由 `pyproject.toml` 的 `video` extra 声明，初始化从包元数据读取需求并交给包管理器解析，不复制依赖版本。`video setup` 只向当前隔离环境安装缺失的二进制依赖，固定已有版本，不重装正在运行的 Campfire；无安全安装器时返回 `needs-input`，版本冲突时停止，不擅自修改系统 Python。安装与模型下载不是跨资源事务，失败保留已完成部分，重试补齐；包管理器后续同步若移除可选依赖，可再次初始化。`prepare` 不再安装或下载，缺环境提示 `setup`。
+
+当前 CPU 路径不要求 CUDA、PyTorch、Ollama 或独立模型服务。通常使用携带 FFmpeg 库的 PyAV wheel，无需独立 FFmpeg 命令；Windows 还需要 Visual C++ 运行库，缺失时须单独安装。参考 [faster-whisper 运行要求](https://github.com/SYSTRAN/faster-whisper#requirements)与 [CTranslate2 安装要求](https://opennmt.net/CTranslate2/installation.html)。本功能为实验能力，平台路径统一不等于全部平台已验收。
+
 待人确认以全局系统受管区 `_待用户确认/` 的 `human-request` 文档为事实来源；它不属于任何 Space、Domain 或 Project。`human_decision_status` 只表达待人处理状态，用户结论随后写回正式文档。不存在独立的 Decision SQLite 状态机或 `_协作/` 投影。
 
 `app/` 按可独立理解的业务能力组织，CLI 只做参数和输出适配，Service 承担业务流程，Repository 负责外部读写。跨 App 的用例编排由组合根 `AppContainer` 承担，`setup` 与 `upgrade` 是当前实例。`common/` 只放跨业务复用、无独立业务流程的原子能力；不能为了“复用”把业务编排下沉到 common。
@@ -88,6 +133,8 @@ Frontmatter 规则采用声明式 Profile：`base` 是最小公共契约，`task
 
 ### CLI 设计理念：治理原语 + Skill SOP
 
+公共命令统一 JSON：成功时 stdout 一个对象，错误时 stderr 一个单行对象并非零退出。`--help` 与无参数帮助返回结构化参数、类型、默认值和子命令；`version` 返回版本字段，`tree` 返回嵌套命令树。不维护文本输出模式或 shell 补全脚本入口；第三方安装与下载日志由适配器捕获，不污染 JSON。
+
 Campfire 不是“Markdown 版 kubectl”，而是面向人机协作场景组合成熟 CLI 经验形成的独立设计。它在资源心智模型、`apply` 语义和机器可读接口上借鉴 kubectl，在“计划—审查—执行”上借鉴 Terraform，在稳定原语与上层工作流分离上借鉴 Git/Unix；Markdown SSOT、Agent 语义判断和显式 Maintenance 则是 Campfire 自身边界。
 
 | 参考 | Campfire 采用的部分 | Campfire 不照搬的部分 |

campfire_cli-0.2.0a2/CHANGELOG.md

@@ -0,0 +1,33 @@
+# 版本记录
+
+只记录有提交或发布证据的变化，不补写无法核实的历史。未发布条目不代表已可从 PyPI 安装。
+
+## 0.2.0a2 - 2026-10-05（Alpha 预发布）
+
+`0.2.0a1` 仅保留为未公开的本地候选标签；首次公开 Alpha 使用 `0.2.0a2`，包含最终素材目录约定。
+
+- 首个视频能力实验预发布，不承诺高可用性，须显式指定版本安装。
+- 公共输出统一为 JSON；`--help`、`version`、`tree` 不再输出文本，旧版本读取脚本需改读 JSON 字段；移除文本 shell 补全入口。
+
+- 新增可选本地视频素材、时间戳转写、候选截图与指定时间补帧能力。
+- 中间素材默认保存到 `<CAMPFIRE_HOME>/materials/<视频SHA-256>/`，支持 `--output` 覆盖；原视频不复制，交付后的图文不依赖素材目录。
+- `video setup` 一次确认安装视频依赖、准备默认模型并验证加载；`prepare` 仅处理视频。模型统一存放于 Campfire 用户目录，已有资源复用，支持显式本地路径。
+- 新增视频整理 Skill、草稿覆盖校验和受管空正文图文交付，不自动覆盖人工内容。
+- 本轮不包含视频 URL 解析或下载；Codex 已用真实本地视频完成图文链路，Claude Code 实际验收延期。
+
+## 0.1.25 - 2026-10-03
+
+- 整理公开文档与 Agent 提示词，修正旧关系页、Profile 和模板说明。
+- 增加隔离上手、安全恢复与卸载指引、贡献及反馈入口。
+- Obsidian 仅为推荐搭配，插件配置教程不在 CLI 重复维护。
+- 补充包链接和示例验证，不改变领域或文档字段模型。
+- 启用 GitHub 私密安全报告入口；独立用户试用尚未完成。
+
+## 0.1.24 - 2026-10-03
+
+- 停止生成 `_generated/相关文档-*.md`，同步时移除 MOC 自动区域的对应入口。
+- 保留 related_docs、关联查询、索引对账及 MOC 其他导航功能。
+- 同步不删除旧生成页或修改人工正文；历史清理需要独立确认。
+- 新增 CLI 进程端到端与回归测试，删除专用关系页展示接口和无调用方辅助函数。
+
+[已发布安装包](https://pypi.org/project/campfire-cli/0.1.24/)。仓库重建前的标签和 Actions 记录不再保留。

campfire_cli-0.1.25/README.md → campfire_cli-0.2.0a2/PKG-INFO

@@ -1,3 +1,30 @@
+Metadata-Version: 2.5
+Name: campfire-cli
+Version: 0.2.0a2
+Summary: Local-first shared context and governance CLI for humans and agents
+Project-URL: Repository, https://github.com/Kepler452Byte/campfire-cli
+Project-URL: Documentation, https://github.com/Kepler452Byte/campfire-cli#readme
+Project-URL: Issues, https://github.com/Kepler452Byte/campfire-cli/issues
+Project-URL: Changelog, https://github.com/Kepler452Byte/campfire-cli/blob/main/CHANGELOG.md
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: alembic>=1.13
+Requires-Dist: packaging>=24
+Requires-Dist: psutil>=7.2.2
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: typer>=0.12
+Provides-Extra: video
+Requires-Dist: av<19,>=14; extra == 'video'
+Requires-Dist: faster-whisper<2,>=1.1; extra == 'video'
+Requires-Dist: huggingface-hub<2,>=0.24; extra == 'video'
+Requires-Dist: markdown-it-py>=3; extra == 'video'
+Requires-Dist: pillow>=11; extra == 'video'
+Description-Content-Type: text/markdown
+
 # Campfire
 
 `campfire` 是面向工作与学习场景的本地优先人机协作 CLI。它让人类和多个 Agent 围绕同一份持久共享上下文协作：把口头要求、临时笔记、任务进度、项目资料和长期知识沉淀进可检索、可交接、可审计的 Workspace。
@@ -18,6 +45,28 @@
 
 推荐搭配 Obsidian：内置 Bases 展示表格，大纲提供章节导航；Kanban 用于看板，Obsidian Git 用于版本历史。它们不是普通文档查询和治理的前提。Templater、TOC 不作为依赖。插件配置教程等待维护者提供博客链接，不在 CLI 输出或仓库重复编写，也不自动修改插件设置。
 
+## 本地视频图文（v0.2.0a2 Alpha 实验能力）
+
+本版统一公共 CLI 输出：成功在 stdout 返回一个 JSON 对象，错误在 stderr 返回一个 JSON 对象并以非零状态退出。`--help` 返回结构化参数，`tree` 返回层级命令树，`version` 返回 `{"status":"ok","version":"0.2.0a2"}`。旧脚本若将版本输出当纯字符串读取，须改读 `version` 字段；不再提供文本帮助或 shell 补全脚本输出。
+
+试用预发布版：`uv tool install "campfire-cli==0.2.0a2"`；已有 uv tool 安装可用 `uv tool upgrade "campfire-cli==0.2.0a2"`。Alpha 不是正式稳定版本，不建议替换重要工作环境；先在独立测试目录验收。
+
+本功能按实验性质逐步推进，不承诺高可用性、所有媒体兼容性或自动整理结果的准确性；生成内容须经人工或 Agent 核验。实验阶段仍保留只读来源、写入预览和冲突保护。
+
+本轮只接受本地单视频，不解析抖音、B站或其他 URL。核心 CLI 不依赖视频运行库；首次使用执行 `campfire video setup`，统一预览缺失依赖与默认模型下载，带回 `--expected-plan <摘要> --confirm` 后一次完成安装和模型加载验证。无需 Workspace 或输入视频。视频由 PyAV 解码，无需额外安装 FFmpeg 命令；语音由 faster-whisper 在 CPU 本地转写。PyAV 暂限 `<19`，避免其删除的 `metadata_errors` 参数与当前转写库冲突。
+
+初始化后运行 `campfire video prepare --source <本地视频> --output <Workspace外新目录>` 预览，带回 `--expected-plan` 和 `--confirm` 处理。`prepare` 不再安装依赖或下载模型，缺失时提示 `video setup`。默认模型位于 `<CAMPFIRE_HOME>/models/faster-whisper-small`，主目录默认 `~/.campfire`，Windows、macOS、Linux 沿用同一相对布局。初始化预览列出 Python 环境、缺失依赖、Hugging Face 固定版本、约 486 MB 模型体积及目标目录；确认后先安装再下载，最后在离线子进程中验证加载。已有依赖和模型复用，不静默更新模型，不上传媒体。
+
+依赖安装只支持当前 uv tool、pipx 或 venv 隔离环境，通过可用的 uv 或环境内 pip 安装二进制包；不修改系统 Python，不重装运行中的 Campfire，不替换已有包。无可用安装器时返回 `needs-input`；版本冲突或缺少兼容 wheel 时停止，由用户按原安装方式修复后重试。安装中断时保留已完成部分，不回滚卸载；正常下载失败清理本次模型临时目录，下载成功但验证失败则保留模型并报告错误。包管理器升级或同步后若移除了可选依赖，重新执行 `video setup` 补齐。源码开发者仍可用 `uv sync --extra video` 管理锁定依赖，再用 `video setup` 验证模型。
+
+可用 `--model <本地模型目录>` 覆盖默认位置；显式路径缺失或不完整时只报错，不下载或覆盖。已有默认目录不完整时也拒绝覆盖。也可用 `--transcript` 提供时间戳 JSON 数组，格式见命令帮助，此时不需要模型。模型权重目录须含非空的 `model.bin`、`config.json`、`tokenizer.json`；配置与权重能否实际加载仍由转写引擎校验。
+
+内置 `campfire-video-capture` Skill 引导 Agent 阅读全部转写、查看候选截图、用 `video frames` 补帧并整理草稿。`video inspect` 校验结构和引用，不能证明内容保真；`video deliver` 向已通过治理检查且正文为空的文档交付正文及图片。沿用 `document apply` 创建结构，不覆盖已有人工内容，不自动处理重复来源。
+
+默认限制为 4 GiB、2 小时、240 张截图、单次处理 3 小时，默认每 30 秒候选抽帧，超长素材按帧数上限增大间隔；配置在内置 `config.yml` 的 `video` 分区。只支持本地 MP4/MOV、Matroska/WebM、AVI、MPEG-TS 容器，具体解码依赖所装 PyAV。截图稀疏采样加精确像素去重，不保证捕获短暂画面，必须按内容补帧。
+
+`prepare` 可省略 `--output`，素材默认保存到 `<CAMPFIRE_HOME>/materials/<视频SHA-256>/`，预览返回实际目录；显式指定时仍须为 Workspace 外的新目录。同一视频已有素材时拒绝覆盖，可复用素材或指定其他目录重新处理。素材目录包含转写与候选图片，保留用于核验，不自动过期；用户确认后可删除指定素材目录。原视频只读且不复制，Vault 仅接收选定图片与正文，交付后不依赖素材目录。模型权重及媒体内容各自的许可由使用者核对；PyAV/FFmpeg 许可随安装构建而异，本项目不捆绑模型或独立 FFmpeg 可执行文件。
+
 ## 安装
 
 ### 升级注意事项

campfire_cli-0.1.25/PKG-INFO → campfire_cli-0.2.0a2/README.md

@@ -1,23 +1,3 @@
-Metadata-Version: 2.5
-Name: campfire-cli
-Version: 0.1.25
-Summary: Local-first shared context and governance CLI for humans and agents
-Project-URL: Repository, https://github.com/Kepler452Byte/campfire-cli
-Project-URL: Documentation, https://github.com/Kepler452Byte/campfire-cli#readme
-Project-URL: Issues, https://github.com/Kepler452Byte/campfire-cli/issues
-Project-URL: Changelog, https://github.com/Kepler452Byte/campfire-cli/blob/main/CHANGELOG.md
-License-Expression: MIT
-License-File: LICENSE
-Requires-Python: >=3.12
-Requires-Dist: alembic>=1.13
-Requires-Dist: psutil>=7.2.2
-Requires-Dist: pydantic-settings>=2.2
-Requires-Dist: pydantic>=2.7
-Requires-Dist: pyyaml>=6.0
-Requires-Dist: sqlalchemy>=2.0
-Requires-Dist: typer>=0.12
-Description-Content-Type: text/markdown
-
 # Campfire
 
 `campfire` 是面向工作与学习场景的本地优先人机协作 CLI。它让人类和多个 Agent 围绕同一份持久共享上下文协作：把口头要求、临时笔记、任务进度、项目资料和长期知识沉淀进可检索、可交接、可审计的 Workspace。
@@ -38,6 +18,28 @@ Description-Content-Type: text/markdown
 
 推荐搭配 Obsidian：内置 Bases 展示表格，大纲提供章节导航；Kanban 用于看板，Obsidian Git 用于版本历史。它们不是普通文档查询和治理的前提。Templater、TOC 不作为依赖。插件配置教程等待维护者提供博客链接，不在 CLI 输出或仓库重复编写，也不自动修改插件设置。
 
+## 本地视频图文（v0.2.0a2 Alpha 实验能力）
+
+本版统一公共 CLI 输出：成功在 stdout 返回一个 JSON 对象，错误在 stderr 返回一个 JSON 对象并以非零状态退出。`--help` 返回结构化参数，`tree` 返回层级命令树，`version` 返回 `{"status":"ok","version":"0.2.0a2"}`。旧脚本若将版本输出当纯字符串读取，须改读 `version` 字段；不再提供文本帮助或 shell 补全脚本输出。
+
+试用预发布版：`uv tool install "campfire-cli==0.2.0a2"`；已有 uv tool 安装可用 `uv tool upgrade "campfire-cli==0.2.0a2"`。Alpha 不是正式稳定版本，不建议替换重要工作环境；先在独立测试目录验收。
+
+本功能按实验性质逐步推进，不承诺高可用性、所有媒体兼容性或自动整理结果的准确性；生成内容须经人工或 Agent 核验。实验阶段仍保留只读来源、写入预览和冲突保护。
+
+本轮只接受本地单视频，不解析抖音、B站或其他 URL。核心 CLI 不依赖视频运行库；首次使用执行 `campfire video setup`，统一预览缺失依赖与默认模型下载，带回 `--expected-plan <摘要> --confirm` 后一次完成安装和模型加载验证。无需 Workspace 或输入视频。视频由 PyAV 解码，无需额外安装 FFmpeg 命令；语音由 faster-whisper 在 CPU 本地转写。PyAV 暂限 `<19`，避免其删除的 `metadata_errors` 参数与当前转写库冲突。
+
+初始化后运行 `campfire video prepare --source <本地视频> --output <Workspace外新目录>` 预览，带回 `--expected-plan` 和 `--confirm` 处理。`prepare` 不再安装依赖或下载模型，缺失时提示 `video setup`。默认模型位于 `<CAMPFIRE_HOME>/models/faster-whisper-small`，主目录默认 `~/.campfire`，Windows、macOS、Linux 沿用同一相对布局。初始化预览列出 Python 环境、缺失依赖、Hugging Face 固定版本、约 486 MB 模型体积及目标目录；确认后先安装再下载，最后在离线子进程中验证加载。已有依赖和模型复用，不静默更新模型，不上传媒体。
+
+依赖安装只支持当前 uv tool、pipx 或 venv 隔离环境，通过可用的 uv 或环境内 pip 安装二进制包；不修改系统 Python，不重装运行中的 Campfire，不替换已有包。无可用安装器时返回 `needs-input`；版本冲突或缺少兼容 wheel 时停止，由用户按原安装方式修复后重试。安装中断时保留已完成部分，不回滚卸载；正常下载失败清理本次模型临时目录，下载成功但验证失败则保留模型并报告错误。包管理器升级或同步后若移除了可选依赖，重新执行 `video setup` 补齐。源码开发者仍可用 `uv sync --extra video` 管理锁定依赖，再用 `video setup` 验证模型。
+
+可用 `--model <本地模型目录>` 覆盖默认位置；显式路径缺失或不完整时只报错，不下载或覆盖。已有默认目录不完整时也拒绝覆盖。也可用 `--transcript` 提供时间戳 JSON 数组，格式见命令帮助，此时不需要模型。模型权重目录须含非空的 `model.bin`、`config.json`、`tokenizer.json`；配置与权重能否实际加载仍由转写引擎校验。
+
+内置 `campfire-video-capture` Skill 引导 Agent 阅读全部转写、查看候选截图、用 `video frames` 补帧并整理草稿。`video inspect` 校验结构和引用，不能证明内容保真；`video deliver` 向已通过治理检查且正文为空的文档交付正文及图片。沿用 `document apply` 创建结构，不覆盖已有人工内容，不自动处理重复来源。
+
+默认限制为 4 GiB、2 小时、240 张截图、单次处理 3 小时，默认每 30 秒候选抽帧，超长素材按帧数上限增大间隔；配置在内置 `config.yml` 的 `video` 分区。只支持本地 MP4/MOV、Matroska/WebM、AVI、MPEG-TS 容器，具体解码依赖所装 PyAV。截图稀疏采样加精确像素去重，不保证捕获短暂画面，必须按内容补帧。
+
+`prepare` 可省略 `--output`，素材默认保存到 `<CAMPFIRE_HOME>/materials/<视频SHA-256>/`，预览返回实际目录；显式指定时仍须为 Workspace 外的新目录。同一视频已有素材时拒绝覆盖，可复用素材或指定其他目录重新处理。素材目录包含转写与候选图片，保留用于核验，不自动过期；用户确认后可删除指定素材目录。原视频只读且不复制，Vault 仅接收选定图片与正文，交付后不依赖素材目录。模型权重及媒体内容各自的许可由使用者核对；PyAV/FFmpeg 许可随安装构建而异，本项目不捆绑模型或独立 FFmpeg 可执行文件。
+
 ## 安装
 
 ### 升级注意事项

{campfire_cli-0.1.25 → campfire_cli-0.2.0a2}/SPEC.md

@@ -41,7 +41,7 @@ SQLite / Filesystem Implementation
 
 ## CLI 输出契约
 
-- 正常输出 indent JSON；错误输出单行 JSON 并写 stderr，退出码非 0。
+- 所有公共命令成功时 stdout 只输出一个 indent JSON 对象，包括 `--help`、无参数帮助、`version` 与 `tree`；错误只输出一个单行 JSON 对象到 stderr，退出码非 0。帮助使用参数结构，命令树使用层级结构，不返回 ANSI 文本。第三方日志须捕获，不混入命令输出；不提供第二套文本模式或 shell 补全脚本输出入口。
 - `status` 字段是 Agent 依赖的公共契约，只允许复用既有词汇，不得发明近义词。命令级词汇：ok、error、blocked、needs-input、needs-review、dry-run、synced、planned、ready、applied、moved、renamed、issues-found、formatted、archived、up-to-date。文档、领域与 Decision 各有自己的字段词汇表。需要新状态先在本节登记。
 - 可恢复的输入错误必须包含稳定 `code`、对应字段和机器可读的期望类型；当正确序列化方式不直观时，同时返回示例值或修复提示。自然语言 message 与示例可以演进，不作为调用方分支判断依据。
 - 前置条件缺失时优先降级执行：能完成的部分照常完成，输出 `needs-input` 并以 `skipped` 字段显式列出被跳过的步骤，而非整体报错退出。
@@ -81,6 +81,7 @@ Campfire 使用语义化版本：
 ```
 
 - 已发布版本不可原地修改；同一版本号必须对应唯一、可重复构建的代码和资源。
+- Python 预发布遵循 PEP 440，例如 `0.2.0a1` 对应标签 `v0.2.0a1`；GitHub Release 标记为 prerelease，版本比较使用标准解析器，不按字符串比较。
 - 已公开标签对象不可变。发布准备必须执行 `scripts/release_check.py --tag <tag>` 对比本地、远端对象及目标提交；对象或提交不一致即停止，禁止重建、强推或自动覆盖本地标签。发布重试复用原标签，不以提交相同为理由替换附注对象。
 - 只修复既有行为时增加补丁版本，例如 `0.17.0 -> 0.17.1`。
 - 新增 CLI 能力、改变治理契约或增加可选公共字段时增加次版本，例如 `0.17.x -> 0.18.0`。

{campfire_cli-0.1.25 → campfire_cli-0.2.0a2}/pyproject.toml

@@ -1,12 +1,13 @@
 [project]
 name = "campfire-cli"
-version = "0.1.25"
+version = "0.2.0a2"
 description = "Local-first shared context and governance CLI for humans and agents"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.12"
 dependencies = [
   "alembic>=1.13",
+  "packaging>=24",
   "psutil>=7.2.2",
   "pydantic>=2.7",
   "pydantic-settings>=2.2",
@@ -21,6 +22,9 @@ Documentation = "https://github.com/Kepler452Byte/campfire-cli#readme"
 Issues = "https://github.com/Kepler452Byte/campfire-cli/issues"
 Changelog = "https://github.com/Kepler452Byte/campfire-cli/blob/main/CHANGELOG.md"
 
+[project.optional-dependencies]
+video = ["av>=14,<19", "Pillow>=11", "faster-whisper>=1.1,<2", "huggingface-hub>=0.24,<2", "markdown-it-py>=3"]
+
 [project.scripts]
 campfire = "campfire_cli.main:app"
 

{campfire_cli-0.1.25 → campfire_cli-0.2.0a2}/scripts/pypi_verify.py

@@ -9,6 +9,7 @@ side_effects:
 from __future__ import annotations
 
 import argparse
+import json
 import os
 import subprocess
 import tempfile
@@ -50,7 +51,8 @@ def verify(version: str, environment: Path) -> None:
         capture_output=True,
         text=True,
         timeout=30,
-    ).stdout.strip()
+    ).stdout
+    installed = json.loads(installed)["version"]
     if installed != version:
         raise SystemExit(f"installed version {installed} does not match {version}")
 

{campfire_cli-0.1.25 → campfire_cli-0.2.0a2}/scripts/quality_check.py

@@ -73,7 +73,8 @@ def smoke_test_wheel(version: str, artifact_dir: Path | None = None) -> None:
             capture_output=True,
             text=True,
             env=smoke_environment,
-        ).stdout.strip()
+        ).stdout
+        installed = json.loads(installed)["version"]
         if installed != version:
             raise SystemExit(f"installed version {installed} does not match {version}")
         subprocess.run(

{campfire_cli-0.1.25 → campfire_cli-0.2.0a2}/src/campfire_cli/__init__.py

@@ -1,3 +1,3 @@
 """Campfire CLI package."""
 
-__version__ = "0.1.25"
+__version__ = "0.2.0a2"

{campfire_cli-0.1.25 → campfire_cli-0.2.0a2}/src/campfire_cli/app/SPEC.md

@@ -9,3 +9,4 @@
 - `workspace/`：注册、初始化、解析和选择多个 Workspace，并通过扁平的 Restructure Service 执行一次性、大规模、批次化结构重构。
 - `skill/`：Campfire SOP Skill 的发现、加载、校验和同步。
 - `base/`：Obsidian Base 标准治理视图。
+- `video/`：实验性的本地视频素材准备、草稿校验与图文交付。

campfire_cli-0.2.0a2/src/campfire_cli/app/video/SPEC.md

@@ -0,0 +1,13 @@
+# Video App SPEC
+
+本模块提供实验性的本地视频素材准备、草稿校验与图文交付，不承诺高可用性或自动内容保真，不解析在线链接。
+
+- `cli/` 解析参数与翻译异常；跨 App 的文档治理检查由 `AppContainer` 编排。
+- `schema/` 定义素材与草稿的数据契约；`service/` 负责预览、校验、审批及安全写入用例。
+- `service/video_protocol.py` 定义消费方媒体接口；`common/media/` 实现隔离进程、解码、抽帧和本地语音转写，不解释文档治理规则。
+- 可选媒体依赖在处理时加载；不隐式下载模型，不上传视频，不修改来源，不覆盖已有正文。
+- `video setup` 是视频环境唯一初始化入口：依赖安装与默认模型下载纳入一次预览和确认，最后通过离线子进程验证实际加载。已有部分复用，失败不卸载已安装依赖。`prepare` 仅处理视频，缺环境提示初始化，不安装或下载。
+- Python 依赖从包元数据的 `video` extra 读取，禁止复制依赖清单。只在当前隔离环境安装缺失的二进制包，固定已有版本，不重装 Campfire 或自动修改系统 Python；无法安全安装时停止并报告。
+- 模型默认位于 Campfire 用户目录的 `models/<模型仓库名>/`，支持 `CAMPFIRE_HOME` 与处理时显式 `--model`。下载到临时目录，必要文件非空后锁内安装；不覆盖已有目录。验证失败保留模型并报告，已有本地模型直接离线使用。
+- 实验性质不降低路径、哈希、写入确认与冲突保护要求。结构校验不代替 Agent 对转写和图片的语义核验。
+- 中间素材默认存放于 `<CAMPFIRE_HOME>/materials/<视频SHA-256>/`，`--output` 可指定 Workspace 外的新目录；预览不创建目录，已有素材不覆盖、不自动清理。原视频只读且不复制；最终正文和选定图片交付到 Vault 后不依赖中间素材目录。

campfire_cli-0.2.0a2/src/campfire_cli/app/video/cli/video_cli.py

@@ -0,0 +1,125 @@
+from collections.abc import Callable
+from pathlib import Path
+
+import typer
+
+from campfire_cli.common.cli_output import JsonTyperGroup, emit
+from campfire_cli.common.cli_output import invoke as invoke_app
+from campfire_cli.common.exceptions import InputError
+from campfire_cli.container import AppContainer
+
+video_cli = typer.Typer(help="本地视频素材与保真图文交付，不解析 URL", cls=JsonTyperGroup)
+
+
+def invoke(operation: Callable[[], dict]) -> dict:
+    def guarded() -> dict:
+        try:
+            return operation()
+        except (OSError, UnicodeError) as exc:
+            raise InputError(
+                "视频文件操作失败，请检查路径、权限和 UTF-8 编码",
+                code="video-io-error",
+                field="path",
+                expected_type="accessible local path",
+                detail=str(exc),
+            ) from exc
+
+    return invoke_app(guarded)
+
+
+@video_cli.command("setup")
+def setup(
+    expected_plan: str | None = typer.Option(None, help="初始化预览返回的计划摘要"),
+    confirm: bool = typer.Option(False, help="确认安装缺失视频依赖、下载默认模型并验证加载"),
+) -> None:
+    """一次启用视频能力；已有依赖和模型直接复用，不要求 Workspace。"""
+    emit(
+        invoke(
+            lambda: AppContainer.build_video().setup(
+                confirm=confirm,
+                expected_plan=expected_plan,
+            )
+        )
+    )
+
+
+@video_cli.command("prepare")
+def prepare(
+    source: Path = typer.Option(..., help="只读本地视频路径，不接受 URL"),
+    output: Path | None = typer.Option(
+        None, help="Workspace 外尚不存在的素材目录；默认 <CAMPFIRE_HOME>/materials/<视频SHA-256>"
+    ),
+    model: Path | None = typer.Option(
+        None,
+        help="本地模型目录；默认使用 video setup 准备的模型，缺失时提示初始化",
+    ),
+    transcript: Path | None = typer.Option(
+        None, help='UTF-8 JSON 数组，如 [{"start":0,"end":1,"text":"文字"}]；秒为单位'
+    ),
+    expected_plan: str | None = typer.Option(None, help="预览返回的计划摘要"),
+    confirm: bool = typer.Option(False, help="按预览计划处理视频，不安装依赖或下载模型"),
+) -> None:
+    emit(
+        invoke(
+            lambda: AppContainer.build_video().prepare(
+                source,
+                output,
+                model=model,
+                transcript=transcript,
+                expected_plan=expected_plan,
+                confirm=confirm,
+            )
+        )
+    )
+
+
+@video_cli.command("inspect")
+def inspect(
+    bundle: Path = typer.Option(..., help="包含 material.json 的素材目录"),
+    draft: Path | None = typer.Option(None, help="可选草稿 JSON；校验覆盖与图片引用"),
+) -> None:
+    emit(invoke(lambda: AppContainer.build_video().inspect(bundle, draft)))
+
+
+@video_cli.command("frames")
+def frames(
+    source: Path = typer.Option(..., help="原始本地视频，须与素材哈希一致"),
+    bundle: Path = typer.Option(..., help="已有素材目录"),
+    at: list[float] = typer.Option(..., help="补帧秒数，可重复 --at"),
+    expected_plan: str | None = typer.Option(None, help="预览返回的计划摘要"),
+    confirm: bool = typer.Option(False, help="按预览计划补帧"),
+) -> None:
+    emit(
+        invoke(
+            lambda: AppContainer.build_video().frames(
+                source,
+                bundle,
+                at,
+                confirm=confirm,
+                expected_plan=expected_plan,
+            )
+        )
+    )
+
+
+@video_cli.command("deliver")
+def deliver(
+    ctx: typer.Context,
+    bundle: Path = typer.Option(..., help="素材目录"),
+    draft: Path = typer.Option(..., help="经 Agent 整理的草稿 JSON，格式见内置视频 Skill"),
+    path: str = typer.Option(..., help="Workspace 内已有的受管空正文文档路径"),
+    expected_plan: str | None = typer.Option(None, help="预览返回的计划摘要"),
+    confirm: bool = typer.Option(False, help="按预览计划写入正文及图片"),
+) -> None:
+    workspace = ctx.find_root().params.get("workspace")
+    emit(
+        invoke(
+            lambda: AppContainer.build(workspace).deliver_video(
+                bundle,
+                draft,
+                path,
+                confirm=confirm,
+                expected_plan=expected_plan,
+            )
+        )
+    )

campfire_cli-0.2.0a2/src/campfire_cli/app/video/schema/video_schema.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class Contract(BaseModel):
+    model_config = ConfigDict(extra="forbid", allow_inf_nan=False)
+
+
+class Segment(Contract):
+    start: float = Field(ge=0)
+    end: float = Field(gt=0)
+    text: str = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def interval(self) -> Segment:
+        if self.end <= self.start or not self.text.strip():
+            raise ValueError("转写区间必须递增且文字不能为空")
+        return self
+
+
+class Frame(Contract):
+    id: str
+    path: str
+    seconds: float = Field(ge=0)
+    sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+
+
+class Material(Contract):
+    schema_version: Literal[1] = 1
+    source_name: str
+    source_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    duration: float = Field(gt=0)
+    width: int = Field(gt=0)
+    height: int = Field(gt=0)
+    transcript_source: str
+    segments: list[Segment]
+    frames: list[Frame]
+    warnings: list[str] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def timeline(self) -> Material:
+        if any(s.end > self.duration + 0.5 for s in self.segments):
+            raise ValueError("转写超出媒体时长")
+        if any(a.start > b.start for a, b in zip(self.segments, self.segments[1:], strict=False)):
+            raise ValueError("转写必须按时间排序")
+        if any(f.seconds > self.duration + 0.5 for f in self.frames):
+            raise ValueError("截图超出媒体时长")
+        if len({f.id for f in self.frames}) != len(self.frames):
+            raise ValueError("截图 ID 重复")
+        return self
+
+
+class Section(Contract):
+    title: str = Field(min_length=1)
+    body: str = Field(min_length=1)
+    segment_ids: list[int] = Field(default_factory=list)
+    frame_ids: list[str] = Field(default_factory=list)
+
+
+class Draft(Contract):
+    title: str = Field(min_length=1)
+    source_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    sections: list[Section] = Field(min_length=1)
+    limitations: list[str] = Field(default_factory=list)
+    visual_reviewed: bool = False

campfire_cli-0.2.0a2/src/campfire_cli/app/video/service/video_protocol.py

@@ -0,0 +1,16 @@
+from pathlib import Path
+from typing import Protocol
+
+
+class MediaBackend(Protocol):
+    def run(self, request: dict, timeout: int) -> dict: ...
+
+
+class ModelDownloader(Protocol):
+    def __call__(self, repository: str, revision: str, output: Path) -> None: ...
+
+
+class VideoRuntime(Protocol):
+    def plan(self) -> dict: ...
+
+    def install(self, plan: dict, timeout: int) -> None: ...