用途
Workfront Actions 用于编写或修复 Workfront App Builder 扩展的服务端代码，即 React SPA 调用以完成浏览器无法完成的工作的 Adobe I/O Runtime action。Actions 是后端——Adobe 按需在其云端运行的小型函数（“无服务器”，即 Adobe I/O Runtime，构建于 OpenWhisk 之上）。前端（SPA，参见 workfront-ui-extension）通过 actionWebInvoke 调用它们；它们持有凭据并调用外部 API。浏览器绝不能直接调用 Workfront/Adobe API——这是 action 的职责，因此登录令牌永远不会到达用户浏览器。
对于通用 action 模式与模板（webhook 接收器、数据库 CRUD、自定义事件提供者、journaling 消费者、大负载重定向、action 序列、Asset Compute worker）以及 App Builder SDK（State/Files/Events/DB），请使用 appbuilder-action-scaffolder。本技能是 Workfront 特有层：{data,error} 契约、IMS 透传以及 Workfront 自身的公共 API。
主要能力与结构
Action 的组织方式：
actions/<name>/index.js # exports main(params)
仅支持 CommonJS——将函数导出为 exports.main（App Builder 仅支持 CommonJS，不支持 ES Modules）。
在 app.config.yaml 中注册每个 action，或在扩展的 ext.config.yaml 中注册（后者会编译进 app.config.yaml），遵循 OpenWhisk wskdeploy YAML 规范。
async function main (params) { // ... return { statusCode: 200, body: { data, error: null } } } exports.main = main
响应结构：始终在 body 中返回 { data, error }；UI 在使用 data 前先检查 error。
return { statusCode: 400, body: { data: null, error: 'missing parameter(s) ...' } }
认证与输入
require-adobe-auth 是逐 action 的选择，默认关闭（平台默认值）——应审慎决定，不要一概启用。设为 true 时，Adobe 会在代码运行前于网关验证用户的 IMS 令牌。
- 当 action 本身即安全边界时（特权操作，或下游没有任何授权调用方的机制）应开启。
- 当下游 API 强制实施自身授权时应保持关闭——例如 action 只是将用户的 imsToken 转发给 Workfront/Planning，由后者拒绝坏令牌——或除非明确要求启用。
UI 将 imsToken（→ Authorization: Bearer …）和 Workfront 实例 URL 作为 params 传入；切勿硬编码。
IMS org id 位于共享上下文的 auth.imsOrgID（注意大写 ID——不是 imsOrgId/imsOrg；这个大小写陷阱会耗费数小时）。前端读取 sharedContext.get('auth').imsOrgID 并向下传递；action 使用 params.imsOrgId / x-gw-ims-org-id 请求头。两个陷阱：(1) 拒绝字符串 "undefined"/"null"/空——前端空值会变成请求头字符串 "undefined"（→ 401 "Org Id undefined is not in the list of user org Ids"）；(2) 当 require-adobe-auth: true 时，网关在你的代码运行前验证 org 请求头。
输入流转：.env → action inputs（配置中）→ params。不要在运行时读取 process.env。在 aio app dev 下 action 以进程内方式运行，因此 process.env 在本地可能看似可用，但部署后会为空。将键/密钥作为 inputs 接入并从 params 读取。
调用外部 API 的模式
对于任何 API——Workfront、Planning、Adobe 服务：
- 以 params 接收 imsToken 以及任何 apiKey / ID。
- 用 Authorization: Bearer <imsToken> fetch 公共 REST 端点（在需要处添加 x-api-key / x-gw-ims-org-id）。
- 将结果映射为 { data, error }。切勿记录令牌。
Workfront Planning → 验证 Workfront MCP 已连接，然后从它获取 v2 端点参考和数据（细节见 references/integrations.md）；若未连接，停止并告知用户先连接 Workfront MCP 再继续。其他 Adobe 服务 → references/integrations.md。从实时来源确认端点，而非猜测。
Workfront 公共 API v21.0
Workfront 自身的 REST API——/attask/api/v21.0 层。从 action 调用它（绝不从 SPA 调用）。
- wfClient / 基础 URL：{workFrontInstanceUrl}/attask/api/v21.0{path}——单一版本常量。workFrontInstanceUrl 和 imsToken 作为 params 到达（绝不硬编码）。
- 通过文档化的查询参数搜索/统计对象（项目、任务、问题）；将响应映射为 { data, error }。
- 自定义 DE 字段在搜索/统计时需要 {field}_Mod=notblank，否则会从结果中被静默省略。
- 用 PUT /{obj}?updates=[...] 进行批量更新（updates 数组在查询字符串中）——分块请求以保持在约 8 KB URL 长度限制内；当某块仍然过长时，回退到逐记录 PUT /{obj}/{ID}。
- 将调用包装在一个小的 wfFetch 辅助函数中；在 app.config.yaml 中注册 action；SPA 仅通过 actionWebInvoke 访问它。
时间预算
SPA 通过 actionWebInvoke 调用的 action 是 web action，因此受 Adobe I/O Runtime 对 web/阻塞型 action 的 60 秒上限约束——提高 limits.timeout 并不能解除它（完整限制表见 appbuilder-action-scaffolder）。因此不要在一次调用中获取或处理大数据集：将 Workfront 搜索分页，并将批量 PUT 工作分块到多次 actionWebInvoke 调用中（参见上文 Workfront 公共 API v21.0），并在 UI 中显示部分进度。面向用户的超时可能是 action-timeout 的候选，但同样可能是缓慢的 CDN/静态加载、冷启动或下游 API——在得出结论前先检查 aio app logs。
添加新 action
- aio app add action（或手工创建 actions/<name>/index.js）。
- 在 app.config.yaml / ext.config.yaml 中注册它，带有 runtime kind（例如 runtime: nodejs:20）及其 inputs；按上文“认证与输入”规则设置 require-adobe-auth。runtime 是必需的——缺失时部署会失败并报 Invalid or missing property "runtime"（并且当 require-adobe-auth 开启时，生成包装的 _secured<action> 上也会触发同样错误）。
- 将其 URL 暴露给 SPA（UI 读取注入的 action URL——绝不硬编码）。参见 workfront-ui-extension。
- 在 test/actions/ 下添加测试；运行 aio app test。用 aio app logs 查看日志（命令目录：appbuilder-workfront → references/commands.md）。
- 用 aio app deploy 部署。可编辑的起点位于 assets/action-boilerplate.js。
适用场景与限制
适用场景：为 Workfront App Builder 扩展编写或修复服务端 action 代码，处理 IMS 令牌透传、{data,error} 契约与 Workfront 公共 API 调用。限制：本文档未提供收费、价格等商业信息；除上述技术与输入输出约定外，其他功能细节暂未提供。