alemonjs-aichat 1.0.33-beta.0 → 1.0.34

package/lib/api/aitools.js

@@ -1,14 +1,17 @@
 import { redis } from '../redis.js';
 import { getConfigValue } from 'alemonjs';
 import fs from 'fs';
-import { uploadImageToR2 } from '../s3.js';
+import { uploadImageToR2, uploadMediaToR2 } from '../s3.js';
 import { TTSClient } from './tts.js';
+import OpenAi from 'openai';
 import { loadSkillDetail } from './loadSkill.js';
 import help from '../data/help.json.js';
 import redisClient from '../config.js';
 import { isPrivateIP, validateURL } from './security.js';
 import { spawn } from 'child_process';
 import * as dns from 'node:dns/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
 import { getWorkspace } from './workspace.js';
 import { getExecCommandEnv } from '../userEnv.js';
 import { remoteNodeManager } from '../remoteNodes.js';
@@ -170,7 +173,7 @@ const tools = [
         type: "function",
         function: {
             name: "exec",
-            description: "执行终端命令. 你可以使用这个工具来执行一些简单的命令, 例如查看当前目录下的文件ls, 查看系统状态top等. 当你想要执行一个命令时, 请提供具体的命令文本, 例如'ls -la'或'top -n 1'. 执行结果将会返回给你, 但请注意, 由于安全限制, 某些命令可能无法执行或返回受限的结果",
+            description: "执行终端命令. 禁止用于 AI agent 编程文件操作；public/{guid}/ 内的文件增查改删只能使用 Agent* 文件工具，不能通过 exec、Docker 或容器完成. 你可以使用这个工具来执行一些简单的命令, 例如查看当前目录下的文件ls, 查看系统状态top等. 当你想要执行一个命令时, 请提供具体的命令文本, 例如'ls -la'或'top -n 1'. 执行结果将会返回给你, 但请注意, 由于安全限制, 某些命令可能无法执行或返回受限的结果",
             parameters: {
                 type: "object",
                 properties: {
@@ -208,6 +211,441 @@ const tools = [
             },
         },
     },
+    {
+        type: "function",
+        function: {
+            name: "AgentListWorkspaces",
+            description: "列出 public/ 下已有的 AI agent 工作目录 guid，适合在不知道之前项目 guid 时先做发现。找到 guid 后再配合 AgentListFiles 或 AgentSearchFiles 查看 knowledge/ 和项目内容。",
+            parameters: {
+                type: "object",
+                properties: {
+                    includeKnowledge: {
+                        type: "boolean",
+                        description: "是否附带每个工作目录下 knowledge/ 的一级仓库目录名摘要",
+                        default: true,
+                    },
+                    maxResults: {
+                        type: "number",
+                        description: "最多返回多少个工作目录，默认 50，最大 200",
+                        default: 50,
+                    },
+                },
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "AgentCreateWorkspace",
+            description: "在项目 public/ 下创建一个新的 AI agent 工作目录，并返回可用于后续文件工具的 guid。需要新项目目录时使用它，不要用 exec 调用 uuidgen。",
+            parameters: {
+                type: "object",
+                properties: {
+                    guid: {
+                        type: "string",
+                        description: "可选。指定工作目录ID；不传则自动生成一个安全的随机ID",
+                    },
+                },
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "AgentCloneRepository",
+            description: "克隆一个公开 http/https Git 仓库到 public/{guid}/ 内作为 AI 知识库。只能执行受限的 git clone，不能执行其他 git、终端、Docker 或容器操作。默认克隆到 knowledge/{仓库名}。",
+            parameters: {
+                type: "object",
+                properties: {
+                    guid: {
+                        type: "string",
+                        description: "项目工作目录ID，对应 public/{guid}/",
+                    },
+                    repoUrl: {
+                        type: "string",
+                        description: "要克隆的公开 Git 仓库 URL，只允许 http/https，不允许 SSH、本地路径或带账号密码的 URL",
+                    },
+                    targetPath: {
+                        type: "string",
+                        description: "可选。克隆目标目录，必须是 public/{guid}/ 下的相对路径。默认 knowledge/{仓库名}",
+                    },
+                    branch: {
+                        type: "string",
+                        description: "可选。要克隆的分支或 tag 名称",
+                    },
+                    depth: {
+                        type: "number",
+                        description: "可选。浅克隆深度，默认 1，最大 50",
+                        default: 1,
+                    },
+                },
+                required: ["guid", "repoUrl"],
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "AgentReviewProjectCommand",
+            description: "审核将在 public/{guid}/ 工作目录中执行的项目命令是否安全。会先做本地规则审查，并在可用时使用当前 AI 配置做二次审查。",
+            parameters: {
+                type: "object",
+                properties: {
+                    guid: {
+                        type: "string",
+                        description: "项目工作目录ID，对应 public/{guid}/",
+                    },
+                    command: {
+                        type: "string",
+                        description: "要审查的项目命令，例如 npm.cmd run build 或 npx.cmd create-vite@latest app",
+                    },
+                    workingDirectory: {
+                        type: "string",
+                        description: "可选。命令执行目录，必须是 public/{guid}/ 下的相对路径，默认为 .",
+                        default: ".",
+                    },
+                    reviewGuid: {
+                        type: "string",
+                        description: "可选。当前聊天或当前 AI 配置对应的 guid；不传时会尝试使用全局 AI 配置做二次审查",
+                    },
+                },
+                required: ["guid", "command"],
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "AgentGitOperation",
+            description: "在 public/{guid}/ 内的 Git 仓库执行受限 Git 操作：查看当前分支、获取分支列表、查看远端列表、切换到已有分支。禁止 commit、push、pull、merge、rebase、reset、tag、stash 等会改动历史或同步远端的操作。",
+            parameters: {
+                type: "object",
+                properties: {
+                    guid: {
+                        type: "string",
+                        description: "项目工作目录ID，对应 public/{guid}/",
+                    },
+                    workingDirectory: {
+                        type: "string",
+                        description: "可选。Git 仓库所在目录，必须是 public/{guid}/ 下的相对路径，默认为 .",
+                        default: ".",
+                    },
+                    action: {
+                        type: "string",
+                        description: "Git 操作类型：currentBranch 当前分支；listBranches 分支列表；listRemotes 远端列表；switchBranch 切换到已有分支",
+                        enum: ["currentBranch", "listBranches", "listRemotes", "switchBranch"],
+                    },
+                    branch: {
+                        type: "string",
+                        description: "action=switchBranch 时必填，要切换到的分支名。只允许已有本地分支，或已有的 origin/<branch> 远端分支。",
+                    },
+                    includeRemote: {
+                        type: "boolean",
+                        description: "action=listBranches 时可选，是否同时包含远端分支，默认 true",
+                        default: true,
+                    },
+                },
+                required: ["guid", "action"],
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "AgentProjectCommand",
+            description: "在 public/{guid}/ 工作目录内执行受限的项目操作：环境检测、受限命令执行、解压缩、重命名和创建目录。run 动作会自动审查命令安全后再执行。",
+            parameters: {
+                type: "object",
+                properties: {
+                    guid: {
+                        type: "string",
+                        description: "项目工作目录ID，对应 public/{guid}/",
+                    },
+                    action: {
+                        type: "string",
+                        description: "操作类型：inspect 环境检测；run 运行受限项目命令；extract 解压缩；rename 重命名；mkdir 创建目录",
+                        enum: ["inspect", "run", "extract", "rename", "mkdir"],
+                    },
+                    workingDirectory: {
+                        type: "string",
+                        description: "可选。操作目录，必须是 public/{guid}/ 下的相对路径，默认为 .",
+                        default: ".",
+                    },
+                    command: {
+                        type: "string",
+                        description: "action=run 时必填，要执行的受限项目命令",
+                    },
+                    reviewGuid: {
+                        type: "string",
+                        description: "可选。当前聊天或当前 AI 配置对应的 guid；用于自动审查 run 命令",
+                    },
+                    archivePath: {
+                        type: "string",
+                        description: "action=extract 时必填，要解压的压缩包路径，必须是 public/{guid}/ 下的相对路径",
+                    },
+                    destinationPath: {
+                        type: "string",
+                        description: "action=extract 时可选，解压目标目录，必须是 public/{guid}/ 下的相对路径，默认解压到当前目录",
+                    },
+                    sourcePath: {
+                        type: "string",
+                        description: "action=rename 时必填，源文件或目录路径，必须是 public/{guid}/ 下的相对路径",
+                    },
+                    targetPath: {
+                        type: "string",
+                        description: "action=rename 时必填，目标文件或目录路径，必须是 public/{guid}/ 下的相对路径",
+                    },
+                    directoryPath: {
+                        type: "string",
+                        description: "action=mkdir 时必填，要创建的目录路径，必须是 public/{guid}/ 下的相对路径",
+                    },
+                },
+                required: ["guid", "action"],
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "AgentReadFileLines",
+            description: "读取项目 public/{guid}/ 目录内指定文本文件的指定行范围。适合写代码前查看文件片段。路径必须是相对 public/{guid}/ 的相对路径。",
+            parameters: {
+                type: "object",
+                properties: {
+                    guid: {
+                        type: "string",
+                        description: "项目工作目录ID，对应 public/{guid}/",
+                    },
+                    filePath: {
+                        type: "string",
+                        description: "要读取的文本文件路径，必须是 public/{guid}/ 下的相对路径",
+                    },
+                    startLine: {
+                        type: "number",
+                        description: "起始行号，从 1 开始",
+                        default: 1,
+                    },
+                    endLine: {
+                        type: "number",
+                        description: "结束行号，从 1 开始。单次最多返回 500 行",
+                    },
+                },
+                required: ["guid", "filePath"],
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "AgentWriteFile",
+            description: "写入项目 public/{guid}/ 目录内指定文件。默认覆盖整个文件，也可追加到文件末尾。路径必须是相对 public/{guid}/ 的相对路径。",
+            parameters: {
+                type: "object",
+                properties: {
+                    guid: {
+                        type: "string",
+                        description: "项目工作目录ID，对应 public/{guid}/",
+                    },
+                    filePath: {
+                        type: "string",
+                        description: "要写入的文件路径，必须是 public/{guid}/ 下的相对路径",
+                    },
+                    content: {
+                        type: "string",
+                        description: "要写入的完整文本内容",
+                    },
+                    mode: {
+                        type: "string",
+                        description: "写入模式：overwrite 覆盖文件，append 追加到末尾",
+                        enum: ["overwrite", "append"],
+                        default: "overwrite",
+                    },
+                },
+                required: ["guid", "filePath", "content"],
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "AgentInsertFile",
+            description: "向项目 public/{guid}/ 目录内指定文本文件的指定行之前插入内容。路径必须是相对 public/{guid}/ 的相对路径。",
+            parameters: {
+                type: "object",
+                properties: {
+                    guid: {
+                        type: "string",
+                        description: "项目工作目录ID，对应 public/{guid}/",
+                    },
+                    filePath: {
+                        type: "string",
+                        description: "要插入内容的文本文件路径，必须是 public/{guid}/ 下的相对路径",
+                    },
+                    lineNumber: {
+                        type: "number",
+                        description: "插入位置行号，从 1 开始。内容会插入到该行之前；传入总行数+1 表示追加到文件末尾",
+                    },
+                    content: {
+                        type: "string",
+                        description: "要插入的文本内容",
+                    },
+                },
+                required: ["guid", "filePath", "lineNumber", "content"],
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "AgentCreateFile",
+            description: "在项目 public/{guid}/ 目录内创建新文件。默认不覆盖已有文件。路径必须是相对 public/{guid}/ 的相对路径。",
+            parameters: {
+                type: "object",
+                properties: {
+                    guid: {
+                        type: "string",
+                        description: "项目工作目录ID，对应 public/{guid}/",
+                    },
+                    filePath: {
+                        type: "string",
+                        description: "要创建的文件路径，必须是 public/{guid}/ 下的相对路径",
+                    },
+                    content: {
+                        type: "string",
+                        description: "新文件内容",
+                        default: "",
+                    },
+                    overwrite: {
+                        type: "boolean",
+                        description: "是否允许覆盖已存在文件",
+                        default: false,
+                    },
+                },
+                required: ["guid", "filePath"],
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "AgentDeleteFile",
+            description: "删除项目 public/{guid}/ 目录内指定文件。只能删除文件，不能删除文件夹。路径必须是相对 public/{guid}/ 的相对路径。",
+            parameters: {
+                type: "object",
+                properties: {
+                    guid: {
+                        type: "string",
+                        description: "项目工作目录ID，对应 public/{guid}/",
+                    },
+                    filePath: {
+                        type: "string",
+                        description: "要删除的文件路径，必须是 public/{guid}/ 下的相对路径",
+                    },
+                },
+                required: ["guid", "filePath"],
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "AgentListFiles",
+            description: "获取项目 public/{guid}/ 目录内指定文件夹的文件列表。路径必须是相对 public/{guid}/ 的相对路径。",
+            parameters: {
+                type: "object",
+                properties: {
+                    guid: {
+                        type: "string",
+                        description: "项目工作目录ID，对应 public/{guid}/",
+                    },
+                    folderPath: {
+                        type: "string",
+                        description: "要列出的文件夹路径，必须是 public/{guid}/ 下的相对路径。默认为当前工作目录根部",
+                        default: ".",
+                    },
+                    recursive: {
+                        type: "boolean",
+                        description: "是否递归列出子目录",
+                        default: false,
+                    },
+                    maxDepth: {
+                        type: "number",
+                        description: "递归时的最大深度，默认 3",
+                        default: 3,
+                    },
+                },
+                required: ["guid"],
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "AgentSearchFiles",
+            description: "在项目 public/{guid}/ 目录内按文件名和文件内容搜索，适合在已克隆的知识库或当前项目中查找 README、类名、函数名、配置项或关键字。不要在说“本地没有”之前跳过这个工具。",
+            parameters: {
+                type: "object",
+                properties: {
+                    guid: {
+                        type: "string",
+                        description: "项目工作目录ID，对应 public/{guid}/",
+                    },
+                    query: {
+                        type: "string",
+                        description: "要搜索的关键词或文本片段",
+                    },
+                    folderPath: {
+                        type: "string",
+                        description: "可选。搜索起始目录，必须是 public/{guid}/ 下的相对路径，默认 .",
+                        default: ".",
+                    },
+                    mode: {
+                        type: "string",
+                        description: "搜索模式：filename 只搜文件名，content 只搜文件内容，both 两者都搜",
+                        enum: ["filename", "content", "both"],
+                        default: "both",
+                    },
+                    maxResults: {
+                        type: "number",
+                        description: "最多返回多少条结果，默认 20，最大 100",
+                        default: 20,
+                    },
+                },
+                required: ["guid", "query"],
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "AgentUploadFileToR2",
+            description: "将项目 public/{guid}/ 目录内的构建产物或媒体文件上传到 R2，返回可公开访问的链接。路径必须是相对 public/{guid}/ 的相对路径；拿到链接后可直接发给用户，图片可用 <img=链接> 发送。",
+            parameters: {
+                type: "object",
+                properties: {
+                    guid: {
+                        type: "string",
+                        description: "项目工作目录ID，对应 public/{guid}/",
+                    },
+                    filePath: {
+                        type: "string",
+                        description: "要上传的文件路径，必须是 public/{guid}/ 下的相对路径",
+                    },
+                    fileName: {
+                        type: "string",
+                        description: "可选。上传后希望使用的文件名，例如 report.zip 或 preview.png。会自动清理非法字符；图片最终扩展名会跟随转换结果。",
+                    },
+                    uploadType: {
+                        type: "string",
+                        description: "上传类型。file 用于普通构建产物/压缩包/音视频等；image 会走图片压缩和格式转换流程",
+                        enum: ["file", "image"],
+                        default: "file",
+                    },
+                },
+                required: ["guid", "filePath"],
+            },
+        },
+    },
     // {
     //   type: "function",
     //   function: {
@@ -255,12 +693,12 @@ const tools = [
                     },
                     dataType: {
                         type: "string",
-                        description: "要获取或修改的数据类型，例如'user'表示用户相关,获取或修改用户数据，'chatHistory'表示历史对话,历史对话只能获取不能修改",
+                        description: "要获取或修改的数据类型，例如'user'表示用户相关,获取或修改用户数据，'chatHistory'表示历史对话与历史归档,历史对话只能获取不能修改",
                         enum: ["user", "chatHistory"],
                     },
                     data: {
                         type: "string",
-                        description: "要获取或修改的数据内容, 例如当operation为'set'时,dataType为'user'时, data应该是要存储的数据内容, 例如用户喜欢的颜色是蓝色, 则data可以是'favoriteColor:blue', 当operation为'get'时, dataType为'user'时, data就不需要传入值, 它会返回之前存储的数据, 当operation为'get'时, dataType为'chatHistory'时, data不传入值获取摘要列表, 传入id获取对应的摘要详情",
+                        description: "要获取或修改的数据内容, 例如当operation为'set'时,dataType为'user'时, data应该是要存储的数据内容, 例如用户喜欢的颜色是蓝色, 则data可以是'favoriteColor:blue', 当operation为'get'时,dataType为'user'时,data可以留空; 当operation为'get'且dataType为'chatHistory'时,data留空会返回摘要列表, 传入'guid:id'获取该归档详情, 传入'search:关键词'可搜索相关历史归档",
                     },
                 },
             },
@@ -316,31 +754,1002 @@ const tools = [
                     method: { type: "string", enum: ["GET", "POST"] },
                     body: { type: "string" },
                 },
-                required: ["url"],
-            },
-        },
-    },
-    {
-        type: "function",
-        function: {
-            name: "getAlemonjsConfig",
-            description: `获取框架配置,详情请参考use-alemon技能说明`,
-            parameters: {
-                type: "object",
-                properties: {
-                    key: {
-                        type: "string",
-                        description: "配置项的键,可用值请参考use-alemon技能说明",
-                    },
-                    value: {
-                        type: "string",
-                        description: "查找时传入值,可用值请参考use-alemon技能说明",
-                    },
+                required: ["url"],
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "getAlemonjsConfig",
+            description: `获取框架配置,详情请参考use-alemon技能说明`,
+            parameters: {
+                type: "object",
+                properties: {
+                    key: {
+                        type: "string",
+                        description: "配置项的键,可用值请参考use-alemon技能说明",
+                    },
+                    value: {
+                        type: "string",
+                        description: "查找时传入值,可用值请参考use-alemon技能说明",
+                    },
+                },
+            },
+        },
+    },
+];
+const AGENT_FILE_MAX_READ_LINES = 500;
+const AGENT_FILE_MAX_LIST_ENTRIES = 500;
+const AGENT_FILE_MAX_SEARCH_RESULTS = 100;
+const PROJECT_COMMAND_MAX_OUTPUT = 24000;
+const PROJECT_COMMAND_TIMEOUT_MS = 10 * 60 * 1000;
+const ALLOWED_PROJECT_COMMAND_BASES = new Set([
+    "dotnet",
+    "dotnet.exe",
+    "npm",
+    "npm.cmd",
+    "npx",
+    "npx.cmd",
+    "pnpm",
+    "pnpm.cmd",
+    "yarn",
+    "yarn.cmd",
+    "bun",
+    "bunx",
+    "node",
+    "node.exe",
+    "git",
+    "where",
+    "where.exe",
+]);
+const ALLOWED_GIT_PROJECT_SUBCOMMANDS = new Set([
+    "init",
+    "status",
+    "branch",
+    "rev-parse",
+    "log",
+    "describe",
+    "remote",
+]);
+const ALLOWED_DOTNET_PROJECT_SUBCOMMANDS = new Set([
+    "--version",
+    "--info",
+    "--list-sdks",
+    "--list-runtimes",
+    "new",
+    "restore",
+    "build",
+    "run",
+    "test",
+    "publish",
+    "clean",
+    "add",
+    "remove",
+    "list",
+    "sln",
+]);
+const BLOCKED_PROJECT_COMMAND_PATTERNS = [
+    { pattern: /&&|\|\||[;|<>`]|[$][(]/, reason: "不允许使用 shell 控制符、重定向、命令替换或反引号" },
+    { pattern: /(^|[\s])(rm|del|erase|rmdir|rd)([\s]|$)/i, reason: "不允许使用删除命令" },
+    { pattern: /(^|[\s])(powershell|pwsh|cmd|bash|sh|docker|ssh|scp|sftp|curl|wget)([\s]|$)/i, reason: "不允许执行受限外部命令" },
+    { pattern: /\.\.[\\/]/, reason: "不允许通过 .. 离开 public 工作目录" },
+];
+const toToolError = (error) => ({
+    success: false,
+    error: error instanceof Error ? error.message : String(error),
+});
+const assertPathInside = (root, target) => {
+    const relative = path.relative(root, target);
+    if (relative && (relative.startsWith("..") || path.isAbsolute(relative))) {
+        throw new Error("路径超出 public/{guid}/ 工作目录");
+    }
+};
+const getExistingAncestor = (target) => {
+    let current = target;
+    while (!fs.existsSync(current)) {
+        const parent = path.dirname(current);
+        if (parent === current) {
+            throw new Error("无法解析目标路径");
+        }
+        current = parent;
+    }
+    return current;
+};
+const assertRealPathInside = (root, target) => {
+    const realRoot = fs.realpathSync.native(root);
+    const existing = getExistingAncestor(target);
+    const realExisting = fs.realpathSync.native(existing);
+    assertPathInside(realRoot, realExisting);
+    if (fs.existsSync(target)) {
+        const realTarget = fs.realpathSync.native(target);
+        assertPathInside(realRoot, realTarget);
+    }
+};
+const resolveAgentRoot = (guid) => {
+    if (!guid || typeof guid !== "string") {
+        throw new Error("guid 不能为空");
+    }
+    const safeGuid = guid.trim();
+    if (!safeGuid || safeGuid === "." || safeGuid === "..") {
+        throw new Error("guid 必须是 public 下的有效目录名");
+    }
+    if (path.isAbsolute(safeGuid) ||
+        safeGuid.includes("/") ||
+        safeGuid.includes("\\") ||
+        safeGuid.includes("\0")) {
+        throw new Error("guid 只能作为 public 下的单级目录名");
+    }
+    const publicRoot = path.resolve(process.cwd(), "public");
+    const root = path.resolve(publicRoot, safeGuid);
+    assertPathInside(publicRoot, root);
+    fs.mkdirSync(root, { recursive: true });
+    assertRealPathInside(publicRoot, root);
+    return root;
+};
+const createAgentGuid = (guid) => {
+    if (guid && guid.trim()) {
+        resolveAgentRoot(guid);
+        return guid.trim();
+    }
+    const guidValue = randomUUID();
+    resolveAgentRoot(guidValue);
+    return guidValue;
+};
+const listAgentWorkspaces = (includeKnowledge = true, maxResults = 50) => {
+    const publicRoot = path.resolve(process.cwd(), "public");
+    if (!fs.existsSync(publicRoot)) {
+        return [];
+    }
+    const limit = Math.max(1, Math.min(normalizePositiveInteger(maxResults, 50, "maxResults"), 200));
+    const ignoredNames = new Set(["sandbox", "image_out"]);
+    return fs
+        .readdirSync(publicRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && !ignoredNames.has(entry.name))
+        .map((entry) => {
+        const root = path.join(publicRoot, entry.name);
+        const knowledgeRoot = path.join(root, "knowledge");
+        const knowledgeProjects = includeKnowledge && fs.existsSync(knowledgeRoot)
+            ? fs
+                .readdirSync(knowledgeRoot, { withFileTypes: true })
+                .filter((item) => item.isDirectory())
+                .map((item) => item.name)
+                .slice(0, 20)
+            : [];
+        return {
+            guid: entry.name,
+            path: `public/${entry.name}`,
+            hasKnowledge: knowledgeProjects.length > 0,
+            knowledgeProjects,
+        };
+    })
+        .sort((a, b) => a.guid.localeCompare(b.guid))
+        .slice(0, limit);
+};
+const commandTargetsAgentWorkspace = (command) => {
+    const normalized = command.replace(/["']/g, "").toLowerCase();
+    return (normalized.includes("public/") ||
+        normalized.includes("public\\") ||
+        normalized.includes("knowledge/") ||
+        normalized.includes("knowledge\\"));
+};
+const sanitizeRepositoryName = (repoUrl) => {
+    const url = new URL(repoUrl);
+    const lastSegment = url.pathname.split("/").filter(Boolean).pop() || "repo";
+    const withoutGit = lastSegment.replace(/\.git$/i, "");
+    const safeName = withoutGit.replace(/[^a-zA-Z0-9._-]/g, "-");
+    return safeName || "repo";
+};
+const validateRepositoryUrl = async (repoUrl) => {
+    const url = new URL(repoUrl);
+    if (!["http:", "https:"].includes(url.protocol)) {
+        throw new Error("仓库地址只允许 http/https");
+    }
+    if (url.username || url.password) {
+        throw new Error("仓库地址不能包含账号密码或 token");
+    }
+    await validateURL(repoUrl);
+};
+const validateGitRef = (ref) => {
+    if (!/^[a-zA-Z0-9._/-]+$/.test(ref) || ref.includes("..")) {
+        throw new Error("branch 只能包含字母、数字、点、下划线、短横线和斜杠");
+    }
+};
+const normalizeCloneDepth = (depth) => {
+    const safeDepth = normalizePositiveInteger(depth, 1, "depth");
+    return Math.min(safeDepth, 50);
+};
+const resolveCloneTargetPath = (repoUrl, targetPath) => {
+    const safeTargetPath = targetPath?.trim();
+    if (safeTargetPath) {
+        if (safeTargetPath === "." || safeTargetPath === "/") {
+            throw new Error("targetPath 不能是工作目录根部");
+        }
+        return safeTargetPath;
+    }
+    return `knowledge/${sanitizeRepositoryName(repoUrl)}`;
+};
+const resolveAgentPath = (guid, inputPath = ".") => {
+    if (path.isAbsolute(inputPath) || inputPath.includes("\0")) {
+        throw new Error("只能使用相对 public/{guid}/ 的路径");
+    }
+    const root = resolveAgentRoot(guid);
+    const target = path.resolve(root, inputPath || ".");
+    assertPathInside(root, target);
+    assertRealPathInside(root, target);
+    return {
+        root,
+        target,
+        relativePath: path.relative(root, target).replace(/\\/g, "/") || ".",
+    };
+};
+const ensureParentDirectory = (target) => {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+};
+const ensureGitRepository = async (cwd) => {
+    const result = await runSpawnCommand({
+        file: "git",
+        args: ["rev-parse", "--is-inside-work-tree"],
+        cwd,
+    });
+    if (result.exitCode !== 0 || result.output.trim().toLowerCase() !== "true") {
+        throw new Error("目标目录不是 Git 仓库");
+    }
+};
+const getGitCurrentBranch = async (cwd) => {
+    const result = await runSpawnCommand({
+        file: "git",
+        args: ["branch", "--show-current"],
+        cwd,
+    });
+    if (result.exitCode !== 0) {
+        throw new Error(result.output.trim() || "获取当前分支失败");
+    }
+    return result.output.trim();
+};
+const listGitBranches = async (cwd, includeRemote) => {
+    const args = ["branch", "--list"];
+    if (includeRemote) {
+        args.push("--all");
+    }
+    const result = await runSpawnCommand({
+        file: "git",
+        args,
+        cwd,
+    });
+    if (result.exitCode !== 0) {
+        throw new Error(result.output.trim() || "获取分支列表失败");
+    }
+    return result.output
+        .split(/\r?\n/)
+        .map((line) => line.trimEnd())
+        .map((line) => {
+        const current = line.startsWith("*");
+        const name = line.replace(/^\*\s*/, "").trim();
+        if (!name || name === "HEAD detached at") {
+            return null;
+        }
+        return {
+            name,
+            current,
+            remote: name.startsWith("remotes/"),
+        };
+    })
+        .filter((item) => !!item);
+};
+const listGitRemotes = async (cwd) => {
+    const result = await runSpawnCommand({
+        file: "git",
+        args: ["remote", "-v"],
+        cwd,
+    });
+    if (result.exitCode !== 0) {
+        throw new Error(result.output.trim() || "获取远端列表失败");
+    }
+    const remotes = new Map();
+    for (const line of result.output.split(/\r?\n/)) {
+        const match = line.trim().match(/^(\S+)\s+(\S+)\s+\((fetch|push)\)$/);
+        if (!match)
+            continue;
+        const [, name, url, type] = match;
+        const current = remotes.get(name) || { name };
+        if (type === "fetch")
+            current.fetch = url;
+        if (type === "push")
+            current.push = url;
+        remotes.set(name, current);
+    }
+    return [...remotes.values()];
+};
+const switchGitBranch = async (cwd, branch) => {
+    validateGitRef(branch);
+    const localBranches = await listGitBranches(cwd, false);
+    const localExists = localBranches.some((item) => item.name === branch);
+    if (localExists) {
+        const result = await runSpawnCommand({
+            file: "git",
+            args: ["switch", branch],
+            cwd,
+        });
+        if (result.exitCode !== 0) {
+            throw new Error(result.output.trim() || "切换本地分支失败");
+        }
+        return {
+            branch,
+            source: "local",
+            output: result.output,
+        };
+    }
+    const remoteBranches = await listGitBranches(cwd, true);
+    const remoteName = `remotes/origin/${branch}`;
+    const remoteExists = remoteBranches.some((item) => item.name === remoteName);
+    if (!remoteExists) {
+        throw new Error("目标分支不存在，本地和 origin 远端都未找到该分支");
+    }
+    const result = await runSpawnCommand({
+        file: "git",
+        args: ["switch", "--track", `origin/${branch}`],
+        cwd,
+    });
+    if (result.exitCode !== 0) {
+        throw new Error(result.output.trim() || "切换远端跟踪分支失败");
+    }
+    return {
+        branch,
+        source: "origin",
+        output: result.output,
+    };
+};
+const readTextLines = (target) => {
+    const content = fs.readFileSync(target, "utf-8");
+    return content.length ? content.split(/\r?\n/) : [];
+};
+const isLikelyTextFile = (filePath) => {
+    const ext = path.extname(filePath).toLowerCase();
+    if (!ext)
+        return true;
+    const binaryExtensions = new Set([
+        ".png",
+        ".jpg",
+        ".jpeg",
+        ".gif",
+        ".webp",
+        ".bmp",
+        ".ico",
+        ".zip",
+        ".tar",
+        ".gz",
+        ".tgz",
+        ".7z",
+        ".rar",
+        ".pdf",
+        ".mp3",
+        ".wav",
+        ".ogg",
+        ".mp4",
+        ".avi",
+        ".mov",
+        ".exe",
+        ".dll",
+        ".so",
+        ".bin",
+        ".woff",
+        ".woff2",
+        ".ttf",
+        ".otf",
+    ]);
+    return !binaryExtensions.has(ext);
+};
+const normalizePositiveInteger = (value, fallback, fieldName) => {
+    const numeric = value === undefined ? fallback : Number(value);
+    if (!Number.isInteger(numeric) || numeric < 1) {
+        throw new Error(`${fieldName} 必须是大于等于 1 的整数`);
+    }
+    return numeric;
+};
+const getAgentFileList = (root, folder, depth, maxDepth, entries) => {
+    if (entries.length >= AGENT_FILE_MAX_LIST_ENTRIES)
+        return;
+    for (const item of fs.readdirSync(folder, { withFileTypes: true })) {
+        if (entries.length >= AGENT_FILE_MAX_LIST_ENTRIES)
+            return;
+        const fullPath = path.join(folder, item.name);
+        assertPathInside(root, fullPath);
+        const stat = fs.statSync(fullPath);
+        const type = item.isDirectory() ? "directory" : "file";
+        entries.push({
+            path: path.relative(root, fullPath).replace(/\\/g, "/"),
+            type,
+            size: stat.size,
+            modifiedAt: stat.mtime.toISOString(),
+        });
+        if (item.isDirectory() && depth < maxDepth) {
+            getAgentFileList(root, fullPath, depth + 1, maxDepth, entries);
+        }
+    }
+};
+const searchFilesWithinWorkspace = ({ root, folder, query, mode, maxResults, }) => {
+    const results = [];
+    const lowerQuery = query.toLowerCase();
+    const walk = (currentFolder) => {
+        if (results.length >= maxResults)
+            return;
+        for (const item of fs.readdirSync(currentFolder, { withFileTypes: true })) {
+            if (results.length >= maxResults)
+                return;
+            const fullPath = path.join(currentFolder, item.name);
+            assertPathInside(root, fullPath);
+            if (item.isDirectory()) {
+                walk(fullPath);
+                continue;
+            }
+            if (!item.isFile()) {
+                continue;
+            }
+            const relativePath = path.relative(root, fullPath).replace(/\\/g, "/");
+            if (mode !== "content" && item.name.toLowerCase().includes(lowerQuery)) {
+                results.push({
+                    path: relativePath,
+                    type: "filename",
+                    preview: item.name,
+                });
+                if (results.length >= maxResults)
+                    return;
+            }
+            if (mode === "filename" || !isLikelyTextFile(fullPath)) {
+                continue;
+            }
+            try {
+                const lines = readTextLines(fullPath);
+                for (let index = 0; index < lines.length; index += 1) {
+                    if (results.length >= maxResults)
+                        return;
+                    const line = lines[index];
+                    if (line.toLowerCase().includes(lowerQuery)) {
+                        results.push({
+                            path: relativePath,
+                            type: "content",
+                            lineNumber: index + 1,
+                            preview: line.trim().slice(0, 240),
+                        });
+                    }
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+    };
+    walk(folder);
+    return results;
+};
+const runGitClone = ({ repoUrl, target, branch, depth, }) => {
+    return new Promise((resolve, reject) => {
+        const args = ["clone", "--depth", String(depth)];
+        if (branch) {
+            args.push("--branch", branch);
+        }
+        args.push("--", repoUrl, target);
+        const child = spawn("git", args, {
+            env: {
+                ...process.env,
+                GIT_TERMINAL_PROMPT: "0",
+            },
+        });
+        let output = "";
+        const appendOutput = (data) => {
+            output += data.toString();
+            if (output.length > 12000) {
+                output = output.slice(-12e3);
+            }
+        };
+        const timeout = setTimeout(() => {
+            child.kill();
+            reject(new Error("git clone 超时"));
+        }, 120000);
+        child.stdout.on("data", appendOutput);
+        child.stderr.on("data", appendOutput);
+        child.on("error", (error) => {
+            clearTimeout(timeout);
+            reject(new Error(error.code === "ENOENT"
+                ? "未找到 git 命令，无法克隆仓库"
+                : `git clone 启动失败: ${error.message}`));
+        });
+        child.on("close", (code) => {
+            clearTimeout(timeout);
+            if (code === 0) {
+                resolve(output.trim());
+                return;
+            }
+            reject(new Error(`git clone 失败，退出码 ${code}${output ? `\n${output}` : ""}`));
+        });
+    });
+};
+const tokenizeCommand = (command) => {
+    const tokens = [];
+    let current = "";
+    let quote = null;
+    for (let i = 0; i < command.length; i += 1) {
+        const char = command[i];
+        if ((char === '"' || char === "'") && (!quote || quote === char)) {
+            if (quote === char) {
+                quote = null;
+            }
+            else {
+                quote = char;
+            }
+            continue;
+        }
+        if (!quote && /\s/.test(char)) {
+            if (current) {
+                tokens.push(current);
+                current = "";
+            }
+            continue;
+        }
+        current += char;
+    }
+    if (quote) {
+        throw new Error("命令引号未闭合");
+    }
+    if (current) {
+        tokens.push(current);
+    }
+    return tokens;
+};
+const trimProjectCommandOutput = (output) => output.length > PROJECT_COMMAND_MAX_OUTPUT
+    ? `${output.slice(0, PROJECT_COMMAND_MAX_OUTPUT)}\n[output truncated]`
+    : output;
+const isUnsafePathToken = (token) => {
+    if (!token)
+        return false;
+    if (token.includes("\0"))
+        return true;
+    if (token === ".." || token.startsWith("../") || token.startsWith("..\\")) {
+        return true;
+    }
+    if (/^[a-zA-Z]:[\\/]/.test(token)) {
+        return true;
+    }
+    return false;
+};
+const buildProjectCommandReview = (command) => {
+    const trimmed = command.trim();
+    if (!trimmed) {
+        return {
+            allowed: false,
+            risk: "blocked",
+            reasons: ["命令不能为空"],
+            baseCommand: "",
+            tokens: [],
+        };
+    }
+    for (const item of BLOCKED_PROJECT_COMMAND_PATTERNS) {
+        if (item.pattern.test(trimmed)) {
+            return {
+                allowed: false,
+                risk: "blocked",
+                reasons: [item.reason],
+                baseCommand: "",
+                tokens: [],
+            };
+        }
+    }
+    let tokens;
+    try {
+        tokens = tokenizeCommand(trimmed);
+    }
+    catch (error) {
+        return {
+            allowed: false,
+            risk: "blocked",
+            reasons: [error instanceof Error ? error.message : String(error)],
+            baseCommand: "",
+            tokens: [],
+        };
+    }
+    if (!tokens.length) {
+        return {
+            allowed: false,
+            risk: "blocked",
+            reasons: ["命令不能为空"],
+            baseCommand: "",
+            tokens,
+        };
+    }
+    if (tokens.some(isUnsafePathToken)) {
+        return {
+            allowed: false,
+            risk: "blocked",
+            reasons: ["命令参数中包含试图离开 public 工作目录的路径"],
+            baseCommand: "",
+            tokens,
+        };
+    }
+    const baseCommand = tokens[0].toLowerCase();
+    if (!ALLOWED_PROJECT_COMMAND_BASES.has(baseCommand)) {
+        return {
+            allowed: false,
+            risk: "blocked",
+            reasons: ["仅允许受限的项目命令，当前基础命令不在允许列表中"],
+            baseCommand,
+            tokens,
+        };
+    }
+    const reasons = [];
+    let risk = "low";
+    if (["node", "node.exe"].includes(baseCommand)) {
+        if (!["-v", "--version"].includes(tokens[1] || "")) {
+            return {
+                allowed: false,
+                risk: "blocked",
+                reasons: ["node 仅允许用于版本检测"],
+                baseCommand,
+                tokens,
+            };
+        }
+        reasons.push("版本检测命令");
+        return {
+            allowed: true,
+            risk,
+            reasons,
+            baseCommand,
+            tokens,
+        };
+    }
+    if (["dotnet", "dotnet.exe"].includes(baseCommand)) {
+        const subcommand = (tokens[1] || "").toLowerCase();
+        if (!ALLOWED_DOTNET_PROJECT_SUBCOMMANDS.has(subcommand)) {
+            return {
+                allowed: false,
+                risk: "blocked",
+                reasons: ["dotnet 仅允许受限的项目和环境检测子命令"],
+                baseCommand,
+                tokens,
+            };
+        }
+        risk = ["new", "restore", "build", "run", "test", "publish", "clean"].includes(subcommand)
+            ? "medium"
+            : "low";
+        reasons.push(risk === "medium"
+            ? ".NET 项目命令会创建、还原或编译工作目录内的项目"
+            : ".NET 环境检测或受限项目查询命令");
+        return {
+            allowed: true,
+            risk,
+            reasons,
+            baseCommand,
+            tokens,
+        };
+    }
+    if (["where", "where.exe"].includes(baseCommand)) {
+        reasons.push("环境探测命令");
+        return {
+            allowed: true,
+            risk,
+            reasons,
+            baseCommand,
+            tokens,
+        };
+    }
+    if (baseCommand === "git") {
+        const subcommand = (tokens[1] || "").toLowerCase();
+        if (!ALLOWED_GIT_PROJECT_SUBCOMMANDS.has(subcommand)) {
+            return {
+                allowed: false,
+                risk: "blocked",
+                reasons: ["git 仅允许受限的只读/初始化子命令"],
+                baseCommand,
+                tokens,
+            };
+        }
+        risk = subcommand === "init" ? "medium" : "low";
+        reasons.push(subcommand === "init" ? "git init 会创建仓库元数据" : "受限 git 查询命令");
+        return {
+            allowed: true,
+            risk,
+            reasons,
+            baseCommand,
+            tokens,
+        };
+    }
+    if (tokens.includes("-g") || tokens.includes("--global")) {
+        return {
+            allowed: false,
+            risk: "blocked",
+            reasons: ["不允许全局安装或修改全局环境"],
+            baseCommand,
+            tokens,
+        };
+    }
+    if (tokens.some((token) => /^https?:\/\//i.test(token))) {
+        return {
+            allowed: false,
+            risk: "blocked",
+            reasons: ["项目命令中不允许直接传入外部 URL"],
+            baseCommand,
+            tokens,
+        };
+    }
+    const subcommand = (tokens[1] || "").toLowerCase();
+    const blockedPackageManagerSubcommands = new Set([
+        "publish",
+        "login",
+        "logout",
+        "config",
+        "cache",
+        "owner",
+        "team",
+    ]);
+    if (blockedPackageManagerSubcommands.has(subcommand)) {
+        return {
+            allowed: false,
+            risk: "blocked",
+            reasons: ["不允许执行账号、发布或全局配置相关命令"],
+            baseCommand,
+            tokens,
+        };
+    }
+    if (["create", "init", "dlx", "exec"].includes(subcommand) || ["npx", "npx.cmd", "bunx"].includes(baseCommand)) {
+        risk = "medium";
+        reasons.push("脚手架或外部执行命令会下载并运行第三方包");
+    }
+    else if (["install", "i", "add", "ci"].includes(subcommand)) {
+        risk = "medium";
+        reasons.push("依赖安装命令会写入项目依赖和锁文件");
+    }
+    else if (["run", "test", "build"].includes(subcommand) || subcommand === "") {
+        risk = "low";
+        reasons.push("项目内脚本或常规包管理命令");
+    }
+    else {
+        risk = "medium";
+        reasons.push("已通过基础命令检查，但属于较少见的包管理子命令");
+    }
+    return {
+        allowed: true,
+        risk,
+        reasons,
+        baseCommand,
+        tokens,
+    };
+};
+const getReviewAIConfig = async (reviewGuid) => {
+    const guid = reviewGuid?.trim();
+    const config = await redisClient.getAIConfig(guid || undefined);
+    const currentAI = guid ? await redisClient.getCurrentAI(guid) : "";
+    if (!config.host.trim() || !config.key.trim() || !config.model.trim()) {
+        return null;
+    }
+    return {
+        guid: guid || "global",
+        currentAI,
+        config,
+    };
+};
+const reviewProjectCommandWithAI = async ({ command, localReview, reviewGuid, }) => {
+    const aiConfig = await getReviewAIConfig(reviewGuid);
+    if (!aiConfig) {
+        return {
+            status: "skipped",
+            reason: "未找到可用的当前 AI 配置，已仅使用本地规则审查",
+        };
+    }
+    try {
+        const openai = new OpenAi({
+            baseURL: aiConfig.config.host,
+            apiKey: aiConfig.config.key,
+            timeout: 30000,
+        });
+        const response = await openai.chat.completions.create({
+            model: aiConfig.config.model,
+            temperature: 0,
+            max_tokens: 200,
+            messages: [
+                {
+                    role: "system",
+                    content: "你是一个命令安全审查器。请只输出 JSON，格式为 {\"allowed\":boolean,\"risk\":\"low|medium|high|blocked\",\"reason\":\"简短中文原因\"}。审核标准：命令必须只适用于 public 工作目录内的安全项目操作，不得包含权限提升、删除系统文件、远程控制、数据外传、全局环境修改或危险 shell 行为。"
+                        + `\n性格约束:${aiConfig.config.systemPrompt || ""}`,
+                },
+                {
+                    role: "user",
+                    content: JSON.stringify({
+                        command,
+                        localReview: {
+                            allowed: localReview.allowed,
+                            risk: localReview.risk,
+                            reasons: localReview.reasons,
+                        },
+                    }),
                 },
-            },
-        },
-    },
-];
+            ],
+        });
+        const text = response.choices[0]?.message?.content || "";
+        const match = text.match(/\{[\s\S]*\}/);
+        if (!match) {
+            return {
+                status: "failed",
+                reason: "AI 审查未返回可解析的 JSON",
+                raw: text,
+            };
+        }
+        const parsed = JSON.parse(match[0]);
+        return {
+            status: "completed",
+            currentAI: aiConfig.currentAI || null,
+            model: aiConfig.config.model,
+            guid: aiConfig.guid,
+            allowed: Boolean(parsed.allowed),
+            risk: parsed.risk === "low" ||
+                parsed.risk === "medium" ||
+                parsed.risk === "high" ||
+                parsed.risk === "blocked"
+                ? parsed.risk
+                : "medium",
+            reason: typeof parsed.reason === "string" && parsed.reason.trim()
+                ? parsed.reason.trim()
+                : "AI 未提供明确原因",
+        };
+    }
+    catch (error) {
+        return {
+            status: "failed",
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+};
+const runSpawnCommand = ({ file, args, cwd, }) => {
+    return new Promise((resolve, reject) => {
+        const child = spawn(file, args, { cwd });
+        let output = "";
+        const appendOutput = (data) => {
+            output += data.toString();
+            if (output.length > PROJECT_COMMAND_MAX_OUTPUT) {
+                output = output.slice(-PROJECT_COMMAND_MAX_OUTPUT);
+            }
+        };
+        const timeout = setTimeout(() => {
+            child.kill();
+            reject(new Error("命令执行超时"));
+        }, PROJECT_COMMAND_TIMEOUT_MS);
+        child.stdout.on("data", appendOutput);
+        child.stderr.on("data", appendOutput);
+        child.on("error", (error) => {
+            clearTimeout(timeout);
+            reject(new Error(`命令启动失败: ${error.message}`));
+        });
+        child.on("close", (exitCode) => {
+            clearTimeout(timeout);
+            resolve({
+                output: trimProjectCommandOutput(output.trim()),
+                exitCode: exitCode ?? -1,
+            });
+        });
+    });
+};
+const findExecutablePaths = async (name, cwd) => {
+    try {
+        if (process.platform === "win32") {
+            const result = await runSpawnCommand({
+                file: "where.exe",
+                args: [name],
+                cwd,
+            });
+            if (result.exitCode !== 0 || !result.output) {
+                return [];
+            }
+            return result.output
+                .split(/\r?\n/)
+                .map((line) => line.trim())
+                .filter(Boolean);
+        }
+        const result = await runSpawnCommand({
+            file: "which",
+            args: [name],
+            cwd,
+        });
+        if (result.exitCode !== 0 || !result.output) {
+            return [];
+        }
+        return result.output
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+};
+const inspectProjectEnvironment = async (cwd) => {
+    const versionCommands = [
+        { name: "dotnet", file: process.platform === "win32" ? "dotnet.exe" : "dotnet", args: ["--version"] },
+        process.platform === "win32"
+            ? { name: "npm", file: "npm.cmd", args: ["-v"] }
+            : { name: "npm", file: "npm", args: ["-v"] },
+        process.platform === "win32"
+            ? { name: "npx", file: "npx.cmd", args: ["-v"] }
+            : { name: "npx", file: "npx", args: ["-v"] },
+        { name: "node", file: process.platform === "win32" ? "node.exe" : "node", args: ["-v"] },
+        { name: "git", file: "git", args: ["--version"] },
+    ];
+    const versions = {};
+    const paths = {};
+    for (const command of versionCommands) {
+        try {
+            const result = await runSpawnCommand({
+                file: command.file,
+                args: command.args,
+                cwd,
+            });
+            versions[command.name] =
+                result.exitCode === 0 ? result.output || "ok" : `exit ${result.exitCode}`;
+        }
+        catch (error) {
+            versions[command.name] =
+                error instanceof Error ? `unavailable: ${error.message}` : String(error);
+        }
+        paths[command.name] = await findExecutablePaths(command.name, cwd);
+    }
+    return {
+        cwd,
+        versions,
+        paths,
+        entries: fs.readdirSync(cwd, { withFileTypes: true }).slice(0, 50).map((item) => ({
+            name: item.name,
+            type: item.isDirectory() ? "directory" : "file",
+        })),
+    };
+};
+const extractArchiveWithinWorkspace = async ({ archive, destination, }) => {
+    ensureParentDirectory(destination);
+    fs.mkdirSync(destination, { recursive: true });
+    const lower = archive.toLowerCase();
+    if (lower.endsWith(".zip")) {
+        if (process.platform === "win32") {
+            return runSpawnCommand({
+                file: "powershell.exe",
+                args: [
+                    "-NoProfile",
+                    "-Command",
+                    `Expand-Archive -LiteralPath '${archive.replace(/'/g, "''")}' -DestinationPath '${destination.replace(/'/g, "''")}' -Force`,
+                ],
+                cwd: destination,
+            });
+        }
+        return runSpawnCommand({
+            file: "unzip",
+            args: ["-o", archive, "-d", destination],
+            cwd: destination,
+        });
+    }
+    if (lower.endsWith(".tar") || lower.endsWith(".tar.gz") || lower.endsWith(".tgz")) {
+        return runSpawnCommand({
+            file: "tar",
+            args: ["-xf", archive, "-C", destination],
+            cwd: destination,
+        });
+    }
+    throw new Error("仅支持 zip、tar、tar.gz、tgz 压缩包");
+};
+const performProjectCommandReview = async ({ command, reviewGuid, }) => {
+    const localReview = buildProjectCommandReview(command);
+    const aiReview = await reviewProjectCommandWithAI({
+        command,
+        localReview,
+        reviewGuid,
+    });
+    const allowed = localReview.allowed &&
+        (aiReview.status !== "completed" || aiReview.allowed === true);
+    const risk = aiReview.status === "completed" && aiReview.risk
+        ? aiReview.risk
+        : localReview.risk;
+    return {
+        allowed,
+        risk,
+        localReview,
+        aiReview,
+    };
+};
 /**
  * 确保 Docker 容器已创建并运行
  */
@@ -348,10 +1757,15 @@ async function ensureContainerRunning(config) {
     const { containerName, image, memory, cpus, pidsLimit, networkMode, workspacePath } = config;
     if (!containerName)
         return;
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
         const check = spawn("docker", ["inspect", "-f", "{{.State.Running}}", containerName]);
         let stdout = "";
         check.stdout.on("data", (d) => (stdout += d.toString()));
+        check.on("error", (error) => {
+            reject(new Error(error.code === "ENOENT"
+                ? "Docker 不可用：未找到 docker 命令"
+                : `Docker 检查失败：${error.message}`));
+        });
         check.on("close", (code) => {
             if (code === 0 && stdout.trim() === "true") {
                 resolve();
@@ -359,7 +1773,17 @@ async function ensureContainerRunning(config) {
             }
             if (code === 0 && stdout.trim() === "false") {
                 const start = spawn("docker", ["start", containerName]);
-                start.on("close", () => resolve());
+                start.on("error", (error) => {
+                    reject(new Error(`Docker 启动容器失败：${error.message}`));
+                });
+                start.on("close", (startCode) => {
+                    if (startCode === 0) {
+                        resolve();
+                    }
+                    else {
+                        reject(new Error(`Docker 启动容器失败，退出码: ${startCode}`));
+                    }
+                });
                 return;
             }
             const args = [
@@ -377,9 +1801,13 @@ async function ensureContainerRunning(config) {
             const create = spawn("docker", args);
             let createStderr = "";
             create.stderr.on("data", (d) => (createStderr += d.toString()));
+            create.on("error", (error) => {
+                reject(new Error(`Docker 创建容器失败：${error.message}`));
+            });
             create.on("close", (code) => {
                 if (code !== 0) {
-                    console.error(`[Docker] 容器创建失败: ${containerName}`, createStderr);
+                    reject(new Error(`Docker 创建容器失败: ${containerName}${createStderr ? `\n${createStderr}` : ""}`));
+                    return;
                 }
                 resolve();
             });
@@ -411,16 +1839,30 @@ const availableTools = {
                 return { success: true, data: userData };
             }
             if (dataType === "chatHistory") {
-                // 从redis获取聊天历史, key为chatHistory:${userID}
-                const [guid, id] = data?.split(":") || [];
+                if (!data) {
+                    const summaryList = await redisClient.getSummaryList();
+                    return { success: true, data: summaryList };
+                }
+                if (data.startsWith("search:")) {
+                    const query = data.slice("search:".length).trim();
+                    const records = await redisClient.searchArchivedChatRecords(query, {
+                        limit: 10,
+                    });
+                    return { success: true, data: records };
+                }
+                const [guid, id] = data.split(":") || [];
                 if (guid && id) {
+                    const record = await redisClient.getArchivedChatRecord(guid, id);
+                    if (record) {
+                        return { success: true, data: record };
+                    }
                     const chatHistory = await redisClient.getSummaryDetail(guid, id);
                     return { success: true, data: chatHistory };
                 }
-                else {
-                    const summaryList = await redisClient.getSummaryList();
-                    return { success: true, data: summaryList };
-                }
+                return {
+                    success: false,
+                    error: "chatHistory 的 data 只能为空、guid:id 或 search:关键词",
+                };
             }
         }
     },
@@ -784,6 +2226,13 @@ const availableTools = {
      */
     exec: async ({ userId, groupId, command }) => {
         const workspace = getWorkspace(userId);
+        if (commandTargetsAgentWorkspace(command || "")) {
+            return [
+                "exec 当前工作目录不是 public/{guid}/，不能可靠查找 AI agent 工作区里的项目。",
+                `exec 当前默认工作目录: ${workspace}`,
+                "如果要查找之前克隆到 public/{guid}/knowledge/ 的仓库，请改用 AgentListWorkspaces 先找 guid，再用 AgentListFiles 或 AgentSearchFiles。",
+            ].join("\n");
+        }
         // 使用新的环境管理获取执行环境
         const envInfo = await getExecCommandEnv(groupId || "private", userId);
         // 远程节点环境：通过 SSH 执行
@@ -823,6 +2272,9 @@ const availableTools = {
                 const child = spawn("sh", ["-c", command], { cwd: workspace });
                 child.stdout.on("data", (d) => (output += d.toString()));
                 child.stderr.on("data", (d) => (output += d.toString()));
+                child.on("error", (error) => {
+                    resolve(`系统执行失败: ${error.message}`);
+                });
                 child.on("close", () => resolve(output));
             });
         }
@@ -832,7 +2284,12 @@ const availableTools = {
         if (!containerName) {
             return "错误：未找到执行环境配置，请先切换执行环境";
         }
-        await ensureContainerRunning(envConfig);
+        try {
+            await ensureContainerRunning(envConfig);
+        }
+        catch (err) {
+            return `容器执行环境不可用: ${err.message}`;
+        }
         return new Promise((resolve) => {
             let output = "";
             const args = ["exec"];
@@ -843,9 +2300,472 @@ const availableTools = {
             const child = spawn("docker", args);
             child.stdout.on("data", (d) => (output += d.toString()));
             child.stderr.on("data", (d) => (output += d.toString()));
+            child.on("error", (error) => {
+                resolve(`Docker 执行失败: ${error.message}`);
+            });
             child.on("close", () => resolve(output));
         });
     },
+    AgentListWorkspaces: async ({ includeKnowledge = true, maxResults = 50, }) => {
+        try {
+            const workspaces = listAgentWorkspaces(includeKnowledge, maxResults);
+            return {
+                success: true,
+                count: workspaces.length,
+                workspaces,
+            };
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    },
+    AgentCreateWorkspace: async ({ guid }) => {
+        try {
+            const workspaceGuid = createAgentGuid(guid);
+            return {
+                success: true,
+                guid: workspaceGuid,
+                path: `public/${workspaceGuid}`,
+            };
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    },
+    AgentCloneRepository: async ({ guid, repoUrl, targetPath, branch, depth = 1, }) => {
+        try {
+            await validateRepositoryUrl(repoUrl);
+            if (branch) {
+                validateGitRef(branch);
+            }
+            const safeDepth = normalizeCloneDepth(depth);
+            const cloneTargetPath = resolveCloneTargetPath(repoUrl, targetPath);
+            const { target, relativePath } = resolveAgentPath(guid, cloneTargetPath);
+            if (fs.existsSync(target)) {
+                throw new Error("目标目录已存在，为避免覆盖请换一个 targetPath");
+            }
+            ensureParentDirectory(target);
+            const output = await runGitClone({
+                repoUrl,
+                target,
+                branch,
+                depth: safeDepth,
+            });
+            assertRealPathInside(resolveAgentRoot(guid), target);
+            return {
+                success: true,
+                guid,
+                repoUrl,
+                path: relativePath,
+                depth: safeDepth,
+                branch: branch || null,
+                output,
+            };
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    },
+    AgentReviewProjectCommand: async ({ guid, command, workingDirectory = ".", reviewGuid, }) => {
+        try {
+            const { relativePath } = resolveAgentPath(guid, workingDirectory);
+            const review = await performProjectCommandReview({
+                command,
+                reviewGuid,
+            });
+            return {
+                success: true,
+                guid,
+                workingDirectory: relativePath,
+                command,
+                ...review,
+            };
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    },
+    AgentGitOperation: async ({ guid, action, workingDirectory = ".", branch, includeRemote = true, }) => {
+        try {
+            const { target: cwd, relativePath } = resolveAgentPath(guid, workingDirectory);
+            await ensureGitRepository(cwd);
+            if (action === "currentBranch") {
+                const currentBranch = await getGitCurrentBranch(cwd);
+                return {
+                    success: true,
+                    guid,
+                    action,
+                    workingDirectory: relativePath,
+                    branch: currentBranch || null,
+                };
+            }
+            if (action === "listBranches") {
+                const branches = await listGitBranches(cwd, includeRemote !== false);
+                return {
+                    success: true,
+                    guid,
+                    action,
+                    workingDirectory: relativePath,
+                    branches,
+                };
+            }
+            if (action === "listRemotes") {
+                const remotes = await listGitRemotes(cwd);
+                return {
+                    success: true,
+                    guid,
+                    action,
+                    workingDirectory: relativePath,
+                    remotes,
+                };
+            }
+            if (action === "switchBranch") {
+                if (!branch) {
+                    throw new Error("action=switchBranch 时必须提供 branch");
+                }
+                const switched = await switchGitBranch(cwd, branch);
+                const currentBranch = await getGitCurrentBranch(cwd);
+                return {
+                    success: true,
+                    guid,
+                    action,
+                    workingDirectory: relativePath,
+                    branch: currentBranch || branch,
+                    source: switched.source,
+                    output: switched.output,
+                };
+            }
+            throw new Error("不支持的 Git action");
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    },
+    AgentProjectCommand: async ({ guid, action, workingDirectory = ".", command, reviewGuid, archivePath, destinationPath, sourcePath, targetPath, directoryPath, }) => {
+        try {
+            const { target: cwd, relativePath } = resolveAgentPath(guid, workingDirectory);
+            if (action === "inspect") {
+                const info = await inspectProjectEnvironment(cwd);
+                return {
+                    success: true,
+                    guid,
+                    action,
+                    workingDirectory: relativePath,
+                    ...info,
+                };
+            }
+            if (action === "mkdir") {
+                if (!directoryPath) {
+                    throw new Error("action=mkdir 时必须提供 directoryPath");
+                }
+                const created = resolveAgentPath(guid, directoryPath);
+                fs.mkdirSync(created.target, { recursive: true });
+                return {
+                    success: true,
+                    guid,
+                    action,
+                    path: created.relativePath,
+                };
+            }
+            if (action === "rename") {
+                if (!sourcePath || !targetPath) {
+                    throw new Error("action=rename 时必须提供 sourcePath 和 targetPath");
+                }
+                const source = resolveAgentPath(guid, sourcePath);
+                const target = resolveAgentPath(guid, targetPath);
+                if (!fs.existsSync(source.target)) {
+                    throw new Error("源路径不存在");
+                }
+                if (fs.existsSync(target.target)) {
+                    throw new Error("目标路径已存在，为避免覆盖请更换 targetPath");
+                }
+                ensureParentDirectory(target.target);
+                fs.renameSync(source.target, target.target);
+                return {
+                    success: true,
+                    guid,
+                    action,
+                    sourcePath: source.relativePath,
+                    targetPath: target.relativePath,
+                };
+            }
+            if (action === "extract") {
+                if (!archivePath) {
+                    throw new Error("action=extract 时必须提供 archivePath");
+                }
+                const archive = resolveAgentPath(guid, archivePath);
+                if (!fs.existsSync(archive.target) || !fs.statSync(archive.target).isFile()) {
+                    throw new Error("压缩包不存在或不是文件");
+                }
+                const destination = resolveAgentPath(guid, destinationPath || workingDirectory || ".");
+                const result = await extractArchiveWithinWorkspace({
+                    archive: archive.target,
+                    destination: destination.target,
+                });
+                return {
+                    success: result.exitCode === 0,
+                    guid,
+                    action,
+                    archivePath: archive.relativePath,
+                    destinationPath: destination.relativePath,
+                    output: result.output,
+                    exitCode: result.exitCode,
+                    error: result.exitCode === 0 ? undefined : "解压命令执行失败",
+                };
+            }
+            if (action === "run") {
+                if (!command) {
+                    throw new Error("action=run 时必须提供 command");
+                }
+                const review = await performProjectCommandReview({
+                    command,
+                    reviewGuid,
+                });
+                if (!review.allowed) {
+                    return {
+                        success: false,
+                        guid,
+                        action,
+                        command,
+                        workingDirectory: relativePath,
+                        error: "命令未通过安全审查",
+                        review,
+                    };
+                }
+                const localReview = review.localReview;
+                const result = await runSpawnCommand({
+                    file: localReview.tokens[0],
+                    args: localReview.tokens.slice(1),
+                    cwd,
+                });
+                return {
+                    success: result.exitCode === 0,
+                    guid,
+                    action,
+                    command,
+                    workingDirectory: relativePath,
+                    review,
+                    output: result.output,
+                    exitCode: result.exitCode,
+                    error: result.exitCode === 0 ? undefined : "项目命令执行失败",
+                };
+            }
+            throw new Error("不支持的 action");
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    },
+    AgentReadFileLines: async ({ guid, filePath, startLine = 1, endLine, }) => {
+        try {
+            const { target, relativePath } = resolveAgentPath(guid, filePath);
+            if (!fs.existsSync(target)) {
+                throw new Error("文件不存在");
+            }
+            if (!fs.statSync(target).isFile()) {
+                throw new Error("目标路径不是文件");
+            }
+            const lines = readTextLines(target);
+            const safeStartLine = normalizePositiveInteger(startLine, 1, "startLine");
+            const requestedEndLine = normalizePositiveInteger(endLine, Math.min(lines.length || 1, safeStartLine + 199), "endLine");
+            const safeEndLine = Math.min(requestedEndLine, safeStartLine + AGENT_FILE_MAX_READ_LINES - 1, lines.length);
+            if (requestedEndLine < safeStartLine) {
+                throw new Error("endLine 不能小于 startLine");
+            }
+            const content = lines
+                .slice(safeStartLine - 1, safeEndLine)
+                .map((line, index) => `${safeStartLine + index}: ${line}`)
+                .join("\n");
+            return {
+                success: true,
+                path: relativePath,
+                startLine: safeStartLine,
+                endLine: safeEndLine,
+                totalLines: lines.length,
+                truncated: requestedEndLine > safeEndLine,
+                content,
+            };
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    },
+    AgentWriteFile: async ({ guid, filePath, content, mode = "overwrite", }) => {
+        try {
+            const { target, relativePath } = resolveAgentPath(guid, filePath);
+            ensureParentDirectory(target);
+            if (mode === "append") {
+                fs.appendFileSync(target, content, "utf-8");
+            }
+            else if (mode === "overwrite") {
+                fs.writeFileSync(target, content, "utf-8");
+            }
+            else {
+                throw new Error("mode 只能是 overwrite 或 append");
+            }
+            return {
+                success: true,
+                path: relativePath,
+                mode,
+                bytes: Buffer.byteLength(content, "utf-8"),
+            };
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    },
+    AgentInsertFile: async ({ guid, filePath, lineNumber, content, }) => {
+        try {
+            const { target, relativePath } = resolveAgentPath(guid, filePath);
+            if (!fs.existsSync(target)) {
+                throw new Error("文件不存在");
+            }
+            if (!fs.statSync(target).isFile()) {
+                throw new Error("目标路径不是文件");
+            }
+            const lines = readTextLines(target);
+            const safeLineNumber = normalizePositiveInteger(lineNumber, 1, "lineNumber");
+            if (safeLineNumber > lines.length + 1) {
+                throw new Error("lineNumber 不能大于总行数 + 1");
+            }
+            lines.splice(safeLineNumber - 1, 0, ...content.split(/\r?\n/));
+            fs.writeFileSync(target, lines.join("\n"), "utf-8");
+            return {
+                success: true,
+                path: relativePath,
+                lineNumber: safeLineNumber,
+                insertedLines: content.split(/\r?\n/).length,
+                totalLines: lines.length,
+            };
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    },
+    AgentCreateFile: async ({ guid, filePath, content = "", overwrite = false, }) => {
+        try {
+            const { target, relativePath } = resolveAgentPath(guid, filePath);
+            const existed = fs.existsSync(target);
+            if (existed && !overwrite) {
+                throw new Error("文件已存在，如需覆盖请传 overwrite=true");
+            }
+            ensureParentDirectory(target);
+            fs.writeFileSync(target, content, "utf-8");
+            return {
+                success: true,
+                path: relativePath,
+                overwritten: existed && overwrite,
+                bytes: Buffer.byteLength(content, "utf-8"),
+            };
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    },
+    AgentDeleteFile: async ({ guid, filePath, }) => {
+        try {
+            const { target, relativePath } = resolveAgentPath(guid, filePath);
+            if (!fs.existsSync(target)) {
+                throw new Error("文件不存在");
+            }
+            if (!fs.statSync(target).isFile()) {
+                throw new Error("只能删除文件，不能删除文件夹");
+            }
+            fs.unlinkSync(target);
+            return {
+                success: true,
+                path: relativePath,
+                deleted: true,
+            };
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    },
+    AgentListFiles: async ({ guid, folderPath = ".", recursive = false, maxDepth = 3, }) => {
+        try {
+            const { root, target, relativePath } = resolveAgentPath(guid, folderPath);
+            if (!fs.existsSync(target)) {
+                throw new Error("文件夹不存在");
+            }
+            if (!fs.statSync(target).isDirectory()) {
+                throw new Error("目标路径不是文件夹");
+            }
+            const entries = [];
+            getAgentFileList(root, target, 1, recursive ? Math.max(1, Math.min(Number(maxDepth) || 3, 10)) : 1, entries);
+            return {
+                success: true,
+                path: relativePath,
+                recursive,
+                truncated: entries.length >= AGENT_FILE_MAX_LIST_ENTRIES,
+                entries,
+            };
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    },
+    AgentSearchFiles: async ({ guid, query, folderPath = ".", mode = "both", maxResults = 20, }) => {
+        try {
+            const { root, target, relativePath } = resolveAgentPath(guid, folderPath);
+            if (!query?.trim()) {
+                throw new Error("query 不能为空");
+            }
+            if (!fs.existsSync(target)) {
+                throw new Error("搜索目录不存在");
+            }
+            if (!fs.statSync(target).isDirectory()) {
+                throw new Error("搜索起点必须是文件夹");
+            }
+            const safeMaxResults = Math.max(1, Math.min(Number(maxResults) || 20, AGENT_FILE_MAX_SEARCH_RESULTS));
+            const results = searchFilesWithinWorkspace({
+                root,
+                folder: target,
+                query: query.trim(),
+                mode,
+                maxResults: safeMaxResults,
+            });
+            return {
+                success: true,
+                path: relativePath,
+                query: query.trim(),
+                mode,
+                maxResults: safeMaxResults,
+                total: results.length,
+                results,
+            };
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    },
+    AgentUploadFileToR2: async ({ guid, filePath, fileName, uploadType = "file", }) => {
+        try {
+            const { target, relativePath } = resolveAgentPath(guid, filePath);
+            if (!fs.existsSync(target)) {
+                throw new Error("文件不存在");
+            }
+            if (!fs.statSync(target).isFile()) {
+                throw new Error("只能上传文件，不能上传文件夹");
+            }
+            const url = uploadType === "image"
+                ? await uploadImageToR2(target, fileName)
+                : await uploadMediaToR2(target, fileName);
+            return {
+                success: true,
+                path: relativePath,
+                fileName: fileName || null,
+                uploadType,
+                url,
+                sendText: uploadType === "image"
+                    ? `<img=${url}>`
+                    : `文件链接: ${url}`,
+            };
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    },
     // /**
     //  * 执行eval
     //  * @param code 代码字符串