[13/13] docs: add the native-Rust porting skills

.agents/native-rust/PROFILE.md

@@ -0,0 +1,85 @@
+# aimux 配置（native-rust profile）
+
+`ts-rust-port` 和 `rust-native-rewrite` 共用。只写不看仓库就不知道、又不会很快过期的事：不写行号、提交号和待办清单，那些放 issue 和 PR。
+
+## 上游和映射
+
+- vercel/ai monorepo；锁定版本以 `fixtures/aisdk/VERSIONS.json` 为准，不在里面的包用 `docs/aisdk-architecture-alignment.md` 头部的版本，再没有就先问。
+- 源码：`https://raw.githubusercontent.com/vercel/ai/<URL 编码的 包名@版本>/packages/<目录>/src/<文件>`；测试是同目录的 `*.test.ts`。
+
+| 上游 | aimux |
+|---|---|
+| `ai` | `aimux-core/src`（如 `json_repair.rs` ← `util/fix-json.ts` + `parse-partial-json.ts`） |
+| `@ai-sdk/provider` | `aimux-core/src` 的 V4 类型 |
+| `@ai-sdk/provider-utils` | `aimux-provider-utils/src`，kebab → snake |
+| `@ai-sdk/<vendor>` | `aimux-providers/src/<vendor>/`；`google-vertex` → `vertex/`，`amazon-bedrock` → `bedrock/`；按模块头注释的 `packages/<pkg>/src/<file>.ts` 找 |
+| 无上游 | `aimux-ffi`、`bindings/`、`recording.rs`/`replay.rs`、`decision_*`：只能新旧差分 |
+
+OpenAI-compatible preset 来自 `provider_registry.json` 的运行时 descriptor 表（D12），没有逐厂商代码。
+
+## 设计文档
+
+`docs/aisdk-architecture-alignment.md`：决策记录 D1–D31，§0.4–0.5，§5（定下来的不像 Rust 的写法），§9.2–9.3（构建检查、行为验收）。碰到消息类型或 wire 再读第二部分。
+
+## 不能动的面
+
+| 面 | 守护 |
+|---|---|
+| 公开 JSON：camelCase、kebab-case `type`、base64 字节、缺失省略、null 保留 | 绑定测试、`cargo test --workspace` |
+| ts-rs 生成的 d.ts（不新增 `#[derive(TS)]`，要退役） | `python3 scripts/gen_ts_types.py --check` |
+| C ABI（`aimux-ffi`，各语言绑定依赖） | `aimux-ffi/tests`、`scripts/local-ci.sh` |
+| Node 绑定 | 构建后 `git diff --exit-code -- bindings/node/index.js bindings/node/index.d.ts` |
+| 录制格式、cassette 回放 | 回放测试 |
+| 错误 JSON（AI SDK 的 `name` 标签） | 原生化不改 |
+| `docs/api/providers.md` | `python3 scripts/gen_providers_doc.py --check` |
+
+## 预言机
+
+1. 上游录制：`fixtures/aisdk/<pkg>/*.json`，`aimux-providers/tests/*_factory_test.rs` 回放（URL、headers、body、结果、流事件、错误分类）。
+2. 搬来的上游单元测试，例如 `aimux-core/tests/util_test.rs` 的 fix-json 用例。
+3. node 跑锁定版本上游（Node 22 `--experimental-strip-types`），读写 JSONL。
+4. cassette 回放：`aimux-providers/tests/cassettes/`，不联网。
+5. 新旧差分只在改动期间存在；入库的是它记下的结果（例：`aimux-core/tests/fixtures/json_repair_cases.jsonl`），不是旧实现。跨构建差分的探针不入库，PR 描述写位置和命令。进程级计数器（`source-{n}` 之类）比较前归一化。
+
+## 检查（CI 对每个 PR 跑）
+
+```sh
+cargo fmt --all -- --check
+cargo clippy --workspace --all-targets -- -D warnings
+RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps
+cargo test --workspace        # 会改写 bindings/node/src/types/*.ts，跑完 checkout 回去
+python3 scripts/gen_ts_types.py --check
+python3 scripts/gen_providers_doc.py --check
+bash scripts/check_provider_boundaries.sh
+```
+
+碰到 napi、FFI 时加跑 `scripts/local-ci.sh` 对应的节。每个 worktree 用自己的 `CARGO_TARGET_DIR`。
+
+## 项目决定
+
+- wire 跟 AI SDK 的 JSON 形态；wire 变化单独成 PR，同步所有绑定。
+- 可选方法用 `Option<Result<…>>`（§5、D22）；provider 可调用 `call(model_id)`；默认 provider 访问不可失败，显式工厂返回 `Result`。
+- 设置求值时机（工厂、取模型、请求）逐包跟上游（D10）；headers 每次请求求值。
+- 不用 provider 名字判断厂商（D8）；providerOptions 的键在各包 `options.rs` 只写一次（D9）；retry 只在调用层（D14）；core 单步，不跑 agent loop（D25）。
+- `do_generate`/`do_stream` 保持 `async_trait`（registry、FFI 要 `dyn`）。
+- 分层单向：`shared/`、`openai_compatible/` 不引用具体厂商模块。跨模块扩展点由共享层定义 trait，厂商用自己的纯数据 struct 实现；包内有限几种情况用包内 enum（`check_provider_boundaries.sh` 守）。
+- 流：每个厂商的流是一个实现 `Transformer` 的具名 struct；工具调用的累积是流 struct 自己的字段，没有共享的 tracker 类型（和上游 provider-utils 结构不同，行为照上游）。
+- 保留 openai-compatible 的 `transformRequestBody`、`metadataExtractor`、`supportsMultiPartToolContent` 和 `specification_version`。
+- 栈内 breaking 直接替换，不留 deprecated 别名，同一 PR 改完调用方和绑定（D31）。
+- 范围只做结构清理、行为对齐和缺陷修复，不新增对外能力（§0.4）。
+
+## 陷阱
+
+- 数字：上游是 JS number，用量、价格、max_tokens 用整数解析；写回 JSON 的 `f64` 会把 `12` 变成 `12.0`，加 golden 测试。
+- null 和缺失：上游区分，`Option` + `skip_serializing_if` 会合并；wire DTO 保留 null。
+- SSE 和 event-stream 可以在任意字节切开；重写分帧时用同一字节流的所有切法差分。
+- headers：settings → 单次调用 → 鉴权，后层覆盖；`None` 删除；名字小写。
+- JS promise 创建就跑，Rust future 不 poll 不跑；不 await 的 promise 移植时改成 spawn 或删掉。
+- UTF-16：JS 的长度和下标按码元；截断、长度校验用 emoji 和中文对一次上游。
+
+## 工作约束
+
+- 每个 PR 一个方向：一个模块或一种模式。标题 `[n/m] refactor: …`，分支名和标题一致，开 PR 前定好。
+- 不改写别人已推送的分支；PR 先 Draft，CI 绿了再 Ready。
+- 生产代码不新增 `unwrap`/`expect`/`panic`（§9.2）；凭据类型的 `Debug` 脱敏。
+- 参照库：rig（`0xPlaygrounds/rig`）、async-openai（`64bit/async-openai`）。

.agents/native-rust/README.md

@@ -0,0 +1,8 @@
+# Agent notes for native-Rust work
+
+For coding agents (and people) doing two kinds of work on aimux:
+
+- aligning a Rust module with its pinned AI SDK upstream: `../skills/ts-rust-port/SKILL.md`;
+- rewriting TS-shaped Rust into native Rust without changing behaviour: `../skills/rust-native-rewrite/SKILL.md`.
+
+`PROFILE.md` holds the repository facts both read. Nothing here is built or run by CI. The skills and profile are written in Chinese.

.agents/skills/rust-native-rewrite/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: rust-native-rewrite
+description: Rewrite TS-shaped Rust into native Rust within one repo, keeping behaviour and wire format, proven by an old-vs-new differential (in-process for one module, cross-build for a cross-cutting refactor).
+---
+
+# 把 TS 味的 Rust 改成原生 Rust
+
+单仓库，不需要上游源码；行为由新旧差分证明。要和上游本身对比，用 `ts-rust-port`。
+仓库事实在 `.agents/native-rust/PROFILE.md`（下称配置）；本文只写流程、纪律和写法对照。
+
+用法：给一个文件或模块；或 `pattern <模式>`（跨模块，如“回调改成 trait”）；或 `review [ref]`（只审查）。
+
+## 纪律
+
+1. 只改结构，不改行为；看到的 bug 记下来，另开 PR。
+2. 一个 PR 一种模式或一个模块。配置“项目决定”里的写法不改。
+3. 动手前在基线上跑一遍配置的检查，记下每个测试二进制的通过数；改完逐个比，多出来的只能是新测试，改过的已有测试逐个说明。
+4. 差分报告写分母和覆盖面：“比较 N 个，M 处差异；没比的是 X，因为 Y”。失败一次修一个，到 0 为止；0 之后做变异检查。
+5. 先测稳定性：同一构建跑两次，会变的值（计数器、UUID、时间、签名）先屏蔽。
+6. 改完要比原来短或一样长。为了“原生”多出来的样板（字段写两遍、套一层通用框架）不算改进。
+7. 去掉闭包时不能颠倒依赖：共享层不为了一个闭合 enum 去 import 具体模块；跨模块扩展点用共享层的 trait，具体模块用纯数据 struct 实现。
+8. 跑完看 `git status`；临时拷进去的探针和生成器改写的文件不进提交。不自动推送。
+
+## 流程
+
+1. **选目标**：对目标跑下面的痕迹扫描，剔除“项目决定”和“不能动的面”挡住的；剩下为空就报告并停下。目标没有测试先补测试，单独提交。
+2. **契约**（commit body 或 PR 描述）：改哪些、不能变什么、允许的差异、怎么测、是否 breaking。只有要 breaking、要动“不能动的面”或违背“项目决定”时先等用户回复。
+3. **差分**：
+   - 一个模块、纯函数或状态机：进程内差分。改动期间把旧实现复制进测试，随机生成器默认 2 万、可放大到 10^6；到 0 后，把有代表性的输入和旧实现的结果录成 fixture 入库，删掉旧实现副本。
+   - 跨很多文件（配置、流、请求构造）：跨构建差分。新旧两个 worktree 各用自己的 target；同一个探针测试文件放两边，在最底层传输（`fetch`）注入一个按录制回答、记录请求的传输，加一个死代理防联网；每个操作一行 JSONL，脚本逐 key 比较。探针不入库，PR 描述写位置和命令。
+4. **实现**：先把新 API 的调用写成 doc test，再按写法对照改。公开名字不变，除非契约允许 breaking。
+5. **审查**（子 agent，有“本次引入”的问题就回第 4 步）：
+   - BEHAVIOUR：输出、错误、边界情况和旧实现一致。
+   - WIRE：“不能动的面”没变。
+   - DECISION：没违背“项目决定”和工作约束；没顺手修 bug。
+   - LAYERING：没有新增 `shared → 具体模块` 之类的反向依赖。
+   - SIZE：行数没有无故增加；没有为编译而加的 clone/unwrap。
+   - ORACLE：差分可复现，数字带分母；变异检查做了。
+   - SECURITY：Debug 不打印密钥；读环境变量不 panic。
+6. **提交和汇报**：`refactor(<crate>)[!]: …`，body 写契约、差分 N/M、变异检查。PR 描述最后放一张 Verification 表：基线和改后测试数、测试改动、差分、变异检查、各项检查。
+
+## 写法对照
+
+| TS 形状 | 原生写法 |
+|---|---|
+| 一个 `kind`/`role`/`state` 字段，其余字段随它变 | enum，每个变体带自己的数据 |
+| 几个 `bool` 组成的状态；`finished` 标志 | enum 变体；终结操作取 `self` |
+| `-1`、空字符串哨兵；`isize` 下标；`Vec<char>` 扫描 | `Option`、`usize`、`char_indices()` |
+| 和字符串字面量比较的 `kind: String` | enum + serde rename |
+| `extra: Value`、`.get("x")` | 有类型字段；开放部分用 `#[serde(flatten)]` |
+| `Option<Vec<_>>`，缺失和空无区别 | `Vec` + `Default` |
+| `expect("never empty")` 维持的不变量 | 让非法状态构造不出来 |
+| options 里的 `Box<dyn Fn>` 钩子 | trait + 给闭包的 blanket impl，`new(closure)` 照常能用 |
+| 包内有限几种配置闭包（`url()`、`headers()`） | 包内纯数据 enum，请求时求值 |
+| 共享层给各具体模块开的扩展点 | 共享层的 trait，具体模块的纯数据 struct 实现 |
+| `new TransformStream({ start, transform, flush })`、靠一堆局部变量维持的流状态 | 实现 `Transformer` 的具名 struct；只读上下文和 `#[derive(Default)]` 的累积状态分开；同步驱动入口方便无 I/O 单测 |
+| 外面套一个通用的 tracker/accumulator 对象 | 状态直接作为使用者 struct 的字段，逻辑是它的私有方法 |
+| 把 `Transformer` 接到流上的 `async_stream!` + 每帧新 `Vec` | 直接实现 `futures::Stream` 的 struct，复用一个 `VecDeque` |
+| 每次调用返回新 `Vec` | 写进调用方给的 `&mut Vec` |
+| 小集合配 `HashMap` 索引 | `Vec` 线性扫描 |
+| `createX(settings)`，settings 全 `Option` | `X::new(必填)` + consuming setter |
+| `Result<_, ()>`、`Other(String)` 错误 | `thiserror` enum，`#[from]` 保留 source |
+| 只有一个实现的 trait | struct |
+| 插入顺序有意义却用 `HashMap` | `IndexMap` |
+| 凭据类型 `derive(Debug)` | 手写脱敏 `Debug` |
+
+## 痕迹扫描
+
+```sh
+P=path/to/module.rs   # 只扫目标
+rg -n '\w+: bool\b|let mut \w+ = (true|false);|isize|-1\b|Vec<char>' "$P"
+rg -n '\.expect\(|\.unwrap\(|unreachable!|panic!' "$P"
+rg -n 'Option<(Vec|HashMap)<|(type|kind|role)\w*: (String|&str)|== "\w+"' "$P"
+rg -n 'pub \w+: (serde_json::)?Value|as_object\(\)|\.get\("|#\[serde\(untagged\)\]|Other\(String\)' "$P"
+rg -n '(Box|Arc)<dyn Fn|pub fn create_\w+\(|pub stream:|AbortSignal|: Option<f64>' "$P"
+rg -n 'use crate::(vertex|bedrock|google|anthropic|openai|aws_polly)' aimux-providers/src/shared   # 反向依赖
+```
+
+rig（`0xPlaygrounds/rig`）里可对照的：按角色的消息 enum（`completion/message.rs`）、请求 `new` + setter + `#[non_exhaustive]`（`completion/request.rs`）、纯数据 provider 配置和 `Secret`（`providers/openai/wire.rs`）、流的 `finish(self)`（`streaming/mod.rs`）、钩子 trait（`agent/hook.rs`）。

.agents/skills/ts-rust-port/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: ts-rust-port
+description: Port a TypeScript module to Rust, fix one place where a Rust port disagrees with its pinned TS upstream, or check a Rust module against that upstream, using upstream tests, recorded fixtures and running upstream TS.
+---
+
+# TS 上游和它的 Rust 移植
+
+两个仓库：锁定版本的 TS 上游和 Rust 仓库，目标是 Rust 的行为和上游一致。把移植来的代码改成原生写法是另一件事，用 `rust-native-rewrite`。
+仓库事实在 `.agents/native-rust/PROFILE.md`（下称配置）。
+
+| 用法 | 做什么 |
+|---|---|
+| 上游文件，或还没移植的模块 | 移植 |
+| `fix <一处不一致>` | 把一处行为改成和上游一样（最常见） |
+| `parity <Rust 模块>` | 和上游对比，只报告 |
+| `review [ref]` | 只审查 |
+
+## 纪律
+
+1. 移植时结构跟上游走（文件、类型、函数一一对应），不改进、不修 bug；已经移植过的代码只走 `fix` 或 `parity`。
+2. 说“上游是这样”要给锁定版本的文件和行号。
+3. 上游测试逐个用例搬，只改 harness，不改场景。
+4. 报告写分母：“比较 N 个，M 处差异”。失败一次修一个，到 0 为止。
+5. 上游源码下载到新的空目录，当数据用：路径作参数传给 node，不在那个目录里执行东西。
+6. 配置“项目决定”里和上游刻意不同的地方，不改回上游。
+7. 不自动推送。
+
+## fix
+
+1. 找到锁定版本的上游文件和行号；在“项目决定”里的就不改，报告并停下。
+2. 先写一个在当前代码上失败的测试：优先回放上游录制的 fixture，其次搬上游用例，再其次用 node 跑上游拿期望值。
+3. 改到通过，只改这一处；顺带看到的其他差异记下来。
+4. 跑配置的检查，基线和改后逐个测试二进制比。
+5. 提交 `fix(<crate>): <行为> matches <包>@<版本>`，body 写上游出处、改前改后、新测试名。同一层的几条可以同一个 PR，每条一个提交。
+
+## 移植
+
+1. 用配置的映射把目标解析成“Rust 文件 + 上游文件 + 版本”；查清碰到哪些“不能动的面”和“项目决定”。
+2. 契约：上游文件和版本、不能变的、允许的差异、怎么测、是否 breaking。只有要 breaking 或违背配置时先等用户回复。
+3. 实现（子 agent）：按上游结构写，只在所有权模型要求时偏离；上游测试逐个搬；循环到 0 失败；再做一次对比上游。常见失败：缺 match 分支、迭代顺序、null 和缺失混同、数字类型、UTF-16 下标、JSON 键顺序、错误文本。
+4. 审查（子 agent，循环）：对每个改动的文件读完对应的上游文件，查 FIDELITY（数据流、边界、错误分类和上游一致）、WIRE、DECISION、ORACLE（用例搬全、引用带版本行号）、ERROR（错误名和消息保留，不新增 panic）、SCOPE。
+5. 提交 `feat(<crate>): port <upstream file>`，body 写搬了多少用例、对比上游的 N/M。
+
+## 对比上游
+
+按能用的顺序：上游录制的 fixture 回放；node 跑锁定版本上游、读同一份 JSONL 语料逐条比；搬来的上游测试（最弱）。
+语料覆盖空输入、截断、乱序、重复、深嵌套、错误路径、非 ASCII 和辅助平面字符，以及配置“陷阱”里的每一项。每类差异给一个最小复现，标明是已知的还是新发现的。runner 不入库，commit body 写位置和命令。

CONTRIBUTING.md

@@ -15,12 +15,19 @@ aimux/
 ├── bindings/              # Node, Python, Swift, Kotlin, Flutter, Go, C — share one Rust core
 ├── rfc/                   # Design docs (RFCs)
 ├── docs/                  # Public product docs (see docs/README.md)
+├── .agents/               # Skills for coding agents (see below)
 └── scripts/               # Code-generation and maintenance scripts
 ```
 
 `docs/internal/` contains historical research and audit notes; it is not part
 of the public surface and generally does not need changes.
 
+`.agents/` holds skills for coding agents and their maintainers (porting from
+the AI SDK, native-Rust rewrites) and the PROFILE of repository facts they share
+(`.agents/native-rust/PROFILE.md`). The skills and profile are written in
+Chinese, like the recent RFCs. They hold only what stays true, and change in
+the same PR as the code they describe.
+
 ## Prerequisites
 
 - **Rust**: stable toolchain (see `rust-toolchain.toml`). The workspace targets