@xgent-ai/skills 0.3.0 → 0.5.0

package/skills/grafton-view-dev/references/recipes.md

@@ -1,208 +0,0 @@
-# Recipes：可复用 worked 示例
-
-可直接抄改的完整模式。每个示例只给 schema/代码 + 一句上下文；语义细节去对应主题文件查（[bindings](bindings.md) / [schema](schema.md) / [stores](stores.md) / [components](components.md)）。
-
-## 1. 一个完整 view（store + schema + createView）
-
-```js
-// stores/tasks.js —— 导出工厂函数
-import { Runtime, createStore } from '@xgent-ai/grafton';
-
-const tasksStore = () =>
-  createStore('tasks')({ tasks: [], filter: 'all', loading: false, loadError: null })
-    .extendSelectors(() => ({
-      total: (s) => s.tasks.length,
-      remaining: (s) => s.tasks.filter((t) => !t.done).length,
-      visibleTasks: (s, filter) =>
-        filter === 'active' ? s.tasks.filter((t) => !t.done)
-        : filter === 'done' ? s.tasks.filter((t) => t.done)
-        : s.tasks,
-    }))
-    .extendActions((api) => ({
-      addTask: (title) => api.set.state((d) => { d.tasks.push({ $key: 'id', id: Date.now(), title, done: false }); }),
-      toggleTask: (id) => api.set.state((d) => { const t = d.tasks.find((x) => x.id === id); if (t) t.done = !t.done; }),
-      clearDone: () => api.set.state((d) => { d.tasks = d.tasks.filter((t) => !t.done); }),
-    }));
-export default tasksStore;
-```
-
-```jsx
-// pages/home.jsx
-import { createView } from '@xgent-ai/grafton';
-import { Button } from '@xgent-ai/ui-shadcn';            // 非内置组件必须注册
-import schema from '../views/home.view.json';
-import tasksStore from '../stores/tasks';
-
-export default createView({
-  displayName: 'HomePage',
-  ns: 'taskboard',
-  stores: { tasks: tasksStore },                       // view store 自动附加
-  registry: { Button },
-  schema,
-});
-```
-
-> 视图必须渲染在 `RouterProvider` 内（内置导航动作依赖 router）。
-
-## 2. 数据驱动列表 + 空状态
-
-推荐写法:单个 `List`,网格类挂 `className`(真实容器),空态用 `emptyState` slot —— 一个节点搞定,不用对偶 `$when`:
-
-```jsonc
-{
-  "$type": "List",
-  "variant": "none",
-  "className": "grid grid-cols-1 gap-2 sm:grid-cols-2 lg:grid-cols-3",
-  "data": "@store::tasks.tasks",
-  "itemTemplate": {
-    "$type": "HBox", "$style": "items-center gap-3 rounded-lg border p-3",
-    "$content": [
-      {
-        "$type": "Button", "variant": "ghost", "size": "icon-sm",
-        "$content": { "$if": "@local::data.done", "$then": "✓", "$else": "○" },
-        "onClick": { "$action": "@action::tasks.toggleTask", "$args": ["@local::data.id"], "$withEventArgs": false }
-      },
-      { "$type": "Text", "text": "@local::data.title", "noTranslate": true,
-        "$style": { "$if": "@local::data.done", "$then": "line-through text-muted-foreground", "$else": "" } }
-    ]
-  },
-  "emptyState": {
-    "$type": "VBox",
-    "$style": "items-center gap-2 rounded-lg border border-dashed p-8 text-muted-foreground",
-    "$content": [{ "$type": "Text", "text": "app.empty" }, { "$type": "Text", "text": "app.emptyHint" }]
-  }
-}
-```
-
-要点：列表 key 由**数据**携带（store 里 `$key: 'id'`）；空态优先用 `emptyState` slot(`List`/`PlainList`/`DataList` 都支持);per-item action 用 `$args: ["@local::data.id"]` + `$withEventArgs: false`。
-
-> **网格布局**：网格类挂在 `List` 的 `className` 上（`List` 是真实 `ul`/`ol` 容器）。**别**把网格容器放进 `before`/`after` slot —— 那是夹在列表项前后的兄弟节点、不包裹卡片,网格不生效。`PlainList` 容器是 `Fragment`、做不了网格,要网格卡片就用 `List`。
->
-> **空状态**:首选 `emptyState` slot(如上,data 空/null 时渲染,进入该分支时 before/after/列表项都不渲染)。另一种是不挂 slot、在列表外用 `$when:_isEmpty` 的对偶节点控制 —— 两者皆可,slot 更简洁。详见 [components.md](components.md)。
-
-## 3. 双向绑定过滤器（带参 selector + `<>`）
-
-```jsonc
-// 过滤控件:必须 <> 绑定(bindable 受控组件传静态值只读)
-{ "$type": "FilterTabs", "value": "<>@store::tasks.filter",
-  "options": [ { "value": "all", "label": "All" }, { "value": "active", "label": "Active" }, { "value": "done", "label": "Done" } ] }
-
-// 列表把过滤状态接进带参 selector,$ifNull 兜底
-{ "$type": "List", "data": { "$selector": "@store::tasks.visibleTasks", "$args": [{ "$ifNull": "@store::tasks.filter", "$then": "all" }] } }
-```
-
-## 4. 异步加载 + loading / 错误态
-
-```js
-// store action(放在 extendActions 内)
-loadTasks: async () => {
-  api.set.loading(true); api.set.loadError(null);
-  try {
-    const data = await Runtime.$api.get_('/tasks');
-    api.set.tasks(data.map((t) => ({ ...t, $key: 'id' })));   // 顺手带列表 key
-  } catch (err) {
-    api.set.loadError(err);                                    // 存 Error,ErrorPanel 读 error.message
-  } finally {
-    api.set.loading(false);
-  }
-},
-```
-
-```jsonc
-[
-  { "$type": "Button", "variant": "outline", "$content": "Reload",
-    "disabled": "@store::tasks.loading", "onClick": "@action::tasks.loadTasks" },
-  { "$type": "Text", "text": "Loading...", "noTranslate": true, "$when": "@store::tasks.loading" },
-  { "$type": "ErrorPanel", "error": "@store::tasks.loadError",
-    "$when": { "$selector": "!@view::_isNull", "$args": ["@store::tasks.loadError"] } }
-]
-```
-
-> 进场自动加载用节点 `$effects` + store `extendSideEffect`（见 [stores.md](stores.md)）；或惰性用 `createApiStore`。
-
-## 5. 自定义 widget：slots + bindable(signal)
-
-```jsx
-// slots widget —— 插槽值是 schema,grafton 渲染成 ReactNode 再传入
-function TaskItem({ title, done, statusIcon, actions, className }) {
-  return (<div className={cn('flex items-center gap-3 rounded-lg border p-3', className)}>
-    {statusIcon}<span className={cn(done && 'line-through text-muted-foreground')}>{title}</span>
-    <div className="ml-auto flex gap-1">{actions}</div></div>);
-}
-TaskItem.grafton = { leaf: true, slots: ['statusIcon', 'actions'] };
-
-// bindable widget —— signal() 解包;传静态值时 setCurrent 是 no-op(退化只读)
-import { signal } from '@xgent-ai/grafton';
-function FilterTabs({ value, options = [] }) {
-  const [current, setCurrent] = signal(value ?? 'all');
-  return (<div className="inline-flex rounded-lg border p-0.5">{options.map((o) => (
-    <button key={o.value} type="button" onClick={() => setCurrent(o.value)}
-      className={cn('rounded-md px-3 py-1 text-sm', current === o.value && 'bg-secondary font-medium')}>{o.label}</button>
-  ))}</div>);
-}
-FilterTabs.grafton = { leaf: true, bindable: ['value'] };
-```
-
-```jsonc
-// TaskItem 的插槽 schema 里照常能用 @local::(列表项 payload 可见)
-{ "$type": "TaskItem", "$mapping": { "title": "title", "done": "done" },
-  "statusIcon": { "$type": "Button", "variant": "ghost", "size": "icon-sm",
-    "$content": { "$if": "@local::data.done", "$then": "✓", "$else": "○" },
-    "onClick": { "$action": "@action::tasks.toggleTask", "$args": ["@local::data.id"], "$withEventArgs": false } } }
-```
-
-## 6. 表单（Form + 字段 + onSubmit + 实时预览）
-
-```jsx
-import { Form, FormInput, FormSelect, ButtonWidget } from '@xgent-ai/ui-shadcn/widgets';
-// createView registry 里加: { Form, FormInput, FormSelect, ButtonWidget }
-```
-
-```jsonc
-{
-  "$type": "Form", "className": "flex items-end gap-2",
-  "defaultValues": { "title": "", "priority": "normal" },
-  "onSubmit": "@action::tasks.addFromForm",
-  "$content": [
-    { "$type": "FormInput", "name": "title", "label": "New task", "rules": { "required": true } },
-    { "$type": "FormSelect", "name": "priority", "label": "Priority",
-      "items": [ { "value": "normal", "label": "Normal" }, { "value": "high", "label": "High" } ] },
-    { "$type": "ButtonWidget", "type": "submit", "text": "Add" },
-    // 实时预览:Form 子树内 @form::watch 读字段
-    { "$type": "Text", "className": "text-xs text-muted-foreground", "noTranslate": true,
-      "text": { "$selector": "@form::watch", "$args": ["title"] },
-      "$when": { "$selector": "!@view::_isEmpty", "$args": [{ "$selector": "@form::watch", "$args": ["title"] }] } }
-  ]
-}
-```
-
-```js
-// action 收到表单值对象
-addFromForm: (values) => api.set.state((d) => {
-  d.tasks.push({ $key: 'id', id: Date.now(), title: values.title, done: false, priority: values.priority });
-}),
-```
-
-## 7. i18n 语言切换（逻辑放 store action）
-
-```js
-switchLanguage: () => {
-  const i18n = Runtime.i18n;
-  i18n.changeLanguage(i18n.language?.startsWith('zh') ? 'en' : 'zh');
-},
-```
-```json
-{ "$type": "Button", "variant": "ghost", "size": "sm", "$content": "中 / EN", "onClick": "@action::tasks.switchLanguage" }
-```
-
-## 8. 多页应用：页面级树按路由 key 重挂载（必做）
-
-不同 schema = 不同 hooks 序列，React 同位复用会崩（"change in the order of Hooks called by Grafton"）。路由出口给页面包带 key 的容器：
-
-```jsx
-import { useLocation } from '@xgent-ai/router-lite';
-function PageOutletWrapper({ children }) {
-  const { pathname } = useLocation();
-  return <Fragment key={pathname}>{children}</Fragment>;
-}
-```

package/skills/grafton-view-dev/references/schema.md

@@ -1,86 +0,0 @@
-# Schema 节点 / createView / createLazyView
-
-schema 节点的结构与视图工厂。读本文当：拿不准某个 `$xxx` 节点键的语义、`$type` 为什么解析不到、createView 接什么参数、视图组件渲染时还能传什么 props。
-
-## $type 解析顺序
-
-1. **HTML 标签白名单**（小写）：`div` `span` `input` `a` `p` `nav` `section` `article` `aside` `header` `footer` `img` `video` `audio`
-2. **当前组件的局部注册表**（`Component.grafton.registry`，见 [components.md](components.md)）
-3. **祖先累积的 payload registry**（局部注册表沿子树向下继承）
-4. **view registry**（`createView` 传入 + grafton 内置组件）
-
-全部未命中则抛错，由 `ErrorBoundary` 捕获渲染为红色 `ErrorPanel`。
-
-## 节点级特殊键
-
-| 键 | 类型 | 语义 |
-|----|------|------|
-| `$type` | string | 组件类型（必填） |
-| `$content` | string \| object \| array | 子内容 → React children。只渲染 truthy 值；数组渲染为元素列表；`leaf` 组件禁止使用 |
-| `$when` | 表达式 | 求值**严格等于 `false`** 时整个节点不渲染。⚠️ `0`、`""`、`null` 等 falsy 值**不会**隐藏节点；要布尔语义配 `_isEmpty`/`_isNull` 或 `!` 取反 |
-| `$payload` | object | 声明 payload 变量，与父级 payload 合并后传给子树（子树用 `@local::` 读）；值支持绑定表达式 |
-| `$clearParentPayload` | boolean | 为真时子树不继承父级 payload（含累积的 registry） |
-| `$style` | string | 追加 className（与已有 `className` 用 `cn()` 合并）。惯例：基础类写 `className`，动态/附加类写 `$style` |
-| `$tooltip` | string \| object | 给节点包一层 Tooltip；字符串等价 `{title: ...}` |
-| `$action` | string \| function | 快捷链接：字符串作 href（`"_target:href"` 可指定 target），函数包成 `<a onClick>` |
-| `$breakpointProps` | object | 响应式 props：`{sm: {...}, md: {...}}`，按当前断点级联合并 |
-| `$extendSchema` | 引用 | 运行时扩展：引用求值出的对象浅合并进当前节点 props |
-| `$effects` | array | 副作用列表，项为 `"store.effectName"` 或 `{$effect, $args}`（见 [stores.md](stores.md) 的 extendSideEffect） |
-| `$key` | string | 渲染时剥离，不传给组件。列表外层 key 只在**数据项自身**含 `$key` 时由 `ListRenderer` 使用（见 [components.md](components.md) 的 renderers） |
-| `$mapping` | object | 列表模板中的字段映射 `{propName: fieldName}` |
-| `$debug` | boolean | 控制台输出该节点的 getters / hooks 信息 |
-| `$comment` | any | 注释，渲染时忽略 |
-
-```jsonc
-{
-  "$type": "div",
-  "$when": { "$selector": "!@view::_isEmpty", "$args": ["@store::app.items"] },
-  "$style": "p-4 border rounded",
-  "$tooltip": "common.hint",
-  "$content": [{ "$type": "Text", "text": "hello" }]
-}
-```
-
-## createView 参数
-
-| 参数 | 说明 |
-|------|------|
-| `schema` | 视图 schema（必填） |
-| `registry` | `$type` → 组件映射，自动并入 grafton 内置组件；`icons` / `schemas` / `hooks` 子对象自动展开为命名空间条目（见 [components.md](components.md) 的局部注册表） |
-| `stores` | store 工厂映射 `{name: creator}`，自动附加内置 `view` store |
-| `actions` | 全局动作映射 |
-| `ns` | i18n 默认命名空间 |
-| `rootPayload` | 根节点初始 payload |
-| `noTranslate` | 不包 `withTranslation()` HOC |
-| `displayName` | 组件名（调试用） |
-
-## 视图组件的渲染期 props
-
-`createView` 返回的组件在渲染时还接受：
-
-| prop | 说明 |
-|------|------|
-| `debug` | 输出渲染日志 |
-| `ns` | 覆盖默认命名空间 |
-| `registry` / `actions` | 追加/覆盖 view model 中的同名配置 |
-| `storesMapping` | store 别名映射 `{schema中的名: 实际store名}`，绑定解析时换名 |
-| `tooltipProps` | 传给内置 TooltipProvider |
-| **其余 props** | 全部传给内部 StoresProvider，作为 **store 工厂的入参**（如内置 view store 消费的 `data` / `selectors`，见 [stores.md](stores.md)） |
-
-## createLazyView
-
-从 URL 异步加载 schema，带缓存与 Suspense：
-
-```js
-const Page = createLazyView({
-  schemaUrl: '/schemas/page.view.json',   // 必填
-  loadingFallback: () => <Spinner />,     // 可选
-  // 其余 createView 参数(registry / stores / actions / ns ...)照常可用
-});
-```
-
-schema 首次拉取后缓存；同一 `schemaUrl` 不重复请求。
-
-## schema 外置
-
-schema 是纯 JSON，可从 `.jsx` 搬到 `.json` 文件，由 `createView({ schema })` 引入；放在 `src/` 内 Tailwind v4 能自动扫到类名。这是 schema 驱动的核心收益（独立存储、下发、非前端角色维护）。更进一步用 `createLazyView` 从 URL 动态下发。

package/skills/grafton-view-dev/references/stores.md

@@ -1,310 +0,0 @@
-# Stores / Runtime / HttpClient
-
-状态层（zustood = zustand 封装）与数据获取。读本文当：写 `createStore` 及 `extendSelectors`/`extendActions`/`extendMemoSelectors`/`extendSideEffect`、用 `createApiStore`/`createEntityStore`/`createListStore`、在组件代码里用 store hooks、在 store action 里发 HTTP 请求。
-
-## 工厂约定
-
-store 总是**工厂函数**，交给 `createView`（或手挂 `StoresProvider`）在渲染时实例化：
-
-```js
-const myStore = (props, parentStores, getStores) =>
-  createStore('my')({ /* initialState 必填 */ }, { /* options 可选 */ })
-    .extendSelectors(/* ... */)
-    .extendActions(/* ... */);
-```
-
-| 参数 | 说明 |
-|------|------|
-| `props` | StoresProvider 收到的 props（经 createView 即视图组件的"其余 props"，如 `data`/`selectors`）—— 初始状态可由运行时 props 决定 |
-| `parentStores` | 父级 StoresProvider 的 stores（顶层为 undefined）；内置 view selector `_parent` 即由此实现 |
-| `getStores` | 返回"正在构建中的当前 store 集合"，允许同级 store 互相引用 |
-
-工厂上可附加 **`canOverride = true`**：嵌套 Provider 遇父级同名 store 时，默认**沿用外层不重建**；只有 `canOverride` 的工厂才在内层重建（内置 view store 即如此）。
-
-## 自动生成的接口
-
-`createStore(name)(initialState)` 返回：
-
-| 成员 | 说明 |
-|------|------|
-| `name` | store 名 |
-| `store` | 原始 zustand store（`getState`/`setState`/`subscribe`） |
-| `get.<key>()` | 每个状态 key 的同步读 |
-| `get.state()` | 整个 state 快照 |
-| `set.<key>(v)` | 每个状态 key 的写；**新旧值 `===` 时跳过**（不触发更新） |
-| `set.state(objOrFn)` | 整包写；传函数时为 **immer draft**，可原地修改 |
-| `use.<key>()` | 每个状态 key 的 React hook 订阅（浅比较去重） |
-| `useState(selector)` | 任意 selector 的 hook 订阅（浅比较） |
-| `extendSelectors` / `extendMemoSelectors` / `extendActions` / `extendSideEffect` | 链式扩展，均返回 store 自身，可任意顺序续链 |
-
-schema 侧：`@store::my.x` 读 → `use.x()`；`@action::my.x` 写 → `set.x`。
-
-## 内置 set 动作
-
-除 per-key setter 外，`set` 上始终可用：
-
-| 动作 | 说明 |
-|------|------|
-| `set.state(objOrFn)` | 整包写（immer） |
-| `set.toggleState(path)` | 翻转布尔字段；支持深路径 `"ui.sidebarOpen"` |
-| `set.enableState(path)` / `set.disableState(path)` | 置 true / false（深路径） |
-| `set.useSideEffect(key, ...args)` | 调用 extendSideEffect 定义的副作用 hook |
-
-schema 中即 `@action::my.toggleState` 配 `$args: ["open"]`。
-
-## extendSelectors
-
-```js
-.extendSelectors((api) => ({
-  total: (state) => state.items.length,
-  hasItem: (state, id) => state.items.some((i) => i.id === id),   // 带参
-  title: (state, prefix) => prefix + api.get.total(),             // 引用其他 selector
-}))
-```
-
-- 回调收到 **store api 本身**，selector 间可 `api.get.xxx()` 复用；
-- 签名 `(state, ...args) => value`；
-- 每个 selector 暴露为 `get.<name>(...args)`（同步）与 `use.<name>(...args)`（hook，浅比较）；schema 中无参 `@store::s.total`，带参用 `{ "$selector": "@store::s.hasItem", "$args": [42] }`；
-- ⚠️ selector 每次调用都执行；hook 侧靠**浅比较**去重，返回"每次新建的深对象"仍被视为变化 → 用 `extendMemoSelectors`。
-
-## extendMemoSelectors
-
-带缓存：deps 浅比较未变则返回缓存，不重算。
-
-```js
-.extendMemoSelectors((api) => ({
-  siteMenu: {
-    deps: (state) => ({ sitemap: state.sitemap }),     // 轻量依赖提取
-    selector: ({ sitemap }) => sitemap.map(toMenu),    // 昂贵计算，入参是 deps 返回值
-  },
-  // 二元组写法(兼容): siteMenu: [ (state)=>({...}), ({sitemap})=>... ]
-}))
-```
-
-- `deps` 也可写**字符串**引用已存在的 selector 名；
-- 调用传入的 `...args` 转交给 deps（`deps(state, ...args)`）；
-- ⚠️ 每个 memo selector **只有一个缓存槽**：交替用不同参数调用会互相挤掉缓存，参数高频交替场景不适用。
-
-## extendActions
-
-```js
-.extendActions((api) => ({
-  addItem: (item) => api.set.state((draft) => { draft.items.push(item); }),
-  reset: () => { api.set.addItem({ id: 0 }); api.set.count(0); },   // action 互调
-  load: async () => {                                              // 可 async
-    const data = await Runtime.$api.get_('/items');
-    api.set.items(data);
-  },
-}))
-```
-
-- 闭包式普通函数，挂到 `set`；通过闭包里的 `api` 读写；
-- 与同名条目（自动 setter 或先前 action）重名时**覆盖**，旧实现保留在 `新函数.origin`，可在新实现内调用；
-- schema 中 `@action::store.x` 匹配顺序：action → 自动 setter → 内置 set 动作。
-
-## extendSideEffect 与 $effects
-
-由 React 渲染驱动的副作用（内部包 `useEffect`）：
-
-```js
-.extendSideEffect((api) => ({
-  syncTitle: {
-    deps: (state, suffix) => [state.title, suffix],   // 必须返回数组(useEffect deps)
-    effect: (title, suffix) => {                      // 入参为 deps 数组展开
-      document.title = title + suffix;
-      return () => { /* 可返回清理函数 */ };
-    },
-  },
-}))
-```
-
-消费两条途径（本质都是渲染期调 `store.set.useSideEffect(key, ...args)`）：
-1. **schema 节点 `$effects`**：项为 `"store.effectName"` 或 `{ "$effect": "store.effectName", "$args": [...] }`；
-2. **值级 `$effect` 对象**（见 [bindings.md](bindings.md)）。
-
-⚠️ 副作用 hook 参与组件 hooks 序列 —— 同一位置节点增删 `$effects` 需重挂载（见 SKILL.md 坑 #3）。
-
-## 配置项（createStore options）
-
-```js
-createStore('my')(initialState, {
-  isGlobal: true,
-  middlewares: [myMiddleware],
-  devtools: { enabled: true },
-  persist: { enabled: true, name: 'my-storage' },
-  persistX: { enabled: true, storage: customStorage },   // 任意 persist* 前缀 = 一条独立通道
-})
-```
-
-| 选项 | 说明 |
-|------|------|
-| `isGlobal` | 注册进 `Runtime.stores`（见下） |
-| `middlewares` | 自定义 zustand 中间件；immer 始终内置（`set.state(fn)` 一定是 draft 语义） |
-| `devtools` | Redux DevTools。⚠️ **必须先在 `Runtime.init` 的 `addons` 注入 `storeDevTools`**，否则 `enabled: true` 直接抛错；`name` 自动填 store 名 |
-| `persist` | 持久化（默认 localStorage）。键：`enabled`、`name`、`storage`（实现 `getItem/setItem/removeItem`）、`version`+`migrate`、`partialize`（白名单）、`merge`、`priority` |
-| `persist*`（任意前缀） | 除 `persist` 外任何以 `persist` 开头的键 = 一条额外持久化通道（`persistX`、`persistSession`），配置同上；控制接口挂在 `store.<键名>` |
-
-持久化通道运行时接口（`store.persist.*` / `store.<通道名>.*`）：`hasHydrated()`、`onHydrate(cb)`、`onFinishHydration(cb)`、`setOptions()`、`clearStorage()`。**水合是异步的**，初始渲染可能在水合完成前发生。辅助：`getAppPersistName(module)` → `` `${Runtime.config.app}-${module}` ``。
-
-## 全局 store
-
-`isGlobal: true` 创建时注册进 `Runtime.stores[name]`（重名抛错），生命周期脱离 React 树；**顶层** StoresProvider 解析 store 时先复用全局注册表中同名实例。适用跨视图共享、与组件生命周期无关的状态（会话、主题）。
-
-## StoresProvider
-
-`createView` 内部用它创建 stores，一般不需手挂。纯 React 代码中提供 store：
-
-```jsx
-import { StoresProvider } from '@xgent-ai/grafton';
-
-<StoresProvider creators={{ tasks: tasksStore }} {...props}>
-  {children}
-</StoresProvider>
-```
-
-- `creators` 是工厂映射；除 `children`/`creators` 等保留 prop 外，**其余 props 都传给每个工厂**作第一参数；
-- 嵌套中同名 store 默认沿用外层，工厂带 `canOverride = true` 才内层重建；
-- Provider 的 props **深比较**变化时重建可重建的 store（给视图传新 `data` 重建 view store 即此机制 —— 及其局限见 SKILL.md 坑 #4）。
-
-## React hooks（组件代码访问 store，均从 `@xgent-ai/grafton` 导出）
-
-| hook | 签名 | 返回 |
-|------|------|------|
-| `useStores()` | — | 全部 stores 映射 |
-| `useStore(name)` | string | 单个 store（不存在抛错） |
-| `useActions(name)` | — | 该 store 的 `set`（全部动作） |
-| `useStoreState(name, selector)` | `(state)=>v` | 自定义 selector 订阅 |
-| `useStateActions(name, key)` | 点分路径 / path array / selector | `[值, store.set]` 元组 |
-| `useSelector(pathKey, ...args)` | `"store.xxx.yyy"` | 见下 |
-| `useSignal(pathKey, storesMapping?)` | `"store.key"` / `"store.a.b"` | `[value, setter]` |
-| `signal(propValue)` | 组件作者用 | `[value, setter]`（见 [bindings.md](bindings.md)） |
-
-`useSelector` 路径语义：
-- **不带 args**：`"tasks.filter"` —— 首段 store 名，第二段按 selector/状态 key 取值，后续段逐级取；段支持 `.$` 操作符（`"tasks.items.$size"`）；首段以 `$` 开头时对全量 state 走路径；
-- **带 args**：`useSelector('tasks.hasItem', 42)` —— 路径只允许 `store.selector` 两段。
-
-`useSignal` setter：单段 key 走 `store.set[key]`（自动 setter **或同名 action**），多段走 `set.state` + 深路径写入。
-
-## 内置 view store
-
-每个视图自带（工厂 `canOverride = true`）：
-
-- 渲染时 **`data` prop 成初始状态**（每 key 有自动 setter → `@view::xxx` 支持 `<>` / `@action::view.xxx` 可写）；
-- **`selectors` prop** 追加自定义 selector（签名同 extendSelectors）；
-- 内置工具 selector（`@view::_xxx`，均可配 `$args`）：
-
-| selector | 作用 |
-|----------|------|
-| `_toPath(...parts)` | `Runtime.basePath` + 片段拼路径 |
-| `_toHref(url, options, local)` | URL 更新（query 等） |
-| `_urlJoin(...args)` | 纯拼接（不含 basePath） |
-| `_isNull(v)` | `v == null` |
-| `_isEmpty(v)` | 空数组/对象/字符串/null |
-| `_isStrictlyEqual(a, b)` | 双非空且 `===` |
-| `_isEqual(a, b)` | 深比较 |
-| `_and(...args)` / `_or(...args)` | 布尔组合 |
-| `_template(text, data)` | 字符串模板插值 |
-| `_omitNull(obj)` | 去掉空值字段 |
-| `_filterOut(data, key, value)` | 排除 `item[key]` 等于 value（或 value 数组中任一）的项；key 支持深路径 |
-| `_parent` | 父视图的 view store（嵌套取上层） |
-
-## createApiStore
-
-普通 store + "API 获取 + 缓存 + Suspense"：每个 API 一个**惰性 selector**，首次读取才发请求，结果缓存。
-
-```js
-const productStore = () =>
-  createApiStore('product')(
-    { selectedId: null, total: 0 },
-    {
-      productList: {
-        fetcher: async (api) => Runtime.$api.get_('/products'),
-        transformer: (result) => { const { products, ...payload } = result; return [products, payload]; },
-        onSuccess: (api, _products, payload) => api.set.total(payload.total),
-      },
-      selectedProduct: {
-        deps: (state) => (state.selectedId ? [state.selectedId] : null),
-        fetcher: async (api, id) => Runtime.$api.get_(`/products/${id}`),
-      },
-    },
-    { /* 常规 options 可选 */ },
-  );
-```
-
-| 键 | 默认 | 说明 |
-|----|------|------|
-| `fetcher` | 必填 | `async (storeApi, ...args) => raw` |
-| `deps` | — | `(state, ...args) => argsArray \| null`：派生 fetcher 参数；返回 `null` = 依赖未就绪不发请求。⚠️ 不配 `deps` 时该 API 的 selector **不允许带参** |
-| `preload` | — | `true` 或参数数组：创建 store 时立即调用一次 |
-| `suspenseOnPending` | `true` | 首次加载抛 Promise 走 Suspense |
-| `suspenseOnReloading` | `false` | 重载也走 Suspense |
-| `minSuspensePeriod` | `2000` | Suspense 最短挂起（毫秒，防闪烁） |
-| `consumeDataOnly` | `true` | selector 只返回 `data`；false 时返回 `{pending, reloading, fetched, data, error}` |
-| `transformer` | 取 `result.data` | `(raw, api) => [data, payload]`。**默认解构 `{data, ...payload}`** —— ⚠️ 响应不是这形状必须自定义，否则存入 `undefined` |
-| `onSuccess` | — | `(storeApi, data, payload) => {}` |
-| `onError` | — | `(storeApi, error) => {}` |
-
-自动生成：selector `use.<apiName>(...args)` / `get.<apiName>(...args)`；actions `set.apiMutate(name, data, payload)`（改写缓存）、`set.apiDrop(name)`（清缓存）、`set.apiReload(name)`（重请求，新数据到达前保留旧数据）。`deps` 返回值（深比较）变化时下次读取自动重载。
-
-## createEntityStore
-
-按 **id 缓存实体**（详情页/逐项加载）：
-
-```js
-const userEntities = () =>
-  createEntityStore('users')({}, {
-    loadById: async (id, api) => Runtime.$api.get_(`/users/${id}`),
-    // 可选: suspenseOnPending / minSuspensePeriod / transformer / onSuccess / onError
-  });
-```
-
-| 接口 | 说明 |
-|------|------|
-| `use.byId(id)` | hook；缓存未命中触发加载并抛 Promise（Suspense） |
-| `use.entities` | hook；返回缓存 **Proxy**，`entities[id]` 取值即触发惰性加载 |
-| `get.byId(id)` / `get.byIdNow(id)` | 同步读缓存，未命中返 null，**不触发**加载 |
-| `get.entitiesCache()` | 原始缓存映射 |
-| `set.mutateById(id, data, payload?)` | 直接写缓存（不请求） |
-| `set.dropById(id)` | 删除缓存项 |
-| `set.reloadById(id)` | 重新加载单个实体 |
-| `set.prefetchById(id)` | 预取：发起加载但**不抛** Suspense |
-
-内部键 `__entityCache` / `__entityStatus` 为实现细节，勿直接读写。
-
-## createListStore
-
-列表/表格数据（快照含 schema 元数据与分页游标）：
-
-```js
-const ordersList = () =>
-  createListStore('orders')({}, {
-    load: async (api, cursor) => Runtime.$api.get_('/orders', { cursor }),
-    // load 必须 resolve 为 { schema, rows, totalRows?, cursor? }
-    // 可选: transformer / suspenseOnPending / suspenseOnReloading / minSuspensePeriod / onSuccess / onError
-  });
-```
-
-| 接口 | 说明 |
-|------|------|
-| `use.list()` | hook；首次读取触发加载（Suspense），返回 `{schema, rows, totalRows, cursor, pending, reloading, error}` |
-| `get.list()` | 同步读当前快照，不触发加载 |
-| `set.reload()` | 重新加载并**替换** rows |
-| `set.loadMore()` | 以当前 cursor 调 `load`，结果 rows **追加** |
-| `set.setCursor(c)` | 显式设置下次 loadMore 的游标 |
-
-内部键 `__list` 为实现细节，勿直接读写。
-
-## Runtime & HttpClient（数据获取所需）
-
-`Runtime` 全局单例，`Runtime.init(config, mode)` 应用入口调一次（先于任何视图渲染）。`mode` 以 `'production'` 开头视为生产，反映在 `Runtime.isDevMode`。完整 app 配置（grafton-app.json / services / i18n / addons）属 `web-app-dev` skill 范畴；view 开发只需知道：
-
-- `services` 每个条目实例化为 `HttpClient`，挂在 **`Runtime.$<服务名>`**。`Runtime.createServiceClient(nameOrOptions)` 手建。
-- `Runtime.$<name>` 的方法（带下划线后缀）：`get_(path, query?, options?)`、`delete_(path, query?, options?)`、`post_(path, body?, query?, options?)`、`put_(...)`、`patch_(...)`，返回解析后数据的 Promise。
-- options 常用键：`endpoint`（覆盖端点）、`headers`（鉴权 token）、`timeout`、`withCredentials`、`onSending`、`onResponse`/`onResponseError`/`onOtherError`、`formData`/`fileField`/`fileName`/`onProgress`（上传）、`usePipe`（流式）。
-
-```js
-const list = await Runtime.$api.get_('/tasks', { page: 1 }, { timeout: 5000 });
-const created = await Runtime.$api.post_('/tasks', { title: 'x' }, null, { headers: { Authorization: `Bearer ${token}` } });
-```
-
-其他静态成员：`Runtime.config`、`Runtime.i18n`（`changeLanguage`/`language`）、`Runtime.logger`、`Runtime.stores`、`Runtime.toLocalPath(...parts)`、`Runtime.registerGlobalStore(store)`、结构化日志 `Runtime.log`/`logEvent`/`logError`/`logApi`/`logAction`。

package/skills/portal-backend-app/SKILL.md

@@ -1,56 +0,0 @@
----
-name: portal-backend-app
-description: '在本 monorepo 内新增或修改「独立后端 App」（apps/*-server + apps/*-app 双包模式，如 spms/qbank/lms/llm-gateway/exam/library）。凡任务涉及新建一个后端服务、TDT 自省/四道闸/服务账号、App 的 scope 与 ACL 声明、LISTING_DEFS/seed 布线、给某 *-server 加 API 端点、DB 迁移或字典表、应用配置 tab、部署接线（Caddy/compose/DEPLOYABLE_APP_SERVICES）时，务必先用本 skill——即使用户只说"给 XX 应用加个接口"。Use when creating or extending a standalone-backend app inside this monorepo: gate/introspection, service accounts, listing/seed wiring, migrations, admin config tabs, deploy wiring.'
----
-
-# portal-backend-app · monorepo 独立后端 App 开发
-
-独立后端 = 自己的进程 + 自己的 DB，消费 Portal 签发的 TDT。本文件是操作序与红线；具体契约按需读 `references/`（为本 skill 提炼的自包含参考；权威源是门户仓库 `docs/`，冲突以门户仓库为准）。本 skill 描述**门户 monorepo 内**的双包模式——服务端在别的 repo 时改用 portal-external-app skill。
-
-## 按任务读参考
-
-| 任务 | 读 |
-| --- | --- |
-| 自省契约 / 四道闸 / 服务账号 / client_credentials / 撤销 | [references/gate-and-tokens.md](references/gate-and-tokens.md) |
-| 注册布线 / scope 目录 / 部署接线 / API 规范 / 用量上报 / 配置 tab | [references/wiring-and-conventions.md](references/wiring-and-conventions.md) |
-
-参考实现：`apps/spms-server/src/lib/gate.ts` + `identity.ts`（各 server 同构的鉴权层）。
-
-## 新建一个后端 App 的全链 checklist
-
-按序做完，每步有既有样板可抄（轻业务抄 `todo-server`、重业务抄 `lms-server`）：
-
-1. **双包**：`apps/<key>-server`（Bun + Elysia，dev 端口取空闲 4xxx）+ `apps/<key>-app`（前端见 portal-micro-app skill）。DB 命名 `xgent-<key>`。
-2. **鉴权层**：整抄 `spms-server/src/lib/gate.ts` + `identity.ts`，改 listingKey/scope 常量。不要手写自省逻辑。
-3. **清单与布线**（位置与规则见 wiring-and-conventions.md §1）：ACL Manifest → `manifests.ts`；listing → `LISTING_DEFS`；服务账号 → `SA_DEFS`；交换 → `EXCHANGE_WIRING`；scope 只能落自己命名空间。
-4. **种子**：App 自己的 seed/bootstrap 写成**非破坏性**独立脚本（`db:seed` 是 portal-only + 破坏性）。
-5. **dev:all**：server+app 挂进根 `package.json` 的 concurrently；绝不叠跑单个 dev 脚本。
-6. **部署接线**一次做全（Caddy 白名单 / compose profile / `DEPLOYABLE_APP_SERVICES` / **Dockerfile COPY 新 workspace** / `build:apps` 串行）——逐项症状见 wiring-and-conventions.md §2，漏一个生产就 404/起不来。
-7. **验证脚本**：`apps/<key>-server/scripts/verify-*.ts` 覆盖 TDT/隔离/ACL/核心业务，挂进 `apps/api/scripts/verify-all.ts`。没有 verify 脚本的功能不算交付。
-
-## 四道闸（每个受保护端点必过）
-
-自省 `POST /api/tokens/introspect`（服务账号 Basic）后：① `(claims.listingKey ?? claims.aud) === 本服务 listingKey`；② 所需 scope ∈ `claims.scopes`；③ 结构性管理操作看 `claims.role === "admin"`；④ 细粒度 `bypass || permissions 命中 PID`（数据范围取最宽）。
-
-如端点是**平台级跨租户**操作，在四道闸之外另加 `claims.isPlatformAdmin === true`：该值是 Portal 按 `user_id` 在每次自省时实时计算的全局身份，不在 JWT 里。`role` / `bypass` 只代表 TDT 当前租户，不能代替这道闸；也不接受前端 header/字段自报。
-
-写错就是全量 401 的硬形状：
-
-- 自省响应走统一信封，**声明在 `data` 里**：`claims = body.data ?? body`；
-- `active:false` 是**成功**的自省（令牌无效），不是传输错误；结果缓存 ≤60s；
-- 服务态 TDT（`kind:"service"`，无 `user_id`）**只按 scope 授权**，勿走 PID 门；
-- `active:true` 的自省结果始终带布尔 `isPlatformAdmin`；服务态恒为 `false`，身份变更传导受下游 ≤60s 缓存上限约束；
-- 租户隔离一律 `claims.tenant_id`，永不信任请求体；限流自建 `(aud, tenant)` 每分钟窗口。
-
-完整字段与服务账号细节见 [references/gate-and-tokens.md](references/gate-and-tokens.md)。
-
-## API 与数据规范（评审必查，细则见 wiring-and-conventions.md §3）
-
-- 业务状态不走 HTTP 状态码：一律 `200 + {ok, data|error}`；数据不存在 = `200 + data:null` 不是 404。
-- 列表端点服务端分页（`Page<T>`）；字典表统一 `sort`（树/兄弟次序保留 `seq`）。
-- 迁移**手写 SQL**（drizzle-kit generate 本仓已知损坏）。
-- 审计写 `POST /api/v1/audit`，不自建审计；租户配置走应用配置 tab 三件套（wiring-and-conventions.md §5）；不做「同步通讯录」；计量走用量上报（wiring-and-conventions.md §4）。
-
-## 验证
-
-改动完成 = 该 server 的 `verify-*.ts` 全绿 + `bun run verify:all` 不回归 + （有 UI 面时）浏览器走通。dev 要点：自省优先服务账号 Basic（`x-resource-key` 仅 `DEV_MOCK_OAUTH=true` 且只认 `FILES_RESOURCE_KEY` 一把）；后端脚本登录用无 2FA 用户（如 `liming`）。