zcbot/CLAUDE.md

zcbot 开发笔记 (给 Claude Code)

环境

• Python 虚拟环境: .venv/(项目根目录下),所有依赖装在里面
• 跑脚本 / 测试一律用 .venv/Scripts/python.exe ...,不要用全局 python(没装 litellm/python-pptx 等会报 ModuleNotFoundError)
• requirements 见 requirements.txt

Shell:别把 PowerShell 语法喂给 Bash 工具

PowerShell here-string @'...'@ 只在 PowerShell 工具里有效;用 Bash 工具跑会把首尾的 @ 当字面量塞进字符串(踩过:commit message 首尾混进 @ 行,只能 amend + force-push 收拾)。规矩:

• 多行文本(commit message / 文件内容)优先写进临时文件,再用 -F <file> / 重定向喂命令,绕开两种 shell 的引号差异 —— 最稳。
• 必须内联多行时:Bash 工具用 $'...\n...' 或 heredoc <<'EOF';PowerShell 工具才用 @'...'@。别混。
• 一句话:先看自己在用哪个工具(Bash vs PowerShell),再选对应语法。

实施前先对方案

非平凡改动(改 >1 个文件 / 涉及行为变化 / 多个候选方案有取舍)动手前先用自然语言把方案讲给用户确认,认可后再写代码。一次性 bug 修复 / 改字面量 / 样式微调 / 加日志这类无歧义动作可以直接动手。

讲方案时要包含:

• 问题定位(指到具体文件 / 行号 / 当前行为)
• 至少 1 个替代方案 + 当前方案为什么更优
• 涉及性能 / 兼容 / 数据迁移时主动说

理由:开发期需求漂移快,写到一半被推翻代价高 —— 口头对齐方案是最低成本的纠偏机会。

开发阶段心智

当前处于开发测试期(开发自用 + 内部测试,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 几)若变化跟着改
• 文件清单若新增 / 删除模块跟着改

每次 commit / push 必须 bump 版本号 —— 单一事实源是 core/__init__.py 的 __version__(web/app.py 的 FastAPI version、/healthz 返回、前端左栏底部展示都引这里,改版本只动这一行):

• patch(0.8.x):bug 修复 / 重构 / 调参 / 新加 skill / 样式
• minor(0.x.0):成批新功能 / 明显的对外行为变化
• major(x.0.0):1.0 正式发版 / 不兼容大重构
• 当前 0.x 开发期,未正式发版前不进 1.0

只有以下情况才动 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 / 兜底)。一次改动可能动多个,但每个动的理由要符合上述边界。

新增 / 修改 / 删除 skill(skills/<name>/SKILL.md)→ 同步更新 SKILL_LIST.md:这份是给外部人看的能力清单(分类 + 一句话 + 何时用 / 不用 + 典型产物 + 核心能力),改 skill 名 / 描述 / frontmatter / 新增删除 skill 都要跟着改,顺手把开头的"最后更新"日期和"Skill 总数"刷新;若新 skill 与已有 skill 有协作模式,补到末尾"跨 skill 协作"段。