dsh-thesis 1.0.0

package/lib/shared/define-tool.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 工具定义器：**生产用宿主的 `defineTool`，离线用本地等价实现**。
+ *
+ * 为什么需要它：本插件的工具定义用的是 DSH 的作者侧 schema DSL（`required: true`
+ * 是**每个属性**的注解，不是 JSON Schema 的 `required` 数组），必须编译成宿主
+ * 认可的 JSON Schema 子集后才能交给 `ctx.tools.register`。这个编译步骤由
+ * `@deepseek-ai/dsh-tools` 的 `defineTool` 完成——但它是**运行时**依赖：
+ * 在没有宿主的离线环境（`npm test`、评审、CI）里 import 它会直接 ERR_MODULE_NOT_FOUND，
+ * 于是所有注册工具的模块都无法被单测加载，装配测试也写不出来。
+ *
+ * 解法是双模：
+ * - **生产**：动态 import 宿主的 `defineTool`，行为与 DSH 第一方插件完全一致
+ *   （含宿主自己的参数校验与 `ToolArgsError`）；
+ * - **离线**：退回本文件里的等价实现，覆盖本插件实际使用的 DSL 子集
+ *   （string/number/integer/boolean/array/object/json/oneOf/enum/const + 注解），
+ *   并提供同样的"参数违规 → `INVALID_ARGS`"行为。
+ *
+ * 编译结果的一致性由两件事兜底：① `tests/shared-define-tool.test.ts` 逐例断言
+ * 编译产物；② `scripts/host-smoke.mjs` 在真实 DSH 宿主上注册并执行工具（见 README「开发」）。
+ *
+ * @module dsh-thesis/shared/define-tool
+ */
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+/** 作者侧值 schema（本插件用到的子集）。 */
+interface ValueSpec {
+    type?: string;
+    description?: string;
+    title?: string;
+    default?: unknown;
+    examples?: unknown;
+    enum?: readonly unknown[];
+    const?: unknown;
+    items?: ValueSpec;
+    properties?: Record<string, ValueSpec & {
+        required?: true;
+    }>;
+    additionalProperties?: boolean;
+    oneOf?: readonly ValueSpec[];
+    required?: true;
+}
+/** 工具定义（作者侧形态）。 */
+export interface PaperToolOptions {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Record<string, ValueSpec & {
+        required?: true;
+    }>;
+    readonly output: {
+        readonly schema: ValueSpec;
+        render(args: any, value: any): Array<{
+            type: 'text';
+            text: string;
+        }>;
+    };
+    execute(args: any, exec: ToolExecution): Promise<unknown>;
+}
+/** 把作者侧的隐式开放参数对象编译成根级 JSON Schema。 */
+export declare function compileParameterSchema(spec: Record<string, ValueSpec & {
+    required?: true;
+}>): Record<string, unknown>;
+/** 编译输出 schema。 */
+export declare function compileValueSchema(spec: ValueSpec): Record<string, unknown>;
+/** 参数违规：与宿主同名的错误码，便于 UI/日志统一识别。 */
+export declare class PaperToolArgsError extends Error {
+    readonly code = "INVALID_ARGS";
+    readonly violations: string[];
+    constructor(violations: string[]);
+}
+/** 是否运行在真实宿主内（供工具返回值与测试断言使用）。 */
+export declare const usingHostDefineTool: boolean;
+/**
+ * 定义一个模型工具。
+ *
+ * 优先宿主实现（与 DSH 第一方插件完全一致），离线退回本地等价实现。
+ */
+export declare function definePaperTool(options: PaperToolOptions): unknown;
+export {};

package/lib/shared/define-tool.js

@@ -0,0 +1,235 @@
+/**
+ * 工具定义器：**生产用宿主的 `defineTool`，离线用本地等价实现**。
+ *
+ * 为什么需要它：本插件的工具定义用的是 DSH 的作者侧 schema DSL（`required: true`
+ * 是**每个属性**的注解，不是 JSON Schema 的 `required` 数组），必须编译成宿主
+ * 认可的 JSON Schema 子集后才能交给 `ctx.tools.register`。这个编译步骤由
+ * `@deepseek-ai/dsh-tools` 的 `defineTool` 完成——但它是**运行时**依赖：
+ * 在没有宿主的离线环境（`npm test`、评审、CI）里 import 它会直接 ERR_MODULE_NOT_FOUND，
+ * 于是所有注册工具的模块都无法被单测加载，装配测试也写不出来。
+ *
+ * 解法是双模：
+ * - **生产**：动态 import 宿主的 `defineTool`，行为与 DSH 第一方插件完全一致
+ *   （含宿主自己的参数校验与 `ToolArgsError`）；
+ * - **离线**：退回本文件里的等价实现，覆盖本插件实际使用的 DSL 子集
+ *   （string/number/integer/boolean/array/object/json/oneOf/enum/const + 注解），
+ *   并提供同样的"参数违规 → `INVALID_ARGS`"行为。
+ *
+ * 编译结果的一致性由两件事兜底：① `tests/shared-define-tool.test.ts` 逐例断言
+ * 编译产物；② `scripts/host-smoke.mjs` 在真实 DSH 宿主上注册并执行工具（见 README「开发」）。
+ *
+ * @module dsh-thesis/shared/define-tool
+ */
+/** 编译期错误：作者写错了 schema（与宿主一样，装配时大声失败）。 */
+function authorError(message) {
+    throw new Error(`dsh-thesis defineTool: ${message}`);
+}
+function copyAnnotations(from, to) {
+    for (const key of ['description', 'title', 'default', 'examples']) {
+        if (from[key] !== undefined)
+            to[key] = from[key];
+    }
+}
+/** 把「属性映射 + 逐属性 required」编译成 `{properties, required}` 形式。 */
+function compilePropertyMap(spec, path) {
+    const properties = {};
+    const required = [];
+    for (const [name, raw] of Object.entries(spec ?? {})) {
+        if (raw === null || typeof raw !== 'object')
+            authorError(`${path}.${name} 必须是对象`);
+        const { required: isRequired, ...rest } = raw;
+        if (isRequired === true)
+            required.push(name);
+        properties[name] = compileValue(rest, `${path}.${name}`);
+    }
+    return {
+        properties: Object.keys(properties).length > 0 ? properties : undefined,
+        required: required.length > 0 ? required : undefined,
+    };
+}
+/** 编译一个值 schema 节点。 */
+function compileValue(spec, path) {
+    if (spec === null || typeof spec !== 'object')
+        authorError(`${path} 必须是对象`);
+    const out = {};
+    copyAnnotations(spec, out);
+    if (spec.oneOf !== undefined) {
+        if (!Array.isArray(spec.oneOf) || spec.oneOf.length < 2)
+            authorError(`${path}.oneOf 至少需要两个分支`);
+        out.oneOf = spec.oneOf.map((branch, index) => compileValue(branch, `${path}.oneOf[${index}]`));
+        return out;
+    }
+    const type = spec.type;
+    if (type === undefined)
+        authorError(`${path} 缺少 type`);
+    // 作者专用：只作注解，不施加约束（对应宿主把 json 节点编译为注解式 schema）。
+    if (type === 'json')
+        return out;
+    out.type = type;
+    if (spec.enum !== undefined)
+        out.enum = spec.enum;
+    if (spec.const !== undefined)
+        out.const = spec.const;
+    if (type === 'object') {
+        // 与宿主作者侧契约一致：object 必须显式声明开放性（additionalProperties: boolean），
+        // 避免"忘了写"被静默解释成任一种语义。
+        if (typeof spec.additionalProperties !== 'boolean') {
+            authorError(`${path}: type 'object' 必须显式声明 additionalProperties（true=开放 / false=封闭）`);
+        }
+        const compiled = compilePropertyMap(spec.properties ?? {}, path);
+        if (compiled.properties !== undefined)
+            out.properties = compiled.properties;
+        if (compiled.required !== undefined)
+            out.required = compiled.required;
+        out.additionalProperties = spec.additionalProperties;
+    }
+    else if (type === 'array') {
+        if (spec.items !== undefined)
+            out.items = compileValue(spec.items, `${path}.items`);
+    }
+    return out;
+}
+/** 把作者侧的隐式开放参数对象编译成根级 JSON Schema。 */
+export function compileParameterSchema(spec) {
+    const compiled = compilePropertyMap(spec, 'parameters');
+    return {
+        type: 'object',
+        ...compiled.properties !== undefined ? { properties: compiled.properties } : {},
+        ...compiled.required !== undefined ? { required: compiled.required } : {},
+    };
+}
+/** 编译输出 schema。 */
+export function compileValueSchema(spec) {
+    return compileValue(spec, 'schema');
+}
+// ---------------------------------------------------------------------------
+// 离线参数校验（等价于宿主 defineTool 内部对模型实参的校验）
+// ---------------------------------------------------------------------------
+function describe(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+function jsonTypeOf(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    if (typeof value === 'number')
+        return Number.isInteger(value) ? 'integer' : 'number';
+    return typeof value;
+}
+function typeMatches(schema, value) {
+    const expected = schema.type;
+    if (expected === undefined)
+        return true;
+    const actual = jsonTypeOf(value);
+    if (expected === 'number')
+        return actual === 'number' || actual === 'integer';
+    if (expected === 'integer')
+        return actual === 'integer';
+    if (expected === 'null')
+        return actual === 'null';
+    // 注解式 json 节点不约束类型。
+    if (expected === 'json')
+        return true;
+    return actual === expected;
+}
+/** 递归校验一个值；返回路径限定的违规列表（空数组 = 通过）。 */
+function validateValue(schema, value, path) {
+    const violations = [];
+    const oneOf = schema.oneOf;
+    if (oneOf !== undefined) {
+        const ok = oneOf.some(branch => validateValue(branch, value, path).length === 0);
+        if (!ok)
+            violations.push(`${path || '(root)'} 不满足 oneOf 的任何一个分支`);
+        return violations;
+    }
+    if (!typeMatches(schema, value)) {
+        violations.push(`${path || '(root)'} 期望 ${String(schema.type)}，实际 ${describe(value)}`);
+        return violations;
+    }
+    const enumValues = schema.enum;
+    if (enumValues !== undefined && !enumValues.some(candidate => Object.is(candidate, value))) {
+        violations.push(`${path || '(root)'} 取值不在枚举内（${enumValues.map(v => JSON.stringify(v)).join(' / ')}）`);
+    }
+    if (schema.type === 'object' && value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        const record = value;
+        const required = schema.required ?? [];
+        for (const name of required) {
+            if (record[name] === undefined)
+                violations.push(`${path ? `${path}.` : ''}${name} 为必填参数`);
+        }
+        const properties = schema.properties ?? {};
+        for (const [name, childSchema] of Object.entries(properties)) {
+            const child = record[name];
+            if (child === undefined)
+                continue;
+            violations.push(...validateValue(childSchema, child, path ? `${path}.${name}` : name));
+        }
+    }
+    if (schema.type === 'array' && Array.isArray(value)) {
+        const items = schema.items;
+        if (items !== undefined) {
+            value.forEach((item, index) => {
+                violations.push(...validateValue(items, item, `${path}[${index}]`));
+            });
+        }
+    }
+    return violations;
+}
+/** 参数违规：与宿主同名的错误码，便于 UI/日志统一识别。 */
+export class PaperToolArgsError extends Error {
+    code = 'INVALID_ARGS';
+    violations;
+    constructor(violations) {
+        super(`invalid arguments: ${violations.join('; ')}`);
+        this.name = 'PaperToolArgsError';
+        this.violations = violations;
+    }
+}
+/** 离线实现：编译 + 校验 + 返回注册就绪的定义。 */
+function localDefineTool(options) {
+    const parameters = compileParameterSchema(options.parameters);
+    const outputSchema = compileValueSchema(options.output.schema);
+    const render = options.output.render;
+    return {
+        name: options.name,
+        description: options.description,
+        parameters,
+        output: { schema: outputSchema, render: (args, value) => render(args, value) },
+        async execute(args, exec) {
+            const violations = validateValue(parameters, args, '');
+            if (violations.length > 0)
+                throw new PaperToolArgsError(violations);
+            return options.execute(args, exec);
+        },
+    };
+}
+/**
+ * 生产用宿主 `defineTool`，离线为 `undefined`。
+ *
+ * 顶层 await 的代价是一次模块加载；收益是「离线可测」与「生产同源」两者兼得。
+ */
+let hostDefineTool;
+try {
+    const host = await import('@deepseek-ai/dsh-tools');
+    if (typeof host.defineTool === 'function') {
+        hostDefineTool = host.defineTool;
+    }
+}
+catch {
+    hostDefineTool = undefined;
+}
+/** 是否运行在真实宿主内（供工具返回值与测试断言使用）。 */
+export const usingHostDefineTool = hostDefineTool !== undefined;
+/**
+ * 定义一个模型工具。
+ *
+ * 优先宿主实现（与 DSH 第一方插件完全一致），离线退回本地等价实现。
+ */
+export function definePaperTool(options) {
+    return hostDefineTool !== undefined ? hostDefineTool(options) : localDefineTool(options);
+}

package/lib/shared/fs-errors.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 文件系统错误分类：**区分「不存在」与「读失败」**。
+ *
+ * 这是本插件最容易出人命的一处细节。工作区里的文件都是学生的真实资产
+ * （追问答案、进度台账、文献库、检索缓存），而几乎所有读路径的写法都是：
+ *
+ * ```ts
+ * try { return await fs.readText(...) } catch { return undefined }   // ✗ 危险
+ * ```
+ *
+ * 这种写法把「文件不存在（第一次运行，正常）」和「文件存在但读不出来
+ * （权限、IO 错误、句柄失效）」折叠成同一个 `undefined`，调用方于是认为
+ * 「还没建过」，转身用默认值把它**覆盖写回**——学生的数据就没了。
+ *
+ * 正确做法：只有**确认不存在**才当作 `undefined`，其余错误一律上抛，
+ * 让工具以可读错误告知用户。宿主与各测试夹具的错误码不同，故在此集中判定。
+ *
+ * @module dsh-thesis/shared/fs-errors
+ */
+/** 各实现使用的「目标不存在」错误码。 */
+export declare const MISSING_CODES: readonly string[];
+/**
+ * 该错误是否表示「目标不存在」？
+ *
+ * 判据按可靠性排序：错误码 → 消息里的 `ENOENT` / `not found` / `不存在`。
+ * 消息回退是必要的：某些后端（含部分测试替身）不带错误码。
+ */
+export declare function isMissingError(error: unknown): boolean;
+/**
+ * 该错误是否表示「调用被取消」。
+ *
+ * 取消与失败必须分开处理：把 `AbortError` 当成「文件不存在」会让取消变成静默继续，
+ * 当成「检索源失败」又会让取消变成一条误导性的网络错误。`fetch` 与宿主 fs 在取消时
+ * 抛的都是 `name === 'AbortError'` 的错误。
+ */
+export declare function isAbortError(error: unknown): boolean;
+/**
+ * 读取一个「存在则读、不存在则 undefined」的文件；**其余错误原样抛出**。
+ *
+ * @param read 实际的读取动作（通常包住 `fs.resolve` + `fs.readText`）。
+ * @param onMissing 命中「不存在」时的返回值，缺省 `undefined`。
+ */
+export declare function readOrUndefined<T>(read: () => Promise<T>, onMissing?: T | undefined): Promise<T | undefined>;
+/**
+ * 把读取错误包装成给用户看的可读消息（工具层用）。
+ *
+ * 关键是把「读不出来」和「还没建过」在**文案上**也区分开，否则用户会以为
+ * 自己的文件真的不存在，从而接受一次错误的覆盖。
+ */
+export declare function describeReadFailure(what: string, path: string, error: unknown, signal?: AbortSignal): string;

package/lib/shared/fs-errors.js

@@ -0,0 +1,90 @@
+/**
+ * 文件系统错误分类：**区分「不存在」与「读失败」**。
+ *
+ * 这是本插件最容易出人命的一处细节。工作区里的文件都是学生的真实资产
+ * （追问答案、进度台账、文献库、检索缓存），而几乎所有读路径的写法都是：
+ *
+ * ```ts
+ * try { return await fs.readText(...) } catch { return undefined }   // ✗ 危险
+ * ```
+ *
+ * 这种写法把「文件不存在（第一次运行，正常）」和「文件存在但读不出来
+ * （权限、IO 错误、句柄失效）」折叠成同一个 `undefined`，调用方于是认为
+ * 「还没建过」，转身用默认值把它**覆盖写回**——学生的数据就没了。
+ *
+ * 正确做法：只有**确认不存在**才当作 `undefined`，其余错误一律上抛，
+ * 让工具以可读错误告知用户。宿主与各测试夹具的错误码不同，故在此集中判定。
+ *
+ * @module dsh-thesis/shared/fs-errors
+ */
+/** 各实现使用的「目标不存在」错误码。 */
+export const MISSING_CODES = ['ENOENT', 'FS_NOT_FOUND'];
+function codeOf(error) {
+    if (error === null || typeof error !== 'object')
+        return undefined;
+    const code = error.code;
+    return typeof code === 'string' ? code : undefined;
+}
+function messageOf(error) {
+    if (error instanceof Error)
+        return error.message;
+    return typeof error === 'string' ? error : '';
+}
+/**
+ * 该错误是否表示「目标不存在」？
+ *
+ * 判据按可靠性排序：错误码 → 消息里的 `ENOENT` / `not found` / `不存在`。
+ * 消息回退是必要的：某些后端（含部分测试替身）不带错误码。
+ */
+export function isMissingError(error) {
+    const code = codeOf(error);
+    if (code !== undefined)
+        return MISSING_CODES.includes(code);
+    const message = messageOf(error);
+    if (message === '')
+        return false;
+    return /\bENOENT\b|FS_NOT_FOUND|\bnot found\b|不存在|no such file/i.test(message);
+}
+/**
+ * 该错误是否表示「调用被取消」。
+ *
+ * 取消与失败必须分开处理：把 `AbortError` 当成「文件不存在」会让取消变成静默继续，
+ * 当成「检索源失败」又会让取消变成一条误导性的网络错误。`fetch` 与宿主 fs 在取消时
+ * 抛的都是 `name === 'AbortError'` 的错误。
+ */
+export function isAbortError(error) {
+    if (error === null || typeof error !== 'object')
+        return false;
+    return error.name === 'AbortError';
+}
+/**
+ * 读取一个「存在则读、不存在则 undefined」的文件；**其余错误原样抛出**。
+ *
+ * @param read 实际的读取动作（通常包住 `fs.resolve` + `fs.readText`）。
+ * @param onMissing 命中「不存在」时的返回值，缺省 `undefined`。
+ */
+export async function readOrUndefined(read, onMissing = undefined) {
+    try {
+        return await read();
+    }
+    catch (error) {
+        if (isMissingError(error))
+            return onMissing;
+        throw error;
+    }
+}
+/**
+ * 把读取错误包装成给用户看的可读消息（工具层用）。
+ *
+ * 关键是把「读不出来」和「还没建过」在**文案上**也区分开，否则用户会以为
+ * 自己的文件真的不存在，从而接受一次错误的覆盖。
+ */
+export function describeReadFailure(what, path, error, signal) {
+    if (signal?.aborted === true)
+        return `${what}读取被取消（${path}）。`;
+    const code = codeOf(error);
+    const suffix = code !== undefined ? `（错误码 ${code}）` : '';
+    const detail = messageOf(error);
+    return `${what}存在但读不出来：${path}${suffix}${detail === '' ? '' : ` —— ${detail}`}。可能是权限问题或文件损坏；`
+        + '已停止本次操作，未覆盖任何已有内容。请检查该文件后重试。';
+}

package/lib/shared/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 跨模块共用的工具胶水：输出形状、会话定位、二进制落盘。
+ *
+ * 三个模块（论文流水线 / 记忆 / 新能力）都通过这里拿同一套约定，
+ * 避免每个模块各写一份 `textOutput`/`sessionCwd` 造成的漂移。
+ *
+ * @module dsh-thesis/shared
+ */
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+export { definePaperTool, usingHostDefineTool, compileParameterSchema, compileValueSchema, type PaperToolOptions } from './define-tool.ts';
+/** 统一的纯文本工具输出（本插件所有工具都返回有界字符串）。 */
+export declare function textOutput(): {
+    schema: {
+        type: "string";
+    };
+    render: (_args: unknown, value: unknown) => {
+        type: "text";
+        text: string;
+    }[];
+};
+/** 当前会话的工作目录；无 agent 的执行体（测试/程序化调用）返回 undefined。 */
+export declare function sessionCwd(exec: ToolExecution): string | undefined;
+/** 二进制落盘签名（docx 等产出）。 */
+export type WriteBinary = (absPath: string, data: Uint8Array) => Promise<void>;
+/**
+ * 二进制落盘：`ctx.fs` 没有二进制写入能力，docx/pptx 由插件经 node:fs 写。
+ * 这是文档化的例外，全插件只有这一处。
+ */
+export declare const writeBinary: WriteBinary;
+/** 缩进渲染一个字符串列表，用于工具返回值里的人类可读清单。 */
+export declare function bulletList(items: readonly string[], marker?: string): string;

package/lib/shared/index.js

@@ -0,0 +1,32 @@
+/**
+ * 跨模块共用的工具胶水：输出形状、会话定位、二进制落盘。
+ *
+ * 三个模块（论文流水线 / 记忆 / 新能力）都通过这里拿同一套约定，
+ * 避免每个模块各写一份 `textOutput`/`sessionCwd` 造成的漂移。
+ *
+ * @module dsh-thesis/shared
+ */
+import { writeFile } from 'node:fs/promises';
+export { definePaperTool, usingHostDefineTool, compileParameterSchema, compileValueSchema } from "./define-tool.js";
+/** 统一的纯文本工具输出（本插件所有工具都返回有界字符串）。 */
+export function textOutput() {
+    return {
+        schema: { type: 'string' },
+        render: (_args, value) => [{ type: 'text', text: String(value) }],
+    };
+}
+/** 当前会话的工作目录；无 agent 的执行体（测试/程序化调用）返回 undefined。 */
+export function sessionCwd(exec) {
+    return exec.agent?.session.header.cwd;
+}
+/**
+ * 二进制落盘：`ctx.fs` 没有二进制写入能力，docx/pptx 由插件经 node:fs 写。
+ * 这是文档化的例外，全插件只有这一处。
+ */
+export const writeBinary = async (absPath, data) => {
+    await writeFile(absPath, data);
+};
+/** 缩进渲染一个字符串列表，用于工具返回值里的人类可读清单。 */
+export function bulletList(items, marker = '- ') {
+    return items.map(item => `${marker}${item}`).join('\n');
+}

package/lib/shared/spawn.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 子进程调用的统一助手：**退出码必须等于 0 才算成功**，且不依赖被限制的管道 stdio。
+ *
+ * 两个真实教训：
+ *
+ * 1. **`status === null` 不是成功**。子进程从未启动（`EPERM`）、被信号杀死或被
+ *    `timeout` 掐断时，`spawnSync` 返回 `status: null`。原先的写法是
+ *    `if (status !== 0) 失败`，`null !== 0` 成立所以能挡住——但 `if (status === 0) 成功`
+ *    这类写法会把「没跑起来」当成成功。本模块统一用 {@link spawnOk} 判定，
+ *    并把 `error`（含 `EPERM`）与退出码一起回报，绝不静默。
+ *
+ * 2. **管道 stdio 在某些受限环境被拒**。沙箱/受限宿主下 `stdio: 'pipe'` 会直接
+ *    `EPERM`，此时 `git init` 之类的调用一律失败。因此默认用 `'ignore'`：
+ *    退出码仍可用，但拿不到 stdout/stderr——需要输出内容的调用（如 `git log`）
+ *    必须显式传 `capture: true` 并在无输出时如实降级，而不是假装拿到结果。
+ *
+ * @module dsh-thesis/shared/spawn
+ */
+export interface SpawnOptions {
+    readonly cwd?: string;
+    readonly timeoutMs?: number;
+    /** 是否需要 stdout/stderr 内容（默认 false；受限环境下管道 stdio 可能被拒）。 */
+    readonly capture?: boolean;
+}
+export interface SpawnOutcome {
+    /** 退出码为 0 时为 true；子进程未启动/被杀死（status=null）一律为 false。 */
+    readonly ok: boolean;
+    readonly status: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    /** 子进程未能启动时的原因（如 `Error: spawnSync git EPERM`）。 */
+    readonly error: string | undefined;
+    readonly timedOut: boolean;
+}
+/** 运行一条命令并给出**可靠的成功判定**与尽可能完整的诊断信息。 */
+export declare function spawnCommand(command: string, args: readonly string[], options?: SpawnOptions): SpawnOutcome;
+/** 失败原因的可读描述（写进工具返回值，绝不出现「失败但什么都不说」）。 */
+export declare function describeFailure(command: string, outcome: SpawnOutcome): string;

package/lib/shared/spawn.js

@@ -0,0 +1,50 @@
+/**
+ * 子进程调用的统一助手：**退出码必须等于 0 才算成功**，且不依赖被限制的管道 stdio。
+ *
+ * 两个真实教训：
+ *
+ * 1. **`status === null` 不是成功**。子进程从未启动（`EPERM`）、被信号杀死或被
+ *    `timeout` 掐断时，`spawnSync` 返回 `status: null`。原先的写法是
+ *    `if (status !== 0) 失败`，`null !== 0` 成立所以能挡住——但 `if (status === 0) 成功`
+ *    这类写法会把「没跑起来」当成成功。本模块统一用 {@link spawnOk} 判定，
+ *    并把 `error`（含 `EPERM`）与退出码一起回报，绝不静默。
+ *
+ * 2. **管道 stdio 在某些受限环境被拒**。沙箱/受限宿主下 `stdio: 'pipe'` 会直接
+ *    `EPERM`，此时 `git init` 之类的调用一律失败。因此默认用 `'ignore'`：
+ *    退出码仍可用，但拿不到 stdout/stderr——需要输出内容的调用（如 `git log`）
+ *    必须显式传 `capture: true` 并在无输出时如实降级，而不是假装拿到结果。
+ *
+ * @module dsh-thesis/shared/spawn
+ */
+import { spawnSync } from 'node:child_process';
+/** 运行一条命令并给出**可靠的成功判定**与尽可能完整的诊断信息。 */
+export function spawnCommand(command, args, options = {}) {
+    const capture = options.capture === true;
+    const result = spawnSync(command, [...args], {
+        ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+        encoding: 'utf8',
+        stdio: capture ? 'pipe' : 'ignore',
+        ...(options.timeoutMs !== undefined ? { timeout: options.timeoutMs } : {}),
+    });
+    const error = result.error === undefined ? undefined : String(result.error);
+    // Node 在 timeout 触发时会设置 error.code === 'ETIMEDOUT'（或 signal 为 SIGTERM）。
+    const timedOut = error !== undefined && /ETIMEDOUT|timed out/i.test(error);
+    return {
+        ok: result.status === 0,
+        status: result.status,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+        error,
+        timedOut,
+    };
+}
+/** 失败原因的可读描述（写进工具返回值，绝不出现「失败但什么都不说」）。 */
+export function describeFailure(command, outcome) {
+    const head = `${command} 未能完成`;
+    if (outcome.error !== undefined)
+        return `${head}：${outcome.error}`;
+    if (outcome.timedOut)
+        return `${head}：超时被终止`;
+    const detail = (outcome.stderr.trim() || outcome.stdout.trim()).split('\n')[0] ?? '';
+    return `${head}：退出码 ${outcome.status ?? 'null'}${detail === '' ? '' : ` —— ${detail}`}`;
+}

package/lib/shared/text.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 纯文本启发式工具：零依赖、纯函数，被闸门、追问与跨会话事实回灌共用。
+ *
+ * 这里的函数只回答「这段文本里有什么」——**不含任何产品判断**。
+ * 「什么样的文本应当触发闸门」属于 `gates/detect.ts`。
+ *
+ * @module dsh-thesis/shared/text
+ */
+/** 命令摘录：截断到 max 字符，用于决策理由展示（绝不无限引用命令全文）。 */
+export declare function excerpt(text: string, max?: number): string;
+/** 从消息内容块中提取纯文本（只取 text 块）。 */
+export declare function textOfBlocks(blocks: readonly {
+    type: string;
+}[]): string;

package/lib/shared/text.js

@@ -0,0 +1,26 @@
+/**
+ * 纯文本启发式工具：零依赖、纯函数，被闸门、追问与跨会话事实回灌共用。
+ *
+ * 这里的函数只回答「这段文本里有什么」——**不含任何产品判断**。
+ * 「什么样的文本应当触发闸门」属于 `gates/detect.ts`。
+ *
+ * @module dsh-thesis/shared/text
+ */
+/** 命令摘录：截断到 max 字符，用于决策理由展示（绝不无限引用命令全文）。 */
+export function excerpt(text, max = 200) {
+    const single = text.replace(/\s+/g, ' ').trim();
+    if (single.length <= max)
+        return single;
+    return `${single.slice(0, max)}…（已截断，共 ${single.length} 字符）`;
+}
+/** 从消息内容块中提取纯文本（只取 text 块）。 */
+export function textOfBlocks(blocks) {
+    let out = '';
+    for (const block of blocks) {
+        const text = block.text;
+        if (block.type === 'text' && typeof text === 'string')
+            out += text;
+        out += '\n';
+    }
+    return out;
+}