@powerformer/refly-cli 0.1.4 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerformer/refly-cli",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Refly CLI - Command-line interface for Refly workflow orchestration",
   "bin": {
     "refly": "./dist/bin/refly.js"
@@ -18,7 +18,12 @@
     "test": "vitest run",
     "prepublishOnly": "pnpm run build"
   },
-  "keywords": ["refly", "cli", "workflow", "automation"],
+  "keywords": [
+    "refly",
+    "cli",
+    "workflow",
+    "automation"
+  ],
   "author": "Refly AI",
   "license": "MIT",
   "dependencies": {
@@ -36,5 +41,9 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "files": ["dist", "skill", "commands"]
+  "files": [
+    "dist",
+    "skill",
+    "commands"
+  ]
 }

package/skill/SKILL.md

@@ -1,247 +1,57 @@
 ---
-name: refly
+name: refly-skill-manager
 description: |
-  Refly workflow orchestration via local CLI (secure). Use this skill when the user asks to:
-  - Create / edit / run workflows (DAG/pipeline/工作流/编排/automation)
-  - Run or debug workflow nodes (node.run, 单节点调试)
-  - Build multi-step document pipelines (parse/summarize/translate/export)
-  - Manage workflow runs (status/abort/logs)
-  Triggers: refly, workflow, DAG, pipeline, 自动化流程, 多步骤任务, 编排任务, 创建工作流, 运行流程.
+  Base skill for Refly ecosystem: creates, discovers, and runs domain-specific skills bound to workflows.
+  Routes user intent to matching domain skills via local registry, delegates execution to Refly backend.
+  Use when user asks to: create skills, run workflows, automate multi-step tasks, or manage pipelines.
+  Triggers: refly, skill, workflow, run skill, create skill, automation, pipeline.
   Requires: @refly/cli installed and authenticated.
 ---
 
-# Refly Skill (CLI-first, Secure, DAG-native)
+# Refly Skill Manager
 
-## 0) Mandatory Execution Rules (NON-NEGOTIABLE)
+## Rules
 
-When this skill is triggered:
+1. **CLI only** - Use `refly <command>`, never call API directly.
+2. **Trust JSON** - Only trust CLI JSON (`ok`, `payload`, `error`, `hint`).
+3. **No fabricated IDs** - Never invent workflow/run/node IDs.
+4. **No tokens** - Never print or request auth tokens.
+5. **Stop on error** - If `ok=false`, stop and show `hint`.
 
-1. MUST use Refly CLI for all actions.
-   - Do NOT call Refly API directly.
-   - Do NOT fabricate API calls, workflow IDs, run IDs, node IDs, or outputs.
-
-2. MUST rely only on CLI JSON output for state.
-   - Never assume a workflow exists unless CLI returned it.
-
-3. MUST keep token private.
-   - Never print, request, or infer tokens.
-   - If auth fails, instruct the user to run `refly login` or `refly init`.
-
-4. MUST present results based on verified CLI JSON fields.
-
-If any rule cannot be satisfied, STOP and tell the user exactly what to run next.
-
----
-
-## 1) Preconditions / Environment Check
-
-Before any operation:
+## Quick Commands
 
 ```bash
 refly status
+refly login
+refly skill list
+refly skill run <name> --input '<json>'
 ```
 
-- If `ok=false` and `error.code=AUTH_REQUIRED`: run `refly login` (or `refly init`).
-- If `error.code=CLI_NOT_FOUND`: install `npm i -g @refly/cli` and rerun.
-
----
-
-## 2) Output Contract (STRICT)
-
-Success:
-```json
-{ "ok": true, "type": "workflow.create", "version": "1.0", "payload": {} }
-```
-
-Error:
-```json
-{ "ok": false, "type": "error", "version": "1.0", "error": { "code": "AUTH_REQUIRED", "message": "...", "hint": "refly login" } }
-```
-
-Rules:
-- Only trust `payload`.
-- If `ok=false`, do NOT proceed. Show `hint`.
-
----
-
-## 3) Core Commands
-
-### Authentication
-```bash
-refly init                    # Initialize and install skill
-refly login                   # Authenticate with API key
-refly logout                  # Remove credentials
-refly status                  # Check CLI and auth status
-refly whoami                  # Show current user
-```
-
-### Workflow CRUD
-```bash
-refly workflow create --name "<name>" --spec '<json>'
-refly workflow generate --query "<natural language description>"  # AI-powered workflow generation
-refly workflow edit <workflowId> --ops '<json>'
-refly workflow get <workflowId>
-refly workflow list
-refly workflow delete <workflowId>
-```
-
-### Workflow Run & Monitoring
-```bash
-refly workflow run <workflowId> --input '<json>'
-refly workflow status <runId>                    # Get detailed execution status
-refly workflow status <runId> --watch            # Watch until completion (polls every 2s)
-refly workflow run detail <runId>                # Full workflow execution detail
-refly workflow run node <runId> <nodeId>         # Single node execution result
-refly workflow run toolcalls <runId>             # All tool calls in workflow
-refly workflow abort <runId>
-```
-
-### Node Operations
-```bash
-refly node types                                 # List available node types
-refly node run --type "<nodeType>" --input '<json>'  # Run a node for debugging
-refly node result <resultId>                     # Get node execution result
-refly node result <resultId> --include-tool-calls    # Include tool call details
-```
-
-### Tool Inspection
-```bash
-refly tool calls --result-id <resultId>          # Get tool execution results for a node
-refly tool get <callId>                          # Get single tool call detail
-```
-
-### Action Result
-```bash
-refly action result <resultId>                   # Action result with default sanitization
-refly action result <resultId> --version <n>     # Specific version
-refly action result <resultId> --raw             # Disable sanitization/truncation
-refly action result <resultId> --include-files   # Include related files
-```
+## Directory Structure
 
-### File Operations
-```bash
-refly file list                                  # List files
-refly file list --canvas-id <id>                 # Filter by canvas
-refly file get <fileId>                          # Get file metadata and content
-refly file download <fileId> -o ./output.txt     # Download file to local filesystem
 ```
-
----
-
-## 4) AI Workflow Generation
-
-Use `workflow generate` to create workflows from natural language:
-
-```bash
-# Basic generation
-refly workflow generate --query "Parse PDF, summarize content, translate to Chinese"
-
-# With options
-refly workflow generate \
-  --query "Research topic, write article, export to markdown" \
-  --model-id <modelId> \
-  --locale zh \
-  --timeout 300000
-
-# With predefined variables
-refly workflow generate \
-  --query "Process documents from input folder" \
-  --variables '[{"variableId":"v1","name":"inputFolder","variableType":"string"}]'
-```
-
-The generate command:
-- Invokes AI to parse the natural language query
-- Creates a workflow plan with tasks
-- Builds the DAG with appropriate nodes and edges
-- Returns workflowId, planId, and task details
-
----
-
-## 5) DAG Rules (STRICT)
-
-- Unique node ids.
-- No cycles.
-- Dependencies reference existing nodes only.
-- Insert X between A→B by rewiring dependencies.
-
----
-
-## 6) Workflow Spec Schema (v1)
-
-```json
-{
-  "version": 1,
-  "name": "string",
-  "description": "string?",
-  "nodes": [
-    {
-      "id": "string",
-      "type": "string",
-      "input": {},
-      "dependsOn": ["string"]
-    }
-  ],
-  "metadata": {
-    "tags": ["string"],
-    "owner": "string?"
-  }
-}
+~/.claude/skills/refly/
+├── SKILL.md                    # Base skill (this file)
+├── registry.json               # Routing registry
+├── 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
+        └── ...                 # Additional docs
 ```
 
----
-
-## 7) Error Codes
-
-| Code | Description | Hint |
-|------|-------------|------|
-| AUTH_REQUIRED | Not authenticated | refly login |
-| CLI_NOT_FOUND | CLI not installed | npm i -g @refly/cli |
-| NETWORK_ERROR | API unreachable | Check connection |
-| NOT_FOUND | Resource not found | Verify ID |
-| CONFLICT | State conflict | Check status |
-| INTERNAL_ERROR | Unexpected error | Report issue |
-
----
-
-## 8) References
-
-- `references/workflow-schema.md` - Full schema documentation
-- `references/node-types.md` - Available node types
-- `references/api-errors.md` - Complete error reference
-
-## 9) Execution Results Workflow (Recommended)
-
-Use this flow when tracking a running workflow and extracting results:
-
-1. **Start run**: `refly workflow run <workflowId> --input '<json>'`
-2. **Monitor status**: `refly workflow status <runId> --watch`
-3. **On node finish**: `refly workflow run node <runId> <nodeId>`
-4. **Tool calls** (optional): `refly workflow run toolcalls <runId>` or `refly tool get <callId>`
-5. **Raw output** for debugging: add `--raw` to disable sanitization
-
-## 10) CLI Backend API Reference (Workflow/Node/Tool)
-
-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)
+## Routing
 
-Node:
-- `GET /v1/cli/node/types` list node types
-- `POST /v1/cli/node/run` run a single node (not implemented yet)
+User intent → match domain skill (name/trigger/description) → read domain skill `.md`
+→ execute via `refly skill run` → return CLI-verified result.
 
-Tool:
-- `GET /v1/cli/toolcall?resultId=<id>&version=<n>` tool calls for action result
-- `GET /v1/cli/toolcall/:callId` single tool call detail
+## References
 
-Action (related):
-- `GET /v1/cli/action/result?resultId=<id>&version=<n>&sanitizeForDisplay=<bool>&includeFiles=<bool>`
+- `references/workflow.md`
+- `references/node.md`
+- `references/file.md`
+- `references/skill.md`

package/skill/references/file.md

@@ -0,0 +1,20 @@
+# File Reference
+
+## File Commands
+
+```bash
+refly file list
+refly file list --canvas-id <id>
+refly file get <fileId>
+refly file download <fileId> -o ./output.txt
+```
+
+## Interaction
+
+- File IDs typically come from action results (`node.md`) or workflow outputs (`workflow.md`).
+- Use file commands to retrieve content produced by workflow runs.
+
+## Backend API (File)
+
+- GET /v1/cli/file list files
+- GET /v1/cli/file/:id get file

package/skill/references/node.md

@@ -0,0 +1,46 @@
+# Node Reference
+
+## Node Commands
+
+```bash
+refly node types
+refly node run --type "<nodeType>" --input '<json>'
+refly node result <resultId>
+refly node result <resultId> --include-tool-calls
+refly node result <resultId> --include-steps
+refly node result <resultId> --include-messages
+```
+
+## Interaction
+
+- `workflow run node <runId> <nodeId>` yields `resultId` used by node/tool commands.
+- Use `node result` to fetch node output and optional file IDs.
+- Use `tool calls` to inspect tool executions tied to a result.
+- File IDs from node results should be handled via `file.md`.
+
+## Node Result Commands
+
+```bash
+refly node result <resultId>
+refly node result <resultId> --include-steps
+refly node result <resultId> --include-messages
+refly node result <resultId> --include-tool-calls
+```
+
+## Tool Commands
+
+```bash
+refly tool calls --result-id <resultId>
+refly tool get <callId>
+```
+
+## Backend API (Node)
+
+- GET /v1/cli/node/types list node types
+- POST /v1/cli/node/run run a single node (not implemented yet)
+- GET /v1/cli/node/result?resultId=<id> get node execution result
+
+## Backend API (Tool)
+
+- GET /v1/cli/toolcall?resultId=<id>&version=<n> tool calls for action result
+- GET /v1/cli/toolcall/:callId single tool call detail

package/skill/references/skill.md

@@ -0,0 +1,119 @@
+# Skill Reference
+
+## CLI Commands
+
+```bash
+# Discovery
+refly skill list                    # List all domain skills
+refly skill search "<query>"        # Search by keyword
+refly skill get <name>              # Get skill details
+
+# 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
+```
+
+---
+
+## 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)
+```
+
+---
+
+## Registry Schema
+
+```json
+{
+  "version": 1,
+  "updatedAt": "2025-01-14T00:00:00Z",
+  "skills": [
+    {
+      "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/",
+      "createdAt": "2025-01-14T00:00:00Z",
+      "source": "local"
+    }
+  ]
+}
+```
+
+---
+
+## Registry Fields
+
+| Field | Type | Required | Description |
+|------|------|----------|-------------|
+| name | string | Yes | Unique skill identifier (lowercase, hyphens) |
+| 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/`) |
+| createdAt | string | Yes | ISO 8601 timestamp |
+| source | string | Yes | `local` or `refly-cloud` |
+
+---
+
+## Domain Skill Template
+
+Location: `~/.claude/skills/refly/domain-skills/<skill-name>/skill.md`
+
+````markdown
+---
+name: <skill-name>
+description: <one-line summary, under 100 chars>
+workflowId: <workflow-id>
+triggers:
+  - <phrase-1>
+  - <phrase-2>
+---
+
+# <Skill Name>
+
+## Quick Start
+
+<Minimal code example>
+
+## Run
+
+```bash
+refly skill run <skill-name> --input '<json>'
+```
+
+## Advanced
+
+**Feature A**: See [FEATURE_A.md](FEATURE_A.md)
+**API Reference**: See [REFERENCE.md](REFERENCE.md)
+````
+
+---
+
+## Best Practices
+
+**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"
+
+**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

package/skill/references/workflow.md

@@ -0,0 +1,82 @@
+# Workflow Reference
+
+## Workflow Commands
+
+```bash
+refly workflow create --name "<name>" --spec '<json>'
+refly workflow generate --query "<natural language description>"
+refly workflow edit <workflowId> --ops '<json>'
+refly workflow get <workflowId>
+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>
+```
+
+## 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`).
+- Action results may include file IDs; use `file.md` to fetch/download.
+
+## Workflow Generate Examples
+
+```bash
+refly workflow generate --query "Parse PDF, summarize content, translate to Chinese"
+```
+
+```bash
+refly workflow generate \
+  --query "Research topic, write article, export to markdown" \
+  --model-id <modelId> \
+  --locale zh \
+  --timeout 300000
+```
+
+```bash
+refly workflow generate \
+  --query "Process documents from input folder" \
+  --variables '[{"variableId":"v1","name":"inputFolder","variableType":"string"}]'
+```
+
+## Workflow Spec Schema (v1)
+
+```json
+{
+  "version": 1,
+  "name": "string",
+  "description": "string?",
+  "nodes": [
+    {
+      "id": "string",
+      "type": "string",
+      "input": {},
+      "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)

package/skill/registry.json

@@ -0,0 +1,15 @@
+{
+  "version": 1,
+  "updatedAt": "2025-01-14T00:00:00Z",
+  "skills": [
+    {
+      "name": "pdf-processing",
+      "description": "从 PDF 文件中提取文本和表格、填充表单、合并文档。在处理 PDF 文件或用户提及 PDF、表单或文档提取时使用。",
+      "workflowId": "wf_pdf_processing_v1",
+      "triggers": ["pdf extract", "pdf 提取", "处理 pdf", "fill pdf form"],
+      "path": "domain-skills/pdf-processing/",
+      "createdAt": "2025-01-14T00:00:00Z",
+      "source": "local"
+    }
+  ]
+}