docs: 更新文档 - REFACTOR、API Key、Agent Config、Roadmap
- REFACTOR.md 记录本次重构要点 - api-key-integration.md 更新接口说明 - agents-config.md 同步新模型变更 - roadmap.md 添加本次重构条目
This commit is contained in:
Wenjie Zhang
parent
fbb5b458ea
commit
3525e357d3
@ -35,3 +35,5 @@
|
||||
- [x] 知识库的权限调整，修改为三个等级，全局共享、部门共享（选择多个部门，默认是自己部门且必须包含自己部门）、指定人可访问（选择多个用户，默认是仅自己，可以添加其他人）。UI 上也需要调整，三个卡片不再是等宽，而是选中的会宽一点，并展示描述以及选择按钮，未选中的则是默认宽度，仅显示标题。对于选中的卡片除了展示描述、按钮之外，还包括“X 个部门可访问”、“X 个用户可访问”的信息展示。全局的就看是所有用户可访问。所以等级的字段配置也要重新设计，不需要考虑兼容，所有知识库都会重新构建。
|
||||
- [x] databaseinfo 的重构，在左侧展示那个 tab 标签吧，将文件管理（filetable）以及右侧的那些图谱、检索、检索配置、评估之类的，都列为不同的 tab，进入之后默认激活的是 filetable。这样页面布局就好的多。作恶侧边栏除了这些 tab 之外，顶部是和 Skill Detail 那里的 header 一样，
|
||||
- [x] 当前的评估基准是最重要的是评估数据集和评估结果都是放在一个文件里面的，这个是绝对不可以的，应该是放在数据库里面，比如评估数据集是一个表，每一个评估的题目是一个表，评估的结果是一个表，每一个评估的 item 也是一个表，但是数据表太多要注意命名规范。现在第一步就是完成原本的评估的功能的重新梳理
|
||||
- [ ] 考虑如何将知识库更好的挂载到沙盒，是不是可以使用一个别的后端，但是使用别的后端是否还能读取到数据？应该不能
|
||||
- [ ] 智能体体系改进。
|
||||
|
||||
@ -14,7 +14,7 @@ API Key 是一种用于身份验证的密钥字符串，外部系统可以通过
|
||||
|
||||
## 接口调用方式
|
||||
|
||||
外部系统通过 HTTP 请求调用 Yuxi 的对话接口，需要在请求头中携带 API Key。流式接口地址为 `POST /api/chat/agent`，非流式接口地址为 `POST /api/chat/agent/sync`（不支持 HITL）。请求头需要包含 `Authorization` 字段，值格式为 `Bearer <api_key>`，其中 `<api_key>` 是创建 API Key 时获取的完整密钥。请求体为 JSON 格式，必填字段为 `query` 和 `agent_config_id`，可选字段为 `thread_id`、`image_content` 和 `meta`。
|
||||
外部系统通过 HTTP 请求调用 Yuxi 的对话接口，需要在请求头中携带 API Key。流式接口地址为 `POST /api/agent/chat`，非流式接口地址为 `POST /api/agent/chat/sync`（不支持 HITL）。请求头需要包含 `Authorization` 字段，值格式为 `Bearer <api_key>`，其中 `<api_key>` 是创建 API Key 时获取的完整密钥。请求体为 JSON 格式，必填字段为 `query` 和 `agent_id`，可选字段为 `thread_id`、`image_content` 和 `meta`。
|
||||
|
||||
以下是一个典型的 Python 调用示例：
|
||||
|
||||
@ -22,14 +22,14 @@ API Key 是一种用于身份验证的密钥字符串，外部系统可以通过
|
||||
import requests
|
||||
import json
|
||||
|
||||
url = "http://your-yuxi-server/api/chat/agent"
|
||||
url = "http://your-yuxi-server/api/agent/chat"
|
||||
headers = {
|
||||
"Authorization": "Bearer yxkey_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
|
||||
"Content-Type": "application/json"
|
||||
}
|
||||
payload = {
|
||||
"query": "你好，请介绍一下你自己",
|
||||
"agent_config_id": 1,
|
||||
"agent_id": "default-chatbot",
|
||||
"meta": {}
|
||||
}
|
||||
|
||||
|
||||
@ -15,7 +15,7 @@ Yuxi 的智能体系统基于 LangGraph 构建。对开发者来说，最重要
|
||||
- **`BaseAgent`**：统一的 Agent 抽象，定义 `get_graph()`、`context_schema`、`capabilities`
|
||||
- **`BaseContext`**：配置 Schema，也是前端配置项的来源
|
||||
- **Graph / Middleware**：LangGraph 图与中间件链，决定运行时行为
|
||||
- **AgentConfig**：数据库中的配置实例，前端侧边栏编辑的就是它
|
||||
- **Agent**：数据库中的一级智能体实例，保存展示信息、后端 `backend_id`、共享权限和 `config_json.context`
|
||||
|
||||
仓库中已经内置了可直接参考的智能体：
|
||||
|
||||
@ -95,22 +95,22 @@ class MyAgent(BaseAgent):
|
||||
|
||||
1. `BaseAgent.get_info()` 暴露 `configurable_items`
|
||||
2. 前端读取 Agent 详情
|
||||
3. `AgentConfigSidebar` 按 `kind` 渲染不同控件
|
||||
3. `AgentRuntimeConfigForm` 按 `kind` 渲染不同控件
|
||||
|
||||
也就是说，`AgentConfigSidebar` 不是手写每个字段，而是直接消费 `context_schema` 生成的配置描述。
|
||||
也就是说，`AgentRuntimeConfigForm` 不是手写每个字段，而是直接消费 `context_schema` 生成的配置描述。
|
||||
|
||||
这也是为什么：
|
||||
|
||||
- 新增一个 Context 字段，往往会直接影响侧边栏
|
||||
- 字段的 `metadata` 信息会直接影响展示方式
|
||||
|
||||
### 3.3 `AgentConfigSidebar` 与 AgentConfig 的联动关系
|
||||
### 3.3 配置表单与 Agent 的联动关系
|
||||
|
||||
这部分是最关键的。
|
||||
|
||||
在前端：
|
||||
|
||||
- `AgentConfigSidebar.vue` 负责渲染配置表单
|
||||
- `AgentRuntimeConfigForm.vue` 负责渲染配置表单
|
||||
- `agentStore` 加载配置时，读取 `config_json.context`
|
||||
- 如果某些字段未配置，会用 `configurable_items` 中的默认值补全
|
||||
- 保存时，前端将当前表单写回 `config_json: { context: agentConfig }`
|
||||
@ -121,7 +121,7 @@ class MyAgent(BaseAgent):
|
||||
context_schema
|
||||
-> get_configurable_items()
|
||||
-> Agent detail API 返回 configurable_items
|
||||
-> AgentConfigSidebar 渲染表单
|
||||
-> AgentRuntimeConfigForm 渲染表单
|
||||
-> 用户编辑后保存到 config_json.context
|
||||
```
|
||||
|
||||
@ -172,23 +172,23 @@ Context 的价值不只在“配置页面”。它贯穿了从配置加载到实
|
||||
|
||||
### 4.1 配置加载阶段
|
||||
|
||||
在聊天请求进入后端时，服务会先解析 `agent_config_id`，再加载对应配置。
|
||||
在聊天请求进入后端时，服务会先解析请求中的 `agent_id` 或线程已绑定的 Agent，再加载对应配置。
|
||||
|
||||
当前主流程在 `chat_service.py` 中：
|
||||
|
||||
1. 通过 `agent_config_id` 查找配置
|
||||
2. 读取该配置绑定的 `agent_id`
|
||||
3. 取出 `config_json.context`
|
||||
4. 与 `user_id`、`thread_id` 合并成运行时输入
|
||||
1. 新线程通过 `agent_id` 查找用户可访问的 Agent
|
||||
2. 已有线程通过 `thread_id` 读取 `Conversation.agent_id`，并拒绝运行中切换 Agent
|
||||
3. 取出 Agent 的 `config_json.context`
|
||||
4. 与 `uid`、`thread_id` 合并成运行时输入
|
||||
|
||||
也就是说，运行期 Context 的基础来源并不是前端临时状态，而是数据库中保存的 AgentConfig。
|
||||
也就是说，运行期 Context 的基础来源并不是前端临时状态，而是数据库中保存的 Agent。
|
||||
|
||||
此外，用户工作区会默认创建 `agents/AGENTS.md`。当 Agent 开始执行时，后端会读取当前用户工作区下的这个文件，并将其内容追加到 `system_prompt`，用于补充该用户对 Agent 的长期指令或工作区约定。该文件属于用户级共享工作区，内容会随 `user_id` 和当前 `thread_id` 映射到运行时工作区路径；文件不存在、为空或不可读时不会影响 Agent 启动，单次注入内容最多读取 64 KiB，超出部分会截断并追加提示。
|
||||
|
||||
合并后的提示词结构可以理解为：
|
||||
|
||||
```text
|
||||
AgentConfig.config_json.context.system_prompt
|
||||
Agent.config_json.context.system_prompt
|
||||
+ 用户工作区 agents/AGENTS.md 内容
|
||||
+ 运行期中间件继续追加的系统提示段
|
||||
```
|
||||
@ -263,7 +263,7 @@ config_json.context + runtime ids -> context_schema instance
|
||||
|
||||
### 4.6 恢复运行阶段
|
||||
|
||||
在 `resume` 流程中，系统同样会重新加载 AgentConfig，并重新构造 Context，再继续执行 Graph。
|
||||
在 `resume` 流程中，系统同样会通过线程绑定的 Agent 重新构造 Context，再继续执行 Graph。
|
||||
|
||||
也就是说，无论是：
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user