用途
Astro Actions 用于在 Astro 项目中处理表单提交、数据变更（mutations）以及服务器端逻辑，并提供类型安全保障。它通过 defineAction 与 astro:actions 模块，将请求、验证与响应边界统一管理，替代传统 API 端点样板代码。
主要能力
- defineAction()：类型安全的服务器函数定义。
- Zod 验证：自动解析 JSON 与 FormData。
- ActionError：标准化错误码与消息。
- accept: 'form'：直接支持 HTML 表单提交。
- 渐进增强：表单在未启用 JavaScript 时仍可工作。
- astro:actions：客户端导入，支持类型安全调用。
核心概念
Action 结构
所有 action 位于 src/actions/index.ts，并导出 server 对象：
// src/actions/index.ts
import { defineAction } from 'astro:actions';
import { z } from 'astro/zod';
export const server = {
myAction: defineAction({ /* ... */ })
}
接受模式（Accept Modes）
| 模式 | 说明 |
|---|---|
| accept: 'json'（默认） | 解析 JSON 请求体 |
| accept: 'form' | 直接解析 HTML FormData |
错误码
标准 HTTP 对齐错误码：UNAUTHORIZED、FORBIDDEN、NOT_FOUND、BAD_REQUEST、INTERNAL_SERVER_ERROR、CONFLICT、TOO_MANY_REQUESTS。
使用方式
何时使用
- 处理带服务器端验证的表单提交
- 创建类型安全的后端变更，无需 API 样板代码
- 构建渐进增强（无 JS 也可工作）
- 替代 API 端点进行客户端-服务器通信
参考指南
| 需求 | 参考 |
|---|---|
| 概念与架构 | overview.md |
| defineAction 模式 | defining-actions.md |
| ActionError 处理 | error-handling.md |
| HTML 表单集成 | forms.md |
| 渐进增强 | progressive-enhancement.md |
| 联系表单模板 | templates/contact-form.md |
| JSON action 模板 | templates/json-action.md |
最佳实践
- 始终定义输入 schema——不要跳过 Zod 验证
- 对已知错误使用 ActionError——标准化错误码便于客户端处理
- HTML 表单使用 accept: 'form'——原生表单提交支持
- 渐进增强——表单无 JS 可工作，有 JS 时增强
- 检查 ctx.cookies 进行鉴权——未登录时抛出 UNAUTHORIZED
适用场景
适用于需要在 Astro 中实现类型安全服务器函数、表单处理、数据变更、渐进增强表单以及替代 API 端点的项目。
限制
该技能不深入覆盖 Astro DB 集成（由 astro-db 处理数据库层），也不覆盖 Content Layer schema（astro-content），其重点在于请求、验证与响应边界。
Agent 工作流（强制）
在任何实现之前，需并行启动 3 个 agent，每个 Agent 调用带一个名称：
- fuse-ai-pilot:explore-codebase - 检查 src/actions/ 中现有 actions
- fuse-ai-pilot:research-expert - 通过 Context7/Exa 验证最新 Actions 文档
- mcp__context7__query-docs - 获取 defineAction 与 ActionError 示例
实现之后，运行 fuse-ai-pilot:sniper 进行验证。