npm package: @moulding-ai/client
Description: 类型安全的 Nexus 客户端 SDK，提供与 AI Agent 交互的完整能力
Latest version: 0.3.0

# @moulding-ai/client

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

## 安装

```bash
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. 解析并持久化新状态

## 使用示例

```typescript
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();
```

## 类型安全示例

```typescript
// ✅ 正确
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. 添加测试

### 测试

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

## Agent 感知实体（perceive）

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

```typescript
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 调用

## 文档

- [使用指南](../SDK_USAGE.md) - 完整的使用文档
- [测试示例](../test-client-sdk.ts) - 端到端测试示例
- [Schema 示例](./client/blueprint-schema.example.ts) - 生成的 schema 示例

## 技术栈

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

## 开发指南

### 本地开发

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

# 安装依赖
pnpm install

# 构建
pnpm build

# 输出在 dist/ 目录
```

### 发布流程

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

1. **创建 changeset**

```bash
pnpm changeset
```

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

2. **提交并推送**

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

3. **自动发布**

GitHub Actions 会自动：

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

详见：[GITHUB_ACTIONS.md](./GITHUB_ACTIONS.md)

### 构建产物

构建后的文件结构：

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

## 许可

MIT