@capyclaw/ppt-skill-narrative 0.0.0-stage → 2.2.0

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# dsh-ppt-skill-narrative bundle patch：只注册 pptmaster-narrative 一个 skill provider。
+- insert:
+    - id: ppt-skill-narrative
+      name: dsh-ppt-skill-narrative

package/lib/index.mjs

@@ -0,0 +1,23 @@
+/** dsh-ppt-skill-narrative：单 skill provider。 */
+import { fileURLToPath } from 'node:url'
+import { createSkillProvider } from './provider.mjs'
+
+export const name = 'ppt-skill-narrative'
+export const inject = ['skills']
+const SKILL = "pptmaster-narrative"
+
+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-narrative",
+    skillDirs: [SKILL],
+    contractNote: (version, skillName) => (String(skillName || '').startsWith('pptmaster-')
+      ? ''
+      : '契约：PPTist Workbench ' + version + '。动作前先调用 ppt_capabilities；工具缺失或 major 不一致时停止，并提示用户安装/升级 dsh-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,28 @@
-{
-  "name": "@capyclaw/ppt-skill-narrative",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@capyclaw/ppt-skill-narrative",
+  "version": "2.2.0",
+  "description": "PPT skill：SCQA、金字塔、一页一观点、deck_brief。",
+  "type": "module",
+  "main": "./lib/index.mjs",
+  "exports": {
+    ".": "./lib/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "meta": {
+    "title": "PPT Skill · PPT 叙事",
+    "description": "SCQA、金字塔、一页一观点、deck_brief。"
+  },
+  "files": [
+    "lib/",
+    "skills/",
+    "contract/",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "license": "MIT"
+}

package/skills/pptmaster-narrative/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: pptmaster-narrative
+description: 方案叙事架构：SCQA 开场、金字塔结构、一页一观点、判断句标题、证据引用、章首过渡与收束。输出 deck 骨架，不负责 PPTist 工具调用与视觉渲染。
+whenToUse: 用户要做方案型/汇报型/提案型 PPT，或要求梳理故事线、目录、章节、页面结构、把资料变成有结论的 deck 时。
+---
+
+# PPTMaster 叙事架构
+
+本技能只负责 **内容结构**，不调用 `ppt_*` 工具，也不决定配色与版式。视觉/工具分别交给独立的视觉技能和工具技能。
+
+## 硬纪律
+
+| 纪律 | 对治 |
+|---|---|
+| **一页一观点**：一页只讲一个核心判断 + ≤4 条支撑论据 | 信息密度爆炸 |
+| **消化不罗列**：每条论据挂在判断下，并标来源 | 资料一页页堆 |
+| **SCQA 开场**：现状 → 冲突 → 核心问题 | 上来就讲内容 |
+| **金字塔**：先顶层结论，再 3–5 个论点（=章节），每章 2–4 页 | 平铺、无结论 |
+| **判断句标题**：标题是结论，不是话题词 | “品牌定位” vs “应占据日常可及的专业精品定位” |
+| **章章递进**：章首过渡问题，章末收束判断，下一章承接 | 章节硬切 |
+
+## 流程
+
+1. **拆 brief**：目标 / 预算 / KPI / 时间 / YES / NO；提炼真正的根问题。
+2. **SCQA**：写 `situation`、`complication`、`question`，顶层主张 `answer`。
+3. **金字塔**：把 answer 拆成 3–5 个支撑论点；各章标题连读应能讲通 answer。
+4. **切页**：每页写 `governing_thought`（判断句）+ ≤4 条 `points` + `evidence_refs`。
+5. **补结构件**：封面、目录、brief 开场、章节过渡、章节收束、总结论、行动页。
+6. **自检**：逐条对照硬纪律；结构件缺一不可，判断句标题不能是话题词。
+
+## 输出：deck_brief JSON（内部使用）
+
+```json
+{
+  "cover": { "title": "方案标题(可含主张)", "subtitle": "客户/项目/日期" },
+  "toc": ["第1章 ...", "第2章 ..."],
+  "brief_opening": {
+    "situation": "现状事实",
+    "complication": "变化/矛盾",
+    "question": "本方案要回答的那一个核心问题"
+  },
+  "sections": [{
+    "section_no": 1,
+    "title": "章节标题",
+    "transition_question": "章首引导问题",
+    "pages": [{
+      "page_no": 1,
+      "governing_thought": "完整判断句",
+      "points": ["论据1", "论据2"],
+      "evidence_refs": ["ind-01", "comp-03"],
+      "layout_hint": "big-number|comparison|timeline|matrix|statement|quote|diagram|bullets"
+    }],
+    "closing_judgment": "本章收束判断"
+  }],
+  "conclusion": { "governing_thought": "全案顶层结论", "action_items": ["下一步"] }
+}
+```
+
+把 `deck_brief` 交给成稿技能：它负责选版式、把 `layout_hint` 映射到 PPTist 页型，并调用工具。不要让本技能直接写工具参数。
+
+## 写作
+
+- 用具体细节和数字，不用空洞形容词；不会的数据标“待验证/假设”，不编。
+- 简洁、短句、动词；避免“赋能/抓手/闭环/全方位”等黑话。
+- 每页标题能单独读懂；读者扫标题能得到完整论证线。
+- 详细方法：`references/scqa-pyramid.md`、`references/page-craft.md`、`references/deck-structure.md`。

package/skills/pptmaster-narrative/references/deck-structure.md

@@ -0,0 +1,42 @@
+# Deck 结构件与骨架
+
+## 结构件（方案型必备）
+
+```text
+封面               标题可直接打核心主张
+目录               方案地图（纯创意案可省）
+Brief 开场          S 现状 → C 冲突 → Q 根问题（SCQA）
+第 N 章 过渡页      用一个问题引出本章
+  内容页 ×K         一页一观点
+  本章收束判断       本章结论，下一章承接
+总结论页            SCQA 的 A / 金字塔顶
+行动页             必须做 vs 可以做，给下一步
+```
+
+结尾不要只写“谢谢”；回到核心主张或留一句记忆点。
+
+## 页面字段
+
+```json
+{
+  "page_no": 1,
+  "governing_thought": "完整判断句",
+  "points": ["论据 1", "论据 2"],
+  "evidence_refs": ["ind-01", "comp-03"],
+  "layout_hint": "big-number|comparison|timeline|matrix|statement|quote|diagram|bullets"
+}
+```
+
+硬规则：
+
+- 每页有且仅有一个 `governing_thought`，必须是判断句。
+- `points` ≤ 4；超过说明是两个观点，拆页。
+- 每个内容页 `evidence_refs` 非空；没有来源的判断标假设或砍掉。
+- 章节必须有 `transition_question` 与 `closing_judgment`。
+
+## 简版 / 详版
+
+- 简版 10–15 页：brief → 各章顶层判断 → 总结论 → 行动。
+- 详版 20–50 页：每个判断展开论据与推导。
+
+先按详版搭，简版 = 每章只留顶层判断页。

package/skills/pptmaster-narrative/references/page-craft.md

@@ -0,0 +1,31 @@
+# 切页与页面文案
+
+## 一页一观点
+
+1. 把一章的核心判断列出来，每个独立判断一页。
+2. 每页配 ≤4 条论据；超过 4 条 = 两个观点，拆页。
+3. 每条论据挂 `evidence_refs`；无出处的判断标假设或砍掉。
+4. 与本页判断无关的论据，再有趣也不放。
+
+## 判断句标题
+
+- ❌ 话题词：“品牌定位”“竞品分析”“市场现状”
+- ✅ 判断句：“竞品在高质平价与匠人叙事间留下中间带”“增长正从开店红利切到复购红利”
+
+标题就是这页的结论；读者扫标题应能获得论证主线。
+
+## 文案公式
+
+| 页型 | 公式 |
+|---|---|
+| 问题/痛点 | PAS：痛点 → 代价 → 方案 |
+| 紧迫 | Cost of Inaction：不行动每周期损失什么 |
+| 转变 | Before-After-Bridge：之前 → 之后 → 方案是桥 |
+| 优势 | FAB：能力 → 优势 → 利益 |
+| 对比 | 前后对比：痛点 vs 效果，感性 + 理性 |
+
+## 情绪弧
+
+好奇 → 焦虑/不满（摆冲突）→ 希望（给方向）→ 信任（证据）→ 笃定/紧迫（行动）。
+
+避免“首先/其次/最后”“综上所述”“赋能/抓手/闭环”等 AI 味套话；用具体细节和数字。

package/skills/pptmaster-narrative/references/scqa-pyramid.md

@@ -0,0 +1,26 @@
+# SCQA 与金字塔
+
+## SCQA
+
+- **S 现状**：对方认可的事实。
+- **C 冲突**：变化/矛盾/威胁，让现状不可持续。
+- **Q 问题**：因此必须回答的那一个核心问题（根问题）。
+- **A 答案**：你的顶层主张，后面所有章节为它服务。
+
+S+C+Q 落进 `brief_opening`；A 落进 `conclusion.governing_thought`，并在开场预告。
+
+## 金字塔
+
+```text
+顶层结论 A
+  ├─ 论点 1（章节 1）
+  │    ├─ 论据（页）
+  │    └─ 论据（页）
+  ├─ 论点 2
+  └─ 论点 3
+```
+
+- 章节 3–5 个；把章节标题连起来读，应能讲通 A。
+- 每页标题写判断句，内容是支撑它的论据。
+- 动笔前先想清楚“读完最希望对方记住的那一句话”，那就是 A。
+- 设计一个可记忆抓手（核心策略名/金句/比喻），开场、章节、结尾重复。