> 作者 @zzzzzzzp（立意 · 判据 · 取舍） · 协作 多多 · AI 助手（检索 · 编码 · 核查）
> 版权 著作权归 @zzzzzzzp 所有（All Rights Reserved） · 版本 v1.3.0
✨ 两个不一样的地方
📈 它会成长 —— 带位次（三阶九位：百工 · 良工 · 营国）。升级不靠买，靠用：
每次真实使用与反馈都折算成经验，推动它升位。
🔁 经验回流 —— 默认不联网：只用一条最小事实（技能名／版本／时间）记在你本机，
不含任何对话内容、不含文件与身份。想让它回传，你在本机配一个收件地址即可；不配就一个字节都不发出。
「他山之石，可以攻玉」——《诗经·小雅·鹤鸣》。
万象-应用后端与用户登录（L0 未习） —— 给应用接上免运维后端：数据库、用户登录、文件存储与免密钥大模型调用。
万象-应用后端与用户登录
何时用
- 用户要给一个应用加上：数据保存、用户账号、文件上传、AI 调用中的任意一项。
- 用户问「后端怎么搭」「能不能存云端」而手上没有服务器。
不适用：纯静态页面（不需要后端就不要引入）；项目自带服务端与数据库；只是读写本机文件。
§0 三条铁律
- 不静默降级。 能力不可用时明说并停下。禁止悄悄换成浏览器本地存储 / 内存数组 / 本地 JSON 文件来「让它看起来能用」—— 那会读起来像需求已满足，而数据根本没被持久化。若本地版本确实有价值，先用一个是/否问题问用户，得到明确同意才做。
- 不发明、不伪造。 不编工具名，不绕过工具直接去戳后端，不假装环境已存在，不给编造的地址或配置。
- 密钥不进代码。 前端代码、仓库文件、日志里都不得出现长期密钥或管理凭证。
> 有一个例外必须认清：当工具明确回报「本次构建不可用，但给出本地实现许可」时，本地兜底是被授权的，此时直接继续、不必再问。区分点在于有无工具的明确许可，不是"我觉得够用了"。
§1 四模块（先判用哪几个）
| 模块 | 能力 | 典型诉求 |
|---|---|---|
| 数据 | 结构化存储与查询（增删改查、条件查询、分页） | 「记下来」「查一下」「台账」 |
| 账号 | 终端用户注册、登录、会话、身份校验 | 「每个人看自己的」 |
| 存储 | 文件上传下载与访问地址（图/音/视频/文档） | 「传图」「附件」 |
| 模型调用 | 免密钥的大模型调用 | 「加个 AI 功能」 |
硬约束：一个应用对应恰好一个环境；环境属于当前应用而非账号；数据不跨应用共享。⇒ 不要试图"复用"别的应用的环境。
§2 激活流程纪律
- 确认由界面驱动，不要自己发问。 激活会弹出授权确认；"要不要开云服务"这个问题不归你问。自己问一遍等于让用户回答两次。
- 意图描述用用户的原话，且回避技术词：说「开支记录」而不是「数据」；禁止出现「数据库」「身份认证」「存储」「云数据库」这类词。
- 最多点两个能力，多说了界面读不懂。
- 应用名自己概括：短、可读、用用户的语言（≤10 字左右），不是目录名、不是会话标题。
- 新建还是复用：会话里已有应用就复用，没有才新建；不要靠目录名或名字相似度去猜该操作哪一个。
§3 应用侧接入纪律
| 纪律 | 说明 |
|---|---|
| 两个公开配置项每次必填 | 初始化时必须同时给到访问地址与公开密钥；每个调用点都要给全，不得只给一个 |
| 不依赖同源回退 | 不要指望 SDK 在缺地址时自动用当前域 —— 发布到别的域就会失败 |
| 不硬编码地址字面量 | 地址来自配置，不写死在代码里 |
| 不从环境变量 / 服务端读地址 | 也不要绕一层服务端转发去拿 |
| 两种接入形态 | 有构建流程的项目用包管理器装；纯静态页面用脚本标签引 CDN；安装失败时退到 CDN 是可接受的 |
| 按需读模块文档 | 写应用代码与维护既有资源是两套文档，别混用；一个任务通常只需要 1–2 份 |
§4 数据安全五条
- 敏感值不打印：终端用户凭证、手机号、邮箱、私有文件地址，都不进日志、不进回复。
- 按用户隔离：任何读写用户数据都必须带身份约束 —— 没有用户可以读写别人的数据。
- 破坏性操作先讲影响面：删表、清数据、批量删文件，先说清影响范围与不可逆性，再动手。
- 不越界：只动当前应用的环境，不读不写别的应用的资源。
- 校验上传：限制类型与大小；不要相信客户端传来的文件名与路径。
§5 本机实测坑
- 能力没接上时最容易出的错是"看起来成功了"：本地兜底、内存数组、mock 数据都能让页面跑起来，但数据一刷新就没 —— 交付前必须真写一条再读回来验证。
- 环境绑定错应用：会话里存在多个应用时，不显式指定就会绑错；显式指定后再核对一次。
- 激活被拒 / 配额用尽：如实告知并给出替代路径，不要说成"已经好了"。
- 不要为了让功能"能用"而绕开身份约束 —— 那是最常见的越权漏洞来源。
- 内部细节不外露：原始后端地址、内部标识都不该出现在给用户的答复里。
- 🔴 应用对接五个坑（2026-09-21 实战 · 两次返工换来，务必先读）：
getSession()返回{ data: session, error }——data本身就是 session（不是data.session）。
取错的表现是登录成功却判定"未登录"⇒ 不跳转、也不报错，极难自查。- 覆盖已有文件必须用
update()：upload()只建新文件，同名报STORAGE_KEY_ALREADY_EXISTS；
upsert: true参数不生效。稳妥写法＝"先update()、失败再upload()"的兜底链，
不要依赖exists()的返回形状（实测其形状与预期不符）。 - 注册链路一次走完：
sendOtp({email})→ 取data.verificationId＋data.isExistingUser
→verifyOtp({verificationId, token, email, isExistingUser, password?})。漏verificationId必失败；
verifyOtp内部即按isExistingUser走/v1/signin或/v1/signup，无需再调signUp()。 - 存储路径固定：
users/<uid>/…仅本人可读写；shared/<ownerUid>/…所有登录用户可读、仅属主可写删。
不暴露公开 URL，存取前必须先过 auth gate。 - 排障手段：页面加一个
?diag=1诊断区（把 SDK／接口状态写进 DOM），
配合msedge --headless --dump-dom <url>?diag=1即可远程验证运行时状态，比读源码可靠。
> 前置铁律：写任何云代码前，读完对应模块的references/<module>/code-generation.md再动手 ——
> 平台文档自己就写着"不要凭记忆写"，本技能两次返工皆因跳过了这一步。
§6 能力边界与反例
能做：四模块选型、环境与应用绑定判据、激活流程纪律、接入配置纪律、数据安全五条、不可用时的诚实处置。
不做：
| 反例 | 正确去处 |
|---|---|
| 悄悄用本地存储冒充持久化 | 明说并停下；要本地兜底先问用户 |
| 自己问用户「要不要开云服务」 | 确认由界面驱动 |
| 把「数据库 / 身份认证 / 存储」写进意图描述 | 用用户原话与非技术词 |
| 编一个环境地址或配置让交付"成功" | 禁止；如实报错 |
| 让前端读服务端转发的地址 | 用公开配置项 |
| 一个新功能顺手读到了别的应用的数据 | 禁止；只动当前应用 |
附 · 来源交代
| 项 | 说明 |
|---|---|
| 版本 | 1.0.0 |
| 建立日期 | 2026-09-19 |
| 来源 | 自研（origin: own）。建立动机：平台内置的云服务系统件覆盖了本域的完整操作面（其正文为英文长文），但①为版本目录结构、随平台升级整体替换，本机经验无处沉淀；②「不静默降级」与「激活确认不归模型问」这两条最容易踩反的纪律，混在大段说明里不便临场取用。故自研一部中文速查版，只吸收模块划分、纪律类别与硬约束，不复制其文本；§5 本机实测坑为自有增量。 |
| 与系统件的关系 | 并存，不替换。系统件仍负责实际的环境生命周期与模块文档；本技能负责选型判据与纪律速查。 |
| 著作权 | 署名 zzzzzzzp，All Rights Reserved |
常见误用与常见问题（FAQ）
常见误用（反模式）
| 误用 | 后果 | 正解 |
|---|---|---|
| 云服务不可用时悄悄换成浏览器本地存储／内存数组／本地 JSON「让它看起来能用」 | 读起来像需求已满足，而数据根本没被持久化 | 不静默降级：能力不可用时明说并停下；若本地版本确有价值，先用一个是/否问题问用户，得到明确同意才做 |
| 自己问用户「要不要开云服务」 | 让用户回答两次 | 确认由界面驱动 —— 激活会弹出授权确认，这个问题不归你问 |
| 意图描述里出现「数据库」「身份认证」「存储」「云数据库」等技术词 | 用户看不懂 | 用用户的原话且回避技术词：说「开支记录」而不是「数据」 |
| 靠目录名或名字相似度猜该操作哪个应用 | 操作错对象 | 会话里已有应用就复用，没有才新建；不要靠名字相似度猜 |
| 试图「复用」别的应用的环境 | 违反硬约束 | 一个应用对应恰好一个环境；环境属于当前应用而非账号；数据不跨应用共享 |
| 只给访问地址、或只给公开密钥 | 初始化失败 | 两个公开配置项每次必填：每个调用点都要给全，不得只给一个 |
| 指望 SDK 在缺地址时自动用当前域 | 不要依赖同源回退 —— 发布到别的域就会失败 | 显式配置地址 |
| 为了让功能「能用」而绕开身份约束 | 最常见的越权漏洞来源 | 不绕 |
| 把长期密钥或管理凭证放进前端代码／仓库文件／日志 | 泄漏 | 密钥不进代码 |
| 相信客户端传来的文件名与路径 | 目录穿越／注入 | 校验类型与大小；不要相信客户端传来的文件名与路径 |
| 编一个环境地址或配置让交付「成功」 | 伪造 | 禁止；如实报错 |
依赖 exists() 的返回形状 |
实测其形状与预期不符 | 不要依赖返回形状 |
| 激活被拒／配额用尽却说成「已经好了」 | 误导 | 如实告知并给出替代路径 |
常见问题
- Q：什么时候不该用本技能？ A：不适用纯静态页面（不需要后端就不要引入）；项目自带服务端与数据库；只是读写本机文件。
- Q：四个模块怎么选？ A：见「§1 四模块（先判用哪几个）」—— 结构化存储与查询／终端用户注册登录与会话身份校验／文件存储与访问地址／免密钥大模型调用。
- Q：激活流程有什么纪律？ A：见「§2 激活流程纪律」。
- Q：数据安全要守哪几条？ A：见「§4 数据安全五条」。
- Q：有哪些本机实测坑？ A：见「§5 本机实测坑」。
触发词与详细说明
（原 description 全文保留在此，供检索与人工查阅；frontmatter.triggers 仍为机器检索用。）
云服务域一站式技能 —— 为应用接入托管的后端能力，免运维、免自建服务器：① 结构化存储与查询（增删改查、条件查询、分页）② 终端用户注册登录与会话身份校验 ③ 文件存储与访问地址（图/音/视频/文档）④ 免密钥大模型调用。含环境生命周期与应用绑定判据（一个应用对应恰好一个环境；新建还是复用已有应用；环境属于应用而非账号，数据不跨应用共享）、激活流程纪律（确认由界面驱动，不要自己发问；意图描述用用户原话且回避技术词、最多点两个能力）、应用侧接入纪律（两个公开配置项每次必填、不得依赖同源回退、不得硬编码地址、不得从环境变量或服务端读取）、数据安全五条（密钥不进代码、敏感值不打印、按用户隔离、破坏性操作先讲影响面、只动当前应用）以及「不可用时不静默降级」的硬规则。当用户要给应用加数据保存、登录、文件上传或 AI 能力，或提到数据库、用户账号、存储、云服务时使用。不适用于：纯静态页面（无需后端）、自带服务端的项目、只做本地文件读写。
