groundwork

---

你已经有了一个原型：你的文档、一个模型，以及有用的输出。但你还缺少让它能够负责任地投入使用所需的整套机制——隐私预处理步骤、基于自身失败案例构建的评估，以及一道门禁，防止悄然进行的提示词调整将会编造内容的系统部署上线。这套机制通常需要 ML 工程师。Groundwork 会为你搭建起来。

Groundwork 的构建单元是部署模式，而非产品——可以把它们想成用于构建可信 AI 部署的 Terraform 模块。groundwork init <archetype> 会为一种模式搭建完整的测试框架：

Archetype	模式	状态
document-qa	文档 → 检索 → 有依据的回答 → 人工审核	✅ 已发布
extraction	文档 → 结构化字段 → 架构验证 → 人工审核	✅ 已发布
研究综合	问题 → 证据 → 综合分析 → 人工审核	计划中 — 请参阅路线图

每项检查都是确定性的：输入相同，结果每次都相同——无需 LLM 评判器，检查本身也无需 API 密钥。

快速入门 — 60 秒，无需 API 密钥

git clone https://github.com/nickjlamb/groundwork.git && cd groundwork
npm install && npm run build
npm run demo          # document QA: the whole loop passes, fully offline
npm run demo:break    # the system starts fabricating — watch the gate go red

✗ GROUNDING demo-savings: ungrounded number "14" — not in the provided context
✗ GROUNDING demo-unanswerable-appeals: unanswerable question — the answer did not abstain

结构化提取也可以使用同样的流程：

npm run demo:extraction         # documents → fields, every check green
npm run demo:extraction:break   # a guessed date of birth, a dropped field — red, by name

✗ EXTRACTION demo-referral: SCHEMA: /referral_date must be string
✗ EXTRACTION demo-referral: FABRICATED field "date_of_birth": document does not state it (got "12 April 1988")

构建失败正是产品的价值：编造的数字、猜测的字段或未能弃答都会导致 CI 失败，而不是让用户投诉。

准备好用于你自己的系统了吗？

npm install -D @pharmatools/groundwork
npx groundwork init                # document QA
npx groundwork init extraction     # structured extraction

工作原理

你编辑的内容	Groundwork 运行的内容	门禁执行的要求
adapter.mjs — 一个文件：用于文档问答的 answer()，用于抽取的 extract()	预先脱敏（Redacta）——标识符会在本地转换为带标签的令牌，然后才会发送任何内容	check --baseline 将一次良好运行固定为最低标准
datasets/cases/*.json — 根据真实问题和真实文档手工标注的黄金案例	该原型的评估（OpenGATE）——文档问答：事实有依据 · 数字可追溯至上下文 · 能够弃答。抽取：模式有效性 · 字段与黄金答案的准确度 · 不编造字段	脚手架生成的 GitHub Action 中的 check --ci 会阻止任何低于该标准的 PR
groundwork.config.json — 原型、脱敏、评估和门禁设置	成本分析——测量令牌用量，并按杠杆优先顺序计算节省量（缓存 → 批处理 → 精简 → 路由）	高风险输出仍由人工审核——门禁只是最低标准，并非认证

对于抽取，一个模式选择就能完成大部分安全工作：可空性就是弃答约定。系统必须始终找到的字段不可为空；文档可能未提及的字段则可以为空，系统会为其返回 null——未知 → null，绝不猜测。如果在黄金答案为 null 的字段中猜测了值，门禁会按名称报错：FABRICATED field "date_of_birth": document does not state it

示例

示例	展示内容	运行方式
demo/	文档问答：在一个微型本地系统中跑完整流程，并由门禁按名称捕获编造内容。不联网。	npm run demo / npm run demo:break
demo-extraction/	结构化抽取：模式验证、字段准确度，以及门禁指出猜测的出生日期和被遗漏的必填字段。不联网。	npm run demo:extraction / npm run demo:extraction:break
examples/claude-doc-qa/	一个由 Claude 驱动的真实系统：仅根据文档作答的提示词、提示词缓存、密钥门控评估，以及为 groundwork cost 提供数据的用量测量——另附模拟 API，让整个流程能在 CI 中离线运行。	npm run example:mock（离线）/ npm run example:check（实时）
examples/claude-extraction/	Claude 从虚构的转诊信中填充模式：在提示词约定中将未知值设为 null、将模式作为缓存前缀，以及由门禁捕获猜测的出生日期——另附模拟 API，支持 CI 离线运行。	npm run example:extraction:mock（离线）/ npm run example:extraction:check（实时）

命令

groundwork init [archetype]      scaffold the harness for a pattern (document-qa, extraction)
groundwork check                 redaction self-test + the archetype's eval
groundwork check --baseline      freeze this run as the regression floor
groundwork check --ci            exit non-zero on failure or regression vs baseline
groundwork cost                  measured token usage + savings, in leverage order

有两种学习方式：docs/GETTING-STARTED.md 是参考指南（约半小时），课程 则通过由检查点驱动的课程涵盖相同内容——包括破坏性测试：你会故意破坏自己的系统，以证明门禁能捕获问题；还包括一节关于抽取原型的课程。脚手架生成的操作手册（GROUNDWORK.md）位于你的代码库中，团队成员实际会在这里阅读。

在 Claude 中使用

同样的检查也以 MCP 服务（groundwork-mcp，stdio）的形式提供，因此 Claude Code、Cowork 或 Claude Desktop 可以通过对话运行这些检查——对代码库运行 check_readiness，对单个回答运行 check_answer_grounding，对单条记录运行 check_extraction（不需要代码库），以及运行 scaffold_harness、cost_summary：

{ "mcpServers": { "groundwork": { "command": "npx", "args": ["-y", "@pharmatools/groundwork", "mcp"] } } }

此外还有一个 Agent Skill（skills/groundwork-readiness/），它会指导 Agent 运行门禁并如实报告结果——包括拒绝将绿色勾号说成安全认证。

Groundwork 不是什么

Groundwork 是坚实的基础，而非保证。确定性检查可以捕获那些能以确定性方式捕获的问题，但无法证明 AI 系统安全。对于高风险输出——任何涉及健康、金钱、法律地位或安全的内容——在输出送达受影响的人之前，必须由人工审核。数据提取会悄然提高风险：记录会用于辅助决策，因此字段错误就意味着决策错误。脚手架提供的操作手册也特意指出了这一点。

项目

• 状态 — 计划的 3 种模式中，已有 2 种（文档问答、结构化数据提取）发布。先求深度，再求广度：每种模式都妥善完善后，才会开始下一种。请参阅路线图。
• 贡献 — 特别欢迎提交 Bug 报告、黄金案例模式和示例：CONTRIBUTING.md。
• 发布 — 在 GitHub 上标记版本，在 npm 上发布版本，历史记录见 CHANGELOG.md。
• 基于 — OpenGATE（评估）和 Redacta（隐私），两者均为开源项目。

许可证

MIT。init 在你的仓库中生成的所有内容均采用 MIT-0 许可证——归你所有，无需注明出处。