@chatu-ai/app-sdk 0.9.4 → 0.9.6

package/README.md

@@ -22,6 +22,17 @@ const src = await storage.url('avatars/u1.png', { expiresIn: 3600 })         //
 | `CHATU_DATA_DRIVER=edgeone` (+ optional `CHATU_EDGEONE_KV_STORE` / `CHATU_EDGEONE_STORAGE_STORE`, external access: `EDGEONE_BLOB_PROJECT_ID` + `EDGEONE_BLOB_TOKEN`) | **edgeone** — Tencent EdgeOne Pages Blob for both `kv` (JSON envelope, TTL emulated) and `storage` (presigned PUT via `createUploadUrl`; `storage.url()` returns the in-app proxy path `/_chatu/blob/<key>` served by the template route) | `npm i @edgeone/pages-blob` (preinstalled in the Builder template); credential-free inside Pages Functions. `ai` keeps using `CHATU_DATA_URL` + `CHATU_APP_KEY` |
 | none | **memory** — in-process, lost on restart | local dev / fallback |
 
+### Structured output
+
+```ts
+const data = await ai.json('extract {title, amount} from: ' + text, {
+  schema: z.toJSONSchema(Schema),   // optional, sent to the model
+  validate: v => Schema.parse(v),   // optional; a failure is retried with the error message
+})
+```
+
+`ai.json` forces JSON-only output, strips code fences, parses, validates, and retries once by default.
+
 ## Auth (app users)
 
 `auth` gives the generated app **its own end users** (separate from ChatU platform accounts), scoped per app + environment (`dev`/`prod`). Email code or email + password; sessions are opaque tokens (stored server-side as SHA-256, sliding 30-day expiry). Requires the **platform** driver.
@@ -43,7 +54,7 @@ await auth.users.update(id, { disabled: true })                // also revokes t
 
 In the Next.js template, `@/lib/platform` wraps this in HttpOnly-cookie helpers: `currentUser()`, `requireUser()`, `signInWithCode()`, `endSession()`.
 
-Limits: 10k users per app/env, 200 codes per day, code valid 10 min / 5 tries, 60s per-email resend window.
+Limits: 10k users per app/env, 200 codes and 500 signups per day, code valid 10 min / 5 tries, 60s per-email resend window, password login locks an email for 15 min after 10 consecutive failures.
 
 Billing: every auth call is metered as `auth_ops` (100 calls = 1 point by default) and each **actually sent** verification email as `auth_emails` (1 email = 1 point). Since `getSession()` runs on every request, the platform driver keeps a 30-second in-process session cache — tune it with `CHATU_AUTH_SESSION_CACHE` (seconds, `0` disables) or `configure({ authSessionCacheSeconds })`. The cache is dropped on `signOut()` and on any `users.update()` / `users.delete()`, so disabling a user takes effect within that window.
 
@@ -96,6 +107,6 @@ Never expose `CHATU_APP_KEY` to the browser. MIT.
 
 ## Agent skills
 
-The package ships `skills/chatu-{kv,db,storage,ai,auth}/SKILL.md` — task-focused manuals for coding agents
+The package ships `skills/chatu-{kv,db,storage,ai,auth,validation}/SKILL.md` — task-focused manuals for coding agents
 (standard rules, boilerplate, boundaries, common failure modes). The ChatU Builder sandbox copies them
 into the workspace `.claude/skills/` so Claude Code loads them on demand; they are versioned with the SDK.

package/dist/ai.d.ts

@@ -26,9 +26,25 @@ export interface AiChatResult {
     model?: string;
     usage?: AiUsage;
 }
+/** ai.json 的选项：schema 用于约束模型输出，validate 用于把结果收成业务类型（可直接传 zod 的 parse） */
+export interface AiJsonOptions<T = unknown> extends AiChatOptions {
+    /** JSON Schema（会随提示词发给模型，并尽量用 response_format 约束） */
+    schema?: Record<string, unknown>;
+    /** 期望结构的示例，比 schema 更直观，两者可同时给 */
+    example?: unknown;
+    /** 校验/转换；抛错即视为不合格，会带着错误信息重试（zod: v => Schema.parse(v)） */
+    validate?: (value: unknown) => T;
+    /** 结构不合格时的重试次数，默认 1 */
+    retries?: number;
+}
 export interface AiClient {
     /** 一次性对话，返回完整回复 */
     chat(messages: AiMessage[] | string, opts?: AiChatOptions): Promise<AiChatResult>;
+    /**
+     * 结构化输出：让模型只回 JSON 并解析成对象；给了 validate 则校验不过会带着错误重试。
+     * 用它替代"让模型回一段文本再自己正则抠字段"。
+     */
+    json<T = unknown>(messages: AiMessage[] | string, opts?: AiJsonOptions<T>): Promise<T>;
     /** 流式对话，逐段产出文本增量 */
     stream(messages: AiMessage[] | string, opts?: AiChatOptions): AsyncIterable<string>;
     /** 可用模型 id 列表 */
@@ -36,6 +52,8 @@ export interface AiClient {
 }
 /** 解析 OpenAI 风格 SSE：`data: {...}` 行，`[DONE]` 结束；产出 choices[0].delta.content */
 export declare function parseSseDeltas(body: ReadableStream<Uint8Array>): AsyncGenerator<string>;
+/** 去掉 ```json 代码围栏、取出第一个完整的 JSON 值；模型经常"顺手"包一层 */
+export declare function extractJson(text: string): unknown;
 /** 按当前配置取 AI 客户端（惰性、缓存；configure() 后自动重建） */
 export declare function getAi(): AiClient;
 /** 便捷单例：`import { ai } from '@chatu-ai/app-sdk'` */

package/dist/ai.js

@@ -75,6 +75,57 @@ export async function* parseSseDeltas(body) {
         reader.releaseLock();
     }
 }
+/** 去掉 ```json 代码围栏、取出第一个完整的 JSON 值；模型经常"顺手"包一层 */
+export function extractJson(text) {
+    const trimmed = text.trim().replace(/^```(?:json)?\s*/i, '').replace(/```$/, '').trim();
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        // 前后可能还有说明文字：截取第一个 { 或 [ 到最后一个 } 或 ]
+        const start = trimmed.search(/[[{]/);
+        const end = Math.max(trimmed.lastIndexOf('}'), trimmed.lastIndexOf(']'));
+        if (start >= 0 && end > start) {
+            return JSON.parse(trimmed.slice(start, end + 1));
+        }
+        throw new AppSdkError('AI_INVALID_JSON', `模型返回的不是 JSON：${trimmed.slice(0, 200)}`);
+    }
+}
+/** ai.json 的公共逻辑：约束提示 + response_format + 解析 + 校验 + 带错误重试 */
+async function jsonWithRetry(chat, messages, opts) {
+    const base = toMessages(messages);
+    const instructions = [
+        '只输出 JSON 本身，不要 Markdown 代码块、不要解释文字。',
+        opts?.schema ? `必须满足这个 JSON Schema：\n${JSON.stringify(opts.schema)}` : '',
+        opts?.example !== undefined ? `结构示例：\n${JSON.stringify(opts.example)}` : '',
+    ].filter(Boolean).join('\n');
+    const retries = Math.max(0, opts?.retries ?? 1);
+    let lastError;
+    let repair = '';
+    for (let attempt = 0; attempt <= retries; attempt += 1) {
+        const msgs = [
+            { role: 'system', content: instructions },
+            ...base,
+            ...(repair ? [{ role: 'user', content: `上次输出不合格：${repair}\n请只返回修正后的 JSON。` }] : []),
+        ];
+        const result = await chat(msgs, {
+            ...opts,
+            // json_object 是 OpenAI 兼容端点的通用写法；不支持的模型会忽略，此时靠提示词与解析兜底
+            extra: { response_format: { type: 'json_object' }, ...(opts?.extra ?? {}) },
+        });
+        try {
+            const parsed = extractJson(result.content);
+            return opts?.validate ? opts.validate(parsed) : parsed;
+        }
+        catch (err) {
+            lastError = err;
+            repair = err instanceof Error ? err.message : String(err);
+        }
+    }
+    throw lastError instanceof AppSdkError
+        ? lastError
+        : new AppSdkError('AI_INVALID_JSON', `模型输出结构不符合要求（已重试 ${String(retries)} 次）：${String(lastError)}`);
+}
 // ---------- platform driver ----------
 function platformAi(cfg) {
     const headers = { authorization: `Bearer ${cfg.apiKey}`, 'content-type': 'application/json' };
@@ -95,6 +146,9 @@ function platformAi(cfg) {
                 usage: u ? { promptTokens: u.prompt_tokens, completionTokens: u.completion_tokens, totalTokens: u.total_tokens } : undefined,
             };
         },
+        async json(messages, opts) {
+            return jsonWithRetry((msgs, o) => this.chat(msgs, o), messages, opts);
+        },
         stream(messages, opts) {
             const start = async () => {
                 const res = await cfg.fetchImpl(`${cfg.aiBaseUrl}/chat/completions`, {
@@ -123,6 +177,7 @@ function notConfigured() {
     const fail = () => { throw new AppSdkError('AI_NOT_CONFIGURED', NOT_CONFIGURED); };
     return {
         chat: async () => fail(),
+        json: async () => fail(),
         stream: () => ({ [Symbol.asyncIterator]: async function* () { fail(); } }),
         models: async () => fail(),
     };
@@ -140,6 +195,7 @@ export function getAi() {
 /** 便捷单例：`import { ai } from '@chatu-ai/app-sdk'` */
 export const ai = {
     chat: (m, o) => getAi().chat(m, o),
+    json: (m, o) => getAi().json(m, o),
     stream: (m, o) => getAi().stream(m, o),
     models: () => getAi().models(),
 };

package/dist/ai.test.js

@@ -80,3 +80,45 @@ d('ai without platform config', () => {
         await expect((async () => { for await (const _ of ai.stream('hi')) { /* noop */ } })()).rejects.toMatchObject({ code: 'AI_NOT_CONFIGURED' });
     });
 });
+d('ai.json（结构化输出）', () => {
+    const reply = (content) => new Response(JSON.stringify({ choices: [{ message: { content } }], model: 'm1' }), { status: 200 });
+    it('解析纯 JSON，并带上 response_format 与 schema 提示', async () => {
+        const calls = [];
+        const fetchImpl = (async (_url, init) => {
+            calls.push(JSON.parse(String(init.body)));
+            return reply('{"title":"买牛奶","done":false}');
+        });
+        configure({ driver: 'platform', baseUrl: 'https://api.test/data/v1', apiKey: 'sk-conv-abc', fetchImpl });
+        const schema = { type: 'object', properties: { title: { type: 'string' } } };
+        const out = await ai.json('提取待办', { schema });
+        expect(out).toEqual({ title: '买牛奶', done: false });
+        expect(calls[0].response_format).toEqual({ type: 'json_object' });
+        expect(JSON.stringify(calls[0].messages[0].content)).toContain('JSON Schema');
+    });
+    it('剥掉 ```json 代码围栏与前后废话', async () => {
+        const fetchImpl = (async () => reply('好的，结果如下：\n```json\n{"a":1}\n```'));
+        configure({ driver: 'platform', baseUrl: 'https://api.test/data/v1', apiKey: 'sk-conv-abc', fetchImpl });
+        expect(await ai.json('x')).toEqual({ a: 1 });
+    });
+    it('校验不过会带着错误重试，第二次通过', async () => {
+        let n = 0;
+        const fetchImpl = (async () => {
+            n += 1;
+            return reply(n === 1 ? '{"count":"多"}' : '{"count":3}');
+        });
+        configure({ driver: 'platform', baseUrl: 'https://api.test/data/v1', apiKey: 'sk-conv-abc', fetchImpl });
+        const validate = (v) => {
+            const c = v.count;
+            if (typeof c !== 'number')
+                throw new Error('count 必须是数字');
+            return { count: c };
+        };
+        expect(await ai.json('数一下', { validate })).toEqual({ count: 3 });
+        expect(n).toBe(2);
+    });
+    it('重试用尽仍不合格则抛 AppSdkError', async () => {
+        const fetchImpl = (async () => reply('不是 JSON'));
+        configure({ driver: 'platform', baseUrl: 'https://api.test/data/v1', apiKey: 'sk-conv-abc', fetchImpl });
+        await expect(ai.json('x', { retries: 0 })).rejects.toMatchObject({ code: 'AI_INVALID_JSON' });
+    });
+});

package/dist/index.d.ts

@@ -10,5 +10,6 @@ export type { StorageClient, StorageObject, StorageListResult, UploadUrlResult }
 export { auth, getAuth } from './auth.js';
 export type { AuthClient, AppUser, SignInResult, SendCodeResult, UserListResult, UserPatch } from './auth.js';
 export { ai, getAi } from './ai.js';
-export type { AiClient, AiMessage, AiChatOptions, AiChatResult, AiUsage } from './ai.js';
+export { extractJson } from './ai.js';
+export type { AiClient, AiMessage, AiChatOptions, AiChatResult, AiJsonOptions, AiUsage } from './ai.js';
 export { encodeKvKey, decodeKvKey } from './edgeone.js';

package/dist/index.js

@@ -5,4 +5,5 @@ export { db, getDb, matchesFilter, applySort, queryDocs, newDocId } from './db.j
 export { storage, getStorage } from './storage.js';
 export { auth, getAuth } from './auth.js';
 export { ai, getAi } from './ai.js';
+export { extractJson } from './ai.js';
 export { encodeKvKey, decodeKvKey } from './edgeone.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatu-ai/app-sdk",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "description": "Runtime SDK for apps generated by ChatU Builder: kv, db, storage, auth (app users) and ai (OpenAI-compatible LLM relay) with platform / byo / edgeone / memory drivers selected by environment variables",
   "license": "MIT",
   "type": "module",

package/skills/chatu-ai/SKILL.md

@@ -7,6 +7,27 @@ description: 平台 LLM 中继（@chatu-ai/app-sdk 的 ai）。当应用需要 A
 
 平台托管的 OpenAI 兼容中继：**不需要 API Key、不需要选模型**，用量计入应用所有者的 ChatU 点数。
 
+
+## 结构化输出：`ai.json`
+
+需要"模型返回可直接用的对象"时不要让它回文本再自己抠字段——用 `ai.json`：强制只回 JSON、剥掉代码围栏、解析、可选校验，不合格会带着错误自动重试。
+
+```ts
+import { ai } from '@/lib/platform';
+import { z } from 'zod';
+
+const Result = z.object({ sentiment: z.enum(['正面', '中性', '负面']), reasons: z.array(z.string()).max(3) });
+
+const data = await ai.json(`判断这条评论的情绪：${comment}`, {
+  schema: z.toJSONSchema(Result),   // 告诉模型结构（zod v4）
+  validate: v => Result.parse(v),   // 不合格自动重试（默认 1 次）
+  retries: 2,
+});
+data.sentiment; // 类型安全
+```
+
+不传 `validate` 也能用（只解析不校验），但线上强烈建议配 zod —— 见 `chatu-validation`。
+
 ## API（只能在服务端调用）
 
 ```ts
@@ -77,21 +98,8 @@ for (;;) {
 
 ## 标准写法 C：要结构化结果（JSON）
 
-模型不保证输出合法 JSON——**必须容错**：
-
-```ts
-const { content } = await ai.chat([
-  { role: 'system', content: '抽取信息，只输出 JSON：{"name":string,"amount":number}，不要解释、不要代码块。' },
-  { role: 'user', content: text },
-], { temperature: 0 });
-
-function parseJson<T>(s: string): T | null {
-  const m = s.match(/\{[\s\S]*\}/);            // 容忍模型加了前后缀/代码块
-  try { return m ? (JSON.parse(m[0]) as T) : null; } catch { return null; }
-}
-const data = parseJson<{ name: string; amount: number }>(content);
-if (!data) return Response.json({ error: 'PARSE_FAILED' }, { status: 422 });
-```
+用上面的 `ai.json`，不要自己写"正则抠 JSON + try/catch"那一套（它是本 skill 的旧写法，已被 `ai.json` 取代）。
+只有在需要流式输出结构化内容时才手写解析。
 
 ## 边界与禁忌
 

package/skills/chatu-auth/SKILL.md

@@ -174,7 +174,8 @@ for (const item of items) { const me = await currentUser(); /* … */ }
 - 不要自己生成 JWT、不要把用户信息写进普通 Cookie / localStorage，会话只用 `chatu_session`（HttpOnly）。
 - 不要在客户端组件里 import `@/lib/platform` 的 auth；通过 Server Action 或 Route Handler 拿 `currentUser()` 的结果传下去。
 - 需要登录的页面要么 `await requireUser()`，要么在 Server Action 里再校验一次——只在前端隐藏按钮不算保护。
-- 单应用单环境上限 1 万用户、每日验证码 200 封（超出报 `CODE_QUOTA_EXCEEDED`）；验证码 10 分钟有效、错 5 次作废、同一邮箱 60 秒才能再发一次。
+- 单应用单环境上限 1 万用户、每日验证码 200 封（超出报 `CODE_QUOTA_EXCEEDED`）、每日新注册 500 个（`SIGNUP_QUOTA_EXCEEDED`）；验证码 10 分钟有效、错 5 次作废、同一邮箱 60 秒才能再发一次。
+- 密码登录同一邮箱连续失败 10 次会锁 15 分钟（`TOO_MANY_ATTEMPTS`）——登录页要把这个错误如实告诉用户，并提示"可以改用邮箱验证码登录"。
 - 只有邮箱登录；没有短信、没有微信/GitHub 第三方登录。用户要"手机号登录"时，如实说明当前只支持邮箱。
 
 ## 常见错误
@@ -185,6 +186,8 @@ for (const item of items) { const me = await currentUser(); /* … */ }
 | 登录后刷新又变未登录 | 页面被静态预渲染 | 保留 layout 里的 `export const dynamic = "force-dynamic"` |
 | `EMAIL_NOT_CONFIGURED`（线上） | 平台未配置邮件通道 | 线上改用邮箱密码登录，或让用户联系平台开通 |
 | `CODE_RATE_LIMITED` | 同一邮箱 60 秒内重复发码 | 前端按钮加倒计时 |
+| `TOO_MANY_ATTEMPTS` | 密码连续输错 10 次，已锁定 15 分钟 | 提示改用验证码登录，或等锁定过期 |
+| `SIGNUP_QUOTA_EXCEEDED` | 当日新注册超过 500 | 正常应用不会触发；若被刷可在平台「用户」面板停用异常账号 |
 | `AUTH_UNSUPPORTED` | 应用被部署在没有平台数据服务的驱动上（如 edgeone blob） | 部署时选择带平台数据服务的目标 |
 | `READ_ONLY` / 无法注册新用户 | 应用所有者点数不足，数据已置只读 | 已登录用户仍可访问；充值后自动恢复 |
 | 停用了用户但他还能访问 | 会话缓存最长 30 秒 | 等待缓存过期，或把 `CHATU_AUTH_SESSION_CACHE` 设为 0 |

package/skills/chatu-validation/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: chatu-validation
+description: 用 zod 校验一切来自外部的输入（Server Action 的 FormData、Route Handler 的 JSON body、URL 查询参数、AI 返回的 JSON、第三方接口响应）。当你要写表单提交、API 路由、参数解析或让 AI 输出结构化数据时使用。禁止直接 `as string` / `as any` 把外部输入当成可信数据。
+---
+
+# 输入校验（zod）
+
+模板已预装 `zod`。**凡是从外面来的数据都要先校验再用**——这是线上 500 最常见的来源：`FormData.get()` 返回 `File | string | null`，查询参数永远是字符串，AI 返回的 JSON 字段可能缺失或类型不对。
+
+## 铁律
+
+```ts
+// ❌ 会在线上炸：值可能是 null / File / 空字符串
+const title = formData.get('title') as string;
+const page = Number(searchParams.page);        // NaN
+const data = await res.json() as Todo[];       // 类型是编的
+
+// ✅ 先校验，拿到的就是可信数据
+const { title } = TodoInput.parse(Object.fromEntries(formData));
+```
+
+## Server Action：表单提交
+
+```ts
+// src/lib/schemas.ts
+import { z } from 'zod';
+
+export const TodoInput = z.object({
+  title: z.string().trim().min(1, '标题不能为空').max(100, '标题最多 100 字'),
+  priority: z.coerce.number().int().min(1).max(3).default(2),   // 表单值是字符串 → coerce
+  dueAt: z.coerce.date().optional(),
+  done: z.union([z.literal('on'), z.literal('')]).transform(v => v === 'on').optional(),  // checkbox
+});
+export type TodoInput = z.infer<typeof TodoInput>;
+```
+
+```tsx
+// src/app/page.tsx
+'use server' 的 action 里用 safeParse，把错误回给页面而不是抛 500：
+
+async function create(formData: FormData) {
+  'use server';
+  const parsed = TodoInput.safeParse(Object.fromEntries(formData));
+  if (!parsed.success) {
+    // 用 useActionState 时 return { error }；简单页面可以 redirect 带 ?error=
+    return { error: parsed.error.issues[0]?.message ?? '输入不合法' };
+  }
+  await addTodo(parsed.data);
+  revalidatePath('/');
+  return { ok: true };
+}
+```
+
+## Route Handler：JSON body 与查询参数
+
+```ts
+// src/app/api/todos/route.ts
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+const Query = z.object({
+  page: z.coerce.number().int().min(0).default(0),
+  keyword: z.string().trim().max(50).optional(),
+});
+
+export async function GET(req: Request) {
+  const parsed = Query.safeParse(Object.fromEntries(new URL(req.url).searchParams));
+  if (!parsed.success) {
+    return NextResponse.json({ error: parsed.error.issues[0]?.message }, { status: 400 });
+  }
+  // parsed.data.page 一定是数字
+}
+
+export async function POST(req: Request) {
+  const body = await req.json().catch(() => null);        // 请求体可能不是 JSON
+  const parsed = TodoInput.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json({ error: parsed.error.issues[0]?.message }, { status: 400 });
+  }
+}
+```
+
+## AI 返回的 JSON（配合 `ai.json`）
+
+```ts
+import { ai } from '@/lib/platform';
+import { z } from 'zod';
+
+const Extracted = z.object({
+  title: z.string(),
+  amount: z.number(),
+  tags: z.array(z.string()).max(5).default([]),
+});
+
+const data = await ai.json('从这段文字里抽取标题、金额、标签：' + text, {
+  schema: z.toJSONSchema(Extracted),     // 让模型知道该回什么（zod v4）
+  validate: v => Extracted.parse(v),      // 不合格会自动带着错误重试一次
+});
+// data 已经是 { title: string; amount: number; tags: string[] }
+```
+
+`ai.json` 会：强制只回 JSON → 剥掉代码围栏 → 解析 → 跑 `validate` → 不合格就把错误发回模型重试（默认 1 次）。详见 `chatu-ai`。
+
+## 常用写法速查
+
+| 场景 | 写法 |
+| --- | --- |
+| 表单里的数字/日期 | `z.coerce.number()` / `z.coerce.date()` |
+| 可选但不能是空串 | `z.string().trim().min(1).optional()` |
+| 枚举 | `z.enum(['todo', 'doing', 'done'])` |
+| 邮箱 / URL | `z.email()` / `z.url()` |
+| 数组上限（防刷） | `z.array(Item).max(100)` |
+| 只读用户输入的一部分 | `Schema.pick({ title: true })` |
+| 更新接口（全部可选） | `Schema.partial()` |
+
+## 边界与禁忌
+
+- **不要**把 zod schema 放进 `'use client'` 组件再 import 服务端逻辑；schema 本身可以共享（纯数据），数据库调用不行。
+- 校验失败要**返回可读中文提示**（取 `issues[0].message`），不要把整个 zod 错误对象丢给用户。
+- 服务端永远重新校验一次：前端的 `required`/`pattern` 只是体验，不是安全边界。
+- 涉及"谁的数据"时，校验之外还要做归属检查（见 `chatu-auth` 的越权检查）。
+- 不要为了通过校验而 `z.any()`；宁可先窄后宽。