42 lines
2.6 KiB
Markdown
42 lines
2.6 KiB
Markdown
# zcbot 开发笔记 (给 Claude Code)
|
|
|
|
## 环境
|
|
|
|
- **Python 虚拟环境**: `.venv/`(项目根目录下),所有依赖装在里面
|
|
- 跑脚本 / 测试一律用 `.venv/Scripts/python.exe ...`,**不要用全局 `python`**(没装 litellm/python-pptx 等会报 ModuleNotFoundError)
|
|
- requirements 见 `requirements.txt`
|
|
|
|
## 开发阶段心智
|
|
|
|
当前处于**开发测试期**(开发自用 + 内部测试,DB 已有真实测试数据)。改需求 / 重构时,**以最优实现为准,不为旧数据 / 旧字段 / 旧 API 留兼容层**,但**不删现有数据**:
|
|
- DB schema 变 → 直接改 model + 写一条干净的 migration:加列 / 改列结构 OK;**不要 truncate / DELETE FROM 现有表 —— 测试数据要保留**
|
|
- 删字段(DROP COLUMN)前:若该列是当前唯一持有该信息(如累计型 tokens 列),先 backfill 到新位置再删;若纯冗余(从其他列能推出)直接删 OK
|
|
- 字段语义变 → 全量替换 + migration 把旧值映射到新值(不留 `legacy_xxx` / `*_v2` 并存)
|
|
- CLI / REPL 选项变 → 直接改,不留 deprecated 别名
|
|
- 只有当用户明确说"这条要保留兼容"时才写兼容代码
|
|
|
|
理由:兼容层是技术债;但测试数据是观察新代码行为的依据 —— 一次 truncate 后再回去查"上周那 task 烧了多少 token / 哪条消息触发的 bug",就只能瞎猜。
|
|
|
|
## 文档维护
|
|
|
|
每完成一步实现(commit 前),**必须更新 `PROGRESS.md`**:
|
|
- "已完成关键能力" 段加一条 `YYYY-MM-DD / <短标题>:<改了什么>`
|
|
- 状态表(§7 B Step 几 / Phase 几)若变化跟着改
|
|
- 文件清单若新增 / 删除模块跟着改
|
|
|
|
**只有以下情况才动 `DESIGN.md`**(避免把工程笔记沉淀成设计):
|
|
- 架构 / 心智模型变化(如 §7.1 task-primary 重写)
|
|
- 取舍决策推翻或新增(§5 / §7.9 类内容)
|
|
- API / schema 字段语义变化(§7.2 / §7.4)
|
|
- 实施中发现 DESIGN 描述与代码偏离 → 同步改回
|
|
|
|
bug 修复、重构、新加 skill、调参 —— **不动 DESIGN**,只更 PROGRESS。
|
|
|
|
**改任何对外行为(CLI 选项 / REPL 命令 / env 变量 / 文件布局 / migration 步骤)→ 同步更新 `RUN.md`**:
|
|
- 新加 / 改 / 删 CLI 子命令 + 选项时,改"日常命令"段
|
|
- env 变量 / 启动初始化变化时,改"环境" / "一次性初始化"段
|
|
- 真实踩过的坑(用户报或自己跑出来),加一行到"故障兜底"表
|
|
- 纯内部重构 / 不影响用户怎么跑的 —— **不动 RUN**
|
|
|
|
三文档边界:`DESIGN`=为什么(架构 / 取舍),`PROGRESS`=做到哪(状态 / 历史),`RUN`=怎么跑(命令 / env / 兜底)。一次改动可能动多个,但每个动的理由要符合上述边界。
|