@moulding-ai/client

基于 Blueprint 的类型安全客户端 SDK，提供与 AI Agent 交互的完整能力。

安装

pnpm add @moulding-ai/client
# 或
npm install @moulding-ai/client
# 或
yarn add @moulding-ai/client

特性

• ✅ 完整的类型安全：通过 TypeScript 泛型和类型推导，提供编译时类型检查
• ✅ 运行时元数据：Schema 同时包含类型定义和运行时数据（prompt 模板等）
• ✅ 自动状态管理：透明的状态更新流程，无需手动干预
• ✅ Action & Prompt：支持结构化 action 调用和自由 prompt 对话
• ✅ 代码生成工具：前端 UI 组件自动生成 schema 代码

架构

sdk/client/
├── types.ts           # 核心类型定义
├── api.ts             # API 客户端层
├── state-updater.ts   # 状态更新逻辑
├── agent.ts           # NexusAgent 类
├── nexus.ts           # Nexus 主类
├── index.ts           # 导出文件
└── blueprint-schema.example.ts  # 示例 schema

lib/
└── blueprint-schema-codegen.ts  # Schema 代码生成器

components/app/
└── BlueprintSchemaGenerator.tsx # Schema 生成器 UI

pages/api/contexts/[contextId]/
└── update-state.ts    # State updater API 端点

核心概念

1. Blueprint Schema

Blueprint Schema 是客户端 SDK 的核心，它包含：

• 类型定义：通过 as const 和 typeof 实现精确的类型推导
• 运行时元数据：Action 的 prompt 模板、参数列表等

生成方式：

• 访问应用详情页
• 使用 BlueprintSchemaGenerator 组件
• 复制生成的代码

2. Nexus 类

主入口类，负责：

• 管理全局配置（baseUrl、apiKey、contextId）
• 创建和缓存 Agent 实例
• 提供类型安全的 getAgent() 方法

3. NexusAgent 类

Agent 实例类，提供：

• action() - 执行结构化 action 调用
• prompt() - 自由文本对话
• perceive() - 感知一个实体（将实体纳入后续推理/行动）
• getState() / setState() - 状态管理
• getMessages() - 消息历史

4. State Updater

自动状态更新流程：

1. Agent 生成回复
2. 自动调用 state updater agent
3. 解析并持久化新状态

使用示例

import { Nexus } from '@moulding-ai/client';
import { blueprintSchema } from './blueprint-schema';

// 1. 创建 Nexus 实例
const nexus = new Nexus(blueprintSchema, {
  baseUrl: 'http://localhost:4111', // Mastra 服务器地址
  apiKey: 'your-api-key',
  contextId: 'ctx_xxx',
});

// 2. 获取 Agent（类型安全）
const agent = nexus.getAgent('PM-Bot');

// 3. 调用 Action
const response = await agent.action('process_group_intent', {
  params: {
    message: '创建任务',
    groupId: 'g1',
  },
  ambients: {
    current_time: new Date().toISOString(),
  },
});

console.log(response.text);
if (response.state) {
  console.log('状态已更新:', response.state);
}

// 4. 自由对话
const response2 = await agent.prompt('你好！');
console.log(response2.text);

// 5. 状态管理
const state = await agent.getState();
await agent.setState({ intention: 'new_task' });
await agent.resetState();

// 6. 消息历史
const messages = await agent.getMessages();

类型安全示例

// ✅ 正确
const agent = nexus.getAgent('PM-Bot');
await agent.action('process_group_intent', {
  params: { message: 'hello', groupId: 'g1' },
});

// ❌ 类型错误：Agent 不存在
const agent = nexus.getAgent('NonExistent');

// ❌ 类型错误：Action 不存在
await agent.action('nonExistent', { params: {} });

// ❌ 类型错误：缺少必需参数
await agent.action('process_group_intent', {
  params: { message: 'hello' }, // 缺少 groupId
});

API 端点

SDK 与以下 API 端点交互（通过 Mastra 服务器）：

• GET /v1/contexts/[contextId]/state - 获取状态
• PUT /v1/contexts/[contextId]/state - 更新状态
• POST /v1/contexts/[contextId]/state - 重置状态
• GET /v1/contexts/[contextId]/messages - 获取消息
• POST /api/agents/stateUpdaterAgent/stream - State updater (Mastra Agent API)

开发指南

添加新功能

1. 更新类型定义（types.ts）
2. 实现功能逻辑（相应的类文件）
3. 更新主导出（index.ts）
4. 添加测试

测试

# 运行测试
npx tsx test-client-sdk.ts

Agent 感知实体（perceive）

当你希望让某个 Agent 感知（注意到）一个实体并在后续推理/行动中考虑该实体，可以使用 perceive：

import { Nexus } from '@moulding-ai/client';
import { blueprintSchema } from './blueprint-schema';

const nexus = new Nexus(blueprintSchema, {
  baseUrl: 'http://localhost:4111',
  apiKey: 'your-api-key',
});

const agent = await nexus.createAgentContext('鲁滨逊');
const door = await nexus.createEntityContext('门');

// description 可选；用于“感知情景”描述（实体描述来自 schema）
const res = await agent.perceive(door, {
  description: '木门，刚被关闭，门把手温热',
});

await res.processDataStream({
  onChunk: async (chunk) => {
    if (chunk.type === 'text-delta' && chunk.payload?.text) {
      process.stdout.write(chunk.payload.text);
    }
  },
});

生成 Schema

1. 确保有激活的 blueprint
2. 访问应用详情页
3. 使用 BlueprintSchemaGenerator 组件
4. 复制或下载生成的代码

最佳实践

1. Schema 管理

   • 每次更新 blueprint 后重新生成 schema
   • 使用版本控制管理 schema 文件
   • 在 CI/CD 中自动化生成

2. 实例复用

   • 复用 Nexus 和 Agent 实例
   • Agent 实例会被自动缓存
   • 避免频繁创建新实例

3. 错误处理

   • 使用 try-catch 捕获 API 错误
   • 检查 NexusAPIError 类型
   • 记录详细的错误信息

4. 安全性

   • 不要在客户端硬编码 API Key
   • 使用环境变量
   • 在服务端代理 API 调用

文档

• 使用指南 - 完整的使用文档
• 测试示例 - 端到端测试示例
• Schema 示例 - 生成的 schema 示例

技术栈

• TypeScript 5.8+
• Fetch API
• ESM 模块格式

开发指南

本地开发

# 克隆仓库
git clone https://github.com/yourusername/mould-ai.git
cd mould-ai/sdk

# 安装依赖
pnpm install

# 构建
pnpm build

# 输出在 dist/ 目录

发布流程

本项目使用 GitHub Actions 自动化发布，避免本地构建污染源代码目录。

1. 创建 changeset

pnpm changeset

选择版本类型（major/minor/patch）并描述变更内容。

2. 提交并推送

git add .changeset/*.md
git commit -m "chore: add changeset"
git push origin main

3. 自动发布

GitHub Actions 会自动：

• 创建 Release PR
• 合并后构建并发布到 npm

详见：GITHUB_ACTIONS.md

构建产物

构建后的文件结构：

dist/
├── index.js         # ESM 入口
├── index.js.map     # Source map
├── index.d.ts       # 类型声明
└── index.d.ts.map   # 类型声明 source map

许可

MIT