@zhushanwen/pi-provider-live-sync 0.2.0

package/README.md

@@ -0,0 +1,40 @@
+# @zhushanwen/pi-provider-live-sync
+
+让**运行中**的 pi 进程实时看到 provider / 模型 / 凭据的配置变更。
+
+## 解决的问题
+
+pi 的可用模型集合在**进程启动时**冻结：`set_model` 从内存快照 `getAvailableSnapshot()` 解析，
+而 pi 自身没有文件 watcher、也没有 refresh RPC。于是「会话开着 → 在设置页新增 provider/模型/凭据 →
+直接切到新模型」会失败并报 `Model not found`（缺凭据与缺模型是同一句文案），只能重开会话。
+
+## 机制
+
+- 每 **2 秒**读一次 `<agentDir>/models.json` 与 `<agentDir>/auth.json`（`getAgentDir()` 解析，
+  尊重 `PI_CODING_AGENT_DIR`），按**字节内容**比较；
+- 内容变化（或文件从无到有）→ 调 `ctx.modelRegistry.refresh({ allowNetwork: false })`：
+  pi 的 `ModelRuntime.refresh()` 首行重读磁盘配置并重组 provider，`allowNetwork:false` 保证
+  **零网络请求**（本地恢复相位，凭据解析/入网前返回）；
+- 刷新后读 `ctx.modelRegistry.getError()`：非空即原样落 ERROR 日志（模型配置被引擎拒绝的
+  唯一有效判据——该退化形态下 `refresh().errors` 为空）。
+
+## 语义要点（易误解处）
+
+| 情形 | 行为 |
+|------|------|
+| `models.json` **一直不存在**（catalog-only 安装的常态） | 视为**非变化信号**，不阻断 `auth.json` 的比较与刷新 |
+| 文件**曾存在、现在缺失**（被隔离/外部删除） | 更新基线但**抑制刷新**（避免用空配置重建可用集合），只记一行日志 |
+| 读失败（权限等非 ENOENT） | 该文件本拍不比较、基线不动；另一文件照常 |
+| 刷新抛错 | 基线照常推进（同一内容不重复刷新），下一拍继续 |
+
+## 安装
+
+作为 taiji 内置扩展随应用打包（`mandatory-extensions.json` 中 tier=infrastructure）。
+独立 pi 用户亦可安装：`pi install @zhushanwen/pi-provider-live-sync`。
+
+## 排障
+
+- 日志前缀 `[provider-live-sync]`：`config change detected (...)` 表示检测到变更并已刷新；
+  `model config rejected by the engine: ...` 表示 pi 拒绝了配置文件（原文含字段路径）；
+  `config file disappeared: ...` 表示文件被隔离/删除（此拍不刷新，引擎保留上一份快照）。
+- 配置无轮询开关：周期为设计标定值（2s）。

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.ts";

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@zhushanwen/pi-provider-live-sync",
+  "version": "0.2.0",
+  "description": "Keep the running pi process's model snapshot in sync with on-disk provider/model/credential config changes.",
+  "type": "module",
+  "main": "index.ts",
+  "taiji": {
+    "role": "universal"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "keywords": [
+    "pi-package",
+    "extension",
+    "provider",
+    "model",
+    "refresh"
+  ],
+  "license": "MIT",
+  "files": [
+    "src/",
+    "index.ts",
+    "skills/"
+  ],
+  "dependencies": {
+    "@zhushanwen/pi-extension-logger": "0.6.1"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.9",
+    "vitest": "^4.1.8"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.4"
+  },
+  "scripts": {
+    "typecheck": "npx tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/skills/provider-live-sync-ext-config/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: provider-live-sync-ext-config
+description: 使用或排查 @zhushanwen/pi-provider-live-sync（运行中 pi 的模型快照实时同步）时加载。说明它为何存在（pi 快照冻结在 spawn 时刻）、轮询语义（2s / 内容比较 / 按文件独立基线）、四态规则（缺失常态 / 曾存在→缺失抑制 / 读失败跳过 / 变化触发）、零网络保证、错误可见性（getError 全文）、日志与排障、无配置项的原因。触发词：provider 不刷新、新加模型切不过去、Model not found、模型快照、provider-live-sync、配置变更不生效、refresh 模型、扩展刷新。
+---
+
+# provider-live-sync 扩展说明
+
+## 它解决什么
+
+pi 的可用模型集合在**进程启动时**冻结：`set_model` 从内存快照 `getAvailableSnapshot()` 解析，
+pi 自身没有文件 watcher、也没有 refresh RPC。因此「会话开着 → 在设置页新增 provider / 模型 / 凭据
+→ 直接切到新模型」会失败，报 `Model not found`（缺凭据与缺模型是同一句文案），只能重开会话。
+
+本扩展把「配置变更 → 引擎重读」变成常态路径：每 2 秒比对 `<agentDir>/models.json` 与
+`<agentDir>/auth.json` 的**字节内容**，有变化就调 pi 自己的
+`ctx.modelRegistry.refresh({ allowNetwork: false })`。pi 的 `ModelRuntime.refresh()` 首行会重读磁盘
+配置并重组 provider，所以新增 / 删除 provider、模型、凭据都会立即对运行中的会话生效。
+
+## 无配置项（有意）
+
+轮询周期 2s 是设计标定值：它是「内容变更 → 生效」的上界，且小于「保存 → 切回会话 → 打开 popover
+→ 点选」的人工时延。没有开关、没有阈值、没有排除列表——本扩展**只做一件事**，任何配置面都会扩大
+「配置错了就不生效」的故障面。需要改周期请改包内常量并同步设计文档。
+
+## 语义要点（排障时先看这张表）
+
+| 观察到的情况 | 行为 | 为什么 |
+|---|---|---|
+| `models.json` **一直不存在**（catalog-only 安装的常态） | 视为**非变化信号**，不影响 `auth.json` 的比较 | 缺失是合法常态；若当作异常会整体关停同步能力 |
+| 文件**曾存在、现在缺失**（被隔离 / 外部删除） | 更新基线但**抑制刷新**，且抑制**持续到该文件被写回**；只在跃迁那一拍记一行日志 | refresh 会以「无 override 的空配置」重建可用集合 = 把一次坏写放大成自定义 provider 的真正丢失；抑制期间引擎保留最后一份好快照 |
+| `auth.json` 消失 | 按**普通变化**处理（触发刷新） | 凭据缺失是自愈的（写回即恢复），且不威胁 provider 配置本身 |
+| 读失败（权限等非 ENOENT） | 该文件本拍不比较、基线不动；另一文件照常 | 无法区分「读不到」与「不存在」时，不动基线避免误触发 |
+| 刷新抛错 | 基线照常推进（同一内容不重复刷新），下一拍继续 | 否则同一坏内容会每拍刷新 + 每拍报错（日志风暴） |
+| 半写文件（截断的内容） | 视为内容变化 → 刷新一次；完整内容到达后再刷一次 | 唯一非原子写方是 pi 对 auth.json 的原地写；瞬时收缩下一拍自愈 |
+
+**零网络**：`allowNetwork: false` 让 pi 只跑本地恢复相位，在任何凭据解析 / 入网前返回。
+
+## 日志与排障
+
+日志走 `@zhushanwen/pi-extension-logger`（前缀 `[provider-live-sync]`，不写 pi 不捕获的 stderr）：
+
+- **error 行**（下表除首行外）→ session JSONL 的 `provider-live-sync:log` custom entry（持久化、
+  不进 LLM 上下文，重开会话可 grep）+ `TAIJI_AGENT_DEBUG=1` / `TAIJI_AGENT_EXT_LOG=1` 时落
+  `<agentDir>/logs/provider-live-sync-YYYY-MM-DD.log`；
+- **debug 行**（`config change detected`）→ 仅上述文件日志（裸 pi 默认 no-op；taiji 托管环境
+  runtime 恒注入 `TAIJI_AGENT_EXT_LOG=1`，INFO 级落盘）。
+
+| 日志 | 含义 |
+|---|---|
+| `config change detected (models.json, auth.json) → refreshing model snapshot` | 检测到变更并已刷新 |
+| `model config rejected by the engine (models.json / auth.json): <pi 原文>` | pi 拒绝了配置（含解析失败与 schema 非法的字段路径）。**这是坏配置的唯一机器证据**——该形态下 `refresh()` 返回的 `errors` 为空，只有 `getError()` 有内容 |
+| `config file disappeared: models.json — refresh suppressed until it is written again` | 文件被隔离 / 删除，进入持续抑制窗口 |
+| `refresh finished with errors (aborted=…, providers=N)` | 通用加固记录（网络 / 凭据 / 取消类；**不是**坏配置判据） |
+| `tick failed: …` | 本拍异常（下拍继续，不影响 pi） |
+
+常见问题：
+
+- **切换新加的模型仍报 `Model not found`**：先在文件日志看有没有 `config change detected` 行。
+  没有 → 配置写入的不是该会话所用的目录（检查 `PI_CODING_AGENT_DIR` / 数据目录），或裸 pi
+  形态下 debug 日志默认 no-op（用 `TAIJI_AGENT_DEBUG=1` 重启复现）；
+  有 → 再看 session JSONL 里 `model config rejected by the engine` 行（那是 pi 的原话）。
+- **日志出现 `Invalid models.json schema: - <字段路径>`**：配置文件里有 pi 不接受的内容
+  （如模型缺 `id`、`baseUrl` 为空串）。按字段路径修正后保存，扩展会自动恢复（≤2s）。
+- **`config file disappeared` 之后模型列表变少**：这是抑制窗口内的预期形态（引擎保留最后一份
+  好快照）；把 `models.json` 写正后下一拍自动恢复，重启会话同样可恢复。
+
+## 相关
+
+- 设计依据：模型切换与运行中 provider 变更的实时可见性（技术设计文档 §3.3 D3/D11/D12）。
+- pi 语义锚点：`ModelRuntime.refresh()` 重读磁盘（`dist/core/model-runtime.js:501-513`）、
+  `getError()` 合成（`:305-317`）、pi-ai 本地相位提前返回（`dist/models.js:153-158`）；
+  登记于 `docs/pi-semantics.json`，受 C-proc-08 版本门禁约束。

package/src/__tests__/model-sync.test.ts

@@ -0,0 +1,329 @@
+/**
+ * provider-live-sync 单元测试（设计 §4.2「单元（extension）」全部断言）。
+ *
+ * 被测面 = 纯函数（`readObservation` / `evaluateSnapshot`），不依赖 pi 运行时：
+ * 决策与基线推进是全部语义所在，时钟/timer 不进断言（timer 只做调度）。
+ *
+ * 覆盖映射（设计行 → 用例）：
+ * - 内容变化 → refresh；内容相同 → 零 refresh
+ * - auth.json 单独变化仍触发（两文件独立比较）
+ * - D3 四态：① 持续缺失（catalog-only 常态）+ 另一文件变化仍触发；② 曾存在→缺失 → 不 refresh；
+ *   ③ 非 ENOENT 读失败只跳过该文件；④ 不存在→存在 → refresh
+ * - 基线推进：同一坏内容连续 N 拍 → 决策 refresh 恰 1 次（不重复）
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, chmodSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import providerLiveSync, {
+  evaluateSnapshot,
+  readObservation,
+  POLL_INTERVAL_MS,
+  WATCHED_FILES,
+  type FileObservation,
+  type Snapshot,
+  type WatchedFile,
+} from '../index.ts'
+
+// tick 层用例：mock pi 宿主模块的 getAgentDir 指向真实 tmp fixture。纯函数用例不经
+// getAgentDir（readObservation 显式传目录），mock 对它们无影响。
+const piMocks = vi.hoisted(() => ({ agentDir: '' }))
+
+vi.mock('@earendil-works/pi-coding-agent', () => ({
+  getAgentDir: () => piMocks.agentDir,
+}))
+
+function makeSnapshot(): Snapshot {
+  return { baselines: new Map(), initialized: false, suppressed: new Set() }
+}
+
+function obs(entries: Partial<Record<WatchedFile, FileObservation>>): Map<WatchedFile, FileObservation> {
+  const m = new Map<WatchedFile, FileObservation>()
+  for (const file of WATCHED_FILES) {
+    m.set(file, entries[file] ?? { state: 'absent' })
+  }
+  return m
+}
+
+const present = (content: string): FileObservation => ({ state: 'present', content })
+
+describe('evaluateSnapshot —— 变更检测（内容比较 + 按文件独立基线）', () => {
+  it('首拍（无基线）建立基线并触发 refresh；内容相同 → 后续拍零 refresh', () => {
+    const snap = makeSnapshot()
+    const first = evaluateSnapshot(snap, obs({ 'models.json': present('{"providers":{}}') }))
+    expect(first).toMatchObject({ action: 'refresh', changedFiles: ['models.json'] })
+
+    const second = evaluateSnapshot(snap, obs({ 'models.json': present('{"providers":{}}') }))
+    expect(second).toEqual({ action: 'none', reason: 'unchanged' })
+  })
+
+  it('内容变化 → refresh（且只列变化的文件）', () => {
+    const snap = makeSnapshot()
+    evaluateSnapshot(snap, obs({ 'models.json': present('A'), 'auth.json': present('X') }))
+    const d = evaluateSnapshot(snap, obs({ 'models.json': present('B'), 'auth.json': present('X') }))
+    expect(d).toMatchObject({ action: 'refresh', changedFiles: ['models.json'] })
+  })
+
+  it('auth.json 单独变化（凭据类变更）→ 仍触发 refresh', () => {
+    const snap = makeSnapshot()
+    evaluateSnapshot(snap, obs({ 'models.json': present('A'), 'auth.json': present('X') }))
+    const d = evaluateSnapshot(snap, obs({ 'models.json': present('A'), 'auth.json': present('Y') }))
+    expect(d).toMatchObject({ action: 'refresh', changedFiles: ['auth.json'] })
+  })
+
+  it('半写内容（截断 JSON）也是「内容变化」→ 触发 refresh；下一拍完整内容到达 → 再刷一次', () => {
+    const snap = makeSnapshot()
+    evaluateSnapshot(snap, obs({ 'auth.json': present('{"kimi":{"apiKey":"sk-1"}}') }))
+    const truncated = evaluateSnapshot(snap, obs({ 'auth.json': present('{"kimi":{"apiK') }))
+    expect(truncated).toMatchObject({ action: 'refresh', changedFiles: ['auth.json'] })
+    const healed = evaluateSnapshot(snap, obs({ 'auth.json': present('{"kimi":{"apiKey":"sk-1"}}') }))
+    expect(healed).toMatchObject({ action: 'refresh', changedFiles: ['auth.json'] })
+  })
+
+  it('基线推进与成败无关：同一坏内容连续 N 拍 → refresh 恰 1 次（不重复、无日志风暴）', () => {
+    const snap = makeSnapshot()
+    let refreshes = 0
+    const bad = present('{ not json')
+    for (let i = 0; i < 5; i += 1) {
+      const d = evaluateSnapshot(snap, obs({ 'models.json': bad }))
+      if (d.action === 'refresh') refreshes += 1
+    }
+    expect(refreshes).toBe(1)
+  })
+})
+
+describe('evaluateSnapshot —— D3 四态（models.json 缺失是 catalog-only 常态）', () => {
+  it('① 持续缺失 + auth.json 变化 → 仍触发 refresh（缺失不阻断另一文件）', () => {
+    const snap = makeSnapshot()
+    // 首拍：models.json 不存在（catalog-only 安装常态），auth.json 在场
+    const first = evaluateSnapshot(snap, obs({ 'auth.json': present('X') }))
+    expect(first).toMatchObject({ action: 'refresh', changedFiles: ['auth.json'] })
+    // 第二拍：models.json 仍缺失，auth.json 变化 → 仍要刷新（旧「两文件都成功才比较」规则会失效）
+    const second = evaluateSnapshot(snap, obs({ 'auth.json': present('Y') }))
+    expect(second).toMatchObject({ action: 'refresh', changedFiles: ['auth.json'] })
+  })
+
+  it('② 曾存在 → 缺失 → skip-missing（抑制 refresh，防空配置重建可用集合）', () => {
+    const snap = makeSnapshot()
+    evaluateSnapshot(snap, obs({ 'models.json': present('A'), 'auth.json': present('X') }))
+    const d = evaluateSnapshot(snap, obs({ 'models.json': { state: 'absent' }, 'auth.json': present('X') }))
+    expect(d).toEqual({ action: 'skip-missing', missingFiles: ['models.json'] })
+    // 持续缺失：抑制保持（每拍仍判定 skip-missing），但调用方按跃迁去重 → 只在第一拍记一行
+    // 日志（`missingLogged`），后续拍零输出（稳态无噪声，设计 §3.6 行 2/S9a②）。
+    const d2 = evaluateSnapshot(snap, obs({ 'models.json': { state: 'absent' }, 'auth.json': present('X') }))
+    expect(d2).toEqual({ action: 'skip-missing', missingFiles: ['models.json'] })
+  })
+
+  it('②变体1：曾存在 → 缺失 + 另一文件同时变化 → 抑制优先（本拍不刷新）', () => {
+    const snap = makeSnapshot()
+    evaluateSnapshot(snap, obs({ 'models.json': present('A'), 'auth.json': present('X') }))
+    const d = evaluateSnapshot(snap, obs({ 'models.json': { state: 'absent' }, 'auth.json': present('Y') }))
+    expect(d).toEqual({ action: 'skip-missing', missingFiles: ['models.json'] })
+  })
+
+  it('②变体2（持续抑制）：文件仍缺失时，后续其它文件变化也一律抑制（否则空配置会打塌可用集合）', () => {
+    const snap = makeSnapshot()
+    evaluateSnapshot(snap, obs({ 'models.json': present('A'), 'auth.json': present('X') }))
+    evaluateSnapshot(snap, obs({ 'models.json': { state: 'absent' }, 'auth.json': present('X') }))
+    // 第二拍：models.json 仍缺失（基线已 absent），auth.json 又变化 → 仍必须抑制
+    const d = evaluateSnapshot(snap, obs({ 'models.json': { state: 'absent' }, 'auth.json': present('Z') }))
+    expect(d).toEqual({ action: 'skip-missing', missingFiles: ['models.json'] })
+  })
+
+  it('②变体3（恢复）：文件被写回 → 解除抑制并触发一次 refresh', () => {
+    const snap = makeSnapshot()
+    evaluateSnapshot(snap, obs({ 'models.json': present('A'), 'auth.json': present('X') }))
+    evaluateSnapshot(snap, obs({ 'models.json': { state: 'absent' }, 'auth.json': present('X') }))
+    const d = evaluateSnapshot(snap, obs({ 'models.json': present('A-fixed'), 'auth.json': present('X') }))
+    expect(d).toMatchObject({ action: 'refresh', changedFiles: ['models.json'] })
+    // 抑制已解除：后续同内容拍回到「无变化」
+    const d2 = evaluateSnapshot(snap, obs({ 'models.json': present('A-fixed'), 'auth.json': present('X') }))
+    expect(d2).toEqual({ action: 'none', reason: 'unchanged' })
+  })
+
+  it('②变体4（auth.json 不对称）：auth.json 曾存在 → 缺失 → 按普通变化处理（凭据缺失自愈，不抑制）', () => {
+    const snap = makeSnapshot()
+    evaluateSnapshot(snap, obs({ 'models.json': present('A'), 'auth.json': present('X') }))
+    const d = evaluateSnapshot(snap, obs({ 'models.json': present('A'), 'auth.json': { state: 'absent' } }))
+    expect(d).toMatchObject({ action: 'refresh', changedFiles: ['auth.json'] })
+    // 写回后再次刷新（恢复）
+    const d2 = evaluateSnapshot(snap, obs({ 'models.json': present('A'), 'auth.json': present('X') }))
+    expect(d2).toMatchObject({ action: 'refresh', changedFiles: ['auth.json'] })
+  })
+
+  it('③ 非 ENOENT 读失败（unreadable）→ 只跳过该文件，另一文件照常比较', () => {
+    const snap = makeSnapshot()
+    evaluateSnapshot(snap, obs({ 'models.json': present('A'), 'auth.json': present('X') }))
+    const d = evaluateSnapshot(snap, obs({ 'models.json': { state: 'unreadable' }, 'auth.json': present('Y') }))
+    expect(d).toMatchObject({ action: 'refresh', changedFiles: ['auth.json'] })
+    // 该文件基线未被动（下拍读得回来仍是原内容 → 不误报变化）
+    const d2 = evaluateSnapshot(snap, obs({ 'models.json': present('A'), 'auth.json': present('Y') }))
+    expect(d2).toEqual({ action: 'none', reason: 'unchanged' })
+  })
+
+  it('③变体：两文件都不可读 → 本拍无动作（不刷新、不推进任何基线）', () => {
+    const snap = makeSnapshot()
+    const d = evaluateSnapshot(snap, obs({ 'models.json': { state: 'unreadable' }, 'auth.json': { state: 'unreadable' } }))
+    expect(d).toEqual({ action: 'none', reason: 'all-unreadable' })
+    expect(snap.baselines.size).toBe(0)
+  })
+
+  it('④ 不存在 → 存在（首次保存 provider 物化文件）→ refresh', () => {
+    const snap = makeSnapshot()
+    evaluateSnapshot(snap, obs({ 'models.json': { state: 'absent' }, 'auth.json': present('X') }))
+    const d = evaluateSnapshot(snap, obs({ 'models.json': present('{"providers":{"p":{"models":[{"id":"m"}]}}}'), 'auth.json': present('X') }))
+    expect(d).toMatchObject({ action: 'refresh', changedFiles: ['models.json'] })
+  })
+})
+
+describe('readObservation —— 真实文件系统（ENOENT vs 其它错误的区分）', () => {
+  let dir: string
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'provider-live-sync-'))
+  })
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+  })
+
+  it('文件存在 → present + 原样内容（不解析）', async () => {
+    writeFileSync(join(dir, 'models.json'), '{"providers":{}}')
+    const o = await readObservation(dir, 'models.json')
+    expect(o).toEqual({ state: 'present', content: '{"providers":{}}' })
+  })
+
+  it('文件不存在 → absent（ENOENT 是合法态，不是错误）', async () => {
+    expect(await readObservation(dir, 'models.json')).toEqual({ state: 'absent' })
+  })
+
+  it('目录位（EISDIR）等非 ENOENT 故障 → unreadable', async () => {
+    mkdirSync(join(dir, 'auth.json'))
+    expect(await readObservation(dir, 'auth.json')).toEqual({ state: 'unreadable' })
+  })
+
+  it('无读权限 → unreadable（不异常外泄）', async () => {
+    writeFileSync(join(dir, 'auth.json'), '{}')
+    chmodSync(join(dir, 'auth.json'), 0o000)
+    try {
+      const o = await readObservation(dir, 'auth.json')
+      // root 用户（CI 容器）可能无视权限位 → 两种结果都合法，断言不抛即可
+      expect(['unreadable', 'present']).toContain(o.state)
+    } finally {
+      chmodSync(join(dir, 'auth.json'), 0o600)
+    }
+  })
+})
+
+/**
+ * tick 层（MF-1-1 回归）：decision 之外的扩展运行时行为——首基线完成的置位时机与
+ * `modelRegistry.refresh` 触发。
+ *
+ * catalog-only 全新安装标准路径：首拍双 absent（models.json/auth.json 均不存在）→ 用户
+ * 首次保存凭据（auth.json 物化）→ **必须** refresh。缺陷形态：initialized 只在 refresh
+ * 分支内置位，双 absent 首拍 decision=none 提前 return 不置位，首个真实变化被
+ * firstBaseline 吞掉（用户首次配完凭据切模型仍报 Model not found）。
+ *
+ * 驱动方式：getAgentDir mock 指向真实 tmp fixture（mkdtemp 自建自删）；fake pi 只需
+ * `on('session_start')` 捕获 ctx（含 refresh/getError spy）；fake timers 只替换
+ * setTimeout/clearTimeout——tick 链上的 readFile 与 setImmediate 保持真实，I/O 宏任务
+ * 逐事件循环轮次自然落地。
+ */
+describe('tick 层 —— 首基线置位时机与 refresh 触发', () => {
+  let agentDir: string
+
+  beforeEach(() => {
+    agentDir = mkdtempSync(join(tmpdir(), 'provider-live-sync-tick-'))
+    piMocks.agentDir = agentDir
+    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] })
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+    rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+  })
+
+  function startWithFakeCtx(): { refresh: ReturnType<typeof vi.fn>; appendEntry: ReturnType<typeof vi.fn> } {
+    const refresh = vi.fn(async () => ({ aborted: false, errors: new Map() }))
+    const getError = vi.fn(() => null)
+    const ctx = { modelRegistry: { refresh, getError } }
+    const appendEntry = vi.fn()
+    const on = vi.fn()
+    providerLiveSync({ on, appendEntry } as unknown as ExtensionAPI)
+    const handler = on.mock.calls.find((call) => call[0] === 'session_start')?.[1] as
+      | ((event: unknown, sessionCtx: unknown) => void)
+      | undefined
+    expect(handler).toBeTypeOf('function')
+    handler({ type: 'session_start' }, ctx)
+    return { refresh, appendEntry }
+  }
+
+  /** 逐真实事件循环轮次（setImmediate 未被 fake）轮询等待谓词成立。 */
+  async function waitFor(predicate: () => boolean, maxTurns = 5_000): Promise<void> {
+    for (let i = 0; i < maxTurns && !predicate(); i += 1) {
+      await new Promise<void>((resolve) => setImmediate(resolve))
+    }
+  }
+
+  /**
+   * 推进一个轮询周期并等本拍 tick **完整落地**。确定性拍屏障：tick 完成后其
+   * `.finally(schedule)` 必然注册下一个 fake timer——等 `getTimerCount() >= 1`
+   * 即证明本拍 readFile 链（真实线程池 I/O）已结束。固定轮次 flush 不行：线程池
+   * 完成回调的到达轮次不定，偶发「tick 晚于下一拍的 writeFileSync 完成 → 新内容
+   * 被当首基线」假红。
+   */
+  async function tickOnce(): Promise<void> {
+    await vi.advanceTimersByTimeAsync(POLL_INTERVAL_MS)
+    await waitFor(() => vi.getTimerCount() >= 1)
+  }
+
+  it('MF-1-1：首拍双 absent（catalog-only 全新安装）→ auth.json 首次出现 → 必须 refresh', async () => {
+    const { refresh } = startWithFakeCtx()
+    await tickOnce() // 首拍：双 absent 建基线，decision=none（首拍本就不刷新）
+    expect(refresh).not.toHaveBeenCalled()
+    // 用户首次保存凭据：auth.json 物化（absent → present）——不得被 firstBaseline 吞掉
+    writeFileSync(join(agentDir, 'auth.json'), '{"kimi":{"apiKey":"sk-1"}}')
+    await tickOnce()
+    expect(refresh).toHaveBeenCalledTimes(1)
+    expect(refresh).toHaveBeenCalledWith({ allowNetwork: false })
+  })
+
+  it('对照不变量：首拍双在场建基线不刷新；此后内容变化 → refresh 恰一次', async () => {
+    writeFileSync(join(agentDir, 'models.json'), '{"providers":{}}')
+    writeFileSync(join(agentDir, 'auth.json'), '{"a":"x"}')
+    const { refresh } = startWithFakeCtx()
+    await tickOnce() // 首拍 decision=refresh 被 firstBaseline 吞（pi spawn 时已建快照）
+    expect(refresh).not.toHaveBeenCalled()
+    writeFileSync(join(agentDir, 'auth.json'), '{"a":"y"}')
+    await tickOnce()
+    expect(refresh).toHaveBeenCalledTimes(1)
+  })
+
+  /**
+   * 日志通道（MF-2-5 迁移回归）：error 级日志必须落 pi.appendEntry（session JSONL custom
+   * entry，持久化、不依赖 pi 不捕获的 extension stderr）。驱动 `getError()` 非空分支——
+   * 引擎拒绝配置是「坏配置的唯一机器证据」（SKILL.md 排障入口），其可见性不能寄望 stderr。
+   */
+  it('MF-2-5：引擎拒绝配置 → logger.error 落 pi.appendEntry（provider-live-sync:log）', async () => {
+    writeFileSync(join(agentDir, 'models.json'), '{"providers":{}}')
+    writeFileSync(join(agentDir, 'auth.json'), '{"a":"x"}')
+    const refresh = vi.fn(async () => ({ aborted: false, errors: new Map() }))
+    const getError = vi.fn(() => 'Invalid models.json schema: - providers')
+    const ctx = { modelRegistry: { refresh, getError } }
+    const appendEntry = vi.fn()
+    const on = vi.fn()
+    providerLiveSync({ on, appendEntry } as unknown as ExtensionAPI)
+    const handler = on.mock.calls.find((call) => call[0] === 'session_start')?.[1] as
+      | ((event: unknown, sessionCtx: unknown) => void)
+      | undefined
+    handler({ type: 'session_start' }, ctx)
+
+    await tickOnce() // 首拍建基线（不刷新）
+    writeFileSync(join(agentDir, 'auth.json'), '{"a":"y"}')
+    await tickOnce() // 本拍 refresh → getError() 非空 → logger.error
+
+    expect(appendEntry).toHaveBeenCalledWith('provider-live-sync:log', expect.objectContaining({
+      level: 'error',
+      message: expect.stringContaining('[provider-live-sync] model config rejected by the engine'),
+    }))
+  })
+})

package/src/index.ts

@@ -0,0 +1,296 @@
+/**
+ * provider-live-sync —— 运行中 pi 进程的**模型快照实时同步**扩展。
+ *
+ * 问题（根因①）：pi 0.84.4 的可用模型集合冻结在 **spawn 时刻**——`set_model` 从
+ * `session.modelRuntime.getAvailableSnapshot()` 解析（`dist/modes/rpc/rpc-mode.js:367-375`），
+ * 该快照建于 `ModelRuntime.create()` 的 refresh（`dist/core/model-runtime.js:63-100`），
+ * 而 pi 自身**没有文件 watcher、没有 refresh RPC**。于是「会话开着 → 在设置页新增 provider/
+ * 模型/凭据 → 直接切到新模型」会报 `Model not found`（缺凭据与缺模型同文案），只能重开会话。
+ *
+ * 解法：本扩展按固定周期读 `<agentDir>/models.json` 与 `<agentDir>/auth.json`，**内容变化**时
+ * 调 pi 自己的 `ctx.modelRegistry.refresh({ allowNetwork: false })`——`ModelRuntime.refresh()`
+ * 首行即 `ModelConfig.load(modelsPath)` **重读磁盘配置**，随后 `rebuildProviders()` 按新配置重组
+ * （`dist/core/model-runtime.js:501-513`），因此新增/删除 provider、模型与凭据都会立即生效；
+ * `allowNetwork:false` 走本地恢复相位并在任何凭据解析/入网前返回（pi-ai `dist/models.js:153-158`）
+ * ——**零网络请求**。
+ *
+ * 设计取舍（详见 docs 侧设计文档 §3.3 D3/D11/D12）：
+ * - **轮询而非 fs.watch**：仓内 `skill-registry` 有 macOS `fs.watch` 触发率 ~40% 前科；轮询不依赖
+ *   事件送达，无静默漏报面。代价 = 每进程 2 个小文件 / 2s 的只读 I/O。
+ * - **按文件独立「存在性 + 内容」基线**：状态 = 缺失/存在 × 内容字节。① 持续缺失 = 非变化信号
+ *   （**models.json 本就不存在是 catalog-only 安装的常态**，不能因此关停另一文件的比较）；
+ *   ② 「曾存在 → 缺失」（quarantine / 外部删除窗口）→ 更新基线但**抑制 refresh**（否则会以空配置
+ *   重建可用集合，把坏写放大成真正丢失）；③ 非 ENOENT 读失败（EACCES 等）→ 该文件本拍不比较、
+ *   不覆盖基线（另一文件照常）；④ 内容变化 / 「不存在 → 存在」→ refresh。
+ *   其中 `models.json` 的「曾存在 → 缺失」抑制是**持续**的（直到文件回归）——否则下一拍另一个文件的
+ *   变更仍会触发 refresh 并应用空配置，保护形同虚设；`auth.json` 消失不威胁配置，按普通变化处理
+ *   （凭据缺失自愈）。
+ * - **基线推进与 refresh 成败无关**：刷新抛错也不回退基线，否则同一坏内容会每拍刷新 + 每拍报错。
+ * - **不解析文件内容**：纯字节比较，判定权全交 pi（pi 对 JSONC/BOM 的宽容与本扩展无关）。
+ * - **错误可见性靠 pi 自己的诊断**：`refresh()` 只返回 `{aborted, errors}`，本退化类
+ *   （models.json 解析失败 / schema 非法）实测 `errors.size=0`、`aborted=false`——**唯一有效判据是
+ *   `ctx.modelRegistry.getError()`**（`dist/core/model-runtime.js:305-317` 合成 config error +
+ *   per-provider composition error）。非空即原样落 ERROR 日志（不解析、不分类、不新增判定层）。
+ * - **定时器 unref**：不阻止 pi 进程退出。
+ *
+ * 可配置项：无（轮询周期 2s 为设计标定值；如需调整请改本包常量并同步设计文档）。
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { getLogger, setPiHandle } from "@zhushanwen/pi-extension-logger";
+
+/** 轮询周期（ms）。设计标定：内容变更到生效的上界 ≈ 2s，小于「保存 → 切回会话 → 点选」的人工时延。 */
+export const POLL_INTERVAL_MS = 2_000;
+
+/** 受监视的两个配置文件（pi 的 models.json 授权源 + auth.json 凭据源）。 */
+export const WATCHED_FILES = ["models.json", "auth.json"] as const;
+export type WatchedFile = (typeof WATCHED_FILES)[number];
+
+/** 单文件观察状态：读失败（非 ENOENT）与「文件不存在」是两种不同的态，不可混为一谈。 */
+export type FileObservation =
+  | { state: "present"; content: string }
+  | { state: "absent" }
+  | { state: "unreadable" };
+
+/** 单文件基线（上一拍成功观察到的态）。 */
+export type FileBaseline = { state: "present"; content: string } | { state: "absent" };
+
+export interface Snapshot {
+  baselines: Map<WatchedFile, FileBaseline>;
+  /**
+   * 是否已完成首个**可比**基线拍：两受监视文件各完成一次可比观察（absent 计入、
+   * unreadable 不计）。此后首拍只建基线、不触发 refresh（pi spawn 时已按磁盘建过快照）。
+   * 置位与当拍 decision 无关——双 absent 首拍（catalog-only 常态）也构成完整基线。
+   */
+  initialized: boolean;
+  /**
+   * **曾存在 → 缺失且尚未恢复**的文件（quarantine / 外部删除窗口）。
+   *
+   * 抑制是**持续**的（不是一拍）：只要 `models.json` 处于这个集合里，任何 refresh 都会重读磁盘、
+   * 以「无 override 的空配置」重建可用集合——把一次坏写放大成用户自定义 provider 的**真正丢失**
+   * （设计 D3②/§3.6「『曾存在 → 缺失』跃迁抑制 refresh」）。恢复 = 该文件重新出现（内容变化）
+   * 或会话重启（spawn 期重读）。
+   *
+   * 只对 `models.json` 生效：`auth.json` 消失不威胁配置本身（凭据缺失是自愈的——文件写回后
+   * 下一拍 refresh 即恢复），按普通内容变化处理，避免「凭据变更被静默丢弃」。
+   */
+  suppressed: Set<WatchedFile>;
+}
+
+export type SyncDecision =
+  | { action: "none"; reason: "no-baseline" | "unchanged" | "all-unreadable" }
+  | { action: "refresh"; changedFiles: WatchedFile[] }
+  | { action: "skip-missing"; missingFiles: WatchedFile[] };
+
+/** 读单个受监视文件：ENOENT → absent；其它错误 → unreadable（含权限、I/O 故障）。 */
+export async function readObservation(agentDir: string, file: WatchedFile): Promise<FileObservation> {
+  try {
+    const content = await readFile(join(agentDir, file), { encoding: "utf8" });
+    return { state: "present", content };
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException | null)?.code;
+    if (code === "ENOENT") return { state: "absent" };
+    return { state: "unreadable" };
+  }
+}
+
+/** 单文件本拍归类：changed（触发 refresh）/ missing（models.json 抑制窗口）/ stable（无变化）。 */
+type FileChangeKind = "changed" | "missing" | "stable";
+
+/**
+ * 单文件比对 + 基线推进（规则 2-4 的 per-file 分支；返回该文件的变化归类）。
+ * present：先摘抑制集合（文件回归即变化），再比内容，基线推进为 present；
+ * absent：按 absentChangeKind 归类，基线推进为 absent。
+ */
+function classifyFileChange(
+  snapshot: Snapshot,
+  file: WatchedFile,
+  obs: FileObservation,
+): FileChangeKind {
+  const prev = snapshot.baselines.get(file);
+
+  if (obs.state === "present") {
+    // 文件回来了（隔离副本被写回 / 用户重新保存）→ 视为变化，恢复正常刷新。
+    const recovered = snapshot.suppressed.delete(file);
+    const changed = recovered || !prev || prev.state !== "present" || prev.content !== obs.content;
+    snapshot.baselines.set(file, { state: "present", content: obs.content });
+    return changed ? "changed" : "stable";
+  }
+
+  const kind = absentChangeKind(snapshot, file, prev);
+  snapshot.baselines.set(file, { state: "absent" });
+  return kind;
+}
+
+/** absent 观察的归类（规则 3 + 抑制持续语义；models.json 路径有入抑制集合的副作用）。 */
+function absentChangeKind(
+  snapshot: Snapshot,
+  file: WatchedFile,
+  prev: FileBaseline | undefined,
+): FileChangeKind {
+  if (prev?.state !== "present") {
+    // 仍在抑制窗口内（持续缺失）：保持抑制，逐拍静默（只在跃迁那一拍有日志）；
+    // 从未出现（catalog-only 常态）= 非变化信号。
+    return snapshot.suppressed.has(file) ? "missing" : "stable";
+  }
+  if (file === "models.json") {
+    // 配置源消失：抑制**整拍**刷新（refresh 会以空配置重建可用集合）；抑制持续到文件回归。
+    snapshot.suppressed.add(file);
+    return "missing";
+  }
+  // auth.json 消失：不威胁 provider 配置，按普通变化处理（凭据缺失自愈——写回即恢复）。
+  return "changed";
+}
+
+/** 本拍决策（优先级：全不可比 → models.json 抑制 → 无变化 → 仅缺失 → refresh）。 */
+function decideAction(
+  snapshot: Snapshot,
+  changedFiles: WatchedFile[],
+  missingFiles: WatchedFile[],
+  comparable: number,
+): SyncDecision {
+  if (comparable === 0) return { action: "none", reason: "all-unreadable" };
+  // 抑制优先于一切：配置源缺失窗口内绝不 refresh（宁可让引擎保留最后一份好快照）。
+  if (snapshot.suppressed.has("models.json")) return { action: "skip-missing", missingFiles: ["models.json"] };
+  if (changedFiles.length === 0 && missingFiles.length === 0) {
+    return { action: "none", reason: "unchanged" };
+  }
+  if (changedFiles.length === 0) return { action: "skip-missing", missingFiles };
+  return { action: "refresh", changedFiles };
+}
+
+/**
+ * 对比观察与基线，产出本拍决策**并就地推进基线**（按文件独立）。
+ *
+ * 规则（与设计 D3 逐条对应，顺序即优先级）：
+ * 1. `unreadable` → 该文件不参与比较、基线不动（另一文件照常）；
+ * 2. 与基线同态（present 内容相同 / 双双 absent）→ 变化集不含该文件；
+ * 3. `present → absent`（曾存在、现在缺失）→ 记入 missing（调用方抑制 refresh 且只记一行）；
+ * 4. `absent → present` 或 present 内容变化 → 记入 changed（触发 refresh）；
+ * 5. 基线推进发生在**决策产出时**，与 refresh 成败无关。
+ */
+export function evaluateSnapshot(
+  snapshot: Snapshot,
+  observations: Map<WatchedFile, FileObservation>,
+): SyncDecision {
+  const changedFiles: WatchedFile[] = [];
+  const missingFiles: WatchedFile[] = [];
+  let comparable = 0;
+
+  for (const file of WATCHED_FILES) {
+    const obs = observations.get(file);
+    if (!obs || obs.state === "unreadable") continue;
+    comparable += 1;
+    const kind = classifyFileChange(snapshot, file, obs);
+    if (kind === "changed") changedFiles.push(file);
+    else if (kind === "missing") missingFiles.push(file);
+  }
+
+  return decideAction(snapshot, changedFiles, missingFiles, comparable);
+}
+
+/**
+ * 本拍完成可比观察的文件数（absent 计入、unreadable / 缺观察不计）——首基线完成判定：
+ * 与当拍 decision 解耦，双 absent 首拍（catalog-only 常态）也构成完整基线。
+ */
+function comparableCount(observations: Map<WatchedFile, FileObservation>): number {
+  let count = 0;
+  for (const file of WATCHED_FILES) {
+    const obs = observations.get(file);
+    if (obs && obs.state !== "unreadable") count += 1;
+  }
+  return count;
+}
+
+/**
+ * 日志出口 = @zhushanwen/pi-extension-logger（logging-conventions.md 三层通道分类）。
+ * pi 自身不捕获 extension 的 stderr——`process.stderr.write` 直写在独立 pi 用户形态下
+ * 不落任何文件（taiji 托管形态的落盘链也只是 runtime rpc-client 转发），故不走 stderr：
+ * - error（config 消失 / 引擎拒绝配置 / refresh 报错 / tick 异常）→ pi.appendEntry 持久化
+ *   （session JSONL custom entry `provider-live-sync:log`，不进 LLM 上下文）+
+ *   `TAIJI_AGENT_DEBUG=1` / `TAIJI_AGENT_EXT_LOG=1` 时文件日志（`<agentDir>/logs/`）；
+ * - debug（变更检测的正常观察 `config change detected`）→ 仅文件日志，默认 no-op
+ *   （taiji 托管环境 runtime spawn 恒注入 `TAIJI_AGENT_EXT_LOG=1`，INFO 级落盘）。
+ * 消息前缀 `[provider-live-sync]` 由 logger 按 extName 自动补（getLogger 名即前缀唯一来源）。
+ */
+const logger = getLogger("provider-live-sync");
+
+export default function providerLiveSync(pi: ExtensionAPI): void {
+  // 最早期注入 pi handle——上方 logger 的 error 通道（appendEntry）由此生效（session-reader 同款）。
+  setPiHandle(pi);
+  const snapshot: Snapshot = { baselines: new Map(), initialized: false, suppressed: new Set() };
+  /** ctx 每次 session_start 重新捕获（pi 可能换实例；未就绪时本拍跳过且不推进基线）。 */
+  let ctx: ExtensionContext | null = null;
+  let timer: NodeJS.Timeout | null = null;
+  /** 「曾存在 → 缺失」状态跃迁去重：只在跃迁那一拍记日志，持续缺失零输出。 */
+  const missingLogged = new Set<WatchedFile>();
+
+  pi.on("session_start", (_event, sessionCtx) => {
+    ctx = sessionCtx;
+  });
+
+  const tick = async (): Promise<void> => {
+    const currentCtx = ctx;
+    if (!currentCtx) return; // 会话未就绪：本拍跳过且不推进基线（下拍重试，无 dirty 状态机）
+    try {
+      const agentDir = getAgentDir();
+      const observations = new Map<WatchedFile, FileObservation>();
+      for (const file of WATCHED_FILES) {
+        observations.set(file, await readObservation(agentDir, file));
+      }
+      const decision = evaluateSnapshot(snapshot, observations);
+      // 首基线完成判定与 refresh 分支解耦：本拍两受监视文件完成可比观察（absent 计入、
+      // unreadable 不计）即置位。若只在 refresh 分支置位，双 absent 首拍（catalog-only
+      // 全新安装常态）decision=none 永不置位，下一拍 auth.json 首次出现会被 firstBaseline
+      // 吞掉——用户首次配完凭据切模型仍报 Model not found。
+      const firstBaseline = !snapshot.initialized;
+      if (comparableCount(observations) === WATCHED_FILES.length) snapshot.initialized = true;
+      if (decision.action === "skip-missing") {
+        for (const file of decision.missingFiles) {
+          if (!missingLogged.has(file)) {
+            missingLogged.add(file);
+            logger.error(
+              `config file disappeared: ${file} — refresh suppressed until it is written again `
+              + "(rebuilding from an empty config would drop the user's custom providers from the running "
+              + "engine; it keeps its last good snapshot meanwhile; restarting the session also recovers).",
+            );
+          }
+        }
+        return;
+      }
+      for (const file of WATCHED_FILES) missingLogged.delete(file);
+      if (decision.action !== "refresh") return;
+      // 首个基线拍不刷新（进程启动时 pi 已按磁盘配置建过快照，重复刷新纯浪费）。
+      if (firstBaseline) return;
+
+      logger.debug(`config change detected (${decision.changedFiles.join(", ")}) → refreshing model snapshot`);
+      const result = await currentCtx.modelRegistry.refresh({ allowNetwork: false });
+      // 有效判据 = getError() 全文（本退化类 errors.size/aborted 恒为空/假，见模块头注释）。
+      const error = currentCtx.modelRegistry.getError();
+      if (error) {
+        logger.error(`model config rejected by the engine (models.json / auth.json): ${error}`);
+      } else if (result.errors.size > 0 || result.aborted) {
+        logger.error(`refresh finished with errors (aborted=${String(result.aborted)}, providers=${result.errors.size})`);
+      }
+    } catch (err) {
+      // 轮询绝不自杀：本拍失败下一拍继续（内容未变则基线已推进 → 不会重复刷新同一内容）。
+      const message = err instanceof Error ? err.message : String(err);
+      logger.error(`tick failed: ${message}`);
+    }
+  };
+
+  const schedule = (): void => {
+    timer = setTimeout(() => {
+      void tick().finally(schedule);
+    }, POLL_INTERVAL_MS);
+    timer.unref();
+  };
+
+  // 首拍只建基线（不 refresh）；此后每拍比较。（pi 无 extension 生命周期 shutdown 钩子，
+  // 进程退出时 unref 定时器自然消失。）
+  schedule();
+}