@zqagent/core 0.1.30 → 0.2.5

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,139 @@
-# zqagent TS
+# @zqagent/core
 
-TypeScript 实现的 zqagent Agent 引擎核心（CLI），复刻 Python 版的核心机制：
+**在终端、桌面或手机上，让 AI 帮你写代码、改文件、跑命令——有副作用的操作先问你。**
 
-- **TurnEngine** — 异步生成器事件循环，驱动"思考 → 工具调用 → 观察"的迭代
-- **ToolRegistry** — 工具注册 / 执行 / 元数据管理
-- **PermissionEngine** — 工具风险分类 + 运行模式门控 + Y/N 交互审批
-- **OpenAIProvider** — 基于 OpenAI SDK 的流式 LLM 调用
+[![CI](https://github.com/zqagent/zqagent/actions/workflows/ci.yml/badge.svg)](https://github.com/zqagent/zqagent/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/zqagent/zqagent/blob/main/LICENSE)
 
-## 快速开始
+ZQAgent 是可自托管的 AI 编码 Agent。它自己读代码、改文件、跑命令，但**每一个有副作用的动作都会先问你**。
 
-### 全局安装（推荐）
+- **自带模型 Key**：DeepSeek、OpenAI 或任意 OpenAI 兼容端点，用多少花多少。
+- **审批可控**：讨论 / 计划 / 交互 / 自动四种模式，写文件、执行命令逐次确认。
+- **多端可用**：终端 CLI、桌面应用，以及手机或 QQ 远程派任务。
+- **可扩展**：接入 MCP 外部工具，或用命令工具、自定义 Agent 扩展能力。
 
-```bash
-# 从私有仓库全局安装（其它机器需先配置该 registry，或加 --registry 参数）
-npm i -g @zqagent/core --registry=https://npm2.cd-zq.com/
+## 安装
 
-# 启动 CLI
+需要 **Node.js >= 18.17**。
+
+```bash
+npm i -g @zqagent/core
 zqagent
 ```
 
-启动后无需手动写 `.env`，输入 `/connect` 即可交互式配置 LLM 连接：
-选择 provider（DeepSeek / OpenAI / 自定义）→ 输入 API Key → 自动刷新模型列表并选择 →
-设置推理强度。API Key 会 AES-256-GCM 加密保存到本机 `~/.config/zqagent/`。
-
-### 本地开发
+Linux 也可以零依赖安装（下载单文件可执行程序，无需 Node）：
 
 ```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
+curl -fsSL https://agent.cd-zq.com/install.sh | sh
 ```
 
-## 使用
+首次启动输入 `/connect`，按提示选择 provider（OpenAI / DeepSeek / 通义千问 / 智谱 GLM / Kimi / 自定义）→
+填写 API Key → 选择模型 → 设置推理强度。Key 使用 AES-256-GCM 加密保存在本机
+`~/.config/zqagent/`，不会上传。
+
+## 快速开始
 
-启动后进入交互式 CLI，直接输入自然语言任务即可。内置命令：
+```text
+$ zqagent
+[interactive][code] > 读一下这个项目，告诉我它是做什么的
+
+● list_files  .
+● read_file   README.md
+✓ 这是一个 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
+✓ 已修改默认端口，测试通过
+```
+
+常用命令：
 
 | 命令 | 说明 |
 | --- | --- |
-| `/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` | 有副作用的操作全部放行（高风险，需自行承担） |
+| `/connect` | 配置模型连接（provider / Key / 模型 / 推理强度） |
+| `/plan` | 计划模式：只读探索，输出方案后等待确认 |
+| `/interactive` | 交互模式：有副作用的操作逐次审批（默认） |
+| `/auto` | 自动模式：全部放行（高风险，建议只在隔离环境使用） |
+| `/discuss` | 讨论模式：纯只读对话 |
+| `/sessions` | 列出并恢复历史会话 |
+| `/agent` | 切换或维护自定义 Agent |
+| `/mcp` | 管理 MCP 服务器 |
+| `/tools` | 查看全部工具及其风险等级 |
 
-交互模式下，审批卡片支持：`Y` 允许一次 / `A` 总是允许此工具 / `D` 拒绝；
-`run_shell` 额外支持 `C` 总是允许此命令（按具体命令白名单，比放行整个工具更安全）。
+任务执行过程中可以直接输入文字追加指示，无需等它跑完；连按两次 `ESC` 中断。
 
-## 内置工具（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 单元测试
+| 文件 | `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 时另有 `ffmpeg` `ffprobe` |
+
+共 21 个内置工具。工具可在运行时新增、删除、禁用，下一次模型调用立即生效。
+
+## 作为库使用
+
+```ts
+import { TurnEngine, ToolRegistry, PermissionEngine, OpenAIProvider } from "@zqagent/core";
+import { ... } from "@zqagent/core/server";   // 多租户 HTTP 服务
+import { ... } from "@zqagent/core/tools/fs"; // 单个工具
 ```
 
-## 开发
+## 安全模型
 
-```bash
-npm run build   # tsc 类型检查与构建
-npm test        # Vitest 运行测试
-```
+ZQAgent 的前提是**模型输出不可信**：
 
-## 云端多租户 Server
+- 写文件、执行命令、访问网络默认需要审批。
+- API Key 加密存储在本机，仓库与日志中不会出现明文。
+- 工作区就是权限边界：以哪个用户、在哪个目录启动，就拥有该用户对该目录的权限。
+- 不要把节点服务直接暴露到公网。
 
-`src/server/` 提供多租户云端化 API（独立于 CLI）：每租户独立工作区/模型配置/状态存储，
-支持审批与提问的**挂起 → 持久化 → 超时回收 → resume 恢复**完整链路。
+发现安全问题请**不要开公开 issue**，按
+[SECURITY.md](https://github.com/zqagent/zqagent/blob/main/SECURITY.md) 私下报告。
 
-```bash
-npm run server   # 启动（默认端口 8787，首次启动自动创建演示租户 demo/demo-key）
-```
+## 文档
+
+| 主题 | 文档 |
+| --- | --- |
+| 系统架构 | [docs/architecture.md](https://github.com/zqagent/zqagent/blob/main/docs/architecture.md) |
+| 线协议（帧 / 消息 / 签名） | [docs/wire-protocol.md](https://github.com/zqagent/zqagent/blob/main/docs/wire-protocol.md) |
+| 上下文压缩 | [docs/context-compaction.md](https://github.com/zqagent/zqagent/blob/main/docs/context-compaction.md) |
+| 节点服务 REST API | [docs/server-api.md](https://github.com/zqagent/zqagent/blob/main/docs/server-api.md) |
+| 共享库 | [docs/shared.md](https://github.com/zqagent/zqagent/blob/main/docs/shared.md) |
+| LLM 连接排查 | [docs/llm-connection-troubleshooting.md](https://github.com/zqagent/zqagent/blob/main/docs/llm-connection-troubleshooting.md) |
+| QQ 机器人 | [docs/qq-bot.md](https://github.com/zqagent/zqagent/blob/main/docs/qq-bot.md) |
 
-- 完整 curl 教程（审批/提问/超时回收/多租户隔离）：[docs/server-api.md](docs/server-api.md)
-- 一键测试：`bash scripts/test-server.sh`（无需 Key 的烟雾测试，18 项）；模型配置
-  （`OPENAI_API_KEY` 等）未显式设置时自动从项目 `.env` 读取，此时为完整链路测试
-  （真实对话 + 提问挂起 + 超时回收 + resume 恢复，24 项）
+上述文档同时提供英文版（`docs/en/`）。使用者指南见 <https://agent.cd-zq.com/>。
 
-## 桌面应用（macOS / Windows）
+## 开发
 
-`desktop/` 把 Server 打包成桌面应用：Tauri 2 外壳 + 内嵌 Node sidecar，前端复用
-`test_web/` 的 React 页面（本地引擎自动连接、托盘常驻、自动更新）。
+本包是 monorepo 的一部分（与 `@zqagent/shared` 同源构建）：
 
 ```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 install
+pnpm --filter @zqagent/core typecheck
+pnpm --filter @zqagent/core test
+pnpm --filter @zqagent/core build
+pnpm --filter @zqagent/core dev      # 以源码方式启动 CLI
 ```
 
-详见 [desktop/README.md](desktop/README.md)。
+贡献前请阅读
+[CONTRIBUTING.md](https://github.com/zqagent/zqagent/blob/main/CONTRIBUTING.md)。
+涉及权限、审批、命令执行的改动会被重点审查。
 
-## 测试 Web 界面（test_web/）
+## 许可
 
-`test_web/` 是 Server 的 React 测试页：多租户 profile 管理、会话/审批/提问全链路。
-桌面壳会注入 `window.__ZQ_HTTP__/__ZQ_API_KEY__` 并自动注册「本地引擎」profile，
-浏览器模式（`npm run dev`）行为不变。
+[Apache-2.0](https://github.com/zqagent/zqagent/blob/main/LICENSE)。
+`@zqagent` 与 ZQAgent 名称为本项目商标，二次分发或托管服务请勿暗示官方背书。