From 028ba37296ca80e143323360779832fdb4a93d84 Mon Sep 17 00:00:00 2001 From: idan Date: Mon, 14 Sep 2026 22:05:56 +0800 Subject: [PATCH 1/2] docs: pin canonical AIsa skill.md and current credential guidance Mintlify root skill.md overrides the auto REST skill from Skill e780949; LICENSE is inlined. Co-authored-by: Cursor --- agent-quickstart-fallbacks.mdx | 8 +- agent-quickstart.mdx | 2 +- scripts/sync_canonical_aisa_skill.py | 107 +++++++++++++++++++++++++++ skill.md | 70 ++++++++++++++++++ zh/agent-quickstart-fallbacks.mdx | 8 +- zh/agent-quickstart.mdx | 2 +- 6 files changed, 187 insertions(+), 10 deletions(-) create mode 100644 scripts/sync_canonical_aisa_skill.py create mode 100644 skill.md diff --git a/agent-quickstart-fallbacks.mdx b/agent-quickstart-fallbacks.mdx index 90c04f3..c8e89a7 100644 --- a/agent-quickstart-fallbacks.mdx +++ b/agent-quickstart-fallbacks.mdx @@ -7,13 +7,13 @@ Do not use this page as the default setup. Return to [Agent Quickstart](https:// ## Skill download (curl) -**Gate:** Node or `npx skills` cannot run, you need the official `aisa` skill on disk, and either this is a user-local machine **or** the user explicitly prefers CLI/Skill in this environment (including a cloud sandbox). 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`. The primary installer remains Node.js **22.20.0+** and `skills` 1.5.25 `engines`; this curl path does not change those floors. +**Gate:** Node or `npx skills` cannot run, you need the official `aisa` skill on disk, and either this is a user-local machine **or** the user explicitly prefers CLI/Skill in this environment (including a cloud sandbox). 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`. The primary installer remains Node.js **22.20.0+** and `skills` 1.5.25 `engines`; this curl path does not change those floors. The raw GitHub pin is Skill commit `e7809490a186af77c4b96a5c1cfeea1ee39ce4f9`; merge that Skill change before this page. ```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/7d7b1267f4363d894528f5c5b8d895214211cb84/platform/aisa" +aisa_skill_base="https://raw.githubusercontent.com/AIsa-team/agent-skills/e7809490a186af77c4b96a5c1cfeea1ee39ce4f9/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" @@ -42,9 +42,9 @@ Send the key as a Bearer token. Do not send a paid example request from this pag ### API key -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. +Reuse `AISA_API_KEY`. Do not read `tokens.json` or compatibility key files. If `aisa login` is usable, run browser `aisa login` so the CLI stores credentials. 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. -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. +If none of those exist and 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. Wait for credentials before protected API requests. Obtaining a key is not paid-call approval. diff --git a/agent-quickstart.mdx b/agent-quickstart.mdx index 05f7705..2286a43 100644 --- a/agent-quickstart.mdx +++ b/agent-quickstart.mdx @@ -27,7 +27,7 @@ npm install -g @aisa-one/cli aisa --version ``` -Reuse `@aisa-one/cli` **0.5.0 or later** if present; otherwise install; do not downgrade. CLI may keep Node.js **18+**. Read the on-disk skill. Sign in via that skill and `aisa login --help`. Prove auth with `aisa balance`. `aisa whoami` is local only. `AISA_API_KEY` overrides the stored key; if they conflict, explain both. Never print credentials or send the user to copy a dashboard key. Browser `aisa login` is the primary credential path. +Reuse `@aisa-one/cli` **0.5.0 or later** if present; otherwise install; do not downgrade. CLI may keep Node.js **18+**. Read the on-disk skill. Sign in via that skill and `aisa login --help`. Prove auth with `aisa balance`. `aisa whoami` may refresh stored tokens and is not protected auth proof. `AISA_API_KEY` overrides stored CLI credentials and never refreshes; if they conflict, explain both. Never print credentials, read token files, or send the user to copy a dashboard key. Browser `aisa login` is the primary credential path. ## Cloud diff --git a/scripts/sync_canonical_aisa_skill.py b/scripts/sync_canonical_aisa_skill.py new file mode 100644 index 0000000..9e72b2a --- /dev/null +++ b/scripts/sync_canonical_aisa_skill.py @@ -0,0 +1,107 @@ +#!/usr/bin/env python3 +"""Export AIsa-team/agent-skills platform/aisa into the Mintlify root skill.md. + +Mintlify overrides the auto-generated Docs skill with a repo-root skill.md. +This copies a pinned canonical SKILL.md and inlines LICENSE so the published +file has no missing relative targets. Merge the Skill commit before this pin. +""" +from __future__ import annotations + +import argparse +import hashlib +import sys +from pathlib import Path + +SOURCE_SHA = "e7809490a186af77c4b96a5c1cfeea1ee39ce4f9" +SOURCE_SKILL = "platform/aisa/SKILL.md" +SOURCE_LICENSE = "platform/aisa/LICENSE" +EXPORTED = "skill.md" +EXPORTED_SHA256 = "5d46448dee7901c1a687d4b1f49716d3d87555bbfb87ed022823e5afa9e4f15a" +LICENSE_LINK = "MIT — see [LICENSE](LICENSE)." + +STALE_GUIDANCE = ( + ("agent-quickstart.mdx", "whoami` is local only"), + ("zh/agent-quickstart.mdx", "whoami` 只检查本地"), + ("agent-quickstart-fallbacks.mdx", "~/.aisa/key"), + ("zh/agent-quickstart-fallbacks.mdx", "~/.aisa/key"), +) + + +def export_text(skill: str, license_text: str) -> str: + if LICENSE_LINK not in skill: + raise SystemExit(f"{SOURCE_SKILL} is missing the LICENSE relative link") + inlined = "MIT. Full license text:\n\n" + license_text.strip() + "\n" + return skill.replace(LICENSE_LINK, inlined) + + +def write_export(root: Path, text: str) -> Path: + path = root / EXPORTED + path.write_text(text, encoding="utf-8") + return path + + +def check_guidance(root: Path) -> list[str]: + errors: list[str] = [] + for rel, stale in STALE_GUIDANCE: + text = (root / rel).read_text(encoding="utf-8") + if stale in text: + errors.append(f"{rel}: still contains {stale!r}") + return errors + + +def main() -> int: + parser = argparse.ArgumentParser() + parser.add_argument("--root", type=Path, default=Path.cwd()) + parser.add_argument("--source-dir", type=Path, help="platform/aisa directory at the pinned SHA") + parser.add_argument("--check", action="store_true") + args = parser.parse_args() + root = args.root.resolve() + source_dir = args.source_dir.resolve() if args.source_dir else None + + errors = check_guidance(root) + exported = root / EXPORTED + + if args.check: + if not exported.is_file(): + errors.append(f"missing {EXPORTED}") + else: + actual = exported.read_text(encoding="utf-8") + digest = hashlib.sha256(actual.encode()).hexdigest() + if digest != EXPORTED_SHA256: + errors.append(f"{EXPORTED} sha256 {digest} != pinned {EXPORTED_SHA256}") + if LICENSE_LINK in actual: + errors.append(f"{EXPORTED} still has a relative LICENSE link") + if source_dir is not None: + expected = export_text( + (source_dir / "SKILL.md").read_text(encoding="utf-8"), + (source_dir / "LICENSE").read_text(encoding="utf-8"), + ) + if actual != expected: + errors.append(f"{EXPORTED} drifted from source-dir at {SOURCE_SHA}") + if errors: + print("canonical aisa skill check failed:", file=sys.stderr) + for error in errors: + print(f"- {error}", file=sys.stderr) + return 1 + print(f"{EXPORTED} matches {SOURCE_SHA}; guidance stale strings absent") + return 0 + + if source_dir is None: + raise SystemExit("--source-dir is required to write the export") + text = export_text( + (source_dir / "SKILL.md").read_text(encoding="utf-8"), + (source_dir / "LICENSE").read_text(encoding="utf-8"), + ) + path = write_export(root, text) + digest = hashlib.sha256(text.encode()).hexdigest() + print(f"wrote {path.relative_to(root)} from {SOURCE_SHA} sha256={digest}") + if errors: + print("guidance still has stale strings:", file=sys.stderr) + for error in errors: + print(f"- {error}", file=sys.stderr) + return 1 + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/skill.md b/skill.md new file mode 100644 index 0000000..0999ab7 --- /dev/null +++ b/skill.md @@ -0,0 +1,70 @@ +--- +name: aisa +description: "Discover and invoke published AIsa tools with the AIsa CLI (search, schema, quote, call) or unified MCP. Use when the user wants AIsa tools or sign-in, or needs current web, company, or social data AIsa tools can fetch—even if they do not name AIsa. Do not use for OpenClaw Chinese model provider setup (aisa-provider), installing other catalog skills, or work that does not need live AIsa data." +license: MIT +--- + +# AIsa + +If you are already reading this skill, continue the current task. Do not reinstall it, reread setup docs, or relogin a working connection. + +If the user named another tool, or a dedicated local tool already covers the job, do not force AIsa. + +First-time install and connect: https://aisa.one/docs/agent-quickstart.md + +## Reuse + +Reuse a working official `aisa` skill, `@aisa-one/cli` **0.5.0 or later**, stored CLI credentials, or a unified MCP session. An explicit user transport choice or a still-authorized connection wins. Otherwise prefer the CLI on a user-local machine (PowerShell counts); prefer MCP on Grok Bot or another cloud sandbox even when a terminal exists. `AISA_API_KEY` overrides stored CLI credentials and never refreshes. If they conflict, explain the sources and leave custom setup alone. Never print credentials. Do not read or refresh token or compatibility key files. `aisa whoami` may refresh stored tokens and is not protected auth proof. Search and schema may be anonymous — they are not auth proof. + +## Sign-in + +Prove CLI auth with `aisa balance`. Before replying to a sign-in message or writing to its terminal, read `aisa login --help`. Follow it to interpret the CLI prompt and relay only the requested authorization result through the existing process. No credit → top up, not “missing key”. + +## Workflow + +`search` → `schema` when `has_full_schema` is false → `quote` → `call` inside authorized scope and spend. `quote` and `call` share the saved credentials and the same `calls` JSON shape. Take tool IDs and arguments from search/schema. Do not invent IDs or prices. Runtime help, schema, and quote are authoritative. `--input` is inline JSON: + +```sh +aisa search --input '{"query":""}' --json +aisa quote --input '{"calls":[{"call_id":"c1","tool":"","arguments":{}}]}' --json +``` + +Quote does not execute and is not approval to execute. A missing, failed, or partial quote is not free and is not a full-batch total or cap. Estimated cost is not a cap. Setup is not paid execution permission. Reuse a still-valid explicit authorization; do not invent confirmation loops for search, schema, or install. Re-quote if tools, arguments, or scope change. Do not silently retry or expand the batch. + +## MCP + +Use native remote Streamable HTTP MCP with OAuth at `https://tools.aisa.one/mcp`. No CLI, npm, npx, or Skill installation is required; already-installed guidance may be used. The client owns browser sign-in and tokens. Do not treat domain MCP or `aisa connect`’s default web-search server as this router. Discovery or a 401 is not a protected call. If a connector cannot be added, give the user that endpoint and one next action; do not claim connected. + +| 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` | + +## License + +MIT. Full license text: + +MIT License + +Copyright (c) 2026 AIsa (aisa.one) + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + diff --git a/zh/agent-quickstart-fallbacks.mdx b/zh/agent-quickstart-fallbacks.mdx index 5423167..79d77a9 100644 --- a/zh/agent-quickstart-fallbacks.mdx +++ b/zh/agent-quickstart-fallbacks.mdx @@ -7,13 +7,13 @@ description: "curl 下载官方 Skill，以及直接 HTTP 付费批准回退。 ## Skill 下载（curl） -**门禁：** Node 或 `npx skills` 跑不起来，需要把官方 `aisa` Skill 落到磁盘，且当前是用户本机，**或**用户在此环境明确要求 CLI/Skill（包括云端沙箱）。把完整三文件（`SKILL.md`、`LICENSE`、`agents/openai.yaml`）下载到当前客户端的原生 Skill 位置。保留已有的官方或自定义 Skill（包括符号链接）；没有原生安装就不要声称 Web 端已持久化。Codex 用户级示例：`~/.agents/skills/aisa`。首选安装器仍是 Node.js **22.20.0+** 和 `skills` 1.5.25 的 `engines`；这条 curl 路径不改变这些下限。 +**门禁：** Node 或 `npx skills` 跑不起来，需要把官方 `aisa` Skill 落到磁盘，且当前是用户本机，**或**用户在此环境明确要求 CLI/Skill（包括云端沙箱）。把完整三文件（`SKILL.md`、`LICENSE`、`agents/openai.yaml`）下载到当前客户端的原生 Skill 位置。保留已有的官方或自定义 Skill（包括符号链接）；没有原生安装就不要声称 Web 端已持久化。Codex 用户级示例：`~/.agents/skills/aisa`。首选安装器仍是 Node.js **22.20.0+** 和 `skills` 1.5.25 的 `engines`；这条 curl 路径不改变这些下限。raw GitHub pin 是 Skill 提交 `e7809490a186af77c4b96a5c1cfeea1ee39ce4f9`；先合并该 Skill 再合并本页。 ```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/7d7b1267f4363d894528f5c5b8d895214211cb84/platform/aisa" +aisa_skill_base="https://raw.githubusercontent.com/AIsa-team/agent-skills/e7809490a186af77c4b96a5c1cfeea1ee39ce4f9/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" @@ -42,9 +42,9 @@ mv "$aisa_skill_tmp/aisa" "$aisa_skill_target" ### API key -复用 `AISA_API_KEY`。若未设置且本 Agent 能读文件系统，使用 `aisa login` 写入的 `~/.aisa/key`，不要显示它。否则使用当前客户端已授权密钥库中的 AIsa API key。来源冲突时说明两边，不要覆盖用户自定义密钥。 +复用 `AISA_API_KEY`。不要读取 `tokens.json` 或兼容 key 文件。若 `aisa login` 可用，运行浏览器 `aisa login` 让 CLI 保存凭证。否则使用当前客户端已授权密钥库中的 AIsa API key。来源冲突时说明两边，不要覆盖用户自定义密钥。 -以上都没有、且 `aisa login` 可用时，运行浏览器 `aisa login` 自动保存密钥。若没有可用的 CLI 或浏览器登录路径，最后一步是用户到 https://console.aisa.one/api-keys 登录并创建密钥，保存到当前客户端的凭证/密钥设置，或本地 `AISA_API_KEY`。不要让用户把密钥粘贴进对话。不要打印密钥。不是每个客户端都有密钥设置界面；若当前客户端无法保存凭证，就停在该限制。 +以上都没有、且没有可用的 CLI 或浏览器登录路径时，最后一步是用户到 https://console.aisa.one/api-keys 登录并创建密钥，保存到当前客户端的凭证/密钥设置，或本地 `AISA_API_KEY`。不要让用户把密钥粘贴进对话。不要打印密钥。不是每个客户端都有密钥设置界面；若当前客户端无法保存凭证，就停在该限制。 受保护的 API 请求前先等到凭证就绪。拿到密钥不等于付费调用已获批准。 diff --git a/zh/agent-quickstart.mdx b/zh/agent-quickstart.mdx index 715180d..c32ddd7 100644 --- a/zh/agent-quickstart.mdx +++ b/zh/agent-quickstart.mdx @@ -27,7 +27,7 @@ npm install -g @aisa-one/cli aisa --version ``` -复用已经能用的 `@aisa-one/cli` **0.5.0 或更高**；只有缺失时才安装；不要降级。CLI 仍可沿用 Node.js **18+**。Skill 落盘后读取它。登录遵循该 Skill 和 `aisa login --help`。用 `aisa balance` 证明认证。`aisa whoami` 只检查本地。`AISA_API_KEY` 优先于已存储密钥；冲突时说明两个来源。不要打印凭证，也不要让用户去控制台复制 Key。获取凭证仍以浏览器 `aisa login` 为主。 +复用已经能用的 `@aisa-one/cli` **0.5.0 或更高**；只有缺失时才安装；不要降级。CLI 仍可沿用 Node.js **18+**。Skill 落盘后读取它。登录遵循该 Skill 和 `aisa login --help`。用 `aisa balance` 证明认证。`aisa whoami` 可能刷新已存 token，但不是受保护认证证明。`AISA_API_KEY` 覆盖已存 CLI 凭证且不会刷新；冲突时说明两个来源。不要打印凭证、不要读 token 文件，也不要让用户去控制台复制 Key。获取凭证仍以浏览器 `aisa login` 为主。 ## 云端 From e8e49c9904fd35085e405798b937a8934a999b57 Mon Sep 17 00:00:00 2001 From: idan Date: Mon, 14 Sep 2026 22:17:12 +0800 Subject: [PATCH 2/2] docs: pin Skill via LICENSE URL and native OpenAPI ingest Rewrite the relative LICENSE link to the pinned raw GitHub URL instead of inlining MIT text. Keep static-key HTTP fallbacks, honest catalog 404s, and an offline export --check in CI. Co-authored-by: Cursor --- .github/workflows/check-canonical-skill.yml | 30 +++++++++ agent-quickstart-fallbacks.mdx | 12 ++-- agent-quickstart.mdx | 2 +- docs.json | 2 + guides/agent-discovery.mdx | 19 ++++-- scripts/sync_canonical_aisa_skill.py | 72 +++++++-------------- skill.md | 25 +------ zh/agent-quickstart-fallbacks.mdx | 12 ++-- zh/agent-quickstart.mdx | 2 +- zh/guides/agent-discovery.mdx | 27 +++++--- 10 files changed, 98 insertions(+), 105 deletions(-) create mode 100644 .github/workflows/check-canonical-skill.yml diff --git a/.github/workflows/check-canonical-skill.yml b/.github/workflows/check-canonical-skill.yml new file mode 100644 index 0000000..55292a0 --- /dev/null +++ b/.github/workflows/check-canonical-skill.yml @@ -0,0 +1,30 @@ +name: Check canonical AIsa skill + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +jobs: + check: + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + - name: Pinned export check + run: python3 scripts/sync_canonical_aisa_skill.py --check + - name: Reject mutated export + run: | + tmp=$(mktemp -d) + cp skill.md "$tmp/skill.md" + printf '\nmutated\n' >> "$tmp/skill.md" + if python3 scripts/sync_canonical_aisa_skill.py --check --root "$tmp"; then + echo "::error::--check accepted a mutated skill.md" + exit 1 + fi diff --git a/agent-quickstart-fallbacks.mdx b/agent-quickstart-fallbacks.mdx index c8e89a7..42c36e2 100644 --- a/agent-quickstart-fallbacks.mdx +++ b/agent-quickstart-fallbacks.mdx @@ -7,7 +7,7 @@ Do not use this page as the default setup. Return to [Agent Quickstart](https:// ## Skill download (curl) -**Gate:** Node or `npx skills` cannot run, you need the official `aisa` skill on disk, and either this is a user-local machine **or** the user explicitly prefers CLI/Skill in this environment (including a cloud sandbox). 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`. The primary installer remains Node.js **22.20.0+** and `skills` 1.5.25 `engines`; this curl path does not change those floors. The raw GitHub pin is Skill commit `e7809490a186af77c4b96a5c1cfeea1ee39ce4f9`; merge that Skill change before this page. +**Gate:** Node or `npx skills` cannot run, you need the official `aisa` skill on disk, and either this is a user-local machine **or** the user explicitly prefers CLI/Skill in this environment (including a cloud sandbox). 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`. The primary installer remains Node.js **22.20.0+** and `skills` 1.5.25 `engines`; this curl path does not change those floors. The raw GitHub pin is Skill commit `e7809490a186af77c4b96a5c1cfeea1ee39ce4f9`. ```sh set -e @@ -30,9 +30,9 @@ mv "$aisa_skill_tmp/aisa" "$aisa_skill_target" ## Direct HTTP API fallback -**Gate:** CLI and MCP are both unavailable, HTTP requests are supported, and a valid existing AIsa API key or secret is already available. Read this entire section — endpoint docs, pricing, and the approval XML — before presenting a paid proposal or cost approval, and before any paid request. +**Gate:** The CLI is not usable here, MCP is unavailable, HTTP requests are supported, and a static `AISA_API_KEY` or equivalent secret is already configured in this environment. If the CLI is usable, leave this page and follow the CLI path on [Agent Quickstart](https://aisa.one/docs/agent-quickstart.md). Read this entire section — endpoint docs, pricing, and the approval XML — before presenting a paid proposal or cost approval, and before any paid request. -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. +Use this only for a client, tooling, or router limitation that blocks CLI and MCP. It does not bypass invalid API credentials, exhausted credit, or a failure of the same underlying API. 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. @@ -42,11 +42,9 @@ Send the key as a Bearer token. Do not send a paid example request from this pag ### API key -Reuse `AISA_API_KEY`. Do not read `tokens.json` or compatibility key files. If `aisa login` is usable, run browser `aisa login` so the CLI stores credentials. 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. +Direct HTTP requires a separately configured static `AISA_API_KEY` or equivalent secret already present as an environment variable or in this client's authorized secret store. Browser `aisa login` and other OAuth flows do not manufacture a static HTTP key. Do not run `aisa login` from this fallback. Do not read `tokens.json` or compatibility key files. If sources conflict, explain them; do not overwrite a custom key. -If none of those exist and 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. - -Wait for credentials before protected API requests. Obtaining a key is not paid-call approval. +If no static key or secret is already configured, stop. Do not ask the user to paste a key into chat. Do not print it. Do not send the user to copy a dashboard key into this conversation. Obtaining a key is not paid-call approval. ## Paid API approval first diff --git a/agent-quickstart.mdx b/agent-quickstart.mdx index 2286a43..05b9af7 100644 --- a/agent-quickstart.mdx +++ b/agent-quickstart.mdx @@ -43,4 +43,4 @@ Then those four tools: search → schema when `has_full_schema` is false → quo Do not jump to HTTP to bypass missing credentials, exhausted credit, or the same API outage. Do not make paid calls to test availability. Do not extract client-owned MCP OAuth tokens. -Only if CLI and MCP are both unavailable, HTTP works, and a valid AIsa key already exists: read the full direct HTTP section of [Agent Quickstart fallbacks](https://aisa.one/docs/agent-quickstart-fallbacks.md) (endpoint docs, pricing, approval XML) before a paid proposal, cost approval, or paid request. Extra models, REST, keys, or skills: [AIsa docs](https://aisa.one/docs). +Only if the CLI is not usable, MCP is unavailable, HTTP works, and a static `AISA_API_KEY` or equivalent secret is already configured separately: read the full direct HTTP section of [Agent Quickstart fallbacks](https://aisa.one/docs/agent-quickstart-fallbacks.md) (endpoint docs, pricing, approval XML) before a paid proposal, cost approval, or paid request. Browser OAuth does not manufacture that static key. Extra models, REST, keys, or skills: [AIsa docs](https://aisa.one/docs). diff --git a/docs.json b/docs.json index a18424e..7c66465 100644 --- a/docs.json +++ b/docs.json @@ -168,6 +168,7 @@ }, { "tab": "API Reference", + "openapi": "openapi.yaml", "groups": [ { "group": "Overview", @@ -2222,6 +2223,7 @@ }, { "tab": "API 参考", + "openapi": "openapi.yaml", "groups": [ { "group": "概览", diff --git a/guides/agent-discovery.mdx b/guides/agent-discovery.mdx index 36799cf..efa8a4b 100644 --- a/guides/agent-discovery.mdx +++ b/guides/agent-discovery.mdx @@ -1,6 +1,6 @@ --- title: "Agent Discovery – Let Autonomous Agents Find and Use AIsa" -description: "Integrate autonomous agents with AIsa using the A2A Agent Card, MCP manifest, OpenAI plugin manifest, OpenAPI 3.1 spec, and llms.txt resources." +description: "Find AIsa capabilities through the product Agent Card, OpenAPI spec, Docs Skill, and documentation indexes. The Docs-hosted card is not an A2A runtime." --- AIsa publishes several machine-readable discovery resources so that autonomous agents can find, understand, and invoke supported capabilities. This guide explains the main resources and the discovery-to-invocation flow. @@ -11,16 +11,23 @@ AIsa exposes the following public URLs for agent and documentation discovery. Th | Endpoint | Protocol | URL | Purpose | | :--- | :--- | :--- | :--- | -| **Agent Card** | Google A2A | `https://aisa.one/.well-known/agent-card.json` | High-level capabilities with metadata, tags, examples, and I/O modes | +| **Product Agent Card** | Landing metadata | `https://aisa.one/.well-known/agent-card.json` | High-level capabilities with metadata, tags, examples, and I/O modes. Not an AIsa A2A execution runtime. | +| **Docs Agent Card** | Mintlify auto | `https://aisa.one/docs/.well-known/agent-card.json` | Auto-derived from the published Docs Skill (`skill.md`). Same source as the canonical `aisa` Skill. Not an A2A runtime. | | **AI Plugin** | OpenAI Plugin (v1) | `https://aisa.one/.well-known/ai-plugin.json` | Backward compatibility with ChatGPT-era agent tooling | | **MCP Catalogue** | Live MCP inventory | `https://mcp.aisa.one/servers` | Entry points (root `mcp.aisa.one/mcp`, domain aliases), modules and per-server endpoints, generated by the running service | -| **OpenAPI Spec** | OpenAPI 3.1.0 | `https://aisa.one/openapi.yaml` | Machine-readable request and response contracts | +| **OpenAPI Spec** | OpenAPI 3.1.0 | `https://aisa.one/openapi.yaml` | Machine-readable request and response contracts. Use this when you need the API contract. | | **Product llms.txt** | llms.txt | `https://aisa.one/llms.txt` | Product fit, goals, interfaces, and evaluation routes | | **Technical llms.txt** | llms.txt | `https://aisa.one/docs/llms.txt` | Technical documentation router | +| **API Reference** | Docs index | `https://aisa.one/docs/api-reference` | Human-readable endpoint index | +| **Docs API catalog** | Mintlify `rel=api-catalog` | `https://aisa.one/docs/.well-known/api-catalog` | Advertised in Docs `Link` headers. **Currently 404** on `aisa.one` and `aisa.mintlify.dev`. Do not treat this URL as a working catalog. | + + +Mintlify advertises `https://aisa.one/docs/.well-known/api-catalog` on Docs responses, including 404s. That path is not a working catalog today. Use `https://aisa.one/openapi.yaml`, `https://aisa.one/docs/llms.txt`, or `https://aisa.one/docs/api-reference` instead. This page does not claim the catalog 404 is fixed. + ## How Agent Discovery Works -The discovery flow follows three steps: **discover**, **inspect**, and **invoke**. An autonomous agent starts by fetching the agent card to learn what AIsa can do, selects the relevant skill, and then calls the corresponding API endpoint using the OpenAPI spec for request/response schemas. +The discovery flow follows three steps: **discover**, **inspect**, and **invoke**. An autonomous agent starts by fetching a published card or Skill, selects the relevant capability, and then calls the corresponding API endpoint using the OpenAPI spec for request/response schemas. The Docs-hosted card is a Mintlify Skill projection, not an A2A transport. @@ -34,9 +41,9 @@ The discovery flow follows three steps: **discover**, **inspect**, and **invoke* -## The A2A Agent Card +## Agent cards -The [Agent2Agent (A2A) Protocol](https://a2a-protocol.org/latest/) defines a standard format for agents to advertise capabilities and interoperate. AIsa's agent card lives at the well-known URL and describes the platform, authentication requirements, and public capability catalog. +The product card at `https://aisa.one/.well-known/agent-card.json` is a landing metadata document. The Docs-hosted card at `https://aisa.one/docs/.well-known/agent-card.json` is generated by Mintlify from the same-source Skill published as repo-root `skill.md`. Fetch the live card instead of copying a fixed skill list. Neither URL adds an A2A execution runtime or a new well-known name. ### Fetching the Agent Card diff --git a/scripts/sync_canonical_aisa_skill.py b/scripts/sync_canonical_aisa_skill.py index 9e72b2a..ef58122 100644 --- a/scripts/sync_canonical_aisa_skill.py +++ b/scripts/sync_canonical_aisa_skill.py @@ -2,8 +2,9 @@ """Export AIsa-team/agent-skills platform/aisa into the Mintlify root skill.md. Mintlify overrides the auto-generated Docs skill with a repo-root skill.md. -This copies a pinned canonical SKILL.md and inlines LICENSE so the published -file has no missing relative targets. Merge the Skill commit before this pin. +The one documented transform rewrites the relative LICENSE link to the pinned +raw GitHub URL so the license stays at the official source. Merge the Skill +commit before this pin. """ from __future__ import annotations @@ -14,39 +15,20 @@ SOURCE_SHA = "e7809490a186af77c4b96a5c1cfeea1ee39ce4f9" SOURCE_SKILL = "platform/aisa/SKILL.md" -SOURCE_LICENSE = "platform/aisa/LICENSE" EXPORTED = "skill.md" -EXPORTED_SHA256 = "5d46448dee7901c1a687d4b1f49716d3d87555bbfb87ed022823e5afa9e4f15a" -LICENSE_LINK = "MIT — see [LICENSE](LICENSE)." - -STALE_GUIDANCE = ( - ("agent-quickstart.mdx", "whoami` is local only"), - ("zh/agent-quickstart.mdx", "whoami` 只检查本地"), - ("agent-quickstart-fallbacks.mdx", "~/.aisa/key"), - ("zh/agent-quickstart-fallbacks.mdx", "~/.aisa/key"), +EXPORTED_SHA256 = "8ccb3903800b3b97a093d36e1c90bee4d70ca705ada6d2a2dc59ef132d0b636f" +LICENSE_RELATIVE = "MIT — see [LICENSE](LICENSE)." +LICENSE_CANONICAL_URL = ( + f"https://raw.githubusercontent.com/AIsa-team/agent-skills/" + f"{SOURCE_SHA}/platform/aisa/LICENSE" ) +LICENSE_ABSOLUTE = f"MIT — see [LICENSE]({LICENSE_CANONICAL_URL})." -def export_text(skill: str, license_text: str) -> str: - if LICENSE_LINK not in skill: - raise SystemExit(f"{SOURCE_SKILL} is missing the LICENSE relative link") - inlined = "MIT. Full license text:\n\n" + license_text.strip() + "\n" - return skill.replace(LICENSE_LINK, inlined) - - -def write_export(root: Path, text: str) -> Path: - path = root / EXPORTED - path.write_text(text, encoding="utf-8") - return path - - -def check_guidance(root: Path) -> list[str]: - errors: list[str] = [] - for rel, stale in STALE_GUIDANCE: - text = (root / rel).read_text(encoding="utf-8") - if stale in text: - errors.append(f"{rel}: still contains {stale!r}") - return errors +def export_text(skill: str) -> str: + if LICENSE_RELATIVE not in skill: + raise SystemExit(f"{SOURCE_SKILL} is missing the relative LICENSE link") + return skill.replace(LICENSE_RELATIVE, LICENSE_ABSOLUTE) def main() -> int: @@ -57,11 +39,10 @@ def main() -> int: args = parser.parse_args() root = args.root.resolve() source_dir = args.source_dir.resolve() if args.source_dir else None - - errors = check_guidance(root) exported = root / EXPORTED if args.check: + errors: list[str] = [] if not exported.is_file(): errors.append(f"missing {EXPORTED}") else: @@ -69,13 +50,12 @@ def main() -> int: digest = hashlib.sha256(actual.encode()).hexdigest() if digest != EXPORTED_SHA256: errors.append(f"{EXPORTED} sha256 {digest} != pinned {EXPORTED_SHA256}") - if LICENSE_LINK in actual: + if LICENSE_RELATIVE in actual: errors.append(f"{EXPORTED} still has a relative LICENSE link") + if LICENSE_CANONICAL_URL not in actual: + errors.append(f"{EXPORTED} is missing the pinned LICENSE URL") if source_dir is not None: - expected = export_text( - (source_dir / "SKILL.md").read_text(encoding="utf-8"), - (source_dir / "LICENSE").read_text(encoding="utf-8"), - ) + expected = export_text((source_dir / "SKILL.md").read_text(encoding="utf-8")) if actual != expected: errors.append(f"{EXPORTED} drifted from source-dir at {SOURCE_SHA}") if errors: @@ -83,23 +63,15 @@ def main() -> int: for error in errors: print(f"- {error}", file=sys.stderr) return 1 - print(f"{EXPORTED} matches {SOURCE_SHA}; guidance stale strings absent") + print(f"{EXPORTED} matches {SOURCE_SHA}") return 0 if source_dir is None: raise SystemExit("--source-dir is required to write the export") - text = export_text( - (source_dir / "SKILL.md").read_text(encoding="utf-8"), - (source_dir / "LICENSE").read_text(encoding="utf-8"), - ) - path = write_export(root, text) + text = export_text((source_dir / "SKILL.md").read_text(encoding="utf-8")) + exported.write_text(text, encoding="utf-8") digest = hashlib.sha256(text.encode()).hexdigest() - print(f"wrote {path.relative_to(root)} from {SOURCE_SHA} sha256={digest}") - if errors: - print("guidance still has stale strings:", file=sys.stderr) - for error in errors: - print(f"- {error}", file=sys.stderr) - return 1 + print(f"wrote {exported.relative_to(root)} from {SOURCE_SHA} sha256={digest}") return 0 diff --git a/skill.md b/skill.md index 0999ab7..511c17b 100644 --- a/skill.md +++ b/skill.md @@ -44,27 +44,4 @@ Use native remote Streamable HTTP MCP with OAuth at `https://tools.aisa.one/mcp` ## License -MIT. Full license text: - -MIT License - -Copyright (c) 2026 AIsa (aisa.one) - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. - +MIT — see [LICENSE](https://raw.githubusercontent.com/AIsa-team/agent-skills/e7809490a186af77c4b96a5c1cfeea1ee39ce4f9/platform/aisa/LICENSE). diff --git a/zh/agent-quickstart-fallbacks.mdx b/zh/agent-quickstart-fallbacks.mdx index 79d77a9..fa01599 100644 --- a/zh/agent-quickstart-fallbacks.mdx +++ b/zh/agent-quickstart-fallbacks.mdx @@ -7,7 +7,7 @@ description: "curl 下载官方 Skill，以及直接 HTTP 付费批准回退。 ## Skill 下载（curl） -**门禁：** Node 或 `npx skills` 跑不起来，需要把官方 `aisa` Skill 落到磁盘，且当前是用户本机，**或**用户在此环境明确要求 CLI/Skill（包括云端沙箱）。把完整三文件（`SKILL.md`、`LICENSE`、`agents/openai.yaml`）下载到当前客户端的原生 Skill 位置。保留已有的官方或自定义 Skill（包括符号链接）；没有原生安装就不要声称 Web 端已持久化。Codex 用户级示例：`~/.agents/skills/aisa`。首选安装器仍是 Node.js **22.20.0+** 和 `skills` 1.5.25 的 `engines`；这条 curl 路径不改变这些下限。raw GitHub pin 是 Skill 提交 `e7809490a186af77c4b96a5c1cfeea1ee39ce4f9`；先合并该 Skill 再合并本页。 +**门禁：** Node 或 `npx skills` 跑不起来，需要把官方 `aisa` Skill 落到磁盘，且当前是用户本机，**或**用户在此环境明确要求 CLI/Skill（包括云端沙箱）。把完整三文件（`SKILL.md`、`LICENSE`、`agents/openai.yaml`）下载到当前客户端的原生 Skill 位置。保留已有的官方或自定义 Skill（包括符号链接）；没有原生安装就不要声称 Web 端已持久化。Codex 用户级示例：`~/.agents/skills/aisa`。首选安装器仍是 Node.js **22.20.0+** 和 `skills` 1.5.25 的 `engines`；这条 curl 路径不改变这些下限。raw GitHub pin 是 Skill 提交 `e7809490a186af77c4b96a5c1cfeea1ee39ce4f9`。 ```sh set -e @@ -30,9 +30,9 @@ mv "$aisa_skill_tmp/aisa" "$aisa_skill_target" ## 直接 HTTP API 回退 -**门禁：** CLI 和 MCP 都不可用、能发 HTTP、且已有有效的 AIsa API key 或秘密。提出付费方案或费用批准之前，以及发起任何付费请求之前，先读完本节（含 endpoint 文档、计价和批准 XML）。 +**门禁：** 当前环境不能使用 CLI、MCP 不可用、能发 HTTP，且静态 `AISA_API_KEY` 或等效秘密已经配置好。若 CLI 可用，离开本页，走 [Agent 快速开始](https://aisa.one/docs/zh/agent-quickstart.md) 的 CLI 路径。提出付费方案或费用批准之前，以及发起任何付费请求之前，先读完本节（含 endpoint 文档、计价和批准 XML）。 -仅当 CLI 和 MCP 都不可用、能发 HTTP、且已有有效的 AIsa API key 或秘密时使用。这条路径用于客户端、工具或路由器限制；不能绕过无效 API 凭证、额度用尽或同一底层 API 的故障。 +仅用于阻塞 CLI 和 MCP 的客户端、工具或路由器限制。不能绕过无效 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)。 @@ -42,11 +42,9 @@ mv "$aisa_skill_tmp/aisa" "$aisa_skill_target" ### API key -复用 `AISA_API_KEY`。不要读取 `tokens.json` 或兼容 key 文件。若 `aisa login` 可用，运行浏览器 `aisa login` 让 CLI 保存凭证。否则使用当前客户端已授权密钥库中的 AIsa API key。来源冲突时说明两边，不要覆盖用户自定义密钥。 +直接 HTTP 需要已经单独配置好的静态 `AISA_API_KEY` 或等效秘密（环境变量，或当前客户端已授权的密钥库）。浏览器 `aisa login` 或其他 OAuth 不会生成静态 HTTP key。不要在这条回退里运行 `aisa login`。不要读取 `tokens.json` 或兼容 key 文件。来源冲突时说明两边，不要覆盖用户自定义密钥。 -以上都没有、且没有可用的 CLI 或浏览器登录路径时，最后一步是用户到 https://console.aisa.one/api-keys 登录并创建密钥，保存到当前客户端的凭证/密钥设置，或本地 `AISA_API_KEY`。不要让用户把密钥粘贴进对话。不要打印密钥。不是每个客户端都有密钥设置界面；若当前客户端无法保存凭证，就停在该限制。 - -受保护的 API 请求前先等到凭证就绪。拿到密钥不等于付费调用已获批准。 +若静态 key 或秘密尚未配置，就停在该限制。不要让用户把密钥粘贴进对话。不要打印密钥。不要让用户把控制台 Key 复制进这次对话。拿到密钥不等于付费调用已获批准。 diff --git a/zh/agent-quickstart.mdx b/zh/agent-quickstart.mdx index c32ddd7..d486846 100644 --- a/zh/agent-quickstart.mdx +++ b/zh/agent-quickstart.mdx @@ -43,4 +43,4 @@ Grok Bot + Plugins：Settings → Plugins → Add → 如需则认证 → `@` 不要为了绕过缺凭证、额度用尽或同一 API 故障而跳到 HTTP。不要用付费请求探测可用性。不要提取客户端持有的 MCP OAuth token。 -仅当 CLI 和 MCP 都不可用、能发 HTTP、且已有有效的 AIsa key 时：先读完 [Agent 快速开始回退](https://aisa.one/docs/zh/agent-quickstart-fallbacks.md) 的直接 HTTP 节（含 endpoint 文档、计价和批准 XML），再提出付费方案或费用批准，也再发起任何付费请求。模型、REST、Key 或额外 Skill：[AIsa 文档](https://aisa.one/docs/zh/guides)。 +仅当 CLI 不可用、MCP 不可用、能发 HTTP，且静态 `AISA_API_KEY` 或等效秘密已经单独配置好时：先读完 [Agent 快速开始回退](https://aisa.one/docs/zh/agent-quickstart-fallbacks.md) 的直接 HTTP 节（含 endpoint 文档、计价和批准 XML），再提出付费方案或费用批准，也再发起任何付费请求。浏览器 OAuth 不会生成该静态 key。模型、REST、Key 或额外 Skill：[AIsa 文档](https://aisa.one/docs/zh/guides)。 diff --git a/zh/guides/agent-discovery.mdx b/zh/guides/agent-discovery.mdx index ff782ef..adfa73d 100644 --- a/zh/guides/agent-discovery.mdx +++ b/zh/guides/agent-discovery.mdx @@ -1,23 +1,32 @@ --- title: "智能体发现：让自主智能体发现并使用 AIsa" -description: "使用 Google A2A 智能体卡片、OpenAI 插件清单和 OpenAPI 3.1 规范，将自主智能体与 AIsa 集成。涵盖程序化发现、身份认证和端到端集成模式。" +description: "通过产品智能体卡片、OpenAPI 规范、Docs Skill 和文档索引发现 AIsa 能力。Docs 托管的卡片不是 A2A 运行时。" --- -AIsa 发布了三个机器可读的发现端点，让自主智能体无需人工介入即可发现、理解并调用 AIsa 的能力。本指南逐一介绍这些端点，解释集成流程，并提供 Python、TypeScript 和 Bash 的可运行代码示例。 +AIsa 发布了若干机器可读的发现资源，让自主智能体可以发现、理解并调用受支持的能力。本指南说明主要入口和从发现到调用的流程。 ## 发现端点 -AIsa 通过以下 well-known URL 支持智能体发现。这三个端点都可公开访问，读取时无需身份认证，并包含宽松的 CORS 响应头，因此基于浏览器的智能体可以直接获取数据。 +AIsa 通过以下公开 URL 支持智能体和文档发现。读取时无需身份认证。 | 端点 | 协议 | URL | 用途 | | :--- | :--- | :--- | :--- | -| **智能体卡片** | Google A2A | `https://aisa.one/.well-known/agent-card.json` | 主要发现入口，发布 13 项技能及其元数据、标签和输入/输出模式 | +| **产品智能体卡片** | 落地页元数据 | `https://aisa.one/.well-known/agent-card.json` | 高层能力、标签、示例和输入/输出模式。不是 AIsa A2A 执行运行时。 | +| **Docs 智能体卡片** | Mintlify 自动派生 | `https://aisa.one/docs/.well-known/agent-card.json` | 由已发布的 Docs Skill（`skill.md`）自动派生，与官方 `aisa` Skill 同源。不是 A2A 运行时。 | | **AI 插件** | OpenAI Plugin (v1) | `https://aisa.one/.well-known/ai-plugin.json` | 兼容 ChatGPT 时代的智能体工具 | -| **OpenAPI 规范** | OpenAPI 3.1.0 | `https://aisa.one/openapi.yaml` | 覆盖 111 多条 API 路径和 121 个 Schema 的机器可读规范 | +| **OpenAPI 规范** | OpenAPI 3.1.0 | `https://aisa.one/openapi.yaml` | 机器可读的请求和响应契约。需要 API 合同时使用此文件。 | +| **产品 llms.txt** | llms.txt | `https://aisa.one/llms.txt` | 产品定位、目标和接口 | +| **技术 llms.txt** | llms.txt | `https://aisa.one/docs/llms.txt` | 技术文档索引 | +| **API 参考** | 文档索引 | `https://aisa.one/docs/zh/api-reference` | 供人阅读的 endpoint 索引 | +| **Docs API catalog** | Mintlify `rel=api-catalog` | `https://aisa.one/docs/.well-known/api-catalog` | Docs 响应的 `Link` 头会广告此路径。在 `aisa.one` 和 `aisa.mintlify.dev` 上**当前为 404**。不要把它当成可用目录。 | + + +Mintlify 会在 Docs 响应（包括 404）里广告 `https://aisa.one/docs/.well-known/api-catalog`。该路径今天不可用。请改用 `https://aisa.one/openapi.yaml`、`https://aisa.one/docs/llms.txt` 或 `https://aisa.one/docs/zh/api-reference`。本页不声称该 404 已修复。 + ## 智能体发现的工作方式 -发现流程包含三个步骤：**发现**、**检查**和**调用**。自主智能体先获取智能体卡片，了解 AIsa 的能力；再选择相关技能；最后根据 OpenAPI 规范中的请求和响应 Schema 调用相应 API 端点。 +发现流程包含三个步骤：**发现**、**检查**和**调用**。自主智能体先获取已发布的卡片或 Skill，再选择相关能力，最后根据 OpenAPI 规范中的请求和响应 Schema 调用相应 API 端点。Docs 托管的卡片是 Mintlify 对 Skill 的投影，不是 A2A 传输。 @@ -31,9 +40,9 @@ AIsa 通过以下 well-known URL 支持智能体发现。这三个端点都可 -## A2A 智能体卡片 +## 智能体卡片 -[Google Agent-to-Agent（A2A）](https://google.github.io/A2A/)协议定义了智能体发布自身能力的标准格式。AIsa 的智能体卡片位于 well-known URL，用于描述平台、身份认证要求和完整技能目录。 +产品卡片位于 `https://aisa.one/.well-known/agent-card.json`，是落地页元数据。Docs 托管卡片位于 `https://aisa.one/docs/.well-known/agent-card.json`，由 Mintlify 从同源 Skill（仓库根目录 `skill.md`）自动生成。请拉取线上卡片，不要复制文档里的固定技能表。这两条 URL 都不会新增 A2A 执行运行时，也不会引入新的 well-known 名称。 ### 获取智能体卡片 @@ -94,7 +103,7 @@ card.skills.forEach((s: any) => console.log(` • ${s.id}: ${s.name}`)); ### 可用技能 -AIsa 当前通过智能体卡片发布 13 项技能。下表中的名称和标签与实际发现 Payload 保持一致： +请拉取线上卡片，不要依赖文档里的固定技能表。下表只是历史示例，不是当前目录： | 技能 ID | 名称 | 标签 | | :--- | :--- | :--- |