@petercjl/seedaudiocli 0.2.1 → 0.3.0

package/INSTALL.md

@@ -0,0 +1,11 @@
+# Installation
+
+Send to the current Agent:
+
+> Install @petercjl/seedaudiocli and its companion Skill for your own environment.
+
+The Agent resolves its own absolute Skill parent directory and registration mechanism. Discover the canonical Skill with `seedaudiocli skill source --json`, then use `skill install --agent NAME --root ABSOLUTE_SKILL_PARENT`. The parent receives a `seedaudiocli` directory. An arbitrary valid Agent name uses the generic adapter. No host directory is inferred.
+
+Verify `version --json`, `skill status --root ABSOLUTE_SKILL_PARENT --json` and the target-owned `runtime/npm/cli.mjs` entry. Installation creates physical copies of the Skill and required package runtime; it creates no shared links. Node.js and Python remain declared external prerequisites. The Agent loads or refreshes its native Skill discovery and verifies it separately; registration pending is incomplete installation. Existing unmanaged or locally edited files are preserved.
+
+An npm installation notice points here. With lifecycle scripts disabled, follow the same handoff explicitly. npm success alone does not complete Skill installation. Credentials, voice libraries and generated task records stay outside the package.

package/README.md

@@ -4,6 +4,12 @@ Official Volcengine Seed Audio CLI with a portable companion Skill. Requires Nod
 
 ## Install and configure
 
+Send to your current Agent:
+
+> Install @petercjl/seedaudiocli and its companion Skill for your own environment.
+
+Follow [INSTALL.md](INSTALL.md) for complete installation and [UPDATE.md](UPDATE.md) for updates. npm success alone does not verify Skill discovery. The command examples below are developer reference.
+
 ```bash
 npm install -g @petercjl/seedaudiocli
 seedaudiocli setup
@@ -45,25 +51,52 @@ Outputs support mp3, wav, pcm and ogg_opus. Select compatible sample rates with
 
 Protocol reference: [Volcengine Seed Audio HTTP documentation](https://docs.volcengine.com/docs/DoubaoVoice/audio-generation-http?lang=zh).
 
+## Named voice library
+
+Save a confirmed reference sample, delivery style and audio settings under a memorable name. The library belongs to the user and survives package upgrades; the public package contains no personal samples. Re-saving an ID creates a new immutable revision, preserving previous settings and samples.
+
+Natural-language requests to your current Agent:
+
+> Save the attached voice sample as a named voice, using the name and delivery style I provide.
+
+> List my seedaudiocli voice library and play the sample for the voice I choose.
+
+> Use my chosen seedaudiocli voice to narrate the attached text.
+
+Developer reference:
+
+```bash
+seedaudiocli voice save --id example-male --name "示例男声" --audio-file ./reference.wav --style "清晰自然，中等语速"
+seedaudiocli voice list
+seedaudiocli voice show "示例男声"
+seedaudiocli voice preview "示例男声"
+seedaudiocli generate audio-ref --voice "示例男声@1" --prompt-file ./narration.txt --subtitle --download ./audio --dry-run
+seedaudiocli voice export "示例男声" --output ./example.voice.json
+seedaudiocli voice import ./example.voice.json
+```
+
+`--voice` accepts a name or stable ID, with an optional `@VERSION`. A bare name selects the latest local revision. Pass plain narration; the CLI adds the reference and saved style. Explicit generation flags override saved settings for this request only. Dry-run shows the resolved payload and voice receipt; generation records exact voice revision, sample SHA256 and effective settings. The final expanded prompt must fit the provider limit. A named voice cannot be combined with separate audio/image references. Generative voices can have small variations between runs.
+
+`preview` returns the original sample path for the Agent's audio player; no new generation is submitted. Samples must be up to 30 seconds and 10 MiB. PCM WAV uses built-in validation; saving/importing MP3 or Ogg/Opus requires FFmpeg's `ffprobe`. The library is under the configuration directory's `voices` folder, or `SEEDAUDIO_VOICE_DIR`. Export creates a self-contained JSON sample/settings bundle and refuses existing output. Sharing or publishing a voice bundle requires appropriate authorization from its owner.
+
 ## Agent installation
 
 ```bash
 seedaudiocli skill source --json
-seedaudiocli skill install --agent codex
-seedaudiocli skill status --agent codex --json
-seedaudiocli skill install --agent sealseek --root "/actual/skills-directory"
+seedaudiocli skill install --agent current-agent --root "/actual/skills-directory"
+seedaudiocli skill status --agent current-agent --root "/actual/skills-directory" --json
 ```
 
-SealSeek's discovery directory is explicit (`--root` or `SEALSEEK_SKILLS_DIR`). Unknown Agents and unmanaged targets are refused. Managed copies have ownership/hash records; updates back up prior contents, preserve customized UI metadata and refuse local edits. In-place synchronization supports directory handles held open by an Agent. Failed synchronization reports the recovery backup.
+The calling Agent supplies its own absolute Skill parent directory. Any valid Agent name uses the generic capability adapter when no dedicated mapping applies. Unmanaged targets are refused. Managed physical copies include the required package runtime, ownership/hash records and preserved UI metadata. In-place synchronization supports directory handles held open by an Agent. Failed synchronization reports the recovery backup. External Node.js/Python prerequisites and native host discovery are verified separately.
 
 ## Update and rollback
 
 ```bash
 npm install -g @petercjl/seedaudiocli@latest
-seedaudiocli skill update --agent codex
+seedaudiocli skill update --agent current-agent --root "/actual/skills-directory"
 ```
 
-Global installs check and install stable latest before every run and synchronize previously registered managed Skills. Use `update check` to inspect availability and `update install` to apply it immediately. For a deliberate rollback, set `SEEDAUDIO_AUTO_UPDATE=0`, install the prior exact npm version and synchronize Skills. Configuration and history remain unchanged.
+Global generation calls check stable latest with a daily notification cache. Use `update check` to inspect availability and `update install --agent current-agent --root "/actual/skills-directory"` to update one selected target. For a deliberate rollback, set `SEEDAUDIO_AUTO_UPDATE=0`, install the prior exact npm version and synchronize the selected Skill. Configuration, voice library and history remain unchanged.
 
 Python discovery checks an explicit `SEEDAUDIO_PYTHON`, configured Agent runtime directories and platform commands. `SEEDAUDIO_RUNTIME_ROOT` can point to a managed runtime root. A missing or broken runtime produces `PYTHON_REQUIRED` with installation guidance.
 
@@ -73,4 +106,4 @@ Run `npm test` for isolated CLI, configuration and lifecycle tests, and `npm pac
 
 ## Automatic updates
 
-Global npm installs check stable latest before every command, install newer releases and sync managed Skills before running the requested command once. No TTL cache is used. Offline checks keep the installed version; updates back up the package for rollback. Configuration and task history remain outside the package. Use `seedaudiocli update check` or `seedaudiocli update install`. For a deliberately pinned run set `SEEDAUDIO_AUTO_UPDATE=0`. Development checkouts are Git-managed; taobao-ai-ops owns suite component updates.
+Detection runs only before ordinary generation, at most daily, with a bounded timeout. Metadata, local voice management, task recovery and dry-run remain read-only with respect to update detection. Updates notify by default; installation explicitly resolves a single Skill target. Offline checks keep the installed version. Package/Skill backups support rollback; configuration and voice samples remain outside npm. `SEEDAUDIO_AUTO_UPDATE=0` disables detection. Development checkouts are Git-managed; suite installations use their parent's updater.

package/UPDATE.md

@@ -0,0 +1,11 @@
+# Updates
+
+Send to the current Agent:
+
+> Update @petercjl/seedaudiocli and its companion Skill in your own environment, preserving my voice library.
+
+Resolve one current Agent Skill parent directory before mutation. Inspect `skill status --agent NAME --root ABSOLUTE_SKILL_PARENT --json`. Stop for unmanaged files or local edits. Explicit `update install --agent NAME --root ABSOLUTE_SKILL_PARENT` backs up the package and selected Skill, verifies the replacement, and synchronizes that target only. Same-version updates reconcile a missing or stale Skill. Source checkouts and suite-owned components retain their owning updater.
+
+Verify global CLI, target-owned runtime, package version, managed SHA256 status and native host discovery. Failed synchronization is incomplete; retain backups and reconcile it before retrying. The package updater attempts rollback on failure. Inspect actual versions after an interrupted update, reuse the acquired version where possible, and preserve the original backup. Historical `skill update --root PARENT` remains supported and safely selects the generic adapter. Historical updates that swept several registered targets are deprecated; use an explicit selected target.
+
+Generation checks for stable updates at most once daily and notifies; installation is explicit. Metadata, help, task recovery and dry-run remain free of registry update calls. `SEEDAUDIO_AUTO_UPDATE=0` disables detection. Voice library, credentials and cached results live outside npm and are preserved. Re-load or refresh the current Agent's Skill discovery after an update; host verification is distinct from package receipts.

package/capabilities.json

@@ -6,31 +6,6 @@
     "python": ">=3.9",
     "python_override": "SEEDAUDIO_PYTHON"
   },
-  "commands": [
-    "version",
-    "capabilities",
-    "doctor",
-    "setup",
-    "config import",
-    "auth status",
-    "models list",
-    "generate text",
-    "generate audio-ref",
-    "generate image-ref",
-    "task get",
-    "task wait",
-    "task url",
-    "task download",
-    "task jobs",
-    "payload validate",
-    "payload submit",
-    "skill source",
-    "skill status",
-    "skill install",
-    "skill update",
-    "update check",
-    "update install"
-  ],
   "config": {
     "format": [
       "json",
@@ -55,15 +30,15 @@
     "migration": "Import official configuration with --replace; backup is automatic; relay endpoints/models are rejected."
   },
   "update": {
-    "trigger": "before-every-run",
+    "trigger": "generate with daily cache",
     "channel": "latest",
-    "automatic_install": true,
+    "automatic_install": false,
     "configuration": "Outside package; preserved",
     "offline": "keep-current",
     "source_checkout": "git-managed",
     "suite_install": "suite-managed",
     "opt_out": "SEEDAUDIO_AUTO_UPDATE=0",
-    "managed_skills": "synchronized with backups; edited content preserved"
+    "managed_skills": "one explicitly selected target, physical copy with isolated runtime"
   },
   "generation": {
     "provider": "Volcengine",
@@ -76,5 +51,477 @@
     "local_references": true,
     "remote_polling": false,
     "recovery": "Persist local record before POST; save response and audio; export locally by record ID. Unknown outcomes require inspection and explicit authorization before --force."
+  },
+  "commandNames": [
+    "version",
+    "capabilities",
+    "doctor",
+    "setup",
+    "config import",
+    "auth status",
+    "models list",
+    "generate text",
+    "generate audio-ref",
+    "generate image-ref",
+    "task get",
+    "task wait",
+    "task url",
+    "task download",
+    "task jobs",
+    "payload validate",
+    "payload submit",
+    "skill source",
+    "skill status",
+    "skill install",
+    "skill update",
+    "update check",
+    "update install"
+  ],
+  "skills": [
+    "seedaudiocli"
+  ],
+  "commandContracts": {
+    "version": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "none"
+    },
+    "capabilities": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "none"
+    },
+    "doctor": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "read"
+    },
+    "skill source": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--name": {
+          "type": "string"
+        },
+        "--all": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "none"
+    },
+    "skill status": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--agent": {
+          "type": "string"
+        },
+        "--root": {
+          "type": "string"
+        }
+      },
+      "sideEffects": "read"
+    },
+    "skill install": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--agent": {
+          "type": "string"
+        },
+        "--root": {
+          "type": "string"
+        }
+      },
+      "sideEffects": "local-write"
+    },
+    "skill update": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--agent": {
+          "type": "string"
+        },
+        "--root": {
+          "type": "string"
+        }
+      },
+      "sideEffects": "local-write"
+    },
+    "update check": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "read"
+    },
+    "update install": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--agent": {
+          "type": "string"
+        },
+        "--root": {
+          "type": "string"
+        }
+      },
+      "sideEffects": "package-and-skill-update"
+    },
+    "voice list": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--all": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "read"
+    },
+    "voice show": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "read"
+    },
+    "voice preview": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "read"
+    },
+    "voice save": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--id": {
+          "type": "string"
+        },
+        "--name": {
+          "type": "string"
+        },
+        "--audio-file": {
+          "type": "string"
+        },
+        "--description": {
+          "type": "string"
+        },
+        "--style": {
+          "type": "string"
+        },
+        "--model": {
+          "type": "string"
+        },
+        "--format": {
+          "type": "string"
+        },
+        "--sample-rate": {
+          "type": "integer"
+        },
+        "--speech-rate": {
+          "type": "integer"
+        },
+        "--pitch-rate": {
+          "type": "integer"
+        },
+        "--loudness-rate": {
+          "type": "integer"
+        }
+      },
+      "sideEffects": "local-write"
+    },
+    "voice export": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--output": {
+          "type": "string"
+        }
+      },
+      "sideEffects": "local-write"
+    },
+    "voice import": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "local-write"
+    },
+    "generate text": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--voice": {
+          "type": "string"
+        },
+        "--prompt": {
+          "type": "string"
+        },
+        "--prompt-file": {
+          "type": "string"
+        },
+        "--dry-run": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "local-write"
+    },
+    "generate audio-ref": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--voice": {
+          "type": "string"
+        },
+        "--audio-file": {
+          "type": "string"
+        },
+        "--audio-reference": {
+          "type": "string"
+        },
+        "--prompt": {
+          "type": "string"
+        },
+        "--prompt-file": {
+          "type": "string"
+        },
+        "--dry-run": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "local-write"
+    },
+    "generate image-ref": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--image-file": {
+          "type": "string"
+        },
+        "--image-url": {
+          "type": "string"
+        },
+        "--prompt": {
+          "type": "string"
+        },
+        "--dry-run": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "local-write"
+    }
+  },
+  "discoveryContract": {
+    "schemaVersion": 1,
+    "entryPoints": [
+      {
+        "argv": [
+          "capabilities",
+          "--json"
+        ],
+        "result": "manifest"
+      },
+      {
+        "argv": [
+          "skill",
+          "source",
+          "--json"
+        ],
+        "result": "source"
+      }
+    ],
+    "commandsField": "commandContracts",
+    "version": {
+      "command": "version",
+      "argv": [
+        "version",
+        "--json"
+      ],
+      "fields": {
+        "package": {
+          "field": "package",
+          "type": "string"
+        },
+        "version": {
+          "field": "version",
+          "type": "string"
+        }
+      }
+    },
+    "skillCollection": {
+      "namesField": "skills",
+      "default": "seedaudiocli",
+      "selector": {
+        "option": "--name",
+        "type": "string"
+      },
+      "enumeration": {
+        "argv": [
+          "skill",
+          "source",
+          "--all",
+          "--json"
+        ],
+        "itemsField": "skills",
+        "completeField": "complete"
+      },
+      "namedSource": [
+        "skill",
+        "source",
+        "--name",
+        "{skill}",
+        "--json"
+      ]
+    }
+  },
+  "maintenanceContract": {
+    "schemaVersion": 1,
+    "agentEligibility": "valid-name-with-generic-fallback",
+    "hostDiscoveryAuthority": "host",
+    "targetOptions": {
+      "--root": {
+        "kind": "skill-parent"
+      }
+    },
+    "source": {
+      "name": {
+        "field": "name",
+        "type": "string"
+      },
+      "package": {
+        "field": "package",
+        "type": "string"
+      },
+      "version": {
+        "field": "version",
+        "type": "string"
+      },
+      "path": {
+        "field": "source",
+        "type": "string"
+      }
+    },
+    "status": {
+      "name": {
+        "field": "name",
+        "type": "string"
+      },
+      "package": {
+        "field": "package",
+        "type": "string"
+      },
+      "version": {
+        "field": "version",
+        "type": "string"
+      },
+      "target": {
+        "field": "target",
+        "type": "string"
+      },
+      "installed": {
+        "field": "installed",
+        "type": "boolean"
+      },
+      "managed": {
+        "field": "managed",
+        "type": "boolean"
+      },
+      "current": {
+        "field": "current",
+        "type": "boolean"
+      },
+      "edited": {
+        "field": "edited",
+        "type": "boolean"
+      },
+      "verification": {
+        "field": "verification",
+        "type": "object"
+      },
+      "recovery": {
+        "field": "recovery",
+        "type": "object"
+      }
+    }
+  },
+  "installationLifecycle": {
+    "agentNeutral": true,
+    "targetRequired": true,
+    "hostRegistrationRequired": true,
+    "installationMode": "copy",
+    "sharedLinksAllowed": false,
+    "isolatedRuntimeRequired": true,
+    "skillRequired": true,
+    "updateRequiresSkillSync": true,
+    "required_components": [
+      "cli",
+      "skill"
+    ],
+    "installGuide": "INSTALL.md",
+    "updateGuide": "UPDATE.md",
+    "install": "skill install with resolved --root",
+    "update": "update install with resolved --root",
+    "verification": "version, managed SHA256 status, target-owned runtime and host discovery",
+    "installerIntegration": "npm postinstall notice and scripts-disabled INSTALL.md"
+  },
+  "automaticUpdates": {
+    "enabledByDefault": true,
+    "intervalHours": 24,
+    "timeoutMs": 4000,
+    "trigger": "generate without dry-run",
+    "defaultMode": "notify",
+    "configuration": "SEEDAUDIO_STATE_DIR/update-check.json; notification only",
+    "recovery": "Keep installed version offline; preserve malformed cache for inspection",
+    "disable": "SEEDAUDIO_AUTO_UPDATE=0"
+  },
+  "voiceLibrary": {
+    "schemaVersion": 1,
+    "commands": [
+      "voice list",
+      "voice save",
+      "voice show",
+      "voice preview",
+      "voice export",
+      "voice import"
+    ],
+    "selector": "--voice ID_OR_NAME[@VERSION]",
+    "storage": "SEEDAUDIO_VOICE_DIR or configuration directory / voices",
+    "versioning": "immutable increasing integer revisions",
+    "precedence": [
+      "explicit generation flags",
+      "voice preset",
+      "service defaults"
+    ],
+    "referenceConflict": "VOICE_REFERENCE_CONFLICT",
+    "preview": "return original local sample path, no paid call",
+    "sharedSamples": false,
+    "receipt": "voice.id/name/version/reference_sha256/style/effective_settings",
+    "compressedReferenceProbe": "ffprobe (FFmpeg), only for MP3/Ogg import or save"
   }
 }