@kenhkl/agent-gate
v0.6.3
Published
AI Agent data collection & security analysis gateway (TypeScript)
Readme
AgentGate (TypeScript)
AI Agent 数据采集与安全分析中间层服务 — TypeScript 版
AgentGate 是一个独立常驻服务，位于 AI Agent 与 AgentMoss 之间：接收 Agent 的工具调用数据，采集系统上下文，转换格式后提交 AgentMoss 安全分析，回传 Allow/Deny 决策。
┌──────────────┐ HTTP ┌──────────────────┐ HTTP ┌─────────────┐
│ AI Agent │── AgentGate ──▶│ AgentGate │── Analyze ──▶│ AgentMoss │
│ (任意Agent) │ Input │ (独立服务) │ Request │ (安全分析) │
│ │◀─ Response ──│ · 系统上下文采集 │◀─ Response ──│ │
└──────────────┘ │ · 格式标准化 │ └─────────────┘
│ · 决策缓存 │
│ · Session 存储 │
│ · Dashboard │
└──────────────────┘1. 安装
npm 安装
npm install @kenhkl/agent-gate安装后 agent-gate 命令即可用。
从源码构建
git clone [email protected]:kenhkl/AgentGate.git
cd AgentGate/ts
npm install
npm run build2. 启动服务
AgentGate 是一个独立常驻服务，支持以下运行方式：
2.1 前台运行（测试/开发）
# 方式 1: 直接运行（占用终端）
agent-gate gateway --config config/agent_gate.yaml
# 方式 2: 使用 npm script
npm run dev:gateway
# 方式 3: 使用 tsx（开发模式，自动重启）
npx tsx src/cli.ts gateway --config config/agent_gate.yaml2.2 后台运行（日常使用）
方式 1: nohup（简单）
# 后台运行，日志输出到文件
nohup agent-gate gateway --config config/agent_gate.yaml > logs/gateway_ts.log 2>&1 &
# 查看进程 ID
echo $!
# 查看日志
tail -f logs/gateway_ts.log
# 停止服务
pkill -f "agent-gate gateway"
# 或使用进程 ID
kill <PID>方式 2: screen/tmux（推荐）
# 使用 screen
screen -S agentgate-ts
agent-gate gateway --config config/agent_gate.yaml
# 按 Ctrl+A+D 分离会话（服务继续运行）
# 重新连接: screen -r agentgate-ts
# 使用 tmux
tmux new -s agentgate-ts
agent-gate gateway --config config/agent_gate.yaml
# 按 Ctrl+B+D 分离会话（服务继续运行）
# 重新连接: tmux attach -t agentgate-ts2.3 systemd 服务（生产环境）
适用于长期部署、开机自启动场景。
安装 systemd 服务
# 使用安装脚本
bash scripts/install-systemd-ts.sh
# 或手动安装（需要 sudo）
sudo cp deploy/agentgate-ts.service.template /etc/systemd/system/agentgate-ts.service
sudo systemctl daemon-reload
sudo systemctl start agentgate-ts服务管理命令
# 启动服务
sudo systemctl start agentgate-ts
# 停止服务
sudo systemctl stop agentgate-ts
# 重启服务
sudo systemctl restart agentgate-ts
# 查看状态
sudo systemctl status agentgate-ts
# 查看日志
tail -f logs/gateway_ts.log
# 开机自启动
sudo systemctl enable agentgate-ts
# 禁用开机自启动
sudo systemctl disable agentgate-ts卸载 systemd 服务
# 使用卸载脚本
bash scripts/uninstall-systemd-ts.sh
# 或手动卸载
sudo systemctl stop agentgate-ts
sudo systemctl disable agentgate-ts
sudo rm /etc/systemd/system/agentgate-ts.service
sudo systemctl daemon-reload2.4 检查服务状态
# 使用状态检查脚本
bash scripts/status-agentgate-ts.sh
# 或手动检查
curl http://127.0.0.1:9110/health
curl http://127.0.0.1:9110/api/stats2.1 启动 AgentMoss
# HTTP 模式（默认端口 9090）
agent-moss server --mode http --port 9090验证：
curl http://127.0.0.1:9090/api/v1/health2.2 启动 AgentGate
# HTTP 模式（默认端口 9100）
agent-gate server
# 自定义端口和地址
agent-gate server --host 0.0.0.0 --port 9100
# 指定 AgentMoss 地址
agent-gate server --moss-url http://127.0.0.1:9090
# 指定数据库路径
agent-gate server --db-path /tmp/agent_gate_ts.db验证：
curl http://127.0.0.1:9100/api/v1/health
# → {"status":"healthy","version":"0.2.1"}2.3 CLI 参数
| 参数 | 默认值 | 说明 |
|------|--------|------|
| --host <host> | 127.0.0.1 | 监听地址 |
| --port <port> | 9100 | 监听端口 |
| --db-path <path> | 自动（见下表） | SQLite 数据库路径 |
| --moss-url <url> | http://127.0.0.1:9090 | AgentMoss 服务地址 |
--moss-url 也支持通过环境变量 MOSS_URL 设置（CLI 参数优先）。
2.4 数据清理
# 清理 30 天前的记录（默认）
agent-gate clean
# 自定义保留天数
agent-gate clean --retention-days 72.5 数据存储路径
独立使用 agent_gate_ts.db，避免与 Python 版 WAL 隔离冲突。
| 场景 | 实际路径 |
|------|----------|
| 默认 | ~/.local/share/agent_gate/agent_gate_ts.db |
| 自定义 | --db-path <path> 指定 |
3. 开发
cd ts
npm install
# 开发模式（tsx 直接运行，端口 9100）
npm run dev
# 构建
npm run build
# 构建产物在 dist/ 下构建工具：tsup，输出 ESM 格式，better-sqlite3 作为 external 不打包。
4. API 接口
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/v1/analyze | 安全分析（核心接口） |
| GET | /api/v1/health | 健康检查 |
| GET | /api/v1/sessions/:id/traces | 查询 session 调用轨迹 |
| GET | /api/v1/tool_calls | 条件查询工具调用记录 |
| GET | /api/v1/agents | 查询 agent 列表及统计 |
| GET | /api/v1/timeline | Allow/Deny 时间线（按分钟聚合） |
| GET | /dashboard/ | 可视化面板 |
请求格式
{
"agent_type": "opendesk",
"agent_version": "1.0",
"session_id": "session-abc",
"tool_name": "bash",
"command": "rm -rf /tmp/cache/*",
"cwd": "/home/user/project",
"description": "清理缓存",
"user_prompt": "清理项目临时文件",
"action_history": [],
"metadata": {}
}| 字段 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| agent_type | string | 是 | — | Agent 标识（如 opendesk, claude-code） |
| agent_version | string | 否 | 0.1.0 | Agent 版本 |
| session_id | string | 是 | — | Session 标识 |
| tool_name | string | 否 | — | 工具名称（如 bash, file_write） |
| command | string | 否 | — | 工具命令或描述 |
| a_next | object | 否 | — | {action_type, action_detail}，Python API 兼容格式 |
| cwd | string | 否 | "" | 当前工作目录 |
| description | string | 否 | "" | 描述 |
| user_prompt | string | 否 | "" | 用户 prompt |
| action_history | array | 否 | [] | 历史动作（同 session 自动累积） |
| metadata | object | 否 | — | 附加元数据 |
tool_name/command和a_next.action_type/a_next.action_detail两种格式均支持，前者优先。
响应格式
{
"decision": "Deny",
"reason": "检测到递归强制删除操作",
"risk_level": "high",
"risk_type": "dangerous_command",
"violated_layers": ["1.2"],
"confidence": 97,
"analysis_duration_ms": 12.5,
"collected_context": {
"os": { "system": "linux", "distribution": "Linux 6.6.87.2", "hostname": "dev-machine" },
"process": { "pid": 12345, "ppid": 1000, "name": "node", "execPath": "/usr/bin/node" },
"user": { "uid": 1000, "gid": 1000, "username": "developer", "homedir": "/home/developer" }
}
}tool_calls 查询参数
| 参数 | 默认值 | 说明 |
|------|--------|------|
| decision | 无 | 按决策过滤（Allow/Deny） |
| limit | 50 | 最大返回条数 |
| offset | 0 | 分页偏移 |
timeline 查询参数
| 参数 | 默认值 | 说明 |
|------|--------|------|
| limit | 100 | 最大时间桶数 |
5. Dashboard 可视化面板
访问 http://localhost:9100/dashboard/ 查看实时面板，自动每 10 秒刷新。
- 统计卡片：Agents / Sessions / Tool Calls / Allow / Deny / Avg Latency
- Risk Distribution：Critical / High / Medium / Low 风险分布条
- Recent Calls：最近工具调用表格（支持水平滚动）
- Agents：Agent 类型分布及调用统计
- Timeline：过去 N 分钟 Allow/Deny 趋势折线图
Dashboard 为自包含 HTML 文件（内联 CSS + JS），浏览器直接打开也能获取数据。
6. 采集层对比
AgentGate 提供三层递进采集，TypeScript 版当前实现了 L1 和 L2：
| 维度 | L1 API Gateway | L2 PTY 拦截 | L3 eBPF（仅 Python） |
|------|---------------|------------|---------------------|
| 技术方案 | HTTP 代理拦截 LLM API 请求/响应 | 伪终端包装，捕获终端 I/O | 内核 eBPF tracepoint |
| 捕获内容 | tool_call JSON（工具名、参数、prompt） | 终端命令原文 + 输出结果 | syscall 元数据 |
| 能否捕获 prompt | ✅ | ❌ | ❌ |
| 能否捕获 tool_call 参数 | ✅ LLM 返回的 JSON | ✅ 终端命令原文 | ✅ execve argv |
| 能否捕获执行结果 | ✅ tool_response | ✅ 终端输出 | ❌ |
| LLM 建议 vs 实际执行 | LLM 建议的操作 | Agent 实际执行的操作 | syscall 真实落地的操作 |
| 能否拦截 | ✅ 响应返回前拦截 | ✅ 信号中断 | ❌ |
| 跨平台 | ✅ 全平台 | ❌ 仅 Linux/macOS | ❌ 仅 Linux |
| TS 实现 | ✅ src/v3/gateway/ | ✅ src/v3/pty/ | ❌ 未实现 |
一句话：L1 知道 LLM 建议 Agent 做什么，L2 知道 Agent 实际做了什么。
7. 关键设计
| 特性 | 说明 |
|------|------|
| Fail-Closed | AgentMoss 不可用时返回 Deny（安全优先） |
| 决策缓存 | LRU 缓存（500 条，TTL 5 分钟），仅缓存 Allow |
| Deny 不缓存 | 每次 Deny 都重新分析，确保安全 |
| Session 持久化 | SQLite + WAL 模式，存储全量 tool_call 记录 |
| action_history 自动累积 | 同一 session_id 的调用序列自动拼接 |
| 系统上下文采集 | 3 模块并行（OS/进程/用户），< 50ms |
| 快速放行 | 安全命令（ls, pwd, echo 等）跳过多层分析，< 10ms 响应 |
7. 项目结构
ts/
├── package.json # @kenhkl/agent-gate v0.2.1
├── tsconfig.json
├── tsup.config.ts # 构建配置（ESM, Node 18+）
├── README.md
└── src/
├── cli.ts # CLI 入口（server / clean）
├── server.ts # Hono 应用工厂 + CORS + 路由挂载
├── routes.ts # 所有 API 路由处理
├── models.ts # Zod 数据模型（请求/响应）
├── normalizer.ts # AgentGateInput → AgentMoss AnalyzeRequest
├── moss-client.ts # AgentMoss HTTP 客户端（Fail-Closed）
├── cache.ts # LRU 决策缓存（500 条，5 分钟 TTL）
├── dashboard.html # 自包含 Dashboard（内联 CSS + JS）
├── collector/ # 系统上下文采集（3 模块并行）
│ ├── index.ts # 并行采集编排
│ ├── system-info.ts # OS/平台/CPU/内存
│ ├── process-info.ts # PID/进程名/execPath
│ └── user-info.ts # UID/GID/用户名/homedir
└── storage/ # SQLite 持久化
├── db.ts # 建表/WAL 模式/Schema DDL
└── repository.ts # CRUD（agents/sessions/tool_calls）许可证
MIT