开源一个 Codex 文件整理 Skill：一句话列出本次会话生成的文档、截图和交付物-平芜编程栈

1. 为什么需要 Artifact Radar：会话产物散落一地的真实痛点

用 Codex 写东西的人大概率都遇到过这个场景：一轮会话里让 Agent 写了三篇 Markdown 草稿、截了一张界面图、更新了 README、导出了一个 HTML 模板，最后你想把这些东西打包交付或者发给同事复查，结果发现自己得在文件管理器里翻半天。问题不在于文件没生成，而在于「刚才这一轮到底产出了哪些能交付的东西」这件事，Agent 自己说不清楚。

普通文件搜索工具解决的是「某个文件在哪」，而 Artifact Radar 解决的是「本次会话产出了哪些可交付、可打开、可继续使用的文件」。这两个问题的差别很大：前者是定位，后者是收口。在 Agent 工作流里，文件是随着对话一轮轮长出来的，散落在工作区、输出目录、Git 变更里，没有一个统一的账本。Artifact Radar 就是给这个场景做的一个 Codex Skill，它不假装自己有完美记账本，而是基于证据做 best-effort 索引，把文档、截图、交付物用一句话列出来。

这篇内容聚焦落地配置：怎么在config.toml里声明 Skill 入口，怎么用 PowerShell 调git status扫描会话产物，怎么跑出 Artifact Radar 清单，以及怎么验证「一句话输出文档、截图与交付物」这个效果。适合经常用 Codex 写技术文章、生成截图、导出 HTML、整理交付物的人，也适合想把「AI 做了什么」沉淀成文件清单的团队。

2. TaoToken 前置：给 Codex 配一个稳定的模型入口

在配 Skill 之前，得先保证 Codex 能正常跑起来。Codex 这类编码 Agent 对模型的稳定性和上下文长度有要求，尤其是长会话里连续生成文件时，模型入口不稳定会直接导致会话中断、产物丢失。我这边用的是 TaoToken 的 API 入口，官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api ，配置时注意 API 地址不加 UTM 参数。

TaoToken 在这里的角色是模型调用入口，不是替代编辑器，也不是什么灰色中转。你把它理解成一个统一的 API 网关就行：Codex 通过它调用模型，Skill 负责在本地文件系统里做产物索引，两者分工明确。配置前先去控制台把 API Key 建好，入口在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，Key 管理页面在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。如果你还没决定用哪个模型，可以先去模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite 试一下对话效果，确认模型能正常响应再往下配。

对于长期跑编码和 Agent 任务的用户，Coding Plan 会更合适，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它针对连续编码场景做了额度优化。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，配置细节以文档为准。如果你用的是 Claude Code 这类 Anthropic 系工具，对应入口在 https://taotoken.net/claudecode-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode-anthropic&utm_campaign=rewrite 。

注意：API Key 只放在本地配置文件或环境变量里，不要提交到 Git 仓库，也不要在截图里露出完整 Key。

3. 可复制配置：config.toml 骨架与 Skill 目录结构

Codex 的 Skill 机制核心是在config.toml里声明入口，然后让 Codex 在会话中按需加载。下面这份骨架可以直接复制，改掉路径和 Key 就能用。

# ~/.codex/config.toml # 模型入口：走 TaoToken API [model] provider = "taotoken" base_url = "https://taotoken.net/api" api_key_env = "TAOTOKEN_API_KEY" model = "gpt-4o" # Skill 声明区 [[skills]] name = "artifact-radar" description = "列出本次会话生成的文档、截图和交付物" entry = "~/.codex/skills/artifact-radar/SKILL.md" enabled = true # Skill 依赖的脚本目录 [skills.artifact-radar] script_dir = "~/.codex/skills/artifact-radar/scripts" default_hours = 8 git_changed_only = false extra_roots = ["~/.codex/generated_images"]

对应的 Skill 目录结构建议这样组织，和仓库结构保持一致，方便后续更新：

~/.codex/skills/artifact-radar/ ├── SKILL.md ├── agents/ │ └── openai.yaml ├── scripts/ │ └── find-artifacts.ps1 ├── assets/ │ └── artifact-radar-usage.png └── README.md

SKILL.md是 Skill 的入口描述文件，Codex 读它来决定什么时候触发这个 Skill。内容不用写太长，把触发条件和输出格式说清楚就行：

# Artifact Radar ## 触发条件 当用户询问「当前会话生成了哪些文件」「列出刚才的产物」「给我一个可点击的产物清单」时触发。 ## 行为 1. 调用 scripts/find-artifacts.ps1 扫描工作区 2. 优先读取 git status 作为高置信证据 3. 按置信度分层输出：high / medium / low 4. 输出可点击链接，而不是裸路径 ## 边界 不声称拥有完整的 session artifact ledger，只做 best-effort 索引。

agents/openai.yaml用来声明 Agent 侧的元信息，比如 Skill 名称、版本、依赖脚本：

name: artifact-radar version: 0.1.0 entry_script: scripts/find-artifacts.ps1 supported_platforms: - windows - linux - macos output_format: markdown

环境变量里把 Key 配上，Windows 用 PowerShell：

$env:TAOTOKEN_API_KEY = "你的Key"

Linux/macOS 用：

export TAOTOKEN_API_KEY="你的Key"

配完之后重启 Codex，让新的 Skill 被加载。这一步别省，很多人配完不重启，然后问为什么 Skill 不生效。

4. PowerShell 扫描脚本：用 git status 抓会话产物

Artifact Radar 的核心脚本是find-artifacts.ps1，它做三件事：读git status拿高置信证据、按时间窗口扫交付物类型、把结果按字段输出给 Agent 组织。下面这份脚本可以直接用，我按实际跑通的版本整理：

param( [string[]]$Roots = @("."), [int]$Hours = 8, [switch]$GitChangedOnly, [string[]]$ExtraRoots = @() ) $ErrorActionPreference = "Stop" $cutoff = (Get-Date).AddHours(-$Hours) # 交付物扩展名白名单 $artifactExt = @( ".md", ".txt", ".rst", ".docx", ".doc", ".pdf", ".xlsx", ".xls", ".csv", ".tsv", ".pptx", ".ppt", ".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg", ".html", ".htm", ".json", ".yaml", ".yml", ".ps1", ".sh", ".bat", ".cmd", ".zip", ".7z", ".tar", ".gz" ) # 排除目录 $excludeDirs = @("node_modules", "target", ".git", "dist", "build", ".venv", "__pycache__") function Get-GitChangedFiles { param([string]$Root) Push-Location $Root try { $staged = git diff --cached --name-only 2>$null $unstaged = git diff --name-only 2>$null $untracked = git ls-files --others --exclude-standard 2>$null return @($staged + $unstaged + $untracked) | Where-Object { $_ } | Sort-Object -Unique } finally { Pop-Location } } $results = @() $scanRoots = $Roots + $ExtraRoots foreach ($root in $scanRoots) { if (-not (Test-Path $root)) { continue } $gitFiles = @() if (Test-Path (Join-Path $root ".git")) { $gitFiles = Get-GitChangedFiles -Root $root } if ($GitChangedOnly -and $gitFiles.Count -eq 0) { continue } Get-ChildItem -Path $root -Recurse -File -ErrorAction SilentlyContinue | Where-Object { $ext = $_.Extension.ToLower() $artifactExt -contains $ext -and $_.LastWriteTime -ge $cutoff -and -not ($excludeDirs | Where-Object { $_.FullName -match "\\$_\\" }) } | ForEach-Object { $rel = Resolve-Path -Relative $_.FullName $evidence = if ($gitFiles -contains $rel -or $gitFiles -contains $_.Name) { "git" } else { "mtime" } $results += [PSCustomObject]@{ LastWriteTime = $_.LastWriteTime.ToString("yyyy-MM-dd HH:mm") Extension = $_.Extension SizeKB = [math]::Round($_.Length / 1KB, 1) Evidence = $evidence FullName = $_.FullName } } } $results | Sort-Object LastWriteTime -Descending | Format-Table -AutoSize

跑基础扫描：

.\scripts\find-artifacts.ps1 -Roots . -Hours 8

只看 Git 里新增或修改的交付物：

.\scripts\find-artifacts.ps1 -Roots . -GitChangedOnly

.\scripts\find-artifacts.ps1 -Roots . -ExtraRoots "$env:USERPROFILE\.codex\generated_images" -Hours 8

脚本输出的字段是LastWriteTime / Extension / SizeKB / Evidence / FullName，Agent 拿到这些字段后再组织成用户能读的清单。Evidence字段是关键：git表示这个文件出现在git status里，属于高置信；mtime表示只是最近修改过，属于中低置信。这个区分很重要，因为一旦把「可能相关」说成「全部产物」，用户后面就会基于错误信心做交付。

5. 验证请求：确认一句话输出文档、截图与交付物

配好之后要验证 Skill 真的能跑通。验证分两步：先确认脚本本身能出结果，再确认 Codex 能按 Skill 描述组织输出。

第一步，在项目目录里手动跑一次脚本，确认能扫到东西：

cd D:\work\my-project .\scripts\find-artifacts.ps1 -Roots . -Hours 2

如果输出里能看到你刚才生成的.md、.png、.html，说明脚本逻辑没问题。如果输出为空，先检查时间窗口是不是太窄，或者文件是不是被排除目录规则误伤了。

第二步，在 Codex 会话里直接问：

当前 session 生成了哪些文件？

或者用英文触发：

show generated artifacts with timestamps

预期输出应该分两层：第一层是产物条，把最重要的几个文件列出来，带可点击链接；第二层是完整明细，包含文件类型、时间、证据、说明和置信度。类似这样：

本次会话产物（最近 2 小时，扫描根目录 .） 高置信（git 变更）： - docs/codex-skill-draft.md 2025-01-15 14:22 12.4 KB - assets/artifact-radar-usage.png 2025-01-15 14:25 86.1 KB - templates/report.html 2025-01-15 14:28 4.7 KB 中置信（最近修改）： - README.md 2025-01-15 14:30 3.2 KB 扫描范围：. 及 ~/.codex/generated_images 时间窗口：2 小时

如果 Codex 输出的是裸路径而不是可点击链接，检查SKILL.md里的输出格式描述是不是写清楚了「输出可点击链接」。如果 Skill 根本没触发，检查config.toml里的entry路径是不是写对了，以及 Codex 有没有重启。

提示：验证时尽量在项目目录里跑，这样git status和最近修改文件都更容易收敛，结果更干净。

6. 本篇常见错排查

配 Skill 的过程中有几个坑比较常见，我按实际遇到的顺序列一下。

Skill 不触发：最常见的原因是config.toml里entry路径写错，或者 Codex 没重启。先确认路径存在，再重启 Codex。如果还不行，检查SKILL.md里的触发条件描述是不是太窄，Codex 匹配不到。

脚本报权限错误：PowerShell 默认执行策略可能禁止运行脚本。用管理员权限开 PowerShell，执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned，然后重试。这个改动只影响当前用户，风险可控。

扫描结果为空：先看时间窗口，-Hours 8改成-Hours 24试试。再看排除目录规则，如果你把产物放在dist或build里，会被默认排除。最后确认文件扩展名在白名单里，比如.log不在白名单，扫不到是正常的。

git status 拿不到变更：脚本只在检测到.git目录时才读git status。如果你的项目不在 Git 仓库里，Evidence字段会全是mtime，置信度会偏低。建议在 Git 仓库里跑，高置信证据更可靠。

输出里混入源码文件：检查$artifactExt白名单，确认没有把.js、.ts、.py这类源码扩展名加进去。Artifact Radar 的定位是交付物索引，不是全盘文件扫描器，源码默认不列。

API 调用报 401：检查TAOTOKEN_API_KEY环境变量是不是配在当前 shell 会话里，以及 Key 有没有过期。配置细节以接入文档为准：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。

长会话结果太杂：把时间窗口收窄，比如-Hours 2，或者加-GitChangedOnly只看 Git 变更。长会话里产物多，收窄范围比扩大扫描更有效。

7. 下一步：把产物索引接进你的工作流

Artifact Radar 本身不复杂，它解决的是一个很具体的问题：当 Codex 在文件系统里连续生成交付物时，你需要一个干净、可点击、带时间和证据的产物清单。配好之后，建议把它接进你的日常流程：写文章、做 README、生成截图、导出 HTML 之后，最后让它跑一次收口，确认有没有漏掉文件。

如果你还没配好模型入口，先去 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 把 Key 建好，再按第 3 节的config.toml骨架配上去。长期跑编码和 Agent 任务的，可以看 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。接入过程中遇到报错，先查 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，大部分配置问题文档里都有说明。

最后提醒一句：Artifact Radar 的定位是「当前会话产物」，不是全盘文件管理器。别让它默认扫整个磁盘，也别指望它给出完美账本。把边界说清楚，比假装什么都知道更有用。