@ai-setting/roy-agent-core 1.7.71 → 1.7.75

package/dist/env/session/index.js

@@ -3,16 +3,15 @@ import {
   MIN_SESSION_ID_LENGTH,
   SessionComponent,
   isValidSessionId
-} from "../../shared/@ai-setting/roy-agent-core-9bshyqjn.js";
+} from "../../shared/@ai-setting/roy-agent-core-ddyk1rc0.js";
 import {
   MemorySessionStore
-} from "../../shared/@ai-setting/roy-agent-core-hy3zn2q2.js";
-import"../../shared/@ai-setting/roy-agent-core-ze068vc9.js";
+} from "../../shared/@ai-setting/roy-agent-core-0qyrk5k0.js";
 import"../../shared/@ai-setting/roy-agent-core-rvxg1wps.js";
 import {
   SessionMessageConverter
-} from "../../shared/@ai-setting/roy-agent-core-kmbct9yg.js";
-import"../../shared/@ai-setting/roy-agent-core-40rv283c.js";
+} from "../../shared/@ai-setting/roy-agent-core-0snm5hc5.js";
+import"../../shared/@ai-setting/roy-agent-core-fghc2m8z.js";
 import"../../shared/@ai-setting/roy-agent-core-zjdzk1gg.js";
 import"../../shared/@ai-setting/roy-agent-core-ntn32q7j.js";
 import"../../shared/@ai-setting/roy-agent-core-7hh0brvs.js";

package/dist/env/session/session-component.d.ts

@@ -8,6 +8,7 @@ import { type SessionConfig, type Session, type CreateSessionOptions, type Updat
 type CompactOptions, // (new)
 type CompactResult, // (new)
 type CompactPreview, // (new)
+type CheckpointAdaptReport, // Task #4933
 type GetContextOptions, // (new)
 type GetContextResult, // (new)
 type SearchMessagesOptions, // (new)
@@ -15,11 +16,11 @@ type SearchResult, // (new)
 type ChatTaskBinding, // Task #4023
 type UpsertChatTaskBindingOptions } from "./types";
 import type { ConfigComponent } from "../../config/config-component";
-import type { SummaryAgentResult } from "../agent/types";
 export type { SessionConfig, Session, SessionMessage, CreateSessionOptions, UpdateSessionOptions, ListSessionsOptions, AddMessageOptions, SessionCheckpoint, // (new)
 CompactOptions, // (new)
 CompactResult, // (new)
 CompactPreview, // (new)
+CheckpointAdaptReport, // Task #4933
 GetContextOptions, // (new)
 GetContextResult, // (new)
 SearchMessagesOptions, // (new) Search
@@ -27,35 +28,6 @@ SearchResult, // (new) Search
 MessageMatch, // (new) Search
 ChatTaskBinding, // Task #4023
 UpsertChatTaskBindingOptions, } from "./types";
-/**
- * 把 compact agent 通过 `workflow_submit_output` 提交的数据归一化。
- */
-export declare function normalizeAgentCheckpoint(data: Record<string, unknown>): SummaryAgentResult;
-/**
- * 判断一段文本是否可作为 checkpoint 正文（拒绝空白与降级哨兵）。
- */
-export declare function isUsableCheckpointText(text?: string | null): boolean;
-/**
- * 降级路径：compact agent 没有调用 `workflow_submit_output` 时，用它输出的
- * 纯文本 `finalText` 兜底构造 checkpoint。
- *
- * 为什么需要（2026-10-16 生产事故 traceId=83eadac2316d5be7529ca42ce7057d63）：
- *   compact 是子 agent。首轮若没调提交工具，`checkpointData` 就是 undefined，
- *   旧代码会写出全空 checkpoint（`"Untitled Checkpoint"`）**然后照样归档几百条消息**
- *   （实测生产 9 次 / 累计吞掉 4731 条 / 单次最多 2710 条）→ 上下文永久丢失且用户无感知。
- *
- *   而实际上模型往往已经产出了可用的 checkpoint 内容，只是以纯文本形式落在
- *   `finalText` 里（例：`"## 📌 Checkpoint: lark-cli profile 配置 ..."`），
- *   或者包在 ```json 代码块里。这些内容全部可以救回来。
- *
- * 策略：
- *   1. 先从文本里抠 JSON（```json 代码块 / 裸 JSON / 第一个 {...}）→ 结构化解析；
- *   2. 否则把整段文本作为 `currentState`，title 取首个 markdown 标题行（或首行）；
- *   3. 文本为空 / 是降级哨兵 → 返回 undefined（调用方继续降级或抛错）
- *
- * @returns 归一化后的 checkpoint，或 undefined（无可用文本）
- */
-export declare function buildCheckpointFromFinalText(finalText?: string): SummaryAgentResult | undefined;
 /**
  * Marker error class so callers can distinguish "lock exhausted after
  * retries" from "validation rejected on first attempt". Previously both
@@ -345,6 +317,19 @@ export declare class SessionComponent extends BaseComponent {
     private executeBeforeHooks;
     private executeAfterHooks;
     private generateTitle;
+    /**
+     * 读取压缩专用模型（`session.compactModel`）。
+     *
+     * ★ Task #4933：两阶段压缩（compact-hint / compact）统一走该模型。
+     *   实现方式：读配置后作为 `AgentContext.model`（run option）传入，
+     *   run option 在 agent-component.ts:1518
+     *   `model: (context?.model) ?? agent.config.model` 处优先级最高，
+     *   因此**会覆盖**用户级 `~/.local/share/roy-agent/agents/compact.yaml`
+     *   里写死的 model 字段。
+     *
+     * @returns 模型 id（如 `minimax/MiniMax-M3.1-Flash`），未配置返回 undefined
+     */
+    private getCompactModel;
     /**
      * 生成场景化压缩提示 (Compact Hint)
      *
@@ -408,12 +393,44 @@ export declare class SessionComponent extends BaseComponent {
     previewCompact(sessionId: string): Promise<CompactPreview>;
     /**
      * Get all checkpoints for a session
+     *
+     * ★ C 方案：旧格式（五栏位）读时适配为新格式（content），
+     *   不写回数据库（lazy adapter）。
      */
     getCheckpoints(sessionId: string): Promise<SessionCheckpoint[]>;
     /**
      * Get a specific checkpoint
+     *
+     * ★ C 方案：旧格式读时适配（见 getCheckpoints）。
      */
     getCheckpoint(sessionId: string, checkpointId: string): Promise<SessionCheckpoint | undefined>;
+    /**
+     * 读取 checkpoint 的**原始存储形态**（不做适配）。
+     *
+     * 用途：存量 checkpoint 检查脚本 / adaptStoredCheckpoints 内部统计 ——
+     * 需要区分「库里到底存的是旧格式还是新格式」。
+     */
+    readStoredCheckpointsRaw(sessionId: string): Promise<SessionCheckpoint[]>;
+    /**
+     * 存量 checkpoint 适配（C 方案 Task #4933）。
+     *
+     * 生产库有 555 个旧格式 checkpoint（五栏位，无 content）。默认**读时适配**
+     * 已能让新代码无感知；本方法提供**显式迁移**能力（把旧格式写回新格式）。
+     *
+     * ⚠️ 默认 dry-run（`apply: false`）：只统计 + 抽样，不写数据库。
+     * ⚠️ `apply: true` 会重写 session.metadata —— 如果 roy-agent daemon 正在运行
+     *    并持有 sessions.db 的内存缓存，外部进程的写入可能被 daemon 的后续
+     *    saveCheckpoint 覆盖。建议在 daemon 重启后（或停机时）执行。
+     */
+    adaptStoredCheckpoints(sessionId: string, options?: {
+        apply?: boolean;
+    }): Promise<CheckpointAdaptReport>;
+    /**
+     * 把一组 checkpoint 整体写回 session.metadata.checkpointDetails。
+     *
+     * 只做「按 id 覆盖」，不动 checkpoints 索引里的 meta（id/title/createdAt 不变）。
+     */
+    private writeCheckpointsBack;
     /**
      * Delete a checkpoint and restore archived messages
      */

package/dist/env/session/storage/index.js

@@ -3,9 +3,9 @@ import {
   SQLiteSessionStore,
   getDefaultDataDir,
   getDefaultSessionDbPath
-} from "../../../shared/@ai-setting/roy-agent-core-hy3zn2q2.js";
-import"../../../shared/@ai-setting/roy-agent-core-kmbct9yg.js";
-import"../../../shared/@ai-setting/roy-agent-core-40rv283c.js";
+} from "../../../shared/@ai-setting/roy-agent-core-0qyrk5k0.js";
+import"../../../shared/@ai-setting/roy-agent-core-0snm5hc5.js";
+import"../../../shared/@ai-setting/roy-agent-core-fghc2m8z.js";
 import"../../../shared/@ai-setting/roy-agent-core-zjdzk1gg.js";
 import"../../../shared/@ai-setting/roy-agent-core-ntn32q7j.js";
 import"../../../shared/@ai-setting/roy-agent-core-qq96p0tj.js";

package/dist/env/session/storage/sqlite.d.ts

@@ -92,6 +92,14 @@ export declare class SQLiteSessionStore extends BaseSessionStore {
     getMessageIndexes(sessionId: string, role: string): Promise<number[]>;
     saveCheckpoint(sessionId: string, checkpoint: SessionCheckpoint): Promise<void>;
     getCheckpoints(sessionId: string): Promise<SessionCheckpoint[]>;
+    /**
+     * 按 id 覆盖写回一组 checkpoint 明细（Task #4933 存量格式迁移用）。
+     *
+     * 只改 `metadata.checkpointDetails`，不动 `metadata.checkpoints` 索引
+     * （id / title / messageIndex / createdAt 都是不变的元数据）。
+     * 返回是否有任何变更被写入。
+     */
+    replaceCheckpointDetails(sessionId: string, checkpoints: SessionCheckpoint[]): Promise<boolean>;
     getCheckpoint(sessionId: string, checkpointId: string): Promise<SessionCheckpoint | undefined>;
     deleteCheckpoint(sessionId: string, checkpointId: string): Promise<boolean>;
     archiveMessages(sessionId: string, checkpointId: string, beforeIndex: number): Promise<number>;

package/dist/env/session/types.d.ts

@@ -83,10 +83,6 @@ export interface CheckpointMeta {
     createdAt: number;
     type: CheckpointType;
 }
-/**
- * User Intent type - represents a user's intent extracted from conversation
- */
-export type UserIntent = string;
 /**
  * Recent message for checkpoint
  *
@@ -100,14 +96,18 @@ export interface RecentMessage {
  * Complete checkpoint information (includes generated content)
  */
 export interface SessionCheckpoint extends CheckpointMeta {
-    summary: string;
-    processKeyPoints: string[];
-    currentState: string;
-    nextSteps: string[];
+    /**
+     * ★ C 方案（Task #4933 重写）：整段自然语言 checkpoint 正文。
+     *
+     * 用户决策：压缩产物不再结构化 —— 没有 summary /
+     * processKeyPoints / currentState / nextSteps / userIntents 五栏位，
+     * 也没有固定 markdown 小节契约。正文形式自由（段落/列表/代码块都行）。
+     *
+     * 旧格式存量数据（生产 555 个）由 adaptLegacyCheckpoint()
+     * 在读取时合成 content，不写回数据库。
+     */
+    content: string;
     messageCountBefore: number;
-    metadata?: Record<string, unknown>;
-    /** User intents extracted from the conversation */
-    userIntents: UserIntent[];
     /**
      * Recent messages preserved from the compacted conversation
      *
@@ -378,16 +378,10 @@ export interface CheckpointPart {
     type: "checkpoint";
     /** Checkpoint ID reference */
     checkpointId: string;
-    /** Markdown content summarizing the checkpoint */
+    /** Checkpoint content (整段自然语言正文) */
     content: string;
     /** Title of the checkpoint */
     title?: string;
-    /** Process key points */
-    processKeyPoints?: string[];
-    /** Current state description */
-    currentState?: string;
-    /** Next steps */
-    nextSteps?: string[];
     /** Number of messages that were compacted */
     messageCountBefore?: number;
     /** Creation timestamp */
@@ -515,30 +509,27 @@ export interface AddMessageOptions {
 }
 /**
  * Options for compact operation
+ *
+ * ★ Task #4933（C 方案）：只剩 `scenarioHint` 一个语义字段。
+ *   旧的 processKeyPoints / currentState / nextSteps 三栏位 hint 已删除
+ *   （它们是「五栏位结构化」时代的遗留 —— C 方案下压缩产物是整段自然语言，
+ *   用户/CLI 再拼装结构化栏位没有意义，且会让后续开发者误以为五栏位仍是契约）。
+ *   `summary` 同样未在 compact() 中被读取（HEAD 之前即如此），一并移除。
  */
 export interface CompactOptions {
-    /** User-provided summary hint for checkpoint generation */
-    summary?: string;
-    /** User-provided process key points hint */
-    processKeyPoints?: string[];
-    /** User-provided current state hint */
-    currentState?: string;
-    /** User-provided next steps hint */
-    nextSteps?: string[];
     /** Whether this is auto-triggered compact */
     auto?: boolean;
     /**
      * Scenario hint for guiding checkpoint generation
      *
      * A natural language description that provides context about the current scenario.
-     * This helps the SummaryAgent generate more relevant checkpoints based on the specific
-     * situation. Examples:
+     * This helps the checkpoint generator produce more relevant content based on the
+     * specific situation. Examples:
      * - "Task execution in progress: implementing feature X, current working directory is /path/to/project"
      * - "Bug investigation: analyzing crash dump, current hypothesis is memory corruption"
      * - "Code review session: reviewing PR #123, focus on security implications"
      *
-     * When provided, this will be prepended to the system prompt to guide the checkpoint
-     * generation with scenario-specific emphasis.
+     * When provided, it is injected into the compact agent's query as a focus hint.
      */
     scenarioHint?: string;
 }
@@ -559,6 +550,30 @@ export interface CompactPreview {
     estimatedCheckpointTokens: number;
     wouldTrigger: boolean;
 }
+/**
+ * 存量 checkpoint 适配报告（Task #4933 C 方案）
+ *
+ * 生产库有 555 个旧格式 checkpoint（五栏位，无 content）。
+ * `adaptStoredCheckpoints()` 默认 dry-run，返回本报告用于人工核对。
+ */
+export interface CheckpointAdaptReport {
+    sessionId: string;
+    /** checkpoint 总数 */
+    total: number;
+    /** 旧格式（无 content）数量 */
+    legacy: number;
+    /** 新格式（已有 content）数量 */
+    modern: number;
+    /** 实际写回的数量（dry-run 时恒为 0） */
+    applied: number;
+    /** 抽样（最多 3 条），用于人工确认合成正文质量 */
+    samples: Array<{
+        id: string;
+        title: string;
+        contentLength: number;
+        contentPreview: string;
+    }>;
+}
 /**
  * Options for getting session context
  */

package/dist/env/task/delegate/delegate-tool.d.ts

@@ -122,6 +122,14 @@ export interface BackgroundTaskAskUserPayload {
     nodeId: string;
     nodeType: string;
     agentSessionId?: string;
+    /**
+     * ★ Task #4983 — 问题**是否已投递到用户渠道**（工具层判定）。
+     *
+     * - `true`  → ask_user 工具已经把问题正文发到 IM 渠道，用户已看到 ⇒
+     *              主 agent 那一轮**不得**再发（否则用户收到两条）。
+     * - `false` → 工具层没投成（没有 replyChannel / 投递失败）⇒ 需要兜底投递。
+     */
+    delivered?: boolean;
     /** 原始 __ASK_USER_ERROR__:... 错误字符串（备份，便于诊断） */
     error: string;
     executionTimeMs: number;

package/dist/env/task/delegate/delegate-tool.js

@@ -12,13 +12,13 @@ import {
   deriveTriggerEventIdFromEnvContext,
   getSubAgentSpec,
   handleBackgroundTask
-} from "../../../shared/@ai-setting/roy-agent-core-101qtkyc.js";
+} from "../../../shared/@ai-setting/roy-agent-core-jg65qnwa.js";
 import"../../../shared/@ai-setting/roy-agent-core-fttgm52a.js";
 import"../../../shared/@ai-setting/roy-agent-core-na18zwj0.js";
-import"../../../shared/@ai-setting/roy-agent-core-zv8bswpw.js";
+import"../../../shared/@ai-setting/roy-agent-core-3e6gg17d.js";
 import"../../../shared/@ai-setting/roy-agent-core-1pg0fepg.js";
-import"../../../shared/@ai-setting/roy-agent-core-4jjwewvw.js";
-import"../../../shared/@ai-setting/roy-agent-core-07fvy74y.js";
+import"../../../shared/@ai-setting/roy-agent-core-11shp00p.js";
+import"../../../shared/@ai-setting/roy-agent-core-ed233k5z.js";
 import"../../../shared/@ai-setting/roy-agent-core-qxnbvgwe.js";
 import"../../../shared/@ai-setting/roy-agent-core-c1v263jn.js";
 import"../../../shared/@ai-setting/roy-agent-core-cpcd24n2.js";

package/dist/env/task/delegate/index.js

@@ -5,13 +5,13 @@ import {
   BackgroundTaskEventTypes,
   BackgroundTaskManager,
   createDelegateTool
-} from "../../../shared/@ai-setting/roy-agent-core-101qtkyc.js";
+} from "../../../shared/@ai-setting/roy-agent-core-jg65qnwa.js";
 import"../../../shared/@ai-setting/roy-agent-core-fttgm52a.js";
 import"../../../shared/@ai-setting/roy-agent-core-na18zwj0.js";
-import"../../../shared/@ai-setting/roy-agent-core-zv8bswpw.js";
+import"../../../shared/@ai-setting/roy-agent-core-3e6gg17d.js";
 import"../../../shared/@ai-setting/roy-agent-core-1pg0fepg.js";
-import"../../../shared/@ai-setting/roy-agent-core-4jjwewvw.js";
-import"../../../shared/@ai-setting/roy-agent-core-07fvy74y.js";
+import"../../../shared/@ai-setting/roy-agent-core-11shp00p.js";
+import"../../../shared/@ai-setting/roy-agent-core-ed233k5z.js";
 import"../../../shared/@ai-setting/roy-agent-core-qxnbvgwe.js";
 import"../../../shared/@ai-setting/roy-agent-core-c1v263jn.js";
 import"../../../shared/@ai-setting/roy-agent-core-cpcd24n2.js";

package/dist/env/task/index.js

@@ -5,27 +5,27 @@ import {
   TaskPriorityEnum,
   TaskStatusEnum,
   TaskTypeEnum
-} from "../../shared/@ai-setting/roy-agent-core-mwa6apzx.js";
-import"../../shared/@ai-setting/roy-agent-core-58804s3j.js";
+} from "../../shared/@ai-setting/roy-agent-core-4gr3k7qg.js";
+import"../../shared/@ai-setting/roy-agent-core-2akfd64z.js";
 import"../../shared/@ai-setting/roy-agent-core-jm136jzh.js";
-import"../../shared/@ai-setting/roy-agent-core-101qtkyc.js";
+import"../../shared/@ai-setting/roy-agent-core-jg65qnwa.js";
 import"../../shared/@ai-setting/roy-agent-core-fttgm52a.js";
 import"../../shared/@ai-setting/roy-agent-core-ntq0gz7q.js";
 import {
   TaskEntityEventTypes
 } from "../../shared/@ai-setting/roy-agent-core-8gxth0eh.js";
-import"../../shared/@ai-setting/roy-agent-core-7sj9xs9c.js";
+import"../../shared/@ai-setting/roy-agent-core-hnyk1by7.js";
 import"../../shared/@ai-setting/roy-agent-core-p5cz9m8v.js";
 import"../../shared/@ai-setting/roy-agent-core-na18zwj0.js";
-import"../../shared/@ai-setting/roy-agent-core-zv8bswpw.js";
+import"../../shared/@ai-setting/roy-agent-core-3e6gg17d.js";
 import {
   SQLiteTaskStore,
   getDefaultTaskDbPath
 } from "../../shared/@ai-setting/roy-agent-core-abqhkbn3.js";
 import"../../shared/@ai-setting/roy-agent-core-1pg0fepg.js";
 import"../../shared/@ai-setting/roy-agent-core-tr3ep81v.js";
-import"../../shared/@ai-setting/roy-agent-core-4jjwewvw.js";
-import"../../shared/@ai-setting/roy-agent-core-07fvy74y.js";
+import"../../shared/@ai-setting/roy-agent-core-11shp00p.js";
+import"../../shared/@ai-setting/roy-agent-core-ed233k5z.js";
 import"../../shared/@ai-setting/roy-agent-core-qxnbvgwe.js";
 import"../../shared/@ai-setting/roy-agent-core-c1v263jn.js";
 import"../../shared/@ai-setting/roy-agent-core-7hh0brvs.js";

package/dist/env/task/mcp/index.js

@@ -6,13 +6,13 @@ import {
   searchTasksTool,
   treeTasksTool,
   updateTaskTool
-} from "../../../shared/@ai-setting/roy-agent-core-7sj9xs9c.js";
+} from "../../../shared/@ai-setting/roy-agent-core-hnyk1by7.js";
 import {
   createOperationTool,
   listOperationsTool
 } from "../../../shared/@ai-setting/roy-agent-core-p5cz9m8v.js";
 import"../../../shared/@ai-setting/roy-agent-core-tr3ep81v.js";
-import"../../../shared/@ai-setting/roy-agent-core-4jjwewvw.js";
+import"../../../shared/@ai-setting/roy-agent-core-11shp00p.js";
 import"../../../shared/@ai-setting/roy-agent-core-7cbpmk4q.js";
 import"../../../shared/@ai-setting/roy-agent-core-qq96p0tj.js";
 import"../../../shared/@ai-setting/roy-agent-core-7f7t9wwp.js";

package/dist/env/task/plugins/index.d.ts

@@ -4,6 +4,9 @@
 export { TaskTagPlugin } from "./task-tag-plugin";
 export { LayaDecisionPlugin, createLayaDecisionPlugin, LAYA_REUSE_THRESHOLD, type LayaDecisionPluginOptions, } from "./laya-decision-plugin";
 export { createAutoTaskPlugin, type AutoTaskPluginConfig, } from "./auto-task-plugin";
+export { LayaCompletionPlugin, createLayaCompletionPlugin, registerLayaCompletionTaskHook, buildCompletionHint, renderCompletionState, buildCompletionQuestion, LAYA_COMPLETION_THRESHOLD, type LayaCompletionPluginOptions, } from "./laya-completion-plugin";
+export { TASK_COMPLETION_HINT_ANCHOR, TASK_COMPLETE_ITEM_BY_ITEM, TASK_COMPLETE_VERIFY_DUTY, TASK_COMPLETE_ACCEPTANCE, } from "../tools/completion-copy";
+export type { DecisionPort, DecisionRequest, DecisionAnswer, DecisionResponse, } from "./decision-port";
 export { WORKFLOW_EXTRACTOR_PROMPT, formatExtractorInput, formatExtractorInputFromDescription, parseExtractorOutput, } from "./workflow-extractor-agent";
 export { LarkCliTaskNotifyHook, createLarkCliTaskNotifyHook, type TaskNotifyConfig, NotifyType, } from "./lark-cli-task-notify-plugin";
 export { PerTaskGroupChatPlugin, createPerTaskGroupChatPlugin, type PerTaskGroupConfig, } from "./per-task-group-chat-plugin";

package/dist/env/task/plugins/index.js

@@ -1,6 +1,8 @@
 import {
+  LAYA_COMPLETION_THRESHOLD,
   LAYA_REUSE_THRESHOLD,
   LarkCliTaskNotifyHook,
+  LayaCompletionPlugin,
   LayaDecisionPlugin,
   MemoryLarkCardStateStore,
   NotifyType,
@@ -8,22 +10,32 @@ import {
   SqliteLarkCardStateStore,
   TaskTagPlugin,
   WORKFLOW_EXTRACTOR_PROMPT,
+  buildCompletionHint,
+  buildCompletionQuestion,
   createAutoTaskPlugin,
   createLarkCardStateStore,
   createLarkCliTaskNotifyHook,
+  createLayaCompletionPlugin,
   createLayaDecisionPlugin,
   createPerTaskGroupChatPlugin,
   formatExtractorInput,
   formatExtractorInputFromDescription,
   getDefaultLarkCardDbPath,
-  parseExtractorOutput
-} from "../../../shared/@ai-setting/roy-agent-core-k13pxrpk.js";
+  parseExtractorOutput,
+  registerLayaCompletionTaskHook,
+  renderCompletionState
+} from "../../../shared/@ai-setting/roy-agent-core-y7x2qzwc.js";
 import"../../../shared/@ai-setting/roy-agent-core-na18zwj0.js";
-import"../../../shared/@ai-setting/roy-agent-core-zv8bswpw.js";
+import"../../../shared/@ai-setting/roy-agent-core-3e6gg17d.js";
 import"../../../shared/@ai-setting/roy-agent-core-abqhkbn3.js";
 import"../../../shared/@ai-setting/roy-agent-core-1pg0fepg.js";
 import"../../../shared/@ai-setting/roy-agent-core-tr3ep81v.js";
-import"../../../shared/@ai-setting/roy-agent-core-4jjwewvw.js";
+import {
+  TASK_COMPLETE_ACCEPTANCE,
+  TASK_COMPLETE_ITEM_BY_ITEM,
+  TASK_COMPLETE_VERIFY_DUTY,
+  TASK_COMPLETION_HINT_ANCHOR
+} from "../../../shared/@ai-setting/roy-agent-core-11shp00p.js";
 import {
   DEFAULT_APP_LINK_BASE,
   LarkCardPatchNotifier,
@@ -42,12 +54,12 @@ import {
   renderWorkflowInfoLines,
   resolveTaskTitleForDisplay,
   sanitizeInlineText
-} from "../../../shared/@ai-setting/roy-agent-core-46rv4d7d.js";
-import"../../../shared/@ai-setting/roy-agent-core-yr1mryb8.js";
-import"../../../shared/@ai-setting/roy-agent-core-mds8tqd0.js";
-import"../../../shared/@ai-setting/roy-agent-core-jrj30vq3.js";
+} from "../../../shared/@ai-setting/roy-agent-core-nmx9934r.js";
+import"../../../shared/@ai-setting/roy-agent-core-1v4g0d4x.js";
+import"../../../shared/@ai-setting/roy-agent-core-cgtq6427.js";
+import"../../../shared/@ai-setting/roy-agent-core-er070zjq.js";
 import"../../../shared/@ai-setting/roy-agent-core-f77k3gqt.js";
-import"../../../shared/@ai-setting/roy-agent-core-e25xkv53.js";
+import"../../../shared/@ai-setting/roy-agent-core-mkc3zshb.js";
 import"../../../shared/@ai-setting/roy-agent-core-az13yzmc.js";
 import"../../../shared/@ai-setting/roy-agent-core-qqaak24r.js";
 import"../../../shared/@ai-setting/roy-agent-core-7cbpmk4q.js";
@@ -64,6 +76,8 @@ export {
   renderProcessSteps,
   renderMilestones,
   renderContextAsLines,
+  renderCompletionState,
+  registerLayaCompletionTaskHook,
   parseExtractorOutput,
   humanizeValue,
   getDefaultLarkCardDbPath,
@@ -74,21 +88,30 @@ export {
   formatDateTimeForDisplay,
   createPerTaskGroupChatPlugin,
   createLayaDecisionPlugin,
+  createLayaCompletionPlugin,
   createLarkCliTaskNotifyHook,
   createLarkCardStateStore,
   createAutoTaskPlugin,
   buildWorkflowCard,
   buildTaskCard,
+  buildCompletionQuestion,
+  buildCompletionHint,
   buildChatAppLink,
   WORKFLOW_EXTRACTOR_PROMPT,
   TaskTagPlugin,
+  TASK_COMPLETION_HINT_ANCHOR,
+  TASK_COMPLETE_VERIFY_DUTY,
+  TASK_COMPLETE_ITEM_BY_ITEM,
+  TASK_COMPLETE_ACCEPTANCE,
   SqliteLarkCardStateStore,
   PerTaskGroupChatPlugin,
   NotifyType,
   MemoryLarkCardStateStore,
   LayaDecisionPlugin,
+  LayaCompletionPlugin,
   LarkCliTaskNotifyHook,
   LarkCardPatchNotifier,
   LAYA_REUSE_THRESHOLD,
+  LAYA_COMPLETION_THRESHOLD,
   DEFAULT_APP_LINK_BASE
 };

package/dist/env/task/plugins/lark-card-patch-notifier.d.ts

@@ -379,6 +379,27 @@ export declare function formatTimestampForDisplay(iso: string | undefined): stri
  * 路径 / 命令 / 中文正文不受影响。
  */
 export declare function sanitizeInlineText(text: string, maxLen?: number): string;
+/**
+ * 卡片 head 标题的**视觉宽度预算**（Task #4984）
+ *
+ * 飞书卡片 header.title 是单行 plain_text，超长会被截断/挤压布局。
+ * 这里用「视觉宽度」而非字符数做预算：CJK 占 2 列、ASCII 占 1 列。
+ */
+export declare const HEAD_TITLE_MAX_WIDTH = 40;
+/**
+ * 截断卡片 head 用的任务名称（Task #4984）
+ *
+ * 策略（按用户诉求「head 要有任务名称，但别撑破布局」）：
+ * 1. 先把多行压成单行（head 是单行 plain_text）
+ * 2. **视觉宽度**预算：CJK 记 2 列、ASCII 记 1 列
+ * 3. 不切半个 emoji —— 按 code point 遍历，代理对整体保留
+ * 4. 不切半个英文单词 —— 尽量在空格/分隔符处断开
+ * 5. 超长时补 "…" 后缀
+ *
+ * @param text 原始标题
+ * @param maxWidth 视觉宽度预算（默认 {@link HEAD_TITLE_MAX_WIDTH}）
+ */
+export declare function truncateHeadTitle(text: string | undefined | null, maxWidth?: number): string;
 /** ISO 8601 时间串 → 北京时间 "YYYY-MM-DD HH:mm"（非 ISO 时原样返回） */
 export declare function formatDateTimeForDisplay(value: string): string;
 /**
@@ -677,6 +698,28 @@ export declare class LarkCardPatchNotifier {
      * ★ 幂等：已有 state 时不覆盖（内存里的比持久化的更新）。
      */
     hydrateState(messageId: string, snapshot: CardStateSnapshot): void;
+    /**
+     * ★ Task #5020 —— 把时间线条目**并入内存态**，但**不发** lark-cli patch。
+     *
+     * ## 为什么需要
+     *
+     * `task:operation:after.create` 的 patch 频率受 `operationThrottleMs`
+     * 约束（默认 5s），目的是别刷屏飞书。但**节流不该丢数据**：
+     * 被节流的那条 operation 如果直接丢掉，它的里程碑既不上卡也不落库。
+     *
+     * 这个方法让「节流」与「数据完整性」解耦：
+     *   - 被节流的 operation → `mergeTimelineState`（只进内存态，不 patch）
+     *   - 下一次允许 patch → `updateTask` 把**累积后的**整条时间线 patch 出去
+     *   - 任何时刻的 `exportState` 都能看到**全部**里程碑 → ledger 落库完整
+     *
+     * ## 与 `updateTask` 的区别
+     *
+     * `updateTask` 会**渲染并发送**卡片（一次 lark-cli 调用）；本方法**不碰飞书**，
+     * 只动内存态。调用方负责决定何时真正 patch。
+     *
+     * @returns 是否真的并入了（state 不存在时返回 false —— 那张卡不是本 notifier 的）
+     */
+    mergeTimelineState(messageId: string, milestones?: Milestone[], processSteps?: ProcessStep[]): boolean;
     /**
      * 暂停卡片（Task #4536：stop / archived）+ unpin，**保留**卡片状态与时间线
      *
@@ -744,6 +787,24 @@ export declare class LarkCardPatchNotifier {
     updateMetaAndBuildCard(messageId: string, meta: TaskMeta, opts?: {
         clearPerTaskChat?: boolean;
     }): CardPayload | undefined;
+    /**
+     * ★ Task #5020 —— 已经走到**真终态**的卡片（review round-4 MAJOR）。
+     *
+     * ## 为什么需要（结构性地堵住竞态，而不是靠时序检查）
+     *
+     * `finishTask` 结束后会 `states.delete(messageId)`。此时若有**另一个**
+     * 已经通过前置检查、正在等 mutex 的 `updateTask` 排队进来，它会因为
+     * 「state 不存在」而用空默认 state 重建卡片 → 把「已完成」刷回「进行中」
+     * 且清空里程碑。
+     *
+     * 前置检查（`cardMessageIds` / ledger status）只能挡住**还没开始**的补发；
+     * 已经进入 `mutexFor(messageId)` 队列的那一个挡不住。所以必须在
+     * notifier 内部——也就是唯一串行化那一步——做终态守卫。
+     *
+     * 记 messageId 而不是 taskId：reopen 场景会发一张**新卡**（新 messageId），
+     * 不会被旧 messageId 的终态记录误伤。
+     */
+    private finalisedCards;
     /** 诊断：当前跟踪中的卡片数（测试/自检用） */
     trackedCardCount(): number;
     /** 诊断：当前跟踪中的 workflow 卡片数（测试/自检用） */

package/dist/env/task/plugins/lark-card-patch-notifier.js

@@ -1,5 +1,6 @@
 import {
   DEFAULT_APP_LINK_BASE,
+  HEAD_TITLE_MAX_WIDTH,
   LarkCardPatchNotifier,
   buildChatAppLink,
   buildCollapsiblePanel,
@@ -19,13 +20,15 @@ import {
   renderTaskInfoLines,
   renderWorkflowInfoLines,
   resolveTaskTitleForDisplay,
-  sanitizeInlineText
-} from "../../../shared/@ai-setting/roy-agent-core-46rv4d7d.js";
+  sanitizeInlineText,
+  truncateHeadTitle
+} from "../../../shared/@ai-setting/roy-agent-core-nmx9934r.js";
 import"../../../shared/@ai-setting/roy-agent-core-qq96p0tj.js";
 import"../../../shared/@ai-setting/roy-agent-core-7f7t9wwp.js";
 import"../../../shared/@ai-setting/roy-agent-core-85xyctnb.js";
 import"../../../shared/@ai-setting/roy-agent-core-fs0mn2jk.js";
 export {
+  truncateHeadTitle,
   sanitizeInlineText,
   resolveTaskTitleForDisplay,
   renderWorkflowInfoLines,
@@ -46,5 +49,6 @@ export {
   buildCollapsiblePanel,
   buildChatAppLink,
   LarkCardPatchNotifier,
+  HEAD_TITLE_MAX_WIDTH,
   DEFAULT_APP_LINK_BASE
 };