campfire-cli 0.1.0__py3-none-any.whl

campfire_cli/resources/skills/campfire-document-capture/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: campfire-document-capture
+description: "把对话或 Agent 工作成果沉淀为 Campfire 文档；适用于问题、决策、结论或状态变化出现时主动提议沉淀或更新文档，写入前确认授权、唯一对象、所需资源、当前事实和目标文档，不用于普通问答或存量批量治理。"
+---
+
+# Campfire 文档沉淀
+
+将当前对话或 Agent 工作中的长期有效信息提炼为可跨 Session 使用的共享上下文。沉淀不是复制聊天或执行流水；保留问题、结论、证据、边界、取舍、未决事项、后续行动和必要来源。
+
+## 写入门禁
+
+正式写入必须同时通过授权门禁和事实门禁。用户允许沉淀，不等于允许 Agent 猜测缺失信息。
+
+```text
+识别到值得沉淀的内容
+          │
+          ▼
+用户是否已经授权写入？
+    │             │
+   否             是
+    │             │
+    ▼             ▼
+可立即询问？   对象是否唯一明确？
+ │       │        │          │
+是       否       否          是
+ │       │        │          │
+ ▼       ▼        ▼          ▼
+询问   待确认   必须询问   资源是否齐备？
+ │                           │          │
+同意                         否          是
+ │                           │          │
+ └───────────────┐           ▼          ▼
+                 │        获取/询问   事实是否核验？
+                 │                     │          │
+                 │                    否          是
+                 │                     │          │
+                 └─────────────────────┤          ▼
+                                       ▼      确定创建或更新
+                                  获取证据/待确认      │
+                                                       ▼
+                                                    正式文档
+```
+
+已经授权包括：用户直接要求沉淀；Agent 提议后用户明确同意；用户在任务开始前授予范围明确的持续沉淀权限。未经确认的静默保存只能生成待确认文档，不能成为正式事实。
+
+## 上下文预检
+
+写入前依次确认：
+
+1. **Workspace**：运行 `campfire workspace resolve`；无法唯一解析时询问用户。
+2. **对象**：项目、知识主题或任务必须唯一明确。使用 `campfire workspace space list` 和 `campfire workspace domain list` 获取候选归属；用户使用简称且可能指向多个项目时，运行 `campfire workspace project list`，仍有歧义必须询问，不凭名称相似度猜测。
+3. **资源**：列出形成可靠文档所需的对话、原始材料、现有文档、源码、配置、测试、日志或外部事实；能自行读取的先读取，只向用户询问真正缺失的资源。
+4. **现状**：写项目当前行为时，运行 `campfire workspace project show <id>` 获取文档领域和本地源码路径，读取项目 `AGENTS.md`、SPEC 或架构文档，并检查相关源码、配置和测试。无法访问源码时不得把讨论或计划写成当前实现。
+5. **目标文档**：搜索同主题文档，明确是创建、更新还是关联。没有合适 Domain 时先提议创建；用户确认后用 `workspace domain create`，不在 Space 根直接落正式文档。可能重复、冲突、覆盖或合并时必须确认。
+
+向用户提问时说明已经确认的内容、缺失资源、缺失原因以及它会影响的结论；一次只集中询问会改变事实、归属或写入方式的关键问题。
+
+## 事实分层
+
+不得混写以下语义：
+
+- **当前事实**：源码、配置、测试、日志或权威材料可以证明。
+- **用户确认的事实**：用户明确提供，但应标注来源，不能伪装成代码验证。
+- **目标方案**：准备实施但尚未落地。
+- **讨论建议**：尚未决策或证据不足。
+- **历史记录**：过去发生过，不能自动代表当前行为。
+
+若关键结论只能作为推断，明确标注推断及证据，或进入待确认；不能为了形成完整文档而补写不存在的事实。
+
+## 主动提议时机
+
+沉淀不必等用户提出。在汇报工作结果时，识别到以下时刻就一并向用户提议对应的文档动作。对象不限于项目文档：问题、决策、记录、知识按各自类型处理，归属判断遵循下方路由，本节只决定"何时提议、提议什么"。
+
+| 时刻 | 提议动作 |
+|------|---------|
+| 梳理出多个问题且尚无跟踪文档 | 创建 issue 文档（问题清单 + 状态跟踪表） |
+| 单个问题的根因经源码或运行核验 | 创建或更新对应 issue 文档，补根因与证据 |
+| 修复或变更完成并通过验证 | 更新 issue 文档状态表与解决记录 |
+| 形成影响实现的取舍决策 | 创建 decision 文档 |
+| 发现与既有文档冲突的事实 | 更新该文档并标注来源 |
+| 新文档已落盘 | 校验并刷新索引，确保进入 MOC |
+
+提议通过后按常规流程执行，配套命令：
+
+```bash
+campfire workspace resolve
+campfire --workspace personal document check --path "mywork/【某项目】文档中心/问题-....md"
+campfire --workspace personal maintenance sync --scope "mywork/【某项目】文档中心"
+```
+
+规则：一次汇报合并多个提议，不逐条打断；用户拒绝的提议不重复追问，除非出现新证据；同一主题只维护一个跟踪文档，用更新代替重复创建；主动提议不等于写入授权，落盘仍走上方写入门禁。
+
+## 路由
+
+预检通过后，知识、项目事实、方案、决策、问题、记录和任务统一交给 `campfire-workspace-maintenance` 选择 Space、Domain 与文档类型。本 Skill 不复制文档 Profile、生命周期、字段枚举或结构重构步骤；需要改变已有主物理位置时再加载 `campfire-workspace-restructure`。
+
+## Pending Decision
+
+Agent 未获授权而静默保存，或对象、资源、事实、目标文档仍存在关键歧义时，调用 `campfire decision create`。Decision 是 SQLite 中的工作流事实，不是正式知识或项目事实；Agent 不手工创建待确认 Markdown。
+
+Decision 应提供稳定幂等 key、唯一问题、背景与证据、候选选项、推荐方案、关联文档和来源 Session。CLI 在 `_协作/decisions/` 自动生成工作流专属只读投影；它不是正式内容文档，不使用普通 Document Profile，也不新增文档生命周期。
+
+获得回答后调用 `decision answer`；原流程使用答案完成创建或更新后调用 `decision close`。用户拒绝则取消或记录拒绝答案，不晋升为正式文档。正式文档直接使用自身类型的生命周期，不增加通用 `pending-review`。
+
+## 自动沉淀边界
+
+持续授权只覆盖约定范围内、已经验证且不改变业务承诺的事实。架构或产品取舍、弱证据推断、覆盖权威文档、归属不明和超出任务范围的内容仍需确认。临时调试输出、失败尝试流水、可从代码直接读出的琐碎实现和无复用价值的聊天留在 Session，不创建文档。
+
+完成后必须向用户报告写入路径、创建或更新结果、证据范围和未解决问题；不得静默修改正式文档。

campfire_cli/resources/skills/campfire-inbox-triage/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: campfire-inbox-triage
+description: "分流 Campfire Workspace 全局收件箱中的输入；适用于判断目标 Space、Domain 和文档类型，以及生成需要用户确认的归属问题。"
+---
+
+# Campfire 收件箱分流
+
+只处理已经进入 `_收件箱/` 的原始材料和待确认文档，不负责从对话提炼新文档。先读取 `campfire-workspace-maintenance`，再读取候选领域的 `_领域.md`；涉及沉淀内容是否足以晋升时加载 `campfire-document-capture`，涉及跨领域批量移动时加载 `campfire-workspace-restructure`。
+
+## 工作流
+
+1. `_收件箱/` 只保存用户原始输入；Decision 位于 `_协作/decisions/`，不作为收件箱材料分流。处理关联 Decision 时通过 `campfire decision show` 读取事实。
+2. 只在已有正式领域中选择目标；创建顶级领域、合并内容或删除原文必须由用户确认。
+3. 给出目标空间、领域、类型、文件名、摘要、理由和置信度。
+4. 归属和事实明确时形成默认未审批的维护建议，不直接移动或晋升。
+5. 空间、领域、权威性或合并关系存在歧义时调用 `campfire decision create`，由 CLI 生成可读投影，并保持原文不动。
+6. 用户通过 `decision answer` 给出决定并转为已审批计划后才执行；完成后同步 MOC，再调用 `decision close`。
+
+## 边界
+
+- `high` 只表示可以生成待审批计划，不表示可以跳过审批。
+- `medium` 或 `low` 必须请求确认。
+- Decision 必须关联原文、列出候选及一个明确问题，不能代替正式知识文档；`_协作/decisions/Decision-*.md` 不允许手工维护。

campfire_cli/resources/skills/campfire-weekly-report-writing/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: campfire-weekly-report-writing
+description: "根据工作日志和上周周报撰写或更新工作周报；适用于周报生成、复盘和下一周计划整理，不依赖固定 Space 路径。"
+---
+
+# 工作周报写作
+
+先通过 `campfire workspace space list` 找到 work 类型 Space，再通过 Domain 声明和现有 `type: weekly-report` 文档确定工作日志与周报位置；不得根据固定目录名推断。
+
+## 输入与依据
+
+1. 读取本周工作日志，确认完成事项、实际结果、已发现问题和待办。
+2. 读取上一周周报，识别承接关系并检查上周计划进展。
+3. 缺少工作日志、周期或必要上下文时明确指出，不编造成果、难点、指标或计划。
+
+## 输出规则
+
+- Frontmatter 与文件名前缀通过 Campfire Document Profile 和类型定义读取，不在 Skill 复制。
+- 正文使用“复盘目标、问题分析、下一步行动计划”；保持简洁、成果导向，不写成日志流水。
+- 完成成果必须有日志、任务、项目文档或用户材料支持；计划和当前事实不能混写。
+- 新建前检查同周期周报是否存在，除非用户明确要求，否则不修改历史周报。

campfire_cli/resources/skills/campfire-weekly-report-writing/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "工作周报写作"
+  short_description: "基于工作日志和上周周报生成周报"

campfire_cli/resources/skills/campfire-workspace-adoption/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: campfire-workspace-adoption
+description: "把 Vault 内外已有文档文件夹首次接管为 Campfire Domain；适用于安全暂存、结构判断、接管计划和验收，不用于已受管领域的日常维护或再次重构。"
+---
+
+# Campfire Workspace Adoption
+
+本 Skill 只负责把一个尚未受管的已有文件夹接入 Campfire。接管完成后，格式治理交给 `campfire-workspace-maintenance`，后续移动、改名、拆分或合并交给 `campfire-workspace-restructure`。
+
+## 路由
+
+```text
+来源文件夹
+├── Vault 外 → inventory --confirm 安全复制到 _收件箱/待接管/<batch>
+└── Vault 内 → inventory 原地冻结事实，不复制
+                 │
+                 ▼
+       Agent 阅读内容并设计粗粒度 Domain
+                 │
+                 ▼
+       plan → apply 预检 → apply --confirm → verify
+                 │
+                 ▼
+       Maintenance 格式治理 / Restructure 子领域拆分
+```
+
+## SOP
+
+1. 运行 `campfire workspace resolve`，确认唯一 Workspace。
+2. `campfire workspace adopt inventory --source <folder> --batch <id>` 只读盘点。外部目录审查复制清单后追加 `--confirm`；不得手工移动或删除外部原目录。
+3. 阅读真实文档，确认 Space、目标路径、稳定 `domain_id`、领域名称、治理类型及可选 Project。无法确定唯一归属时先询问用户或创建 Decision。
+4. 使用 `campfire workspace adopt plan` 建立粗粒度目标 Domain。不要在接管阶段假装自动完成语义分类；需要多个子领域时，接管根领域后再使用 Restructure。
+5. 运行不带 `--confirm` 的 `apply` 审查最终计划；用户已经明确授权且没有冲突时追加 `--confirm`。
+6. 运行 `verify`。随后加载 Maintenance Skill，处理标题、摘要、类型、Frontmatter 和归档问题；需要拆分子领域时加载 Restructure Skill。
+
+## 安全边界
+
+- 外部来源只复制到暂存区，绝不修改或删除原目录。
+- 软链接、目标冲突、暂存内容冲突或源哈希变化必须阻塞。
+- 接管计划一次建立一个粗粒度 Domain；语义拆分由 Agent 提案并走独立重构计划。
+- CLI 管理复制、哈希、声明、Project/Manifest 联动、MOC 与索引；Agent 负责理解正文。
+- 验收前不得宣称接管完成；报告复制数量、目标 Domain、剩余治理问题和原始来源是否保留。

campfire_cli/resources/skills/campfire-workspace-maintenance/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: campfire-workspace-maintenance
+description: "持续维护 Campfire Workspace 的结构与文档合规；适用于 Space/Domain 声明、文档检查与格式化、MOC 同步、归档和日常维护，不用于跨领域批量重构。"
+---
+
+# Campfire Workspace Maintenance
+
+`.campfire.yaml`、`_空间.md`、`_领域.md` 和内容文档是跨设备 SSOT；SQLite 中的 Workspace 拓扑与文档数据只是本机可重建索引。首次接入使用 `campfire setup --workspace <vault>`，它会自动扫描并建立索引，不要求用户单独初始化数据库。
+
+日常运行 `campfire maintenance check` 时会同步刷新 Space、Domain 和 Document 索引。仅在 SQLite 被删除、怀疑索引漂移或 CLI 升级修复时使用低频恢复入口：
+
+```bash
+campfire workspace rebuild
+campfire workspace rebuild --confirm
+```
+
+`rebuild` 不修改 Vault 文档；它从 Manifest 和 Markdown SSOT 完整替换本机派生索引。不要直接修改 SQLite，也不要把数据库提交到 Git 或跨设备同步。
+
+目标是允许人类低成本记录，同时让 Agent 以可审阅、可重复执行的方式保持 Workspace 合规。
+
+先运行 `campfire workspace resolve` 获取目标 Workspace，再读取其 `AGENTS.md`。运行 `campfire workspace config check`、`workspace space/domain check` 和 `campfire maintenance check` 获取当前状态；检查不修改原始笔记，但可能刷新用户级索引和报告，不得直接编辑 `~/.campfire/`。
+
+## 工作流
+
+1. 通过 `workspace space/domain list` 和声明文件理解现有结构。正式文档必须归入 Domain，Space 不直接承载正式文档。
+2. 新目录使用 `space/domain create`；已有目录使用 `space/domain adopt`。默认先预览，用户确认后追加 `--confirm`。顶级 Space、根 Domain 和有歧义的父子关系必须由用户确认。
+3. 单篇文档先运行 `campfire document inspect --path <file>`；字段、顺序与枚举以返回的有效 Profile 为准，不在 Skill 中复制。
+4. 确定性问题可以生成普通 Plan；缺标题、摘要、类型等语义时，Agent 必须阅读正文和领域上下文，生成 YAML/JSON Spec，再运行 `campfire maintenance plan --id <id> --scope <path> --spec <file>`。Spec 中每项默认不审批；只有用户已明确授权或逐项审查通过才写 `approved: true`。
+5. 依次运行 `maintenance show --plan <id>`、`maintenance apply --plan <id>` 预检、`maintenance apply --plan <id> --confirm` 执行和 `maintenance verify --plan <id>` 局部验收。出现 `concurrent-change` 或配置变化时废弃旧计划并重新生成。
+6. 使用 `maintenance sync --scope <path> --dry-run` 预览当前范围的 MOC、关系页与治理视图变更，审查后去掉 `--dry-run`。日常完整流程使用 `maintenance run --scope <path>`。
+7. 报告原始笔记变化、自动生成物和仍需用户确认的事项。涉及跨领域移动、领域拆分或合并时停止，改用 `campfire-workspace-restructure`。
+8. 无法从正文、领域上下文或项目事实唯一决定时，统一调用 `campfire decision create`。不要判断当前是交互会话还是定时任务；当前对话获得回答后调用 `decision answer`，答案被原任务消费后调用 `decision close`。全部状态由 CLI 投影到统一的决策工作台，未回答事项显示在“待我确认”视图。
+
+## 路由
+
+```text
+发现对象
+   |
+   +-- 已在 Domain，字段、类型、同目录命名或 Formatter 不合规
+   |      -> inspect/check -> Agent 语义判断 -> plan --spec
+   |      -> show -> apply 预检 -> apply --confirm -> verify -> sync --scope
+   |
+   +-- 已有目录但没有声明
+   |      -> space/domain adopt
+   |
+   +-- 需要新 Space 或 Domain
+   |      -> space/domain create
+   |
+   +-- 需要改变主 Domain、拆分或合并领域
+   |      -> campfire-workspace-restructure
+   |
+   `-- 归属或语义不能唯一确定
+          -> decision create
+          -> pending Decision 自动投影到 _协作/decisions/pending
+```
+
+Agent 负责理解正文、项目事实和业务语义；CLI 负责 Profile 校验、计划、哈希保护、执行、引用更新和审计；用户负责确认歧义与高风险归属。不要由 Agent 手工执行本可进入 Maintenance Plan 的批量修改。
+
+## 不变量
+
+- 整个 Workspace 只有一个根 `_收件箱/`；语义无法唯一判断时进入待用户确认，不为追求检查通过而猜测。
+- `_空间.md` 声明 Space，`_领域.md` 声明可多级嵌套的 Domain；保留目录不是 Space 或 Domain。
+- 一篇文档只有一个主物理 Domain，可以出现在多个自动索引中。
+- MOC 自动区域、相关文档、反向链接、关系和统计由 CLI 生成，不手工维护。
+- Maintenance 只允许在原 Domain 内按 type 修正文件名，不改变文档主物理归属，不进行跨领域移动、领域合并或拆分。
+- 写入返回 `concurrent-change` 时停止并重新检查，不覆盖其他会话的新内容。
+- Markdown 是内容事实来源，用户级配置是治理契约；SQLite 只保存索引与工作流状态。
+- Decision 是工作流对象：SQLite 当前状态与追加事件是 SSOT，`_协作/decisions/` 只读投影不得手工维护。
+
+## 内容与任务
+
+- 跨项目可复用的长期认知归入 knowledge 类型 Space；项目当前实现、方案、决策、问题或记录归入 Project 绑定的 Domain。项目事实必须检查已注册源码、配置和测试。
+- `status`、`lifecycle` 和其他字段只从 Document Profile 获取。任务正文需要创建或更新时参考[任务正文结构](references/任务正文结构.md)。
+- 归档必须由显式 `archive_requested` 触发；先运行 `maintenance archive check`，审查后执行 `archive apply --confirm`。不得仅因长期未更新而归档。

campfire_cli/resources/skills/campfire-workspace-maintenance/references//344/273/273/345/212/241/346/255/243/346/226/207/347/273/223/346/236/204.md

@@ -0,0 +1,23 @@
+# 任务正文结构
+
+任务正文用于保留协作上下文，按实际信息选择以下章节；不要为了填模板编造内容。
+
+```markdown
+# 任务标题
+
+## 原始要求
+
+## 当前理解
+
+## 待确认
+
+## 验收标准
+
+## 执行计划
+
+## 关键进展
+
+## 结果与证据
+```
+
+小型确认留在任务正文；影响任务是否成立、Project/Domain 归属或权威结论的问题进入全局待用户确认区。

campfire_cli/resources/skills/campfire-workspace-restructure/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: campfire-workspace-restructure
+description: "按审批计划重构 Campfire Workspace 的已有物理结构；适用于跨领域移动、批量改名、领域拆分或合并和引用更新，不用于日常检查、格式化或 MOC 同步。"
+---
+
+# Campfire Workspace Restructure
+
+本 Skill 只处理会改变文档主物理位置或领域结构的一次性重构。日常新增、格式修正、声明补全、MOC、归档和持续检查使用 `campfire-workspace-maintenance`。
+
+先运行 `campfire workspace resolve`，读取目标 Workspace 的 `AGENTS.md`、相关 `_空间.md`、`_领域.md` 和已有 MOC。Agent 负责理解内容并提出目标结构；CLI 负责冻结事实、哈希保护、计划执行、引用更新和验收。
+
+## 工作流
+
+先识别被重构的对象，不要把领域目录改名拆成大量逐文件移动：
+
+```text
+重构意图
+├── 单篇或一批内容文档 → inventory / plan / apply / verify
+└── 已声明 Domain
+    ├── 修改人类名称     → domain rename
+    ├── 修改物理位置     → domain move
+    └── 修改稳定机器身份 → domain rekey（高风险）
+```
+
+领域级命令默认只输出影响计划，用户明确要求执行且计划无歧义时才追加 `--confirm`：
+
+```bash
+campfire workspace restructure domain rename --domain <id> --name <name>
+campfire workspace restructure domain rename --domain <id> --name <name> --rename-directory --project-name <name> --confirm
+campfire workspace restructure domain move --domain <id> --target-path <path> --parent-domain <id> --confirm
+campfire workspace restructure domain rekey --domain <id> --new-id <id> --confirm
+```
+
+`rename` 默认只修改领域显示名称；`--rename-directory` 或 `--target-path` 才修改目录，`--project-name` 才修改关联 Project 展示名称。普通 rename/move 必须保持 `domain_id`；只有用户明确要求改变稳定身份时使用 `rekey`。
+
+1. 使用 `campfire workspace restructure inventory --scope <path> --batch <id>` 冻结明确范围。
+2. 使用 `workspace restructure plan --batch <id>` 生成推断计划。工具不能表达的移动或 Frontmatter 修改写入 YAML/JSON 意图规格，再运行 `plan --spec <file>`。
+3. 逐项审查 source、target、Frontmatter Patch、理由和审批状态。删除、合并、根领域拆分、冲突权威判定和无法逆推的语义必须由用户确认。
+4. 先运行不带 `--confirm` 的 `workspace restructure apply --batch <id>` 做执行前预检；计划已经明确审批且没有阻塞问题时才追加 `--confirm`。
+5. 执行 `workspace restructure verify --batch <id>`，随后加载 `campfire-workspace-maintenance` 运行 `maintenance check` 与 `maintenance sync --dry-run`，审查后刷新派生内容。
+
+## 安全边界
+
+- 纯移动必须保持文档内容不变；只有 Spec 明确提供 Frontmatter Patch 时才改写内容。
+- `restructure verify` 只验证 source/target 迁移事实；文档 Profile 与 Formatter 合规交给 Maintenance。
+- 不用 Restructure 处理普通增量维护，也不绕过批次计划直接移动受管文档。
+- 写入返回 `concurrent-change`、`source-hash-changed` 或 `restructure-config-changed` 时停止，重新 inventory 和 plan。
+- 一篇文档只有一个主目标位置；跨领域关系使用链接和自动索引表达。
+- 领域路径变化必须联动 Project `document_domain`、`.campfire.yaml`、路径引用和子领域解析；不得手工分别维护。
+- `domain_id` 是稳定身份；`rekey` 必须更新直接子领域的 `parent_domain`，且必须显式确认。
+- 目标冲突、来源缺失、链接歧义或语义不明确时保持未执行并请求确认。
+- 报告移动、改名、Frontmatter 变化、引用更新、验证结果和剩余问题。

campfire_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.5
+Name: campfire-cli
+Version: 0.1.0
+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: 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 结构重构与后续增量维护分开。
+
+产品目标、业务对象、SSOT 与模块边界见 [ARCHITECTURE.md](ARCHITECTURE.md)。Markdown/Obsidian Vault 是当前首个存储适配器，Workspace 才是面向用户的顶层概念。
+
+```bash
+uv sync
+uv run campfire --help
+uv run campfire setup --workspace /path/to/vault --default
+uv run campfire workspace list
+uv run campfire --workspace personal maintenance check
+```
+
+Vault 根目录的 `.campfire.yaml` 是可跨设备同步的 Workspace/Project 元数据事实源；它不保存任何设备绝对路径。CLI 通过本机唯一的 `~/.campfire/campfire.db` 管理路径绑定、Decision、文档索引和运行状态。各 Workspace 的配置、批次和报告保存在 `~/.campfire/workspaces/<id>/`，不会向 Workspace 写入工具状态目录。可用 `CAMPFIRE_HOME` 覆盖用户级根目录。
+
+## 安装与调用
+
+开发机安装：
+
+```bash
+uv tool install --editable /path/to/campfire-cli
+campfire version
+```
+
+安装全局 Agent Skill（同步到 `~/.claude/skills` 与 `~/.agents/skills`）：
+
+```bash
+campfire skill list   # 查看包内 SSOT Skill 与全局同步状态
+campfire skill sync   # 确定性同步托管 Skill 到全局目录
+```
+
+`skill` 命令不依赖已注册 Workspace，可在 `setup` 之前使用；`campfire setup` 初始化
+Workspace 时也会自动执行一次同步。可用 `CAMPFIRE_SKILL_TARGETS`（路径分隔符分隔的
+列表）覆盖同步目标。
+
+人类和 Agent 使用同一条链路：全局 Skill 先调用 `campfire workspace resolve`，再读取目标 Workspace 的 `AGENTS.md`，并使用 Workspace id 调用 `campfire`。不修改原始笔记的检查可以直接执行（会刷新 SQLite 当前状态和 current 报告）；`campfire workspace restructure apply`、
+`maintenance apply` 和 `maintenance archive apply` 必须先审查计划，并使用命令要求的显式确认参数。
+
+```bash
+campfire workspace add --id personal --path /path/to/vault --default
+campfire workspace create --id new-vault --path /new/path --default
+campfire setup --workspace /path/to/existing-vault --default
+campfire workspace attach --path /path/to/existing-vault --default
+campfire workspace project bind --id example --local-path /path/to/repository
+campfire workspace space list --workspace personal
+campfire workspace domain list --workspace personal
+campfire workspace domain check --workspace personal
+campfire workspace space create --id research --name "研究" --path myresearch --type research
+campfire workspace space create --id research --name "研究" --path myresearch --type research --confirm
+campfire workspace space adopt --id research --name "研究" --path myresearch --type research
+campfire workspace config check --workspace personal
+campfire workspace domain create --id distributed-systems --name "分布式系统" --path "knowledge/分布式系统" --space knowledge --type knowledge-domain --governance knowledge-docs
+campfire workspace domain create --id distributed-systems --name "分布式系统" --path "knowledge/分布式系统" --space knowledge --type knowledge-domain --governance knowledge-docs --confirm
+campfire workspace domain adopt --id meetings --name "会议记录" --path "mywork/会议记录" --space work --type work-domain --governance work-docs
+campfire workspace domain adopt --id meetings --name "会议记录" --path "mywork/会议记录" --space work --type work-domain --governance work-docs --confirm
+campfire workspace project add --id example --workspace personal --name "Example" --document-domain "work/example" --local-path /path/to/repository
+campfire workspace project list --workspace personal
+campfire --workspace personal document profile list
+campfire --workspace personal document profile show task
+campfire --workspace personal document profile resolve --path "work/example/任务-示例.md"
+campfire --workspace personal document type list
+campfire --workspace personal document check --path "knowledge/example/知识-示例.md"
+campfire --workspace personal document format --path "knowledge/example/知识-示例.md"
+campfire --workspace personal document format --path "knowledge/example/知识-示例.md" --confirm
+campfire --workspace personal decision create --key example-decision --question "需要确认什么？" --source-type agent
+campfire --workspace personal decision list --status pending
+campfire --workspace personal decision show <decision-id>
+campfire --workspace personal decision answer <decision-id> --answer "确认内容" --answered-by user
+campfire --workspace personal decision close <decision-id>
+campfire workspace export --output campfire-registry-backup.json
+campfire workspace import --input campfire-registry-backup.json
+campfire workspace import --input campfire-registry-backup.json --confirm
+campfire workspace resolve
+campfire workspace rebuild --confirm
+campfire workspace adopt inventory --source /path/to/folder --batch notes-001
+campfire workspace adopt inventory --source /path/to/folder --batch notes-001 --confirm
+campfire workspace adopt plan --batch notes-001 --target-path "mynote/新领域" --domain-id knowledge-new --name "新领域" --space knowledge --type knowledge-domain --governance knowledge-docs
+campfire workspace adopt apply --batch notes-001 --confirm
+campfire workspace adopt verify --batch notes-001
+campfire tree
+campfire --workspace personal maintenance check
+campfire --workspace personal maintenance check --summary
+campfire --workspace personal maintenance plan --id <plan-id>
+campfire --workspace personal maintenance apply --plan <plan-id> --confirm
+campfire --workspace personal maintenance sync --dry-run
+campfire --workspace personal maintenance sync --scope "work/example"
+```
+
+`maintenance check` 统一负责正式文档 Schema 与枚举校验，并从当前 `_空间.md`、`_领域.md` 刷新 SQLite 中可重建的 Space、Domain 和 Document 索引；结构声明本身由 `workspace space/domain check` 校验。`maintenance sync` 只因领域结构、MOC、路径或并发安全问题阻塞。单篇文档的元数据问题会继续出现在检查报告中，但不会阻止其他领域刷新生成视图。`sync` 和 `run` 可用 `--scope` 限定同步领域。索引损坏或被删除时使用 `workspace rebuild --confirm` 从 Manifest 和 Markdown SSOT 完整恢复。
+
+`workspace adopt` 负责首次接管已有文件夹。Vault 外来源先按哈希复制到 `_收件箱/待接管/<batch>`，原目录始终保留；Vault 内来源原地盘点。计划一次建立一个粗粒度 Domain，应用后自动生成声明与 MOC 并刷新索引。文档语义和子领域拆分仍由 Agent 通过 Maintenance/Restructure 的审批计划完成。
+
+所有受管内容文档都使用 `base` 或 `base → knowledge/project-doc/task` 的一层配置继承；`human-request` 等没有专属字段的类型直接使用 `base`。`_空间.md`、`_领域.md` 是 Workspace 声明，不是内容文档。`document profile show` 展示编译后的完整规则，`document profile resolve` 展示指定文档最终使用的 Profile。Formatter 只按有效 Profile 排序并保留值；不允许字段由 Validator 报告，不会被自动删除。
+
+Decision 的当前状态和追加事件位于全局 SQLite。全部状态自动投影到 `_协作/decisions/`，并统一显示在 `治理视图/决策工作台.base` 的不同状态视图中。投影不是事实源，不接受手工更新。
+
+跨目录重构或显式修改 Frontmatter 时，先冻结范围，再传入 YAML/JSON 意图规格：
+
+```yaml
+operations:
+  - source: work/old-project/技术-架构.md
+    target: work/new-project/platform/技术-架构.md
+    frontmatter:
+      project: new-project
+      domain: platform
+    reason: 文档实际描述新项目的平台实现
+    approved: false
+```
+
+```bash
+campfire --workspace /path/to/vault workspace restructure inventory --scope work --batch move-001
+campfire --workspace /path/to/vault workspace restructure plan --batch move-001 --spec restructure.yaml
+# 审查批次 plan.json，将确定项目 approved 改为 true
+campfire --workspace /path/to/vault workspace restructure apply --batch move-001
+campfire --workspace /path/to/vault workspace restructure apply --batch move-001 --confirm
+campfire --workspace /path/to/vault workspace restructure verify --batch move-001
+```
+
+领域名称、路径和稳定身份分别使用 `domain rename`、`domain move` 和高风险的 `domain rekey`。领域级命令会联动领域声明、子领域关系、Project、`.campfire.yaml` 和路径引用，默认只预览，追加 `--confirm` 才执行。
+
+Workspace Restructure、Maintenance、Archive 写入前会在治理锁内复核内容哈希；检测到其他会话修改时返回
+`concurrent-change` 或 `source-hash-changed`，不会覆盖新内容。文档、任务状态和 Skill 模板枚举由
+同一个治理规则引擎按照有效 `config.yml` 中的 `frontmatter_schema` 校验。
+
+产品默认契约位于包内 `resources/defaults/config.yml`，用户只在 `~/.campfire/config.yml` 写需要覆盖的配置。首次初始化会创建最小用户配置；修改后运行 `campfire workspace config check` 验证完整有效配置。`.campfire.yaml` 是便携元数据 SSOT；本机 SQLite 是设备路径、Decision、索引和运行状态的 SSOT。`workspace export/import` 只用于本机注册库备份，不承担跨设备同步。