@wallbreakerno4/opencode-commandcode 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 MAXeaglet
+Copyright (c) 2026 WallBreakerNO4
+
+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

@@ -0,0 +1,54 @@
+# @wallbreakerno4/opencode-commandcode
+
+OpenCode provider 插件：把 Command Code Go plan 专用的 `/alpha/generate` 网关桥接成 OpenCode 原生 provider。安装插件即完成全部配置——provider（`commandcode-go`）、模型清单与认证方式由插件自举，无需手写任何 provider 定义。
+
+## 安装
+
+> 前置：Command Code Go plan 订阅，并在 [Studio → API Keys](https://commandcode.ai/docs/studio) 生成 API key（与 CLI 同一把）。
+
+### OpenCode v2（beta）
+
+```bash
+opencode2 plugin add @wallbreakerno4/opencode-commandcode
+```
+
+再在 `opencode.json` 合入一行 provider 空壳（beta 限制，需手动添加）：
+
+```json
+{
+  "providers": {
+    "commandcode-go": {}
+  }
+}
+```
+
+启动 `opencode2` 后输入 `/connect`，选择 Command Code (Go) 粘贴 key 登录；
+或直接用环境变量（与 `/connect` 二选一）：
+
+```bash
+export COMMANDCODE_API_KEY=user_xxx
+```
+
+> v2 处于 beta，命令名以当前快照为准；正式版更名后以官方文档为准。
+
+### OpenCode v1
+
+`~/.config/opencode/opencode.json`（已有配置则合并）加一行：
+
+```json
+{
+  "plugin": ["@wallbreakerno4/opencode-commandcode"]
+}
+```
+
+启动 `opencode` 后输入 `/connect`，选择 Command Code (Go) 粘贴 key 登录；
+或直接用环境变量 `COMMANDCODE_API_KEY`（同上）。
+
+### 验证安装
+
+```bash
+opencode2 run --model commandcode-go/deepseek/deepseek-v4-pro "hi"   # v2
+opencode run  --model commandcode-go/deepseek/deepseek-v4-pro "hi"   # v1
+```
+
+注意：`opencode2 models` 不加载插件，不能用来判断安装是否成功。

package/dist/disguise/backoff.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 预请求退避状态机（disguise.md §5 + §11 参数速查）。指纹记录与 lifecycle 两个
+ * 预请求合记一个结局（照抄 MAXeaglet 的耦合结构）；任何结局都不影响主请求，
+ * 本模块只推进「下次允许尝试的时刻」。
+ *
+ * 结局三态：
+ * - success：`nextInitAt = now + 8h + rand×2h`（长驻补发节奏），`failCount = 0`
+ * - transient（网络错误 / 超时 / 5xx 任一）：`now + min(60s × 2^failCount, 15min)`，`failCount++`
+ * - rejected（4xx 含 401/403 任一）：长冷却 `now + 8h + rand×2h`——服务器明确说
+ *   「不」之后继续敲门更像机器人，安静是上策
+ *
+ * 时间直接取 `Date.now()`（testing.md：生产代码不加时钟注入参数，测试走 fake timers）。
+ */
+/** 成功 / 4xx 长冷却的基础间隔：8h（ground truth 未获证实，保守保留，#9） */
+export declare const SUCCESS_INTERVAL_MS: number;
+/** 成功 / 长冷却的随机抖动上限：`floor(random × 2h)` 均匀分布 */
+export declare const JITTER_MS: number;
+/** 瞬时失败退避基数：60s × 2^failCount */
+export declare const TRANSIENT_BASE_MS: number;
+/** 瞬时失败退避封顶：15min */
+export declare const TRANSIENT_CAP_MS: number;
+/** 预请求单元（两请求合记）的结局分类（§5 表） */
+export type PreflightOutcome = "success" | "transient" | "rejected";
+export interface PreflightState {
+    /** 下次允许预请求的时刻（epoch ms）；0 = 立即可试（首见 key / 重启归零）。
+     * 成功结局下即规格 §5 的 `nextInitAt`（长驻补发节奏），其余结局是重试时刻 */
+    nextAttemptAt: number;
+    /** 瞬时失败连续计数，驱动指数退避档位；成功清零 */
+    failCount: number;
+}
+export declare function initialPreflightState(): PreflightState;
+/** 按结局推进状态；返回新状态对象，不改入参 */
+export declare function applyPreflightOutcome(state: PreflightState, outcome: PreflightOutcome): PreflightState;

package/dist/disguise/backoff.js

@@ -0,0 +1,43 @@
+/**
+ * 预请求退避状态机（disguise.md §5 + §11 参数速查）。指纹记录与 lifecycle 两个
+ * 预请求合记一个结局（照抄 MAXeaglet 的耦合结构）；任何结局都不影响主请求，
+ * 本模块只推进「下次允许尝试的时刻」。
+ *
+ * 结局三态：
+ * - success：`nextInitAt = now + 8h + rand×2h`（长驻补发节奏），`failCount = 0`
+ * - transient（网络错误 / 超时 / 5xx 任一）：`now + min(60s × 2^failCount, 15min)`，`failCount++`
+ * - rejected（4xx 含 401/403 任一）：长冷却 `now + 8h + rand×2h`——服务器明确说
+ *   「不」之后继续敲门更像机器人，安静是上策
+ *
+ * 时间直接取 `Date.now()`（testing.md：生产代码不加时钟注入参数，测试走 fake timers）。
+ */
+/** 成功 / 4xx 长冷却的基础间隔：8h（ground truth 未获证实，保守保留，#9） */
+export const SUCCESS_INTERVAL_MS = 8 * 60 * 60 * 1000;
+/** 成功 / 长冷却的随机抖动上限：`floor(random × 2h)` 均匀分布 */
+export const JITTER_MS = 2 * 60 * 60 * 1000;
+/** 瞬时失败退避基数：60s × 2^failCount */
+export const TRANSIENT_BASE_MS = 60 * 1000;
+/** 瞬时失败退避封顶：15min */
+export const TRANSIENT_CAP_MS = 15 * 60 * 1000;
+export function initialPreflightState() {
+    return { nextAttemptAt: 0, failCount: 0 };
+}
+/** 8h + floor(random × 2h) 均匀抖动（成功与 4xx 长冷却共用同一节奏） */
+function jitteredInterval() {
+    return SUCCESS_INTERVAL_MS + Math.floor(Math.random() * JITTER_MS);
+}
+/** 按结局推进状态；返回新状态对象，不改入参 */
+export function applyPreflightOutcome(state, outcome) {
+    const now = Date.now();
+    if (outcome === "transient") {
+        // 指数按旧计数取档：第 1 次失败 60s、第 2 次 120s……第 5 次起封顶 15min
+        const delay = Math.min(TRANSIENT_BASE_MS * 2 ** state.failCount, TRANSIENT_CAP_MS);
+        return { nextAttemptAt: now + delay, failCount: state.failCount + 1 };
+    }
+    if (outcome === "rejected") {
+        // 4xx 不动 failCount：规格只在成功时指明清零；长冷却本身远超任何退避档位，
+        // 计数去留的可观察差异仅在「4xx 冷却后紧跟瞬时失败」一档，保持最小语义
+        return { nextAttemptAt: now + jitteredInterval(), failCount: state.failCount };
+    }
+    return { nextAttemptAt: now + jitteredInterval(), failCount: 0 };
+}

package/dist/disguise/config-block.d.ts

@@ -0,0 +1,71 @@
+/**
+ * generate 信封 `config` 块九字段采集（disguise.md §9，#19 定稿）：逐字段照抄官方
+ * CLI 实现（`command-code` 1.38.2 `buildServerConfig`，调研 `docs/research/cli-config-collection.md`
+ * 字节偏移级还原）。
+ *
+ * 官方语义照抄：structure 先于 git 判定（非 git 目录也有内容）；git 查询顺序 await、
+ * 无并发；shell 输出 try/catch 全包，非零退出码 / 异常 → `""`，逐字段独立降级、
+ * 绝不抛错；非 git 仓库九字段**齐全**显式空值、不省略字段；`date` 恒 UTC；
+ * `mainBranch` 三级远程 HEAD 推断（从不直接取当前分支）；`gitStatus` 空 / 失败 →
+ * `"Working tree clean"`（失败与干净工作区在 wire 上不可区分，照抄接受）。
+ *
+ * 两处防御偏离（§9.3，均不改请求线上形状）：每条 git 查询加 2s 超时（官方无超时，
+ * 插件长驻进程）；进程级冻结 + 24h 过期重采归状态层（#33），本模块只提供单次采集。
+ *
+ * runtime 接缝对应官方 `createNodeRuntime()` 的形状（cwd / platform / workspaceRoots /
+ * fs.readdir / shell.run），`homeDir()` 为本接口补充——官方 formatScopeDir 的 home 来源
+ * 在其 runtime 内部，此处显式化以便 scope 标签可测；测试注入 fake（testing.md §3 允许
+ * 的既有接缝注入）。
+ */
+/** 每条 git 查询的防御超时（§11 参数速查：2s/条，到点按失败处理） */
+export declare const GIT_QUERY_TIMEOUT_MS = 2000;
+/** 信封 `date` 字段取值（§9.1）：恒 UTC 的 `YYYY-MM-DD`（官方 `toISOString()` 即 UTC，非本地时区） */
+export declare function currentUtcDate(): string;
+/** 信封顶层 `permissionMode`：恒 `"standard"`（#9 抓包 ground truth，与 OpenCode 自身权限模式无关） */
+export declare const PERMISSION_MODE = "standard";
+/** 官方 structure 黑名单（调研偏移 1629355）；点开头项与「滤点开头」规则重叠属官方冗余保险，照抄 */
+export declare const STRUCTURE_BLACKLIST: ReadonlySet<string>;
+/** 官方 runtime 抽象（buildServerConfig 的注入面）；生产实现见 createNodeConfigRuntime */
+export interface ConfigRuntime {
+    cwd(): string;
+    platform(): string;
+    /** scope 标签的 home 相对化需要；对应官方 formatScopeDir 的 homeDir 来源 */
+    homeDir(): string;
+    workspaceRoots(): string[];
+    readdir(path: string): Promise<string[]>;
+    shell: {
+        /** 执行命令 resolve stdout；非零退出码 / 进程起不来 / signal abort 一律 reject */
+        run(command: string, signal: AbortSignal): Promise<string>;
+    };
+}
+/** config 块九字段；键序即官方 buildServerConfig 的 return 序（wire 形状） */
+export interface ConfigBlock {
+    workingDir: string;
+    date: string;
+    environment: string;
+    structure: string[];
+    isGitRepo: boolean;
+    currentBranch: string;
+    mainBranch: string;
+    gitStatus: string;
+    recentCommits: string[];
+}
+/**
+ * scope 标签的目录格式化（官方 formatScopeDir 语义）：目录即 cwd → `"."`；在 cwd 下 →
+ * `"./xxx"`；即 home → `"~"`；在 home 下 → `"~/xxx"`；否则原样绝对路径。
+ */
+export declare function formatScopeDir(dir: string, cwd: string, homeDir: string): string;
+/**
+ * structure 采集（官方 readStructure 逐字）：cwd 单层 readdir、无递归，滤点开头条目 +
+ * 黑名单，默认字典序（`.sort()`，大写在小写前），无数量上限；额外工作区目录（非 cwd）
+ * 格式化为 `scope:<路径>` 追加在数组末尾、不参与排序；readdir 抛异常 → 仅含 scope 标签。
+ */
+export declare function collectStructure(runtime: ConfigRuntime): Promise<string[]>;
+/** 单次采集 config 块九字段；任何子查询失败独立降级、整体绝不抛错（官方语义） */
+export declare function collectConfigBlock(runtime: ConfigRuntime): Promise<ConfigBlock>;
+/** 生产 runtime：官方 createNodeRuntime 同源取值（cwd = process.cwd() 等）。
+ * shell 用 exec 走 shell 解释（对齐官方 spawn {shell: true, windowsHide}；exec 无
+ * detached 选项，该参数对一次性短命令无观察差异）；stdout 无上限收集（官方无截断）。
+ * OpenCode 单工作区场景 workspaceRoots 仅 cwd（scope 标签自然为空）；宿主侧若暴露
+ * 多根工作区由 glue 层追加。 */
+export declare function createNodeConfigRuntime(): ConfigRuntime;

package/dist/disguise/config-block.js

@@ -0,0 +1,166 @@
+/**
+ * generate 信封 `config` 块九字段采集（disguise.md §9，#19 定稿）：逐字段照抄官方
+ * CLI 实现（`command-code` 1.38.2 `buildServerConfig`，调研 `docs/research/cli-config-collection.md`
+ * 字节偏移级还原）。
+ *
+ * 官方语义照抄：structure 先于 git 判定（非 git 目录也有内容）；git 查询顺序 await、
+ * 无并发；shell 输出 try/catch 全包，非零退出码 / 异常 → `""`，逐字段独立降级、
+ * 绝不抛错；非 git 仓库九字段**齐全**显式空值、不省略字段；`date` 恒 UTC；
+ * `mainBranch` 三级远程 HEAD 推断（从不直接取当前分支）；`gitStatus` 空 / 失败 →
+ * `"Working tree clean"`（失败与干净工作区在 wire 上不可区分，照抄接受）。
+ *
+ * 两处防御偏离（§9.3，均不改请求线上形状）：每条 git 查询加 2s 超时（官方无超时，
+ * 插件长驻进程）；进程级冻结 + 24h 过期重采归状态层（#33），本模块只提供单次采集。
+ *
+ * runtime 接缝对应官方 `createNodeRuntime()` 的形状（cwd / platform / workspaceRoots /
+ * fs.readdir / shell.run），`homeDir()` 为本接口补充——官方 formatScopeDir 的 home 来源
+ * 在其 runtime 内部，此处显式化以便 scope 标签可测；测试注入 fake（testing.md §3 允许
+ * 的既有接缝注入）。
+ */
+import { exec } from "node:child_process";
+import { readdir as fsReaddir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { promisify } from "node:util";
+const execAsync = promisify(exec);
+/** 每条 git 查询的防御超时（§11 参数速查：2s/条，到点按失败处理） */
+export const GIT_QUERY_TIMEOUT_MS = 2000;
+/** 信封 `date` 字段取值（§9.1）：恒 UTC 的 `YYYY-MM-DD`（官方 `toISOString()` 即 UTC，非本地时区） */
+export function currentUtcDate() {
+    return new Date().toISOString().split("T")[0] ?? "";
+}
+/** 信封顶层 `permissionMode`：恒 `"standard"`（#9 抓包 ground truth，与 OpenCode 自身权限模式无关） */
+export const PERMISSION_MODE = "standard";
+/** 官方 structure 黑名单（调研偏移 1629355）；点开头项与「滤点开头」规则重叠属官方冗余保险，照抄 */
+export const STRUCTURE_BLACKLIST = new Set([
+    "node_modules",
+    "dist",
+    "build",
+    ".git",
+    ".svn",
+    ".hg",
+    "coverage",
+    ".nyc_output",
+    ".cache",
+    "tmp",
+    "temp",
+    ".next",
+    ".nuxt",
+    "out",
+]);
+/** 官方 shellOutput 等价物：成功 → stdout.trim()；失败（reject）→ ""。超时经 signal 到点 reject，
+ * 与其他失败同形落入 ""。 */
+async function shellOutput(runtime, command) {
+    try {
+        const stdout = await runtime.shell.run(command, AbortSignal.timeout(GIT_QUERY_TIMEOUT_MS));
+        return stdout.trim();
+    }
+    catch {
+        return "";
+    }
+}
+/** mainBranch 三级推断（调研 resolveMainBranch 逐字）：symbolic-ref → branch -r → 兜底 main */
+async function resolveMainBranch(runtime) {
+    const symbolicRef = await shellOutput(runtime, "git symbolic-ref --short refs/remotes/origin/HEAD");
+    if (symbolicRef)
+        return symbolicRef.replace(/^origin\//, "");
+    const remoteBranches = await shellOutput(runtime, "git branch -r");
+    return remoteBranches.includes("origin/main") ? "main" : remoteBranches.includes("origin/master") ? "master" : "main";
+}
+/**
+ * scope 标签的目录格式化（官方 formatScopeDir 语义）：目录即 cwd → `"."`；在 cwd 下 →
+ * `"./xxx"`；即 home → `"~"`；在 home 下 → `"~/xxx"`；否则原样绝对路径。
+ */
+export function formatScopeDir(dir, cwd, homeDir) {
+    const prefixOf = (base) => (base.endsWith("/") ? base : `${base}/`);
+    if (dir === cwd)
+        return ".";
+    if (dir.startsWith(prefixOf(cwd)))
+        return `./${dir.slice(prefixOf(cwd).length)}`;
+    if (dir === homeDir)
+        return "~";
+    if (dir.startsWith(prefixOf(homeDir)))
+        return `~/${dir.slice(prefixOf(homeDir).length)}`;
+    return dir;
+}
+/**
+ * structure 采集（官方 readStructure 逐字）：cwd 单层 readdir、无递归，滤点开头条目 +
+ * 黑名单，默认字典序（`.sort()`，大写在小写前），无数量上限；额外工作区目录（非 cwd）
+ * 格式化为 `scope:<路径>` 追加在数组末尾、不参与排序；readdir 抛异常 → 仅含 scope 标签。
+ */
+export async function collectStructure(runtime) {
+    const cwd = runtime.cwd();
+    const homeDir = runtime.homeDir();
+    const scopeLabels = runtime
+        .workspaceRoots()
+        .filter((root) => root !== cwd)
+        .map((root) => `scope:${formatScopeDir(root, cwd, homeDir)}`);
+    try {
+        const entries = await runtime.readdir(cwd);
+        return [
+            ...entries.filter((name) => !name.startsWith(".") && !STRUCTURE_BLACKLIST.has(name)).sort(),
+            ...scopeLabels,
+        ];
+    }
+    catch {
+        return scopeLabels;
+    }
+}
+/** 单次采集 config 块九字段；任何子查询失败独立降级、整体绝不抛错（官方语义） */
+export async function collectConfigBlock(runtime) {
+    // 官方顺序：structure 最先（先于 git 判定），date/environment/workingDir 同步取
+    const structure = await collectStructure(runtime);
+    const date = currentUtcDate();
+    const environment = runtime.platform();
+    const workingDir = runtime.cwd();
+    const gitDir = await shellOutput(runtime, "git rev-parse --git-dir");
+    if (!gitDir) {
+        // 非 git 仓库 / git 未装同形：九字段齐全的显式空值，不省略字段（源码调研纠偏 #19）
+        return {
+            workingDir,
+            date,
+            environment,
+            structure,
+            isGitRepo: false,
+            currentBranch: "",
+            mainBranch: "",
+            gitStatus: "",
+            recentCommits: [],
+        };
+    }
+    const currentBranch = await shellOutput(runtime, "git branch --show-current");
+    const mainBranch = await resolveMainBranch(runtime);
+    const gitStatus = (await shellOutput(runtime, "git status --porcelain")) || "Working tree clean";
+    const logOutput = await shellOutput(runtime, "git log --oneline -3");
+    return {
+        workingDir,
+        date,
+        environment,
+        structure,
+        isGitRepo: true,
+        currentBranch,
+        mainBranch,
+        gitStatus,
+        recentCommits: logOutput ? logOutput.split("\n") : [],
+    };
+}
+/** 生产 runtime：官方 createNodeRuntime 同源取值（cwd = process.cwd() 等）。
+ * shell 用 exec 走 shell 解释（对齐官方 spawn {shell: true, windowsHide}；exec 无
+ * detached 选项，该参数对一次性短命令无观察差异）；stdout 无上限收集（官方无截断）。
+ * OpenCode 单工作区场景 workspaceRoots 仅 cwd（scope 标签自然为空）；宿主侧若暴露
+ * 多根工作区由 glue 层追加。 */
+export function createNodeConfigRuntime() {
+    return {
+        cwd: () => process.cwd(),
+        platform: () => process.platform,
+        homeDir: () => homedir(),
+        workspaceRoots: () => [process.cwd()],
+        readdir: (path) => fsReaddir(path),
+        shell: {
+            run: (command, signal) => execAsync(command, {
+                signal,
+                windowsHide: true,
+                maxBuffer: Infinity,
+            }).then(({ stdout }) => stdout),
+        },
+    };
+}

package/dist/disguise/config-freeze.d.ts

@@ -0,0 +1,27 @@
+/**
+ * config 块的进程级冻结与过期重采（disguise.md §9.3 偏离 b）：
+ *
+ * - 官方语义照抄：进程级只构建一次，首次需要时构建并冻结复用，失败结果同样冻结；
+ * - 偏离 b：插件长驻可跨日，冻结值距构建超 24h 后由下一次取值触发**后台**重采——
+ *   期间沿用旧值、主请求不等待（与 §6 版本头惰性刷新同节奏，24h、无抖动）；
+ * - 防御超时（偏离 a：git 查询 2s/条）在 config-block.ts 采集层实现，本模块不管。
+ *
+ * 采集经 ConfigRuntime 既有接缝注入（testing.md §3 认可），生产用
+ * createNodeConfigRuntime()；采集层承诺整体绝不抛错，此处防御性 catch 仅覆盖
+ * 意外（采集器自身 bug），兜一个「非 git 九字段齐全」的显式空值形状让主请求照常发。
+ */
+import { type DisguiseLogger } from "./logger.js";
+import { type ConfigBlock, type ConfigRuntime } from "./config-block.js";
+/** 冻结值过期重采间隔（§11 参数速查：24h，与版本头惰性刷新同节奏） */
+export declare const CONFIG_REBUILD_INTERVAL_MS: number;
+export interface FrozenConfigProvider {
+    /**
+     * 取冻结 config 块：首次调用构建并等待（官方「首次需要时构建」同语义）；此后
+     * 同进程恒返回同一冻结对象；24h 过期后返回旧值并后台重采（主请求零等待）。
+     */
+    get(): Promise<ConfigBlock>;
+}
+export declare function createFrozenConfigProvider(options?: {
+    runtime?: ConfigRuntime;
+    logger?: DisguiseLogger;
+}): FrozenConfigProvider;

package/dist/disguise/config-freeze.js

@@ -0,0 +1,87 @@
+/**
+ * config 块的进程级冻结与过期重采（disguise.md §9.3 偏离 b）：
+ *
+ * - 官方语义照抄：进程级只构建一次，首次需要时构建并冻结复用，失败结果同样冻结；
+ * - 偏离 b：插件长驻可跨日，冻结值距构建超 24h 后由下一次取值触发**后台**重采——
+ *   期间沿用旧值、主请求不等待（与 §6 版本头惰性刷新同节奏，24h、无抖动）；
+ * - 防御超时（偏离 a：git 查询 2s/条）在 config-block.ts 采集层实现，本模块不管。
+ *
+ * 采集经 ConfigRuntime 既有接缝注入（testing.md §3 认可），生产用
+ * createNodeConfigRuntime()；采集层承诺整体绝不抛错，此处防御性 catch 仅覆盖
+ * 意外（采集器自身 bug），兜一个「非 git 九字段齐全」的显式空值形状让主请求照常发。
+ */
+import { consoleLogger } from "./logger.js";
+import { collectConfigBlock, createNodeConfigRuntime, currentUtcDate, } from "./config-block.js";
+/** 冻结值过期重采间隔（§11 参数速查：24h，与版本头惰性刷新同节奏） */
+export const CONFIG_REBUILD_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/** 采集意外失败的兜底形状：与非 git 仓库九字段齐全的显式空值同形（§9.1）。
+ * cwd/platform 也包防御——工作目录被删时 process.cwd() 本身会 throw，兜底必须
+ * 永远可构造，否则主请求拿不到任何 config 块。 */
+function emptyConfigBlock(runtime) {
+    const safe = (fn) => {
+        try {
+            return fn();
+        }
+        catch {
+            return "";
+        }
+    };
+    return {
+        workingDir: safe(() => runtime.cwd()),
+        date: currentUtcDate(),
+        environment: safe(() => runtime.platform()),
+        structure: [],
+        isGitRepo: false,
+        currentBranch: "",
+        mainBranch: "",
+        gitStatus: "",
+        recentCommits: [],
+    };
+}
+function deepFreeze(block) {
+    Object.freeze(block.structure);
+    Object.freeze(block.recentCommits);
+    return Object.freeze(block);
+}
+export function createFrozenConfigProvider(options = {}) {
+    const runtime = options.runtime ?? createNodeConfigRuntime();
+    const logger = options.logger ?? consoleLogger();
+    let frozen;
+    let builtAt = 0;
+    let rebuilding;
+    /** 单轮采集：collectConfigBlock 承诺整体绝不抛错；真抛（采集器自身缺陷）视为本轮采集失败 */
+    function build() {
+        return collectConfigBlock(runtime);
+    }
+    return {
+        async get() {
+            if (frozen === undefined) {
+                try {
+                    frozen = deepFreeze(await build());
+                }
+                catch (error) {
+                    // 首次构建意外失败：没有旧值可沿用，兜显式空值形状（主请求照常发）
+                    logger.warn(`config 块首次构建意外失败，兜空值形状：${error instanceof Error ? error.message : String(error)}`);
+                    frozen = deepFreeze(emptyConfigBlock(runtime));
+                }
+                builtAt = Date.now();
+                return frozen;
+            }
+            if (Date.now() - builtAt >= CONFIG_REBUILD_INTERVAL_MS && rebuilding === undefined) {
+                rebuilding = build()
+                    .then((block) => {
+                    frozen = deepFreeze(block);
+                    builtAt = Date.now();
+                })
+                    .catch((error) => {
+                    // 重采意外失败沿用旧值（冻结语义），只记日志——旧数据好过空数据
+                    logger.warn(`config 块重采失败，沿用旧值：${error instanceof Error ? error.message : String(error)}`);
+                })
+                    .finally(() => {
+                    rebuilding = undefined;
+                });
+            }
+            return frozen;
+        },
+    };
+}

package/dist/disguise/fingerprint.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 设备指纹（disguise.md §8，#9 校准后如实上报真机真值）。
+ *
+ * - 15 字段 components 结构、thumbmark 联合哈希的拼接序与「五字段不入哈希」结构
+ *   照抄调研 §1.2–§1.3（服务端无从校验原像，结构同构无成本）；
+ * - 输入换成真机真值：platform / 内核版本 / CPU / 内存 / 时区 / 网卡——真机真值
+ *   天然确定，指纹跨进程稳定随之免费获得（MAXeaglet 的 win32 随机池假人格弃用）；
+ * - 采集器直接读系统 API（testing.md §1.5：不单测、不抽象注入接口，正确性归
+ *   真机人工验收）；哈希纯函数照测（注入固定输入）。
+ */
+/** components 15 字段（调研 §1.4）；键序即 wire 序 */
+export interface FingerprintComponents {
+    machineIdHash: string;
+    macHashes: string[];
+    osUserHash: string;
+    hostnameHash: string;
+    gitEmailHash: string;
+    platform: string;
+    arch: string;
+    osRelease: string;
+    cpuModel: string;
+    cpuCount: number;
+    memGiB: number;
+    isContainer: boolean;
+    timezone: string;
+    runtime: string;
+    collectorVersion: number;
+}
+/** `/alpha/fingerprint/record` 的 body 形状 */
+export interface FingerprintBody {
+    thumbmark: string;
+    components: FingerprintComponents;
+}
+/**
+ * thumbmark 联合哈希：参与字段为 machineIdHash → macHashes（按序全部）→ osUserHash
+ * → hostnameHash → gitEmailHash → platform → osRelease → cpuModel → cpuCount →
+ * memGiB，分隔符 `|`；arch / timezone / isContainer / runtime / collectorVersion
+ * 五字段不入哈希（调研 §1.3，原样保留该实现取舍）。
+ */
+export declare function computeThumbmark(components: FingerprintComponents): string;
+/** 组装 record body：thumbmark 重算，components 原样搬运 */
+export declare function buildFingerprintBody(components: FingerprintComponents): FingerprintBody;
+/** 采集真机真值并计算各字段哈希与 thumbmark；进程启动时调用一次（disguise.md §1） */
+export declare function collectFingerprintComponents(): Promise<FingerprintComponents>;