@ai-setting/roy-agent-core 1.7.52 → 1.7.55

package/dist/env/task/registry-hook-installer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Registry Hook Installer — wires TaskCreationRegistry to the
+ * TaskComponent hook system so create/update/complete/delete events feed
+ * the registry automatically.
+ *
+ * Use this when you want sub-agent delegate prompts to surface recent
+ * task candidates. See docs/design/task-reuse-context.md for the full
+ * design rationale.
+ *
+ * The installer returns a handle with `uninstall()` for clean teardown
+ * (tests + plugin shutdown).
+ */
+import type { TaskComponent } from "./task-component";
+import type { TaskCreationRegistry, TaskRecordSource } from "./task-creation-registry";
+export interface InstallOptions {
+    /**
+     * Returns the sessionId to record as source.sessionId. If omitted, the
+     * registry record's source.sessionId will be undefined.
+     *
+     * Why an explicit provider? Hook contexts don't always carry a sessionId
+     * (e.g. AFTER_UPDATE may run from background code paths). The provider
+     * lets the caller inject the correct value from the call site where it's
+     * known (e.g. delegate-tool's executeWithAbort).
+     */
+    sessionIdProvider?: () => string | undefined;
+    /** Default: "registry-hook-installer" */
+    hookName?: string;
+    /** Default: 100 (medium priority — runs after notifications) */
+    priority?: number;
+    /** Optional metadata to attach (e.g. { subagentType: "roy" }) */
+    staticSource?: Omit<TaskRecordSource, "sessionId">;
+}
+export interface InstallHandle {
+    uninstall(): void;
+}
+/**
+ * Subscribe a TaskCreationRegistry to a TaskComponent's lifecycle hooks.
+ *
+ * The registry is observation-only; this installer never mutates tasks.
+ * Errors thrown by registry calls are caught and logged so they can never
+ * break the host task lifecycle.
+ */
+export declare function installTaskCreationRegistryHooks(taskComponent: TaskComponent, registry: TaskCreationRegistry, options?: InstallOptions): InstallHandle;

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

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Task Storage Index
+ */
+export { SQLiteTaskStore, type TaskStore } from "./sqlite-task-store";
+export { getDefaultTaskDbPath, getDefaultDataDir } from "./sqlite-task-store";

package/dist/env/task/storage/migrations/001_add_project_path_context.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Task Migration: Add project_path and context columns
+ *
+ * Migration ID: 001_add_project_path_context
+ * Description: Add project_path and context columns to task table
+ * Date: 2026-05-12
+ */
+/**
+ * Run migration to add project_path and context columns
+ *
+ * This migration is idempotent - safe to run multiple times.
+ * Existing databases will have columns added if missing.
+ */
+export declare function runMigration(dbPath: string): void;

package/dist/env/task/storage/migrations/002_add_task_type.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Task Migration: Add type column
+ *
+ * Migration ID: 002_add_task_type
+ * Description: Add type column to task table (normal/cycle/longterm)
+ * Date: 2026-06-04
+ */
+/**
+ * Run migration to add type column
+ *
+ * This migration is idempotent - safe to run multiple times.
+ * Existing databases will have the column added if missing.
+ */
+export declare function runMigration(dbPath: string): void;

package/dist/env/task/storage/migrations/003_add_process_description.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Task Migration: Add process_description column to task_operation
+ *
+ * Migration ID: 003_add_process_description
+ * Description: Add process_description column to task_operation table.
+ *              用于记录达成节点状态所采用的策略 + 工具步骤的过程概要，
+ *              区别于 action_description（状态/结果描述）。
+ *              字符范围 100-150（应用层 schema 校验，本字段不做 DB 长度约束）。
+ * Date: 2026-07-20
+ */
+/**
+ * Run migration to add process_description column.
+ *
+ * Idempotent: 重复执行安全。
+ * - 已存在 process_description 列：跳过 ALTER
+ * - 不存在：添加 TEXT NOT NULL DEFAULT ''
+ *
+ * 默认值空字符串且禁止 NULL（与应用层 rowToOperation 的空字符串语义一致）。
+ */
+export declare function runMigration(dbPath: string): void;

package/dist/env/task/storage/migrations/004_rename_action_to_milestone.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Task Migration 004: Rename action_* columns to milestone_*
+ *
+ * Migration ID: 004_rename_action_to_milestone
+ * Description: Rename task_operation.action_type/action_title/action_description
+ *              to milestone_type/milestone_title/milestone_description.
+ *              这是 task_operation 状态语义重构的核心 schema 迁移。
+ *              ActionTypeEnum 包含 create/progress/milestone/problem/solution/
+ *              decision/review/completed，本身就是里程碑类型枚举；
+ *              action_* 命名偏"动作/行为层"，不能准确表达"这一刻达到的
+ *              里程碑/状态"。新命名 milestone_* 与 process_description（过程维度）
+ *              形成清晰的"状态/里程碑 + 过程"双维度分工。
+ *
+ * 数据保留：
+ * - SQLite ALTER TABLE RENAME COLUMN 自带数据保留
+ * - 迁移完成后原有 action_* 列内容自动落到 milestone_* 列
+ *
+ * 兼容：
+ * - task_operation 行旧字段 action_* 不可再读（已重命名）
+ * - 旧 API 调用方仍能通过 rowToOperation 同时拿到 milestone_* + action_* (deprecated alias)
+ *
+ * Date: 2026-07-21
+ */
+/**
+ * Run migration 004 on the given database file.
+ *
+ * Idempotent:
+ * - 重复执行安全：检查 milestone_* 列是否已存在，已存在则跳过。
+ *
+ * Algorithm:
+ * - 对 RENAME_MAP 每对 (oldName, newName)：
+ *   - if oldName exists AND newName does NOT exist → ALTER TABLE RENAME COLUMN
+ *   - else skip
+ *
+ * @param dbPath SQLite database file path
+ */
+export declare function runMigration(dbPath: string): void;

package/dist/env/task/storage/migrations/005_convert_blob_description_to_text.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Task Migration 005: Convert BLOB description to TEXT
+ *
+ * Migration ID: 005_convert_blob_description_to_text
+ * Description: Some tasks (notably Task #2084 with 15619-byte markdown
+ *              description) had their `description` column stored as BLOB
+ *              instead of TEXT. SQLite type affinity rules allow this when
+ *              an INSERT/UPDATE uses a BLOB literal. The result is that
+ *              better-sqlite3 / bun:sqlite return a Buffer object (truthy,
+ *              no toLowerCase) instead of a string, crashing
+ *              searchTasksByKeywords at line 1082.
+ *
+ *              The rowToTask defensive String() coercion (Task #2226) is
+ *              the load-bearing fix. This migration is a data-hygiene pass
+ *              that converts any existing BLOB descriptions to TEXT in
+ *              place so the column's declared type matches the storage
+ *              class on every row.
+ *
+ * Data preservation:
+ * - CAST(description AS TEXT) decodes the bytes as UTF-8 and stores
+ *   the result back into the same column. The column's type affinity
+ *   (TEXT) is then respected for the new value.
+ * - Original content is preserved (the Buffer payload was the same UTF-8
+ *   bytes that a TEXT column would have stored).
+ *
+ * Idempotent:
+ * - WHERE typeof(description) = 'blob' gates the update; re-running the
+ *   migration on an already-migrated DB is a no-op.
+ *
+ * Date: 2026-07-21
+ */
+/**
+ * Run migration 005 on the given database file.
+ *
+ * Algorithm:
+ *  1. Open DB.
+ *  2. Verify the `task` table exists (fresh DBs may not have it yet).
+ *  3. Count rows where typeof(description) = 'blob' (BLOB-stored values).
+ *  4. If count > 0, run UPDATE task SET description = CAST(description AS TEXT)
+ *     WHERE typeof(description) = 'blob'.
+ *  5. Close DB.
+ *
+ * @param dbPath SQLite database file path
+ * @returns Migration result: { blobCountBefore, blobCountAfter, ran }
+ */
+export interface Migration005Result {
+    blobCountBefore: number;
+    blobCountAfter: number;
+    ran: boolean;
+}
+export declare function runMigration(dbPath: string): Migration005Result;

package/dist/env/task/storage/sqlite-task-store.d.ts

@@ -0,0 +1,241 @@
+/**
+ * @fileoverview SQLite Task Store
+ *
+ * SQLite-based implementation of TaskStore.
+ *
+ * 根据运行环境自动选择 SQLite 实现：
+ * - Bun 运行时：使用 bun:sqlite
+ * - Node.js/Electron：使用 better-sqlite3
+ *
+ * 参考 Session SQLiteStore 实现模式：
+ * - 内存缓存提高性能
+ * - 默认路径：~/.local/share/roy-agent/tasks.db
+ */
+/**
+ * 创建兼容的 Database 实例
+ *
+ * bun:sqlite 和 better-sqlite3 的 API 略有不同：
+ * - bun:sqlite 有 db.run() 方法
+ * - better-sqlite3 没有 db.run()，需要用 db.exec() 或 db.prepare().run()
+ *
+ * 此函数确保两种实现都有 run() 方法
+ */
+export declare function createCompatibleDatabase(path: string): any;
+import type { Task, TaskOperation, TaskTag, CreateTaskOptions, UpdateTaskOptions, ListTasksOptions, TaskListResult, SearchTasksOptions, CreateOperationOptions, ListOperationsOptions } from "../types";
+import type { ListTagsOptions, SearchTagsOptions } from "../tag-service";
+/**
+ * Get default data directory for task storage
+ */
+declare function getDefaultDataDir(): string;
+/**
+ * Get default database path for task storage
+ */
+declare function getDefaultTaskDbPath(): string;
+export interface TaskStore {
+    createTask(options: CreateTaskOptions): Promise<Task>;
+    getTask(id: number): Promise<Task | undefined>;
+    updateTask(id: number, options: UpdateTaskOptions): Promise<Task | undefined>;
+    deleteTask(id: number): Promise<boolean>;
+    listTasks(options?: ListTasksOptions): Promise<TaskListResult>;
+    /**
+     * 按 session_id 反查该 session 里创建的第一个 task（用于 sub-session → task 的
+     * 确定性映射：sub-agent 的 task_create 用 sessionId=sub-session id）。
+     */
+    getTaskIdBySessionId(sessionId: string): Promise<number | undefined>;
+    createOperation(options: CreateOperationOptions): Promise<TaskOperation>;
+    getOperation(id: number): Promise<TaskOperation | undefined>;
+    updateOperation(id: number, updates: {
+        milestoneTitle?: string;
+        milestoneDescription?: string;
+        processDescription?: string;
+        actionTitle?: string;
+        actionDescription?: string;
+    }): Promise<TaskOperation | undefined>;
+    deleteOperation(id: number): Promise<boolean>;
+    listOperations(options: ListOperationsOptions): Promise<TaskOperation[]>;
+    createTag(name: string): Promise<TaskTag>;
+    getTag(id: number): Promise<TaskTag | undefined>;
+    getTagByName(name: string): Promise<TaskTag | undefined>;
+    listTags(options?: ListTagsOptions): Promise<TaskTag[]>;
+    searchTags(options: SearchTagsOptions): Promise<TaskTag[]>;
+    deleteTag(id: number): Promise<boolean>;
+    addTagsToTask(taskId: number, tagIds: number[]): Promise<void>;
+    removeTagsFromTask(taskId: number, tagIds: number[]): Promise<void>;
+    getTagsForTask(taskId: number): Promise<TaskTag[]>;
+    getTaskIdsByTags(tagNames: string[]): Promise<number[]>;
+    updateTaskTags(taskId: number, tagNames: string[]): Promise<void>;
+    /**
+     * Search tasks by keywords (tags, description, goals, operations).
+     * Returns { tasks, total } for pagination.
+     *
+     * 支持 depth 层级检索（参见 SearchTasksOptions.depth）。
+     */
+    searchTasksByKeywords(keywords: string[], options?: SearchTasksOptions): Promise<TaskListResult>;
+    /** Find similar tasks using new keywords search */
+    findSimilarTasksByKeywords(keywords: string[], options?: {
+        limit?: number;
+        excludeTaskId?: number;
+    }): Promise<Task[]>;
+    /**
+     * 获取任务的子树（包含所有后代）
+     *
+     * @param taskId 起始任务 ID
+     * @param depth 层级深度，-1 表示无限层级（默认）
+     * @returns 所有后代任务的扁平列表（不含 taskId 本身）
+     *
+     * 实现：BFS 逐层展开 children，每层 +1。depth 限制 BFS 展开层数。
+     */
+    getTaskTree(taskId: number, depth?: number): Promise<Task[]>;
+    /**
+     * 获取直接子任务（一层）。
+     */
+    getChildTasks(taskId: number, options?: ListTasksOptions): Promise<TaskListResult>;
+    findSimilarTasks(taskId: number, limit?: number): Promise<Task[]>;
+    searchTasks(query: string, limit?: number): Promise<Task[]>;
+    /**
+     * Task #4230 follow-up：按 context 里的字符串值反查 task
+     *
+     * 用途：已知一个飞书 chatId，反查"哪些 task 把这个群写进了自己的 context"
+     * （用于判定"这个群是不是某个 task 的专属群"）。
+     * 只用 LIKE 做粗筛，精确字段名/语义判断交给调用方（card-chat-routing）。
+     */
+    findTasksByContextValue(value: string, limit?: number): Promise<Task[]>;
+    close(): void;
+}
+/**
+ * SQLite-based Task Store
+ *
+ * 参考 Session SQLiteStore 实现模式：
+ * - 使用 bun:sqlite 内置模块
+ * - 内存缓存提高性能
+ * - 默认路径：~/.local/share/roy-agent/tasks.db
+ */
+export declare class SQLiteTaskStore implements TaskStore {
+    private db;
+    private dbPath;
+    private initialized;
+    private tasksCache;
+    private operationsCache;
+    constructor(dbPath?: string);
+    private initialize;
+    createTask(options: CreateTaskOptions): Promise<Task>;
+    getTask(id: number): Promise<Task | undefined>;
+    updateTask(id: number, options: UpdateTaskOptions): Promise<Task | undefined>;
+    deleteTask(id: number): Promise<boolean>;
+    listTasks(options?: ListTasksOptions): Promise<TaskListResult>;
+    /**
+     * 按层级深度检索任务（BFS 展开）
+     *
+     * - depth === 0：只查根任务（parent_task_id IS NULL）
+     * - depth === 1：根 + 一层子任务
+     * - depth >= 2：根 + N 层子任务
+     *
+     * 支持 status / priority / type 过滤（在每层展开时复用）。
+     * limit/offset 在合并所有层级结果后应用（注意：total 是展开后的总数）。
+     */
+    private listTasksByDepth;
+    /**
+     * 获取任务的子树（包含所有后代）
+     *
+     * @param taskId 起始任务 ID
+     * @param depth 层级深度，-1 表示无限层级（默认）
+     * @returns 所有后代任务的扁平列表（不含 taskId 本身）
+     */
+    getTaskTree(taskId: number, depth?: number): Promise<Task[]>;
+    /**
+     * 获取直接子任务（一层）
+     */
+    getChildTasks(taskId: number, options?: ListTasksOptions): Promise<TaskListResult>;
+    createOperation(options: CreateOperationOptions): Promise<TaskOperation>;
+    getOperation(id: number): Promise<TaskOperation | undefined>;
+    updateOperation(id: number, updates: {
+        milestoneTitle?: string;
+        milestoneDescription?: string;
+        processDescription?: string;
+        actionTitle?: string;
+        actionDescription?: string;
+    }): Promise<TaskOperation | undefined>;
+    deleteOperation(id: number): Promise<boolean>;
+    listOperations(options: ListOperationsOptions): Promise<TaskOperation[]>;
+    /**
+     * 按 session_id 反查该 session 创建的第一个 task。
+     *
+     * task 表本身不存 session_id，但 createTask 会写一条 milestone_type='create'
+     * 的 task_operation（带 session_id）。sub-agent 的 task_create 用
+     * sessionId=sub-session id，所以这里能确定性地把 sub-session 映射回它创建的 task，
+     * 不依赖易失的 EnvContext.currentTaskId（会被 task_complete 清空）或结果文本正则。
+     */
+    getTaskIdBySessionId(sessionId: string): Promise<number | undefined>;
+    private rowToTask;
+    /**
+     * 安全解析 tags 字段。
+     *
+     * 历史背景：Bug 修复 Task #4033 — 任务 [HTML 样式重构] v33 → v34 的 tags 字段
+     * 被存成了 CSV 字符串 `'html-styling, css-refactor, v34, feishu, slides'` 而非
+     * 合法 JSON 数组，导致裸 `JSON.parse` 抛 SyntaxError，`tasks list` 命令
+     * `ORDER BY updated_at DESC` 第一条就挂掉，整个 CLI 不显示任何任务。
+     *
+     * 策略（按优先级 fallback，不抛错）：
+     *   1. null/undefined/空串 → undefined
+     *   2. 合法 JSON 数组 → 原样返回
+     *   3. 合法 JSON 但不是数组（如 "tag1" 单字符串）→ 包成单元素数组（向后兼容）
+     *   4. 非法 JSON（CSV / 纯文本）→ 当作单个 tag 字符串，包成单元素数组
+     *   5. 其他类型（数字、对象等）→ undefined
+     */
+    private static parseTagsSafely;
+    private rowToOperation;
+    createTag(name: string): Promise<TaskTag>;
+    getTag(id: number): Promise<TaskTag | undefined>;
+    getTagByName(name: string): Promise<TaskTag | undefined>;
+    listTags(options?: ListTagsOptions): Promise<TaskTag[]>;
+    searchTags(options: SearchTagsOptions): Promise<TaskTag[]>;
+    deleteTag(id: number): Promise<boolean>;
+    addTagsToTask(taskId: number, tagIds: number[]): Promise<void>;
+    removeTagsFromTask(taskId: number, tagIds: number[]): Promise<void>;
+    getTagsForTask(taskId: number): Promise<TaskTag[]>;
+    getTaskIdsByTags(tagNames: string[]): Promise<number[]>;
+    updateTaskTags(taskId: number, tagNames: string[]): Promise<void>;
+    /**
+     * Search tasks by keywords list
+     * Searches in: tags (JSON), description, goals_and_expected_deliverables, operations
+     *
+     * 支持 depth 参数：depth=0 只匹配根任务（AND 关系），depth=1 根+子，依此类推
+     */
+    searchTasksByKeywords(keywords: string[], options?: SearchTasksOptions): Promise<TaskListResult>;
+    /**
+     * 内部方法：BFS 展开根任务到指定深度，返回所有可达任务 ID 集合
+     *
+     * - depth === 0：只根任务 ID
+     * - depth >= 1：根 + 1..N 层所有后代 ID
+     */
+    private collectTaskIdsByDepth;
+    /**
+     * Find similar tasks by keywords
+     * Excludes the target task and sorts by relevance
+     * Default limit is 5 to keep prompt concise
+     *
+     * Note: Returns only the tasks array (not {tasks, total}) for backwards
+     * compatibility with internal callers (e.g. plugin similar-task injection).
+     */
+    findSimilarTasksByKeywords(keywords: string[], options?: {
+        limit?: number;
+        excludeTaskId?: number;
+    }): Promise<Task[]>;
+    findSimilarTasks(taskId: number, limit?: number): Promise<Task[]>;
+    searchTasks(query: string, limit?: number): Promise<Task[]>;
+    /**
+     * Task #4230 follow-up：按 context 值反查 task（LIKE 粗筛）
+     *
+     * 用途：已知一个飞书 chatId，反查"哪些 task 把这个群写进了自己的 context"
+     * （用于判定"这个群是不是某个 task 的专属群"）。精确的字段名 / 语义判断
+     * 交给调用方（card-chat-routing），这里只做粗筛。
+     *
+     * @param value 目标值（通常是一个 chatId）
+     * @param limit 最多返回条数（默认 50）
+     */
+    findTasksByContextValue(value: string, limit?: number): Promise<Task[]>;
+    private rowToTag;
+    private syncTaskTagsJson;
+    close(): Promise<void>;
+}
+export { getDefaultTaskDbPath, getDefaultDataDir };

package/dist/env/task/tag-service.d.ts

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview TagService - Tag 池管理服务
+ *
+ * 提供 Tag 的 CRUD、Tag 与 Task 关联、类似任务检索能力
+ *
+ * 设计原则：
+ * - Tag 池模式：新 Tag 从池中选取，无合适则新增
+ * - 混合存储：Task.tags JSON 快速读取 + Tag 表高效检索
+ */
+import type { Task, TaskTag } from "./types";
+import type { TaskStore } from "./storage/sqlite-task-store";
+export interface ListTagsOptions {
+    limit?: number;
+    offset?: number;
+    orderBy?: "count" | "name" | "created_at";
+}
+export interface SearchTagsOptions {
+    query: string;
+    limit?: number;
+}
+export interface TagService {
+    /**
+     * 创建 Tag（如果已存在则返回现有 Tag）
+     */
+    createTag(name: string): Promise<TaskTag>;
+    /**
+     * 获取 Tag by ID
+     */
+    getTag(id: number): Promise<TaskTag | undefined>;
+    /**
+     * 获取 Tag by Name
+     */
+    getTagByName(name: string): Promise<TaskTag | undefined>;
+    /**
+     * 列出所有 Tag
+     */
+    listTags(options?: ListTagsOptions): Promise<TaskTag[]>;
+    /**
+     * 搜索 Tag（模糊匹配）
+     */
+    searchTags(options: SearchTagsOptions): Promise<TaskTag[]>;
+    /**
+     * 删除 Tag（同时删除所有关联）
+     */
+    deleteTag(id: number): Promise<boolean>;
+    /**
+     * 给 Task 添加 Tags
+     */
+    addTagsToTask(taskId: number, tagIds: number[]): Promise<void>;
+    /**
+     * 从 Task 移除 Tags
+     */
+    removeTagsFromTask(taskId: number, tagIds: number[]): Promise<void>;
+    /**
+     * 获取 Task 的所有 Tags
+     */
+    getTagsForTask(taskId: number): Promise<TaskTag[]>;
+    /**
+     * 根据 Tag 名称获取关联的 Task IDs
+     */
+    getTaskIdsByTags(tagNames: string[]): Promise<number[]>;
+    /**
+     * 根据关键词列表搜索 Task（检索 tags、description、goals、operations）
+     * 这是新的核心检索方法
+     */
+    searchTasksByKeywords(keywords: string[], options?: {
+        limit?: number;
+        excludeTaskId?: number;
+    }): Promise<Task[]>;
+    /**
+     * 根据关键词查找类似 Task（排除自身，按相关性排序）
+     * 这是新的核心检索方法
+     */
+    findSimilarTasksByKeywords(keywords: string[], options?: {
+        limit?: number;
+        excludeTaskId?: number;
+    }): Promise<Task[]>;
+    /**
+     * 同步 Tags 到 Task（根据 tag 名称列表）
+     * - 查找或创建 Tag
+     * - 更新关联关系
+     * - 更新 task.tags JSON 字段
+     */
+    syncTagsToTask(taskId: number, tagNames: string[]): Promise<void>;
+    /**
+     * 查找类似 Task（基于 Tag 匹配度）- 原始实现，保留兼容
+     * @deprecated 使用 findSimilarTasksByKeywords 代替
+     */
+    findSimilarTasks(taskId: number, limit?: number): Promise<Task[]>;
+    /**
+     * 根据关键词搜索 Task（标题 + 描述）- 原始实现，保留兼容
+     * @deprecated 使用 searchTasksByKeywords 代替
+     */
+    searchTasks(query: string, limit?: number): Promise<Task[]>;
+}
+/**
+ * TagService 实现
+ */
+export declare class DefaultTagService implements TagService {
+    private store;
+    constructor(store: TaskStore);
+    createTag(name: string): Promise<TaskTag>;
+    getTag(id: number): Promise<TaskTag | undefined>;
+    getTagByName(name: string): Promise<TaskTag | undefined>;
+    listTags(options?: ListTagsOptions): Promise<TaskTag[]>;
+    searchTags(options: SearchTagsOptions): Promise<TaskTag[]>;
+    deleteTag(id: number): Promise<boolean>;
+    addTagsToTask(taskId: number, tagIds: number[]): Promise<void>;
+    removeTagsFromTask(taskId: number, tagIds: number[]): Promise<void>;
+    getTagsForTask(taskId: number): Promise<TaskTag[]>;
+    getTaskIdsByTags(tagNames: string[]): Promise<number[]>;
+    /**
+     * 根据关键词列表搜索 Task
+     * @deprecated 使用 findSimilarTasksByKeywords 代替
+     */
+    findSimilarTasks(taskId: number, limit?: number): Promise<Task[]>;
+    /**
+     * 根据关键词搜索 Task（单字符串）- 原始实现
+     * @deprecated 使用 searchTasksByKeywords 代替
+     */
+    searchTasks(query: string, limit?: number): Promise<Task[]>;
+    /**
+     * 根据关键词列表搜索 Task
+     * 检索范围：tags、description、goals、operations
+     */
+    searchTasksByKeywords(keywords: string[], options?: {
+        limit?: number;
+        excludeTaskId?: number;
+    }): Promise<Task[]>;
+    /**
+     * 根据关键词查找类似 Task
+     */
+    findSimilarTasksByKeywords(keywords: string[], options?: {
+        limit?: number;
+        excludeTaskId?: number;
+    }): Promise<Task[]>;
+    syncTagsToTask(taskId: number, tagNames: string[]): Promise<void>;
+}

package/dist/env/task/task-child-context.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Task Child Context — Pure helper for safely inheriting context
+ *                 from a parent task when creating a child task.
+ *
+ * Used by `task_create` (and by delegate prompt builders) to suggest a
+ * sensible default payload for a child task. The caller may override any
+ * field; the helper never silently drops required fields.
+ *
+ * Inheritance rules (v1):
+ *
+ *   1. project_path — ALWAYS inherited from parent unless overridden.
+ *   2. worktree_path, branch, parent_branch, type — inherited from parent
+ *      `context` JSON when present and the caller doesn't override.
+ *   3. tags — NOT inherited by default (caller may opt in via `inheritTags`).
+ *      Why: tags often encode the parent feature/iteration; children may
+ *      want different tagging to track their own scope.
+ *   4. prior_context.commit — NEVER copied (security: avoid leaking private
+ *      commit SHAs). prior_context.prev_task IS preserved (helpful trail).
+ *   5. created_at — always auto-injected with current timestamp unless
+ *      the caller overrides it.
+ *   6. Sensitive fields — token redaction is the responsibility of the
+ *      caller (TaskCreationRegistry already redacts on storage). This
+ *      helper additionally strips known commit-SHA leakage patterns.
+ *
+ * If parent.contextJson is malformed, we fall back gracefully:
+ *   - project_path still inherited
+ *   - context still produced (as minimal JSON)
+ *   - all other inherited fields absent
+ */
+/**
+ * Snapshot of the parent task's stored context. Sourced from
+ * `taskComponent.getTask(parentId)` + `parent.context` JSON.
+ */
+export interface ParentContextSnapshot {
+    taskId: number;
+    projectPath: string;
+    /** Raw JSON string of the parent's context field. */
+    contextJson: string;
+    tags?: string[];
+}
+/**
+ * Caller-provided overrides. `undefined` = "use inherited value".
+ */
+export interface ChildContextOverrides {
+    /** Replace inherited project_path. */
+    projectPath?: string;
+    /** Replace inherited branch (in context.branch). */
+    branch?: string;
+    /** Replace inherited worktree_path (in context.worktree_path). */
+    worktreePath?: string;
+    /** If true, inherit parent's tags. Default false. */
+    inheritTags?: boolean;
+    /** If false, skip all inherited context fields. Default true. */
+    contextInherit?: boolean;
+    /** Override auto-injected created_at. */
+    createdAt?: string;
+}
+export interface InheritedChildContext {
+    /** Resolved project_path to use for the child task. */
+    project_path: string;
+    /** Serialized JSON `context` field ready for the child task. */
+    context: string;
+    /** Tags inherited from parent (only populated when `inheritTags=true`). */
+    inheritedTags: string[];
+}
+export interface InheritArgs {
+    parent: ParentContextSnapshot;
+    overrides?: ChildContextOverrides;
+}
+export declare function inheritChildContext(args: InheritArgs): InheritedChildContext;