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 build

2. 启动服务

AgentGate 依赖 AgentMoss 做安全分析，需要先启动 AgentMoss，再启动 AgentGate。

2.1 启动 AgentMoss

# HTTP 模式（默认端口 9090）
agent-moss server --mode http --port 9090

验证：

curl http://127.0.0.1:9090/api/v1/health

2.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 7

2.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. 关键设计

| 特性 | 说明 | |------|------| | 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