From 23410db1fb99168eb9fc106fe146a7fb9c37c757 Mon Sep 17 00:00:00 2001 From: scotares Date: Mon, 28 Sep 2026 16:36:55 +0800 Subject: [PATCH 1/2] =?UTF-8?q?docs(plan):=200.5.0=20=E2=86=92=201.0=20roa?= =?UTF-8?q?dmap=EF=BC=88=E5=9B=9B=E9=98=B6=E6=AE=B5=20+=20=E4=BD=93?= =?UTF-8?q?=E7=A7=AF=E9=A2=84=E7=AE=97=20+=20=E7=94=9F=E6=80=81=E8=B7=9F?= =?UTF-8?q?=E8=B8=AA=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit issue 驱动的排期总览，单项设计仍在各 issue / RFC： - 0.6.0 收缩+体积止血：#166 A2–A5/E1、#185、#170/#171(前半)、 B1+C2 解锁项、S1 桌面 .a 切 staticlib profile、S2 体积门禁 - 0.7.0 protocol registry + auth：#166 B2–B9、#174/#175、#171(后半)、 S3 体积审计（gating 仅可选路径，默认 API 不变） - 0.8.0 FFI ops + bindings：#166 C/D 轨 - 1.0 锚点：#167 transport replay、#179/#181/#180 清尾、API 冻结 - §6 横切：产物体积预算（瘦身不改变对外 API 的约束）与 协议/生态定期跟踪节奏（扩展 #170 为三条流水） --- docs/plan/roadmap.md | 169 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 docs/plan/roadmap.md diff --git a/docs/plan/roadmap.md b/docs/plan/roadmap.md new file mode 100644 index 00000000..12c9fcff --- /dev/null +++ b/docs/plan/roadmap.md @@ -0,0 +1,169 @@ +# Roadmap：0.5.0 → 1.0 + +> 基线：v0.5.0（2026-09-28 发布）。本文档是 issue 驱动的排期总览， +> 单项设计与差距分析仍在各 issue / RFC 内，本文不复制细节。 +> 上次复核：2026-09-28（open issues #95 #166 #167 #170 #171 #174 #175 #179 #180 #181 #185）。 + +## 1. 依赖全景 + +``` +#166 代码缩减总纲（25 PR，净 ≈ −44k 行，已对抗性验证） +├─ A 轨 机械清理 A1 ✅(#169)；A2–A5 未动，互相独立 +├─ B 轨 protocol registry（RFC-0032 修正版，−10~12k 行） +│ ├─→ #174 Auth L1（registry auth schema + apply_auth） ← 依赖 B1 +│ │ └─→ #175 Auth L2（CredentialStore + TokenRefresher） +│ └─→ #167 transport-level replay ← 依赖 B1 +│ └─→ #179 replay 子命令 ← 依赖 #167 +├─ C 轨 FFI ops（109 导出 → 9 JSON 导出）；C2 构造器转发是 B4/B5 前置 +├─ D 轨 7 语言 binding 重写 + D8 类型镜像生成（依赖 C1；手工镜像 18.9k 行归零） +├─ E 轨 #164 内部清理 + 文档三层重组（docs/ 用户面 / rfc/ 索引 / archive/ 历史） +│ +├── 独立项：#185 ToolInput 类型化 + 删 StreamingToolCallTracker +├── 独立项：#170 registry 维护自动化 → #171 triage（27 个 base_url 分歧 + 116 缺失） +└── 小项：#181 session 后续 | #180 cache probe §10 八项 | #179 online mode（需设计决策） + +横切（见 §6）：产物体积（桌面 .a 117–139MB）| 协议/生态定期跟踪（扩展 #170） + +常设跟踪：#95 错误体系（P1/P2 已落地于 #94/#158，基本收官，新错误相关 PR 挂此 issue） +``` + +## 2. 阶段划分 + +### 0.6.0 —— 「收缩 + 体积止血」（低风险，目标 ~3-4 周） + +目标：消化全部纯减法与解锁项，发布产物体积回落，API 面不动（除两处 Rust 层 breaking）。 + +| 项 | 内容 | 量级 | +|---|---|---| +| A2 | 删生成式 `ProviderName` 枚举及 9 份语言副本 | −3.5k | +| A3 | `provider-inventory/` 归档 `archive/`（42.6k 行数据移出仓库树） | 归档 | +| A4 | `aimux-web` 140 个 ts-rs 类型副本指向生成集 | −3.0k | +| A5 | Flutter example 删桌面平台脚手架（iOS/Android 留守 CI 门禁） | −3.0k | +| E1 | #164 内部清理 + 文档三层重组（§1–§3/§14 保留，其余入 rfc/0031） | −1.5k | +| #185 | `ToolInput{Raw,Parsed}` 类型化 + 删 429 行死码 tracker | −0.5k | +| #170 | `sync_registry.py` 周报 + `probe_registry.py` 月探活 + scheduled Action | 新增脚本 | +| #171(前半) | 27 个 base_url 分歧逐条 triage（修错的、note 有意的） | 数据 | +| **S1** | **桌面 `.a` 切 LTO-off profile**：v0.5.0 的 `libaimux_ffi-*.a` 达 117–139MB（fat-LTO bitcode，同 iOS 根因）；`ios-release` profile 改名 `staticlib-release` 复用于所有 `.a` 目标，Linux 实测 138.4→66.5MB | 体积 | +| **S2** | **体积门禁推广**：把 iOS 的 64MiB slice 守门推广到所有发布产物（桌面 `.a`、Android `.so`、`.node`、wheel），CI 输出体积报告 | 门禁 | +| **B1** | registry 行加 `protocol` 列（纯增量，RFC-0032 修正 1–7 已写入 issue） | +行 | +| **C2** | 40 个 FFI 构造器转 `provider()` 的转发 shim | 前置项 | + +B1 + C2 是本版本最重要的两项：它们解锁 #174 / #175 / #167 / #179 与 B4–B6， +纯增量零破坏，越早落地后续越顺。 + +版本语义：Rust 层 breaking（A2 删枚举、#185 换类型），binding wire 与 C ABI 不变。 + +### 0.7.0 —— 「protocol registry + auth」（主菜，目标 ~5-6 周） + +目标：provider 构造从代码变成数据，auth 从 12 处手写收敛为一处；顺带完成体积审计（S3，见 §6.1）。 + +| 项 | 内容 | +|---|---| +| B2→B9 | protocol registry 全量：17 个 LanguageModel 实现 → 7 个协议；33 个 wrapper 退役；responses 家族合并（注意 #166 修正 3：xai/mistral 非纯 fork，节流为 profile hooks；修正 6：五个 `MistralProvider::model()` 直连点先迁 `provider()`） | +| #174 | registry `auth{kind,env,header}` schema + `apply_auth()` 单点；`none` kind 退役 33 处 `PLACEHOLDER_API_KEY` | +| #175 | `Credential` 解析序（explicit → env → store）+ `CredentialStore` + 通用 `TokenRefresher`（codex_refresh 泛化；vertex 未装 refresher 时照旧抛 `TokenExpired`） | +| #171(后半) | 116 个缺失 provider 按 auth/protocol schema 一行一个补齐 + cassette | + +版本语义：Rust API 大 breaking（33 wrapper 退役）；C ABI 经 C2 转发不受影响。 + +0.7.0 期间体积跟进（S3）：`cargo-bloat` 审计 0.5.0 动态库增重来源（Android `.so` +13.4→21MB，+57%：jsonschema / rustls+webpki-roots(ws) / replay / repair 等新依赖）， +评估 per-modality 或 per-protocol feature gating 对 binding 包的收益——产出仅为 +**可选的 feature 组合与裁剪文档**，默认 feature 全量、对外 API 不变（§6.1 约束）。 +node workspace 默认全量的问题需一并解决。 + +### 0.8.0 —— 「FFI / binding 手术」（~4-5 周） + +| 项 | 内容 | +|---|---| +| C1→C3→C4 | 109 个 FFI 导出收敛为 9 个 JSON ops（recording/mock/session 走 `configure` op） | +| D1–D7 | 七语言 binding 按同一 ops 面重写（Kotlin 先行——纯 Java artifact；Node 先测 runtime 重入；Python 先做 ctypes 原型） | +| D8 | 类型镜像生成：serde 类型 → JSON Schema → 六语言，`gen_ts_types.py --check` 扩到全部输出 | + +版本语义：C ABI breaking，八个 binding 全量重发。 + +### 1.0 —— 「replay 完成 + API 冻结」锚点 + +| 项 | 内容 | +|---|---| +| #167 | transport-level replay：mock 挂在 HTTP 层跑真协议代码，覆盖全协议/全模态；删 OpenAI-only 解码器（~1.5k 行）；`ProviderRecord` = registry 行 + protocol；exchange schema 与 RFC-0003 cassette 统一；Router/MoA 记录实际 child；`PassthroughOnMiss` | +| #179 | `aimux-cli replay` 子命令（依赖 #167）；`online` mode 需先做设计决策（dump-on-signal / sidecar / FFI export，单独 RFC） | +| #181 / #180 | session partial-match 决策、debug CLI（并入 aimux-cli）、cache probe §10 验证项清尾 | +| — | 1.0 发布判据：#166 ledger 全勾 + 错误模型 #95 / 请求管线 #164 双稳定一个周期 | + +时机理由：错误模型（#158）、请求管线（#164）刚在 0.5.0 定型；#166 全量落地后 +API 面才真正定形，1.0 语义干净。粗估 3.5–5 个月后。 + +## 3. 贯穿原则（沿用 #166 ground rules） + +- **一个方向一个 PR**；providers 先于 bindings；最高确定性的删除先落。 +- **Cassettes 是字节级回归门禁**：2,799 份录音只增不减，后续 PR 依赖更重。 +- **文档重组而非删除**：`git mv` + 链接修复；`archive/` 只留 README 指向 git 历史。 +- **Scheduled registry 报告永不阻塞合并**（#170 验收条件）。 +- 语言规则：`docs/` 与 `bindings/*/README` 英文，`rfc/` 中文。 + +## 4. 近期第一步（本周可并行开） + +1. **A2–A5**：四个独立 PR，纯删码/归档。 +2. **#185**：先删 `StreamingToolCallTracker`（纯删），再 `ToolInput` 枚举（17 处机械替换）。 +3. **#170**：sync/probe 脚本 + Action，吸收两个 LiteLLM survey 脚本。 +4. **S1**：桌面 `.a` 切 staticlib profile——机制已在 iOS 修复（PR #196）中验证， + 改 profile 名 + `ffi-build` job 换 profile + S2 门禁，一个小 PR。 +5. **B1 + C2**：解锁项，RFC-0032 修正版按 issue 内 7 条修正执行。 + +## 5. 版本节奏预估 + +| 版本 | 主题 | 预估 | +|---|---|---| +| 0.6.0 | 收缩 + 解锁 + 体积止血 | ~3-4 周 | +| 0.7.0 | protocol registry + auth + 体积审计 | ~5-6 周 | +| 0.8.0 | FFI ops + bindings | ~4-5 周 | +| 1.0 | replay + 冻结 | ~2-3 周 | + +产出节奏参照 0.3.0→0.5.0（6 周 13 PR，含 3 个特大）；25 个 #166 PR +按 2-3 PR/周推进。各阶段允许交叠：A/E 轨与 B1/C2 无依赖可同批。 + +## 6. 横切需求 + +### 6.1 产物体积（binary-size budget） + +v0.5.0 现状与目标： + +| 产物 | v0.5.0 | 目标 | 手段 | +|---|---|---|---| +| 桌面 `.a` ×5 | 117–139 MB | ≤ 70 MB | S1：staticlib LTO-off profile（已验证 138.4→66.5MB） | +| iOS slice | ~40 MB/片 | ≤ 32 MB | 已落 strip+守门（#196）；S3 审计后视情况再压 | +| Android `.so` ×3 | 21 MB 合计 | 默认构建依赖瘦身回落；裁剪构建 ≤ 15 MB | S3：cargo-bloat 找增重；gating 仅作可选路径（§6.1 约束） | +| `.node` / wheel | 15–22 MB | 报告化 | S2 门禁先跟踪，S3 评估可选裁剪收益 | +| pub 包压缩 | 31.7 MB | ≤ 25 MB | 跟随 iOS/Android 改善（Flutter 包固定全量） | + +原则：体积是发布门禁不是事后优化——每个产物有预算线（S2），回归即 CI 失败， +与 iOS 的 64MiB 守门同机制。体积问题不新增单独版本，S1/S2 随 0.6.0，S3 随 0.7.0。 + +**约束：瘦身不改变对外 API。** 所有体积手段（profile、strip、gating）以默认 +构建的对外 API 面不变为前提：S1/S2 是构建管线变化，代码零改动；S3 的 feature +gating 若落地，只新增「可选的小体积构建路径」（按需关闭某模态/某协议的 +编译），默认 feature 集全量、binding 的完整 API 不变——凡需要删除或收窄 +公开 API 才能换到的体积收益，不在此需求范围内，需另立提案讨论。 + +### 6.2 协议与生态定期跟踪（ecosystem tracking） + +registry 数据层已由 #170 覆盖（weekly models.dev diff + monthly reachability）。 +协议行为层与上游演进在此扩展为固定节奏： + +| 周期 | 内容 | 产出 | +|---|---|---| +| 每周 | models.dev registry diff（#170） | 报告贴固定 issue，不阻塞合并 | +| 每月 | reachability probe（#170） | 同上 | +| 每月 | **上游参照系 diff**：Vercel AI SDK release notes + pi-ai 变更，标注 aimux 未跟进的能力 | 差异清单贴 tracking issue，超出 2 个版本未跟进的项升 issue | +| 每季度 | **协议新鲜度审计**：对照各 provider 官方 changelog（OpenAI Responses 演进、Anthropic thinking/computer-use 参数、Gemini API 版本等），过时 cassette 标记 | 审计报告 + 需更新的协议转换 issue | +| 每季度 | **新机制评估**：新模态/新协议特性（MCP、computer use、audio output…）→ 开 DRAFT RFC 或明确记录不做 | RFC 决策记录 | + +落地方式：扩展 #170 的 scheduled Action 为三条流水（registry-diff / probe / +upstream-diff），quarterly 审计人工触发。#167（transport replay）落地后， +「重新录制真实 provider cassette」可脚本化，协议新鲜度从文档对照升级为 +字节级验证——这是把 #167 排在 1.0 前的另一个理由。 + +关联：#95（错误体系参照 AI SDK）是此节奏在错误域的常设形式；#171 的 triage +是 registry 数据层的一次性清偿。 + From 2dfe5b10527e7c24e1e0162d8e23d724531be26a Mon Sep 17 00:00:00 2001 From: eric8810 Date: Tue, 29 Sep 2026 21:56:31 +0800 Subject: [PATCH 2/2] docs: rewrite roadmap against RFC-0036 and move it to ROADMAP.md - re-staged around RFC-0036: 0.6 gates + protocol groundwork, 0.7 L1 + auth, 0.8 ops protocol (FFI + stdio), 0.9 governance, 1.0 freeze only - moved out of docs/plan/ (archived by the E1 docs reorg) - A2 flagged as binding source-level breaking, with migration note - C1 in 0.8 with old exports coexisting; C4 at 1.0; D1/D5 can go early - #167/#179 moved to 0.9 so 1.0 carries no large feature - RFC-0031/0032/0033 landing is an explicit 0.6 item - S1 limited to the staticlib job; S2 gets concrete thresholds; perf gate P - refreshed facts: FFI 123 exports, #164 merged, A1 done; 0.6 re-estimated Co-Authored-By: Claude --- ROADMAP.md | 163 +++++++++++++++++++++++++++++++++++++++++ docs/plan/roadmap.md | 169 ------------------------------------------- 2 files changed, 163 insertions(+), 169 deletions(-) create mode 100644 ROADMAP.md delete mode 100644 docs/plan/roadmap.md diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 00000000..dce47390 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,163 @@ +# Roadmap：0.5.0 → 1.0 + +> 基线：v0.5.0（2026-09-27 发布）。方向依据 [RFC-0036](rfc/0036-positioning-and-layered-architecture.md) +> （定位与分层架构）；本文档只做排期，单项设计与差距分析在各 issue / RFC 内。 +> 上次复核：2026-09-29（open issues #95 #166 #167 #170 #171 #174 #175 #179 #180 #181 #185）。 +> +> 位置说明：放在仓库根目录而非 `docs/plan/`——后者在 E1 文档重组中整体归档；`docs/` 的英文约定不适用于本文。 + +## 0. 方向（RFC-0036 摘要） + +aimux 是 **provider 接入与治理的运行时**： + +1. 性能与体积是第一基准线——每个产物有预算，回归即 CI 失败。 +2. 多语言绑定的目的是多语言栈的**行为统一**。 +3. 治理（端侧测试、漂移检测、能力验证）是一等能力。 +4. 协议持续演进、私有 API 持续存在——数据真相下沉到 L0 传输 / L1 协议，L2（AI SDK 形态）是版本化投影，不随 1.0 冻结。 +5. 与 harness 解耦——同一套 **ops 协议**两个入口：FFI（8 种绑定）与 stdio CLI。 +6. 不做 agent / 编排 / 多租户网关业务。 + +## 1. 依赖全景 + +``` +#166 代码缩减总纲（25 PR，净 ≈ −44k 行）——保留，按 RFC-0036 §8 重新归类 +├─ A 轨 机械清理 A1 ✅(#169)；A2–A5 互相独立 +├─ B 轨 protocol registry = L1 协议层（RFC-0032，需先入库） +│ ├─→ #174 Auth L1 ──→ #175 Auth L2 ← 依赖 B1 +│ └─→ #167 transport-level replay ──→ #179 replay 子命令 ← 依赖 B1 +├─ C 轨 FFI（现 123 个 extern "C"，#166 基线 109）→ ops 协议（C1 升级为传输无关协议：op 表 / 二进制帧 / 版本协商） +│ └─ C2 构造器转发 shim 是 B4/B5 前置 +├─ D 轨 8 种绑定重写为 ops 薄封装（依赖 C1）+ D8 类型镜像生成 +├─ E 轨 内部清理（#164 已合入，改为 master 上独立 PR）+ 文档三层重组 +│ +├── 新增（RFC-0036）：L0 native passthrough | ops 协议 schema | stdio CLI | 性能门禁 P +├── 独立项：#185 ToolInput 类型化 + 删 StreamingToolCallTracker +├── 独立项：#170 registry 维护自动化 → #171 triage（前半：27 个 base_url 分歧） +└── 小项（随时插空）：#181 session 后续 | #180 cache probe §10 + +常设跟踪：#95 错误体系（新错误相关 PR 挂此 issue） +``` + +## 2. 阶段划分 + +### 0.6.0 ——「门禁 + 协议地基 + 纯减法」（~4-6 周） + +| 项 | 内容 | +|---|---| +| RFC | RFC-0031 / 0032（写入 #166 的 7 条修正）/ 0033 入库——B1、#170、#174、#175 均引用它们 | +| **S1** | 桌面 `.a` 切 LTO-off staticlib profile（`ios-release` 改名 `staticlib-release`）。**只改 staticlib job**：`aimux-ffi` 同时产出 cdylib，`.so/.dylib/.dll` 保持 fat-LTO。实测 138.4 → 66.5 MB | +| **S2** | 体积门禁推广到所有发布产物，**每个产物给具体阈值**（初期取当前值 +10%），CI 输出体积报告 | +| **P** | 性能回归门禁：单请求开销、流式吞吐、RSS 增长 | +| A2–A5 | 删 `ProviderName` 枚举及各语言副本；归档 `provider-inventory/`；aimux-web 类型副本；Flutter example 桌面脚手架 | +| E1 | 内部清理 + 文档三层重组 | +| #185 | 删 `StreamingToolCallTracker`（纯删）→ `ToolInput{Raw,Parsed}` | +| #170 / #171 前半 | sync/probe 脚本 + scheduled Action；27 个 base_url 分歧 triage | +| **B1 + C2** | 解锁项：protocol 列 + `from_resolved`；40 个 FFI 构造器转发 shim | +| **ops 协议 schema** | op 表、消息与错误信封、二进制帧、版本协商——先以文档 + 测试落地（RFC-0036 §4） | +| **L0 passthrough** | 原样调用任意 provider 端点，享受 auth / 重试 / 录制 | + +版本语义： +- **Rust 层 breaking**：A2 删枚举、#185 换类型。 +- **绑定源码级 breaking**：A2 删除 Go / Java / Kotlin / Swift / Flutter / Node / Python 的 `ProviderName` 类型化常量，改为字符串（Node 由 `gen_ts_types.py` 生成 string-literal union 保留补全）；CHANGELOG 需给迁移说明。 +- binding wire 与 C ABI 不变。 + +### 0.7.0 ——「L1 协议层 + auth」（~5-6 周） + +| 项 | 内容 | +|---|---| +| B2–B8 | 17 个 LanguageModel 实现 → ~7 个协议；33 个 wrapper 退役；responses 家族合并（遵循 #166 修正 3/6） | +| #174 / #175 | registry `auth` schema + `apply_auth()`；Credential 解析序 + CredentialStore + TokenRefresher | +| L2 补齐 | `StreamPart::Raw` / `provider_metadata` 在各协议接线——投影不下的不得静默丢弃 | +| **S3** | `cargo-bloat` 审计 0.5.0 增重（Android `.so` 13.4 → 21 MB）；feature gating 仅作可选小体积路径，默认全量 | +| 调研 RFC | L2 数据模型选型（AI SDK 形态 / Open Responses items / 自有），指标见 RFC-0036 §3 | + +版本语义：Rust API 大 breaking（33 wrapper 退役）；C ABI 经 C2 转发不受影响。 + +### 0.8.0 ——「ops 协议落地」（~4-5 周） + +| 项 | 内容 | +|---|---| +| C1 | 9 个导出 + `dispatch`，**同一 dispatch 同时服务 FFI 与 stdio CLI**；旧导出保留共存 | +| C3 | `aimux_error_*` 访问器 → 错误 JSON 信封（含派生 `retry_after_ms`） | +| D1–D7 | 8 种绑定迁到 ops 薄封装。D1 Kotlin（只依赖 Java artifact）与 D5 Flutter ffigen 过渡版不依赖 C1，可在 0.6/0.7 提前做 | +| D8 | 类型镜像生成：serde → JSON Schema → 各语言，`--check` 门禁扩到全部输出 | +| P | stdio 入口往返开销纳入性能门禁 | + +版本语义：新 ABI 加入，旧导出并存（#166 要求共存至少一个 minor 版本）；绑定按各自节奏迁移。 + +### 0.9.0 ——「治理」（~3-4 周） + +| 项 | 内容 | +|---|---| +| #167 | transport-level replay：mock 挂 HTTP 层跑真协议代码，覆盖全协议 / 全模态；`ProviderRecord` = registry 行 + protocol | +| 漂移检测 | #170 扩展：定期重录，与 cassette 字节级 diff | +| 能力矩阵 | provider × 能力，每格由探测或录制支撑 | +| CLI | `aimux probe / replay / diff`（#179 replay 子命令并入）；#181 debug CLI 并入 | + +### 1.0 ——「冻结」（~1-2 周） + +| 项 | 内容 | +|---|---| +| C4 | 8 种绑定全部迁移后删除旧导出、旧头文件、旧 FFI 测试 | +| 冻结范围 | ops 协议与 L0 / L1 契约。**L2 独立版本化，不随 1.0 冻结** | +| 发布判据 | #166 ledger 全勾（B9 / #171 后半除外）；错误模型 #95 与请求管线 #164 稳定一个周期；各门禁（S2 / P）连续绿 | + +## 3. 贯穿原则（沿用 #166 ground rules） + +- **一个方向一个 PR**；providers 先于 bindings；最高确定性的删除先落。 +- **Cassettes 是字节级回归门禁**：2,799 份录音只增不减。 +- **文档重组而非删除**：`git mv` + 链接修复；`archive/` 只留 README 指向 git 历史。 +- **Scheduled registry 报告永不阻塞合并**（#170 验收条件）。 +- **瘦身不改变对外 API**（§6.1）。 +- 语言规则：`docs/` 与 `bindings/*/README` 英文，`rfc/` 中文。 + +## 4. 近期第一步（本周可并行开） + +1. **RFC-0032 / 0033 入库**：B1 与 #174 的前提。 +2. **S1 + S2**：一个小 PR——改 profile 名、staticlib job 换 profile、全产物体积阈值。 +3. **A2–A5**：四个独立 PR；#166 的 A1 checkbox 补勾（#169 已合入）。 +4. **#185**：先删 tracker，再换 `ToolInput`。 +5. **B1 + C2**：解锁项。 + +## 5. 版本节奏预估 + +| 版本 | 主题 | 预估 | +|---|---|---| +| 0.6.0 | 门禁 + 协议地基 + 纯减法 | ~4-6 周 | +| 0.7.0 | L1 协议层 + auth | ~5-6 周 | +| 0.8.0 | ops 协议落地（FFI + stdio） | ~4-5 周 | +| 0.9.0 | 治理 | ~3-4 周 | +| 1.0 | 冻结 | ~1-2 周 | + +合计约 4-5.5 个月。产出节奏参照 0.3.0 → 0.5.0（6 周 13 PR），按 2-3 PR/周推进；各阶段允许交叠，A/E 轨与 B1/C2 无依赖可同批，#180 / #181 随时插空。 + +**不排期**（RFC-0036 已定方向）：UDS / HTTP 传输、`aimux-proxy` 扩展包——有真实需求时另立 RFC。**降级**：B9、#171 后半（补 116 个 provider），机会性推进。 + +## 6. 横切需求 + +### 6.1 产物体积与性能（硬门禁） + +| 产物 | v0.5.0 | 目标 | 手段 | +|---|---|---|---| +| 桌面 `.a` ×5 | 117–139 MB | ≤ 70 MB | S1（只改 staticlib job） | +| iOS slice | ~40 MB/片 | ≤ 32 MB | 已落 strip + 64 MiB 守门（#196）；S3 后视情况再压 | +| Android `.so` ×3 | 合计 21 MB | 默认构建回落；可选裁剪构建 ≤ 15 MB | S3 | +| `.node` / wheel | 15–22 MB | S2 阈值（当前 +10%） | S2 门禁，S3 评估 | +| pub 包压缩 | 31.7 MB | ≤ 25 MB | 跟随 iOS / Android | +| `aimux` CLI | — | 0.8 设定预算 | 新增 | + +性能门禁 P：单请求开销、流式吞吐、RSS 增长；0.8 起加入 stdio 往返。 + +**约束：瘦身不改变对外 API。** profile、strip 是构建管线变化；feature gating 只新增可选的小体积构建路径，默认 feature 全量。需要删除或收窄公开 API 才能换到的收益，另立提案。 + +### 6.2 协议与生态定期跟踪 + +| 周期 | 内容 | 产出 | +|---|---|---| +| 每周 | models.dev registry diff（#170） | 报告贴固定 issue，不阻塞合并 | +| 每月 | reachability probe（#170） | 同上 | +| 每月 | 上游参照系 diff：AI SDK、pi-ai、Open Responses 规范变更 | 差异清单；超过 2 个版本未跟进的升 issue | +| 每季度 | 协议新鲜度审计：各 provider 官方 changelog 对照，过时 cassette 标记 | 审计报告 + 协议转换 issue | +| 每季度 | 新机制评估（新模态 / 新协议特性）→ DRAFT RFC 或明确记录不做 | RFC 决策记录 | + +0.9 的漂移检测落地后，协议新鲜度从文档对照升级为字节级验证（#167）。 diff --git a/docs/plan/roadmap.md b/docs/plan/roadmap.md deleted file mode 100644 index 12c9fcff..00000000 --- a/docs/plan/roadmap.md +++ /dev/null @@ -1,169 +0,0 @@ -# Roadmap：0.5.0 → 1.0 - -> 基线：v0.5.0（2026-09-28 发布）。本文档是 issue 驱动的排期总览， -> 单项设计与差距分析仍在各 issue / RFC 内，本文不复制细节。 -> 上次复核：2026-09-28（open issues #95 #166 #167 #170 #171 #174 #175 #179 #180 #181 #185）。 - -## 1. 依赖全景 - -``` -#166 代码缩减总纲（25 PR，净 ≈ −44k 行，已对抗性验证） -├─ A 轨 机械清理 A1 ✅(#169)；A2–A5 未动，互相独立 -├─ B 轨 protocol registry（RFC-0032 修正版，−10~12k 行） -│ ├─→ #174 Auth L1（registry auth schema + apply_auth） ← 依赖 B1 -│ │ └─→ #175 Auth L2（CredentialStore + TokenRefresher） -│ └─→ #167 transport-level replay ← 依赖 B1 -│ └─→ #179 replay 子命令 ← 依赖 #167 -├─ C 轨 FFI ops（109 导出 → 9 JSON 导出）；C2 构造器转发是 B4/B5 前置 -├─ D 轨 7 语言 binding 重写 + D8 类型镜像生成（依赖 C1；手工镜像 18.9k 行归零） -├─ E 轨 #164 内部清理 + 文档三层重组（docs/ 用户面 / rfc/ 索引 / archive/ 历史） -│ -├── 独立项：#185 ToolInput 类型化 + 删 StreamingToolCallTracker -├── 独立项：#170 registry 维护自动化 → #171 triage（27 个 base_url 分歧 + 116 缺失） -└── 小项：#181 session 后续 | #180 cache probe §10 八项 | #179 online mode（需设计决策） - -横切（见 §6）：产物体积（桌面 .a 117–139MB）| 协议/生态定期跟踪（扩展 #170） - -常设跟踪：#95 错误体系（P1/P2 已落地于 #94/#158，基本收官，新错误相关 PR 挂此 issue） -``` - -## 2. 阶段划分 - -### 0.6.0 —— 「收缩 + 体积止血」（低风险，目标 ~3-4 周） - -目标：消化全部纯减法与解锁项，发布产物体积回落，API 面不动（除两处 Rust 层 breaking）。 - -| 项 | 内容 | 量级 | -|---|---|---| -| A2 | 删生成式 `ProviderName` 枚举及 9 份语言副本 | −3.5k | -| A3 | `provider-inventory/` 归档 `archive/`（42.6k 行数据移出仓库树） | 归档 | -| A4 | `aimux-web` 140 个 ts-rs 类型副本指向生成集 | −3.0k | -| A5 | Flutter example 删桌面平台脚手架（iOS/Android 留守 CI 门禁） | −3.0k | -| E1 | #164 内部清理 + 文档三层重组（§1–§3/§14 保留，其余入 rfc/0031） | −1.5k | -| #185 | `ToolInput{Raw,Parsed}` 类型化 + 删 429 行死码 tracker | −0.5k | -| #170 | `sync_registry.py` 周报 + `probe_registry.py` 月探活 + scheduled Action | 新增脚本 | -| #171(前半) | 27 个 base_url 分歧逐条 triage（修错的、note 有意的） | 数据 | -| **S1** | **桌面 `.a` 切 LTO-off profile**：v0.5.0 的 `libaimux_ffi-*.a` 达 117–139MB（fat-LTO bitcode，同 iOS 根因）；`ios-release` profile 改名 `staticlib-release` 复用于所有 `.a` 目标，Linux 实测 138.4→66.5MB | 体积 | -| **S2** | **体积门禁推广**：把 iOS 的 64MiB slice 守门推广到所有发布产物（桌面 `.a`、Android `.so`、`.node`、wheel），CI 输出体积报告 | 门禁 | -| **B1** | registry 行加 `protocol` 列（纯增量，RFC-0032 修正 1–7 已写入 issue） | +行 | -| **C2** | 40 个 FFI 构造器转 `provider()` 的转发 shim | 前置项 | - -B1 + C2 是本版本最重要的两项：它们解锁 #174 / #175 / #167 / #179 与 B4–B6， -纯增量零破坏，越早落地后续越顺。 - -版本语义：Rust 层 breaking（A2 删枚举、#185 换类型），binding wire 与 C ABI 不变。 - -### 0.7.0 —— 「protocol registry + auth」（主菜，目标 ~5-6 周） - -目标：provider 构造从代码变成数据，auth 从 12 处手写收敛为一处；顺带完成体积审计（S3，见 §6.1）。 - -| 项 | 内容 | -|---|---| -| B2→B9 | protocol registry 全量：17 个 LanguageModel 实现 → 7 个协议；33 个 wrapper 退役；responses 家族合并（注意 #166 修正 3：xai/mistral 非纯 fork，节流为 profile hooks；修正 6：五个 `MistralProvider::model()` 直连点先迁 `provider()`） | -| #174 | registry `auth{kind,env,header}` schema + `apply_auth()` 单点；`none` kind 退役 33 处 `PLACEHOLDER_API_KEY` | -| #175 | `Credential` 解析序（explicit → env → store）+ `CredentialStore` + 通用 `TokenRefresher`（codex_refresh 泛化；vertex 未装 refresher 时照旧抛 `TokenExpired`） | -| #171(后半) | 116 个缺失 provider 按 auth/protocol schema 一行一个补齐 + cassette | - -版本语义：Rust API 大 breaking（33 wrapper 退役）；C ABI 经 C2 转发不受影响。 - -0.7.0 期间体积跟进（S3）：`cargo-bloat` 审计 0.5.0 动态库增重来源（Android `.so` -13.4→21MB，+57%：jsonschema / rustls+webpki-roots(ws) / replay / repair 等新依赖）， -评估 per-modality 或 per-protocol feature gating 对 binding 包的收益——产出仅为 -**可选的 feature 组合与裁剪文档**，默认 feature 全量、对外 API 不变（§6.1 约束）。 -node workspace 默认全量的问题需一并解决。 - -### 0.8.0 —— 「FFI / binding 手术」（~4-5 周） - -| 项 | 内容 | -|---|---| -| C1→C3→C4 | 109 个 FFI 导出收敛为 9 个 JSON ops（recording/mock/session 走 `configure` op） | -| D1–D7 | 七语言 binding 按同一 ops 面重写（Kotlin 先行——纯 Java artifact；Node 先测 runtime 重入；Python 先做 ctypes 原型） | -| D8 | 类型镜像生成：serde 类型 → JSON Schema → 六语言，`gen_ts_types.py --check` 扩到全部输出 | - -版本语义：C ABI breaking，八个 binding 全量重发。 - -### 1.0 —— 「replay 完成 + API 冻结」锚点 - -| 项 | 内容 | -|---|---| -| #167 | transport-level replay：mock 挂在 HTTP 层跑真协议代码，覆盖全协议/全模态；删 OpenAI-only 解码器（~1.5k 行）；`ProviderRecord` = registry 行 + protocol；exchange schema 与 RFC-0003 cassette 统一；Router/MoA 记录实际 child；`PassthroughOnMiss` | -| #179 | `aimux-cli replay` 子命令（依赖 #167）；`online` mode 需先做设计决策（dump-on-signal / sidecar / FFI export，单独 RFC） | -| #181 / #180 | session partial-match 决策、debug CLI（并入 aimux-cli）、cache probe §10 验证项清尾 | -| — | 1.0 发布判据：#166 ledger 全勾 + 错误模型 #95 / 请求管线 #164 双稳定一个周期 | - -时机理由：错误模型（#158）、请求管线（#164）刚在 0.5.0 定型；#166 全量落地后 -API 面才真正定形，1.0 语义干净。粗估 3.5–5 个月后。 - -## 3. 贯穿原则（沿用 #166 ground rules） - -- **一个方向一个 PR**；providers 先于 bindings；最高确定性的删除先落。 -- **Cassettes 是字节级回归门禁**：2,799 份录音只增不减，后续 PR 依赖更重。 -- **文档重组而非删除**：`git mv` + 链接修复；`archive/` 只留 README 指向 git 历史。 -- **Scheduled registry 报告永不阻塞合并**（#170 验收条件）。 -- 语言规则：`docs/` 与 `bindings/*/README` 英文，`rfc/` 中文。 - -## 4. 近期第一步（本周可并行开） - -1. **A2–A5**：四个独立 PR，纯删码/归档。 -2. **#185**：先删 `StreamingToolCallTracker`（纯删），再 `ToolInput` 枚举（17 处机械替换）。 -3. **#170**：sync/probe 脚本 + Action，吸收两个 LiteLLM survey 脚本。 -4. **S1**：桌面 `.a` 切 staticlib profile——机制已在 iOS 修复（PR #196）中验证， - 改 profile 名 + `ffi-build` job 换 profile + S2 门禁，一个小 PR。 -5. **B1 + C2**：解锁项，RFC-0032 修正版按 issue 内 7 条修正执行。 - -## 5. 版本节奏预估 - -| 版本 | 主题 | 预估 | -|---|---|---| -| 0.6.0 | 收缩 + 解锁 + 体积止血 | ~3-4 周 | -| 0.7.0 | protocol registry + auth + 体积审计 | ~5-6 周 | -| 0.8.0 | FFI ops + bindings | ~4-5 周 | -| 1.0 | replay + 冻结 | ~2-3 周 | - -产出节奏参照 0.3.0→0.5.0（6 周 13 PR，含 3 个特大）；25 个 #166 PR -按 2-3 PR/周推进。各阶段允许交叠：A/E 轨与 B1/C2 无依赖可同批。 - -## 6. 横切需求 - -### 6.1 产物体积（binary-size budget） - -v0.5.0 现状与目标： - -| 产物 | v0.5.0 | 目标 | 手段 | -|---|---|---|---| -| 桌面 `.a` ×5 | 117–139 MB | ≤ 70 MB | S1：staticlib LTO-off profile（已验证 138.4→66.5MB） | -| iOS slice | ~40 MB/片 | ≤ 32 MB | 已落 strip+守门（#196）；S3 审计后视情况再压 | -| Android `.so` ×3 | 21 MB 合计 | 默认构建依赖瘦身回落；裁剪构建 ≤ 15 MB | S3：cargo-bloat 找增重；gating 仅作可选路径（§6.1 约束） | -| `.node` / wheel | 15–22 MB | 报告化 | S2 门禁先跟踪，S3 评估可选裁剪收益 | -| pub 包压缩 | 31.7 MB | ≤ 25 MB | 跟随 iOS/Android 改善（Flutter 包固定全量） | - -原则：体积是发布门禁不是事后优化——每个产物有预算线（S2），回归即 CI 失败， -与 iOS 的 64MiB 守门同机制。体积问题不新增单独版本，S1/S2 随 0.6.0，S3 随 0.7.0。 - -**约束：瘦身不改变对外 API。** 所有体积手段（profile、strip、gating）以默认 -构建的对外 API 面不变为前提：S1/S2 是构建管线变化，代码零改动；S3 的 feature -gating 若落地，只新增「可选的小体积构建路径」（按需关闭某模态/某协议的 -编译），默认 feature 集全量、binding 的完整 API 不变——凡需要删除或收窄 -公开 API 才能换到的体积收益，不在此需求范围内，需另立提案讨论。 - -### 6.2 协议与生态定期跟踪（ecosystem tracking） - -registry 数据层已由 #170 覆盖（weekly models.dev diff + monthly reachability）。 -协议行为层与上游演进在此扩展为固定节奏： - -| 周期 | 内容 | 产出 | -|---|---|---| -| 每周 | models.dev registry diff（#170） | 报告贴固定 issue，不阻塞合并 | -| 每月 | reachability probe（#170） | 同上 | -| 每月 | **上游参照系 diff**：Vercel AI SDK release notes + pi-ai 变更，标注 aimux 未跟进的能力 | 差异清单贴 tracking issue，超出 2 个版本未跟进的项升 issue | -| 每季度 | **协议新鲜度审计**：对照各 provider 官方 changelog（OpenAI Responses 演进、Anthropic thinking/computer-use 参数、Gemini API 版本等），过时 cassette 标记 | 审计报告 + 需更新的协议转换 issue | -| 每季度 | **新机制评估**：新模态/新协议特性（MCP、computer use、audio output…）→ 开 DRAFT RFC 或明确记录不做 | RFC 决策记录 | - -落地方式：扩展 #170 的 scheduled Action 为三条流水（registry-diff / probe / -upstream-diff），quarterly 审计人工触发。#167（transport replay）落地后， -「重新录制真实 provider cassette」可脚本化，协议新鲜度从文档对照升级为 -字节级验证——这是把 #167 排在 1.0 前的另一个理由。 - -关联：#95（错误体系参照 AI SDK）是此节奏在错误域的常设形式；#171 的 triage -是 registry 数据层的一次性清偿。 -