65 lines
6.0 KiB
Markdown
65 lines
6.0 KiB
Markdown
# 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 理解需求。
|