@zqagent/core 0.1.30 → 0.2.4

package/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# 贡献指南
+
+感谢你愿意改进 ZQAgent。这个项目能执行真实命令、修改真实文件，所以我们对变更的要求比一般项目更严格。
+
+## 开始之前
+
+- 小改动（错别字、文档、明显的 bug 修复）可以直接提 PR。
+- **大改动请先开 issue 讨论**，尤其是：新增工具、修改权限/审批逻辑、改动线协议（`proto/`）、改动对外 API。未经讨论的大 PR 很可能被拒绝，避免你的时间被浪费。
+- 涉及安全的问题请看 [SECURITY.md](./SECURITY.md)，不要开公开 issue。
+
+## 开发环境
+
+要求 Node.js >= 18.17，包管理器使用 pnpm。
+
+```bash
+pnpm install
+pnpm --filter @zqagent/core test        # 单元测试
+pnpm --filter @zqagent/core typecheck   # 类型检查
+pnpm --filter @zqagent/core dev         # 本地启动 CLI
+```
+
+提交前请确保 `test` 与 `typecheck` 都通过。
+
+## 代码约定
+
+- 使用 TypeScript，保持 `strict` 通过；不要用 `any` 掩盖类型问题。
+- 注释用中文，只解释「为什么」，不复述代码在做什么。
+- 新增工具体现在 `src/tools/`，并在工具注册处声明风险等级（`read` / `write` / `exec`）。**风险等级标错会导致审批被绕过，属于阻断性问题。**
+- 任何写文件、起进程、发网络请求的逻辑都必须走 `PermissionEngine`，不要自己直接调用 `fs.writeFile` 或 `child_process`。
+- 改动线协议时同步更新 `proto/` 与 `docs/wire-protocol.md`，并跑 `pnpm --filter @zqagent/core exec tsx scripts/gen_wire_vectors.ts` 重新生成向量。
+
+## 双语文档
+
+`docs/architecture.md` 与 `docs/wire-protocol.md` 有英文版（`docs/en/`）。
+修改这两篇时请**同一次提交里同步更新英文版**，否则英文读者会看到过期内容。
+其余文档目前只有中文，新增时不必强制翻译，但请在 README 的文档表中保持链接有效
+（导出脚本会校验所有相对链接，失效会直接失败）。
+
+## 测试
+
+- 修 bug 请附带一个能复现该 bug 的测试。
+- 新增工具需要覆盖：正常路径、审批被拒绝、参数非法。
+- 不要提交依赖真实网络的测试；需要外部服务时用本地 stub。
+
+## 提交信息
+
+采用 Conventional Commits：
+
+```
+feat(cli): 支持 /model 切换时保留会话
+fix(permissions): 修复 auto 模式下命令白名单失效
+docs: 补充 MCP http 传输示例
+```
+
+## PR 检查清单
+
+- [ ] `test` 与 `typecheck` 通过
+- [ ] 新增/修改的行为有测试覆盖
+- [ ] 没有提交密钥、真实账号、内部地址或 `dist/`、`node_modules/`
+- [ ] 涉及权限、审批、命令执行的改动，在 PR 描述中说明了安全影响
+- [ ] 面向用户的变更已同步文档（`packages/site/docs/` 或 `docs/`）
+
+## 许可
+
+提交 PR 即表示你同意以 [Apache-2.0](./LICENSE) 许可贡献你的代码，并确认你有权这样做。

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Chengdu Zhiqian Technology Co., Ltd.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,183 +1,60 @@
-# zqagent TS
+# @zqagent/core
 
-TypeScript 实现的 zqagent Agent 引擎核心（CLI），复刻 Python 版的核心机制：
+zqagent 的引擎核心：`TurnEngine`（异步事件循环）、`ToolRegistry`、`PermissionEngine`、
+`OpenAIProvider`，以及 CLI 与**多租户云端 Server**（含 MQTT 节点管理 v2 节点桥）。
 
-- **TurnEngine** — 异步生成器事件循环，驱动"思考 → 工具调用 → 观察"的迭代
-- **ToolRegistry** — 工具注册 / 执行 / 元数据管理
-- **PermissionEngine** — 工具风险分类 + 运行模式门控 + Y/N 交互审批
-- **OpenAIProvider** — 基于 OpenAI SDK 的流式 LLM 调用
+依赖 `@zqagent/shared`（经 tsconfig `paths` 引用其源码，构建期打进 bundle）。
 
-## 快速开始
-
-### 全局安装（推荐）
-
-```bash
-# 从私有仓库全局安装（其它机器需先配置该 registry，或加 --registry 参数）
-npm i -g @zqagent/core --registry=https://npm2.cd-zq.com/
-
-# 启动 CLI
-zqagent
-```
-
-启动后无需手动写 `.env`，输入 `/connect` 即可交互式配置 LLM 连接：
-选择 provider（DeepSeek / OpenAI / 自定义）→ 输入 API Key → 自动刷新模型列表并选择 →
-设置推理强度。API Key 会 AES-256-GCM 加密保存到本机 `~/.config/zqagent/`。
-
-### 本地开发
-
-```bash
-# 安装依赖
-npm install
-
-# 配置环境变量（复制为 .env 后填写），或启动后直接 /connect
-#   OPENAI_API_KEY=sk-...          # 必填（未用 /connect 时）
-#   OPENAI_MODEL=gpt-4o            # 可选，默认 gpt-4o
-#   OPENAI_BASE_URL=...            # 可选，自定义端点
-#   WORKSPACE=./                   # 可选，工作区根目录，默认当前目录
-cp .env.example .env
-
-# 启动 CLI
-npm run dev
-```
-
-## 使用
-
-启动后进入交互式 CLI，直接输入自然语言任务即可。内置命令：
-
-| 命令 | 说明 |
-| --- | --- |
-| `/plan` | 切换为计划模式（只读探索 + 计划提案） |
-| `/interactive` | 切换为交互式审批模式（默认） |
-| `/auto` | 切换为全自动模式（无需审批，高风险） |
-| `/discuss` | 切换为讨论模式（只读对话） |
-| `/mode` | 显示当前模式 |
-| `/connect` | 连接 LLM（选 provider → key → 刷新模型列表 → 推理强度） |
-| `/connect rm` | 清除连接配置（回退到环境变量） |
-| `/sessions` | 列出已保存会话并选择恢复（切换后回显最近消息） |
-| `/history` | 列出当前会话的用户指令 |
-| `/model <id>` | 切换 LLM 模型 |
-| `/agent <name>` | 切换 agent（Prompt + 可选模型同步） |
-| `/agents` | 列出所有 agent（当前高亮） |
-| `/agent add <name> <prompt...>` | 新增自定义 agent |
-| `/agent edit <name> <prompt...>` | 修改 agent 的 Prompt（当前 agent 即时热更新） |
-| `/agent rm <name>` | 删除 agent |
-| `/agent show [name]` | 查看 agent 详情 |
-| `/mcp` | 列出 MCP 服务器与连接状态 |
-| `/mcp add <name> stdio <cmd...>\|http <url>` | 添加并连接 MCP 服务器（工具自动注入） |
-| `/mcp rm\|enable\|disable\|refresh [name]` | 移除 / 启用 / 禁用 / 刷新工具列表 |
-| `/tools` | 列出所有工具（来源、风险、禁用状态） |
-| `/tool add <name> <cmd...>` | 添加命令工具（执行 shell 命令） |
-| `/tool rm\|disable\|enable <name>` | 移除 / 禁用 / 启用工具 |
-| `/clear` | 清空会话，重建引擎 |
-| `quit` / `exit` | 退出 |
-| `reset` | 重置会话 |
-
-> **Agent 机制**：内置 `code`（编程助手）/ `cowork`（通用协作）两个 agent。
-> 通过 `/agent add / edit / rm` 可运行时维护任意数量的 agent（名称 + Prompt + 可选模型）；
-> 定义持久化到项目内 `.agent/agents.json`（可提交 git，随项目共享）。
-> 切换 agent 时若其配置了 `model`，LLM 模型会同步切换；否则沿用当前模型。
-> 提示符以 `[模式][agent名] > ` 形式展示当前状态，如 `[plan][code] > `。
-
-> **MCP 与工具管理**：运行时可通过 `/mcp add` 注入外部 MCP 服务器
-> （stdio 本地进程或 http 远程端点），其工具自动以 `mcp__<server>__<tool>`
-> 前缀注册到工具表；`/tool add` 可创建执行 shell 命令的命令工具。
-> 引擎每次请求都实时拉取工具 schema，因此工具的新增 / 移除 / 禁用 / 替换
-> 对下一次 LLM 调用立即生效，无需重启。
-> MCP 服务器配置持久化到 `.agent/mcp.json`，命令工具到 `.agent/tools.json`
-> （均随项目走，可提交 git）；MCP 注入工具默认按高风险归类，交互模式下需逐次审批。
-
-### 运行模式
-
-| 模式 | 行为 |
-| --- | --- |
-| `discuss` | 只读，禁止一切写入与执行 |
-| `plan` | 只读，禁止一切写入与执行，面向计划提案 |
-| `interactive` | 有副作用的操作需用户逐次审批（默认） |
-| `auto` | 有副作用的操作全部放行（高风险，需自行承担） |
-
-交互模式下，审批卡片支持：`Y` 允许一次 / `A` 总是允许此工具 / `D` 拒绝；
-`run_shell` 额外支持 `C` 总是允许此命令（按具体命令白名单，比放行整个工具更安全）。
-
-## 内置工具（18 个）
-
-| 类别 | 工具 |
-| --- | --- |
-| 文件 | `read_file`, `write_file`, `replace_in_file`, `list_files`, `grep` |
-| Shell | `run_shell`（持久化 shell，命令白名单在 Auto 模式下自动放行） |
-| 网络 | `web_search`, `web_fetch` |
-| Git | `git_log`, `git_status`, `git_diff`（只读） |
-| 补丁 | `apply_patch`, `apply_unified_diff` |
-| 协作 | `ask_user`, `propose_plan`, `request_directory` |
-| 任务 | `todo_write`（共享进度状态） |
-| 子代理 | `explore`（独立 TurnEngine 实例，只读研究） |
-
-## 项目结构
+## 目录
 
 ```
 src/
-├── index.ts                  # CLI 入口：装配组件、命令行审批器、事件渲染
-├── agents/
-│   └── AgentRegistry.ts      # Agent 注册表（运行时增删改查 / 切换 agent）
-├── mcp/
-│   ├── McpClient.ts          # 单个 MCP 服务器客户端（stdio / http）
-│   └── McpManager.ts         # 多服务器管理 + 工具动态注入 ToolRegistry
-├── engine/
-│   ├── TurnEngine.ts         # 异步生成器事件循环
-│   ├── events.ts             # 事件类型定义
-│   └── types.ts
-├── permissions/
-│   └── PermissionEngine.ts   # 风险分类 + 模式门控 + 审批决策
-├── providers/
-│   └── OpenAIProvider.ts     # 流式 LLM 调用
-├── prompts/
-│   └── index.ts              # 中文系统提示词模板
-└── tools/
-    ├── ToolRegistry.ts       # 工具注册表（注册/移除/禁用/替换）
-    ├── files.ts  shell.ts  search.ts  web.ts
-    ├── git.ts  diff.ts  todo.ts  explore.ts
-    └── ask.ts  plan.ts  directories.ts
-test/                         # Vitest 单元测试
+├── index.ts          # 库入口（re-export）
+├── cli/              # CLI（index.ts 入口 / 连接向导 / 输入 / 会话元数据 …）
+├── agents/           # Agent 注册表（运行时维护 agent）
+├── mcp/              # MCP 客户端与管理（stdio / http）
+├── engine/           # TurnEngine / events / compaction / hooks / renderer
+├── permissions/      # 风险分类 + 模式门控 + 审批
+├── providers/        # OpenAI 兼容 provider（流式 / chat）
+├── prompts/          # 中文系统提示词
+├── tools/            # 19 个内置工具（文件/shell/搜索/web/git/补丁/协作/子代理/媒体）
+└── server/           # 多租户 API + 项目/节点 + MQTT 节点管理 v2 桥（FleetNodeBridge/FleetCommands）
+bin/zqagent           # CLI 可执行入口
+scripts/              # SEA 单文件构建 / 冒烟 / 探针 / busybox 下载
+test/                 # Vitest（492 用例，覆盖引擎/server/hub/web 协议）
 ```
 
-## 开发
+## 使用
 
 ```bash
-npm run build   # tsc 类型检查与构建
-npm test        # Vitest 运行测试
-```
+# 库
+import { TurnEngine, ToolRegistry, PermissionEngine, OpenAIProvider } from "@zqagent/core";
+import { ... } from "@zqagent/core/server";   // 服务端 API
+import { ... } from "@zqagent/core/tools/fs";  // 单个工具
 
-## 云端多租户 Server
-
-`src/server/` 提供多租户云端化 API（独立于 CLI）：每租户独立工作区/模型配置/状态存储，
-支持审批与提问的**挂起 → 持久化 → 超时回收 → resume 恢复**完整链路。
-
-```bash
-npm run server   # 启动（默认端口 8787，首次启动自动创建演示租户 demo/demo-key）
+# CLI（全局安装）
+npm i -g @zqagent/core --registry=https://npm2.cd-zq.com/
+zqagent
 ```
 
-- 完整 curl 教程（审批/提问/超时回收/多租户隔离）：[docs/server-api.md](docs/server-api.md)
-- 一键测试：`bash scripts/test-server.sh`（无需 Key 的烟雾测试，18 项）；模型配置
-  （`OPENAI_API_KEY` 等）未显式设置时自动从项目 `.env` 读取，此时为完整链路测试
-  （真实对话 + 提问挂起 + 超时回收 + resume 恢复，24 项）
-
-## 桌面应用（macOS / Windows）
-
-`desktop/` 把 Server 打包成桌面应用：Tauri 2 外壳 + 内嵌 Node sidecar，前端复用
-`test_web/` 的 React 页面（本地引擎自动连接、托盘常驻、自动更新）。
+## 开发与构建（在仓库根 ts/ 或本目录）
 
 ```bash
-# 开发调试
-cd desktop && npm install && npm run tauri dev
-
-# 一键构建
-./desktop/scripts/build_macos.sh          # macOS → DMG
-.\desktop\scripts\build_windows.ps1       # Windows → NSIS + MSI
+pnpm run dev            # CLI（tsx packages/core/src/cli/index.ts）
+pnpm run server         # 多租户 Server :8787
+pnpm run build          # tsup → dist/（含 dts）
+pnpm run test           # Vitest
+pnpm run typecheck      # tsc --noEmit
+pnpm run build:sea      # 单 CJS bundle（供 SEA）
+pnpm run build:cli-bin  # SEA 单文件可执行 → release/cli/
+pnpm run probes:sea     # 生成对照探针
+pnpm run fetch:busybox  # 下载 BusyBox-w32（Windows）
 ```
 
-详见 [desktop/README.md](desktop/README.md)。
-
-## 测试 Web 界面（test_web/）
+## 相关文档
 
-`test_web/` 是 Server 的 React 测试页：多租户 profile 管理、会话/审批/提问全链路。
-桌面壳会注入 `window.__ZQ_HTTP__/__ZQ_API_KEY__` 并自动注册「本地引擎」profile，
-浏览器模式（`npm run dev`）行为不变。
+- 系统架构与构建：[../../docs/architecture.md](../../docs/architecture.md)
+- CLI 使用/工具/Agent/MCP：[../../packages/site/docs/guide/](../../packages/site/docs/guide/)
+- Server REST API：[../../docs/server-api.md](../../docs/server-api.md)
+- 线协议规范（帧/信封/消息/签名）：[../../docs/wire-protocol.md](../../docs/wire-protocol.md)
+- CLI SEA 故障排查：[../../docs/cli-sea-troubleshooting.md](../../docs/cli-sea-troubleshooting.md)

package/README.oss.en.md

@@ -0,0 +1,161 @@
+# ZQAgent
+
+**English** · [简体中文](./README.md) · [繁體中文](./README.zh-TW.md)
+
+**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.**
+
+[![CI](https://github.com/__OSS_REPO__/actions/workflows/ci.yml/badge.svg)](https://github.com/__OSS_REPO__/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D18.17-brightgreen.svg)](https://nodejs.org/)
+
+![zqagent CLI](./docs/assets/cli-help.svg)
+
+ZQAgent is a self-hostable AI coding agent. It reads code, edits files, and runs commands on its own — but **every side-effecting action asks for your approval first**.
+
+- **Bring your own model key** — DeepSeek, OpenAI, or any OpenAI-compatible endpoint. Pay for what you use instead of a subscription.
+- **Approval by default** — four modes (discuss / plan / interactive / auto); file writes and shell commands are confirmed one by one.
+- **Works everywhere** — terminal CLI, desktop app, and remote task dispatch from your phone or QQ.
+- **Extensible** — plug in MCP servers, or add command tools and custom agents; changes take effect immediately.
+
+> This repository is the **open-source part**: the agent engine, built-in tools, permission system, CLI, and node service.
+> Cloud accounts, subscriptions, and billing (Hub) are closed source, and are not required for local use.
+
+---
+
+## Install
+
+**Linux (no dependencies, recommended)**
+
+```bash
+curl -fsSL https://agent.cd-zq.com/install.sh | sh
+```
+
+The script downloads a single-file executable for your architecture, verifies its SHA-256, and puts it on your `PATH`. No Node.js required.
+
+**Other platforms / npm** (requires Node.js >= 18.17)
+
+```bash
+npm i -g @zqagent/core
+zqagent
+```
+
+On first launch, run `/connect` and follow the prompts: pick a provider (OpenAI / DeepSeek / Qwen / Zhipu GLM / Kimi / custom) → enter your API key → choose a model → set reasoning effort. Keys are encrypted with AES-256-GCM and stored locally in `~/.config/zqagent/`; they are never uploaded.
+
+To run from source instead:
+
+```bash
+pnpm install
+pnpm build
+node packages/core/bin/zqagent
+```
+
+## Quick start
+
+```text
+$ zqagent
+[interactive][code] > read this project and tell me what it does
+
+● list_files  .
+● read_file   README.md
+● read_file   package.json
+✓ This is a TypeScript AI agent engine...
+
+[interactive][code] > change the default port in src/config.ts to 8788, then run the tests
+
+● read_file        src/config.ts
+⏵ replace_in_file  1 change, waiting for approval
+  [Y] allow once   [A] always allow   [D] deny
+> Y
+● run_shell        pnpm test
+  ✓ 42 passed
+✓ Changed the default port; tests pass
+```
+
+Common commands:
+
+| Command | Description |
+| --- | --- |
+| `/connect` | Configure the model connection (provider / key / model / reasoning effort) |
+| `/plan` | Plan mode: read-only exploration, proposes a plan and waits |
+| `/interactive` | Interactive mode: every side-effecting action needs approval (default) |
+| `/auto` | Auto mode: allow everything (risky — use in isolated environments only) |
+| `/discuss` | Discuss mode: read-only conversation |
+| `/sessions` | List and resume previous sessions |
+| `/agent` | Switch or maintain custom agents |
+| `/mcp` | Manage MCP servers |
+| `/tools` | Show all tools and their risk levels |
+
+While a task is running you can type additional instructions at any time — no need to wait for it to finish. Press `ESC` twice to interrupt.
+
+## How it works
+
+![Architecture](./docs/assets/architecture.svg)
+
+`TurnEngine` drives each task: the model thinks → calls a tool → observes the result → next round,
+until the task is done or the turn limit is reached.
+
+Every tool call goes through `PermissionEngine`: each tool declares a risk level (read / write / exec),
+and the current mode decides whether it runs directly or requires approval.
+
+## Built-in tools
+
+| Category | Tools |
+| --- | --- |
+| Files | `read_file` `write_file` `replace_in_file` `list_files` `grep` |
+| Shell | `run_shell` `shell_task_output` `shell_task_kill` (persistent shell, background tasks) |
+| Web | `web_search` `web_fetch` |
+| Git | `git_log` `git_status` `git_diff` |
+| Patches | `apply_patch` `apply_unified_diff` |
+| Collaboration | `ask_user` `propose_plan` `request_directory` `todo_write` |
+| Exploration | `explore` (sub-agent for cross-file research; returns conclusions only) |
+| Media | `media` `ffmpeg` `ffprobe` (audio/video; requires ffmpeg on the host) |
+
+Tools can be added, removed, or disabled at runtime; the next model call picks up the change immediately.
+
+## Security model
+
+ZQAgent assumes **model output is untrusted**:
+
+- File writes, command execution, and network access require approval by default.
+- API keys are encrypted locally and never appear in the repository or logs.
+- The workspace is the permission boundary: the agent has exactly the permissions of the user and directory it was started in.
+- Do not expose the node service directly to the internet.
+
+Please **do not open a public issue** for security problems — follow [SECURITY.md](./SECURITY.md) instead.
+
+## Documentation
+
+| Topic | Document |
+| --- | --- |
+| Architecture and event flow | [docs/en/architecture.md](./docs/en/architecture.md) |
+| Wire protocol (frames / messages / signatures) | [docs/en/wire-protocol.md](./docs/en/wire-protocol.md) |
+| Node service REST API | [docs/en/server-api.md](./docs/en/server-api.md) |
+| Shared library (protocol / crypto / approvals / notifications) | [docs/en/shared.md](./docs/en/shared.md) |
+| Context compaction | [docs/en/context-compaction.md](./docs/en/context-compaction.md) |
+| LLM connection errors | [docs/en/llm-connection-troubleshooting.md](./docs/en/llm-connection-troubleshooting.md) |
+| QQ bot integration | [docs/qq-bot.md](./docs/qq-bot.md) *(Chinese)* |
+| Windows tool compatibility | [docs/windows-tool-compat.md](./docs/windows-tool-compat.md) *(Chinese)* |
+| CLI single-file (SEA) packaging and troubleshooting | [docs/cli-sea-troubleshooting.md](./docs/cli-sea-troubleshooting.md) *(Chinese)* |
+
+Every document except the QQ bot, Windows compatibility, and CLI-packaging notes is available
+in English; those three are currently Chinese only.
+
+User-facing guides (installation, CLI usage, agents, MCP): <https://agent.cd-zq.com/en/>
+
+## Development
+
+```bash
+pnpm install
+pnpm typecheck     # tsc --noEmit
+pnpm test          # vitest
+pnpm build         # tsup → dist/
+pnpm dev           # run the CLI from source
+```
+
+Please read [CONTRIBUTING.md](./CONTRIBUTING.md) before submitting a pull request. Changes touching permissions,
+approval, or command execution get extra scrutiny.
+
+## License
+
+[Apache-2.0](./LICENSE). `@zqagent` and the ZQAgent name are trademarks of this project;
+redistributions and hosted services must not imply official endorsement.