@blod-nm/user-kit 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blod-nm/user-kit",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "private": false,
   "type": "module",
   "description": "CloudBase user-center kit: auth (wechat code / unionid / password / sms / email / signup) + crm_user_detail archive on @blod-nm/base-cb.",

package/src/schemas.js

@@ -4,57 +4,72 @@
   职责: 23 条 user-kit 能力的 title / inputSchema / outputSchema / MCP annotations。
         能力实现（auth.js / user.js）只负责 run；约束集中在这里，挂 MCP 时原样透传。
 
-  取用:
-    withSchemas([[key, ability], ...])   // 把元数据合并进能力对象
+  取用: withSchemas([[key, ability], ...])
 
-  约定:
-    · 参数里出现 access_token 的能力 = 用户令牌面（工具调用方负责传）
-    · 输出 schema 只约束我们会稳定返回的字段；网关原样透传类只声明已保证的字段
+  必填约定:
+    · required 列出的字段缺一即 400（实现里已有同名校验）
+    · 二选一用 anyOf（signup: phone_number/email；sendVerification: phone/email）
+    · 可选字段在 description 里写明「可选」
+    · 本地/自定义链路 additionalProperties:false（不接受多余参数）；网关透传类保持开放
 */
 const str = (description, extra = {}) => ({ type: 'string', description, ...extra })
-const obj = (properties = {}, required = []) => ({ type: 'object', properties, ...(required.length ? { required } : {}) })
+const obj = (properties = {}, { required = [], anyOf, additionalProperties = true } = {}) => ({
+  type: 'object',
+  properties,
+  ...(required.length ? { required } : {}),
+  ...(anyOf ? { anyOf } : {}),
+  additionalProperties,
+})
 const tokens = {
-  access_token: str('访问令牌'),
-  refresh_token: str('刷新令牌'),
-  expires_in: { type: 'number', description: '有效期（秒）' },
+  access_token: str('访问令牌（必返）'),
+  refresh_token: str('刷新令牌（必返）'),
+  expires_in: { type: 'number', description: '有效期秒数（必返）' },
 }
-const TOKEN_OUT = { properties: { ...tokens }, required: ['access_token', 'refresh_token', 'expires_in'] }
-const tokenInput = obj({ access_token: str('用户访问令牌（Bearer）') }, ['access_token'])
+const tokenOut = { type: 'object', properties: { ...tokens }, required: ['access_token', 'refresh_token', 'expires_in'] }
+const tokenIn = obj({ access_token: str('用户访问令牌（必填，Bearer）') }, { required: ['access_token'], additionalProperties: false })
 
 export const SCHEMAS = {
-  /* ---------- auth ---------- */
+  /* ---------- auth：自定义登录 ---------- */
   'auth.loginByWxcode': {
     title: '微信小程序登录',
-    inputSchema: obj({ code: str('wx.login 得到的 code') }, ['code']),
-    outputSchema: {
-      type: 'object',
-      properties: { uid: str('唯一用户 id'), openid: str('微信 openid'), unionid: { type: ['string', 'null'] }, ...tokens, config: { type: 'object', description: 'prefix_config' } },
-      required: ['uid', 'openid', 'access_token', 'refresh_token', 'expires_in', 'config'],
-    },
+    inputSchema: obj({ code: str('wx.login 得到的 code（必填）') }, { required: ['code'], additionalProperties: false }),
+    outputSchema: obj({
+      uid: str('唯一用户 id（必返）'),
+      openid: str('微信 openid（必返）'),
+      unionid: { type: ['string', 'null'], description: '微信 unionid，可能为 null（必返）' },
+      ...tokens,
+      config: { type: 'object', description: 'prefix_config（必返，客户端强依赖）' },
+    }, { required: ['uid', 'openid', 'unionid', 'access_token', 'refresh_token', 'expires_in', 'config'], additionalProperties: false }),
     annotations: { openWorldHint: true },
   },
   'auth.loginByUnionid': {
     title: '唯一 id 登录',
-    inputSchema: obj({ unionid: str('调用方唯一用户 id') }, ['unionid']),
-    outputSchema: { type: 'object', properties: { uid: str('唯一用户 id'), unionid: str('唯一用户 id'), ...tokens }, required: ['uid', 'unionid', 'access_token', 'refresh_token', 'expires_in'] },
+    inputSchema: obj({ unionid: str('调用方唯一用户 id（必填）') }, { required: ['unionid'], additionalProperties: false }),
+    outputSchema: obj({
+      uid: str('唯一用户 id（必返）'),
+      unionid: str('唯一用户 id（必返）'),
+      ...tokens,
+    }, { required: ['uid', 'unionid', 'access_token', 'refresh_token', 'expires_in'], additionalProperties: false }),
     annotations: { openWorldHint: true },
   },
+
+  /* ---------- auth：透传登录 ---------- */
   'auth.loginByPassword': {
     title: '账号密码登录',
-    inputSchema: obj({ username: str('用户名'), password: str('密码') }, ['username', 'password']),
-    outputSchema: obj({ uid: str('唯一用户 id'), access_token: str('访问令牌') }, ['uid', 'access_token']),
+    inputSchema: obj({ username: str('用户名（必填）'), password: str('密码（必填）') }, { required: ['username', 'password'] }),
+    outputSchema: obj({ uid: str('唯一用户 id（必返）'), access_token: str('访问令牌（必返）') }, { required: ['uid', 'access_token'] }),
     annotations: { openWorldHint: true },
   },
   'auth.loginBySms': {
     title: '短信验证码登录',
-    inputSchema: obj({ verification_token: str('verifyCode 得到的令牌') }, ['verification_token']),
-    outputSchema: obj({ uid: str('唯一用户 id'), access_token: str('访问令牌') }, ['uid', 'access_token']),
+    inputSchema: obj({ verification_token: str('verifyCode 得到的令牌（必填）') }, { required: ['verification_token'] }),
+    outputSchema: obj({ uid: str('唯一用户 id（必返）'), access_token: str('访问令牌（必返）') }, { required: ['uid', 'access_token'] }),
     annotations: { openWorldHint: true },
   },
   'auth.loginByEmail': {
     title: '邮箱验证码登录',
-    inputSchema: obj({ verification_token: str('verifyCode 得到的令牌') }, ['verification_token']),
-    outputSchema: obj({ uid: str('唯一用户 id'), access_token: str('访问令牌') }, ['uid', 'access_token']),
+    inputSchema: obj({ verification_token: str('verifyCode 得到的令牌（必填）') }, { required: ['verification_token'] }),
+    outputSchema: obj({ uid: str('唯一用户 id（必返）'), access_token: str('访问令牌（必返）') }, { required: ['uid', 'access_token'] }),
     annotations: { openWorldHint: true },
   },
   'auth.signup': {
@@ -62,118 +77,167 @@ export const SCHEMAS = {
     inputSchema: obj({
       phone_number: str('手机号（与 email 二选一）'),
       email: str('邮箱（与 phone_number 二选一）'),
-      verification_token: str('验证码令牌'),
-      username: str('用户名'),
-      password: str('密码'),
-    }, ['verification_token']),
-    outputSchema: obj({ uid: str('唯一用户 id'), access_token: str('访问令牌') }, ['uid', 'access_token']),
+      verification_token: str('验证码令牌（必填）'),
+      username: str('用户名（可选）'),
+      password: str('密码（可选）'),
+    }, {
+      required: ['verification_token'],
+      anyOf: [{ required: ['phone_number'] }, { required: ['email'] }],
+    }),
+    outputSchema: obj({ uid: str('唯一用户 id（必返）'), access_token: str('访问令牌（必返）') }, { required: ['uid', 'access_token'] }),
     annotations: { openWorldHint: true },
   },
+
+  /* ---------- auth：验证码 ---------- */
   'auth.sendVerification': {
     title: '发送验证码',
-    inputSchema: obj({ phone: str('手机号'), email: str('邮箱'), email_redirect_to: str('Magic Link 跳转地址') }),
-    outputSchema: obj({ verification_id: str('验证码会话 id') }, ['verification_id']),
+    inputSchema: obj({
+      phone: str('手机号（与 email 二选一）'),
+      email: str('邮箱（与 phone 二选一）'),
+      email_redirect_to: str('Magic Link 跳转地址（可选，仅邮箱）'),
+    }, { anyOf: [{ required: ['phone'] }, { required: ['email'] }] }),
+    outputSchema: obj({ verification_id: str('验证码会话 id（必返）') }, { required: ['verification_id'] }),
   },
   'auth.sendSmsCode': {
     title: '发送短信验证码',
-    inputSchema: obj({ phone: str('手机号') }, ['phone']),
-    outputSchema: obj({ verification_id: str('验证码会话 id') }, ['verification_id']),
+    inputSchema: obj({ phone: str('手机号（必填）') }, { required: ['phone'], additionalProperties: false }),
+    outputSchema: obj({ verification_id: str('验证码会话 id（必返）') }, { required: ['verification_id'] }),
   },
   'auth.sendEmailCode': {
     title: '发送邮箱验证码',
-    inputSchema: obj({ email: str('邮箱') }, ['email']),
-    outputSchema: obj({ verification_id: str('验证码会话 id') }, ['verification_id']),
+    inputSchema: obj({ email: str('邮箱（必填）') }, { required: ['email'], additionalProperties: false }),
+    outputSchema: obj({ verification_id: str('验证码会话 id（必返）') }, { required: ['verification_id'] }),
   },
   'auth.verifyCode': {
     title: '校验验证码',
-    inputSchema: obj({ verification_id: str('验证码会话 id'), verification_code: str('用户输入的验证码') }, ['verification_id', 'verification_code']),
-    outputSchema: obj({ verification_token: str('验证码令牌') }, ['verification_token']),
+    inputSchema: obj({
+      verification_id: str('验证码会话 id（必填）'),
+      verification_code: str('用户输入的验证码（必填）'),
+    }, { required: ['verification_id', 'verification_code'], additionalProperties: false }),
+    outputSchema: obj({ verification_token: str('验证码令牌（必返）') }, { required: ['verification_token'] }),
   },
+
+  /* ---------- auth：会话 ---------- */
   'auth.reauthenticate': {
     title: '敏感操作二次验证',
-    inputSchema: obj({ access_token: str('用户访问令牌'), verify_opt: { type: 'string', enum: ['phone_code', 'email_code'], description: '验证方式' } }, ['access_token', 'verify_opt']),
-    outputSchema: obj({ verification_id: str('验证码会话 id') }),
+    inputSchema: obj({
+      access_token: str('用户访问令牌（必填）'),
+      verify_opt: { type: 'string', enum: ['phone_code', 'email_code'], description: '验证方式（必填）' },
+    }, { required: ['access_token', 'verify_opt'], additionalProperties: false }),
+    outputSchema: obj({ verification_id: str('验证码会话 id（必返）') }),
   },
   'auth.introspect': {
     title: '校验令牌',
-    inputSchema: tokenInput,
-    outputSchema: obj({ sub: str('用户 id'), active: { type: 'boolean', description: '是否有效' } }),
+    inputSchema: tokenIn,
+    outputSchema: obj({ sub: str('令牌对应的用户 id'), active: { type: 'boolean', description: '是否有效' } }),
     annotations: { readOnlyHint: true, openWorldHint: true },
   },
   'auth.refresh': {
     title: '刷新令牌',
-    inputSchema: obj({ refresh_token: str('刷新令牌') }, ['refresh_token']),
-    outputSchema: { type: 'object', properties: { ...tokens }, required: ['access_token', 'refresh_token', 'expires_in'] },
+    inputSchema: obj({ refresh_token: str('刷新令牌（必填）') }, { required: ['refresh_token'], additionalProperties: false }),
+    outputSchema: tokenOut,
   },
   'auth.signOut': {
     title: '退出登录',
-    inputSchema: tokenInput,
-    outputSchema: { type: 'object' },
+    inputSchema: obj({
+      access_token: str('用户访问令牌（必填）'),
+      client_id: str('客户端 id（可选，默认环境 id）'),
+      x_device_id: str('设备 id（可选）'),
+    }, { required: ['access_token'] }),
+    outputSchema: { type: 'object', description: '网关响应（通常为空对象）' },
     annotations: { destructiveHint: true },
   },
 
-  /* ---------- user ---------- */
+  /* ---------- user：本地档案 ---------- */
   'user.upsert': {
     title: '建档 / 合并档案',
-    inputSchema: obj({ uid: str('唯一用户 id'), profile: obj({}, []) }, ['uid']),
-    outputSchema: obj({ id: str('档案行 id'), data: { type: 'object' } }),
+    inputSchema: obj({
+      uid: str('唯一用户 id（必填，≤128 字符）'),
+      profile: { type: 'object', description: '要合并进档案 profile 段的字段（可选）' },
+      env: str('建档环境标签（可选，缺省 prod）'),
+    }, { required: ['uid'], additionalProperties: false }),
+    outputSchema: obj({ id: str('档案行 id'), data: { type: 'object', description: '档案 data 段' } }, { additionalProperties: false }),
   },
   'user.get': {
     title: '读取档案',
-    inputSchema: obj({ uid: str('唯一用户 id') }, ['uid']),
-    outputSchema: { type: ['object', 'null'], properties: { id: str('档案行 id'), data: { type: 'object' }, status: str('状态'), deleted_at: { type: ['string', 'null'] } } },
+    inputSchema: obj({ uid: str('唯一用户 id（必填）') }, { required: ['uid'], additionalProperties: false }),
+    outputSchema: {
+      type: ['object', 'null'],
+      description: '档案行；不存在时为 null',
+      properties: { id: str('档案行 id'), data: { type: 'object' }, status: str('状态'), deleted_at: { type: ['string', 'null'] } },
+    },
     annotations: { readOnlyHint: true },
   },
   'user.patchProfile': {
     title: '局部更新档案',
-    inputSchema: obj({ uid: str('唯一用户 id'), patch: { type: 'object', description: '要合并进 profile 的字段' } }, ['uid', 'patch']),
-    outputSchema: obj({ section: { type: ['object', 'null'] } }),
+    inputSchema: obj({
+      uid: str('唯一用户 id（必填）'),
+      patch: { type: 'object', description: '要浅合并进 profile 的字段（必填）' },
+    }, { required: ['uid', 'patch'], additionalProperties: false }),
+    outputSchema: obj({ section: { type: ['object', 'null'], description: '合并后的 profile 段' } }),
+  },
+  'user.schemaStatus': {
+    title: '档案表状态',
+    inputSchema: obj({}, { required: [], additionalProperties: false }),
+    outputSchema: obj({
+      table: { type: 'boolean', description: '表是否存在' },
+      primaryKey: { type: 'boolean', description: '主键是否存在' },
+      indexes: { type: 'object', description: '四个索引的存在性' },
+    }, { required: ['table', 'primaryKey', 'indexes'], additionalProperties: false }),
+    annotations: { readOnlyHint: true },
+  },
+  'user.ensureSchema': {
+    title: '初始化档案表',
+    inputSchema: obj({}, { required: [], additionalProperties: false }),
+    outputSchema: obj({
+      table: { type: 'string', enum: ['created', 'exists'], description: '本次建表结果' },
+      indexes: { type: 'object', description: '{ created: string[], existing: string[] }' },
+      status: { type: 'object', description: '执行后的探测结果' },
+    }, { required: ['table', 'indexes', 'status'], additionalProperties: false }),
+    annotations: { readOnlyHint: true, idempotentHint: true },
   },
+
+  /* ---------- user：用户令牌面（网关透传） ---------- */
   'user.me': {
     title: '当前用户',
-    inputSchema: tokenInput,
+    inputSchema: tokenIn,
     outputSchema: { type: 'object', description: '网关用户信息（原样）' },
     annotations: { readOnlyHint: true },
   },
   'user.updateBasic': {
     title: '修改资料（含手机号/邮箱）',
     inputSchema: obj({
-      access_token: str('用户访问令牌'),
-      nickname: str('昵称'),
-      username: str('用户名'),
-      phone: str('手机号'),
-      email: str('邮箱'),
-      avatar_url: str('头像 URL'),
-      gender: { type: 'string', enum: ['MALE', 'FEMALE'], description: '性别' },
-      description: str('个人简介'),
-      verification_token: str('手机号/邮箱变更所需验证码令牌'),
-    }, ['access_token']),
+      access_token: str('用户访问令牌（必填）'),
+      nickname: str('昵称（可选）'),
+      username: str('用户名（可选）'),
+      phone: str('手机号（可选，修改需验证码）'),
+      email: str('邮箱（可选，修改需验证码）'),
+      avatar_url: str('头像 URL（可选）'),
+      gender: { type: 'string', enum: ['MALE', 'FEMALE'], description: '性别（可选）' },
+      description: str('个人简介（可选）'),
+      verification_token: str('手机号/邮箱变更的验证码令牌（可选，改手机/邮箱时需要）'),
+    }, { required: ['access_token'] }),
     outputSchema: { type: 'object', description: '网关响应（原样）' },
   },
   'user.changePassword': {
     title: '修改密码',
-    inputSchema: obj({ access_token: str('用户访问令牌'), password: str('新密码'), verification_token: str('二次验证令牌') }, ['access_token']),
-    outputSchema: { type: 'object' },
+    inputSchema: obj({
+      access_token: str('用户访问令牌（必填）'),
+      password: str('新密码（必填）'),
+      verification_token: str('二次验证令牌（可选，按网关要求）'),
+    }, { required: ['access_token', 'password'] }),
+    outputSchema: { type: 'object', description: '网关响应（通常为空对象）' },
     annotations: { destructiveHint: true },
   },
   'user.deleteMe': {
     title: '注销账号',
-    inputSchema: obj({ access_token: str('用户访问令牌'), verification_token: str('二次验证令牌') }, ['access_token']),
-    outputSchema: { type: 'object' },
+    inputSchema: obj({
+      access_token: str('用户访问令牌（必填）'),
+      verification_token: str('二次验证令牌（可选，按网关要求）'),
+    }, { required: ['access_token'] }),
+    outputSchema: { type: 'object', description: '网关响应（通常为空对象）' },
     annotations: { destructiveHint: true },
   },
-  'user.schemaStatus': {
-    title: '档案表状态',
-    inputSchema: obj(),
-    outputSchema: obj({ table: { type: 'boolean' }, primaryKey: { type: 'boolean' }, indexes: { type: 'object', description: '四个索引的存在性' } }, ['table', 'indexes']),
-    annotations: { readOnlyHint: true },
-  },
-  'user.ensureSchema': {
-    title: '初始化档案表',
-    inputSchema: obj(),
-    outputSchema: obj({ table: { type: 'string', enum: ['created', 'exists'] }, indexes: { type: 'object' }, status: { type: 'object' } }, ['table']),
-    annotations: { readOnlyHint: true, idempotentHint: true },
-  },
 }
 
 /** 把元数据合并进 [key, ability] 列表（能力对象原样保留 describe/run） */