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

campfire_cli-0.2.0a2/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,18 @@
+---
+name: Bug report
+about: Report a reproducible problem without private data
+title: ''
+labels: ''
+assignees: ''
+---
+
+## 环境
+Campfire、Python、操作系统和安装方式：
+
+## 最小复现
+使用虚构路径、文档和命令，不上传真实 Vault、数据库、公司资料或凭据。
+
+## 预期与实际
+提供脱敏 JSON 和退出码：
+
+安全问题不要在此提交细节，先阅读 SECURITY.md。

campfire_cli-0.2.0a2/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,15 @@
+---
+name: Feature request
+about: Explain a concrete workflow and its missing capability
+title: ''
+labels: ''
+assignees: ''
+---
+
+## 实际场景与问题
+
+## 现有命令或方案为何不够
+
+## 期望结果与不涉及的范围
+
+请使用脱敏示例，不上传公司资料。

campfire_cli-0.2.0a2/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,10 @@
+## 动机与范围
+
+## 变更及兼容性
+
+## 验证证据
+- [ ] 已阅读 SPEC.md
+- [ ] 测试使用隔离目录，没有修改真实 Vault 或全局 Agent 配置
+- [ ] 已运行相关测试，列明未验证内容
+- [ ] 文档、命令示例与实现一致
+- [ ] 不包含凭据、私人数据或无权公开的代码

{campfire_cli-0.1.24 → 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.24 → 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.24 → campfire_cli-0.2.0a2}/ARCHITECTURE.md

@@ -18,9 +18,9 @@ Campfire 当前不负责 Agent 调度、实时消息推送或替代 Jira/Notion
 - **Project**：Workspace 连接的外部工作资源，关联代码仓库、本地路径和一个项目根 Domain。
 - **Participant**：参与协作的人类或 Agent。
 - **Document**：知识、项目、决策、计划、问题、记录等持久内容。
-- **Task Channel**：围绕一项任务持续记录负责人、状态、进展、阻塞、交接、结果和验收的异步协作通道。
+- **Task Channel（演进设想，非已实现协议）**：围绕一项任务持续记录负责人、状态、进展、阻塞、交接、结果和验收的异步协作通道。
 - **Inbox Item**：尚未完成归属、类型或意图判断的输入，以及需要人类确认的问题。
-- **Human request**：Agent 需要人类确认的 Markdown 事项，位于全局收件箱并以 Frontmatter 状态跟踪。
+- **Human request**：Agent 需要人类确认的 Markdown 事项，位于 `_待用户确认/` 并以 Frontmatter 状态跟踪。
 - **Generated View**：由事实数据生成的 MOC、Base、报告和索引，不由人手重复维护。
 
 ## 3. 业务架构
@@ -42,10 +42,12 @@ Campfire 当前不负责 Agent 调度、实时消息推送或替代 Jira/Notion
 
 Domain 由声明而不是目录名称决定；`任务/`、`记录/`、`assets/` 等普通目录可按需要成为 Domain，但文档类型不强制绑定同名目录。以下划线开头的 `_xxx/` 统一表示治理基础设施，不能声明为 Space 或 Domain；MOC 保留领域导航，Base 使用 `_治理视图/`；不再生成 `_generated/` 关系页。归档是 `document_status=archived`，不对应特殊物理目录。
 
-Task Channel 借鉴 Go 的原则：**Do not communicate by sharing memory; instead, share memory by communicating.** 多个参与者不依赖各自会话中的隐式记忆，而是通过明确的任务状态与事件共享上下文。它是持久异步 Channel，不承诺实时唤醒；外部 Agent 运行时可在其上增加通知和调度。
+Task Channel 是未来演进设想，借鉴 Go 的原则：**Do not communicate by sharing memory; instead, share memory by communicating.** 多个参与者不依赖各自会话中的隐式记忆，而是通过明确的任务状态与事件共享上下文。它是持久异步 Channel，不承诺实时唤醒；外部 Agent 运行时可在其上增加通知和调度。
 
 ## 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 by sharing memory; inste
         │ 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 不照搬的部分 |
@@ -159,7 +206,7 @@ Campfire 不把“调用方能够猜对未声明契约”作为可靠性前提
 | Workspace、Project 本机路径绑定 | `~/.campfire/campfire.db` | 本机 CLI 命令 |
 | Campfire Skills | Python 包内 `resources/skills/` | 全局 Agent Skill 目录 |
 | 文档查询索引 | Workspace Markdown、结构声明与有效治理契约 | `~/.campfire/campfire.db` 中按 `workspace_id` 隔离的可重建投影 |
-| Decision、结构重构批次和维护运行状态 | `~/.campfire/campfire.db` | Markdown 投影、报告与有限变更日志；当前不能仅从 Workspace 重建 |
+| 结构重构批次和维护运行状态 | `~/.campfire/campfire.db` | Markdown 投影、报告与有限变更日志；当前不能仅从 Workspace 重建 |
 
 SQLite 中的 Workspace 与 Project 注册数据是结构化事实，文档索引可以从 Markdown 重建；SQLite 不是知识内容的 SSOT。工具状态不写入 Workspace，因而一个 Campfire 安装可以管理多个 Workspace。
 
@@ -186,13 +233,12 @@ SQLite 中的 Workspace 与 Project 注册数据是结构化事实，文档索
 每台设备独立维护
   Project local_path
   SQLite 查询投影与运行记录
-  Decision 与事件
   Skills 安装路径、锁、缓存和报告
 ```
 
 Project 的逻辑身份可以跨设备保持一致，但 `local_path` 是机器绑定：同一个 Project 在不同电脑上可以位于不同目录，也可以在某台电脑上尚未克隆。新设备通过稳定 Project id 和 `git_remote_url` 识别代码仓库，自动探测失败时由用户或 Agent 在本机显式绑定路径。
 
-可移植元数据由 Vault 根目录唯一的 `.campfire.yaml` 承载并随 Git 或文件同步；不得提交 `campfire.db` 来共享状态。Manifest 使用稳定的 `workspace.id`，保存 Workspace 名称、治理版本，以及 Project 的 id、名称、根 `document_domain_id`、Git remote、默认分支和状态，明确禁止 `local_path`。`projects[].document_domain_id` 是 Project–Domain 绑定的唯一事实；`_领域.md` 不保存 Project 字段。现有 `_空间.md` 与 `_领域.md` 分别承载 Space 和 Domain 自身事实。Decision 当前保持本地，不属于该 Manifest。
+可移植元数据由 Vault 根目录唯一的 `.campfire.yaml` 承载并随 Git 或文件同步；不得提交 `campfire.db` 来共享状态。Manifest 使用稳定的 `workspace.id`，保存 Workspace 名称、治理版本，以及 Project 的 id、名称、根 `document_domain_id`、Git remote、默认分支和状态，明确禁止 `local_path`。`projects[].document_domain_id` 是 Project–Domain 绑定的唯一事实；`_领域.md` 不保存 Project 字段。现有 `_空间.md` 与 `_领域.md` 分别承载 Space 和 Domain 自身事实。待人确认内容以 Markdown 文档同步，不存在当前公共 Decision 状态机。
 
 Space/Domain 声明采用区域所有权：Frontmatter 由 Workspace App 管理，成对 `AUTO-GENERATED` 标记内由生成器管理，标记外 Markdown 正文由人和 Agent 自由维护。声明 formatter 只能重排 Frontmatter，必须逐字节保留正文；生成器遇到重复、嵌套或未闭合标记时停止，不猜测覆盖范围。
 
@@ -216,21 +262,11 @@ SQLite 中的 `spaces`、`domains` 与 `documents` 是本机查询投影，不
 
 Adoption 是首次接管边界，不属于日常 Maintenance。`workspace domain adopt` 一次完成只读盘点、预览和确认后的原子接管，不持久化中间批次。外部目录通过临时隐藏目录复制并校验，原来源保持不变；Vault 内目录原地声明或移动到目标。CLI 负责哈希、软链接与冲突保护、声明、初始 MOC 和 Project/Manifest 联动；Agent 负责阅读正文、选择目标 Space/Domain，并执行返回的 `follow_up`。
 
-## 6. 本地 Web 工作台
-
-Campfire 可以提供由 CLI 启动的单进程本地 HTTP 服务和浏览器工作台。CLI 与 HTTP 是同级交付适配器，必须复用同一个 Application Service、Repository、事务和审计逻辑；前端不得直接访问 SQLite，也不得复制 Decision 状态机。
-
-```text
-Agent / Terminal ──> CLI Adapter  ──┐
-                                    ├── Application Service ──> Repository
-Human / Browser  ──> HTTP Adapter ──┘                           │
-                                                                ├── SQLite
-                                                                └── Vault
-```
+## 6. 可选阅读环境与未来交付
 
-第一期 Web UI 只处理 Decision：查看 pending、answered、closed、cancelled，阅读问题、证据、建议、关联文档与来源 Session，并执行 answer 或 cancel。用户回答后仍由原 Agent 消费答案并调用 close。Obsidian Base 继续作为只读快速视图，不承担状态写入。
+当前公共入口是 CLI，没有已交付的 Web 工作台或独立 Decision HTTP 状态机。Obsidian 是推荐阅读工具，不是 CLI 的强依赖；Bases、大纲和可选 Kanban 负责相应展示，普通 Markdown 和文档查询不依赖这些组件。Obsidian Git 可辅助版本历史，CLI 不另建备份系统。
 
-本地服务默认只监听 `127.0.0.1`，不内置账号、云同步、远程调度或多服务器部署。前端源码独立构建，静态产物随 Python wheel 发布；最终用户不需要 Node.js。
+如未来增加其他交付适配器，必须复用 Application Service，不复制治理规则；这不是当前版本的交付承诺。插件配置教程由维护者后续博客说明，不在 CLI 内实现安装器或配置管理。
 
 ## 7. 稳定不变量
 
@@ -239,7 +275,7 @@ Human / Browser  ──> HTTP Adapter ──┘                           │
 3. 规则集中在配置契约和规则引擎，Skill、模板、CLI 不复制枚举定义。
 4. MOC、Base 和报告能生成就不手工维护；文档关系通过 CLI 查询，不再复制为关系页。
 5. 有歧义的分类和结构重构进入待确认，不由 Agent 擅自决定。
-6. Markdown 内容可脱离 Campfire 阅读和迁移；文档查询投影在 SQLite 丢失后可以重建，Decision 与未完成批次等工作流状态不作此承诺。
+6. Markdown 内容可脱离 Campfire 阅读和迁移；文档查询投影在 SQLite 丢失后可以重建，未完成重构批次等本机工作流状态不作此承诺。
 7. 只有一个用户级 SQLite；所有 Workspace 业务表必须携带 `workspace_id`，Repository 查询不得越界。
 8. 正式文档必须归入 Domain；Space 不直接替代 Domain，系统区域不伪装成 Space。
 

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.24 → campfire_cli-0.2.0a2}/COMMAND.md

@@ -42,7 +42,7 @@ campfire base list / show / check / sync
 
 Space、Domain、Project 的 `create`/`adopt`，以及文档移动和重构写操作默认先预览；审查通过后才追加 `--confirm`。归档通过 `document apply --set document_status=archived` 修改，且必须先获得用户明确同意。已注册 Workspace 只通过根级 `campfire --workspace <id> ...` 选择；已声明 Space、Domain 和 Project 使用稳定 ID，CLI 自行推导路径和父子关系。路径参数只用于新位置、具体文件、外部输入和显式扫描范围。
 
-目录名以 `_` 开头时表示系统治理区域，不能声明为 Space 或 Domain；错误结果返回命中的 `reserved_directory` 和修复提示。其他目录名默认没有隐藏保留语义，`任务/`、`记录/`、`assets/`、`archive/`、`generated/` 均可按需 create/adopt 为 Domain。文档类型不强制对应同名 Domain，归档只通过 `document_status=archived` 表达；CLI 关系页写入 `_generated/`，Base 写入 `_治理视图/`。
+目录名以 `_` 开头时表示系统治理区域，不能声明为 Space 或 Domain；错误结果返回命中的 `reserved_directory` 和修复提示。其他目录名默认没有隐藏保留语义，`任务/`、`记录/`、`assets/`、`archive/`、`generated/` 均可按需 create/adopt 为 Domain。文档类型不强制对应同名 Domain，归档只通过 `document_status=archived` 表达；不再生成关系页；Base 写入 `_治理视图/`，无需 Obsidian 即可查询文档关联。
 
 `document apply` 可新建、更新、为已有正文补齐 Frontmatter，或通过显式 `--type` 原子转换文档类型。新建文档在 Frontmatter 后包含唯一的 `<!-- CAMPFIRE:BODY -->`，调用方只在锚点后编辑正文；存量文档不强制迁移。创建或唯一更新时可省略 `.md`；创建和类型转换时还可省略类型前缀。CLI 在 `normalization` 中返回每项标准化，并在 `target` 中返回最终路径；调用方不手工同步类型、前缀与 Markdown 后缀。`document move` 可在任意已声明 Domain 之间移动单篇文档，并对齐目标 Profile 与可确定引用。目标 Profile 缺少语义字段时返回 `missing_fields`，调用方补齐明确业务值。只有实际写入成功的结果才可返回零或一个、且可直接执行的 scoped `maintenance sync` follow-up；Domain 内部路径会归一化为对应 Domain，预览、阻塞或无派生影响时返回空列表。具体参数以对应命令的 `-h` 为准。
 

campfire_cli-0.2.0a2/CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# 参与贡献
+
+先阅读 [SPEC](SPEC.md) 的边界，再讨论问题和范围。小修复直接提交 PR；新增命令、领域模型或兼容性变化先开 Issue。不要将内部公司代码、数据或无权分发的资料提交到项目。
+
+## 开发与验证
+
+Python 3.12+ 和 uv 是开发前提，安装后运行：
+
+```text
+uv sync --frozen
+uv run python scripts/quality_check.py
+uv run python scripts/quality_check.py --release
+```
+
+最后一项额外构建并在临时环境安装 wheel，不发布。测试必须隔离 CAMPFIRE_HOME、Skill 与提示词目录，不修改开发者真实 Workspace。公开上手案例见 [quickstart](docs/quickstart.md)。
+
+提交使用 conventional commits，说明动机、改动范围和验证结果。只暂存相关文件；不提交 .venv、状态数据库、真实 Vault 或凭据。行为保持型重构与功能变更分开提交。不要自行重写公开历史或重建已发布标签。
+
+## 报告问题
+
+通过 [Issues](https://github.com/Kepler452Byte/campfire-cli/issues) 提供 CLI/Python/系统版本、最小命令、预期和实际 JSON 结果。使用脱敏的最小文件，不附原始企业资料。安全问题先读 [SECURITY](SECURITY.md)。
+
+## 发布职责
+
+维护者核对 CHANGELOG、版本和标签，运行 release_check 与本地门禁；只有明确发布授权后才推送标签。三平台 release 工作流通过后发布验证过的包，随后从公共 PyPI 安装验证。GitHub Release Notes 摘录 CHANGELOG 对应版本；不修改已有版本的包和标签。
+
+当前 v0.1.25 聚焦开源文档、隔离示例与使用安全；领域模式重构、搜索和插件自动管理不在本轮范围。

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

@@ -1,17 +1,75 @@
+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。
 
 - **人类和 Agent 同一条链路**：同一套 CLI 契约 + 全局 Agent Skill，没有两套规则。
-- **Markdown 是事实源**：正文永远可脱离 campfire 阅读和迁移；SQLite 只是可重建的本机索引与运行状态。
-- **写操作默认预览**：先计划、再确认、执行前在治理锁内复核内容哈希，多会话并发不会互相覆盖。
-- **本地优先**：不绑定云服务、不内置账号；Obsidian Vault 是当前首个存储适配器，Workspace 才是顶层概念。
+- **Markdown 是事实源**：正文永远可脱离 campfire 阅读和迁移；SQLite 保存可重建索引，也保存本机注册与运行状态，不能整体当作缓存删除。
+- **写操作默认预览**：先计划、再确认、执行前在治理锁内复核内容哈希，检测到输入变化时拒绝覆盖；不承诺外部编辑器遵守锁或跨介质崩溃原子性。
+- **本地优先**：不绑定云服务、不内置账号；Obsidian 是推荐阅读工具而非强依赖；CLI 可独立治理 Markdown Workspace。
 
 产品目标、业务对象、SSOT 与模块边界见 [ARCHITECTURE.md](ARCHITECTURE.md)。不知道 Campfire 是否具有某项能力时用 `campfire tree` 发现命令；已知文档操作不把 tree 作为固定前置步骤。
 
+## 使用入口
+
+首次使用先看 [独立环境快速上手](docs/quickstart.md)，完整走通文档创建与关联查询，不接入真实 Vault。需要 Python 3.12+；发布流程验证 Linux、macOS 和 Windows，具体 Shell 要求见示例。
+
+- [数据安全、误操作恢复与退出](docs/safety.md)
+- [版本变化](CHANGELOG.md) · [贡献指南](CONTRIBUTING.md) · [安全反馈](SECURITY.md)
+
+推荐搭配 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 可执行文件。
+
 ## 安装
 
-### v0.1.24 变更说明
+### 升级注意事项
 
 `maintenance sync` 不再生成 `_generated/相关文档-*.md`，并移除 MOC 自动区域中的关系页入口；MOC 的文档导航、分组和模板入口保持不变。`related_docs` 仍为可选字段，Agent 通过 `document list` 定位文档、通过 `document inspect` 查询出向、入向及失效关联，查询不要求先同步 MOC。
 
@@ -67,7 +125,7 @@ Workspace ── Space ── Domain 树 ── 文档
 | Space / Domain | 顶级容器 / 可嵌套内容边界，声明式 + 自动 MOC | Vault 内 `_空间.md`、`_领域.md` |
 | Document | 知识、计划、问题、决策、记录等持久内容 | Markdown 正文 + Frontmatter |
 | Human request | Agent 需要人类回答的待确认事项 | `_待用户确认/` 中的 `human-request` 文档 |
-| Generated View | MOC、相关文档页、Base、报告 | 派生数据，能生成就不手工维护 |
+| Generated View | MOC、Base、报告 | 派生数据，能生成就不手工维护 |
 
 `任务/`、`记录/` 可按实际组织需要成为 Domain，但文档类型不强制对应同名目录，也不要求每个 Project 预建。新建受管文档在 Frontmatter 后提供 `<!-- CAMPFIRE:BODY -->`，Agent 以该锚点定位人工正文；旧文档无需迁移。
 
@@ -82,7 +140,7 @@ campfire workspace list / show / export / import # 注册库管理与备份
 campfire workspace project resolve               # 当前目录属于哪个已注册项目
 
 campfire maintenance check [--summary] [--scope] # Schema/枚举校验 + 刷新索引
-campfire maintenance sync [--dry-run] [--scope]  # 刷新 MOC 与相关文档页
+campfire maintenance sync [--dry-run] [--scope]  # 刷新 MOC 导航
 
 campfire document inspect / check / format       # 单篇文档查看、校验、格式化
 campfire document list                           # 精确枚举和筛选受管文档
@@ -101,7 +159,7 @@ campfire base list / show / check / sync          # Obsidian Base `_治理视图
 ```bash
 campfire workspace space create --id research --name "研究" --path myresearch --type research
 campfire workspace domain create --id wiki --name "Wiki" --path "mywork/项目/wiki" \
-  --type knowledge-domain --confirm
+  --type knowledge-domain --governance knowledge-base --confirm
 campfire --workspace personal workspace project adopt --id example \
   --name "Example" --domain project-example --local-path /path/to/repo
 campfire workspace rebuild --confirm             # 索引损坏时从 SSOT 完整恢复
@@ -134,7 +192,7 @@ campfire workspace restructure verify --batch move-001
 - **本地查询投影**：`document list` 按 Project、Domain、类型、`document_status` 和 `task_status` 精确筛选；`document inspect` 返回显式关联、出链、反向链接和失效/歧义引用。两者在查询前自动 reconcile，Agent 无需先运行 Maintenance。SQLite 不复制正文，正文仍由 Agent 按返回路径读取。
 - **校验分工**：`maintenance check` 汇总 Space/Domain 结构与正式文档问题，并刷新可重建索引；`workspace space/domain check` 提供结构声明的专项诊断。`maintenance sync` 只因结构、MOC、路径或并发安全问题阻塞，单篇文档问题不阻止其他领域刷新。
 - **Frontmatter Profile**：声明式一层继承（`base` 或 `base → task/human-request/board`），`document profile show` 展示编译后的完整规则；Formatter 只按有效 Profile 排序并保留值，不允许字段由 Validator 报告、不自动删除。
-- **并发与提交安全**：写入前在治理锁内复核内容哈希，外部变化返回 `concurrent-change` / `source-hash-changed`，拒绝覆盖；多文件写入和路径移动经同一 ChangeSet 提交，失败恢复到执行前。
+- **并发与提交安全**：写入前在治理锁内复核内容哈希，外部变化返回 `concurrent-change` / `source-hash-changed`，拒绝覆盖；多文件写入和路径移动经同一 ChangeSet 提交，可捕获失败尝试补偿；若报告恢复失败，停止重试并核对实际文件。
 - **按需后续治理**：写入命令只在实际写入成功且派生内容可能变化时返回零或一个、且可直接执行的最小 scope `maintenance sync`；预览和阻塞结果的 `follow_up` 为空。位于 Domain 内部的 scope 由 CLI 归一化为有效 Domain。Skill 消费该结果，没有 follow-up 就结束，不固定追加 dry-run 或全量 check。
 - **配置两层模型**：产品默认契约在包内 `resources/defaults/config.yml`（SSOT），用户只在 `~/.campfire/config.yml` 写覆盖项；Mapping 递归合并，`campfire workspace config check` 验证有效配置。
 

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

@@ -1,33 +1,48 @@
-Metadata-Version: 2.5
-Name: campfire-cli
-Version: 0.1.24
-Summary: Local-first shared context and governance CLI for humans and agents
-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。
 
 - **人类和 Agent 同一条链路**：同一套 CLI 契约 + 全局 Agent Skill，没有两套规则。
-- **Markdown 是事实源**：正文永远可脱离 campfire 阅读和迁移；SQLite 只是可重建的本机索引与运行状态。
-- **写操作默认预览**：先计划、再确认、执行前在治理锁内复核内容哈希，多会话并发不会互相覆盖。
-- **本地优先**：不绑定云服务、不内置账号；Obsidian Vault 是当前首个存储适配器，Workspace 才是顶层概念。
+- **Markdown 是事实源**：正文永远可脱离 campfire 阅读和迁移；SQLite 保存可重建索引，也保存本机注册与运行状态，不能整体当作缓存删除。
+- **写操作默认预览**：先计划、再确认、执行前在治理锁内复核内容哈希，检测到输入变化时拒绝覆盖；不承诺外部编辑器遵守锁或跨介质崩溃原子性。
+- **本地优先**：不绑定云服务、不内置账号；Obsidian 是推荐阅读工具而非强依赖；CLI 可独立治理 Markdown Workspace。
 
 产品目标、业务对象、SSOT 与模块边界见 [ARCHITECTURE.md](ARCHITECTURE.md)。不知道 Campfire 是否具有某项能力时用 `campfire tree` 发现命令；已知文档操作不把 tree 作为固定前置步骤。
 
+## 使用入口
+
+首次使用先看 [独立环境快速上手](docs/quickstart.md)，完整走通文档创建与关联查询，不接入真实 Vault。需要 Python 3.12+；发布流程验证 Linux、macOS 和 Windows，具体 Shell 要求见示例。
+
+- [数据安全、误操作恢复与退出](docs/safety.md)
+- [版本变化](CHANGELOG.md) · [贡献指南](CONTRIBUTING.md) · [安全反馈](SECURITY.md)
+
+推荐搭配 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 可执行文件。
+
 ## 安装
 
-### v0.1.24 变更说明
+### 升级注意事项
 
 `maintenance sync` 不再生成 `_generated/相关文档-*.md`，并移除 MOC 自动区域中的关系页入口；MOC 的文档导航、分组和模板入口保持不变。`related_docs` 仍为可选字段，Agent 通过 `document list` 定位文档、通过 `document inspect` 查询出向、入向及失效关联，查询不要求先同步 MOC。
 
@@ -83,7 +98,7 @@ Workspace ── Space ── Domain 树 ── 文档
 | Space / Domain | 顶级容器 / 可嵌套内容边界，声明式 + 自动 MOC | Vault 内 `_空间.md`、`_领域.md` |
 | Document | 知识、计划、问题、决策、记录等持久内容 | Markdown 正文 + Frontmatter |
 | Human request | Agent 需要人类回答的待确认事项 | `_待用户确认/` 中的 `human-request` 文档 |
-| Generated View | MOC、相关文档页、Base、报告 | 派生数据，能生成就不手工维护 |
+| Generated View | MOC、Base、报告 | 派生数据，能生成就不手工维护 |
 
 `任务/`、`记录/` 可按实际组织需要成为 Domain，但文档类型不强制对应同名目录，也不要求每个 Project 预建。新建受管文档在 Frontmatter 后提供 `<!-- CAMPFIRE:BODY -->`，Agent 以该锚点定位人工正文；旧文档无需迁移。
 
@@ -98,7 +113,7 @@ campfire workspace list / show / export / import # 注册库管理与备份
 campfire workspace project resolve               # 当前目录属于哪个已注册项目
 
 campfire maintenance check [--summary] [--scope] # Schema/枚举校验 + 刷新索引
-campfire maintenance sync [--dry-run] [--scope]  # 刷新 MOC 与相关文档页
+campfire maintenance sync [--dry-run] [--scope]  # 刷新 MOC 导航
 
 campfire document inspect / check / format       # 单篇文档查看、校验、格式化
 campfire document list                           # 精确枚举和筛选受管文档
@@ -117,7 +132,7 @@ campfire base list / show / check / sync          # Obsidian Base `_治理视图
 ```bash
 campfire workspace space create --id research --name "研究" --path myresearch --type research
 campfire workspace domain create --id wiki --name "Wiki" --path "mywork/项目/wiki" \
-  --type knowledge-domain --confirm
+  --type knowledge-domain --governance knowledge-base --confirm
 campfire --workspace personal workspace project adopt --id example \
   --name "Example" --domain project-example --local-path /path/to/repo
 campfire workspace rebuild --confirm             # 索引损坏时从 SSOT 完整恢复
@@ -150,7 +165,7 @@ campfire workspace restructure verify --batch move-001
 - **本地查询投影**：`document list` 按 Project、Domain、类型、`document_status` 和 `task_status` 精确筛选；`document inspect` 返回显式关联、出链、反向链接和失效/歧义引用。两者在查询前自动 reconcile，Agent 无需先运行 Maintenance。SQLite 不复制正文，正文仍由 Agent 按返回路径读取。
 - **校验分工**：`maintenance check` 汇总 Space/Domain 结构与正式文档问题，并刷新可重建索引；`workspace space/domain check` 提供结构声明的专项诊断。`maintenance sync` 只因结构、MOC、路径或并发安全问题阻塞，单篇文档问题不阻止其他领域刷新。
 - **Frontmatter Profile**：声明式一层继承（`base` 或 `base → task/human-request/board`），`document profile show` 展示编译后的完整规则；Formatter 只按有效 Profile 排序并保留值，不允许字段由 Validator 报告、不自动删除。
-- **并发与提交安全**：写入前在治理锁内复核内容哈希，外部变化返回 `concurrent-change` / `source-hash-changed`，拒绝覆盖；多文件写入和路径移动经同一 ChangeSet 提交，失败恢复到执行前。
+- **并发与提交安全**：写入前在治理锁内复核内容哈希，外部变化返回 `concurrent-change` / `source-hash-changed`，拒绝覆盖；多文件写入和路径移动经同一 ChangeSet 提交，可捕获失败尝试补偿；若报告恢复失败，停止重试并核对实际文件。
 - **按需后续治理**：写入命令只在实际写入成功且派生内容可能变化时返回零或一个、且可直接执行的最小 scope `maintenance sync`；预览和阻塞结果的 `follow_up` 为空。位于 Domain 内部的 scope 由 CLI 归一化为有效 Domain。Skill 消费该结果，没有 follow-up 就结束，不固定追加 dry-run 或全量 check。
 - **配置两层模型**：产品默认契约在包内 `resources/defaults/config.yml`（SSOT），用户只在 `~/.campfire/config.yml` 写覆盖项；Mapping 递归合并，`campfire workspace config check` 验证有效配置。
 

campfire_cli-0.2.0a2/SECURITY.md

@@ -0,0 +1,9 @@
+# 安全反馈
+
+不要把访问令牌、真实 Vault、公司资料、未公开漏洞利用细节或包含这些内容的日志发到公开 Issue。
+
+2026-10-03 已启用并通过 GitHub API 核验 Private vulnerability reporting。发现安全问题时，通过 [私密报告入口](https://github.com/Kepler452Byte/campfire-cli/security/advisories/new) 提交最小复现，不在公开 Issue 披露敏感细节。本文不承诺响应时限，也不把普通 Issue 当作私密通道。
+
+凭据已暴露时先撤销或轮换凭据，删除公开帖子或 Git 历史不等于撤销访问能力。项目处于 0.x 阶段，安全修复优先面向最新版本，不承诺旧版本长期维护。
+
+报告入口需要登录 GitHub；若不可用，可在 Issue 仅请求维护者提供私密沟通方式，不附漏洞细节或凭据。

{campfire_cli-0.1.24 → 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`。
@@ -94,7 +95,7 @@ Campfire 使用语义化版本：
 - 可跨设备共享的是 Workspace、Space、Domain 和 Project 的稳定身份与逻辑关联，不是本机文件路径。
 - `git_remote_url`、Project id、文档 Domain 和治理契约版本属于可移植元数据。
 - `local_path`、Skill 安装位置、锁、缓存、索引和运行报告属于设备本地状态，不得写入可移植元数据。
-- Decision 及其事件当前属于创建它的本机工作流状态，不要求跨设备同步。
+- 待人确认采用 `_待用户确认/` 中的 Markdown 文档；本机重构批次和运行记录不承诺跨设备同步。
 - 新设备接管已有 Workspace 时，从可移植元数据恢复逻辑关系，再在本机独立绑定项目路径并重建 SQLite 派生状态。
 - Vault 根目录的 `.campfire.yaml` 是唯一可移植 Manifest；禁止在其他文件重复维护 Workspace/Project 便携元数据。
 - `.campfire.yaml` 禁止保存 Vault 或代码仓库的本机绝对路径。