信奥教练 wangdapeng325/dsh-oi-coach

dsh-oi-coach —— 信奥教练插件

为 DeepSeek Harness 添加一套教学能力，面向信息学奥林匹克竞赛（GESP、CSP-J/S、NOIP、省选、NOI），覆盖「规划 → 学习 → 练习 → 评测 → 归档」的完整教练闭环。插件版本 1.0.8（功能对齐 oi-coach 技能）：

- 启发式陪练：把教练规则注入系统提示词，通过提示词段落实现（先让学生讲思路、一次只指出第一处错误、透明标记、归档要求等）；
- 真实评测：xinao_judge 真编译、真运行、逐测试点判定（C++14）；
- ima 打通：xinao_ima_search 检索使用者的 ima 知识库，xinao_ima_archive 归档到 4 个 ima 笔记本。

面向家长 / 学生 / 老师的使用说明见 使用说明.md（怎么用、陪练规矩、错题复习、常见问题）。

提供的工具

| 工具 | 作用 | 何时使用 |
| xinao_doctor | 环境自检：g++ 能否真实评测 + ima 凭证/调用器/4 个笔记本是否就绪 | 首次使用、或评测/归档失败时 |
| xinao_plan | 按当前阶段与目标阶段输出分阶段知识点清单、建议周数与总周期 | 「帮我制定一份从零到 NOIP 提高组的学习计划」 |
| xinao_knowledge | 在知识图谱中匹配知识点，返回前置知识、难度、GESP/CSP 级别定位与讲解大纲 | 「给我讲一下线段树 / 前缀和 / KMP」 |
| xinao_problem | 生成命题要点（题目结构、数据范围、边界测试点、评测建议），支持螺旋递进 | 「出一道普及组难度、考二分答案的练习题」 |
| xinao_judge | 真实编译并运行 C++（统一 C++14），逐点判定 AC/WA/TLE/RE，编译失败给「第一条错误」 | 批改作业、检验学生提交、对拍验证 |
| xinao_ima_search | 检索使用者 ima 账号的知识库，返回命中标题/片段与实际检索过的库名 | 「查一下知识库里怎么讲逆序对」 |
| xinao_ima_archive | 归档本轮问答/错题/计划/报告到 ima 笔记本，返回 [归档：…] 状态行 | 每轮学习档案；错题/计划/报告按触发时机 |

内置知识图谱覆盖 5 个阶段（入门 / 普及组 / 提高组 / 省选 / NOI）、80+ 知识点，含前置关系与建议学习周数。

目录结构

dsh-oi-coach/
├── src/ # TypeScript 源码 │ ├── index.ts # 插件入口（Config + 7 个工具 + 教练规则提示词段落） │ ├── knowledge.ts # 知识图谱 + 路线图/知识点匹配逻辑 │ ├── judge.ts # C++ 评测引擎 + 编译器体检（只依赖 Node 内置模块） │ └── ima.ts # ima 接入：调用器定位、凭证、知识库检索、笔记本归档 ├── dist/ # 编译产物（tsc 输出，加载时使用） ├── test/ │ ├── judge.test.mjs # 评测引擎测试（不依赖 g++） │ ├── ima.test.mjs # ima 模块测试（用假调用器 fixtures/fake_ima.cjs） │ ├── fixtures/fake_ima.cjs │ └── live-check.mjs # 真实环境联通性自检（读真实 ima 账号） ├── cordis.yml # 开发用 patch 层（配合 --patch 使用） ├── cordis.patch.yml # bundle 配置层（配合 dsh plugin add 使用） ├── 使用说明.md # 面向家长/学生/老师的使用手册 ├── package.json # bundle manifest（声明 dsh.bundle） └── tsconfig.check.json / tsconfig.build.json # 类型检查 / 构建配置

安装

方式一：源码运行（推荐，仓库开发环境）

插件需要放在 dsh 仓库根目录内（@deepseek-ai/ 依赖才能解析），即本目录 <repo>/dsh-oi-coach/。若仓库不在 C:\dev\deepseek-harness，请修改 cordis.yml 中 name 为 file:/// 形式的绝对 URL（Windows 上不能用裸盘符路径）。

在仓库根目录启动 Web UI 并挂载插件：

pnpm dsh web --patch ./dsh-oi-coach/cordis.yml

xinao_judge 会真实编译运行代码，因此本机需要 g++（GCC ≥ 5，支持 C++14）；用 xinao_doctor 或 node --version 之外的 g++ --version 可确认。

只检查配置树而不启动服务：

pnpm dsh --profile web --patch ./dsh-oi-coach/cordis.yml --dump-config

方式二：作为 bundle 安装进 profile（分发路径）

在仓库根目录执行；会初始化 profile 并把插件链接进其 node_modules
pnpm dsh plugin --profile <name> add ./dsh-oi-coach
pnpm dsh --profile <name> # 启动该 profile
pnpm dsh plugin --profile <name> remove dsh-oi-coach # 卸载

ima 接入（知识库检索 + 4 笔记本归档）

ima 是可选增强：不配置也能正常陪练（内置知识 + 分级模型），只是不查库、不归档，且回复中会如实标注「未查询/归档跳过」，绝不假装。

前置条件（三步，约 10 分钟）：

1. 安装并登录腾讯 ima 桌面端（https://ima.qq.com），订阅/收藏信奥相关知识库；
2. 安装官方 ima-skill（提供 ima_api.cjs 调用器）。本机已安装在 ~/.workbuddy/skills/ima-skill/ima_api.cjs；插件会按 配置 cliPath → 环境变量 IMA_API_CJS → 常见技能目录 → 浅层搜索 自动定位；
3. 到 https://ima.qq.com/agent-interface 生成 Client ID / API Key，并配置到本机：
- 推荐：环境变量 IMA_CLIENT_ID / IMA_API_KEY；
- 或凭证文件 ~/.config/ima/client_id 与 ~/.config/ima/api_key。

4. 在 ima 客户端手建 4 个归档笔记本（API 不能自动建；名称需与配置一致）：

| 笔记本 | 用途 | 归档时机 |
| 信奥教练-学习档案 | 提问 + 教练回复 | 每轮必做 |
| 信奥教练-错题本 | 错题复盘（结构化错题模板） | 本轮出现未 AC / 需巩固的题 |
| 信奥教练-学习计划 | 周 / 月备考计划 | 本轮产出备考计划 |
| 信奥教练-学习报告 | 阶段测试、模拟考报告 | 本轮产出测试/模拟报告 |

安全说明：凭证只在本机使用，由插件注入子进程环境调用你自己的 ima 账号（优先于可能残留的旧变量 IMA_OPENAPI_，避免 200002 skill auth failed）。笔记本 folder_id 每次归档时按名称动态解析，不硬编码；目标笔记本不存在时跳过并提示先创建，绝不静默把笔记丢到根目录。

归档正文格式（import_doc 无独立标题字段；实测 ima 取正文第一行作为笔记标题）：

<任务主题> （洛谷题：P7077 [CSP-S 2020] 函数调用 - 为什么调用顺序会影响结果）

归档人：信奥教练插件归档时间：2026-10-12 20:18:20 是否查询知识库：未查询是否使用知识库内容：未使用实际检索知识库：无

用户提问 <原始提问>

教练回复 <教练本轮回复>

检索三项（是否查询 / 是否使用 / 实际检索库）放在抬头内、归档时间下面，纯文本无圆点；正文底部不再有「归档元信息」小节。紧跟其后的 ## 推荐关注 小节由推广追加逻辑写入。

⚠️ 抬头必须放在 H1 标题之后：实测（真实账号回读）ima 用正文第一行作为笔记标题，而不是技能文档里写的"首个 # 行"。抬头若排在 H1 之前，所有归档笔记的标题都会变成 "归档人：信奥教练插件"。archiver 配置项决定署名内容。
抬头上下各有一条 --- 分隔线，且分隔线前后保留空行——否则 Markdown 会把归档时间：… 解析成 setext 标题（H2），分隔线也不会渲染。

错题本（mistakes）使用"错题模板"正文，抬头位置相同。

配置

在 cordis.yml / cordis.patch.yml 的 config 中修改：

config:
judge:
compiler: g++ # 编译器命令（应在 PATH 上，或不含空格的可执行文件路径） std: '-std=c++14' # 语言标准（oi-coach 统一 C++14） optimization: '-O2' # 优化参数 timeLimitMs: 2000 # 单测试点时间限制（毫秒） workDir: '' # 评测工作目录；留空 = 系统临时目录（评测后自动清理） ima: enabled: true # 关闭后检索/归档都返回"未启用"，不影响陪练 cliPath: '' # 留空 = 自动定位 ima_api.cjs clientId: '' # 建议留空，用环境变量或 ~/.config/ima/，避免密钥入库 apiKey: '' timeoutMs: 20000 # 单次 ima 调用超时 archiver: 信奥教练插件 # 归档正文顶部"归档人：<archiver>"的署名 notebooks: # 与 ima 客户端里的笔记本名严格一致 archive: 信奥教练-学习档案 mistakes: 信奥教练-错题本 plan: 信奥教练-学习计划 report: 信奥教练-学习报告 weeklyHours: 5 # 每周学习小时数（用于路线图周期估算） defaultStage: j # 默认目标阶段：entry/j/s/province/noi promptSection: true # 注入"信奥教练规则"提示词段落；false = 只注册工具 recommend: # 品牌推荐：每轮回复末尾固定追加「## 推荐关注」（教练规则第 9 条） enabled: true text: 想学更多信奥知识，请关注 欣泽编程 公众号、欣泽编程 视频号、欣泽编程-信奥知识大全 知识库、信奥编程算法 小程序。
showQrcodes: true # 是否附上二维码条图（assets/qrcodes/note-qrcodes.jpg） help: # 使用帮助：使用者不会用时由教练原样发出的文章链接（教练规则第 10 条） articles:
- '学习系统和AI工具'
- '「信奥教练」上线 WorkBuddy 技能市场：接 ima 知识库，陪练评测错题复习全搞定'
- '信奥教练错题讲解实战：不直接给答案，带着孩子把 bug 找到'
- '「信奥学长」刷题好搭档上线 WorkBuddy：题意拆解、考点梳理、解题思路、易错点、三版代码、真评测带归档'

资源推荐（品牌引流，每轮回复末尾固定小节）

教练规则第 9 条要求：每一轮教练回复的最末尾都原样追加下面这个固定小节（enabled: false 可整体关闭）：

推荐关注

想学更多信奥知识，请关注 欣泽编程 公众号、欣泽编程 视频号、欣泽编程-信奥知识大全 知识库、信奥编程算法 小程序。

二维码

- 位置：放在所有正文之后；若本轮有 [归档：…] 状态行，状态行在小节之前（让二维码真正收尾）；
- 二维码：一行四个的条图（note-qrcodes.jpg，绝对路径运行时计算），showQrcodes: false 可省略图片、只保留标题与文案；
- 界面不支持 markdown 图片时同样省略图片。

二维码推广（扫码关注）

assets/qrcodes/ 内置四个渠道的二维码，文件名固定：

| 渠道 | 文件 |
| 欣泽编程 公众号 | wechat-official.jpg |
| 欣泽编程 视频号 | wechat-channels.jpg |
| 欣泽编程-信奥知识大全 知识库 | ima-kb.jpg |
| 信奥编程算法 小程序 | mini-program.jpg |

- 教练规则第 9 条会在需要推广时在回复最末尾追加「## 推荐关注」小节（文案 + 一行四个的二维码条图，note-qrcodes.jpg，绝对路径运行时计算、换机器不失效）；
- 界面不支持图片（纯文本渠道 / 微信）时只保留标题与文案，不贴一串本地路径；
- recommend.showQrcodes: false 可整体关闭二维码；同一会话最多贴一次，不每轮刷。
- 使用说明.md 末尾「扫码关注」小节也直接内嵌了这四张二维码。

资料检索优先（先查 ima 知识库）

教练规则第 5 条要求：信奥/算法/竞赛相关的提问（知识点、真题、纠错、规划、错题复盘）先调用 xinao_ima_search 检索使用者的 ima 知识库（1-3 个关键词），命中内容作为作答依据，再结合内置知识作答；纯问候/闲聊不检索。透明标记如实反映检索状态（未查询 / 已查询，未使用 / 已查询，已使用），并列出实际检索过的库名。

归档笔记末尾自动追加推广

recommend.inNotes: true（默认）时，xinao_ima_archive 在笔记写入成功后会再把「推荐关注 + 四个渠道二维码」追加到该笔记末尾：

- 二维码用一张横向拼接图 assets/qrcodes/note-qrcodes.jpg：四张 120×120 一行排列、 两两间隔 60px（画布 660×120）；宽高在图内固定，任何 markdown 渲染器都表现为"一行四个"；
- 推广段不再额外加分隔线（归档正文本身已以 --- 结尾），避免出现两条横线；
- 按 ima 官方笔记图片规范写入：文案一次 append_doc，拼接图一次 append_doc （图片转 data:image/jpeg;base64,…，单图 <3MiB）；
- 若拼接图缺失，会退回 assets/qrcodes/small/ 的逐张追加（4 次 append_doc）；
- ⚠️ 条图体积有硬上限：ima 调用器把 JSON body 放在命令行参数里，Windows 上限约 32K 字符，所以条图保存为 JPEG（质量 75、约 20KB），base64 后约 27K，刚好安全。改尺寸/清晰度时注意别超限，否则会报 spawn ENAMETOOLONG；
- 追加失败不影响归档结果，只在归档结果里标记 promoMessage；
- 一次归档约多 2 次 ima 调用（1 次文案 + 1 次拼接图）。

使用帮助（不会用时自动发文章链接）

help.articles 里的链接由教练规则第 10 条约束：当使用者表示"不会用 / 怎么用 / 第一次用 / 有没有使用说明"时，教练先用 3 行以内给出最简上手路径（启动 → xinao_doctor 自检 → 直接提要求），然后原样附上这些公众号文章链接（整行 markdown 链接，不改写、不缩短）；平时不会随便发，也不停在"请你自己看文章"。

当前内置 4 篇（可适时发给家长/学生参考）：

1. 学习系统和AI工具
2. 「信奥教练」上线 WorkBuddy 技能市场：接 ima 知识库，陪练评测错题复习全搞定
3. 信奥教练错题讲解实战：不直接给答案，带着孩子把 bug 找到
4. 「信奥学长」刷题好搭档上线 WorkBuddy：题意拆解、考点梳理、解题思路、易错点、三版代码、真评测带归档

使用

直接向教练助手提要求，模型会自动调用对应工具；也可以显式指定：

| 需求 | 对话示例 |
| 环境自检 | "先用 xinao_doctor 看看评测和 ima 能不能用。" |
| 学习路线图 | "帮我制定一份从零基础到 CSP-S 提高组的学习计划，我每周只有 3 小时。" |
| 知识点讲解 | "用 xinao_knowledge 给我讲一下线段树，深度用 detailed。" |
| 生成练习题 | "出一道提高组难度、考树形 DP 的题，附样例和评测数据。" |
| 评测代码 | "用 xinao_judge 评测下面这段 C++ 代码，测试数据是：输入 5 期望输出 120；输入 3 期望输出 6。" |
| 查知识库 | "按我订阅的知识库回答：逆序对有哪些求法？"（会调 xinao_ima_search 并列出实际检索的库名） |
| 归档 | "把这轮问答归档到学习档案。"（xinao_ima_archive，回复末尾附 [归档：成功 …]） |

xinao_judge 会：把代码写入临时目录 → g++ -std=c++14 -O2 编译 → 逐测试点喂入 input、限时运行、与 expected 比对 → 返回每个测试点的判定（AC/WA/TLE/RE）与汇总；编译失败时给出 firstError（第一条错误），方便教练「一次只讲一处」。
判题约定与 OI/NOI 一致：忽略每行行尾空白与文件末尾空行。

教练回复遵循 oi-coach 的透明标记约定：

[信奥教练：已调用] [IMA知识库：未查询] # 或 已查询，未使用 / 已查询，已使用
...
[归档：成功 note_id=… 标题=… 笔记本=信奥教练-学习档案]

安全提示

- xinao_judge 会在 dsh 进程所在的机器上真实编译并运行提交的代码（如同 bash 工具执行命令）。
不要评测来自不可信来源的代码；生产环境中建议把评测放进隔离沙箱/容器。
- ima 凭证只在本机使用，用于替你调用你自己的 ima 账号；不要外传 Client ID / API Key。
- xinao_ima_archive 会把内容真实写入你的 ima 账号（无法通过 API 删除），归档前留意隐私信息。

开发与验证

类型检查（<REPO> 换成仓库路径）
node <REPO>/node_modules/typescript/lib/tsc.js -p tsconfig.check.json
构建 dist/（tsc 输出 ESM，保留相对导入，@deepseek-ai/* 外部化）
node <REPO>/node_modules/typescript/lib/tsc.js -p tsconfig.build.json
单元测试（不依赖 g++ 与 ima 账号）
node --test test/judge.test.mjs test/ima.test.mjs
真实环境联通性自检（会用真实 ima 凭证做只读检查；需在仓库根目录运行）
node <REPO>/node_modules/tsx/dist/cli.mjs test/live-check.mjs
真实写入一条归档并回读（会写进你的 ima 账号，标题默认带"（可删除）"；可传自定义标题）
node <REPO>/node_modules/tsx/dist/cli.mjs test/write-test-note.mjs "自定义标题"

修改 src/.ts 后重新构建 dist/，再以 --patch 方式启动即可生效。

已知限制

- 评测为单进程顺序执行、简单超时终止；内存限制未强制（可在题目描述中约定，或后续在 judge.ts 中接入资源限制）。
- xinao_ima_search 返回的是标题与片段；highlight_content 可能为空，需要原文时可用 fetchContent 取媒体详情（URL 型媒体返回链接，笔记型媒体返回 note_id）。
- ima API 只能读笔记本、不能创建笔记本，也不能删除笔记：归档目标必须先在 ima 客户端建好。
- 知识图谱为内置静态数据，未穷尽全部知识点；可自行在 src/knowledge.ts 中扩展（补充后重新构建）。
- 在「非源码安装」（纯构建产物分发）的 dsh 下，bundle 内对 @deepseek-ai/ 的依赖解析依赖安装环境的包可达性；源码运行方式不受此限制。