用途
本技能面向 Freshworks Platform 3.0 市场应用的开发工作,定位为“高级解决方案架构师与强制执行层”,用于构建、调试、审查和迁移 Freshworks 平台 3.0 应用。它强调只生成 Platform 3.0 模式,对 Platform 2.x 的 API、模式或代码片段采取零容忍、静默拒绝的态度。
主要能力
- 平台版本强制:清单中 platform-version 必须为 "3.0",禁止 2.1/2.2/2.3。
- 清单结构强制:必须使用 modules(如 common、support_ticket),禁止使用 product 结构。
- 请求 API 强制:必须使用 $request.invokeTemplate(),禁止 $request.post()/.get()/.put()/.delete()。
- 请求模板语法强制:使用 <%= context.variable %>、<%= iparam.name %>、<%= access_token %>,禁止 {{variable}}。
- FQDN 强制:host 必须为纯 FQDN,不得包含路径或编码字符;path 必须以 / 开头。
- icon.svg 强制:前端应用必须创建 app/styles/images/icon.svg,否则会导致 fdk validate 失败。
- async/await 强制:async 函数必须包含 await,否则产生 lint 错误。
- OAuth 结构强制:必须包含 integrations 包装,OAuth 凭据放在 oauth_config.json 的 oauth_iparams 中,而非 config/iparams.json。
- 其他强制项:使用 Crayons 组件而非原生 HTML 表单元素;location 必须放在对应产品模块;计划事件用 $schedule.create() 动态创建;辅助函数必须定义在 exports 之后;移除未使用参数或加 _ 前缀。
使用方式
技能内置应用生成工作流:
- 明确需求:识别产品(Freshdesk 或 Freshservice)、放置位置(ticket_sidebar、full_page_app 等)、触发方式(按钮、事件、计划)、集成对象。
- 参考文档:使用本技能获取清单结构、占位符、模块名、模板与校验规则;外部 API 通过 web 搜索确认。
- 设计选择:令牌与 API 密钥保留在服务端(请求模板 + 无服务器),不暴露在前端;多步骤 API 使用多个请求模板加一个 SMI。
- 实现顺序:清单 → 服务端/API → 前端 → 配置(OAuth、requests、iparams)→ 资源(icon、README)。
- 判断是否需要前端:需要查看、配置、交互、监控状态、手动触发、仪表盘等场景必须包含前端(Hybrid 或 Frontend-only);纯自动化、后台同步、Webhook 接收、计划任务、纯通知等场景使用 Serverless。默认规则:存疑时包含前端。
- 选择模板:frontend-skeleton、serverless-skeleton、hybrid-skeleton、oauth-skeleton。
- 自动校验与修复:创建文件后自动运行 fdk validate,仅处理致命错误,最多进行两轮自动修复(JSON 结构、逗号、模板语法、缺失文件、FQDN、路径、清单结构、请求模板声明、函数声明、OAuth 结构、location 放置),每轮后重新运行校验;lint 错误与警告忽略。
适用场景
- Freshworks 平台 3.0 市场应用的构建、调试、审查与迁移。
- Freshdesk、Freshservice 等产品的侧边栏、全页应用、无服务器自动化。
- 需要外部 API 调用、OAuth 集成、请求模板、SMI 的应用。
- 需要判断 Hybrid、Frontend-only、Serverless 架构选型的场景。
限制
- 仅支持 Platform 3.0,不生成 Platform 2.x 模式。
- 若确定性低于 100%,响应为“Insufficient platform certainty.”。
- 自动修复仅处理致命错误,忽略 lint 错误与警告。
- OAuth 仅在第三方服务明确要求时使用,否则默认使用 iparams 中的 API Key。
- 具体模板文件内容、外部 API 细节、收费与价格信息暂未提供。