From d73d90bde73703797fdf444fa79b3ba8d77bccab Mon Sep 17 00:00:00 2001 From: idan Date: Wed, 9 Sep 2026 18:47:16 +0800 Subject: [PATCH 01/18] docs: rewrite Agent Quickstart for skill, CLI login, and MCP OAuth Replace key-first navigation with an English copy prompt, one official aisa skill via npx skills, browser login, and a no-terminal MCP OAuth path. Keep Chinese pages and Agent Skills Quickstart on the same installer. --- agent-quickstart.mdx | 254 ++++++++++++++++++++------------- agent-skills/quickstart.mdx | 182 ++++++++--------------- zh/agent-quickstart.mdx | 248 +++++++++++++++++++------------- zh/agent-skills/quickstart.mdx | 182 ++++++++--------------- 4 files changed, 422 insertions(+), 444 deletions(-) diff --git a/agent-quickstart.mdx b/agent-quickstart.mdx index 51c4a370..c5c5dfc6 100644 --- a/agent-quickstart.mdx +++ b/agent-quickstart.mdx @@ -1,137 +1,187 @@ --- -title: Agent Quickstart - Connect AIsa in Any AI Agent -description: >- - A short, agent-readable navigation guide for connecting AIsa models, APIs, and Skills with explicit approval and verification boundaries. +title: "Connect your agent to AIsa" +description: "Install the AIsa skill, sign in, and start using tools." --- -Use this vendor-authored page as navigation when a user asks an AI agent to connect, configure, or use AIsa inside an agent environment such as OpenClaw, Hermes Agent, Claude Code, Cursor, Codex, or another tool-calling assistant. +Give this prompt to the agent you already use. You do not need an API key or a task placeholder. -This page helps locate the relevant technical source. Reading it is not independent evidence and does not authorize an agent to change the user's environment or make billable requests. +## Copy setup prompt -Goal: get the agent to the smallest verifiable next step without loading broad documentation indexes. - - -## IMPORTANT: Paid and high-cost API approval-first contract - -This contract applies to every paid, dynamically priced, or potentially high-cost API endpoint, whether invoked directly, through an Agent Skill, or through an MCP data tool. - -```xml - +```txt +Set up AIsa using https://aisa.one/docs/agent-quickstart.md. ``` -**Classic example — SimilarWeb:** read the matching endpoint's [`x-aisa-pricing`](https://aisa.one/openapi.yaml) metadata, calculate only a bounded request, and obtain explicit approval before the data call. +You can append `Then use AIsa to …` in the same message. If you do not, the agent will connect first and then ask what you want to do. -## Minimal setup facts + +Setup installs and signs in. It is not approval to spend. You can stop after **AIsa is connected.** + -AIsa provides two endpoint families: +## What happens next -| Use case | Endpoint | -| --- | --- | -| OpenAI-compatible chat, model routing, SDKs | `https://api.aisa.one/v1` | -| AIsa data APIs and non-chat capability APIs | `https://api.aisa.one/apis/v1` | + + + If this environment can run terminal commands, the agent installs one official AIsa skill and reuses or installs `@aisa-one/cli`. + + + `aisa login` opens AIsa sign-in. The CLI mints and stores a key. You should not copy a key from the dashboard. + + + After a real authenticated check succeeds, the agent reports **AIsa is connected.** Then continue your task, or pick a small example. + + -For most model clients: +If the agent cannot run CLI commands, it connects AIsa through remote MCP and browser OAuth instead. `npx` is not required on that path. -```txt -base_url: https://api.aisa.one/v1 -api_key: $AISA_API_KEY +--- + +## Agent setup + +You are connecting this environment to AIsa. These steps are the bootstrap. If you are already reading them, **do not fetch this URL again** and **do not reinstall the same skill**. + +Do not load the full docs index, OpenAPI catalog, or Skill body here. After the skill file is available, read that file for standing workflow rules. + +### 1. Detect the environment + +1. Identify the current agent/harness. +2. Reuse a working AIsa connection when one already exists: the official `aisa` skill plus valid CLI auth, or a connected AIsa MCP session with the four router tools listed below. +3. Prefer the CLI path when this environment can run terminal or CLI commands. Any working shell counts, including PowerShell. Bash is not required. +4. Use the MCP path when there is no usable terminal/CLI, or the user explicitly prefers MCP. +5. Do not require Node.js or `npx` on the MCP path. On the CLI path, if `npm`/`npx` are missing, install Node.js 18+ or switch to MCP. + +Do not install every skill, every agent target, or unrelated model settings. + +### 2. CLI path (default) + +#### Install one official skill + +Source: [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills). Slug: `aisa`. Canonical file: `search-research/aisa/SKILL.md`. + +Use the Vercel skills installer, targeted at **this** harness only: + +```sh +npx skills add AIsa-team/agent-skills --skill aisa --agent codex --global ``` -Use the API key as a Bearer token. Do not print, log, commit, or hardcode it. Prefer environment variables or the agent runtime's secret store. +Adapt `--agent` to the current harness (for example `codex`, `claude-code`, `cursor`). Prefer `--global` for personal use. Use project scope only when the user asked to limit the install to this repo. + +- Do not use `--all`, `--agent '*'`, or `--skill '*'`. +- Use `--yes` only when this install is already authorized and the source/target are clear. +- If the official `aisa` skill is already present, reuse it. Do not overwrite a same-named custom skill. +- Do **not** use `aisa skills install` as the default installer. +- After the file is on disk, **read it in this session and continue**. Do not stop only to wait for a restart. If this client cannot load a newly installed skill until a new session, say that and continue with CLI commands you can already run. -```bash -export AISA_API_KEY="" +#### Install or reuse the CLI + +Install or reuse npm package `@aisa-one/cli`. Verified baseline: **0.5.0 or later**. Do not downgrade an existing CLI. The skill version does not need to match the CLI version. + +Confirm `search`, `schema`, `quote`, and `call` exist (`aisa --help` or `aisa manifest`). Take flags, JSON shapes, and examples from `aisa --help` — not from a guessed catalog. + +```sh +npm install -g @aisa-one/cli +aisa --version ``` -If the user has not provided a key, explain where to create one instead of inventing a placeholder value. +#### Sign in -Select an endpoint that the chosen model currently supports. Check the [model catalog](/guides/models) or the exact API reference instead of inferring `chat/completions`, `responses`, `messages`, or a media endpoint from the model name. +1. Reuse existing auth. Do not log in again if a stored CLI key or `AISA_API_KEY` already works. +2. If not signed in, run `aisa login` and let the user finish browser OAuth. The CLI mints and stores a CLI key. The user should not open the API Keys page or paste a key. +3. `aisa login --no-browser` is only for SSH / no local browser with an interactive TTY. It is not a silent headless login. +4. `--key` / `AISA_API_KEY` are for automation or advanced use, not this Quickstart. +5. Never print, log, or commit the raw key. Do not change the user's default model or unrelated client config. +6. `AISA_API_KEY` overrides the stored key. If both exist and disagree, explain the two sources. Do not blindly unset the environment variable or overwrite config. +7. `aisa whoami` is **local only**. It does not prove the remote credential still works. +8. Validate with a real authenticated read such as `aisa balance`. Report **AIsa is connected.** only after that succeeds. +9. Expired credentials → run `aisa login` again. Empty balance → top up the account; that is not a missing key. +10. If login or mint fails, show the error and the next step. Do not send the user to hunt for an API key, and do not “fix” every failure by reinstalling. -## Choose one path +### 3. MCP path (no CLI, or user prefers MCP) -First identify what the user wants, then read only the docs for that path. +Connect the **unified AIsa router**. Do not use the domain catalog at `https://mcp.aisa.one/servers`, and do not treat the default `aisa connect` web-search server as this router. -| User wants | Read next | +| Field | Value | | --- | --- | -| Basic AIsa account/API key setup | [Getting Started with AIsa](/guides/getting-started-with-aisa), [Authentication](/guides/authentication) | -| Use AIsa as an LLM provider | [Models](/guides/models), [Chat Completions API](/api-reference/chat/post_chat-completions) | -| Use AIsa in Hermes Agent | [Use AIsa in Hermes Agent](/guides/tutorials/use-aisa-in-hermes-agent) | -| Use AIsa in OpenClaw | [Use AIsa in OpenClaw](/guides/tutorials/use-aisa-in-openclaw) | -| Use Agent Skills | [Agent Skills](/agent-skills), [Agent Skills Quickstart](/agent-skills/quickstart) | -| Search or research the web | [Tavily Search](/agent-skills/tavily-search), [Tavily Extract](/agent-skills/tavily-extract), [Smart Search](/agent-skills/smart-search) | -| Deep research | [Perplexity Deep Research](/agent-skills/perplexity-research), [Perplexity Deep Research API](/api-reference/perplexity/post_perplexity-sonar-deep-research) | -| Academic search | [Scholar Search](/agent-skills/scholar-search), [Scholar API](/api-reference/scholar/post_scholar-search-scholar) | -| Specific REST API | [API Reference](/api-reference), then only the exact endpoint page needed | - -## Agent behavior - -- Ask one clarifying question only if the target path is unclear. -- Load the smallest relevant doc set for the task. -- Do not open unrelated API pages. -- Do not paste large docs into the conversation when a short summary and links are enough. -- Match the selected model to a documented endpoint; do not infer route support from its name. -- Before modifying files, installing software, or sending a billable request, describe the action and get the user's confirmation. -- Before saying setup works, perform the relevant checks below. -- For secrets, verify storage without revealing the key. - -## Verify the setup - -Start with a read-only request that checks connectivity and authentication without invoking a model: - -```bash -curl --silent --show-error --fail \ - --output /dev/null \ - --write-out "HTTP %{http_code}\n" \ - https://api.aisa.one/v1/models \ - -H "Authorization: Bearer $AISA_API_KEY" -``` +| Name | AIsa | +| Server URL | `https://tools.aisa.one/mcp` | +| Transport | Streamable HTTP | +| Auth | OAuth (let the client discover endpoints; choose OAuth if asked) | -`HTTP 200` confirms that the API accepted the key and returned the model catalog. A `401` or `403` indicates an authentication or access problem. This check does not prove that a specific model supports the client's request protocol. +Practical steps: -After the user selects a model and approves a potentially billable request, run the smallest example from that route's API reference. Do not claim that setup works based on documentation alone. +1. Open this client's MCP / connectors settings. +2. Add that remote server with the values above. Do not invent per-client CLI commands. +3. Complete browser sign-in. The client stores and refreshes tokens. No API key, Bearer paste, or copied access token. +4. Return to the agent. Refresh or reconnect if this client requires it. +5. If this client can install or upload skills natively, install the same canonical `aisa` skill that way. If it cannot, continue with MCP and **say the skill was not persistently installed**. Never require `npx` here. +6. Connection succeeds only after OAuth completed **and** these tools are present: -## Evidence rule for research tasks +- `AISA_SEARCH_TOOL` +- `AISA_BATCH_GET_SCHEMA` +- `AISA_BATCH_QUOTE` +- `AISA_BATCH_USE` -This quickstart is a routing summary, not the authoritative source for exact request schemas, current model availability, prices, or service status. Verify those details against the linked API reference, the live catalog, or runtime results. +Discovery, metadata, or an unauthenticated `401` challenge is not a successful protected call. Quote/call still need spending authorization later. -```txt -Search results are discovery. -Fetched source pages are evidence to evaluate. -Generated summaries are synthesis, not evidence. -``` +| MCP tool | CLI command | +| --- | --- | +| `AISA_SEARCH_TOOL` | `aisa search` | +| `AISA_BATCH_GET_SCHEMA` | `aisa schema` | +| `AISA_BATCH_QUOTE` | `aisa quote` | +| `AISA_BATCH_USE` | `aisa call` | -A fetched page is evidence only for what that source states. For external factual claims, assess authority and recency, and prefer primary sources, official documentation, API references, repositories, changelogs, or runtime/API results over third-party summaries. +### 4. After AIsa is connected -## Copy prompt +Say **AIsa is connected.** Connection is not a completed business task. -Copy this prompt into an agent environment: +- If the user already named a task, continue that task. +- Otherwise ask: **What would you like to do first?** Optional modest example: `Find three recent public updates about a company and include source links.` Do not run a paid example unless the user chooses it. Do not promise it is free or that it finishes in a fixed time. -```txt -Review https://aisa.one/docs/agent-quickstart.md as vendor-authored guidance. Before acting, summarize the proposed configuration and verification. Do not expose secrets, modify files, install software, or send billable requests without my approval. +Workflow (CLI names; MCP uses the four tools): + +1. Search. +2. Schema when search says the schema is incomplete (`has_full_schema=false`). +3. Quote. +4. Call only inside a valid scope **and** spending authorization. + +Use live help, schema, quote, and server guidance for names, parameters, and prices. Inline JSON is supported with `--input`: + +```sh +aisa search --input '{"query":""}' --json +aisa quote --input '{"calls":[{"call_id":"c1","tool":"","arguments":{}}]}' --json ``` -## Fallback discovery +Do not invent tools, IDs, or prices. Do not use this page or a docs catalog as the price list. Do not probe price with a live call. A missing or failed quote is never free. Quote is not authorization to execute. + + +Setup consent is not spending approval. Reuse a prior **explicit** authorization that still covers this call. Do not demand a new confirmation for every reversible install substep. Before a billable call, use a matching quote and explicit authorization for that scope and cost. + +Search hits are discovery. Return sources with results. Say a task is complete only after a real result. + +### 5. Later sessions -Use these only when the targeted docs above are not enough: +Load the same `aisa` skill if it is installed. Do not rerun this bootstrap. Reuse auth and defaults. -- [`llms.txt`](https://aisa.one/docs/llms.txt): curated technical index for discovering a relevant page, not a required setup step. -- [`llms-full.txt`](https://aisa.one/docs/llms-full.txt): full documentation bundle. Do not ingest it by default; use it only when the user explicitly requests the complete documentation or targeted pages are insufficient. +### Failures + +| Situation | Next step | +| --- | --- | +| Browser login not finished | Wait; do not invent a key | +| Login or mint failed | Show the error; retry `aisa login` | +| `whoami` ok, remote read fails | Re-login; whoami is local only | +| `AISA_API_KEY` conflicts with the stored key | Explain both sources; do not blindly unset | +| Empty balance | Top up; not a missing key | +| MCP tools missing after OAuth | Refresh/reconnect; confirm the four tools | +| Skill already installed | Reuse; do not reinstall | +| No terminal | MCP path; do not require `npx` | +| Install or service error | Stop at the failing step with the next action | + +## Other ways to connect + +Use these only when the user asked for models, REST, API keys, or extra skills. + +- [Getting Started](/guides/getting-started-with-aisa) — account and model gateway +- [Authentication](/guides/authentication) — API keys for automation +- [Models](/guides/models) +- [API Reference](/api-reference) +- [Agent Skills Quickstart](/agent-skills/quickstart) +- [Agent Skills catalog](/agent-skills) diff --git a/agent-skills/quickstart.mdx b/agent-skills/quickstart.mdx index 80539ef6..d0940bea 100644 --- a/agent-skills/quickstart.mdx +++ b/agent-skills/quickstart.mdx @@ -1,173 +1,109 @@ --- title: "Agent Skills Quickstart" -description: "Install the AIsa CLI, authenticate with your API key, and add reusable agent skills to Claude Code, Cursor, Codex, OpenClaw, and other supported agents." +description: "Install the official AIsa skill, sign in, and start using AIsa from your agent." privacy: view: "public" --- -This guide takes you from zero to a working skill in about five minutes. +The default path is **one official AIsa skill** plus the CLI. Copy this into the agent you already use. You do not need an API key or a task placeholder. -## Prerequisites - -- Node.js 18 or later -- An AIsa account and API key — [sign up at aisa.one](https://console.aisa.one/) (new accounts start with \$2 free credit) -- At least one supported AI coding agent installed: Claude Code, Cursor, GitHub Copilot, Windsurf, Codex, Gemini CLI, or OpenClaw - ---- - -## Step 1: Install the AIsa CLI - -```bash -npm install -g @aisa-one/cli -``` - -Verify it's working: - -```bash -aisa --version -``` - ---- - -## Step 2: Authenticate - -```bash -aisa login --key YOUR_AISA_API_KEY +```txt +Set up AIsa using https://aisa.one/docs/agent-quickstart.md. ``` -Or set the environment variable — it takes precedence over the stored key: +The complete agent bootstrap — environment detection, login reuse, validation, spend authorization, and failure handling — is in [Agent Quickstart](/agent-quickstart). This page matches that installer and the no-terminal MCP branch so the two entries stay consistent. -```bash -export AISA_API_KEY="YOUR_AISA_API_KEY" -``` + +Do not fetch the Quickstart URL again if you are already following these steps. Do not reinstall the same `aisa` skill. + -Check your auth status at any time: +## Install the official AIsa skill -```bash -aisa whoami -``` +Source: [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills). Slug: `aisa`. Canonical file: `search-research/aisa/SKILL.md`. ---- - -## Step 3: Browse available skills +If this environment can run terminal or CLI commands (any shell, not only Bash), install **one** skill into the **current** harness with the Vercel installer: -```bash -aisa skills list +```sh +npx skills add AIsa-team/agent-skills --skill aisa --agent codex --global ``` -This fetches the live catalogue from the [agent-skills](https://github.com/AIsa-team/agent-skills) registry and prints each skill's name, slug, and description. - -Search by keyword: - -```bash -aisa skills search "finance" -aisa skills search "search" -``` - -See the full details for a specific skill before installing: - -```bash -aisa skills show market -``` +Adapt `--agent` to this harness (for example `codex`, `claude-code`, `cursor`). Prefer `--global` for personal use. Use project scope only when the user asked to limit the install to this repo. ---- +- Do not use `--all`, `--agent '*'`, or `--skill '*'`. +- Use `--yes` only when this install is already authorized and the source/target are clear. +- If the official `aisa` skill is already present, reuse it. Do not overwrite a same-named custom skill. +- Do **not** use `aisa skills install` as the default way to connect AIsa. +- After the file is on disk, **read it in this session and continue**. Do not stop only to wait for a restart. -## Step 4: Install a skill +## Install or reuse the CLI, then sign in -```bash -aisa skills install search +```sh +npm install -g @aisa-one/cli +aisa --version +aisa login ``` -The CLI automatically detects every supported agent on your machine and writes the skill to each agent's skills directory. You'll see a confirmation line per agent: +Reuse `@aisa-one/cli` if it is already installed. Verified baseline: **0.5.0 or later**. Do not downgrade. -```text -✓ ~/.claude/skills/ (claude) -✓ ~/.cursor/skills/ (cursor) -Skill 'search' installed to 2 agent(s) -``` +`aisa login` opens browser OAuth and mints a stored CLI key. The user should not copy a key from the dashboard. `--key` / `AISA_API_KEY` are for automation, not this path. -To install only for a specific agent: +- Never print the raw key. +- `AISA_API_KEY` overrides the stored key. If they conflict, explain both sources; do not blindly unset the environment variable. +- `aisa whoami` is local only. Validate with a real authenticated read such as `aisa balance` before saying **AIsa is connected.** +- Setup is not approval to spend. -```bash -aisa skills install search --agent claude -``` +Then use `aisa search` → `aisa schema` when needed → `aisa quote` → `aisa call` inside a valid scope and spending authorization. Parameters and prices come from help/schema/quote, not from this page. Inline JSON works with `--input`. -To install for all supported agents regardless of what's detected: +## No terminal, or you prefer MCP -```bash -aisa skills install search --agent all -``` - ---- +If this agent cannot run CLI commands, or the user asked for MCP, do not require `npx`. Add the unified AIsa router as a remote Streamable HTTP MCP server: -## Step 5: Use the skill +| Field | Value | +| --- | --- | +| Name | AIsa | +| Server URL | `https://tools.aisa.one/mcp` | +| Transport | Streamable HTTP | +| Auth | OAuth | -Open a **new session** in your agent (skills are loaded at session start, not mid-session). Then ask it to do something the skill handles: +Open this client's MCP settings, add that server, complete browser sign-in, then return and refresh/reconnect if needed. The client discovers endpoints and stores/refreshes tokens. No manual keys. -```text -Search the web for the latest news on AI agent frameworks and summarise the top three stories. -``` +Do **not** use `https://mcp.aisa.one/servers` or the default `aisa connect` web-search server as this router. -The agent reads the `search` skill description, loads the full `SKILL.md` instructions, and calls the AIsa search API using your key. +If the client can install skills natively, install the same canonical `aisa` skill. If it cannot, continue with MCP and say the skill was **not persistently installed**. ---- +Connection succeeds only after OAuth completed **and** these tools are present: `AISA_SEARCH_TOOL`, `AISA_BATCH_GET_SCHEMA`, `AISA_BATCH_QUOTE`, `AISA_BATCH_USE`. Discovery alone is not a protected business call. -## Step 6: Install multiple skills +## After AIsa is connected -```bash -aisa skills install market -aisa skills install twitter -aisa skills install media-gen -``` +Ask **What would you like to do first?** unless the user already named a task. Optional example: `Find three recent public updates about a company and include source links.` Do not promise it is free. -Once multiple skills are installed, your agent can use whichever is appropriate for any given task — without you specifying which skill to use. +Later sessions should load the same `aisa` skill. Do not rerun setup. ---- +## Optional: more skills from the catalog -## Managing installed skills +After AIsa is connected, you can browse extra domain skills. This is not the default connect path. -```bash -# List skills available in the registry +```sh aisa skills list - -# Remove a skill from all agent directories -aisa skills remove market - -# Remove from a specific agent only +aisa skills search "finance" +aisa skills show market +aisa skills install market --agent cursor aisa skills remove market --agent cursor ``` ---- +Do not install every catalog skill, and do not target all agents unless the user asked. ## Create your own skill -Scaffold a new skill from a template: - -```bash -# Default blank template +```sh aisa skills init my-skill - -# Start from a specific template -aisa skills init my-skill --template finance # finance template -aisa skills init my-skill --template search # search template -aisa skills init my-skill --template llm # LLM gateway template -aisa skills init my-skill --template twitter # Twitter template -aisa skills init my-skill --template video # video generation template -``` - -This creates a `my-skill/` folder with a pre-filled `SKILL.md`. Edit the `name`, `description`, and body to describe your capability. Then install it like any other skill: - -```bash -aisa skills install ./my-skill # install from local path +aisa skills install ./my-skill ``` -To share your skill with the community, submit a pull request to [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills). - ---- +Edit `SKILL.md`, then install from the local path. To share it, open a pull request on [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills). Authoring rules: [Standards](/agent-skills/standards). ## What's next -- [Agent Skills](/agent-skills) — full catalogue with descriptions and GitHub links -- [Standards](/agent-skills/standards) — how SKILL.md files work and how to author your own -- [Agent Skills vs custom skills](/guides/learn/agent-skills-vs-tools) — when to use a registry skill vs. building your own -- Questions? [contact us](mailto:developer@aisa.one) +- [Agent Quickstart](/agent-quickstart) — full connect, login, MCP, and spend rules +- [Agent Skills](/agent-skills) — catalog +- [Standards](/agent-skills/standards) — how `SKILL.md` works diff --git a/zh/agent-quickstart.mdx b/zh/agent-quickstart.mdx index bd6fc924..08d2d736 100644 --- a/zh/agent-quickstart.mdx +++ b/zh/agent-quickstart.mdx @@ -1,131 +1,187 @@ --- -title: Agent 快速开始 - 在任意 AI Agent 中连接 AIsa -description: >- - 面向 Agent 的简短导航指南，通过明确的确认和验证边界连接 AIsa 模型、API 和 Skills。 +title: "把 Agent 连接到 AIsa" +description: "安装 AIsa Skill，登录，然后开始使用工具。" --- -当用户要求 AI Agent 在 OpenClaw、Hermes Agent、Claude Code、Cursor、Codex 或其他可调用工具的助手环境中连接、配置或使用 AIsa 时，可将这份由 AIsa 编写的页面作为导航。 +把下面这句英文交给你正在使用的 Agent。你不需要先准备 API Key，也不需要先填写任务占位符。 -本页用于定位相关技术来源，不是独立证据。阅读本页不代表用户授权 Agent 修改其环境或发起计费请求。 +## 复制接入提示词 -目标：让 Agent 走到**最小且可验证**的下一步，而不是一次性加载完整文档索引。 - - -## 重要：付费和高成本 API 的先批准后执行合同 - -该合同适用于每一个付费、动态计价或可能高成本的 API endpoint，无论它是直接调用、通过 Agent Skill，还是通过 MCP 数据工具调用。 - -```xml - +```txt +Set up AIsa using https://aisa.one/docs/agent-quickstart.md. ``` -**典型场景 — SimilarWeb：** 请读取匹配 endpoint 的 [`x-aisa-pricing`](https://aisa.one/openapi.yaml) 元数据；只有请求可界定时才计算成本，并在数据调用前取得明确批准。 +可以在同一句话后面加上 `Then use AIsa to …`。如果没有，Agent 会先完成接入，再问你想做什么。 -## 最小设置事实 + +接入流程只负责安装和登录，不等于批准消费。你可以在 **AIsa is connected.** 之后停下。 + -AIsa 提供两类端点： +## 接下来会发生什么 -| 用途 | 端点 | -| --- | --- | -| OpenAI 兼容聊天、模型路由、SDK | `https://api.aisa.one/v1` | -| AIsa 数据 API 与非聊天能力 API | `https://api.aisa.one/apis/v1` | + + + 如果当前环境可以运行终端命令，Agent 会安装一个官方 AIsa Skill，并复用或安装 `@aisa-one/cli`。 + + + `aisa login` 会打开 AIsa 登录页。CLI 会自动签发并保存密钥。你不必从控制台复制 Key。 + + + 真实的已认证读取成功后，Agent 会报告 **AIsa is connected.** 然后继续你的任务，或选一个轻量例子。 + + -大多数模型客户端只需要： +如果 Agent 无法运行 CLI 命令，就改为通过远程 MCP 和浏览器 OAuth 连接 AIsa。这条路径不要求先运行 `npx`。 -```txt -base_url: https://api.aisa.one/v1 -api_key: $AISA_API_KEY +--- + +## Agent 接入步骤 + +你正在把当前环境连接到 AIsa。下面就是 bootstrap。**如果你已经在读这些步骤，不要再抓取同一个 URL，也不要重复安装同一个 Skill。** + +不要在这里加载完整文档索引、OpenAPI 目录或 Skill 正文。Skill 文件可用后，再读它获取常驻工作流规则。 + +### 1. 识别环境 + +1. 识别当前 Agent / harness。 +2. 若已有可用的 AIsa 连接，直接复用：官方 `aisa` Skill 加上有效的 CLI 认证，或已连接且能列出下方四个 Router 工具的 AIsa MCP 会话。 +3. 只要当前环境能运行终端或 CLI 命令，就优先走 CLI。任意可用 shell 都可以，包括 PowerShell。不要求必须是 Bash。 +4. 没有可用终端 / CLI，或用户明确选择 MCP 时，走 MCP。 +5. MCP 路径不要求 Node.js 或 `npx`。CLI 路径如果缺少 `npm`/`npx`，安装 Node.js 18+，或改走 MCP。 + +不要安装全部 Skill、全部 Agent 目标，也不要改无关的默认模型设置。 + +### 2. CLI 路径（默认） + +#### 安装一个官方 Skill + +来源：[AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills)。Slug：`aisa`。权威文件：`search-research/aisa/SKILL.md`。 + +用 Vercel skills 安装器，只安装到**当前** harness： + +```sh +npx skills add AIsa-team/agent-skills --skill aisa --agent codex --global ``` -API key 作为 Bearer token 使用。不要打印、记录、提交或硬编码密钥。优先使用环境变量或 Agent runtime 的 secret store。 +把 `--agent` 改成当前 harness（例如 `codex`、`claude-code`、`cursor`）。个人通用接入建议 `--global`。只有用户要求限制在当前仓库时，才用 project scope。 + +- 不要使用 `--all`、`--agent '*'` 或 `--skill '*'`。 +- 仅在本次安装已被授权、且来源/目标清楚时使用 `--yes`。 +- 如果官方 `aisa` Skill 已经存在，就复用。不要覆盖用户的同名自定义 Skill。 +- **不要**把 `aisa skills install` 当作默认安装方式。 +- 文件落盘后，**在当前会话读取并继续**。不要仅仅因为“需要重启”就停住。如果当前客户端必须新开会话才能加载新 Skill，说明这一点，并继续使用你已经能运行的 CLI 命令。 -```bash -export AISA_API_KEY="YOUR_AISA_API_KEY" +#### 安装或复用 CLI + +安装或复用 npm 包 `@aisa-one/cli`。已验证基线：**0.5.0 或更高**。不要降级现有 CLI。Skill 版本不必与 CLI 版本相等。 + +确认存在 `search`、`schema`、`quote`、`call`（`aisa --help` 或 `aisa manifest`）。参数、JSON 形状和示例以 `aisa --help` 为准，不要猜目录。 + +```sh +npm install -g @aisa-one/cli +aisa --version ``` -如果用户还没有提供 key，请说明到哪里创建，而不是编造一个看似真实的占位值。 +#### 登录 -请选择当前模型支持的 endpoint。通过[模型目录](/zh/guides/models)或对应 API reference 确认，不要根据模型名称猜测应使用 `chat/completions`、`responses`、`messages` 还是媒体 endpoint。 +1. 复用现有认证。如果已存储的 CLI 密钥或 `AISA_API_KEY` 已经可用，不要再登录。 +2. 未登录时运行 `aisa login`，让用户完成浏览器 OAuth。CLI 会签发并保存 CLI 密钥。用户不必打开 API Keys 页面，也不必粘贴 Key。 +3. `aisa login --no-browser` 仅用于 SSH / 本机无浏览器、且有交互 TTY 的情况。它不是静默无头登录。 +4. `--key` / `AISA_API_KEY` 用于自动化或高级用法，不是本 Quickstart 的前置步骤。 +5. 永远不要打印、记录或提交原始密钥。不要改用户的默认模型或其他无关客户端配置。 +6. `AISA_API_KEY` 优先于已存储密钥。两者冲突时说明两个来源，不要盲目取消环境变量或覆盖配置。 +7. `aisa whoami` **只检查本地**。它不能证明远端凭证仍然有效。 +8. 用真实的已认证读取验证，例如 `aisa balance`。只有成功后才报告 **AIsa is connected.** +9. 凭证失效 → 重新运行 `aisa login`。余额为 0 → 去充值，不是缺 Key。 +10. 登录或 mint 失败时，展示错误和下一步。不要让用户去找 API Key，也不要用反复重装来“修复”所有问题。 -## 选择一条路径 +### 3. MCP 路径（无 CLI，或用户选择 MCP） -先判断用户要做什么，然后只读对应文档。 +连接 **AIsa 统一 Router**。不要使用 `https://mcp.aisa.one/servers` 的领域目录，也不要把默认 `aisa connect` 的 web-search 服务器当成这个 Router。 -| 用户想做 | 下一步阅读 | +| 字段 | 值 | | --- | --- | -| 基础账号/API key 设置 | [AIsa 入门](/zh/guides/getting-started-with-aisa)、[认证](/zh/guides/authentication) | -| 把 AIsa 当作 LLM provider | [模型](/zh/guides/models)、[Chat Completions API](/api-reference/chat/post_chat-completions) | -| 在 Hermes Agent 中使用 AIsa | [在 Hermes Agent 中使用 AIsa](/zh/guides/tutorials/use-aisa-in-hermes-agent) | -| 在 OpenClaw 中使用 AIsa | [在 OpenClaw 中使用 AIsa](/zh/guides/tutorials/use-aisa-in-openclaw) | -| 使用 Agent Skills | [Agent Skills](/zh/agent-skills)、[Agent Skills 快速开始](/zh/agent-skills/quickstart) | -| 搜索或研究网页 | [Tavily Search](/zh/agent-skills/tavily-search)、[Tavily Extract](/zh/agent-skills/tavily-extract)、[Smart Search](/zh/agent-skills/smart-search) | -| 深度研究 | [Perplexity Deep Research](/zh/agent-skills/perplexity-research)、[Perplexity Deep Research API](/api-reference/perplexity/post_perplexity-sonar-deep-research) | -| 学术搜索 | [Scholar Search](/zh/agent-skills/scholar-search)、[Scholar API](/api-reference/scholar/post_scholar-search-scholar) | -| 使用特定 REST API | [API 参考](/zh/api-reference)，然后只打开需要的具体 endpoint 页 | - -## Agent 行为准则 - -- 只有目标路径不清楚时，才问一个澄清问题。 -- 只加载完成任务所需的最小文档集合。 -- 不要打开无关 API 页面。 -- 简短总结和链接足够时，不要把大段文档粘贴进对话。 -- 让所选模型与有明确记录的 endpoint 匹配，不要根据名称推断路由支持情况。 -- 修改文件、安装软件或发送计费请求前，先说明操作并获得用户确认。 -- 声称配置可用前，完成下面对应的检查。 -- 对于密钥，只验证存储方式，不展示密钥本身。 - -## 验证设置 - -先通过只读请求检查网络和认证，不调用模型： - -```bash -curl --silent --show-error --fail \ - --output /dev/null \ - --write-out "HTTP %{http_code}\n" \ - https://api.aisa.one/v1/models \ - -H "Authorization: Bearer $AISA_API_KEY" -``` +| 名称 | AIsa | +| 服务器 URL | `https://tools.aisa.one/mcp` | +| 传输 | Streamable HTTP | +| 认证 | OAuth（让客户端自动发现端点；需要选择时选 OAuth） | -`HTTP 200` 表示 API 已接受该 key 并返回模型目录。`401` 或 `403` 表示认证或访问权限存在问题。此检查不能证明某个具体模型支持客户端使用的请求协议。 +实际步骤： -用户选定模型并同意可能产生费用的请求后，再执行对应 API reference 中最小的示例请求。不要仅根据文档就声称设置已经可用。 +1. 打开当前客户端的 MCP / connectors 设置。 +2. 按上表添加远程服务器。不要编造各客户端专用命令。 +3. 在浏览器完成登录。由客户端保存并刷新 token。不需要 API Key、粘贴 Bearer，或复制 access token。 +4. 回到 Agent。如果客户端要求，刷新或重新连接。 +5. 若客户端支持原生安装或上传 Skill，按同样的 canonical `aisa` Skill 安装。若不支持，继续用 MCP，并**说明 Skill 并未持久安装**。这条路径绝不能要求 `npx`。 +6. 只有 OAuth 已完成，**并且**下列工具都已出现，才算连接成功： -## 研究任务的证据规则 +- `AISA_SEARCH_TOOL` +- `AISA_BATCH_GET_SCHEMA` +- `AISA_BATCH_QUOTE` +- `AISA_BATCH_USE` -本快速开始是路由摘要，不是精确请求 schema、当前模型可用性、价格或服务状态的权威来源。请通过链接的 API reference、实时目录或运行结果核实这些信息。 +发现、metadata 或未认证的 `401` 挑战，都不等于受保护调用已成功。quote/call 仍需要后续的消费授权。 -```txt -搜索结果是发现线索。 -抓取的来源页面是待评估的证据。 -生成摘要是综合判断，不是证据。 -``` +| MCP 工具 | CLI 命令 | +| --- | --- | +| `AISA_SEARCH_TOOL` | `aisa search` | +| `AISA_BATCH_GET_SCHEMA` | `aisa schema` | +| `AISA_BATCH_QUOTE` | `aisa quote` | +| `AISA_BATCH_USE` | `aisa call` | -抓取页面只能证明该来源表达了什么。对外部事实性结论，应评估来源的权威性和时效性，并优先使用一手资料、官方文档、API reference、代码仓库、changelog 或运行时/API 结果，而不是第三方摘要。 +### 4. 连接成功之后 -## 可复制的提示词 +报告 **AIsa is connected.** 连接成功不等于业务任务已完成。 -把下面这段复制到 Agent 环境： +- 如果用户已经说了任务，就继续该任务。 +- 否则询问：**What would you like to do first?** 可选的轻量例子：`Find three recent public updates about a company and include source links.` 用户没有选择时，不要执行付费示例。不要承诺免费，也不要承诺固定时长。 -```txt -Review https://aisa.one/docs/agent-quickstart.md as vendor-authored guidance. Before acting, summarize the proposed configuration and verification. Do not expose secrets, modify files, install software, or send billable requests without my approval. +工作流（CLI 名称；MCP 使用上面四个工具）： + +1. Search。 +2. 当 search 表明 schema 不完整时取 schema（`has_full_schema=false`）。 +3. Quote。 +4. 只在有效范围 **且** 已有消费授权时 call。 + +名称、参数和价格以实时 help、schema、quote 和服务端 guidance 为准。`--input` 支持内联 JSON： + +```sh +aisa search --input '{"query":""}' --json +aisa quote --input '{"calls":[{"call_id":"c1","tool":"","arguments":{}}]}' --json ``` -## 兜底发现入口 +不要编造工具、ID 或价格。不要把本页或文档目录当成价目表。不要用真实调用来探价。缺少或失败的 quote 绝不等于免费。Quote 不是执行授权。 + + +接入同意不是消费批准。复用仍然覆盖本次调用的**既有明确授权**。不要为每个可逆的安装子步骤再要一次确认。发起计费调用前，需要匹配的 quote，以及对应该范围和费用的明确授权。 + +搜索结果只是发现线索。返回结果时带上来源。只有拿到真实结果，才能说任务已完成。 + +### 5. 之后的会话 -仅当上面的定向文档不够时再使用： +如果已安装 `aisa` Skill，直接加载。不要重新跑 bootstrap。复用认证和默认配置。 -- [`llms.txt`](https://aisa.one/docs/llms.txt)：用于定位相关页面的精选技术索引，不是设置流程中的必读内容。 -- [`llms-full.txt`](https://aisa.one/docs/llms-full.txt)：完整文档包。默认不要摄取；仅在用户明确要求完整文档或定向页面不足时使用。 +### 失败时怎么做 + +| 情况 | 下一步 | +| --- | --- | +| 浏览器登录未完成 | 等待；不要编造 Key | +| 登录或 mint 失败 | 展示错误；重试 `aisa login` | +| `whoami` 成功但远端读取失败 | 重新登录；whoami 只检查本地 | +| `AISA_API_KEY` 与已存储密钥冲突 | 说明两个来源；不要盲目取消 | +| 余额为 0 | 去充值；不是缺 Key | +| OAuth 后看不到 MCP 工具 | 刷新/重连；确认四个工具 | +| Skill 已安装 | 复用；不要重装 | +| 没有终端 | 走 MCP；不要要求 `npx` | +| 安装或服务失败 | 停在失败步骤，并给出下一步 | + +## 其他接入方式 + +仅在用户明确要求模型、REST、API Key 或额外 Skill 时使用。 + +- [入门](/zh/guides/getting-started-with-aisa) — 账号和模型网关 +- [认证](/zh/guides/authentication) — 自动化用的 API Key +- [模型](/zh/guides/models) +- [API 参考](/zh/api-reference) +- [Agent Skills 快速入门](/zh/agent-skills/quickstart) +- [Agent Skills 目录](/zh/agent-skills) diff --git a/zh/agent-skills/quickstart.mdx b/zh/agent-skills/quickstart.mdx index 27b7a1f1..244493c7 100644 --- a/zh/agent-skills/quickstart.mdx +++ b/zh/agent-skills/quickstart.mdx @@ -1,173 +1,109 @@ --- title: "Agent Skills 快速入门" -description: "安装 AIsa CLI，使用 API Key 完成身份认证，并将可复用的 Agent Skills 添加到 Claude Code、Cursor、Codex、OpenClaw 和其他受支持的智能体。" +description: "安装官方 AIsa Skill，登录，然后在你的 Agent 里开始使用 AIsa。" privacy: view: "public" --- -本指南将带你在大约五分钟内从零开始安装并使用一个 Skill。 +默认路径是 **一个官方 AIsa Skill** 加上 CLI。把下面这句英文交给你正在使用的 Agent。你不需要先准备 API Key，也不需要先填写任务占位符。 -## 前置条件 - -- Node.js 18 或更高版本 -- AIsa 账户和 API Key——[在 aisa.one 注册](https://console.aisa.one/)（新账户包含 2 美元免费额度） -- 至少安装一个受支持的 AI 编程智能体：Claude Code、Cursor、GitHub Copilot、Windsurf、Codex、Gemini CLI 或 OpenClaw - ---- - -## 第 1 步：安装 AIsa CLI - -```bash -npm install -g @aisa-one/cli -``` - -验证是否可用： - -```bash -aisa --version -``` - ---- - -## 第 2 步：身份认证 - -```bash -aisa login --key YOUR_AISA_API_KEY +```txt +Set up AIsa using https://aisa.one/docs/agent-quickstart.md. ``` -也可以设置环境变量，它的优先级高于已存储的密钥： +完整的 Agent bootstrap——环境识别、登录复用、验证、消费授权和失败处理——见 [Agent 快速开始](/zh/agent-quickstart)。本页与该安装方式和无终端 MCP 分支保持一致，避免两个入口互相矛盾。 -```bash -export AISA_API_KEY="YOUR_AISA_API_KEY" -``` + +如果你已经在执行这些步骤，不要再抓取 Quickstart URL，也不要重复安装同一个 `aisa` Skill。 + -随时检查身份认证状态： +## 安装官方 AIsa Skill -```bash -aisa whoami -``` +来源：[AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills)。Slug：`aisa`。权威文件：`search-research/aisa/SKILL.md`。 ---- - -## 第 3 步：浏览可用 Skills +如果当前环境可以运行终端或 CLI 命令（任意 shell，不限于 Bash），用 Vercel 安装器把 **一个** Skill 装到 **当前** harness： -```bash -aisa skills list +```sh +npx skills add AIsa-team/agent-skills --skill aisa --agent codex --global ``` -该命令会从 [agent-skills](https://github.com/AIsa-team/agent-skills) 技能仓库拉取实时目录，并打印每个 Skill 的名称、Slug 和说明。 - -按关键词搜索： - -```bash -aisa skills search "finance" -aisa skills search "search" -``` - -安装前查看某个 Skill 的完整详情： - -```bash -aisa skills show market -``` +把 `--agent` 改成当前 harness（例如 `codex`、`claude-code`、`cursor`）。个人通用接入建议 `--global`。只有用户要求限制在当前仓库时，才用 project scope。 ---- +- 不要使用 `--all`、`--agent '*'` 或 `--skill '*'`。 +- 仅在本次安装已被授权、且来源/目标清楚时使用 `--yes`。 +- 如果官方 `aisa` Skill 已经存在，就复用。不要覆盖用户的同名自定义 Skill。 +- **不要**把 `aisa skills install` 当作连接 AIsa 的默认方式。 +- 文件落盘后，**在当前会话读取并继续**。不要仅仅因为“需要重启”就停住。 -## 第 4 步：安装 Skill +## 安装或复用 CLI，然后登录 -```bash -aisa skills install search +```sh +npm install -g @aisa-one/cli +aisa --version +aisa login ``` -CLI 会自动检测你机器上的每个受支持智能体，并将 Skill 写入各自的 Skills 目录。你会看到每个智能体对应的一行确认信息： +如果已经安装了 `@aisa-one/cli`，直接复用。已验证基线：**0.5.0 或更高**。不要降级。 -```text -✓ ~/.claude/skills/ (claude) -✓ ~/.cursor/skills/ (cursor) -Skill 'search' installed to 2 agent(s) -``` +`aisa login` 会打开浏览器 OAuth，并签发保存到本地的 CLI 密钥。用户不必从控制台复制 Key。`--key` / `AISA_API_KEY` 用于自动化，不是这条路径。 -如果只想为特定智能体安装： +- 永远不要打印原始密钥。 +- `AISA_API_KEY` 优先于已存储密钥。两者冲突时说明两个来源，不要盲目取消环境变量。 +- `aisa whoami` 只检查本地。在报告 **AIsa is connected.** 之前，用真实的已认证读取验证，例如 `aisa balance`。 +- 接入不等于批准消费。 -```bash -aisa skills install search --agent claude -``` +随后在有效范围和消费授权内使用 `aisa search` → 必要时 `aisa schema` → `aisa quote` → `aisa call`。参数和价格来自 help/schema/quote，而不是本页。`--input` 支持内联 JSON。 -如果想忽略自动检测结果，为所有受支持的智能体安装： +## 没有终端，或你更想用 MCP -```bash -aisa skills install search --agent all -``` - ---- +如果当前 Agent 无法运行 CLI 命令，或用户要求 MCP，不要先要求 `npx`。把 AIsa 统一 Router 添加为远程 Streamable HTTP MCP 服务器： -## 第 5 步：使用 Skill +| 字段 | 值 | +| --- | --- | +| 名称 | AIsa | +| 服务器 URL | `https://tools.aisa.one/mcp` | +| 传输 | Streamable HTTP | +| 认证 | OAuth | -在智能体中打开一个**新会话**。Skills 会在会话启动时加载，而不是在会话进行途中加载。然后让智能体执行该 Skill 能处理的任务： +打开当前客户端的 MCP 设置，添加该服务器，完成浏览器登录，必要时返回后刷新/重连。由客户端发现端点并保存/刷新 token。不需要手工 Key。 -```text -Search the web for the latest news on AI agent frameworks and summarise the top three stories. -``` +**不要**把 `https://mcp.aisa.one/servers` 或默认 `aisa connect` 的 web-search 服务器当成这个 Router。 -智能体会读取 `search` Skill 的 `description`，加载完整的 `SKILL.md` 指令，并使用你的密钥调用 AIsa 搜索 API。 +如果客户端支持原生安装 Skill，安装同一个 canonical `aisa` Skill。如果不支持，继续用 MCP，并说明 Skill **并未持久安装**。 ---- +只有 OAuth 已完成，**并且**这些工具都已出现，才算连接成功：`AISA_SEARCH_TOOL`、`AISA_BATCH_GET_SCHEMA`、`AISA_BATCH_QUOTE`、`AISA_BATCH_USE`。仅完成发现不等于受保护的业务调用已成功。 -## 第 6 步：安装多个 Skills +## 连接成功之后 -```bash -aisa skills install market -aisa skills install twitter -aisa skills install media-gen -``` +除非用户已经说了任务，否则询问 **What would you like to do first?** 可选例子：`Find three recent public updates about a company and include source links.` 不要承诺免费。 -安装多个 Skills 后，智能体可以根据具体任务自动选择合适的 Skill，无需你指定使用哪一个。 +之后的会话应加载同一个 `aisa` Skill，不要重新跑 setup。 ---- +## 可选：从目录安装更多 Skill -## 管理已安装的 Skills +AIsa 连接成功后，可以浏览额外的领域 Skill。这不是默认接入路径。 -```bash -# List skills available in the registry +```sh aisa skills list - -# Remove a skill from all agent directories -aisa skills remove market - -# Remove from a specific agent only +aisa skills search "finance" +aisa skills show market +aisa skills install market --agent cursor aisa skills remove market --agent cursor ``` ---- +不要安装目录里的全部 Skill，也不要在用户未要求时对所有 Agent 安装。 ## 创建自己的 Skill -使用模板搭建一个新 Skill： - -```bash -# Default blank template +```sh aisa skills init my-skill - -# Start from a specific template -aisa skills init my-skill --template finance # finance template -aisa skills init my-skill --template search # search template -aisa skills init my-skill --template llm # LLM gateway template -aisa skills init my-skill --template twitter # Twitter template -aisa skills init my-skill --template video # video generation template -``` - -这会创建一个 `my-skill/` 文件夹，其中包含预填充的 `SKILL.md`。编辑 `name`、`description` 和正文，描述该 Skill 的能力。然后像安装其他 Skill 一样安装它： - -```bash -aisa skills install ./my-skill # install from local path +aisa skills install ./my-skill ``` -如需与社区分享你的 Skill，请向 [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills) 提交 Pull Request。 - ---- +编辑 `SKILL.md`，然后从本地路径安装。如需分享，向 [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills) 提交 Pull Request。编写规则见 [标准](/zh/agent-skills/standards)。 ## 下一步 -- [Agent Skills](/zh/agent-skills)：浏览包含说明和 GitHub 链接的完整 Skill 目录 -- [标准](/zh/agent-skills/standards)：了解 `SKILL.md` 文件的工作方式，以及如何编写自己的 Skill -- [预构建 Skills 与自定义 Skills](/zh/guides/learn/agent-skills-vs-tools)：了解什么时候使用技能仓库中的 Skill，什么时候构建自己的 Skill -- 有问题？[联系我们](mailto:developer@aisa.one) +- [Agent 快速开始](/zh/agent-quickstart) — 完整接入、登录、MCP 和消费规则 +- [Agent Skills](/zh/agent-skills) — 目录 +- [标准](/zh/agent-skills/standards) — `SKILL.md` 如何工作 From c7ed3cd3be92030ca11ed14b7a2dacb157158a58 Mon Sep 17 00:00:00 2001 From: idan Date: Wed, 9 Sep 2026 18:57:58 +0800 Subject: [PATCH 02/18] docs: escape AISA_MODEL= in hermes CIO install MDX Raw was parsed as JSX and blocked Mintlify preview. Present on origin/main. --- agents/aisa-cio/INSTALL-hermes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agents/aisa-cio/INSTALL-hermes.mdx b/agents/aisa-cio/INSTALL-hermes.mdx index f2e0b7eb..5de62333 100644 --- a/agents/aisa-cio/INSTALL-hermes.mdx +++ b/agents/aisa-cio/INSTALL-hermes.mdx @@ -16,7 +16,7 @@ AI Chief Investment Officer — live multi-market portfolio valuation, deep stoc |---|---|---| | `AISA_API_KEY` | required | AISA multi-model gateway — default LLM + the agent-skills data skills (marketpulse / multi-source-search / prediction-market-data / aisa-twitter-api / last30days) | | `SEC_IDENTITY` | optional | Your own name + email, e.g. "Jane Doe jane@example.com". The SEC requires every automated request for filings to declare a real contact, and caps each declared identity at 10 requests/second. Not an API key — there is nothing to sign up for, and the value is sent verbatim without validation. Used only by the optional sec-filings skill. In a hermes/openclaw .env it MUST be quoted, since it contains spaces and the file is shell-sourced: SEC_IDENTITY="Jane Doe jane@example.com" — degrade: sec-filings skill (deep SEC filing research) is unavailable; marketpulse still covers prices and quick financials | -| `AISA_MODEL` | optional | Reasoning model id for the last30days 30-day scan, e.g. deepseek-v4-pro. Add it to ~/.aisa/credentials as AISA_MODEL=. — degrade: last30days refuses to run without a model pin; every other skill is unaffected | +| `AISA_MODEL` | optional | Reasoning model id for the last30days 30-day scan, e.g. deepseek-v4-pro. Add it to ~/.aisa/credentials as `AISA_MODEL=`. — degrade: last30days refuses to run without a model pin; every other skill is unaffected | Keys live in `~/.aisa/credentials` (one `KEY=VALUE` per line, `chmod 600`) — the shared convention across all AIsa install targets. The installer resolves From 72b76d1d5face36e84ba18d4c9a961bb6ed88b6c Mon Sep 17 00:00:00 2001 From: idan Date: Wed, 9 Sep 2026 19:06:13 +0800 Subject: [PATCH 03/18] docs: set npx skills Node 22.20 floor; restore hermes MDX Unpinned skills 1.5.25 engines require Node.js >=22.20.0; keep a working CLI on its Node 18+ floor. Restore INSTALL-hermes.mdx to origin/main baseline. Full-site raw parse failures stay documented, not cleaned. --- agent-quickstart.mdx | 6 +++--- agent-skills/quickstart.mdx | 4 ++-- agents/aisa-cio/INSTALL-hermes.mdx | 2 +- zh/agent-quickstart.mdx | 6 +++--- zh/agent-skills/quickstart.mdx | 4 ++-- 5 files changed, 11 insertions(+), 11 deletions(-) diff --git a/agent-quickstart.mdx b/agent-quickstart.mdx index c5c5dfc6..e10be5c0 100644 --- a/agent-quickstart.mdx +++ b/agent-quickstart.mdx @@ -47,7 +47,7 @@ Do not load the full docs index, OpenAPI catalog, or Skill body here. After the 2. Reuse a working AIsa connection when one already exists: the official `aisa` skill plus valid CLI auth, or a connected AIsa MCP session with the four router tools listed below. 3. Prefer the CLI path when this environment can run terminal or CLI commands. Any working shell counts, including PowerShell. Bash is not required. 4. Use the MCP path when there is no usable terminal/CLI, or the user explicitly prefers MCP. -5. Do not require Node.js or `npx` on the MCP path. On the CLI path, if `npm`/`npx` are missing, install Node.js 18+ or switch to MCP. +5. Do not require Node.js or `npx` on the MCP path. Unpinned `npx skills` needs Node.js **22.20.0+** (`skills` 1.5.25 `engines`; verified on 22.22). `@aisa-one/cli` may keep its Node.js **18+** floor — do not replace a working older CLI. If the installer cannot run, use Node 22.20.0+ for that command only, or switch to MCP. Do not install every skill, every agent target, or unrelated model settings. @@ -57,7 +57,7 @@ Do not install every skill, every agent target, or unrelated model settings. Source: [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills). Slug: `aisa`. Canonical file: `search-research/aisa/SKILL.md`. -Use the Vercel skills installer, targeted at **this** harness only: +Use the Vercel skills installer, targeted at **this** harness only. It needs Node.js 22.20.0+; that is not a reason to replace a working CLI. ```sh npx skills add AIsa-team/agent-skills --skill aisa --agent codex --global @@ -73,7 +73,7 @@ Adapt `--agent` to the current harness (for example `codex`, `claude-code`, `cur #### Install or reuse the CLI -Install or reuse npm package `@aisa-one/cli`. Verified baseline: **0.5.0 or later**. Do not downgrade an existing CLI. The skill version does not need to match the CLI version. +Install or reuse npm package `@aisa-one/cli`. Verified baseline: **0.5.0 or later**. Do not downgrade an existing CLI. A working CLI on Node.js 18+ can stay; do not replace it to match the `npx skills` Node floor. The skill version does not need to match the CLI version. Confirm `search`, `schema`, `quote`, and `call` exist (`aisa --help` or `aisa manifest`). Take flags, JSON shapes, and examples from `aisa --help` — not from a guessed catalog. diff --git a/agent-skills/quickstart.mdx b/agent-skills/quickstart.mdx index d0940bea..6a1589b3 100644 --- a/agent-skills/quickstart.mdx +++ b/agent-skills/quickstart.mdx @@ -21,7 +21,7 @@ Do not fetch the Quickstart URL again if you are already following these steps. Source: [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills). Slug: `aisa`. Canonical file: `search-research/aisa/SKILL.md`. -If this environment can run terminal or CLI commands (any shell, not only Bash), install **one** skill into the **current** harness with the Vercel installer: +If this environment can run terminal or CLI commands (any shell, not only Bash), install **one** skill into the **current** harness with the Vercel installer. Unpinned `npx skills` needs Node.js **22.20.0+** (`skills` 1.5.25 `engines`; verified on 22.22). That is not a reason to replace a working `@aisa-one/cli`. ```sh npx skills add AIsa-team/agent-skills --skill aisa --agent codex --global @@ -43,7 +43,7 @@ aisa --version aisa login ``` -Reuse `@aisa-one/cli` if it is already installed. Verified baseline: **0.5.0 or later**. Do not downgrade. +Reuse `@aisa-one/cli` if it is already installed. Verified baseline: **0.5.0 or later**. Do not downgrade. A working CLI on Node.js 18+ can stay; do not replace it to match the `npx skills` Node floor. `aisa login` opens browser OAuth and mints a stored CLI key. The user should not copy a key from the dashboard. `--key` / `AISA_API_KEY` are for automation, not this path. diff --git a/agents/aisa-cio/INSTALL-hermes.mdx b/agents/aisa-cio/INSTALL-hermes.mdx index 5de62333..f2e0b7eb 100644 --- a/agents/aisa-cio/INSTALL-hermes.mdx +++ b/agents/aisa-cio/INSTALL-hermes.mdx @@ -16,7 +16,7 @@ AI Chief Investment Officer — live multi-market portfolio valuation, deep stoc |---|---|---| | `AISA_API_KEY` | required | AISA multi-model gateway — default LLM + the agent-skills data skills (marketpulse / multi-source-search / prediction-market-data / aisa-twitter-api / last30days) | | `SEC_IDENTITY` | optional | Your own name + email, e.g. "Jane Doe jane@example.com". The SEC requires every automated request for filings to declare a real contact, and caps each declared identity at 10 requests/second. Not an API key — there is nothing to sign up for, and the value is sent verbatim without validation. Used only by the optional sec-filings skill. In a hermes/openclaw .env it MUST be quoted, since it contains spaces and the file is shell-sourced: SEC_IDENTITY="Jane Doe jane@example.com" — degrade: sec-filings skill (deep SEC filing research) is unavailable; marketpulse still covers prices and quick financials | -| `AISA_MODEL` | optional | Reasoning model id for the last30days 30-day scan, e.g. deepseek-v4-pro. Add it to ~/.aisa/credentials as `AISA_MODEL=`. — degrade: last30days refuses to run without a model pin; every other skill is unaffected | +| `AISA_MODEL` | optional | Reasoning model id for the last30days 30-day scan, e.g. deepseek-v4-pro. Add it to ~/.aisa/credentials as AISA_MODEL=. — degrade: last30days refuses to run without a model pin; every other skill is unaffected | Keys live in `~/.aisa/credentials` (one `KEY=VALUE` per line, `chmod 600`) — the shared convention across all AIsa install targets. The installer resolves diff --git a/zh/agent-quickstart.mdx b/zh/agent-quickstart.mdx index 08d2d736..0d2caf5d 100644 --- a/zh/agent-quickstart.mdx +++ b/zh/agent-quickstart.mdx @@ -47,7 +47,7 @@ Set up AIsa using https://aisa.one/docs/agent-quickstart.md. 2. 若已有可用的 AIsa 连接，直接复用：官方 `aisa` Skill 加上有效的 CLI 认证，或已连接且能列出下方四个 Router 工具的 AIsa MCP 会话。 3. 只要当前环境能运行终端或 CLI 命令，就优先走 CLI。任意可用 shell 都可以，包括 PowerShell。不要求必须是 Bash。 4. 没有可用终端 / CLI，或用户明确选择 MCP 时，走 MCP。 -5. MCP 路径不要求 Node.js 或 `npx`。CLI 路径如果缺少 `npm`/`npx`，安装 Node.js 18+，或改走 MCP。 +5. MCP 路径不要求 Node.js 或 `npx`。未固定版本的 `npx skills` 需要 Node.js **22.20.0+**（`skills` 1.5.25 的 `engines`；已在 22.22 验证）。`@aisa-one/cli` 仍可沿用 Node.js **18+** 下限——不要为了安装器替换已经能用的旧 CLI。如果安装器跑不起来，只为该命令使用 Node 22.20.0+，或改走 MCP。 不要安装全部 Skill、全部 Agent 目标，也不要改无关的默认模型设置。 @@ -57,7 +57,7 @@ Set up AIsa using https://aisa.one/docs/agent-quickstart.md. 来源：[AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills)。Slug：`aisa`。权威文件：`search-research/aisa/SKILL.md`。 -用 Vercel skills 安装器，只安装到**当前** harness： +用 Vercel skills 安装器，只安装到**当前** harness。它需要 Node.js 22.20.0+；这不是替换已经能用的 CLI 的理由。 ```sh npx skills add AIsa-team/agent-skills --skill aisa --agent codex --global @@ -73,7 +73,7 @@ npx skills add AIsa-team/agent-skills --skill aisa --agent codex --global #### 安装或复用 CLI -安装或复用 npm 包 `@aisa-one/cli`。已验证基线：**0.5.0 或更高**。不要降级现有 CLI。Skill 版本不必与 CLI 版本相等。 +安装或复用 npm 包 `@aisa-one/cli`。已验证基线：**0.5.0 或更高**。不要降级现有 CLI。已经能在 Node.js 18+ 上运行的 CLI 可以保留，不要为了匹配 `npx skills` 的 Node 下限而替换它。Skill 版本不必与 CLI 版本相等。 确认存在 `search`、`schema`、`quote`、`call`（`aisa --help` 或 `aisa manifest`）。参数、JSON 形状和示例以 `aisa --help` 为准，不要猜目录。 diff --git a/zh/agent-skills/quickstart.mdx b/zh/agent-skills/quickstart.mdx index 244493c7..44bb8e74 100644 --- a/zh/agent-skills/quickstart.mdx +++ b/zh/agent-skills/quickstart.mdx @@ -21,7 +21,7 @@ Set up AIsa using https://aisa.one/docs/agent-quickstart.md. 来源：[AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills)。Slug：`aisa`。权威文件：`search-research/aisa/SKILL.md`。 -如果当前环境可以运行终端或 CLI 命令（任意 shell，不限于 Bash），用 Vercel 安装器把 **一个** Skill 装到 **当前** harness： +如果当前环境可以运行终端或 CLI 命令（任意 shell，不限于 Bash），用 Vercel 安装器把 **一个** Skill 装到 **当前** harness。未固定版本的 `npx skills` 需要 Node.js **22.20.0+**（`skills` 1.5.25 的 `engines`；已在 22.22 验证）。这不是替换已经能用的 `@aisa-one/cli` 的理由。 ```sh npx skills add AIsa-team/agent-skills --skill aisa --agent codex --global @@ -43,7 +43,7 @@ aisa --version aisa login ``` -如果已经安装了 `@aisa-one/cli`，直接复用。已验证基线：**0.5.0 或更高**。不要降级。 +如果已经安装了 `@aisa-one/cli`，直接复用。已验证基线：**0.5.0 或更高**。不要降级。已经能在 Node.js 18+ 上运行的 CLI 可以保留，不要为了匹配 `npx skills` 的 Node 下限而替换它。 `aisa login` 会打开浏览器 OAuth，并签发保存到本地的 CLI 密钥。用户不必从控制台复制 Key。`--key` / `AISA_API_KEY` 用于自动化，不是这条路径。 From b2bb5e461ed31128b673b159e695f837572f2fcb Mon Sep 17 00:00:00 2001 From: idan Date: Wed, 9 Sep 2026 22:39:52 +0800 Subject: [PATCH 04/18] docs: lean Agent Quickstart; split connect vs skill workflow Shorten English-first onboarding, point Skills Quickstart at the canonical flow, and keep Claude/Codex MCP examples as help-sourced copyable steps. --- agent-quickstart.mdx | 151 ++++++++++++--------------------- agent-skills/quickstart.mdx | 98 ++------------------- zh/agent-quickstart.mdx | 147 +++++++++++--------------------- zh/agent-skills/quickstart.mdx | 98 ++------------------- 4 files changed, 116 insertions(+), 378 deletions(-) diff --git a/agent-quickstart.mdx b/agent-quickstart.mdx index e10be5c0..c03ceb53 100644 --- a/agent-quickstart.mdx +++ b/agent-quickstart.mdx @@ -3,7 +3,7 @@ title: "Connect your agent to AIsa" description: "Install the AIsa skill, sign in, and start using tools." --- -Give this prompt to the agent you already use. You do not need an API key or a task placeholder. +Give this prompt to the agent you already use. You do not need an API key. ## Copy setup prompt @@ -11,116 +11,95 @@ Give this prompt to the agent you already use. You do not need an API key or a t Set up AIsa using https://aisa.one/docs/agent-quickstart.md. ``` -You can append `Then use AIsa to …` in the same message. If you do not, the agent will connect first and then ask what you want to do. - - -Setup installs and signs in. It is not approval to spend. You can stop after **AIsa is connected.** - +You can append `Then use AIsa to …` in the same message. ## What happens next - If this environment can run terminal commands, the agent installs one official AIsa skill and reuses or installs `@aisa-one/cli`. + If this environment can run terminal commands, the agent installs one official AIsa skill and reuses or installs `@aisa-one/cli` 0.5.0 or later. - `aisa login` opens AIsa sign-in. The CLI mints and stores a key. You should not copy a key from the dashboard. + `aisa login` opens AIsa sign-in in your browser. You should not copy a key from the dashboard. After a real authenticated check succeeds, the agent reports **AIsa is connected.** Then continue your task, or pick a small example. -If the agent cannot run CLI commands, it connects AIsa through remote MCP and browser OAuth instead. `npx` is not required on that path. +If the agent cannot run commands, it connects AIsa through remote MCP and browser OAuth instead. `npx` is not required on that path. ---- +## Optional first task -## Agent setup +After **AIsa is connected.**, ask **What would you like to do first?** unless you already named a task. + +Example: `Find three recent public updates about a company and include source links.` Do not run a paid example unless you choose it. It is not promised free. -You are connecting this environment to AIsa. These steps are the bootstrap. If you are already reading them, **do not fetch this URL again** and **do not reinstall the same skill**. + +Setup installs and signs in. It is not approval to spend. + -Do not load the full docs index, OpenAPI catalog, or Skill body here. After the skill file is available, read that file for standing workflow rules. +--- -### 1. Detect the environment +## Agent setup -1. Identify the current agent/harness. -2. Reuse a working AIsa connection when one already exists: the official `aisa` skill plus valid CLI auth, or a connected AIsa MCP session with the four router tools listed below. -3. Prefer the CLI path when this environment can run terminal or CLI commands. Any working shell counts, including PowerShell. Bash is not required. -4. Use the MCP path when there is no usable terminal/CLI, or the user explicitly prefers MCP. -5. Do not require Node.js or `npx` on the MCP path. Unpinned `npx skills` needs Node.js **22.20.0+** (`skills` 1.5.25 `engines`; verified on 22.22). `@aisa-one/cli` may keep its Node.js **18+** floor — do not replace a working older CLI. If the installer cannot run, use Node 22.20.0+ for that command only, or switch to MCP. +Connect this environment to AIsa. If you are already reading these steps, do not fetch this URL again and do not reinstall the same skill. After the `aisa` skill is on disk, read it in this session for when to use AIsa, the four-step workflow, and spend rules. -Do not install every skill, every agent target, or unrelated model settings. +### Detect -### 2. CLI path (default) +1. Reuse a working AIsa connection: the official `aisa` skill plus valid CLI auth, or unified MCP with the four router tools below. +2. Prefer the CLI path when this environment can run terminal or CLI commands. Any working shell counts, including PowerShell. Bash is not required. +3. Use MCP when there is no usable command execution, or the user explicitly prefers MCP. Do not require Node.js or `npx` on that path. +4. Install only the official `aisa` skill for this harness. Do not change unrelated model settings. -#### Install one official skill +### CLI path -Source: [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills). Slug: `aisa`. Canonical file: `search-research/aisa/SKILL.md`. +Source: [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills). Slug: `aisa`. File: `search-research/aisa/SKILL.md`. -Use the Vercel skills installer, targeted at **this** harness only. It needs Node.js 22.20.0+; that is not a reason to replace a working CLI. +Unpinned `npx skills` needs Node.js 22.20.0+ (`skills` 1.5.25 `engines`; verified on 22.22). A working `@aisa-one/cli` on Node.js 18+ can stay. ```sh npx skills add AIsa-team/agent-skills --skill aisa --agent codex --global ``` -Adapt `--agent` to the current harness (for example `codex`, `claude-code`, `cursor`). Prefer `--global` for personal use. Use project scope only when the user asked to limit the install to this repo. - -- Do not use `--all`, `--agent '*'`, or `--skill '*'`. -- Use `--yes` only when this install is already authorized and the source/target are clear. -- If the official `aisa` skill is already present, reuse it. Do not overwrite a same-named custom skill. -- Do **not** use `aisa skills install` as the default installer. -- After the file is on disk, **read it in this session and continue**. Do not stop only to wait for a restart. If this client cannot load a newly installed skill until a new session, say that and continue with CLI commands you can already run. +Set `--agent` to this harness (`codex`, `claude-code`, `cursor`, …). Prefer `--global` unless the user asked for this repo only. Do not use `--all` or `*`. Do not use `aisa skills install` as the default. Reuse the official skill if it is already present; do not overwrite a same-named custom skill. Then read the skill and continue. -#### Install or reuse the CLI - -Install or reuse npm package `@aisa-one/cli`. Verified baseline: **0.5.0 or later**. Do not downgrade an existing CLI. A working CLI on Node.js 18+ can stay; do not replace it to match the `npx skills` Node floor. The skill version does not need to match the CLI version. - -Confirm `search`, `schema`, `quote`, and `call` exist (`aisa --help` or `aisa manifest`). Take flags, JSON shapes, and examples from `aisa --help` — not from a guessed catalog. +If `aisa` is missing: ```sh npm install -g @aisa-one/cli aisa --version ``` -#### Sign in +Reuse CLI **0.5.0 or later**. Do not downgrade. + +Sign in with `aisa login` unless a stored key or `AISA_API_KEY` already works. The CLI mints and stores a key. `aisa login --no-browser` is only for SSH / no local browser with an interactive TTY. `AISA_API_KEY` overrides the stored key; if they conflict, explain both sources and do not blindly unset the environment variable. Never print the raw key. -1. Reuse existing auth. Do not log in again if a stored CLI key or `AISA_API_KEY` already works. -2. If not signed in, run `aisa login` and let the user finish browser OAuth. The CLI mints and stores a CLI key. The user should not open the API Keys page or paste a key. -3. `aisa login --no-browser` is only for SSH / no local browser with an interactive TTY. It is not a silent headless login. -4. `--key` / `AISA_API_KEY` are for automation or advanced use, not this Quickstart. -5. Never print, log, or commit the raw key. Do not change the user's default model or unrelated client config. -6. `AISA_API_KEY` overrides the stored key. If both exist and disagree, explain the two sources. Do not blindly unset the environment variable or overwrite config. -7. `aisa whoami` is **local only**. It does not prove the remote credential still works. -8. Validate with a real authenticated read such as `aisa balance`. Report **AIsa is connected.** only after that succeeds. -9. Expired credentials → run `aisa login` again. Empty balance → top up the account; that is not a missing key. -10. If login or mint fails, show the error and the next step. Do not send the user to hunt for an API key, and do not “fix” every failure by reinstalling. +`aisa whoami` is local only. Prove auth with a real authenticated read such as `aisa balance`. Then say **AIsa is connected.** Empty balance → top up, not a missing key. Login or mint failure → show the error and retry `aisa login`; do not send the user to hunt for a key. -### 3. MCP path (no CLI, or user prefers MCP) +### MCP path -Connect the **unified AIsa router**. Do not use the domain catalog at `https://mcp.aisa.one/servers`, and do not treat the default `aisa connect` web-search server as this router. +Connect the unified AIsa router, not `https://mcp.aisa.one/servers` and not the default `aisa connect` web-search server. | Field | Value | | --- | --- | | Name | AIsa | | Server URL | `https://tools.aisa.one/mcp` | | Transport | Streamable HTTP | -| Auth | OAuth (let the client discover endpoints; choose OAuth if asked) | +| Auth | OAuth (client discovery; choose OAuth if asked) | -Practical steps: +**No command execution:** do not require `npx`. Add the remote server above in this client's connector settings, sign in with OAuth, then return and enable it if needed. If the client can install skills natively, install the same `aisa` skill; otherwise continue and say it was **not persistently installed**. -1. Open this client's MCP / connectors settings. -2. Add that remote server with the values above. Do not invent per-client CLI commands. -3. Complete browser sign-in. The client stores and refreshes tokens. No API key, Bearer paste, or copied access token. -4. Return to the agent. Refresh or reconnect if this client requires it. -5. If this client can install or upload skills natively, install the same canonical `aisa` skill that way. If it cannot, continue with MCP and **say the skill was not persistently installed**. Never require `npx` here. -6. Connection succeeds only after OAuth completed **and** these tools are present: +Claude (individual Pro/Max), from Anthropic's [custom connectors guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp): **Customize → Connectors → + → Add custom connector**, enter name `AIsa` and URL `https://tools.aisa.one/mcp`, **Add**, then **Connect** and complete OAuth. Enable it in the conversation via **+ → Connectors**. Team/Enterprise owner setup differs; use that guide, not a client matrix. These UI labels are from the official article, not a completed native OAuth. -- `AISA_SEARCH_TOOL` -- `AISA_BATCH_GET_SCHEMA` -- `AISA_BATCH_QUOTE` -- `AISA_BATCH_USE` +**Codex, when the user explicitly chose MCP and a terminal is available.** From Codex CLI `codex mcp add --help` and `codex mcp login --help`. Copyable example, not a completed OAuth: -Discovery, metadata, or an unauthenticated `401` challenge is not a successful protected call. Quote/call still need spending authorization later. +```sh +codex mcp add aisa --url https://tools.aisa.one/mcp +codex mcp login aisa --scopes openid,profile,email +``` + +Connection succeeds only after OAuth completed **and** these tools are present: `AISA_SEARCH_TOOL`, `AISA_BATCH_GET_SCHEMA`, `AISA_BATCH_QUOTE`, `AISA_BATCH_USE`. Metadata or a `401` challenge is not a protected call. Native client OAuth is not claimed verified here. | MCP tool | CLI command | | --- | --- | @@ -129,58 +108,34 @@ Discovery, metadata, or an unauthenticated `401` challenge is not a successful p | `AISA_BATCH_QUOTE` | `aisa quote` | | `AISA_BATCH_USE` | `aisa call` | -### 4. After AIsa is connected - -Say **AIsa is connected.** Connection is not a completed business task. - -- If the user already named a task, continue that task. -- Otherwise ask: **What would you like to do first?** Optional modest example: `Find three recent public updates about a company and include source links.` Do not run a paid example unless the user chooses it. Do not promise it is free or that it finishes in a fixed time. - -Workflow (CLI names; MCP uses the four tools): - -1. Search. -2. Schema when search says the schema is incomplete (`has_full_schema=false`). -3. Quote. -4. Call only inside a valid scope **and** spending authorization. +### After you are connected -Use live help, schema, quote, and server guidance for names, parameters, and prices. Inline JSON is supported with `--input`: - -```sh -aisa search --input '{"query":""}' --json -aisa quote --input '{"calls":[{"call_id":"c1","tool":"","arguments":{}}]}' --json -``` - -Do not invent tools, IDs, or prices. Do not use this page or a docs catalog as the price list. Do not probe price with a live call. A missing or failed quote is never free. Quote is not authorization to execute. +Say **AIsa is connected.** That is not a completed business task. Follow the `aisa` skill for search → schema when needed → quote → call. Runtime help, schema, and quote are authoritative. Inline JSON is supported with `--input`. -Setup consent is not spending approval. Reuse a prior **explicit** authorization that still covers this call. Do not demand a new confirmation for every reversible install substep. Before a billable call, use a matching quote and explicit authorization for that scope and cost. - -Search hits are discovery. Return sources with results. Say a task is complete only after a real result. - -### 5. Later sessions +Setup is not spending approval. Reuse a still-valid explicit authorization. Do not turn a missing, failed, partial, or estimated quote into a cap or free use. -Load the same `aisa` skill if it is installed. Do not rerun this bootstrap. Reuse auth and defaults. +Later sessions: load the same skill. Do not rerun setup. -### Failures +### If something fails | Situation | Next step | | --- | --- | | Browser login not finished | Wait; do not invent a key | | Login or mint failed | Show the error; retry `aisa login` | | `whoami` ok, remote read fails | Re-login; whoami is local only | -| `AISA_API_KEY` conflicts with the stored key | Explain both sources; do not blindly unset | -| Empty balance | Top up; not a missing key | +| `AISA_API_KEY` conflicts with the stored key | Explain both sources | +| Empty balance | Top up | | MCP tools missing after OAuth | Refresh/reconnect; confirm the four tools | -| Skill already installed | Reuse; do not reinstall | -| No terminal | MCP path; do not require `npx` | -| Install or service error | Stop at the failing step with the next action | +| Skill already installed | Reuse | +| No command execution | MCP path; no `npx` | ## Other ways to connect -Use these only when the user asked for models, REST, API keys, or extra skills. +Only if the user asked for models, REST, API keys, or extra skills. -- [Getting Started](/guides/getting-started-with-aisa) — account and model gateway -- [Authentication](/guides/authentication) — API keys for automation +- [Getting Started](/guides/getting-started-with-aisa) +- [Authentication](/guides/authentication) - [Models](/guides/models) - [API Reference](/api-reference) - [Agent Skills Quickstart](/agent-skills/quickstart) diff --git a/agent-skills/quickstart.mdx b/agent-skills/quickstart.mdx index 6a1589b3..424e68d6 100644 --- a/agent-skills/quickstart.mdx +++ b/agent-skills/quickstart.mdx @@ -5,105 +5,19 @@ privacy: view: "public" --- -The default path is **one official AIsa skill** plus the CLI. Copy this into the agent you already use. You do not need an API key or a task placeholder. +Copy this into the agent you already use. You do not need an API key. ```txt Set up AIsa using https://aisa.one/docs/agent-quickstart.md. ``` -The complete agent bootstrap — environment detection, login reuse, validation, spend authorization, and failure handling — is in [Agent Quickstart](/agent-quickstart). This page matches that installer and the no-terminal MCP branch so the two entries stay consistent. +The full connect flow — one official `aisa` skill, CLI or MCP, browser sign-in, and first-task rules — is [Agent Quickstart](/agent-quickstart). Use that page. This is the skills entry, not a second manual. - -Do not fetch the Quickstart URL again if you are already following these steps. Do not reinstall the same `aisa` skill. - +If you are already following those steps, do not fetch this URL again and do not reinstall the same skill. -## Install the official AIsa skill +Official skill: [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills), slug `aisa`, file `search-research/aisa/SKILL.md`. -Source: [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills). Slug: `aisa`. Canonical file: `search-research/aisa/SKILL.md`. +After AIsa is connected, keep using that skill. Extra catalog skills and authoring are optional: -If this environment can run terminal or CLI commands (any shell, not only Bash), install **one** skill into the **current** harness with the Vercel installer. Unpinned `npx skills` needs Node.js **22.20.0+** (`skills` 1.5.25 `engines`; verified on 22.22). That is not a reason to replace a working `@aisa-one/cli`. - -```sh -npx skills add AIsa-team/agent-skills --skill aisa --agent codex --global -``` - -Adapt `--agent` to this harness (for example `codex`, `claude-code`, `cursor`). Prefer `--global` for personal use. Use project scope only when the user asked to limit the install to this repo. - -- Do not use `--all`, `--agent '*'`, or `--skill '*'`. -- Use `--yes` only when this install is already authorized and the source/target are clear. -- If the official `aisa` skill is already present, reuse it. Do not overwrite a same-named custom skill. -- Do **not** use `aisa skills install` as the default way to connect AIsa. -- After the file is on disk, **read it in this session and continue**. Do not stop only to wait for a restart. - -## Install or reuse the CLI, then sign in - -```sh -npm install -g @aisa-one/cli -aisa --version -aisa login -``` - -Reuse `@aisa-one/cli` if it is already installed. Verified baseline: **0.5.0 or later**. Do not downgrade. A working CLI on Node.js 18+ can stay; do not replace it to match the `npx skills` Node floor. - -`aisa login` opens browser OAuth and mints a stored CLI key. The user should not copy a key from the dashboard. `--key` / `AISA_API_KEY` are for automation, not this path. - -- Never print the raw key. -- `AISA_API_KEY` overrides the stored key. If they conflict, explain both sources; do not blindly unset the environment variable. -- `aisa whoami` is local only. Validate with a real authenticated read such as `aisa balance` before saying **AIsa is connected.** -- Setup is not approval to spend. - -Then use `aisa search` → `aisa schema` when needed → `aisa quote` → `aisa call` inside a valid scope and spending authorization. Parameters and prices come from help/schema/quote, not from this page. Inline JSON works with `--input`. - -## No terminal, or you prefer MCP - -If this agent cannot run CLI commands, or the user asked for MCP, do not require `npx`. Add the unified AIsa router as a remote Streamable HTTP MCP server: - -| Field | Value | -| --- | --- | -| Name | AIsa | -| Server URL | `https://tools.aisa.one/mcp` | -| Transport | Streamable HTTP | -| Auth | OAuth | - -Open this client's MCP settings, add that server, complete browser sign-in, then return and refresh/reconnect if needed. The client discovers endpoints and stores/refreshes tokens. No manual keys. - -Do **not** use `https://mcp.aisa.one/servers` or the default `aisa connect` web-search server as this router. - -If the client can install skills natively, install the same canonical `aisa` skill. If it cannot, continue with MCP and say the skill was **not persistently installed**. - -Connection succeeds only after OAuth completed **and** these tools are present: `AISA_SEARCH_TOOL`, `AISA_BATCH_GET_SCHEMA`, `AISA_BATCH_QUOTE`, `AISA_BATCH_USE`. Discovery alone is not a protected business call. - -## After AIsa is connected - -Ask **What would you like to do first?** unless the user already named a task. Optional example: `Find three recent public updates about a company and include source links.` Do not promise it is free. - -Later sessions should load the same `aisa` skill. Do not rerun setup. - -## Optional: more skills from the catalog - -After AIsa is connected, you can browse extra domain skills. This is not the default connect path. - -```sh -aisa skills list -aisa skills search "finance" -aisa skills show market -aisa skills install market --agent cursor -aisa skills remove market --agent cursor -``` - -Do not install every catalog skill, and do not target all agents unless the user asked. - -## Create your own skill - -```sh -aisa skills init my-skill -aisa skills install ./my-skill -``` - -Edit `SKILL.md`, then install from the local path. To share it, open a pull request on [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills). Authoring rules: [Standards](/agent-skills/standards). - -## What's next - -- [Agent Quickstart](/agent-quickstart) — full connect, login, MCP, and spend rules -- [Agent Skills](/agent-skills) — catalog +- [Agent Skills catalog](/agent-skills) - [Standards](/agent-skills/standards) — how `SKILL.md` works diff --git a/zh/agent-quickstart.mdx b/zh/agent-quickstart.mdx index 0d2caf5d..658ee940 100644 --- a/zh/agent-quickstart.mdx +++ b/zh/agent-quickstart.mdx @@ -3,7 +3,7 @@ title: "把 Agent 连接到 AIsa" description: "安装 AIsa Skill，登录，然后开始使用工具。" --- -把下面这句英文交给你正在使用的 Agent。你不需要先准备 API Key，也不需要先填写任务占位符。 +把下面这句英文交给你正在使用的 Agent。你不需要先准备 API Key。 ## 复制接入提示词 @@ -11,116 +11,95 @@ description: "安装 AIsa Skill，登录，然后开始使用工具。" Set up AIsa using https://aisa.one/docs/agent-quickstart.md. ``` -可以在同一句话后面加上 `Then use AIsa to …`。如果没有，Agent 会先完成接入，再问你想做什么。 - - -接入流程只负责安装和登录，不等于批准消费。你可以在 **AIsa is connected.** 之后停下。 - +可以在同一句话后面加上 `Then use AIsa to …`。 ## 接下来会发生什么 - 如果当前环境可以运行终端命令，Agent 会安装一个官方 AIsa Skill，并复用或安装 `@aisa-one/cli`。 + 如果当前环境可以运行终端命令，Agent 会安装一个官方 AIsa Skill，并复用或安装 `@aisa-one/cli` 0.5.0 或更高版本。 - `aisa login` 会打开 AIsa 登录页。CLI 会自动签发并保存密钥。你不必从控制台复制 Key。 + `aisa login` 会在浏览器打开 AIsa 登录页。你不必从控制台复制 Key。 真实的已认证读取成功后，Agent 会报告 **AIsa is connected.** 然后继续你的任务，或选一个轻量例子。 -如果 Agent 无法运行 CLI 命令，就改为通过远程 MCP 和浏览器 OAuth 连接 AIsa。这条路径不要求先运行 `npx`。 +如果 Agent 无法运行命令，就改为通过远程 MCP 和浏览器 OAuth 连接 AIsa。这条路径不要求 `npx`。 ---- +## 可选的首个任务 -## Agent 接入步骤 +在 **AIsa is connected.** 之后，除非你已经说了任务，否则询问 **What would you like to do first?** + +例子：`Find three recent public updates about a company and include source links.` 你没有选择时，不要执行付费示例。不要承诺免费。 -你正在把当前环境连接到 AIsa。下面就是 bootstrap。**如果你已经在读这些步骤，不要再抓取同一个 URL，也不要重复安装同一个 Skill。** + +接入流程只负责安装和登录，不等于批准消费。 + -不要在这里加载完整文档索引、OpenAPI 目录或 Skill 正文。Skill 文件可用后，再读它获取常驻工作流规则。 +--- -### 1. 识别环境 +## Agent 接入步骤 -1. 识别当前 Agent / harness。 -2. 若已有可用的 AIsa 连接，直接复用：官方 `aisa` Skill 加上有效的 CLI 认证，或已连接且能列出下方四个 Router 工具的 AIsa MCP 会话。 -3. 只要当前环境能运行终端或 CLI 命令，就优先走 CLI。任意可用 shell 都可以，包括 PowerShell。不要求必须是 Bash。 -4. 没有可用终端 / CLI，或用户明确选择 MCP 时，走 MCP。 -5. MCP 路径不要求 Node.js 或 `npx`。未固定版本的 `npx skills` 需要 Node.js **22.20.0+**（`skills` 1.5.25 的 `engines`；已在 22.22 验证）。`@aisa-one/cli` 仍可沿用 Node.js **18+** 下限——不要为了安装器替换已经能用的旧 CLI。如果安装器跑不起来，只为该命令使用 Node 22.20.0+，或改走 MCP。 +把当前环境连接到 AIsa。如果你已经在读这些步骤，不要再抓取同一个 URL，也不要重复安装同一个 Skill。`aisa` Skill 落盘后，在当前会话读取它，了解何时使用 AIsa、四步工作流和消费规则。 -不要安装全部 Skill、全部 Agent 目标，也不要改无关的默认模型设置。 +### 识别环境 -### 2. CLI 路径（默认） +1. 复用已有的 AIsa 连接：官方 `aisa` Skill 加上有效的 CLI 认证，或已列出下方四个 Router 工具的统一 MCP。 +2. 只要当前环境能运行终端或 CLI 命令，就优先走 CLI。任意可用 shell 都可以，包括 PowerShell。不要求必须是 Bash。 +3. 没有可用的命令执行能力，或用户明确选择 MCP 时，走 MCP。这条路径不要求 Node.js 或 `npx`。 +4. 只为当前 harness 安装官方 `aisa` Skill。不要改无关的默认模型设置。 -#### 安装一个官方 Skill +### CLI 路径 -来源：[AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills)。Slug：`aisa`。权威文件：`search-research/aisa/SKILL.md`。 +来源：[AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills)。Slug：`aisa`。文件：`search-research/aisa/SKILL.md`。 -用 Vercel skills 安装器，只安装到**当前** harness。它需要 Node.js 22.20.0+；这不是替换已经能用的 CLI 的理由。 +未固定版本的 `npx skills` 需要 Node.js 22.20.0+（`skills` 1.5.25 的 `engines`；已在 22.22 验证）。已经能在 Node.js 18+ 上运行的 `@aisa-one/cli` 可以保留。 ```sh npx skills add AIsa-team/agent-skills --skill aisa --agent codex --global ``` -把 `--agent` 改成当前 harness（例如 `codex`、`claude-code`、`cursor`）。个人通用接入建议 `--global`。只有用户要求限制在当前仓库时，才用 project scope。 - -- 不要使用 `--all`、`--agent '*'` 或 `--skill '*'`。 -- 仅在本次安装已被授权、且来源/目标清楚时使用 `--yes`。 -- 如果官方 `aisa` Skill 已经存在，就复用。不要覆盖用户的同名自定义 Skill。 -- **不要**把 `aisa skills install` 当作默认安装方式。 -- 文件落盘后，**在当前会话读取并继续**。不要仅仅因为“需要重启”就停住。如果当前客户端必须新开会话才能加载新 Skill，说明这一点，并继续使用你已经能运行的 CLI 命令。 +把 `--agent` 改成当前 harness（`codex`、`claude-code`、`cursor` 等）。个人通用接入建议 `--global`，除非用户要求限制在当前仓库。不要使用 `--all` 或 `*`。不要把 `aisa skills install` 当作默认安装方式。官方 Skill 已存在就复用，不要覆盖同名自定义 Skill。然后读取 Skill 并继续。 -#### 安装或复用 CLI - -安装或复用 npm 包 `@aisa-one/cli`。已验证基线：**0.5.0 或更高**。不要降级现有 CLI。已经能在 Node.js 18+ 上运行的 CLI 可以保留，不要为了匹配 `npx skills` 的 Node 下限而替换它。Skill 版本不必与 CLI 版本相等。 - -确认存在 `search`、`schema`、`quote`、`call`（`aisa --help` 或 `aisa manifest`）。参数、JSON 形状和示例以 `aisa --help` 为准，不要猜目录。 +如果缺少 `aisa`： ```sh npm install -g @aisa-one/cli aisa --version ``` -#### 登录 +复用 CLI **0.5.0 或更高**。不要降级。 + +除非已存储的密钥或 `AISA_API_KEY` 已经可用，否则运行 `aisa login`。CLI 会签发并保存密钥。`aisa login --no-browser` 仅用于 SSH / 本机无浏览器、且有交互 TTY 的情况。`AISA_API_KEY` 优先于已存储密钥；两者冲突时说明两个来源，不要盲目取消环境变量。永远不要打印原始密钥。 -1. 复用现有认证。如果已存储的 CLI 密钥或 `AISA_API_KEY` 已经可用，不要再登录。 -2. 未登录时运行 `aisa login`，让用户完成浏览器 OAuth。CLI 会签发并保存 CLI 密钥。用户不必打开 API Keys 页面，也不必粘贴 Key。 -3. `aisa login --no-browser` 仅用于 SSH / 本机无浏览器、且有交互 TTY 的情况。它不是静默无头登录。 -4. `--key` / `AISA_API_KEY` 用于自动化或高级用法，不是本 Quickstart 的前置步骤。 -5. 永远不要打印、记录或提交原始密钥。不要改用户的默认模型或其他无关客户端配置。 -6. `AISA_API_KEY` 优先于已存储密钥。两者冲突时说明两个来源，不要盲目取消环境变量或覆盖配置。 -7. `aisa whoami` **只检查本地**。它不能证明远端凭证仍然有效。 -8. 用真实的已认证读取验证，例如 `aisa balance`。只有成功后才报告 **AIsa is connected.** -9. 凭证失效 → 重新运行 `aisa login`。余额为 0 → 去充值，不是缺 Key。 -10. 登录或 mint 失败时，展示错误和下一步。不要让用户去找 API Key，也不要用反复重装来“修复”所有问题。 +`aisa whoami` 只检查本地。用真实的已认证读取证明认证，例如 `aisa balance`。然后报告 **AIsa is connected.** 余额为 0 → 去充值，不是缺 Key。登录或 mint 失败 → 展示错误并重试 `aisa login`，不要让用户去找 Key。 -### 3. MCP 路径（无 CLI，或用户选择 MCP） +### MCP 路径 -连接 **AIsa 统一 Router**。不要使用 `https://mcp.aisa.one/servers` 的领域目录，也不要把默认 `aisa connect` 的 web-search 服务器当成这个 Router。 +连接 AIsa 统一 Router，不要使用 `https://mcp.aisa.one/servers`，也不要把默认 `aisa connect` 的 web-search 服务器当成这个 Router。 | 字段 | 值 | | --- | --- | | 名称 | AIsa | | 服务器 URL | `https://tools.aisa.one/mcp` | | 传输 | Streamable HTTP | -| 认证 | OAuth（让客户端自动发现端点；需要选择时选 OAuth） | +| 认证 | OAuth（由客户端发现；需要选择时选 OAuth） | -实际步骤： +**没有命令执行能力：** 不要要求 `npx`。在当前客户端的 connector 设置里添加上面的远程服务器，用 OAuth 登录，必要时返回后启用。如果客户端能原生安装 Skill，安装同一个 `aisa` Skill；否则继续，并说明 **并未持久安装**。 -1. 打开当前客户端的 MCP / connectors 设置。 -2. 按上表添加远程服务器。不要编造各客户端专用命令。 -3. 在浏览器完成登录。由客户端保存并刷新 token。不需要 API Key、粘贴 Bearer，或复制 access token。 -4. 回到 Agent。如果客户端要求，刷新或重新连接。 -5. 若客户端支持原生安装或上传 Skill，按同样的 canonical `aisa` Skill 安装。若不支持，继续用 MCP，并**说明 Skill 并未持久安装**。这条路径绝不能要求 `npx`。 -6. 只有 OAuth 已完成，**并且**下列工具都已出现，才算连接成功： +Claude（个人 Pro/Max）按 Anthropic 的 [custom connectors 指南](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)：**Customize → Connectors → + → Add custom connector**，填入名称 `AIsa` 和 URL `https://tools.aisa.one/mcp`，**Add**，然后 **Connect** 并完成 OAuth。在对话里通过 **+ → Connectors** 启用。Team/Enterprise 由所有者配置，路径不同；以该指南为准，不要铺开客户端矩阵。这些界面文案来自官方文章，不是已完成的原生 OAuth。 -- `AISA_SEARCH_TOOL` -- `AISA_BATCH_GET_SCHEMA` -- `AISA_BATCH_QUOTE` -- `AISA_BATCH_USE` +**用户明确选择 MCP、且有终端可用时的 Codex 示例。** 来自 Codex CLI 的 `codex mcp add --help` 和 `codex mcp login --help`。可复制示例，不是已完成的 OAuth： -发现、metadata 或未认证的 `401` 挑战，都不等于受保护调用已成功。quote/call 仍需要后续的消费授权。 +```sh +codex mcp add aisa --url https://tools.aisa.one/mcp +codex mcp login aisa --scopes openid,profile,email +``` + +只有 OAuth 已完成，**并且**这些工具都已出现，才算连接成功：`AISA_SEARCH_TOOL`、`AISA_BATCH_GET_SCHEMA`、`AISA_BATCH_QUOTE`、`AISA_BATCH_USE`。metadata 或 `401` 挑战不等于受保护调用。这里不宣称原生客户端 OAuth 已验证。 | MCP 工具 | CLI 命令 | | --- | --- | @@ -129,37 +108,14 @@ aisa --version | `AISA_BATCH_QUOTE` | `aisa quote` | | `AISA_BATCH_USE` | `aisa call` | -### 4. 连接成功之后 - -报告 **AIsa is connected.** 连接成功不等于业务任务已完成。 - -- 如果用户已经说了任务，就继续该任务。 -- 否则询问：**What would you like to do first?** 可选的轻量例子：`Find three recent public updates about a company and include source links.` 用户没有选择时，不要执行付费示例。不要承诺免费，也不要承诺固定时长。 - -工作流（CLI 名称；MCP 使用上面四个工具）： - -1. Search。 -2. 当 search 表明 schema 不完整时取 schema（`has_full_schema=false`）。 -3. Quote。 -4. 只在有效范围 **且** 已有消费授权时 call。 +### 连接成功之后 -名称、参数和价格以实时 help、schema、quote 和服务端 guidance 为准。`--input` 支持内联 JSON： - -```sh -aisa search --input '{"query":""}' --json -aisa quote --input '{"calls":[{"call_id":"c1","tool":"","arguments":{}}]}' --json -``` - -不要编造工具、ID 或价格。不要把本页或文档目录当成价目表。不要用真实调用来探价。缺少或失败的 quote 绝不等于免费。Quote 不是执行授权。 +报告 **AIsa is connected.** 这不等于业务任务已完成。按 `aisa` Skill 执行 search → 必要时 schema → quote → call。实时 help、schema 和 quote 是权威来源。`--input` 支持内联 JSON。 -接入同意不是消费批准。复用仍然覆盖本次调用的**既有明确授权**。不要为每个可逆的安装子步骤再要一次确认。发起计费调用前，需要匹配的 quote，以及对应该范围和费用的明确授权。 - -搜索结果只是发现线索。返回结果时带上来源。只有拿到真实结果，才能说任务已完成。 - -### 5. 之后的会话 +接入不是消费批准。复用仍然有效的明确授权。不要把缺少、失败、部分或估算的 quote 当成上限或免费。 -如果已安装 `aisa` Skill，直接加载。不要重新跑 bootstrap。复用认证和默认配置。 +之后的会话：加载同一个 Skill。不要重新跑 setup。 ### 失败时怎么做 @@ -168,19 +124,18 @@ aisa quote --input '{"calls":[{"call_id":"c1","tool":"","argum | 浏览器登录未完成 | 等待；不要编造 Key | | 登录或 mint 失败 | 展示错误；重试 `aisa login` | | `whoami` 成功但远端读取失败 | 重新登录；whoami 只检查本地 | -| `AISA_API_KEY` 与已存储密钥冲突 | 说明两个来源；不要盲目取消 | -| 余额为 0 | 去充值；不是缺 Key | +| `AISA_API_KEY` 与已存储密钥冲突 | 说明两个来源 | +| 余额为 0 | 去充值 | | OAuth 后看不到 MCP 工具 | 刷新/重连；确认四个工具 | -| Skill 已安装 | 复用；不要重装 | -| 没有终端 | 走 MCP；不要要求 `npx` | -| 安装或服务失败 | 停在失败步骤，并给出下一步 | +| Skill 已安装 | 复用 | +| 没有命令执行能力 | 走 MCP；不要要求 `npx` | ## 其他接入方式 仅在用户明确要求模型、REST、API Key 或额外 Skill 时使用。 -- [入门](/zh/guides/getting-started-with-aisa) — 账号和模型网关 -- [认证](/zh/guides/authentication) — 自动化用的 API Key +- [入门](/zh/guides/getting-started-with-aisa) +- [认证](/zh/guides/authentication) - [模型](/zh/guides/models) - [API 参考](/zh/api-reference) - [Agent Skills 快速入门](/zh/agent-skills/quickstart) diff --git a/zh/agent-skills/quickstart.mdx b/zh/agent-skills/quickstart.mdx index 44bb8e74..a7decd7b 100644 --- a/zh/agent-skills/quickstart.mdx +++ b/zh/agent-skills/quickstart.mdx @@ -5,105 +5,19 @@ privacy: view: "public" --- -默认路径是 **一个官方 AIsa Skill** 加上 CLI。把下面这句英文交给你正在使用的 Agent。你不需要先准备 API Key，也不需要先填写任务占位符。 +把下面这句英文交给你正在使用的 Agent。你不需要先准备 API Key。 ```txt Set up AIsa using https://aisa.one/docs/agent-quickstart.md. ``` -完整的 Agent bootstrap——环境识别、登录复用、验证、消费授权和失败处理——见 [Agent 快速开始](/zh/agent-quickstart)。本页与该安装方式和无终端 MCP 分支保持一致，避免两个入口互相矛盾。 +完整接入流程——一个官方 `aisa` Skill、CLI 或 MCP、浏览器登录，以及首个任务规则——见 [Agent 快速开始](/zh/agent-quickstart)。请走那一页。本页只是 Skills 入口，不是第二份手册。 - -如果你已经在执行这些步骤，不要再抓取 Quickstart URL，也不要重复安装同一个 `aisa` Skill。 - +如果你已经在执行那些步骤，不要再抓取这个 URL，也不要重复安装同一个 Skill。 -## 安装官方 AIsa Skill +官方 Skill：[AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills)，slug `aisa`，文件 `search-research/aisa/SKILL.md`。 -来源：[AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills)。Slug：`aisa`。权威文件：`search-research/aisa/SKILL.md`。 +AIsa 连接成功后，继续使用该 Skill。额外的目录 Skill 和编写说明是可选的： -如果当前环境可以运行终端或 CLI 命令（任意 shell，不限于 Bash），用 Vercel 安装器把 **一个** Skill 装到 **当前** harness。未固定版本的 `npx skills` 需要 Node.js **22.20.0+**（`skills` 1.5.25 的 `engines`；已在 22.22 验证）。这不是替换已经能用的 `@aisa-one/cli` 的理由。 - -```sh -npx skills add AIsa-team/agent-skills --skill aisa --agent codex --global -``` - -把 `--agent` 改成当前 harness（例如 `codex`、`claude-code`、`cursor`）。个人通用接入建议 `--global`。只有用户要求限制在当前仓库时，才用 project scope。 - -- 不要使用 `--all`、`--agent '*'` 或 `--skill '*'`。 -- 仅在本次安装已被授权、且来源/目标清楚时使用 `--yes`。 -- 如果官方 `aisa` Skill 已经存在，就复用。不要覆盖用户的同名自定义 Skill。 -- **不要**把 `aisa skills install` 当作连接 AIsa 的默认方式。 -- 文件落盘后，**在当前会话读取并继续**。不要仅仅因为“需要重启”就停住。 - -## 安装或复用 CLI，然后登录 - -```sh -npm install -g @aisa-one/cli -aisa --version -aisa login -``` - -如果已经安装了 `@aisa-one/cli`，直接复用。已验证基线：**0.5.0 或更高**。不要降级。已经能在 Node.js 18+ 上运行的 CLI 可以保留，不要为了匹配 `npx skills` 的 Node 下限而替换它。 - -`aisa login` 会打开浏览器 OAuth，并签发保存到本地的 CLI 密钥。用户不必从控制台复制 Key。`--key` / `AISA_API_KEY` 用于自动化，不是这条路径。 - -- 永远不要打印原始密钥。 -- `AISA_API_KEY` 优先于已存储密钥。两者冲突时说明两个来源，不要盲目取消环境变量。 -- `aisa whoami` 只检查本地。在报告 **AIsa is connected.** 之前，用真实的已认证读取验证，例如 `aisa balance`。 -- 接入不等于批准消费。 - -随后在有效范围和消费授权内使用 `aisa search` → 必要时 `aisa schema` → `aisa quote` → `aisa call`。参数和价格来自 help/schema/quote，而不是本页。`--input` 支持内联 JSON。 - -## 没有终端，或你更想用 MCP - -如果当前 Agent 无法运行 CLI 命令，或用户要求 MCP，不要先要求 `npx`。把 AIsa 统一 Router 添加为远程 Streamable HTTP MCP 服务器： - -| 字段 | 值 | -| --- | --- | -| 名称 | AIsa | -| 服务器 URL | `https://tools.aisa.one/mcp` | -| 传输 | Streamable HTTP | -| 认证 | OAuth | - -打开当前客户端的 MCP 设置，添加该服务器，完成浏览器登录，必要时返回后刷新/重连。由客户端发现端点并保存/刷新 token。不需要手工 Key。 - -**不要**把 `https://mcp.aisa.one/servers` 或默认 `aisa connect` 的 web-search 服务器当成这个 Router。 - -如果客户端支持原生安装 Skill，安装同一个 canonical `aisa` Skill。如果不支持，继续用 MCP，并说明 Skill **并未持久安装**。 - -只有 OAuth 已完成，**并且**这些工具都已出现，才算连接成功：`AISA_SEARCH_TOOL`、`AISA_BATCH_GET_SCHEMA`、`AISA_BATCH_QUOTE`、`AISA_BATCH_USE`。仅完成发现不等于受保护的业务调用已成功。 - -## 连接成功之后 - -除非用户已经说了任务，否则询问 **What would you like to do first?** 可选例子：`Find three recent public updates about a company and include source links.` 不要承诺免费。 - -之后的会话应加载同一个 `aisa` Skill，不要重新跑 setup。 - -## 可选：从目录安装更多 Skill - -AIsa 连接成功后，可以浏览额外的领域 Skill。这不是默认接入路径。 - -```sh -aisa skills list -aisa skills search "finance" -aisa skills show market -aisa skills install market --agent cursor -aisa skills remove market --agent cursor -``` - -不要安装目录里的全部 Skill，也不要在用户未要求时对所有 Agent 安装。 - -## 创建自己的 Skill - -```sh -aisa skills init my-skill -aisa skills install ./my-skill -``` - -编辑 `SKILL.md`，然后从本地路径安装。如需分享，向 [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills) 提交 Pull Request。编写规则见 [标准](/zh/agent-skills/standards)。 - -## 下一步 - -- [Agent 快速开始](/zh/agent-quickstart) — 完整接入、登录、MCP 和消费规则 -- [Agent Skills](/zh/agent-skills) — 目录 +- [Agent Skills 目录](/zh/agent-skills) - [标准](/zh/agent-skills/standards) — `SKILL.md` 如何工作 From 9ce5dcac057768d56c967dca7c6a59f897565252 Mon Sep 17 00:00:00 2001 From: idan Date: Wed, 9 Sep 2026 22:41:23 +0800 Subject: [PATCH 05/18] docs: drop process asides; fix first-task and auth-failure copy Keep one MCP tool table, cite Claude/Codex help without verification disclaimers, and treat remote-read errors as cause-specific. --- agent-quickstart.mdx | 15 ++++++++------- agent-skills/quickstart.mdx | 4 ++-- zh/agent-quickstart.mdx | 15 ++++++++------- zh/agent-skills/quickstart.mdx | 4 ++-- 4 files changed, 20 insertions(+), 18 deletions(-) diff --git a/agent-quickstart.mdx b/agent-quickstart.mdx index c03ceb53..f9f7cb35 100644 --- a/agent-quickstart.mdx +++ b/agent-quickstart.mdx @@ -3,7 +3,7 @@ title: "Connect your agent to AIsa" description: "Install the AIsa skill, sign in, and start using tools." --- -Give this prompt to the agent you already use. You do not need an API key. +Give this prompt to the agent you already use. No API key to copy or manage. ## Copy setup prompt @@ -31,9 +31,9 @@ If the agent cannot run commands, it connects AIsa through remote MCP and browse ## Optional first task -After **AIsa is connected.**, ask **What would you like to do first?** unless you already named a task. +After **AIsa is connected.**, tell your agent what to do. If you do not, it will ask what you want next. -Example: `Find three recent public updates about a company and include source links.` Do not run a paid example unless you choose it. It is not promised free. +Example: `Find three recent public updates about a company and include source links.` A paid example runs only if you choose it. Setup installs and signs in. It is not approval to spend. @@ -90,16 +90,16 @@ Connect the unified AIsa router, not `https://mcp.aisa.one/servers` and not the **No command execution:** do not require `npx`. Add the remote server above in this client's connector settings, sign in with OAuth, then return and enable it if needed. If the client can install skills natively, install the same `aisa` skill; otherwise continue and say it was **not persistently installed**. -Claude (individual Pro/Max), from Anthropic's [custom connectors guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp): **Customize → Connectors → + → Add custom connector**, enter name `AIsa` and URL `https://tools.aisa.one/mcp`, **Add**, then **Connect** and complete OAuth. Enable it in the conversation via **+ → Connectors**. Team/Enterprise owner setup differs; use that guide, not a client matrix. These UI labels are from the official article, not a completed native OAuth. +Claude (individual Pro/Max), from Anthropic's [custom connectors guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp): **Customize → Connectors → + → Add custom connector**, enter name `AIsa` and URL `https://tools.aisa.one/mcp`, **Add**, then **Connect** and complete OAuth. Enable it in the conversation via **+ → Connectors**. Team/Enterprise owner setup differs; use that guide. -**Codex, when the user explicitly chose MCP and a terminal is available.** From Codex CLI `codex mcp add --help` and `codex mcp login --help`. Copyable example, not a completed OAuth: +**Codex, when the user explicitly chose MCP and a terminal is available.** From Codex CLI `codex mcp add --help` and `codex mcp login --help`: ```sh codex mcp add aisa --url https://tools.aisa.one/mcp codex mcp login aisa --scopes openid,profile,email ``` -Connection succeeds only after OAuth completed **and** these tools are present: `AISA_SEARCH_TOOL`, `AISA_BATCH_GET_SCHEMA`, `AISA_BATCH_QUOTE`, `AISA_BATCH_USE`. Metadata or a `401` challenge is not a protected call. Native client OAuth is not claimed verified here. +Connection succeeds only after OAuth completed **and** the four tools below are present. Metadata or a `401` challenge is not a protected call. | MCP tool | CLI command | | --- | --- | @@ -123,7 +123,8 @@ Later sessions: load the same skill. Do not rerun setup. | --- | --- | | Browser login not finished | Wait; do not invent a key | | Login or mint failed | Show the error; retry `aisa login` | -| `whoami` ok, remote read fails | Re-login; whoami is local only | +| Rejected or expired credentials | `aisa login` | +| Network or service error | Show the actual cause; do not relogin by default | | `AISA_API_KEY` conflicts with the stored key | Explain both sources | | Empty balance | Top up | | MCP tools missing after OAuth | Refresh/reconnect; confirm the four tools | diff --git a/agent-skills/quickstart.mdx b/agent-skills/quickstart.mdx index 424e68d6..fb32f554 100644 --- a/agent-skills/quickstart.mdx +++ b/agent-skills/quickstart.mdx @@ -5,13 +5,13 @@ privacy: view: "public" --- -Copy this into the agent you already use. You do not need an API key. +Copy this into the agent you already use. No API key to copy or manage. ```txt Set up AIsa using https://aisa.one/docs/agent-quickstart.md. ``` -The full connect flow — one official `aisa` skill, CLI or MCP, browser sign-in, and first-task rules — is [Agent Quickstart](/agent-quickstart). Use that page. This is the skills entry, not a second manual. +The full connect flow — one official `aisa` skill, CLI or MCP, browser sign-in, and first-task rules — is [Agent Quickstart](/agent-quickstart). If you are already following those steps, do not fetch this URL again and do not reinstall the same skill. diff --git a/zh/agent-quickstart.mdx b/zh/agent-quickstart.mdx index 658ee940..3bc03f2d 100644 --- a/zh/agent-quickstart.mdx +++ b/zh/agent-quickstart.mdx @@ -3,7 +3,7 @@ title: "把 Agent 连接到 AIsa" description: "安装 AIsa Skill，登录，然后开始使用工具。" --- -把下面这句英文交给你正在使用的 Agent。你不需要先准备 API Key。 +把下面这句英文交给你正在使用的 Agent。没有需要复制或自行管理的 API Key。 ## 复制接入提示词 @@ -31,9 +31,9 @@ Set up AIsa using https://aisa.one/docs/agent-quickstart.md. ## 可选的首个任务 -在 **AIsa is connected.** 之后，除非你已经说了任务，否则询问 **What would you like to do first?** +在 **AIsa is connected.** 之后，告诉 Agent 你想做什么。如果你没有说，它会问下一步要做什么。 -例子：`Find three recent public updates about a company and include source links.` 你没有选择时，不要执行付费示例。不要承诺免费。 +例子：`Find three recent public updates about a company and include source links.` 付费示例只有在你选择时才会执行。 接入流程只负责安装和登录，不等于批准消费。 @@ -90,16 +90,16 @@ aisa --version **没有命令执行能力：** 不要要求 `npx`。在当前客户端的 connector 设置里添加上面的远程服务器，用 OAuth 登录，必要时返回后启用。如果客户端能原生安装 Skill，安装同一个 `aisa` Skill；否则继续，并说明 **并未持久安装**。 -Claude（个人 Pro/Max）按 Anthropic 的 [custom connectors 指南](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)：**Customize → Connectors → + → Add custom connector**，填入名称 `AIsa` 和 URL `https://tools.aisa.one/mcp`，**Add**，然后 **Connect** 并完成 OAuth。在对话里通过 **+ → Connectors** 启用。Team/Enterprise 由所有者配置，路径不同；以该指南为准，不要铺开客户端矩阵。这些界面文案来自官方文章，不是已完成的原生 OAuth。 +Claude（个人 Pro/Max）按 Anthropic 的 [custom connectors 指南](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)：**Customize → Connectors → + → Add custom connector**，填入名称 `AIsa` 和 URL `https://tools.aisa.one/mcp`，**Add**，然后 **Connect** 并完成 OAuth。在对话里通过 **+ → Connectors** 启用。Team/Enterprise 由所有者配置，路径不同；以该指南为准。 -**用户明确选择 MCP、且有终端可用时的 Codex 示例。** 来自 Codex CLI 的 `codex mcp add --help` 和 `codex mcp login --help`。可复制示例，不是已完成的 OAuth： +**用户明确选择 MCP、且有终端可用时的 Codex 示例。** 来自 Codex CLI 的 `codex mcp add --help` 和 `codex mcp login --help`： ```sh codex mcp add aisa --url https://tools.aisa.one/mcp codex mcp login aisa --scopes openid,profile,email ``` -只有 OAuth 已完成，**并且**这些工具都已出现，才算连接成功：`AISA_SEARCH_TOOL`、`AISA_BATCH_GET_SCHEMA`、`AISA_BATCH_QUOTE`、`AISA_BATCH_USE`。metadata 或 `401` 挑战不等于受保护调用。这里不宣称原生客户端 OAuth 已验证。 +只有 OAuth 已完成，**并且**下表四个工具都已出现，才算连接成功。metadata 或 `401` 挑战不等于受保护调用。 | MCP 工具 | CLI 命令 | | --- | --- | @@ -123,7 +123,8 @@ codex mcp login aisa --scopes openid,profile,email | --- | --- | | 浏览器登录未完成 | 等待；不要编造 Key | | 登录或 mint 失败 | 展示错误；重试 `aisa login` | -| `whoami` 成功但远端读取失败 | 重新登录；whoami 只检查本地 | +| 凭证被拒绝或已过期 | `aisa login` | +| 网络或服务错误 | 展示实际原因；不要默认重新登录 | | `AISA_API_KEY` 与已存储密钥冲突 | 说明两个来源 | | 余额为 0 | 去充值 | | OAuth 后看不到 MCP 工具 | 刷新/重连；确认四个工具 | diff --git a/zh/agent-skills/quickstart.mdx b/zh/agent-skills/quickstart.mdx index a7decd7b..c83ff2d1 100644 --- a/zh/agent-skills/quickstart.mdx +++ b/zh/agent-skills/quickstart.mdx @@ -5,13 +5,13 @@ privacy: view: "public" --- -把下面这句英文交给你正在使用的 Agent。你不需要先准备 API Key。 +把下面这句英文交给你正在使用的 Agent。没有需要复制或自行管理的 API Key。 ```txt Set up AIsa using https://aisa.one/docs/agent-quickstart.md. ``` -完整接入流程——一个官方 `aisa` Skill、CLI 或 MCP、浏览器登录，以及首个任务规则——见 [Agent 快速开始](/zh/agent-quickstart)。请走那一页。本页只是 Skills 入口，不是第二份手册。 +完整接入流程——一个官方 `aisa` Skill、CLI 或 MCP、浏览器登录，以及首个任务规则——见 [Agent 快速开始](/zh/agent-quickstart)。 如果你已经在执行那些步骤，不要再抓取这个 URL，也不要重复安装同一个 Skill。 From 15fb64a88632c865f82b295bae3105a85f942571 Mon Sep 17 00:00:00 2001 From: idan Date: Thu, 10 Sep 2026 00:09:01 +0800 Subject: [PATCH 06/18] docs: split pure Agent setup from human Skills copy prompt Move the public copy prompt onto Agent Skills Quickstart. Keep agent-quickstart.mdx as operating instructions without a self URL. --- agent-quickstart.mdx | 107 +++++++++++---------------------- agent-skills/quickstart.mdx | 26 ++++++-- zh/agent-quickstart.mdx | 107 +++++++++++---------------------- zh/agent-skills/quickstart.mdx | 24 ++++++-- 4 files changed, 109 insertions(+), 155 deletions(-) diff --git a/agent-quickstart.mdx b/agent-quickstart.mdx index f9f7cb35..7db0180a 100644 --- a/agent-quickstart.mdx +++ b/agent-quickstart.mdx @@ -3,96 +3,58 @@ title: "Connect your agent to AIsa" description: "Install the AIsa skill, sign in, and start using tools." --- -Give this prompt to the agent you already use. No API key to copy or manage. +Set up AIsa. -## Copy setup prompt +## 1. Choose or reuse a connection -```txt -Set up AIsa using https://aisa.one/docs/agent-quickstart.md. -``` - -You can append `Then use AIsa to …` in the same message. - -## What happens next - - - - If this environment can run terminal commands, the agent installs one official AIsa skill and reuses or installs `@aisa-one/cli` 0.5.0 or later. - - - `aisa login` opens AIsa sign-in in your browser. You should not copy a key from the dashboard. - - - After a real authenticated check succeeds, the agent reports **AIsa is connected.** Then continue your task, or pick a small example. - - - -If the agent cannot run commands, it connects AIsa through remote MCP and browser OAuth instead. `npx` is not required on that path. +Reuse a working AIsa connection when one already exists: the official `aisa` skill plus valid CLI auth, or unified MCP with the four router tools below. -## Optional first task +If this environment can run terminal or CLI commands, use the CLI path. Any working shell counts, including PowerShell. Bash is not required. -After **AIsa is connected.**, tell your agent what to do. If you do not, it will ask what you want next. - -Example: `Find three recent public updates about a company and include source links.` A paid example runs only if you choose it. - - -Setup installs and signs in. It is not approval to spend. - - ---- +If there is no usable command execution, or the user explicitly prefers MCP, use native remote MCP with OAuth. Do not require Node.js or `npx` on that path. -## Agent setup +Install only the official `aisa` skill for this harness. Do not change the user's default model or unrelated client settings. -Connect this environment to AIsa. If you are already reading these steps, do not fetch this URL again and do not reinstall the same skill. After the `aisa` skill is on disk, read it in this session for when to use AIsa, the four-step workflow, and spend rules. - -### Detect - -1. Reuse a working AIsa connection: the official `aisa` skill plus valid CLI auth, or unified MCP with the four router tools below. -2. Prefer the CLI path when this environment can run terminal or CLI commands. Any working shell counts, including PowerShell. Bash is not required. -3. Use MCP when there is no usable command execution, or the user explicitly prefers MCP. Do not require Node.js or `npx` on that path. -4. Install only the official `aisa` skill for this harness. Do not change unrelated model settings. - -### CLI path +## 2. CLI path Source: [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills). Slug: `aisa`. File: `search-research/aisa/SKILL.md`. -Unpinned `npx skills` needs Node.js 22.20.0+ (`skills` 1.5.25 `engines`; verified on 22.22). A working `@aisa-one/cli` on Node.js 18+ can stay. +Install one official skill for the **current** harness: ```sh npx skills add AIsa-team/agent-skills --skill aisa --agent codex --global ``` -Set `--agent` to this harness (`codex`, `claude-code`, `cursor`, …). Prefer `--global` unless the user asked for this repo only. Do not use `--all` or `*`. Do not use `aisa skills install` as the default. Reuse the official skill if it is already present; do not overwrite a same-named custom skill. Then read the skill and continue. +Set `--agent` to this harness (`codex`, `claude-code`, `cursor`, …). Prefer `--global` unless the user asked for this repo only (project scope). Do not use `--all` or `*`. Do not overwrite a same-named custom skill. Reuse the official skill if it is already present. + +Unpinned `npx skills` needs Node.js **22.20.0+** (`skills` 1.5.25 `engines`; verified on 22.22). `@aisa-one/cli` may keep its Node.js **18+** floor. Do not replace a working CLI to match the installer. -If `aisa` is missing: +Check for `@aisa-one/cli` **0.5.0 or later**. Reuse it if it works. Install only if it is absent: ```sh npm install -g @aisa-one/cli aisa --version ``` -Reuse CLI **0.5.0 or later**. Do not downgrade. +Upgrade only when the installed CLI is unsupported. Do not downgrade or reinstall a working version. -Sign in with `aisa login` unless a stored key or `AISA_API_KEY` already works. The CLI mints and stores a key. `aisa login --no-browser` is only for SSH / no local browser with an interactive TTY. `AISA_API_KEY` overrides the stored key; if they conflict, explain both sources and do not blindly unset the environment variable. Never print the raw key. +Check authentication with `aisa balance`. If credentials are missing or rejected, run browser `aisa login`, then `aisa balance` again. `aisa login --no-browser` is only for interactive SSH / no local browser with a TTY. `AISA_API_KEY` overrides the stored key; if they conflict, explain both sources and do not blindly unset the environment variable. Never print credentials. Do not send the user to copy a key from the dashboard. -`aisa whoami` is local only. Prove auth with a real authenticated read such as `aisa balance`. Then say **AIsa is connected.** Empty balance → top up, not a missing key. Login or mint failure → show the error and retry `aisa login`; do not send the user to hunt for a key. +`aisa whoami` is local only. It is not proof of remote auth. -### MCP path +After the skill is on disk, read it in this session and continue. -Connect the unified AIsa router, not `https://mcp.aisa.one/servers` and not the default `aisa connect` web-search server. +## 3. MCP path -| Field | Value | -| --- | --- | -| Name | AIsa | -| Server URL | `https://tools.aisa.one/mcp` | -| Transport | Streamable HTTP | -| Auth | OAuth (client discovery; choose OAuth if asked) | +Connect the unified AIsa router at `https://tools.aisa.one/mcp` (Streamable HTTP, OAuth). The client discovers endpoints and owns token storage and refresh. The user completes browser sign-in. Reconnect or enable the connector if the client requires it. + +Do not use `https://mcp.aisa.one/servers` or the default `aisa connect` web-search server as this router. Do not require `npx` when there is no command execution. -**No command execution:** do not require `npx`. Add the remote server above in this client's connector settings, sign in with OAuth, then return and enable it if needed. If the client can install skills natively, install the same `aisa` skill; otherwise continue and say it was **not persistently installed**. +If this client can install skills natively, install the same `aisa` skill. If it cannot, continue and say the skill was **not persistently installed**. Claude (individual Pro/Max), from Anthropic's [custom connectors guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp): **Customize → Connectors → + → Add custom connector**, enter name `AIsa` and URL `https://tools.aisa.one/mcp`, **Add**, then **Connect** and complete OAuth. Enable it in the conversation via **+ → Connectors**. Team/Enterprise owner setup differs; use that guide. -**Codex, when the user explicitly chose MCP and a terminal is available.** From Codex CLI `codex mcp add --help` and `codex mcp login --help`: +Codex, when the user explicitly chose MCP and a terminal is available, from Codex CLI `codex mcp add --help` and `codex mcp login --help`: ```sh codex mcp add aisa --url https://tools.aisa.one/mcp @@ -108,32 +70,33 @@ Connection succeeds only after OAuth completed **and** the four tools below are | `AISA_BATCH_QUOTE` | `aisa quote` | | `AISA_BATCH_USE` | `aisa call` | -### After you are connected +## 4. After authentication is verified + +Say **AIsa is connected.** only after authentication is verified (`aisa balance` on the CLI path, or OAuth completed with the four tools on the MCP path). That is not a completed business task. + +If the user already named a task, continue it. Otherwise ask **What would you like to do first?** -Say **AIsa is connected.** That is not a completed business task. Follow the `aisa` skill for search → schema when needed → quote → call. Runtime help, schema, and quote are authoritative. Inline JSON is supported with `--input`. +Follow the `aisa` skill for search → schema when needed → quote → call. Runtime help, schema, and quote are authoritative. Inline JSON is supported with `--input`. - -Setup is not spending approval. Reuse a still-valid explicit authorization. Do not turn a missing, failed, partial, or estimated quote into a cap or free use. +## Paid API approval first -Later sessions: load the same skill. Do not rerun setup. +Setup is not spending approval. Before `call` / `AISA_BATCH_USE`, use a matching quote and an authorization that covers that scope and cost. Reuse a still-valid explicit authorization. A missing, failed, or partial quote is not free and is not a full-batch total. Estimated cost is not a guaranteed cap. -### If something fails +## 5. If something fails | Situation | Next step | | --- | --- | | Browser login not finished | Wait; do not invent a key | -| Login or mint failed | Show the error; retry `aisa login` | -| Rejected or expired credentials | `aisa login` | +| Missing, rejected, or expired credentials | `aisa login`, then `aisa balance` | | Network or service error | Show the actual cause; do not relogin by default | +| Empty credit | Top up; not a missing key | | `AISA_API_KEY` conflicts with the stored key | Explain both sources | -| Empty balance | Top up | | MCP tools missing after OAuth | Refresh/reconnect; confirm the four tools | | Skill already installed | Reuse | -| No command execution | MCP path; no `npx` | -## Other ways to connect +## Other surfaces -Only if the user asked for models, REST, API keys, or extra skills. +Only if the user asked for models, REST, API keys, or extra skills: - [Getting Started](/guides/getting-started-with-aisa) - [Authentication](/guides/authentication) diff --git a/agent-skills/quickstart.mdx b/agent-skills/quickstart.mdx index fb32f554..c3015bb1 100644 --- a/agent-skills/quickstart.mdx +++ b/agent-skills/quickstart.mdx @@ -5,19 +5,33 @@ privacy: view: "public" --- -Copy this into the agent you already use. No API key to copy or manage. +Give this prompt to the agent you already use. No API key to copy or manage. + +## Copy setup prompt ```txt Set up AIsa using https://aisa.one/docs/agent-quickstart.md. ``` -The full connect flow — one official `aisa` skill, CLI or MCP, browser sign-in, and first-task rules — is [Agent Quickstart](/agent-quickstart). +You can append `Then use AIsa to …` in the same message. + +## What happens next + +1. The agent installs one official AIsa skill and reuses or installs the CLI, or connects through remote MCP if it cannot run commands. +2. You sign in with your browser. You should not copy a key from the dashboard. +3. After a real authenticated check succeeds, the agent reports **AIsa is connected.** + +## Optional first task + +After **AIsa is connected.**, tell your agent what to do. If you do not, it will ask what you want next. + +Example: `Find three recent public updates about a company and include source links.` A paid example runs only if you choose it. -If you are already following those steps, do not fetch this URL again and do not reinstall the same skill. +Setup installs and signs in. It is not approval to spend. -Official skill: [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills), slug `aisa`, file `search-research/aisa/SKILL.md`. +The agent follows [Agent Quickstart](/agent-quickstart). Official skill: [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills), slug `aisa`. -After AIsa is connected, keep using that skill. Extra catalog skills and authoring are optional: +Extra catalog skills and authoring are optional: - [Agent Skills catalog](/agent-skills) -- [Standards](/agent-skills/standards) — how `SKILL.md` works +- [Standards](/agent-skills/standards) diff --git a/zh/agent-quickstart.mdx b/zh/agent-quickstart.mdx index 3bc03f2d..e02baa31 100644 --- a/zh/agent-quickstart.mdx +++ b/zh/agent-quickstart.mdx @@ -3,96 +3,58 @@ title: "把 Agent 连接到 AIsa" description: "安装 AIsa Skill，登录，然后开始使用工具。" --- -把下面这句英文交给你正在使用的 Agent。没有需要复制或自行管理的 API Key。 +Set up AIsa. -## 复制接入提示词 +## 1. 选择或复用连接 -```txt -Set up AIsa using https://aisa.one/docs/agent-quickstart.md. -``` - -可以在同一句话后面加上 `Then use AIsa to …`。 - -## 接下来会发生什么 - - - - 如果当前环境可以运行终端命令，Agent 会安装一个官方 AIsa Skill，并复用或安装 `@aisa-one/cli` 0.5.0 或更高版本。 - - - `aisa login` 会在浏览器打开 AIsa 登录页。你不必从控制台复制 Key。 - - - 真实的已认证读取成功后，Agent 会报告 **AIsa is connected.** 然后继续你的任务，或选一个轻量例子。 - - - -如果 Agent 无法运行命令，就改为通过远程 MCP 和浏览器 OAuth 连接 AIsa。这条路径不要求 `npx`。 +若已有可用的 AIsa 连接，直接复用：官方 `aisa` Skill 加上有效的 CLI 认证，或已列出下方四个 Router 工具的统一 MCP。 -## 可选的首个任务 +只要当前环境能运行终端或 CLI 命令，就走 CLI。任意可用 shell 都可以，包括 PowerShell。不要求必须是 Bash。 -在 **AIsa is connected.** 之后，告诉 Agent 你想做什么。如果你没有说，它会问下一步要做什么。 - -例子：`Find three recent public updates about a company and include source links.` 付费示例只有在你选择时才会执行。 - - -接入流程只负责安装和登录，不等于批准消费。 - - ---- +没有可用的命令执行能力，或用户明确选择 MCP 时，走原生远程 MCP + OAuth。这条路径不要求 Node.js 或 `npx`。 -## Agent 接入步骤 +只为当前 harness 安装官方 `aisa` Skill。不要改用户的默认模型或其他无关客户端设置。 -把当前环境连接到 AIsa。如果你已经在读这些步骤，不要再抓取同一个 URL，也不要重复安装同一个 Skill。`aisa` Skill 落盘后，在当前会话读取它，了解何时使用 AIsa、四步工作流和消费规则。 - -### 识别环境 - -1. 复用已有的 AIsa 连接：官方 `aisa` Skill 加上有效的 CLI 认证，或已列出下方四个 Router 工具的统一 MCP。 -2. 只要当前环境能运行终端或 CLI 命令，就优先走 CLI。任意可用 shell 都可以，包括 PowerShell。不要求必须是 Bash。 -3. 没有可用的命令执行能力，或用户明确选择 MCP 时，走 MCP。这条路径不要求 Node.js 或 `npx`。 -4. 只为当前 harness 安装官方 `aisa` Skill。不要改无关的默认模型设置。 - -### CLI 路径 +## 2. CLI 路径 来源：[AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills)。Slug：`aisa`。文件：`search-research/aisa/SKILL.md`。 -未固定版本的 `npx skills` 需要 Node.js 22.20.0+（`skills` 1.5.25 的 `engines`；已在 22.22 验证）。已经能在 Node.js 18+ 上运行的 `@aisa-one/cli` 可以保留。 +为**当前** harness 安装一个官方 Skill： ```sh npx skills add AIsa-team/agent-skills --skill aisa --agent codex --global ``` -把 `--agent` 改成当前 harness（`codex`、`claude-code`、`cursor` 等）。个人通用接入建议 `--global`，除非用户要求限制在当前仓库。不要使用 `--all` 或 `*`。不要把 `aisa skills install` 当作默认安装方式。官方 Skill 已存在就复用，不要覆盖同名自定义 Skill。然后读取 Skill 并继续。 +把 `--agent` 改成当前 harness（`codex`、`claude-code`、`cursor` 等）。个人通用接入建议 `--global`，用户要求限制在当前仓库时用 project scope。不要使用 `--all` 或 `*`。不要覆盖同名自定义 Skill。官方 Skill 已存在就复用。 + +未固定版本的 `npx skills` 需要 Node.js **22.20.0+**（`skills` 1.5.25 的 `engines`；已在 22.22 验证）。`@aisa-one/cli` 仍可沿用 Node.js **18+** 下限。不要为了安装器替换已经能用的 CLI。 -如果缺少 `aisa`： +检查 `@aisa-one/cli` **0.5.0 或更高**。能用就复用。只有缺失时才安装： ```sh npm install -g @aisa-one/cli aisa --version ``` -复用 CLI **0.5.0 或更高**。不要降级。 +仅在已安装的 CLI 不受支持时升级。不要降级或重装已经能用的版本。 -除非已存储的密钥或 `AISA_API_KEY` 已经可用，否则运行 `aisa login`。CLI 会签发并保存密钥。`aisa login --no-browser` 仅用于 SSH / 本机无浏览器、且有交互 TTY 的情况。`AISA_API_KEY` 优先于已存储密钥；两者冲突时说明两个来源，不要盲目取消环境变量。永远不要打印原始密钥。 +用 `aisa balance` 检查认证。凭证缺失或被拒绝时，运行浏览器 `aisa login`，然后再跑 `aisa balance`。`aisa login --no-browser` 仅用于有交互 TTY 的 SSH / 本机无浏览器。`AISA_API_KEY` 优先于已存储密钥；两者冲突时说明两个来源，不要盲目取消环境变量。永远不要打印凭证。不要让用户去控制台复制 Key。 -`aisa whoami` 只检查本地。用真实的已认证读取证明认证，例如 `aisa balance`。然后报告 **AIsa is connected.** 余额为 0 → 去充值，不是缺 Key。登录或 mint 失败 → 展示错误并重试 `aisa login`，不要让用户去找 Key。 +`aisa whoami` 只检查本地，不能证明远端认证。 -### MCP 路径 +Skill 落盘后，在当前会话读取并继续。 -连接 AIsa 统一 Router，不要使用 `https://mcp.aisa.one/servers`，也不要把默认 `aisa connect` 的 web-search 服务器当成这个 Router。 +## 3. MCP 路径 -| 字段 | 值 | -| --- | --- | -| 名称 | AIsa | -| 服务器 URL | `https://tools.aisa.one/mcp` | -| 传输 | Streamable HTTP | -| 认证 | OAuth（由客户端发现；需要选择时选 OAuth） | +连接统一 AIsa Router：`https://tools.aisa.one/mcp`（Streamable HTTP，OAuth）。由客户端发现端点并保存/刷新 token。用户在浏览器完成登录。如果客户端要求，重新连接或启用 connector。 + +不要使用 `https://mcp.aisa.one/servers`，也不要把默认 `aisa connect` 的 web-search 服务器当成这个 Router。没有命令执行能力时不要要求 `npx`。 -**没有命令执行能力：** 不要要求 `npx`。在当前客户端的 connector 设置里添加上面的远程服务器，用 OAuth 登录，必要时返回后启用。如果客户端能原生安装 Skill，安装同一个 `aisa` Skill；否则继续，并说明 **并未持久安装**。 +如果客户端能原生安装 Skill，安装同一个 `aisa` Skill。如果不能，继续并说明 Skill **并未持久安装**。 Claude（个人 Pro/Max）按 Anthropic 的 [custom connectors 指南](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)：**Customize → Connectors → + → Add custom connector**，填入名称 `AIsa` 和 URL `https://tools.aisa.one/mcp`，**Add**，然后 **Connect** 并完成 OAuth。在对话里通过 **+ → Connectors** 启用。Team/Enterprise 由所有者配置，路径不同；以该指南为准。 -**用户明确选择 MCP、且有终端可用时的 Codex 示例。** 来自 Codex CLI 的 `codex mcp add --help` 和 `codex mcp login --help`： +用户明确选择 MCP、且有终端可用时的 Codex 示例，来自 Codex CLI `codex mcp add --help` 和 `codex mcp login --help`： ```sh codex mcp add aisa --url https://tools.aisa.one/mcp @@ -108,32 +70,33 @@ codex mcp login aisa --scopes openid,profile,email | `AISA_BATCH_QUOTE` | `aisa quote` | | `AISA_BATCH_USE` | `aisa call` | -### 连接成功之后 +## 4. 认证通过之后 + +只有认证已验证（CLI 路径上的 `aisa balance`，或 MCP 路径上 OAuth 完成且四个工具都在）才报告 **AIsa is connected.** 这不等于业务任务已完成。 + +如果用户已经说了任务，就继续该任务。否则询问 **What would you like to do first?** -报告 **AIsa is connected.** 这不等于业务任务已完成。按 `aisa` Skill 执行 search → 必要时 schema → quote → call。实时 help、schema 和 quote 是权威来源。`--input` 支持内联 JSON。 +按 `aisa` Skill 执行 search → 必要时 schema → quote → call。实时 help、schema 和 quote 是权威来源。`--input` 支持内联 JSON。 - -接入不是消费批准。复用仍然有效的明确授权。不要把缺少、失败、部分或估算的 quote 当成上限或免费。 +## Paid API approval first -之后的会话：加载同一个 Skill。不要重新跑 setup。 +接入不是消费批准。在 `call` / `AISA_BATCH_USE` 之前，需要匹配的 quote，以及覆盖该范围和费用的授权。复用仍然有效的明确授权。缺少、失败或部分的 quote 不是免费，也不是整批合计。估算费用不是保证上限。 -### 失败时怎么做 +## 5. 失败时怎么做 | 情况 | 下一步 | | --- | --- | | 浏览器登录未完成 | 等待；不要编造 Key | -| 登录或 mint 失败 | 展示错误；重试 `aisa login` | -| 凭证被拒绝或已过期 | `aisa login` | +| 凭证缺失、被拒绝或已过期 | `aisa login`，然后 `aisa balance` | | 网络或服务错误 | 展示实际原因；不要默认重新登录 | +| 余额为 0 | 去充值；不是缺 Key | | `AISA_API_KEY` 与已存储密钥冲突 | 说明两个来源 | -| 余额为 0 | 去充值 | | OAuth 后看不到 MCP 工具 | 刷新/重连；确认四个工具 | | Skill 已安装 | 复用 | -| 没有命令执行能力 | 走 MCP；不要要求 `npx` | -## 其他接入方式 +## 其他入口 -仅在用户明确要求模型、REST、API Key 或额外 Skill 时使用。 +仅在用户明确要求模型、REST、API Key 或额外 Skill 时使用： - [入门](/zh/guides/getting-started-with-aisa) - [认证](/zh/guides/authentication) diff --git a/zh/agent-skills/quickstart.mdx b/zh/agent-skills/quickstart.mdx index c83ff2d1..2eb32ea5 100644 --- a/zh/agent-skills/quickstart.mdx +++ b/zh/agent-skills/quickstart.mdx @@ -7,17 +7,31 @@ privacy: 把下面这句英文交给你正在使用的 Agent。没有需要复制或自行管理的 API Key。 +## 复制接入提示词 + ```txt Set up AIsa using https://aisa.one/docs/agent-quickstart.md. ``` -完整接入流程——一个官方 `aisa` Skill、CLI 或 MCP、浏览器登录，以及首个任务规则——见 [Agent 快速开始](/zh/agent-quickstart)。 +可以在同一句话后面加上 `Then use AIsa to …`。 + +## 接下来会发生什么 + +1. Agent 会安装一个官方 AIsa Skill，并复用或安装 CLI；如果无法运行命令，则通过远程 MCP 连接。 +2. 你在浏览器里登录。不必从控制台复制 Key。 +3. 真实的已认证检查成功后，Agent 会报告 **AIsa is connected.** + +## 可选的首个任务 + +在 **AIsa is connected.** 之后，告诉 Agent 你想做什么。如果你没有说，它会问下一步要做什么。 + +例子：`Find three recent public updates about a company and include source links.` 付费示例只有在你选择时才会执行。 -如果你已经在执行那些步骤，不要再抓取这个 URL，也不要重复安装同一个 Skill。 +接入只负责安装和登录，不等于批准消费。 -官方 Skill：[AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills)，slug `aisa`，文件 `search-research/aisa/SKILL.md`。 +Agent 会遵循 [Agent 快速开始](/zh/agent-quickstart)。官方 Skill：[AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills)，slug `aisa`。 -AIsa 连接成功后，继续使用该 Skill。额外的目录 Skill 和编写说明是可选的： +额外的目录 Skill 和编写说明是可选的： - [Agent Skills 目录](/zh/agent-skills) -- [标准](/zh/agent-skills/standards) — `SKILL.md` 如何工作 +- [标准](/zh/agent-skills/standards) From 8e0d61c2448c30a9d059a82148d36804e83cacb6 Mon Sep 17 00:00:00 2001 From: idan Date: Thu, 10 Sep 2026 00:14:19 +0800 Subject: [PATCH 07/18] docs: localize Agent setup headings while keeping approval anchor --- zh/agent-quickstart.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/zh/agent-quickstart.mdx b/zh/agent-quickstart.mdx index e02baa31..2be88452 100644 --- a/zh/agent-quickstart.mdx +++ b/zh/agent-quickstart.mdx @@ -3,7 +3,7 @@ title: "把 Agent 连接到 AIsa" description: "安装 AIsa Skill，登录，然后开始使用工具。" --- -Set up AIsa. +配置 AIsa。 ## 1. 选择或复用连接 @@ -78,7 +78,9 @@ codex mcp login aisa --scopes openid,profile,email 按 `aisa` Skill 执行 search → 必要时 schema → quote → call。实时 help、schema 和 quote 是权威来源。`--input` 支持内联 JSON。 -## Paid API approval first + + +## 付费 API 授权 接入不是消费批准。在 `call` / `AISA_BATCH_USE` 之前，需要匹配的 quote，以及覆盖该范围和费用的授权。复用仍然有效的明确授权。缺少、失败或部分的 quote 不是免费，也不是整批合计。估算费用不是保证上限。 From 772c95c1b0b728afed577ac3461b06734ec59c1e Mon Sep 17 00:00:00 2001 From: idan Date: Thu, 10 Sep 2026 00:24:03 +0800 Subject: [PATCH 08/18] docs: add HTTP API fallback with scoped paid-data approval XML Keep CLI/MCP on quote-and-scope rules. Use direct HTTP only when both are unavailable and an existing key is present; do not switch transport to bypass auth, credit, or outage. --- agent-quickstart.mdx | 56 ++++++++++++++++++++++++++++++++++++++--- zh/agent-quickstart.mdx | 52 ++++++++++++++++++++++++++++++++++---- 2 files changed, 100 insertions(+), 8 deletions(-) diff --git a/agent-quickstart.mdx b/agent-quickstart.mdx index 7db0180a..8863c83c 100644 --- a/agent-quickstart.mdx +++ b/agent-quickstart.mdx @@ -15,6 +15,15 @@ If there is no usable command execution, or the user explicitly prefers MCP, use Install only the official `aisa` skill for this harness. Do not change the user's default model or unrelated client settings. +If a step cannot run, do not jump to HTTP: + +1. Skill installer unavailable, but CLI works — continue with CLI/help in this session and say the skill is **not persistently installed**. +2. CLI unavailable — native MCP OAuth. +3. CLI and MCP both unavailable, HTTP requests are supported, **and** a valid existing AIsa API key or secret is already available — direct HTTP API fallback below. +4. No working API credentials — explain and recover auth (browser `aisa login` when a terminal exists). Do not invent a key or make unauthenticated calls. + +Auth rejection, exhausted credit, or a service outage is not fixed by switching transport. Do not extract or reuse client-owned MCP OAuth tokens. Browser `aisa login` remains the primary way to obtain credentials. Do not default to asking the user to create or paste a key. + ## 2. CLI path Source: [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills). Slug: `aisa`. File: `search-research/aisa/SKILL.md`. @@ -78,9 +87,7 @@ If the user already named a task, continue it. Otherwise ask **What would you li Follow the `aisa` skill for search → schema when needed → quote → call. Runtime help, schema, and quote are authoritative. Inline JSON is supported with `--input`. -## Paid API approval first - -Setup is not spending approval. Before `call` / `AISA_BATCH_USE`, use a matching quote and an authorization that covers that scope and cost. Reuse a still-valid explicit authorization. A missing, failed, or partial quote is not free and is not a full-batch total. Estimated cost is not a guaranteed cap. +Setup is not spending approval. For ordinary CLI `quote`/`call` and MCP `AISA_BATCH_QUOTE`/`AISA_BATCH_USE`, use a matching quote and an authorization that covers that scope and cost. Reuse a still-valid explicit authorization. A missing, failed, or partial quote is not free and is not a full-batch total. Estimated cost is not a guaranteed cap. Switching transport never grants permission. ## 5. If something fails @@ -93,6 +100,49 @@ Setup is not spending approval. Before `call` / `AISA_BATCH_USE`, use a matching | `AISA_API_KEY` conflicts with the stored key | Explain both sources | | MCP tools missing after OAuth | Refresh/reconnect; confirm the four tools | | Skill already installed | Reuse | +| Skill installer unavailable, CLI works | Continue via CLI/help; say no persistent Skill | +| CLI unavailable | MCP OAuth | +| CLI and MCP unavailable, existing key present | Direct HTTP API fallback | +| CLI and MCP unavailable, no key | Recover auth; do not invent a key | + +## Direct HTTP API fallback + +Use this only when CLI and MCP are both unavailable, HTTP requests are supported, and a valid existing AIsa API key or secret is already available. Do not treat auth rejection, exhausted credit, or an outage as a reason to switch here. + +Use the matching endpoint reference and published pricing. [API Reference](/api-reference). [Authentication](/guides/authentication). Data APIs: `https://api.aisa.one/apis/v1`. Model catalog: `https://api.aisa.one/v1/models`. Read [pricing](/guides/pricing) before any paid data request. + +Reuse `AISA_API_KEY` or the runtime secret store as a Bearer token. Never print it. Do not send a paid example request from this page. Success on `/v1/models` or other discovery does not prove authenticated business access. If there is no documented maximum or provider bound, or no auth, stop at that limitation. A changed endpoint, scope, or maximum needs new details and approval. + + + +## Paid API approval first + +This contract applies **only** to direct HTTP paid or data API fallback. It does not add a separate subsequent-message requirement to ordinary CLI or MCP quote/call. + +```xml + +``` + +The original task, or an "I approve" in the same planning turn, is not that subsequent approval. ## Other surfaces diff --git a/zh/agent-quickstart.mdx b/zh/agent-quickstart.mdx index 2be88452..13e866bd 100644 --- a/zh/agent-quickstart.mdx +++ b/zh/agent-quickstart.mdx @@ -15,6 +15,15 @@ description: "安装 AIsa Skill，登录，然后开始使用工具。" 只为当前 harness 安装官方 `aisa` Skill。不要改用户的默认模型或其他无关客户端设置。 +某一步跑不起来时，不要直接跳到 HTTP： + +1. Skill 安装器不可用，但 CLI 能用 — 本次会话用 CLI/help 继续，并说明 Skill **并未持久安装**。 +2. CLI 不可用 — 走原生 MCP OAuth。 +3. CLI 和 MCP 都不可用，当前环境能发 HTTP，**且** 已有有效的 AIsa API key/秘密 — 走下方直接 HTTP API 回退。 +4. 没有可用的 API 凭证 — 说明并恢复认证（有终端时用浏览器 `aisa login`）。不要编造 Key，也不要发未认证调用。 + +认证被拒、额度用尽或服务中断，不能靠换传输方式绕过。不要提取或复用客户端持有的 MCP OAuth token。获取凭证仍以浏览器 `aisa login` 为主。不要默认要用户去领取或粘贴 Key。 + ## 2. CLI 路径 来源：[AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills)。Slug：`aisa`。文件：`search-research/aisa/SKILL.md`。 @@ -78,11 +87,7 @@ codex mcp login aisa --scopes openid,profile,email 按 `aisa` Skill 执行 search → 必要时 schema → quote → call。实时 help、schema 和 quote 是权威来源。`--input` 支持内联 JSON。 - - -## 付费 API 授权 - -接入不是消费批准。在 `call` / `AISA_BATCH_USE` 之前，需要匹配的 quote，以及覆盖该范围和费用的授权。复用仍然有效的明确授权。缺少、失败或部分的 quote 不是免费，也不是整批合计。估算费用不是保证上限。 +接入不是消费批准。普通 CLI `quote`/`call` 和 MCP `AISA_BATCH_QUOTE`/`AISA_BATCH_USE` 仍要匹配的 quote，以及覆盖该范围和费用的授权。复用仍然有效的明确授权。缺少、失败或部分的 quote 不是免费，也不是整批合计。估算费用不是保证上限。换传输方式不等于授予权限。 ## 5. 失败时怎么做 @@ -95,6 +100,43 @@ codex mcp login aisa --scopes openid,profile,email | `AISA_API_KEY` 与已存储密钥冲突 | 说明两个来源 | | OAuth 后看不到 MCP 工具 | 刷新/重连；确认四个工具 | | Skill 已安装 | 复用 | +| Skill 安装器不可用但 CLI 能用 | 用 CLI/help 继续；说明未持久安装 Skill | +| CLI 不可用 | 走 MCP OAuth | +| CLI 与 MCP 都不可用，且已有 Key | 直接 HTTP API 回退 | +| CLI 与 MCP 都不可用，且没有 Key | 恢复认证；不要编造 Key | + +## 直接 HTTP API 回退 + +仅当 CLI 和 MCP 都不可用、能发 HTTP、且已有有效的 AIsa API key 或秘密时使用。认证被拒、额度用尽或故障，不能当成换到这里的理由。 + +使用匹配的 endpoint 文档和公开计价。[API 参考](/zh/api-reference)。[认证](/zh/guides/authentication)。数据 API：`https://api.aisa.one/apis/v1`。模型目录：`https://api.aisa.one/v1/models`。任何付费数据请求前先读 [计价](/zh/guides/pricing)。 + +复用 `AISA_API_KEY` 或 runtime secret store 作为 Bearer。永远不要打印它。不要从本页发起付费示例请求。`/v1/models` 或其他 discovery 成功不能证明已通过受保护的业务访问。没有已记录的最高上限 / provider 边界，或没有认证时，停在该限制。endpoint、scope 或最高费用变化时，需要新的明细与批准。 + + + +## 付费 API 授权 + +该合同**仅**适用于直接 HTTP 付费或数据 API 回退。不会给普通 CLI 或 MCP 的 quote/call 增加“必须另一条消息批准”。 + +```xml + +``` + +初始任务，或同一规划轮中的“我批准”，都不是那条后续批准消息。 ## 其他入口 From c38131ec1e5972c7f9b7c9a98dc6c0e1d49e1897 Mon Sep 17 00:00:00 2001 From: idan Date: Thu, 10 Sep 2026 00:26:40 +0800 Subject: [PATCH 09/18] docs: tighten HTTP fallback scope, business-call, and absolute docs URLs Limit the XML contract to costly data endpoints, allow public discovery without a key, keep one fallback ladder, and use aisa.one docs links in the raw Agent page. --- agent-quickstart.mdx | 12 +++++------- zh/agent-quickstart.mdx | 12 +++++------- 2 files changed, 10 insertions(+), 14 deletions(-) diff --git a/agent-quickstart.mdx b/agent-quickstart.mdx index 8863c83c..f6a74915 100644 --- a/agent-quickstart.mdx +++ b/agent-quickstart.mdx @@ -20,7 +20,7 @@ If a step cannot run, do not jump to HTTP: 1. Skill installer unavailable, but CLI works — continue with CLI/help in this session and say the skill is **not persistently installed**. 2. CLI unavailable — native MCP OAuth. 3. CLI and MCP both unavailable, HTTP requests are supported, **and** a valid existing AIsa API key or secret is already available — direct HTTP API fallback below. -4. No working API credentials — explain and recover auth (browser `aisa login` when a terminal exists). Do not invent a key or make unauthenticated calls. +4. No working API credentials — explain and recover auth (browser `aisa login` when a terminal exists). Do not invent a key or make unauthenticated business calls. Documented public docs, `/v1/models`, and discovery reads remain allowed. Auth rejection, exhausted credit, or a service outage is not fixed by switching transport. Do not extract or reuse client-owned MCP OAuth tokens. Browser `aisa login` remains the primary way to obtain credentials. Do not default to asking the user to create or paste a key. @@ -100,16 +100,14 @@ Setup is not spending approval. For ordinary CLI `quote`/`call` and MCP `AISA_BA | `AISA_API_KEY` conflicts with the stored key | Explain both sources | | MCP tools missing after OAuth | Refresh/reconnect; confirm the four tools | | Skill already installed | Reuse | -| Skill installer unavailable, CLI works | Continue via CLI/help; say no persistent Skill | -| CLI unavailable | MCP OAuth | -| CLI and MCP unavailable, existing key present | Direct HTTP API fallback | -| CLI and MCP unavailable, no key | Recover auth; do not invent a key | + +Transport fallback follows the four-step ladder in section 1. Do not copy it here. ## Direct HTTP API fallback Use this only when CLI and MCP are both unavailable, HTTP requests are supported, and a valid existing AIsa API key or secret is already available. Do not treat auth rejection, exhausted credit, or an outage as a reason to switch here. -Use the matching endpoint reference and published pricing. [API Reference](/api-reference). [Authentication](/guides/authentication). Data APIs: `https://api.aisa.one/apis/v1`. Model catalog: `https://api.aisa.one/v1/models`. Read [pricing](/guides/pricing) before any paid data request. +Use the matching endpoint reference and published pricing. [API Reference](https://aisa.one/docs/api-reference). [Authentication](https://aisa.one/docs/guides/authentication). Data APIs: `https://api.aisa.one/apis/v1`. Model catalog: `https://api.aisa.one/v1/models`. Read [pricing](https://aisa.one/docs/guides/pricing) before any paid data request. Reuse `AISA_API_KEY` or the runtime secret store as a Bearer token. Never print it. Do not send a paid example request from this page. Success on `/v1/models` or other discovery does not prove authenticated business access. If there is no documented maximum or provider bound, or no auth, stop at that limitation. A changed endpoint, scope, or maximum needs new details and approval. @@ -117,7 +115,7 @@ Reuse `AISA_API_KEY` or the runtime secret store as a Bearer token. Never print ## Paid API approval first -This contract applies **only** to direct HTTP paid or data API fallback. It does not add a separate subsequent-message requirement to ordinary CLI or MCP quote/call. +This contract applies **only** to direct HTTP calls to paid, dynamically priced, or potentially high-cost data endpoints. It does not apply to documented free discovery. It does not add a separate subsequent-message requirement to ordinary CLI or MCP quote/call. ```xml