dsh-courseware 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Liang Yu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# 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。技能内容与引擎源码版权归原作者。

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# dsh-courseware bundle patch: 把 courseware 技能提供器挂进 host 层技能注册表，
+# 使 profile 里每个 agent preset 的作用域链都能合并它注册的技能。
+#
+# 本补丁叠加在 dsh-base 层之上；后面的层（profile 自己的 cordis.patch.yml、
+# --patch 叠加）仍可按 id 定位这一行。技能正文在包内 skills/ 目录随包分发，
+# 提供器用 import.meta.url 定位，无需任何用户配置。
+- insert:
+    - id: dsh-courseware
+      name: 'dsh-courseware'

package/engine/pptxgen/__init__.py

@@ -0,0 +1,8 @@
+"""pptxgen —— 基于自有模板的中小学课件 PPTX 生成器。"""
+
+__version__ = "0.1.0"
+
+from .spec import SpecError, load_deck, normalize_deck  # noqa: F401
+from .template import load_template  # noqa: F401
+
+__all__ = ["load_deck", "load_template", "normalize_deck", "SpecError", "__version__"]

package/engine/pptxgen/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/engine/pptxgen/builtin_template.py

@@ -0,0 +1,218 @@
+"""内置兜底模板：没有提供模板文件时，生成一份干净的 16:9 课件模板。"""
+
+from __future__ import annotations
+
+import copy
+from typing import Dict, Optional
+
+from pptx import Presentation
+from pptx.enum.shapes import MSO_SHAPE
+from pptx.oxml.ns import qn
+from pptx.util import Emu, Inches, Pt
+
+from .util import emu_from_inch, parse_color
+
+DEFAULT_PALETTE: Dict[str, str] = {
+    "dk1": "1F2937",
+    "lt1": "FFFFFF",
+    "dk2": "5B6675",
+    "lt2": "EEF2F7",
+    "accent1": "2F6FED",
+    "accent2": "F08C00",
+    "accent3": "2F9E44",
+    "accent4": "7048E8",
+    "accent5": "0C8599",
+    "accent6": "E8590C",
+    "hlink": "2F6FED",
+    "folHlink": "7048E8",
+}
+
+DEFAULT_MAJOR_FONT = "微软雅黑"
+DEFAULT_MINOR_FONT = "微软雅黑"
+
+
+def build_builtin_template(path: str, *, palette: Optional[Dict[str, str]] = None,
+                           font: Optional[str] = None, theme_name: str = "DSH 课件模板",
+                           size: str = "16:9") -> str:
+    prs = Presentation()
+    base_w = prs.slide_width
+    if size == "4:3":
+        # python-pptx 默认模板本身就是 4:3，无需缩放
+        pass
+    else:
+        prs.slide_width = Emu(12192000)      # 13.333in
+        prs.slide_height = Emu(6858000)      # 7.5in
+
+    pal = dict(DEFAULT_PALETTE)
+    if palette:
+        pal.update({k: parse_color(v) or v for k, v in palette.items()})
+    font = font or DEFAULT_MINOR_FONT
+
+    _patch_theme(prs, pal, font, theme_name)
+    if size != "4:3":
+        # 默认模板是 4:3 的版式，把占位符横向拉伸到目标比例
+        _rescale_horizontally(prs, prs.slide_width / float(base_w))
+    _patch_master(prs, pal)
+    title_pt = 36 if size != "4:3" else 32
+    body_pt = (20, 17, 15, 14, 13) if size != "4:3" else (24, 20, 18, 16, 14)
+    _set_txstyles(prs, title_pt=title_pt, body_pt=body_pt)
+    _rename_layouts(prs)
+    prs.save(path)
+    return path
+
+
+# 把 Office 默认版式改成中文语义名，让页型->版式映射天然精确
+LAYOUT_NAMES = [
+    "封面", "标题和内容", "节标题", "两栏内容", "比较",
+    "仅标题", "空白", "内容与标题", "图片与标题", "标题和竖排文字", "竖排标题与文本",
+]
+
+
+def _rename_layouts(prs) -> None:
+    for i, lay in enumerate(prs.slide_layouts):
+        if i < len(LAYOUT_NAMES):
+            try:
+                lay.name = LAYOUT_NAMES[i]
+            except Exception:
+                pass
+
+
+def _set_txstyles(prs, title_pt: float, body_pt) -> None:
+    """重设母版文字样式的字号，使其符合 16:9 课件的可读性。"""
+    txStyles = prs.slide_master._element.find(qn("p:txStyles"))
+    if txStyles is None:
+        return
+
+    def set_levels(style_tag: str, sizes) -> None:
+        node = txStyles.find(qn(style_tag))
+        if node is None:
+            return
+        for i, size in enumerate(sizes, start=1):
+            lvl = node.find(qn(f"a:lvl{i}pPr"))
+            if lvl is None:
+                continue
+            d = lvl.find(qn("a:defRPr"))
+            if d is None:
+                d = lvl.makeelement(qn("a:defRPr"), {})
+                lvl.append(d)
+            d.set("sz", str(int(size * 100)))
+
+    set_levels("p:titleStyle", [title_pt])
+    set_levels("p:bodyStyle", list(body_pt))
+    set_levels("p:otherStyle", [title_pt if False else body_pt[0]])
+
+
+def _rescale_horizontally(prs, factor: float) -> None:
+    """把母版与所有版式里形状的 x / cx 按比例缩放（保持 y / cy 不变）。"""
+    from pptx.oxml.ns import qn as _qn
+
+    roots = [prs.slide_master._element]
+    roots += [lay._element for lay in prs.slide_layouts]
+    for root in roots:
+        for xfrm in root.iter(_qn("a:xfrm")):
+            off = xfrm.find(_qn("a:off"))
+            ext = xfrm.find(_qn("a:ext"))
+            if off is not None and off.get("x"):
+                off.set("x", str(int(int(off.get("x")) * factor)))
+            if ext is not None and ext.get("cx"):
+                ext.set("cx", str(int(int(ext.get("cx")) * factor)))
+
+
+# --------------------------------------------------------------------------
+def _theme_root(prs):
+    """python-pptx 把 theme 当作不透明 Part，需要用 blob 读写。"""
+    from lxml import etree
+    from pptx.opc.constants import RELATIONSHIP_TYPE as RT
+
+    part = prs.slide_master.part.part_related_by(RT.THEME)
+    root = getattr(part, "_element", None)
+    if root is None:
+        root = etree.fromstring(part.blob)
+    return part, root
+
+
+def _save_theme(part, root) -> None:
+    from lxml import etree
+
+    part._blob = etree.tostring(root, xml_declaration=True, encoding="UTF-8", standalone=True)
+
+
+def _patch_theme(prs, pal: Dict[str, str], font: str, theme_name: str) -> None:
+    part, root = _theme_root(prs)
+    clrScheme = root.find(f".//{qn('a:clrScheme')}")
+    if clrScheme is not None:
+        clrScheme.set("name", theme_name)
+        for child in list(clrScheme):
+            key = child.tag.split("}")[-1]
+            color = pal.get(key)
+            if not color:
+                continue
+            for sub in list(child):
+                child.remove(sub)
+            srgb = child.makeelement(qn("a:srgbClr"), {"val": color})
+            child.append(srgb)
+
+    fontScheme = root.find(f".//{qn('a:fontScheme')}")
+    if fontScheme is not None:
+        fontScheme.set("name", theme_name)
+        for which in ("majorFont", "minorFont"):
+            node = fontScheme.find(qn(f"a:{which}"))
+            if node is None:
+                continue
+            for tag in ("a:latin", "a:ea", "a:cs"):
+                el = node.find(qn(tag))
+                if el is None:
+                    el = node.makeelement(qn(tag), {})
+                    node.append(el)
+                el.set("typeface", font)
+
+    _save_theme(part, root)
+
+
+def _patch_master(prs, pal: Dict[str, str]) -> None:
+    master = prs.slide_master
+    W, H = prs.slide_width, prs.slide_height
+
+    # 纯白背景，保证任何版式下文字都清晰
+    cSld = master._element.find(qn("p:cSld"))
+    if cSld is not None:
+        old = cSld.find(qn("p:bg"))
+        if old is not None:
+            cSld.remove(old)
+        bg = cSld.makeelement(qn("p:bg"), {})
+        bgPr = bg.makeelement(qn("p:bgPr"), {})
+        solid = bgPr.makeelement(qn("a:solidFill"), {})
+        solid.append(solid.makeelement(qn("a:srgbClr"), {"val": "FFFFFF"}))
+        bgPr.append(solid)
+        bgPr.append(bgPr.makeelement(qn("a:effectLst"), {}))
+        bg.append(bgPr)
+        cSld.insert(0, bg)
+
+    spTree = master.shapes._spTree
+    accent = pal.get("accent1", "2F6FED")
+    accent2 = pal.get("accent2", "F08C00")
+
+    # 底部细色条（母版装饰，所有版式/幻灯片自动继承）
+    bar_h = max(int(H * 0.012), 9144)
+    spTree.append(_rect_sp(0, int(H) - bar_h, int(W * 0.62), bar_h, accent, 900, "__builtin_bar1"))
+    spTree.append(_rect_sp(int(W * 0.62), int(H) - bar_h, int(W * 0.38), bar_h, accent2, 901, "__builtin_bar2"))
+
+
+def _rect_sp(x: int, y: int, cx: int, cy: int, color: str, shape_id: int, name: str):
+    """构造一个无描边的纯色矩形 <p:sp>（用于母版装饰）。"""
+    from pptx.oxml import parse_xml
+    from pptx.oxml.ns import nsdecls
+
+    xml = (
+        f'<p:sp {nsdecls("p", "a")}>'
+        f'<p:nvSpPr><p:cNvPr id="{shape_id}" name="{name}"/><p:cNvSpPr/><p:nvPr/></p:nvSpPr>'
+        f'<p:spPr>'
+        f'<a:xfrm><a:off x="{int(x)}" y="{int(y)}"/><a:ext cx="{int(cx)}" cy="{int(cy)}"/></a:xfrm>'
+        f'<a:prstGeom prst="rect"><a:avLst/></a:prstGeom>'
+        f'<a:solidFill><a:srgbClr val="{parse_color(color)}"/></a:solidFill>'
+        f'<a:ln><a:noFill/></a:ln>'
+        f'</p:spPr>'
+        f'<p:txBody><a:bodyPr/><a:lstStyle/><a:p/></p:txBody>'
+        f'</p:sp>'
+    )
+    return parse_xml(xml)