Prompting for Agents | Code w/ Claude

• Youtube

• 主讲人：Hannah（Applied AI）与 Jeremy（Applied AI，产品工程师）。

• 什么是 Agent（Hannah）

  • Anthropic 的定义：“模型在循环中使用工具”（models using tools in a loop）。
  • 工作方式：给定任务 → 代理自主选择调用工具 → 根据工具反馈更新决策 → 持续迭代直至完成。
  • 三要素：环境（可用工具与外部系统）、工具（可执行能力）、系统提示（告诉代理目标/角色）。
  • 设计原则：越简洁越好；让模型在明确目标与工具下自己工作。

• 何时（不）该用 Agent：使用清单（Hannah）

  • 任务复杂度：若人类能直给“可重复的步骤”，更像工作流/脚本；不必上代理。路径不明确、需探索时更适合代理。
  • 价值密度：高杠杆/高价值（如可能带来收入或显著体验提升）更值得用代理；低价值任务用简单工作流即可。
  • 可行性：能否为代理提供完成任务所需的工具与数据？若缺关键工具/权限，应缩小范围或改用他法。
  • 错误成本/可纠错性：难发现或代价高的错误 → 加人类在环；易发现且可回滚 → 可放权。

• 典型用例举例（Hannah）

  • 编码：从设计文档到 PR，路径与迭代不确定，高价值、很适合代理。
  • 搜索/研究：可用引用与复核纠错；错误可恢复。
  • 电脑操作（Computer Use）：多次尝试可回退，适合试错式点击与流程探索。
  • 数据分析：目标明确但数据形态/质量未知、步骤需探索，适合代理。

• 为 Agent 提示的核心理念（Jeremy）

  • 像代理那样思考：建立代理在其工具与返回值构成的环境中的心智模型；用“人类可理解”的工具描述/模式来模拟代理处境。

  • 给出务实的启发式（heuristics）：

    • 例：不可逆操作要谨慎；找到答案就停止；预算/配额（简单查询 ≤5 次工具调用；复杂可到 10–15）。
    • 将“常识”写明，避免模型过度主动/过度探索。

  • 工具选择策略很关键：

    • Sonnet 4 / Opus 4 可同时挂大量工具（~100+），但必须明确“何时优先用哪类工具”（如公司内事先查 Slack）。
    • 避免只给“短描述+一堆工具名”，要写清使用场景与优先级。

  • 引导思考过程（不仅是开“扩展思考”开关）：

    • 在首个思考块里要求：评估问题复杂度、规划工具调用数量、列出信息源、成功判据。
    • 使用 “工具调用间的思考（interleaved thinking）”：拿到结果后反思质量、决定是否验证/补充/加免责声明。

  • 代理的不可预测性与副作用：

    • 提示如“持续搜索直到找到最优来源” → 可能无止境循环/撑爆上下文；需写清停止条件与“足够好”的标准。

  • 上下文窗口管理：

    • Claude 4 上下文约 200k tokens；长任务会触顶。
    • Compaction：约 190k 触发自动压缩总结，把关键上下文迁移到新会话，通常可近乎无限续航（偶尔丢细节）。
    • 外部文件记忆：把关键状态写入文件，作为“外置记忆”扩展上下文。
    • 子代理（sub-agents）：让子代理负责重检索/重处理，压缩结果回传给主代理，节省主会话上下文。

  • 让 Claude 做 Claude：

    • 先用极简提示+少量工具试跑，看真实缺陷再补指令与示例；别过早把流程写死。

• 工具设计（Jeremy）

  • 好工具的特征：名称简单准确；描述完备（人读得懂即可用）；已测试可用。
  • 避免同质化/重名工具（如 6 个相似搜索器）；相近能力合并成单一工具。
  • 让代理从数据库查询 → 反思 → 生成发票 → 发邮件等形成完整工具-思考-再行动闭环。

• 实操演示（Jeremy）

  • 在 Console 中演示一个研究型代理提示（约千 token）：

    • 要求预规划、并行工具调用（并行多路搜索）、思考与工具交替、质量标准/信息源要求、工具预算。

  • 示例问题：“一辆 Rivian R1S 能装下多少根香蕉？”

    • 模型需上网查规格/香蕉尺寸 → 并行检索 → 单位换算/体积估算 → 得出数量级（常见区间 3万–5万，一次演示约 4.8 万）。
    • 过程中可见思考块与工具调用交替、对结果反思/再查/计算。

• 评估（Evals）方法论（Jeremy）

  • 从小做起：效果显著时小样本也能给强信号；不要一开始就做“数百样本全自动大评测”，先跑少量真实用例。

  • 贴近真实任务：评测内容要与生产任务一致（编码就用真实工程任务，不是竞赛题）。

  • LLM 作为裁判（LLM-as-a-Judge）+ 明确评分规程：

    • 例：搜索任务给出来源质量/答案区间等判据（如 R1S 香蕉量应在一合理区间）。
    • 比“字符串匹配”更鲁棒。

  • 工具使用准确性：程序化检查是否调用了应有工具/次数（如“订机票”必须调用“搜索航班”工具）。

  • 最终状态评测（文中口误提到 tobench/“Towen” 等开源基准）：检验是否达到正确终态（DB 行被正确更新、文件被修改、PR 达标等）。

  • 人工评测不可替代：阅读对话/思考块/调用轨迹，理解系统真实行为与问题根因。

• Q&A 精要

  • 构建代理提示的流程：从短小简单开始 → 试跑 → 收集失败/边界用例 → 逐步补充指令与示例，提升通过率。

  • Few-shot/CoT 在代理里的位置：

    • 前沿模型已“会思考”，无需强行“用链式思考”口令。
    • 少量非刚性示例可用，但避免过度规定流程以免束缚模型；更应指定思考/计划方式与注意事项（如在思考里先列计划/预算/成功判据）。

  • 并行与协作：可多开实例并行推进；必要时用共享 Markdown/票据文件在代理间传递状态。

• 可复用的提示要点汇总（从演讲中抽取）

  • 角色/目标：一句话明确任务与成功定义。
  • 工具策略：列出工具及使用优先级/典型触发场景；设定调用预算与停止条件。
  • 思考指导：首个思考块先做计划（复杂度、调用数、来源、验真方法、成功标准）。
  • 风险控制：不可逆操作需确认；找到答案即可停止；上下文接近上限时启用压缩/外部记忆。
  • 输出契约：需要可解析结构（JSON/标记块），并在必要时附上证据/引用或免责声明。
  • 评估闭环：小样本真实任务 + LLM 裁判（带 rubric）+ 工具使用与终态校验；逐步扩展覆盖面。

Prompting 101 | Code w/ Claude

• Youtube

• 视频信息与主旨

  • 主讲人：Hannah（Applied AI 团队）与 Christian（Applied AI 团队）。
  • 目标：用一个真实改编的业务场景，演示如何迭代构建高质量 Prompt 与最佳实践。

• 场景设定（保险理赔示例）

  • 角色：瑞典一家车险公司的理赔场景。
  • 输入：① 车祸事故报告表（瑞典语，17 个勾选项，左右两列分别代表车辆 A / 车辆 B）；② 人工手绘事故草图。
  • 任务：从表单 + 草图中抽取客观事实，并判断责任归属（谁应负主要责任）。

• 第一次直接尝试（V0）与教训

  • 把两份材料直接丢给模型，只给了很粗糙的提示。
  • 结果：模型误判为“滑雪事故”，并错误理解地名（因为任务与上下文未设定）。
  • 结论：Prompt 工程是迭代+实证过程；需要逐步补全场景、边界与约束。

• 推荐的 Prompt 总体结构（面向一次命中 / API 场景）

  • Task / 角色与目标：告诉模型“你是谁、要做什么、成功标准是什么”。
  • Content / 动态输入：此次为表单图像 + 草图（也可能来自外部系统）。
  • Instructions / 详细步骤：先做什么再做什么，如何推理、何时停。
  • Examples / 示例：必要时提供正反例/棘手样例及预期输出。
  • Reminders / 重要提醒：防幻觉、仅在有把握时输出、引用依据等。
  • 说明：实际演示会把这些模块分布在 system prompt 与 user prompt 中，按稳定性与复用度区分。

• 版本迭代与关键改进

  • V1 → V2：补足任务与“语气/置信度”

    • 明确：这是车险理赔；图像是人手绘；看不清就不要猜；仅在非常有把握时下结论。
    • 温度设定：temperature = 0；max tokens 很大（保证可重复且不被截断）。

  • V3：把“稳定背景”放入 System Prompt

    • 固定不变的信息（表单结构：标题、左右列含义、17 行各自代表什么；常见填写不规范方式如圈/涂抹/非“×”等）长期缓存/复用。
    • 价值：让模型不用每次再猜表单结构，减少无关叙述，更快进入事实抽取。

  • 结构化标记与组织

    • 使用 XML 风格标签（或 Markdown 分节）明确区块：如 <analysis_form>…</analysis_form>、<sketch_analysis>…</sketch_analysis>、<final_verdict>…</final_verdict>，便于引用与对齐。

  • 处理顺序（至关重要）

    • 先读表单逐项确认哪些框被勾选并记录客观事实 → 再读草图结合上述事实理解过程。
    • 目的：避免“先看草图”导致的误导与幻觉。

  • 证据与自信度约束

    • 输出判断必须引用依据（如“车辆 B 右转—因为第 X 项明确被勾选”）。
    • 不清楚就拒答/说明不确定，不要臆测。

  • V4：输出契约（Output Contract）与可落地性

    • 规定最终输出模板（如仅把“最终裁定”包在 <final_verdict> 内），其他分析供调试用、生产可裁剪。
    • 可配合预填（prefill）技巧：要求以特定XML 片段 / JSON 结构开头，便于机器可解析与下游写库。

  • 示例（Few-shot）与“棘手样例库”

    • 在 system prompt 中累积边界/灰度案例；必要时把图片 base64嵌入示例并附文字说明，帮助模型学会拆解/比对。

  • 会话/历史（可选）

    • 用户导向的长对话产品：可在 system prompt 摘要相关对话历史以丰富上下文（本 Demo 为后台处理，未使用）。

• 实际演示观察到的行为变化

  • 加入系统背景后，模型不再解释表单含义本身，而是聚焦勾选事实与草图对应。
  • 按“先表单后草图”的顺序，模型能更自信地判断：示例中明确给出车辆 B 负责的结论。
  • 若在指令中要求“逐项核对每个勾选框”，模型会显式展示过程（利于开发调试；生产可简化）。

• 重要实践要点（通用化总结）

  • 把稳定知识放入 System，变动数据放入 User；减少“每次再解释”的开销。
  • 顺序与结构化（XML/区块标签）能显著降低幻觉、提升可维护性与可复现性。
  • 给出停止条件与置信度规则，避免“凑答案”。
  • 要求引用依据，形成可审计的判断链。
  • 预填/输出格式契约让结果直接可机读（JSON/XML），方便落地到数据库/流程。

• 扩展能力与工具

  • Prompt Caching：对长期不变的系统背景（如表单结构）启用缓存以省成本、提性能。
  • Extended Thinking / 思考展开：可作为分析“模型是怎么想的”的抓手；从思考过程反推把有效步骤固化进 prompt（更省 token、效果更稳）。

MCP 201 — The Power of the Protocol | Code w/ Claude

• Youtube

• 主讲：David Soria Parra（Anthropic，MCP 共创者之一）。

• 目标：系统讲解 MCP 协议的能力边界，不仅限于多数人熟悉的 tools（工具调用），还包含其它原语（primitives），并展示如何构建更丰富的交互与 路线图（Web 化、授权、扩展性等）

• 开场与主旨

  • 现在大家对 MCP 的使用多集中在 工具调用；本次要展示 协议可用的所有原语 与 更进阶的交互模式
  • 结构：先讲 MCP 服务器可暴露给客户端的原语 → 再讲鲜为人知的能力 → 如何构建更丰富交互 → 展望 MCP on the Web 与近/中期计划

• MCP 原语（一）：Prompts（提示模版）—「用户驱动」

  • 定义：由 MCP 服务器暴露的可复用交互模板（一段文本/提示），用户可直接注入上下文来指导模型

  • 价值：

    • 由服务器作者提供最佳使用示例，让用户知道“怎样用这个服务器最有效”
    • 动态：Prompt 底层可执行代码（在 MCP 服务器中），可做更丰富的参数化逻辑

  • 演示：在编辑器中调用 Prompt，把 GitHub PR 的评论拉进上下文，便于随后让模型按这些评论修改代码

  • 与工具的区别：是否由用户决定加进上下文（Prompts） vs 由模型决定何时调用（Tools）

  • Prompt Completion（参数补全）：Prompt 可定义参数与自动补全（例如弹出 PR 列表供选择），在 TS 中几行代码即可实现（一个生成 Prompt 的函数 + 一个 completion 函数）

• MCP 原语（二）：Resources（资源）—「应用驱动」

  • 定义：服务器对客户端暴露的原始数据/内容（文件、Schema、文档、知识等）

  • 用法：

    • 客户端可直接把资源内容加入上下文
    • 也可对资源构建向量索引/做 RAG，由应用挑选最相关内容再注入（目前仍待更多探索）

  • 演示：将某数据库（示例中为 apostra）Schema 以 Resource 暴露，客户端把它当“文件”加入上下文，请 Claude 绘制可视化关系图

• MCP 原语（三）：Tools（工具）—「模型驱动」

  • 定义：服务器暴露的可执行动作；由模型推理时决定何时调用
  • 经验：当模型第一次成功调用并产生外部影响（如查库/改数据）是很“魔法”的时刻

• 三原语的「交互模型」与分工

  • Prompts：用户驱动（slash 命令、Add 命令等），用户决定把什么放进上下文
  • Resources：应用/客户端驱动（检索、索引、择优注入）
  • Tools：模型驱动（推理中自主调用）
  • 同一份数据可被三种方式暴露，取决于希望何时/由谁把它引入到交互中 → 帮助做出更细腻的产品体验，而不只是“等模型来调工具”

• 超越基础：更丰富的交互模式

  • 例题：“做一个能总结 Issue Tracker 讨论的 MCP 服务器”

    • 服务器要能拉到讨论数据（容易）
    • 还要能做总结（需要模型）——出现模型调用的归属问题

  • 方案 A（不理想）：服务器自带 SDK 调模型

    • 问题：客户端选用的模型未知；还要额外交 API Key，安全/成本/隐私都别扭

  • 方案 B：Sampling（采样）原语

    • 含义：服务器向客户端请求一次“补全”（让客户端用其已配置模型来计算）

    • 好处：

      • 安全/隐私/成本全由客户端掌控（沿用现有订阅/Key）
      • 可在多服务器链路里逐层冒泡采样请求，仍保持客户端统一掌控
      • 支持构建更复杂的MCP agent 链式模式

    • 现状：很激动人心但客户端支持最少；官方一方产品会在年内支持

  • Roots 原语

    • 作用：服务器向客户端查询工作空间根目录/打开项目（如 VS Code 中当前打开的项目）
    • 场景：做一个 Git 服务器，需要知道在哪些目录执行命令
    • 现状：VS Code 已支持；命名“起得一般”（作者自嘲）

• **原语小结：**5 个原语、两侧归属

  • 服务器侧：Prompts / Resources / Tools
  • 客户端侧：Sampling / Roots

• 端到端示例：做一个面向聊天应用（Slack/Discord）的 MCP 服务器

  • Prompts：提供“总结这个讨论”“昨天以来有什么新消息”等模板（带参数补全：最近的线程、用户列表…）
  • Resources：列出频道、暴露最近线程给客户端做索引/检索
  • Tools：搜索、读取频道/线程
  • Sampling：对某条线程发起总结（由客户端执行补全） → 组合原语，构造**远超“单纯工具调用”**的体验

• 把 MCP 带到 Web（从本地走向公网）

  • 背景：6–7 个月内社区已构建 ~10,000 个 MCP 服务器，大多是本地体验

  • 方向：MCP Server = 一个网站（客户端直连 Web 端点），不再是本地可执行/Docker

  • 两大前提：授权（Authorization） 与 扩展性（Scaling）

    • 规范最新修订：吸收社区与行业伙伴反馈，完善以上两块

• 授权（Authorization）：OAuth 2.1

  • 目的：把用户的私有上下文/账号资源安全地提供给 LLM 应用；把服务器能力与具体用户身份绑定

  • 规范：OAuth 2.1（本质是 2.0 的安全实践合集；做过 2.0 的基本都在做 2.1 要求）

  • 两种常见部署模式：

    1. 公网/Web 服务器：例如支付商 mcp.payment.com

       • 客户端接入时走 OAuth；用户登录信任的一方（支付商），无需本地陌生镜像
       • 供应方可随时更新服务器，无需用户拉新镜像
       • 现场演示：用 Claude AI Integrations 连接远端并走 OAuth，拿到与用户数据绑定的工具

    2. 企业内网：

       • 部署到公司内网；用 Azure AD / Okta 等 IdP 做 SSO
       • 员工早上登录后，使用任意 MCP 服务器都自动带身份
       • 有利于形成**平台团队（平台/授权/运维）与集成团队（业务工具）**的分工与规模化

• 扩展性（Scaling）：Streamable HTTP

  • 目标：让 MCP 像常规 API 一样可横向扩展

  • 形态：

    • 简单场景：直接返回 JSON（类似 REST）→ 连接即断、易扩展（如无状态函数/Lambda）
    • 复杂场景：开启流式通道（Sampling/通知/多段结果），在最终返回前可多次向客户端发送事件/消息

  • 授权 + 扩展性 = MCP 从本地走向 Web 的地基

• 接下来要做什么（Roadmap / 近中期）

  • 异步任务（Asynchronous tasks）：支持长时运行（分钟→小时）的代理/任务

  • Elicitation（征询）：服务器主动向用户要输入（该能力已进入协议，将在“今天或周一”落地）

  • 官方注册中心（Registry）：集中发现/发布 MCP 服务器；便于代理动态下载/安装/使用

  • 多模态：更好的流式结果与更多模态支持（细节待定）

  • 生态更新：

    • Ruby SDK（Shopify 捐赠，数周内合入）
    • Go SDK（Google Go 团队在做，官方实现）

• 结语

  • 本场旨在让大家用全套原语构建“用户驱动 + 应用驱动 + 模型驱动”的三向交互，并展望 Web 化的 MCP
  • 受限于时间不设 Q&A；可会后交流

Claude Code best practices | Code w/ Claude

• Youtube

• 讲者与背景铺垫

  • 讲者自我介绍：加入 Anthropic 的 Applied AI/产品团队，从大量一线实践中总结 Claude Code 的使用方法。
  • 个人经历：最初周末用 Claude Code 搭笔记应用，被其效率震撼；随后加入团队，专注系统提示、工具描述、评估方案等。

• Claude Code 的心智模型（像“全在终端的同事”）

  • 把 Claude Code 类比为擅长 Bash/Vim/各类 CLI 的同事，随时在终端里帮你排查与改动代码。

• 架构与工作原理（“做简单而有效的事”）

  • 纯代理（pure agent）：给模型一组强大的工具与少量指令，让其循环调用工具直到“任务完成”。
  • 工具层：创建/编辑文件、执行终端命令、调用 MCP 连接的外部能力。
  • 理解代码库的方式：不做全量索引/Embedding/RAG；而是进行Agentic Search（用 grep/find/glob 等逐步探索→读结果→继续搜索），像新同事入项一样学项目。
  • 薄 UI 与权限层：实时可视化“思考/调用”，对“写入/执行”类危险操作弹权限确认，确保人类在环干预。
  • 安全与多云可用性：可直连 Anthropic 或通过 AWS/GCP 等提供方使用模型。

• 典型用例与价值

  • 代码库探索/新人上手：定位功能实现位置、梳理 Git 历史、总结近期改动故事。

  • “思维伙伴”：先让 Claude 搜索与评估实现方案，暂不落地改动，给出 2–3 个选项再定。

  • 写代码：

    • 0→1：空目录起步快速搭应用/原型。
    • 在既有库中工作（团队重点）：补测试极其方便，从而形成更高单测覆盖；完成后自动写 Commit/PR 文案。

  • 部署与自动化：通过 Headless/SDK 融入 CI/CD、GitHub 等流水线。

  • 支持与规模化：更快定位线上错误；大规模迁移/重构（如老 Java→新版、PHP→React/Angular）更可行。

  • 终端场景：熟练运用 Git/Docker/BigQuery 等 CLI；遇到复杂 rebase 也能“托管”给 Claude 处理。

• 最佳实践（一）：CLAUDE.md（核心机制）

  • 作用：在启动时自动注入上下文，承载“对这仓库工作的关键指示”。
  • 放置位置：项目根目录（团队共享）；也可在用户主目录放“全局 CLAUDE.md”。
  • 建议内容：如何运行测试、项目结构速览/模块说明、代码风格/提交规范、内部工具说明等；可逐步积累。

• 最佳实践（二）：权限管理

  • 读操作默认放行；写文件/跑 Bash 等“有副作用”的动作需确认。

  • 提速技巧：

    • Auto-accept（如 Shift+Tab 让其连续工作）；
    • 设置里对常见命令（如 npm run test）总是允许；
    • 也可按会话/项目粒度配置放权。

• 最佳实践（三）：集成方式选择（CLI vs MCP）

  • 有官方/成熟 CLI 工具的服务（如 GitHub gh），优先直接安装 CLI 供 Claude 调用，通常更稳更文档化；
  • 自研或定制能力可通过 MCP 服务器暴露；相关说明可写进 CLAUDE.md。

• 最佳实践（四）：上下文管理

  • 模型支持超长上下文（20 万级 token），长会话仍可能“顶满”。

  • 两个关键命令：

    • /clear：清空历史，从 CLAUDE.md 重新开始；
    • /compact：让 Claude 先总结当前会话（交接给“下一位开发者”），再以摘要继续，保持连续性。

• 最佳实践（五）：高效工作流

  • 先计划再执行：让 Claude 先搜索+给计划，你审核计划后再开工。
  • To-do 清单：大任务会自动拆 To-do；随时按 Esc 打断、修改清单纠偏。
  • “聪明的 vibe coding”：小步快跑 + TDD；频跑测试/类型检查/Lint；勤提交以便回滚。
  • 多模态调试/实现：贴截图/模型图等让 Claude 参照实现 UI/修 Bug。

• 最佳实践（六）：进阶技巧

  • 多实例并行：同时开 2–4 个 Claude 实例并行推进；用终端复用器/多 Tab 协作。
  • Esc 的妙用：工作中随时中断并插话；双击 Esc 可“回溯对话/重置工具扩展”。
  • 工具扩展 & Headless：当 Bash/内置工具不够用时引入 MCP 服务器；在 Headless/CI 场景程序化使用。

• 最新功能与“跟进更新”的建议

  • /model & /config：随时查看/切换当前模型版本。
  • “Think hard/Extended thinking”：从 Claude 4 起，工具调用之间也能进行更长的“思考”，可在复杂排错时开启。
  • IDE 集成：VS Code / JetBrains 插件增强了“当前文件感知”等体验。
  • 关注更新：建议关注 Claude Code GitHub 项目/文档与变更记录，形成每周巡阅节奏。

• Q&A 精要（现场问答）

  • 多个 CLAUDE.md：同级目录不支持多个；子目录中相关的 CLAUDE.md 在搜索到时会被读取；默认仅加载工作目录的那一个；支持在 CLAUDE.md 引用其他文件（@…）以组合常用指令。
  • “不听话”的注释问题：旧模型（如 3.7）易复写“多余注释”；Claude 4 里对“遵循指令”已显著改进，建议升级并整理 CLAUDE.md。
  • 多代理并行/上下文共享：当下主张“单一、能干的编码代理”；若需多代理协作，用共享 Markdown/票据文件在会话间传递状态，未来或考虑更原生支持。

• 延伸参考（文字版最佳实践）

  • Anthropic 官方工程博客 “Claude Code: Best practices for agentic coding”（系统化总结 CLAUDE.md、权限、计划→执行、CI/Headless 等实践）。

Building headless automation with Claude Code | Code w/ Claude

• Youtube

• 主讲：Sedara（Claude Code 团队工程师）

• Claude Code SDK 是什么（定位与价值）

  • 在无界面（headless）模式下以编程方式调用 Claude Code 代理能力

  • 作为新的基础构件/原语，让很多以往做不到的自动化应用成为可能

  • 典型用途：

    • 像 Unix 工具 一样用：可在任意能跑 Bash/终端的地方接入，参与 管道（pipe in / pipe out）与组合
    • 做 CI 自动化：请 Claude 审查代码、甚至编写自定义 Linter
    • 搭建自己的 聊天/助理应用（以 Claude Code 作为大脑）
    • 让 Claude 在远程/隔离环境中写代码

  • 语言绑定：Python / TypeScript SDK（bindings）即将提供

• SDK 基础用法（命令与示例）

  • 直接调用：claude -p "Write me a function to calulate the fibonacci series" --allowedTools "Write"（示例语义）
  • 授权写入：通过参数预先允许“写文件”工具（示例提到 allow tools write），以便落地到文件系统
  • 管道示例：cat app.log | claude -p "Summarize the most common error logs" 让 Claude 总结日志失败点
  • 解析系统命令输出：把 ifconfig 等结果交给 Claude 解释
  • 结构化输出：用 --output-format json 或 --output-format stream-json 返回可解析 JSON，便于下游程序消费

• GitHub Action 现场演示（基于 SDK 构建）

  • 选用一个开源 Quiz App 仓库作 Demo（本地跑 npm start 展示功能）

  • 处理两个 Issue：

    1. Power-ups：新增 “50/50 消除” 与 “免费跳题”，需在配置页可开关，跳题不扣分
    2. 每题计时器：为每道题添加单独倒计时

  • 触发方式：在 Issue 评论里 @claude（如 “please implement this feature”）

  • Action 执行过程可见：

    • Issue 下收到 已开始工作 的机器人评论，并附 Action 运行链接
    • 日志中打印 SDK 的 JSON 输出；自动生成并执行 To-Do 任务清单

  • 同步演示对已有 PR 追加提交：把“背景色改为蓝色”的 PR 改成绿色（新增一个 commit，修改所有相关定义）

  • 结果验证：

    • Action 自动开了实现 Power-ups 的分支/PR；本地切换到该分支启动应用
    • 配置页出现 Power-ups 区块（勾选项）；答题界面出现 50/50 与 Skip 按钮
    • 现场点击 50/50、Skip，功能按预期工作（演示承认还有可优化之处：如标注哪些题用过 Power-up）

• SDK 进阶特性（更细能力）

  • 权限与安全（默认保守）：

    • 默认无编辑/破坏性权限；通过 allowed tools 预授权需要的能力
    • 常见授权组合：bash（如 npm run build、npm test）、write（写文件）；若接入 MCP，可白名单允许特定 MCP 工具

  • 结构化输出模式：

    • json：一次性返回完整 JSON
    • stream-json：边产出边流式返回事件/片段
    • 下游据此解析/编排，构建应用逻辑与 UI

  • 自定义系统提示：例如 --system-prompt "talk like a pirate"（示例强调可玩性）

  • 会话续接与用户交互：

    • 在结构化输出模式下会返回 session_id；保存后可继续同一上下文推进，支持把用户后续反馈接入同一会话

  • 实时权限征询（permission-prompt tool）：

    • 若不想预先枚举授权工具，可把权限决策交给一个 MCP 服务器，由其在运行时向用户弹窗询问是否允许调用某工具（新能力，欢迎反馈）

• GitHub Action 能力回顾

  • 读代码、从 Issue 创建 PR、在已有 PR/分支追加提交
  • 回答问题/解释代码、审查代码
  • 运行于现有 GitHub Runners，零自建基础设施

• Action 的分层实现（开源）

  • 底层：SDK
  • 中间：Base Action（与 Claude Code 通信并回传结果）
  • 上层：PR Action（负责在 PR 上评论/渲染 To-Do/附链接等交互）
  • Base/PR Action 均已开源，可参考源码扩展自定义工作流

• 如何安装 GitHub Action（现场教你配）

  • 在目标仓库目录打开 Claude Code 终端，运行：/install github action
  • 跟随引导完成配置并自动提交一个 YAML PR；合并后配置 API Key 即可使用
  • Bedrock / Vertex 用户：流程略有不同且更手动，需参考对应文档

• 最佳实践/小贴士（贯穿讲解中的建议）

  • 在 CI 中预授权必要命令，保证 Claude 能构建/测试/验证再继续写代码
  • 优先使用结构化输出对接你的脚本与 UI
  • 用 To-Do 清单 与 追加提交实现小步快跑、可回滚
  • Demo 之外仍可继续提升体验（如标注已使用的 Power-up、更多可视化等）

• 资源与反馈

  • 演讲列出：云端开源仓库链接（Base Action / PR Action）、公共 Claude Code 仓库（欢迎提 Issue/反馈）
  • 鼓励大家把 SDK 与 Action 结合自用场景继续扩展

• 收尾

  • 目标达成：展示了 SDK 作为“无头”原语 + GitHub Action 实践，如何把 Claude Code 嵌入管道与 CI，并以最小运维成本获得“写/测/改/审”自动化
  • 致谢与祝福（结束语）