# CHANGELOG

本文件记录已发布版本的用户可见变更。更细的过程见 git log。0.x 期间破坏性变更走 minor 号，条目里标 **BREAKING**。

## 0.11.1 — 2026-11-03

- 发布：`CHANGELOG.md` 进 `files`。此前 tarball 里没有它，pi 更新扩展后看不到变更。本版起补上。首次更新到本版时，"Extension Updates" 下只有这一条。

## 0.11.0 — 2026-11-01

- **BREAKING**：源码并入 [setwhite/pi-extensions](https://github.com/setwhite/pi-extensions)，只从 npm 安装。pi 的 git 安装只认仓库根，指不到子目录。`git:` 安装留在旧仓，不再更新。
- 开发：CI、发布、提交前闸、lockfile 与行尾策略收成仓库一份。提交前闸改跑全部三个包。

## 0.10.0 — 2026-11-01

- 代理故障不再拖死全部请求。有代理时先走代理。传输层失败（连不上 / 超时）时改直连，重试一次。连续 3 次失败后，60 秒内只直连，到期自动再试。降级写进结果头一行，含重试间隔（ADR-0013）。
- **BREAKING**：`timeoutMs` 改为每次尝试各一份。此前一份预算覆盖整个请求，含全部重定向跳与读 body。现在每次传输尝试各有一份。代理连不上、改直连时，最坏延迟是两份之和（默认 60 秒）。靠 `timeoutMs` 卡总耗时的配置要按两倍留余量。
- gh 探测不再把网络故障说成「未登录」。配置了 `proxy` 时先带代理探，失败再去掉代理复核一次（复核预算 `min(timeoutMs, 5s)`）。业务命令走探测走通的那条路。带代理的结论一律不缓存，只有直连复核算数，缓存键也带上代理。此前一次代理故障会让本会话所有 GitHub 链接都不走 gh，原因还写着 `gh is not authenticated`。实测代理不通时，gh 自己就会报 `The token in keyring is invalid.`。

## 0.9.0 — 2026-10-25

- guidance 的 `description` 与 `promptSnippet` 接受空串。`""` 把内置提示词替换为空值。此前报 `expected a non-empty string` 并拒绝加载。纯空白与 `null` 仍然报错。

## 0.8.4 — 2026-10-25

- 无运行时变更（运行时与 0.8.3 相同）。模块文档收口为取舍、坑与指针，契约以代码与测试为准（ADR-0011）。任务台账迁到 `docs/todos/`。
- 文档：新增 ADR-0012（e2e 只在发版前手动跑，不进 CI）。README 中英两版按 STE10 重写。
- 开发：删掉 7 处复述请求形状的文件头注释。三个回归测试的头部注释去掉失效的任务号。

## 0.8.3 — 2026-10-22

- 升级 `undici` 8.10.2 → 8.12.3。修掉重复 `Content-Encoding` 头导致的解压失败（8.11.0）。抓取拿到的正文不再可能解成乱码。
- 开发：新增 `test/undici-surface.test.ts`，钉住四条隐式契约：`badPortsSet` 的内部路径、http 目标经代理走 absolute-form 不建隧道、响应自动解压、错误 cause 链带底层 code。undici 升级流程写进 `docs/modules/http.md` 的「依赖升级」。
- 开发：`files` 与依赖方向不再靠 review。`test/package.test.ts` 断言发布物（新增顶层模块漏写目录即红）。`pnpm check:imports` 执行 `docs/ARCHITECTURE.md` §2 的边与四处「单一出口」。发布流水线在 publish 前再对真实 tarball 断言一遍。
- 开发：新增 `pnpm test:e2e`（真链路冒烟：8 家 provider 按 key 跳过，加一个公开页抓取），不进 CI。`pnpm test` 只跑夹具。
- 开发：CI 显式 `pnpm install --frozen-lockfile`（不再依赖 action 的隐式安装）、`biome check --error-on-warnings`、`timeout-minutes: 10`，action 按 commit SHA 固定。新增每日 `pnpm audit --prod` 工作流。新增 `.githooks/pre-commit`（`git config core.hooksPath .githooks` 启用）。
- 文档：`docs/modules/config.md` 删掉默认值列。默认值唯一来源改为 `schema.ts` 常量与根 README「完整示例」。此前三处同源，无人对账。

## 0.8.2 — 2026-10-21

- 无运行时变更（运行时与 0.8.1 相同）。新增 `.gitattributes`（`* text=auto eol=lf`），把仓库与工作区的行尾固定成 LF。CI 恢复 Windows runner。此前为躲 CRLF 与 biome `lineEnding lf` 的冲突，只跑 Linux。

## 0.8.1 — 2026-10-18

- 无运行时变更（运行时与 0.8.0 相同）。CI 只跑 Linux：Windows runner 的 `core.autocrlf=true` 会让 checkout 出来是 CRLF，与 biome 的 LF 默认冲突，lint 必红。README 中英两版补「发版」一行。模块文档把代理转发形态改成实测口径：`http:` 目标走 absolute-form，只有 `https:` 目标才建 CONNECT 隧道。

## 0.8.0 — 2026-10-18

- 出站请求失败的错误文案带上底层原因（`connect ECONNREFUSED …`、`getaddrinfo ENOTFOUND …`、`bad port`）。此前模型只能看到 undici 的 `fetch failed`，无从判断该换域名还是重试。
- 跨域重定向摘掉的认证头从 `authorization` 扩到整个头名族（`x-api-key`、`x-subscription-token` 等以 `token` / `api-key` / `api_key` / `apikey` 结尾的头名）。此前 exa / parallel / keenable 的 key 会随 30x 转发到新域。
- GitHub release 链接的 tag 与 blob / tree 的 ref 走同一套校验。gh 参数用 `--` 分界，`/o/r/releases/tag/--repo` 不再被当成开关。含控制字符的 tag 落到提取器链，不再把 Node 的 `must be a string without null bytes` 透给模型。
- 开发：新增 `pnpm lint`（biome 的 lint + 格式闸）。CI 与发布流水线跑同一条命令。

## 0.7.0 — 2026-10-18

- 新增 parallel / keenable / deepseek 三家。三家既是搜索源（`provider`），也是提取器（`fetch.extractors`）。key 走 `PARALLEL_API_KEY` / `KEENABLE_API_KEY` / `DEEPSEEK_API_KEY` 或 `config.apiKeys.*`。
- README 的最小可用配置补上 `provider`。此前只演示 tavily 的 key，换源时看不出来要改哪里。

## 0.6.1 — 2026-10-18

- 无功能变更（运行时与 0.6.0 相同）。文档重构：模块文档移入 `docs/modules/`（npm 包内不再含这 7 份 README），决策拆成 `docs/adr/`，新增本文件与 `docs/GLOSSARY.md`。

## 0.6.0 — 2026-10-11

- **BREAKING**：`web_search` 移除 per-call `provider` 参数。换源只走 `WEB_SEARCH_PROVIDER` / `config.provider`（ADR-0001）。
- `web_fetch` 折叠行标注最终提取来源，如 `✓ Fetched: 标题 (exa)`。

## 0.5.0 — 2026-10-11

- 新增 reddit handler：默认把 reddit 域名换成 redlib 实例，再交给提取器链（ADR-0009）。

## 0.4.0 — 2026-10-10

- 无功能变更：文档精简，README 加封面图。

## 0.3.0 — 2026-10-10

- 新增 firecrawl / perplexity 搜索源与 firecrawl / jina 提取器。

## 0.2.0 — 2026-10-10

- `fetch.allowRaw` 默认关闭（`raw` 参数不进 schema）。默认提取链改为 `html` → `jina`。`handlers.github.timeoutMs` 改为 30s，与 HTTP 超时一致。
- 新增英文 README。新增 npm 发布工作流（OIDC 可信发布）。

## 0.1.0 — 2026-10-09

- 首个发布：`config/`（单 JSON + 环境变量 key）、`http/`（代理 / 超时 / 重定向）、`ssrf/`、`providers/`（tavily / brave / exa）、`handlers/`（GitHub）、`extractors/`（tavily / exa / html）、`tools/` 与结果信封、入口注册、TUI 渲染、CI。