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

package/dist/env/memory/plugin/memory-manager.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview MemoryManager V3 - Simplified
+ *
+ * 后台异步任务队列处理
+ *
+ * 简化设计：
+ * - 移除 DraftManager（草稿管理已废弃）
+ * - 移除 MemoryOrganizer（整理机制已废弃）
+ * - 移除 AccessLog（访问日志已废弃）
+ * - 只保留核心的任务队列处理
+ */
+import type { MemoryTask, ExtractMemoryPayload } from "./types";
+/**
+ * MemoryManager 配置
+ */
+export interface MemoryManagerConfig {
+    /** 回调：当需要提取记忆时调用 */
+    onExtractMemory?: (payload: ExtractMemoryPayload) => Promise<void>;
+}
+/**
+ * MemoryManager V3 - Simplified
+ *
+ * 简化的后台异步内存处理，只负责任务队列
+ */
+export declare class MemoryManager {
+    /** 队列最大容量，防止内存溢出 */
+    private static readonly MAX_QUEUE_SIZE;
+    private queue;
+    private processing;
+    private shuttingDown;
+    private config;
+    private processingPromise;
+    private resolveProcessing;
+    constructor(config?: MemoryManagerConfig);
+    /**
+     * 更新配置
+     */
+    updateConfig(config: Partial<MemoryManagerConfig>): void;
+    /**
+     * 入队（非阻塞）
+     */
+    enqueue(task: Omit<MemoryTask, "id">): void;
+    /**
+     * 启动处理循环
+     */
+    private startProcessingLoop;
+    /**
+     * 检查是否有待处理任务
+     */
+    hasPendingTasks(): boolean;
+    /**
+     * 等待处理完成
+     */
+    waitForCompletion(): Promise<void>;
+    /**
+     * 准备关闭
+     */
+    prepareShutdown(): void;
+    /**
+     * 释放资源
+     */
+    dispose(): Promise<void>;
+    /**
+     * 处理单个任务
+     */
+    private processTask;
+    /**
+     * 处理记忆提取
+     */
+    private handleExtractMemory;
+}

package/dist/env/memory/plugin/memory-plugin.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @fileoverview MemoryPlugin - Simplified
+ *
+ * Hook handler for agent:after.react
+ *
+ * 简化设计（移除旧的复杂机制）：
+ * - 移除了 DraftManager（草稿管理已废弃）
+ * - 移除了 MemoryOrganizer（整理机制已废弃）
+ * - 移除了 AccessLog（访问日志已废弃）
+ *
+ * 新的记忆管理方式：
+ * - 使用 `roy memory recall --extract` 命令手动触发
+ * - 使用 Memory Agent 自动分析会话历史
+ * - 直接更新 memory.md 文件
+ */
+import type { HookContext } from "../../agent/types";
+import type { MemoryPluginConfig } from "./types";
+/**
+ * MemoryPlugin - Simplified
+ *
+ * 简化的记忆插件，不再自动处理。
+ *
+ * 用户应该使用 `roy memory recall --extract` 命令来手动触发记忆提取。
+ *
+ * 保留此插件是为了：
+ * 1. 保持 API 兼容性
+ * 2. 未来可以扩展为可选的自动触发
+ */
+export declare class MemoryPlugin {
+    private config;
+    private disposed;
+    private initialized;
+    /** 项目 memory 基础目录 */
+    private projectBaseDir;
+    /** 全局 memory 基础目录 */
+    private globalBaseDir;
+    /** 当前工作目录（用于推断项目路径） */
+    private workDir;
+    /** AgentComponent 引用（延迟获取） */
+    private agentComponent;
+    constructor(baseDir: string, config?: MemoryPluginConfig);
+    /**
+     * Plugin 名称
+     */
+    get name(): string;
+    /**
+     * 订阅的 Hook 点
+     */
+    get hookPoint(): "agent:after.react";
+    /**
+     * 优先级
+     */
+    get priority(): number;
+    /**
+     * 描述
+     */
+    get description(): string;
+    /**
+     * 获取 Hook 定义
+     */
+    get hooks(): {
+        point: "agent:after.react";
+        priority: number;
+    }[];
+    /**
+     * 初始化
+     */
+    initialize(): Promise<void>;
+    /**
+     * 执行 Hook
+     *
+     * 简化为空操作。用户应该使用 `roy memory recall --extract` 命令。
+     */
+    execute(ctx: HookContext): Promise<void>;
+    /**
+     * 准备关闭
+     */
+    prepareShutdown(): void;
+    /**
+     * 检查是否有待处理任务
+     */
+    hasPendingTasks(): boolean;
+    /**
+     * 等待处理完成
+     */
+    waitForCompletion(): Promise<void>;
+    /**
+     * 释放资源
+     */
+    dispose(): Promise<void>;
+    /**
+     * 获取项目 base dir
+     */
+    getProjectBaseDir(): string;
+    /**
+     * 获取全局 base dir
+     */
+    getGlobalBaseDir(): string;
+}
+/**
+ * 创建 MemoryPlugin 实例
+ */
+export declare function createMemoryPlugin(baseDir: string, config?: MemoryPluginConfig): MemoryPlugin;

package/dist/env/memory/plugin/recall-memory.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Recall Memory - Simplified
+ *
+ * 简化设计：
+ * - 移除 AccessLog（访问日志已废弃）
+ * - 只读取 memory.md 文件
+ */
+import type { MemoryPath } from "../types";
+/**
+ * 读取记忆文件
+ *
+ * @param memoryPaths - 记忆路径列表
+ * @returns 记忆内容
+ */
+export declare function recallMemory(memoryPaths: MemoryPath[]): Promise<string>;
+export type { MemoryPath } from "../types";

package/dist/env/memory/plugin/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview Memory Plugin Types (Simplified)
+ *
+ * MemoryPlugin 相关类型定义
+ *
+ * 简化设计：
+ * - 移除 Draft 相关的类型
+ * - 移除 AccessLog 相关的类型
+ */
+import type { HookContext } from "../../hook/types";
+import type { ModelMessage } from "ai";
+/**
+ * MemoryPlugin configuration
+ */
+export interface MemoryPluginConfig {
+    /** Enable memory plugin */
+    enabled?: boolean;
+}
+/**
+ * Default MemoryPlugin configuration
+ */
+export declare const DEFAULT_MEMORY_PLUGIN_CONFIG: MemoryPluginConfig;
+/**
+ * Memory task types
+ */
+export type MemoryTaskType = "extract_memory";
+/**
+ * Memory task
+ */
+export interface MemoryTask {
+    id: string;
+    type: MemoryTaskType;
+    payload: unknown;
+    timestamp: number;
+    priority: number;
+}
+/**
+ * Extract memory payload
+ */
+export interface ExtractMemoryPayload {
+    messages: ModelMessage[];
+    sessionId?: string;
+    /** Hook context for Memory Agent */
+    ctx?: MemoryHookContext;
+}
+/**
+ * SessionMessage 接口
+ */
+export interface SessionMessage {
+    /** 消息角色 */
+    role: "user" | "assistant" | "system" | "tool";
+    /** 消息内容 */
+    content: string | Array<{
+        type: string;
+        [key: string]: unknown;
+    }>;
+    /** 工具调用 ID（仅 tool 角色） */
+    toolCallId?: string;
+    /** 工具名称（仅 tool 角色） */
+    toolName?: string;
+    /** 时间戳 */
+    timestamp?: number;
+}
+/**
+ * Hook context data for agent:after.react
+ */
+export interface MemoryHookContext {
+    /** Current messages for memory extraction */
+    messages: ModelMessage[];
+    /** Current session ID */
+    sessionId?: string;
+    /** Project summaries (populated by project agent) */
+    projectSummaries?: unknown[];
+}
+export type { HookContext };

package/dist/env/memory/tools/memory-agent-tools.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview Memory Agent Tools
+ *
+ * Memory Agent 使用的工具：
+ * - search_sessions: 搜索会话历史
+ * - get_session: 获取指定会话
+ * - write_memory: 写入记忆文件
+ * - bash: 执行 Shell 命令（用于探索项目结构）
+ * - read_file: 读取文件内容（用于阅读文档）
+ */
+import { z } from "zod";
+import type { Tool } from "../../tool/types";
+/**
+ * search_sessions 输入参数
+ */
+export declare const SearchSessionsSchema: z.ZodObject<{
+    query: z.ZodString;
+    session_id: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    limit: number;
+    session_id?: string | undefined;
+}, {
+    query: string;
+    session_id?: string | undefined;
+    limit?: number | undefined;
+}>;
+export type SearchSessionsParams = z.infer<typeof SearchSessionsSchema>;
+/**
+ * get_session 输入参数
+ */
+export declare const GetSessionSchema: z.ZodObject<{
+    session_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    session_id: string;
+}, {
+    session_id: string;
+}>;
+export type GetSessionParams = z.infer<typeof GetSessionSchema>;
+/**
+ * write_memory 输入参数
+ */
+export declare const WriteMemorySchema: z.ZodObject<{
+    scope: z.ZodEnum<["project", "global"]>;
+    content: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    scope: "project" | "global";
+    content: string;
+}, {
+    scope: "project" | "global";
+    content: string;
+}>;
+export type WriteMemoryParams = z.infer<typeof WriteMemorySchema>;
+/**
+ * Session Component 接口（需要 searchSessions, getSession 方法）
+ */
+export interface MemoryAgentSessionComponent {
+    /**
+     * 列出所有会话（用于 search_sessions）
+     */
+    list(options?: any): Promise<any[]>;
+    /**
+     * 获取会话上下文（包含消息）
+     */
+    getContext(sessionId: string, options?: any): Promise<any>;
+    /**
+     * 搜索会话（通过 grep 命令）
+     */
+    searchSessions(query: string, options?: {
+        session_id?: string;
+        limit?: number;
+    }): Promise<any[]>;
+    /**
+     * 获取单个会话
+     */
+    getSession(sessionId: string): Promise<any | null>;
+}
+/**
+ * Memory Component 接口（需要 recallMemory, recordMemory 方法）
+ */
+export interface MemoryAgentMemoryComponent {
+    recallMemory(scope?: "project" | "global"): Promise<string | null>;
+    recordMemory(params: {
+        mode: string;
+        content: string;
+        scope?: string;
+    }): Promise<void>;
+}
+/**
+ * Config Component 接口
+ */
+export interface MemoryAgentConfigComponent {
+    get(key: string): unknown;
+}
+/**
+ * Memory Agent 工具工厂
+ */
+export declare function createMemoryAgentTools(deps: {
+    sessionComponent: MemoryAgentSessionComponent;
+    memoryComponent: MemoryAgentMemoryComponent;
+    configComponent?: MemoryAgentConfigComponent;
+}): {
+    searchSessions: Tool;
+    getSession: Tool;
+    writeMemory: Tool;
+    bash: Tool;
+    read_file: Tool;
+};

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

@@ -0,0 +1,80 @@
+import { z } from "zod";
+/**
+ * Memory 来源类型
+ * - project: 项目级记忆
+ * - global: 全局记忆
+ */
+export type MemorySource = "project" | "global";
+/**
+ * Memory 路径配置
+ */
+export interface MemoryPath {
+    /** 来源类型 */
+    type: MemorySource;
+    /** 绝对路径 */
+    path: string;
+}
+/**
+ * MemoryComponent 配置
+ */
+export interface MemoryConfig {
+    /** 多路径配置 */
+    memoryPaths: MemoryPath[];
+    /** 是否递归扫描子目录 */
+    recursive: boolean;
+    /** 是否启用缓存 */
+    cacheEnabled: boolean;
+    /** 缓存有效期（毫秒） */
+    cacheTTL?: number;
+    /** 记忆文件名 */
+    memoryFile?: string;
+}
+/**
+ * record_memory 操作模式
+ */
+export type RecordMemoryMode = "append" | "prepend" | "overwrite" | "delete";
+/**
+ * record_memory 操作结果
+ */
+export interface RecordMemoryResult {
+    /** 文件路径 */
+    path: string;
+    /** 操作类型 */
+    action: "created" | "append" | "prepend" | "overwrite" | "delete";
+}
+/**
+ * record_memory 工具参数
+ */
+export declare const RecordMemorySchema: z.ZodObject<{
+    /** 作用域 (必填) */
+    scope: z.ZodEnum<["project", "global"]>;
+    /** 操作模式 */
+    mode: z.ZodEnum<["append", "prepend", "overwrite", "delete"]>;
+    /** 记忆内容 (delete 模式不需要) */
+    content: z.ZodOptional<z.ZodString>;
+    /** 章节标题 (可选，用于生成 ## title 章节) */
+    title: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    scope: "project" | "global";
+    mode: "append" | "prepend" | "overwrite" | "delete";
+    title?: string | undefined;
+    content?: string | undefined;
+}, {
+    scope: "project" | "global";
+    mode: "append" | "prepend" | "overwrite" | "delete";
+    title?: string | undefined;
+    content?: string | undefined;
+}>;
+export type RecordMemoryParams = z.infer<typeof RecordMemorySchema>;
+/**
+ * recall_memory 工具参数
+ */
+export declare const RecallMemorySchema: z.ZodObject<{
+    /** 作用域 (可选，不传则读取所有 scope) */
+    scope: z.ZodOptional<z.ZodEnum<["project", "global"]>>;
+}, "strip", z.ZodTypeAny, {
+    scope?: "project" | "global" | undefined;
+}, {
+    scope?: "project" | "global" | undefined;
+}>;
+export type RecallMemoryParams = z.infer<typeof RecallMemorySchema>;

package/dist/env/paths.d.ts

@@ -0,0 +1,46 @@
+/**
+ * XDG 基础目录类型
+ */
+export type XDGDirType = "config" | "state" | "data" | "cache";
+/**
+ * XDG 路径接口
+ */
+export interface XDGPaths {
+    home: string;
+    config: string;
+    state: string;
+    data: string;
+    cache: string;
+}
+/**
+ * XDG 路径计算器（惰性计算）
+ */
+declare class XDGPathsCalculator {
+    private _paths?;
+    get paths(): XDGPaths;
+    /**
+     * 获取特定类型的路径
+     */
+    getPath(type: XDGDirType): string;
+    /**
+     * 计算 Component 的绝对路径
+     */
+    getComponentPath(base: XDGDirType, subPath: string): string;
+    /**
+     * 强制重新计算路径（用于测试或配置变更）
+     */
+    reset(): void;
+}
+/**
+ * 全局 XDG 路径实例
+ */
+export declare const XDG_PATHS: XDGPathsCalculator;
+/**
+ * 获取 XDG 路径
+ */
+export declare function getXDGPaths(): XDGPaths;
+/**
+ * 获取特定类型的 XDG 路径
+ */
+export declare function getXDGPath(type: XDGDirType): string;
+export {};

package/dist/env/plugin/bounty-cli-notification-channel.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview BountyCliNotificationChannel
+ *
+ * 仿 `LarkCliNotificationChannel` 设计，spawn `bounty event publish` 子进程
+ * 投递到 Mattermost。
+ *
+ * ## 路由逻辑
+ *
+ * - canRoute = true 仅当 `envContext.replyChannel` 存在
+ *   - type 含 "bounty-cli"（不区分大小写）
+ *   - 至少有 channelId 或 messageId
+ *
+ * ## spawn bounty-cli
+ *
+ * - `bounty event publish --channel <channelId> --text <text>` 投递到 Mattermost
+ * - profile 不为 undefined 时在 args 头部插入 `--profile <name>` flag
+ * - 也支持 channelName（按 Mattermost 频道名称）
+ *
+ * ## 失败处理
+ *
+ * - spawn 失败 / exit code != 0 → swallow（log warn，notification 失败不污染 Plugin 主流程）
+ *
+ * ## 与 bounty-cli 的关系
+ *
+ * bounty-cli 是独立的 Go 二进制（@ai-setting/bounty-cli npm 包，
+ * https://github.com/ai-setting/bounty-cli）。它通过 postinstall 自动下载。
+ * 用户安装 `@ai-setting/bounty-cli` 后，`bounty` 命令即可在 PATH 中使用。
+ */
+import type { EnvContextLike, NotificationChannel, NotificationOptions, NotificationSendExtras } from "./notification-channel";
+/**
+ * BountyCli Notification Channel
+ *
+ * @example
+ * ```ts
+ * // 注册 bounty-cli 通道（用于 Mattermost 投递）
+ * component.setNotificationChannels([
+ *   new BountyCliNotificationChannel(),
+ *   EventBusNotificationChannel(), // 兜底
+ * ]);
+ * ```
+ */
+export declare class BountyCliNotificationChannel implements NotificationChannel {
+    readonly name = "bounty-cli";
+    /**
+     * 仅当 replyChannel 含 bounty-cli 类型且有 channelId/messageId/channelName 时路由
+     */
+    canRoute(_options: NotificationOptions, _extras: NotificationSendExtras, envContext: EnvContextLike): boolean;
+    /**
+     * spawn bounty event publish 发 Mattermost 消息
+     */
+    send(options: NotificationOptions, extras: NotificationSendExtras, envContext: EnvContextLike): Promise<void>;
+    /**
+     * spawn `bounty event publish` 子进程
+     *
+     * - messageId 优先：用 `bounty event reply`（如果存在）或附加到 publish 的 text
+     * - channelId 优先：用 `--channel <id>`
+     * - channelName：用 `--channel <name>`（按名称）
+     */
+    private spawnBountyPublish;
+}

package/dist/env/plugin/event-bus-notification-channel.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview EventBusNotificationChannel
+ *
+ * 默认 NotificationChannel 实现 —— 把通知转成 roy-agent 自身
+ * `env.pushEnvEvent` 事件。
+ *
+ * ## 事件命名空间
+ *
+ * - event.type = `plugin.notification.<NotificationOptions.type>`
+ * - event.metadata.source = `plugin:<extras.pluginName>`
+ * - event.metadata 合并用户传入的 options.metadata（不覆盖 source）
+ * - event.payload = `{ title, content }`
+ *
+ * ## 失败处理
+ *
+ * - 缺失 envInstance / pushEnvEvent → silent skip（log debug）
+ * - pushEnvEvent 抛错 → swallow（log warn）
+ *
+ * 通知失败不应当污染 Plugin 主流程 —— Plugin 永远拿不到通知失败信号。
+ */
+import type { EnvContextLike, NotificationChannel, NotificationOptions, NotificationSendExtras } from "./notification-channel";
+/**
+ * EventBus Notification Channel
+ *
+ * 默认通道。可用于任何 plugin 通知场景（不依赖 replyChannel）。
+ *
+ * @example
+ * ```ts
+ * import { EventBusNotificationChannel } from "./event-bus-notification-channel";
+ *
+ * component.setNotificationChannels([
+ *   new EventBusNotificationChannel(),
+ *   // 或其他自定义通道
+ * ]);
+ * ```
+ */
+export declare class EventBusNotificationChannel implements NotificationChannel {
+    readonly name = "event-bus";
+    /**
+     * event-bus 通道 always routable（无外部依赖）
+     *
+     * 注：missing envInstance / pushEnvEvent 在 send 时检测，不在这里拒绝，
+     * 保持 canRoute 语义简单（"我能路由这种通知吗"），让 send 决定是否真的能投递。
+     */
+    canRoute(_options: NotificationOptions, _extras: NotificationSendExtras, _envContext: EnvContextLike): boolean;
+    /**
+     * 通过 env.pushEnvEvent 推送 plugin.notification.<type> 事件
+     */
+    send(options: NotificationOptions, extras: NotificationSendExtras, _envContext: EnvContextLike): Promise<void>;
+}

package/dist/env/plugin/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Plugin System Module
+ */
+export { BasePlugin, type PluginEnv, type HookDefinition, type HookHandler, type AgentInstanceConfig, type ToolDefinition, type HookContext, type HookResult, } from "./types";
+export { PluginComponent, type PluginComponentOptions } from "./plugin-component";
+export type { EnvContextLike, NotificationChannel, NotificationOptions, NotificationSendExtras, } from "./notification-channel";
+export { EventBusNotificationChannel } from "./event-bus-notification-channel";
+/**
+ * @deprecated 自 v2 起默认通道改为 EventBusNotificationChannel。
+ *             LarkCliNotificationChannel 保留为 opt-in legacy 实现。
+ *             新代码请用 EventBusNotificationChannel + env-level event subscriber。
+ */
+export { LarkCliNotificationChannel } from "./lark-cli-notification-channel";

package/dist/env/plugin/lark-cli-notification-channel.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview LarkCliNotificationChannel
+ *
+ * @deprecated 自 v2 起默认通道改为 `EventBusNotificationChannel`。
+ *             LarkCliNotificationChannel 保留为可选/opt-in 实现，
+ *             新代码请用 EventBusNotificationChannel + env-level event
+ *             subscriber 自行投递到飞书。
+ *
+ * ## 保留原因
+ *
+ * - 部分现有 Plugin 通过 `PluginEnv.notify` 期望直接发飞书（不通过 event bus）
+ * - 兼容旧 Plugin 配置（lark-cli 是历史默认通道）
+ *
+ * ## 路由逻辑
+ *
+ * - canRoute = true 仅当 `envContext.replyChannel` 存在，且
+ *   - type 含 "lark"（不区分大小写）
+ *   - 至少有 chatId 或 messageId
+ *
+ * ## spawn lark-cli
+ *
+ * - messageId 走 `lark-cli im +messages-reply --message-id <id> --markdown <md>`
+ * - chatId 走 `lark-cli im +messages-send --chat-id <id> --markdown <md>`
+ * - profile 不为 undefined 时在 args 头部插入 `--profile <name>`
+ *
+ * ## 失败处理
+ *
+ * - spawn 失败 / exit code != 0 → swallow（log warn，notification 失败不污染 Plugin 主流程）
+ */
+import type { EnvContextLike, NotificationChannel, NotificationOptions, NotificationSendExtras } from "./notification-channel";
+/**
+ * Lark-cli Notification Channel（legacy / @deprecated）
+ *
+ * 行为：
+ * - 通过 spawn lark-cli 子进程投递到飞书
+ * - 路由依据 envContext.replyChannel
+ *
+ * @example
+ * ```ts
+ * // opt-in legacy channel
+ * component.setNotificationChannels([
+ *   new LarkCliNotificationChannel(),
+ *   EventBusNotificationChannel(), // 兜底
+ * ]);
+ * ```
+ */
+export declare class LarkCliNotificationChannel implements NotificationChannel {
+    readonly name = "lark-cli";
+    /**
+     * 仅当 replyChannel 含 lark 类型且有 chatId/messageId 时路由
+     */
+    canRoute(_options: NotificationOptions, _extras: NotificationSendExtras, envContext: EnvContextLike): boolean;
+    /**
+     * spawn lark-cli 发飞书消息
+     */
+    send(options: NotificationOptions, extras: NotificationSendExtras, envContext: EnvContextLike): Promise<void>;
+    /**
+     * spawn `lark-cli im +messages-{reply,send}` 子进程
+     */
+    private spawnLarkMessage;
+}