file-brief

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

以下示例中的 `` 是已安装的 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"。

Usage (language- and platform-agnostic)

`` below means the installed file-brief skill directory. Any task — data analysis, a web project, a config pipeline, a migration script — follows the same workflow.

Choose a task root

--task-root should be the highest sensible directory that contains the inputs, scripts, and outputs for one large task.

• Prefer a root explicitly provided by the user.
• Otherwise use the current working directory.
• Do not infer a Git root.
• Every cataloged path must remain inside the task root.

Create the first catalog

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

With no explicit path, catalog recursively processes the task while excluding .git, .file-catalog, dependency folders, virtual environments, and caches.

Look up an input before starting work

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

When the result is fresh, read the returned Markdown explanation instead of probing the source again. Append --json for machine-readable output.

Refresh a new or changed file

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

The skill first compares file size and high-resolution modification time. It recalculates SHA-256 and reparses only missing or changed (or parser-version-upgraded) entries.

Search across subdirectories and inspect the catalog

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

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

Search covers relative paths, file names, formats, summaries, fields, keys, and other structural identifiers. info summarizes entries by status and format. Skip unwanted names with --exclude "cache,tmp.sqlite".