参照

パックやトラックを読む・更新する・リンクするときは、参照で対象を指定します。パックは共有・再利用される前提のため複数の参照形式を受け取りますが、トラックは進行中の作業を表し曖昧さを避ける必要があるため、狭い形式に限定されています。どの形式を使うかを知っておくと、生の UUID を持ち回らずに済みます。

パックの参照

知っておくとよい点です。

• エイリアス が最も人に優しい形式です。プロンプト、運用手順書、CI スクリプトで使うべき形式です。裸の @alias、または先頭 @ のない alias はまず個人用名前空間で解決され、見つからなければアクティブなワークスペースにフォールバックします。名前空間を明示したい場合は --namespace / namespace を渡します。エイリアス を参照してください。
• 共有 URL はパックをリンク共有したときに生成されます。ワークスペースではワークスペースのサブドメインを使うことがあります(例: https://acme.epismo.ai/share/<token>)。
• ハブ URL は公開なパックを指し、両方のパックの種別に対応します。…/hub/workflows/<id> と …/hub/contexts/<id> です。

パックの読み取り・更新の入口は、reference が記載されている箇所であればこれらの形式のいずれも受け取ります。UUID で動く CLI の例は、エイリアスや URL でも同様に動きます。

reference を使う場所

Epismo で reference と呼ぶのはパックとトラックだけです。

• pack reference は pack ID、alias、共有 URL、ハブ URL です。
• track reference は task/goal UUID、またはその UUID を含む URL です。

CLI と MCP は、共通して持つ pack/track 系の入口で同じ名前を使います。既存のパックやトラックを指すコマンド / ツールでは、外部入力名は reference です。それ以外のレコードは reference ではないため、ID 形の名前を維持します。たとえば suggestion id、logId、workspace-id、project-id、user-ids、agent-ids です。

CLI には workspace、project、agent、credit、token など、MCP ツールとしては公開していない追加コマンドがあります。これらは対象レコードを直接管理するため、意図的に ID ベースです。

名前空間の指定

裸のエイリアスは便利ですが、個人用名前空間とアクティブなワークスペースの両方に同じ名前があると曖昧になります。解決順は個人用が先で、見つからなければワークスペースにフォールバックします。

自動化で必ず片方の名前空間を対象にしたい場合は、API / MCP では namespace: "personal" / namespace: "workspace"、CLI では --namespace personal|workspace を指定してください。@handle/alias 形式は別アカウントの public handle を対象にする読み取り専用の参照です。

トラックの参照

トラックは UUID、またはタスク / ゴールの UUID を含む URL でのみ参照します。トラックのエイリアスはありません。これは意図的な設計です。トラックはステータスと所有者を持ち、進行中の作業への曖昧な参照は不便さ以上に危険だからです。読みやすい handle が欲しくなったら、それはパックにすべきというサインです。

実用上のルール

再利用する知識やワークフロー・パックにはエイリアスを使います。進行中の作業トラックには UUID を使います。人がプロダクトからコピーしたリンクは URL のまま受け取ってよいですが、スクリプトでは可能な限り背後の UUID やエイリアスに正規化してください。