[542474846]

变更说明 / Description

背景与动机 / Context and motivation

静态审计确认的文件工具失败机制：提示词与实现不对齐（32KB 截断未文档化、read_file 输出的行号前缀污染 edit 匹配、environment 支持矩阵失实）；edit_file/apply_file 的模糊匹配没有精确快路径，0.9 相似度的多候选静默取最优，报错还指向不存在的工具名；read_file_binary 的内容根本到不了模型；工作区零防护，任意绝对路径直接执行且递归删除没有危险路径底线；工具调用没有审查机制。失败率居高导致模型绕开文件工具改用终端脚本改文件。

改动范围 / Changes

八个阶段，落在一个分支，计划与逐阶段实施记录见 docs/TODO/chat_file_tool_hardening/：

• A 描述规范化：可见与内部文件工具补 details（environment 真实矩阵、成功返回、失败类别与修法、工具分工），修正幽灵工具名与误导文案
• B 读取上限与健壮性：read 族 32MB 硬上限并引导 read_file_part 分段、read_file_part 改单次流式扫描、isTextLike 二进制门禁、截断判定修复、read_file_binary 内容直达模型
• C 编辑引擎重构：精确匹配快路径、近似多候选按行区间拒绝并列出候选行号与相似度（绝不静默选第一处）、剥离 read_file 行号前缀、新增 occurrence 参数、成功回传匹配行号、失败给出最高相似度候选引导精读；删除 [START-REPLACE] 死代码链
• D 工作区防护：区内按既有权限模式；区外 ALLOW/ASK 强制弹窗列出目标路径，FORBID 直接拒绝；判定先于 deny_tool 标记，不可被模型文本绕过；未绑定工作区一律按区外；扩展包限定名同族纳管；delete_file 对 /、/sdcard、/data 等危险根硬拦截；JS 包嵌套调用经 AIToolHook 兜底
• E 大模型审查：FunctionType.TOOL_REVIEW 功能模型 + 审查 prompt（工具名、操作类别、目标路径、区内外、内容摘要、call_purpose 调用说明）+ ToolReviewService（15s 超时）；合规直接执行、不合规弹窗由用户决定、审查失败弹窗提示错误
• F 环境矩阵与扩展通道：repo: 环境 clean guard、applyFile 按环境路由（linux 支持 ~）、edit_file occurrence 透传、grep_code 在 linux 下经 PathMapper 映射到宿主 rootfs 扫描并反向映射、SAF 白名单报错列全扩展名、禁用包报错给出真实原因
• G 高危工具审查泛化：HighRiskToolCatalog 纳管 18 个高危工具族，审查开关扩展为三分区（区内文件 / 区外文件 / 高危工具），call_purpose 由执行层剥离
• H AI 读取提炼：read 族默认经 FILE_DISTILL 功能模型返回带行号的相关摘录（part 与大文件逐块扫描，worth=false 或摘录占比超 0.6 回原文）；开关关、raw=true、repo: 环境、特殊类型抽取管线、≤2048 字节一律透传；失败显式报错指引 raw=true 重读
• 构建修复：补全 avator/dragonbones/consumer-rules.pro 占位，模块 build.gradle.kts 的 consumerProguardFiles 引用此前指向不存在的文件

不包含：聊天列表滚动实现调整（独立改动）、token 统计改动。

兼容性与风险 / Compatibility and risks

• 行为变更，均为已确认决策：区外与未绑定工作区的文件操作一律强制弹窗或直接拒绝；审查不合规由用户决定是否放行；审查失败弹窗并显示错误信息
• 新开关默认值：file_distill_enabled 默认开，审查三开关默认关。开启审查或 AI 提炼会对功能模型产生额外调用与 token 消耗，需用户在功能配置中指定 FILE_DISTILL / TOOL_REVIEW 模型，未配置时回落主模型
• 工具 schema 变更：edit_file/apply_file 新增 occurrence 参数，copy_file 的 recursive 默认 true→false 与文档对齐
• 同步更新 8 个语言目录 strings、assets/packages/extended_file_tools.js、examples/types/files.d.ts
• 无 Room 迁移、无数据库结构与导出格式变化

关联 Issue / Related issue

N/A。改动来源为本地静态审计，背景与实施记录见 docs/TODO/chat_file_tool_hardening/index.md。

验证方式 / Verification

检查或命令：./gradlew :app:compileDebugKotlin
            ./gradlew :app:testDebugUnitTest --tests "*FileBindingServiceTest" --tests "*WorkspacePathCheckerTest"
环境与变体：Android debug 变体
结果：`:app:compileDebugKotlin` 通过（exit 0）。环境：JAVA_HOME 指向 Android Studio JBR，Gradle 8.13 / AGP 8.13.2，debug 变体；排除 `:app:syncSttModelAssets`（该任务每次强制重新下载 STT 模型，本机到下载源不可达会以 ConnectException 中断，与 Kotlin 编译无关）。单元测试未在本机执行，交由 CI。

手工回归矩阵（记录于 TODO index，结果待填）：区内/区外/无工作区 × 允许/询问/禁止 × 审查开/关 × 合规/不合规/失败；高危工具 execute_shell × 高危开关独立生效；32MB 大文件读取、read_file_part 分页、edit_file 行号粘贴/多候选/occurrence、扩展包 file_exists、禁用包报错、repo: guard。

检查清单 / Checklist

• 我已记录可复现验证和未运行项原因 / Reproducible verification and reasons for unrun checks are recorded
• 日常开发 PR 的目标分支为 dev；如目标为 main，我已说明这是维护者发布同步 / The target branch is dev for regular work; if it is main, I explained why this is a maintainer-led release sync
• 我已确认 Candidate checks 覆盖改动范围，并会处理技术失败项 / Candidate checks covers the change scope and technical failures will be addressed
• 最终 diff 无无关、临时、生成、二进制或敏感内容 / Final diff has no unrelated, temporary, generated, binary, or secret content
• 已提供对应的回归、UI、文档/字符串或兼容性证据 / Relevant regression, UI, docs/strings, or compatibility evidence is provided

[CATMIAOZHI]

审计结论：❌ 请求修改

改动（52 个文件，+4151/−582）：文件工具八阶段强化：描述规范化、读取 32MB 上限与流式分段、edit/apply 引擎重构（精确快路径 + 多候选拒绝 + occurrence）、工作区防护与危险根删除底线、大模型合规审查（TOOL_REVIEW）、环境矩阵与扩展通道、高危工具审查泛化、read 族 AI 提炼（FILE_DISTILL，默认开）。

通过的检查：

• 目标分支 dev，非草稿，非自审（作者 542474846）；PR 描述与 diff 基本一致（52 文件与 API 计数一致；早前一次 stale origin/dev 导致的 terminal 子模块差异已核实不在本 PR 内）
• 工作区判定：android 路径用 canonicalPath 前缀比较（/data/ws 与 /data/ws2 不会混淆）；未绑定工作区一律按区外；判定先于 deny_tool 标记
• 审查失败 fail-closed：超时/解析失败/未配置均走弹窗人工确认，不静默放行；未配置功能模型时回落主模型（FunctionalConfigManager defaultMapping 覆盖全部 FunctionType）
• call_purpose 仅供审查读取、执行前剥离；Hook 注册幂等，主链路执行走直接 executor、不重跑拦截，与嵌套兜底不重叠
• 读取侧：32MB 硬上限覆盖 read_file/read_file_full/read_file_binary 及 SAF/Linux 路径；read_file_part 单次流式扫描；截断判定改为"读满且还有下一字符"；二进制门禁与 base64 预算；特殊类型抽取管线透传
• 旧 [START-REPLACE] 死代码链删除干净，无残留调用方；ToolRuntimeContext 由 data class 改为普通类，无 copy/判等使用方
• copy_file recursive 默认 true→false 与文档对齐（行为变更已在 PR 描述中声明）

问题：

1. [P1] 危险根递归删除硬底线可被路径拼写绕过：WorkspacePathChecker.isDangerousRecursiveDeleteTarget 只做 trim + 去尾部 / 后的精确字符串匹配，不做 canonicalize；两个调用点（StandardFileSystemTools.deleteFile、LinuxFileSystemTools.deleteFile）都直接传模型原始 path。/sdcard/.、/sdcard/..、//sdcard、/storage/emulated/0/. 均不在集合内，但指向同一目录，deleteRecursively() 会真的清空。测试也只覆盖精确拼写。建议：比较前先取 File(path).canonicalPath（不存在的路径做规范化处理），并把 /.、.. 这类变体补进单测。
2. [P1] linux 环境 grep 的 .. 可逃出 proot rootfs：LinuxFileSystemTools.grepCode 把模型传的 linux 路径经 PathMapper.resolvePath → mapLinuxPath（File(ubuntuRoot, relativePath).absolutePath，不 canonicalize、不做 containment 校验）交给宿主 native ripgrep；validateLinuxPath 只校验以 //~ 开头，不拦 ..。grep_code(path=/../../../../data/..., environment=linux) 可扫描宿主文件系统；且工作区判定把"环境一致"视为区内，不会弹窗。建议：映射后 canonicalize 并校验仍在 ubuntuRoot 内，否则拒绝；同类问题也存在于 zip/unzip 既有用 resolvePath 的路径上，建议一并收敛到 mapLinuxPath 内。
3. [P1] FunctionTypeTest 与新枚举不一致，测试必失败：枚举现有 13 个值（新增 TOOL_REVIEW、FILE_DISTILL），测试断言总数 12 且 expected 列表漏了 FILE_DISTILL。作者自述单元测试未在本地执行、交由 CI，CI 会红。建议：总数改为 13 并补 FILE_DISTILL，本地跑一次 :app:testDebugUnitTest。
4. [P2] occurrence 的 schema default 与实现矛盾：edit_file/apply_file 的 ToolParameterSchema 写 default = "1"（中英文两处），而实现把"未传 occurrence"当作 null、多候选一律拒绝；JSON-schema 的 default 不会被 API 自动注入，实际行为是拒绝，与 details 里"命中多处会被拒绝"的说明直接冲突。建议：去掉 default="1"，说明统一为"未传则拒绝"。
5. [P2] 嵌套调用的高危工具不受 Hook 约束：WorkspaceFileToolHook 只拦截文件工具族；JS 扩展包经 toolCall → AIToolHandler.executeTool 嵌套调用 execute_shell/http_request 等高危工具时，Hook 直接放行，也不经过主链路的审查/弹窗（主链路只审了外层包工具）。建议：说明该缺口在设计预期内，或把高危工具族也纳入 Hook 的拒绝范围。
6. [P2] read_file_part 在 end_line < start_line 时静默返回空成功：requestedCount 被 coerceAtLeast(0)，0 行时返回 success 空内容；旧实现会把 end_line 钳到有效范围返回实际内容。模型传错范围时得不到纠错信号。建议：非法范围改为显式失败并提示有效范围。
7. [P3] i18n 不同步：PR 描述称"同步更新 8 个语言目录 strings"，但 8 条新审查/工作区文案只存在于默认 values/，values-en 只有 4 条 function_type/file_distill 文案，其余 6 个语言目录各 2 条；非中文语言下弹窗与菜单会回退显示中文（不崩溃）。建议补齐各语言翻译或至少英文。
8. [P3] 模糊匹配聚类的传递闭包可能合并相邻重复块：clusterOverlappingWindows 按行区间重叠做传递闭包聚类，相邻的近似重复块可被一串重叠窗口桥接成一个簇、只保留最优窗。精确重复由精确路径兜底（列出全部位置并拒绝），残余风险限于"非精确的近似重复且相邻"的情形。
9. [P3] linux grep 反向映射失败时回落返回宿主原始路径：mapAndroidPathToLinux 返回 null 时调用方保留 fileMatch 原路径（宿主 rootfs 绝对路径），会把宿主内部路径暴露给模型，且模型后续可能拿它当 linux 路径用。建议：映射失败时丢弃该条或标注清楚。
10. [P3] CDATA 内 diff 若含 ]]> 会破坏 XML：FileApplyResultData 把 diff 原文直接放进 CDATA（旧的"转义"链本就是恒等替换，无回归），含 ]]> 的代码 diff 会提前闭合 CDATA。建议：对 ]]> 做分段处理或转义。

后续可跟进（不阻塞）：

• [question] 手工回归矩阵（区内/区外/无工作区 × 允许/询问/禁止 × 审查开/关 × 合规/不合规/失败等）在 TODO index 中"结果待填"，是否计划合入前补齐实测结果？
• [question] file_distill_enabled 默认开启且 focus 必填：现有角色卡/子任务/自动化流程中不带 focus 的 read 调用会改为显式失败（指引 raw=true），是否确认这是期望的默认行为？

验证说明：作者称 :app:compileDebugKotlin 通过（exit 0），单元测试未在本地执行、交由 CI；手工回归矩阵结果待填。结合问题 3（FunctionTypeTest 计数错误），建议合入前本地跑一次 :app:testDebugUnitTest 并补齐回归矩阵。

由 水晴喵的muse 审计

[542474846]

感谢审计，问题均已处理（commit b2c416c9 + ab346982），并按建议在本地跑通了完整单测套件。逐项回复：

P1-1 危险根拼写绕过 — 已修。isDangerousRecursiveDeleteTarget 在比较前先做词法规范化（lexicallyNormalizePath：消解 ./../重复斜杠，纯字符串运算，测试可跨平台断言），再做 canonicalPath（覆盖符号链接），两道比较任一命中即拒绝；调用点无需改动。补充说明：canonicalPath 的分隔符随平台变化（Windows 桌面 JVM 为 \），isAndroidPathInside 的前缀比较同样做了分隔符归一——Android 设备上 canonicalPath 本就用 /，归一是 no-op。测试补了 9 个拼写变体；其中我最初写的 /storage/emulated/0/../storage/emulated/0 是错误用例（.. 只回退一级，该路径本就不在根集合内），已换成真正回到受保护根的 /storage/emulated/0/..。

P1-2 linux grep .. 逃出 rootfs — 已修。mapLinuxPath 拼接结果 canonical 化并强制 containment（逃出 rootfs 返回 null），zip_files / unzip_files / download_file / grep_code 四个调用点显式拒绝（rootfsEscapeResult），不再回落原始路径；resolvePath 签名改为可空以强制调用方处理。已确认 zip/unzip 的既有 resolvePath 用法一并收敛到该实现。

P1-3 FunctionTypeTest — 已修（总数 13，补 FILE_DISTILL）。完整 :app:testDebugUnitTest 已在本地跑通：1666 个用例全部通过。顺带说明：这是该测试源首次真正编译运行——FileBindingServiceTest 此前有两处编译/断言错误（lambda 隐式 it 与 $i 不匹配、无匹配诊断用例传了空 new 的 REPLACE 被校验丢弃），本次一并修正。

P2-4 occurrence schema — 三处（EN/CN edit_file、Internal apply_file）已去掉 default = "1"，描述明确"不传 occurrence 会被拒绝，不会默认取第 1 处"。

P2-5 嵌套调用的高危工具不受 Hook 约束 — 按评审给出的第一个选项处理：说明为设计预期。外层包工具调用已经过主链路的工作区判定与审查/弹窗；把高危工具族纳入 Hook 拒绝范围意味着已审查通过的扩展包从此完全失去 execute_shell 等能力，这是显著的行为收紧，留待 maintainer 决策后再做。

P2-6 end_line < start_line — 已修。android/linux/saf 三分支委托前统一显式失败并提示重查行号。

P3-7 i18n — 已补齐：9 条审查/工作区文案（en）+ 11 条（es/id/ko/ms/ro/pt-rBR/ja，含 function_type/desc_file_distill），8 个语言目录全部补齐并通过 XML 结构校验。

P3-8 聚类传递闭包 — 维持现状：精确重复由精确路径兜底（列出全部位置并拒绝），残余风险限于"非精确近似重复且相邻"的情形；待真实案例出现再收敛聚类策略。

P3-9 反向映射失败回落宿主路径 — 已修。映射失败的 grep 结果条目直接丢弃并记日志，不把宿主真实路径回传给模型。

P3-10 CDATA ]]> — 已修。按 XML 规范拆段转义（]] → ]]]]><![CDATA[>），diff 与 request-content 两处 CDATA 均覆盖。

[question] 回归矩阵 — 目前仅完成编译与全量单测；真机回归矩阵（区内/区外/无工作区 × 三权限模式 × 审查开关 × 合规/不合规/失败）待实机执行后补填到 TODO index。

[question] file_distill 默认开 + focus 必填 — 确认为期望行为。设计即"无兜底"：不带 focus 的旧调用显式失败并指引 raw=true 重读，这是让调用方显式表达意图的一部分，不回退。

[CATMIAOZHI]

审计结论：✅ 批准合并

复审说明：这是针对新提交 b2c416c9 + ab346982 的复审（上次 review 5887753747，commit 50016df7，结论 REQUEST_CHANGES）。本轮只审新增 diff（18 个文件，+301/−34），作者在评论区已逐项回复。

改动（新增 diff，18 个文件，+301/−34）：按上次评审意见修复危险根拼写绕过、linux grep rootfs 逃逸、FunctionTypeTest 不一致、occurrence schema、非法行号范围、CDATA 转义、i18n 补齐等，并补测试。

逐项核对（上次评审的问题）：

• [P1] 危险根拼写绕过 — ✅ 已修并核实。isDangerousRecursiveDeleteTarget 先经 lexicallyNormalizePath（纯词法消解 ./../重复斜杠）再经 canonicalPath（覆盖符号链接），任一命中即拒绝；"/" 与 "/storage/emulated" 本就在危险根集合内，/sdcard/.. → /、/storage/emulated/0/.. → /storage/emulated 均能命中。新增测试覆盖 9 个拼写变体。
• [P1] linux grep .. 逃出 proot rootfs — ✅ 已修并核实。mapLinuxPath 改为可空返回：拼接结果 canonical 化并强制 containment，逃出 rootfs 返回 null；grep_code、zip_files、unzip_files、download_file 四个调用点均显式拒绝（rootfsEscapeResult），不再回落原始路径；resolvePath 签名改为可空，主代码中全部 6 处调用点均已处理 null，无遗漏。
• [P1] FunctionTypeTest 与新枚举不一致 — ✅ 已修。补 FILE_DISTILL，总数断言 12 → 13；作者称本地完整 :app:testDebugUnitTest 1666 个用例全部通过（以 CI 为准）。
• [P2] occurrence schema 与实现矛盾 — ✅ 已修。三处（EN/CN edit_file、Internal apply_file）去掉 default = "1"，描述明确不传会被拒绝。
• [P2] 嵌套调用的高危工具不受 Hook 约束 — 说明已接受，留待 maintainer 决策。作者按评审给出的第一个选项处理：外层包工具调用已过主链路判定与审查，把高危工具族纳入 Hook 拒绝范围会使已审查通过的扩展包完全失去 execute_shell 等能力，属于显著行为收紧，需 maintainer 拍板后再做。结论上不阻塞本次合并。
• [P2] read_file_part 在 end_line < start_line 时静默返回空成功 — ✅ 已修。android/linux/saf 三分支委托前统一显式失败并提示重查行号。
• [P3] i18n 不同步 — ✅ 已修并核实。function_type/desc_file_distill 在 values 及 8 个语言目录均已存在；9 条审查/工作区文案（en）+ 11 条（其余 7 个语言目录）已补齐。
• [P3] 模糊匹配聚类传递闭包 — 维持现状，可接受。精确重复由精确路径兜底（列出全部位置并拒绝），残余风险限于"非精确近似重复且相邻"的情形，待真实案例出现再收敛。
• [P3] linux grep 反向映射失败回落宿主路径 — ✅ 已修。映射失败的条目直接丢弃并记日志，不把宿主真实路径回传给模型。
• [P3] CDATA 内 diff 含 ]]> 破坏 XML — ✅ 已修。按 XML 规范拆段转义（]] → ]]]]><![CDATA[>），diff 与 request-content 两处 CDATA 均覆盖。
• [question] 手工回归矩阵"结果待填" — 作者回复：目前仅完成编译与全量单测，真机回归矩阵待实机执行后补填到 TODO index。已记录为合入后跟进项，不阻塞合并。
• [question] file_distill_enabled 默认开且 focus 必填 — 作者确认为期望行为（设计即"无兜底"，不带 focus 的旧调用显式失败并指引 raw=true 重读）。接受。

通过的检查：

• 新增 diff 全部落在上次评审指出的问题范围内，无无关改动、无新文件（相对上次 head 无新增文件）；
• resolvePath 改为可空后全部主代码调用点均显式处理 null，grep/zip/unzip/download 均 fail-closed；
• isAndroidPathInside 的分隔符归一在 Android 设备上是 no-op，不改变设备行为；
• lexicallyNormalizePath 为纯字符串运算，不做文件系统访问；绝对路径的 .. 在根处截断，不会逃逸到根之外；
• CDATA 转义、行号范围显式失败、grep 结果丢弃并记日志等均为 fail-closed 的处理。

后续可跟进（不阻塞）：

• 嵌套调用的高危工具是否纳入 Hook 拒绝范围，需 maintainer（@AAswordman）决策；
• 真机回归矩阵（区内/区外/无工作区 × 三权限模式 × 审查开关 × 合规/不合规/失败）待作者实机执行后补填到 docs/TODO/chat_file_tool_hardening/index.md。

由 水晴喵的muse 审计