Add Codex project guidance and memory
This commit is contained in:
parent
eab623d5b5
commit
d4965e196c
|
|
@ -0,0 +1,64 @@
|
|||
# zcbot 项目记忆（Codex）
|
||||
|
||||
更新时间：2026-07-27。内容从 Claude 项目 memory 迁移并按 Codex 使用方式压缩。`AGENTS.md` 存放每次任务都适用的强约束；本文件存放遇到相关问题时再读取的历史结论。若历史结论与当前代码、`DESIGN.md`、`PROGRESS.md` 或 `RUN.md` 冲突，以当前仓库事实为准并指出差异。
|
||||
|
||||
## 用户偏好与长期原则
|
||||
|
||||
- 一律使用中文与用户沟通。
|
||||
- Windows Python 脚本 stdout 可能是 GBK：使用 ASCII 状态标签，不用 emoji 或特殊装饰字符。
|
||||
- `CHANGELOG.md` 提到海外模型时只用“国际旗舰模型”等泛称；具体型号只放在 `PROGRESS.md`、配置和 git log。
|
||||
- 版本、CHANGELOG、PROGRESS 在 push 前统一更新；DESIGN 跟随产生架构或决策变化的 commit。
|
||||
- 真实文件是事实源，不引入向量机制作为事实源；索引只能是可从 Markdown 重建的派生缓存。
|
||||
- skill 禁令不写违规配方；脚本错误不向 agent 推荐安装命令或替代管线；真正硬约束检查产物。
|
||||
|
||||
## 生产与环境
|
||||
|
||||
- 本机 `.env` 的 `ZCBOT_DB_URL=127.0.0.1:6012...` 是生产数据库隧道。数据库测试必须显式使用 `ZCBOT_TEST_DB_URL`，绝不能默认读取 `.env` 后向库中插入会被调度器执行的任务。
|
||||
- 生产机 `/data` 是独立的 `/dev/vdb1`、ext4、约 1 TB 数据盘。若执行 Stage C project quota，既定方案是短停服：停服务、卸载 `/data`、为 ext4 开启 project/quota、fstab 加 `prjquota`、重新挂载；每用户限额取 `config/agent.yaml`。
|
||||
|
||||
## 已落地机制
|
||||
|
||||
- 知识库于 2026-07-22 以 0.59.0 落地，设计见 `DESIGN.md` §3.8。它是机制而非 skill：个人小库使用 `<user_root>/.kb/<库名>/` 下的纯文件、INDEX、docs 和 sources；共享大库走院检索服务。agent 通过文件工具检索，不新增向量事实源。
|
||||
- 方舟文档理解已落地到 `tools/read_document.py`：`doubao-seed-2-0-lite-260428` 可通过 `file_data` 的 `data:application/pdf;base64,...` 读取扫描 PDF；单页约 3600 万像素上限，约 100 页上下文上限。相关六个 skill 已有扫描件兜底。探针在 `scripts/probe_ark_doc.py`。
|
||||
- paper_server 的历史 handoff 已完成：当前已有 `skills/research/SKILL.md`、`skills/research/paper.py`，不要把 `.claude/HANDOFF_paper_skill.md` 当作待办。
|
||||
|
||||
## 智能体稳定性历史结论
|
||||
|
||||
### 高轮数与重复调用
|
||||
|
||||
2026-06 的真实任务诊断确认三类根因：
|
||||
|
||||
1. 畸形 tool arguments 退化为合法空 `{}`，旧 malformed 检查未拦截；
|
||||
2. 工具报错后原样重复调用；
|
||||
3. 检索 query 不断微调但没有停止条件。
|
||||
|
||||
已通过批量工具与 `core/loop.py::_RepeatGuard` 缓解：同一工具与参数在无产出时累计，软阈值提示、硬阈值拦截。相关回归测试是 `tests/test_loop_repeat_guard.py`，诊断脚本位于 `scripts/diag_tool_repeat.py`、`diag_search_args.py`、`diag_error_retry.py`。
|
||||
|
||||
### 流式畸形 tool_call
|
||||
|
||||
DeepSeek 及部分网关模型曾把 arguments 流切片乱序，属于 provider wire 问题而非本地 builder 拼接。0.58.24 已在 `core/salvage.py::salvage_tool_arguments` 与 loop 中落地全有或全无的 salvage：从后缀寻找可完整解析的 JSON，并以工具 schema 顶层 key 白名单保护；无法恢复时继续走非流式重试。线上复盘显示 salvage 命中率约 85%，残差可由重试自愈，不应再次改 builder。观测事件为 `tool_salvaged` / `tool_malformed`，测试见 `tests/test_salvage.py`。
|
||||
|
||||
### GLM 空响应烧满输出
|
||||
|
||||
GLM 5.2 的空响应根因是网关默认开启 thinking，推理耗尽模型 65536 输出上限，返回 `finish_reason=length` 且无 content/tool_call。0.58.49 已按 GLM family 透传 `extra_body.thinking.type`，当前配置关闭 thinking，并记录空响应 finish_reason。
|
||||
|
||||
不要重新引入全局 `max_tokens` 窗口约束：该方案已探针验证后撤销，未解决根因且可能截断合法大 write。若未来需要成本闸，应设计任务级 token budget。
|
||||
|
||||
### unifyllm Claude tool_use 漏为正文
|
||||
|
||||
曾出现复杂请求下 Anthropic `tool_use` 未转换为 OpenAI `tool_calls`、直接漏成 Markdown 正文，loop 因 `tool_calls=[]` 误判完成。诊断脚本 `scripts/diag_narrated_toolcall_2a1bc25d.py` 曾稳定复现，但 2026-07-15 当日复测 6/6 已恢复，判断为网关瞬态或已修。复测时必须显式传 profile，不能依赖 task 当前模型。它与 arguments 畸形是不同问题，salvage 无法处理没有结构化 tool_call 的正文泄漏。
|
||||
|
||||
## 沙箱与 Chromium
|
||||
|
||||
Mermaid/Chromium 的历史故障最终有三个根因：
|
||||
|
||||
1. `init.sh` 对 `127.0.0.0/8 DROP` 阻断容器内 Puppeteer 到 Chromium DevTools，表现为恒定约 2 分 15 秒超时且 CPU 接近零；已改为优先允许 loopback。
|
||||
2. Chromium 150.0.7871.46 点版本启动即崩；已增加刷新旋钮和 build canary。
|
||||
3. `--pids-limit=256` 过低；已调到 1024。
|
||||
|
||||
排查同类问题必须用默认 entrypoint 和生产一致的 network/limits 启容器后再 `docker exec`。使用 `--entrypoint bash` 会绕过 `init.sh` 与 iptables，不能代表线上。build canary 也没有运行时 iptables，只能覆盖浏览器和字体问题。探针位于 `deploy/sandbox/probe_mermaid.sh`、`probe_chromium_bisect.sh`、`probe_chromium_round3.sh`。
|
||||
|
||||
## 领域
|
||||
|
||||
用户单位是中国建筑材料科学研究总院。代码、库、模板和示例默认服务于水泥/混凝土、玻璃、陶瓷、耐火和新型建材的材料研发、表征分析、实验建模与科研写作；不是建筑施工、BIM 或结构设计语境。
|
||||
|
||||
|
|
@ -0,0 +1,62 @@
|
|||
# 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；任何连库写操作前都要再次确认目标。
|
||||
|
||||
## 文档与版本
|
||||
|
||||
- 版本号、`CHANGELOG.md`、`PROGRESS.md` 在 push 前统一更新一次，不按每个 commit 更新。
|
||||
- push 前更新 `PROGRESS.md`：补“已完成关键能力”条目，状态表变化随之更新，新增或删除模块时同步文件清单。
|
||||
- 版本号唯一事实源是 `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 理解需求。
|
||||
|
||||
Loading…
Reference in New Issue