企业官网建设流程全解析

1. 项目缘起：为什么我要折腾一个叫 Agent-Reach 的东西

先坦白讲，我不是那种看到新概念就冲上去的人。AI Agent 这个词火了一年多，各种框架、平台、白皮书满天飞，我一开始的态度是观望。真正让我动手的契机，是手上几个重复性极高的活儿——每天要在几个内容平台之间来回搬运数据、整理表格、发通知、盯状态，纯手工做一天下来脑子是木的。我试过用现成的自动化工具，要么太重，要么太贵，要么就是配置复杂到让人想砸键盘。

Agent-Reach 就是在这个背景下冒出来的一个想法：能不能用一套轻量的 CLI 工具，把 AI Agent 的能力直接拉到终端里，让我在命令行里就能指挥它干活？不用打开浏览器，不用登录一堆后台，不用写几百行胶水代码。核心诉求就三个字：快、轻、稳。

这个项目本质上是一个基于 Python 构建的 AI Agent 命令行工具集，它把大模型的推理能力、工具调用能力和本地文件系统操作能力打包在一起，通过简洁的 CLI 命令暴露出来。你可以把它理解成一个"终端里的智能助手"——你告诉它要做什么，它自己规划步骤、调用工具、执行操作、返回结果。适合谁用？我觉得三类人最合适：一是像我这样天天泡在终端里的开发者，二是想入门 AI Agent 开发但被各种框架劝退的新手，三是需要快速搭建自动化流程但不想引入重型依赖的运维或数据岗位的同学。

我踩过的第一个坑就是：市面上很多 Agent 框架默认你要用它的云服务、它的 SDK、它的整套生态。Agent-Reach 的设计哲学恰恰相反——本地优先、依赖最小、可插拔。这一点在后面我会展开讲，因为它直接决定了这个项目的架构选型和实操方式。

2. 整体架构拆解：一个 CLI Agent 该怎么设计才不臃肿

2.1 核心模块划分与职责边界

Agent-Reach 的架构我反复调整过三版，前两版都因为"什么都想塞进去"而变得臃肿不堪。最终定下来的结构遵循一个原则：每个模块只做一件事，模块之间通过明确定义的接口通信。

整个项目分成四个核心层：

• CLI 交互层：负责解析命令行参数、管理会话状态、渲染输出。这一层不包含任何业务逻辑，纯粹是"翻译官"——把用户的自然语言指令翻译成内部调用，把执行结果翻译成人能看懂的格式。
• Agent 调度层：这是大脑。它接收任务描述，决定用哪个工具、按什么顺序执行、遇到错误怎么回退。调度层不直接操作文件或网络，它只做决策。
• 工具执行层：每个工具是一个独立的 Python 模块，有统一的接口定义。比如文件读写工具、命令执行工具、HTTP 请求工具、数据处理工具。新增工具不需要改调度层代码，注册一下就行。
• 模型接入层：负责和大模型 API 通信，处理 token 计算、流式输出、重试逻辑。这一层做了抽象，换模型供应商只需要改配置。

为什么这么分？因为我试过把所有逻辑塞在一个文件里，结果就是改一个功能要通读两千行代码，调试的时候根本不知道问题出在哪一层。分层之后，每层的测试可以独立进行，替换实现也不影响其他部分。

2.2 为什么选 Python 而不是其他语言

热词里有人搜"基于 rust 语言 ai agent"，我理解这种选择——Rust 性能好、内存安全、二进制分发方便。但 Agent-Reach 最终选了 Python，理由很实际：

第一，生态成熟度。Python 在 AI 领域的库支持是碾压级的。无论是调用模型 API、处理文本、解析 JSON、还是做数据清洗，Python 都有现成的轮子。用 Rust 的话，很多库要么没有，要么社区维护不活跃，你得自己造。

第二，开发迭代速度。Agent 这个领域变化太快了，今天流行的架构明天可能就被推翻。Python 的动态特性让快速试错成为可能，改一行代码就能跑，不用等编译。对于个人项目和小团队来说，这个优势比运行时性能重要得多。

第三，目标用户匹配。会用 CLI 工具的人，大概率也懂点 Python。这意味着他们可以自己写工具插件、改调度逻辑、扩展功能。如果我用 Rust 写，用户想定制就得先学 Rust，门槛直接劝退一大半人。

当然 Python 的缺点我也认——启动慢、打包体积大、并发处理不如编译型语言。但这些在 Agent 场景下不是致命问题，因为瓶颈通常在大模型推理速度上，不在语言本身。

2.3 依赖管理：少即是多

我给自己定了一条死规矩：核心依赖不超过五个。最终清单是这样的：

就这五个。没有 ORM，没有 Web 框架，没有消息队列。所有工具插件按需引入额外依赖，核心包保持干净。这样做的好处是安装快、冲突少、升级不痛苦。我见过太多项目因为依赖树太深，装个包能报一屏幕错，新手直接放弃。

提示：如果你在 Windows 上安装，建议先用python -m venv建虚拟环境，避免污染全局 Python。Linux 和 macOS 同理，虚拟环境是基本操作。

3. 核心功能实现：从零搭建一个能用的 Agent

3.1 环境准备与项目初始化

先把基础环境搭起来。我假设你已经装好了 Python，版本建议 3.9 以上，因为用到了不少新语法特性。如果你还没装，去 Python 官网下载对应系统的安装包，Windows 记得勾选"Add Python to PATH"。

# 创建项目目录 mkdir agent-reach && cd agent-reach # 创建虚拟环境 python -m venv venv # 激活虚拟环境 # Windows: venv\Scripts\activate # Linux/macOS: source venv/bin/activate # 初始化项目结构 mkdir -p src/agent_reach/{core,tools,models,utils} touch src/agent_reach/__init__.py touch src/agent_reach/core/__init__.py touch src/agent_reach/tools/__init__.py

项目结构长这样：

agent-reach/ ├── src/ │ └── agent_reach/ │ ├── __init__.py │ ├── cli.py # CLI 入口 │ ├── core/ │ │ ├── __init__.py │ │ ├── agent.py # Agent 调度核心 │ │ ├── planner.py # 任务规划 │ │ └── executor.py # 执行引擎 │ ├── tools/ │ │ ├── __init__.py │ │ ├── base.py # 工具基类 │ │ ├── file_ops.py # 文件操作 │ │ ├── shell_ops.py # 命令执行 │ │ └── http_ops.py # 网络请求 │ ├── models/ │ │ ├── __init__.py │ │ └── client.py # 模型客户端 │ └── utils/ │ ├── __init__.py │ ├── config.py # 配置管理 │ └── logger.py # 日志 ├── tests/ ├── pyproject.toml └── README.md

这个结构不是拍脑袋定的。core放调度逻辑，tools放可插拔工具，models放模型接入，utils放通用工具。每个目录职责单一，找代码的时候不用翻半天。

3.2 工具基类设计：统一接口是关键

所有工具都继承同一个基类，这样调度层可以用统一的方式调用它们。基类定义如下：

# src/agent_reach/tools/base.py from abc import ABC, abstractmethod from typing import Any, Dict class BaseTool(ABC): """所有工具的基类""" name: str = "" description: str = "" @abstractmethod def run(self, **kwargs) -> Dict[str, Any]: """执行工具，返回统一格式的结果""" pass def to_schema(self) -> Dict[str, Any]: """返回工具的 schema，供模型理解工具用途""" return { "name": self.name, "description": self.description, "parameters": self.get_parameters() } def get_parameters(self) -> Dict[str, Any]: """子类覆盖，定义参数结构""" return {}

为什么要有to_schema方法？因为大模型需要知道每个工具是干什么的、需要什么参数，才能正确调用。这个 schema 会作为提示词的一部分发给模型。没有这个，模型就是瞎猜，调用成功率极低。

我试过不用基类，每个工具各写各的，结果就是调度层要写一堆 if-else 判断工具类型，新增工具就要改调度代码。用了基类之后，调度层只认BaseTool接口，新增工具只需要注册，零改动。

3.3 文件操作工具的实现细节

拿文件操作工具举例，这是最常用的工具之一：

# src/agent_reach/tools/file_ops.py import os from pathlib import Path from typing import Any, Dict from .base import BaseTool class ReadFileTool(BaseTool): name = "read_file" description = "读取指定路径的文件内容，支持文本文件" def get_parameters(self) -> Dict[str, Any]: return { "type": "object", "properties": { "path": { "type": "string", "description": "文件路径，支持相对路径和绝对路径" }, "max_lines": { "type": "integer", "description": "最大读取行数，默认 500", "default": 500 } }, "required": ["path"] } def run(self, path: str, max_lines: int = 500) -> Dict[str, Any]: try: file_path = Path(path).expanduser().resolve() if not file_path.exists(): return {"success": False, "error": f"文件不存在: {path}"} if not file_path.is_file(): return {"success": False, "error": f"路径不是文件: {path}"} # 检查文件大小，避免读取超大文件撑爆内存 size_mb = file_path.stat().st_size / (1024 * 1024) if size_mb > 10: return { "success": False, "error": f"文件过大 ({size_mb:.1f}MB)，请指定 max_lines 或分段读取" } with open(file_path, "r", encoding="utf-8", errors="replace") as f: lines = [] for i, line in enumerate(f): if i >= max_lines: break lines.append(line.rstrip("\n")) return { "success": True, "content": "\n".join(lines), "total_lines": len(lines), "truncated": len(lines) >= max_lines } except Exception as e: return {"success": False, "error": str(e)}

这里有几个细节值得说：

路径处理用Path而不是字符串拼接。expanduser()处理~符号，resolve()转成绝对路径。跨平台兼容性好，Windows 的反斜杠和 Linux 的正斜杠都能正确处理。

文件大小检查。我踩过坑——让 Agent 读一个几百 MB 的日志文件，直接把内存吃满了。加了 10MB 上限之后，超过就提示用户分段读。

编码容错。errors="replace"保证遇到非 UTF-8 字符不会直接崩溃，而是用替换符代替。实际场景中文件编码五花八门，这个参数能省很多事。

返回统一格式。不管成功失败，都返回字典，包含success字段。调度层只需要检查这个字段就知道结果，不用 try-except 包一层。

3.4 Agent 调度核心：任务规划与执行循环

调度层是整个项目最复杂的部分。它的工作流程是这样的：

1. 接收用户输入的任务描述
2. 把任务描述和可用工具列表一起发给模型
3. 模型返回下一步该做什么（调用哪个工具、传什么参数）
4. 执行工具，把结果反馈给模型
5. 重复 3-4，直到模型认为任务完成或达到最大步数

# src/agent_reach/core/agent.py import json from typing import List, Dict, Any from ..tools.base import BaseTool from ..models.client import ModelClient class Agent: def __init__(self, model_client: ModelClient, tools: List[BaseTool], max_steps: int = 15): self.model = model_client self.tools = {tool.name: tool for tool in tools} self.max_steps = max_steps self.history: List[Dict[str, Any]] = [] def _build_system_prompt(self) -> str: tool_schemas = [tool.to_schema() for tool in self.tools.values()] return f"""你是一个命令行智能助手。你可以使用以下工具来完成任务： {json.dumps(tool_schemas, ensure_ascii=False, indent=2)} 工作规则： 1. 每次只调用一个工具，等待结果后再决定下一步 2. 如果任务已完成，返回 finish 动作并给出最终答案 3. 如果遇到无法解决的问题，返回 error 动作并说明原因 4. 不要编造工具执行结果，必须等待真实返回 输出格式必须是 JSON： {{"action": "工具名或finish或error", "params": {{...}}, "reasoning": "你的思考"}} """ def run(self, task: str) -> str: self.history = [{"role": "user", "content": task}] for step in range(self.max_steps): response = self.model.chat( system=self._build_system_prompt(), messages=self.history ) try: decision = json.loads(response) except json.JSONDecodeError: # 模型输出不是合法 JSON，尝试提取 decision = self._extract_json(response) if not decision: return f"模型输出格式错误，无法解析: {response[:200]}" action = decision.get("action") if action == "finish": return decision.get("params", {}).get("answer", "任务完成") if action == "error": return f"任务失败: {decision.get('reasoning', '未知原因')}" if action not in self.tools: self.history.append({ "role": "user", "content": f"错误：工具 '{action}' 不存在。可用工具：{list(self.tools.keys())}" }) continue # 执行工具 tool = self.tools[action] params = decision.get("params", {}) try: result = tool.run(**params) except Exception as e: result = {"success": False, "error": str(e)} self.history.append({ "role": "assistant", "content": response }) self.history.append({ "role": "user", "content": f"工具执行结果：{json.dumps(result, ensure_ascii=False)}" }) return f"达到最大步数限制 ({self.max_steps})，任务未完成"

这段代码有几个设计决策需要解释：

为什么用 JSON 格式而不是自然语言？因为解析自然语言太不可靠了。模型可能说"我打算调用 read_file 工具读取 config.json"，也可能说"接下来读取配置文件"，格式千变万化。强制 JSON 之后，解析成功率从 70% 提升到 95% 以上。

为什么限制最大步数？防止死循环。我遇到过模型在两个工具之间反复横跳，永远不结束的情况。15 步是个经验值，大部分任务 5 步内能完成，复杂的也就 10 步左右。

历史记录怎么管理？每轮把模型输出和工具结果都追加到 history 里，下一轮一起发给模型。这样模型能看到完整的执行链路，不会重复调用同一个工具。但要注意 token 消耗，history 太长会超限，后面会讲怎么处理。

3.5 模型接入层：兼容多家 API 的抽象设计

模型接入层要解决的核心问题是：不同供应商的 API 格式不一样，但上层调度逻辑不应该关心这些差异。

# src/agent_reach/models/client.py import os import requests from typing import List, Dict, Any class ModelClient: def __init__(self, provider: str = "openai", model: str = None, api_key: str = None): self.provider = provider self.model = model or os.getenv("AGENT_MODEL", "gpt-4o-mini") self.api_key = api_key or os.getenv("AGENT_API_KEY") self.base_url = os.getenv("AGENT_BASE_URL", "https://api.openai.com/v1") if not self.api_key: raise ValueError("未配置 API Key，请设置 AGENT_API_KEY 环境变量") def chat(self, system: str, messages: List[Dict[str, str]], temperature: float = 0.1) -> str: """发送对话请求，返回模型回复文本""" payload = { "model": self.model, "messages": [{"role": "system", "content": system}] + messages, "temperature": temperature, "max_tokens": 2000 } headers = { "Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json" } for attempt in range(3): try: resp = requests.post( f"{self.base_url}/chat/completions", json=payload, headers=headers, timeout=60 ) resp.raise_for_status() data = resp.json() return data["choices"][0]["message"]["content"] except requests.exceptions.Timeout: if attempt == 2: raise continue except requests.exceptions.HTTPError as e: if e.response.status_code == 429 and attempt < 2: import time time.sleep(2 ** attempt) continue raise raise RuntimeError("模型请求失败，已重试 3 次")

temperature 设成 0.1是有意为之。Agent 场景需要确定性，不需要创意。温度太高模型会胡思乱想，调用不存在的工具或者传错参数。0.1 基本能保证输出稳定。

重试逻辑处理两类错误：超时和限流。超时直接重试，限流用指数退避（1秒、2秒、4秒）。这是调用外部 API 的基本素养，不写重试的话，网络抖一下就整个任务失败。

base_url 可配置意味着你可以接任何兼容 OpenAI 格式的服务。这是行业事实标准，大部分模型供应商都支持这个格式。换供应商只需要改环境变量，代码一行不动。

4. 实操全流程：从安装到跑通第一个任务

4.1 安装与配置的完整步骤

假设你已经有了 Python 环境，下面是完整的安装流程：

# 1. 克隆项目（或从源码安装） git clone <项目地址> agent-reach cd agent-reach # 2. 创建虚拟环境 python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate # 3. 安装依赖 pip install -e . # 4. 配置环境变量 cat > .env << 'EOF' AGENT_API_KEY=你的API密钥 AGENT_MODEL=gpt-4o-mini AGENT_BASE_URL=https://api.openai.com/v1 EOF # 5. 验证安装 agent-reach --version

如果第 5 步报"command not found"，说明入口脚本没注册成功。检查pyproject.toml里的[project.scripts]配置：

[project.scripts] agent-reach = "agent_reach.cli:main"

然后重新pip install -e .。这个坑我踩过，改完配置忘了重装，折腾了半小时才发现。

4.2 CLI 入口的实现与参数设计

CLI 入口用 click 实现，支持子命令和交互模式：

# src/agent_reach/cli.py import click from rich.console import Console from rich.markdown import Markdown from .core.agent import Agent from .models.client import ModelClient from .tools.file_ops import ReadFileTool, WriteFileTool from .tools.shell_ops import ShellTool console = Console() def build_agent() -> Agent: """构建 Agent 实例，注册所有工具""" tools = [ ReadFileTool(), WriteFileTool(), ShellTool(), ] client = ModelClient() return Agent(model_client=client, tools=tools) @click.group() @click.version_option() def main(): """Agent-Reach: 终端里的 AI 智能助手""" pass @main.command() @click.argument("task", nargs=-1, required=True) @click.option("--max-steps", default=15, help="最大执行步数") def run(task, max_steps): """执行一个任务""" task_text = " ".join(task) console.print(f"[bold blue]任务:[/bold blue] {task_text}\n") agent = build_agent() agent.max_steps = max_steps with console.status("[bold green]思考中..."): result = agent.run(task_text) console.print(Markdown(result)) @main.command() def interactive(): """进入交互模式""" console.print("[bold green]Agent-Reach 交互模式[/bold green]") console.print("输入任务，输入 'exit' 退出\n") agent = build_agent() while True: try: task = console.input("[bold cyan]> [/bold cyan]") except (EOFError, KeyboardInterrupt): break if task.strip().lower() in ("exit", "quit"): break if not task.strip(): continue with console.status("[bold green]思考中..."): result = agent.run(task) console.print(Markdown(result)) console.print() if __name__ == "__main__": main()

用起来是这样的：

# 单次执行 agent-reach run "读取 config.json 文件，告诉我里面配置了哪些字段" # 交互模式 agent-reach interactive

console.status那个转圈动画不是花架子。Agent 执行任务可能要几十秒，没有反馈用户会以为卡死了。rich 库的 status 上下文管理器能在等待时显示动态提示，体验好很多。

4.3 一个完整任务的执行过程实录

我拿一个真实任务来演示。任务描述："统计当前目录下所有 Python 文件的总行数"。

第一步，模型收到任务和工具列表，返回：

{ "action": "shell", "params": {"command": "find . -name '*.py' -type f | xargs wc -l | tail -1"}, "reasoning": "用 find 找到所有 Python 文件，用 wc -l 统计行数，tail 取总计行" }

第二步，执行 shell 工具，返回结果：

{"success": true, "stdout": " 1523 total", "stderr": "", "returncode": 0}

第三步，模型看到结果，返回：

{ "action": "finish", "params": {"answer": "当前目录下所有 Python 文件总行数为 1523 行。"}, "reasoning": "已获得统计结果，任务完成" }

整个过程 3 步，耗时约 8 秒（主要花在模型推理上）。如果手动做，敲命令加看结果也就 10 秒，但 Agent 的价值在于——你不需要知道find和xargs怎么组合，你只需要描述意图。对于不熟悉命令行的用户，这个价值就体现出来了。

4.4 工具注册与扩展：新增一个工具要改哪些地方

假设我要加一个"发送 HTTP 请求"的工具，步骤是这样的：

1. 在tools/下新建http_ops.py，继承BaseTool
2. 实现run方法和get_parameters方法
3. 在cli.py的build_agent函数里注册

# src/agent_reach/tools/http_ops.py import requests from typing import Any, Dict from .base import BaseTool class HttpGetTool(BaseTool): name = "http_get" description = "发送 GET 请求获取网页内容或 API 数据" def get_parameters(self) -> Dict[str, Any]: return { "type": "object", "properties": { "url": {"type": "string", "description": "请求地址"}, "timeout": {"type": "integer", "default": 30} }, "required": ["url"] } def run(self, url: str, timeout: int = 30) -> Dict[str, Any]: try: resp = requests.get(url, timeout=timeout, headers={ "User-Agent": "Agent-Reach/1.0" }) return { "success": True, "status_code": resp.status_code, "content": resp.text[:5000], # 截断避免 token 爆炸 "truncated": len(resp.text) > 5000 } except Exception as e: return {"success": False, "error": str(e)}

然后在build_agent里加一行HttpGetTool()。完事。调度层、模型层、CLI 层都不用动。这就是接口抽象带来的好处。

注意：HTTP 工具返回内容一定要截断。我试过不截断，一个网页几万字符直接塞进上下文，token 瞬间超限，模型报错。5000 字符是个比较安全的阈值。

5. 踩坑实录与排查技巧

5.1 模型不按格式输出怎么办

这是最高频的问题。你要求模型返回 JSON，它偏偏给你一段自然语言，或者 JSON 外面包了 markdown 代码块。我的处理策略是三层防御：

第一层，提示词里明确要求"只返回 JSON，不要任何其他文字"。第二层，解析失败时尝试提取 JSON 子串（用正则匹配{...}）。第三层，如果还失败，把错误信息反馈给模型，让它重新输出。

def _extract_json(self, text: str) -> dict: """从文本中提取 JSON 对象""" import re # 去掉 markdown 代码块标记 text = re.sub(r'```json\s*|\s*```', '', text) # 尝试直接解析 try: return json.loads(text.strip()) except json.JSONDecodeError: pass # 尝试提取第一个完整的 JSON 对象 match = re.search(r'\{.*\}', text, re.DOTALL) if match: try: return json.loads(match.group()) except json.JSONDecodeError: pass return None

实测下来，加了这层防御之后，格式错误率从 30% 降到 5% 以下。剩下 5% 基本是模型彻底跑偏，重试一次就好了。

5.2 上下文超限的预防与处理

Agent 执行步数多了之后，history 会越来越长。每轮都要把完整 history 发给模型，token 消耗是平方级增长的。我的做法是：

• 工具返回结果超过 2000 字符的，截断并标注
• history 超过 20 条时，保留最近 10 条，前面的用摘要代替
• 设置单次请求的 max_tokens 上限

def _trim_history(self, max_messages: int = 20): """裁剪历史记录，保留最近的消息""" if len(self.history) <= max_messages: return # 保留第一条（原始任务）和最近的消息 first = self.history[0] recent = self.history[-(max_messages - 1):] self.history = [first] + recent

这个策略不是完美的，可能丢失中间步骤的上下文。但相比直接报错，能继续跑下去更重要。如果任务确实需要长上下文，那就得换支持更大窗口的模型，或者上向量数据库做检索增强，那是另一个话题了。

5.3 常见问题速查表

5.4 几个让我印象深刻的坑

坑一：Windows 路径分隔符。在 Linux 上跑得好好的代码，到 Windows 上文件路径全错。原因是硬编码了/。后来全部改用pathlib.Path，问题消失。跨平台项目一定要用Path，别用字符串拼路径。

坑二：shell 命令注入。早期版本直接把模型生成的命令丢给subprocess.run(shell=True)，结果模型生成了一个rm -rf开头的命令，差点把测试目录删了。后来加了命令白名单和危险命令拦截。Agent 能执行 shell 命令很强大，但安全边界必须划清楚。

坑三：模型幻觉调用不存在的工具。模型有时候会编造一个工具名，比如read_file_content（实际叫read_file）。调度层发现工具不存在后，把可用工具列表反馈给模型，它下一轮就能纠正。这个反馈机制很重要，不能直接报错退出。

坑四：并发任务的状态污染。我试过同时跑两个任务，结果 history 串了。原因是 Agent 实例是共享的。后来改成每个任务创建独立的 Agent 实例，问题解决。如果你要做并发，记住状态隔离。

6. 性能优化与进阶方向

6.1 响应速度的优化手段

Agent 的响应速度主要卡在模型推理上。能做的优化有：

流式输出。不等模型生成完整回复再处理，而是边生成边解析。这样用户能更快看到进展，体验上感觉快了很多。实现上用 SSE（Server-Sent Events）接收流式响应，逐块拼接。

工具结果缓存。同一个文件读两次，第二次直接返回缓存。对于读多写少的场景，能省不少时间。但要注意缓存失效策略，文件修改后要清除缓存。

并行工具调用。如果模型一次返回多个独立的工具调用，可以并行执行。比如同时读三个文件，串行要 3 秒，并行只要 1 秒。但这要求模型支持一次返回多个动作，目前不是所有模型都支持。

小模型做路由。用一个便宜快速的小模型判断任务类型，简单任务直接处理，复杂任务才交给大模型。这样能显著降低成本和提高速度。

6.2 安全边界的划定

Agent 能执行 shell 命令、读写文件、发网络请求，能力越大风险越大。我划了几条红线：

• 文件操作限制在工作目录内。不允许访问..上级目录，不允许操作系统关键路径。
• shell 命令白名单。只允许ls、cat、grep、find、wc等只读命令，写操作需要显式确认。
• 网络请求限制域名。默认只允许 HTTPS，可以配置域名白名单。
• 敏感信息过滤。工具返回结果里如果包含 API Key、密码等模式，自动打码。

这些限制会牺牲一些灵活性，但安全第一。我宁愿 Agent 少做点事，也不愿意它闯祸。

6.3 后续可以扩展的方向

这个项目目前是个最小可用版本，后续可以往几个方向扩展：

多模态支持。让 Agent 能处理图片、PDF、Excel 等非文本文件。这需要接入 OCR 和文档解析能力。

持久化记忆。把历史任务和结果存到本地数据库，下次遇到类似任务可以直接参考。这需要设计一套记忆检索机制。

Web UI。虽然 CLI 很酷，但不是所有人都习惯命令行。加一个轻量的 Web 界面能扩大用户群。

插件市场。让社区贡献工具插件，形成生态。这需要定义插件规范和审核机制。

多 Agent 协作。一个 Agent 负责规划，一个负责执行，一个负责审核。这种架构在复杂任务上表现更好，但复杂度也高很多。

我个人最想做的其实是持久化记忆。现在每次任务都是从零开始，Agent 不记得之前做过什么。如果能记住"上次统计行数用的是 find + wc 组合"，下次直接复用，效率会高很多。这个方向值得投入时间。

6.4 一些个人体会

做这个项目最大的收获不是技术上的，而是对 AI Agent 这个领域的理解加深了。我一开始以为 Agent 就是"大模型 + 工具调用"，做完之后发现远不止于此。真正的难点在于：怎么让模型稳定地按预期工作、怎么处理各种边界情况、怎么在灵活性和安全性之间找平衡。

还有一个体会是：不要追求一步到位。我第一版想做一个全能 Agent，结果什么都做不好。后来砍掉一半功能，专注做好文件操作和命令执行两件事，反而好用了。做项目跟做产品一样，减法比加法重要。

最后分享一个小技巧：调试 Agent 的时候，把每一轮的模型输入和输出都打到日志里。出问题的时候翻日志，比盯着终端猜快十倍。我专门写了个--debug参数，开启后打印完整对话历史。这个功能在排查问题时救了我无数次。