howone 0.1.23 → 0.1.25

package/templates/vite/.howone/skills/howone-sdk/04-ai/02-workflow-contract-rules.md

@@ -1,21 +1,64 @@
 # Workflow Contract Rules
 
-Use this reference when designing `inputSchema`, `outputSchema`, and capability descriptions for
-HowOne AI workflows.
+Use this reference when designing `capability.description`, `inputSchema`, `outputSchema`, and
+`outputEntityName` for HowOne AI workflows.
+
+These rules come from `docs/ai-worlfow-guide-schema.md`. Violating them can make the workflow
+service reject the request or produce a workflow that the SDK cannot call reliably.
+
+## Contract Shape
+
+```json
+{
+  "name": "summarizeDocument",
+  "description": "Reads an uploaded document and produces a concise summary highlighting the key points.",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "document_url": {
+        "type": "string",
+        "format": "uri",
+        "description": "Supabase Storage URL of the uploaded document."
+      },
+      "summary_length": {
+        "type": "string",
+        "description": "Desired summary length, e.g. short, medium, long, or a specific sentence count."
+      }
+    },
+    "required": ["document_url"]
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "summary": {
+        "type": "string",
+        "description": "The generated summary in the same language as the source document."
+      }
+    },
+    "required": ["summary"]
+  },
+  "outputEntityName": "DocumentSummary"
+}
+```
 
 ## Loose JSON Schema
 
-Workflow schemas should be loose enough for an AI workflow engine.
+The workflow engine is agentic. Overly strict schemas reduce reliability.
 
-Rules:
+Do:
+
+- require only essential inputs;
+- make non-essential options optional;
+- use strings with good descriptions for open-ended user choices;
+- use nested objects only when the product truly needs structured output;
+- use `format: "uri"` for URLs.
+
+Avoid:
 
-- Require only essential inputs.
-- Mark non-essential options optional.
-- Prefer `string` with a clear description over restrictive enums when user values are open-ended.
-- Avoid `minLength`, `maxLength`, `pattern`, and narrow validation unless there is a concrete
-  technical reason.
-- Avoid nested objects when a simple described string is enough.
-- Avoid exposing implementation knobs the user does not need.
+- `minLength`, `maxLength`, `pattern` unless technically required;
+- enum for open-ended values like tone, style, audience, mood;
+- many required knobs that normal users do not understand;
+- provider/model/tool names in schema fields.
 
 Good:
 
@@ -28,142 +71,356 @@ Good:
 }
 ```
 
-Use enums only for truly closed domains.
+Bad:
+
+```json
+{
+  "tone": {
+    "type": "string",
+    "enum": ["formal", "casual", "humorous"],
+    "minLength": 3,
+    "maxLength": 20
+  }
+}
+```
+
+Use enum only for closed domains such as `"daily" | "minute"` or known output modes.
+
+## URLs Only For Files
+
+All file exchange uses cloud storage URLs.
+
+Correct inputs:
+
+```json
+{
+  "source_image_url": {
+    "type": "string",
+    "format": "uri",
+    "description": "Public URL of the source image to edit."
+  }
+}
+```
+
+Correct outputs:
 
-## URLs, Not Raw Files
+```json
+{
+  "edited_image_url": {
+    "type": "string",
+    "format": "uri",
+    "description": "Public URL of the edited image."
+  }
+}
+```
 
-All file exchange uses URLs.
+Forbidden:
 
-Rules:
+- raw `File` / `Blob`;
+- base64 content;
+- `contentEncoding`;
+- inline PDF/image/audio bytes;
+- browser upload logic in workflow.
 
-- File inputs are strings with `format: "uri"`, such as `document_url`, `source_image_url`, or
-  `audio_file_url`.
-- File outputs are strings with `format: "uri"`, such as `generated_image_url`, `edited_video_url`,
-  or `result_pdf_url`.
-- Never use base64, raw bytes, inline file content, or `contentEncoding`.
-- The app uploads user files first, then passes the URL to the workflow.
+The app uploads first through `howone.upload.*`, then passes the URL to the workflow.
 
 ## Output Minimalism
 
-The workflow will try to fill every output field. Only ask for fields the product needs.
+Every output field costs model attention. Only include what the product will render or persist.
 
 Usually forbidden unless explicitly requested:
 
-- timestamps and processing time
-- file size, MIME type, encoding, dimensions, frame rate, bitrate
-- confidence scores and bounding boxes
-- model, provider, version, cost, or internal execution metadata
-- style/tone metadata when the user only asked for an asset
+- `processing_time`, `timestamp`, `created_at`;
+- `model_used`, `provider`, `version`;
+- `file_size`, `mime_type`, `resolution`, `frame_rate`;
+- `confidence_score`, `bounding_boxes`, `coordinates`;
+- style/color/tone metadata when user only asked for an asset.
 
 Examples:
 
-| User Need | Good Output | Avoid |
+| User asks | Good output | Avoid |
 |---|---|---|
-| Summarize a document | `summary` | `summary`, `word_count`, `reading_time` |
-| Generate an image | `generated_image_url` | `generated_image_url`, `model_used`, `color_palette` |
-| OCR an image | `extracted_text` | `extracted_text`, `confidence_score`, `bounding_boxes` |
+| Summarize a PDF | `summary` | `summary`, `word_count`, `reading_time` |
+| Generate image | `generated_image_url` | `generated_image_url`, `model_used`, `color_palette` |
+| OCR image | `extracted_text` | `extracted_text`, `confidence_score`, `bounding_boxes` |
+| Generate video | `video_url` | `video_url`, `duration_seconds`, `frame_rate` |
+
+If the app needs history metadata, put it in the entity schema, not workflow output.
 
-## No Input/Output Name Overlap
+## Input / Output Names Must Not Overlap
 
-Input and output property names must not overlap. The workflow engine uses a shared parameter
-namespace.
+Input and output property names share a routing namespace. Do not reuse names.
+
+| Scenario | Bad | Good |
+|---|---|---|
+| Translation | input `text`, output `text` | input `source_text`, output `translated_text` |
+| Summary | input `content`, output `content` | input `source_content`, output `summary` |
+| Image edit | input `image_url`, output `image_url` | input `source_image_url`, output `edited_image_url` |
+| Audio transcript | input `audio_url`, output `audio_url` | input `source_audio_url`, output `transcript_text` |
+
+## Description Says What, Not How
+
+`capability.description` describes the user-visible outcome.
+
+Good:
+
+```json
+"description": "Searches the web for recent news on a topic and produces a structured briefing with source links."
+```
 
 Bad:
 
 ```json
-{
-  "inputSchema": { "properties": { "text": { "type": "string" } } },
-  "outputSchema": { "properties": { "text": { "type": "string" } } }
+"description": "First calls search_web, then summarizes articles with an LLM, then saves the result."
+```
+
+Do not mention:
+
+- internal tool names;
+- step sequences;
+- model/provider names;
+- database writes;
+- storage implementation details except URL inputs/outputs.
+
+## Output Language Must Be Explicit
+
+Every text output field description must say what language to use.
+
+Patterns:
+
+```json
+"summary": {
+  "type": "string",
+  "description": "Summary in the same language as the source document."
 }
 ```
 
-Good:
+```json
+"translated_text": {
+  "type": "string",
+  "description": "Translated text in the target language specified by 'target_language'."
+}
+```
 
 ```json
-{
-  "inputSchema": { "properties": { "source_text": { "type": "string" } } },
-  "outputSchema": { "properties": { "translated_text": { "type": "string" } } }
+"briefing": {
+  "type": "string",
+  "description": "Briefing written in the language specified by 'language'."
 }
 ```
 
-Common pairs:
+Do not write vague descriptions like `"The translated text."`
 
-- `source_text` -> `translated_text`
-- `source_content` -> `summary`
-- `source_image_url` -> `edited_image_url`
-- `description_prompt` -> `generated_image_url`
+## No CRUD In Workflow
 
-## Output Language
+Workflow belongs to intelligent processing. App persistence belongs to entities.
 
-Every text output field description must specify the language rule.
+Forbidden in capability descriptions and schemas:
 
-Use one of these patterns:
+- "save to database";
+- "create user record";
+- "update task status";
+- "delete previous result";
+- "read current user's records";
+- "assign owner".
 
-- fixed: "Summary in English."
-- input-driven: "Translated text in the target language specified by `target_language`."
-- source-driven: "Summary in the same language as the source document."
-- mixed: "Extracted text, which may contain mixed Chinese and English content."
+Instead:
 
-Do not write vague descriptions like "The translated text."
+1. workflow returns output fields;
+2. frontend/server code calls SDK entity methods;
+3. persistence helper maps durable fields.
 
-## Description Says What, Not How
+## External Data Assumptions
 
-`capability.description` describes the user outcome.
+Do not require user-provided datasets unless the user said they have them.
 
-Do:
+| User asks | Bad input | Better input |
+|---|---|---|
+| Stock analysis app | `stock_data_csv_url` | `trading_symbol`, `start_date`, `end_date` |
+| Latest news app | `article_urls` | `topic`, `language` |
+| Academic research | `paper_pdf_urls` | `query`, optional `year_range` |
+| Product comparison | `product_dataset_url` | `product_names` or `search_topic` |
 
-```json
-{
-  "description": "Searches the web for the latest news on a topic and produces a structured briefing with source links."
-}
-```
+The workflow should use available retrieval/search capabilities when data is external.
+
+## Raw JSON Requirement
+
+Schemas must be raw JSON objects:
 
-Do not:
+- start with `{` and end with `}`;
+- ASCII double quotes;
+- no trailing commas;
+- no `undefined`, `NaN`, comments, or single quotes;
+- not a string containing escaped JSON.
+
+Good:
 
 ```json
-{
-  "description": "First calls search_web, then summarizes each article with an LLM, then saves JSON."
-}
+{ "type": "object", "properties": {} }
 ```
 
-Never mention internal tool names, step sequences, providers, or model names in the capability
-description.
+Bad:
 
-## Available Capability Families
+```json
+"{ \"type\": \"object\" }"
+```
 
-Design only around capabilities available to the workflow service:
+## Schema Pattern Templates
 
-- web search and page crawling
-- image generation, editing, analysis, OCR
-- video generation, editing, concatenation, frame extraction
-- audio generation, recognition, merging
-- financial price history retrieval
-- academic paper search and bibliography
-- file storage/read for JSON, YAML, CSV, PDF, Markdown, TXT
-- email sending
-- RSS feed fetching
-- Airbnb search
-- Hacker News search
+### Text generation
 
-If the requested product needs unavailable functionality, redesign the feature around available
-capabilities or exclude it explicitly.
+```json
+{
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "topic": {
+        "type": "string",
+        "description": "Topic to write about."
+      },
+      "audience": {
+        "type": "string",
+        "description": "Intended audience, e.g. executives, children, developers, or general readers."
+      },
+      "language": {
+        "type": "string",
+        "description": "Output language, e.g. English or Chinese."
+      }
+    },
+    "required": ["topic"]
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "generated_text": {
+        "type": "string",
+        "description": "Generated text in the language specified by 'language', or English if not specified."
+      }
+    },
+    "required": ["generated_text"]
+  }
+}
+```
 
-When the user explicitly requires the unavailable AI behavior, terminate the AI task instead of
-building a fake or silently degraded implementation. Report the unsupported requirement and the
-closest supported alternative.
+### Image generation
 
-## External Data Assumptions
+```json
+{
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "image_description": {
+        "type": "string",
+        "description": "Detailed description of the image to generate, including subject, style, mood, and composition."
+      },
+      "style_preference": {
+        "type": "string",
+        "description": "Optional style preference such as watercolor, pixel art, photorealistic, anime, or flat design."
+      }
+    },
+    "required": ["image_description"]
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "generated_image_url": {
+        "type": "string",
+        "format": "uri",
+        "description": "Public URL of the generated image."
+      }
+    },
+    "required": ["generated_image_url"]
+  }
+}
+```
 
-Do not assume the user can provide external datasets unless they explicitly say so.
+### Image editing
 
-For "stock analysis", use a workflow input such as `trading_symbol` and let the workflow retrieve
-history. Do not require `stock_data_csv_url` unless the user says they have a CSV.
+```json
+{
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "source_image_url": {
+        "type": "string",
+        "format": "uri",
+        "description": "Public URL of the image to edit."
+      },
+      "edit_instruction": {
+        "type": "string",
+        "description": "Natural language instruction describing the desired edit."
+      }
+    },
+    "required": ["source_image_url", "edit_instruction"]
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "edited_image_url": {
+        "type": "string",
+        "format": "uri",
+        "description": "Public URL of the edited image."
+      }
+    },
+    "required": ["edited_image_url"]
+  }
+}
+```
 
-For "latest news", use web search inside the workflow. Do not ask the user to provide article URLs
-unless that is the product requirement.
+### Research briefing
 
-## MVP Limit
+```json
+{
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "topic": {
+        "type": "string",
+        "description": "Research topic or question."
+      },
+      "language": {
+        "type": "string",
+        "description": "Language for the output briefing."
+      }
+    },
+    "required": ["topic"]
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "briefing": {
+        "type": "object",
+        "description": "Structured briefing written in the language specified by 'language'.",
+        "properties": {
+          "summary": { "type": "string" },
+          "sources": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "title": { "type": "string" },
+                "url": { "type": "string", "format": "uri" },
+                "key_point": { "type": "string" }
+              }
+            }
+          }
+        },
+        "required": ["summary", "sources"]
+      }
+    },
+    "required": ["briefing"]
+  }
+}
+```
 
-Keep AI app generation to at most five core features. Exclude feedback forms, onboarding tutorials,
-notification settings, export, sharing, personalization, and preferences unless the user explicitly
-requests them.
+## Contract Checklist
+
+- Required inputs are essential only.
+- File inputs/outputs are URL strings.
+- Output contains only the requested product result.
+- Input/output property names do not overlap.
+- Text output descriptions specify language.
+- Description says what, not how.
+- No CRUD/auth/upload/payment/app-state requirements.
+- Feature fits an available capability.
+- Schema is raw valid JSON.