精简 DESIGN/PROGRESS:对齐当前实现,去掉落地前的设想

- DESIGN.md 1140 → 212 行:删 v1/v2 比较、Eval Suite 章节、Phase
  roadmap、长代码草图、技术栈清单(在 requirements.txt)、超长附录
- PROGRESS.md 185 → 82 行:删超细分的 ppt v3 描述、重复测试列表

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

PROGRESS.md

@@ -1,113 +1,38 @@
 # 实施进度
 
-> 配合 `DESIGN.md` 阅读。本文件记录已完成的事、关键决策、与原设计的偏差。
+> 配合 `DESIGN.md` 阅读。本文件只记录 phase 状态、决策偏差、文件量、下一步。
 
-最后更新: 2026-05-06 (Phase 4 + Phase 6 task/state.json 落地;移除 legacy session 兼容;Phase 5 evals 决定不做)
+最后更新:2026-05-06(Phase 4 + Phase 6 task/state.json 落地;Phase 5 evals 决定不做)
 
 ---
 
-## 总体状态
+## 状态
 
 | Phase | 标题 | 状态 | 备注 |
 |------|-----|-----|------|
-| 1 | 最小可用骨架 | ✅ 完成 | 全部验收点过 |
+| 1 | 最小可用骨架 | ✅ | 全部验收点过 |
-| 2 | Skill 系统 + 三个 skill | ✅ 完成 | Anthropic 格式;coding/ppt/proposal |
+| 2 | Skill 系统 + 三个 skill | ✅ | Anthropic 格式;coding/ppt/proposal |
-| 3 | Hybrid 范式 (run_python) | ✅ 完成 | subprocess + 敏感 env 过滤 |
+| 3 | Hybrid 范式 (run_python) | ✅ | subprocess + 敏感 env 过滤 |
-| 4 | 演化性能力 | 🟡 部分 | Model Profile 已就位;capability probing ✅;版本化 prompts 未做 |
+| 4 | 演化性能力 | 🟡 | Model Profile + Capability Probing ✅;版本化 prompts 未做 |
-| 5 | Eval Suite | ⏸ 不做 | 个人工具,造作 case 没区分度;真换模型用 dogfooding 判断 |
+| 5 | Eval Suite | ⏸ 不做 | 个人工具用 dogfooding 替代,probe 覆盖健康检查 |
-| 6 | 长任务工程化 | 🟡 部分 | task + state.json ✅;session 中断恢复 ✅;context 压缩、双层记忆未做 |
+| 6 | 长任务工程化 | 🟡 | task + state.json + 中断恢复 ✅;context 压缩、双层记忆未做 |
-| 7 | 打磨 | ❌ 未开始 | Docker 沙盒 / 更多 skill / Web UI |
+| 7 | 打磨 | ❌ | Docker 沙盒 / 更多 skill / Web UI |
 
 ---
 
-## 已完成清单
+## 已完成关键能力
 
-### 1. 项目骨架
+**Phase 1-3**(2026 早期):骨架 + skill 系统 + run_python。所有工具基目录是用户当前 cwd(不是 zcbot 仓库本身),agent 操作的是用户项目。`tools/fs.py` 的 `edit` 用 CoreCoder 风格唯一匹配。`tools/run_python.py` 过滤 `*API_KEY *TOKEN *SECRET *PASSWORD *PRIVATE_KEY` 环境变量。三个 skill 中 `ppt/` 最完整(v3:商务红硬约束 + apply_brand 品牌条 + Iconify 图标库 + scripts:fetch_icon / quality_check / source_to_md / render_icon)。
-- 目录: `core/ tools/ skills/ prompts/ config/ workspace/`
-- 入口: `cli.py` (REPL) + `main.py` (装配)
-- 依赖: `requirements.txt` (litellm / pyyaml / click / rich / python-pptx / python-docx / matplotlib)
-- 本地虚拟环境: `.venv/`(Python 3.10.9)
 
-### 2. 模型层
+**Phase 4**(2026-05-06):
-- `core/capabilities.py`: `ModelCapabilities` 数据类,从 `config/models/<family>.yaml` 加载
+- `core/probe.py` + `cli.py probe` —— basic_chat / parallel_tools / thinking_mode / long_context 四项探测
-- `core/llm.py`: LiteLLM 封装,自动按 capabilities 启用 parallel_tools / reasoning_effort / prompt_caching / thinking_mode;指数退避重试
+- 真实 probe 跑通,**flash mismatch 发现**:yaml `parallel_tools: false` 但实测能并发(暂不自动改 yaml,需更多场景观察)
-- `config/models/deepseek_v4.yaml`: flash 和 pro 两档
+- pro 全 ok
-- 缺 `DEEPSEEK_API_KEY` 时报清晰错误,不崩
 
-### 3. 会话与持久化
+**Phase 6 部分**(2026-05-06):
-- `core/session.py`: 内存消息列表 + 元数据 + 落盘 JSON,文件格式
+- `core/task.py` + `workspace/tasks/<id>/{state.json, messages.json}` —— TaskState 跟 mode/desc/status/tokens/timestamps;`build_agent` 返 5 元组;`sync_task_tokens` 每轮后写回
-  ```json
+- CLI 新增 `tasks` 子命令 + REPL `/status /done /abandon /desc`;`chat` 加 `--mode --desc` 选项
-  {"meta": {"id","created_at","cwd","model","model_profile"}, "messages": [...]}
+- 移除 legacy `workspace/sessions/` 兼容(单一布局)
-  ```
-  老格式(纯 list)向后兼容
-- 每次 `cli.py chat` 启动一个新 session,文件名 `workspace/sessions/<YYYYMMDD_HHMMSS>.json`
-- 支持: `--resume last` / `--resume <id>`;resume 时若当前 cwd 与记录不同会警告
-- REPL 命令: `/exit /reset /new /id`
-- `cli.py sessions` 列表显示 id / msgs / cwd / 第一条用户消息预览
-
-### 4. ReAct 主循环
-- `core/loop.py`: LLM ↔ tool 循环,无 tool_calls 即返回
-- LLM 调用包了 `console.status("thinking...", spinner="dots")` 转圈点
-- 工具结果对模型截断到 16K 字符,对用户预览 400 字符
-- 所有日志走 `rich.Console`,彩色
-
-### 5. 通用工具
-- `tools/base.py`: `Tool` 基类 + `_resolve` 路径解析
-- `tools/fs.py`:
-  - `read` —— 带行号,支持 offset/limit
-  - `write` —— 自动建父目录,覆写
-  - `edit` —— old_str **唯一匹配**约束(CoreCoder 风格)
-  - `glob` —— `**/*.py` 等模式
-  - `grep` —— Python 正则,自动跳过 `.git node_modules __pycache__ .venv venv dist build`
-- `tools/shell.py`: subprocess 执行,黑名单拦 `rm -rf /` 等;默认 60s 超时
-- `tools/run_python.py`: subprocess 跑临时 .py 文件,过滤 `*API_KEY *TOKEN *SECRET *PASSWORD *PRIVATE_KEY` 环境变量
-
-### 6. Skill 系统(Anthropic 渐进披露标准)
-- `core/skills.py`: `SkillRegistry` 扫描 `skills/<name>/`,只读 SKILL.md frontmatter 做 discovery
-- `tools/skill_tool.py`: `load_skill(name)` 工具返回完整 SKILL.md 给模型
-- 三个 skill,均按 WHY+WHAT 风格写,不写 Step 1/2/3:
-  - `skills/coding/SKILL.md`
-  - `skills/ppt/` —— 完整渐进披露结构(借鉴 hugohe3/ppt-master 的两阶段 + spec lock 思路):
-    - `SKILL.md`(两阶段工作流 + ⛔ blocking 八条对齐 + 红色硬约束 + 强制封面/尾页 + 反模式)
-    - `references/design_principles.md`(§0 画布 + §1-9 字号/配色/留白/字数预算/图表)
-    - `references/layouts.md`(9 种版式 + `apply_brand(slide, kind)` 品牌条覆盖每页 + assert_inside)
-    - `references/icons.md`(业务图标两层:Iconify / unicode 兜底;MSO_SHAPE 退为 layouts.md helper 内部几何原语)
-    - `assets/icons/INDEX.md`(本地图标库索引 + 推荐清单)
-    - `scripts/fetch_icon.py`(Iconify CDN 拉个性化 SVG/PNG,主题色染色,缓存本地)
-    - `scripts/quality_check.py`(页数/标题/bullet/字号/配色 + shape 越界 + 文本溢出估算)
-    - `scripts/source_to_md.py`(PDF/DOCX/PPTX/URL → Markdown)
-    - `scripts/render_icon.py`(unicode 字形 → 透明 PNG,兜底)
-    - **配色**:商务红 PRIMARY `#C00000` / SECONDARY `#E15554` / ACCENT `#FFC107` —— v3 改为硬约束,模型不能基于"场景判断"自行换色
-    - **品牌条**:v3 加 `apply_brand(slide, kind)`,所有版式起手必调,4 种模式 (cover/inner/section/end) 覆盖左竖条 + 浅底,不再裸白纸
-    - **图标**:v3 加 Iconify CDN 拉取链路 (tabler/lucide/heroicons/material-symbols 等 150+ 集),本地缓存复用
-  - `skills/proposal/SKILL.md`(含工作目录约定 + 字数表 + python-docx 合并模板)
-
-### 7. System Prompt
-- `prompts/system/general_v1.md`(无版本化软链接,直接引用 v1)
-- 启动时拼接顺序: 通用指引 → discovery 块(skill 列表) → 当前工作目录
-
-### 8. Capability Probing(Phase 4)
-- `core/probe.py`:四项探测 + ProbeReport
-  - `probe_basic_chat` —— 连通性,失败则跳过其余
-  - `probe_parallel_tools` —— 给两个独立工具,看 single response 里 tool_calls 数 ≥2
-  - `probe_thinking_mode` —— 对 declared=True 的模型传 reasoning_effort,看 API 接受 + 是否产出 reasoning_content/thinking
-  - `probe_long_context` —— needle-in-haystack 简化版,默认 reliable_context * 4 / 8 字符,上限 200K(opt-in,需 `--long-context`)
-- `cli.py probe [--model X] [--long-context]`:rich Table 输出;退出码 0=全 ok / 2=有 mismatch / 3=有 error
-- 不修改 yaml,只报告差异——是否调档案由用户决定
-- 不进启动路径(每次启动跑会烧 API),用户显式触发
-
-### 9. Task 概念 + state.json(Phase 6)
-- `core/task.py`:`TaskState` dataclass(对齐 DESIGN.md §7.1)
-  - 字段:task_id / mode / description / status (active/completed/abandoned) / model / model_profile / reasoning_effort / cwd / created_at / updated_at / tokens_prompt / tokens_completion / cost_usd
-  - `save(task_dir)` / `load(task_dir)`,加载时容忍未知字段(schema 演化)
-- 存储布局:`workspace/tasks/<task_id>/{state.json, messages.json}`
-- `main.build_agent` 返回 5 元组 `(agent, session, sid, task_state, task_dir)`
-- `main.sync_task_tokens(state, dir, llm)`:每轮 agent.run 后调,把 LLM 累计 tokens 写回 state.json
-- CLI:
-  - `chat --mode coding --desc "修一处 bug"`(可选元数据)
-  - REPL:`/status` 看 state、`/done` 标完成、`/abandon` 标弃、`/desc <文本>` 改描述
-  - `cli.py tasks [--status active|completed|abandoned]`:列任务,显示 mode/model/msgs/tokens/desc
-- 已知小坑:`Session.save()` 不原子,write_text 抛错(如 stdin 注入了 UTF-8 surrogate 半字符)会留下 0 字节文件——交互使用没问题,后续可加 tmp+rename
 
 ---
 
@@ -115,71 +40,43 @@
 
 | 项 | 决策 | 与设计差异 |
 |---|------|-----------|
-| 工具基目录 | 用户当前 cwd,不是 workspace/ | 设计未明说;选 cwd 是因为 agent 该操作用户的项目 |
+| 工具基目录 | 用户当前 cwd | 设计未明说;agent 该操作用户项目 |
-| Workspace 用途 | `tasks/<id>/{state.json, messages.json}`;memory/ 待 Phase 6 双层记忆 | 设计含 `tasks/ memory/ logs/`,部分落地 |
+| Workspace 用途 | `tasks/<id>/{state.json, messages.json}` | memory/ 待 Phase 6 双层记忆 |
-| Session 粒度 | 一个目录一个 task,含 state.json | Phase 6 落地;DESIGN.md §7.1 字段对齐 |
+| Eval Suite | 不做 | 设计为团队场景;个人工具 dogfooding 替代 |
-| Eval Suite | 决定不做 | DESIGN.md §6.3 设计为团队/产品场景;个人工具用 dogfooding 替代,probe 覆盖健康检查 |
+| 版本化 prompt | 直接 `general_v1.md`,无 active.md 软链接 | Windows 软链接麻烦,真要切版本时再做 |
-| 版本化 prompt | 直接 general_v1.md,无 active.md 软链接 | Windows 软链接麻烦;后续要切版本时再做 |
+| run_python 沙盒 | subprocess + env 过滤 | 阶段 1 设计如此;Docker 待 Phase 7 |
-| run_python 沙盒 | subprocess + env 过滤 | 设计阶段 1 就是这套,未升级 Docker |
-| 工具数 | 8 个 (read/write/edit/glob/grep/shell/run_python/load_skill) | 设计上限 ≤10 同时可见,目前刚好 |
-
----
-
-## 验收过的测试
-
-- 全项目 `ast.parse` 语法 OK
-- yaml 配置可解析
-- 所有 import 链路在 venv 中跑通
-- `cli.py --help` / `cli.py chat --help` / `cli.py tasks --help` / `cli.py probe --help` 正常
-- `SkillRegistry` 识别出 3 个 skill,discovery 块拼装正确
-- 缺 `DEEPSEEK_API_KEY` 时报清晰错误
-- 实测 DeepSeek API 接通,`flash` 和 `pro` 两档都能调通
-- **真实 probe 结果**(2026-05-06):
-  - `deepseek_v4.flash`:basic_chat ok / **parallel_tools mismatch**(yaml=false, observed=true,2 个 tool_calls)/ thinking_mode skip(declared false)
-  - `deepseek_v4.pro`:basic_chat ok / parallel_tools ok / thinking_mode ok(reasoning_content 返回)
-  - flash 的 mismatch 暂不自动改 yaml —— `parallel_tools=true` 会影响所有实际调用,需更多场景观察后再决定
-
----
-
-## 已知遗留 / 下一步候选
-
-按性价比排序:
-
-1. **Phase 6 双层记忆**(~半天)—— `workspace/memory/core.md` 注 prompt + `extended/` 按需读
-2. **Phase 6 context 三层压缩**(~1 天)—— 兜底用,V4 长上下文一般用不到
-3. **小修打磨**(~半小时)—— `Session.save()` 改原子写(tmp + rename),防 surrogate 等异常 truncate
-4. **Phase 7 Docker 沙盒**(~1 天)—— 替换 subprocess,run_python 安全升级
-5. **Phase 7 更多 skill / 模型档案**(持续)
 
 ---
 
 ## 文件清单(代码量)
 
 ```
-core/capabilities.py        71 行
+core/capabilities.py        71
-core/llm.py                 89 行
+core/llm.py                 89
-core/loop.py                99 行
+core/loop.py                99
-core/probe.py              243 行   ← Phase 4
+core/probe.py              243   ← Phase 4
-core/session.py             77 行
+core/session.py             77
-core/skills.py              81 行
+core/skills.py              81
-core/task.py                63 行   ← Phase 6
+core/task.py                63   ← Phase 6
-tools/base.py               34 行
+tools/base.py               34
-tools/fs.py                182 行
+tools/fs.py                182
-tools/shell.py              63 行
+tools/shell.py              63
-tools/run_python.py         84 行
+tools/run_python.py         84
-tools/skill_tool.py         45 行
+tools/skill_tool.py         45
-main.py                    175 行   ← +tasks 布局 / TaskState 装配
+main.py                    175   ← Phase 6 task 装配
-cli.py                     265 行   ← +probe / +tasks 子命令
+cli.py                     265   ← +probe / +tasks 子命令
 ─────────────────────────────────
-合计 Python               ~1571 行
+Python 合计              ~1571 行
-
-prompts/system/general_v1.md
-skills/coding/SKILL.md
-skills/ppt/SKILL.md
-skills/proposal/SKILL.md
-config/agent.yaml
-config/models/deepseek_v4.yaml
-requirements.txt
 ```
 
-设计预估 Phase 1-3 大约 800-1000 行,实际 1083 行,加上 Phase 4 + Phase 6 约 1571 行 Python。
+加上 skills/ppt 下的脚本(~600 行)、SKILL.md / references / config / prompts,总仓库约 2500 行可读源码。
+
+---
+
+## 下一步候选(性价比排序)
+
+1. **Phase 6 双层记忆**(~半天)—— `workspace/memory/core.md` 注 prompt,`extended/<topic>.md` 按需读
+2. **Phase 6 context 三层压缩**(~1 天)—— 兜底用,V4 长上下文一般用不到
+3. **小修打磨**(~半小时)—— `Session.save()` 改原子写(tmp + rename),防 surrogate 等异常 truncate
+4. **Phase 7 Docker 沙盒**(~1 天)—— 替换 subprocess,run_python 安全升级
+5. **Phase 7 更多 skill / 模型档案**(持续)