@lincyaw/dsh 0.1.0 → 0.2.0-rc.0

package/skills/presmium-author/SKILL.md

@@ -1,95 +0,0 @@
----
-name: presmium-author
-description: "帮助用户把内容写成可阅读、可演示的 Presmium 讲义，或修改现有 MyST 文稿、修复检查与构建问题、发布学生版和译本。Use when creating or editing a Presmium lecture, arranging narration and reveal steps, referencing or running code, or preparing document builds."
----
-
-# 编写与修改讲义
-
-从用户要讲清楚的内容出发，交付能阅读、能按预期演示的讲义。先弄清读者会看到什么、讲者需要怎样推进，再选择语法与插件。
-
-本仓库唯一公开示例是 `examples/cs336/` 的 17 讲完整课程。`pnpm demo:check` 检查全部内容和来源清单，`pnpm demo:build` 构建整个课程。Python 讲义将原 web server 的执行结果直接转换为 MyST Markdown，PPT 用内置步骤控制出现与替换，阅读文档按主题连续编排，不使用 trace plugin、专用播放器或源执行计数器。不能把 `text(...)`、`print(...)` 等源码调用当成结果；修改时验证变量、展示内容的前进与回退。没有可见变化的调用不生成空演示步骤。源码、转换说明、Original content 等元信息不进入讲义展示，来源与校验仅在维护文件中保存。PDF 的 PPT 保留全部 496 页，阅读文档使用提取文字与独立图表。`pnpm studio` 默认准备并复用独立副本 `.presmium/cs336-workspace`。
-
-## 找到这次任务的入口
-
-| 用户想做什么 | 先确认什么 | 按需阅读 |
-|---|---|---|
-| 从材料写一份讲义 | 面向谁、读完能理解或完成什么、需要哪些交付形式 | [组织内容与演示步骤](references/writing.md) |
-| 修改现有讲义 | 相关章节、已有写法、这次要改变的阅读或演示效果 | [组织内容与演示步骤](references/writing.md) |
-| 引用代码、让读者动手运行 | 代码来自哪里、何时运行、是否共享变量 | [代码引用与执行](references/code.md) |
-| 给学生发布、增加译本、组成课程站点 | 公开哪些内容、发布哪些语言、最终访问地址 | [发布与复现](references/publishing.md) |
-| 检查报错、构建失败、显示与预期不同 | 首条相关诊断及其位置、出问题的形态 | 下文“修复问题”；语法查 [指令参考](references/directives.md) |
-| 在浏览器中编辑、请 agent 改文稿 | 文稿或工作区目录、要改的范围 | 下文“选择编辑方式” |
-| 让外部 agent 读取文稿、给读者加 AI 问答 | 是作者编辑，还是读者阅读时提问 | [编辑与问答](references/assistance.md) |
-
-只读取当前任务需要的参考。指令参考回答“怎么写”，本技能负责“该选什么、做到什么程度”。
-
-## 先接上现有文稿
-
-修改前读入口 `lecture.md` 的头部、相关章节与它引入的文件；沿用已有的语言、插件、标签和排版方式。文稿也可以使用其他入口文件名，命令接受目录或入口文件。
-
-从材料和现有内容推断受众、目标与交付形式。确实会改变内容取舍却无法推断的信息再询问；不要把配置选项变成问卷。
-
-新项目需要 Node.js 22.19 以上与 pnpm。安装 `pnpm add -g presmium` 后：
-
-```sh
-presmium new my-lecture --type lecture --title 分词入门
-cd my-lecture
-presmium dev --to web
-```
-
-多份文档组成课程时用 `presmium new my-course --type workspace`。项目中安装依赖用 `pnpm install`；全局 `presmium` 会转交给项目安装的版本。面向使用者的命令用 pnpm 与 `presmium`。
-
-## 写作与验证一起进行
-
-围绕读者的问题组织章节。讲解补足推理、前提和例子；投影内容保留当前一步需要看的证据。普通段落默认成为幻灯片的演讲备注，想投到屏幕上的文字放进 `{slide}`。两者都在网页中出现。
-
-需要分步揭示时，按讲者的推进顺序安排上屏内容与后续讲解。给会被链接、课堂笔记或讲授回放引用的章节与块写显式标签；自动生成的块 ID 会随插入内容变化。
-
-文档按主题连续阅读，不把每次输出或投影片分页变成重复标题。CS336 示例的 `lecture.md` 是文档与 notebook 的入口，`slides.md` 单独编排 PPT，保留全部原生演示步骤；课程构建命令会分别处理两个入口。PDF 文档使用文字与独立图表，完整原页用于 PPT。
-
-在文稿目录运行 `presmium check`，修复与本次内容有关的诊断。用 `presmium dev --to web` 看阅读效果；需要幻灯片时也预览幻灯片，检查文字是否上屏、字号与溢出、前进和后退时的步骤。步数或备注归属不明确时才用 `presmium ir` 核对块的 `at`、`span` 与章节的 `steps`。
-
-按约定的交付形式构建，例如 `presmium build --to web,slides`。查看报告中未渲染或降级的内容；构建成功后仍要确认用户需要的内容出现在产物中。图片、链接、运行结果和交互组件都是正文的一部分。
-
-## 修复问题
-
-先复现用户使用的命令和形态，再沿诊断中的文件与行定位源码。优先修复造成后续错误的第一处原因。
-
-| 现象 | 下一步 |
-|---|---|
-| `unknown directive`、`unknown option` | 查 [指令参考](references/directives.md) 的写法与提供插件，确认头部 `plugins` 已列出它 |
-| 幻灯片少了文字、备注与步骤对不上 | 查 [组织内容与演示步骤](references/writing.md)，核对讲解与上屏内容的角色 |
-| 代码锚点丢失、路径不对、输出没更新 | 查 [代码引用与执行](references/code.md)，核对仓库根路径、锁定版本与缓存 |
-| 链接、学生版或译本检查失败 | 查 [发布与复现](references/publishing.md)，核对交付目录与对应版本 |
-
-不要用隐藏内容、关闭检查或删除缓存来代替定位问题。确认代码引用的新位置后才更新锚点锁；确认译文跟上原文后才更新译本摘要。
-
-## 选择编辑方式
-
-在 VS Code 中编辑时，从 GitHub Release 下载对应系统与处理器的 `.vsix`，用“Extensions: Install from VSIX…”安装。打开讲义后执行“Presmium: Open Preview to the Side”，保存后更新、按光标所在章节定位；需要 Node.js 22.19 以上与文稿自己的插件依赖，不需要工作台或模型。安装与平台选择见 [扩展说明](../../../packages/vscode/README.md)。
-
-用户已有编辑器时直接修改源码。想在浏览器中编辑时，另装 `pnpm add -g @lincyaw/studio`，用 `presmium-studio <目录>` 打开工作台；项目内安装则用 `pnpm add -D @lincyaw/studio` 和 `pnpm exec presmium studio <目录>`。打开终端打印的完整网址，`Ctrl+C` 停止。不配置模型也能编辑、保存与预览。
-
-工作台打开文稿先显示预览，顶部可切换“源码”“并排”；右侧对话可收起再打开。选中源码或预览中的文字、点选预览块后，顶部显示同步给 agent 的关注内容；切到聊天输入框后仍保留，可手动清除。并排或源码视图中点选预览块也会定位源码。agent 改动接受后成为可撤销的 git 提交；同一文档正在审阅时留意锁定与外部编辑冲突。
-
-有未保存的修改时，关闭文件或离开文稿会让作者选择保存、放弃或取消；保存失败时保留编辑内容，先处理错误或冲突再离开。刷新或关闭浏览器页面也会提示未保存的修改。
-
-文件树以启动的工作区根目录显示文件，包含讲义目录外引用的 Python、TypeScript 等代码。对话记录中的文件名、代码行引用与文件列表共用中央源码编辑器；重复打开同一文件会复用标签并保留草稿。打开代码或根目录笔记时保留当前讲义预览，均可编辑保存；图片、PDF 与表格沿用专用预览。
-
-在对话栏顶部点“新建对话”开始新的讨论，旁边的“历史对话”打开已有会话。新建对话不需要先切到左侧，也不会关闭当前文稿或丢弃编辑草稿。
-
-活动栏只有一个“历史对话”入口，兼顾历史列表与聊天恢复。选择历史会话会直接显示聊天，包括收起后重新选择当前会话；不用再点另一个聊天按钮。聊天可从顶部收起，未发送的内容保留。
-
-插件和自动化任务从活动栏底部打开，与设置同列；再次点击当前工具可回到文稿，编辑草稿会保留。
-
-活动栏的“修改”展示待审阅文件、未提交修改与提交历史，支持查看差异、接受、撤回、恢复检查点，以及提交、放弃和撤销。审阅与未保存编辑的保护共同生效。
-
-窗口较窄时，打开历史或文件会收起对话，避免遮住文稿；从活动栏切回对话即可，草稿会保留。辅助面板也可以全屏查看，退出后回到分栏。
-
-`presmium dev` 预览一份文稿；`presmium serve` 预览工作区；两者提供完整文稿。给学生分享时显式构建学生版，见 [发布与复现](references/publishing.md)。
-
-## 交付给用户
-
-说明内容改在何处、怎样预览或打开产物、哪些检查实际完成，以及仍影响使用的限制。需要用户接手时给出可执行的下一步。
-
-现场放映、课堂、离线准备、PDF 与讲授回放使用 `presmium-present`；只有现有语法确实不能满足任务、需要开发组件或插件时才使用 `presmium-develop`。

package/skills/presmium-author/references/assistance.md

@@ -1,27 +0,0 @@
-# 编辑与问答
-
-先区分请求者是谁：作者让 agent 修改源码，和读者对讲义提问，使用不同的入口与模型配置。
-
-## 作者在工作台中修改
-
-用作者技能中的工作台启动方式打开文稿。不配置模型也能手工编辑与预览；要对话时在工作台的模型设置里选择已有服务，按用户选择填写地址、密钥与模型。
-
-先定位相关章节或在预览中点选块，再说明希望改变的内容。agent 修改后检查源码差异与预览，接受成为 git 提交，拒绝恢复对应文件。不要把“对话完成”当作作者已经接受修改。
-
-## 继续使用用户自己的编辑器或 agent
-
-直接编辑 MyST 源码即可，开发服务器会更新预览。需要 agent 查询讲义结构、诊断与当前位置时，再连接 Presmium 的 MCP。
-
-运行 `presmium dev` 或 `presmium serve` 后，终端打印 MCP 地址和令牌所在的状态文件。按用户所用客户端的配置方式连接 HTTP 端点，请求头为 `Authorization: Bearer <令牌>`。从状态文件读取本次进程的令牌，不把它写进文稿或分享地址。
-
-不需要预览服务时，安装 `pnpm add -g @lincyaw/mcp`，用 `presmium-mcp <文稿目录>` 作为 stdio 服务。默认提供读取能力；需要其他操作时查看命令帮助并按任务配置。
-
-连接后发现服务实际提供的工具，再查询章节、步骤、代码和诊断。MCP 本身不提供通用文件写入，agent 仍用自己的文件工具修改源码。操作可能需要在页面中确认，按实际提示处理。
-
-## 给读者加提问入口
-
-文稿列出 `@lincyaw/slidev-addon-assistant`，构建的静态站点也能提问。每位读者在“提问”中填写自己的 OpenAI 兼容服务地址、密钥与模型，问题和相关讲义内容从其浏览器直接发送，费用由该读者的服务承担。
-
-模型配置保存在该站点的浏览器存储，同源脚本可以读取。不要把作者的密钥预填进发布产物，也不要把工作台的模型配置误当成读者共享的模型。学生版产物只包含学生内容，问答也从这份内容取上下文。
-
-验证时选择相关文字发问，检查引用能否回到对应章节。课堂中主讲为问题生成的 AI 回答先留在主讲窗口，点“发给课堂”后才分享，课堂流程见 `presmium-present`。

package/skills/presmium-author/references/code.md

@@ -1,52 +0,0 @@
-# 代码引用与执行
-
-先问清读者需要看什么：真实仓库中的某段代码、构建时的固定结果，还是可以修改后运行的示例。沿用文稿已有的环境配置，不为简单例子引入额外后端。
-
-## 引用真实代码
-
-列出 `@lincyaw/slidev-addon-code`，用 `{code-ref}`。锚点路径从文稿所在 git 仓库的根目录写起；不在 git 中时才从文稿目录写起。
-
-- 有人工标记的区域用 `region:src/bpe.py#merge`。
-- 引用声明用 `symbol:src/bpe.py#Tokenizer.encode`。
-- 需要固定讲解版本时用 `:pin: <提交>`，否则读取工作区代码。
-
-完整写法、分步高亮与多版本比较见 [指令参考](directives.md) 的 `{code-ref}`。引用的提交也必须在这个仓库中。
-
-锚点“丢失”时先查文件与区域；“模糊”时检查候选是否正确。确认后用 `presmium check --update-lock` 更新锁文件。锁定版本与工作区发生漂移时，先读差异，再决定更新 `:pin:` 还是保留旧版。
-
-## 选择执行时机
-
-列出 `@lincyaw/slidev-addon-exec`。代码块加 `:run: compile` 在编译时运行，`:run: live` 由读者点击运行，`:run: both` 两者都要；单独写 `:run:` 是编译时运行。
-
-````md
-```{code} python
-:run: both
-print(sum([1, 2, 3]))
-```
-````
-
-网页给现场代码显示运行按钮；幻灯片中的 Python、JavaScript、TypeScript 使用 Monaco Runner。执行面板适合带参数的例子，分步执行适合解释运行过程，写法查 [指令参考](directives.md)。
-
-浏览器 Python 使用 Pyodide，现有内置运行环境只有标准库；依赖 numpy、matplotlib 等的例子优先用编译时输出，或选择合适的远端环境。C、C++、Ruby、SQL 可用 `@lincyaw/slidev-addon-exec-wasi`，其运行时会增加发布体积。GPU 和远端内核只在任务需要时配置。
-
-## 让前后代码共享变量
-
-需要“先训练、再编码”时，为相关块写相同的 `:session:`。这些块必须使用同一执行环境；前面的块改动会使后续会话录制重新生成。浏览器中需按顺序运行，“重置会话”清空解释器状态。
-
-不共享状态的例子不加会话。一次运行写的文件不应被当作下一次独立运行的前提。
-
-## 使用具名环境
-
-头部 `execute.environments` 声明环境，代码用 `:env: <名字>` 选择；`execute.env` 可指定默认环境。选择了环境却不可用时不自动换执行器，有录制就显示录制。
-
-环境的配置、提供插件与示例见 [指令参考](directives.md) 的 `{local-env}`、`{terminal}` 与代码指令。凭据放环境变量，例如 `PRESMIUM_ENV_<名>_TOKEN`，不写进文稿。用 `presmium check --env` 验证实际连接。
-
-## 输出不对时检查什么
-
-编译会发生在 `check`、`ir`、`build`、`dev` 中，可能执行代码并更新 `.presmium/freeze/`。代码没变时沿用录制；没有运行环境时也能用已有录制。默认沿用其他环境的录制并警告，确实需要重跑时才设 `execute: { rerun: environment }`。
-
-先区分“旧录制”“执行失败”“环境不可用”。检查代码、参数、会话顺序和诊断；不要先删除缓存。超时优先改例子，必要时用 `:timeout:` 调整。
-
-富输出可显示图、表等内容；`:echo: false` 只显示输出。组件拥有的代码由组件运行，不再附加一套运行控件。执行面板失败时可显示 `:recorded:` 的预录输出。
-
-交付前检查目标媒介里的结果，确认未把本机路径、环境变量或教师内容写进输出。复现所需的录制文件见 [发布与复现](publishing.md)。