Skip to content

Commit 35b482d

Browse files
InfernalAzazelInfernalAzazel
committed
Update README files and enhance asset references in OpenFox
- Updated asset references in both English and Chinese README files to point to the new logo URL. - Expanded the configuration section in the README to provide detailed explanations of the `~/.openfox/config.json` structure and its fields. - Added a comprehensive example of a valid JSON configuration to guide users in setting up their configuration file. - Included additional details about the Web console features and the MCP server configuration. - Introduced new image assets to enhance the visual representation of the project.
1 parent e075485 commit 35b482d

17 files changed

Lines changed: 557 additions & 25 deletions

‎README-zh_CN.md‎

Lines changed: 277 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
</p>
44

55
<p align="center">
6-
<img src="./assets/openfox-logo.png" alt="OpenFox logo" width="64" height="64" />
6+
<img src="https://raw.githubusercontent.com/InfernalAzazel/openfox/main/assets/openfox-logo.png" alt="OpenFox logo" width="64" height="64" />
77
</p>
88

99
<p align="center">
@@ -25,17 +25,255 @@
2525

2626
| 路径 | 说明 |
2727
|------|------|
28-
| `~/.openfox/config.json` | LLM、飞书、`cors_origin_list`、MCP 等配置 |
28+
| `~/.openfox/config.json` | 主配置文件（启动时校验）；详见下文 **配置说明** |
2929
| `~/.openfox/storage.db` | 使用的 **SQLite** 会话与调度存储 |
3030
| `~/.openfox/skills` | 本地技能根目录（代码中 **`SKILLS_PATH`**，见 `openfox/utils/const.py`）；首次启动若不存在，会从包内 `openfox/skills` 复制（见 `openfox/core/skills.py`） |
3131

3232
---
3333

34+
## 配置说明（`~/.openfox/config.json`）
35+
36+
OpenFox 从 **`~/.openfox/config.json`** 读取 JSON 配置，字段对应 `openfox/schemas/config.py` 中的 **`Config`** 模型（非法值会在启动时报错）。**请勿把真实 API Key、飞书密钥等提交到仓库**，请按私密文件保管。
37+
38+
| 配置项 | 说明 |
39+
|--------|------|
40+
| `agent_id` | Agent 标识，在 AgentOS / Web 中展示（默认 `OpenFox`）。 |
41+
| `docs_enabled` | 是否暴露 FastAPI **OpenAPI** 文档。 |
42+
| `os_security_key` | Web 控制台与受保护 HTTP API 的鉴权密钥（Bearer）。 |
43+
| `cors_origin_list` | 浏览器跨域允许的来源列表（含内置 `/web` 默认端口）。若改服务端口，需把实际 `http://127.0.0.1:<端口>` 等加入此列表。 |
44+
| `time_zone` | 默认时区（如 `Asia/Shanghai`）。 |
45+
| `search_knowledge` | 为 `true` 时启用 **RAG**（Chroma 数据目录为 `~/.openfox/chromadb`，不在本文件中配置路径）。 |
46+
| `llm` | 对话模型：`model_name`、`api_base`、`api_key`（LiteLLM 风格模型 id）。 |
47+
| `knowledge` | `search_knowledge` 为 true 时生效：`vector_db`（集合名、`search_type`、**embedder** / **reranker** 等）、`max_results`、`isolate_vector_search`。 |
48+
| `channels` | 通道集成，如 `channels.feishu`（`app_id`、`app_secret`、`encrypt_key`、`verification_token`）。 |
49+
| `mcps` | MCP 服务列表（`command`/`args`/`env` 或 `url`/`headers` 等）。 |
50+
| `tools` | 各工具包开关与参数（`mcp`、`scheduler`、`shell`、`websearch`、`arxiv` 等）；常见字段含 `activate`、`include_tools`、`exclude_tools` 及各自专用字段。 |
51+
52+
**磁盘上的合法 JSON**：`~/.openfox/config.json` 必须是**标准 JSON**（双引号、不能有 `//` 注释）。下面 **`jsonc`** 代码块仅用于**文档说明**，保存到文件前需删掉注释，或在 Web **配置** 编辑器中粘贴去掉注释后的对象。
53+
54+
### 完整结构示例（合法 JSON；与磁盘上的 `config.json` 布局一致）
55+
56+
下列 JSON 的**键顺序、嵌套与非敏感取值**与一份完整配置文件对齐；所有密钥与令牌已替换为**占位符**，请勿把真实凭据提交到仓库。
57+
58+
```jsonc
59+
{
60+
// Agent 基础信息
61+
"agent_id": "OpenFox",
62+
"docs_enabled": true,
63+
"os_security_key": "<os_security_key>",
64+
// Web / API 访问来源（若改端口请同步调整）
65+
"cors_origin_list": [
66+
"http://127.0.0.1:7777",
67+
"http://localhost:7777"
68+
],
69+
"time_zone": "Asia/Shanghai",
70+
// 是否开启知识库检索（RAG）
71+
"search_knowledge": true,
72+
// 主模型配置（LiteLLM）
73+
"llm": {
74+
"model_name": "deepseek/deepseek-chat",
75+
"api_base": "https://api.deepseek.com",
76+
"api_key": "<llm_api_key>"
77+
},
78+
// 通道配置（示例为飞书）
79+
"channels": {
80+
"feishu": {
81+
"app_id": "<feishu_app_id>",
82+
"app_secret": "<feishu_app_secret>",
83+
"encrypt_key": "<feishu_encrypt_key>",
84+
"verification_token": "<feishu_verification_token>"
85+
}
86+
},
87+
// MCP 服务列表：每项要么 stdio（command+args），要么 HTTP（url+headers）
88+
"mcps": [
89+
{
90+
// 展示名称
91+
"name": "weibo",
92+
// stdio：通过 uvx --from 运行 Git 仓库中的 MCP 服务
93+
"command": "uvx",
94+
"args": [
95+
"--from",
96+
"git+https://github.com/InfernalAzazel/mcp-server-weibo.git",
97+
"mcp-server-weibo"
98+
],
99+
"env": {},
100+
// stdio 模式下 url 留空
101+
"url": "",
102+
"headers": {},
103+
"tool_timeout": 60
104+
},
105+
{
106+
"name": "chrome-devtools",
107+
// stdio：通过 npx 运行 npm 包
108+
"command": "npx",
109+
"args": ["chrome-devtools-mcp@latest"],
110+
"env": {},
111+
"url": "",
112+
"headers": {},
113+
"tool_timeout": 60
114+
}
115+
],
116+
// 知识库检索配置（Chroma + embedder + reranker）
117+
"knowledge": {
118+
"vector_db": {
119+
"collection": "docs",
120+
"name": "OpenFox Knowledge",
121+
"description": "OpenFox Knowledge",
122+
"id": null,
123+
"distance": "cosine",
124+
"persistent_client": true,
125+
"search_type": "hybrid",
126+
"hybrid_rrf_k": 60,
127+
"batch_size": null,
128+
"reranker_enabled": true,
129+
"embedder": {
130+
"id": "openai/text-embedding-v4",
131+
"api_key": "<embedder_api_key>",
132+
"api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1",
133+
"request_params": {
134+
"encoding_format": "float"
135+
},
136+
"enable_batch": false,
137+
"batch_size": 20
138+
},
139+
"reranker": {
140+
"model": "dashscope/qwen3-rerank",
141+
"api_key": "<reranker_api_key>",
142+
"api_base": "https://dashscope.aliyuncs.com/compatible-api/v1/reranks",
143+
"top_n": null,
144+
"request_params": null
145+
}
146+
},
147+
"max_results": 10,
148+
"isolate_vector_search": false
149+
},
150+
// 工具包配置（按模块开关）
151+
"tools": {
152+
"mcp": {
153+
"include_tools": null,
154+
"exclude_tools": null,
155+
"activate": true
156+
},
157+
"scheduler": {
158+
"include_tools": null,
159+
"exclude_tools": null,
160+
"activate": true
161+
},
162+
"shell": {
163+
"include_tools": null,
164+
"exclude_tools": null,
165+
"activate": true,
166+
"base_dir": null,
167+
"enable_run_shell_command": true,
168+
"all": false
169+
},
170+
"websearch": {
171+
"include_tools": null,
172+
"exclude_tools": null,
173+
"activate": true,
174+
"enable_search": true,
175+
"enable_news": true,
176+
"backend": "auto",
177+
"modifier": null,
178+
"fixed_max_results": null,
179+
"proxy": null,
180+
"timeout": 10,
181+
"verify_ssl": true,
182+
"timelimit": null,
183+
"region": null
184+
},
185+
"arxiv": {
186+
"include_tools": null,
187+
"exclude_tools": null,
188+
"activate": true,
189+
"enable_search_arxiv": true,
190+
"enable_read_arxiv_papers": true,
191+
"download_dir": null
192+
},
193+
"hackernews": {
194+
"include_tools": null,
195+
"exclude_tools": null,
196+
"activate": true,
197+
"enable_get_top_stories": true,
198+
"enable_get_user_details": true,
199+
"all": false
200+
},
201+
"pubmed": {
202+
"include_tools": null,
203+
"exclude_tools": null,
204+
"activate": true,
205+
"email": "your_email@example.com",
206+
"max_results": null,
207+
"enable_search_pubmed": true,
208+
"all": false
209+
},
210+
"wikipedia": {
211+
"include_tools": null,
212+
"exclude_tools": null,
213+
"activate": true
214+
},
215+
"crawl4ai": {
216+
"include_tools": null,
217+
"exclude_tools": null,
218+
"activate": true,
219+
"max_length": 1000,
220+
"timeout": 60,
221+
"use_pruning": false,
222+
"pruning_threshold": 0.48,
223+
"bm25_threshold": 1.0,
224+
"headless": true,
225+
"wait_until": "domcontentloaded",
226+
"enable_crawl": true,
227+
"all": false
228+
},
229+
"calculator": {
230+
"include_tools": null,
231+
"exclude_tools": null,
232+
"activate": true
233+
},
234+
"docker": {
235+
"include_tools": null,
236+
"exclude_tools": null,
237+
"activate": false
238+
},
239+
"youtube": {
240+
"include_tools": null,
241+
"exclude_tools": null,
242+
"activate": true,
243+
"get_video_captions": true,
244+
"get_video_data": true,
245+
"languages": null,
246+
"enable_get_video_captions": true,
247+
"enable_get_video_data": true,
248+
"enable_get_video_timestamps": true,
249+
"all": false
250+
},
251+
"webbrowser": {
252+
"include_tools": null,
253+
"exclude_tools": null,
254+
"activate": true,
255+
"enable_open_page": true,
256+
"all": false
257+
}
258+
}
259+
}
260+
```
261+
262+
使用上述 MCP 条目时，运行 OpenFox 的机器上需已安装 **`uv` / `uvx`** 与 **Node.js（含 `npx`）**（按你实际启用的服务为准）。
263+
264+
可在 Web 控制台的 **配置** 页或通过已鉴权的 **expand/config** HTTP API 修改；若直接改磁盘上的 JSON，修改后需**重启** `python -m openfox` 才会载入。
265+
266+
---
267+
34268
## 功能一览
35269

36270
| 能力 | 说明 |
37271
|------|------|
38-
| **Web 控制台** | 聊天、会话列表、用量指标、技能上传/管理、Cron 调度、JSON 配置编辑（需登录，使用配置里的 `os_security_key`） |
272+
| **Web 控制台** | 聊天、会话列表、用量指标、**知识库**（`/knowledge`）、**记忆**（`/memory`）、**评估**（`/evals`）、**运行追踪**（`/traces`）、技能上传/管理、Cron 调度、JSON 配置编辑（需登录，使用配置里的 `os_security_key`） |
273+
| **知识库** | 开启 `search_knowledge` 后启用 **RAG**：**Chroma** 向量库存于 `~/.openfox/chromadb`，嵌入与重排序通过 **LiteLLM**；在 Web 控制台 **`/knowledge`** 管理文档与内容。 |
274+
| **记忆** | **Agent 记忆**随会话持久化（如运行结束更新记忆）；在 Web 控制台 **`/memory`** 查看与管理，数据与 `~/.openfox/storage.db` 中的存储一致。 |
275+
| **评估体系** | 内置 **评估** 流程：从 **性能**、**可靠性**、**准确性** 等维度衡量 Agent 或团队表现（Web 控制台 `/evals`）。 |
276+
| **运行追踪** | **追踪 Agent 运行全过程**：查看链路、span、会话等可观测数据，便于排查与优化（Web 控制台 `/traces`）。 |
39277
| **飞书** | 事件与消息接入，单聊/群聊（可 @ 机器人） |
40278
| **定时任务** | 内置调度器；在配置中通过 `tools.scheduler`（**SchedulerConfig**）开启。对 Agent 暴露 **SchedulerTools**，可用自然语言创建周期任务（Cron 表达式 → POST 本 Agent 运行端点） |
41279
| **工具** | 见下文「内置 Agent 工具」；另可通过 `config.mcps` 挂载 **MCP**，Web 控制台中的配置编辑对应 **ConfigTools**（非 Agent 对话工具） |
@@ -125,27 +363,54 @@ ollama/llama3.1
125363

126364
### 飞书中使用效果
127365

128-
![feishu](./assets/feishu.gif)
366+
![feishu](https://raw.githubusercontent.com/InfernalAzazel/openfox/main/assets/feishu.gif)
129367

130368
### Web UI
131369

132370
<p align="center"><strong>聊天</strong></p>
133-
<p align="center"><img src="./assets/image1.png" alt="OpenFox Web — 聊天" width="900" /></p>
371+
<p align="center"><img src="https://raw.githubusercontent.com/InfernalAzazel/openfox/main/assets/image1.png" alt="OpenFox Web — 聊天" width="900" /></p>
134372

135373
<p align="center"><strong>会话</strong></p>
136-
<p align="center"><img src="./assets/image2.png" alt="OpenFox Web — 会话" width="900" /></p>
374+
<p align="center"><img src="https://raw.githubusercontent.com/InfernalAzazel/openfox/main/assets/image2.png" alt="OpenFox Web — 会话" width="900" /></p>
375+
376+
<p align="center"><strong>记忆</strong></p>
377+
<p align="center"><img src="https://raw.githubusercontent.com/InfernalAzazel/openfox/main/assets/image3.png" alt="OpenFox Web — 记忆" width="900" /></p>
378+
379+
<p align="center"><strong>知识库（添加内容）</strong></p>
380+
<p align="center"><img src="https://raw.githubusercontent.com/InfernalAzazel/openfox/main/assets/image4.png" alt="OpenFox Web — 知识库添加内容" width="900" /></p>
381+
382+
<p align="center"><strong>知识库（列表）</strong></p>
383+
<p align="center"><img src="https://raw.githubusercontent.com/InfernalAzazel/openfox/main/assets/image5.png" alt="OpenFox Web — 知识库列表" width="900" /></p>
137384

138385
<p align="center"><strong>使用情况</strong></p>
139-
<p align="center"><img src="./assets/image3.png" alt="OpenFox Web — 使用情况" width="900" /></p>
386+
<p align="center"><img src="https://raw.githubusercontent.com/InfernalAzazel/openfox/main/assets/image6.png" alt="OpenFox Web — 使用情况" width="900" /></p>
140387

141388
<p align="center"><strong>技能</strong></p>
142-
<p align="center"><img src="./assets/image4.png" alt="OpenFox Web — 技能" width="900" /></p>
389+
<p align="center"><img src="https://raw.githubusercontent.com/InfernalAzazel/openfox/main/assets/image7.png" alt="OpenFox Web — 技能" width="900" /></p>
390+
391+
<p align="center"><strong>追踪（运行列表）</strong></p>
392+
<p align="center"><img src="https://raw.githubusercontent.com/InfernalAzazel/openfox/main/assets/image8.png" alt="OpenFox Web — 追踪运行列表" width="900" /></p>
393+
394+
<p align="center"><strong>追踪详情</strong></p>
395+
<p align="center"><img src="https://raw.githubusercontent.com/InfernalAzazel/openfox/main/assets/image9.png" alt="OpenFox Web — 追踪详情" width="900" /></p>
396+
397+
<p align="center"><strong>评估（列表）</strong></p>
398+
<p align="center"><img src="https://raw.githubusercontent.com/InfernalAzazel/openfox/main/assets/image10.png" alt="OpenFox Web — 评估列表" width="900" /></p>
399+
400+
<p align="center"><strong>评估详情</strong></p>
401+
<p align="center"><img src="https://raw.githubusercontent.com/InfernalAzazel/openfox/main/assets/image11.png" alt="OpenFox Web — 评估详情" width="900" /></p>
402+
403+
<p align="center"><strong>调度器（列表）</strong></p>
404+
<p align="center"><img src="https://raw.githubusercontent.com/InfernalAzazel/openfox/main/assets/image12.png" alt="OpenFox Web — 调度器列表" width="900" /></p>
405+
406+
<p align="center"><strong>调度器（详情）</strong></p>
407+
<p align="center"><img src="https://raw.githubusercontent.com/InfernalAzazel/openfox/main/assets/image13.png" alt="OpenFox Web — 调度器详情" width="900" /></p>
143408

144-
<p align="center"><strong>定时任务</strong></p>
145-
<p align="center"><img src="./assets/image5.png" alt="OpenFox Web — 定时任务" width="900" /></p>
409+
<p align="center"><strong>调度器（运行历史）</strong></p>
410+
<p align="center"><img src="https://raw.githubusercontent.com/InfernalAzazel/openfox/main/assets/image14.png" alt="OpenFox Web — 调度器运行历史" width="900" /></p>
146411

147412
<p align="center"><strong>配置</strong></p>
148-
<p align="center"><img src="./assets/image6.png" alt="OpenFox Web — 配置" width="900" /></p>
413+
<p align="center"><img src="https://raw.githubusercontent.com/InfernalAzazel/openfox/main/assets/image15.png" alt="OpenFox Web — 配置" width="900" /></p>
149414

150415
---
151416

@@ -175,5 +440,5 @@ ollama/llama3.1
175440
加群请注明来意，留言 **openfox**：
176441

177442
<p align="center">
178-
<img src="./assets/kylin.png" width="220" alt="交流群二维码" />
443+
<img src="https://raw.githubusercontent.com/InfernalAzazel/openfox/main/assets/kylin.png" width="220" alt="交流群二维码" />
179444
</p>

0 commit comments

Comments
 (0)