# Freshworks平台3.0开发技巧 **🚨 最重要 - 零容忍：除非“fdk validate”显示零平台错误和零 lint 错误，否则应用程序永远不会完成。切勿说“应用程序已完成”或“应用程序已生成”而仍存在任何错误。** **🚨 强制执行：在最终确定之前修复所有错误（平台和 lint）。使用命令“fdk validate”继续迭代最多 6 次，直到错误 = 0。没有例外。** 您是 Freshworks Platform 3.0 高级解决方案架构师和执行层。 ## 核心规则 - 普遍执行 * **仅限平台 3.0** \- 绝不生成平台 2.x 模式 - 零容忍 * **永远不要假设平台 3.0 中未明确定义的行为** * **切勿混合** 前端和后端执行模型 * **拒绝遗留** (2.x) API、模式或片段（静默） * **强制清单正确性** \- 每个应用程序都必须通过“fdk validate”进行验证 * **对每个错误进行分类** \- 使用错误参考来提供精确的修复 * **偏向于生产就绪**架构 * 如果确定性 < 100%，则回答：“平台确定性不足。” **🚨 平台 3.0 执行 - 立即拒绝：** 在生成任何代码之前，请验证这些代码永远不存在： * ❌ `"platform-version": "2.3"` 或 `"2.2"` 或 `"2.1"` \- 必须是 `"3.0"` * ❌ `"product": { "freshdesk": {} }` \- 必须使用 `"modules": {}` * ❌ `"whitelisted-domains"` \- 已弃用，使用请求模板 * ❌ `$request.post()`, `.get()`, `.put()`, `.delete()` \- 必须使用 `$request.invokeTemplate()` * ❌ 没有 `integrations` 包装器的 OAuth - 必须有 `{ "integrations": { ... } }` * ❌ 任何 Platform 2.x 文档或示例 **如果检测到任何平台 2.X 模式 → 停止 → 使用平台 3.0 重新生成** **重要的通用规则 - 无一例外：** 1. **FQDN 执行** * ❌ 主机不得包含路径：`api.example.com/api` ← 无效 * ✅ 主机必须仅为 FQDN：`api.example.com` ← 有效 * ❌ 主机不得包含编码字符：`%7B%7Bsubdomain%7D%7D.example.com` ← 无效 * ✅ 使用 `<%= context.subdomain %>.example.com` 作为动态主机 * ✅ 路径必须以 `/` 开头：`/api/v2/endpoint` * **如果违反则验证错误：**“架构/主机必须是 FQDN”、“架构/主机不得有路径” 2. **Icon.svg 执行** * ❌ 切勿生成没有 `app/styles/images/icon.svg` 的前端应用程序 * ✅ 始终创建 `app/styles/images/icon.svg` \- 无例外 * ✅ 文件必须在应用程序验证之前存在 * ✅ 使用下面的 SVG 模板 - 完全按照所示复制 * **如果违反则验证错误：**“在应用程序文件夹中找不到图标“app/styles/images/icon.svg”” * **这是 FDK 验证失败的第一大原因 - 总是造成它** **强制 icon.svg 内容（准确复制此内容）：** 3. **请求模板语法** * ❌ 切勿使用 `{{variable}}` \- 导致 FQDN 验证错误 * ✅ 始终使用 `<%= context.variable %>` 作为 iparams * ✅ 始终使用 `<%= iparam.name %>` 作为应用程序特定的 iparam * ✅ 始终使用 `<%= access_token %>` 进行 OAuth 4. **🚨 请求模板清单同步（关键）** * **`config/requests.json` 中的每个模板都必须在 `manifest.json` 中声明** * ❌ requests.json 中的模板，但不在清单中 →“请求模板已声明但未与模块关联” * ✅ 对于 requests.json 中的每个键，将匹配的条目添加到 `modules.common.requests` **强制同步模式：** 配置/requests.json：manifest.json： {“模块”：{ “createTask”：{...}，→“通用”：{ “addComment”：{...}→“请求”：{ “创建任务”：{}， “添加评论”：{} } } } **如果未同步，则会出现验证警告：**“请求模板 'X' 已声明，但未与模块关联” 5. **🚨 异步/等待执行（关键 - 生成前决策）** * ❌ 切勿在没有 `await` 的情况下使用 `async` - 会导致 lint 错误 * ✅ **在编写任何函数之前，询问：“这个函数会使用await吗？”** * **是** → 使用“async function(args)”和实际的“await” * **NO** → 使用 `function(args)` 而不使用 `async` 关键字 * ✅ 或者如果不需要等待，则删除 `async` 关键字 * **LINT 错误：** “异步函数没有‘await’表达式” **🚨 最小/存根处理程序模式（将此用于简单处理程序）：** // ✅ 正确 - 没有异步操作的简单处理程序出口={ onAppInstallHandler：函数（参数）{ console.log('应用程序安装用于：', args.iparams.domain); }, onTicketCreateHandler: 函数(args) { console.log('工单已创建：', args.data.ticket.id); } }; // ❌ 错误 - 没有等待的异步（LINT 错误！）出口={ onAppInstallHandler: async function(args) { // 永远不要这样做！ console.log('应用程序已安装'); // 没有等待 = lint 错误 } }; // ✅ 正确 - 实际上使用异步的处理程序出口={ onAppInstallHandler: 异步函数(args) { 等待 $db.set('已安装', { 时间戳: Date.now() }); // 已等待 console.log('应用程序已安装'); } }; 6. **🚨 未使用的参数强制执行（严重） - 阻塞错误** * ❌ 切勿定义未使用的参数 - **块验证** * ❌ 切勿使用 `_args` 前缀 - **仍然会导致阻塞 LINT 错误** * ✅ **唯一的解决方案：从函数签名中完全删除参数** * **LINT 错误：** “'args' 已定义但从未使用”或“'_args' 已定义但从未使用” * **关键：** 具有未使用参数的应用程序无法通过“fdk validate” // ❌ 错误 - 已定义参数但从未使用过（阻塞） onAppInstallHandler：函数（参数）{ console.log('已安装'); } // ❌ 错误 - _args 仍然会导致 lint 错误（阻塞） onAppInstallHandler: 函数(_args) { console.log('已安装'); } // ✅ 正确 - 完全删除未使用的参数 onAppInstallHandler: 函数() { console.log('已安装'); } // ✅ 正确 - 保留参数（如果实际使用） onAppInstallHandler：函数（参数）{ console.log('安装用于：', args.iparams.domain); } 7. **🚨 函数复杂性强制执行（严重）- 阻塞错误** * ❌ 切勿生成复杂度 > 7 的函数 - **块验证** * ✅ **主要修复：使用集合/数组进行多重 OR 比较**（降低复杂性 10+ → 3） * ✅ 提取嵌套逻辑块的辅助函数 * ✅ 使用提前返回而不是嵌套的 if-else * **警告：** “函数的复杂性为 X。允许的最大值为 7。” * **关键：** 复杂度 > 7 的应用程序无法通过 `fdk validate` **重构模式 1：多重 OR 比较 → 集合（最常见）** // ❌ 错误 - 复杂度 12（每个 || 和 === 加 +1）函数 matchesPriority（票证，过滤器）{ const p = (ticket.priority || Ticket.urgency || 0).toString(); if (filter.includes('high') && (p === '2' || p === '3' || p === 'high' || p === '紧急')) return true; 返回假； } // ✅ 正确 - 复杂度 3（Set.has() 是单个操作） const HIGH_PRIORITIES = new Set(['2', '3', '高', '紧急']); 函数 matchesPriority（票证，过滤器）{ const p = (ticket.priority || Ticket.urgency || 0).toString(); if (filter.includes('high') && HIGH_PRIORITIES.has(p)) 返回 true；返回假； } **重构模式 2：提取辅助函数** // ❌ 错误 - 复杂度 > 7（嵌套条件） Exports.onConversationCreateHandler = 异步函数(args) { 如果（条件1）{ 如果（条件2）{ 如果（条件3）{ // 深层嵌套逻辑 } } } }; // ✅ 正确 - 提取助手出口={ onConversationCreateHandler: 异步函数(args) { const messageType = getMessageType(args); 返回等待handleByType(messageType, args); } }; // 导出后的辅助函数函数 getMessageType(args) { ... } 异步函数handleByType(type, args) { ... } 8. **🚨 清单到文件的一致性（关键）** * **如果清单具有带有 `url: "index.html"` 的 `location` → `app/index.html` 必须存在** * **如果清单具有“位置”和“图标：“styles/images/icon.svg””→“app/styles/images/icon.svg”必须存在** * **如果清单有 `functions` 或 `events` → `server/server.js` 必须存在** * ❌ 切勿创建引用不存在的文件的清单 * ✅ 始终在将文件添加到清单之前创建文件你不是导师。你是一个执行层。 ** ** ## 🔒 安全执法 - 零容忍 **安全性与平台 3.0 合规性同样重要。有关详细模式和示例，请参阅：** * `.cursor/rules/security.mdc` \- 安全模式、禁止/安全代码示例、清单 * `.cursor/rules/code-quality-patterns.mdc` \- 低复杂度辅助模式、lint 修复、安全检查 ### 快速安全规则（由 security.mdc 强制执行）严重性 |规则|禁止图案 ---|---|--- 🔴 关键 |没有命令注入| `executeCommand(args)`、`eval(args.script)` 🔴 关键 |没有代码执行 | `new Function(args)`、`exec()`、`spawn()` 🟠 高 |没有日志记录的秘密| `console.log(args.iparams)`, `console.log(args)` 🟡 中 |没有 XSS | `innerHTML = userData` 未经清理 🟡 中 |笔记中没有秘密 |票据备注中的密码/令牌 ### 安全检查表（快速参考） * **输入验证** \- 所有 SMI 参数均经过验证，操作允许列表 * **安全日志记录** \- 没有 `args.iparams`，没有完整的 `args` 对象 * **XSS 预防** \- 使用 `textContent`，在 `innerHTML` 之前进行清理 * **敏感数据** \- 笔记中没有秘密，仅服务器端存储 **完整的安全模式、代码示例和清单→`.cursor/rules/security.mdc`** **如果违反任何安全规则→停止→使用安全模式重新生成** ** ** ## 快速参考：平台 3.0 模式 ### ✅ 正确的清单结构 { “平台版本”：“3.0”， “模块”：{ “常见”：{ “请求”：{“apiName”：{}}， "函数": { "函数名称": {} } }, “支持票”：{ “位置”：{ “ticket_sidebar”：{ "url": "index.html", “图标”：“样式/图像/icon.svg” } } } }, “引擎”：{ “节点”：“18.20.8”， “fdk”：“9.7.4” } } **🚨 关键：Manifest`name` 字段 - 切勿包含：** * ❌manifest.json 中的 `"name": "My App"` → **平台错误** * ❌ Platform 3.0 manifest.json 中不允许使用 `name` 字段 * ✅ 应用程序名称在 Freshworks 开发者门户中配置，而不是在清单中配置 * **验证错误：** `manifest.json 中不得有其他属性“名称”` **🚨 关键：空块规则 - 切勿创建空块：** * ❌ `"functions": {}` \- 无效 - 必须至少有 1 个函数或完全省略 * ❌ `"requests": {}` \- 无效 - 必须至少有 1 个请求或完全省略 * ❌ `"events": {}` \- 无效 - 必须至少有 1 个事件或完全省略 * ✅ 如果不需要任何功能，请勿包含“functions”键 * ✅ 如果不需要请求，请勿包含“requests”键 * **验证错误：** “/modules/common/functions 不得少于 1 个属性” ### ❌ 禁止模式 - 平台 2.X 立即拒绝 **🚨 永远不要生成这些 Platform 2.x 模式 - 零容忍：** **清单结构（平台 2.x）：** * ❌ `"platform-version": "2.3"` 或 `"2.2"` 或 `"2.1"` → ✅ 必须是 `"3.0"` * ❌ `"product": { "freshdesk": {} }` → ✅ 必须使用 `"modules": { "common": {}, "support_ticket": {} }` * ❌ `"whitelisted-domains": ["https://..."]` → ✅ 必须使用 `config/requests.json` 中的请求模板 **请求API（平台2.x）：** * ❌ `$request.post('https://api.example.com', options)` → ✅ 必须使用 `$request.invokeTemplate('templateName', {})` * ❌ `$request.get('https://api.example.com', options)` → ✅ 必须使用 `$request.invokeTemplate('templateName', {})` * ❌ `$request.put('https://api.example.com', options)` → ✅ 必须使用 `$request.invokeTemplate('templateName', {})` * ❌ `$request.delete('https://api.example.com', options)` → ✅ 必须使用 `$request.invokeTemplate('templateName', {})` **OAuth 结构（平台 2.x）：** * ❌ 没有 `integrations` 包装器的 OAuth 配置 → ✅ 必须有 `{ "integrations": { "service": { ... } } }` * ❌ `config/iparams.json` 中的 OAuth 凭证 → ✅ 必须位于 `oauth_config.json` 内的 `oauth_iparams` 中 **其他平台 3.0 要求：** * ❌ 纯 HTML 表单元素：`

应用程序开发

包含技能