campfire-cli 0.1.4__tar.gz → 0.1.6__tar.gz

{campfire_cli-0.1.4 → campfire_cli-0.1.6}/ARCHITECTURE.md

@@ -72,7 +72,7 @@ Markdown Workspace Adapter   用户级状态
 
 Decision 以 SQLite 当前快照和追加事件为 SSOT。全部状态在 `_协作/decisions/` 生成只读 Markdown 投影，并由统一的决策工作台按 pending、answered、closed、cancelled 展示。Notification 与未来 Task Channel 只通过稳定 Decision id 和事件联动，不反向拥有 Decision 状态。
 
-`app/` 按可独立理解的业务能力组织，CLI 只做参数和输出适配，Service 承担业务流程，Repository 负责外部读写。`common/` 只放跨业务复用、无独立业务流程的原子能力；不能为了“复用”把业务编排下沉到 common。
+`app/` 按可独立理解的业务能力组织，CLI 只做参数和输出适配，Service 承担业务流程，Repository 负责外部读写。跨 App 的用例编排由组合根 `AppContainer` 承担，`setup` 与 `upgrade` 是当前实例。`common/` 只放跨业务复用、无独立业务流程的原子能力；不能为了“复用”把业务编排下沉到 common。
 
 配置采用两层模型：包内 `resources/defaults/config.yml` 保存完整默认契约，用户级 `~/.campfire/config.yml` 只保存覆盖项。Mapping 递归合并，scalar 和 list 整体替换；配置不按 Workspace 复制，运行状态不写回 YAML。
 

{campfire_cli-0.1.4 → campfire_cli-0.1.6}/COMMAND.md

@@ -4,6 +4,9 @@
 
 ```bash
 campfire setup --workspace <vault-path> --default
+campfire upgrade
+campfire skill sync
+campfire base sync
 campfire workspace resolve
 campfire workspace rebuild
 campfire workspace rebuild --confirm

campfire_cli-0.1.6/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.5
+Name: campfire-cli
+Version: 0.1.6
+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 才是顶层概念。
+
+产品目标、业务对象、SSOT 与模块边界见 [ARCHITECTURE.md](ARCHITECTURE.md)，命令全景用 `campfire tree` 渐进发现。
+
+## 安装
+
+标准安装（已发布至 PyPI，无需源码仓库）：
+
+```bash
+uv tool install campfire-cli
+campfire version
+```
+
+升级：`campfire upgrade` 是一条幂等命令——检测 PyPI 新版本并按安装方式（uv tool / pipx）更新包本身（更新器在独立进程中等待当前进程退出后执行，完成后自动用新版代码对齐治理资源），随后对齐 SQLite Schema、全局 Skill、Base 与提示词路标。离线、已是最新、editable 源码安装或无法识别安装方式时跳过包更新仅对齐资源。
+
+开发机安装（跟随本地源码）：
+
+```bash
+git clone https://github.com/Kepler452Byte/campfire-cli
+uv tool install --editable /path/to/campfire-cli
+```
+
+源码开发使用 `uv sync` 后直接 `uv run campfire --help`。
+
+## 快速上手
+
+```bash
+# 1. 接入已有 Vault（目录已存在，含或不含 .campfire.yaml）
+campfire setup --workspace /path/to/vault --default
+
+# 2. 或者从零创建新 Workspace（初始化目录结构并注册）
+campfire workspace create --id personal --path /path/to/vault --default
+
+# 3. 日常：检查治理状态、刷新生成视图
+campfire maintenance check --summary
+campfire maintenance sync --dry-run
+```
+
+不指定 `--workspace` 运行 `campfire setup` 是降级执行而不是报错：仍会同步全局 Skill 与提示词路标，输出接入引导，并显式列出被跳过的 Manifest 相关步骤。
+
+`setup` 与 `skill sync` 会向 `~/.claude/CLAUDE.md`、`~/.agents/AGENTS.md` 注入幂等的 campfire 路标块（带注释标记、不触碰块外内容；`CAMPFIRE_AGENT_HINT_PATH` 可覆盖目标），并把托管 Skill 同步到 `~/.claude/skills`、`~/.agents/skills`（`CAMPFIRE_SKILL_TARGETS` 可覆盖）。Agent 冷启动时由此知道本机装有 campfire。
+
+## 核心概念
+
+```text
+Workspace ── Space ── Domain 树 ── 文档
+     │        （_空间.md）（_领域.md + 自动 MOC）
+     └── Project（关联代码仓库与项目根 Domain）
+```
+
+| 对象 | 说明 | 事实源 |
+|------|------|--------|
+| Workspace | 人与 Agent 共享的上下文边界，可对应一个 Vault | `~/.campfire/campfire.db`（注册）+ `.campfire.yaml`（便携 Manifest） |
+| Space / Domain | 顶级容器 / 可嵌套内容边界，声明式 + 自动 MOC | Vault 内 `_空间.md`、`_领域.md` |
+| Document | 知识、计划、问题、决策、记录等持久内容 | Markdown 正文 + Frontmatter |
+| Decision | 需要人类或高级 Agent 回答的持久判断 | 全局 SQLite，投影到 `_协作/decisions/` |
+| Generated View | MOC、相关文档页、Base、报告 | 派生数据，能生成就不手工维护 |
+
+设备边界：`.campfire.yaml` 只保存可跨设备同步的稳定身份与逻辑关联（Project id、Git remote、文档 Domain 等），禁止本机绝对路径；新设备执行 `campfire setup --workspace <vault>` 即可恢复。本机路径绑定、索引、Decision、锁与报告都在 `~/.campfire/`（可用 `CAMPFIRE_HOME` 覆盖），按 Workspace 隔离。
+
+## 常用命令
+
+```bash
+campfire tree                                    # 完整命令树
+campfire workspace resolve                       # Agent 冷启动第一步：解析当前 Workspace
+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 archive check / apply       # 归档候选检查与执行
+
+campfire document inspect / check / format       # 单篇文档查看、校验、格式化
+campfire document profile list / show / resolve  # Frontmatter Profile 规则
+campfire document type list                      # 文档类型与前缀
+
+campfire decision create / list / answer / close # 持久决策通道
+```
+
+结构治理命令默认只输出计划，追加 `--confirm` 才执行：
+
+```bash
+campfire workspace space create --id research --name "研究" --path myresearch --type research
+campfire workspace domain create --id wiki --name "Wiki" --path "mywork/项目/wiki" \
+  --space work --type knowledge-domain --governance project-docs --confirm
+campfire workspace project add --id example --workspace personal \
+  --name "Example" --document-domain "work/example" --local-path /path/to/repo
+campfire workspace rebuild --confirm             # 索引损坏时从 SSOT 完整恢复
+```
+
+## 存量接管与结构重构
+
+`workspace adopt` 负责首次接管已有文件夹：Vault 外来源先按哈希复制到 `_收件箱/待接管/<batch>`（原目录始终保留），Vault 内来源原地盘点；一次建立一个粗粒度 Domain，语义细分交给后续 Maintenance/Restructure 计划。
+
+```bash
+campfire workspace adopt inventory --source /path/to/folder --batch notes-001
+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
+```
+
+跨目录重构先冻结范围，再传入 YAML/JSON 意图规格（含 Frontmatter 修改），逐项审查 `approved` 后执行：
+
+```bash
+campfire workspace restructure inventory --scope work --batch move-001
+campfire workspace restructure plan --batch move-001 --spec restructure.yaml
+campfire workspace restructure apply --batch move-001 --confirm
+campfire workspace restructure verify --batch move-001
+```
+
+领域三个维度独立演进：`domain rename`（显示名）、`domain move`（物理路径）、`domain rekey`（稳定身份，高风险）。领域级命令联动 `_领域.md`、子领域、Project、`.campfire.yaml` 与路径引用。
+
+## 治理模型
+
+- **校验分工**：`maintenance check` 统一负责正式文档的 Schema 与枚举校验，并刷新可重建索引；结构声明由 `workspace space/domain check` 校验；`maintenance sync` 只因结构、MOC、路径或并发安全问题阻塞，单篇文档问题不阻止其他领域刷新。
+- **Frontmatter Profile**：声明式一层继承（`base` 或 `base → knowledge/project-doc/task`），`document profile show` 展示编译后的完整规则；Formatter 只按有效 Profile 排序并保留值，不允许字段由 Validator 报告、不自动删除。
+- **并发安全**：写入前在治理锁内复核内容哈希，外部变化返回 `concurrent-change` / `source-hash-changed`，拒绝覆盖。
+- **配置两层模型**：产品默认契约在包内 `resources/defaults/config.yml`（SSOT），用户只在 `~/.campfire/config.yml` 写覆盖项；Mapping 递归合并，`campfire workspace config check` 验证有效配置。
+
+## Agent 协作
+
+全局 Skill（`campfire skill list` 查看托管清单，`campfire skill sync` 手动同步）定义了 Agent 的标准工作流：先 `workspace resolve` 解析上下文，再读取目标 Workspace 的 `AGENTS.md`；只读检查可直接执行，`restructure apply`、`maintenance apply`、`archive apply` 必须先审查计划并用显式确认参数。有歧义的分类和重构进入 Decision 待确认，不由 Agent 擅自决定。
+
+## 许可
+
+MIT。

campfire_cli-0.1.6/README.md

@@ -0,0 +1,135 @@
+# Campfire
+
+`campfire` 是面向工作与学习场景的本地优先人机协作 CLI。它让人类和多个 Agent 围绕同一份持久共享上下文协作：把口头要求、临时笔记、任务进度、项目资料和长期知识沉淀进可检索、可交接、可审计的 Workspace。
+
+- **人类和 Agent 同一条链路**：同一套 CLI 契约 + 全局 Agent Skill，没有两套规则。
+- **Markdown 是事实源**：正文永远可脱离 campfire 阅读和迁移；SQLite 只是可重建的本机索引与运行状态。
+- **写操作默认预览**：先计划、再确认、执行前在治理锁内复核内容哈希，多会话并发不会互相覆盖。
+- **本地优先**：不绑定云服务、不内置账号；Obsidian Vault 是当前首个存储适配器，Workspace 才是顶层概念。
+
+产品目标、业务对象、SSOT 与模块边界见 [ARCHITECTURE.md](ARCHITECTURE.md)，命令全景用 `campfire tree` 渐进发现。
+
+## 安装
+
+标准安装（已发布至 PyPI，无需源码仓库）：
+
+```bash
+uv tool install campfire-cli
+campfire version
+```
+
+升级：`campfire upgrade` 是一条幂等命令——检测 PyPI 新版本并按安装方式（uv tool / pipx）更新包本身（更新器在独立进程中等待当前进程退出后执行，完成后自动用新版代码对齐治理资源），随后对齐 SQLite Schema、全局 Skill、Base 与提示词路标。离线、已是最新、editable 源码安装或无法识别安装方式时跳过包更新仅对齐资源。
+
+开发机安装（跟随本地源码）：
+
+```bash
+git clone https://github.com/Kepler452Byte/campfire-cli
+uv tool install --editable /path/to/campfire-cli
+```
+
+源码开发使用 `uv sync` 后直接 `uv run campfire --help`。
+
+## 快速上手
+
+```bash
+# 1. 接入已有 Vault（目录已存在，含或不含 .campfire.yaml）
+campfire setup --workspace /path/to/vault --default
+
+# 2. 或者从零创建新 Workspace（初始化目录结构并注册）
+campfire workspace create --id personal --path /path/to/vault --default
+
+# 3. 日常：检查治理状态、刷新生成视图
+campfire maintenance check --summary
+campfire maintenance sync --dry-run
+```
+
+不指定 `--workspace` 运行 `campfire setup` 是降级执行而不是报错：仍会同步全局 Skill 与提示词路标，输出接入引导，并显式列出被跳过的 Manifest 相关步骤。
+
+`setup` 与 `skill sync` 会向 `~/.claude/CLAUDE.md`、`~/.agents/AGENTS.md` 注入幂等的 campfire 路标块（带注释标记、不触碰块外内容；`CAMPFIRE_AGENT_HINT_PATH` 可覆盖目标），并把托管 Skill 同步到 `~/.claude/skills`、`~/.agents/skills`（`CAMPFIRE_SKILL_TARGETS` 可覆盖）。Agent 冷启动时由此知道本机装有 campfire。
+
+## 核心概念
+
+```text
+Workspace ── Space ── Domain 树 ── 文档
+     │        （_空间.md）（_领域.md + 自动 MOC）
+     └── Project（关联代码仓库与项目根 Domain）
+```
+
+| 对象 | 说明 | 事实源 |
+|------|------|--------|
+| Workspace | 人与 Agent 共享的上下文边界，可对应一个 Vault | `~/.campfire/campfire.db`（注册）+ `.campfire.yaml`（便携 Manifest） |
+| Space / Domain | 顶级容器 / 可嵌套内容边界，声明式 + 自动 MOC | Vault 内 `_空间.md`、`_领域.md` |
+| Document | 知识、计划、问题、决策、记录等持久内容 | Markdown 正文 + Frontmatter |
+| Decision | 需要人类或高级 Agent 回答的持久判断 | 全局 SQLite，投影到 `_协作/decisions/` |
+| Generated View | MOC、相关文档页、Base、报告 | 派生数据，能生成就不手工维护 |
+
+设备边界：`.campfire.yaml` 只保存可跨设备同步的稳定身份与逻辑关联（Project id、Git remote、文档 Domain 等），禁止本机绝对路径；新设备执行 `campfire setup --workspace <vault>` 即可恢复。本机路径绑定、索引、Decision、锁与报告都在 `~/.campfire/`（可用 `CAMPFIRE_HOME` 覆盖），按 Workspace 隔离。
+
+## 常用命令
+
+```bash
+campfire tree                                    # 完整命令树
+campfire workspace resolve                       # Agent 冷启动第一步：解析当前 Workspace
+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 archive check / apply       # 归档候选检查与执行
+
+campfire document inspect / check / format       # 单篇文档查看、校验、格式化
+campfire document profile list / show / resolve  # Frontmatter Profile 规则
+campfire document type list                      # 文档类型与前缀
+
+campfire decision create / list / answer / close # 持久决策通道
+```
+
+结构治理命令默认只输出计划，追加 `--confirm` 才执行：
+
+```bash
+campfire workspace space create --id research --name "研究" --path myresearch --type research
+campfire workspace domain create --id wiki --name "Wiki" --path "mywork/项目/wiki" \
+  --space work --type knowledge-domain --governance project-docs --confirm
+campfire workspace project add --id example --workspace personal \
+  --name "Example" --document-domain "work/example" --local-path /path/to/repo
+campfire workspace rebuild --confirm             # 索引损坏时从 SSOT 完整恢复
+```
+
+## 存量接管与结构重构
+
+`workspace adopt` 负责首次接管已有文件夹：Vault 外来源先按哈希复制到 `_收件箱/待接管/<batch>`（原目录始终保留），Vault 内来源原地盘点；一次建立一个粗粒度 Domain，语义细分交给后续 Maintenance/Restructure 计划。
+
+```bash
+campfire workspace adopt inventory --source /path/to/folder --batch notes-001
+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
+```
+
+跨目录重构先冻结范围，再传入 YAML/JSON 意图规格（含 Frontmatter 修改），逐项审查 `approved` 后执行：
+
+```bash
+campfire workspace restructure inventory --scope work --batch move-001
+campfire workspace restructure plan --batch move-001 --spec restructure.yaml
+campfire workspace restructure apply --batch move-001 --confirm
+campfire workspace restructure verify --batch move-001
+```
+
+领域三个维度独立演进：`domain rename`（显示名）、`domain move`（物理路径）、`domain rekey`（稳定身份，高风险）。领域级命令联动 `_领域.md`、子领域、Project、`.campfire.yaml` 与路径引用。
+
+## 治理模型
+
+- **校验分工**：`maintenance check` 统一负责正式文档的 Schema 与枚举校验，并刷新可重建索引；结构声明由 `workspace space/domain check` 校验；`maintenance sync` 只因结构、MOC、路径或并发安全问题阻塞，单篇文档问题不阻止其他领域刷新。
+- **Frontmatter Profile**：声明式一层继承（`base` 或 `base → knowledge/project-doc/task`），`document profile show` 展示编译后的完整规则；Formatter 只按有效 Profile 排序并保留值，不允许字段由 Validator 报告、不自动删除。
+- **并发安全**：写入前在治理锁内复核内容哈希，外部变化返回 `concurrent-change` / `source-hash-changed`，拒绝覆盖。
+- **配置两层模型**：产品默认契约在包内 `resources/defaults/config.yml`（SSOT），用户只在 `~/.campfire/config.yml` 写覆盖项；Mapping 递归合并，`campfire workspace config check` 验证有效配置。
+
+## Agent 协作
+
+全局 Skill（`campfire skill list` 查看托管清单，`campfire skill sync` 手动同步）定义了 Agent 的标准工作流：先 `workspace resolve` 解析上下文，再读取目标 Workspace 的 `AGENTS.md`；只读检查可直接执行，`restructure apply`、`maintenance apply`、`archive apply` 必须先审查计划并用显式确认参数。有歧义的分类和重构进入 Decision 待确认，不由 Agent 擅自决定。
+
+## 许可
+
+MIT。

{campfire_cli-0.1.4 → campfire_cli-0.1.6}/SPEC.md

@@ -7,6 +7,8 @@
 ```text
 CLI delivery adapter
         ↓
+AppContainer 组合根，承担跨 App 编排
+        ↓
 Workspace Restructure / Maintenance Service
         ↓
 消费方 Protocol
@@ -17,6 +19,8 @@ SQLite / Filesystem Implementation
 - `app/` 放业务模块与 CLI 适配器。
 - `common/` 放两个 App 共同使用的文档治理原子能力和技术机制。
 - `config/` 放随 Workspace 或运行环境变化的配置。
+- 跨 App 的用例编排放 `AppContainer` 组合根，`setup` 与 `upgrade` 是当前实例；CLI 不编排跨服务流程，单个 App Service 不直接调用其他 App 的 Service。
+- 纯技术机制放 `common/`，例如网络查询、版本比较与进程编排；不得包含治理业务语义，也不得反向依赖 `app/`。
 - `resources/defaults/config.yml` 是产品默认规则的唯一 SSOT；Service 不得重复声明可演进的目录、类型、状态、归档或 Issue 规则。
 - CLI 通过用户级 registry 管理多个 Workspace，不依赖任何 Workspace 内的工具目录。
 - Markdown 是内容事实来源；包内 `config.yml` 与可选的 `~/.campfire/config.yml` 覆盖共同形成有效治理契约；`~/.campfire/campfire.db` 是唯一数据库，保存 Workspace/Project 注册数据、按 Workspace 隔离的可重建索引和工作流状态。
@@ -30,6 +34,34 @@ SQLite / Filesystem Implementation
 
 代码风格参考 `templates/fastapi-template`，但不引入 HTTP、WebSocket、认证和异步数据库等无关能力。
 
+## CLI 输出契约
+
+- 正常输出 indent JSON；错误输出单行 JSON 并写 stderr，退出码非 0。
+- `status` 字段是 Agent 依赖的公共契约，只允许复用既有词汇，不得发明近义词。命令级词汇：ok、error、blocked、needs-input、needs-review、dry-run、synced、planned、ready、applied、issues-found、formatted、archived、up-to-date。文档、领域与 Decision 各有自己的字段词汇表。需要新状态先在本节登记。
+- 前置条件缺失时优先降级执行：能完成的部分照常完成，输出 `needs-input` 并以 `skipped` 字段显式列出被跳过的步骤，而非整体报错退出。
+
+## 升级语义
+
+- `campfire upgrade` 是唯一的幂等升级入口：先更新 Python 包本身，再对齐本机治理资源，覆盖 Schema 迁移、全局 Skill、Base 与提示词路标。
+- 包自更新按检测到的安装方式在独立进程中执行，当前支持 uv tool 与 pipx。更新脚本必须等待当前进程退出后再运行，因为 Windows 会锁定运行中的解释器与可执行文件，包管理器无法原地替换；成功后由新版代码完成资源对齐。
+- editable 源码安装、离线、无法识别安装方式时跳过包更新仅对齐资源，结果中以 `action` 与 `hint` 显式说明原因。
+- 自更新链使用的内部参数必须 `hidden=True`，`--skip-package` 是当前实例，不进入公共 CLI 契约。
+- 外部网络查询尽力而为，例如 PyPI 版本检测；失败或超时静默降级，不得让命令失败或明显变慢。
+
+## 开发纪律
+
+- 提交使用 conventional commits，类型限定为 feat、fix、perf、refactor、docs、chore，正文说明动机；纯重构独立成 commit，不与功能变更混排。
+- 行为保持型重构的验收等于两条同时满足：既有测试不改断言仍通过，真实数据上新旧输出全等对比。只过测试不足以证明行为未变。
+- Windows 不变量：进程探活用 `psutil.pid_exists`，不用 `os.kill(pid, 0)`，后者在 Windows 等价于发送 CTRL_C_EVENT；CLI 入口处对 stdout/stderr 执行 UTF-8 reconfigure。
+
+## 注释与文档字符串
+
+以 PEP 8 与 PEP 257 为基线，外加两条本项目的硬规则：
+
+- 注释只写代码本身表达不了的约束：为什么这样做、什么条件下不能改。不写下一行做什么，不写给评审者看的改动说明，不重复代码；只对本次改动有意义的内容进提交说明，不进代码。
+- Docstring 是 API 契约：摘要行一句话陈述行为，补充行写前置条件、返回语义与副作用，不描述实现步骤。
+- 注释是完整句子，与代码同语言；行内注释只用于取值域等代码无法自明的信息。
+
 ## 版本规范
 
 Campfire 使用语义化版本：

{campfire_cli-0.1.4 → campfire_cli-0.1.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "campfire-cli"
-version = "0.1.4"
+version = "0.1.6"
 description = "Local-first shared context and governance CLI for humans and agents"
 readme = "README.md"
 license = "MIT"
@@ -35,6 +35,9 @@ dev = [
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 python_files = ["test_*.py"]
+markers = [
+  "perf: 性能回归测试，只断言确定性计数，不断言墙钟时间",
+]
 
 [tool.ruff]
 line-length = 100

{campfire_cli-0.1.4 → campfire_cli-0.1.6}/src/campfire_cli/__init__.py

@@ -1,3 +1,3 @@
 """Campfire CLI package."""
 
-__version__ = "0.1.4"
+__version__ = "0.1.6"

{campfire_cli-0.1.4 → campfire_cli-0.1.6}/src/campfire_cli/app/document/cli/document_cli.py

@@ -13,6 +13,7 @@ from campfire_cli.app.document.service.document_service import DocumentService
 from campfire_cli.app.workspace.repository.workspace_repository import SqliteWorkspaceRepository
 from campfire_cli.app.workspace.service.workspace_service import WorkspaceService
 from campfire_cli.common.exceptions import AppError
+from campfire_cli.common.filesystem.cwd import safe_cwd
 from campfire_cli.config.settings import WorkspaceSettings, campfire_home
 
 document_cli = typer.Typer(
@@ -27,7 +28,7 @@ def service(ctx: typer.Context) -> DocumentService:
     selector = ctx.find_root().params.get("workspace")
     root = campfire_home()
     resolution = WorkspaceService(root, SqliteWorkspaceRepository(root)).resolve(
-        selector, Path.cwd()
+        selector, safe_cwd()
     )
     settings = WorkspaceSettings.load(resolution.workspace_id, Path(resolution.workspace))
     return DocumentService(settings)
@@ -47,6 +48,12 @@ def check(ctx: typer.Context, path: str = typer.Option(..., "--path")) -> None:
     invoke(lambda: service(ctx).check(path))
 
 
+@document_cli.command("kanban-check")
+def kanban_check(ctx: typer.Context, path: str = typer.Option(..., "--path")) -> None:
+    """检查文档是否满足 Obsidian Kanban 插件的渲染契约。"""
+    invoke(lambda: service(ctx).kanban_check(path))
+
+
 @document_cli.command("inspect")
 def inspect(ctx: typer.Context, path: str = typer.Option(..., "--path")) -> None:
     """返回 Agent 治理单篇文档所需的类型、Profile、领域和问题上下文。"""

{campfire_cli-0.1.4 → campfire_cli-0.1.6}/src/campfire_cli/app/document/cli/profile_cli.py

@@ -16,6 +16,7 @@ from campfire_cli.app.document.service.document_profile_service import (
 from campfire_cli.app.workspace.repository.workspace_repository import SqliteWorkspaceRepository
 from campfire_cli.app.workspace.service.workspace_service import WorkspaceService
 from campfire_cli.common.exceptions import AppError
+from campfire_cli.common.filesystem.cwd import safe_cwd
 from campfire_cli.config.settings import WorkspaceSettings, campfire_home
 
 profile_cli = typer.Typer(
@@ -28,7 +29,7 @@ def service(ctx: typer.Context) -> DocumentProfileService:
     selector = ctx.find_root().params.get("workspace")
     root = campfire_home()
     resolution = WorkspaceService(root, SqliteWorkspaceRepository(root)).resolve(
-        selector, Path.cwd()
+        selector, safe_cwd()
     )
     settings = WorkspaceSettings.load(resolution.workspace_id, Path(resolution.workspace))
     return DocumentProfileService(

{campfire_cli-0.1.4 → campfire_cli-0.1.6}/src/campfire_cli/app/document/cli/type_cli.py

@@ -14,6 +14,7 @@ from campfire_cli.app.document.service.document_type_service import DocumentType
 from campfire_cli.app.workspace.repository.workspace_repository import SqliteWorkspaceRepository
 from campfire_cli.app.workspace.service.workspace_service import WorkspaceService
 from campfire_cli.common.exceptions import AppError
+from campfire_cli.common.filesystem.cwd import safe_cwd
 from campfire_cli.config.settings import WorkspaceSettings, campfire_home
 
 type_cli = typer.Typer(
@@ -26,7 +27,7 @@ def service(ctx: typer.Context) -> DocumentTypeService:
     selector = ctx.find_root().params.get("workspace")
     root = campfire_home()
     resolution = WorkspaceService(root, SqliteWorkspaceRepository(root)).resolve(
-        selector, Path.cwd()
+        selector, safe_cwd()
     )
     settings = WorkspaceSettings.load(resolution.workspace_id, Path(resolution.workspace))
     return DocumentTypeService(

{campfire_cli-0.1.4 → campfire_cli-0.1.6}/src/campfire_cli/app/document/service/document_rule_service.py

@@ -233,6 +233,17 @@ class DocumentRuleService:
     def known_fields(self) -> set[str]:
         return self._profiles.known_fields()
 
+    def field_order_for(
+        self, frontmatter: dict[str, Any], path: Path | None = None
+    ) -> list[str]:
+        """返回文档在当前治理契约下的有效 Profile 字段序。
+
+        写入口修改 frontmatter 后必须按此序插入新增字段，否则文档立即产生
+        frontmatter-field-order-invalid。
+        """
+        profile = self._profiles.resolve(frontmatter.get("type"), frontmatter, path)
+        return list(profile.field_order)
+
     def validate_patch(
         self,
         root: Path,

{campfire_cli-0.1.4 → campfire_cli-0.1.6}/src/campfire_cli/app/document/service/document_service.py

@@ -6,6 +6,10 @@ from typing import Any
 from campfire_cli.app.document.service.document_rule_service import DocumentRuleService
 from campfire_cli.app.document.service.document_scanner import exempt_document
 from campfire_cli.app.document.service.frontmatter_formatter import format_text
+from campfire_cli.app.document.service.kanban_service import (
+    check_kanban_renderability,
+    renderability_result,
+)
 from campfire_cli.app.document.service.profile_registry import ProfileRegistry
 from campfire_cli.common.documents.markdown import parse_document
 from campfire_cli.common.exceptions import ConfigurationError, GovernanceBlockedError
@@ -33,6 +37,16 @@ class DocumentService:
             "issues": issues,
         }
 
+    def kanban_check(self, relative_path: str) -> dict[str, Any]:
+        path = self._document_path(relative_path)
+        if self._is_exempt(path):
+            return self._not_applicable(relative_path, path)
+        issues = check_kanban_renderability(path.read_text(encoding="utf-8"))
+        return {
+            **renderability_result(relative_path, issues),
+            "workspace_id": self._settings.workspace_id,
+        }
+
     def inspect(self, relative_path: str) -> dict[str, Any]:
         path = self._document_path(relative_path)
         if self._is_exempt(path):

campfire_cli-0.1.6/src/campfire_cli/app/document/service/kanban_service.py

@@ -0,0 +1,74 @@
+"""
+SPEC:
+  name: kanban_service
+  purpose: 校验 Markdown 文档是否满足 Obsidian Kanban 插件的渲染契约
+  default_env_file: none
+  env_override: none
+  idempotent: true
+  behavior:
+    - 只读检查 frontmatter 与正文结构，输出确定性 issue 列表
+    - 不修改文档；改造由 Agent 按 skill 流程完成
+  safety:
+    - 不把渲染契约混入 Frontmatter Profile 契约，两者正交
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from campfire_cli.common.documents.markdown import parse_document
+
+LANE_RE = re.compile(r"^##\s+\S")
+COMMENT_START_RE = re.compile(r"^(<!--|%%)")
+INDENTED_RE = re.compile(r"^\s+\S")
+
+
+def check_kanban_renderability(text: str) -> list[dict[str, str]]:
+    """返回文档渲染为 Obsidian Kanban 看板的阻碍项；空列表即可渲染。
+
+    契约按真实看板校准：frontmatter 含 kanban-plugin 键；正文由 `## 泳道`
+    标题分区，卡片为列表项；泳道前的 H1 标题与引用块导言、`%%` 设置块、
+    卡片的缩进续行都被插件容忍，不视为阻碍。
+    """
+    parsed = parse_document(text)
+    issues: list[dict[str, str]] = []
+    plugin = parsed.frontmatter.get("kanban-plugin") if parsed.has_frontmatter else None
+    if not isinstance(plugin, str) or not plugin.strip():
+        issues.append({"code": "kanban-plugin-missing"})
+    lane_seen = False
+    comment_block = False
+    for number, raw in enumerate(parsed.body.splitlines(), start=1):
+        stripped = raw.strip()
+        if comment_block:
+            if stripped == "%%" or stripped.endswith("%%"):
+                comment_block = False
+            continue
+        if not stripped:
+            continue
+        if stripped.startswith("%%") and not stripped.endswith("%%"):
+            comment_block = True
+            continue
+        if LANE_RE.match(raw):
+            lane_seen = True
+            continue
+        if COMMENT_START_RE.match(stripped) or raw.startswith("#") or stripped.startswith(">"):
+            continue
+        if INDENTED_RE.match(raw) or stripped.startswith("-"):
+            if not lane_seen:
+                issues.append({"code": "kanban-card-outside-lane", "detail": f"line {number}"})
+            continue
+        issues.append({"code": "kanban-line-not-card", "detail": f"line {number}"})
+    if not lane_seen:
+        issues.append({"code": "kanban-lane-missing"})
+    return issues
+
+
+def renderability_result(relative_path: str, issues: list[dict[str, str]]) -> dict[str, Any]:
+    return {
+        "status": "ok" if not issues else "needs-review",
+        "path": relative_path,
+        "renderable": not issues,
+        "issue_count": len(issues),
+        "issues": issues,
+    }

{campfire_cli-0.1.4 → campfire_cli-0.1.6}/src/campfire_cli/app/maintenance/schema/maintenance_schema.py

@@ -62,6 +62,7 @@ class MaintenanceResult(BaseModel):
     blocked_scope: str | None = None
     issue_counts: dict[str, int] = Field(default_factory=dict)
     operations: list[dict[str, Any]] = Field(default_factory=list)
+    candidates: list[dict[str, Any]] = Field(default_factory=list)
     scope: str | None = None
     workspace_status: str | None = None
     space_count: int = 0