企业官网建设流程全解析

• 人工智能
• 大模型
• AI Agent
• 代码智能体
• CLI
• 开发工具
• 工具调用
• MCP Clients

pi_agent_rust是一个用 Rust 编写的高性能 AI 编码代理（AI coding agent）命令行工具，零 unsafe 代码。它内置了一个可扩展的 TypeScript 扩展运行时（PiJS/QuickJS），而为了证明这个运行时"真的能跑"生态里的真实扩展，项目构建了一条**扩展符合性测试（Extension Conformance）**验证流水线，覆盖223 个真实扩展语料。本文将带你看懂这套流水线的设计思路与运行方式。

什么是"符合性测试"？双运行时对照是核心思路

一个扩展到底能不能在新运行时上跑，靠嘴说没有说服力。pi_agent_rust 的做法是双运行时差分测试（Differential Conformance）：

1. 同一个扩展文件，先在TypeScript 参考运行时（Bun + 旧版 pi-mono，充当"标准答案"Oracle）中加载运行；
2. 再在Rust 内嵌的 QuickJS 运行时（PiJS）中加载运行；
3. 把两边的输出做归一化（统一时间戳、路径、随机值），然后逐字段比对；
4. 一致记PASS，不一致记FAIL并输出详细 diff。

这套逻辑让"行为是否一致"变成了可自动判定、可回归对比的机器问题，而不是主观感受。

223 项扩展语料从哪来？

语料不是随手抓的，而是分层采样出来的。语料库位于 tests/ext_conformance/artifacts/，按来源分为四个层级：

采样策略定义在 docs/EXTENSION_SAMPLING_MATRIX.md 中：官方扩展全量纳入（Tier-0），必过语料（must-pass）目标≥200 个，另有长尾覆盖（Tier-2）。每个扩展入库时都会登记来源、版本、SHA-256 校验值，语料的真实性由 tests/ext_conformance/VALIDATED_MANIFEST.json 和 tests/ext_conformance/artifacts/SHA256SUMS.txt 保证——每个扩展还附带能力画像（是否注册工具/命令/事件钩子、是否使用 exec/http 等），见 tests/ext_conformance/API_USAGE_MATRIX.md。

5 个复杂度分层：扩展按"难度"分级考核

并非所有扩展都一视同仁。docs/ext-compat.md 定义了 5 个兼容层级，测试深度随复杂度递增：

跑一遍流水线：5 条测试泳道

符合性测试不是单一命令，而是一组互相印证的测试泳道（均在 tests/ 下，需要开启ext-conformancecargo feature，开关定义于 Cargo.toml）：

• 差分符合性：tests/ext_conformance_diff.rs —— 核心对照测试，TS Oracle vs Rust 运行时逐字段比对；
• 全量语料：tests/ext_conformance_generated.rs —— 对全部 223 项扩展执行"加载并注册"测试，生成完整报告；
• 场景符合性：tests/ext_conformance_scenarios.rs —— 用 JSON 场景夹具验证"注册形状 + hostcall 行为 + 输出内容"三要素；
• 运行时 API 矩阵：tests/ext_conformance_matrix.rs —— 校验 Node.js/Bun API 面覆盖率（Node 13/13 全过，Bunconnect/listen因沙箱限制打桩）；
• 策略负向测试：tests/extensions_policy_negative.rs 与 tests/capability_denial_matrix.rs —— 验证沙箱该拒绝的确实拒绝了。

常用命令（来自 docs/conformance-operator-playbook.md）：

# 完整 223 项扩展战役（快速 CI 上约 2 分钟） cargo test --test ext_conformance_generated conformance_full_report \ --features ext-conformance -- --nocapture # 快速检查（仅 5 个官方扩展） PI_OFFICIAL_MAX=5 cargo test --test ext_conformance_diff \ --features ext-conformance -- --nocapture

如何让测试"稳定可复现"：确定性工程

测试最怕 flaky。流水线用一套环境约定把所有随机性钉死：

• PI_TEST_MODE=1：固定时间戳、归一化工作目录；
• PI_CONFORMANCE_SEED/PI_EXT_RANDOM_SEED：固定随机种子；
• RUST_TEST_THREADS=1：串行执行，避免顺序敏感；
• 每个扩展运行于独立临时目录，TZ=UTC，不断言精确时间戳而断言"形状与存在性"。

这些规则写在 docs/EXTENSION_CAPTURE_SCENARIOS.md 中，并配有随机抽样子泳道 tests/ext_random_trials.rs 做日常冒烟。

如何解读结果：223 的数字与失败分桶

当前快照（见 tests/ext_conformance/reports/COMPATIBILITY_SUMMARY.md）：

每项扩展的机器可读结果落在 tests/ext_conformance/reports/conformance_summary.json，人读版本在 tests/ext_conformance/reports/CONFORMANCE_REPORT.md。失败不是笼统地记一个"挂了"，而是分桶归因：

防回归：CI 门禁与季度刷新机制

流水线不是"跑一次就完"，而是嵌进了日常工程节奏：

• CI 符合性门禁：每个 PR 跑 223 项测试（约 2 分钟），另有性能预算门禁（加载时间百分位不超基线）；一键执行入口是 scripts/ext_quality_pipeline.sh（格式化 → Clippy → 检查 → 单测 → 集成/符合性 → 预检分析器自测）；
• 季度刷新：docs/EXTENSION_REFRESH_CHECKLIST.md 定义了完整的语料刷新流程——发现新扩展 → 入库登记来源与校验值 → 跑符合性+性能 → 更新目录与报告；
• 紧急刷新触发条件：官方扩展由过转挂、语料中发现安全问题、或整体通过率跌破 80%的回归阈值。

治理层面，语料刷新、失败分诊、门禁刷新都明确了责任人，记录在 docs/program-governance.md。

延伸阅读：值得翻的文档与源码

• 兼容矩阵与 API 面：docs/extension-compatibility-matrix.md、docs/ext-compat.md
• 操作员手册（跑、调、读）：docs/conformance-operator-playbook.md
• 目录与来源追溯：docs/extension-catalog.json、docs/extension-artifact-provenance.json
• 扩展架构总览：docs/extension-architecture.md

总结：pi_agent_rust 用"双运行时差分 + 分层语料 + 确定性执行 + 失败分桶 + CI 门禁"五件事，把"我的 Rust 运行时能不能兼容 223 个真实 TypeScript 扩展"变成了一个可量化（92.4% 通过率）、可复现、可回归追踪的工程事实。对于任何想做运行时/解释器迁移的团队，这套验证流水线都是一份值得抄的作业。

• 人工智能
• 大模型
• AI Agent
• 代码智能体
• CLI
• 开发工具
• 工具调用
• MCP Clients