@jayyuen66/dsh-plugin-shared 0.1.9 → 0.2.1

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

@@ -0,0 +1,10 @@
+/** 设置卡统一组件与样式。客户端专用的子模块，不进入根 barrel。 */
+export { CARD_UI_CSS } from "./card-ui/styles.js";
+export { splitHint } from "./card-ui/hint.js";
+export { CardForm, FieldGrid, Section, StatusBar } from "./card-ui/layout.js";
+export { Field, FieldLabel, InfoTip } from "./card-ui/field.js";
+export type { FieldBase } from "./card-ui/field.js";
+export { ListField, NumberField, TextField, ToggleField } from "./card-ui/inputs.js";
+export { SelectField } from "./card-ui/select.js";
+export type { SelectOption } from "./card-ui/select.js";
+export { SaveBar } from "./card-ui/save-bar.js";

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

@@ -2,32 +2,32 @@ import type { OxlintConfig, OxlintOverride } from "oxlint";
 export type RuleTable = NonNullable<OxlintConfig["rules"]>;
 /**
  * 一条规则能被关掉的**全部**合法理由。写不进这六类的，就不该有关掉它的选项。
- * 每类的判据来自 oxlint/eslint 官方文档、上游 recommended 集合的归属，加上本仓的实测。
+ * 每类的判断依据来自 oxlint/eslint 官方文档、上游 recommended 集合的归属，加上本仓的实测。
  */
 export type OffReason = 
-/** 规则的判据与官方契约方向相反，开了等于判官方写法违规。 */
-"契约冲突"
-/** 与本仓已启用的对侧规则互斥（开一侧就判另一侧死刑）。 */
- | "对侧互斥"
-/** 按它的意思改代码会把代码改坏，有实测的编译/运行后果。 */
- | "实测否证"
-/** 判据只在某种文体（用例文件 / 构建脚本）里成立，按文件种类收窄。 */
- | "文体作用域"
-/** 纯口味规则，上游不放进 recommended，开启只带来语义无关的重写。 */
+/** 规则的判断标准与官方代码形态相反，开启等于判定官方写法违规。 */
+"与官方形态冲突"
+/** 与本仓已启用的另一条规则互相排除（开一侧就判另一侧全部违规）。 */
+ | "与已启用规则互斥"
+/** 按它的意思改代码会把代码改坏，有实测的编译或运行后果。 */
+ | "实测有害"
+/** 判断标准只在某类文件（用例文件、构建脚本）里成立，按文件种类收窄。 */
+ | "仅限特定文件"
+/** 纯风格偏好类规则，上游不放进 recommended，开启只带来语义无关的重写。 */
  | "上游不推荐"
-/** 旧 `.oxlintrc.json` 继承下来、实测开了是 0 条 —— 没有存在的理由，直接作废。 */
- | "零代价作废";
+/** 旧 `.oxlintrc.json` 继承下来、实测开启后零命中——没有存在的理由，直接作废。 */
+ | "零命中作废";
 export interface OffJustification {
     /** 关它的理由类别。 */
     kind: OffReason;
-    /** 打开它在全仓产生的条数（口径见 OFF_JUSTIFICATIONS 的头注释）。 */
+    /** 打开它在全仓产生的条数（测量方法见 OFF_JUSTIFICATIONS 的头注释）。 */
     measured: number;
     /** 一句话依据；配置加载只要求这个字段非空。 */
     note: string;
 }
 /**
- * 实测口径：临时把基线里每条 `off`（rules 与 override 层都算）翻成 `error` 再跑 15 个成员、
- * 与基线取差数 `::error` 行，按路径分成 prod / test / scripts 三桶。`--deny=<rule>` 盖不住
+ * 实测方法：临时把基线里每条 `off`（rules 与 override 层都算）翻成 `error` 再跑 15 个成员、
+ * 与基线取差数 `::error` 行，按路径分成 prod / test / scripts 三类。`--deny=<rule>` 盖不住
  * `off`，最早一轮用它在 13 个包目录上量出的数因此全偏小（`vitest/no-hooks` 用 `-D` 量出来是
  * 0，实际是 181），整批作废重测。
  *
@@ -37,8 +37,8 @@ export declare const OFF_JUSTIFICATIONS: Record<string, OffJustification>;
 /**
  * 基线里**不设豁免**的规则清单：这些规则必须保持开启，谁要关掉就得先给出依据。
  *
- * 判据是「按文体分别核命中数」。`oxlint --deny=<rule>` 量的是整体，而 `--deny` 盖不住
- * override 层的 off（这条口径见本文件头），所以一条规则可以同时是「TS 侧零命中、保持开启」
+ * 方法是「按文件种类分别核对命中数」。`oxlint --deny=<rule>` 量的是整体，而 `--deny` 盖不住
+ * override 层的 off（这个测量方法见本文件头），所以一条规则可以同时是「TS 侧零命中、保持开启」
  * 与「`scripts/` 的无类型 .mjs 里有命中、按文体收窄」——`eslint/no-continue` 正是这一类，
  * 它的收窄在 SCRIPTS_OVERRIDES 里，不在这里。`eslint/no-await-in-loop` 则两侧都开着
  * （实测探针对 .mjs 照样报），两边都按代码写到位，没有收窄层。
@@ -46,23 +46,23 @@ export declare const OFF_JUSTIFICATIONS: Record<string, OffJustification>;
 export declare const RETIRED_OFFS: string[];
 export declare const READONLY_SYNC_ALLOWLIST: string[];
 /**
- * 组装 `jsPlugins`：本包解析到的 sonarjs 入口在前，调用方自带的在后并去重。
+ * 组装 sonarjs 的入口：本包解析到的入口在前，调用方自带的在后并去重。
  *
- * 为什么要有这一层而不是直接 `[resolveSonarjsEntry(), ...(jsPlugins ?? [])]`：
- * 那写法无条件先求值，于是「调用方自带入口」这条官方逃生口在缺 sonarjs 时**用不了**——
+ * 为什么要有这一层而不是直接 `[resolvePluginEntry(SONARJS_PLUGIN), ...(jsPlugins ?? [])]`：
+ * 那写法无条件先求值，于是「调用方自带入口」这条官方预留的退路在缺 sonarjs 时**用不了**——
  * 抛错发生在调用方的入口被用上之前，报错信息给的补救办法照做必然再报同一条。
- * 分支口径：
+ * 分支规则：
  *  - 调用方带了**指向 sonarjs 的**入口 → 解析失败就跳过（它自备的就是 sonarjs），
  *    成功则去重后前置；
  *  - 调用方只带了别家插件、或没带 → 解析失败照旧抛那条可操作的信息。SONARJS_RULES
- *    无条件引用 sonarjs，只带别家插件救不了它：那种失败会迟到到 oxlint 装载配置那一刻
- *    （`Plugin 'sonarjs' not found`），可操作的成因必须在这里先抛出来，而不是被吞掉。
+ *    无条件引用 sonarjs，只带别家插件满足不了它：那种失败会推迟到 oxlint 装载配置那一刻
+ *    （`Plugin 'sonarjs' not found`），可操作的成因必须在这里先抛出来，而不是留到后面被掩盖。
  *    「指向 sonarjs」按入口路径含 `sonarjs` 判定——调用方传的是自己解析到的插件路径，
- *    这是能落进字符串判据的全部信号。
+ *    这是能落进字符串判断的全部信号。
  *
  * 导出且把解析器做成入参，是为了「解析失败」那一支在**本仓**可测：本仓 devDependencies
- * 装着 sonarjs，真实的解析路径永远成功，那两个分支就只能靠注桩走到（与 `LauncherLocator`、
- * `ProjectKeyOptions.realpath` 同一套可注入面的取舍）。生产侧的 consumer 是
+ * 装着 sonarjs，真实的解析路径永远成功，那两个分支就只能靠注入 stub 走到（与 `LauncherLocator`、
+ * `ProjectKeyOptions.realpath` 同一套可注入选项的取舍）。生产侧的 consumer 是
  * `definePluginConfig`，故这不是「只被测试养着的导出」。
  *
  * @param callerPlugins - 调用方经 `jsPlugins` 传入的入口；undefined / 空数组均可
@@ -70,37 +70,117 @@ export declare const READONLY_SYNC_ALLOWLIST: string[];
  * @returns 交给 oxlint 的 jsPlugins 数组
  */
 export declare function resolveJsPlugins(callerPlugins: NonNullable<OxlintConfig["jsPlugins"]> | undefined, resolve?: () => string): NonNullable<OxlintConfig["jsPlugins"]>;
+/**
+ * 组装全部常挂插件的 `jsPlugins`：sonarjs 走 {@link resolveJsPlugins} 的退路语义，
+ * 其余三条在调用方没有自带入口时从本包解析并前置。
+ *
+ * 调用方自带入口的判定按路径/别名子串（`pointsAtPlugin`）：这是能落进字符串判断的全部信号。
+ * 自带入口时**不再解析**本包那一份，避免同一个插件被挂两遍（两份插件对象会让同一条规则报两次）。
+ *
+ * 导出并把解析器做成可注入，是为了缺包分支在本仓可测：本仓 devDependencies 装着这四个包，
+ * 真实解析永远成功，失败支只能靠 stub 走到。
+ *
+ * @param callerPlugins - 调用方经 `jsPlugins` 传入的入口
+ * @param resolvers - 按插件 label 注入的入口解析器（生产用默认实现，测试注桩）
+ * @returns 交给 oxlint 的 jsPlugins 数组
+ */
+export declare function resolveBundledJsPlugins(callerPlugins: NonNullable<OxlintConfig["jsPlugins"]> | undefined, resolvers?: Record<string, () => string>): NonNullable<OxlintConfig["jsPlugins"]>;
+/**
+ * `eslint-plugin-regexp` recommended 里带 `regexp/` 前缀的全部规则（63 条）。
+ *
+ * 不带它同 preset 的 4 条裸 eslint 规则（no-control-regex / no-misleading-character-class /
+ * no-regex-spaces / prefer-regex-literals）：oxlint 的内建 eslint 插件已有同名规则，重复挂只会
+ * 把同一个缺陷报两遍。
+ *
+ * 实测（oxlint 1.90、9 包，含既有代码）：95 条命中，prod 34 / test 56 / 其余 5；其中 56 条所属
+ * 规则带 fixer（实测 oxlint 会执行 JS plugin 的 fixer，用 prefer-w 验过）。剩余非 fixer 的
+ * `no-super-linear-backtracking` 在测试文件里由 TEST_OVERRIDES 收窄（理由见 OFF_JUSTIFICATIONS）。
+ *
+ * `no-obscure-range` 允许本仓刻意使用的两个 CJK 范围：把 `[一-鿿]` 改写成 `\u4e00-\u9fff` 只会
+ * 让中文正则更难读，而这两个范围的语义在项目里是明确的。
+ */
+export declare const REGEXP_RULES: RuleTable;
+/**
+ * `eslint-plugin-zod` recommended 的 23 条里去掉 `consistent-schema-var-name` 后的 22 条
+ * （针对 zod 4）。
+ *
+ * 实测（oxlint 1.90、9 包）：
+ *  - `consistent-import` 默认要求 namespace import，与本仓统一的 `import { z } from "zod"` 冲突；
+ *    按参考仓的做法把 syntax 设成 named 后归零。
+ *  - `no-number-schema-with-int` 5 条（`z.number().int()` → `z.int()`，fixer 可修）。
+ *  - `require-error-message` 5 条待按代码补错误文案。
+ *  - `consistent-schema-var-name` 71 条**不挂**：本仓的 schema 常量是大写词（`MAX_DENIES_SCHEMA`、
+ *    `STATS_SNAPSHOT_SCHEMA`），规则的默认口径是把 `Schema` 后缀再拼一次，得到
+ *    `MAX_DENIES_SCHEMASchema` 这类坏名字；把它当命名缺陷改 71 处只是风格迁移，不指向缺陷。
+ *
+ * 该插件只对真的 import zod 的文件生效；本仓九个包都声明了 zod，规则面不会空转。
+ */
+export declare const ZOD_RULES: RuleTable;
+/**
+ * `@e18e/eslint-plugin` recommended 里**不与 oxlint 内建规则重复**的那一族。
+ *
+ * 刻意不挂的 9 条：
+ *  - 实测与内建规则同义，挂上会把同一条缺陷报两遍：`prefer-array-at`（unicorn/prefer-at）、
+ *    `prefer-array-some`（unicorn/prefer-array-some）、`prefer-date-now`（unicorn/prefer-date-now）、
+ *    `prefer-includes`（unicorn/prefer-includes / typescript/prefer-includes）、
+ *    `prefer-nullish-coalescing`（typescript/prefer-nullish-coalescing）、
+ *    `prefer-object-has-own`（eslint/prefer-object-has-own）、`prefer-regex-test`
+ *    （unicorn/prefer-regexp-test）、`prefer-spread-syntax`（unicorn/prefer-spread；某个消费方的
+ *    sidecar 已为后者做过文件级 off，再挂本条会把那个冲突原样带回来）。
+ *  - `prefer-string-fromcharcode` 与已启用的 `unicorn/prefer-code-point` **方向相反**：前者的
+ *    fixer 把 `String.fromCodePoint` 改回 `String.fromCharCode`，后者要求反过来。实测在一个
+ *    消费方上执行 `--fix` 会把 15 处 `fromCodePoint` 改写成 `fromCharCode`，其中含非 BMP
+ *    码点时运行语义会变，故整条不挂（不是"重复"，是互斥）。
+ *
+ * 实测非重复规则当前命中：`prefer-array-from-map` 25、`prefer-array-fill` 5（都带 fixer）；
+ * `ban-dependencies` 唯一命中落在某个消费方的脚本，由 SCRIPTS_OVERRIDES 收窄（理由见
+ * OFF_JUSTIFICATIONS）。
+ *
+ * `prefer-static-regex` 全仓 1778 条（生产 78、测试 1672、其余 28），且没有 fixer：基线全局
+ * off，只在 PROD_OVERRIDES 的生产文件上开。测试里的内联正则不构成性能问题，生产侧按代码提到
+ * 模块作用域。
+ */
+export declare const E18E_RULES: RuleTable;
 /**
  * oxlint 认识的 vitest 规则全集（取自 `oxlint --rules` 的表格，73 条）。整族在基线 off，再由
  * TEST_FILE_OVERRIDES 在用例文件上 on —— 理由见 OFF_JUSTIFICATIONS 里的 `vitest/*`。
  *
  * 这是一张**快照**，不是「上游新增规则自动落在生产文件之外」的机制：`categories` 是全局
  * error 开关，上游在任一 category 里新增 vitest 规则，它就会先作用到每一个 host.ts。
- * 拦这一步的是 test/config-oxlint.test.ts 的一致性用例——它拿 `oxlint --rules` 现量与
- * 本数组逐条对照，上游新增/删除规则即红，由人工同步名单（需要豁免的再补依据）。
+ * 拦这一步的是 test/config-oxlint.test.ts 的一致性用例——它拿 `oxlint --rules` 的实际输出与
+ * 本数组逐条对照，上游新增/删除规则即失败，由人工同步名单（需要豁免的再补依据）。
  */
 export declare const VITEST_ALL_RULES: string[];
 export declare const BASE_RULES: RuleTable;
 /**
- * 用例文件（含 `test/*.ts` 夹具与 helper）共享的豁免：规模类，以及「桩件要跨官方名义类型」
- * 的类型类判据。vitest 的用例结构类判据不在这里 —— 它们在基线整族 off、只在
- * TEST_FILE_OVERRIDES 里开回来，所以 helper 模块天然不在射程内，旧配置那份按目录豁免的
+ * 用例文件（含 `test/*.ts` 测试数据与 helper）共享的豁免：规模类，以及「stub 要跨官方名义类型」
+ * 的类型类判断。vitest 的用例结构类判断不在这里 —— 它们在基线整族 off、只在
+ * TEST_FILE_OVERRIDES 里开回来，所以 helper 模块天然不在范围内，旧配置那份按目录豁免的
  * TEST_HELPER_OVERRIDES 因此作废。
  */
 export declare const TEST_OVERRIDES: OxlintOverride;
 /**
- * vitest 的用例结构类判据**只**在这里生效。
+ * 生产代码面的 override：目前只有 `e18e/prefer-static-regex`。
+ *
+ * 该规则在全仓 1778 条（生产 78、测试 1672、其余 28），没有 fixer；全局 off、这里 on，
+ * 既保住「生产代码里的内联正则提到模块作用域」这条要求，又不把测试断言与构建脚本逼成
+ * 一堆模块级常量。`lib/**` 是各包的运行期模块（shared 的 build-* helper 也在 lib 下，
+ * 它们随包发布，按生产代码对待）；`host.ts` / `cli-main.ts` 是包根的生产入口。
+ */
+export declare const PROD_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` 报名字。
+ *    prefer-lowercase-title 给的同一个选项（官方例子就是 HTTP 方法前缀）。走 `titlePrefixes` 报名字。
  *    反过来的做法——把标题改成 `pTC` / `w5`——会把领域名字改成坏名字，本仓不采取。
  */
 export declare const VITEST_ASSERTION_DEFAULTS: string[];
@@ -116,7 +196,7 @@ export interface TestFileOverridesOptions {
     titlePrefixes?: string[];
 }
 /**
- * 生成用例文件的 override（vitest 结构类判据的开与关都在这张表里）。
+ * 生成用例文件的 override（vitest 结构类判断的开与关都在这张表里）。
  * @param opts - 本包需要用规则自带选项登记的名单（见文件头的两族说明）。
  * @returns 可直接放进 `overrides` 的配置项。
  */
@@ -133,8 +213,8 @@ export interface PluginLintOptions {
     offReasons?: Record<string, OffJustification>;
     /**
      * 本包"内部会断言"的用例 helper 名（如 `assertSameLedger`）。报进来的名字并入
-     * `vitest/expect-expect` 的 `assertFunctionNames`，规则本身保持 error —— 这是规则给的口径，
-     * 不是豁免。只收裸标识符，通配会掏空这条规则，直接抛。
+     * `vitest/expect-expect` 的 `assertFunctionNames`，规则本身保持 error —— 这是规则自带的机制，
+     * 不是豁免。只收裸标识符，通配会让这条规则失去作用，直接抛。
      */
     assertionHelpers?: string[];
     /** 允许开头的用例标题大写术语（`PTC`/`W5`/`B1` 这类档位或模式名），进 allowedPrefixes。 */

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

@@ -9,12 +9,12 @@ type PackageConfig = ViteUserConfig;
 type TestConfig = NonNullable<PackageConfig["test"]>;
 type CoverageConfig = NonNullable<TestConfig["coverage"]>;
 /**
- * 覆盖率覆盖项的形状。`include` 不在其中：统计面由 `coverageInclude` 单源供给，两处各写一份
+ * 覆盖率覆盖项的形状。`include` 不在其中：统计范围由 `coverageInclude` 单独供给，两处各写一份
  * 必然漂移。覆盖率对象整块替换会让四项 100% 阈值与排除表静默消失，所以覆盖项不走 `test`
  * 展开，而是逐键合并；`thresholds` 之内也逐键合并，单项可改、其余三项删不掉。
  */
 type CoverageOverride = Omit<Partial<CoverageConfig>, "include">;
-/** 覆盖率面与 test 块里真正因包而异的那一项。 */
+/** 公共覆盖率配置与 test 块里真正因包而异的那一项。 */
 export interface PackageVitestOptions {
     /** `coverage.include` —— 本包该被统计的源文件（各包只有这里不同）；空数组/空串在工厂即抛。 */
     coverageInclude: string[];
@@ -24,7 +24,7 @@ export interface PackageVitestOptions {
     test?: PackageConfig["test"];
 }
 /**
- * 公共面：各份配置里逐字相同的那部分，从今往后只有一处。
+ * 公共部分：各份配置里逐字相同的那部分，从今往后只有一处。
  * `testTimeout: 20_000` 是各包共同值（vitest 默认 5000）；继承它只会放宽不会收紧，
  * 故不会把任何已过用例变成不稳定。
  */

package/dist/types/errors.d.ts

@@ -1,18 +1,18 @@
 /**
  * 把捕获到的值渲染成一段人读文本。
  * `Error` 取 message（空串时回退 name）并接上 cause 链；`AggregateError` 附上成员；
- * 非 Error 但带可读 message 属性的取该属性，其余按 `String()` 兜底。
- * 全程不抛异常：敌意输入降级为占位文本。
+ * 非 Error 但带可读 message 属性的取该属性，其余按 `String()` 处理。
+ * 全程不抛异常：恶意输入改用占位文本。
  * @param error - 捕获到的值（catch 里的 `unknown`）。
  * @returns 可直接进界面通知或日志的文本。
  */
 export declare function errorText(error: unknown): string;
 /**
- * 是不是「设置冲突」那一类失败（宿主在两个界面同时改同一份设置时抛的形）。
+ * 是不是「设置冲突」那一类失败（宿主在两个界面同时改同一份设置时抛出的那种失败）。
  *
- * 认两枚痕迹而不是 `instanceof`：跨 realm 抛过来的错误类不是同一个构造函数，而
- * `code`/`name` 是宿主两边都写的那两个值。经 `fieldOf` 读——它的探测出口把敌意
- * getter / Proxy 陷阱的抛错塌成「取不到」，判定面因此天然只回答是/否，不外抛。
+ * 认两处痕迹而不是 `instanceof`：跨 realm 抛过来的错误类不是同一个构造函数，而
+ * `code`/`name` 是宿主两边都写的那两个值。经 `fieldOf` 读——它的带保护出口把恶意
+ * getter / Proxy trap 的抛错变成「取不到」，判定因此天然只回答是/否，不外抛。
  * @param error 捕获到的值
  * @returns 该失败是否应当按「设置已被别处改动」处理
  */

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

@@ -2,34 +2,34 @@ import type { ShellProcess } from "@deepseek-ai/dsh-shell";
 import type { JobOutcome } from "@deepseek-ai/dsh-jobs";
 /**
  * 官方结局类型在这里再出一个具名出口。`jobOutcomeOf` 的返回类型就是它，消费方把它写进自己的
- * 签名（生产者回调、测试断言）时若没有具名出口，只能把结构重述一遍——而重述正是本包要收敛掉的。
+ * 签名（生产者回调、测试断言）时若没有具名出口，只能把结构重述一遍——而重述正是本包要消除的。
  */
 export type { JobOutcome } from "@deepseek-ai/dsh-jobs";
-/** 映射只用得到的三个成员（不是整个 ShellProcess：生产者句柄的其余面与本函数无关）。 */
+/** 映射只用得到的三个成员（不是整个 ShellProcess：生产者句柄的其余成员与本函数无关）。 */
 export type SettledProcess = Pick<ShellProcess, "status" | "exitCode" | "signal">;
 /**
- * 落定进程 → 作业结局。
- * @param proc 已落定的子进程句柄（`done` 已 resolve 之后再读，值才是终态）
+ * 已结束进程 → 作业结局。
+ * @param proc 已结束的子进程句柄（`done` 已 resolve 之后再读，值才是终态）
  * @returns 交给 {@link JobRegistry} 生产者的结局：killed / completed，理由在 detail
  */
 export declare function jobOutcomeOf(proc: SettledProcess): JobOutcome;
 /**
- * 只用得到的那一个成员。**不按 `ShellProcess` 整型收**：官方的 `kill` 返回 `Promise<boolean>`，
+ * 只用得到的那一个成员。**不按 `ShellProcess` 整个收**：官方的 `kill` 返回 `Promise<boolean>`，
  * 把那个返回类型写进签名等于要求每个调用方（含测试替身）都得交回一个 Promise，
- * 而这里真正需要的只是「有一个可以试着调的 kill」——返回值要么被丢弃，要么被收掉拒绝。
+ * 而这里真正需要的只是「有一个可以试着调的 kill」——返回值要么被丢弃，要么把拒绝接管下来。
  */
 export interface KillableProcess {
     kill: () => unknown;
 }
 /**
- * 收掉子进程，**忽略失败**：进程可能已自然退出或已被系统回收，此时 kill 失败不是本包的失败。
+ * 终止子进程，**忽略失败**：进程可能已自然退出或已被系统回收，此时 kill 失败不是本包的失败。
  *
- * 为什么不向调用方通报：调用点都在清理臂（卸载、被拒、超时）上，那里没有可行动的下一步；
- * 把异常抛出去只会让清理链半途而废，留下更难的现场。
+ * 为什么不向调用方通报：调用点都在清理分支（卸载、被拒、超时）上，那里没有可行动的下一步；
+ * 把异常抛出去只会让清理链半途而废，留下更难处理的现场。
  *
- * 同步抛错与**异步拒绝**都要收：官方句柄的 `kill` 返回 `Promise<boolean>`，同步 try/catch
- * 只拦得住前者，返回的 Promise 拒绝会一路逃到进程级 unhandledRejection——清理臂不该有能力
+ * 同步抛错与**异步拒绝**都要处理：官方句柄的 `kill` 返回 `Promise<boolean>`，同步 try/catch
+ * 只拦得住前者，返回的 Promise 拒绝最终会变成进程级 unhandledRejection——清理分支不该有能力
  * 把宿主进程的未处理拒绝计数器推高。
- * @param proc 待收的句柄
+ * @param proc 待清理的句柄
  */
 export declare function killProc(proc: KillableProcess): void;

package/dist/types/jsonl.d.ts

@@ -1,8 +1,8 @@
 /**
  * 反复保留后半行段直到 UTF-8 字节数 ≤ `maxBytes`；行数 ≤2 时停手（单条超限行原样保留，
- * 防死循环也防清空文件）。未超限直接返回入参**同一引用**，调用方可据此跳过写盘。
+ * 防死循环也防清空文件）。未超限直接返回入参**同一引用**，调用方可据此跳过磁盘写入。
  *
- * **配额必须是有限数**（这一档由调用方保证，本函数不代为归一）：
+ * **配额必须是有限数**（这一点由调用方保证，本函数不代为归一）：
  *   - `0` 与负数**照样收缩**到 ≤2 行为止——「0 = 永不截断」是某消费方在**调用前**
  *     `maxBytes > 0` 那道触发策略的承诺，不是本函数的语义（见它自己的 jsonl-fuse 头注）。
  *     把 0 当成「不裁」会把这个承诺写成一个假象。
@@ -11,14 +11,14 @@
      另一个在调用前就把非有限值与负数归一成 0。但那道归一在**消费方**，本包并不强制——
      新增消费方时没有任何东西会提醒它。
  *
- * 为什么不在这种预算上抛错拒收：抛错会被两个消费方各自的 catch 接走（一个上抛、一个内部吞），
+ * 为什么不在这种预算上抛错拒收：抛错会被两个消费方各自的 catch 接走（一个向外抛、一个内部捕获），
  * 等于把一条清晰的预算错误变成一次静默跳过，排查方向反而更差。这里"不设限"只是「这次不裁」，
- * 不像读请求体那样会同时放开内存上限，所以没有必须拒收的那条失败模型。形状不同的同一种错，
- * 各按各的失败模型处理。
+ * 不像读请求体那样会同时放开内存上限，所以没有必须拒收的那条失败方式。表现不同的同一种错，
+ * 各按各的失败方式处理。
  *
  * 两个消费方的具体调用点与配额归一位置记在 test/jsonl.test.ts 的同名用例里——这一段
  * 不出现兄弟包标识符：声明上的 JSDoc 会被 tsc 抄进 dist/types/*.d.ts 一起发出去，
- * 包名会让装了这个包的消费方以为存在一个并不存在的依赖（test/publish-manifest.test.ts 会红）。
+ * 包名会让装了这个包的消费方以为存在一个并不存在的依赖（test/publish-manifest.test.ts 会判定失败）。
  *
  * @param text 整份 JSONL 文本
  * @param maxBytes 字节上限；调用方须保证是有限数

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

@@ -1,8 +1,8 @@
 /**
  * 执行一次 lesson bus 调用，并把两类失败归到同一个出口。
  * @param call - 真正的调用（同步返回或返回 Promise 都接受）。
- * @param onFailure - 失败收口：同步抛错与异步拒绝都会到这里，且各自只被调一次。
- *   返回类型写 `unknown` 而不是 `void`：签名不能让"收口是 async 函数"变成类型错误，
+ * @param onFailure - 失败处理：同步抛错与异步拒绝都会到这里，且各自只被调一次。
+ *   返回类型写 `unknown` 而不是 `void`：签名不能让"失败处理是 async 函数"变成类型错误，
  *   而它返回的 Promise 由 report 接管（见该函数的注释），调用方不必也不该自己等它。
  */
 export declare function settleLessonCall(call: () => unknown, onFailure: (reason: unknown) => unknown): void;

package/dist/types/locale.d.ts

@@ -8,10 +8,10 @@ export type Locale = BuiltInLocaleId;
 /** 缺省语言。设置项未设或值不合语法时落到这里。 */
 export declare const DEFAULT_LOCALE: Locale;
 /**
- * 官方 `@deepseek-ai/dsh-client-locale` 拥有的 settings 命名空间与字段名。那两枚常量官方
- * 也外销（同包的根入口），这里**不引它而是抄字面量**：引它就得把 client 包变成 host 半的运行期
+ * 官方 `@deepseek-ai/dsh-client-locale` 拥有的 settings 命名空间与字段名。那两个常量官方
+ * 也导出（同包的根入口），这里**不引它而是抄字面量**：引它就得把 client 包变成宿主侧的运行期
  * 依赖，而这两个值是纯字符串常量、不参与任何 client 行为。两侧必须逐字同名才读得到同一份偏好，
- * 所以这条耦合是本包 README 的登记项：官方那两枚常量一旦改名，本包必须同步改。
+ * 所以这条耦合是本包 README 的登记项：官方那两个常量一旦改名，本包必须同步改。
  */
 export declare const LOCALE_SETTINGS_NAMESPACE = "locale";
 export declare const LOCALE_PREFERENCE_FIELD = "preference";
@@ -19,7 +19,7 @@ export declare const LOCALE_PREFERENCE_FIELD = "preference";
  * 一个包的全部消息键值表（键名即语义，值是人读文案）。
  *
  * 键集绑 `Locale` 而不是手写 `{ zh; en }`：本文件的 `Locale` 已改成官方 `BuiltInLocaleId`
- * 的别名，宿主哪天加一门语言，这两处必须**一起**响——只改 `Locale` 而把键集钉死成
+ * 的别名，宿主哪天加一门语言，这两处必须**一起**响——只改 `Locale` 而把键集锁死成
  * `{ zh; en }`，新增那门语言会静默取不到文案（`messagesFor` 的 else 分支落回 zh）。
  * `Record` 与原 interface 在当前 `Locale`（恰为 `"zh"｜"en"`）下结构等价，消费方字面量
  * 无需改动；差别只在宿主扩宽那一刻，从「静默回落」变成「编译报错」。
@@ -27,7 +27,7 @@ export declare const LOCALE_PREFERENCE_FIELD = "preference";
  * 值域收在 string 上，用**同构映射类型**而不是 `Record<string, string>`：实测（tsc）消费方
  * 全部用 `interface Messages { readonly xxx: string }` 声明，而 interface **拿不到**隐式索引
  * 签名——写成 `Messages extends Record<string, string>` 会让全部消费方 TS2322，那是外溢到
- * 9 个包的破坏性变更。映射类型对 interface 与 type 都成立（test/type-guards.test.ts 钉住）。
+ * 9 个包的破坏性变更。映射类型对 interface 与 type 都成立（test/type-guards.test.ts 固定）。
  * 收窄前实测到的缺口：`messagesFor({ zh: { g: 1 }, en: { g: "x" } }, "zh")` 零错误通过，即文件头
  * 「值不是字符串都在 tsc 阶段就红」原本只在消费方自己声明 `Messages` 时才成立。
  */
@@ -37,15 +37,15 @@ export type MessagesCatalog<Messages> = Record<Locale, {
 /**
  * 把设置里的原始值归一成受支持的 locale：只取**主语言子标签**判定（`en-US`、`zh-Hans-CN`
  * 都落位到 `en` / `zh`），没有「先按完整标签匹配」那一层——受支持的语言只有 `zh` 与 `en`
- * 两个主标签，完整标签匹配不会多认出任何一个，反而要多维护一张表。判不出来一律退
- * DEFAULT_LOCALE——文案语言不该成为报错面。
+ * 两个主标签，完整标签匹配不会多认出任何一个，反而要多维护一张表。判不出来一律回退到
+ * DEFAULT_LOCALE——文案语言不该成为报错来源。
  * @param raw - 设置里的原始值，类型不可信（来自用户文档）。
  * @returns 归一后的 locale。
  */
 export declare function resolveLocale(raw: unknown): Locale;
 /**
  * 从 `ctx.settings.describe(LOCALE_SETTINGS_NAMESPACE)` 的返回值里取偏好并归一。
- * describe 出来的形状由别的包拥有，所以入参按 unknown 处理：非对象、数组、缺字段
+ * describe 出来的结构由别的包拥有，所以入参按 unknown 处理：非对象、数组、缺字段
  * 都走默认语言，不抛。
  * @param described - describe 的原始返回值（可能 undefined）。
  * @returns 归一后的 locale。
@@ -57,7 +57,7 @@ export declare function resolveLocalePreference(described: unknown): Locale;
  * 按 `locale` 直接索引而不是 `locale === "en" ? … : …` 的二元分派：后者的 else 分支
  * 把「非 en 即 zh」这个假设写死在运行期，`Locale` 扩宽时它**照样编译通过**，新增那门
  * 语言静默拿不到文案。与 `MessagesCatalog` 的 `Record<Locale, …>` 合起来，
- * 扩宽会在 `catalog[locale]` 这一处落成 TS2322。
+ * 扩宽会在 `catalog[locale]` 这一处报出 TS2322。
  * @param catalog - 各语言齐全的消息表。
  * @param locale - 已归一的语言。
  * @returns 对应语言的消息表（引用返回，不做拷贝）。

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

@@ -1,14 +1,15 @@
 /**
- * 可注入面。`realpath` 是同步 fs 调用，`sep` 决定**整条**路径语义臂：分隔符字形与 `resolve`
- * 用的那套解析都由它选。两者注入是为了让两条臂在任何 runner 上都可判定——`path.sep` 在模块
- * 装载时就定死了，而只注入字形会让非 POSIX runner 上的 POSIX 用例拿到原生解析结果，键随之漂移。
+ * 可注入的选项。`realpath` 是同步 fs 调用，`sep` 决定**整条**路径语义分支：分隔符字形与
+ * `resolve` 用的那套解析都由它选。两者注入是为了让两条分支在任何 runner 上都可判定——
+ * `path.sep` 在模块装载时就定死了，而只注入字形会让非 POSIX runner 上的 POSIX 用例拿到
+ * 原生解析结果，键随之漂移。
  */
 export interface ProjectKeyOptions {
     realpath?: (target: string) => string;
     sep?: string;
 }
 /**
- * cwd → 项目桶键。非字符串 / trim 后为空 / 归一后落到根目录 → `"default"`
- * （与记忆网关的兜底桶名一致）。
+ * cwd → 项目键。非字符串 / trim 后为空 / 归一后落到根目录 → `"default"`
+ * （与记忆网关的回退键名一致）。
  */
 export declare function deriveProjectKey(cwd: unknown, opts?: ProjectKeyOptions): string;

package/dist/types/record.d.ts

@@ -1,41 +1,41 @@
 /** 对象类型守卫：非 `null` 的 `object` 且非数组（`Record` 索引签名投影的基础）。 */
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
 /**
- * 服务面校验：对象存在且**声明的每个方法**都可调用。
+ * 服务可用性校验：对象存在且**声明的每个方法**都可调用。
  *
- * 只做 `typeof value["shell"] === "object"` 的话，守卫声称的是「有这个服务」而实际证明的只是
- * 「有个对象」——运行到一半才炸。逐个点名方法，守卫才名副其实。
+ * 只做 `typeof value["shell"] === "object"` 的话，检查声称的是「有这个服务」而实际证明的只是
+ * 「有个对象」——运行到一半才报错。逐个写出方法名，检查才名副其实。
  *
  * `Object.prototype` 的默认成员不算服务实现：`hasMethods({}, ["toString"])` 若照单全收，
- * 一个普通对象就能冒充服务面。判据是**身份**——解析到的函数正是 `Object.prototype` 上
- * 那一枚才排除，所以类/中间原型上的真实实现（包括对原型成员的重写）照常可识别，
- * cordis 方法挂在原型上的承重面不受影响。
+ * 一个普通对象就能冒充服务。判断是**身份**——解析到的函数正是 `Object.prototype` 上
+ * 那一个才排除，所以类/中间原型上的真实实现（包括对原型成员的重写）照常可识别，
+ * cordis 方法挂在原型上的读取不受影响。
  * @param value 待验证的服务候选（来自 `ctx.get(...)` 的 unknown）
- * @param methods 该服务面必须可调用的方法名
- * @returns 是否为可用的服务面
+ * @param methods 该服务必须可调用的方法名
+ * @returns 是否为可用的服务
  */
 export declare function hasMethods(value: unknown, methods: readonly string[]): boolean;
 /**
  * 从 `unknown` 投影单个字段；非 `Record` → `undefined`。
  *
- * ⚠ **取值走原型链，这是承重的，不是疏忽**：`value[key]` 不做 `hasOwn` 判定，所以原型上的
- * 方法照样取得到。消费方正靠这一条做**能力探测**——cordis 服务对象的方法挂在原型上、不是
+ * ⚠ **取值走原型链，这是有意为之，不是疏忽**：`value[key]` 不做 `hasOwn` 判定，所以原型上的
+ * 方法照样取得到。消费方正靠这一条做**能力检查**——cordis 服务对象的方法挂在原型上、不是
  * 自有键，形如 `typeof fieldOf(settings, "describe") === "function"`、
  * `hasMethods(fieldOf(value, "timer"), ["timeout"])`、`typeof fieldOf(session,
  * "snapshotEvents") === "function"`（消费包的调用点记在 test/record.test.ts）。
  * 改成 `Object.hasOwn` 会让上面几处**一律判否**，那些包随即认不出合法的 cordis 服务——
- * 而这类误判的表现是「能力探测静默返回 false」，不是报错，极难往这里归因。
+ * 而这类误判的表现是「能力检查静默返回 false」，不是报错，极难往这里归因。
  *
  * 代价是明写在这里：键名取到的是原型成员时（`fieldOf({}, "__proto__")` 交回
  * `Object.prototype`、`fieldOf({}, "constructor")` 交回 `Object`）。这是本函数的取舍，
  * 不是让消费方猜的属性——现存调用点的键名全是字面量，没有一处来自数据。
- * test/record.test.ts 两侧都钉住了：原型方法取得到（承重面），自有键优先于原型键。
+ * test/record.test.ts 两侧都有用例固定：原型方法取得到（这是关键行为），自有键优先于原型键。
  *
- * ⚠ 本段刻意不点名兄弟包：**声明上的 JSDoc 会被 tsc 抄进 dist/types/record.d.ts 一起
+ * ⚠ 本段刻意不写出兄弟包的名字：**声明上的 JSDoc 会被 tsc 抄进 dist/types/record.d.ts 一起
  * 发出去**，包名会让装了这个包的消费方以为存在一个并不存在的依赖
- *（test/publish-manifest.test.ts 的产物面判据会红）。要写具体调用点就写在 test/ 里。
+ *（test/publish-manifest.test.ts 的产物检查会判定失败）。要写具体调用点就写在 test/ 里。
  *
- * 读取走的是探测式出口：被测对象带抛错 getter / Proxy 陷阱时按「取不到」交回
- * `undefined`，异常不冒泡（能力探测不该把流程炸掉）。
+ * 读取走的是带保护的出口：被测对象带抛错 getter / Proxy trap 时按「取不到」交回
+ * `undefined`，异常不冒泡（能力检查不该打断流程）。
  */
 export declare function fieldOf(value: unknown, key: string): unknown;

package/dist/types/text.d.ts

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