| name | orbcafe-graph-detail-ai |
| description | Build ORBCAFE graph analytics dialogs, detail pages, and AI settings with CGraphReport, chart components, CDetailInfoPage/useDetailInfo, and CCustomizeAgent using official Next.js examples patterns. Use for KPI/chart drilldown, searchable detail tabs, and configurable prompt settings, especially when UI appears rendered but interactions are ineffective. |
ORBCAFE Graph + Detail + Agent
Workflow
- 先对照
skills/orbcafe-ui-component-usage/references/module-contracts.md,确认这里是混合模块:graph/detail 为 Hook-first,agent settings 为 Component-first。
- 用
references/domain-selector.md 判定 graph/detail/agent 子域。
- 执行
skills/orbcafe-ui-component-usage/references/integration-baseline.md,按 Next.js App Router + 官方 examples 做最小接入。
- 用
references/recipes.md 输出最小可运行片段。
- 用
references/guardrails.md 检查图表联动、详情检索、AI 设置保存一致性。
- 输出验收步骤与“无效果”排障;非 Next 项目先标记为偏离基线,不要静默改成 Vite/CRA 范式。
Canonical Setup
先检查宿主 package.json,缺失或版本不兼容时才安装:
npm install orbcafe-ui @mui/material@^7.3.9 @mui/icons-material@^7.3.9 @mui/x-date-pickers@^8.27.2 @emotion/react@^11.14.0 @emotion/styled@^11.14.1 dayjs@^1.11.20 lucide-react@^0.575.0 tailwind-merge@^3.5.0 clsx@^2.1.1 class-variance-authority@^0.7.1 @radix-ui/react-slot@^1.2.4
官方 examples 不随 npm 包发布。消费项目没有 examples/ 时,到 ORBCAFE GitHub 仓库或本地 ORBCAFE 源码仓库对照。
本仓库联调:
npm run build
cd examples
npm install
npm run dev
参考实现:
examples/app/detail-info/[id]/page.tsx
examples/app/detail-info/[id]/DetailInfoExampleClient.tsx
src/components/GraphReport/README.md
src/components/CustomizeAgent/README.md
Output Contract
Mode: Hook-first for graph/detail, Component-first for agent settings.
Chosen module: graph/detail/agent and why.
Minimal code: one focused snippet.
Data model: model/tabs/sections/settings shape.
Verify: 图表联动或详情搜索/AI fallback/设置保存至少 3 项可验证行为。
Troubleshooting: 至少 3 条“看得到 UI 但交互没效果”的排查项。
Examples-Based Experience Summary
- Detail 动态路由采用
Server page await params -> Client page 模式,避免 Next16 参数 Promise 误用。
CDetailInfoPage 搜索优先命中字段,未命中再回退 ai.onSubmit,这是稳定体验基线。
ai.onSubmit 返回 Markdown 字符串时保持结构化文本,避免不可预测富文本注入。
- Graph 报表优先接入
CTable.graphReport 联动入口;独立 CGraphReport 仅在外部需要完全控制 open/model 时使用。
CCustomizeAgent.onSaveAll 必须一次性提交 settings + template ids,防止配置部分成功导致“看似保存但不生效”。