From 20c1edb36a200170d3ba4835776df2a1f32a1775 Mon Sep 17 00:00:00 2001 From: AskaEth Date: Sun, 4 Oct 2026 17:36:56 +0800 Subject: [PATCH] =?UTF-8?q?feat(tools):=20document-read=20=E6=8C=89?= =?UTF-8?q?=E9=9C=80=E8=AF=BB=E5=8F=96=E5=B7=A5=E5=85=B7=EF=BC=88design/24?= =?UTF-8?q?=20S4=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 只读 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 存全文 + 注入预算与抽取预算解耦」根治。 --- internal/runtime/documents/sidecar.go | 52 +-- internal/runtime/documents/sidecar_read.go | 128 ++++++ plugins/tools/io/document_read.go | 256 ++++++++++++ plugins/tools/io/document_read_test.go | 447 +++++++++++++++++++++ plugins/tools/io/tools.go | 1 + plugins/tools/io/tools_test.go | 8 +- 6 files changed, 842 insertions(+), 50 deletions(-) create mode 100644 internal/runtime/documents/sidecar_read.go create mode 100644 plugins/tools/io/document_read.go create mode 100644 plugins/tools/io/document_read_test.go diff --git a/internal/runtime/documents/sidecar.go b/internal/runtime/documents/sidecar.go index 0340c48..ac54a67 100644 --- a/internal/runtime/documents/sidecar.go +++ b/internal/runtime/documents/sidecar.go @@ -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。它**只写一次**：已存在且版本匹配的记录 diff --git a/internal/runtime/documents/sidecar_read.go b/internal/runtime/documents/sidecar_read.go new file mode 100644 index 0000000..287800f --- /dev/null +++ b/internal/runtime/documents/sidecar_read.go @@ -0,0 +1,128 @@ +package documents + +import ( + "encoding/json" + "errors" + "fmt" + "io" + "os" + "strings" + + "git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/history" +) + +// 本文件是 sidecar 的**读侧出口**（design/24 §4.2 路线②）。装配期的 +// `resolveDocuments` 走 `sidecarStore.load`（未命中就重抽一次），而 +// `document-read` 工具要的是「已经落盘的那份正文」：它既不该重抽（design/24 §4.3 +// 「只抽一次」，否则 status/chars 的持久统计会漂移），也不该把 sidecar 形状 +// （首行元数据 + 正文自第二行起）再实现一遍。这里因此把读路径收成一个小出口， +// 形状、名字形态校验、抽取器版本判据仍**只有一份实现**。 + +// ErrSidecarUnavailable 报告一份文档**没有可读的抽取结果**：数据目录未配置、 +// sidecar 不存在、读不出、形态损坏或抽取器版本不匹配。不重抽的读侧据此给出诚实 +// 错误，绝不返回空正文假装成功（design/24 §4.4）。一律用 errors.Is 判定。 +var ErrSidecarUnavailable = errors.New("没有可读的抽取结果") + +// Sidecar 是一条已落盘 sidecar 的读取结果 —— 纯读取，不含任何抽取动作。 +type Sidecar struct { + // Status 是抽取结论，取值见 history.DocumentStatus*。 + Status string + // Reason 是 Status == unreadable 时的诚实原因（正文位置为空）。 + Reason string + // Kind 是抽取所得内容的种类（text / csv / tsv）。 + Kind string + // Chars 是抽取期写盘时的正文字符数（rune）。 + Chars int + // Truncated 报告抽取期的正文是否已按预算截断（design/24 §3.4 的 64K 字符）。 + Truncated bool + // Text 是正文本身：sidecar 第一行元数据**之后**的部分（含 CSV/TSV 的摘要行）。 + Text string +} + +// Readable 报告这条记录是否带着可读正文：只有抽取结论为 extracted 才有正文 +// （unreadable 时 sidecar 的正文位置是空的，原因在 Reason 里）。 +func (s Sidecar) Readable() bool { return s.Status == history.DocumentStatusExtracted } + +// ReadSidecar 读取 name 的 sidecar：**只读 sidecar，绝不重抽、绝不读原文件**。 +// +// 名字形态非法（非单个路径段、非 32 位小写十六进制主名、扩展名超长）返回包装 +// ErrInvalidName 的错误，并且**在触达文件系统之前**就拒绝；其余失败（数据目录 +// 未配置、sidecar 不存在、读不出、损坏、版本失效）返回包装 ErrSidecarUnavailable +// 的错误，具体原因在错误链的文案里。dataDir 是**数据目录**（不是 extracted 目录）： +// sidecar 落在它的 extracted/ 子目录下，与装配期解析器同一口径。 +func ReadSidecar(dataDir, name string) (Sidecar, error) { + if !validStorageName(name) { + return Sidecar{}, fmt.Errorf("documents: read sidecar %q: %w", name, ErrInvalidName) + } + store := newSidecarStore(dataDir, sourcedLog(nil)) + if store == nil { + return Sidecar{}, fmt.Errorf("documents: read sidecar %q: 数据目录未配置: %w", name, ErrSidecarUnavailable) + } + rec, err := store.loadSidecar(name) + if err != nil { + return Sidecar{}, fmt.Errorf("documents: read sidecar %q: %w", name, err) + } + return Sidecar{ + Status: rec.Status, + Reason: rec.Reason, + Kind: rec.Kind, + Chars: rec.Chars, + Truncated: rec.Truncated, + Text: rec.Text, + }, nil +} + +// loadSidecar 是 sidecar 读路径的唯一实现。命中返回记录与 nil；任何失败返回包装了 +// ErrSidecarUnavailable 的错误（名字形态非法时为 ErrInvalidName），并把**具体原因** +// （不存在 / 读不出 / 形态损坏 / 版本失效）写进错误链 —— 装配期的 load 只关心「是否 +// 命中」（未命中就重抽一次），而不重抽的读侧需要知道到底为什么读不到。 +// +// 日志口径与既有读路径一致：缓存未命中是正常路径，「文件不在」因此不吵；其余失败 +// 留一条带来源的 WARN/INFO，绝不静默吞掉「文件在那儿却读不出来」这类信号（日志只记 +// name/字节数/版本，**绝不记正文**）。 +func (s *sidecarStore) loadSidecar(name string) (cachedExtract, error) { + if s == nil { + return cachedExtract{}, fmt.Errorf("sidecar 存储未配置: %w", ErrSidecarUnavailable) + } + path, ok := s.pathFor(name) + if !ok { + return cachedExtract{}, fmt.Errorf("sidecar 名字形态非法: %w", ErrInvalidName) + } + 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{}, fmt.Errorf("sidecar 打开失败: %w", ErrSidecarUnavailable) + } + return cachedExtract{}, fmt.Errorf("sidecar 不存在: %w", ErrSidecarUnavailable) + } + 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{}, fmt.Errorf("sidecar 读不出或超出上限（%d 字节）: %w", len(data), ErrSidecarUnavailable) + } + header, body, ok := strings.Cut(string(data), sidecarHeaderEnd) + if !ok || !strings.HasPrefix(header, "{") { + s.log.Warn("sidecar malformed", "name", name) + return cachedExtract{}, fmt.Errorf("sidecar 形态损坏（首行不是元数据）: %w", ErrSidecarUnavailable) + } + meta := sidecarMeta{} + if err := json.Unmarshal([]byte(header), &meta); err != nil { + s.log.Warn("sidecar meta decode", "name", name, "error", err) + return cachedExtract{}, fmt.Errorf("sidecar 元数据解码失败: %w", ErrSidecarUnavailable) + } + if meta.Version != ExtractorVersion { + // 抽取器升级：旧缓存按失效处理并重抽一次（记版本号的意义所在）。 + s.log.Info("sidecar stale", "name", name, "version", meta.Version) + return cachedExtract{}, fmt.Errorf("sidecar 抽取器版本不匹配（%s）: %w", meta.Version, ErrSidecarUnavailable) + } + return cachedExtract{ + Status: meta.Status, + Reason: meta.Reason, + Kind: meta.Kind, + Chars: meta.Chars, + Truncated: meta.Truncated, + Text: body, + }, nil +} diff --git a/plugins/tools/io/document_read.go b/plugins/tools/io/document_read.go new file mode 100644 index 0000000..7734c9d --- /dev/null +++ b/plugins/tools/io/document_read.go @@ -0,0 +1,256 @@ +package io + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "log/slog" + "strings" + "unicode/utf8" + + "git.yeij.top/AskaEth/Cyrene_v2/internal/config" + "git.yeij.top/AskaEth/Cyrene_v2/internal/logger" + "git.yeij.top/AskaEth/Cyrene_v2/internal/platform" + "git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/documents" + "git.yeij.top/AskaEth/Cyrene_v2/pkg/plugins/sdk" +) + +// 本文件实现 design/24 §4.2 路线② 的按需读取工具 `document-read`：附件超出注入 +// 预算时，装配期只给出「清单行 + 续读游标」（loop/document.go 的 +// documentNoteTruncated），模型用本工具按 offset/limit 自己取正文。 +// +// 三条口径： +// 1. **只读 sidecar，绝不重抽**（design/24 §4.3）：读取走 documents.ReadSidecar， +// 因此「只抽一次」与 status/chars/truncated 的持久统计不会被一次读取打乱； +// 原文件在抽取之后被删除也不影响读取。 +// 2. **不扩大文件访问面**（design/24 §4.2 末）：本工具只接受**服务端签发的存储名**， +// 不接路径；可触达的范围就是 `/extracted`（本就是 file 工具 roots 的 +// 子集），路径拼接与名字形态校验全在摄取层那一份实现里（不重复校验）。 +// 3. **失败必须可见**（design/24 §4.4）：名非法、没有抽取结果、抽取结论为不可读 +// 一律返回诚实错误（哨兵 + 可读文案），绝不返回空正文假装成功。 + +// Compile-time assertion that documentReadTool implements sdk.Tool. +var _ sdk.Tool = (*documentReadTool)(nil) + +const ( + // documentReadToolName 是工具名。它与装配期清单行里的字样（loop 的 + // documentNoteTruncated：「可用 document-read 继续读取」）**逐字一致** —— + // 这两处是成对契约，改一处必须改两处，否则模型照清单调用会拿到「未知工具」。 + documentReadToolName = "document-read" + + // defaultDocumentReadChars 是 limit 缺省时的读取字符数。依据：装配期一次注入 + // 最多 64K 字符（documents.MaxExtractChars），本工具是**按需**取用，单次 8000 + // 字符（≈2–3K token）是「读完整一段」与「别让一次工具往返吃掉整个上下文」之间的 + // 折中，与 file（5 MiB）/ web-fetch（2 MiB）同属「有上限的取用」。 + defaultDocumentReadChars = 8000 + + // maxDocumentReadChars 是 limit 的上限 = **抽取期预算**（sidecar 正文的物理上限）。 + // 它直接取抽取器的常量而不是再写一个字面量：正文在抽取期已被截到 + // documents.MaxExtractChars，再大的请求都读不到更多，因此上限就是它。 + maxDocumentReadChars = documents.MaxExtractChars + + // documentReadNoReason 是 sidecar 说「不可读」却没给出原因时的兜底文案：不静默， + // 也不编造一个具体原因。 + documentReadNoReason = "抽取侧的结论是不可读，且没有给出原因" +) + +// ErrDocumentOffset 报告 offset 超出可读范围（负数，或超过抽取正文的字符数）。 +// 调用方与测试一律用 errors.Is 判定（项目规范 §10：不按错误文本匹配）。 +var ErrDocumentOffset = errors.New("offset 超出可读范围") + +// ErrDocumentUnreadable 报告该文档的抽取结论就是「读不到正文」（design/24 §4.4 的 +// status=unreadable）：sidecar 在，但正文位置是空的，因此没有东西可读。 +var ErrDocumentUnreadable = errors.New("文档不可读：抽取侧没有给出正文") + +// documentReadTool 按 offset/limit 读一份**已抽取**文档的正文片段。 +type documentReadTool struct { + // dataDir 是数据目录；sidecar 在它的 extracted/ 子目录下（与装配期同一口径）。 + dataDir string + log *slog.Logger +} + +// newDocumentReadTool 构造本工具。数据目录由 documentDataDir 解析 —— 必须与 +// cmd/cyrene 的 resolveDataDir 得出同一棵树，否则会出现「装配期写下了 sidecar， +// 工具却在另一个目录里找」的症状（设计上「只抽一次」的前提被破坏）。 +func newDocumentReadTool(t *tools) *documentReadTool { + return &documentReadTool{ + dataDir: documentDataDir(t.cfg), + // 标来源（项目规范 §10）：注入的基 logger 可能不带来源标签，这里补齐。 + log: logger.WithSource(t.log, source), + } +} + +// Name implements sdk.Tool. +func (d *documentReadTool) Name() string { return documentReadToolName } + +// Description implements sdk.Tool. It documents the coordinate system, because the +// model only sees this text plus the attachment list line that pointed it here. +func (d *documentReadTool) Description() string { + return "Read a slice of an already-extracted document (an attachment) by character offset. " + + "Use it with the attachment list line: that line prints a continuation cursor 'offset=N' when the " + + "injected text was cut, and 'offset' here is that same 0-based character offset into the extracted " + + "text (the CSV/TSV summary line, when present, is part of it). Each result reports totalChars and, " + + "when more text is available after this slice, truncated=true plus nextOffset to continue from. " + + "Only server-issued document names from the attachment list can be read; nothing is re-extracted, " + + "so the extracted text is the same text that was injected. Note that the extraction itself is " + + "capped: when extractTruncated is true the extracted text ends there but the original document is longer." +} + +// Parameters implements sdk.Tool. +func (d *documentReadTool) Parameters() (map[string]any, error) { + return map[string]any{ + "type": "object", + "properties": map[string]any{ + "name": map[string]any{ + "type": "string", + "description": "Server-issued document name, exactly as printed in the attachment list line (32 hex characters plus an extension).", + }, + "offset": map[string]any{ + "type": "integer", + "description": "0-based character offset into the extracted text; pass the attachment line's cursor to continue where the injection stopped. Default 0.", + }, + "limit": map[string]any{ + "type": "integer", + "description": fmt.Sprintf("How many characters to return. Default %d, capped at %d.", + defaultDocumentReadChars, maxDocumentReadChars), + }, + }, + "required": []any{"name"}, + }, nil +} + +// documentReadResult 是工具的返回载荷（以 JSON 文本返回）。字段名对齐 design/24 +// §4.3 的「续读游标」与本仓 web-fetch 的 truncated 语义。 +type documentReadResult struct { + // Name 回显文档存储名，便于模型在多附件时对齐是哪一份。 + Name string `json:"name"` + // Status 是抽取结论。读到正文时它恒为 extracted —— 其它结论走诚实错误。 + Status string `json:"status"` + // Offset 是本次读取的起始字符偏移（生效值）。 + Offset int `json:"offset"` + // Limit 是本次生效的字符上限（缺省与夹取之后的值）。 + Limit int `json:"limit"` + // TotalChars 是抽取正文的总字符数，也是 offset 的上界。 + TotalChars int `json:"totalChars"` + // Truncated 报告本次读取是否被 limit 截断：为 true 时还有内容，用 NextOffset 续读。 + Truncated bool `json:"truncated"` + // NextOffset 是续读游标（= Offset + 本次返回的字符数）；没有更多内容时为 0 并省略。 + NextOffset int `json:"nextOffset,omitempty"` + // ExtractTruncated 报告**抽取期**是否已按预算截断（sidecar 的 truncated）：为 true 时 + // 「正文到此为止」不等于「原文件到此为止」—— 预算之外的内容不在 sidecar 里 + //（design/24 §9.6 第 3 条：64K 预算落在抽取期）。这条事实必须让模型看得见， + // 否则它会拿「读到末尾」当成「文件只有这么长」。 + ExtractTruncated bool `json:"extractTruncated,omitempty"` + // Text 是本次读到的正文（sidecar 第一行元数据之后的部分）。 + Text string `json:"text"` +} + +// Execute implements sdk.Tool. 返回的是 **JSON 文本**（字符串）：循环的 +// formatToolResult 对字符串直通，模型因此看到裸 JSON，与 web-fetch 的结果同族。 +func (d *documentReadTool) Execute(ctx context.Context, args any) (any, error) { + m, ok := args.(map[string]any) + if !ok { + return nil, fmt.Errorf("io: %s: 参数必须是对象", documentReadToolName) + } + if err := ctx.Err(); err != nil { + return nil, err + } + offset, limit, err := documentReadWindow(m) + if err != nil { + return nil, err + } + name := strings.TrimSpace(argString(m, "name")) + rec, err := documents.ReadSidecar(d.dataDir, name) + if err != nil { + // 名非法 / 没有可读的抽取结果：摄取层的哨兵原样上抛（errors.Is 可达）， + // 具体原因在错误链的文案里。日志只记名字与错误，**绝不记正文**。 + d.log.Warn("io document-read: extracted document unavailable", "name", name, "error", err) + return nil, fmt.Errorf("io: %s: %w", documentReadToolName, err) + } + if !rec.Readable() { + reason := strings.TrimSpace(rec.Reason) + if reason == "" { + reason = documentReadNoReason + } + d.log.Warn("io document-read: extracted document unreadable", "name", name, "status", rec.Status) + return nil, fmt.Errorf("io: %s: name %q: %s: %w", documentReadToolName, name, reason, ErrDocumentUnreadable) + } + total := utf8.RuneCountInString(rec.Text) + if offset > total { + return nil, fmt.Errorf("io: %s: offset %d 超出正文范围（共 %d 字符）: %w", + documentReadToolName, offset, total, ErrDocumentOffset) + } + slice, more := documentReadSlice(rec.Text, offset, limit) + next := 0 + if more { + next = offset + utf8.RuneCountInString(slice) + } + raw, err := json.Marshal(documentReadResult{ + Name: name, + Status: rec.Status, + Offset: offset, + Limit: limit, + TotalChars: total, + Truncated: more, + NextOffset: next, + ExtractTruncated: rec.Truncated, + Text: slice, + }) + if err != nil { + return nil, fmt.Errorf("io: %s: 编码结果: %w", documentReadToolName, err) + } + // 日志只记 name/offset/limit/chars —— **绝不记正文**（design/24 §3.2 的日志口径）。 + d.log.Debug("io document-read: served extracted document slice", + "name", name, "offset", offset, "limit", limit, + "chars", utf8.RuneCountInString(slice), "truncated", more) + return string(raw), nil +} + +// documentReadWindow 解析 offset 与 limit。offset 缺省 0，**负数在这里就被拒**（早于 +// 任何读盘动作）；limit 缺省 defaultDocumentReadChars、非正数按缺省处理、超过 +// maxDocumentReadChars 夹到上限 —— 夹取只会削掉「多要了」的部分，绝不会少给已存在的 +// 正文（正文本身就在同一上限内）。 +func documentReadWindow(m map[string]any) (int, int, error) { + offset := 0 + if v, ok := argInt(m, "offset"); ok { + offset = v + } + if offset < 0 { + return 0, 0, fmt.Errorf("io: %s: offset %d 无效（0 基，从抽取正文开头算起）: %w", + documentReadToolName, offset, ErrDocumentOffset) + } + limit := defaultDocumentReadChars + if v, ok := argInt(m, "limit"); ok && v > 0 { + limit = v + } + if limit > maxDocumentReadChars { + limit = maxDocumentReadChars + } + return offset, limit, nil +} + +// documentReadSlice 返回 s 从第 offset 个字符起的至多 limit 个字符，以及其后是否还有 +// 内容。单位是**字符（rune）**而不是字节 —— 与清单行的续读游标同一口径（loop 给的 +// 是「已注入的字符数」），因此多字节字符既不会被算错，也不会被切成两半。s 的长度受 +// 抽取预算封顶（documents.MaxExtractChars），故这里的一次转换是有界的。 +func documentReadSlice(s string, offset, limit int) (string, bool) { + runes := []rune(s) + if offset >= len(runes) { + return "", false + } + if end := offset + limit; end < len(runes) { + return string(runes[offset:end]), true + } + return string(runes[offset:]), false +} + +// documentDataDir 解析本工具要读的数据目录：配置为空时用平台标准数据目录，与 +// cmd/cyrene 的 resolveDataDir（装配期解析器的 DataDir）同一口径。两侧不一致的症状是 +// 「附件全都读不到」—— sidecar 写在一棵树里，工具却在另一棵树里找。 +func documentDataDir(cfg *config.Config) string { + if cfg != nil && strings.TrimSpace(cfg.DataDir) != "" { + return cfg.DataDir + } + return platform.DefaultDataDir() +} diff --git a/plugins/tools/io/document_read_test.go b/plugins/tools/io/document_read_test.go new file mode 100644 index 0000000..47cf636 --- /dev/null +++ b/plugins/tools/io/document_read_test.go @@ -0,0 +1,447 @@ +package io + +import ( + "context" + "encoding/json" + "errors" + "os" + "path/filepath" + "strings" + "testing" + "unicode/utf8" + + "git.yeij.top/AskaEth/Cyrene_v2/internal/capability/registry" + "git.yeij.top/AskaEth/Cyrene_v2/internal/capability/restrict" + "git.yeij.top/AskaEth/Cyrene_v2/internal/config" + "git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/documents" + "git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/history" + "git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model" + "git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/tool" +) + +// docName 造一个形态合法的服务端存储名：32 位小写十六进制主名 + 扩展名。 +func docName(ext string) string { return strings.Repeat("ab12", 8) + ext } + +// docReadFixture 是一份隔离的数据目录 + **真实上游解析器**。夹具里的 sidecar 一律由 +// documents.Resolver（S3-A 的生产者）写出，测试因此不复制「首行元数据 + 正文自第二行 +// 起」的第二份实现：生产者与消费者在同一份夹具里对接，sidecar 形状一漂移测试就红。 +type docReadFixture struct { + dataDir string + uploads string + resolver *documents.Resolver +} + +func newDocReadFixture(t *testing.T) *docReadFixture { + t.Helper() + dataDir := t.TempDir() + uploads := filepath.Join(dataDir, "uploads", "documents") + if err := os.MkdirAll(uploads, 0o700); err != nil { + t.Fatalf("建上传目录: %v", err) + } + return &docReadFixture{ + dataDir: dataDir, + uploads: uploads, + resolver: documents.NewResolver(documents.Config{DataDir: dataDir, UploadsDir: uploads}), + } +} + +// extract 落一份上传件并让装配期解析器跑一次（写出 sidecar），返回结论与**注入正文**： +// 后者就是模型在清单行下面看到的正文，也是工具 offset/limit 的坐标系。 +func (f *docReadFixture) extract(t *testing.T, name, content string) (history.DocumentRef, string) { + t.Helper() + if err := os.WriteFile(filepath.Join(f.uploads, name), []byte(content), 0o600); err != nil { + t.Fatalf("写上传件: %v", err) + } + msg := model.DocumentMessage(model.RoleUser, "", model.Document{Name: name, MIME: "text/plain", Size: int64(len(content))}) + refs, bodies, err := f.resolver.Resolve(context.Background(), msg) + if err != nil { + t.Fatalf("解析 %q: %v", name, err) + } + return refs[name], bodies[name] +} + +// sidecarPath 是某份文档的 sidecar 路径（与上游同一命名规则，供断言用）。 +func (f *docReadFixture) sidecarPath(name string) string { + return filepath.Join(f.dataDir, "extracted", name+".txt") +} + +// tool 返回指向同一份数据目录的 document-read 工具。 +func (f *docReadFixture) tool(t *testing.T) *documentReadTool { + t.Helper() + got, ok := findTool(t, buildTools(t, &config.Config{DataDir: f.dataDir}), documentReadToolName).(*documentReadTool) + if !ok { + t.Fatalf("%q 工具类型不符", documentReadToolName) + } + return got +} + +// callDocRead 执行一次 document-read，并把返回的 JSON 文本解回结果结构。工具返回的是 +// **字符串**（循环的 formatToolResult 对字符串直通，模型看到裸 JSON），这里因此必须反 +// 序列化才能断言字段 —— 它同时钉住「返回值是 JSON 文本」这条约定。 +func callDocRead(t *testing.T, tl *documentReadTool, args map[string]any) (documentReadResult, error) { + t.Helper() + raw, err := tl.Execute(context.Background(), args) + if err != nil { + return documentReadResult{}, err + } + text, ok := raw.(string) + if !ok { + t.Fatalf("返回值类型 = %T, want string（JSON 文本）", raw) + } + var out documentReadResult + if err := json.Unmarshal([]byte(text), &out); err != nil { + t.Fatalf("返回值不是合法 JSON: %v（%q）", err, text) + } + return out, nil +} + +// TestDocumentReadTool_PaginatesWithNextOffset 钉住①：首读 + 用 nextOffset 续读，两段 +// 拼接逐字等于装配期注入的正文（两边同一坐标系），游标单位为字符而非字节。 +func TestDocumentReadTool_PaginatesWithNextOffset(t *testing.T) { + t.Parallel() + fx := newDocReadFixture(t) + name := docName(".txt") + body := "季度报告：营收增长 12%。\n" + strings.Repeat("第二段：成本下降 3%。\n", 12) + _, injected := fx.extract(t, name, body) + tool := fx.tool(t) + total := utf8.RuneCountInString(injected) + half := total / 2 + + first, err := callDocRead(t, tool, map[string]any{"name": name, "limit": half}) + if err != nil { + t.Fatalf("首读: %v", err) + } + if first.Status != "extracted" || first.Offset != 0 || first.TotalChars != total { + t.Fatalf("首读 = %+v, want extracted / offset 0 / totalChars %d", first, total) + } + if !first.Truncated || first.NextOffset != half || utf8.RuneCountInString(first.Text) != half { + t.Fatalf("首读截断信息 = %+v, want truncated + nextOffset %d + 正文 %d 字符", first, half, half) + } + second, err := callDocRead(t, tool, map[string]any{"name": name, "offset": first.NextOffset}) + if err != nil { + t.Fatalf("续读: %v", err) + } + if second.Offset != half || second.Truncated || second.NextOffset != 0 { + t.Fatalf("续读 = %+v, want 读到末尾（offset %d、无续读游标）", second, half) + } + if first.Text+second.Text != injected { + t.Fatalf("两段拼接 %q + %q != 注入正文 %q", first.Text, second.Text, injected) + } + if second.Text != string([]rune(injected)[half:]) { + t.Fatalf("续读正文 = %q, want 注入正文的后半段", second.Text) + } +} + +// TestDocumentReadTool_ContinuesAcrossPages 钉住「续读之后**仍然**被 limit 截断」这条 +// 路径：游标必须一页页往前走（既不原地打转，也不吞掉中间的内容），多页拼接逐字等于 +// 注入正文。 +func TestDocumentReadTool_ContinuesAcrossPages(t *testing.T) { + t.Parallel() + fx := newDocReadFixture(t) + name := docName(".txt") + _, injected := fx.extract(t, name, strings.Repeat("一行正文，用于多页续读。\n", 20)) + tool := fx.tool(t) + total := utf8.RuneCountInString(injected) + step := total/4 + 1 // 至少 3 页，因此中间那些页后面还有内容 + + var joined string + offset, pages := 0, 0 + for { + if pages++; pages > 8 { + t.Fatalf("分页不收敛：offset 停在 %d", offset) + } + page, err := callDocRead(t, tool, map[string]any{"name": name, "offset": offset, "limit": step}) + if err != nil { + t.Fatalf("第 %d 页: %v", pages, err) + } + if page.Offset != offset { + t.Fatalf("第 %d 页 offset = %d, want %d", pages, page.Offset, offset) + } + // limit 是**上限**：任何一页都不得超出（多给会让模型的上下文预算失控）。 + if n := utf8.RuneCountInString(page.Text); n > step { + t.Fatalf("第 %d 页返回 %d 字符, 超过 limit %d", pages, n, step) + } + joined += page.Text + if page.Truncated && utf8.RuneCountInString(page.Text) != step { + t.Fatalf("第 %d 页被截断却只给了 %d 字符, want %d", pages, utf8.RuneCountInString(page.Text), step) + } + if !page.Truncated { + if page.NextOffset != 0 { + t.Fatalf("末页仍带续读游标 %d", page.NextOffset) + } + break + } + if want := offset + utf8.RuneCountInString(page.Text); page.NextOffset != want { + t.Fatalf("第 %d 页续读游标 = %d, want %d", pages, page.NextOffset, want) + } + offset = page.NextOffset + } + if pages < 3 { + t.Fatalf("只读到 %d 页，夹具没有覆盖「续读后仍被截断」", pages) + } + if joined != injected { + t.Fatalf("多页拼接 = %d 字符, want 注入正文 %d 字符", utf8.RuneCountInString(joined), total) + } +} + +// TestDocumentReadTool_LimitDefaultAndCap 钉住 limit 的缺省与上限：缺省取 +// defaultDocumentReadChars，超过上限的请求夹到 maxDocumentReadChars —— 正文本身就在同一 +// 上限内（抽取期预算），因此夹取只会削掉「多要了」的部分，不会少给已存在的正文。 +func TestDocumentReadTool_LimitDefaultAndCap(t *testing.T) { + t.Parallel() + fx := newDocReadFixture(t) + name := docName(".txt") + _, injected := fx.extract(t, name, "短正文：只有这一行。\n") + tool := fx.tool(t) + + got, err := callDocRead(t, tool, map[string]any{"name": name}) + if err != nil { + t.Fatalf("缺省读取: %v", err) + } + if got.Limit != defaultDocumentReadChars || got.Truncated || got.NextOffset != 0 || got.Text != injected { + t.Fatalf("缺省读取 = %+v, want limit %d、无截断、正文 %q", got, defaultDocumentReadChars, injected) + } + capped, err := callDocRead(t, tool, map[string]any{"name": name, "limit": maxDocumentReadChars * 2}) + if err != nil { + t.Fatalf("超大 limit 读取: %v", err) + } + if capped.Limit != maxDocumentReadChars { + t.Fatalf("limit 夹取 = %d, want %d", capped.Limit, maxDocumentReadChars) + } +} + +// TestDocumentReadTool_OffsetOutOfRange 钉住②：负 offset 在碰盘之前就被拒，超过正文长度 +// 的 offset 也不静默给空，而「恰好等于正文长度」是合法的「读到末尾」。 +func TestDocumentReadTool_OffsetOutOfRange(t *testing.T) { + t.Parallel() + fx := newDocReadFixture(t) + name := docName(".txt") + _, injected := fx.extract(t, name, "abcdefghij\n") + tool := fx.tool(t) + total := utf8.RuneCountInString(injected) + + // 负数：用一份**从未抽取过**的名字证明它在读盘之前就被拒 —— 若实现先读盘，这里得到的 + // 会是「没有可读的抽取结果」而不是 offset 错误。 + if _, err := callDocRead(t, tool, map[string]any{"name": docName(".log"), "offset": -1}); !errors.Is(err, ErrDocumentOffset) { + t.Fatalf("负 offset → %v, want ErrDocumentOffset（应在碰盘前被拒）", err) + } + if _, err := callDocRead(t, tool, map[string]any{"name": name, "offset": total + 1}); !errors.Is(err, ErrDocumentOffset) { + t.Fatalf("越界 offset → %v, want ErrDocumentOffset", err) + } + last, err := callDocRead(t, tool, map[string]any{"name": name, "offset": total}) + if err != nil { + t.Fatalf("末尾读取: %v", err) + } + if last.Text != "" || last.Truncated || last.NextOffset != 0 || last.TotalChars != total { + t.Fatalf("末尾读取 = %+v, want 空 text + 无续读 + totalChars %d", last, total) + } +} + +// TestDocumentReadTool_RejectsIllegalName 钉住④（含「不碰盘」）：形态非法的名字必须在触达 +// 文件系统之前被拒。数据目录在这里被指向一条**不存在**的路径：若实现先读盘，得到的会是 +// 「没有可读的抽取结果」，因此 errors.Is(ErrInvalidName) 本身就是「没碰盘」的证据。 +func TestDocumentReadTool_RejectsIllegalName(t *testing.T) { + t.Parallel() + dataDir := filepath.Join(t.TempDir(), "missing") + tool, ok := findTool(t, buildTools(t, &config.Config{DataDir: dataDir}), documentReadToolName).(*documentReadTool) + if !ok { + t.Fatalf("%q 工具类型不符", documentReadToolName) + } + illegal := []string{ + "", // 空名字 + "../secret.txt", // 路径穿越 + "..", // 父目录 + "a.txt", // 主名不足 32 位 + "ab12ab12ab12ab12ab12ab12ab12ab1.txt", // 31 位主名 + docName(".TXT"), // 大写扩展名 + strings.Repeat("g", 32) + ".txt", // 主名不是十六进制 + docName("." + strings.Repeat("x", 13)), // 扩展名超长（>12） + "extracted/" + docName(".txt"), // 含目录分隔符 + `C:\Windows\x.txt`, // 绝对路径 + "ab12ab12ab12ab12ab12ab12ab12ab12..txt", // 扩展名里带点 + } + for _, name := range illegal { + if _, err := callDocRead(t, tool, map[string]any{"name": name}); !errors.Is(err, documents.ErrInvalidName) { + t.Fatalf("name %q → %v, want documents.ErrInvalidName", name, err) + } + } + if _, err := tool.Execute(context.Background(), "not-an-object"); err == nil { + t.Fatal("非对象参数应当报错") + } + entries, err := os.ReadDir(filepath.Join(dataDir, "extracted")) + if err != nil && !errors.Is(err, os.ErrNotExist) { + t.Fatalf("读 extracted 目录: %v", err) + } + if len(entries) != 0 { + t.Fatalf("非法名字竟然产生了 %d 个文件", len(entries)) + } + // 扩展名白名单是 S1 存储侧的裁决（design/24 §4.2 末：不重复存储侧校验、不扩大访问面）： + // 形态合法但 S1 永不会签发的扩展名因此走到「没有可读的抽取结果」这条诚实错误。 + if _, err := callDocRead(t, tool, map[string]any{"name": docName(".exe")}); !errors.Is(err, documents.ErrSidecarUnavailable) { + t.Fatalf("形态合法但无对应 sidecar → %v, want documents.ErrSidecarUnavailable", err) + } +} + +// TestDocumentReadTool_MissingSidecarIsHonest 钉住③（缺失）与「只读 sidecar，绝不重抽」： +// 没有 sidecar 时给的是诚实错误，而不是空正文、也不是回头重抽原文件。 +func TestDocumentReadTool_MissingSidecarIsHonest(t *testing.T) { + t.Parallel() + fx := newDocReadFixture(t) + name := docName(".txt") + tool := fx.tool(t) + + if _, err := callDocRead(t, tool, map[string]any{"name": name}); !errors.Is(err, documents.ErrSidecarUnavailable) { + t.Fatalf("无 sidecar → %v, want documents.ErrSidecarUnavailable", err) + } + // 抽取过、随后 sidecar 被清掉：原文件仍在，但工具**绝不**因此回头重抽。 + _, injected := fx.extract(t, name, "正文在 sidecar 里。\n") + if err := os.Remove(fx.sidecarPath(name)); err != nil { + t.Fatalf("删除 sidecar: %v", err) + } + if _, err := callDocRead(t, tool, map[string]any{"name": name}); !errors.Is(err, documents.ErrSidecarUnavailable) { + t.Fatalf("sidecar 被清掉后 → %v, want documents.ErrSidecarUnavailable（不得回退重抽）", err) + } + if injected == "" { + t.Fatal("夹具前提：抽取应当产出正文") + } +} + +// TestDocumentReadTool_UnreadableIsHonest 钉住③（unreadable）：sidecar 的结论是读不到正文 +// 时，工具给的是**带原因的**诚实错误，而不是空正文假装成功。 +func TestDocumentReadTool_UnreadableIsHonest(t *testing.T) { + t.Parallel() + fx := newDocReadFixture(t) + name := docName(".pdf") + ref, _ := fx.extract(t, name, "%PDF-1.7\n") + if ref.Status != history.DocumentStatusUnreadable { + t.Fatalf("夹具前提不成立：status = %q, want %q", ref.Status, history.DocumentStatusUnreadable) + } + _, err := callDocRead(t, fx.tool(t), map[string]any{"name": name}) + if !errors.Is(err, ErrDocumentUnreadable) { + t.Fatalf("unreadable → %v, want ErrDocumentUnreadable", err) + } + // 抽取侧给的原因短句必须抵达错误文案（那是模型/用户唯一能看到的解释）；这里断言的 + // 是全部原因文案共有的前缀，不是某一句具体措辞。 + if !strings.Contains(err.Error(), "无法抽取正文") { + t.Fatalf("错误文案没带上抽取侧的原因：%v", err) + } +} + +// TestDocumentReadTool_TextExcludesMetadataLine 钉住⑥：sidecar 第一行的元数据绝不混进 +// text（正文自第二行起），返回的正文与装配期注入的正文逐字相同。 +func TestDocumentReadTool_TextExcludesMetadataLine(t *testing.T) { + t.Parallel() + fx := newDocReadFixture(t) + name := docName(".txt") + body := "正文第一行\n正文第二行\n" + _, injected := fx.extract(t, name, body) + if injected != body { + t.Fatalf("夹具前提：注入正文 = %q, want %q", injected, body) + } + got, err := callDocRead(t, fx.tool(t), map[string]any{"name": name}) + if err != nil { + t.Fatalf("读取: %v", err) + } + if got.Text != injected { + t.Fatalf("text = %q, want 注入正文 %q", got.Text, injected) + } + // 磁盘上的 sidecar 确实带一行元数据（否则上面的相等只是「本来就没有元数据」的假绿）。 + raw, err := os.ReadFile(fx.sidecarPath(name)) + if err != nil { + t.Fatalf("读 sidecar: %v", err) + } + if !strings.HasPrefix(string(raw), "{") || !strings.Contains(string(raw), "\n") { + t.Fatalf("sidecar 首行不是元数据：%q", string(raw)) + } + for _, leak := range []string{`"status"`, `"v":`, `"chars"`} { + if strings.Contains(got.Text, leak) { + t.Fatalf("text 混进了 sidecar 元数据（含 %s）：%q", leak, got.Text) + } + } +} + +// TestDocumentReadTool_ManifestCursorAndCSVSummary 钉住与上游的两处成对契约： +// - CSV 的摘要行属于正文坐标系（offset 0 = 摘要行开头），与装配期注入的正文一致； +// - 清单行给的续读游标（= 已注入字符数）可以原样传进来：读到末尾不报错，并如实标注 +// 抽取期的截断（extractTruncated）—— 抽取期预算之外的内容**不在 sidecar 里** +// （design/24 §9.6 第 3 条），这条事实必须让模型看得见。 +func TestDocumentReadTool_ManifestCursorAndCSVSummary(t *testing.T) { + t.Parallel() + fx := newDocReadFixture(t) + tool := fx.tool(t) + + csv := docName(".csv") + _, injectedCSV := fx.extract(t, csv, "a,b\n1,2\n3,4\n") + if !strings.HasPrefix(injectedCSV, "[CSV") { + t.Fatalf("CSV 夹具应当带摘要行：%q", injectedCSV) + } + gotCSV, err := callDocRead(t, tool, map[string]any{"name": csv}) + if err != nil { + t.Fatalf("读 CSV: %v", err) + } + if gotCSV.Text != injectedCSV { + t.Fatalf("CSV text = %q, want 含摘要行的注入正文 %q", gotCSV.Text, injectedCSV) + } + + big := docName(".txt") + ref, _ := fx.extract(t, big, strings.Repeat("宽", documents.MaxExtractChars+10)) + if !ref.Truncated || ref.Chars != documents.MaxExtractChars { + t.Fatalf("夹具前提：ref = %+v, want 抽取期已截断到 %d 字符", ref, documents.MaxExtractChars) + } + atCursor, err := callDocRead(t, tool, map[string]any{"name": big, "offset": ref.Chars}) + if err != nil { + t.Fatalf("按清单游标读取: %v", err) + } + if atCursor.TotalChars != ref.Chars || atCursor.Text != "" || atCursor.Truncated || atCursor.NextOffset != 0 { + t.Fatalf("按清单游标读取 = %+v, want 读到抽取正文末尾（totalChars %d）", atCursor, ref.Chars) + } + if !atCursor.ExtractTruncated { + t.Fatal("抽取期的截断事实没有如实回给模型（extractTruncated=false）") + } +} + +// TestDocumentReadTool_OwnerOnlyByDefault 钉住⑤：工具以**默认最严**的可达性标记注册 +// （tool_policies 无行 = 两者皆 false = owner-only），因此群聊/陌生人会话在默认策略下既 +// 看不到也调不到它（design/24 §5 红线）。注册走的是既有工具同一条路径 +// （dispatcher.Register → registry.RegisterTool），因此它同样受 CAPACITY_TOOL_SETS 裁剪。 +func TestDocumentReadTool_OwnerOnlyByDefault(t *testing.T) { + t.Parallel() + fx := newDocReadFixture(t) + reg := registry.New() + dispatcher, err := tool.New(reg) + if err != nil { + t.Fatalf("tool.New: %v", err) + } + for _, tl := range buildTools(t, &config.Config{DataDir: fx.dataDir}) { + if rerr := dispatcher.Register(tl); rerr != nil { + t.Fatalf("注册 %q: %v", tl.Name(), rerr) + } + } + cap, err := reg.Get(documentReadToolName) + if err != nil { + t.Fatalf("%q 未注册: %v", documentReadToolName, err) + } + if cap.Kind != registry.KindTool { + t.Fatalf("kind = %q, want %q", cap.Kind, registry.KindTool) + } + if cap.Policy.AllowInGroup || cap.Policy.AllowInStranger { + t.Fatalf("默认可达性标记 = %+v, want 两者皆 false（最严）", cap.Policy) + } + for _, tc := range []struct { + name string + env restrict.ActorEnv + want bool + }{ + {"owner", restrict.ActorOwner, true}, + {"group", restrict.ActorGroupMember, false}, + {"stranger", restrict.ActorStranger, false}, + } { + if got := restrict.SetContext(reg, tc.env).Allow(documentReadToolName); got != tc.want { + t.Fatalf("%s 环境 Allow = %v, want %v", tc.name, got, tc.want) + } + // 循环真正用的那道门（dispatcher 的策略引擎）必须与策略引擎同一结论。 + if got := dispatcher.PolicyEngine(tc.env).Allow(documentReadToolName); got != tc.want { + t.Fatalf("%s 环境 PolicyEngine().Allow = %v, want %v", tc.name, got, tc.want) + } + } +} diff --git a/plugins/tools/io/tools.go b/plugins/tools/io/tools.go index acf753f..66b8bb7 100644 --- a/plugins/tools/io/tools.go +++ b/plugins/tools/io/tools.go @@ -210,6 +210,7 @@ func (t *tools) build() []sdk.Tool { newWebSearchTool(t), newWebFetchTool(t), newKnowledgeTool(t), + newDocumentReadTool(t), } } diff --git a/plugins/tools/io/tools_test.go b/plugins/tools/io/tools_test.go index 4dff4e9..d83b231 100644 --- a/plugins/tools/io/tools_test.go +++ b/plugins/tools/io/tools_test.go @@ -15,10 +15,10 @@ func TestTools_ReturnsEveryTool(t *testing.T) { if err != nil { t.Fatalf("New: %v", err) } - if len(set) != 6 { - t.Fatalf("expected 6 tools, got %d", len(set)) + if len(set) != 7 { + t.Fatalf("expected 7 tools, got %d", len(set)) } - want := []string{"file", "image-crop", "http", "web-search", "web-fetch", "knowledge"} + want := []string{"file", "image-crop", "http", "web-search", "web-fetch", "knowledge", "document-read"} seen := map[string]bool{} for _, tool := range set { seen[tool.Name()] = true @@ -53,7 +53,7 @@ func TestRegister_RegistersEveryTool(t *testing.T) { if err := Register(reg); err != nil { t.Fatalf("Register: %v", err) } - for _, name := range []string{"file", "image-crop", "http", "web-search", "web-fetch", "knowledge"} { + for _, name := range []string{"file", "image-crop", "http", "web-search", "web-fetch", "knowledge", "document-read"} { c, err := reg.Get(name) if err != nil { t.Fatalf("Get(%q): %v", name, err)