dsh-thesis 1.0.0

package/lib/codewalk/tools.js

@@ -0,0 +1,314 @@
+/**
+ * 面向前模型的工具：`defense_code_status`、`defense_code_next`、`defense_code_update`。
+ *
+ * 这三个工具是模型操作引擎的手柄：分析架构、安排教学由模型完成，但每一次改动
+ * 都必须穿过引擎校验过的状态迁移，并立刻落盘。工具注册走 `ctx.tools`（只有在
+ * 组合了工具注册表时才注册）；定义是纯对象，因此不需要任何 `@deepseek-ai/dsh-*`
+ * 的运行时导入。
+ *
+ * @module dsh-thesis/codewalk
+ */
+import { randomUUID } from 'node:crypto';
+import { AiLearningEngine } from "./engine.js";
+import { isLearningError } from "./errors.js";
+import { runMilestoneGate } from "./gate.js";
+const TODO_STATUS = ['pending', 'in_progress', 'done'];
+const MILESTONE_STATUS = ['pending', 'in_progress', 'verified', 'failed'];
+const QUESTION_STATUS = ['unasked', 'asked', 'passed', 'failed'];
+const PHASES = ['analyzing', 'skeletonizing', 'learning', 'complete'];
+const LEVELS = ['beginner', 'intermediate', 'advanced'];
+const TODO_SCHEMA = {
+    type: 'object',
+    required: ['id', 'where', 'what', 'steps', 'difficulty', 'status'],
+    properties: {
+        id: { type: 'string', description: '稳定 id，供里程碑引用，如 "t3"。' },
+        where: { type: 'string', description: '文件与符号位置，如 "internal/store/task.go SaveTask"。' },
+        what: { type: 'string', description: '一句话说明这个方法的目的。' },
+        steps: { type: 'array', items: { type: 'string' }, description: '分步实现提示。' },
+        hint: { type: 'string', description: '可选的坑、设计理由与语言特性。' },
+        difficulty: { type: 'integer', enum: [1, 2, 3, 4], description: '1（读数据模型）到 4（分布式协同）。' },
+        status: { type: 'string', enum: [...TODO_STATUS] },
+    },
+    additionalProperties: false,
+};
+const QUESTION_SCHEMA = {
+    type: 'object',
+    required: ['ask', 'expected', 'hints', 'status', 'hintLevel'],
+    properties: {
+        ask: { type: 'string', description: '要向学生提出的追问。' },
+        expected: {
+            type: 'array',
+            items: { type: 'string' },
+            description: '作为评分标准的期望答案要点。绝不逐字公布给学生。',
+        },
+        hints: { type: 'array', items: { type: 'string' }, description: '逐步升级的提示，在公布答案之前一次给一条。' },
+        status: { type: 'string', enum: [...QUESTION_STATUS] },
+        hintLevel: { type: 'integer', description: '已经给过多少条提示。' },
+        note: { type: 'string', description: '评分定分时记录的备注（可选）。' },
+    },
+    additionalProperties: false,
+};
+const MILESTONE_SCHEMA = {
+    type: 'object',
+    required: ['id', 'title', 'todos', 'questions'],
+    properties: {
+        id: { type: 'string', description: '稳定 id，如 "m1"。' },
+        title: { type: 'string', description: '简短的人类标题，如 "etcd 里的任务 CRUD"。' },
+        todos: { type: 'array', items: { type: 'string' }, description: '本里程碑覆盖的 todo id。' },
+        gate: {
+            type: 'object',
+            required: ['build'],
+            properties: {
+                build: { type: 'array', items: { type: 'string' }, description: '命令与参数；缺省用语言级验证门。' },
+            },
+            additionalProperties: false,
+        },
+        questions: { type: 'array', items: QUESTION_SCHEMA },
+    },
+    additionalProperties: false,
+};
+/** 组合了工具注册表时，注册这三个面向前模型的工具。 */
+export function registerTools(ctx, engine) {
+    const tools = ctx.get('tools');
+    if (tools === undefined)
+        return;
+    tools.register(statusTool(engine));
+    tools.register(nextTool(engine));
+    tools.register(updateTool(ctx, engine));
+}
+/** 解析一次工具调用的会话 cwd；缺失或没有演练状态时直接拒绝。 */
+async function toolCwd(engine, exec) {
+    const cwd = exec.agent?.session.header.cwd;
+    if (cwd === undefined) {
+        throw new Error('learn_* 工具需要会话 cwd，但本次调用没有绑定 agent');
+    }
+    const state = await engine.load(cwd);
+    if (state === undefined) {
+        throw new Error(`${cwd} 下没有代码演练状态；请先执行 "/thesis-defense new <原始项目路径>"`);
+    }
+    return state;
+}
+function text(text) {
+    return [{ type: 'text', text }];
+}
+function statusTool(engine) {
+    return {
+        name: 'defense_code_status',
+        description: '读取本会话 cwd 下代码演练的状态：阶段、里程碑、todo 进度、未完成的追问、编译验证门记录。' +
+            '动手推进演练之前先用它看清当前位置。答辩前把系统讲清楚就从这里开始。',
+        parameters: { type: 'object', properties: {}, required: [], additionalProperties: false },
+        output: { schema: { type: 'string' }, render: (_args, value) => text(String(value)) },
+        async execute(_args, exec) {
+            const state = await toolCwd(engine, exec);
+            return engine.describe(state);
+        },
+    };
+}
+function nextTool(engine) {
+    return {
+        name: 'defense_code_next',
+        description: '返回本会话 cwd 下一次该做什么：当前里程碑连同它的 todo、编译验证门与追问' +
+            '（含用于评分的期望答案要点）。',
+        parameters: { type: 'object', properties: {}, required: [], additionalProperties: false },
+        output: { schema: { type: 'object' }, render: (_args, value) => text(JSON.stringify(value, null, 2)) },
+        async execute(_args, exec) {
+            const state = await toolCwd(engine, exec);
+            return nextPayload(state);
+        },
+    };
+}
+function nextPayload(state) {
+    const current = state.milestones.find((milestone) => milestone.status === 'in_progress');
+    const gate = current === undefined ? undefined : (current.gate ?? state.gates[state.origin.language]);
+    return {
+        phase: state.phase,
+        current: current === undefined
+            ? null
+            : {
+                id: current.id,
+                title: current.title,
+                status: current.status,
+                gate,
+                todos: current.todos
+                    .map((id) => state.todos.find((todo) => todo.id === id))
+                    .filter((todo) => todo !== undefined),
+                questions: current.questions,
+            },
+        nextMilestone: state.milestones.find((milestone) => milestone.status === 'pending')?.id ?? null,
+        guidance: state.phase === 'analyzing'
+            ? '先分析原始项目，用 defense_code_update 把架构记成 todo 与里程碑，然后推进阶段。'
+            : state.phase === 'skeletonizing'
+                ? '开始搭骨架：剥掉非核心功能，留下带注释的 TODO 桩，用 /thesis-defense check 跑通编译验证门。'
+                : state.phase === 'learning'
+                    ? '推进当前里程碑：带学生走完它的 todo，逐个提出追问，并对照期望要点评分。'
+                    : '全部里程碑已验证：总结学生现在能讲清哪些设计。',
+    };
+}
+function updateTool(ctx, engine) {
+    return {
+        name: 'defense_code_update',
+        description: '对本会话 cwd 的代码演练状态施加一次「经校验的」改动：登记 todo 与里程碑、迁移 todo 状态、推进阶段、' +
+            '驱动追问与评分、重试里程碑。每一次改动都会立即落盘。',
+        parameters: {
+            type: 'object',
+            required: ['action'],
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: [
+                        'create',
+                        'upsert_todo',
+                        'upsert_milestone',
+                        'set_todo_status',
+                        'advance_phase',
+                        'ask_question',
+                        'give_hint',
+                        'assess_answer',
+                        'retry_milestone',
+                        'check_gate',
+                    ],
+                },
+                originPath: { type: 'string', description: '原始项目的绝对路径，action=create 时必填。' },
+                language: { type: 'string', description: 'action=create 时的语言键，如 "go"。' },
+                level: { type: 'string', enum: ['beginner', 'intermediate', 'advanced'], description: 'action=create 时的学生水平。' },
+                module: { type: 'string', description: 'action=create 时可选：只聚焦某个子模块。' },
+                todo: TODO_SCHEMA,
+                milestone: MILESTONE_SCHEMA,
+                todoId: { type: 'string' },
+                status: { type: 'string', enum: [...TODO_STATUS] },
+                phase: { type: 'string', enum: [...PHASES] },
+                milestoneId: { type: 'string' },
+                questionIndex: { type: 'integer' },
+                passed: { type: 'boolean' },
+                note: { type: 'string', description: 'assess_answer 的评分备注。' },
+            },
+            additionalProperties: false,
+        },
+        output: { schema: { type: 'string' }, render: (_args, value) => text(String(value)) },
+        async execute(args, exec) {
+            const cwd = exec.agent?.session.header.cwd;
+            if (cwd === undefined) {
+                throw new Error('learn_* 工具需要会话 cwd，但本次调用没有绑定 agent');
+            }
+            const update = args;
+            if (update.action === 'create') {
+                const state = await engine.create(cwd, {
+                    origin: {
+                        path: requireFieldValue(update, 'originPath', 'create'),
+                        language: update.language ?? 'go',
+                    },
+                    scope: {
+                        level: update.level ?? 'beginner',
+                        ...(update.module !== undefined ? { module: update.module } : {}),
+                    },
+                });
+                return `已为 ${state.origin.path} 创建代码演练（${state.origin.language}，${state.scope.level}）。\n${engine.describe(state)}`;
+            }
+            const state = await toolCwd(engine, exec);
+            if (update.action === 'check_gate') {
+                return await checkGate(ctx, engine, exec, cwd, state, update);
+            }
+            const result = applyUpdate(engine, state, update);
+            await engine.save(cwd, state);
+            return result;
+        },
+        timeoutMs: 60_000,
+    };
+}
+/** 从模型侧跑一次里程碑验证门，并渲染结论。 */
+async function checkGate(ctx, engine, exec, cwd, state, args) {
+    const milestone = pickCheckMilestone(state.milestones, args.milestoneId);
+    if (milestone === undefined) {
+        throw new Error(args.milestoneId === undefined
+            ? '当前没有 in_progress 或 failed 的里程碑，没有可检查的对象'
+            : `未知里程碑 "${args.milestoneId}"`);
+    }
+    const settled = await runMilestoneGate(ctx, engine, cwd, state, milestone, exec.signal, exec.agent?.session);
+    const label = `验证门 "${settled.command.join(' ')}"`;
+    if (settled.interrupted)
+        return `${label} 被中断；该里程碑已标记为 failed`;
+    if (settled.outcome.kind === 'failed') {
+        return `${label} 失败（退出码 ${settled.exitCode}）；该里程碑已标记为 failed。\nstderr 末尾：\n${settled.stderr}`;
+    }
+    if (settled.outcome.kind === 'pending-questions') {
+        return `${label} 通过，但仍有 ${milestone.questions.filter((question) => question.status !== 'passed').length} 个问题未通过：先提问并评分，再重跑 check_gate。`;
+    }
+    return `${label} 通过 —— 里程碑 "${milestone.id}" 已验证。${state.phase === 'complete' ? ' 全部里程碑已验证：本次代码演练完成。' : ''}`;
+}
+function pickCheckMilestone(milestones, requestedId) {
+    if (requestedId !== undefined)
+        return milestones.find((milestone) => milestone.id === requestedId);
+    return (milestones.find((milestone) => milestone.status === 'in_progress') ??
+        milestones.find((milestone) => milestone.status === 'failed'));
+}
+function applyUpdate(engine, state, args) {
+    switch (args.action) {
+        case 'upsert_todo': {
+            if (args.todo === undefined)
+                throw new Error('upsert_todo 需要 "todo"');
+            engine.upsertTodo(state, args.todo);
+            return `已登记 todo ${args.todo.id}（${args.todo.where}）`;
+        }
+        case 'upsert_milestone': {
+            if (args.milestone === undefined)
+                throw new Error('upsert_milestone 需要 "milestone"');
+            engine.upsertMilestone(state, args.milestone);
+            return `已登记里程碑 ${args.milestone.id}（${args.milestone.title}）：${args.milestone.todos.length} 个 todo、${args.milestone.questions.length} 个问题`;
+        }
+        case 'set_todo_status': {
+            requireField(args, 'todoId', 'set_todo_status');
+            requireField(args, 'status', 'set_todo_status');
+            engine.setTodoStatus(state, args.todoId, args.status);
+            return `todo ${args.todoId} → ${args.status}`;
+        }
+        case 'advance_phase': {
+            requireField(args, 'phase', 'advance_phase');
+            engine.advancePhase(state, args.phase);
+            return `阶段 → ${state.phase}${state.phase === 'learning' ? `；当前里程碑：${state.milestones.find((milestone) => milestone.status === 'in_progress')?.id ?? '无'}` : ''}`;
+        }
+        case 'ask_question': {
+            requireField(args, 'milestoneId', 'ask_question');
+            requireField(args, 'questionIndex', 'ask_question');
+            engine.askQuestion(state, args.milestoneId, args.questionIndex);
+            return `问题 ${args.milestoneId}[${args.questionIndex}] 已标记为已提出`;
+        }
+        case 'give_hint': {
+            requireField(args, 'milestoneId', 'give_hint');
+            requireField(args, 'questionIndex', 'give_hint');
+            const hint = engine.giveHint(state, args.milestoneId, args.questionIndex);
+            return hint === null
+                ? `${args.milestoneId}[${args.questionIndex}] 的提示阶梯已用尽；公布答案并让学生复述，然后再评分`
+                : `提示 ${args.milestoneId}[${args.questionIndex}]：${hint}`;
+        }
+        case 'assess_answer': {
+            requireField(args, 'milestoneId', 'assess_answer');
+            requireField(args, 'questionIndex', 'assess_answer');
+            requireField(args, 'passed', 'assess_answer');
+            engine.assessAnswer(state, args.milestoneId, args.questionIndex, args.passed, args.note);
+            return `问题 ${args.milestoneId}[${args.questionIndex}] 评分：${args.passed ? '通过' : '未通过'}`;
+        }
+        case 'retry_milestone': {
+            requireField(args, 'milestoneId', 'retry_milestone');
+            engine.retryMilestone(state, args.milestoneId);
+            return `里程碑 ${args.milestoneId} 已重新打开，可以再试一次`;
+        }
+        default:
+            throw new Error(`未知的更新动作 "${args.action}"`);
+    }
+}
+function requireField(args, key, action) {
+    if (args[key] === undefined)
+        throw new Error(`${action} 需要 "${key}"`);
+}
+/** 取一个必填字符串字段（收窄类型），否则抛错。 */
+function requireFieldValue(args, key, action) {
+    const value = args[key];
+    if (typeof value !== 'string' || value === '')
+        throw new Error(`${action} 需要 "${key}"`);
+    return value;
+}
+/** pre-step 注入用的随机 id 生成器；导出以便复用。 */
+export function newMessageId() {
+    return randomUUID();
+}
+export { isLearningError };

package/lib/codewalk/types.d.ts

@@ -0,0 +1,151 @@
+/**
+ * 演练状态 schema：持久化在 `<cwd>/.paper/state.json`。
+ *
+ * 一个文件随演练骨架仓库一起走，因此进度能跨过每一次会话边界：里程碑、todo
+ * 状态、已提出的问题、评分备注、验证门记录全都落在这里，而不是留在对话记忆里。
+ *
+ * @module dsh-thesis/codewalk
+ */
+/** 难度：1（读数据模型）到 4（分布式协同）。 */
+export type Difficulty = 1 | 2 | 3 | 4;
+/** 一个带注释的骨架桩：这段代码做什么（WHAT）以及怎么重建（HOW）。 */
+export interface Todo {
+    /** 供里程碑引用的稳定 id，如 "t3"。 */
+    readonly id: string;
+    /** 文件与符号位置，如 "internal/store/task.go SaveTask"。 */
+    readonly where: string;
+    /** 一句话说明这个方法的目的。 */
+    readonly what: string;
+    /** 分步实现提示。 */
+    readonly steps: readonly string[];
+    /** 可选的坑、设计理由与语言/库特性。 */
+    readonly hint?: string;
+    /** 难度评级。 */
+    readonly difficulty: Difficulty;
+    status: TodoStatus;
+}
+export type TodoStatus = 'pending' | 'in_progress' | 'done';
+/** 一个验证门：一条必须成功的可执行命令行。 */
+export interface GateSpec {
+    /** 命令与参数，如 ["go", "build", "./..."]。 */
+    build: string[];
+}
+/** 一次实际执行的验证门：里程碑确实被验证过的证据。 */
+export interface GateRecord {
+    /** 该验证门所属的里程碑 id。 */
+    readonly milestone: string;
+    /** 实际执行的命令行。 */
+    readonly command: readonly string[];
+    /** 进程退出码。 */
+    readonly exitCode: number;
+    /** 捕获的 stdout，受 `maxCapturedOutput` 截断。 */
+    readonly stdout: string;
+    /** 捕获的 stderr，受 `maxCapturedOutput` 截断。 */
+    readonly stderr: string;
+    /** 墙钟耗时（毫秒）。 */
+    readonly durationMs: number;
+    /** 执行时刻（epoch 毫秒）。 */
+    readonly at: number;
+}
+/** 一个追问：含评分标准与升级提示。 */
+export interface Question {
+    /** AI 应该向学生提出的问题。 */
+    readonly ask: string;
+    /**
+     * 作为评分标准的期望答案要点。AI 用它与学生的回答比对，而不是凭感觉打分。
+     * 绝不直接展示给学生；只能通过提示阶梯逐步接近。
+     */
+    readonly expected: readonly string[];
+    /** 逐步升级的提示，在公布答案之前一次给一条。 */
+    readonly hints: readonly string[];
+    status: QuestionStatus;
+    /** 已经给过多少条提示（0..hints.length）。 */
+    hintLevel: number;
+    /** 评分定分时记录的备注。 */
+    note?: string;
+}
+export type QuestionStatus = 'unasked' | 'asked' | 'passed' | 'failed';
+/** 一组相关 todo 加上它的验证门与问题：一个演练步骤。 */
+export interface Milestone {
+    /** 稳定 id，如 "m1"。 */
+    readonly id: string;
+    /** 简短的人类标题，如 "etcd 里的任务 CRUD"。 */
+    readonly title: string;
+    /** 本里程碑覆盖的 todo id。 */
+    readonly todos: readonly string[];
+    /** 里程碑级验证门；缺省时回退到语言级验证门。 */
+    readonly gate?: GateSpec;
+    /** 本里程碑的追问。 */
+    readonly questions: readonly Question[];
+    status: MilestoneStatus;
+}
+export type MilestoneStatus = 'pending' | 'in_progress' | 'verified' | 'failed';
+/** 工作流阶段；严格单向前进。 */
+export type Phase = 'analyzing' | 'skeletonizing' | 'learning' | 'complete';
+/** `create` 时选定的学生水平。 */
+export type LearnerLevel = 'beginner' | 'intermediate' | 'advanced';
+/** 整个持久化演练状态。 */
+export interface LearningState {
+    readonly schemaVersion: 1;
+    phase: Phase;
+    /** 原始项目在哪里、用什么语言。 */
+    readonly origin: {
+        /** 学生要研究的原始项目绝对路径。 */
+        readonly path: string;
+        /** 选择验证门的语言键，如 "go"。 */
+        readonly language: string;
+    };
+    /** create 时捕获的范围配置。 */
+    readonly scope: {
+        /** 可选：只聚焦某个子模块，而不是整个项目。 */
+        readonly module?: string;
+        /** 学生水平校准。 */
+        readonly level: LearnerLevel;
+    };
+    /** 按演练顺序排列的里程碑。 */
+    milestones: Milestone[];
+    /** 全部 todo，隐式按 id 索引。 */
+    todos: Todo[];
+    /** create 时快照下来的语言验证门。 */
+    readonly gates: Readonly<Record<string, GateSpec>>;
+    /** 每一次执行的验证门，最新的在最后。 */
+    records: GateRecord[];
+    /** 最后一次保存的 epoch 毫秒。 */
+    updatedAt: number;
+}
+/** `AiLearningEngine.create` 的新状态输入。 */
+export interface CreateStateInput {
+    readonly origin: LearningState['origin'];
+    readonly scope: LearningState['scope'];
+}
+/**
+ * 代码演练的部署配置（与 `src/config.ts` 的 `CodeWalkthroughOptions` 结构一致）。
+ *
+ * `src/config.ts` 的 `LearnOptions` 要求字段必填，可直接传给引擎；此处的可选
+ * 版本便于单测里只覆盖关心的字段，缺省值由引擎统一回退。
+ */
+export interface LearnOptions {
+    /** 会话 cwd 下存放状态文件的目录。 */
+    stateDir?: string;
+    /** 按语言名索引的验证门，如 "go"。 */
+    gates?: Record<string, GateSpec>;
+    /** 每条验证门输出流保留的最大字符数。 */
+    maxCapturedOutput?: number;
+}
+/** `AiLearningEngine.recordGate` 的结论。 */
+export type GateOutcome = {
+    readonly kind: 'verified';
+} | {
+    readonly kind: 'failed';
+} | {
+    readonly kind: 'pending-questions';
+};
+export interface EngineStateSnapshot {
+    readonly state: LearningState;
+    readonly phase: Phase;
+    readonly current: Milestone | undefined;
+    readonly next: Milestone | undefined;
+    readonly gateCount: number;
+    readonly questionCount: number;
+    readonly doneQuestionCount: number;
+}

package/lib/codewalk/types.js

@@ -0,0 +1,9 @@
+/**
+ * 演练状态 schema：持久化在 `<cwd>/.paper/state.json`。
+ *
+ * 一个文件随演练骨架仓库一起走，因此进度能跨过每一次会话边界：里程碑、todo
+ * 状态、已提出的问题、评分备注、验证门记录全都落在这里，而不是留在对话记忆里。
+ *
+ * @module dsh-thesis/codewalk
+ */
+export {};

package/lib/commands.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 斜杠命令的聚合层。
+ *
+ * `/thesis-defense` 同时覆盖**答辩幻灯**与**代码演练**两块能力，因此它的注册
+ * 放在装配层：`ppt/` 与 `codewalk/` 各自导出处理器，由本文件按子命令调度，
+ * 两个模块之间没有反向依赖（见 DESIGN.md 的分层规则）。
+ *
+ * 命令只做薄封装：解析输入 → 交给对应模块的纯逻辑入口，因此命令行为与工具完全一致。
+ *
+ * @module dsh-thesis/commands
+ */
+import type { CommandInvocation, CommandResult } from '@deepseek-ai/dsh-commands';
+import type { Context } from '@deepseek-ai/cordis';
+import type { PptOptions } from './config.ts';
+import type { PptDeps } from './ppt/actions.ts';
+/** 答辩命令两侧的子命令集合（仅用于错误提示）。 */
+export declare const DEFENSE_COMMAND_HINT = "prepare | convert | check | guide [\u9875\u6570] [undergrad|master] [force] | new <\u539F\u59CB\u9879\u76EE\u8DEF\u5F84> [--lang go] [--level beginner] [--module pkg] | status | check [\u91CC\u7A0B\u7891]";
+/**
+ * 注册 `/thesis-defense`：答辩幻灯 + 代码演练。
+ *
+ * 幻灯侧子命令：`prepare`（= outline）/ `convert` / `check` / `guide`；
+ * 代码演练侧子命令：`new` / `status` / `check`。`check` 两侧同名，按是否给出
+ * 里程碑参数区分——幻灯侧的 check 不接受位置参数。
+ *
+ * headless/ACP 组合没有命令面时静默跳过。
+ */
+export declare function registerDefenseCommand(ctx: Context, options: {
+    ppt: PptOptions;
+}, deps?: PptDeps): void;
+/** 按子命令把一次 `/thesis-defense` 调用分派到幻灯侧或代码演练侧。 */
+export declare function dispatchDefenseCommand(ctx: Context, options: {
+    ppt: PptOptions;
+}, invocation: CommandInvocation, deps?: PptDeps): Promise<CommandResult>;

package/lib/commands.js

@@ -0,0 +1,60 @@
+/**
+ * 斜杠命令的聚合层。
+ *
+ * `/thesis-defense` 同时覆盖**答辩幻灯**与**代码演练**两块能力，因此它的注册
+ * 放在装配层：`ppt/` 与 `codewalk/` 各自导出处理器，由本文件按子命令调度，
+ * 两个模块之间没有反向依赖（见 DESIGN.md 的分层规则）。
+ *
+ * 命令只做薄封装：解析输入 → 交给对应模块的纯逻辑入口，因此命令行为与工具完全一致。
+ *
+ * @module dsh-thesis/commands
+ */
+import { CODEWALK_COMMAND_HINT, handleCodewalkCommand } from "./codewalk/commands.js";
+import { handlePptCommand, PPT_COMMAND_DESCRIPTION, PPT_COMMAND_HINT, PPT_SUBCOMMANDS } from "./ppt/commands.js";
+/** 答辩命令两侧的子命令集合（仅用于错误提示）。 */
+export const DEFENSE_COMMAND_HINT = `${PPT_COMMAND_HINT} | ${CODEWALK_COMMAND_HINT}`;
+/**
+ * 注册 `/thesis-defense`：答辩幻灯 + 代码演练。
+ *
+ * 幻灯侧子命令：`prepare`（= outline）/ `convert` / `check` / `guide`；
+ * 代码演练侧子命令：`new` / `status` / `check`。`check` 两侧同名，按是否给出
+ * 里程碑参数区分——幻灯侧的 check 不接受位置参数。
+ *
+ * headless/ACP 组合没有命令面时静默跳过。
+ */
+export function registerDefenseCommand(ctx, options, deps = {}) {
+    const commands = ctx.get('commands');
+    if (commands === undefined)
+        return;
+    commands.register({
+        name: 'thesis-defense',
+        description: `答辩准备：幻灯与演练。${PPT_COMMAND_DESCRIPTION}；代码演练：new <原始项目路径> | status | check [里程碑]`,
+        input: { hint: DEFENSE_COMMAND_HINT },
+        handler: async (invocation) => {
+            return await dispatchDefenseCommand(ctx, options, invocation, deps);
+        },
+    });
+}
+/** 按子命令把一次 `/thesis-defense` 调用分派到幻灯侧或代码演练侧。 */
+export async function dispatchDefenseCommand(ctx, options, invocation, deps = {}) {
+    const tokens = invocation.rawInput.trim().split(/\s+/).filter(token => token !== '');
+    const sub = (tokens[0] ?? 'prepare').toLowerCase();
+    if (PPT_SUBCOMMANDS.includes(sub)) {
+        return await handlePptCommand(ctx.fs, options, invocation, deps);
+    }
+    if (sub === 'new' || sub === 'status' || (sub === 'check' && tokens.length > 1)) {
+        const engine = ctx.get('paperCodeWalkthrough');
+        if (engine === undefined) {
+            return { kind: 'error', text: '代码演练引擎未装配：请确认插件配置里 codeWalkthrough 已启用。' };
+        }
+        return await handleCodewalkCommand(ctx, engine, invocation);
+    }
+    if (sub === 'check') {
+        // 无里程碑参数的 check 属于幻灯侧质量检查。
+        return await handlePptCommand(ctx.fs, options, invocation, deps);
+    }
+    return {
+        kind: 'error',
+        text: `未知子命令「${sub}」。可用：${DEFENSE_COMMAND_HINT}`,
+    };
+}