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

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

@@ -80,6 +80,55 @@ Document App 是所有面向用户和 Agent 的文档命令入口；Profile、
 
 Frontmatter 规则采用声明式 Profile：`base` 是最小公共契约，`knowledge`、`project-doc`、`task` 只允许一层继承。Profile Loader 将配置编译为完整 EffectiveProfile，Resolver 根据文档类型和领域上下文选择 Profile，Validator 与 Formatter 共同消费该结果。字段规则不使用每种文档一个 Python 子类，也不在 Skill 中复制。
 
+### CLI 设计理念：治理原语 + Skill SOP
+
+Campfire 不是“Markdown 版 kubectl”，而是面向人机协作场景组合成熟 CLI 经验形成的独立设计。它在资源心智模型、`apply` 语义和机器可读接口上借鉴 kubectl，在“计划—审查—执行”上借鉴 Terraform，在稳定原语与上层工作流分离上借鉴 Git/Unix；Markdown SSOT、Agent 语义判断和显式 Maintenance 则是 Campfire 自身边界。
+
+| 参考 | Campfire 采用的部分 | Campfire 不照搬的部分 |
+| --- | --- | --- |
+| [kubectl 命令与资源模型](https://kubernetes.io/docs/reference/kubectl/) | 按对象域组织命令、用 `apply` 统一创建与更新、显式选择作用域、提供稳定机器输出 | 不复制 `kubectl <verb> <type> <name>` 语法，不引入 API Server、Controller 或持续调谐 |
+| [kubectl 声明式 apply](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/declarative-config/) | 目标不存在时创建、存在时更新；把“期望变更”交给工具校验和执行 | 不保存 `last-applied-configuration`，不实现三方合并或字段所有权；Campfire apply 是 Profile 约束下的显式补丁 |
+| [Terraform plan/apply](https://developer.hashicorp.com/terraform/cli/commands/plan) | 写入前预览，可审查计划后再执行，执行前重新确认输入未漂移 | 不把所有日常写入都升级为持久计划；单文档原子修改保持轻量 |
+| [Git plumbing/porcelain](https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain) | CLI 提供可组合、可脚本化的稳定原语，Skill 组合成人类可理解的 SOP | 不暴露仅供内部实现使用的隐藏命令，不要求用户理解底层存储 |
+
+本文中的“原子命令”特指**意图原子命令**，不是把实现拆成最小文件操作或最小函数。一个公共命令需同时满足三层原子性：
+
+| 层次 | 规范 | 例子 |
+| --- | --- | --- |
+| 语义原子性 | 一条命令只表达一个可以用一句话说清的用户意图 | `document move` 表达“在已声明 Domain 之间正确移动一篇文档” |
+| 一致性原子性 | 为保持该意图不变量而必须一起变更的事实，属于同一个变更集；整体成功或恢复到执行前 | 移动文档时同步修复可确定解析的引用 |
+| 可组合原子性 | 不相关的派生治理不隐式执行；命令用结构化 `follow_up` 声明后续步骤，由 Skill 决定组合顺序 | `document apply` 不自动运行 `maintenance sync/check` |
+
+命令副作用按下列边界分类：
+
+- **必须纳入当前事务**：不执行就会让当前意图产生破损状态的变更，例如结构迁移时的 Domain 声明、Project 归属和可移植 Manifest 对齐。
+- **必须显式返回**：可从原始事实重建的派生结果，例如 MOC、关系页、索引和治理报告；这些作为 `follow_up` 由 Skill 显式执行。
+- **禁止捎带**：与当前意图无关的全 Workspace 格式化、归档、结构重构或其他写操作。
+
+“一次改多个文件”不等于不原子；“一次只改一个字段”也不自动等于边界正确。评审新命令时必须逐项回答：
+
+1. 用户意图能否用一句话准确表达？
+2. 对象和作用域是否显式？
+3. 所有被修改的事实是否都是维持该意图不变量所必需？
+4. 预览和 JSON 输出能否完整说明变更、阻断和后续操作？
+5. 重复执行是否幂等，或至少以稳定结果明确拒绝？
+6. 预览后的并发变更是否会被锁与快照复核阻断？
+7. 可重建的派生工作是否作为可组合 `follow_up` 返回？
+
+命令设计遵循以下约束：
+
+1. **对象域优先**：公共入口采用 `campfire <object-domain> <verb>`，例如 `document apply`、`maintenance check`；动词在所属业务对象内保持单义，不为同一行为保留多个别名。
+2. **意图原子、派生显式**：`document apply` 只创建或更新目标文档，`document move` 原子完成单文档移动、目标 Profile 对齐和确定性引用修复；MOC、关系页和索引治理由 Skill 显式编排 `maintenance sync/check`。
+3. **契约声明式，变更显式**：Profile 是字段、类型、枚举、顺序和条件必填的 SSOT。Agent 提交业务值，CLI 解析有效 Profile 并拒绝猜测；已有文档只修改明确给出的字段或正文操作。
+4. **写入先证明安全**：写命令默认预览，显式确认后才提交；提交时在锁内复核快照或期望哈希，多文件变更作为一个 ChangeSet 执行，失败回滚，避免静默覆盖和部分写入。
+5. **人类与 Agent 共用一个契约**：命令和结果只有一套语义。JSON 状态、issues、missing fields 与 follow-up 供 Agent 稳定消费，`tree` 和分层 `-h` 供人类与 Agent 渐进发现，不维护第二套参数目录。
+6. **语义与机制分层**：人类决定高风险取舍，Agent 理解正文和业务语义，Skill 规定加载时机、事实门禁与 SOP，CLI 只执行可确定验证的治理机制。歧义进入 Decision，不为“自动化成功”而猜测。
+7. **聚合入口是少数例外**：`setup` 和 `upgrade` 可以编排多个服务，因为它们表达完整安装生命周期；日常内容治理保持原子能力，避免重新出现 `maintenance run` 一类不可审查的聚合入口。
+
+横切关注点与业务 SOP 不使用同一种复用手段。哈希复核、写锁、原子替换和失败恢复由显式 ChangeSet Executor 复用；`apply → sync → check` 等业务顺序由 Skill 明文编排。不为了复用 Maintenance 而引入 AOP 切面、命令总线、全局钩子或隐式中间件。
+
+因此，`document apply` 的准确含义是“对一个 Markdown 文档应用经 Profile 校验的显式意图”，不是“把完整声明持续调谐到某个服务端状态”。用户或 Agent 可以直接 edit 已有正文；无论通过 apply 还是 edit 写入，跨文档派生结果都由后续显式 Maintenance 收敛。
+
 ## 5. SSOT 与派生数据
 
 | 数据 | 唯一事实来源 | 派生或运行副本 |
@@ -132,7 +181,7 @@ SQLite 中的 `spaces`、`domains` 与 `documents` 是本机查询投影，不
 
 ### 存量文件夹接管
 
-Adoption 是首次接管边界，不属于日常 Maintenance。外部目录只读并复制到 `_收件箱/待接管/<batch>`，Vault 内目录原地冻结事实；两者随后通过同一份计划建立一个粗粒度 Domain。CLI 负责文件清单、哈希、软链接与冲突保护、声明、MOC、Project/Manifest 联动和索引；Agent 负责阅读正文、选择目标 Space/Domain，并在接管后继续生成格式治理或子领域重构计划。
+Adoption 是首次接管边界，不属于日常 Maintenance。外部目录只读并复制到 `_收件箱/待接管/<batch>`，Vault 内目录原地冻结事实；两者随后通过同一份计划建立一个粗粒度 Domain。CLI 负责文件清单、哈希、软链接与冲突保护、声明、初始 MOC 和 Project/Manifest 联动；Agent 负责阅读正文、选择目标 Space/Domain，并按 `follow_up` 显式刷新派生视图与索引。
 
 ## 6. 本地 Web 工作台
 

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

@@ -3,7 +3,7 @@
 人类与 Agent 先用 `campfire tree` 发现命令，再用任意层级的 `-h` 渐进加载参数。
 
 ```bash
-campfire setup --workspace <vault-path> --default
+campfire setup --workspace <vault-path> [--id <workspace-id>] --default
 campfire upgrade
 campfire skill sync
 campfire base sync
@@ -14,7 +14,6 @@ campfire workspace adopt inventory --source <folder> --batch <id> [--confirm]
 campfire workspace adopt plan --batch <id> --target-path <path> --domain-id <id> --name <name> --space <id> --type <type> --governance <policy> [--parent-domain <id>] [--project <id>]
 campfire workspace adopt apply --batch <id> [--confirm]
 campfire workspace adopt verify --batch <id>
-campfire workspace attach --path <vault-path> --default
 campfire workspace project bind --id <project-id> --local-path <repository-path>
 campfire workspace space list
 campfire workspace space check
@@ -28,6 +27,8 @@ campfire workspace restructure domain rename --domain <id> --name <name> [--rena
 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]
 campfire workspace project resolve --path "$PWD"
+campfire document apply --path <workspace-relative-markdown> --type <type> --set <field=value> [--body-file <path>] [--confirm]
+campfire document move --from <source> --to <target> [--set <field=value>] [--unset <field>] [--expected-hash <sha256>] [--confirm]
 campfire document inspect --path <file>
 campfire document type list
 campfire document profile list
@@ -46,4 +47,4 @@ campfire maintenance verify --plan <plan-id>
 campfire maintenance sync --scope <path> --dry-run
 ```
 
-Space、Domain、Project 的 `create`、存量目录的 `space/domain adopt`，以及文档重构、归档写操作默认先预览；审查通过后才追加 `--confirm`。`adopt` 只新增声明文件和必要 MOC，不移动已有内容。具体参数以对应命令的 `-h` 为准，避免在文档中维护第二份参数目录。
+Space、Domain、Project 的 `create`、存量对象的 `adopt`，以及文档移动、重构、归档写操作默认先预览；审查通过后才追加 `--confirm`。`document move` 可在任意已声明 Domain 之间移动单篇文档，自动对齐可确定的 `domain`/`project` 归属；目标 Profile 缺失语义字段时返回 `needs-input`，调用方通过 `--set`/`--unset` 显式补齐。`adopt` 只接入已有对象，不移动已有内容。具体参数以对应命令的 `-h` 为准，避免在文档中维护第二份参数目录。

{campfire_cli-0.1.6 → campfire_cli-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: campfire-cli
-Version: 0.1.6
+Version: 0.1.7
 Summary: Local-first shared context and governance CLI for humans and agents
 License-Expression: MIT
 License-File: LICENSE
@@ -94,6 +94,7 @@ campfire maintenance sync [--dry-run] [--scope]  # 刷新 MOC 与相关文档页
 campfire maintenance archive check / apply       # 归档候选检查与执行
 
 campfire document inspect / check / format       # 单篇文档查看、校验、格式化
+campfire document apply / move                   # 单篇文档创建更新、跨 Domain 移动
 campfire document profile list / show / resolve  # Frontmatter Profile 规则
 campfire document type list                      # 文档类型与前缀
 
@@ -106,7 +107,7 @@ campfire decision create / list / answer / close # 持久决策通道
 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 \
+campfire workspace project adopt --id example --workspace personal \
   --name "Example" --document-domain "work/example" --local-path /path/to/repo
 campfire workspace rebuild --confirm             # 索引损坏时从 SSOT 完整恢复
 ```
@@ -124,7 +125,7 @@ campfire workspace adopt apply --batch notes-001 --confirm
 campfire workspace adopt verify --batch notes-001
 ```
 
-跨目录重构先冻结范围，再传入 YAML/JSON 意图规格（含 Frontmatter 修改），逐项审查 `approved` 后执行：
+单篇文档在已声明 Domain 之间移动使用 `document move`。批量文档或 Domain 结构重构先冻结范围，再传入 YAML/JSON 意图规格（含 Frontmatter 修改），逐项审查 `approved` 后执行：
 
 ```bash
 campfire workspace restructure inventory --scope work --batch move-001
@@ -139,7 +140,8 @@ campfire workspace restructure verify --batch move-001
 
 - **校验分工**：`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`，拒绝覆盖。
+- **并发与提交安全**：写入前在治理锁内复核内容哈希，外部变化返回 `concurrent-change` / `source-hash-changed`，拒绝覆盖；多文件写入和路径移动经同一 ChangeSet 提交，失败恢复到执行前。
+- **显式后续治理**：写入命令以轻量 `follow_up` 返回 `maintenance sync/check` 的 Workspace 和 scope；Skill 顺序执行，CLI 不隐式捎带派生治理。
 - **配置两层模型**：产品默认契约在包内 `resources/defaults/config.yml`（SSOT），用户只在 `~/.campfire/config.yml` 写覆盖项；Mapping 递归合并，`campfire workspace config check` 验证有效配置。
 
 ## Agent 协作

{campfire_cli-0.1.6 → campfire_cli-0.1.7}/README.md

@@ -78,6 +78,7 @@ campfire maintenance sync [--dry-run] [--scope]  # 刷新 MOC 与相关文档页
 campfire maintenance archive check / apply       # 归档候选检查与执行
 
 campfire document inspect / check / format       # 单篇文档查看、校验、格式化
+campfire document apply / move                   # 单篇文档创建更新、跨 Domain 移动
 campfire document profile list / show / resolve  # Frontmatter Profile 规则
 campfire document type list                      # 文档类型与前缀
 
@@ -90,7 +91,7 @@ campfire decision create / list / answer / close # 持久决策通道
 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 \
+campfire workspace project adopt --id example --workspace personal \
   --name "Example" --document-domain "work/example" --local-path /path/to/repo
 campfire workspace rebuild --confirm             # 索引损坏时从 SSOT 完整恢复
 ```
@@ -108,7 +109,7 @@ campfire workspace adopt apply --batch notes-001 --confirm
 campfire workspace adopt verify --batch notes-001
 ```
 
-跨目录重构先冻结范围，再传入 YAML/JSON 意图规格（含 Frontmatter 修改），逐项审查 `approved` 后执行：
+单篇文档在已声明 Domain 之间移动使用 `document move`。批量文档或 Domain 结构重构先冻结范围，再传入 YAML/JSON 意图规格（含 Frontmatter 修改），逐项审查 `approved` 后执行：
 
 ```bash
 campfire workspace restructure inventory --scope work --batch move-001
@@ -123,7 +124,8 @@ campfire workspace restructure verify --batch move-001
 
 - **校验分工**：`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`，拒绝覆盖。
+- **并发与提交安全**：写入前在治理锁内复核内容哈希，外部变化返回 `concurrent-change` / `source-hash-changed`，拒绝覆盖；多文件写入和路径移动经同一 ChangeSet 提交，失败恢复到执行前。
+- **显式后续治理**：写入命令以轻量 `follow_up` 返回 `maintenance sync/check` 的 Workspace 和 scope；Skill 顺序执行，CLI 不隐式捎带派生治理。
 - **配置两层模型**：产品默认契约在包内 `resources/defaults/config.yml`（SSOT），用户只在 `~/.campfire/config.yml` 写覆盖项；Mapping 递归合并，`campfire workspace config check` 验证有效配置。
 
 ## Agent 协作

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

@@ -105,7 +105,9 @@ Campfire 使用语义化版本：
 
 - SQLite `spaces`、`domains`、`documents` 只允许作为可重建本机投影，不得反向覆盖 Markdown SSOT。
 - `setup` 与 `maintenance check` 必须自动刷新完整拓扑和文档索引。
-- 领域重构完成后必须刷新受影响 MOC，并重建当前 Workspace 索引。
+- 领域重构只提交当前结构意图，并返回 scoped `maintenance sync` 与
+  `maintenance check` follow-up；调用方必须显式执行它们以刷新受影响 MOC
+  和当前 Workspace 索引。
 - `workspace rebuild` 默认只预览；`--confirm` 后从 Manifest 和 Markdown 完整替换派生索引。
 
 ## Workspace 接管

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

@@ -1,6 +1,6 @@
 [project]
 name = "campfire-cli"
-version = "0.1.6"
+version = "0.1.7"
 description = "Local-first shared context and governance CLI for humans and agents"
 readme = "README.md"
 license = "MIT"

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

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

campfire_cli-0.1.7/src/campfire_cli/app/base/schema/operation_schema.py

@@ -0,0 +1,23 @@
+from collections.abc import Iterable
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class CommandFollowUp(BaseModel):
+    """Describe one deterministic governance command that a caller should run next."""
+
+    command: Literal["maintenance sync", "maintenance check"]
+    workspace: str
+    scope: str
+
+
+def maintenance_follow_up(workspace: str, scopes: Iterable[str]) -> list[CommandFollowUp]:
+    """Build the ordered, deduplicated follow-up for derived workspace maintenance."""
+
+    unique_scopes = tuple(dict.fromkeys(scopes))
+    return [
+        CommandFollowUp(command=command, workspace=workspace, scope=scope)
+        for command in ("maintenance sync", "maintenance check")
+        for scope in unique_scopes
+    ]

{campfire_cli-0.1.6 → campfire_cli-0.1.7}/src/campfire_cli/app/document/SPEC.md

@@ -12,7 +12,11 @@ document/
 │   ├── document_cli.py
 │   ├── profile_cli.py
 │   └── type_cli.py
+├── schema/
+│   └── document_schema.py
 ├── service/
+│   ├── document_apply_service.py
+│   ├── document_move_service.py
 │   ├── document_profile_service.py
 │   ├── document_type_service.py
 │   ├── document_service.py
@@ -34,13 +38,17 @@ document/
 - `frontmatter`：检查、规划、执行和格式化文档属性。
 - `rule`：统一解释类型、Profile、枚举与跨字段不变量。
 - `inspect`：向 Agent 返回单篇文档的 Domain、类型、有效 Profile 和具体问题。
+- `apply`：根据目标路径和类型解析 Profile，不存在时生成文档，已存在时仅应用显式补丁；先完整渲染并校验，追加 `--confirm` 后原子写入。
+- `move`：在任意已声明 Domain 之间移动或改名一篇文档，按目标 Profile 对齐可确定的 `domain`/`project` 归属，并更新可确定解析的 Wiki、Markdown 和路径引用。目标 Profile 缺少业务字段时返回 `needs-input`，不猜测。
 - `scanner`：统一解释受管根、忽略目录和豁免文件；Document 与 Maintenance 共用。
 
 Document Service 可以被 Maintenance 和 Workspace Restructure 编排，但不得反向依赖它们。批量计划文件、运行记录、MOC、Base、归档和重构批次不属于 Document App。
 
+`apply` 与 `move` 只保证目标文档操作自身有效，不触发 Maintenance。Skill SOP 在写入后显式编排 scoped `maintenance sync` 和 `maintenance check`。所有写入先生成完整 ChangeSet，再经共享 Executor 在乐观锁内提交；多文件操作失败时恢复提交前内容。
+
 包内 `config.yml` 的默认 Profile 与用户级 `~/.campfire/config.yml` 覆盖共同构成当前治理契约。
 
-Profile 只允许一层 `base` 继承。Service 将声明配置编译为完整 `EffectiveProfile`；Validator、Formatter 和 CLI 必须消费同一结果，不得复制字段与枚举。
+Profile 只允许一层 `base` 继承。Service 将声明配置编译为完整 `EffectiveProfile`；Validator、Formatter 和 CLI 必须消费同一结果，不得复制字段、枚举与值类型。`value_types` 声明不能由 YAML 形状可靠推断的标量类型，当前支持 `string` 和 `boolean`。
 
 标准字段用于格式化、补全和校验。默认 `unknown_fields: preserve`：已有业务扩展字段不参与标准排序但必须原样保留，不因尚未建立专属 Profile 而制造全库噪声；确需封闭字段集合的 Profile 可显式设为 `report`。
 

campfire_cli-0.1.7/src/campfire_cli/app/document/cli/document_cli.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import typer
+import yaml
+from pydantic import BaseModel
+
+from campfire_cli.app.document.cli.profile_cli import profile_cli
+from campfire_cli.app.document.cli.type_cli import type_cli
+from campfire_cli.app.document.schema import DocumentApplyRequest
+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(
+    help="创建、检查和维护文档及其规则",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+document_cli.add_typer(profile_cli, name="profile")
+document_cli.add_typer(type_cli, name="type")
+
+
+def service(ctx: typer.Context) -> DocumentService:
+    selector = ctx.find_root().params.get("workspace")
+    root = campfire_home()
+    resolution = WorkspaceService(root, SqliteWorkspaceRepository(root)).resolve(
+        selector, safe_cwd()
+    )
+    settings = WorkspaceSettings.load(resolution.workspace_id, Path(resolution.workspace))
+    return DocumentService(settings)
+
+
+def invoke(operation: Callable[[], dict[str, Any] | BaseModel]) -> None:
+    try:
+        result = operation()
+        payload = result.model_dump(mode="json") if isinstance(result, BaseModel) else result
+        typer.echo(json.dumps(payload, ensure_ascii=False, indent=2))
+    except AppError as exc:
+        typer.echo(json.dumps({"status": "error", "message": str(exc)}, ensure_ascii=False))
+        raise typer.Exit(exc.exit_code) from exc
+
+
+@document_cli.command("check")
+def check(ctx: typer.Context, path: str = typer.Option(..., "--path")) -> None:
+    """检查一篇 Markdown 文档是否符合当前类型与 Profile 契约。"""
+    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、领域和问题上下文。"""
+    invoke(lambda: service(ctx).inspect(path))
+
+
+@document_cli.command("format")
+def format_document(
+    ctx: typer.Context,
+    path: str = typer.Option(..., "--path"),
+    confirm: bool = typer.Option(False, "--confirm"),
+) -> None:
+    """预览或执行一篇文档的 Frontmatter 字段排序。"""
+    invoke(lambda: service(ctx).format(path, confirm))
+
+
+def parse_values(items: list[str]) -> dict[str, Any]:
+    values: dict[str, Any] = {}
+    for item in items:
+        if "=" not in item:
+            raise typer.BadParameter(f"--set 必须使用 field=value：{item}")
+        key, raw = item.split("=", 1)
+        if not key.strip():
+            raise typer.BadParameter("--set 字段名不能为空")
+        key = key.strip()
+        if key in values:
+            raise typer.BadParameter(f"--set 字段重复：{key}")
+        values[key] = yaml.safe_load(raw)
+    return values
+
+
+@document_cli.command("apply")
+def apply_document(
+    ctx: typer.Context,
+    path: str = typer.Option(..., "--path"),
+    document_type: str | None = typer.Option(None, "--type"),
+    set_values: list[str] | None = typer.Option(None, "--set"),
+    body_file: Path | None = typer.Option(None, "--body-file"),
+    append_section: str | None = typer.Option(None, "--append-section"),
+    replace_body: bool = typer.Option(False, "--replace-body"),
+    expected_hash: str | None = typer.Option(None, "--expected-hash"),
+    confirm: bool = typer.Option(False, "--confirm"),
+) -> None:
+    """预览或应用一篇 Profile 合法文档的创建与补丁。"""
+    body = body_file.read_text(encoding="utf-8") if body_file else None
+    invoke(
+        lambda: service(ctx).apply(
+            DocumentApplyRequest(
+                path=path,
+                document_type=document_type,
+                values=parse_values(set_values or []),
+                body=body,
+                append_section=append_section,
+                replace_body=replace_body,
+                expected_hash=expected_hash,
+                confirm=confirm,
+            )
+        )
+    )
+
+
+@document_cli.command("move")
+def move_document(
+    ctx: typer.Context,
+    source: str = typer.Option(..., "--from"),
+    target: str = typer.Option(..., "--to"),
+    set_values: list[str] | None = typer.Option(None, "--set"),
+    unset_fields: list[str] | None = typer.Option(None, "--unset"),
+    expected_hash: str | None = typer.Option(None, "--expected-hash"),
+    confirm: bool = typer.Option(False, "--confirm"),
+) -> None:
+    """预览或移动一篇文档，并按目标 Domain 契约更新归属与引用。"""
+    invoke(
+        lambda: service(ctx).move(
+            source,
+            target,
+            values=parse_values(set_values or []),
+            unset_fields=tuple(unset_fields or []),
+            expected_hash=expected_hash,
+            confirm=confirm,
+        )
+    )

campfire_cli-0.1.7/src/campfire_cli/app/document/schema/__init__.py

@@ -0,0 +1,13 @@
+"""Typed document application contracts."""
+
+from campfire_cli.app.document.schema.document_schema import (
+    DocumentApplyRequest,
+    DocumentApplyResult,
+    DocumentMoveResult,
+)
+
+__all__ = [
+    "DocumentApplyRequest",
+    "DocumentApplyResult",
+    "DocumentMoveResult",
+]

campfire_cli-0.1.7/src/campfire_cli/app/document/schema/document_schema.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from campfire_cli.app.base.schema.operation_schema import CommandFollowUp
+
+
+class DocumentApplyRequest(BaseModel):
+    path: str
+    document_type: str | None = None
+    values: dict[str, Any] = Field(default_factory=dict)
+    body: str | None = None
+    append_section: str | None = None
+    replace_body: bool = False
+    expected_hash: str | None = None
+    confirm: bool = False
+
+
+class DocumentApplyResult(BaseModel):
+    status: Literal["planned", "needs-input", "blocked", "applied"]
+    workspace_id: str
+    action: Literal["create", "update"]
+    path: str
+    profile: str
+    expected_hash: str
+    write_performed: bool = False
+    issues: list[dict[str, Any]] = Field(default_factory=list)
+    missing_fields: list[str] = Field(default_factory=list)
+    follow_up: list[CommandFollowUp] = Field(default_factory=list)
+
+
+class DocumentMoveResult(BaseModel):
+    status: Literal["ready", "needs-input", "blocked", "moved"]
+    workspace_id: str
+    source: str
+    target: str
+    expected_hash: str
+    source_domain: str | None = None
+    target_domain: str | None = None
+    profile: str | None = None
+    write_performed: bool = False
+    updated_references: list[str] = Field(default_factory=list)
+    frontmatter_changes: dict[str, Any] = Field(default_factory=dict)
+    issues: list[dict[str, Any]] = Field(default_factory=list)
+    missing_fields: list[str] = Field(default_factory=list)
+    follow_up: list[CommandFollowUp] = Field(default_factory=list)