@howone/agent-cli 0.0.0-stage → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +34 -2
- package/bin/index.d.mts +1 -0
- package/bin/index.mjs +2450 -0
- package/package.json +55 -4
- package/skills/howone/01-apps.md +29 -0
- package/skills/howone/02-develop.md +107 -0
- package/skills/howone/03-workflows.md +71 -0
- package/skills/howone/04-functions-and-data.md +41 -0
- package/skills/howone/05-capabilities.md +46 -0
- package/skills/howone/SKILL.md +52 -0
- package/templates/vite/.howone/skills/hallmark/SKILL.md +557 -0
- package/templates/vite/.howone/skills/hallmark/references/anti-patterns.md +418 -0
- package/templates/vite/.howone/skills/hallmark/references/assets.md +406 -0
- package/templates/vite/.howone/skills/hallmark/references/color.md +95 -0
- package/templates/vite/.howone/skills/hallmark/references/component-cookbook.md +265 -0
- package/templates/vite/.howone/skills/hallmark/references/components/c1-outlined-chip.md +12 -0
- package/templates/vite/.howone/skills/hallmark/references/components/c2-inline-form-as-cta.md +16 -0
- package/templates/vite/.howone/skills/hallmark/references/components/c3-typographic-link.md +8 -0
- package/templates/vite/.howone/skills/hallmark/references/components/c4-sticky-bottom-bar.md +16 -0
- package/templates/vite/.howone/skills/hallmark/references/components/f1-bento-grid.md +20 -0
- package/templates/vite/.howone/skills/hallmark/references/components/f2-sticky-scroll-stack.md +20 -0
- package/templates/vite/.howone/skills/hallmark/references/components/f3-tabular-spec-sheet.md +11 -0
- package/templates/vite/.howone/skills/hallmark/references/components/f4-step-sequence.md +11 -0
- package/templates/vite/.howone/skills/hallmark/references/components/f5-annotated-screenshot.md +11 -0
- package/templates/vite/.howone/skills/hallmark/references/components/f6-product-card-grid.md +41 -0
- package/templates/vite/.howone/skills/hallmark/references/components/ft1-mast-headed.md +13 -0
- package/templates/vite/.howone/skills/hallmark/references/components/ft2-inline-rule-single-line.md +10 -0
- package/templates/vite/.howone/skills/hallmark/references/components/ft3-index-style-category-list.md +12 -0
- package/templates/vite/.howone/skills/hallmark/references/components/ft4-dense-typographic.md +10 -0
- package/templates/vite/.howone/skills/hallmark/references/components/ft5-statement.md +21 -0
- package/templates/vite/.howone/skills/hallmark/references/components/ft6-letter-close.md +19 -0
- package/templates/vite/.howone/skills/hallmark/references/components/ft7-newsletter-first.md +27 -0
- package/templates/vite/.howone/skills/hallmark/references/components/ft8-marquee-scroll.md +25 -0
- package/templates/vite/.howone/skills/hallmark/references/components/h1-marquee.md +15 -0
- package/templates/vite/.howone/skills/hallmark/references/components/h2-split-diptych.md +15 -0
- package/templates/vite/.howone/skills/hallmark/references/components/h3-quote-led.md +11 -0
- package/templates/vite/.howone/skills/hallmark/references/components/h4-stat-led.md +14 -0
- package/templates/vite/.howone/skills/hallmark/references/components/h5-letter-hero.md +11 -0
- package/templates/vite/.howone/skills/hallmark/references/components/h6-photographic-fold.md +16 -0
- package/templates/vite/.howone/skills/hallmark/references/components/h7-demo-video-clipped-by-viewport-edge.md +27 -0
- package/templates/vite/.howone/skills/hallmark/references/components/h8-mockup-split-browser-framed.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/components/h9-custom-illustration-centerpiece.md +27 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n1-wordmark-2-links.md +12 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n10-floating-on-scroll-morph.md +19 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n11-mega-menu.md +40 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n12-banner-retract.md +34 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n13-inline-cmdk-pill.md +39 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n1b-saas-three-section.md +35 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n2-floating-chip.md +14 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n3-side-rail.md +14 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n4-hidden-behind-k.md +9 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n5-floating-pill.md +28 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n6-newspaper-masthead.md +24 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n7-brutal-slab.md +22 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n8-terminal-command.md +21 -0
- package/templates/vite/.howone/skills/hallmark/references/components/n9-edge-aligned-minimal.md +17 -0
- package/templates/vite/.howone/skills/hallmark/references/components/s1-left-margin-numbered.md +15 -0
- package/templates/vite/.howone/skills/hallmark/references/components/s2-hanging.md +13 -0
- package/templates/vite/.howone/skills/hallmark/references/components/s3-sticky-pinned.md +19 -0
- package/templates/vite/.howone/skills/hallmark/references/components/s4-inline-no-break.md +11 -0
- package/templates/vite/.howone/skills/hallmark/references/components/s5-bottom-anchored.md +13 -0
- package/templates/vite/.howone/skills/hallmark/references/components/t1-pull-quote-with-marginalia.md +12 -0
- package/templates/vite/.howone/skills/hallmark/references/components/t2-logo-wall-hairline.md +19 -0
- package/templates/vite/.howone/skills/hallmark/references/components/t3-single-huge-quote.md +11 -0
- package/templates/vite/.howone/skills/hallmark/references/components/t4-numbered-stat-strip.md +14 -0
- package/templates/vite/.howone/skills/hallmark/references/contract.md +24 -0
- package/templates/vite/.howone/skills/hallmark/references/copy.md +182 -0
- package/templates/vite/.howone/skills/hallmark/references/custom-craft.md +626 -0
- package/templates/vite/.howone/skills/hallmark/references/custom-theme.md +367 -0
- package/templates/vite/.howone/skills/hallmark/references/design-md.md +116 -0
- package/templates/vite/.howone/skills/hallmark/references/export-formats.md +328 -0
- package/templates/vite/.howone/skills/hallmark/references/floating-nav.md +89 -0
- package/templates/vite/.howone/skills/hallmark/references/genres/atmospheric.md +69 -0
- package/templates/vite/.howone/skills/hallmark/references/genres/editorial.md +72 -0
- package/templates/vite/.howone/skills/hallmark/references/genres/modern-minimal.md +71 -0
- package/templates/vite/.howone/skills/hallmark/references/genres/playful.md +70 -0
- package/templates/vite/.howone/skills/hallmark/references/hero-enrichment.md +475 -0
- package/templates/vite/.howone/skills/hallmark/references/imagery-kit.md +170 -0
- package/templates/vite/.howone/skills/hallmark/references/interaction-and-states.md +208 -0
- package/templates/vite/.howone/skills/hallmark/references/layout-and-space.md +112 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/01-bento-grid.md +35 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/02-long-document.md +34 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/03-marquee-hero.md +31 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/04-stat-led.md +34 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/05-workbench.md +32 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/06-conversational-faq.md +33 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/07-manifesto.md +32 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/08-photographic.md +34 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/09-quote-led.md +32 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/10-specimen.md +32 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/11-catalogue.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/12-letter.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/13-index-first.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/14-narrative-workflow.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/15-split-studio.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/16-feature-stack.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/17-type-specimen.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/18-portfolio-grid.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/19-map-diagram.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/20-ecosystem-index.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures/21-component-playground.md +23 -0
- package/templates/vite/.howone/skills/hallmark/references/macrostructures.md +89 -0
- package/templates/vite/.howone/skills/hallmark/references/microinteractions.md +258 -0
- package/templates/vite/.howone/skills/hallmark/references/motion.md +109 -0
- package/templates/vite/.howone/skills/hallmark/references/preview-examples.md +49 -0
- package/templates/vite/.howone/skills/hallmark/references/responsive.md +138 -0
- package/templates/vite/.howone/skills/hallmark/references/slop-test.md +192 -0
- package/templates/vite/.howone/skills/hallmark/references/structure.md +160 -0
- package/templates/vite/.howone/skills/hallmark/references/study.md +509 -0
- package/templates/vite/.howone/skills/hallmark/references/themes/carnival.md +301 -0
- package/templates/vite/.howone/skills/hallmark/references/themes/cobalt.md +146 -0
- package/templates/vite/.howone/skills/hallmark/references/themes/hum.md +403 -0
- package/templates/vite/.howone/skills/hallmark/references/themes/lumen.md +478 -0
- package/templates/vite/.howone/skills/hallmark/references/typography.md +243 -0
- package/templates/vite/.howone/skills/hallmark/references/verbs/audit.md +25 -0
- package/templates/vite/.howone/skills/hallmark/references/verbs/redesign.md +269 -0
- package/templates/vite/.howone/skills/howone/01-architect/01-app-generation.md +209 -0
- package/templates/vite/.howone/skills/howone/01-architect/02-manifest-codegen.md +194 -0
- package/templates/vite/.howone/skills/howone/02-entity-schema/01-schema-design.md +523 -0
- package/templates/vite/.howone/skills/howone/02-entity-schema/02-schema-operations.md +329 -0
- package/templates/vite/.howone/skills/howone/02-entity-schema/03-access-models.md +151 -0
- package/templates/vite/.howone/skills/howone/02-entity-schema/04-query-contracts.md +123 -0
- package/templates/vite/.howone/skills/howone/02-entity-schema/05-ai-persistence-patterns.md +255 -0
- package/templates/vite/.howone/skills/howone/03-ai-capabilities/01-ai-capability-architecture.md +215 -0
- package/templates/vite/.howone/skills/howone/03-ai-capabilities/02-workflow-contract-rules.md +427 -0
- package/templates/vite/.howone/skills/howone/03-ai-capabilities/03-service-capability-catalog.md +304 -0
- package/templates/vite/.howone/skills/howone/03-ai-capabilities/04-workflow-operations.md +164 -0
- package/templates/vite/.howone/skills/howone/03-ai-capabilities/05-ai-feature-playbooks.md +275 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/01-client-setup.md +162 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/02-entity-operations.md +163 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/03-auth.md +418 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/04-react-integration.md +138 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/05-file-upload.md +112 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/06-raw-http.md +128 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/07-ai-action-calls.md +210 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/08-ai-manifest-handoff.md +90 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/09-extension-boundaries.md +226 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/10-workflow-execute-sse.md +138 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/11-entity-data-access-patterns.md +310 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/12-query-dsl-and-responses.md +237 -0
- package/templates/vite/.howone/skills/howone/04-app-sdk/13-credits.md +31 -0
- package/templates/vite/.howone/skills/howone/SKILL.md +256 -0
- package/templates/vite/.howone/skills/howone/agents/openai.yaml +4 -0
- package/templates/vite/.howone/skills/howone/references/audio-generation.md +30 -0
- package/templates/vite/.howone/skills/howone/references/audio-recognition.md +30 -0
- package/templates/vite/.howone/skills/howone/references/common-errors.md +27 -0
- package/templates/vite/.howone/skills/howone/references/finance.md +28 -0
- package/templates/vite/.howone/skills/howone/references/image-editing.md +30 -0
- package/templates/vite/.howone/skills/howone/references/image-generation.md +30 -0
- package/templates/vite/.howone/skills/howone/references/version-evidence.md +47 -0
- package/templates/vite/.howone/skills/howone/references/video-generation.md +35 -0
- package/templates/vite/.howone/skills/howone/scripts/verify-project.mjs +151 -0
- package/templates/vite/.prettierignore +7 -0
- package/templates/vite/.prettierrc +11 -0
- package/templates/vite/AGENTS.md +87 -0
- package/templates/vite/README.md +21 -0
- package/templates/vite/components.json +25 -0
- package/templates/vite/eslint.config.js +23 -0
- package/templates/vite/index.html +12 -0
- package/templates/vite/package.json +58 -0
- package/templates/vite/public/vite.svg +1 -0
- package/templates/vite/src/App.tsx +17 -0
- package/templates/vite/src/assets/react.svg +1 -0
- package/templates/vite/src/components/theme-provider.tsx +230 -0
- package/templates/vite/src/components/ui/accordion.tsx +79 -0
- package/templates/vite/src/components/ui/alert-dialog.tsx +197 -0
- package/templates/vite/src/components/ui/alert.tsx +76 -0
- package/templates/vite/src/components/ui/aspect-ratio.tsx +11 -0
- package/templates/vite/src/components/ui/avatar.tsx +110 -0
- package/templates/vite/src/components/ui/badge.tsx +49 -0
- package/templates/vite/src/components/ui/breadcrumb.tsx +122 -0
- package/templates/vite/src/components/ui/button-group.tsx +83 -0
- package/templates/vite/src/components/ui/button.tsx +67 -0
- package/templates/vite/src/components/ui/calendar.tsx +222 -0
- package/templates/vite/src/components/ui/card.tsx +103 -0
- package/templates/vite/src/components/ui/carousel.tsx +240 -0
- package/templates/vite/src/components/ui/chart.tsx +373 -0
- package/templates/vite/src/components/ui/checkbox.tsx +31 -0
- package/templates/vite/src/components/ui/collapsible.tsx +33 -0
- package/templates/vite/src/components/ui/combobox.tsx +299 -0
- package/templates/vite/src/components/ui/command.tsx +193 -0
- package/templates/vite/src/components/ui/context-menu.tsx +261 -0
- package/templates/vite/src/components/ui/dialog.tsx +168 -0
- package/templates/vite/src/components/ui/direction.tsx +22 -0
- package/templates/vite/src/components/ui/drawer.tsx +132 -0
- package/templates/vite/src/components/ui/dropdown-menu.tsx +269 -0
- package/templates/vite/src/components/ui/empty.tsx +104 -0
- package/templates/vite/src/components/ui/field.tsx +238 -0
- package/templates/vite/src/components/ui/hover-card.tsx +42 -0
- package/templates/vite/src/components/ui/input-group.tsx +154 -0
- package/templates/vite/src/components/ui/input-otp.tsx +87 -0
- package/templates/vite/src/components/ui/input.tsx +19 -0
- package/templates/vite/src/components/ui/item.tsx +196 -0
- package/templates/vite/src/components/ui/kbd.tsx +26 -0
- package/templates/vite/src/components/ui/label.tsx +22 -0
- package/templates/vite/src/components/ui/menubar.tsx +280 -0
- package/templates/vite/src/components/ui/native-select.tsx +61 -0
- package/templates/vite/src/components/ui/navigation-menu.tsx +164 -0
- package/templates/vite/src/components/ui/pagination.tsx +129 -0
- package/templates/vite/src/components/ui/popover.tsx +87 -0
- package/templates/vite/src/components/ui/progress.tsx +31 -0
- package/templates/vite/src/components/ui/radio-group.tsx +42 -0
- package/templates/vite/src/components/ui/resizable.tsx +50 -0
- package/templates/vite/src/components/ui/scroll-area.tsx +53 -0
- package/templates/vite/src/components/ui/select.tsx +192 -0
- package/templates/vite/src/components/ui/separator.tsx +26 -0
- package/templates/vite/src/components/ui/sheet.tsx +145 -0
- package/templates/vite/src/components/ui/sidebar.tsx +700 -0
- package/templates/vite/src/components/ui/skeleton.tsx +13 -0
- package/templates/vite/src/components/ui/slider.tsx +59 -0
- package/templates/vite/src/components/ui/sonner.tsx +47 -0
- package/templates/vite/src/components/ui/spinner.tsx +10 -0
- package/templates/vite/src/components/ui/switch.tsx +33 -0
- package/templates/vite/src/components/ui/table.tsx +114 -0
- package/templates/vite/src/components/ui/tabs.tsx +90 -0
- package/templates/vite/src/components/ui/textarea.tsx +18 -0
- package/templates/vite/src/components/ui/toggle-group.tsx +89 -0
- package/templates/vite/src/components/ui/toggle.tsx +45 -0
- package/templates/vite/src/components/ui/tooltip.tsx +57 -0
- package/templates/vite/src/hooks/use-mobile.ts +19 -0
- package/templates/vite/src/index.css +133 -0
- package/templates/vite/src/lib/sdk.ts +34 -0
- package/templates/vite/src/lib/utils.ts +6 -0
- package/templates/vite/src/main.tsx +14 -0
- package/templates/vite/tsconfig.app.json +32 -0
- package/templates/vite/tsconfig.json +13 -0
- package/templates/vite/tsconfig.node.json +26 -0
- package/templates/vite/vite.config.ts +14 -0
|
@@ -0,0 +1,255 @@
|
|
|
1
|
+
# AI Persistence Entity Patterns
|
|
2
|
+
|
|
3
|
+
Use this reference after the AI output schema is known and the product needs durable data:
|
|
4
|
+
generation history, saved results, reports, retryable jobs, share pages, or user libraries.
|
|
5
|
+
|
|
6
|
+
This is a backend entity design reference. It does not define SDK calls. App-side execution and
|
|
7
|
+
persistence code belongs in `04-app-sdk/07-ai-action-calls.md` and
|
|
8
|
+
`04-app-sdk/08-ai-manifest-handoff.md`.
|
|
9
|
+
|
|
10
|
+
## Core Boundary
|
|
11
|
+
|
|
12
|
+
```text
|
|
13
|
+
AI capability outputSchema != database entity schema
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
The AI output schema is the workflow return contract. The database entity schema is the product
|
|
17
|
+
record contract. Persist only fields the product needs after refresh, across sessions, in lists, or
|
|
18
|
+
on public pages.
|
|
19
|
+
|
|
20
|
+
For every AI output field, decide:
|
|
21
|
+
|
|
22
|
+
| Question | Persist? | Entity design |
|
|
23
|
+
|---|---:|---|
|
|
24
|
+
| User must see it after refresh | yes | explicit field |
|
|
25
|
+
| It appears in history/library/search | yes | field + index if queried |
|
|
26
|
+
| It is needed for retry/resume | yes | input/options/status fields |
|
|
27
|
+
| It is only a streaming/intermediate chunk | no | runtime/UI state |
|
|
28
|
+
| It is provider debug metadata | usually no | logs, not product records |
|
|
29
|
+
| It is sensitive internal/provider data | usually no | omit or keep private-only |
|
|
30
|
+
|
|
31
|
+
## Pending-First Record Model
|
|
32
|
+
|
|
33
|
+
For long-running or user-visible AI jobs, design an entity that can represent pending, completed,
|
|
34
|
+
and failed states. The app may create a pending record before workflow execution, then update it
|
|
35
|
+
after completion or failure.
|
|
36
|
+
|
|
37
|
+
Required contract pieces:
|
|
38
|
+
|
|
39
|
+
- original user input or durable input reference;
|
|
40
|
+
- `status`;
|
|
41
|
+
- output fields for completed display;
|
|
42
|
+
- failure fields for history/retry;
|
|
43
|
+
- timestamps for list ordering and stale-job handling.
|
|
44
|
+
|
|
45
|
+
Status field:
|
|
46
|
+
|
|
47
|
+
```json
|
|
48
|
+
{
|
|
49
|
+
"status": {
|
|
50
|
+
"type": "string",
|
|
51
|
+
"description": "pending | running | completed | failed | canceled",
|
|
52
|
+
"default": "pending"
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Rules:
|
|
58
|
+
|
|
59
|
+
- Do not infer completion only from `resultUrl`, `summary`, or another output field.
|
|
60
|
+
- Keep failed records when the product has history or retry UX.
|
|
61
|
+
- If pending/running records are shown from persisted data, define how stale records are recovered.
|
|
62
|
+
- Do not store raw event streams unless the entity explicitly needs them.
|
|
63
|
+
|
|
64
|
+
## Minimal Generation History Entity
|
|
65
|
+
|
|
66
|
+
Use for image, text, report, music, video, or similar generation history.
|
|
67
|
+
|
|
68
|
+
```json
|
|
69
|
+
{
|
|
70
|
+
"name": "Generation",
|
|
71
|
+
"type": "object",
|
|
72
|
+
"properties": {
|
|
73
|
+
"prompt": { "type": "string" },
|
|
74
|
+
"status": { "type": "string", "default": "pending" },
|
|
75
|
+
"resultUrl": { "type": ["string", "null"], "default": null },
|
|
76
|
+
"resultText": { "type": ["string", "null"], "default": null },
|
|
77
|
+
"errorMessage": { "type": ["string", "null"], "default": null },
|
|
78
|
+
"requestedAt": { "type": "date" },
|
|
79
|
+
"completedAt": { "type": ["date", "null"], "default": null }
|
|
80
|
+
},
|
|
81
|
+
"required": ["prompt", "status", "requestedAt"],
|
|
82
|
+
"access": {
|
|
83
|
+
"authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
|
|
84
|
+
"public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
|
|
85
|
+
},
|
|
86
|
+
"indexes": [
|
|
87
|
+
{ "name": "owner_updated", "fields": ["updatedDate"], "scope": "owner" },
|
|
88
|
+
{ "name": "owner_status_updated", "fields": ["status", "updatedDate"], "scope": "owner" }
|
|
89
|
+
],
|
|
90
|
+
"performance": {
|
|
91
|
+
"defaultLimit": 20,
|
|
92
|
+
"maxLimit": 100,
|
|
93
|
+
"allowedSorts": ["updatedDate", "requestedAt"]
|
|
94
|
+
},
|
|
95
|
+
"presentation": {
|
|
96
|
+
"titleField": "prompt",
|
|
97
|
+
"subtitleField": "status"
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Prefer separate product fields over one opaque `result` object when the UI lists, filters, previews,
|
|
103
|
+
or shares the output. Use an object field only for genuinely nested product-level structured data.
|
|
104
|
+
|
|
105
|
+
## Structured Analysis Report Entity
|
|
106
|
+
|
|
107
|
+
Use when AI returns a report users browse later.
|
|
108
|
+
|
|
109
|
+
```json
|
|
110
|
+
{
|
|
111
|
+
"name": "AnalysisReport",
|
|
112
|
+
"type": "object",
|
|
113
|
+
"properties": {
|
|
114
|
+
"sourceTitle": { "type": "string" },
|
|
115
|
+
"sourceUrl": { "type": ["string", "null"], "default": null },
|
|
116
|
+
"status": { "type": "string", "default": "pending" },
|
|
117
|
+
"summary": { "type": ["string", "null"], "default": null },
|
|
118
|
+
"insights": { "type": "array", "default": [] },
|
|
119
|
+
"score": { "type": ["number", "null"], "default": null },
|
|
120
|
+
"errorMessage": { "type": ["string", "null"], "default": null },
|
|
121
|
+
"requestedAt": { "type": "date" },
|
|
122
|
+
"completedAt": { "type": ["date", "null"], "default": null }
|
|
123
|
+
},
|
|
124
|
+
"required": ["sourceTitle", "status", "requestedAt"],
|
|
125
|
+
"access": {
|
|
126
|
+
"authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
|
|
127
|
+
"public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
|
|
128
|
+
},
|
|
129
|
+
"indexes": [
|
|
130
|
+
{ "name": "owner_updated", "fields": ["updatedDate"], "scope": "owner" },
|
|
131
|
+
{ "name": "owner_score_updated", "fields": ["score", "updatedDate"], "scope": "owner" }
|
|
132
|
+
]
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Mapping rule:
|
|
137
|
+
|
|
138
|
+
```text
|
|
139
|
+
workflow input.sourceTitle -> AnalysisReport.sourceTitle
|
|
140
|
+
workflow input.sourceUrl -> AnalysisReport.sourceUrl
|
|
141
|
+
workflow output.summary -> AnalysisReport.summary
|
|
142
|
+
workflow output.insights -> AnalysisReport.insights
|
|
143
|
+
workflow output.score -> AnalysisReport.score
|
|
144
|
+
runtime failure -> AnalysisReport.errorMessage
|
|
145
|
+
runtime completed -> AnalysisReport.completedAt
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Do not save the whole workflow envelope unless the product explicitly needs a private object field
|
|
149
|
+
for audit/debug.
|
|
150
|
+
|
|
151
|
+
## Public Share Split
|
|
152
|
+
|
|
153
|
+
For public AI result pages, split private history from public share data:
|
|
154
|
+
|
|
155
|
+
- private `Generation` stores prompts, failures, drafts, internal metadata, and user history;
|
|
156
|
+
- public/scoped `SharedGeneration` stores only curated fields for anonymous viewing.
|
|
157
|
+
|
|
158
|
+
Scoped public share entity:
|
|
159
|
+
|
|
160
|
+
```json
|
|
161
|
+
{
|
|
162
|
+
"name": "SharedGeneration",
|
|
163
|
+
"type": "object",
|
|
164
|
+
"properties": {
|
|
165
|
+
"shareId": {
|
|
166
|
+
"type": "string",
|
|
167
|
+
"autoGenerate": { "strategy": "uuid" }
|
|
168
|
+
},
|
|
169
|
+
"title": { "type": "string" },
|
|
170
|
+
"resultUrl": { "type": "string" },
|
|
171
|
+
"active": { "type": "boolean", "default": true },
|
|
172
|
+
"sourceGenerationId": { "type": "string" }
|
|
173
|
+
},
|
|
174
|
+
"required": ["shareId", "title", "resultUrl", "active", "sourceGenerationId"],
|
|
175
|
+
"access": {
|
|
176
|
+
"authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
|
|
177
|
+
"public": {
|
|
178
|
+
"read": "scoped",
|
|
179
|
+
"create": "none",
|
|
180
|
+
"update": "none",
|
|
181
|
+
"delete": "none",
|
|
182
|
+
"requiredScopes": ["shareId"],
|
|
183
|
+
"allowedFilters": ["shareId", "active"],
|
|
184
|
+
"allowedSorts": ["updatedDate"],
|
|
185
|
+
"defaultLimit": 1,
|
|
186
|
+
"maxLimit": 1
|
|
187
|
+
}
|
|
188
|
+
},
|
|
189
|
+
"indexes": [
|
|
190
|
+
{ "name": "share_id_unique", "fields": ["shareId"], "unique": true },
|
|
191
|
+
{ "name": "owner_updated", "fields": ["updatedDate"], "scope": "owner" }
|
|
192
|
+
]
|
|
193
|
+
}
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
Never make the main private generation history public just to support share pages.
|
|
197
|
+
|
|
198
|
+
## Retry And Resume Fields
|
|
199
|
+
|
|
200
|
+
If retry is part of the product, persist enough input fields to rebuild the workflow request:
|
|
201
|
+
|
|
202
|
+
- prompt/source content reference;
|
|
203
|
+
- selected style/mode/options;
|
|
204
|
+
- uploaded file URLs or file IDs;
|
|
205
|
+
- status and error message;
|
|
206
|
+
- requested/completed timestamps.
|
|
207
|
+
|
|
208
|
+
Do not persist:
|
|
209
|
+
|
|
210
|
+
- auth/session/token values;
|
|
211
|
+
- raw uploaded browser bytes;
|
|
212
|
+
- temporary component state;
|
|
213
|
+
- raw streaming chunks;
|
|
214
|
+
- provider secrets;
|
|
215
|
+
- hidden system prompts or internal prompts.
|
|
216
|
+
|
|
217
|
+
Prefer a new retry record for history-oriented products. Prefer updating the same record only when
|
|
218
|
+
retry semantically replaces the original attempt.
|
|
219
|
+
|
|
220
|
+
## Field Mapping Checklist
|
|
221
|
+
|
|
222
|
+
Before app implementation, write the mapping explicitly:
|
|
223
|
+
|
|
224
|
+
```text
|
|
225
|
+
workflow input.prompt -> Generation.prompt
|
|
226
|
+
workflow input.style -> Generation.style
|
|
227
|
+
workflow output.imageUrl -> Generation.resultUrl
|
|
228
|
+
workflow output.caption -> Generation.resultText
|
|
229
|
+
workflow error.message -> Generation.errorMessage
|
|
230
|
+
runtime request started -> Generation.requestedAt
|
|
231
|
+
runtime request completed -> Generation.completedAt
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
If a workflow output has no mapping, decide whether it is intentionally transient or the entity
|
|
235
|
+
schema is missing a product field.
|
|
236
|
+
|
|
237
|
+
## Access Checklist
|
|
238
|
+
|
|
239
|
+
| Product behavior | Entity access |
|
|
240
|
+
|---|---|
|
|
241
|
+
| User-only private generation history | authenticated own, public none |
|
|
242
|
+
| Shared authenticated library | authenticated all, public none |
|
|
243
|
+
| Anonymous public gallery | public list with safe fields only |
|
|
244
|
+
| One public share link | public scoped with share id |
|
|
245
|
+
| Public submission to AI queue | public create only with anti-abuse constraints |
|
|
246
|
+
|
|
247
|
+
## Persistence Checklist
|
|
248
|
+
|
|
249
|
+
- AI output schema is fixed before persistence schema design.
|
|
250
|
+
- Entity stores product fields, not workflow internals.
|
|
251
|
+
- Status and failure fields exist for long-running jobs.
|
|
252
|
+
- Retry/resume input fields are durable.
|
|
253
|
+
- Public share data is split from private history.
|
|
254
|
+
- Indexes match history/share/list query patterns.
|
|
255
|
+
- SDK implementation begins only after database and AI manifests are synced.
|
package/templates/vite/.howone/skills/howone/03-ai-capabilities/01-ai-capability-architecture.md
ADDED
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
# AI Capability Architecture
|
|
2
|
+
|
|
3
|
+
**Track:** `03-ai-capabilities/` — capability/workflow **design** only; SDK calls live in `04-app-sdk/`.
|
|
4
|
+
|
|
5
|
+
Use this reference when the user needs HowOne platform AI (verify `03-service-capability-catalog.md` first).
|
|
6
|
+
|
|
7
|
+
This file answers: **what AI layer should be designed, in what order, and where each responsibility
|
|
8
|
+
belongs?** For schema details read `02-workflow-contract-rules.md`. For workflow service calls read
|
|
9
|
+
`04-workflow-operations.md`.
|
|
10
|
+
|
|
11
|
+
## Platform Mental Model
|
|
12
|
+
|
|
13
|
+
HowOne AI has five distinct layers:
|
|
14
|
+
|
|
15
|
+
| Layer | Owns | Does not own |
|
|
16
|
+
|---|---|---|
|
|
17
|
+
| Product feature | User-facing goal, UX states, persistence decision | workflow internals |
|
|
18
|
+
| AI capability contract | `name`, `description`, `inputSchema`, `outputSchema`, `outputEntityName`, versions, manifest | database CRUD, UI, auth |
|
|
19
|
+
| External workflow implementation | generated/edited workflow graph behind a manifest `workflowId`/EAX `config_id` | app schema, frontend state |
|
|
20
|
+
| Status/background layer | job/task polling, completed/failed state, submitted config mapping | SDK binding source |
|
|
21
|
+
| SDK handoff | synced manifest action names, workflow IDs, input/output schemas | workflow generation |
|
|
22
|
+
|
|
23
|
+
Do not collapse these layers. The common mistakes are:
|
|
24
|
+
|
|
25
|
+
- putting database writes into the workflow;
|
|
26
|
+
- generating `src/lib/sdk.ts` before `.howone/ai/manifest.json` is synced;
|
|
27
|
+
- using action names instead of workflow UUIDs;
|
|
28
|
+
- treating workflow `outputSchema` as a database schema;
|
|
29
|
+
- faking unsupported AI with static frontend data.
|
|
30
|
+
|
|
31
|
+
## Source Of Truth
|
|
32
|
+
|
|
33
|
+
```text
|
|
34
|
+
user request = intent
|
|
35
|
+
agent AI contract proposal = draft
|
|
36
|
+
applied AI capability version = validated contract
|
|
37
|
+
.howone/ai/manifest.json = local synced source for workflow submit and later SDK codegen
|
|
38
|
+
external-ai-capability submission = job/task/config mapping; update IDs remain pending
|
|
39
|
+
terminal background finalizer = promotes successful update IDs in the backend capability version
|
|
40
|
+
SDK/UI implementation = separate app-sdk track after AI design is complete
|
|
41
|
+
entity schema = persistence contract, separate from AI contract
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Never generate SDK bindings from the user prompt or from an unsynced draft.
|
|
45
|
+
|
|
46
|
+
## Standard AI Feature Flow
|
|
47
|
+
|
|
48
|
+
Use this flow for new AI features:
|
|
49
|
+
|
|
50
|
+
1. Classify the feature using `03-ai-capabilities/03-service-capability-catalog.md`.
|
|
51
|
+
2. Decide whether the feature is supported. If not supported, stop and explain the missing capability.
|
|
52
|
+
3. Decide one workflow per user-facing feature. Use two workflows only for RAG.
|
|
53
|
+
4. Design `inputSchema` and `outputSchema` using `02-workflow-contract-rules.md`.
|
|
54
|
+
5. Apply the AI capability patch through the capability tool.
|
|
55
|
+
6. Sync `.howone/ai/manifest.json`.
|
|
56
|
+
7. Submit workflow create/update through `external-ai-capability` from the synced manifest.
|
|
57
|
+
8. Store returned job/task IDs and submitted config IDs for polling/debugging.
|
|
58
|
+
9. Let the host poll status until `completed` or `failed`.
|
|
59
|
+
10. On success, the background finalizer promotes successful update IDs in the backend capability version. Failed operations keep their previous IDs.
|
|
60
|
+
11. Run `sync_ai_artifacts` again, then re-read `.howone/ai/manifest.json`.
|
|
61
|
+
12. Leave AI design. If app code must call the workflow, read the SDK track and generate bindings.
|
|
62
|
+
13. If output must persist, design entity schema after the output contract is fixed.
|
|
63
|
+
|
|
64
|
+
Do not submit external workflow create/update from a hand-written schema. It should come from the
|
|
65
|
+
synced manifest.
|
|
66
|
+
|
|
67
|
+
## New Feature vs Existing Feature
|
|
68
|
+
|
|
69
|
+
| Situation | Correct path |
|
|
70
|
+
|---|---|
|
|
71
|
+
| New AI feature, no manifest entry | create AI capability, sync manifest, submit workflow create |
|
|
72
|
+
| Manifest entry exists but no workflow created yet | submit workflow create from manifest |
|
|
73
|
+
| User asks to change input/output contract | update capability contract first, sync, then submit workflow update |
|
|
74
|
+
| User asks to improve behavior only | submit workflow update with `updates[]` and `updatePrompt` |
|
|
75
|
+
| User asks to save outputs/history | design/update database entity after AI output contract is known |
|
|
76
|
+
| User asks for public share of AI result | private history entity + public scoped share entity |
|
|
77
|
+
|
|
78
|
+
## Create vs Update
|
|
79
|
+
|
|
80
|
+
Create external workflow when:
|
|
81
|
+
|
|
82
|
+
- capability has a `workflowId`;
|
|
83
|
+
- no confirmed external implementation exists;
|
|
84
|
+
- the manifest `workflowId` has not already been submitted as an implementation config.
|
|
85
|
+
|
|
86
|
+
Update external workflow when:
|
|
87
|
+
|
|
88
|
+
- an external implementation exists;
|
|
89
|
+
- you have a concrete `updatePrompt`.
|
|
90
|
+
- `external-ai-capability` can read the current manifest `workflowId`.
|
|
91
|
+
|
|
92
|
+
Current `external-ai-capability` semantics:
|
|
93
|
+
|
|
94
|
+
```text
|
|
95
|
+
create:
|
|
96
|
+
config_id = manifest capability.workflowId
|
|
97
|
+
mode = create
|
|
98
|
+
|
|
99
|
+
update:
|
|
100
|
+
previous config = current manifest capability.workflowId
|
|
101
|
+
new config = freshly generated UUID
|
|
102
|
+
submitted state = local manifest remains unchanged while EAX runs
|
|
103
|
+
completed state = backend capability version receives the fresh UUID
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The SDK execution binding uses the synced manifest `workflowId`, which is the EAX config id. After
|
|
107
|
+
update completion, run `sync_ai_artifacts`; only the newly synced manifest value should be copied
|
|
108
|
+
into `src/lib/sdk.ts`.
|
|
109
|
+
Do not invent IDs; let the AI design/sync/external workflow tools generate and persist them.
|
|
110
|
+
|
|
111
|
+
## Workflow Count Rule
|
|
112
|
+
|
|
113
|
+
Default: one user-facing AI feature equals one workflow.
|
|
114
|
+
|
|
115
|
+
Examples:
|
|
116
|
+
|
|
117
|
+
| Feature | Workflow count | Why |
|
|
118
|
+
|---|---:|---|
|
|
119
|
+
| Generate illustrated story | 1 | story text + images are one product action |
|
|
120
|
+
| Edit uploaded photo | 1 | one input image + edit prompt -> edited image |
|
|
121
|
+
| Research news briefing | 1 | search + synthesis are one action |
|
|
122
|
+
| Generate video from prompt | 1 | media generation is one action |
|
|
123
|
+
| Chat with uploaded documents | 2 | RAG needs indexing + query workflows |
|
|
124
|
+
|
|
125
|
+
Do not split normal multi-step behavior into separate workflows. The workflow service handles
|
|
126
|
+
internal orchestration.
|
|
127
|
+
|
|
128
|
+
## Persistence Boundary
|
|
129
|
+
|
|
130
|
+
AI workflows produce outputs. They do not own product records.
|
|
131
|
+
|
|
132
|
+
Workflow may do:
|
|
133
|
+
|
|
134
|
+
- generate, summarize, translate, classify, extract;
|
|
135
|
+
- search/crawl and synthesize;
|
|
136
|
+
- generate/edit/analyze images, video, and audio;
|
|
137
|
+
- retrieve financial or academic data;
|
|
138
|
+
- save/read generated files through URL-based storage.
|
|
139
|
+
|
|
140
|
+
Workflow must not do:
|
|
141
|
+
|
|
142
|
+
- database create/read/update/delete;
|
|
143
|
+
- authentication/session logic;
|
|
144
|
+
- file upload from browser raw bytes;
|
|
145
|
+
- payment processing;
|
|
146
|
+
- owner assignment or permissions;
|
|
147
|
+
- app navigation, UI state, toast, or modal logic.
|
|
148
|
+
|
|
149
|
+
If the product needs durable history, design entity persistence outside the workflow:
|
|
150
|
+
|
|
151
|
+
```text
|
|
152
|
+
workflow input.prompt -> Generation.prompt
|
|
153
|
+
workflow output.imageUrl -> Generation.resultUrl
|
|
154
|
+
runtime failure -> Generation.errorMessage
|
|
155
|
+
runtime status -> Generation.status
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
After AI and database manifests are synced, app implementation can read the SDK track to wire the
|
|
159
|
+
runtime calls.
|
|
160
|
+
|
|
161
|
+
## Unsupported AI Behavior
|
|
162
|
+
|
|
163
|
+
If a user explicitly requires behavior not available in the workflow service, stop that AI path.
|
|
164
|
+
|
|
165
|
+
Do not:
|
|
166
|
+
|
|
167
|
+
- fake AI with static templates;
|
|
168
|
+
- hide the unsupported part;
|
|
169
|
+
- build a UI that pretends the workflow exists;
|
|
170
|
+
- replace the requested capability with a different one without saying so;
|
|
171
|
+
- assume private APIs, external datasets, or providers that are not listed.
|
|
172
|
+
|
|
173
|
+
Correct response:
|
|
174
|
+
|
|
175
|
+
```text
|
|
176
|
+
This exact AI behavior needs <missing capability>. The current workflow service supports <closest
|
|
177
|
+
available capability>. I can build <narrow supported version>, or we need platform support for
|
|
178
|
+
<missing capability> first.
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
## Capability Naming
|
|
182
|
+
|
|
183
|
+
Use stable JavaScript-safe IDs:
|
|
184
|
+
|
|
185
|
+
```text
|
|
186
|
+
generateIllustration
|
|
187
|
+
summarizeDocument
|
|
188
|
+
researchNewsBriefing
|
|
189
|
+
editProductPhoto
|
|
190
|
+
transcribeAudio
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
Avoid:
|
|
194
|
+
|
|
195
|
+
- display labels with spaces;
|
|
196
|
+
- names that collide with base methods: `run`, `stream`, `events`;
|
|
197
|
+
- provider names: `openAiImage`, `geminiAnalyze`;
|
|
198
|
+
- implementation names: `searchThenSummarize`.
|
|
199
|
+
|
|
200
|
+
The description can be human readable. The ID must be stable for codegen.
|
|
201
|
+
|
|
202
|
+
## AI Architecture Checklist
|
|
203
|
+
|
|
204
|
+
Before editing files:
|
|
205
|
+
|
|
206
|
+
- Feature maps to available workflow capabilities.
|
|
207
|
+
- One workflow per feature unless RAG.
|
|
208
|
+
- Description says what the user gets, not how tools run.
|
|
209
|
+
- Input schema accepts URLs for files, not raw bytes.
|
|
210
|
+
- Output schema contains only requested result fields.
|
|
211
|
+
- Input and output property names do not overlap.
|
|
212
|
+
- Text output descriptions specify language behavior.
|
|
213
|
+
- Persistence is modeled as entity schema, not workflow CRUD.
|
|
214
|
+
- `workflowId` / EAX `config_id` values are generated by tools and not guessed.
|
|
215
|
+
- SDK binding will be generated only after manifest sync.
|