AskaEth
3589f4b14f
新增 plugins/tools/io/file_targets.go：fileTool 与 cropTool 实现 tool.FileTargeter （编译期钉住 var _ tool.FileTargeter，声明集中一处可审计）。 file：read/list/search ⇒ 读；其余（含 delete / 未知 / 缺失 action）⇒ 写（保守侧，宁可多挡一次）。 路径取沙箱解析前的声明值（绝对、clean、已确认在 roots 内，纯词法不触盘）；沙箱会拒的路径不声明。 search 的缺省 base 与执行路径共用 f.searchBase（避免声明目录 ≠ 实际走查目录）。 image-crop：仅本地路径声明为读（URL/data URI 不落盘）；分类与 load 共用一份。 体检清单：file ✅ / image-crop ✅ / document-read ❌（sidecar 走「临时文件 + rename」原子替换， 无撕读风险；且布局属未导出的第二份真相）/ basic、http、knowledge 等不碰盘； vision·ocr（internal 越界）、terminal（cmd 越界 + 目标不可知）、MCP 外部工具 未做 —— 如实登记为遗留。 测试：单元（action→Op 全表 / 路径归一 / 不声明场景）+ 机制层 6 条（真插件 + 真 Dispatcher + 真占用表， 用闸门工具把并发变确定性事件，不靠 sleep）。 变异 5 条（一切按写 / 未知按读 / 用原始相对串 / crop 不声明 / file 声明被抹掉）。 注：本切片声明正确但生效依赖 ef3dcb6（网关给每条在途路挂互斥身份）。
41 lines
2.3 KiB
Go
41 lines
2.3 KiB
Go
// Package io implements the built-in I/O and network tools for Cyrene v2
|
|
// (DevDocs/design/09-插件生态.md). It exposes file, image-crop, document-read, http,
|
|
// web-search, web-fetch and knowledge as pkg/plugins/sdk.Tool values, wired to the
|
|
// process-internal config, logger and runtime/memory retriever.
|
|
//
|
|
// Build the full configured tool set with New(cfg, opts...). Tools() and
|
|
// Register(reg) are convenience wrappers that use platform defaults; production
|
|
// wiring should call New(cfg, opts...) so the tools honor the real DataDir,
|
|
// search endpoint and knowledge retriever.
|
|
//
|
|
// Security constraints
|
|
//
|
|
// - file: every path is cleaned and validated to stay inside the configured
|
|
// data directory or an explicit whitelist; ".." traversal and symlink escape
|
|
// are rejected; reads and writes are size-capped.
|
|
// - image-crop: crops a region out of a large image so the agent can read it in
|
|
// parts (an image service downsamples big images); path sources go through the
|
|
// file sandbox, URL sources through the SSRF guard, and the returned data URI
|
|
// is size-capped.
|
|
// - http: GET/POST only, timeouts, response truncation and SSRF protection
|
|
// (loopback/private/link-local addresses and localhost are refused unless
|
|
// the host is on an explicit allowlist).
|
|
// - web-search: requires a configured search endpoint, otherwise a clear error.
|
|
// - web-fetch: size- and content-type-limited readable text extraction.
|
|
// - knowledge: RAG lookup over the runtime memory retriever; a clear message
|
|
// when no knowledge base is configured.
|
|
//
|
|
// File-level mutual exclusion
|
|
//
|
|
// The two tools that touch files declare the file each call will touch
|
|
// (tool.FileTargeter, implemented in file_targets.go): file declares read for
|
|
// read/list/search and write for write; image-crop declares a read when its image
|
|
// is a local path. When another in-flight parallel leg is already operating on that
|
|
// same file, the call returns tool.ErrFileBusy with the file's state instead of
|
|
// running or queueing; two reads of one file still run in parallel, and calls that
|
|
// cannot touch a file (a sandbox-rejected path, an HTTP or data: URI source) declare
|
|
// nothing and keep their previous behavior.
|
|
//
|
|
// All tools are safe for concurrent use, as required by sdk.Tool.
|
|
package io
|