Skill: shenruiyang/auto-pivot-table (version 1.0.0)

--- name: orbcafe-pivot-ainav description: Build ORBCAFE advanced analytics and voice navigation with CPivotTable/usePivotTable and CAINavProvider/useVoiceInput using official examples patterns. Use for drag-drop pivot dimensions, PivotChart companion views, aggregation controls, preset persistence, or space-key voice workflows, especially when interactions appear not to take effect. --- # ORBCAFE Pivot + AINav ## Workflow 1. 先对照 `skills/orbcafe-ui-component-usage/references/module-contracts.md`，确认这是 `Hook-first` 模块。 2. 用 `references/domain-patterns.md` 判定 pivot、voice 或组合模式。 3. 执行安装与最小可运行接入。 4. 用 `references/recipes.md` 产出实现骨架。 5. 对 pivot 需求额外检查是否需要三段式布局（配置区 + 图表区 + 结果区）、独立折叠、图表选择器和 preset 图表快照。 6. 用 `references/guardrails.md` 检查受控状态、preset 持久化、ASR 配置。 7. 输出验收步骤与“没效果”排障。 ## Installation and Bootstrapping (Mandatory) ```bash npm install orbcafe-ui @mui/material @mui/icons-material @mui/x-date-pickers @emotion/react @emotion/styled dayjs ``` 本仓库联调： ```bash npm run build cd examples npm install npm run dev ``` 参考实现： - `examples/app/_components/PivotTableExampleClient.tsx` - `examples/app/_components/AINavExampleClient.tsx` - [REDACTED_SECRET] ## Output Contract 0. `Mode`: `Hook-first`. 1. `Module choice`: pivot or AINav (or both). 2. `Minimal implementation`: controlled if persistence/integration needed. 3. `Ops note`: preset 持久化、PivotChart 默认逻辑或 ASR 契约。 4. `Verify`: 至少包括拖拽布局生效、聚合切换、图表切换、独立折叠、生效后持久化、语音触发与回调。 5. `Troubleshooting`: 至少包含 3 条失效排查点。 ## Examples-Based Experience Summary - 需要持久化时优先 `usePivotTable` 受控模式，不要只依赖组件内部状态。 - preset 持久化应在 `onPresetsChange` 回调落地（本地可用 localStorage，生产建议服务端）。 - Pivot 默认是三段式：配置区、PivotChart、结果表格；图表区和表格区都能独立折叠。 - PivotChart 最多只映射 1 个维度和 2 个度量。默认维度优先取 `rows[0]`，否则 `columns[0]`；默认主度量取 `values[0]`。 - 多维或多度量时，图表工具条应显示 4 个统一宽度的下拉：`Dimension / Measure / Compare measure / Chart type`。 - preset 不只保存布局和筛选，也要保存图表维度、主度量、对比度量和图表类型。 - localStorage 读写放在浏览器安全边界（初始化判定 `window`，写入放 `useEffect`）。 - AINav 强制提供 `onVoiceSubmit`，否则“录音了但业务不动作”。 - 空格热键建议保持 `ignoreWhenFocusedInput=true`，避免输入框场景误触。

path: references/recipes.md
content: # Pivot + AINav Recipes

## Recipe 1: Controlled pivot table with hook

```tsx
import { CPivotTable, usePivotTable } from 'orbcafe-ui';

const pivot = usePivotTable({
  fields,
  initialLayout: {
    rows: ['region'],
    columns: ['quarter'],
    values: [{ fieldId: 'revenue', aggregation: 'sum' }],
  },
});

<CPivotTable rows={dataRows} fields={fields} model={pivot.model} />;
```

## Recipe 2: Pivot preset management

```tsx
import { CPivotTable, type PivotTablePreset } from 'orbcafe-ui';

const [presets, setPresets] = useState<PivotTablePreset[]>([]);

<CPivotTable
  rows={rows}
  fields={fields}
  enablePresetManagement
  presets={presets}
  onPresetsChange={setPresets}
/>;
```

## Recipe 3: Controlled pivot with PivotChart defaults

```tsx
import { CPivotTable, usePivotTable } from 'orbcafe-ui';

const pivot = usePivotTable({
  fields,
  initialLayout: {
    rows: ['region'],
    columns: ['quarter'],
    values: [
      { fieldId: 'revenue', aggregation: 'sum' },
      { fieldId: 'profit', aggregation: 'sum' },
    ],
  },
  initialChart: {
    dimensionFieldId: 'quarter',
    primaryValueFieldId: 'revenue',
    secondaryValueFieldId: 'profit',
    chartType: 'bar-vertical',
  },
});

<CPivotTable rows={rows} fields={fields} model={pivot.model} />;
```

要点：

- 默认图表维度优先取 `rows[0]`，否则 `columns[0]`
- 图表最多只展示 1 个维度、2 个度量
- 多维或多度量时显示 4 个下拉，且应保持等宽

## Recipe 4: Voice navigation provider

```tsx
import { CAINavProvider } from 'orbcafe-ui';

<CAINavProvider
  onVoiceSubmit={async (text) => {
    await routeByIntent(text);
  }}
  onVoiceError={(err) => console.error(err)}
  longPressMs={200}
  wsUrl="ws://localhost:8765"
>
  {children}
</CAINavProvider>;
```


path: references/guardrails.md
content: # Pivot + AINav Guardrails

## Pivot constraints

- Prefer controlled mode (`usePivotTable`) when external filters, persistence, or replay are needed.
- `fields` must provide correct `type` (`string/number/...`) or aggregations become invalid.
- For multi-table analytics pages, isolate each pivot config in separate persisted keys.

## Preset constraints

- If presets are business assets, persist server-side via `onPresetsChange` sync.
- If presets are personal preferences only, local storage is acceptable.

## Voice constraints

- `onVoiceSubmit` is required on `CAINavProvider`.
- Keep `ignoreWhenFocusedInput=true` unless explicitly required, to avoid hijacking typing UX.
- `wsUrl` and ASR auth must come from app config, not hardcoded secrets.
- Handle silence threshold and min volume conservatively to reduce false stops.


path: references/domain-patterns.md
content: # Domain Patterns

## Pivot table intent

Keywords:
- `pivot`, `透视`, `rows/columns/filters/values`, `aggregation`, `preset`

Use:
- `CPivotTable` standalone
- `usePivotTable` for controlled state + persistence

## Voice navigation intent

Keywords:
- `voice nav`, `space`, `speech`, `asr`, `hotkey`, `long press`

Use:
- `CAINavProvider` as page/app wrapper
- `useVoiceInput` only when custom recording pipeline is needed


path: agents/openai.yaml
content: interface:
  display_name: "ORBCAFE Pivot + AINav"
  short_description: "Implement pivot analytics and voice navigation"
  default_prompt: "Use $orbcafe-pivot-ainav to implement this pivot table or voice navigation requirement with ORBCAFE UI."


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)