7.7 KiB

Raw Blame History

实施进度

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

最后更新: 2026-05-06 (PPT skill v3:红色硬约束 + ⛔ blocking + canvas 合并 + apply_brand 品牌条 + 强制尾页 + Iconify 图标库)

总体状态

Phase	标题	状态	备注
1	最小可用骨架	✅ 完成	全部验收点过
2	Skill 系统 + 三个 skill	✅ 完成	Anthropic 格式;coding/ppt/proposal
3	Hybrid 范式 (run_python)	✅ 完成	subprocess + 敏感 env 过滤
4	演化性能力	🟡 部分	Model Profile 已就位;capability probing 未做;版本化 prompts 未做
5	Eval Suite	❌ 未开始
6	长任务工程化	🟡 部分	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 列表) → 当前工作目录

关键决策与偏差

项	决策	与设计差异
工具基目录	用户当前 cwd,不是 workspace/	设计未明说;选 cwd 是因为 agent 该操作用户的项目
Workspace 用途	只存 sessions/(暂时)	设计含 `tasks/ memory/ logs/`,后续 Phase 6 再加
Session 粒度	一个文件一个 session,无 task 概念	设计有 task_id / state.json,Phase 6 再加
版本化 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 sessions --help 正常
SkillRegistry 识别出 3 个 skill,discovery 块拼装正确
缺 DEEPSEEK_API_KEY 时报清晰错误
实测 DeepSeek API 接通(deepseek-v4-flash 模型 ID 被认),仅因账户余额不足而返回 InsufficientBalance —— 接入路径已通

已知遗留 / 下一步候选

按性价比排序:

Phase 4 capability probing(~半天)—— 启动时跑 needle-in-haystack / 并行 tool 探测,把 yaml 声称的能力对账
Phase 5 Eval Suite(~2 天)—— 模型升级决策的依据。每类任务 3-5 个 case,客观 + LLM judge 双评分
Phase 6 task 概念 + state.json(~1 天)—— 让 session 升级为任务,workspace 加 tasks/<task_id>/
Phase 6 context 三层压缩(~1 天)—— 兜底用,V4 长上下文一般用不到
Phase 6 双层记忆(~半天)—— workspace/memory/core.md 注 prompt + extended/ 按需读
Phase 7 Docker 沙盒(~1 天)—— 替换 subprocess,run_python 安全升级
Phase 7 更多 skill / 模型档案(持续)

文件清单(代码量)

core/capabilities.py        71 行
core/llm.py                 89 行
core/loop.py                99 行
core/session.py             77 行
core/skills.py              81 行
tools/base.py               34 行
tools/fs.py                182 行
tools/shell.py              63 行
tools/run_python.py         84 行
tools/skill_tool.py         45 行
main.py                    120 行
cli.py                     138 行
─────────────────────────────────
合计 Python               1083 行

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 行,略多但仍在可读范围。

7.7 KiB Raw Blame History

实施进度

总体状态

已完成清单

1. 项目骨架

2. 模型层

3. 会话与持久化

4. ReAct 主循环

5. 通用工具

6. Skill 系统(Anthropic 渐进披露标准)

7. System Prompt

关键决策与偏差

验收过的测试

已知遗留 / 下一步候选

文件清单(代码量)

7.7 KiB

Raw Blame History