@h-ai/cli 0.1.0-alpha.61 → 0.1.0-alpha.63

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "0.1.0-alpha.61",
+  "version": "0.1.0-alpha.63",
   "description": "Hai Framework CLI for project scaffolding and code generation.",
   "license": "Apache-2.0",
   "keywords": [
@@ -30,7 +30,7 @@
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "dependencies": {
-    "@h-ai/core": "0.1.0-alpha.61",
+    "@h-ai/core": "0.1.0-alpha.63",
     "cac": "^7.0.1",
     "chalk": "^6.0.1",
     "fast-wrap-ansi": "^0.2.2",
@@ -41,11 +41,11 @@
     "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@h-ai/cache": "0.1.0-alpha.61",
-    "@h-ai/deploy": "0.1.0-alpha.61",
-    "@h-ai/reach": "0.1.0-alpha.61",
-    "@h-ai/reldb": "0.1.0-alpha.61",
-    "@h-ai/storage": "0.1.0-alpha.61",
+    "@h-ai/cache": "0.1.0-alpha.63",
+    "@h-ai/deploy": "0.1.0-alpha.63",
+    "@h-ai/reach": "0.1.0-alpha.63",
+    "@h-ai/reldb": "0.1.0-alpha.63",
+    "@h-ai/storage": "0.1.0-alpha.63",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^26.6.5",
     "@types/prompts": "^2.4.9",

package/templates/README.md

@@ -57,7 +57,7 @@ templates/
 │       └── settings.json    # Paraglide 项目配置
 │
 └── skills/                  # AI Skill 与各 appType 桥接指引
-    └── bridges/             # admin / api / website / h5 / mobile-app / fullstack 专属 AGENTS/Copilot
+    └── bridges/             # admin / api / website / h5 / mobile-app / fullstack 专属 AGENTS
 ```
 
 ## AI Skill 模板（Single Source of Truth）
@@ -65,11 +65,12 @@ templates/
 `templates/skills/` 是 CLI 生成共享 AI 上下文时的单一来源，同时用于 `hai create` 与 `hai add`。
 
 - `hai create` 会把 `templates/skills/` 下所有 `hai-*` Skill 目录复制到 `.agents/skills/<skill>/`，再按 appType 排除互斥项（例如 fullstack 不复制 `hai-kit`；admin / website / h5 不复制 `hai-serv`、`hai-api-contract`、`hai-api-client`、`hai-capacitor`；mobile-app 不复制 `hai-core`、`hai-kit`、`hai-serv`、`hai-api-contract`）
-- `bridges/<appType>/copilot-instructions.md` 会复制到 `.github/copilot-instructions.md`；没有专属文件时回退到通用桥接文件
+- 通用 `copilot-instructions.md` 复制到 `.github/copilot-instructions.md`，只引用项目根 `AGENTS.md`，不另维护 appType 专属规则
 - `bridges/<appType>/AGENTS.md` 会复制到项目根目录，确保不同样板工程使用自己的 AI 指引；通用 `CLAUDE.md` 仅包含 `@AGENTS.md`
 - `opencode.json` 会复制到项目根目录
-- `templates/skills/AGENTS.md`、`CLAUDE.md`、`copilot-instructions.md` 与 `opencode.json` 不是多余副本：它们是 generic fallback，主要服务于缺少 appType 上下文时的桥接复制与 `hai add` 回填 AI 支持
-- `opencode.json` 使用 OpenCode 的 `instructions` 配置复用 `.github/copilot-instructions.md`；`.agents/skills/` 由 OpenCode 原生发现，不再写入过期的 `skills.paths`
+- `templates/skills/AGENTS.md` 是缺少 appType 上下文时的通用规则；`CLAUDE.md`、`copilot-instructions.md` 与 `opencode.json` 是各工具的轻量入口，用于创建项目和回填 AI 支持
+- Codex 原生读取根 `AGENTS.md` 并发现 `.agents/skills/`，支持 `$hai-app-create` 等显式调用和按任务自动选择；无需 `.codex/skills` 或工具专属配置。依据：[Codex skills](https://learn.chatgpt.com/docs/build-skills)、[AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
+- `opencode.json` 使用 OpenCode 的 `instructions` 配置直接引用 `AGENTS.md`；`.agents/skills/` 由 OpenCode 原生发现，不再写入过期的 `skills.paths`
 - `CLAUDE.md` 通过 `@AGENTS.md` 复用共享规范，Claude Code 按其中的任务导航读取 `.agents/skills/` 正文与参考。CLI 不生成 `.claude/` 技能副本；此模式不提供 Claude 原生技能自动发现或 `/skill` 命令。依据：[Claude Code 项目指引](https://code.claude.com/docs/en/memory)、[原生 skills](https://code.claude.com/docs/en/skills)
 - `hai add` / `hai init` 只补齐缺失的 AI 支持文件，不覆盖用户已自定义的桥接文件，也不会自动删除遗留的 `.github/skills/` 或 `.claude/`
 
@@ -156,3 +157,7 @@ import { iam } from '@h-ai/iam'
 选用 IAM 的 admin/h5/website 模板提供 AuthPanel 和标准认证路由；mobile-app 与 fullstack Web/App/Desktop 使用 API 客户端共享动作。修改服务端 config/_iam.yml 即可控制登录方式、注册、重置、协议和品牌，无需改表单。配置 Reach 模板和真实发送 Provider 后启用 OTP/重置。分布式部署使用共享数据库与 Redis。
 
 LDAP/Reach 是可选 peer；IAM 不强制启用 Reach。默认 LDAP 客户端由应用选择安装 ldapts。自定义通知回调、协议弹窗、表单 snippet 用法随 hai-iam/hai-ui skills 完整复制到生成项目，不能要求应用读取本仓库私有路径。
+
+## 表单布局
+
+新增/编辑复用 `@h-ai/ui` 的 Form/FormLayout/FormField：可选一列或双列、标签独立成行或与控件同行，多行文本与多选自动跨列，窄容器自动收为一列。CRUD 使用 `form` 配置，字段可用 `colSpan` 覆盖。错误显示在字段附近并随 UI 语言更新。website 联系页采用 FormLayout + FormField；fullstack 共享用户编辑页采用双列同行标签，个人资料与密码页复用 UI 场景组件。没有数据表单的模板保留现有骨架，新增表单按 hai-ui skill 接入。

package/templates/apps/api/e2e/capture-evidence.ts.hbs

@@ -0,0 +1,23 @@
+import { mkdir } from 'node:fs/promises'
+import path from 'node:path'
+import process from 'node:process'
+import { chromium, expect } from '@playwright/test'
+
+/** 仅在指定证据目录时采集健康端点截图，常规 API 测试通过 HTTP 请求完成。 */
+export default async function captureEvidence() {
+  const evidence = process.env.HAI_AUTH_EVIDENCE_DIR
+  if (!evidence)
+    return
+  const browser = await chromium.launch({ channel: 'chrome' })
+  try {
+    const page = await browser.newPage()
+    const response = await page.goto(new URL('/health', process.env.BASE_URL || 'http://127.0.0.1:3000').href)
+    expect(response?.status()).toBe(200)
+    await expect(page.locator('body')).toContainText('ok')
+    await mkdir(evidence, { recursive: true })
+    await page.screenshot({ path: path.join(evidence, '{{projectName}}-health.png'), fullPage: true })
+  }
+  finally {
+    await browser.close()
+  }
+}

package/templates/apps/api/playwright.config.ts.hbs

@@ -32,6 +32,7 @@ function resolvePortFromBaseUrl(urlString: string, fallbackPort: string): string
 
 export default defineConfig({
   testDir: './e2e',
+  globalSetup: './e2e/capture-evidence.ts',
   fullyParallel: false,
   forbidOnly: !!process.env.CI,
   retries: process.env.CI ? 2 : 0,

package/templates/apps/fullstack/e2e/fullstack.spec.ts.hbs

@@ -18,13 +18,29 @@ const configuredEnv = process.env.HAI_CORE_ENV || 'test'
 // 测试专用的一像素 PNG；上传仍使用完整前后端加密链路。
 const avatar = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aSxkAAAAASUVORK5CYII=', 'base64')
 
-async function login(page: Page, username: string, password: string) {
+async function capture(page: Page, name: string, fallback: string) {
+  const evidence = process.env.HAI_AUTH_EVIDENCE_DIR
+  if (evidence)
+    await mkdir(evidence, { recursive: true })
+  await expect(page.getByTestId('guide-loading')).toHaveCount(0)
+  await page.evaluate(() => document.fonts.ready)
+  await page.screenshot({ path: evidence ? path.join(evidence, name) : fallback, fullPage: true, animations: 'disabled' })
+}
+
+async function submitLogin(page: Page, username: string, password: string) {
   await expect(page.getByTestId('login-form')).toBeVisible()
   await page.locator('#login-username').fill(username)
   await page.getByTestId('login-form').locator('input[type="password"]').fill(password)
   await page.getByTestId('login-form').getByRole('button', { name: /登录|Sign in|Login|Log in/i }).click()
 }
 
+async function login(page: Page, username: string, password: string, keepGuide = false) {
+  await submitLogin(page, username, password)
+  await expect(page.getByTestId('logout')).toBeVisible()
+  if (!keepGuide && await page.getByTestId('guide-later').isVisible())
+    await page.getByTestId('guide-later').click()
+}
+
 async function userEditor(page: Page, username: string) {
   await page.getByTestId('users-search').locator('input').fill(username)
   await page.getByTestId('users-page').getByRole('button', { name: /查询|Search/ }).click()
@@ -45,6 +61,95 @@ test('service rejects plaintext business requests', async ({ request }) => {
 })
 
 {{#if fullstack.e2eFrontend}}
+test('first-use tour, help search and settings navigation work on desktop and mobile', async ({ page }, testInfo) => {
+  await page.goto('/')
+  await login(page, 'admin', adminPassword, true)
+  await expect(page.getByTestId('guide-offer')).toBeVisible()
+  await page.getByTestId('guide-start').click()
+  const popover = page.locator('.hai-guide-popover')
+  await expect(popover).toBeVisible()
+  await capture(page, '{{projectName}}-guide-desktop.png', testInfo.outputPath('guide-desktop.png'))
+  for (let step = 1; step < 3; step++) {
+    await popover.locator('.driver-popover-next-btn').click()
+    await expect(popover.locator('.driver-popover-progress-text')).toContainText(String(step + 1))
+  }
+  await popover.locator('.driver-popover-next-btn').click()
+  await expect(popover).toHaveCount(0)
+  await page.reload()
+  await expect(page.getByTestId('admin-help')).toBeVisible()
+  await expect(page.getByTestId('guide-offer')).toHaveCount(0)
+  await page.getByTestId('admin-help').click()
+  const profileTitle = (await page.getByTestId('guide-article-profile').textContent())!.trim()
+  await page.getByTestId('guide-search').locator('input').fill(profileTitle)
+  await expect(page.getByTestId('guide-article-profile')).toBeVisible()
+  await expect(page.getByTestId('guide-article-overview')).toHaveCount(0)
+  await page.getByTestId('guide-article-start').click()
+  await expect(page.getByTestId('settings-page')).toBeVisible()
+  await expect(popover).toBeVisible()
+  await page.keyboard.press('Escape')
+  await expect(popover).toHaveCount(0)
+  await page.setViewportSize({ width: 390, height: 844 })
+  await page.getByTestId('admin-help').click()
+  await expect(page.getByTestId('help-center')).toBeVisible()
+  expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true)
+  await capture(page, '{{projectName}}-guide-help-mobile.png', testInfo.outputPath('guide-help-mobile.png'))
+  await page.getByTestId('guide-tour-overview').click()
+  await expect(popover.locator('.driver-popover-next-btn')).toBeEnabled()
+  // 下一步未渲染时仍能通过宿主提示取消，不能被引擎遮罩阻止。
+  await page.locator('[data-guide="admin-profile"]').evaluate(element => element.removeAttribute('data-guide'))
+  await popover.locator('.driver-popover-next-btn').click()
+  await expect(page.getByTestId('guide-loading')).toBeVisible()
+  await page.getByTestId('guide-cancel').click()
+  await expect(popover).toHaveCount(0)
+  await expect(page.getByTestId('guide-error')).toHaveCount(0)
+})
+
+// 所有已生成的浏览器前端都验证共享引导，不能用 Web 的成功代替 App/Desktop 预览。
+const additionalFrontends = [
+{{#each fullstack.frontendApps}}
+  {
+    target: '{{target}}',
+    url: process.env.HAI_E2E_{{target}}_URL || 'http://127.0.0.1:{{port}}',
+  },
+{{/each}}
+].filter(frontend => frontend.target !== '{{fullstack.e2eFrontend.target}}')
+
+for (const frontend of additionalFrontends) {
+  test(`${frontend.target} preview supports login, tour, help and profile navigation`, async ({ browser }, testInfo) => {
+    const page = await browser.newPage({ viewport: frontend.target === 'app' ? { width: 390, height: 844 } : { width: 1440, height: 960 } })
+    const pageErrors: string[] = []
+    page.on('pageerror', error => pageErrors.push(error.message))
+    try {
+      await page.goto(frontend.url)
+      await expect(page.getByTestId('login-form')).toBeVisible()
+      await capture(page, `{{projectName}}-${frontend.target}-login.png`, testInfo.outputPath(`${frontend.target}-login.png`))
+      await login(page, 'admin', adminPassword, true)
+      await expect(page.getByTestId('guide-offer')).toBeVisible()
+      await page.getByTestId('guide-start').click()
+      const popover = page.locator('.hai-guide-popover')
+      await expect(popover).toBeVisible()
+      await capture(page, `{{projectName}}-${frontend.target}-guide.png`, testInfo.outputPath(`${frontend.target}-guide.png`))
+      await page.keyboard.press('Escape')
+      await expect(popover).toHaveCount(0)
+      await page.getByTestId('admin-help').click()
+      await expect(page.getByTestId('help-center')).toBeVisible()
+      expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true)
+      await capture(page, `{{projectName}}-${frontend.target}-help.png`, testInfo.outputPath(`${frontend.target}-help.png`))
+      await page.getByTestId('guide-article-profile').click()
+      await page.getByTestId('guide-article-start').click()
+      await expect(page.getByTestId('settings-page')).toBeVisible()
+      await expect(popover).toBeVisible()
+      await page.keyboard.press('Escape')
+      await expect(popover).toHaveCount(0)
+      await capture(page, `{{projectName}}-${frontend.target}-profile.png`, testInfo.outputPath(`${frontend.target}-profile.png`))
+      expect(pageErrors).toEqual([])
+    }
+    finally {
+      await page.close()
+    }
+  })
+}
+
 test('shared authentication supports public registration with configuration', async ({ page }) => {
   test.setTimeout(90_000)
   const evidence = process.env.HAI_AUTH_EVIDENCE_DIR || path.resolve('test-results/auth-screenshots')
@@ -106,7 +211,7 @@ test('shared authentication supports public registration with configuration', as
   await expect(page.getByTestId('settings-page')).toBeVisible()
 })
 
-test('frontend displays configured core metadata and restores the administrator session', async ({ page }) => {
+test('frontend displays configured core metadata and restores the administrator session', async ({ page }, testInfo) => {
   await page.goto('/')
   await expect(page.getByTestId('app-name')).toHaveText(configuredName)
   await expect(page).toHaveTitle(configuredName)
@@ -118,17 +223,24 @@ test('frontend displays configured core metadata and restores the administrator
   await expect(page.getByTestId('users-page')).toBeVisible()
   await expect(page.getByTestId('nav-roles')).toBeVisible()
   await expect(page.getByTestId('nav-audit')).toBeVisible()
+  const evidence = process.env.HAI_AUTH_EVIDENCE_DIR
+  if (evidence)
+    await mkdir(evidence, { recursive: true })
+  await page.screenshot({ path: evidence ? path.join(evidence, '{{projectName}}-users.png') : testInfo.outputPath('users.png'), fullPage: true })
   await page.getByTestId('logout').click()
   await expect(page.getByTestId('login-form')).toBeVisible()
 })
 
-test('audit filters align and fit desktop, tablet and narrow mobile screens', async ({ page }) => {
+test('audit filters align and fit desktop, tablet and narrow mobile screens', async ({ page }, testInfo) => {
   await page.goto('/')
   await login(page, 'admin', adminPassword)
   await page.getByTestId('nav-audit').click()
   await expect(page.getByTestId('audit-page')).toBeVisible()
   for (const width of [1440, 960, 390, 320]) {
     await page.setViewportSize({ width, height: 900 })
+    // 等待移动侧栏收起，避免过渡帧遮挡内容并污染截图。
+    if (width < 1024)
+      await expect.poll(() => page.locator('aside').evaluate(sidebar => sidebar.getBoundingClientRect().right)).toBeLessThanOrEqual(1)
     const controls = await page.getByTestId('audit-page').locator('form').evaluate(form => [
       form.querySelector('#audit-action')?.parentElement,
       form.querySelector('#audit-resource')?.parentElement,
@@ -152,6 +264,13 @@ test('audit filters align and fit desktop, tablet and narrow mobile screens', as
       expect(controls[2]!.top).toBeCloseTo(controls[3]!.top, 0)
     }
     expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true)
+    if (width === 1440 || width === 390) {
+      const evidence = process.env.HAI_AUTH_EVIDENCE_DIR
+      if (evidence)
+        await mkdir(evidence, { recursive: true })
+      const file = `{{projectName}}-audit-${width}.png`
+      await page.screenshot({ path: evidence ? path.join(evidence, file) : testInfo.outputPath(file), fullPage: true, animations: 'disabled' })
+    }
   }
 })
 
@@ -252,7 +371,7 @@ test('administrator and user complete account, avatar, preference, password and
     await passwordInputs.nth(2).fill(newPassword)
     await userPage.getByTestId('password-form').getByRole('button', { name: /Change password/i }).click()
     await expect(userPage.getByTestId('login-form')).toBeVisible()
-    await login(userPage, username, password)
+    await submitLogin(userPage, username, password)
     await expect(userPage.getByTestId('login-form')).toContainText(/不正确|incorrect/i)
     await login(userPage, username, newPassword)
     await expect(userPage.getByTestId('settings-page')).toBeVisible()

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_serv.yml.hbs

@@ -10,6 +10,8 @@ server:
   port: 3000
 
 http:
+  # 仅列出会清洗/追加转发头的代理 IP/CIDR；空数组忽略 X-Forwarded-For/X-Real-IP。
+  trustedProxies: []
   apiPrefix: /api/v1
   openapi:
     path: /openapi.json

package/templates/apps/fullstack/packages/{{projectName}}-serv/src/app-server.ts.hbs

@@ -1,6 +1,6 @@
 import type { CoreConfig } from '@h-ai/core'
 import type { ServHttpApp } from '@h-ai/serv'
-import { core, err, HaiCommonError, ok } from '@h-ai/core'
+import { core } from '@h-ai/core'
 import { createReldbTransportKeyStore, crypto } from '@h-ai/crypto'
 import { iam } from '@h-ai/iam'
 import { reldb } from '@h-ai/reldb'
@@ -40,26 +40,6 @@ export function createServerApp(): ServHttpApp {
       },
     }),
     iam,
-    verifyToken: async (token) => {
-      const session = await iam.session.verifyToken(token)
-      if (!session.success)
-        return session
-      const user = await iam.user.getUser(session.data.userId)
-      if (!user.success)
-        return user
-      if (!user.data?.enabled)
-        return err(HaiCommonError.UNAUTHORIZED, core.i18n.coreM('core_errorUnauthorized'))
-      // 会话中的授权同步属于最大努力，业务守卫始终读取最新持久化角色与权限。
-      const [roles, permissions] = await Promise.all([
-        iam.authz.getUserRoles(user.data.id),
-        iam.authz.getUserPermissions(user.data.id),
-      ])
-      if (!roles.success)
-        return roles
-      if (!permissions.success)
-        return permissions
-      return ok({ ...session.data, roles: roles.data.map(role => role.code), permissions: permissions.data.map(permission => permission.code) })
-    },
     refreshCookie: {
       secure: security.secureRefreshCookie,
       nativeTokenTransport: { isRequest: request => request.headers.get('x-hai-token-transport') === 'body'

package/templates/apps/fullstack/packages/{{projectName}}-serv/src/server/procedures/admin-procedures.ts.hbs

@@ -85,7 +85,7 @@ export function createAdminProcedures() {
     const result = await audit.list({ ...input, startDate: input.startDate ? new Date(input.startDate) : undefined, endDate: input.endDate ? new Date(input.endDate) : undefined })
     if (!result.success)
       return result
-    return ok({ ...result.data, page: input.page, pageSize: input.pageSize, items: result.data.items.map(item => ({ ...item, createdAt: new Date(item.createdAt).toISOString() })) })
+    return ok({ ...result.data, items: result.data.items.map(item => ({ ...item, createdAt: new Date(item.createdAt).toISOString() })) })
   }).build()
 }
 

package/templates/apps/fullstack/packages/{{projectName}}-shared/README.md.hbs

@@ -21,6 +21,12 @@ Capacitor native uses `createCapacitorTokenStorage()` and the trusted native tok
 
 Language and theme preferences are saved in IAM user metadata, restored after login and synchronized with the shared/host Paraglide runtimes and `core.i18n`. The small reactive theme store delegates DOM updates and safe appearance caching to `@h-ai/ui/theme` (`applyTheme` / `getSavedTheme`); the framework uses the `theme` localStorage key. Appearance selectors live in personal settings and save through the authenticated profile contract.
 
+## Onboarding and help
+
+AdminWorkspace mounts the shared `@h-ai/ui/guide` controller and GuideHost after authentication. AppShell includes a help button; first-use invitations offer start, later and dismiss. Web stores preferences in Cookies, while App/Desktop use localStorage, scoped by the current user and tour version. Help articles link to the overview and profile tours.
+
+Extend `src/lib/stores/guide-store.ts` and the shared Chinese/English messages, then add stable data-guide attributes to existing components. Navigation uses the same ManagementStore. Keep business text as i18n callbacks and preserve the host's locale/scope binding. Browser tests cover completion, reload, replay, settings navigation and mobile help.
+
 ## i18n and themes
 
 Shared page copy belongs in `messages/{zh-CN,en-US}.json`. Frontend-specific copy belongs in each app's own messages directory. Keep `baseLocale` and `locales` aligned across all enabled projects, then run root `pnpm i18n:compile`; do not edit generated Paraglide files.
@@ -31,7 +37,7 @@ The scaffold theme configuration determines the themes compiled into frontend CS
 
 ## Validation
 
-Run root `pnpm typecheck`, `pnpm lint`, `pnpm build`, `pnpm test` and `pnpm test:e2e`. Shared API tests exercise real transport key exchange, encrypted request/response handling, configured core metadata and credential forwarding. Root browser tests cover administrator and ordinary-user workflows, avatar rendering, persisted preferences, password/session invalidation and narrow-screen layout.
+Run root `pnpm typecheck`, `pnpm lint`, `pnpm build`, `pnpm test` and `pnpm test:e2e`. Shared API tests exercise real transport key exchange, encrypted request/response handling, configured core metadata and credential forwarding. Root browser tests cover administrator and ordinary-user workflows, avatar rendering, persisted preferences, password/session invalidation and narrow-screen layout. All selected Web/App/Desktop previews also exercise login, tours, help and profile navigation. Set `HAI_AUTH_EVIDENCE_DIR` to keep screenshots outside the test output directory. These browser checks do not replace native-shell or miniapp device acceptance.
 
 ## IAM configuration
 
@@ -42,3 +48,7 @@ LDAP and Reach are optional. Install ldapts in the IAM service workspace only wh
 协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
 
 See `.agents/skills/hai-iam/reference.md` in the generated application for the complete contract.
+
+## Form layouts
+
+The user editor uses `FormLayout columns={2} labelPosition="left"`; profile and password forms reuse the same UI options. Narrow containers automatically stack fields and labels. Field validation errors follow the current UI language. The management store syncs locale through the lightweight `@h-ai/ui/i18n` entry, without loading components or tour CSS. Configure `colSpan` on FormField to override automatic spans for textareas, uploads and multiple choices.

package/templates/apps/fullstack/packages/{{projectName}}-shared/messages/en-US.json.hbs

@@ -83,5 +83,23 @@
   "audit_system": "System",
   "audit_details": "Audit log details",
   "audit_date_invalid": "The end date must be on or after the start date.",
-  "api_not_configured": "The service connection is not configured. Please contact your administrator."
+  "api_not_configured": "The service connection is not configured. Please contact your administrator.",
+  "guide_overview_title": "Explore your admin workspace",
+  "guide_overview_description": "A few short steps introduce the workspace, personal settings and help. Leave at any time and replay tours from the help center.",
+  "guide_content_title": "Workspace",
+  "guide_content_description": "The current page appears here. Use navigation to switch features. Available actions depend on your permissions.",
+  "guide_theme_title": "Appearance",
+  "guide_theme_description": "Switch between light and dark appearances here. More themes are available in settings.",
+  "guide_profile_title": "Your profile",
+  "guide_profile_description": "Use your avatar to access your profile and settings, including personal information and passwords.",
+  "guide_help_title": "Help center",
+  "guide_help_description": "Search instructions here whenever you need help, or replay a product tour.",
+  "guide_profile_tour_title": "Set up your profile",
+  "guide_profile_tour_description": "Find your personal information, preferences and password settings. This tour explains actions without submitting changes.",
+  "guide_profile_form_description": "View or edit your profile, choose an avatar and save your changes. Uploaded files must meet the format and size requirements shown on the page.",
+  "guide_preferences_description": "Save your preferred language and theme. The interface and help content follow your selection.",
+  "guide_password_title": "Change password",
+  "guide_password_description": "Enter your current password, new password and confirmation. Check the password rules before submitting.",
+  "guide_overview_article": "## Getting started\n\n- Open features through navigation. Menus and actions depend on your current permissions.\n- The workspace contains lists, details or settings. Follow the page instructions and check information before submitting.\n- Use your avatar to access your profile and settings.\n- Search instructions or replay tours through the help button.\n\n## First-use tour\n\n“Remind me later” pauses reminders for one day. “Do not remind me” saves your preference. Completed tours no longer prompt automatically and remain available for manual replay.",
+  "guide_profile_article": "## Profile and preferences\n\nOpen your profile to view or update personal information and your avatar. Check the file requirements, save changes and read the result message. Appearance and language can be adjusted in settings.\n\n## Password\n\nChanging a password requires the current password, new password and confirmation. Follow the displayed password rules and check the result after submitting.\n\n“Start tour” opens the relevant page. Tours never save forms or change your account automatically."
 }

package/templates/apps/fullstack/packages/{{projectName}}-shared/messages/zh-CN.json.hbs

@@ -83,5 +83,23 @@
   "audit_system": "系统",
   "audit_details": "审计日志详情",
   "audit_date_invalid": "结束日期不能早于开始日期。",
-  "api_not_configured": "尚未配置服务连接，请联系应用管理员。"
+  "api_not_configured": "尚未配置服务连接，请联系应用管理员。",
+  "guide_overview_title": "快速认识管理后台",
+  "guide_overview_description": "用几个简短步骤了解工作区、个人设置和帮助入口。你可以随时退出，也可以从帮助中心重新查看。",
+  "guide_content_title": "工作区",
+  "guide_content_description": "这里展示当前页面的内容。通过导航菜单切换功能，页面会根据你的权限提供可用操作。",
+  "guide_theme_title": "外观切换",
+  "guide_theme_description": "点击这里快速切换亮色与暗色外观。更多主题可以在设置页面中选择。",
+  "guide_profile_title": "个人资料",
+  "guide_profile_description": "点击头像打开个人资料和设置入口，管理头像、个人信息与密码。",
+  "guide_help_title": "帮助中心",
+  "guide_help_description": "遇到问题时从这里搜索使用说明，或重新开始任意操作导览。",
+  "guide_profile_tour_title": "完善个人资料",
+  "guide_profile_tour_description": "了解个人信息、偏好和密码设置的位置。引导只说明操作，不会自动提交修改。",
+  "guide_profile_form_description": "在这里查看或编辑个人资料，选择头像并保存修改。上传文件需符合页面显示的格式与大小要求。",
+  "guide_preferences_description": "选择语言和主题后保存，界面与帮助内容会使用所选语言和外观。",
+  "guide_password_title": "修改密码",
+  "guide_password_description": "输入当前密码、新密码和确认密码，按页面提示提交。修改前请确认新密码符合密码规则。",
+  "guide_overview_article": "## 从哪里开始\n\n- 使用导航菜单打开需要的功能。可见菜单和操作由当前权限决定。\n- 工作区显示列表、详情或设置内容。按页面提示完成操作，提交前确认信息。\n- 点击头像访问个人资料与设置。\n- 点击帮助入口搜索说明或重新查看导览。\n\n## 首次引导\n\n选择“稍后提醒”会暂缓一天；选择“不再提醒”会保留你的选择。完成导览后不会重复提示，仍可手动重看。",
+  "guide_profile_article": "## 个人资料与偏好\n\n打开个人资料页面，查看或修改个人信息与头像。头像需符合页面显示的文件要求，保存后查看结果提示。外观和语言可在设置中调整。\n\n## 密码\n\n修改密码需要当前密码、新密码和确认密码。按页面显示的密码规则填写，提交后查看结果。\n\n点击“开始引导”可以直接进入对应页面。导览不会自动保存表单或修改账户。"
 }

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/components/AdminWorkspace.svelte.hbs

@@ -3,10 +3,12 @@
   import { Alert, Skeleton } from '@h-ai/ui/components/compounds/index'
   import { Button } from '@h-ai/ui/components/primitives/index'
   import { AuthPanel } from '@h-ai/ui/components/scenes/iam/index'
-  import { onMount } from 'svelte'
+  import { GuideHost } from '@h-ai/ui/guide'
+  import { onMount, untrack } from 'svelte'
   import { managementAuthActions } from '../api/api-client.js'
   import * as m from '../paraglide/messages.js'
   import { ManagementStore } from '../stores/management-store.svelte.js'
+  import { createManagementGuide } from '../stores/guide-store.js'
   import AppShell from './AppShell.svelte'
 
   interface Props {
@@ -16,6 +18,8 @@
   }
   const { platform, apiOptions = {}, onLocaleChange }: Props = $props()
   const store = new ManagementStore()
+  // 宿主平台在组件生命周期中固定，引导控制器只创建一次。
+  const guide = untrack(() => createManagementGuide(store, platform))
   let resetToken = $state('')
   async function authenticated() {
     await store.authenticated()
@@ -67,7 +71,7 @@
       {/if}
     </main>
   {:else}
-    <AppShell {platform} {store}>
+    <AppShell {platform} {store} onhelp={() => guide.openHelp()}>
       <div class='space-y-5'>
         {#if store.error}<Alert variant='error' data-testid='error'>{store.error}</Alert>{/if}
         {#if store.notice}<Alert variant='success' data-testid='notice'>{store.notice}</Alert>{/if}
@@ -78,5 +82,6 @@
         {/await}
       </div>
     </AppShell>
+    <GuideHost {guide} locale={store.locale} scope={store.user.id} autoStart='overview' />
   {/if}
 {/key}

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/components/AppShell.svelte.hbs

@@ -8,8 +8,9 @@
     platform: 'web' | 'app' | 'desktop' | 'miniapp'
     store: ManagementStore
     children: Snippet
+    onhelp: () => void
   }
-  const { platform, store, children }: Props = $props()
+  const { platform, store, children, onhelp }: Props = $props()
   let menuOpen = $state(false)
   const items = $derived([
     ...(store.isAdmin
@@ -54,9 +55,10 @@
         <span class="truncate text-sm font-medium">{title}</span>
       </div>
       <div class="flex shrink-0 items-center gap-1.5 sm:gap-3">
+        <Button variant="ghost" size="sm" onclick={onhelp} data-guide="admin-help" data-testid="admin-help" ariaLabel={m.guide_help_title()}><span class="icon-[tabler--help-circle] size-4"></span><span class="hidden sm:inline">{m.guide_help_title()}</span></Button>
         <Badge variant="ghost" size="sm" data-testid="app-environment">{store.info?.env}</Badge>
         {#if store.user}
-          <BareButton class="flex items-center gap-2 rounded-lg px-1 py-1 hover:bg-base-content/5 sm:px-2" ariaLabel={m.settings_title()} onclick={() => navigate('settings')}>
+          <BareButton class="flex items-center gap-2 rounded-lg px-1 py-1 hover:bg-base-content/5 sm:px-2" ariaLabel={m.settings_title()} onclick={() => navigate('settings')} data-guide="admin-profile">
             <Avatar name={store.user.displayName || store.user.username} src={store.user.avatarUrl} size="sm" />
             <span class="hidden max-w-36 truncate text-sm sm:block">{store.user.displayName || store.user.username}</span>
           </BareButton>
@@ -64,7 +66,7 @@
         <Button variant="ghost" size="sm" loading={store.saving} onclick={() => void store.logout()} data-testid="logout">{m.logout()}</Button>
       </div>
     </header>
-    <main class="mx-auto w-full max-w-7xl flex-1 p-4 pb-8 sm:p-6 lg:p-8">{@render children()}</main>
+    <main class="mx-auto w-full max-w-7xl flex-1 p-4 pb-8 sm:p-6 lg:p-8" data-guide="admin-content">{@render children()}</main>
     <footer class="border-t border-base-content/8 px-6 py-3 text-center text-xs text-base-content/35">{store.info?.name} · v{store.info?.version}</footer>
   </div>
 </div>

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/components/ProfileSettings.svelte.hbs

@@ -32,11 +32,11 @@
         </div>
         <p class='mt-4 text-xs leading-6 text-base-content/50'>{m.avatar_hint()}</p>
       </Card>
-      <Card title={m.profile_title()} bordered shadow={false}>
-        <UserProfile user={store.user} editable alwaysEditable fields={['avatar', 'displayName', 'email']} avatarAccept='image/png,image/jpeg,image/webp' avatarHint={m.avatar_hint()} loading={store.saving} onsubmit={data => store.saveProfile(data)} onavatarchange={file => void store.uploadAvatar(file)} data-testid='profile-form' />
+      <Card title={m.profile_title()} bordered shadow={false} data-guide='admin-profile-form'>
+        <UserProfile columns={2} labelPosition='left' user={store.user} editable alwaysEditable fields={['avatar', 'displayName', 'email']} avatarAccept='image/png,image/jpeg,image/webp' avatarHint={m.avatar_hint()} loading={store.saving} onsubmit={data => store.saveProfile(data)} onavatarchange={file => void store.uploadAvatar(file)} data-testid='profile-form' />
       </Card>
     </div>
-    <Card title={m.preferences_title()} bordered shadow={false}>
+    <Card title={m.preferences_title()} bordered shadow={false} data-guide='admin-preferences'>
       <p class='mb-5 text-sm text-base-content/50'>{m.preferences_description()}</p>
       <div class='grid gap-6 sm:grid-cols-2'>
         <div class='space-y-2'>
@@ -49,9 +49,9 @@
         </div>
       </div>
     </Card>
-    <Card title={m.password_title()} bordered shadow={false}>
+    <Card title={m.password_title()} bordered shadow={false} data-guide='admin-password'>
       <p class='mb-5 text-sm text-base-content/50'>{m.password_rules()}</p>
-      <div class='max-w-xl'><ChangePasswordForm loading={store.saving} passwordPolicy={store.authConfig?.password} minPasswordLength={store.authConfig?.password.minLength ?? 8} onsubmit={data => store.changePassword(data)} data-testid='password-form' /></div>
+      <div class='max-w-xl'><ChangePasswordForm labelPosition='left' loading={store.saving} passwordPolicy={store.authConfig?.password} minPasswordLength={store.authConfig?.password.minLength ?? 8} onsubmit={data => store.changePassword(data)} data-testid='password-form' /></div>
     </Card>
   {/if}
 </section>

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/components/UserManagement.svelte.hbs

@@ -1,7 +1,7 @@
 <script lang="ts">
   import type { AdminRoleCode, AdminUser } from '{{fullstack.contractPackageName}}'
   import type { ManagementStore } from '../stores/management-store.svelte.js'
-  import { Card, DataTable, FormField, Modal, Pagination, Skeleton } from '@h-ai/ui/components/compounds/index'
+  import { Card, DataTable, FormField, FormLayout, Modal, Pagination, Skeleton } from '@h-ai/ui/components/compounds/index'
   import { Avatar, Badge, BareInput, Button, Checkbox, Input, Select } from '@h-ai/ui/components/primitives/index'
   import { PasswordInput } from '@h-ai/ui/components/scenes/iam/index'
   import * as m from '../paraglide/messages.js'
@@ -133,23 +133,25 @@
   </div>
 </section>
 
-<Modal bind:open={editorOpen} title={editing ? m.user_edit() : m.user_create()} closeOnBackdrop={!store.saving} closeOnEscape={!store.saving} data-testid="user-editor">
-  <form class="space-y-4" onsubmit={submit}>
-    <FormField label={m.user_username()} required>
-      <Input bind:value={username} name="username" readonly={!!editing} required minlength={3} maxlength={64} pattern="[\w\-]+" autocomplete="off" data-testid="user-username" />
-    </FormField>
-    <FormField label={m.user_display_name()}><Input bind:value={displayName} maxlength={100} data-testid="user-display-name" /></FormField>
-    <FormField label={m.user_email()}><Input type="email" bind:value={email} data-testid="user-email" /></FormField>
-    {#if !editing}
-      <FormField label={m.user_password()} hint={m.initial_password_rules({ min: store.authConfig?.password.minLength ?? 8 })} required><PasswordInput bind:value={password} autocomplete="new-password" minLength={store.authConfig?.password.minLength ?? 8} data-testid="user-password" /></FormField>
-    {/if}
-    <FormField label={m.user_role()}><Select bind:value={role} options={roleOptions} disabled={editing?.id === store.user?.id} data-testid="user-role" /></FormField>
-    <Checkbox bind:checked={enabled} label={m.account_enabled()} disabled={editing?.id === store.user?.id} />
-    {#if store.error}<p class="text-sm text-error" role="alert">{store.error}</p>{/if}
-    <div class="flex justify-end gap-2 border-t border-base-content/8 pt-4">
-      <Button variant="ghost" disabled={store.saving} onclick={() => { editorOpen = false }}>{m.cancel()}</Button>
-      <Button type="submit" variant="primary" loading={store.saving} disabled={!editing && password.length < 8} data-testid="user-save">{m.save()}</Button>
-    </div>
+<Modal bind:open={editorOpen} title={editing ? m.user_edit() : m.user_create()} closeOnBackdrop={!store.saving} closeOnEscape={!store.saving} size="3xl" data-testid="user-editor">
+  <form onsubmit={submit}>
+    <FormLayout columns={2} labelPosition="left" labelWidth="6rem">
+      <FormField label={m.user_username()} required>
+        <Input bind:value={username} name="username" readonly={!!editing} required minlength={3} maxlength={64} pattern="[\w\-]+" autocomplete="off" data-testid="user-username" />
+      </FormField>
+      <FormField label={m.user_display_name()}><Input bind:value={displayName} maxlength={100} data-testid="user-display-name" /></FormField>
+      <FormField label={m.user_email()}><Input type="email" bind:value={email} data-testid="user-email" /></FormField>
+      {#if !editing}
+        <FormField label={m.user_password()} hint={m.initial_password_rules({ min: store.authConfig?.password.minLength ?? 8 })} required><PasswordInput required bind:value={password} autocomplete="new-password" minLength={store.authConfig?.password.minLength ?? 8} data-testid="user-password" /></FormField>
+      {/if}
+      <FormField label={m.user_role()}><Select bind:value={role} options={roleOptions} disabled={editing?.id === store.user?.id} data-testid="user-role" /></FormField>
+      <Checkbox bind:checked={enabled} label={m.account_enabled()} disabled={editing?.id === store.user?.id} />
+      {#if store.error}<p class="text-sm text-error" role="alert">{store.error}</p>{/if}
+      <div class="flex justify-end gap-2 border-t border-base-content/8 pt-4">
+        <Button variant="ghost" disabled={store.saving} onclick={() => { editorOpen = false }}>{m.cancel()}</Button>
+        <Button type="submit" variant="primary" loading={store.saving} disabled={!editing && password.length < 8} data-testid="user-save">{m.save()}</Button>
+      </div>
+    </FormLayout>
   </form>
 </Modal>