智能文件 ⚡

停止凭猜测寻找文件位置。直接按文件内容定位目标。

问题所在

Agent 的文件操作是“盲目的”。find . -name "*.js" 仅匹配文件名，grep 仅搜索文本内容。目前没有任何工具能将你正在查找的内容与文件实际包含的内容关联起来。

Smart Files 通过一个工具、零依赖，彻底解决这一问题。

⚠️ 重要警告

破坏性操作

• --organize 分析文件类别，但不会自动移动文件
• --rename 默认为预演模式（dry run）；需显式指定 --force 才会真正执行重命名
• --cleanup 仅提供分析结果 —— 不执行任何删除操作，除非用户明确触发 首次使用这些模式时，请务必先不带 --force 运行，以预览将发生的变更。

路径边界与 --force 覆盖机制

默认情况下，所有操作均被限制在 workspace 根目录范围内。--dir 参数接受路径输入；若所传路径超出 workspace 范围，该工具将拒绝执行并自动回退至 workspace 根目录。传入 --force 可绕过此边界限制 —— 请谨慎使用。

操作日志

监听模式（--watch）会在 memory/smart-files-journal.json 维护一份日志，记录文件哈希值及检测到的变更。该文件在进程重启后仍保持持久化。

快速上手

按内容搜索文件（而不仅是文件名）

node skills/smart-files/smart-files.js --search "database connection"

在整个 workspace 中搜索所有文件的实际内容，而非仅限文件名。返回按相关性排序的结果，并附带匹配上下文片段。

查找重复文件

node skills/smart-files/smart-files.js --dedup

基于 SHA-256 哈希值识别重复文件，并按文件大小和路径分组展示。

自动分类文件

node skills/smart-files/smart-files.js --organize /path/to/dir

将文件自动归类为：code、data、docs、media、archives、images、other。

文件元数据与类型识别

node skills/smart-files/smart-files.js --info /path/to/file

显示文件大小、类型、行数、词数、最后修改时间，以及自动识别的内容类型。

清理分析

node skills/smart-files/smart-files.js --cleanup /path/to/dir

识别临时文件、大文件（>1MB）及重复文件组。

Workspace 概览

node skills/smart-files/smart-files.js --status

统计总文件数、总大小、扩展名分布、最大尺寸文件等信息。

重命名文件

node skills/smart-files/smart-files.js --rename script.js app.js

支持上下文感知的重命名。默认为预演模式 —— 仅显示将要发生的变更。

功能特性

内容感知型搜索

• 搜索文件真实内容，而非仅限文件名
• 支持词级匹配，可处理部分单词及特殊字符
• 结果按相关性得分排序（1.0 表示完全匹配）
• 返回匹配项周围的上下文片段
• 自动跳过二进制文件

重复文件检测

• 基于 SHA-256 的内容哈希（非仅文件名）
• 按文件大小进行预筛选，提升性能
• 将内容完全一致的文件归为同一组
• 展示各重复文件的大小与完整路径

自动分类

• 基于内容的文件类型识别
• 支持类别：code、data、docs、media、archives、images、other
• 适用于任意目录，不仅限于 workspace

清理分析

• 识别临时/备份文件（如 .tmp、~、.bak 等）
• 标记大文件（>1MB）
• 报告重复文件组
• 扫描整个目录树

文件信息

• 自动识别内容类型（JSON、Python、HTML、SQL、Markdown 等）
• 提供行数、词数、大小等统计信息
• 显示最后修改时间与创建时间

配置

无需任何配置，开箱即用。

覆盖 workspace 根目录：

--dir /path/to/workspace

性能表现

• 自动跳过二进制文件
• 重复检测前按大小预筛选（dedup）
• 单文件内容扫描上限为 10MB
• 搜索结果最多返回 20 条匹配项

Agent 协议

当 Agent 需执行文件操作时：

1. 查找文件 → 使用 --search 替代 find 或 grep
2. 执行清理 → 使用 --cleanup 识别待清理项
3. 删除前确认 → 使用 --dedup 先找出重复文件
4. 理解文件 → 使用 --info 获取元数据与类型信息
5. 组织整理 → 使用 --organize 对目录进行自动分类

安全性

• 路径校验 —— 拒绝 workspace 根目录之外的路径
• 二进制文件检测 —— 自动跳过非文本文件
• 大小限制 —— 单文件扫描上限为 10MB
• 符号链接安全 —— 使用标准 fs 操作

对比分析

Smart Files 将内容感知搜索、去重、清理与元数据获取整合于单一工具之中。

设计原则

1. 零配置 —— 开箱即用，无需任何配置
2. 零依赖 —— 纯 Node.js 实现，不依赖任何 npm 包
3. 默认安全 —— 自动跳过二进制文件，严格遵守大小限制
4. 完全透明 —— 所有操作均明确报告
5. 高性能 —— 针对 workspace 规模的文件操作优化