read-external

flavor-code 项目插件：提供只读工具 read_external，用于访问工作区之外的文件。 内置 Read 受工作区边界限制读不到目标文件时（例如另一个仓库、临时目录、系统配置），用本工具读取。

注册能力

• 斜杠命令 /read-external <文件路径> [起始行] [结束行]（用户手动调用）
  • 相对路径按当前工作区解析；成功输出文件元信息 + 内容，失败输出「读取失败: …」提示（不抛错）
  • 安全边界与工具完全一致（共用 read-external.mjs 核心逻辑）
• 工具 read_external（readOnly: true，与 Read/Glob/Grep 同级免审批；agent 自动调用）
  • path（必填）：绝对路径，或相对当前工作目录的路径
  • maxBytes（可选）：读取上限，默认 1 MiB，硬上限 10 MiB
  • startLine / endLine（可选）：1 基闭区间行号（作用于已读入的内容）
  • 返回：{ path, sizeBytes, readBytes, truncated, firstLine, lastLine, content }

安全边界（内置拒绝名单，不可配置）

读取前对 realpath 解析后的路径做检查，命中即拒绝：

• 路径段位于凭据目录：.ssh/、.aws/、.gnupg/、.azure/
• .env* 环境密钥文件（豁免 .env.example）
• SSH 私钥：id_rsa / id_ed25519 / id_ecdsa / id_dsa 及其 -/_ 后缀变体（豁免 .pub）
• 凭据文件：.netrc、_netrc、.npmrc、.pgpass、git-credentials、credentials
• 私钥/证书扩展名：.pem、.key、.p12、.pfx、.kdbx
• 二进制防护：内容含 NUL 字节或非 UTF-8 一律拒绝（截断切断多字节尾部的情况会自动回退最多 3 字节重试）
• 只读：仅 stat/open("r")，无任何写路径；目录与非普通文件拒绝

开发与验证

node scripts/check.mjs

零依赖离线检查：清单结构、输入校验、拒绝名单命中/豁免、真实临时文件的读取/行区间/截断/二进制用例、activate 冒烟与 ToolDefinition 契约。

说明

• 插件依赖宿主默认的 in-process 加载（production.ts 中 sandbox 缺省关闭），因此可直接使用 node:fs，与 astgraph 同模式；若未来开启 Worker/vm 沙箱需改为宿主中介的 filesystem 服务。
• .flavor/ 整目录被 git 忽略，本插件为工作区本地能力，不随仓库分发。
• 曾以 RegisterTool 创建的旧 managed 工具 read_external 已删除，避免同名注册冲突。