@wallbreakerno4/opencode-commandcode 0.1.0

package/dist/disguise/fingerprint.js

@@ -0,0 +1,127 @@
+/**
+ * 设备指纹（disguise.md §8，#9 校准后如实上报真机真值）。
+ *
+ * - 15 字段 components 结构、thumbmark 联合哈希的拼接序与「五字段不入哈希」结构
+ *   照抄调研 §1.2–§1.3（服务端无从校验原像，结构同构无成本）；
+ * - 输入换成真机真值：platform / 内核版本 / CPU / 内存 / 时区 / 网卡——真机真值
+ *   天然确定，指纹跨进程稳定随之免费获得（MAXeaglet 的 win32 随机池假人格弃用）；
+ * - 采集器直接读系统 API（testing.md §1.5：不单测、不抽象注入接口，正确性归
+ *   真机人工验收）；哈希纯函数照测（注入固定输入）。
+ */
+import { exec } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import os from "node:os";
+import { promisify } from "node:util";
+import { sha256Hex } from "./hash.js";
+const execAsync = promisify(exec);
+/**
+ * 采集命令（ioreg / reg query / git config）的防御超时，到点按失败处理。取值与
+ * §11 参数速查的「git 查询防御超时」同参数（2s/条）同理由（纯客户端防御）；
+ * 官方无指纹采集器可照抄，此为采集实现自身的防御决策。
+ */
+const COLLECT_COMMAND_TIMEOUT_MS = 2000;
+/**
+ * thumbmark 联合哈希：参与字段为 machineIdHash → macHashes（按序全部）→ osUserHash
+ * → hostnameHash → gitEmailHash → platform → osRelease → cpuModel → cpuCount →
+ * memGiB，分隔符 `|`；arch / timezone / isContainer / runtime / collectorVersion
+ * 五字段不入哈希（调研 §1.3，原样保留该实现取舍）。
+ */
+export function computeThumbmark(components) {
+    const thumbData = [
+        components.machineIdHash,
+        ...components.macHashes,
+        components.osUserHash,
+        components.hostnameHash,
+        components.gitEmailHash,
+        components.platform,
+        components.osRelease,
+        components.cpuModel,
+        String(components.cpuCount),
+        String(components.memGiB),
+    ].join("|");
+    return sha256Hex(thumbData);
+}
+/** 组装 record body：thumbmark 重算，components 原样搬运 */
+export function buildFingerprintBody(components) {
+    return { thumbmark: computeThumbmark(components), components };
+}
+async function runCapture(command) {
+    try {
+        const { stdout } = await execAsync(command, { signal: AbortSignal.timeout(COLLECT_COMMAND_TIMEOUT_MS), windowsHide: true });
+        return stdout.trim();
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * machineId 原像：跨重启稳定的机器标识。Linux 读 /etc/machine-id，macOS 读
+ * IOPlatformUUID，Windows 读注册表 MachineGuid；取不到时退 hostname 拼接串——
+ * 服务端无从校验原像（调研 §1.2），只需保证 64hex 形状与跨进程稳定。
+ */
+async function machineIdSeed(hostname) {
+    if (process.platform === "linux") {
+        const id = await readFile("/etc/machine-id", "utf8").then((raw) => raw.trim()).catch(() => "");
+        if (id)
+            return id;
+    }
+    if (process.platform === "darwin") {
+        const out = await runCapture("ioreg -rd1 -c IOPlatformExpertDevice");
+        const uuid = /"IOPlatformUUID"\s*=\s*"([^"]+)"/.exec(out)?.[1];
+        if (uuid)
+            return uuid;
+    }
+    if (process.platform === "win32") {
+        const out = await runCapture("reg query HKLM\\SOFTWARE\\Microsoft\\Cryptography /v MachineGuid");
+        const guid = /MachineGuid\s+REG_SZ\s+(\S+)/.exec(out)?.[1];
+        if (guid)
+            return guid;
+    }
+    return `machine-id:${hostname}`;
+}
+/** macHashes 按真实网卡数量生成（#9：多网卡主机 29 个）——非 internal 接口逐个入哈希 */
+function macSeeds() {
+    const seeds = [];
+    for (const interfaces of Object.values(os.networkInterfaces())) {
+        for (const iface of interfaces ?? []) {
+            if (!iface.internal)
+                seeds.push(iface.mac);
+        }
+    }
+    return seeds;
+}
+/** 采集真机真值并计算各字段哈希与 thumbmark；进程启动时调用一次（disguise.md §1） */
+export async function collectFingerprintComponents() {
+    const hostname = os.hostname();
+    const [machineIdSeedValue, gitEmail] = await Promise.all([
+        machineIdSeed(hostname),
+        runCapture("git config --get user.email"),
+    ]);
+    // 无 passwd 条目的环境（个别容器）会抛错，退环境变量兜底
+    let username = "";
+    try {
+        username = os.userInfo().username;
+    }
+    catch {
+        username = process.env["USER"] ?? process.env["USERNAME"] ?? "";
+    }
+    const components = {
+        machineIdHash: sha256Hex(machineIdSeedValue),
+        macHashes: macSeeds().map(sha256Hex),
+        osUserHash: sha256Hex(username),
+        hostnameHash: sha256Hex(hostname),
+        gitEmailHash: sha256Hex(gitEmail),
+        platform: process.platform,
+        arch: process.arch,
+        osRelease: os.release(),
+        cpuModel: os.cpus()[0]?.model ?? "",
+        cpuCount: os.cpus().length,
+        memGiB: Math.round(os.totalmem() / 2 ** 30),
+        // 抓包样本恒 false（§11.3），真实 CLI 的检测语义无从考证，照抄观测值
+        isContainer: false,
+        timezone: Intl.DateTimeFormat().resolvedOptions().timeZone ?? "UTC",
+        runtime: "cli",
+        collectorVersion: 1,
+    };
+    return components;
+}

package/dist/disguise/hash.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 伪装模块共用哈希原语（调研 §1.2 的 sha256 辅助函数）：
+ * `sha256(s) = hex(sha256(utf8(s)))`，输出 64 位小写 hex。
+ */
+/** sha256(utf8(input)) → 64 位小写 hex */
+export declare function sha256Hex(input: string): string;
+/** sha256(utf8(input)) 的 32 字节摘要，供截取与位修补类派生（会话 id、slug 字节流）使用 */
+export declare function sha256Digest(input: string): Buffer;

package/dist/disguise/hash.js

@@ -0,0 +1,13 @@
+/**
+ * 伪装模块共用哈希原语（调研 §1.2 的 sha256 辅助函数）：
+ * `sha256(s) = hex(sha256(utf8(s)))`，输出 64 位小写 hex。
+ */
+import { createHash } from "node:crypto";
+/** sha256(utf8(input)) → 64 位小写 hex */
+export function sha256Hex(input) {
+    return createHash("sha256").update(input, "utf8").digest("hex");
+}
+/** sha256(utf8(input)) 的 32 字节摘要，供截取与位修补类派生（会话 id、slug 字节流）使用 */
+export function sha256Digest(input) {
+    return createHash("sha256").update(input, "utf8").digest();
+}

package/dist/disguise/headers.d.ts

@@ -0,0 +1,25 @@
+/**
+ * generate 主请求的伪装头组装（disguise.md §2/§3/§10，#9 抓包 ground truth）。
+ *
+ * 头全集 = 预请求基础九键（preflight.ts buildPreflightHeaders 同源）+ 主请求专属四键：
+ * - `x-session-id`：会话身份（§3 主路径派生值，调用方经 state.resolveSessionId 取得；
+ *   与信封顶层 `threadId` 同值，#9 抓包定案）；
+ * - `x-project-slug`：workingDir 哈希近似（§3，与 config 块 workingDir 同源）；
+ * - `traceparent`：逐请求新造（每次调用本函数即新值，零复用）；
+ * - `x-taste-learning`：恒 `"true"`（#25 注记：本插件人格按官方规则恒 true）。
+ *
+ * 预请求**不带**这四键的边界由预请求侧自己保证（§2）；`x-command-code-version`
+ * 缺值时省略该键（四层兜底皆空的极端场景，与预请求同款处理）。
+ */
+export interface GenerateHeadersInput {
+    apiKey: string;
+    /** 版本头全局单值（D6）；undefined 时省略 x-command-code-version */
+    ccVersion: string | undefined;
+    /** 会话身份（与信封 threadId 同值，§3） */
+    sessionId: string;
+    /** slug 派生来源；与 config 块 workingDir 同源（process.cwd()） */
+    workingDir: string;
+    traceparent: string;
+}
+/** 组装 generate 主请求伪装头全集；键序照抓包样本（基础集在前，会话四键在后） */
+export declare function buildGenerateHeaders(input: GenerateHeadersInput): Record<string, string>;

package/dist/disguise/headers.js

@@ -0,0 +1,25 @@
+/**
+ * generate 主请求的伪装头组装（disguise.md §2/§3/§10，#9 抓包 ground truth）。
+ *
+ * 头全集 = 预请求基础九键（preflight.ts buildPreflightHeaders 同源）+ 主请求专属四键：
+ * - `x-session-id`：会话身份（§3 主路径派生值，调用方经 state.resolveSessionId 取得；
+ *   与信封顶层 `threadId` 同值，#9 抓包定案）；
+ * - `x-project-slug`：workingDir 哈希近似（§3，与 config 块 workingDir 同源）；
+ * - `traceparent`：逐请求新造（每次调用本函数即新值，零复用）；
+ * - `x-taste-learning`：恒 `"true"`（#25 注记：本插件人格按官方规则恒 true）。
+ *
+ * 预请求**不带**这四键的边界由预请求侧自己保证（§2）；`x-command-code-version`
+ * 缺值时省略该键（四层兜底皆空的极端场景，与预请求同款处理）。
+ */
+import { buildPreflightHeaders } from "./preflight.js";
+import { deriveProjectSlug } from "./slug.js";
+/** 组装 generate 主请求伪装头全集；键序照抓包样本（基础集在前，会话四键在后） */
+export function buildGenerateHeaders(input) {
+    return {
+        ...buildPreflightHeaders(input.apiKey, input.ccVersion),
+        "x-session-id": input.sessionId,
+        "x-project-slug": deriveProjectSlug(input.workingDir),
+        "x-taste-learning": "true",
+        traceparent: input.traceparent,
+    };
+}

package/dist/disguise/logger.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 注入式 logger 通道（disguise.md §7）：伪装模块不直接依赖 opencode 客户端——
+ * v1 注 client.app.log 适配器（#37），v2 插件 ctx 无 log 域（beta d.ts 全字段
+ * 核对，models-url-override.md §3.1）与独立调用退化 console，测试注 no-op。
+ * 级别只用两档（§7 级别表）：`debug`（预请求成功、版本刷新成功，默认安静）、
+ * `warn`（预请求失败、降级路径、落盘异常）。
+ */
+export interface DisguiseLogger {
+    debug(message: string): void;
+    warn(message: string): void;
+}
+export declare const noopLogger: DisguiseLogger;
+/** v1 与独立调用的退化通道：宿主未注入 logger 时保证伪装层日志有处可去 */
+export declare function consoleLogger(): DisguiseLogger;

package/dist/disguise/logger.js

@@ -0,0 +1,18 @@
+/**
+ * 注入式 logger 通道（disguise.md §7）：伪装模块不直接依赖 opencode 客户端——
+ * v1 注 client.app.log 适配器（#37），v2 插件 ctx 无 log 域（beta d.ts 全字段
+ * 核对，models-url-override.md §3.1）与独立调用退化 console，测试注 no-op。
+ * 级别只用两档（§7 级别表）：`debug`（预请求成功、版本刷新成功，默认安静）、
+ * `warn`（预请求失败、降级路径、落盘异常）。
+ */
+export const noopLogger = {
+    debug() { },
+    warn() { },
+};
+/** v1 与独立调用的退化通道：宿主未注入 logger 时保证伪装层日志有处可去 */
+export function consoleLogger() {
+    return {
+        debug: (message) => console.debug(message),
+        warn: (message) => console.warn(message),
+    };
+}

package/dist/disguise/preflight.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 伪装预请求（disguise.md §2/§4/§5）：指纹记录与 lifecycle 两个请求**并行**发出
+ * （同一 `Promise.allSettled`），各自挂独立 3s 超时（`AbortSignal.timeout`）——
+ * 修 MAXeaglet 无独立超时被网关挂起拖死主请求的真 bug（调研 §8.2）。
+ *
+ * 请求头照 #9 抓包校准全集（调研 §11.3）：`User-Agent: cli`、`x-cli-environment:
+ * production`、accept 家族等；**不带** `x-session-id` / `x-project-slug` /
+ * `traceparent` / `x-taste-learning`（抓包样本 capture/samples/ 证实预请求无此头，
+ * 规格 disguise.md §2 同）；`x-co-flag` 真实 CLI 不发送，不存在。
+ *
+ * 结局三态合记（两请求合记，照抄 MAXeaglet 耦合结构）：两 2xx 成功；4xx 任一
+ * 拒绝（优先于瞬时——服务器明确说「不」后继续敲门更像机器人）；网络错/超时/5xx
+ * 任一瞬时。推进动作归 backoff.ts 状态机。本模块任何函数绝不向上抛——预请求的
+ * 任何结局都不得影响主请求（§5 总则）。
+ */
+import type { FetchLike } from "../protocol/json.js";
+import { type PreflightOutcome, type PreflightState } from "./backoff.js";
+import type { FingerprintBody } from "./fingerprint.js";
+import { type DisguiseLogger } from "./logger.js";
+/** 指纹记录预请求端点（调研 §11.3 抓包 ground truth） */
+export declare const FINGERPRINT_ENDPOINT = "https://api.commandcode.ai/alpha/fingerprint/record";
+/** lifecycle 事件预请求端点 */
+export declare const LIFECYCLE_ENDPOINT = "https://api.commandcode.ai/alpha/lifecycle-events";
+/** 每个预请求的独立超时（§11 参数速查：3s） */
+export declare const PREFLIGHT_TIMEOUT_MS = 3000;
+/**
+ * 预请求头全集（§2，#9 校准后照抄真实 CLI）。`x-command-code-version` 缺值时
+ * 省略该键（四层兜底皆空的极端场景；真实 CLI 恒带）。
+ */
+export declare function buildPreflightHeaders(apiKey: string, ccVersion: string | undefined): Record<string, string>;
+/** lifecycle 事件 body（§4，#9 校准形状；wire 键序照抓包样本） */
+export interface LifecycleEvent {
+    eventType: "cli_session_exists";
+    metadata: {
+        sessionId: string;
+        cliVersion: string;
+        mode: "interactive";
+        os: string;
+    };
+}
+/**
+ * 构造 lifecycle 事件：`metadata.sessionId` 为与 `x-session-id` **无关**的随机
+ * `sess_<16hex>`（#9 证实真实 CLI 两套 ID 互不引用，每进程现造，照抄）；`mode`
+ * 恒 interactive（连 `-p` 一次性调用也报）；`os` 报真实 `platform-arch`。
+ */
+export declare function buildLifecycleEvent(ccVersion: string | undefined): LifecycleEvent;
+/** 单轮预请求的结局与可日志化细节（只含 HTTP status 与错误类别，不含头与 body） */
+export interface PreflightRound {
+    outcome: PreflightOutcome;
+    details: string[];
+}
+/**
+ * 两请求合记结局：4xx 任一 → rejected（优先于瞬时）；网络错/超时/5xx 任一 →
+ * transient；两 2xx → success。details 按请求序给出 status 或错误类别。
+ */
+export declare function summarizePreflightResults(results: readonly PromiseSettledResult<Response>[]): PreflightRound;
+export interface PreflightDeps {
+    apiKey: string;
+    /** 预请求调度状态载体（§5）；结局后经 applyPreflightOutcome 推进并合并回此对象 */
+    preflight: PreflightState;
+    fetchImpl: FetchLike;
+    logger?: DisguiseLogger;
+    /** 当前版本头值（预请求与主请求共享全局单值，D6a） */
+    getVersion: () => Promise<string | undefined>;
+    /** 指纹 body（KeyState 进程内缓存；采集失败 reject 时按瞬时失败处理） */
+    ensureFingerprintBody: () => Promise<FingerprintBody>;
+}
+/**
+ * 执行一轮预请求：未到点（冷却/退避未过）直接返回；否则指纹 + lifecycle 并行
+ * 上线，按结局推进状态机并记脱敏日志。**绝不向上抛**（§5：预请求任何结局都不
+ * 影响主请求）。调用方以 fire-and-forget 方式触发，本函数内部也不可再等待其他
+ * 会阻塞主请求的东西——版本初解析自带 1.5s 上限，指纹采集为本地系统调用。
+ */
+export declare function runPreflight(deps: PreflightDeps): Promise<void>;

package/dist/disguise/preflight.js

@@ -0,0 +1,139 @@
+/**
+ * 伪装预请求（disguise.md §2/§4/§5）：指纹记录与 lifecycle 两个请求**并行**发出
+ * （同一 `Promise.allSettled`），各自挂独立 3s 超时（`AbortSignal.timeout`）——
+ * 修 MAXeaglet 无独立超时被网关挂起拖死主请求的真 bug（调研 §8.2）。
+ *
+ * 请求头照 #9 抓包校准全集（调研 §11.3）：`User-Agent: cli`、`x-cli-environment:
+ * production`、accept 家族等；**不带** `x-session-id` / `x-project-slug` /
+ * `traceparent` / `x-taste-learning`（抓包样本 capture/samples/ 证实预请求无此头，
+ * 规格 disguise.md §2 同）；`x-co-flag` 真实 CLI 不发送，不存在。
+ *
+ * 结局三态合记（两请求合记，照抄 MAXeaglet 耦合结构）：两 2xx 成功；4xx 任一
+ * 拒绝（优先于瞬时——服务器明确说「不」后继续敲门更像机器人）；网络错/超时/5xx
+ * 任一瞬时。推进动作归 backoff.ts 状态机。本模块任何函数绝不向上抛——预请求的
+ * 任何结局都不得影响主请求（§5 总则）。
+ */
+import { randomBytes } from "node:crypto";
+import { applyPreflightOutcome } from "./backoff.js";
+import { consoleLogger } from "./logger.js";
+import { redactApiKey } from "./redact.js";
+/** 指纹记录预请求端点（调研 §11.3 抓包 ground truth） */
+export const FINGERPRINT_ENDPOINT = "https://api.commandcode.ai/alpha/fingerprint/record";
+/** lifecycle 事件预请求端点 */
+export const LIFECYCLE_ENDPOINT = "https://api.commandcode.ai/alpha/lifecycle-events";
+/** 每个预请求的独立超时（§11 参数速查：3s） */
+export const PREFLIGHT_TIMEOUT_MS = 3000;
+/**
+ * 预请求头全集（§2，#9 校准后照抄真实 CLI）。`x-command-code-version` 缺值时
+ * 省略该键（四层兜底皆空的极端场景；真实 CLI 恒带）。
+ */
+export function buildPreflightHeaders(apiKey, ccVersion) {
+    const headers = {
+        "content-type": "application/json",
+        "User-Agent": "cli",
+        "x-cli-environment": "production",
+        accept: "*/*",
+        "accept-language": "*",
+        "sec-fetch-mode": "cors",
+        "accept-encoding": "br, gzip, deflate",
+        Authorization: `Bearer ${apiKey}`,
+    };
+    if (ccVersion !== undefined)
+        headers["x-command-code-version"] = ccVersion;
+    return headers;
+}
+/**
+ * 构造 lifecycle 事件：`metadata.sessionId` 为与 `x-session-id` **无关**的随机
+ * `sess_<16hex>`（#9 证实真实 CLI 两套 ID 互不引用，每进程现造，照抄）；`mode`
+ * 恒 interactive（连 `-p` 一次性调用也报）；`os` 报真实 `platform-arch`。
+ */
+export function buildLifecycleEvent(ccVersion) {
+    return {
+        eventType: "cli_session_exists",
+        metadata: {
+            sessionId: `sess_${randomBytes(8).toString("hex")}`,
+            cliVersion: ccVersion ?? "",
+            mode: "interactive",
+            os: `${process.platform}-${process.arch}`,
+        },
+    };
+}
+function describeFailure(reason) {
+    // AbortSignal.timeout 到点的 reject reason 是 DOMException TimeoutError
+    return reason instanceof Error && reason.name === "TimeoutError" ? "timeout" : "network-error";
+}
+/**
+ * 两请求合记结局：4xx 任一 → rejected（优先于瞬时）；网络错/超时/5xx 任一 →
+ * transient；两 2xx → success。details 按请求序给出 status 或错误类别。
+ */
+export function summarizePreflightResults(results) {
+    const details = [];
+    let outcome = "success";
+    for (const result of results) {
+        if (result.status === "rejected") {
+            details.push(describeFailure(result.reason));
+            if (outcome !== "rejected")
+                outcome = "transient";
+            continue;
+        }
+        const status = result.value.status;
+        details.push(String(status));
+        if (status >= 400 && status < 500)
+            outcome = "rejected";
+        else if ((status < 200 || status >= 300) && outcome !== "rejected")
+            outcome = "transient";
+    }
+    return { outcome, details };
+}
+/**
+ * 执行一轮预请求：未到点（冷却/退避未过）直接返回；否则指纹 + lifecycle 并行
+ * 上线，按结局推进状态机并记脱敏日志。**绝不向上抛**（§5：预请求任何结局都不
+ * 影响主请求）。调用方以 fire-and-forget 方式触发，本函数内部也不可再等待其他
+ * 会阻塞主请求的东西——版本初解析自带 1.5s 上限，指纹采集为本地系统调用。
+ */
+export async function runPreflight(deps) {
+    const logger = deps.logger ?? consoleLogger();
+    if (Date.now() < deps.preflight.nextAttemptAt)
+        return;
+    let round;
+    try {
+        round = await executeRound(deps);
+    }
+    catch {
+        // 本地前置（指纹采集/版本解析）意外失败：按瞬时失败处理，绝不外溢
+        round = { outcome: "transient", details: ["preparation-failed"] };
+    }
+    // 纯函数返回新状态对象，此处合并回 KeyState 持有的载体
+    Object.assign(deps.preflight, applyPreflightOutcome(deps.preflight, round.outcome));
+    const key = redactApiKey(deps.apiKey);
+    if (round.outcome === "success") {
+        logger.debug(`伪装预请求成功（指纹+lifecycle） ${key}`);
+    }
+    else if (round.outcome === "rejected") {
+        logger.warn(`伪装预请求被拒绝（4xx），进入长冷却 ${key} [${round.details.join(", ")}]`);
+    }
+    else {
+        logger.warn(`伪装预请求瞬时失败，按退避状态机重试 ${key} [${round.details.join(", ")}]`);
+    }
+}
+async function executeRound(deps) {
+    // 指纹采集（本地）与版本初解析并行就绪后，两请求才并行上线（Promise.allSettled：
+    // 等两个都落定再合记结局，不因先失败者提前收场）
+    const [fingerprintBody, ccVersion] = await Promise.all([deps.ensureFingerprintBody(), deps.getVersion()]);
+    const headers = buildPreflightHeaders(deps.apiKey, ccVersion);
+    const results = await Promise.allSettled([
+        deps.fetchImpl(FINGERPRINT_ENDPOINT, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(fingerprintBody),
+            signal: AbortSignal.timeout(PREFLIGHT_TIMEOUT_MS),
+        }),
+        deps.fetchImpl(LIFECYCLE_ENDPOINT, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(buildLifecycleEvent(ccVersion)),
+            signal: AbortSignal.timeout(PREFLIGHT_TIMEOUT_MS),
+        }),
+    ]);
+    return summarizePreflightResults(results);
+}

package/dist/disguise/redact.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 日志脱敏（disguise.md §7，老板红线：不泄露敏感信息）：
+ * - apiKey 只以 `cc-key#` + sha256 前 8 位 hex 出现，日志中零原文；
+ * - thumbmark / sessionId / trace-id 本身即伪标识符，截断为前 12 位 hex + `…`；
+ * - Authorization 头 / 完整 key 永不整串输出——错误日志只记 HTTP status 与错误
+ *   类别、不序列化请求头，该纪律由调用方遵守，无对应纯函数。
+ */
+/** apiKey 的日志形态：`cc-key#` + sha256(apiKey) 前 8 位 hex */
+export declare function redactApiKey(apiKey: string): string;
+/** 伪标识符（thumbmark 64hex / sessionId uuid / trace-id 32hex）截断为前 12 位 hex + `…`；
+ * uuid 的连字符剥除后再取，保证截出的是纯 hex 位。 */
+export declare function redactIdentifier(id: string): string;

package/dist/disguise/redact.js

@@ -0,0 +1,17 @@
+/**
+ * 日志脱敏（disguise.md §7，老板红线：不泄露敏感信息）：
+ * - apiKey 只以 `cc-key#` + sha256 前 8 位 hex 出现，日志中零原文；
+ * - thumbmark / sessionId / trace-id 本身即伪标识符，截断为前 12 位 hex + `…`；
+ * - Authorization 头 / 完整 key 永不整串输出——错误日志只记 HTTP status 与错误
+ *   类别、不序列化请求头，该纪律由调用方遵守，无对应纯函数。
+ */
+import { sha256Hex } from "./hash.js";
+/** apiKey 的日志形态：`cc-key#` + sha256(apiKey) 前 8 位 hex */
+export function redactApiKey(apiKey) {
+    return `cc-key#${sha256Hex(apiKey).slice(0, 8)}`;
+}
+/** 伪标识符（thumbmark 64hex / sessionId uuid / trace-id 32hex）截断为前 12 位 hex + `…`；
+ * uuid 的连字符剥除后再取，保证截出的是纯 hex 位。 */
+export function redactIdentifier(id) {
+    return `${id.replace(/-/g, "").slice(0, 12)}…`;
+}

package/dist/disguise/session.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 会话身份主路径（disguise.md §3）：OpenCode 会话标识 → 确定性 uuid v4。
+ * sha256 摘要取前 16 字节（32 hex），修补 uuid v4 的版本位与变体位——无需任何
+ * 存储即保证「同会话同 id、跨重启同 id」。回退路径（per-key 随机 uuid + 12–13h
+ * 轮换）的存储与轮换语义归状态层（#33），不在本模块。
+ */
+/**
+ * 确定性派生 `x-session-id`：同输入恒得同一 uuid v4 形状的 id。
+ * 摘要字节本身已是均匀分布，位修补只重写版本/变体两个半字节，不损失会话关联性。
+ */
+export declare function deriveSessionId(seed: string): string;

package/dist/disguise/session.js

@@ -0,0 +1,24 @@
+/**
+ * 会话身份主路径（disguise.md §3）：OpenCode 会话标识 → 确定性 uuid v4。
+ * sha256 摘要取前 16 字节（32 hex），修补 uuid v4 的版本位与变体位——无需任何
+ * 存储即保证「同会话同 id、跨重启同 id」。回退路径（per-key 随机 uuid + 12–13h
+ * 轮换）的存储与轮换语义归状态层（#33），不在本模块。
+ */
+import { sha256Digest } from "./hash.js";
+/** uuid v4 版本位所在字节的掩码：低 4 位保留，高 4 位写 0100 */
+const VERSION_MASK = 0x0f;
+const VERSION_V4 = 0x40;
+/** uuid 变体位所在字节的掩码：低 6 位保留，高 2 位写 10（RFC 4122 保留态） */
+const VARIANT_MASK = 0x3f;
+const VARIANT_RFC4122 = 0x80;
+/**
+ * 确定性派生 `x-session-id`：同输入恒得同一 uuid v4 形状的 id。
+ * 摘要字节本身已是均匀分布，位修补只重写版本/变体两个半字节，不损失会话关联性。
+ */
+export function deriveSessionId(seed) {
+    const bytes = sha256Digest(seed).subarray(0, 16);
+    bytes[6] = (bytes[6] & VERSION_MASK) | VERSION_V4;
+    bytes[8] = (bytes[8] & VARIANT_MASK) | VARIANT_RFC4122;
+    const hex = bytes.toString("hex");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}

package/dist/disguise/slug.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `x-project-slug` 派生（disguise.md §3，#9 校准后改写）：真实 CLI 的 slug 由
+ * workingDir 派生、跨会话恒定，形状为「小写字母数字短横分组 ×8 组、组长 4–11」，
+ * 确切算法未知（逐段哈希链为最像假说，调研 §11.4）——本实现取形状一致的
+ * workingDir 哈希近似。MAXeaglet 的 `users-dev-projects-*` 旧算法整体弃用。
+ *
+ * 字节流：sha256(workingDir) 作种子，耗尽后接 `sha256(种子#序号)` 哈希链续流；
+ * 字符按 base36 取（256 ∤ 36，尾部 4 个字节值拒绝采样弃用以保均匀）；组长由
+ * 同一字节流驱动。纯函数，同 workingDir 跨调用、跨会话、跨重启恒定。
+ */
+/** 派生 `x-project-slug`：8 组、每组 4–11 字符、字符集 [0-9a-z]、短横连接 */
+export declare function deriveProjectSlug(workingDir: string): string;

package/dist/disguise/slug.js

@@ -0,0 +1,47 @@
+/**
+ * `x-project-slug` 派生（disguise.md §3，#9 校准后改写）：真实 CLI 的 slug 由
+ * workingDir 派生、跨会话恒定，形状为「小写字母数字短横分组 ×8 组、组长 4–11」，
+ * 确切算法未知（逐段哈希链为最像假说，调研 §11.4）——本实现取形状一致的
+ * workingDir 哈希近似。MAXeaglet 的 `users-dev-projects-*` 旧算法整体弃用。
+ *
+ * 字节流：sha256(workingDir) 作种子，耗尽后接 `sha256(种子#序号)` 哈希链续流；
+ * 字符按 base36 取（256 ∤ 36，尾部 4 个字节值拒绝采样弃用以保均匀）；组长由
+ * 同一字节流驱动。纯函数，同 workingDir 跨调用、跨会话、跨重启恒定。
+ */
+import { sha256Digest } from "./hash.js";
+const GROUP_COUNT = 8;
+const GROUP_MIN = 4;
+const GROUP_MAX = 11;
+const BASE36 = "0123456789abcdefghijklmnopqrstuvwxyz";
+/** base36 取字符的拒绝采样阈值：256 % 36 = 4，>= 252 的字节值弃用 */
+const REJECT_ABOVE = 256 - (256 % BASE36.length);
+function createByteStream(seed) {
+    let pool = sha256Digest(seed);
+    let poolIndex = 0;
+    let chainCount = 0;
+    return () => {
+        if (poolIndex >= pool.length) {
+            chainCount += 1;
+            pool = sha256Digest(`${seed}#${chainCount}`);
+            poolIndex = 0;
+        }
+        return pool[poolIndex++];
+    };
+}
+/** 派生 `x-project-slug`：8 组、每组 4–11 字符、字符集 [0-9a-z]、短横连接 */
+export function deriveProjectSlug(workingDir) {
+    const nextByte = createByteStream(workingDir);
+    const groups = [];
+    for (let group = 0; group < GROUP_COUNT; group++) {
+        const length = GROUP_MIN + (nextByte() % (GROUP_MAX - GROUP_MIN + 1));
+        let chars = "";
+        while (chars.length < length) {
+            const byte = nextByte();
+            if (byte >= REJECT_ABOVE)
+                continue;
+            chars += BASE36[byte % BASE36.length];
+        }
+        groups.push(chars);
+    }
+    return groups.join("-");
+}

package/dist/disguise/state.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 伪装模块的状态与调度门面（disguise.md §1/§3/§5，#33）：
+ *
+ * - **per-key 内存 KeyState**（`Map<apiKey, KeyState>`，key 为 Map 键原文、绝不
+ *   落盘绝不进日志——日志一律经 redactApiKey 短哈希）：指纹、回退会话、预请求
+ *   调度；全局内存态（ccVersion、config 冻结）收在对应子模块；
+ * - **指纹进程内稳定（D1）**：KeyState 只增不删，会话轮换只换 session 不删指纹，
+ *   进程重启 = Map 清空、首见 key 重新采集并立即重报（MAXeaglet 同款重启语义）；
+ * - **会话身份主路径（D3）**：doStream 调用 headers 中 `X-Session-Id` /
+ *   `x-session-affinity`（v2 另有同值 `x-opencode-session`）任一存在即确定性派生
+ *   `x-session-id`（session.ts 纯函数）——无需存储即保证同会话同 id、跨重启同 id；
+ *   多头同场值不一致 warn（「值漂移打日志」的落地；跨请求漂移无法与正常的新会话
+ *   区分，不告警防噪音）。全部缺失才落回退路径：per-key 随机 uuid v4、12h +
+ *   0~1h 抖动惰性轮换；
+ * - **预请求调度（D2/D5）**：startPreflight 对齐真实 CLI「每进程启动发一次」
+ *   （幂等守卫）；主请求前 maybeRunPreflight 做惰性补发/退避重试检查，到点后台
+ *   发射，主请求永不等待；
+ * - 全部出网与采集依赖经构造 options 注入（工厂 options.fetch、注入式 logger、
+ *   ConfigRuntime、兜底链 getter），测试零后门。
+ */
+import type { FetchLike } from "../protocol/json.js";
+import type { ConfigBlock, ConfigRuntime } from "./config-block.js";
+import { type DisguiseLogger } from "./logger.js";
+/** 回退路径会话寿命：12h + 0~1h 抖动（§11 参数速查，惰性轮换） */
+export declare const SESSION_TTL_BASE_MS: number;
+export declare const SESSION_TTL_JITTER_MS: number;
+export interface DisguiseStateOptions {
+    /** 出网接缝（工厂 options.fetch；预请求与版本查询全部经此注入 mock） */
+    fetch?: FetchLike;
+    /** 注入式 logger（§7；v1 注 client.app.log，v2 ctx 无 log 域走 console） */
+    logger?: DisguiseLogger;
+    /** config 采集 runtime 接缝（生产 createNodeConfigRuntime()，测试注 fake） */
+    configRuntime?: ConfigRuntime;
+    /** 版本兜底链 ③：模型管线内存中已拉取产物的 sourceCliVersion */
+    artifactSourceCliVersion?: () => string | undefined;
+    /** 版本兜底链 ④：包内快照的 sourceCliVersion */
+    snapshotSourceCliVersion?: () => string | undefined;
+}
+export interface DisguiseState {
+    /**
+     * 进程启动预请求（D2）：指纹 + lifecycle 并行、各 3s 超时、fire-and-forget。
+     * 幂等：每进程每 key 至多发一次；对 key 的首请求也可能先于本调用发生（此时
+     * maybeRunPreflight 的首次检查即承担首发）。
+     */
+    startPreflight(apiKey: string): void;
+    /**
+     * 主请求前的惰性检查（D5）：预请求到点（8–10h 补发 / 退避重试）即后台发射，
+     * 未到点零开销返回。绝不阻塞调用方。
+     */
+    maybeRunPreflight(apiKey: string): void;
+    /**
+     * 会话身份（D3）：主路径从 doStream headers 确定性派生；全部缺失落 per-key
+     * 回退轮换。同步无 IO，主请求零等待。
+     */
+    resolveSessionId(apiKey: string, headers: Record<string, string | undefined> | undefined): string;
+    resolveTraceparent(apiKey: string, sessionId: string, turnKey: string): string;
+    /** 版本头全局单值（D6）：初解析 1.5s 竞速 + 24h 惰性刷新；四层皆空返回 undefined */
+    getCommandCodeVersion(): Promise<string | undefined>;
+    /** config 块（D9/§9.3）：进程级冻结 + 24h 过期后台重采，主请求除首次构建外零等待 */
+    getConfigBlock(): Promise<ConfigBlock>;
+}
+export declare function createDisguiseState(options?: DisguiseStateOptions): DisguiseState;