Documentation
¶
Overview ¶
Package tools 是 einox 通用工具面基设：类型化工具构造（InferTool——结构体 反射出参数 JSON Schema，schema 推断复用 eino 反射器保证与既有工具面完全 同构）与通用工具族（fs/todo/web/时间/问答/命令/补丁，自原 ext/tools 迁入）。 统一形态：NewXxxTools(cfg) ([]contract.Tool, error)；失败容忍策略由应用 装配层决定；写面审批由基座 hitl 组装期包装，工具内不落审批语义。
Index ¶
- func CheckTopDirs(what string, dirs []string) error
- func DiffToolOf(t contract.Tool, diff func(args string) string) contract.Tool
- func Fail(msg string) map[string]any
- func InferTool[T, D any](name, desc string, fn func(ctx context.Context, in T) (D, error)) (contract.Tool, error)
- func ParamsOf(sc *contract.Schema) *schema.ParamsOneOf
- func PathBlocked(rel string, dirs []string) bool
- func ResolveUnder(root, p string) (string, error)
- func SchemaOf(po *schema.ParamsOneOf) *contract.Schema
- func ValidTopDir(name string) bool
- func WithBehavior(t contract.Tool, behavior string) contract.Tool
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CheckTopDirs ¶ added in v0.4.0
CheckTopDirs 清单条目逐一过 ValidTopDir；what = 配置字段名（错误文案定位 用）。构造期 fail-fast——配置意图非法即拒，不拖到运行时（对齐 SessionToolsOff / DenyTools 纪律）。
func DiffToolOf ¶
DiffToolOf 包装（diff = 参数 JSON → diff 文本；不改 Info/Invoke 行为）。
func Fail ¶ added in v0.5.0
Fail 工具失败信封（{"ok":false,"error":…}——mid.ToolResultDigest 判红的 软契约形态）。七个工具包各自同名的本地 fail() 与手拼 JSON 的两处 （mid 硬上限信封、engine 悬空调回执）曾各写（审查 P2-11——手拼一旦文案 带引号即产非法 JSON），此处单点。
func InferTool ¶
func InferTool[T, D any](name, desc string, fn func(ctx context.Context, in T) (D, error)) (contract.Tool, error)
InferTool 类型化工具构造：In 结构体反射出参数 schema（json/jsonschema tag 语义与 eino utils.InferTool 完全一致——内部即其反射器），fn 返回值 JSON 序列化为工具结果。挂起 = fn 返回 *contract.Suspend（适配层转引擎中断）。
func ParamsOf ¶ added in v0.5.0
func ParamsOf(sc *contract.Schema) *schema.ParamsOneOf
ParamsOf contract.Schema → eino ParamsOneOf（反向转换，与 SchemaOf 成对； nil 入参 = nil 返回）。失败 nil——schema 是描述面，工具仍可用。
func PathBlocked ¶ added in v0.4.0
PathBlocked 写区命中判定：rel = 工作区内相对路径，dirs = 顶层子目录名清单 （调用方已过 CheckTopDirs）。命中 = 目标为保护区本身或其子路径；rel 归一 为 "."（工作区根）时非空清单即命中——根是所有顶层区的祖先。归一覆盖 ./ 前缀与平台分隔符（Clean + ToSlash；Linux 下反斜杠是合法文件名字符、不视作 分隔符——与 fsutil/applypatch 既有路径解析语义一致，Windows 模型输出的 反斜杠形态在 Windows 宿主上命中）。大小写折叠匹配（安全审查 2026-09-06）： macOS/Windows 默认大小写不敏感文件系统上「Docs/」会落进 protect=["docs"] 的真实目录，字节级比较即旁路；大小写敏感文件系统上折叠只会多拦不会漏 （收紧方向，可接受）。
func ResolveUnder ¶ added in v0.5.0
ResolveUnder 工作区路径圈禁（防穿越）单点实现：fsutil（读删检索）、office （文档族写）、applypatch（补丁写）、einoext/extwire（本地算子）四家共用—— 曾四份两算法（Join+Rel 三份逐字拷贝 + applypatch 子串拒绝误伤 a..b.txt 致 同一文件可读不可改，审查 P1-5）。语义：空白路径与 "." 归根；词法圈禁 （Join 清洗后逃出 root 显式拒绝）+ 符号链接圈禁（目标现存祖先经 EvalSymlinks 解析后仍在 root 内才放行——区内指向区外的 symlink 即拒， 写面沿链接写出工作区的逃逸面闭合）。fail-closed，未列明的形态不侥幸 放行。已知残留窗口：检查通过后到实际打开前并发创建的 symlink 不在此拦 （并发对抗需 openat/O_NOFOLLOW 级改造，超出库基座形态——沙箱是第二层）。
func SchemaOf ¶ added in v0.5.0
func SchemaOf(po *schema.ParamsOneOf) *contract.Schema
SchemaOf eino ParamsOneOf → contract.Schema（JSON 往返最小子集投影；失败 nil——schema 是描述面，工具仍可用）。与 einoext 反向转换（adapt.go）成对 三处收敛的单点（审查 P2-9：曾三份各写）。
func ValidTopDir ¶ added in v0.4.0
ValidTopDir 顶层子目录名围栏（工作区相对、单段）：非空、非 . / ..、不含 路径分隔符与 ..。WorkspaceKeep/WorkspaceProtect（engine.Options）与 fsutil/applypatch 的 ProtectDirs 共用——持久区与写区一律顶层粒度，嵌套 子树留待真实需求再议（YAGNI）。
Types ¶
This section is empty.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package applypatch 提供 apply_patch 工具：codex `*** Begin Patch` 格式的 解析与应用（多文件 增/改/删/改名，事务性——任一失败全部不落盘）。
|
Package applypatch 提供 apply_patch 工具：codex `*** Begin Patch` 格式的 解析与应用（多文件 增/改/删/改名，事务性——任一失败全部不落盘）。 |
|
Package askuser 提供 ask_user 工具：长任务中途向用户结构化提问（单选/ 多选/自由文本），经挂起-续流通道（contract.Suspend 哨兵 → 适配层转引擎 Interrupt×Resume）。
|
Package askuser 提供 ask_user 工具：长任务中途向用户结构化提问（单选/ 多选/自由文本），经挂起-续流通道（contract.Suspend 哨兵 → 适配层转引擎 Interrupt×Resume）。 |
|
Package currenttime 提供 get_current_time 工具：时钟/周界语义——周报周期 与 deadline 计算的正确性底线。
|
Package currenttime 提供 get_current_time 工具：时钟/周界语义——周报周期 与 deadline 计算的正确性底线。 |
|
Package egress 提供工具层网络出口治理（Phase S-9——2026-08-26 沙箱设计定案 §9；移植蓝本 = nanobot nanobot/security/network.py，344 行 Python 的 Go 直译 收敛）。
|
Package egress 提供工具层网络出口治理（Phase S-9——2026-08-26 沙箱设计定案 §9；移植蓝本 = nanobot nanobot/security/network.py，344 行 Python 的 Go 直译 收敛）。 |
|
Package fsutil 提供工作区文件工具四件：read_file / list_dir / search_files / delete_file（读-搜为主 + 显式删除——删除走审批卡直白话，比拼 rm 命令可控； 内容写面归 applypatch / str_replace_editor / runcommand）。
|
Package fsutil 提供工作区文件工具四件：read_file / list_dir / search_files / delete_file（读-搜为主 + 显式删除——删除走审批卡直白话，比拼 rm 命令可控； 内容写面归 applypatch / str_replace_editor / runcommand）。 |
|
Package office 提供 office 文档读写工具族（2026-08-25 裁决：office 读写是 通用能力，归基座）：read_xlsx / write_xlsx / read_docx / write_docx / read_pptx。
|
Package office 提供 office 文档读写工具族（2026-08-25 裁决：office 读写是 通用能力，归基座）：read_xlsx / write_xlsx / read_docx / write_docx / read_pptx。 |
|
Package plan 提供 submit_plan 工具：计划文档提交（用户域 plans/<sid>/ <seq>.md 持久落盘）+ 挂起送审（Suspend → 引擎转 plan_request 事件卡 → approve 端点决议 → Resume 消费）。
|
Package plan 提供 submit_plan 工具：计划文档提交（用户域 plans/<sid>/ <seq>.md 持久落盘）+ 挂起送审（Suspend → 引擎转 plan_request 事件卡 → approve 端点决议 → Resume 消费）。 |
|
Package runcommand 提供 run_command 工具：工作区内 shell 命令执行（P1b 简版——超时/输出头尾截断/cwd 圈进工作区；后台任务形态 P2 随编码子代理）。
|
Package runcommand 提供 run_command 工具：工作区内 shell 命令执行（P1b 简版——超时/输出头尾截断/cwd 圈进工作区；后台任务形态 P2 随编码子代理）。 |
|
Package todo 提供 todo_write 任务清单工具：多步任务的自跟踪与用户可见 进度。
|
Package todo 提供 todo_write 任务清单工具：多步任务的自跟踪与用户可见 进度。 |
|
Package webfetch 提供 web_fetch 工具：URL → 正文 markdown 提取（httprequest 只回裸 HTML，真实网页数百 KB 直接爆上下文——本工具做「提取」而非「全文」）。
|
Package webfetch 提供 web_fetch 工具：URL → 正文 markdown 提取（httprequest 只回裸 HTML，真实网页数百 KB 直接爆上下文——本工具做「提取」而非「全文」）。 |