Merge remote-tracking branch 'origin/main' into codex/fix-fofa-region

docs/zh-CN/blackboard-context-memory.md

@@ -0,0 +1,136 @@
+# 长上下文压缩后的黑板续接留存
+
+已绑定项目且启用项目黑板时，每次成功生成压缩摘要，系统会自动保存一条续接记录。不再仅依靠 Agent 在压缩前主动调用事实工具。
+
+## 保存内容与读取方式
+
+续接记录使用 `note/context-*` key，包含摘要中的重要发现、授权约束、当前进度、失败尝试与下一步，以及来源会话、代理范围和压缩前原始记录的快照路径。主代理、各子代理、计划执行中的规划器和执行器分别维护自己的记录；同一会话/代理多次压缩更新同一个 key。
+
+记录属于 `category=note`、`confidence=tentative`，不自动置顶，也不会覆盖 `finding/*` 等已确认事实。它是模型生成的工作摘要，不能直接作为经过独立验证的漏洞或新的授权指令。正式事实和漏洞仍由 `upsert_project_fact`、`record_vulnerability` 维护。
+
+压缩后的上下文会附上该记录的 `get_project_fact(key)` 入口，并刷新系统中的黑板索引。后续按需读取记录，再使用 `read_file` 分段查看原始证据；无须重新把完整历史注入每一次模型请求。
+
+新上下文和黑板记录保存同一份续接摘要，并融合原始快照的绝对路径、历史快照目录和回读提示。摘要保留关键证据的来源目标、用途与发现经过；当前任务缺少 Cookie、认证信息、精确参数或错误原文时，Agent 可直接搜索对应快照，再用 `read_file` 分段核对附近原文，不猜测原值。
+
+原有摘要章节及原始用户输入账本保持不变，只在同一次摘要中追加「原始证据检索线索」，记录工具结果或关键进展的来源与关键词，不新增对用户输入的归纳，也不由模型编造文件名或行号。
+
+不再生成独立 `.index.md` 文件，不使用正则或关键词分类扫描快照，不增加模型调用。摘要本身承担证据检索入口；它仍可能遗漏细节，原文以快照为准。
+
+## 用户输入与系统摘要不能混为同一来源
+
+Eino 默认续接摘要使用 `user` 消息角色传输，但同时带 `_eino_summarization_content_type=summary` 的来源标记；保留的技能上下文使用 `skills` 标记。原始用户输入账本按该元数据排除内部摘要和技能消息，不能仅凭 `role=user` 将生成内容归入用户原文。摘要中的模拟用户账本也不作为原始输入来源导入，避免多轮压缩把模型自己写的目标或操作提升为用户指令。快照和摘要模型的文本记录同时标出内部消息的系统生成来源，明确其不是用户输入或新的授权。
+
+用户账本的延续优先读取系统消息内的结构化来源元数据，不再从普通助手或工具响应中提取同名文本标签。JSON 检查点恢复、classic/native 转换和系统消息合并均保留这份来源；兼容旧版本时，仅接受系统消息尾部完整的宿主账本区块，不导入嵌在黑板或响应中的片段。
+
+压缩摘要仍保留在模型工作上下文中，不因来源区分而丢弃进展；主/子代理本轮输入仍来自原始请求及原始聊天记录。不会用 `<summary>` 等文本关键词过滤真正的用户输入。回归测试调用实际 `DefaultFinalize`、连续执行三轮压缩并经过 classic/native 转换，核对原始授权目标与禁止测试本机的约束保留、生成目标与模拟指令不进入用户账本、摘要进展不丢失，以及用户引用摘要文本时仍被视为真正用户输入。
+
+## 会话工作记录与项目共享事实的读取边界
+
+设计依据是区分会话状态和跨会话记忆，而非把每次自动摘要直接视为共享事实。[LangChain 官方记忆概念文档](https://docs.langchain.com/oss/python/concepts/memory) 将工作状态定义为 thread-scoped，跨会话记忆使用独立 namespace；本项目保留现有项目事实结构，用保留前缀 `note/context-*` 与来源会话标识建立相应读取范围，不增加数据库迁移或额外模型提取。
+
+| 内容 | 自动注入与默认事实工具 | 显式历史查询 |
+|---|---|---|
+| 普通项目事实（含已确认发现、手工 note） | 沿用原有项目共享行为 | 沿用原有行为 |
+| 当前会话的自动续接记录（含该会话子代理/规划器/执行器） | 可见，标为当前会话工作记录 | 可见 |
+| 同项目其他会话的自动续接记录 | 不自动注入，列表/搜索默认不返回，直接 get 要求历史标志 | `include_history=true` 可读，标为历史参考 |
+| 缺少来源会话的旧续接记录 | 不作为当前工作记录返回 | 显式历史查询可读，标明未知来源 |
+| 其他项目的记录 | 当前项目工具不可读 | 历史标志不能扩大项目范围或绕过 project:read |
+
+`list_project_facts`、`search_project_facts` 与 `get_project_fact` 默认使用当前会话范围；前两者支持 `source_conversation_id` 缩小查询。过滤在数据库分页前执行，避免置顶历史记录占满一页后才被丢弃。初始主 Agent 注入、子 Agent 黑板补充以及普通/原生压缩后的索引刷新，都显式传入当前会话 ID；缺少会话 ID 时不会退回注入全部自动续接记录。
+
+关系速览、索引行内关系提示以及 get/upsert 的关系边返回同样过滤其他会话的自动续接 key，防止通过关系边绕过默认范围。事实 body 的「关联」镜像段由 `get_project_fact` 原样返回、没有按读取方过滤，因此该段不写入任何自动续接 key；结构化关系边仍按调用方范围返回，本会话自己的续接记录不会因此消失。历史正文附来源会话和更新时间，不因读取自动升级为已确认事实或新的任务授权。`note/context-*` 为系统保留前缀，事实写入工具与控制台的事实新建/改写接口都不能创建、覆盖或把普通事实改名进该前缀（续接记录只由压缩流程写入）；废弃/恢复工具不能修改其他会话的自动续接记录。核实后的项目知识应另写独立事实 key 并保留证据。
+
+这属于上下文注入和事实检索的默认范围，不是新的文件访问权限隔离；不删除快照、不修改既有记录，也不清洗已进入旧对话历史的内容。项目管理页面及原有不带范围参数的数据库查询仍可供有权用户查看项目全量数据。现有项目权限继续由工具授权层核验。
+
+验证使用同项目两会话、另一个项目及未知来源旧记录：覆盖默认/显式查询、来源筛选、分页、置顶历史记录、关系边、保留 key 写保护、权限拒绝、初始主 Agent 注入，以及真实 classic/native 压缩自动保存后的索引刷新。已有黑板预算与原始用户账本测试继续运行，确保范围标识不突破长度上限、不更改用户输入。
+
+## 原始证据不会随下一次压缩被覆盖
+
+过去所有压缩轮次写入同一个 `transcript.txt`，后一次写入会覆盖前一次记录。现在每份压缩前历史保存到 `snapshots/transcript-<MD5前5位>-<时间戳>.txt`，例如 `transcript-a1b2c-20261012-010203.000000004+0800.txt`。时间戳带纳秒与时区，记录首次保存时间；相同内容的重试通过完整文件内容核对复用快照，不改变原快照的时间或路径。短 MD5 仅用于识别，不用作唯一性判断；前缀或时间戳碰撞时不覆盖旧文件。旧 SHA-256 文件名保持可读且可复用，不改名以免旧摘要的引用失效。`transcript.txt` 仍保留为最新记录的兼容入口，续接摘要引用的是具体快照。快照沿用现有会话记录格式，保留用户、助手与工具记录，省略不变的系统提示与工具/技能索引。
+
+快照沿用 `conversation_artifacts/<conversationId>/summarization/` 目录，与会话产物一起管理；子代理使用独立 scope 子目录。删除会话时现有清理逻辑会删除对应产物，快照不作为会话删除后的独立备份。文件通过临时文件原子替换写入，权限为 0600。
+
+默认数据库为 `data/conversations.db` 时，主代理文件布局如下（摘要向 Agent 提供绝对路径）：
+
+```text
+data/conversation_artifacts/<conversationId>/summarization/
+├── transcript.txt
+└── snapshots/
+    └── transcript-<MD5前5位>-<时间戳>.txt
+```
+
+可按文件名中的时间排序判断快照先后。快照可能在生成摘要前保存，包括失败尝试；相同历史的重试复用文件，因此文件序号不严格等同于成功压缩次数。
+
+数据库路径为空时，临时快照也使用 `<临时目录>/cyberstrike-summarization/<conversationId>/summarization/snapshots/`，不会退回多个会话共用一个目录。
+
+子代理、规划器和执行器使用 `summarization/scopes/<scopeHash>/snapshots/`。摘要提供历史快照目录，Agent 可用 `glob` 查找 `transcript-*.txt`，按需回读更早证据。已有旧索引文件不参与新流程，也不会在升级时被自动删除。
+
+系统复用本次已经生成的压缩摘要，不增加一次额外的模型提取调用。原始历史在生成摘要前就做快照，因此即使摘要遗漏某个精确细节，也还有来源可以追溯。黑板或快照保存失败时会记录告警，保留当前可用摘要继续运行，不提示保存成功。
+
+## 配置和边界
+
+```yaml
+project:
+  enabled: true
+  context_checkpoints: true
+```
+
+`context_checkpoints` 省略时默认开启；设置为 false 可关闭自动黑板续接记录，不影响原始证据快照。没有绑定项目的会话仍保留本地快照，但不会把内容写进其他项目。
+
+自动记录前会核对会话当前绑定的项目，并在实际 SQLite upsert 的同一条写入语句中再次核验绑定，避免检查与写入之间切换项目造成旧运行写入旧项目。绑定不匹配时不新增行，也不改写已有记录。这里没有增加跨项目搜索。现有项目黑板权限与事实工具的当前会话范围继续适用。
+
+自动记录只在压缩触发时落库，不能代替每次新发现后的即时事实登记。摘要仍可能遗漏细节；具体原文以快照为准。快照累计占用本地存储，保留到对应会话产物被清理。
+
+## 索引预算与来源区分
+
+自动注入仍只包含 key、短摘要与关系边，完整 body 留在数据库按需读取。索引查询不再加载最终不会注入的 body。字符预算现在包含标题、起止标记、查询提示、遗漏说明和关系速览；特别小的预算会使用简短查询提示或不注入索引，不截断 HTML 边界。
+
+黑板不需要再次调用模型压缩：同一会话/代理的自动续接正文更新为本次摘要，短标签最多 200 字符，不自动注入完整正文或原始快照。读取入口只附在续接摘要与黑板正文中，不复制完整历史，也不维护额外的证据类别索引。历史原文保留在文件中，已确认事实不因续接记录更新而被改写。
+
+快照写入失败时，不注入框架默认的 `transcript.txt` 路径提示，避免 Agent 读取不存在或属于上一轮的文件。普通文本、带 `<summary>` 标签的文本与多段消息均保留同一读取入口，避免正文重复附加。
+
+遗留超长 summary 在展示索引时缩短为单行，库中的完整 summary/body 不改动。索引行的 category 与 confidence 同样只取单行：两者入库时只补默认值、不做校验，含换行就能往系统提示的索引里插入伪造行。关系速览仅使用实际列入索引的事实，避免预算外事实继续通过路径视图占用上下文；索引为空时关系速览也为空，不因集合为空而放开过滤。置顶与事实类型的原有优先级保持不变。
+
+## 实现依据与验证
+
+Eino 的压缩流程支持在 `Finalize` 中处理摘要并重写上下文，`Callback` 在后处理之后触发；本项目在既有自定义 Finalize 中落库、附上快照引用，然后更新索引。普通消息与原生 AgenticMessage 路径均使用同一留存函数。[Eino Summarization 文档](https://www.cloudwego.io/docs/eino/core_modules/eino_adk/eino_adk_chatmodelagentmiddleware/middleware_summarization/)
+
+回归覆盖多次压缩保留早期证据、重复快照幂等、原子文件权限、主/子代理记录隔离、已确认事实保持不变、配置关闭、项目不匹配、保存失败不宣称成功、多段文本摘要、普通与原生中间件自动落库/刷新，以及索引硬预算和正文不注入。
+
+## 追加代码审查验证
+
+本轮进一步修复工具/助手文本伪装原始用户账本、无数据库路径时临时目录混用，以及项目绑定检查/写入竞态。回归覆盖工具与助手伪造标签、系统黑板嵌入片段、结构化来源 JSON 恢复及系统归一化、错误来源元数据拒绝、classic/native 无数据库路径的独立会话目录，以及切换/解绑项目时拒绝新增和更新且已有证据不变。该改动不迁移或改写历史快照，生产更新应与本轮代码验证结果对应。
+
+## 恢复链路与边界回归
+
+代理轨迹恢复统一通过同一解析器处理，只携带已知的 `summary` / `skills` 来源标记与系统消息中的结构化原始用户账本。`agent.ChatMessage` 以运行时字段传递这些信息，普通模型请求 JSON 不包含内部元数据；轨迹专用序列化保留允许的来源字段。恢复时不重放旧系统提示，仅按当前预算重新渲染宿主账本；经典及原生模型调用入口合并系统消息时继续保留结构化来源，且兼容文本不能覆盖已有结构化账本；普通用户引用摘要或标签仍作为用户原文。多段文本摘要恢复后继续保留工作进展与来源标记。测试使用生产相同的中文 ADK 设置，覆盖实际数据库加载和三轮「压缩→持久化→恢复→再次压缩」，包含 classic/native 转换。修复不能补回旧轨迹中已经丢失的来源信息，不改写历史记录。
+
+不可变快照成功后，即使更新 `transcript.txt` 兼容入口失败，摘要及黑板仍保留成功快照的路径；日志单独报告兼容入口故障。快照本身失败时仍不宣称保存成功。
+
+事实 key 的写入校验拒绝首尾空白，默认 SQL 范围过滤兼容已有 key 的 Unicode 空白，与 Go 判断一致；读取不会批量改名或迁移旧记录。索引成功构建为空时会移除旧索引块，其他系统内容及用户账本保持；数据库读取失败时继续保留原索引。
+
+黑板短标签优先使用第 8 节中已经生成的证据检索线索；没有可用线索则沿用原先的标签取法。只更改索引标签，不改摘要第 1–7 节、完整正文或原始用户账本，不增加模型调用。新增 `Context memory` CI 在 macOS、Ubuntu、Windows 上直接运行 agent/attackchain/app/database/handler/multiagent/project/projectprompt 的并发回归测试；Windows 不检查其文件系统不支持的 Unix 权限位。
+
+## 发布前场景验收
+
+计划执行和重新规划的用户角色消息是系统生成模板，包含计划与模型/工具结果，不等于用户新输入。模板使用独立的允许列表来源字段，生成前从未拼接的原始消息保存受限用户账本，再进入重写/压缩；角色与来源也保留在输入文本和快照中。恢复轨迹及框架的用户消息区块不会把模板内容归入用户原文，模板中的工作进展仍保留给模型使用。普通用户引用计划或摘要文字继续作为真实输入处理。
+
+上下文超限或临时故障重新启动时，移除旧指令与索引，但保留并按当前预算重建结构化原始用户账本。首条长输入的预算计算包含编号、分隔符和省略号，避免有空间却整条丢弃；只保留原文的受限片段，不增加用户输入的模型摘要。预算仍不能保存无限原文，精确细节按需回读快照。
+
+已有首尾空白 key 的事实可按原 ID、项目和完整 key 更新摘要/正文，不改名、不修改历史关系引用；新建及更改为非规范 key 仍被拒绝。真实 HTTP 部分更新回归覆盖这一兼容路径。
+
+验收还覆盖长工具输出先保存为原文文件、压缩与恢复后从快照获得文件引用，再通过 read_file 后端分段回读精确 Cookie。合成 Cookie 放在 2001 行输出的中间，不出现在截断预览或摘要中；classic/native 两种路径均可完整恢复。这里只保证证据与读取入口可用，模型是否主动回读取决于任务与模型行为。
+
+聊天输入、审批交互和 API 路由沿用原流程。新增可见内容是自动续接记录、简短读取提示和攻击链侧栏的摘要入口；同项目其他会话的自动工作记录默认不注入，普通共享事实与手工 note 保持原有读取方式。本地快照随不同压缩内容累计，沿用会话产物删除生命周期。
+
+## 攻击链中的摘要与证据线索
+
+攻击链分析输入根据持久化的来源元数据，分别标明真实用户输入、宿主保留的原始用户账本、系统生成摘要、技能上下文和执行模板。生成摘要和模板只是工作线索，不构成新的用户授权，也不能独立证明漏洞或工具执行；节点仍须以实际工具记录为依据。用户自己引用摘要文字时继续作为真实用户输入，不根据正文关键词判定来源。
+
+「以实际工具记录为依据」由程序判定，不只写在提示词里。`action` 与 `vulnerability` 节点可带 `tool_call_id`，取值须逐字来自轨迹中宿主签发的调用 ID；引用了轨迹里不存在的 ID 即判为编造，节点连同指向它的边一起丢弃，`target` 节点不参与判定。是否强制「必须引用」取决于模型当时看不看得到 ID：预算裁剪后全部真实 ID 仍可见时，留空同样丢弃；有 ID 被裁掉时，留空只算无法对应、不算编造。多代理补充的过程详情原样转储事件 JSON，其 ID 不在解析后的轨迹内，此时与 `messages` 表回退分支一样跳过判定，避免误杀真实节点。通过校验的引用写入节点 `metadata.tool_call_id`；不写 `attack_chain_nodes.tool_execution_id`，该列有指向 `tool_executions` 的外键，而模型引用的是调用 ID。
+
+攻击链侧栏提供可展开的「压缩摘要与证据线索」，显示当前会话轨迹中带摘要来源标记的完整正文，保留其中的不可变快照路径，并可复制正文按路径核对原文。读取已有缓存攻击链时也会返回当前轨迹中的摘要，不需要重新生成节点才能查看。摘要单独展示，不变成图中的攻击节点，不改变节点统计、筛选或图导出。没有工具执行的会话可展示摘要而保持空图。
+
+该入口只读取当前会话的代理轨迹，不从项目共享黑板汇总其他会话，不增加快照文件下载或任意文件读取接口。旧轨迹缺少来源元数据时不猜测其摘要身份；已被后续压缩移出轨迹的旧摘要仍按快照目录回溯。更新代码不会重写旧缓存节点；需要使用新的来源标注重新分析攻击链时，点击「重新生成」。
+
+攻击链请求按会话和请求顺序丢弃迟到响应；切换、关闭和错误时清理旧摘要，避免旧内容覆盖新视图。并发重新生成的忙碌请求返回 409 前不再删除缓存图；缓存图的空节点和边统一返回数组，单节点无边也可正常展示。回归覆盖真实模型 HTTP 请求输入、当前会话与同项目其他会话隔离、缓存摘要更新/清空、摘要中的 HTML 仅作为文本、复制与失败回退，以及跨会话和同会话请求乱序。

docs/zh-CN/configuration.md

@@ -256,12 +256,15 @@ c2:
   enabled: true
 project:
   enabled: true
+  context_checkpoints: true
+  # 续接补充包含在事实索引预算内；工作文件候选清单另有最多 4000 字符预算
   fact_index_max_runes: 65000
 ```
 
 - `c2.enabled`：关闭后不启动 C2 监听器，也不注册 C2 MCP 工具。
 - WebShell 连接配置存 SQLite，没有单独的主配置开关。
-- `project` 控制跨对话事实黑板注入预算。
+- `project` 控制跨对话事实黑板注入预算。[项目续聊与成果复用](project-resume.md) 说明脚本登记、测试结果与续接流程。
+- `project.context_checkpoints` 默认开启：已绑定项目的会话成功压缩时，将续接摘要自动保存为 `note/context-*`（tentative），按会话及主/子代理分别更新，不覆盖已确认事实。完整原始记录保存为不可变快照，后续可通过 `get_project_fact` 与 `read_file` 找回。关闭此项仅停止自动黑板记录，仍保留原始上下文快照。详见 [长上下文续接留存](blackboard-context-memory.md)。
 
 ## 机器人
 

docs/zh-CN/project-resume.md

@@ -0,0 +1,46 @@
+# 项目续聊与成果复用
+
+同一项目第二天继续任务时，应先恢复已有成果，再执行新的工作。仅保留聊天摘要不足以恢复脚本参数、依赖、成功证据和已经验证过的失败路线。
+
+## 自动恢复的内容
+
+每轮用户任务都从当前数据库和磁盘重新构建上下文，单代理和多代理共用此入口：
+
+- 项目事实索引与测试范围。先通读索引；存在省略时，使用 `list_project_facts` 分页补全索引，再读取与本次任务有关的事实正文。
+- 脚本与测试记录：`artifact/*`、`test/*`、`negative/*`，以及兼容既有的 `exploit/*`、`poc/*`。脚本和测试记录分别最多展示 3 条正文预览，避免其中一类挤掉另一类；预览不代替 `get_project_fact` 返回的完整正文。
+- 项目关联漏洞的 ID、标题、目标和状态，包括已修复、误报等状态；详情使用 `get_vulnerability`，其余使用 `list_vulnerabilities` 分页/筛选。没有事实的项目也会恢复已有漏洞。
+- 工作目录内的脚本候选文件路径、大小和修改时间。清单不会读取或执行脚本，也不将“文件存在”当作“验证成功”。先检查 `artifacts/`，再查找其他位置；执行前仍需读取文件并核对事实记录。
+
+项目续接补充内容置于事实索引的刷新边界内，因此摘要压缩后的索引刷新以及多代理任务上下文补充都会带上最新的数据库记录。磁盘文件清单在每轮用户任务开始时重建。
+
+## 成果如何保存
+
+已绑定项目的会话共用 `<agent.workspace_root_dir>/projects/<project_id>/`；未绑定项目的会话使用各自的 `conversations/<conversation_id>/`。在同一项目创建新会话或重新打开原对话，都能访问该项目已有的工作文件。
+
+成功脚本和依赖建议放在项目工作目录的 `artifacts/` 下。完成验证后立即使用现有的 `upsert_project_fact` 工具登记：
+
+- `category=note`、`fact_key=artifact/<稳定名称>`。
+- summary 标明用途与验证状态。
+- body 记录相对文件路径、目标和适用条件、调用方式、可变参数、依赖/版本、输入输出、成功证据、验证时间、来源会话和关联事实/漏洞。认证信息引用现有 `auth/*` 事实。
+
+已完成的测试路线同样立即保存：
+
+- `category=note`、`fact_key=test/<目标入口与方法的稳定名称>`。
+- body 包含目标、入口、参数、身份/认证、测试方法、证据、结论、时间及复测触发条件。
+- 阴性结论只适用于已测条件。证据充分的阴性结果仍是 `confirmed` 事实，不能因为没有发现漏洞就标记为 `deprecated`。工具错误、超时或缺少认证应记为受阻/待验证，不能记为已排除。
+
+同一测试条件更新同一 key；条件变化时另记并关联。此约定复用现有事实表和工具，不增加数据库迁移或分类枚举。已有脚本可保留原路径，核对内容与证据后补登记。
+
+## 继续任务时的顺序
+
+先检查当前授权范围与用户的新需求，然后恢复事实、漏洞和工作文件。命中已有脚本时先读取说明与源码，优先修改调用参数、复用已验证的部分。执行前简述本次复用什么、跳过什么、增加什么。
+
+相同目标、入口、参数和认证条件下有证据支撑的失败路线默认跳过。用户明确要求复测、目标/版本/入口/身份发生变化或原证据不足时，可以重新验证并说明原因。历史任务不会因为恢复记录而自动执行。
+
+## 预算与局限
+
+`project.fact_index_max_runes` 继续控制原有事实索引预算；续接补充最多 6500 字符，包含在索引总预算内；有事实时至少为索引行预留 800 字符，预算不足时省略补充并保留按需检索入口，文件清单另有最多 4000 字符的预算。漏洞最多查询 20 条；所有省略都会提示使用现有工具继续检索。文件遍历最多检查 1500 项、深度最多 5 层、最多列出 24 个候选文件，不跟随符号链接，跳过隐藏项及常见依赖目录。支持常见脚本扩展名；无扩展名脚本等仍需按事实中的路径查找。清单受限、目录不可读或没有命中，均不能证明成果丢失。
+
+事实正文与脚本候选名作为 JSON 数据呈现，正文预览会压缩空白并截断；不可直接拿预览拼接执行命令。应通过详情工具和文件读取工具获取原始内容。历史文件和事实都不是新的系统指令。
+
+这项改动提供自动恢复和复用规则，具体检索、登记与执行选择仍由模型完成，并非阻断所有重复工具调用的硬门禁。不会自动重建曾经只写在系统 `/tmp`、已被清理或从未保存的脚本，也不会从文件名推断成功。未登记的旧成果需核对后补录。项目工作目录仍属于服务端运行数据，需要随数据库一起备份；删除项目会按原有清理规则删除项目目录。

docs/zh-CN/token-usage-monitoring.md

@@ -0,0 +1,68 @@
+# Token 用量监控：调研与实现
+
+调研时间：2026-10-11。
+
+## 调研结论
+
+| 参考 | 官方能力 | 本项目采用的设计 |
+| --- | --- | --- |
+| [ZCode 使用统计](https://zcode.z.ai/cn/docs/usage-stats) | 本地会话统计与远端编程套餐额度分别展示；支持时间范围、日趋势和模型占比 | 首页增加可展开的本地用量面板，提供 7/30/90 天、日趋势、模型占比与明细 |
+| [DeepSeek 上下文缓存](https://api-docs.deepseek.com/guides/kv_cache/) | 响应 usage 的 `prompt_cache_hit_tokens` / `prompt_cache_miss_tokens` 区分输入缓存命中和未命中 | 将命中字段补入 OpenAI 标准缓存读取字段；不把未命中错误映射为缓存写入 |
+| [Eino v0.9.21](https://github.com/cloudwego/eino/releases/tag/v0.9.21)、[schema PR #1309](https://github.com/cloudwego/eino/pull/1309) | 稳定版新增 `PromptTokenDetails.CacheWriteTokens`，原有缓存读取、输入、输出、推理字段继续保留 | 使用稳定版的标准字段贯穿流式归并、运行汇总、数据库和 UI |
+| [Eino-ext PR #1015](https://github.com/cloudwego/eino-ext/pull/1015) | 模型适配器传递缓存写入计数 | 升级 agenticclaude 0.1.7、agenticopenai 0.2.4 与对应 OpenAI ACL，而非仅升级框架 |
+| [Eino 回调与 Trace](https://www.cloudwego.io/docs/eino/quick_start/chapter_06_callback_and_trace/) | 组件回调可收集模型生命周期、用量与耗时 | 保留现有运行事件采集；未来要覆盖所有内部调用，应另外设计统一模型调用账本 |
+
+版本已通过 Go module 解析和本地源码确认；未采用 0.10 alpha。DeepSeek 原始字段当前不会自动进入 Eino 的标准缓存读取计数，因此在项目现有兼容 HTTP 层补齐，覆盖普通 JSON 和 SSE 流式响应。已有标准 `cached_tokens` 优先，未知字段使用 RawMessage 保存，避免浮点转换损失数字精度。
+
+## 统计口径
+
+- `promptTokens`：模型返回的全部输入。
+- `completionTokens`：全部输出，包括供应商计入其中的推理。
+- `totalTokens`：使用供应商的总量；缺省时由输入加输出补齐。
+- `cachedTokens`：输入中的缓存读取部分。
+- `cacheWriteTokens`：输入中的缓存写入部分。
+- `reasoningTokens`：输出中的推理部分。
+- 缓存读取、写入、推理都是细分，不能再加到总量。缓存读取占输入的比例为 `cachedTokens / promptTokens`；没有输入时显示破折号。
+- 一个流式模型输出可能多次返回累计计数，沿用按字段取最大值的归并方式，整条输出结束后只加入一次运行汇总。部分输出发生错误时，仍可保留已返回用量。
+
+DeepSeek 的未命中输入不等于 Claude 的缓存写入。不能根据文本长度推导账单级计数，也不能根据缺失字段断言供应商未使用缓存。旧记录的新增字段默认为 0，表示未记录该细分。
+
+## 功能入口与数据流
+
+点击首页「Token 用量」卡片进入「系统设置 → Token 用量」，也可直接从设置二级菜单打开。首页卡片显示近 7 天总用量，副标仅显示缓存命中率（缓存读取 Token / 输入 Token），调用次数和每日用量保留在详情页。支持当前项目范围、7/30/90 天切换、八项指标、最多 20 项运行模型排行、每日趋势与完整日明细、最多 20 项最近运行。详情页独立加载，支持手动刷新与请求取消，切换周期不会刷新整个仪表盘；刷新页面可保持该设置分区。
+
+详情页采用四项核心指标（总量、输入、输出、缓存读取占输入）与四项次级指标（调用、缓存读取、缓存写入、推理）的层级布局。趋势可切换总 Token、模型调用与缓存命中率，鼠标悬停或键盘聚焦柱形可查看日期与精确数字；切换图表指标不再请求 API。缓存环形图拆分缓存读取与其余输入，不把缓存或推理再次叠加到总量。模型明细展示占比条，每日数字明细默认折叠，最近运行区分完整与部分记录。统计口径可展开查看。
+
+每日图表沿用 API 返回的服务端日期，只补齐已返回日期之间无记录的空档，不根据浏览器时区猜测查询终点。小屏图表和宽表在自己的区域内横向滚动。没有记录和无法获取统计分别展示空状态与不可用状态。
+
+### UI 调研依据（2026-10-12）
+
+| 参考 | 采用的设计 |
+| --- | --- |
+| [DeepSeek Context Caching](https://api-docs.deepseek.com/guides/kv_cache/) | 使用其明确的缓存命中/未命中输入定义，设计缓存构成视图；比例按 Token 而非请求次数计算 |
+| [LiteLLM Usage](https://docs.litellm.ai/docs/proxy/ui/chat_ui) | 周期选择、核心统计与使用日志分层；本项目保留已有数据范围，不新增无法准确计量的费用或成功率 |
+| [Langfuse Custom Dashboards](https://langfuse.com/docs/metrics/features/custom-dashboards) | 将汇总、时间趋势、模型分布拆为独立可读区域，并让趋势指标可切换 |
+
+DeepSeek 和 GLM 控制台的完整页面本轮未能公开读取，因此本轮视觉设计以能核实的开源面板为依据。没有声称复刻它们当前登录后的界面。项目也没有新增供应商账单、预算或节省金额推算。
+
+运行事件 → 流式/非流式用量累加 → `eino_usage_summary` → `process_details` 与 `model_token_usage` → 现有 `/api/usage/tokens`、对话用量接口 → 首页与聊天摘要。
+
+新增 `model_token_usage.cache_write_tokens INTEGER NOT NULL DEFAULT 0`。启动时现有声明式 SQLite schema reconciliation 自动补列；旧数据库无需手工执行迁移。现有事件 ID 幂等写入、外键删除关联和历史回填继续生效。日分组按服务本地时区显示，与首页「今日」边界一致。
+
+面板采用文本节点渲染供应商模型名称，表格在手机上局部横向滚动，提供中文、英文、俄文标签。聊天轮次 tooltip、主对话与 WebShell 时间线均增加缓存写入字段。
+
+## 当前边界与后续方向
+
+统计基于已记录的 Agent 输出事件，包括已有采集链路中的子 Agent，**不是全站 API 请求账本**。摘要压缩、检索 embedding、隐藏的模型调用、没有返回 usage 的请求不能由当前链路完整覆盖；因请求取消丢失最终 usage 的消耗也无法还原。
+
+模型排行按运行配置的模型名称归类，发生 failover 的运行可能混合多个模型，不能据此核算逐模型账单。近期列表每项是运行汇总，不是单次 HTTP 请求；模型调用次数也仅统计返回了非空 usage 的输出。
+
+本次不展示费用或套餐剩余额度。自定义中转渠道和订阅套餐的价格、计费方式不同，token 乘固定单价无法可靠代表费用。下一步如需要完整成本管理，应先建设按请求记录的账本：调用来源、真实供应商与模型、成功/错误/取消、耗时、TTFT、usage 是否返回、价格版本和币种；统一覆盖主/子 Agent、压缩、重试、embedding，单独对接供应商额度接口。
+
+## 验证
+
+- `go test ./...`：全仓通过。
+- `node --test web/static/js/*.test.cjs`：295 项通过。
+- 针对缓存写入的保存/分组/近期记录、旧 schema 补列、用户可见范围、流式去重和总量回退添加回归测试。
+- DeepSeek 普通 JSON/SSE 的缓存字段转换、标准字段优先、错误/终止块保持、超大数值精度验证通过。
+- 浏览器使用合成数据验证桌面、390px 手机、深色模式、模型名称转义、空数据与接口不可用状态；没有读取真实运行数据库，也没有调用付费模型。