This is an automated email from the ASF dual-hosted git repository. hsluoyz pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/casbin-gateway.git
commit 5fec54974392ccff71e252d81593bb2cce6ef569 Author: Yang Luo <[email protected]> AuthorDate: Fri Sep 4 14:18:58 2026 +0800 docs(readme): document link imports, the palette and session filters --- README.md | 15 ++++++++++++++- README_zh.md | 15 ++++++++++++++- 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 52872ac..ef6170b 100644 --- a/README.md +++ b/README.md @@ -112,6 +112,7 @@ - **[Is the API behind that key what it was sold as?](#the-killer-feature-is-the-api-behind-that-key-what-it-was-sold-as)** — a reseller can quietly swap in a cheaper model or fake a cache hit, and none of it shows up in the traffic. Authenticity asks the upstream directly and grades it A–F. - **[Switch every agent's provider from one place](#send-an-agents-traffic-through-gateway)** — change an API key or base URL once, and every agent pointed at Gateway picks it up. +- **[Add a provider, an MCP server, a prompt or a skill from a link](#import-from-a-link)** — click a vendor's "add this" button on the web and Gateway opens with what the link carries, before any of it is written. - **[Run several instances of one agent side by side](#what-to-do-next)** — e.g. multiple Claude Desktop instances, each signed in to a different account. - **[See the whole request, not just a count](#recording-prompts)** — every prompt, message and tool schema an agent sent, kept on this machine. - **[Say what each agent may do](#what-each-agent-is-allowed-to-do)** — around forty switches per agent, in groups, over its tools, models and providers, enforced by Casbin on every request it relays. @@ -173,7 +174,7 @@ Gateway installed some other way, or in a directory it cannot write to, says so | --- | --- | --- | | **Agents** | Every AI coding agent installed on this machine — Claude Code, Codex CLI, Cursor, the Gemini CLI, opencode and more — four cards to a row, each naming the account it is signed in to, the provider it answers to, what it has spent, and whether it is running right now. Start or stop one from its card, or run several **instances** of the same agent at once, each with a state directory and an account of its own. An agent this machine does not have is listed too, and installed o [...] | **Skills, MCP & Prompts** | Every skill, MCP server and instruction file of every agent in one table. Install skills from a GitHub repository, a `.zip` or `.tar.gz`, or a folder on this machine, into one agent or several at once. Add an MCP server the same way, edit the instructions an agent reads before every session, open one, delete it, or copy it into another agent. | Nothing | -| **Sessions** | Every session those agents have had, read from the transcripts they leave on disk: the whole conversation, message by message. | Nothing | +| **Sessions** | Every session those agents have had, read from the transcripts they leave on disk: the whole conversation, message by message. How many there are, how many ran today and how many came from a transcript rather than from monitoring, then filtered down to one agent or one of those two sources. | Nothing | | **Activity** | What a monitored agent is doing as it does it — each tool call, its target and how long it took. | Monitoring on for an agent | | **Providers** | One endpoint in front of your model vendors. Gateway holds the API key, so the agents never have it — or forwards the agent's own sign-in and holds nothing. | A vendor API key, or nothing at all | | **Authenticity** | A score out of 100 and a grade for every provider, measured without being asked — see [the section below](#the-killer-feature-is-the-api-behind-that-key-what-it-was-sold-as). | A provider with an API key | @@ -181,6 +182,8 @@ Gateway installed some other way, or in a directory it cannot write to, says so | **Usage** | What every agent on this machine spent, over time and broken down by model and by agent, read from the agents' own transcripts — so it counts the requests that never went through Gateway. A second tab shows what Gateway relayed, which is the only account that knows which provider answered and whether it failed. | Nothing | | **Model pricing** | What a million tokens costs, which is what every figure on the Usage page is worked out from. Edit a price by hand, or let Gateway reprice the models this machine has run from the [models.dev](https://models.dev) catalogue on a schedule; a price you edited yourself is left alone. | Nothing | +A page with tabs or sections is in the sidebar under its own name, so the rail lands on the test cases, the MCP servers or the security settings rather than only on the top of the page they are on. **⌘K**, or **Ctrl+K**, opens a search box over whichever page you are on: every page by name, and every agent and provider on this machine, which is how you reach one of thirty providers without paging through the list. + Agents are found by reading the user accounts, home directories and install paths of **the machine Gateway runs on**, so run it on the machine whose agents you want to watch. ### The killer feature: is the API behind that key what it was sold as? @@ -226,6 +229,16 @@ The environment snippet for such a provider sets the base URL and nothing else Codex is the exception: its ChatGPT sign-in talks to an endpoint no provider stands in for, so a Codex CLI still needs a provider with an API key. +### Import from a link + +Vendors put an "add this to my agent manager" button on their own pages, which opens a `ccswitch://` link rather than a page. Gateway reads that format instead of inventing a second one nobody would be given a button for, and one link carries any of four things: a provider with its base URL, key and model list; an MCP server, as the JSON block a server is written in; a set of instructions for an agent to read before every session; or a repository to install skills from. + +Gateway claims the scheme on Windows and Linux when it starts, so clicking such a button opens Gateway on the **Import** page with everything the link held laid out — the arguments an MCP server would be run with, the instructions in full, the repository a skill would come from. **Nothing is written until the button under it is pressed**: the link came from a website, so its values are read first. A provider goes on to the Providers form, where it is reviewed and probed against the upstr [...] + +The link is handed to Gateway in the body of an API call, not in the address of the page it opens, because a provider link carries an API key and an address is kept in browser history and sent on to wherever the page navigates next. + +The scheme is taken from whatever held it only the first time, and given back when Gateway is removed; a registration that is already Gateway's own is rewritten on every start, since it records a path that an update or a move would otherwise leave pointing at a Gateway that is no longer there. On macOS nothing is claimed at all — a URL scheme there belongs to an application bundle and the link arrives as an Apple event, which this launcher has no loop to receive, so declaring it would ta [...] + ### What each agent is allowed to do **Permissions** in the sidebar is the page for it: every agent on this machine down one side, what the one you picked may do beside it. The same card is on the agent's own page. Everything that agent relays through Gateway is held to what is set there, so it can be given less than it came with without editing its own configuration. diff --git a/README_zh.md b/README_zh.md index ff47ae6..7ac8c5f 100644 --- a/README_zh.md +++ b/README_zh.md @@ -112,6 +112,7 @@ - **[查一查那个 Key 背后的 API 是不是真的](#杀手锏那个-key-背后的-api真是卖给你的那个吗)** —— 中转商可以偷偷换成便宜模型、伪造缓存命中，流量里根本看不出来。Authenticity 直接问上游，测出 A 到 F 的等级。 - **[一个地方切换所有 Agent 的 API 供应商](#让-agent-的流量走-gateway)** —— 改一次 Key 或 base URL，接进 Gateway 的每个 Agent 都跟着换。 +- **[一条链接就能导入 Provider、MCP、提示词或技能](#从一条链接导入)** —— 在网页上点厂商的「添加到」按钮，Gateway 就带着链接里的东西打开，写进去之前先给你看。 - **[同一个 Agent 开多个实例](#接下来做什么)** —— 比如同时跑好几个 Claude Desktop，各自登录不同账号。 - **[看到完整的请求，而不只是一个数字](#记录提示词)** —— 每一条 prompt、消息和工具 schema，都留在这台机器上。 - **[规定每个 Agent 能做什么](#每个-agent-能做什么)** —— 每个 Agent 四十来个开关，分组管理，覆盖工具、模型和供应商，每个转发的请求都由 Casbin 判定。 @@ -171,7 +172,7 @@ Gateway 会在自己的窗口里打开 —— 不用登录：它只服务本机 | --- | --- | --- | | **Agents** | 本机安装的每一个 AI 编程 Agent —— Claude Code、Codex CLI、Cursor、Gemini CLI、opencode 等等 —— 一行四张卡片，每张写明它登录的是哪个账号、接的是哪个 Provider、花了多少、此刻是不是在跑。可以在卡片上直接启动或停止，也可以给同一个 Agent 开多个**实例**，每个实例有自己的状态目录和自己的登录账号，同时运行。本机没装的 Agent 也会列出来，可以直接用宿主机已有的包管理器安装或升级。 | 无 | | **Skills, MCP & Prompts** | 所有 Agent 的所有技能、MCP 服务器和提示词文件汇总在一张表里。可以从 GitHub 仓库、`.zip` / `.tar.gz` 压缩包，或本机的一个目录安装技能，一次装进一个或多个 Agent。MCP 服务器也一样，还能编辑某个 Agent 每次会话前读到的提示词，或者打开、删除、复制到另一个 Agent。 | 无 | -| **Sessions** | 这些 Agent 的每一次会话，从它们留在磁盘上的会话记录里读出来：完整的对话，一条一条。 | 无 | +| **Sessions** | 这些 Agent 的每一次会话，从它们留在磁盘上的会话记录里读出来：完整的对话，一条一条。一共多少次、今天跑了多少次、其中多少条是从会话记录里读来而不是监控到的，都在页头；再按 Agent 或按这两种来源筛。 | 无 | | **Activity** | 被监控的 Agent 正在做什么：每一次工具调用、调用的目标，以及耗时。 | 给某个 Agent 打开监控 | | **Providers** | 挡在模型厂商前面的统一入口。API Key 由 Gateway 持有，Agent 拿不到；也可以转发 Agent 自己的登录，什么都不持有。 | 一个厂商的 API Key，或者什么都不用 | | **Authenticity** | 每个 Provider 一个 100 分制的分数和一个等级，不用点按钮就会自动测出来 —— 见[下面这一节](#杀手锏那个-key-背后的-api真是卖给你的那个吗)。 | 一个带 API Key 的 Provider | @@ -179,6 +180,8 @@ Gateway 会在自己的窗口里打开 —— 不用登录：它只服务本机 | **Usage** | 本机每个 Agent 花了多少：按时间、按模型、按 Agent 分别统计，数据来自 Agent 自己写的会话记录 —— 所以没走 Gateway 的请求也算得上。另一个页签是 Gateway 转发过的部分，那是唯一知道由哪个 Provider 作答、是否失败的账。 | 无 | | **Model pricing** | 每百万 Token 多少钱，Usage 页面上的每一个金额都由它算出来。可以手工改某个价格，也可以让 Gateway 按计划从 [models.dev](https://models.dev) 的目录给本机跑过的模型重新定价；你手工改过的价格不会被覆盖。 | 无 | +带页签或分节的页面，在侧边栏里各有自己的名字，所以从导航栏可以直接落到测试用例、MCP 服务器或安全设置那一节，而不是只能落到它们所在页面的顶部。**⌘K**（Windows 和 Linux 上是 **Ctrl+K**）在当前页面上打开一个搜索框：按名字搜每一个页面，也搜本机的每一个 Agent 和 Provider —— 三十个 Provider 里找一个，不用一页页翻。 + Agent 是通过读取 **Gateway 所在机器**的用户账户、home 目录和安装路径发现的，所以要在你想观察的那台机器上运行它。 ### 杀手锏：那个 Key 背后的 API，真是卖给你的那个吗？ @@ -223,6 +226,16 @@ export ANTHROPIC_AUTH_TOKEN="cg-..." Codex 是例外：它的 ChatGPT 登录走的是没有任何 Provider 能替代的端点，所以 Codex CLI 仍然需要一个带 API Key 的 Provider。 +### 从一条链接导入 + +厂商会在自己的页面上放一个「添加到我的 Agent 管理器」按钮，点开的是一条 `ccswitch://` 链接，而不是一个网页。Gateway 直接读这个格式，而不是再造一个没人会给你按钮的格式。一条链接可以带四样东西之一：一个 Provider，连同它的 base URL、Key 和模型列表；一个 MCP 服务器，就是它平时写成的那段 JSON；一份 Agent 每次会话前要读的提示词；或者一个安装技能用的仓库。 + +Gateway 启动时会在 Windows 和 Linux 上接管这个协议，所以点这种按钮就会打开 Gateway 的 **Import** 页面，把链接里的东西摊开给你看 —— MCP 服务器会以什么参数启动、提示词的全文、技能从哪个仓库来。**在你按下下面那个按钮之前，什么都不会写进去**：链接来自别人的网站，所以先看清楚里面是什么。Provider 会转到 Providers 的表单里，在那里过目并向上游探测之后才存下来；另外三样从这里写入，走的是手工添加时的同一批接口，写进你勾选的那些 Agent。链接里写的是「应用」而不是本机的 Agent，其中 Gateway 不管的那些会明确告诉你，而不是悄悄丢掉。 + +链接是放在一次 API 调用的 body 里交给 Gateway 的，不是放在它打开的那个页面的地址里 —— Provider 链接带着 API Key，而地址会留在浏览器历史里，还会跟着页面之后的跳转一起发出去。 + +这个协议只在第一次从原来的持有者手里接管，Gateway 卸载时再还回去；已经是 Gateway 自己的注册则每次启动都重写一遍，因为它记的是一个路径，升级或移动之后会指向一个已经不在那里的 Gateway。macOS 上则什么都不接管 —— 那里的 URL 协议属于应用程序包，链接是以 Apple event 送达的，而这个启动器没有接收它的事件循环，声明了反而会把链接从能打开它的程序那里抢走。在 macOS 上把链接粘进 Import 页面的输入框即可，这个办法在所有平台都能用；Providers 页面同样可以直接粘一条 Provider 链接。 + ### 每个 Agent 能做什么 侧边栏的 **Permissions** 就是这个页面：一侧是这台机器上的每个 Agent，另一侧是选中那个能做什么；Agent 自己的详情页上也有同一张卡片。这个 Agent 经 Gateway 转发的所有请求，都按这里设的来判，不用改它自己的配置，就能把能力收窄。 --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
