@zqagent/core 0.0.0-stage → 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,3 +1,60 @@
-# Temporary Holding Version
+# @zqagent/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+zqagent 的引擎核心：`TurnEngine`（异步事件循环）、`ToolRegistry`、`PermissionEngine`、
+`OpenAIProvider`，以及 CLI 与**多租户云端 Server**（含 MQTT 节点管理 v2 节点桥）。
+
+依赖 `@zqagent/shared`（经 tsconfig `paths` 引用其源码，构建期打进 bundle）。
+
+## 目录
+
+```
+src/
+├── 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
+# 库
+import { TurnEngine, ToolRegistry, PermissionEngine, OpenAIProvider } from "@zqagent/core";
+import { ... } from "@zqagent/core/server";   // 服务端 API
+import { ... } from "@zqagent/core/tools/fs";  // 单个工具
+
+# CLI（全局安装）
+npm i -g @zqagent/core --registry=https://npm2.cd-zq.com/
+zqagent
+```
+
+## 开发与构建（在仓库根 ts/ 或本目录）
+
+```bash
+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）
+```
+
+## 相关文档
+
+- 系统架构与构建：[../../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.

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 名称为本项目商标，
+二次分发或托管服务请勿暗示官方背书。