dsh-thesis 1.0.0

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

@@ -0,0 +1,198 @@
+/**
+ * 本插件可选消费的宿主表面的结构化契约：命令注册表、shell 执行器，以及接收
+ * 命令的 agent。
+ *
+ * 刻意**不**从 `@deepseek-ai/dsh-*` 导入：已发布的 rc.1 依赖树引用了未发布的包，
+ * 因此外部 bundle 不能安装 dsh 包。这些接口只声明插件真正读取的字段；宿主真实的
+ * 服务在运行期满足它们。必需的 `fs` 接缝在 `fs-types.ts` 里。
+ *
+ * @module dsh-thesis/codewalk
+ */
+/** shell 执行器捕获的一条输出流。 */
+export interface CollectedOutputShape {
+    /** 捕获到的文本 —— 发生截断时是这条流的**尾部**。 */
+    readonly text: string;
+    /** 为 true 表示 `text` 中丢弃了字节。 */
+    readonly truncated: boolean;
+    /** 保存**完整**流的文件路径（若可用）。 */
+    readonly spillPath?: string;
+}
+/** 前台 shell 结果：非零退出会正常 resolve，绝不 reject。 */
+export interface ShellRunResultShape {
+    /** 退出码；进程被信号杀死时为 null。 */
+    readonly exitCode: number | null;
+    /** 终止信号（如 'SIGTERM'）；正常退出时为 null。 */
+    readonly signal: string | null;
+    /** 为 true 表示执行器自身的超时杀掉了命令。 */
+    readonly timedOut: boolean;
+    /** 为 true 表示调用方的 AbortSignal 杀掉了命令。 */
+    readonly aborted: boolean;
+    /** 本次运行实际生效的超时。 */
+    readonly timeoutMs: number;
+    readonly stdout: CollectedOutputShape;
+    readonly stderr: CollectedOutputShape;
+}
+/** 插件会设置的 shell 执行请求子集。 */
+export interface ShellExecSpecShape {
+    /** 完整命令行，如 "go build ./..."。 */
+    readonly command: string;
+    readonly workdir?: string;
+    readonly timeoutMs?: number;
+    readonly stdoutMaxBytes?: number;
+    readonly signal?: AbortSignal;
+    /** 由调用会话解析出的本次调用沙箱策略。 */
+    readonly sandboxPolicy?: unknown;
+}
+/** shell 接缝（`ctx.shell`）；每个宿主由一个 bash provider 提供。 */
+export interface ShellServiceShape {
+    run(spec: ShellExecSpecShape): Promise<ShellRunResultShape>;
+}
+/** 命令被调用时所针对的接收 agent 切片。 */
+export interface AgentShape {
+    readonly session: {
+        readonly header: {
+            /** 会话工作目录；DSH 契约里可缺省（例如无工作区的会话）。 */
+            readonly cwd?: string;
+        };
+    };
+}
+/** 传给某个已注册命令 handler 的调用信息。 */
+export interface CommandInvocationShape {
+    readonly commandId: unknown;
+    readonly agent: AgentShape;
+    readonly rawInput: string;
+    readonly signal: AbortSignal;
+}
+/** 由调度 UI 直接渲染的命令结果。 */
+export type CommandResultShape = {
+    readonly kind: 'success';
+    readonly text?: string;
+} | {
+    readonly kind: 'error';
+    readonly text: string;
+};
+/** 插件自有命令注册（`ctx.commands.register`）。 */
+export interface CommandDefinitionShape {
+    readonly name: string;
+    readonly description: string;
+    readonly input?: {
+        readonly hint: string;
+    };
+    readonly recordInput?: boolean;
+    handler(invocation: CommandInvocationShape): CommandResultShape | Promise<CommandResultShape>;
+}
+/** 命令注册表（`ctx.commands`）；在 headless 组合里是可选的。 */
+export interface CommandsServiceShape {
+    register(definition: CommandDefinitionShape): unknown;
+}
+/** 面向模型的消息或工具渲染中的一个文本内容块。 */
+export interface TextBlockShape {
+    readonly type: 'text';
+    readonly text: string;
+}
+/** 工具注册表（`ctx.tools`）；在无执行器的组合里是可选的。 */
+export interface ToolsServiceShape {
+    register(definition: ToolDefinitionShape): unknown;
+}
+/** 一个已注册的工具：JSON Schema 参数 + 执行 + 渲染。 */
+export interface ToolDefinitionShape {
+    readonly name: string;
+    readonly description: string;
+    /** 参数的 JSON Schema 对象。 */
+    readonly parameters: Record<string, unknown>;
+    readonly output: {
+        readonly schema: Record<string, unknown>;
+        render(args: unknown, value: unknown): TextBlockShape[];
+    };
+    execute(args: unknown, exec: ToolRunContextShape): Promise<unknown>;
+    readonly timeoutMs?: number;
+}
+/** 交给工具主体的运行期上下文。 */
+export interface ToolRunContextShape {
+    readonly callId: unknown;
+    /** 本次调用所代表的 agent；在无执行器的循环里缺席。 */
+    readonly agent?: AgentShape;
+    readonly signal: AbortSignal;
+}
+/** 为 pre-step 上下文注入的一条临时 user 角色消息。 */
+export interface InjectedUserMessageShape {
+    readonly id: string;
+    readonly role: 'user';
+    readonly content: readonly TextBlockShape[];
+    readonly source: {
+        readonly kind: 'plugin';
+        readonly plugin: string;
+        readonly form: string;
+        readonly sections: readonly {
+            readonly name: string;
+            readonly text: string;
+        }[];
+    };
+}
+/** 插件扩展的 `agent/pre-step` waterfall 决策。 */
+export interface PreStepDecisionShape {
+    readonly kind: 'enter' | 'reject';
+    readonly messages: readonly InjectedUserMessageShape[];
+}
+/** 一次 `agent/pre-step` waterfall 派发的载荷。 */
+export interface PreStepPayloadShape {
+    readonly agent: AgentShape;
+    readonly turn: number;
+    readonly step: number;
+    readonly signal: AbortSignal;
+}
+/** 技能摘要携带的模型/用户可调用性开关。 */
+export interface SkillInvocationPolicyShape {
+    readonly modelInvocable: boolean;
+    readonly userInvocable: boolean;
+}
+/** provider 特有的相对技能资源基址。 */
+export type SkillResourceBaseShape = {
+    readonly kind: 'directory';
+    readonly path: string;
+} | {
+    readonly kind: 'url';
+    readonly url: string;
+} | {
+    readonly kind: 'opaque';
+    readonly description: string;
+};
+/** 一条 provider 目录条目。 */
+export interface SkillCandidateShape {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse?: string;
+    readonly invocation: SkillInvocationPolicyShape;
+    readonly provider: string;
+    readonly source: string;
+    readonly resourceBase?: SkillResourceBaseShape;
+    /** 同名技能里 rank 更小者胜出。 */
+    readonly rank: number;
+    /** provider 自有的不透明句柄，会原样传回 `provider.get()`。 */
+    readonly locator: unknown;
+    readonly path?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** `provider.get()` 返回的完整已解析技能正文。 */
+export interface SkillDefinitionShape {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse?: string;
+    readonly invocation: SkillInvocationPolicyShape;
+    readonly provider: string;
+    readonly source: string;
+    readonly resourceBase?: SkillResourceBaseShape;
+    readonly content: string;
+    readonly path?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** 注册在 `ctx.skills` 上的一个技能来源。 */
+export interface SkillsProviderShape {
+    readonly name: string;
+    list(options: unknown): Promise<readonly SkillCandidateShape[]>;
+    get(candidate: SkillCandidateShape, options: unknown): Promise<SkillDefinitionShape | undefined>;
+}
+/** 技能注册表（`ctx.skills`）；在最小组合里是可选的。 */
+export interface SkillsServiceShape {
+    registerProvider(create: (control: unknown) => SkillsProviderShape): () => void;
+}

package/lib/codewalk/host-types.js

@@ -0,0 +1,11 @@
+/**
+ * 本插件可选消费的宿主表面的结构化契约：命令注册表、shell 执行器，以及接收
+ * 命令的 agent。
+ *
+ * 刻意**不**从 `@deepseek-ai/dsh-*` 导入：已发布的 rc.1 依赖树引用了未发布的包，
+ * 因此外部 bundle 不能安装 dsh 包。这些接口只声明插件真正读取的字段；宿主真实的
+ * 服务在运行期满足它们。必需的 `fs` 接缝在 `fs-types.ts` 里。
+ *
+ * @module dsh-thesis/codewalk
+ */
+export {};

package/lib/codewalk/prestep.d.ts

@@ -0,0 +1,17 @@
+/**
+ * pre-step 进度注入：当会话 cwd 下存在进行中的代码演练时，每个 agent step 都会
+ * 收到一张紧凑的进度卡片，因此无论是续接的会话还是全新的会话，都不必从零重建
+ * 这次演练的全部上下文。
+ *
+ * 卡片只在状态文件确实变化时才重新注入（按 agent 用 `updatedAt` 跟踪），把
+ * token 开销压到「每次状态变更一张卡」。
+ *
+ * @module dsh-thesis/codewalk
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { AiLearningEngine } from './engine.ts';
+import type { InjectedUserMessageShape } from './host-types.ts';
+/** 为一份状态快照构造注入用的进度消息。 */
+export declare function buildProgressMessage(state: Awaited<ReturnType<AiLearningEngine['load']>> & object): InjectedUserMessageShape;
+/** 注册 pre-step 监听器；只在状态变化时重新注入。 */
+export declare function registerPreStep(ctx: Context, engine: AiLearningEngine): void;

package/lib/codewalk/prestep.js

@@ -0,0 +1,62 @@
+/**
+ * pre-step 进度注入：当会话 cwd 下存在进行中的代码演练时，每个 agent step 都会
+ * 收到一张紧凑的进度卡片，因此无论是续接的会话还是全新的会话，都不必从零重建
+ * 这次演练的全部上下文。
+ *
+ * 卡片只在状态文件确实变化时才重新注入（按 agent 用 `updatedAt` 跟踪），把
+ * token 开销压到「每次状态变更一张卡」。
+ *
+ * @module dsh-thesis/codewalk
+ */
+import { AiLearningEngine } from "./engine.js";
+import { newMessageId } from "./tools.js";
+/** 为一份状态快照构造注入用的进度消息。 */
+export function buildProgressMessage(state) {
+    const text = [
+        '当前工作区有一个进行中的代码演练（把自己的系统拆成讲得清的模块，并用可评分的追问确认你答辩时讲得出实现细节）。请带学生把它走完。',
+        '',
+        '和学生一起推进：带他做完当前里程碑的 todo，逐个提出追问，先沿提示阶梯升级再公布答案，并对照期望要点评分。用 defense_code_status、defense_code_next、defense_code_update 三个工具；只有学生说“做完了”才跑 "/thesis-defense check <milestone>"。',
+        '',
+    ].join('\n');
+    const full = `${text}${JSON.stringify(state, null, 2)}`;
+    return {
+        id: newMessageId(),
+        role: 'user',
+        content: [{ type: 'text', text: full }],
+        source: {
+            kind: 'plugin',
+            plugin: 'dsh-thesis',
+            form: 'snapshot',
+            sections: [{ name: '代码演练进度', text: full }],
+        },
+    };
+}
+/** 注册 pre-step 监听器；只在状态变化时重新注入。 */
+export function registerPreStep(ctx, engine) {
+    const lastInjected = new WeakMap();
+    // 宿主的 `agent/pre-step` waterfall 由本 bundle 无法安装的包声明，
+    // 因此事件名按无类型方式派发。
+    const on = ctx.on.bind(ctx);
+    on('agent/pre-step', async (payload, next) => {
+        const { agent, signal } = payload;
+        const decision = await next();
+        if (decision.kind === 'reject' || signal.aborted)
+            return decision;
+        const cwd = agent?.session?.header?.cwd;
+        if (typeof cwd !== 'string')
+            return decision;
+        let state;
+        try {
+            state = await engine.load(cwd);
+        }
+        catch {
+            return decision;
+        }
+        if (state === undefined || state.phase === 'complete')
+            return decision;
+        if (lastInjected.get(agent) === state.updatedAt)
+            return decision;
+        lastInjected.set(agent, state.updatedAt);
+        return { kind: 'enter', messages: [...decision.messages, buildProgressMessage(state)] };
+    }, { prepend: true });
+}

package/lib/codewalk/register.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 代码演练模块的装配入口（`apply` 之外唯一需要调用的函数）。
+ *
+ * 模块的角色：把 AI 写的系统代码拆成「能跑的骨架 + 可评分的追问」，
+ * 保证学生答辩时讲得出自己系统的实现与取舍。引擎守住流程，模型负责教学。
+ *
+ * 装配顺序与 `src/index.ts` 的无关，四个表面互不依赖：
+ * 引擎 → `paperCodeWalkthrough` 服务 → 命令 / 模型工具 / pre-step 注入 / 技能提供者。
+ *
+ * 注意：本文件只做**装配**，不导入 `src/config.ts` 的运行时值（只导入类型），
+ * 因此单测可以在不安装 schemastery 的前提下直接 `import` 它。
+ *
+ * @module dsh-thesis/codewalk
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { CodeWalkthroughOptions } from '../config.ts';
+/**
+ * 用宿主 `dsh-thesis` 的配置装配代码演练模块。
+ *
+ * @param ctx 插件 fiber 的上下文（需要 `fs`；`tools`/`skills` 可选）。
+ * @param options 来自 `resolveConfig(config).codeWalkthrough` 的已解析配置。
+ */
+export declare function registerCodewalk(ctx: Context, options: CodeWalkthroughOptions): void;

package/lib/codewalk/register.js

@@ -0,0 +1,31 @@
+/**
+ * 代码演练模块的装配入口（`apply` 之外唯一需要调用的函数）。
+ *
+ * 模块的角色：把 AI 写的系统代码拆成「能跑的骨架 + 可评分的追问」，
+ * 保证学生答辩时讲得出自己系统的实现与取舍。引擎守住流程，模型负责教学。
+ *
+ * 装配顺序与 `src/index.ts` 的无关，四个表面互不依赖：
+ * 引擎 → `paperCodeWalkthrough` 服务 → 命令 / 模型工具 / pre-step 注入 / 技能提供者。
+ *
+ * 注意：本文件只做**装配**，不导入 `src/config.ts` 的运行时值（只导入类型），
+ * 因此单测可以在不安装 schemastery 的前提下直接 `import` 它。
+ *
+ * @module dsh-thesis/codewalk
+ */
+import { AiLearningEngine } from "./engine.js";
+import { registerPreStep } from "./prestep.js";
+import { registerSkill } from "./skill.js";
+import { registerTools } from "./tools.js";
+/**
+ * 用宿主 `dsh-thesis` 的配置装配代码演练模块。
+ *
+ * @param ctx 插件 fiber 的上下文（需要 `fs`；`tools`/`skills` 可选）。
+ * @param options 来自 `resolveConfig(config).codeWalkthrough` 的已解析配置。
+ */
+export function registerCodewalk(ctx, options) {
+    const engine = new AiLearningEngine(ctx, options);
+    ctx.provide('paperCodeWalkthrough', engine);
+    registerTools(ctx, engine);
+    registerPreStep(ctx, engine);
+    registerSkill(ctx);
+}

package/lib/codewalk/skill.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 随包发布的 `code-walkthrough` 技能提供者（答辩层的代码演练方法论）。
+ *
+ * 把「答辩前把自己的系统讲清楚」的方法论打包成一个 Markdown 技能
+ * （与 `@deepseek-ai/dsh-skill-badge` 同一套做法）：只登记一个不可变候选，
+ * 正文从包的 `skills/code-walkthrough/` 目录读取，并把该目录暴露为资源基址，
+ * 因此正文里的 `references/*.md` 可以按需通过技能工具加载。
+ * 方法论始终是可编辑的 Markdown —— 插件代码只承载机制。
+ *
+ * @module dsh-thesis/codewalk
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const SKILL_NAME = "code-walkthrough";
+/** 组合了技能注册表时注册这个随包技能提供者。 */
+export declare function registerSkill(ctx: Context): void;

package/lib/codewalk/skill.js

@@ -0,0 +1,57 @@
+/**
+ * 随包发布的 `code-walkthrough` 技能提供者（答辩层的代码演练方法论）。
+ *
+ * 把「答辩前把自己的系统讲清楚」的方法论打包成一个 Markdown 技能
+ * （与 `@deepseek-ai/dsh-skill-badge` 同一套做法）：只登记一个不可变候选，
+ * 正文从包的 `skills/code-walkthrough/` 目录读取，并把该目录暴露为资源基址，
+ * 因此正文里的 `references/*.md` 可以按需通过技能工具加载。
+ * 方法论始终是可编辑的 Markdown —— 插件代码只承载机制。
+ *
+ * @module dsh-thesis/codewalk
+ */
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+const SKILL_DIR_URL = new URL('../../skills/code-walkthrough/', import.meta.url);
+const SKILL_BODY_URL = new URL('SKILL.md', SKILL_DIR_URL);
+/** 技能正文的磁盘路径；`readFile` 在本仓库的类型面里只接受字符串路径。 */
+const SKILL_BODY_PATH = fileURLToPath(SKILL_BODY_URL);
+const RESOURCE_BASE = { kind: 'directory', path: fileURLToPath(SKILL_DIR_URL) };
+export const SKILL_NAME = 'code-walkthrough';
+const PROVIDER_NAME = 'dsh-thesis';
+const DESCRIPTION = '把自己系统（常常是 AI 写的）拆成能讲清的模块，并用可评分的追问确认你在答辩席上讲得出实现细节与取舍。' +
+    '答辩几乎必问「你的系统怎么实现的」「为什么这么设计」，答不上来是最常见的失分点。' +
+    '触发场景：「答辩前我要搞懂自己系统的实现」「老师会问实现细节」「把这些代码拆成我讲得清的部分」。';
+const WHEN_TO_USE = '当用户说「答辩前要把自己的系统讲明白」「老师会问实现细节/为什么这么设计」「帮我理清这套代码好答辩」，' +
+    '或在 `thesis_defense` 生成了预答辩问题库、需要逐个准备「实现细节」类问题时触发。';
+const INVOCATION = { modelInvocable: true, userInvocable: true };
+const CANDIDATE = {
+    name: SKILL_NAME,
+    description: DESCRIPTION,
+    whenToUse: WHEN_TO_USE,
+    invocation: INVOCATION,
+    provider: PROVIDER_NAME,
+    source: 'bundled',
+    resourceBase: RESOURCE_BASE,
+    // 低于所有本地文件系统来源（100–600），因此用户自己的同名技能会优先；
+    // 同时足够高，不会抢别的技能。
+    rank: 900,
+    locator: SKILL_BODY_URL,
+};
+const provider = {
+    name: PROVIDER_NAME,
+    list: () => Promise.resolve([CANDIDATE]),
+    async get(_candidate) {
+        return {
+            ...CANDIDATE,
+            ...(CANDIDATE.whenToUse !== undefined ? { whenToUse: CANDIDATE.whenToUse } : {}),
+            content: await readFile(SKILL_BODY_PATH, 'utf8'),
+        };
+    },
+};
+/** 组合了技能注册表时注册这个随包技能提供者。 */
+export function registerSkill(ctx) {
+    const skills = ctx.get('skills');
+    if (skills === undefined)
+        return;
+    skills.registerProvider(() => provider);
+}

package/lib/codewalk/tools.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 面向前模型的工具：`defense_code_status`、`defense_code_next`、`defense_code_update`。
+ *
+ * 这三个工具是模型操作引擎的手柄：分析架构、安排教学由模型完成，但每一次改动
+ * 都必须穿过引擎校验过的状态迁移，并立刻落盘。工具注册走 `ctx.tools`（只有在
+ * 组合了工具注册表时才注册）；定义是纯对象，因此不需要任何 `@deepseek-ai/dsh-*`
+ * 的运行时导入。
+ *
+ * @module dsh-thesis/codewalk
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { AiLearningEngine } from './engine.ts';
+import { isLearningError } from './errors.ts';
+/** 组合了工具注册表时，注册这三个面向前模型的工具。 */
+export declare function registerTools(ctx: Context, engine: AiLearningEngine): void;
+/** pre-step 注入用的随机 id 生成器；导出以便复用。 */
+export declare function newMessageId(): string;
+export { isLearningError };