@ftai/dsh-plugin-acn 0.0.0-stage → 0.1.1

package/docs/architecture.md

@@ -0,0 +1,130 @@
+# 当前架构
+
+`acn-knowledge` 是唯一配置承载行，发布 `acnKnowledge` 领域服务和 `acnRuntime` 连接池。七个领域组件隔离 `acnRuntime` / `acnKnowledge` / `acnFormation` / `acnInbox` / `acnDream`，其他六行注册工具、提示词、后台处理器和命令。未配置身份时只提供状态命令。第八行 `acn-configuration` 使用包根入口，独立承载插件配置 Remote，避免知识重载中断保存请求。
+
+| 模块 | 当前职责 |
+| --- | --- |
+| `configuration.ts`、`interaction.ts`、`client/` | 工作配置与常用参数、ACN 插件设置、会话工具栏、知识及活动、结果展示 |
+| `dsh-adapter/configuration-*` | 严格 Remote 协议与宿主 profile 编辑器，保存前及文件锁内检查配置版本 |
+| `dsh-adapter/project-upstream.ts` | 通过公开只读会话接口，按创建时间为新会话预选 upstream，不另存项目偏好 |
+| `dsh-adapter/runtime-pool.ts` | 按会话持久归属分配领域服务，首次同步门禁、组件生命周期、独立存储与冻结快照 |
+| `dsh-adapter/interaction-service.ts`、`store/presentation.ts` | 只读知识/活动、显式连接检查及重试、终态版本展示回执 |
+| `protocol/` | 规范 DTO、ID、时间、revision |
+| `store/` | 实体文件、原子写、跨进程锁、租约、队列、编辑恢复和私有文档 |
+| `store/library-directory.ts`、`store/history.ts` | 统一账号目录的配置索引、身份目录定位与历史记录只读投影；不接管旧队列或复制宿主凭据 |
+| `knowledge/service.ts` | Claim / Trace 浏览、修订、形成批次提交、知识版本与变化事件 |
+| `knowledge/pages.ts` | 稳定排序、Unicode 摘要和分页 |
+| `knowledge/catalog.ts`、`changes.ts`、`sessions.ts` | 冻结目录、累计身份差异与会话状态 |
+| `tools/claim.ts`、`commands/` | 无宿主运行时依赖的领域分发和文本命令 |
+| `prompt/`、`prompts/` | 异步预读模板、内存渲染和知识语义 |
+| `knowledge/alignment.ts` | 完整快照变化核对、精确部分提交识别与恢复边界 |
+| `formation/` | transcript、触发、schema、占位符与引用、prepared / applied checkpoint |
+| `worker/` | 持久任务、优先级与 FIFO、单 worker、抢占、重试和接管 |
+| `team/` | 鉴权信封、代理、超时/重试、严格响应解码、连接状态与警告去重 |
+| `inbox/` | pull/ACK、同类消息批处理、仲裁和引用校验、撤回、批次 effect journal |
+| `dream/` | 调度、候选、草稿硬校验、逐 Claim 语义复核、逐组提交、依赖重绑与报告 |
+| `upload/` | 精确版本投递、整合依赖递归就绪、Dispute 集合去重、事件与空闲补传 |
+| `llm/structured.ts` | schema 提示、结构 / 传输重试、取消与无正文审计 |
+| `llm/response.ts` | 识别显式推理结束边界后的完整 JSON 对象，之后仍执行全部结构与领域校验 |
+| `plugins/`、`dsh-adapter/` | 宿主生命周期、严格模型 schema、工具策略与注册 |
+
+插件设置界面注册在宿主 `settings.section`，会话工具栏使用 `conversation.input.left`。`plugin:acn/session-eligibility` 记录插件启用后创建的空白会话资格；`plugin:acn/team-selection` 记录连接 ID、身份摘要及首次同步完成标记。已有消息或模型请求即锁定选择，未绑定历史只放行普通聊天，不放行知识或后台会话投影；已有绑定失效仍受身份门禁保护。输入框反馈与后端准入分别检查；团队同步失败降级为本地工作。历史只读使用 `sessionController.inspect`，显式操作才恢复 Agent；恢复未绑定历史不会拉取收件。新建无 seed 的派生会话继承已记录的父选择，不能回落到个人空间；子代理继续只读 Claim。
+
+连接池按 upstream 与运行配置按需创建领域对象。会话绑定先于知识读取落盘，运行配置缓存跨插件重载保留，真正恢复新实例时读取同一 upstream 的当前连接。相同存储路径的后台 worker 和上传调度器在新实例实际启动时交接，旧前台实例继续使用原客户端。重载先恢复最近实际激活的后台所有者，持久队列由该消费者处理；仅保存配置不会激活另一个团队。所有组件遵循各自行启用状态；禁用、重载时取消未固定任务并等待本地固定提交结束。个人存储和旧版全局团队目录不搬迁。普通文件工具保护整个配置数据根，包括尚未启动、停用及删除配置后仍保留的连接数据。
+
+知识和活动只读台账，不启动连接运行时；首次使用连接才初始化恢复和调度。结果展示回执只保存任务 ID、终态版本和升级基线，不保存正文；后台完成与用户看到结果分别记账。界面按来源、焦点和可见性过滤，真正绘制后才确认已展示。
+
+修订在 `knowledge_apply.lock` 内恢复旧编辑及已有 journal、重读正文、校验 holder 和 revision、验证新文本、推进更新时间，然后原子写正文。团队配置下依次写 pending edit、正文、持久队列，再删除 pending；锁外触发 HTTP 投递。单人模式跳过全部团队文件操作。
+
+知识服务的 Claim / Trace 读取与推理快照在同一知识锁内完成恢复和文件扫描，避免跨过批量提交而读取到混合版本；锁内没有模型或网络调用，显式读取及修订的锁等待可取消。写后变化通知单独处理：通知暂时失败不能把已经提交的修改误报为失败，持久上传队列继续按既有投递机制处理。
+
+编辑日志恢复只将精确等于已授权 target 的正文入队；当前仍是原 revision 时丢弃未落盘日志，遇到其他版本时保留当前正文、告警并丢弃旧日志，不以“已经不同于原文”推定新版本可上传。
+
+每个会话的 `sessions/<id>/state.yaml` 保存冻结目录及完整身份基线、最近通知版本、已观察身份和来源集合。状态更新在文件锁内合并，保留其他模块字段。提示词段落通过同步缓存读取冻结目录；`agent/created` 的 serial 监听负责完成异步准备。
+
+变化检查在 `agent/pre-step` 的下游决定为 enter 后运行，将消息追加到返回值。宿主真正追加 `user/message` 时，插件才排队持久化去重游标；下一步骤先等待此前状态写入。拒绝或取消请求不会提前消耗通知。跨进程变化通过目录时间戳和两秒兜底的全文 revision digest 检测。
+
+增量变化检查不等待其他提交持有的知识锁，对短暂一致性冲突最多尝试两次，仍忙时保留冻结目录和通知游标，后续步骤再补发。首次及恢复目录冻结仍必须取得一致快照，锁等待使用宿主请求的取消信号；损坏、权限错误和取消不会被当作暂时忙碌吞掉。形成和 Inbox 提交在取得知识锁前也响应取消，prepared 后继续沿既有恢复边界完成固定效果。Dream 资格预检不等待知识锁：自动检查遇忙时保留一个去重的一秒重试，停止或卸载时清理；手动请求可以先入队，由 worker 在可取消的初始快照中重检资格。
+
+模型工具先经 `tools/pre-execute`，子代理写入还受不可撤销的最终 guard 约束。身份来自执行器持有的 SessionHeader，不接受模型参数提供的身份。工具返回规范 JSON，文本展示由 renderer 派生。
+
+身份摘要通过宿主公开的 `appendPluginRecord` 写入 `plugin:acn/session-binding`，随会话持久化和 fork 继承；摘要只绑定本地知识根，不含私有正文。新建无继承日志的子会话须有已验证父身份，历史无绑定记录默认拒绝。Dream 的领域状态仍使用插件自有持久记录。
+
+
+`acn-formation` 增量消费公开 session/event，投影与状态共用 session 锁，先同步正文再推进 lastSeenSeq。未处理行超过主文件 50MiB 时写入 `transcript-pending/`，先持久分片再替换主文件，最后清理副本；恢复核对重复 seq 的完整正文，冲突即拒绝。模型输入为未处理区间、全部 active/stale 本地 Claim 和形成说明。系统内容、私有记忆及 provider replay 不会进入输入。
+
+投影捕获按会话保留失败事件及其后继，不能用后继成功覆盖旧失败。文件暂不可写、句柄不足或锁超时最多尝试三次；持续失败时阻止该会话的形成，不阻止其他会话或前台聊天。DSH 适配层在每次服务启动后首次准备该会话时，只读原会话日志并核对知识归属，重新执行公开事件过滤，补齐共享处理游标之后的缺失正文；已处理内容不重新形成，已有同 seq 正文不同则拒绝覆盖；根据原日志确认属于私有工具的既存误写结果会先清除，不能进入形成输入。归档入口按宿主日志中的当前工作配置验证归属，草稿改选留下的旧空目录不再拦截其他配置的归档。重放只有在宿主确认会话已撤销归档，且存在归档上界之后的真实用户输入时，才恢复解除暂停与续聊活动时间；仍在归档、仅内部通知或归档状态未知时保留暂停。原日志不可读或未覆盖既存未处理投影时停止形成，保留任务供恢复后重试。原日志是跨进程修复依据，不新增一份含私有正文的投影日志。关闭时的可选收尾按会话隔离失败，失败会话保留原日志供恢复，其他会话仍可入队；重复关闭共用同一清理任务，不因收尾失败跳过共享 worker、投递器和团队客户端的关闭。
+
+扫描、全局备用路由保存、入队与投影失败分别记录阶段和安全错误码，不保存异常原文。全局备用路由失败不影响已保存自身路由的会话复盘；空闲扫描及归档对账逐会话隔离失败。归档待派发标记保留到输入恢复，后续扫描补投冻结范围的 Finalize，不因一次恢复失败丢失收尾。活动中的失败任务区分文件占用或权限、空间或配额、单条容量限制、损坏冲突和原会话来源不可读，不会一律归因于磁盘空间或模型服务。
+
+形成状态还持久化活动时间、已完成人工轮次和归档暂停标记。`turn/start` / `turn/end` 与真正准入的 `user/message` 决定轮次；attach、查看历史和状态查询不更新活动时间。空闲策略对未处理投影计算批量或尾部门槛，路由可用且无前台 turn 时入队。手动 Recap、压缩和归档各自冻结上界，成功提交才推进共享游标并清理轮次。
+
+兼容基线没有普通归档完成事件，`dsh-adapter/formation-archive.ts` 在插件生命周期内包裹公开 `workspaceRegistry.archiveSession`，保留宿主的活动检查和停止行为，卸载时恢复方法。归档前持久保存 intent 和上界，成功后持久暂停及待派发标记，再投递 Finalize；启动时依据宿主归档集合恢复已完成归档或撤销未完成 intent。暂停只被实际用户输入解除，撤销归档本身不解除。已有 workspaceRegistry 在空闲扫描启动前完成对账；没有该服务的宿主组合仍支持其他形成入口。
+
+任务保存于 `jobs/<id>.yaml`，包含状态、尝试次数、退避时间及单调 ordinal；固定优先级后按入队顺序执行。只有取得 worker.lock 的进程恢复 running 并消费。持有者每秒检查队列；其他进程在入队或每 60 秒尝试接管。租约与队列短锁独立，领域提交仍遵循知识锁到上传锁的顺序。
+
+Dream 的暂停状态保存在共享任务中。持有者在模型等待时监听该标记，并在每个阶段边界重读；其他宿主发出的 stop 同样生效。prepared 期间先完成当前本地组，之后读取暂停标记，不能继续下一候选或最终收尾。
+
+模型与网络调用均在知识锁外。提交时获取知识锁，恢复 pending edit 和已有形成 checkpoint，再比较分析快照。首次 prepared 前版本失效会抛可重试的 `AnalysisChanged`，不消耗原对话区间；Inbox 在生成 effect journal 前执行相同检查，不标记消息完成。prepared checkpoint 固定 Claim / Dispute / Trace 的实体与 ID，逐个提交并记录已执行内容；之后持久入上传队列（仅团队模式）、标记 applied、推进共享处理游标并回收 transcript。崩溃恢复识别落盘后尚未记录进度的精确目标；发现外部变更则放弃其余旧方案。已 applied 的 checkpoint 只补游标和回收，不再调用模型。
+
+卸载会取消未 prepared 的模型调用，通常在十秒内到达安全点；若本地提交仍未收敛，保留租约直到提交结束。worker 由知识服务拥有，Formation、Inbox 和 Dream 注册各自处理器；禁用某一行仅移除对应处理器并保留任务。状态与 retry 不依赖 Formation 行。
+
+Inbox 同步先逐条持久化，再 ACK 成功保存的前缀；ACK 只确认 receipt，done 才代表本地内化完成。单 worker 在模型前回收旧消费者的 processing 租约，每轮最多领取 1024 条。同类连续消息共用一次调用，Policy 撤回会先冲刷前批次并确定性废弃直接依赖。CAU 可编辑本地 active/stale 和自身 direct deprecated Claim，其他 holder 的冻结快照只读；输入没有 Memory、USER 或 transcript。
+
+批次 `inbox/effects/<canonical-id>.yaml` 保存成员快照/hash、分析 Claim、固定目标/Trace/Dispute、已执行结果和状态，其他成员文件指向 canonical。恢复先整体校验成员及引用，补齐缺失 refs，再补本地效果；applied 后补 done。新批次开始前先恢复已 prepared 的前缀。这个 journal 是插件私有格式，协议实体仍与 Rust 相同。
+
+上传在独立 `delivery.lock` 生命周期租约下单飞执行，HTTP 期间不持知识锁或 pending 锁。成功后用 id + revision 移除 Claim，避免删去并发新版本；每轮每 ID 只发送一次，新版本留待下一轮。尝试 Claim 后独立投递 Dispute，不因关联 Claim 更新失败或暂停而阻断已有团队版本的争议；缺失依赖由服务端判定，失败保留重试。服务确认后记集合台账，确认与本地记账之间崩溃时以相同实体 ID 重送。知识应用、会话创建、手动 Inbox 及每十分钟补传触发投递；网络、鉴权等故障保留队列，明确拒绝的 Dispute 409 则移出自动重试并告警。
+
+形成与 Inbox 的团队去重只查看待投递和成功上报台账，本地单人争议不会阻断新的团队上报。读取时先 pending 后台账，避免交付确认与移除 pending 之间的并发空隙。
+
+Policy 撤回区分本地状态变更与补传集合。所有直接依赖都进入 `syncClaims`，已废弃条目保留精确版本、不计作新 Trace 输出；该集合与 effect 一同持久化。恢复仍检查分析快照和团队授权，第三版本使尚未执行的补传失效，不借撤回覆盖并发修订。
+
+投递前在短知识锁内确认存储已恢复，并核对所有待传 Claim 的当前精确版本。版本漂移或缺失时暂停该项；投递层不自动替换正文，尤其不能把单人期间的后续整合当作已有依赖。团队编辑正常入队或显式 `sync_review` 重绑后才能发布新版本。
+
+## Dream 的自主整理与恢复
+
+`acn-dream` 激活、agent/created 及每四小时检查资格；上次成功满 24 小时、至少五条不同的自有 Claim 版本变化才自动排队。手动运行跳过两个门槛，仍须有自有非废弃 Claim。失败、停止和部分提交不更新成功冷却，未完成候选沿原任务恢复。单 worker 按 Finalize、Recap、Inbox、Dream 的优先级处理，Dream 在 prepared 前让位，prepared 后完成当前组再响应停止或卸载。
+
+队列领取、入队时抢占、跨进程监控和 Dream 阶段边界共用 runnableJob 条件：queued、未暂停、已注册处理器、nextRunAt 已到期。处理器禁用或退避中的高优先级任务仍持久保留，但不会导致 Dream 反复让位重领；重新启用或到期后才参与调度。
+
+自主整理运行在 DSH 的 AgentLoop 子会话中，插件不另建通用执行循环。初始 Claim 按 effective_updated_at、created_at 降序、ID 升序装入，保守预算 64000；超长或较旧条目可能遗漏，目录仅用于发现，须经 read_claim 完整读取后才能登记。模型自行决定探索顺序与深度，通过 dream_record_candidates、dream_stage_group、dream_validate、dream_apply_group、dream_keep_candidate 和 dream_finish 推进。允许继续发现候选、逐组立即执行、明确保留和零修改。
+
+候选登记先在副本上校验整批，全部通过才替换持久进度。当前候选允许扩展及调整类型，不能移除已有目标或与其他未处理组重叠；调整会撤销旧验证而保留草稿供模型继续修订。恢复用 group_id 与 validation_id 共同关联执行回执，避免同名后续组误用旧结果。首次无探索结束会给一次持久提醒，普通文本收尾有最多两次同上下文协议修复，所有请求仍受探索与收尾总额度约束。
+
+`dream/autonomous.ts` 持有领域工具事务、候选、已读 ID 与持久模型轮数。复核采用当前原版的逐 Claim SemanticReview：解释信息去向、事实纠正、证据 ID、最终名称与确定性；不要求旧的双向全文引用或原摘要逐字复印。结构、来源、直接证据、权限和 CAS 仍由宿主独立校验；原始 high 资格固定，不能通过前一组降级绕过。旧格式的 prepared 记录及旧结构化适配入口保留兼容，不重新解释已经固定的提交。
+
+`dsh-adapter/dream-agent.ts` 只负责接入宿主循环、隔离工具与上下文、路由和生命周期。每次 agent/request（包括宿主同一步内重试）先落盘轮数，默认 24 次探索加最多 3 次收尾，恢复及自动重试不返还额度。收尾阶段通过独立 required context 在请求准入后刷新通知，不再允许发现候选、新证据读取或同步复核；已有项仍须通过正常版本与语义校验。模型结束收尾或收尾额度用尽后，未完成候选标为 skipped 并清除未提交草稿，持久 final checkpoint 终结本次并记录冷却。下次触发建立新任务与当前 Claim 快照。崩溃恢复可完成同一次尚未结束的收尾，但不会重置额度；旧版 budget_exhausted 暂停迁移为有限收尾，不分配新探索额度。
+
+宿主明确报告工具参数 JSON 解析失败时，失败响应尚未进入可执行工具消息，插件通过独立 required context 回喂安全的解析错误、未执行说明和修复要求，再复用宿主同一步重试；不伪造无对应调用的工具结果，不回传坏参数正文。合法响应被接纳后清除当前错误 context。每次子会话最多额外重试两次，计入原有持久额度，成功调用不重置此上限；达到上限保留具体错误和已有进度。合法 JSON 仍经过同一工具 guard 与领域校验。受宿主接口限制，解析失败的整次响应（含同批合法调用）均不执行，须由模型重新发出。
+
+每组先写 `dream/<job>/executions/<validation-hash>.yaml` 和可读审计，之后在知识锁内重检当前版本，写 `dream_pending.yaml` 字符串指针，先写存续承接、再写废弃来源，同锁内持久入队整合依赖。完成组、Trace、applied、DreamState 后删除 pending。最终 checkpoint 位于 `runtime/supervisor/dream/<job>.yaml`，其成功状态才更新冷却。恢复同时发现指针与指针落盘前的 prepared 记录；所有知识入口及 worker 领取任务前先恢复本地 Dream，失败不消耗其他任务 attempt。
+
+恢复接受精确 before 或精确 target，第三版本使本组剩余效果失效，已落盘目标和外部编辑保留；原因记入 `report.md` 与 `executions/*.md`。上传不阻塞本地恢复。整合弃用只在每个当前精确承接已获远端确认，或有显式后续整合链且最终承接已获确认时就绪；递归检查防环，清理保留传递依赖。承接普通修订使旧依赖继续阻塞，需 `sync_review` 重新核对完整来源、当前版本与信息去向后重绑；同步日志可恢复，但不修改 Claim。
+
+## 受限证据校准
+
+任务 payload 和 origin 冻结可信会话 cwd 的 canonical 工作区；模型不能指定新根。`EvidenceStore` 持久化候选 Claim revision、工作区、额度和真实读取回执。读取预算在执行前预占，回执在响应工具前同步落盘。当前候选在校验错误后可以继续读；扩展目标时只追加合格的冻结版本，保留原回执和已用额度，不允许删除原目标、换根或替换旧版本。提交前关闭清单并重检实际证据。证据锁只覆盖本地短 I/O，子会话和结构化模型均在领域数据锁外。
+
+`dsh-adapter/dream-agent.ts` 通过 agents.create 的 setup 在发布前清除继承能力、强制 native 模式、注册领域工具与受限只读工具并安装最终执行 guard。完整系统段落不插值，关闭可选 context，并用同名空 scoped contribution 阻止 required context 在准入刷新时回流。知识目录和变化通知跳过这种查证会话；形成、Inbox 和 Dream 的普通会话触发也忽略子会话。子会话结束、取消和超时后必须 dispose 并排空循环，不能留下后台工具继续工作。
+
+文件策略同时核对 lexical / canonical 根、逐层拒绝符号链接，打开时使用 no-follow/non-blocking，前后校验普通文件、inode、链接数、长度和修改时间。版本包含完整文件原始 SHA-256 和字节数，实际返回页保留完整行。glob/grep 有累计遍历和读取额度，只是定位结果；唯一独立证据是绑定明确 claim_ids 的 file_read。工具不暴露 shell、通用代码、网络、团队或私有 Memory 能力。
+
+## 知识提炼与领域数据保护
+
+知识提炼过滤名称包含 `memory` 的工具调用及其结果（不区分大小写），覆盖原生调用和程序桥子调用。`run_code` 外层代码和回显不采集，只保留实际公共子调用。Recap / Finalize 明确排除私有记忆指令、记忆文件更新、Memory 工具结果及用户画像、偏好和私密信息作为 Claim / Dispute 的依据。
+
+普通文件工具不能绕过领域接口读写 ACN 数据。知识插件检查实际路径、目录包含关系和硬链接，最终门禁复核工具参数与工作目录；写入与编辑意图沿用同一目录边界。
+
+## 只读迁移
+
+`commands/import.ts` 在目标写入之前验证源路径、UTF-8、DTO、归属，再持知识锁逐文件发布。`writeTextAtomicIfAbsent` 复用原子写的临时文件与 fsync，以独占硬链接发布完整目标，已有路径不覆盖；源目录从不加锁或写入。导入没有独立后台任务或网络调用；进程中断后用户重试补齐缺失文件，不承诺整批原子可见。
+
+草稿协议中，`operation.reason` 只作为无 changes、无独立 change_basis 的质量废弃简写，不是通用备注；所有其他依据使用 change_basis。JSON schema 字段说明与错误反馈给出具体操作 ID / 类别。整合时保留指向将废弃输入的既有来源，仅免除合回存续 ID 自身的自引用。
+
+Recap、Inbox 和 Dream 的 prepared 日志固定记录创建时的团队共享授权。单人事务恢复后仍只应用本地效果，不因恢复时切到团队模式而补传；旧日志缺少授权时告警并仅恢复本地效果。明确被 Maintainer 以 409 拒绝的 Dispute 按精确版本保存终止记录，先记录再出队，恢复不会重新投递该版本；这不等于成功上报，也不阻止新争议。
+
+## 活动与配置恢复
+
+`activities.ts` 只投影公开任务结果和投递台账，按筛选条件分页；不输出 Memory、模型正文或报告路径。worker 保存失败分类，停用处理器的排队任务显示为暂停，持久状态仍留在队列。`maintainer_uploads/delivery_status.yaml` 保存实体、错误分类、HTTP 状态与失败尝试次数；版本或依赖等待不冒充网络尝试。永久拒绝以精确版本的拒绝台账为准，展示回执只取消提醒，不改变投递事实。
+
+凭据替换生成新引用。凭据存储、状态读取、配置保存与废弃临时引用共用服务端顺序锁；存储响应未知时重用草稿的临时引用确认结果，配置保存未知时不直接清理。明确拒绝后的清理仍检查配置和冻结会话的引用，不能删除已采用的密钥。配置冲突刷新合并未修改字段；团队开关、地址与引用按整体选择，双方均修改时要求用户明确保留本地或已保存连接，避免混用另一团队密钥。终止拒绝按争议精确版本保存已知尝试次数，旧拒绝记录至少计入其必然发生的一次 409。

package/docs/command-reference.md

@@ -0,0 +1,201 @@
+# 命令与行为参考
+
+第一次使用请先阅读带界面截图的[使用指南](user_guide.md)。本文保留工具参数、恢复行为和安全边界，供查阅与排障。
+
+命令使用当前会话绑定的工作配置和 Agent 身份，支持浏览、修订已有知识，以及通过 Recap / Finalize 形成知识。单人配置不会联系团队服务。首次使用需先保存工作配置，再新建会话并选择；未绑定配置的历史会话仍可普通聊天。
+
+模型可调用 `claim`：
+
+| action | 参数 | 行为 |
+| --- | --- | --- |
+| `list` | `query?`、`include_deprecated?`、`offset?`、`limit?` | 搜索 name/scope/statement，默认不显示 deprecated |
+| `read` | `id` | 返回完整 Claim 与 revision，只允许读取当前 holder 的 Claim |
+| `update` | `id`、`expected_revision`、至少一个可编辑字段 | CAS 修订；过期时返回 `{conflict:true,current_revision}` |
+| `traces` | `claim_id?`、`offset?`、`limit?` | 查找当前 Agent 的 Trace，可按输入或输出关系过滤 |
+| `read_trace` | `id`、`task_offset?`、`task_limit?` | 分页返回原始任务文本 |
+
+列表默认每页 20 条，最多 100 条；Trace 正文默认每页 4000 个 Unicode 字符，最多 16000 个。分页结果包含遗漏计数和下一页 offset。动作只接受自身字段。
+
+可编辑字段为 `name`、`statement`、`scope`、`evidence_summary`、`confidence`、`status`。修订保留 id、holder、created_at 和 source_claim_ids，拒绝空白文本、不可见控制字符和明确的指令劫持/凭据外传模式。每次接受的修订都会推进更新时间，即使给出的值与原值相同；未来时间戳也保证严格递增。子代理可以读取，修订会被门禁拒绝。
+
+```json
+{"action":"read","id":"claim_00000001"}
+```
+
+取得实际 revision 后，将其原样用于 update。领域失败以规范 JSON 返回，文件损坏等基础设施失败由工具执行器报告为错误。
+
+并发修改同一 Claim 时，只有使用当前 revision 的写入能成功；遇到 `conflict` 应重新读取并判断，不能盲目覆盖。知识正在提交且锁等待超时时，Claim 工具返回 `error.kind=knowledge_busy`、`retryable=true`，可等本地提交完成后再试。取消锁等待不会继续写入。已经成功的修改不会因后续变化通知失败而被报告为写入失败。
+
+前台步骤的增量知识通知遇忙会暂缓，继续使用已冻结的目录，后续步骤重新检查；不会为刷新通知终止正常编码回合，也不会提前推进通知游标。
+
+用户可以直接运行：
+
+```text
+/acn-status
+/claim
+/claim list example --offset 0 --limit 20
+/claim list --include-deprecated
+/claim show claim_00000001
+/claim set claim_00000001 name="revised name" confidence=medium
+```
+
+`set` 会先读取当前 revision，再进行同样的 CAS 修订。命令及其输出不提交给模型；状态命令显示身份、计数和最近十项后台任务，不输出凭据或私有正文。
+
+每个会话在创建时冻结有界目录；resume、compact 和 fork 沿用已有目录，clear 重建基线。fork 独立确认当前知识变化，不继承父会话的通知游标。目录只有身份字段，完整基线覆盖未展示的 Claim。其他会话或进程修改知识后，下一个获准请求会收到累计变化提示；同一知识版本只准入一次。提示只包含 id、name、scope、status 和变化类型，正文仍需按相关性调用 `read`。
+
+使用原子替换写文件时，目录 mtime 可立即触发重新检查；外部程序原地写入文件时，最多经过约两秒的缓存兜底检查发现变化。当前会话目录不因变化提示而重写。
+
+
+## 知识形成与失败重试
+
+单人和团队模式都支持以下触发。阈值只统计尚未成功处理的增量，不按整个会话的累计历史计算。
+
+| 触发方式 | 默认条件 |
+| --- | --- |
+| 手动 `/recap` | 有新增公开投影即可，不要求轮次、token 或空闲时长；没有新增内容不创建任务 |
+| 批量空闲 Recap | 已完成的人工交互达到 10 轮，或估算达到 100000 token，并且空闲至少 5 分钟 |
+| 尾部空闲 Recap | 有未处理内容并空闲至少 1 小时，不要求达到批量门槛 |
+| 宿主成功压缩 | 对实际被压缩的安全历史范围入队 Recap，不受空闲门槛限制 |
+| 归档 Finalize | 冻结归档时的处理范围并收尾；迟到结果不自动追加到这次任务 |
+
+自动空闲检查每 30 秒执行，也会在前台任务结束时检查；必须有可用模型路由且该会话没有正在运行的前台 turn。进入持久队列不代表立即调用模型。完成轮次只计入实际用户输入对应的成功 turn，内部通知、失败或取消的 turn 不计轮次；token 是公开投影 UTF-8 字节数除以四的近似值，不是模型账单数。
+
+查看历史、切换页面、重新加载会话和重启均不刷新空闲时间。归档后自动触发暂停；仅撤销归档或查看历史不会恢复，真正继续发送用户消息才恢复。归档前正在运行时，普通归档沿用宿主的拒绝规则；选择停止并归档时先冻结范围，再沿用宿主取消流程。手动 `/recap` 在前台运行中只提交此前已完成的安全范围，在暂停中也不会扩大归档范围。
+
+Recap 和 Finalize 共用处理游标，已成功形成的区间不会再次调用模型。Finalize 可以取消尚未 prepared 的 Recap；prepared 后先补完本地提交。重复自动扫描不会为同一失败区间反复创建任务；修正问题后手动重试。旧配置 `finalizeIdleMinutes` 和 `finalizeOnDispose` 保留为显式启用的兼容选项，默认关闭。
+
+```text
+/recap
+/acn-finalize
+/acn-status
+/acn-status retry <job_id>
+```
+
+`/recap` 和 `/acn-finalize` 返回持久任务 ID（`/recap` 无新增内容时直接提示），不向普通对话追加用户命令。用 `/acn-status` 查看 queued / running / succeeded / failed、尝试次数及可操作的失败提示。结构或引用校验默认最多五次（`llm.structuredRetries`）；每个结构化尝试的传输最多三次，临时失败可进入持久退避，任务最多五次尝试。达到自动重试上限时会明确提示手动重试。修正原因后可按任务 ID 重试。没有本会话的请求路由时，需要先完成普通模型请求，或配置 `llm.provider` / `llm.model`；不会借用别的会话路由。
+
+Inbox 内化、Recap/Finalize 共用结构化响应校验：坏 JSON、字段或引用不合法时向模型提供纠正反馈；输出达到 token 上限与返回工具调用、附件会单独分类。失败不会发布未通过校验的知识，未完成的 Inbox 消息与形成区间保留。
+
+处理活动展开后显示已保存的原因与重试按钮。常见模型错误如下；诊断不包含提供商返回的原始正文、密钥或私有内容。
+
+| 分类 | 处理方式 |
+| --- | --- |
+| `AUTH` 鉴权失败 | 检查 DSH 提供商凭据配置后重试 |
+| `QUOTA` 额度不足 | 检查额度或更换知识处理模型 |
+| `CONTEXT_WINDOW_EXCEEDED` 上下文超限 | 缩小输入范围或使用更大上下文模型 |
+| `MAX_TOKENS` 输出被截断 | 结构化任务在现有次数内纠正；仍失败时调整输出上限或精简输出 |
+| `MALFORMED_RESPONSE` 响应格式无效 | 显示格式分类；Dream 的明确工具输入 JSON 语法错误最多额外自动重试两次 |
+| `EMPTY_RESPONSE`、`RATE_LIMIT`、`SERVER`、`TIMEOUT`、`TRANSPORT` | 结构化任务按既有次数重试；Dream 由宿主处理重试，宿主终止后保留分类与进度 |
+
+限流或临时服务错误若带有 `Retry-After`，会通过已有持久队列延后再试，期间可以处理其他任务；HTTP 408 归为可重试的超时。
+
+Dream 的宿主重试仍计入探索和收尾额度；兼容旧任务的受限查证子会话也按每次实际请求计入查证额度，耗尽后封存已取得的回执并结束查证，无直接证据时保持原样，重复进入不会扩充预算。同一次宿主失败结束后不会再叠加任务级模型自动重试，已有超时、暂停和固定提交恢复机制继续生效。
+
+手动 `/acn-finalize` 只提交收尾任务，不会归档宿主会话，也不会开启归档暂停。归档暂停由 DSH 的归档操作触发，恢复条件仍是真实用户续聊。
+
+只有有价值的新增、更新或实际使用已有 Claim 时才写 Trace；空结果也推进游标。新增 Claim 默认 active，更新只能针对自身持有且本轮可见的 Claim。来源沿用原版当前区间的扁平可见规则：本地非废弃 Claim 及已过滤 transcript 中完整合法的 Claim ID 可以参与校验；不从已消费区间或私有工具继承授权。非法 used IDs、非法来源、未声明占位符、越权更新或重复 Dispute 引用会让整批结果重新校验。首次 prepared 提交前发现分析快照被并发修改时，保留原对话区间并按新快照重试；Inbox 同样保留待内化输入。已经 prepared 的崩溃恢复若遇到外部第三版本，则保留已提交结果和用户编辑，告警并放弃剩余旧方案。
+
+会话投影从插件激活后增量记录，仅在本地保存。系统指令、目录、插件变化提示、压缩替换、私有记忆工具内容和模型私有推理不进入复盘；公开工具正文完整保留，附件只保留占位符。旧投影已经截断时仍明确标记，升级不能补回其缺失片段。不读取私有 MEMORY / USER 文件。主 transcript 文件最多 50MiB，装不下的未处理投影保存为本地有界分片，成功处理后回收；单条投影超过上限会阻止不完整区间形成。投影超过所选模型上下文时，请换用更大上下文模型后重试。
+
+关闭插件时中止尚未 prepared 的模型请求，已排队任务下次启动继续；没有排队的增量仍按原空闲截止时间检查，不因重启立即收尾。prepared 本地提交到达安全点后才释放 worker 租约。单人模式只保存本地知识；团队模式先持久入队，再于锁外投递。Recap、Inbox 与 Dream 的 prepared 日志固定创建时的团队共享授权；单人事务及缺少授权的旧日志在团队模式恢复时仍只落本地，旧日志另有告警。
+
+## 团队查询、Inbox 与同步
+
+配置两个团队 endpoint 后，模型可使用 `consult_router`：`{"mode":"overview"}` 发现 scope，再以 `{"mode":"query","scope":"service / retries","semantic_query":"bounded retry"}` 获取完整候选及关联 Dispute。query 的 scope 必填；overview 不能带 query 字段。概览是发现入口，候选正文才可作为来源引用。会话创建时冻结团队概览，resume/compact 沿用，clear 重建。
+
+通过会话输入框旁的 ACN 菜单选择团队配置时，首发前会等待收件同步和内化；只查看历史不会启动同步。实际继续工作时，Inbox 默认后台同步并排队内化，不向普通对话插入命令。用户也可执行 `/inbox`：显示拉取、持久化、ACK 和待内化数量以及任务 ID。通过 `/acn-status` 查看结果，失败后用 `/acn-status retry <job_id>` 重试。Inbox 没有自身会话路由，默认使用同一知识身份下最近会话的请求路由；首次显式同步会优先读取当前会话的待生效模型选择；也可显式配置后台 provider/model。
+
+Policy 是建议，只有内化后才改变本地 Claim。普通 Policy 可创建、修订或跳过；CAU 同时校验持有权、仲裁冻结上下文和相关 Policy 来源。连续同类消息合批，单 Policy CAU 可补充兼容归因，多 Policy 必须由模型明确指出相关来源。撤回 Policy 直接废弃依赖它的本地 Claim，不递归废弃间接下游。内化只读取 Policy、冻结 Claim 和本地 Claim，不读取私有 Memory / USER 或会话正文。
+
+在插件管理器关闭 Inbox 组件时，会取消等待中的拉取和模型调用，并等待当前本地提交收敛。已经 prepared 的批次完成固定提交后停止，不能继续下一批。未完成消息和持久任务保留，重新启用后继续；知识存储及其他任务仍可工作。
+
+ACK 表示消息已经在本地持久化，ACK 失败也会继续处理已保存内容。服务不可用时保留本地队列；鉴权失败只告警一次，可继续本地会话。修复凭据后再调用 `/inbox` 会触发补传，非空队列也会每十分钟自动尝试。普通编辑和形成成功同样触发投递，先尝试 Claim，再独立尝试 Dispute；Claim 更新失败或暂停不会阻塞争议上报，缺失依赖由服务端判断。状态页显示两项服务的独立连接状态和待上传数量，不包含凭据或服务器响应正文。
+
+Maintainer 以 409 明确拒绝的 Dispute（例如直接 Claim 已废弃）持久记录被拒绝的精确版本，停止自动重试并在日志中记录争议 ID；崩溃恢复不会将该版本重新上报，本地争议记录保留；网络、鉴权等故障继续保留待传项。
+
+从团队切换到单人期间，旧队列保持冻结。恢复团队后，普通待上传版本若已与本地不同，会暂停该项并告警；Dispute 仍独立尝试报告已有团队版本的争议。不能把旧 active 版本重新发布，也不能把单人期间的整合弃用自动当作团队裁决。应在团队模式核对并修订需要共享的 Claim，再触发投递；新的单人知识不会自动加入队列。收到团队 Policy 撤回后，直接依赖的 Claim 会按该次内化结果重新同步，已废弃条目保留原版本。
+
+单人时期本地保存过某组争议，也不代表已向团队上报。在团队模式重新发现并提出同组冲突时，会按待投递与成功上报台账判断是否入队。
+
+单人模式不提供 `consult_router`；`/inbox` 提示没有团队 inbox，并可处理已有本地 pending，始终不发团队请求、不创建上传目录。子代理可以团队查询，但不能手动触发 Inbox、形成或修改知识。
+
+## Dream 知识整理
+
+```text
+/dream
+/dream stop
+/acn-status
+/acn-status retry <job_id>
+```
+
+Dream 清理自身 Claim 中的纯一次性记录，或把同主题知识整理到已有存续 ID。原始废弃正文仍可通过包含 deprecated 的列表读取；有用规则、条件、例外、备选行动和来源必须保留。没有安全改动时可以保持原样。默认不查证工作区；不读取私有 Memory / USER、会话 transcript 或裁决 Dispute。
+
+整理模型可用 `read_trace` 先按 `claim_id` 列出已读自有 Claim 的关联 Trace，再用 `claim_id` 与 `trace_id` 读取正文。列表的 `offset` / `limit` 按条计（默认 20，最多 100），正文按 Unicode 字符计（默认 4000，最多 8000），返回下一页位置；旧 `id` 单独读取入口仍兼容。Trace 只说明形成或使用背景，不能单独证明事实正确，也不能用来提升置信度。
+
+Dream 通过 DSH 子会话自主发现候选、按需探索、暂存、校验、语义复核并逐组提交。复核必须解释每条输入的有效条件、例外、备选行动、版本和证据限制的去向，并核对最终名称与置信度。沿用原 ACN 的简洁逐 Claim 复核，不强制逐字复制原摘要；事实纠正与置信度提升仍须真实、适用且版本未变化的直接证据。
+
+默认在插件激活、会话创建时检查，运行期间每 4 小时再检查一次；至少 5 条不同的自有 Claim 版本变化，且距离上次成功整理已满 24 小时后自动执行。首次没有成功记录时不受 24 小时冷却限制，仍需满足数量条件。`/dream` 跳过时间和数量门槛，已有排队、运行或暂停任务时继续原任务；failed 任务通过 `/acn-status retry <job_id>` 重试。`dream.enabled=false` 同时禁止自动和手动执行。路由使用同一知识身份下最近会话的请求路由，或显式配置的 `llm.provider` / `llm.model`。子代理不能触发或停止 Dream。
+
+`/dream stop` 取消正在等待的模型调用或知识锁，保留候选、草稿和已提交组。已 prepared 的本地组先完成，再暂停；停止确认表示请求已记录，可通过状态页观察是否到达暂停点。再次 `/dream` 可继续用户主动停止的原任务，也可通过重新启用插件恢复。额度耗尽则走有限收尾并结束本次，不属于暂停；收尾结束会记录冷却，下次手动触发建立新任务。用户停止和未完成的故障恢复不会消耗成功冷却；高优先级知识任务可让尚未 prepared 的 Dream 让位。
+
+直接通过宿主取消 Dream 子会话也不会自动启动收尾或丢弃未提交草稿；任务保留进度并报告未正常结束，可用 `/acn-status retry <job_id>` 显式重试。
+
+`llm.timeoutMs` 对每次模型请求分别计时，多个正常请求的累计耗时不会触发同一超时；整体成本仍由探索与收尾额度约束。单次请求超时会停止子会话、保留已用额度和进度，由持久任务按故障恢复规则处理。
+
+只向当前可执行的高优先级任务让位。禁用处理器后保留的排队任务、暂停任务及尚未到期的重试任务不会阻止 Dream；恢复处理器或到期后会重新参与调度。
+
+报告位于 Agent 数据目录的 `dream/<job_id>/report.md`，包含装入覆盖数、候选的执行/保留/跳过原因和实际修改 ID。逐组 `executions/*.md` 记录 before/after、复核与执行结果。预算没有装入的 Claim 不代表不存在；语义自复核不等同于独立知识质量评估。
+
+复核错误不会直接落盘为知识。修复、工具反馈和失败重试均计入请求额度：`dream.maxModelSteps` 提供探索额度（默认 24，范围 1–128），耗尽后 `dream.maxWrapUpSteps` 提供额外收尾额度（默认 3，范围 1–8）。请求前持久记账，抢占、崩溃和重启均不重置。收尾只能处理已有项，必须如实总结覆盖情况；`dream_finish` 会将剩余 pending 标为未完成并丢弃未提交草稿。收尾耗尽或模型只返回文字时，插件按真实执行记录结束任务，不将未完成事项冒充成功。下一次 `/dream` 重新读取当前 Claim。探索额度尚未耗尽就提前以普通文本结束且未调用 `dream_finish`，会在当前上下文获得最多两次协议修复机会，之后仍未完成才失败。没有探索或提案就调用结束工具时会先提醒一次，再次确认仍可零修改结束；提醒和修复不增加请求额度。
+
+团队整合先上传完整存续承接，确认后才投递来源的 deprecated 版本。服务故障时，已完成的本地整理保留，上传队列独立补送。承接被其他编辑修改后，旧弃用请求会阻塞；后续 Dream 可把它作为同步候选，重新复核当前承接并重绑依赖。该步骤不改 Claim。来源重新 active 会取消旧弃用依赖。
+
+重绑前也检查当前承接是否仍包含原来源的完整证据摘要，丢失则保留阻塞的弃用依赖，不自动替用户重写 Claim。升级后，尚未 prepared 的旧草稿若不满足保留规则，会清除旧复核、携带具体反馈重新起草；已经 prepared 的固定提交仍沿原恢复协议完成，已生效历史不自动重写。
+
+## Dream 证据校准
+
+显式启用 `dream.evidenceCalibration: true` 后，Dream 可以选择自身 medium/low Claim 做文件查证。原始 high 不进入校准，也不能先降低置信度再纠正；high 的纯质量清理和信息重组仍可进行。
+
+关闭证据校准后，恢复中的任务同样不能发起新文件读取或搜索，旧查证清单不延续该权限。已经 prepared 的固定提交仍核对既有证据版本并按恢复协议完成，不重新探索或生成证据。
+
+`/dream` 冻结当前命令会话的工作区；自动任务冻结最近普通会话的工作区。自主子会话获得已装入 Claim、候选与执行进度，可调用领域整理工具、`read_claim`、关联自身 `read_trace` 及 `file_read`、`file_grep`、`file_glob`。文件搜索做有界字面搜索，仅用于定位；file_read 返回完整文件 SHA-256/字节数、实际读取页和持久 evidence_id。当前不提供联网检索、命令执行、通用代码、编辑、Memory、上传或委托工具，也不会为工具拒绝申请扩大权限。
+
+工作区外、隐藏/凭据路径、MEMORY/USER、私有知识根、符号链接、硬链接、非普通文件和非 UTF-8 文本均不能读取。读取、搜索和目录扫描共用凭据路径拦截，包括 `secrets.json`、`tokens.json`、`app.credentials.json` 和 `secrets/config.json` 等常见名称。该保护按文件名和目录名判断，不扫描普通文件正文中的敏感信息。
+
+整次 Dream 的模型轮数、每组读取工具次数、文件字节、返回文本及搜索范围均有持久预算；到期、停止或卸载会中止并排空子会话。查证子会话不会进入普通形成投影，也不触发 Inbox 或额外 Dream。
+
+每条事实修改都要在 change_basis 中引用该 Claim 自己的新直接证据，更新 evidence_summary，并在逐 Claim 语义复核中说明纠正依据与证据 ID。提高置信度也遵循相同条件，没有按读取次数自动升级的规则；不确定或矛盾时保留原置信度。其他 Claim、Trace、命令输出、模型结论和搜索结果均不能独立授权修改。引用及版本符合要求仍不代表模型的事实判断正确。
+
+本地 `dream/<job>/evidence/<group>.yaml` 保存工作区、候选版本、已用预算和读取回执。重试复用已有读取回执和额度，模型可在剩余额度内继续读取；证据变化使基于旧回执的提交跳过。提交和恢复重检文件版本，过期证据停止尚未完成的写入，已生效结果保留。恢复不再运行模型或查证工具；真实 I/O 故障会暂缓其他知识写入，修复存储后继续。
+
+## 从已有 ACN 目录导入
+
+如果你已经使用过 [ACN 官方仓库](https://github.com/FTShare-Lab/agent-claim-network) 提供的 Agent 侧功能，你可以使用该命令将历史知识导入本插件。
+
+`/acn-import` 是一次性只读迁移。先让原 ACN 停止写入，找到实际 Agent 目录，例如 `<acn_home>/<upstream>/data/agents/agent-a/`；某些部署还有 `dev/` 一层。传入的目录应直接包含 `claims/` 或 `traces/`，不是整个数据根目录。
+
+```text
+/acn-import --dry-run "~/Documents/data/example/data/agents/agent-a"
+/acn-import "~/Documents/data/example/data/agents/agent-a"
+/acn-import "/path/to/agent-a"
+```
+
+`~` 会在插件内展开，含空格的路径加引号；命令不会执行 Shell。Windows 可以直接粘贴原生路径，反斜杠会保留，也接受既有 JSON 转义路径。例如：
+
+```text
+/acn-import --dry-run "D:\ACN data\example\data\agents\agent-a"
+/acn-import "D:\ACN data\example\data\agents\agent-a"
+```
+
+Windows 上的 `~\` 和 UNC 路径也可解析；网络共享的存储可靠性尚未验证。macOS 继续使用原有命令转义规则。
+
+预览只给出可复制数量与冲突列表，不创建目标。实际导入先完整校验源文件，再复制原始 UTF-8 字节；Claim holder 与 Trace agent 必须等于当前 `agentId`，不改归属。单文件上限 16 MiB，不接受符号链接、硬链接、目录伪装、非法 YAML、ID 与文件名不一致或重叠源/目标。
+
+现有目标一律保留，包含同 ID 的不同正文；输出逐项列出跳过内容。
+
+只导入 Claim 和 Trace；锁、会话、待处理任务、Dream 状态、团队队列和凭据不复制。不会请求团队服务或加入上传队列，团队模式也一样；以后主动修订 Claim 会按普通规则入队。
+
+Claim / Trace 使用独占的原子文件发布。整批不是一次原子切换：进程中断后可能已有部分文件可读，重新执行命令会跳过已有文件并补齐缺失文件。源内容应保持稳定；并发源写入会尽力检测并拒绝，但不提供跨运行时的活动数据库快照。子代理不能导入，命令结果不进入模型历史，也不回显私有正文。
+
+### 查找历史失败任务
+
+`/acn-status` 优先显示失败与暂停任务的 ID；`/acn-status failed [页码]` 只列这些任务，`/acn-status all [页码]` 分页查看全部。重试前先修复显示的原因；后台组件停用时需在 DSH 插件管理中恢复它。团队投递异常应在「知识与活动 → 处理活动」查看实体与专用恢复操作，不使用任务重试命令。