workos

WorkOS Skill Router

从这里开始：无需账号即可设置 AuthKit

当用户想在尚无 WorkOS 凭据的项目中添加 WorkOS 或 AuthKit 登录时，先运行安装程序：

WORKOS_MODE=agent npx workos@latest install

这不需要 WorkOS 账号、API 密钥或访问控制面板。

如果你是 WorkOS 安装程序自己的 Agent（它已经写入凭据），项目已有 WorkOS 凭据，或者用户要求的不是全新设置，请跳过本节，转到使用方法。

功能说明。 本文介绍的是撰写时的最新版本 workos CLI 0.23.0。CLI 的输出优先于此列表。

• 如果找不到凭据（shell 或项目的 env 文件中没有 WORKOS_API_KEY，且没有启用的 workos CLI 配置文件），它会创建一个新的、尚未认领的 WorkOS 环境，在 https://workos.com/auth.md 中称为一次性环境。如果找到凭据，则会使用这些凭据，不会创建任何内容。
• 当项目包含 package.json 时，它会将 WORKOS_API_KEY、WORKOS_CLIENT_ID 和 WORKOS_CLAIM_TOKEN 写入 .env.local；否则写入 .env，并将该文件添加到 .gitignore。JavaScript 项目还会生成 WORKOS_COOKIE_PASSWORD 和框架的重定向 URI 变量。后端语言项目的其他变量由安装程序的 Agent 提供。
• 它会将环境及其认领令牌保存为此机器上启用的 workos CLI 配置文件。认领令牌只存在于该配置文件和 env 文件中。在环境认领前，不要删除其中任何一项。
• 它会接入 AuthKit SDK，并向环境注册回调 URL（如果无法注册，安装就会失败），然后报告它已保存或留给你设置的其他应用程序 URL（Sign-out URI、Initiate login URI、CORS origin）。除非传入 --no-validate，否则它会运行安装后验证。
• 它只会设置 AuthKit 登录。安装程序不会创建组织或 SSO 连接，且 auth.md 没有说明一次性环境包含测试身份提供方。不要承诺可以直接使用现成的 SSO 登录。如果用户想试用 SSO，接下来请阅读 references/workos-sso.md。
• Git：在 Agent 模式下，0.23.0 默认会新建分支并提交更改。如果用户希望更改保留在当前分支且不提交，请传入 --no-branch --no-commit。尚未发布的 CLI 版本会停止提交，且其中的 --no-commit 会被接受为无操作。如果遇到 git_dirty 错误而停止，请让用户提交或暂存更改，或者先取得用户同意，再使用 --no-git-check 重新运行。

完成后。 安装成功报告并不能证明登录可用。请阅读框架参考文档和 references/workos-authkit-setup.md（下文规则 4），并验证登录、登出和外部发起的登录。随后检查安装是否创建了新环境：项目的 env 文件中新增了 WORKOS_CLAIM_TOKEN，且 WORKOS_MODE=agent npx workos@latest profile list --json 显示启用的配置文件的 "type": "unclaimed"。只有在这种情况下，才告知用户该环境尚未认领，以及如何认领。如果安装复用了现有凭据，用户可能已经拥有该环境，因此不要提供认领说明。

稍后认领环境。 用户可以继续使用尚未认领的环境。如需将其关联到自己的 WorkOS 账号，请在同一台机器上、并将该未认领环境设为启用的配置文件后运行：

npx workos@latest profile claim

（env claim 和 claim 是别名。）它会打印认领 URL（https://dashboard.workos.com/claim?nonce=...）。在人类模式下，它会尝试打开浏览器，并等待最多 5 分钟。在 Agent 模式下，它会以 JSON 格式返回 URL，因此请将该 URL 提供给用户。用户登录或创建免费账户，然后确认。认领操作是永久性的，无法撤销。之后，workos auth login 会将 CLI 连接到他们的账户，这是 authkit 和 config 命令所必需的。auth.md 将这些环境称为临时环境，但未说明有效期，因此不要承诺未认领的环境能持续多久。

如果命令失败：

• 退出代码 4 / auth_required：未配置环境（例如，遭遇速率限制、网络错误、密钥环处于沙盒环境中，或项目中已有 WORKOS_API_KEY），且 Agent 模式无法打开浏览器登录。请用户在自己的终端中运行 npx workos@latest install。不要自行写入密钥。
• 优先使用结构化错误中的 error.recovery.hints，以及 CLI 打印的调试日志路径。
• “AuthKit already installed”：未经用户同意，不要传入 --force。请遵循规则 4，使用现有集成。
• 未知标志或命令：缓存的 CLI 可能较旧。请参阅 references/workos-cli-upgrade.md。
• 没有 Node.js：https://workos.com/auth.md 说明了原始 HTTP 配置和认领步骤，包括如何持久保存认领令牌。

现有 WorkOS 账户或生产环境。 API 密钥仅用于这些情况。如果用户已有 WorkOS 账户，请先让他们在自己的终端中运行 npx workos@latest auth login，因为这会打开浏览器。如果当前没有激活的 CLI 配置文件，登录会将其账户的 Staging 环境保存为活动 CLI 配置文件（使用 npx workos@latest profile list 检查），之后，同一安装命令会使用该环境，而不是配置新环境。或者，在 WorkOS 控制面板中设置来自其环境的 WORKOS_API_KEY 和 WORKOS_CLIENT_ID（参见 https://workos.com/docs/authkit/cli-installer）。生产部署需要 WorkOS 账户中生产环境的凭据。切勿发布未认领环境的密钥。

使用方法

此文件会指向参考文档；答案在参考文档中。作答前：

1. 根据规则 0 和下方的决策树，将请求匹配到参考文件。
2. 使用 Read 工具读取匹配的参考文件，然后再提供任何答案、URL 或代码。
3. 遵循参考文件中的说明（其中会告知你应使用 WebFetch 获取哪些实时文档，以及应避免哪些陷阱）。

例外：Widget 请求使用 Skill 工具调用 workos-widgets skill——它有自己的多框架编排流程。

防护规则（适用于每个回复）

无论触发哪条路由规则，这些规则都适用。之所以制定这些规则，是因为过去 WorkOS Agent 交互中最常见的失败模式，是编造看似合理的 CLI 命令和控制面板路径。

• **在工作区管理任务中使用 CLI 前，先检查是否已连接 WorkOS MCP 服务。**如果会话已连接 WorkOS MCP 工具（提供 whoami、list_operations、query 和 mutate 的服务——工具名称可能带有特定客户端的前缀），请优先使用这些工具读取和更改工作区资源：它们已以当前登录的 Dashboard 用户身份运行，无需安装 CLI，也无需 API 密钥。CLI 仍适用于引导、填充数据、本地项目配置和诊断。完整的决策指南见 references/workos-management.md 中的“选择操作界面”部分。
• **在依赖损坏的 WorkOS MCP 连接前，先修复连接——但绝不要把设置 MCP 视为使用 CLI 的前提。**当用户要求设置 WorkOS MCP 服务，或用户预期会有 MCP 工具但发现工具缺失、未通过身份验证或在启动期间中断时，请先阅读 references/workos-mcp.md：确认 MCP 客户端和用户要求的配置范围；未经明确授权，不要修改用户级全局 Agent 配置。依赖浏览器、凭据存储或主机证书的身份验证必须在用户常用的主机 shell 中完成。如果未配置 MCP 服务且用户没有提出相关要求，不要把请求引向 MCP 设置——references/workos-management.md 中的 CLI 路径完全能够满足需求。
• **绝不要编造 workos CLI 命令。**使用 WORKOS_MODE=agent workos --help --json 验证命令。宣称某项操作不受支持前，还要检查 WORKOS_MODE=agent workos api ls --json，确认能否通过 workos api 使用 REST 端点。不要因为存在 list/get/delete 子命令，就假设也存在 create 子命令；也不要假设 GraphQL 操作就是 REST 端点。请参阅 references/workos-management.md。
• **每项 AuthKit 集成都必须配置并验证应用 URL。**进行设置和迁移时，请同时阅读 references/workos-authkit-setup.md 以及对应的框架或语言参考。该文档涵盖重定向目标（不一定是服务器回调处理程序）、Sign-out URI 和 Initiate login URI。构建成功并不能证明这些设置或流程有效。
• **在编码 Agent 会话中调用 workos CLI 时，优先使用 WORKOS_MODE=agent。**CLI 会自动检测大多数 Agent 环境（CLAUDECODE、CLAUDE_CODE、CURSOR_AGENT、CODEX_SANDBOX、非 TTY），但显式设置环境变量在不同沙盒配置中更可靠。请参阅下文的 编码 Agent 会话中的 WorkOS CLI 部分。
• **绝不要编造 Dashboard 点击路径。**除非你已通过刚刚获取的文档页面核实，否则不要使用“Dashboard > Organizations > X > Roles > Map Groups”或 dashboard.workos.com/some/specific/path 之类的表述。Dashboard UI 会调整布局；文档页面则较为稳定。请引用文档 URL，并概述目标位置（如“Authorization 页面”或“目录的设置”），而不是给出具体点击路径。
• **针对账户 UI，推荐使用实际的 Widgets。**WorkOS 通过 @workos-inc/widgets 提供预构建的个人资料、安全、会话和组织 UI；不要声称这些都必须从头构建。对于 Clerk UserButton 的需求，应使用相关 Widgets 加上针对应用定制的菜单／导航框架，而不是将其视为可直接替换的组件，也不要编造 WorkOS 的 UserButton 导出项。请加载 workos-widgets 了解设置；迁移请求还需阅读 references/workos-migrate-clerk.md。身份验证和会话仍由 AuthKit 管理。
• **当用户想执行 CLI 不支持的操作时，请直言说明。**相比编造一个会失败的命令，直接告知用户“CLI 不支持此操作；这是相关文档 URL”更有帮助。请参阅 references/workos-management.md 中的“CLI 不支持的操作”部分。
• **编写操作指南时，优先提供文档 URL，而不是文字描述。**如果参考文件要求引用特定文档 URL，请原样引用；不要改写 URL 路径。

编码 Agent 会话中的 WorkOS CLI

CLI 会解析两个独立维度：交互模式（human/agent/ci）和输出模式（human/json）。CLI 会通过已知环境变量（CLAUDECODE、CLAUDE_CODE、CURSOR_AGENT、CODEX_SANDBOX、CURSOR_TRACE_ID）和非 TTY 检测来自动识别 Agent 环境，但在不同沙盒配置中，显式设置更可靠。

任何设置或调试任务的建议预检步骤：

WORKOS_MODE=agent workos doctor --json --skip-ai

--skip-ai 会禁用医生工具基于 AI 的诊断流程，该流程需要 API 密钥并进行网络往返，而沙盒不一定能保证这两项条件。如果 --skip-ai 报错提示未知标志，说明 CLI 版本过旧，请参阅 references/workos-cli-upgrade.md。结构化 JSON 输出足以用于程序化排查。

此命令会返回结构化 JSON 报告，其中包含 interactionMode（{ mode, source }）和 hostExecution（{ ok, failures[] }）字段。提出修复建议前，请先阅读 JSON。

规则：

• 解析命令输出时使用 --json。它只控制输出格式，不会改变 CLI 行为。
• 即使要转述人类可读的消息，也要使用 WORKOS_MODE=agent。它控制提示、浏览器启动和主机信任。
• 将医生工具的 HOST_EXECUTION_UNTRUSTED 问题视为严格的信任边界。如果医生工具报告中包含此问题（或 hostExecution.ok 为 false），当前 shell 可能处于沙盒中。此 shell 中的身份验证、配置、密钥链和 API 故障都不能作为权威依据。在下结论前，请用户在其主机 shell 中重新运行主机敏感命令（workos auth login、workos doctor、workos env add）。
• 不要假设基于浏览器的身份验证（workos auth login）能在沙盒中正常工作。如果需要身份验证，请提供 CLI 打印的手动 URL/代码备用方案，或请用户在其主机 shell 中运行 workos auth login。
• 对于具有破坏性或会改变权限的 CLI 命令，在传入确认标志前，先获得用户批准。Agent 模式不会提示确认，因此省略必需标志会导致 confirmation_required 错误。已知标志：--yes 用于会修改数据的 workos api 请求、角色/权限写入以及成员资格角色更新；--force 用于 workos connection delete、workos directory delete 和 workos debug reset。请通过 workos --help --json 查看已安装命令的标志。确认标志不代表用户授权你执行未请求的更改。
• 结构化 CLI 错误（stderr 中的 JSON）包含可选的 error.recovery.hints 数组，其中每条提示都有 description，以及可选的 command 和 hostShellRequired。优先采用这些提示，不要猜测下一步操作。

可能遇到的旧版兼容设置：

• WORKOS_NO_PROMPT=1 是旧版别名，会同时设置 Agent 交互行为和 JSON 输出。迁移时，请设置 WORKOS_MODE=agent，并为命令传入 --json，以保留这两种行为。单独使用 WORKOS_MODE=agent 会失去隐式 JSON 格式设置。
• WORKOS_FORCE_TTY=1 只影响输出格式，不会改变交互模式。

主题 → 参考资料映射

术语查询——“X 是什么”“X 的文档 URL”——由下方的规则 0处理，而不是由此主题映射处理。它们会路由到 references/workos-terms.md。

AuthKit 安装（阅读 references/{name}.md）

用户想要……	阅读文件
在 Next.js 中安装 AuthKit	references/workos-authkit-nextjs.md
在 React SPA 中安装 AuthKit	references/workos-authkit-react.md
使用 React Router 安装 AuthKit	references/workos-authkit-react-router.md
使用 TanStack Start 安装 AuthKit	references/workos-authkit-tanstack-start.md
使用 SvelteKit 安装 AuthKit	references/workos-authkit-sveltekit.md
在原生 JS 中安装 AuthKit	references/workos-authkit-vanilla-js.md
AuthKit 架构参考	references/workos-authkit-base.md
配置 AuthKit 应用 URL	references/workos-authkit-setup.md
添加 Widgets / Clerk 风格 UI	通过 Skill 工具加载 workos-widgets 技能
构建直接调用 Widgets API 的请求	workos-widgets → fetching-apis.md

后端 SDK 安装（阅读 references/{name}.md）

用户想要……	阅读文件
在 Node.js 后端安装 AuthKit	references/workos-node.md
在 Python 中安装 AuthKit	references/workos-python.md
在 .NET 中安装 AuthKit	references/workos-dotnet.md
在 Go 中安装 AuthKit	references/workos-go.md
在 Ruby 中安装 AuthKit	references/workos-ruby.md
在 PHP 中安装 AuthKit	references/workos-php.md
在 PHP Laravel 中安装 AuthKit	references/workos-php-laravel.md
在 Kotlin 中安装 AuthKit	references/workos-kotlin.md
在 Elixir 中安装 AuthKit	references/workos-elixir.md

功能（阅读 references/{name}.md）

用户想要……	阅读文件
配置单点登录	references/workos-sso.md
设置目录同步	references/workos-directory-sync.md
实现 RBAC / 角色	references/workos-rbac.md
使用 Vault 加密数据	references/workos-vault.md
处理 WorkOS 事件 / Webhook	references/workos-events.md
设置审计日志	references/workos-audit-logs.md
启用管理门户	references/workos-admin-portal.md
添加多重身份验证	references/workos-mfa.md
配置电子邮件发送	references/workos-email.md
设置自定义域名	references/workos-custom-domains.md
设置 IdP 集成	references/workos-integrations.md
实现 FGA / 细粒度授权	references/workos-fga.md
设置 Pipes / 已连接应用	references/workos-pipes.md
配置功能标志	references/workos-feature-flags.md
设置 Radar / 欺诈检测	references/workos-radar.md

API 参考（阅读 references/{name}.md）

上方的功能主题文件包含相应 API 的端点表。没有对应功能主题时，请使用以下仅限 API 的参考文档：

用户想要……	阅读文件
AuthKit API 参考	references/workos-api-authkit.md
组织 API 参考	references/workos-api-organization.md

迁移（读取 references/{name}.md）

用户想要……	读取文件
从 Auth0 迁移	references/workos-migrate-auth0.md
从 AWS Cognito 迁移	references/workos-migrate-aws-cognito.md
从 Better Auth 迁移	references/workos-migrate-better-auth.md
从 Clerk 迁移	references/workos-migrate-clerk.md
从 Descope 迁移	references/workos-migrate-descope.md
从 Firebase 迁移	references/workos-migrate-firebase.md
从 Stytch 迁移	references/workos-migrate-stytch.md
从 Supabase Auth 迁移	references/workos-migrate-supabase-auth.md
从独立 SSO API 迁移	references/workos-migrate-the-standalone-sso-api.md
从其他服务迁移	references/workos-migrate-other-services.md

管理与 CLI 生命周期（读取 references/{name}.md）

用户想要……	读取文件
设置或恢复 WorkOS MCP 服务	references/workos-mcp.md
管理 WorkOS 资源（MCP 服务或 CLI）	references/workos-management.md
将 workos CLI 升级到较新版本	references/workos-cli-upgrade.md

路由决策树

按顺序应用这些规则。第一个匹配项优先。

0. 术语／文档 URL 查询

触发条件：以查询为目的的表述——“X 是什么”“X 是什么意思”“X 的文档 URL 是什么”“关于 X 的文档在哪里”“X 的规范链接是什么”“我在哪里可以在控制面板中配置 X”——其中 X 是 WorkOS 专属的配置字段、端点、环境变量或术语。例如：initiate_login_uri、“Sign-in endpoint”、“Redirect URI”、控制面板字段名称、WORKOS_* 环境变量。

对于“设置 Vault”“启用 Admin Portal”“配置 MFA”这类以设置为目的的表述，不要触发规则 0——这些应路由到规则 3（特定功能）。

操作：

1. 读取 references/workos-terms.md——其中有一张精选表格，将 WorkOS 术语映射到规范文档 URL。
2. 如果表格中包含该术语，使用摘要回答；仅当用户想了解更多详情时才 WebFetch 所列 URL。
3. 如果表格中没有该术语，遵循该文件底部的“仍然找不到？”回退说明。找到规范 URL 后，回答用户并建议他们提交 PR 添加一行。

对于术语查询，读取术语文件之前，不要 WebFetch llms.txt，也不要猜测 workos.com/docs/... URL。（规则 8 和 9 会将 llms.txt 用于其他目的——此限制仅适用于规则 0。）

优先原因：术语查询独立于功能、框架和迁移上下文。它们应优先处理，而不是落入“模糊或一般”类别（规则 8）。

---

1. 迁移上下文

触发条件：用户提到要从其他提供商迁移（Auth0、Clerk、Cognito、Firebase、Supabase、Stytch、Descope、Better Auth、独立 SSO API）。

操作：读取 references/workos-migrate-[provider].md，其中 [provider] 与源系统匹配。如果提供商不在表格中，则读取 references/workos-migrate-other-services.md。

优先原因：迁移上下文优先于特定功能路由，因为用户需要针对相应提供商的数据导出和转换步骤。

---

2. API 参考请求

触发条件：用户明确询问“API 端点”“请求格式”“响应架构”“API 参考”，或提到要检查 HTTP 详情。

Widgets 例外：直接的 Widgets Client API / GraphQL 请求应加载 workos-widgets 及其 references/fetching-apis.md。当前文档使用 POST /client/graphql；嵌入已发布的 React widgets 属于单独的组件设置任务。不要将这两类请求导向通用工作区管理，也不要假设捆绑的 /_widgets REST 表格描述的是当前 API。

操作：对于有主题文件的功能（SSO、Directory Sync、RBAC、Vault、Events、Audit Logs、Admin Portal），请阅读对应的功能主题文件，其中包含端点表。对于 AuthKit 或 Organization API，请阅读 references/workos-api-[domain].md。

原因：API 参考属于底层内容；功能主题属于高层内容，但包含端点表，便于快速查阅。

---

3. 特定功能请求

触发条件：用户提及某个特定的 WorkOS 功能名称（SSO、MFA、Directory Sync、Audit Logs、Vault、RBAC、FGA、Admin Portal、Custom Domains、Events、Integrations、Email、Pipes、Feature Flags、Radar）。

操作：阅读 references/workos-[feature].md，其中 [feature] 是小写 slug（sso、mfa、directory-sync、audit-logs、vault、rbac、fga、admin-portal、custom-domains、events、integrations、email、pipes、feature-flags、radar）。

例外：Widgets 请求，包括与 Clerk UserButton 的比较、个人资料/账户设置、安全/会话界面、组织切换器和成员管理界面，应通过 Skill 工具加载 workos-widgets skill。这是嵌入式终端用户界面，而非工作区管理命令。AuthKit 登录/会话配置仍遵循规则 4；迁移和术语参考也会链接到 Widgets 设置。

消歧：如果用户同时提及某项功能和“API”，请转到该功能主题文件（其中包含端点）。如果用户提及多项功能，先转到最具体的功能（例如，“SSO with MFA” → 转到 SSO；用户可以另行询问 MFA）。如果用户提及“FGA”或“细粒度授权”，请转到 workos-fga，而不是 workos-rbac。RBAC 是组织级角色；FGA 是建立在 RBAC 之上的资源范围角色。

特殊情况 — IdP 组到角色的映射：如果用户询问如何将 Entra / Azure AD / Okta / Google Workspace / SCIM / directory / SSO 组映射到 WorkOS 角色（无论具体措辞如何），请同时阅读 workos-rbac.md 和对应来源的参考文件：

• Directory Sync / SCIM / Google Workspace 组 → 也阅读 workos-directory-sync.md
• 仅限 SSO 的组 → 也阅读 workos-sso.md

这两个文件现在都包含规范操作指南。不要凭记忆作答，也不要转述控制台菜单路径——文档并未明确规定具体点击路径，因此你也不应这么做。此映射不是 WorkOS CLI 操作；如果用户询问 CLI 命令，请说明 CLI 中没有此命令，并链接相关文档。

---

4. AuthKit 安装

触发条件：用户提及身份验证设置、登录流程、注册、会话管理，或明确提及“AuthKit”但未提及 SSO 或 MFA 等特定功能。

操作：如果项目尚无 WorkOS 凭据，先从从这里开始执行无账户安装，然后使用以下参考资料进行验证。根据以下证据检查项检测框架、运行时模式和语言。阅读对应的参考文件以及 references/workos-authkit-setup.md。在报告集成完成之前，完成其中的应用设置和流程检查。

消歧：

• 如果用户说“通过 AuthKit 实现 SSO 登录”，请转到 workos-sso（#3）——功能优先于框架。
• 如果用户说“用 React 和 Google 登录”，请转到 AuthKit React（#4）——这是 AuthKit 级别的身份验证，不是 SSO API。
• 如果用户已经在使用 AuthKit，并希望添加某项功能（例如“为我的 AuthKit 应用添加 MFA”），请转到功能参考（#3），而不是返回 AuthKit 安装。

框架和运行时检测（仅限 AuthKit）

检查当前应用/工作区：包脚本和依赖项、框架/路由器配置、SDK 导入、路由注册、服务器执行方式和部署行为。仅凭依赖项名称不足以选择 SDK；浏览器加载器不能证明存在服务器。

已确认的活动集成	阅读
Next.js 配置/脚本以及 Next.js 路由/运行时	references/workos-authkit-nextjs.md
TanStack Start 配置/脚本以及 Start 运行时	references/workos-authkit-tanstack-start.md
SvelteKit 配置/脚本以及 Kit 运行时	references/workos-authkit-sveltekit.md
React Router 与已部署的服务器框架路由	references/workos-authkit-react-router.md
仅客户端的 React，包括以库/数据/声明式方式使用 React Router，或静态部署的框架 SPA 模式（ssr: false）	references/workos-authkit-react.md
已确认使用不含 React 的浏览器 JavaScript	references/workos-authkit-vanilla-js.md

存在 React Router 时，如果执行方式不明确，请阅读 references/workos-authkit-react-router.md 中的模式检查。配置文件、@react-router/node 或构建时预渲染都不能证明存在请求时服务器。不要将服务器回调/环境变量要求应用于浏览器加载器或静态部署。检查运行时和托管配置；如果仍不明确，请提问。

语言检测（后端 SDK）

如果项目不是 JavaScript/TypeScript 前端框架，请根据清单文件检测：

清单文件证据	阅读
pyproject.toml / requirements.txt / setup.py	references/workos-python.md
go.mod	references/workos-go.md
Gemfile / config/routes.rb	references/workos-ruby.md
composer.json 的依赖中包含 laravel/framework	references/workos-php-laravel.md
composer.json 不包含 Laravel	references/workos-php.md
*.csproj / *.sln	references/workos-dotnet.md
build.gradle.kts / build.gradle	references/workos-kotlin.md
mix.exs	references/workos-elixir.md
package.json 包含 express / fastify / hono / koa	references/workos-node.md

Laravel 与普通 PHP 的区分（是否存在 laravel/framework）是这里唯一不明显的情况。

多个信号并非优先级竞争。 Next.js 加上 React Router 依赖，并不意味着 React Router 是当前使用的服务端框架。请检查由哪个应用和运行时负责身份验证。如果未找到前端框架，再检查后端语言；不要将无法识别的项目默认视为纯 JavaScript。

边缘情况 — 证据相互矛盾：如果配置、导入项或部署方式相互冲突（例如，使用服务端 SDK，却采用纯静态托管），请询问用户预期使用哪个运行时。不要猜测，也不要强制迁移框架。

边缘情况 — 根据上下文无法判断框架：如果用户说“添加登录”，但你无法扫描文件（远程仓库、无访问权限），请询问：“你使用的是哪种框架/语言？”未经确认，不要自行设定默认项。

---

5. 集成设置

触发条件：用户提到连接外部 IdP、配置第三方集成，或询问“如何与 [provider] 集成”。

操作：阅读 references/workos-integrations.md。

为何与 SSO 分开：SSO 涵盖身份验证流程；集成涵盖 IdP 配置和连接设置。如果用户同时提到两者（“设置 Google SSO”），请转到 SSO（#3）——其中会在需要时引用集成相关内容。

---

6. MCP 设置或恢复

触发条件：用户要求安装或配置 WorkOS MCP 服务、选择配置范围，或报告 WorkOS MCP 工具缺失、未经身份验证、不可用，或在启动过程中中断。

操作：阅读 references/workos-mcp.md。该文档会通过 WorkOS MCP 官方文档引导设置和恢复，保护配置范围与 OAuth 凭据，并指出必须在用户常用的宿主 Shell 中执行的身份验证步骤。

为何优先处理：在 MCP 工具可调用之前，必须先完成 MCP 设置。这需要检查配置范围和宿主信任，而普通的工作区管理指南并未涵盖这些内容。

---

7. 管理操作（MCP 服务或 CLI）

触发条件：用户提到管理 WorkOS 资源（组织、用户、角色、权限）、播种数据或 CLI 管理命令。

操作：阅读 references/workos-management.md。该文件开篇提供了界面选择指南：读取或写入工作区时优先使用已连接的 WorkOS MCP 工具；引导设置、播种数据、本地配置、CI 和诊断则使用 CLI。即使 MCP 工具已就绪，也要阅读该文件——它会说明哪些操作属于哪个界面。

子情况 — CLI 升级：如果用户报告 workos CLI 已过时（workos --version 显示旧版本、按照近期文档操作后出现 unknown command 错误，或询问“如何更新 workos CLI？”），请改为阅读 references/workos-cli-upgrade.md。不要猜测最新版本——该文件会指导用户运行 npm view workos version。

---

8. 宽泛或一般性请求

触发条件：用户说“帮我了解 WorkOS”“设置 WorkOS”“WorkOS 能做什么”，或未提供具体功能相关的上下文。

操作：

1. WebFetch https://workos.com/docs/llms.txt
2. 在索引中查找最符合用户可能意图的章节
3. WebFetch 对应章节的 URL
4. 总结相关功能，并询问用户想要完成什么

不要猜测用户想用什么功能——应列出选项，促使用户明确需求。

---

9. 无匹配项／有歧义

触发条件：以上规则均不适用，或请求确实存在歧义。

操作：

1. WebFetch https://workos.com/docs/llms.txt
2. 在索引中搜索用户请求中的关键词
3. 如果找到匹配项，WebFetch 对应章节的 URL 并继续处理
4. 如果没有匹配项，请回复：“我找不到与‘[user's term]’匹配的 WorkOS 功能。能否请你说明得更具体一些？例如：身份验证、SSO、MFA、目录同步、审计日志等。”

各规则中的歧义消除说明如下：涉及多项功能 → 选择最具体的一项（规则 3）；功能 + API → 阅读功能文件（规则 2–3）；在现有 AuthKit 应用中添加功能 → 阅读功能参考文档（规则 4）；提及提供商但未指定功能 → Integrations（规则 5）；提供商 + 功能 → 阅读功能参考文档（规则 3）；框架未知或相互冲突 → 询问用户（规则 4）。