在 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
