@powerformer/refly-cli 0.1.13 → 0.1.15

package/skill/references/skill.md

@@ -2,36 +2,217 @@
 
 ## CLI Commands
 
+### Discovery
+
+```bash
+# List skill packages
+refly skill list [options]
+  --status <status>     # Filter: draft, published, deprecated
+  --mine                # Show only my packages
+  --tags <tags>         # Filter by tags (comma-separated)
+  --page <number>       # Page number (default: 1)
+  --page-size <number>  # Page size (default: 20)
+
+# Search public packages
+refly skill search <query> [options]
+  --tags <tags>         # Filter by tags (comma-separated)
+  --page <number>       # Page number (default: 1)
+  --page-size <number>  # Page size (default: 20)
+
+# Get skill details
+refly skill get <skillId> [options]
+  --include-workflows   # Include workflow details
+  --share-id <shareId>  # Share ID for private skills
+```
+
+### Lifecycle
+
+```bash
+# Create skill package (see "Skill Creation Modes" below)
+refly skill create [options]
+  --name <name>                 # Skill name (required)
+  --version <version>           # Semantic version (default: 1.0.0)
+  --description <desc>          # Skill description
+  --triggers <triggers>         # Trigger phrases (comma-separated)
+  --tags <tags>                 # Category tags (comma-separated)
+  --workflow <workflowId>       # Bind single workflow
+  --workflow-ids <ids>          # Bind multiple workflows (comma-separated)
+  --workflow-spec <json>        # Workflow spec JSON
+  --workflow-query <query>      # Natural language description
+  --verbose                     # Include workflow details in output
+
+# Publishing
+refly skill publish <skillId>   # Make public
+refly skill unpublish <skillId> # Make private
+refly skill delete <skillId> [options]
+  --force                       # Skip confirmation
+
+# Local management
+refly skill sync [options]      # Sync registry with filesystem
+  --dry-run                     # Preview changes only
+  --prune                       # Remove orphan entries
+
+refly skill validate [path] [options]
+  --fix                         # Attempt to fix issues
+```
+
+### Installation
+
+```bash
+# Install skill
+refly skill install <skillId> [options]
+  --version <version>   # Specific version
+  --share-id <shareId>  # Share ID for private skills
+  --config <json>       # Installation config JSON
+
+# List installations
+refly skill installations [options]
+  --status <status>     # Filter: downloading, initializing, ready, error, disabled
+  --page <number>       # Page number (default: 1)
+  --page-size <number>  # Page size (default: 20)
+
+# Uninstall
+refly skill uninstall <installationId> [options]
+  --force               # Skip confirmation
+```
+
+### Execution
+
+```bash
+# Run installed skill
+refly skill run <installationId> [options]
+  --input <json>                # Input JSON for the skill
+  --workflow <skillWorkflowId>  # Run specific workflow only
+  --async                       # Run asynchronously
+```
+
+---
+
+## Skill Creation Modes
+
+### Mode 1: Generate Workflow from Query
+
+```bash
+refly skill create --name <name> --workflow-query "<query>"
+```
+
+Behavior:
+1. Calls backend AI to generate workflow
+2. Creates skill and binds workflow
+3. Returns skillId + workflowId
+
+Optional metadata (does not generate workflow by itself):
+- `--description`, `--triggers`, `--tags`
+
+Example:
+```bash
+refly skill create \
+  --name comfyui-refly-skill \
+  --workflow-query "ComfyUI image generation workflow collection" \
+  --description "ComfyUI image workflow collection" \
+  --triggers "comfyui,text to image,image generation,image to image" \
+  --tags "image,comfyui"
+```
+
+### Mode 2: Bind Existing Workflow(s)
+
+```bash
+refly skill create --name <name> --workflow <workflowId>
+```
+
+Bind multiple workflows:
+```bash
+refly skill create --name <name> --workflow-ids "<workflowId1,workflowId2>"
+```
+
+Example:
+```bash
+refly skill create \
+  --name my-skill \
+  --description "My custom skill" \
+  --workflow c-zybbx65ydi5npo7xevjx1wlr \
+  --triggers "custom,workflow" \
+  --tags "internal"
+```
+
+### Mode 3b: Bind Multiple Workflows (Explicit)
+
+```bash
+refly skill create --name <name> --workflow-ids "<workflowId1,workflowId2>"
+```
+
+Example:
+```bash
+refly skill create \
+  --name multi-workflow-skill \
+  --description "Multiple workflow entry points" \
+  --workflow-ids "c-aaa111,c-bbb222" \
+  --triggers "multi,entry" \
+  --tags "batch,workflow"
+```
+
+### Mode 3: Use Workflow Spec (Structured)
+
+```bash
+refly skill create --name <name> --workflow-spec '<json>'
+```
+
+Example:
+```bash
+refly skill create \
+  --name pdf-processor \
+  --workflow-spec '{
+    "nodes": [
+      {"id": "n1", "type": "start", "data": {"title": "Start"}},
+      {"id": "n2", "type": "skillResponse", "data": {"title": "Process PDF", "metadata": {"query": "Extract and summarize PDF content"}}}
+    ],
+    "edges": [
+      {"id": "e1", "source": "n1", "target": "n2"}
+    ]
+  }'
+```
+
+> **Note**: Examples use `start` and `skillResponse`. Additional node types may be supported by backend.
+
+### Mode 4: Local Skill Only (No Cloud Package)
+
+Use when you only want a local skill directory and registry entry.
+
 ```bash
-# Discovery
-refly skill list                    # List all domain skills
-refly skill search "<query>"        # Search by keyword
-refly skill get <name>              # Get skill details
+# Create local skill files manually, then sync
+refly skill sync
+```
 
-# Lifecycle
-refly skill create --workflow <id> --name <name>   # Create from workflow
-refly skill run <name> --input '<json>'            # Run skill
-refly skill delete <name>                          # Delete skill
+You can later create a cloud skill package with:
+```bash
+refly skill create --name <name> --workflow <workflowId>
 ```
 
 ---
 
+## Workflow Generation Logic
+
+When no `--workflow`, `--workflow-ids`, `--workflow-spec`, or `--workflow-query` is specified,
+CLI will return `skill.create.needs_workflow` with suggested options and examples.
+
+---
+
 ## Directory Structure
 
 ```
 ~/.claude/skills/refly/
-├── SKILL.md                    # Base skill
-├── registry.json               # Skill index
-├── references/                 # Core CLI docs
-│   ├── workflow.md
-│   ├── node.md
-│   ├── file.md
-│   └── skill.md
-└── domain-skills/              # Domain skills (one directory per skill)
-    └── <skill-name>/
-        ├── skill.md            # Entry file
-        ├── REFERENCE.md        # API reference (optional)
-        └── EXAMPLES.md         # Examples (optional)
+|-- SKILL.md                    # Base skill
+|-- registry.json               # Skill index
+|-- references/                 # Core CLI docs
+|   |-- workflow.md
+|   |-- node.md
+|   |-- file.md
+|   `-- skill.md
+`-- domain-skills/              # Domain skills (one directory per skill)
+    `-- <skill-name>/
+        |-- skill.md            # Entry file
+        |-- REFERENCE.md        # API reference (optional)
+        `-- EXAMPLES.md         # Examples (optional)
 ```
 
 ---
@@ -46,19 +227,22 @@ refly skill delete <name>                          # Delete skill
     {
       "name": "pdf-processing",
       "description": "Extract text/tables from PDF, fill forms, merge documents.",
-      "workflowId": "wf_pdf_processing_v1",
-      "triggers": ["pdf extract", "处理 pdf", "fill pdf form"],
-      "path": "domain-skills/pdf-processing/",
+      "workflowId": "c-abc123xyz",
+      "triggers": ["pdf extract", "process pdf", "fill pdf form"],
+      "path": "domain-skills/pdf-processing",
       "createdAt": "2025-01-14T00:00:00Z",
-      "source": "local"
+      "updatedAt": "2025-01-14T00:00:00Z",
+      "source": "local",
+      "tags": ["pdf", "document"],
+      "author": "team-refly",
+      "version": "1.0.0",
+      "skillId": "skp-abc123"
     }
   ]
 }
 ```
 
----
-
-## Registry Fields
+### Registry Fields
 
 | Field | Type | Required | Description |
 |------|------|----------|-------------|
@@ -66,9 +250,14 @@ refly skill delete <name>                          # Delete skill
 | description | string | Yes | One-line summary for matching |
 | workflowId | string | Yes | Bound workflow ID in Refly backend |
 | triggers | string[] | Yes | Phrases that trigger this skill |
-| path | string | Yes | Relative path to skill directory (e.g. `domain-skills/pdf-processing/`) |
+| path | string | Yes | Relative path to skill directory |
 | createdAt | string | Yes | ISO 8601 timestamp |
 | source | string | Yes | `local` or `refly-cloud` |
+| updatedAt | string | No | ISO 8601 timestamp |
+| tags | string[] | No | Categorization tags |
+| author | string | No | Skill author |
+| version | string | No | Semantic version |
+| skillId | string | No | Cloud skill ID (if available) |
 
 ---
 
@@ -84,6 +273,10 @@ workflowId: <workflow-id>
 triggers:
   - <phrase-1>
   - <phrase-2>
+tags:
+  - <tag-1>
+author: <author>
+version: 1.0.0
 ---
 
 # <Skill Name>
@@ -95,7 +288,7 @@ triggers:
 ## Run
 
 ```bash
-refly skill run <skill-name> --input '<json>'
+refly skill run <installationId> --input '<json>'
 ```
 
 ## Advanced
@@ -111,9 +304,161 @@ refly skill run <skill-name> --input '<json>'
 **Naming**: lowercase, hyphens, max 64 chars (`pdf-processing`, `doc-translator`)
 
 **Description**: verb + what + when, third person, under 100 chars
-- ✓ "Extracts text from PDF files. Use when processing PDF documents."
-- ✗ "I can help you with PDFs"
+- Good: "Extracts text from PDF files. Use when processing PDF documents."
+- Bad: "I can help you with PDFs"
 
 **Triggers**: 3-6 high-signal phrases, mix EN/ZH if needed
 
 **Structure**: Each skill is a directory with `skill.md` as entry; push details to sibling files
+
+**Workflow Creation**:
+1. Be specific in workflow query - helps AI generate accurate workflow
+2. Include diverse triggers - cover EN/ZH variations
+3. Test before publish - install then run (`refly skill install` -> `refly skill run`)
+4. Use `--workflow-spec` for complex scenarios requiring precise control
+
+---
+
+## Local Skills vs Cloud Skills
+
+| Type | Location | Management | Use Case |
+|------|----------|------------|----------|
+| Local | `~/.claude/skills/refly/domain-skills/` | `registry.json` | Fast iteration |
+| Cloud | Backend `SkillPackage` | API | Distribution & versioning |
+
+Integration flow:
+1. Write local `skill.md` -> run `refly skill sync` -> updates `registry.json`
+2. Create cloud skill -> `refly skill create` (bind workflow) -> `refly skill publish`
+3. Install to run -> `refly skill install` -> `refly skill run <installationId>`
+4. Cloud skills can still match locally via `source: refly-cloud`
+
+---
+
+## Output Examples
+
+### List Output
+
+```json
+{
+  "ok": true,
+  "type": "skill.list",
+  "version": "1.0",
+  "payload": {
+    "skills": [
+      {
+        "skillId": "skp-xxx",
+        "name": "my-skill",
+        "version": "1.0.0",
+        "description": "Skill description",
+        "status": "published",
+        "isPublic": true,
+        "downloadCount": 10,
+        "createdAt": "2026-01-19T00:00:00Z"
+      }
+    ],
+    "total": 10,
+    "page": 1,
+    "pageSize": 20,
+    "hasMore": false
+  }
+}
+```
+
+### Installations Output
+
+```json
+{
+  "ok": true,
+  "type": "skill.installations",
+  "version": "1.0",
+  "payload": {
+    "installations": [
+      {
+        "installationId": "skpi-xxx",
+        "skillId": "skp-xxx",
+        "skillName": "my-skill",
+        "skillVersion": "1.0.0",
+        "status": "ready",
+        "installedAt": "2026-01-19T00:00:00Z"
+      }
+    ],
+    "total": 3,
+    "page": 1,
+    "pageSize": 20,
+    "hasMore": false
+  }
+}
+```
+
+### Execution Output
+
+```json
+{
+  "ok": true,
+  "type": "skill.run",
+  "version": "1.0",
+  "payload": {
+    "executionId": "skpe-xxx",
+    "installationId": "skpi-xxx",
+    "status": "completed",
+    "workflowExecutions": [
+      {
+        "skillWorkflowId": "skw-xxx",
+        "workflowId": "c-xxx",
+        "status": "completed"
+      }
+    ],
+    "result": {},
+    "error": null
+  }
+}
+```
+
+---
+
+## Skill Sync Details
+
+`refly skill sync` will:
+- Scan local `domain-skills/` directories
+- Load frontmatter from each `skill.md`
+- Update `registry.json` with added/updated entries
+- Optionally prune orphan entries with `--prune`
+
+---
+
+## Skill Validate Details
+
+`refly skill validate [path]` will:
+- Validate frontmatter schema and required fields
+- Return per-file errors and warnings
+- Provide a summary of valid/invalid files
+
+Example output:
+```json
+{
+  "ok": true,
+  "type": "skill.validate",
+  "version": "1.0",
+  "payload": {
+    "path": "/path/to/skills",
+    "summary": {
+      "total": 3,
+      "valid": 2,
+      "invalid": 1,
+      "warnings": 1
+    }
+  }
+}
+```
+
+---
+
+## Error Handling
+
+| Error Code | Cause | Solution |
+|------------|-------|----------|
+| `VALIDATION_ERROR` | Missing required params or invalid format | Check `--name` and other required params |
+| `ACCESS_DENIED` | No permission for resource | Verify login and resource ownership |
+| `INTERNAL_ERROR` | Server error | Retry later or contact support |
+
+> **Note**: Invalid JSON in `--workflow-spec` will fail the command; ensure it is valid JSON.

package/skill/references/workflow.md

@@ -2,31 +2,142 @@
 
 ## Workflow Commands
 
+### Management
+
 ```bash
-refly workflow create --name "<name>" --spec '<json>'
-refly workflow generate --query "<natural language description>"
-refly workflow edit <workflowId> --ops '<json>'
+# Create workflow
+refly workflow create [options]
+  --name <name>              # Workflow name
+  --spec <json>              # Workflow spec JSON
+  --description <desc>       # Description
+
+# Generate workflow from natural language
+refly workflow generate [options]
+  --query <query>            # Natural language description
+  --canvas-id <id>           # Update existing workflow
+  --model-id <id>            # Model for generation
+  --locale <locale>          # Output language (en, zh)
+  --timeout <ms>             # Timeout (default: 300000)
+  --variables <json>         # Predefined variables
+  --skip-default-nodes       # Skip default start+skillResponse
+  --no-cleanup               # Disable orphan cleanup on failure
+
+# Edit workflow
+refly workflow edit <workflowId> [options]
+  --name <name>              # New name
+  --ops <json>               # Node/edge operations
+  --variables <json>         # Variables array
+  --toolsets <keys>          # Toolset keys (comma-separated)
+  --auto-layout              # Auto-layout nodes
+
+# Patch workflow plan
+refly workflow patch <planId> [options]
+  --ops <json>               # Operations array
+  --ops-file <path>          # Read ops from file
+  --update-title <title>     # Shortcut: update title
+  --delete-task <taskId>     # Shortcut: delete task
+  --delete-variable <varId>  # Shortcut: delete variable
+
+# Other management
 refly workflow get <workflowId>
-woshrefly workflow nodes <workflowId>
-refly workflow nodes <workflowId> --include-edges
-refly workflow nodes <workflowId> --include-metadata
-refly workflow list
 refly workflow delete <workflowId>
-refly workflow run <workflowId> --input '<json>'
-refly workflow status <runId>
-refly workflow status <runId> --watch
-refly workflow run detail <runId>
-refly workflow run node <runId> <nodeId>
-refly workflow run toolcalls <runId>
-refly workflow abort <runId>
+refly workflow list [--limit <n>] [--offset <n>]
+refly workflow layout <workflowId> [--direction LR|TB]
+refly workflow toolset-keys [--type <type>]
+```
+
+### Execution
+
+```bash
+# Start workflow run
+refly workflow run start <workflowId> [options]
+  --input <json>             # Input variables
+  --from-node <nodeId>       # Run From Here
+
+# Query run status
+refly workflow run get <runId>
+refly workflow run detail <runId> [--no-tool-calls] [--preview-length <n>]
+refly workflow runs <workflowId> [--limit <n>] [--offset <n>] [--status <s>]
+refly workflow status <id> [--watch] [--interval <ms>] [--full]
+refly workflow detail <id> [--no-tool-calls] [--preview-length <n>]
+refly workflow abort <workflowId>
+```
+
+### Node Operations
+
+```bash
+# List/get nodes
+refly workflow nodes <workflowId> [--include-edges] [--include-position] [--include-metadata]
+refly workflow node <id> <nodeId> [--include-connections]
+refly workflow node-output <id> <nodeId> [--include-tool-calls] [--raw]
+
+# Run from node
+refly workflow run node-start [options]
+  --from <nodeId>            # Node to run from
+  --run-id <runId>           # Existing run context
+  --workflow-id <id>         # Start new run
+
+# Node results
+refly workflow run node-detail <runId> <nodeId> [--include-messages] [--raw]
+refly workflow run node-result <resultId> [--include-steps] [--include-messages] [--include-tool-calls]
+refly workflow run node-abort <resultId> [--version <n>]
+```
+
+### Tool Calls
+
+```bash
+# Workflow-level tool calls (full options)
+refly workflow toolcalls <id> [options]
+refly workflow run toolcalls <runId> [options]
+  --node-id <nodeId>         # Filter by node
+  --toolset-id <id>          # Filter by toolset
+  --tool-name <name>         # Filter by tool name
+  --status <status>          # Filter: executing, completed, failed
+  --limit <n>                # Max results (default: 100)
+  --offset <n>               # Pagination offset
+  --raw                      # Full output without sanitization
+
+# Node-level tool calls (limited options)
+refly workflow run node-toolcalls <resultId> [options]
+  --status <status>          # Filter: executing, completed, failed
+  --tool-name <name>         # Filter by tool name
+  --toolset-id <id>          # Filter by toolset
+
+# Single tool call
+refly workflow run node-toolcall <callId> [--raw]
 ```
 
 ## Interaction
 
-- `workflow run` returns `runId` used by `workflow status` and `workflow run node`.
-- `workflow run node` returns `resultId` for action/tool lookups (see `node.md`).
+- `workflow run start` returns `runId` used by `workflow run get` and `workflow run node-detail`.
+- `workflow run node-detail` returns `resultId` for action/tool lookups (see `node.md`).
+- `workflow node-output` retrieves the actual execution output content of a node.
 - Action results may include file IDs; use `file.md` to fetch/download.
 
+## Node Output Command
+
+Get the execution output content of a specific node:
+
+```bash
+# Using workflowId (gets output from latest run)
+refly workflow node-output c-xxx <nodeId>
+
+# Using runId (gets output from specific run)
+refly workflow node-output we-xxx <nodeId>
+
+# Include tool call details
+refly workflow node-output <id> <nodeId> --include-tool-calls
+
+# Get full content without truncation (default: 10KB limit)
+refly workflow node-output <id> <nodeId> --raw
+```
+
+**ID Type Detection:**
+- `c-xxx` prefix: Treated as workflowId, uses latest/active run
+- `we-xxx` prefix: Treated as runId, uses specific run
+
+**Security:** Node output access requires ownership verification at both workflow execution level and action result level (defense-in-depth).
+
 ## Workflow Generate Examples
 
 ```bash
@@ -37,7 +148,7 @@ refly workflow generate --query "Parse PDF, summarize content, translate to Chin
 refly workflow generate \
   --query "Research topic, write article, export to markdown" \
   --model-id <modelId> \
-  --locale zh \
+  --locale en \
   --timeout 300000
 ```
 
@@ -47,39 +158,21 @@ refly workflow generate \
   --variables '[{"variableId":"v1","name":"inputFolder","variableType":"string"}]'
 ```
 
-## Workflow Spec Schema (v1)
+## Workflow Spec Schema (Simplified)
+
+`workflow create` expects a simplified spec (no `version` or `metadata`).
+Supported node types: `skill`, `agent` (start node is auto-created).
 
 ```json
 {
-  "version": 1,
-  "name": "string",
-  "description": "string?",
   "nodes": [
     {
       "id": "string",
-      "type": "string",
-      "input": {},
+      "type": "skill",
+      "query": "string",
+      "toolsetKeys": ["string"],
       "dependsOn": ["string"]
     }
-  ],
-  "metadata": {
-    "tags": ["string"],
-    "owner": "string?"
-  }
+  ]
 }
 ```
-
-## Backend API (Workflow)
-
-- POST /v1/cli/workflow create
-- POST /v1/cli/workflow/generate AI generate
-- GET /v1/cli/workflow list
-- GET /v1/cli/workflow/:id detail
-- PATCH /v1/cli/workflow/:id update
-- DELETE /v1/cli/workflow/:id delete
-- POST /v1/cli/workflow/:id/run start run
-- GET /v1/cli/workflow/run/:runId run status
-- POST /v1/cli/workflow/run/:runId/abort abort run
-- GET /v1/cli/workflow/run/:runId/detail run detail
-- GET /v1/cli/workflow/run/:runId/node/:nodeId node result (workflow scope)
-- GET /v1/cli/workflow/run/:runId/toolcalls tool calls (workflow scope)