feat：更新readme

README.md

@@ -45,6 +45,27 @@ flowchart LR
 | 数据文件 | python-calamine、PyArrow（Parquet）、DuckDB |
 | 观测 | Loguru、Langfuse（可选） |
 
+## 记忆与上下文管理
+
+大屏是唯一的事实来源：每次请求由前端带来完整画布，记忆只保存画布上看不出来的东西，例如做过哪些修改、问答用过哪些查询。画布状态不进记忆，用户在前端手动修改或撤销后，不会出现记忆和画布不一致。
+
+| 范围 | 做法 |
+|------|------|
+| 单次运行 | Agent 在工具循环里完成任务，模型调用次数有上限（`MAX_AGENT_STEPS`、`MAX_QA_STEPS`），上下文不压缩 |
+| 同一会话 | 服务端按 `conversation_id` 读取历史，不采用前端传来的历史。最多带最近 `CONVERSATION_HISTORY_TURNS`（20）轮，再按 `HISTORY_MAX_TOKENS`（10000，o200k 计数，消息和记录合计）从最近一轮往前整轮保留；最近一轮总是保留，单独超出预算时截掉中间、保留开头和结尾 |
+| 澄清恢复 | 任务暂停时状态存入检查点，恢复后同一任务覆盖保存为一轮，追问和回答记在这一轮里 |
+| 跨会话 | 暂不做，新会话从当前画布开始 |
+
+每轮除用户原话和回复外，服务端从运行结果中记下轮次记录，不经过模型：
+
+- `changes`：交付的修改，按原始画布与交付后画布逐组件比较，记为新增、修改或删除
+- `queries`：问答中成功执行的 SQL，以及结果的列和行数，不保存结果本身
+- `clarifications`：本轮的追问和用户的回答
+
+下一轮请求时，原话和回复作为对话消息；记录作为 `history_records` 放进请求 JSON，不拼进消息。其中 `on_screen` 按当前画布计算，组件被撤销后不会被误认为还在。读取规则见 [app/prompt/domain.py](app/prompt/domain.py)。意图判断只看原话、回复和澄清，不看 SQL 和修改记录。
+
+暂不采用滚动摘要、向量检索和用户级偏好：各轮多是对可见画布的独立修改，摘要容易失真。跨会话的长期要求（如“金额统一用万元”）计划以大屏级备忘实现，待真实使用中出现需要时再做。
+
 ## 快速开始
 
 **依赖**：Python ≥ 3.11、[uv](https://docs.astral.sh/uv/)、MongoDB、支持工具调用与结构化输出的 OpenAI 兼容聊天模型服务、TypeSafe API Key。
@@ -61,7 +82,7 @@ uv run uvicorn app.main:app --host 127.0.0.1 --port 8000
 | 配置 | 说明 |
 |------|------|
 | `LLM_API_KEY` `LLM_MODEL` `LLM_BASE_URL` | 聊天模型。默认发送 `reasoning_effort=low`，服务端不支持时设 `LLM_REASONING_EFFORT=` |
-| `TYPESAFE_API_KEY` | 意图判断 |
+| `TYPESAFE_API_KEY` `TYPESAFE_DEFAULT_MODEL` | 意图判断。模型固定为 `jev-1.13.0`，阈值按该版本校准，换版本需重新评测 |
 | `MONGODB_URI` `MONGODB_DB` | 物料目录与大屏存取必需；未配置时会话与检查点退回进程内存，大屏接口返回 503 |
 | `AUTH_ENABLED` `USER_CENTER_URL` | 鉴权。本地开发设 `AUTH_ENABLED=false`；开启后请求携带 `Authorization: Bearer <token>`，服务调用用户中心 `GET /api/users/me` 校验 |
 | `LANGFUSE_TRACING_ENABLED` | 未部署 Langfuse 时设为 `false` |
@@ -187,14 +208,9 @@ skills/           大屏设计、编辑、图表替换与数据制图规则
 - **本地存储**：数据文件与封面图写入磁盘（`DATA_FILE_DIR`、`THUMBNAIL_DIR`，默认在 `data/` 下），容器部署需挂载持久卷。
 - **反向代理**：SSE 需关闭响应缓冲并放宽读取超时；上传大小限制需与 `DATA_FILE_MAX_MB` 一致。应用未配置 CORS，请通过同源代理转发 `/api`。
 - **连接中断**：客户端断开会取消当前任务，不支持心跳、事件重放或断线续传。
+- **历史计数**：会话历史用 tiktoken 的 o200k 编码表计数。Docker 镜像在构建时下载好；其他方式部署时首次请求会联网下载，离线环境需预先放入 `TIKTOKEN_CACHE_DIR`。下载失败时退回按字符估算，不影响请求。
 - **日志**：写入 `logs/app.log`。
 
 ## 开发
 
 扩展组件：修改物料定义，重新导入后重启。调整 Agent 行为：修改 [skills](skills) 与 [app/prompt](app/prompt)。新增 MCP 服务：修改 [mcp_servers.json](mcp_servers.json)，连接配置支持 `${环境变量}` 展开。
-
-测试使用标准库 `unittest`，目录 `tests/` 不在版本控制内：
-
-```sh
-uv run python -m unittest discover -s tests
-```