devinfra-bridge 0.1.0-alpha.1 → 0.1.0-alpha.2

package/README.md

@@ -4,14 +4,98 @@
 
 ## 开发与运行
 
+在仓库根目录执行，先用 `npm ci` 安装开发依赖。要求 Node.js >=22；启动命令的 `--config` 必须指向实际存在的绝对路径。
+
 ```bash
+cd ~/code/devinfra/devinfra_bridge
 npm ci
-npm run typecheck
-npm run lint
-npm test
+```
+
+### 命令速查
+
+| 功能 | 命令 | 行为与前置条件 |
+| --- | --- | --- |
+| 源码启动 | `npm run dev -- serve --config /absolute/path/bridge.json` | 用 tsx 前台运行最新 TS 源码，无需 build；不会自动监听文件变化或重启 |
+| 调试重启 | `./scripts/debug-daemon.sh [--config /absolute/path/bridge.json]` | 构建、校验配置后结束占用 18765 的进程，前台启动最新产物；首次自动生成默认配置；macOS/Linux，需要 lsof |
+| 类型检查 | `npm run typecheck` | 只检查类型，不生成产物 |
+| lint / 格式检查 | `npm run lint` | 检查 src、tests、scripts，不改文件 |
+| 格式化 / 自动修复 | `npm run format` | 写入格式调整和 Biome 可自动修复的内容 |
+| 全部测试 | `npm test` | 执行源码与集成测试，使用假 JWT 和本机 mock Gateway |
+| 构建最新代码 | `npm run build` | 重新生成 dist 中的 JS bundle 和类型声明 |
+| 构建产物启动 | `npm start -- serve --config /absolute/path/bridge.json` | 前台运行 dist/main.js；修改源码后先 build |
+| 文本版本 | `npm start -- --version` | 输出已构建产物的版本，无需配置文件 |
+| JSON 版本 | `npm start -- --version --json` | 输出 `{"version":"..."}`，无需配置文件 |
+| 打包运行验证 | `npm run smoke:artifact` | 先 build；npm pack 后临时解包，验证版本、启动、query 和 SIGTERM，不上传 npm |
+| 完整发布前检查 | `npm run prepublishOnly` | 顺序执行 typecheck → lint → test → build → smoke:artifact，不上传 npm |
+| 发布预演 | `npm run publish:dry` | 完整检查后列出包清单；允许当前功能分支，不上传、不要求 npm 登录 |
+
+测试与打包运行验证会监听本机端口；生命周期测试和 smoke 使用 18765，执行前需要停止该端口的调试 daemon。普通启动命令遇到端口占用会失败，不会终止占用进程。
+
+### 调试重启脚本
+
+```bash
+# 复用 ~/.local/state/devinfra-bridge/bridge.json；不存在时自动生成
+./scripts/debug-daemon.sh
+
+# 指定实际存在的绝对路径；支持含空格的路径
+./scripts/debug-daemon.sh --config "/absolute/path/bridge.json"
+
+# 首次生成配置时覆盖内置 Gateway（已有配置不会被覆盖）
+DEVINFRA_GATEWAY_ORIGIN=https://another-gateway.example ./scripts/debug-daemon.sh
+
+# 查看用法
+./scripts/debug-daemon.sh --help
+```
+
+设置 `DEVINFRA_BRIDGE_STATE_ROOT` 时，默认配置路径改为该目录下的 `bridge.json`。首次运行且默认文件不存在时，脚本自动生成配置（权限 0600），使用内置 Gateway 和 PATH 中的 bytedcli；不写入 JWT。已有配置保持不变；显式 `--config` 指向不存在的文件时仍报错。脚本不修改 CC 文件、不安装 Node 或依赖，首次使用先执行 `npm ci`。
+
+执行顺序：构建最新代码 → 必要时生成默认配置 → 校验运行时和配置 → 打印 TCP 18765 监听进程的 PID/进程名 → SIGTERM → 等待最多 12 秒 → 对仍监听的原进程 SIGKILL → 前台启动 `dist/main.js`。即使监听者不是 bridge，也会按该规则停止；权限不足或端口被其他新进程抢占时退出，不使用 sudo。构建或配置校验失败时保留当前进程。
+
+终端显示就绪/启动错误；请求日志写入配置 `state_root` 下的 `daemon.log`，省略 state_root 时为 `~/.local/state/devinfra-bridge/daemon.log`。Ctrl+C 停止 daemon。此脚本供本机开发调试，不包含在 npm 发布包中。
+
+### 请求日志与 Gateway LogID
+
+```bash
+tail -f ~/.local/state/devinfra-bridge/daemon.log
+```
+
+每条请求在完成或中断后写入日志（SSE 在流结束后）；字段包括：
+
+| 字段 | 含义 |
+| --- | --- |
+| `time` | 日志时间，UTC |
+| `request_id` | daemon 生成的本机 UUID，不是云端 LogID |
+| `gateway_logid` | Gateway 响应头 `x-tt-logid`，用于云端查日志 |
+| `gateway_request_id` | Gateway 响应头 `request-id` |
+| `gateway_x_request_id` | Gateway 响应头 `x-request-id` |
+| `path` / `status` / `duration_ms` / `code` | 路由、返回状态、耗时、本机错误码 |
+
+三个 Gateway ID 分别保存，不互相替代；云端未返回或值不符合长度/字符校验时省略。`x-tt-logid`、`request-id`、`x-request-id` 透传给客户端，仍遵守 HTTP connection header 的剥离规则。日志不记录 query 内容、JWT 或整组 headers，因此不能用 query 文本搜索历史请求。
+
+### 常用执行组合
+
+```bash
+# 直接运行最新源码
+npm run dev -- serve --config /absolute/path/bridge.json
+
+# 构建后运行，行为与发布包一致
 npm run build
+npm start -- serve --config /absolute/path/bridge.json
+
+# 也可直接调用服务入口
 node dist/main.js --version --json
 node dist/main.js serve --config /absolute/path/bridge.json
+
+# 一次完成全部本地检查、构建和打包运行验证
+npm run prepublishOnly
+```
+
+脚本本身也可直接执行（仍在仓库根目录）：
+
+```bash
+node scripts/test.mjs             # 等价于 npm test
+node scripts/build.mjs            # 等价于 npm run build
+node scripts/smoke-artifact.mjs   # 等价于 npm run smoke:artifact，先 build
 ```
 
 `bridge.json`：
@@ -19,7 +103,7 @@ node dist/main.js serve --config /absolute/path/bridge.json
 ```json
 {
   "config_version": 1,
-  "gateway_origin": "https://your-gateway.example",
+  "gateway_origin": "https://devinfra-llm-gateway.bytedance.net",
   "auth": {
     "mode": "bytedcli",
     "executable": "/absolute/path/bytedcli"
@@ -27,6 +111,8 @@ node dist/main.js serve --config /absolute/path/bridge.json
 }
 ```
 
+`gateway_origin` 可选，省略时使用内置 `https://devinfra-llm-gateway.bytedance.net`；显式配置优先。Messages 发往该 origin 下的 `/v1/messages`。`DEVINFRA_GATEWAY_ORIGIN` 只供调试脚本首次生成配置使用，daemon 本身不读取该环境变量。
+
 `state_root` 可选，默认 `~/.local/state/devinfra-bridge`。使用同一 OS 用户及其认证环境启动 daemon；bytedcli 子进程继承 `BYTEDCLI_CLOUD_SITE` / `BYTEDCLI_PROFILE`，无 site 覆盖，固定 `--as user`，不执行登录、不读取 refresh token。
 
 正常启动后 stdout 输出一行就绪 JSON。固定监听 `127.0.0.1:18765`；端口占用则退出。用 SIGINT/SIGTERM 停止，最多 10 秒排空 HTTP 请求，随后清理资源。
@@ -34,28 +120,52 @@ node dist/main.js serve --config /absolute/path/bridge.json
 ## 首版行为
 
 - 只转发 `POST /v1/messages`（可带 `?beta=true`）；原始 body、model、effort、thinking、工具字段、JSON/SSE 字节不转换。
-- 替换员工 JWT header，附加 `x-use-agent-plan: 1`、`X-Devinfra-Agent: claude-code`；剥离客户端 Authorization、x-api-key、Cookie 等凭据。
+- 注入 `x-use-agent-plan: 1`、`x-identity-token: <ByteCloud JWT>`、`x-identity-token-type: jwt`、`x-llm-app: devinfra-bridge:<agent>`；剥离客户端 Authorization、x-api-key、Cookie 等凭据。原有 `X-Devinfra-Agent: claude-code` 保留为本版路由标签。
 - `devinfra-bridge:cc` 是 CC 配置中的固定占位 token，本版不校验；来源 header 表示服务路由，不能证明发送进程身份。
 - 背压、取消、分阶段超时；401 等上游错误原样返回，模型请求不自动重试。
 - `/v1/models`、`count_tokens`、管理接口返回 404；CLI、安装、模型配置、配置恢复、目录查询由其他项目负责。
 
 更多见 [开发说明](docs/development.md)、[验收说明](docs/acceptance.md)和 [实施计划](docs/superpowers/plans/2026-11-09-cc-gateway-integration.md)。
 
+### 请求来源标记
+
+CLI 配置 agent 的占位凭据使用 `devinfra-bridge:{agent}`：CC 为 `devinfra-bridge:cc`，Codex 为 `devinfra-bridge:codex`，Hermes 为 `devinfra-bridge:hermes`，未知类型为 `devinfra-bridge:x`。CC 写在 settings.json 的 `env.ANTHROPIC_AUTH_TOKEN`；真实 JWT 只由 daemon 获取，不写入 agent 配置。
+
+daemon 优先读取 Authorization Bearer 中的标记，再读取 x-api-key；没有显式标记时，通过已知 User-Agent 和 Codex originator 兜底识别。未知标记或无法识别的客户端统一为 x；不按 Messages/Responses 协议推断 agent。新增类型需同步 `src/agents/identity.ts` 注册表。所有上游身份 header 由共用转发函数覆盖生成，这套规则供后续协议接入复用，当前仍只支持 Messages 路由。
+
+占位标记和客户端 header 都只用于来源统计，不认证发送进程；缺少或使用任意占位凭据不会被本机 daemon 拒绝。CLI 无需自行配置 Gateway 身份 header。
+
 ## npm 包与发布
 
 包名 `devinfra-bridge`，首版 `0.1.0-alpha.1`，MIT 许可证。发布到公网 npm 的 `alpha` 标签，供外部 CLI 联调；真实 CC + Gateway 验收见验收说明。
 
+所有发布脚本命令都会先执行完整检查；真实发布需 npm 公网登录凭据具有目标包写权限，并满足 2FA 要求。第一次发新包可通过账号登录并完成 2FA，或使用覆盖新包、启用 bypass 2FA 的 granular token；`npm whoami` 成功仅确认登录身份。
+
+| 执行方式 | 行为 |
+| --- | --- |
+| `./scripts/publish.sh --help` | 显示参数说明 |
+| `./scripts/publish.sh` | 从 main/master/develop 发布，检查通过后询问 y/N |
+| `./scripts/publish.sh --force` | 从当前功能分支发布，只跳过分支限制，仍检查并确认 |
+| `./scripts/publish.sh --dry-run` | 检查并列出包清单，不上传；保留分支限制 |
+| `./scripts/publish.sh --dry-run --force` | 功能分支发布预演，等价于 `npm run publish:dry` |
+| `./scripts/publish.sh --yes` | 跳过最终 y/N，仍检查分支及完整验证；可用于 CI |
+| `./scripts/publish.sh --force --yes` | 跳过分支限制和最终确认，检查通过后直接上传 |
+
 ```bash
-# 开发时验证发布产物，不上传；当前功能分支也能运行
-npm run publish:dry
+# 检查公网登录身份；缺少登录时按提示完成浏览器登录
+npm whoami --registry=https://registry.npmjs.org/
+npm login --auth-type=web --registry=https://registry.npmjs.org/
 
-# 在 main/master/develop 发布；脚本先检查，最后确认后才上传
-./scripts/publish.sh
+# 本机预演
+npm run publish:dry
 
-# 确认需要从其他分支发布时，只跳过分支检查
+# 当前功能分支发布；脚本最终会询问确认
 ./scripts/publish.sh --force
+
+# 发布成功后核对 alpha 标签
+npm view devinfra-bridge@alpha version --registry=https://registry.npmjs.org/
 ```
 
-脚本不会自动修改版本、暂存或提交。预发布版本自动使用 alpha/beta/rc/next 标签，正式版本使用 latest；检查包括 typecheck、lint、测试、构建与解包运行。`npm publish` 本身也通过 `prepublishOnly` 执行这些检查。
+发版只需手工修改 `package.json` 的 `version`；发布脚本以它为准，不要求 lockfile 根版本同步，仍校验 npm 包和构建产物版本。脚本不会自动修改版本、暂存或提交。预发布版本自动使用 alpha/beta/rc/next 标签，正式版本使用 latest；检查包括 typecheck、lint、测试、构建与解包运行。`npm publish` 本身也通过 `prepublishOnly` 执行这些检查。
 
 外部 CLI 可添加依赖 `devinfra-bridge@alpha`，通过 Node.js >=22 启动安装包中的 `dist/main.js serve --config ...`，或导入 `startDaemon`。本包没有 `bin` 命令，用户 CLI 在独立项目中提供。

package/dist/agents/identity.d.ts

@@ -0,0 +1,14 @@
+import type { IncomingHttpHeaders } from "node:http";
+declare const AGENT_IDENTITIES: readonly [{
+    readonly id: "cc";
+    readonly client: RegExp;
+}, {
+    readonly id: "codex";
+    readonly client: RegExp;
+}, {
+    readonly id: "hermes";
+    readonly client: RegExp;
+}];
+export type AgentIdentity = (typeof AGENT_IDENTITIES)[number]["id"] | "x";
+export declare function identifyAgent(headers: IncomingHttpHeaders): AgentIdentity;
+export {};

package/dist/agents/types.d.ts

@@ -1,8 +1,8 @@
-import type { IncomingMessage, ServerResponse } from "node:http";
+import type { IncomingHttpHeaders, IncomingMessage, ServerResponse } from "node:http";
 import type { ProxyContext } from "../proxy/server.js";
 export interface AgentRoute {
     agent: string;
     path: string;
     method: string;
-    forward(req: IncomingMessage, res: ServerResponse, context: ProxyContext, signal: AbortSignal, agent: string): Promise<void>;
+    forward(req: IncomingMessage, res: ServerResponse, context: ProxyContext, signal: AbortSignal, agent: string, onUpstreamHeaders?: (headers: IncomingHttpHeaders) => void): Promise<void>;
 }

package/dist/config/load.d.ts

@@ -1,4 +1,4 @@
-import type { DaemonConfig } from "./types.js";
+import { type DaemonConfig } from "./types.js";
 export declare class ConfigError extends Error {
     readonly code = "INVALID_CONFIG";
 }

package/dist/config/types.d.ts

@@ -1,3 +1,4 @@
+export declare const DEFAULT_GATEWAY_ORIGIN = "https://devinfra-llm-gateway.bytedance.net";
 export declare const HOST = "127.0.0.1";
 export declare const PORT = 18765;
 export declare const CC_PLACEHOLDER_TOKEN = "devinfra-bridge:cc";

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { assertSupportedNode, loadDaemonConfig, parseDaemonConfig } from "./config/load.js";
-export { CC_PLACEHOLDER_TOKEN, HOST, PORT } from "./config/types.js";
+export { CC_PLACEHOLDER_TOKEN, DEFAULT_GATEWAY_ORIGIN, HOST, PORT } from "./config/types.js";
 export type { AuthConfig, DaemonConfig } from "./config/types.js";
 export { startDaemon } from "./daemon/daemon.js";
 export type { DaemonHandle } from "./daemon/daemon.js";

package/dist/index.js

@@ -3,6 +3,21 @@ import { constants } from "node:fs";
 import { access, readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { extname, isAbsolute, join } from "node:path";
+
+// src/config/types.ts
+var DEFAULT_GATEWAY_ORIGIN = "https://devinfra-llm-gateway.bytedance.net";
+var HOST = "127.0.0.1";
+var PORT = 18765;
+var CC_PLACEHOLDER_TOKEN = "devinfra-bridge:cc";
+var DEFAULT_LIMITS = Object.freeze({
+  bodyBytes: 32 * 1024 * 1024,
+  bodyIdleMs: 6e4,
+  concurrency: 8,
+  headersMs: 12e4,
+  streamIdleMs: 12e4
+});
+
+// src/config/load.ts
 var ConfigError = class extends Error {
   code = "INVALID_CONFIG";
 };
@@ -27,14 +42,15 @@ function parseDaemonConfig(value) {
   const config = object(value);
   onlyKeys(config, ["config_version", "gateway_origin", "state_root", "auth"]);
   if (config.config_version !== 1) fail("Unsupported config_version; expected 1.");
-  if (typeof config.gateway_origin !== "string") fail("gateway_origin is required.");
+  const gatewayOrigin = config.gateway_origin === void 0 ? DEFAULT_GATEWAY_ORIGIN : config.gateway_origin;
+  if (typeof gatewayOrigin !== "string") fail("gateway_origin must be an HTTPS origin.");
   let origin;
   try {
-    origin = new URL(config.gateway_origin);
+    origin = new URL(gatewayOrigin);
   } catch {
     return fail("gateway_origin must be an HTTPS origin.");
   }
-  if (origin.protocol !== "https:" || origin.username || origin.password || origin.hash || origin.search || origin.pathname !== "/" || !/^https:\/\/[^/?#]+\/?$/.test(config.gateway_origin))
+  if (origin.protocol !== "https:" || origin.username || origin.password || origin.hash || origin.search || origin.pathname !== "/" || !/^https:\/\/[^/?#]+\/?$/.test(gatewayOrigin))
     fail("gateway_origin must be an HTTPS origin without credentials, path, query or fragment.");
   const rawAuth = object(config.auth);
   let auth;
@@ -93,18 +109,6 @@ function assertSupportedNode(version = process.versions.node) {
   }
 }
 
-// src/config/types.ts
-var HOST = "127.0.0.1";
-var PORT = 18765;
-var CC_PLACEHOLDER_TOKEN = "devinfra-bridge:cc";
-var DEFAULT_LIMITS = Object.freeze({
-  bodyBytes: 32 * 1024 * 1024,
-  bodyIdleMs: 6e4,
-  concurrency: 8,
-  headersMs: 12e4,
-  streamIdleMs: 12e4
-});
-
 // src/daemon/daemon.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
 
@@ -324,6 +328,33 @@ function sendError(res, error) {
   res.end(body);
 }
 
+// src/agents/identity.ts
+var AGENT_IDENTITIES = [
+  { id: "cc", client: /^claude-cli(?:\/|\s|$)/i },
+  {
+    id: "codex",
+    client: /^(?:codex(?:_cli_rs|_exec|_vscode| desktop)?|acp-extension-codex|vscode_agent_host)(?:\/|\s|$)/i
+  },
+  { id: "hermes", client: /^hermes-agent(?:\/|\s|$)/i }
+];
+function single(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+function identifyAgent(headers) {
+  const authorization = single(headers.authorization);
+  const bearer = /^Bearer\s+(.+)$/i.exec(authorization)?.[1] ?? "";
+  for (const token of [bearer, single(headers["x-api-key"])]) {
+    if (!token.startsWith("devinfra-bridge:")) continue;
+    const id = token.slice("devinfra-bridge:".length);
+    return AGENT_IDENTITIES.find((agent) => agent.id === id)?.id ?? "x";
+  }
+  for (const client of [single(headers["user-agent"]), single(headers.originator)]) {
+    const agent = AGENT_IDENTITIES.find((agent2) => agent2.client.test(client));
+    if (agent) return agent.id;
+  }
+  return "x";
+}
+
 // src/proxy/headers.ts
 var HOP = /* @__PURE__ */ new Set([
   "connection",
@@ -346,6 +377,7 @@ var REQUEST = /* @__PURE__ */ new Set([
   "request-id"
 ]);
 var RESPONSE = /* @__PURE__ */ new Set([
+  "x-tt-logid",
   "content-type",
   "content-encoding",
   "content-length",
@@ -367,8 +399,12 @@ function requestHeaders(incoming, jwt, bytes, agent) {
   }
   result["content-length"] = bytes;
   result["x-identity-token"] = jwt;
+  result["x-identity-token-type"] = "jwt";
   result["x-use-agent-plan"] = "1";
+  result["x-llm-app"] = `devinfra-bridge:${identifyAgent(incoming)}`;
   result["x-devinfra-agent"] = agent;
+  result["x-use-ppe"] = "1";
+  result["x-tt-env"] = "ppe_devinfra_bridge";
   return result;
 }
 function responseHeaders(incoming) {
@@ -430,7 +466,7 @@ async function readBody(req, context, signal) {
     if (signal.aborted) onAbort();
   });
 }
-async function forwardMessages(req, res, context, signal, agent) {
+async function forwardMessages(req, res, context, signal, agent, onUpstreamHeaders) {
   const body = await readBody(req, context, signal);
   try {
     const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(body);
@@ -479,6 +515,7 @@ async function forwardMessages(req, res, context, signal, agent) {
     });
     upstreamResponse = response;
     clearTimeout(headerTimer);
+    onUpstreamHeaders?.(response.headers);
     if ((response.statusCode ?? 502) >= 300 && (response.statusCode ?? 502) < 400) {
       response.destroy();
       throw new ProxyError(502, "UPSTREAM_REDIRECT", "Gateway redirection is not supported.");
@@ -558,6 +595,9 @@ import {
 import { join as join2 } from "node:path";
 var silentLogger = { write() {
 } };
+function safeTraceId(value) {
+  return typeof value === "string" && value.length <= 256 && /^[A-Za-z0-9]/.test(value) && !/[^A-Za-z0-9._:-]/.test(value) ? value : void 0;
+}
 function createLogger(stateRoot, maxBytes = 5 * 1024 * 1024) {
   const path = join2(stateRoot, "daemon.log");
   const safeFile = (file) => {
@@ -573,6 +613,9 @@ function createLogger(stateRoot, maxBytes = 5 * 1024 * 1024) {
           time: (/* @__PURE__ */ new Date()).toISOString(),
           event: record.event,
           request_id: record.request_id,
+          gateway_logid: safeTraceId(record.gateway_logid),
+          gateway_request_id: safeTraceId(record.gateway_request_id),
+          gateway_x_request_id: safeTraceId(record.gateway_x_request_id),
           path: record.path,
           duration_ms: record.duration_ms,
           status: record.status,
@@ -656,6 +699,7 @@ function createProxyHandler(context) {
       const started = Date.now();
       const requestId = randomUUID();
       let code;
+      let upstreamHeaders;
       const onAbort = () => controller.abort();
       const onClose = () => {
         if (!res.writableFinished) onAbort();
@@ -663,7 +707,9 @@ function createProxyHandler(context) {
       req.once("aborted", onAbort);
       res.once("close", onClose);
       try {
-        await route.forward(req, res, context, controller.signal, route.agent);
+        await route.forward(req, res, context, controller.signal, route.agent, (headers) => {
+          upstreamHeaders = headers;
+        });
       } catch (error) {
         const failure = error instanceof ProxyError ? error : new ProxyError(502, "PROXY_FAILURE", "Request forwarding failed.");
         code = failure.code;
@@ -675,6 +721,9 @@ function createProxyHandler(context) {
         context.logger.write({
           event: "request",
           request_id: requestId,
+          gateway_logid: safeTraceId(upstreamHeaders?.["x-tt-logid"]),
+          gateway_request_id: safeTraceId(upstreamHeaders?.["request-id"]),
+          gateway_x_request_id: safeTraceId(upstreamHeaders?.["x-request-id"]),
           path: "/v1/messages",
           duration_ms: Date.now() - started,
           status: res.statusCode,
@@ -722,7 +771,7 @@ async function prepareStateRoot(path) {
 }
 
 // src/version.ts
-var VERSION = true ? "0.1.0-alpha.1" : "0.1.0-dev";
+var VERSION = true ? "0.1.0-alpha.2" : "0.1.0-dev";
 
 // src/daemon/single-instance.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
@@ -826,6 +875,7 @@ async function startDaemon(config) {
 }
 export {
   CC_PLACEHOLDER_TOKEN,
+  DEFAULT_GATEWAY_ORIGIN,
   HOST,
   PORT,
   assertSupportedNode,

package/dist/main.js

@@ -3,6 +3,20 @@ import { constants } from "node:fs";
 import { access, readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { extname, isAbsolute, join } from "node:path";
+
+// src/config/types.ts
+var DEFAULT_GATEWAY_ORIGIN = "https://devinfra-llm-gateway.bytedance.net";
+var HOST = "127.0.0.1";
+var PORT = 18765;
+var DEFAULT_LIMITS = Object.freeze({
+  bodyBytes: 32 * 1024 * 1024,
+  bodyIdleMs: 6e4,
+  concurrency: 8,
+  headersMs: 12e4,
+  streamIdleMs: 12e4
+});
+
+// src/config/load.ts
 var ConfigError = class extends Error {
   code = "INVALID_CONFIG";
 };
@@ -27,14 +41,15 @@ function parseDaemonConfig(value) {
   const config = object(value);
   onlyKeys(config, ["config_version", "gateway_origin", "state_root", "auth"]);
   if (config.config_version !== 1) fail("Unsupported config_version; expected 1.");
-  if (typeof config.gateway_origin !== "string") fail("gateway_origin is required.");
+  const gatewayOrigin = config.gateway_origin === void 0 ? DEFAULT_GATEWAY_ORIGIN : config.gateway_origin;
+  if (typeof gatewayOrigin !== "string") fail("gateway_origin must be an HTTPS origin.");
   let origin;
   try {
-    origin = new URL(config.gateway_origin);
+    origin = new URL(gatewayOrigin);
   } catch {
     return fail("gateway_origin must be an HTTPS origin.");
   }
-  if (origin.protocol !== "https:" || origin.username || origin.password || origin.hash || origin.search || origin.pathname !== "/" || !/^https:\/\/[^/?#]+\/?$/.test(config.gateway_origin))
+  if (origin.protocol !== "https:" || origin.username || origin.password || origin.hash || origin.search || origin.pathname !== "/" || !/^https:\/\/[^/?#]+\/?$/.test(gatewayOrigin))
     fail("gateway_origin must be an HTTPS origin without credentials, path, query or fragment.");
   const rawAuth = object(config.auth);
   let auth;
@@ -277,17 +292,6 @@ function createCredentialProvider(config) {
   return config.mode === "bytedcli" ? new BytedcliProvider(config.executable) : new DirectJwtProvider(config);
 }
 
-// src/config/types.ts
-var HOST = "127.0.0.1";
-var PORT = 18765;
-var DEFAULT_LIMITS = Object.freeze({
-  bodyBytes: 32 * 1024 * 1024,
-  bodyIdleMs: 6e4,
-  concurrency: 8,
-  headersMs: 12e4,
-  streamIdleMs: 12e4
-});
-
 // src/proxy/server.ts
 import { randomUUID } from "node:crypto";
 import { createServer } from "node:http";
@@ -323,6 +327,33 @@ function sendError(res, error) {
   res.end(body);
 }
 
+// src/agents/identity.ts
+var AGENT_IDENTITIES = [
+  { id: "cc", client: /^claude-cli(?:\/|\s|$)/i },
+  {
+    id: "codex",
+    client: /^(?:codex(?:_cli_rs|_exec|_vscode| desktop)?|acp-extension-codex|vscode_agent_host)(?:\/|\s|$)/i
+  },
+  { id: "hermes", client: /^hermes-agent(?:\/|\s|$)/i }
+];
+function single(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+function identifyAgent(headers) {
+  const authorization = single(headers.authorization);
+  const bearer = /^Bearer\s+(.+)$/i.exec(authorization)?.[1] ?? "";
+  for (const token of [bearer, single(headers["x-api-key"])]) {
+    if (!token.startsWith("devinfra-bridge:")) continue;
+    const id = token.slice("devinfra-bridge:".length);
+    return AGENT_IDENTITIES.find((agent) => agent.id === id)?.id ?? "x";
+  }
+  for (const client of [single(headers["user-agent"]), single(headers.originator)]) {
+    const agent = AGENT_IDENTITIES.find((agent2) => agent2.client.test(client));
+    if (agent) return agent.id;
+  }
+  return "x";
+}
+
 // src/proxy/headers.ts
 var HOP = /* @__PURE__ */ new Set([
   "connection",
@@ -345,6 +376,7 @@ var REQUEST = /* @__PURE__ */ new Set([
   "request-id"
 ]);
 var RESPONSE = /* @__PURE__ */ new Set([
+  "x-tt-logid",
   "content-type",
   "content-encoding",
   "content-length",
@@ -366,8 +398,12 @@ function requestHeaders(incoming, jwt, bytes, agent) {
   }
   result["content-length"] = bytes;
   result["x-identity-token"] = jwt;
+  result["x-identity-token-type"] = "jwt";
   result["x-use-agent-plan"] = "1";
+  result["x-llm-app"] = `devinfra-bridge:${identifyAgent(incoming)}`;
   result["x-devinfra-agent"] = agent;
+  result["x-use-ppe"] = "1";
+  result["x-tt-env"] = "ppe_devinfra_bridge";
   return result;
 }
 function responseHeaders(incoming) {
@@ -429,7 +465,7 @@ async function readBody(req, context, signal) {
     if (signal.aborted) onAbort();
   });
 }
-async function forwardMessages(req, res, context, signal, agent) {
+async function forwardMessages(req, res, context, signal, agent, onUpstreamHeaders) {
   const body = await readBody(req, context, signal);
   try {
     const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(body);
@@ -478,6 +514,7 @@ async function forwardMessages(req, res, context, signal, agent) {
     });
     upstreamResponse = response;
     clearTimeout(headerTimer);
+    onUpstreamHeaders?.(response.headers);
     if ((response.statusCode ?? 502) >= 300 && (response.statusCode ?? 502) < 400) {
       response.destroy();
       throw new ProxyError(502, "UPSTREAM_REDIRECT", "Gateway redirection is not supported.");
@@ -557,6 +594,9 @@ import {
 import { join as join2 } from "node:path";
 var silentLogger = { write() {
 } };
+function safeTraceId(value) {
+  return typeof value === "string" && value.length <= 256 && /^[A-Za-z0-9]/.test(value) && !/[^A-Za-z0-9._:-]/.test(value) ? value : void 0;
+}
 function createLogger(stateRoot, maxBytes = 5 * 1024 * 1024) {
   const path = join2(stateRoot, "daemon.log");
   const safeFile = (file) => {
@@ -572,6 +612,9 @@ function createLogger(stateRoot, maxBytes = 5 * 1024 * 1024) {
           time: (/* @__PURE__ */ new Date()).toISOString(),
           event: record.event,
           request_id: record.request_id,
+          gateway_logid: safeTraceId(record.gateway_logid),
+          gateway_request_id: safeTraceId(record.gateway_request_id),
+          gateway_x_request_id: safeTraceId(record.gateway_x_request_id),
           path: record.path,
           duration_ms: record.duration_ms,
           status: record.status,
@@ -655,6 +698,7 @@ function createProxyHandler(context) {
       const started = Date.now();
       const requestId = randomUUID();
       let code;
+      let upstreamHeaders;
       const onAbort = () => controller.abort();
       const onClose = () => {
         if (!res.writableFinished) onAbort();
@@ -662,7 +706,9 @@ function createProxyHandler(context) {
       req.once("aborted", onAbort);
       res.once("close", onClose);
       try {
-        await route.forward(req, res, context, controller.signal, route.agent);
+        await route.forward(req, res, context, controller.signal, route.agent, (headers) => {
+          upstreamHeaders = headers;
+        });
       } catch (error) {
         const failure = error instanceof ProxyError ? error : new ProxyError(502, "PROXY_FAILURE", "Request forwarding failed.");
         code = failure.code;
@@ -674,6 +720,9 @@ function createProxyHandler(context) {
         context.logger.write({
           event: "request",
           request_id: requestId,
+          gateway_logid: safeTraceId(upstreamHeaders?.["x-tt-logid"]),
+          gateway_request_id: safeTraceId(upstreamHeaders?.["request-id"]),
+          gateway_x_request_id: safeTraceId(upstreamHeaders?.["x-request-id"]),
           path: "/v1/messages",
           duration_ms: Date.now() - started,
           status: res.statusCode,
@@ -721,7 +770,7 @@ async function prepareStateRoot(path) {
 }
 
 // src/version.ts
-var VERSION = true ? "0.1.0-alpha.1" : "0.1.0-dev";
+var VERSION = true ? "0.1.0-alpha.2" : "0.1.0-dev";
 
 // src/daemon/single-instance.ts
 import { randomUUID as randomUUID2 } from "node:crypto";

package/dist/proxy/forward-messages.d.ts

@@ -1,3 +1,3 @@
-import type { IncomingMessage, ServerResponse } from "node:http";
+import type { IncomingHttpHeaders, IncomingMessage, ServerResponse } from "node:http";
 import type { ProxyContext } from "./server.js";
-export declare function forwardMessages(req: IncomingMessage, res: ServerResponse, context: ProxyContext, signal: AbortSignal, agent: string): Promise<void>;
+export declare function forwardMessages(req: IncomingMessage, res: ServerResponse, context: ProxyContext, signal: AbortSignal, agent: string, onUpstreamHeaders?: (headers: IncomingHttpHeaders) => void): Promise<void>;

package/dist/util/logger.d.ts

@@ -1,6 +1,9 @@
 export interface LogRecord {
     event: "request" | "ready" | "stopped" | "shutdown_error";
     request_id?: string;
+    gateway_logid?: string;
+    gateway_request_id?: string;
+    gateway_x_request_id?: string;
     path?: "/v1/messages";
     duration_ms?: number;
     status?: number;
@@ -10,4 +13,5 @@ export interface Logger {
     write(record: LogRecord): void;
 }
 export declare const silentLogger: Logger;
+export declare function safeTraceId(value: unknown): string | undefined;
 export declare function createLogger(stateRoot: string, maxBytes?: number): Logger;

package/docs/acceptance.md

@@ -20,9 +20,9 @@
 | 命令 | 结果 |
 | --- | --- |
 | `npm run typecheck` | 通过 |
-| `npm run lint` | 通过，30 个源码/测试/脚本文件 |
+| `npm run lint` | 通过，32 个源码/测试/脚本文件 |
 | `npm run build` | 通过，JS bundle 和类型声明已生成 |
-| `npm test` | 31 项通过，0 失败/跳过 |
+| `npm test` | 35 项通过，0 失败/跳过 |
 | `npm run smoke:artifact` | 通过：打包、临时解包、版本、启动、query、SIGTERM；无需安装生产依赖 |
 | `git diff --check` | 通过 |
 
@@ -37,6 +37,16 @@
 新增 5 项回归测试，连同既有测试共 31 项全部通过。上述 typecheck、lint、build、smoke 和 diff 检查均已在修复后的实际仓库重新执行。
 
 
+## 共用身份 header 与来源标记验收
+
+2026-11-09 在 macOS / Node.js 22.22.3 重新执行 typecheck、lint、35 项测试、build 与 artifact smoke，全部通过；未发布 npm 包。
+
+- 固定注入 `x-use-agent-plan: 1`、`x-identity-token-type: jwt`，JWT 来自 daemon 凭据源，`x-llm-app` 由来源识别生成，客户端同名 header 无法覆盖。
+- 优先读取 Authorization Bearer / x-api-key 的 `devinfra-bridge:{agent}`；显式标记优先于原生客户端 header，未知标记统一 x。无标记时识别已知 User-Agent / Codex originator，通用 SDK 或未知客户端统一 x。
+- 同一个 Messages 路由分别标记 cc/codex/hermes；未带占位 key 的请求仍正常工作并标记 x，不因协议被强制归为 cc。
+- 普通请求、工具多轮、SSE 和解包产物均验证新增 header，原始 body 与响应保持不变；新增 4 项测试，总计 35 项。
+- 现有 `X-Devinfra-Agent: claude-code` 保留为本版路由标签，来源统计使用新的 x-llm-app。来源标签不是本机鉴权；本期未增加 Responses/Codex 专属路由。
+
 ## 尚未进行的真实全链路验收
 
 需要真实 Gateway HTTPS origin、员工 JWT-only Messages 能力、测试模型及外部准备好的 CC 配置。mock 通过不代表真实 CC + Gateway 已验收。

package/docs/development.md

@@ -23,7 +23,7 @@ flowchart LR
 
 ## 外部启动方
 
-本工程交付 `dist/main.js` 与可导入的 `dist/index.js` / 类型声明，不提供用户 setup/disable 命令或 HTTP 管理 API。CLI/安装器准备 Node.js >=22、bytedcli、Gateway 地址、CC 文件并管理进程。运行时仅拒绝低于 22 的 Node 版本；当前实际验收环境为 Node.js 22，构建目标保留 node22。
+本工程交付 `dist/main.js` 与可导入的 `dist/index.js` / 类型声明，不提供用户 setup/disable 命令或 HTTP 管理 API。CLI/安装器准备 Node.js >=22、bytedcli、CC 文件并管理进程。运行时仅拒绝低于 22 的 Node 版本；当前实际验收环境为 Node.js 22，构建目标保留 node22。
 
 ```bash
 node /absolute/path/dist/main.js serve --config /absolute/path/bridge.json
@@ -32,16 +32,42 @@ node /absolute/path/dist/main.js serve --config /absolute/path/bridge.json
 ```json
 {
   "config_version": 1,
-  "gateway_origin": "https://your-gateway.example",
+  "gateway_origin": "https://devinfra-llm-gateway.bytedance.net",
   "state_root": "/absolute/path/user-state",
   "auth": {"mode": "bytedcli", "executable": "/absolute/path/bytedcli"}
 }
 ```
 
+`gateway_origin` 可选，默认 `https://devinfra-llm-gateway.bytedance.net`；配置中显式值优先。Messages 请求路径为 `/v1/messages`，不在 origin 中添加协议路径。
+
 bytedcli 参数固定为 `--no-auto-upgrade --json --as user auth get-bytecloud-jwt-token`。可执行入口支持绝对 native executable 路径，或 `.js/.mjs/.cjs`（由当前 Node 执行）；不执行 `.cmd/.bat` 包装脚本，不启用 shell。Windows 的实际入口路径和三平台安装验收由后续迭代对齐。
 
 bytedcli 默认获取/续取凭据。首版不自动在 Gateway 401 后强制刷新并重发模型请求。JWT 仅在内存存放，缓存最多 60 秒且不跨 `exp`（留 5 秒余量）；不解析身份，不验签，Gateway 最终授权。
 
+### 共用 Gateway header 与 agent 识别
+
+`src/proxy/headers.ts` 为所有模型协议提供同一个请求 header 构造函数：
+
+```http
+x-use-agent-plan: 1
+x-identity-token: <ByteCloud JWT>
+x-identity-token-type: jwt
+x-llm-app: devinfra-bridge:cc
+```
+
+前两项固定注入策略不变，token-type 固定为 jwt，llm-app 的后缀来自 `src/agents/identity.ts`，均覆盖客户端同名字段。客户端 Authorization、x-api-key 和 Cookie 仍剥离。已有 `X-Devinfra-Agent: claude-code` 保留其本版路由标签语义；新的 x-llm-app 表示识别出的请求来源，不能据路由标签把所有 Messages 都算作 CC。
+
+| 顺序 | 识别依据 | 结果 |
+| --- | --- | --- |
+| 1 | Authorization Bearer 中的 `devinfra-bridge:{agent}` | 注册的 cc/codex/hermes；x 或未注册名称统一 x |
+| 2 | x-api-key 中的同格式标记 | 同上；Authorization 中的显式标记优先 |
+| 3 | 已知 User-Agent；再看 originator | claude-cli → cc；Codex CLI/exec/VS Code/Desktop/ACP/VS Code agent host 名称 → codex；hermes-agent → hermes |
+| 4 | 缺少、通用 SDK/HTTP 库或无法识别的标识 | x |
+
+显式 x 或未注册标记不再回退猜测；UA 按注册的客户端名称边界匹配，避免把相似产品名误识别。此判断不依赖请求 body、模型名或协议，也不查询本机进程。占位凭据仍不作鉴权，所有标识都是来源统计线索。
+
+外部 CLI 将 CC 的 `env.ANTHROPIC_AUTH_TOKEN` 设为 `devinfra-bridge:cc`，后续 agent 使用相应标记。CLI 不写真实 JWT、不注入上述 Gateway header；新增 agent 同步注册表与配置实现。识别 codex/hermes 不表示已支持它们的其他协议，本期只有 Messages，后续 handler 必须复用该共用 header 函数。
+
 若由外部提供已有 JWT，将 `auth` 替换为其一：
 
 ```json
@@ -58,7 +84,7 @@ bytedcli 默认获取/续取凭据。首版不自动在 Gateway 401 后强制刷
 
 - 就绪输出：`{"event":"ready","version":"0.1.0-alpha.1","instance_id":"...","host":"127.0.0.1","port":18765}`。
 - TCP 独占绑定是单实例锁；`instance.json` 只是诊断信息，不据此杀进程。崩溃遗留标记不阻止重启；仅绑定成功后替换标记。
-- 日志 `daemon.log` + 两个轮转文件，每个约 5 MiB；只含内部请求 ID、固定路由、耗时、状态和归一化错误码。
+- 日志 `daemon.log` + 两个轮转文件，每个约 5 MiB；包含内部 `request_id`、Gateway 响应中的 `gateway_logid`（x-tt-logid）、`gateway_request_id`（request-id）、`gateway_x_request_id`（x-request-id）、固定路由、耗时、状态和归一化错误码。请求完成/中断后记录；Gateway ID 缺失或不是 1–256 字符的字母数字及 `._:-` token 时省略。对应三个响应头透传给客户端；不记录 query/JWT/整组 headers。
 - Body 最大 32 MiB、读取空闲 60 秒；并发最多 8；上游头等待和流空闲各 120 秒，无整体流总时限。
 - 输入必须为未压缩 JSON；不重序列化。响应不解压，保留编码及有效长度。
 - HTTPS 不跟随重定向；TLS 验证保持开启。企业 CA 用启动环境 `NODE_EXTRA_CA_CERTS`。首版不支持显式 HTTPS_PROXY 传输。
@@ -92,6 +118,6 @@ npm run publish:dry                 # 全量验证、列出包内容，不上传
 
 `--yes` 可跳过最后的发布确认；`--dry-run --force` 可在功能分支验证。真实发布前检查 npm 公网登录态；如未登录，运行 `npm login --registry=https://registry.npmjs.org/`。npm 要求额外认证时按提示完成。
 
-版本需手工更新 package.json 和 package-lock.json 并由开发者决定何时提交；发布脚本不自动 bump 或提交。`prepublishOnly` 包含类型检查、lint、测试、build 与 artifact smoke，后者会核对打包版本和 bundle 版本，确保生产依赖为零时仍可运行。发布脚本显式执行该检查后再确认上传，因此最终 publish 使用 `--ignore-scripts` 避免重复执行。
+发版版本以 package.json 为准，只需手工修改其中的 version，不要求 package-lock.json 根版本同步；依赖变更时仍正常更新 lockfile。开发者自行决定何时提交，发布脚本不自动 bump 或提交。`prepublishOnly` 包含类型检查、lint、测试、build 与 artifact smoke，后者会核对打包版本和 bundle 版本，确保生产依赖为零时仍可运行。发布脚本显式执行该检查后再确认上传，因此最终 publish 使用 `--ignore-scripts` 避免重复执行。
 
 alpha/beta/rc 版本对应同名 dist-tag，其他预发布版本使用 next，正式版本使用 latest。本期先发布 alpha 包给 CLI 项目联调，真实 CC + Gateway 未验收完成前不作为正式稳定版。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devinfra-bridge",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "description": "Local Messages proxy daemon for devinfra llm gateway",
   "type": "module",
   "engines": {