# AGENTS.md

## 仓库定位

DSH (DeepSeek Harness) 适配仓库: 把 Codex marketplace `math-research` 的 4 个插件
(rigorous-open-math-research / manage-math-research-program / math-research-workflow /
lean-verify) 以 DSH skill 形式发布, 附带脚本/模板/冒烟测试与同步工具链.

父仓库: https://github.com/xsoc1/rigorous-open-math-research (Codex marketplace).

## 目录结构

- `skills/<name>/` -- DSH skill bundles (SKILL.md + references/ + assets/ + scripts/)
- `scripts/sync-from-parent.py` -- 父仓库同步 + DSH 层重放 + upstream.lock.json
- `scripts/validate_all.py` -- 仓库校验 (结构/MANIFEST/lock/UTF-8+LF/py_compile/JSON+YAML)
- `scripts/dsh-doctor.py` -- DSH 环境自检 (skill 挂载/python/lake)
- `tests/` -- fixtures + 21 个 smoke + DSH 同步与 2.0 续接 unit tests + 一次性 STORE Profile 验收
- `package.json` / `index.mjs` / `cordis.patch.yml` -- 官方 bundle 技能包 (社区一键安装)
- `scripts/dsh-check-bundle.py` -- bundle 打包门禁 (package.json/patch/index.mjs/skills)
- `upstream.lock.json` -- 父仓库 commit + 逐文件哈希
- `install.ps1` -- 安装到 $DSH_HOME/skills 的 junction (热更新)

## 维护规则

1. 每次变更后运行 `python scripts/validate_all.py .` (Python 3.10+, 建议 PYTHONUTF8=1).
2. 禁止手改同步文件: 上游内容改动走父仓库然后重跑 sync-from-parent.py; DSH 层只维护
   加载说明, 布局映射和测试输出目录. 简短 2.0 指南保留父源码的研究选择.
3. 父仓库冻结后: `sync-from-parent.py --upstream <clean-clone> --expect-commit <full-commit>`
   重新同步, 再运行相同命令加 `--check`. CI 从 lock 固定的父提交检查漂移.
4. 所有文本文件 UTF-8 无 BOM, LF 换行, 英文标点.
5. 提交后按 project.json 的 git_sync.push_order push (当前只有 origin).
6. 本机安装用 install.ps1 (junction 热更新); `git pull` 后无需重装.
7. README 中英两版必须同步更新 (README.md 中文 + README_EN.md 英文, 顶部互链).
8. 内容变更 (skill 正文/脚本) 时同步 bump package.json 的 version.
9. bundle 安装与 junction 安装二选一, 不要同时用 (同一批 skill 会双份注册).
10. 新代码使用 tab 缩进, snake_case 函数名和 PascalCase 多词变量名.

## 2.0 发布工作方法

- 当前授权: 用户已确认父提交 72a1cc17ce98f3d3fd3b001d7b25d442ba2d3803 发布到
  origin/main, fork/main 及两处 v2.0.0, 父 CI 34336134215 全部通过. 实际同步,
  DSH 提交推送和发布 CI 验证均已获授权, 无需再次确认.
- 本机真实验收优先用原生 Windows Python + Lean.exe. 保存验收输入的逐文件哈希与原位
  测试工件. 发布后若对应输入字节一致, 可复用适用的行为测试结果; 不复制证明 receipt
  并认定其在新路径仍 current. 实际同步后仍运行 sync --check, bundle/结构检查和发布 CI.
- 当前只维护本仓库. 父工作目录 `_xsoc1_work` 由协调者维护; canonical clone 是
  `~/.dsh/_math-research-upstream/rigorous-open-math-research`.
- 以后尚未发布的父候选只用 `--preview <new-external-directory>` 进行迁移检查,
  以 PREVIEW.json 标记未发布源码. 正式同步必须核对已发布 main 的完整 SHA.
- 保留现有 bundle/junction 安装状态. 本轮不启动子 agent, 不重启 DSH, 不修改 auth/profile.
- 发布顺序: 源码和文档先提交到候选分支并推送. 原生实际测试及候选 CI 通过后,
  才 fast-forward main 并核对实际 main CI. 不为 Git 元数据或无关 CI 文本重跑相同原生测试.
- 先核对遗留 diff, 再修改适配器, 然后在外部预览执行 README 索引和 CI 所列测试.
  比较实际安装文件前后哈希, 报告实际通过与 SKIP, 冻结后重跑最终同步与发布验证.
- Q9 直接继承父测试的祖先目录发现和缺原件 SKIP; 不改写 REPO_ROOT 或虚构外部数据.
  显式原件回放在固定父源码执行. Lean 可移植测试默认报告真实编译 SKIP; 专门 CI 任务
  按 `tests/fixtures/lean-v2-runtime/lean-toolchain` 固定 4.31.0 后显式启用真实编译.
- 长命令和证据范围见 [docs/v2-release-validation.md](docs/v2-release-validation.md).

## 注意事项 (Notes for future agents)

- **版本 bump 是硬门禁**: 修改 `skills/`、`index.mjs` 或 `cordis.patch.yml` 时必须同步
  bump `package.json`; CI 的 `version-bump` job 和本地 `validate_all.py` 都会检查.
- **上游同步纪律**: 不要手改 `skills/` 下从父仓库同步来的文件; 上游内容变更走
  `xsoc1/rigorous-open-math-research`, 然后重跑 `scripts/sync-from-parent.py`.
- **两种安装方式互斥**: `dsh plugin add github:xsoc1/math-research-dsh` (bundle) 与
  `install.ps1` (junction) 只能二选一, 同时安装会导致同一批 skill 双份注册.
- **README 中英同步**: README.md 与 README_EN.md 必须同步更新; `validate_all.py` 会
  检查所有 `tests/smoke_*.py` 是否都出现在两份 README 中.
- **测试索引**: 当前 21 个 smoke; 新增根 smoke/unit test 后同步更新 README 两版.
- **GitHub 网络**: 直连 github.com 失败时, 用本地代理 push:
  `git -c http.proxy=http://127.0.0.1:7897 push origin main` (本机实测可用).

## 会话记录

- 2026-10-02 用户再次要求进入项目研究并解决 DSH STORE #1185. 先核对 issue,
  默认分支和两处固定源状态: 2.0.1/888bcc0 已被商城读取, 缺兼容声明的理由已消除,
  剩余 files/network/commands 是真实能力触发的自动策略. 官方 npm 最新三版已变为
  0.1.7-rc.2, 0.2.0-rc.1, 0.2.0-rc.2. 旧驱动对新版在测试前直接拒绝, 已实际复现.
  本轮候选分支 codex/store-1185-current-compatibility, 基线237文件哈希保存在
  F:/tools/math-research-dsh-issue-1185-20261002/baseline.json. 方法: 不修改父技能或
  已安装 Profile, 只在临时 DSH_HOME 验证固定官方发布版; 驱动显式绑定版本, 增加
  真实官方 Skills registry 的正文/生命周期及损坏包负对照, CI 逐版本留证.
  本条是实施记录, 完整验收和对外发布尚待当前测试结果. 不规避 STORE 能力门禁.

- 2026-10-02 本地验收补记: 三版 official CLI 均完成一次性 headless/web 安装,
  启动, 卸载和配置恢复, headless manifest/lock 精确回滚; 四技能官方 registry
  读取及生命周期和每版三项损坏包负对照通过. 最终检查另发现已生成 Python
  bytecode 被 npm 打包, 候选74缓存另记失败, 显式排除后核对140父资源全保留.
  干净2.0.2 tarball 为357888字节, SHA256
  2e99a4e702519bc7f3dae74287e6c34a7886449210c774946ac07274c16c4f59,
  三版用同一精确包复验通过; 版本不符也实际拒绝. 校验51项, Bundle和原生
  Windows根36项通过; 首次0.5秒超时测试缺partial记录, 单独及整套复验通过,
  原测试及阈值不改. 初版包资源检查把相对skills根误认成仓库根, 修正后再测,
  不将该驱动错误冒称宿主失败. 145项受保护源码和历史证据哈希不变. 用户新增
  "不要用显式cmd", 后续使用PowerShell/Python/Node, 不显式调用CMD或.cmd.
  当前仅完成本地门禁, 候选与默认分支CI交付后另记真实结果.

- 完整旧记录: [AGENTS_HISTORY.md](AGENTS_HISTORY.md). 仅在查找历史决策, benchmark 或故障证据时按关键词读取相关段落.
- 2026-09-05 用户要求: 根据既有 benchmark 优化 Codex 研究插件, 重点完善真实文献读取, agent 可注释工具库与指针表, 以及额度中断续接; 额度恢复后继续实施.
- 本轮方法: 先做确定性 L0, 使用隔离的真实工具卡和 sequence-26 工件回放; 保留主项目原文件和数学状态. 高成本 solver A/B 留待后续匹配实验.
- 功能与验证证据见父仓库 docs/optimization-20260905-results.md; 本地适配版本 1.15.1, 父提交以 upstream.lock.json 为准. 每次维护在本节追加简短结果, 长证据放专门报告.

- 2026-09-05 发布 1.15.1: 从父提交 0af2461 同步 manage 1.8.1 修复, 测试版本断言改用本包版本. 51 项校验, library 7 项, closure-first, bundle 和 sync 检查通过. 当前完整旧记录仍可从 AGENTS_HISTORY.md 查阅.

- 2026-09-06: 1.15.1 发布 CI 通过 (2b80ea4). 上游仅补发布文档后将 lock 前移至 6d6d739, skill 内容和版本不变; canonical clone 与父仓库远端一致.

- 2026-09-09 用户要求: 从意外中断处恢复有界 2.0 DSH 适配, 接手 README 中英版,
  package 2.0.0, sync/validate 修改, 同步 unit test 及旧 distilled smoke 删除.
  既有父仓库/fork/DSH 发布计划已获授权, 本轮等协调者给出冻结父提交再实际同步和提交.
  协调者补充: library smoke 改为隔离损坏批注并保留正常命中; Q9 已使用真实 evidence
  祖先目录发现并明确跳过缺数据; 保留新版 Lean portable tests 与 4.31.0 fixture/CI.
  本轮方法: 移除旧 Q9 专用改写, 仅适配 Lean 测试临时目录, 扩展 Linux/Windows CI,
  保留简短运行说明与可选任务模板. 检查结果记录在发布验证说明和用户指定 prep report.
- 2026-09-09 预览实测: Linux 21 个 smoke 通过. DSH 包装器 smoke 改用外部临时程序,
  验证退出码与完整日志, 避免假定旧流水线是默认行为. 原生 Windows/Python 3.10 暴露
  续接测试的分隔符断言, 已通过同步层的 Path.as_posix 路径适配处理. library 两平台
  各 25 项通过, Q9 缺原件 SKIP 1 项, 直接回放请求明确失败且不创建输出.
  父 Lean 路线测试的简化证据与新版 manifest 重检不匹配, Windows mock 还依赖 os.killpg;
  这两项作为父源码冻结前待修问题交还协调者, 不在 DSH 层放宽证据校验.
- 2026-09-09 有界刷新: 已接收父源码的路线测试修复, Linux Lean portable 12 项通过,
  真实 Lean 11 项明确 SKIP. 新增 schema 测试的 jsonschema 依赖已补入 DSH CI.
  Windows 根测试为 20 项通过 + 2 项 POSIX 专用 SKIP; 父 Lean timeout mock 的
  os.killpg Windows 错误仍待协调者修复. 正式冻结后须重新同步并验证, 预览不计发布.
- 2026-09-09 后续协调: 用户报告 Windows Lean mock 已修复, recovery 最终为 Windows 26
  通过, Linux 24 通过 + 2 项 Windows 专用 SKIP; 尚待最终复查和冻结, 本 sidecar 未复跑.
  用户要求不再生成父工作源码预览. CI fixture 新增 lakefile.toml 和实际 lake.exe update
  生成的 lake-manifest.json, 因 lean-action v1 即使关闭自动配置/构建仍要求 manifest.
  方法: 保留三文件源内容, 同步前检查 fixture 完整性并排除 .lake 缓存, CI 在
  tests/fixtures/lean-v2-runtime 固定工具链目录启动. Elan 无默认工具链, 不在未固定
  工具链的仓库根调用 Lean. 本轮仅运行同步 unit tests 和只读检查, 不实际同步或提交.
  结果: 同步 unit tests 在 Linux 和原生 Windows 各 9 项通过, 仓库 51 项校验通过;
  三个 fixture 文件待同步内容与父源码一致, 120 个已安装受保护文件哈希未变.
- 2026-09-09 用户重新授权并行准备: 候选 72a1cc17 已提交且干净, 全部定向复查完成,
  父 CI 34336134215 仍运行. 方法: 从该提交建立独立源码副本并使用现有 preview 流程,
  明确未发布, 启用原生 Windows 的完整 15 项真实 Lean 测试与适配验收. 新版真实测试
  也使用 jsonschema, 已加入对应 DSH CI 任务. 用户确认 published main 前保持实际安装不变.
- 2026-09-09 用户确认正式发布: 父 main/fork 和 v2.0.0 均为 72a1cc17, 父 CI 五项
  全通过, 包括真实 Lean 15 项. 已授权本 sidecar 实际同步, 提交推送及 CI 核验.
  本机原记录的 canonical 副本缺失, 从官方已发布 main 重建并核对完整提交.
  方法: 逐文件比较外部预览和实际同步, 在实际 DSH 目录运行当前测试, 保留原位
  Lean 工件; 协调者单独负责 Codex 安装验收, 本轮保持 DSH 安装方式和进程配置.
- 2026-09-09 实际同步: clean canonical main/tag 均为 72a1cc17, sync 与 sync --check
  通过, lock 覆盖 140 文件. 外部预览和实际目录的 221 个代码/测试/配置输入字节一致.
  已通过 51 项结构校验, bundle, 全部 21 smoke, Windows 根测试 36 项,
  Linux 根测试 34 项 + 2 项 Windows 专用 SKIP. 两平台 library 各 25 项通过 +
  1 项缺可选 Q9 原件 SKIP, 两平台 Lean portable 各 12 项通过. 固定父源 Q9 回放通过.
  原生实际 Lean 15 项验收与发布 CI 的日志和最终状态保存在外部 dsh-prep-report.md;
  证明 receipt 留在原位测试项目, 不作路径重绑定. index/patch/install 内容哈希保持原值.
- 2026-09-09 发布顺序修正: 080a83e 已按先前授权推送 main 时, 用户新增候选分支门禁.
  已如实告知时序, 现保留 release/v2.0.0-candidate, 后续修复先经原生测试与候选 CI.
  首次 CI 34338243007 未启动任何 job: job.env 不支持 runner.temp 上下文.
  修复仅将临时目录变量移到对应 Lean portable step.env; 运行时代码和测试内容不变.
  继续保留原生驱动 60228 / 测试 6408 和原位日志. 原始输入清单保持不变,
  对 CI 文件变化单独核对适用行为范围, 不将复制的证明 receipt 当作当前证据.

- 2026-09-26 DSH STORE #1185: 用户提供 bot issue 全文, 其固定 Commit 检查将
  `xsoc1/math-research-dsh` 2.0.0 标记为 `catalog-blocked`, 原因是缺 DSH/Node
  显式兼容声明及运行源码的 files/network/commands 权限信号; 建议一次性 Profile
  安装/启动/卸载证据并说明依赖和失败边界. 本轮从干净默认分支
  `4f750265875ea1e0ba3f7abc67e26d31fd830409` 建独立候选分支, 阅读本仓库约定、
  STORE 当前 schema/自动策略和 build-dsh-plugin 方法, 不改真实 `~/.dsh` 或 STORE.
  首轮一次性安装虽成功且 Patch 合成, 冷启动却警告入口导入失败: 入口直接依赖未进入
  干净 Profile 依赖闭包的官方 filesystem provider. 改用公开注入的
  `ctx.skills.register` 注册四项固定技能, 保留正文及 resourceBase; 包版本提升 2.0.1,
  声明 Node/DSH 范围与逐版本结果, README 双语和打包门禁同步. 源技能及父 lock 原字节不改.
  固定 DSH 0.1.7-rc.2、Node 24.17.0 的 Linux 一次性 tarball 验收完成
  headless/web 安装、配置、启动、卸载和恢复; Web 仅本地监听且无令牌请求返回 401,
  独立回滚周期的配置、Profile manifest 和 lockfile 字节相等. 另有 51 项仓库校验、
  Bundle gate 与根 unit 36 项 (2 skip). 精确范围、tarball SHA 和未测试项见
  `docs/dsh-store-issue-1185-evidence.md` 及 JSON; 自动低风险许可仍会因真实能力信号
  受阻, 不能称 STORE 已批准. 本轮未推送分支或修改真实 Profile; 后续需候选 CI
  和用户对外发布授权, 再按候选先于 main 的本仓库方法交付.

- 2026-09-26 #1185 推送续接: 用户明确原话“推送”, 授权按上一轮说明推候选分支、
  核查 CI 后推进默认分支. 候选 `8892bf0` 已先推至 origin/codex/store-issue-1185,
  对应 Actions 36249116650. 首次新增 Profile job 在官方 DSH `plugin add` 时
  返回 127; 真实原因是 runner 缺 `pnpm` (DSH CLI 将 plugin 管理转交 pnpm),
  其它已完成 job 通过, Lean 当时仍运行. 现仅修 CI 预装固定 pnpm 11.22.0,
  测试驱动增加前置检查; 保留首次失败, 在候选分支重新验证后再决定 main.


- 2026-10-04 DSH STORE #1185: 用户先问"这个怎么还没修复", 后明确
  "那你修复和推送一下, 解决问题". 实查商城已复检2.0.2/ed70243, 三项
  files/network/commands仍阻断, 上次上游发布不等于本Issue已解决. 本轮使用
  diagnosing-bugs方法和STORE固定源原版纯只读review模块, 基线240文件及商城
  eab44d15c250644a6db2e1ae8b4fa43e972097a2政策源码存于项目外
  F:/tools/math-research-dsh-issue-1185-20261004. 新规则不支持files反向排除,
  已复现全仓240文件/109来源的fallback, 包括开发测试的凭据/动态加载信号.
  修为从父资源lock生成精确正向文件清单, 同步器重建和门禁查漂移, 140父资源
  保留; tarball门禁校验精确147成员及逐资源哈希. 修后原版重放为147分发文件/
  59来源, 开发触发项消失; 三项真实能力与科学模板需独立受审, 不删工具或
  改STORE阈值来假称低风险. 回归先失败后通过, Windows根40项, 结构51项及
  Bundle通过. 隔离四版Profile及候选/main CI尚在执行, 本条不预发通过回执.
  发布版本2.0.3, 候选codex/store-1185-reviewed-release. README双语, 契约,
  修复记录和受审请求同步. 不启动子agent, 不动父内容/lock/真实Profile/
  BVE研究canonical, 不显式调用CMD或.cmd. 对外审核材料及实际交付状态另记.

- 2026-10-04 本地验收补记: 四版0.1.7-rc.2/0.2.0-rc.1/0.2.0-rc.2/
  0.2.1-alpha.1完成同一2.0.3包安装, headless/web启动, 四技能官方registry,
  损坏资源负对照, 卸载及配置/manifest/lock回滚. 包SHA256为
  c6cb290942d385a272e43e6b6bc7f0bb4b7d02cc80c42f674a0c8594a1e88c9d,
  359665字节, 147成员, 140父资源哈希一致. 实际alpha预检另留旧候选包记录,
  先通过才补compatible/passed声明, 最终四版重验新包. 新归档负对照发现
  set成员比较漏重复项, 保留首次失败后补数量检查; 最终4项打包测试拒绝
  内容篡改, 额外文件与重复成员, 新门禁另复查最终包通过. Windows根40项
  通过时尚未新增该归档用例, 不冒称它在那次已执行; 后续CI使用最终驱动.
  原入口, 140技能和父lock及历史报告均不变, 默认分支发布仍待候选CI.