ai-agent-book/chapter2/agent-skills-ppt/demo.py

#!/usr/bin/env python3
"""
实验 2-6：使用 Agent Skills 从论文生成演示文稿（自建同构 Skills 机制）

本 demo 复现《深入理解 AI Agent》第二章「Agent Skills / 渐进式披露」一节的思想。
由于 Anthropic key 无效，这里用 OpenAI（gpt-5.6-luna）+ 一套自建的、与 Anthropic
Skills 同构的机制来演示，核心是「渐进式披露（Progressive Disclosure）」：

  第一层（元数据）：Agent 启动时的 system prompt 里只放各 Skill 的 name +
                    description（薄目录，数百 token），并不含具体流程。
  第二层（核心流程）：当任务需要时，Agent 主动用 read_skill 工具加载完整 SKILL.md。
  第三层（细则）：Agent 可再用 read_skill_file 读取 reference.md / 脚本源码。

然后 Agent 用捆绑脚本 scripts/generate_pptx.py（经 run_skill_script 工具）用
python-pptx 生成真实的 .pptx，并读回校验页数与每页标题。

运行：
    export OPENAI_API_KEY=your-openai-api-key
    python demo.py
"""

import argparse
import json
import os
import sys
from pathlib import Path

from openai import OpenAI
from pptx import Presentation

# 从同目录 .env 读取 OPENAI_API_KEY（若安装了 python-dotenv）
try:
    from dotenv import load_dotenv

    load_dotenv(Path(__file__).resolve().parent / ".env")
except ImportError:
    pass

# ---------------------------------------------------------------------------
# 路径与配置
# ---------------------------------------------------------------------------
ROOT = Path(__file__).resolve().parent
SKILLS_DIR = ROOT / "skills"
PAPER_PATH = ROOT / "papers" / "sample_paper.md"
OUTPUT_DIR = ROOT / "output"
MODEL = os.environ.get("OPENAI_MODEL", "gpt-5.6-luna")


def log(msg: str) -> None:
    print(msg, flush=True)


# ---------------------------------------------------------------------------
# 第一层：启动时扫描 skills/ 目录，只读取每个 SKILL.md 的 frontmatter
# （name + description），拼成薄目录注入 system prompt。这一步刻意「只看目录」。
# ---------------------------------------------------------------------------
def parse_frontmatter(skill_md: str) -> dict:
    """从 SKILL.md 顶部的 --- YAML frontmatter --- 中解析 name / description。"""
    meta = {}
    if not skill_md.startswith("---"):
        return meta
    end = skill_md.find("---", 3)
    if end == -1:
        return meta
    for line in skill_md[3:end].splitlines():
        if ":" in line:
            k, v = line.split(":", 1)
            meta[k.strip()] = v.strip()
    return meta


def scan_skill_catalog() -> dict:
    """返回 {skill_name: {"description":..., "dir": Path}}，只含元数据。"""
    catalog = {}
    for skill_md in sorted(SKILLS_DIR.glob("*/SKILL.md")):
        meta = parse_frontmatter(skill_md.read_text(encoding="utf-8"))
        name = meta.get("name") or skill_md.parent.name
        catalog[name] = {
            "description": meta.get("description", ""),
            "dir": skill_md.parent,
        }
    return catalog


def build_system_prompt(catalog: dict) -> str:
    lines = [
        "你是一个能使用 Agent Skills 的助手。你并不预先知道每个 Skill 的详细流程，",
        "只在下方看到一份「薄目录」——每个 Skill 的 name 与 description（路由条件）。",
        "",
        "当任务需要某个 Skill 时，你必须：",
        "  1) 先用 read_skill(name) 加载它的完整 SKILL.md（第二层：核心流程）；",
        "  2) 如需实现/样式细节，再用 read_skill_file(name, path) 读取子文档或脚本（第三层）；",
        "  3) 按 SKILL.md 的约定，用 run_skill_script 调用捆绑脚本完成任务。",
        "不要在没有 read_skill 的情况下臆测某个 Skill 的调用方式。",
        "",
        "== 已安装的 Skills（薄目录，仅元数据）==",
    ]
    for name, info in catalog.items():
        lines.append(f"- {name}: {info['description']}")
    return "\n".join(lines)


# ---------------------------------------------------------------------------
# 工具实现：read_skill / read_skill_file / run_skill_script
# 这些是「渐进式披露」的通道——第二、三层内容只有被调用时才进入上下文。
# ---------------------------------------------------------------------------
def tool_read_skill(catalog: dict, name: str) -> str:
    info = catalog.get(name)
    if not info:
        return f"[error] 未找到 Skill: {name}"
    content = (info["dir"] / "SKILL.md").read_text(encoding="utf-8")
    log(f"\n  >>> [渐进式披露·第二层] Agent 调用 read_skill('{name}')，"
        f"加载完整 SKILL.md（{len(content)} 字符）")
    return content


def tool_read_skill_file(catalog: dict, name: str, rel_path: str) -> str:
    info = catalog.get(name)
    if not info:
        return f"[error] 未找到 Skill: {name}"
    target = (info["dir"] / rel_path).resolve()
    # 防目录穿越：必须落在该 skill 目录内
    if not str(target).startswith(str(info["dir"].resolve())):
        return f"[error] 非法路径: {rel_path}"
    if not target.exists():
        return f"[error] 文件不存在: {rel_path}"
    content = target.read_text(encoding="utf-8")
    log(f"  >>> [渐进式披露·第三层] Agent 调用 read_skill_file('{name}', '{rel_path}')，"
        f"加载子文档（{len(content)} 字符）")
    return content


def tool_run_skill_script(catalog: dict, name: str, script: str, payload: str,
                          out_path: Path) -> str:
    info = catalog.get(name)
    if not info:
        return f"[error] 未找到 Skill: {name}"
    scripts_dir = (info["dir"] / "scripts").resolve()
    script_path = (scripts_dir / script).resolve()
    # 防目录穿越：脚本会被直接执行，必须落在该 skill 的 scripts 目录内
    if not script_path.is_relative_to(scripts_dir):
        return f"[error] 非法脚本路径: {script}"
    if not script_path.exists():
        return f"[error] 脚本不存在: {script}"

    # 动态载入捆绑脚本（它就是 Skill 的一部分）
    import importlib.util
    spec = importlib.util.spec_from_file_location("bundled_generator", script_path)
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)

    try:
        data = json.loads(payload) if isinstance(payload, str) else payload
    except json.JSONDecodeError as e:
        return f"[error] payload 不是合法 JSON: {e}"

    log(f"  >>> [执行捆绑脚本] run_skill_script('{name}', '{script}') "
        f"生成 {out_path.name} ...")
    result = module.build_presentation(data, str(out_path))
    return json.dumps(result, ensure_ascii=False)


TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "read_skill",
            "description": "加载指定 Skill 的完整 SKILL.md（核心流程，渐进式披露第二层）。",
            "parameters": {
                "type": "object",
                "properties": {"name": {"type": "string", "description": "Skill 名称"}},
                "required": ["name"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "read_skill_file",
            "description": "读取某 Skill 目录内的子文档或脚本源码（细则，渐进式披露第三层）。",
            "parameters": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "path": {"type": "string", "description": "相对 skill 目录的路径，如 reference.md 或 scripts/generate_pptx.py"},
                },
                "required": ["name", "path"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "run_skill_script",
            "description": "执行某 Skill 捆绑的脚本以完成实际产出（如生成 pptx）。",
            "parameters": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "script": {"type": "string", "description": "脚本文件名，如 generate_pptx.py"},
                    "payload": {"type": "string", "description": "传给脚本的 JSON 字符串（大纲）"},
                },
                "required": ["name", "script", "payload"],
            },
        },
    },
]


def dispatch(catalog: dict, name: str, args: dict, out_path: Path) -> str:
    # 模型给的 arguments 可能缺字段（或根本不是合法 JSON，被上层回退成 {}）。
    # 缺参时返回 [error] 让 Agent 在下一轮自我纠正，而不是抛 KeyError 中断 loop。
    required = {
        "read_skill": ["name"],
        "read_skill_file": ["name", "path"],
        "run_skill_script": ["name", "script", "payload"],
    }
    if name not in required:
        return f"[error] 未知工具: {name}"
    missing = [k for k in required[name] if k not in args]
    if missing:
        return f"[error] 工具 {name} 缺少参数: {', '.join(missing)}"
    if name == "read_skill":
        return tool_read_skill(catalog, args["name"])
    if name == "read_skill_file":
        return tool_read_skill_file(catalog, args["name"], args["path"])
    return tool_run_skill_script(catalog, args["name"], args["script"],
                                 args["payload"], out_path)


# ---------------------------------------------------------------------------
# 主流程：agentic loop
# ---------------------------------------------------------------------------
def run_agent(paper_path: Path, model: str, out_path: Path,
              max_turns: int = 8) -> Path | None:
    # OPENAI_API_KEY 存在则官方直连；否则回退 OPENROUTER_API_KEY
    # （gpt-* 模型名会被映射为 openai/…）。两者皆无则给出清晰错误。
    from agentbook.providers import resolve_backend

    if not os.environ.get("OPENAI_API_KEY") and not os.environ.get("OPENROUTER_API_KEY"):
        log("错误：未设置 OPENAI_API_KEY，也未设置 OPENROUTER_API_KEY（通用回退）。")
        log("请 export OPENAI_API_KEY=your-openai-api-key 或 export OPENROUTER_API_KEY=your-openrouter-api-key")
        log("（无 key 时可用 --offline 走内置大纲、确定性地复现三层渐进式披露并生成 pptx。）")
        sys.exit(1)

    # 端点与 key 的对应关系由 agentbook 的 provider 注册表统一维护，
    # OPENAI_BASE_URL 覆盖也在其中处理。
    backend = resolve_backend("openai", model=model)
    model = backend.model
    # timeout + 自动重试：单次网络/SSL 抖动不至于让整个 agentic loop 崩溃
    client = OpenAI(
        api_key=backend.api_key, base_url=backend.base_url, timeout=60.0, max_retries=3
    )
    catalog = scan_skill_catalog()

    system_prompt = build_system_prompt(catalog)
    log("=" * 72)
    log("【第一层·元数据】Agent 启动时只看到这份薄 Skill 目录（system prompt）：")
    log("-" * 72)
    log(system_prompt)
    log("-" * 72)
    log(f"（薄目录约 {len(system_prompt)} 字符 / 数百 token；各 Skill 的详细流程此刻并不在上下文中）")
    log("=" * 72)

    paper = paper_path.read_text(encoding="utf-8")
    user_task = (
        "请把下面这篇论文做成一份 8-12 页的演示文稿（含标题页、目录页、问题背景、"
        "方法概述、关键结果、局限性、小结页），总页数务必落在 8-12 页。"
        "先判断该用哪个 Skill，再严格按其 SKILL.md 的页序与约束操作。\n\n"
        "=== 论文全文 ===\n" + paper
    )

    messages = [
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": user_task},
    ]

    log("\n【任务下发】要求 Agent 从论文生成演示文稿。观察它如何按需渐进式披露：\n")

    final_result = None
    for turn in range(1, max_turns + 1):
        resp = client.chat.completions.create(
            model=model,
            messages=messages,
            tools=TOOLS,
            temperature=0.2,
        )
        msg = resp.choices[0].message
        messages.append(msg.model_dump(exclude_none=True))

        if not msg.tool_calls:
            log(f"\n【Agent 第 {turn} 轮·结束语】\n{msg.content}")
            break

        for tc in msg.tool_calls:
            fn = tc.function.name
            try:
                args = json.loads(tc.function.arguments or "{}")
            except json.JSONDecodeError:
                args = {}
            log(f"\n[Agent 第 {turn} 轮] 调用工具 -> {fn}({', '.join(f'{k}={_short(v)}' for k, v in args.items())})")
            result = dispatch(catalog, fn, args, out_path)
            if fn == "run_skill_script" and not result.startswith("[error]"):
                final_result = json.loads(result)
                log(f"  >>> 生成结果：{result}")
            messages.append({
                "role": "tool",
                "tool_call_id": tc.id,
                "content": result,
            })

    if final_result:
        return Path(final_result["path"])
    return None


# ---------------------------------------------------------------------------
# 离线复现：无 OpenAI key 时，用内置大纲（papers/sample_outline.json）确定性地
# 走完与在线完全相同的三层渐进式披露与工具通道（read_skill / read_skill_file /
# run_skill_script），从而在没有任何 API 访问权限时也能真实生成并校验 pptx。
# 唯一区别是「用哪个 Skill、大纲写什么」由预置脚本给定，而非模型即时决策。
# ---------------------------------------------------------------------------
OUTLINE_PATH = ROOT / "papers" / "sample_outline.json"


def run_offline(out_path: Path) -> Path | None:
    catalog = scan_skill_catalog()
    system_prompt = build_system_prompt(catalog)
    log("=" * 72)
    log("【离线模式】不调用 OpenAI，用内置大纲确定性地复现三层渐进式披露。")
    log("【第一层·元数据】启动时只看到这份薄 Skill 目录（system prompt）：")
    log("-" * 72)
    log(system_prompt)
    log("-" * 72)
    log(f"（薄目录约 {len(system_prompt)} 字符；各 Skill 的详细流程此刻并不在上下文中）")
    log("=" * 72)

    if not OUTLINE_PATH.exists():
        log(f"错误：内置大纲不存在：{OUTLINE_PATH}")
        return None

    # 与在线 agentic loop 相同的工具通道，只是调用序列由脚本给定
    log("\n【离线回放】按 SKILL.md 约定，逐层加载并调用捆绑脚本：")
    dispatch(catalog, "read_skill", {"name": "pptx"}, out_path)
    dispatch(catalog, "read_skill_file",
             {"name": "pptx", "path": "reference.md"}, out_path)

    payload = OUTLINE_PATH.read_text(encoding="utf-8")
    result = dispatch(catalog, "run_skill_script",
                      {"name": "pptx", "script": "generate_pptx.py", "payload": payload},
                      out_path)
    if result.startswith("[error]"):
        log(f"  >>> 生成失败：{result}")
        return None
    log(f"  >>> 生成结果：{result}")
    return Path(json.loads(result)["path"])


def _short(v, n=48):
    s = str(v).replace("\n", " ")
    return s if len(s) <= n else s[:n] + "…"


# ---------------------------------------------------------------------------
# 校验：用 python-pptx 重新打开生成的文件，读回页数与每页标题，证明是有效 pptx。
# ---------------------------------------------------------------------------
def verify_pptx(path: Path) -> None:
    log("\n" + "=" * 72)
    log("【校验】用 python-pptx 重新打开生成的文件，读回页数与每页标题：")
    log("-" * 72)
    prs = Presentation(str(path))
    slides = list(prs.slides)
    log(f"文件: {path}")
    log(f"总页数: {len(slides)}")
    for i, slide in enumerate(slides, 1):
        first_text = "(空)"
        for shp in slide.shapes:
            if shp.has_text_frame and shp.text_frame.text.strip():
                first_text = shp.text_frame.text.strip().splitlines()[0]
                break
        log(f"  第 {i:>2} 页标题: {first_text}")
    log("-" * 72)
    log(f"校验通过：这是一个可被 python-pptx / PowerPoint 打开的有效 .pptx（{len(slides)} 页）。")
    log("=" * 72)


def parse_args():
    p = argparse.ArgumentParser(
        description="实验 2-6：用 Agent Skills 的「渐进式披露」从论文生成演示文稿。"
                    "Agent 启动只看到薄 Skill 目录，按需逐层加载 pptx Skill 的流程与脚本，"
                    "最后用 python-pptx 生成并校验 output/presentation.pptx。",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    p.add_argument("--paper", default=str(PAPER_PATH),
                   help="输入论文/大纲（markdown）路径，默认 papers/sample_paper.md。")
    p.add_argument("--output", "-o", default=str(OUTPUT_DIR / "presentation.pptx"),
                   help="输出 .pptx 路径，默认 output/presentation.pptx。")
    p.add_argument("--model", default=MODEL,
                   help="OpenAI 模型名，默认取环境变量 OPENAI_MODEL，否则 gpt-5.6-luna。")
    p.add_argument("--max-turns", type=int, default=8,
                   help="agentic loop 的最大轮数，默认 8。")
    p.add_argument("--offline", action="store_true",
                   help="离线演示：不调用 OpenAI，用内置大纲（papers/sample_outline.json）"
                        "确定性地走完三层渐进式披露并生成 pptx（无需 API key，可复现）。")
    return p.parse_args()


def main():
    args = parse_args()
    paper_path = Path(args.paper)
    out_path = Path(args.output)
    out_path.parent.mkdir(parents=True, exist_ok=True)

    if args.offline:
        pptx_path = run_offline(out_path)
    else:
        if not paper_path.exists():
            log(f"错误：论文文件不存在：{paper_path}")
            sys.exit(1)
        pptx_path = run_agent(paper_path, args.model, out_path, args.max_turns)

    if pptx_path and pptx_path.exists():
        verify_pptx(pptx_path)
    else:
        log("\n未生成 pptx。请检查上面的日志。")
        sys.exit(2)


if __name__ == "__main__":
    main()