@kirkchinese/dsh-citeciter 0.6.0 → 0.8.0

package/lib/{update-C0K5ekMg.js → update-0LcFDvI5.js}

@@ -1,4 +1,62 @@
 import { z } from "zod";
+//#region lib/types/native-session-contract.js
+const attachmentId = z.string().min(1).transform((value) => value);
+const nativeImageSchema = z.object({
+	attachmentId,
+	mediaType: z.enum([
+		"image/png",
+		"image/jpeg",
+		"image/webp",
+		"image/gif"
+	]),
+	bytes: z.number().int().nonnegative(),
+	width: z.number().int().positive(),
+	height: z.number().int().positive(),
+	name: z.string().optional(),
+	originalDimensions: z.object({
+		width: z.number().int().positive(),
+		height: z.number().int().positive()
+	}).strict().optional()
+}).strict().transform(({ name, originalDimensions, ...image }) => ({
+	...image,
+	...name === void 0 ? {} : { name },
+	...originalDimensions === void 0 ? {} : { originalDimensions }
+}));
+const file = z.object({
+	attachmentId,
+	name: z.string(),
+	bytes: z.number().int().nonnegative()
+}).strict();
+/** Wire reference for an authorized attachment; generic files have no image metadata. */
+const nativeAttachmentRefSchema = z.union([nativeImageSchema, file]);
+const nativeAttachmentSchema = z.discriminatedUnion("type", [z.object({
+	type: z.literal("image"),
+	attachment: nativeImageSchema
+}).strict(), z.object({
+	type: z.literal("file"),
+	attachment: file
+}).strict()]);
+/** Read-only control projection. The Agent inbox remains the only authoritative queue. */
+const nativeStateSchema = z.object({
+	running: z.boolean(),
+	blank: z.boolean(),
+	error: z.string().nullable(),
+	queue: z.array(z.object({
+		id: z.string().min(1),
+		placement: z.enum([
+			"queued",
+			"steering",
+			"context"
+		]),
+		rpcId: z.string().optional(),
+		text: z.string(),
+		attachments: z.array(nativeAttachmentSchema)
+	}).strict()),
+	receipts: z.array(z.object({
+		requestId: z.string().min(1),
+		attachments: z.array(nativeAttachmentSchema)
+	}).strict())
+}).strict();
 /** Maximum combined UTF-8 element-content bytes retained on one board. */
 const BOARD_MAX_CONTENT_BYTES = 5e5;
 /** Element kinds the blackboard renders safely on the chalk canvas. */
@@ -253,6 +311,134 @@ Object.freeze({
 	elements: [],
 	invalid: 0
 });
+//#endregion
+//#region lib/types/learning.js
+/** User-selected teaching stages; these indicate intent, never measured mastery. */
+const LEARNING_STAGES = [
+	{
+		id: "logic",
+		label: "底层逻辑",
+		shortLabel: "逻辑",
+		hint: "从定义、成立条件和因果机制讲起。",
+		instruction: "请讲清当前主题的底层逻辑：先给出定义和成立条件，再解释因果机制与为什么成立。区分来源证据、一般知识和假设。只讲这一阶段，不自动推进。"
+	},
+	{
+		id: "qualitative",
+		label: "定性分析",
+		shortLabel: "定性",
+		hint: "看方向、边界，以及改变条件会发生什么。",
+		instruction: "请对当前主题做定性分析：解释变量或因素之间的关系、变化方向、边界与反例，用一个具体情境说明。只讲这一阶段，不自动推进。"
+	},
+	{
+		id: "quantitative",
+		label: "定量分析（板书）",
+		shortLabel: "定量",
+		hint: "把变量、推导和算例写到板书上。",
+		instruction: "请对当前主题做定量分析，并调用 blackboard_apply 整理板书：注明变量、单位、假设、推导步骤与一个可核查算例。示例数值必须标明是假设，不得伪造来源数据。如果此主题不适合定量或信息不足，请明确说明原因。只讲这一阶段，不自动推进。"
+	},
+	{
+		id: "connections",
+		label: "概念关联",
+		shortLabel: "关联",
+		hint: "说明它与哪些概念相连，以及为什么。",
+		instruction: "请围绕当前主题给出 2–4 个最有帮助的概念关联，逐一解释是前提、推论、类比还是对比，说明关联理由与类比的边界。需要时用板书画关系。只讲这一阶段，不自动推进。"
+	},
+	{
+		id: "summary",
+		label: "总结学习卡片",
+		shortLabel: "总结",
+		hint: "先核对与纠错，再整理成学习卡片。",
+		instruction: "请先核对本 Topic 的结论与已有板书：检查定义、成立条件、推导、数值和前后矛盾，不要把此前的模型回答当作证据；必要时读取可用来源。纠正发现的错误，将无法核实的内容明确标为“未核实”或省略，不要补造来源与定位。然后调用 learning_cards 生成 1–6 张学习卡片，每张包含核心结论、一个具体例子、可选自测问题和参考答案；逐项检查这些字段的一致性，纠错必须同步到例子和参考答案。涉及来源事实时保留真实可用的定位，区分来源证据与一般知识。完成后简短说明纠正了什么、还有哪些内容未核实；不安排复习计划。"
+	}
+];
+/** Make the entire stage instruction visible and durable as an ordinary Topic user message. */
+function learningQuestion(stageId, question = "") {
+	const stage = LEARNING_STAGES.find((candidate) => candidate.id === stageId);
+	return `【学习阶段：${stage.label}】\n${stage.instruction}${question.trim() === "" ? "" : `\n\n我的问题：${question.trim()}`}`;
+}
+const learningCardSchema = z.object({
+	title: z.string().trim().min(1).max(100),
+	summary: z.string().trim().min(1).max(2e3),
+	example: z.string().trim().min(1).max(1500),
+	question: z.string().trim().min(1).max(500),
+	answer: z.string().trim().min(1).max(2e3)
+}).strict();
+const learningCardsInputSchema = z.object({ cards: z.array(learningCardSchema).min(1).max(8) }).strict();
+/** Shared teaching contract appended to every scenario's logged tutor section. */
+const LEARNING_PROMPT = `The optional learning route is 底层逻辑 → 定性分析 → 定量分析（板书） → 概念关联 → 总结学习卡片. A user may select or skip any stage. Respond to the current request only; never advance automatically or claim that a stage proves mastery. Never schedule spaced repetition or reminders. Do not require quizzes before continuing.
+
+Use learning_cards only when the user asks to summarize or revise learning cards. Before composing cards in this same turn, check the Topic's conclusions and existing board for incorrect definitions, missing conditions, faulty derivations or arithmetic, and contradictions. Earlier assistant output is not evidence. Read available sources when needed; distinguish source evidence from general knowledge. Correct errors before saving, and explicitly label unresolved claims as 未核实 (unverified) or omit them. Check every card's summary, example, question and reference answer for consistency: a correction in the summary must also reach its example and answer. Briefly report corrections and unresolved points; do not present this self-check as independent verification.
+
+Each successful learning_cards call replaces the visible card set for this Topic; older sets remain in its log. Send the complete desired set in one call, not separate calls for individual cards. Write concise, source-grounded summaries and examples, plus a question and reference answer for optional self-testing. Preserve real available source locators inside summaries; do not invent offsets, sources or evidence. Cards and blackboard tools only record learning material inside this independent Topic; they never write to the workspace or source Session.`;
+//#endregion
+//#region lib/types/actions.js
+/** One persisted wheel slot; its prompt is sent as a durable user message. */
+const citeActionSchema = z.object({
+	label: z.string().trim().min(1).max(20),
+	prompt: z.string().max(4e3),
+	ask: z.boolean(),
+	scenario: z.enum(["qa", "present"]),
+	presentation: z.enum(["side", "floating"])
+}).strict().refine((action) => action.ask || action.prompt.trim() !== "", "直接执行的模式需要提示词");
+const wheelSlotsSchema = z.array(citeActionSchema.nullable()).length(8);
+const wheelTriggerSchema = z.enum([
+	"right-button",
+	"Alt",
+	"Control",
+	"Shift",
+	"Meta"
+]);
+const actionModelSchema = z.object({
+	provider: z.string().min(1).max(200),
+	model: z.string().min(1).max(200)
+}).strict();
+/** Clockwise from twelve o'clock. Empty slots retain their positions. */
+const DEFAULT_WHEEL_SLOTS = [
+	{
+		label: "自由提问",
+		prompt: "",
+		ask: true,
+		scenario: "qa",
+		presentation: "side"
+	},
+	{
+		label: "解释这段",
+		prompt: learningQuestion("logic"),
+		ask: false,
+		scenario: "present",
+		presentation: "side"
+	},
+	{
+		label: "找错误",
+		prompt: "请审查引用内容的错误、遗漏和成立条件。区分可确认的错误与需要补充的信息。",
+		ask: false,
+		scenario: "qa",
+		presentation: "floating"
+	},
+	{
+		label: "翻译",
+		prompt: "请将引用内容翻译为中文，保留重要术语的原文。",
+		ask: false,
+		scenario: "qa",
+		presentation: "floating"
+	},
+	{
+		label: "定量板书",
+		prompt: learningQuestion("quantitative"),
+		ask: false,
+		scenario: "present",
+		presentation: "side"
+	},
+	{
+		label: "总结卡片",
+		prompt: learningQuestion("summary", "围绕本次引用的内容整理。"),
+		ask: false,
+		scenario: "present",
+		presentation: "side"
+	},
+	null,
+	null
+];
 /** Host settings namespace mirrored by the browser settings scope. */
 const CITECITER_SETTINGS_NAMESPACE = "citeciter";
 /** Topic-scoped system prompt section. */
@@ -289,7 +475,17 @@ const citeCiterSettingsSchema = z.object({
 	promptTemplates: z.array(promptTemplateSchema).max(8).optional(),
 	shortcutOpenPanel: z.string().max(40).optional(),
 	boardAnimations: z.boolean().optional(),
-	updateNotifications: z.boolean().optional()
+	activeRecall: z.boolean().optional(),
+	updateNotifications: z.boolean().optional(),
+	wheelSlots: wheelSlotsSchema.optional(),
+	wheelTrigger: wheelTriggerSchema.optional(),
+	defaultCiterModel: actionModelSchema.nullable().optional(),
+	defaultPermission: z.enum([
+		"read-only",
+		"workspace-write",
+		"danger-full-access"
+	]).optional(),
+	learningRoute: z.boolean().optional()
 }).strict();
 /** Settings used before an optional DSH settings provider becomes available. */
 const DEFAULT_CITECITER_SETTINGS = Object.freeze({
@@ -300,6 +496,9 @@ const DEFAULT_CITECITER_SETTINGS = Object.freeze({
 	reopenLastTopic: true,
 	followupQuestions: true,
 	boardAnimations: true,
+	activeRecall: false,
+	defaultPermission: "read-only",
+	learningRoute: false,
 	updateNotifications: true,
 	promptTemplates: [
 		{
@@ -449,6 +648,8 @@ const modelConfigSchema = z.object({
 }).strict();
 /** Fields shared by the canonical Topic metadata schema and its on-disk reader. */
 const topicMetadataFields = {
+	hosted: z.boolean().optional(),
+	storage: z.literal("source").optional(),
 	topicId: z.number().int().positive(),
 	createRequestId: z.string().min(1).optional(),
 	sessionId: z.string().min(1),
@@ -511,7 +712,15 @@ function parseTopicMetadataFile(raw) {
 		documentId: documentId ?? null
 	});
 }
+const permissionSchema = z.enum([
+	"read-only",
+	"workspace-write",
+	"danger-full-access"
+]);
 const topicSummarySchema = z.object({
+	permission: permissionSchema.optional(),
+	hosted: z.boolean().optional(),
+	storage: z.literal("source").optional(),
 	topicId: z.number().int().positive(),
 	sessionId: z.string().min(1),
 	sourceSessionId: z.string().min(1),
@@ -529,6 +738,11 @@ const topicSummarySchema = z.object({
 	observedThroughSeq: z.number().int().nonnegative().nullable(),
 	modelConfig: modelConfigSchema
 }).strict();
+const messageAttachmentSchema = z.object({
+	kind: z.enum(["image", "file"]),
+	id: z.string().min(1),
+	name: z.string()
+}).strict();
 const topicMessageIdentitySchema = {
 	id: z.string().min(1),
 	seq: z.number().int().nonnegative()
@@ -537,11 +751,13 @@ const topicMessageSchema = z.discriminatedUnion("role", [
 	z.object({
 		...topicMessageIdentitySchema,
 		role: z.literal("user"),
+		attachments: z.array(messageAttachmentSchema).optional(),
 		text: z.string()
 	}).strict(),
 	z.object({
 		...topicMessageIdentitySchema,
 		role: z.literal("assistant"),
+		renderKey: z.string().optional(),
 		text: z.string(),
 		reasoning: z.string().nullable(),
 		streaming: z.boolean()
@@ -555,6 +771,7 @@ const topicMessageSchema = z.discriminatedUnion("role", [
 	z.object({
 		...topicMessageIdentitySchema,
 		role: z.literal("tool"),
+		attachments: z.array(messageAttachmentSchema).optional(),
 		name: z.string().min(1),
 		arguments: z.string(),
 		result: z.string().nullable(),
@@ -591,6 +808,8 @@ const pendingQuestionSchema = z.object({
 	questions: z.array(questionItemSchema).min(1)
 }).strict();
 const topicSnapshotSchema = z.object({
+	captureId: z.string().optional(),
+	documentTitle: z.string().optional(),
 	topic: topicSummarySchema,
 	messages: z.array(topicMessageSchema),
 	pendingQuestion: pendingQuestionSchema.nullable(),
@@ -611,6 +830,7 @@ const providerOptionSchema = z.object({
 	name: z.string().min(1),
 	models: z.array(modelOptionSchema)
 }).strict();
+const draftQuestionSchema = z.string().trim().max(12e3);
 const questionSchema = z.string().trim().min(1).max(12e3);
 const topicSessionIdSchema = z.string().min(1);
 const createModeSchema = z.enum([
@@ -653,46 +873,53 @@ const documentContentSchema = z.object({
 	title: z.string().trim().min(1).max(200),
 	format: documentFormatSchema,
 	content: z.string(),
-	truncated: z.boolean()
+	truncated: z.boolean(),
+	page: z.number().int().nonnegative().default(0),
+	pageCount: z.number().int().positive().default(1)
 }).strict();
 const createRequestSchema = z.union([
 	z.object({
 		action: z.literal("create"),
+		modelRoute: actionModelSchema.optional(),
 		requestId: z.string().min(1),
 		sourceSessionId: z.string().min(1),
-		question: questionSchema,
+		question: draftQuestionSchema,
 		mode: z.literal("observer"),
 		scenario: z.enum(["qa", "present"]).optional()
 	}).strict(),
 	z.object({
 		action: z.literal("create"),
+		modelRoute: actionModelSchema.optional(),
 		requestId: z.string().min(1),
 		citation: citationDraftSchema,
-		question: questionSchema,
+		question: draftQuestionSchema,
 		mode: createModeSchema,
 		scenario: topicScenarioSchema.optional()
 	}).strict(),
 	z.object({
 		action: z.literal("create"),
+		modelRoute: actionModelSchema.optional(),
 		requestId: z.string().min(1),
 		selectionClaim: citationSelectionClaimSchema,
-		question: questionSchema,
+		question: draftQuestionSchema,
 		mode: createModeSchema,
 		scenario: topicScenarioSchema.optional()
 	}).strict(),
 	z.object({
 		action: z.literal("create"),
+		modelRoute: actionModelSchema.optional(),
 		requestId: z.string().min(1),
 		toolClaim: toolEvidenceClaimSchema,
-		question: questionSchema,
+		question: draftQuestionSchema,
 		mode: createModeSchema,
 		scenario: topicScenarioSchema.optional()
 	}).strict(),
 	z.object({
 		action: z.literal("create"),
+		modelRoute: actionModelSchema.optional(),
 		requestId: z.string().min(1),
 		documentClaim: documentEvidenceClaimSchema,
-		question: questionSchema,
+		question: draftQuestionSchema,
 		mode: createModeSchema,
 		scenario: topicScenarioSchema.optional()
 	}).strict()
@@ -704,10 +931,27 @@ const citeCiterRequestSchema = z.union([createRequestSchema, z.discriminatedUnio
 		sourceSessionId: z.string().min(1),
 		includeArchived: z.boolean().optional()
 	}).strict(),
+	z.object({
+		action: z.literal("board-capture"),
+		topicSessionId: topicSessionIdSchema,
+		id: z.string().min(1),
+		png: z.string().max(8e6).regex(/^[A-Za-z0-9+/]+={0,2}$/).optional(),
+		error: z.string().max(500).optional()
+	}).strict(),
 	z.object({
 		action: z.literal("get"),
 		topicSessionId: topicSessionIdSchema
 	}).strict(),
+	z.object({
+		action: z.literal("native-state"),
+		topicSessionId: topicSessionIdSchema,
+		requestIds: z.array(z.string().min(1).max(100)).max(32)
+	}).strict(),
+	z.object({
+		action: z.literal("native-attachment"),
+		topicSessionId: topicSessionIdSchema,
+		attachmentId: z.string().min(1).max(200)
+	}).strict(),
 	z.object({
 		action: z.literal("ask"),
 		requestId: z.string().min(1).optional(),
@@ -745,6 +989,11 @@ const citeCiterRequestSchema = z.union([createRequestSchema, z.discriminatedUnio
 		confirmSessionId: topicSessionIdSchema
 	}).strict(),
 	z.object({ action: z.literal("models") }).strict(),
+	z.object({
+		action: z.literal("set-permission"),
+		topicSessionId: topicSessionIdSchema,
+		mode: permissionSchema
+	}).strict(),
 	z.object({
 		action: z.literal("set-model-route"),
 		topicSessionId: topicSessionIdSchema,
@@ -773,11 +1022,21 @@ const citeCiterRequestSchema = z.union([createRequestSchema, z.discriminatedUnio
 	z.object({ action: z.literal("documents") }).strict(),
 	z.object({
 		action: z.literal("document-get"),
-		documentId: z.string().min(1)
+		documentId: z.string().min(1),
+		page: z.number().int().nonnegative().optional()
 	}).strict()
 ])]);
 /** Strict response union returned by the single Remote command endpoint. */
 const citeCiterResponseSchema = z.discriminatedUnion("kind", [
+	z.object({
+		kind: z.literal("native-state"),
+		state: nativeStateSchema
+	}).strict(),
+	z.object({
+		kind: z.literal("native-attachment"),
+		attachment: nativeAttachmentRefSchema,
+		data: z.string().regex(/^[A-Za-z0-9+/]*={0,2}$/)
+	}).strict(),
 	z.object({
 		kind: z.literal("topic"),
 		topic: topicSnapshotSchema
@@ -850,6 +1109,13 @@ function stableVersionParts(version) {
 	];
 }
 const stableVersionSchema = z.string().refine((version) => stableVersionParts(version) !== null, "expected a stable MAJOR.MINOR.PATCH version with safe integer components");
+/** Installed development builds may use a valid SemVer prerelease suffix; registry latest stays stable. */
+const installedVersionSchema = z.string().refine((version) => {
+	const [core, ...suffix] = version.split("-");
+	if (core === void 0 || stableVersionParts(core) === null) return false;
+	if (suffix.length === 0) return true;
+	return suffix.join("-").split(".").every((part) => /^[0-9A-Za-z-]+$/u.test(part) && (!/^\d+$/u.test(part) || part === "0" || !part.startsWith("0")));
+}, "expected a stable version or a valid prerelease");
 /** Stable failure identifiers consumed by the Web settings and notification UI. */
 const updateCheckErrorCodeSchema = z.enum([
 	"installed-version-invalid",
@@ -863,7 +1129,7 @@ const updateCheckErrorCodeSchema = z.enum([
 /** Strict result of one read-only npm `latest` check. */
 const updateCheckResponseSchema = z.discriminatedUnion("kind", [z.object({
 	kind: z.literal("success"),
-	installedVersion: stableVersionSchema,
+	installedVersion: installedVersionSchema,
 	latestVersion: stableVersionSchema,
 	updateAvailable: z.boolean(),
 	checkedAt: z.number().int().nonnegative(),
@@ -982,7 +1248,7 @@ var UpdateChecker = class {
 				checkedAt: this.now()
 			};
 		}
-		if (stableVersionParts(installedVersion) === null) return {
+		if (!installedVersionSchema.safeParse(installedVersion).success) return {
 			kind: "error",
 			code: "installed-version-invalid",
 			checkedAt: this.now()
@@ -1021,7 +1287,7 @@ var UpdateChecker = class {
 				code: "registry-response-invalid",
 				checkedAt: this.now()
 			};
-			const comparison = compareStableVersions(installedVersion, latest.data.version);
+			const comparison = compareStableVersions(installedVersion.split("-")[0], latest.data.version);
 			if (comparison === null) return {
 				kind: "error",
 				code: "registry-version-invalid",
@@ -1032,7 +1298,7 @@ var UpdateChecker = class {
 				kind: "success",
 				installedVersion,
 				latestVersion: latest.data.version,
-				updateAvailable: comparison < 0,
+				updateAvailable: comparison < 0 || comparison === 0 && installedVersion.includes("-"),
 				checkedAt
 			};
 			this.cached = {
@@ -1070,4 +1336,4 @@ function waitForCaller(operation, signal) {
 	});
 }
 //#endregion
-export { topicSummarySchema as C, boardBatchSchema as E, topicSnapshotSchema as S, applyBoardOps as T, documentSummarySchema as _, CITECITER_SETTINGS_NAMESPACE as a, toolEvidenceClaimSchema as b, canonicalCitationIdentity as c, citationSelectionClaimSchema as d, citeCiterRequestSchema as f, documentEvidenceClaimSchema as g, documentContentSchema as h, CITATION_CONTEXT_NAME as i, citationDraftSchema as l, citeCiterSettingsSchema as m, updateCheckErrorCodeSchema as n, DEFAULT_CITECITER_SETTINGS as o, citeCiterResponseSchema as p, updateCheckResponseSchema as r, TUTOR_SECTION_NAME as s, UpdateChecker as t, citationRecordSchema as u, parseTopicMetadataFile as v, EMPTY_BOARD_STATE as w, topicMetadataSchema as x, renderCitationContext as y };
+export { topicSummarySchema as C, EMPTY_BOARD_STATE as D, learningCardsInputSchema as E, applyBoardOps as O, topicSnapshotSchema as S, LEARNING_PROMPT as T, documentSummarySchema as _, CITECITER_SETTINGS_NAMESPACE as a, toolEvidenceClaimSchema as b, canonicalCitationIdentity as c, citationSelectionClaimSchema as d, citeCiterRequestSchema as f, documentEvidenceClaimSchema as g, documentContentSchema as h, CITATION_CONTEXT_NAME as i, boardBatchSchema as k, citationDraftSchema as l, citeCiterSettingsSchema as m, updateCheckErrorCodeSchema as n, DEFAULT_CITECITER_SETTINGS as o, citeCiterResponseSchema as p, updateCheckResponseSchema as r, TUTOR_SECTION_NAME as s, UpdateChecker as t, citationRecordSchema as u, parseTopicMetadataFile as v, DEFAULT_WHEEL_SLOTS as w, topicMetadataSchema as x, renderCitationContext as y };