@capyclaw/ppt-skill-editing 0.0.0-stage → 2.2.1

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# @capyclaw/ppt-skill-editing（目录 dsh-ppt-skill-editing） bundle patch：只注册 pptist-editing 一个 skill provider。
+- insert:
+    - id: ppt-skill-editing
+      name: @capyclaw/ppt-skill-editing

package/lib/index.mjs

@@ -0,0 +1,23 @@
+/** @capyclaw/ppt-skill-editing（目录 dsh-ppt-skill-editing）：单 skill provider。 */
+import { fileURLToPath } from 'node:url'
+import { createSkillProvider } from './provider.mjs'
+
+export const name = 'ppt-skill-editing'
+export const inject = ['skills']
+const SKILL = "pptist-editing"
+
+function defaultProvider(config = {}) {
+  return createSkillProvider({
+    assetRoot: config.assetRoot ?? fileURLToPath(new URL('../skills/', import.meta.url)),
+    contractRoot: config.contractRoot ?? fileURLToPath(new URL('../contract/', import.meta.url)),
+    contractFile: 'ppt-contract.json',
+    providerName: "dsh-ppt-editing",
+    skillDirs: [SKILL],
+    contractNote: (version, skillName) => (String(skillName || '').startsWith('pptmaster-')
+      ? ''
+      : '契约：PPTist Workbench ' + version + '。动作前先调用 ppt_capabilities；工具缺失或 major 不一致时停止，并提示用户安装/升级 @capyclaw/ppt-suite。'),
+  })
+}
+
+export function createProvider(config = {}) { return defaultProvider(config) }
+export function apply(ctx, config = {}) { ctx.skills.registerProvider(() => defaultProvider(config)) }

package/lib/provider.mjs

@@ -0,0 +1,82 @@
+/** 通用 skill provider：从目录扫描 kebab-case SKILL.md，按需加载正文。 */
+import { readFileSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { isAbsolute, join, sep } from 'node:path'
+
+const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+const RANK = 600
+
+function parseSkill(raw, path) {
+  const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u.exec(raw)
+  if (!frontmatter?.[1]) throw new Error(`skill ${path} 缺少 YAML frontmatter`)
+  const meta = {}
+  for (const line of frontmatter[1].split(/\r?\n/)) {
+    const match = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line)
+    if (match) meta[match[1]] = match[2].replace(/^['"]|['"]$/g, '').trim()
+  }
+  if (!meta.name || !meta.description) throw new Error(`skill ${path} 缺少 name/description`)
+  if (!NAME_RE.test(meta.name)) throw new Error(`skill ${path} name 必须是 kebab-case`)
+  return {
+    name: meta.name,
+    description: meta.description,
+    whenToUse: meta.whenToUse || undefined,
+    content: raw.slice(frontmatter[0].length).trim(),
+  }
+}
+
+/**
+ * @param {{
+ *   assetRoot: string,
+ *   skillDirs: string[],
+ *   providerName?: string,
+ *   contractRoot?: string,
+ *   contractNote?: (version: string) => string
+ * }} config
+ */
+export function createSkillProvider(config) {
+  const assetRoot = config.assetRoot
+  if (!assetRoot || !isAbsolute(assetRoot)) throw new Error('createSkillProvider: assetRoot 必须是绝对路径')
+  let contract = null
+  if (config.contractRoot) {
+    try {
+      contract = JSON.parse(readFileSync(join(config.contractRoot, config.contractFile || 'contract.json'), 'utf8'))
+    } catch { /* 非技能包可以没有契约快照 */ }
+  }
+  const dirs = config.skillDirs || []
+  if (!dirs.length) throw new Error('createSkillProvider: skillDirs 不能为空')
+  const candidates = dirs.map((dir) => {
+    const directory = join(assetRoot, dir)
+    const locator = join(directory, 'SKILL.md')
+    const parsed = parseSkill(readFileSync(locator, 'utf8'), locator)
+    if (parsed.name !== dir) throw new Error(`skill ${locator} name 必须是 ${dir}`)
+    return {
+      name: parsed.name,
+      description: parsed.description,
+      whenToUse: parsed.whenToUse,
+      invocation: { modelInvocable: true, userInvocable: true },
+      provider: config.providerName || 'dsh-plugin',
+      source: 'bundled',
+      rank: RANK,
+      resourceBase: { kind: 'directory', path: directory.split(sep).join('/') },
+      locator,
+    }
+  })
+  const byName = new Map(candidates.map((candidate) => [candidate.name, candidate]))
+  const noteFor = (name) => (contract && config.contractNote
+    ? config.contractNote(contract.contractVersion, name)
+    : '')
+
+  return {
+    name: config.providerName || 'dsh-plugin',
+    list: () => Promise.resolve(candidates),
+    async get(candidate, options = {}) {
+      const hit = byName.get(candidate.name)
+      if (!hit) throw new Error(`未知 skill ${candidate.name}`)
+      const raw = await readFile(hit.locator, { encoding: 'utf8', signal: options.signal })
+      const parsed = parseSkill(raw, hit.locator)
+      const { rank: _rank, locator: _locator, ...summary } = hit
+      const note = noteFor(candidate.name)
+      return { ...summary, content: parsed.content + (note ? `\n\n---\n\n${note}` : '') }
+    },
+  }
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@capyclaw/ppt-skill-editing",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.2.1",
+  "description": "PPT skill：指哪打哪的修改执行器：每步落盘、不审美、不审计、不回头验证。",
+  "type": "module",
+  "main": "./lib/index.mjs",
+  "exports": {
+    ".": "./lib/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18",
+    "dsh": "^0.2.0-rc.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "category": "skills",
+    "platform": "both"
+  },
+  "meta": {
+    "title": "PPT Skill · PPT 纯执行",
+    "description": "指哪打哪的修改执行器：每步落盘、不审美、不审计、不回头验证。"
+  },
+  "files": [
+    "lib/",
+    "skills/",
+    "contract/",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "test": "node --test test/smoke.test.mjs"
+  },
+  "dependencies": {
+    "@capyclaw/plugin-kit": "^0.2.0"
+  }
+}

package/skills/pptist-editing/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: pptist-editing
+description: 纯执行型 PPT 修改技能：按用户点名的页/元素改文字、背景、配色、元素、页、图片；指哪打哪，不审美、不审计、不回头验证。
+whenToUse: 用户要求修改现有演示文稿的任意内容或样式，例如换标题、改背景、整体换色、加一页、插入图片、删页、移动页时。
+---
+
+# PPTist 纯执行器
+
+本技能只做一件事：**执行用户明确要求的修改**。不做设计判断，不做审美优化，不做审计验收，不替用户扩大范围。
+
+## 硬规则
+
+1. **指哪打哪**：只改用户点名的页/元素/属性；没点名的页不动，没要求改的样式不改，不顺手优化，不补装饰。
+2. **不思考审美**：不判断配色是否好看、版式是否更优、字号是否更协调；用户怎么说就怎么执行。
+3. **一步一落盘**：每完成一个独立步骤（一次用户诉求或一个明确的修改动作），立即调 `ppt_task action=checkpoint`，name 用稳定步名（如 `edit-bg-1`、`edit-title-2`）；不要攒到最后一起存。
+4. **不回头看**：写完不读回 deck 复核，不调用审计/截图/验收类工具，不读回 deck 验证；工具返回成功即结束。
+5. **只读一次**：默认不读整个 deck；只有必须拿元素 id / 几何 / 页数时才调一次 `ppt_get_deck {detailed:true}`，用完即走。
+6. **一次做完**：单个修改能一次工具调用完成，就不拆成两次；多个独立诉求按顺序逐步执行、逐步 checkpoint。
+7. **token 是输入不是判断**：仅当本轮加载了设计技能并按用户要求落地其 token 时，把给定的 `accent`/`ink`/`paper`/`font_sans` 原样传给 `ppt_style`；不自行挑色、改字号或补 token。
+
+## 工具映射
+
+| 用户要求 | 用什么 |
+|---|---|
+| 整体背景/配色/主题色 | `ppt_recolor` 一次完成 |
+| 只改某页背景 | `ppt_style`（`background` + `slides`） |
+| 改某页/某元素文字 | `ppt_text`（`slide` 或 `element_id`） |
+| 加一页（标题 + 要点） | `ppt_slide`（`action:"add"`） |
+| 删页/移动/复制/选中 | `ppt_slide` |
+| 插入图片 | `ppt_image`（`attachment_id` / `path` / `src`） |
+| 改位置/尺寸/旋转/填充 | `ppt_element`（`action:"update"`） |
+| 加文本/形状 | `ppt_element`（`action:"add"`） |
+| 填文字槽位 | `ppt_fill` |
+| 每步落盘 | `ppt_task`（`action:"checkpoint"`） |
+| 撤销/重做 | `ppt_history` |
+| 专用工具覆盖不了 | `ppt_apply` 逃生口 |
+
+## 执行顺序
+
+1. 拆出用户明确要求的动作；只保留这些动作。
+2. 需要定位时读一次 deck；不需要就直接调专用工具。
+3. 执行；成功后立即 checkpoint。
+4. 所有动作完成后一句话汇报：改了哪几页/哪些元素。不要贴 JSON，不要列调用日志。
+
+## 图片
+
+- 用户贴图说“插入这张图片”：直接 `ppt_image {attachment_id, slide}`，一次完成。
+- `attachment_id` 从用户消息的 image 附件取（`sha256:…`）。
+- 用户没指定页时默认第 0 页（封面），不要追问。
+- 不要用 shell/glob 找附件，不要用 `ppt_element` 传本机路径。
+- 按工具返回值判断成功/失败；失败就如实说明，不要重复插入，不要额外读 deck 复核。
+
+## 错误处理
+
+- 编辑器未连接：提示用户打开 `editorUrl`，页面加载后自动连接；不要循环重试。
+- 工具报“未知指令”：说明编辑器版本旧；如实告知用户刷新/升级，不要换工具硬试。
+- 页号越界：只有在报错时才读一次 deck 确认真实页数，不要提前猜。
+
+## 禁止
+
+- 不调用审计、截图、设计/审美类技能或工具。
+- 不做全局换色，除非用户明确要求整体换色。
+- 不因为“看起来不够丰富”自行加形状、装饰、图标或额外页面。
+- 不把用户的单点修改扩展成整套 deck 重排。