From d4965e196caa2e0746978ed709145a5a63b5e622 Mon Sep 17 00:00:00 2001
From: caoqianming <caoqianming@foxmail.com>
Date: Mon, 27 Jul 2026 10:38:31 +0800
Subject: [PATCH] Add Codex project guidance and memory

---
 .agents/MEMORY.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++
 AGENTS.md         | 62 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 126 insertions(+)
 create mode 100644 .agents/MEMORY.md
 create mode 100644 AGENTS.md

diff --git a/.agents/MEMORY.md b/.agents/MEMORY.md
new file mode 100644
index 0000000..f732316
--- /dev/null
+++ b/.agents/MEMORY.md
@@ -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 或结构设计语境。
+
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..3230740
--- /dev/null
+++ b/AGENTS.md
@@ -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 理解需求。
+