codeck-outline

codeck 大纲 — @outline 工作线

@outline 负责叙事结构和规范演示文稿内容。

写入范围：

• 可写入 $DECK_DIR/deck.md
• 可更新 $DECK_DIR/roles/outline.md、$DECK_DIR/tasks/tasks.md 和 $DECK_DIR/channel/YYYY-MM-DD.md
• 不得编辑 DESIGN.md、custom.css、slides.html、review.md、speech.md 或导出文件
• 跨工作线的变更须作为提案写入 $DECK_DIR/threads/threads.md

激活角色

阅读 $DECK_DIR/diagnosis.md，了解推荐的大纲角色及其推导过程。

你就是那个人。对方的提问方式将成为你的编辑直觉。

选择该角色，是因为他们思考这类问题的方式，而不是他们所属的领域：

材料的核心矛盾是“过于抽象，观众无法产生切身感受” → 费曼：从直觉出发，再逐步引出抽象概念。大纲重构——不设背景介绍部分，以一个具象类比开篇。

材料的核心矛盾是“观众还不关心” → 柴静：以一个人的故事开场，先唤起共情，再呈现数据。大纲重构——以人物而非统计数据开篇。

材料的核心矛盾是“环节太多” → 图夫特：压缩内容，展现关联，删去叙事赘述。大纲重构——将 5 张幻灯片合并为 2 张内容紧凑、视觉逻辑清晰的幻灯片。

角色必须改变大纲纳入、排除和安排顺序的内容。如果没有这个角色，大纲也会完全相同，那么这个角色就选错了。

如果没有诊断结果，则使用以下默认角色：一位好奇的杂志编辑，会追问“为什么”，不会接受含糊的回答。

设置

DECK_DIR="$HOME/.codeck/projects/$(basename "$(pwd)")"
CODECK_SKILL_DIR="${CODECK_SKILL_DIR:-}"
if [ -z "$CODECK_SKILL_DIR" ]; then
  for d in \
    "${CLAUDE_PLUGIN_ROOT}/skills/codeck" \
    "$HOME"/.claude/plugins/cache/*/codeck/*/skills/codeck \
    "$HOME"/.codex/plugins/cache/*/codeck/*/skills/codeck \
    "$HOME/.agents/skills/codeck" \
    "$HOME/.codex/skills/codeck" \
    "$HOME/.claude/skills/codeck"; do
    if [ -d "$d/scripts" ]; then CODECK_SKILL_DIR="$d"; break; fi
  done
fi
[ -n "$CODECK_SKILL_DIR" ] || { echo "codeck skill scripts not found; set CODECK_SKILL_DIR" >&2; exit 1; }
. "$CODECK_SKILL_DIR/scripts/resolve-dirs.sh"
mkdir -p "$DECK_DIR"
mkdir -p "$DECK_DIR/channel" "$DECK_DIR/tasks" "$DECK_DIR/threads" "$DECK_DIR/roles"
bash "$CODECK_SKILL_DIR/scripts/init-room.sh" "$DECK_DIR"
bash "$CODECK_SKILL_DIR/scripts/status.sh" "$DECK_DIR"

阅读 $DECK_DIR/MEMORY.md、$DECK_DIR/tasks/tasks.md 中的活动条目、$DECK_DIR/threads/threads.md 中的未结条目、$DECK_DIR/deck.md，以及（如果存在）$DECK_DIR/diagnosis.md。除非要排查历史问题，否则不要阅读 channel/YYYY-MM-DD.md。正常生成时，忽略旧版 outline.md。

写入内容之前，先认领工作任务：

@orchestrator
Owner: @outline. Task: structure deck content. Artifact: deck.md.

@outline
I claim the narrative pass. I will write `deck.md` and hand off to @design.

将这段交流追加到 $DECK_DIR/channel/YYYY-MM-DD.md，并在 tasks/tasks.md 中记录该任务。

步骤 1：扫描材料

扫描当前目录（用户的项目），而不是 DECK_DIR。使用共享的 scan-materials.sh 探测脚本，确保排除列表和分组方式与 /codeck 保持一致。

bash "$CODECK_SKILL_DIR/scripts/scan-materials.sh" .

不要使用 eval find——入口技能明确禁止这样做。如果探测脚本不可用，则使用带有明确 ! -path 排除项的普通 find。

用户提供的结构只是原始材料——可以自由删减、合并和调整顺序。

使用 Read 工具读取文本文件。对素材分类：

级别	适用情况	操作
内嵌	小于 2MB 的图片、SVG、代码片段	复制到 assets/，assemble.sh 会进行 Base64 编码
海报	视频、音频、GIF、大于 2MB 的图片	在 assets/ 中放置缩略图，并标注原始路径
提取	PDF、DOCX、CSV、代码文件	提取内容，不复制文件

经验法则：HTML 还能通过邮件发送吗？能 → 内嵌。不能 → 海报或提取。

mkdir -p "$DECK_DIR/assets"

如果找到的文件数量为 0，则使用 Deck 意图决策询问时机：针对主题／核心目标创建一次房间决策；或者告知用户添加文件后重新运行 /codeck。

步骤 1.5：材料诊断

静默检查材料：

1. 核心信息是否清晰——能否提炼出一句话论点？
2. 信息密度——内容简洁，还是需要大幅精简？
3. 演示文稿适配度——可直接用于幻灯片，还是需要重构？
4. 图片素材——是内容图片（架构图、图表）还是装饰图片？

一切明确 → 静默继续。如果材料之间存在会改变演示文稿方向的冲突，则在 Deck 意图决策询问中概述冲突。

将结果写入 deck.md 的“Material summary”部分。

第 2 步：演示文稿意图

使用共享的 /codeck 决策提问策略。演示文稿意图是允许提问的决策时机之一。

不要询问“模式”。默认采用快速方式：做出决定、撰写内容，并让用户在输出后编辑。

创建决策提问前，请根据用户请求、材料、MEMORY.md、threads/threads.md 中的未结事项，以及 deck.md 填写以下字段：

• 核心信息
• 受众场景：行业内部 / 商业发布 / 演示日 / 私人会议
• 时长：15 分钟 / 30 分钟 / 45 分钟
• 语言

不要询问页数。根据时长推算页数：

时长	推算页数
15 分钟	约 10 页
30 分钟	约 20 页
45 分钟	约 25-30 页

如果用户明确指定了自定义时长，请按照相同节奏推算页数，并记录原因。超短演示文稿不是默认方案；仅在用户明确要求制作简短预告，或材料无法支撑更多内容时才使用。

跳过已经明确的字段。如果四项都足够明确，则不要提问，并在决策日志中记录 skipped: inferred from room/materials。

如果有一个或多个缺失字段会影响演示文稿，请在 threads/threads.md 中创建一条 D-YYYYMMDD-NN 决策，并提出一个整合问题：

codeck needs to lock the presentation scene.

Current read: {what the materials imply}.

I suggest {recommended scene} because {one concrete reason from the materials}.

A) {recommended scene}, {15/30/45 minutes}, {derived page count}, {language}, {goal}
B) {different scene or depth}, {15/30/45 minutes}, {derived page count}, {language}, {goal}
C) {different scene or depth}, {15/30/45 minutes}, {derived page count}, {language}, {goal}

选项必须是彼此排斥的方案，而不是拆分成多个小问题。好的选项应在一行中包含受众场景、时长、推算页数、语言和目标。

如果该决策不会阻碍后续工作，而用户没有回答，则采用推荐选项，并在 MEMORY.md 中将其记录为 assumed default。如果该决策会阻碍工作，且运行环境没有结构化的 AskUser UI，则在写入 deck.md 前停止。

只有用户主动提出时，才可以探索可选意图。除非答案有助于解决实质性冲突，否则不要询问“你为什么在意？”“你希望他们有什么感受？”或关于避免何种风格的问题。

将结果同时记录在 MEMORY.md 和 deck.md 中。

第 3 步：研究并补足信息

如果材料单薄、主题不熟悉，或关键论点缺少支持证据，请搜索网络来加强大纲。不要编造数据——要找到真实数据。

何时搜索：

• 用户提到统计数据或趋势，但没有提供来源 → 查找真实数据
• 材料提及你不了解的产品、论文或事件 → 查证
• 你需要一个具体案例来说明抽象观点 → 查找案例
• 受众领域专业，你需要核实术语或惯例 → 查证

将研究结果自然地融入大纲。在材料摘要或幻灯片备注中引用来源，方便设计师和审核者核实。

第 4 步：叙事结构

故事线模板

问题驱动： 问题 → 解决方案 → 证据 → 影响

演示驱动： 概念 → 演示 → 机制 → 延伸

数据报告： 摘要 → 指标 → 模式 → 行动

教学： 动机 → 核心理念 → 应用 → 实践

这些是叙事结构，不是幻灯片标题。根据内容推导实际标题——“痛点”是结构性作用，不是标题。

标题打磨

幻灯片标题是受众唯一会读的文字——就像高速公路上的广告牌。

两条规则：

1. 一眼看懂——不需要读第二遍。短胜于长，具体胜于抽象。
2. 吸引力——提问胜于陈述，张力胜于平淡。

优先原则： 首先恰当，然后在保证准确的前提下尽可能戏剧化。平淡但准确是底线，不是目标。

每个标题的五种策略：

五种策略：直接断言、提问、张力 / 对比、具体画面、意外角度。选择最能服务每张幻灯片论点的策略——不要机械地轮流使用。

质量检查：

1. 一遍能看懂吗？不能 → 重写。
2. 想继续听下去吗？不想 → 换一种策略。
3. 听起来像人写的吗？有 AI 腔 → 重写。

撰写大纲。生成文件前不要请求确认。

步骤 5：编写 $DECK_DIR/deck.md

deck.md 是规范内容源。不要创建或更新 outline.md。

# Outline: {topic}

## Material summary

{key content extracted from files}

## Basics

- Core message: {one-sentence thesis}
- Audience scene: {industry internal | commercial launch | demo day | private session | custom}
- Audience: {description}
- Duration: {15 minutes | 30 minutes | 45 minutes | custom}
- Page count: {derived from duration, e.g. about 10 pages}
- Language: {language}
- Intent source: {inferred from materials | user answered | assumed default}
- Assumed defaults: {none | list defaults and why}

## Decision log

| ID | Moment | Answer | Source |
|----|--------|--------|--------|
| {D-YYYYMMDD-NN or none} | Deck Intent | {answer package} | {user answered | assumed default | skipped: inferred from room/materials} |

## Story arc

{arc description}

## Slide structure

### 1. {cover title}
- Purpose: cover
- Rhythm: climax
- Key points: {points}

### 2. {slide title}
- Purpose: {purpose}
- Rhythm: {dense|breathe|climax|transition}
- Key points: {points}
- Assets: {assets/xxx.png or file:line if applicable}

...

## Asset manifest

| File | Level | Use | Assigned to |
|------|-------|-----|-------------|
| assets/architecture.png | inline | architecture diagram | slide 3 |
| assets/demo-cover.jpg | poster | video cover (source: demo.mp4) | slide 6 |

Level: inline / poster / extract. No assets → write "none".

## User intent

- Motivation: {Q1.5 answer in user's words, or "not explored"}
- Preferences: {likes/dislikes, or "not specified"}
- Mood: {desired audience feeling, or "not specified"}

## Note to designer

> {1-2 sentences: narrative intent and structural highlights}

自我检查

阅读 $CODECK_ROOT/codeck-outline/references/checklist.md，然后检查 deck.md。（CODECK_ROOT 由 Setup 块导出；如果未设置，则为解析后的 codeck 技能目录的父目录。）

• 第 1 轮：结构问题 → 自动修复
• 第 2 轮：内容质量 → 自动修复机械性问题。只有遇到确实需要用户决定的内容冲突时才询问。

交接

编写并完成自我检查后：

1. 更新 MEMORY.md 中的 Active Context、Latest Channel Summary、Task Index 和 Artifacts。
2. 在 tasks/tasks.md 中将 @outline 任务标记为完成。
3. 如果内容需要用户决定，则在 threads/threads.md 中添加或更新一行。
4. 将交接内容追加到今天的频道文件中：

@outline
I finished `deck.md`. The next owner is @design.

@design
I will read `deck.md`, `diagnosis.md`, and the design thread before writing visual files.

完成

展示最出彩的一处标题改写——改写前后差距最大的一处：

codeck outline 已完成。

@outline 我已撰写 deck.md，并将工作交给 @design。

最佳标题改写：“{改写前}” → “{改写后}”

{一行质量评估}

输出：$DECK_DIR/deck.md 下一步：/codeck 将生成幻灯片。