zcbot/AGENTS.md

zcbot 开发约定（Codex）

本文件是 Codex 的项目级入口，由 CLAUDE.md 与 Claude 项目 memory 迁移而来。进入项目后先读本文件；涉及历史故障、架构取舍、生产环境或用户偏好时，再读 .agents/MEMORY.md 中对应条目。详细设计、进度和运行方式分别以 DESIGN.md、PROGRESS.md、RUN.md 为准。

沟通

• 面向用户的回复、方案和解释一律使用中文；代码、命令和标识符保持原样。
• 非平凡改动（改动多个文件、改变行为或存在明显方案取舍）实施前先用自然语言对齐方案。说明具体定位、至少一个替代方案与选择理由；涉及性能、兼容或数据迁移时主动说明。
• 一次性 bug 修复、字面量修改、样式微调或加日志等无歧义动作可直接实施。

环境与 Shell

• Python 虚拟环境固定为项目根目录 .venv/，脚本和测试一律使用 .venv/Scripts/python.exe ...，不要使用全局 python。
• 依赖以 requirements.txt 为准。
• 当前默认 shell 是 PowerShell。PowerShell here-string @'...'@ 不能交给 Bash；Bash 的 heredoc 或 $'...\n...' 也不要照搬到 PowerShell。
• 多行文本优先交给项目编辑工具；确需传给命令时使用明确的临时文件，避免跨 shell 引号污染。
• Windows 控制台可能使用 GBK。项目 CLI/脚本的 stdout 使用 ASCII 标签（[OK]、[WARN]、[ERR]、[INFO]），不要输出 emoji、特殊项目符号或装饰线；文档正文不受此限制。

公测期兼容原则

项目已有真实用户、真实数据和线上会话。对外契约必须向后兼容，纯内部实现可按最优方案重构。

• 用户数据：不得 truncate、DELETE FROM 清库或重置现有表。
• DB schema：变更必须有干净 migration，并平滑兼容存量数据；删除字段前先 backfill、确认无引用。
• 字段语义：迁移旧值，并考虑线上旧请求与新代码并行期间的兼容。
• HTTP API：不删除既有字段、不改变字段语义、不直接改 URL；先增加新字段或端点，并为旧接口保留废弃窗口。
• CLI、REPL、环境变量和文件布局：改名或删除前保留 deprecated 别名至少一个版本，并在 RUN.md 标注。
• 纯内部模块、函数和私有数据流可直接重写，不保留无意义的 legacy_* 或 *_v2 双轨。
• 无法判断是否属于外部契约时，按外部契约处理并先对齐方案；仅在用户明确允许 break 时做破坏性变更。

数据库安全

• 本机 .env 中的 ZCBOT_DB_URL（127.0.0.1:6012）通过隧道连接生产 PostgreSQL，不是开发库。
• DB 测试只能使用显式的 ZCBOT_TEST_DB_URL，不得回退到 .env。
• 不得向该生产库写入启用状态且已到执行时间的 scheduled job；任何连库写操作前都要再次确认目标。

文档与版本

• 开发 push 与正式发布分离：功能开发期间允许持续 commit / push，不因此提升版本号，也不新增已发布的 CHANGELOG.md 数字版本条目。
• 尚未发布但需要预先整理的用户文案写在 CHANGELOG.md 顶部 ## Unreleased；该区不会被前端更新日志接口解析。正式发布时再把它改成 ## <版本> — <日期>。
• 版本号与用户版 CHANGELOG.md 只在功能稳定、准备上线时通过单独的 release commit 统一更新；同一次发布中校准 PROGRESS.md，不按每个开发 commit 更新。
• 阶段性成果可随开发更新 PROGRESS.md；正式发布前补“已完成关键能力”条目，状态表变化随之更新，新增或删除模块时同步文件清单。
• 未完成且不能让线上用户接触的功能，应在独立功能分支开发、待稳定后合并生产分支；若必须提前合并或部署，则使用默认关闭的 feature flag，并限制为管理员或测试账号启用。
• 版本号唯一事实源是 core/__init__.py::__version__：
  • patch：bug 修复、重构、调参、新 skill、样式；
  • minor：成批新功能或明显对外行为变化；
  • major：正式 1.0 或不兼容大重构。
• 当前公测期保持 0.x；1.0 留给正式 GA 和对外契约冻结。
• 用户可感知的版本变化才写 CHANGELOG.md，措辞面向用户，不写内部模块、环境变量或部署细节。涉及海外模型时使用“国际旗舰模型”等泛称，不写具体型号。
• DESIGN.md 仅在架构、心智模型、取舍决策、API/schema 语义变化，或设计与代码发生偏离时更新，并随触发该变化的 commit 提交。普通 bug 修复、重构、调参、新 skill 不更新 DESIGN。
• 对外 CLI、REPL、env、文件布局或 migration 步骤变化时同步更新 RUN.md；真实踩坑补入其“故障兜底”。
• 文档边界：DESIGN.md 解释为什么，PROGRESS.md 记录做到哪，RUN.md 说明怎么运行。
• 新增、修改或删除 skills/<name>/SKILL.md 时同步更新 SKILL_LIST.md 的日期、总数、能力说明和必要的跨 skill 协作关系。

设计偏好

• 真实文件是事实源。检索和知识功能优先采用 Markdown 文件、人可读索引与 glob/grep/read 的 agentic search。
• 不把向量库或 embedding 作为事实源。若未来确有规模与频率数据支持，只能添加可从 Markdown 全量重建的派生索引。
• 大规模、高并发共享检索使用院内外部检索服务，不在 zcbot 内重复建设检索服务。
• 编写 skill 和提示词时，使用正面的唯一入口约束；禁令不要附带可执行的违规配方。脚本报错不要给 agent 输出 pip install 或替代工具指令；硬约束优先在平台层检查最终产物。

领域语境

主要使用方是中国建筑材料科学研究总院，核心语境是无机非金属材料研发与生产，包括水泥、混凝土、玻璃、陶瓷、耐火材料和新型建材。典型任务是配方研发、性能测试、XRD/SEM/热分析、实验数据建模，以及申报书、调研报告、专利和论文写作。默认按材料研发而非建筑施工、结构计算或 BIM 理解需求。