npm - @cc-monitoring/proxy-core - Versions diffs - 0.1.5 → 0.1.7 - Mend

@cc-monitoring/proxy-core 0.1.5 → 0.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (445) hide show

package/dist/docs/assets/proxy-core_index.md.BM6VV5Qe.js ADDED Viewed

@@ -0,0 +1,55 @@
+import{_ as a,o as n,c as e,a2 as p}from"./chunks/framework.D_Xv2a7c.js";const m=JSON.parse('{"title":"proxy-core","description":"","frontmatter":{},"headers":[],"relativePath":"proxy-core/index.md","filePath":"proxy-core/index.md"}'),o={name:"proxy-core/index.md"};function l(i,s,t,c,d,r){return n(),e("div",null,[...s[0]||(s[0]=[p(`<h1 id="proxy-core" tabindex="-1">proxy-core <a class="header-anchor" href="#proxy-core" aria-label="Permalink to &quot;proxy-core&quot;"></a></h1><h2 id="本文档覆盖的源文件" tabindex="-1">本文档覆盖的源文件 <a class="header-anchor" href="#本文档覆盖的源文件" aria-label="Permalink to &quot;本文档覆盖的源文件&quot;"></a></h2><ul><li><code>apps/proxy-core/package.json</code></li><li><code>apps/proxy-core/tsconfig.json</code></li><li><code>apps/proxy-core/src/**/*.ts</code>（不含测试）</li></ul><h2 id="模块角色" tabindex="-1">模块角色 <a class="header-anchor" href="#模块角色" aria-label="Permalink to &quot;模块角色&quot;"></a></h2><p><code>proxy-core</code> 是整个系统的后端。它承担四类职责：</p><ol><li><strong>业务代理</strong>：转发 Claude Code 的 <code>/v1/*</code> 请求到上游 AI API，同时记录完整请求与响应</li><li><strong>UI 后端</strong>：提供 REST API + 两个 WebSocket 通道给前端面板（proxy-cli）</li><li><strong>CLI 工具</strong>：<code>proxy</code> 命令行工具，用于 start/stop/status/logs/config/reload/test/ui/clean-requests</li><li><strong>静态资源托管</strong>：<code>@fastify/static</code> 挂载 <code>proxy-cli/dist</code> 到 <code>/ui/</code></li></ol><p>发布名：<code>@cc-monitoring/cli-core</code>，<code>bin/proxy</code> → <code>dist/cli/index.js</code>，<code>main</code> → <code>dist/server/index.js</code>。</p><h2 id="目录布局" tabindex="-1">目录布局 <a class="header-anchor" href="#目录布局" aria-label="Permalink to &quot;目录布局&quot;"></a></h2><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>apps/proxy-core/</span></span>
+<span class="line"><span>├── bin/proxy-cli.ts          # 一行 bin，只 import dist/cli/index.js</span></span>
+<span class="line"><span>├── ecosystem.config.cjs      # PM2 配置（.cjs 因为 root type=module）</span></span>
+<span class="line"><span>├── package.json</span></span>
+<span class="line"><span>├── tsconfig.json</span></span>
+<span class="line"><span>└── src/</span></span>
+<span class="line"><span>    ├── cli/</span></span>
+<span class="line"><span>    │   ├── index.ts          # Commander 命令注册</span></span>
+<span class="line"><span>    │   └── commands/</span></span>
+<span class="line"><span>    │       ├── start.ts</span></span>
+<span class="line"><span>    │       ├── stop.ts</span></span>
+<span class="line"><span>    │       ├── status.ts</span></span>
+<span class="line"><span>    │       ├── logs.ts</span></span>
+<span class="line"><span>    │       ├── config.ts</span></span>
+<span class="line"><span>    │       ├── reload.ts</span></span>
+<span class="line"><span>    │       ├── test.ts</span></span>
+<span class="line"><span>    │       └── ui.ts</span></span>
+<span class="line"><span>    ├── server/</span></span>
+<span class="line"><span>    │   ├── index.ts          # createServer / startServer / ESM+PM2 入口判断</span></span>
+<span class="line"><span>    │   ├── proxy.ts          # 代理转发核心 (486 行)</span></span>
+<span class="line"><span>    │   ├── ui-route.ts       # REST + 双 WebSocket + 静态挂载</span></span>
+<span class="line"><span>    │   ├── providers-route.ts</span></span>
+<span class="line"><span>    │   ├── data-push.ts      # WebSocket 广播工具</span></span>
+<span class="line"><span>    │   ├── auth.ts           # Bearer Token 校验</span></span>
+<span class="line"><span>    │   └── middleware/</span></span>
+<span class="line"><span>    │       └── request-id.ts # nanoid + x-request-id</span></span>
+<span class="line"><span>    ├── config/</span></span>
+<span class="line"><span>    │   ├── index.ts          # load / save / reset</span></span>
+<span class="line"><span>    │   └── schema.ts         # Zod 校验</span></span>
+<span class="line"><span>    ├── logger/</span></span>
+<span class="line"><span>    │   └── index.ts          # Pino + file-stream-rotator</span></span>
+<span class="line"><span>    ├── utils/</span></span>
+<span class="line"><span>    │   ├── db.ts             # SQLite 初始化 + 4 版 schema 迁移</span></span>
+<span class="line"><span>    │   ├── providers-db.ts   # providers 表 CRUD + validate</span></span>
+<span class="line"><span>    │   ├── request-writer.ts # requests 表读写</span></span>
+<span class="line"><span>    │   ├── stats-aggregator.ts</span></span>
+<span class="line"><span>    │   ├── status-history.ts # 内存中的 CPU/内存滑动窗口</span></span>
+<span class="line"><span>    │   ├── sse-accumulator.ts</span></span>
+<span class="line"><span>    │   ├── sse-writer.ts     # 合成 SSE</span></span>
+<span class="line"><span>    │   ├── tool-injector.ts</span></span>
+<span class="line"><span>    │   ├── inject-loop.ts    # tool 命中后的内部循环</span></span>
+<span class="line"><span>    │   ├── pm2.ts            # PM2 promise 封装</span></span>
+<span class="line"><span>    │   ├── paths.ts          # ~/.cc-monitoring 锚点</span></span>
+<span class="line"><span>    │   ├── esm-dirname.ts    # ESM+CJS 双模 __dirname</span></span>
+<span class="line"><span>    │   ├── net.ts            # waitForPort</span></span>
+<span class="line"><span>    │   ├── version.ts        # 项目 + Claude Code 版本</span></span>
+<span class="line"><span>    │   └── migrate-files-to-db.ts # 旧文件系统迁移到 SQLite（一次性脚本）</span></span>
+<span class="line"><span>    ├── tools/</span></span>
+<span class="line"><span>    │   ├── index.ts          # 转发 registry 导出</span></span>
+<span class="line"><span>    │   ├── registry.ts       # ALL_TOOLS + enabled/find</span></span>
+<span class="line"><span>    │   ├── types.ts          # InjectableTool 接口</span></span>
+<span class="line"><span>    │   ├── curl.tool.ts</span></span>
+<span class="line"><span>    │   └── probe.tool.ts</span></span>
+<span class="line"><span>    └── types/</span></span>
+<span class="line"><span>        ├── api.ts / config.ts / log.ts / pm2.ts / index.ts</span></span></code></pre></div><h2 id="依赖速览" tabindex="-1">依赖速览 <a class="header-anchor" href="#依赖速览" aria-label="Permalink to &quot;依赖速览&quot;"></a></h2><p><code>apps/proxy-core/package.json</code>：</p><ul><li><code>fastify</code> <code>4.26</code> + <code>@fastify/static</code> <code>7.0</code> + <code>@fastify/http-proxy</code> <code>9.5</code>（<strong>未使用</strong>，早期遗留）</li><li><code>@fastify/websocket</code> <code>10</code>（也未使用，服务器直接用原生 <code>ws</code>）</li><li><code>commander</code> <code>11.1</code>、<code>chalk</code> <code>5.6</code>、<code>ora</code> <code>9.4</code>（CLI 交互）</li><li><code>better-sqlite3</code> <code>12.11</code> + <code>@types/better-sqlite3</code></li><li><code>pino</code> <code>8.18</code> + <code>pino-pretty</code> <code>10.3</code> + <code>file-stream-rotator</code> <code>1.0</code>（日志）</li><li><code>pm2</code> <code>5.4</code></li><li><code>nanoid</code> <code>5.0</code>（request id）</li><li><code>open</code> <code>10.1</code>（<code>ui</code> 命令打开浏览器）</li><li><code>ws</code> <code>8.21</code>（原生 WebSocket）</li><li><code>zod</code> <code>3.23</code></li></ul><p>Dev：Jest 29 + ts-jest + tsx 4。</p><h2 id="阅读顺序" tabindex="-1">阅读顺序 <a class="header-anchor" href="#阅读顺序" aria-label="Permalink to &quot;阅读顺序&quot;"></a></h2><ul><li>先看启动 → <a href="./entry.html">entry.md</a></li><li>后看代理核心 → <a href="./proxy.html">proxy.md</a></li><li>想理解数据 → <a href="./data-layer.html">data-layer.md</a> + <a href="./stats.html">stats.md</a></li><li>想扩展 tool → <a href="./tool.html">tool.md</a></li><li>想改 UI 端点 → <a href="./ui-routes.html">ui-routes.md</a></li><li>想改供应商 → <a href="./providers.html">providers.md</a></li><li>想改配置字段 → <a href="./config.html">config.md</a></li><li>打包/进程细节 → <a href="./pm2.html">pm2.md</a></li><li>底层小工具 → <a href="./utilities.html">utilities.md</a></li><li>CLI 每个命令 → <a href="./cli.html">cli.md</a></li></ul>`,15)])])}const u=a(o,[["render",l]]);export{m as __pageData,u as default};

package/dist/docs/assets/proxy-core_index.md.BM6VV5Qe.lean.js ADDED Viewed

@@ -0,0 +1 @@

+ import{_ as a,o as n,c as e,a2 as p}from"./chunks/framework.D_Xv2a7c.js";const m=JSON.parse('{"title":"proxy-core","description":"","frontmatter":{},"headers":[],"relativePath":"proxy-core/index.md","filePath":"proxy-core/index.md"}'),o={name:"proxy-core/index.md"};function l(i,s,t,c,d,r){return n(),e("div",null,[...s[0]||(s[0]=[p("",15)])])}const u=a(o,[["render",l]]);export{m as __pageData,u as default};

package/dist/docs/assets/proxy-core_pm2.md.DUhWEtgn.js ADDED Viewed

@@ -0,0 +1,79 @@
+import{_ as i,o as a,c as n,a2 as t}from"./chunks/framework.D_Xv2a7c.js";const o=JSON.parse('{"title":"proxy-core / PM2 集成","description":"","frontmatter":{},"headers":[],"relativePath":"proxy-core/pm2.md","filePath":"proxy-core/pm2.md"}'),e={name:"proxy-core/pm2.md"};function l(h,s,p,k,r,d){return a(),n("div",null,[...s[0]||(s[0]=[t(`<h1 id="proxy-core-pm2-集成" tabindex="-1">proxy-core / PM2 集成 <a class="header-anchor" href="#proxy-core-pm2-集成" aria-label="Permalink to &quot;proxy-core / PM2 集成&quot;"></a></h1><h2 id="本文档覆盖的源文件" tabindex="-1">本文档覆盖的源文件 <a class="header-anchor" href="#本文档覆盖的源文件" aria-label="Permalink to &quot;本文档覆盖的源文件&quot;"></a></h2><ul><li><code>apps/proxy-core/ecosystem.config.cjs</code></li><li><code>apps/proxy-core/src/utils/pm2.ts</code></li><li><code>apps/proxy-core/src/utils/esm-dirname.ts</code></li><li><code>apps/proxy-core/src/server/index.ts:42-60</code>（入口守卫）</li></ul><h2 id="挑战" tabindex="-1">挑战 <a class="header-anchor" href="#挑战" aria-label="Permalink to &quot;挑战&quot;"></a></h2><p>项目根 <code>package.json</code> 声明了 <code>&quot;type&quot;: &quot;module&quot;</code>，因此所有 <code>.js</code> 文件默认按 ESM 加载。而 PM2 是 CJS 库，<code>ecosystem.config.js</code> 会被解析成 ESM，报 <code>Cannot use import statement / module.exports is not defined</code>。同时 PM2 fork 模式启动脚本时会替换 <code>process.argv[1]</code>，导致 ESM <code>import.meta.url === main module url</code> 判定失败。</p><p>三个应对：</p><ol><li><code>ecosystem.config.cjs</code> 用 <code>.cjs</code> 扩展名，绕过 <code>type: module</code> 全局设定</li><li><code>utils/pm2.ts</code> 用 <code>createRequire(import.meta.url)</code> 加载 PM2 库</li><li><code>server/index.ts</code> 用 <code>pm_id</code> / <code>NODE_APP_INSTANCE</code> 环境变量补检测</li></ol><h2 id="ecosystem-config-cjs-逐行" tabindex="-1"><code>ecosystem.config.cjs</code> 逐行 <a class="header-anchor" href="#ecosystem-config-cjs-逐行" aria-label="Permalink to &quot;\`ecosystem.config.cjs\` 逐行&quot;"></a></h2><div class="language-js vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">js</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> path</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> require</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;path&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> os</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> require</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;os&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> dataDir</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> process.env.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">CC_DATA_DIR</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ||</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">join</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(os.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">homedir</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;.cc-monitoring&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> logsDir</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">join</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(dataDir, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;logs&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> configPath</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> process.env.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">CONFIG_PATH</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ||</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">join</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(dataDir, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;config.json&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">module</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">exports</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  apps: [{</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;cc-monitoring&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    script: path.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">join</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(__dirname, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;dist/server/index.js&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    cwd: dataDir,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    instances: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    exec_mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;fork&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    autorestart: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    watch: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    max_memory_restart: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;200M&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    env: {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      NODE_ENV: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;production&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      CONFIG_PATH: configPath</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    env_development: {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      NODE_ENV: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;development&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      CONFIG_PATH: configPath</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    log_date_format: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;YYYY-MM-DD HH:mm:ss Z&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    error_file: path.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">join</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(logsDir, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;error.log&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    out_file: path.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">join</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(logsDir, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;out.log&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    merge_logs: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }]</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>关键点：</p><ul><li><code>name: &#39;cc-monitoring&#39;</code>：CLI 里所有 PM2 操作都用这个进程名（<code>utils/pm2.ts</code>、<code>ui-route.ts</code> 的 <code>getProcessStatus(&#39;cc-monitoring&#39;)</code> 等）</li><li><code>script</code>：<code>path.join(__dirname, ...)</code>——<code>__dirname</code> 是 CJS 全局，在 <code>.cjs</code> 里可用。相对包内绝对路径，不依赖 <code>process.cwd()</code></li><li><code>cwd: dataDir</code>：让子进程的相对路径日志/DB 落到用户目录</li><li><code>instances: 1</code> + <code>exec_mode: &#39;fork&#39;</code>：cluster 模式基于 worker 复制主进程内存，ESM 会在 worker 里报错；fork 是干净的 spawn Node</li><li><code>autorestart: true</code> + <code>max_memory_restart: &#39;200M&#39;</code>：内存超 200M 自动重启（应用层代理有大响应缓冲的可能）</li><li><code>watch: false</code>：不监控文件变动重启（生产模式）</li><li><code>env</code> / <code>env_development</code>：<code>NODE_ENV</code> 切换；<code>CONFIG_PATH</code> 覆盖 <code>loadConfig</code> 的读取路径</li><li><code>log_date_format</code>：PM2 自己的日志时间戳（区别于 pino 的 ISO time）</li><li><code>error_file / out_file</code>：PM2 fork 子进程的 stderr/stdout 落盘位置</li><li><code>merge_logs: true</code>：多实例合并（虽然本项目 instances=1，属默认合理设置）</li></ul><h2 id="node-侧-pm2-封装-utils-pm2-ts" tabindex="-1">Node 侧 PM2 封装 <code>utils/pm2.ts</code> <a class="header-anchor" href="#node-侧-pm2-封装-utils-pm2-ts" aria-label="Permalink to &quot;Node 侧 PM2 封装 \`utils/pm2.ts\`&quot;"></a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> requireCjs</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> NodeRequire</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (() </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  try</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">return</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> createRequire</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">getCurrentModuleUrl</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()) } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">catch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> require }</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})()</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> pm2</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> requireCjs</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;pm2&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">as</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> any</span></span></code></pre></div><ul><li><code>createRequire(getCurrentModuleUrl())</code>：ESM 环境下让 CJS <code>require</code> 可用</li><li><code>getCurrentModuleUrl()</code>（<code>esm-dirname.ts:52</code>）包装 <code>import.meta.url</code>——<code>__mocks__/esm-dirname.ts</code> 里被 Jest 覆盖成静态字符串，因为 ts-jest 编译 CJS 时无法解析 <code>import.meta</code></li><li>若 <code>createRequire</code> 也不可用（比如某种测试环境），fallback 到全局 <code>require</code>（此时应用其实已在 CJS 环境）</li></ul><p>内部 promisify 六个 PM2 API：</p><table tabindex="0"><thead><tr><th>内部</th><th>说明</th></tr></thead><tbody><tr><td><code>pm2Connect()</code></td><td>建立与 PM2 daemon 的 IPC</td></tr><tr><td><code>pm2Disconnect()</code></td><td>释放（<strong>必须调</strong>否则 daemon 认为客户端仍连着，其它 CLI 会等待）</td></tr><tr><td><code>pm2Start(options)</code></td><td>options 可以是 ecosystem 路径字符串或对象</td></tr><tr><td><code>pm2Stop(name)</code></td><td></td></tr><tr><td><code>pm2Reload(name)</code></td><td>优雅（零停机）重启</td></tr><tr><td><code>pm2List()</code></td><td>返回所有进程数组</td></tr></tbody></table><p>对外 5 个函数：</p><ul><li><code>startProcess(ecosystemPath)</code> = connect + start + disconnect</li><li><code>stopProcess(name)</code> = 同上</li><li><code>reloadProcess(name)</code> = 同上</li><li><code>waitForOnline(name, timeoutMs=8000, intervalMs=300)</code>：单次 connect + 轮询 list + disconnect（finally 保证释放）</li><li><code>getProcessStatus(name)</code>：单次 connect + list + disconnect，映射到 <code>Pm2ProcessStatus</code> 简洁形状</li></ul><p><strong>pm2Start 的错误可能是数组</strong>：PM2 有时候多个 app 同时失败，回调 <code>err</code> 是 <code>Error[]</code>：</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> error</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Array.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">isArray</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(err)</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  ?</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> new</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Error</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(err.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">map</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> e.message).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">join</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;; &#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">))</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  :</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> err</span></span></code></pre></div><p>合成成单个 Error 抛出。</p><h2 id="双入口守卫-server-index-ts" tabindex="-1">双入口守卫 <code>server/index.ts</code> <a class="header-anchor" href="#双入口守卫-server-index-ts" aria-label="Permalink to &quot;双入口守卫 \`server/index.ts\`&quot;"></a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> _isPm2</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> process.env.pm_id </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> undefined</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ||</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> process.env.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">NODE_APP_INSTANCE</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> !==</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> undefined</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> _currentModuleUrl</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> getCurrentModuleUrl</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> _mainModulePath</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> process.argv[</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">resolve</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(process.argv[</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;&#39;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> _mainModuleUrl</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> _mainModulePath </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> \`file://\${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">_mainModulePath</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> :</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;&#39;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> _isDirectExecution</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> _currentModuleUrl </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> _mainModuleUrl</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (_isPm2 </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">||</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> _isDirectExecution) {</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  startServer</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">catch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">err</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { console.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">error</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">...</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">); process.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">exit</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) })</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><ul><li><strong>PM2 fork 特殊性</strong>：PM2 用 <code>child_process.fork(ProcessContainerFork.js)</code> 拉起进程，<code>process.argv[1]</code> 是 <code>ProcessContainerFork.js</code> 而非 <code>dist/server/index.js</code>。所以 <code>_isDirectExecution</code> 判定为 false。用 <code>pm_id</code> env 补检测</li><li><strong>直接执行</strong>：<code>tsx src/server/index.ts</code> 或 <code>node dist/server/index.js</code>，<code>argv[1]</code> 就是本文件，URL 相等</li><li><strong>测试 / import</strong>：既不是 PM2 也不是直接执行时（例如从测试文件 import），两个判定都是 false，<code>startServer</code> 不自动跑，测试可以控制生命周期</li></ul><p><strong>注释里说明</strong>：<code>server/index.ts:42-45</code> 明确指出为什么不能用 <code>require.main === module</code>——那是 CJS 模式的判定，ESM 里 <code>require</code> 不存在。</p><h2 id="esm-dirname-替代-esm-dirname-ts" tabindex="-1">ESM __dirname 替代 <code>esm-dirname.ts</code> <a class="header-anchor" href="#esm-dirname-替代-esm-dirname-ts" aria-label="Permalink to &quot;ESM __dirname 替代 \`esm-dirname.ts\`&quot;"></a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> thisDirname</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (() </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  try</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">dirname</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">new</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> URL</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">meta</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.url).pathname) }</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  catch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">return</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> typeof</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> __dirname </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;undefined&#39;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ?</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> __dirname </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> process.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">cwd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() }</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})()</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> function</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> getCallerDirname</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">relativePath</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">resolve</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(thisDirname, relativePath)</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> function</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> getCurrentModuleUrl</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  return</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">meta</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.url</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><ul><li><code>thisDirname</code>：本模块自身的 __dirname 等价物（编译后位于 <code>dist/utils/</code>）</li><li><code>getCallerDirname(&#39;../server&#39;)</code>：调用方直接算出 <code>dist/server</code> 目录，不用自己 fiddle import.meta.url。多处使用（<code>ui-route.ts:396</code> 静态资源、<code>start.ts:32</code> ecosystem 路径、<code>ui.ts:9</code> UI dist 路径、<code>utils/version.ts:14</code> 版本文件）</li><li>三重 fallback（ESM → CJS <code>__dirname</code> → <code>process.cwd()</code>）覆盖所有环境</li></ul><p><strong>注释里明确</strong>：<code>getCurrentModuleUrl</code> 是包装函数而非直接内联 <code>import.meta.url</code>——因为 ts-jest 编译 CJS 时会遇到语法错误，<code>__mocks__/esm-dirname.ts</code> 可以在测试里替换整个模块返回固定值。</p><h2 id="冷启动全流程" tabindex="-1">冷启动全流程 <a class="header-anchor" href="#冷启动全流程" aria-label="Permalink to &quot;冷启动全流程&quot;"></a></h2><div class="language-mermaid vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">mermaid</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">sequenceDiagram</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  actor U as 用户</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  participant CLI as bin/proxy-cli.ts (ESM)</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  participant CI as cli/index.ts</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  participant SC as commands/start.ts</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  participant PM as utils/pm2.ts</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  participant D as PM2 daemon</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  participant PC as ProcessContainerFork.js (CJS wrapper)</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  participant S as dist/server/index.js (ESM)</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  U-&gt;&gt;CLI: proxy start</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  CLI-&gt;&gt;CI: import</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  CI-&gt;&gt;SC: startCommand</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  SC-&gt;&gt;PM: startProcess(ecosystemPath)</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  PM-&gt;&gt;PM: createRequire(import.meta.url)(&#39;pm2&#39;)</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  PM-&gt;&gt;D: pm2.connect + pm2.start(ecosystem.config.cjs)</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  D-&gt;&gt;PC: fork</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  PC-&gt;&gt;S: 加载 script</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  S-&gt;&gt;S: 检测 pm_id → startServer()</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  S-&gt;&gt;S: loadConfig → configureDbPath → createLogger → Fastify → setupUi → setupProxy → listen</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  PM-&gt;&gt;D: pm2.disconnect</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  PM--&gt;&gt;SC: return</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  SC-&gt;&gt;SC: waitForOnline (再 connect/disconnect)</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  SC-&gt;&gt;SC: waitForPort (递增退避)</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  SC--&gt;&gt;U: 打印 summary</span></span></code></pre></div><h2 id="相关文档" tabindex="-1">相关文档 <a class="header-anchor" href="#相关文档" aria-label="Permalink to &quot;相关文档&quot;"></a></h2><ul><li>CLI 命令细节 → <a href="./cli.html">cli.md</a></li><li>启动链 → <a href="./entry.html">entry.md</a></li></ul>`,33)])])}const c=i(e,[["render",l]]);export{o as __pageData,c as default};

package/dist/docs/assets/proxy-core_pm2.md.DUhWEtgn.lean.js ADDED Viewed

@@ -0,0 +1 @@

+ import{_ as i,o as a,c as n,a2 as t}from"./chunks/framework.D_Xv2a7c.js";const o=JSON.parse('{"title":"proxy-core / PM2 集成","description":"","frontmatter":{},"headers":[],"relativePath":"proxy-core/pm2.md","filePath":"proxy-core/pm2.md"}'),e={name:"proxy-core/pm2.md"};function l(h,s,p,k,r,d){return a(),n("div",null,[...s[0]||(s[0]=[t("",33)])])}const c=i(e,[["render",l]]);export{o as __pageData,c as default};

package/dist/docs/assets/proxy-core_providers.md.CbDZ6b_7.js ADDED Viewed

@@ -0,0 +1 @@

+ import{_ as i,o as s,c as a,a2 as d}from"./chunks/framework.D_Xv2a7c.js";const k=JSON.parse('{"title":"proxy-core / 供应商管理","description":"","frontmatter":{},"headers":[],"relativePath":"proxy-core/providers.md","filePath":"proxy-core/providers.md"}'),t={name:"proxy-core/providers.md"};function o(r,e,l,p,n,h){return s(),a("div",null,[...e[0]||(e[0]=[d('<h1 id="proxy-core-供应商管理" tabindex="-1">proxy-core / 供应商管理 <a class="header-anchor" href="#proxy-core-供应商管理" aria-label="Permalink to "proxy-core / 供应商管理""></a></h1><h2 id="本文档覆盖的源文件" tabindex="-1">本文档覆盖的源文件 <a class="header-anchor" href="#本文档覆盖的源文件" aria-label="Permalink to "本文档覆盖的源文件""></a></h2><ul><li><code>apps/proxy-core/src/server/providers-route.ts</code></li><li><code>apps/proxy-core/src/utils/providers-db.ts</code></li><li><code>apps/proxy-core/src/server/proxy.ts:40-88</code>（<code>resolveProxyTarget</code>）</li><li><code>apps/proxy-core/src/server/proxy.ts:98-115</code>（<code>getProxyModel</code>）</li><li><code>apps/proxy-core/src/utils/db.ts:68-131</code>（v2/v3/v4 schema）</li></ul><h2 id="用途" tabindex="-1">用途 <a class="header-anchor" href="#用途" aria-label="Permalink to "用途""></a></h2>「供应商」= 一组可切换的上游 AI API 配置（base_url + api_key + 多档模型）。用户可以在 UI 里维护多个 provider，激活其中一个作为「当前」，proxy 转发时会按激活项覆盖 <code>config.json</code> 的对应字段。<h2 id="数据模型" tabindex="-1">数据模型 <a class="header-anchor" href="#数据模型" aria-label="Permalink to "数据模型""></a></h2>SQLite <code>providers</code> 表（<code>db.ts:68-131</code>，v2 建表、v3 加 <code>is_default</code>、v4 放开 NOT NULL）：<table tabindex="0"><thead><tr><th>字段</th><th>类型</th><th>备注</th></tr></thead><tbody><tr><td><code>id</code></td><td>INTEGER PK AUTOINCREMENT</td><td></td></tr><tr><td><code>name</code></td><td>TEXT UNIQUE NOT NULL</td><td>主键之外的唯一键</td></tr><tr><td><code>base_url</code></td><td>TEXT (nullable)</td><td>完整 URL，含 API 前缀</td></tr><tr><td><code>api_key</code></td><td>TEXT (nullable)</td><td></td></tr><tr><td><code>model</code></td><td>TEXT (nullable)</td><td>主 model 覆盖</td></tr><tr><td><code>haiku_model</code></td><td>TEXT (nullable)</td><td>Anthropic 分档预留</td></tr><tr><td><code>sonnet_model</code></td><td>TEXT (nullable)</td><td></td></tr><tr><td><code>opus_model</code></td><td>TEXT (nullable)</td><td></td></tr><tr><td><code>subagent_model</code></td><td>TEXT (nullable)</td><td>子 agent 单独 model 预留</td></tr><tr><td><code>provider</code></td><td>TEXT NOT NULL</td><td>分类标签（"anthropic"/"aliyun"/"volces"...）</td></tr><tr><td><code>is_default</code></td><td>INTEGER NOT NULL DEFAULT 0</td><td>激活标记，全表最多 1 个为 1</td></tr><tr><td><code>created_at</code></td><td>TEXT DEFAULT CURRENT_TIMESTAMP</td><td></td></tr><tr><td><code>updated_at</code></td><td>TEXT DEFAULT CURRENT_TIMESTAMP</td><td></td></tr></tbody></table>索引：<code>idx_providers_name</code> UNIQUE。<code>haiku_model / sonnet_model / opus_model</code> 现已参与转发：<code>resolveProxyTarget</code> 读取 tier models 并返回，由 <code>getProxyModel</code> 根据请求的原始 model 按 tier 映射替换。<code>subagent_model</code> 目前仅存储，不参与转发——为将来子 agent 单独 model 预留。<h2 id="schema-迁移的三步" tabindex="-1">Schema 迁移的三步 <a class="header-anchor" href="#schema-迁移的三步" aria-label="Permalink to "Schema 迁移的三步""></a></h2><code>applySchemaV2</code>：建表 + 唯一索引，NOT NULL 约束加在 <code>base_url / api_key / model</code>（<code>db.ts:68-86</code>）。<code>applySchemaV3</code>：<code>PRAGMA table_info</code> 检测 <code>is_default</code> 是否存在，缺失则 <code>ALTER TABLE ADD COLUMN is_default INTEGER NOT NULL DEFAULT 0</code>（<code>db.ts:88-95</code>）。ADD COLUMN 是 SQLite 支持的少数原地变更之一，且带 DEFAULT 时不阻塞。<code>applySchemaV4</code>：SQLite 不能直接 <code>ALTER COLUMN</code> 去除 NOT NULL，只能重建表：新建 <code>providers_new</code>（无 NOT NULL） → <code>INSERT INTO providers_new SELECT ... FROM providers</code> → <code>DROP TABLE providers</code> → <code>ALTER TABLE providers_new RENAME TO providers</code> → 重建索引（<code>db.ts:97-132</code>）。整个过程带条件（仅当检测到 NOT NULL 列时才触发），idempotent-safe。放开 NOT NULL 是为支持「部分覆盖」：一个 provider 只需要指定要替换的字段，其它字段留 NULL 表示「用 config.json 默认」。<h2 id="resolveproxytarget" tabindex="-1"><code>resolveProxyTarget</code> <a class="header-anchor" href="#resolveproxytarget" aria-label="Permalink to "`resolveProxyTarget`""></a></h2><code>apps/proxy-core/src/server/proxy.ts:40-88</code>。每次业务请求进入 handler 都同步跑一次：<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button>ts<pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code>const active = db.prepare(\n 'SELECT base_url, api_key, model, haiku_model, sonnet_model, opus_model FROM providers WHERE is_default = 1 LIMIT 1'\n).get()\n\nif (active) {\n if (active.base_url?.trim()) { /* 覆盖 baseUrl/targetPath */ }\n if (active.api_key?.trim()) { apiKey = active.api_key }\n if (active.model?.trim()) { model = active.model }\n if (active.haiku_model?.trim()) { haiku_model = active.haiku_model }\n if (active.sonnet_model?.trim()) { sonnet_model = active.sonnet_model }\n if (active.opus_model?.trim()) { opus_model = active.opus_model }\n}</code></pre></div>返回 <code>{ baseUrl, targetPath, apiKey?, model?, haiku_model?, sonnet_model?, opus_model? }</code>。部分覆盖语义：<ul><li>只填 <code>base_url</code> → 换目标但复用 config.json 的 key（多数场景：切上游 endpoint）</li><li>只填 <code>api_key</code> → 换 key 但复用 target（多账户轮换）</li><li>只填 <code>model</code> → 强制所有请求跑同一 model（灰度、成本控制）</li><li>填 tier models（如 <code>sonnet_model</code>）→ 按 <code>getProxyModel</code> 映射，haiku/sonnet/opus 分别走不同模型</li><li>三者组合 → 完全独立的 provider</li></ul><h2 id="getproxymodel" tabindex="-1"><code>getProxyModel</code> <a class="header-anchor" href="#getproxymodel" aria-label="Permalink to "`getProxyModel`""></a></h2><code>apps/proxy-core/src/server/proxy.ts:98-115</code>。根据请求的原始 model 和 provider tier 配置选择替换 model：<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button>ts<pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code>claude-haiku* → haiku_model (fallback: model → undefined)\nclaude-sonnet* → sonnet_model (fallback: model → undefined)\nclaude-opus* → opus_model (fallback: model → undefined)\n其它 → model (fallback: undefined)</code></pre></div>fallback 链：tier 专属 model → 通用 <code>model</code> → undefined（不替换）。这让一个 provider 可以只配一个通用 model（所有 tier 都用它），也可以精细到每个 tier 不同 model。使用场景：国内模型通常不区分 tier，一个 <code>model</code> 字段就够了。但如果用 Anthropic 直连或不同 tier 跑不同供应商，<code>haiku_model / sonnet_model / opus_model</code> 让一次切换覆盖所有 tier。同步查询开销：better-sqlite3 是同步 API，单行 UNIQUE 索引 SELECT 微秒级，无缓存。热切换时下一次请求立即生效，不需要重启进程。异常兜底：<code>try/catch</code> 内部若 DB 未 initDatabase / URL 解析失败 / 表不存在，直接 fallback 到 <code>config.proxy.target</code> 的解析结果。<h2 id="node-层-utils-providers-db-ts" tabindex="-1">Node 层：<code>utils/providers-db.ts</code> <a class="header-anchor" href="#node-层-utils-providers-db-ts" aria-label="Permalink to "Node 层：`utils/providers-db.ts`""></a></h2>三类函数：<h3 id="listproviders-db" tabindex="-1"><code>listProviders(db)</code> <a class="header-anchor" href="#listproviders-db" aria-label="Permalink to "`listProviders(db)`""></a></h3><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button>ts<pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code>SELECT * FROM providers ORDER BY created_at DESC</code></pre></div>每行把 <code>is_default: number</code> 转为 <code>default: boolean</code> 后返回。<h3 id="saveproviders-db-providers" tabindex="-1"><code>saveProviders(db, providers[])</code> <a class="header-anchor" href="#saveproviders-db-providers" aria-label="Permalink to "`saveProviders(db, providers[])`""></a></h3>Destructive full replacement：先 <code>DELETE FROM providers</code>，再逐行 INSERT，全部在一个 SQLite transaction 内。空数组 → 清空全表。<code>INSERT</code> 中每个可选字段：<code>p.base_url?.trim() ? p.base_url : null</code> — 空串统一转 NULL，避免 UNIQUE / 逻辑判断上「非空空串」和「NULL」混淆。<code>is_default</code> 从 boolean 转 <code>1 | 0</code>。为什么全量替换而不是 upsert：前端 UI 是「一张表格 → 保存整表」的模式，实现上更简单，避免局部同步的边界（同一 id 改名、id 冲突等）。开销：只在用户点「保存」时触发（低频运维操作），准备语句每次 new 也无性能问题。<h3 id="validateprovider-validateproviders" tabindex="-1"><code>validateProvider</code> / <code>validateProviders</code> <a class="header-anchor" href="#validateprovider-validateproviders" aria-label="Permalink to "`validateProvider` / `validateProviders`""></a></h3>单个校验（<code>providers-db.ts:85-126</code>）：<ul><li>必填字段：<code>name</code>、<code>provider</code>（trim 后非空）</li><li>「至少填一个可选字段」：<code>base_url / api_key / model / haiku_model / sonnet_model / opus_model / subagent_model</code> 至少有一个非空——防止用户建一个只有名字的空 provider</li><li><code>base_url</code> 若填了必须是 <code>http:</code> 或 <code>https:</code> 协议的合法 URL</li></ul>批量校验（<code>providers-db.ts:128-156</code>）：<ul><li>逐个跑 <code>validateProvider</code>，错误项挂 <code>index</code></li><li>检查 <code>name</code> 重复</li><li>检查 <code>default: true</code> 最多 1 个</li></ul>任何一条不通过就整批拒绝，返回 <code>ProviderValidationError[]</code>。<h2 id="rest-端点" tabindex="-1">REST 端点 <a class="header-anchor" href="#rest-端点" aria-label="Permalink to "REST 端点""></a></h2><code>apps/proxy-core/src/server/providers-route.ts</code>：<h3 id="get-ui-api-providers" tabindex="-1">GET /ui/api/providers <a class="header-anchor" href="#get-ui-api-providers" aria-label="Permalink to "GET /ui/api/providers""></a></h3>无认证。<code>listProviders</code> 结果封装到 <code>{ providers }</code>。异常返回 500。<h3 id="post-ui-api-providers" tabindex="-1">POST /ui/api/providers <a class="header-anchor" href="#post-ui-api-providers" aria-label="Permalink to "POST /ui/api/providers""></a></h3>认证（<code>checkAuth</code>）。请求体：<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button>ts<pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code>{ providers: ProviderInput[] }</code></pre></div>流程：<ol><li>Bearer 认证</li><li>请求体存在 + <code>providers</code> 是数组</li><li><code>validateProviders(providers)</code> → 错误列表非空 → 400 + <code>{ errors }</code></li><li><code>saveProviders(db, providers)</code>（事务）</li><li><code>{ success: true }</code></li></ol><h2 id="前端交互" tabindex="-1">前端交互 <a class="header-anchor" href="#前端交互" aria-label="Permalink to "前端交互""></a></h2><code>ProviderManagerModal</code>（<code>apps/proxy-cli/src/components/ProviderManagerModal.tsx</code>）：<ul><li>打开时 <code>fetchProviders()</code> 装填表格</li><li>每行 9 个字段 + 「激活 / 删除」按钮；「激活」把该行 <code>default = true</code>、其它行 <code>default = false</code></li><li>「保存」调 <code>saveProviders(rows)</code>：全量提交</li><li>错误分两种：<code>errors[]</code>（字段级）分行显示；<code>error</code>（顶层字符串）单条显示</li></ul>详见 <a href="./../proxy-cli/components-config.html">../proxy-cli/components-config</a>。<h2 id="切换与广播" tabindex="-1">切换与广播 <a class="header-anchor" href="#切换与广播" aria-label="Permalink to "切换与广播""></a></h2>供应商切换不广播事件。前端保存成功后无 WebSocket 通知，其它连接需要手动刷新 <code>ProviderManagerModal</code>。业务请求端不受影响：<code>resolveProxyTarget</code> 下次 SELECT 就拿到新的激活项。<h2 id="相关文档" tabindex="-1">相关文档 <a class="header-anchor" href="#相关文档" aria-label="Permalink to "相关文档""></a></h2><ul><li>Schema 迁移全景 → <a href="./data-layer.html">data-layer.md</a></li><li>前端管理界面 → <a href="./../proxy-cli/components-config.html">../proxy-cli/components-config</a></li><li><code>resolveProxyTarget</code> 在 handler 中的位置 → <a href="./proxy.html#公用步骤">proxy.md</a></li></ul>',62)])])}const E=i(t,[["render",o]]);export{k as __pageData,E as default};

package/dist/docs/assets/proxy-core_providers.md.CbDZ6b_7.lean.js ADDED Viewed

@@ -0,0 +1 @@

package/dist/docs/assets/proxy-core_proxy.md.CzQYmX6X.js ADDED Viewed

@@ -0,0 +1,46 @@
+import{_ as e,o as i,c as a,a2 as t}from"./chunks/framework.D_Xv2a7c.js";const c=JSON.parse('{"title":"proxy-core / 代理转发（/v1/* 纯代理路径）","description":"","frontmatter":{},"headers":[],"relativePath":"proxy-core/proxy.md","filePath":"proxy-core/proxy.md"}'),l={name:"proxy-core/proxy.md"};function n(d,s,o,h,p,r){return i(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="proxy-core-代理转发-v1-纯代理路径" tabindex="-1">proxy-core / 代理转发（<code>/v1/*</code> 纯代理路径） <a class="header-anchor" href="#proxy-core-代理转发-v1-纯代理路径" aria-label="Permalink to &quot;proxy-core / 代理转发（\`/v1/*\` 纯代理路径）&quot;"></a></h1><h2 id="本文档覆盖的源文件" tabindex="-1">本文档覆盖的源文件 <a class="header-anchor" href="#本文档覆盖的源文件" aria-label="Permalink to &quot;本文档覆盖的源文件&quot;"></a></h2><ul><li><code>apps/proxy-core/src/server/proxy.ts:1-457</code></li></ul><blockquote><p><strong>注意</strong>：<code>/v1/*</code> 现为纯代理路径，不做请求体修改（除 model tier rewrite）、不做 tool 注入、不做 mock 拦截。增强型代理路径 <code>/api/chat</code> 见 <a href="./chat-api.html">chat-api.md</a>。</p></blockquote><h2 id="与-api-chat-的分工" tabindex="-1">与 <code>/api/chat</code> 的分工 <a class="header-anchor" href="#与-api-chat-的分工" aria-label="Permalink to &quot;与 \`/api/chat\` 的分工&quot;"></a></h2><table tabindex="0"><thead><tr><th>能力</th><th><code>/v1/*</code></th><th><code>/api/chat</code></th></tr></thead><tbody><tr><td>请求体修改</td><td>仅 model tier rewrite</td><td>model rewrite + MCP tool 注入</td></tr><tr><td>响应处理</td><td>透传原样（JSON/SSE pipe）</td><td>SSE 流式转发 + inject loop 续接</td></tr><tr><td>Session 管理</td><td>从 header 读 <code>x-claude-code-session-id</code></td><td>生成/复用 <code>x-chat-session-id</code>，支持 resume</td></tr><tr><td>Tool 注入</td><td>无</td><td><code>injectMcpTools</code>（MCP 动态 tool only）</td></tr><tr><td>Mock 拦截</td><td>无</td><td><code>shouldMock</code>（PoC 测试）</td></tr><tr><td>DB 记录</td><td>单条（原始请求）</td><td>多条（原始 + 每次 loop 迭代独立记录）</td></tr></tbody></table><h2 id="顶层结构" tabindex="-1">顶层结构 <a class="header-anchor" href="#顶层结构" aria-label="Permalink to &quot;顶层结构&quot;"></a></h2><p><code>setupProxy(fastify, proxyConfig)</code>（<code>proxy.ts:186-228</code>）注册一个 <code>fastify.all(&#39;/v1/*&#39;, ...)</code>。函数在服务启动时执行一次，主要做五件事：</p><ol><li><code>initDatabase()</code></li><li><code>mcpManager.init()</code>：初始化 MCP server 连接（seed config + connect enabled servers）</li><li><code>preloadMachineId()</code>：预加载 machine ID</li><li>启动 <code>aggregateStats</code> 定时器（5 分钟一次；启动时立即跑一次）</li><li><code>fastify.addHook(&#39;onClose&#39;, ...)</code>：关服时 <code>clearInterval</code> + <code>mcpManager.close()</code> + <code>closeDatabase()</code></li><li>注册请求 handler</li></ol><p>请求 handler 是本文的核心。</p><h2 id="为什么不用-fastify-http-proxy" tabindex="-1">为什么不用 <code>@fastify/http-proxy</code> <a class="header-anchor" href="#为什么不用-fastify-http-proxy" aria-label="Permalink to &quot;为什么不用 \`@fastify/http-proxy\`&quot;"></a></h2><p>Fastify 生态里有透明代理插件，但项目最早使用后遇到了矛盾：透明代理内部完全接管 request stream，任何试图读 body 的操作都会消耗 stream。而本项目要同时满足：</p><ul><li>记录完整 payload（model / messages / tools / MCP 参数）</li><li>原样转发 SSE 流</li><li>未来扩展 Token 统计、鉴权、审计</li></ul><p>HTTP stream 只能被消费一次，于是切到「应用层转发」：Fastify 让 body 先被解析成 JSON，业务代码用 <code>fetch()</code> 主动发起上游请求，响应体用 <code>Readable.fromWeb().pipe(reply.raw)</code> 转发。</p><h2 id="handler-三分支-纯代理" tabindex="-1">Handler 三分支（纯代理） <a class="header-anchor" href="#handler-三分支-纯代理" aria-label="Permalink to &quot;Handler 三分支（纯代理）&quot;"></a></h2><p><code>/v1/*</code> 不注入 tool、不做 mock、不进入 inject loop——只做纯转发 + 记录。</p><div class="language-mermaid vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">mermaid</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">flowchart TD</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  START([POST/GET/... /v1/*]) --&gt; RESOLVE[resolveProxyTarget]</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  RESOLVE --&gt; MODEL[getProxyModel tier rewrite]</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  MODEL --&gt; HEADER[extractSafeHeaders → filterForwardHeaders]</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  HEADER --&gt; DATA[组装 requestData + machineId]</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  DATA --&gt; LOG[cleanOldRequestsDB]</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  LOG --&gt; FETCH[fetch targetUrl]</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  FETCH --&gt; CT{content-type}</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  CT -- application/json --&gt; BR1[&quot;JSON 分支&lt;br/&gt;response.text() + reply.code().send()&quot;]</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  CT -- text/event-stream --&gt; BR2[&quot;SSE pipe 分支&lt;br/&gt;Readable.fromWeb.pipe(reply.raw)&lt;br/&gt;边转发边解析 data: 行&quot;]</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  FETCH --&gt; CATCH[catch → error 分支]</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  BR1 --&gt; SAVE[saveRequestDB + pushNewRequest]</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  BR2 --&gt; STREAM_END[on &#39;end&#39; → save + push]</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  CATCH --&gt; PUSH_ERR[pushNewRequest(error record)]</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  SAVE --&gt; END([返回])</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  STREAM_END --&gt; END</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  PUSH_ERR --&gt; END_ERR([返回错误 JSON])</span></span></code></pre></div><p>公用部分见下面 <a href="#公用步骤">公用步骤</a>，三个分支分别见后续小节。</p><h2 id="公用步骤" tabindex="-1">公用步骤 <a class="header-anchor" href="#公用步骤" aria-label="Permalink to &quot;公用步骤&quot;"></a></h2><h3 id="resolveproxytarget-proxyconfig" tabindex="-1"><code>resolveProxyTarget(proxyConfig)</code> <a class="header-anchor" href="#resolveproxytarget-proxyconfig" aria-label="Permalink to &quot;\`resolveProxyTarget(proxyConfig)\`&quot;"></a></h3><p><code>proxy.ts:40-88</code>。每次请求同步查一次 <code>providers WHERE is_default = 1 LIMIT 1</code>。better-sqlite3 是同步 API，单行 SELECT 微秒级，无需缓存。</p><p>策略：</p><ul><li>起始值 = 从 <code>config.proxy.target</code> 解析出 <code>baseUrl</code> + <code>targetPath</code>，<code>apiKey = config.proxy.apiKey</code></li><li>若激活的 provider 有 <code>base_url</code> 且非空 → 覆盖 baseUrl/targetPath</li><li>若 <code>api_key</code> 非空 → 覆盖 apiKey</li><li>若 <code>model / haiku_model / sonnet_model / opus_model</code> 非空 → 记入返回值（供 <code>getProxyModel</code> 按 tier 替换）</li><li>任何异常（DB 未初始化 / URL 解析失败）→ fallback 只用 config</li></ul><p>返回 <code>{ baseUrl, targetPath, apiKey?, model?, haiku_model?, sonnet_model?, opus_model? }</code>。</p><h3 id="getproxymodel-originalmodel-tiermodels" tabindex="-1"><code>getProxyModel(originalModel, tierModels)</code> <a class="header-anchor" href="#getproxymodel-originalmodel-tiermodels" aria-label="Permalink to &quot;\`getProxyModel(originalModel, tierModels)\`&quot;"></a></h3><p><code>proxy.ts:98-115</code>。根据请求的原始 model 和 provider tier 配置选择替换 model：</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">claude</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">haiku</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">*</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">   → </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">haiku_model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (fallback: model)</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">claude</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">sonnet</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">*</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  → </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">sonnet_model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (fallback: model)</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">claude</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">opus</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">*</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    → </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">opus_model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (fallback: model)</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">其它            → model</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">所有为空        → </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">undefined</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (不替换)</span></span></code></pre></div><p>例如：provider <code>sonnet_model = &quot;glm-5.1&quot;</code> → 请求 <code>model = &quot;claude-sonnet-4-6&quot;</code> 被改写为 <code>glm-5.1</code>。</p><h3 id="extractsafeheaders-headers" tabindex="-1"><code>extractSafeHeaders(headers)</code> <a class="header-anchor" href="#extractsafeheaders-headers" aria-label="Permalink to &quot;\`extractSafeHeaders(headers)\`&quot;"></a></h3><p><code>proxy.ts:117-128</code>。Fastify 的 <code>request.headers</code> 是 <code>Record&lt;string, unknown&gt;</code>（值可能是 string[]），直接传给 <code>filterForwardHeaders</code> 会产生 circular reference 或类型问题。<code>extractSafeHeaders</code> 把所有值转为 <code>string</code>（数组 join <code>, </code>），生成干净的 <code>Record&lt;string, string&gt;</code>。</p><h3 id="请求元数据组装" tabindex="-1">请求元数据组装 <a class="header-anchor" href="#请求元数据组装" aria-label="Permalink to &quot;请求元数据组装&quot;"></a></h3><p><code>proxy.ts:234-290</code>：</p><ul><li><code>sessionId = headers[&#39;x-claude-code-session-id&#39;] || &#39;unknown-session&#39;</code></li><li><code>getProxyModel(originalModel, resolved)</code> 替换 model（原地修改 <code>request.body.model</code>）</li><li><code>extractSafeHeaders(request.headers)</code> → <code>filterForwardHeaders(safeHeaders, resolved.apiKey)</code>：删 host/content-length/x-req-key；有 provider key 则覆盖 <code>x-api-key</code> 和 <code>authorization</code></li><li>从 Authorization / x-api-key 头提取客户端原 apiKey；从 filtered 后的 headers 提取实际发给上游的 proxyApiKey</li><li><code>machineId = getMachineIdSync() ?? undefined</code></li><li>组装 <code>RequestData</code>：request 部分立即填齐（含 machineId, baseUrl），response 部分先占位（<code>statusCode: 0, events: []</code>）</li></ul><h3 id="记录与清理" tabindex="-1">记录与清理 <a class="header-anchor" href="#记录与清理" aria-label="Permalink to &quot;记录与清理&quot;"></a></h3><ul><li><code>cleanOldRequestsDB(maxDays)</code>：每次请求都跑一次 DELETE（<code>maxDays=0</code> 时函数直接 return）</li><li><code>request.log.info(...)</code> 打印请求摘要</li></ul><h2 id="分支-1-json-响应" tabindex="-1">分支 1：JSON 响应 <a class="header-anchor" href="#分支-1-json-响应" aria-label="Permalink to &quot;分支 1：JSON 响应&quot;"></a></h2><p><code>proxy.ts:324-362</code>。当上游返回 <code>content-type: application/json</code>（通常是错误响应或非流式）：</p><ul><li><code>const responseBody = await response.text()</code></li><li>尝试 <code>JSON.parse(responseBody)</code>；成功则把整个 body 作为单一 event <code>push</code> 到 <code>events</code> 数组；失败则 push <code>{ raw: responseBody }</code></li><li>更新 <code>requestData.response.statusCode / headers / completedAt</code></li><li><code>saveRequestDB</code> 写库</li><li><code>extractTokenUsage</code> 提取 usage（从 events 中找 <code>type === &#39;message_delta&#39;</code>）</li><li><code>pushNewRequest</code> 广播（含 machineId, baseUrl）</li><li><code>reply.code(response.status).headers(...).send(responseBody)</code> 原样返回给客户端</li></ul><p>优点：完整错误信息进库，方便调试云端 429/401/500。</p><h2 id="分支-2-sse-pipe-默认路径" tabindex="-1">分支 2：SSE pipe（默认路径） <a class="header-anchor" href="#分支-2-sse-pipe-默认路径" aria-label="Permalink to &quot;分支 2：SSE pipe（默认路径）&quot;"></a></h2><p><code>proxy.ts:364-426</code>。零缓冲，纯转发：</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">reply.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">hijack</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">reply.raw.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">writeHead</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(response.status, responseHeaders)</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nodeStream</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Readable.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">fromWeb</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(response.body </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">as</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> any</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">nodeStream.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">on</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;data&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">chunk</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // 边转发边解析 data: 行到 requestData.response.events</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // 管道转发：chunk → reply.raw（客户端实时收到）</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // 解析：提取 data: 行 JSON → push events[]</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">nodeStream.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">on</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;end&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  requestData.response.completedAt </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> new</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Date</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">toISOString</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> saveRequestDB</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">...</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  pushNewRequest</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">...</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)  </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// 含 machineId, baseUrl</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">nodeStream.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pipe</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(reply.raw)</span></span></code></pre></div><ul><li><strong>Web ReadableStream → Node Readable</strong>：<code>Readable.fromWeb()</code>（Node 18+ 提供）</li><li><strong>数据事件双职责</strong>：pipe 会把 chunk 转发出去，同时 handler 里手动解析 <code>data:</code> 前缀行提取 event（含 Anthropic 双行 <code>event:xxx\\ndata:{...}</code> 格式）</li><li><strong>保留原响应头</strong>：不覆盖 content-type，客户端拿到的响应长得跟直连上游一样</li></ul><h3 id="sse-解析容错" tabindex="-1">SSE 解析容错 <a class="header-anchor" href="#sse-解析容错" aria-label="Permalink to &quot;SSE 解析容错&quot;"></a></h3><p><code>proxy.ts:412-427</code>：</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> lines</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> text.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">split</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\n</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> line</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> of</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> lines) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (line.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">startsWith</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;data:&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> eventData</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> line.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">slice</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">5</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">trim</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (eventData </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&amp;&amp;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> eventData </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;[DONE]&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      try</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { requestData.response.events.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">push</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">JSON</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">parse</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(eventData)) } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">catch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {}</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    }</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>同时兼容标准 <code>data: {...}</code> 和阿里云的 <code>event:xxx\\ndata:{...}</code> 双行格式（<code>event:</code> 行被忽略）。<code>[DONE]</code> 也跳过。</p><h3 id="chunk-边界问题" tabindex="-1">chunk 边界问题 <a class="header-anchor" href="#chunk-边界问题" aria-label="Permalink to &quot;chunk 边界问题&quot;"></a></h3><p><strong>已知边界</strong>：如果一个 <code>data: {...}</code> 事件跨 chunk 被截断，当前实现会解析失败（<code>JSON.parse</code> 抛错被 catch 吞掉）。数据库里丢一条 event 但不影响客户端流转发。项目里另有 <code>SSEAccumulator</code>（<code>utils/sse-accumulator.ts</code>）是完整的 Transform 流，但在 <code>proxy.ts</code> 当前路径中<strong>未启用</strong>。</p><h2 id="分支-3-error" tabindex="-1">分支 3：Error <a class="header-anchor" href="#分支-3-error" aria-label="Permalink to &quot;分支 3：Error&quot;"></a></h2><p><code>proxy.ts:428-456</code>：</p><ul><li>上游 <code>fetch</code> 抛错时命中</li><li><code>getErrorStatusCode</code>：<code>ECONNREFUSED</code> / <code>ENOTFOUND</code> → 502；<code>ETIMEDOUT</code> → 504；其它 → 500</li><li><code>getErrorMessage</code>：三选一或 <code>Proxy error</code></li><li>仍然 <code>pushNewRequest</code> 一条含错误 statusCode 的记录（供面板显示红色徽章）</li><li>响应体：<code>{ error, requestId }</code> JSON</li></ul><h2 id="关键决策" tabindex="-1">关键决策 <a class="header-anchor" href="#关键决策" aria-label="Permalink to &quot;关键决策&quot;"></a></h2><ul><li><strong>纯代理设计</strong>：<code>/v1/*</code> 不做任何请求体修改（除 model tier rewrite）、不注入 tool、不做 mock。所有增强逻辑放在 <code>/api/chat</code>。这让 <code>/v1/*</code> 成为零风险路径——客户端用它时 proxy 完全透明</li><li><strong><code>reply.hijack()</code> 的语义</strong>：Fastify 停止管你，包括路由响应、日志钩子、<code>onSend</code> hook。之后你必须自己 <code>reply.raw.end()</code>，否则连接挂着</li><li><strong>重新序列化 body</strong>：<code>fetch</code> 的 body 用 <code>JSON.stringify(request.body)</code>。这意味着如果客户端发送的 JSON 有非语义变化（空格、字段顺序），代理会「格式化」它。对语义无影响，但会影响某些希望做 body hash 的场景</li><li><strong>URL 拼接</strong>：<code>targetUrlStr = baseUrl + targetPath + request.url</code>。例如 <code>baseUrl=&#39;https://ark.cn-beijing.volces.com&#39;</code> + <code>targetPath=&#39;/api/coding&#39;</code> + <code>request.url=&#39;/v1/messages&#39;</code> = <code>https://ark.cn-beijing.volces.com/api/coding/v1/messages</code>。因此 provider 的 base_url 应写成含 API 前缀的形式</li><li><strong>一次请求两次 <code>Date.now()</code></strong>：<code>startTime</code> 在 handler 入口；SSE 分支的 <code>elapsed</code> 在 <code>end</code> 事件；同步分支（JSON）在 <code>send</code> 前。都体现 handler 视角的耗时</li><li><strong>Tier model fallback 链</strong>：<code>getProxyModel</code> 按 tier 映射，每个 tier 优先用专属 model（<code>haiku_model / sonnet_model / opus_model</code>），无专属 model 时 fallback 到通用 <code>model</code>，再 fallback 到不替换</li></ul>`,54)])])}const E=e(l,[["render",n]]);export{c as __pageData,E as default};

package/dist/docs/assets/proxy-core_proxy.md.CzQYmX6X.lean.js ADDED Viewed

@@ -0,0 +1 @@

+ import{_ as e,o as i,c as a,a2 as t}from"./chunks/framework.D_Xv2a7c.js";const c=JSON.parse('{"title":"proxy-core / 代理转发（/v1/* 纯代理路径）","description":"","frontmatter":{},"headers":[],"relativePath":"proxy-core/proxy.md","filePath":"proxy-core/proxy.md"}'),l={name:"proxy-core/proxy.md"};function n(d,s,o,h,p,r){return i(),a("div",null,[...s[0]||(s[0]=[t("",54)])])}const E=e(l,[["render",n]]);export{c as __pageData,E as default};