npm run build          # Full build (client + server)
npm run build-client   # Frontend only
npm run build-server   # Backend only

const response = await fetch("/server-function/echo", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ message: "hello" }),
});
const data = await response.json();

// src/server-function/echo.ts
import { Request, Response } from "express";

export default async function handler(req: Request, res: Response) {
  const { message } = req.body;
  res.json({ echo: message });
}

pulse skill create

// src/server-function/my-api.ts
import "dotenv/config";

export default async function handler(req, res) {
  const apiKey = process.env.MY_API_KEY;
  // ...
}

Pulse App 开发者指南

什么是 Pulse App？

Pulse App 是一个模块联邦式、全栈 React 扩展，既可以独立运行，也可以集成到 Pulse Editor 平台中。Pulse Editor 主要作为这些模块化应用的托管环境。

项目结构

my-pulse-app/
├── pulse.config.ts # 应用元数据及 Pulse Editor 配置
├── package.json
├── tsconfig.json
├── src/
│ ├── main.tsx # 前端入口文件（React UI）
│ ├── tailwind.css
│ ├── server-function/ # 后端端点（文件路径 = URL 路径）
│ │ └── echo.ts # → POST /server-function/echo
│ └── skill/ # 代理技能（AI 可调用的操作）
│ └── example-skill/
│ ├── SKILL.md # 技能定义（Anthropic YAML 前置元数据格式）
│ └── action.ts # 操作处理器（默认导出函数）

快速开始

1. 创建新的 Pulse App

bash pulse create

2. 启动开发服务器

bash npm run dev

托管于 http://localhost:3030

在 Pulse Editor → 设置中注册

3. 在浏览器中预览（无编辑器集成）

bash npm run preview

注意：预览模式下模块间通信功能不可用

4. 构建

bash npm run build # 完整构建（客户端 + 服务器） npm run build-client # 仅前端 npm run build-server # 仅后端

---

前端：src/main.tsx

由 Pulse Editor 渲染的单个 React 入口点，作为扩展 UI。使用 Tailwind CSS 进行样式设计。

@pulse-editor/react-api 中的关键钩子

tsx
import { useLoading, useActionEffect } from @pulse-editor/react-api;

// useLoading — 管理加载状态
const { isLoading, setLoading } = useLoading();

// useActionEffect — 为应用操作注册处理器
useActionEffect(mySkillName, {
beforeAction: (input) => {
setLoading(true);
return input; // 可选地转换输入
},
afterAction: (output) => {
setLoading(false);
console.log(操作完成：, output);
},
});

从前端调用服务器函数

tsx const response = await fetch(/server-function/echo, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ message: hello }), }); const data = await response.json();

---

后端：src/server-function/

此目录中的文件会自动映射到 HTTP 端点：

文件路径	端点
src/server-function/echo.ts	POST /server-function/echo
src/server-function/hello/hello-world.ts

POST /server-function/hello/hello-world |

服务器函数示例

ts // src/server-function/echo.ts import { Request, Response } from express;

export default async function handler(req: Request, res: Response) {
const { message } = req.body;
res.json({ echo: message });
}

---

技能：src/skill/

技能是代理能力——可由 AI 代理、通过 useActionEffect 的前端组件或 Pulse Editor 的自动化平台调用的操作。

每个技能位于自己的子目录中，包含两个文件：

SKILL.md — 技能定义（Anthropic YAML 前置元数据格式）

markdown

---

name: mySkill description: 此技能功能的简要描述

---

我的技能

供 AI 代理使用的更详细描述，说明何时以及如何使用此技能。

action.ts — 操作处理器

ts // src/skill/my-skill/action.ts

type Input = {
/ 要处理的主要文本 */
text: string;
/ 可选计数参数 */
count?: number;
};

type Output = {
result: string;
processedCount: number;
};

/
* 默认导出为操作处理器。
* 输入/输出类型 + JSDoc 注释用于 AI 代理文档。
*/
export default function mySkill({ text, count = 1 }: Input): Output {
return {
result: text.repeat(count),
processedCount: count,
};
}

使用 CLI 创建新技能

bash pulse skill create

---

应用配置：pulse.config.ts

ts
import { AppConfig } from @pulse-editor/shared-utils;
import pkg from ./package.json;

const config: AppConfig = {
id: pkg.name, // 必须与包名匹配 — 不能包含连字符
version: pkg.version,
libVersion: pkg.dependencies[@pulse-editor/react-api],
displayName: pkg.displayName,
description: pkg.description,
visibility: unlisted, // 或 public
recommendedHeight: 640,
recommendedWidth: 360,
thumbnail: ./src/assets/thumbnail.png,
};

export default config;

重要提示： id 字段不能包含连字符。请使用下划线或驼峰命名法。

---

关键概念

应用操作

应用操作是 Pulse App 中的主要集成机制。它们：

• - 由技能的 action.ts 默认导出定义
• 可由 AI 代理调用（通过 SKILL.md 定义）
• 可从前端 UI 调用（通过 useActionEffect）
• 可通过专用 API 端点从外部服务调用

beforeAction / afterAction 管道

这些在操作执行周围起到中间件的作用：

• - beforeAction(input) — 在操作之前运行；返回值成为操作的输入（用于 UI 状态设置、输入转换）
• afterAction(output) — 在操作完成后运行（用于 UI 状态清理、处理结果）

---

常见模式

操作周围的加载状态

tsx const { isLoading, setLoading } = useLoading();

useActionEffect(processData, {
beforeAction: (input) => { setLoading(true); return input; },
afterAction: (output) => {
setLoading(false);
setResult(output.result);
},
});

使用环境变量的服务器函数

ts // src/server-function/my-api.ts import dotenv/config;

export default async function handler(req, res) {
const apiKey = process.env.MYAPIKEY;
// ...
}

---

限制

• - 仅支持单个入口点 — 尚不支持多页面应用
• 模块间通信（IMC）功能需要在 Pulse Editor 中运行（npm run dev），预览模式下不可用

---

资源

• - 模板仓库：https://github.com/claypulse/pulse-app-template
• @pulse-editor/react-api — 用于 Pulse Editor 集成的 React 钩子
• @pulse-editor/shared-utils — 共享类型，包括 AppConfig
• Pulse Editor CLI：pulse create、pulse skill create