1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | trace-file-lineage |
| 作者/维护者 | tianyiwei、Claudia Chen |
| 来源链接 | https://github.com/uczltw6/trace-file-lineage |
| 许可证 | MIT |
| GitHub Stars | 172（GitHub API） |
| Forks | 3（GitHub API） |
| 最新版本 | v0.7.0 |
| 安装方式 | pip install trace-file-lineage；另提供 Claude Code / Codex 原生插件包 |
2. 功能介绍与亮点
trace-file-lineage 回答一个 AI 编码 agent 用户常遇到的问题：“这个文件到底是哪个脚本、notebook、命令还是 agent 任务生成的？” 它在本地工作区内追溯文件的来源、派生关系、下游影响，并能对一次 agent 任务产出的全部文件给出完整清单。
核心亮点：
- 两种取证模式：对已存在的旧文件做“回溯取证”（给出带证据的候选来源，诚实标注为 candidate）；对未来要执行的命令或 agent 任务做“前瞻捕获”（用
run包装命令，产出可核验的 verified 记录）。 - 零依赖、纯本地：
pyproject.toml中dependencies = []，不请求任何供应商 API，不上传文件内容。 - 不执行被扫描的代码：Python 与 notebook 分析基于 AST 静态解析，凭据、密钥文件、缓存目录默认排除在索引之外。
- 多格式互操作：可读取 Git 历史、导入 DVC 声明的 pipeline、导入 OpenLineage 事件，并支持导出到 Obsidian；可选本地 OCR 处理扫描件。
- 双平台原生集成：仓库同时提供
.claude-plugin/plugin.json与.codex-plugin/plugin.json，通过UserPromptSubmit/Stop钩子自动记录任务边界，并附带“两平台产出必须一致”的等价性校验脚本。
3. 适用场景
所属分类：工程效率与代码质量。
典型场景是数据分析、科研代码或 AI agent 密集生成文件的项目：一段时间后想弄清某张图表、某份报告或某个中间数据集究竟由哪次运行、哪个脚本产生，尤其是在事先没有埋点或声明 pipeline 的情况下。受益人群主要是用 Claude Code / Codex 等编码 agent 做研究计算、数据管道开发的工程师与数据科学家，也适合需要排查“孤儿产物”“过期输出”的仓库维护者。
4. 跨 Agent 兼容性
- Claude Code：原生支持。仓库提供
.claude-plugin/plugin.json与钩子配置，也可将skills/trace-file-lineage直接软链接到~/.claude/skills/。 - Codex：原生支持。提供
.codex-plugin/plugin.json，安装路径与钩子机制与 Claude Code 并行维护，作者附带脚本核验两平台导出结果一致。 - OpenClaw：未验证——文档未提及。
- Hermes Agent：未验证——文档未提及。
5. 推荐理由
在 AI agent 越来越多地自主生成文件的当下，trace-file-lineage 用纯本地、零依赖的方式回答“这是哪来的”，并诚实区分“已证实”与“有根据的猜测”，避免开发者被自动化产出的文件淹没却无从追溯。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 5 | 上线约 4 天已获 172 Stars，日均增长明显，但仓库很新，尚无独立第三方评价可交叉验证 |
| 可用性 | 9 | 一条 pip install 加 lineage demo 即可体验；文档含安装指南、对比说明、真实案例；近日仍有持续提交；无付费依赖 |
| 安全性 | 9 | 见下方检查清单 |
安全检查清单： ① Shell 命令权限：仅在本地文件系统读取分析，不执行被扫描的项目代码（AST 静态解析）——无广泛写权限 ② 联网外发：核心代码不导入任何供应商 SDK、不要求 API key，SECURITY.md 明确“分析在本地完成，文件内容不会被传输” ③ 凭据处理：默认排除密钥文件、凭据存储、缓存目录，不纳入索引 ④ 可疑指令：未发现 prompt injection 或混淆代码迹象 ⑤ 作者信誉：两位具名维护者，仓库含 CONTRIBUTING.md、CODE_OF_CONDUCT.md、SECURITY.md 等完整治理文件 ⑥ License：MIT，明确 ⑦ 维护时间：近日仍有提交，非弃置项目
7. 跟同类 Skills 相比的优势
| 工具 | 定位 | 与 trace-file-lineage 的差异 |
|---|---|---|
| Git | 版本控制 | 只记录“文件在某次提交变了”，不知道是哪个脚本产生的，也不追踪未提交的中间产物 |
| DVC | 数据版本控制 | 前瞻式：需要事先在 dvc.yaml 中声明 pipeline 才能追溯；trace-file-lineage 主打无需事先声明的回溯取证，两者可通过 lineage import --format dvc 互补 |
| OpenLineage / Marquez | 数据血缘标准 | 需要作业主动上报事件、通常还要搭建后端服务；trace-file-lineage 面向单机工作区，无需服务端 |
| cursor/agent-trace | AI 生成代码归属标准 | 是一套记录归属数据的格式规范，本身不提供“这个文件哪来的”查询能力 |
| JayFarei/opentraces | agent 工作证据层 | 采用仓库内追加事件并可上传至 Hugging Face Hub；trace-file-lineage 坚持纯本地、不上传 |
8. 用户评价
该技能上线仅数日，目前在第三方平台尚无具名用户评价。
9. 其他补充
仓库提供中英双语 README（README.md / README-zh.md），并配有 GitHub Actions CI 校验流水线与 PyPI 发布（trace-file-lineage 包）。
10. 安装使用方式
- 作为 CLI：
pip install trace-file-lineage，运行lineage demo体验完整流程 - Claude Code（含钩子的完整插件）：
claude plugin validate . --strict后claude --plugin-dir .；仅需技能本体时执行ln -s "$PWD/skills/trace-file-lineage" "$HOME/.claude/skills/trace-file-lineage" - Codex：
mkdir -p "$HOME/.agents/skills" && ln -s "$PWD/skills/trace-file-lineage" "$HOME/.agents/skills/trace-file-lineage"，或通过 Codex 插件/市场流程安装完整包 - 安装钩子后无需重启 agent 会话；钩子依赖宿主显式信任，且在捕获失败时“fail open”（不阻断正常工作）；若
Stop事件被跳过，可用lineage recover手动补记
11. 注意事项
- 项目处于公开 Alpha 阶段（0.7.x），API 与索引格式可能变化
- 原生精细分析覆盖 Python / notebook，JavaScript / TypeScript 支持标注为“保守”（覆盖面较窄）
- 对捕获开始前就已存在的文件，结论标注为“候选猜测”而非“已证实”，不能作为历史因果的严格证明
- OpenClaw、Hermes Agent 上的可用性未经验证