Back to Details

truefoundry-workspaces

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Routing note: For ambiguous user intents, use the shared clarification templates in references/intent-clarification.md.
<objective>
路由说明：若用户意图不明确，请使用references/intent-clarification.md中的通用澄清模板。
<objective>

Workspaces & Clusters

工作区与集群

List TrueFoundry workspaces and clusters. Workspaces are the deploy targets; clusters are the underlying infrastructure.
列出TrueFoundry工作区和集群。工作区是部署目标，集群是底层基础设施。

When to Use

适用场景

List workspaces and clusters, find workspace FQNs for deployment, check cluster connectivity, or discover available GPU types and base domains.
</objective> <instructions>
列出工作区和集群、查找部署所需的工作区FQN、检查集群连接状态，或者查询可用GPU类型和基础域名。
</objective> <instructions>

Execution Priority

执行优先级

For simple read/list operations in this skill, always use MCP tool calls first:
  • tfy_clusters_list
  • tfy_workspaces_list
If tool calls are unavailable because the MCP server is not configured, or a tool is missing, fall back automatically to direct API via 
tfy-api.sh
.
When using direct API, set 
TFY_API_SH
to the full path of this skill's 
scripts/tfy-api.sh
. See 
references/tfy-api-setup.md
for paths per agent.
对于本技能中的简单读取/列出操作，始终优先使用MCP工具调用：
  • tfy_clusters_list
  • tfy_workspaces_list
如果因MCP服务器未配置或缺少工具导致无法调用工具，自动回退到通过
tfy-api.sh
直接调用API。
使用直接API时，请将
TFY_API_SH
设置为本技能
scripts/tfy-api.sh
的完整路径。各Agent对应的路径请参考
references/tfy-api-setup.md
。

Recommended Flow: Cluster → Workspace

推荐流程：集群 → 工作区

Never ask users to set 
TFY_CLUSTER_ID
manually. Instead, list clusters and let the user pick — then filter workspaces by that cluster.
切勿要求用户手动设置
TFY_CLUSTER_ID
。你应该先列出集群供用户选择，再根据选中的集群过滤工作区。

Step 1: List Clusters

步骤1：列出集群

undefined
undefined

Via Tool Call

工具调用方式

tfy_clusters_list()
tfy_clusters_list()

Via Direct API

直接API方式

$TFY_API_SH GET /api/svc/v1/clusters

Present as a table and ask the user to pick one:
Clusters:
NameIDConnected
prod-clusterprod-clusterYes
dev-clusterdev-clusterYes
Which cluster would you like to use?
undefined
$TFY_API_SH GET /api/svc/v1/clusters

以表格形式展示结果并请用户选择：
集群列表：
名称ID已连接
prod-clusterprod-cluster是
dev-clusterdev-cluster是
你希望使用哪个集群？
undefined

Step 2: List Workspaces (Filtered by Cluster)

步骤2：列出工作区（按集群过滤）

Once the user picks a cluster, list workspaces filtered to that cluster:
undefined
用户选择集群后，列出该集群下的所有工作区：
undefined

Via Tool Call

工具调用方式

tfy_workspaces_list(filters={"cluster_id": "selected-cluster-id"})
tfy_workspaces_list(filters={"cluster_id": "selected-cluster-id"})

Via Direct API

直接API方式

$TFY_API_SH GET '/api/svc/v1/workspaces?clusterId=SELECTED_CLUSTER_ID'

Present as a table and ask the user to pick one:
Workspaces in prod-cluster:
NameFQN
dev-wsprod-cluster:dev-ws
staging-wsprod-cluster:staging
Which workspace would you like to use?

**Key field**: `fqn` — this is what `TFY_WORKSPACE_FQN` needs for deploy.
$TFY_API_SH GET '/api/svc/v1/workspaces?clusterId=SELECTED_CLUSTER_ID'

以表格形式展示结果并请用户选择：
prod-cluster下的工作区：
名称FQN
dev-wsprod-cluster:dev-ws
staging-wsprod-cluster:staging
你希望使用哪个工作区？

**关键字段**：`fqn` —— 这是部署时`TFY_WORKSPACE_FQN`需要的参数。

Shortcut: If Only One Cluster

快捷流程：仅存在一个集群时

If the user has access to only one cluster, skip the cluster selection step — go straight to listing workspaces.
如果用户仅有权访问一个集群，跳过集群选择步骤，直接列出工作区即可。

List All Workspaces (Unfiltered)

列出所有工作区（无过滤）

undefined
undefined

Via Tool Call

工具调用方式

tfy_workspaces_list()
tfy_workspaces_list()

Via Direct API

直接API方式

$TFY_API_SH GET /api/svc/v1/workspaces
undefined
$TFY_API_SH GET /api/svc/v1/workspaces
undefined

Get Specific Workspace

获取指定工作区信息

bash
undefined
bash
undefined

Via Tool Call

工具调用方式

tfy_workspaces_list(workspace_id="ws-id-here")
tfy_workspaces_list(workspace_id="ws-id-here")

Via API

API方式

$TFY_API_SH GET /api/svc/v1/workspaces/WORKSPACE_ID
undefined
$TFY_API_SH GET /api/svc/v1/workspaces/WORKSPACE_ID
undefined

Get Cluster Details

获取集群详情

undefined
undefined

Via Tool Call

工具调用方式

tfy_clusters_list(cluster_id="cluster-id") # with status + addons
tfy_clusters_list(cluster_id="cluster-id") # 包含状态 + 附加组件

Via Direct API

直接API方式

$TFY_API_SH GET /api/svc/v1/clusters/CLUSTER_ID $TFY_API_SH GET /api/svc/v1/clusters/CLUSTER_ID/is-connected $TFY_API_SH GET /api/svc/v1/clusters/CLUSTER_ID/get-addons
undefined
$TFY_API_SH GET /api/svc/v1/clusters/CLUSTER_ID $TFY_API_SH GET /api/svc/v1/clusters/CLUSTER_ID/is-connected $TFY_API_SH GET /api/svc/v1/clusters/CLUSTER_ID/get-addons
undefined

Cluster Base Domains (for Public URLs)

集群基础域名（用于公共URL）

When a user wants to expose a service publicly, you need the cluster's base domains to construct a valid hostname. Invalid hosts cause deploy failures. See 
references/cluster-discovery.md
for how to look up base domains, extract cluster ID from workspace FQN, and construct public URLs.
当用户需要公开暴露服务时，你需要获取集群的基础域名来构造合法的主机名。非法主机名会导致部署失败。关于如何查询基础域名、从工作区FQN中提取集群ID以及构造公共URL，请参考
references/cluster-discovery.md
。

Available GPU Types

可用GPU类型

When a user needs GPU resources, discover what's available on the cluster before offering options.
当用户需要GPU资源时，在提供选项前请先查询集群上可用的GPU类型。

How to Discover

查询方式

Option A: Check cluster addons/node pools
bash
$TFY_API_SH GET /api/svc/v1/clusters/CLUSTER_ID/get-addons
Option B: The SDK/API error message tells you
If you deploy with an unsupported GPU type, the error message lists all valid ones:
"None of the nodepools support A10G. Valid devices are [T4, A10_4GB, A10_8GB, A10_12GB, A10_24GB, H100_94GB]"
Not all types are available on every cluster. Always check before presenting options to the user.
For the full GPU type reference table and SDK usage examples, see 
references/gpu-reference.md
.
</instructions>
<success_criteria>
  • The user can see a formatted table of available workspaces with their FQNs
  • The agent has identified the correct workspace FQN for the user's intended deployment target
  • The user can see cluster connectivity status and available infrastructure
  • The agent has discovered and presented available GPU types if the user needs GPU resources
  • The user has the cluster base domain if they need to expose a service publicly
</success_criteria>
<references>
选项A：检查集群附加组件/节点池
bash
$TFY_API_SH GET /api/svc/v1/clusters/CLUSTER_ID/get-addons
选项B：通过SDK/API错误提示获取
如果你使用了不支持的GPU类型部署，错误信息会列出所有合法的类型：
"None of the nodepools support A10G. Valid devices are [T4, A10_4GB, A10_8GB, A10_12GB, A10_24GB, H100_94GB]"
并非所有GPU类型在所有集群都可用，给用户展示选项前请务必先查询。
完整的GPU类型参考表和SDK使用示例请参考
references/gpu-reference.md
。
</instructions>
<success_criteria>
  • 用户可以看到格式化的可用工作区表格，包含对应FQN
  • Agent已识别出用户目标部署对象对应的正确工作区FQN
  • 用户可以看到集群连接状态和可用基础设施信息
  • 若用户需要GPU资源，Agent已查询并展示可用的GPU类型
  • 若用户需要公开暴露服务，用户已获取集群基础域名
</success_criteria>
<references>

Composability

可组合性

  • Need workspace for deploy: Use this skill first, then 
    deploy
    skill with the 
    fqn
  • Need cluster for filtering: Pass 
    cluster_id
    to workspaces or applications
  • Check infra status: Get cluster + addons for monitoring
</references> <troubleshooting>
  • 部署需要工作区信息：先使用本技能，再将获取的
    fqn
    传给
    deploy
    技能
  • 需要按集群过滤：将
    cluster_id
    传给工作区或应用查询接口
  • 检查基础设施状态：获取集群+附加组件信息用于监控
</references> <troubleshooting>

Error Handling

错误处理

No Workspaces Found

未找到工作区

No workspaces found. Check:
- The selected cluster may not have any workspaces
- Your API key may not have access to this cluster
- Try listing clusters first to pick a different one
未找到工作区，请检查：
- 选中的集群可能没有任何工作区
- 你的API密钥可能没有该集群的访问权限
- 尝试先列出集群，选择其他集群重试

Permission Denied

权限被拒绝

Cannot list workspaces. Your API key may lack workspace permissions.
</troubleshooting>
无法列出工作区，你的API密钥可能缺少工作区访问权限。
</troubleshooting>