@ai-setting/roy-agent-core 1.7.64 → 1.7.65

package/dist/env/environment.d.ts

@@ -23,6 +23,33 @@ import type { Environment, ServiceConfig, ComponentConfigEntry, GeneratedCompone
 import type { EnvironmentConfig, BaseEnvironmentConfig, EnvEvent, EnvEventInput, EnvEventHandler, Action, ToolResult, Context } from "./types";
 import type { AgentContext } from "./agent/types";
 import type { ContentPart } from "./llm/types";
+import type { TaskComponent } from "./task/task-component";
+import type { LayaDecisionPluginOptions } from "./task/plugins/laya-decision-plugin";
+/**
+ * Task #4627 — 把 Laya 决策插件注册到 **task hook 通道**（`task:before.create`）。
+ *
+ * ⚠️ 为什么必须走 task hook 而不是 Agent Plugin（#4620 的 bug 1）：
+ *   `AgentComponent.registerPlugin()` 只把 plugin 放进 `agent.plugins` Map，
+ *   **不写 globalHookManager**；而 `agent.plugins` 只在 agent 作用域 hook 点
+ *   被派发（`agent:before.start` / `agent:before.llm` / ...），**不含
+ *   `task:before.create`**。`task:before.create` 的唯一派发路径是
+ *   `TaskComponent.createTask()` → `globalHookManager.execute(...)`。
+ *
+ * ⚠️ 幂等保护：
+ *   `globalHookManager.register()` 是 **push 到数组**（不覆盖同名），
+ *   而 `handle_query` 每次调用都会走一遍注册逻辑 → 不去重会导致：
+ *     ① hook 被注册 N 次 → hint 重复执行
+ *     ② 模型被重复调用 N 次（每次 task_create 都打 N 次 HTTP）
+ *   这里采用「先 unregister 再 register」保证**全局恰好 1 份**。
+ *
+ * ⚠️ fail-open：注册失败**绝不影响** agent 启动 / task_create 成功语义。
+ *
+ * @param taskComponent —— TaskComponent（由 `this.getComponent("task")` 取得）
+ * @param options —— LayaDecisionPluginOptions（生产不传 → 读 auth.json；
+ *                   测试可注入 decisionPort / fetchImpl）
+ * @returns 是否成功注册
+ */
+export declare function registerLayaDecisionTaskHook(taskComponent: TaskComponent | undefined | null, options?: LayaDecisionPluginOptions): boolean;
 /**
  * 默认 agent 名字（向后兼容）
  */

package/dist/env/event-source/event-source-handlers.js

@@ -10,18 +10,19 @@ import {
   patchCardByLarkCli,
   renderRuleNoticeSection,
   timerHandler
-} from "../../shared/@ai-setting/roy-agent-core-1h5bbqcg.js";
+} from "../../shared/@ai-setting/roy-agent-core-18am1h07.js";
 import"../../shared/@ai-setting/roy-agent-core-bxkjk7zx.js";
 import"../../shared/@ai-setting/roy-agent-core-add1zqsh.js";
 import {
   cliCommandHandler
 } from "../../shared/@ai-setting/roy-agent-core-v0hf14bj.js";
 import"../../shared/@ai-setting/roy-agent-core-tm1mxttk.js";
-import"../../shared/@ai-setting/roy-agent-core-ry2eztft.js";
+import"../../shared/@ai-setting/roy-agent-core-f6c0nadn.js";
 import"../../shared/@ai-setting/roy-agent-core-na18zwj0.js";
 import"../../shared/@ai-setting/roy-agent-core-9bs6xrav.js";
 import"../../shared/@ai-setting/roy-agent-core-1pg0fepg.js";
 import"../../shared/@ai-setting/roy-agent-core-6masakz4.js";
+import"../../shared/@ai-setting/roy-agent-core-tr3ep81v.js";
 import"../../shared/@ai-setting/roy-agent-core-0ys85x46.js";
 import"../../shared/@ai-setting/roy-agent-core-zk2jg0v7.js";
 import"../../shared/@ai-setting/roy-agent-core-c2gbt68e.js";

package/dist/env/event-source/index.js

@@ -1,7 +1,7 @@
 import"../../shared/@ai-setting/roy-agent-core-5enxfga2.js";
 import {
   EventSourceComponent
-} from "../../shared/@ai-setting/roy-agent-core-vd9zak15.js";
+} from "../../shared/@ai-setting/roy-agent-core-e42v9bcq.js";
 import {
   BountyIMInstance,
   TimerInstance,
@@ -13,7 +13,7 @@ import {
   larkCliHandler,
   resolveBountyIMSystemPrompt,
   timerHandler
-} from "../../shared/@ai-setting/roy-agent-core-1h5bbqcg.js";
+} from "../../shared/@ai-setting/roy-agent-core-18am1h07.js";
 import {
   BUILT_IN_EVENT_SOURCE_TYPES,
   BUILT_IN_EVENT_SOURCE_TYPE_LIST,
@@ -32,7 +32,7 @@ import {
   parseCliSessionChatId
 } from "../../shared/@ai-setting/roy-agent-core-v0hf14bj.js";
 import"../../shared/@ai-setting/roy-agent-core-tm1mxttk.js";
-import"../../shared/@ai-setting/roy-agent-core-ry2eztft.js";
+import"../../shared/@ai-setting/roy-agent-core-f6c0nadn.js";
 import {
   EventStoreImpl,
   getSharedEventStore,
@@ -42,6 +42,7 @@ import {
 import"../../shared/@ai-setting/roy-agent-core-9bs6xrav.js";
 import"../../shared/@ai-setting/roy-agent-core-1pg0fepg.js";
 import"../../shared/@ai-setting/roy-agent-core-6masakz4.js";
+import"../../shared/@ai-setting/roy-agent-core-tr3ep81v.js";
 import"../../shared/@ai-setting/roy-agent-core-0ys85x46.js";
 import"../../shared/@ai-setting/roy-agent-core-zk2jg0v7.js";
 import"../../shared/@ai-setting/roy-agent-core-c2gbt68e.js";

package/dist/env/index.js

@@ -1,24 +1,24 @@
 import {
   BaseEnvironment
-} from "../shared/@ai-setting/roy-agent-core-vncwfzw5.js";
+} from "../shared/@ai-setting/roy-agent-core-6z412atw.js";
 import {
   TaskComponent
-} from "../shared/@ai-setting/roy-agent-core-e4hehcdr.js";
+} from "../shared/@ai-setting/roy-agent-core-hmdcz3g9.js";
 import"../shared/@ai-setting/roy-agent-core-amkqnyzy.js";
 import"../shared/@ai-setting/roy-agent-core-jm136jzh.js";
 import"../shared/@ai-setting/roy-agent-core-hjejpcg5.js";
 import"../shared/@ai-setting/roy-agent-core-fttgm52a.js";
 import"../shared/@ai-setting/roy-agent-core-gxzxq1sf.js";
 import"../shared/@ai-setting/roy-agent-core-8gxth0eh.js";
-import"../shared/@ai-setting/roy-agent-core-xw4wsj38.js";
+import"../shared/@ai-setting/roy-agent-core-t0ktaevq.js";
 import"../shared/@ai-setting/roy-agent-core-rn57psp0.js";
 import {
   EventSourceComponent
-} from "../shared/@ai-setting/roy-agent-core-vd9zak15.js";
+} from "../shared/@ai-setting/roy-agent-core-e42v9bcq.js";
 import {
   builtInHandlers,
   larkCliHandler
-} from "../shared/@ai-setting/roy-agent-core-1h5bbqcg.js";
+} from "../shared/@ai-setting/roy-agent-core-18am1h07.js";
 import {
   EventSourceInitHooks,
   getDefaultConfigForType,
@@ -29,11 +29,12 @@ import {
 import"../shared/@ai-setting/roy-agent-core-add1zqsh.js";
 import"../shared/@ai-setting/roy-agent-core-v0hf14bj.js";
 import"../shared/@ai-setting/roy-agent-core-tm1mxttk.js";
-import"../shared/@ai-setting/roy-agent-core-ry2eztft.js";
+import"../shared/@ai-setting/roy-agent-core-f6c0nadn.js";
 import"../shared/@ai-setting/roy-agent-core-na18zwj0.js";
 import"../shared/@ai-setting/roy-agent-core-9bs6xrav.js";
 import"../shared/@ai-setting/roy-agent-core-1pg0fepg.js";
 import"../shared/@ai-setting/roy-agent-core-6masakz4.js";
+import"../shared/@ai-setting/roy-agent-core-tr3ep81v.js";
 import"../shared/@ai-setting/roy-agent-core-0ys85x46.js";
 import"../shared/@ai-setting/roy-agent-core-zk2jg0v7.js";
 import {

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

@@ -165,17 +165,17 @@ export declare const DelegateToolParameters: z.ZodObject<{
     triggerEventId: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     description: string;
+    similar_task_ids: number[];
     prompt: string;
     subagent_type: string;
-    similar_task_ids: number[];
     reason?: string | undefined;
     timeout?: number | undefined;
     sub_session_id?: string | undefined;
     triggerEventId?: string | undefined;
 }, {
     description: string;
-    prompt: string;
     similar_task_ids: number[];
+    prompt: string;
     reason?: string | undefined;
     timeout?: number | undefined;
     subagent_type?: string | undefined;

package/dist/env/task/hooks/contexts.d.ts

@@ -18,6 +18,40 @@ export interface TaskCreateContext {
     sessionId: string;
     /** Tag 服务引用 */
     tagService: TagService;
+    /**
+     * TaskComponent 句柄（**只读能力**）。
+     *
+     * ⚠️ Task #4620：决策检测插件需要按 `similar_task_ids` 取候选任务详情，
+     *   而候选详情只有 TaskComponent 能给（store 是私有的）。这就是 #4467
+     *   契约里「实在需要就只加 1 行 `taskComponent: this`」的那一行。
+     *
+     *   插件**只读**它（getTask / listTasks / searchTasksByKeywords /
+     *   getChildTasks），不写、不删、不改任何任务 —— 决策是**只提示不拦截**。
+     *
+     *   可选（`?`）：老插件 / 测试里不注入时插件应自行跳过（fail-open）。
+     */
+    taskComponent?: TaskComponentReadonlyHandle;
+}
+/**
+ * TaskCreateContext.taskComponent 的最小只读能力面。
+ *
+ * 单独定义接口（而不是直接用 TaskComponent）是为了**避免类型循环依赖** ——
+ * TaskComponent 也引用 hook contexts。
+ */
+export interface TaskComponentReadonlyHandle {
+    getTask(id: number): Promise<any>;
+    listTasks(options?: any): Promise<{
+        tasks: any[];
+        total: number;
+    }>;
+    searchTasksByKeywords(keywords: string[], options?: any): Promise<{
+        tasks: any[];
+        total: number;
+    }>;
+    getChildTasks(taskId: number, options?: any): Promise<{
+        tasks: any[];
+        total: number;
+    }>;
 }
 /**
  * Task Create Result Hook Context

package/dist/env/task/hooks/verdict.d.ts

@@ -0,0 +1,170 @@
+/**
+ * @fileoverview Task #4467 — task_create 检测的纯函数层（verdict）
+ *
+ * 契约：/tmp/task-create-verdict-contract-v2.md
+ *
+ * 本文件只放**纯函数**（无 IO、无网络），便于单测：
+ *   - parseSimilarTaskIds   解析 context.similar_task_ids
+ *   - deriveActionFromStatus status → reopen / enhance
+ *   - buildHintText          生成可执行的 hint 文本
+ *   - assertNoLeakage        键名树泄漏断言（**不对值做正则**）
+ *   - writeDecisionHint      写 context.decision_hint
+ *   - renderCandidate*       #4107 实测的 99 字符候选模板
+ */
+import type { CreateTaskOptions } from "../types";
+/** `similar_task_ids` 元素上限（P16） */
+export declare const MAX_SIMILAR_TASK_IDS = 20;
+/** 候选渲染：key 的 title 截断长度（P13） */
+export declare const CANDIDATE_TITLE_MAX = 40;
+/** 候选渲染：value 的 description 截断长度（P14） */
+export declare const CANDIDATE_DESC_MAX = 45;
+/** 候选渲染：tags 展示上限（P15） */
+export declare const CANDIDATE_TAGS_MAX = 4;
+export type DecisionAction = "reopen" | "enhance" | "none";
+export type HintScenario = "reuse" | "reopen" | "reopen_enhance" | "remount" | "soft_reuse";
+export interface HintInput {
+    scenario: HintScenario;
+    /** 本次新建出来的任务 id（hint 里回指） */
+    newTaskId: number;
+    /** 建议复用 / 重开的目标任务 id */
+    targetTaskId?: number;
+    targetTask?: {
+        title: string;
+        status: string;
+        type: string;
+    };
+    /** remount 场景：推荐的 root id */
+    recommendedRootId?: number;
+    recommendedRootTitle?: string;
+    /** remount 场景：当前实际传入的 parent */
+    currentParentId?: number;
+    /** remount 场景：当前 parent 所属的 root 祖先 */
+    currentRootAncestorId?: number;
+    confidence?: number;
+    /** reopen_enhance 场景：是否额外带 goals 参数 */
+    includeGoals?: boolean;
+}
+export interface CandidateRenderInput {
+    id: number;
+    type: string;
+    title: string;
+}
+/** 泄漏断言的 deny-list（键名匹配，前缀语义） */
+export declare const LEAKAGE_DENY_KEYS: readonly ["expected_decision", "expected_root", "expected_", "case_id", "category", "suggested_", "recommended_", "best_match", "answer", "answer_key", "label", "should_", "target", "gold", "ground_truth", "hint", "solution", "duplicate_of", "similar_task_ids", "candidate_order", "verdict", "decision"];
+/**
+ * 从 context JSON 里解析 `similar_task_ids`。
+ *
+ * 容错规则（契约 §2.3）：
+ *   - context 缺失 / 非 JSON / 非对象 → []
+ *   - 字段缺失 / 非数组 → []
+ *   - 逐元素校验 `Number.isInteger(id) && id > 0`，非法元素丢弃
+ *   - 长度 > MAX_SIMILAR_TASK_IDS → 截断
+ *   - 重复 id → 去重（保留首次出现顺序）
+ */
+declare function parseSimilarTaskIdsImpl(contextJson: string | undefined): number[];
+/**
+ * status → 动作派生（纯规则，不需要模型）。
+ *
+ *   completed / cancelled / paused / archived → reopen
+ *   todo / active / 未知                        → enhance
+ */
+declare function deriveActionFromStatusImpl(status: string): DecisionAction;
+/**
+ * reopen 时目标 status 的派生（契约 §4.5）。
+ *   paused                        → active（恢复即继续做）
+ *   completed / cancelled / archived → todo（已终结的任务先回未开始）
+ */
+export declare function deriveReopenStatus(status: string): "todo" | "active";
+/**
+ * 新任务 id 的占位符（**裸数字**形态）。
+ *
+ * ⚠️ hint 是在 `task:before.create` 阶段写入 `context.decision_hint` 的，
+ * 此时新任务**还没有 id**。create-tool 在 `:351` 拼 output 时用真实 id 替换本占位符。
+ *
+ * 形态选择：占位符是**裸数字**（`__NEW_TASK_ID__`），因为它主要出现在
+ * `task_update(task_id=__NEW_TASK_ID__, ...)` 这种参数位置；
+ * 需要 `#id` 形态的地方（散文里的「本次已创建新任务 #__NEW_TASK_ID__」）由调用方加 `#`。
+ */
+export declare const NEW_TASK_ID_PLACEHOLDER = "__NEW_TASK_ID__";
+/**
+ * 新任务 id 的**带 # 形态**占位符（用于散文语境，如「本次已创建新任务 #__NEW_TASK_ID__」）。
+ *
+ * 与 {@link NEW_TASK_ID_PLACEHOLDER} 分开的原因：参数位置需要裸数字
+ * （`task_update(task_id=__NEW_TASK_ID__)`），散文位置需要 `#id`。
+ * 两者由 create-tool 一起替换。
+ */
+export declare const NEW_TASK_ID_HASH_PLACEHOLDER = "#__NEW_TASK_ID__";
+/**
+ * 生成 hint 文本。
+ *
+ * 每种场景都必须给出**可直接执行的 `task_update` 参数** ——
+ * 提示不可执行等于没说（这是 v1 的阻断级缺陷 B3）。
+ */
+declare function buildHintTextImpl(input: HintInput): string;
+/**
+ * 泄漏断言：**只 walk 键名树**，绝不对值做正则。
+ *
+ * 原因（契约 §4.6 + 请求契约 v1 交叉验证第 8 项）：值含用户自由文本
+ * （例如用户写「期望的 label 是 xxx」），正则会误杀用户正常输入。
+ *
+ * @throws Error 当键名树命中 deny-list 时
+ */
+declare function assertNoLeakageImpl(state: unknown, questions: unknown): void;
+/**
+ * 把 hint 写进 `options.context.decision_hint`（JSON 内字段）。
+ *
+ * @returns true 写成功；false 写失败（context 不是合法 JSON 对象）——
+ *          失败时**不修改** context，绝不破坏用户数据。
+ */
+declare function writeDecisionHintImpl(options: CreateTaskOptions, hint: string): boolean;
+/** key = `#<id> [<type>] <title 截断>` */
+export declare function renderCandidateKey(c: CandidateRenderInput): string;
+/** value = `<status 首字母>|<相对时间>|<description 截断45> [tags: 前4个]` */
+export declare function renderCandidateValue(c: {
+    id: number;
+    status: string;
+    ago: string;
+    description: string;
+    tags?: string[];
+}): string;
+/**
+ * 相对时间格式化（P17）：d / h / m；未来时间钳到 `0m`。
+ */
+export declare function formatRelativeAge(isoTimestamp: string, now?: number): string;
+/**
+ * 解析 `context.similar_task_ids`。
+ *
+ * recordParams: 只记 `contextLen` + 原始片段前 80 字（避免整段 context JSON 进 trace）
+ * recordResult: 记 id 数组（数量小，可直接看）
+ */
+export declare const parseSimilarTaskIds: typeof parseSimilarTaskIdsImpl;
+/**
+ * status → 动作派生（纯规则）。
+ *
+ * 入参是单个 status 字符串，出参是 reopen/enhance/none —— 体积小，全记。
+ */
+export declare const deriveActionFromStatus: typeof deriveActionFromStatusImpl;
+/**
+ * 生成可执行 hint 文本。
+ *
+ * ⚠️ result 是**多行长文本**（含 `task_update({...})` 模板），必须截断：
+ * 契约 §6 的 5 种模板最长约 800 字符，这里只留前 240 字符 + 总长度，
+ * 完整文本可通过 `debug span` 的 attributes.params 拿到 HintInput 反推。
+ */
+export declare const buildHintText: typeof buildHintTextImpl;
+/**
+ * 泄漏断言 —— **最关键的一条 trace**。
+ *
+ * 为什么必须可观测：泄漏断言是「请求体永不含答案」的唯一守门人。
+ * 如果它静默跳过/静默失败，trace 里会完全看不出来（无 span = 无证据）。
+ * 这里用 `errorIf` 让 span 在抛错时显式标 ERROR。
+ */
+export declare const assertNoLeakage: typeof assertNoLeakageImpl;
+/**
+ * 写 `options.context.decision_hint`。
+ *
+ * 返回值是 boolean（写成功/失败），用 `errorIf` 把 false 标成 span ERROR ——
+ * 否则"写失败导致 hint 静默丢失"在 trace 里完全看不出来。
+ */
+export declare const writeDecisionHint: typeof writeDecisionHintImpl;
+export {};

package/dist/env/task/index.js

@@ -5,7 +5,7 @@ import {
   TaskPriorityEnum,
   TaskStatusEnum,
   TaskTypeEnum
-} from "../../shared/@ai-setting/roy-agent-core-e4hehcdr.js";
+} from "../../shared/@ai-setting/roy-agent-core-hmdcz3g9.js";
 import"../../shared/@ai-setting/roy-agent-core-amkqnyzy.js";
 import"../../shared/@ai-setting/roy-agent-core-jm136jzh.js";
 import"../../shared/@ai-setting/roy-agent-core-hjejpcg5.js";
@@ -14,7 +14,7 @@ import"../../shared/@ai-setting/roy-agent-core-gxzxq1sf.js";
 import {
   TaskEntityEventTypes
 } from "../../shared/@ai-setting/roy-agent-core-8gxth0eh.js";
-import"../../shared/@ai-setting/roy-agent-core-xw4wsj38.js";
+import"../../shared/@ai-setting/roy-agent-core-t0ktaevq.js";
 import"../../shared/@ai-setting/roy-agent-core-rn57psp0.js";
 import"../../shared/@ai-setting/roy-agent-core-na18zwj0.js";
 import {
@@ -23,6 +23,7 @@ import {
 } from "../../shared/@ai-setting/roy-agent-core-9bs6xrav.js";
 import"../../shared/@ai-setting/roy-agent-core-1pg0fepg.js";
 import"../../shared/@ai-setting/roy-agent-core-6masakz4.js";
+import"../../shared/@ai-setting/roy-agent-core-tr3ep81v.js";
 import"../../shared/@ai-setting/roy-agent-core-07fvy74y.js";
 import"../../shared/@ai-setting/roy-agent-core-qxnbvgwe.js";
 import"../../shared/@ai-setting/roy-agent-core-c1v263jn.js";

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

@@ -6,11 +6,12 @@ import {
   searchTasksTool,
   treeTasksTool,
   updateTaskTool
-} from "../../../shared/@ai-setting/roy-agent-core-xw4wsj38.js";
+} from "../../../shared/@ai-setting/roy-agent-core-t0ktaevq.js";
 import {
   createOperationTool,
   listOperationsTool
 } from "../../../shared/@ai-setting/roy-agent-core-rn57psp0.js";
+import"../../../shared/@ai-setting/roy-agent-core-tr3ep81v.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/__e2e__/laya-chain-validate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Task #4620 — 全链路验证：真实 layaRenderer + 真实 LayaDecisionPort
+ *
+ * 目的：证明「roy-agent 侧渲染 + client + laya 服务」这条完整链路
+ * 在**有 ground truth 的 held-out 集**上能复现 #4614 报告的准确率。
+ *
+ * 这比单点验证强得多：
+ *   - 只测 client → 只能证明协议通
+ *   - 只测渲染 → 只能证明格式对
+ *   - 全链路 → 证明「roy-agent 发的请求」与「训练分布」一致，且结果可复现
+ *
+ * 跑法（worktree 的 packages/core 下）：
+ *   bun run src/env/task/plugins/__e2e__/laya-chain-validate.ts
+ */
+export {};

package/dist/env/task/plugins/__e2e__/laya-decision-branches.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Task #4627 — Laya 决策插件 **全分支回归脚本**（可重跑）
+ *
+ * 用法：
+ * ```bash
+ * cd packages/core && bun run src/env/task/plugins/__e2e__/laya-decision-branches.ts
+ * # 或从仓库根
+ * bun run packages/core/src/env/task/plugins/__e2e__/laya-decision-branches.ts
+ * ```
+ *
+ * ⚠️ 两种驱动模式：
+ *   - **mock 模式**（默认）：注入假 port，**确定性**，不依赖 Laya 服务 → 断言 7 个分支的判定逻辑
+ *   - **live 模式**（`--live`）：真调本机 Laya 服务（http://127.0.0.1:8901）
+ *
+ * 每个场景打印：场景名 / 实测值 / 断言结果 / 延迟(ms)，最后给出汇总。
+ * 退出码 0 = 全部通过，1 = 有失败。
+ */
+export {};

package/dist/env/task/plugins/__e2e__/laya-decision-e2e-live.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Task #4632 — Laya 决策插件 **真实端到端回归脚本**（真服务 + 真任务库）
+ *
+ * ⚠️⚠️⚠️ 与 `laya-decision-branches.ts` 的本质区别 ⚠️⚠️⚠️
+ *
+ *   branches.ts  → 场景 1a/1b/2/3/4/6/7 **全是 mock port**（直接返回构造好的答案），
+ *                  只有场景 8 是 live 且只有 1 个 case、不强制断言 hint。
+ *   本脚本      → **全程真实**：真读 auth.json → 真 HTTP 打 Laya 服务 →
+ *                  真走 task_create → 候选来自**真实 tasks.db 的真实任务**。
+ *
+ * 跑法：
+ * ```bash
+ * cd <worktree>/packages/core
+ * bun run src/env/task/plugins/__e2e__/laya-decision-e2e-live.ts
+ * ```
+ *
+ * 前置：
+ *   - Laya 服务在线（auth.json 的 providers['laya-decision'].baseURL，health 200）
+ *   - 真实任务库 `~/.local/share/roy-agent/tasks.db` 存在（4188 个真实任务）
+ *   - 金标准 `laya-train/data/gold-split.json`（unseen 25 个真实父子对）
+ *
+ * ⚠️ 本脚本**只写临时 sqlite**（tmpdir），**不碰真实 tasks.db**；
+ *    只**读**真实 tasks.db 取候选内容。
+ *
+ * 退出码 0 = 全绿；1 = 有失败。
+ */
+export {};

package/dist/env/task/plugins/__e2e__/laya-e2e-verify.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview Task #4620 — 端到端验证脚本（真调本地 laya 服务 + 真 task_create）
+ *
+ * 目的：证明「task_create 带上 similar_task_ids → output 里真的出现 hint」这条链路
+ * 在**真实服务 + 真实 TaskComponent + 真实 create-tool** 下是通的。
+ *
+ * 跑法：
+ *   cd <worktree>/packages/core
+ *   bun run src/env/task/plugins/__e2e__/laya-e2e-verify.ts
+ *
+ * 前置：
+ *   - laya-serve 已在 http://127.0.0.1:8901 跑着（scripts/serve_laya.sh）
+ *   - ~/.roy-agent/auth.json 有 providers['laya-decision']
+ *
+ * ⚠️ 本脚本**只写临时 sqlite**（tmpdir），不碰真实 tasks.db。
+ */
+export {};

package/dist/env/task/plugins/decision-hint-plugin.d.ts

@@ -0,0 +1,144 @@
+/**
+ * @fileoverview Task #4467 — task:before.create 的 decision 检测插件
+ *
+ * 契约：/tmp/task-create-verdict-contract-v2.md
+ *
+ * 形态：**只提示，不拦截**。
+ *   创建照常发生，插件只把建议文本写进 `ctx.options.context.decision_hint`，
+ *   由调用方 agent 自己决定是否调 `task_update` 修正。
+ *
+ * 门槛（契约 §4.1）：
+ *   候选 0 个 → 放行，不调模型
+ *   候选 1 个 → 不调模型，直接给「建议复用 #id」hint
+ *   候选 ≥2 个 → 调 decision model 做 Stage A 判定
+ *
+ * Stage A 判「新建 vs 复用」；Stage B（仅当新建）判「新建 root vs 挂到某 root」。
+ * status → 动作（reopen / enhance）是**纯规则**推导，不需要模型。
+ */
+import type { DecisionPort, DecisionRequest, DecisionAnswer } from "./decision-port";
+import type { TaskCreateContext } from "../hooks/contexts";
+import type { Task } from "../types";
+/** 只读能力面 —— 避免与 TaskComponent 产生类型循环依赖（契约 §3.3） */
+export interface TaskComponentReadonly {
+    getTask(id: number): Promise<Task | undefined>;
+    listTasks(options?: any): Promise<{
+        tasks: Task[];
+        total: number;
+    }>;
+    searchTasksByKeywords(keywords: string[], options?: any): Promise<{
+        tasks: Task[];
+        total: number;
+    }>;
+    getChildTasks(taskId: number, options?: any): Promise<{
+        tasks: Task[];
+        total: number;
+    }>;
+}
+export interface DecisionHintPluginOptions {
+    /** 注入的决策端口（测试用假 port；生产用 SystemOneDecisionPort） */
+    decisionPort: DecisionPort;
+    /** 上下文读取（生产用 getEnvContextOrEmpty().parentTaskId） */
+    envParentTaskIdProvider?: () => number | undefined | null;
+    /**
+     * 渲染策略 —— 决定 state / criteria / choice 映射的形态。
+     *
+     * ⚠️ Task #4620：**不同载体的训练格式不同，必须显式选**。
+     *   - `systemone`（默认）：阿里百炼 systemone 的习惯 —— state 是 JSON 对象，
+     *     criteria key = `#<id> [<type>] <title>`（#4107 模板）
+     *   - `laya`：#4614 的 Laya 微调模型训练时的格式 —— state 是中文文本
+     *     （【新任务标题】/【新任务描述】/【候选任务】），criteria key = `#<id> <title[:50]>`
+     *
+     * 实测（200 条 held-out，laya-train/scripts/format_probe.py）：
+     *   laya 格式 79.00% vs systemone 格式 46.50% → **用 laya 载体必须选 laya 渲染**。
+     */
+    renderer?: DecisionRenderer;
+    /**
+     * 「建议复用」硬提示的置信度门禁（默认 0.6 = #4467 Q4 的 routing 档）。
+     *
+     * ⚠️ Task #4620：Laya 载体用 **0.85**（#4467 Q4 的「不新建」破坏性档）。
+     *   896 条实测：thr=0.85 → 提示精确率 80.5%（coverage 28.7%），
+     *   thr=0.9 → 84.9%，thr=0.95 → 87.0%。
+     */
+    reuseThreshold?: number;
+    /**
+     * 低于此置信度**完全不出提示**（默认 0.4）。
+     *
+     * ⚠️ Task #4620：Laya 载体把它设成与 `reuseThreshold` 同值（0.85），
+     *   语义就是「< 0.85 一律不出提示」（任务书的硬要求）。
+     */
+    softHintThreshold?: number;
+    /**
+     * 「只有 1 个候选 → 不调模型，直接给建议复用 hint」的捷径。
+     *
+     * 默认 true（#4467 契约 §4.1）。Laya 载体设成 false —— 快捷路径**没有置信度**，
+     * 与「必须 confidence 门禁 ≥ 0.85」冲突，所以让它也走模型。
+     */
+    singleCandidateShortcut?: boolean;
+}
+/**
+ * 渲染策略接口 —— 把「候选 → state/questions」和「choice → task id」两件事
+ * 抽象出来，让同一套判定逻辑能服务不同载体的训练分布。
+ */
+export interface DecisionRenderer {
+    /** 渲染 Stage A 的请求 */
+    buildStageA(input: {
+        title: string;
+        description: string;
+        goals: string;
+        tags: string[];
+        projectPath: string;
+        candidates: Task[];
+        now: number;
+    }): DecisionRequest;
+    /** 把模型回的 choice 映射回候选 task id（映射不到返回 undefined） */
+    matchChoice(choice: string, candidates: Task[]): number | undefined;
+}
+export declare class DecisionHintPlugin {
+    readonly name = "decision-hint";
+    readonly version = "1.0.0";
+    readonly description = "Task #4467 \u2014 task:before.create \u7684 decision \u68C0\u6D4B\uFF1A\u5224\u5B9A\u65B0\u5EFA/\u590D\u7528 + root/\u5B50\u6302\u8F7D\uFF0C\u53EA\u63D0\u793A\u4E0D\u62E6\u622A";
+    private readonly decisionPort;
+    private readonly envParentTaskIdProvider;
+    private readonly renderer;
+    private readonly reuseThreshold;
+    private readonly softHintThreshold;
+    private readonly singleCandidateShortcut;
+    constructor(options: DecisionHintPluginOptions);
+    /**
+     * hook 入口 —— 任何异常都不得抛出（契约 §8 总原则）。
+     *
+     * ⚠️ 形状兼容（交叉验证 P1）：框架 `HookManager` 派发的是 `HookContext`
+     * （载荷在 `ctx.data`，见 `hook/hook-manager.ts` createContext），而本插件
+     * 内部按裸 `TaskCreateContext` 工作。这里两种形状都接受，避免按标准
+     * `registerHook({ execute: (ctx) => plugin.execute(ctx) })` 接入时静默失效。
+     */
+    execute(ctx: TaskCreateContext | {
+        data: TaskCreateContext;
+    }): Promise<void>;
+    private run;
+    private fallbackCandidates;
+    private runStageA;
+    private buildStageARequest;
+    private runStageB;
+    private collectRootCandidates;
+    /**
+     * 解析 root 祖先链（**防环** —— tasks.db 里存在手改 parent_task_id 造成的环）。
+     */
+    private resolveRootAncestor;
+    private reuseHintInput;
+}
+/**
+ * Task #4627 — 选取**门禁用的置信度**（#302 的核心）。
+ *
+ * ⚠️ `confidence` 是**归一化熵**，**不是** Jev 公式置信度。
+ *   laya 同时返回 `confidence`（熵）与 `x_jev_confidence`（Jev 公式），
+ *   60 条实测里 20 条差异 > 0.05 —— 读错字段会让门禁形同虚设。
+ *
+ *   选源顺序：`x_jev_confidence` → `answer_confidence` → `confidence`。
+ *
+ *   ⚠️ 为什么不在载体侧做完就算：`LayaDecisionPort.normalize()` 已经把
+ *   `confidence` 覆盖成选源后的值，但那是**载体专属**的归一化 —— 换载体
+ *   （systemone 就没有 x_jev_confidence）就失效。判定层自己再选一次源，
+ *   保证「门禁永远读 Jev 公式置信度」这条不变量与载体解耦。
+ */
+export declare function pickGateConfidence(answer: DecisionAnswer | undefined): number;