重建下文档
This commit is contained in:
+30
-41
@@ -1,60 +1,49 @@
|
||||
# Agent 任务台(app)
|
||||
# agent-core
|
||||
|
||||
按仓库根目录 `README.md` 设计方案实现的自用通用 Agent 系统。
|
||||
`agent` 仓库的 core 服务:Express + SQLite + 静态 H5 前端。
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
app/
|
||||
├── server/
|
||||
│ ├── server.js # 入口:装配配置/DB/总线/路由/静态资源
|
||||
│ ├── config.js # config.yml 加载与校验
|
||||
│ ├── db.js # SQLite(better-sqlite3,WAL)
|
||||
│ ├── engine.js # 会话管理 + 模型池 FIFO 调度 + Agent 主循环
|
||||
│ ├── llm.js # OpenAI 兼容上游流式调用(SSE 解析/工具分片合并)
|
||||
│ ├── mcp.js # MCP 客户端:mcp_servers 工具发现(tools/list)与转发(tools/call)
|
||||
│ ├── sse.js # 按会话分组的 SSE 事件总线
|
||||
│ ├── routes/
|
||||
│ │ ├── sessions.js # 会话 CRUD(10.1)
|
||||
│ │ ├── messages.js # 消息/SSE/start/stop(10.2)
|
||||
│ │ └── files.js # 文件上传/列表/下载/删除(10.3)
|
||||
│ ├── tools/
|
||||
│ │ ├── definitions.json # 内置 16 个工具的 JSON Schema
|
||||
│ │ └── executor.js # 内置工具执行器(任务目录沙箱;未知工具名转 MCP)
|
||||
│ ├── templates/profile-default.txt # System prompt 模板(直接编辑)
|
||||
│ └── public/ # H5 前端(Vanilla JS + SSE;无构建,index.html + js/ 六模块按序加载)
|
||||
├── test/ # mock 上游 + 端到端冒烟测试
|
||||
├── config.example.yml # core 专属配置模板(部署时生成/复制为仓库根 config.yml 挂进容器)
|
||||
├── Dockerfile / docker-compose.yml
|
||||
```
|
||||
对外能力、部署与配置见仓库根 [`../README.md`](../README.md);内部结构、数据模型与修改约束见 [`../docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md)。
|
||||
|
||||
## 本地运行
|
||||
|
||||
```bash
|
||||
cd app
|
||||
npm install
|
||||
cp config.example.yml config.yml # platforms 可先留空(启动后在设置页添加);本地跑再把 workspace_root / data_root 改回 ./data/...
|
||||
npm start # http://localhost:8090
|
||||
cp config.example.yml config.yml
|
||||
# 本地调试时把 workspace_root / data_root 改到仓库内可写目录
|
||||
AGENT_CONFIG=./config.yml node server/server.js
|
||||
```
|
||||
|
||||
默认监听 `8090`。`platforms` 可以留空,启动后到设置页添加模型并重启。
|
||||
|
||||
## 测试
|
||||
|
||||
```bash
|
||||
cd app
|
||||
npm test # 启动 mock 上游 + 真实 server 的端到端冒烟测试(25 项断言)
|
||||
npm test
|
||||
```
|
||||
|
||||
## 提示词与工具 schema
|
||||
端到端冒烟测试会启动 mock 模型上游(`:9999`)和真实 server(`:8099`),测试数据隔离在 `test/tmp`。
|
||||
|
||||
System prompt 完全静态(所有会话共用,利于上游前缀缓存),在 `server/templates/profile-default.txt` 直接编辑;工具定义在 `server/tools/definitions.json`。改完重启服务。
|
||||
> 注意:`test/smoke.js` 仍有旧断言——排队已从运行期移除,且 `GET /api/sessions/:id` 不再直接返回 `role=tool` 行(改为按需加载)。当前会在 `[2] 工具调用` 与 `[5] 排队调度` 失败;修改相关路径时先同步测试,不要把它当作全绿基线。
|
||||
|
||||
## 关键行为速查
|
||||
其他测试:
|
||||
|
||||
- 会话创建即尝试绑定空闲模型;无空闲则进全局队列 FIFO。
|
||||
- 每轮 AI 完成(无工具调)或用户终止后释放模型;新消息重新入队。
|
||||
- 规划阶段点「开始执行」:追加固定模板消息并切 execution。
|
||||
- 终止:置位标志 + kill 进程组 + 中止模型流,不再发新请求。
|
||||
- 所有文件路径解析到任务目录内,拒绝越界。
|
||||
- MCP 服务在 config.yml 的 `mcp_servers` 配置(可多个,每项 name?/url/headers/enable?/timeout_ms?,enable 默认 true、false 时启动不加载其工具;timeout_ms 为该服务单次工具调用最大等待,默认 60s);启动时发现其工具,追加在内置工具之后与 system prompt 一起发给模型;服务不可用仅启动日志告警,工具名重名时加「服务名__」前缀。
|
||||
```bash
|
||||
node test/remote-exec.test.js # 远端 executor 集成
|
||||
node test/trim-smoke.js # 历史裁剪
|
||||
node test/dep-check.js # 依赖完整性
|
||||
```
|
||||
|
||||
部署见 `../docs/DEPLOY.md`。
|
||||
## 关键文件
|
||||
|
||||
| 文件 | 职责 |
|
||||
|---|---|
|
||||
| `server/server.js` | 装配配置、DB、SSE、路由与启动顺序 |
|
||||
| `server/engine.js` | 会话、模型池、Agent 主循环、压缩、标题、日记收口 |
|
||||
| `server/llm.js` | 消息组装与上游流式调用 |
|
||||
| `server/tools/executor.js` | 内置工具与路径沙箱 |
|
||||
| `server/tools/definitions.json` | 内置工具 schema |
|
||||
| `server/routes/` | HTTP API |
|
||||
| `server/public/` | 前端(无构建,按序加载脚本) |
|
||||
|
||||
修改前先读架构文档的「修改时必须遵守的约束」一节。
|
||||
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
// SQLite 数据层。表结构见 README 第九章;本模块同时提供常用查询。
|
||||
// SQLite 数据层。表结构见 docs/ARCHITECTURE.md §4.1;本模块同时提供常用查询。
|
||||
const Database = require('better-sqlite3');
|
||||
const path = require('path');
|
||||
const fs = require('fs');
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
// 文本命令接入端(channel)API:给没有可点击 UI 的端(IM 桥、CLI 等)提供会话内操作的文字入口。
|
||||
// 设计(docs/ARCHITECTURE.md §4.1/§7):
|
||||
// 设计(docs/ARCHITECTURE.md §5.13):
|
||||
// - 命令只在 /api/channel/send 解析,不进普通消息路由——Web 上以斜杠开头的文本照常发给模型。
|
||||
// 命令是无 UI 端的按钮替代品,不是全局协议(防误伤路径/代码讨论这类合法文本)。
|
||||
// - 每个 (user, channel) 记一个「当前会话」(channel_sessions 表):接入端没有会话列表 UI,
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
// 文件管理 API(README 10.3):上传 / 列表 / 下载 / 删除
|
||||
// 文件管理 API(docs/ARCHITECTURE.md §5.15):上传 / 列表 / 下载 / 删除
|
||||
const express = require('express');
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
// 消息与交互 API(README 10.2):发消息 / SSE 流 / 开始执行 / 终止
|
||||
// 消息与交互 API(docs/ARCHITECTURE.md §5.15):发消息 / SSE 流 / 开始执行 / 终止
|
||||
const express = require('express');
|
||||
const engine = require('../engine');
|
||||
const log = require('../log');
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
// 会话管理 API(README 10.1)
|
||||
// 会话管理 API(docs/ARCHITECTURE.md §5.15)
|
||||
const express = require('express');
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
|
||||
+691
-675
File diff suppressed because it is too large
Load Diff
-181
@@ -1,181 +0,0 @@
|
||||
# 部署说明(Docker,IP:端口直连,无 nginx-proxy)
|
||||
|
||||
配置与编排文件都放在**仓库顶层**,方便直接调整:
|
||||
|
||||
| 宿主机路径 | 容器内路径 | 说明 |
|
||||
|---|---|---|
|
||||
| `./docker-compose.yml` | — | 编排(构建 `./app`,把容器 8090 映射到宿主机 8090) |
|
||||
| `./config.yml` | `/app/config.yml` | 运行配置(AGENT_CONFIG 指向它;含密钥,已被 .gitignore 忽略) |
|
||||
| `./tasks/` | `/workspace/tasks` | 任务目录:AI 的文件工作区(与 executor 必须同路径) |
|
||||
| `./data/` | `/workspace/data` | 数据目录 + SQLite(`.agent.db`) |
|
||||
| `./skills/` | `/workspace/skills` | 技能目录:所有任务/会话共享 |
|
||||
| `./.env` | — | 编排变量(`EXECUTOR_TOKEN` / `AGENT_PORT` / `AUTH_SECRET`),已被 .gitignore 忽略 |
|
||||
| `./scripts/init.sh` | — | 一键生成上面两个文件并起服务(见第 0 节) |
|
||||
|
||||
> `config.yml` 与 `.env` 推荐交给 `scripts/init.sh` 生成(见第 0 节);不想用脚本的话也可以自己建(见第 2 节)。
|
||||
|
||||
## 0. 一键生成配置(推荐)
|
||||
|
||||
`scripts/init.sh` 只读环境变量(不依赖任何外部文件),生成 `.env` 与 `config.yml`:
|
||||
|
||||
```bash
|
||||
# 什么都不给也能跑:默认账号 admin/admin、无模型(platforms: [])
|
||||
./scripts/init.sh
|
||||
|
||||
# 给几个变量
|
||||
BIGMODEL_KEY=xxx DEEPSEEK_KEY=yyy ZHIPU_KEY=zzz PUBLIC_IP=1.2.3.4 AUTH_USER=me ./scripts/init.sh
|
||||
```
|
||||
|
||||
| 输入变量(均可选) | 说明 |
|
||||
|---|---|
|
||||
| `BIGMODEL_KEY` / `DEEPSEEK_KEY` / `QWEN_KEY` | 模型平台 key,**填几个启用几个**(0~3 个) |
|
||||
| `ZHIPU_KEY` | image_task / video_task 用;**留空则这两个服务 `enable: false`**(工具不加载) |
|
||||
| `AUTH_USER` / `AUTH_PASSWORD` | 登录账号(默认 `admin`/`admin`,记得改) |
|
||||
| `PUBLIC_IP` / `AGENT_PORT` | 对外地址与端口,写进 `public_link.base_url`(`PUBLIC_IP` 空则尝试自动探测) |
|
||||
| `AUTH_SECRET` / `EXECUTOR_TOKEN` | 一般不用给:不给就自动生成,并**存在 `.env` 里复用**(所以重跑不会掉登录态) |
|
||||
|
||||
生成的 `config.yml` **只含 deploy 相关段**:`platforms` / `auth` / `mcp_servers` / `public_link`;其余配置项
|
||||
(路径、超时、`model_profiles` 等)走 `server/config.js` 的默认值,完整清单见 `app/config.example.yml`。
|
||||
|
||||
⚠️ **`config.yml` 是生成物,不要再手改**:每次生成都会把旧的备份成 `config.yml.bak.<时间戳>`。
|
||||
要改配置请带环境变量重跑该脚本,或者不用脚本、按第 2 节手动维护。
|
||||
|
||||
> 本机现成的一键流程(仓库外):`/root/deploy.conf` 放变量 → `/root/init_repos.sh`(拉仓库 → 把变量 export 出去 → 调本脚本)。
|
||||
|
||||
## 1. 网络(自动创建,无需手动)
|
||||
|
||||
`agent-core` 与 `mcp` 仓库的服务共用网络 `agent-mcp-net`:agent 按容器名访问 MCP
|
||||
(如 `http://mcp_web_search:3000/`)。该网络由**本仓库的 compose 创建**(固定名字,不带项目名前缀),
|
||||
`mcp` 侧声明为 `external` 直接加入。
|
||||
|
||||
所以全新机器上有**先后顺序**:先起 agent(创建网络),再起 mcp(mcp 单独先起会因为网络不存在而报错)。
|
||||
|
||||
```bash
|
||||
# 1) 先 agent,创建网络
|
||||
docker compose up -d --build
|
||||
|
||||
# 2) 再 mcp
|
||||
cd ../mcp && docker compose up -d --build
|
||||
```
|
||||
|
||||
> 拆的时候反着来:先 `down` mcp,再 `down` agent。否则 agent 侧会报
|
||||
> `network agent-mcp-net has active endpoints`(容器照删、网络留下,重新 up 就恢复,不损数据)。
|
||||
|
||||
## 2. 准备配置(手动方式)
|
||||
|
||||
不用 `scripts/init.sh` 时,自己建这两个文件:
|
||||
|
||||
```bash
|
||||
cp app/config.example.yml config.yml
|
||||
cp .env.example .env
|
||||
vi .env # 填 EXECUTOR_TOKEN / WXBOT_TOKEN(或直接跑 scripts/init.sh 自动生成)
|
||||
vi config.yml
|
||||
```
|
||||
|
||||
`app/config.example.yml` 与 `server/config.js` 的默认值一一对应,容器内可直接用(路径默认
|
||||
`/workspace/tasks`、`/workspace/data`)。`config.yml` 里至少要配:
|
||||
|
||||
```yaml
|
||||
platforms: ... # 模型池:每个平台 url + keys.api_key + models.id;可留空,启动后到设置页添加
|
||||
auth: # 建议启用,否则谁都能访问
|
||||
secret: "换一个随机串"
|
||||
users:
|
||||
- user: admin
|
||||
password: "换一个密码"
|
||||
mcp_servers: # 无域名时按容器名访问(模板已写好,按需启用)
|
||||
- name: web_search
|
||||
url: "http://mcp_web_search:3000/"
|
||||
```
|
||||
|
||||
> `public_link.base_url` 只在需要给外部服务公网 URL(图生视频取参考图)时才配;纯 IP:端口部署
|
||||
> 填 `"http://<服务器IP>:8090"`,容器 env 有 `VIRTUAL_HOST`(nginx-proxy)时以它为准(见第 4.1 节)。
|
||||
|
||||
> ⚠️ 必须先有 `config.yml` 再 `up`:compose 挂载的是 `./config.yml:/app/config.yml`,
|
||||
> 文件不存在时 Docker 会在宿主机建一个同名**目录**,容器起来会读不到配置。
|
||||
|
||||
## 3. 构建并启动
|
||||
|
||||
```bash
|
||||
# 在仓库顶层(含 docker-compose.yml 的位置)执行
|
||||
docker compose up -d --build
|
||||
docker compose logs -f agent-core # 看到 "Agent server listening on 8090" 即成功
|
||||
```
|
||||
|
||||
首次启动会先跑一次 `agent-executor-init`(把技能依赖落到宿主机 `./skills`),跑完自动退出,
|
||||
属正常现象。
|
||||
|
||||
> 镜像构建默认走腾讯云镜像源(apt / pip / npm),否则国内机器上 `apt-get update` 可以卡十几分钟。
|
||||
> 境外构建或想换源:`docker compose build --build-arg DEBIAN_MIRROR=deb.debian.org agent-executor`
|
||||
> (mcp 仓库同理,参数名是 `NPM_REGISTRY`)。腾讯云 CVM 上还可换成内网镜像 `mirrors.tencentyun.com`。
|
||||
|
||||
## 4. 访问
|
||||
|
||||
浏览器打开 **`http://<服务器IP>:8090`**(端口可用 `.env` 里的 `AGENT_PORT` 改)。
|
||||
登录用第 2 步 `auth.users` 里配的账号。
|
||||
|
||||
**对外只需要放行这一个端口**:`agent-executor`(9000)和 mcp 的三个服务都只在 `agent-mcp-net`
|
||||
内网,没有映射到宿主机(需要从宿主机 curl 调试时,去 mcp 仓库的 `docker-compose.yml` 里临时
|
||||
把对应服务的 `ports` 两行取消注释)。
|
||||
|
||||
### 4.1 公网临时链接(只有“把本地文件交给外部服务”时才用到)
|
||||
|
||||
场景:图生视频时,智谱服务器生成视频前要**自己来拉参考图**,它不带 cookie、不带 `Authorization`,
|
||||
所以必须有一条公网匿名可达的 URL。做法是给一个**不透明短 ID**(`app/server/public-files.js`):
|
||||
22 字符随机串,服务端内存表记着它对应哪个会话的哪个文件、什么时候过期。
|
||||
|
||||
AI 拿链接的姿势:直接调内置工具 `mint_public_link`(只传文件名),core 在进程内签好并把 URL 当
|
||||
工具结果返回。没有任何额外的 HTTP 签发端口,也不存在“AI 的命令带不了凭据”这个问题:
|
||||
|
||||
```
|
||||
mint_public_link({ path: "_cgi-bin_..._d92292d.jpg" })
|
||||
→ http://124.221.199.237:8090/p/9fQ2mZ7xK4tR1vBn
|
||||
返回的就是现成 URL(约 50 字符、纯 ASCII),直接当 image_url 用
|
||||
```
|
||||
|
||||
```
|
||||
智谱 ──匿名 GET──► /p/9fQ2mZ7xK4tR1vBn (core :8090)
|
||||
│ 查内存表:未过期?→ 得到(会话, 相对路径)
|
||||
▼
|
||||
./tasks/<会话>/foo.png ← 文件仍在原地,零拷贝
|
||||
```
|
||||
|
||||
> 为什么不做成“带签名的 URL”:那样必须把会话名、文件名、过期时间、64 位签名全塞进 URL(数百字符、
|
||||
> 满是 `%XX`)。而这条 URL 会被模型抄进工具参数、并且**永久留在会话历史里每轮重发**,
|
||||
> 太长又难抄,还白烧 token。短 ID 把三个问题一次解决了。
|
||||
|
||||
- 必须在 `config.yml` 配 `public_link.base_url = "http://<服务器IP>:8090"`;不配则 `mint_public_link` 直接报错
|
||||
(需要公网 URL 的那部分功能就用不了,例如 video_task 拉不到参考图)。
|
||||
例外:容器 env 里配了 `VIRTUAL_HOST`(nginx-proxy 域名 + HTTPS 那套)时,前缀自动用 `https://<域名>`,
|
||||
不用改 `config.yml`(改也盖不住它)。
|
||||
- 链接有效期 `public_link.ttl_ms`,默认 30 分钟;签完尽快用掉。
|
||||
- 沙箱外的人要用上这条链接,得拿到那个 22 字符随机 ID(猜不出来,也不可能枚举),且过期即废。
|
||||
- 这条路不搬字节:文件始终在它原本的位置,也不需要 video_task 参与上传/落盘。
|
||||
|
||||
## 5. 没有 HTTPS 的影响(可忽略,仅记录)
|
||||
|
||||
HTTP 直连时浏览器不认为这是"安全上下文",以下能力自动降级,不影响主流程:
|
||||
|
||||
- PWA / Service Worker 不注册(`http://IP` 不是 secure context),离线缓存与「添加到主屏」不可用。
|
||||
- 复制按钮的 `navigator.clipboard` 不可用,前端自动回退到旧 API。
|
||||
- 登录 cookie 本身没带 `Secure` 标志,HTTP 下正常签发与携带(`auth.js` 用的是 HttpOnly + SameSite=Lax)。
|
||||
|
||||
日后若加回 nginx / HTTPS 反代,注意 **SSE 必须关代理缓冲**,否则流式输出会被攒住不发:
|
||||
|
||||
```
|
||||
location / {
|
||||
proxy_pass http://agent-core:8090; # 或宿主机 IP:8090
|
||||
proxy_http_version 1.1;
|
||||
proxy_buffering off; # SSE 关键
|
||||
proxy_read_timeout 3600s;
|
||||
}
|
||||
```
|
||||
|
||||
## 6. 升级流程
|
||||
|
||||
```bash
|
||||
git pull
|
||||
docker compose up -d --build # 仓库顶层执行
|
||||
```
|
||||
|
||||
数据库与任务目录都在 bind 挂载的 `./data`、`./tasks` 内,升级不丢数据。进程重启时,
|
||||
原 active 会话会自动退回排队队列,待模型空闲后继续。
|
||||
@@ -1,80 +0,0 @@
|
||||
## 1. 页面定位
|
||||
|
||||
- `v2.html` 是并行于 `index.html` 的另一套 H5 界面,主打**移动端单聊 + 历史抽屉**,不沿用 index 的底部多 Tab 结构。
|
||||
- 直接访问 `/v2.html`;无入口链接(浏览器手动打开或自己加)。
|
||||
- index.html 仍是功能最全的 1.x 界面(tasks.js 多 Tab / 工具卡片 / makrdown / 图片压缩 / 文件面板),v2 迭代时可随时回看参考实现。
|
||||
|
||||
## 2. 涉及文件
|
||||
|
||||
| 文件 | 说明 |
|
||||
|---|---|
|
||||
| `app/server/public/v2.html` | 页面结构 + 全部前端逻辑(内联 `<script>`,无构建步骤) |
|
||||
| `app/server/public/css/v2.css` | v2 全部样式(已从 html 内联 `<style>` 抽出) |
|
||||
|
||||
- 后端只用了**既有 /api 接口**,上一轮未新增/改动任何后端代码。
|
||||
- 样式与 `index.html` 体系(`css/style.css`)完全隔离,互不干扰。
|
||||
|
||||
## 3. 已接通的真实业务流
|
||||
|
||||
全部走 `v2.html` 内联脚本,核心请求函数为自带 `req()`(401 自动跳 `/login`):
|
||||
|
||||
| 用户动作 | 实现方式 |
|
||||
|---|---|
|
||||
| 首页欢迎态 | 仅「文秘助理 / 识图专家」两个模式胶囊,纯前端状态 |
|
||||
| 首条消息 | `ensureSession()` → 无会话时先 `POST /api/sessions {title:'', model_id:''}`,再发消息;创建后进入 chat 视图 |
|
||||
| 发送文本+附件 | `send()` → `POST /:id/messages {content, attachments:[{name,size}]}` |
|
||||
| 附件上传 | 选文件只进本地 `state.attachments`;发送时才 `POST /:id/files`(multipart,字段名 `files`),拿回文件名后再随消息体发 attachments |
|
||||
| 历史列表(抽屉) | 打开抽屉 / 发送后 / done 后调 `loadSessionList()`:搜索词为空时并行拉 `status=active&limit=100` 与 `status=done&limit=50&with_total=1` 合并;搜索走 `?q=` |
|
||||
| 打开历史会话 | `openSession()` → `GET /api/sessions/:id` 渲染全部消息 → `connectStream()` |
|
||||
| 实时回复 | EventSource `GET /:id/stream`:`status` / `assistant_delta` / `assistant_message` / `tool_call` / `tool_result` / `done` |
|
||||
| 复制 AI 文本 | 历史 AI 消息右下角按钮,内容以 `data-b64` 存放(防引号破坏属性) |
|
||||
| 删除会话 | 消息操作栏垃圾桶 → `window.confirm` → `DELETE /:id?delete_dir=true`(连同任务目录文件,不可恢复) |
|
||||
| 会话标题 | 后端会在首条用户消息时自动截取前 24 字;本地 header 同步乐观赋值 |
|
||||
|
||||
### 消息展示约定
|
||||
|
||||
- 用户消息:右侧浅灰气泡。附件由服务端拼成前缀 `【系统通知】用户上传了文件:xx(大小 N)…`,前端 `parseUploadNotice()` 拆出 📎 行后展示正文。
|
||||
- AI 消息:左侧大段白底文本,无 markdown,`white-space: pre-wrap`。
|
||||
- 工具调用:仅显示一行 `🔧 工具名`(有 tool_call 事件 / 历史 assistant 的 tool_calls 字段时)。历史中的 `role: tool` 消息不展示(看不到工具输出与图片)。
|
||||
- 「思考中」打字占位:每次发送后出现,首个 SSE 事件到达时消失。
|
||||
|
||||
## 4. 明确纯前端、无后端支撑的能力(现状即如此)
|
||||
|
||||
这些概念在 mock 原型里能“表演”,接真实后端后**后端没有对应字段/参数**,目前只影响外观或文案:
|
||||
|
||||
1. **文秘助理 / 识图专家 模式**:后端无 `mode` 字段,也暂无「模式 → 模型」映射约定。现仅影响欢迎页 hint 与聊天 header 的模式文案。
|
||||
2. **深度思考开关**:后端请求无 `reasoning`/`deep_think` 参数。开关纯本地视觉状态。
|
||||
3. **思考过程折叠块(已思考 N 秒/思考步骤)**:后端不输出 reasoning 内容,此能力已随 mock 一起删除。
|
||||
4. **按条删除消息**:后端只有会话级删除/清空,无消息级删除接口,故删除按钮 = 删除整个会话。
|
||||
|
||||
若让 1/2/4 真正生效,属于**后端新增能力或接口扩展**的范畴,需先定接口再实现(例如 `POST /:id/messages` 增加 `mode/deep_think` 参数;或前端把「识图专家」映射到某个带 vision 的 `model_id` 走现有 `POST /api/sessions` 建会话)。
|
||||
|
||||
## 5. 后端已有、v2 尚未接入 UI 的接口(下次可做清单)
|
||||
|
||||
| 接口 | 建议接入点 |
|
||||
|---|---|
|
||||
| `PATCH /api/sessions/:id {title}` | 会话重命名(header 标题点击 / 抽屉长按) |
|
||||
| `POST /:id/stop`、`/release`、`/bind {model_id}` | 对话中终止 / 保持态断开 / 换模型,需先有会话状态与模型池 UI |
|
||||
| `DELETE /:id/messages` | 一键清空会话(保留文件) |
|
||||
| `GET /:id/files/download-token?path=` | 附件/文件下载(配合文件面板) |
|
||||
| `GET /api/models` | 当前空闲/占用模型池,供新建会话选模型、模式映射 |
|
||||
| `GET /api/system/status` | 版本信息、上传压缩配置 `upload`(参考 `tasks.js` 的大图压缩逻辑) |
|
||||
|
||||
## 6. 已知行为瑕疵 / 简化点(建议优先修)
|
||||
|
||||
1. **流式回复完成后没有操作行**:`assistant_message` 收尾时只留文本,不追加「时间 + 复制/删除」;而历史重开(`aiMsgHtml`)有。同一消息两种状态下观感不一致。
|
||||
2. **排队场景无提示**:`send()` 无条件挂思考占位。若 `POST /messages` 返回 `delivered:'queued'`(在排队等模型),应像 index 那样提示「排队中/暂存」,避免用户以为卡死。SSE `status` 事件带 `queue_pos` 可展示第几位。
|
||||
3. **抽屉列表无分页**:只拉 active 100 + done 50,会话多时看不到更早归档;搜索无 loading/竞态处理。
|
||||
4. **无 markdown 渲染**:AI 回复为纯文本。index 用 marked CDN,若 v2 要渲染代码块/列表需引入同一方案。
|
||||
5. **移动端大图上传无压缩**:index `tasks.js` 有 `maybeCompressImage` + `/api/system/status` 的 upload 配置,v2 直传原图,流量大且可能超服务端 50MB 限制。
|
||||
6. **看不到工具输出与文件**:工具只显示一行名字;不做结果展开/图片查看下载。
|
||||
7. **会话删除不可选「保留文件」**:v2 固定传 `delete_dir=true`;index 有二次弹窗让用户选是否连目录一起删。
|
||||
|
||||
## 7. 修改 v2 时的注意点
|
||||
|
||||
- 页面**自包含**:不加载 `core.js / tasks.js / marked`,全部工具函数(`$`/`esc`/`req`/`toast`/`copyText`/`fmtTime`)在页面内定义。若今后要共享代码先考虑重名冲突。
|
||||
- 全局状态集中在 `state`(`view/mode/deepThink/sessionId/sessionTitle/status/sessions/attachments/es/streamText/streamEl/toolLines/typingEl/streaming`),别再散落游离变量。
|
||||
- 切换会话/新建/删除前务必 `closeStream()` + `removeTyping()` + 重置流式相关字段,防旧会话 SSE 污染新会话。
|
||||
- 消息内容一律 `esc()` 后再进模板;复制按钮用 base64 传内容。
|
||||
- `v2.html` 顶部大注释维护着「接口参考/未接入清单」,改动的接口状态要同步更新那里。
|
||||
- 页面入口 `/v2.html` 无防盗链,直接可访问,注意它同样受全局登录中间件保护。
|
||||
@@ -1,48 +0,0 @@
|
||||
定位吸收了:**微信通道 = 一个有记忆的人**。会话是工作台(短期记忆),按天的日记是长期记忆,轮换即"下班记日记"。方向我认同,且它和刚落地的 30 分钟自动收口正好咬合:轮换留下的旧 held 会话自己归档。
|
||||
|
||||
先补三个**代码里发现的硬事实**,它们影响设计,然后给里程碑计划。
|
||||
|
||||
## 设计层要碰的三个钉子
|
||||
|
||||
**1. 回忆 skill 的数据通路是真坑(你第 4 点里藏着)。** 隔离是刻意的:executor 的 session 模式把其它会话的任务目录遮掉了,`read_file`/terminal 跨不出当前会话目录——skill 脚本从执行器侧**天然摸不到**旧会话的消息流和成果文件。两条出路:
|
||||
- **方案 A(我推荐)**:回忆仍走 skill(SKILL.md 当"怎么回忆"的操作手册,不占 tool schema),但脚本调 core 的**只读内部接口**(`/api/sessions/:id/messages|files` 已存在,加个 executor→core 的服务 token 即可)——基础设施增量只有一条回连通道;
|
||||
- 方案 B:不建 skill,加一个极简 `recall` tool(op=days / op=session)——违背你"别撑 tool 描述"的初衷,但通路最短。
|
||||
这个要你拍板,它决定 M3 的形态。
|
||||
|
||||
**2. 碎片摘要绝不能阻塞微信回信。** 轮换发生在入站消息路径上;旧会话摘要是一次 LLM 调用,必须**后台异步**生成(先换绑新会话、先回用户,碎片慢慢落),失败只记日志——日记晚到一分钟无伤大雅。另外碎片生成复用压缩那套基建(`templates/` 加个 journal prompt + 轻量 LLM 调用),不是新子系统。
|
||||
|
||||
**3. 定时任务会话和日记有个现成的交集**:scheduler 每次触发前本来就"历史整体存档、AI 只看到任务 prompt"(等价自动换班)。所以**定时任务的每次执行也是天然日记事件**——不需要 LLM,模板化一行(「X 任务按计划执行,结果:…」)直接追加当日条目。这让"纯任务会话"虽不轮换也有记忆痕迹,成本为零。
|
||||
|
||||
## 里程碑切割
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
M0["M0 地基\n记忆表+碎片生成"] --> M1["M1 短期记忆边界\n轮换触发器组"] --> M2["M2 注入闭环\n新会话读日记"]
|
||||
M3["M3 回忆通路\n跨会话细粒度"]
|
||||
M4["M4 定时任务\nlist_all+承接"]
|
||||
M2 -.可并行.- M3
|
||||
M2 -.可并行.- M4
|
||||
```
|
||||
|
||||
**M0 — 地基**(`db.js` / `engine.js` / `config.js`)
|
||||
- `memory_entries(user, day, content)` 表 + 追加/读取/按保留期裁剪(`memory.retain_days` 默认 7、上限 30 截断);
|
||||
- `appendFragment(user, day, text)` 与 `journalFor(user)`;碎片 LLM 摘要函数(异步、幂等、失败降级为"仅标题+文件清单");
|
||||
- 当日多碎片 = 机械拼接追加(每片已条目化,不再二次 LLM 合并,省钱且确定性)。
|
||||
|
||||
**M1 — 短期记忆边界**(`wechat.js` handleInbox + `engine.js`)
|
||||
轮换触发器,全部收敛到同一个 `rotateChannelSession()`:① 入站距最后一条 **user** 消息 >4h(排除 scheduler_note 续命坑);② 微信会话上下文超 `auto_compress_tokens` → 直接换会话不压缩(复用现有阈值,行为按通道分叉);③ `/new`、`/switch` 换绑时对手动离开的会话产碎片;④ 删会话不产。每次轮换后台产碎片 + 旧会话 releaseHold 收口。
|
||||
|
||||
**M2 — 注入闭环**(`wechat.js` ensureChannelContext)
|
||||
新通道会话创建时把近 7 天日记注入上下文(channel_note 同族的一条 memory_note,第一人称口吻「9月28日 帮他整理了…」)。到这里"这个人"已经能连续地活:**M0-M2 是最小可用闭环**。
|
||||
|
||||
**M3 — 回忆通路**(按上面方案 A/B 拍板结果做)
|
||||
日记条目里带旧会话 id + 成果文件清单索引 → skill/工具按 id 下钻详细消息与文件。
|
||||
|
||||
**M4 — 定时任务配套**(`tools/executor.js` + `routes/channel.js`)
|
||||
- `schedule` 加 `op=list_all`(跨会话:join sessions 出标题/cron/下次/上次状态)——只读全览,改删仍绑当前会话,引导 `/switch`;
|
||||
- `op=create` 撞主键时错误文案升级为「本会话已有任务 X,如需新闹钟请开新会话承接」→ AI 依你第 5 点走 `/new` 流程;
|
||||
- 微信 `/tasks` 文本命令(与现有命令同族)+ 定时任务执行结果模板化落日记(第 3 个钉子)。
|
||||
|
||||
顺序 M0→M1→M2 串行(每步都可独立验证),M3/M4 并行或调序。**要你拍板的只剩两个**:① 回忆走 A(skill+内部 API 回连)还是 B(极简 recall tool)?② `/clear`(网页端清空回 advising)要不要也产碎片——我倾向产,语义一致。
|
||||
|
||||
定了我就从 M0 开干。
|
||||
Reference in New Issue
Block a user