参照
パックやトラックを指し示すための参照形式です。
パックやトラックを読む・更新する・リンクするときは、参照で対象を指定します。パックは共有・再利用される前提のため複数の参照形式を受け取りますが、トラックは進行中の作業を表し曖昧さを避ける必要があるため、狭い形式に限定されています。どの形式を使うかを知っておくと、生の UUID を持ち回らずに済みます。
パックの参照
| 形式 | 例 | こんなときに使う |
|---|---|---|
| UUID | 8f3c… |
既に正確な ID がある(例: 直前の API レスポンスから) |
| エイリアス | @team-onboarding |
安定した読みやすい名前を使いたい(個人用優先→ワークスペース) |
| 所有者エイリアス | @hiroki/team-onboarding |
別の handle が所有するエイリアスを読む |
| 共有 URL | https://epismo.ai/share/<token> |
非公開のパックをリンクで共有された |
| ハブ URL | https://epismo.ai/hub/workflows/<id> |
hub から公開なパックを取得する |
知っておくとよい点です。
- エイリアス が最も人に優しい形式です。プロンプト、運用手順書、CI スクリプトで使うべき形式です。先頭
@のない@aliasはまず個人用名前空間で解決され、見つからなければアクティブなワークスペースにフォールバックします。名前空間を明示したい場合は--namespace/namespaceを渡します。エイリアス を参照してください。 - 共有 URL はパックをリンク共有したときに生成されます。ワークスペースではワークスペースのサブドメインを使うことがあります(例:
https://acme.epismo.ai/share/<token>)。 - ハブ URL は公開なパックを指し、両方のパックの種別に対応します。
…/hub/workflows/<id>と…/hub/contexts/<id>です。
パックの読み取り・更新の入口は、reference が記載されている箇所であればこれらの形式のいずれも受け取ります。UUID で動く CLI の例は、エイリアスや URL でも同様に動きます。
トラックの参照
トラックは UUID、またはタスク / ゴールの UUID を含む URL でのみ参照します。トラックのエイリアスはありません。これは意図的な設計です。トラックはステータスと所有者を持ち、進行中の作業への曖昧な参照は不便さ以上に危険だからです。読みやすい handle が欲しくなったら、それはパックにすべきというサインです。