155 lines
7.2 KiB
Markdown
155 lines
7.2 KiB
Markdown
# 实施进度
|
|
|
|
> 配合 `DESIGN.md` 阅读。本文件记录已完成的事、关键决策、与原设计的偏差。
|
|
|
|
最后更新: 2026-05-06 (PPT skill 完善:references + scripts;v2 加图标系统 + 安全区 + 越界检测 + 默认红色主题)
|
|
|
|
---
|
|
|
|
## 总体状态
|
|
|
|
| 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,文件格式
|
|
```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`(两阶段工作流 + 八条对齐 + 默认红色主题 + 反模式)
|
|
- `references/design_principles.md`(字号/配色/留白/图表 + §4.1 **字数预算表**)
|
|
- `references/canvas_presets.md`(16:9 / 4:3 / 9:16 等画布表)
|
|
- `references/layouts.md`(9 种轻量版式 + **safe area 起手** + assert_inside / TEXT_TO_FIT_SHAPE 兜底)
|
|
- `references/icons.md`(MSO_SHAPE 图标目录 + unicode 字形表 + 5 个标准图标 helper)
|
|
- `scripts/quality_check.py`(页数/标题/bullet/字号/配色 + **shape 越界 + 文本溢出估算**)
|
|
- `scripts/source_to_md.py`(PDF/DOCX/PPTX/URL → Markdown,策略阶段输入)
|
|
- `scripts/render_icon.py`(unicode 字形 → 透明 PNG,MSO_SHAPE 兜底)
|
|
- **默认配色**:商务红 PRIMARY `#C00000` / SECONDARY `#E15554` / ACCENT `#FFC107`
|
|
- `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 —— **接入路径已通**
|
|
|
|
---
|
|
|
|
## 已知遗留 / 下一步候选
|
|
|
|
按性价比排序:
|
|
|
|
1. **Phase 4 capability probing**(~半天)—— 启动时跑 needle-in-haystack / 并行 tool 探测,把 yaml 声称的能力对账
|
|
2. **Phase 5 Eval Suite**(~2 天)—— 模型升级决策的依据。每类任务 3-5 个 case,客观 + LLM judge 双评分
|
|
3. **Phase 6 task 概念 + state.json**(~1 天)—— 让 session 升级为任务,workspace 加 `tasks/<task_id>/`
|
|
4. **Phase 6 context 三层压缩**(~1 天)—— 兜底用,V4 长上下文一般用不到
|
|
5. **Phase 6 双层记忆**(~半天)—— `workspace/memory/core.md` 注 prompt + `extended/` 按需读
|
|
6. **Phase 7 Docker 沙盒**(~1 天)—— 替换 subprocess,run_python 安全升级
|
|
7. **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 行,略多但仍在可读范围。
|