@petercjl/seedaudiocli 0.2.0 → 0.3.0

package/skills/seedaudiocli/SKILL.md

@@ -1,33 +1,50 @@
 ---
 name: seedaudiocli
-description: Generate audio through official Volcengine Seed Audio using the seedaudiocli CLI; import configuration files, submit explicit audio requests, recover tasks, and download results.
+description: Generate audio through official Volcengine Seed Audio using seedaudiocli; manage named voice presets and samples, import configuration, recover tasks, and download results.
 ---
 
 # Seed Audio CLI
 
 This companion Skill documents the capability contract of `@petercjl/seedaudiocli`.
-Inputs are an explicit audio prompt, selected reference mode, output settings and a destination. Outputs are task IDs, status and downloaded audio paths. The calling application owns content strategy and audio acceptance; this Skill owns correct invocation and recovery.
+Inputs are narration or an explicit audio prompt, an optional named voice, reference mode, output settings and a destination. Outputs are immutable voice revisions or generation task IDs, status and downloaded audio paths. The calling application owns content strategy, voice selection and audio acceptance; this Skill owns library integrity, correct invocation and recovery.
 
 ## Runtime and discovery
 
 Requires Node.js 22+, Python 3.9+ with SSL, network access to Doubao Speech, and an authorized API key. Run `seedaudiocli version`, `seedaudiocli capabilities --json` and `seedaudiocli doctor --json`. Resolve the canonical Skill with `seedaudiocli skill source --json`; the returned `source` directory belongs to the installed npm package.
 
-Use the current host's terminal execution capability. Its mapping is declared in [capabilities.json](capabilities.json) and the selected adapter: [Codex](adapters/codex.json) or [SealSeek](adapters/sealseek.json). Adapter mappings are implemented; host integration evidence is separate from CLI tests.
+When continuing an existing conversation or after a package update, load the current canonical `SKILL.md` and read the selected leaf command's `--help` (for example, `seedaudiocli generate text --help`). Build the invocation from that live contract; earlier conversation commands may belong to a different version.
+
+Use the current host's terminal execution capability through [capabilities.json](capabilities.json). The [generic adapter](adapters/generic.json) covers any host with that capability; named adapters describe host conventions and evidence, not an eligibility list. A managed Skill includes its own package runtime at `runtime/npm/cli.mjs`; invoke that entry with Node.js when executing from a physical managed installation. Source inspection and library-only operations require no service authentication.
+
+## Named voice library
+
+For a request to list, inspect, save, import, export or preview a voice, enter this local branch before authentication, then return to generation step 3 only if the user also requested generation.
+
+- Discover installed choices with `seedaudiocli voice list --json`. `--all` includes historical revisions. A name is user-facing; its stable ASCII ID is used for precise selection.
+- `voice show NAME` returns settings and sample integrity; `voice preview NAME` returns `preview_path` for the Agent's native audio player. Preview plays the existing reference, not a new paid generation.
+- Save an authorized reference with `voice save --id example-male --name "示例男声" --audio-file SAMPLE --style "清晰自然，中等语速" --description "适合课程解说"`. Optional model, format, sample-rate, speech-rate, pitch-rate and loudness-rate flags are validated. Save copies the original sample into the private library; another save to that ID creates a new immutable revision. Preserve the original confirmed sample instead of chaining generated narration as future references.
+- Local references are PCM WAV, MP3 or Ogg/Opus, at most 30 seconds and 10 MiB. PCM WAV validation uses Python; compressed-sample save/import requires FFmpeg's `ffprobe`. Install the dependency in the host's managed environment when needed, then retry the same local operation. Generation from a validated stored sample does not require ffprobe.
+- `voice export NAME --output NEW_FILE.voice.json` creates a self-contained sample/settings bundle, refusing an existing destination. `voice import FILE.voice.json` validates schema, checksum and actual duration, then creates a local revision. Export is a local write, not permission to upload or publicly distribute someone's voice.
+- Generation uses `generate audio-ref --voice "VOICE_NAME" --prompt-file NARRATION_FILE ...`. A name/ID selects its latest revision; `NAME@1` pins a revision. Supply plain narration text: the CLI adds the reference-addressing wrapper and saved delivery style. Explicit output flags override preset settings for this request only; saved revisions remain unchanged. Inspect the resolved payload and `voice` receipt during dry-run. Limits apply to the final expanded prompt.
+- A named voice and explicit audio/image references conflict. Respect the selected mode and resolve conflicts with the caller. `VOICE_NOT_FOUND`, `VOICE_NAME_CONFLICT`, `VOICE_AMBIGUOUS`, `VOICE_INVALID`, `VOICE_INTEGRITY_FAILED`, `VOICE_BUSY` and `VOICE_PROBE_REQUIRED` are local terminal errors: preserve files, resolve the cause, then return to this branch. Never substitute another voice silently.
+
+Library storage is `SEEDAUDIO_VOICE_DIR` or the configuration directory's `voices` subdirectory. Samples and credentials are outside the npm package. Every generated job records preset ID/name/version, original sample SHA256, style and effective settings. Voice consistency is generative, not an exact acoustic guarantee.
 
 ## Main flow
 
 1. Check `seedaudiocli auth status`. This checks local configuration only and does not prove the key is accepted remotely.
 2. If configuration is missing, ask the user for the local path to the administrator-provided JSON or env configuration file. Import with `seedaudiocli config import "FILE"`. Pass the file path to the CLI without displaying or reading its secret contents into the conversation. If configuration already exists, preserve it; an explicitly requested replacement uses `--replace`, which creates a backup. After import, return to step 1. Interactive terminal users can run `seedaudiocli setup`.
 3. Preserve the caller's prompt, model, reference mode and output choices. Choose `generate text`, `generate audio-ref`, or `generate image-ref` according to those inputs. Prompts support 1–3000 characters. Audio mode accepts up to three preset speaker IDs, public URLs or local recordings (each at most 30 seconds and 10 MiB). Image mode accepts one JPEG/PNG/WebP URL or local image (at most 10 MiB). Use `--audio-file` / `--image-file` for local files; the CLI sends their bytes directly. Audio and image references are mutually exclusive.
-4. Validate the intended request with `--dry-run`. Validation must succeed before paid submission. Configuration import and dry-run do not submit generation jobs.
+4. Construct the complete generation command, including references, output settings, timeout, destination and output name. Validate that exact command by adding `--dry-run`; after success, remove only `--dry-run` for the authorized submission. If any argument changes, repeat this preflight. Configuration import and dry-run do not submit generation jobs.
 5. Execute the authorized request with `--download "OUTPUT_DIRECTORY"` when local delivery is required. The official call is synchronous; `--wait` remains a compatibility flag. Save the local task ID emitted before submission. The CLI saves the official response and audio in private local state. Generation can incur service charges.
 6. Inspect status and actual output paths. A completed task without an audio file is incomplete delivery. Report the task ID, file and material limitations; content quality remains the caller's acceptance responsibility.
 
 ## Invocation examples
 
 ```bash
-seedaudiocli generate text --prompt "Generate five seconds of instrumental piano." --dry-run
-seedaudiocli generate text --prompt "Generate five seconds of instrumental piano." --wait --download ./audio
+seedaudiocli generate text --help
+seedaudiocli generate text --prompt "Generate five seconds of instrumental piano." --timeout 300 --download ./audio --output-name piano --dry-run
+seedaudiocli generate text --prompt "Generate five seconds of instrumental piano." --timeout 300 --download ./audio --output-name piano
 seedaudiocli generate audio-ref --audio-reference zh_female_vv_uranus_bigtts --prompt "@音频1 今天的咖啡刚刚好。" --wait --download ./audio
 seedaudiocli generate image-ref --image-url "https://example.com/reference.jpg" --prompt "Generate audio matching the supplied reference." --dry-run
 seedaudiocli task get TASK_ID
@@ -39,8 +56,11 @@ Use `@音频1` through `@音频3` to address references in order; `--audio-refer
 
 The only provider endpoint is `https://openspeech.bytedance.com/api/v3/tts/create`, with model `seed-audio-1.0` and `X-Api-Key` authentication. Use a Doubao Speech API key authorized for Seed Audio. Ark credentials belong to another service. The official schema is documented at https://docs.volcengine.com/docs/DoubaoVoice/audio-generation-http?lang=zh.
 
+Official generation waits synchronously for the HTTP response. `--timeout` sets the request timeout in seconds; `--wait` is an optional compatibility flag. `--interval` is unsupported because there is no remote polling loop. When migrating an old invocation, omit `--interval` and its value while preserving the caller's supported choices; it is not a substitute for `--timeout`.
+
 ## Error and recovery branches
 
+- Argument parsing error (`unrecognized arguments`, exit 2): read the selected command's current help, correct the invocation and return to step 4. A confirmed local parser rejection happens before audio submission, so it does not require `--force`. This branch applies only to a parser error; timeout, connection loss or a returned task ID require the recovery branches below. Inspect the CLI exit status and stderr directly; a following shell command can mask its exit status.
 - `CONFIG_REQUIRED`: request the file path, import, then return to authentication check.
 - `CONFIG_INVALID` or `CONFIG_READ_FAILED`: request a corrected file/path. Preserve the saved configuration.
 - `CONFIG_EXISTS`: explain that configuration already exists; replace only when the user requests it.
@@ -56,6 +76,6 @@ The only provider endpoint is `https://openspeech.bytedance.com/api/v3/tts/creat
 
 ## Installation and update
 
-`seedaudiocli skill install --agent codex` installs a managed copy. For SealSeek supply the actual discovery directory with `--root SKILLS_DIRECTORY` or `SEALSEEK_SKILLS_DIR`; installation refuses to guess the host's layout. Existing unmanaged Skills are preserved. `skill status` reports ownership and freshness; `skill update` backs up managed files and preserves customized UI metadata. Edited managed content requires reconciliation.
+Follow package-root INSTALL.md and UPDATE.md. Resolve the current Agent's absolute Skill parent directory and native discovery mechanism, then pass `--agent NAME --root ABSOLUTE_SKILL_PARENT` to managed install/status/update. Every valid Agent name is accepted through a named or generic adapter. Managed installation creates physical copies of the Skill and required package runtime. Existing unmanaged files and local edits are preserved; updates back up managed files and preserve customized UI metadata. Verify global CLI, target-owned runtime, version and SHA256 status, then verify native host discovery independently.
 
-Global npm installations check stable `latest` before every invocation and install a newer version before executing the command once. Managed Skills are synchronized with backups. Offline checks retain the installed version. `seedaudiocli update check` inspects availability; `update install` performs an explicit update. Set `SEEDAUDIO_AUTO_UPDATE=0` for a deliberately pinned run. Development checkouts remain Git-managed. Within taobao-ai-ops use `taobao-ai-ops component run seedaudiocli ...`; the suite owns component updates. Configuration and task history remain in user directories. Record recurring contract failures for a separately authorized package update.
+Global npm generation calls check stable `latest` with a daily notification cache. Explicit `update install --agent NAME --root ABSOLUTE_SKILL_PARENT` updates one selected host and reconciles its Skill even at the same version. Metadata, help, local library commands, task recovery and dry-run make no automatic update request. Set `SEEDAUDIO_AUTO_UPDATE=0` to disable detection. Offline checks retain the installed version. Development checkouts remain Git-managed; suite-owned installations use their parent's update entry. Configuration, voice samples and task history remain in user directories. Record recurring contract failures for a separately authorized package update.

package/skills/seedaudiocli/adapters/generic.json

@@ -0,0 +1,23 @@
+{
+  "schema": "portable-skill-adapter",
+  "schema_version": "1.0.0",
+  "platform": "generic",
+  "mappings": [
+    {
+      "capability_id": "command.execute",
+      "status": "implemented",
+      "features": [
+        "argv",
+        "exit-code",
+        "stdout",
+        "local-files"
+      ],
+      "implementation": {
+        "kind": "cli",
+        "command": "seedaudiocli",
+        "discovery": "Use the current Agent's terminal capability; resolve PATH or its target-owned runtime/npm/cli.mjs with Node.js. Read version and capabilities before invocation.",
+        "result": "Parse JSON stdout and exit code; preserve task_id, voice receipt, preview_path and downloaded_to."
+      }
+    }
+  ]
+}

package/skills/seedaudiocli/capabilities.json

@@ -2,9 +2,9 @@
   "schema": "portable-skill-capabilities",
   "schema_version": "1.0.0",
   "target_platforms": [
-    "codex",
-    "sealseek"
+    "generic"
   ],
+  "host_resolution": {"fallback_adapter": "generic", "agent_eligibility": "capability-based"},
   "capabilities": [
     {
       "id": "command.execute",
@@ -39,7 +39,10 @@
         "SUBMISSION_UNKNOWN",
         "REQUEST_BUSY",
         "OUTPUT_CONTRACT_FAILED",
-        "OUTPUT_EXISTS"
+        "OUTPUT_EXISTS",
+        "VOICE_NOT_FOUND",
+        "VOICE_INTEGRITY_FAILED",
+        "VOICE_REFERENCE_CONFLICT"
       ]
     }
   ]