@jayyuen66/dsh-plugin-shared 0.1.0

package/dist/trust.js

@@ -0,0 +1,122 @@
+import { sendJson } from "./http.js";
+import os from "node:os";
+//#region lib/trust.ts
+/** 回环主机名的两个字面量（IPv6 在 WHATWG URL 里**带方括号**）。 */
+const LOOPBACK_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "[::1]"]);
+/** 唯一允许通过的 `sec-fetch-site` 取值（缺失=非浏览器，走第 1 条分歧的本地面）。 */
+const SAME_SITE_ALLOW = /* @__PURE__ */ new Set(["same-origin", "none"]);
+/** 站点级拒绝的响应文案（沿用 `lib/http.ts` 既有那句，统一口径时就少改一处断言）。 */
+const CROSS_ORIGIN_TEXT = "cross-origin request rejected";
+/** Host 权威不是本机可信地址时的响应文案。 */
+const UNTRUSTED_HOST_TEXT = "untrusted host authority";
+/** Origin 那条腿的结论（三形共用：沙箱 `null` 源、Origin 解析失败、权威不相等）。 */
+const BAD_ORIGIN_VERDICT = "bad-origin";
+/** 两形之外没有第三形（Node 的 IncomingHttpHeaders 值是 `string | string[]`），故不做 typeof 自卫。 */
+function singleHeader(req, name) {
+	const value = req.headers?.[name];
+	if (value === void 0) return null;
+	if (Array.isArray(value)) return value.length === 1 ? value.join("") : null;
+	return value;
+}
+/** Host 头的可接受字形。WHATWG 解析会**静默吃掉** tab/CR/LF 并丢掉 `user@` 前缀，
+*  于是 `local\thost:8787` 与 `evil.com@localhost:8787` 都能被折成"回环权威"（本机实测
+*  `new URL("http://" + "local\\thost:8787").hostname === "localhost"`）。浏览器发不出这些，
+*  但这一腿是本仓唯一挡得住 DNS 重绑定的判据 ⇒ 先按字形拒，再交给解析。 */
+const HOST_GLYPHS_RE = /^[A-Za-z0-9._\-[\]:%]+$/u;
+/** WHATWG 解析一个 authority（`host:port`）；失败返回 null。IPv6 必须已带方括号。 */
+function authorityOf(authority) {
+	if (!HOST_GLYPHS_RE.test(authority)) return null;
+	try {
+		return new URL(`http://${authority}`);
+	} catch {
+		return null;
+	}
+}
+/** 回环判定：`localhost` / `[::1]` / 127/8 四段纯数字（逐条对齐官方 loopback-hostname.ts）。 */
+function isLoopbackHostname(hostname) {
+	const lowered = hostname.toLowerCase();
+	if (LOOPBACK_HOSTNAMES.has(lowered)) return true;
+	const parts = lowered.split(".");
+	return parts.length === 4 && parts[0] === "127" && parts.every((part) => /^\d{1,3}$/u.test(part) && Number(part) <= 255);
+}
+/** `os.networkInterfaces()` 的地址面：IPv6 加方括号（与 `URL.hostname` 同形），IPv4 原样。 */
+function interfaceAddresses() {
+	const listed = [];
+	for (const infos of Object.values(os.networkInterfaces())) for (const { family, address } of infos ?? []) listed.push(family === "IPv6" ? `[${address}]` : address);
+	return listed;
+}
+/** Host 权威是不是本机可信地址：回环恒过；非回环只在**声明了非回环服务面**且该址确属本机网卡时过。 */
+function isAcceptedAuthority(hostname, opts) {
+	if (isLoopbackHostname(hostname)) return true;
+	if (opts.servingNonLoopback !== true) return false;
+	return (opts.localInterfaceAddresses ?? interfaceAddresses()).includes(hostname);
+}
+/** `sec-fetch-site` 白名单（缺失等于非浏览器面，交 Host/Origin 两条腿判）。 */
+function siteIsSameOrigin(req) {
+	const site = singleHeader(req, "sec-fetch-site");
+	return site === null || SAME_SITE_ALLOW.has(site);
+}
+/**
+* 对端是不是回环。拿不到 socket（手搓请求的测试构造点、非 node:http 的适配层）时返回 null，
+* 表示"这一维未知"，交调用侧按只看头部的旧口径处理。
+*/
+function peerLoopback(req) {
+	const raw = req.socket?.remoteAddress;
+	if (typeof raw !== "string" || raw === "") return null;
+	const address = raw.replaceAll(/^\[|\]$/gu, "").replace(/^::ffff:/iu, "");
+	return isLoopbackHostname(address) || address === "::1";
+}
+/**
+* Host 腿：返回解析出的权威、`null`（没带 Host 且对端不是可判的非回环），或 `"rejected"`。
+*
+* 缺 Host 只在**非回环对端**时拒——浏览器走不到这条路（HTTP/1.1 强制 Host、HTTP/2 强制
+* `:authority`，且 Host/Origin/Sec-Fetch-* 由同一个 URL 上下文导出），能走到的只有本地裸 socket
+* 与 Node 客户端（Node 确实收无 Host 的请求）。
+*/
+function authorityOfFrom(req, opts) {
+	const rawHost = req.headers?.host;
+	if (Array.isArray(rawHost) && rawHost.length !== 1) return "rejected";
+	const host = singleHeader(req, "host");
+	if (host === null) return peerLoopback(req) === false ? "rejected" : null;
+	const parsed = authorityOf(host);
+	if (parsed === null || !isAcceptedAuthority(parsed.hostname, opts)) return "rejected";
+	return parsed;
+}
+/**
+* 一次判据：Host 权威 → sec-fetch-site（白名单）→ Origin 逐字比对。
+* 纯函数、不写响应；写响应的样板在 `guardTrust`。
+*/
+function requestTrust(req, opts = {}) {
+	const hostUrl = authorityOfFrom(req, opts);
+	if (hostUrl === "rejected") return "untrusted-host";
+	if (!siteIsSameOrigin(req)) return "cross-site";
+	const origin = singleHeader(req, "origin");
+	if (origin === null) return "trusted";
+	if (origin === "null" || hostUrl === null) return BAD_ORIGIN_VERDICT;
+	const originUrl = authorityOf(origin.replace(/^[a-z][a-z0-9+.-]*:\/\//iu, ""));
+	if (originUrl === null) return BAD_ORIGIN_VERDICT;
+	return originUrl.host === hostUrl.host ? "trusted" : BAD_ORIGIN_VERDICT;
+}
+/** 结论对应的响应文案（cross-site 与 bad-origin 同一句，两者都是"不是本站的浏览器请求"）。 */
+function trustRejectionText(verdict) {
+	return verdict === "untrusted-host" ? UNTRUSTED_HOST_TEXT : CROSS_ORIGIN_TEXT;
+}
+/**
+* handler 体的**第一条语句**该放的东西：非 trusted 即写一次 403 JSON 并返回 false。
+* 返回 false 时调用方必须立即 return，不得继续读 body 或产生副作用。
+*/
+function guardTrust(req, res, opts = {}) {
+	const verdict = requestTrust(req, opts);
+	if (verdict === "trusted") return true;
+	if (res.headersSent || res.writableEnded) {
+		console.error("[shared/trust] rejecting after headers were sent:", verdict);
+		return false;
+	}
+	sendJson(res, 403, {
+		ok: false,
+		error: trustRejectionText(verdict)
+	});
+	return false;
+}
+//#endregion
+export { guardTrust, requestTrust, trustRejectionText };

package/dist/types/canonicalize-region-paths.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 产物文本的 canonical 形态：所有 `//#region` 行折成相对包根的形状，其余字节原样保留。
+ * @param code - builder 拿到的产物文本
+ * @param pkgDir - 包根绝对路径（builder 的 import.meta.dirname）
+ * @returns 与 process.cwd() 无关的同一份文本；对 canonical 输入幂等
+ */
+export declare function canonicalizeRegionPaths(code: string, pkgDir: string): string;

package/dist/types/card-apply.d.ts

@@ -0,0 +1,25 @@
+import type { Context } from "@deepseek-ai/cordis";
+/**
+ * 客户端 apply 接收的 ctx 最小面。
+ * `effect` 逐字取官方 `Context['effect']`（installed
+ * `@deepseek-ai/cordis/lib/types/fiber.d.ts`：`interface Context extends
+ * Pick<Fiber, 'effect'>`，同步 `Disposable` 与可 await 的 `AsyncDisposable` 两条重载），
+ * 而不是本地重述一条 `(factory: () => (() => void) | undefined, label?) => void`。
+ * ⚠ 为什么这条要紧：各卡片的 `ClientCtx.effect` 现在也绑官方，而本地那份把 factory 的
+ * 值域写**宽**了（官方 `SyncEffect` 不收 `undefined`）。函数属性位按 contravariance 检查，
+ * 于是「官方 ctx」反而赋不进本投影——三个卡片包会各自撞出一个
+ * `TS2345 … Type 'undefined' is not assignable to type 'SyncEffect<any>'`，
+ * 并在每个消费包里用一个类型断言去过桥。守卫的 ctx 面归本模块所有，就在这里一次修好。
+ */
+export interface CardApplyCtx {
+    effect: Context["effect"];
+}
+/**
+ * apply 幂等守卫：已 claim 返回 false（调用方直接 return），否则占位并
+ * 挂 ctx.effect 清理——HMR 重载时 flag 复位，再次 apply 可重新声明。
+ * @param ctx   - apply 的 ctx（需要 effect）。
+ * @param flag  - globalThis 上的布尔标记键名（如 "__xxxCardApplied"）。
+ * @param label - effect 标签（日志/生命周期可观测）。
+ * @returns true 表示本次拿到声明权（继续执行），false 表示已被占位。
+ */
+export declare function claimApply(ctx: CardApplyCtx, flag: string, label: string): boolean;

package/dist/types/config/oxlint.base.d.ts

@@ -0,0 +1,109 @@
+import type { OxlintConfig, OxlintOverride } from "oxlint";
+export type RuleTable = NonNullable<OxlintConfig["rules"]>;
+/**
+ * 一条规则能被关掉的**全部**合法理由。写不进这六类的，就不该有关掉它的选项。
+ * 每类的判据来自 oxlint/eslint 官方文档、上游 recommended 集合的归属，加上本仓的实测。
+ */
+export type OffReason = 
+/** 规则的判据与官方契约方向相反，开了等于判官方写法违规。 */
+"契约冲突"
+/** 与本仓已启用的对侧规则互斥（开一侧就判另一侧死刑）。 */
+ | "对侧互斥"
+/** 按它的意思改代码会把代码改坏，有实测的编译/运行后果。 */
+ | "实测否证"
+/** 判据只在某种文体（用例文件 / 构建脚本）里成立，按文件种类收窄。 */
+ | "文体作用域"
+/** 纯口味规则，上游不放进 recommended，开启只带来语义无关的重写。 */
+ | "上游不推荐"
+/** 旧 `.oxlintrc.json` 继承下来、实测开了是 0 条 —— 没有存在的理由，直接作废。 */
+ | "零代价作废";
+export interface OffJustification {
+    /** 关它的理由类别。 */
+    kind: OffReason;
+    /** 打开它在全仓产生的条数（口径见 OFF_JUSTIFICATIONS 的头注释）。 */
+    measured: number;
+    /** 一句话依据；配置加载只要求这个字段非空。 */
+    note: string;
+}
+/**
+ * 实测口径：临时把基线里每条 `off`（rules 与 override 层都算）翻成 `error` 再跑 15 个成员、
+ * 与基线取差数 `::error` 行，按路径分成 prod / test / scripts 三桶。`--deny=<rule>` 盖不住
+ * `off`，最早一轮用它在 13 个包目录上量出的数因此全偏小（`vitest/no-hooks` 用 `-D` 量出来是
+ * 0，实际是 181），整批作废重测。
+ *
+ * 键支持插件级通配（`vitest/*`），作用于该插件下没有更具体键的全部规则。
+ */
+export declare const OFF_JUSTIFICATIONS: Record<string, OffJustification>;
+/**
+ * 旧 `.oxlintrc.json` 里继承来、此次**取消豁免**且确实零代价的规则。
+ *
+ * 这里原来记着三条。"零代价"那句话是用 `oxlint --deny=<rule>` 量的，而 `--deny` 盖不住
+ * override 层的 off（本文件头注释里有这条实测口径）——重测之后：`eslint/no-continue` 在
+ * `scripts/` 有 53 条、`eslint/no-await-in-loop` 有 2 条，于是这两条按文体收窄回
+ * `SCRIPTS_OVERRIDES`（TS 侧仍 0 条、仍生效），从这份"已作废"名单里撤掉。留在这儿的
+ * 才是真正确认过零代价的。
+ */
+export declare const RETIRED_OFFS: string[];
+export declare const READONLY_SYNC_ALLOWLIST: string[];
+export declare const BASE_RULES: RuleTable;
+/**
+ * 用例文件（含 `test/*.ts` 夹具与 helper）共享的豁免：规模类，以及「桩件要跨官方名义类型」
+ * 的类型类判据。vitest 的用例结构类判据不在这里 —— 它们在基线整族 off、只在
+ * TEST_FILE_OVERRIDES 里开回来，所以 helper 模块天然不在射程内，旧配置那份按目录豁免的
+ * TEST_HELPER_OVERRIDES 因此作废。
+ */
+export declare const TEST_OVERRIDES: OxlintOverride;
+/**
+ * vitest 的用例结构类判据**只**在这里生效。
+ * `expect-expect` 的 `assertFunctionNames` 取 vitest flavor 的官方默认
+ * （`["expect", "expectTypeOf", "assert", "assertType"]`）：本仓用例里有相当一部分用
+ * `node:assert/strict` 断言，那不是「缺断言」，而是这条规则在 jest flavor 默认值下漏判
+ * ——实测 17 条里 5 条属于这一族，补上默认值后就不报了。
+ *
+ * 剩下两族用规则自带的选项解决，不关规则、也不改判据方向：
+ *  - 断言写在包内 helper 里（`assertSameLedger()` 一类）：`assertFunctionNames` 就是
+ *    "哪些函数算断言"的名单，走 {@link makeTestFileOverrides} 的 `assertionHelpers` 报名字。
+ *    名单只收**裸标识符**：带 `*` / `.` 的通配会把"任何调用都算断言"写进配置，等于掏空规则，直接抛。
+ *  - 标题以大写术语开头（`PTC`、`W5`、`B1` 这类档位/模式名）：`allowedPrefixes` 是
+ *    prefer-lowercase-title 给的同一条口径（官方例子就是 HTTP 方法前缀）。走 `titlePrefixes` 报名字。
+ *    反过来的做法——把标题改成 `pTC` / `w5`——会把领域名字改成坏名字，本仓不采取。
+ */
+export declare const VITEST_ASSERTION_DEFAULTS: string[];
+export declare const TEST_FILE_OVERRIDES: OxlintOverride;
+/**
+ * 生成用例文件的 override（vitest 结构类判据的开与关都在这张表里）。
+ * @param assertionHelpers - 本包"内部会断言"的 helper 函数名，并入 `expect-expect` 的名单。
+ * @returns 可直接放进 `overrides` 的配置项。
+ */
+export interface TestFileOverridesOptions {
+    /** 本包"内部会断言"的 helper 函数名，并入 `vitest/expect-expect` 的名单。 */
+    assertionHelpers?: string[];
+    /** 允许作为用例/套件标题开头的大写术语，并入 `vitest/prefer-lowercase-title` 的 allowedPrefixes。 */
+    titlePrefixes?: string[];
+}
+/**
+ * 生成用例文件的 override（vitest 结构类判据的开与关都在这张表里）。
+ * @param opts - 本包需要用规则自带选项登记的名单（见文件头的两族说明）。
+ * @returns 可直接放进 `overrides` 的配置项。
+ */
+export declare function makeTestFileOverrides(opts?: TestFileOverridesOptions): OxlintOverride;
+export declare const SCRIPTS_OVERRIDES: OxlintOverride;
+export interface PluginLintOptions {
+    syncWrites?: string[];
+    extraRules?: RuleTable;
+    extraOverrides?: OxlintOverride[];
+    extraIgnorePatterns?: string[];
+    /** 追加 oxlint JS plugin（alpha、不受 semver 保护）；包内自定义规则走这里。 */
+    jsPlugins?: NonNullable<OxlintConfig["jsPlugins"]>;
+    /** 包级豁免：每个 off 都要在这里写明 kind / measured / note，否则配置加载即抛错。 */
+    offReasons?: Record<string, OffJustification>;
+    /**
+     * 本包"内部会断言"的用例 helper 名（如 `assertSameLedger`）。报进来的名字并入
+     * `vitest/expect-expect` 的 `assertFunctionNames`，规则本身保持 error —— 这是规则给的口径，
+     * 不是豁免。只收裸标识符，通配会掏空这条规则，直接抛。
+     */
+    assertionHelpers?: string[];
+    /** 允许开头的用例标题大写术语（`PTC`/`W5`/`B1` 这类档位或模式名），进 allowedPrefixes。 */
+    titlePrefixes?: string[];
+}
+export declare function definePluginConfig(options?: PluginLintOptions): OxlintConfig;

package/dist/types/config/vitest.base.d.ts

@@ -0,0 +1,29 @@
+import type { ViteUserConfig } from "vitest/config";
+/**
+ * 类型名按实测取（四轮才钉准，过程记在这里免得下次再猜）：
+ *  - `import type { UserConfig } from "vitest/config"` ⇒ TS2305，5.0.2 不导出这个名字；
+ *  - `import type { UserConfig as ViteUserConfig }` 同样 TS2305 —— 它在 `vitest/config` 里的
+ *    **导出名就已经是 `ViteUserConfig`**（源上是 `export { UserConfig as ViteUserConfig } from 'vite'`），
+ *    别名要写在被导入的那一侧，不能自己再造一遍；
+ *  - `Parameters<typeof defineConfig>[0]` ⇒ 合出来是重载联合 `ViteUserConfigExport`（函数类型），
+ *    取 `.test` 直接 TS2339，并级联两条 `no-unsafe-*`；
+ *  - `TestUserConfig` 是 **test 块本身**的类型，不是配置文件对象类型，
+ *    拿它当返回值会在 `exactOptionalPropertyTypes: true` 下报 TS2375。
+ * 正确的那个是 `ViteUserConfig`：vitest 用模块声明合并给它加了 `test?: VitestInlineConfig`，
+ * 也正是 `defineConfig(config: UserConfig): UserConfig` 那条重载吃的形状。
+ */
+type PackageConfig = ViteUserConfig;
+/** 覆盖率面与 test 块里真正因包而异的那一项。 */
+export interface PackageVitestOptions {
+    /** `coverage.include` —— 本包该被统计的源文件（各包只有这里不同）。 */
+    coverageInclude: string[];
+    /** 追加/覆盖 test 字段（少用；出现即应在包内配置里写明为什么）。 */
+    test?: PackageConfig["test"];
+}
+/**
+ * 公共面：13 份配置里逐字相同的那部分，从今往后才真的只有一处。
+ * `testTimeout: 20_000` 是 12 个包的共同值（vitest 默认 5000），shared 原先没写、
+ * 现在继承这个值只会放宽不会收紧，故不会把任何已过用例变成不稳定。
+ */
+export declare function definePackageConfig(options: PackageVitestOptions): PackageConfig;
+export {};

package/dist/types/errors.d.ts

@@ -0,0 +1,2 @@
+/** `Error` 取 `message`，其余一律 `String(error)`（`null` → `"null"`，对象 → 其 `toString()`）。 */
+export declare function errorText(error: unknown): string;

package/dist/types/http.d.ts

@@ -0,0 +1,60 @@
+import type { IncomingHttpHeaders, IncomingMessage, ServerResponse } from "node:http";
+/**
+ * 下面的 header 读取 helper 不只被真 `IncomingMessage` 调用：`test/trust*.test.ts` 手搓合成
+ * 请求、以及非 node:http 的适配层都会传只带部分字段的对象。Node 的类型把 `headers` /
+ * `socket` 都标成必存在，照抄那个形状会让类型面比现实更乐观 —— 运行时不得不写 `?.` 自卫，
+ * 而那条自卫又会被类型感知规则判成冗余。所以这里如实声明可缺字段的入参类型。
+ */
+export interface PartialRequest {
+    readonly headers?: IncomingHttpHeaders;
+    readonly socket?: {
+        readonly remoteAddress?: string | undefined;
+    } | null;
+    readonly url?: string | undefined;
+}
+/** helper 接受的请求：真 `IncomingMessage` 或合成片段。 */
+export type HttpRequest = IncomingMessage | PartialRequest;
+/** 写 JSON 响应（no-store：端点都是运行时状态，禁缓存防陈旧）。
+ * 已发头/已结束则静默跳过：同一响应被写两次会抛 ERR_HTTP_HEADERS_SENT，
+ * 而端点多在 async 回调里，抛错变成 unhandled rejection 拖垮共享的 web host。 */
+export declare function sendJson(res: ServerResponse, status: number, payload: unknown): void;
+/**
+ * CORS 同源纵深防御：浏览器请求带 sec-fetch-site，非 same-origin/none 即拒绝。
+ * 空头（curl/CLI）不拦——浏览器侧伪造不了同源判定，CLI 是本地可信调用面。
+ */
+export declare function isCrossOrigin(req: IncomingMessage): boolean;
+/** 从 req.url 读 query 参数（URLSearchParams 语义：+ 解码空格、尊重 ; 分隔等）。 */
+export declare function queryParam(req: IncomingMessage, name: string): string | null;
+/** CSRF 校验：header 值非空且等于下发 token（sec-fetch-site 只防浏览器，可伪造）。 */
+export declare function checkCsrf(req: IncomingMessage, token: string, headerName: string): boolean;
+/** readBody 的失败原因：`too-large` 超限（413），`aborted` 流读取中断/坏流（400）。 */
+export type BodyRead = {
+    readonly ok: true;
+    readonly text: string;
+} | {
+    readonly ok: false;
+    readonly reason: "too-large" | "aborted";
+};
+/**
+ * 读 POST body（**按 UTF-8 字节**计上限；先查 content-length 再收流）。
+ *
+ * 两个必须一次做对的点：
+ *   1. 逐块 `String(chunk)` 会把跨 chunk 边界的多字节字符（中文/emoji）解码成
+ *      U+FFFD 且仍是合法 JSON —— 静默写坏用户数据。故累积 Buffer 后一次性解码。
+ *   2. 只按解码后字符数设限，恶意 body 可在触顶前已占满内存；content-length
+ *      预检让明显超限的请求根本不开始累积。
+ * 超限/坏流都立即停止读取（for-await 提前 return 会 release 迭代器并销毁流）。
+ */
+export declare function readBody(req: IncomingMessage, maxBytes: number): Promise<BodyRead>;
+/**
+ * 一次性校验组合（通用 POST 端点样板）：跨域拒绝 → CSRF 拒绝 → 读 body →
+ * 413（超限）/400（流中断）。全过返回 body 字符串。缺 CSRF 规范（如 GET 或
+ * 自持 token 端点）时传 skipCsrf=true。
+ */
+export declare function guardBody(req: IncomingMessage, res: ServerResponse, opts: {
+    maxBytes: number;
+    csrf?: {
+        token: string;
+        headerName: string;
+    };
+}): Promise<string | null>;

package/dist/types/job-outcome.d.ts

@@ -0,0 +1,10 @@
+import type { ShellProcess } from "@deepseek-ai/dsh-shell";
+import type { JobOutcome } from "@deepseek-ai/dsh-jobs";
+/** 映射只用得到的三个成员（不是整个 ShellProcess：生产者句柄的其余面与本函数无关）。 */
+export type SettledProcess = Pick<ShellProcess, "status" | "exitCode" | "signal">;
+/**
+ * 落定进程 → 作业结局。
+ * @param proc 已落定的子进程句柄（`done` 已 resolve 之后再读，值才是终态）
+ * @returns 交给 {@link JobRegistry} 生产者的结局：killed / completed，理由在 detail
+ */
+export declare function jobOutcomeOf(proc: SettledProcess): JobOutcome;

package/dist/types/jsonl.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 反复保留后半行段直到 UTF-8 字节数 ≤ `maxBytes`；行数 ≤2 时停手（单条超限行原样保留，
+ * 防死循环也防清空文件）。未超限直接返回入参**同一引用**，调用方可据此跳过写盘。
+ * @param text 整份 JSONL 文本
+ * @param maxBytes 字节上限
+ * @returns 收缩后的文本
+ */
+export declare function shrinkJsonlTail(text: string, maxBytes: number): string;

package/dist/types/lesson-bus.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 执行一次 lesson bus 调用，并把两类失败归到同一个出口。
+ * @param call - 真正的调用（同步返回或返回 Promise 都接受）。
+ * @param onFailure - 失败收口：同步抛错与异步拒绝都会到这里，且各自只被调一次。
+ */
+export declare function settleLessonCall(call: () => unknown, onFailure: (reason: unknown) => void): void;

package/dist/types/locale.d.ts

@@ -0,0 +1,39 @@
+/** 支持的界面/模型侧文案语言。 */
+export type Locale = "zh" | "en";
+/** 缺省语言。设置项未设或值不合语法时落到这里。 */
+export declare const DEFAULT_LOCALE: Locale;
+/**
+ * 官方 `@deepseek-ai/dsh-client-locale` 在 Host settings 文档里拥有的命名空间与字段名
+ * （其 `lib/index.js:5-7`）。这里是**抄常量不是引依赖**：那是宿主内部实现，没进公开
+ * 依赖面，而两侧必须同名才能读到同一份偏好。
+ */
+export declare const LOCALE_SETTINGS_NAMESPACE = "locale";
+export declare const LOCALE_PREFERENCE_FIELD = "preference";
+/** 一个包的全部消息键值表（键名即语义，值是人读文案）。 */
+export interface MessagesCatalog<Messages> {
+    readonly zh: Messages;
+    readonly en: Messages;
+}
+/**
+ * 把设置里的原始值归一成受支持的 locale：按**主语言子标签**判定（`en-US`、`zh-Hans-CN`
+ * 都落位），与 client 半「先完整标签、再主语言子标签」的规则同源；判不出来一律退
+ * DEFAULT_LOCALE——文案语言不该成为报错面。
+ * @param raw - 设置里的原始值，类型不可信（来自用户文档）。
+ * @returns 归一后的 locale。
+ */
+export declare function resolveLocale(raw: unknown): Locale;
+/**
+ * 从 `ctx.settings.describe(LOCALE_SETTINGS_NAMESPACE)` 的返回值里取偏好并归一。
+ * describe 出来的形状由别的包拥有，所以入参按 unknown 处理：非对象、数组、缺字段
+ * 都走默认语言，不抛。
+ * @param described - describe 的原始返回值（可能 undefined）。
+ * @returns 归一后的 locale。
+ */
+export declare function resolveLocalePreference(described: unknown): Locale;
+/**
+ * 取某个语言下的消息表。
+ * @param catalog - 两语齐全的消息表。
+ * @param locale - 已归一的语言。
+ * @returns 对应语言的消息表（引用返回，不做拷贝）。
+ */
+export declare function messagesFor<Messages>(catalog: MessagesCatalog<Messages>, locale: Locale): Messages;

package/dist/types/project-key.d.ts

@@ -0,0 +1,9 @@
+/** 可注入面：realpath 是同步 fs 调用，测试替换它来观察软链归一与失败兜底两条臂。 */
+export interface ProjectKeyOptions {
+    realpath?: (target: string) => string;
+}
+/**
+ * cwd → 项目桶键。非字符串 / trim 后为空 / 归一后落到根目录 → `"default"`
+ * （与记忆网关的兜底桶名一致）。
+ */
+export declare function deriveProjectKey(cwd: unknown, opts?: ProjectKeyOptions): string;

package/dist/types/record.d.ts

@@ -0,0 +1,4 @@
+/** 对象类型守卫：非 `null` 的 `object` 且非数组（`Record` 索引签名投影的基础）。 */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** 从 `unknown` 投影单个字段；非 `Record` → `undefined`。 */
+export declare function fieldOf(value: unknown, key: string): unknown;

package/dist/types/text.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 保留前 `maxChars` 个码元；切点切开代理对时丢掉尾部那个孤立高代理。
+ * `maxChars <= 0` 与 NaN ⇒ 空串。
+ */
+export declare function truncateEnd(text: string, maxChars: number): string;
+/**
+ * 保留后 `minChars` 个码元；切点切开代理对时丢掉首部那个孤立低代理。
+ * `minChars <= 0` 与 NaN 与 `truncateEnd(text, 0)` 同口径返回空串，不返回整串。
+ */
+export declare function truncateStart(text: string, minChars: number): string;

package/dist/types/tool-events.d.ts

@@ -0,0 +1,77 @@
+import type { SessionEvent } from "@deepseek-ai/dsh-session";
+export type { SessionEvent } from "@deepseek-ai/dsh-session";
+export type { PtcDispatchEventData, PtcDispatchStartEventData } from "@deepseek-ai/dsh-tools/types";
+/** 一条 tool/call 的记账记录。 */
+export interface ToolCallRecord {
+    /** 调用名（edit/write/str_replace_editor/read/grep/…）。 */
+    name: string | undefined;
+    /** callId：tool/result 串联键；缺失时由调用方按 seq 造 `nc:` 键。 */
+    callId: string | undefined;
+    /** 解析后的参数对象（解析失败/非对象时为空对象，配合 badArguments 使用）。 */
+    arguments: Record<string, unknown>;
+    /**
+     * arguments 原始值无法解析为对象（JSON 字符串非法、或非字符串非对象）。
+     * 调用方据此保留各自语义：quality-gate 判 EDIT_SKIP、danger-guard 跳过记账——
+     * 共享层只标记不决策，避免把两插件的"坏参是否记账"策略悄悄统一。
+     */
+    badArguments: boolean;
+    /**
+     * 在**入参数组**中的下标（归因/游标用），不是官方事件自带的 `SessionSeq`：消费方按
+     * 窗口切片读取事件流，切片下标才是它们游标语义里的那个「序」。
+     */
+    seq: number;
+}
+/** 一条 tool/result 的成败。 */
+export interface ToolResultRecord {
+    callId: string | undefined;
+    isError: boolean;
+    seq: number;
+}
+/**
+ * tool/result 的 isError 判定（官方 v4：成败位在 message 级、类型为 `?: boolean`；
+ * 字段缺失按成功）。非 tool/result 事件一律按成功——PTC 子调度的成败位在 data 顶层，
+ * 由 `resultRecordOf` 的对应分支处理，不从这儿走。
+ */
+export declare function resultIsError(event: SessionEvent): boolean;
+/** 解析 tool/call 的 arguments：string JSON 文本或已解析对象；非法/缺失 → 空对象。 */
+export declare function parseToolArguments(raw: unknown): Record<string, unknown>;
+/**
+ * arguments 是否「无法参与记账」：仅当字符串 JSON **语法非法**（JSON.parse 抛错）。
+ * 合法 JSON 非对象（"42"）、undefined/数字/对象等一律不标——quality-gate 原实现
+ * 对 JSON.parse 抛错判 EDIT_SKIP，但对"解析成功却非对象"仍记账（path=undefined），
+ * 本标记必须精确复用那一个语义点，不能把"非对象"也划进坏参。
+ */
+export declare function toolArgumentsBad(raw: unknown): boolean;
+/** 一条事件产出的记账行（call 与 result 互斥；非记账事件两位都是 undefined）。 */
+export interface ToolEventRows {
+    call: ToolCallRecord | undefined;
+    result: ToolResultRecord | undefined;
+}
+/**
+ * **单条事件**的记账行（`scanToolEvents` 的一步，也是它唯一的实现处）。
+ *
+ * 之所以导出：danger-guard 把同一套台账折成 `sessionProjections` 投影单元（增量折叠）后，
+ * 折叠与"注册表缺席时的全量扫描"必须逐字同源——两处各写一遍字段读取，就会在两行上给出
+ * 不同的证据链（那是安全门禁的 fail-open）。折叠侧传 `event.seq`，扫描侧传数组下标，
+ * 两者在官方 `seq = log.length` 的连号契约下同一个值。
+ */
+export declare function toolEventRowsOf(event: SessionEvent, index: number): ToolEventRows;
+/**
+ * 扫描事件流 → tool/call 与 tool/result 两张表。
+ * 只收集形状可用的事件，其余静默跳过——调用方（门禁/证据链）以空表安全降级，不因零星
+ * 坏事件抛错。数组空洞（类型面不可表示、重放数据里却可能出现）同样跳过。
+ * seq 取事件在入参数组里的下标（与 danger-guard scanToolCalls 的归因语义一致）。
+ */
+export declare function scanToolEvents(events: readonly SessionEvent[]): {
+    calls: ToolCallRecord[];
+    results: ToolResultRecord[];
+};
+/**
+ * 由 tool/call 记录推导被编辑的文件路径；str_replace_editor 的 view 只读不算写。
+ * @returns { kind: "write", path } 写操作；{ kind: "read-view", path } 只读视图；
+ *          { kind: "skip" } 无路径或参数形状不可用（调用方忽略）。
+ */
+export declare function editPathOf(call: ToolCallRecord): {
+    kind: "write" | "read-view" | "skip";
+    path: string | undefined;
+};

package/dist/types/trust.d.ts

@@ -0,0 +1,22 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/** 信任判据的结论。除 `trusted` 外都该被拒。 */
+export type TrustVerdict = "trusted" | "untrusted-host" | "cross-site" | "bad-origin";
+/** `requestTrust` / `guardTrust` 的可选入参。 */
+export interface TrustOptions {
+    /** 宿主是否绑在非回环地址上（`webServer.host === "0.0.0.0"`）。缺省按 false（保守）。 */
+    servingNonLoopback?: boolean;
+    /** 注入本机地址面（测试用；缺省取 `os.networkInterfaces()` 的实际值）。 */
+    localInterfaceAddresses?: readonly string[];
+}
+/**
+ * 一次判据：Host 权威 → sec-fetch-site（白名单）→ Origin 逐字比对。
+ * 纯函数、不写响应；写响应的样板在 `guardTrust`。
+ */
+export declare function requestTrust(req: IncomingMessage, opts?: TrustOptions): TrustVerdict;
+/** 结论对应的响应文案（cross-site 与 bad-origin 同一句，两者都是"不是本站的浏览器请求"）。 */
+export declare function trustRejectionText(verdict: TrustVerdict): string;
+/**
+ * handler 体的**第一条语句**该放的东西：非 trusted 即写一次 403 JSON 并返回 false。
+ * 返回 false 时调用方必须立即 return，不得继续读 body 或产生副作用。
+ */
+export declare function guardTrust(req: IncomingMessage, res: ServerResponse, opts?: TrustOptions): boolean;

package/icon.svg

@@ -0,0 +1 @@
+<svg width="36" height="36" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><g fill="none" stroke="#658EFF" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"><path fill="#54ECE7" d="M14 6h3a3 3 0 0 1 3 3v8a3 3 0 0 1 -3 3H7a3 3 0 0 1 -3 -3V9a3 3 0 0 1 3 -3h3" opacity=".2" stroke="#54ECE7"/><path stroke="#658EFF" d="M14 6h3a3 3 0 0 1 3 3v8a3 3 0 0 1 -3 3H7a3 3 0 0 1 -3 -3V9a3 3 0 0 1 3 -3h3"/><path stroke="#658EFF" d="M4 11h16"/><path stroke="#658EFF" d="M12 6v5"/></g></svg>