@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 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/Unix Socket ┌──────────────────┐ HTTP/Unix Socket ┌─────────────┐
9
- │ AI Agent │ ── AgentGateInput ──────▶│ AgentGate │ ── AnalyzeRequest ────▶│ AgentMoss │
10
- │ (任意Agent) │ │ (独立服务) │ │ (安全分析) │
11
- │ │◀─ AgentGateResponse ────│ · 系统上下文采集 │◀─ AnalyzeResponse ────│ │
12
- └──────────────┘ │ · 格式标准化 │ └─────────────┘
13
- │ · 决策缓存 │
14
- │ · Session 存储 │
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
- pip install agent-gate-sec
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
- pip install -e ".[dev]"
35
+ cd AgentGate/ts
36
+ npm install
37
+ npm run build
32
38
  ```
33
39
 
40
+ ---
41
+
34
42
  ## 2. 启动服务
35
43
 
36
- AgentGate 依赖 AgentMoss 做安全分析,需要**先启动 AgentMoss,再启动 AgentGate**。
44
+ AgentGate 是一个**独立常驻服务**,支持以下运行方式:
37
45
 
38
- ### 2.1 启动 AgentMoss
46
+ ### 2.1 前台运行(测试/开发)
39
47
 
40
48
  ```bash
41
- # HTTP 模式(默认端口 9090)
42
- agent-moss server --mode http --port 9090
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
- curl http://127.0.0.1:9090/api/v1/health
48
- # → {"status": "ok", ...}
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
- ### 2.2 启动 AgentGate
79
+ #### 方式 2: screen/tmux(推荐)
52
80
 
53
81
  ```bash
54
- cd /home/hkl/gitcode/AgentGate
82
+ # 使用 screen
83
+ screen -S agentgate-ts
84
+ agent-gate gateway --config config/agent_gate.yaml
55
85
 
56
- # HTTP 模式(默认端口 9100)
57
- agent-gate server --mode http --port 9100
86
+ # 按 Ctrl+A+D 分离会话(服务继续运行)
87
+ # 重新连接: screen -r agentgate-ts
58
88
 
59
- # 或指定数据库路径
60
- agent-gate server --mode http --port 9100 --db-path /tmp/agent_gate.db
89
+ # 使用 tmux
90
+ tmux new -s agentgate-ts
91
+ agent-gate gateway --config config/agent_gate.yaml
61
92
 
62
- # Unix Socket 模式(同机更低延迟)
63
- agent-gate server --mode socket --socket /var/run/agent_gate/agent_gate.sock
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
- curl http://127.0.0.1:9100/api/v1/health
69
- # → {"status": "ok", "version": "0.1.0"}
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
- ### 2.3 数据存储路径
113
+ #### 服务管理命令
114
+
115
+ ```bash
116
+ # 启动服务
117
+ sudo systemctl start agentgate-ts
73
118
 
74
- `db_path` 默认为 `"auto"`,根据运行环境自动选择:
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
- ## 3. 验证联调效果
128
+ # 查看日志
129
+ tail -f logs/gateway_ts.log
85
130
 
86
- ### 3.1 端到端测试(自动启动双服务)
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
- python3 examples/opendesk/test_e2e.py
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
- 自动启动 AgentMoss + AgentGate,执行安全命令和危险命令,验证:
93
- - 危险命令 `rm -rf /` → **Deny** (critical)
94
- - 危险命令 `curl | bash` → **Deny** (high)
95
- - Session 历史自动累积
96
- - 系统上下文完整采集
151
+ ### 2.4 检查服务状态
97
152
 
98
- ### 3.2 手动 curl 测试
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
- curl -s -X POST http://127.0.0.1:9100/api/v1/analyze \
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
- ## 4. 三方 Agent 如何调用 AgentGate
174
+ ### 2.2 启动 AgentGate
117
175
 
118
- ### 4.1 Python Agent(SDK)
176
+ ```bash
177
+ # HTTP 模式(默认端口 9100)
178
+ agent-gate server
119
179
 
120
- ```python
121
- from agent_gate.sdk import GateClient
180
+ # 自定义端口和地址
181
+ agent-gate server --host 0.0.0.0 --port 9100
122
182
 
123
- client = GateClient(base_url="http://127.0.0.1:9100")
183
+ # 指定 AgentMoss 地址
184
+ agent-gate server --moss-url http://127.0.0.1:9090
124
185
 
125
- # 安全分析
126
- response = client.analyze(
127
- agent_type="my-agent",
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
- if response["decision"] == "Allow":
135
- # 执行命令
136
- print("允许执行")
137
- else:
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
- ### 4.2 TypeScript / Electron Agent(SDK)
196
+ ### 2.3 CLI 参数
142
197
 
143
- ```typescript
144
- import { GateClient } from './gate_client';
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
- const client = new GateClient({ baseUrl: 'http://127.0.0.1:9100' });
205
+ `--moss-url` 也支持通过环境变量 `MOSS_URL` 设置(CLI 参数优先)。
147
206
 
148
- const result = await client.analyze({
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
- if (result.decision === 'Allow') {
157
- // 执行命令
158
- } else {
159
- console.error(`被阻止: ${result.reason}`);
160
- }
209
+ ```bash
210
+ # 清理 30 天前的记录(默认)
211
+ agent-gate clean
212
+
213
+ # 自定义保留天数
214
+ agent-gate clean --retention-days 7
161
215
  ```
162
216
 
163
- ### 4.3 任意 Agent(HTTP / curl)
217
+ ### 2.5 数据存储路径
164
218
 
165
- ```bash
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
- ### 4.4 Shell 包装器(无代码接入)
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
- export AGENT_GATE_URL=http://127.0.0.1:9100
185
- export AGENT_SESSION_ID=shell-session-001
231
+ cd ts
232
+ npm install
186
233
 
187
- # 用包装器执行命令
188
- agent-gate-wrap ls -la # Allow → 正常执行
189
- agent-gate-wrap rm -rf / # Deny → 阻断并退出 126
190
- ```
234
+ # 开发模式(tsx 直接运行,端口 9100)
235
+ npm run dev
191
236
 
192
- ### 4.5 OpenDesk 集成
237
+ # 构建
238
+ npm run build
193
239
 
194
- 参考 `examples/opendesk/`:
195
- - `agent_gate_plugin.ts` — 插件代码(放到 OpenDesk 源码中)
196
- - `README.md` — 3 步集成指南
197
- - `TESTING.md` — 分层测试指南
198
- - `test_e2e.py` — 端到端自动测试
240
+ # 构建产物在 dist/ 下
241
+ ```
199
242
 
200
- 核心:在 OpenDesk 的 `afterParseToolcall` 钩子中调用 AgentGate API,返回 `reject` 即可阻断工具执行。
243
+ 构建工具:[tsup](https://github.com/egoist/tsup),输出 ESM 格式,`better-sqlite3` 作为 external 不打包。
201
244
 
202
245
  ---
203
246
 
204
- ## 5. API 接口
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/{id}/traces` | 查询 session 完整调用轨迹 |
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": "opendes",
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
- > `action_history` 可选 — AgentGate 从 SQLite 自动累积同一 session 的历史。
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": "Ubuntu 24.04", ... },
245
- "resources": { "cpu_count": 8, "memory_total_gb": 31.2, ... },
246
- "process": { "pid": 12345, "name": "opendesk", ... },
247
- "user": { "uid": 1000, "username": "developer", ... }
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
- ## 6. 关键设计
313
+ | 参数 | 默认值 | 说明 |
314
+ |------|--------|------|
315
+ | `decision` | 无 | 按决策过滤(`Allow`/`Deny`) |
316
+ | `limit` | `50` | 最大返回条数 |
317
+ | `offset` | `0` | 分页偏移 |
256
318
 
257
- | 特性 | 说明 |
258
- |------|------|
259
- | **Fail-Closed** | AgentMoss 不可用时 AgentGate 返回 Deny(安全优先) |
260
- | **决策缓存** | LRU 缓存 Allow 决策(同 session+同 cwd+同 command 可复用) |
261
- | **Deny 不缓存** | 每次 Deny 都重新分析,确保安全 |
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
- ## 7. 测试
327
+ ## 5. Dashboard 可视化面板
270
328
 
271
- ```bash
272
- # 单元测试(42 项)
273
- python3 -m pytest tests/test_server.py -v
329
+ 访问 `http://localhost:9100/dashboard/` 查看实时面板,自动每 10 秒刷新。
274
330
 
275
- # 端到端测试(AgentMoss + AgentGate 联调)
276
- python3 examples/opendesk/test_e2e.py
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
- ## 8. 高权限需求
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
- 推荐以专用 `agent-gate` 用户 + Linux capabilities 运行,不使用 root。
341
+ ## 6. 采集层对比
292
342
 
293
- ---
343
+ AgentGate 提供三层递进采集,TypeScript 版当前实现了 L1 和 L2:
294
344
 
295
- ## 9. Dashboard 可视化面板
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
- AgentGate 内置实时 Dashboard(`http://localhost:9100/dashboard/`),提供:
357
+ > **一句话**:L1 知道 LLM **建议** Agent 做什么,L2 知道 Agent **实际**做了什么。
298
358
 
299
- - 实时统计卡片(Agents / Sessions / Tool Calls / Allow / Deny / Avg Latency)
300
- - Risk Distribution 风险分布条
301
- - Recent Tool Calls 操作记录表格
302
- - Agent 类型分布
303
- - Timeline 折线图(过去 60 分钟 Allow/Deny 趋势)
359
+ ---
304
360
 
305
- ### 在 OpenDesk 中查看
361
+ ## 7. 关键设计
306
362
 
307
- AgentGate 已集成到 OpenDesk 桌面端作为侧边栏应用,点击图标即可在应用内查看 Dashboard。
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
- ## 10. 项目结构
375
+ ## 7. 项目结构
312
376
 
313
377
  ```
314
- AgentGate/
315
- ├── agent_gate/ # 主包
316
- │ ├── cli.py # 命令行入口 (agent-gate server / clean)
317
- │ ├── config.py # YAML 配置 + XDG 路径自动适配
318
- │ ├── normalizer.py # AgentGateInput → AgentMoss AnalyzeRequest
319
- │ ├── sdk.py # Python SDK
320
- │ ├── server/ # FastAPI 服务
321
- │ │ ├── app.py # HTTP / Unix Socket 双模式
322
- │ │ ├── routes.py # /analyze /traces /tool_calls /health
323
- │ │ ├── models.py # Pydantic 数据模型
324
- │ │ └── middleware.py # 请求日志
325
- │ ├── collector/ # 系统数据采集(5 模块并行)
326
- │ │ ├── system_info.py # OS/内核/CPU/内存/磁盘
327
- │ │ ├── process_info.py # PID/capabilities/cgroup
328
- │ │ ├── env_info.py # 环境变量白名单过滤
329
- │ │ ├── network_info.py # 网络接口/连接数
330
- │ │ └── user_info.py # UID/GID/用户组
331
- │ ├── client/ # AgentMoss 客户端
332
- │ │ ├── moss_client.py # 异步 HTTP + Fail-Closed
333
- │ │ └── cache.py # LRU 决策缓存
334
- │ └── storage/ # SQLite 持久化
335
- │ ├── db.py # 建表/迁移/WAL 模式
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
  ## 许可证