# 为什么接上模型之后还需要这一层

v0.2.0 增加两种入口：原生 /bfy-ofm 命令处理当前会话选模；CLI 的 DshClient + runOneTurn 完成独立文本回合。下文“完整宿主未包含”指完整 QQ 工具 Agent 的行动账本、队列与记忆接线，不再表示缺少文本调用入口。最新操作和状态契约以 integration.md 为准。

一个短脚本只需要拿到回答。持续运行的 Agent 还要处理额度、后台任务、工具执行、取消、会话恢复和外部行动。

## 模型名称与供模渠道分开

`provider/model` 表示一次具体的候选路径。示例使用 `qodercn/dfmodel` 和 `trae/deepseek-v4.1-flash`，它们来自本地集成版本的目录，未必在别人的实例中存在。

调用顺序是：读取最新策略 → 过滤允许集、到期与临时停用 → 对照当前模型目录 → 跳过冷却渠道 → 映射本次任务档位 → 确认宿主选模成功 → 提交生成。

核心 `resolveLaneChain()` 保留生产策略，包括排除 `deepseek-official` 和 `deepseek-account`；这表达本项目的账号渠道使用范围，不代表其他渠道一定免费。`selectSessionRoute()` 额外要求显式启用、实际目录和有效的 CN 期限。

## 冷却是按渠道记录的

日额度错误、认证问题、短限频、网络错误与目录缺失不应共用一个等待时长。

| 分类 | 核心默认行为 |
| --- | --- |
| daily-quota / quota | 默认 30 分钟；CN 且明确启用 UTC+8 日重置策略时，冷却到次日零点 |
| auth | 30 分钟 |
| rate-limit | 1 分钟 |
| transport / stall | 10 分钟 |
| route | 6 小时 |
| 会话不存在、内容业务错误 | 不自动归为渠道故障 |

这些是工程策略，并非上游承诺。`dailyQuotaResetUtcOffset: 8` 只适用于确认按该服务日重置的 CN 权益；如果账号规则不同，需要调整策略。当前实现也会对 CN 的通用 quota 使用该日重置策略，故不能用它处理任意长期余额不足问题。

冷却记录只由一个进程写入；其他任务只读。正常写入先生成临时文件再替换。文件损坏时保留原件，本进程继续内存退避；持久化失败需要宿主处理日志，不能宣称重启后仍有可靠状态。

## 思考档位是一套映射

`lowest` 是偏好，不直接发给上游。示例目录中，CN 对应 `none`，TRAE 对应 `light`。任务可以覆盖全局偏好：普通聊天低档，日记或反思高档。

目录词表优先于内置副本。未知模型无明确映射时，不猜档位，交给宿主默认值。高档不保证更好的答案，也不保证固定用量。

## 模型等待和工具执行分别计时

`expect(sessionId)` 覆盖已提交却未收到 `turn/start` 的阶段。模型阶段出现有效文本会刷新静默计时，但累计模型活跃时间仍有上限。默认静默 45 秒，累计模型活跃预算 180 秒，可由宿主按任务设置。

收到工具调用后暂停模型计时，所有并行工具返回后再恢复。工具自身需要独立期限，事件流也需要独立健康检查。用户确认与审批事件会暂停计时，恢复接线由宿主负责。

看门狗只报告状态，不自动取消、不切换模型、不发送补偿消息。宿主应校验回合代际，防止对已经结束或已被替代的回合进行处置。

## 重试和外部行动

`runLaneAttempts()` 将尝试次数限制在两次以内，但不会自己证明重试安全。生产提取版默认检查 `error.safeToRetry === true`，这个标记必须由宿主根据实际回执计算。

公开适配层的 `mayReplayTurn()` 要求：错误属于渠道故障、旧回合已确认取消、没有调用工具、外部行动明确未发生。只要发送结果未知就停止自动重放，交给行动账本核对。即使旧回合已取消，也不能据此推断此前工具没有产生副作用。

完整生产系统还有行动授权令牌、持久回执、任务队列与工作会话归档；它们未包含在本仓库中。这里的保守判断不能替代完整的去重与行动授权机制。

## 审计与记忆

审计只投影会话、来源、任务、渠道、档位和状态等已声明字段，不保存提示词或工具参数。若调用者把敏感文本塞入这些元数据字段，模块并不会自动将其匿名化。重启前没有收尾的提交显示 unknown；审计文件损坏则保留原件并报错。

长期记忆位于桥接层背后的独立存储。切换模型不需要迁移这份存储；新会话是否能正确读取仍取决于宿主的记忆注入、权限和检索接线。本仓库只描述这个边界，不实现记忆系统。