howone 0.1.22 → 0.1.25

package/templates/vite/.howone/skills/howone-sdk/04-ai/04-service-capability-catalog.md

@@ -0,0 +1,281 @@
+# Service Capability Catalog
+
+Use this reference before designing an AI workflow. It tells the agent what the current workflow
+service can actually do and what input/output shapes are expected.
+
+Source: `docs/ai-capability.md`.
+
+## Quick Selection Table
+
+| User asks for | Use capability family | Typical inputs | Typical outputs |
+|---|---|---|---|
+| Latest info, research, source-backed answer | Web search / crawling | `topic`, `prompt`, `url`, `search_level` | `answer`, `sources`, `page_content` |
+| Generate artwork/photo/logo/mockup | Image generation | `image_description`, `style_preference`, optional references | `generated_image_url` |
+| Edit an image | Image editing | `source_image_url`, `edit_instruction` | `edited_image_url` |
+| OCR or visual analysis | Image analysis / OCR | `image_urls`, `analysis_prompt` | `analysis_result` or `extracted_text` |
+| Generate short video | Video generation | `video_prompt`, aspect/duration/frame URLs | `video_url` |
+| Join clips / extract frames | Video editing | `video_urls` or `video_url` | `video_url` or `image_url` |
+| Text to speech | Audio generation | `text_to_generate`, `language`, `voice_hint` | `audio_url` |
+| Speech to text | Audio recognition | `source_audio_url`, `language` | `transcript_text`, optional `utterances` |
+| Merge audio | Audio merging | `audio_urls` | `merged_audio_url` |
+| Stock/index history | Financial data retrieval | `trading_symbol`, `unit`, `start`, `end` | `price_history` |
+| Literature search/citations | Academic research | `query` | `papers`, `bibtex` |
+| Save generated file | File storage | `file_type`, `content` | `file_url` |
+
+If the requested behavior is not in this table or the detailed sections below, do not invent it.
+
+## Web Search And Crawling
+
+Use for latest information, news, market context, source-backed answers, web page extraction.
+
+Inputs:
+
+- `prompt`: query or detailed research instruction;
+- `search_level`: `low`, `medium`, or `high`; default to medium;
+- `offset`: pagination for low-level search;
+- page crawl input should be a URL.
+
+Outputs:
+
+- synthesized answer or raw search result;
+- `sources` array of URLs;
+- crawled page text/markdown when crawling.
+
+Rules:
+
+- Use web search when the user asks for current/latest information.
+- Use page crawling when the product needs content from a specific URL.
+- Do not use search as an outbound API caller.
+- Include source links in output when the product promises research.
+
+## Image Generation
+
+Use for new images from prompts or prompt + reference URLs.
+
+Inputs:
+
+- `image_description`: detailed prompt;
+- `style_preference`: optional;
+- `reference_image_urls`: optional URL array;
+- size/format options only when product exposes them.
+
+Outputs:
+
+- `generated_image_url` or `image_urls`;
+- avoid metadata unless product needs it.
+
+Rules:
+
+- One image per request is usually more reliable.
+- Do not put resolution text into the prompt when a size parameter exists.
+- Reference images must be URLs and should be described by position/content.
+- Subject to moderation; do not promise forbidden content.
+
+## Image Editing
+
+Use for modifying existing images.
+
+Inputs:
+
+- `source_image_url` or `source_image_urls`;
+- `edit_instruction`;
+- optional output size/format.
+
+Outputs:
+
+- `edited_image_url`.
+
+Supported edits include resize/crop/rotate, background removal/replacement, object removal/addition,
+style transfer, enhancement, merge/composite, lighting/color changes.
+
+Rules:
+
+- At least one image URL is required.
+- Keep edit instructions focused.
+- For complex multi-step edits, describe the final desired result.
+
+## Image Analysis And OCR
+
+Use for visual understanding, image comparison, text extraction, quality review.
+
+Inputs:
+
+- `image_urls`;
+- `analysis_prompt` or `ocr_instruction`.
+
+Outputs:
+
+- `analysis_result` for semantic analysis;
+- `extracted_text` for OCR.
+
+Rules:
+
+- Ask for the exact information needed.
+- Do not include confidence/bounding boxes unless user asks.
+- OCR quality depends on image quality.
+
+## Video Generation
+
+Use for short video clips from text or image frames.
+
+Inputs:
+
+- `video_prompt`;
+- optional `first_frame_url`, `last_frame_url`, `reference_image_urls`;
+- optional `aspect_ratio`, `duration`, `negative_prompt`, `generate_audio`.
+
+Outputs:
+
+- `video_url`.
+
+Rules:
+
+- Keep individual clips short, generally 5-10 seconds.
+- For consistency, generate/use a first-frame image.
+- For longer videos, generate clips and concatenate via video editing.
+- Audio in video works best with one speaker per clip.
+
+## Video Editing
+
+Use for concatenating clips or extracting first/last frames.
+
+Inputs:
+
+- concatenate: `video_urls` with at least two URLs;
+- frame extraction: `source_video_url`.
+
+Outputs:
+
+- `merged_video_url` or `frame_image_url`.
+
+Rules:
+
+- Inputs must be accessible URLs.
+- Best results when clips share resolution/aspect ratio.
+
+## Audio Generation
+
+Use for text-to-speech.
+
+Inputs:
+
+- `text_to_generate`;
+- `language` or `languages`;
+- `gender`;
+- `audio_hint`;
+- optional output format/name.
+
+Outputs:
+
+- `audio_url`.
+
+Rules:
+
+- Single speaker per call.
+- For dialogue, generate each speaker line and merge audio.
+- `audio_hint` should describe voice in English.
+
+## Audio Recognition
+
+Use for speech-to-text.
+
+Inputs:
+
+- `source_audio_url`;
+- optional `language`;
+- optional speaker diarization setting.
+
+Outputs:
+
+- `transcript_text`;
+- optional `utterances` when speaker info is requested.
+
+Rules:
+
+- Audio must be URL-accessible.
+- Silent or low-quality audio can produce empty/poor transcript.
+
+## Financial Data Retrieval
+
+Use for historical stock/index price data.
+
+Inputs:
+
+- `trading_symbol`;
+- `unit`: `daily` or `minute`;
+- `start`;
+- `end`.
+
+Outputs:
+
+- `price_history` array;
+- `trading_symbol`;
+- optional warning.
+
+Rules:
+
+- Historical data only; no real-time streaming.
+- Indices usually support daily data only.
+- Ask for exact tickers when possible.
+- Does not provide fundamentals, earnings, or live news unless combined with web search.
+
+## Academic Research
+
+Use for literature search, paper metadata, BibTeX.
+
+Inputs:
+
+- `query`.
+
+Outputs:
+
+- `papers`;
+- `bibtex` when citation output is requested.
+
+Rules:
+
+- Search quality depends on query specificity.
+- Availability varies by academic source.
+- PDF assets should be handled as URLs.
+
+## File Storage
+
+Use when workflow needs to save generated content into a file.
+
+Inputs:
+
+- `file_type`: `json`, `yaml`, `csv`, `pdf`, `md`, or `txt`;
+- `content`: string content to save.
+
+Outputs:
+
+- `file_url`.
+
+Rules:
+
+- Structured content must be serialized to string before saving.
+- Do not use file storage as a database.
+- If app needs records/history, persist file URL through entities.
+
+## Composition Patterns
+
+| Pattern | Workflow design |
+|---|---|
+| Image -> Video | generate first-frame image, pass as `first_frame_url` to video generation |
+| Multi-clip video | generate short clips, concatenate via video editing |
+| Dialogue audio | generate each speaker line, merge audio |
+| Search -> Report | web search/crawl, synthesize structured report, optionally save file |
+| Video -> Image edit -> Video | extract frame, edit frame, use as next reference |
+| RAG document chat | indexing workflow + query workflow |
+
+## Capability Rejection Checklist
+
+Stop or narrow scope if user requires:
+
+- real-time streaming market data;
+- arbitrary external API calls not listed;
+- raw file bytes/base64 in workflow;
+- database CRUD inside workflow;
+- unsupported provider-specific model guarantees;
+- content disallowed by moderation;
+- long video generation in one call beyond service limits.

package/templates/vite/.howone/skills/howone-sdk/04-ai/05-workflow-operations.md

@@ -0,0 +1,256 @@
+# Workflow Operations
+
+Use this reference when submitting or checking external workflow create/update operations.
+
+Source: `docs/ai-worlfow-guide-schema.md`.
+
+## Endpoints
+
+| Purpose | Method | Path |
+|---|---|---|
+| Submit create/update operations | `POST` | `/workflow/{project_short_id}/operate` |
+| Check operation status | `GET` | `/workflow/status_check/{request_id}` |
+
+All requests require `Authorization: Bearer <token>`.
+
+## Operation Object
+
+```json
+{
+  "appId": "proj_docs",
+  "workflowId": "550e8400-e29b-41d4-a716-446655440000",
+  "mode": "create",
+  "capability": {
+    "name": "summarizeDocument",
+    "description": "Reads an uploaded document and produces a concise summary highlighting the key points.",
+    "inputSchema": {},
+    "outputSchema": {},
+    "outputEntityName": "DocumentSummary"
+  },
+  "requestMeta": {}
+}
+```
+
+Field rules:
+
+| Field | Required | Notes |
+|---|---:|---|
+| `appId` | yes | Must match path project short ID. |
+| `workflowId` | yes | UUID v4 from manifest/capability contract. |
+| `mode` | yes | `"create"` or `"update"`. |
+| `capability` | yes | Synced capability contract. |
+| `workflowConfigID` | update only | Comes from completed status result. |
+| `updatePrompt` | update only | Natural language behavior change request. |
+| `requestMeta` | no | Optional execution metadata. |
+
+Do not hand-copy stale schemas. Submit from synced `.howone/ai/manifest.json` whenever possible.
+
+## Create Request
+
+```json
+{
+  "operations": [
+    {
+      "appId": "proj_docs",
+      "workflowId": "550e8400-e29b-41d4-a716-446655440000",
+      "mode": "create",
+      "capability": {
+        "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"
+      },
+      "requestMeta": {}
+    }
+  ]
+}
+```
+
+Create response:
+
+```json
+{
+  "request_ids": [
+    {
+      "request_id": "req_abc123",
+      "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
+      "workflow_config_id": null,
+      "operation_type": "generate"
+    }
+  ]
+}
+```
+
+Store every `request_id`.
+
+## Update Request
+
+Use update when the external workflow implementation already exists.
+
+```json
+{
+  "operations": [
+    {
+      "appId": "proj_docs",
+      "workflowId": "550e8400-e29b-41d4-a716-446655440000",
+      "workflowConfigID": "cfg_xyz789",
+      "mode": "update",
+      "capability": {
+        "name": "summarizeDocument",
+        "description": "Reads an uploaded document and produces a concise summary. Supports paragraph or bullet-point format.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "document_url": {
+              "type": "string",
+              "format": "uri",
+              "description": "Supabase Storage URL of the uploaded document."
+            },
+            "output_format": {
+              "type": "string",
+              "description": "Format of the summary output: paragraphs or bullet_points."
+            }
+          },
+          "required": ["document_url"]
+        },
+        "outputSchema": {
+          "type": "object",
+          "properties": {
+            "summary": {
+              "type": "string",
+              "description": "The generated summary in the requested format and same language as the source document."
+            }
+          },
+          "required": ["summary"]
+        },
+        "outputEntityName": "DocumentSummary"
+      },
+      "updatePrompt": "Add support for optional bullet-point summary output through output_format.",
+      "requestMeta": {}
+    }
+  ]
+}
+```
+
+Update response has `operation_type: "edit"`.
+
+## Status Polling
+
+```text
+POST /workflow/{project_short_id}/operate
+  -> request_ids[]
+
+GET /workflow/status_check/{request_id}
+  -> queued/running/completed/failed
+```
+
+Poll every 2-5 seconds until terminal.
+
+Status values:
+
+| Status | Meaning | Action |
+|---|---|---|
+| `queued` | waiting | continue polling |
+| `running` | being generated/edited | continue polling |
+| `completed` | operation finished | inspect `payload.success` |
+| `failed` | system failure | report/display error |
+
+Completed success:
+
+```json
+{
+  "success": true,
+  "jobId": "req_abc123",
+  "status": "completed",
+  "payload": {
+    "success": true,
+    "workflow_details": {
+      "workflow_graph": {},
+      "new_workflow_config_id": "cfg_xyz789"
+    }
+  }
+}
+```
+
+Completed business failure:
+
+```json
+{
+  "success": true,
+  "status": "completed",
+  "payload": {
+    "success": false,
+    "display_error_message": "Unable to generate workflow: the requested capability is not supported.",
+    "full_error_message": "Detailed internal error..."
+  }
+}
+```
+
+System failure:
+
+```json
+{
+  "success": true,
+  "status": "failed",
+  "payload": {
+    "success": false,
+    "display_error_message": "Service temporarily unavailable.",
+    "full_error_message": "Timeout after 120s waiting for LLM response."
+  }
+}
+```
+
+On success, persist:
+
+- `request_id`;
+- `workflowId`;
+- `new_workflow_config_id`;
+- capability name;
+- mode;
+- any status/error useful for future update.
+
+## Agent Handoff Notes
+
+When another tool/layer owns submission:
+
+- provide the synced capability name and manifest path;
+- do not rewrite raw schemas if the tool can load manifest;
+- preserve returned request IDs;
+- after status success, preserve `workflowConfigID` for future edits;
+- regenerate SDK only after manifest changes, not after behavior-only workflow edits.
+
+## Operation Checklist
+
+- Manifest is synced before submit.
+- `appId` matches path project ID.
+- `workflowId` is a UUID.
+- `mode=create` omits `workflowConfigID`.
+- `mode=update` includes confirmed `workflowConfigID`.
+- `updatePrompt` says what to change, not a whole new fake schema.
+- Request IDs are stored.
+- Status is polled to terminal.
+- Business failure and system failure are handled differently.