zcdsj
/
zcbot
5
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
zcbot/PROGRESS.md

10 KiB
Raw Blame History

实施进度

配合 DESIGN.md 阅读。本文件记录已完成的事、关键决策、与原设计的偏差。

最后更新: 2026-05-06 (Phase 4 + Phase 6 task/state.json 落地;移除 legacy session 兼容;Phase 5 evals 决定不做)

总体状态

Phase 标题 状态 备注
1 最小可用骨架 ✅ 完成 全部验收点过
2 Skill 系统 + 三个 skill ✅ 完成 Anthropic 格式;coding/ppt/proposal
3 Hybrid 范式 (run_python) ✅ 完成 subprocess + 敏感 env 过滤
4 演化性能力 🟡 部分 Model Profile 已就位;capability probing ✅;版本化 prompts 未做
5 Eval Suite ⏸ 不做 个人工具,造作 case 没区分度;真换模型用 dogfooding 判断
6 长任务工程化 🟡 部分 task + state.json ✅;session 中断恢复 ✅;context 压缩、双层记忆未做
7 打磨 ❌ 未开始 Docker 沙盒 / 更多 skill / Web UI

已完成清单

1. 项目骨架

  • 目录: 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. 模型层

  • core/capabilities.py: ModelCapabilities 数据类,从 config/models/<family>.yaml 加载
  • core/llm.py: LiteLLM 封装,自动按 capabilities 启用 parallel_tools / reasoning_effort / prompt_caching / thinking_mode;指数退避重试
  • config/models/deepseek_v4.yaml: flash 和 pro 两档
  • 缺 DEEPSEEK_API_KEY 时报清晰错误,不崩

3. 会话与持久化

  • core/session.py: 内存消息列表 + 元数据 + 落盘 JSON,文件格式 
    {"meta": {"id","created_at","cwd","model","model_profile"}, "messages": [...]}
    老格式(纯 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

关键决策与偏差

项 决策 与设计差异
工具基目录 用户当前 cwd,不是 workspace/ 设计未明说;选 cwd 是因为 agent 该操作用户的项目
Workspace 用途 tasks/<id>/{state.json, messages.json};memory/ 待 Phase 6 双层记忆 设计含 tasks/ memory/ logs/,部分落地
Session 粒度 一个目录一个 task,含 state.json Phase 6 落地;DESIGN.md §7.1 字段对齐
Eval Suite 决定不做 DESIGN.md §6.3 设计为团队/产品场景;个人工具用 dogfooding 替代,probe 覆盖健康检查
版本化 prompt 直接 general_v1.md,无 active.md 软链接 Windows 软链接麻烦;后续要切版本时再做
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/llm.py                 89 行
core/loop.py                99 行
core/probe.py              243 行   ← Phase 4
core/session.py             77 行
core/skills.py              81 行
core/task.py                63 行   ← Phase 6
tools/base.py               34 行
tools/fs.py                182 行
tools/shell.py              63 行
tools/run_python.py         84 行
tools/skill_tool.py         45 行
main.py                    175 行   ← +tasks 布局 / TaskState 装配
cli.py                     265 行   ← +probe / +tasks 子命令
─────────────────────────────────
合计 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。