feat(tools): document-read 按需读取工具(design/24 S4)
CI / Backend (build / vet / test / cross-compile) (push) Has been cancelled
CI / Frontend (tsc + vite build) (push) Has been cancelled

- 只读 S3-A 的 sidecar 正文(首行元数据行不计入 text),按字符分页,带 truncated/nextOffset 续读语义与 extractTruncated(区分「正文到此为止」与「原文件到此为止」)。

- 越界三态不静默:offset<0 / offset>totalChars → ErrDocumentOffset(碰盘前拦下,文案带总字符数);offset==totalChars 合法(读到末尾)。名非法/无 sidecar/unreadable → 哨兵错误 + 中文文案,绝不返回空正文假装成功。

- 读侧出口收敛到 documents 包:新增 ReadSidecar(含 Sidecar/Readable/ErrSidecarUnavailable),sidecar.go 的 load 变薄壳且对外行为逐字不变 ⇒ sidecar 形状与名字形态校验全仓只有一份实现。

- 注册与既有 6 个 io 工具同一路径(tools.go),策略默认 owner-only(群聊/陌生人默认调不到)。

- 主会话独立验收:隔离 worktree(HEAD + 本切片 6 个路径)build/vet 绿、全树 59 包 0 FAIL、双平台交叉编译绿、io 包 60 PASS;变异独立复现(工具名常量改成 document_read ⇒ 注册名单两条用例红)。

- 报告里发现的真实断裂(清单游标恒等于 sidecar 正文长度 ⇒ 照它续读必空)已登记,并入 T1 以「sidecar 存全文 + 注入预算与抽取预算解耦」根治。
This commit is contained in:
AskaEth committed 2026-10-04 17:36:56 +08:00
1 parent a4789ec13e
commit 20c1edb36a
6 files changed
+842 -50

No files matched your search

+6 -46
View File
@@ -139,53 +139,13 @@ func (s *sidecarStore) pathFor(name string) (string, bool) {
return path, true
}
// load 读一条 sidecar 记录。不存在、读不出、形态损坏、抽取器版本不匹配都
// 返回 false(调用方据此重抽一次),并留下带来源的日志 —— 缓存失效是正常
// 路径,但绝不静默吞掉「文件在那儿却读不出来」这类信号。
// load 读一条 sidecar 记录,报告是否命中。**未命中一律返回 false**(调用方据此
// 重抽一次):不存在、读不出、形态损坏、抽取器版本不匹配都算未命中 —— 缓存失效是
// 正常路径。读取本体与带原因的错误由 loadSidecar 提供(sidecar_read.go),
// 供不重抽的读侧(`document-read` 工具)区分「到底为什么读不到」。
func (s *sidecarStore) load(name string) (cachedExtract, bool) {
if s == nil {
return cachedExtract{}, false
}
path, ok := s.pathFor(name)
if !ok {
return cachedExtract{}, false
}
f, err := os.Open(path)
if err != nil {
if !errors.Is(err, os.ErrNotExist) {
s.log.Warn("sidecar open", "name", name, "error", err)
}
return cachedExtract{}, false
}
defer func() { _ = f.Close() }()
data, err := io.ReadAll(io.LimitReader(f, maxSidecarBytes+1))
if err != nil || len(data) > maxSidecarBytes {
s.log.Warn("sidecar unreadable", "name", name, "bytes", len(data), "error", err)
return cachedExtract{}, false
}
header, body, ok := strings.Cut(string(data), sidecarHeaderEnd)
if !ok || !strings.HasPrefix(header, "{") {
s.log.Warn("sidecar malformed", "name", name)
return cachedExtract{}, false
}
meta := sidecarMeta{}
if err := json.Unmarshal([]byte(header), &meta); err != nil {
s.log.Warn("sidecar meta decode", "name", name, "error", err)
return cachedExtract{}, false
}
if meta.Version != ExtractorVersion {
// 抽取器升级:旧缓存按失效处理并重抽一次(记版本号的意义所在)。
s.log.Info("sidecar stale", "name", name, "version", meta.Version)
return cachedExtract{}, false
}
return cachedExtract{
Status: meta.Status,
Reason: meta.Reason,
Kind: meta.Kind,
Chars: meta.Chars,
Truncated: meta.Truncated,
Text: body,
}, true
rec, err := s.loadSidecar(name)
return rec, err == nil
}
// save 把一条结论原子地写进 sidecar。它**只写一次**:已存在且版本匹配的记录