@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,427 @@
|
|
|
1
|
+
# Workflow Contract Rules
|
|
2
|
+
|
|
3
|
+
Use this reference when designing `capability.description`, `inputSchema`, `outputSchema`, and
|
|
4
|
+
`outputEntityName` for HowOne AI workflows.
|
|
5
|
+
|
|
6
|
+
These rules come from `docs/ai-worlfow-guide-schema.md`. Violating them can make the workflow
|
|
7
|
+
service reject the request or produce a workflow the runtime cannot execute reliably.
|
|
8
|
+
|
|
9
|
+
## Contract Shape
|
|
10
|
+
|
|
11
|
+
```json
|
|
12
|
+
{
|
|
13
|
+
"name": "summarizeDocument",
|
|
14
|
+
"description": "Reads an uploaded document and produces a concise summary highlighting the key points.",
|
|
15
|
+
"inputSchema": {
|
|
16
|
+
"type": "object",
|
|
17
|
+
"properties": {
|
|
18
|
+
"document_url": {
|
|
19
|
+
"type": "string",
|
|
20
|
+
"format": "uri",
|
|
21
|
+
"description": "Supabase Storage URL of the uploaded document."
|
|
22
|
+
},
|
|
23
|
+
"summary_length": {
|
|
24
|
+
"type": "string",
|
|
25
|
+
"description": "Desired summary length, e.g. short, medium, long, or a specific sentence count."
|
|
26
|
+
}
|
|
27
|
+
},
|
|
28
|
+
"required": ["document_url"]
|
|
29
|
+
},
|
|
30
|
+
"outputSchema": {
|
|
31
|
+
"type": "object",
|
|
32
|
+
"properties": {
|
|
33
|
+
"summary": {
|
|
34
|
+
"type": "string",
|
|
35
|
+
"description": "The generated summary in the same language as the source document."
|
|
36
|
+
}
|
|
37
|
+
},
|
|
38
|
+
"required": ["summary"]
|
|
39
|
+
},
|
|
40
|
+
"outputEntityName": "DocumentSummary"
|
|
41
|
+
}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Loose JSON Schema
|
|
45
|
+
|
|
46
|
+
The workflow engine is agentic. Overly strict schemas reduce reliability.
|
|
47
|
+
|
|
48
|
+
Do:
|
|
49
|
+
|
|
50
|
+
- require only essential inputs;
|
|
51
|
+
- make non-essential options optional;
|
|
52
|
+
- use strings with good descriptions for open-ended user choices;
|
|
53
|
+
- use nested objects only when the product truly needs structured output;
|
|
54
|
+
- use `format: "uri"` for URLs.
|
|
55
|
+
|
|
56
|
+
Avoid:
|
|
57
|
+
|
|
58
|
+
- `minLength`, `maxLength`, `pattern` unless technically required;
|
|
59
|
+
- enum for open-ended values like tone, style, audience, mood;
|
|
60
|
+
- many required knobs that normal users do not understand;
|
|
61
|
+
- provider/model/tool names in schema fields.
|
|
62
|
+
|
|
63
|
+
Good:
|
|
64
|
+
|
|
65
|
+
```json
|
|
66
|
+
{
|
|
67
|
+
"tone": {
|
|
68
|
+
"type": "string",
|
|
69
|
+
"description": "Desired writing tone, e.g. formal, casual, humorous, empathetic, professional."
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Bad:
|
|
75
|
+
|
|
76
|
+
```json
|
|
77
|
+
{
|
|
78
|
+
"tone": {
|
|
79
|
+
"type": "string",
|
|
80
|
+
"enum": ["formal", "casual", "humorous"],
|
|
81
|
+
"minLength": 3,
|
|
82
|
+
"maxLength": 20
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Use enum only for closed domains such as `"daily" | "minute"` or known output modes.
|
|
88
|
+
|
|
89
|
+
## URLs Only For Files
|
|
90
|
+
|
|
91
|
+
All file exchange uses cloud storage URLs.
|
|
92
|
+
|
|
93
|
+
Correct inputs:
|
|
94
|
+
|
|
95
|
+
```json
|
|
96
|
+
{
|
|
97
|
+
"source_image_url": {
|
|
98
|
+
"type": "string",
|
|
99
|
+
"format": "uri",
|
|
100
|
+
"description": "Public URL of the source image to edit."
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Correct outputs:
|
|
106
|
+
|
|
107
|
+
```json
|
|
108
|
+
{
|
|
109
|
+
"edited_image_url": {
|
|
110
|
+
"type": "string",
|
|
111
|
+
"format": "uri",
|
|
112
|
+
"description": "Public URL of the edited image."
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Forbidden:
|
|
118
|
+
|
|
119
|
+
- raw `File` / `Blob`;
|
|
120
|
+
- base64 content;
|
|
121
|
+
- `contentEncoding`;
|
|
122
|
+
- inline PDF/image/audio bytes;
|
|
123
|
+
- browser upload logic in workflow.
|
|
124
|
+
|
|
125
|
+
The app uploads first, then passes the resulting URL to the workflow. File upload helpers belong to
|
|
126
|
+
the SDK track.
|
|
127
|
+
|
|
128
|
+
## Output Minimalism
|
|
129
|
+
|
|
130
|
+
Every output field costs model attention. Only include what the product will render or persist.
|
|
131
|
+
|
|
132
|
+
Usually forbidden unless explicitly requested:
|
|
133
|
+
|
|
134
|
+
- `processing_time`, `timestamp`, `created_at`;
|
|
135
|
+
- `model_used`, `provider`, `version`;
|
|
136
|
+
- `file_size`, `mime_type`, `resolution`, `frame_rate`;
|
|
137
|
+
- `confidence_score`, `bounding_boxes`, `coordinates`;
|
|
138
|
+
- style/color/tone metadata when user only asked for an asset.
|
|
139
|
+
|
|
140
|
+
Examples:
|
|
141
|
+
|
|
142
|
+
| User asks | Good output | Avoid |
|
|
143
|
+
|---|---|---|
|
|
144
|
+
| Summarize a PDF | `summary` | `summary`, `word_count`, `reading_time` |
|
|
145
|
+
| Generate image | `generated_image_url` | `generated_image_url`, `model_used`, `color_palette` |
|
|
146
|
+
| OCR image | `extracted_text` | `extracted_text`, `confidence_score`, `bounding_boxes` |
|
|
147
|
+
| Generate video | `video_url` | `video_url`, `duration_seconds`, `frame_rate` |
|
|
148
|
+
|
|
149
|
+
If the app needs history metadata, put it in the entity schema, not workflow output.
|
|
150
|
+
|
|
151
|
+
## Input / Output Names Must Not Overlap
|
|
152
|
+
|
|
153
|
+
Input and output property names share a routing namespace. Do not reuse names.
|
|
154
|
+
|
|
155
|
+
| Scenario | Bad | Good |
|
|
156
|
+
|---|---|---|
|
|
157
|
+
| Translation | input `text`, output `text` | input `source_text`, output `translated_text` |
|
|
158
|
+
| Summary | input `content`, output `content` | input `source_content`, output `summary` |
|
|
159
|
+
| Image edit | input `image_url`, output `image_url` | input `source_image_url`, output `edited_image_url` |
|
|
160
|
+
| Audio transcript | input `audio_url`, output `audio_url` | input `source_audio_url`, output `transcript_text` |
|
|
161
|
+
|
|
162
|
+
## Description Says What, Not How
|
|
163
|
+
|
|
164
|
+
`capability.description` describes the user-visible outcome.
|
|
165
|
+
|
|
166
|
+
Good:
|
|
167
|
+
|
|
168
|
+
```json
|
|
169
|
+
"description": "Searches the web for recent news on a topic and produces a structured briefing with source links."
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Bad:
|
|
173
|
+
|
|
174
|
+
```json
|
|
175
|
+
"description": "First calls search_web, then summarizes articles with an LLM, then saves the result."
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Do not mention:
|
|
179
|
+
|
|
180
|
+
- internal tool names;
|
|
181
|
+
- step sequences;
|
|
182
|
+
- model/provider names;
|
|
183
|
+
- database writes;
|
|
184
|
+
- storage implementation details except URL inputs/outputs.
|
|
185
|
+
|
|
186
|
+
## Output Language Must Be Explicit
|
|
187
|
+
|
|
188
|
+
Every text output field description must say what language to use.
|
|
189
|
+
|
|
190
|
+
Patterns:
|
|
191
|
+
|
|
192
|
+
```json
|
|
193
|
+
"summary": {
|
|
194
|
+
"type": "string",
|
|
195
|
+
"description": "Summary in the same language as the source document."
|
|
196
|
+
}
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
```json
|
|
200
|
+
"translated_text": {
|
|
201
|
+
"type": "string",
|
|
202
|
+
"description": "Translated text in the target language specified by 'target_language'."
|
|
203
|
+
}
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
```json
|
|
207
|
+
"briefing": {
|
|
208
|
+
"type": "string",
|
|
209
|
+
"description": "Briefing written in the language specified by 'language'."
|
|
210
|
+
}
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Do not write vague descriptions like `"The translated text."`
|
|
214
|
+
|
|
215
|
+
## No CRUD In Workflow
|
|
216
|
+
|
|
217
|
+
Workflow belongs to intelligent processing. App persistence belongs to entities.
|
|
218
|
+
|
|
219
|
+
Forbidden in capability descriptions and schemas:
|
|
220
|
+
|
|
221
|
+
- "save to database";
|
|
222
|
+
- "create user record";
|
|
223
|
+
- "update task status";
|
|
224
|
+
- "delete previous result";
|
|
225
|
+
- "read current user's records";
|
|
226
|
+
- "assign owner".
|
|
227
|
+
|
|
228
|
+
Instead:
|
|
229
|
+
|
|
230
|
+
1. workflow returns output fields;
|
|
231
|
+
2. app code persists through the entity runtime after SDK handoff;
|
|
232
|
+
3. durable fields map to the entity contract.
|
|
233
|
+
|
|
234
|
+
## External Data Assumptions
|
|
235
|
+
|
|
236
|
+
Do not require user-provided datasets unless the user said they have them.
|
|
237
|
+
|
|
238
|
+
| User asks | Bad input | Better input |
|
|
239
|
+
|---|---|---|
|
|
240
|
+
| Stock analysis app | `stock_data_csv_url` | `trading_symbol`, `start_date`, `end_date` |
|
|
241
|
+
| Latest news app | `article_urls` | `topic`, `language` |
|
|
242
|
+
| Academic research | `paper_pdf_urls` | `query`, optional `year_range` |
|
|
243
|
+
| Product comparison | `product_dataset_url` | `product_names` or `search_topic` |
|
|
244
|
+
|
|
245
|
+
The workflow should use available retrieval/search capabilities when data is external.
|
|
246
|
+
|
|
247
|
+
## Raw JSON Requirement
|
|
248
|
+
|
|
249
|
+
Schemas must be raw JSON objects:
|
|
250
|
+
|
|
251
|
+
- start with `{` and end with `}`;
|
|
252
|
+
- ASCII double quotes;
|
|
253
|
+
- no trailing commas;
|
|
254
|
+
- no `undefined`, `NaN`, comments, or single quotes;
|
|
255
|
+
- not a string containing escaped JSON.
|
|
256
|
+
|
|
257
|
+
Good:
|
|
258
|
+
|
|
259
|
+
```json
|
|
260
|
+
{ "type": "object", "properties": {} }
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
Bad:
|
|
264
|
+
|
|
265
|
+
```json
|
|
266
|
+
"{ \"type\": \"object\" }"
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
## Schema Pattern Templates
|
|
270
|
+
|
|
271
|
+
### Text generation
|
|
272
|
+
|
|
273
|
+
```json
|
|
274
|
+
{
|
|
275
|
+
"inputSchema": {
|
|
276
|
+
"type": "object",
|
|
277
|
+
"properties": {
|
|
278
|
+
"topic": {
|
|
279
|
+
"type": "string",
|
|
280
|
+
"description": "Topic to write about."
|
|
281
|
+
},
|
|
282
|
+
"audience": {
|
|
283
|
+
"type": "string",
|
|
284
|
+
"description": "Intended audience, e.g. executives, children, developers, or general readers."
|
|
285
|
+
},
|
|
286
|
+
"language": {
|
|
287
|
+
"type": "string",
|
|
288
|
+
"description": "Output language, e.g. English or Chinese."
|
|
289
|
+
}
|
|
290
|
+
},
|
|
291
|
+
"required": ["topic"]
|
|
292
|
+
},
|
|
293
|
+
"outputSchema": {
|
|
294
|
+
"type": "object",
|
|
295
|
+
"properties": {
|
|
296
|
+
"generated_text": {
|
|
297
|
+
"type": "string",
|
|
298
|
+
"description": "Generated text in the language specified by 'language', or English if not specified."
|
|
299
|
+
}
|
|
300
|
+
},
|
|
301
|
+
"required": ["generated_text"]
|
|
302
|
+
}
|
|
303
|
+
}
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
### Image generation
|
|
307
|
+
|
|
308
|
+
```json
|
|
309
|
+
{
|
|
310
|
+
"inputSchema": {
|
|
311
|
+
"type": "object",
|
|
312
|
+
"properties": {
|
|
313
|
+
"image_description": {
|
|
314
|
+
"type": "string",
|
|
315
|
+
"description": "Detailed description of the image to generate, including subject, style, mood, and composition."
|
|
316
|
+
},
|
|
317
|
+
"style_preference": {
|
|
318
|
+
"type": "string",
|
|
319
|
+
"description": "Optional style preference such as watercolor, pixel art, photorealistic, anime, or flat design."
|
|
320
|
+
}
|
|
321
|
+
},
|
|
322
|
+
"required": ["image_description"]
|
|
323
|
+
},
|
|
324
|
+
"outputSchema": {
|
|
325
|
+
"type": "object",
|
|
326
|
+
"properties": {
|
|
327
|
+
"generated_image_url": {
|
|
328
|
+
"type": "string",
|
|
329
|
+
"format": "uri",
|
|
330
|
+
"description": "Public URL of the generated image."
|
|
331
|
+
}
|
|
332
|
+
},
|
|
333
|
+
"required": ["generated_image_url"]
|
|
334
|
+
}
|
|
335
|
+
}
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
### Image editing
|
|
339
|
+
|
|
340
|
+
```json
|
|
341
|
+
{
|
|
342
|
+
"inputSchema": {
|
|
343
|
+
"type": "object",
|
|
344
|
+
"properties": {
|
|
345
|
+
"source_image_url": {
|
|
346
|
+
"type": "string",
|
|
347
|
+
"format": "uri",
|
|
348
|
+
"description": "Public URL of the image to edit."
|
|
349
|
+
},
|
|
350
|
+
"edit_instruction": {
|
|
351
|
+
"type": "string",
|
|
352
|
+
"description": "Natural language instruction describing the desired edit."
|
|
353
|
+
}
|
|
354
|
+
},
|
|
355
|
+
"required": ["source_image_url", "edit_instruction"]
|
|
356
|
+
},
|
|
357
|
+
"outputSchema": {
|
|
358
|
+
"type": "object",
|
|
359
|
+
"properties": {
|
|
360
|
+
"edited_image_url": {
|
|
361
|
+
"type": "string",
|
|
362
|
+
"format": "uri",
|
|
363
|
+
"description": "Public URL of the edited image."
|
|
364
|
+
}
|
|
365
|
+
},
|
|
366
|
+
"required": ["edited_image_url"]
|
|
367
|
+
}
|
|
368
|
+
}
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
### Research briefing
|
|
372
|
+
|
|
373
|
+
```json
|
|
374
|
+
{
|
|
375
|
+
"inputSchema": {
|
|
376
|
+
"type": "object",
|
|
377
|
+
"properties": {
|
|
378
|
+
"topic": {
|
|
379
|
+
"type": "string",
|
|
380
|
+
"description": "Research topic or question."
|
|
381
|
+
},
|
|
382
|
+
"language": {
|
|
383
|
+
"type": "string",
|
|
384
|
+
"description": "Language for the output briefing."
|
|
385
|
+
}
|
|
386
|
+
},
|
|
387
|
+
"required": ["topic"]
|
|
388
|
+
},
|
|
389
|
+
"outputSchema": {
|
|
390
|
+
"type": "object",
|
|
391
|
+
"properties": {
|
|
392
|
+
"briefing": {
|
|
393
|
+
"type": "object",
|
|
394
|
+
"description": "Structured briefing written in the language specified by 'language'.",
|
|
395
|
+
"properties": {
|
|
396
|
+
"summary": { "type": "string" },
|
|
397
|
+
"sources": {
|
|
398
|
+
"type": "array",
|
|
399
|
+
"items": {
|
|
400
|
+
"type": "object",
|
|
401
|
+
"properties": {
|
|
402
|
+
"title": { "type": "string" },
|
|
403
|
+
"url": { "type": "string", "format": "uri" },
|
|
404
|
+
"key_point": { "type": "string" }
|
|
405
|
+
}
|
|
406
|
+
}
|
|
407
|
+
}
|
|
408
|
+
},
|
|
409
|
+
"required": ["summary", "sources"]
|
|
410
|
+
}
|
|
411
|
+
},
|
|
412
|
+
"required": ["briefing"]
|
|
413
|
+
}
|
|
414
|
+
}
|
|
415
|
+
```
|
|
416
|
+
|
|
417
|
+
## Contract Checklist
|
|
418
|
+
|
|
419
|
+
- Required inputs are essential only.
|
|
420
|
+
- File inputs/outputs are URL strings.
|
|
421
|
+
- Output contains only the requested product result.
|
|
422
|
+
- Input/output property names do not overlap.
|
|
423
|
+
- Text output descriptions specify language.
|
|
424
|
+
- Description says what, not how.
|
|
425
|
+
- No CRUD/auth/upload/payment/app-state requirements.
|
|
426
|
+
- Feature fits an available capability.
|
|
427
|
+
- Schema is raw valid JSON.
|