dsh-thesis 1.0.0

package/lib/codewalk/commands.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 人类可用的 `/thesis-defense` 命令：`new`、`status`、`check`。
+ *
+ * 只有在组合了命令适配器时才通过 `ctx.commands` 注册（交互式部署）；纯 headless
+ * 与仅 ACP 的组合没有命令注册表，直接跳过这一层表面。命令面的结果直接渲染，
+ * 不进入模型历史。
+ *
+ * @module dsh-thesis/codewalk
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { AiLearningEngine } from './engine.ts';
+import type { CommandInvocationShape, CommandResultShape } from './host-types.ts';
+/** 代码演练侧的子命令（与幻灯侧区分）。 */
+export declare const CODEWALK_SUBCOMMANDS: readonly string[];
+/** 命令的展示元信息（装配层注册 `/thesis-defense` 时使用）。 */
+export declare const CODEWALK_COMMAND_HINT = "new <\u539F\u59CB\u9879\u76EE\u8DEF\u5F84> [--lang go] [--level beginner] [--module pkg] | status | check [\u91CC\u7A0B\u7891]";
+/**
+ * 代码演练侧的命令处理器（由装配层在 `/thesis-defense` 下调度）。
+ *
+ * `rawInput` 是命令名之后的全部输入；本函数只认代码演练侧的子命令
+ * （`new` / `status` / `check`），其余一律交回装配层。
+ */
+export declare function handleCodewalkCommand(ctx: Context, engine: AiLearningEngine, invocation: CommandInvocationShape): Promise<CommandResultShape>;

package/lib/codewalk/commands.js

@@ -0,0 +1,168 @@
+/**
+ * 人类可用的 `/thesis-defense` 命令：`new`、`status`、`check`。
+ *
+ * 只有在组合了命令适配器时才通过 `ctx.commands` 注册（交互式部署）；纯 headless
+ * 与仅 ACP 的组合没有命令注册表，直接跳过这一层表面。命令面的结果直接渲染，
+ * 不进入模型历史。
+ *
+ * @module dsh-thesis/codewalk
+ */
+import { AiLearningEngine } from "./engine.js";
+import { isLearningError } from "./errors.js";
+import { runMilestoneGate } from "./gate.js";
+const DEFAULT_LANGUAGE = 'go';
+const LEVELS = ['beginner', 'intermediate', 'advanced'];
+/** 会话没有工作目录时的统一答复。 */
+const NO_WORKSPACE = {
+    kind: 'error',
+    text: '本次会话没有工作目录，无法定位代码演练状态。请在论文工作区目录里打开会话。',
+};
+/** 代码演练侧的子命令（与幻灯侧区分）。 */
+export const CODEWALK_SUBCOMMANDS = ['new', 'status', 'check'];
+/** 命令的展示元信息（装配层注册 `/thesis-defense` 时使用）。 */
+export const CODEWALK_COMMAND_HINT = 'new <原始项目路径> [--lang go] [--level beginner] [--module pkg] | status | check [里程碑]';
+/**
+ * 代码演练侧的命令处理器（由装配层在 `/thesis-defense` 下调度）。
+ *
+ * `rawInput` 是命令名之后的全部输入；本函数只认代码演练侧的子命令
+ * （`new` / `status` / `check`），其余一律交回装配层。
+ */
+export async function handleCodewalkCommand(ctx, engine, invocation) {
+    try {
+        const tokens = invocation.rawInput.trim().split(/\s+/);
+        const sub = tokens[0] ?? '';
+        const args = tokens.slice(1);
+        if (sub === 'new')
+            return await handleNew(engine, invocation, args);
+        if (sub === 'status')
+            return await handleStatus(engine, invocation);
+        if (sub === 'check')
+            return await handleCheck(ctx, engine, invocation, args);
+        return { kind: 'error', text: `未知子命令 "${sub}"；代码演练侧应为 new | status | check` };
+    }
+    catch (error) {
+        if (isLearningError(error))
+            return { kind: 'error', text: error.message };
+        const message = error instanceof Error ? error.message : String(error);
+        return { kind: 'error', text: `内部错误：${message}` };
+    }
+}
+function parseNewArgs(args) {
+    const options = { language: DEFAULT_LANGUAGE, level: 'beginner' };
+    const positional = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--lang' || arg === '--level' || arg === '--module') {
+            const value = args[index + 1];
+            if (value === undefined)
+                continue;
+            if (arg === '--lang')
+                options.language = value;
+            else if (arg === '--level')
+                options.level = value;
+            else
+                options.module = value;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--lang='))
+            options.language = arg.slice('--lang='.length);
+        else if (arg.startsWith('--level='))
+            options.level = arg.slice('--level='.length);
+        else if (arg.startsWith('--module='))
+            options.module = arg.slice('--module='.length);
+        else
+            positional.push(arg);
+    }
+    const first = positional[0];
+    if (first !== undefined)
+        options.path = first;
+    return options;
+}
+async function handleNew(engine, invocation, args) {
+    const options = parseNewArgs(args);
+    if (options.path === undefined) {
+        return {
+            kind: 'error',
+            text: '用法：/thesis-defense new <原始项目路径> [--lang go] [--level beginner] [--module pkg]',
+        };
+    }
+    if (!LEVELS.includes(options.level)) {
+        return { kind: 'error', text: `非法的 level "${options.level}"；应为 ${LEVELS.join(' | ')}` };
+    }
+    const cwd = invocation.agent.session.header.cwd;
+    if (cwd === undefined || cwd === '')
+        return NO_WORKSPACE;
+    const state = await engine.create(cwd, {
+        origin: { path: options.path, language: options.language },
+        scope: { level: options.level, ...(options.module !== undefined ? { module: options.module } : {}) },
+    });
+    return {
+        kind: 'success',
+        text: `已为 ${options.path} 创建代码演练（${options.language}，${options.level}）。\n` +
+            `${engine.describe(state)}\n` +
+            `下一步：让 AI 分析该项目，用 defense_code_update 工具登记 todo 与里程碑。`,
+    };
+}
+async function handleStatus(engine, invocation) {
+    const cwd = invocation.agent.session.header.cwd;
+    if (cwd === undefined || cwd === '')
+        return NO_WORKSPACE;
+    const state = await engine.load(cwd);
+    if (state === undefined) {
+        return { kind: 'error', text: `${cwd} 下没有代码演练状态；请先执行 "/thesis-defense new <原始项目路径>"` };
+    }
+    return { kind: 'success', text: engine.describe(state) };
+}
+async function handleCheck(ctx, engine, invocation, args) {
+    const cwd = invocation.agent.session.header.cwd;
+    if (cwd === undefined || cwd === '')
+        return NO_WORKSPACE;
+    const state = await engine.load(cwd);
+    if (state === undefined) {
+        return { kind: 'error', text: `${cwd} 下没有代码演练状态；请先执行 "/thesis-defense new <原始项目路径>"` };
+    }
+    const milestone = pickMilestone(state.milestones, args[0]);
+    if (milestone === undefined) {
+        return {
+            kind: 'error',
+            text: args[0] === undefined
+                ? '当前没有 in_progress 或 failed 的里程碑，没有可检查的对象'
+                : `未知里程碑 "${args[0]}"`,
+        };
+    }
+    if (milestone.status === 'failed')
+        engine.retryMilestone(state, milestone.id);
+    const settled = await runMilestoneGate(ctx, engine, cwd, state, milestone, invocation.signal, invocation.agent.session);
+    if (settled.interrupted) {
+        return { kind: 'error', text: `验证门 "${settled.command.join(' ')}" 被中断；该里程碑已标记为 failed` };
+    }
+    if (settled.outcome.kind === 'failed') {
+        return {
+            kind: 'error',
+            text: `验证门 "${settled.command.join(' ')}" 失败，退出码 ${settled.exitCode}；该里程碑已标记为 failed。\n` +
+                (settled.stderr.trim() === '' ? `stdout 末尾：\n${settled.stdout}` : `stderr 末尾：\n${settled.stderr}`),
+        };
+    }
+    if (settled.outcome.kind === 'pending-questions') {
+        return {
+            kind: 'success',
+            text: `验证门 "${settled.command.join(' ')}" 通过，但仍有 ${milestone.questions.filter((question) => question.status !== 'passed').length} 个问题未通过。\n` +
+                '让 AI 把追问做完；当验证门为绿且全部问题通过时，该里程碑才算 verified。',
+        };
+    }
+    const next = state.milestones.find((entry) => entry.status === 'in_progress');
+    const complete = state.phase === 'complete';
+    return {
+        kind: 'success',
+        text: `验证门 "${settled.command.join(' ')}" 通过 —— 里程碑 "${milestone.id}" 已验证。\n` +
+            (complete ? '全部里程碑已验证：本次代码演练完成。' : `下一个里程碑：${next?.title ?? '无'}。`),
+    };
+}
+function pickMilestone(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'));
+}

package/lib/codewalk/engine.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 代码演练引擎：一个普通类，由 `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 type { Context } from '@deepseek-ai/cordis';
+import type { StateFileSystem } from './fs-types.ts';
+import type { CreateStateInput, EngineStateSnapshot, GateOutcome, GateRecord, GateSpec, LearningState, LearnOptions, Milestone, Phase, Todo, TodoStatus } from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        paperLearn: AiLearningEngine;
+    }
+}
+/** 已物化全部默认值的解析后配置。 */
+export interface ResolvedConfig {
+    readonly stateDir: string;
+    readonly gates: Readonly<Record<string, GateSpec>>;
+    readonly maxCapturedOutput: number;
+}
+/**
+ * 代码演练引擎。
+ *
+ * 所有状态机方法都直接修改传入的 `state` 对象，并用 `LearningError` 拒绝非法
+ * 迁移。持久化方法一律走注入的文件系统，因此本地与远端后端行为一致。
+ */
+export declare class AiLearningEngine {
+    private readonly ctx;
+    private readonly resolved;
+    constructor(ctx: Context, config?: LearnOptions);
+    /** 解析后的配置（默认值已物化）。 */
+    get config(): ResolvedConfig;
+    /** 宿主文件系统接缝；`inject: ['fs']` 保证其存在。 */
+    private get fs();
+    private stateFilePath;
+    /** 相对会话 cwd 解析状态文件目标。 */
+    stateTarget(cwd: string): Promise<ReturnType<StateFileSystem['resolve']>>;
+    /** `cwd` 下是否已存在演练状态。 */
+    hasState(cwd: string): Promise<boolean>;
+    /**
+     * 读取并校验 `cwd` 下的状态；不存在时返回 `undefined`。
+     * 内容损坏时以 `STATE_INVALID` 拒绝。
+     */
+    load(cwd: string): Promise<LearningState | undefined>;
+    /**
+     * 为一次新的代码演练创建初始状态。
+     *
+     * 已存在状态时以 `STATE_EXISTS` 拒绝（经 `createIfAbsent` 保证竞态安全）；
+     * 源语言没有配置验证门时以 `GATE_UNKNOWN` 拒绝。
+     */
+    create(cwd: string, input: CreateStateInput): Promise<LearningState>;
+    /** 持久化当前状态，并刷新 `updatedAt`。 */
+    save(cwd: string, state: LearningState): Promise<void>;
+    /**
+     * 推进工作流阶段。只允许沿
+     * analyzing → skeletonizing → learning → complete 向前走。
+     * 进入 `learning` 至少需要一个带 todo 的里程碑；
+     * 进入 `complete` 需要每个里程碑都已 verified。
+     */
+    advancePhase(state: LearningState, next: Phase): void;
+    /** 新增或替换一个 todo。被 verified 里程碑引用的 todo 已冻结。 */
+    upsertTodo(state: LearningState, todo: Todo): void;
+    /** 沿 pending → in_progress → done 迁移一个 todo（允许返工）。 */
+    setTodoStatus(state: LearningState, todoId: string, status: TodoStatus): void;
+    private assertTodoEditable;
+    /**
+     * 新增或替换一个里程碑。verified 里程碑已冻结。每个 todo 引用都必须能解析。
+     * 新里程碑从 `pending` 开始；对未关闭里程碑做内容编辑会保留其当前状态。
+     */
+    upsertMilestone(state: LearningState, milestone: Milestone): void;
+    /** 启动第一个 pending 里程碑。要求处于 learning 阶段。 */
+    startNextMilestone(state: LearningState): void;
+    /** 重新打开一个 failed 里程碑，允许再试一次。 */
+    retryMilestone(state: LearningState, milestoneId: string): void;
+    private milestone;
+    /** 提出（或在失分后重提）某个里程碑问题。 */
+    askQuestion(state: LearningState, milestoneId: string, questionIndex: number): void;
+    /**
+     * 为一个已提出的问题给出下一级升级提示。返回提示文本；提示阶梯用尽时返回
+     * `null` —— 此时必须公布答案，并要求学生用自己的话复述，再走 `assessAnswer`。
+     */
+    giveHint(state: LearningState, milestoneId: string, questionIndex: number): string | null;
+    /** 用评分结论（可选评分备注）给一个已提出的问题定分。 */
+    assessAnswer(state: LearningState, milestoneId: string, questionIndex: number, passed: boolean, note?: string): void;
+    private question;
+    /**
+     * 记录一次实际执行的验证门，并把结论折进里程碑。
+     *
+     * - 退出码 0 且所有问题已 passed → `verified`，随后启动下一个 pending
+     *   里程碑（或整个流程完成）；
+     * - 退出码 0 但仍有未通过的问题 → 保持 in_progress（`pending-questions`）；
+     * - 退出码非 0 → `failed`；用 `retryMilestone` 重新打开。
+     */
+    recordGate(state: LearningState, milestoneId: string, input: Omit<GateRecord, 'milestone' | 'at'>): GateOutcome;
+    /** 只读快照，供状态视图、模型工具与注入使用。 */
+    snapshot(state: LearningState): EngineStateSnapshot;
+    /** `/thesis-defense status` 用的人类可读状态文本。 */
+    describe(state: LearningState): string;
+}