# 实施进度

> 配合 `DESIGN.md`。本文件只记 phase 状态、决策偏差、文件量、下一步。每条 1-2 句:做了啥 + 关键判断;细节查 `git log` / `git diff` / `DESIGN §7.9`。

最后更新:2026-07-20(加 glm.pro52 空响应定层探针,交生产跑,bump 0.58.48)

---

## 状态

| Phase | 标题 | 状态 | 备注 |
|---|---|---|---|
| 1-3 | 骨架 + Skill + run_python | ✅ | 多 skill(coding/proposal/ppt/research/documents/imagegen/videogen/review/patent);CoreCoder 唯一匹配 edit;敏感 env 过滤 |
| 4 | 演化性能力 | 🟡 | Model Profile + Probing ✅;版本化 prompt 未做 |
| 5 | Eval Suite | ⏸ 不做 | dogfooding 替代,probe 覆盖健康检查 |
| 6 | 长任务工程化 | 🟡 | task + 恢复 ✅;双层记忆 ✅;context 压缩 ✅(加压力门槛);长会话中段折叠摘要 ✅(§8.8 Phase 2) |
| 7 | 打磨 | ❌ | Docker 沙盒 / 更多 skill |
| §7 SaaS | DESIGN §7 路线 | 🟡 | A 事件流化 ✅;B 完工 ✅;D `/v1` JSON API ✅;D' 过渡 auth + dev SPA ✅;单活 run 锁 + cancel ✅;0004 schema 瘦身 ✅;入口归位 ✅;真 OIDC 待;**C Step 1-3 + 3d ✅(Executor + Docker 池 + DockerExecutor + fs 工具进容器)+ Step 5 部署前置对账 ✅ + 容器资源 yaml + 应用层磁盘配额 ✅ + dogfood 网络放开 + 容器内 pip/npm 源持久化 ✅**;**Step 4 完整 egress proxy + Step 3b PGID kill 协议延后到外部用户开放前**(还需 egress proxy + xfs project quota OS 层硬化,§7.5 落地清单 #2 #4)。 |

---

## 已完成关键能力

### 2026-07

- **07-20 / 0.58.48 / glm.pro52 空响应定层探针**:失败面板 empty 簇(15)主角从 opus48 换成 `glm.pro52`(11/15)。加 `scripts/diag_glm_empty_probe.py`——`build_agent(resume=True)` 复原真实 system prompt + 全工具 schema + **完整多轮上下文**(空响应发生在深层,单条 user 消息复现不了,这是与 2a1bc25d narrated 探针的关键差别),打 glm.pro52,三态判定 EMPTY(真吐空)/NARRATED(工具意图漏成正文)/STRUCTURED。默认锁 task 35744bea(近7天 empty 5 次最可复现)。本机 import litellm 卡 ~20min,交生产机 `.venv/Scripts/python.exe scripts/diag_glm_empty_probe.py` 跑,输出写 `scripts/_glm_empty_probe_*.txt`。定层后再决处置。
- **07-20 / 0.58.47 / 工具失败面板 6 簇巡检 + svg 质量门签名诚实化**:扫近7天失败聚集逐簇定根因。①**write/edit malformed(45/32)**=100% DeepSeek v4 wire 把并行 tool_call 的 arguments 拼成 `{...}{...}`,salvage(0.58.24)复盘提前到 07-20:命中率稳 ~85%(post-launch salvaged 252/malformed 44)、残差涉事 task 全在跑无终态失败=落非流式重试自愈,**决策保持现状不再写代码**(面板绝对数被上线前 07-13/14 尾巴撑高,要看 salvaged/malformed 比)。②**shell/exit "Font issues"(20)**=`svg_quality_checker` 质量门按设计 exit-1,但 `toolfail._classify` 取 `[exit]` 前尾行当签名,而尾行永远是通用 tip「4. Font issues:…」→ 所有门失败(typography/alignment/spec_lock drift)误标成 Font issues 误导排查。修:checker 在 errors>0 时末尾多打确定性 `gate_verdict_line()`「[GATE FAIL] svg_quality_checker: N error file(s) / M total; top issues: …」作为最后一行 stdout(放 main() 里 export 之后),toolfail 现有取尾行逻辑自动拾取诚实签名、toolfail 零改动;`_categorize_issue` 加 `spec_lock/typography` 类避免真错落 "Other"。补 3 测试(GateVerdictLineTests),39+3 全绿。③**run_python 预检(31)**=pysyntax 按设计拦中文正文硬拼进 .py(引号/缩进崩),非平台 bug=提示词治理待办。④**empty(15)**=主角换成 `glm.pro52`(11/15,非旧 opus48 案),需生产跑 narrated 探针定层(本机 import litellm 卡,task e7c2f50b 备用)。⑤**web_fetch(6)**=外部 403 拒抓为主,非平台锅。
- **07-20 / 0.58.45 / glob 绝对路径崩溃(工具失败聚集 #2)**:巡检近7天工具失败聚集,`glob` 排第2(3次/3task/3用户、近24h 仍在发)。根因:`tools/fs.py` GlobTool 直接 `base.glob(pattern)`,模型传绝对 pattern(沙箱 cwd 就是 `/workspace`,自然写 `/workspace/**/*.py`)时 pathlib 抛 `NotImplementedError: Non-relative patterns are unsupported`,整个调用崩返 `[Error executing glob]`。改:绝对 pattern 先 `_split_abs_glob` 拆成「存在的静态前缀目录 + 相对 glob 串」(左起吃掉不含 `*?[` 的组件当 base)再匹配;补首字符 `/`\`\\` 判定(POSIX 前导斜杠在 Windows 宿主 `is_absolute()` 为 False,沙箱是 Linux,两处对齐)。顺手删掉原 `if "**"`/`else` 两分支代码完全相同的死重构。`/sandbox/tools/` 是 Dockerfile `COPY tools/` 拷贝,**需重建沙箱镜像**才生效。
- **07-20 / 0.58.45 / PPT 页脚漂移治本(工具失败聚集 #1,A+C)**:`shell/exit` 排第1(近7天16条 exit-1、近24h 6条,9task/7用户),实测拆解 15/16 是**逐页手写绝对坐标偏离 `spec_lock.layout_grid` 锁定值 2–16px 的「想对齐没对齐」**(footer_y 近失 27行为最大头,margin_x/content_top 各7行,content_bottom 溢出12行),字体/spec_lock 只是 WARN 不 fail。关键发现:`executor-base.md §180-185` 早有「HARD—checker-enforced」的 snap 纪律却仍被漂移,加 prose 无用,治本须机械化。**A**:spec_lock_reference 新增 `## footer` 锁定片段——x/y 用 `margin_x`/`footer_y` 预填好、页码 `text-anchor="end"` 在 `canvas_w−margin_x`、留 `{PAGE}` 占位,executor 每页**逐字粘贴只换页码**,把 footer_y 这个跨页漂移第一大头从「每页手算」收敛成「一次编写」(executor-base 加对应硬规则,SKILL.md 同步);冒烟验证锁定片段过质检 errors=0、无 footer_y/margin_x 报错。**C**:`svg_quality_checker._ALIGN_TOL` 2→3px(2px 对手写实测过严),同步刷 SKILL/spec_lock_reference/executor-base 的「2–15px/2–12px」表述与测试值(margin drift 用例 60/63/66→60/64/68,30 测试全绿)。content_bottom 溢出(装太多项,另一性质)与 grid-snap 后处理(B)本轮未做。
- **07-19 / 0.58.43**:文件预览遮罩改整屏、消除"上暗下亮"割裂——旧实现用 `#file-preview-modal { bottom: var(--preview-bottom-inset) }` 把遮罩顶到 chat-form 之上,好让预览时能边看边打字,代价是底部整条(输入区+左栏入口+右栏+状态)全不压暗,与上方压暗区形成一条硬边界的通亮带,很割裂。改为遮罩铺满整屏(`bottom`→`padding-bottom`,仍让居中卡片停在输入区之上不遮挡),底部随整屏统一压暗;仅 chat-form 由新 `body.fp-open` 类 `position:relative;z-index:95`(压过遮罩 z90,层叠上下文已核:`#app`/`#pane-mid` 均不建 context)+ 上向阴影,上浮成"悬浮活动条",继续可打字。预览时左栏/右栏/状态点击落到遮罩=关预览(符合"背景不可用"预期)。改 `web/static/dev.html` + `web/static/js/preview.js`(open/close 加/去 `fp-open`)。
- **07-20 / 0.58.46**:文件预览背景撤回毛玻璃、改回压暗遮罩——用户反馈 0.58.44 的毛玻璃虚化(`rgba(20,22,28,.22)` + `blur(6px)`)"不行",要求变暗且背景仍看得到、注意度适中。改回半透明深色遮罩 `rgba(0,0,0,0.45)`(比 0.58.43 的 `.5` 略透、背景内容仍隐约可辨),去掉 `backdrop-filter`,chat-form 悬浮阴影恢复 `0 -10px 28px/.22`。因 0.58.44 之上已叠 0.58.45(工具修复),不走 `git revert`(会冲突版本/CHANGELOG),改为前向修复。只动 `web/static/dev.html`。
- **07-19 / 0.58.44**(已被 0.58.46 撤回):文件预览背景一度改毛玻璃虚化,用户反馈观感"不行",0.58.46 改回压暗遮罩。
- **07-19 / 0.58.42**:页内弹框替代原生 alert/confirm/prompt——用户反馈原生浏览器弹框(顶部丑框)应改成页内样式,且区分两类(对标 Element `dialog`/`message`)。新增 `web/static/js/dialog.js`:`dialogConfirm`/`dialogPrompt`(遮罩+卡片 modal,复用改密码那套头/体/脚布局,Promise 化以一比一替换同步的 `confirm`/`prompt`,Esc/点遮罩=取消、Enter=确认、danger 变体红键)+ `message`(顶部居中轻量 toast,success/error/info 三态,自动消失、点即消)。dev.html 加 `#app-dialog` 容器 + `#app-messages` toast + 对应 CSS。全量替换主应用 8 文件调用点(chat/files/crons/procs/wechat/skills/media/auth,共 30 处);`admin.js`(独立 admin-only 页、独立 `<style>`、无 CSS 变量)刻意保留原生 alert 避免缺样式。纯前端加法,不动后端/接口。
- **07-18 / 0.58.41**:任务改名 UI——后端 `PATCH /v1/tasks/{id}` 早支持 `name`(validate_task_name 校验)但前端无入口;`taskMenuItems` 加「重命名」项(列表行 ⋯ 与顶栏 ⋯ 共用此菜单,一处插入两处生效),`renameTask()` 走 prompt→PATCH→更 `state.tasksById`/`taskMeta.name` + `renderChatMeta()` + `loadTaskList()` 全同步。刻意只改 DB 显示名,不动 working_dir/磁盘宪法文件(定位锚是 task_id/short_id,name 设计为自由可变标签)。仅改 `web/static/js/chat.js`。
- **07-18 / 0.58.39**:JWT 滑动续签——活跃用户临期(剩余寿命 < TTL 1/4,env `ZCBOT_JWT_REFRESH_THRESHOLD_SECONDS` 可调、0 关)由 `_authenticate` 中间件就地重签发新 token 走响应头 `X-Refreshed-Token`/`X-Token-Expires-At`,前端 `api()` 无感吸收换 `state.token`,不再因 7d TTL 掉线。additive 惠及 platform 层 + SPA(不认退回原重登行为);CORS 加 `expose_headers`。
- **07-17 / 0.58.38**:修定时简报产物文件链接点开 404——推送端 `_build_push_message` 把产物写成完整 `/v1/files/download?path=` URL,撞前端相对路径拦截器致二次包装 404。A 拦截器识别 `^/?v1/files/` 抽真 rel 救 DB 历史存量 + B 推送端源头收敛为 user_root 相对 rel(企微 send_file 独立通道不碰此链接,不受影响)。
- **07-17 / 0.58.37**:修 task d9c74a5a 三处独立缺陷——① chip 提取 `_TAIL_CLS` 补排除 `*`(粗体路径尾 `**` 被吞成 404 chip)② docx 加 `EMOJI_RE` + `add_fonted_runs`,emoji 段走 Segoe UI Emoji 补缺字(不破坏化学式下标)③ `collect_md_files` 让 docx 三 profile 认单文件,兑现 render.py 单文件承诺、不再被迫建 sections/。
- **07-17 / 0.58.36**:run_python 超时返回超时前的部分输出 + `-u` 无缓冲——19 次超时全是真慢批量 I/O(论文检索/多 PDF/大下载),超时分支原丢弃已捕获输出致模型整批重跑;`format_timeout_result` 回部分输出 + 续跑提示(据已完成部分续 / 大操作走 background),docker/host 两执行器共用。
- **07-17 / 0.58.35**:通用报告走平台渲染器 `report` profile——平台早有 `rendering/` md→docx(+pdf)但没引导指向,烧 token 报告在裸手撸 python-docx;加 report profile(目录默认无 / 不强制分页)+ agent_builder 软引导。渲染器为**首选加法不硬拦** run_python(定制版式照样自由写)。
- **07-17 / 0.58.34**:run_python 宿主 `compile()` 语法预检——模型手撸 python-docx 把中文正文拼进源码致 SyntaxError 反复重试(失败面板最大头,20 样本实证);新 `core/pysyntax.py`(不 import litellm、本机可跑)命中返锐化中文诊断早返、跳过 docker 往返,零误伤(compile 不过 = 运行必失败)。
- **07-17 / 0.58.33**:堵两条烧 token 裂缝——① `_toolcalls_partial_args`(部分必填在场、部分缺失 = 流式 wire 乱序吞键特征)走非流式重试 + 落 `usage_events` kind=`tool_malformed` 可观测;② `_RepeatGuard` 补连续同类错误 streak 判据(`_norm_err` 抹平路径/数字签名,跨 ≥2 args),SOFT 提示、HARD 拦一次重置留活口。
- **07-15 / 0.58.32**:空响应防御——provider 吐空 tool_calls + 空正文原被当"答完"静默 done(隐蔽卡死);`_is_empty_response` 接 attempt 循环走非流式重试,耗尽仍空发**可见 warn**「已重试仍空,回复继续可重试」+ toolfail 聚集留痕,不引入终态 error。刻意不做内容嗅探式重试(假阳性更糟)。
- **07-15 / 0.58.31**:撤回 §8.11 delegate(0.58.30 曾整体落地,revert + force-push 抹除)——机制没错但触发信号没坐实(motivating 案更像批量扇出而非探索检索);重建前先用 diag 确认是真探索(依赖前序结果、无法一次列全)才 delegate,是批量走批量工具。只留验证过的批量工具(0.58.28)。
- **07-15 / 0.58.29**:修对话正文文件锚点两回归——① `media.js` `_TAIL_CLS` 误排间隔号 `·`(文件名合法分隔符)致含 `·` 的 pptx 丢 chip;② 正文相对路径链接点击整页 404,`chat.js` 加 `.msg .body a[href]` 拦截(外链新标签 / 内部 openFilePreview)。
- **07-15 / 0.58.28**:`mp_search_summary` 加批量入参 `formulas=[...]`(检索型烧 token 头号定点解)——pymatgen task 562 次逐式调用(91% 重复),批量化并成 1 次工具调用、复用单 MPRester 会话、中间数据落盘不进对话、只回紧凑摘要 + 路径;单查询路径字节不变向后兼容。"已知清单扇出"正解是工具批量化,非 delegate 子循环。
- **07-15 / 0.58.27**:对话卡片悬停「复制」按钮(仿 GPT/DeepSeek)——取正文 Markdown 原文(据 `data-idx` 回 `loadedMessages`,不从渲染 HTML 反推),clipboard 主路径 + execCommand 降级;范围收敛只做复制(后端纯追加无重跑/截断语义,重生成/编辑留待后端支持)。
- **07-15 / 0.58.26**:用户停止后「已停止」持久提示(补 cancel 终态,与 error 对称)——cancel 提升为一等持久终态 `run_status="cancelled"`(Text 列无 migration),前端 `renderPersistedRunTerminal` 认 error/cancelled、刷新/切任务仍在;删被收尾 loadMessages 冲掉的 live badge。蓝绿旧实例读到当良性态优雅退化。
- **07-15 / 0.58.25**:skill 定向模型豁免——current profile family==`unifyllm`(已选国际旗舰)时不切走 pin 的国产档,尊重用户显式选择;判据放 DB 写入前无副作用。DESIGN §3.5 记。
- **07-15 / 0.58.24**:畸形 tool_call arguments 就地抢救(salvage)——char-0 前缀垃圾(provider-wire 脏,parse 成功故 salvage/malformed 都不命中)命中畸形后 `core/salvage.py` 左→右扫 `{` 试 parse-to-end + key⊆schema,全有或全无采纳、省一次非流式重试;记 `tool_salvaged` 区分真丢弃 vs 救回。纯函数单列(避 loop.py import litellm 本机卡死)。
- **07-15 / 0.58.23**:sandbox 补 OLE 老格式解析依赖 `olefile`/`xlrd`/`extract-msg`(建材院高频老 `.doc/.xls/.msg` 转发件,markitdown 盖不到);需重建镜像。
- **07-13 / 0.58.22**:run_python script_path 宿主预检 + 路径容错 + code 落盘回退——三形态(没写就跑 / user_root 相对双重拼接 / code+script_path 同给);`_prepare_script` 前台 + background 共用,docker/host 同语义,含越界防护。
- **07-13 / 0.58.21**:run 级错误前端持久提示 + 进失败聚集面板 + provider 致命错误即时告警——错误卡被收尾 loadMessages 冲掉,`renderPersistedRunError` 据 `run_status=error` 持久化;`record_run_error` 留痕 toolfail 加 run cluster;余额/配额/认证正则命中即邮件(签名 6h 冷却)。
- **07-13 / 0.58.20**:非流式重试期「思考中」指示恢复 + 停止即时生效——`llm_start` 挪进 attempt 循环每次重发,前端既有逻辑自动重建占位段;`_nonstream_once` 挪后台 daemon 线程,主线程 0.5s poll cancel(弃养线程跑完丢弃、语义同流式 cancel)。
- **07-13 / 0.58.19**:畸形 tool_call 首败即降级非流式 + 损坏原文留痕——v4-pro 也踩 delta 错位老病且同轮流式重 roll 强相关;`_MAX_MALFORMED_ATTEMPTS`(1 流式 + 2 非流式)首败即降级、修 off-by-one;`_log_malformed_args` 打首尾 300 字符 ascii 转义(畸形轮不入库,唯一取证)。
- **07-13 / 0.58.17**:历史消息丢图片预览/chip 两根因——① `selectTask` 并发化(0.12.16 引入)致 renderMessages 时 taskMeta 还是旧值/null → wd 算错、chip+inline 图全丢,`loadMessages` 加 `{render}` 开关延后渲染到 meta 赋值后;② 中文语境正则漏挂,lead 边界改"行首或非 `[A-Za-z0-9._-]`"、tail 补中文标点。
- **07-13 / 0.58.16**:有 gpt_image 权限用户生图默认 GPT——`_default_image_variant` 档位集有 gpt_image 则默认它、否则 seedream;`is_default` 与 resolve 空串解析共用,保证下拉与实挂图像工具一致。可下拉切回豆包。
- **07-13 / 0.58.15**:结构图 mermaid vs 生图改 ask_user 让用户点选——mermaid 路径不触发 load_skill 看不到岔路,`_MEDIA_DIAGRAM_FORK_SEG`(挂图像 variant 时追加)先二选一(矢量可编辑 vs 生图有质感但中文标签易乱码);免问例外 = 已点名/已选过/paper·proposal 管线要 mermaid。纯 prompt。
- **07-13 / 0.58.14**:toolfail 聚集加时间分布——`daily` 按 24h 分桶 + `count_24h` + first_at,排序"近 24h 活跃在前",admin 页加"近24h"(>0 红)+ 趋势 mini 条形图,已安静行淡化;修好次日看板变灰 = 修好。API 只加字段向后兼容。
- **07-13 / 0.58.13**:look_at_image 引导改"慢、谨慎调"——原写"便宜"鼓励随手调,实际痛点是慢(几十秒);tool description + 媒体段改强调 SLOW / 一次问全 / 别反复看同图。纯 prompt。
- **07-13 / 0.58.12**:沙箱镜像补 `file` 命令(13 任务撞 `file: command not found`);同批 olefile/cairosvg 决定不装(量小可自愈 + cairo DLL 坑 Windows host,待巡检趋势)。
- **07-13 / 0.58.11**:工具失败聚集巡检(反 9dcae061"挂 90 天无人知")——新 `core/toolfail.py` 扫近 7 天 role=tool 错误按(工具 + 归一签名:路径/数字/uuid 抹平)聚合,≥5 次跨 ≥2 task 判聚集;三出口 = 周期任务发 `ZCBOT_DEVELOPER_EMAIL` + `GET /v1/admin/tool-failures` + admin 页表。无新表无 migration。
- **07-12 / 0.58.10**:**mermaid 渲染真·终案**——init.sh `127.0.0.0/8 DROP` 掐死 puppeteer↔chromium 的 127.0.0.1 DevTools WebSocket(SYN DROP → TCP 重试打满,恒 ~2m15s 超时 + CPU 近 0),`apply_blocklist` 首条放行 `-o lo` 后大图 5.2s 出图,"1 vCPU 渲大图慢"亦误判。90 天 67 次 timeout 真凶是它;之前 probe 全走 `--entrypoint bash` 绕过 init.sh 误判三轮(复现线上必须默认 entrypoint)。生效需重建镜像 + 回收容器。详见 memory `sandbox_chromium_crash_saga`。
- **07-11 / 0.58.8**:mermaid 必崩阶段性定案(后被 0.58.10 推翻)——07-08 镜像烤进的 chromium 点版本 `150.0.7871.46` 启动即崩(int3 自杀零日志),`--only-upgrade` 复活;Dockerfile 加 `CHROMIUM_REFRESH` cache-bust 旋钮 + build 末尾渲染 canary(坏则 build 当场失败)。0.58.9/0.58.7-0.58.4/0.58.5/0.58.6 = 排查过程中的 probe 迭代(bisect hardening 逐 flag / round-3 探针 / 下载源修正 / `-i` stdin 坑),结论沉淀进 memory,细节查 git log。
- **07-11 / 0.58.3**:admin 用量表默认时间范围 all→近 7 天(两表初始 range,API 默认不动)。
- **07-11 / 0.58.2**:sandbox `pids_limit` 256→1024(chromium headless ~150-200 线程 + shell 超时只杀 host 侧 docker CLI、容器内残留 → 打满 EAGAIN;彻底修法是 Step 3b PGID kill,未动);unifyllm 文本再加 `gpt55`/`gpt54_mini` 进 pro 档。
- **07-10 / 0.58.0**:第二图像后端 gpt_image(unifyllm 网关,pro 档)——媒体 provider 从豆包单家泛化为多家:`config/media/unifyllm.yaml` + `tools/gpt_image.py`(仅 prompt,不支持 i2i/尺寸);装配泛化(`_choose_image_variant` 跨 provider、`_media_tools_block` 按实挂工具拼装、web catalog 扫 `config/media/*.yaml`);豆包在前默认仍 seedream。
- **07-10 / 0.57.0**:unifyllm 网关接入(5 个国际旗舰进 pro 档)——`config/models/unifyllm.yaml`(fable5/opus48/sonnet46/gpt56_sol/gemini31_pro,litellm `openai/` 前缀零代码改动)。坑记 yaml 头注释(gpt-5.x 硬拦 temp≠1、gemini temp=0.3 返空 → 两者 `optimal_temperature: 1.0`)。**部署注意:服务器直连 unifyllm.ai TLS 握手失败需代理出口**,价格字段暂 0。
- **07-10 / 0.56.0**:后台进程 bg proc(DESIGN §8.12)——解"长脚本被工具超时掐死 / 占死 run / 蓝绿切换陪葬":`shell`/`run_python` 加 `background=true` + `check_process` 工具;状态协议纯文件(`<user_root>/.zcbot_procs/…`)无 DB 无队列;host 走独立 wrapper、docker 走专用容器(与 sandbox 生命周期解耦扛蓝绿);前端 `[Background]` 结果卡活化 + toast + 对话锁(轮询式,proc 完成往往无活跃 run)。同批带 seedance `resume_task_id` 续查 + LLM 超时显式化 600s(`ZCBOT_LLM_TIMEOUT_S`)。
- **07-10 / 0.55.2**:文件面板根目录隐藏系统工作目录(定时任务 / 渠道镜像目录,DB 回查判定);仅列表降噪非权限拦截,带 path 直接访问照常放行。
- **07-10 / 0.55.1**:per-user 磁盘配额 5GB→20GB(应用层软配额,OS 层 xfs prjquota 留待 §7.5 #4)。
- **07-09 / 0.55.0**:用户版更新日志——根 `CHANGELOG.md`(面向用户口径,回填至 0.30,与工程笔记 PROGRESS 分离)+ `GET /v1/changelog`(公开、mtime 缓存热改即生效、零 migration)+ 前端版本号可点弹层 + localStorage 记 last-seen 亮红点。CLAUDE.md 加维护约定。
- **07-09 / 0.54.2**:清理 `deepseek-chat/reasoner` 下线残留描述(照做会打不通)。
- **07-09 / 0.54.1**:对话头部压缩指示环(编辑器式)——头部改 `N tok + 环形指示器`(窗口体量/模型容量,三段色阶:绿未压缩 / 琥珀压缩区 / 红达折叠阈值),金额/缓存命中挪 hover。数据链:`GET /v1/tasks/{id}` 加 4 个 additive 字段 + 折叠计费 kind `context_fold`。**§8.8 Phase 2 长会话中段折叠摘要**——run 起点窗口达 `reliable_context×85%` → `core/context_fold.py` 把中段折叠为结构化摘要写 `tasks.context_summary`(0021)、推进 `context_base_idx`,`Session.load` 注入仅内存「[前情摘要]」;前缀缓存友好(复用会话 prepare 前缀 + 末尾追加),失败零阻塞。
- **07-08 / 0.53.1**:新增 rebuttal skill(审稿意见回复 / 修回)+ paper·review 增强——调研 GitHub nature skill 生态后移植:rebuttal(逐点回复 + 修改清单 + cover letter,零编造铁律 + 语气纪律 + 疑难案例库);paper 补 `figure_discipline.md` + `submission_audit.md`;review 补 `sci_polish.md` 英文 SCI 润色子模式。文献检索/paper2ppt 等未装(自有后端对不上 / 已有更强版)。
- **07-08 / 0.53.0**:录音文件转写工具 `transcribe_audio`——新 `core/asr_lfasr.py`(讯飞 raasr v2:签名 + 异步订单 + 说话人分离)+ host-side tool;选 LFASR 弃 IAT 分片(单文件 5h/500MB、服务端解码、roleType=1 自带说话人分离);全文落 `.transcript.txt` 只回预览 + 路径。凭据 `XFYUN_LFASR_SECRET_KEY`。
- **07-08 / 0.52.x**:企微/个微语音接入收尾——个微 ClawBot 语音(SILK v3 → pilk 解码 + ffmpeg,`core/audio.py` 统一入口 `transcribe_voice` 按字节头分流,两渠道共用)+ 企微语音(AMR → ffmpeg)全链路用户实测跑通;沿途修 pilk 源码编译坑(需 build-essential)、requirements `# [host-only]` 标记 build 时过滤、npm 源重试、企微回调平台侧失效(后台重存配置恢复)、推送失败不再静默。**服务器新增系统依赖 ffmpeg**。ppt 验收改纯代码几何质检、撤 0.36.0 渲图 vision 闭环(DESIGN §8.10,SKILL 零提及渲图)。
- **07-07 / 0.4x**:web 端语音输入全链(讯飞 IAT)——`POST /v1/asr/transcribe`(整段 PCM)+ `WS /v1/asr/stream`(流式 wpgs 服务端合并动态修正,16.8s 音频 end→final 179ms)+ 前端手势(触屏按住说话 / 桌面点击开停 + Enter/Esc,按下时长判别两端统一,明确不做桌面 VAD 自动停)+ 录音面板实时波浪字幕;凭据 `XFYUN_APPID/API_KEY/API_SECRET`。踩坑:讯飞控制台 IP 白名单(握手 403)。企微会话冷启动改**聊天优先布局**(不配主页 + 菜单「工作台」按钮直进会话)+ 未绑定入站回绑定指引;撤除欢迎推送死重(0.46.1);移动端浮层菜单钳视口 + 对外品牌名 env `ZCBOT_BRAND_NAME`(zcbot 只是内部代号);企微应用主页免登(snsapi_base 静默授权进 embed);run 长耗时可视化(SSE `reasoning` 事件 + 每秒跳秒指示,修"静止被当卡死")。
- **07-06 / 0.4x**:**蓝绿无感部署(RUN.md B 档落地)**——`zcbot@blue/green` 双 systemd 实例 + nginx upstream 单行切流 + `update_bluegreen.sh`(轮询 DB 等旧色 run 清空再 stop);双实例并存三修(`tasks.run_owner`(0020)reaper 各收各色 / 容器名带实例色 / 微信长轮询 PG advisory lock 选主);broker 刻意不出进程(接受切换瞬间刷新看不到旧实例直播)。**broker 外置 Redis**(`ZCBOT_REDIS_URL` 开关,不设 = 进程内)——LocalRunBroker/RedisRunBroker 双实现,event 走 PUBLISH + done SETEX、cancel key poll 跨实例可达。沿途:nginx TLS/497 跳转示例修正 + 部署脚本 pip `-q` + `wait_health` unbound bug。
- **07-03 / 0.38.x**:任务列表运行态标识(`run_status` 快照 + liveRuns 叠加,7px 脉冲圆点、默认态静默、running 行自动挂 SSE 上限 4 条);ppt 反纯文字页 + 图表落地硬门(7aa49195 复盘:版式指纹 + spec 指派图表退化→error + CJK 互叠升 error + content_bottom 越界检测);web 直播流式文字按轮次分段(修工具刷屏把文字推出视口);seedream size 面积钳制;ppt 对齐网格锁 layout_grid(d1285247 复盘)。
- **07-02 / 0.36.x**:ppt 渲图验收闭环(139a59c5 复盘)+ check13 几何检测(压字/越界=error);二轮硬化(渲图验收不可 flag 豁免 / 图标门对 svg_output / 导出前内嵌质检 / 修 svg_final 嵌图失效)。[后于 0.52.x 撤除 vision 验收,改纯几何质检]
- **07-01 / 0.3x**:快捷指令(`core/shortcuts.py` 触发词→完整指令,入口层确定性替换非 memory);ppt 修多起零图标/伪导出(`sys.exit(main())` 吞退出码 / 图标硬门 / cairosvg 兜底 / 页数升独立 🔒 gate);ppt 工作目录重构(可再生产物收进 `.build/`);look_at_image/seedream 接受容器绝对路径。

### 2026-06 下半月(渠道/ppt SVG-first/管控)

- **06-30 / 0.33.5**:ppt 加商务红品牌预设(business-red,#C00000 + 政企口吻,设为中文政企汇报默认配色候选);用户没给图时主动提议 ai 配图(提议免费,确认才花钱)。
- **06-30 / 0.33.4**:修「PPT 缺图形」:质检加扁平 deck gate(文字密集全 deck 0 图形图元→error)+ 策略层视觉下限(spec_lock 不许 page_charts 与 page_layouts 同时空)。prompt+gate 抬下限,执行模型设计功力是上限。
- **06-30 / 0.33.3**:修「PPT 缺图标」四层断点:references 里 23 处 ppt-master 残留路径修正 + 新建 icon_sync.py(strategist GATE 此前空转)、质检加"锁了图标却全 deck 0 图标→error"、执行层强制内容页 1-3 图标、导出预扫警告。附:svg_preview 认容器 chromium + 修 `--screenshot` 相对路径静默失败。
- **06-30 / 0.33.2**:look_at_image 偶发超时改 tool 内透明重试(新 `ArkTimeoutError` 子类,仅超时/网络抖动重试),vision timeout 60→120s;避免报错抛给主模型触发整调用重发烧 token。
- **06-30 / 0.33.1**:修 web 端 SVG 无法预览(前端按扩展名强制 blob mime + 后端 download 对 .svg 显式回 `image/svg+xml`,双保险)。
- **06-29 / 0.33.0**:**ppt skill 清空重构为 SVG-first**(移植 ppt-master 引擎+设计知识,弃 GUI):AI 逐页手写 SVG,纯 Python 转换器译成原生可编辑 DrawingML;templates 全量入仓(icons 30MB);Confirm UI 换聊天 BLOCKING 确认,配图走 imagegen;端到端 4 页 deck 验证过。
- **06-29 / 0.32.5**:system prompt 加全局 context 纪律铁律:大段工具输出会进历史每轮重发——中间数据落文件、只 read 用得上的片段。
- **06-29 / 0.32.4**:定时任务默认单次超时 0→1800s(`DEFAULT_TIMEOUT_SECONDS` 单一事实源,显式 0 仍=不限)。
- **06-29 / 0.32.3**:brief skill 加 context 纪律,堵"同一批 38 篇 abstract 反复 dump 进上下文烧 2.5M token"(弱模型放飞);更大杠杆(框架层截断超大 stdout)留待单议。
- **06-29 / 0.32.2**:修定时任务超时被误记成 ok:`_execute_scheduled_job` 超时分支置 `timed_out`,收尾按 error 记(计连续失败、不投半成品 notify)。
- **06-29 / 0.32.0**:channel 长会话软重置(Phase 1):`tasks.context_base_idx`(0019),`Session.load` 只装 base 之后的消息进 LLM 上下文,历史全量留表;自动 gap(默 6h)软重置 + 手动「新话题」硬重置。Phase 2 摘要 / Phase 3 检索延后。
- **06-26 / 0.31.3**:消息框支持拖拽文件;附件 chip 独立托盘 `#chat-attach`(与状态文字解耦),修多次粘贴互相顶掉。
- **06-26 / 0.31.2**:目录圆点错位再修:点选加跳转锁防平滑滚动途中被 scroll-spy 抢写;触底且无更新内容时直接判最后一轮(经典"不可达末项"bug)。
- **06-26 / 0.31.1**:admin 近 7 天用量表加合计行(纯前端 tfoot)。
- **06-26 / 0.31.0**:per-account 模型访问控制——**档位制**(复用休眠列 `users.plan`,「档位→模型集合」配 agent.yaml `model_tiers`,管理成本 O(档位)):list 端点按档过滤、resolve 显式选档外模型→403、老 task 存量模型出档→持久降级 flash;admin 加档位列+图例。
- **06-26 / 0.30.0**:新增豆包 Seed 2.1(turbo/pro/evolving)+ GLM 5.2 文本模型档案(纯 yaml 即上下拉);pro52 与 glm.pro(5.1)并存不动线上引用。
- **06-26 / 0.29.0**:定时任务执行历史:右栏改 Tab(详情/执行记录),新端点 `GET /v1/schedules/{id}/tasks` 分页;保留全部历史不剪枝。
- **06-26 / 0.28.1**:渠道绑定/对话/管理收进左栏卡片(未绑定/已绑无对话/已绑有对话三态),删 rail「微信」按钮。
- **06-26 / 0.28.0**:定时任务 task 归属(`tasks.scheduled_job_id`,0017,普通列表过滤掉)+ push 统一记录到渠道对话——记录下沉到 `send_to_user`,投递成功即写 assistant 摘要消息(`messages.kind="push"`,0018,取回复时跳过),用户可基于推送追问。
- **06-25 / 0.27.4-0.27.3**:渠道镜像对话从任务列表置顶行改成左栏固定卡片(`/v1/channel_tasks`,列表查询排除渠道任务),两卡并排;企业微信对话同微信一样 web 端只读。
- **06-25 / 0.27.2**:企业微信入站支持图片/文件(`media/get` 下载→InboundAttachment,复用个人微信同一落盘/注入约定)。
- **06-25 / 0.27.1**:`wechat_push` 加可选 `channel` 参数定向投递,修"点名企微仍广播到个微";不静默回退到别的渠道。
- **06-25 / 0.27.0**:企业微信入站对话:回调 webhook(新 `wecom_crypto.py` 验签解密)+ 把个微会话核心抽成 `_run_channel_conversation(channel)` 两渠道共用、各一张会话 task;回复走主动推(agent 超 5s 被动窗口)。
- **06-25 / 0.26.10**:修企微扫码绑定——网页授权端点只能企微客户端内打开,换 `wwlogin/sso/login` 扫码授权端点(桌面浏览器出二维码)。
- **06-25 / 0.26.9**:修 wechat_push 漏挂企微:提取 `service.active_channels()` 作渠道清单唯一真相源,门槛与投递同源,根除两处各列各的漏判。
- **06-25 / 0.26.3**:企微加「手填 userid」绑定第二条路——推送是出站直连根本不需要域名,只有 OAuth 扫码要。
- **06-25 / 0.26.2-0.26.1**:监控页近 7 天按日期倒序;用户名展示统一兜底链 `name→user_name→email→uid8`(监控页 + dev 顶栏)。
- **06-25 / 0.26.0**:平台登录注入用户档案 name/user_name(0016 加两列;`ensure_user_row` 升 upsert,COALESCE 语义传空不覆盖);`/v1/me` 回带。
- **06-25 / 0.25.2**:登录失败提示修正——凭据错统一给「账号或密码错误」,不再回显被网关改写的状态码。
- **06-24 / 0.25.1**:微信 task 在 web 端改只读镜像(单一交互权威锚定微信;24h 窗口约束下"双向打通"只能有时同步,不做)。
- **06-24 / 0.25.0**:微信入站收图片/文件(此前静默丢弃):ilink 解析 image/file item + CDN 下载 AES-ECB 解密,落盘 `inbound/` 并按 web 端粘贴图同一约定注入正文。
- **06-24 / 0.24.3**:微信绑定两表合一 `channel_bindings`(判别列+JSONB 多态,0015 搬数据+drop 旧表)——加渠道零 migration;service 公共 API 形状不变,调用方零改动。
- **06-24 / 0.24.1**:修 host-side 工具(send_email/wechat_push)发不出附件:`tools/base.py` 加共享 `_resolve_user_file`(容器路径翻译+越界校验),base_dir 从 cwd 改 working_dir。
- **06-24 / 0.24.0**:企业微信渠道 B:纯推送 + OAuth 扫码绑定(用户拍板"和邮箱似的"不做对话)——无条件主动推正补 ClawBot 24h 窗口短板,定时简报必达首选。
- **06-24 / 0.23.2-0.23.0**:配 QQ SMTP + 发件人显示名走 `SMTP_FROM_NAME`;`tasks.channel` 列(0013)微信 task 后端置顶 + 品牌绿徽章。
- **06-24 / 0.22.2-0.22.1**:微信绑定 UI 并入主 SPA(rail modal);修顶栏 token 计量栏回复后不刷新(fetchSse 收尾重拉 meta)。
- **06-24 / 0.22.0**:**微信接入第一期 ClawBot 个人微信**(官方个人号 Bot API,零封号):协议全程真机实测(`client_id` 每条必唯一、`context_token` 24h 复用→主动推送成立、文件走 AES-128-ECB+CDN);`core/wechat/` 四模块 + 0012 + `wechat_push` 工具 + 定时 notify 加 wechat 通道;凭据加密列不进沙箱。
- **06-23 / 0.21.0**:**平台渲染层 `rendering/`**:渲染是平台能力非 skill 内容(共享库进 skill 会破坏自包含/可 fork),三 skill 重复的 render_docx 收敛成配置化 profile + chromium md→pdf(不用 weasyprint);重构前后 docx 字节一致零回归;需一次 deploy 原子激活。
- **06-23 / 0.20.4**:消息目录定位错位修:跳转改 `block:"start"` 与活跃判定同锚点,容差 80→24。
- **06-22 / 0.20.3**:crons modal 补 z-index;登录页 focus 引用错 id。
- **06-21 / 0.20.2**:发送期修复悬空 tool_calls——run 中断留下的 `assistant.tool_calls` 无对应 tool 结果会被 API 拒、task 卡 error;`_repair_dangling_tool_calls` 发送前补占位 tool 消息,不改库、存量坏数据自愈。
- **06-18 / 0.20.0**:brief 重定位「重要文献速览」(只描述不给建议,Elsevier 优先,web 动向单列),8 文件精简到 3。
- **06-18 / 0.19.0**:**定时任务 v1**(`scheduled_jobs`):job 本体=cron+一句 prompt+会话模式,"发邮件"是 agent 动作不是字段(加能力不改 schema);croniter 只当 next_run 计算器,调度是 plain-asyncio 守护循环不上框架;对话端完整 CRUD、前端只读+停用/删除;isolated/persistent 两模式。
- **06-18 / 0.18.0**:新增 brief skill(文献计量趋势型简报,documents/research/web 三路取数,六阶段);顺带抽化学式下标白名单补进三个 render_docx(CO2/C3S 平排数字老毛病)。
- **06-17 / 0.17.0**:任务软删除(`deleted_at`,0010):公测后对话轨迹是语料,硬删推翻;DELETE 改置位 + restore 端点,文件不动。
- **06-17 / 0.16.2**:用户操作说明书(详+精简两版,不出现产品代号);文献库库容口径 21W+→100W+ 全量 10 处改。
- **06-17 / 0.16.1**:新增 paper skill(期刊论文写作):调研 ARS 等开源不直接装(license/领域/引文格式不合),移植流程骨架、底座全换 zcbot 自有;中英双语×三类型用子 md 分流;微型 fixture 端到端 smoke 过。
- **06-16 / 0.16.0**:look_at_image 图像理解(Doubao Seed 2.0 Lite,一次读图 <¥0.01):主模型纯文本按需"借眼睛",否决换 vision 主模型(DeepSeek code/tool-calling 是核心);`usage_events.kind=vision` 免 migration;路径解析抽 `tools/image_ref.py` 共用。
- **06-16 / 0.15.0**:seedream i2i 改图(`reference_images` v1 单图,不传=文生图行为不变);前端发送时注入粘贴图路径 `[用户上传的参考图]`(修既有缺口:粘贴的图路径根本到不了模型)。
- **06-16 / 0.14.0**:ask_user 方案确认选项卡(Claude 式):虚拟工具、调用即提前结束本轮,点选项=把 label 当新用户消息发,零额外 LLM 往返;严格收窄到"2-4 个互斥方向"防变爱问。
- **06-16 / 0.13.0**:消息目录:右侧悬浮圆点轨道(每点=一轮提问,hover 标题、点击定位),新 outline 端点只取 user 消息 idx+片段;消息列表支持双向分页。
- **06-16 / 0.12.16**:切 task 提速:meta 与 messages 改并发拉(此前串行 await 是真瓶颈,索引没问题),首屏窗口 60→30。

### 2026-06 上半月(前端打磨/记忆/admin/token 治理)

- **06-15 / 0.12.15**:plot_pub 吸收 nature-figure 投稿级复合图设计纪律(只迁设计 IP 不整包移植,示例改建材领域)。
- **06-15 / 0.12.14**:消息分页:尾部窗口 + 顶部 sentinel 向上滚动加载更早;不传 limit 保持旧行为。
- **06-15 / 0.12.13-0.12.10**:文件预览四连:滚动不穿透(overscroll-behavior+wheel 断冒泡)、图片 Ctrl+滚轮缩放(CSS zoom 被 max-width 夹回,改显式 px)、双击复位、放大后左键拖动平移。
- **06-15 / 0.12.9**:sandbox 镜像加 `fonts-noto-color-emoji`,修 mermaid 图 emoji 全豆腐块。
- **06-15 / 0.12.8**:左栏筛选区默认折叠(显式展开过才记住展开)。
- **06-15 / 0.12.7**:system prompt 按 backend 注入「运行环境」段——原写死 Windows/cmd,docker 下误导模型 Linux 里打 cmd 构文 + 不知渲图走本地。原则:全局环境事实归 system(高杠杆),可选方法归 skill。
- **06-14 / 0.12.6**:容器 `mmdc` 套 wrapper 自动注入 puppeteer config(`--no-sandbox` 等),裸调一次成;不开 first-class tool(mermaid 纯本地计算,专用 tool 只留给带 key 计费能力)。
- **06-14 / 0.12.5**:容器 `docker run` 加 `--shm-size 512m`(默认 64MB 让 chromium 起不来,一次对话烧 120k token 才绕道)。
- **06-13 / 0.12.4-0.12.1**:模型选择瘦身(对话下拉常驻、生图/生视频收 ⚙ 弹层);筛选区可折叠;中栏 5 按钮收「完成+⋯」菜单 + 消息阅读限宽 + 色彩收敛(颜色=后果);移动端 task 列表可滚等四小修。
- **06-12 / 0.12.0**:**双层记忆升级 agent 自管**:`memory_block` 注「记忆维护契约+可写路径锚点」常驻(空记忆也注,解冷启动),agent 用已有 fs 工具自维护;召回升级 frontmatter description;前端只读记忆面板(看走 GUI、改全走对话——单一写入口不会写坏格式)。
- **06-12 / 0.11.1**:进入公测期:CLAUDE.md 兼容策略翻新为"对外契约必须向后兼容、纯内部实现仍最优重写"。
- **06-12 / 0.11.0**:admin 增强:TOC + 按模型/各用户用量独立端点(range/sort/分页,零用量用户条件放 JOIN ON)+ 存储分页 + 导出 PDF(客户端 window.print 零依赖)。
- **06-12 / 0.10.1**:**修上下文压缩投毒**:旧 assistant tool_call 参数被压成 `{"_compacted":...}` marker,模型照葫芦画瓢当真实参数吐出(DB 实测 83 次报错里 61 次是仿写)→ run_python 空转。修:参数一律原样保留,只压 tool 结果 + skill——模型看到的范本永远真实可执行。
- **06-12 / 0.9.x**:admin 管理后台:`users.role` 列(0009)+ `require_admin`(role 走 DB 查不进 JWT,改完即时生效)+ `/v1/admin/overview` 五段聚合 + 各用户用量分页 + 独立 admin.html(阈值热力色,10s 轮询);命名定 admin(既盖"看"又盖"管")。
- **06-11**:版本号机制(`core/__init__.__version__` 单一事实源→FastAPI/healthz/前端左栏,改版本只动一行);显式 ThreadPoolExecutor 接管默认池 + `[stats]` 60s 采样日志(空闲静默);dev SPA「技能」查看 modal(纯查看+删除,编辑走对话);**用户私有 skill**(`user_root/.skills/`,多来源 registry user wins、覆盖显式标注、坏 skill 不崩扫描;写走 host-side `save_skill`/`fork_skill`——fs 工具跨 backend 够不到 user_root)。
- **06-10**:system prompt 瘦身 ~40 行 + 媒体段按需注入(有 ARK key 才发);上下文压缩加压力门槛(超阈值才压,护 DeepSeek 前缀缓存);单轮停机判据从步数解耦为进展信号(`_RepeatGuard` + run 级 `_stall`,max_iterations 降为纯 backstop);systemctl restart 优雅 drain in-flight run(先拒新再等收尾)。
- **06-09**:PPTX 前端在线预览(soffice→PDF 复用已有 iframe 路径,缓存+超时 kill);药3 幽灵路径不复现 + 回归测试钉死;ppt 补信息设计纪律件(takeaway/kpi/卡片组合件 + pptx_preview 渲 PNG 验观感)。
- **06-08**:loop 加病理性重复调用守卫(`_RepeatGuard` 按指纹累计"无产出重复",SOFT2 提示/HARD4 拦截);检索/抓取 host 工具批量化(单数改列表,一轮并发一批——高轮数烧 token 三股根因之一);ppt 视觉系统升级卡片式;system prompt 加「少来回」原则;ppt 工作流批量化(N 页 ~2N 轮降到 3-4 轮)。
- **06-06**:前端模块化 Step 2 收官(main.js 2719→75 行入口,拆 15 个零构建 ES module);修 flash 大参数 tool_call arguments 损坏——校验 json.loads 失败丢弃整轮重 roll(不入库,断投毒级联),最多 3 次后降级非流式。
- **06-05**:前端模块化 Step 1(抽 5 个叶子模块);run_python 过程脚本约定落 `scripts/`;新增 standard skill(GB/T 1.1—2020 自建,重点对接 CSTM 团标)。
- **06-04**:ppt 版式 helper 收进 `pptx_helpers.py` + 修中文字体(`font.name` 只写 latin 是根因,补 ea/cs);quality_check 加内容形状重叠检测 + 三色制判定(非灰阶 ≤3);前端存储进度条;容器 env 收编 `_CONTAINER_ENV` 三路共用。
- **06-03**:修 docker 下 system prompt 焊死宿主路径(容器注入 `/workspace/<wd_rel>`);顺扫清 SKILL.md 残留宿主路径;图标种子库降只读;镜像源改清华/腾讯;workspace 落数据盘改 bind mount(回退 env 覆盖——与相对存储锚点冲突)。
- **06-01**:一键部署 `deploy/update.sh`(pull→pip→migrate→build→restart→healthz,自更新重跑守卫);修 MP 工具全量下载致 IP 被封(补分页);sandbox 镜像加中文字体;documents/MP 改 host-side tools(key 不进 sandbox)。

### 2026-05(骨架→SaaS 化→dev SPA)

- **05-29**:Seedream i2i base64 通路 probe(内网无需对象存储)+ tool_call 标题改中文活动描述。
- **05-28**:新增 analyze skill(问题拆解协调器)+ 3 个科学计算 skill(pymatgen/stats_ml/plot_pub,服务无机非金属材料 R&D);`config/models/local.yaml` 接内网模型(涉密专用,thinking_mode=false);Python 3.10→3.12;LoadSkillTool 修 docker 返容器路径;review 加长文档分章深审。
- **05-27**:ppt 歧义先反问(升格 system prompt 通用原则)+ description 白名单收紧路由;skill 热更新每次现扫。
- **05-25**:前端 CDN 依赖本地化 vendor/;上传进度/布局拖拽打磨;接入博查 web_search + web_fetch(SSRF 内网屏蔽)。
- **05-22**:dev SPA iframe embed 模式(postMessage 握手,PLATFORM_KEY 不下发浏览器)+ task_id 定位;媒体生成每日配额(默 20 图/5 视频);产物路径协议刚性化(`<wd_name>/<rel>` 全形式);Seedance 视频生成接入 + videogen skill;移动端自适应。
- **05-21**:新增 imagegen skill(五步法 + BLOCKING 确认防白烧钱)+ documents skill(内部材料学科库);sandbox 阻塞地位写进 DESIGN(shell 黑名单是装饰品,正确防线在 OS 层);task 预选 skill 注入提示;SSE 客户端重连;research fetch_pdf 直链 + pg_trgm 索引;同 wd 并发软警告(Claude Code 同款信任+软警告);paper_server 收编为 research skill。
- **05-20**:LLM 调用切 streaming(cancel 秒退 + 打字机);豆包 Seedream 5.0 接入 + 0007 全表统一 CNY;artifact chip 演进 + seedream 透明性 banner;润色按钮;fs 输出 user_root 相对路径;clear 端点;CLAUDE.md 加「实施前先对方案」。
- **05-19**:0006 task 级模型切换 + usage_events v2(units jsonb 多态);登录撤邀请码复用邮箱密码;SENTINEL user 彻底撤;任务/文件 `⋯` 菜单;proposal mermaid 强制;文件预览弹框。
- **05-18**:入口归位(cli.py→main.py,删 CLI REPL);0004 schema 大瘦身(删 runs,run_status 合入 tasks);files API 升格唯一目录树 mutation 入口(DB-FS 一致性服务端内化);task 级协作式 cancel;单活 run 锁 + 孤儿 reaper;proposal 流程图管线;skill 机制改可选辅助;UI 中文化。
- **05-17**:0003 name+working_dir+skill 三件套(任务标识与目录解耦);tasks 分页+筛选;task=name-based 项目目录(废 UUID 派生,同 name 共享,memory 进 `.memory/` dotfile)。
- **05-15**:§7 D `/v1` JSON API 落地(Phase G Jinja2/HTMX 撤);D' 过渡 auth(PLATFORM_KEY→JWT)+ dev SPA;task_dir 改相对存储(`core/paths.py`);workspace 统一 per-user。
- **05-14 → 05-12**:§7.1 心智修正 Folder-centric→Task 一等公民;§7 B ORM 5 表 + alembic(state.json 全废入 PG);§7 改写 user-direct(多租户方案废弃)。

### 历史(2026-Q1 → 05-11)

- **Phase 1-4**:骨架 / 三 skill / run_python / Model Profile + Probing;ppt v3 商务红 + apply_brand + Iconify;素材摄取改 markitdown CLI。
- **05-06 → 05-11**:Phase 6 部分(task + state.json + tokens 累计);TUI rich + `/resume`;DESIGN §7 初版(05-12 重写);`cli.py export` + `core/export_docx.py`;`atomic_write_text` + `core/memory.py`;loop 事件流化铺 SSE 路。
- **06-04 token 优化启动(DESIGN §8.2)**:chat usage 记 cache hit/miss + cost 兜底;`run_python` 加 `script_path` 模式;`core/context.py` 压缩旧 tool / load_skill(不改持久化历史)。
- **06-05 记账给缓存命中折价**:缓存命中按全价记致成本虚高 2-3x,成本公式拆三段 + 历史 backfill。

---

## 关键决策与偏差

| 项 | 决策 | 备注 |
|---|---|---|
| 工具基目录 | cwd(读)+ working_dir(写) | system prompt 同时注入两者绝对路径 |
| Workspace 布局 | `workspace/users/<user_id>/{.memory/, <name>/}` | per-user 隔离;memory dotfile 防撞;同 name 多 task 共享 |
| Eval Suite | 不做 | 个人工具 dogfooding |
| 版本化 prompt | 直接 `general_v1.md` | 真要切再做 |
| run_python 沙盒 | subprocess + env 过滤 | Docker 在 §7 C 阶段 |
| 兼容层 | 开发期不写 | DB schema / 字段 / API 改动直接切,见 CLAUDE.md |
| `/v1/files/*` 与 DB | files API 作目录树唯一 mutation 入口,DB-FS 一致性服务端内化 | rename / delete 顶层目录 DB-aware |
| 单活 run | task 同时最多 1 个活 run | gate 在 `post_message` 同事务 `SELECT FOR UPDATE` |
| LLM 调用走 streaming | `chat_stream` + `stream_chunk_builder` 拼回;chunk 间 + tool_call 间 poll cancel | cancel 延迟 100ms 级;content delta 即时 emit |
| 上下文压缩 | 加压力门槛,超阈值才压 | 护前缀缓存 + 不丢旧细节(§8.2 / 06-10) |
| 停机判据 | max_iterations 降为 backstop,靠进展信号掐空转 | `_RepeatGuard` + run 级 `_stall`(06-10) |

---

## 文件清单

```
core/capabilities.py        75   ← 模型档案增加 CNY/Mtok 计费兜底字段
core/llm.py                151   ← litellm 离线 cost map env + chat_stream(stream + include_usage)
core/loop.py               300   ← sink.emit + _stream_llm(chunk 间 poll cancel + emit delta)+ _RepeatGuard + usage cache 明细
core/context.py             95   ← LLM 调用前压缩旧 tool / load_skill 消息(带压力门槛),保 tool_call 协议字段
core/sinks.py              101
core/paths.py               50   ← task_dir db form 归一
core/probe.py              243
core/session.py            153   ← ORM
core/task.py                82   ← PG-backed TaskState
core/skills.py             180   ← 多来源 registry(SkillSource)+ source 标记 + 覆盖感知(user wins)+ load_errors + container_dir
core/memory.py              81   ← per-user `.memory/` dotfile
core/export_docx.py        383
core/storage/{__init__,engine,models,usage,utils}.py  ← 4 表(0004-0007 演进);record_chat/image_usage
core/ark_client.py         105   ← 火山方舟 HTTP 客户端
core/asr_xfyun.py          170   ← 讯飞语音听写 IAT wss 客户端(整段 PCM→文本;web 语音输入用,diag: scripts/diag_asr.py)
core/asr_lfasr.py          250   ← 讯飞录音文件转写 LFASR 客户端(异步订单 + 说话人分离;transcribe_audio 工具底座,diag: scripts/diag_lfasr.py)
core/agent_builder.py      340   ← 装配 lib(有 ARK_API_KEY 才挂 SeedreamTool);build_skill_registry 装两来源
core/executor.py / sandbox/{network,pool}.py / executor_docker.py  ← Executor ABC + Docker per-user 容器池
tools/{base,fs,shell,run_python,skill_tool,skill_authoring,seedream,seedance,web_search,web_fetch,documents,materials_project,transcribe_audio}.py  ← skill_authoring=save_skill/fork_skill(host-side 写 user .skills)
main.py                    ~210  ← 入口:web / db / probe / user / sandbox check
db/migrations/versions/    0001-0008
web/app.py                ~1360  ← /v1 JSON API + user_id 隔离 + run lock + cancel + files + pptx 预览 + skills(列表/正文/删)
web/auth.py                ~190  ← 邮箱密码 + platform_key → JWT
web/broker.py / sinks.py / pptx_render.py
web/static/dev.html + js/*.js    ← dev SPA 拆 15 个零构建 ES module(main.js 入口;skills.js=技能查看 modal)
web/static/vendor/        ~1 MB  ← jszip / docx-preview / xlsx
─────────────────────────────────
Python 合计              ~3400 行(+ dev SPA + vendor 1MB);加 skills 脚本 + 配置,总仓库约 3800 行
```

---

## 下一步候选(性价比排序)

1. **CORS 收紧**(~半小时,已接入真实用户应尽快做)—— `allow_origins` 从 `*` 改读 env 域名 allowlist;与 OIDC 解耦。
   - **真 OIDC**(~1 天,选做)—— `/v1/auth/login` 内部换 ID token 校验(路由层 Depends 不动);**邮箱密码长期保留并存**。platform_key 信任模型可接受则可延后,真要弃 PLATFORM_KEY 共享密钥时再做(延后无技术债)。
2. **§7 C Executor + sandbox 收尾**(~3-5 天,按 §7.5 落地清单)—— 剩 Step 4 完整 egress proxy + Step 3b PGID kill 协议 + xfs project quota OS 层硬化。**Stage C DoD** = 6 条落地清单全完成 + 红队回归通过(metadata IP / PG IP block、残留进程清理、跨 user 网络隔离、egress allowlist)。**多用户在线跑代码 hard prereq**。
3. **Phase 6 context 第二步 task summary**(~1 天)—— 旧消息压成一条 summary(区分硬约束/计划/文件路径/关键事实),不直接塞回旧 tool 原文。

> §7 B + D + D' + 单活 run 锁 + cancel + 0004 schema 瘦身 + 入口归位 + Stage C 主体已完工。剩余:真 OIDC → C 收尾 → F(deploy/billing)。§7 E CLI 双模式撤;Phase G Jinja2/HTMX 撤(详见 DESIGN §7.9)。