@saber2pr/ai-agent 0.0.15 → 0.0.16

package/README.md

@@ -80,39 +80,93 @@ await agent.chat("Scan for hardcoded colors and submit a review report.");
 
 ## 🔧 Extending with Private LLMs
 
-To use your own API protocol, extend the `BaseChatModel` from `@langchain/core`:
+### Using AgentChainModel (Recommended)
+
+For LangChain mode, extend `AgentChainModel` which provides a simplified interface for integrating custom LLMs:
 
 ```javascript
-const { BaseChatModel } = require("@langchain/core/language_models/chat_models");
+const { AgentChainModel } = require("@saber2pr/ai-agent");
+
+class MyPrivateLLM extends AgentChainModel {
+  constructor(fields) { 
+    super(fields || {}); 
+  }
 
-class MyPrivateLLM extends BaseChatModel {
-  async _generate(messages) {
+  async generateAgentChainResponse(messages) {
     const lastMessage = messages[messages.length - 1];
-    const response = await fetch("https://your-api.com/v1/chat", {
+    const queryText = lastMessage.content;
+    
+    const response = await fetch("https://your-api-gateway.com/api/completions", {
       method: 'POST',
-      body: JSON.stringify({ query: lastMessage.content }),
-      headers: { 'Authorization': `Bearer ${token}` }
+      body: JSON.stringify({ query: queryText, stream: false }),
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer YOUR_API_KEY`,
+      }
     });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`HTTP Error: ${response.status}, ${errorText}`);
+    }
+
     const data = await response.json();
-    return {
-      generations: [{ text: data.text, message: { content: data.text, role: "assistant" } }]
-    };
+    let text = data.text || "";
+    
+    // Handle special response formats if needed
+    if (text.includes("Action:") && text.includes("Final Answer:")) {
+      text = text.split("Final Answer:")[0].trim();
+    }
+    
+    return text;
   }
-  _llmType() { return "private_llm"; }
 }
-
 ```
 
+**Key Points:**
+- `AgentChainModel` abstracts away LangChain's internal message handling
+- You only need to implement `generateAgentChainResponse(messages)` which receives an array of messages
+- The method should return a plain string response
+- The base class handles conversion to LangChain's expected format
+
 ---
 
 ## 📦 Built-in Toolset
 
-| Tool              | Description                                                              |
-| ----------------- | ------------------------------------------------------------------------ |
-| `generate_review` | Finalizes the process by submitting a structured violation report.       |
-| `get_repo_map`    | Generates a high-level map of the project files and exports.             |
-| `read_text_file`  | Reads file content with line numbers for precise auditing.               |
-| `read_skeleton`   | Extracts class/function signatures without full logic (Token efficient). |
+The toolkit provides a comprehensive set of built-in tools organized into two categories: **Filesystem Tools** and **Code Analysis Tools**. All tools operate within the `targetDir` scope for security.
+
+### Filesystem Tools
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `read_text_file` | Read complete file contents as text. Supports `head` and `tail` parameters for partial reading. Handles various text encodings. | `path` (required), `head?`, `tail?` |
+| `read_multiple_files` | Read multiple files simultaneously for efficient batch analysis. Individual failures won't stop the operation. | `paths` (array, required) |
+| `write_file` | Create a new file or completely overwrite an existing file. Use with caution as it overwrites without warning. | `path` (required), `content` (required) |
+| `edit_file` | Make line-based edits to a text file. Replaces exact line sequences with new content. Returns git-style diff. Supports `dryRun` mode for preview. | `path` (required), `edits` (array, required), `dryRun?` |
+| `get_directory_tree` | Get a recursive tree view of files and directories as JSON. Supports `excludePatterns` for filtering (minimatch patterns). Essential for understanding project structure. | `path` (required), `excludePatterns?` (array) |
+| `list_directory` | List all files and directories in a specified path. Results distinguish files and directories with `[FILE]` and `[DIR]` prefixes. | `path` (required) |
+| `list_directory_with_sizes` | List directory contents with file sizes. Supports sorting by name or size. Includes summary statistics. | `path` (required), `sortBy?` ("name" \| "size") |
+| `search_files` | Search for files matching a glob pattern. Supports exclude patterns for filtering. | `path` (required), `pattern` (required), `excludePatterns?` (array) |
+| `move_file` | Move or rename files and directories. Can move between directories and rename in a single operation. | `source` (required), `destination` (required) |
+| `create_directory` | Create a new directory or ensure it exists. Can create multiple nested directories recursively. | `path` (required) |
+| `get_file_info` | Get detailed metadata about a file: size, last modified time, type, etc. | `path` (required) |
+
+### Code Analysis Tools
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `get_repo_map` | Generate a high-level map of project files and exports. Extracts export definitions to understand module relationships. Use this first to understand project structure. | None |
+| `read_skeleton` | Extract structural definitions (interfaces, classes, method signatures) without implementation details. Token-efficient for code analysis. | `filePath` (required) |
+| `analyze_deps` | Analyze dependency relationships for a specific file. Supports TypeScript path alias resolution via tsconfig. | `filePath` (required) |
+| `get_method_body` | Get the complete implementation code for a specific method or function within a file. | `filePath` (required), `methodName` (required) |
+
+### Tool Usage Tips
+
+1. **Start with `get_directory_tree`**: Always begin by understanding the project structure before reading files.
+2. **Use `read_skeleton` before `read_text_file`**: Extract signatures first to save tokens, then read full content only when needed.
+3. **Leverage `excludePatterns`**: Use minimatch patterns to exclude `node_modules`, `.git`, build artifacts, etc.
+4. **Batch operations**: Use `read_multiple_files` when analyzing multiple files to improve efficiency.
+5. **Preview changes**: Use `edit_file` with `dryRun: true` to preview changes before applying them.
 
 ---
 

package/lib/core/agent-chain.d.ts

@@ -11,6 +11,7 @@ export default class McpChainAgent {
     private memory?;
     private systemPrompt;
     private runningTokenCounter;
+    private verbose;
     constructor(options?: AgentOptions);
     private initTools;
     private wrapHandler;

package/lib/core/agent-chain.js

@@ -39,14 +39,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const fs_1 = __importDefault(require("fs"));
 const js_tiktoken_1 = require("js-tiktoken");
 const agents_1 = require("langchain/agents");
+const memory_1 = require("langchain/memory");
+const readline = __importStar(require("readline"));
 const prompts_1 = require("@langchain/core/prompts");
 const tools_1 = require("@langchain/core/tools");
 const openai_1 = require("@langchain/openai");
-const memory_1 = require("langchain/memory");
-const readline = __importStar(require("readline"));
 const config_1 = require("../config/config");
-const jsonSchemaToZod_1 = require("../utils/jsonSchemaToZod");
 const builtin_1 = require("../tools/builtin");
+const jsonSchemaToZod_1 = require("../utils/jsonSchemaToZod");
 class McpChainAgent {
     constructor(options) {
         this.allTools = [];
@@ -58,6 +58,7 @@ class McpChainAgent {
         this.apiConfig = options === null || options === void 0 ? void 0 : options.apiConfig;
         this.maxIterations = (options === null || options === void 0 ? void 0 : options.maxIterations) || 20;
         this.apiModel = options === null || options === void 0 ? void 0 : options.apiModel;
+        this.verbose = (options === null || options === void 0 ? void 0 : options.verbose) || false;
         const baseSystemPrompt = `你是一个专业的代码架构师。
 你的目标是理解并分析用户项目，请务必遵循以下工作流：
 
@@ -119,6 +120,7 @@ class McpChainAgent {
             // 必须添加下面这两行显式声明：
             inputKey: "input", // 对应 invoke 里的 input 字段
             outputKey: "output", // 对应 Agent 输出的字段
+            chatHistory: new memory_1.ChatMessageHistory(), // 👈 显式指定 history 实例
         });
         const langchainTools = this.allTools.map(t => new tools_1.DynamicStructuredTool({
             name: t.function.name,
@@ -126,37 +128,44 @@ class McpChainAgent {
             schema: (0, jsonSchemaToZod_1.jsonSchemaToZod)(t.function.parameters),
             func: async (args) => await t._handler(args),
         }));
-        // 2. 构造支持 Memory 的 Prompt
         const prompt = prompts_1.PromptTemplate.fromTemplate(`{system_prompt}
 
-### 历史记录摘要及近期对话：
-{chat_history}
-
-### 可用工具：
+### 🛠 可用工具：
 {tools}
 
-工具名称列表: [{tool_names}]
+### 🛠 工具名称：
+[{tool_names}]
+
+### 📝 历史记录：
+{chat_history}
+
+### ⚠️ 回复规范（严格遵守）：
+1. 首先输出 **Thought:**，用中文详细说明你的分析思路。
+2. 接着输出一个 **JSON Action 代码块**。
 
-### 交互协议：
-Thought: [你的中文分析思路]
+示例格式：
+Thought: 正在查看目录。
 \`\`\`json
 {{
-  "action": "工具名称",
-  "action_input": {{ "参数名": "参数值" }}
+  "action": "directory_tree",
+  "action_input": {{}}
 }}
 \`\`\`
 
 Begin!
 Question: {input}
-Thought: {agent_scratchpad}`);
+{agent_scratchpad}`); // 👈 强制以 Thought: 开头，解决断更问题
         const agent = await (0, agents_1.createStructuredChatAgent)({ llm: model, tools: langchainTools, prompt });
         this.executor = new agents_1.AgentExecutor({
             agent,
             tools: langchainTools,
             memory: this.memory, // 挂载内存模块
-            verbose: false,
-            handleParsingErrors: true,
-            maxIterations: this.maxIterations
+            verbose: this.verbose,
+            maxIterations: this.maxIterations,
+            handleParsingErrors: (e) => {
+                // 简化报错，不要再给 AI 错误的 JSON 示例
+                return `格式不正确。请确保你输出了一个正确的 Markdown JSON 代码块，例如：\n\`\`\`json\n{ "action": "...", "action_input": { ... } }\n\`\`\``;
+            },
         });
     }
     async chat(input) {
@@ -174,9 +183,13 @@ Thought: {agent_scratchpad}`);
             }, {
                 callbacks: [{
                         handleAgentAction: (action) => {
-                            const thought = action.log.split(/```json|\{/)[0].replace(/Thought:/i, "").trim();
-                            if (thought && !thought.startsWith('{')) {
-                                console.log(`\n💭 [思考]: ${thought.split('\n')[0]}`);
+                            const rawLog = action.log || "";
+                            // 兼容 Thought: Thought: [内容]
+                            let thought = rawLog.split(/```json|\{/)[0]
+                                .replace(/Thought:/gi, "") // 全局替换掉所有 Thought: 标签
+                                .trim();
+                            if (thought) {
+                                console.log(`\n💭 [思考]: ${thought}`);
                             }
                         }
                     }]

package/lib/index.d.ts

@@ -2,3 +2,4 @@ export * from './core/agent';
 export { default as McpChainAgent } from './core/agent-chain';
 export { default } from './core/agent';
 export { createTool } from './utils/createTool';
+export { AgentChainModel } from './model/AgentChainModel';

package/lib/index.js

@@ -17,7 +17,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createTool = exports.default = exports.McpChainAgent = void 0;
+exports.AgentChainModel = exports.createTool = exports.default = exports.McpChainAgent = void 0;
 __exportStar(require("./core/agent"), exports);
 var agent_chain_1 = require("./core/agent-chain");
 Object.defineProperty(exports, "McpChainAgent", { enumerable: true, get: function () { return __importDefault(agent_chain_1).default; } });
@@ -25,3 +25,5 @@ var agent_1 = require("./core/agent");
 Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(agent_1).default; } });
 var createTool_1 = require("./utils/createTool");
 Object.defineProperty(exports, "createTool", { enumerable: true, get: function () { return createTool_1.createTool; } });
+var AgentChainModel_1 = require("./model/AgentChainModel");
+Object.defineProperty(exports, "AgentChainModel", { enumerable: true, get: function () { return AgentChainModel_1.AgentChainModel; } });

package/lib/model/AgentChainModel.d.ts

@@ -0,0 +1,18 @@
+import { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import { AIMessage, MessageFieldWithRole } from "@langchain/core/messages";
+interface AgentChainModelImpl {
+    generateAgentChainResponse: (messages: MessageFieldWithRole[]) => Promise<string>;
+}
+export declare abstract class AgentChainModel extends BaseChatModel implements AgentChainModelImpl {
+    bind(args: any): any;
+    constructor(fields?: any);
+    generateAgentChainResponse(messages: MessageFieldWithRole[]): Promise<string>;
+    _generate(messages: any): Promise<{
+        generations: {
+            text: string;
+            message: AIMessage;
+        }[];
+    }>;
+    _llmType(): string;
+}
+export {};

package/lib/model/AgentChainModel.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentChainModel = void 0;
+const chat_models_1 = require("@langchain/core/language_models/chat_models");
+const messages_1 = require("@langchain/core/messages");
+class AgentChainModel extends chat_models_1.BaseChatModel {
+    bind(args) {
+        // 逻辑上调用基类（即使基类在类型上说没有，运行时通常是有的）
+        // 如果运行时也没有，这里就返回 this 本身
+        // @ts-ignore
+        return (super.bind ? super.bind(args) : this);
+    }
+    constructor(fields) { super(fields || {}); }
+    async generateAgentChainResponse(messages) {
+        return '';
+    }
+    async _generate(messages) {
+        let text = await this.generateAgentChainResponse(messages);
+        return { generations: [{ text, message: new messages_1.AIMessage(text) }] };
+    }
+    _llmType() { return "my_private_llm"; }
+}
+exports.AgentChainModel = AgentChainModel;

package/lib/tools/filesystem/index.js

@@ -7,6 +7,7 @@ exports.getFilesystemTools = void 0;
 const zod_1 = require("zod");
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
+const zod_to_json_schema_1 = require("zod-to-json-schema");
 const createTool_1 = require("../../utils/createTool");
 const minimatch_1 = require("minimatch");
 const lib_1 = require("./lib");
@@ -89,7 +90,7 @@ const getFilesystemTools = (targetDir) => {
             "the contents of a single file. Use the 'head' parameter to read only " +
             "the first N lines of a file, or the 'tail' parameter to read only " +
             "the last N lines of a file. Operates on the file as text regardless of extension.",
-        parameters: ReadTextFileArgsSchema.toJSONSchema(),
+        parameters: (0, zod_to_json_schema_1.zodToJsonSchema)(ReadTextFileArgsSchema, 'ReadTextFileArgsSchema'),
         validateParams: ["path"],
         handler: readTextFileHandler
     });
@@ -100,7 +101,7 @@ const getFilesystemTools = (targetDir) => {
             "or compare multiple files. Each file's content is returned with its " +
             "path as a reference. Failed reads for individual files won't stop " +
             "the entire operation. Only works within allowed directories.",
-        parameters: ReadMultipleFilesArgsSchema.toJSONSchema(),
+        parameters: (0, zod_to_json_schema_1.zodToJsonSchema)(ReadMultipleFilesArgsSchema, 'ReadMultipleFilesArgsSchema'),
         validateParams: ["paths"],
         handler: async (args) => {
             const results = await Promise.all(args.paths.map(async (filePath) => {
@@ -123,7 +124,7 @@ const getFilesystemTools = (targetDir) => {
         description: "Create a new file or completely overwrite an existing file with new content. " +
             "Use with caution as it will overwrite existing files without warning. " +
             "Handles text content with proper encoding. Only works within allowed directories.",
-        parameters: WriteFileArgsSchema.toJSONSchema(),
+        parameters: (0, zod_to_json_schema_1.zodToJsonSchema)(WriteFileArgsSchema, 'WriteFileArgsSchema'),
         validateParams: ["path", "content"],
         handler: async (args) => {
             const validPath = await (0, lib_1.validatePath)(targetDir, args.path);
@@ -137,7 +138,7 @@ const getFilesystemTools = (targetDir) => {
         description: "Make line-based edits to a text file. Each edit replaces exact line sequences " +
             "with new content. Returns a git-style diff showing the changes made. " +
             "Only works within allowed directories.",
-        parameters: EditFileArgsSchema.toJSONSchema(),
+        parameters: (0, zod_to_json_schema_1.zodToJsonSchema)(EditFileArgsSchema, 'EditFileArgsSchema'),
         validateParams: ["path", "edits"],
         handler: async (args) => {
             const validPath = await (0, lib_1.validatePath)(targetDir, args.path);
@@ -151,7 +152,7 @@ const getFilesystemTools = (targetDir) => {
             "nested directories in one operation. If the directory already exists, " +
             "this operation will succeed silently. Perfect for setting up directory " +
             "structures for projects or ensuring required paths exist. Only works within allowed directories.",
-        parameters: CreateDirectoryArgsSchema.toJSONSchema(),
+        parameters: (0, zod_to_json_schema_1.zodToJsonSchema)(CreateDirectoryArgsSchema, 'CreateDirectoryArgsSchema'),
         validateParams: ["path"],
         handler: async (args) => {
             const validPath = await (0, lib_1.validatePath)(targetDir, args.path);
@@ -166,7 +167,7 @@ const getFilesystemTools = (targetDir) => {
             "Results clearly distinguish between files and directories with [FILE] and [DIR] " +
             "prefixes. This tool is essential for understanding directory structure and " +
             "finding specific files within a directory. Only works within allowed directories.",
-        parameters: ListDirectoryArgsSchema.toJSONSchema(),
+        parameters: (0, zod_to_json_schema_1.zodToJsonSchema)(ListDirectoryArgsSchema, 'ListDirectoryArgsSchema'),
         validateParams: ["path"],
         handler: async (args) => {
             const validPath = await (0, lib_1.validatePath)(targetDir, args.path);
@@ -183,7 +184,7 @@ const getFilesystemTools = (targetDir) => {
             "Results clearly distinguish between files and directories with [FILE] and [DIR] " +
             "prefixes. This tool is useful for understanding directory structure and " +
             "finding specific files within a directory. Only works within allowed directories.",
-        parameters: ListDirectoryWithSizesArgsSchema.toJSONSchema(),
+        parameters: (0, zod_to_json_schema_1.zodToJsonSchema)(ListDirectoryWithSizesArgsSchema, 'ListDirectoryWithSizesArgsSchema'),
         validateParams: ["path"],
         handler: async (args) => {
             const validPath = await (0, lib_1.validatePath)(targetDir, args.path);
@@ -238,7 +239,7 @@ const getFilesystemTools = (targetDir) => {
             "Each entry includes 'name', 'type' (file/directory), and 'children' for directories. " +
             "Files have no children array, while directories always have a children array (which may be empty). " +
             "The output is formatted with 2-space indentation for readability. Only works within allowed directories.",
-        parameters: DirectoryTreeArgsSchema.toJSONSchema(),
+        parameters: (0, zod_to_json_schema_1.zodToJsonSchema)(DirectoryTreeArgsSchema, 'DirectoryTreeArgsSchema'),
         validateParams: ["path"],
         handler: async (args) => {
             const rootPath = args.path;
@@ -283,7 +284,7 @@ const getFilesystemTools = (targetDir) => {
             "and rename them in a single operation. If the destination exists, the " +
             "operation will fail. Works across different directories and can be used " +
             "for simple renaming within the same directory. Both source and destination must be within allowed directories.",
-        parameters: MoveFileArgsSchema.toJSONSchema(),
+        parameters: (0, zod_to_json_schema_1.zodToJsonSchema)(MoveFileArgsSchema, 'MoveFileArgsSchema'),
         validateParams: ["source", "destination"],
         handler: async (args) => {
             const validSourcePath = await (0, lib_1.validatePath)(targetDir, args.source);
@@ -297,7 +298,7 @@ const getFilesystemTools = (targetDir) => {
         name: "search_files",
         description: "Search for files matching a specific pattern in a specified path. " +
             "Returns a list of files that match the pattern. Only works within allowed directories.",
-        parameters: SearchFilesArgsSchema.toJSONSchema(),
+        parameters: (0, zod_to_json_schema_1.zodToJsonSchema)(SearchFilesArgsSchema, 'SearchFilesArgsSchema'),
         validateParams: ["path", "pattern"],
         handler: async (args) => {
             const validPath = await (0, lib_1.validatePath)(targetDir, args.path);
@@ -310,7 +311,7 @@ const getFilesystemTools = (targetDir) => {
         name: "get_file_info",
         description: "Get detailed information about a file, including its size, last modified time, and type. " +
             "Only works within allowed directories.",
-        parameters: GetFileInfoArgsSchema.toJSONSchema(),
+        parameters: (0, zod_to_json_schema_1.zodToJsonSchema)(GetFileInfoArgsSchema, 'GetFileInfoArgsSchema'),
         validateParams: ["path"],
         handler: async (args) => {
             const validPath = await (0, lib_1.validatePath)(targetDir, args.path);

package/lib/types/type.d.ts

@@ -1,4 +1,3 @@
-import { BaseChatModel } from "@langchain/core/language_models/chat_models";
 import { Client } from "@modelcontextprotocol/sdk/client/index";
 export interface ApiConfig {
     baseURL: string;
@@ -27,12 +26,24 @@ export interface McpConfig {
 }
 export interface AgentOptions {
     targetDir?: string;
-    /** 外部传入的内置工具列表，不传则使用默认的 registerBuiltinTools */
     tools?: ToolInfo[];
     extraSystemPrompt?: any;
     maxTokens?: number;
+    /**
+     * only for chain agent
+     */
     apiConfig?: ApiConfig;
-    apiModel?: BaseChatModel;
+    /**
+     * only for chain agent
+     * extends BaseChatModel
+     */
+    apiModel?: any;
+    /**
+     * only for chain agent
+     */
     maxIterations?: number;
+    /**
+     * only for chain agent
+     */
     verbose?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saber2pr/ai-agent",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "AI Assistant CLI.",
   "author": "saber2pr",
   "license": "ISC",
@@ -22,16 +22,21 @@
     "prepublishOnly": "tsc"
   },
   "dependencies": {
-    "@langchain/core": "^1.1.18",
-    "@langchain/openai": "^1.2.4",
     "@modelcontextprotocol/sdk": "^1.25.3",
     "@saber2pr/ts-context-mcp": "^0.0.8",
     "diff": "^8.0.3",
     "glob": "^10.5.0",
     "js-tiktoken": "^1.0.21",
-    "langchain": "~0.3",
     "minimatch": "^10.0.1",
-    "openai": "^6.16.0"
+    "openai": "^6.16.0",
+    "zod-to-json-schema": "3.23.2",
+    "langchain": "0.3.15",
+    "@langchain/core": "0.3.39",
+    "@langchain/openai": "0.4.0",
+    "zod": "3.23.8"
+  },
+  "resolutions": {
+    "@langchain/core": "0.3.39"
   },
   "devDependencies": {
     "@types/node": "^16.3.3",