umbra-yurei/agent

Cruma 隧道

当用户想要将本机上的内容发布到公网、管理 Cruma 已提供的内容，或者安装/停止 Cruma 时，使用此技能。任何被分享的内容都是公开的：在分享前必须请求确认，并明确告知哪个端口或文件夹将被公开访问。匿名隧道无需注册。

用户的 Cruma 账户

账户功能，包括套餐详情、账户隧道和站点、面板以及记忆存储，由可选的 cruma-cloud 插件提供。有关这些请求请使用其 cloud 技能。分享端口或文件夹以及用户正在运行的代理，则保留在本地 cruma 服务器上。

配合 cruma MCP 工具

此插件通过其启动器 (mcp/cruma-mcp.mjs) 启动 cruma mcp，这是一个名为 cruma 的本地 MCP 服务器，它运行已安装的 cruma 二进制文件。当这些工具出现在你的工具列表中时，直接使用它们，而不要使用 shell 命令。该服务器启动时不会暴露任何内容。

查找信息，而非猜测

此文件是一张地图，而不是操作手册。对于简单的端口或文件夹分享，请使用下面的工具。对于其他一切（例如认证、过滤器、域名、路由、进程、规则、或你不熟悉的设置），请先阅读 Cruma 自身提供的信息，然后使用它指向的工具：

1. 资源 cruma://about（或 describe_cruma）：说明 Cruma 能做什么以及哪个工具来做。然后使用 get_config_model_reference 并指定 section 参数（对于访问控制和请求过滤器使用 middleware_model，以及 backend_kinds、listener_model、recommended_mcp_usage；完整参考很大）和 get_cruma_glossary 来获取术语解释。在用户自己的代理上（见下文），get_runtime_inventory 可以显示已配置的内容。加载你将调用的工具的 schemas。
2. 如果这些还不够，请查阅 Markdown 文档：https://cruma.io/llms.txt、章节列表 https://cruma.io/book/cruma-tunnels.md，以及任何具体章节 https://cruma.io/book/cruma-tunnels/<chapter>.md。这些文档是为命令行（cruma serve，cruma proxy）编写的：从文档中了解 Cruma 的能力，并通过 MCP 工具应用它们。
3. 对于仅限 CLI 的路径，使用 cruma --help 和 cruma <command> --help。

像 expose_local_port 这样的快捷方式涵盖了常见用例。它们无法覆盖的部分，应使用通用的 upsert_* 工具来完成；永远不要将快捷方式的限制说成是 Cruma 的限制。如果参考信息和文档不支持用户的要求，就如实告知；不要臆想一个设置或工具。

永远不要自行提供 HTTP 服务。 不要启动 python3 -m http.server、npx serve 或任何其他文件服务器，也不要运行 cruma serve 或 cruma proxy：当 MCP 连接时，这些命令会启动另一个带有自己隧道的代理。

谁的 Cruma

这些工具在启动时连接到一个临时会话代理：一个匿名隧道，你的窗口共享此隧道，并且它不保存用户存储的任何内容。它不是用户自己的 Cruma。

在会话期间首次分享之前，调用一次 list_agents（它不会从任何代理读取数据，因此首先调用是安全的）。查找正在运行的、不是会话代理并且其 tunnel_account 为 registered 的代理（桌面应用或无头代理，已登录或具有隧道凭据）。具有 tunnel_account anonymous 的正在运行的代理则不是。

• 如果存在一个这样的代理在运行：在分享任何东西之前询问一次。 如果存在多个，则在同一个问题中列出它们。在回答前，不要分享任何东西，也不要调用任何其他读取或更改代理的工具。
  • 用户选择了他们自己的代理：在该代理上调用 use_agent（这就是在 use_agent 之前需要询问的确认），并且会话中的所有分享都通过该代理进行。当适用时，提及已知的限制：在由多个代理服务的隧道的一个代理上进行的分享，只能通过该代理访问。
  • 用户选择了临时隧道：保留在会话代理上。
  • 记住用户的回答，并且在本会话的后续分享中不再询问。不要再次调用 list_agents。仅当用户再次提起时才重新询问。
• 没有这样的代理运行（没有任何代理运行，或者只有像会话代理这样的匿名代理）：无需询问。直接使用会话代理并报告 URL。
• 你无法询问（非交互式运行，或无法获得回答）：使用会话代理，并在交接消息中说明你这样做，并且当 list_agents 显示有已登录的 Cruma 可用时你未使用它。
• 如果用户已经指明了分享的位置（“在我的桌面 Cruma 上”，“使用临时隧道”），则无需询问：遵循用户指示。

分享内容归会话所有，当会话结束时会被撤销；永远不要为它们设置 persist。

当请求是关于他们的 Cruma（他们的应用、站点、路由、域名、进程或日志：例如“为什么我的站点返回 502？”，“给我的 staging 站点添加密码”，“我的 Cruma 里在运行什么？”），或者他们希望通过自己的隧道、自定义域名或命名配置文件来分享时，请在任何读取或更改代理的工具之前调用 list_agents（但 describe_cruma、cruma://about、get_config_model_reference 和 get_cruma_glossary 可以首先安全调用）。读取会话代理得到的答案是关于一个不属于他们的设置，因此永远不要为此类请求读取会话代理。在他们账户上列出或创建隧道属于账户功能（见上文），不属于 list_agents。

• 在 use_agent 之前询问，指明代理的类型（桌面、无头）、配置文件和域名，并等待回答。对于简单的分享，上面的问题就是那个询问；没有询问永远不要切换。切换会撤销你在之前代理上创建的分享。
• 切换之前，只说你要切换到哪个代理并询问。 不要描述任一代理上的内容（包括会话代理上的内容），也不要陈述或暗示任何原因、诊断或已配置的内容，即使 list_agents 显示了进程摘要（例如 Failed 阶段）或站点名称：那只是一个列表，不是诊断。指明目标（类型、配置文件、域名），询问，并说明在用户回答之前没有任何更改，然后停止。在切换之后，从用户的代理进行诊断。
• use_agent 永远不会启动一个代理。如果没有代理在运行用户所指的内容，请如实告知并请用户打开桌面应用，或者运行 cruma --profile <name>（使用 list_agents 为已停止的配置文件提供的名称）。对于关于他们自己站点的请求，不要回退到临时隧道。
• 只说出工具返回的内容。 list_agents 列出它知道的代理；根据它，你只能说哪些代理正在运行以及它们的类型、配置文件和域名。除非工具结果说明存在或缺失配置文件、站点、设置或账户，否则不要做出这样的断言（例如，永远不要说“没有找到保存的配置文件”或“没有配置任何东西”）。
• 如果工具列表中没有 list_agents，则说明是较旧的代理：对于分享，使用临时隧道，并说明需要更新 cruma 才能操作用户自己的代理（Update 中提供了升级命令）。
• 如果用户客户端中已经存在一个 Cruma HTTP MCP 服务器（例如 cruma-app），那就是他们自己的代理。对于关于他们 Cruma 的请求，使用其工具；对于临时分享，使用本插件的工具。如果它无法连接，请如实告知，而不要使用会话代理。list_agents 会标记提供 HTTP /mcp 的代理。

在用户自己的代理上，在他们同意切换之后：

• 成功的 use_agent 结果是你现在所连接代理的状态（域名、前端、进程、allow_persistent_changes）。基于此进行操作；不要仅仅为了确认切换而再次调用 list_agents。

• 读取是自由的：get_health_summary、get_site_summary、get_proxy_routes、probe_route、get_process_logs、list_recorded_requests。

• 更改会应用于正在运行的代理，并在其重启后消失。请告知用户。

• 永久更改（“永久设置一个站点”）需要使用 persist: true，并且除非用户开启了“允许保存更改”设置（mcp.local_socket.allow_persistent_changes；桌面 MCP 页面，“此电脑上的编码代理”），否则代理会拒绝。不要悄悄地进行内存更改。解释此设置并请用户开启它，或者在应用中自行更改。一旦开启（use_agent 结果中的 allow_persistent_changes 为 true，或在切换前的 list_agents 中为 true），不要立即以 persist: true 调用写入工具：首先在你的回复中描述确切的更改（前端、后端、中间件）并询问是否保存，明确指出该更改将保存到磁盘上的代理配置中，并在重启后保留。只有在用户明确批准了该确切更改后，才传递 persist: true：批准可以是在后续轮次中对你的描述的肯定，或者是在同一条消息中对后端和前端按类型和名称命名的保存更改的明确批准（“我批准这个确切的已保存更改：...”）。即使用户要求一个“永久的”或“已保存的”站点，甚至带有名称和路径，那也只是请求，而非批准：描述更改并询问。不要为了使其永久化而在没有相同批准的情况下使用 persist: true 重新发送现有设置。这是 persist 的唯一用途，并且永远不要在会话代理上使用。

保护看起来私密的内容

在暴露看起来私密的内容（如管理界面、数据库工具、内部文档、包含凭据的文件夹、.env 文件或个人数据）之前，询问是否需要进行保护，并建议使用密码。等待回答；不要先暴露后询问。如果用户已经要求保护，则无需再次询问。

• 密码或 IP 白名单：将 access 参数传递给 expose_local_port 或 expose_local_directory（工具 schema 列出了类型）。生成的密码只返回一次。如果 schema 中没有 access 参数（较旧的代理），则使用 upsert_backend 和 upsert_frontend 构建站点，并添加 basic_auth 中间件；请阅读 middleware_model 以了解其结构。
• 使用账户或服务提供商（Google、GitHub）登录：access sign_in 目前不适用于分享。不要尝试或绕过它。登录功能通过 upsert_frontend 实现，需要添加 oauth2 中间件，该中间件引用用户自有代理已有的提供商。在现有前端的 oauth2 中间件中查找提供商 id（使用 full: true 和 `sections: [