dsh-thesis 1.0.0

package/lib/codewalk/engine.js

@@ -0,0 +1,449 @@
+/**
+ * 代码演练引擎：一个普通类，由 `register.ts` 里的 `registerCodewalk`
+ * 注册为 `paperLearn` 服务。
+ *
+ * 引擎负责守住流程，模型负责执行流程。所有非法迁移都在这里被拒绝：没有
+ * 真实跑过一次验证门，模型就不能把某个里程碑标成 verified；不能修改已冻结
+ * （verified）的里程碑；不能跳阶段。状态落在 `<cwd>/.paper/state.json`，
+ * 因此跨会话存活，并随演练骨架仓库一起走。
+ *
+ * 这个类刻意**不**继承 Cordis 的 `Service`：装进 profile 的 bundle 会从自己的
+ * 依赖树里解析 `@deepseek-ai/cordis`，两份模块副本会破坏框架以 Symbol 为键的
+ * 生命周期钩子。注册一律走 `ctx.provide` —— 与生产 boot 插件用的是同一个接缝。
+ *
+ * @module dsh-thesis/codewalk
+ */
+import { LearningError } from "./errors.js";
+const PHASES = ['analyzing', 'skeletonizing', 'learning', 'complete'];
+const PHASE_NEXT = {
+    analyzing: 'skeletonizing',
+    skeletonizing: 'learning',
+    learning: 'complete',
+    complete: null,
+};
+const TODO_STATUS = ['pending', 'in_progress', 'done'];
+const MILESTONE_STATUS = ['pending', 'in_progress', 'verified', 'failed'];
+const QUESTION_STATUS = ['unasked', 'asked', 'passed', 'failed'];
+const DIFFICULTIES = [1, 2, 3, 4];
+/** 合法的 todo 状态迁移：允许返工（done → in_progress）。 */
+const TODO_MOVES = {
+    pending: ['in_progress', 'done'],
+    in_progress: ['done'],
+    done: ['in_progress'],
+};
+/**
+ * 代码演练引擎。
+ *
+ * 所有状态机方法都直接修改传入的 `state` 对象，并用 `LearningError` 拒绝非法
+ * 迁移。持久化方法一律走注入的文件系统，因此本地与远端后端行为一致。
+ */
+export class AiLearningEngine {
+    ctx;
+    resolved;
+    constructor(ctx, config = {}) {
+        this.ctx = ctx;
+        this.resolved = {
+            stateDir: config.stateDir ?? '.paper',
+            gates: config.gates ?? { go: { build: ['go', 'build', './...'] } },
+            maxCapturedOutput: config.maxCapturedOutput ?? 8000,
+        };
+    }
+    /** 解析后的配置（默认值已物化）。 */
+    get config() {
+        return this.resolved;
+    }
+    /** 宿主文件系统接缝；`inject: ['fs']` 保证其存在。 */
+    get fs() {
+        return this.ctx.get('fs');
+    }
+    stateFilePath() {
+        return `${this.resolved.stateDir}/state.json`;
+    }
+    // ── 持久化 ───────────────────────────────────────────────────────────
+    /** 相对会话 cwd 解析状态文件目标。 */
+    async stateTarget(cwd) {
+        return this.fs.resolve(this.stateFilePath(), { cwd });
+    }
+    /** `cwd` 下是否已存在演练状态。 */
+    async hasState(cwd) {
+        const target = await this.stateTarget(cwd);
+        return (await this.fs.stat(target)) !== undefined;
+    }
+    /**
+     * 读取并校验 `cwd` 下的状态；不存在时返回 `undefined`。
+     * 内容损坏时以 `STATE_INVALID` 拒绝。
+     */
+    async load(cwd) {
+        const target = await this.stateTarget(cwd);
+        const info = await this.fs.stat(target);
+        if (info === undefined)
+            return undefined;
+        const text = await this.fs.readText(target);
+        return parseState(text);
+    }
+    /**
+     * 为一次新的代码演练创建初始状态。
+     *
+     * 已存在状态时以 `STATE_EXISTS` 拒绝（经 `createIfAbsent` 保证竞态安全）；
+     * 源语言没有配置验证门时以 `GATE_UNKNOWN` 拒绝。
+     */
+    async create(cwd, input) {
+        const gate = this.resolved.gates[input.origin.language];
+        if (gate === undefined) {
+            throw new LearningError('GATE_UNKNOWN', `语言 "${input.origin.language}" 没有配置验证门（已配置：${Object.keys(this.resolved.gates).join(', ') || '无'}）`);
+        }
+        const target = await this.stateTarget(cwd);
+        if ((await this.fs.stat(target)) !== undefined) {
+            throw new LearningError('STATE_EXISTS', `${cwd} 下已存在演练状态`);
+        }
+        const state = {
+            schemaVersion: 1,
+            phase: 'analyzing',
+            origin: { path: input.origin.path, language: input.origin.language },
+            scope: { ...input.scope },
+            milestones: [],
+            todos: [],
+            gates: this.resolved.gates,
+            records: [],
+            updatedAt: Date.now(),
+        };
+        const content = serializeState(state);
+        try {
+            await this.fs.writeText(target, content, { createIfAbsent: true });
+        }
+        catch (error) {
+            if (errorCode(error) === 'FS_NOT_OBSERVED') {
+                throw new LearningError('STATE_EXISTS', `${cwd} 下已存在演练状态`);
+            }
+            throw error;
+        }
+        return state;
+    }
+    /** 持久化当前状态，并刷新 `updatedAt`。 */
+    async save(cwd, state) {
+        validateStateShape(state);
+        state.updatedAt = Date.now();
+        const target = await this.stateTarget(cwd);
+        await this.fs.writeText(target, serializeState(state));
+    }
+    // ── 阶段状态机 ───────────────────────────────────────────────────────
+    /**
+     * 推进工作流阶段。只允许沿
+     * analyzing → skeletonizing → learning → complete 向前走。
+     * 进入 `learning` 至少需要一个带 todo 的里程碑；
+     * 进入 `complete` 需要每个里程碑都已 verified。
+     */
+    advancePhase(state, next) {
+        if (next === state.phase)
+            return;
+        if (PHASE_NEXT[state.phase] !== next) {
+            throw new LearningError('ILLEGAL_TRANSITION', `不能从阶段 "${state.phase}" 迁移到 "${next}"`);
+        }
+        if (next === 'learning') {
+            if (state.milestones.length === 0) {
+                throw new LearningError('ILLEGAL_TRANSITION', '不能进入 learning 阶段：尚未定义任何里程碑');
+            }
+            for (const milestone of state.milestones) {
+                if (milestone.todos.length === 0) {
+                    throw new LearningError('ILLEGAL_TRANSITION', `里程碑 "${milestone.id}" 没有任何 todo`);
+                }
+            }
+        }
+        if (next === 'complete') {
+            const open = state.milestones.filter((milestone) => milestone.status !== 'verified');
+            if (open.length > 0) {
+                throw new LearningError('ILLEGAL_TRANSITION', `不能完成：仍有未关闭的里程碑：${open.map((milestone) => milestone.id).join(', ')}`);
+            }
+        }
+        state.phase = next;
+        if (next === 'learning')
+            this.startNextMilestone(state);
+    }
+    // ── todo 状态机 ──────────────────────────────────────────────────────
+    /** 新增或替换一个 todo。被 verified 里程碑引用的 todo 已冻结。 */
+    upsertTodo(state, todo) {
+        if (!DIFFICULTIES.includes(todo.difficulty)) {
+            throw new LearningError('ILLEGAL_TRANSITION', `todo "${todo.id}" 的难度值非法`);
+        }
+        if (!TODO_STATUS.includes(todo.status)) {
+            throw new LearningError('ILLEGAL_TRANSITION', `todo "${todo.id}" 的状态值非法`);
+        }
+        this.assertTodoEditable(state, todo.id);
+        const index = state.todos.findIndex((entry) => entry.id === todo.id);
+        if (index >= 0)
+            state.todos[index] = todo;
+        else
+            state.todos.push(todo);
+    }
+    /** 沿 pending → in_progress → done 迁移一个 todo（允许返工）。 */
+    setTodoStatus(state, todoId, status) {
+        const todo = state.todos.find((entry) => entry.id === todoId);
+        if (todo === undefined)
+            throw new LearningError('TODO_UNKNOWN', `未知 todo "${todoId}"`);
+        if (status === todo.status)
+            return;
+        if (!TODO_MOVES[todo.status].includes(status)) {
+            throw new LearningError('ILLEGAL_TRANSITION', `不能把 todo "${todoId}" 从 "${todo.status}" 迁移到 "${status}"`);
+        }
+        todo.status = status;
+    }
+    assertTodoEditable(state, todoId) {
+        const frozen = state.milestones.some((milestone) => milestone.status === 'verified' && milestone.todos.includes(todoId));
+        if (frozen) {
+            throw new LearningError('ILLEGAL_TRANSITION', `todo "${todoId}" 已被 verified 里程碑冻结`);
+        }
+    }
+    // ── 里程碑状态机 ─────────────────────────────────────────────────────
+    /**
+     * 新增或替换一个里程碑。verified 里程碑已冻结。每个 todo 引用都必须能解析。
+     * 新里程碑从 `pending` 开始；对未关闭里程碑做内容编辑会保留其当前状态。
+     */
+    upsertMilestone(state, milestone) {
+        const existing = state.milestones.find((entry) => entry.id === milestone.id);
+        if (existing?.status === 'verified') {
+            throw new LearningError('ILLEGAL_TRANSITION', `里程碑 "${milestone.id}" 已 verified，处于冻结状态`);
+        }
+        for (const todoId of milestone.todos) {
+            if (!state.todos.some((todo) => todo.id === todoId)) {
+                throw new LearningError('TODO_UNKNOWN', `里程碑 "${milestone.id}" 引用了未知 todo "${todoId}"`);
+            }
+        }
+        for (const [index, question] of milestone.questions.entries()) {
+            if (question.ask.trim() === '') {
+                throw new LearningError('ILLEGAL_TRANSITION', `里程碑 "${milestone.id}" 的第 ${index} 个问题缺少提问文本`);
+            }
+            if (!QUESTION_STATUS.includes(question.status)) {
+                throw new LearningError('ILLEGAL_TRANSITION', `里程碑 "${milestone.id}" 的第 ${index} 个问题状态非法`);
+            }
+        }
+        const normalized = {
+            ...milestone,
+            status: existing === undefined ? 'pending' : existing.status,
+            questions: milestone.questions.map((question) => ({ ...question })),
+        };
+        if (existing === undefined)
+            state.milestones.push(normalized);
+        else {
+            const index = state.milestones.indexOf(existing);
+            if (index >= 0)
+                state.milestones.splice(index, 1, normalized);
+        }
+    }
+    /** 启动第一个 pending 里程碑。要求处于 learning 阶段。 */
+    startNextMilestone(state) {
+        if (state.phase !== 'learning') {
+            throw new LearningError('ILLEGAL_TRANSITION', `阶段 "${state.phase}" 下不能启动里程碑`);
+        }
+        const next = state.milestones.find((milestone) => milestone.status === 'pending');
+        if (next !== undefined)
+            next.status = 'in_progress';
+    }
+    /** 重新打开一个 failed 里程碑，允许再试一次。 */
+    retryMilestone(state, milestoneId) {
+        const milestone = this.milestone(state, milestoneId);
+        if (milestone.status !== 'failed') {
+            throw new LearningError('ILLEGAL_TRANSITION', `里程碑 "${milestoneId}" 当前是 "${milestone.status}"，不是 failed`);
+        }
+        milestone.status = 'in_progress';
+    }
+    milestone(state, milestoneId) {
+        const milestone = state.milestones.find((entry) => entry.id === milestoneId);
+        if (milestone === undefined)
+            throw new LearningError('MILESTONE_UNKNOWN', `未知里程碑 "${milestoneId}"`);
+        return milestone;
+    }
+    // ── 问答状态机 ───────────────────────────────────────────────────────
+    /** 提出（或在失分后重提）某个里程碑问题。 */
+    askQuestion(state, milestoneId, questionIndex) {
+        const question = this.question(state, milestoneId, questionIndex);
+        if (question.status === 'asked')
+            return;
+        if (question.status !== 'unasked' && question.status !== 'failed') {
+            throw new LearningError('ILLEGAL_TRANSITION', `第 ${questionIndex} 个问题当前是 "${question.status}"，不可提问`);
+        }
+        question.status = 'asked';
+    }
+    /**
+     * 为一个已提出的问题给出下一级升级提示。返回提示文本；提示阶梯用尽时返回
+     * `null` —— 此时必须公布答案，并要求学生用自己的话复述，再走 `assessAnswer`。
+     */
+    giveHint(state, milestoneId, questionIndex) {
+        const question = this.question(state, milestoneId, questionIndex);
+        if (question.status !== 'asked') {
+            throw new LearningError('ILLEGAL_TRANSITION', `第 ${questionIndex} 个问题必须先提出才能给提示`);
+        }
+        if (question.hintLevel >= question.hints.length)
+            return null;
+        const hint = question.hints[question.hintLevel];
+        question.hintLevel += 1;
+        return hint ?? null;
+    }
+    /** 用评分结论（可选评分备注）给一个已提出的问题定分。 */
+    assessAnswer(state, milestoneId, questionIndex, passed, note) {
+        const question = this.question(state, milestoneId, questionIndex);
+        if (question.status !== 'asked') {
+            throw new LearningError('ILLEGAL_TRANSITION', `第 ${questionIndex} 个问题必须先提出才能评分`);
+        }
+        question.status = passed ? 'passed' : 'failed';
+        if (note !== undefined)
+            question.note = note;
+    }
+    question(state, milestoneId, questionIndex) {
+        const milestone = this.milestone(state, milestoneId);
+        const question = milestone.questions[questionIndex];
+        if (question === undefined) {
+            throw new LearningError('QUESTION_UNKNOWN', `里程碑 "${milestoneId}" 没有第 ${questionIndex} 个问题`);
+        }
+        return question;
+    }
+    // ── 验证 ─────────────────────────────────────────────────────────────
+    /**
+     * 记录一次实际执行的验证门，并把结论折进里程碑。
+     *
+     * - 退出码 0 且所有问题已 passed → `verified`，随后启动下一个 pending
+     *   里程碑（或整个流程完成）；
+     * - 退出码 0 但仍有未通过的问题 → 保持 in_progress（`pending-questions`）；
+     * - 退出码非 0 → `failed`；用 `retryMilestone` 重新打开。
+     */
+    recordGate(state, milestoneId, input) {
+        const milestone = this.milestone(state, milestoneId);
+        if (milestone.status !== 'in_progress') {
+            throw new LearningError('ILLEGAL_TRANSITION', `里程碑 "${milestoneId}" 当前是 "${milestone.status}"，不是 in_progress`);
+        }
+        const record = {
+            milestone: milestoneId,
+            command: [...input.command],
+            exitCode: input.exitCode,
+            stdout: truncate(input.stdout, this.resolved.maxCapturedOutput),
+            stderr: truncate(input.stderr, this.resolved.maxCapturedOutput),
+            durationMs: input.durationMs,
+            at: Date.now(),
+        };
+        state.records.push(record);
+        if (input.exitCode !== 0) {
+            milestone.status = 'failed';
+            return { kind: 'failed' };
+        }
+        const openQuestions = milestone.questions.filter((question) => question.status !== 'passed');
+        if (openQuestions.length > 0) {
+            return { kind: 'pending-questions' };
+        }
+        milestone.status = 'verified';
+        const open = state.milestones.filter((entry) => entry.status === 'pending');
+        if (open.length === 0) {
+            state.phase = 'complete';
+            return { kind: 'verified' };
+        }
+        open[0].status = 'in_progress';
+        return { kind: 'verified' };
+    }
+    // ── 视图 ─────────────────────────────────────────────────────────────
+    /** 只读快照，供状态视图、模型工具与注入使用。 */
+    snapshot(state) {
+        const current = state.milestones.find((milestone) => milestone.status === 'in_progress');
+        const next = state.milestones.find((milestone) => milestone.status === 'pending');
+        let questionCount = 0;
+        let doneQuestionCount = 0;
+        for (const milestone of state.milestones) {
+            questionCount += milestone.questions.length;
+            doneQuestionCount += milestone.questions.filter((question) => question.status === 'passed').length;
+        }
+        return {
+            state,
+            phase: state.phase,
+            current,
+            next,
+            gateCount: state.records.length,
+            questionCount,
+            doneQuestionCount,
+        };
+    }
+    /** `/thesis-defense status` 用的人类可读状态文本。 */
+    describe(state) {
+        const view = this.snapshot(state);
+        const verified = state.milestones.filter((milestone) => milestone.status === 'verified').length;
+        const lines = [
+            `代码演练状态 — phase: ${view.phase}`,
+            `  origin: ${state.origin.path} (${state.origin.language})`,
+            `  level: ${state.scope.level}${state.scope.module === undefined ? '' : `, module: ${state.scope.module}`}`,
+            `  milestones: ${verified}/${state.milestones.length} verified`,
+            `  todos: ${state.todos.filter((todo) => todo.status === 'done').length}/${state.todos.length} done`,
+            `  questions: ${view.doneQuestionCount}/${view.questionCount} passed`,
+            `  gate runs: ${view.gateCount}`,
+        ];
+        if (view.current !== undefined) {
+            const todos = view.current.todos
+                .map((id) => state.todos.find((todo) => todo.id === id))
+                .filter((todo) => todo !== undefined);
+            const doneCount = todos.filter((todo) => todo.status === 'done').length;
+            lines.push(`  current: ${view.current.title} (todos ${doneCount}/${todos.length} done, questions ${view.current.questions.length})`);
+        }
+        else if (view.next !== undefined) {
+            lines.push(`  next: ${view.next.title}`);
+        }
+        return lines.join('\n');
+    }
+}
+// ── 纯函数辅助 ───────────────────────────────────────────────────────────
+function serializeState(state) {
+    return `${JSON.stringify(state, null, 2)}\n`;
+}
+function parseState(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new LearningError('STATE_INVALID', '状态文件不是合法 JSON');
+    }
+    const state = value;
+    validateStateShape(state);
+    return state;
+}
+/** 对已加载（或即将保存）状态做结构校验。 */
+function validateStateShape(value) {
+    if (typeof value !== 'object' || value === null) {
+        throw new LearningError('STATE_INVALID', '状态必须是对象');
+    }
+    const state = value;
+    if (state.schemaVersion !== 1) {
+        throw new LearningError('STATE_INVALID', `不支持的 schemaVersion ${String(state.schemaVersion)}`);
+    }
+    if (!PHASES.includes(state.phase)) {
+        throw new LearningError('STATE_INVALID', `非法阶段 ${String(state.phase)}`);
+    }
+    if (typeof state.origin?.path !== 'string' ||
+        typeof state.origin.language !== 'string' ||
+        typeof state.scope?.level !== 'string') {
+        throw new LearningError('STATE_INVALID', 'origin 或 scope 字段格式错误');
+    }
+    if (state.gates === undefined || typeof state.gates[state.origin.language] !== 'object') {
+        throw new LearningError('STATE_INVALID', `语言 "${state.origin.language}" 没有记录验证门`);
+    }
+    if (!Array.isArray(state.milestones) || !Array.isArray(state.todos) || !Array.isArray(state.records)) {
+        throw new LearningError('STATE_INVALID', 'milestones、todos 或 records 不是数组');
+    }
+    for (const milestone of state.milestones) {
+        if (!MILESTONE_STATUS.includes(milestone.status)) {
+            throw new LearningError('STATE_INVALID', `里程碑 "${milestone.id}" 的状态非法`);
+        }
+        for (const todoId of milestone.todos) {
+            if (!state.todos.some((todo) => todo.id === todoId)) {
+                throw new LearningError('STATE_INVALID', `里程碑 "${milestone.id}" 引用了未知 todo "${todoId}"`);
+            }
+        }
+    }
+}
+function errorCode(error) {
+    if (typeof error === 'object' && error !== null && 'code' in error) {
+        const code = error.code;
+        if (typeof code === 'string')
+            return code;
+    }
+    return undefined;
+}
+function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    return `\u2026${text.slice(-(max - 1))}`;
+}

package/lib/codewalk/errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 演练引擎的结构化错误。每一次拒绝都携带稳定的 `code`，调用方（命令、工具）
+ * 因此可以按 code 分支，而不必去匹配文案。
+ *
+ * @module dsh-thesis/codewalk
+ */
+export type LearningErrorCode = 
+/** create 要求目标不存在，但已有状态文件。 */
+'STATE_EXISTS'
+/** 状态文件存在但无法解析或校验失败。 */
+ | 'STATE_INVALID'
+/** 请求的迁移违反状态机。 */
+ | 'ILLEGAL_TRANSITION'
+/** 里程碑 id 未知。 */
+ | 'MILESTONE_UNKNOWN'
+/** todo id 未知。 */
+ | 'TODO_UNKNOWN'
+/** 问题下标越界。 */
+ | 'QUESTION_UNKNOWN'
+/** 该语言在解析后的配置里没有验证门。 */
+ | 'GATE_UNKNOWN'
+/** 没有组合 shell 执行器，验证门无法运行。 */
+ | 'SHELL_MISSING';
+/** 一次被拒绝的演练引擎操作。 */
+export declare class LearningError extends Error {
+    /** 稳定的机器可读 code。 */
+    readonly code: LearningErrorCode;
+    constructor(code: LearningErrorCode, message: string);
+}
+/** 任意拒绝是否为 LearningError。 */
+export declare function isLearningError(error: unknown): error is LearningError;

package/lib/codewalk/errors.js

@@ -0,0 +1,20 @@
+/**
+ * 演练引擎的结构化错误。每一次拒绝都携带稳定的 `code`，调用方（命令、工具）
+ * 因此可以按 code 分支，而不必去匹配文案。
+ *
+ * @module dsh-thesis/codewalk
+ */
+/** 一次被拒绝的演练引擎操作。 */
+export class LearningError extends Error {
+    /** 稳定的机器可读 code。 */
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'LearningError';
+        this.code = code;
+    }
+}
+/** 任意拒绝是否为 LearningError。 */
+export function isLearningError(error) {
+    return error instanceof LearningError;
+}

package/lib/codewalk/fs-types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 本插件需要的那一小片宿主文件系统接缝。
+ *
+ * 刻意**不**从 `@deepseek-ai/dsh-fs` 导入：已发布的 rc.1 依赖树引用了未发布的包，
+ * 因此外部 bundle 不能安装 dsh 包。宿主真实的 `ctx.fs` 在运行期满足这个结构化
+ * 接口；引擎只通过这份声明的契约与它对话。
+ *
+ * @module dsh-thesis/codewalk
+ */
+/** 不透明的已解析文件句柄；只有 `displayPath` 可以对外展示。 */
+export interface LearningFsTarget {
+    readonly targetKey: unknown;
+    readonly displayPath: string;
+}
+/** `stat` 返回的元信息。 */
+export interface LearningFsInfo {
+    readonly version: unknown;
+    readonly type: string;
+}
+/** 受保护的写入意图：仅当目标不存在时创建。 */
+export interface CreateIfAbsentIntent {
+    readonly createIfAbsent: true;
+}
+/** 引擎传给 `writeText` 的写入意图联合。 */
+export type LearningWriteIntent = CreateIfAbsentIntent;
+/** 引擎使用的文件系统表面；由宿主 `ctx.fs` 满足。 */
+export interface StateFileSystem {
+    resolve(path: string, opts?: {
+        cwd?: string;
+    }): Promise<LearningFsTarget>;
+    stat(target: LearningFsTarget, signal?: AbortSignal): Promise<LearningFsInfo | undefined>;
+    readText(target: LearningFsTarget, signal?: AbortSignal): Promise<string>;
+    writeText(target: LearningFsTarget, content: string, expected?: LearningWriteIntent, signal?: AbortSignal): Promise<void>;
+}

package/lib/codewalk/fs-types.js

@@ -0,0 +1,10 @@
+/**
+ * 本插件需要的那一小片宿主文件系统接缝。
+ *
+ * 刻意**不**从 `@deepseek-ai/dsh-fs` 导入：已发布的 rc.1 依赖树引用了未发布的包，
+ * 因此外部 bundle 不能安装 dsh 包。宿主真实的 `ctx.fs` 在运行期满足这个结构化
+ * 接口；引擎只通过这份声明的契约与它对话。
+ *
+ * @module dsh-thesis/codewalk
+ */
+export {};

package/lib/codewalk/gate.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 共享的验证门执行逻辑：通过 `ctx.shell` 跑一个里程碑的验证命令，把结论折进
+ * 引擎（记录 + 状态 + 落盘），再把结算后的结果交回给调用方渲染。
+ *
+ * 人类的 `/thesis-defense check` 命令与模型侧的 `defense_code_update` `check_gate` 动作共用这段
+ * 逻辑，因此两个表面永远不会对「什么叫 verified」产生分歧。
+ *
+ * @module dsh-thesis/codewalk
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { AiLearningEngine } from './engine.ts';
+import type { GateOutcome, LearningState, Milestone } from './types.ts';
+export declare const GATE_TIMEOUT_MS = 120000;
+/** 一次验证门执行结算后的结果。 */
+export interface MilestoneGateOutcome {
+    readonly outcome: GateOutcome;
+    readonly command: readonly string[];
+    readonly exitCode: number;
+    readonly interrupted: boolean;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/**
+ * 跑 `milestone` 的有效验证门，记录它，持久化状态，并返回结算后的结论。
+ * 验证门失败会自动重新打开该里程碑 —— 修完再跑一次检查就是预期的重试回路。
+ *
+ * `session`（调用方 agent 的会话，若有）会喂给宿主的逐调用沙箱策略解析，因此
+ * 带沙箱的 shell 执行器能拿到它需要的策略，而不是退回到部署默认值。
+ */
+export declare function runMilestoneGate(ctx: Context, engine: AiLearningEngine, cwd: string, state: LearningState, milestone: Milestone, signal: AbortSignal, session?: unknown): Promise<MilestoneGateOutcome>;

package/lib/codewalk/gate.js

@@ -0,0 +1,60 @@
+/**
+ * 共享的验证门执行逻辑：通过 `ctx.shell` 跑一个里程碑的验证命令，把结论折进
+ * 引擎（记录 + 状态 + 落盘），再把结算后的结果交回给调用方渲染。
+ *
+ * 人类的 `/thesis-defense check` 命令与模型侧的 `defense_code_update` `check_gate` 动作共用这段
+ * 逻辑，因此两个表面永远不会对「什么叫 verified」产生分歧。
+ *
+ * @module dsh-thesis/codewalk
+ */
+import { AiLearningEngine } from "./engine.js";
+import { LearningError } from "./errors.js";
+export const GATE_TIMEOUT_MS = 120_000;
+/**
+ * 跑 `milestone` 的有效验证门，记录它，持久化状态，并返回结算后的结论。
+ * 验证门失败会自动重新打开该里程碑 —— 修完再跑一次检查就是预期的重试回路。
+ *
+ * `session`（调用方 agent 的会话，若有）会喂给宿主的逐调用沙箱策略解析，因此
+ * 带沙箱的 shell 执行器能拿到它需要的策略，而不是退回到部署默认值。
+ */
+export async function runMilestoneGate(ctx, engine, cwd, state, milestone, signal, session) {
+    const shell = ctx.get('shell');
+    if (shell === undefined) {
+        throw new LearningError('SHELL_MISSING', '没有组合 shell 执行器，无法运行验证门');
+    }
+    const gate = milestone.gate ?? state.gates[state.origin.language];
+    if (gate === undefined) {
+        throw new LearningError('GATE_UNKNOWN', `语言 "${state.origin.language}" 没有记录验证门`);
+    }
+    if (milestone.status === 'failed')
+        engine.retryMilestone(state, milestone.id);
+    const command = [...gate.build];
+    const started = Date.now();
+    const result = await shell.run({
+        command: command.join(' '),
+        workdir: cwd,
+        timeoutMs: GATE_TIMEOUT_MS,
+        stdoutMaxBytes: engine.config.maxCapturedOutput,
+        signal,
+        sandboxPolicy: resolveSandboxPolicy(ctx, session),
+    });
+    const durationMs = Date.now() - started;
+    const interrupted = result.timedOut || result.aborted;
+    const exitCode = interrupted ? 1 : (result.exitCode ?? 1);
+    const outcome = engine.recordGate(state, milestone.id, {
+        command,
+        exitCode,
+        stdout: result.stdout.text,
+        stderr: result.stderr.text,
+        durationMs,
+    });
+    await engine.save(cwd, state);
+    return { outcome, command, exitCode, interrupted, stdout: result.stdout.text, stderr: result.stderr.text };
+}
+/** 宿主组合了沙箱策略服务时，解析本次调用的策略。 */
+function resolveSandboxPolicy(ctx, session) {
+    const service = ctx.get('sandboxPolicy');
+    if (service === undefined)
+        return undefined;
+    return service.resolve(session === undefined ? {} : { session });
+}