file-brief

file-brief

[中文](#中文) · [English](#english)

file-brief is an agent-agnostic skill (OpenAI Codex · Claude Code · DeepSeek Harness) that turns repeated input-file inspection into reusable, task-local documentation.

---

中文

为什么发布这个仓库

当 Agent 开始数据分析、代码生成、文件转换或任何涉及本地文件的工程任务时，往往会先重复执行同一批检查：

• 文件是什么格式？
• 表格有多少列，各列是什么类型？
• JSON、YAML 或嵌套对象如何组织？
• Excel 有哪些工作表？SQLite 有哪些表和视图？
• 压缩包里有什么？XML/HTML 有哪些标签结构？
• 哪些字段存在缺失？文件是否已经变化？

这些检查本身很有必要，但如果每个会话、每个 Agent 都重新执行，会产生三个问题：

1. 浪费时间和上下文：相同输入文件被反复读取，真正用于解决任务的上下文反而减少。

2. 污染正式代码：临时的 head()、str()、read_csv()、字段打印和调试逻辑容易留在最终脚本中。

3. 难以复用知识：即使同一文件在另一个任务或会话中再次使用，之前发现的数据结构通常没有被保存。

这个仓库发布 file-brief 技能，把上述检查集中为一个可复用的预检层。技能为每个大型任务维护独立的 .file-catalog，生成简洁的 Markdown 说明和 SQLite 检索索引。后续 Agent 可以先读取说明，只在文件新增或变化时重新解析。

技能本身与具体 Agent 平台无关：任何能执行 Python 命令的 Agent（OpenAI Codex、Claude Code、DeepSeek Harness 等）都可以按同一工作流使用。

支持的平台与安装

| 平台 | 安装位置 | 说明 |

|---|---|---|

| OpenAI Codex | /skills/file-brief | 原生 skill 机制 |

| Claude Code | ~/.claude/skills/file-brief | 原生 Agent Skills 机制 |

| DeepSeek Harness | ~/.dsh/skills/ 或 ~/.agents/skills/（也可用项目内 .dsh/skills、.agents/skills） | 自动发现 SKILL.md |

一键安装（在仓库根目录）：

# Windows PowerShell：安装到全部平台
powershell -ExecutionPolicy Bypass -File .\install.ps1
# 或指定平台：.\install.ps1 -Target codex,claude,dsh,agents

# macOS/Linux：安装到全部平台
./install.sh
# 或指定平台：./install.sh codex claude dsh

也可以手动复制：

# Windows：DeepSeek Harness
Copy-Item -LiteralPath ".\skills\file-brief" -Destination "$HOME\.dsh\skills\file-brief" -Recurse

# macOS/Linux：Claude Code
mkdir -p ~/.claude/skills && cp -R skills/file-brief ~/.claude/skills/

npm 安装（DeepSeek Harness 插件方式）：file-brief@2.0.0 已发布到 npm（声明 dsh.bundle），可以作为 DSH 插件安装，也可在 [deepseek1024.com](https://deepseek1024.com/) 插件商店详情页获得一键安装命令：

dsh plugin --profile web add file-brief
# 或
npx @deepseek-ai/dsh plugin --profile web add file-brief

> 说明：作为 npm 插件安装时，bundle 的 patch 层是空操作（技能本体通过 SKILL.md 加载）；仍建议把技能复制到 ~/.dsh/skills 等技能根目录以获得最佳体验。

安装后请启动一个新的 Agent 会话，使技能列表重新加载。

为什么每个任务拥有自己的目录

解释文档保存在 /.file-catalog，而不是任何 Agent 的全局目录，原因是：

• 数据说明与对应任务一起移动、备份和归档。
• 不同任务不会互相污染索引。
• 任务内相对路径保持稳定，整个项目目录移动后仍能匹配。
• Markdown 说明可以选择性纳入版本控制。
• SQLite、锁文件和临时文件默认被 .file-catalog/.gitignore 排除。

隐私设计

技能的目标是保存“结构知识”，不是复制数据。生成的说明允许包含：

• 文件名、格式、大小、修改时间和 SHA-256；
• 字段名、键名、工作表名、表名、视图名、函数名、类名、压缩包成员名和对象名；
• 类型、维度、缺失量、样本内近似唯一值数量；
• PDF 页数、图片尺寸、文档结构计数、XML/HTML 标签计数、归档成员统计。

说明不会保存：

• 原始数据行、单元格样例或数据库单元格值；
• 正文段落、源代码片段或 notebook 单元格内容；
• 类别的实际值或高频值；
• 图片像素、PDF 正文、压缩包成员内容。

解析器可能在内存中读取有界样本以推断结构，但不会把样本值写入目录。

一个面向未来的问题

> 未来是否会出现一种专供 AI 阅读的新文件格式，将文件内容说明、数据结构、字段语义、来源和更新状态直接整合到文件本身，从而让这些信息能够随文件在不同 Agent、工具和平台之间传播，而无需每次重新解析？

支持的文件