跳到主要内容

Studio 本地开发:Hello 当前登录用户

使用 Soln SDK 制作显示 Hello, 当前登录用户名称 的页面。从本地创建文件夹开始,完成真实租户数据查询、本地预览、保存源码和发布。线上 AI 助手可通过 system.help.search 和 system.help.read 检索本文,docId 为 integration/studio-local-development。

身份与执行链路​

浏览器通过 @soln/studio 的 callAction('getCurrentUser', {}) 调用已声明的服务端动作。动作参数为 (payload, context),使用 SDK 的 await context.member.current() 查询当前用户。返回值是 { data: Record<string, unknown> } 或 null;内置成员姓名字段是 data.so_name,不是顶层 name。示例校验姓名后只向页面返回 { name },不返回邮箱等无关资料,不写死用户名,不接受页面传入的成员 ID 作为当前身份依据。

运行 sl studio dev 时,使用 CLI 当前登录成员。线上编辑器预览和挂载页面使用 实际调用页面动作的成员。两种环境均由 Runtime 执行权限检查和租户隔离。例如 demo 租户中以名称为 One 的成员登录后,显示 Hello, One;One 仅为示例结果,不会写入源码。

AI 执行链路为 CLI/Runtime 命令:SL_COMMANDS → 严格输入 Schema → executeSlCommand → Runtime 领域 repository → 租户数据库,不经过旧 MCP 工具。浏览器只能调用页面声明的动作。线上助手可通过 Studio workspace 命令编写同样的文件;本地创建目录和运行 sl studio dev 需要在开发者电脑上进行。

从本地创建文件夹​

先安装 Soln CLI 并登录目标租户,参见 CLI。用 sl whoami --json 确认账号和租户。连接的 Runtime 需要支持 system.studio.draft.preview 和 system.studio.draft.execute,本地预览需要 Studio 订阅权益和 Studio 资源管理权限。

mkdir studio-projects
cd studio-projects
sl studio init page --dir ./hello-member --code hello-member --name "Hello Member"
cd hello-member
mkdir -p src/server

保留生成的 package.json、tsconfig.json 和 src/soln-studio.d.ts。如需本地编辑器补全和类型检查,运行 npm install。Runtime 编译时提供支持的浏览器依赖,无需上传 node_modules 或 Vite 构建产物;浏览器依赖受 Studio 包白名单限制。服务端动作运行在租户 Runtime,不运行在本地 Node 服务中。

Hello 示例源码​

替换 manifest 并添加以下文件。已有项目请保留实际 assetId、code、其他文件及无关配置,将动作加入 settings.serverActions,不要覆盖其他动作。

soln.extension.json​

{
"schemaVersion": 1,
"code": "hello-member",
"name": "Hello Member",
"assetType": "page",
"runtimeType": "client_page",
"entryFilePath": "src/App.tsx",
"settings": {
"extensionPoints": [],
"permissions": [],
"serverActions": [
{ "name": "getCurrentUser", "entryFilePath": "src/server/get-current-user.ts" }
]
}
}

src/shared.ts​

export type CurrentUser = { name: string };

src/server/get-current-user.ts​

import type { CurrentUser } from '../shared';

type Context = {
member: {
current(): Promise<{ data: Record<string, unknown> } | null>;
};
};

export default async function getCurrentUser(
_payload: unknown,
context: Context,
): Promise<CurrentUser> {
const member = await context.member.current();
if (!member) throw new Error('CURRENT_MEMBER_REQUIRED');
const name = member.data.so_name;
if (typeof name !== 'string' || !name.trim()) {
throw new Error('CURRENT_MEMBER_NAME_REQUIRED');
}
return { name: name.trim() };
}

src/i18n.ts​

const en = {
title: 'Hello',
greeting: 'Hello, {name}',
loading: 'Loading current user…',
error: 'Unable to load the current user. Check your sign-in and permissions.',
};

const messages: Record<string, typeof en> = {
en,
'zh-CN': {
title: 'Hello',
greeting: 'Hello, {name}',
loading: '正在读取当前用户…',
error: '无法读取当前用户,请检查登录状态和权限。',
},
};

export function getMessages(locale: string) {
return messages[locale] ?? en;
}

src/App.tsx​

import { useEffect, useState } from 'react';
import { callAction, useLocale } from '@soln/studio';
import { getMessages } from './i18n';
import type { CurrentUser } from './shared';

export default function App() {
const text = getMessages(useLocale());
const [user, setUser] = useState<CurrentUser | null>(null);
const [failed, setFailed] = useState(false);

useEffect(() => {
let active = true;
callAction<Record<string, never>, CurrentUser>('getCurrentUser', {}).then(
value => { if (active) setUser(value); },
() => { if (active) setFailed(true); },
);
return () => { active = false; };
}, []);

return (
<p
role={failed ? 'alert' : 'status'}
style={{
display: 'grid', placeItems: 'center', minHeight: '100dvh', margin: 0,
fontFamily: 'system-ui, sans-serif', fontSize: 32, lineHeight: 1.5,
textAlign: 'center',
}}
>
{failed ? text.error : user ? text.greeting.replace('{name}', user.name) : text.loading}
</p>
);
}

启动本地预览​

sl studio deploy --dir . --json
sl studio dev --dir . --port 5173 --locale zh-CN

首次 deploy 创建并编译租户侧的未发布草稿,将资源 ID 写回本地 manifest。本地开发无需发布。打开 dev 输出的回环地址,页面应显示 Hello, <当前成员名称>。修改并保存本地源码后,连接的 Runtime 自动重新编译并刷新页面。编译失败时,旧快照的动作被阻止。更换 CLI 账号、租户或 Runtime 地址后,需要重启 dev。

dev 不保存源码、不发布版本;动作访问的仍是 真实租户数据,SDK 写操作会真实生效。令牌保留在本地 CLI 进程。桥接仅监听 127.0.0.1,校验 Host/Origin,使用随机会话地址,不暴露数据库凭证、任意 SQL 或任意命令/API 代理。每次动作输入上限 1 MiB,最多并发八次动作;快照允许 199 个项目源码文件,加一份生成的 manifest。

本地预览支持 callAction、语言和运行时上下文,主题为 null。账号、密码、个性化、设备定位、表单容器 effects 需要线上宿主,在本地会明确拒绝。服务端 SDK 仍遵循连接的 Runtime 的方法、权限和对外 HTTP 限制,参见 Soln SDK。

保存源码与发布​

按 Ctrl+C 停止 dev,保存完成后的源码:

sl studio deploy --dir . --json

Deploy 保存并编译草稿,不会自动发布。确定要发布时再执行:

sl studio publish --dir . --json

以目标成员身份登录并测试挂载后的线上页面,Hello 读取的是该线上成员,可以与 CLI 成员不同。发布本身不配置访客路由,也不会替换内置首页。

线上助手使用指引​

回答本地开发问题前先检索并读取本文。用户要求线上编写时,读取真实资源和当前 workspace,添加 manifest 动作及源码后编译,按请求保存和发布。不应声称已经在开发者电脑上执行命令,也不能仅凭编译成功宣称 SDK 查询成功;报告姓名查询可用之前,应验证实际调用者的动作返回值。

将已发布页面用作成员首页​

发布只生成可运行的 Studio 版本,不会自动分配给用户。进入 集成 → 页面,创建配置、选择已发布资产和适用范围,再启用配置,参见 自定义页面。初始管理员始终排除,请使用适用范围内的非初始管理员账号检查效果。