Chess Coach项目文档一方自己的棋盘
棋盘与引擎在本机运行，棋局也在本机保存。
每一步，都有所得
与 Codex 讨论的，正是眼前棋盘上的真实局面。
随时回来，继续落子
一盘棋，没有时钟，留给思考足够的时间。
01落下第一子
准备好你的棋友。
完成一次安装，往后想下棋时，只需请 Codex 打开棋盘。
安装稳定版
通过原生 GitHub marketplace 安装完整稳定版插件包。
终端codex plugin marketplace add jovijovi/chess-coach --ref marketplace codex plugin add chess-coach@chess-coach当前预览版使用 ref marketplace-preview 和插件标识 chess-coach@chess-coach-preview。公开仓库无需 GitHub 认证。
手动升级
刷新稳定目录并重新安装；预览版将目录名称改为 chess-coach-preview。
终端codex plugin marketplace upgrade chess-coach codex plugin add chess-coach@chess-coach每次升级后新建 Codex 任务。旧缓存不会覆盖较新的运行版本。
落下第一子
在新任务中发出下方请求；插件自动启动本地服务，并在应用内浏览器打开棋盘。
打开国际象棋棋盘。
默认执白、中等难度。安装后棋盘和引擎可离线运行；模型对话仍使用 Codex 服务。
02从容对弈
给思考，一点余地。
选择你的执棋颜色与挑战难度。退回一步，换个角度，或者明天再继续。
自然落子
拖动棋子，或依次点击棋子和目标格。合法落点会高亮显示，也支持键盘走棋与四种升变选择。
看清局面
棋谱、上一步高亮和将军提示帮助你掌握棋局。需要换个视角时，随时翻转棋盘。
重新想一想
悔棋退回到你上一次走棋之前：撤销你的落子及引擎应手；引擎思考中，则撤销你的那一步。
留住一盘好棋
想保留棋谱，就在新开局前导出 PGN。新开局会替换唯一的当前保存槽。
选择合适的挑战
| 难度 | Skill Level | 每步搜索时间 |
|---|---|---|
| 简单 | 0 | 200 ms |
| 中等 · 默认 | 5 | 500 ms |
| 困难 | 10 | 1,000 ms |
难度名称不对应经校准的等级分。执黑时由 Stockfish 先走；悔棋会保留引擎的首步。
棋盘支持英文与简体中文。首次使用遵循浏览器中第一个受支持的语言；手动选择后，刷新和服务重启都会保留偏好，不影响棋局或 PGN。
03棋盘之外
知其然，也知其所以然。
棋盘提供引擎提示，而每一步背后的思路，可以在 Codex 对话中慢慢展开。
理解眼前的局面
分析当前局面，我应该重点考虑什么？
回看刚才的选择
解释我刚才那一步，并与引擎建议的其他走法比较。
寻找下一步思路
给我一个提示，并解释这步棋背后的计划。
Codex 会读取真实棋局，并用 Stockfish 分析对应局面。分析结果包含半步数（ply）、FEN、棋局版本与合法变化线，不会修改棋盘。你可以用中文或英文请求讲解。
04表里如一
同一盘棋，共同的理解。
交互棋盘与 Codex 共用同一套棋局服务。展开工具，查看它的用途和输入参数。
show_board打开或继续棋盘
返回当前棋局和供 Codex 应用内浏览器打开的地址；需要时自动启动本地服务。
无需参数。
get_game读取完整棋局
返回当前局面、完整历史、合法走法、引擎状态、gameId 和 revision。
无需参数。
new_game开始新的一局
按明确的新开局请求替换当前保存槽。希望保留旧棋谱时，请先导出 PGN。
gameId、expectedRevision、playerColor（w | b）、difficulty（easy | medium | hard）。
make_move执行你指定的走法
校验并保存走法，然后安排 Stockfish 应手。格子使用 e2、e4 等代数坐标。
gameId、expectedRevision、from、to；可选 promotion（q | r | b | n）。
undo_turn重想上一个回合
取消正在进行的搜索，退回到玩家上一次走棋之前。
gameId、expectedRevision。
retry_engine重试引擎应手
引擎超时或退出后，从已保存的局面重试，不会编造替代走法。
gameId、expectedRevision。
analyze_position分析指定局面
返回白方视角的分数和合法变化线，不修改对局。结果会标明对应的局面和版本。
gameId、expectedRevision；可选 ply（0 表示初始局面）。
export_pgn带走这盘棋谱
返回当前 PGN、建议文件名和本地下载信息。
无需参数。
05好棋，留待下回
回来时，棋局还在。
每次落子都在引擎应手前保存。关闭棋盘后，当前这一局仍等待你下一次继续。
数据始终留在本机
| 路径 | 用途 |
|---|---|
~/.local/share/chess-coach/state.db | 当前棋局和完整历史 |
~/.local/share/chess-coach/preferences.json | 语言偏好 |
~/.local/share/chess-coach/runtime/ | 校验后的运行文件 |
| activation-lock.db / service-lock.db | 独立 SQLite 进程锁 |
node ~/.local/share/chess-coach/runtime/control.js doctor
node ~/.local/share/chess-coach/runtime/control.js stopdoctor 不输出令牌。停止保留棋局和语言；服务重启后通过 Codex 重新打开棋盘。
node ~/.local/share/chess-coach/runtime/control.js stop
codex plugin remove chess-coach@personal
cp -R ~/.local/share/chess-coach/runtime ~/.local/share/chess-coach/runtime-0.1-backup先关闭旧任务。安装预览版后，使用安装输出中的插件绝对路径执行 node <installed-plugin>/scripts/launch.mjs clean-runtime，再新建任务。不会删除棋局、偏好或其他 personal 条目。验证完成前保留备份。
node ~/.local/share/chess-coach/runtime/control.js stop
node ~/.local/share/chess-coach/runtime/control.js clean-runtime
codex plugin remove chess-coach@chess-coach-preview先关闭下棋任务。clean-runtime 为可选操作，仅删除运行文件，保留棋局与语言。稳定版标识为 chess-coach@chess-coach。
引擎停止响应怎么办？
用户走棋已经保存，使用重试即可。服务断开时重新打开棋盘，必要时检查数据目录的 service.log。
升级失败会丢失棋局吗？
新文件先暂存、校验再切换，并检查服务健康状态。失败恢复旧运行文件，不回退数据库。进程崩溃自动释放锁，中断的切换在下次启动时恢复。
如何主动回退？
关闭任务、停止服务、卸载插件并清理运行文件，只移除对应目录注册，再用 --ref plugin-vVERSION 安装兼容版本。请从 Release 选择已存在的 RC 引用，使用对应预览目录。不要覆盖较新的数据库；0.2.0 各 RC 保持现有棋谱格式。
三个平台采用相同数据目录。直接 CLI 可使用 CHESS_COACH_DATA_DIR；Codex 若过滤继承变量，需在 MCP 环境中显式设置，并让任务和控制命令一致。数据库损坏会报错，不会静默清空。
06探索其间
清晰构建，从容维护。
棋盘由 React 与 TypeScript 构建，背后是 Node.js、chess.js、SQLite 和 Stockfish。所有交互共享带版本的真实棋局。
日常开发命令
| 命令 | 用途 |
|---|---|
npm run dev | 在 output/dev-data 构建独立棋局，不提供热更新 |
npm run typecheck | 检查 TypeScript |
npm run build | 打包插件与本地引擎资源 |
npm run package | 完整包、归档、校验文件和来源清单 |
npm test | 打包后运行 Vitest 集成测试 |
npm run test:browser | 在 Chromium 中检查两种界面语言 |
npm run check | 运行完整代码检查流程 |
npm run docs:build | 在 output/docs 构建这份双语静态手册 |
npm run docs:preview | 重新构建并在本机预览手册 |
npm run install:local -- --dry-run
npm run install:local开发目录为 chess-coach-local，通过 Codex 原生命令安装，无 Python 安装依赖。带注释的 v0.2.0-rc.N 或 v0.2.0 标签触发三平台检查和 Draft Release；手动确认后更新发行分支。普通 main 推送不会发布插件。
原创代码、文档与图标采用 Apache-2.0。Stockfish 18.0.8 保持 GPL-3.0；完整包保留依赖许可证、对应源码、网络文件、构建说明和固定哈希。源码材料不完整时禁止发行。