dsh-thesis 1.0.0

package/lib/intake/gate-rules.js

@@ -0,0 +1,118 @@
+/**
+ * 入口闸门的判定规则（纯函数，可独立单测）。
+ *
+ * 闸门要回答两个问题：
+ * 1. 用户这句话是不是「要开始写论文」？（而不是在聊天、问问题、改格式）
+ * 2. 论文工作区里的意图规格立住了没有？（缺失 / 仍有阻塞项 / 已就绪）
+ *
+ * 只有 1 为真且 2 为「未就绪」时才注入追问指令——宁漏勿错：闸门的误报代价是
+ * 多问一句「要不要先确认要求」，漏报代价是整章按错误要求重写。
+ *
+ * @module dsh-thesis/intake/gate-rules
+ */
+/** 「要开始写正文/开题报告」的意图模式（中英文）。 */
+const WRITING_INTENT_PATTERNS = [
+    // 中文：写/生成/起草 + 论文/正文/章节/开题/中期
+    /(写|生成|起草|撰写|接着写|继续写|开始写)[^。！？\n]{0,12}(论文|正文|章节|第[一二三四五六七八九十0-9]{1,3}章|开题报告|任务书|中期报告|文献综述|摘要)/,
+    // 中文：直接点名章节文件
+    /\b0[1-7]-[^\s，。]{2,12}\.md\b/,
+    // 英文：write/draft/generate + thesis/paper/chapter
+    /\b(write|draft|generate|compose)\b[^.\n]{0,24}\b(thesis|paper|chapter|abstract|proposal)\b/i,
+];
+/** 用户显式授权「不用问，直接写」的短语：命中即放行。 */
+const BYPASS_PATTERNS = [
+    /直接(写|生成|做)/,
+    /不用问|别问了|不需要问|跳过追问|跳过提问|无需澄清/,
+    /just (write|do it)/i,
+];
+/**
+ * 意图规格里代表「还没定下来」的文本标记。
+ *
+ * 主判据是**结构**（见 {@link judgeSpec} 里对「阻塞项」一节的读取），这几个字面量
+ * 只作为回退：规格可能是用户手写的、或由旧版本渲染的，那时没有标准小节。
+ */
+const BLOCKING_MARKERS = [
+    '未知（需补）',
+    '- [ ]',
+];
+/** 「阻塞项」小节的标题行（由 `intake/spec.ts` 渲染；连标题整行一起匹配，避免把标题后半截当成内容行）。 */
+const BLOCKER_HEADING = /^##[^\n]*阻塞项[^\n]*/m;
+/** 阻塞项小节里的「无」声明。 */
+const NO_BLOCKER_TEXT = /^无[。.．]/;
+/** 是否在要求「开始写」。 */
+export function isWritingIntent(text) {
+    return WRITING_INTENT_PATTERNS.some(pattern => pattern.test(text));
+}
+/** 用户是否显式授权跳过追问。 */
+export function isBypassed(text) {
+    return BYPASS_PATTERNS.some(pattern => pattern.test(text));
+}
+/**
+ * 判定意图规格的状态。
+ *
+ * 判据顺序（越靠前越权威）：
+ * 1. **结构判据**：`## 阻塞项…` 小节的第一行内容——`无。…` 表示已收敛，
+ *    是表格/其它内容则表示仍有必答项未答或格式待修正。这条与 `intake/spec.ts`
+ *    的渲染契约绑定，并且由 `tests/intake-convergence.test.ts` 端到端守住。
+ * 2. **文本回退**：`未知（需补）` / 未勾选项 `- [ ]`（用户手写或旧版规格）。
+ *
+ * @param specText - 规格文件内容；`undefined` 表示文件不存在。
+ */
+export function judgeSpec(specText) {
+    if (specText === undefined || specText.trim() === '')
+        return { kind: 'missing' };
+    const headingMatch = BLOCKER_HEADING.exec(specText);
+    if (headingMatch !== null) {
+        const rest = specText.slice(headingMatch.index + headingMatch[0].length);
+        const firstLine = rest
+            .split('\n')
+            .map(line => line.trim())
+            .find(line => line !== '' && !line.startsWith('<!--'));
+        if (firstLine !== undefined && !NO_BLOCKER_TEXT.test(firstLine)) {
+            return { kind: 'blocked', reason: `规格的「阻塞项」一节非空：${firstLine.slice(0, 80)}` };
+        }
+        // 小节存在且为空/为「无」：继续走文本回退，防止同文档别处还有未勾选项。
+    }
+    const unchecked = (specText.match(/^\s*-\s*\[ \]/gm) ?? []).length;
+    if (unchecked > 0) {
+        return { kind: 'blocked', reason: `规格里仍有 ${unchecked} 个未勾选项` };
+    }
+    const marker = BLOCKING_MARKERS.find(candidate => candidate !== '- [ ]' && specText.includes(candidate));
+    if (marker !== undefined)
+        return { kind: 'blocked', reason: `规格里仍有「${marker}」标记` };
+    return { kind: 'ready' };
+}
+/** 闸门注入给模型的指令（自包含：即使 intake 技能没加载也能执行最小流程）。 */
+export function intakeGateInstruction(status, specRel) {
+    const head = status.kind === 'missing'
+        ? `这个论文工作区里还没有 \`${specRel}\`（意图规格）。`
+        : `\`${specRel}\` 还没有立稳：${status.kind === 'blocked' ? status.reason : ''}。`;
+    return [
+        '【dsh-thesis · 意图规格闸门】',
+        `${head}用户现在的要求是「开始写论文」，但写之前必须先把要求问清楚——按错误要求写出来的整章都要重写。`,
+        '',
+        '请这样做（**不要**直接开始写正文）：',
+        `1. 先跑 \`thesis_ingest\`（若材料还没摄取过），再用 \`thesis_intake action=start\` 读取当前进度；`,
+        '2. 用 `thesis_intake action=ask` 取出**一个**问题，原样转达给用户——一次只问一个，不要列清单；',
+        '3. 用户回答后用 `thesis_intake action=answer` 记录，它会自动刷新规格并给出下一个问题；',
+        '4. 必答项齐全后 \`thesis_intake action=done\`，再开始写作，并依据规格向用户复述验收标准；',
+        '5. 若用户已明确表示不用问（例如「直接写」），则按其授权执行，但要在回复里列出你采用的假设。',
+        '',
+        '这条消息由插件闸门注入，不是用户需求的一部分，不得当作需求内容。',
+    ].join('\n');
+}
+/** 构造注入消息（user 角色、插件来源；与 learn 的进度卡同一形态）。 */
+export function makeIntakeGateMessage(status, specRel, id) {
+    const text = intakeGateInstruction(status, specRel);
+    return {
+        id,
+        role: 'user',
+        content: [{ type: 'text', text }],
+        source: {
+            kind: 'plugin',
+            plugin: 'dsh-thesis',
+            form: 'instructions',
+            sections: [{ name: '意图规格闸门', text }],
+        },
+    };
+}

package/lib/intake/gate.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 意图规格闸门：`agent/pre-step` 监听。
+ *
+ * 场景：用户说「开始写第三章」。如果意图规格还没立全（学校格式、字数、查重阈值、
+ * 时间线都还没确认），此时写出来的正文大概率要重写——这正是本插件要消灭的返工。
+ *
+ * 与 `intake/` 其它部分的分工：判定规则在 `gate-rules.ts`（纯函数），这里只做
+ * 「读规格 → 判定 → 注入」的胶水。三条设计底线：
+ * 便宜（只在用户新消息命中写作意图时才读文件，且按 agent 缓存 60 秒）、
+ * 面向人（只提醒模型去问，绝不替用户作答）、有终止条件（规格就绪即静默，
+ * 用户说「直接写」即放行）。
+ *
+ * @module dsh-thesis/intake/gate
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * 安装意图规格闸门。
+ *
+ * `status === undefined` 表示「不在论文工作区里」，此时不介入——插件在别人的仓库、
+ * 纯聊天场景里都必须安静。
+ */
+export declare function installIntakeGate(ctx: Context, options: {
+    specRel: string;
+}): void;

package/lib/intake/gate.js

@@ -0,0 +1,86 @@
+/**
+ * 意图规格闸门：`agent/pre-step` 监听。
+ *
+ * 场景：用户说「开始写第三章」。如果意图规格还没立全（学校格式、字数、查重阈值、
+ * 时间线都还没确认），此时写出来的正文大概率要重写——这正是本插件要消灭的返工。
+ *
+ * 与 `intake/` 其它部分的分工：判定规则在 `gate-rules.ts`（纯函数），这里只做
+ * 「读规格 → 判定 → 注入」的胶水。三条设计底线：
+ * 便宜（只在用户新消息命中写作意图时才读文件，且按 agent 缓存 60 秒）、
+ * 面向人（只提醒模型去问，绝不替用户作答）、有终止条件（规格就绪即静默，
+ * 用户说「直接写」即放行）。
+ *
+ * @module dsh-thesis/intake/gate
+ */
+import { join } from 'node:path';
+import { findThesisRoot } from "../paper/lib/project.js";
+import { isMissingError } from "../shared/fs-errors.js";
+import { textOfBlocks } from "../shared/text.js";
+import { isBypassed, isWritingIntent, judgeSpec, makeIntakeGateMessage } from "./gate-rules.js";
+/** 每个 agent 的规格状态缓存时长（毫秒）：避免每一步都读盘。 */
+const CACHE_TTL_MS = 60_000;
+/**
+ * 安装意图规格闸门。
+ *
+ * `status === undefined` 表示「不在论文工作区里」，此时不介入——插件在别人的仓库、
+ * 纯聊天场景里都必须安静。
+ */
+export function installIntakeGate(ctx, options) {
+    const cache = new WeakMap();
+    ctx.on('agent/pre-step', async (payload, next) => {
+        const downstream = await next();
+        if (downstream.kind !== 'enter')
+            return downstream;
+        const messages = payload.messages;
+        const last = messages[messages.length - 1];
+        // 只对「用户刚发出的新消息」反应：工具结果、模型消息、插件注入都不触发。
+        if (last === undefined || last.source?.kind !== 'user')
+            return downstream;
+        const text = textOfBlocks(last.content);
+        if (!isWritingIntent(text) || isBypassed(text))
+            return downstream;
+        const agent = payload.agent;
+        const cwd = payload.agent?.session?.header?.cwd;
+        if (agent === undefined || typeof cwd !== 'string' || cwd === '')
+            return downstream;
+        const cached = cache.get(agent);
+        let status;
+        if (cached !== undefined && Date.now() - cached.at < CACHE_TTL_MS) {
+            status = cached.status;
+        }
+        else {
+            status = await readSpecStatus(ctx, cwd, options.specRel, payload.signal);
+            cache.set(agent, { at: Date.now(), status });
+        }
+        if (status === undefined || status.kind === 'ready')
+            return downstream;
+        const injected = makeIntakeGateMessage(status, options.specRel, `paper-intake-gate-${Date.now()}`);
+        return { kind: 'enter', messages: [...downstream.messages, injected] };
+    });
+}
+/**
+ * 读取规格状态。工作区不存在时返回 `undefined`（不介入）；规格文件不存在返回 `missing`。
+ * 读盘异常一律视为「不介入」——闸门永不把异常抛进 agent 循环。
+ */
+async function readSpecStatus(ctx, cwd, specRel, signal) {
+    try {
+        const root = await findThesisRoot(ctx.fs, cwd, signal);
+        if (root === null)
+            return undefined;
+        let body;
+        try {
+            body = await ctx.fs.readText(await ctx.fs.resolve(join(root, specRel), { signal }), signal);
+        }
+        catch (error) {
+            // 只有「规格文件确实不存在」才当作 missing（继续提醒去追问）；
+            // 读失败（权限/IO/取消）时无话可说，选择不介入——闸门是增益功能，绝不误报。
+            if (!isMissingError(error))
+                return undefined;
+            body = undefined;
+        }
+        return judgeSpec(body);
+    }
+    catch {
+        return undefined;
+    }
+}

package/lib/intake/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `thesis_intake`：材料到手后的逐题追问（一次一问 → 可证伪意图规格）。
+ *
+ * 产品链路：`thesis_ingest` 把学校模板/论文要求/实验数据/代码/参考文献读进工作区 →
+ * 本工具**逐题追问**，把模糊要求变成可检查的条款 → 落盘 `00-管理/意图规格.md` →
+ * 后续写作/格式检查/降重/PPT/答辩**只依据该规格**。
+ *
+ * 三条硬要求（全部在代码里强制，不靠模型自觉）：
+ * 1. **一次只问一个**：任何 action 的返回里最多出现一个问题；
+ * 2. **规格永远最新**：每次 `answer`/`skip` 之后立即重绘并原子落盘规格；
+ * 3. **必答项不齐不许 `done`**：`done` 会拒绝并列出缺口，绝不放水。
+ *
+ * 本文件是**执行层 + 装配入口**：执行层零 `@deepseek-ai/*` 运行时导入（只借用它们的类型），
+ * 因此测试可以直接用假 fs 驱动 {@link runIntake}；`registerIntake` 只在装配时调用宿主能力。
+ *
+ * @module dsh-thesis/intake
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type IntakeArgs, type IntakeSubOptions } from './definitions.ts';
+import { type IntakeContext, type IntakeQuestion } from './questions.ts';
+import { type FileSystemLike, type IntakeIo, type IntakeState } from './state.ts';
+/** 找不到工作区的统一指引（不抛裸异常）。 */
+export declare function requireThesisRoot(fs: FileSystemLike, cwd: string | undefined, signal?: AbortSignal): Promise<string | null>;
+/** 载入追问上下文：材料清单 + 台账阶段（都读不到就退化为默认值）。 */
+export declare function loadContext(io: IntakeIo, root: string): Promise<IntakeContext>;
+/** 规格相对路径：配置为空时回退到默认位置。 */
+export declare function specRelOf(intake: IntakeSubOptions): string;
+/** 进度一句话：必答项已答数 + 未答 + 格式待修正。 */
+export declare function progressLine(state: IntakeState): string;
+/**
+ * 执行一次 `thesis_intake` 调用（纯 I/O，零 cordis 依赖）。
+ *
+ * @param sessionAsked 本次会话已经问过的问题数（由调用方累加，用于 `maxQuestions` 上限）。
+ */
+export declare function runIntake(fs: FileSystemLike, intake: IntakeSubOptions, args: IntakeArgs, cwd: string | undefined, signal?: AbortSignal, sessionAsked?: number): Promise<string>;
+/** 供其它模块/测试复用：一次裁剪后的待问队列（受 maxQuestions 限制）。 */
+export declare function pendingQueue(state: IntakeState, ctx: IntakeContext, maxQuestions: number): IntakeQuestion[];
+/**
+ * 注册 `thesis_intake`（单个工具、7 个 action）。
+ *
+ * 工具定义走仓库统一的 `definePaperTool`（生产 = 宿主真实 `defineTool`，
+ * 离线 = `shared/define-tool.ts` 的等价实现），因此本模块在测试环境里可加载。
+ * 工作区根由 `findThesisRoot` 从会话 cwd 向上探测 `00-管理/进度台账.md`；
+ * 找不到时工具返回明确指引（先 `thesis_init`），不抛裸异常。
+ */
+export declare function registerIntake(ctx: Context, options: {
+    intake: IntakeSubOptions;
+}): void;
+/** 命令执行上下文的最小面（宿主 `CommandInvocation` 在结构上满足它）。 */
+export interface IntakeExecLike {
+    readonly signal?: AbortSignal;
+    readonly agent?: {
+        readonly session: {
+            readonly header: {
+                readonly cwd?: string;
+            };
+        };
+    };
+}
+/** 命令返回值（宿主 `CommandResult` 的形状）。 */
+export interface IntakeCommandResult {
+    readonly kind: 'success' | 'error';
+    readonly text?: string;
+}
+/** 把 `/thesis-intake` 的一行输入翻译成追问动作。 */
+export declare function parseCommandInput(raw: string): IntakeArgs;
+/**
+ * 注册命令 `/thesis-intake`（命令名只允许 `[a-z][a-z0-9_-]*`）。
+ *
+ * 用法：`/thesis-intake` 取下一个问题；`/thesis-intake status|spec|done|start`；
+ * `/thesis-intake answer school.name XX大学`；`/thesis-intake skip ref.samples 暂时没有`。
+ * `ctx.commands` 不可用（未装配命令服务的宿主）时静默跳过，不影响工具能力。
+ */
+export declare function registerIntakeCommand(ctx: Context, options: {
+    intake: IntakeSubOptions;
+}): boolean;