现在可以做什么
可以拿 DeckProbe Skill 做小范围试用。它能在 Linux 上检查一份本地 PDF、Office 或 iWork 文件,告诉用户文件是否适合交给下一个文档工具。它不做 OCR、内容摘要,也不能代替安全扫描。
01 · 结果先说
Demo 已经覆盖安装、真实文件检查和异常处理。当前还没有业务使用数据,所以这版适合试用,不适合直接下长期投入结论。
可以拿 DeckProbe Skill 做小范围试用。它能在 Linux 上检查一份本地 PDF、Office 或 iWork 文件,告诉用户文件是否适合交给下一个文档工具。它不做 OCR、内容摘要,也不能代替安全扫描。
文档交给 AI 或其他工具前,先检查格式、页数和结构信号,避免拿错文件继续处理。
把一个 GitHub 地址发给 Codex。Codex 会补依赖、安装官方 CLI 和 Skill,然后做一次校验。
输入不合适、资源不够或检查失败时会直接说明原因,不会拿旧报告顶替这次结果。
页面内有安装视频、真实 PDF 结果、原始 JSON 和文字记录,开发可以继续查,汇报也够用。
Codex 会按项目说明补齐当前环境缺少的基础依赖,安装官方 DeckProbe CLI 和最新版 Skill,并在结束前完成验证。
请按 https://github.com/nexteamer/deckprobe-skill 安装最新版 DeckProbe Skill,自动补齐依赖并验证。
02 · 现场演示
环境是干净的 Ubuntu 24.04。视频里先补依赖并安装正式版,再开一个新会话检查真实《三体》PDF。
03 · Skill 怎么组装
真正读取文件的是 DeckProbe CLI。Skill 不解析文档,它只规定哪些请求可以调用 CLI、调用前要检查什么,以及结果应该怎么写给用户。两边目前放在不同的仓库。
DeckProbe CLI 检查文件并生成 JSON;DeckProbe Skill 让 Codex 知道什么时候运行这个命令,并把 JSON 改写成用户看得懂的检查结果。原始 JSON 仍然保留,开发排查时可以直接查看。
一次只检查一份本地 PDF、Office 或 iWork 文件。
确认这个请求该不该运行,以及文件和环境是否符合要求。
检查条件满足后,脚本调用一次官方 deckprobe。
Codex 给出五段检查结果,同时附上这次运行的原始 JSON。
DeckProbe 仓库放检查引擎;DeckProbe Skill 仓库放 Codex 规则和安装说明。
deckflow/deckprobe/
├── crates/deckprobe-cli/
├── crates/deckprobe-core/
├── crates/deckprobe-engine/
├── crates/deckprobe-format-*/
└── packages/deckprobe-js/
nexteamer/deckprobe-skill/
└── skills/deckprobe/
├── SKILL.md
├── agents/openai.yaml
├── docs/INSTALLATION.md
├── references/result-interpretation.md
└── scripts/probe-document.sh
Skill 装进 Codex 的 Skills 目录。每次检查产生的文件放在当前项目里,方便用户找到。
$CODEX_HOME/skills/deckprobe/
├── SKILL.md
├── agents/openai.yaml
├── docs/INSTALLATION.md
├── references/result-interpretation.md
└── scripts/probe-document.sh
caller-workspace/
└── output/deckprobe/
├── <file>-XXXXXX.json
└── <file>-XXXXXX.diagnostic
检查成功会生成 JSON;失败时可能留下 diagnostic。两者都只记录本次运行,旧文件不能当成新结果。
如果只是希望用户少记一个地址,现有方案已经做到了:用户把 Skill 仓库地址发给 Codex,安装说明会继续安装官方 CLI。真正合仓解决的是开发维护问题,不是当前 Demo 的使用问题。
本地 DeckProbe checkout 里已经有一份早期 Skill 副本,但它没有被上游仓库跟踪,而且已经落后于正式 Skill。直接复制只能得到一份新副本,不能解决同步和发布问题。我的建议是:Demo 阶段维持分仓;真要合仓,交给开发按一次正式的单仓发布改造来做。
deckflow/deckprobe,Skill 在 nexteamer/deckprobe-skill,需要上游接受 Skill 目录和维护责任。一个总控文件,另外四个文件分别负责入口、执行、结果说明和安装。
SKILL.md总说明告诉 Codex 什么时候用、怎么用,以及哪些事情不要做。
agents/openai.yaml登记入口保存名称、简介和默认提示词,让 Codex 能找到这个 Skill。
scripts/probe-document.sh运行脚本检查文件和机器条件,然后调用官方 CLI。
references/result-interpretation.md结果写法规定 JSON 里的信息怎么整理成用户看到的五段结果。
docs/INSTALLATION.md安装说明说明安装、验证、升级、回滚和卸载。
它的核心就是这张流程图:先判断是否适用,再运行一次检查,最后按本次结果写回复。任何条件不满足,马上停。
flowchart TB
subgraph R1["先判断该不该用"]
direction LR
A["01 任务范围
只检查一份本地文档"] --> B["02 触发判断
确认请求是否适用"] --> C["03 范围边界
不适用就说明原因并停止"]
end
subgraph R2["再完成一次检查"]
direction LR
D["04 运行准备
检查环境、文件和资源"] --> E["05 执行
脚本调用一次 CLI"] --> F["06 给出建议
选择处理意见"]
end
subgraph R3["最后写清楚结果"]
direction LR
G["07 写回复
生成五段结果卡"] --> H["08 核对证据
缺什么就如实写"] --> I["09 停止条件
完成或遇错即结束"]
end
R1 -- "适用时继续" --> R2 --> R3
classDef main fill:#102137,stroke:#55d9f7,color:#f7fbff,stroke-width:1.5px;
classDef stop fill:#241b2a,stroke:#ff8e9f,color:#f7fbff,stroke-width:1.5px;
class A,B,D,E,F,G,H main;
class C,I stop;
style R1 fill:#0b1726,stroke:#27415d,color:#c5d2e2
style R2 fill:#0b1726,stroke:#27415d,color:#c5d2e2
style R3 fill:#0b1726,stroke:#27415d,color:#c5d2e2
图中九个节点对应 SKILL.md 的九个主段落。粉色分支表示不再继续调用;手机端可左右滑动查看完整流程。
平时改触发入口看 YAML,改运行逻辑看脚本,改回复看解释规则,改安装步骤看安装文档。
这个文件只登记入口信息,不执行文档检查。
它先检查文件、内存和 CLI,再运行一次 DeckProbe。成功写 JSON,失败保留诊断和退出码。
它决定什么情况下建议继续、复核、输入密码或停止,也规定五段结果里放哪些信息。
从干净 Ubuntu 开始,写清官方 CLI、Skill 安装、第一次使用,以及后续升级和卸载。
04 · 几轮怎么做成
第一轮先判断项目值不值得用,第二轮把它接进 Codex。后面两轮都在修实测中发现的问题,没有另起新方向。
README 讲了很多技术细节,但看不出真实文件跑起来怎样。Docker Hub 当时也无法正常拉取。
改用官方静态二进制,并从源码确认 CLI、格式识别和资源限制。
结论很明确:它适合放在文档处理前做检查,不是给普通用户读文档的工具。
只有 CLI 还不够。Codex 不知道什么时候该调用,也不知道失败后该怎么回答。
补上 SKILL.md、包装脚本、结果说明和安装文档,再加文件、容器和新会话测试。
形成了一套可以安装、调用和验证的 Skill,所有测试都能回到同一份运行记录。
v0.3.0 把符号链接本身当成文件大小;v0.3.1 的回复条目又写多了。
改为读取链接目标的真实大小,并在回复前检查条目数量。旧版本保持原样。
v0.3.2 第一次完整通过文件、Docker、远端安装和 Codex 新会话测试。
早期回复全是技术字段,干净 Ubuntu 安装时也缺少明确的依赖处理。
v0.3.3 重写结果格式,v0.3.4 补全安装步骤和依赖说明。
同一批 JSON 的结果检查从 0/12 变成 12/12,最终视频也把安装和真实 PDF 检查完整跑通。
05 · 版本变化
前两个版本有明确问题,所以没有拿来做最终演示。后面的版本分别补运行、结果表达和安装。
| 版本 | 实际结果 | 处理 | 状态 |
|---|---|---|---|
| v0.3.0 | 大 PDF 通过符号链接输入时,脚本量到的是链接本身,不是真实文件大小。 | 保留这个版本,在后续版本修复。 | 未采用 |
| v0.3.1 | 运行问题修好,但回复写了 6 条内容,超过约定的 3–5 条。 | 增加回复前检查,不修改旧标签。 | 未采用 |
| v0.3.2 | 包装脚本、46 份文件、Docker、远端安装和 12 条 Codex 测试全部通过。 | 作为第一个正式通过测试的版本。 | 测试通过 |
| v0.3.3 | 同一批 JSON 的结果表达检查从 0/12 提升到 12/12,运行逻辑没有改。 | 用户先看结论,技术字段留在原始 JSON。 | 改写结果 |
| v0.3.4 | 干净 Ubuntu 可以按一个入口补齐依赖并完成安装验证。 | 用于本页的安装和真实 PDF 演示。 | 当前版本 |
06 · 实测范围
数字来自仓库里的运行记录、验证索引和最终视频。截图只用来展示,判断仍以实际结果为准。
本页使用 DeckProbe、DeckProbe Skill 两个本地仓库的代码和运行记录,并核对了正式标签 v0.3.4 与最终视频。业务收益还没有实测,本页不做收益承诺。