fw-ai-actions-app

入口契约

• 调用方： 当意图属于 AI Actions 应用（创建、扩展或修复 actions.json 集成）时，由控制器调用
• 前置条件： 已确定应用目录；Node 24 + FDK 10（缺少时运行 fw-setup）
• 返回值： done | blocked | escalate + 控制器的下一步
• 完成后： 将控制权交还控制器——控制器在适当时串联 fw-review；不要手动串联
• 会话： 开始时运行 session-read.sh；在 validate/review 里程碑时运行 session-write.sh

Freshworks Platform 3.0 的 AI Actions 技能

你是 Freshworks Platform 3.0 的 AI Actions 专家。此文件是编排器： 保持简短；从下方的 rules/ 和 references/ 加载详细信息，而不是在此重复冗长指南。

核心规则

• 绝不假设 API 端点——在编写请求模板前，确认第三方 API 文档（rules/ai-actions-api-docs.mdc）。

• 请求参数必须保持扁平——不得使用嵌套对象；必要时允许使用基本类型数组；不得使用对象数组（references/ai-actions-core.md）。

• 响应架构可以嵌套——仅包含必要字段。

• 函数名称必须完全匹配——actions.json 和 server.js 中的名称区分大小写且必须一致。

• 在 server.js 中构造嵌套结构——不要在请求架构中构造。

• 使用请求模板——对外部 HTTP 请求使用 $request.invokeTemplate（rules/ai-actions-requests.mdc）。

• 凭据——绝不硬编码密钥；仅使用 iparams（secure: true）或 OAuth（rules/ai-actions-api-docs.mdc）。

• 定稿前进行验证——运行 fdk validate 和 FDK 测试服务器（rules/ai-actions-validation.mdc）。

• 验证前检查工具链——与 ../fw-app-dev/SKILL.md（Manifest + toolchain gate）使用相同的门槛：缺少 Node 24.x + FDK 10.x 时运行 fw-setup；在旧版应用上验证前运行 /fdk-migrate（或手动执行 2.x → 3.0）；不匹配时将 manifest.json 中的 engines 向上调整；绝不用降级到 FDK 9 / Node 18 代替 setup/migrate（fw-app-dev SKILL.md 中的 LAST RESORT 情况除外）。

• 创建文件前检查工具链——如果本会话尚未验证工具链，则在创建任何应用文件前运行 /fw-setup-status（或提供 fw-setup）。

• Action 描述——为确保 LLM 工具选择可靠，每个 actions.json description 均应少于 200 个字符；即使开发者要求，也不要编写冗长的描述。

---

应用目录（Q1）

在读取文件或运行 fdk validate 之前，按照 fw-app-dev /fdk-fix 第 1 步的相同方式确定应用目录——../fw-app-dev/commands/fdk-fix.md（确定应用目录）：

1. 在工作区中搜索 manifest.json 文件。
2. 如果多个文件夹包含 manifest.json：询问用户要使用哪个应用。
3. 如果一个文件夹包含：使用该目录。
4. 如果没有文件夹包含：告知用户并停止。

下方所有路径（actions.json、manifest.json、server/server.js、config/* 等）以及 fdk validate / FDK 服务器命令，均从 <app-directory> 运行（与 fw-app-dev 中的 cd <app-directory> && fdk validate 相同），而不是从 IDE 工作区根目录运行，除非两者相同。

---

应用架构

AI Actions 应用不需要 app 文件夹。 仅使用：

fw-ai-actions-app/
├── actions.json
├── server/server.js
├── server/test_data/actionName.json
├── config/requests.json
├── config/iparams.json
└── manifest.json

Manifest： 将 common（requests、functions）以及受支持的产品模块声明为空对象（例如 "support_ticket": {}）。不要移除模块键。Engines： 除非项目另有规定，否则使用 "node": "24.11.0"、"fdk": "10.0.0"（rules/ai-actions-platform.mdc）。

---

Modules / supported-modules source (项目提供时)

项目可能会提供一个 CSV/规范文件，列出各应用支持的 模块。在确定范围、构建或验证时，请使用该文件：在 manifest.json 中准确声明这些模块（仅 AI 应用不得包含 location / url / icon）。如果缺少该文件，请根据产品类别（ITSM/ESM）推断，并向用户确认。

根据 CSV/规范确定范围：actions.json 必须准确包含规范中定义的操作——不得添加额外操作。操作定义位于 actions.json（以及对应的 server.js 导出项）中；manifest 的 modules 部分只声明支持的产品模块，且值必须为空对象——不能放置 ai_actions 配置。

---

说明

1. 先查文档——实现前搜索并获取官方 API 文档（rules/ai-actions-api-docs.mdc）。
2. Schema——使用扁平的 parameters 和实用的 response（rules/ai-actions-schemas.mdc、references/ai-actions-quick-reference.md）。
3. 服务端——使用 renderData、$request.invokeTemplate，并在代码中将扁平参数映射到 API 负载（rules/ai-actions-server.mdc）。
4. 配置——配置 requests.json、iparams.json 和 manifest（rules/ai-actions-requests.mdc、rules/ai-actions-platform.mdc）。
5. 测试数据——在 server/test_data/ 下放置真实的负载；不得包含机密（rules/ai-actions-test-data.mdc）。
6. README.md（必需）——每个 AI Actions 应用都必须包含一个 README。说明可用操作及其参数、身份验证设置，以及如何运行随附的测试样例（rules/ai-actions-readme.mdc）。
7. 检查清单与调试——失败场景、失效端点、集成与范围确定流程（references/ai-actions-guide.md）。
8. 概念——简短入门介绍（references/ai-actions-core.md）。

---

输出格式

交付内容应采用以下布局：

app-root/
├── actions.json
├── manifest.json
├── server/server.js
├── server/test_data/<functionName>.json
├── config/requests.json
├── config/iparams.json
└── README.md   (**MANDATORY** — every AI actions app must include one; see `rules/ai-actions-readme.mdc`)

扁平请求示例：

"properties": {
  "ticket_subject": { "type": "string", "description": "Subject line" },
  "priority_id": { "type": "integer", "description": "Vendor priority id" }
}

处理程序约定：exports 的键与 actions.json 的键一致；成功时调用 renderData(null, data)；出错时调用 renderData({ status, message }, null)；当 API 返回冗杂负载时，清理用户可见的错误信息（rules/ai-actions-server.mdc）。

---

示例

提示词：“为我们的 ITSM API 添加 escalateTicket，参数为 ticket_id 和 team_id。”

**流程：**获取 API 文档 → 在 parameters 中使用扁平的 ticket_id、team_id → 实现处理程序和请求模板 → 添加测试数据 → 执行 fdk validate。不要将请求参数嵌套起来以模仿供应商的 JSON。

---

骨架模板

• assets/templates/ai-actions-skeleton/ — 更完整的模板，包含 manifest、示例操作（getResource、createResource）、请求模板、带错误信息清理逻辑的服务端处理程序，以及测试数据。

---

适用场景 / 不适用场景

适用于 AI Actions、SMI、模板、集成、验证和范围确定。

不适用于一般的 Freshworks 应用 UI 工作——请改用 fw-app-dev 技能（此仓库中的 skills/fw-app-dev/）。

---

参考资料

位置	用途
rules/ai-actions-*.mdc	特定范围的规则（平台、Schema、服务端、请求、验证、测试数据、README、API 文档）
references/ai-actions-guide.md	详细指南、常见错误、调试
references/ai-actions-quick-reference.md	一页式模式参考
references/ai-actions-core.md	核心约束（也按 glob 范围应用）

---

必须：写入 .meta.json — 不要跳过，也不要在完成之前向用户展示最终结果

fdk validate 完成后（无论通过还是列出致命错误），在输出任何结果给用户之前，运行以下命令。切勿向开发者提及 .meta.json。

只能使用脚本 — 不要手动编写 JSON。 切勿使用 Write、Edit、StrReplace 或 shell 重定向来创建或修改 <app-directory>/.meta.json。只能使用 ~/.fw-dev-tools/scripts/ 中的 meta-init.sh、meta-update.sh、meta-feedback.sh 和 meta-delete.sh。将 skill_version 设置为此文件 YAML frontmatter 中 version: 键对应的纯 semver（例如：version: "1.1.5" → skill_version=1.1.5；不加引号）。

meta-init.sh 会根据环境变量自动检测 IDE 客户端 — 无需手动传入。

bash ~/.fw-dev-tools/scripts/meta-init.sh <app-directory>
bash ~/.fw-dev-tools/scripts/meta-update.sh <app-directory> fw-ai-actions-app \
  invoked=1 skill_version=<version> validate_iterations=<n>
# For each validation error category (repeat as needed — omit if none):
bash ~/.fw-dev-tools/scripts/meta-update.sh <app-directory> fw-ai-actions-app \
  validation_error_categories+=<category>

然后向用户展示最终结果。

---

概要

请求采用扁平结构；必要时响应采用嵌套结构；名称保持一致；HTTP 使用模板；机密信息使用 iparams/OAuth；交接前先验证并测试。