变量注入速查手册（v2）¶

受众： 模板编排人员（运营、产品） 目的： 在 AdminPortal InitFlow 编排器中编写初始化流程时，快速查找平台注入的可用变量 契约版本： v2（TFRM-245「机器人模板系统强化」）。权威单一信源 internal/shared/initflow/context_schema.go，发现接口 GET /api/v1/admin/digital-employee-templates/init-variables（返回 factNamespaces/credentialTypes/scopes）。 v1 扁平变量（{{ServiceURL}}/{{AdminSecret}}/{{AdminKey}}/{{RobotID}}/{{Password}}/{{Namespace}}）已于 TFRM-249 硬切退役——存量模板经 cmd/migrate-init-flow-v2 迁移。

变量分三族，按「可暴露性」划分：事实 {{Robot.*}}（非密身份/位置）、Feature {{Feature.*}}（用户业务参数）、 凭证 {{Credentials.*}}（密，须先在模板顶层 credentials[] 声明）。

1. 事实变量 `{{Robot.*}}`（平台自动注入，非密）¶

在 path、headers、body、condition 中通过 {{Robot.X}} 引用，无需声明。

变量	说明	示例值
`{{Robot.Id}}`	机器人唯一标识（cluster+namespace 内唯一）	`friday`
`{{Robot.AccountId}}`	机器人自身 Account ID（AccessToken sub/aud 命名空间；回填过渡期可能为空）	`4242`
`{{Robot.Namespace}}`	K8s 租户命名空间（Istio 路由 Header `X-TF-Namespace`）	`tenant-a`
`{{Robot.ServiceUrl}}`	机器人服务地址（自动拼接到 `request.path` 前，无需硬编码）	`http://cr.ns.svc.cluster.local:8080`
`{{Robot.Type}}`	机器人类型	`tfrserver` / `tfropenclaw`
`{{Robot.Org}}`	所属组织 ID	`7`

{{Robot.ServiceUrl}} 由系统根据实例所在 K8s namespace / CR 名称自动计算（见 §4）。

2. Feature 变量 `{{Feature.*}}`（用户业务参数，非密）¶

Feature 是模板定义的：每个模板通过 JsonSchema 定义需要用户填写的配置字段，用户部署时填写，平台展平注入。

{{Feature}}              ← 完整 JSON 字符串（很少直接用）
{{Feature.字段名}}        ← 顶层字段
{{Feature.父字段.子字段}}  ← 嵌套字段（按点路径）

模板 Feature 配置为：

{
  "feishuToken": "t-xxx",
  "webhook": {"url": "https://example.com/hook", "secret": "s-yyy"},
  "maxRetry": 3
}

则可用变量：{{Feature.feishuToken}} / {{Feature.webhook.url}} / {{Feature.webhook.secret}} / {{Feature.maxRetry}}。

3. 凭证变量 `{{Credentials.*}}`（密，须先声明）¶

凭证是密值，与事实/Feature 分开治理：只能在 InitFlow 中用，禁止出现在 CR Spec（密钥永不进 CR/etcd）。使用两步：① 在模板顶层 credentials[] 声明需要哪些凭证；② 步骤中用 {{Credentials.<name>}} 引用。 首次引用才铸造，声明未引用不铸。

3.1 声明（模板顶层 `credentials[]`）¶

{
  "version": "2.0",
  "name": "标准机器人初始化",
  "credentials": [
    {"name": "mgmt", "type": "robot_jwt", "scopes": ["robot:admin"]}
  ],
  "steps": [ ... ]
}

字段	说明
`name`	引用名，`{{Credentials.<name>}}`；run 内唯一、须字母起头、禁点
`type`	凭证类型（见 3.2）
`scopes`	仅 `robot_jwt`：签进短 JWT 的最小权限（⊆ 有效 scope 词表，见 `/api/v1/oauth/scopes`）；其余类型须省略
`ttl`	仅 `robot_jwt`：形如 `"30m"`；省略=用部署级默认；其余类型须省略

3.2 凭证类型¶

type	适用机器人	引用方式	说明
`robot_jwt`	tfrserver	`{{Credentials.<name>}}`	Manager 现签短 RS256 JWT（sub/aud=`robot:<id>`，scope 按声明最小权限求交）——管理 API 认证首选（取代旧 `{{AdminSecret}}`）
`gateway_token`	tfropenclaw	`{{Credentials.<name>}}`	LLM Key 托管网关 Token（数据面调用）
`machine_client`	tfrserver	`{{Credentials.<name>.clientId}}` / `{{Credentials.<name>.clientSecret}}`	机器身份 client_id/client_secret（OAuth client_credentials 换发）
`a2a_jwt`	—	—	预留，暂不铸造

3.3 认证请求示例（tfrserver 管理 API）¶

{
  "version": "2.0",
  "name": "示例",
  "credentials": [
    {"name": "mgmt", "type": "robot_jwt", "scopes": ["robot:admin"]}
  ],
  "steps": [
    {
      "type": "http",
      "name": "调用管理 API",
      "request": {
        "method": "POST",
        "path": "/v1/factory/drafts/release",
        "headers": {"admin_key": "{{Credentials.mgmt}}"}
      },
      "assert": [{"source": "status", "op": "eq", "value": 200}]
    }
  ]
}

认证 Header 键名 admin_key（原 {{AdminKey}} 常量，现直接写字面量）。Header 具体形态（admin_key vs Authorization: Bearer）随机器人管理面在 INT（TFRS-265）收敛，以届时约定为准。

4. `{{Robot.ServiceUrl}}` 解析规则¶

系统根据实例部署位置自动计算（见 internal/user/service/digital_employee_service/init_executor_v2.go getServiceURL）：

场景	格式
TFRServer（有集群域名）	`https://{Cluster.Domain}`（Istio + BFF 路由）
TFRServer（无集群域名）	`http://{CRName}.{Namespace}.svc.cluster.local:8080`
TFROpenClaw	`http://tfopenclaw-{RobotID}.{Namespace}.svc.cluster.local:18789`
Mock（本地测试）	`http://localhost:9999`（或 `ECHO_SERVER_PORT`）

5. 步骤提取的变量¶

HTTP 步骤 extract 从响应提取，后续步骤直接引用：

{
  "type": "http", "name": "登录",
  "request": {"method": "POST", "path": "/api/login"},
  "extract": [
    {"var": "token", "from": "body", "path": "$.data.accessToken"},
    {"var": "reqId", "from": "header", "headerName": "X-Request-Id"}
  ]
}

后续引用："headers": {"Authorization": "Bearer {{token}}"}。

6. 变量优先级¶

步骤提取变量（extract / script，local 层）  ← 最高
  ↓
平台注入变量（{{Robot.*}} / {{Feature.*}} / {{Credentials.*}}，environment 层）  ← 最低

7. 循环变量¶

forEach¶

变量	说明	默认名	可自定义
`{{_item}}`	当前迭代元素	`_item`	`itemVar` 字段
`{{_index}}`	当前迭代索引（从 0 开始）	`_index`	`indexVar` 字段

对象元素自动展平：{{item.name}}、{{item.type}}。

loop¶

变量	说明
`{{_iteration}}`	当前轮次索引（从 0 开始）

8. 常用 InitFlow 片段¶

条件配置¶

{
  "type": "if",
  "condition": {"left": "{{Feature.enableFeishu}}", "op": "eq", "right": "true"},
  "steps": [
    {"type": "http", "name": "配置飞书", "request": {"method": "POST", "path": "/api/feishu"}}
  ]
}

轮询等待就绪¶

{
  "type": "loop",
  "maxIterations": 10,
  "delay": 3000,
  "breakWhen": {"source": "body", "path": "$.status", "op": "eq", "value": "ready"},
  "steps": [
    {"type": "http", "name": "轮询状态", "request": {"method": "GET", "path": "/api/health"}}
  ]
}