From c465d39d5865e8dd85c690a4ee53b6e0ed48795f Mon Sep 17 00:00:00 2001 From: mesalogo Date: Wed, 7 Oct 2026 21:26:40 +0800 Subject: [PATCH] docs(architecture): clarify storage pass-through mode --- docs/architecture/performance-principles.md | 1 + docs/development/agent-feature-maintenance.md | 6 ++++++ src/main/readonly-query-reader.ts | 9 ++++++++- 3 files changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/architecture/performance-principles.md b/docs/architecture/performance-principles.md index 1f7cc137..9365d30e 100644 --- a/docs/architecture/performance-principles.md +++ b/docs/architecture/performance-principles.md @@ -133,6 +133,7 @@ Main 负责窗口、生命周期、权限和消息转发。数据库查询、文 - 重查询复用有界 Worker；必要写入不排在整个导入解析或模型请求之后。长事务先减少事务内无关计算，再测写入排队，不把阻塞简单搬进唯一存储队列。 - 复用现有池、批处理和队列，记录在途数、排队数及实际资源使用。只有有明确依据时才设置容量；没有依据时将负载交给所属 Host，不因内部数字拒绝用户工作。有实测饥饿才引入最小调度调整，不预建通用优先级框架。 - 控制和取消不等待新的执行槽位；如果外部或用户设置要求排队，按该语义执行。禁止静默丢失、无限重启或自动扩增进程；不能把未经证明的队列上限包装成稳定性。 +- `ReadonlyQueryReader` 的生产 storage 模式不传 `maxPending`，因此请求直接透传给 storage host；其等待队列只服务显式有界的调用方和测试，不构成第二个 storage owner。 - 每个异步响应携带已有项目／会话／任务／操作归属；迟到响应不得覆盖新选择或新操作。归属检查先于改变共享请求代次、缓存或队列状态。 ### P12 架构完整性与 KISS diff --git a/docs/development/agent-feature-maintenance.md b/docs/development/agent-feature-maintenance.md index ad4a9d1a..ab589fdc 100644 --- a/docs/development/agent-feature-maintenance.md +++ b/docs/development/agent-feature-maintenance.md @@ -136,6 +136,12 @@ write 也必须服从当前实现与测试。修改前先确认代码中的常 Worker 发生故障时可以进入已有退避和恢复流程；这不应被伪装成负载上限。正常排队的 解析、存储和 Host 工作不能因为一个未经测量的队列数字直接返回 busy。 +`ReadonlyQueryReader` 同时服务只读 Worker 和桌面 storage client。只有调用方显式传入 +`maxPending` 时，`waiting` 队列才承担有界等待语义；生产 storage client 不传该选项， +请求直接交给 storage host。这个共享类不是第二个 storage owner，不能因为看到等待队列 +就给生产路径恢复默认 admission 上限。若未来实测证明某个边界需要容量策略，应先说明 +资源、故障和测量依据，再拆出最小的显式 wrapper 或增加调用方配置。 + ## 测试与真实验证 单元测试用于确定字节边界、事务回滚、顺序、归属、取消竞态、失败清理和重试。行为改动 diff --git a/src/main/readonly-query-reader.ts b/src/main/readonly-query-reader.ts index 74b394d7..91479b8e 100644 --- a/src/main/readonly-query-reader.ts +++ b/src/main/readonly-query-reader.ts @@ -43,7 +43,11 @@ type Waiting = { start: () => void; cancel: () => void; fail: (error: Error) => export type QueryTransport = Pick & Pick export interface QueryTransportOptions { createTransport: () => QueryTransport - /** Optional test or caller policy; production storage leaves this unset. */ + /** + * Optional caller policy. Production desktop storage leaves this unset so + * requests pass through to the storage host; the waiting queue is only for + * explicit bounded readers and tests. + */ maxPending?: number } @@ -83,6 +87,9 @@ export class ReadonlyQueryReader { private readonly transportOptions?: QueryTransportOptions ) {} + // This class correlates requests for both read workers and storage. The + // storage client intentionally uses the unbounded pass-through mode; it does + // not create a second storage owner or impose a product capacity limit. private get maxPending(): number { return this.transportOptions?.maxPending ?? DEFAULT_MAX_PENDING } /** False while backing off after a crash or startup failure. */