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

{campfire_cli-0.1.7 → campfire_cli-0.1.8}/.github/workflows/ci.yml

@@ -15,8 +15,8 @@ jobs:
     env:
       PYTHONUTF8: "1"
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v5
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v10.1.0
         with:
           enable-cache: true
           cache-dependency-glob: "uv.lock"

{campfire_cli-0.1.7 → campfire_cli-0.1.8}/.github/workflows/release.yml

@@ -11,8 +11,8 @@ jobs:
       id-token: write
       contents: read
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v5
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v10.1.0
       - name: Build
         run: uv build
       - name: Publish to PyPI

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

@@ -97,7 +97,7 @@ Campfire 不是“Markdown 版 kubectl”，而是面向人机协作场景组合
 | --- | --- | --- |
 | 语义原子性 | 一条命令只表达一个可以用一句话说清的用户意图 | `document move` 表达“在已声明 Domain 之间正确移动一篇文档” |
 | 一致性原子性 | 为保持该意图不变量而必须一起变更的事实，属于同一个变更集；整体成功或恢复到执行前 | 移动文档时同步修复可确定解析的引用 |
-| 可组合原子性 | 不相关的派生治理不隐式执行；命令用结构化 `follow_up` 声明后续步骤，由 Skill 决定组合顺序 | `document apply` 不自动运行 `maintenance sync/check` |
+| 可组合原子性 | 不相关的派生治理不隐式执行；命令用结构化 `follow_up` 声明必要步骤，由 Skill 决定组合顺序 | `document apply` 只在必要时返回一个 scoped `maintenance sync` |
 
 命令副作用按下列边界分类：
 
@@ -118,14 +118,14 @@ Campfire 不是“Markdown 版 kubectl”，而是面向人机协作场景组合
 命令设计遵循以下约束：
 
 1. **对象域优先**：公共入口采用 `campfire <object-domain> <verb>`，例如 `document apply`、`maintenance check`；动词在所属业务对象内保持单义，不为同一行为保留多个别名。
-2. **意图原子、派生显式**：`document apply` 只创建或更新目标文档，`document move` 原子完成单文档移动、目标 Profile 对齐和确定性引用修复；MOC、关系页和索引治理由 Skill 显式编排 `maintenance sync/check`。
+2. **意图原子、派生显式**：`document apply` 只创建或更新目标文档，`document move` 原子完成单文档移动、目标 Profile 对齐和确定性引用修复；命令只在 MOC、关系页或索引可能变化时返回一个最小 scope 的 `maintenance sync`。
 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 切面、命令总线、全局钩子或隐式中间件。
+横切关注点与业务 SOP 不使用同一种复用手段。哈希复核、写锁、原子替换和失败恢复由显式 ChangeSet Executor 复用；写命令返回的 `follow_up` 由 Skill 消费。不为了复用 Maintenance 而引入 AOP 切面、命令总线、全局钩子或隐式中间件。
 
 因此，`document apply` 的准确含义是“对一个 Markdown 文档应用经 Profile 校验的显式意图”，不是“把完整声明持续调谐到某个服务端状态”。用户或 Agent 可以直接 edit 已有正文；无论通过 apply 还是 edit 写入，跨文档派生结果都由后续显式 Maintenance 收敛。
 
@@ -181,7 +181,7 @@ SQLite 中的 `spaces`、`domains` 与 `documents` 是本机查询投影，不
 
 ### 存量文件夹接管
 
-Adoption 是首次接管边界，不属于日常 Maintenance。外部目录只读并复制到 `_收件箱/待接管/<batch>`，Vault 内目录原地冻结事实；两者随后通过同一份计划建立一个粗粒度 Domain。CLI 负责文件清单、哈希、软链接与冲突保护、声明、初始 MOC 和 Project/Manifest 联动；Agent 负责阅读正文、选择目标 Space/Domain，并按 `follow_up` 显式刷新派生视图与索引。
+Adoption 是首次接管边界，不属于日常 Maintenance。`workspace domain adopt` 一次完成只读盘点、预览和确认后的原子接管，不持久化中间批次。外部目录通过临时隐藏目录复制并校验，原来源保持不变；Vault 内目录原地声明或移动到目标。CLI 负责哈希、软链接与冲突保护、声明、初始 MOC 和 Project/Manifest 联动；Agent 负责阅读正文、选择目标 Space/Domain，并执行返回的 `follow_up`。
 
 ## 6. 本地 Web 工作台
 

campfire_cli-0.1.8/COMMAND.md

@@ -0,0 +1,44 @@
+# Campfire 稳定命令
+
+人类与 Agent 先用 `campfire tree` 发现命令，再用任意层级的 `-h` 渐进加载参数。
+
+```bash
+campfire setup --workspace <vault-path> [--id <workspace-id>] --default
+campfire upgrade
+campfire skill sync
+campfire base sync
+campfire workspace resolve
+campfire workspace rebuild
+campfire workspace rebuild --confirm
+campfire workspace project bind --id <project-id> --local-path <repository-path>
+campfire workspace space list
+campfire workspace space check
+campfire workspace space check --space <space-id>
+campfire workspace config check
+campfire workspace domain list
+campfire workspace domain check
+campfire workspace domain adopt --source <folder> --target-path <path> --id <id> --name <name> --space <id> --type <type> --governance <policy> [--parent <id>] [--project <id>] [--confirm]
+campfire workspace domain rename --domain <id> --name <name> [--rename-directory|--target-path <path>] [--project-name <name>] [--confirm]
+campfire workspace domain move --domain <id> --target-path <path> [--parent-domain <id>] [--confirm]
+campfire workspace domain rekey --domain <id> --new-id <id> [--confirm]
+campfire workspace restructure inventory --scope <path> --batch <id>
+campfire workspace restructure plan --batch <id>
+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
+campfire decision create --key <key> --question <question> --source-type <source>
+campfire decision list --status pending
+campfire decision show <decision-id>
+campfire decision answer <decision-id> --answer <answer> --answered-by <actor>
+campfire decision close <decision-id>
+campfire decision sync
+campfire maintenance check --summary
+campfire maintenance sync --scope <path> [--dry-run]
+campfire maintenance archive check [--scope <path>]
+campfire maintenance archive apply [--scope <path>] --confirm
+```
+
+Space、Domain、Project 的 `create`/`adopt`，以及文档移动、重构、归档写操作默认先预览；审查通过后才追加 `--confirm`。`document apply` 可新建、更新或为已有正文补齐 Frontmatter；`document move` 可在任意已声明 Domain 之间移动单篇文档并对齐可确定的 `domain`/`project`。目标 Profile 缺少语义字段时返回 `missing_fields`，调用方用 `--set`/`--unset` 补齐。写命令只返回实际需要的一个 scoped `maintenance sync` follow-up，没有派生影响时返回空列表。具体参数以对应命令的 `-h` 为准。

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: campfire-cli
-Version: 0.1.7
+Version: 0.1.8
 Summary: Local-first shared context and governance CLI for humans and agents
 License-Expression: MIT
 License-File: LICENSE
@@ -114,15 +114,13 @@ campfire workspace rebuild --confirm             # 索引损坏时从 SSOT 完
 
 ## 存量接管与结构重构
 
-`workspace adopt` 负责首次接管已有文件夹：Vault 外来源先按哈希复制到 `_收件箱/待接管/<batch>`（原目录始终保留），Vault 内来源原地盘点；一次建立一个粗粒度 Domain，语义细分交给后续 Maintenance/Restructure 计划。
+`workspace domain adopt` 用一条命令接管一个已有文件夹。Vault 外来源经临时暂存和哈希校验复制到目标 Domain，原目录始终保留；Vault 内来源原地声明或移动到明确目标。命令一次建立一个粗粒度 Domain，语义细分交给后续 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 \
+campfire workspace domain adopt --source /path/to/folder --target-path "mynote/新领域" \
+  --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
+# 审查同一份结构化计划后，对相同命令追加 --confirm
 ```
 
 单篇文档在已声明 Domain 之间移动使用 `document move`。批量文档或 Domain 结构重构先冻结范围，再传入 YAML/JSON 意图规格（含 Frontmatter 修改），逐项审查 `approved` 后执行：
@@ -141,12 +139,12 @@ 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`，拒绝覆盖；多文件写入和路径移动经同一 ChangeSet 提交，失败恢复到执行前。
-- **显式后续治理**：写入命令以轻量 `follow_up` 返回 `maintenance sync/check` 的 Workspace 和 scope；Skill 顺序执行，CLI 不隐式捎带派生治理。
+- **按需后续治理**：写入命令只在派生内容可能变化时返回一个最小 scope 的 `maintenance sync`；Skill 消费该结果，没有 follow-up 就结束，不固定追加 dry-run 或全量 check。
 - **配置两层模型**：产品默认契约在包内 `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 擅自决定。
+全局 Skill（`campfire skill list` 查看托管清单，`campfire skill sync` 手动同步）定义了 Agent 的标准工作流：首次读写先 `workspace resolve` 并读取 Workspace 的 `AGENTS.md`；单文档用 `document apply/move`，批量结构调整用 `workspace restructure`，归档用 `maintenance archive`。有歧义的分类和重构进入 Decision，不由 Agent 擅自决定。
 
 ## 许可
 

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

@@ -98,15 +98,13 @@ campfire workspace rebuild --confirm             # 索引损坏时从 SSOT 完
 
 ## 存量接管与结构重构
 
-`workspace adopt` 负责首次接管已有文件夹：Vault 外来源先按哈希复制到 `_收件箱/待接管/<batch>`（原目录始终保留），Vault 内来源原地盘点；一次建立一个粗粒度 Domain，语义细分交给后续 Maintenance/Restructure 计划。
+`workspace domain adopt` 用一条命令接管一个已有文件夹。Vault 外来源经临时暂存和哈希校验复制到目标 Domain，原目录始终保留；Vault 内来源原地声明或移动到明确目标。命令一次建立一个粗粒度 Domain，语义细分交给后续 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 \
+campfire workspace domain adopt --source /path/to/folder --target-path "mynote/新领域" \
+  --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
+# 审查同一份结构化计划后，对相同命令追加 --confirm
 ```
 
 单篇文档在已声明 Domain 之间移动使用 `document move`。批量文档或 Domain 结构重构先冻结范围，再传入 YAML/JSON 意图规格（含 Frontmatter 修改），逐项审查 `approved` 后执行：
@@ -125,12 +123,12 @@ 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`，拒绝覆盖；多文件写入和路径移动经同一 ChangeSet 提交，失败恢复到执行前。
-- **显式后续治理**：写入命令以轻量 `follow_up` 返回 `maintenance sync/check` 的 Workspace 和 scope；Skill 顺序执行，CLI 不隐式捎带派生治理。
+- **按需后续治理**：写入命令只在派生内容可能变化时返回一个最小 scope 的 `maintenance sync`；Skill 消费该结果，没有 follow-up 就结束，不固定追加 dry-run 或全量 check。
 - **配置两层模型**：产品默认契约在包内 `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 擅自决定。
+全局 Skill（`campfire skill list` 查看托管清单，`campfire skill sync` 手动同步）定义了 Agent 的标准工作流：首次读写先 `workspace resolve` 并读取 Workspace 的 `AGENTS.md`；单文档用 `document apply/move`，批量结构调整用 `workspace restructure`，归档用 `maintenance archive`。有歧义的分类和重构进入 Decision，不由 Agent 擅自决定。
 
 ## 许可
 

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

@@ -105,16 +105,15 @@ Campfire 使用语义化版本：
 
 - SQLite `spaces`、`domains`、`documents` 只允许作为可重建本机投影，不得反向覆盖 Markdown SSOT。
 - `setup` 与 `maintenance check` 必须自动刷新完整拓扑和文档索引。
-- 领域重构只提交当前结构意图，并返回 scoped `maintenance sync` 与
-  `maintenance check` follow-up；调用方必须显式执行它们以刷新受影响 MOC
-  和当前 Workspace 索引。
+- 写命令只在派生状态可能变化时返回一个 scoped `maintenance sync` follow-up；
+  调用方只执行实际返回的 follow-up，不固定追加 check 或全量扫描。
 - `workspace rebuild` 默认只预览；`--confirm` 后从 Manifest 和 Markdown 完整替换派生索引。
 
 ## Workspace 接管
 
-- 外部来源必须只读，先复制到 `_收件箱/待接管/<batch>`；不得删除或修改原目录。
+- 外部来源必须只读，经临时隐藏目录复制和哈希校验后落到目标；不得删除或修改原目录。
 - Vault 内来源原地盘点，不得重复复制。
-- 软链接、目标冲突、暂存冲突和源哈希变化必须 fail closed。
+- 软链接、目标冲突和源哈希变化必须 fail closed。
 - 接管计划一次建立一个粗粒度 Domain；CLI 不得自行推断文档语义或子领域。
-- `apply` 默认只预检，显式 `--confirm` 后才移动暂存内容并创建领域声明。
-- `verify` 必须核对接管文件、哈希和领域声明；接管后的格式与细分治理继续使用 Maintenance 和 Restructure。
+- `workspace domain adopt` 默认只预览，显式 `--confirm` 后在一个 ChangeSet 中移动或复制内容并创建领域声明。
+- 提交成功前必须核对接管文件、哈希和领域声明；接管后的细分治理继续使用 Restructure。

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

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

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

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

campfire_cli-0.1.8/src/campfire_cli/alembic/versions/008_remove_adoption_batches.py

@@ -0,0 +1,16 @@
+"""Remove obsolete multi-stage Workspace adoption state."""
+
+from alembic import op
+
+revision = "008"
+down_revision = "007"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.drop_table("adoption_batches")
+
+
+def downgrade() -> None:
+    raise RuntimeError("The adoption workflow consolidation is intentionally irreversible")

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

@@ -0,0 +1,33 @@
+from collections.abc import Iterable
+from pathlib import PurePosixPath
+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"]
+    workspace: str
+    scope: str
+
+
+def maintenance_sync_follow_up(workspace: str, scopes: Iterable[str]) -> list[CommandFollowUp]:
+    """Build one sync follow-up at the smallest scope containing all changes."""
+
+    paths = [PurePosixPath(scope.strip("/")) for scope in dict.fromkeys(scopes) if scope]
+    if not paths:
+        return []
+    common = list(paths[0].parts)
+    for path in paths[1:]:
+        shared: list[str] = []
+        for left, right in zip(common, path.parts, strict=False):
+            if left != right:
+                break
+            shared.append(left)
+        common = shared
+        if not common:
+            break
+    scope = PurePosixPath(*common).as_posix() if common else "."
+    return [CommandFollowUp(command="maintenance sync", workspace=workspace, scope=scope)]

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

@@ -2,7 +2,7 @@
 
 本模块承载面向用户和 Agent 的文档业务能力，包括单篇检查与格式化、类型契约、Profile 契约、命名和 Frontmatter 治理。
 
-Document App 负责文档自身及其规则；Maintenance App 负责跨文档统一计划、执行、验收和派生内容同步；Workspace Restructure 用例负责存量结构重构。纯解析、序列化和路径安全等无业务状态的原子能力保留在 `common/documents/`。
+Document App 负责单篇文档及其规则；Maintenance App 负责检查、派生内容同步和归档；Workspace Restructure 负责存量批量结构重构。纯解析、序列化和路径安全等无业务状态的原子能力保留在 `common/documents/`。
 
 ## 当前能力
 
@@ -38,13 +38,13 @@ document/
 - `frontmatter`：检查、规划、执行和格式化文档属性。
 - `rule`：统一解释类型、Profile、枚举与跨字段不变量。
 - `inspect`：向 Agent 返回单篇文档的 Domain、类型、有效 Profile 和具体问题。
-- `apply`：根据目标路径和类型解析 Profile，不存在时生成文档，已存在时仅应用显式补丁；先完整渲染并校验，追加 `--confirm` 后原子写入。
+- `apply`：根据目标路径和类型解析 Profile，不存在时生成文档，已有 Frontmatter 时只应用显式补丁，无 Frontmatter 时保留正文并补齐完整契约；先完整渲染并校验，追加 `--confirm` 后原子写入。
 - `move`：在任意已声明 Domain 之间移动或改名一篇文档，按目标 Profile 对齐可确定的 `domain`/`project` 归属，并更新可确定解析的 Wiki、Markdown 和路径引用。目标 Profile 缺少业务字段时返回 `needs-input`，不猜测。
 - `scanner`：统一解释受管根、忽略目录和豁免文件；Document 与 Maintenance 共用。
 
-Document Service 可以被 Maintenance 和 Workspace Restructure 编排，但不得反向依赖它们。批量计划文件、运行记录、MOC、Base、归档和重构批次不属于 Document App。
+Document Service 可以被 Workspace Restructure 编排，但不得反向依赖 Maintenance。批量计划文件、运行记录、MOC、Base、归档和重构批次不属于 Document App。
 
-`apply` 与 `move` 只保证目标文档操作自身有效，不触发 Maintenance。Skill SOP 在写入后显式编排 scoped `maintenance sync` 和 `maintenance check`。所有写入先生成完整 ChangeSet，再经共享 Executor 在乐观锁内提交；多文件操作失败时恢复提交前内容。
+`apply` 与 `move` 只保证目标文档操作自身有效，不触发 Maintenance。结果只在派生状态可能变化时返回一个最小 scope 的 `maintenance sync`；调用方不得固定追加 check。所有写入先生成完整 ChangeSet，再经共享 Executor 在乐观锁内提交；多文件操作失败时恢复提交前内容。
 
 包内 `config.yml` 的默认 Profile 与用户级 `~/.campfire/config.yml` 覆盖共同构成当前治理契约。
 

{campfire_cli-0.1.7 → campfire_cli-0.1.8}/src/campfire_cli/app/document/service/document_apply_service.py

@@ -4,7 +4,7 @@ from datetime import date
 from pathlib import Path
 from typing import Any
 
-from campfire_cli.app.base.schema.operation_schema import maintenance_follow_up
+from campfire_cli.app.base.schema.operation_schema import maintenance_sync_follow_up
 from campfire_cli.app.document.schema import (
     DocumentApplyRequest,
     DocumentApplyResult,
@@ -13,6 +13,10 @@ from campfire_cli.app.document.service.document_rule_service import DocumentRule
 from campfire_cli.app.document.service.frontmatter_formatter import render_patch
 from campfire_cli.app.document.service.profile_registry import ProfileRegistry
 from campfire_cli.common.documents.document_types import prefixed_name
+from campfire_cli.common.documents.domain_context import (
+    DomainContextError,
+    resolve_domain_context,
+)
 from campfire_cli.common.documents.markdown import parse_document, render_document
 from campfire_cli.common.exceptions import ConfigurationError, GovernanceBlockedError
 from campfire_cli.common.filesystem import FileChangeExecutor, FileChangeSet, FileWrite, safe_path
@@ -41,8 +45,6 @@ class DocumentApplyService:
         exists = path.is_file()
         original = path.read_text(encoding="utf-8") if exists else ""
         parsed = parse_document(original)
-        if exists and not parsed.has_frontmatter:
-            raise GovernanceBlockedError("已有文档缺少 Frontmatter，不能安全 apply")
 
         current_type = parsed.frontmatter.get("type")
         document_type = request.document_type or (
@@ -52,7 +54,12 @@ class DocumentApplyService:
             raise ConfigurationError("创建文档时必须提供 --type")
         if document_type not in self._settings.document_types.get("types", {}):
             raise ConfigurationError(f"未知文档类型：{document_type}")
-        if exists and request.document_type and current_type != request.document_type:
+        if (
+            exists
+            and parsed.has_frontmatter
+            and request.document_type
+            and current_type != request.document_type
+        ):
             raise GovernanceBlockedError("不允许通过 document apply 改变已有文档的 type")
 
         expected_name = prefixed_name(path.name, document_type, self._settings.document_types)
@@ -63,7 +70,7 @@ class DocumentApplyService:
 
         today = date.today().isoformat()
         frontmatter = dict(parsed.frontmatter)
-        if not exists:
+        if not exists or not parsed.has_frontmatter:
             frontmatter.update(self._creation_defaults(path, document_type, today))
         for key in ("project", "domain"):
             if key in request.values and request.values[key] != frontmatter.get(key):
@@ -81,6 +88,7 @@ class DocumentApplyService:
             return self._result(
                 request,
                 exists,
+                parsed.has_frontmatter,
                 profile.name,
                 actual_hash,
                 "blocked",
@@ -95,7 +103,7 @@ class DocumentApplyService:
             )
 
         next_body = self._next_body(request, parsed.body, exists)
-        if exists:
+        if exists and parsed.has_frontmatter:
             rendered, render_errors = render_patch(
                 original,
                 {**request.values, "updated": today},
@@ -106,6 +114,7 @@ class DocumentApplyService:
                 return self._result(
                     request,
                     exists,
+                    parsed.has_frontmatter,
                     profile.name,
                     actual_hash,
                     "blocked",
@@ -132,6 +141,7 @@ class DocumentApplyService:
         result = self._result(
             request,
             exists,
+            parsed.has_frontmatter,
             profile.name,
             actual_hash,
             status,
@@ -167,22 +177,20 @@ class DocumentApplyService:
             "updated": today,
             "tags": [],
         }
-        marker_name = self._settings.governance.get("domain_marker", "_领域.md")
-        current = path.parent
-        while current == self._settings.vault_root or self._settings.vault_root in current.parents:
-            marker = current / marker_name
-            if marker.is_file():
-                domain = parse_document(marker.read_text(encoding="utf-8")).frontmatter
-                if domain.get("domain_id"):
-                    values["domain"] = domain["domain_id"]
-                project = domain.get("project_id") or domain.get("project")
-                if project:
-                    values["project"] = project
-                return values
-            if current == self._settings.vault_root:
-                break
-            current = current.parent
-        raise ConfigurationError("正式文档必须位于已声明的 Domain 内")
+        try:
+            context = resolve_domain_context(
+                self._settings.vault_root,
+                path,
+                self._settings.governance.get("domain_marker", "_领域.md"),
+            )
+        except DomainContextError as exc:
+            raise ConfigurationError(
+                f"无法解析目标 Domain 上下文：{exc.code}: {exc.detail}"
+            ) from exc
+        values["domain"] = context.domain_id
+        if context.project_id:
+            values["project"] = context.project_id
+        return values
 
     @staticmethod
     def _next_body(request: DocumentApplyRequest, current: str, exists: bool) -> str:
@@ -208,6 +216,7 @@ class DocumentApplyService:
         self,
         request: DocumentApplyRequest,
         exists: bool,
+        had_frontmatter: bool,
         profile: str,
         expected_hash: str,
         status: str,
@@ -215,6 +224,10 @@ class DocumentApplyService:
         missing_fields: list[str] | None = None,
     ) -> DocumentApplyResult:
         scope = Path(request.path).parent.as_posix()
+        derived_fields = {"name", "type", "status", "lifecycle", "domain", "project", "related"}
+        needs_sync = not exists or not had_frontmatter
+        needs_sync = needs_sync or bool(set(request.values) & derived_fields)
+        needs_sync = needs_sync or request.body is not None
         return DocumentApplyResult(
             status=status,
             workspace_id=self._settings.workspace_id,
@@ -224,5 +237,9 @@ class DocumentApplyService:
             expected_hash=expected_hash,
             issues=issues,
             missing_fields=missing_fields or [],
-            follow_up=maintenance_follow_up(self._settings.workspace_id, [scope]),
+            follow_up=(
+                maintenance_sync_follow_up(self._settings.workspace_id, [scope])
+                if not issues and needs_sync
+                else []
+            ),
         )

{campfire_cli-0.1.7 → campfire_cli-0.1.8}/src/campfire_cli/app/document/service/document_move_service.py

@@ -1,12 +1,11 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
 from datetime import date
 from pathlib import Path
 from typing import Any
 from urllib.parse import quote
 
-from campfire_cli.app.base.schema.operation_schema import maintenance_follow_up
+from campfire_cli.app.base.schema.operation_schema import maintenance_sync_follow_up
 from campfire_cli.app.document.schema import DocumentMoveResult
 from campfire_cli.app.document.service.document_rule_service import DocumentRuleService
 from campfire_cli.app.document.service.frontmatter_formatter import render_patch
@@ -17,6 +16,11 @@ from campfire_cli.app.document.service.type_apply import (
     rewrite_wikilinks,
 )
 from campfire_cli.common.documents.document_types import prefixed_name
+from campfire_cli.common.documents.domain_context import (
+    DomainContext,
+    DomainContextError,
+    resolve_domain_context,
+)
 from campfire_cli.common.documents.markdown import parse_document
 from campfire_cli.common.exceptions import ConfigurationError
 from campfire_cli.common.filesystem import FileChangeExecutor, FileChangeSet, FileWrite, safe_path
@@ -26,13 +30,6 @@ from campfire_cli.config.settings import WorkspaceSettings
 STRUCTURAL_FIELDS = {"domain", "project", "updated"}
 
 
-@dataclass(frozen=True)
-class DomainContext:
-    root: Path
-    domain_id: str
-    project_id: str | None
-
-
 class DocumentMoveService:
     """Move one document between declared Domains and preserve document invariants."""
 
@@ -69,15 +66,19 @@ class DocumentMoveService:
         actual_hash = file_sha256(source)
         original = source.read_text(encoding="utf-8")
         parsed = parse_document(original)
-        source_domain = self._domain_context(source)
-        target_domain = self._domain_context(target)
+        source_domain, source_domain_issue = self._domain_context(source)
+        target_domain, target_domain_issue = self._domain_context(target)
         issues: list[dict[str, Any]] = []
         if target.exists():
             issues.append({"code": "target-exists", "path": target_name})
         if source_domain is None:
-            issues.append({"code": "source-domain-missing", "path": source_name})
+            issues.append(
+                {"code": source_domain_issue or "source-domain-missing", "path": source_name}
+            )
         if target_domain is None:
-            issues.append({"code": "target-domain-missing", "path": target_name})
+            issues.append(
+                {"code": target_domain_issue or "target-domain-missing", "path": target_name}
+            )
         elif self._is_reserved_target(target_domain, target):
             issues.append({"code": "target-directory-reserved", "path": target_name})
         if not parsed.has_frontmatter:
@@ -211,7 +212,7 @@ class DocumentMoveService:
             frontmatter_changes=frontmatter_changes,
             issues=issues,
             missing_fields=missing_fields,
-            follow_up=maintenance_follow_up(
+            follow_up=maintenance_sync_follow_up(
                 self._settings.workspace_id,
                 (
                     context.root.relative_to(self._settings.vault_root).as_posix()
@@ -272,26 +273,18 @@ class DocumentMoveService:
                 changed.append(reference.relative_to(self._settings.vault_root).as_posix())
         return [FileWrite(path, text) for path, text in writes.items()], changed, expected
 
-    def _domain_context(self, path: Path) -> DomainContext | None:
-        marker_name = self._settings.governance.get("domain_marker", "_领域.md")
-        current = path.parent
-        while current == self._settings.vault_root or self._settings.vault_root in current.parents:
-            marker = current / marker_name
-            if marker.is_file():
-                values = parse_document(marker.read_text(encoding="utf-8")).frontmatter
-                domain_id = values.get("domain_id")
-                if not isinstance(domain_id, str) or not domain_id:
-                    return None
-                project = values.get("project_id") or values.get("project")
-                return DomainContext(
-                    root=current,
-                    domain_id=domain_id,
-                    project_id=project if isinstance(project, str) and project else None,
-                )
-            if current == self._settings.vault_root:
-                break
-            current = current.parent
-        return None
+    def _domain_context(self, path: Path) -> tuple[DomainContext | None, str | None]:
+        try:
+            return (
+                resolve_domain_context(
+                    self._settings.vault_root,
+                    path,
+                    self._settings.governance.get("domain_marker", "_领域.md"),
+                ),
+                None,
+            )
+        except DomainContextError as exc:
+            return None, exc.code
 
     def _is_reserved_target(self, context: DomainContext, target: Path) -> bool:
         relative = target.parent.relative_to(context.root)

{campfire_cli-0.1.7 → campfire_cli-0.1.8}/src/campfire_cli/app/document/service/document_scanner.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from collections.abc import Iterable
 from pathlib import Path
 from typing import Any
 
@@ -13,21 +14,32 @@ def exempt_document(path: Path, config: dict[str, Any]) -> bool:
     return path.name in set(config.get("exempt_basenames", []))
 
 
-def iter_documents(root: Path, config: dict[str, Any]) -> list[Path]:
+def iter_documents(
+    root: Path,
+    config: dict[str, Any],
+    roots: Iterable[Path] | None = None,
+) -> list[Path]:
     root = root.resolve()
     ignored = set(config.get("ignored_directories", []))
     documents: set[Path] = set()
     space_marker = config.get("space_marker", "_空间.md")
-    spaces = [
-        marker.parent.relative_to(root).as_posix() for marker in root.glob(f"*/{space_marker}")
-    ]
-    if spaces:
-        inboxes = [value for value in config.get("scope_roots", []) if value.startswith("_收件箱/")]
-        scope_roots = [*spaces, *inboxes]
+    if roots is not None:
+        scope_paths = [path.resolve() for path in roots]
     else:
-        scope_roots = config.get("scope_roots", [])
-    for raw_root in scope_roots:
-        scope = safe_path(root, raw_root)
+        spaces = [
+            marker.parent.relative_to(root).as_posix() for marker in root.glob(f"*/{space_marker}")
+        ]
+        if spaces:
+            inboxes = [
+                value for value in config.get("scope_roots", []) if value.startswith("_收件箱/")
+            ]
+            scope_roots = [*spaces, *inboxes]
+        else:
+            scope_roots = config.get("scope_roots", [])
+        scope_paths = [safe_path(root, raw_root) for raw_root in scope_roots]
+    for scope in scope_paths:
+        if scope != root and root not in scope.parents:
+            continue
         if not scope.exists():
             continue
         for path in scope.rglob("*.md"):