devinfra-bridge 0.0.0-stage → 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 devinfra-bridge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,171 @@
-# Temporary Holding Version
+# devinfra_bridge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+本机 proxy daemon：接收 Claude Code 的原生 Messages 请求，附加机器已有的 ByteCloud JWT，转发到固定 llm gateway。使用 TypeScript，要求 Node.js >=22；无生产 npm 依赖。当前实际验收环境为 Node.js 22，构建目标为 node22。
+
+## 开发与运行
+
+在仓库根目录执行，先用 `npm ci` 安装开发依赖。要求 Node.js >=22；启动命令的 `--config` 必须指向实际存在的绝对路径。
+
+```bash
+cd ~/code/devinfra/devinfra_bridge
+npm ci
+```
+
+### 命令速查
+
+| 功能 | 命令 | 行为与前置条件 |
+| --- | --- | --- |
+| 源码启动 | `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`：
+
+```json
+{
+  "config_version": 1,
+  "gateway_origin": "https://devinfra-llm-gateway.bytedance.net",
+  "auth": {
+    "mode": "bytedcli",
+    "executable": "/absolute/path/bytedcli"
+  }
+}
+```
+
+`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 请求，随后清理资源。
+
+## 首版行为
+
+- 只转发 `POST /v1/messages`（可带 `?beta=true`）；原始 body、model、effort、thinking、工具字段、JSON/SSE 字节不转换。
+- 注入 `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 whoami --registry=https://registry.npmjs.org/
+npm login --auth-type=web --registry=https://registry.npmjs.org/
+
+# 本机预演
+npm run publish:dry
+
+# 当前功能分支发布；脚本最终会询问确认
+./scripts/publish.sh --force
+
+# 发布成功后核对 alpha 标签
+npm view devinfra-bridge@alpha version --registry=https://registry.npmjs.org/
+```
+
+发版只需手工修改 `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/registry.d.ts

@@ -0,0 +1,2 @@
+import type { AgentRoute } from "./types.js";
+export declare const AGENT_ROUTES: readonly AgentRoute[];

package/dist/agents/types.d.ts

@@ -0,0 +1,8 @@
+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, onUpstreamHeaders?: (headers: IncomingHttpHeaders) => void): Promise<void>;
+}

package/dist/auth/bytedcli-provider.d.ts

@@ -0,0 +1,22 @@
+import { type CredentialProvider } from "./credential-provider.js";
+export declare const JWT_ARGS: string[];
+export interface BytedcliOptions {
+    timeoutMs?: number;
+    outputBytes?: number;
+    cacheMs?: number;
+}
+export declare class BytedcliProvider implements CredentialProvider {
+    private readonly executable;
+    private readonly controller;
+    private pending?;
+    private cached?;
+    private readonly timeoutMs;
+    private readonly outputBytes;
+    private readonly cacheMs;
+    constructor(executable: string, options?: BytedcliOptions);
+    getJwt({ signal }?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    private acquire;
+    close(): Promise<void>;
+}

package/dist/auth/credential-provider.d.ts

@@ -0,0 +1,13 @@
+import type { AuthConfig } from "../config/types.js";
+export interface CredentialProvider {
+    getJwt(options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    close(): Promise<void>;
+}
+export declare class CredentialError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+export declare function validateJwt(value: unknown): string;
+export declare function createCredentialProvider(config: AuthConfig): CredentialProvider;

package/dist/auth/direct-jwt-provider.d.ts

@@ -0,0 +1,14 @@
+import type { AuthConfig } from "../config/types.js";
+import { type CredentialProvider } from "./credential-provider.js";
+export declare class DirectJwtProvider implements CredentialProvider {
+    private readonly config;
+    private closed;
+    private readonly snapshot?;
+    constructor(config: Exclude<AuthConfig, {
+        mode: "bytedcli";
+    }>);
+    getJwt({ signal }?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    close(): Promise<void>;
+}

package/dist/config/load.d.ts

@@ -0,0 +1,7 @@
+import { type DaemonConfig } from "./types.js";
+export declare class ConfigError extends Error {
+    readonly code = "INVALID_CONFIG";
+}
+export declare function parseDaemonConfig(value: unknown): DaemonConfig;
+export declare function loadDaemonConfig(path: string): Promise<DaemonConfig>;
+export declare function assertSupportedNode(version?: string): void;

package/dist/config/types.d.ts

@@ -0,0 +1,28 @@
+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";
+export type AuthConfig = {
+    mode: "bytedcli";
+    executable: string;
+} | {
+    mode: "direct-jwt";
+    file: string;
+} | {
+    mode: "direct-jwt";
+    env: string;
+};
+export interface DaemonConfig {
+    configVersion: 1;
+    gatewayOrigin: string;
+    stateRoot: string;
+    auth: AuthConfig;
+}
+export interface ProxyLimits {
+    bodyBytes: number;
+    bodyIdleMs: number;
+    concurrency: number;
+    headersMs: number;
+    streamIdleMs: number;
+}
+export declare const DEFAULT_LIMITS: Readonly<ProxyLimits>;

package/dist/daemon/daemon.d.ts

@@ -0,0 +1,10 @@
+import { type DaemonConfig, HOST, PORT } from "../config/types.js";
+export interface DaemonHandle {
+    instanceId: string;
+    host: typeof HOST;
+    port: typeof PORT;
+    close(options?: {
+        drainMs?: number;
+    }): Promise<void>;
+}
+export declare function startDaemon(config: DaemonConfig): Promise<DaemonHandle>;

package/dist/daemon/single-instance.d.ts

@@ -0,0 +1,3 @@
+import type { Server } from "node:http";
+export declare function bindSingleInstance(server: Server): Promise<void>;
+export declare function writeInstance(stateRoot: string, id: string, version: string): Promise<() => Promise<void>>;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { assertSupportedNode, loadDaemonConfig, parseDaemonConfig } from "./config/load.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";
+export type { CredentialProvider } from "./auth/credential-provider.js";