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

package/docs/config.md

@@ -0,0 +1,253 @@
+# 配置
+
+日常配置可在 DSH 的「ACN 插件设置」中完成，包括工作配置、知识处理模型和六项高级参数。完整配置保存在组合中的 `id: acn-knowledge` 行，其他参数可通过 YAML 管理。
+
+## 插件设置
+
+打开 DSH「设置 → ACN 插件设置」或「插件 → ACN记忆框架」，也可以从聊天框的 **ACN** 菜单进入。三个入口共用同一张表单。
+
+| 页签 | 可以做什么 |
+| --- | --- |
+| **工作配置** | 创建单人或团队 upstream，查看各自的知识与活动；进入「配置」调整启用状态和「设为默认」，保存后生效。 |
+| **知识与模型** | 选择后台模型和所有配置的知识根目录。模型检查成功后保存，取消或失败会保留原模型。 |
+| **偏好** | 设置结果提示，调整 Inbox 过期、Router 查询总超时、HTTP 单次超时及三项重试参数。 |
+
+每份工作配置有自己的 Agent ID 和知识库。新建时只需填写 Agent ID，显示名称可选。单人使用可自取固定名称，例如 `coding`。以后打开这份配置，开启「连接团队服务」并填写 Router、Maintainer 地址及团队鉴权密钥，继续使用同一个 Agent ID 和知识库。两项地址必须同时填写或留空。需要部署服务时可参考[原 ACN 仓库](https://github.com/FTShare-Lab/agent-claim-network)。
+
+知识根目录支持 `~/`，也支持 Windows 的 `~\`、盘符绝对路径与带空格的路径。默认根目录仍为 `~/.acn-dsh`，在 Windows 上会展开到当前用户主目录，不会相对于项目目录创建 `~` 文件夹。知识目录输入框可填写系统原生路径；高级 YAML 中的 Windows 路径建议使用单引号，例如 `'D:\ACN data'`，避免双引号的转义规则。
+
+Windows 的目录名不能使用 `CON`、`PRN`、`AUX`、`NUL`、`COM1`–`COM9`、`LPT1`–`LPT9` 等保留名称，大小写均适用。upstream 标识会在保存和运行时校验；Agent 使用身份摘要作为目录名，不受明文 Agent ID 的设备名限制。这只限制本机目录，不修改团队协议中的 Agent ID 规则，macOS 的既有名称仍有效。跨设备复用配置时请选 `coding`、`agent-a` 等中性名称；旧的不可用配置可先停用，再新建合法配置，不会自动改 ID 或迁移数据。
+
+「检查连接」先按保存规则校验填写内容，再分别验证两个服务和认证。格式错误会在操作按钮附近指出对应字段，输入保留；地址格式有效但服务离线时仍可保存。地址支持部署路径前缀，不允许用户名、密码、查询参数或片段。在「团队鉴权密钥」直接输入 key，由 DSH 托管；配置只保存自动生成的引用。模型密钥沿用宿主配置。替换密钥使用新引用，只有配置保存成功后才采用；保存失败保留输入和原密钥。已绑定密钥的团队配置修改 Agent ID 时，需要同时输入新身份密钥，或明确移除绑定。若同时保存为单人模式，自动解除旧身份的密钥绑定，旧凭据保留。「移除密钥绑定」可明确解绑，保存前可以撤销。保存配置不会让正在运行的会话切换客户端或密钥；新启动的会话使用保存后的配置。未发送的会话若已启动旧实例，菜单会显示实际模式，并可点击「按已保存配置启动」。新运行实例恢复旧会话时仍选择原 upstream 和 Agent ID，并保留原知识目录。
+
+新会话优先沿用同项目最近新建的普通会话所选 upstream。读取按创建时间排序，不按最近聊天或查看时间；内部子代理不参与，目录的符号链接别名视为同一项目。最近配置失效或归属无法确认时回退到全局默认；全局默认也为空时，可在首发前从 ACN 菜单明确选择，或不启用 ACN 直接聊天。首发前可以改选，首发后归属固定；派生会话继续继承父归属。已有会话和草稿不因新会话的选择而改绑。
+
+选择资格在安装插件后创建空白会话时记录并持久化。安装前的会话、没有选择配置就开始聊天的会话可以继续普通工作，但不能在已有历史上绑定团队；不会注入 ACN 上下文或收集该会话的知识投影。旧版在未配置时记录的空身份只作为创建资格兼容读取，不授予知识访问权限。无绑定历史与已有绑定失效分别处理：前者不阻止聊天，后者仍需恢复原身份，不能回退到默认配置。
+
+此预选直接读取宿主的公开会话记录，不保存项目默认选项，不恢复历史 Agent，也不因读取历史调用模型或同步团队。项目目录只用来确定会话属于哪个项目，不决定知识位置。
+
+团队启动、实际恢复或手动同步会处理 Inbox。连接、鉴权或内化失败会保留归属并提示原因，允许继续本地工作。单人不发团队请求，仍可通过 `/inbox` 处理已落盘的本地 pending。浏览知识和只读检查历史归属不会同步或调用模型。打开完整会话（包括「打开来源会话」）时，宿主可能恢复 Agent，并按团队启动配置同步 Inbox。结果通过聊天框外的提示展示，避免改变输入框尺寸。
+
+知识目录统一使用账号结构，默认根目录为 `~/.acn-dsh`，也可在「知识与模型 → 知识目录」选择其他位置：
+
+```text
+<home>/
+├── settings.json
+└── upstreams/<配置ID>/
+    ├── ACN.md
+    └── agents/<身份摘要>/
+        ├── claims/
+        ├── traces/
+        ├── disputes/
+        └── jobs/、sessions/、dream/ 等运行记录
+```
+
+身份摘要由 Agent ID 生成。不同 upstream 即使 Agent ID 相同，本地知识也分开；同一 upstream 的多个项目会话共用知识。修改显示名称不改变目录，修改 Agent ID 会选择另一份存储。两个相同 Agent ID 连接同一团队时，在通过鉴权后对应同一个远端成员。当前 upstream 的 `ACN.md` 在创建会话时冻结，恢复会话继续使用原快照。
+
+选择已有账号目录时，该位置应直接包含 `settings.json` 和 `upstreams/`。插件加载其中的工作配置，并在原位置读取、修订和新增 Claim、Trace、Dispute。保存后的工作配置公开摘要同步到 `settings.json`；未变化的索引不改写。团队 Key 与知识模型由当前宿主管理，不从索引导入，也不写入索引。
+
+同一知识目录只由一个程序写入。接续已有目录前先结束原程序的知识任务并退出。历史应用、任务和投递账本只读保留，不重放旧任务；已有的本地应用与投递确认可在处理活动查看。来源会话在当前宿主中存在时才提供跳转。读取忽略与当前功能无关的扩展字段，浏览不改写实体，更新实体时只写通用 ACN 字段。
+
+### 接入团队与更换地址
+
+单人期间不积累上传任务，历史 Claim 在接入后仍可本地使用，不会整库补传。已处于团队模式的 upstream 更换地址会沿用知识与上传队列，原待投记录没有固定旧服务器地址。新配置启动后，仍符合重试条件的记录可能发送到新 Maintainer。页面显示当前待投数量并说明影响；需要隔离团队时新建 upstream。
+
+「返回工作配置」和「取消编辑」会放弃当前配置草稿。关闭并重新打开设置可读取最新保存值；保存冲突时可点击「刷新并保留草稿」核对修改。未改动的默认开关跟随最新保存值，主动修改的选择保留在草稿中。模型或偏好单独保存，不会提交正在编辑的工作配置草稿。保存使用宿主的版本校验和原子配置编辑器。有 Agent 正在运行时，先结束当前轮次再保存。
+
+「偏好」中高级参数的「重置为默认值」先填入草稿，点击「保存高级参数」才会生效。沿用插件默认值：Inbox 600 秒、Router 50 秒、HTTP 15 秒、额外重试 3 次、基础等待 500 毫秒、最长等待 8000 毫秒。设置界面将秒换算为配置中的毫秒；HTTP 超时与模型超时独立。显式修改全局 HTTP 超时时，会统一现有工作配置的团队请求超时；只修改其他偏好保留各连接原值。新启动的会话与后台实例采用新参数，已有会话保留启动配置。编辑工作配置的草稿保留期间，请先保存或取消该草稿，再保存高级参数。
+
+## YAML 与完整字段
+
+需要高级配置时，在 profile 的 `cordis.patch.yml` 加入以下覆盖项，并重新启动 profile：
+
+新安装推荐使用 upstream，例如以下两份单人配置。以后在其中一份补填两个 endpoint 即可接入团队。
+
+```yaml
+- id: acn-knowledge
+  config:
+    home: ~/.acn-dsh
+    upstream: coding
+    upstreams:
+      coding:
+        name: 日常开发
+        agentId: coding
+      review:
+        name: 独立审查
+        agentId: reviewer
+```
+
+`upstream` 是没有可用项目历史时的全局默认，可留空；没有历史且未设置全局默认时需明确选择。`upstreams.<标识>` 使用小写字母、数字、下划线和连字符，排除原版保留目录名。每项支持 `name`、`agentId`、`enabled`、`routerEndpoint`、`maintainerEndpoint`、`keyEnv` 和 `timeoutMs`。旧版 `projectUpstreams` 仅兼容读取，不再影响预选，下次保存配置时会移除。
+
+以下完整默认模板也保留旧单身份配置，便于兼容已有安装。未列出可选的 `upstreams` 时继续使用旧入口。
+
+<!-- config:complete -->
+```yaml
+- id: acn-knowledge
+  config:
+    upstream: ''
+    agentId: agent-a
+    home: ~/.acn-dsh
+    sessionEpoch: 0
+    connections: []
+    defaultConnection: ''
+    legacyEnabled: true
+    showCompletion: true
+    team:
+      routerEndpoint: ''
+      maintainerEndpoint: ''
+      keyEnv: ''
+      timeoutMs: 15000
+      routerTimeoutMs: 50000
+      retryCount: 3
+      retryBaseDelayMs: 500
+      retryMaxDelayMs: 8000
+    llm:
+      provider: ''
+      model: ''
+      maxOutputTokens: 32768
+      timeoutMs: 600000
+      structuredRetries: 5
+    catalog:
+      maxClaims: 20
+      maxChars: 24000
+    formation:
+      recapOnCompaction: true
+      idleRecap: true
+      recapMinTurns: 10
+      recapMinTokens: 100000
+      recapBatchIdleMinutes: 5
+      recapTailIdleMinutes: 60
+      recapScanSeconds: 30
+      finalizeIdleMinutes: 0
+      finalizeOnDispose: false
+    inbox:
+      pullOnSessionStart: true
+      processingStaleAfterSecs: 600
+    dream:
+      enabled: true
+      minIntervalHours: 24
+      minChangedClaims: 5
+      checkIntervalHours: 4
+      maxModelSteps: 24
+      maxWrapUpSteps: 3
+      evidenceCalibration: false
+      evidenceMaxCalls: 32
+      evidenceMaxSteps: 24
+      evidenceMaxBytes: 1048576
+      evidenceMaxChars: 16000
+      evidenceMaxFiles: 256
+```
+
+按 id 覆盖会整体替换该行的 config，所以每次覆盖都需包含希望保留的自定义项。未填写的字段由插件补默认值。
+
+单配置入口的 `agentId` 只能含小写字母、数字、下划线和连字符。未配置 `upstreams` 且该字段为空时，插件保持未配置状态：只有 ACN 的 `/acn-status`，不注册 Claim 工具与知识段落，不创建知识文件。`home` 支持 `~`，实际目录仍在 `<home>/upstreams/<配置ID>/agents/<身份摘要>/`，与工作区 cwd 无关。
+
+当前可用的行为配置：
+
+| 配置 | 默认值 | 含义 |
+| --- | --- | --- |
+| `agentId` | 空 | 旧入口的知识 holder；配置 `upstreams` 后由所选项确定 |
+| `home` | `~/.acn-dsh` | 独立数据根目录 |
+| `sessionEpoch` | 0 | 更换身份或知识目录时自动保存的会话时间边界，不应手动清零 |
+| `connections` | 空数组 | 具名连接：`id`、`name`、`enabled`、`agentId`、两个 endpoint、`keyEnv`、`timeoutMs`；ID 确定存储位置，不应重用为另一团队 |
+| `defaultConnection` | 空 | 团队菜单候选，不自动接入 |
+| `legacyEnabled` | true | 是否启用旧版 `team` 连接；停用保留原数据 |
+| `showCompletion` | true | 显示来源会话的知识处理结果 |
+| `catalog.maxClaims` | 20 | 冻结目录条数上限；显式设置更大值仍有效 |
+| `catalog.maxChars` | 24000 | 目录的 Unicode 字符上限 |
+| `llm.provider` / `llm.model` | 空 | 指定后台路由；为空时形成用本会话路由，Inbox / Dream 用持久的同一知识身份下最近会话路由 |
+| `llm.maxOutputTokens` | 32768 | 后台模型输出 token 上限；显式配置优先于默认值 |
+| `llm.timeoutMs` | 600000 | 每次后台模型请求的超时毫秒数；Dream 每次尝试重新计时，不是整次整理总时限 |
+| `llm.structuredRetries` | 5 | 结构和引用校验的最大模型响应次数 |
+| `formation.recapOnCompaction` | true | 压缩后入队 Recap |
+| `formation.idleRecap` | true | 启用批量和尾部空闲 Recap；不影响手动、压缩及归档 |
+| `formation.recapMinTurns` | 10 | 批量门槛：尚未处理的已完成人工轮次 |
+| `formation.recapMinTokens` | 100000 | 批量门槛：尚未处理公开投影的估算 token，与轮次取“或” |
+| `formation.recapBatchIdleMinutes` | 5 | 达到批量门槛后仍需满足的空闲分钟数 |
+| `formation.recapTailIdleMinutes` | 60 | 少量未处理内容的空闲分钟数 |
+| `formation.recapScanSeconds` | 30 | 自动空闲扫描间隔，达到条件后入持久队列 |
+| `formation.finalizeIdleMinutes` | 0 | 旧版定时 Finalize 兼容项；0 关闭，显式开启会增加独立触发 |
+| `formation.finalizeOnDispose` | false | 旧版释放会话收尾兼容项；默认不因关闭或重启立即收尾 |
+| `team.routerEndpoint` / `team.maintainerEndpoint` | 空 | 旧版全局连接的 HTTP(S) 服务，可带路径前缀；新会话按工作配置选择连接 |
+| `team.keyEnv` | 空 | 每次请求经 DSH 凭据服务解析引用；无该服务时兼容同名环境变量 |
+| `team.timeoutMs` | 15000 | 每次 HTTP 尝试（含响应正文）的总超时 |
+| `team.routerTimeoutMs` | 50000 | Router 查询与范围概览的总超时，包含额外重试与等待；连接检查最长 15 秒且不重试 |
+| `team.retryCount` | 3 | 首次请求后的重试次数 |
+| `team.retryBaseDelayMs` / `team.retryMaxDelayMs` | 500 / 8000 | 指数退避起点与上限，带 ±20% 抖动 |
+| `inbox.pullOnSessionStart` | true | 实际启动 / 恢复 Agent 时同步；知识浏览和只读归属检查不触发。打开完整会话可能恢复 Agent；同步失败仍可继续本地工作 |
+| `inbox.processingStaleAfterSecs` | 600 | 独立存储租约的过期窗口；独占 worker 接管后可立即回收孤儿租约 |
+| `dream.enabled` | true | 是否允许自动与手动 Dream |
+| `dream.checkIntervalHours` | 4 | 自动检查间隔小时数 |
+| `dream.minIntervalHours` | 24 | 上次成功后的自动冷却小时数 |
+| `dream.minChangedClaims` | 5 | 自动运行所需的不同自有变更 Claim 数 |
+| `dream.maxModelSteps` | 24 | 每次 Dream 探索请求上限，最多 128；失败重试也计次 |
+| `dream.maxWrapUpSteps` | 3 | 探索结束后的额外收尾请求上限，最多 8；耗尽后终结本次 |
+| `dream.evidenceCalibration` | false | 启用受限文件查证与自身 medium/low Claim 校准 |
+| `dream.evidenceMaxCalls` | 32 | 每个候选组的工具调用总预算，最多 256；失败请求也计次 |
+| `dream.evidenceMaxSteps` | 24 | 旧查证适配器的每组模型步数上限，最多 128；当前自主流程使用整次 Dream 额度 |
+| `dream.evidenceMaxBytes` | 1048576 | 每组累计文件读取字节预算，最多 16777216；先保留额度再读取 |
+| `dream.evidenceMaxChars` | 16000 | 每次读取或搜索返回文本上限，最多 64000；读取仅返回完整行 |
+| `dream.evidenceMaxFiles` | 256 | 每组搜索累计检查的目录项预算，最多 4096 |
+
+选择单人配置的会话使用其单人空间，不发团队请求或创建上传项。完全未选择工作配置的会话只进行普通聊天，不访问 ACN 存储。旧版全局 `team` 配置继续服务已有绑定的会话；新配置使用 `upstreams`，通过会话输入框旁的 ACN 菜单选择。以下仅为旧格式兼容示例：
+
+```yaml
+- id: acn-knowledge
+  config:
+    agentId: agent-a
+    team:
+      routerEndpoint: https://router.example.com/acn
+      maintainerEndpoint: https://maintainer.example.com/acn
+      keyEnv: ACN_TEAM_CREDENTIAL
+```
+
+文件校准可在同一知识行的完整自定义配置中加入 `dream: { evidenceCalibration: true }`。`/dream` 使用命令会话的 cwd；自动任务使用最近普通会话 cwd，缺省为宿主启动 cwd，创建任务后冻结工作区。查证不提供命令执行或联网检索工具；独立证据限于带版本的文件读取。限额写入每组清单，失败、暂停与重启不返还已用额度；修改配置不会扩大原组授权。已经 prepared 的提交仍按固定目标和版本依赖恢复。
+
+可在工作配置中直接输入团队鉴权密钥并保存，也可在启动宿主的环境中提供对应凭据。每次请求重新解析宿主托管值或兼容的环境变量，在插件设置中替换密钥会使用新引用，配置保存成功后才采用；驻留的旧会话实例保留原连接和密钥；重启或释放后重新加载实例时，仍固定原 upstream、Agent ID 和私有快照，但使用该 upstream 当前保存的服务地址与凭据。旧凭据不自动删除，避免影响仍驻留的其他实例。回环地址直连；其他地址优先遵循 HTTP(S)_PROXY 与 NO_PROXY。未设置环境代理时，团队请求使用 macOS 或 Windows 的系统 HTTP(S) 代理及例外；调整系统代理后重启 DSH 以更新已有连接。PAC、自动发现和仅 SOCKS 代理暂不支持。两个服务在启用时各做一次异步 health；失败会显示在 `/acn-status`，不会撤销本地知识服务。鉴权错误每次服务生命周期只警告一次。
+
+
+配置校验要求团队 endpoint 同时为空或同时为 HTTP(S) URL，不接受内嵌用户名、密码、query 或 fragment；`llm.provider`/`model` 必须成对；数值必须处于规定范围。配置错误只报告字段名。
+
+`team.keyEnv` 和 `upstreams.<标识>.keyEnv` 是内部凭据引用，不接受密钥正文。正常使用时在「团队鉴权密钥」直接输入 key，引用由界面自动生成。字段默认掩码显示，右侧按钮切换本次输入的显隐；保存配置时写入 DSH 托管存储，检查连接时只临时使用。已保存密钥只返回可用状态，留空保留原值。旧环境变量引用继续兼容，托管值优先。宿主缺少凭据托管服务时，插件设置无法保存新密钥，仍可临时检查连接或沿用已有引用；其他方式见下节。
+
+### 凭据托管不可用时的高级配置
+
+常规使用时，在插件设置中输入密钥并由 DSH 托管。缺少托管服务或需要通过环境变量提供凭据时，可选择固定引用名，例如 `ACN_TEAM_TOKEN`，在启动 DSH 的进程环境中将它设置为团队管理员提供的密钥，并在该 upstream 的 YAML 中配置相同引用：
+
+```yaml
+upstreams:
+  coding:
+    agentId: coding
+    routerEndpoint: https://router.example.org
+    maintainerEndpoint: https://maintainer.example.org
+    keyEnv: ACN_TEAM_TOKEN
+```
+
+密钥正文不写入 YAML。完全退出应用后，从包含该变量的环境启动 DSH；另开终端设置变量不会改变已运行的桌面进程。此方式用于环境变量兼容场景；通过插件设置保存密钥时无需操作环境变量。
+
+### 组件开关
+
+各插件可以按行 id 单独禁用，例如：
+
+```yaml
+- id: acn-tools
+  disabled: true
+```
+
+可分别禁用 `acn-tools`、`acn-prompt`、`acn-formation`、`acn-inbox`、`acn-dream` 和 `acn-commands`。禁用 formation 会撤销 `/recap` 和 `/acn-finalize`，Inbox 仍可运行；禁用 inbox 会撤销 `/inbox`，已有消息和任务保留；禁用 dream 会撤销 `/dream`，中止调用并保留进度，prepared 组先到达安全点。上传投递属于知识服务，禁用 Inbox 或 Dream 不会停止已形成知识的投递。`/acn-status retry` 共用知识服务的 worker。禁用知识行时，其依赖贡献全部撤销。客户端仍在时不阻止普通聊天，并提供插件管理入口；恢复后会自动重读状态，已固定的身份仍不能中途更换。
+
+## 会话压缩与知识复盘
+
+**会话压缩由 DSH 负责**：对话变长时，将较早的聊天内容归纳为摘要，减少模型需要读取的上下文，让当前会话继续工作。压缩策略由 DSH 的会话模式管理；兼容基线的标准模式已经提供压缩功能和 `/compact` 命令，日常使用 ACN 无需额外添加压缩组件。需要调整压缩策略时，参考 [DSH 压缩说明](https://github.com/deepseek-ai/deepseek-harness/blob/687f282e8625c6b8d11ff58211a90524be2e4317/packages/compaction/compaction-basic/README.zh.md)。
+
+**知识复盘由 ACN 负责**：从工作对话中提炼值得复用的结论，保存为知识，供后续任务查阅。默认在 DSH 成功产生压缩结果后，ACN 会对尚未处理的对应历史安排复盘；如果本次没有实际压缩，就不会通过这条路径触发复盘。
+
+空闲自动复盘、手动 `/recap` 和 `/acn-finalize` 都可以独立运行，不要求先执行 `/compact`。完整触发条件见[知识形成与失败重试](command-reference.md#知识形成与失败重试)。
+
+所有正整数配置必须是安全整数；`team.retryCount` 与 `formation.finalizeIdleMinutes` 可为 0。证据预算和 review 输入另有表中上限，未知字段拒绝；最大退避不得小于起始退避。模型供应端的凭据由宿主管理，插件不新增密钥配置。
+
+`dream.maxModelSteps` 是探索额度，`dream.maxWrapUpSteps` 是额外收尾额度；默认总计最多 27 次对话模型请求。工具反馈、格式修复及请求重试均计次，先持久记账再发送，崩溃和抢占不返还。收尾禁止扩展探索，保留已提交结果并记录未完成项，然后结束本次。下次 `/dream` 创建新的当前 Claim 快照，不恢复旧草稿。`evidenceMaxSteps` 仅供旧受限查证适配器兼容。
+
+### 工作配置的启用和停用
+
+在「工作配置」列表打开所需配置，在编辑页调整「启用此配置」并保存。停用保留数据与配置标识；启用不会恢复旧字段，当前草稿中的 Agent ID 和团队地址随保存一起生效，也不自动设为全局默认。若要让身份不匹配的旧会话继续，应把 Agent ID 改回该会话原来的值并保存。

package/docs/development.md

@@ -0,0 +1,197 @@
+# 开发指南
+
+本文面向插件维护者。安装配置见[使用指南](user_guide.md)，模块职责见[架构](architecture.md)。
+
+## 构建与自动化检查
+
+使用 Node `^22.19.0 || >=24.0.0` 和 pnpm `11.25.0`。以下命令应串行执行：测试、契约脚本、打包和安装检查都会使用或重建同一个 `lib/`。
+
+```sh
+pnpm install --frozen-lockfile
+pnpm typecheck
+pnpm lint
+pnpm check:security
+pnpm check:docs
+pnpm test --maxWorkers=4
+ACN_REPO=/path/to/reference pnpm test:compat
+ACN_REPO=/path/to/reference pnpm test:contract
+pnpm build
+pnpm pack --pack-destination .artifacts
+pnpm smoke:install
+```
+
+`ACN_REPO` 指向参考 ACN 源码仓库，版本与提交基线见[ACN 兼容边界](acn-compat.md)。`test:compat` / `test:contract` 需要 Bash 与 Rust 工具链，在 macOS 执行；脚本会按需读取参考仓库的 `export_env.sh`。普通单元与集成测试使用临时目录和本地测试模型，不依赖真实模型服务。
+
+| 检查入口 | 验证范围 |
+| --- | --- |
+| `pnpm test` | 工具与宿主接入、存储、权限、并发、进程崩溃和恢复 |
+| `pnpm test:compat` | 已提交的协议 fixture，以及 TypeScript 写出的 YAML 能否被 Rust 读回 |
+| `pnpm test:contract` | 在临时目录启动真实 Router / Maintainer，验证查询、上传、裁决通知的双成员内化和整合依赖；内化模型使用本地测试适配器 |
+| `pnpm smoke:install` | 新 DSH profile 中的实际包安装、Loader 生命周期、公开资源和不兼容引擎拒绝 |
+| `pnpm check:security` | 版本控制文本中的凭据、邮箱和个人路径，以及提交元数据中的其他敏感内容；允许用户确认的 Git 身份邮箱 |
+| `pnpm check:docs` | 文档相对链接与标题锚点 |
+
+安装包包含运行 JS、类型声明、提示词、组合 patch、双语说明、本地化资源、图标、使用截图和许可证；不包含源码测试、依赖缓存、临时项目或运行日志。安装检查使用独立的 `DSH_HOME`，不会修改日常 profile。`smoke:install` 由 Node 脚本执行，可从 Windows PowerShell 或 POSIX 终端运行；Windows 的 pnpm / dsh 命令 shim 通过统一启动器调用，不要求安装 Bash。它需要可用的 `tar` 和 DSH CLI；`DSH_BIN` 也可指向桌面附带 CLI 的 `.js` 入口。
+
+日常安全扫描覆盖当前文件和 Git 提交身份，不扫描全部历史文件正文，也不识别截图文字。公开完整 Git 历史前，应另行检查历史文件和图片。更新图片时应检查可见内容，使用中性示例，避免展示实际数据路径、提供商别名、邮箱或凭据。
+
+### 维护使用说明书
+
+`docs/user_guide.md` 是面向用户的完整 Markdown 指南，截图保存在 `docs/assets/`。更新界面或操作流程时，同时更新指南与截图，并运行 `pnpm check:docs`。截图应使用隔离的示例身份和数据，不包含账号、真实目录、团队内网地址或凭据；必要时遮挡后逐张检查。
+
+### 发布到 npm
+
+发布包为 `@ftai/dsh-plugin-acn`，使用有该作用域发布权限的账号。先完成上述检查和桌面验收，确认版本号，再生成并检查同一份安装包：
+
+```sh
+pnpm pack --pack-destination .artifacts/release
+npm publish .artifacts/release/ftai-dsh-plugin-acn-0.1.1.tgz --dry-run --access public --registry=https://registry.npmjs.org/
+```
+
+检查包内包含构建后的 `lib/`、提示词和文档，不含凭据、个人信息或测试日志；使用该包完成隔离安装。`--dry-run` 不上传内容，也不验证账号发布权限。准备完成后登录并发布已检查的包：
+
+```sh
+npm login --registry=https://registry.npmjs.org/
+npm whoami --registry=https://registry.npmjs.org/
+npm publish .artifacts/release/ftai-dsh-plugin-acn-0.1.1.tgz --access public --registry=https://registry.npmjs.org/
+```
+
+发布前同步检查中英文 README 和使用指南，使用同一份安装包完成 Mac、Windows 验收，再提交版本变更并建立版本 tag。确认源码提交和 tag 的 CI 均通过后，创建对应的 GitHub Release 并上传已验收的安装包。随后执行 npm 发布，按提示完成账号认证；发布成功后，在两个平台的全新 DSH profile 按 `@ftai/dsh-plugin-acn@0.1.1` 从 npm 安装复验，并确认不带版本号时也会安装新版。后续版本替换命令中的版本号；已发布的同名同版本不能覆盖。仓库、主页及问题反馈地址指向本插件仓库，团队服务部署链接继续指向 ACN 官方仓库。
+
+GitHub Release 使用与 npm 一致的版本号，例如 tag `v0.1.1`，指向该包对应的源码提交。正文简要列出主要功能或修复、兼容的 DSH 版本和平台、安装包名、升级步骤及需要用户注意的变化，并链接使用指南与 npm 包页面。建议附件上传与 npm 发布时完全相同的 `.tgz`，供需要安装包的用户下载；不另行构建 Mac、Windows 两份包。GitHub 自动生成的源码归档不含构建后的 `lib/`，不能替代该安装包。
+
+## 隔离插件界面调试
+
+以下脚本通过 DSH 的 `web` 模板，在本机浏览器中加载插件界面，用于隔离调试与验收。日常使用请在 DSH 桌面应用中安装插件，无需启动这套调试环境。
+
+选择本机 `web` profile 已配置的模型提供商，并将 `your-provider` 替换成它的 ID：
+
+```sh
+export ACN_ACCEPTANCE_PROVIDER=your-provider
+pnpm smoke:web
+```
+
+脚本默认使用 `deepseek-v4-flash-api`；可通过 `ACN_ACCEPTANCE_MODEL_ID` 选择该提供商下其他已配置模型。凭据只传给子进程，模型请求会访问所选提供商。脚本创建临时工作区、知识目录和 DSH profile，并输出可在浏览器打开的本地调试地址；日常配置不变。停止脚本会结束其创建的服务。macOS 调试期间向该脚本进程发送 `SIGUSR1` 可只重启它创建的 DSH，保留测试服务与数据；新调试地址会再次输出。Windows 不支持此信号，需停止脚本后使用相同 `ACN_WEB_HOME` 重新启动。
+
+从空白环境验证插件安装与设置时使用：
+
+```sh
+ACN_WEB_INSTALL=browser pnpm smoke:web
+```
+
+此模式不预装 ACN、不预填其配置，也不生成 seed Claim。按[使用指南](user_guide.md)安装输出的 tarball，填写配置并保存。以相同 `ACN_WEB_HOME` 重启，可检查保存与恢复；已有 profile 不会再次初始化。
+
+不调用真实模型的流程调试可使用 `ACN_WEB_MODEL=local pnpm smoke:web`。这是预设响应的本地测试模型，不适合评价知识质量。
+
+验收应核对以下行为和实际产物：
+
+- 安装、启用、保存、重读草稿与重启后，身份、目录和模型配置符合预期。
+- 多个具名连接可检查、离线保存、停用和恢复；新会话按默认工作配置预选、首发前可改选并等待内化，首发后归属固定。
+- 首次同步失败允许使用所选身份的本地知识；未绑定历史仍可普通聊天。取消、热重载、冷历史读取和派生会话不改变归属。
+- 知识浏览不触发同步/模型；活动可查看来源、失败和重试。结果只在可见且有焦点的来源会话展示，重启不重复弹旧结果。
+- 完成一项小任务并 `/recap` 或 `/acn-finalize` 后，能从新会话检索 Claim、读取 Trace，并保留适用范围与未验证条件。
+- 模型输出不合法、服务不可达或进程中断时，任务状态可解释，恢复后没有重复提交或丢失输入。
+
+### Recap 触发与恢复验收
+
+在隔离 profile 中选择真实模型，以实际开发、测试和新会话复用检查形成效果。单人和团队模式均应覆盖下列行为，使用不同会话测试各类计时，避免一项测试的输入改变另一项的空闲时间。
+
+| 场景 | 检查重点 |
+| --- | --- |
+| 手动 `/recap` | 空会话不建任务；少量新增内容能处理；成功后重复执行不再次处理同一区间 |
+| 前台仍在运行 | 自动触发等待前台结束；手动 Recap 只处理此前已完成的范围，不消费正在生成的内容 |
+| 批量空闲 | 默认 9 轮且不足 token 门槛时，空闲 5 分钟不触发；第 10 轮后仍需空闲 5 分钟；token 门槛可独立触发 |
+| 尾部空闲 | 不足批量门槛的增量在默认 1 小时前不触发，到期进入队列；后续扫描不重复消费 |
+| 归档与暂停 | 普通归档保留宿主的忙碌拒绝规则；停止并归档冻结收尾范围，迟到结果不扩大范围 |
+| 恢复与续聊 | 重启保留空闲起点及归档暂停；撤销归档、查看状态不解除暂停；实际用户续聊后恢复 |
+| 压缩与故障 | 成功压缩处理对应区间；模型故障、任务中断和重启后保留输入，不重复提交知识 |
+
+默认时长验收应实际等待；缩短 `formation.recapBatchIdleMinutes`、`formation.recapTailIdleMinutes` 或 `formation.recapScanSeconds` 可用于故障调试，但不能据此声称默认时长已验证。精确阈值、内部通知、失败或取消轮次、归档中断和并发边界由 `tests/formation/` 与 `tests/flow/recap-lifecycle.test.ts` 回归覆盖。
+
+核对任务的触发原因、创建时间、状态和处理范围，并检查实际 Claim、Trace 及团队待上传项。一次模型调用可能更新已有知识或没有产出；任务成功本身不证明知识内容正确。验收日志、临时项目和按次记录保留在仓库外。
+
+## 本地团队调试
+
+首次配置验收应分别保留安装前的历史与空白会话，以及安装后新建的空白会话。前两类可以继续聊天，但不能绑定团队或访问 ACN 数据；只有最后一类能在首发前选择配置，回复后 `/recap` 可形成知识。安装后未选择配置就开始聊天的会话，也不能中途入队；热重载或重启不能绕过限制。已有绑定及派生历史不能换身份。配置停用与恢复应保留同一标识、知识及会话归属。
+
+旧格式配置升级还应覆盖已经聊过且仍打开的单人、团队会话：只修改名称并保存或调整全局默认后，原会话均应按有效绑定继续访问原 Claim 和冻结知识目录；冷恢复结果一致。损坏、冲突及身份不匹配的绑定不能被迁移为有效选择。
+
+在「团队鉴权密钥」输入随机测试 key，确认默认掩码、眼睛按钮显隐、空值保留及取消草稿；连接检查不写入托管存储，保存配置才保存密钥。确认自动引用只进入插件 YAML、密钥只进入宿主托管存储，新启动会话采用新引用，驻留实例保留原连接，释放后重新加载实例使用同 upstream 当前连接；同时检查带路径前缀的服务地址。展开本地和缺失的来源 Claim，确认返回时保留原详情与筛选，浏览不触发网络和模型。
+
+同时启动参考服务和用于验证插件安装、团队配置的隔离 DSH 实例：
+
+```sh
+ACN_REPO=/path/to/reference \
+ACN_CONTRACT_WEB_HOME=/path/to/isolated-web-check \
+pnpm test:contract
+```
+
+该命令先构建 Router / Maintainer，再为 `agent-a`、`agent-b` 生成临时凭据，启动两项服务和用于浏览器调试的 DSH 实例。脚本预配置 `ACN_TEST_TEAM_CREDENTIAL` 与 `ACN_TEST_OTHER_CREDENTIAL` 的兼容引用；页面无需填写引用名。正常新建工作配置时直接输入成员 key，地址使用脚本实际输出的回环 endpoint。停止脚本会结束这些服务并清理临时团队数据。
+
+此模式默认不启用 Router 模型检索或 Maintainer 自动仲裁，只验证通信。需要评价模型仲裁时，应另行在服务端配置 Maintainer 模型并启用仲裁；推荐保持 Router 为词法检索，避免[已知重排限制](outstanding-issues.md#团队仲裁与信息边界)。插件中的模型选项不会替团队服务配置模型。
+
+接入已经启动的测试服务时，为 `pnpm smoke:web` 同时提供 `ACN_WEB_TEAM_ROUTER`、`ACN_WEB_TEAM_MAINTAINER`，并用 `ACN_WEB_TEAM_KEY_ENV` 指定认证环境变量名。默认变量名为 `ACN_WEB_TEAM_CREDENTIAL`。少配一个 endpoint 会启动失败；凭据不写入配置文件。
+
+可在同一隔离 profile 的「ACN 插件设置 → 工作配置」页添加两份配置，分别使用不同成员 ID 与团队鉴权密钥；也可为多个进程分别设置独立的 `ACN_WEB_HOME`、不同的 `ACN_WEB_AGENT_ID` 和对应凭据。可用 `ACN_WEB_SEED_CLAIM=false` 从空知识开始，避免多个成员生成同一个 seed ID。`ACN_WEB_TEAM_TIMEOUT_MS` 控制团队请求超时，默认 15000 毫秒。
+
+团队检查应覆盖 A 形成并上传知识、B 检索和复用、冲突上报、Maintainer 给出建议、各成员 Inbox 内化、修订回传，以及 Dream 整理后的依赖交付。仲裁完成、建议送达和本地内化是不同阶段，应分别确认；服务断开后的补送也应检查。
+
+### 自动仲裁与通知边界
+
+真实模型专项测试应使用隔离团队数据，固定 Router 为词法检索，在 Maintainer 另行启用自动仲裁与模型。使用有明确来源、版本和限制的合成材料时，须标为测试输入，不能混作业务实证。
+
+| 场景 | 应核对的结果 |
+| --- | --- |
+| 有证据的冲突 | 提案与独立复核通过后才采纳；保留版本、请求方法、次数和预算边界 |
+| 等强度、未核实的相反证据 | 可以保持未解决，不把某一方自动视为正确；不生成假完成通知 |
+| 分析期间修订输入 | 旧输入不能采纳；重分析使用当前版本，并记录轮次与输入变化 |
+| 两名持有者与旁观成员 | 通知只送直接涉争持有者；旁观成员通过 Router 发现修订，而非等待广播 |
+| 持久收件、ACK、内化与回传 | 分别确认各阶段；ACK 后本地仍可能尚未变化，内化也可能决定不修改 |
+| 非法 JSON 或外部持有者修改 | 严格校验拒绝，不执行无效变更；失败通知保留，修正后重试只应用一次 |
+| 重复拉取、进程中断、并发提交 | 不重复生成 Trace 或覆盖更新版本；按现有日志与恢复边界完成或重新分析 |
+
+`tests/inbox/` 覆盖模型失败、重试、并发和崩溃恢复；`tests/contract/team.test.ts` 的裁决契约经真实服务送达两个成员，内化前后分别核对本地状态、回传与再次同步。契约中的管理员操作仅用于构造裁决，不能替代真实模型自动仲裁验收。最终应在 DSH 界面操作同步与查询，并保存任务、服务裁决和实际知识内容的证据，不能仅凭成功提示判断完成。
+
+## Dream 恢复调试
+
+设置 `ACN_WEB_EVIDENCE_CALIBRATION=true` 可在隔离宿主启用文件查证，默认关闭。先运行 `pnpm build`，再执行 `node scripts/seed-dream-preservation.mjs legacy` 或 `fresh`，可创建带版本限制的合成材料。
+
+以输出的根目录作为 `ACN_WEB_HOME` 启动 `pnpm smoke:web`。随后运行 `/dream`，通过 `/acn-status` 和 `/claim show <id>` 核对恢复结果、证据摘要与来源承接。脚本不导入日常知识。
+
+## 提示词维护
+
+内容选择和知识使用纪律以原 ACN 的同名模板、`agent_system.j2` 中的知识段落为基准，保留其原文和示例，不以缩短提示词为由删减或弱化规则。适配范围限于插件实际提供的工具参数、结构化输出格式、会话投影、私有数据边界及 Dream 额度和收尾通知。
+
+正常插件使用当前自主 Dream 提示词；旧固定阶段模板只用于兼容适配器及其测试，不注入当前自主流程。
+
+修改后核对知识提炼的私有内容过滤规则、单人模式不出现团队调用指令，并使用参考模板引擎重新导出受影响的快照；同时运行宿主集成与真实模型验收，检查输出接口和知识选择结果。
+
+## CI 配置
+
+工作流使用 GitHub Actions，定义在 `.github/workflows/ci.yml`；仅推送到其他 Git 托管平台不会执行这个工作流。主检查矩阵为 Apple silicon macOS / Windows × Node 22 / 24，覆盖类型、lint、安全、文档、全量测试、构建、打包和真实安装。测试使用两个文件进程，减少共享 runner 的磁盘争用；保留跨进程并发和强制终止恢复测试。
+
+Windows job 只在临时 runner 开启开发者模式，以执行真实符号链接 fixture；不跳过链接保护测试，也不修改用户电脑设置。本机 Windows 运行这些测试需要开发者模式或创建符号链接的权限；普通插件使用不要求创建链接。新增 `tests/platform/` 覆盖反斜杠主目录、盘符 / UNC、原生导入、保留名称和领域目录访问保护。现有 macOS 权限断言继续保留，Windows 改为检查可读写，不把 mode 位当作 ACL 验收。
+
+基线安装检查使用 DSH rc.2，独立的 Windows 安装 job 另检查 rc.5；不重复运行主矩阵已覆盖的测试集。团队契约在 macOS 运行，验证插件与参考服务的通信；团队服务的部署范围由原 ACN 项目说明。Windows 本地可在 PowerShell 串行执行以下检查（先安装所需版本的 Node、pnpm、DSH CLI 和 tar）：
+
+```powershell
+pnpm install --frozen-lockfile
+pnpm typecheck
+pnpm lint
+pnpm check:security
+pnpm check:docs
+pnpm test --maxWorkers=4
+pnpm build
+pnpm pack --pack-destination .artifacts
+pnpm smoke:install
+```
+
+提交前的本机验证不触发远端 CI，Windows runner 的结果应在工作流实际运行后确认。团队契约 job 需要仓库变量 `ACN_REFERENCE_REPOSITORY`，其值为 `FTShare-Lab/agent-claim-network`（不带 URL 协议或 `.git` 后缀）；私有跨仓库访问另用 `ACN_REFERENCE_TOKEN` secret。缺少参考仓库变量会明确失败，不会跳过契约检查。
+
+参考提交与 fixture 应一起维护。升级 ACN 或 DSH 后，先核对协议、事件、工具门禁、模型取消和卸载边界，再运行上述检查。测试是否通过以本次命令退出码及 CI 结果为准，不把旧报告的通过数量当作当前结论。
+
+## 项目会话预选验证
+
+项目预选只使用公开的 `sessionPersistence.list/open` 和 `sessions.list`；无需替换宿主 UI 包、安装额外 bundle 或执行安装后脚本。只读历史不会创建 Agent 或触发模型、团队同步。
+
+检查同一项目的新会话是否沿用最近新建普通会话的 upstream，以及另一个项目是否使用自己的记录或全局默认。重启后应从持久会话日志恢复；打开旧会话、继续旧任务和后台子代理不能改变创建顺序。还需覆盖草稿改选、无全局默认、并发新建、目录别名、配置停用/删除/身份变化及历史读取失败。已有会话继续保持原绑定。

package/docs/dsh-compat.md

@@ -0,0 +1,59 @@
+# DSH 兼容边界
+
+兼容基线为 DSH `0.2.1-rc.2`，对应源码提交 `687f282e8625c6b8d11ff58211a90524be2e4317`。声明 `engines.dsh: >=0.2.1-rc.2 <0.3.0` 不代表逐版本实测。Node 支持 `^22.19.0 || >=24.0.0`，CI 配置使用 Node 22 / 24。
+
+身份持久化使用宿主公开的 `appendPluginRecord` / `pluginRecordOf`，不修改会话日志格式。
+
+## 平台
+
+本插件支持 Apple silicon Mac（macOS 13 或更高）和 Windows，与 DSH 桌面版保持一致。两个平台使用同一插件安装包，包含 JavaScript 与静态资源，不含平台专用二进制。独立 CLI 需满足上述 Node 版本要求，桌面应用使用自身运行时。
+
+私有文件读取会检查符号链接、硬链接以及路径与打开文件的身份；在 Windows 缺少 `O_NOFOLLOW` 等 POSIX 标志时仍执行这些检查。普通文件工具仅拒绝指向私有数据的硬链接，公开项目的硬链接不阻断搜索。安装验收使用 Node 脚本和系统临时目录；Windows 主 CI 配置覆盖 Node 22 / 24 的全量测试与基线 CLI 安装，另保留 rc.5 CLI 安装检查。
+
+Windows 导入命令保留原生路径的反斜杠，支持盘符、UNC、含空格的引号路径与 `~\` 主目录前缀。Agent ID、配置标识等本地目录名会拒绝 `con`、`nul`、`com1` 等 Windows 设备保留名称；其他平台已有合法名称继续兼容。
+
+安装由宿主读取 tarball 的 `dsh.bundle.patch`，八行组合（插件配置入口和七个领域组件）按隔离服务依赖装配。只有 `plugins/` 与 `dsh-adapter/` 导入宿主运行时；协议与核心模块可独立使用。按 id 覆盖整体替换 config，插件再补字段默认值。
+
+| 公开接口 | 用途与约束 |
+| --- | --- |
+| `agent/created` serial、SessionHeader | 冻结知识目录，身份和子代理权限来自宿主 |
+| systemPrompt sections | 同步读已准备缓存；数据不做模板插值 |
+| `agent/pre-step`、`agent/request`、`session/event` | 请求准入后的知识变化、路由与公开投影 |
+| tools DSL、renderer、最终 guard | 原生 / 程序桥工具结果、权限与路径门禁 |
+| `llm.prepareCall`、stream、BlockAssembler | 宿主模型路由、结构化后台调用及取消 |
+| `agents.create` setup / dispose | 隔离只读证据子会话、专属系统上下文与预算 |
+| `dsh.client`、`plugins.bundle.config`、`settings.section`、ModuleLoader | 配置入口与 ACN 插件设置，宿主共享 React |
+| `conversation.input.left`、conversation blocks、`uiWorkspace.openSession` | 会话团队选择、首次准备反馈、知识活动与返回来源 |
+| `sessionPersistence.list/open`、`sessions.list` | 同项目按创建时间选择最近普通会话的 upstream，只读历史，不恢复 Agent |
+| `sessionController.inspect` / `resolveAgent` | 只读历史与显式恢复分离，不因浏览启动同步 |
+| `uiWorkspace.pickDirectory`、`sessionController.openWorkspacePath` | 目录选择与系统文件管理器由桌面宿主提供，选择只更新草稿；打开前展开主目录并检查目录存在 |
+| Typert Remote / Gateway、`configEditor.edit` | 宿主认证、严格入参、profile 文件锁、原子写和普通字段重载 |
+| `workspaceRegistry.archiveSession`、`archivedSessionIds` | 归档前冻结范围，归档后暂停；包裹公开方法，卸载时恢复。宿主升级需重验普通及停止归档 |
+| `credentials.resolve/describe/set` | 每次团队请求解析引用，设置页只回传可用状态；密码独立写入宿主托管存储 |
+| `commands.register` | 命令不进入普通模型历史，贡献随依赖卸载撤销 |
+| fs 路径解析、写 / 编辑意图 | 已知文件工具的私有路径保护；没有通用读取前 hook |
+
+知识、任务及恢复状态保存在插件自身目录；身份绑定通过宿主公开插件记录接口写入会话日志，不自行改写宿主日志格式。Recap 监听宿主实际成功压缩的结果，不改变 DSH 的压缩策略。兼容基线的[标准模式](https://github.com/deepseek-ai/deepseek-harness/blob/687f282e8625c6b8d11ff58211a90524be2e4317/packages/bundle/web-app/presets/standard.patch.yml)已提供 `compaction-basic` 和 `command-compact`；顶层同名行因能力由会话模式管理而停用，不能据此判断客户端关闭了压缩。两项功能的关系见[会话压缩与知识复盘](config.md#会话压缩与知识复盘)。DSH 当前工作区可能与启动目录不同，需在客户端选择实际项目；验收脚本显式配置临时默认工作区。
+
+原生工具、程序桥、Loader 单行禁用、安装、恢复会话、证据子会话和 知识目录保护都有自动化测试。宿主升级后应重新检查工具门禁、事件、压缩、模型取消和卸载边界，再按[开发指南](development.md)验证。
+
+模型适配器可能只转发工具 Schema 的顶层 `properties` 和 `required`。Claim、Router 查询和 Dream 只读 Claim 因此同时提供顶层参数字段与完整的动作联合约束，避免模型收到空参数说明。执行时仍按具体动作严格校验；展示全部动作的字段不代表可以混用字段，也不放宽 revision、所有权或只读限制。
+
+## 操作系统
+
+两个受支持桌面平台的实际验收范围如下。
+
+| 平台 | 当前覆盖与验证边界 |
+| --- | --- |
+| Apple silicon Mac（macOS 13 或更高） | 本机全量测试、真实安装与插件界面回归；继续保留 POSIX 文件打开标志和权限检查 |
+| Windows | 已在 Windows 11、DSH `0.2.1-rc.5` 实机验证预构建包安装、配置与默认切换、原生目录选择和打开、中文及空格路径、知识浏览与来源跳转、宽窄窗口、Recap 和 Dream 重试；实际团队服务的连接检查与收件同步通过，模型流程使用本地模拟服务 |
+
+macOS 和 Windows 本机自动化均已通过，包含符号链接路径保护测试。Windows 上运行这类测试需允许测试账户创建符号链接，普通用户安装和使用插件无需此权限。路径单测中的 UNC 支持仅验证解析，不代表已验证 SMB 共享存储的锁、原子发布或断电恢复。
+
+知识目录建议位于当前用户独占的本地磁盘；普通文件工具不能绕过领域接口访问 ACN 数据。Windows 目录应具有正确的 ACL；保护范围见[已知限制](outstanding-issues.md#领域文件访问)。
+
+## 安装包与界面资源
+
+预构建包包含双语 locale、图标、README 和图文指南。`meta.detail` 指向包内的中英文 README；安装检查会确认正文和相对图片完整。长文详情的显示取决于宿主支持，兼容基线尚未验证该界面的渲染；插件设置界面与 README 介绍区是不同入口。
+
+插件已发布到 npm，在 DSH「添加插件」中填写 `@ftai/dsh-plugin-acn` 即可安装，也可使用 GitHub Release 中的预构建 `.tgz`。源码仓库不跟踪 `lib/`，也未配置 Git 安装用的 `prepare`。从 Git 获取源码后应先构建打包，不能把仓库地址直接当作已支持的安装入口。

package/docs/index.md

@@ -0,0 +1,16 @@
+# 文档导航
+
+文档说明插件当前的使用方式、实现边界和开发方法。仓库概览见 [README](../README.md)；版本变化见[更新记录](../CHANGELOG.md)。
+
+| 需要了解 | 文档 |
+| --- | --- |
+| 插件安装、配置与日常使用 | [使用指南](user_guide.md) |
+| 配置字段、默认值，以及压缩与复盘的关系 | [配置说明](config.md) |
+| 工具参数、命令、任务恢复与导入 | [命令与行为参考](command-reference.md) |
+| 模块职责、数据所有权与恢复协议 | [架构](architecture.md) |
+| 宿主接口、版本要求与安装包边界 | [DSH 兼容边界](dsh-compat.md) |
+| 共享协议、团队服务与迁移边界 | [ACN 兼容边界](acn-compat.md) |
+| 构建、自动化测试、安装检查与本地调试 | [开发指南](development.md) |
+| 使用限制与尚未覆盖的能力 | [已知限制](outstanding-issues.md) |
+
+首次使用请按[使用指南](user_guide.md)完成配置、一次复盘和知识复用。查询完整自动复盘条件、归档暂停或失败重试规则，见[知识形成与失败重试](command-reference.md#知识形成与失败重试)；调整参数见[配置参考](config.md)。

package/docs/outstanding-issues.md

@@ -0,0 +1,61 @@
+# 已知限制
+
+本文记录当前的使用边界和未完成验证的场景。日常操作见[使用指南](user_guide.md)，完整参数见[配置参考](config.md)。
+
+## 配置与会话
+
+插件设置和会话控件依赖 DSH 的配置、模型、会话及工作区服务；仅加载核心组件的最小 CLI 环境不提供这些界面。宿主缺少凭据托管服务时，插件设置无法保存新密钥，仍可临时检查连接或沿用已有引用；替代方式见[高级配置](config.md#凭据托管不可用时的高级配置)。
+
+「检查连接」反映本次检查结果，保存配置也不保证服务持续可达。后续连接故障可通过 `/acn-status` 和失败任务查看。
+
+会话开始后固定工作配置、Agent ID 和知识目录，已有历史及无法验证父身份的派生会话不能改绑。更换身份或知识目录后需要新建会话；原数据保留，但不会自动搬移。运行中的实例沿用启动时的连接，新启动或冷恢复实例采用原 upstream 当前保存的团队地址与凭据。更换地址会保留待投队列，符合条件的旧记录可能发往新服务；连接不同团队应新建工作配置。
+
+新会话的项目配置预选依赖可读取的 DSH 会话记录。最近会话的归属无法确认或配置已失效时，回退全局默认；已有会话的绑定失效时，需要恢复原配置。宿主接口与支持平台见 [DSH 兼容边界](dsh-compat.md)。
+
+## 团队仲裁与信息边界
+
+当前建议 Router 使用词法检索，不启用 LLM 重排。ACN Maintainer 采纳前会重新检索并检查输入指纹；Router 缓存刷新、新上传或成员修订引起候选及争议变化时，即使关闭模型重排，也可能进入重分析退避，这是服务的并发保护。模型重排还可能使相同查询重复产生变化，连续变化时停止自动采纳、等待人工处理。这是参考服务之间的联动限制，插件不修改服务端仲裁逻辑。Embedding 检索尚未纳入当前兼容验证范围。
+
+`consult_router` 返回可引用的候选 Claim、关联争议和已解决争议 ID，但不提供完整 Resolution、仲裁内部阶段或 `retrieval_debug`。需要裁决全文或检索降级原因时，应查看对应服务的管理接口和诊断记录。
+
+Maintainer 的属性更新是建议，成员内化后才决定如何修改本地知识，不保证所有成员立即得到相同正文。单人期间修改过的待上传版本会暂停；切回团队后不会自动发布这些变化，需核对当前版本或执行受复核的整合重绑。
+
+自动仲裁的属性更新发送给直接涉争 Claim 的持有者，并非向所有成员广播。其他成员通过 Router 检索最新 Claim 与已解决争议；已有会话的冻结目录不会因此整体重建。
+
+## 知识质量
+
+Claim 可引用、结构合法、能够恢复，不等于结论完整或正确。形成、共享与复用仍可能扩大适用范围、遗漏版本条件，或把临时要求泛化为长期规则。待业务方确认的决策应保留为未决事项，不能仅凭可复现的代码现象写成强制要求。
+
+知识复用依赖 Agent 主动检索和判断。本项目没有提供系统性的自动召回率、事实正确率或节省工时指标。测试与模型自评不能取代对当前代码、证据和业务约定的核对。
+
+## Dream 整理与查证
+
+Dream 使用有界候选上下文，按更新时间装入知识，并在报告中标明遗漏数量；不保证多次运行一定遍历到全部旧知识。模型可能输出不合法的草稿或复核参数；工具会返回错误供其在当前会话内修复，修复也消耗模型轮数。探索额度耗尽后进行有限收尾并结束；收尾仍未完成的事项明确记为未完成，下次触发从当前 Claim 重新开始。
+
+宿主明确报告工具参数 JSON 语法错误时，通过宿主上下文在重试前回喂解析错误和未执行说明，每次子会话最多额外自动重试两次，每次仍消耗原有额度；耗尽后保留进度并显示具体错误分类。此恢复仅覆盖明确的工具输入解析错误，其他响应、网络和鉴权错误沿用宿主处理，不自动修补 JSON 或切换模型。
+
+后台模型默认输出上限为 32768 token，显式配置仍优先。新 Dream 使用原版的简洁逐 Claim 语义复核，不再生成双向全文引用；复杂知识仍可能耗尽上下文或轮数预算。预算上限控制成本，不保证模型判断正确。
+
+整合通过逐 Claim 语义复核说明信息去向，并独立校验来源与承接关系；不要求逐字复制原证据摘要，也不能证明事实相关性或语义等价。已进入 prepared 阶段的固定提交按原恢复协议完成，不追溯重写已经生效的结果。
+
+文件证据校准默认关闭，只提供受限的 `file_read`、`file_grep`、`file_glob` 和只读知识查询，不提供联网检索或命令执行。只有带版本的实际文件读取可以授权事实修改；原始 high Claim 不进入校准。材料本身仍可能错误、恶意或与断言无关。
+
+搜索和读取共用查证预算。宽泛搜索可能在读取目标文件前耗尽文件数或字节数；只有定位结果、没有实际读取回执时，Dream 会保留原判断和置信度，不能视为校准成功。应检查逐组报告，并优先提供明确的项目路径和证据范围。
+
+凭据保护按常见文件名和目录名拦截，不扫描任意文件正文中的秘密，也不构成操作系统沙箱。完整规则见[Dream 证据校准](command-reference.md#dream-证据校准)。
+
+## 领域文件访问
+
+知识目录建议放在当前用户独占的本地磁盘。普通文件工具的路径保护不替代操作系统权限；Windows 应使用权限正确的本地目录。UNC、云同步盘及特殊 reparse point 的存储语义尚未完成实机验证。
+
+## 会话投影与恢复边界
+
+复盘的跨进程修复依赖原 DSH 会话日志仍可读取且归属一致；它无法恢复宿主本身从未保存的事件，也不自动修复正文冲突或跳过超限输入。单条投影限制为 50MiB，多个较小未处理事件可以分片保存。界面中的“未调用知识模型”指本次输入准备失败发生在模型请求前，不代表该任务之前从未尝试过模型调用。
+
+文件占用和原子替换故障已有注入测试；Windows 仅对短暂占用导致的 rename 失败进行有限重试，持续无权限仍明确报错。macOS 和 Windows 桌面均已进行安装与交互验收，模型及文件系统的验证边界见[兼容说明](dsh-compat.md#操作系统)。
+
+## 时间与运行状态兼容
+
+UTC 规范年份只接受 0–9999。参考 ACN `0.3.3` 能将部分 offset 时间格式化为四位年份之外的值，但无法再按自身 RFC 3339 规则读回；插件拒绝这类输入，以免写出不可回读的数据。
+
+Dream、形成、Inbox effect、会话状态和权限清单属于插件运行时格式。Rust 的 pending checkpoint 或 safety review 缺少插件授权清单，不能直接接管；DTO 读回兼容不意味着运行日志可互换。不要与原生 ACN 共用活动数据目录，迁移时使用[只读导入](command-reference.md#从已有-acn-目录导入)。