docs: add CLI system docs

2026-07-19 04:37:28 +08:00 · 2026-03-29 17:57:12 +08:00
parent e06925ab85
commit 3cb5a0fbd6
62 changed files with 2995 additions and 750 deletions
--- a/docs/guide/manual-install.mdx
+++ b/docs/guide/manual-install.mdx
@@ -32,7 +32,39 @@ pip3 install -r requirements-optional.txt

 > 国内网络可使用镜像源加速：`pip3 install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple`

-### 3. 配置
+### 3. 安装 Cow CLI
+
+安装命令行工具，用于管理服务和技能：
+
+```bash
+pip3 install -e .
+```
+
+安装后即可使用 `cow` 命令：
+
+```bash
+cow help
+```
+
+<Note>
+  此步骤为推荐操作。安装后可以使用 `cow start`、`cow stop`、`cow update` 等命令管理服务，也可以使用 `cow skill` 管理技能。如果不安装 CLI，可以使用 `./run.sh` 或 `python3 app.py` 运行。
+</Note>
+
+### 3.1 安装浏览器工具（可选）
+
+如需使用浏览器工具（控制浏览器访问网页、填写表单等），运行：
+
+```bash
+cow install-browser
+```
+
+该命令会自动安装 Playwright 和 Chromium 浏览器。详细说明参考 [浏览器工具文档](/tools/browser)。
+
+<Note>
+  浏览器工具依赖较重（~300MB），如不需要可跳过，不影响其他功能正常使用。
+</Note>
+
+### 4. 配置

 复制配置文件模板并编辑：

@@ -42,9 +74,15 @@ cp config-template.json config.json

 在 `config.json` 中填写模型 API Key 和通道类型等配置，详细说明参考各 [模型文档](/models/minimax)。

-### 4. 运行
+### 5. 运行

-**本地运行：**
+**使用 Cow CLI 运行（推荐）：**
+
+```bash
+cow start
+```
+
+**或者本地前台运行：**

 ```bash
 python3 app.py
@@ -52,7 +90,7 @@ python3 app.py

 运行后默认启动 Web 控制台，访问 `http://localhost:9899` 开始对话和管理Agent。

-**服务器后台运行：**
+**服务器后台运行（不使用 CLI 时）：**

 ```bash
 nohup python3 app.py & tail -f nohup.out
@@ -96,28 +134,44 @@ sudo docker logs -f chatgpt-on-wechat

 ## 核心配置项

-```json
-{
-  "channel_type": "web",
-  "model": "MiniMax-M2.5",
-  "agent": true,
-  "agent_workspace": "~/cow",
-  "agent_max_context_tokens": 40000,
-  "agent_max_context_turns": 30,
-  "agent_max_steps": 15
-}
-```
+<Tabs>
+  <Tab title="源码部署（config.json）">
+    ```json
+    {
+      "channel_type": "web",
+      "model": "MiniMax-M2.7",
+      "agent": true,
+      "agent_workspace": "~/cow",
+      "agent_max_context_tokens": 40000,
+      "agent_max_context_turns": 30,
+      "agent_max_steps": 15
+    }
+    ```
+  </Tab>
+  <Tab title="Docker 部署（docker-compose.yml）">
+    ```yaml
+    environment:
+      CHANNEL_TYPE: 'web'
+      MODEL: 'MiniMax-M2.7'
+      MINIMAX_API_KEY: 'your-api-key'
+      AGENT: 'True'
+      AGENT_MAX_CONTEXT_TOKENS: 40000
+      AGENT_MAX_CONTEXT_TURNS: 30
+      AGENT_MAX_STEPS: 15
+    ```
+  </Tab>
+</Tabs>

-| 参数 | 说明 | 默认值 |
-| --- | --- | --- |
-| `channel_type` | 接入渠道类型 | `web` |
-| `model` | 模型名称 | `MiniMax-M2.5` |
-| `agent` | 是否启用 Agent 模式 | `true` |
-| `agent_workspace` | Agent 工作空间路径 | `~/cow` |
-| `agent_max_context_tokens` | 最大上下文 tokens | `40000` |
-| `agent_max_context_turns` | 最大上下文记忆轮次 | `30` |
-| `agent_max_steps` | 单次任务最大决策步数 | `15` |
+| 参数 | 环境变量 | 说明 | 默认值 |
+| --- | --- | --- | --- |
+| `channel_type` | `CHANNEL_TYPE` | 接入渠道类型 | `web` |
+| `model` | `MODEL` | 模型名称 | `MiniMax-M2.5` |
+| `agent` | `AGENT` | 是否启用 Agent 模式 | `true` |
+| `agent_workspace` | - | Agent 工作空间路径 | `~/cow` |
+| `agent_max_context_tokens` | `AGENT_MAX_CONTEXT_TOKENS` | 最大上下文 tokens | `40000` |
+| `agent_max_context_turns` | `AGENT_MAX_CONTEXT_TURNS` | 最大上下文记忆轮次 | `30` |
+| `agent_max_steps` | `AGENT_MAX_STEPS` | 单次任务最大决策步数 | `15` |

 <Tip>
-  全部配置项可在项目 [`config.py`](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/config.py) 文件中查看。
+  全部配置项可在项目 [`config.py`](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/config.py) 文件中查看。Docker 部署时，配置项名称需转为大写环境变量格式。
 </Tip>
--- a/docs/guide/quick-start.mdx
+++ b/docs/guide/quick-start.mdx
@@ -18,7 +18,7 @@ bash <(curl -fsSL https://cdn.link-ai.tech/code/cow/run.sh)
 1. 检查 Python 环境（需要 Python 3.7+）
 2. 安装必要工具（git、curl 等）
 3. 克隆项目代码到 `~/chatgpt-on-wechat`
-4. 安装 Python 依赖
+4. 安装 Python 依赖和 Cow CLI
 5. 引导配置 AI 模型和通信渠道
 6. 启动服务

@@ -26,14 +26,20 @@ bash <(curl -fsSL https://cdn.link-ai.tech/code/cow/run.sh)

 ## 管理命令

-安装完成后，可使用以下命令管理服务：
+安装完成后，使用 `cow` CLI 管理服务：

 | 命令 | 说明 |
 | --- | --- |
-| `./run.sh start` | 启动服务 |
-| `./run.sh stop` | 停止服务 |
-| `./run.sh restart` | 重启服务 |
-| `./run.sh status` | 查看运行状态 |
-| `./run.sh logs` | 查看实时日志 |
-| `./run.sh config` | 重新配置 |
-| `./run.sh update` | 更新项目代码 |
+| `cow start` | 启动服务 |
+| `cow stop` | 停止服务 |
+| `cow restart` | 重启服务 |
+| `cow status` | 查看运行状态 |
+| `cow logs` | 查看实时日志 |
+| `cow update` | 更新代码并重启 |
+| `cow install-browser` | 安装浏览器工具依赖 |
+
+更多命令和用法参考 [命令文档](/commands/index)。
+
+<Note>
+  如果 `cow` 命令不可用，也可以使用 `./run.sh <命令>` 作为替代（如 `./run.sh start`、`./run.sh stop`），二者功能等效。
+</Note>
--- a/docs/guide/upgrade.mdx
+++ b/docs/guide/upgrade.mdx
@@ -3,20 +3,25 @@ title: 更新升级
 description: CowAgent 的升级方式说明
 ---

-## 脚本升级（推荐）
+## 命令升级（推荐）

-如果使用 `run.sh` 管理服务，在项目根目录执行以下命令即可一键升级：
+使用 `cow update` 一键完成代码更新和服务重启：

 ```bash
-./run.sh update
+cow update
 ```

 该命令会自动完成以下流程：

-1. 停止当前运行的服务
-2. 拉取最新代码
-3. 重新检查依赖
-4. 启动服务
+1. 拉取最新代码（`git pull`）
+2. 停止当前服务
+3. 更新 Python 依赖
+4. 重新安装 CLI
+5. 启动服务
+
+<Note>
+  如果未安装 Cow CLI，也可以使用 `./run.sh update` 完成相同操作。
+</Note>

 ## 手动升级

@@ -25,15 +30,19 @@ description: CowAgent 的升级方式说明
 ```bash
 git pull
 pip3 install -r requirements.txt
+pip3 install -e .
 ```

 更新完成后重启服务：

 ```bash
-# 如果使用 run.sh 管理
+# 使用 Cow CLI
+cow restart
+
+# 或使用 run.sh
 ./run.sh restart

-# 如果使用 nohup 直接运行
+# 或使用 nohup 直接运行
 kill $(ps -ef | grep app.py | grep -v grep | awk '{print $2}')
 nohup python3 app.py & tail -f nohup.out
 ```