这个项目最初是家长为女儿学习围棋而提出，并与 Codex 协作开发的工具，希望让初学者每走一步都能得到可理解的反馈。项目 ID：project-go-coach。
在同一个网页里做题、下棋和看讲解。默认建立“我”和“宝宝”两份独立学习档案，也可添加其他学习者。
家庭云端入口：go.huashan.app，需要家庭密码。云端版本采用 Cloudflare Workers + D1，支持家庭登录、每台设备独立选择学习者、PWA 添加到主屏幕与触屏确认落子。学习记录存入 D1；Mac 处理书题后只上传已核对结构，原照片留本地。云端计算采用 fnOS b18 主力、VPS b10 后备，主力故障时自动切换，Mac 关机不影响云端使用。部署、数据迁移和计算服务说明见 云端部署说明。
新增 GoGameGuru 题库保留原作者署名与 CC BY-NC-SA 4.0 数据许可；原始 420 题逐题回放校验，417 题激活，基础变式精简后合计 474 道可选题。来源、数量与未激活原因见 第三方数据说明。
需要 Python 3.10 或更高版本。克隆仓库后，双击 启动围棋.command，或 python3 start.py，打开 http://127.0.0.1:8769/?v=3。重启电脑后重新启动即可恢复，没有配置开机自启。
- 练习题：落子后自动反馈结果、原因与棋盘标记，并保存作答。四类基础知识点，8 个基础局面按难度保留 32 个旋转／镜像版本（一级每类 3 个，二级每类 5 个）；另有 25 个原创多手吃子局面，难度 3–5，其中难度 3 有 21 题。原三道题与精简前的变式继续兼容，已有作答记录和成绩保留。
- 人机对弈：可选 9 路／19 路、执黑或执白，KataGo自动应手；网页打开时驱动自动应手。悔棋回到自己的上次决策点。
- 双人对弈：选择 9 路／19 路和黑白两位学习者，在同一棋盘轮流落子；双方都能在对局记录中继续这盘最新棋局。
- 记录：练习、想法、模型讲解和历史对局分别保存。重试、悔棋、换题不清除学习记录；对局不计入练习成绩。支持历史棋谱SGF导出。
首页以棋盘为主，只保留当前题目、轮次和常用落子操作。「菜单」展开学习者、练习/对弈模式及题库、学习记录、设置入口；「讲解」打开当前反馈、参考解法、AI 答疑与下一题建议；「棋盘选项」收起查看气、全盘切换、落子确认等设置。作答后的简短反馈与下一题按钮留在棋盘附近，讲解不自动滚动打断落子。抽屉关闭后回到棋盘；开始选题或继续历史对局也自动回到棋盘。
练习方式可选「智能推荐 / 顺序闯关 / 错题复习」，按学习者分别保存。顺序闯关按题库顺序推进，完整做对即可通关，提示后完成不增加独立答题积分；复习模式保留还没做对的题。19 路局部题默认放大题目所在区域，保留真实坐标和边界提示，可随时切回全盘。遇到未收录变化，可从反馈里「看参考解法」，逐手查看后返回原局面重练。
水平表示入门知识点掌握情况，不是围棋段位。按不同题目的首次独立作答计算证据，少于3题标为待评估。提示、查看气、演示后的作答与重复尝试会留痕，不增加独立掌握证据。
基础题有至少3个不同题号的独立样本且正确率达到75%后，可推荐下一档。吃子题可逐档到难度5；某档不足3题时，以该档全部题目为样本门槛。推荐也会覆盖尚未练习的知识点。基础旋转版本当前仍分别记录作答，界面另列独立局面数；不把这些数量当作段位评估。
题库可以直接选择难度和具体题，不要求先通关。多手题由你连续落子，程序按收录分支自动应手；重复练习会轮换对手分支。原创吃子答案已验证合法性和实际提子目标；第三方死活题按作者明确标注的正解收录，但不表示穷尽所有防守或唯一最佳着。未收录的合法走法标为待复核，不判错、不计正确率。完成整条变化才记录成绩；悔棋回到自己的决策点，提示、悔棋或中途重练后的完成不冒充首次独立作答。
智能推荐结合最近 30 条真实作答按题型调整：连续做对 3 道不同题时减少该类出现；连续答错 2 道不同题时优先换题巩固，有较简单题时降低难度；连续练同一类 3 次后穿插其他题。中间的错误或辅助会打断连续正确，反复做同一道题不凑次数；题库未收录的变化不当作错误。后来练熟后真正连续做对也可减频，首次独立评价与 XP 仍按原口径计算。推荐会说明安排原因；顺序闯关保持固定顺序。
新增 17 道短变化原创题 包含倒扑、接不归、短征吃各 3 道；全部分支回放验证合法和提子目标，并排除旋转、镜像、平移重复。难度 3 的原创专项由 4 题增加到 21 题，加上 Go Game Guru 的 139 题，共 160 道；题库选择难度时默认展示全部知识点，也可再缩小筛选。
「讲解」中的中文视频默认收起，按相关概念推荐最多 3 条；题库可展开 14 节基础视频目录，涵盖数气、打吃、连接分断及常见吃子手法。视频打开原作者页面，不占据主棋盘；来源及核对范围见 视频目录。
把题图发到 Codex 对话，可附上答案图、书名、页码与题号。识别后先核对棋子、棋盘边界与先手，再录入答案分支并由规则程序回放验证；看不清或无可靠解答的内容先留待核对。当前网页不自动识别照片，也不将照片发给外部服务。
已核对题目可以通过网页“把书上的题放进题库”导入单题 JSON；也可由 Codex 直接调用本地导入接口。导入内容持久保存在 .local/imported-lessons.json，所有学习者共用题库，作答仍各自记录。已有题号拒绝覆盖。当前支持 9 路或 19 路吃子及带可靠作者解答来源的题目、黑先或白先、1–31 手答案树；不支持通用死活评分；19 路对弈、摆题、导入和 SGF 导出均支持。导入流程实测使用原创测试题，尚未收到实际书题照片。
JSON 字段及识别核对流程见 题库导入说明.md。
在“AI讲解老师 → AI讲解设置”填写 OpenAI兼容的 Base URL、模型名、API Key。保存后可点击连接测试；勾选启用后，完成练习或对局落子会自动请求讲解，也可以手动提问。
LLM只负责中文讲解和辅导，KataGo负责落子。练习反馈由规则程序核对；自由对局讲解可结合KataGo分析。未配置时仍能练习、对弈和获得本地规则反馈。
API调用费用按提供方规则计算。连接测试只发简单问候，不发棋盘。启用讲解会发送匿名棋盘、最近走法、规则事实和学习概况；不自动发送姓名、完整练习历史或已保存的个人想法。主动输入的问题会发送给模型。
本地运行时，密钥保存在本机 .local/llm-settings.json，权限0600，不回显、不写入浏览器存储。留空保留旧密钥，更换API地址会清除旧密钥，需要重新填写。默认关闭，没有替用户选择模型服务或填写凭据。模型回答不是规则裁判，复杂判断仍需结合棋盘验证。
Python标准库服务、原生HTML/CSS/JavaScript，无网页外部依赖。仅监听127.0.0.1:8769并校验Host/Origin。
KataGo 为可选的独立引擎，不随本仓库分发；未安装时仍可做题和双人对弈。macOS 可先运行 brew install katago，其他系统安装后通过下述环境变量指定引擎和模型。当前已验证环境为 macOS，默认使用 /opt/homebrew/share/katago 的b18模型。可通过 GO_COACH_KATAGO、GO_COACH_MODEL 改路径。每次最多64 visits、3秒搜索预算，首次加载另计；棋力较强，未校准初学者段位。
棋局禁止自杀，采用全局同形禁着，停一手豁免。引擎按相同规则贴7.5目分析。双方停一手后结束；本版尚不自动裁定死活、终局数目或胜负。
.local/profiles.json 原子保存全部角色与对局。旧 .local/state.json 保留，并备份为 state.pre-profiles.json；旧局面迁入“我”，不会倒推历史成绩。整个 .local/ 被Git忽略。可通过 GO_COACH_DATA_DIR 使用隔离数据目录测试。
python3 coach.py 读取当前共享局面；--analyze 获取KataGo分析；--action-file 提交JSON文件。动作必须携带读取到的revision，旧请求409，不能重放覆盖另一角色。
- GET
/api/state、/api/lessons、/api/history、/api/matches、/api/sgf。 - POST
/api/lessons/import：{revision, lesson}，校验后新增本地题目。 - POST
/api/action：play、pass、undo、retry、next_lesson、practice_mode（mode 为 recommended / sequential / review）、solution、switch_profile、add_profile、new、resume_match；也支持setup、annotate、demo、demo_next、restore_demo。 - POST
/api/analyze：只读分析，传revision。 - GET/POST
/api/llm/settings；POST/api/llm/test；POST/api/llm/explain（revision与可选question）。
落子坐标左上角为 x0,y0：9 路是 A9，19 路是 A19。19 路右下角 T1 为 x18,y18。数字1黑2白，字母跳过 I。新对局和摆题的 size 支持 9/19，未传默认为 9；导入题按自己的 size 恢复。19 路可在棋盘内切换放大后滚动查看。
python3 -m unittest -v、npm run test:cloud 与 node --check static/app.js。详见 验证记录.md。真实用户的API尚需用户填写后测试；自动讲解链路使用本地模拟接口验收。