diff --git a/agent-quickstart.mdx b/agent-quickstart.mdx index 51c4a370..2c180046 100644 --- a/agent-quickstart.mdx +++ b/agent-quickstart.mdx @@ -1,137 +1,119 @@ --- -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. +Set up AIsa. -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. +Reuse a working connection when one exists: the official `aisa` skill plus valid CLI auth, or unified MCP with `AISA_SEARCH_TOOL`, `AISA_BATCH_GET_SCHEMA`, `AISA_BATCH_QUOTE`, and `AISA_BATCH_USE`. Any working shell counts, including PowerShell. Install only the official `aisa` skill for this harness. Do not change unrelated model settings. Describe installs and credentials as in this agent environment. -Goal: get the agent to the smallest verifiable next step without loading broad documentation indexes. +## Install the official skill - -## IMPORTANT: Paid and high-cost API approval-first contract +Primary installer (Node.js **22.20.0+**; `skills` 1.5.25 `engines`): -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 - +```sh +npx skills add AIsa-team/agent-skills --skill aisa --agent codex --global ``` -**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. - -## Minimal setup facts - -AIsa provides two endpoint families: - -| 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` | - -For most model clients: - -```txt -base_url: https://api.aisa.one/v1 -api_key: $AISA_API_KEY +Set `--agent` to this harness (`codex`, `claude-code`, `cursor`, …). Prefer `--global` unless the user asked for this repo only. Do not use `--all` or `*`. + +If Node or `npx skills` cannot run, download the complete three files (`SKILL.md`, `LICENSE`, `agents/openai.yaml`) into this client's native Skill location. Preserve an existing official or custom skill, including a symlink; do not claim Web persistence without a native install. Codex user-level example: `~/.agents/skills/aisa`. + +```sh +set -e +aisa_skill_target="$HOME/.agents/skills/aisa" +aisa_skill_parent="$HOME/.agents/skills" +aisa_skill_base="https://raw.githubusercontent.com/AIsa-team/agent-skills/0332d85b282c4fe271fc4df18f8393a5d4993ca9/platform/aisa" +if [ -e "$aisa_skill_target" ] || [ -L "$aisa_skill_target" ]; then + echo "exists, left unchanged: $aisa_skill_target" + echo "not assumed official; inspect before treating as the AIsa skill" + exit 0 +fi +aisa_skill_tmp="$(mktemp -d)" +trap 'rm -rf "$aisa_skill_tmp"' EXIT +mkdir -p "$aisa_skill_tmp/aisa/agents" "$aisa_skill_parent" +curl -fSL "$aisa_skill_base/SKILL.md" -o "$aisa_skill_tmp/aisa/SKILL.md" +curl -fSL "$aisa_skill_base/LICENSE" -o "$aisa_skill_tmp/aisa/LICENSE" +curl -fSL "$aisa_skill_base/agents/openai.yaml" -o "$aisa_skill_tmp/aisa/agents/openai.yaml" +mv "$aisa_skill_tmp/aisa" "$aisa_skill_target" ``` -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. +## CLI + +Reuse `@aisa-one/cli` **0.5.0 or later** if it works. Install only if it is absent. Do not downgrade. CLI may keep its Node.js **18+** floor; do not replace a working CLI to match the Skill installer. -```bash -export AISA_API_KEY="" +```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. +After the skill is on disk, read it in this session. For sign-in, follow that skill and `aisa login --help`. Check authentication with `aisa balance`. `aisa whoami` is local only. `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. Browser `aisa login` remains the primary way to obtain credentials. -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. +## MCP -## Choose one path +When this environment cannot run CLI commands, or the user prefers MCP, connect `https://tools.aisa.one/mcp` (Streamable HTTP, OAuth). The client owns browser sign-in and tokens. Do not require `npx`. Do not use `https://mcp.aisa.one/servers` or the default `aisa connect` web-search server. Connection succeeds only after OAuth completed **and** `AISA_SEARCH_TOOL`, `AISA_BATCH_GET_SCHEMA`, `AISA_BATCH_QUOTE`, and `AISA_BATCH_USE` are present. Metadata or a `401` challenge is not a protected call. -First identify what the user wants, then read only the docs for that path. +## After AIsa is connected -| User wants | Read next | -| --- | --- | -| 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 | +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?** Follow the `aisa` skill. Setup is not spending approval. -## Agent behavior +If the quote or documented maximum exceeds the remaining approved cap, stop. Do not ask the user to approve that same endpoint under an insufficient cap. -- 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. +Do not jump to HTTP to bypass missing credentials, exhausted credit, or an outage of the same API. A CLI/MCP client or router limitation may still allow the direct HTTP fallback below; do not use a paid request to probe availability. Do not extract or reuse client-owned MCP OAuth tokens. -## Verify the setup +## Direct HTTP API fallback -Start with a read-only request that checks connectivity and authentication without invoking a model: +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. Use this for a client, tooling, or router limitation; it does not bypass invalid API credentials, exhausted credit, or a failure of the same underlying API. -```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" -``` +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. -`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. +Before presenting a paid request or cost proposal for approval, read the selected endpoint's full reference, or the matching OpenAPI operation, including parameters and charging rules. A catalog, index, or pricing overview is not the endpoint contract. -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. +Send the key as a Bearer token. 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. -## Evidence rule for research tasks +### API key -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. +Reuse `AISA_API_KEY`. If it is unset and this agent can read the filesystem, use `~/.aisa/key` from `aisa login` without displaying it. Otherwise use an AIsa API key already in this client's authorized secret store. If sources conflict, explain them; do not overwrite a custom key. -```txt -Search results are discovery. -Fetched source pages are evidence to evaluate. -Generated summaries are synthesis, not evidence. -``` +If none of those exist and `aisa login` is usable, run browser `aisa login` so the key is stored automatically. If there is no usable CLI or browser-login path, the last option is for the user to sign in at https://console.aisa.one/api-keys, create a key, and save it in this client's credential or secret settings, or as local `AISA_API_KEY`. Do not ask them to paste the key into chat. Do not print it. Not every client has a secret UI; if this client cannot store a credential, stop there. -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. +Wait for credentials before protected API requests. Obtaining a key is not paid-call approval. -## Copy prompt +## Paid API approval first -Copy this prompt into an agent environment: +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. -```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. +```xml + ``` -## Fallback discovery +The original task, or an "I approve" in the same planning turn, is not that subsequent approval. + +## Other surfaces -Use these only when the targeted docs above are not enough: +Only if the user asked for models, REST, API keys, or extra skills: -- [`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. +- [Getting Started](https://aisa.one/docs/guides/getting-started-with-aisa) +- [Authentication](https://aisa.one/docs/guides/authentication) +- [Models](https://aisa.one/docs/guides/models) +- [API Reference](https://aisa.one/docs/api-reference) +- [Agent Skills catalog](https://aisa.one/docs/agent-skills) diff --git a/agent-skills/quickstart.mdx b/agent-skills/quickstart.mdx index 80539ef6..c3015bb1 100644 --- a/agent-skills/quickstart.mdx +++ b/agent-skills/quickstart.mdx @@ -1,173 +1,37 @@ --- 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. +Give this prompt to the agent you already use. No API key to copy or manage. -## Prerequisites +## Copy setup prompt -- 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: +You can append `Then use AIsa to …` in the same message. -```bash -export AISA_API_KEY="YOUR_AISA_API_KEY" -``` +## What happens next -Check your auth status at any time: +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.** -```bash -aisa whoami -``` +## Optional first task ---- - -## Step 3: Browse available skills - -```bash -aisa skills list -``` +After **AIsa is connected.**, tell your agent what to do. If you do not, it will ask what you want next. -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 -``` - ---- - -## Step 4: Install a skill - -```bash -aisa skills install search -``` - -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: - -```text -✓ ~/.claude/skills/ (claude) -✓ ~/.cursor/skills/ (cursor) -Skill 'search' installed to 2 agent(s) -``` - -To install only for a specific agent: - -```bash -aisa skills install search --agent claude -``` +Example: `Find three recent public updates about a company and include source links.` A paid example runs only if you choose it. -To install for all supported agents regardless of what's detected: +Setup installs and signs in. It is not approval to spend. -```bash -aisa skills install search --agent all -``` - ---- - -## Step 5: Use the skill - -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: - -```text -Search the web for the latest news on AI agent frameworks and summarise the top three stories. -``` - -The agent reads the `search` skill description, loads the full `SKILL.md` instructions, and calls the AIsa search API using your key. - ---- - -## Step 6: Install multiple skills - -```bash -aisa skills install market -aisa skills install twitter -aisa skills install media-gen -``` - -Once multiple skills are installed, your agent can use whichever is appropriate for any given task — without you specifying which skill to use. - ---- - -## Managing installed skills - -```bash -# List skills available in the registry -aisa skills list - -# Remove a skill from all agent directories -aisa skills remove market - -# Remove from a specific agent only -aisa skills remove market --agent cursor -``` - ---- - -## Create your own skill - -Scaffold a new skill from a template: - -```bash -# Default blank template -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 -``` - -To share your skill with the community, submit a pull request to [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills). - ---- +The agent follows [Agent Quickstart](/agent-quickstart). Official skill: [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills), slug `aisa`. -## What's next +Extra catalog skills and authoring are optional: -- [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 Skills catalog](/agent-skills) +- [Standards](/agent-skills/standards) diff --git a/zh/agent-quickstart.mdx b/zh/agent-quickstart.mdx index bd6fc924..8632e83e 100644 --- a/zh/agent-quickstart.mdx +++ b/zh/agent-quickstart.mdx @@ -1,131 +1,115 @@ --- -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 编写的页面作为导航。 +配置 AIsa。 -本页用于定位相关技术来源，不是独立证据。阅读本页不代表用户授权 Agent 修改其环境或发起计费请求。 +若已有可用连接，直接复用：官方 `aisa` Skill 加上有效的 CLI 认证，或已具备 `AISA_SEARCH_TOOL`、`AISA_BATCH_GET_SCHEMA`、`AISA_BATCH_QUOTE`、`AISA_BATCH_USE` 的统一 MCP。任意可用 shell 都可以，包括 PowerShell。只为当前 harness 安装官方 `aisa` Skill。不要改无关模型设置。安装和凭证按当前 Agent 环境描述。 -目标：让 Agent 走到**最小且可验证**的下一步，而不是一次性加载完整文档索引。 +## 安装官方 Skill - -## 重要：付费和高成本 API 的先批准后执行合同 +首选安装器（Node.js **22.20.0+**；`skills` 1.5.25 的 `engines`）： -该合同适用于每一个付费、动态计价或可能高成本的 API endpoint，无论它是直接调用、通过 Agent Skill，还是通过 MCP 数据工具调用。 - -```xml - +```sh +npx skills add AIsa-team/agent-skills --skill aisa --agent codex --global ``` -**典型场景 — SimilarWeb：** 请读取匹配 endpoint 的 [`x-aisa-pricing`](https://aisa.one/openapi.yaml) 元数据；只有请求可界定时才计算成本，并在数据调用前取得明确批准。 - -## 最小设置事实 - -AIsa 提供两类端点： +把 `--agent` 改成当前 harness（`codex`、`claude-code`、`cursor` 等）。个人通用接入建议 `--global`，除非用户要求限制在当前仓库。不要使用 `--all` 或 `*`。 + +如果 Node 或 `npx skills` 跑不起来，把完整三文件（`SKILL.md`、`LICENSE`、`agents/openai.yaml`）下载到当前客户端的原生 Skill 位置。保留已有的官方或自定义 Skill（包括符号链接）；没有原生安装就不要声称 Web 端已持久化。Codex 用户级示例：`~/.agents/skills/aisa`。 + +```sh +set -e +aisa_skill_target="$HOME/.agents/skills/aisa" +aisa_skill_parent="$HOME/.agents/skills" +aisa_skill_base="https://raw.githubusercontent.com/AIsa-team/agent-skills/0332d85b282c4fe271fc4df18f8393a5d4993ca9/platform/aisa" +if [ -e "$aisa_skill_target" ] || [ -L "$aisa_skill_target" ]; then + echo "exists, left unchanged: $aisa_skill_target" + echo "not assumed official; inspect before treating as the AIsa skill" + exit 0 +fi +aisa_skill_tmp="$(mktemp -d)" +trap 'rm -rf "$aisa_skill_tmp"' EXIT +mkdir -p "$aisa_skill_tmp/aisa/agents" "$aisa_skill_parent" +curl -fSL "$aisa_skill_base/SKILL.md" -o "$aisa_skill_tmp/aisa/SKILL.md" +curl -fSL "$aisa_skill_base/LICENSE" -o "$aisa_skill_tmp/aisa/LICENSE" +curl -fSL "$aisa_skill_base/agents/openai.yaml" -o "$aisa_skill_tmp/aisa/agents/openai.yaml" +mv "$aisa_skill_tmp/aisa" "$aisa_skill_target" +``` -| 用途 | 端点 | -| --- | --- | -| OpenAI 兼容聊天、模型路由、SDK | `https://api.aisa.one/v1` | -| AIsa 数据 API 与非聊天能力 API | `https://api.aisa.one/apis/v1` | +## CLI -大多数模型客户端只需要： +复用已经能用的 `@aisa-one/cli` **0.5.0 或更高**。只有缺失时才安装。不要降级。CLI 仍可沿用 Node.js **18+** 下限；不要为了 Skill 安装器替换已经能用的 CLI。 -```txt -base_url: https://api.aisa.one/v1 -api_key: $AISA_API_KEY +```sh +npm install -g @aisa-one/cli +aisa --version ``` -API key 作为 Bearer token 使用。不要打印、记录、提交或硬编码密钥。优先使用环境变量或 Agent runtime 的 secret store。 +Skill 落盘后，在当前会话读取它。登录请遵循该 Skill 和 `aisa login --help`。用 `aisa balance` 检查认证。`aisa whoami` 只检查本地。`AISA_API_KEY` 优先于已存储密钥；两者冲突时说明两个来源，不要盲目取消环境变量。永远不要打印凭证。不要让用户去控制台复制 Key。获取凭证仍以浏览器 `aisa login` 为主。 -```bash -export AISA_API_KEY="YOUR_AISA_API_KEY" -``` +## MCP -如果用户还没有提供 key，请说明到哪里创建，而不是编造一个看似真实的占位值。 +当前环境不能跑 CLI 命令，或用户更想用 MCP 时，连接 `https://tools.aisa.one/mcp`（Streamable HTTP，OAuth）。由客户端完成浏览器登录并保存 token。不要要求 `npx`。不要使用 `https://mcp.aisa.one/servers` 或默认 `aisa connect` 的 web-search。只有 OAuth 已完成，**并且** `AISA_SEARCH_TOOL`、`AISA_BATCH_GET_SCHEMA`、`AISA_BATCH_QUOTE`、`AISA_BATCH_USE` 都在，才算连接成功。metadata 或 `401` 挑战不是受保护调用。 -请选择当前模型支持的 endpoint。通过[模型目录](/zh/guides/models)或对应 API reference 确认，不要根据模型名称猜测应使用 `chat/completions`、`responses`、`messages` 还是媒体 endpoint。 +## 连接成功之后 -## 选择一条路径 +只有认证已验证（CLI 路径上的 `aisa balance`，或 MCP 路径上 OAuth 完成且四个工具都在）才报告 **AIsa is connected.** 这不等于业务任务已完成。如果用户已经说了任务，就继续该任务。否则询问 **What would you like to do first?** 遵循 `aisa` Skill。接入不是消费批准。 -先判断用户要做什么，然后只读对应文档。 +如果 quote 或已记录的最高费用超过剩余已批准额度，就停止。不要在额度不足时仍请用户批准同一 endpoint。 -| 用户想做 | 下一步阅读 | -| --- | --- | -| 基础账号/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 页 | +不要为了绕过缺凭证、额度用尽或同一 API 故障而跳到 HTTP。CLI/MCP 客户端或路由器限制时，下方直接 HTTP 回退仍可能可用；不要用付费请求探测可用性。不要提取或复用客户端持有的 MCP OAuth token。 -## Agent 行为准则 +## 直接 HTTP API 回退 -- 只有目标路径不清楚时，才问一个澄清问题。 -- 只加载完成任务所需的最小文档集合。 -- 不要打开无关 API 页面。 -- 简短总结和链接足够时，不要把大段文档粘贴进对话。 -- 让所选模型与有明确记录的 endpoint 匹配，不要根据名称推断路由支持情况。 -- 修改文件、安装软件或发送计费请求前，先说明操作并获得用户确认。 -- 声称配置可用前，完成下面对应的检查。 -- 对于密钥，只验证存储方式，不展示密钥本身。 +仅当 CLI 和 MCP 都不可用、能发 HTTP、且已有有效的 AIsa API key 或秘密时使用。这条路径用于客户端、工具或路由器限制；不能绕过无效 API 凭证、额度用尽或同一底层 API 的故障。 -## 验证设置 +使用匹配的 endpoint 文档和公开计价。[API 参考](https://aisa.one/docs/zh/api-reference)。[认证](https://aisa.one/docs/zh/guides/authentication)。数据 API：`https://api.aisa.one/apis/v1`。模型目录：`https://api.aisa.one/v1/models`。任何付费数据请求前先读 [计价](https://aisa.one/docs/zh/guides/pricing)。 -先通过只读请求检查网络和认证，不调用模型： +在提出付费请求或费用方案供批准之前，先读所选 endpoint 的完整参考（或对应的 OpenAPI operation），包括参数和计费规则。目录、索引或计价总览不是该 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" -``` - -`HTTP 200` 表示 API 已接受该 key 并返回模型目录。`401` 或 `403` 表示认证或访问权限存在问题。此检查不能证明某个具体模型支持客户端使用的请求协议。 +把密钥作为 Bearer 发送。不要从本页发起付费示例请求。`/v1/models` 或其他 discovery 成功不能证明已通过受保护的业务访问。没有已记录的最高上限 / provider 边界，或没有认证时，停在该限制。endpoint、scope 或最高费用变化时，需要新的明细与批准。 -用户选定模型并同意可能产生费用的请求后，再执行对应 API reference 中最小的示例请求。不要仅根据文档就声称设置已经可用。 +### API key -## 研究任务的证据规则 +复用 `AISA_API_KEY`。若未设置且本 Agent 能读文件系统，使用 `aisa login` 写入的 `~/.aisa/key`，不要显示它。否则使用当前客户端已授权密钥库中的 AIsa API key。来源冲突时说明两边，不要覆盖用户自定义密钥。 -本快速开始是路由摘要，不是精确请求 schema、当前模型可用性、价格或服务状态的权威来源。请通过链接的 API reference、实时目录或运行结果核实这些信息。 +以上都没有、且 `aisa login` 可用时，运行浏览器 `aisa login` 自动保存密钥。若没有可用的 CLI 或浏览器登录路径，最后一步是用户到 https://console.aisa.one/api-keys 登录并创建密钥，保存到当前客户端的凭证/密钥设置，或本地 `AISA_API_KEY`。不要让用户把密钥粘贴进对话。不要打印密钥。不是每个客户端都有密钥设置界面；若当前客户端无法保存凭证，就停在该限制。 -```txt -搜索结果是发现线索。 -抓取的来源页面是待评估的证据。 -生成摘要是综合判断，不是证据。 -``` +受保护的 API 请求前先等到凭证就绪。拿到密钥不等于付费调用已获批准。 -抓取页面只能证明该来源表达了什么。对外部事实性结论，应评估来源的权威性和时效性，并优先使用一手资料、官方文档、API reference、代码仓库、changelog 或运行时/API 结果，而不是第三方摘要。 + -## 可复制的提示词 +## 付费 API 授权 -把下面这段复制到 Agent 环境： +该合同**仅**适用于直接 HTTP 访问付费、动态计价或可能高成本的数据 endpoint。不适用于已记录的免费 discovery。不会给普通 CLI 或 MCP 的 quote/call 增加“必须另一条消息批准”。 -```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. +```xml + ``` -## 兜底发现入口 +初始任务，或同一规划轮中的“我批准”，都不是那条后续批准消息。 + +## 其他入口 -仅当上面的定向文档不够时再使用： +仅在用户明确要求模型、REST、API Key 或额外 Skill 时使用： -- [`llms.txt`](https://aisa.one/docs/llms.txt)：用于定位相关页面的精选技术索引，不是设置流程中的必读内容。 -- [`llms-full.txt`](https://aisa.one/docs/llms-full.txt)：完整文档包。默认不要摄取；仅在用户明确要求完整文档或定向页面不足时使用。 +- [入门](https://aisa.one/docs/zh/guides/getting-started-with-aisa) +- [认证](https://aisa.one/docs/zh/guides/authentication) +- [模型](https://aisa.one/docs/zh/guides/models) +- [API 参考](https://aisa.one/docs/zh/api-reference) +- [Agent Skills 目录](https://aisa.one/docs/zh/agent-skills) diff --git a/zh/agent-skills/quickstart.mdx b/zh/agent-skills/quickstart.mdx index 27b7a1f1..2eb32ea5 100644 --- a/zh/agent-skills/quickstart.mdx +++ b/zh/agent-skills/quickstart.mdx @@ -1,173 +1,37 @@ --- title: "Agent Skills 快速入门" -description: "安装 AIsa CLI，使用 API Key 完成身份认证，并将可复用的 Agent Skills 添加到 Claude Code、Cursor、Codex、OpenClaw 和其他受支持的智能体。" +description: "安装官方 AIsa Skill，登录，然后在你的 Agent 里开始使用 AIsa。" privacy: view: "public" --- -本指南将带你在大约五分钟内从零开始安装并使用一个 Skill。 +把下面这句英文交给你正在使用的 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. ``` -也可以设置环境变量，它的优先级高于已存储的密钥： +可以在同一句话后面加上 `Then use AIsa to …`。 -```bash -export AISA_API_KEY="YOUR_AISA_API_KEY" -``` +## 接下来会发生什么 -随时检查身份认证状态： +1. Agent 会安装一个官方 AIsa Skill，并复用或安装 CLI；如果无法运行命令，则通过远程 MCP 连接。 +2. 你在浏览器里登录。不必从控制台复制 Key。 +3. 真实的已认证检查成功后，Agent 会报告 **AIsa is connected.** -```bash -aisa whoami -``` +## 可选的首个任务 ---- - -## 第 3 步：浏览可用 Skills - -```bash -aisa skills list -``` +在 **AIsa is connected.** 之后，告诉 Agent 你想做什么。如果你没有说，它会问下一步要做什么。 -该命令会从 [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 -``` - ---- - -## 第 4 步：安装 Skill - -```bash -aisa skills install search -``` - -CLI 会自动检测你机器上的每个受支持智能体，并将 Skill 写入各自的 Skills 目录。你会看到每个智能体对应的一行确认信息： - -```text -✓ ~/.claude/skills/ (claude) -✓ ~/.cursor/skills/ (cursor) -Skill 'search' installed to 2 agent(s) -``` - -如果只想为特定智能体安装： - -```bash -aisa skills install search --agent claude -``` +例子：`Find three recent public updates about a company and include source links.` 付费示例只有在你选择时才会执行。 -如果想忽略自动检测结果，为所有受支持的智能体安装： +接入只负责安装和登录，不等于批准消费。 -```bash -aisa skills install search --agent all -``` - ---- - -## 第 5 步：使用 Skill - -在智能体中打开一个**新会话**。Skills 会在会话启动时加载，而不是在会话进行途中加载。然后让智能体执行该 Skill 能处理的任务： - -```text -Search the web for the latest news on AI agent frameworks and summarise the top three stories. -``` - -智能体会读取 `search` Skill 的 `description`，加载完整的 `SKILL.md` 指令，并使用你的密钥调用 AIsa 搜索 API。 - ---- - -## 第 6 步：安装多个 Skills - -```bash -aisa skills install market -aisa skills install twitter -aisa skills install media-gen -``` - -安装多个 Skills 后，智能体可以根据具体任务自动选择合适的 Skill，无需你指定使用哪一个。 - ---- - -## 管理已安装的 Skills - -```bash -# List skills available in the registry -aisa skills list - -# Remove a skill from all agent directories -aisa skills remove market - -# Remove from a specific agent only -aisa skills remove market --agent cursor -``` - ---- - -## 创建自己的 Skill - -使用模板搭建一个新 Skill： - -```bash -# Default blank template -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 -``` - -如需与社区分享你的 Skill，请向 [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills) 提交 Pull Request。 - ---- +Agent 会遵循 [Agent 快速开始](/zh/agent-quickstart)。官方 Skill：[AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills)，slug `aisa`。 -## 下一步 +额外的目录 Skill 和编写说明是可选的： -- [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 Skills 目录](/zh/agent-skills) +- [标准](/zh/agent-skills/standards)