@zqagent/core 0.1.30 → 0.2.5

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.

package/README.oss.md

@@ -0,0 +1,165 @@
+# ZQAgent
+
+**简体中文** · [English](./README.en.md) · [繁體中文](./README.zh-TW.md)
+
+**在终端、桌面或手机上，让 AI 帮你写代码、改文件、跑命令——有副作用的操作先问你。**
+
+[![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 是一个可自托管的 AI 编码 Agent。它自己读代码、改文件、跑命令，但**每一个有副作用的动作都会先问你**。
+
+- **自带模型 Key**：DeepSeek、OpenAI 或任意 OpenAI 兼容端点，用多少花多少，不被订阅制绑定。
+- **审批可控**：讨论 / 计划 / 交互 / 自动四种模式，写文件、执行命令逐次确认。
+- **多端可用**：终端 CLI、桌面应用，以及手机或 QQ 远程派任务。
+- **可扩展**：接入 MCP 外部工具，或用命令工具、自定义 Agent 扩展能力，改完即生效。
+
+> 本仓库是**开源部分**：Agent 引擎、内置工具、权限系统、CLI 与节点服务。
+> 云端账号、订阅与计费（Hub）为闭源，但不影响本地完整使用。
+
+---
+
+## 安装
+
+**Linux（零依赖，推荐）**
+
+```bash
+curl -fsSL https://agent.cd-zq.com/install.sh | sh
+```
+
+脚本下载对应架构的单文件可执行程序、校验 SHA-256，并装进 `PATH`，无需预先安装 Node。
+
+**其它平台 / 用 npm 管理版本**（需要 Node.js >= 18.17）
+
+```bash
+npm i -g @zqagent/core
+zqagent
+```
+
+首次启动输入 `/connect`，按提示选择 provider（DeepSeek / OpenAI / 自定义）→ 填写 API Key →
+选择模型 → 设置推理强度。Key 使用 AES-256-GCM 加密保存在本机 `~/.config/zqagent/`，
+不会上传到任何服务器。
+
+不想全局安装，也可以直接从源码运行：
+
+```bash
+pnpm install
+pnpm build
+node packages/core/bin/zqagent
+```
+
+## 快速开始
+
+```text
+$ zqagent
+[interactive][code] > 读一下这个项目，告诉我它是做什么的
+
+● list_files  .
+● read_file   README.md
+● read_file   package.json
+✓ 这是一个 TypeScript 实现的 AI Agent 引擎……
+
+[interactive][code] > 把 src/config.ts 里的默认端口改成 8788，然后跑测试
+
+● read_file        src/config.ts
+⏵ replace_in_file  1 处修改，等待审批
+  [Y] 允许一次   [A] 总是允许   [D] 拒绝
+> Y
+● run_shell        pnpm test
+  ✓ 42 passed
+✓ 已修改默认端口，测试通过
+```
+
+常用命令：
+
+| 命令 | 说明 |
+| --- | --- |
+| `/connect` | 配置模型连接（provider / Key / 模型 / 推理强度） |
+| `/plan` | 计划模式：只读探索，输出方案后等待确认 |
+| `/interactive` | 交互模式：有副作用的操作逐次审批（默认） |
+| `/auto` | 自动模式：全部放行（高风险，建议只在隔离环境使用） |
+| `/discuss` | 讨论模式：纯只读对话 |
+| `/sessions` | 列出并恢复历史会话 |
+| `/agent` | 切换或维护自定义 Agent |
+| `/mcp` | 管理 MCP 服务器 |
+| `/tools` | 查看全部工具及其风险等级 |
+
+任务执行过程中可以直接输入文字追加指示，无需等它跑完；连按两次 `ESC` 中断。
+
+## 它是怎么工作的
+
+![架构](./docs/assets/architecture.svg)
+
+一次任务由 `TurnEngine` 驱动：模型思考 → 调用工具 → 观察结果 → 进入下一轮，
+直到任务完成或达到轮次上限。
+
+所有工具调用都经过 `PermissionEngine`：每个工具声明风险等级（读 / 写 / 执行），
+再由当前运行模式决定是直接放行、还是弹出审批。
+
+## 内置工具
+
+| 类别 | 工具 |
+| --- | --- |
+| 文件 | `read_file` `write_file` `replace_in_file` `list_files` `grep` |
+| Shell | `run_shell` `shell_task_output` `shell_task_kill`（持久化 shell，支持后台任务） |
+| 网络 | `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`（子代理：跨文件调研，只返回结论） |
+| 媒体 | `media` `ffmpeg` `ffprobe`（音视频处理，需本机有 ffmpeg） |
+
+工具可在运行时新增、删除、禁用，下一次模型调用立即生效。
+
+## 安全模型
+
+ZQAgent 的前提是**模型输出不可信**：
+
+- 写文件、执行命令、访问网络默认需要审批。
+- API Key 加密存储在本机，仓库与日志中不会出现明文。
+- 工作区就是权限边界：以哪个用户、在哪个目录启动，就拥有该用户对该目录的权限。
+- 不要把节点服务直接暴露到公网。
+
+发现安全问题请**不要开公开 issue**，按 [SECURITY.md](./SECURITY.md) 私下报告。
+
+## 文档
+
+| 主题 | 文档 |
+| --- | --- |
+| 架构与事件流 | [docs/architecture.md](./docs/architecture.md) |
+| 线协议（帧 / 消息 / 签名） | [docs/wire-protocol.md](./docs/wire-protocol.md) |
+| 上下文压缩 | [docs/context-compaction.md](./docs/context-compaction.md) |
+| 节点服务 REST API | [docs/server-api.md](./docs/server-api.md) |
+| QQ 机器人 | [docs/qq-bot.md](./docs/qq-bot.md) |
+| 共享库（协议 / 加密 / 审批 / 通知） | [docs/shared.md](./docs/shared.md) |
+| Windows 终端兼容 | [docs/windows-tool-compat.md](./docs/windows-tool-compat.md) |
+| 单文件可执行（SEA）排错 | [docs/cli-sea-troubleshooting.md](./docs/cli-sea-troubleshooting.md) |
+| LLM 连接错误排查 | [docs/llm-connection-troubleshooting.md](./docs/llm-connection-troubleshooting.md) |
+
+面向使用者的指南（安装、CLI 用法、Agent、MCP）：<https://agent.cd-zq.com/>
+
+架构、线协议、REST API、共享库、上下文压缩与连接排错另有英文版：
+[architecture](./docs/en/architecture.md) · [wire-protocol](./docs/en/wire-protocol.md) ·
+[server-api](./docs/en/server-api.md) · [shared](./docs/en/shared.md) ·
+[context-compaction](./docs/en/context-compaction.md) ·
+[llm-connection](./docs/en/llm-connection-troubleshooting.md)
+
+## 开发
+
+```bash
+pnpm install
+pnpm typecheck     # tsc --noEmit
+pnpm test          # vitest
+pnpm build         # tsup → dist/
+pnpm dev           # 源码方式启动 CLI
+```
+
+提交前请阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)。涉及权限、审批、命令执行的改动会被重点审查。
+
+## 许可
+
+[Apache-2.0](./LICENSE)。`@zqagent` 与 ZQAgent 名称为本项目商标，
+二次分发或托管服务请勿暗示官方背书。

package/README.oss.zh-TW.md

@@ -0,0 +1,165 @@
+# ZQAgent
+
+[简体中文](./README.md) · [English](./README.en.md) · **繁體中文**
+
+**在終端、桌面或手機上，讓 AI 幫你寫程式、改檔案、跑指令——有副作用的操作會先問你。**
+
+[![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 是一個可自架的 AI 編碼 Agent。它會自己讀程式碼、改檔案、跑指令，但**每一個有副作用的動作都會先問你**。
+
+- **自備模型金鑰**：DeepSeek、OpenAI 或任意 OpenAI 相容端點，用多少付多少，不被訂閱制綁住。
+- **預設需審批**：討論 / 計畫 / 互動 / 自動四種模式，寫檔案、執行指令逐次確認。
+- **多端可用**：終端 CLI、桌面應用，以及從手機或 QQ 遠端派任務。
+- **可擴充**：接入 MCP 外部工具，或用指令工具、自訂 Agent 擴充能力，改完即生效。
+
+> 本儲存庫是**開源部分**：Agent 引擎、內建工具、權限系統、CLI 與節點服務。
+> 雲端帳號、訂閱與計費（Hub）為閉源，但不影響本機完整使用。
+
+---
+
+## 安裝
+
+**Linux（零依賴，推薦）**
+
+```bash
+curl -fsSL https://agent.cd-zq.com/install.sh | sh
+```
+
+腳本會下載對應架構的單檔可執行檔、驗證 SHA-256，並放進 `PATH`，不需要預先安裝 Node.js。
+
+**其它平台 / 用 npm**（需要 Node.js >= 18.17）
+
+```bash
+npm i -g @zqagent/core
+zqagent
+```
+
+首次啟動請輸入 `/connect`，依提示選擇 provider（OpenAI / DeepSeek / 通義千問 / 智譜 GLM / Kimi / 自訂）→
+輸入 API Key → 選擇模型 → 設定推理強度。金鑰以 AES-256-GCM 加密保存在本機
+`~/.config/zqagent/`，不會上傳。
+
+也可以直接從原始碼執行：
+
+```bash
+pnpm install
+pnpm build
+node packages/core/bin/zqagent
+```
+
+## 快速開始
+
+```text
+$ zqagent
+[interactive][code] > 讀一下這個專案，用三句話說明它在做什麼
+
+● list_files  .
+● read_file   README.md
+● read_file   package.json
+✓ 這是一個 TypeScript 實作的 AI Agent 引擎……
+
+[interactive][code] > 把 src/config.ts 的預設連接埠改成 8788，然後跑測試
+
+● read_file        src/config.ts
+⏵ replace_in_file  1 處修改，等待審批
+  [Y] 允許一次   [A] 總是允許   [D] 拒絕
+> Y
+● run_shell        pnpm test
+  ✓ 42 passed
+✓ 已修改預設連接埠，測試通過
+```
+
+常用指令：
+
+| 指令 | 說明 |
+| --- | --- |
+| `/connect` | 設定模型連線（provider / 金鑰 / 模型 / 推理強度） |
+| `/plan` | 計畫模式：唯讀探索，提出方案後等待確認 |
+| `/interactive` | 互動模式：有副作用的操作逐次審批（預設） |
+| `/auto` | 自動模式：全部放行（高風險，建議只在隔離環境使用） |
+| `/discuss` | 討論模式：純唯讀對話 |
+| `/sessions` | 列出並恢復歷史工作階段 |
+| `/agent` | 切換或維護自訂 Agent |
+| `/mcp` | 管理 MCP 伺服器 |
+| `/tools` | 檢視全部工具及其風險等級 |
+
+任務執行過程中可以直接輸入文字追加指示，不需等它跑完；連按兩次 `ESC` 中斷。
+
+## 運作方式
+
+![架構](./docs/assets/architecture.svg)
+
+每個任務由 `TurnEngine` 驅動：模型思考 → 呼叫工具 → 觀察結果 → 進入下一輪，
+直到任務完成或達到輪次上限。
+
+所有工具呼叫都經過 `PermissionEngine`：每個工具宣告風險等級（讀 / 寫 / 執行），
+再由目前的執行模式決定是直接放行，還是跳出審批。
+
+## 內建工具
+
+| 類別 | 工具 |
+| --- | --- |
+| 檔案 | `read_file` `write_file` `replace_in_file` `list_files` `grep` |
+| Shell | `run_shell` `shell_task_output` `shell_task_kill`（持續連線的 shell，支援背景任務） |
+| 網路 | `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`（子代理：跨檔案調研，只回傳結論） |
+| 媒體 | `media` `ffmpeg` `ffprobe`（影音處理，需本機有 ffmpeg） |
+
+工具可在執行時新增、移除、停用，下一次模型呼叫立即生效。
+
+## 安全模型
+
+ZQAgent 的前提是**模型輸出不可信**：
+
+- 寫檔案、執行指令、存取網路預設需要審批。
+- API Key 加密保存在本機，儲存庫與日誌中不會出現明文。
+- 工作區就是權限邊界：以哪個使用者、在哪個目錄啟動，就擁有該使用者對該目錄的權限。
+- 不要把節點服務直接暴露到公網。
+
+發現安全問題請**不要開公開 issue**，請依 [SECURITY.md](./SECURITY.md) 私下回報。
+
+## 文件
+
+| 主題 | 文件 |
+| --- | --- |
+| 架構與事件流 | [docs/architecture.md](./docs/architecture.md) |
+| 線協議（幀 / 訊息 / 簽章） | [docs/wire-protocol.md](./docs/wire-protocol.md) |
+| 上下文壓縮 | [docs/context-compaction.md](./docs/context-compaction.md) |
+| 節點服務 REST API | [docs/server-api.md](./docs/server-api.md) |
+| 共享函式庫（協議 / 加密 / 審批 / 通知） | [docs/shared.md](./docs/shared.md) |
+| QQ 機器人 | [docs/qq-bot.md](./docs/qq-bot.md) |
+| Windows 終端相容性 | [docs/windows-tool-compat.md](./docs/windows-tool-compat.md) |
+| CLI 單檔（SEA）打包與排錯 | [docs/cli-sea-troubleshooting.md](./docs/cli-sea-troubleshooting.md) |
+| LLM 連線錯誤排查 | [docs/llm-connection-troubleshooting.md](./docs/llm-connection-troubleshooting.md) |
+
+使用者導向的指南（安裝、CLI 用法、Agent、MCP）：<https://agent.cd-zq.com/>
+
+架構、線協議、REST API、共享函式庫、上下文壓縮與連線排錯另有英文版：
+[architecture](./docs/en/architecture.md) · [wire-protocol](./docs/en/wire-protocol.md) ·
+[server-api](./docs/en/server-api.md) · [shared](./docs/en/shared.md) ·
+[context-compaction](./docs/en/context-compaction.md) ·
+[llm-connection](./docs/en/llm-connection-troubleshooting.md)
+
+## 開發
+
+```bash
+pnpm install
+pnpm typecheck     # tsc --noEmit
+pnpm test          # vitest
+pnpm build         # tsup → dist/
+pnpm dev           # 以原始碼啟動 CLI
+```
+
+提交前請閱讀 [CONTRIBUTING.md](./CONTRIBUTING.md)。涉及權限、審批、指令執行的變更會被重點審查。
+
+## 授權
+
+[Apache-2.0](./LICENSE)。`@zqagent` 與 ZQAgent 名稱為本專案商標，
+二次散布或託管服務請勿暗示官方背書。

package/SECURITY.md

@@ -0,0 +1,51 @@
+# 安全策略
+
+## 报告漏洞
+
+**请不要用公开 issue 报告安全问题。** ZQAgent 会读写文件、执行命令，安全问题一旦公开，
+影响的是所有已部署的节点。
+
+请通过以下任一渠道私下报告：
+
+- 邮件：security@cd-zq.com（如需 PGP 加密，请先来信说明，我们会提供公钥）
+- 或通过 GitHub 的 [Private vulnerability reporting](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability)
+
+请在报告中包含：
+
+- 受影响的版本（`zqagent --version`）与平台
+- 复现步骤或最小复现脚本
+- 影响范围（能否绕过审批、读到工作区外的文件、执行未授权命令等）
+
+## 响应时限
+
+| 阶段 | 目标 |
+| --- | --- |
+| 确认收到 | 3 个工作日内 |
+| 初步评估与定级 | 7 个工作日内 |
+| 修复与披露 | 视严重程度，一般 30 天内 |
+
+修复发布后，我们会在 CHANGELOG 与 GitHub Security Advisory 中致谢报告者（除非你要求匿名）。
+
+## 支持范围
+
+| 版本 | 是否接收安全修复 |
+| --- | --- |
+| 最新 minor | ✅ |
+| 上一个 minor | ✅（仅高危） |
+| 更早版本 | ❌ 请先升级 |
+
+## 安全边界（部署前请知悉）
+
+ZQAgent 的设计前提是：**模型输出不可信**。因此：
+
+- 写文件、执行命令、访问网络等有副作用的操作默认需要逐次审批（`interactive` 模式）。
+- `auto` 模式会跳过审批，只应在隔离环境或可丢弃的工作区使用。
+- API Key 使用 AES-256-GCM 加密保存在本机 `~/.config/zqagent/`，但仍建议为 agent 单独申请一把低权限、可限额的 Key。
+- 不要把 `zqagent serve` 直接暴露到公网；对外提供服务请通过反向代理并启用鉴权。
+- 工作区即权限边界：以哪个用户、在哪个目录启动，就拥有该用户对该目录的全部权限。
+
+## 不在范围内的报告
+
+- 需要用户主动执行 `auto` 模式或手动放行后才会发生的问题
+- 依赖库自身的已知漏洞（请同时反馈给上游，我们会跟进升级）
+- 缺少速率限制、缺少 HTTPS 等纯部署配置问题（可提普通 issue）

package/dist/{ToolRegistry-BmvPxgMr.d.cts → ToolRegistry-C3pTFiaJ.d.cts}

@@ -86,7 +86,7 @@ interface Message {
         };
     }[];
     /** 通知类型：错误 / 中断 / 上下文压缩 / 模型切换 */
-    kind?: "error" | "interrupted" | "compacted" | "model_switch";
+    kind?: "error" | "interrupted" | "compacted" | "model_switch" | "retry";
     /** 通知附加文本 */
     text?: string;
 }
@@ -139,6 +139,14 @@ interface ToolMetadata {
     /** 是否强制需要人工审批 */
     requiresApproval: boolean;
 }
+/** 工具执行上下文（由引擎注入） */
+interface ToolExecContext {
+    /**
+     * 中断信号。可中断的工具（如 run_shell）应把它传给子进程，
+     * 使用户中断能立即终止正在执行的命令，而不是等命令自然结束。
+     */
+    signal?: AbortSignal;
+}
 /** 单个工具规格 */
 interface ToolSpec {
     /** 工具名 */
@@ -146,7 +154,7 @@ interface ToolSpec {
     /** OpenAI 工具 Schema（供 LLM 识别调用方式） */
     schema: ToolSchema;
     /** 实际执行函数 */
-    func: (args: Record<string, unknown>) => unknown;
+    func: (args: Record<string, unknown>, ctx?: ToolExecContext) => unknown;
     /** 工具元数据（供权限引擎评估风险） */
     metadata: ToolMetadata;
     /**
@@ -171,7 +179,7 @@ declare class ToolRegistry {
      * @param source   工具来源标识（展示用，如 "mcp:<server>"）
      * @returns 注册完成后的 ToolSpec
      */
-    register(func: (args: Record<string, unknown>) => unknown, metadata: ToolMetadata, schema?: ToolSchema, source?: string): ToolSpec;
+    register(func: (args: Record<string, unknown>, ctx?: ToolExecContext) => unknown, metadata: ToolMetadata, schema?: ToolSchema, source?: string): ToolSpec;
     /** 移除工具。@returns 是否移除成功 */
     remove(name: string): boolean;
     /** 是否存在指定工具 */
@@ -193,9 +201,10 @@ declare class ToolRegistry {
     /**
      * 执行工具
      *
+     * @param ctx 执行上下文（引擎注入的中断信号等）
      * @throws 工具未注册时抛出错误
      */
-    execute(name: string, args: Record<string, unknown>): unknown;
+    execute(name: string, args: Record<string, unknown>, ctx?: ToolExecContext): unknown;
     /**
      * 构建默认 Schema
      *

package/dist/{ToolRegistry-BmvPxgMr.d.ts → ToolRegistry-C3pTFiaJ.d.ts}

@@ -86,7 +86,7 @@ interface Message {
         };
     }[];
     /** 通知类型：错误 / 中断 / 上下文压缩 / 模型切换 */
-    kind?: "error" | "interrupted" | "compacted" | "model_switch";
+    kind?: "error" | "interrupted" | "compacted" | "model_switch" | "retry";
     /** 通知附加文本 */
     text?: string;
 }
@@ -139,6 +139,14 @@ interface ToolMetadata {
     /** 是否强制需要人工审批 */
     requiresApproval: boolean;
 }
+/** 工具执行上下文（由引擎注入） */
+interface ToolExecContext {
+    /**
+     * 中断信号。可中断的工具（如 run_shell）应把它传给子进程，
+     * 使用户中断能立即终止正在执行的命令，而不是等命令自然结束。
+     */
+    signal?: AbortSignal;
+}
 /** 单个工具规格 */
 interface ToolSpec {
     /** 工具名 */
@@ -146,7 +154,7 @@ interface ToolSpec {
     /** OpenAI 工具 Schema（供 LLM 识别调用方式） */
     schema: ToolSchema;
     /** 实际执行函数 */
-    func: (args: Record<string, unknown>) => unknown;
+    func: (args: Record<string, unknown>, ctx?: ToolExecContext) => unknown;
     /** 工具元数据（供权限引擎评估风险） */
     metadata: ToolMetadata;
     /**
@@ -171,7 +179,7 @@ declare class ToolRegistry {
      * @param source   工具来源标识（展示用，如 "mcp:<server>"）
      * @returns 注册完成后的 ToolSpec
      */
-    register(func: (args: Record<string, unknown>) => unknown, metadata: ToolMetadata, schema?: ToolSchema, source?: string): ToolSpec;
+    register(func: (args: Record<string, unknown>, ctx?: ToolExecContext) => unknown, metadata: ToolMetadata, schema?: ToolSchema, source?: string): ToolSpec;
     /** 移除工具。@returns 是否移除成功 */
     remove(name: string): boolean;
     /** 是否存在指定工具 */
@@ -193,9 +201,10 @@ declare class ToolRegistry {
     /**
      * 执行工具
      *
+     * @param ctx 执行上下文（引擎注入的中断信号等）
      * @throws 工具未注册时抛出错误
      */
-    execute(name: string, args: Record<string, unknown>): unknown;
+    execute(name: string, args: Record<string, unknown>, ctx?: ToolExecContext): unknown;
     /**
      * 构建默认 Schema
      *