wiki-bot: Instructions file for Codex

AGENTS.md — wiki-bot

Re:Zero Fandom Wiki（https://rezero.fandom.com/zh）的维护机器人，基于 Pywikibot。 主要工作：把英文站内容同步到中文站，并对中文站做译名/格式规范化。

知识归处（docs/ vs project skill vs profile skill）

• 与本仓库/wiki 绑定的知识只写进本仓库、随 git 提交——这是唯一权威来源。两个落点：
  • docs/：数据/记录/被代码消费的文档（模板盘点、Module 审查、429 考据、翻译管线、todo 等）；
  • .agents/skills/：流程型知识（project-local skills，Hermes 按 description 索引触发、按需加载）。
• 项目 skill 的维护：用文件工具编辑 + git 提交，不用 skill_manage（其 create 写进 profile 目录）；curator 不会改项目 skill。新 clone 后 Hermes 需在本仓库跑一次 hermes skills trust 才加载（banner 会提示）。
• profile skill（~/.hermes/skills/）禁止存仓库知识：它在仓库之外、不随代码走，曾漂移出相互矛盾的副本。任务收尾时的知识落盘是主 agent（有文件工具）的职责；回合结束后的后台 skill review（只有 memory/skill 工具的 fork agent）对本仓库知识应直接放弃（'Nothing to save'）。
• 判断标准是「知识从哪里来、在哪里验证」，不是「理论上能不能用在别处」：源自本仓库实践的 pywikibot / Fandom / Cloudflare 限流 / 模板审计等知识，即使看似通用，也算本仓库知识。
• profile skill 只用于跨仓库/跨资源的流程（例如译名核验横跨 OCR 语料库与 gh issue）。新建前检查内容不与 docs/、.agents/skills/ 重复。
• 文档记录原则：规则、原因、不变量进文档；仓库自身的变更事件（何时改了什么、谁改的）归 git log，不写编年史——文档里出现「2026-xx-xx 改了某文件」类句子即腐化信号。两类例外保留日期：对外部系统的实测观测（Fandom/Cloudflare 行为，日期=时效元数据）、wiki 侧决策与状态（wiki 没有决策日志，这里是唯一记录处）。

环境

• Python >=3.14（pyproject.toml；当前解释器选择见 .python-version），uv 管理，有 uv.lock。
• 安装：uv sync（default-groups = "all"）。pywikibot 的全部可选依赖以 extras 形式声明在 dev 组（pywikibot[html,http,...]），覆盖其 requirements.txt，随 submodule 更新自动跟随。
• 运行脚本：uv run python <script>（仓库根目录）。uv 按 cwd 的 pyproject.toml 定位项目 .venv，天然绕过 PATH 上 Hermes 自身 venv 的裸 python（3.11、无项目依赖），且每次运行顺带校验环境与 uv.lock 同步（开销可忽略，--no-sync 可跳过）。
• pywikibot 是 git submodule（fork：github.com/re0wiki/pywikibot，upstream 是 wikimedia/pywikibot）。克隆要 --recurse-submodules（否则 uv sync 会因路径缺失失败）。fork 上的 re0wiki 定制补丁 rebase 上游时必须逐条保留——清单与流程的唯一权威是 pywikibot-update skill。更新 submodule 后提交信息写 chore: update pywikibot。
• pywikibot 通过 [tool.uv.sources] 以 editable 方式从 submodule 路径装入 venv（{ path = "pwb", editable = true }），submodule gitlink 是唯一版本锁，无需再同步 uv.lock 里的 commit。pyproject.toml 里的 [tool.ty.environment] extra-paths = ["./pwb"] 是必须的：ty 无法静态解析 PEP 660 editable finder，删掉会导致全项目 unresolved-import。
• Lint：ruff check / ruff format（PATH 里没有 ruff 时用 uv run ruff ...，ty 同理；pyproject.toml 里 extend-exclude 了 pwb 子模块、logs/ 与 *.md（保留手工对齐的代码块注释），不要给它们 lint；src/oneoff/ 归档脚本纳入正常检查，归档前需先过 lint/format/ty）。类型检查用 ty（src.exclude 排除 pwb 与 logs/，正常应为 0 诊断）。Windows 上 ruff 无法检查可执行位，shebang 文件的 EXE001 只在 Linux（CI）触发——新增带 shebang 的脚本记得 git update-index --chmod=+x。
• 离线单测：pytest tests/（不触 wiki；覆盖译名表一致性、watchdog 纯函数；PYWIKIBOT_DIR 由 tests/conftest.py 设置）。临时探索脚本写成 .py 放 scratch/（gitignored）、从仓库根目录跑（uv run python scratch/_foo.py）；docs 只写结论不引用其路径。从子目录跑则 pywikibot 找不到 user-config.py（cwd 不参与配置发现时按用户目录找）。Wiki 侧改动验证方式仍是 -s/--simulate 干跑 + 上 wiki 查编辑结果。
• Secrets：user-password.py（BotPasswords，gitignored，勿读勿提交）。