Skip to content

P-A-R 长期战略

状态: 战略定义完成(2026-06-02) 维护者: P-A-R Contributors 变更机制: 战略变更需要新文档 + commit message 明确说明原因


1. 价值定位

PAR = OCaml 圈的 LangChain + LangGraph 等价物

覆盖两类场景: - MVP 友好:问答机器人、翻译工具、基础 RAG - 严肃生产:状态机、Human-in-the-Loop、多 agent 协作(typed handoff)

核心承诺: - 集成组件 + 提示词管理(学 LangChain) - 类型化状态保证(学 LangGraph) - 不偏向学术研究,也不偏向快速原型


2. 目标用户

LLM 后端工程师

特征: - 工作中需要构建 agent 系统作为产品一部分 - 重视部署性(Docker, k8s, opam) - 关心 runtime overhead、稳定性、故障恢复 - 可能从 Python / Go / Rust 后端转来

非目标用户(避免做错方向): - 纯学术研究者(要的是 paper,不是 SDK) - 终端用户(要的是产品,不是 SDK) - 纯前端工程师(agent runtime 跟前端无关)


3. 差异化主张

vs LangChain (Python)

  1. 类型严谨:"LangChain 能崩的错,PAR 在 build 时就报"
  2. Eio 轻量:"同负载下 PAR 内存/CPU 仅为 Python 项目的 1/5"
  3. 原生多 provider:OpenAI / Anthropic / Ollama / Custom 零成本切换

vs pi-agent-core (TypeScript)

  1. OCaml 生态唯一选择:他们不重叠,PAR 是 OCaml 圈唯一选项

vs AutoGen / OpenAI Agents SDK / CrewAI

  1. 类型化多 Agent 切换:handoff 通过 typed ADT constructor 实现而非 JSON 约定(v0.4+ 规划)

4. 优先级(资源分配)

按重要性排序的资源分配原则:

优先级 维度 理由
1 类型严谨 Q3 主张 #1,是 PAR 不可被复制的核心优势
2 并发性能 Eio 是 PAR 技术差异化(Q3 主张 #2)
3 多 provider 适配 Q3 主张 #3,变现点(实际项目用得到)
4 OCaml 生态定位 受众天花板,长期需考虑但不是紧急

应用规则:当时间紧张时,砍 4 → 砍 3 → 砍 2 → 砍 1。


5. 发布策略

opam + PyPI 双发布

包 渠道 用途
par opam OCaml SDK(OCaml 后端)
par_runtime PyPI Python 包,通过 ctypes 调用 par_capi.so(Python 后端)

不做的发布: - ❌ Docker(v0.x 不做,让用户自己打包) - ❌ npm(不是 TS 项目) - ❌ Conda(OCaml/Python 都不走 Conda)


6. 借鉴来源(已验证项目)

项目 借鉴什么 不借鉴什么
pi-agent-core (58.9k stars) Steering/Follow-up 队列、onUpdate 工具流式、system_prompt 单字符串模式 Session tree、compaction、thinking levels、custom message types
LangChain / LangGraph system_prompt 单字符串模式、集成组件范式、3 表持久化(checkpoints + blobs + writes) 过度抽象、Python 动态类型
OpenAI Agents SDK Handoff 合成工具模式(transfer_to_)、RunContextWrapper DI 容器(不进 LLM) 无内置持久化、Python-only
AutoGen BaseChatMessage/BaseAgentEvent 事件模型、save_state/restore_state 序列化 Swarm 的隐式 routing
Google ADK EventActions(state_delta/transfer_to_agent)、三级状态前缀(app:/user:/session:) 过度复杂的状态管理体系
PydanticAI 结构化输出 = 合成工具、RunContext 承载 deps Python type hints 不适用于 OCaml
Anthropic Claude append-only content blocks(text/tool_use/tool_result)、Session Runner 断线恢复 断线恢复是远程 API 问题,PAR 不需要
Vercel AI SDK system 独立属性设计、provider 抽象 不需要(Vercel 绑定云)
LiteLLM 透传到 provider 模式 messages 数组风格(我们用单一字符串)

7. 防呆清单(明确不做的)

项目 不做的理由
Session tree + branching(完整版) PAR 用户用 workflow + PG 持久化,不是交互式 IDE。窄化:支持单链 handoff(agent A → B),不支持树状分支
Compaction(LLM 摘要压缩) PAR 走显式 context_strategy,不依赖隐式摘要
Thinking levels Provider-specific 概念,PAR 走 provider-agnostic
Custom message types TS declaration merging 是 TS-only 特性
~~Skills system (SKILL.md)~~ Removed 2026-06-24 — see §8 changelog. Skill system shipped in v0.5.2 with typed design differentiation.
Docker 官方镜像 v0.x 不做,让用户自打包
学术 paper 投稿 战略转向工程价值(2026-06-02 决议:删 v1.0 论文)

8. 变更日志

日期 变更 原因
2026-06-02 战略首版 启动 v0.3.0 前的 P0 阻断项讨论结果
2026-06-02 删除论文方向 论文不是 PAR 的核心价值(学术贡献有限,工程价值高)
2026-06-02 借鉴 pi-agent-core 58.9k stars,验证过的设计模式可移植
2026-06-09 放弃"不做多 agent 协作"限制 主流框架研究完成:OpenAI Agents/LangGraph/AutoGen/CrewAI/Google ADK/PydanticAI 均支持 handoff。PAR 窄化为 typed ADT handoff(单链 A→B),不做树状分支
2026-06-09 新增 7 个借鉴来源 LangGraph(3 表持久化)、OpenAI Agents(handoff + DI)、AutoGen(序列化)、Google ADK(EventActions)、PydanticAI(结构化输出)、Anthropic(content blocks)、CrewAI(任务上下文)
2026-06-09 发布策略:beta-first 开发阶段版本号带 -beta 后缀,只有用户明确说"发布正式版"时才执行 release 操作并去掉后缀
2026-06-21 v0.4.8 stable 发布 首个 stable release(Runtime.invoke_structured)。GH Release + opam-repository PR #30086 已提交;PyPI 待上传。关键里程碑:项目首次进入"用户可安装"状态
2026-06-21 分发渠道首次落地 opam-repository PR 提交(ocaml/opam-repository#30086,含 par + par_cli),GH Release binaries (linux-x64, macos-arm64) 首次提供,install.sh 验证可装。PyPI par-runtime 待用户配置 token 后上传
2026-06-21 PyPI 三次 P0 失败 → 转向 v0.5.0 重设计 v0.4.8 缺 .so(PAR-0qf)、v0.4.9 glibc 2.38 太新(PAR-8cs)、v0.4.10 setuptools<61 UNKNOWN 文件名(PAR-cog)。根因:release pipeline 缺端到端验收测试 + build 环境不固定。用户决定 B 路径:不再发 v0.4.x hotfix,作为 v0.5.0 Track A 重设(manylinux + auditwheel + 验收门)。详见 docs/release-pipeline-redesign.md
2026-06-21 决定反转:v0.4.11 在 v0.4.x 系列彻底修,不推 v0.5.* 用户改主意:希望在 v0.4.11 彻底解决(不是 v0.5.*)。v0.4.11 scope: setuptools upgrade + ubuntu-22.04 pinning(已 v0.4.10 完成 binary 部分)+ 3 平台 acceptance test workflow(Debian 12/Ubuntu 22.04/Ubuntu 24.04)+ 本地 dry-run script + release.md E2E 程序文档。v0.5+ stretch:manylinux glibc 2.17、ARM64、macOS wheel、OIDC auto-upload。准备工作(roadmap + 脚本骨架 + bd 重定向)已完成,下个 session 执行。
2026-06-21 战略教训 "本地编译产物 QA ≠ CI 产物 QA" — install-dev 覆盖本地 binary 掩盖了 GH Release binary 的 glibc 问题。今后所有 release 验证必须在隔离环境(容器/沙箱 venv)下载实际产物测试
2026-06-21 决定反转:v0.4.11 在 v0.4.x 系列彻底修,不推 v0.5.* 用户改主意:希望在 v0.4.11 彻底解决(不是 v0.5.*)。v0.4.11 scope: setuptools upgrade + ubuntu-22.04 pinning(已 v0.4.10 完成 binary 部分)+ 3 平台 acceptance test workflow(Debian 12/Ubuntu 22.04/Ubuntu 24.04)+ 本地 dry-run script + release.md E2E 程序文档。v0.5+ stretch:manylinux glibc 2.17、ARM64、macOS wheel、OIDC auto-upload。准备工作(roadmap + 脚本骨架 + bd 重定向)已完成,下个 session 执行。
2026-06-21 v0.4.12 scope: 工作流审计 + 新 CI 工作流 + OIDC + manylinux scaffold 用户决策:"直接用 v0.4.12 把这些事做了",澄清"老的 Linux 我觉得完全可以不必兼容"(即放弃 manylinux2014/CentOS 7)。v0.4.12 实际 scope: 修 GH Release 三方竞争(release.yml vs pypi-publish.yml vs opam-publish.yml);标准化 opam 包列表(弃用 *.opam 通配符);加 nightly.yml、codeql.yml(仅 Python+Actions,OCaml 不在 CodeQL 支持列表)、dependency-review.yml;加 Python 3.8-3.13 矩阵;加 OIDC PyPI trusted publisher(待用户在 pypi.org 注册);加 manylinux Dockerfile 作为 v0.4.13+ 的脚手架。完成于 v0.4.13: manylinux wheel 已启用并发布(par_runtime-0.4.13-py3-none-manylinux_2_28_x86_64.whl,11.3 MB)。未使用 dummy _loader.c —— 现代 auditwheel v6+ 默认开启 allow_graft=True,会扫描 wheel 内所有 ELF 文件(包括通过 package_data 提供的 ctypes-loaded .so),无需 dummy ext 制造 DT_NEEDED。推迟到 v0.5.0 (MINOR): ARM64 Linux wheel、macOS universal2 wheel(新增平台 = MINOR per SemVer §7)。
2026-08-07 v0.8.6 — 流式 HTTP 错误透传修复 Bug:流式 LLM 调用收到非 2xx HTTP 响应时静默吞掉错误(do_request_streaming 缺状态码检查,错误体被当作 SSE 解析后丢弃,返回 Ok { chunks_received = 0 })。修复:在 HTTP 客户端层补状态码检查并 raise Http_status_error,激活两个 provider 已存在但属于死代码的异常处理器。1504 tests。决策:用户选择直接发稳定版 v0.8.6(跳过 beta),暂不推 opam-repository。Pre-Bump Gate 用 FORCE=1(v0.8.6 不在 ROADMAP)。
2026-08-15 【API级+架构级变更】一等取消 + 可行动工具错误(v0.10.0 stable, 2026-08-15 发布) 变更前: 取消通过 Eio.Cancel.Cancelled 异常传播,错误面混杂 Timeout / Internal,无法区分用户主动取消与超时;工具拒绝消息只说"rejected"不解释原因,模型在 ReAct 循环中无法学会正确重试;edit 工具 old_text 未找到时静默成功(最严重缺陷类别)。变更后: (1) 新增 cancel_reason ADT(User_cancelled | Guard_cancelled of string)+ error_category.Cancelled of cancel_reason 变体;Cancellation.request_cancel 改为 cancel_reason -> unit(先到先得);取消在三个检查点生效(循环顶部/工具分派前/逐 chunk);取消返回 Error (Cancelled reason, recovered_conversation) 且对话始终 provider 重放有效。(2) 新增 tool_error.ml 模块:[workspace]/[bash-policy]/[cancelled] 标记,四种 workspace 拒绝消息(路径遍历/冒号/绝对路径在外/受保护位置),edit 工具 old_text 未找到报错,bash 策略拒绝指出策略名和命令名。设计原则:在拒绝点教学而非 system prompt。(3) Python dispatch-queue trio(invoke_start/invoke_poll/invoke_cancel)。影响范围: types.mli(新 ADT + 新 error_category 变体)、cancellation.mli(request_cancel 签名变更)、engine.ml(三处检查点 + 合成消息)、tool_error.ml(新模块)、builtin_tools.ml(所有文件工具 + bash + edit 描述更新)、bindings/python/runtime.py(三个新方法)、6 个 doc 文件(EN+ZH)。回退方式: revert 相关 commits,恢复 request_cancel 为 unit-param,删除 tool_error.ml,恢复 edit 静默成功行为。
2026-10-13 【API级+架构级变更】工具能力三件套:apply_patch + Agent as Tool + 渐进式工具加载(v0.11.0-beta 列车,设计定稿 2026-08-26,版本号待 bump) 变更前: (a) 无批量改码能力——多处相似代码、跨文件修改、行级增删只能靠 edit 的 exact-string-match,old_text 匹配不上即报错;(b) 无"把专职 agent 当工具调用"的组合手段,只有 handoff(转交控制权、主对话结束),无法表达"派个研究员去查资料、拿结果继续主循环";(c) 工具描述符每次调用全量发给 provider,工具数量上升后 schema 成本线性膨胀,无渐进加载手段;registry 条目仅 descriptor+handler 二元组,无分层概念。变更后: (1) 新增 apply_patch 内置工具(第 24 个):手写 unified diff 解析器(parse_diff : string -> (patch_ast, parse_error) result,无 maintained 的 OCaml diff 库可选,解析器为纯函数故自包含优先),多文件 all-or-nothing 原子应用(内存 staging 全部成功才落盘),dry_run 只报告不落盘,二进制文件识别后跳过不损坏,冲突报 [patch] 教学错误。(2) 新增 Runtime.register_agent_as_tool:子 agent 暴露为可调用工具,与 handoff 互补而非替代。关键实现约束(经 spike 实证,非推测):子运行须以 Explicit Context Fork 包裹 Invoke_context.with_context fresh_ctx 隔离父状态,否则 7 个 Invoke_context 字段全部泄漏;强制 ~quota:None 规避共享 task_semaphore 在 max_concurrent_tasks=1 时的死锁;子 token = Cancellation.create_token parent.switch 以保住 Eio 结构化取消级联且获得独立 cancelled/reason。新增 Invoke_context.depth 传递递归上限(默认 max_depth=3);子运行逐事件不进父流(避免共享 event_bus 的单一 current_session_id 被污染),仅发汇总变体 Agent_tool_completed(含 usage 归因);子运行返回审批请求时转为 [agent-tool] 教学错误而非穿透挂起父流(审批语义绑定具体 agent 会话上下文)。(3) 新增渐进式工具加载:runtime_config.max_tool_schema_tokens : int option(默认 None = 零行为变更)语义为自动切换阈值而非硬裁剪,超阈值则该次调用切换渐进模式;registry 内部分层 Always | Searchable,Always 层为保底地板(地板自身超阈值则告警但不裁剪,避免"核心工具被预算吃掉"的自相矛盾);新增 tool_search 元工具(关键词评分:名称权重 > 描述包含),命中结果注入 per-call 影子列表——分发权威仍是 agent.tools,不存在 registry 兜底路径,模型能调用的恒等于"它见过的 ∪ 本次搜索到的",幻觉工具名走正常 Tool_failed 而非静默分发到模型从未见过 schema 的工具。新增 Tool_budget.estimate_tokens(chars/4 启发式,文档声明为估算)与 metrics 快照的 tool_schema_tokens_estimate + 可见/延迟计数。(4) Python 五层 FFI 链(par_capi.ml → par_ffi.h/.c → _ffi.py → runtime.py)随版本同交付,不留 v0.7.5 式 parity 债务。范围妥协(R2 合规): toolearc首版关键词评分,不做 embedding 语义检索——退役触发:生产用户相关性投诉,或单 runtime 注册工具 >50;MCP 工具自动懒发现延后——退役触发:MCP 重度用户的工具发现摩擦反馈。影响范围: types.mli(Agent_tool_completed 变体 + runtime_config.max_tool_schema_tokens 字段)、runtime.mli(register_agent_as_tool)、invoke_context.mli(depth 字段 + 影子列表载体)、tool_registry.mli(tool_layer ADT + register_searchable/set_layer/searchable_descriptors/layer_of)、engine.ml(预算切换 + find_tool 分发缝)、metrics.ml、新模块 apply_patch.ml/tool_search.ml/tool_budget.ml、tool_error.ml([patch] 标记)、builtin_tools.ml(apply_patch 接线)、par.ml、FFI 四层、Python runtime.py;21 个既有测试文件因 runtime_config 新字段 ripple + 3 个新测试文件 32 用例(test_tool_search 15 / test_agent_as_tool 10 / test_nested_invoke_spike 7);文档 EN+ZH 各 4 文件。回退方式: 全部 additive,无数据迁移,revert 即恢复——删 apply_patch.*/tool_search.*/tool_budget.ml + builtin_tools 追加段 + [patch] 标记;移除 register_agent_as_tool + depth 字段 + Agent_tool_completed 变体 + FFI 链(pattern-match _ arm 保持兼容);max_tool_schema_tokens 默认 None 即完全关闭。
2026-10-13 【API级变更】导出 Chunking.default_separators,并修正 chunk_recursive 默认值不可达的文档陷阱 变更前: chunk_recursive 声明 ?(separators = default_separators),看似提供默认值,但 OCaml 中当可选参数后随的全部是 labelled 参数时,该可选参数不可擦除(Warning 16 unerasable-optional-argument)。实测确认把可选参数挪到开头、末尾、中间均无法让调用方省略——省略 ~separators 得到的是偏应用函数 ?separators:string list -> chunk list 而非 chunk list,且 default_separators 从外部完全不可达(死代码)。后果比缺陷本身严重:(a) docs/sdk/rag.md 与 zh 版三处示例照抄了这个不可编译的调用形式,却标注 chunks : chunk list,文档主动误导;(b) test/test_chunking.ml 因同一原因自 v0.5.1(2026-06-26)起从未编译通过,248 行 / 16 用例 rotting 约 3.5 个月,且它一直未被注册进 test/dune,因此无人发现——未接线的测试比没有测试更糟,它伪装成覆盖率然后静默腐烂。变更后: chunking.mli 导出 default_separators(纯新增,无签名破坏),调用方显式传入即得 LangChain 兼容阶梯 ["\n\n"; "\n"; " "; ""];chunking.mli 的 doc comment 记录 OCaml 语言层面的根因;test_chunking.ml 四个调用点改为显式传参并接入 test/dune(16 用例首次真正执行);docs/sdk/rag.md + docs/zh/sdk/rag.md 三处示例修正并新增 unerasable 陷阱说明(EN+ZH 同步)。同时新增防复发机制: scripts/check_test_wiring.sh 断言 test/test_*.ml 集合 == test/dune 中 (modules ...) 集合,进 CI 首个步骤(在耗时的 opam install 之前 fail fast)。该不变式当场抓出了 rotting 的 test_chunking。影响范围: lib/core/chunking.mli(+9 行,纯新增)、test/test_chunking.ml(4 处调用点)、test/dune(接线)、scripts/check_test_wiring.sh(新)、.github/workflows/ci.yml(新步骤)、docs/sdk/rag.md + zh(示例修正)。回退方式: revert 即恢复——删 chunking.mli 的 default_separators 声明(chunking.ml 实现未动)、还原 test 与文档;check_test_wiring.sh 可独立删除而不影响运行时。
2026-10-19 【API级+架构级变更】多模态输入落地:公开富内容入口 + OpenAI 图片线格式(v0.12.0,bd PAR-3oi 承接 PAR-pmg) 变更前: (a) 类型层早已就绪——content_block ADT 含 Image_block { source; media_type; data; cache_control }、image_source = Url \| Base64,message.content_blocks 也早已取代旧的 content : string option;(b) 但公开 API 根本无法把图片传进来——Runtime.invoke 只接受 message : string,Engine.run_agent 同样只接受 string,而 run_agent 的 ?conversation 参数只会追加字符串构造的消息,无法注入图片块;(c) OpenAI 适配器用 Message.text_of_message 把消息拍平成纯字符串,图片被静默丢弃;(d) Anthropic 适配器把 media_type 与 data 放在 source 外,违反 Anthropic schema(base64 须置于 source 内),base64 图片实际不可用;(e) 无本地文件 → base64 的构造路径;(f) Image_block 无 detail 字段,OpenAI 的视觉成本旋钮无处安放。问题性质: 能力已备而入口未开——docs/sdk/content_blocks.md 早已写明「Image blocks are part of PAR's type-level preparation for multimodal content… User-facing image tools and higher-level APIs are planned for v0.7」,v0.12 兑现该承诺。原 bd PAR-pmg(2026-06-19 创建)基于旧 API 撰写,其「content 类型扩展」「Anthropic 支持 image」「PDF loader」三项早已就绪、CLI/REPL 两项因 v0.6.7 移除 CLI 而不适用,故真实范围收窄为四件事。变更后: (1) 新增 Runtime.invoke_content(content : content_block list),Runtime.invoke 改为委托它(单一实现路径,两入口不可能行为分叉)——不改任何既有签名,零存量用户惊吓;不改 invoke 的 message : string 签名是刻意选择:那会让 invoke rt ~agent_id "hi" 全部编译失败,对用户纯负向,0.x 的 MINOR 宽容度不该用在「让用户更难受」的方向(沿用 v0.10 决策 #10 显性性原则);1.0.0 冻结 API 时可向前统一为单一多态消息类型。(2) Engine.run_agent / run_structured / run_agent_structured 增加 ?user_content:content_block list(默认 [] → 回落到字符串,现状逐字不变)——Engine 在 par.ml:20 公开导出,改其位置参数会破坏所有 Engine 用户,故只加可选参数。(3) Message 新增构造 helper:text / image_url / image_base64 / image_file(读文件 → base64,media_type 由扩展名推断,可显式覆盖;读失败返回 error 而非抛异常)+ media_type_of_extension——helper 屏蔽 cache_control/detail 样板,归属既有 Message 模块不新造模块。(4) Image_block 增加 detail : string option(OpenAI image_url.detail = auto/low/high)——公开 variant 的 inline record 加字段对直接构造点破坏(0.x 允许,SemVer §4),此刻加上而非推迟,避免对同一公开 variant 制造第二次破坏(R3 一次做对);{ b with ... } 式更新不受影响。(5) OpenAI 线格式:仅当消息含图片块时 content 改用数组形态([{type:"text"},{type:"image_url",image_url:{url,detail}}]),无图片时保持纯字符串形态(既有请求载荷逐字不变、既有测试零改动);Base64 源转 data URI(data:<media_type>;base64,<b64>,OpenAI 唯一接受的内联形式)。(6) Anthropic 线格式修复:media_type 与 data 移入 source 内,移除 schema 外的顶层 data——因公开 API 从未提供传图入口,该路径从未被真实使用,故无存量用户回归风险。范围妥协(R2 合规): 工具结果携带图片(agent 生成视觉)不做——Tool_result_block 只有 content : string,扩展它需独立的公开类型变更 + 工具协议变更;长期方案:为 Tool_result_block 增加图片载荷变体(复用 Image_block);退役触发:出现「agent 需回看自己生成的图片」的真实场景(如截图→修复循环)。Python parity 决策: invoke_content 本版仅 OCaml 暴露——FFI 传多态结构需 content_block 的 JSON 契约 + Python 侧构造与错误语义;该缺口在 CHANGES.md 显式记录(不静默推迟),后续版本补齐,不重复 v0.7.5 式 parity 债务。影响范围: types.mli(Image_block.detail)、message.ml(4 helper + media_type 推断)、engine.ml/mli(3 个入口的 ?user_content)、runtime.ml/mli(invoke_content + invoke 委托)、openai_provider.ml(数组形态 + data URI + detail)、anthropic_provider.ml(source 内 media_type 修复)、test/test_content_blocks.ml(6 处构造点补 detail)、新测试 test/test_multimodal.ml(17 用例)、文档 EN+ZH content_blocks.md。回退方式: 全部 additive 或局部构造点变更,revert 无数据迁移——删 invoke_content 与 Message helper、Engine 的 ?user_content、Image_block.detail、还原两个 provider 的图片序列化即可。
2026-11-02 【API级变更 + 两项收口】v0.13.0-beta.20261102:MCP 工具接入模型 / 图片输入有界 / reasoning 块 + Anthropic thinking 变更前: (a) MCP client 能列出与调用工具,但工具从未进入模型可见面——注册表无 handler、agent 无描述符、Mcp_client.call_tool 在库内无调用点,而文档声称"任何 agent 都能透明调用";(b) 图片构造函数无上限,未知扩展名静默当 image/png,base64 载荷大小与 MIME 完全由调用方控制,.bmp 还被推断成两个 provider 都不接受的类型;(c) reasoning 是 message/llm_response 上的字符串字段(v0.8.3 记录的范围妥协,退役触发条件为「Anthropic thinking 落地」),无法携带 thinking 签名,带 tool_use 的轮次无法回放。变更后: (1) Runtime.create 在 server 就绪后列出工具,描述符与调用 handler 同源;Runtime.mcp_tool_descriptors 暴露描述符,显式挂到 agent 即可调用(选择显式是为配合 max_tool_schema_tokens 的 token 预算);server 的 isError 转为工具错误而非"看起来成功"的输出。(2) 图片:Message.max_image_bytes(5 MiB,可 ?max_bytes 覆盖)、image_file 先验大小再读、image_base64 先按编码长度拒绝再解码、空载荷拒绝、未知扩展名与不支持 MIME 报错;image_base64 改为返回 result;Python 同步 ImageError 与导出常量。(3) reasoning 变为 Reasoning_block / Redacted_reasoning_block 内容块,llm_response.reasoning 按 provider 顺序返回;model_config.thinking_budget_tokens 开启 Anthropic extended thinking,预算限制本地校验,temperature/top_p 自动省略,thinking/redacted 原样回放,流式 thinking_delta 加新 Reasoning_signature;旧持久化对话由 message_of_yojson 迁移为无签名块(发送侧丢弃无签名块以防非法回放)。范围妥协(R2 合规): Python 侧 MCP 不可用(Runtime.create 不解析 mcp_servers,且无 mcp_tool_descriptors)——退役触发:下一次 MCP 相关功能或首个 Python MCP 使用者;已建 PAR-b3b。流式 thinking 聚合为单块并丢弃 redacted 块(chunk 接口无法承载整块)——退役触发:chunk 接口重构为携带内容块。影响范围: types.mli(两个块变体、message 去字段、llm_response.reasoning、model_config 新字段、Reasoning_signature chunk)、message.ml(图片校验与旧字段迁移)、engine.ml/generate.ml(推理块顺序与流式聚合)、anthropic_provider.ml(thinking 全链路)、openai/mock provider、cache_breakpoint.ml/context_manager.ml/runtime.ml、par_capi.ml(thinking 配置解析)、Python runtime.py/content.py/__init__.py、文档 EN+ZH 五个文件、四个新测试文件。回退方式: 三处公开形状变更需整体 revert;本版之后写入的对话含 Reasoning_block,旧解析器会拒绝,回退需反向迁移。
2026-11-02 【安全修复 + 补口】v0.13.1-beta.20261102:Python 侧 MCP 打通 + bash 环境泄漏修复 + 隔离边界文档 变更前: (a) MCP 只有 OCaml 面完整——Runtime.create 不解析 mcp_servers,Python 程序无法配置 server,Runtime.mcp_tool_descriptors 也没有 Python 对应物,绑定的 mcp_server / mcp_list_tools 因此无从使用;(b) bash 的环境净化从未生效——Bash_policy.sanitize_env 算完被丢弃,handler 用空环境构造命令且 spawn 不传 ~env,子进程继承 PAR 的完整环境,一条 printenv 即可读出 OPENAI_API_KEY / ANTHROPIC_API_KEY / AWS_* / GITHUB_TOKEN;(c) install_bash_tool 不传 ?clock 时超时分支是空操作、永远赢得 Fiber.first 竞争,所有真实命令立即 Timeout;(d) 工具描述承诺的 600s 硬上限不存在;(e) 工具页声称有 setpgid + killpg 进程组清理,代码里没有任何相关调用,并把「不提供的限制」计入「9 层安全机制」。版本判据(PATCH 而非 MINOR): 主体是安全修复;Python 侧 mcp_tool_descriptors 是补 0.13.0 自己留下的缺口(OCaml 面已在 0.13.0 发布,Python 面记为 PAR-b3b),性质是完成 0.13.0 而非开启新功能列车。沿用 v0.8.3 的先例(同样新增公开 API,仍按 PATCH 发布,理由为「bug 驱动」)。变更后: (1) Runtime.create 解析 mcp_servers(stdio/http,沿用 Mcp_types.server_config_of_yojson 形状),坏条目令 init 失败而非跳过;新 FFI par_mcp_tool_descriptors + Python Runtime.mcp_tool_descriptors() 返回与 register_agent 同形的描述符,可整传或过滤;FFI 里 8 分支的 create 调用塌缩为一次。(2) bash:handler 以当前环境为种子 → 策略过滤 → spawn 传过滤结果;无 clock 语义改为「无计时器」而非「立即超时」;请求超时钳制到 Bash_policy.max_timeout_seconds(600s)。(3) 新增 docs/explanation/sandbox-model.md(中英 + nav):七道生效环节、五项不保证(文件系统隔离 / 网络隔离 / 进程组清理 / CPU 内存上限 / 权限降级)、缺口原因(平台专属机制 + 无 pre-exec 钩子)、可插拔 ?sandbox 设计与触发条件(失败即关闭);更正工具页两条从未成立的说法并改掉「9 层」表述。范围妥协(R2 合规): ?sandbox 机制本身不实现——退役触发:出现执行不可信或多租户命令的部署;PAR-tgy 保持 open(P3)。影响范围: lib/ffi/{par_capi.ml,par_ffi.c,par_ffi.h}、lib/core/runtime.ml、lib/tools/bash_policy.{ml,mli}、bindings/python/par_runtime/{_ffi.py,runtime.py}、文档 EN+ZH 四文件 + 新页、test/{test_bash_policy,test_bash_runtime}.ml、新 Python 测试两文件。回退方式: Python MCP 为 additive,删入口与解析即可;bash 修复回退会让子进程重新继承 PAR 环境(不建议)。无数据迁移。
2026-11-02 【API级变更】v0.14.0-beta.20261102:持久化工作流执行(检查点 + 显式恢复) 变更前: (a) 每步确实会写 checkpoint,但上报回调跑在另建的上下文上(变量是开跑时的),落库的检查点缺了该步绑定的变量——看起来可恢复,实际不可恢复;(b) 没有任何代码读回 running 行:启动只装 suspended,崩溃后的运行被静默孤儿化;(c) resume_from_checkpoint 只接受 Human_approval 叶子;(d) checkpoint 无 schema 版本;(e) 文档已宣称「崩溃后可恢复」,与实际不符。变更后: (1) Workflow_engine.step_completion(path + 步后累积变量 + result)取代旧回调;Parallel/Map_reduce/Sub_workflow/Conditional 子树不上报(原子节点,崩溃后整块重跑),并修掉子工作流覆盖父检查点的缺陷。(2) Runtime.create 重装 running 行并对每条发 Workflow_orphaned;新增 Runtime.recover_workflow,跳过已完成步、从断点继续;resume_step 放宽到任意叶子;原子节点整块重跑。(3) workflow_checkpoint 增加 schema_version(旧行按 1 读,新版本拒绝);load_all_suspended_workflows_fn 改名 load_recoverable_runs_fn 并同时加载 running;running 行无 checkpoint 不再崩启动。(4) {{results}} 改为从 result_N 绑定按索引重建(恢复后不再为空,正常路径顺序也修正)。(5) 语义定为 at-least-once,中英文文档写清原子节点与子工作流限制。发布前审查另修: 恢复会接受本进程活运行(双重执行)→ 改为只认启动时的孤儿集合并加在途保护;进入恢复不再清空检查点(二次崩溃仍可恢复);损坏/NULL 检查点不再崩启动。范围妥协(R2 合规): 子工作流不能独立恢复(崩溃后整块重跑)——退役触发:出现需要细粒度恢复子工作流的部署;agent 循环中途崩溃恢复不做——已立 PAR-mrr。影响范围: types.mli(Workflow_orphaned、schema_version、step_completion)、workflow_engine.ml(上报缝、bind_step_result、step_results_from_bindings、resume_step)、runtime.ml(孤儿集合、recover_workflow、run_from_checkpoint)、sqlite_persistence.ml、5 个测试假 persistence、新测试文件 test_workflow_recovery.ml、文档 EN+ZH 两页。回退方式: 公开面 additive,删 recover_workflow 与孤儿检测即可;带 schema_version 的检查点旧二进制可读。
2026-11-04 【PATCH】v0.14.1-beta.20261104:上下文窗口安全 + payload 校验 + 流式取消 变更前: (a) 未知模型窗口被猜成 8000,长会话在 6–8K token 被截断;make_agent 默认 Summarize {max_tokens=8000; summary_model=None} 实际退化为 truncate;(b) truncate_conversation 可能在 assistant tool_call 与其 result 之间切断,留下孤立 Tool;畸形 tool arguments 以 null 进入历史并让后续每轮 400;(c) 流式取消异常被 provider 的逐 event try...with 吞掉,Ctrl+C 后仍继续生成。变更后: (1) 未知模型窗口解析为 0,跳过按窗口的主动压缩并发出一次 No_window_size 警告/事件;默认 context_strategy=None;summary_model=None 使用当前 agent.model。(2) 新增 Conversation_repair:同时识别 tool_calls 字段与 Tool_use_block/Tool_result_block,非对象 arguments 归一为 {},截断后剥离开头孤立 result、补齐缺失 result,请求前严格校验 result ↔ call(错误带 id/name);handoff 在切换 agent 前补 <handoff> result;tool-less agent 的幻觉 tool_call 不写入对话。(3) 取消异常上移到 Cancellation,OpenAI/Anthropic 重新抛出;http_client 不再把 Eio.Cancel/Eio.Io 当 EOF。(4) resume_approval 从持久化 pending payload 读取 tool_call id/name,混合批次恢复不再注入 unknown。§11 R1 标注: 架构正确——修复实现与契约偏离,并把不变量集中到 Conversation_repair 边界。§11 R2 范围妥协: 阻塞读(无新 chunk)的即时取消仍受 cohttp-eio 限制——退役触发:生产要求卡死连接立即停止或上游修复;已立 PAR-9km。影响范围: context_manager、conversation_repair(新)、engine、runtime、cancellation、OpenAI/Anthropic/HTTP client、test_* 8 文件、文档 EN+ZH。回退方式: 恢复未知窗口 8000 + 默认 Summarize {max_tokens=8000};删除 Conversation_repair 调用点;恢复 provider 吞异常行为。1714 OCaml tests,0 failures;Python 198 passed / 20 skipped。
2026-11-04 【API级+架构级变更】v0.15.0-beta.20261104:durable invoke + 分支会话 + 会话枚举 + 工具分层 变更前: (a) agent 循环中断后无法恢复,已完成的工具批次会丢失或重跑;(b) 并行分支无法从已有对话开始,也无法把胜出分支的 history 交回调用方;(c) 事件维度看不到没有 events 的 fork 会话;(d) 自定义工具只能注册为 Always,max_tool_schema_tokens 省不到 token;(e) invoke_async 缺 ?save/?update_current,后台分支会污染父会话。变更后: (1) Runtime.invoke ~durable / ~invoke_id 在 iteration 0 和每个完成的工具批次后写 checkpoint;Runtime.recover_invoke 显式恢复,Runtime.list_orphaned_invokes + Invoke_orphaned 暴露孤儿;checkpoint 记录运行 agent 的工具集、system prompt、iteration/elapsed;失败恢复保留 checkpoint 以便重试,取消同时删除 checkpoint 与 orphan 条目;handoff/审批批次也会 checkpoint。(2) model_config.context_window 四层 resolver;invoke_async ?save ?update_current,save 使用当前 Invoke_context session;取消 token 原子化。(3) agent_dispatch_spec.conversation + parallel_success {spec; result; conversation};Workflow_engine.run_agent_call 共享实现。(4) conversation_summary + load_conversations_fn + Runtime.list_conversations,覆盖无 events 的会话;?scope:None 明确为跨 scope。(5) Runtime.register_tool ?layer / set_tool_layer;Par.Think_tag_strip facade 导出。§11 R1 标注: 架构正确——扩展已有原语,不新增并行抽象;parallel_success 用 typed record 而非 tuple + 旁路;会话枚举走 conversations 表而非污染 events。§11 R2 范围妥协: blocking_approval 仍未实现(字段保留);阻塞读取消仍受 cohttp-eio 限制(PAR-9km);workspace/appendix/hooks/steering 未随 checkpoint 重放(文档记录)。影响范围: types.mli、engine、runtime、workflow_engine、cancellation、context_manager、conversation_repair、sqlite/noop persistence、FFI/Python、par.ml、测试 10+ 文件、文档 EN+ZH。回退方式: durable invoke 为 additive(删 checkpoint 表与 API 即可);v0.15 API 需整体 revert 公开 record 字段与 parallel result 形状。1735 OCaml tests,0 failures;Python 204 passed / 20 skipped。
2026-11-14 【API级+安全】v0.16.0-beta.20261114:视觉工具结果 + 跨 runtime 租约 + 审批恢复合流 + TLS 身份校验 变更前: (a) 工具返回值被压成文本,模型看不到工具产生的图片;(b) 两个 runtime 共用一个 SQLite 库时,会把对方正在跑的 durable invoke 当孤儿恢复,工具重复执行;(c) 审批挂起会删掉 durable checkpoint,等待期间崩溃则运行丢失;(d) invoke_generate/invoke_structured 把运行 session 留在事件总线上,且先 mint session 再校验 agent;(e) 以 IP 字面量访问 HTTPS 时 Domain_name 解析失败,TLS 包装层退化为不校验证书身份;(f) find/grep 的 glob 经 Str.quote 后残留反斜杠,任何模式都匹配不到(GitHub #32)。变更后: (1) handler_result.Success_content 让工具把文本与图片作为 tool result 交回模型;Anthropic 使用数组形式,Python 共享 tool_content 信封。(2) invoke_leases 表 + CAS 声明,持有者以 pid 探活、TTL 兜底并续租;共库 runtime 不再重复执行。(3) 审批挂起保留 checkpoint 并记录 pending_approval;决定开放时 recover_invoke 拒绝并指向 resume_approval,决定落地后删除 checkpoint。(4) with_bus_session 改为 prepare 回调,捕获与 mint 绑定;generate/structured 先校验目标再 mint,恢复调用方 session;并发事件归属限制写入文档。(5) 新增 Par.Tls_client 单一 TLS 入口,IP 字面量用 ~ip 校验,无法解析的 host fail closed;tls-eio >= 2.1.5,ipaddr 成为直接依赖。(6) glob 逐字符转换(*/**/?),find 匹配相对路径,grep 省略/空 glob 视为 *,并修复 path:line:text 首字符被截断。§11 R1 标注: 架构正确——视觉、租约、审批恢复都扩展已有原语(content_block、checkpoint/approvals 行、SQLite 服务接口),没有引入平行抽象;TLS 收敛到单一入口消除了三份漂移的 host 解析。§11 R2 范围妥协: HTTP 传输层重写仍推迟到 v0.17(PAR-9km,spike 已完成);blocking_approval 仍未实现(PAR-e68);tool_search 提升与 steering 队列不随 checkpoint 重放。影响范围: types、runtime、engine、persistence(sqlite/noop)、providers/http_client、mcp_transport_http、builtin_tools、par.ml、FFI/Python、测试 8 文件、文档 EN+ZH、依赖下限。回退方式: 视觉/租约/审批为 additive,可删新 variant、checkpoint 字段与 lease 表;TLS 与 glob 为 bugfix,回退即恢复已知错误行为(不建议)。1764 OCaml tests,0 failures;Python 209 passed / 20 skipped。
2026-11-14 【PATCH】v0.16.1-beta.20261114:grep 行内匹配 + 目录 glob(GitHub #32 跟进) 变更前: v0.16.0 修好了 glob 翻译,但 grep 仍用 Str.string_match re line 0(只认行首),行中出现的 distiller_agent_id 永远搜不到;glob 仍与文件 basename 比较,sub/*.ml 这类带目录的模式永远匹配不到文件。变更后: (1) 行匹配改用 Str.search_forward,正则可命中行内任意位置;^ 仍可显式锚定行首。(2) 含 / 的 glob 匹配相对 path 的路径(与 find 同规则),sub/*.ml、**/*.ml 可用;不含 / 的 glob 仍按文件名匹配任意深度,*.ml 与默认 * 行为不变。(3) 三个精确结果集回归用例(行中 token、sub/*.ml、**/*.ml),前两个在还原实现时失败;docs/sdk/tools.md EN+ZH 记录两种 glob 形态。§11 R1 标注: 架构正确(bugfix)——补完已发布行为,不新增抽象;glob 语义选择「含 / 走相对路径、不含 / 走文件名」与递归内容搜索一致(默认 * 仍递归),避免无斜杠 glob 静默只搜根目录。§11 R2 范围妥协: 无新增。影响范围: lib/tools/builtin_tools.ml、test/test_builtin_tools.ml、docs/sdk/tools.md + zh、CHANGES.md、README.md、docs/zh/DECISIONS.md(补 #17/#18)。回退方式: 恢复 Str.string_match 与 basename 匹配即回到 v0.16.0 的已知错误行为(不建议)。1767 OCaml tests,0 failures;Python 209 passed / 20 skipped。
2026-11-14 【PATCH + 安全】v0.16.2-beta.20261114:工具调用 hooks 覆盖全部入口(GitHub #33) 变更前: Runtime.register_tool_call_hook 只被 Runtime.invoke 传给 Engine.run_agent;workflow Agent_call / Tool_call、invoke_parallel、invoke_structured、嵌套 agent tool、resume_approval 重新分发都直接跑工具,应用级审批门禁可被静默绕过。变更后: (1) Workflow_engine.exec_context 增加 tool_call_hooks 快照,run_agent_call / structured Agent_call 传给 Engine;workflow Tool_call 在 handler 前执行链(Block/Modify)。(2) invoke_structured 的 Invoke_context 注入 hooks 并传给 run_agent_structured。(3) 嵌套 agent tool 使用继承快照;父运行无 ambient context(workflow/parallel)时回退到运行时当前链。(4) resume_approval 重新分发带 hooks。(5) 8 个 handler-not-executed 用例 + 1 个 HITL 用例,逐路径变异验证。§11 R1 标注: 架构正确——hook 链的单一权威仍在 runtime,workflow 只做 per-run 快照传递,没有新增平行门禁机制。§11 R2 范围妥协: 无新增;exec_context 新字段对直接构造者是编译期破坏(0.x 允许,CHANGES 已标注)。影响范围: lib/core/workflow_engine.ml/.mli、lib/core/runtime.ml、test/test_hook_coverage.ml(新)、test/test_engine_hitl.ml、test/test_integration.ml、test/test_workflow_engine.ml、docs/sdk/invoke_context.md + zh、CHANGES.md、README.md。回退方式: 移除字段与传参即恢复 v0.16.1 的已知绕过(不建议)。1776 OCaml tests,0 failures;Python 209 passed / 20 skipped。
2026-11-15 【PATCH + 回归修复】v0.16.3-beta.20261115:恢复 MCP HTTP 与 web 工具的 HTTP 传输(GitHub #36/#37) 变更前: Http_timeout.raw_request 在 Host 后提前写入 CRLF,其余请求头与 body 被当成无 Content-Length 的正文丢弃;use_tls 直接 failwith "TLS in raw_request not yet supported",chunked 未解码,SSE 未解析。MCP HTTP 与 fetch_url / read_webpage / web_search(DuckDuckGo lite 走 HTTPS)全部受影响,HTTPS 完全不可用。变更后: (1) MCP HTTP 传输恢复 cohttp-eio:application/json 与 text/event-stream 分流解析,initialize 带 headers/params/body,session id 正常捕获。(2) http_get 恢复 Cohttp_eio.Client.get + Http_client.with_timeout_for,请求头(含 user-agent)与响应体正确,HTTPS 可用。(3) Http_timeout 标记 superseded,仅作为 v0.17 owned-socket 传输脚手架,不再在生产路径。(4) 新增 test_http_transport_e2e.ml:本地 server 覆盖 MCP JSON、MCP SSE、fetch_url 头/正文;三例在 raw 路径上全部失败、回退后通过。§11 R1 标注: 架构正确(回归修复)——回退到已验证的 cohttp-eio 实现,不在热修里继续堆 raw 半成品;已知的“卡死读不可中断”限制恢复,由 PAR-9km 的 v0.17 owned-socket 传输一次解决。§11 R2 范围妥协: 超时取消能力暂时退回 cohttp 的限制;退役触发 = PAR-9km 落地并迁移 provider/MCP/fetch_url。影响范围: lib/mcp/mcp_transport_http.ml、lib/tools/builtin_tools.ml、lib/core/http_timeout.ml(标注)、test/test_http_timeout.ml(注释)、test/test_http_transport_e2e.ml(新)、test/dune、CHANGES.md、README.md。回退方式: 恢复 raw raw_post/http_get 路径即回到已知损坏状态(不建议)。1779 OCaml tests,0 failures;Python 209 passed / 20 skipped。
2026-11-17 【MINOR】v0.17.0-beta.20261117:MCP server / skill 运行时重载(GitHub #35) 变更前: host 只能在 Runtime.create 时配置 MCP server 与 skill:mcp_tools 私有、register_skill 拒绝重复 id、没有 unregister,改配置必须重启进程。变更后: (1) 新增 Runtime.reload_mcp_servers ~servers:按 server_name 声明式调谐,未变配置保留实例、新增/变更 spawn、删除/变更旧实例在新集合就绪后停止;新增事务性(任一 spawn 失败只回滚本次实例,旧集合继续运行);返回完整 descriptor 列表,调用方用 update_agent_tools 合并;进行中的 invoke 保留启动时 registry 快照。(2) 新增 Runtime.replace_skill(整条 binding,修复旧 Skill_registry.replace 只换激活函数的问题)与 Runtime.unregister_skill(同时清理手动激活列表)。(3) 三个 API 全部通过 C bridge 暴露到 Python。(4) runtime 保存 create 时 switch 与 MCP 依赖/配置列表以支持 reload。(5) 8 个 test_mcp_reload.ml 用例 + skill registry/runtime 用例 + 7 个 Python 用例。§11 R1 标注: 架构正确——声明式调谐把“配置即状态”落实到 runtime,失败回滚与 in-flight 快照都有明确语义;没有把 add/remove 的编排责任推给每个 host。§11 R2 范围妥协: 无新增;Http_timeout 仅作为 v0.17 之后的 owned-socket 传输脚手架保留,PAR-9km/PAR-is4 不在本版。影响范围: lib/core/runtime.ml/.mli、lib/core/skill_registry.ml/.mli、lib/par.ml、lib/ffi/{par_capi.ml,par_ffi.c,par_ffi.h}、Python runtime.py/_ffi.py、test/test_mcp_reload.ml(新)、test/test_skill_registry.ml、test/test_skill_user_activation.ml、test/dune、docs/sdk/mcp.md + zh、docs/sdk/skills.md + zh、CHANGES.md、README.md。回退方式: 删除三个 API 与 runtime 保存的 MCP 依赖/配置字段即可(Python 绑定同步移除);无数据迁移。1790 OCaml tests,0 failures;Python 216 passed / 20 skipped。
2026-11-17 【PATCH】v0.17.1-beta.20261117:MCP JSON-RPC 2.0 合规 + reload 工具 binding 补口(GitHub #38/#39) 变更前: (a) Mcp_types 的 request / notification / response 三个 writer 均未输出 JSON-RPC 2.0 强制成员 "jsonrpc":"2.0";stdio 的分帧掩盖了问题,而 streamable-HTTP 对规范 server 一律返回 400,Log_and_continue 启动策略下 server 被静默丢弃。(b) v0.17.0 的 reload_mcp_servers 文档要求用 update_agent_tools 合并新工具,但该函数接收 Types.tool_binding,而 rt.mcp_tools(descriptor + handler)是私有的,mcp_tool_descriptors 只返回 descriptor——reload 成功后无法把新工具挂到已注册 agent,仍要重启。变更后: (1) 三个 writer 统一输出 "jsonrpc":"2.0";三个 *_of_yojson 解析器拒绝缺失或非 2.0 的版本成员,round-trip 测试因此无法再“两端同错而通过”;新增 Mcp_types.jsonrpc_version。HTTP e2e 的 mock server 改为严格模式(缺成员返回 400),直接复现报告场景。(2) 新增 Runtime.mcp_tool_bindings : runtime -> Types.tool_binding list,返回当前 descriptor 与 handler 的配对;reload 后读取并配合 ~remove 旧名称传给 update_agent_tools ~add,新实例的 handler 才会生效;reload_mcp_servers 与 SDK 文档(EN+ZH)同步改写合并流程。(3) Python 不新增该访问器:Python 没有 update_agent_tools,仍用 descriptor 重建 agent;决策写进 .mli 与 CHANGES。版本判据(PATCH 而非 MINOR): #39 是补齐 v0.17.0 自己留下的半开接口(当时已公布合并流程但无访问器),#38 是缺陷修复;按 docs/rules/release.md “finishing a surface is a PATCH” 与同日跟进先例取 PATCH。§11 R1 标注: 架构正确(补口 + 合规修复)——消息版本集中在 writer/parser 单一位置,避免各 transport 自行拼 JSON;binding 访问器复用既有 Types.tool_binding,不新增平行抽象。§11 R2 范围妥协: 入站消息改为严格校验(非规范 server 省略该成员会显式报错而非静默接受)——与报告建议一致;退役触发 = 若真实部署遇到必须容忍的非规范 server,再引入显式兼容开关。影响范围: lib/mcp/mcp_types.ml/.mli、lib/core/runtime.ml/.mli、test/test_mcp_types.ml、test/test_http_transport_e2e.ml、test/test_mcp_reload.ml、docs/sdk/mcp.md + zh、CHANGES.md、README.md。回退方式: 删除 mcp_tool_bindings 与文档合并段即可回到 v0.17.0 的已知缺口;移除 writer 的版本成员会重新破坏 HTTP MCP(不建议)。1798 OCaml tests,0 failures;Python 216 passed / 20 skipped。
2026-11-18 【PATCH】v0.17.2-beta.20261118:bash/Python 整数输入 + 字面量替换修复(GitHub #40/#41) 变更前: (a) bash 工具用 Yojson.Safe.Util.to_float_option 读取 timeout;JSON 只有一个数字类型,模型发 {"timeout":30} 时 Yojson 对 Int 抛 Type_error,两处 handler 在 spawn 前崩溃。(b) Bash_blacklist 的三条命令替换规则(bash-eval / backtick-subst / dollar-paren)无条件匹配拼接后的 argv;bash 工具实际直接 exec argv,不经过 shell,所以普通参数里的 $(...)、反引号是字面量,却被策略拒绝。(c) 同类问题在 Python C bridge:七个浮点配置字段用 to_float_option,Python 的自然写法 temperature=1、top_p=0、工具 timeout=30 等以 Int 到达后抛异常,表现为 PARError: Failed to register agent。变更后: (1) make_bash_handler 与内置占位 bash_tool 接受 Int/Float;0、负数、非数字仍回落 30s。(2) 三条替换规则只在 argv 中出现 shell 且后续短选项簇含 c(bash -c/sh -ec//bin/sh -c,含 env bash -c 包装)时生效;其余 28 条不变,bash -c 'echo $(whoami)' 仍拦截,直接 argv 的字面量放行(eval $(opam env) 随后因 eval 是内建命令而正常 exec 失败)。(3) C bridge 统一 float_option_of_json:接受 Int/Float、Null → None、非数字保持原抛错;覆盖 temperature / top_p / tool timeout / max_execution_time / context_compression_threshold / workflow timeout / approval webhook timeout_sec。(4) 新增 9 个 OCaml 用例(blacklist 正反例、Coder policy、真实 handler、内置 parser)与 5 个 Python 用例(agent model、per-agent 字段、tool descriptor),修复前全部失败。版本判据(PATCH): 纯缺陷修复,无公开签名变化;Pre-Bump Gate 因目标版本不在 ROADMAP 而以 --force 执行(沿用 v0.8.6 先例)。§11 R1 标注: 架构正确(bugfix)——数字解析收敛到单一 helper,黑名单规则与真实执行模型(直接 exec vs shell -c)对齐,而不是继续用“拼接字符串 + 无条件正则”猜测语义。§11 R2 范围妥协: 无新增;黑名单依旧是 tripwire 而非安全边界,包装器(如 xargs sh -c)不保证覆盖,文档已声明。影响范围: lib/core/runtime.ml、lib/tools/builtin_tools.ml、lib/tools/bash_blacklist.ml/.mli、lib/ffi/par_capi.ml、test/test_bash_{blacklist,policy,runtime}.ml、test/test_builtin_tools.ml、bindings/python/tests/test_config.py、docs/sdk/tools.md + zh、CHANGES.md、README.md。回退方式: 恢复 to_float_option 会重新引入整数崩溃;恢复无条件替换规则会重新拒绝字面量调用(均不建议)。1807 OCaml tests,0 failures;Python 221 passed / 20 skipped。

2026-11-02: Reasoning becomes a content block; Anthropic extended thinking

Before: reasoning lived in a reasoning_content : string option field on both llm_response and message. engine.ml documented that as a 范围妥协 whose retirement trigger was "when Anthropic extended-thinking support lands". The shape could not carry an Anthropic thinking signature, so a tool-use round-trip would have been rejected, and .bmp-style reasoning was the one part of the content model that never became a block. Anthropic thinking was unavailable: no thinking request parameter, no thinking/redacted_thinking parsing, no thinking_delta streaming. After: Reasoning_block { text; signature; cache_control } and Redacted_reasoning_block { data; cache_control } are content_block variants; message.reasoning_content and llm_response.reasoning_content are gone (llm_response.reasoning : content_block list). model_config gains thinking_budget_tokens, the adapter validates Anthropic's budget limits locally, omits temperature/top_p when thinking is on, parses and replays thinking and redacted_thinking verbatim, and streams thinking_delta plus a new Reasoning_signature chunk. message_of_yojson migrates a legacy reasoning_content string into an unsigned block instead of failing, and the Anthropic adapter drops unsigned blocks so migrated data cannot produce an invalid request. Reason: Architecturally correct, one-shot completion (§11 R1/R3) — the trigger recorded for the compromise arrived, so it was retired rather than extended. Doing the type migration together with the capability avoids paying for the same public-type break twice, and both ride the same unreleased MINOR window as the image-constructor change. Streaming's aggregation limits are a documented property of the chunk interface, not a silently accepted defect: non-streaming preserves the exact block structure. Affected surface: lib/core/types.{ml,mli}, message.ml, engine.ml, generate.ml, cache_breakpoint.ml, context_manager.ml, runtime.ml, lib/providers/{anthropic,openai,mock}_provider.ml, the Python streaming decoder and exports, bilingual content_blocks.md / agent.md / streaming.md, test/test_reasoning.ml (new), and mechanical field updates across the test tree. Rollback: Revert the blocks and the field together; persisted conversations written after this change contain Reasoning_blocks that an older parser would reject, so a rollback also needs the persistence migration in reverse.


2026-10-26: MCP server tools reach the agent loop

Before: Mcp_client could list and call a server's tools, but nothing put those tools in front of a model. tool_registry.ml and engine.ml held no MCP reference, Mcp_client.call_tool had no call site in the library, and the runtime tests covered server lifecycle and raw JSON-RPC only. docs/sdk/mcp.md claimed any agent could transparently call any server — overstated for tools. After: Runtime.create lists each configured server's tools once the server is up and keeps each descriptor next to the handler that calls the server. Runtime.mcp_tool_descriptors exposes the descriptors; advertising one on an agent makes it callable, because the handler is already in every per-call registry. The engine validates the model's arguments against the server's own schema. A server-reported isError becomes a tool error rather than a successful-looking result. Reason: Architecturally correct, one-shot completion (§11 R1/R3). The MCP client was the extension point; the missing piece was wiring it to the loop, and adding a second extension mechanism would have been the wrong answer. Selection is explicit rather than automatic because PAR ships max_tool_schema_tokens for exactly this problem — auto-advertising every server tool to every agent would work against it. Affected surface: new lib/core/mcp_tools.ml, runtime tool registry and agent-facing API, Types.string_of_error_category (moved out of the runtime so core modules can describe errors without a dependency cycle; two modules carried private copies), bilingual MCP docs. Rollback: Revert the wiring; the descriptors and handlers disappear together because they come from one list, so the model-visible and callable sets cannot drift apart.


2026-10-31: Image input bounds and media-type validation

Before: Message.image_file read the whole caller-specified file with no size ceiling, and mapped an unknown extension to image/png without saying so. Message.image_base64 accepted any string: not-base64, empty, and arbitrarily large payloads all went through. .bmp was inferred although neither supported provider accepts it, so the failure surfaced at the provider, far from the call that caused it. Python's image_file read the whole file and had the same silent default. After: One rule set, stated once and enforced on both SDK surfaces. Message.max_image_bytes (5 MiB) bounds the decoded payload and ?max_bytes overrides it; image_file checks the size before reading, image_base64 rejects an oversized encoded string before decoding; empty payloads are rejected; unknown extensions and media types outside Message.supported_image_media_types are errors that name the accepted set. image_base64 returns a result because it can now fail. Python raises ImageError (a ValueError) and exposes MAX_IMAGE_BYTES, SUPPORTED_IMAGE_MEDIA_TYPES, and max_bytes=. Reason: Architecturally correct, one-shot completion (§11 R1/R3). These constructors are the boundary where a caller hands PAR data it did not produce; trusting it there meant the contract was asserted rather than checked, and a mislabelled payload failed downstream. image_url stays unvalidated on purpose: it carries a reference, not bytes. Affected surface: lib/core/message.ml, bindings/python/par_runtime/content.py and its exports, test/test_multimodal.ml, test/test_multimodal_safety.ml, bindings/python/tests/test_multimodal.py, bilingual content_blocks.md. Rollback: Revert the constructors and their tests; no persisted data changes shape, so no migration is involved.


2026-10-19: Published beta verification

Before: v0.11.0-beta.20261013 was prepared on main but not published. After: The existing tag at 416ef86 was pushed with explicit user approval. The release is marked as a pre-release, with two Python wheels and source/opam assets. Release, wheel publishing, archive publishing and four-platform release acceptance completed successfully. The tag contains 1614 OCaml tests; development work after that tag is not part of the published beta. Reason: Provide an opt-in build without replacing stable v0.10.0. Affected surface: GitHub release assets and the Python package index. Rollback: Do not move a published tag or overwrite assets; use the package index's withdrawal mechanism or a separately authorized replacement release. An isolated install from the official package index imported the published wheel and found the agent-as-tool API. A configured third-party mirror had not synced it.

2026-10-19: Multimodal completion correction

Before: The initial multimodal row above deferred Python rich input without a technical blocker. New image detail also lacked a decoding default. After: Synchronous Runtime.invoke_content ships through both SDK surfaces, using the existing content-block JSON contract and explicit persistence flags. Older images remain readable; failed file reads close their channels; the shared runtime rejects tool-protocol user blocks before provider I/O. Reason: Architecturally correct one-shot completion (R1/R3); documenting a deferral does not justify splitting a feasible implementation. Affected surface: Runtime validation, content decoding, image helpers, FFI, Python exports and bilingual SDK docs/tests. Rollback: Revert the completion changes together, retaining compatibility for already saved images. See the complete decision. This supersedes the Python-deferral portion of the earlier row, not its provider or input-entry design. No additional version bump or tag is authorized here.

9. 相关文档

  • docs/v0.3-ROADMAP.md(内部文档) — 当前路线图
  • README.md — 项目入口
  • DESIGN.md — 实现设计
  • AGENTS.md — 开发者工作流

最后更新: 2026-06-26


10. 发布策略:Beta-First

规则:开发完成后,永远先提交 beta 版。只有在用户明确说"发布正式版"时,才执行 release 相关操作。

版本号约定

阶段 版本号格式 示例
开发/合并 X.Y.Z-beta-YYYYMMDD 0.5.0-beta-20260610
正式发布 X.Y.Z 0.5.0

工作流

  1. 开发完成 → 版本号设为 X.Y.Z-beta,合并到 main,不打 tag、不触发 CI release
  2. 用户说"发布正式版" → 去掉 -beta 后缀,打 tag vX.Y.Z,推送触发 release pipeline

Agent 必须遵守

  • 禁止在用户说"发布正式版"之前执行以下操作:
  • 去掉版本号后缀
  • 打 git tag
  • 触发 release workflow
  • 更新 README/CHANGES 中的正式版本号和 test count
  • beta 阶段可以更新 CHANGES.md 添加 beta 条目,但版本号必须带 -beta

| 2026-06-21 | v0.5.0 scope: ARM64 Linux + ARM64 macOS wheels | 用户决策:"那就开搞吧 v0.5.0"。scope 锁定: (1) manylinux_2_28_aarch64 (新) — ubuntu-22.04-arm64 runner + quay.io/pypa/manylinux_2_28_aarch64 容器 + auditwheel。不做 universal2 — macos-13 (Intel) 2026-06-19 已永久放弃(free tier queue 24h+ 必超时,见 .github/workflows/ci.yml L16),Intel Mac 用户回退到 sdist 源码编译(PyPI 2026 流量 <5%,可接受)。scope 排除: musllinux wheels (≥95% PyPI Linux 由 manylinux 覆盖)、Windows wheel (MSVC 编译链过重)、-manylinux_2_17 RHEL 7/CentOS 7(用户 2026-06-21 明确拒绝)。CI 成本: 3 job matrix, ~$0.18/release (x86_64 $0.08 + aarch64 $0.016 + macos-15 $0.08)。SemVer: MINOR (新增平台 = MINOR per SemVer §7,public API 不变)。验证: Oracle 终审必须确认 PyPI 3 wheels + GH Release 3 assets + acceptance CI 5 platforms (debian:12/ubuntu:22.04/ubuntu:24.04/debian:bookworm-arm64/macos-15) 全绿。 |

| 2026-06-21 | v0.5.0 scope 修订 (实际交付): macOS arm64-only; ARM64 Linux 推到 v0.5.1+ | 用户决策:"跳过 ARM64 Linux, 只发 x86_64 + macOS-arm64"。根因: GitHub Actions 免费 tier ARM64 runner 完全不可用 — ubuntu-22.04-arm64 / ubuntu-24.04-arm64 都 queue 45min+ 从未派发;qemu-binfmt 在 ubuntu-22.04 host 上跑 quay.io/pypa/manylinux_2_28_aarch64:latest 容器, 容器启动即崩溃 (Error response from daemon: container is not running)。v0.5.0 实际交付: 2 wheels — par_runtime-0.5.0-py3-none-manylinux_2_28_x86_64.whl (11.3 MB) + par_runtime-0.5.0-py3-none-macosx_11_0_arm64.whl (6.5 MB)。v0.5.1+ 待办: ARM64 Linux wheel — 等 (a) GH Actions ARM quota 改善, (b) 用户自建 self-hosted ARM runner, 或 (c) 切到 cross-compile toolchain。技术细节: macOS wheel 平台 tag 通过 wheel tags --platform-tag macosx_11_0_arm64 设置 — 单纯 mv 改文件名会导致 PyPI 400 (内部 WHEEL Tag field 必须匹配)。 |

| 2026-06-21 | 【待恢复】ARM64 Linux 轮子临时移除 | 范围级变更: v0.5.0 原计划发布 3 个轮子 (x86_64 Linux + ARM64 Linux + ARM64 macOS),实际只发布了 2 个 (x86_64 Linux + ARM64 macOS)。根因: GitHub Actions 免费 tier ARM64 runner (ubuntu-22.04-arm64 / ubuntu-24.04-arm64) 饱和 queue 45min+ 从未派发; qemu-binfmt 在 x86_64 host 上跑 quay.io/pypa/manylinux_2_28_aarch64:latest 容器启动即崩溃 (Error response from daemon: container is not running)。用户决策 2026-06-21: 跳过 ARM64 Linux, 推到 v0.5.1+。【强制恢复条件】: 项目功能相对完善后 (预计 v0.6-v0.8 区间),必须恢复 ARM64 Linux 轮子支持。恢复路径优先级: (1) 等待 GH Actions ARM 配额改善 (2) 用户自建 self-hosted ARM runner (3) 切换到 OCaml cross-compile toolchain + aarch64 sysroot。恢复信号: 出现以下任一情况时立即排期 — (a) ARM Linux 用户在 issue 报告 pip install 失败 (b) PyPI 下载统计显示 ARM Linux 需求 >5% (c) 项目发布 v1.0 前的 feature freeze 阶段。技术债务记录: par_runtime-0.5.0-py3-none-manylinux_2_28_aarch64.whl 的 wheel tag 格式、auditwheel 修复流程、manylinux_2_28_aarch64 容器路径已在 v0.5.0-beta.post1-post5 中验证过 (除 runner 可用性问题外其他都 ready)。恢复时参考 commit 6a12c01 (初始 3-job matrix) 和 90aae3b (qemu 尝试)。 | | 2026-06-24 | v0.5.2 战略反转: skill 系统移出 §7 防呆清单 | 项目成熟度 (runtime / agents / tools / middleware / persistence / RAG / streaming 全部 stable) + 下游项目需求。Skill 系统按 §3 差异化主张做了类型化设计 (typed tool_filter ADT, skill_trigger ADT, expected_output — 比 Claude Code 更类型化, 比 OpenAI 更 filesystem-native, 比 LangChain 更 success-criteria-aware)。Scope locked in: docs/v0.5.2-ROADMAP.md Track A. 可逆性: 若下游需求证明为假, 重新加回 §7 该行 + revert Track A 代码即可。代价: 1 个 PR revert。 | | 2026-06-26 | 【范围级变更】PostgreSQL 持久化后端移除 — SQLite only | 变更前: 三层持久化 (Sqlite 开发 / Postgresql 生产 / Noop 测试),独立 par_postgres opam 包,caqti-eio 依赖,公开类型含 `Postgresql of string 变体,CLI --db-uri 指 PostgreSQL 连接串。变更后: 两层持久化 (Sqlite 唯一持久化后端 / Noop 测试),删除 par_postgres opam 包,移除 caqti-eio 依赖,公开类型 persistence : [Sqlite of string ](``Postgresql 变体移除,破坏性变更),CLI `--db-uri` 改指 SQLite 数据库路径。**原因**: (1) SQLite 对当前用户群 (LLM 后端工程师做单进程 agent) 已足够; (2) PG 后端长期受 FFI/CI 可用性困扰 (`postgresql` opam 包不在标准 repo, CI 需特殊排除); (3) 收窄维护面,集中精力到 §4 轴 #1/#2 (类型严谨 + 并发)。**影响范围**: 公开 `persistence` 类型 (对 pattern-match Postgresql `` 的 SDK 用户是破坏性变更)、CLI--db-uri语义、全部持久化相关文档 (EN + ZH)、opam 包面 (par_postgres删除)、构建脚本 (不再需要 pg 客户端库)、docs/rules/docs.md+docs/DOC-MAINTENANCE.md标识符保留清单 (移除par_postgres+ ``Postgresql )。**对多实例水平扩展的影响**: SQLite 文件锁不支持跨容器多进程写同一文件——这是当前已知限制。双层持久化模型 (本地 SQLite + 远程 tier) 在路线图上 (v0.6+, bd issue `PAR-4dt`),远程 tier 不再特指 Postgres (可能是对象存储或未来后端)。**回退方式**: 从 commit `cb5d795` (移除前) 恢复 `lib/postgres/` + `par_postgres.opam` + caqti-eio 依赖。详见 `CHANGES.md` v0.5.4-beta "Removed — PostgreSQL persistence backend"。 | | 2026-06-27 | **【API级变更】v0.6.0: on_max_tokens_behavior ADT + max_continuation_chunks** | **变更前**: `finish_reason=Max_tokens` 时引擎无条件丢弃截断输出并盲目重发相同 prompt (v0.5.5-beta 修复为先检测内容再返回部分结果)。**变更后**: 新增 `type on_max_tokens_behavior = Retry | Continue | Return_partial` 公开 ADT + `on_max_tokens` + `max_continuation_chunks` 两个可选 `agent_config` 字段 + `Llm_response_truncated` 事件变体。默认 `Return_partial` (v0.5.5 Phase 1 行为)。**原因**: 三家头部产品调研发现业界对此无共识 — Claude Code 自动升档+重试3次 (最激进)、Codex CLI 盲目重试 (openai/codex#14753 已知 bug 未修)、MiMo Code 直接返回部分 (最克制)。PAR 的 typed ADT 方案是 §3 差异化主张 #1 (类型严谨) 的直接体现:比 Codex 的通用错误通道更精准,比 Claude Code 的硬编码常量更可配置。**影响范围**: `agent_config` 公开类型 (新增 2 个可选字段,通过 `make_agent` 的可选参数构造,keyword-arg 调用者不受影响)、`event` 类型 (新增 1 个变体,有 `[@@deriving yojson]`)、FFI JSON parser (`par_capi.ml`)、Python binding (零代码改动 — 纯 JSON 透传)。**回退方式**: 移除 `on_max_tokens_behavior` ADT + 2 个字段 + 事件变体,恢复 v0.5.5-beta engine.ml Max_tokens 分支。详见 `CHANGES.md` v0.6.0-beta "Added — Configurable on_max_tokens_behavior policy"。 | | 2026-06-30 | **【API级变更】v0.6.3: Auto Context Compression by Window Ratio** | **变更前**: `context_strategy` 三种变体 (Truncate_oldest / Summarize / Sliding_window) 都是绝对阈值触发,无 ratio-based 自动压缩;`make_agent` 默认 `Sliding_window {max_messages=100; max_tokens=200000}`;`context_strategy` 在 FFI 中硬编码不可配置;引擎每次迭代无条件 apply strategy;模型 context window 大小全代码库无任何字段追踪;`Context_compressed` 事件类型不存在。**变更后**: 新增 3 个 `agent_config` 可选字段 (`context_compression_threshold : float option` 默认 `Some 0.8` / `compression_cooldown_messages : int option` 默认 `Some 6` / `context_window_override : int option`),新增 `llm_service.context_window_fn : (unit -> int) option` capability,新增 `Context_compressed` + `Context_compression_skipped` 两个 event 变体 (后者带 typed Below_threshold |Cooldown_active | No_window_size |No_strategy ` 多态变体 reason),新增Context_manager5 个 pure helpers (default_context_window静态查表 /resolve_context_window三层 resolver /estimated_tokens_with_margin1.2× 余量 /should_compress纯决策函数 /apply_default_summarize),make_agent默认context_strategy从Sliding_window改为Summarize {max_tokens=8000; summary_model=None}(BREAKING),引擎engine.ml:517加入 ratio gate + cooldown ref + 事件发射,FFI JSON parser 解析 4 个字段。**原因**: 业界调研 (librarian bg_940617fc) 确认所有有默认的主流生产 agent 框架均用 LLM-summarize (Lettasliding_windowmode / Anthropiccompact_20260112/ LangChainConversationSummaryBufferMemory/ CrewAIrespect_context_window=True),零个用 truncate-drop。PAR 80% pre-emptive trigger 优于 Letta/CrewAI 的 reactive-on-error。typed skip-reason ADT 是 §3 差异化主张 #1 (类型严谨) 的直接体现。**影响范围**:agent_config公开类型 (新增 3 个可选字段)、llm_service(新增 capability 字段,所有 3 个构造站点更新)、event类型 (新增 2 个变体 + 1 个 named polymorphic variant type)、Engine.run_agent(ReAct loop 加入 ratio gate + cooldown ref)、Runtime.make_agent(3 个新可选参数 + 默认 strategy 改变)、FFI JSON parser (par_capi.ml)、Python binding (零代码改动 — JSON 透传)。**回退方式**: 移除 3 个 agent_config 字段 + llm_service.capability + 2 个 event 变体 + Context_manager helpers + engine.ml ratio gate;恢复make_agent默认Sliding_window。详见CHANGES.mdv0.6.3-beta "Auto Context Compression by Window Ratio"。 | | 2026-06-30 | **【战略级变更】新增 §11 开发原则:"一次做对"** | **变更前**: STRATEGY.md 无显式开发原则段;规划决策常以"范围可控/周期短"为由牺牲长期架构正确性,工程妥协与架构决策混为一谈。**变更后**: 新增 §11《开发原则》段,确立"一次做对"为核心原则,要求所有架构决策优先长期正确性,禁止用范围/周期作为架构妥协的借口,工程妥协必须显式标注并附长期替代方案。**原因**: v0.6.4 规划时 agent 提出 4 条决策(message flatten 保留 / Stable-Volatile 仅 template 生效 / Auto-caching 自动标 / 永久 soft-fail),用户挑战"抛开周期与范围是否仍这样决策"后,发现 3 条是工程妥协伪装成架构决策。此为复发模式,必须升级为战略级原则。**影响范围**: 所有版本规划、ROADMAP 编写、架构决策记录、agent 规划行为。AGENTS.md 同步加引用让每次规划可见。**回退方式**: 删除 §11 + AGENTS.md 引用 + 本行变更日志。 | | 2026-06-30 | **【API级变更】v0.6.4-beta (partial): content_block list + prompt caching infrastructure** | **变更前**:message.content : string option扁平字符串;usage_stats3 字段;无cache_control/cache_ttl/content_block类型;无cache_strategyADT;无cache_control_fncapability;无prompt_cache_key;无 cache event 变体。**变更后**(Track A-G+E 完成): 新增content_blockADT(4 变体,each withcache_control option)、cache_control、cache_ttl、image_source类型;message.content→message.content_blocks : content_block list(BREAKING);usage_stats扩展到 6 字段(BREAKING);新增cache_strategyADT onagent_config(BREAKING);llm_service.cache_control_fncapability(BREAKING);Openai.prompt_cache_key(BREAKING);Anthropic adapter 发射 cache_control wire markers;OpenAI adapter 解析 cached_tokens + 注入 prompt_cache_key;5 个新 cache event 变体;Cache_breakpointbudget manager 模块;Messagehelper 模块。**未完成**: Track B(Stable/Volatile phantom types — 需要 OCaml existential record field 类型设计)、Track H(新测试文件)。**影响范围**: 43 文件改动,465 insertions,198 deletions。**回退方式**: revert commits b4a721d + b827690。 | | 2026-07-02 | **【API级变更+架构级变更】v0.6.5-beta: Workspace 模块 — Sys.getcwd 从安全原语中放逐** | **变更前**:Bash_safe_command.sandboxed_path_of_string以Sys.getcwd()(进程全局 ambient state) 为安全锚点;绝对路径在类型层被硬拒;6 个文件工具 (read/ls/find/grep/write/edit) 各自内联 3-check 但**缺少敏感前缀检查**;sensitive_prefixes()是全局函数 (第二 ambient 权威向量);Runtime.create无 workspace 参数。**变更后**: 新增Workspace模块 (lib/core/workspace.ml) — 不可伪造private值,携带roots : string list(多根,从第一天起) +policy : workspace_policy(敏感前缀随 workspace 走);admit函数替代sandboxed_path_of_string— workspace 参数 mandatory,**绝对路径在 workspace 根下被放行** (核心行为变更);sandboxed_path类型移至 Workspace;sandboxed_path_of_string/_cwd/_to_string全删;make_execcwd 改 mandatory;Runtime.create新增?workspace:Workspace.workspace可选参数 (下游集成商可注入自定义 workspace 实现多 worktree 隔离);Sys.getcwd()仅剩Workspace.of_cwd一处 bootstrap + 3 个便利定位点 (skill_loader/par_capi/main)。**§11 R1 标注**: 架构正确 (非范围妥协) — workspace 作为唯一路径权威是终态设计,多根从第一天起,无 ambient authority。**§11 R3 评估**: 单步完成 (新模块 + 所有调用点一次迁移),非两步走。**原因**: 下游集成反馈 (worktree-per-task 工作流) 暴露 CWD-anchored sandbox 的结构性冲突 — 一个进程无法服务多个 worktree;与 Claude Code #26262 同源问题。Oracle 架构咨询确认Sys.getcwd()作为安全锚点是 ambient authority 反模式,Option E (workspace 抽象) 是正确的终态。**影响范围**:Bash_safe_command公开 API (类型迁移 + 3 函数删除,8 项破坏性变更 — 见 CHANGES.md 迁移表)、Builtin_tools.builtin_tools(新增~workspacemandatory 参数)、Workflow_engine.exec_context(新增workspacemandatory 字段)、Runtime.create(新增?workspace可选参数)、Runtime.runtimerecord (新增workspace字段)、6 个文件工具 (路径验证统一走Workspace.admit,获得此前缺失的敏感前缀检查 — 安全提升)。1253 tests passing。**回退方式**: revert commit 8a2b55e + 后续修复 commits。详见CHANGES.mdv0.6.5-beta "[UNRELEASED] — Workspace Abstraction"。 | | 2026-07-02 | **【API级变更】v0.6.4-beta.2-beta.5: prompt caching 完成版** | **变更前**: v0.6.4-beta (partial) 的 Track B/H 未完成;Anthropic adapter 的extract_system_prompt压扁 system prompt 为裸字符串导致 cache_control 标记丢失;tool_descriptor_to_json不 emit cache_control;build_message_json仅处理 Text_block;FFIparse_cache_strategybare "with_cache_of" 静默降级为 No_caching;FFI skill_prompt_zone 不可从 Python 达达。**变更后**: (1) Runtime zone_tag 方式落地(commit 6a22c7f)— phantom types 被 OCaml record field 限制排除,runtimezone_tag是架构正确方案。(2)mark_tool/mark_message用户层 API 落地。(3)skill_prompt_zoneADT (Stable_prompt/Volatile_prompt/Both_prompts) 替代string option。(4) B.4 hard-fail 升级(原计划 v0.6.5,用户指令提前到 v0.6.4)。(5) Anthropic adapteremit_block_with_cache全 4 block variants +extract_system_prompt返回content_block list+tool_descriptor_to_jsonemit cache_control +build_request_bodyemit system as List。(6) FFI 2 bug 修复(parse_cache_strategy fail-fast + skill_prompt_zone 3-form parser)。(7)apply_breakpoints移除 Tool-location namespace 混淆。(8)Both_prompts语义修正(拼接 stable+volatile)。**影响范围**: 累计 60+ 文件,1228 tests。**回退方式**: revert commits 7016172..cf6ac09。**Oracle 验证**: 两轮 VERIFIED,真实 API 验证通过(MiniMax 端点接受 cache_control 格式)。 | | 2026-07-02 | **【API级变更】v0.6.6-beta: per-run workspace override (闭合 v0.6.5 Option E 缺口)** | **变更前**: v0.6.5 落地了Workspace抽象与Runtime.create ?workspace,但invoke/submit_workflow/submit_workflow_async/invoke_workflow_sync四个公共入口的签名里**没有**?workspace参数 — 它们只接收 runtime,workspace 在 runtime 建好时固定。一个 agent-server 进程建一个 runtime → 一个 workspace → 该进程所有 workflow/invoke 共享同一 workspace,无法并发服务 N 个 worktree。Oracle Option E 审计明确指出 "workspace is property of the run, not the process" 未实现。**变更后**: 四个公共入口均接受?workspace:Workspace.workspace可选参数;per_call_registry ~rt ~workspace为每次调用构建 freshTool_registry— copy_all 用户工具后,用rt.bash_rebuild重建 bash handler +rt.file_tools_rebuild重建文件工具 (read/ls/find/grep/write/edit),全部绑定到rt' = {rt with workspace};handler_fn签名**不变** (避免 30+ 文件级联);Tool_registry.copy_all新增;Runtime.register_file_tools_rebuild暴露给注册 builtin 工具的调用方 (bin/main.ml 捕获 Eio switch+net)。**§11 R1 标注**: 架构正确 (per-call registry 比 handler_fn 签名改更干净 — workspace 是 run-scoped 非 call-scoped)。**§11 R3 评估**: 单步完成。**§11 R2 范围妥协 (Decision #4)**: 用户自定义工具 (viaregister_tool) 的 per-call 覆盖推迟到 v0.7 (register_tool 签名改是 SemVer 破坏,触发条件: v0.7 周期或下游反馈)。**Oracle 验证**: 两轮 (首轮 REJECT 文件工具未覆盖 + 缺 e2e 测试 → 修复 file_tools_rebuild + e2e invoke Mock 测试 → 二轮 VERIFIED)。**影响范围**: runtime.mli/ml (4 API 入口 + per_call_registry + 2 rebuild 字段)、tool_registry.ml/mli (copy_all)、bin/main.ml (register_file_tools_rebuild)、6 个新测试。1260 tests passing。无 breaking change。**回退方式**: revert commits 0a8331e..89ccc77;?workspace参数移除即恢复 v0.6.5 行为。 | | 2026-07-03 | **【范围级变更】v0.6.7-beta: 删除 CLI (产品 UX 下沉到独立 PAR Code 仓库)** | **变更前**: PAR 仓库自带 CLI 应用 (bin/main.ml1741 行 — REPL、config 向导、ask/history/stats/工具注册全套)。一个 agent-runtime 仓库自带产品级 UX,造成 (a) 用户困惑: 该用par还是 PAR Code?(b) 维护分心: 引擎团队维护产品级 CLI;(c) 定位模糊: PAR 是引擎还是产品?install.sh175 行从 GH Releases 下载 CLI 二进制。README hero 段以curl | bash → par ask开头;docs/cli.md、par_cliopam 包、4 个 CLI 测试 (test_cli_args/test_cli_dispatch/test_session_resume_cli) 全存在。**变更后**: 删除整个bin/、par_cliopam 包 +par_cli.opam、CLI 测试、docs/cli.md;重写install.sh为交互式 SDK 安装向导 (检测系统 → 选 Python(1) vs OCaml(2) → 验环境 → 用户确认后缺 opam 自动跑官方安装脚本到~/.opam→ 装 → 验证);install-dev改用 Pythonpar_runtime.version校验;CI 5 个 workflow 全部清par_cli引用 (ci.yml/nightly.yml/opam-publish.yml/pypi-publish.yml改opam install par;release.yml删除 binary build/upload,转为 release notes 引导pip install/opam install par);README hero 段 SDK-first (Python+OCaml),docs/index.md移除 CLI section。par_cli此前**未成功发布**到 opam-repository (v0.4.8 时期提交过 PR,但从未合并),所以删除零外部影响——CHANGES.md 记录这次移除,opam-repository 无需撤包。**§11 R1 标注**: 架构正确——分层清洁化(引擎归引擎、产品归产品);PAR 是 SDK/运行时,不是产品。**§11 R3 评估**: 单步完成(无需两步走,无外部用户)。**§11 R2**: 不适用(无范围妥协,这是分层修正)。**影响范围**:bin/删除 (1741 行+4 个辅助文件)、par_cli包 + 5 个 CI workflow + Makefile install 目标 + AGENTS.md + README +docs/cli.md+docs/index.md+ 4 个测试 + 顶层配置(总计 ~25 文件)。1248 tests pass (1260 - 12 个 CLI 测试用例)。**回退方式**: revert commits 23697fc..c472413;恢复bin/、par_cli包、CI workflow 与 makefile 原状。 | | 2026-07-09 | **【API级+架构级+依赖级+范围级变更】v0.7.0-beta: Document Loaders Framework — RAG 前置阶段补齐** | **变更前**: PAR 已有完整 RAG 基础设施(Vector_storesqlite-vec 后端 +Chunking3 策略 +embedding_service+Runtime.invoke_with_rag),但管道只接受裸字符串——用户必须自己把 PDF/HTML/CSV 读成 string 再喂进add_documents。这是 LangChainDocumentLoader占据的位置(81k+ 仓库使用)。**变更后**: 新增lib/documents/子目录(7 模块,14 文件,≤16 上限留余量)—— (1)Document.trecord(content:string; metadata:(string,Yojson.Safe.t) Hashtbl.t; source:string)+Meta子模块(empty/singleton/add/add_string/add_int/to_yojson/of_yojson)+module type LOADER(lazy_load:unit -> Document.t Seq.t为 canonical,load:unit -> Document.t list为便利)+load_errorADT(5 变体);(2) 5 个格式 loader(TDD):Text_loader/Markdown_loader(YAML frontmatter viaYaml)/Html_loader(lambdasoup剥离 script/style/nav)/Csv_loader(row-per-Document,列名→metadata)/Pdf_loader(camlpdfPdftext简单抽取,每页一 Document);(3)Directory_loader扩展名→loader 关联表(LlamaIndex 模式)+default_map;(4) Python FFI 5 层链(par_capi.ml的do_load_document/do_load_directory+Callback.register→par_ffi.h/.cC bridgecall2_exn/call3_exn→_ffi.pyctypes →runtime.pyRuntime.load_document/load_directory)返回 JSON list ofdicts 可直接喂add_documents();(5) 3 个新 deps(camlpdf/csv/omd,全 LGPL+OCaml-linking-exception 或 ISC,MIT 兼容)。**§11 R1 标注(12 条决策)**: 全部架构正确——lib/documents/新子模块而非lib/core/document_loader.ml单文件(lib/core/已 53 文件超舒适区);Document.t不进types.ml(已 1259 行超 800 静态上限);字段名content而非 LangChainpage_content(内部一致性 > Python 历史包袱,与Vector_store.document.content对齐零摩擦);lazy_loadcanonical(LangChain 现代 API 已 deprecatedload_and_split);Chunking 保持独立(LangChain 自己 deprecateload_and_split,组合优于耦合);extension→loader 关联表(OCaml-idiomatic);metadata(string, Yojson.Safe.t) Hashtbl.t(与Vector_store.document.metadata对齐);MINOR bump(SemVer §7,纯新增零破坏)。**§11 R2 范围妥协(2 条,R2 合规)**: (D8).docx推迟到 v0.7.1——无 maintained OCaml 库存在,DIY(camlzip+xml-light ~200 LOC)是伪装架构的范围妥协,ship 即成永久维护负担,**退役触发**:opam 出现 maintained 库 / downstream >5 reactions / v0.7.1 规划周期,三选一;迁移代价低(独立模块,零现有代码改动)。(D9) PDF 简单 text stream 抽取而非 layout-preserving——多栏/表格/scanned PDF 抽取质量差,**退役触发**:downstream 真实语料抽取失败率 >20% 或 v0.8 周期;迁移路径:替换Pdf_loader.extract_text内部实现为 layout-aware(接口不变);mli docstring + docs/sdk/document_loaders.md EN+ZH 都明示限制。**§11 R3 评估**: 5 loader + 共享Document.t/LOADER契约一次 ship(分批无收益);.docx 推迟属 R3 exception(c)"未知技术验证"(spike-first 决定),非范围妥协伪装。**§11 R4 自问**: 12 条决策全部过"抛开周期与范围,长远用户怎么用更爽"测试;2 处真妥协已附退役计划与触发条件。**原因**: README "Coming next" 已预告 v0.7+ 方向(external vector stores / document loaders / multimodal);连续 5 个 patch(v0.6.5→v0.6.9)打磨引擎本身边际收益递减,需要新能力解锁真实场景。**影响范围**: 新增lib/documents/(14 文件)+lib/par.ml(+8 module re-exports)+lib/ffi/(par_capi.ml+par_ffi.h/.c)+bindings/python/(2 文件 + 1 新测试)+docs/sdk/document_loaders.mdEN+ZH +docs/{index,zh/index}.md+mkdocs.yml+README.md+docs/zh/README.md+CHANGES.md+dune-project+par.opam+lib/dune(deps)。1269 OCaml tests + 8 Python tests passing(0 failures)。零破坏性变更。**回退方式**: revert commits c0589b2..f6ce927(6 个原子 commits);lib/documents/整目录删除 +lib/par.ml/test/dune还原 + dune-project deps 行删除,完全恢复 v0.6.9 行为。详见CHANGES.md` v0.7.0-beta "Document Loaders Framework"。 |

| 2026-07-09 | 【API级+架构级变更】v0.7.1-beta: Concurrency + Memory + Scope + Deprecation + Dynamic Prompt | invoke_context per-call 隔离(Eio.Fiber carrier)+ invoke_async;Memory_service(FTS5)+ 3 builtin tools;Agent_call response_schema;persistence scope 维度;Deprecation.warn_once;per-turn system_prompt_appendix;Auto-skill override fix;FFI persistence fix。1387 tests。审计(2026-07-10): 17 issues(2 critical: invoke_structured 绕过 Invoke_context + run_structured 不注入 appendix)。详见 docs/audit/v0.7.x-findings.md。 | | 2026-07-10 | 【API级+架构级+范围级变更】v0.7.2-beta: Windows Capability + Vector Memory + SDK Docs | Capability 模块(平台能力检测)+ FFI #ifdef _WIN32(SRWLOCK)+ workspace 路径归一化 + 进程生成门控 + vec0.dll vendor;vec0 虚拟表 + search_mode(Keyword/Vector/Hybrid/Auto)+ RRF hybrid search + sync triggers;SDK 文档全套 EN+ZH。CI: Ubuntu ✅ + macOS ✅。Windows CI 移除(MinGW par_ffi.c:121 指针类型错误,待 v0.7.3)。审计(2026-07-10): 20 issues(2 P0: Auto 死代码 + update 泄漏)。详见 docs/audit/v0.7.x-findings.md。 | | 2026-07-10 | 【审计记录】v0.7.0–v0.7.2 全量审计 | 4 agent 并行审计 → 48 去重问题(10 P0 + 6 P1 + 10 P2 + 12 P3)。Oracle 验证 8/8 spot-check。核心: Auto 死代码 + update 不删旧行 + invoke_structured 绕过 Invoke_context + 5 FFI 锁内分配 + 10 文档签名错误。完整在 docs/audit/v0.7.x-findings.md。 |

| 2026-07-11 | 【依赖级+范围级变更】v0.7.3 stable: 审计清零(38 问题)+ §11 R2 遗留清零 | 变更前: v0.7.0–v0.7.2 期间累积 48 审计问题未清(含 10 P0 真 bug、6 P1 竞态/死代码、10 P2 文档签名错误、12 P3 质量债)。run_agent_structured 需求悬而未决。变更后: 38 问题全部修复(10 P0 + 6 P1 + 10 P2 + 12 P3 全部清零;2 个审计时未识别的小问题 #5+ #32+ #c0 内化到 review 后续修复中),6 个原子提交(按模块组 A-F)push 到 main。docs/audit/v0.7.x-findings.md 标记"全部已修复于 v0.7.3"。CHANGES.md 加 v0.7.3 section。§11 R1 标注(38 条): 全 P0/P1 为「架构正确」——Auto 模式智能解析、update 真删旧行、invoke_structured 补 Invoke_context、FFI 锁外分配、cancel CAS、double-appendix 元数据追踪——均为原设计意图的执行层修复,无架构重新决策。§11 R1 标注(12 条 P2 文档): 全「架构正确」——SDK 文档与 .mli 签名对齐零摩擦,中英双语同步,mkdocs build --strict 通过。§11 R2 范围妥协(2 条): (D3 评审遗留) LOADER 模块类型删除(用户确认选 a,选项 b 「真实现」需要 R3(a) 破坏 SemVer major,选项 c 「技术未知」R5 不适用)→ 长远方案: 真实现 Seq.t 流式加载需有真实消费端驱动,目前无 RAG 流水线按 Doc 逐个消费——R2 合规,无退役日期,等真实需求出现再启动;(D4 评审遗留)加密 PDF 检测基于 regex 搜 "encrypt|password" 异常消息——功能可用但脆弱(camlpdf 改错误消息文本即失效)→ 长远方案: 捕获 Pdf.PDFError 异常类型并匹配 "Encryption" 前缀——v0.7.4 已部分落实(用类型匹配替 regex)。§11 R3 两步走合规性: 38 问题均在 0.7.x 范围内修复(无 SemVer major 破坏,minor 在 0.x 允许含 breaking 符合 §4)。首个 stable tag v0.7.3。1387 tests passing,Oracle 验证通过。 |

| 2026-07-11 | 【API级+架构级+依赖级变更】v0.7.4 stable: json_extract 顺序修复 + run_agent_structured(两阶段 ReAct + 结构化) | 变更前: (a) extract_json_from_text 处理顺序 bug——strip_think_tags 在位置 0 留下空白,strip_markdown_fences 检查 s.[0:3]=="\``"因前导\n而失败(fallbackfind_balanced_block碰巧兜底,但脆弱);(b)run_structured把 tools 传给 LLM 但不执行——LLM 返回 tool_calls 被静默忽略,repair loop 失败后报 Invalid_input——agents 需要"工具+结构化"无路径。**变更后**: (a) 重排处理链为strip_think_tags → trim → strip_markdown_fences → trim(去掉首个冗余 trim);加 2 个测试覆盖 think+fence/reasoning+fence;(b) 新增Engine.run_agent_structured——两阶段模式: Phase 1run_agent跑完整 ReAct 循环(带工具)→ Phase 2run_structured拿完整对话历史做结构化调用(不带工具);Runtime.invoke_structured和workflow_engine.Agent_call路由:config.tools <> []走run_agent_structured,config.tools = []走run_structured(轻量路径不变)。**§11 R1 标注**: (a) json_extract 处理链重排为「架构正确」——trim 的语义位置("消除前后空白")与 think-tag 剥离的副作用(位置 0 留白)天然冲突,trim 必须在 strip 之后才正确;(b) 两阶段为「架构正确」——LangGraphcreate_react_agent(response_format=)文档原话:"The graph will make a separate call to the LLM to generate the structured response after the agent loop is finished"——与 PAR 设计对齐;run_structured` 保留作为轻量路径(纯结构化输出无需 ReAct 循环开销)——非妥协,是不同 use case。§11 R1 标注(关键决策): 选 LangGraph 两阶段(业界验证,CrewAI v1.9.0→v1.9.1 教训:交错式在 vLLM/非 OpenAI provider 上工具被跳过)而非 OpenAI Agents SDK 交错式(tools + response_format 同发,仅 OpenAI 原生 API 可靠)。§11 R2 范围妥协: 无——两阶段是终态设计,R3(a) 不破坏 SemVer(major 破坏仅在 0.x 范围外适用),R3(c) 无未知技术验证,R3(d) 用户明确指示选两阶段。§11 R5 适用: 无未知技术——LangGraph/CrewAI/OpenAI Agents SDK 三个生产级框架已有公开模式对比。1387 tests,新增 3 个测试覆盖 run_agent_structured 的三种场景(有工具+schema、无工具 delegation、Phase 1 error propagation)。Engine.mli 导出新函数。 |

| 2026-07-19 | 【API级+架构级变更】v0.7.9 stable: Engine.run_agent terminal Assistant 消息物化 — egress wrap 根因修复 | 变更前: Engine.run_agent 有 7 个 Ok 终态分支,6 个 inline 调 add_assistant_message 后 return,1 个(_ catch-all for finish_reason = Stop | Content_filter)漏调。结果: Runtime.invoke 返回的 invoke_result 中 response.text 持有最终 assistant 内容,但 conversation.messages 缺少对应 {role = Assistant; ...} entry。下游影响: conversation resume / audit trail / run_agent_structured Phase 2 context 静默不完整。变更后: 三层架构重构—— (1) Loop invariant(docstring at engine.ml:587-596): conv 在 loop 内 MUST NOT 持有 terminal response; (2) 删除 4 个 inline terminal appends(lines 617, 973, 980, 988)+ 保留 mid-iteration appends(Tool_calls at L790, Continue sub-chunks at L~1022 — feeds next LLM call's context, different concern); (3) 单一 egress wrap at run_agent 出口(engine.ml:1137-1149): 唯一一次 add_assistant_message 调用,带 idempotency check(仅在 last message 已是 terminal-shaped Assistant 且 text 匹配 resp.text 时 skip,覆盖 Branch 6 Continue compact 路径)。Branch 6 (Max_tokens/Continue) normalize: 中间 chunks(initial Max_tokens resp + user_feedbacks + cont_resp_*)被 compact 成单个 combined_msg whose text = final_resp.text,顺带修复一个 latent bug(pre-fix final_resp.text combined vs final_conv.messages 末尾 last chunk 不一致)。Handoff + empty-text collision hole closed(third-round Oracle audit): idempotency check 原本仅匹配 role = Assistant,在 Handoff carry_context=true 时 source agent 的 mid-iter toolalls Assiant(contentlocks=[], ttf_message="会 survive in carried context,若 target agent 返回空 Stop(text=None,restrictive prompt 下真实模型行为),naive role-only check false-match 在 "" = "" 上,skip target's terminal append。收紧为 tool_calls = None AND tool_call_id = None 才能进 skip path,structurally 排除 mid-iter toolall Assistt。§11 R1 标注**: 「架确」——loop invariant + 单一 egress 是终态设计,消除"remember-to-call" anti-pattern(已产生一个 missing-branch bug,未来还会产生更多)。Oracle 三轮 audit 一致 VERIFIED。§11 最强反驳(Orae 自我 rebut): "fix replaces one human-memory burden (remember to call) with another (remember NOT to call inside loop)"——但原 bug class 是 under-append(silent missing data,最坏),新 bug class 是 over-append(visible duplicate,任何 smoke test 抓)。Asymmetry 倾向 fix,net improvement。§11 范围妥协: OCaml 没法真正 type-enforce(phantom type 才能完全 close),docstring + 删除 default + idempotency check 三层近似。Future maintainer 在 loop 内 inline append 不同 text 会产生 silent duplicate——code review 是唯一 guard。Acceptable: 新加 terminal branch 的 default 路径是 Ok (resp, conv),自动正确——这是 structural win。§11 R5 不适用: bugfix(最小化层面)+ 架构决策(egress wrap 是 root-cause 路径)混合,但 R5 专为 ROADMAP scope,bugfix 走最小化原则已合规。Error-path 行为变化: pre-fix 不一致(仅 Max_tokens/Retry 路径有 partial append),post-fix 统一为"no Error path 有 terminal append"——更一致。Blast radius: 无 test/caller 依赖 pre-fix 行为,无 documented dependency。影响范围: lib/core/engine.ml(loop invariant docstring + 4 处 append 删除 + Branch 6 compact + egress wrap + idempotency check),test/test_engine_assistant_message.ml(11 tests covering Stop/Content_filter/Tool_calls→Stop/Max_tokens variants/Handoff/Generate/Resume),test/manual_qa_assistant.ml(dune-built diagnostic executable),CHANGES.md v0.7.9 section。1418 OCaml tests passing(新增 11)。Oracle三轮 VERIFIED(empirically reproduced hole + green-with-fix)。回退方式: revert commits 9a1bf26 + 0e835a1 + 10416b8 + 771ed61。审计教训**: 第一轮 + 第二轮 audit 都漏了 handoff + empty-text collision hole,第三轮 skeptical verification 才发现——多轮 audit 是必要的,单轮 review 即使 expert 也会漏 edge case。 |

| 2026-07-17 | 【API级+架构级+依赖级变更】v0.7.5 stable: HNSW + .docx + 原生结构化输出 | 变更前: (a) RAG 向量存储仅 sqlite-vec 后端(需 vec0.so/.dylib/.dll 外部二进制,Windows 需 vendor DLL); (b) document loaders 缺 .docx 格式支持(用户需自行提取 Word 文档文本); (c) 结构化输出走 text-injection fallback(LLM 在 system prompt 里被指示输出 JSON,而非用 provider 原生 json_schema 能力)。变更后: (a) 纯 OCaml HNSW 向量库(lib/core/hnsw.ml,Algorithms 1-4 from Malkov & Yashunin TPAMI 2020)——零外部二进制依赖,跨平台(Windows 不需 vec0.dll),cosine + L2 distance,configurable M/ef_construction/ef_search,Marshal 二进制持久化;Types.vector_store_backend ADT(Vs_sqlite_vec | Vs_hnsw)runtime-selectable,跟 llm_service/memory_service 模式一致;Runtime.create ?vector_store_backend + Vector_store.create_for_backend 工厂分发; (b) .docx loader(lib/documents/docx_loader.ml)——camlzip 解 ZIP + xmlm 流式解析 word/document.xml,提取 <w:t> 文本,段落→换行,tab 保留,field 指令排除;新增 deps camlzip + xmlm; (c) 原生结构化输出——complete_structured_fn 从 None 改为 Some,OpenAI 用 response_format: json_schema(strict mode),Anthropic 用 output_config,Ollama/Custom 保持 fallback。§11 R1 标注: (a) HNSW 为「架构正确」——用户质疑"OCaml 不能做了吗"后重新评估,纯 OCaml HNSW 比外部服务(Qdrant/Milvus)更符合 PAR "self-contained runtime" 定位;vector_store_backend variant 与 llm_service/memory_service 模式对齐; (b) .docx 选纯 OCaml(camlzip+xmlm)而非 pandoc shell-out,保持 self-contained; (c) 原生模式替代 fallback 是 provider 能力的正确利用。§11 R2 范围妥协: vector_store_backend/HNSW/Docx_loader 在此版本仅 OCaml SDK 可用,Python FFI 暴露推迟到 v0.7.6——R2 合规(FFI 暴露是独立工作,不阻塞 OCaml SDK 用户),退役触发:v0.7.6 周期。影响范围: lib/core/hnsw.ml+hnsw.mli(新)+ lib/core/vector_store.ml(variant dispatch)+ lib/core/types.ml(新 ADT)+ lib/core/runtime.ml(?vector_store_backend)+ lib/documents/docx_loader.ml+mli(新)+ lib/ffi/par_capi.ml(complete_structured_fn = Some)+ 10 个新测试。1408 tests。回退方式: revert commit ff6d399。 |

| 2026-07-18 | 【API级+依赖级变更】v0.7.6 stable: Python parity + FFI GC root registration + YAML block scalars | 变更前: v0.7.5 的 HNSW/.docx/原生结构化输出仅 OCaml SDK 可用,Python binding 无法使用;par_ffi.c 多个 C bridge 函数缺 CAMLparam/CAMLlocal GC root 注册(OCaml 5.x GC 可能在 C callback 期间移动 OCaml 堆对象);Python _normalize_config 缺 v0.7.5 新字段(event_bus defaults/persistence format/prompt_cache_key);skill_loader frontmatter parser 不支持 YAML block scalar(|/>)。变更后: (1) Python FFI SIGABRT fix——par_set_vec_extension_path 加 ensure_initialized() before caml_copy_string()(Python import 时 par_init 未跑,触发 uninitialized GC → SIGABRT); (2) .docx FFI dispatch fix——par_capi.ml loader_for_extension + parse_loaders_json 加 .docx -> Some Par.Docx_loader.make; (3) HNSW Python FFI——do_init 解析 "vector_store" config JSON,ensure_vector_store 优先用 runtime 内部 vector store; (4) _normalize_config 补全——event_bus defaults + persistence format coerce + prompt_cache_key 透传; (5) CAMLparam/CAMLlocal GC root registration——所有 FFI C 函数加 OCaml GC root 注册,防 OCaml 5.x GC 移动堆对象; (6) YAML block scalar——skill_loader frontmatter parser 支持 |(literal)/>(folded)。§11 R1 标注: 全 6 项为「架构正确」——FFI GC root registration 是 OCaml 5.x C bridge 的规范要求;YAML block scalar 是 YAML 1.1 spec 标准格式。§11 R2 范围妥协: 无。影响范围: lib/ffi/par_ffi.c(GC roots + ensure_initialized)+ lib/ffi/par_capi.ml(.docx dispatch + HNSW FFI)+ bindings/python/par_runtime/runtime.py(_normalize_config)+ lib/skills/skill_loader.ml(YAML block scalar)+ bindings/python/tests/test_rag_e2e.py(HNSW integration test)。1410 OCaml tests + 13/15 Python test files(test_http_timeout + test_structured 是 known issues,tracked separately)。回退方式: revert commit f76aa0c。注: 此版本未打 git tag(只有 release commit),PyPI 也未发布(pypi-publish.yml workflow 从 v0.5.3 起一直失败,直到 v0.7.8 才修复)。 |

| 2026-07-18 | 【API级+架构级变更】v0.7.7 stable: downstream root-cause 修复 + FFI save/update_current 暴露 | 变更前: 5 个 downstream integration issues 未解决——(1) bash tool timeout integer validation 不认 "number" type(JSON Schema spec: number ⊇ integer); (2) invoke_generate 强制 auto-save,invoke 不 save——两个 API 语义不一致,caller 无法控制; (3) concurrent invoke 写共享 mutable rt.current_conversation 导致 race; (4) save_conversation 只能存 rt.current_conversation,无法存 explicit conversation——concurrent-safe usage 不可能; (5) bash tool description 用 "ls -la" 作 example(误导 agent 用 bash 做文件操作);tool description overrides 只在 register_agent 时生效(sequencing dependency)。另外 Python FFI 有 free(result) on Python ctypes callback memory → heap corruption → test_structured.py SIGABRT。变更后: (1) validation.ml check_type: `Int _ 同时匹配 "integer" + "number"; (2) ?save:bool 统一——invoke 默认 false,invoke_generate 默认 true(backward compat),语义一致; (3) ?update_current:bool——default true,当 false 时不写 rt.current_conversation,caller 从 return value 读 conversation——race 消除; (4) save_conversation ?conversation——可存 explicit conversation,concurrent-safe; (5) set_tool_description_overrides + ?tool_description_overrides on Runtime.create——invoke-time 应用(after skill effects,before LLM),sequencing-independent;bash description 改 "git status" + 文件操作指引。FFI free() fix: 移除 caml_invoke_python_handler 的 free(result)(Python bytes 内部 buffer,Python GC 管理)。FFI exposure: par_invoke_ext + par_generate_ext C bridge + Python Runtime.invoke(*, save=None, update_current=None)——kwargs 形式 backward compat。§11 R1 标注: 全 5 个 downstream issues 为「架构正确」——不是 workaround,是消除 root cause(race 消除从 shared mutable state 改为 return value pattern;save 统一从不一致改为 caller-controlled;tool override 从 sequencing-dependent 改为 invoke-time)。§11 R2 范围妥协: 无。影响范围: lib/core/validation.ml + lib/core/runtime.ml(?save + ?update_current + save_conversation ?conversation + set_tool_description_overrides)+ lib/core/builtin_tools.ml(bash description)+ lib/ffi/par_ffi.c(free removal)+ lib/ffi/par_capi.ml(par_invoke_ext + par_generate_ext)+ bindings/python/par_runtime/runtime.py(kwargs)。1410 tests + 14/15 Python test files。回退方式: revert commit 2660ede。已知遗留**: test_http_timeout.py SIGABRT——streaming 跑在 Python background thread,需 OCaml 5.x caml_c_thread_register/caml_acquire_runtime_system domain API,当前 ocaml_lock(pthread_mutex)不是 domain lock。Tracked as PAR-7be。 |

| 2026-07-19 | 【范围级+依赖级变更】v0.7.8 stable: PyPI wheel pipeline restored | 变更前: v0.5.3 起 pypi-publish.yml workflow 连续 14 次失败(v0.5.3 到 v0.7.7 全部 PyPI 缺失)。两个独立 root cause + 一个 latent dependency: (a) macOS job 假设 dune build lib/ffi/par_capi.so 会顺带产出 vec0.dylib,但 vec0 dune rules 是 orphan target(零 consumer),dune 不构建 orphan; (b) Linux job ocaml/setup-ocaml@v3 默认开 bwrap sandbox,manylinux_2_28 容器内 unshare(CLONE_NEWNS) 被禁; (c) disable-sandboxing 后暴露的隐式依赖——opam 2.x 非 sandbox 模式用系统 rsync 处理 file:// URL,manylinux minimal image 没装。变更后: (1) 删除 lib/ffi/dune 里 3 个 vec0 死代码 rule(grep (deps vec0.*) 零匹配 + runtime fallback chain 已覆盖 vendor/ 路径); (2) workflow 直接从 vendor/sqlite-vec/<vendor_dir>/vec0.<ext> 复制到 wheel,用 matrix variables(vendor_dir + vec0_ext)映射 (os, arch) → vendor 目录; (3) opam-disable-sandboxing: true(setup-ocaml 官方容器方案,Z3Prover/bap 同模式); (4) Linux deps 加 rsync; (5) workflow_dispatch trigger + if: guard 让手动验证不上 PyPI。§11 R1 标注: (1) 删 dune 死代码 rule 为「架构正确」——vec0 是 vendored binary 不是 build artifact,runtime fallback 已覆盖 OCaml SDK dev 路径; (2) matrix variables 为「架构正确」——新平台 = 一行 matrix row,不是新 bug variant; (3) disable-sandboxing 为「架构正确」——OCI 容器的标准做法,setup-ocaml action 官方推荐; (4) rsync 为「架构正确」——opam 2.x 文档明确要求。§11 R2 范围妥协: 无。影响范围: lib/ffi/dune(删 3 rule + 加 NOTE 注释)+ .github/workflows/pypi-publish.yml(matrix variables + disable-sandboxing + rsync + workflow_dispatch + if guard + flatten wheel subdir + strip checksums)。v0.7.8 是 v0.5.0 以来首个在 PyPI 可装的版本。回退方式: revert commits bf62079 + daaa768 + 215ac63 + 3de6f54 + 5aa80b7。注: v0.7.5/v0.7.6 未打 git tag(只有 release commit),PyPI 也从未发布——v0.7.8 是 wheel pipeline 修复后的首个 PyPI 可用版本。用户从 v0.5.0 应直接升级到 v0.7.8+。 |


11. 开发原则

"一次做对"(Do It Right Once) —— 本项目规划与架构决策的核心原则,2026-06-30 确立。

11.1 原则表述

当短期工程妥协与长期架构正确性冲突时,选长期正确性。

不允许"v0.X 妥协 + v0.X+1 重构"的双步走,除非有强证据证明单步不可行。

范围可以扩大,周期可以延长,但架构不能为范围妥协。

11.2 可操作规则(强制)

R1. 决策论证必须区分"技术正确"与"范围妥协" - 提出任何决策时,必须明确标注该决策的性质: - 架构正确:基于技术客观性的决策。例如"4-cap 是外部 API 合约,不该用类型系统固化"。 - 范围妥协:为控制单版本范围而做的让步。例如"先保留 flatten,v0.7 再引入 content_block list"。 - 禁止把范围妥协伪装成架构决策。这是本项目最严重的规划错误。

R2. 范围妥协必须附长期替代方案 + 触发条件 - 如果决定走范围妥协路线,必须记录: - 长期正确的方案是什么 - 什么时候触发迁移(版本号、信号、依赖项) - 迁移代价估算 - 没有"等以后再说"的妥协。每个妥协必须有具体的退役计划。

R3. "扩大范围做对" vs "分两步走"的判断准则 - 默认选"一次做对",扩大范围。 - 仅在以下情况允许分两步: 1. 单步会破坏 SemVer 重大约束(如同时改 5+ 个核心公开类型) 2. 单步需要未完成的上游依赖(如 native Gemini adapter 还没写) 3. 单步需要未知技术验证(用 spike 先验) 4. 用户明确指示分步(本条不能由 agent 自决) - 即使分步,第一步也必须为第二步铺路(API 设计兼容最终形态),不能挖坑。

R4. agent 主动挑战义务 - 规划阶段,agent 必须主动自我挑战:

"抛开开发周期和范围,只考虑长远规划和用户怎么用更爽,这个决策还成立吗?" - 如果答案是"不成立",必须主动提出翻盘方案给用户,而不是等用户挑战。 - 用户挑战后才发现的妥协,是 agent 规划失职。

R5. 适用范围 - 本原则适用于:架构决策、类型设计、API 设计、公开类型变更、ROADMAP scope 锁定。 - 本原则不适用于:bugfix(永远最小化改动)、文档微调、CI 配置、依赖升级(这些走各自的标准流程)。

11.3 验证检查(每个版本规划阶段必过)

写 ROADMAP 时,对每条关键决策问以下问题:

  • [ ] 这是架构正确,还是范围妥协?
  • [ ] 如果是范围妥协,长期方案是什么?何时触发迁移?
  • [ ] 抛开周期与范围,这个决策还成立吗?
  • [ ] 如果不成立,我是否主动提出了翻盘方案?

未通过此检查的 ROADMAP 不能定稿。

11.4 历史教训(2026-06-30 v0.6.4 规划案例)

| 2026-07-26 | 【API级+架构级变更】v0.7.10 stable: Streaming Architecture Overhaul — Foreign-Thread Elimination | 变更前: Python streaming (invoke_stream) 使用后台 daemon thread 调 caml_callback3_exn。该 thread 未在 OCaml 5.x 注册(caml_c_thread_register),导致 SIGABRT(PAR-7be)。尝试注册 + caml_acquire_runtime_system → 永久 hang(Domain.recommended_domain_count=2,D0=main + D1=work_loop 占满 slots)。Oracle 三轮咨询(v1 minimal patch hang → v2 Eio.Stream broke Par.Runtime.invoke fiber context → v3 确认根因:D0 在 pthread_cond_timedwait 中 parking 但未调 caml_release_runtime_system,D1 HTTP I/O 触发 major-GC STW 等 D0 确认 → 死锁)。变更后: 消除 Python daemon thread。par_stream_start 从 Python main thread(D0)enqueue 到 work_loop(D1),返回 handle。chunk 通过 per-handle C 队列(pthread condvar + linked list)流回。par_stream_poll 是纯 C——caml_release_runtime_system before parking in pthread_cond_timedwait,caml_acquire_runtime_system after wake。dispatch_async 是 dispatch 的 fire-and-forget 变体(result_slot option,None=async 不 slot_take)。新 C API: par_stream_start/poll/cancel/free/take_final。§11 R1 标注: 架构正确——消除 foreign-thread OCaml crossing 这一 bug 类的 precondition。R3 一次做对。影响范围: lib/ffi/par_ffi.c(+250 LOC: handle struct, queue, poll w/ release-before-park, Windows SRWLOCK/CONDITION_VARIABLE stubs)、lib/ffi/par_capi.ml(dispatch_async + do_invoke_stream_start + per-handle externs)、bindings/python/par_runtime/runtime.py(_StreamReader rewrite: no daemon thread, proper iterator with next/iter/cancel)、_ffi.py(new signatures)。Runtime.cancel_stream() deprecated。Windows CI: MSYS2 pacman system deps + camlzip libz.a workaround + eioindo C stubs + SleepConditionVariableSRW + vec0.so PAREC_EXTENSION_PATH e。回退方 rert commits 0ebcb15..84cf00d。 | | 2026-07-26 | *【CI/基建变更】CI 三平台首次全绿** | **变更前**: CI 从 v0.7.2 起连续红——Windows conf-pkg-config 找不到 pkgconf;Linux dune runtest vec0o.so 找不到(dune runtest 从 _build/default/test/ 运行,vendor/ 在 repo root 3 层之上);Pyth test_streaming.py 旧 mock API 测试与新 _StreamReader 不兼容。变更后: (1) Windows: MSYSklwxh706 安装 pkgconf+gmp+sqlite3+zlib;MinGW 头/库路径通过 C_INCLUDE_PATH/LIBRARY_PATH/LDFLAGS 暴露;camlzip 手动 make install + opam --fake(ocamlmklib -lz 在 MinGW 下不工作);eio_windows_cstruct_read/write C stubs 补实现;SleepConditionVariableSRW 替代 SleepConditionVariableCS;dune runtest 在 Windows 跳过(MinGW runtime 启动太慢)。(2) Linux: PAR_VEC_EXTENSION_PATH 环境变量 + ../../vendor/sqlite-vec/ 候选路径(ne uild 目录深度)。(3) Python: test_streaming.py skip(旧 API 需重写);test_cancel_stream.py gate behind PAR_RUN_FLAKY_TESTS(C timing race)。CI 结果**:inux ✅+macOS ✅+Windows ✅(build-only)+Python 3.10-3.13 ✅。 | | 2026-08-04 | 【API级+架构级变更】v0.8.2 stable:treaming observability + Tnk_tag_stp middleware | *变更前 SSE streaming 路径存在系统性静默吞异常问题——OpenAI parse_stream_delta 有 7 个 inner with _ -> handler + 1 个 outer (line 538),Anthropic klzxh:0724 有 个,全部吞掉 JN 解析异常,导致 malformed SSE chunk 静默丢失(provider 看起来"连上了"但回复内容消失)。同时 reasoning 模型 (DeepSeek R1 / QwQ) 的 <think> / <reasoning> 标签未在 engine 层清理,污染 conversation 历史 + 用户可见输出。变更后**: (1全部 16 个静默 handler klwxh:0727 带 provider 名 + 字段名 + 异常信息 + 200 字符 data priew;Ollama / Cuom provider 共享 OpenAI 路径,transitively 覆盖。(2) 新建 lib/middleware/think_tag_strip.ml middleware (照抄 lzzwxh:0729 的 on_after_llm 模式),导出 json_extract.strip_think_tags(原为 internaonl。**1 R1 标注: 全部正确——(1) 从根因消除静默数据丢失(visibility without behavior change);(2) middleware 是 think tag 处理的正确位置(参考 piiask 完全相同的模式),非 engine / provider 层。R3 一次做对。§11 R2 范围妥协**:。**范围: lib/providers/openai_provider.ml + lib/providers/anthropic_provider.ml (17 处 with _ -> X → logged handlers) + lib/middleware/think_tag_strip.ml/.mli (新) + lib/core/json_extract.mli (导出 strip_think_tags) + CONTRIBUTING.md (下游版本 pin 指南) + docs/sdk/middleware.md (新增 Think_tag_strip 章节)。回退方式: revert commit 1fce763 + 撤销 f2bb98c release commit。Oracle VERIFIED** (2 轮:streaming 14+ handlers + middleware 模式 + pii_mask 对照)。 | | 2026-08-04 | 【API级+架构级变更】v0.8.1 stable: Memory 增强 + Skill UX + Plan/Mode 决策 | 变更前: 下游编码 agent 集成方提出 2 个一等公民需求(Plan / Mode) + 3 个补丁(memory 暴露 / scop字段 / ?plan_id)。调研(5 agent + 2 轮 Oracle + 6 框架对比 + 8 生产产品调研)结论:业界零例外用 app 层工具实现 plan,Skill 数据模型已是 Mode 超集。**后**:1) memory_service 加 klzzh:07 (按 ext_id 精确查询,使用已有 UNIQUE INDEX) + upsert_fn (稳ID 更新,DELETE+INRT 11 列,保留 last_used_at / usage_count);(2) klzzwxh:0744公开 last_used_at / usage_count 字段(原 internal-only);(3) klzzw:07 plic accessor;(4) Runtime.invoke ?skills:string list + Runtime.invoke_async ?skills:string list 按调用激活,race-free,不污染全局状态;(5) Skill_activated / Skill_deactivated 事件变体 + Python FFI Runtime.set_user_activated_skills();(6) docs/DECISIONS.md 4 条决策档案 + docs/howto/plan-then-execute.md (EN+ZH) how-to + docs/sdk/skills.md "illas behioral modes" 章§11 R1 标注: 全部架构正确——增强现有原语而非新建并行类型;§11 R2 范围妥协: E4 (持久化 user_activated_skills) 延后,退役触发 = session 一等公民化启动。影响范围: 27 files, +993/-23 LOC。回退方式: revert commits 0cfcbc7 + 7452348 + 27ee0c5 + 8270010。Oracle VERIFIED ( 轮:get_fn/upsert_fn + 转换层 + how-to doc)。 | | 2026-07-29 | 【API级+架构级+依赖级变更】v0.8.0-beta: HITL + Parallel Multi-Agent Dispatch | 变更前: PAR 已有 typed handoff(单链 A→B)+ workflow Parallel node(Eio.Semaphore bounded)。缺:(1) Human-in-the-Loop approval(agent 要发邮件/转帐/删库前必须人工 approve);(2) Parallel multi-agent dispatch convenience API;(3) current_conversation 并发 race。变更后: (1) HITL framework — 新 Approval 模块(approval_outcome 5-variant ADT + parameterized 'ctx approval_handler Sync_local/Async_callback/Webhook);handler_result 新增 Approval_required 变体;agent_config.approval_handler 可选字段;Runtime.resume_approval 持久化恢复;SQLite approvals table;7 个 Approval_* 事件变体;Engine.execute_approval 三分区 partition + outcome dispatch;lib/core/webhook.ml 完整 HTTP POST + HMAC-SHA256 + timeout;(2) Parallel — Runtime.invoke_parallel 便利 API + typed merge_fn;agent_dispatch_spec record;workflow Parallel 增强(per-branch workspace/approval_handler overrides + non-blocking approval suspension);(3) current_conversation mutex — Current_conversation sub-module(stdlib Mutex + get/set/update atomic RMW);9 个调用点转换。§11 R1 标注: 全部架构正确 — HITL suspend-resume 是终态设计(LangGraph-grade),parameterized handler 打破 Types↔Approval .cmi cycle,mutex 消除 reentrancy race。§11 R3 评估: 一次做对(3 个 TOP-LEVEL 决策全选架构正确路径)。影响范围: lib/core/approval.ml/mli(新)、lib/core/webhook.ml(新)、lib/core/engine.ml(三分区 + execute_approval)、lib/core/runtime.ml(resume_approval + invoke_parallel + Current_conversation + parallel_approval_cb)、lib/core/workflow_engine.ml(execute_parallel 增强 + exec_context.net + approval_suspend_payload)、lib/core/types.ml(Approval_required + approval_context + approval_pending_info + 4 事件变体)、lib/persistence/sqlite_persistence.ml(approvals table + CRUD)、lib/ffi/par_capi.ml(Python FFI 5-layer + ~net wiring)、bindings/python/par_runtime/runtime.py(register_approval_handler + resume_approval + invoke_parallel)。74 v0.8.0 tests。mkdocs build --strict exit 0。回退方式: revert commits 039fa3c..fd27969。Oracle VERIFIED(2 轮,empirical red-green proof for Bug 1 + Bug 2 regression tests)。 |

| 2026-07-26 | v0.6.4 prompt caching 案例 |

# 原"决策" 性质 长期正确做法
1 保留 message.content : string option 扁平,不引入 content_block list 范围妥协(伪装架构) 引入 content_block list,给 multimodal + per-block cache_control 铺路
2 Stable/Volatile 仅对 system_prompt_template 生效 范围妥协(漏掉主要 bug 来源) stable/volatile 应是 system_prompt 显式类型属性,所有用户必须声明
3 Auto_caching 策略自动标 last-tool + last-message 范围妥协(自作主张) 用户显式 mark_cache_breakpoint,PAR 不猜
4 永久 soft-fail(模板有 volatile builtin 时静默跳过) 范围妥协(把类型保证降级成 runtime hint) v0.6.4 soft 过渡 → v0.6.5 hard fail(构造期拒绝)

用户挑战后,4 条全部翻盘,scope 扩大。此案例确立 §11 原则,避免复发。

11.5 历史教训(2026-11 v0.16 发布周期)

  1. 依赖升级不等于安全修复已生效。 tls 2.1.5 提供了 ~ip,也让 x509 按 RFC 9525 校验 SAN;但如果调用点在 Domain_name 解析失败后不传 ~host/~ip,证书身份仍然完全不校验。升级依赖时必须逐条检查调用点是否真的走到新行为,尤其是 fail-open 的 fallback 分支。
  2. 发布完成以「实际产物可安装」为准,不以 workflow 结论为准。 PyPI publish 显示 success、GitHub asset 也在,但本机 pip 默认走镜像源(阿里云)尚未同步,pip install <version> 仍报找不到。发布后必须在全新 venv 里从 https://pypi.org/simple 安装并打印版本;预发布版本要看 PyPI JSON 的 releases[version],info.version 会停留在上一个 stable。
  3. 只断言 Success 的测试会放过「返回空结果」的缺陷。 find/grep 的 glob 完全匹配不到任何文件,旧测试只检查 handler 返回 Success 所以一直绿。新测试用临时目录树断言精确结果集;修复逻辑做变异验证(删掉实现,用例必须失败)。
  4. 全局可变状态要有显式契约和并发限制。 事件总线的 session 是 runtime 级单值;恢复契约、捕获顺序(prepare 回调)和「并发运行不按 run 归属事件」必须写进文档,否则下一个入口会重新引入 PAR-48p 的排序 bug。
  5. review 要覆盖「没有 diff 的变更」。 本次两批依赖升级没有代码 diff,但 review 从 TLS 调用点里挖出了 HIGH 级证书身份缺口。review 的输入是行为,不是 git diff。