在 DeepSeek Harness 或其他智能体处理包含大量输入文件的任务时，Agent 经常需要重复执行相同的检查：文件是什么格式？表格有多少列？JSON/YAML 的嵌套结构是怎样的？如果每次会话都重新执行这些检查，不仅浪费时间和上下文窗口，还容易在正式代码中残留临时的调试语句。
file-brief 插件旨在解决这一问题。它是一个 Agent 无关的技能（兼容 OpenAI Codex、Claude Code 和 DeepSeek Harness），能够将重复的文件检查转化为可复用的、任务级别的结构化文档。
插件定位¶
file-brief 是一个任务级文件目录工具。它通过扫描任务根目录下的文件，生成 Markdown 说明文档和 SQLite 检索索引。生成的文档仅包含文件结构元数据（如字段名、类型、大小、修改时间、统计计数），不存储原始数据或单元格样例，从而保护隐私并节省存储空间。索引保存在任务目录下的 .file-catalog 文件夹中。
核心功能¶
该插件专注于提供“结构知识”而非数据本身：
- 隐私保护索引：仅记录文件结构元数据（文件名、格式、大小、SHA-256、字段名、键名、类型、维度、缺失量等），不保存原始数据、正文段落、代码片段或单元格值。
- 广泛格式支持：支持 CSV、TSV、XLSX、Parquet、SQLite、JSON、YAML、ZIP、XML、HTML、Jupyter Notebook、Stata、R 数据文件（RDS/RDA）、各种代码文件（Python, R, JS 等）以及文档和图片（PDF, DOCX）。
- 跨平台兼容：作为 DeepSeek Harness 插件，可配合官方 CLI 安装使用。
安装与启用¶
通过 DeepSeek Harness 的官方插件命令安装：
dsh plugin --profile web add file-brief
安装后请启动一个新的 Agent 会话，使技能列表重新加载。插件本体通过 SKILL.md 加载，无需额外配置。
使用方法¶
安装完成后，需要在任务目录下执行 Python 脚本来生成和管理索引。<skill-dir> 指代已安装技能的路径。
1. 首次建档¶
对任务根目录下的所有文件进行扫描，生成结构索引。
python "<skill-dir>/scripts/file_catalog.py" catalog --task-root "/work/my-task"
2. 查询文件状态¶
检查特定文件是否存在以及是否需要刷新。返回 fresh 表示无需重新解析，返回 stale 或 missing 则需要运行 catalog 刷新。
python "<skill-dir>/scripts/file_catalog.py" lookup --task-root "/work/my-task" "data/observations.csv"
3. 刷新变更¶
仅对新增或修改过的文件重新解析结构。
python "<skill-dir>/scripts/file_catalog.py" catalog --task-root "/work/my-task" "data/observations.csv"
4. 搜索与概览¶
在索引中搜索关键词，或查看任务目录的总体索引统计。
python "<skill-dir>/scripts/file_catalog.py" search --task-root "/work/my-task" "species"
python "<skill-dir>/scripts/file_catalog.py" info --task-root "/work/my-task"
环境要求与注意事项¶
- Python 版本：需要 Python 3.9 或更高版本。
- 依赖库：核心功能依赖标准库，但若要支持完整格式（如 Excel、Parquet、PDF 等），需安装额外库：
python -m pip install pandas openpyxl pyarrow PyYAML pypdf Pillow tomli
- R 数据支持：解析 RDS/RData 格式需要系统安装
Rscript以及 R 包lite（或jsonlite）。 - 权限与安全：插件以当前 DSH 进程的权限运行，安装前应检查源码与许可证。
适用场景¶
该插件适合所有需要频繁读取和检查本地文件的任务，特别是数据分析、代码生成、文件转换等工程场景。通过维护 .file-catalog 目录，可以避免 Agent 重复读取相同文件，从而将更多 token 用于核心业务逻辑。
总结¶
file-brief 提供了一种标准化的方式来管理任务文件结构。它通过生成轻量级的结构索引，让智能体能够快速了解文件概况，仅在文件发生变化时才重新解析。这对于提升 Agent 的执行效率和代码质量非常有帮助。
- GitHub: https://github.com/Zhiyi-Zhao/file-brief
- DSH Market: https://www.skillhub.cn/plugins/Zhiyi-Zhao/file-brief
