ai-helper-agent 1.14.7 → 1.14.8
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.en.md +372 -0
- package/README.md +2 -0
- package/package.json +6 -4
package/README.en.md
ADDED
|
@@ -0,0 +1,372 @@
|
|
|
1
|
+
> [English](./README.en.md) | [中文](./README.md)
|
|
2
|
+
|
|
3
|
+
# AI Helper Agent
|
|
4
|
+
|
|
5
|
+
AI Helper Agent — a local proxy service that provides the [AI Helper Chrome Extension](https://github.com/xiweicheng/ai-helper) with local file read/write, system command execution, Skill system, and MCP protocol extension capabilities.
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install -g ai-helper-agent
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Requires Node.js >= 18.0.0.
|
|
14
|
+
|
|
15
|
+
## Quick Start
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
# Start in foreground (real-time logs in terminal, ideal for debugging)
|
|
19
|
+
ai-helper-agent start
|
|
20
|
+
|
|
21
|
+
# Start in background (daemon mode, terminal returns immediately)
|
|
22
|
+
ai-helper-agent start --background
|
|
23
|
+
ai-helper-agent start -b
|
|
24
|
+
|
|
25
|
+
# Specify work directory and port
|
|
26
|
+
ai-helper-agent start --workdir /path/to/your/project --port 18911
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
After startup, the terminal will display a 4-digit pairing code. Enter it in the "Agent" tab of the Chrome extension settings page to complete pairing.
|
|
30
|
+
|
|
31
|
+
## CLI Commands
|
|
32
|
+
|
|
33
|
+
| Command | Description |
|
|
34
|
+
|---------|-------------|
|
|
35
|
+
| `start` | Start the agent service (foreground, with real-time logs) |
|
|
36
|
+
| `start --background` / `start -b` | Start in background (daemon mode) |
|
|
37
|
+
| `stop` | Stop the running agent |
|
|
38
|
+
| `restart` | Restart the agent service (supports -b for background restart) |
|
|
39
|
+
| `status` | Check running status |
|
|
40
|
+
| `paircode` | Show pairing code |
|
|
41
|
+
| `config` | View current configuration |
|
|
42
|
+
| `help` | Show help information |
|
|
43
|
+
| `--version` / `-v` | Show version number |
|
|
44
|
+
|
|
45
|
+
### Startup Options
|
|
46
|
+
|
|
47
|
+
```
|
|
48
|
+
--background, -b Run in background (daemon mode)
|
|
49
|
+
--port <port> Listen port, default 18910
|
|
50
|
+
--host <address> Listen address, default 127.0.0.1
|
|
51
|
+
--workdir <dir> Work directory (file read/write restricted to this scope)
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
### Foreground vs Background
|
|
55
|
+
|
|
56
|
+
| Mode | Command | Terminal Behavior | Use Case |
|
|
57
|
+
|------|---------|-------------------|----------|
|
|
58
|
+
| Foreground | `start` | Blocks terminal, shows real-time logs | Development, debugging |
|
|
59
|
+
| Background | `start --background` | Returns immediately, no log output | Production, daily use |
|
|
60
|
+
|
|
61
|
+
When running in foreground, all file read/write, command execution, and security interception logs are output in real-time in a formatted manner:
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
[12:30:01] [INFO] [File:read] path=/project/src/index.js size=2048
|
|
65
|
+
[12:30:05] [INFO] [Command:started] command="npm test" cwd=/project execId=a1b2c3d4
|
|
66
|
+
[12:30:12] [INFO] [Command:completed] execId=a1b2c3d4 exitCode=0 killed=false
|
|
67
|
+
[12:31:00] [WARN] [Security:exec_denied] command="rm -rf /" reason=High-risk command blocked
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### Process Management
|
|
71
|
+
|
|
72
|
+
The agent manages process lifecycle via a PID file (`~/.ai-helper-agent/agent.pid`):
|
|
73
|
+
|
|
74
|
+
- Automatically writes PID file on startup
|
|
75
|
+
- `stop` command prefers graceful shutdown via API, falls back to killing process via PID file
|
|
76
|
+
- Automatically cleans up PID file on normal shutdown
|
|
77
|
+
|
|
78
|
+
## Security
|
|
79
|
+
|
|
80
|
+
### File Sandbox
|
|
81
|
+
|
|
82
|
+
All file operations are restricted to directories listed in the `allowedPaths` whitelist. `realpath` resolution prevents symlink bypasses, ensuring physical paths are safe.
|
|
83
|
+
|
|
84
|
+
### Command Tiered Control
|
|
85
|
+
|
|
86
|
+
**Blacklist** — Blocked directly, cannot be bypassed:
|
|
87
|
+
|
|
88
|
+
| Type | Examples |
|
|
89
|
+
|------|----------|
|
|
90
|
+
| Disk destruction | `rm -rf /`, `mkfs.*`, `dd if=... of=/dev/...` |
|
|
91
|
+
| System file overwrite | `> /etc/passwd`, `> /etc/shadow` |
|
|
92
|
+
| Malicious pipe execution | `curl ... \| bash`, `git clone ... \| sh` |
|
|
93
|
+
| Shell injection | Backticks, `$()`, `${}` command substitution |
|
|
94
|
+
| Fork bomb | `:(){ :\|:& };:` |
|
|
95
|
+
|
|
96
|
+
**Greylist** — Requires user confirmation before execution:
|
|
97
|
+
|
|
98
|
+
| Command Pattern | Reason |
|
|
99
|
+
|-----------------|--------|
|
|
100
|
+
| `sudo ...` | Requires admin privileges |
|
|
101
|
+
| `npm install -g ...` | Global package installation |
|
|
102
|
+
| `pip install/uninstall` | Python package management |
|
|
103
|
+
| `chmod -R 777` | Recursive permission modification |
|
|
104
|
+
| `rm -rf ...` | Recursive forced deletion |
|
|
105
|
+
| `git push --force` | Force push |
|
|
106
|
+
| `shutdown/reboot` | System shutdown/restart |
|
|
107
|
+
|
|
108
|
+
### Authentication
|
|
109
|
+
|
|
110
|
+
Pairing is completed by entering the 4-digit pairing code displayed in the terminal into the extension. The pairing code rotates every 30 seconds. After successful pairing, an HMAC token is used for subsequent request authentication, stored in `~/.ai-helper-agent/pairings.json`.
|
|
111
|
+
|
|
112
|
+
## Configuration
|
|
113
|
+
|
|
114
|
+
Configuration file path: `~/.ai-helper-agent/config.json`
|
|
115
|
+
|
|
116
|
+
```json
|
|
117
|
+
{
|
|
118
|
+
"port": 18910,
|
|
119
|
+
"host": "127.0.0.1",
|
|
120
|
+
"workdir": "/path/to/project",
|
|
121
|
+
"allowedPaths": [],
|
|
122
|
+
"pairCodeTTL": 30,
|
|
123
|
+
"commandTimeout": 300000,
|
|
124
|
+
"fileMaxSize": 52428800
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
| Field | Description | Default |
|
|
129
|
+
|-------|-------------|---------|
|
|
130
|
+
| `port` | Listen port | 18910 |
|
|
131
|
+
| `host` | Listen address | 127.0.0.1 |
|
|
132
|
+
| `workdir` | Default work directory | Current directory at startup |
|
|
133
|
+
| `allowedPaths` | Additional allowed directory list | `[]` |
|
|
134
|
+
| `pairCodeTTL` | Pairing code validity (seconds) | 30 |
|
|
135
|
+
| `commandTimeout` | Command execution timeout (ms) | 300000 (5 min) |
|
|
136
|
+
| `fileMaxSize` | Max file read/write size (bytes) | 52428800 (50 MB) |
|
|
137
|
+
|
|
138
|
+
## File Search
|
|
139
|
+
|
|
140
|
+
The agent prefers native system search tools, with automatic fallback to Node.js implementation when unavailable:
|
|
141
|
+
|
|
142
|
+
| Engine | Purpose | Detection Command |
|
|
143
|
+
|--------|---------|-------------------|
|
|
144
|
+
| `fd` | Filename search (fast) | `fd --version` |
|
|
145
|
+
| `rg` (ripgrep) | File content search (fast) | `rg --version` |
|
|
146
|
+
|
|
147
|
+
The status endpoint reports currently available search tools:
|
|
148
|
+
|
|
149
|
+
```json
|
|
150
|
+
{ "searchTools": { "fd": true, "rg": true } }
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
## Audit Logs
|
|
154
|
+
|
|
155
|
+
All operations are automatically recorded in audit logs, located in `~/.ai-helper-agent/logs/`.
|
|
156
|
+
|
|
157
|
+
### Dual Channel Output
|
|
158
|
+
|
|
159
|
+
- **Terminal output** (foreground mode): Formatted human-readable output to stderr
|
|
160
|
+
- **File output**: JSON Lines format, written to log files
|
|
161
|
+
|
|
162
|
+
Both channels work simultaneously without interfering with each other.
|
|
163
|
+
|
|
164
|
+
### Log Format
|
|
165
|
+
|
|
166
|
+
JSON Lines format, one record per line, files named by date `agent-YYYY-MM-DD.log`.
|
|
167
|
+
|
|
168
|
+
```json
|
|
169
|
+
{"timestamp":"2026-01-15T10:30:00.123Z","level":"info","category":"fs","action":"read","path":"/home/user/project/src/index.js","size":2048}
|
|
170
|
+
{"timestamp":"2026-01-15T10:30:05.456Z","level":"info","category":"exec","action":"completed","command":"npm test","cwd":"/home/user/project","execId":"a1b2c3d4","exitCode":0,"killed":false,"stdoutLen":1024,"stderrLen":0}
|
|
171
|
+
{"timestamp":"2026-01-15T10:31:00.789Z","level":"warn","category":"security","action":"exec_denied","command":"rm -rf /","reason":"High-risk command blocked"}
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
### Log Categories
|
|
175
|
+
|
|
176
|
+
| Category | Description | Included Actions |
|
|
177
|
+
|----------|-------------|-----------------|
|
|
178
|
+
| `auth` | Authentication events | Pairing success/failure |
|
|
179
|
+
| `fs` | File operations | read, write, list, delete, search_files, search_content |
|
|
180
|
+
| `exec` | Command execution | started, completed, stopped, error |
|
|
181
|
+
| `security` | Security events | deny, confirm, auth failure, path breach interception |
|
|
182
|
+
| `system` | System events | server_start, server_stop, shutdown, server_error, uncaught_exception, unhandled_rejection |
|
|
183
|
+
|
|
184
|
+
### Log Query API
|
|
185
|
+
|
|
186
|
+
```
|
|
187
|
+
GET /api/logs?date=2026-01-15&category=security&limit=50&offset=0
|
|
188
|
+
GET /api/logs/dates
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
- `date` - Date filter (YYYY-MM-DD), defaults to today
|
|
192
|
+
- `category` - Category filter, returns all if omitted
|
|
193
|
+
- `limit` - Max number of records returned, defaults to 200
|
|
194
|
+
- `offset` - Pagination offset
|
|
195
|
+
|
|
196
|
+
Results are returned in reverse chronological order (newest first).
|
|
197
|
+
|
|
198
|
+
### Auto Cleanup
|
|
199
|
+
|
|
200
|
+
- Maximum 30 log files retained
|
|
201
|
+
- Single files exceeding 10 MB are automatically deleted
|
|
202
|
+
- Cleanup check triggered on every log write
|
|
203
|
+
|
|
204
|
+
## API Endpoints
|
|
205
|
+
|
|
206
|
+
### No Authentication Required
|
|
207
|
+
|
|
208
|
+
| Method | Path | Description |
|
|
209
|
+
|--------|------|-------------|
|
|
210
|
+
| POST | `/api/pair` | Pairing authentication |
|
|
211
|
+
| GET | `/api/status` | Health check (version, platform info, search tool availability) |
|
|
212
|
+
| POST | `/api/shutdown` | Shut down the agent service (local access only) |
|
|
213
|
+
|
|
214
|
+
### Authentication Required (Bearer Token)
|
|
215
|
+
|
|
216
|
+
| Method | Path | Description |
|
|
217
|
+
|--------|------|-------------|
|
|
218
|
+
| POST | `/api/fs/read` | Read file content |
|
|
219
|
+
| POST | `/api/fs/write` | Write file |
|
|
220
|
+
| POST | `/api/fs/list` | List directory |
|
|
221
|
+
| POST | `/api/fs/delete` | Delete file/directory |
|
|
222
|
+
| POST | `/api/fs/search_files` | Search files by name pattern (glob) |
|
|
223
|
+
| POST | `/api/fs/search_content` | Search file content (rg preferred, Node.js fallback) |
|
|
224
|
+
| POST | `/api/exec` | Execute system command |
|
|
225
|
+
| POST | `/api/exec/stop` | Stop command execution |
|
|
226
|
+
| GET | `/api/exec/running` | List running processes |
|
|
227
|
+
| GET | `/api/status/detail` | Detailed info (work directory, pairing code, search tools) |
|
|
228
|
+
| GET | `/api/logs` | Query audit logs (supports date/category/limit/offset params) |
|
|
229
|
+
| GET | `/api/logs/dates` | Get available log date list |
|
|
230
|
+
|
|
231
|
+
### WebSocket
|
|
232
|
+
|
|
233
|
+
| Path | Description |
|
|
234
|
+
|------|-------------|
|
|
235
|
+
| `ws://127.0.0.1:18910/ws/exec/:execId` | Real-time command execution output stream |
|
|
236
|
+
|
|
237
|
+
## Robustness
|
|
238
|
+
|
|
239
|
+
The agent has built-in multi-layer exception protection to prevent a single error from crashing the entire service:
|
|
240
|
+
|
|
241
|
+
- **Request-level protection**: Each HTTP request handler is wrapped with exception catching, returns 500 instead of crashing
|
|
242
|
+
- **URL parsing protection**: Malformed URLs don't crash the process, returns 400
|
|
243
|
+
- **Server-level protection**: Server errors like port conflicts are handled gracefully
|
|
244
|
+
- **Global fallback**: `uncaughtException` and `unhandledRejection` global handlers, logs errors but doesn't exit the process
|
|
245
|
+
- **File I/O protection**: Config file read/write failures don't affect service operation
|
|
246
|
+
- **Process management protection**: `SIGTERM`/`SIGKILL` sending has try-catch protection for already-exited processes
|
|
247
|
+
|
|
248
|
+
## Skill System
|
|
249
|
+
|
|
250
|
+
The agent has a built-in Skill system that allows codifying workflows into reusable skills.
|
|
251
|
+
|
|
252
|
+
### Skill Types
|
|
253
|
+
|
|
254
|
+
| Type | Definition Format | Execution | Purpose |
|
|
255
|
+
|------|-------------------|-----------|---------|
|
|
256
|
+
| **Workflow Skill** | JSON/YAML | Direct execution | Automated workflows, step-by-step |
|
|
257
|
+
| **Agent Skill** | SKILL.md | AI autonomous invocation | Knowledge codification, triggered in conversation |
|
|
258
|
+
|
|
259
|
+
### Skill Directory Structure
|
|
260
|
+
|
|
261
|
+
All skills are stored in `~/.ai-helper-agent/skills/`:
|
|
262
|
+
|
|
263
|
+
```
|
|
264
|
+
~/.ai-helper-agent/skills/
|
|
265
|
+
├── workflow-skill.json # Workflow Skill (JSON format)
|
|
266
|
+
├── another-skill.yaml # Workflow Skill (YAML format)
|
|
267
|
+
└── agent-skill/ # Agent Skill (directory form)
|
|
268
|
+
├── SKILL.md # Skill definition file
|
|
269
|
+
└── _meta.json # Metadata (optional)
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
### SKILL.md Format
|
|
273
|
+
|
|
274
|
+
```markdown
|
|
275
|
+
---
|
|
276
|
+
name: <skill-name>
|
|
277
|
+
description: "<Brief description including: (1) what the skill does, (2) when to trigger>"
|
|
278
|
+
enabled: true
|
|
279
|
+
---
|
|
280
|
+
|
|
281
|
+
# <Skill Title>
|
|
282
|
+
|
|
283
|
+
## When to Use This Skill
|
|
284
|
+
|
|
285
|
+
- Trigger condition 1
|
|
286
|
+
- Trigger condition 2
|
|
287
|
+
|
|
288
|
+
## Core Capabilities
|
|
289
|
+
|
|
290
|
+
- Capability 1
|
|
291
|
+
- Capability 2
|
|
292
|
+
|
|
293
|
+
## Usage
|
|
294
|
+
|
|
295
|
+
### Step-by-Step
|
|
296
|
+
|
|
297
|
+
1. Step 1
|
|
298
|
+
2. Step 2
|
|
299
|
+
|
|
300
|
+
## Examples
|
|
301
|
+
|
|
302
|
+
[Concrete examples]
|
|
303
|
+
|
|
304
|
+
## Source
|
|
305
|
+
|
|
306
|
+
Codified from conversation, created: YYYY-MM-DD
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
### Built-in Skills
|
|
310
|
+
|
|
311
|
+
- **skill-creator**: Meta-skill for creating and updating other skills from conversations
|
|
312
|
+
|
|
313
|
+
### Skill API
|
|
314
|
+
|
|
315
|
+
| Method | Path | Description |
|
|
316
|
+
|--------|------|-------------|
|
|
317
|
+
| GET | `/api/skill/list` | Get all skills list |
|
|
318
|
+
| GET | `/api/skill/:name` | Get a single skill's full definition |
|
|
319
|
+
| POST | `/api/skill/import` | Import a new skill |
|
|
320
|
+
| POST | `/api/skill/:name/toggle` | Toggle enable/disable status |
|
|
321
|
+
| DELETE | `/api/skill/:name` | Delete a skill |
|
|
322
|
+
| POST | `/api/skill/:name/run` | Execute a workflow skill |
|
|
323
|
+
|
|
324
|
+
## MCP Protocol Extension
|
|
325
|
+
|
|
326
|
+
Supports Model Context Protocol (MCP) to extend third-party tool capabilities.
|
|
327
|
+
|
|
328
|
+
### MCP Server Configuration
|
|
329
|
+
|
|
330
|
+
Configuration file path: `~/.ai-helper-agent/config.json`
|
|
331
|
+
|
|
332
|
+
```json
|
|
333
|
+
{
|
|
334
|
+
"mcpServers": [
|
|
335
|
+
{
|
|
336
|
+
"id": "my-mcp-server",
|
|
337
|
+
"name": "My MCP Server",
|
|
338
|
+
"command": ["python", "-m", "my_mcp_server"],
|
|
339
|
+
"enabled": true
|
|
340
|
+
}
|
|
341
|
+
]
|
|
342
|
+
}
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
### MCP API
|
|
346
|
+
|
|
347
|
+
| Method | Path | Description |
|
|
348
|
+
|--------|------|-------------|
|
|
349
|
+
| GET | `/api/mcp/status` | Get all MCP server statuses |
|
|
350
|
+
| POST | `/api/mcp/:serverId/connect` | Connect to specified MCP server |
|
|
351
|
+
| POST | `/api/mcp/:serverId/disconnect` | Disconnect |
|
|
352
|
+
| GET | `/api/mcp/tools` | Get all MCP tools list |
|
|
353
|
+
|
|
354
|
+
### How It Works
|
|
355
|
+
|
|
356
|
+
1. Agent auto-connects all enabled MCP servers on startup
|
|
357
|
+
2. Establishes JSON-RPC 2.0 communication via stdio
|
|
358
|
+
3. Auto-discover tools provided by MCP servers
|
|
359
|
+
4. Tool call requests are forwarded to MCP servers via the agent
|
|
360
|
+
5. Tool results are returned to the extension
|
|
361
|
+
|
|
362
|
+
## Tech Stack
|
|
363
|
+
|
|
364
|
+
- Node.js >= 18
|
|
365
|
+
- Native `http` module (HTTP server)
|
|
366
|
+
- `ws` library (WebSocket server)
|
|
367
|
+
- Zero external framework dependencies
|
|
368
|
+
- Optional dependencies: `fd`, `rg` (ripgrep) — for accelerated file search
|
|
369
|
+
|
|
370
|
+
## License
|
|
371
|
+
|
|
372
|
+
MIT
|
package/README.md
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ai-helper-agent",
|
|
3
|
-
"version": "1.14.
|
|
3
|
+
"version": "1.14.8",
|
|
4
4
|
"description": "AI Helper Agent - Local file access and system command execution proxy for Chrome extension / AI Helper 代理服务，为 Chrome 扩展提供本地文件读写和系统命令执行",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./src/server.js",
|
|
@@ -11,7 +11,8 @@
|
|
|
11
11
|
"files": [
|
|
12
12
|
"bin/",
|
|
13
13
|
"src/",
|
|
14
|
-
"README.md"
|
|
14
|
+
"README.md",
|
|
15
|
+
"README.en.md"
|
|
15
16
|
],
|
|
16
17
|
"scripts": {
|
|
17
18
|
"start": "node bin/agent.js start",
|
|
@@ -41,9 +42,10 @@
|
|
|
41
42
|
"license": "MIT",
|
|
42
43
|
"repository": {
|
|
43
44
|
"type": "git",
|
|
44
|
-
"url": ""
|
|
45
|
+
"url": "git+https://github.com/xiweicheng/ai-helper.git",
|
|
46
|
+
"directory": "agent"
|
|
45
47
|
},
|
|
46
|
-
"homepage": "",
|
|
48
|
+
"homepage": "https://github.com/xiweicheng/ai-helper/tree/main/agent#readme",
|
|
47
49
|
"bugs": {
|
|
48
50
|
"url": "https://github.com/xiweicheng/ai-helper/issues"
|
|
49
51
|
}
|