# 安全与限制

[English](SECURITY-AND-LIMITS.md) · **简体中文**

在安装到 Host、认证 provider 或允许对项目进行写入之前，请先阅读本文。

## 权限与安装

- 这是一个原生 DSH/Cordis 插件。它连接真实的 Host 服务，并不是针对恶意代码的安全边界。
- 保留常规的 Host 权限、沙箱限制、审批与 provider 条款。**没有预算审批流程**并不意味着可以绕过这些管控。
- 先确认当前生效的**由用户拥有的 Host 补丁**并做好备份，再合并生成的插入内容。绝不要覆盖无关配置、编辑随包提供的 preset，或盲目移除发生冲突的插件。在用户授权下停用它之前，先确认确切的旧行与回滚映射。
- Setup 只写入 `.local/entry.mjs` 与 `.local/host-patch.yml`，不会激活 profile。Doctor 与 `npm test` 都是离线的，不能证明可以真实访问 provider。
- 复制之后，`node scripts/verify.mjs` 会把清单中所列文件的哈希与 `portable-manifest.json` 比对。它检测的是清单中所列文件的缺失／修改，而不是未列出的额外文件。这既不是签名，也不能证明真实性；代码与清单两者的来源都需要你自己信任。
- 随附内容不含凭据、已认证账号或先前的资格认定状态。请通过获准的 Host UI／官方流程完成认证。不要把 API key 放进对话、不要复制剪贴板中的密钥，也不要迁移另一台机器的账号／状态目录。

## 项目范围与 agent 工具

先从明确的读取路径和 `allowed_tools:["read","glob","grep"]` 开始。做实现时，请指明可写文件与验收测试；只有在获得授权后才加入 `write`/`edit`。只有在确有需要且被允许时才加入 `pwsh`。工具的可用性并不等于有权改动无关文件、运行任意命令、删除数据或访问网络。

原生分发器使用绝对的 `maxDepth:1`，并期望调用方是根 agent。只读的未完成工作可以在新的子 agent 中继续。能改动文件或运行命令的工具集不会自动续行，因为已完成的副作用可能被重复执行。同一子 agent 的记忆、自主嵌套委派与持久的原生 assignment 恢复都不在承诺范围内。

## 资格认定范围

实测证据与 provider/model/effort 以及**所有者／根 agent 会话**精确绑定，并具有 **24 小时有效期**。请在实际派发该项目的同一会话中完成资格认定。新项目／会话或变更过的映射都需要重新取证；先前机器上的成功不会迁移过来。仅仅完成注册并不能证明授权资格、可用性、工具支持或可靠性。

探测失败的路由保持不可用；不要伪造资格认定 JSON、不要把合成 fixture 提升为证据、不要静默地用别名替换成另一个模型，也不要为了掩盖失败而卸载 provider。本插件不承诺自动重新认定。基础冒烟测试验证的是有限的文本／工具行为，而不是广泛的能力、保密性或不可变的后端身份。

`vision` 角色需要通过图像探测；`domain` 角色需要领域证据；机密／受限数据需要操作者具结。这三者都要通过 `orchestrator_qualify` 申请（见 [USAGE.zh.md](USAGE.zh.md)），且都不是仅凭基础冒烟测试就能获得的。

具结记录的是具名人员作出的主张及其书面依据，并且只用于放宽路由策略。它**不是**能力证明、授权资格核验、合规管控或隐私认证，本插件也无法核实其作者是否有权作出该具结。若某条已存储记录在没有具结的情况下其策略超出普通冒烟测试，就会被视为已被篡改而拒用。机密与受限数据仍然需要你的环境实际要求的那些管控；记录一份具结并不会创造出这些管控。

能力探测与其他任何探测一样会消耗真实配额。图像探测会通过 Host 的 attachment 服务写入其生成的 PNG，因此这些字节遵循该服务通常的保留策略。

路由还取决于本插件无法检查的 Host 解析。已安装 adapter 目录未描述的 model id 会以纯文本路由提供，因此其图像会在派发前被替换，图像探测会因能力而非可达性失败。若某个订阅桥接层原样转发 harness 的 tool-result 消息，那么每一次工具往返都会失败，而纯文本仍然成功。这两种情况都以 `UNAVAILABLE_AT_PROBE` 到达本插件；它们描述的是 Host，而不是模型。

## 持久化与恢复

原始 prompt 与可见输出在状态目录中都是**明文**。请限制文件系统访问、尽量减少敏感内容，并选择一个全新的绝对私有目录。不要把任务／资格认定状态复制到别处来制造「已就绪」的假象。校验和只能发现损坏，发现不了控制该目录的恶意写入者。

没有任何机制会自动清理已存储记录：assignment、直接任务与资格认定证据都会保留到你自己删除为止，已经过期的证据也一样。用 `orchestrator_list` 查看当前存有哪些内容，用 `orchestrator_forget` 删除它们。删除是永久性的，会拒绝正在执行中的记录，而且这是从不断增长的状态目录中清除明文 prompt 与输出的唯一方式。

状态目录与文件以 POSIX 模式 `0700`/`0600` 创建。**Windows 会忽略这些模式**，因此状态目录转而继承父文件夹的 ACL。在 Windows 上，请把它放在共享或同步位置之外，并显式限制其权限，例如：

```powershell
icacls "<state directory>" /inheritance:r /grant:r "$env:USERNAME:(OI)(CI)F"
```

该实现假定只有一个受信任的协调者。独占修订与文件同步并不提供分布式事务、有保证的远端精确一次投递或断电持久性。突然中断可能丢失尚未写入检查点的文本尾部。经脱敏的诊断信息只存在于内存中；拿不到诊断信息并不能证明原因出在 provider。

不确定的传输／用量状态、已取消的请求以及恢复出来的在途尝试都**不会被盲目重放**。不能通过重置 task ID 来规避这条规则。安全且已结算的直接续行与重试一次未知尝试是两回事。部分输出无法找回 provider 从未返回的文本。

## 预算与技术边界

**$1 是软性的估算目标，不是支出上限。** 获授权的请求可以在超出目标的情况下完成，无需逐次调用的财务审批。用量可能消耗付费或订阅配额；本插件不强制执行通用的硬性发票上限。

历史的 API 费率估算不是当前账单。订阅／原生 agent 的成本可能未知；在 `costUnknown:true` 下已知成本小计为零，并不意味着执行是免费的。推理计数绝不能被重复计费。provider 中间件可能执行认证刷新或内部重试，因此一次引擎尝试并不普遍等同于一次 HTTP 请求。

直接任务有 15 分钟的墙钟截止时间，从**计划时刻**开始计算；轮次默认 3、最多 8，并有受约束的 context／输出与所请求的输出 token 上限。原生任务同样有受约束的轮次／时间／context。adapter 行为可能不同；不要把所请求的 token 上限等同于上游已证实的强制执行。取消是协作式的，不能证明计费已经停止。

并发度被刻意设得很小。每个所有者会话**最多同时运行 2 个资格认定与 2 个原生委派／压缩 assignment**（`QUALIFICATION_BUSY`、`DELEGATION_BUSY`）。batch worker 共享这些原生槽位，并可能在一个内部 FIFO 队列中等待，该队列最多容纳 8 个待处理预留（`DELEGATION_QUEUE_FULL`）；普通的委派与压缩仍然直接拒绝而不是排队。每个所有者一次 batch 接受 2–8 个相互独立的只读任务。即使发生取消，槽位也要等子结果与资源释放都结算完毕才归还。这不是 Host 级／provider 级速率限制：资格认定与直接执行并不共享原生准入池。

直接任务仍然强制每个 task ID 只运行一次（`CONCURRENT_TASK`），最多 64 个所有者会话与 64 个已加载任务（`OWNER_CAPACITY`、`TASK_CAPACITY`），而不是共享的直接调用信号量。batch 限制约束的是任务扇出，而不是每个子 agent 内部的模型调用或总 token 数。batch 输出是收集到的 worker 数据，不是经策略批准的合并结果。写入、依赖调度以及自动恢复／重放都在 batch 接口之外。scope 字符串无法收窄文件系统沙箱；Host 工具白名单强制只读工具，而路径选择仍然属于任务指令。

## 输出验收

模型完成一轮并不证明答案或代码是正确的。请在常规权限下审阅生成的改动，并运行项目自身的检查。续行轮次的直接拼接可能缺少换行或其他分隔符；当精确格式很重要时，请检查轮次边界。添加分隔符并不是对截断的单词或结构化数据的通用修复。

本包不会创设新的许可授权，也不主张任何未在其他地方提供的开源许可。请查阅实际的 package／Host／provider 许可信息。离线测试、生成的候选文件、运行时激活、实际资格认定与真实任务结果应当分别报告——绝不要把它们合并成「处处完全就绪」这类没有依据的说法。