campfire-cli 0.1.9__tar.gz → 0.1.11__tar.gz

{campfire_cli-0.1.9 → campfire_cli-0.1.11}/ARCHITECTURE.md

@@ -78,6 +78,8 @@ Decision 以 SQLite 当前快照和追加事件为 SSOT。全部状态在 `_协
 
 Document App 是所有面向用户和 Agent 的文档命令入口；Profile、类型命名、Frontmatter 和文档规则是其内部能力。Maintenance 只编排跨文档批量维护，Workspace 的 Restructure 用例只处理存量结构重构；两者调用 Document Service，不再从 `common/` 获取文档业务流程。
 
+Document App 同时拥有设备本地的文档查询投影。Indexer 从 Markdown、Domain 声明、Project 文档根映射和显式链接生成文档记录与确定关系；Repository 只负责按 `workspace_id` 持久化完整快照。组合根从 Workspace Registry 提供当前 Project 映射，Document App 不直接读取 Workspace Repository，也不把每篇文档中可能漂移的重复字段当作物理归属。`document list` 和 `document inspect` 查询前自行轻量 reconcile，不要求 Agent 先运行 Maintenance。Maintenance 只在全量检查或可见生成物同步时触发索引校正，不拥有索引规则，也不是读取命令的前置步骤。
+
 Frontmatter 规则采用声明式 Profile：`base` 是最小公共契约，`knowledge`、`project-doc`、`task` 只允许一层继承。Profile Loader 将配置编译为完整 EffectiveProfile，Resolver 根据文档类型和领域上下文选择 Profile，Validator 与 Formatter 共同消费该结果。字段规则不使用每种文档一个 Python 子类，也不在 Skill 中复制。
 
 ### CLI 设计理念：治理原语 + Skill SOP
@@ -118,7 +120,7 @@ Campfire 不是“Markdown 版 kubectl”，而是面向人机协作场景组合
 命令设计遵循以下约束：
 
 1. **对象域优先**：公共入口采用 `campfire <object-domain> <verb>`，例如 `document apply`、`maintenance check`；动词在所属业务对象内保持单义，不为同一行为保留多个别名。
-2. **意图原子、派生显式**：`document apply` 只创建或更新目标文档，`document move` 原子完成单文档移动、目标 Profile 对齐和确定性引用修复；命令只在 MOC、关系页或索引可能变化时返回一个最小 scope 的 `maintenance sync`。
+2. **意图原子、派生显式**：`document apply` 创建或更新文档，并在显式类型变化时将类型、文件名前缀和确定性引用作为同一变更提交；`document move` 原子完成单文档跨 Domain 移动、目标 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 渐进发现，不维护第二套参数目录。
@@ -126,9 +128,21 @@ Campfire 不是“Markdown 版 kubectl”，而是面向人机协作场景组合
 7. **聚合入口是少数例外**：`setup` 和 `upgrade` 可以编排多个服务，因为它们表达完整安装生命周期；日常内容治理保持原子能力，避免重新出现 `maintenance run` 一类不可审查的聚合入口。
 8. **参数最小充分、黄金路径唯一**：调用方只提交 CLI 无法可靠推导的事实。已受管的 Workspace、Space、Domain 和 Project 优先使用稳定 id，路径只用于外部输入、未接管来源、显式物理位置或尚无稳定 id 的文档；同一事实不得同时要求 id、完整路径和父级关系。一个常规意图只保留一个公共入口，不用互斥模式参数、兼容别名或要求 Agent 手工拼装底层步骤来表达同一行为。
 
+### Agent 可执行契约
+
+Campfire 不把“调用方能够猜对未声明契约”作为可靠性前提。Agent 可能不会自行推断字段枚举、补丁值类型、Shell 引号、隐含前置步骤或上一次命令留下的状态；公共接口必须用已有入口提供足以完成当前意图的信息。
+
+- 参数帮助说明参数语义和输入格式；列表、结构化补丁等不直观输入至少给出一个可直接使用的例子。
+- 校验失败同时服务机器恢复和人工诊断：稳定错误码、字段与期望类型供程序判断，简短的实际值、示例或修复提示帮助调用方完成下一次正确调用。调用方不得被迫解析易变的自然语言 message。
+- Profile 仍是字段类型、枚举和跨字段规则的唯一事实源。`tree` 只发现能力，Skill 只选择路径，帮助和错误只呈现当前调用所需信息；三者不得复制整套 Profile 或建立平行参数目录。
+- 已知路径的正文小改直接使用文件工具；Frontmatter 契约已知时直接 `document apply`；现有文档的字段类型或合法值未知时使用一次 `document inspect` 后 apply。`tree` 只在不知道 Campfire 是否具有对应能力时使用，不是文档操作的固定前置步骤。
+- CLI 不使用“最近一次 apply”之类的隐式可变状态补偿 Agent 能力。跨命令动作由当前结果中的结构化 `follow_up` 显式描述，输入、对象和作用域在每次调用中均可审查。
+
+这里的“自解释”不是把所有教程塞进一个命令，也不是保证任何 Agent 零读取完成任意任务；它表示完成常规意图所需的契约有唯一来源、最短获取路径和可操作的失败反馈。只有出现新的独立用户意图时才增加命令，单纯的帮助或诊断不足不构成扩张命令面的理由。
+
 横切关注点与业务 SOP 不使用同一种复用手段。哈希复核、写锁、原子替换和失败恢复由显式 ChangeSet Executor 复用；写命令返回的 `follow_up` 由 Skill 消费。不为了复用 Maintenance 而引入 AOP 切面、命令总线、全局钩子或隐式中间件。
 
-因此，`document apply` 的准确含义是“对一个 Markdown 文档应用经 Profile 校验的显式意图”，不是“把完整声明持续调谐到某个服务端状态”。用户或 Agent 可以直接 edit 已有正文；无论通过 apply 还是 edit 写入，跨文档派生结果都由后续显式 Maintenance 收敛。
+因此，`document apply` 的准确含义是“对一个 Markdown 文档应用经 Profile 校验的显式意图”，不是“把完整声明持续调谐到某个服务端状态”。创建时文件名可省略类型前缀；显式变更类型时，CLI 负责同步类型、前缀和可确定引用。用户或 Agent 可以直接 edit 唯一路径下的已有正文；只有新建文档、修改 Frontmatter/类型/归属或需要派生治理时才进入 CLI 工作流。
 
 ## 5. SSOT 与派生数据
 
@@ -139,10 +153,21 @@ Campfire 不是“Markdown 版 kubectl”，而是面向人机协作场景组合
 | 治理规则 | 包内 `config.yml` + `~/.campfire/config.yml` 覆盖 | 校验结果与执行计划 |
 | Workspace、Project 注册关系 | `~/.campfire/campfire.db` | JSON 导入导出备份 |
 | Campfire Skills | Python 包内 `resources/skills/` | 全局 Agent Skill 目录 |
-| 文档索引、结构重构和维护状态 | `~/.campfire/campfire.db`，按 `workspace_id` 隔离 | JSON 当前快照、有限变更日志 |
+| 文档查询索引 | Workspace Markdown、结构声明与有效治理契约 | `~/.campfire/campfire.db` 中按 `workspace_id` 隔离的可重建投影 |
+| Decision、结构重构批次和维护运行状态 | `~/.campfire/campfire.db` | Markdown 投影、报告与有限变更日志；当前不能仅从 Workspace 重建 |
 
 SQLite 中的 Workspace 与 Project 注册数据是结构化事实，文档索引可以从 Markdown 重建；SQLite 不是知识内容的 SSOT。工具状态不写入 Workspace，因而一个 Campfire 安装可以管理多个 Workspace。
 
+### 文档查询投影
+
+文档索引 v1 保存列表查询需要的结构化字段、内容哈希、源文件 stat，以及显式 Frontmatter 关联、WikiLink、Markdown Link、Embed 形成的确定关系。它不复制正文，不保存相似度建议，也不把文件 mtime 解释为任务时间。
+
+每次 `document list` 或 `document inspect` 先对账文件清单、size、mtime、有效配置哈希和 Space/Domain 拓扑哈希。stat 只用于筛选变化候选，内容哈希才表示内容版本；新增、修改和删除会在查询前自动 reconcile。候选快照在内存中完成后，通过单个 SQLite 事务替换文档、关系和 generation，中断不能暴露半套新索引。
+
+`document list` 只做结构化精确枚举与 AND 筛选；未来正文关键词、模糊匹配、相关性排序或混合检索使用独立 `document search`。`document inspect.relations` 只返回可证明的 declared、outgoing、incoming 和 unresolved；相似文档属于未来独立 suggestions，不能混入确定关系。
+
+索引新鲜度是 CLI 内部读取保障，不生成让 Agent 手工执行的 index follow-up。MOC、关系页等 Workspace 内可见生成物仍由成功写命令按需返回 scoped `maintenance sync`。
+
 ### 设备本地与跨设备边界
 
 ```text
@@ -155,7 +180,7 @@ SQLite 中的 Workspace 与 Project 注册数据是结构化事实，文档索
                 ▼ 新设备 attach
 每台设备独立维护
   Project local_path
-  SQLite 索引与运行记录
+  SQLite 查询投影与运行记录
   Decision 与事件
   Skills 安装路径、锁、缓存和报告
 ```
@@ -207,7 +232,7 @@ Human / Browser  ──> HTTP Adapter ──┘                           │
 3. 规则集中在配置契约和规则引擎，Skill、模板、CLI 不复制枚举定义。
 4. MOC、Base、关系和报告能生成就不手工维护。
 5. 有歧义的分类和结构重构进入待确认，不由 Agent 擅自决定。
-6. Markdown 内容可脱离 Campfire 阅读和迁移；SQLite 丢失后可以重建。
+6. Markdown 内容可脱离 Campfire 阅读和迁移；文档查询投影在 SQLite 丢失后可以重建，Decision 与未完成批次等工作流状态不作此承诺。
 7. 只有一个用户级 SQLite；所有 Workspace 业务表必须携带 `workspace_id`，Repository 查询不得越界。
 8. 正式文档必须归入 Domain；Space 不直接替代 Domain，系统区域不伪装成 Space。
 

{campfire_cli-0.1.9 → campfire_cli-0.1.11}/COMMAND.md

@@ -1,6 +1,6 @@
 # Campfire 稳定命令
 
-人类与 Agent 先用 `campfire tree` 发现命令，再用任意层级的 `-h` 渐进加载参数。
+`campfire tree` 用于不知道 Campfire 是否具有某项能力时的命令发现，不是已知文档操作的固定前置步骤。具体参数从目标命令的 `-h` 获取；现有文档的 Frontmatter 契约未知时使用一次 `document inspect`，契约已知时直接调用写命令。
 
 ```bash
 campfire setup --path <vault-path> [--id <workspace-id>] --default
@@ -27,6 +27,7 @@ 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 list [--project <id>] [--domain <id>] [--type <type>] [--lifecycle <value>]
 campfire document apply --path <workspace-relative-markdown> --type <type> --set <field=value> [--body-file <path>] [--confirm]
 campfire document move --path <source> --domain <target-domain-id> [--name <filename>] [--set <field=value>] [--unset <field>] [--expected-hash <sha256>] [--confirm]
 campfire document inspect --path <file>
@@ -46,4 +47,8 @@ campfire maintenance archive apply [--scope <path>] --confirm
 
 Space、Domain、Project 的 `create`/`adopt`，以及文档移动、重构、归档写操作默认先预览；审查通过后才追加 `--confirm`。已注册 Workspace 只通过根级 `campfire --workspace <id> ...` 选择；已声明 Space、Domain 和 Project 使用稳定 ID，CLI 自行推导路径和父子关系。路径参数只用于新位置、具体文件、外部输入和显式扫描范围。
 
-`document apply` 可新建、更新或为已有正文补齐 Frontmatter；`document move` 可在任意已声明 Domain 之间移动单篇文档并对齐可确定的 `domain`/`project`。目标 Profile 缺少语义字段时返回 `missing_fields`，调用方用 `--set`/`--unset` 补齐。只有实际写入成功的结果才可返回一个实际需要的 scoped `maintenance sync` follow-up；预览、阻塞或无派生影响时返回空列表。具体参数以对应命令的 `-h` 为准。
+`document apply` 可新建、更新、为已有正文补齐 Frontmatter，或通过显式 `--type` 原子转换文档类型。创建和类型转换时，CLI 根据文档类型推导文件名前缀，并在结果的 `target` 中返回最终路径；调用方只提交标题或现有路径，不手工同步类型与前缀。`document move` 可在任意已声明 Domain 之间移动单篇文档并对齐可确定的 `domain`/`project`。目标 Profile 缺少语义字段时返回 `missing_fields`，调用方补齐明确业务值。只有实际写入成功的结果才可返回零或一个、且可直接执行的 scoped `maintenance sync` follow-up；Domain 内部路径会归一化为对应 Domain，预览、阻塞或无派生影响时返回空列表。具体参数以对应命令的 `-h` 为准。
+
+`--set` 的值类型由有效 Profile 决定，不使用 YAML 隐式类型推断。enum、string 和 date 保留原始字符串，boolean 只接受 `true` 或 `false`，list 只接受严格 JSON 数组。标量可写为 `--set lifecycle=completed`，列表在 Shell 中使用单引号保护，例如 `--set 'tags=["tag1","tag2"]'`。CLI 不把 `tag1,tag2` 猜成列表；格式错误时通过稳定错误码、期望类型和参数示例说明修复方式。字段与枚举不在本命令清单重复登记。
+
+`document list` 是 SQLite 查询投影上的精确集合枚举，多个筛选条件使用 AND 语义，`--type task` 不隐式排除任何 lifecycle。`document inspect` 在原有 Profile 和问题上下文之外返回 declared、outgoing、incoming 与 unresolved 确定关系。两条读取命令查询前自动 reconcile；Agent 取得路径后用文件工具读取正文，不需要先跑 Maintenance。未来正文关键词、模糊匹配和相关性排序使用独立 `document search`，不改变 list/inspect 的确定语义。

{campfire_cli-0.1.9 → campfire_cli-0.1.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: campfire-cli
-Version: 0.1.9
+Version: 0.1.11
 Summary: Local-first shared context and governance CLI for humans and agents
 License-Expression: MIT
 License-File: LICENSE
@@ -23,7 +23,7 @@ Description-Content-Type: text/markdown
 - **写操作默认预览**：先计划、再确认、执行前在治理锁内复核内容哈希，多会话并发不会互相覆盖。
 - **本地优先**：不绑定云服务、不内置账号；Obsidian Vault 是当前首个存储适配器，Workspace 才是顶层概念。
 
-产品目标、业务对象、SSOT 与模块边界见 [ARCHITECTURE.md](ARCHITECTURE.md)，命令全景用 `campfire tree` 渐进发现。
+产品目标、业务对象、SSOT 与模块边界见 [ARCHITECTURE.md](ARCHITECTURE.md)。不知道 Campfire 是否具有某项能力时用 `campfire tree` 发现命令；已知文档操作不把 tree 作为固定前置步骤。
 
 ## 安装
 
@@ -94,7 +94,8 @@ campfire maintenance sync [--dry-run] [--scope]  # 刷新 MOC 与相关文档页
 campfire maintenance archive check / apply       # 归档候选检查与执行
 
 campfire document inspect / check / format       # 单篇文档查看、校验、格式化
-campfire document apply / move                   # 单篇文档创建更新、跨 Domain 移动
+campfire document list                           # 精确枚举和筛选受管文档
+campfire document apply / move                   # 创建更新、类型转换、跨 Domain 移动
 campfire document profile list / show / resolve  # Frontmatter Profile 规则
 campfire document type list                      # 文档类型与前缀
 
@@ -136,15 +137,16 @@ campfire workspace restructure verify --batch move-001
 
 ## 治理模型
 
+- **本地查询投影**：`document list` 按 Project、Domain、类型和生命周期精确筛选；`document inspect` 返回显式关联、出链、反向链接和失效/歧义引用。两者在查询前自动 reconcile，Agent 无需先运行 Maintenance。SQLite 不复制正文，正文仍由 Agent 按返回路径读取。
 - **校验分工**：`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 提交，失败恢复到执行前。
-- **按需后续治理**：写入命令只在实际写入成功且派生内容可能变化时返回一个最小 scope 的 `maintenance sync`；预览和阻塞结果的 `follow_up` 为空。Skill 消费该结果，没有 follow-up 就结束，不固定追加 dry-run 或全量 check。
+- **按需后续治理**：写入命令只在实际写入成功且派生内容可能变化时返回零或一个、且可直接执行的最小 scope `maintenance sync`；预览和阻塞结果的 `follow_up` 为空。位于 Domain 内部的 scope 由 CLI 归一化为有效 Domain。Skill 消费该结果，没有 follow-up 就结束，不固定追加 dry-run 或全量 check。
 - **配置两层模型**：产品默认契约在包内 `resources/defaults/config.yml`（SSOT），用户只在 `~/.campfire/config.yml` 写覆盖项；Mapping 递归合并，`campfire workspace config check` 验证有效配置。
 
 ## Agent 协作
 
-全局 Skill（`campfire skill list` 查看托管清单，`campfire skill sync` 手动同步）定义了 Agent 的标准工作流：首次读写先 `workspace resolve` 并读取 Workspace 的 `AGENTS.md`；单文档用 `document apply/move`，批量结构调整用 `workspace restructure`，归档用 `maintenance archive`。有歧义的分类和重构进入 Decision，不由 Agent 擅自决定。
+全局 Skill（`campfire skill list` 查看托管清单，`campfire skill sync` 手动同步）定义了 Agent 的标准工作流：已给出唯一文件路径的正文读取或小改直接使用文件工具；新建文档、修改 Frontmatter/类型/归属或执行结构治理时才加载 bootstrap，并使用 `document apply/move` 等原子命令。Frontmatter 契约已知时直接 apply；现有文档的字段类型或合法值未知时只执行一次 `document inspect` 后 apply。批量结构调整用 `workspace restructure`，归档用 `maintenance archive`。有歧义的分类和重构进入 Decision，不由 Agent 擅自决定。
 
 ## 许可
 

{campfire_cli-0.1.9 → campfire_cli-0.1.11}/README.md

@@ -7,7 +7,7 @@
 - **写操作默认预览**：先计划、再确认、执行前在治理锁内复核内容哈希，多会话并发不会互相覆盖。
 - **本地优先**：不绑定云服务、不内置账号；Obsidian Vault 是当前首个存储适配器，Workspace 才是顶层概念。
 
-产品目标、业务对象、SSOT 与模块边界见 [ARCHITECTURE.md](ARCHITECTURE.md)，命令全景用 `campfire tree` 渐进发现。
+产品目标、业务对象、SSOT 与模块边界见 [ARCHITECTURE.md](ARCHITECTURE.md)。不知道 Campfire 是否具有某项能力时用 `campfire tree` 发现命令；已知文档操作不把 tree 作为固定前置步骤。
 
 ## 安装
 
@@ -78,7 +78,8 @@ campfire maintenance sync [--dry-run] [--scope]  # 刷新 MOC 与相关文档页
 campfire maintenance archive check / apply       # 归档候选检查与执行
 
 campfire document inspect / check / format       # 单篇文档查看、校验、格式化
-campfire document apply / move                   # 单篇文档创建更新、跨 Domain 移动
+campfire document list                           # 精确枚举和筛选受管文档
+campfire document apply / move                   # 创建更新、类型转换、跨 Domain 移动
 campfire document profile list / show / resolve  # Frontmatter Profile 规则
 campfire document type list                      # 文档类型与前缀
 
@@ -120,15 +121,16 @@ campfire workspace restructure verify --batch move-001
 
 ## 治理模型
 
+- **本地查询投影**：`document list` 按 Project、Domain、类型和生命周期精确筛选；`document inspect` 返回显式关联、出链、反向链接和失效/歧义引用。两者在查询前自动 reconcile，Agent 无需先运行 Maintenance。SQLite 不复制正文，正文仍由 Agent 按返回路径读取。
 - **校验分工**：`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 提交，失败恢复到执行前。
-- **按需后续治理**：写入命令只在实际写入成功且派生内容可能变化时返回一个最小 scope 的 `maintenance sync`；预览和阻塞结果的 `follow_up` 为空。Skill 消费该结果，没有 follow-up 就结束，不固定追加 dry-run 或全量 check。
+- **按需后续治理**：写入命令只在实际写入成功且派生内容可能变化时返回零或一个、且可直接执行的最小 scope `maintenance sync`；预览和阻塞结果的 `follow_up` 为空。位于 Domain 内部的 scope 由 CLI 归一化为有效 Domain。Skill 消费该结果，没有 follow-up 就结束，不固定追加 dry-run 或全量 check。
 - **配置两层模型**：产品默认契约在包内 `resources/defaults/config.yml`（SSOT），用户只在 `~/.campfire/config.yml` 写覆盖项；Mapping 递归合并，`campfire workspace config check` 验证有效配置。
 
 ## Agent 协作
 
-全局 Skill（`campfire skill list` 查看托管清单，`campfire skill sync` 手动同步）定义了 Agent 的标准工作流：首次读写先 `workspace resolve` 并读取 Workspace 的 `AGENTS.md`；单文档用 `document apply/move`，批量结构调整用 `workspace restructure`，归档用 `maintenance archive`。有歧义的分类和重构进入 Decision，不由 Agent 擅自决定。
+全局 Skill（`campfire skill list` 查看托管清单，`campfire skill sync` 手动同步）定义了 Agent 的标准工作流：已给出唯一文件路径的正文读取或小改直接使用文件工具；新建文档、修改 Frontmatter/类型/归属或执行结构治理时才加载 bootstrap，并使用 `document apply/move` 等原子命令。Frontmatter 契约已知时直接 apply；现有文档的字段类型或合法值未知时只执行一次 `document inspect` 后 apply。批量结构调整用 `workspace restructure`，归档用 `maintenance archive`。有歧义的分类和重构进入 Decision，不由 Agent 擅自决定。
 
 ## 许可
 

{campfire_cli-0.1.9 → campfire_cli-0.1.11}/SPEC.md

@@ -9,7 +9,7 @@ CLI delivery adapter
         ↓
 AppContainer 组合根，承担跨 App 编排
         ↓
-Workspace Restructure / Maintenance Service
+Document / Workspace Restructure / Maintenance Service
         ↓
 消费方 Protocol
         ↓
@@ -29,6 +29,9 @@ SQLite / Filesystem Implementation
 - CLI 不直接实现业务规则；Service 不依赖 Typer。
 - 字段、枚举和跨字段不变量统一由 DocumentRuleService 解释；Maintenance 与 Workspace Restructure 不得复制规则值。
 - Frontmatter Profile 只允许一层 `base` 配置继承；Profile Loader 编译完整规则，Validator 与 Formatter 共用同一个 EffectiveProfile。
+- 公共接口不得依赖调用方猜测未声明契约。参数类型与复杂输入格式必须能从当前命令帮助获得；错误必须同时提供稳定机器字段和可操作的修复信息，但不得为此复制 Profile 枚举或新增平行命令。
+- `tree` 只用于未知能力发现，不是 Agent 执行已知文档操作的固定前置步骤；Skill 必须把已知正文编辑、契约已知的 Frontmatter 写入和契约未知的 `inspect → apply` 分流清楚。
+- 命令不得读取“最近一次操作”等隐式 Session 状态推导对象或作用域；跨命令后续动作只使用当前结果显式返回的结构化 `follow_up`。
 - 所有写入默认预检，语义计划默认未审批。
 - 写入用例必须在治理锁内复核生成计划时的内容哈希，发现外部变化时拒绝覆盖。
 
@@ -38,6 +41,7 @@ SQLite / Filesystem Implementation
 
 - 正常输出 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 各有自己的字段词汇表。需要新状态先在本节登记。
+- 可恢复的输入错误必须包含稳定 `code`、对应字段和机器可读的期望类型；当正确序列化方式不直观时，同时返回示例值或修复提示。自然语言 message 与示例可以演进，不作为调用方分支判断依据。
 - 前置条件缺失时优先降级执行：能完成的部分照常完成，输出 `needs-input` 并以 `skipped` 字段显式列出被跳过的步骤，而非整体报错退出。
 
 ## 升级语义
@@ -106,8 +110,13 @@ Campfire 使用语义化版本：
 ## Workspace 索引
 
 - SQLite `spaces`、`domains`、`documents` 只允许作为可重建本机投影，不得反向覆盖 Markdown SSOT。
+- Document App 拥有文档记录、确定关系、集合查询和单篇关系查询；Repository 只持久化投影，不解释 Profile、Domain 或链接语义。
+- 文档索引保存 schema version、parser version、有效配置 hash、拓扑 hash 和 generation；Domain 声明、Project 文档根映射等任一解释输入变化都必须自动完整重建。
+- `document list` 与 `document inspect` 查询前必须轻量 reconcile。文件 stat 只筛选变化候选，content hash 表示内容版本；调用方不需要先运行 Maintenance。
+- 候选文档与关系快照必须在一个 SQLite 事务中切换，失败继续保留上一完整 generation。
+- `document list` 只做结构化精确筛选；`document inspect` 只返回显式关联和链接形成的确定关系。全文检索、模糊匹配、相关性排序和相似建议不得混入这两个契约。
 - `setup` 与 `maintenance check` 必须自动刷新完整拓扑和文档索引。
-- 写命令只在实际写入成功且派生状态可能变化时返回一个 scoped `maintenance sync` follow-up；预览和阻塞结果必须返回空列表；
+- 索引 reconcile 是读取命令内部保障，不得作为 follow-up 暴露给 Agent。写命令只在实际写入成功且可见派生状态可能变化时返回零或一个可直接执行的 scoped `maintenance sync` follow-up；Domain 内部路径必须归一化为对应 Domain，预览和阻塞结果必须返回空列表；
   调用方只执行实际返回的 follow-up，不固定追加 check 或全量扫描。
 - `workspace rebuild` 默认只预览；`--confirm` 后从 Manifest 和 Markdown 完整替换派生索引。
 

{campfire_cli-0.1.9 → campfire_cli-0.1.11}/pyproject.toml

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

{campfire_cli-0.1.9 → campfire_cli-0.1.11}/src/campfire_cli/__init__.py

@@ -1,3 +1,3 @@
 """Campfire CLI package."""
 
-__version__ = "0.1.9"
+__version__ = "0.1.11"

campfire_cli-0.1.11/src/campfire_cli/alembic/versions/009_document_query_index.py

@@ -0,0 +1,84 @@
+"""Expand the rebuildable document query index."""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "009"
+down_revision = "008"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table("documents") as batch:
+        batch.add_column(sa.Column("name", sa.String(240)))
+        batch.add_column(sa.Column("project_id", sa.String(63)))
+        batch.add_column(sa.Column("lifecycle", sa.String(32)))
+        batch.add_column(sa.Column("priority", sa.String(32)))
+        batch.add_column(sa.Column("assignee_json", sa.Text(), nullable=False, server_default="[]"))
+        batch.add_column(sa.Column("due", sa.String(32)))
+        batch.add_column(sa.Column("source_updated", sa.String(32)))
+        batch.add_column(sa.Column("source_size", sa.Integer()))
+        batch.add_column(sa.Column("source_mtime_ns", sa.Integer()))
+        batch.add_column(
+            sa.Column("queryable", sa.Boolean(), nullable=False, server_default=sa.true())
+        )
+
+    op.create_table(
+        "document_edges",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "workspace_id",
+            sa.String(63),
+            sa.ForeignKey("workspaces.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("source_path", sa.Text(), nullable=False),
+        sa.Column("target_path", sa.Text()),
+        sa.Column("raw_target", sa.Text(), nullable=False),
+        sa.Column("relation_type", sa.String(48), nullable=False),
+        sa.Column("resolution", sa.String(24), nullable=False),
+        sa.Column("candidates_json", sa.Text(), nullable=False, server_default="[]"),
+        sa.Column("line", sa.Integer()),
+    )
+    op.create_index("ix_document_edges_workspace_id", "document_edges", ["workspace_id"])
+    op.create_index("ix_document_edges_source_path", "document_edges", ["source_path"])
+    op.create_index("ix_document_edges_target_path", "document_edges", ["target_path"])
+
+    op.create_table(
+        "document_index_state",
+        sa.Column(
+            "workspace_id",
+            sa.String(63),
+            sa.ForeignKey("workspaces.id", ondelete="CASCADE"),
+            primary_key=True,
+        ),
+        sa.Column("schema_version", sa.Integer(), nullable=False),
+        sa.Column("parser_version", sa.String(32), nullable=False),
+        sa.Column("config_hash", sa.String(64), nullable=False),
+        sa.Column("topology_hash", sa.String(64), nullable=False),
+        sa.Column("generation", sa.Integer(), nullable=False),
+        sa.Column("status", sa.String(24), nullable=False),
+        sa.Column("rebuilt_at", sa.DateTime(), nullable=False),
+        sa.Column("indexed_at", sa.DateTime(), nullable=False),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("document_index_state")
+    op.drop_table("document_edges")
+    with op.batch_alter_table("documents") as batch:
+        for column in (
+            "queryable",
+            "source_mtime_ns",
+            "source_size",
+            "source_updated",
+            "due",
+            "assignee_json",
+            "priority",
+            "lifecycle",
+            "project_id",
+            "name",
+        ):
+            batch.drop_column(column)

{campfire_cli-0.1.9 → campfire_cli-0.1.11}/src/campfire_cli/app/document/SPEC.md

@@ -1,6 +1,6 @@
 # Document App SPEC
 
-本模块承载面向用户和 Agent 的文档业务能力，包括单篇检查与格式化、类型契约、Profile 契约、命名和 Frontmatter 治理。
+本模块承载面向用户和 Agent 的文档业务能力，包括单篇检查与格式化、类型契约、Profile 契约、命名与 Frontmatter 治理，以及设备本地可重建的文档查询投影。
 
 Document App 负责单篇文档及其规则；Maintenance App 负责检查、派生内容同步和归档；Workspace Restructure 负责存量批量结构重构。纯解析、序列化和路径安全等无业务状态的原子能力保留在 `common/documents/`。
 
@@ -20,6 +20,9 @@ document/
 │   ├── document_profile_service.py
 │   ├── document_type_service.py
 │   ├── document_service.py
+│   ├── document_index_service.py
+│   ├── document_index_builder.py
+│   ├── document_index_protocol.py
 │   ├── document_rule_service.py
 │   ├── document_scanner.py
 │   ├── profile_registry.py
@@ -29,6 +32,7 @@ document/
 │   ├── frontmatter_apply.py
 │   └── frontmatter_formatter.py
 └── repository/
+    ├── document_index_repository.py
     ├── document_profile_repository.py
     └── document_type_repository.py
 ```
@@ -37,19 +41,34 @@ document/
 - `type`：检查、规划和执行单选类型与文件命名治理。
 - `frontmatter`：检查、规划、执行和格式化文档属性。
 - `rule`：统一解释类型、Profile、枚举与跨字段不变量。
-- `inspect`：向 Agent 返回单篇文档的 Domain、类型、有效 Profile 和具体问题。
+- `index`：Service 只编排新鲜度、generation 和查询，Builder 只把 Markdown、Domain/Project 上下文与显式链接转换为确定性投影；配置、拓扑或解析器变化时完整重建，普通文件变化时调用时 reconcile。
+- `list`：按 Project、Domain、类型和生命周期对索引做精确 AND 筛选；返回全部生命周期，不读取或复制正文。
+- `inspect`：向 Agent 返回单篇文档的 Domain、类型、有效 Profile、具体问题，以及 declared、outgoing、incoming、unresolved 四类确定关系。
 - `apply`：根据目标路径和类型解析 Profile，不存在时生成文档，已有 Frontmatter 时只应用显式补丁，无 Frontmatter 时保留正文并补齐完整契约；先完整渲染并校验，追加 `--confirm` 后原子写入。
 - `move`：在任意已声明 Domain 之间移动或改名一篇文档，按目标 Profile 对齐可确定的 `domain`/`project` 归属，并更新可确定解析的 Wiki、Markdown 和路径引用。目标 Profile 缺少业务字段时返回 `needs-input`，不猜测。
 - `scanner`：统一解释受管根、忽略目录和豁免文件；Document 与 Maintenance 共用。
 
 Document Service 可以被 Workspace Restructure 编排，但不得反向依赖 Maintenance。批量计划文件、运行记录、MOC、Base、归档和重构批次不属于 Document App。
 
+Markdown 是内容与关系事实源，SQLite 是按 Workspace 隔离的查询投影。Document Index Repository 不解析 Markdown、Profile 或 Domain，只原子持久化文档、关系和 generation 快照。索引不得复制正文；相似度、全文关键词和相关性排序不属于 v1，未来只能以独立 suggestions/search 契约扩展。
+
+`list` 与 `inspect` 自行保障查询新鲜度，不返回索引维护 follow-up。文件 size/mtime 只用于发现变化候选，content hash 表示内容版本；Space/Domain 声明、Project 文档根映射或有效治理配置变化必须触发完整重建。Project 归属优先来自 Domain 继承，其次来自组合根注入的已注册 Project 文档根，不信任每篇 Frontmatter 的重复值。MOC 与其他生成文档不作为普通内容节点。
+
 `apply` 与 `move` 只保证目标文档操作自身有效，不触发 Maintenance。结果只在派生状态可能变化时返回一个最小 scope 的 `maintenance sync`；调用方不得固定追加 check。所有写入先生成完整 ChangeSet，再经共享 Executor 在乐观锁内提交；多文件操作失败时恢复提交前内容。
 
 包内 `config.yml` 的默认 Profile 与用户级 `~/.campfire/config.yml` 覆盖共同构成当前治理契约。
 
 Profile 只允许一层 `base` 继承。Service 将声明配置编译为完整 `EffectiveProfile`；Validator、Formatter 和 CLI 必须消费同一结果，不得复制字段、枚举与值类型。`value_types` 声明不能由 YAML 形状可靠推断的标量类型，当前支持 `string` 和 `boolean`。
 
+Document 写入接口不得要求 Agent 猜测 Frontmatter 输入契约：
+
+- `--set` 是统一的显式字段补丁入口。CLI Adapter 只拆分首个 `=`、拒绝空字段名和重复字段，并保留原始 value；它不解释 Profile，也不使用 YAML 隐式类型推断。
+- Document App 解析一次目标 EffectiveProfile，并由 apply 与 move 共用的值解码器转换补丁：enum、string 和 date 保留原始字符串，boolean 只接受明确的 `true` 或 `false`，list 只接受严格 JSON 数组。
+- Profile 与 Rule Service 继续拥有字段类型、合法值和业务校验，不保存命令行字符串。命令帮助负责 Shell 展示方式，并为列表值给出 `--set 'tags=["tag1","tag2"]'` 形式的最小例子。
+- 输入错误统一返回稳定错误码、字段、实际值、期望类型和可直接照抄的参数示例；apply 与 move 不得分别构造两套解码或诊断。
+- 不因输入格式不直观而增加 `--tags`、`--sources` 等字段专用参数，也不把逗号字符串静默猜成列表。
+- 现有文档的有效 Profile 已由 `document inspect` 返回。Skill 只在字段契约未知时安排一次 `inspect → apply`；契约已知的补丁直接 apply，正文小改不进入本接口。
+
 标准字段用于格式化、补全和校验。默认 `unknown_fields: preserve`：已有业务扩展字段不参与标准排序但必须原样保留，不因尚未建立专属 Profile 而制造全库噪声；确需封闭字段集合的 Profile 可显式设为 `report`。
 
 Document 不维护配置副本，也不提供契约同步命令。升级 Python 包会更新默认契约；用户自定义类型和 Profile 只写入 `~/.campfire/config.yml`，并通过 `workspace config check` 验证。

{campfire_cli-0.1.9 → campfire_cli-0.1.11}/src/campfire_cli/app/document/cli/document_cli.py

@@ -6,18 +6,13 @@ 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="创建、检查和维护文档及其规则",
@@ -26,15 +21,18 @@ document_cli = typer.Typer(
 document_cli.add_typer(profile_cli, name="profile")
 document_cli.add_typer(type_cli, name="type")
 
+SET_OPTION_HELP = (
+    "设置 Frontmatter 字段，格式 field=value，可重复使用。"
+    "值类型由有效 Profile 决定；列表使用严格 JSON，例如 "
+    '--set \'tags=["tag1","tag2"]\'。'
+)
+
 
 def service(ctx: typer.Context) -> DocumentService:
+    from campfire_cli.container import AppContainer
+
     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)
+    return AppContainer.build(selector).document
 
 
 def invoke(operation: Callable[[], dict[str, Any] | BaseModel]) -> None:
@@ -61,10 +59,29 @@ def kanban_check(ctx: typer.Context, path: str = typer.Option(..., "--path")) ->
 
 @document_cli.command("inspect")
 def inspect(ctx: typer.Context, path: str = typer.Option(..., "--path")) -> None:
-    """返回 Agent 治理单篇文档所需的类型、Profile、领域和问题上下文。"""
+    """返回单篇文档的 Profile、领域、确定关系和问题上下文。"""
     invoke(lambda: service(ctx).inspect(path))
 
 
+@document_cli.command("list")
+def list_documents(
+    ctx: typer.Context,
+    project: str | None = typer.Option(None, "--project"),
+    domain: str | None = typer.Option(None, "--domain"),
+    document_type: str | None = typer.Option(None, "--type"),
+    lifecycle: str | None = typer.Option(None, "--lifecycle"),
+) -> None:
+    """按 Project、Domain、类型和生命周期列出受管内容文档。"""
+    invoke(
+        lambda: service(ctx).list(
+            project=project,
+            domain=domain,
+            document_type=document_type,
+            lifecycle=lifecycle,
+        )
+    )
+
+
 @document_cli.command("format")
 def format_document(
     ctx: typer.Context,
@@ -75,8 +92,8 @@ def format_document(
     invoke(lambda: service(ctx).format(path, confirm))
 
 
-def parse_values(items: list[str]) -> dict[str, Any]:
-    values: dict[str, Any] = {}
+def parse_values(items: list[str]) -> dict[str, str]:
+    values: dict[str, str] = {}
     for item in items:
         if "=" not in item:
             raise typer.BadParameter(f"--set 必须使用 field=value：{item}")
@@ -86,7 +103,7 @@ def parse_values(items: list[str]) -> dict[str, Any]:
         key = key.strip()
         if key in values:
             raise typer.BadParameter(f"--set 字段重复：{key}")
-        values[key] = yaml.safe_load(raw)
+        values[key] = raw
     return values
 
 
@@ -95,21 +112,26 @@ 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"),
+    set_values: list[str] | None = typer.Option(None, "--set", help=SET_OPTION_HELP),
     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 合法文档的创建与补丁。"""
+    """预览或应用一篇 Profile 合法文档的创建、补丁与显式类型变更。
+
+    创建时文件名可省略类型前缀；CLI 根据 --type 返回并写入最终 target。
+    已有文档的 --type 发生变化时，同一原子操作同步文件名和引用。
+    """
+    values = parse_values(set_values or [])
     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 []),
+                values=values,
                 body=body,
                 append_section=append_section,
                 replace_body=replace_body,
@@ -126,18 +148,19 @@ def move_document(
     source: str = typer.Option(..., "--path", help="源文档的 Workspace 相对路径"),
     target_domain: str = typer.Option(..., "--domain", help="目标 Domain 的稳定 id"),
     name: str | None = typer.Option(None, "--name", help="可选的新文件名；省略时保持原文件名"),
-    set_values: list[str] | None = typer.Option(None, "--set"),
+    set_values: list[str] | None = typer.Option(None, "--set", help=SET_OPTION_HELP),
     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 契约更新归属与引用。"""
+    values = parse_values(set_values or [])
     invoke(
         lambda: service(ctx).move(
             source,
             target_domain,
             name=name,
-            values=parse_values(set_values or []),
+            values=values,
             unset_fields=tuple(unset_fields or []),
             expected_hash=expected_hash,
             confirm=confirm,

campfire_cli-0.1.11/src/campfire_cli/app/document/repository/__init__.py

@@ -0,0 +1,7 @@
+"""Document persistence adapters."""
+
+from campfire_cli.app.document.repository.document_index_repository import (
+    SqliteDocumentIndexRepository,
+)
+
+__all__ = ["SqliteDocumentIndexRepository"]