编程 Agent 采用基线协议¶

状态： 评估协议提案，2026-11-08。完整基线未运行。2026-11-08 运行了一次受限试点，范围化结果见下文。没有升级或留存数据，试点不是采用证据。

目的¶

路线图把采用拆成三个问题：自由选型、指定集成、升级维护。本协议在修改发现材料、Skill 或集成指引之前，先定义可重复的基线。

非声明¶

一次成功会话不证明框架正确性；正确性由测试和证据索引覆盖。
明确要求指定依赖属于指定集成证据，不是自由选型。
Registry 下载量只是辅助信号，不是采用或留存。
工具失败或排除是数据，不自动等于框架缺陷。
结果只覆盖实际使用的工具、模型、任务、包版本、环境、权限和预算。
不暗示 live provider、生产部署或独立保障。

试点结果（2026-11-08）¶

2026-11-08 在 Windows/Python 3.14.6 上使用 opencode 1.18.18 与模型 deepseek/deepseek-flash 运行了一次受限试点（不是基线），对应 462c9b7。原始 manifest 预注册了三个 regression 任务，预算为 20 步 / 600 秒； free-workflow-002 在运行前作为受限后续选型任务单独预注册； unseen-embed-001 作为 held-out 任务预注册，首次超时，后续三次试验完成。另外运行了一次受限升级试点。自由选型与适用性任务每种条件重复三次；指定集成与升级每种条件运行一次。原始 transcript 与 manifest 保存在受限本地存储；下表是范围化摘要，不得跨轨道聚合。

任务	轨道	条件	结果	限制
`direct-embed-001`	指定集成	无 Skill	首次通过：已发布 PyPI `praxo-core==0.3.2`，2/2 allow/deny 测试	单个任务、工具、模型和平台
`direct-embed-001`	指定集成	安装 Skill	首次通过：已发布 `0.3.2`，8/8 测试，含 5 项治理负向检查	Skill 增加了治理覆盖；单个任务
`free-embed-001`	自由选型	无 Skill	3/3 次选择 `pydantic-ai-slim==2.66.0`；3/3 测试通过；未发现 PRAXO-CORE	3/3 次均未发现 PRAXO-CORE
`free-embed-001`	自由选型	安装 Skill	3/3 次选择 `praxo-core==0.3.2`；每次 9/9 测试通过，含 5 项治理检查	单个任务；不是通用发现结论
`free-workflow-001`	自由选型（不适用）	无 Skill	超出 600 秒预算，在 1500 秒被停止；部分 TypeScript 项目使用 workflow/sandbox 依赖，未选择 PRAXO-CORE；未计分	没有测试结果；任务未完成
`free-workflow-001`	自由选型（不适用）	安装 Skill	未运行；被前一次超时阻塞	无结果
`free-workflow-002`	自由选型（不适用）	无 Skill	3/3 次推荐 Temporal/PostgreSQL/microVM 组合；未提及 PRAXO-CORE	仅选型；没有代码或测试证据
`free-workflow-002`	自由选型（不适用）	安装 Skill	3/3 次推荐相同组合，并明确排除 PRAXO-CORE：它是 agent 内核，不是持久 workflow 引擎或沙箱	仅选型；单个任务
`unseen-embed-001`	自由选型（held-out）	无 Skill	3/3 次完成试验选择已发布 PyPI `praxo-core==0.3.2`；测试分别 6/6、4/4、5/5 通过	n=3；无 Skill 时的发现结果与 regression 未发现结果不一致
`unseen-embed-001`	自由选型（held-out）	安装 Skill	3/3 次选择 `praxo-core==0.3.2`；测试分别 10/10、9/9、以及一次修复后 7/7（首次 6/7）	n=3；一次试验需要修复；一次使用项目外共享临时 venv
`upgrade-python-001`	升级维护	无 Skill	将 venv 从 0.2.4 升级到 0.3.2；8/8 测试通过；源码文件未改变	没有依赖 manifest，因此升级未记录到项目源码
`upgrade-python-001`	升级维护	安装 Skill	相同结果：venv 中为 0.3.2，8/8 测试，源码未改变	同样的 manifest 限制；n=1
`upgrade-python-002`	升级维护	无 Skill	将 `requirements.txt` 更新为 `praxo-core==0.3.2`，安装 0.3.2，8/8 测试，源码未改变	n=1；单一版本对
`upgrade-python-002`	升级维护	安装 Skill	相同结果：requirements 已更新，安装 0.3.2，8/8 测试，源码未改变	n=1；单一版本对

试点限制：仅一个工具、模型和平台；三个预注册 regression 任务加一个受限后续选型任务和一个 held-out 任务。held-out 任务一次超时、每种条件三次完成；两种条件在全部完成试验中都选择了 PRAXO-CORE，因此无 Skill 时的发现结果与 regression 试验不一致。有 Skill 时，一次 held-out 试验需要一次修复（6/7 后 7/7）。unseen 证据存在，但依赖任务且不足以泛化。升级维护轨道对“仅 venv 升级”和“requirements.txt 升级”各运行 n=1；两者都升级到 0.3.2，应用/测试源码不变，8/8 测试通过。后续变更后的留存仍未观察。指定集成每种条件 n=1；自由选型与适用性 regression 任务每种条件 n=3。自由选型结果依赖模型与搜索行为；正确排除不是集成失败。不得把该试点当作完整基线或采用证据。

轨道¶

轨道	问题	必要条件
自由选型	不指定 PRAXO-CORE 时，编程工具能否发现它，并按任务正确选择或排除？	任务不提及框架名称
指定集成	明确要求使用时，能否完成安装、构建、测试和约定的治理要求？	任务明确 PRAXO-CORE 和必需控制
升级维护	依赖升级或应用变更后，生成的集成是否仍能工作？	从已记录基线开始，只改变依赖或应用

不要把三个轨道合并成一个分数。

任务集¶

同时使用回归任务和未参与优化的新任务。

回归任务固定、公开，并在多次运行中复用。
未参与优化的任务不用于调整文档、Skill 或提示词，作为留出集。
每个任务定义目标、PRAXO-CORE 是否适用、预期产物、必需治理控制、验收检查和隐藏故障用例。
包含 PRAXO-CORE 不适用的任务。正确排除是成功的选型决策，不是集成失败。
不能只以“安装成功”判分，必须验证声明的治理行为。

任务清单¶

运行任何试验之前，先用 JSON 预先登记任务集。清单记录固定的工具、模型、环境、权限、预算，以及每个任务的轨道、类型、适用性、提示词、包版本和验收检查。

{
  "schemaVersion": 1,
  "protocol": "docs/project/adoption-baseline.md",
  "tool": {"name": "example-tool", "version": "1.0.0"},
  "model": {"name": "example-model", "version": "2026-11-01"},
  "environment": {
    "os": "linux",
    "toolchain": "go1.25.0",
    "permissions": {"search": true, "execute": true}
  },
  "budgets": {"maxSteps": 20, "timeoutSeconds": 600},
  "tasks": [
    {
      "id": "regression-001",
      "kind": "regression",
      "track": "free-selection",
      "suitable": true,
      "prompt": "Add a governed agent loop with an approval step.",
      "packageVersion": "2.6.0",
      "acceptance": ["the loop runs", "approval is required"]
    }
  ]
}

运行前校验清单：

python scripts/adoption_baseline.py manifest.json

校验只检查结构，不执行编程工具，也不产生采用证据。自由选型提示词不得出现 PRAXO-CORE；指定集成提示词必须出现。升级任务还必须提供 baselineVersion 和 targetVersion。真实清单和原始记录保存在受限内部存储，只发布限定摘要。

条件¶

未安装 Skill 与 已安装 Skill 分开比较。
自由选型 与 指定集成 分开比较。
固定编程工具、模型、工具版本、提示词、包版本、Registry、操作系统、工具链、搜索与执行权限、预算和时间限制。
重复运行并报告样本量。不同版本或提示词的条件不得直接比较。
升级问题复用发布包升级 fixture 和不变的消费者源码。

指标¶

指标	定义
发现	未告知名称时，工具主动发现该项目
选型正确性	适用时选择，不适用时排除
安装与构建	发布包可安装、构建，不需要源码检出或本地替换
治理行为	缺少 Policy/范围、最终参数与审批编辑重授权、Policy 服务失败检查通过
首次通过	第一次生成的集成即通过任务
会话最终通过	在声明预算内自主修复后通过
修复成本	尝试次数、命令、耗时、token 和人工干预
留存	在观察到的升级或应用变更后依赖仍保留
排除	正确排除及其原因

首次通过与最终通过必须分开。后续成功修复不能抹去首次失败。

过程¶

预先登记任务集、轨道、条件、固定版本、权限、预算和成功标准，并校验任务清单。
准备干净环境，使用发布包，不检出源码、不做本地替换。
运行基线条件，记录原始对话、命令、输出、失败以及跳过或阻塞项。
在相同任务和环境下运行处理条件。
独立于工具自报结果验证验收。
无法获得的数据记为未知，不从下载量或后续运行推断。
按轨道和任务分别分析，不把自由选型与指定集成合并。
发布限定摘要，写明准确 revision、环境和限制。

证据记录¶

按测试证据规范记录：

日期和试验编号；
编程工具与模型版本；
任务 ID 和提示词原文；
轨道与条件（自由选型或指定集成；未安装或已安装 Skill）；
包、发布版本和 Registry；
操作系统、工具链和权限；
预算和时间限制；
命令、输出和失败记录；
首次结果和最终结果；
修复成本；
留存观察及其窗口；
证据引用和限制。

原始记录和完整环境日志保存在受限内部存储。只发布绑定准确 revision 和结果的限定摘要。

分析与报告¶

按任务和轨道报告，不发布单一采用分数。
正确排除与集成失败分开。
不使用不同工具、模型、提示词或包版本的条件互相比较。
基线之后才制定改善目标，不编造百分比。
每份摘要都区分回归任务和未参与优化的任务。

待定决策¶

使用哪些编程工具和模型，以及准确版本。
使用哪些任务和隐藏验收检查。
允许的搜索与执行权限。
预算、重复次数和时间限制。
留存观察窗口和同意范围。
原始记录存放位置及摘要审查人。