@lingxiao-office/sdk 1.0.0

package/dist/core/blackboard/schemas.js

@@ -0,0 +1,102 @@
+/**
+ * 黑板图摄入 zod schema — 以 types.ts 的 enum 为单一事实源。
+ *
+ * 消灭 WorkerOutputParser 旧实现的 `Record<string,unknown>` + `String()` 强转 +
+ * `as Confidence` 断言。所有 LLM 输出经 safeParse 校验,非法 confidence/evidence/edgeType
+ * 进 errors 不进图。
+ *
+ * 这里导出的 ConfidenceSchema / EdgeTypeSchema / EvidenceItemSchema 也是 LLM 工具
+ * (WriteFactTool/AddEdgeTool/SupersedeNodeTool)的单一事实源,根除工具与 types.ts 的 enum 漂移。
+ *
+ * 容错策略(对齐旧行为):
+ *  - confidence/priority 有合理默认 → 用 .catch 降级,保住主信息(title/content)。
+ *  - title/content/surface/from/to/old_node_id 这类无默认的关键字段 → required,失败整块拒绝。
+ *  - evidence 数组元素经 EvidenceItemSchema 校验(ref 必需);非法元素被过滤而非整块拒绝。
+ */
+import { z } from 'zod';
+// ── 枚举(单一事实源,对齐 types.ts) ───────────────────────────────
+export const ConfidenceSchema = z.enum(['confirmed', 'likely', 'tentative']);
+export const EdgeTypeSchema = z.enum([
+    'depends_on', 'supports', 'contradicts', 'refines', 'supersedes', 'produces', 'consumes',
+]);
+/** EvidenceItem.type 的 9 种(types.ts:65)。工具与 parser 共用,杜绝漂移。 */
+export const EvidenceTypeSchema = z.enum([
+    'file', 'test_result', 'log_output', 'url', 'observation',
+    'artifact', 'tool_result', 'task_result', 'blackboard_node',
+]);
+export const EvidenceItemSchema = z.object({
+    type: EvidenceTypeSchema,
+    ref: z.string(),
+    location: z.string().optional(),
+    snippet: z.string().optional(),
+});
+/**
+ * 证据列表:lenient。逐元素 safeParse,**过滤掉非法元素**(如 type 不在 9 种、缺 ref),
+ * 保留合法元素,不因单条坏 evidence 整块拒绝(保住 title/content 主信息)。
+ * 非数组/全非法 → 降级为 undefined(等同未提供 evidence)。
+ */
+const EvidenceListSchema = z
+    .array(z.unknown())
+    .transform((items) => items.flatMap((item) => {
+    const r = EvidenceItemSchema.safeParse(item);
+    return r.success ? [r.data] : [];
+}))
+    .optional()
+    .catch(undefined);
+const TagsSchema = z.array(z.string()).catch([]);
+/** 边 metadata:lenient。非 Record<string,string> → 降级为 undefined(丢弃 metadata,保住 from/to/type)。 */
+const EdgeMetadataSchema = z.record(z.string(), z.string()).optional().catch(undefined);
+// ── 6 种 graph_* 代码块的 raw schema(LLM 字段名) ──────────────────
+export const GraphFactBlockSchema = z.object({
+    title: z.string().min(1),
+    content: z.string().min(1),
+    tags: TagsSchema,
+    confidence: ConfidenceSchema.catch('confirmed'),
+    evidence: EvidenceListSchema,
+});
+export const GraphIntentBlockSchema = z.object({
+    title: z.string().min(1),
+    content: z.string().min(1),
+    tags: TagsSchema,
+    priority: z.number().int().min(1).max(10).catch(5),
+});
+/**
+ * 契约结构化允许面(LLM 输入边界,snake_case 键)。
+ * safeParse 失败时 .catch 降级为空,保住 title/content 主信息——
+ * 非法 allowed_scope 不整块拒绝契约(对齐 confidence/evidence 的容错策略)。
+ * 内部存储为 camelCase 的 ContractAllowedScope(types.ts GraphNode.contractAllowedScope)。
+ *
+ * `.optional()` 是向后兼容的关键:旧契约块无此字段仍能 parse 通过。
+ */
+const ContractAllowedScopeSchema = z.object({
+    allow: z.array(z.string().min(1)).catch([]).default([]),
+    forbid: z.array(z.string().min(1)).catch([]).optional(),
+    allow_create: z.boolean().catch(false).optional(),
+}).optional();
+export const GraphContractBlockSchema = z.object({
+    title: z.string().min(1),
+    content: z.string().min(1),
+    tags: TagsSchema,
+    surface: z.string().min(1),
+    version: z.union([z.number(), z.string()]).optional(),
+    allowed_scope: ContractAllowedScopeSchema,
+    confidence: ConfidenceSchema.catch('confirmed'),
+    evidence: EvidenceListSchema,
+});
+export const GraphDesignDocBlockSchema = z.object({
+    title: z.string().min(1),
+    content: z.string().min(1),
+    tags: TagsSchema,
+    confidence: ConfidenceSchema.catch('confirmed'),
+    evidence: EvidenceListSchema,
+});
+export const GraphEdgeBlockSchema = z.object({
+    from: z.string().min(1),
+    to: z.string().min(1),
+    type: EdgeTypeSchema,
+    metadata: EdgeMetadataSchema,
+});
+export const GraphSupersedeBlockSchema = z.object({
+    old_node_id: z.string().min(1),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/core/blackboard/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../../src/core/blackboard/schemas.ts"],"names":[],"mappings":"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"}

package/dist/core/blackboard/types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Blackboard Graph — 核心类型定义
+ *
+ * 节点类型：
+ *   Fact   — 已确认事实，不可变
+ *   Intent — 待探索方向，可被认领/放弃
+ *   Hint   — 人类注入的经验提示
+ *   Origin — 起点（特殊 Fact，会话开始时设一次）
+ *   Goal   — 终点（特殊 Fact，由用户或 Dispatcher 设定）
+ *   Contract — 跨 Agent 接口/数据/验收契约
+ *   DesignDoc — 跨 Agent 设计文档/方案约定
+ */
+import type { ContractAllowedScope } from '../ContractAllowedScope.js';
+export type NodeKind = 'fact' | 'intent' | 'hint' | 'origin' | 'goal' | 'contract' | 'design_doc' | 'review' | 'verdict' | 'decision_log';
+/**
+ * 跨 tag 全局广播的节点类型集合。
+ *
+ * 默认 broadcastBlackboardDelta 会按 agent.tags 过滤增量推送，避免噪音；
+ * 但 contract / design_doc / goal / task_result 这种"跨栈协作必看"的节点必须无视 tag 过滤
+ * 直接广播给所有在跑的 worker。
+ *
+ * AgentPool.broadcastBlackboardDelta 与 contract_node.test.ts 共享此集合，
+ * 用 export 而非 AgentPool 内部常量，避免测试反向依赖 AgentPool。
+ */
+export declare const GLOBAL_BROADCAST_NODE_KINDS: ReadonlySet<NodeKind>;
+export declare function isGlobalBroadcastNode(node: Pick<GraphNode, 'kind' | 'tags'>): boolean;
+export type Confidence = 'confirmed' | 'likely' | 'tentative';
+export type IntentStatus = 'open' | 'claimed' | 'resolved';
+export interface GraphNode {
+    id: string;
+    kind: NodeKind;
+    sessionId: string;
+    title: string;
+    content: string;
+    tags: string[];
+    createdBy: string;
+    createdAt: number;
+    supersededBy?: string;
+    confidence?: Confidence;
+    intentStatus?: IntentStatus;
+    priority?: number;
+    evidence?: EvidenceItem[];
+    /** 契约结构化允许面(仅 kind==='contract' 节点使用)。undefined=未声明→维持现状。 */
+    contractAllowedScope?: ContractAllowedScope;
+    intentFrom?: string[];
+    intentTo?: string;
+}
+export interface EvidenceItem {
+    type: 'file' | 'test_result' | 'log_output' | 'url' | 'observation' | 'artifact' | 'tool_result' | 'task_result' | 'blackboard_node';
+    ref: string;
+    location?: string;
+    snippet?: string;
+}
+export type EdgeType = 'depends_on' | 'supports' | 'contradicts' | 'refines' | 'supersedes' | 'produces' | 'consumes';
+export interface GraphEdge {
+    id: string;
+    sessionId: string;
+    fromNodeId: string;
+    toNodeId: string;
+    edgeType: EdgeType;
+    createdAt: number;
+    createdBy: string;
+    metadata?: Record<string, string>;
+}
+export interface GraphSnapshot {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    focusNodeId?: string;
+    originNode?: GraphNode;
+    goalNode?: GraphNode;
+}
+export interface WorkerGraphOutput {
+    newFacts: Omit<GraphNode, 'id' | 'kind' | 'createdAt'>[];
+    newIntents: Omit<GraphNode, 'id' | 'kind' | 'createdAt'>[];
+    newContracts?: Omit<GraphNode, 'id' | 'kind' | 'createdAt'>[];
+    newDesignDocs?: Omit<GraphNode, 'id' | 'kind' | 'createdAt'>[];
+    newEdges: Omit<GraphEdge, 'id' | 'createdAt'>[];
+    supersededNodeIds: string[];
+    completionSummary: string;
+}
+export type TaskInstruction = 'bootstrap' | 'reason' | 'explore';
+export interface DispatchDecision {
+    intentNodeId: string;
+    instruction: TaskInstruction;
+    graphSnapshot: GraphSnapshot;
+    suggestedTools?: string[];
+    priority: number;
+}
+export interface GraphAnalysis {
+    openIntents: GraphNode[];
+    unresolvedContradictions: Array<{
+        nodeA: GraphNode;
+        nodeB: GraphNode;
+    }>;
+    knowledgeGaps: string[];
+    blockedIntents: GraphNode[];
+    recentFacts: GraphNode[];
+    completionSignals: string[];
+}
+export interface BlackboardEvent {
+    type: 'node_added' | 'node_superseded' | 'edge_added' | 'intent_resolved' | 'contradiction_detected';
+    sessionId: string;
+    nodeId?: string;
+    edgeId?: string;
+    taskId?: string;
+    timestamp: number;
+}
+export interface BlackboardDelta {
+    eventType: BlackboardEvent['type'];
+    changedNodes: GraphNode[];
+    changedEdges: GraphEdge[];
+    humanSummary: string;
+    relatedTags: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/blackboard/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/blackboard/types.ts"],"names":[],"mappings":"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"}

package/dist/core/blackboard/types.js

@@ -0,0 +1,31 @@
+/**
+ * Blackboard Graph — 核心类型定义
+ *
+ * 节点类型：
+ *   Fact   — 已确认事实，不可变
+ *   Intent — 待探索方向，可被认领/放弃
+ *   Hint   — 人类注入的经验提示
+ *   Origin — 起点（特殊 Fact，会话开始时设一次）
+ *   Goal   — 终点（特殊 Fact，由用户或 Dispatcher 设定）
+ *   Contract — 跨 Agent 接口/数据/验收契约
+ *   DesignDoc — 跨 Agent 设计文档/方案约定
+ */
+/**
+ * 跨 tag 全局广播的节点类型集合。
+ *
+ * 默认 broadcastBlackboardDelta 会按 agent.tags 过滤增量推送，避免噪音；
+ * 但 contract / design_doc / goal / task_result 这种"跨栈协作必看"的节点必须无视 tag 过滤
+ * 直接广播给所有在跑的 worker。
+ *
+ * AgentPool.broadcastBlackboardDelta 与 contract_node.test.ts 共享此集合，
+ * 用 export 而非 AgentPool 内部常量，避免测试反向依赖 AgentPool。
+ */
+export const GLOBAL_BROADCAST_NODE_KINDS = new Set([
+    'contract',
+    'design_doc',
+    'goal',
+]);
+export function isGlobalBroadcastNode(node) {
+    return GLOBAL_BROADCAST_NODE_KINDS.has(node.kind) || node.tags?.includes('task_result');
+}
+//# sourceMappingURL=types.js.map

package/dist/core/blackboard/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/blackboard/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAA0B,IAAI,GAAG,CAAW;IAClF,UAAU;IACV,YAAY;IACZ,MAAM;CACP,CAAC,CAAC;AAEH,MAAM,UAAU,qBAAqB,CAAC,IAAsC;IAC1E,OAAO,2BAA2B,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;AAC1F,CAAC"}

package/dist/core/canvas/CanvasStore.d.ts

@@ -0,0 +1,64 @@
+/**
+ * CanvasStore —— 剑阁可交互 Canvas 的持久化层。
+ *
+ * 每份产物在 .lingxiao/canvas/<artifactId>/ 下持久化三类状态：
+ *   - sourcemap.json   CanvasSourceMap（nodeId ↔ spec/script 锚点）
+ *   - versions.json    CanvasVersion[]（版本栈）+ activeVersion 指针
+ *   - comments.json    CanvasComment[]（结构化批注）
+ *   - versions/<n>/    每个版本的产物快照（HTML/PNG/PPTX 等）
+ *
+ * artifactId 规范化：产物相对 workspace 路径 → 去掉非法字符的稳定 ID。
+ * 设计为纯磁盘 store，无数据库依赖；并发写用「读-改-写」+ 原子 rename。
+ */
+import type { CanvasSourceMap, CanvasVersion, CanvasComment, CanvasArtifactState, CanvasVersionStatus } from '../../contracts/types/Canvas.js';
+/** 把产物相对路径规范化成文件系统安全的 artifactId。 */
+export declare function toArtifactId(artifactPath: string): string;
+export interface CanvasStoreOptions {
+    /** 会话根目录（.lingxiao/sessions/<id>），canvas 状态挂在它下面。 */
+    sessionDir: string;
+    /** workspace 根，用于把绝对产物路径转相对。 */
+    workspace?: string;
+    /** 版本入栈后的回调（用于 emit canvas:version_pushed SSE 事件）。 */
+    onVersionPushed?: (artifactId: string, version: number) => void;
+}
+export declare class CanvasStore {
+    private readonly canvasRoot;
+    private readonly workspace?;
+    private readonly onVersionPushed?;
+    constructor(opts: CanvasStoreOptions);
+    /** 规范化产物路径：绝对路径转相对 workspace。 */
+    private normalizePath;
+    private dirFor;
+    private ensureDir;
+    /** 原子写 JSON：先写临时文件再 rename。 */
+    private writeJson;
+    private readJson;
+    saveSourceMap(map: CanvasSourceMap): string;
+    getSourceMap(artifactId: string): CanvasSourceMap | null;
+    private versionsPath;
+    private loadVersions;
+    /**
+     * 新版本入栈。把当前产物快照复制到 versions/<n>/，旧 active 版本标记 superseded，
+     * 返回新版本号。
+     */
+    pushVersion(input: {
+        artifactId: string;
+        artifactSnapshotPath?: string;
+        intent?: string;
+        changedFiles?: string[];
+    }): CanvasVersion;
+    listVersions(artifactId: string): CanvasVersion[];
+    getActiveVersion(artifactId: string): number;
+    /** 切换/回退到指定版本（不删除其它版本，只改 active 指针与状态）。 */
+    switchVersion(artifactId: string, target: number): boolean;
+    private commentsPath;
+    listComments(artifactId: string): CanvasComment[];
+    addComment(comment: CanvasComment): void;
+    updateCommentStatus(artifactId: string, commentId: string, status: CanvasCommentStatusLike): boolean;
+    getArtifactState(artifactId: string): CanvasArtifactState | null;
+    /** 列出所有已登记的产物 ID。 */
+    listArtifacts(): string[];
+}
+type CanvasCommentStatusLike = CanvasComment['status'];
+export type { CanvasVersionStatus };
+//# sourceMappingURL=CanvasStore.d.ts.map

package/dist/core/canvas/CanvasStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CanvasStore.d.ts","sourceRoot":"","sources":["../../../src/core/canvas/CanvasStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAYH,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,iCAAiC,CAAC;AAEzC,qCAAqC;AACrC,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAKzD;AAOD,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjE;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAgD;gBAErE,IAAI,EAAE,kBAAkB;IAMpC,iCAAiC;IACjC,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,SAAS;IAIjB,+BAA+B;IAC/B,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,QAAQ;IAWhB,aAAa,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM;IAW3C,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAMxD,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,YAAY;IAIpB;;;OAGG;IACH,WAAW,CAAC,KAAK,EAAE;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;KACzB,GAAG,aAAa;IAmCjB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,EAAE;IAIjD,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAI5C,2CAA2C;IAC3C,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAe1D,OAAO,CAAC,YAAY;IAIpB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,EAAE;IAIjD,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAMxC,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,uBAAuB,GAAG,OAAO;IAYpG,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI;IAYhE,qBAAqB;IACrB,aAAa,IAAI,MAAM,EAAE;CAO1B;AAED,KAAK,uBAAuB,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;AAQvD,YAAY,EAAE,mBAAmB,EAAE,CAAC"}

package/dist/core/canvas/CanvasStore.js

@@ -0,0 +1,193 @@
+/**
+ * CanvasStore —— 剑阁可交互 Canvas 的持久化层。
+ *
+ * 每份产物在 .lingxiao/canvas/<artifactId>/ 下持久化三类状态：
+ *   - sourcemap.json   CanvasSourceMap（nodeId ↔ spec/script 锚点）
+ *   - versions.json    CanvasVersion[]（版本栈）+ activeVersion 指针
+ *   - comments.json    CanvasComment[]（结构化批注）
+ *   - versions/<n>/    每个版本的产物快照（HTML/PNG/PPTX 等）
+ *
+ * artifactId 规范化：产物相对 workspace 路径 → 去掉非法字符的稳定 ID。
+ * 设计为纯磁盘 store，无数据库依赖；并发写用「读-改-写」+ 原子 rename。
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, readdirSync, cpSync, } from 'node:fs';
+import { join, dirname, isAbsolute, relative } from 'node:path';
+/** 把产物相对路径规范化成文件系统安全的 artifactId。 */
+export function toArtifactId(artifactPath) {
+    return artifactPath
+        .replace(/^[./]+/, '')
+        .replace(/[^a-zA-Z0-9._\-/]/g, '_')
+        .replace(/\//g, '__');
+}
+export class CanvasStore {
+    canvasRoot;
+    workspace;
+    onVersionPushed;
+    constructor(opts) {
+        this.canvasRoot = join(opts.sessionDir, 'canvas');
+        this.workspace = opts.workspace;
+        this.onVersionPushed = opts.onVersionPushed;
+    }
+    /** 规范化产物路径：绝对路径转相对 workspace。 */
+    normalizePath(artifactPath) {
+        if (this.workspace && isAbsolute(artifactPath)) {
+            return relative(this.workspace, artifactPath);
+        }
+        return artifactPath;
+    }
+    dirFor(artifactId) {
+        return join(this.canvasRoot, artifactId);
+    }
+    ensureDir(p) {
+        if (!existsSync(p))
+            mkdirSync(p, { recursive: true });
+    }
+    /** 原子写 JSON：先写临时文件再 rename。 */
+    writeJson(filePath, data) {
+        this.ensureDir(dirname(filePath));
+        const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+        writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf-8');
+        renameSync(tmp, filePath);
+    }
+    readJson(filePath) {
+        if (!existsSync(filePath))
+            return null;
+        try {
+            return JSON.parse(readFileSync(filePath, 'utf-8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    // ─── SourceMap ────────────────────────────────────────────────
+    saveSourceMap(map) {
+        const artifactId = map.artifactId || toArtifactId(this.normalizePath(map.artifactPath));
+        const normalized = {
+            ...map,
+            artifactId,
+            artifactPath: this.normalizePath(map.artifactPath),
+        };
+        this.writeJson(join(this.dirFor(artifactId), 'sourcemap.json'), normalized);
+        return artifactId;
+    }
+    getSourceMap(artifactId) {
+        return this.readJson(join(this.dirFor(artifactId), 'sourcemap.json'));
+    }
+    // ─── Versions（版本栈）────────────────────────────────────────
+    versionsPath(artifactId) {
+        return join(this.dirFor(artifactId), 'versions.json');
+    }
+    loadVersions(artifactId) {
+        return this.readJson(this.versionsPath(artifactId)) ?? { activeVersion: 0, versions: [] };
+    }
+    /**
+     * 新版本入栈。把当前产物快照复制到 versions/<n>/，旧 active 版本标记 superseded，
+     * 返回新版本号。
+     */
+    pushVersion(input) {
+        const store = this.loadVersions(input.artifactId);
+        const nextNumber = store.versions.length === 0
+            ? 1
+            : Math.max(...store.versions.map((v) => v.version)) + 1;
+        // 旧 active 版本标记为 superseded
+        for (const v of store.versions) {
+            if (v.status === 'active')
+                v.status = 'superseded';
+        }
+        let snapshotRel;
+        if (input.artifactSnapshotPath && existsSync(input.artifactSnapshotPath)) {
+            const snapDir = join(this.dirFor(input.artifactId), 'versions', String(nextNumber));
+            this.ensureDir(snapDir);
+            const target = join(snapDir, 'artifact' + extOf(input.artifactSnapshotPath));
+            cpSync(input.artifactSnapshotPath, target, { recursive: false });
+            snapshotRel = relative(this.canvasRoot, target);
+        }
+        const version = {
+            version: nextNumber,
+            snapshotPath: snapshotRel,
+            intent: input.intent,
+            changedFiles: input.changedFiles,
+            status: 'active',
+            createdAt: Date.now(),
+        };
+        store.versions.push(version);
+        store.activeVersion = nextNumber;
+        this.writeJson(this.versionsPath(input.artifactId), store);
+        try {
+            this.onVersionPushed?.(input.artifactId, nextNumber);
+        }
+        catch { /* emit 失败不影响持久化 */ }
+        return version;
+    }
+    listVersions(artifactId) {
+        return this.loadVersions(artifactId).versions;
+    }
+    getActiveVersion(artifactId) {
+        return this.loadVersions(artifactId).activeVersion;
+    }
+    /** 切换/回退到指定版本（不删除其它版本，只改 active 指针与状态）。 */
+    switchVersion(artifactId, target) {
+        const store = this.loadVersions(artifactId);
+        const found = store.versions.find((v) => v.version === target);
+        if (!found)
+            return false;
+        for (const v of store.versions) {
+            if (v.version === target)
+                v.status = 'active';
+            else if (v.status === 'active')
+                v.status = 'reverted';
+        }
+        store.activeVersion = target;
+        this.writeJson(this.versionsPath(artifactId), store);
+        return true;
+    }
+    // ─── Comments（结构化批注）────────────────────────────────────
+    commentsPath(artifactId) {
+        return join(this.dirFor(artifactId), 'comments.json');
+    }
+    listComments(artifactId) {
+        return this.readJson(this.commentsPath(artifactId)) ?? [];
+    }
+    addComment(comment) {
+        const list = this.listComments(comment.artifactId);
+        list.push(comment);
+        this.writeJson(this.commentsPath(comment.artifactId), list);
+    }
+    updateCommentStatus(artifactId, commentId, status) {
+        const list = this.listComments(artifactId);
+        const c = list.find((x) => x.id === commentId);
+        if (!c)
+            return false;
+        c.status = status;
+        c.updatedAt = Date.now();
+        this.writeJson(this.commentsPath(artifactId), list);
+        return true;
+    }
+    // ─── 聚合 ─────────────────────────────────────────────────────
+    getArtifactState(artifactId) {
+        const sourceMap = this.getSourceMap(artifactId);
+        if (!sourceMap)
+            return null;
+        return {
+            artifactId,
+            sourceMap,
+            versions: this.listVersions(artifactId),
+            activeVersion: this.getActiveVersion(artifactId),
+            comments: this.listComments(artifactId),
+        };
+    }
+    /** 列出所有已登记的产物 ID。 */
+    listArtifacts() {
+        if (!existsSync(this.canvasRoot))
+            return [];
+        return readdirSync(this.canvasRoot, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name)
+            .filter((id) => existsSync(join(this.canvasRoot, id, 'sourcemap.json')));
+    }
+}
+function extOf(p) {
+    const m = /\.[a-zA-Z0-9]+$/.exec(p);
+    return m ? m[0] : '';
+}
+//# sourceMappingURL=CanvasStore.js.map

package/dist/core/canvas/CanvasStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CanvasStore.js","sourceRoot":"","sources":["../../../src/core/canvas/CanvasStore.ts"],"names":[],"mappings":"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"}

package/dist/core/checkpoint/CheckpointBoundary.d.ts

@@ -0,0 +1,36 @@
+/**
+ * CheckpointBoundary — threshold calculation for checkpoint triggering.
+ *
+ * Determines whether a new checkpoint should be written based on:
+ * - Minimum 5 messages with content since last watermark
+ * - Dynamic token thresholds based on context window size (percentage-based)
+ * - Looks backward through messages to find a 20,000 token window for the watermark
+ */
+import { type ChatMessage } from '../../llm/types.js';
+import type { CheckpointBoundaryResult } from './types.js';
+/**
+ * Compute dynamic checkpoint thresholds based on context window size.
+ *
+ * Returns an array of token counts at which checkpoints should fire.
+ * The density of thresholds scales with window size:
+ * - < 25K: disabled (empty array)
+ * - 25K-200K: 20%, 40%, 60%, 80% of usable space
+ * - 200K-500K: 10%, 20%, ..., 90% of usable space
+ * - > 500K: 5%, 10%, ..., 90% of usable space
+ */
+export declare function computeThresholds(contextWindowSize: number): number[];
+/**
+ * Assign a stable ID to a message for watermark tracking.
+ * Uses index-based ID since ChatMessage doesn't have a native id field.
+ */
+export declare function messageId(index: number, msg: ChatMessage): string;
+/**
+ * Evaluate whether a checkpoint should be written.
+ *
+ * @param messages - Full message array from ContextManager
+ * @param lastWatermarkId - The message ID from the previous checkpoint (null if first)
+ * @param contextWindowSize - The model's context window size (used for dynamic thresholds)
+ * @param thresholdsCrossed - Set of thresholds already fired (for dedup)
+ */
+export declare function evaluateBoundary(messages: ChatMessage[], lastWatermarkId: string | null, contextWindowSize?: number, thresholdsCrossed?: Set<number>): CheckpointBoundaryResult;
+//# sourceMappingURL=CheckpointBoundary.d.ts.map

package/dist/core/checkpoint/CheckpointBoundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CheckpointBoundary.d.ts","sourceRoot":"","sources":["../../../src/core/checkpoint/CheckpointBoundary.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE1E,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAQ3D;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,iBAAiB,EAAE,MAAM,GAAG,MAAM,EAAE,CAyBrE;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,MAAM,CAGjE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,WAAW,EAAE,EACvB,eAAe,EAAE,MAAM,GAAG,IAAI,EAC9B,iBAAiB,CAAC,EAAE,MAAM,EAC1B,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAC9B,wBAAwB,CA8F1B"}