diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index abaf160..ce7c90d 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -81,3 +81,14 @@ jobs: - run: pnpm install --frozen-lockfile - run: pnpm exec tsc --noEmit - run: pnpm test + + deepseek-harness-plugin: + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 22 + - name: bloomtutor-dsh package contract (real-host check is scripts/acceptance.mjs, run by hand) + run: node --test integrations/deepseek-harness/test/*.test.mjs diff --git a/README.md b/README.md index 100d41e..ca6fe66 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ In 1984, educational psychologist Benjamin Bloom discovered that students receiv | Mode | Setup | Best for | |------|-------|----------| -| **CLI** | Claude Code + terminal | Power users who like Markdown editors | +| **CLI** | Claude Code (or DeepSeek Harness) + terminal | Power users who like Markdown editors | | **Web** | Browser (Next.js + FastAPI), self-hosted | Visual learners, your own materials and PDFs | Both follow the same flow: **syllabus → lesson → annotate → feedback → next lesson → evaluation → summary**. @@ -73,6 +73,15 @@ Then say: `Create a new folder and help me learn [any topic]` /plugin install bloom@li-evan ``` +**Or use it in [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)**: the same skills ship as the `bloomtutor-dsh` plugin. Until it is on npm, build it from this clone: + +```bash +node integrations/deepseek-harness/scripts/pack.mjs +dsh plugin --profile web add "$PWD/integrations/deepseek-harness/bloomtutor-dsh-0.1.0.tgz" +``` + +Details in [integrations/deepseek-harness](./integrations/deepseek-harness/PACKAGE_README.md). + See [GUIDE.md](./GUIDE.md) for the full walkthrough. ## Quick Start: Web Mode @@ -196,7 +205,7 @@ Bloom ships a set of portable **[Claude Code](https://claude.com/claude-code) sk | **learn-prototype** | Learn by building the crappiest working prototype, then iterating | | **learn-feynman** | Verify true understanding by explaining it back | -Each folder is dependency-free: copy it into a skills directory, then just talk to Claude Code (e.g. *"help me learn X"*, *"I'm done reading"*). +Each folder is dependency-free: copy it into a skills directory, then just talk to Claude Code (e.g. *"help me learn X"*, *"I'm done reading"*). The same folders also run in DeepSeek Harness through the `bloomtutor-dsh` plugin. ## Tech Stack @@ -237,6 +246,7 @@ make up / make down # docker compose start / stop ├── extension/ # browser web clipper ├── docs/ARCHITECTURE.md # how the pieces fit together ├── example/ # pre-built topics for CLI mode +├── integrations/deepseek-harness/ # the bloomtutor-dsh plugin for DeepSeek Harness ├── site/ # marketing website (standalone Astro static build, decoupled from the app) └── skills/ # portable Claude Code skills (bloom-tutor + learn-*) ``` diff --git a/README.zh.md b/README.zh.md index f31be3a..06dfa45 100644 --- a/README.zh.md +++ b/README.zh.md @@ -42,7 +42,7 @@ | 方式 | 配置 | 适合 | |------|------|------| -| **CLI 模式** | Claude Code + 终端 | 喜欢用 Markdown 编辑器的人 | +| **CLI 模式** | Claude Code(或 DeepSeek Harness)+ 终端 | 喜欢用 Markdown 编辑器的人 | | **Web 模式** | 浏览器(Next.js + FastAPI),自己部署 | 偏好可视化界面、想用自己的资料和 PDF 的人 | 两种模式遵循相同流程:**大纲 → 课文 → 批注 → 反馈 → 下一篇 → 评估 → 总结**。 @@ -73,6 +73,15 @@ claude /plugin install bloom@li-evan ``` +**也可以在 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 里用**:同一套 skill 打包成了 `bloomtutor-dsh` 插件。发布到 npm 之前,先从这个 clone 打包安装: + +```bash +node integrations/deepseek-harness/scripts/pack.mjs +dsh plugin --profile web add "$PWD/integrations/deepseek-harness/bloomtutor-dsh-0.1.0.tgz" +``` + +详见 [integrations/deepseek-harness](./integrations/deepseek-harness/PACKAGE_README.md#中文)。 + 详见 [GUIDE.zh.md](./GUIDE.zh.md)。 ## 快速开始:Web 模式 @@ -195,7 +204,7 @@ Bloom 在 [`skills/`](./skills/) 里附带一组可移植的 **[Claude Code](htt | **learn-prototype** | 用「先做最垃圾的能跑原型再迭代」来学 | | **learn-feynman** | 用「讲给别人听」自查是否真懂 | -每个文件夹都零依赖:拷进任意 skills 目录,然后直接对 Claude Code 说话(如 *「帮我学 X」*、*「我读完了」*)。 +每个文件夹都零依赖:拷进任意 skills 目录,然后直接对 Claude Code 说话(如 *「帮我学 X」*、*「我读完了」*)。同样这些文件夹也能通过 `bloomtutor-dsh` 插件在 DeepSeek Harness 里用。 ## 技术栈 @@ -236,6 +245,7 @@ make up / make down # docker compose 启动 / 停止 ├── extension/ # 浏览器网页剪藏插件 ├── docs/ARCHITECTURE.md # 各部分怎么配合 ├── example/ # CLI 模式的预制主题 +├── integrations/deepseek-harness/ # DeepSeek Harness 插件 bloomtutor-dsh ├── site/ # 营销网站(独立的 Astro 静态站,和应用解耦) └── skills/ # 可移植的 Claude Code 技能(bloom-tutor + learn-*) ``` diff --git a/integrations/deepseek-harness/.gitignore b/integrations/deepseek-harness/.gitignore new file mode 100644 index 0000000..aa1ec1e --- /dev/null +++ b/integrations/deepseek-harness/.gitignore @@ -0,0 +1 @@ +*.tgz diff --git a/integrations/deepseek-harness/PACKAGE_README.md b/integrations/deepseek-harness/PACKAGE_README.md new file mode 100644 index 0000000..6cab75e --- /dev/null +++ b/integrations/deepseek-harness/PACKAGE_README.md @@ -0,0 +1,82 @@ +# bloomtutor-dsh + +[BloomTutor](https://github.com/Li-Evan/BloomTutor) for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): a one-on-one AI tutor that writes a syllabus, teaches one adaptive lesson at a time, and shapes the next lesson from your notes and feedback. + +This is a community plugin. It is not made or endorsed by DeepSeek. + +[中文说明](#中文) + +## Install + +```bash +dsh plugin --profile web add bloomtutor-dsh@0.1.0 +``` + +Use `npx @deepseek-ai/dsh plugin …` if `dsh` is not on your PATH. Run the command once for each profile you use. Running it again with a newer version upgrades the plugin. + +Tested with DeepSeek Harness `0.2.2-rc.1` on Node 24. DeepSeek Harness is a developer preview; other versions may work but have not been tested. + +## Use + +Say in a chat: + +```text +Create a new folder and help me learn Rust ownership +``` + +Or name a skill: + +```text +Use the learn-feynman skill to check whether I really understand TCP congestion control +``` + +| Skill | What it does | +|-------|-------------| +| `bloom-tutor` | The full tutoring loop: syllabus → one lesson at a time → your `???` marks and feedback → next lesson → review → summary | +| `learn-deep` | Explains a new concept through all five lenses below in one pass | +| `learn-crossover` | Learn something new through what you already know | +| `learn-occam` | Decide whether something is worth learning, and how deep | +| `learn-graph` | Map a field and plan a learning path | +| `learn-prototype` | Learn by building the roughest working version, then improving it | +| `learn-feynman` | Check your understanding by explaining it back | + +The tutor keeps everything as Markdown in your workspace: a folder per topic with `syllabus.md`, `01.md`, `02.md` … and a `learning-log.jsonl` at the workspace root. + +## Which copy loads + +Skills you installed yourself win over this package when they have the same name. DeepSeek Harness looks in `/.dsh/skills`, `/.agents/skills`, `~/.dsh/skills` and `~/.agents/skills` before it looks here. If you copied `bloom-tutor` into one of those folders earlier, that copy is the one that loads. + +## Uninstall + +```bash +dsh plugin --profile web remove bloomtutor-dsh +``` + +## What it changes in DeepSeek Harness + +- `cordis.patch.yml` adds one `@deepseek-ai/dsh-skill-filesystem` provider, named `bloomtutor-plugin`, over the package's `skills/` folder. It keeps your own project and personal skill folders in view. +- Its `bundledSkillDir` value is a `!!js` expression that DeepSeek Harness runs in the host process. It only uses Node's built-in `path` and `module` helpers to find this installed package. +- The package has no tools, dependencies, install scripts, network requests or telemetry. +- The skills read and write Markdown files in your workspace. + +## 中文 + +在 DeepSeek Harness 里用 BloomTutor:一位一对一的 AI 导师,先出学习大纲,每次只讲一篇,下一篇按你的批注和反馈来调整。这是社区插件,不是 DeepSeek 官方出品。 + +安装: + +```bash +dsh plugin --profile web add bloomtutor-dsh@0.1.0 +``` + +`dsh` 不在 PATH 里时,用 `npx @deepseek-ai/dsh plugin …`。每个要用的 profile 各装一次;换成新版本号再运行一次就是升级。已在 DeepSeek Harness `0.2.2-rc.1`、Node 24 上测过。 + +装好后在对话里说「开个文件夹,帮我学 Rust 的所有权」,或者点名某个 Skill,比如「用 learn-feynman 检验一下我是不是真懂了 TCP 拥塞控制」。读课时在没看懂的地方标 `???`,读完在文末写反馈,然后说「我读完了」。 + +你自己装过的同名 Skill(`<项目>/.dsh/skills`、`<项目>/.agents/skills`、`~/.dsh/skills`、`~/.agents/skills`)优先于插件里的版本。 + +卸载:`dsh plugin --profile web remove bloomtutor-dsh`。 + +## License + +MIT diff --git a/integrations/deepseek-harness/README.md b/integrations/deepseek-harness/README.md new file mode 100644 index 0000000..631c907 --- /dev/null +++ b/integrations/deepseek-harness/README.md @@ -0,0 +1,53 @@ +# DeepSeek Harness plugin + +This folder builds `bloomtutor-dsh`, the npm package that brings BloomTutor's skills to [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH). Users install it with `dsh plugin --profile web add bloomtutor-dsh`; what they see is in [PACKAGE_README.md](PACKAGE_README.md), which becomes the package's README. + +## How it works + +The package is skills only. `package.json` declares `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`, and the patch inserts one `@deepseek-ai/dsh-skill-filesystem` provider named `bloomtutor-plugin` whose `bundledSkillDir` is the package's `skills/` folder. DSH then lists those skills in its catalog and loads one when the model calls `skill({ name })`. + +The skills are not stored here. `scripts/pack.mjs` copies every folder with a `SKILL.md` from the repository's top-level [`skills/`](../../skills/) into the package at pack time, so editing a skill there changes the next release. + +| File | Role | +|------|------| +| `package.json` | Package identity, the bundle declaration, display icon | +| `cordis.patch.yml` | The one provider row DSH adds to a profile | +| `locale/*.json`, `docs/DETAIL*.md`, `icon.svg` | Title, description and detail page in DSH's plugin manager | +| `PACKAGE_README.md` | Published as the package README | +| `scripts/pack.mjs` | Stages the files and skills, runs `npm pack` | +| `scripts/acceptance.mjs` | Installs a real DSH and checks install, load, precedence and uninstall | +| `test/` | Package contract tests and the probe plugin the acceptance script mounts | + +## Check it + +Contract tests (no network, run in CI): + +```bash +node --test integrations/deepseek-harness/test/*.test.mjs +``` + +Real host (downloads DSH from npm, never calls a model, needs a Node version DSH accepts — 0.2.2 needs 24.9 or newer — and pnpm 10): + +```bash +node integrations/deepseek-harness/scripts/acceptance.mjs +``` + +It works in a temporary directory with its own `DSH_HOME` and `DSH_AGENTS_HOME`, and prints a JSON receipt. If registry.npmjs.org is slow from your network, set `npm_config_registry=https://registry.npmmirror.com/`. + +## Try it before it is on npm + +```bash +node integrations/deepseek-harness/scripts/pack.mjs +dsh plugin --profile web add "$PWD/integrations/deepseek-harness/bloomtutor-dsh-0.1.0.tgz" +``` + +`dsh plugin add` needs an absolute path to the tarball. + +## Release + +1. Bump `version` in `package.json` and the version in `PACKAGE_README.md`'s install commands. +2. Run the contract tests and the acceptance script. Update the tested DSH version in `PACKAGE_README.md` and `TESTED_DSH_VERSION` in `scripts/acceptance.mjs` if you tested a newer host. +3. `node integrations/deepseek-harness/scripts/pack.mjs`, then `npm publish integrations/deepseek-harness/bloomtutor-dsh-.tgz`. +4. Tag the commit `bloomtutor-dsh-v`. + +A published version never changes; ship fixes as a new version. diff --git a/integrations/deepseek-harness/cordis.patch.yml b/integrations/deepseek-harness/cordis.patch.yml new file mode 100644 index 0000000..1afd07d --- /dev/null +++ b/integrations/deepseek-harness/cordis.patch.yml @@ -0,0 +1,18 @@ +# BloomTutor skills for DeepSeek Harness. +# +# Mounts one filesystem Skill provider over this package's skills/ directory. +# includeDefaultRoots keeps the host's project and personal skill roots, so a +# profile whose base provider is off still sees the user's own skills. +# +# bundledSkillDir is a !!js expression: DSH evaluates it in the host process, +# outside the agent sandbox. It only uses Node's built-in path and module +# helpers to find this installed package from the profile's baseUrl. It reads +# no data, makes no requests and spawns nothing. Review any change to it as +# host-process code. +- insert: + - id: bloomtutor-skill-filesystem + name: '@deepseek-ai/dsh-skill-filesystem' + config: + providerName: bloomtutor-plugin + includeDefaultRoots: true + bundledSkillDir: !!js process.getBuiltinModule('node:path').join(process.getBuiltinModule('node:path').dirname(process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('bloomtutor-dsh/package.json')), 'skills') diff --git a/integrations/deepseek-harness/docs/DETAIL.md b/integrations/deepseek-harness/docs/DETAIL.md new file mode 100644 index 0000000..b5c2286 --- /dev/null +++ b/integrations/deepseek-harness/docs/DETAIL.md @@ -0,0 +1,47 @@ +# BloomTutor + +A one-on-one AI tutor for anything you want to learn. It is built on Benjamin Bloom's 1984 finding that students with a personal tutor score two standard deviations above classroom learners. + +## What you get + +| Skill | Use it when | +|-------|-------------| +| **bloom-tutor** | You want to learn a topic step by step. It writes a syllabus, teaches one lesson at a time, and shapes the next lesson from your `???` marks and feedback. | +| **learn-deep** | You meet a new concept and want it explained through all five lenses below in one pass. | +| **learn-crossover** | Something new feels hard and you want to learn it through what you already know. | +| **learn-occam** | You are deciding whether something is worth learning, and how deep to go. | +| **learn-graph** | You want a map of a whole field and a learning path through it. | +| **learn-prototype** | You learn best by building a rough first version and improving it. | +| **learn-feynman** | You think you understand something and want to check by explaining it back. | + +## Start + +Say in a chat: + +```text +Create a new folder and help me learn Rust ownership +``` + +The tutor writes `syllabus.md` and the first lesson, `01.md`. Read it, put `???` after anything unclear, write your thoughts in the feedback section at the end, then say `I'm done reading`. The next lesson starts from what you marked. + +You can also name a skill directly: + +```text +Use the learn-feynman skill to check whether I really understand TCP congestion control +``` + +## Your files + +Everything is plain Markdown in your workspace: + +``` +Rust ownership/ +├── syllabus.md # goals you can check off +├── 01.md, 02.md … # one lesson at a time +└── summary.md # written after the final review lesson +learning-log.jsonl # at the workspace root, across all topics +``` + +## Prefer a browser? + +The same tutor also runs as a web app for your own materials, PDFs and web articles: use it at [bloomtutor.app](https://bloomtutor.app), or self-host it from [Li-Evan/BloomTutor](https://github.com/Li-Evan/BloomTutor). diff --git a/integrations/deepseek-harness/docs/DETAIL.zh.md b/integrations/deepseek-harness/docs/DETAIL.zh.md new file mode 100644 index 0000000..f120750 --- /dev/null +++ b/integrations/deepseek-harness/docs/DETAIL.zh.md @@ -0,0 +1,47 @@ +# BloomTutor + +一位一对一的 AI 导师,想学什么都可以。它来自 Benjamin Bloom 1984 年的研究:有私人导师的学生,成绩比课堂学生高出两个标准差。 + +## 装上之后有什么 + +| Skill | 什么时候用 | +|-------|-----------| +| **bloom-tutor** | 想一步步学一个课题。它先出学习大纲,每次只讲一篇,下一篇按你标的 `???` 和反馈来调整。 | +| **learn-deep** | 碰到一个新概念,想用下面五个角度一次讲透。 | +| **learn-crossover** | 新东西学着吃力,想借你已经会的知识来理解它。 | +| **learn-occam** | 拿不准值不值得学、要学到多深。 | +| **learn-graph** | 想看清一个领域的全貌,排一条学习路线。 | +| **learn-prototype** | 喜欢先做个粗糙的版本,再一点点改好。 | +| **learn-feynman** | 觉得自己懂了,想用自己的话讲一遍来检验。 | + +## 开始 + +在对话里说: + +```text +开个文件夹,帮我学 Rust 的所有权 +``` + +导师会写出 `syllabus.md` 和第一篇 `01.md`。读的时候在没看懂的地方标 `???`,读完在文末的反馈区写下想法,然后说「我读完了」。下一篇会从你标的地方讲起。 + +也可以直接点名某个 Skill: + +```text +用 learn-feynman 检验一下我是不是真懂了 TCP 拥塞控制 +``` + +## 你的文件 + +所有内容都是工作区里的 Markdown 文件: + +``` +Rust的所有权/ +├── syllabus.md # 可以逐条打勾的学习目标 +├── 01.md, 02.md … # 一次一篇 +└── summary.md # 读完最后的复盘篇后生成 +learning-log.jsonl # 在工作区根目录,记录所有课题 +``` + +## 想在浏览器里学? + +同一位导师也有网页版,能学你自己的资料、PDF 和网页文章:直接用 [bloomtutor.app](https://bloomtutor.app),或者从 [Li-Evan/BloomTutor](https://github.com/Li-Evan/BloomTutor) 自己部署。 diff --git a/integrations/deepseek-harness/icon.svg b/integrations/deepseek-harness/icon.svg new file mode 100644 index 0000000..7b75042 --- /dev/null +++ b/integrations/deepseek-harness/icon.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/integrations/deepseek-harness/locale/en.json b/integrations/deepseek-harness/locale/en.json new file mode 100644 index 0000000..1dd3506 --- /dev/null +++ b/integrations/deepseek-harness/locale/en.json @@ -0,0 +1,7 @@ +{ + "meta": { + "title": "BloomTutor", + "description": "A personal AI tutor based on Bloom's 2-sigma research: it writes a syllabus, teaches one adaptive lesson at a time, and shapes the next lesson from your notes and feedback.", + "detail": "docs/DETAIL.md" + } +} diff --git a/integrations/deepseek-harness/locale/zh.json b/integrations/deepseek-harness/locale/zh.json new file mode 100644 index 0000000..330012e --- /dev/null +++ b/integrations/deepseek-harness/locale/zh.json @@ -0,0 +1,7 @@ +{ + "meta": { + "title": "BloomTutor", + "description": "基于 Bloom 2 Sigma 研究的 AI 私人导师:先给你出学习大纲,每次只讲一篇,下一篇按你的批注和反馈来调整。", + "detail": "docs/DETAIL.zh.md" + } +} diff --git a/integrations/deepseek-harness/package.json b/integrations/deepseek-harness/package.json new file mode 100644 index 0000000..832afce --- /dev/null +++ b/integrations/deepseek-harness/package.json @@ -0,0 +1,49 @@ +{ + "name": "bloomtutor-dsh", + "version": "0.1.0", + "description": "BloomTutor's AI tutor skills for DeepSeek Harness: a syllabus, one adaptive lesson at a time, and six learning-method skills.", + "license": "MIT", + "type": "module", + "icon": "./icon.svg", + "exports": { + "./package.json": "./package.json", + "./locale/*.json": "./locale/*.json" + }, + "files": [ + "locale/*.json", + "docs", + "cordis.patch.yml", + "icon.svg", + "skills", + "README.md", + "LICENSE" + ], + "keywords": [ + "dsh-plugin", + "deepseek-harness", + "agent-skills", + "ai-tutor", + "bloom-2-sigma", + "socratic-method", + "education" + ], + "author": { + "name": "Li Zhengping", + "url": "https://github.com/Li-Evan" + }, + "homepage": "https://github.com/Li-Evan/BloomTutor/tree/main/integrations/deepseek-harness", + "repository": { + "type": "git", + "url": "git+https://github.com/Li-Evan/BloomTutor.git", + "directory": "integrations/deepseek-harness" + }, + "bugs": "https://github.com/Li-Evan/BloomTutor/issues", + "publishConfig": { + "access": "public" + }, + "dsh": { + "bundle": { + "patch": "./cordis.patch.yml" + } + } +} diff --git a/integrations/deepseek-harness/scripts/acceptance.mjs b/integrations/deepseek-harness/scripts/acceptance.mjs new file mode 100644 index 0000000..417bdec --- /dev/null +++ b/integrations/deepseek-harness/scripts/acceptance.mjs @@ -0,0 +1,237 @@ +#!/usr/bin/env node +// Real-host acceptance for bloomtutor-dsh. Run it before every release. +// +// It is not part of CI: it downloads DeepSeek Harness from npm and boots it in +// throwaway profiles. Everything lives in a temporary directory (DSH_HOME and +// DSH_AGENTS_HOME point there), so your own ~/.dsh and ~/.agents are untouched. +// It never calls a model. +// +// Needs: a Node version the DSH release accepts (0.2.2 needs >= 24.9), pnpm 10 +// on PATH, and network access to the npm registry. +// +// node integrations/deepseek-harness/scripts/acceptance.mjs +// DSH_VERSION=0.2.2-rc.3 node integrations/deepseek-harness/scripts/acceptance.mjs +// node integrations/deepseek-harness/scripts/acceptance.mjs --dsh-runtime /abs/dir # reuse a dir where @deepseek-ai/dsh is installed +// node integrations/deepseek-harness/scripts/acceptance.mjs --keep # keep the temporary directory +// +// Prints a JSON receipt on stdout; progress goes to stderr. + +import { spawn, spawnSync } from 'node:child_process'; +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; +import { pathToFileURL } from 'node:url'; + +import { integrationRoot, listSkillNames, pack } from './pack.mjs'; + +export const TESTED_DSH_VERSION = '0.2.2-rc.1'; +const DSH_VERSION = process.env.DSH_VERSION || TESTED_DSH_VERSION; +const PROFILE = 'bloomtutor-dsh-acceptance'; +const PROVIDER = 'bloomtutor-plugin'; +const ROW_ID = 'bloomtutor-skill-filesystem'; +const manifest = JSON.parse(fs.readFileSync(path.join(integrationRoot, 'package.json'), 'utf8')); +const PACKAGE_NAME = manifest.name; +const SKILLS = listSkillNames(); + +const argValue = (flag) => { + const index = process.argv.indexOf(flag); + return index === -1 ? undefined : process.argv[index + 1]; +}; +const keep = process.argv.includes('--keep'); +const reuseRuntime = argValue('--dsh-runtime'); + +const steps = []; +const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'bloomtutor-dsh-acceptance-')); + +function finish(code) { + if (keep) process.stderr.write(`kept ${scratch}\n`); + else fs.rmSync(scratch, { recursive: true, force: true }); + process.exit(code); +} +function pass(step, detail = {}) { + steps.push({ step, ...detail }); + process.stderr.write(`ok ${step}\n`); +} +function fail(step, message, detail) { + process.stderr.write(`FAIL ${step}: ${message}\n`); + if (detail) process.stderr.write(`${JSON.stringify(detail, null, 2)}\n`); + finish(1); +} +const tail = (text = '', lines = 40) => text.split('\n').slice(-lines).join('\n'); +function requireOk(step, result, label) { + if (result.status !== 0) { + fail(step, `${label} exited ${result.status ?? result.signal ?? result.error?.message}`, { + stdout: tail(result.stdout), + stderr: tail(result.stderr), + }); + } +} + +const dshHome = path.join(scratch, 'dsh-home'); +const agentsHome = path.join(scratch, 'agents-home'); +const workspace = path.join(scratch, 'workspace'); +for (const dir of [dshHome, agentsHome, workspace]) fs.mkdirSync(dir); +// Anchor DSH's project-root lookup here even if the temp dir has a Git ancestor. +fs.mkdirSync(path.join(workspace, '.git')); +const env = { + ...process.env, + DSH_HOME: dshHome, + DSH_AGENTS_HOME: agentsHome, + DSH_TELEMETRY_DISABLED: '1', + npm_config_update_notifier: 'false', +}; + +// 1. Build the tarball exactly as it would be published. +const tarball = path.join(scratch, `${PACKAGE_NAME}-${manifest.version}.tgz`); +const packed = pack({ out: tarball }); +const missing = SKILLS.filter((skill) => !packed.files.includes(`skills/${skill}/SKILL.md`)); +if (missing.length) fail('pack', 'tarball is missing skills', { missing }); +pass('pack', { files: packed.files.length, skills: SKILLS }); + +// 2. Install the pinned DSH host on its own, so host install failures are not +// mistaken for plugin failures. Only the host's known native builds may run. +let runtime = reuseRuntime && path.resolve(reuseRuntime); +if (!runtime) { + runtime = path.join(scratch, 'dsh-runtime'); + fs.mkdirSync(runtime); + fs.writeFileSync(path.join(runtime, 'package.json'), '{"name":"dsh-runtime","private":true}\n'); + const install = spawnSync('pnpm', [ + 'add', '--save-exact', '--reporter=append-only', + '--allow-build=@deepseek-ai/dsh-subprocess-local', + '--allow-build=@google/genai', + '--allow-build=koffi', + '--allow-build=node-pty', + '--allow-build=protobufjs', + `@deepseek-ai/dsh@${DSH_VERSION}`, + ], { cwd: runtime, env, encoding: 'utf8', timeout: 600_000, shell: process.platform === 'win32' }); + requireOk('dsh-install', install, `pnpm add @deepseek-ai/dsh@${DSH_VERSION}`); +} +const dshRoot = path.join(runtime, 'node_modules', '@deepseek-ai', 'dsh'); +const dshBin = path.join(dshRoot, 'lib', 'bin.js'); +const dshManifest = JSON.parse(fs.readFileSync(path.join(dshRoot, 'package.json'), 'utf8')); +if (dshManifest.version !== DSH_VERSION || !fs.existsSync(dshBin)) { + fail('dsh-install', 'installed DSH does not match the requested version', { installed: dshManifest.version, DSH_VERSION }); +} +pass('dsh-install', { version: dshManifest.version, node: process.version }); + +const dsh = (args, timeout = 180_000) => spawnSync(process.execPath, [dshBin, ...args], { + cwd: workspace, env, encoding: 'utf8', timeout, +}); + +// Boot the profile with the probe plugin mounted, wait for its report, stop the host. +const probeModule = pathToFileURL(path.join(integrationRoot, 'test', 'probe-skills.mjs')).href; +const probePatch = path.join(scratch, 'probe.patch.yml'); +fs.writeFileSync(probePatch, `- insert: + - id: bloomtutor-dsh-skill-probe + name: ${JSON.stringify(probeModule)} + inject: [skills] +`); +let probeCount = 0; +async function probe(step, expectedNames) { + const out = path.join(scratch, `probe-${++probeCount}.json`); + const child = spawn(process.execPath, [dshBin, '--profile', PROFILE, '--patch', probePatch], { + cwd: workspace, + env: { + ...env, + BLOOMTUTOR_DSH_PROBE_OUT: out, + BLOOMTUTOR_DSH_PROBE_CWD: workspace, + BLOOMTUTOR_DSH_PROBE_SKILLS: JSON.stringify(expectedNames), + }, + stdio: ['ignore', 'pipe', 'pipe'], + }); + let output = ''; + child.stdout.on('data', (chunk) => { output += chunk; }); + child.stderr.on('data', (chunk) => { output += chunk; }); + const exited = new Promise((resolve) => child.once('exit', (code, signal) => resolve({ code, signal }))); + const started = Date.now(); + let early; + exited.then((status) => { early = status; }); + while (!fs.existsSync(out)) { + if (early) fail(step, `DSH exited ${early.code ?? early.signal} before the probe reported`, { output: tail(output) }); + if (Date.now() - started > 120_000) { + child.kill('SIGTERM'); + fail(step, 'probe timed out', { output: tail(output) }); + } + await new Promise((resolve) => setTimeout(resolve, 250)); + } + child.kill('SIGTERM'); + await Promise.race([exited, new Promise((resolve) => setTimeout(resolve, 10_000))]); + return JSON.parse(fs.readFileSync(out, 'utf8')); +} + +const resourceDir = (definition) => { + const base = definition.resourceBase; + if (typeof base === 'string') return base; + if (base?.path) return base.path; + return path.dirname(definition.path); +}; + +// 3. Install the tarball with the same command users run. +requireOk('plugin-add', dsh(['plugin', '--profile', PROFILE, 'add', tarball]), 'dsh plugin add'); +const profileDir = path.join(dshHome, 'profiles', PROFILE); +const profileManifest = JSON.parse(fs.readFileSync(path.join(profileDir, 'package.json'), 'utf8')); +if (!profileManifest.dependencies?.[PACKAGE_NAME]) { + fail('plugin-add', 'profile does not depend on the package', { dependencies: profileManifest.dependencies }); +} +pass('plugin-add', { profile: PROFILE, dependency: profileManifest.dependencies[PACKAGE_NAME] }); + +// 4. The composed profile carries our provider row with the expected config. +const dump = dsh(['--profile', PROFILE, '--dump-config']); +requireOk('compose', dump, 'dsh --dump-config'); +for (const needle of [`id: ${ROW_ID}`, `providerName: ${PROVIDER}`, 'includeDefaultRoots: true']) { + if (!dump.stdout.includes(needle)) fail('compose', `composed config lacks "${needle}"`, { stdout: tail(dump.stdout, 120) }); +} +pass('compose', { row: ROW_ID }); + +// 5. Every skill is discovered once, from our provider, and loads in full from the installed package. +const loaded = await probe('skill-load', SKILLS); +for (const skill of SKILLS) { + const hits = loaded.skills.filter((entry) => entry.name === skill); + const definition = loaded.definitions[skill]; + if (hits.length !== 1 || hits[0].provider !== PROVIDER) fail('skill-load', `${skill} not listed once from ${PROVIDER}`, { hits }); + if (!definition?.contentLength || definition.provider !== PROVIDER) fail('skill-load', `${skill} did not load`, { definition }); + if (!definition.path.includes(`${PACKAGE_NAME}${path.sep}skills${path.sep}${skill}${path.sep}`)) { + fail('skill-load', `${skill} loaded from outside the installed package`, { path: definition.path }); + } +} +const tutorResources = resourceDir(loaded.definitions['bloom-tutor']); +const references = ['articles.md', 'logging.md', 'summary.md', 'syllabus.md']; +const missingRefs = references.filter((file) => !fs.existsSync(path.join(tutorResources, 'references', file))); +if (missingRefs.length) fail('skill-load', 'bloom-tutor references are not reachable', { tutorResources, missingRefs }); +pass('skill-load', { + skills: SKILLS.map((skill) => ({ name: skill, contentLength: loaded.definitions[skill].contentLength })), + bloomTutorPath: loaded.definitions['bloom-tutor'].path, +}); + +// 6. A personal copy with the same name wins, and removing it brings the bundled one back. +const personal = path.join(agentsHome, 'skills', 'bloom-tutor'); +fs.mkdirSync(personal, { recursive: true }); +fs.writeFileSync(path.join(personal, 'SKILL.md'), '---\nname: bloom-tutor\ndescription: Personal copy used by the acceptance test.\n---\n\nPersonal copy.\n'); +const shadowed = (await probe('personal-copy-wins', ['bloom-tutor'])).definitions['bloom-tutor']; +if (!shadowed?.path?.startsWith(fs.realpathSync(agentsHome)) && !shadowed?.path?.startsWith(agentsHome)) { + fail('personal-copy-wins', 'the personal copy did not take precedence', { shadowed }); +} +fs.rmSync(personal, { recursive: true, force: true }); +const restored = (await probe('bundled-copy-restored', ['bloom-tutor'])).definitions['bloom-tutor']; +if (restored?.provider !== PROVIDER || restored.contentSha256 !== loaded.definitions['bloom-tutor'].contentSha256) { + fail('bundled-copy-restored', 'the bundled copy did not come back', { restored }); +} +pass('personal-copy-wins', { personalPath: shadowed.path }); +pass('bundled-copy-restored'); + +// 7. Uninstall removes the row and leaves a profile that still boots. +requireOk('plugin-remove', dsh(['plugin', '--profile', PROFILE, 'remove', PACKAGE_NAME]), 'dsh plugin remove'); +const after = dsh(['--profile', PROFILE, '--dump-config']); +requireOk('plugin-remove', after, 'dsh --dump-config after remove'); +if (after.stdout.includes(ROW_ID) || after.stdout.includes(PROVIDER)) { + fail('plugin-remove', 'our provider row is still composed after remove', { stdout: tail(after.stdout, 120) }); +} +const empty = await probe('base-profile-boots', SKILLS); +if (empty.skills.some((entry) => entry.provider === PROVIDER || SKILLS.includes(entry.name))) { + fail('base-profile-boots', 'skills are still visible after remove', { skills: empty.skills }); +} +pass('plugin-remove'); +pass('base-profile-boots'); + +process.stdout.write(`${JSON.stringify({ package: `${PACKAGE_NAME}@${manifest.version}`, dsh: DSH_VERSION, node: process.version, platform: `${process.platform}-${process.arch}`, steps }, null, 2)}\n`); +finish(0); diff --git a/integrations/deepseek-harness/scripts/pack.mjs b/integrations/deepseek-harness/scripts/pack.mjs new file mode 100644 index 0000000..3eb19d1 --- /dev/null +++ b/integrations/deepseek-harness/scripts/pack.mjs @@ -0,0 +1,94 @@ +#!/usr/bin/env node +// Build the bloomtutor-dsh npm tarball. +// +// The skills live once, in the repository's top-level skills/ directory. This +// script stages the adapter files plus a copy of those skills in a temporary +// directory and runs `npm pack` there, so the repository never holds a second +// copy that could drift. +// +// node integrations/deepseek-harness/scripts/pack.mjs # writes ./bloomtutor-dsh-.tgz next to package.json +// node integrations/deepseek-harness/scripts/pack.mjs --out /abs/path.tgz --json + +import { spawnSync } from 'node:child_process'; +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; + +export const integrationRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'); +export const repoRoot = path.resolve(integrationRoot, '..', '..'); +export const skillsRoot = path.join(repoRoot, 'skills'); + +const manifest = JSON.parse(fs.readFileSync(path.join(integrationRoot, 'package.json'), 'utf8')); + +// Every directory under skills/ that holds a SKILL.md ships in the package. +export function listSkillNames() { + return fs.readdirSync(skillsRoot, { withFileTypes: true }) + .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.')) + .filter((entry) => fs.existsSync(path.join(skillsRoot, entry.name, 'SKILL.md'))) + .map((entry) => entry.name) + .sort(); +} + +const skipHidden = (source) => !path.basename(source).startsWith('.'); + +function stage(destination) { + for (const file of ['package.json', 'cordis.patch.yml', 'icon.svg']) { + fs.copyFileSync(path.join(integrationRoot, file), path.join(destination, file)); + } + fs.copyFileSync(path.join(integrationRoot, 'PACKAGE_README.md'), path.join(destination, 'README.md')); + fs.copyFileSync(path.join(repoRoot, 'LICENSE'), path.join(destination, 'LICENSE')); + fs.cpSync(path.join(integrationRoot, 'locale'), path.join(destination, 'locale'), { recursive: true, filter: skipHidden }); + fs.cpSync(path.join(integrationRoot, 'docs'), path.join(destination, 'docs'), { recursive: true, filter: skipHidden }); + for (const name of listSkillNames()) { + fs.cpSync(path.join(skillsRoot, name), path.join(destination, 'skills', name), { recursive: true, filter: skipHidden }); + } +} + +function parsePackJson(stdout) { + const start = stdout.indexOf('['); + if (start === -1) throw new Error(`npm pack printed no JSON:\n${stdout}`); + const [entry] = JSON.parse(stdout.slice(start)); + if (!entry || !Array.isArray(entry.files)) throw new Error(`npm pack JSON has no file list:\n${stdout}`); + return entry; +} + +export function pack({ out } = {}) { + const work = fs.mkdtempSync(path.join(os.tmpdir(), 'bloomtutor-dsh-pack-')); + try { + const staged = path.join(work, 'package'); + fs.mkdirSync(staged); + stage(staged); + const result = spawnSync('npm', ['pack', '--json', '--ignore-scripts', '--pack-destination', work], { + cwd: staged, + encoding: 'utf8', + shell: process.platform === 'win32', + }); + if (result.status !== 0) { + throw new Error(`npm pack failed (${result.status}):\n${result.stderr || result.stdout || result.error?.message}`); + } + const entry = parsePackJson(result.stdout); + const destination = path.resolve(out || path.join(integrationRoot, entry.filename)); + fs.mkdirSync(path.dirname(destination), { recursive: true }); + fs.copyFileSync(path.join(work, entry.filename), destination); + return { + name: entry.name, + version: entry.version, + destination, + files: entry.files.map((file) => file.path).sort(), + }; + } finally { + fs.rmSync(work, { recursive: true, force: true }); + } +} + +if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { + const outIndex = process.argv.indexOf('--out'); + const out = outIndex === -1 ? undefined : process.argv[outIndex + 1]; + const packed = pack({ out }); + if (packed.name !== manifest.name || packed.version !== manifest.version) { + throw new Error(`packed ${packed.name}@${packed.version}, expected ${manifest.name}@${manifest.version}`); + } + if (process.argv.includes('--json')) process.stdout.write(`${JSON.stringify(packed, null, 2)}\n`); + else process.stdout.write(`${packed.destination}\n`); +} diff --git a/integrations/deepseek-harness/test/package.test.mjs b/integrations/deepseek-harness/test/package.test.mjs new file mode 100644 index 0000000..13feca4 --- /dev/null +++ b/integrations/deepseek-harness/test/package.test.mjs @@ -0,0 +1,128 @@ +// Contract tests for the bloomtutor-dsh package. No network, no DSH install: +// node --test integrations/deepseek-harness/test/*.test.mjs +// scripts/acceptance.mjs covers the real host. + +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; +import test from 'node:test'; + +import { integrationRoot, listSkillNames, pack, skillsRoot } from '../scripts/pack.mjs'; + +const read = (file) => fs.readFileSync(path.join(integrationRoot, file), 'utf8'); +const manifest = JSON.parse(read('package.json')); +const patch = read('cordis.patch.yml'); + +// DSH's skill catalog truncates descriptions past this many UTF-16 units (catalogDescriptionMaxLength). +const CATALOG_DESCRIPTION_MAX = 500; +const KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*$/; + +function frontmatter(text) { + const match = text.match(/^---\n([\s\S]*?)\n---\n/); + assert.ok(match, 'SKILL.md starts with a frontmatter block'); + const fields = {}; + for (const line of match[1].split('\n')) { + const field = line.match(/^([a-z-]+):\s*(.*)$/); + if (field) fields[field[1]] = field[2].trim(); + } + return fields; +} + +test('manifest declares a DSH bundle and nothing that runs on install', () => { + assert.equal(manifest.name, 'bloomtutor-dsh'); + assert.match(manifest.version, /^\d+\.\d+\.\d+$/); + assert.equal(manifest.type, 'module'); + assert.equal(manifest.license, 'MIT'); + assert.equal(manifest.private, undefined, 'a private package cannot be published'); + assert.deepEqual(manifest.dsh, { bundle: { patch: './cordis.patch.yml' } }); + assert.ok(manifest.keywords.includes('dsh-plugin')); + // The patch resolves /package.json; locale lookup needs the locale export. + assert.equal(manifest.exports['./package.json'], './package.json'); + assert.equal(manifest.exports['./locale/*.json'], './locale/*.json'); + for (const field of ['scripts', 'dependencies', 'peerDependencies', 'optionalDependencies', 'bin', 'main']) { + assert.equal(manifest[field], undefined, `${field} must stay empty`); + } +}); + +test('patch mounts one filesystem provider over the packaged skills', () => { + const rows = patch.match(/^\s+- id:/gm) || []; + assert.equal(rows.length, 1, 'exactly one inserted row'); + assert.match(patch, /^- insert:$/m); + assert.match(patch, /^\s+- id: bloomtutor-skill-filesystem$/m); + assert.match(patch, /^\s+name: '@deepseek-ai\/dsh-skill-filesystem'$/m); + assert.match(patch, /^\s+providerName: bloomtutor-plugin$/m); + assert.match(patch, /^\s+includeDefaultRoots: true$/m); + const expression = patch.match(/^\s+bundledSkillDir: !!js (.+)$/m)?.[1]; + assert.ok(expression, 'bundledSkillDir is a host-evaluated expression'); + assert.ok(expression.includes(`resolve('${manifest.name}/package.json')`), 'resolves this package from the profile baseUrl'); + assert.ok(expression.endsWith(", 'skills')")); + // The expression runs in the host process: only the path and module built-ins are allowed. + const builtins = [...expression.matchAll(/getBuiltinModule\('([^']+)'\)/g)].map((m) => m[1]); + assert.deepEqual([...new Set(builtins)].sort(), ['node:module', 'node:path']); + assert.doesNotMatch(expression, /require\(|import\(|fetch|child_process|process\.env|readFile|writeFile|spawn|exec/); +}); + +test('every skill loads under DSH naming and catalog rules', () => { + const names = listSkillNames(); + assert.ok(names.includes('bloom-tutor')); + assert.ok(names.length >= 7); + for (const name of names) { + assert.match(name, KEBAB, `${name} is kebab-case`); + const fields = frontmatter(fs.readFileSync(path.join(skillsRoot, name, 'SKILL.md'), 'utf8')); + assert.equal(fields.name, name, `${name}: frontmatter name matches its directory`); + assert.ok(fields.description, `${name}: has a description`); + assert.ok(fields.description.length <= CATALOG_DESCRIPTION_MAX, `${name}: description is ${fields.description.length} long`); + } +}); + +test('locale metadata and detail documents are complete', () => { + for (const [language, detail] of [['en', 'docs/DETAIL.md'], ['zh', 'docs/DETAIL.zh.md']]) { + const { meta } = JSON.parse(read(`locale/${language}.json`)); + assert.equal(meta.title, 'BloomTutor'); + assert.ok(meta.description?.trim(), `${language}: description`); + assert.match(meta.description, /[.。]$/, `${language}: description ends with punctuation`); + assert.equal(meta.detail, detail); + assert.ok(fs.existsSync(path.join(integrationRoot, detail)), `${detail} exists`); + } +}); + +test('icon is a small self-contained SVG', () => { + const icon = read('icon.svg'); + assert.equal(manifest.icon, './icon.svg'); + assert.ok(Buffer.byteLength(icon) < 256 * 1024); + assert.doesNotMatch(icon, / { + const out = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'bloomtutor-dsh-test-')), 'package.tgz'); + const packed = pack({ out }); + assert.equal(packed.name, manifest.name); + assert.equal(packed.version, manifest.version); + const skillFiles = []; + for (const name of listSkillNames()) { + const walk = (dir) => { + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + if (entry.name.startsWith('.')) continue; + const full = path.join(dir, entry.name); + if (entry.isDirectory()) walk(full); + else skillFiles.push(path.relative(path.join(skillsRoot, '..'), full).split(path.sep).join('/')); + } + }; + walk(path.join(skillsRoot, name)); + } + const expected = [ + 'LICENSE', + 'README.md', + 'cordis.patch.yml', + 'docs/DETAIL.md', + 'docs/DETAIL.zh.md', + 'icon.svg', + 'locale/en.json', + 'locale/zh.json', + 'package.json', + ...skillFiles, + ].sort(); + assert.deepEqual(packed.files, expected); + fs.rmSync(path.dirname(out), { recursive: true, force: true }); +}); diff --git a/integrations/deepseek-harness/test/probe-skills.mjs b/integrations/deepseek-harness/test/probe-skills.mjs new file mode 100644 index 0000000..a321309 --- /dev/null +++ b/integrations/deepseek-harness/test/probe-skills.mjs @@ -0,0 +1,52 @@ +// Test-only Cordis plugin for scripts/acceptance.mjs. It is never packaged. +// +// The acceptance script boots a real DSH profile with this module mounted as an +// extra patch row. It reads the host's Skill registry, loads every expected +// Skill in full, writes what it saw to BLOOMTUTOR_DSH_PROBE_OUT and exits. + +import { createHash } from 'node:crypto'; +import fs from 'node:fs'; +import path from 'node:path'; +import { setTimeout as delay } from 'node:timers/promises'; + +export const name = 'bloomtutor-dsh-skill-probe'; +export const inject = ['skills']; + +export async function probeSkills(skills, cwd, expectedNames, { timeoutMs = 30_000, pollMs = 100 } = {}) { + const deadline = Date.now() + timeoutMs; + let list = []; + // Providers finish their first scan asynchronously; poll until every expected name shows up. + for (;;) { + list = await skills.list({ cwd }); + if (expectedNames.every((skillName) => list.some((skill) => skill.name === skillName))) break; + if (Date.now() >= deadline) break; + await delay(pollMs); + } + const definitions = {}; + for (const skillName of expectedNames) { + const definition = await skills.get(skillName, { cwd }); + if (!definition) continue; + definitions[skillName] = { + name: definition.name, + provider: definition.provider, + path: definition.path, + resourceBase: definition.resourceBase, + contentLength: definition.content?.length || 0, + contentSha256: createHash('sha256').update(definition.content || '').digest('hex'), + }; + } + return { + skills: list.map((skill) => ({ name: skill.name, provider: skill.provider, path: skill.path })), + definitions, + }; +} + +export async function apply(ctx) { + const out = process.env.BLOOMTUTOR_DSH_PROBE_OUT; + if (!out) throw new Error('BLOOMTUTOR_DSH_PROBE_OUT is required'); + const expectedNames = JSON.parse(process.env.BLOOMTUTOR_DSH_PROBE_SKILLS || '[]'); + const cwd = process.env.BLOOMTUTOR_DSH_PROBE_CWD || process.cwd(); + const result = await probeSkills(ctx.skills, cwd, expectedNames); + fs.mkdirSync(path.dirname(out), { recursive: true }); + fs.writeFileSync(out, `${JSON.stringify(result, null, 2)}\n`); +}