# ToyChat **Repository Path**: Zer0Boy/toychat ## Basic Information - **Project Name**: ToyChat - **Description**: 一个玩具性质的LLM 聊天客户端(通过 DeepSeek V4.1 Flash和MiMo V2.6模型Vibe Coding 实现) - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: next - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-21 - **Last Updated**: 2026-11-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # ToyChat > 🧸 一个玩具性质的 LLM 聊天客户端 · CLI + WebUI · 联网搜索 · Markdown 渲染 **版本:v0.4.0-alpha** — *尚处于早期开发阶段,功能不完善。* [![Python](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://www.python.org/) [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Dependencies](https://img.shields.io/badge/deps-openai%20%7C%20rich%20%7C%20flask-%23412991)](https://pypi.org/project/openai/) --- ## 📦 项目简介 **ToyChat** 是一个玩具性质的 Python 项目,提供终端 CLI 与网页 WebUI 两种方式与 LLM 对话。 > ⚠️ **声明**:未完成的实验性项目,仅供学习与娱乐用途,不具备生产级软件所需的完整性、稳定性与安全性。 ## ✨ 功能特性 | 功能 | 状态 | |------|------| | OpenAI 兼容 API · 多轮上下文 · 流式响应 | ✅ | | 终端 Markdown 实时渲染(rich) | ✅ | | 思考过程显示(回答开始时自动折叠) | ✅ | | 联网问答(web_search 网页搜索 + web_fetch 网页抓取,供应商可插拔,默认关闭) | ✅ | | WebUI(仿 DeepSeek 布局,SSE 流式) | ✅ | | WebUI 历史会话管理(新建 / 切换 / 删除,持久化) | ✅ | | WebUI 公式渲染(KaTeX)· 代码高亮(highlight.js) | ✅ | | Token 消耗显示(CLI 末尾 / WebUI 输入框旁) | ✅ | | CLI 会话切换(`/sessions`,与 WebUI 共用 `data/sessions.json`) | ✅ | | CLI 工作模式(`/mode work`,可读写文件、执行 shell;联网开启时可查资料) | ✅ | | WebUI 工作模式(侧边栏对话/工作分区 · 工作空间切换 · 工具步骤流式展示) | ✅ | | 交互式配置引导(`chat.conf`) | ✅ | ### 🚧 尚未实现 模型参数微调 · MCP / 插件 …… ## 🚀 快速开始 ### 安装与运行 ```bash python3 -m pip install -r requirements.txt # 或 pip install -e . python3 toychat.py # CLI python3 toychat.py web # WebUI ``` > 安全提示:WebUI 默认只接受本机回环访问;要暴露到局域网必须显式设置 > `TOYCHAT_WEB_ALLOW_REMOTE=1`,但项目没有账号体系,请自行加反向代理/认证。 可选 `-w DIR` / `--workspace DIR` 指定工作模式的工作空间(默认 `~/toychat-workspace`,不存在则创建): ```bash python3 toychat.py -w ~/projects/demo # CLI:工作空间即进程目录 python3 toychat.py web -w ~/projects/demo # WebUI:作为工作模式默认工作空间(不切换进程目录) ``` 等价模块写法:`python3 -m toychat` / `python3 -m toychat web`(别名 `python3 -m toychat.web`)。 首次运行 CLI 会进入交互式配置向导,按提示输入 API Key、Base URL、模型 ID, 可选开启联网(网页搜索 + 网页抓取,按所选供应商补 API Key)。配置保存在 `chat.conf`,也可手动创建。 WebUI 浏览器访问 `http://127.0.0.1:8080`(启动时打印实际地址): | 场景 | 用法 | |------|------| | 换端口 / 随机端口 | `TOYCHAT_WEB_PORT=3000` / `TOYCHAT_WEB_PORT=0` | | 8080 被占用 | 自动改用空闲端口并打印提示 | | 换监听地址 | `TOYCHAT_WEB_HOST=…`(默认只允许回环;非回环需 `TOYCHAT_WEB_ALLOW_REMOTE=1`,无鉴权) | WebUI 亮点:设置页可改全部配置(模型/上下文/联网供应商与端点/密钥/超时与输出上限); 首次运行或配置不完整时自动弹出初始化窗口,顶栏徽标显示「已配置 / 未配置」, 设置页顶部展示当前配置摘要,API Key 用 `••••••••` 代替;「联网」开关即时持久化; 引用角标 [n] 点击弹确认框后打开来源网址(仅允许 http/https); 左侧边栏管理历史会话(持久化到项目 `data/sessions.json`,刷新不丢失),**对话 / 工作两个分区** (侧边栏顶部标签切换,历史会话按模式分开);输入框左侧 chip 可切换 💬 对话 / ⚙️ 工作模式 (切模式即开新会话),工作模式下显示 📁 工作空间 chip(点击弹出目录浏览器:点选文件夹、返回上级、新建文件夹)并提示 shell/文件风险;工作模式的工具调用以步骤行流式展示(📖 read / ⚡ bash / 🔍 搜索 / 📄 抓取 …), 任务进行中输入框上方显示状态条(思考/执行步骤/计时),发送按钮变为 ⏹ 可随时停止 (服务端取消:杀工具进程树、关模型流;bash 可秒停,联网请求受单次 HTTP 超时约束); 刷新/断线后任务继续在服务端执行, 顶部横幅「⏳ 任务进行中」可一键接回看直播并取回结果, 完整轨迹(思维链 + tool_calls + 工具结果)随会话落盘,刷新后原样回显; 悬停提问可复制 / 编辑 / 重新回答(作废本轮及之后轮次);思考过程可展开收起。回答中的 LaTeX 公式 (`$…$` / `$$…$$` / `\(…\)` / `\[…\]`)由 KaTeX 渲染,代码块经 highlight.js 语法高亮;两者与 marked、DOMPurify 一并本地托管于 `toychat/web/static/`,不依赖 CDN。 ### CLI 输入编辑 自实现行内编辑(不依赖 readline):`←` `→` 移动光标,`Home`/`Ctrl+A`、`End`/`Ctrl+E` 行首尾, `Backspace`/`Delete` 删除(中文按整字);`↑` `↓` 不进入输入内容。 ## ⚙️ 配置说明(chat.conf) `chat.conf` 在启动时解析一次:优先当前目录、否则回退到程序所在目录;之后进程内 `chdir`(`-w` / `/workspace`)不会改变配置读写位置, 格式如下(含 API Key,**不要提交到仓库**): ```ini api_key="sk-xxxxxxxxxxxxxxxx" base_url="https://api.deepseek.com/v1" model="deepseek-flash" response_language="简体中文" websearch_enabled="false" search_provider="doubao" search_api_key="" search_endpoint="" fetch_provider="local" fetch_api_key="" fetch_endpoint="" websearch_count="10" websearch_max_steps="8" work_max_steps="0" shell_timeout="60" max_output_chars="60000" ``` | 配置项 | 说明 | 示例 | |--------|------|------| | `api_key` / `base_url` / `model` | 必填,缺失会触发向导 | `sk-xxx` / `https://api.deepseek.com/v1` / `deepseek-flash` | | `context_window` | 上下文总容量,**留空自动探测**;填了则优先 | `"128000"` | | `response_language` | 工作模式回答语言(最长 32 字,默认简体中文) | `"简体中文"` | | `websearch_enabled` | 联网开关,**默认关闭**;开 = 两个工具都挂给模型 | `"false"` | | `search_provider` | 网页搜索供应商 | `"doubao"` / `"deepseek"` | | `search_api_key` | 网页搜索供应商的 API Key | `"xxxx-xxxx"` | | `search_endpoint` | 搜索接口地址覆盖,空 = 供应商默认(一般无需修改) | `""` | | `fetch_provider` | 网页抓取供应商 | `"local"` / `"deepseek"` | | `fetch_api_key` | 网页抓取供应商的 API Key(`local` 无需) | `"xxxx-xxxx"` | | `fetch_endpoint` | 抓取接口地址覆盖,空 = 供应商默认 | `""` | | `websearch_count` | 单次搜索结果条数**上限**(1~50),具体条数由模型每次决定 | `"10"` | | `websearch_max_steps` | 单轮联网调用次数上限(web_search + web_fetch 合计,1~20) | `"8"` | | `work_max_steps` | 工作模式工具循环轮数上限;`0` = 不限制(默认),1~1000 | `"0"` | | `shell_timeout` | 单条 shell 命令超时秒数(5~600,默认 60) | `"60"` | | `max_output_chars` | 单次工具输出上限字符数(2000~500000) | `"60000"` | > 老配置文件升级时自动迁移旧键(`websearch_api_key` → `search_api_key`, > `deepseek_search_api_key` → `fetch_api_key`,值不丢失),联网保持原开关状态; > 运行时 `/websearch` 命令的修改会立即写回本文件。 ## 🌐 联网(网页搜索 + 网页抓取) 联网 = 两个独立工具,开启后由**模型按需调用**(并非每轮都联网): | 工具 | 职责 | 供应商 | API Key | |------|------|--------|---------| | `web_search` | 搜罗网页信息与摘要 | `doubao`(豆包搜索 Custom)/ `deepseek` | `search_api_key` | | `web_fetch` | 抓取单个网页读正文 | `local`(本地标准库抓取)/ `deepseek` | `fetch_api_key` | - 典型工作流:先 `web_search` 拿摘要与链接,摘要不够再 `web_fetch` 深读最相关的 1~2 个网页 - 结果按 `[1] [2] …` 全局编号(搜索与抓取共用一套编号,抓取搜索结果里的网页 = 加深同一来源),回答中引用编号,结束后打印「📚 参考来源」 - 每次搜索条数由模型决定,`websearch_count` 仅作上限;抓取正文超过 8000 字会截断,本轮重复抓取同一网址走缓存 - 工具失败仅警告降级(错误回灌给模型自行决策),不影响对话 **两个模式的差异**: | | 对话模式 | 工作模式(`/mode work`) | |---|---|---| | 工具描述 | 问答导向(时效内容才联网) | 任务导向(为完成任务查资料) | | 工具结果 | 带全局引用编号,要求标注来源 `[n]` | 纯资料文本,**不带编号、不标出处** | | 结尾 | 打印「📚 参考来源」、写入 `citations` | 无引用清单 | **API Key 获取**: - 豆包搜索 Custom:火山引擎控制台 → 豆包搜索 → API Key 管理(每月 500 次免费额度,限流 5 QPS) - DeepSeek:[platform.deepseek.com](https://platform.deepseek.com/)(搜索与抓取共用同一把平台 Key, 按次计费约 ¥5/千次成功请求,搜索 100 QPS、抓取 25 QPS,详见[官方文档](https://api-docs.deepseek.com/zh-cn/guides/search)) **扩展供应商**:按能力划分,加一家 = 加一个 py 文件,无需改其他代码: - 搜索:`toychat/websearch/search/` 下新增 `xxx.py`,定义 `PROVIDER = SearchProvider(...)` - 抓取:`toychat/websearch/fetch/` 下新增 `xxx.py`,定义 `PROVIDER = FetchProvider(...)` 文件会被自动发现(`websearch/core.py` 的 `discover()`),设置页 / 向导 / 配置键自动跟上。 **CLI 命令**: | 命令 | 说明 | |------|------| | `/mode [chat\|work]` | 查看 / 切换模式(默认对话;工作模式可操作电脑) | | `/workspace [路径]` | 查看 / 切换工作空间(默认 `~/toychat-workspace`,避免误改源码) | | `/sessions`(或 `/会话`) | 列出**当前模式**的历史会话,选编号继续;`0` 新建 | | `/sessions new` | 新建会话(当前会话自动保存) | | `/sessions <编号>` | 直接切换到第 N 条历史会话 | | `/websearch on \| off` | 开启 / 关闭联网 | | `/websearch count <1~50>` | 单次搜索结果条数上限(立即生效并保存) | | `/websearch steps <1~20>` | 单轮联网调用次数上限(搜索+抓取合计,立即生效并保存) | | `/worksteps [0~1000]` | 工作模式工具轮数上限(0=不限制,默认;立即生效并保存) | | `/status` `/help` `/quit` | 状态栏 / 帮助 / 退出 | CLI 与 WebUI 共用同一份 `data/sessions.json`(统一存放,不随工作空间变动;旧的 `sessions.json` 首次启动会自动迁入)。工作模式会话记录所属工作空间,切换时自动 `cd` 过去; 对话模式不会因为切换历史会话而改变进程目录。 CLI 每轮回答后自动保存;切换历史会话后回显最近 8 条 消息(助手正文按终端 Markdown 渲染,带联网引用时列出「📚 参考来源」)。消息里的 `citations` 字段与 WebUI 同结构,WebUI 的参考链接不受影响。 **工作模式上下文**(与对话模式不同):会话完整保存并回传问题、思维链 (`reasoning_content`)、`tool_calls`、工具结果与回答;已知上下文容量时会按轮次 裁剪过旧的历史(最近一轮完整保留),多轮延续时模型能接上之前的思考与执行现场 (对齐 DeepSeek 思考模式·工具调用约定)。 工作模式的工具循环默认**不限制轮数**(`work_max_steps="0"`):模型自己决定何时停止, 用户也可以用 ⏹ / Ctrl+C 随时取消;如果担心失控,把 `work_max_steps` 设成正整数 (1~1000)即可加一道硬上限(触顶后摘掉工具,强制模型总结)。 工作模式系统提示词只写通用策略(先调查再修改、失败停止、工作空间边界、 不可信数据、截断处理等),**不枚举具体工具名**;工具清单与参数由每次请求的 `tools` 字段动态提供,因此新增本地工具或接入 MCP 时不需要改提示词。回答语言由 `response_language` 配置(默认简体中文)。 **Token 消耗**:CLI 每轮结束后显示本轮消耗与上下文占用;WebUI 在发送按钮左侧显示 `占用 / 总容量 · 百分比`(≥70% 变黄,≥90% 变红)。上下文总容量按三级回退解析: `chat.conf` 的 `context_window` → OpenAI 兼容 `models` 接口探测 → 模型名启发式; 探测失败会回退启发式并缓存,不会在设置页反复阻塞; 都拿不到则只显示 token 数、不显示百分比。 ## 🧪 使用示例(联网) ```text 你(🌐开):今天有什么科技新闻? 助手:🔍 第 1/8 次搜索:今天科技新闻 ⎿ 返回 10 条(新增 10 · 累计来源 10 条) 📄 抓取网页:https://example.com/news/1 ⎿ Example News(5321 字) 根据最新报道,……[1],另有消息称……[2][3] ──────────── 📚 参考来源 ──────────── [1] xxxxx(某站点 · 2026-09-21) https://example.com/news/1 ... ``` ## 📁 项目结构 ```text toychat-project/ ├── toychat.py # 兼容入口(python3 toychat.py) ├── toychat/ # 主包 │ ├── config.py # chat.conf 读写与解析(JSON 转义 / 原子写 / 旧键迁移) │ ├── storage.py # 原子写 + 跨进程文件锁(配置/会话/任务共用) │ ├── sessions.py # 会话持久化(核心层;web/sessions.py 为兼容壳) │ ├── tasks.py # 服务端任务、事件缓冲、协作式取消 │ ├── context.py # 按上下文预算裁剪历史(保护 tool 配对) │ ├── chat.py # 对话编排核心(事件流,与 UI 解耦) │ ├── agent.py # 工作模式编排(工具循环) │ ├── tools/ # 工作模式工具(fs / shell;路径 realpath 隔离) │ ├── websearch/ # 联网能力(按能力划分,供应商可插拔) │ │ ├── core.py # 统一抽象:供应商规格 / 数据形状 / 插件发现 │ │ ├── citations.py # 引用注册表(全局编号) │ │ ├── tools.py # web_search / web_fetch 两个工具 schema 与分发 │ │ ├── search/ # 网页搜索供应商(doubao / deepseek,一文件一家) │ │ └── fetch/ # 网页抓取供应商(deepseek / local,一文件一家) │ ├── __main__.py # python -m toychat [web] │ ├── cli/ # 终端界面(输入编辑 / 渲染 / 主循环) │ └── web/ # 网页界面(Flask + SSE、会话持久化、内置前端库含 KaTeX/hljs) ├── chat.conf # 用户配置(自动生成,勿提交) └── README.md ``` ## 🗺️ 路线图 - [x] 基础对话 · 流式响应 · 多轮上下文 - [x] 交互式配置向导 · 中文输入与行内编辑 - [x] 联网问答(web_search + web_fetch 双工具,供应商可插拔,引用来源) - [x] 终端 Markdown 渲染 · 思考过程折叠显示 - [x] WebUI(仿 DeepSeek)+ 会话管理 + 历史持久化 - [x] WebUI 公式渲染(KaTeX)+ 代码语法高亮(highlight.js) - [x] CLI 会话切换 · Token 消耗显示 - [x] CLI 工作模式(`/mode work`,read/write/edit/glob/grep/bash,联网开启时可搜索/抓取查资料) - [x] WebUI 工作模式(对话/工作分区 · 工作空间切换 · 工具步骤流式展示 · 轨迹落盘) - [ ] 可调节模型参数(temperature 等) - [ ] 更好的错误提示与重试机制 ## 🔒 安全边界(重要) - WebUI 默认只监听 `127.0.0.1`,所有 `/api/*` 写请求要求 `application/json` 并校验 `Origin`/`Sec-Fetch-Site`/`Host`,挡跨站请求和 DNS rebinding;非回环监听必须显式 `TOYCHAT_WEB_ALLOW_REMOTE=1`,且仍无账号体系。 - 工作模式的文件工具(read/write/edit/glob/grep)会把路径 `realpath` 后限制在 工作空间内;`bash` 本身仍可 `cd` 到别处,这是 shell 的固有属性——请只在你信任 模型/任务来源时使用工作模式,或把进程放进容器/低权限用户。 - 联网抓取会解析域名并拒绝私网/环回/链路本地地址,重定向逐跳校验;引用链接只允许 `http/https`,Markdown 消毒在注入引用之后仍受 CSP 约束。 - `chat.conf` / `data/*.json` 以 0600 权限原子写入;会话文件损坏时拒绝覆盖,不会 静默清空历史。 ## ⚠️ 已知问题与审查清单(2026-11-20) 本节记录最近一次完整代码审查发现的 **40 项已知问题与交互改进项**。截至本次提交, 以下问题均尚未在实现中修复;前文的功能与安全描述表示设计目标,阅读时应同时参考本节。 严重度按默认本机使用场景评估,开启远程访问或工作模式会放大影响。验证状态含义: - **已复现**:已通过临时目录、合成数据、打桩或函数级测试复现,未使用真实 API Key。 - **代码确认**:触发链可由代码确定,但未做完整浏览器 E2E、真实网络攻击或大内存压力测试。 - **改进**:主要属于交互或安全设计缺口,不作为实现缺陷的严重度评级。 ### 1. 取消、任务生命周期与流式恢复 | 编号 | 严重度 | 验证 | 问题与影响 | 主要位置 | |---|---|---|---|---| | A1 | 高 | 已复现 | **模型流没有接入取消令牌。** 普通对话、工作模式及触顶后的强制收尾调用 `stream_once()` 时都未传 `cancel=cancel`,已有“关闭上游流”钩子因此不会生效。点击停止或 Ctrl+C 后,模型仍可能继续生成和计费;Web 前端 3 秒后只是断开自己的 SSE 连接。 | `toychat/chat.py:327-342,493-502`;`toychat/agent.py:170-173,241-244`;`toychat/web/static/app.js:830-845` | | A2 | 高 | 已复现 | **取消后仍可能执行同批后续工具。** 编排层只在整批工具结束后检查取消;本地文件工具入口也不拒绝已取消任务,预先取消后调用 `write` 仍会落盘。Shell 还会先 `Popen` 再注册/检查取消,进程在被杀前可能已经产生副作用。 | `toychat/agent.py:164-169,190-234`;`toychat/tools/__init__.py:150-169`;`toychat/tools/shell.py:86-97,128-139` | | A3 | 中 | 已复现 | **旧停止计时器可能误停新一轮,恢复任务又缺少硬中断能力。** 3 秒计时器读取全局 `state.sending/abortCtrl`,回合结束未清理;第一轮迅速收尾后,旧计时器可 abort 第二轮。任务恢复请求没有独立 `AbortController`,流卡住时可能一直停在 sending。 | `toychat/web/static/app.js:830-845,1013-1032,1953-1955` | | A4 | 低 | 代码确认 | **联网请求进行中无法主动取消。** 联网工具基本只在请求前检查令牌,未把关闭响应/socket 的钩子传给供应商。本地抓取最多 6 跳且每跳独立超时,停止可能等待较长时间,期间会话 Gate 仍被占用。 | `toychat/websearch/tools.py:282-294`;`toychat/websearch/fetch/local.py:42-63,145-155` | | A5 | 低 | 已复现 | **`CancelToken` 注册与取消存在竞态。** 钩子加入列表后、注册方检查事件前,另一线程可能完成取消并执行同一钩子;注册方随后又会立即执行一次,违反“仅执行一次”的约定。 | `toychat/tasks.py:35-46,51-64` | | A6 | 中 | 代码确认 | **首个任务创建前可能长时间卡在上下文探测。** `/api/chat` 在创建 Task 之前调用 models 接口探测,失败路径包含 retrieve/list 与重试。此时前端拿不到任务 ID,停止无法送达未来的服务端任务,断开后任务仍可能被创建。 | `toychat/web/app.py:609-626`;`toychat/chat.py:124-169,175-199` | | A7 | 中 | 代码确认 | **工具已产生副作用后再发生模型/网络异常,会丢失部分工作轨迹。** 工作生成器没有机会给出最终 `trace`,CLI 不写历史,Web 只保存错误消息。用户重试时模型不知道此前已修改过什么,可能重复写入或执行命令。 | `toychat/web/app.py:659-665`;`toychat/cli/app.py:700-719`;`toychat/web/static/app.js:1007-1011` | ### 2. 配置、会话与持久化 | 编号 | 严重度 | 验证 | 问题与影响 | 主要位置 | |---|---|---|---|---| | B1 | 高 | 已复现 | **SSE 异常 EOF 可静默保存半段历史,完成结果又可能无法接回。** `consumeStream()` 不区分收到 `[DONE]` 与连接直接结束,部分正文可能被按成功保存;恢复按钮只显示 running,任务完成后入口消失。服务端完成任务时不写 canonical session,持久化依赖浏览器最后同步,关闭页面后正确答案可能只留在任务记录中。 | `toychat/web/static/app.js:971-991,1036-1083,1894-1903`;`toychat/web/app.py:628-669` | | B2 | 高 | 已复现 | **会话整包覆盖导致最后写入者胜。** 两个标签页、CLI 与 Web 或多个 Web 进程基于同一旧历史更新时,后写的完整 `messages` 会抹掉先写的新回合。SessionGate 只覆盖单个 Flask 进程的 `/api/chat`,保护不了会话 PUT、CLI 和跨进程写入。 | `toychat/sessions.py:153-174`;`toychat/web/app.py:311-332,609-611`;`toychat/web/static/app.js:709-742` | | B3 | 高 | 已复现 | **配置读—改—写竞态会回滚其他字段。** 文件锁只覆盖最终保存,不覆盖路由前的读取;两个标签分别修改不同字段,或 CLI 用启动时的旧快照保存联网开关,都可能覆盖另一客户端刚保存的模型、Base URL 或密钥。 | `toychat/config.py:248-274`;`toychat/web/app.py:464-485,525-529`;`toychat/web/static/app.js:1679-1687` | | B4 | 中 | 已复现 | **旧会话迁移存在跨进程覆盖竞态。** 两个进程同时看到目标不存在时,一个进程迁移并创建新会话后,另一个仍可执行无锁 `copy2`,用旧文件覆盖新数据;直接复制也不是原子替换。 | `toychat/sessions.py:56-71` | | B5 | 中 | 已复现 | **任务文件损坏后会被静默清空重建。** `persist()` 把 JSON 解析/读取失败当成空列表,下次任务结束会只写当前记录,与“会话损坏拒绝覆盖”的保护策略不一致。 | `toychat/tasks.py:223-238` | | B6 | 中 | 已复现 | **会话数据缺少完整语义校验。** 合法 JSON 中 `messages` 为整数或 `updated_at` 类型不一致会使列表排序/计数报错;会话 PUT 又只检查最外层数组,`[null]`、对象 content、非法 role 均可落盘,随后前端访问 `m.role` 时可能崩溃。 | `toychat/sessions.py:75-87,99-118`;`toychat/web/app.py:317-325`;`toychat/web/static/app.js:602-604` | | B7 | 中 | 代码确认 | **保存/删除失败对用户基本不可见。** 多处保存失败只写 console,删除甚至不检查 HTTP 状态就更新界面;磁盘满、权限错误或存储损坏时,用户刷新后才发现丢消息。运行中的会话也可被另一标签删除,原标签最后保存只能失败。 | `toychat/web/static/app.js:413,764-773,1026-1030,1486` | | B8 | 中 | 已复现 | **工具前说明在页面可见,但保存时丢失。** 展示层合并工具前后正文,历史写入却优先保存最后一段 `result.content`;刷新后只剩最终答案,下一轮模型上下文也与用户所见不一致。工作模式取消补尾时还可能丢掉已显示片段。 | `toychat/web/static/app.js:889-897,1087-1122,1177-1180` | | B9 | 中 | 代码确认 | **已有部分正文时,错误提示可能被最后一次 Markdown 重绘擦掉。** 错误节点放在会被替换的 Markdown 容器内,`errorShown` 却仍为 true,后续不再追加;状态条又会自动隐藏,用户可能只看到看似完整的半段正文。 | `toychat/web/static/app.js:907-912,976-980,1172-1188` | | B10 | 中 | 代码确认 | **会话选择与模式列表请求存在响应乱序。** 快速选择 A、B 或切换对话/工作模式时,旧响应可覆盖后选会话、列表和 active 高亮,用户可能在非预期会话中继续输入。需要请求序号、AbortController 或服务端版本校验。 | `toychat/web/static/app.js:492-534,691-707,1359-1365` | | B11 | 低 | 代码确认 | **删除会话不会清理任务中的完整历史副本。** Task detail 包含请求时 history 和最终结果,任务文件另行保留最近 20 条;删除会话只删除 sessions 数据,敏感对话仍可能留在任务文件中。需要明确保留策略及联动清理能力。 | `toychat/tasks.py:164-168,215-238`;`toychat/web/app.py:334-342` | ### 3. 本地工具与上下文预算 | 编号 | 严重度 | 验证 | 问题与影响 | 主要位置 | |---|---|---|---|---| | C1 | 高 | 已复现 | **`grep` 可通过工作区内符号链接读取外部文件。** 入口只校验搜索根目录,遍历结果未逐项执行真实路径检查,`open()` 会跟随链接;同一路径用 `read` 会被拒绝,安全边界不一致。 | `toychat/tools/fs.py:124-156`;`toychat/tools/__init__.py:160-162` | | C2 | 高 | 已复现 | **`edit` 会静默损坏非 UTF-8 文件。** `errors="replace"` 先把无法解码的字节换成 U+FFFD,再整文件回写;即使只改另一段 ASCII,原始字节也会不可逆变化,工具仍返回 ok。 | `toychat/tools/fs.py:69-82` | | C3 | 中 | 已复现 | **Shell 成功/失败存在双向误判。** 非零退出但没有 `error:` 前缀会被判成功,成功命令输出以 `error:` 开头又会被判失败;超时和取消也未结构化参与 ok 判定。已验证 `exit 7` 返回 `ok=True`。 | `toychat/tools/shell.py:160-168`;`toychat/tools/__init__.py:169-172` | | C4 | 中 | 已复现 | **并发 `edit` 会丢失一方更新。** 两个任务同时读取旧文件、修改不同位置再原子替换时,双方都返回 ok,但后写者覆盖先写者。原子写只能避免半截文件,不能保护读—改—写事务。 | `toychat/tools/fs.py:69-82` | | C5 | 中 | 代码确认 | **输出限制不能统一限制内存和工具结果。** `read` 在切片前用 `readlines()` 完整读入文件,大文件/超长行即使只读 400 行也会占用大量内存;`max_output_chars` 只在 bash 分支生效,read/grep 等结果不受该配置约束。 | `toychat/tools/fs.py:31-52,134-156`;`toychat/tools/__init__.py:164-169` | | C6 | 中 | 已复现 | **500 条历史硬切片可能从半轮工具消息开始。** 长 work 轨迹直接取最后 500 条,首条可能是 tool 或缺少前置 user/assistant tool_call,导致供应商协议 400,并无声丢弃旧上下文。 | `toychat/web/app.py:175,185-208` | | C7 | 中 | 已复现 | **超长单轮工作轨迹完全绕过上下文裁剪。** 只有一个 user 回合时直接原样返回,有多个回合时最新一轮也始终完整保留。单个回合积累大量工具输出后,后续请求可能持续超窗口,现有裁剪无法恢复会话。 | `toychat/context.py:56-74` | ### 4. 联网与内容安全 | 编号 | 严重度 | 验证 | 问题与影响 | 主要位置 | |---|---|---|---|---| | D1 | 高 | 代码确认 | **DNS 校验与实际连接分离,仍存在 DNS rebinding SSRF。** 安全检查时域名可解析为公网 IP,`urllib` 建连时又可重新解析为内网地址;逐跳校验不能消除每一跳内部的检查—使用竞态。应把验证后的 IP 固定到实际 socket,并保留 Host、SNI 和证书校验。 | `toychat/websearch/core.py:132-167`;`toychat/websearch/fetch/local.py:42-62` | | D2 | 高 | 已复现 | **API 请求自动跨域重定向会转发 Bearer Key。** 默认 `urllib` 重定向继承 `Authorization`,供应商接口返回跨域 301/302/303 时,Key 可能发送到另一主机,POST 还可能被改成 GET。此项通过标准库行为离线验证,未向真实服务发送请求。 | `toychat/websearch/core.py:67-81` | | D3 | 中 | 已复现 | **SSRF 地址过滤漏过 CGNAT 等非公网特殊地址。** 当前黑名单属性组合会接受 `100.64.0.0/10` 等地址,在特定路由环境可能访问非公开服务。应默认要求 `ip.is_global`,例外显式列举。 | `toychat/websearch/core.py:120-129,142-167` | | D4 | 中 | 代码确认 | **Markdown 仍允许主动样式和表单内容,存在 UI redress/钓鱼面。** 模型或被篡改的历史可返回全屏样式区块或外站凭据表单,覆盖/伪造应用界面。普通脚本和事件属性仍受 DOMPurify/CSP 防护,本次**未发现可直接执行的 JavaScript XSS**,不应把此项夸大为脚本 XSS。 | `toychat/web/static/app.js:162-167`;`toychat/web/templates/index.html:6-7`;`toychat/web/app.py:264-268` | ### 5. 交互、移动端与可访问性 | 编号 | 类型/严重度 | 验证 | 问题与改进方向 | 主要位置 | |---|---|---|---|---| | E1 | 中 | 代码确认 | **中文输入法确认候选的 Enter 会直接发送。** 键盘处理未检查 `e.isComposing`,中文/日文组字时可能提前发出未完成文本;应补 IME 键盘回归测试。 | `toychat/web/static/app.js:1881-1885` | | E2 | 中 | 代码确认 | **手机端隐藏了唯一的会话管理入口。** 宽度不超过 640px 时整个 sidebar 被隐藏,新对话、历史会话、删除和模式分区都无法使用。应改为顶栏按钮加抽屉,并处理 safe-area/动态视口。 | `toychat/web/static/style.css:685-690`;`toychat/web/templates/index.html:19-29` | | E3 | 中 | 代码确认 | **关键操作对键盘和读屏不可用。** 会话项、目录项、思考标题均为仅 click 的 div;删除和消息操作主要依赖 hover;弹窗缺少 dialog/aria 语义、焦点圈定、Escape 和焦点恢复,输入框也只有 placeholder。 | `toychat/web/static/app.js:440-447,499-517,1391-1395`;`toychat/web/static/style.css:77-89,242-250`;`toychat/web/templates/index.html:61,79-93` | | E4 | 中 | 代码确认 | **“已配置”状态不代表联网配置可用。** 就绪检查只看模型 API 三项,联网已开启但当前供应商缺 Key 时仍显示已配置,顶栏联网开关也能直接开启;应把所选供应商的必要 Key 纳入校验并提供明确引导。 | `toychat/web/app.py:435-444`;`toychat/web/static/app.js:1679-1699` | | E5 | 低 | 代码确认 | **多数数字配置非法值会静默变成默认值或边界值。** 只有 `work_max_steps` 做严格 400 校验,其他字段通过 `to_count/to_context_window` 容错,调用方无法发现拼写或范围错误。Web API 应统一严格校验,CLI 交互命令再保留容错。 | `toychat/web/app.py:490-512` | | E6 | 中 | 代码确认 | **CLI 的 API Key 输入会明文回显。** 密钥与普通配置共用 `read_line()`,应改用隐藏输入;自实现编辑器还可补充输入历史、多行编辑、粘贴及长行换行处理。 | `toychat/cli/app.py:32-45,89-103,628-640`;`toychat/cli/input_editor.py:86-179` | | E7 | 改进 | 代码确认 | **长回答渲染和自动滚动体验较差。** 流式期间虽有 50ms 节流,仍反复对完整回答执行 Markdown、消毒、公式与高亮,工作量近似 O(n²);每个增量还强制滚到底部,用户无法安静阅读旧内容。应只更新活动块、结束后统一高亮,并提供“回到底部”。 | `toychat/web/static/app.js:485-488,871-887,1135-1141` | | E8 | 改进 | 代码确认 | **草稿与 CLI 输入连续性不足。** Web 未持久化未发送草稿,刷新/断线恢复可能丢失输入;CLI 明确吞掉上下方向键且只支持单行。建议保存按会话区分的草稿,并补输入历史与多行编辑。 | `toychat/web/static/app.js:1873-1886,1910-1994`;`toychat/cli/input_editor.py:37-43,165-179` | | E9 | 改进 | 代码确认 | **设置页只有保存,没有连接验证。** Base URL、API Key、模型 ID 和联网供应商只有真正发消息时才验证,保存成功容易被理解为配置可用。应提供分项“测试连接”、超时与可读错误,并避免为测试重复计费。 | `toychat/web/static/app.js:1787-1857`;`toychat/web/app.py:458-529` | | E10 | 改进 | 代码确认 | **工作模式没有确定性的工具审批层。** “高风险操作先征得确认”仅存在于系统提示词,write/edit/bash 默认直接执行,UI 只有静态警告。应对写入、覆盖、高危命令提供参数预览和允许/拒绝,区分单次与本轮授权,并优先使用沙箱/低权限运行。 | `toychat/agent.py:39-50`;`toychat/tools/shell.py:74-88`;`toychat/web/templates/index.html:74` | ### 6. 测试自身的隔离问题 | 编号 | 严重度 | 验证 | 问题与影响 | 主要位置 | |---|---|---|---|---| | F1 | 低 | 已复现 | **`test_expanduser` 会在真实 `$HOME` 下创建目录。** 在 HOME 不可写的沙箱中,205 项无网络单测结果为 204 通过、1 失败;将 HOME 指向隔离目录后该项单独通过。测试应使用临时 HOME,并清理副作用,不能依赖开发机真实用户目录。 | `tests/unit/test_web_api.py:233-237` | ### 7. 建议修复顺序 1. **先保证停止可信、历史不丢**:A1-A3、B1-B3,并将任务结果在服务端事务性提交到会话。 2. **再封安全和数据损坏缺口**:C1-C2、D1-D3,以及所有本地工具的取消入口。 3. **补齐协议与可靠性**:Shell 退出码、按完整工具组裁剪上下文、异常轨迹保存、存储 schema/revision。 4. **最后集中处理交互**:IME、移动端、工具审批、连接测试、可访问性和长回答渲染,并补对应回归测试。 ## 🧪 测试 ```bash python3 tests/run_all.py --unit # 无网络单元测试 python3 tests/run_all.py # 含真实 API 的集成测试(少量计费) ``` 测试目录默认不入库(见 `.gitignore`);如要纳入版本管理,可取消白名单注释。 ## 📄 许可证 本项目采用 **MIT 许可证**,详见 [LICENSE](LICENSE)。 --- *—— 一个还在成长的玩具 🧸*