. 背景

使用者痛点：市面上已有的 Agent 框架往往「开箱即用」却缺乏安全防护和可 性，导致公司在实际落地时面临「AI 越权执行」和「难以维护」的风险。

去年开始 AI Agent 概念大火，各种框架层出不穷。但与其直接用现成的 Agent 框架。不如亲手从零搭建一个——既能 AI Agent 的工作原理，又能把控安全、 性等工程细节。说起来，

这个项目是个人的练手项目。基于 Turborepo Monorepo包含一个 Express.js API 后端和一个 Vue 前端。主要目标是建立一个安全、可 的 AI Agent 网站让它能自主执行文件操作、运行 Shell 命令、加载专业技能、甚至创建子智能体来并行处理任务。

再看源码地址，express-turbo-monorepo

. 技术栈选型

选择这些技术栈的理由：

• Express : 轻量灵活，适合理解 Agent 的请求-响应生命周期。
• Vercel AI SDK: 提供高阶抽象 ToolLoopAgent。自动循环调用工具，无需手动管理多轮逻辑。
• Turborepo: 天然支持 apps/* 多包结构，API 和前端共享配置。
• bubblewrap 沙箱: 使用 Linux 内核命名空间实现真正的文件程序和网络隔离。
• Pain Point — 缺乏统一日志 & 可观测性： Pino 为每一次工具调用提供结构化审计日志，满足合规需求。
• Pain Point — 环境一致性： Docker 多阶段建立确保本地/生产环境行为一致。

. 项目结构

express-turbo-monorepo/
├── apps/
│ └── api/ # Express.js API 服务
│ ├── src/
│ │ ├── index.ts # 应用入口点
│ │ ├── app.ts # Express 应用工厂
│ │ ├── errors/ # 错误处理
│ │ ├── lib/ # 工具库
│ │ ├── middleware/ # 中间件
│ │ ├── modules/ # 功能模块
│ │ │ ├── chat/ # AI 对话模块
│ │ │ └── skills/ # Skills 管理模块
│ │ ├── sandbox/ # 沙箱运行时
│ │ ├── skills/ # Skills 发现与加载
│ │ ├── tools/ # AI 工具定义
│ │ ├── schema/ # Zod 校验规则
│ │ └── util/ # 工具函数
│ └── package.json
│ └── dev-web/ # Vue 前端
├── turbo.json # Turborepo 配置
└── package.json

每个模块采用一致的文件结构：

/
.module.ts # 路由注册
.routes.ts # 路由定义
.controller.ts # 请求处理
.service.ts # 业务逻辑
/

. 主要功能详解

AI 对话与工具调用

The project leverages Vercel AI SDK’s ToolLoopAgent。enabling agent to iterate automatically:

• A思考 → 调用工具 → 获取结果 → 再思考
• The loop stops when task is completed or when a step limit is reached.
• This design directly addresses **pain point of uncontrolled token consumption** by limiting steps and compressing tool results.
)

const { text,steps } = streamText({
至于model，provider,system: agentSystemPrompt,tools: agentTools,maxSteps: MAX_STEPS,onStepFinish: => {
// 每个 step 完成后压缩历史结果，节省 token
return compressToolResults;},})，

Cores design points:

• S​tep Upper‑bound： 防止无限循环。
• S​tool Result Compression： 当历史结果字符数超过阈值时用简短提示替代，仅保留最近 N 条完整记录。话说回来，
• {大结果持久化}：当输出超过设定字符数时自动写入磁盘。并返回「预览 + 文件方法」给模型，解决**长文本导致上下文截断**的问题。按理说，

内置工具一览

...

沙箱安全执行

This is most critical design. Direct execution of shell commands on host would be disastrous.

Pain Point — “AI 能直接破坏宿主程序”： 双层防护机制将此类风险降到最低。话说回来，

A. 应用层权限过滤

const permissionRules: PermissionRule =;


// 在 ToolExecutor 中统一拦截判断...
if ) throw new ForbiddenError;if ) await requestHumanApproval;else executeTool;

B. 程序级沙箱   


• *文件程序限制*: Only SANDBOX_DIR / AGENTS_DIR ….

• *写保护*: .env 、*.pem 、*.key 等关键文件不可覆盖。

• *网络限制*: 域名白名单 / 黑名单策略。

• *深度防护*: mandatoryDenySearchDepth 防止符号链接逃逸。

Human-in--Loop 审批程序   

This component bridges gap 娱乐ween “full autonomy” and “complete manual control”. Four chat modes let users pick a safety‑vs‑speed trade‑off.



# 模式
#读操作
#写操作
#适用场景

"default"- 所有写操作均需要人工审批；最安全，怎么说呢，适用于生产环境。
说起来，

"plan"- 禁止任何写入。只做只读探索，适用于调研或代码审计。

"auto"- 写入默认自动批准，但仍保留“拒绝”按钮；适用于内部测试，

"yolo"- 完全信任，不做任何审批；仅在受信任环境下使用，json
{ "prompt":"帮我创建一个 React组件","metadata":{"mode":"yolo"} }
在前端。当工具需要审批时会弹出带有 **批准 / 拒绝** 按钮的气泡，对话在使用者确认后继续。

Skills 动态加载程序   

A Skill = a directory containing a S K I L L . md ​\​` file that describes domain‑specific knowledge.
agents/
├─ python-developer/
├─ react-optimizer/
└─ SKILL.md


至于*自动发现*，启动时遍历 $AGENTS_DIR/*/SKILL.md<\/ code>

*ZIP 上传／下载／删除*：通过 Skills Module API 管理 Skill 包装体。

* *运行时注入*：loadSkill 工具把 Skill 内容拼接进 system prompt，让模型即时拥有新能力。其实，​

子智能体
text
使用者的观点是。"帮我分析这个项目的代码结构并生成文档"
→ 主 Agent 创建计划
→ 子 Agent A：探索 src/tools/
→ 子 Agent B：探索 src/modules/
→ 子 Agent C：阅读 package.json 与配置文件
→ 汇果 → 主 Agent 输出完整文档。


Each sub‑agent runs in its own sandbox instance.

Sub‑agents receive a subset of tools to limit privilege.

After finishing y return a structured summary which parent agent merges.


OpenAPI / Swagger 文档

typescript
new OpenApiRegistryZodExtensions();

Visit /docs for an interactive Swagger UI generated directly from Zod schemas—no manual YAML maintenance.

. 架构设计要点 

. 工厂模式 

// app.ts
export function createApp {
const app = express;app.use)，app.use);app.use，app.use);app.get=>{res.json;})，app.use;说起来，app.use，app.use;app.use，app.use;return app，}



统一响应与错误码

typescript
interface ApiJsonResponse{
responseCode:string;// "" 成功，其它为错误码
responseMsg:string;// 描述信息
data这方面，T;}


环境变量即配置

typescript
const envSchema = z.object({
PORT这方面。z.coerce.number.default,OPENAI_API_KEY:z.string.min,OPENAI_BASE_URL:z.string.url,SANDBOX_ENABLED:z.coerce.boolean.default,//…more configs
});

. Docker 部署 

# Multi-stage build – Builder
FROM node:-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev && npm install -g typescript && npm run build


FROM node:-alpine
RUN apk add --no-cache bash ripgrep bubblewrap socat
COPY --from=builder /app/dist ./dist
CMD
``
**关键点**：因为沙箱依赖 bubblewrap。需要在容器启动时授予SYSADMIN与NETADMIN` 权限：

bash
docker run --cap-add=SYS_ADMIN --cap-add=NET_ADMIN -p8080:8080 your-image


. 开发流程与规范 



类型优先：Zod 定义即 TypeScript 类型，所有业务代码引用统一 schema，提高可维护性。老实说，

b工具函数复用：src/util/* 集中抽象通用逻辑。禁止 Copy‑Paste。老实说，

b错误码同步：AppErrorCode 与 ApiResponseCode 必须保持一一对应。以免前端误判状态，

b模块自包含：modules/* 各自注册到 app.ts通过接口通信避免耦合。

b提交前检查：npm run typecheck && npm run lint && npm run test 必须全部通过方可 merge。

⚠️ 缺少统一错误程序会导致调试成本激增——本项目通过统一响应格式解决此痛点。话说回来，



收获与思考