OpenProgram / Provider design / implementation handoff

请求录制与严格离线回放入口

设计审计基线：990bfe36e625579443e1cb01a1b3266c8dbd0e87；生命周期实现复核提交：99252205957a2850e1203a888a0fa0b403b0c3f7。本页定义产品入口、provider runtime 生命周期、registry 包装、文件安全、严格离线和验证合同，并分别记录设计与实现证据。

01 · 目标、非目标与安全边界

02 · 基线中的当前实现与缺口

03 · 现有 reference corpus 的对应设计

本仓当前参考快照只有 references/pi-ai。本节只描述该快照，不声称覆盖其他版本或整个开源生态。

拒绝的做法：逐 vendor 增加 recorder、通过 HTTP 代理捕获原始流量、用测试 mock 替代产品入口。这些做法分别增加重复实现、暴露未脱敏 wire 数据，或不能覆盖真实 worker 配置。

04 · 总体设计

05 · CLI 与配置合同

CLI 语法

openprogram recordings status [--json]
openprogram recordings record [--name NAME]
openprogram recordings replay <ID-or-PATH>
openprogram recordings off
openprogram recordings list [--json]
openprogram recordings show <ID-or-PATH> [--json] [--content]
openprogram recordings delete <ID> [--yes]
openprogram recordings prune --older-than-days N [--dry-run] [--yes]

配置 schema

{
  "record_replay": {
    "mode": "off",          // off | record | replay
    "file": ""              // managed ID or explicit filesystem path
  }
}

openprogram config set 仍可逐项修改；推荐的 recordings record/replay/off 用 setup.update_config() 一次写两个字段，避免中间状态。配置仅在 initialize_provider_runtime() 从 NEW 转入 INITIALIZING 时读取，READY 或 FAILED 后不再重读。修改后必须重启相关进程；命令输出必须明确打印这一点。管理命令本身只检查和更新配置，不触发 runtime 初始化。

06 · Registry 包装与生命周期

导入合同

import openprogram.providers 只完成 Python API 定义、模型 API 导出以及既有静态模型模块加载。它不得调用 register_builtins()、不得读取 record_replay 配置、不得打开录制文件、不得安装 transform，也不得通过导入 auth adapter 改变凭证注册表。这个合同用隔离子进程测试验证，不以代码注释代替；本任务不承诺清除模型目录模块已有的其他只读初始化。

职责与接口

api_registry 保留 register_api_provider(api, provider)、get_api_provider(api) 和一次性 transform。transform 必须同时处理初始化前已有的注册项和初始化后新增的注册项。

configure_provider_transform(transform)
  - 同一进程只允许设置一次；重复同值是 no-op，冲突值抛 RuntimeError
  - 保存 original provider，不对已经 transformed 的 provider 再包装
  - 原子地替换当前 registry 的全部值
  - 后续 register_api_provider(api, original) 自动存入 transform(api, original)

record:
  shared_sink = RecordingSink(path)
  transform(api, original) -> RecordingProvider(original, shared_sink)

replay:
  shared_replay = ReplayProvider(path)
  transform(api, original) -> shared_replay
  original 只用于确认该 api 已注册，不保存到 ReplayProvider，不允许委托

所有 record wrapper 共享一个 sink，所有 replay API 共享一个 ReplayProvider，因此 call_index 表示进程内所有 provider API 调用的总顺序，而不是每个 API 各自从 0 开始。direct library 用法继续支持独立构造器；产品激活不得要求调用方逐个枚举 API。

进程级状态

NEW
  └─ initialize_provider_runtime() ─→ INITIALIZING
       ├─ 成功 ─→ READY
       └─ 任意未完成退出 ─→ FAILED（保存不可变 failure descriptor）

• 状态和等待使用一个 threading.Condition；同一时刻只有一个线程执行初始化，其他线程等待 READY 或 FAILED。
• READY 后不再读取配置；配置修改继续遵循 next_start。
• FAILED 只在 built-in 注册阶段出现：runtime 保存 stage、cause type 和脱敏后的 cause message。每个调用方得到新的 ProviderRuntimeInitializationError，字段和消息一致；不得重复使用带旧 traceback 的异常对象。
• record/replay 激活失败不使 runtime FAILED：错误被记录，registry transform 被原子替换为 fail-closed _BlockedRecordReplayProvider，runtime 进入 READY 且 snapshot.mode == "blocked"。任何 provider 调用抛同一诊断，指示运行 openprogram recordings status 或 openprogram recordings off；不解析凭据、不访问网络。
• KeyboardInterrupt/SystemExit 等控制异常在锁内写入 initialization_interrupted failure descriptor 并 notify_all()；初始化线程继续抛原控制异常，等待者和后续调用得到稳定的初始化失败。进程内不重试，重启后从 NEW 开始。
• 构造 RecordingSink/ReplayProvider 和完整校验在 transform 发布前完成；发布失败不得留下部分 registry 替换。
• off/record/replay/blocked/FAILED 的测试隔离使用新子进程，不增加可在生产代码中重置全局生命周期的 API。

Built-in 注册的可见性

register_builtins() 在自身锁内先导入和验证现有内建模块，在局部变量中形成 API provider batch，再由 API registry 一次发布；失败前不改变 API registry，只有完整成功后才设置 registered。Anthropic/Codex/Gemini auth adapter 继续调用各自现有幂等注册函数，但从 package import 移到这个显式阶段。若 auth adapter 失败，provider runtime 进入 FAILED，公共 get_api_provider() 因生命周期门禁不能观察或使用已发布 provider；进程重启后重建。项目当前把 Anthropic/OpenAI/Google SDK 声明为核心依赖，因此不再用包住整个 provider import 的 except ImportError 静默跳过内部缺陷。

显式启动与统一保证

Web 和 worker 在创建恢复线程、dispatcher 或 provider warm-up 线程前显式调用 initialize_provider_runtime()，使无效 replay 在单线程启动阶段失败。公共 get_api_provider() 仍执行幂等检查，覆盖 Python library 调用和未来入口。auth 的延迟 adapter 注册只调用 register_builtins()；它不能因为 replay 文件损坏而失败。

Runtime 构造与 credential 边界

严格离线必须覆盖 create_runtime()，不能只覆盖 stream.py。当前 factory 和 subscription runtime 构造器会在 get_api_provider() 前读取 API key/OAuth。目标实现不重构这些 live runtime：off/record 继续走现有 factory；replay 增加一个 credential-free 分支，只接受调用方显式给出的 provider/model，或 AGENTIC_PROVIDER/AGENTIC_MODEL、配置文件 default_provider/default_model 中已有的非凭证选择。没有这些选择时立即返回 replay 配置错误，不继续执行 CLI 探测或 AuthStore 探测。

replay factory 不实例化 subscription runtime，而是按 PROVIDERS 的 provider→model namespace 纯元数据构造基础 Runtime。plain provider 已有该字段；三个 subscription entry 新增 model_namespace：claude-code→anthropic、openai-codex→openai-codex、gemini-cli→gemini-subscription。API-routed provider 继续使用其模型目录 namespace。这个分支不读取录制文件来推断原始 factory provider：现有 v1 request 只保存 wire-level Model，无法区分 claude-code 与 anthropic 等共享 wire 的入口，也不能把多 API 文件的首个 model 当成所有后续 runtime 的 identity。请求进入 ReplayProvider 后由现有完整 request comparison 校验最终 Model、context、tools 和 options；不匹配按既有 ReplayMismatch 报告。

与 OpenProgram 执行模型的关系

record/replay 是 provider 测试与故障复现能力，不是 workflow 能力。Agent loop、Runtime retry、工具执行、Session 持久化和 DAG 状态仍按正常代码执行；仅 registry 返回的 provider 从 live/record provider 变为 ReplayProvider。因此 replay 可以验证这些上层组件在同一模型事件序列下的行为，但不会恢复历史 Session、重放工具副作用、回滚文件或定义执行步骤。

07 · 录制文件、严格解析与并发写入

格式策略

新 writer 继续写 format_version=1 和现有四类行。call_end.outcome 是可选诊断字段：缺失等同 complete，因此旧 v1 文件和旧 reader 保持兼容；它不改变事件模型或 request 匹配。header 可增加可选元数据；v1 reader 必须忽略未知 header 字段。任何 request/event 的必需字段或语义发生变化时才升级版本。

{"type":"header","format_version":1,
 "recording_id":"20260811T134502Z-f7a29c1d",
 "created_at":"2026-08-11T13:45:02Z","redaction_version":1}
{"type":"request","call_index":0,"model":{...},"context":{...},"options":{...}}
{"type":"event","call_index":0,"event_index":0,"event":{...}}
{"type":"call_end","call_index":0,"event_count":1,"outcome":"complete"}

recording_id、created_at 和 redaction_version 只用于管理和诊断，不参与请求比较。旧 v1 文件没有这些字段时仍可回放，list/show 从 stat 与内容推导缺失信息。

严格读取不变量

并发写入合同

1. RecordingSink 持有进程内 threading.RLock；每条 JSONL 的序列化和 append 在同一临界区完成。
2. 每次 append 以 os.open(O_WRONLY | O_CREAT | O_APPEND, 0o600) 打开数据文件，并用 openprogram._compat.flock(fd, LOCK_EX) 提供跨进程互斥。
3. 首次创建 header 与分配下一个 call_index 都在文件锁内完成。最小实现可在 begin_call 时扫描现有 request 的最大索引；这是诊断文件路径，先接受 O(n) 分配，只有测得大文件成为瓶颈时才增加 sidecar counter。
4. 一条完整 UTF-8 JSON 加换行使用循环 os.write 写完；不得依赖一次 write 写全。
5. request 和每个 event append 后不强制 fsync；call_end 写入后 fsync。这样崩溃最多留下一个可被严格 parser 识别的未完成 call。
6. 跨线程/跨进程 event 可以交错，但 call_index 与 event_index 把每个调用完整分组。回放顺序按 request 的 call_index。

08 · 0700/0600、路径约束与脱敏

文件系统

• managed root 为 get_state_dir() / "recordings"；增加 get_recordings_dir()，创建后收紧到 0700。
• managed recordings root 无论新建还是已存在，在 POSIX 上均收紧到 0700；库级显式外部 RecordingSink(path) 不修改父目录权限，也不跟随父目录 symlink 执行 chmod。数据文件在第一次写入时以 0600 创建。record 写路径每次打开已有文件后调用 openprogram._compat.restrict_to_user(path)，修复历史宽权限；随后以 fstat 确认 mode 为 0600，无法保证时拒绝录制。
• replay 读取区分 managed 与显式外部路径：managed 文件可收紧为 0600；显式外部文件只验证当前为普通文件且 mode 已是 0600，不主动 chmod。外部文件权限过宽时明确拒绝，由文件所有者处理。
• 锁文件同样以 0600 创建。list/show/delete/prune 使用 lstat 拒绝 symlink，并在 resolve 后验证 managed root 包含关系。
• record 模式使用 O_NOFOLLOW（平台支持时）和 O_EXCL 初始化新文件；不得截断已有录制。名称冲突直接失败。没有 O_NOFOLLOW 时，在持有 managed root 的目录 fd 下按 basename 打开，并用 lstat/fstat 的设备号、inode 与普通文件类型复核打开结果。
• delete/prune 只删除后缀为 .jsonl 的普通文件；不递归、不跟随 symlink、不删除显式外部路径。

脱敏合同

• remove_secret_values() 在任何序列化之前执行，record 模式不存在关闭选项。
• 保留当前大小写不敏感的敏感字段集合，并覆盖嵌套 dict/list。字段名识别 -/_ 与 camelCase 分段；以 token、key、secret、password 结尾的复合 header/option 名同样整体脱敏，例如 X-Session-Token、service_api_key、refreshToken、clientSecret。不匹配 token_count/tokenCount 等非凭据计数字段。
• value pattern 覆盖 Authorization 常见 scheme（Bearer、Basic、Bot、token、Key）、URL userinfo，以及 query 中当前已实现的 api_key/apikey/access_token/token；新增 query key 必须同时提交实现和测试，不能只写入设计状态。
• 不采用通用“高熵字符串”规则：它会不稳定地改写正常 prompt，导致回放 mismatch。新增 provider 凭证形态必须以确定 pattern 和回归测试加入。
• record 与 replay 必须使用同一个 redaction_version 分派。当前 v1 文件没有该字段时按 redaction v1 处理。

09 · 严格离线回放合同

回放的离线保证由结构约束实现，而不是依赖调用方自觉避免网络。

1. replay transform 对所有已注册和后注册 API 返回同一个 ReplayProvider。
2. ReplayProvider 不保存 original provider，不 import vendor transport，不提供 fallback。
3. stream.py 必须先取得 provider；当 provider 声明 requires_credentials = False 时，不调用 resolve_provider_key()。
4. 文件在 transform 安装前完整解析和验证；损坏文件阻止 worker 启动，不能启动到一半后才失败。
5. 未知 API 仍由 registry 返回 missing-provider 错误；不得为了回放动态加载真实 provider。
6. request mismatch、调用耗尽、未知事件、事件校验失败都直接抛异常；任何失败都不能切到真实 provider。

测试必须同时替换 socket.socket.connect、socket.create_connection 和共享 HTTP client 构造函数为失败函数，并断言正常回放、mismatch、损坏文件和调用耗尽四条路径都没有尝试网络。

10 · 录制文件管理

list/show 使用同一 inspect_recording(path) 纯函数，replay 激活也使用同一严格 parser。不能为管理命令另写一套宽松解析器。prune 的年龄来源使用 stat mtime；header created_at 只显示，不作为删除依据，避免手工编辑 header 改变保留行为。

11 · 失败语义

12 · 兼容与迁移规则

• 库 API：RecordingProvider(provider, path)、ReplayProvider(path)、recording_path、call_count 和现有异常属性保持。
• 现有 v1 文件：继续读取；新增严格检查会拒绝之前被宽松 reader 忽略的截断、孤立或重复行。这是有意的 fail-closed 行为。
• 旧 writer：header 只有 type/version 仍有效；管理元数据从 stat/内容推导并标为 legacy-v1。
• 默认运行：mode=off 时首次实际 provider 获取完成一次配置快照，随后请求不增加配置文件 I/O；provider identity 和 credential 解析顺序保持。
• 配置：缺少 record_replay subtree 等同 off。不会从环境变量自动启用，也不会扫描并选取“最新录制”。
• 导入：import openprogram.providers 不再保证 built-in registry 已填充；实际 provider 获取和显式 register_builtins() 承担该责任。公开 stream/complete API 行为保持。
• 管理恢复：删除 _OPENPROGRAM_RECORDINGS_MANAGEMENT；status/off 等恢复能力由结构分离保证，不再依赖 import 顺序。
• Markdown：record-replay.md/.zh.md 与本页同步当前 CLI、严格离线和生命周期边界，不再保留“仅测试库模块”的过期描述。
• 未来格式：版本升级使用独立 parser；不原地改写用户文件。只在有明确字段语义变化时提供显式 migrate 命令。

13 · 最小实现文件

不修改 vendor provider、off/record 的 live factory、Web routes、Node CLI 或录制格式。runtime factory 只增加 replay 分支。若实现时发现调用绕过 get_api_provider() 或插件绕过 register_api_provider()，应改回统一边界，不能在 recorder 或生命周期模块增加 vendor 特例。

14 · 验收与测试矩阵

实现后最小验证命令

pytest -q tests/providers/test_provider_initialization.py tests/providers/test_record_replay.py tests/providers/test_record_replay_registry.py tests/providers/test_record_replay_cli.py
  pytest -q tests/providers/test_scripted_provider.py tests/providers/test_registry_from_config.py tests/unit/test_usage_stream_chokepoint.py tests/unit/test_auth_methods.py tests/unit/test_web_config_schema.py tests/unit/test_config_write_safety.py
python -m openprogram recordings --help
python -m openprogram config get record_replay.mode
python -m tools.docs_site.build
python -m tools.docs_site.checklinks
git diff --check

15 · 实现与验证记录

设计来源：当前 OpenProgram provider 实现、CLI/config 入口、测试，以及仓内 references/pi-ai 快照。更新实现状态时必须附代码符号、测试或 commit；不得把“设计已写”标为“功能已实现”。