DeckProbe · Demo 汇报

DeckProbe Demo 跑通了。下一步,看怎么接进项目。

这次把安装、Skill 调用和真实 PDF 检查完整跑了一遍。结果能用,边界也清楚:DeckProbe 负责检查文档结构,Skill 负责告诉 Codex 什么时候调用、怎么把结果说清楚。下面重点讲现状、这几轮改了什么,以及有没有必要合成一个仓库。

01 · 结果先说

先看现状:能装、能检查,也知道什么时候该停。

Demo 已经覆盖安装、真实文件检查和异常处理。当前还没有业务使用数据,所以这版适合试用,不适合直接下长期投入结论。

现在可以做什么

可以拿 DeckProbe Skill 做小范围试用。它能在 Linux 上检查一份本地 PDF、Office 或 iWork 文件,告诉用户文件是否适合交给下一个文档工具。它不做 OCR、内容摘要,也不能代替安全扫描。

01 / PRODUCT

它解决什么问题

文档交给 AI 或其他工具前,先检查格式、页数和结构信号,避免拿错文件继续处理。

02 / INSTALL

用户怎么安装

把一个 GitHub 地址发给 Codex。Codex 会补依赖、安装官方 CLI 和 Skill,然后做一次校验。

03 / QUALITY

出错时怎么处理

输入不合适、资源不够或检查失败时会直接说明原因,不会拿旧报告顶替这次结果。

04 / DELIVERY

这次交了什么

页面内有安装视频、真实 PDF 结果、原始 JSON 和文字记录,开发可以继续查,汇报也够用。

给同事的安装口令

打开 Codex,直接发下面这句话。

Codex 会按项目说明补齐当前环境缺少的基础依赖,安装官方 DeckProbe CLI 和最新版 Skill,并在结束前完成验证。

请按 https://github.com/nexteamer/deckprobe-skill 安装最新版 DeckProbe Skill,自动补齐依赖并验证。

02 · 现场演示

演示从安装开始,中间步骤没有跳过。

环境是干净的 Ubuntu 24.04。视频里先补依赖并安装正式版,再开一个新会话检查真实《三体》PDF。

最终观看版 · E2E RESULT: PASS
1366×768 · H.264 · 15 fps · 7.8 MB

安装完成后,新会话成功检查了真实 PDF。

使用的是 Skill v0.3.4 和官方 DeckProbe CLI 2.3.1。文件识别为 189 页,原始 schema-v2 JSON 已保留,整条演示路径通过。

03 · Skill 怎么组装

DeckProbe 是检查工具,Skill 是 Codex 的使用说明。

真正读取文件的是 DeckProbe CLI。Skill 不解析文档,它只规定哪些请求可以调用 CLI、调用前要检查什么,以及结果应该怎么写给用户。两边目前放在不同的仓库。

一句话看懂两边的分工

DeckProbe CLI 检查文件并生成 JSON;DeckProbe Skill 让 Codex 知道什么时候运行这个命令,并把 JSON 改写成用户看得懂的检查结果。原始 JSON 仍然保留,开发排查时可以直接查看。

01 · 文件请求

用户给出文件

一次只检查一份本地 PDF、Office 或 iWork 文件。

02 · 规则判断

Skill 先判断

确认这个请求该不该运行,以及文件和环境是否符合要求。

03 · 执行检查

包装脚本运行 CLI

检查条件满足后,脚本调用一次官方 deckprobe

04 · 返回结果

用户看到结论

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。两者都只记录本次运行,旧文件不能当成新结果。

ONE REPOSITORY?

能不能合成一个仓库?能,但现在没必要急着做。

如果只是希望用户少记一个地址,现有方案已经做到了:用户把 Skill 仓库地址发给 Codex,安装说明会继续安装官方 CLI。真正合仓解决的是开发维护问题,不是当前 Demo 的使用问题。

额外 EFFORT:中等偏大

代码搬过去不难,后续发版才是主要工作。

本地 DeckProbe checkout 里已经有一份早期 Skill 副本,但它没有被上游仓库跟踪,而且已经落后于正式 Skill。直接复制只能得到一份新副本,不能解决同步和发布问题。我的建议是:Demo 阶段维持分仓;真要合仓,交给开发按一次正式的单仓发布改造来做。

合仓需要补的工作

  1. 01先解决仓库归属。CLI 在 deckflow/deckprobe,Skill 在 nexteamer/deckprobe-skill,需要上游接受 Skill 目录和维护责任。
  2. 02重新设计版本号。CLI 使用 v2.x,Skill 使用 v0.x;现有 Cargo 发布任务会响应版本标签,不能直接把两套标签混在一起。
  3. 03合并发布检查。Rust 构建、二进制发布、Skill 测试、干净安装和 Codex 实测都要进入同一套 CI。
  4. 04改安装文档和升级路径,并验证单仓发布后仍然只使用官方构建的 CLI,没有引入另一份二进制。
PACKAGE MAP

Skill 目录里只有五个主要文件。

一个总控文件,另外四个文件分别负责入口、执行、结果说明和安装。

SKILL.md总说明

告诉 Codex 什么时候用、怎么用,以及哪些事情不要做。

agents/openai.yaml登记入口

保存名称、简介和默认提示词,让 Codex 能找到这个 Skill。

scripts/probe-document.sh运行脚本

检查文件和机器条件,然后调用官方 CLI。

references/result-interpretation.md结果写法

规定 JSON 里的信息怎么整理成用户看到的五段结果。

docs/INSTALLATION.md安装说明

说明安装、验证、升级、回滚和卸载。

SKILL.MD

SKILL.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,改运行逻辑看脚本,改回复看解释规则,改安装步骤看安装文档。

agents/openai.yaml · 让 Codex 找到 Skill

这个文件只登记入口信息,不执行文档检查。

名称和简介默认提示词是否允许自动触发

probe-document.sh · 负责把检查跑稳

它先检查文件、内存和 CLI,再运行一次 DeckProbe。成功写 JSON,失败保留诊断和退出码。

Linux 和单文件检查文件大小与内存CLI 路径和版本一次正式调用结果有效性

result-interpretation.md · 规定结果怎么写

它决定什么情况下建议继续、复核、输入密码或停止,也规定五段结果里放哪些信息。

建议优先级五段结果格式不同文档的重点缺失值和失败措辞发送前检查

INSTALLATION.md · 说明怎么装和怎么维护

从干净 Ubuntu 开始,写清官方 CLI、Skill 安装、第一次使用,以及后续升级和卸载。

首次安装安装后验证资源限制升级与回滚卸载

04 · 几轮怎么做成

这几轮到底改了什么。

第一轮先判断项目值不值得用,第二轮把它接进 Codex。后面两轮都在修实测中发现的问题,没有另起新方向。

第一轮 · 看项目

先确认 DeckProbe 能不能解决实际问题

当时的问题

README 讲了很多技术细节,但看不出真实文件跑起来怎样。Docker Hub 当时也无法正常拉取。

怎么处理

改用官方静态二进制,并从源码确认 CLI、格式识别和资源限制。

做到什么

结论很明确:它适合放在文档处理前做检查,不是给普通用户读文档的工具。

第二轮 · 接进 Codex

把命令行工具做成可安装的 Skill

当时的问题

只有 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 · 实测范围

这些用例都实际跑过。

数字来自仓库里的运行记录、验证索引和最终视频。截图只用来展示,判断仍以实际结果为准。

46文件矩阵41 份成功报告,5 份预期错误报告。
20/20包装器合同尺寸、预算、错误、缺依赖与旧结果污染都覆盖。
9Docker 用例非 root、只读根目录、断网和缺依赖路径均执行。
12新会话旅程10 条触发检查,2 条不触发或拒绝路径。
189真实 PDF 页数《三体》实测,页数来自本次原始报告。
E2E完整用户路径从一句安装口令到第一次真实文件结果。

已经证明

  • 干净 Ubuntu 环境可以从一个 GitHub 入口完成安装和验证。
  • 一份本地 PDF、Office 或 iWork 文件可以稳定进入标准检查。
  • 结果能保留事实、边界和原始 JSON,同时让非技术读者看得懂。
  • 大文件、失败、缺依赖和不应触发的请求不会被伪装成成功。

还没证明

  • 还没有 Windows、macOS、URL 或批量文档支持。
  • OCR、全文摘要、渲染、转换和安全认证均不在范围内。
  • 真实业务里能节省多少时间、减少多少错误,本轮没有数据。
  • 要不要长期投入,应该由下一阶段的小范围业务试用来决定。

07 · 建议

先接一个真实入口试用;合仓让开发另开任务评估。

下一步选一个真实文档入口,记录人工检查时间、分流错误和失败处理成本。合仓会增加发布和维护工作,不建议混在 Demo 收尾里一起做。

请按 https://github.com/nexteamer/deckprobe-skill 安装最新版 DeckProbe Skill,自动补齐依赖并验证。

本页使用 DeckProbe、DeckProbe Skill 两个本地仓库的代码和运行记录,并核对了正式标签 v0.3.4 与最终视频。业务收益还没有实测,本页不做收益承诺。

019feb70-6b2d-7881-b6a9-bbead632fd53
019feb70-6328-72a1-a7d4-b20d0c425cba