Imported from ZQZWCQ/ChessWithDSH (
AGENTS.md). Install upstream withnpx skills add ZQZWCQ/ChessWithDSH. Copyright stays with the author.
在这个仓库里工作：操作契约
为了方便接手这个仓库的人或 agent 工作。 姊妹项目
ChessWithCodex有一份同名文件。两边数据契约对齐，实现各自决定。
这是什么
在 DeepSeek Harness 里下一盘能讲明白的棋。本地引擎负责计算，模型负责讲解。 以 DSH bundle 插件的形式分发。
硬性要求
- 不要自己起服务器。 界面挂在宿主自己的 web 服务上（
ctx.webServer、ctx.connection.fetch）， 进程生命周期归宿主。 - 数字必须来自引擎。 评估、最佳着法、失误判定都问引擎。 没有对应的引擎记录时，只描述事实，不下棋力结论。
- 评估缓存键是
<fen>|d<深度>|<引擎名>，统一按照白方视角分数存储。 云评估的引擎名为lichess-cloud-eval，depth 采用响应里的真实值。 games/是生成物，不要改动；notes/是人写的，不要覆盖。 重算时按(ply, san)把人写字段合并回去，并且校验 SAN：序号不存在或 SAN 对不上就跳过。- 提交前跑
pnpm verify。main受保护，改动走分支加 PR。
分支与 PR
分支名 <type>/<短描述>，type 跟提交信息一致：feat/ fix/ docs/ refactor/ test/ chore/。
一个分支不做太多事，标题写中文短句，正文说清改了什么、为什么、怎么验证。
提交信息用 Conventional Commits，例如 feat(engine): 补 Windows 引擎查找。
不要直接 push 到 main。合并前 pnpm verify 要全绿，CI 跑的是同一条命令。
常用命令
pnpm install
pnpm verify # 提交门槛：format:check + lint + typecheck + test
pnpm test # vitest
pnpm test -- 名字 # 只跑匹配的用例
pnpm typecheck
pnpm lint / pnpm format如何讲解对局
先分析整盘的评估曲线，再从中挑几个转折点重点讲，剩下的不必像 chess.com 那样逐手讲解。 指出问题时带上引擎数字和替代着法，比如「2.exf5 是 +1.90，实战 2.d3 只剩 +0.36」。 正文没有必要重复强调界面上的曲线、箭头、评估数字等。 指出清晰的赢棋/输棋原因：对手是几档、多少 ELO，对手的失误是设计使然还是真被打崩了，行棋方的失误是没有看到什么。
数据存储
代码存储在插件目录里，数据存储在数据根。
顺序是 CHESSPLUGIN_HOME，没有就用 ${DSH_HOME}/dsh-chess（DSH_HOME 也没设时取 ~/.dsh）。
把 CHESSPLUGIN_HOME 指到 Codex 侧的数据目录，可以实现双侧共享。
pgn/ 存放原始棋谱。games/ 是唯一数据源，由 PGN 生成。notes/ 是人写的，永不覆盖。
cache/evals.json 是可丢弃的加速层。sessions/ 存放进行中的对局。
文字风格——主要是给agent看的
文档和提交信息都用中文。句子写短，能具体就具体，写清文件、命令和数字。
AI味太重的文字会让人丧失阅读的欲望，如果这样，还不如直接写成agent的接口式文档。
肯定句不必再配一句否定，是 A，不是 B 这类成对写法在技术文档里是废话。
边界
不随仓库分发引擎。Stockfish 是 GPLv3，只通过 UCI 协议调用。
不接收他人评注，只在棋谱库存着法和元数据，讲解则写进 notes/。
引擎缺失时对弈盘必须仍能下，退回内置的弱搜索；分析类功能需要提供可读的安装指引。
棋谱库是独立仓库，本地侧仅负责读取仓库的 index.json。
文档地图
docs/problems_met.md曾遇到过的问题，注意规避docs/architecture.md目录职责和设计（待补）
