@yss123/cage-admin 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yss123/cage-admin",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "组织模型声明与 /admin 系统管理",
   "type": "module",
   "main": "dist/index.js",
@@ -25,7 +25,8 @@
     "fastify": "^5.6.0",
     "zod": "^4.1.5",
     "kysely": "^0.28.5",
-    "@yss123/cage-kernel": "0.2.0"
+    "@yss123/cage-kernel": "0.3.0",
+    "@yss123/cage-ai-protocol": "0.3.0"
   },
   "license": "MIT",
   "repository": {

package/ui/dist/app/shell.js

@@ -1,3 +1,8 @@
+/**
+ * 系统管理应用壳，负责 hash 页面映射、导航、账号操作与加载/错误状态。
+ * 页面模块经公开入口组合，模块只接收内容容器；权限提示按当前会话能力计算，后端仍做权威授权。
+ * 管理界面使用自身 hash 导航，返回业务首页通过普通链接，避免与业务 React Router 混用。
+ */
 import { api, can, run, state } from '../shared/api.js';
 import { emptyState, h, icon, panel } from '../shared/dom.js';
 import { navigate } from '../shared/navigation.js';
@@ -7,7 +12,22 @@ import { renderRoles } from '../modules/roles/index.js';
 import { renderAudit } from '../modules/audit/index.js';
 import { renderOperations, renderSync } from '../modules/operations/index.js';
 import { loginPage } from '../modules/auth/index.js';
+import { renderModels } from '../modules/models/index.js';
+import { renderPersonalities } from '../modules/personalities/index.js';
+/**
+ * 页面目录及所需能力清单。need 为空表示有登录会话即可尝试进入，非空采用 some 允许满足任一能力。
+ * 这些条目同时决定导航显示和页面级提示，不能替代模块请求或服务端鉴权。
+ */
 const pages = {
+    personalities: {
+        title: '助理性格', description: '设置助理的语气、表达习惯和默认性格，随时试聊。',
+        glyph: 'users', category: '运行与记录', render: renderPersonalities, need: ['Sys.ai.personalities.manage'],
+    },
+    models: {
+        title: 'AI 模型',
+        description: '为智能审批与业务助理配置模型连接，保存后后续调用自动生效。',
+        glyph: 'grid', category: '运行与记录', render: renderModels, need: ['Sys.ai.models.manage'],
+    },
     tasks: {
         title: '我的待办',
         description: '集中处理分配给你的审批任务，让每一步协作及时推进。',
@@ -58,6 +78,11 @@ const pages = {
     },
 };
 /** 应用组合层只负责导航、会话和页面加载；各管理模块维护自己的表单和请求。 */
+/**
+ * 根据当前会话与 hash 重建侧栏、页头和内容容器，并等待目标模块完成数据加载。
+ * 没有会话时返回登录页，登录成功调用 boot 重新取身份和目录；退出成功后清空本地会话资料。
+ * 加载异常写入错误面板，finally 移除加载提示；本函数不把隐藏按钮视为服务端授权。
+ */
 export async function render(boot) {
     const root = document.getElementById('app');
     if (!state.me) {

package/ui/dist/app.js

@@ -1,7 +1,17 @@
+/**
+ * 系统管理浏览器入口：恢复登录身份、加载展示目录，再交给 shell 组合页面。
+ * 监听 hash 导航、刷新及会话过期事件；未登录进入登录页，网络或服务异常显示可重试连接状态。
+ * 本入口不保存授权或执行领域逻辑，真实身份与目录通过同源 HTTP 请求获取。
+ */
 import { api, ApiError, state } from './shared/api.js';
 import { h, icon } from './shared/dom.js';
 import { render } from './app/shell.js';
 /** 浏览器入口恢复真实会话与展示目录，不包含具体页面、表单或授权逻辑。 */
+/**
+ * 按顺序读取 /api/me 与管理目录，成功后渲染当前 hash 页面。
+ * 仅 UNAUTHENTICATED 走未登录界面；其他故障保留明确重连入口，避免把网络异常伪装为退出。
+ * 此函数也作为登录成功回调和重新连接动作，恢复失败通过页面反馈。
+ */
 async function boot() {
     try {
         state.me = await api('GET', '/api/me');

package/ui/dist/modules/audit/audit-page.js

@@ -1,3 +1,7 @@
+/**
+ * 操作审计查询页面，通过安全审计接口读取记录并展示操作人、时间和变化详情。
+ * 筛选、分页与详情均属于读操作；界面不补写审计，也不将查到的部分记录当作完整请求轨迹。
+ */
 import { api, run, state } from '../../shared/api.js';
 import { badge, field, formatTime, h, panel, table } from '../../shared/dom.js';
 import { capabilityName, objectName } from '../../shared/labels.js';
@@ -14,6 +18,10 @@ const actors = {
     job: '定时任务',
     system: '系统',
 };
+/**
+ * 构建审计筛选器与列表，等待初次 load 完成；服务端仍校验 Sys.audit.read 与安全视图。
+ * 详情通过 DOM 文本展示，包含结构化差异时也不解释为 HTML。
+ */
 export async function renderAudit(main) {
     const actor = h('input', { placeholder: '操作人的用户 ID' });
     const aggregate = h('select', {}, h('option', { value: '' }, '全部业务对象'), state.catalog.aggregates.map((item) => h('option', { value: item.name }, item.label)));
@@ -47,6 +55,10 @@ export async function renderAudit(main) {
             void load();
         },
     }, field('业务对象', aggregate), field('操作类型', kind), field('操作人', actor), field('单据编号', aggregateId), field('操作标识', command), search), out, h('div', { class: 'pagination' }, pageText, h('div', { class: 'row-actions' }, previous, next))));
+    /**
+     * 按当前筛选和页码请求审计记录，更新表格及分页控制。
+     * 查询失败保留明确错误反馈，不生成占位成功记录；请求只读，不重放任何业务命令。
+     */
     async function load() {
         const params = new URLSearchParams(Object.entries(fields)
             .filter(([, input]) => input.value)

package/ui/dist/modules/audit/index.js

@@ -1 +1,5 @@
+/**
+ * 审计查询模块的公开入口。
+ * 应用壳通过这里组合页面，其他模块无需依赖内部表单实现；导出本身不发请求或执行管理操作。
+ */
 export { renderAudit } from './audit-page.js';

package/ui/dist/modules/auth/index.js

@@ -1 +1,5 @@
+/**
+ * 登录页面模块的公开入口。
+ * 应用壳通过这里组合页面，其他模块无需依赖内部表单实现；导出本身不发请求或执行管理操作。
+ */
 export { loginPage } from './login-page.js';

package/ui/dist/modules/auth/login-page.js

@@ -1,5 +1,13 @@
+/**
+ * 构造系统管理登录页面，复用统一 JSON/CSRF 请求和操作反馈。
+ * 账号密码只用于本次登录表单；成功清掉旧 CSRF 后由上层重新加载真实身份和目录，SSO 使用独立服务端入口。
+ */
 import { api, run, state } from '../../shared/api.js';
 import { field, h, icon } from '../../shared/dom.js';
+/**
+ * 返回未挂载的登录页面 DOM。提交期间禁用按钮，失败由 run 显示原因并保留可重试表单。
+ * onLogin 仅在登录请求成功后等待执行，负责恢复会话并切换页面；本组件不自行伪造身份或能力列表。
+ */
 export function loginPage(onLogin) {
     const username = h('input', {
         name: 'username',

package/ui/dist/modules/models/index.js

@@ -0,0 +1,5 @@
+/**
+ * 托管模型配置模块的公开入口。
+ * 应用壳通过这里组合页面，其他模块无需依赖内部表单实现；导出本身不发请求或执行管理操作。
+ */
+export { renderModels } from './models-page.js';

package/ui/dist/modules/models/models-page.js

@@ -0,0 +1,60 @@
+import { api, run } from '../../shared/api.js';
+import { badge, emptyState, field, formatTime, h, panel } from '../../shared/dom.js';
+/** Admin 只管理框架模型配置；审批规则、业务工具与聊天界面仍由各自声明和应用负责。 */
+/**
+ * 读取托管模型列表并在 main 中构建配置表单，无模型时显示启用提示。
+ * 表单以秒显示超时，提交转换为毫秒；保存携带已读取的 version 防止覆盖其他编辑。
+ * 测试仅使用已保存配置，连接成功不证明全部协议特性或业务工具验收通过；错误由共享操作层反馈。
+ */
+export async function renderModels(main) {
+    const models = await api('GET', '/api/ai/admin/models');
+    if (!models.length) {
+        main.append(panel('尚无可管理的模型', undefined, emptyState('应用尚未启用托管模型', '应用声明模型后，可在这里配置服务地址与密钥。', 'grid')));
+        return;
+    }
+    main.append(h('div', { class: 'model-overview' }, h('div', {}, h('span', { class: 'eyebrow' }, 'MODEL CONNECTIONS'), h('h2', {}, '一个连接，支撑每次智能协作'), h('p', {}, '模型按当前租户配置。API Key 加密保存，不会回显到页面。')), badge(`${models.length} 个模型入口`, 'green')));
+    for (let saved of models) {
+        const label = h('input', { value: saved.label, required: true, maxlength: 100 });
+        const baseUrl = h('input', { type: 'url', value: saved.baseUrl, placeholder: 'https://api.example.com/v1', required: true, maxlength: 1000 });
+        const model = h('input', { value: saved.model, placeholder: '填写服务商提供的模型名称', required: true, maxlength: 200 });
+        const apiKey = h('input', { type: 'password', autocomplete: 'new-password', placeholder: saved.hasApiKey ? '已保存；留空保留原密钥' : '粘贴 API Key', maxlength: 4096 });
+        const enabled = h('input', { type: 'checkbox', checked: saved.enabled });
+        const timeout = h('input', { type: 'number', min: 1, max: 180, value: saved.timeoutMs / 1000, required: true });
+        const compaction = h('input', { type: 'checkbox', checked: saved.responsesCompaction, disabled: saved.apiFormat !== 'responses' });
+        const apiFormat = h('select', { value: saved.apiFormat, onchange: () => {
+                compaction.disabled = apiFormat.value !== 'responses';
+                if (compaction.disabled)
+                    compaction.checked = false;
+            } }, h('option', { value: 'chat-completions' }, 'Chat Completions'), h('option', { value: 'responses' }, 'Responses'));
+        const contextWindow = h('input', { type: 'number', min: 8192, max: 2000000, step: 1, value: saved.contextWindowTokens, required: true });
+        const status = h('div', { class: 'model-save-status', role: 'status' });
+        const summary = h('div', { class: 'model-meta' });
+        const refresh = () => summary.replaceChildren(badge(saved.enabled ? '已启用' : '未启用', saved.enabled ? 'green' : 'neutral'), h('span', {}, saved.hasApiKey ? '密钥已保存' : '等待配置'), h('span', {}, saved.apiFormat === 'responses' ? 'Responses · 服务端接续' : 'Chat Completions'), h('span', {}, `更新于 ${formatTime(saved.updatedAt)}`));
+        refresh();
+        const save = h('button', { class: 'primary', type: 'submit' }, '保存配置');
+        const test = h('button', { type: 'button', disabled: !saved.enabled, onclick: async () => {
+                status.textContent = '正在测试已保存的配置…';
+                const result = await run(() => api('POST', `/api/ai/admin/models/${encodeURIComponent(saved.key)}/test`), undefined, test);
+                status.textContent = result ? result.ok ? `连接成功 · ${result.latencyMs} ms · 配置版本 ${result.version}`
+                    : `连接未成功（${result.code}），请核对地址、模型名称与密钥。` : '测试未完成，请根据错误提示检查配置。';
+            } }, '测试连接');
+        const form = h('form', { class: 'model-form', onsubmit: async (event) => {
+                event.preventDefault();
+                test.disabled = true;
+                const result = await run(() => api('POST', `/api/ai/admin/models/${encodeURIComponent(saved.key)}`, {
+                    version: saved.version, label: label.value, baseUrl: baseUrl.value, model: model.value, apiKey: apiKey.value || undefined,
+                    enabled: enabled.checked, timeoutMs: Number(timeout.value) * 1000,
+                    apiFormat: apiFormat.value, contextWindowTokens: Number(contextWindow.value), responsesCompaction: compaction.checked,
+                }).catch(error => { status.textContent = error.message; throw error; }), '模型配置已保存', save);
+                if (result) {
+                    saved = result;
+                    apiKey.value = '';
+                    apiKey.placeholder = '已保存；留空保留原密钥';
+                    refresh();
+                    status.textContent = '已保存，后续模型调用将使用这份配置。';
+                }
+                test.disabled = !saved.enabled;
+            } }, h('div', { class: 'model-fields' }, field('显示名称', label), field('模型名称', model), field('接口协议', apiFormat, 'Responses 可由服务端接续对话，兼容服务须支持对应协议。'), field('模型上下文窗口（Token）', contextWindow, '按服务商公布的容量填写，用于预留回答空间和限制每次输入。'), field('API 基地址', baseUrl, '支持 HTTP / HTTPS。可填写基础地址或对应接口完整路径；更换地址时需重新填写密钥。'), field('API Key', apiKey, '仅在首次配置或更换密钥时填写。'), field('调用超时（秒）', timeout), field('服务端自动压缩', compaction, '仅对支持 context_management 的 Responses 服务启用；历史仍计入上下文与输入费用。'), h('label', { class: 'model-enabled' }, enabled, '启用此模型')), h('div', { class: 'model-actions' }, status, test, save));
+        main.append(panel(saved.label, `模型入口：${saved.key}`, summary, form));
+    }
+}

package/ui/dist/modules/operations/index.js

@@ -1,2 +1,6 @@
+/**
+ * 异步运维与第三方同步记录模块的公开入口。
+ * 应用壳通过这里组合页面，其他模块无需依赖内部表单实现；导出本身不发请求或执行管理操作。
+ */
 export { renderOperations } from './operations-page.js';
 export { renderSync } from './sync-page.js';

package/ui/dist/modules/operations/operations-page.js

@@ -1,7 +1,15 @@
+/**
+ * 异步运行运维页面，读取 outbox 汇总、未处理死信和注册任务状态。
+ * 运维读取与管理能力分开，重放/丢弃与启停任务通过系统接口执行；界面不直接操作数据库。
+ */
 import { api, can, run } from '../../shared/api.js';
 import { badge, field, formatTime, h, icon, modal, panel, table } from '../../shared/dom.js';
 import { capabilityName, eventName, jobName, statusName } from '../../shared/labels.js';
 import { navigate } from '../../shared/navigation.js';
+/**
+ * 并行取得运行快照并渲染统计、队列、死信和任务列表。
+ * Sys.ops.manage 控制动作按钮，成功请求后重新加载数据；重放仅表示重新投递，不保证远端业务最终成功。
+ */
 export async function renderOperations(main) {
     const [summary, dead, jobs] = await Promise.all([
         api('GET', '/api/sys/ops/summary'),
@@ -74,6 +82,10 @@ export async function renderOperations(main) {
                 }, job.enabled ? '停用' : '启用')),
         ],
     ], jobs, '当前业务没有声明定时任务')));
+    /**
+     * 打开针对单条死信的确认操作，提交 discard 后按成功结果刷新页面。
+     * 丢弃会改变后续事件处理条件，因此需要用户明确选择，不能作为自动修复失败的默认动作。
+     */
     function discard(item) {
         const confirm = h('input', { type: 'checkbox', required: true });
         const save = h('button', { class: 'danger', type: 'submit' }, '确认丢弃事件');
@@ -90,6 +102,9 @@ export async function renderOperations(main) {
         const dialog = modal('丢弃死信事件', form);
     }
 }
+/**
+ * 以既有计数生成运行统计卡，warning 仅决定视觉提示，不改变后台任务状态。
+ */
 function stat(label, value, glyph, warning = false) {
     return h('div', { class: `stat-card ${warning ? 'attention' : ''}` }, h('span', { class: 'stat-icon' }, icon(glyph)), h('div', {}, h('span', {}, label), h('strong', {}, value)));
 }

package/ui/dist/modules/operations/sync-page.js

@@ -1,5 +1,13 @@
+/**
+ * 第三方同步记录查询页面，以连接器和状态筛选展示实际外呼记录。
+ * 响应受服务器数量上限限制，结果记录与业务最终完成是不同事实，页面没有绕过未知结果隔离的重发入口。
+ */
 import { api, run, state } from '../../shared/api.js';
 import { badge, field, formatTime, h, panel, table } from '../../shared/dom.js';
+/**
+ * 构建连接器/状态筛选与同步表格，初始 load 完成后返回。
+ * 读取需运维权限，错误和 HTTP 状态用于定位外部调用，不把 fake 或单次回执当真实系统验收。
+ */
 export async function renderSync(main) {
     const connector = h('input', { placeholder: '连接器标识，留空查看全部' });
     const status = h('select', {}, h('option', { value: '' }, '全部结果'), h('option', { value: 'ok' }, '同步成功'), h('option', { value: 'failed' }, '同步失败'));
@@ -12,6 +20,10 @@ export async function renderSync(main) {
             void load();
         },
     }, field('连接器', connector), field('同步结果', status), query), out));
+    /**
+     * 根据当前连接器及状态筛选发起只读请求，再替换同步记录列表。
+     * 查询失败通过页面反馈，不修改失败计数、回执或任务状态。
+     */
     async function load() {
         const params = new URLSearchParams();
         if (connector.value)

package/ui/dist/modules/org/index.js

@@ -1 +1,5 @@
+/**
+ * 部门与用户管理模块的公开入口。
+ * 应用壳通过这里组合页面，其他模块无需依赖内部表单实现；导出本身不发请求或执行管理操作。
+ */
 export { renderOrg } from './org-page.js';

package/ui/dist/modules/org/org-page.js

@@ -1,7 +1,15 @@
+/**
+ * 组织管理页面：按读取能力分别加载部门、用户与角色，再提供受能力控制的组织命令入口。
+ * 部门负责人用于审批选人，角色用于授权，两种配置独立维护；页面显示只反映当前取回的分页数据。
+ */
 import { api, can, run } from '../../shared/api.js';
 import { badge, field, h, icon, modal, panel, searchInput, table } from '../../shared/dom.js';
 import { navigate } from '../../shared/navigation.js';
 /** 组织编辑继续走生成命令；负责人和角色是两份配置，在界面上明确区分。 */
+/**
+ * 并行读取最多一页组织数据，缺读取能力的集合按空列表处理，后端继续约束实际范围。
+ * 部门用 ancestors 深度显示层级；用户列表支持本地搜索，写入通过生成的领域路由，成功后刷新管理页面。
+ */
 export async function renderOrg(main) {
     const [departments, people, roleResult] = await Promise.all([
         can('Dept.read')
@@ -73,6 +81,10 @@ export async function renderOrg(main) {
             toolbar.append(h('button', { class: 'primary', disabled: !depts.length, onclick: createUser }, icon('plus'), '新建用户'));
         const userPanel = panel('用户与角色', '通过角色分配操作权限；账号停用后将无法继续访问系统。', toolbar, out);
         main.append(userPanel);
+        /**
+         * 按当前本地搜索条件重画已加载用户，并根据命令能力展示角色、密码、启停操作。
+         * 过滤范围限于当前返回的数据，不执行服务器全量搜索。
+         */
         function renderUsers() {
             const visible = users.filter((user) => `${user.name} ${user.username} ${departmentName.get(user.deptId) ?? ''}`
                 .toLowerCase()
@@ -123,6 +135,9 @@ export async function renderOrg(main) {
     }
     if (people.total > users.length || departments.total > depts.length)
         main.append(h('p', { class: 'muted' }, '当前仅展示前 200 条可见组织记录；超出部分请通过业务组织接口查询。'));
+    /**
+     * 打开新建部门表单，通过 Dept.create 传入父部门与资料；成功关闭弹窗并重载组织页。
+     */
     function createDepartment() {
         const name = h('input', { required: true, maxlength: 100, placeholder: '例如：采购部' });
         const parent = selectDepartment();
@@ -140,6 +155,10 @@ export async function renderOrg(main) {
         const dialog = modal('新建部门', form);
         name.focus();
     }
+    /**
+     * 收集用户名、姓名及部门并调用用户创建命令；成功后刷新组织页，密码和角色需通过独立操作配置。
+     * 页面成功动作基于实际请求结果，不通过直接写表配置账号。
+     */
     function createUser() {
         const username = h('input', { required: true, placeholder: '用于登录的账号', autocomplete: 'off' });
         const name = h('input', { required: true, placeholder: '用户真实姓名' });
@@ -162,6 +181,10 @@ export async function renderOrg(main) {
         const dialog = modal('新建用户', form);
         username.focus();
     }
+    /**
+     * 编辑所选用户的完整角色 ID 集合，已有选择作为初值，保存走 User.assignRoles。
+     * 界面提示不能代替服务端防提权和角色有效性检查，成功后才关闭并刷新。
+     */
     function assignRoles(user) {
         const selected = new Set(user.roleIds);
         const save = h('button', { class: 'primary', type: 'submit' }, '保存角色');
@@ -187,6 +210,10 @@ export async function renderOrg(main) {
         }), h('span', {}, h('strong', {}, role.name), h('small', {}, role.code))))), h('div', { class: 'form-actions' }, save));
         const dialog = modal('配置用户角色', form);
     }
+    /**
+     * 为指定用户打开密码重置表单，提交到独立 set-password 命令。
+     * 密码仅保留在表单和请求中；输入校验/授权由服务端再次执行，不影响角色分配。
+     */
     function resetPassword(user) {
         const password = h('input', {
             type: 'password',
@@ -208,6 +235,9 @@ export async function renderOrg(main) {
         password.focus();
     }
 }
+/**
+ * 生成组织页的统计展示卡；value 由调用者传入，不能把本页条数误当服务器总数。
+ */
 function stat(label, value, glyph) {
     return h('div', { class: 'stat-card' }, h('span', { class: 'stat-icon' }, icon(glyph)), h('div', {}, h('span', {}, label), h('strong', {}, value)));
 }

package/ui/dist/modules/personalities/index.js

@@ -0,0 +1,5 @@
+/**
+ * 助理性格配置与试聊模块的公开入口。
+ * 应用壳通过这里组合页面，其他模块无需依赖内部表单实现；导出本身不发请求或执行管理操作。
+ */
+export { renderPersonalities } from './personalities-page.js';

package/ui/dist/modules/personalities/personalities-page.js

@@ -0,0 +1,161 @@
+import { api, postEvents, run } from '../../shared/api.js';
+import { badge, field, h } from '../../shared/dom.js';
+/** 编辑器只提交框架协议；配置与试聊的权限、模型和持久化全部由 AI 运行时处理。 */
+/**
+ * 读取性格目录并装配默认选择、卡片、编辑器和试聊区。
+ * 保存期间冻结表单，成功才清草稿并替换服务端版本；失败保留输入，finally 恢复控件。
+ * 试聊逐段追加文本并在 done 时校准最终回复；断流和取消保留已收到内容并给出明确状态。
+ */
+export async function renderPersonalities(main) {
+    let catalog = await api('GET', '/api/ai/admin/personalities');
+    let selected = catalog.settings.defaultKey, saving = false, activePreview = null;
+    const drafts = new Map();
+    const grid = h('div', { class: 'persona-grid', 'aria-label': '性格列表' });
+    const editor = h('div', { class: 'persona-editor-area' });
+    const defaults = h('div', { class: 'persona-default' });
+    const current = () => drafts.get(selected) ?? catalog.items.find(p => p.key === selected);
+    /**
+     * 重建默认性格选择，只列已启用项；提交携带 settings.version，成功后更新目录和默认标记。
+     */
+    function drawDefault() {
+        const select = h('select', { 'aria-label': '默认性格', value: catalog.settings.defaultKey }, catalog.items.filter(p => p.enabled).map(p => h('option', { value: p.key }, `${p.avatar} ${p.label}`)));
+        const save = h('button', { onclick: async () => {
+                const result = await run(() => api('POST', '/api/ai/admin/assistant-settings', {
+                    version: catalog.settings.version, defaultKey: select.value,
+                }), '默认性格已更新', save);
+                if (result) {
+                    catalog.settings = result;
+                    drawCards();
+                    drawDefault();
+                }
+            } }, '设为默认');
+        defaults.replaceChildren(h('div', {}, h('strong', {}, '默认的相处方式'), h('p', {}, '跟随默认的会话，从下一条消息开始使用此性格。')), h('div', { class: 'persona-default-actions' }, select, save));
+    }
+    /**
+     * 合并已保存目录与新建草稿生成卡片；选择只改变本页编辑对象，保存期间禁止切换。
+     */
+    function drawCards() {
+        const all = new Map(catalog.items.map(p => [p.key, p]));
+        for (const [key, draft] of drafts)
+            if (!all.has(key))
+                all.set(key, draft);
+        grid.replaceChildren(...[...all.values()].map(profile => h('button', { class: `persona-card${selected === profile.key ? ' selected' : ''}`,
+            'aria-pressed': selected === profile.key, onclick: () => { if (saving)
+                return; selected = profile.key; drawCards(); drawEditor(); },
+        }, h('span', { class: 'persona-avatar', 'aria-hidden': 'true' }, profile.avatar), h('span', { class: 'persona-card-copy' }, h('strong', {}, profile.label), h('small', {}, profile.description)), h('span', { class: 'persona-card-tags' }, profile.key === catalog.settings.defaultKey ? badge('默认', 'green') : !profile.enabled ? badge('已停用') : badge(profile.builtin ? '预设' : '自定义')))));
+    }
+    /**
+     * 取消上一份预览，再依据当前草稿/目录构造编辑器。
+     * 表单 input 保存内存草稿；试聊使用当前未保存字段，保存与设默认是独立请求。
+     */
+    function drawEditor() {
+        activePreview?.abort();
+        activePreview = null;
+        let profile = current();
+        const label = h('input', { value: profile.label, required: true, maxlength: 40 });
+        const avatar = h('input', { value: profile.avatar, required: true, maxlength: 16 });
+        const description = h('textarea', { rows: 5, required: true, maxlength: 3000, value: profile.description, placeholder: '描述你希望助理怎样表达、解释和与你相处…' });
+        const verbosity = h('select', { value: profile.verbosity }, ...[['concise', '简短利落'], ['balanced', '详略适中'], ['detailed', '详细解释']].map(([value, text]) => h('option', { value }, text)));
+        const emoji = h('select', { value: profile.emoji }, ...[['none', '不使用'], ['light', '偶尔点缀'], ['expressive', '活泼一些']].map(([value, text]) => h('option', { value }, text)));
+        const address = h('input', { value: profile.address, maxlength: 40, placeholder: '留空，自然称呼' });
+        const examples = [0, 1, 2].map(i => h('input', { value: profile.examples[i] ?? '', maxlength: 400, 'aria-label': `说话示例 ${i + 1}`, placeholder: `示例 ${i + 1}（可选）` }));
+        const enabled = h('input', { type: 'checkbox', checked: profile.enabled });
+        const status = h('p', { class: 'persona-save-status', role: 'status' }, drafts.has(profile.key) ? '有未保存的修改' : profile.version ? `已保存 · 版本 ${profile.version}` : '框架预设，可直接调整');
+        const values = () => ({ label: label.value, avatar: avatar.value, description: description.value,
+            verbosity: verbosity.value, emoji: emoji.value, address: address.value,
+            examples: examples.map(e => e.value.trim()).filter(Boolean), enabled: enabled.checked });
+        const save = h('button', { class: 'primary', type: 'submit' }, '保存性格');
+        const form = h('form', { class: 'persona-form', oninput: () => {
+                drafts.set(profile.key, { ...profile, ...values() });
+                status.textContent = '有未保存的修改';
+            }, onsubmit: async (event) => {
+                event.preventDefault();
+                if (saving)
+                    return;
+                saving = true;
+                // 保存期间冻结这份表单，避免请求结束后把后来输入的草稿误标为已保存。
+                const controls = [label, avatar, description, verbosity, emoji, address, ...examples, enabled];
+                controls.forEach(control => { control.disabled = true; });
+                try {
+                    const result = await run(() => api('POST', `/api/ai/admin/personalities/${encodeURIComponent(profile.key)}`, {
+                        ...values(), version: profile.version,
+                    }).catch(error => { status.textContent = error.message; throw error; }), '性格已保存', save);
+                    if (result) {
+                        profile = result;
+                        drafts.delete(result.key);
+                        catalog.items = [...catalog.items.filter(p => p.key !== result.key), result];
+                        status.textContent = `已保存 · 版本 ${result.version} · 后续消息生效`;
+                        drawCards();
+                        drawDefault();
+                    }
+                }
+                finally {
+                    saving = false;
+                    controls.forEach(control => { control.disabled = false; });
+                }
+            } }, h('div', { class: 'persona-section-heading' }, h('span', { class: 'eyebrow' }, 'CHARACTER'), h('h2', {}, '定义它的表达方式')), h('div', { class: 'persona-fields' }, field('性格名称', label), field('头像符号', avatar, '输入一个表情或短符号'), field('回复长度', verbosity), field('表情使用', emoji)), field('性格描述', description), field('如何称呼用户', address), h('div', { class: 'persona-examples' }, h('strong', {}, '说话示例'), h('small', {}, '两三句自然的话，帮助助理找到语气。'), examples), h('label', { class: 'persona-enabled' }, enabled, '允许用户选择此性格'), h('div', { class: 'persona-save-row' }, status, save));
+        const output = h('div', { class: 'persona-preview-answer', role: 'log', 'aria-live': 'polite' }, '先打个招呼，听听它会怎么说。');
+        const message = h('textarea', { rows: 2, required: true, maxlength: 2000, 'aria-label': '试聊消息', value: '今天事情有点多，你能怎么帮我？' });
+        const previewStatus = h('p', { class: 'persona-preview-status', role: 'status' });
+        const tryButton = h('button', { class: 'primary', type: 'submit' }, '试聊一下');
+        const stop = h('button', { type: 'button', hidden: true, onclick: () => activePreview?.abort() }, '停止');
+        const preview = h('form', { class: 'persona-preview', onsubmit: async (event) => {
+                event.preventDefault();
+                if (activePreview || !form.reportValidity())
+                    return;
+                const controller = new AbortController();
+                activePreview = controller;
+                tryButton.disabled = true;
+                stop.hidden = false;
+                output.textContent = '';
+                previewStatus.textContent = '正在准备回复…';
+                let done = false;
+                const abort = () => controller.abort();
+                window.addEventListener('hashchange', abort, { once: true });
+                window.addEventListener('cage:session-expired', abort, { once: true });
+                try {
+                    await postEvents('/api/ai/admin/personality-preview', { profile: values(), message: message.value }, value => {
+                        if (value.type === 'delta') {
+                            output.append(document.createTextNode(value.text));
+                            previewStatus.textContent = '正在回复…';
+                        }
+                        if (value.type === 'done') {
+                            output.textContent = value.result.text;
+                            previewStatus.textContent = `试聊完成 · ${(value.result.latencyMs / 1000).toFixed(1)} 秒`;
+                            done = true;
+                        }
+                        if (value.type === 'error')
+                            throw new Error(value.code === 'RATE_LIMITED' ? '已有试聊正在进行，请稍后重试' : `试聊未完成（${value.code}），请检查模型配置后重试`);
+                    }, controller.signal);
+                    if (!done)
+                        throw new Error('试聊连接中断，请重试');
+                }
+                catch (error) {
+                    previewStatus.textContent = controller.signal.aborted ? '已停止，保留已收到的文字' : error.message;
+                }
+                finally {
+                    window.removeEventListener('hashchange', abort);
+                    window.removeEventListener('cage:session-expired', abort);
+                    if (activePreview === controller)
+                        activePreview = null;
+                    tryButton.disabled = false;
+                    stop.hidden = true;
+                }
+            } }, h('span', { class: 'eyebrow' }, 'SAY HELLO'), h('h2', {}, '先聊两句'), h('p', { class: 'persona-preview-intro' }, '直接体验当前草稿的语气，不必先保存。这里仅预览表达风格，不处理实际业务。'), output, previewStatus, field('你想说什么', message), h('div', { class: 'persona-preview-actions' }, stop, tryButton));
+        editor.replaceChildren(form, preview);
+    }
+    const create = h('button', { class: 'primary', onclick: () => {
+            if (saving)
+                return;
+            const key = `custom-${crypto.randomUUID()}`;
+            drafts.set(key, { key, label: '我的助理', avatar: '✨', description: '', verbosity: 'balanced', address: '', emoji: 'light', examples: [], enabled: true, version: 0, builtin: false, updatedAt: null });
+            selected = key;
+            drawCards();
+            drawEditor();
+            editor.scrollIntoView({ behavior: 'smooth', block: 'start' });
+        } }, '＋ 自定义性格');
+    main.append(h('div', { class: 'persona-overview' }, h('div', {}, h('span', { class: 'eyebrow' }, 'A LITTLE CHARACTER'), h('h2', {}, '同样的可靠，多一点个性。'), h('p', {}, '选一种合拍的语气，或创造属于团队的助理。')), create), defaults, grid, editor);
+    drawDefault();
+    drawCards();
+    drawEditor();
+}

package/ui/dist/modules/roles/index.js

@@ -1 +1,5 @@
+/**
+ * 角色能力和范围配置模块的公开入口。
+ * 应用壳通过这里组合页面，其他模块无需依赖内部表单实现；导出本身不发请求或执行管理操作。
+ */
 export { renderRoles } from './roles-page.js';