feat(env): 托管 agent CLI 的 PI_PROXY_* 变量（write/install + status/doctor）

CHANGELOG.md

@@ -5,6 +5,35 @@
 
 ## [Unreleased]
 
+### Added
+
+- **`proxyctl env --write` / `--install` / `--uninstall`：把 `PI_PROXY_*` 托管给 agent CLI。**
+  通用 `HTTP(S)_PROXY` 覆盖不到所有 agent：omp 的 anthropic-messages transport
+  只认 `PI_PROXY_<PROVIDER>`，没有这个变量就直连，受限地区直接 `403 Request
+  not allowed`。现在 proxyctl 负责把出口写成可 source 的契约文件
+  `~/.config/proxyctl/agent-env.sh`，并在 `start` / `stop` / `restart` / `fix` /
+  `daemon` / `engine` 之后自动刷新：引擎端口在听 → 指向引擎；否则指向
+  `agent_env.fallback_daemon` 声明的 port；两个都没在听 → 删掉文件（避免 agent
+  一直打到死口）。`--install` 幂等注入 shell rc 的 marker 块，`--uninstall`
+  一步收摊。
+- `proxyctl status` 新增 `AGENT ENV` 段；`status --json` 新增 `data.agent_env`
+  （契约文件路径、当前出口与来源、出口是否可达、`in_sync`、shell rc 是否已注入）。
+- `config.yaml` 新增 `agent_env:` 段：`enabled` / `providers` / `fallback_daemon`
+  / `shell_rc`。
+- doctor 新增 3 条建议：`agent_env.dead_endpoint`（warn，文件指向已停的出口）、
+  `agent_env.missing`（有存活出口但没生成文件）、`agent_env.not_sourced`
+  （文件在但 shell rc 没 source 它）；三条都带 `fix_command`、`auto_fixable=true`。
+
+### Changed
+
+- `proxyctl env`（无参）现在额外输出 `PI_PROXY_<PROVIDER>` 的 `export` 行；
+  当前没有存活出口时改输出 `unset`，避免 `eval "$(proxyctl env)"` 之后残留指向
+  死口的旧值。`proxyctl env --unset` 同时清除 `PI_PROXY_*`。
+- `proxyctl env` 支持 `--json`（`data.vars` + `data.agent_env`）。
+- `proxyctl --version --json` 的 `supported_features` 新增 `agent_env_contract`、
+  `status_agent_env`。
+- 相关 flag 已进 bash / zsh / fish 补全。
+
 ## [0.5.13] — 2026-07-17
 
 ### Fixed

config.yaml.example

@@ -75,6 +75,24 @@ extra_daemons: {}
 #   - 100.64.0.0/10        # Tailscale CGNAT
 #   - .ts.net              # Tailscale MagicDNS
 
+# ─────────────────────────────────────────────────────────────
+# agent CLI 的 provider 级代理变量（v0.5.14+）
+# ─────────────────────────────────────────────────────────────
+# 通用 HTTP(S)_PROXY 覆盖不到全部 agent：omp 的 anthropic-messages transport
+# （cowork-fetch）只认 PI_PROXY_<PROVIDER>，缺它就直连 → 受限地区 403。
+# proxyctl 按生命周期把出口写成可 source 的契约文件（默认
+# ~/.config/proxyctl/agent-env.sh），start/stop/restart/fix/daemon 自动刷新：
+# 引擎端口在听 → 指向引擎；否则指向 fallback_daemon 的 port；都没有 → 删文件。
+#
+#   proxyctl env --write      # 立即生成/刷新
+#   proxyctl env --install    # 再往 shell rc 注入 source 块（幂等）
+#   proxyctl env --uninstall  # 收摊
+agent_env:
+  enabled: true
+  providers: [anthropic]        # → PI_PROXY_ANTHROPIC；可加 openai-codex 等
+  fallback_daemon: claude-proxy  # extra_daemons 里的名字；null 关闭兜底
+  shell_rc: ~/.zprofile          # --install 注入的目标
+
 # ─────────────────────────────────────────────────────────────
 # 其他配置
 # ─────────────────────────────────────────────────────────────

man/proxyctl.1

@@ -184,8 +184,20 @@ rulePayload / host / IP 聚合目的地，输出 app_contexts / candidate_contex
 
 .SS 工具
 .TP
-.B proxyctl env [--unset]
-输出 / 清除 HTTP_PROXY / HTTPS_PROXY / NO_PROXY 环境变量（可 \fIeval\fR）。
+.B proxyctl env [--unset | --write | --install | --uninstall] [--shell-rc \fIPATH\fR] [--json]
+无参：输出 HTTP_PROXY / HTTPS_PROXY / NO_PROXY 环境变量 + provider 级
+\fBPI_PROXY_\fR\fIPROVIDER\fR（可 \fIeval\fR；无存活出口时输出 \fBunset\fR）。
+\fB--unset\fR 清除同一组变量。
+.PP
+\fB--write\fR 把 \fBPI_PROXY_*\fR 写成契约文件
+\fI~/.config/proxyctl/agent-env.sh\fR：引擎端口在听就指向引擎，否则指向
+\fIconfig.yaml\fR 中 \fBagent_env.fallback_daemon\fR 的 port，都没在听则删除文件。
+\fBstart\fR / \fBstop\fR / \fBrestart\fR / \fBfix\fR / \fBdaemon\fR / \fBengine\fR
+之后会自动刷新，无需手工调用。
+.PP
+\fB--install\fR 额外把 source 块（marker 包裹，幂等）写进 \fIshell_rc\fR
+（默认 \fI~/.zprofile\fR，可用 \fB--shell-rc\fR 覆盖）；\fB--uninstall\fR 摘掉该块
+并删除契约文件。三种写模式都支持 \fB--dry-run\fR。
 .TP
 .B proxyctl log [--tail \fIN\fR] [--no-follow] [--json]
 查看后端日志。默认 \fItail -f\fR；\fB--json\fR 为 NDJSON（首行 meta header + 数据行）。
@@ -268,10 +280,21 @@ DEPENDENCY_MISSING — 依赖二进制 / 脚本缺失
 .TP
 .B NO_COLOR
 遵循 https://no-color.org/。
+.TP
+.B PROXYCTL_AGENT_ENV_PATH
+覆盖 agent 代理变量契约文件路径（默认 \fI~/.config/proxyctl/agent-env.sh\fR）。
+.TP
+.B PROXYCTL_SHELL_RC
+覆盖 \fBproxyctl env --install\fR 注入的 shell rc（默认取配置里的
+\fIagent_env.shell_rc\fR，即 \fI~/.zprofile\fR）。
 .SH FILES
 .TP
 .I ~/.config/proxyctl/config.yaml
-proxyctl 自身配置（API token / 端口 / 企业 DNS / extra_daemons / no_proxy_extra / plugins_disabled）。
+proxyctl 自身配置（API token / 端口 / 企业 DNS / extra_daemons / no_proxy_extra / agent_env / plugins_disabled）。
+.TP
+.I ~/.config/proxyctl/agent-env.sh
+agent 代理变量契约文件（\fBPI_PROXY_<PROVIDER>\fR）；由 \fBproxyctl env --write\fR
+与生命周期命令生成，勿手改。
 .TP
 .I ~/.config/mihomo/config.yaml
 mihomo 引擎配置（rules / proxies / proxy-providers / dns / tun）。