Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
14 changes: 12 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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**.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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-*)
```
Expand Down
14 changes: 12 additions & 2 deletions README.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@

| 方式 | 配置 | 适合 |
|------|------|------|
| **CLI 模式** | Claude Code + 终端 | 喜欢用 Markdown 编辑器的人 |
| **CLI 模式** | Claude Code(或 DeepSeek Harness)+ 终端 | 喜欢用 Markdown 编辑器的人 |
| **Web 模式** | 浏览器(Next.js + FastAPI),自己部署 | 偏好可视化界面、想用自己的资料和 PDF 的人 |

两种模式遵循相同流程:**大纲 → 课文 → 批注 → 反馈 → 下一篇 → 评估 → 总结**。
Expand Down Expand Up @@ -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 模式
Expand Down Expand Up @@ -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 里用。

## 技术栈

Expand Down Expand Up @@ -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-*)
```
Expand Down
1 change: 1 addition & 0 deletions integrations/deepseek-harness/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
*.tgz
82 changes: 82 additions & 0 deletions integrations/deepseek-harness/PACKAGE_README.md
Original file line number Diff line number Diff line change
@@ -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 `<project>/.dsh/skills`, `<project>/.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
53 changes: 53 additions & 0 deletions integrations/deepseek-harness/README.md
Original file line number Diff line number Diff line change
@@ -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-<version>.tgz`.
4. Tag the commit `bloomtutor-dsh-v<version>`.

A published version never changes; ship fixes as a new version.
18 changes: 18 additions & 0 deletions integrations/deepseek-harness/cordis.patch.yml
Original file line number Diff line number Diff line change
@@ -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')
47 changes: 47 additions & 0 deletions integrations/deepseek-harness/docs/DETAIL.md
Original file line number Diff line number Diff line change
@@ -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).
47 changes: 47 additions & 0 deletions integrations/deepseek-harness/docs/DETAIL.zh.md
Original file line number Diff line number Diff line change
@@ -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) 自己部署。
9 changes: 9 additions & 0 deletions integrations/deepseek-harness/icon.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
7 changes: 7 additions & 0 deletions integrations/deepseek-harness/locale/en.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
7 changes: 7 additions & 0 deletions integrations/deepseek-harness/locale/zh.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"meta": {
"title": "BloomTutor",
"description": "基于 Bloom 2 Sigma 研究的 AI 私人导师:先给你出学习大纲,每次只讲一篇,下一篇按你的批注和反馈来调整。",
"detail": "docs/DETAIL.zh.md"
}
}
Loading
Loading