Pointy Hat 是一个声明式的 AI 工作流自动化框架，允许用户通过 YAML 定义多步骤"咒语"（Spells），内置质量门控（Wards）和参考数据（Catalysts），实现跨任意 LLM 提供商的一键执行。

Pointy Hat：声明式 AI 工作流自动化工具，用 YAML 编排智能代理\n\n## 从"有 AI 工具"到"把事情做成"\n\n当前的人工智能工具生态存在一个明显的断层。一方面，MCP（Model Context Protocol）服务器提供了丰富的功能接口——文件系统访问、网络搜索、数据库查询等；另一方面，用户每次使用这些能力时，都需要从零开始编写提示词，手动编排多步骤流程，然后祈祷输出结果足够好。\n\n这种"每次重新开始"的模式严重制约了 AI 工具的生产力潜能。Pointy Hat 正是为了弥合这一鸿沟而设计的。它的核心理念是：将 AI 能力封装成可复用、可验证、可分享的工作流单元，让用户从"拥有工具"进化到"完成任务"。\n\n## 什么是 Spell（咒语）？\n\n在 Pointy Hat 的术语体系中，Spell 是一个声明式的多步骤 AI 工作流。它通过 YAML 文件完整描述一个任务所需的一切信息：\n\n- 输入（Inputs）：任务需要什么数据或文件\n- 工具（Tools）：需要调用哪些 MCP 服务器功能\n- 步骤（Steps）：执行的具体指令序列，支持依赖关系图\n- 质量门控（Wards）：输出必须满足的质量标准\n- 参考数据（Catalysts）：随 Spell 一起分发的模板、风格指南或数据集\n- 输出（Outputs）：任务最终交付的成果\n\n这种结构化的定义方式彻底改变了与 AI 交互的模式。用户不再需要每次都重新构思提示词，而是直接"施放"一个预先定义好的咒语，由 Pointy Hat 负责协调智能代理完成所有步骤，并独立验证结果质量。\n\n## 核心概念对比\n\nPointy Hat 在 AI 工具生态中占据了一个独特的位置。下表展示了它与传统 MCP 服务器和提示词库的区别：\n\n| 特性 | MCP 服务器 | 提示词库 | Spells |\n|------|-----------|---------|-----------|\n| 分享单元 | 工具（能力） | 单个提示词 | 多步骤工作流 |\n| 质量保证 | 无 | 无 | Wards（质量门控） |\n| 捆绑上下文 | 无 | 无 | Catalysts（参考数据） |\n| 代理集成 | 直接工具安装 | 复制粘贴 | 原生 MCP 服务 |\n| 可组合性 | 无 | 无 | 支持依赖关系的步骤 DAG |\n\n从表中可以看出，Spells 填补了"能力层"和"应用层"之间的空白，提供了一种结构化的方式来封装和复用复杂的 AI 工作流。\n\n## 快速上手\n\nPointy Hat 的使用流程设计得非常直观：\n\n### 第一步：安装代理运行时\n\nPointy Hat 本身不直接执行 AI 任务，而是委托给支持 MCP 协议的自主代理。用户可以选择：\n\nbash\n# 推荐：Claude Code\nnpm install -g @anthropic/claude-code\n\n\nPointy Hat 会自动检测系统中可用的代理运行时。\n\n### 第二步：创建咒语\n\nbash\npointyhat spell create my-review --template code-review\n\n\n这条命令会基于内置模板生成一个 my-review.spell.yaml 文件，包含了代码审查任务所需的完整结构。\n\n### 第三步：施放咒语\n\nbash\npointyhat spell cast my-review --input-file src/main.py\n\n\nPointy Hat 会自动分析所需的输入和工具是否齐全，然后启动代理执行所有步骤，并通过 Wards 验证输出质量。\n\n### 第四步：作为 MCP 服务器运行\n\nbash\npointyhat serve\n\n\n启动后，Pointy Hat 会暴露为一个 MCP 服务器。Claude Code、Cursor 或其他兼容代理可以连接它，发现可用的 Spells，并在需要时调用 Pointy Hat 进行质量评估。\n\n## Spell 格式详解\n\n一个典型的 Spell YAML 文件结构如下：\n\nyaml\nspell:\n name: code-review\n version: 1.0.0\n description: Thorough code review with security analysis\n author: your-name\n tags: [code, review, quality]\n\n # 用户需要提供的输入\n inputs:\n required:\n - id: source-code\n description: The code to review\n formats: [py, ts, js, go, rs]\n\n # 随 Spell 分发的参考数据\n catalysts:\n - id: review-template\n description: Structured review format\n uri: catalyst://code-review/template.md\n type: template\n\n # 需要的 MCP 工具\n requires:\n tools:\n - uri: mcp://filesystem/read_file\n reason: Read source files for analysis\n\n # 执行步骤（支持依赖关系）\n steps:\n - id: analyze\n instruction: >\n Read the source code and identify bugs, security vulnerabilities,\n performance issues, and style inconsistencies.\n inputs_needed: [source-code]\n tools_needed: [read_file]\n\n - id: review\n instruction: >\n Write a detailed review using the template. Be specific — cite\n line numbers, explain why each issue matters, suggest fixes.\n depends_on: [analyze]\n catalysts_needed: [review-template]\n ward:\n criteria: Review must cite specific lines and provide actionable suggestions\n min_score: 0.8\n retry_on_failure: true\n\n # 输出定义\n outputs:\n - id: review\n type: document\n format: [md]\n\n\n这个例子展示了 Spell 的核心特性：\n\n- 声明式结构：所有信息都在 YAML 中明确定义，无需编写代码\n- 依赖管理：review 步骤明确声明依赖 analyze 步骤的输出\n- 质量门控：ward 部分定义了验收标准，未达标时会自动重试\n- 参考数据：catalysts 允许将模板、风格指南等数据与 Spell 一起打包分发\n\n## 术语体系\n\nPointy Hat 使用了一套富有想象力的术语，增强了使用体验的趣味性：\n\n| 术语 | 含义 |\n|------|------|\n| Spell | 声明式的多步骤 AI 工作流 |\n| Inputs | 用户需要提供的输入（文件、数据、参数） |\n| Catalysts | 随 Spell 分发的参考材料（模板、风格指南、数据集） |\n| Steps | 有序的执行指令，支持依赖关系图 |\n| Wards | 质量门控，评估输出并支持失败重试 |\n| Outputs | Spell 产生的成果，包含格式和质量规范 |\n| Casting | 执行 Spell 的过程 |\n| Spellbook | 本地安装的 Spell 集合 |\n| Grimoire | Pointy Hat 官方维护的 Spell 注册中心 |\n\n## 安装方式\n\nPointy Hat 提供多种安装选项：\n\n### 预编译二进制文件（推荐）\n\nbash\n# macOS / Linux\ncurl -fsSL https://raw.githubusercontent.com/Maelhann/pointy-hat/main/scripts/install.sh | bash\n\n\n支持的平台包括：\n- macOS（Apple Silicon arm64、Intel x64）\n- Linux（arm64、x64）\n- Windows（x64）\n\n单二进制文件约 30-50MB，无需额外运行时依赖，无需 Node.js。\n\n### 从源码安装\n\nbash\ngit clone https://github.com/Maelhann/pointy-hat.git\ncd pointy-hat\nnpm install\nnpm run dev -- --help\n\n\n需要 Node.js 20+ 和 npm 10+。构建二进制文件需要 Bun。\n\n## 应用场景\n\nPointy Hat 的设计使其适用于多种 AI 工作流场景：\n\n### 1. 代码审查\n\n通过预定义的代码审查 Spell，团队可以确保每次审查都遵循统一的标准和深度，不会因为审查者的疲劳或经验差异而导致质量波动。\n\n### 2. 文档生成\n\n从代码注释、API 定义或示例代码自动生成文档，通过 Catalysts 注入组织的文档风格指南，确保输出符合品牌规范。\n\n### 3. 数据分析报告\n\n将数据探索、可视化、洞察提取封装成可复用的 Spell，分析师可以一键生成标准化的分析报告。\n\n### 4. 内容创作工作流\n\n从研究、大纲生成、草稿撰写到最终润色，将复杂的内容创作流程分解为可管理的步骤，每个步骤都有明确的质量标准。\n\n## 生态与社区\n\nPointy Hat 正在建设一个开放的 Spell 生态系统：\n\n- Grimoire：官方维护的 Spell 注册中心，用户可以浏览、下载社区贡献的 Spells\n- Spellbook：每个用户的本地 Spell 集合，支持版本管理和依赖追踪\n- Catalyst 共享：参考数据可以独立打包和分享，促进最佳实践的传播\n\n## 结语\n\nPointy Hat 代表了一种新的 AI 工作流编排范式。它不再将 AI 视为一个需要精心哄骗的黑盒，而是将其封装成可预测、可验证、可复用的工作流单元。通过声明式的 YAML 配置、内置的质量门控和与 MCP 生态的无缝集成，Pointy Hat 让"把事情做成"变得像施放一个咒语一样简单。\n\n对于希望将 AI 能力系统化地整合到工作流程中的团队和个人开发者来说，Pointy Hat 提供了一个值得探索的新选择。

Pointy Hat：声明式 AI 工作流自动化工具，用 YAML 编排智能代理\n\n从"有 AI 工具"到"把事情做成"\n\n当前的人工智能工具生态存在一个明显的断层。一方面，MCP（Model Context Protocol）服务器提供了丰富的功能接口——文件系统访问、网络搜索、数据库查询等；另一方面，用户每次使用这些能力时，都需要从零开始编写提示词，手动编排多步骤流程，然后祈祷输出结果足够好。\n\n这种"每次重新开始"的模式严重制约了 AI 工具的生产力潜能。Pointy Hat 正是为了弥合这一鸿沟而设计的。它的核心理念是：将 AI 能力封装成可复用、可验证、可分享的工作流单元，让用户从"拥有工具"进化到"完成任务"。\n\n什么是 Spell（咒语）？\n\n在 Pointy Hat 的术语体系中，Spell 是一个声明式的多步骤 AI 工作流。它通过 YAML 文件完整描述一个任务所需的一切信息：\n\n- 输入（Inputs）：任务需要什么数据或文件\n- 工具（Tools）：需要调用哪些 MCP 服务器功能\n- 步骤（Steps）：执行的具体指令序列，支持依赖关系图\n- 质量门控（Wards）：输出必须满足的质量标准\n- 参考数据（Catalysts）：随 Spell 一起分发的模板、风格指南或数据集\n- 输出（Outputs）：任务最终交付的成果\n\n这种结构化的定义方式彻底改变了与 AI 交互的模式。用户不再需要每次都重新构思提示词，而是直接"施放"一个预先定义好的咒语，由 Pointy Hat 负责协调智能代理完成所有步骤，并独立验证结果质量。\n\n核心概念对比\n\nPointy Hat 在 AI 工具生态中占据了一个独特的位置。下表展示了它与传统 MCP 服务器和提示词库的区别：\n\n| 特性 | MCP 服务器 | 提示词库 | Spells |\n|------|-----------|---------|-----------|\n| 分享单元 | 工具（能力） | 单个提示词 | 多步骤工作流 |\n| 质量保证 | 无 | 无 | Wards（质量门控） |\n| 捆绑上下文 | 无 | 无 | Catalysts（参考数据） |\n| 代理集成 | 直接工具安装 | 复制粘贴 | 原生 MCP 服务 |\n| 可组合性 | 无 | 无 | 支持依赖关系的步骤 DAG |\n\n从表中可以看出，Spells 填补了"能力层"和"应用层"之间的空白，提供了一种结构化的方式来封装和复用复杂的 AI 工作流。\n\n快速上手\n\nPointy Hat 的使用流程设计得非常直观：\n\n第一步：安装代理运行时\n\nPointy Hat 本身不直接执行 AI 任务，而是委托给支持 MCP 协议的自主代理。用户可以选择：\n\nbash\n推荐：Claude Code\nnpm install -g @anthropic/claude-code\n\n\nPointy Hat 会自动检测系统中可用的代理运行时。\n\n第二步：创建咒语\n\nbash\npointyhat spell create my-review --template code-review\n\n\n这条命令会基于内置模板生成一个 my-review.spell.yaml 文件，包含了代码审查任务所需的完整结构。\n\n第三步：施放咒语\n\nbash\npointyhat spell cast my-review --input-file src/main.py\n\n\nPointy Hat 会自动分析所需的输入和工具是否齐全，然后启动代理执行所有步骤，并通过 Wards 验证输出质量。\n\n第四步：作为 MCP 服务器运行\n\nbash\npointyhat serve\n\n\n启动后，Pointy Hat 会暴露为一个 MCP 服务器。Claude Code、Cursor 或其他兼容代理可以连接它，发现可用的 Spells，并在需要时调用 Pointy Hat 进行质量评估。\n\nSpell 格式详解\n\n一个典型的 Spell YAML 文件结构如下：\n\nyaml\nspell:\n name: code-review\n version: 1.0.0\n description: Thorough code review with security analysis\n author: your-name\n tags: [code, review, quality]\n\n 用户需要提供的输入\n inputs:\n required:\n - id: source-code\n description: The code to review\n formats: [py, ts, js, go, rs]\n\n 随 Spell 分发的参考数据\n catalysts:\n - id: review-template\n description: Structured review format\n uri: catalyst://code-review/template.md\n type: template\n\n 需要的 MCP 工具\n requires:\n tools:\n - uri: mcp://filesystem/read_file\n reason: Read source files for analysis\n\n 执行步骤（支持依赖关系）\n steps:\n - id: analyze\n instruction: >\n Read the source code and identify bugs, security vulnerabilities,\n performance issues, and style inconsistencies.\n inputs_needed: [source-code]\n tools_needed: [read_file]\n\n - id: review\n instruction: >\n Write a detailed review using the template. Be specific — cite\n line numbers, explain why each issue matters, suggest fixes.\n depends_on: [analyze]\n catalysts_needed: [review-template]\n ward:\n criteria: Review must cite specific lines and provide actionable suggestions\n min_score: 0.8\n retry_on_failure: true\n\n 输出定义\n outputs:\n - id: review\n type: document\n format: [md]\n\n\n这个例子展示了 Spell 的核心特性：\n\n- 声明式结构：所有信息都在 YAML 中明确定义，无需编写代码\n- 依赖管理：review 步骤明确声明依赖 analyze 步骤的输出\n- 质量门控：ward 部分定义了验收标准，未达标时会自动重试\n- 参考数据：catalysts 允许将模板、风格指南等数据与 Spell 一起打包分发\n\n术语体系\n\nPointy Hat 使用了一套富有想象力的术语，增强了使用体验的趣味性：\n\n| 术语 | 含义 |\n|------|------|\n| Spell | 声明式的多步骤 AI 工作流 |\n| Inputs | 用户需要提供的输入（文件、数据、参数） |\n| Catalysts | 随 Spell 分发的参考材料（模板、风格指南、数据集） |\n| Steps | 有序的执行指令，支持依赖关系图 |\n| Wards | 质量门控，评估输出并支持失败重试 |\n| Outputs | Spell 产生的成果，包含格式和质量规范 |\n| Casting | 执行 Spell 的过程 |\n| Spellbook | 本地安装的 Spell 集合 |\n| Grimoire | Pointy Hat 官方维护的 Spell 注册中心 |\n\n安装方式\n\nPointy Hat 提供多种安装选项：\n\n预编译二进制文件（推荐）\n\nbash\nmacOS / Linux\ncurl -fsSL https://raw.githubusercontent.com/Maelhann/pointy-hat/main/scripts/install.sh | bash\n\n\n支持的平台包括：\n- macOS（Apple Silicon arm64、Intel x64）\n- Linux（arm64、x64）\n- Windows（x64）\n\n单二进制文件约 30-50MB，无需额外运行时依赖，无需 Node.js。\n\n从源码安装\n\nbash\ngit clone https://github.com/Maelhann/pointy-hat.git\ncd pointy-hat\nnpm install\nnpm run dev -- --help\n\n\n需要 Node.js 20+ 和 npm 10+。构建二进制文件需要 Bun。\n\n应用场景\n\nPointy Hat 的设计使其适用于多种 AI 工作流场景：\n\n1. 代码审查\n\n通过预定义的代码审查 Spell，团队可以确保每次审查都遵循统一的标准和深度，不会因为审查者的疲劳或经验差异而导致质量波动。\n\n2. 文档生成\n\n从代码注释、API 定义或示例代码自动生成文档，通过 Catalysts 注入组织的文档风格指南，确保输出符合品牌规范。\n\n3. 数据分析报告\n\n将数据探索、可视化、洞察提取封装成可复用的 Spell，分析师可以一键生成标准化的分析报告。\n\n4. 内容创作工作流\n\n从研究、大纲生成、草稿撰写到最终润色，将复杂的内容创作流程分解为可管理的步骤，每个步骤都有明确的质量标准。\n\n生态与社区\n\nPointy Hat 正在建设一个开放的 Spell 生态系统：\n\n- Grimoire：官方维护的 Spell 注册中心，用户可以浏览、下载社区贡献的 Spells\n- Spellbook：每个用户的本地 Spell 集合，支持版本管理和依赖追踪\n- Catalyst 共享：参考数据可以独立打包和分享，促进最佳实践的传播\n\n结语\n\nPointy Hat 代表了一种新的 AI 工作流编排范式。它不再将 AI 视为一个需要精心哄骗的黑盒，而是将其封装成可预测、可验证、可复用的工作流单元。通过声明式的 YAML 配置、内置的质量门控和与 MCP 生态的无缝集成，Pointy Hat 让"把事情做成"变得像施放一个咒语一样简单。\n\n对于希望将 AI 能力系统化地整合到工作流程中的团队和个人开发者来说，Pointy Hat 提供了一个值得探索的新选择。