信奥学长 wangdapeng325/dsh-oi-senior

dsh-oi-senior v1.0.8 —— 信奥学长 DSH 插件

把技能包 oi-senior（信奥学长） 落地成 DeepSeek Harness 插件：面向 GESP 1~8 级、CSP-J/S、NOIP、NOI 学习者的算法竞赛陪练学长。

学长的定位是「陪你刷、给参考实现」：独立推导、一次给三版 C++14 代码（常规注释 / 详细讲解 / 极简可提交）、附一份解题说明，并用本机 g++ 真编译真评测，做题记录归档到 ima 笔记本「信奥学长-题解复盘」。

与「信奥教练 oi-coach」的分工：oi-coach 是苏格拉底式教练，逼你自己想、默认不给答案；本插件是给你对照实现的学长。两者评测与归档逻辑一致，可并行使用。

使用者请先看 USER-GUIDE.md（安装、四种用法、评测与归档说明、常见问题）；本文档偏实现与维护。

对外介绍/推荐给同学家长可发这篇公众号文章：《「信奥学长」刷题好搭档上线 WorkBuddy：题意拆解、考点梳理、解题思路、易错点、三版代码、真评测带归档》 <https://mp.weixin.qq.com/s/6xZbOt232HGVZfLxKrzpKA>

另有 3 篇配套说明（学习路线 / 教练介绍 / 错题讲解实战），按场景挑一条发，见下文「参考阅读」。

提供的工具

| 工具 | 作用 | 何时使用 |
| oi_solve | 接题工作台：返回学长规程（角色称呼、独立推导纪律、三版代码规范、解题说明骨架、改代码模式、归档格式、随包资源路径） | 用户以「学长 / 信奥学长 / oi学长 / oi-senior」开头，或贴出题面 / 题号 / 洛谷链接 / 自己的半成品代码 |
| oi_judge | 真编译真评测：g++ -std=c++14 -O2 -Wall 编译后逐点判定 AC / WA / TLE / RE / CE，回填每点耗时、期望与实际输出 | 批改提交、验证参考实现、改代码模式下的真编译 |
| oi_archive | 按技能 Step 4 的 10 字段与 6 条格式细则生成归档 markdown，并写入 ima 笔记本「信奥学长-题解复盘」 | 一道题讲完后归档题解复盘 |
| oi_doctor | 环境自检：ima 调用器、凭证来源、目标笔记本 folder_id、本机 g++ 是否可用 | 排查「归档为什么没生效 / 能不能真评测」 |

为什么要有 oi_solve

技能规程（三版代码、10 字段归档格式、评测边界、称呼规则）如果只写在 SKILL.md 里，会随上下文被压缩掉。oi_solve 把这些机器可读地固化成一次工具调用，保证每一轮回复都守得住规程——尤其是容易漂移的三条：

- 自称「学长」、称用户「学弟 / 学妹」，绝不把用户叫成「学长」；
- 三版代码只改注释不改逻辑，且 v3 必须提醒「先自己写自己交」；
- 评测必须写明测试点来源，不得暗示跑了 OJ 私密测试点。

目录结构

dsh-oi-senior/
├── src/
│ ├── index.ts # 插件入口：name/inject/apply/Config + 注册 4 个工具 │ ├── judge.ts # C++14 评测引擎（纯 Node 内置模块，无框架依赖） │ ├── ima.ts # ima 归档引擎（纯 Node 内置模块，无框架依赖） │ └── qrcodes.ts # 关注二维码资源清单（公众号/视频号/知识库/小程序） ├── assets/qrcodes/ # 四张二维码原图（jpg，随包分发） ├── dist/ # 构建产物（加载时使用） ├── test/ │ ├── judge.test.mjs # 评测引擎测试（本机有 g++ 时含真实编译评测用例） │ ├── ima.test.mjs # 归档引擎测试（本地假调用器，不依赖外网） │ ├── qrcodes.test.mjs # 二维码资源：文件真实存在、签名合法、体积合规 │ └── inline-images.test.mjs # data URL 内嵌与大请求改走直连 HTTP ├── scripts/ │ ├── build.mjs # 构建：src/.ts -> dist/.js + 语法校验（+ 可选桩自检） │ ├── verify-real.mjs # 用真实 @deepseek-ai/* 加载 dist 并调用 apply() │ ├── e2e-archive.mjs # 真实归档链路验证（会真的往 ima 写一条笔记，默认不要跑） │ ├── e2e-qrcode-note.mjs # 真实写入带二维码的笔记（会真的写，用于验证渲染） │ ├── e2e-list-notes.mjs # 只读盘点笔记本（不写） │ ├── verify-prompt-section.mjs # 常驻提示段健壮性（有/抛错/缺失三种 ctx） │ └── install.mjs # 安装到 DSH profile / 卸载（含 YAML 复验） ├── skills/oi-senior/ # 随包技能原件（SKILL.md、templates/、oi_tools/） ├── cordis.patch.yml # bundle 配置层（配合 dsh plugin add 使用） └── package.json # bundle manifest（声明 dsh.bundle）

说明：src/.ts 的文件内容是合法 ESM JavaScript（无类型注解）。扩展名沿用 .ts 是为了与技能包命名习惯对齐；构建即「拷贝 + 改名」。

安装

快速安装（推荐）

cd dsh-oi-senior
node scripts/build.mjs # 构建 dist/
node scripts/install.mjs # 安装到 desktop profile

install.mjs 做三件事：

1. 在包内 node_modules/@deepseek-ai 下为 dsh-tools、schemastery 建立指向 DSH profile 自身副本的目录链接 —— 这是插件唯一的外部运行期依赖，指向同一份副本可保证版本天然对齐；
2. 在 ~/.dsh/profiles/<profile>/cordis.patch.yml 追加一条 oi-senior 条目，入口用绝对 file:/// URL。这样插件不必拷贝进 DSH 仓库，也不必成为 pnpm workspace 成员；
3. 落盘后用 profile 自带的 js-yaml 复验：仍是合法顶层数组、oi-senior 恰好出现一次、入口文件可达。复验不过就报错，不会给 DSH 留下坏配置层。

为什么必须包在 - insert: 里：profile 的 patch 层中，平铺的 - id: xxx 是「覆盖既有节点」，而「新增一个插件节点」必须写在 - insert: 列表下（DSH 各 bundle 的 cordis.patch.yml 都是这个形态）。把新插件写成平铺条目不会报错，但会被当成对不存在节点的覆盖而静默失效 —— 这是本项目踩过并已用复验堵住的坑。

常用参数：

node scripts/install.mjs --preview # 只打印改动，不落盘
node scripts/install.mjs --profile web # 指定 profile（默认 desktop）
node scripts/install.mjs --uninstall # 移除条目

装完需要重启 DSH（或该条目被 HMR 热加载）后 4 个工具才会出现。

作为 bundle 安装（分发路径）

在 dsh 仓库根目录执行
pnpm dsh plugin --profile <name> add ./dsh-oi-senior
pnpm dsh --profile <name>

配置

在 cordis.patch.yml（或 bundle 配置层）的 config 中调整：

config:
judge:
compiler: g++ # 编译器命令 std: '-std=c++14' # 语言标准（技能规定 C++14） optimization: '-O2' timeLimitMs: 2000 # 单点时限（毫秒） compileTimeoutMs: 30000 workDir: '' # 空 = 系统临时目录（评测后自动清理） ima: enabled: true # 关掉则 oi_archive 静默跳过 cliPath: '' # ima_api.cjs 路径；空 = 自动定位 clientId: '' # 空 = 用环境变量 / ~/.config/ima/ apiKey: '' timeoutMs: 20000

ima 归档的前置条件

oi_archive 走的是技能自带的 ima_api.cjs 调用器形态（与 oi_tools/archive_note.cjs 一致）。要真正写入，需要：

1. 已安装腾讯 ima 桌面端并登录；
2. 已安装 ima-skill（内含 ima_api.cjs）；插件按 配置 cliPath → 环境变量 IMA_API_CJS → ~/.workbuddy/skills、~/.dsh/skills、~/.claude/skills、~/.codex/skills、~/.cursor/skills、~/.workbuddy/plugins 的顺序定位；
3. 已在 <https://ima.qq.com/agent-interface> 生成自己的 Client ID / API Key，写入 ~/.config/ima/{client_id,api_key}；
4. 已在 ima 客户端手动创建笔记本「信奥学长-题解复盘」（API 无法自动建笔记本）。

任一条件缺失 → 本轮归档静默跳过，绝不假装存过、绝不把笔记落到根目录。先用 oi_doctor 自检最省事。

归档格式要点（技能 Step 4 + 本项目扩展）

- H1 不含日期时间，洛谷题格式：# P7077 [CSP-S 2020] 函数调用 - 树形DP+拓扑序（题号在最前，题名与主题之间用英文半角 - ）；
- 正文最上边的固定版式（由插件自动写入，模型不需要也不应该自己拼）：
P7077 [CSP-S 2020] 函数调用 - 树形DP+拓扑序

归档人：信奥学长插件

归档时间：2026-10-05 09:47:09

「归档人」是固定署名（ARCHIVER 常量，见 src/ima.ts）；两条 --- 分隔线分别夹在「标题与归档人之间」和「归档时间与正文之间」；归档时间精确到秒；
- 两行用「普通段落 + 前后空行」（无项目符号、不加粗），结构与「信奥教练」的笔记一致。实测过的四种写法：

| 写法 | 是否加粗 | 项目符号 | 归档时间下方的 --- |
| 普通段落，--- 后不留空行 | ❌ 加粗 | 无 | 正常 |
| 缩进两格 归档人：… | ❌ 加粗 | 无 | 被吃掉，不显示 |
| 列表项 - 归档人：… | ✅ 不加粗 | ❌ 有一个小圆点 | 正常 |
| 普通段落 + 前后各留一个空行（当前采用） | ✅ 不加粗 | ✅ 无 | 正常 |

关键在空行：空行把两行各自切成独立段落，ima 就不会把「分隔线 --- 之后的第一段」当标签行加粗。
- 首部没有「记录时间」：已按要求去掉，记录时间 不再出现；
- URL 前后各留一个空格（否则 ima 里点链接会 404）；
- 难度写「（蓝题）提高+/省选−」，中文全角括号，且难度值要从洛谷题目页「难度[xxx]」字段抓取，禁止凭记忆估；
- 章节顺序固定：题目来源 → 题目难度 → 题目大意 → 考点梳理 → 解题思路 → 易错点 → 参考代码 → 复杂度 → 评测结论（不叫「状态」）→ 关联题目；
- 正文末尾自动追加推广小节（## 推荐关注），内容为「想学更多信奥知识，请关注 欣泽编程 公众号、欣泽编程 视频号、欣泽编程-信奥知识大全 知识库、信奥编程算法 小程序。」：渠道清单是 src/ima.ts 里的 PROMO_CHANNELS 常量，改一处即可；oi_archive 传 promo: false 可关闭、传 promoText 可覆盖文案；
- 成功时回复末尾附 [归档：成功 note_id=...]；失败 / 无凭证 / 笔记本不存在时静默，不打印任何归档标签。

关注二维码（笔记里也能扫码）

四张二维码随包放在 assets/qrcodes/（公众号 / 视频号 / ima 知识库 / 小程序），清单见 src/qrcodes.ts。

- 归档笔记：推广小节（## 推荐关注 + 一句话渠道文案）之后，直接跟一张二维码合成图，没有小节标题、没有图注（与「信奥教练」笔记本的版式一致）。
合成图里四张二维码各 120×120、间隔 60，整张 660×120（assets/qrcodes/combined.png），笔记里以 显示。

为什么不放四张独立图：四张原图宽高比不同，即使写死 width/height，渲染端仍按原比例缩放，结果高度参差不齐、看起来偏大（实测过）。合成图正解。
附带好处：笔记体积从 ~585KB 降到 ~107KB。

视频号 / 知识库两张必须裁剪：这两个原图带顶部标题、底部说明和 App logo，整体缩进 120 的格子后二维码本体只剩 ~80px，手机扫不出。裁剪时要注意：

- 裁剪框必须是正方形，否则四张渲染出来尺寸不一致（脚本会校验，非正方形直接报错）；
- 别裁掉二维码图案本身：视频号的放射状装饰点与三个定位角、知识库的绿色底与右下角 ima 字样，都属于二维码图案，切边就扫不出；
- 只裁掉纯装饰文字（顶部标题、底部「扫一扫二维码…」「扫码订阅ima知识库」）。

裁剪框是人工用网格量出来的（scripts/qr-grid.py 叠坐标 + scripts/qr-crop-preview.py 并排预览比较），不用自动检测——自动检测会被中间那个彩色 logo 吸走，把二维码边缘切掉。
改了四张原图后要重跑 python scripts/make-qr-composite.py；布局常量在 src/qrcodes.ts：QR_CELL = 120、QR_GAP = 60、COMBINED_WIDTH = 660、COMBINED_HEIGHT = 120。
oi_archive 传 qrcodes: false 可关闭二维码。
- 对话回复：oi_solve 返回的「关注二维码」小节给出四张图的绝对路径，模型用 直接渲染成图片。

为什么不走 ima 的图片上传接口：openapi/mcp_cloud_agent/upload_temp_file 在当前凭证下返回 100001 session ID is required（连 ima-skill 自带的 note-images.cjs --url 也一样失败），拿不到 download_url。
因此改为把图片以 data URL 内嵌进笔记正文（已实测 ima 能正常渲染）。

由此带来的两个实现约束：

1. 带 data URL 的正文会把请求体撑到 ~586KB，塞进命令行参数会 spawn ENAMETOOLONG，所以 callImaAuto 在请求体超过 16KB 时自动改走直连 HTTP（协议与 ima_api.cjs 等价）。
2. 每条笔记会因此变大（四张二维码约 +438KB → base64 约 +584KB）。内嵌总量有上限 MAX_INLINE_IMAGE_BYTES = 4 MiB，超限的图片会被跳过并保留原引用（不阻断归档）。

推广推荐的插入时机

对话回复末尾也带推广 + 二维码图：oi_solve 返回 promo.chatFooter.markdown（分隔线 + 一句话渠道文案 + 同一张二维码合成图），模型把它原样附在回复最后。插件级常驻提示段（systemPrompt.section，名字 plugin:dsh-oi-senior，order 106）里也内联了这整段，所以即使模型没调用 oi_solve 也知道要附。

- 同一轮对话只出现一次，不要改写渠道名、不要自己另拼图片路径；
- 例外：用户正在排错调 bug、或只问一个极小的问题时可以省略；其余实质回答（讲题、讲解、评测、复盘）都附在末尾；
- 对话里的图片用 ...，DSH 直接读本地文件渲染；笔记里则内嵌为 data URL。

oi_solve 还会返回四张单图的路径（qrcodes.items），用户想看单个渠道时模型可以逐张贴。

参考阅读（4 篇公众号文章）

常量 REFERENCE_ARTICLES（src/index.ts）里登记了 4 篇说明文章，每篇带 title / url / when：

| key | 文章 | 适用场景 |
| learning-system | 学习系统和AI工具 | 问学习路线、AI 工具怎么用 |
| coach-launch | 「信奥教练」上线 WorkBuddy | 想了解教练能做什么 |
| coach-debug-demo | 信奥教练错题讲解实战 | 问错题怎么讲、家长怎么陪 |
| senior-launch | 「信奥学长」刷题好搭档 | 了解/推荐本插件（即 INTRO_ARTICLE） |

投放纪律（REFERENCE_RULES）：按场景只挑一条发，说清是公众号文章；同一轮最多发一次链接；正在排错时不插。用户问「还有别的资料吗」再给其余的。

同时暴露在 oi_solve 的 references.articles 与常驻提示段里，本地文档见 USER-GUIDE.md §八。

评测规程要点

- 默认只用题目公开样例；OJ 不公开完整测试点，本地通常只有样例。要全量验证就用随包的 skills/oi-senior/oi_tools/checker_lib.py 自造对拍数据。每轮评测必须在回复里写明测试点来源。
- 输出比对遵循 OI 宽松空白约定：忽略每行行尾空白、忽略文件末尾空行，其余逐字符比较。
- 递归深题用 recursion: true（加 -Wl,--stack,16777216）避免假 RE。
- 文件 IO 题（freopen xxx.in / xxx.out）用 fileIo: true，评测不走 stdin 重定向。
- special judge / 浮点多解不能逐字符比时必须先声明，改用容差比对，否则会误判 WA。
- 找不到编译器 → 如实告知「本环境无 C++ 编译器，无法真实评测」，退回静态审阅，绝不谎称跑了。

开发

node scripts/build.mjs --check # 构建 + 语法校验
node scripts/build.mjs --selftest # 额外跑桩接线自检（沙箱，不碰本包 node_modules）
node scripts/verify-real.mjs # 用真实 @deepseek-ai/ 加载 dist 并调用 apply()（推荐）
node scripts/verify-prompt-section.mjs # 常驻提示段：有服务 / 抛错 / 缺失三种 ctx 都必须不影响工具注册
node scripts/e2e-list-notes.mjs # 只读盘点 ima 笔记本（不写任何东西）
node --test "test/.test.mjs" # 单元测试

verify-real.mjs 是本插件的关键验证手段：它用 DSH profile 里真实的 @deepseek-ai/dsh-tools 与 schemastery 加载 dist/index.js、跑真实 Config 解析与 defineTool 参数校验，因此能证明「插件在真实框架下可用」，而不只是「语法没错」。

安全提示

oi_judge 会在 DSH 进程所在机器上真实编译并运行提交的代码（等同 bash 工具执行命令）。只评测可信来源的提交；生产环境建议把评测放进隔离沙箱或容器。

验证状态（交付时 · v1.0.8）

| 项目 | 结果 |
| 单元测试 | 87/87 通过（评测引擎 18 + 归档引擎 35 + 工具接线 15 + 二维码资源 9 + 内嵌图片与传输 10），node --test "test/.test.mjs" |
| 真实框架加载 | node scripts/verify-real.mjs 全通过：真实 Config 解析、4 工具注册、参数硬校验、lossless JSON |
| 真实编译器评测 | g++ 16.2.0 真编译真跑：AC / WA / TLE / RE / CE、fileIo、超大输出截断、运行中取消全部实测通过 |
| 真实 ima 归档 | openapi/note/v1/import_doc 返回 code=0 并取得真实 note_id（端到端写入成功） |
| 真实 ima 只读 | list_notebook / list_note 均 code=0；limit 边界实测 20→ok、21/50→code=51 |
| 独立验收 | 两轮外部验收（task-3 七节 + 缺陷复核五项）全部通过，报告见 review/REPORT-task3.md、review/RECHECK-round2.md |

生效前提：需要重启 DSH

profile 配置已写入，插件已能被 DSH 加载并调用（实测 harness 派发成功）。但 DSH 是在启动时装配 cordis 配置树的，本轮修复需要重启 DSH（或触发该条目 HMR 重载）后才会生效。

重启后建议按这个顺序自检：

oi_doctor() # 应显示 ima 已连通、笔记本就绪、g++ 可用
oi_solve(topic="P7077") # 只给题号也应正常返回规程
oi_judge(code=..., tests=[...]) # 真编译真评测

已知的验收残留

- ~/.dsh/profiles/desktop/cordis.patch.yml.bak-oi-senior 是安装前的备份，确认新配置可用后可删除。
- 本次为验证真实写入，在 ima 中留下 2 条笔记（见下方「本次交付期间写入 ima 的两条笔记」）。
- 「重启后 oi_archive 对非法格式是否确实拦截」属未验证：验证它需要拿非法格式触发一次真实归档，而若拦截尚未加载就会真的写库，因此在重启前刻意没做。

已知限制

- 评测为单进程顺序执行、简单超时终止；内存限制未强制（可在题目描述中约定）。
- 没有特殊评测（special judge）能力；浮点多解需人工容差判断。
- 归档依赖外部 ima_api.cjs；未安装 ima-skill 时只能生成 markdown 供人工保存。
- 随包技能资源（skills/oi-senior/）与插件同号为 1.0.8：技能原件的 frontmatter version 与归档首部说明已随本次改版一起更新，因此它不再是上游 1.0.2 的逐字节副本 —— 相对上游的差异只有「归档正文首部版式」这一处。插件版本见 package.json，也会随 oi_solve（plugin.version）与 oi_doctor（pluginVersion）暴露出来，便于确认运行实例加载的是哪一版。
- 插件按技能纪律不实现删除接口（只写不读、且只有 list/import/append）。误写的笔记只能到 ima 客户端手动删除。
- 归档正文首部相对上游技能新增（有意为之）：本项目按使用要求，在标题与正文之间插入了 --- + 归档人：… + 归档时间：… + --- 的首部（两行为普通段落、前后留空行，无项目符号、不加粗），并去掉了上游的 记录时间。随包 skills/oi-senior/SKILL.md 的 frontmatter 已更新为 1.0.8，Step 4/5.3 的首部描述也已同步改写成本项目口径。首部版式以本插件工具的格式校验为准——oi_archive 会强制两条分隔线的位置与「无符号普通段落」写法。
- skills/oi-senior/oi_tools/archive_note.cjs 里写的接口路径是 /openapi/wiki/import_doc，与 ima 官方 notes 模块的 openapi/note/v1/import_doc 不一致（本插件用后者，已在真实账号验证 code=0）。该脚本疑为技能包自身的 bug，已如实记录、未照抄。
- fileIo 模式只认「源码里出现的 .out 字面量」与测试点名。若程序用变量 / 字符串拼接构造输出文件名，探测不到 → 判 WA（fail-loud；stderr 会列出目录里实际出现的 .out 文件名供人工判断，但不读其内容、不参与比对）。
- 进一步边界：若程序写了多个 .out，候选顺序是「源码中靠前出现的 .out → 源码 .in 名 → 测试点 name → main」，因此源码里靠前的辅助 .out 可能被先读走而误判 WA（低概率；方向仍是可见的假 WA，不是假 AC）。正常 OI 写法（一题只写一个 .out）不受影响。

本次交付期间写入 ima 的两条笔记（需人工清理）

为验证真实写入链路，本次在「信奥学长-题解复盘」中产生了 2 条记录。插件按技能纪律不实现删除接口，请到 ima 客户端按需处理：

| note_id | 标题 | 说明 |
| 7515384269769076 | 未命名题解 | 建议删除。独立验收过程中误写入的垃圾笔记（正文只有一行记录时间），根因是当时「格式校验不拦截写入」的缺陷；该缺陷已修复并加了回归测试。 |
| 7515384139774210 | 信奥学长插件自检 - 题解复盘归档链路验证 - ima归档与评测联动 | 建议保留或删除均可。这是经用户授权做的一次有意归档，用来证明 import_doc 端到端可用（返回 code=0 并拿到真实 note_id）。 |

该笔记本原有的 6 条记录未受影响。验收期间另有一条自检笔记已由用户本人在 ima 客户端删除（插件无删除能力）。