# A2IO Agent Guide This page is the machine-oriented entry point for A2IO. It is intentionally explicit: an Agent may fetch this document, inspect the installed binary, and then choose a safe command without guessing platform capability or a local path. ## Product contract A2IO is a cross-platform CLI for collecting content from multiple sources and delivering it to explicit destinations. The normal data flow is: ```text source -> normalized record -> idempotent route -> destination ``` The installed binary is the source of truth for available features. Website documentation is a guide, not permission to execute an unavailable command. ## 1. Discover the installed binary Use the downloaded binary for the current operating system. The stable manifest is [here](/update/stable.json); it contains an Ed25519 signature and SHA-256 for every artifact. Run these read-only checks first: ```text a2io capabilities --json a2io version --json a2io sources list --json ``` Require the capabilities response to contain `product: "a2io"`, `edition`, `version`, `contract_version`, `platform`, `architecture` and `capabilities`. If a required capability is absent, stop and report that the installed edition cannot perform the requested operation. For a local Obsidian Vault: ```text a2io init --vault --json a2io doctor --vault --json ``` Do not search the disk for a Vault and do not invent a destination. ## 2. Credentials and privacy Read credentials from an existing `.env`, environment variables or an OS secret store. Do not ask the user to paste cookies, API keys, IMA tokens, license keys or private keys into a chat prompt. Do not put them into route configuration, logs, Markdown, JSON reports or URLs. For Pro-only flows, check authorization before any gated network call: ```text a2io runtime status --json a2io license status --json ``` If authorization is missing or expired, explain the required onboarding step. Do not bypass a platform login, paywall, anti-bot challenge or access control. ## 3. One-shot synchronization Use `--json` and parse the structured result. Examples: ```text a2io sync --source rss --param feed= --json a2io sync --source url --param url= --destinations obsidian --json a2io sync --source github --param username= --destinations obsidian --json a2io sync --source weread_app --resource favourites --json ``` The last command requires a Pro capability and an authenticated WeRead App session. Use only the resource and parameters listed by the installed binary. ## 4. Persistent routes Persistent routes are the right abstraction when a user says “whenever this source has new content, sync it to this destination”. A route stores the source identity, destination configuration, mode, cursor, content fingerprint and delivery ledger. It is not the same as a one-time export. ### WeRead public-account articles ```text a2io mp route add --url <公众号文章链接> --ima-knowledge-base <知识库ID> --ima-folder <目录ID> --ima-mode url|html|markdown --initial baseline --json a2io mp route list --json a2io mp route test --route-id --json ``` ### X bookmarks ```text a2io x route add --account-id --ima-knowledge-base <知识库ID> --ima-folder <目录ID> --ima-mode url|html|markdown --initial baseline --json a2io x route test --route-id --json ``` ### GitHub Star or one repository ```text a2io github route add --username --content-mode summary --ima-knowledge-base <知识库ID> --initial baseline --json a2io github route add --url https://github.com// --content-mode readme --ima-knowledge-base <知识库ID> --json ``` GitHub synchronization is intentionally bounded: default content is a repository summary; `readme` may include README and `watch` may include the latest Release. Do not synchronize a whole source tree, all Issues or all Pull Requests unless a future capability explicitly says so. ### MediaCrawler as an upstream input MediaCrawler is upstream and must not be modified. A2IO reads its already-written JSONL or SQLite data: ```text a2io mediacrawler route add --root --input-mode jsonl --platform all --ima-knowledge-base <知识库ID> --initial baseline --json ``` Use the exact flags reported by `a2io capabilities --json` and `a2io mediacrawler --help` in the installed build. ## 5. Destination modes Both IMA and Obsidian can use: - `url`: store/import the source URL; lightest and least likely to trigger content fetching. - `html`: fetch and preserve controlled HTML when the source parser and target support it. - `markdown`: parse/render content into Markdown before upload or file creation. IMA requires an explicit knowledge-base ID; an existing folder ID should be supplied when the user named a target folder. Obsidian requires an explicit absolute Vault directory. Preserve manual edits and report `unchanged`, `skipped`, `conflict` and `failed` separately. Use `baseline` for a new route unless the user explicitly asks for historical backfill. Use `full` only for that backfill. Test a new route before enabling or scheduling it. ## 6. Scheduling and forced checks A2IO commands are one-shot. The CLI does not run a permanent daemon. Use the host scheduler: - Windows Task Scheduler - Linux systemd timer or cron - macOS launchd The scheduled command is: ```text a2io monitor auto-sync --once --json ``` For an immediate manual check: ```text a2io monitor auto-sync --once --force --json ``` The current Pro runtime uses a 10-minute internal throttle for route checks in this workspace. `--force` bypasses that throttle for the current invocation. Each enabled route is evaluated through the same unified monitor; routes do not each start their own independent shelf checker. ## 7. Updates Check and apply updates with the signed manifest: ```text a2io update check --channel stable --json a2io update apply --channel stable --json a2io update status --json a2io update rollback --json ``` The updater verifies the manifest signature, product/edition/platform/architecture/contract compatibility, artifact size and SHA-256 before an atomic replacement. It must not modify `.env`, Pro encrypted state, sync databases, Vault files or exported content. ## 8. Failure handling On a failure, report the JSON error code, `run_id` if present, source counts, delivery counts, warnings and the affected route ID. Recommended responses: - capability missing: stop and request the required edition or upgrade; - credential missing/expired: use the configured login or refresh flow, never request a secret in chat; - destination missing: ask for the exact knowledge-base/folder ID or absolute Vault path; - `conflict`: preserve the user-edited target and ask before overwriting; - transient network or provider error: allow the route ledger to retry; do not blindly duplicate a delivery; - parser or anti-bot rejection: report that the source denied/changed access and do not attempt to evade the control. ## Stable machine endpoints - [Agent manifest](/agent.json) - [LLM / Agent summary](/llms.txt) - [Quick start](/docs/quickstart.md) - [Configuration](/docs/configuration.md) - [Update protocol](/docs/update.md) - [Health](/healthz)