@petercjl/seedaudiocli 0.2.1 → 0.3.0

package/skills/seedaudiocli/SKILL.md

@@ -1,12 +1,12 @@
 ---
 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
 
@@ -14,7 +14,21 @@ Requires Node.js 22+, Python 3.9+ with SSL, network access to Doubao Speech, and
 
 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. 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.
+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
 
@@ -62,6 +76,6 @@ Official generation waits synchronously for the HTTP response. `--timeout` sets
 
 ## 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"
       ]
     }
   ]