文件速览目录Zhiyi-Zhao/file-brief

file-brief

npm version
npm downloads
DSH Market
License: MIT
CI

中文 · English

file-brief 是一个与 Agent 无关的技能（OpenAI Codex · Claude Code · DeepSeek Harness），可将重复的输入文件检查转化为可复用、任务本地的文档。

中文

为什么发布这个仓库

当 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 插件商店详情页获得一键安装命令：

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、工具和平台之间传播，而无需每次重新解析？

支持的文件

| 类别 | 格式 | 说明 |
|---|---|---|
| 分隔表格 | CSV、TSV、TAB 及分号/竖线分隔变体 | 自动探测分隔符；采样字段类型、缺失率和近似唯一值数量 |
| 工作簿 | XLSX、XLS、XLSM、ODS | 工作表、字段和每表有界样本结构 |
| 列式数据 | Parquet、Feather、Arrow IPC | 使用元数据读取字段、行组和记录批次 |
| 数据库 | SQLite（.db/.sqlite/.sqlite3） | 只读方式列出表、视图、索引、列声明类型和行数 |
| 结构化文本 | JSON、JSONL、NDJSON、YAML、TOML | 键、嵌套层级和元素类型 |
| 归档 | ZIP/JAR/WAR/APK、TAR/TGZ/TBZ2/TXZ、GZIP | 成员清单、类型直方图和压缩统计，不读取成员内容 |
| 标记文档 | XML/XSD/SVG/KML/GPX、HTML | 标签计数、属性键、命名空间、标题/表格/链接结构 |
| Notebook | Jupyter（.ipynb） | 单元格类型分布、执行状态、内核语言，不保存单元格内容 |
| 统计软件 | Stata（.dta） | 变量名、类型与有界样本结构 |
| R 数据 | RDS、RDA、RData | 对象、类、维度、列、列表成员和缺失量 |
| 代码与文本 | Python、R、JS/TS、Java、Go、Rust、C/C++、C#、Ruby、PHP、Kotlin、Swift、Scala、Julia、Lua、Perl、Dart、Elixir、Haskell、Erlang、F#、VB、Shell、PowerShell、Markdown 及常见文本 | 编码、行数、声明、导入和标题结构 |
| 文档与媒体 | PDF、DOCX、常见图片 | 页面、段落、表格、尺寸和元数据键 |
| 其他 | 未知文本或二进制 | 至少生成 MIME 类型和基础元数据说明 |

解析库缺失或文件无法深度读取时，技能会生成带有 unsupported 或 error 状态的通用说明，而不是静默失败。

环境要求

- Python 3.9 或更高版本。
- 核心索引、SQLite/归档/XML/HTML/notebook 解析和大多数源代码分析只依赖标准库。
- 完整格式支持建议安装：

python -m pip install pandas openpyxl pyarrow PyYAML pypdf Pillow tomli

- RDS/RData 深度解析需要：
- Rscript；
- R 包 jsonlite。

Rscript 的发现顺序是：

1. 环境变量 R_SCRIPT_EXE；
2. 系统 PATH 中的 Rscript；
3. Windows 常见 R 安装目录。

使用（与语言和平台无关）

以下示例中的  是已安装的 file-brief 技能目录。任何任务——数据分析、Web 项目、配置管线、迁移脚本——都遵循同一工作流。

选择任务根目录

--task-root 应指向包含当前大型任务全部输入、脚本和输出的最高合理目录。

- 优先使用用户明确指定的任务目录。
- 未指定时使用当前工作目录。
- 不自动向上搜索 Git 根目录。
- 所有待建档文件必须位于任务根目录内。

首次建档

python "/scripts/file_catalog.py" catalog --task-root "/work/my-task"

不提供具体文件时会递归处理整个任务目录，并跳过 .git、.file-catalog、依赖目录、虚拟环境和缓存目录。

开始任务前查询

python "/scripts/file_catalog.py" lookup \
--task-root "/work/my-task" \
"data/observations.csv"

如果返回 fresh，Agent 应优先读取返回的 Markdown 文档，而不是再次探查源文件。需要机器可读输出时追加 --json。

刷新增或变化的文件

python "/scripts/file_catalog.py" catalog \
--task-root "/work/my-task" \
"data/observations.csv"

技能先比较文件大小和高精度修改时间；只有缺失或变化（或解析器版本升级）的条目才重新计算 SHA-256 并解析。

跨子目录搜索与目录概览

python "/scripts/file_catalog.py" search \
--task-root "/work/my-task" \
"species"

python "/scripts/file_catalog.py" info \
--task-root "/work/my-task"

搜索范围包括相对路径、文件名、格式、摘要、字段名、键名和其他结构标识符。info 输出按状态和格式的条目统计。跳过不需要的目录或文件：--exclude "cache,tmp.sqlite"。

.file-catalog 的结构

/
└── .file-catalog/
├── INDEX.md
├── documents/
│   └── .md
├── catalog.sqlite3
└── .gitignore

- INDEX.md：适合人工浏览的紧凑索引。
- documents/：每个任务相对路径对应一份当前说明。
- catalog.sqlite3：供 lookup 和 search 使用的机器索引。
- .gitignore：只排除 SQLite、锁和临时文件，Markdown 可以提交。

状态含义

| 状态 | 含义 | 推荐动作 |
|---|---|---|
| fresh | 说明存在且文件大小/修改时间一致 | 直接读取说明 |
| stale | 源文件自上次解析后发生变化 | 运行 catalog 刷新 |
| missing | 文件或说明不存在 | 检查路径；存在源文件时运行 catalog |
| unsupported | 没有深度解析器，但已有通用元数据 | 使用现有说明，必要时人工检查 |
| error | 深度解析失败，并已生成降级说明 | 阅读警告，修复依赖或文件问题后刷新 |

示例结果

SQLite 说明只保留表结构，不读取单元格值：

{
"table_count": 2,
"tables": [
{"name": "measurements", "column_count": 3, "row_count": 1250,
"columns": [
{"name": "species", "declared_type": "TEXT", "notnull": true}
]}
]
}

ZIP 归档说明列出成员与类型直方图，不读取成员内容：

{
"member_count": 42,
"member_names": ["data/a.csv", "data/b.csv", "README.md"],
"extension_histogram": [{"extension": ".csv", "count": 2}]
}

CSV 说明自动记录探测到的分隔符：

{
"delimiter": ";",
"column_count": 3,
"columns": [{"name": "species", "dtype": "object", "missing_percent_in_sample": 1.2}]
}

这些示例是结构示意，不包含真实输入数据。

推荐工作流

确定 task root
→ lookup 输入文件
→ fresh：读取说明
→ missing/stale：catalog 后读取说明
→ 只有说明不足时才检查原文件
→ 将实际业务逻辑写入正式代码

不要把一次性的字段打印、样本输出和格式探测重新写入生产脚本。

本版本改进与下一步方向

v2 已实现：

- 平台无关化：同一 SKILL.md 同时适配 OpenAI Codex、Claude Code 与 DeepSeek Harness；提供 install.ps1 / install.sh 一键安装。
- 格式覆盖扩展：SQLite、ZIP/JAR/APK、TAR/TGZ、GZIP、XML、HTML、Jupyter notebook、Stata，全部仅依赖标准库（Stata 除外）。
- 通用化：CSV/TSV 自动探测分隔符；20+ 编程语言的表驱动结构提取；工作流与语言/技术栈无关。
- 工程改进：--json 机器可读输出、info 子命令、--exclude 排除项、并行解析（有界线程池）、解析器版本化（升级后自动重新解析旧条目）、搜索通配符转义。

未来方向（欢迎贡献）：

- 数据格式侧：HDF5/NetCDF、SAS/SPSS、地理空间（GeoJSON/Shapefile）深度解析。
- 结构侧：目录级聚合说明（一个文档描述整个子目录树）；跨任务全局索引。
- 语义侧：可选 LLM 摘要层，用模型生成字段语义（仍不写入原始值）。
- 格式侧：尝试为“AI 原生文件格式”提供预检支持。

常见问题

为什么没有精确统计 CSV 总行数？
默认使用有界样本，以避免为结构说明完整扫描超大文本表格。文档会明确标注采样范围。

为什么某个 Excel 文件显示 error？
旧式 XLS 或特殊工作簿可能需要额外解析库。安装对应 pandas 引擎后重新运行 catalog。

为什么 TOML 降级？
Python 3.11+ 内置 tomllib；Python 3.9/3.10 需要安装 tomli。

为什么 R 数据无法解析？
确认 Rscript 可用，并运行 Rscript -e "install.packages('jsonlite')"。也可以设置 R_SCRIPT_EXE 为可执行文件路径。

SQLite 说明会读取我的数据吗？
不会。SQLite 解析以只读 URI 打开数据库并启用 query_only，只读取 sqlite_master 的 schema 信息和行数，不读取任何单元格值。

可以提交 .file-catalog 吗？
可以提交 INDEX.md 和 documents/。SQLite 和临时文件默认被目录内 .gitignore 排除。

会不会把隐私数据写入说明？
设计上不会保存原始行、单元格、正文、归档成员内容或类别值。对于高度敏感的数据，仍建议在提交生成的 Markdown 前进行组织自己的安全审查。

English

为什么存在这个仓库

在智能体能够分析数据、生成代码、转换文件或处理任何本地文件工程任务之前，它通常会重复相同的发现工作：

- 这个文件是什么格式？
- 存在哪些列，它们的类型是什么？
- JSON、YAML 或嵌套对象是如何组织的？
- 存在哪些工作表、表和视图？
- 归档文件里有什么？XML/HTML 文档使用了哪些标签？
- 哪些地方存在缺失值？
- 自上一个任务以来，文件是否发生了变化？

这些检查是必要的，但在每个会话中重复进行会带来三个问题：

1. 时间和上下文被浪费。 相同的输入被反复打开，而留给实际任务的上下文却越来越少。
2. 生产代码变得杂乱。 临时的 head()、str()、read_csv()、模式打印和调试逻辑会泄漏到最终脚本中。
3. 知识无法复用。 后续的智能体或会话通常不得不重新发现相同的结构。

本仓库将 file-brief 技能发布为一个可复用的预检层。每个大型任务都会获得自己的 .file-catalog，其中包含简洁的 Markdown 说明和一个 SQLite 搜索索引。后续的智能体可以复用这些说明，并且只重新解析新增或过期的文件。

该技能与智能体平台无关：任何能够执行 Python 命令的智能体——OpenAI Codex、Claude Code、DeepSeek Harness 以及其他——都使用相同的工作流程。

支持的平台与安装

| 平台 | 安装位置 | 备注 |
|---|---|---|
| OpenAI Codex | /skills/file-brief | 原生技能机制 |
| Claude Code | ~/.claude/skills/file-brief | 原生 Agent Skills 机制 |
| DeepSeek Harness | ~/.dsh/skills/ 或 ~/.agents/skills/（项目级 .dsh/skills 和 .agents/skills 也可用） | 自动发现 SKILL.md |

一次性安装（从仓库根目录执行）：

Windows PowerShell: install to every platform
powershell -ExecutionPolicy Bypass -File .\install.ps1
or select targets: .\install.ps1 -Target codex,claude,dsh,agents

macOS/Linux: install to every platform
./install.sh
or select targets: ./install.sh codex claude dsh

手动复制也可以：

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 商店在其插件页面上显示了一键安装命令：

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

注意：作为 npm 插件安装时，bundle 的补丁层是一个空操作（技能本身通过 SKILL.md 加载）；将技能复制到 ~/.dsh/skills 或其他技能根目录仍能获得最佳体验。

安装后启动一个新的智能体会话，以便重新加载技能列表。

为什么目录是任务本地的

生成的文档位于 /.file-catalog 下，而不是任何智能体全局目录中：

- 说明会随任务一起移动、归档和备份。
- 独立的任务不会相互污染彼此的索引。
- 当整个目录移动时，任务相对路径保持稳定。
- Markdown 说明在有用时可以纳入版本控制。
- SQLite、锁和临时文件会被生成的 .gitignore 忽略。
隐私模型

该技能存储的是结构知识，而非数据的副本。说明可能包含：

- 文件名、格式、大小、时间戳和 SHA-256 哈希值；
- 列、键、工作表、表、视图、函数、类、归档成员和对象名称；
- 样本中的类型、维度、缺失计数和近似去重计数；
- PDF 页数、图像尺寸、文档结构计数、XML/HTML 标签计数和归档成员统计信息。

它们有意省略：

- 原始行、单元格样本和数据库单元格值；
- 段落摘录、源代码片段和笔记本单元格内容；
- 实际类别值和频率列表；
- 图像像素、PDF 文本和归档成员内容。

解析器可能会检查有界的内存样本以推断结构，但样本值不会写入目录。

面向未来的一个问题

是否会出现一种专为 AI 消费而设计的新文件格式——它将内容描述、数据结构、字段语义、来源和更新状态直接嵌入文件本身，使这些知识能够随文件在代理、工具和平台之间传递，而无需每次都重新推导？

支持的文件

| 类别 | 格式 | 结构信息 |
|---|---|---|
| 分隔表格 | CSV、TSV、TAB 以及分号/竖线变体 | 自动分隔符检测；采样类型、缺失率和近似去重计数 |
| 工作簿 | XLSX、XLS、XLSM、ODS | 工作表、字段和有界的工作表级样本 |
| 列式数据 | Parquet、Feather、Arrow IPC | 来自元数据的模式、行组和记录批次 |
| 数据库 | SQLite（.db/.sqlite/.sqlite3） | 只读表、视图、索引、声明的列类型和行数 |
| 结构化文本 | JSON、JSONL、NDJSON、YAML、TOML | 键、嵌套和元素类型 |
| 归档 | ZIP/JAR/WAR/APK、TAR/TGZ/TBZ2/TXZ、GZIP | 成员列表、类型直方图和压缩统计信息；从不读取内容 |
| 标记文档 | XML/XSD/SVG/KML/GPX、HTML | 标签计数、属性键、命名空间、标题/表格/链接结构 |
| 笔记本 | Jupyter（.ipynb） | 单元格类型分布、执行状态、内核语言；从不存储单元格内容 |
| 统计软件 | Stata（.dta） | 变量名、类型和有界样本结构 |
| R 数据 | RDS、RDA、RData | 对象、类、维度、列、成员和缺失计数 |
| 代码和文本 | Python、R、JS/TS、Java、Go、Rust、C/C++、C#、Ruby、PHP、Kotlin、Swift、Scala、Julia、Lua、Perl、Dart、Elixir、Haskell、Erlang、F#、VB、Shell、PowerShell、Markdown、常见文本 | 编码、行数、声明、导入和标题 |
| 文档和媒体 | PDF、DOCX、常见图像 | 页数、段落、表格、尺寸和元数据键 |
| 其他 | 未知文本或二进制 | MIME 类型和通用文件元数据 |

当可选解析器不可用时，该技能会生成有用的 unsupported 或 error 说明，并带有明确的警告。

要求

- Python 3.9 或更高版本。
- 核心索引、SQLite/归档/XML/HTML/notebook 解析以及大多数源代码分析仅使用标准库。
- 如需完整的格式覆盖，请安装：

python -m pip install pandas openpyxl pyarrow PyYAML pypdf Pillow tomli

- 深度 RDS/RData 检查需要 Rscript 和 R 包 jsonlite。

Rscript 按以下顺序解析：

1. R_SCRIPT_EXE；
2. PATH 上的 Rscript；
3. 常见的 Windows R 安装目录。

用法（语言和平台无关）

下文的  指已安装的 file-brief 技能目录。任何任务——数据分析、Web 项目、配置流水线、迁移脚本——都遵循相同的工作流。

选择任务根目录

--task-root 应当是包含某个大型任务的输入、脚本和输出的最高合理目录。

- 优先使用用户显式提供的根目录。
- 否则使用当前工作目录。
- 不要推断 Git 根目录。
- 每个编入目录的路径都必须保持在任务根目录内。

创建第一个目录

python "/scripts/file_catalog.py" catalog --task-root "/work/my-task"

在没有显式路径的情况下，catalog 会递归处理任务，同时排除 .git、.file-catalog、依赖文件夹、虚拟环境和缓存。

在开始工作前查找输入

python "/scripts/file_catalog.py" lookup \
--task-root "/work/my-task" \
"data/observations.csv"

当结果为 fresh 时，请阅读返回的 Markdown 说明，而不是再次探查源文件。追加 --json 可获得机器可读的输出。

刷新新增或已更改的文件

python "/scripts/file_catalog.py" catalog \
--task-root "/work/my-task" \
"data/observations.csv"

该技能首先比较文件大小和高分辨率修改时间。它仅对缺失或已更改（或解析器版本已升级）的条目重新计算 SHA-256 并重新解析。

跨子目录搜索并检查目录

python "/scripts/file_catalog.py" search \
--task-root "/work/my-task" \
"species"

python "/scripts/file_catalog.py" info \
--task-root "/work/my-task"

搜索涵盖相对路径、文件名、格式、摘要、字段、键以及其他结构标识符。info 按状态和格式汇总条目。使用 --exclude "cache,tmp.sqlite" 跳过不需要的名称。

.file-catalog 布局

/
└── .file-catalog/
├── INDEX.md
├── documents/
│   └── .md
├── catalog.sqlite3
└── .gitignore

- INDEX.md：供人工浏览的紧凑索引。
- documents/：每个任务相对路径对应一份当前说明。
- catalog.sqlite3：供 lookup 和 search 使用的机器索引。
- .gitignore：忽略 SQLite、锁和临时文件，同时让 Markdown 可跟踪。

状态参考

| 状态 | 含义 | 建议操作 |
|---|---|---|
| fresh | 解释存在，且大小/修改时间仍然匹配 | 读取解释 |
| stale | 源文件在上次分析后发生了变化 | 运行 catalog |
| missing | 源文件或解释缺失 | 检查路径，然后对现有源文件运行 catalog |
| unsupported | 没有匹配的深度解析器，但存在通用元数据 | 使用元数据，或在需要时手动检查 |
| error | 深度解析失败，并生成了回退解释 | 阅读警告，修复依赖项或文件，然后刷新 |

示例结构

SQLite 解释仅记录表结构，从不记录单元格值：

{
"table_count": 2,
"tables": [
{"name": "measurements", "column_count": 3, "row_count": 1250,
"columns": [
{"name": "species", "declared_type": "TEXT", "notnull": true}
]}
]
}

ZIP 解释列出成员和类型直方图，而不读取内容：

{
"member_count": 42,
"member_names": ["data/a.csv", "data/b.csv", "README.md"],
"extension_histogram": [{"extension": ".csv", "count": 2}]
}

CSV 解释记录检测到的分隔符：

{
"delimiter": ";",
"column_count": 3,
"columns": [{"name": "species", "dtype": "object", "missing_percent_in_sample": 1.2}]
}

这些是结构性示例，不是真实输入记录。

推荐工作流

选择任务根目录
→ 查找输入
→ fresh：读取解释
→ missing/stale：运行 catalog，然后读取解释
→ 仅在解释不足时检查原始源文件
→ 让生产代码专注于实际任务

不要将一次性的 schema 打印、样本转储或格式探测重新引入生产脚本。

v2 中的变化及其发展方向

v2 中已实现：

- 平台中立：一个 SKILL.md 可配合 OpenAI Codex、Claude Code 和 DeepSeek Harness 使用；install.ps1 / install.sh 提供一键安装。
- 更广的格式覆盖：SQLite、ZIP/JAR/APK、TAR/TGZ、GZIP、XML、HTML、Jupyter notebooks、Stata——除 Stata 外全部仅使用标准库。
- 泛化：对分隔表格自动检测分隔符；对 20 多种编程语言进行表驱动的结构提取；工作流独立于语言或技术栈。
- 工程化：--json 机器可读输出、info 子命令、--exclude 扫描过滤器、有界并行解析、解析器版本化（升级会重新分析旧条目），以及搜索通配符转义。

未来方向（欢迎贡献）：

- 数据格式：HDF5/NetCDF、SAS/SPSS、地理空间（GeoJSON/Shapefile）深度解析。
- 结构：目录级聚合解释；跨任务全局索引。
- 语义：可选的 LLM 摘要层，在不存储原始值的情况下推导字段语义。
- 格式：对新兴 AI 原生文件格式的预检支持。

故障排除与常见问题

为什么缺少确切的 CSV 行数？
分隔文件默认使用有界采样，因此结构预检不会完整扫描非常大的文本表。说明中会记录采样范围。

为什么 Excel 文件报告 error？
旧版 XLS 文件或专用工作簿可能需要额外的 pandas 引擎。请安装相关引擎并重新运行 catalog。

为什么 TOML 回退了？
Python 3.11+ 包含 tomllib；Python 3.9/3.10 需要 tomli。

为什么 R 数据检查失败？
确认 Rscript 可用，并运行 Rscript -e "install.packages('jsonlite')"。你也可以将 R_SCRIPT_EXE 设置为可执行文件路径。

SQLite 分析会读取我的数据吗？
不会。SQLite 以只读方式打开，并启用了 query_only；只读取 sqlite_master 模式对象和行数，从不读取单元格值。

.file-catalog 可以提交吗？
可以。在有用时提交 INDEX.md 和 documents/。生成的 .gitignore 会忽略 SQLite 和临时文件。

私有值会泄漏到说明中吗？
该实现有意省略行、单元格、段落文本、归档成员内容、类别值和代码片段。处理高度敏感数据的组织在发布生成的 Markdown 之前仍应进行审查。

许可证

MIT。参见 LICENSE。