dsh-courseware

Readme

# dsh-courseware

把 DeepSeek Harness 的 **courseware 技能**（中小学课件生成）及其 **pptxgen 引擎**
打包成官方可安装的 DSH 插件包：`dsh plugin --profile <名字> add <本包>`。

安装后，profile 里每个 agent 的技能目录都会出现 `courseware` 技能：
拿用户自己的 `.pptx` 模板 + 一份课程大纲（教案/文档/纯文本），产出套用该模板
背景、配色、字体、页面骨架的课件 `.pptx`。

## 包内结构

```
dsh-courseware/
├── package.json          type:module + main:lib/index.js + dsh.bundle.patch（命门）
├── cordis.patch.yml      把本包插成一行，loader 才会加载它
├── lib/index.js          零依赖提供器：扫描 skills/ 注册进 ctx.skills
├── skills/courseware/    SKILL.md + workflows/ + references/
└── engine/               pptxgen 引擎源码 + pptxgen.sh + requirements.txt
```

## 安装

前置：已装 DeepSeek Harness + pnpm（`dsh plugin` 内部调用 pnpm）。

```sh
# 本地文件夹（pnpm 链接安装，改完重启 profile 即生效，适合开发）
dsh plugin --profile web add /路径/到/dsh-courseware

# 发布到 npm 后（推荐）
dsh plugin --profile web add dsh-courseware

# 或 GitHub / tarball
dsh plugin --profile web add https://github.com/你的账号/dsh-courseware.git
dsh plugin --profile web add /路径/to/dsh-courseware-0.1.0.tgz
```

安装后**重启 profile**（停掉重跑 `dsh web`，刷新浏览器），然后验证：

```sh
dsh --profile web --dump-config     # 输出里应出现 dsh-courseware 行
```

agent 的技能目录里应出现 `courseware`，可用 `skill` 工具加载。

卸载：

```sh
dsh plugin --profile web remove dsh-courseware
```

> 必须用 `dsh plugin` 形式安装。直接 `npm install` 只会把包当普通库装进当前
> 目录，不会注册进任何 profile，技能永远不会被加载。

## 首次使用：初始化引擎（一次性）

引擎需要 Python 3.10+，首次跑课件前初始化虚拟环境：

```sh
python3 -m venv "<引擎目录>/.venv"
"<引擎目录>/.venv/bin/pip" install -r "<引擎目录>/requirements.txt"
```

引擎目录 = 技能目录的上两级（agent 会自行按此规则定位）；也可用环境变量
`PPTXGEN_ENGINE_HOME` 指向自备引擎。

另外，`check --render` 与 `preview` 需要本机装有 LibreOffice（macOS：
`/Applications/LibreOffice.app`）；仅 `build` 不依赖它。模板用到的字体
（如 华文琥珀/微软雅黑）在目标机器上缺失时，字号会退化，建议装齐常用中文字体。

## 图片后端配置 —— 本包不含任何密钥

**包里没有任何 API key、也没有任何密钥配置**（引擎源码只有占位符；`~/.pptxgen/config.yaml`
在用户侧，不在包内）。每个使用者装好后自己配：

方式一：环境变量

```sh
export PPTXGEN_IMAGE_BASE_URL="https://你的服务商/v1"
export PPTXGEN_IMAGE_MODEL="你的模型名"
export PPTXGEN_IMAGE_API_KEY="你自己的 key"
```

方式二：用户配置文件 `~/.pptxgen/config.yaml`

```yaml
images:
  base_url: https://你的服务商/v1
  model: 你的模型名
  api_key: 你自己的 key
```

引擎的图片配置优先级：环境变量 > 课件 `options.images` > 用户配置文件。
生成配图时 agent 会先检查后端是否配好；没配就停下来提示你去配（不静默跳过）。

## 发布到 npm 的注意

- `package.json` 的 `files` 白名单已排除 `.venv/`、`__pycache__/`、`.git/` 等；
  发布前再跑一遍 `npm pack --dry-run` 确认包内**没有**任何密钥文件。
- 发布前先在干净的 profile 上本地安装验证一遍（上面"安装"节）。
- 包名 `dsh-courseware` 如与 npm 已有包冲突，可改成带 scope 的
  `@你的账号/dsh-courseware`（改 package.json 的 `name` 与 cordis.patch.yml 的
  `name` 两处即可）。
- 技能内容更新：改 `skills/courseware/` 后重新发布即可，无需改代码
  （提供器自动发现新技能/新文件）。
- 引擎更新：替换 `engine/pptxgen/` 内容后重新发布。

## License

MIT。技能内容与引擎源码版权归原作者。