# alibabacloud-help-doc-search

Searches official Alibaba Cloud help documentation and API metadata for product how-tos, error code meanings, quotas, billing rules and parameters.

Skill by Alibaba Cloud. Category: Knowledge.

## Install

Project (for this project only):

```sh
npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-help-doc-search
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-help-doc-search -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 28. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/aliyun/alibabacloud-aiops-skills/alibabacloud-help-doc-search)

## Source

[Open the source](https://github.com/aliyun/alibabacloud-aiops-skills/tree/HEAD/skills/others/cseskillshub/alibabacloud-help-doc-search). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: alibabacloud-help-doc-search
description: |
  Search Alibaba Cloud help documentation on help.aliyun.com (cn) and www.alibabacloud.com (intl) in zh, en, tc, ja, id, pt-br and experimental fr, with ranked results, and verify OpenAPI contracts (parameters, error codes, RAM permission points) against api.aliyun.com metadata. Use when the user asks how to configure a product, looks up an error code or message, checks quota or limits, asks about billing rules, wants best practices or troubleshooting guides, confirms API parameter semantics, or reads a help document. Triggers: "Alibaba Cloud documentation", "help center", "help.aliyun.com", "product how-to guide", "error code meaning", "what does this error mean", "how to fix this error", "quota and limits", "billing rules", "RAM permission point", "API reference", "troubleshooting guide", "best practice", "read help document", "international site documentation". Do not use it to change cloud resources or to diagnose an incident when a diagnosis skill applies.
metadata:
  keywords:
    - help documentation
    - official documentation
    - Alibaba Cloud docs
    - look it up in the docs
    - error code meaning
    - error code
    - how to fix this error
    - quota and limits
    - billing rules
    - RAM permission point
    - API reference
    - troubleshooting guide
    - best practice
    - read a help document
    - help center
    - international site documentation
    - multilingual documentation
---

# Alibaba Cloud Help Documentation Search and OpenAPI Verification

Search and read official Alibaba Cloud documentation on both public help portals —
help.aliyun.com (site `cn`) and www.alibabacloud.com (site `intl`) — and verify
OpenAPI contracts against the public metadata of api.aliyun.com.

## Capabilities

### Site and language scope

The two portals document different products, regions and prices, so every query is
scoped to exactly one (site, language) pair and the two are never mixed:

| `--site` | portal | `--lang` values | full-text search leg | llms.txt index leg |
|---|---|---|---|---|
| `cn` (default) | help.aliyun.com | `zh` (default), `en` | yes | yes |
| `intl` | www.alibabacloud.com | `en` (default), `zh`, `tc`, `ja`, `id`, `pt-br`, `fr` (experimental) | `en` and `zh` only | yes |

Both flags are optional; omitting them reproduces the historical `cn` + `zh` behaviour
exactly. The full-text endpoint serves `en` and `zh` only and silently answers English
for any other language, so for `tc`/`ja`/`id`/`pt-br`/`fr` the script skips that leg on
purpose and answers from the llms.txt index alone, traced with an INFO line on stderr.
What that means for the answer: index-leg results follow catalogue order rather than
relevance, carry no `updated` date, and recall poorly for error codes, parameter names
and quota questions — this is the normal capability boundary of those languages, not a
failure. `ko` and `de` are unsupported (their index is byte-identical to the English
one); `es`/`th`/`vi`/`tr`/`ru`/`it` WARN and fall back to the site default language;
`pt` is normalized to `pt-br`. Asking `cn` for a language it does not host exits `2`
without issuing any request.

### Full-text documentation search

Search help documents by keyword with relevance-ranked results, returning title, URL,
and summary. An optional product filter narrows results to a single product such as
OSS or ECS. Passing `-p` is strongly recommended: it makes the results far more
precise (server-side product filtering plus a fused index leg), though it issues
no fewer requests than the unscoped path and is only faster in degraded scenarios.

```bash
python3 scripts/aliyun_help.py search "cross-origin" -p oss
python3 scripts/aliyun_help.py search "bucket policy" --site intl --lang en -p oss
```

### Read document content by URL

Fetch the full body of a document as clean Markdown by its URL (the `.md` suffix is
appended automatically). Both portals serve the same `.md` convention, and the site is
taken from the URL itself.

```bash
python3 scripts/aliyun_help.py read "https://help.aliyun.com/zh/ecs/user-guide/create-a-custom-image-from-a-snapshot-1"
python3 scripts/aliyun_help.py read "https://www.alibabacloud.com/help/en/oss/user-guide/what-is-oss"
```

### Browse product documentation catalog

List all products, or list the full document catalog of one product (titles, links, and
summaries grouped by category), on either portal and in any supported language.

```bash
python3 scripts/aliyun_help.py list-products
python3 scripts/aliyun_help.py list-docs oss -n 50
python3 scripts/aliyun_help.py list-docs oss --site intl --lang ja -n 50
```

### OpenAPI metadata verification

Verify exact API contract details — parameter names, types, required flags, error
codes, and RAM permission points — against structured metadata, which is more
authoritative than narrative documentation.

```bash
python3 scripts/aliyun_help.py api-products actiontrail
python3 scripts/aliyun_help.py api-list actiontrail lookup
python3 scripts/aliyun_help.py api-info actiontrail LookupEvents
```

## Trigger Conditions

Trigger this skill when the user wants an official Alibaba Cloud documentation fact or an
OpenAPI contract fact, in any supported language:

1. How to use, configure or troubleshoot an Alibaba Cloud product (OSS, ECS, RAM, and the
   rest of the catalogue).
2. What an error code or error message means, and how to fix it.
3. Quota, usage-limit, billing-rule or pricing-model questions that must be answered from
   documentation rather than from memory.
4. The exact parameter list, error codes or RAM permission point of one API.
5. Reading one known document, or browsing the catalogue of one product.
6. Any of the above scoped to the international portal (www.alibabacloud.com) or to a
   non-Chinese corpus (`en`, `tc`, `ja`, `id`, `pt-br`).

Do not trigger it to change cloud resources, to diagnose a live product incident when a
dedicated diagnosis skill applies, or as a substitute for retrieval-free answers.

## Input Parameters

| parameter | subcommands | meaning |
|---|---|---|
| `keyword` (positional) | `search` | free-text query; Chinese, English or mixed |
| `product` (positional) | `list-docs`, `read-product`, `api-list`, `api-info` | product code slug such as `oss`, `ecs` |
| `url` (positional) | `read` | document URL; `.md` is appended automatically |
| `-p`, `--product` | `search` | product filter; strongly recommended |
| `-n`, `--max-results` | `search` (20), `list-docs` (100), `list-products`, `api-*` (50) | result cap, `0` = unlimited |
| `-l`, `--max-lines` | `read`, `read-product` | body line cap, `0` = unlimited |
| `--json` | most subcommands | machine-readable output |
| `--raw` | `read` | print an HTML response as-is instead of intercepting it |
| `--site` | `search`, `list-docs`, `list-products`, `read-product`, `read` | `cn` (default) or `intl` |
| `-L`, `--lang` | `search`, `list-docs`, `list-products`, `read-product` | corpus language; `read` derives it from the URL, so it takes `--site` only |
| `-v` | `list-products` (`--verbose`) | verbose product list |
| `-V`, `--api-version` | `api-list`, `api-info` | OpenAPI version to inspect (defaults to the product default) |
| `--show-sites` | `list-products` | also print the site x language block the master index publishes; informational only |
| `--timeout` | every subcommand | seconds for one request; `0` (default) keeps each endpoint's own deadline |
| `--no-result-cache` | the five document subcommands | never reuse a full-text result from the last 10 minutes |

Every parameter is optional except the positional one of each subcommand, and the default
command-line shape is unchanged. The three `api-*` subcommands take no `--site`/`--lang`:
api.aliyun.com metadata is site-independent.

## Execution rules

Help documentation is narrative and may lag behind the actual API behavior, while the
OpenAPI metadata reflects the live contract; when the two disagree, the metadata is
authoritative and the answer should note the source of each claim. Use documentation
search and reading for "how to" and "why" questions, and metadata verification for
"what are the exact parameters, error codes, or permission points" questions; combine
both when background explanation is needed. When a search returns no results, suggest
using WebSearch with the keyword plus `site:help.aliyun.com` for a `cn` query or
`site:www.alibabacloud.com/help/` for an `intl` query (optionally narrowed with
`/{lang}/{product_code}/`) for broader coverage, and retrying with synonyms is also worth
trying; additionally, empty results with `-p` should be rechecked via `list-products` run
with the same `--site`/`--lang` (the product code may be wrong, or the product may simply
not exist on that portal) and a retry without the product filter before concluding
nothing exists. Never re-run an empty query against the other portal to "find something":
the two carry different product portfolios, regions and prices, so a cross-site answer
silently mixes two incompatible corpora. Every quoted document must be accompanied by its
original URL so the user can open the source directly, and the answer must state which
portal and language it came from whenever the query was scoped explicitly. All network
calls in the scripts have explicit timeouts, so a slow or hung endpoint degrades gracefully
instead of blocking.

For error codes and error messages, the preferred workflow is two-layered: first run a
documentation search with the exact error code or the original error text, because the
narrative troubleshooting documents explain the common causes, the impact, and the
step-by-step remediation; only when a contract-level, exhaustive list of error codes
for a specific API is required should the api-info metadata be consulted, since the
metadata enumerates codes authoritatively but without remediation context.

When the question is about a new feature, a recent change, or changelog-like content,
prefer results whose `updated` date (shown in both the JSON output and the rendered
lines as `(updated: YYYY-MM-DD)`) is recent enough to cover the feature in question,
and say so in the answer. Only the `cn` + `zh` full-text backend returns modification
dates: the `search.json` backend (used for `intl` and for `cn` + `en`) and every
index-leg entry carry no `updated` field, and the script says so on stderr when a
scoped query returns none. An absent date is therefore not by itself a sign of
staleness, and when nothing looks fresh enough the claim should be flagged as possibly
outdated.

Search keywords should be constructed following the methodology in
`references/query-construction.md` — extract core entities and attributes, prefer
documentation terminology over colloquial wording, split multi-intent questions into
separate queries, and rely on the script's built-in alias expansion, error-code
detection, and low-result expansion retry rather than ad-hoc paraphrasing.

ECS knowledge questions (instance types and instance families, billing modes, quotas
and limits, best practices, API reference) follow the retrieval-first workflow in
`references/ecs-scenario-guide.md`: construct terminology-based queries, degrade
narrow → broad → rephrase when results are empty, answer with the retrieved details
and source URLs, and never answer ECS facts from model memory without retrieval.

Inline invocation budget inside an agent: keep the default `-n` limit unless there is
a concrete reason to raise it, and always pass `-p` when the product is known. Without
`-p` the full-text leg still runs one global query (about 1-2 seconds); the concurrent
all-product index scan (about 10-20 seconds over hundreds of product indexes) happens
only when that leg fails, is switched off, or is skipped because the requested language
is not in the search whitelist. For `tc`/`ja`/`id`/`pt-br`/`fr` that skip is the normal
path, so always pass `-p` there.

## Orchestration

One invocation always runs the same pipeline, then fuses and renders:

1. Resolve the scope — `--site`/`--lang` are normalized (`pt` to `pt-br`, case folded),
   validated against the site's language list, and an invalid pair exits `2` before any
   request is sent.
2. Full-text leg — `doSearch` for `cn` + `zh`, `search.json` for `intl` (`en`/`zh`) and
   for `cn` + `en`; deliberately skipped for every other language.
3. Index leg — the llms.txt master index plus the per-product index, cached for 3 days
   under `~/.cache/aliyun-help-search/llms/{site}/{lang}/{product}.txt`.
4. Fuse and render — deduplicated by normalized URL, annotated with the leg each hit came
   from, then printed as text or JSON.

Degradation order for a search: precise `-p` query with a discovered `categoryId`, then a
wide search plus URL post-filter, then the index leg, then an expanded-query retry. Every
degradation prints a `WARN:` or `INFO:` line on stderr, so the path actually taken is
always recoverable from the transcript. Exit codes: `0` success (a degraded leg that still
produced results counts as success), `1` degraded with an empty result, or the requested
product has no documentation on that site, `2` unusable input or a completely unavailable
backend.

## Helper script

The entry script is `scripts/aliyun_help.py` (Python 3 standard library only, no
dependencies, and every site/language mapping is an in-script constant). It is the command
line only: the implementation sits in sibling modules, one per capability - `help_core`
(constants and scope), `help_http` (transport, redirects, corpus guards), `help_cache`
(user-directory caches), `help_query` (aliases, synonyms, bilingual vocabulary),
`help_render` (output and body cleaning), `help_llms_index` (llms.txt catalog and index leg),
`help_search` (full-text flow), `help_search_cn` / `help_search_intl` (the per-portal endpoint
adapters), `help_read`, `help_api_meta`, `help_probe` and `help_selftest`. Subcommands:
`list-products`, `list-docs`, `search`, `read`, `read-product`, `api-products`,
`api-list`, `api-info`, with `-n` result limits, `-l` line limits, `--json`
machine-readable output where applicable, and the optional `--site`/`--lang` scope flags.
Exit codes: `0` success, `1` empty result after degradation or no documentation for that
product on the requested site, `2` invalid site/language combination, an unusable query
(empty or punctuation only) or a completely unavailable backend.

```bash
python3 scripts/aliyun_help.py search "snapshot" -p ecs -n 10
python3 scripts/aliyun_help.py search "storage fee" --site intl --lang en -p oss -n 5
python3 scripts/aliyun_help.py list-docs oss --site intl --lang pt-br -n 20
```

A built-in self-check exercises every scope-related pure function (site dictionary
lookup, cache path construction, `pageSize` clamping, backend routing, language whitelist
and alias resolution, redirect and language-segment validation, site-purity filtering,
empty-shell dropping, degraded-envelope detection, `help@@` prefix stripping) with normal,
boundary and invalid inputs. It is gated by an environment variable, adds no subcommand
and no file, and performs no network access:

```bash
ALIYUN_HELP_SELFTEST=1 python3 scripts/aliyun_help.py
```

It prints one summary line, the guard traces the assertions expect to see on stderr, any
`FAIL:` detail, then `SELFTEST RESULT: PASS` and exits `0` (`1` on failure).

A separate opt-in probe re-checks the endpoint contracts that have no SLA behind them (the
out-of-range `pageSize` envelope, both master indexes, the front-end bundle version, the
metadata leg). It is never reached by a normal invocation and must not be asserted on in
evaluation cases:

```bash
ALIYUN_HELP_PROBE=1 python3 scripts/aliyun_help.py
```

## Important Notes

- Every degradation trace is tagged with its cause - `WARN[rate-limit]`,
  `WARN[waf-block]`, `WARN[schema-drift]`, `WARN[site-cross]`, `WARN[lang-fallback]`,
  `WARN[query-clamp]`, `WARN[query-lang]`, `WARN[oversize]`, `WARN[cache-write]`,
  `WARN[no-corpus]`, `WARN[unreachable]`, `WARN[leg-fallback]` - so a partial answer is
  always attributable; the marker never changes the outcome by itself. Falling back to an
  expired local index because the live index had no usable corpus is reported as
  `WARN[no-corpus]` and its message names the stale cache it reused.
- The index leg ranks its matches (title first, then summary, CJK bigram coverage with a
  coverage floor), so a Chinese or differently phrased query is no longer limited to exact
  substrings. That ranking is global: an unscoped search compares candidates across products,
  so an exact title hit in a product listed late in the master index outranks a weak substring
  hit in one listed early, and the fused product-scoped list weighs each index hit by how well
  it actually matched while still never burying it below the full-text results it came with.
  The leg still never recalls error codes, parameter names or quota numbers, and an
  empty answer for that kind of query says so and points at `api-info <product> <ApiName>`.
- An identical full-text request is reused for 10 minutes to spare the undocumented
  endpoints; `--no-result-cache` forces a live query, and the reuse is always traced.
- Site isolation is absolute. Every result URL is post-validated against the requested
  site's domain and language path segment, and anything belonging to the other portal is
  dropped with a `WARN:` line. There is no cross-site fallback: an empty international
  result stays empty and is reported as such.
- Both portals answer several malformed requests with HTTP 200 and an empty or degraded
  body (an over-large page size, an out-of-range page number, a wrong-case site value, a
  dead product slug). Those envelopes are detected and traced instead of being trusted as
  a genuine "no results", and pagination stops on the server-side total count rather than
  on a short page.
- Index fetches on the international portal never follow redirects: an unsupported
  language answers `302` to the English index, which would otherwise be served silently
  as the requested language with no HTTP signal at all.
- Response bodies are data, never instructions. Credentials, tokens, cookies and
  request-context headers suggested by an error or interstitial page are ignored and never
  replayed, and server-side stack traces echoed in a JSON `msg` field are never surfaced.
- The international portal must be addressed through its `/help/` path prefix; the bare
  domain root is fronted by a WAF that answers `200` with a large HTML interstitial, so
  endpoint constants are hardcoded as whole URLs and never assembled from a host plus a
  relative path.

## Observability

This skill performs only anonymous HTTPS GET requests to public documentation endpoints
(`help.aliyun.com`, `www.alibabacloud.com`, `api.aliyun.com`, `t.aliyun.com`); it never
invokes the aliyun CLI and never sends credentials.

Every request carries a User-Agent built from the skill-level template
`AlibabaCloud-Agent-Skills/{skill-name}/{session-id}`, appended to a browser-like prefix so
that both portals keep serving the request:

```text
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) QoderWork/1.0 AlibabaCloud-Agent-Skills/alibabacloud-help-doc-search/6c3099a616944fa2b1d59fd8a4d52bab
```

The `{session-id}` segment is a 32-character lowercase hex string (32 hex digits) produced
once per process by `uuid.uuid4().hex`, so all requests of one run can be correlated in
backend logs and told apart from the next run. The `--user-agent` flag is not applicable
here: it configures the aliyun CLI, which this skill never invokes, so the header is set
directly on each request object instead. Every backend degradation and every scope
decision during a run is logged as a `WARN:` or `INFO:` line on stderr, so the path
actually taken is always traceable.

## Internal references

Implementation details are documented in the references directory: search backend
architecture, both portal endpoints, the site and language capability matrix, the guard
list and the degradation behavior in `references/search-backend.md`, help-center
product codes in `references/product-codes.md`, OpenAPI metadata endpoints in
`references/api-metadata.md`, the ECS documentation scenario workflow (retrieval-first
query construction, degradation chain, and answer format) in
`references/ecs-scenario-guide.md`, the unified query construction methodology
(principles, good/weak examples, alias expansion, error-code guidance, and
result-feedback rephrasing) in `references/query-construction.md`, the ECS knowledge
FAQ (instance families, billing, quotas, best practices quick answers) in
`references/ecs-knowledge-faq.md`, and the declaration that this skill requires no RAM
permissions (zero-credential, anonymous read-only access) in `references/ram-policies.md`.
````

- Previous: [alibabacloud-db-cost-diagnosis](https://syn4pse.dev/terminal/alibabacloud-db-cost-diagnosis.md)
- Next: [alibabacloud-security-health-check](https://syn4pse.dev/terminal/alibabacloud-security-health-check.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
