@zqagent/core 0.2.4 → 0.2.6
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 +125 -43
- package/README.oss.en.md +5 -0
- package/README.oss.md +5 -0
- package/README.oss.zh-TW.md +5 -0
- package/dist/cli/index.cjs +1135 -599
- package/dist/cli/index.cjs.map +1 -1
- package/dist/cli/index.js +1141 -605
- package/dist/cli/index.js.map +1 -1
- package/dist/{explore-D4lCKXbA.d.ts → explore-B_bIPzmB.d.ts} +49 -1
- package/dist/{explore-Dj1j_GyN.d.cts → explore-COqHKDoK.d.cts} +49 -1
- package/dist/index.cjs +654 -258
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +12 -2
- package/dist/index.d.ts +12 -2
- package/dist/index.js +654 -258
- package/dist/index.js.map +1 -1
- package/dist/server/index.cjs +974 -442
- package/dist/server/index.cjs.map +1 -1
- package/dist/server/index.js +980 -448
- package/dist/server/index.js.map +1 -1
- package/dist/tools/explore.cjs +528 -141
- package/dist/tools/explore.cjs.map +1 -1
- package/dist/tools/explore.d.cts +1 -1
- package/dist/tools/explore.d.ts +1 -1
- package/dist/tools/explore.js +528 -141
- package/dist/tools/explore.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,60 +1,142 @@
|
|
|
1
1
|
# @zqagent/core
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
`OpenAIProvider`，以及 CLI 与**多租户云端 Server**（含 MQTT 节点管理 v2 节点桥）。
|
|
3
|
+
**在终端、桌面或手机上，让 AI 帮你写代码、改文件、跑命令——有副作用的操作先问你。**
|
|
5
4
|
|
|
6
|
-
|
|
5
|
+
🌐 **官网与使用文档：[agent.cd-zq.com](https://agent.cd-zq.com/)**
|
|
7
6
|
|
|
8
|
-
|
|
7
|
+
[](https://agent.cd-zq.com/)
|
|
8
|
+
[](https://github.com/zqagent/zqagent/actions/workflows/ci.yml)
|
|
9
|
+
[](https://github.com/zqagent/zqagent/blob/main/LICENSE)
|
|
9
10
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
test/ # Vitest（492 用例，覆盖引擎/server/hub/web 协议）
|
|
11
|
+
ZQAgent 是可自托管的 AI 编码 Agent。它自己读代码、改文件、跑命令，但**每一个有副作用的动作都会先问你**。
|
|
12
|
+
|
|
13
|
+
- **自带模型 Key**：DeepSeek、OpenAI 或任意 OpenAI 兼容端点，用多少花多少。
|
|
14
|
+
- **审批可控**：讨论 / 计划 / 交互 / 自动四种模式，写文件、执行命令逐次确认。
|
|
15
|
+
- **多端可用**：终端 CLI、桌面应用，以及手机或 QQ 远程派任务。
|
|
16
|
+
- **可扩展**：接入 MCP 外部工具，或用命令工具、自定义 Agent 扩展能力。
|
|
17
|
+
|
|
18
|
+
## 安装
|
|
19
|
+
|
|
20
|
+
需要 **Node.js >= 18.17**。
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npm i -g @zqagent/core
|
|
24
|
+
zqagent
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
-
|
|
27
|
+
Linux 也可以零依赖安装（下载单文件可执行程序，无需 Node）：
|
|
28
28
|
|
|
29
29
|
```bash
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
import { ... } from "@zqagent/core/server"; // 服务端 API
|
|
33
|
-
import { ... } from "@zqagent/core/tools/fs"; // 单个工具
|
|
30
|
+
curl -fsSL https://agent.cd-zq.com/install.sh | sh
|
|
31
|
+
```
|
|
34
32
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
zqagent
|
|
33
|
+
首次启动输入 `/connect`，按提示选择 provider（OpenAI / DeepSeek / 通义千问 / 智谱 GLM / Kimi / 自定义）→
|
|
34
|
+
填写 API Key → 选择模型 → 设置推理强度。Key 使用 AES-256-GCM 加密保存在本机
|
|
35
|
+
`~/.config/zqagent/`，不会上传。
|
|
36
|
+
|
|
37
|
+
## 快速开始
|
|
38
|
+
|
|
39
|
+
```text
|
|
40
|
+
$ zqagent
|
|
41
|
+
[interactive][code] > 读一下这个项目，告诉我它是做什么的
|
|
42
|
+
|
|
43
|
+
● list_files .
|
|
44
|
+
● read_file README.md
|
|
45
|
+
✓ 这是一个 TypeScript 实现的 AI Agent 引擎……
|
|
46
|
+
|
|
47
|
+
[interactive][code] > 把 src/config.ts 里的默认端口改成 8788，然后跑测试
|
|
48
|
+
|
|
49
|
+
● read_file src/config.ts
|
|
50
|
+
⏵ replace_in_file 1 处修改，等待审批
|
|
51
|
+
[Y] 允许一次 [A] 总是允许 [D] 拒绝
|
|
52
|
+
> Y
|
|
53
|
+
● run_shell pnpm test
|
|
54
|
+
✓ 42 passed
|
|
55
|
+
✓ 已修改默认端口，测试通过
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
常用命令：
|
|
59
|
+
|
|
60
|
+
| 命令 | 说明 |
|
|
61
|
+
| --- | --- |
|
|
62
|
+
| `/connect` | 配置模型连接（provider / Key / 模型 / 推理强度） |
|
|
63
|
+
| `/plan` | 计划模式：只读探索，输出方案后等待确认 |
|
|
64
|
+
| `/interactive` | 交互模式：有副作用的操作逐次审批（默认） |
|
|
65
|
+
| `/auto` | 自动模式：全部放行（高风险，建议只在隔离环境使用） |
|
|
66
|
+
| `/discuss` | 讨论模式：纯只读对话 |
|
|
67
|
+
| `/sessions` | 列出并恢复历史会话 |
|
|
68
|
+
| `/agent` | 切换或维护自定义 Agent |
|
|
69
|
+
| `/mcp` | 管理 MCP 服务器 |
|
|
70
|
+
| `/tools` | 查看全部工具及其风险等级 |
|
|
71
|
+
|
|
72
|
+
任务执行过程中可以直接输入文字追加指示，无需等它跑完；连按两次 `ESC` 中断。
|
|
73
|
+
|
|
74
|
+
## 内置能力
|
|
75
|
+
|
|
76
|
+
| 类别 | 工具 |
|
|
77
|
+
| --- | --- |
|
|
78
|
+
| 文件 | `read_file` `write_file` `replace_in_file` `list_files` `grep` |
|
|
79
|
+
| Shell | `run_shell` `shell_task_output` `shell_task_kill`（持久化 shell，支持后台任务） |
|
|
80
|
+
| 网络 | `web_search` `web_fetch` |
|
|
81
|
+
| Git | `git_log` `git_status` `git_diff` |
|
|
82
|
+
| 补丁 | `apply_patch` `apply_unified_diff` |
|
|
83
|
+
| 协作 | `ask_user` `propose_plan` `request_directory` `todo_write` |
|
|
84
|
+
| 探索 | `explore`（子代理：跨文件调研，只返回结论） |
|
|
85
|
+
| 媒体 | `media`，检测到本机 ffmpeg 时另有 `ffmpeg` `ffprobe` |
|
|
86
|
+
|
|
87
|
+
共 21 个内置工具。工具可在运行时新增、删除、禁用，下一次模型调用立即生效。
|
|
88
|
+
|
|
89
|
+
## 作为库使用
|
|
90
|
+
|
|
91
|
+
```ts
|
|
92
|
+
import { TurnEngine, ToolRegistry, PermissionEngine, OpenAIProvider } from "@zqagent/core";
|
|
93
|
+
import { ... } from "@zqagent/core/server"; // 多租户 HTTP 服务
|
|
94
|
+
import { ... } from "@zqagent/core/tools/fs"; // 单个工具
|
|
38
95
|
```
|
|
39
96
|
|
|
40
|
-
##
|
|
97
|
+
## 安全模型
|
|
98
|
+
|
|
99
|
+
ZQAgent 的前提是**模型输出不可信**：
|
|
100
|
+
|
|
101
|
+
- 写文件、执行命令、访问网络默认需要审批。
|
|
102
|
+
- API Key 加密存储在本机，仓库与日志中不会出现明文。
|
|
103
|
+
- 工作区就是权限边界：以哪个用户、在哪个目录启动，就拥有该用户对该目录的权限。
|
|
104
|
+
- 不要把节点服务直接暴露到公网。
|
|
105
|
+
|
|
106
|
+
发现安全问题请**不要开公开 issue**，按
|
|
107
|
+
[SECURITY.md](https://github.com/zqagent/zqagent/blob/main/SECURITY.md) 私下报告。
|
|
108
|
+
|
|
109
|
+
## 文档
|
|
110
|
+
|
|
111
|
+
| 主题 | 文档 |
|
|
112
|
+
| --- | --- |
|
|
113
|
+
| 系统架构 | [docs/architecture.md](https://github.com/zqagent/zqagent/blob/main/docs/architecture.md) |
|
|
114
|
+
| 线协议（帧 / 消息 / 签名） | [docs/wire-protocol.md](https://github.com/zqagent/zqagent/blob/main/docs/wire-protocol.md) |
|
|
115
|
+
| 上下文压缩 | [docs/context-compaction.md](https://github.com/zqagent/zqagent/blob/main/docs/context-compaction.md) |
|
|
116
|
+
| 节点服务 REST API | [docs/server-api.md](https://github.com/zqagent/zqagent/blob/main/docs/server-api.md) |
|
|
117
|
+
| 共享库 | [docs/shared.md](https://github.com/zqagent/zqagent/blob/main/docs/shared.md) |
|
|
118
|
+
| LLM 连接排查 | [docs/llm-connection-troubleshooting.md](https://github.com/zqagent/zqagent/blob/main/docs/llm-connection-troubleshooting.md) |
|
|
119
|
+
| QQ 机器人 | [docs/qq-bot.md](https://github.com/zqagent/zqagent/blob/main/docs/qq-bot.md) |
|
|
120
|
+
|
|
121
|
+
上述文档同时提供英文版（`docs/en/`）。使用者指南见 <https://agent.cd-zq.com/>。
|
|
122
|
+
|
|
123
|
+
## 开发
|
|
124
|
+
|
|
125
|
+
本包是 monorepo 的一部分（与 `@zqagent/shared` 同源构建）：
|
|
41
126
|
|
|
42
127
|
```bash
|
|
43
|
-
pnpm
|
|
44
|
-
pnpm
|
|
45
|
-
pnpm
|
|
46
|
-
pnpm
|
|
47
|
-
pnpm
|
|
48
|
-
pnpm run build:sea # 单 CJS bundle（供 SEA）
|
|
49
|
-
pnpm run build:cli-bin # SEA 单文件可执行 → release/cli/
|
|
50
|
-
pnpm run probes:sea # 生成对照探针
|
|
51
|
-
pnpm run fetch:busybox # 下载 BusyBox-w32（Windows）
|
|
128
|
+
pnpm install
|
|
129
|
+
pnpm --filter @zqagent/core typecheck
|
|
130
|
+
pnpm --filter @zqagent/core test
|
|
131
|
+
pnpm --filter @zqagent/core build
|
|
132
|
+
pnpm --filter @zqagent/core dev # 以源码方式启动 CLI
|
|
52
133
|
```
|
|
53
134
|
|
|
54
|
-
|
|
135
|
+
贡献前请阅读
|
|
136
|
+
[CONTRIBUTING.md](https://github.com/zqagent/zqagent/blob/main/CONTRIBUTING.md)。
|
|
137
|
+
涉及权限、审批、命令执行的改动会被重点审查。
|
|
138
|
+
|
|
139
|
+
## 许可
|
|
55
140
|
|
|
56
|
-
-
|
|
57
|
-
|
|
58
|
-
- Server REST API：[../../docs/server-api.md](../../docs/server-api.md)
|
|
59
|
-
- 线协议规范（帧/信封/消息/签名）：[../../docs/wire-protocol.md](../../docs/wire-protocol.md)
|
|
60
|
-
- CLI SEA 故障排查：[../../docs/cli-sea-troubleshooting.md](../../docs/cli-sea-troubleshooting.md)
|
|
141
|
+
[Apache-2.0](https://github.com/zqagent/zqagent/blob/main/LICENSE)。
|
|
142
|
+
`@zqagent` 与 ZQAgent 名称为本项目商标，二次分发或托管服务请勿暗示官方背书。
|
package/README.oss.en.md
CHANGED
|
@@ -4,9 +4,14 @@
|
|
|
4
4
|
|
|
5
5
|
**Your AI assistant in the terminal, on the desktop, or on your phone — write code, edit files, run commands. Anything with side effects asks you first.**
|
|
6
6
|
|
|
7
|
+
🌐 **Website and docs: [agent.cd-zq.com](https://agent.cd-zq.com/en/)**
|
|
8
|
+
|
|
9
|
+
[](https://agent.cd-zq.com/en/)
|
|
7
10
|
[](https://github.com/__OSS_REPO__/actions/workflows/ci.yml)
|
|
8
11
|
[](./LICENSE)
|
|
9
12
|
[](https://nodejs.org/)
|
|
13
|
+
[](https://github.com/__OSS_REPO__)
|
|
14
|
+
[](https://www.npmjs.com/package/@zqagent/core)
|
|
10
15
|
|
|
11
16
|
|
|
12
17
|
|
package/README.oss.md
CHANGED
|
@@ -4,9 +4,14 @@
|
|
|
4
4
|
|
|
5
5
|
**在终端、桌面或手机上，让 AI 帮你写代码、改文件、跑命令——有副作用的操作先问你。**
|
|
6
6
|
|
|
7
|
+
🌐 **官网与使用文档：[agent.cd-zq.com](https://agent.cd-zq.com/)**
|
|
8
|
+
|
|
9
|
+
[](https://agent.cd-zq.com/)
|
|
7
10
|
[](https://github.com/__OSS_REPO__/actions/workflows/ci.yml)
|
|
8
11
|
[](./LICENSE)
|
|
9
12
|
[](https://nodejs.org/)
|
|
13
|
+
[](https://github.com/__OSS_REPO__)
|
|
14
|
+
[](https://www.npmjs.com/package/@zqagent/core)
|
|
10
15
|
|
|
11
16
|
|
|
12
17
|
|
package/README.oss.zh-TW.md
CHANGED
|
@@ -4,9 +4,14 @@
|
|
|
4
4
|
|
|
5
5
|
**在終端、桌面或手機上，讓 AI 幫你寫程式、改檔案、跑指令——有副作用的操作會先問你。**
|
|
6
6
|
|
|
7
|
+
🌐 **官網與使用文件：[agent.cd-zq.com](https://agent.cd-zq.com/)**
|
|
8
|
+
|
|
9
|
+
[](https://agent.cd-zq.com/)
|
|
7
10
|
[](https://github.com/__OSS_REPO__/actions/workflows/ci.yml)
|
|
8
11
|
[](./LICENSE)
|
|
9
12
|
[](https://nodejs.org/)
|
|
13
|
+
[](https://github.com/__OSS_REPO__)
|
|
14
|
+
[](https://www.npmjs.com/package/@zqagent/core)
|
|
10
15
|
|
|
11
16
|
|
|
12
17
|
|