@kenhkl/agent-gate 0.2.1 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +262 -212
- package/dist/cli.js +28983 -174
- package/dist/cli.js.map +1 -1
- package/dist/dashboard.html +98 -0
- package/package.json +16 -12
package/README.md
CHANGED
|
@@ -1,221 +1,267 @@
|
|
|
1
|
-
# AgentGate
|
|
1
|
+
# AgentGate (TypeScript)
|
|
2
2
|
|
|
3
|
-
> AI Agent 数据采集与安全分析中间层服务
|
|
3
|
+
> AI Agent 数据采集与安全分析中间层服务 — TypeScript 版
|
|
4
4
|
|
|
5
5
|
AgentGate 是一个**独立常驻服务**,位于 AI Agent 与 [AgentMoss](https://atomgit.com/kenhkl/AgentMoss) 之间:接收 Agent 的工具调用数据,采集系统上下文,转换格式后提交 AgentMoss 安全分析,回传 Allow/Deny 决策。
|
|
6
6
|
|
|
7
7
|
```
|
|
8
|
-
┌──────────────┐ HTTP
|
|
9
|
-
│ AI Agent
|
|
10
|
-
│ (任意Agent) │
|
|
11
|
-
│ │◀─
|
|
12
|
-
└──────────────┘
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
8
|
+
┌──────────────┐ HTTP ┌──────────────────┐ HTTP ┌─────────────┐
|
|
9
|
+
│ AI Agent │── AgentGate ──▶│ AgentGate │── Analyze ──▶│ AgentMoss │
|
|
10
|
+
│ (任意Agent) │ Input │ (独立服务) │ Request │ (安全分析) │
|
|
11
|
+
│ │◀─ Response ──│ · 系统上下文采集 │◀─ Response ──│ │
|
|
12
|
+
└──────────────┘ │ · 格式标准化 │ └─────────────┘
|
|
13
|
+
│ · 决策缓存 │
|
|
14
|
+
│ · Session 存储 │
|
|
15
|
+
│ · Dashboard │
|
|
16
|
+
└──────────────────┘
|
|
16
17
|
```
|
|
17
18
|
|
|
18
19
|
---
|
|
19
20
|
|
|
20
21
|
## 1. 安装
|
|
21
22
|
|
|
23
|
+
### npm 安装
|
|
24
|
+
|
|
22
25
|
```bash
|
|
23
|
-
|
|
26
|
+
npm install @kenhkl/agent-gate
|
|
24
27
|
```
|
|
25
28
|
|
|
26
|
-
安装后 `agent-gate`
|
|
29
|
+
安装后 `agent-gate` 命令即可用。
|
|
30
|
+
|
|
31
|
+
### 从源码构建
|
|
27
32
|
|
|
28
33
|
```bash
|
|
29
34
|
git clone git@gitcode.com:kenhkl/AgentGate.git
|
|
30
|
-
cd AgentGate
|
|
31
|
-
|
|
35
|
+
cd AgentGate/ts
|
|
36
|
+
npm install
|
|
37
|
+
npm run build
|
|
32
38
|
```
|
|
33
39
|
|
|
40
|
+
---
|
|
41
|
+
|
|
34
42
|
## 2. 启动服务
|
|
35
43
|
|
|
36
|
-
AgentGate
|
|
44
|
+
AgentGate 是一个**独立常驻服务**,支持以下运行方式:
|
|
37
45
|
|
|
38
|
-
### 2.1
|
|
46
|
+
### 2.1 前台运行(测试/开发)
|
|
39
47
|
|
|
40
48
|
```bash
|
|
41
|
-
#
|
|
42
|
-
agent-
|
|
49
|
+
# 方式 1: 直接运行(占用终端)
|
|
50
|
+
agent-gate gateway --config config/agent_gate.yaml
|
|
51
|
+
|
|
52
|
+
# 方式 2: 使用 npm script
|
|
53
|
+
npm run dev:gateway
|
|
54
|
+
|
|
55
|
+
# 方式 3: 使用 tsx(开发模式,自动重启)
|
|
56
|
+
npx tsx src/cli.ts gateway --config config/agent_gate.yaml
|
|
43
57
|
```
|
|
44
58
|
|
|
45
|
-
|
|
59
|
+
### 2.2 后台运行(日常使用)
|
|
60
|
+
|
|
61
|
+
#### 方式 1: nohup(简单)
|
|
62
|
+
|
|
46
63
|
```bash
|
|
47
|
-
|
|
48
|
-
|
|
64
|
+
# 后台运行,日志输出到文件
|
|
65
|
+
nohup agent-gate gateway --config config/agent_gate.yaml > logs/gateway_ts.log 2>&1 &
|
|
66
|
+
|
|
67
|
+
# 查看进程 ID
|
|
68
|
+
echo $!
|
|
69
|
+
|
|
70
|
+
# 查看日志
|
|
71
|
+
tail -f logs/gateway_ts.log
|
|
72
|
+
|
|
73
|
+
# 停止服务
|
|
74
|
+
pkill -f "agent-gate gateway"
|
|
75
|
+
# 或使用进程 ID
|
|
76
|
+
kill <PID>
|
|
49
77
|
```
|
|
50
78
|
|
|
51
|
-
|
|
79
|
+
#### 方式 2: screen/tmux(推荐)
|
|
52
80
|
|
|
53
81
|
```bash
|
|
54
|
-
|
|
82
|
+
# 使用 screen
|
|
83
|
+
screen -S agentgate-ts
|
|
84
|
+
agent-gate gateway --config config/agent_gate.yaml
|
|
55
85
|
|
|
56
|
-
#
|
|
57
|
-
|
|
86
|
+
# 按 Ctrl+A+D 分离会话(服务继续运行)
|
|
87
|
+
# 重新连接: screen -r agentgate-ts
|
|
58
88
|
|
|
59
|
-
#
|
|
60
|
-
|
|
89
|
+
# 使用 tmux
|
|
90
|
+
tmux new -s agentgate-ts
|
|
91
|
+
agent-gate gateway --config config/agent_gate.yaml
|
|
61
92
|
|
|
62
|
-
#
|
|
63
|
-
|
|
93
|
+
# 按 Ctrl+B+D 分离会话(服务继续运行)
|
|
94
|
+
# 重新连接: tmux attach -t agentgate-ts
|
|
64
95
|
```
|
|
65
96
|
|
|
66
|
-
|
|
97
|
+
### 2.3 systemd 服务(生产环境)
|
|
98
|
+
|
|
99
|
+
**适用于长期部署、开机自启动场景。**
|
|
100
|
+
|
|
101
|
+
#### 安装 systemd 服务
|
|
102
|
+
|
|
67
103
|
```bash
|
|
68
|
-
|
|
69
|
-
|
|
104
|
+
# 使用安装脚本
|
|
105
|
+
bash scripts/install-systemd-ts.sh
|
|
106
|
+
|
|
107
|
+
# 或手动安装(需要 sudo)
|
|
108
|
+
sudo cp deploy/agentgate-ts.service.template /etc/systemd/system/agentgate-ts.service
|
|
109
|
+
sudo systemctl daemon-reload
|
|
110
|
+
sudo systemctl start agentgate-ts
|
|
70
111
|
```
|
|
71
112
|
|
|
72
|
-
|
|
113
|
+
#### 服务管理命令
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
# 启动服务
|
|
117
|
+
sudo systemctl start agentgate-ts
|
|
73
118
|
|
|
74
|
-
|
|
119
|
+
# 停止服务
|
|
120
|
+
sudo systemctl stop agentgate-ts
|
|
75
121
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
| 开发(git clone 中运行) | `data/agent_gate.db` |
|
|
79
|
-
| 用户安装(`pip install`) | `~/.local/share/agent_gate/agent_gate.db` |
|
|
80
|
-
| 系统服务(systemd) | 显式 `--db-path /var/lib/agent_gate/agent_gate.db` |
|
|
122
|
+
# 重启服务
|
|
123
|
+
sudo systemctl restart agentgate-ts
|
|
81
124
|
|
|
82
|
-
|
|
125
|
+
# 查看状态
|
|
126
|
+
sudo systemctl status agentgate-ts
|
|
83
127
|
|
|
84
|
-
|
|
128
|
+
# 查看日志
|
|
129
|
+
tail -f logs/gateway_ts.log
|
|
85
130
|
|
|
86
|
-
|
|
131
|
+
# 开机自启动
|
|
132
|
+
sudo systemctl enable agentgate-ts
|
|
133
|
+
|
|
134
|
+
# 禁用开机自启动
|
|
135
|
+
sudo systemctl disable agentgate-ts
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
#### 卸载 systemd 服务
|
|
87
139
|
|
|
88
140
|
```bash
|
|
89
|
-
|
|
141
|
+
# 使用卸载脚本
|
|
142
|
+
bash scripts/uninstall-systemd-ts.sh
|
|
143
|
+
|
|
144
|
+
# 或手动卸载
|
|
145
|
+
sudo systemctl stop agentgate-ts
|
|
146
|
+
sudo systemctl disable agentgate-ts
|
|
147
|
+
sudo rm /etc/systemd/system/agentgate-ts.service
|
|
148
|
+
sudo systemctl daemon-reload
|
|
90
149
|
```
|
|
91
150
|
|
|
92
|
-
|
|
93
|
-
- 危险命令 `rm -rf /` → **Deny** (critical)
|
|
94
|
-
- 危险命令 `curl | bash` → **Deny** (high)
|
|
95
|
-
- Session 历史自动累积
|
|
96
|
-
- 系统上下文完整采集
|
|
151
|
+
### 2.4 检查服务状态
|
|
97
152
|
|
|
98
|
-
|
|
153
|
+
```bash
|
|
154
|
+
# 使用状态检查脚本
|
|
155
|
+
bash scripts/status-agentgate-ts.sh
|
|
156
|
+
|
|
157
|
+
# 或手动检查
|
|
158
|
+
curl http://127.0.0.1:9110/health
|
|
159
|
+
curl http://127.0.0.1:9110/api/stats
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
### 2.1 启动 AgentMoss
|
|
99
163
|
|
|
100
164
|
```bash
|
|
101
|
-
#
|
|
102
|
-
|
|
103
|
-
-H "Content-Type: application/json" \
|
|
104
|
-
-d '{"agent_type":"test","session_id":"sess-001",
|
|
105
|
-
"tool_name":"bash","command":"ls -la","cwd":"/tmp"}' | python3 -m json.tool
|
|
106
|
-
|
|
107
|
-
# 危险命令
|
|
108
|
-
curl -s -X POST http://127.0.0.1:9100/api/v1/analyze \
|
|
109
|
-
-H "Content-Type: application/json" \
|
|
110
|
-
-d '{"agent_type":"test","session_id":"sess-001",
|
|
111
|
-
"tool_name":"bash","command":"rm -rf /","cwd":"/root"}' | python3 -m json.tool
|
|
165
|
+
# HTTP 模式(默认端口 9090)
|
|
166
|
+
agent-moss server --mode http --port 9090
|
|
112
167
|
```
|
|
113
168
|
|
|
114
|
-
|
|
169
|
+
验证:
|
|
170
|
+
```bash
|
|
171
|
+
curl http://127.0.0.1:9090/api/v1/health
|
|
172
|
+
```
|
|
115
173
|
|
|
116
|
-
|
|
174
|
+
### 2.2 启动 AgentGate
|
|
117
175
|
|
|
118
|
-
|
|
176
|
+
```bash
|
|
177
|
+
# HTTP 模式(默认端口 9100)
|
|
178
|
+
agent-gate server
|
|
119
179
|
|
|
120
|
-
|
|
121
|
-
|
|
180
|
+
# 自定义端口和地址
|
|
181
|
+
agent-gate server --host 0.0.0.0 --port 9100
|
|
122
182
|
|
|
123
|
-
|
|
183
|
+
# 指定 AgentMoss 地址
|
|
184
|
+
agent-gate server --moss-url http://127.0.0.1:9090
|
|
124
185
|
|
|
125
|
-
#
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
session_id="sess-001",
|
|
129
|
-
tool_name="bash",
|
|
130
|
-
command="ls -la",
|
|
131
|
-
cwd="/home/user/project",
|
|
132
|
-
)
|
|
186
|
+
# 指定数据库路径
|
|
187
|
+
agent-gate server --db-path /tmp/agent_gate_ts.db
|
|
188
|
+
```
|
|
133
189
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
print(f"被阻止: {response['reason']}")
|
|
190
|
+
验证:
|
|
191
|
+
```bash
|
|
192
|
+
curl http://127.0.0.1:9100/api/v1/health
|
|
193
|
+
# → {"status":"healthy","version":"0.2.1"}
|
|
139
194
|
```
|
|
140
195
|
|
|
141
|
-
###
|
|
196
|
+
### 2.3 CLI 参数
|
|
142
197
|
|
|
143
|
-
|
|
144
|
-
|
|
198
|
+
| 参数 | 默认值 | 说明 |
|
|
199
|
+
|------|--------|------|
|
|
200
|
+
| `--host <host>` | `127.0.0.1` | 监听地址 |
|
|
201
|
+
| `--port <port>` | `9100` | 监听端口 |
|
|
202
|
+
| `--db-path <path>` | 自动(见下表) | SQLite 数据库路径 |
|
|
203
|
+
| `--moss-url <url>` | `http://127.0.0.1:9090` | AgentMoss 服务地址 |
|
|
145
204
|
|
|
146
|
-
|
|
205
|
+
`--moss-url` 也支持通过环境变量 `MOSS_URL` 设置(CLI 参数优先)。
|
|
147
206
|
|
|
148
|
-
|
|
149
|
-
agentType: 'opendes',
|
|
150
|
-
sessionId: 'sess-001',
|
|
151
|
-
toolName: 'executeBash',
|
|
152
|
-
command: 'ls -la',
|
|
153
|
-
cwd: '/home/user/project',
|
|
154
|
-
});
|
|
207
|
+
### 2.4 数据清理
|
|
155
208
|
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
209
|
+
```bash
|
|
210
|
+
# 清理 30 天前的记录(默认)
|
|
211
|
+
agent-gate clean
|
|
212
|
+
|
|
213
|
+
# 自定义保留天数
|
|
214
|
+
agent-gate clean --retention-days 7
|
|
161
215
|
```
|
|
162
216
|
|
|
163
|
-
###
|
|
217
|
+
### 2.5 数据存储路径
|
|
164
218
|
|
|
165
|
-
|
|
166
|
-
curl -s -X POST http://127.0.0.1:9100/api/v1/analyze \
|
|
167
|
-
-H "Content-Type: application/json" \
|
|
168
|
-
-d '{
|
|
169
|
-
"agent_type": "my-agent",
|
|
170
|
-
"agent_version": "1.0",
|
|
171
|
-
"session_id": "sess-abc",
|
|
172
|
-
"tool_name": "bash",
|
|
173
|
-
"command": "rm -rf /tmp/cache",
|
|
174
|
-
"cwd": "/home/user/project",
|
|
175
|
-
"description": "清理缓存",
|
|
176
|
-
"user_prompt": "清理项目临时文件"
|
|
177
|
-
}'
|
|
178
|
-
```
|
|
219
|
+
独立使用 `agent_gate_ts.db`,避免与 Python 版 WAL 隔离冲突。
|
|
179
220
|
|
|
180
|
-
|
|
221
|
+
| 场景 | 实际路径 |
|
|
222
|
+
|------|----------|
|
|
223
|
+
| 默认 | `~/.local/share/agent_gate/agent_gate_ts.db` |
|
|
224
|
+
| 自定义 | `--db-path <path>` 指定 |
|
|
225
|
+
|
|
226
|
+
---
|
|
227
|
+
|
|
228
|
+
## 3. 开发
|
|
181
229
|
|
|
182
230
|
```bash
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
export AGENT_SESSION_ID=shell-session-001
|
|
231
|
+
cd ts
|
|
232
|
+
npm install
|
|
186
233
|
|
|
187
|
-
#
|
|
188
|
-
|
|
189
|
-
agent-gate-wrap rm -rf / # Deny → 阻断并退出 126
|
|
190
|
-
```
|
|
234
|
+
# 开发模式(tsx 直接运行,端口 9100)
|
|
235
|
+
npm run dev
|
|
191
236
|
|
|
192
|
-
|
|
237
|
+
# 构建
|
|
238
|
+
npm run build
|
|
193
239
|
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
- `README.md` — 3 步集成指南
|
|
197
|
-
- `TESTING.md` — 分层测试指南
|
|
198
|
-
- `test_e2e.py` — 端到端自动测试
|
|
240
|
+
# 构建产物在 dist/ 下
|
|
241
|
+
```
|
|
199
242
|
|
|
200
|
-
|
|
243
|
+
构建工具:[tsup](https://github.com/egoist/tsup),输出 ESM 格式,`better-sqlite3` 作为 external 不打包。
|
|
201
244
|
|
|
202
245
|
---
|
|
203
246
|
|
|
204
|
-
##
|
|
247
|
+
## 4. API 接口
|
|
205
248
|
|
|
206
249
|
| 方法 | 路径 | 说明 |
|
|
207
250
|
|------|------|------|
|
|
208
251
|
| `POST` | `/api/v1/analyze` | 安全分析(核心接口) |
|
|
209
252
|
| `GET` | `/api/v1/health` | 健康检查 |
|
|
210
|
-
| `GET` | `/api/v1/sessions
|
|
211
|
-
| `GET` | `/api/v1/agents/{id}/sessions` | 查询某 agent 所有 session |
|
|
253
|
+
| `GET` | `/api/v1/sessions/:id/traces` | 查询 session 调用轨迹 |
|
|
212
254
|
| `GET` | `/api/v1/tool_calls` | 条件查询工具调用记录 |
|
|
255
|
+
| `GET` | `/api/v1/agents` | 查询 agent 列表及统计 |
|
|
256
|
+
| `GET` | `/api/v1/timeline` | Allow/Deny 时间线(按分钟聚合) |
|
|
257
|
+
| `GET` | `/dashboard/` | 可视化面板 |
|
|
213
258
|
|
|
214
259
|
### 请求格式
|
|
215
260
|
|
|
216
261
|
```json
|
|
217
262
|
{
|
|
218
|
-
"agent_type": "
|
|
263
|
+
"agent_type": "opendesk",
|
|
264
|
+
"agent_version": "1.0",
|
|
219
265
|
"session_id": "session-abc",
|
|
220
266
|
"tool_name": "bash",
|
|
221
267
|
"command": "rm -rf /tmp/cache/*",
|
|
@@ -227,7 +273,21 @@ agent-gate-wrap rm -rf / # Deny → 阻断并退出 126
|
|
|
227
273
|
}
|
|
228
274
|
```
|
|
229
275
|
|
|
230
|
-
|
|
276
|
+
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
|
277
|
+
|------|------|------|--------|------|
|
|
278
|
+
| `agent_type` | string | 是 | — | Agent 标识(如 `opendesk`, `claude-code`) |
|
|
279
|
+
| `agent_version` | string | 否 | `0.1.0` | Agent 版本 |
|
|
280
|
+
| `session_id` | string | 是 | — | Session 标识 |
|
|
281
|
+
| `tool_name` | string | 否 | — | 工具名称(如 `bash`, `file_write`) |
|
|
282
|
+
| `command` | string | 否 | — | 工具命令或描述 |
|
|
283
|
+
| `a_next` | object | 否 | — | `{action_type, action_detail}`,Python API 兼容格式 |
|
|
284
|
+
| `cwd` | string | 否 | `""` | 当前工作目录 |
|
|
285
|
+
| `description` | string | 否 | `""` | 描述 |
|
|
286
|
+
| `user_prompt` | string | 否 | `""` | 用户 prompt |
|
|
287
|
+
| `action_history` | array | 否 | `[]` | 历史动作(同 session 自动累积) |
|
|
288
|
+
| `metadata` | object | 否 | — | 附加元数据 |
|
|
289
|
+
|
|
290
|
+
> `tool_name`/`command` 和 `a_next.action_type`/`a_next.action_detail` 两种格式均支持,前者优先。
|
|
231
291
|
|
|
232
292
|
### 响应格式
|
|
233
293
|
|
|
@@ -241,112 +301,102 @@ agent-gate-wrap rm -rf / # Deny → 阻断并退出 126
|
|
|
241
301
|
"confidence": 97,
|
|
242
302
|
"analysis_duration_ms": 12.5,
|
|
243
303
|
"collected_context": {
|
|
244
|
-
"os": { "system": "linux", "distribution": "
|
|
245
|
-
"
|
|
246
|
-
"
|
|
247
|
-
|
|
248
|
-
},
|
|
249
|
-
"source": "agent_moss"
|
|
304
|
+
"os": { "system": "linux", "distribution": "Linux 6.6.87.2", "hostname": "dev-machine" },
|
|
305
|
+
"process": { "pid": 12345, "ppid": 1000, "name": "node", "execPath": "/usr/bin/node" },
|
|
306
|
+
"user": { "uid": 1000, "gid": 1000, "username": "developer", "homedir": "/home/developer" }
|
|
307
|
+
}
|
|
250
308
|
}
|
|
251
309
|
```
|
|
252
310
|
|
|
253
|
-
|
|
311
|
+
### tool_calls 查询参数
|
|
254
312
|
|
|
255
|
-
|
|
313
|
+
| 参数 | 默认值 | 说明 |
|
|
314
|
+
|------|--------|------|
|
|
315
|
+
| `decision` | 无 | 按决策过滤(`Allow`/`Deny`) |
|
|
316
|
+
| `limit` | `50` | 最大返回条数 |
|
|
317
|
+
| `offset` | `0` | 分页偏移 |
|
|
256
318
|
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
|
260
|
-
|
|
261
|
-
|
|
|
262
|
-
| **Session 持久化** | SQLite 存储全量 tool_call 记录,Agent 无需自维护 history |
|
|
263
|
-
| **action_history 自动累积** | 同一 session_id 的调用序列自动拼接,传给 AgentMoss |
|
|
264
|
-
| **系统上下文采集** | 5 模块并行(OS/进程/网络/用户/环境变量),< 50ms |
|
|
265
|
-
| **环境变量安全过滤** | 白名单机制,自动排除 KEY/TOKEN/SECRET 等敏感变量 |
|
|
319
|
+
### timeline 查询参数
|
|
320
|
+
|
|
321
|
+
| 参数 | 默认值 | 说明 |
|
|
322
|
+
|------|--------|------|
|
|
323
|
+
| `limit` | `100` | 最大时间桶数 |
|
|
266
324
|
|
|
267
325
|
---
|
|
268
326
|
|
|
269
|
-
##
|
|
327
|
+
## 5. Dashboard 可视化面板
|
|
270
328
|
|
|
271
|
-
|
|
272
|
-
# 单元测试(42 项)
|
|
273
|
-
python3 -m pytest tests/test_server.py -v
|
|
329
|
+
访问 `http://localhost:9100/dashboard/` 查看实时面板,自动每 10 秒刷新。
|
|
274
330
|
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
331
|
+
- **统计卡片**:Agents / Sessions / Tool Calls / Allow / Deny / Avg Latency
|
|
332
|
+
- **Risk Distribution**:Critical / High / Medium / Low 风险分布条
|
|
333
|
+
- **Recent Calls**:最近工具调用表格(支持水平滚动)
|
|
334
|
+
- **Agents**:Agent 类型分布及调用统计
|
|
335
|
+
- **Timeline**:过去 N 分钟 Allow/Deny 趋势折线图
|
|
280
336
|
|
|
281
|
-
|
|
337
|
+
Dashboard 为自包含 HTML 文件(内联 CSS + JS),浏览器直接打开也能获取数据。
|
|
282
338
|
|
|
283
|
-
|
|
284
|
-
|----------|----------|----------|
|
|
285
|
-
| system_info | 普通用户 | `/proc/version`, `/etc/os-release` |
|
|
286
|
-
| process_info | `CAP_SYS_PTRACE` | `/proc/*/status`, capabilities |
|
|
287
|
-
| env_info | 普通用户 | 自身进程环境变量 |
|
|
288
|
-
| network_info | `CAP_NET_ADMIN` | `/proc/net/*` |
|
|
289
|
-
| user_info | 普通用户 | `/etc/passwd`, `/etc/group` |
|
|
339
|
+
---
|
|
290
340
|
|
|
291
|
-
|
|
341
|
+
## 6. 采集层对比
|
|
292
342
|
|
|
293
|
-
|
|
343
|
+
AgentGate 提供三层递进采集,TypeScript 版当前实现了 L1 和 L2:
|
|
294
344
|
|
|
295
|
-
|
|
345
|
+
| 维度 | L1 API Gateway | L2 PTY 拦截 | L3 eBPF(仅 Python) |
|
|
346
|
+
|------|---------------|------------|---------------------|
|
|
347
|
+
| **技术方案** | HTTP 代理拦截 LLM API 请求/响应 | 伪终端包装,捕获终端 I/O | 内核 eBPF tracepoint |
|
|
348
|
+
| **捕获内容** | tool_call JSON(工具名、参数、prompt) | 终端命令原文 + 输出结果 | syscall 元数据 |
|
|
349
|
+
| **能否捕获 prompt** | ✅ | ❌ | ❌ |
|
|
350
|
+
| **能否捕获 tool_call 参数** | ✅ LLM 返回的 JSON | ✅ 终端命令原文 | ✅ execve argv |
|
|
351
|
+
| **能否捕获执行结果** | ✅ tool_response | ✅ 终端输出 | ❌ |
|
|
352
|
+
| **LLM 建议 vs 实际执行** | LLM **建议**的操作 | Agent **实际**执行的操作 | syscall **真实落地**的操作 |
|
|
353
|
+
| **能否拦截** | ✅ 响应返回前拦截 | ✅ 信号中断 | ❌ |
|
|
354
|
+
| **跨平台** | ✅ 全平台 | ❌ 仅 Linux/macOS | ❌ 仅 Linux |
|
|
355
|
+
| **TS 实现** | ✅ `src/v3/gateway/` | ✅ `src/v3/pty/` | ❌ 未实现 |
|
|
296
356
|
|
|
297
|
-
|
|
357
|
+
> **一句话**:L1 知道 LLM **建议** Agent 做什么,L2 知道 Agent **实际**做了什么。
|
|
298
358
|
|
|
299
|
-
|
|
300
|
-
- Risk Distribution 风险分布条
|
|
301
|
-
- Recent Tool Calls 操作记录表格
|
|
302
|
-
- Agent 类型分布
|
|
303
|
-
- Timeline 折线图(过去 60 分钟 Allow/Deny 趋势)
|
|
359
|
+
---
|
|
304
360
|
|
|
305
|
-
|
|
361
|
+
## 7. 关键设计
|
|
306
362
|
|
|
307
|
-
|
|
363
|
+
| 特性 | 说明 |
|
|
364
|
+
|------|------|
|
|
365
|
+
| **Fail-Closed** | AgentMoss 不可用时返回 Deny(安全优先) |
|
|
366
|
+
| **决策缓存** | LRU 缓存(500 条,TTL 5 分钟),仅缓存 Allow |
|
|
367
|
+
| **Deny 不缓存** | 每次 Deny 都重新分析,确保安全 |
|
|
368
|
+
| **Session 持久化** | SQLite + WAL 模式,存储全量 tool_call 记录 |
|
|
369
|
+
| **action_history 自动累积** | 同一 session_id 的调用序列自动拼接 |
|
|
370
|
+
| **系统上下文采集** | 3 模块并行(OS/进程/用户),< 50ms |
|
|
371
|
+
| **快速放行** | 安全命令(`ls`, `pwd`, `echo` 等)跳过多层分析,< 10ms 响应 |
|
|
308
372
|
|
|
309
373
|
---
|
|
310
374
|
|
|
311
|
-
##
|
|
375
|
+
## 7. 项目结构
|
|
312
376
|
|
|
313
377
|
```
|
|
314
|
-
|
|
315
|
-
├──
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
│
|
|
330
|
-
│
|
|
331
|
-
│ ├──
|
|
332
|
-
│
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
│ └── repository.py # CRUD (agents/sessions/tool_calls)
|
|
337
|
-
├── sdk/ # 客户端 SDK
|
|
338
|
-
│ ├── python/gate_client.py # Python SDK
|
|
339
|
-
│ └── typescript/ # TypeScript SDK (package.json + tsconfig)
|
|
340
|
-
├── examples/opendesk/ # OpenDesk 集成
|
|
341
|
-
│ ├── agent_gate_plugin.ts # 插件(afterParseToolcall 钩子)
|
|
342
|
-
│ ├── test_integration.py # 接口测试(不改 OpenDesk)
|
|
343
|
-
│ ├── test_e2e.py # 端到端测试(自动启双服务)
|
|
344
|
-
│ ├── README.md # 集成指南
|
|
345
|
-
│ └── TESTING.md # 分层测试指南
|
|
346
|
-
├── config/agent_gate.yaml # YAML 配置模板
|
|
347
|
-
├── scripts/agent-gate-wrap.sh # Shell 包装器
|
|
348
|
-
├── tests/test_server.py # 单元 + 集成测试(42 项)
|
|
349
|
-
└── docs/agent_collector_design_v1.md # 设计文档
|
|
378
|
+
ts/
|
|
379
|
+
├── package.json # @kenhkl/agent-gate v0.2.1
|
|
380
|
+
├── tsconfig.json
|
|
381
|
+
├── tsup.config.ts # 构建配置(ESM, Node 18+)
|
|
382
|
+
├── README.md
|
|
383
|
+
└── src/
|
|
384
|
+
├── cli.ts # CLI 入口(server / clean)
|
|
385
|
+
├── server.ts # Hono 应用工厂 + CORS + 路由挂载
|
|
386
|
+
├── routes.ts # 所有 API 路由处理
|
|
387
|
+
├── models.ts # Zod 数据模型(请求/响应)
|
|
388
|
+
├── normalizer.ts # AgentGateInput → AgentMoss AnalyzeRequest
|
|
389
|
+
├── moss-client.ts # AgentMoss HTTP 客户端(Fail-Closed)
|
|
390
|
+
├── cache.ts # LRU 决策缓存(500 条,5 分钟 TTL)
|
|
391
|
+
├── dashboard.html # 自包含 Dashboard(内联 CSS + JS)
|
|
392
|
+
├── collector/ # 系统上下文采集(3 模块并行)
|
|
393
|
+
│ ├── index.ts # 并行采集编排
|
|
394
|
+
│ ├── system-info.ts # OS/平台/CPU/内存
|
|
395
|
+
│ ├── process-info.ts # PID/进程名/execPath
|
|
396
|
+
│ └── user-info.ts # UID/GID/用户名/homedir
|
|
397
|
+
└── storage/ # SQLite 持久化
|
|
398
|
+
├── db.ts # 建表/WAL 模式/Schema DDL
|
|
399
|
+
└── repository.ts # CRUD(agents/sessions/tool_calls)
|
|
350
400
|
```
|
|
351
401
|
|
|
352
402
|
## 许可证
|