diff --git a/AGENTS.md b/AGENTS.md
index 3a9258aa..c080235a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -123,6 +123,9 @@ graph TD
 - Primary language is Simplified Chinese; add English when practical.
 - One paragraph per line; use `<br>` for line breaks only when needed; no trailing spaces.
 - Markdown is linted by `markdownlint-cli2`.
+- End-user / agent usage of the installed `maa` CLI lives in `skills/maa-cli/` (`SKILL.md`, `setup.md`, `reference.md`). This file is for contributing to the crates.
+- Unimplemented product designs live in `docs/design/`. Do not describe them in `skills/maa-cli/` as if the commands exist; the skill may link to a design to say they do not.
+- When changing commands, task types, connection presets, or installer behavior, update `skills/maa-cli/` in the same change. When the task is to install, connect, or run maa-cli, read `skills/maa-cli/SKILL.md` instead of this file.
 
 ## MISC
 
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index a1ec8a50..8596eb5e 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -159,3 +159,4 @@ graph TD
 - 文档以简体中文为主，英文为辅，其他语言（繁体、韩文、日文）尽量翻译，无法翻译时可用简体中文占位。
 - 所有文档为 Markdown 格式，使用 [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) 检查。
 - 段落内不换行，每段仅一行，段落间空行分隔。非段落换行请用 `<br>`，不要用尾随空格。
+- 尚未实现、需要跨 MaaCore / maa-cli 讨论的方案放在 [`docs/design/`](docs/design/)（例如 [信息查询面](docs/design/query-surface.md)），不要写进用户手册或 `skills/maa-cli/` 当成已有命令。
diff --git a/README.md b/README.md
index 97fbceb3..8db54d0b 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,7 @@
 - [使用](crates/maa-cli/docs/zh-CN/usage.md)
 - [配置](crates/maa-cli/docs/zh-CN/config.md)
 - [常见问题](crates/maa-cli/docs/zh-CN/faq.md)
+- [Agent 技能](skills/maa-cli/SKILL.md)
 
 [maa-home]: https://github.com/MaaAssistantArknights/MaaAssistantArknights/
 
diff --git a/crates/maa-cli/docs/zh-CN/intro.md b/crates/maa-cli/docs/zh-CN/intro.md
index 2e4ec498..b42ed8aa 100644
--- a/crates/maa-cli/docs/zh-CN/intro.md
+++ b/crates/maa-cli/docs/zh-CN/intro.md
@@ -14,5 +14,6 @@
 - [使用](usage.md)
 - [配置](config.md)
 - [常见问题](faq.md)
+- [Agent 技能](../../../../skills/maa-cli/SKILL.md)
 
 [maa-home]: https://github.com/MaaAssistantArknights/MaaAssistantArknights/
diff --git a/docs/design/query-surface.md b/docs/design/query-surface.md
new file mode 100644
index 00000000..0eaf9993
--- /dev/null
+++ b/docs/design/query-surface.md
@@ -0,0 +1,115 @@
+# 信息查询面（中期）
+
+状态：提案。未实现。文中的 `maa snapshot` / `maa query` 不存在，只是切面草图。
+
+本文写给要改 maa-cli / 对接 MaaCore 的人。用户手册在 `crates/maa-cli/docs/`。当前 CLI 怎么用在 `skills/maa-cli/`。
+
+## 要解决什么
+
+MAA 现在是执行器：识别界面、点按钮、把 callback 打进日志。maa-cli 把任务交出去，自己不识图，也不把结果收成 agent 能反复引用的事实。
+
+Agent 接上之后，真正缺的不是再写一套自动点击，而是**这个号现在是什么状态**——按需、带来源、缺了就说缺。有了这层，才能做比「按名单点下去」更复杂的决策：这周期红票换书还是换芯片、绿票要不要兑许可、专精材料刷关还是等店、公招许可还够不够撑到下次刷新。
+
+所以中期要扩的是信息查询面，不是某一个推荐功能。两块一起做：
+
+1. **OCR / 只读扫描**：把现在扫不到、扫不稳、或不落盘的界面状态读出来。包括但不限于各种票据、凭证店本期限购，以及干员箱里仍缺的养成字段。
+2. **Agent 友好的查询切面**：按需取 detail，输出带 `source` / `as_of` 的 JSON。静态表（货盘、掉率、养成消耗）和 OCR 事实分开，不让模型记价格，也不把「没扫到」补成 0。
+
+购买清单、公招规划、刷关 vs 兑换，都是这层之上的**消费者**。第一期可以拿红/绿票店当试金石，但不能把产品做成「商店购买推荐」。
+
+## 现在停在哪
+
+|能力|今天做什么|查询面缺什么|
+|---|---|---|
+|`Depot`|材料页模板匹配；部分 Core 再扫「全部」里少数货币|票类不是一等公民；结果只打日志，不落盘|
+|`OperBox`|干员列表：`id` / 精英 / 等级 / 潜能 / 稀有度|技能等级、专精、模组、信赖不在结果里|
+|`Mall`|按名单**真实购买**信用店|不解释为什么；不管凭证店|
+|`Recruit` / `Fight` / `Infrast`|执行公招、作战、基建|callback 里有片段（理智、公招结果），没有按需查询|
+|maa-cli|派任务、打日志|没有 snapshot，没有 `query`，agent 只能从日志里抠|
+
+信用商店已经有执行器，高价值状态（票、限购、养成细节）既不扫全，也不供查询。卡点不是「OCR 读不了」，而是 Core 很少把只读扫描当成任务，cli 也没有给 agent 的事实层。
+
+## 非目标
+
+- 不把 Depot 扩成万能背包。票、许可、黄票、情报凭证和材料不是同一套 OCR 模板；硬扩仓库会把「没识别」混进「数量为零」。
+- 不做通用「OCR 任意界面大脑」。按界面拆扫描器，查询切面再组合。
+- 不替代 `Mall`。信用店货每天随机，按 `buy_first` / `blacklist` 下单是规则执行，不是查询。
+- 不在 Core 或 cli 里跑模型做养成规划。表负责数值，agent 负责把事实和用户目标翻成决策。
+- 不把建议或代操作写成已经存在的子命令。高代价动作（凭证店下单、源石）默认不 click；apply 若要做，必须和查询分开。
+
+## OCR：按事实选界面
+
+一条事实从它自然出现的页面读。不要假设「扫一次仓库就有一切」。
+
+|要读的事实|自然界面|现状|
+|---|---|---|
+|材料数量|仓库「材料」|`Depot` 已有|
+|红票 / 源石 / 合成玉 / 龙门币 / 赤金|仓库「全部」或部分商店顶栏|部分 Core 已扫；以当前日志为准|
+|绿票、黄票、情报凭证、寻访凭证、招聘许可|仓库「全部」或对应商店顶栏|默认不稳或不全|
+|凭证店还能买几次|该商店货架（例如芯片助剂 2/2）|没有只读扫描任务|
+|信用点|信用商店|走 `Mall` 执行过程，不是查询|
+|干员技能 / 专精 / 模组|干员详情，不是列表页|`OperBox` 没有|
+|理智|作战前后|`SanityBeforeStage` 等 callback，不是独立查询|
+
+凭证店「库存」不是全服货量，而是这个号本周期的限购余量。OCR 商店页读到的是「还能买几次」。货盘本身多半是静态表（GameData 商店表，例如 `shop_client_table`），多数时候不必 OCR 整页商品名。
+
+票据同理：数量是 OCR，物品定义走 `item_index.json`。常用 ID：黄票 `4004`、绿票 `4005`、红票 `4006`、情报凭证 `REP_COIN`。
+
+## 查询切面：按需、可引用、可组合
+
+Agent 一次决策往往只要几条 detail，而不是整局游戏的 dump。切面按资源分，而不是按「推荐场景」分。
+
+草图（实现时再定名）：
+
+```text
+maa snapshot tickets              # 票/凭证余量
+maa snapshot shop red|green       # 本期限购余量
+maa snapshot depot                # 材料
+maa snapshot operators            # 干员箱；以后可加技能/专精
+maa query tickets
+maa query shop --shop red
+maa query operator --id <char>
+maa query depot --item 30012
+```
+
+约定：
+
+- `snapshot`：跑只读扫描，写出带时间戳的 JSON。可以贵，所以按需，不默认全量。
+- `query`：读已有 snapshot + 静态表。没有快照就说没有，不要默默再扫一遍；需要刷新时显式 snapshot。
+- 每条字段带 `source`（`ocr` / `table` / `callback` / `user`）和 `as_of`。缺测用缺测，禁止用 0 填充。
+- 执行类结果若要暴露，也走同一形状，并标明 `side_effect`（例如 `Mall` 已经买过）。查询切面默认无副作用。
+
+静态表不走 OCR：货盘与兑换价、企鹅掉率、技能专精消耗、经验规则。查询输出里表数据与账号状态并列，让 agent 能区分「游戏里还剩几次」和「表上这件值多少票」。
+
+## 决策是消费者，不是切面本身
+
+查询面给的是事实。复杂决策在 agent（或以后可选的纯函数）里做。下面只说明**为什么切面必须比单一推荐更宽**，不是第一期要交货的产品列表。
+
+凭证店是一个典型组合：用户缺口 × 本周期性价比 × 余票 × 限购余量。没有票余量和限购，推荐只能猜；没有材料 Depot，不知道缺什么；没有表，模型会编价格。MAA 故意不自动买红/绿票店，因为买错代价高——查询面默认只建议、不代操作，和这条一致。
+
+同一组事实还能支撑别的决策，例如：绿票 + 招聘许可限购 + 公招目标 → 要不要兑许可；红票 + 技能书库存 + 专精表 → 兑书还是刷关；干员专精缺口 + 芯片库存 + 芯片助剂限购 → 这期店该不该动。这些都不该各自做一套 OCR。
+
+若以后要 `recommend` 入口，它是读 query JSON 的纯函数，可以先放在仓库外或脚本里，不一定进二进制。Apply（按清单代点）更往后，且必须和建议、查询分开：查询可旧，建议可错，代买不能默默错。
+
+## 分层
+
+|层|做什么|不做什么|
+|---|---|---|
+|MaaCore|按界面增加只读扫描，稳定 callback / 结构化结果|不在 Core 里做养成规划；只读任务默认不点击购买|
+|maa-cli|查询切面：收 snapshot、按需 query、标明来源与时间|不把日志当 API；不用模型算性价比|
+|表 / 外部数据|货盘、兑换价、掉率、养成消耗|不靠截图推数值|
+|Agent|组合事实与用户目标，输出可解释决策|不把缺测补成 0；高代价动作先问再执行|
+
+## 分期
+
+第一期把**查询面的形状**做对，并补上最常用、现在又最残的 OCR：票据余量（红/绿优先，黄票与许可跟上），以及红票店、绿票店的限购余量。`snapshot` JSON 带 `source` / `as_of`；`query` 可以先是读文件的约定，不一定立刻进 CLI。
+
+紧接着把 `query` 做成真正的无副作用入口，并决定 OperBox 要不要扩技能/专精/模组（可能是另一套详情扫描，而不是给列表页加字段）。
+
+第二期再扩黄票店、情报凭证店、活动店，以及把更多 callback（理智、公招）收进同一套 query 形状。决策辅助（商店清单、材料缺口）作为消费者接入，仍然默认不代操作。
+
+## 为什么这样切
+
+把 Depot 做成万能背包，看起来一次扫完，实际是把不同界面的失败模式叠进一个「已读到」。票余量可以在仓库「全部」或商店顶栏；限购只在商店货架上；技能等级在干员详情。查询切面按事实组合，扫描器按界面拆开。
+
+先做某一个推荐功能，会把 API 绑死在「买不买」上，后面的公招、专精、刷关规划都要另起炉灶。先做 OCR + 按需 query，推荐只是其中一个调用方，才配得上 agent 要做的复杂决策。
diff --git a/skills/maa-cli/SKILL.md b/skills/maa-cli/SKILL.md
new file mode 100644
index 00000000..1a59288e
--- /dev/null
+++ b/skills/maa-cli/SKILL.md
@@ -0,0 +1,93 @@
+---
+name: maa-cli
+description: >-
+  Operate MaaAssistantArknights maa-cli (`maa` / `maa-cli`) for 明日方舟 automation.
+  Use when installing or running maa-cli, connecting via PlayCover / Waydroid / ADB,
+  or diagnosing a failed game connection. Do not use for the MAA desktop GUI,
+  non-Arknights games, or this repo's Rust/CI work.
+license: AGPL-3.0-only
+metadata:
+  author: MaaAssistantArknights
+  version: "0.2.2"
+  tags: arknights maa-cli maacore
+---
+
+# maa-cli
+
+maa-cli 只服务《明日方舟》。它把任务交给已安装的 MaaCore，自己不识图、不点屏幕。
+本机命令多数是 `maa`；Windows winget 安装后是 `maa-cli`。先 `command -v maa`，没有再试 `maa-cli`。下文示例写 `maa`。
+旗标以 `maa help` / `maa help <command>` 为准。
+
+**会点击购买或消耗源石的操作，先得到用户明确同意。**
+
+## 三层
+
+会操作游戏的命令要求三层同时就绪。缺哪一层就补哪一层。
+
+1. **maa-cli**：PATH 上的 `maa` 或 `maa-cli`。
+2. **MaaCore + 资源**：`maa install`（已装则 `maa update`）。热更新资源用 `maa hot-update`。Nix 已捆绑 Core。包管理器装的 cli 用包管理器升级。
+3. **游戏运行时**：Android 走 ADB（模拟器、真机、Waydroid）；macOS 上的 iOS 包走 PlayCover + PlayTools。maa-cli 不安装模拟器、PlayCover 或游戏。
+
+数量、余量、限购只引用命令日志或用户给出的数字。物品 ID 查已装资源的 `item_index.json`（`maa dir resource`）。
+
+## 冷启动
+
+完成标准：`maa version` 同时打出 cli 与 Core；`maa dir config` 能打印路径；若要跑游戏，profile 的 preset/地址与当前运行时一致，且目标命令 `--dry-run` 通过。
+
+1. 跑 `maa version`。命令不存在 → 读 [setup.md](setup.md) 的「安装 maa-cli」，装到 `maa version` 能跑。没有 Core → `maa install`（Windows 先装 VC++）。**完成：** 输出版本里同时有 cli 和 Core。
+2. `maa dir config` 打印配置目录（`MAA_CONFIG_DIR` 可覆盖）。**完成：** 得到一条真实路径。
+3. 要操作游戏且运行时不明：问用户是 PlayCover、哪家模拟器、Waydroid 还是真机，再按 [setup.md](setup.md) 写 `$MAA_CONFIG_DIR/profiles/default.toml`。有人在场可用 `maa init`；无人值守直接写文件。**完成：** profile 的 preset/地址与当前客户端一致，或用户只要安装、不连游戏。
+4. `maa startup --dry-run`（或目标任务加 `--dry-run`）。连不上走 setup 的连通性检查。**完成：** dry-run 退出码为 0。
+5. 任务文件有输入项时加 `--batch`。**完成：** 不会在提示符上卡住。
+
+## 连接怎么选
+
+选 `preset` 用下表。写入文件的完整模板、分平台依赖、排错见 [setup.md](setup.md) 对应平台小节和「写连接 profile」。
+
+|本机|游戏怎么跑|`connection.preset`|默认地址|
+|---|---|---|---|
+|macOS|PlayCover 安装的 iOS 包|`PlayCover`|`127.0.0.1:1717`（以窗口标题 `[host:port]` 为准）|
+|macOS|MuMu Player Pro|`MuMuPro`|`127.0.0.1:16384`|
+|Windows|腾讯 Androws|`Androws`|`127.0.0.1:5555`|
+|Linux|Waydroid|`Waydroid`|`waydroid`|
+|任意|其它 Android 模拟器或真机|`ADB`|`adb devices` 的 serial，找不到则 `emulator-5554`|
+
+PlayCover 预设强制 `MacPlayTools`，并加载 iOS 资源。窗口保持可见。B 服没有 iOS 包。
+本次运行覆盖地址：`maa fight 1-7 --addr 127.0.0.1:1717`。
+
+## 命令怎么路由
+
+|用户要|去做|
+|---|---|
+|装 / 更新 Core|`maa install` / `maa update`|
+|热更新资源|`maa hot-update`|
+|路径 / 版本 / 活动表|`maa dir …` / `maa version` / `maa activity`|
+|启动、作战、抄作业、肉鸽、生息|预定义子命令：`startup` `closedown` `fight` `copilot` `ssscopilot` `paradoxcopilot` `roguelike` `reclamation`|
+|基建、公招、信用商店、领奖、仓库、干员箱|自定义任务的 `type`，`maa run <文件名不含扩展名>`|
+
+预定义例子：`maa startup Official && maa fight BB-7 -m 3 && maa closedown`
+作业 URI 用 `prts://<id>` 或 `prts://s<id>`，或本地 JSON。
+自定义任务放 `$MAA_CONFIG_DIR/tasks/`。类型名与识别边界见 [reference.md](reference.md)。
+`Mall` 的 `buy_first` / `blacklist` 会在信用商店真实下单。
+
+## 何时读哪份文件
+
+- 缺 cli / Core、要写 profile、连不上：读 [setup.md](setup.md) 里对应当前 OS 的那一节。
+- 自定义 `type`、URI、仓库/干员箱能扫到什么：读 [reference.md](reference.md) 对应小节。
+
+仓库内用户手册：
+
+- 安装：[install.md](../../crates/maa-cli/docs/zh-CN/install.md)
+- 使用：[usage.md](../../crates/maa-cli/docs/zh-CN/usage.md)
+- 配置：[config.md](../../crates/maa-cli/docs/zh-CN/config.md)
+
+## 常见错误
+
+|错|改成|
+|---|---|
+|把 `Infrast` / `Recruit` / `Mall` / `Depot` 当成子命令|自定义任务 `type` + `maa run …`|
+|只装了 cli 就开打|`maa version` 看到 Core 之后再连|
+|macOS 默认 ADB 去连 PlayCover|preset `PlayCover`，地址用标题栏端口|
+|作业写成 `maa://`|`prts://`|
+|把 `Mall` 名单当成推荐清单|先确认再跑；名单里的东西会被买掉|
+|把 `maa activity` 当成背包|活动表来自已装资源；背包走 `Depot` 任务日志|
diff --git a/skills/maa-cli/reference.md b/skills/maa-cli/reference.md
new file mode 100644
index 00000000..8eac7181
--- /dev/null
+++ b/skills/maa-cli/reference.md
@@ -0,0 +1,93 @@
+# maa-cli 参考
+
+任务类型和识别边界。旗标以 `maa help` 为准。
+
+## Contents
+
+- [子命令 vs 任务类型](#子命令-vs-任务类型)
+- [Copilot URI](#copilot-uri)
+- [客户端](#客户端)
+- [物品 ID 与 Depot](#物品-id-与-depot)
+- [OperBox / Mall](#operbox--mall)
+- [安装资源里有什么](#安装资源里有什么)
+- [条件与 batch](#条件与-batch)
+
+## 子命令 vs 任务类型
+
+|能力|有子命令|自定义任务 `type`|
+|---|---|---|
+|启动/关闭|`startup` / `closedown`|`StartUp` / `CloseDown`|
+|作战|`fight`|`Fight`|
+|作业|`copilot` / `ssscopilot` / `paradoxcopilot`|`Copilot` / `SSSCopilot` / `ParadoxCopilot`|
+|肉鸽|`roguelike`|`Roguelike`|
+|生息演算|`reclamation`|`Reclamation`|
+|基建 / 公招 / 信用商店 / 领奖 / 仓库 / 干员箱|无|`Infrast` / `Recruit` / `Mall` / `Award` / `Depot` / `OperBox`|
+|其它|无|`Custom` / `SingleStep` / `VideoRecognition`|
+
+自定义任务文件：`$MAA_CONFIG_DIR/tasks/`，`maa run <stem>`。
+基建计划 JSON：`$MAA_CONFIG_DIR/infrast/`（必须 JSON）。maa-cli 不按时段读计划文件，要用任务 `condition` 配 `plan_index`。
+Schema：[task.schema.json](../../crates/maa-cli/schemas/task.schema.json)
+参数权威：[集成文档 · 任务类型](https://maa.plus/docs/zh-cn/protocol/integration.html)
+
+`maa fight --help` 给出作战旗标。`--stone` 先确认；`-D<物品ID>=件数` 的 ID 来自 `item_index.json`（`maa dir resource`）。
+
+未知 `connection.preset` 会被当成 `ADB` 并打警告。PlayCover 的别名是 `PlayTools`。
+
+## Copilot URI
+
+优先 `prts://<id>`（单份作业）或 `prts://s<id>`（作业集）。
+也接受本地路径或 `file://`。
+`maa://<id>` / `maa://<id>s` 仍能用，但会告警弃用。
+
+## 客户端
+
+|值|说明|PlayCover bundle|Android 包名|
+|---|---|---|---|
+|`Official`|官服|`com.hypergryph.arknights`|`com.hypergryph.arknights`|
+|`Bilibili`|B 服|无|`com.hypergryph.arknights.bilibili`|
+|`txwy`|台服|`tw.txwy.ios.arknights`|`tw.txwy.and.arknights`|
+|`YoStarEN`|国际服|`com.YoStarEN.Arknights`|同左|
+|`YoStarJP`|日服|`com.YoStarJP.Arknights`|同左|
+|`YoStarKR`|韩服|`com.YoStarKR.Arknights`|同左|
+
+## 物品 ID 与 Depot
+
+票和货币的常用 ID（其余查 `item_index.json`）：
+
+|ID|名称|classifyType|备注|
+|---|---|---|---|
+|`4001`|龙门币|NORMAL||
+|`4002`|至纯源石|NORMAL||
+|`4003`|合成玉|NORMAL||
+|`4004`|高级凭证|NORMAL|黄票|
+|`4005`|资质凭证|NORMAL|绿票|
+|`4006`|采购凭证|NORMAL|红票|
+|`REP_COIN`|情报凭证|NORMAL||
+|`30012`|固源岩|MATERIAL|`-D` 示例常用|
+
+`classifyType == MATERIAL` 才是 Depot 材料页模板白名单。票和货币是 `NORMAL`。
+
+Depot 是自定义任务 `type = "Depot"`，截图模板匹配 + 数量 OCR。结果打在日志里，不落盘。
+部分 Core 会再扫「全部」页的源石/合成玉/龙门币/赤金/红票；黄票、绿票、情报凭证、寻访凭证、招聘许可以当前日志为准。
+理智在战斗 callback `SanityBeforeStage`。信用点走 `Mall`。
+
+## OperBox / Mall
+
+OperBox 日志字段：`id` / `name` / `own` / `elite` / `level` / `potential` / `rarity`。技能等级、专精、模组、信赖不在结果里。
+
+`Mall` 只自动买信用商店，会真实点击购买。红/绿/黄票店和情报凭证店没有扫描或自动购买子命令。没有 `maa snapshot` / `maa query`。
+凭证店「库存」是本号本周期限购余量。没扫到的票余量和限购次数不当成已经读到。
+中期方向（OCR 扩采集 + 按需查询，决策是消费者）见 [信息查询面](../../docs/design/query-surface.md)。
+
+## 安装资源里有什么
+
+`maa install` 装的资源够识别图标和跑作业：物品名、关卡掉落种类、干员职业/射程、基建技能文案与排班效率、公招 tags。
+养成数值（攻防 HP、技能各等级、专精/模组材料）查游戏数据或 wiki。掉率查企鹅物流。
+
+## 条件与 batch
+
+自定义任务可用 `Time` / `DateTime` / `Weekday` / `DayMod` / `OnSideStory` 以及 `And`/`Or`/`Not`。
+`timezone = "Official"` 用游戏日界（官服 UTC+4），不是东八区 0 点。
+当天 `DayMod` 余数：`maa remainder <divisor>`。
+
+任务参数里的 `Input`/`Select` 在交互运行时会提问。`--batch` 用默认值；没有默认值就失败。
diff --git a/skills/maa-cli/setup.md b/skills/maa-cli/setup.md
new file mode 100644
index 00000000..ba341e18
--- /dev/null
+++ b/skills/maa-cli/setup.md
@@ -0,0 +1,208 @@
+# 安装与运行时
+
+在用户本机把 maa-cli 接到能打的明日方舟客户端。
+命令示例写 `maa`；winget 安装后改成 `maa-cli`。
+技能未写到的安装细节以 [install.md](../../crates/maa-cli/docs/zh-CN/install.md) 和 [config.md](../../crates/maa-cli/docs/zh-CN/config.md) 为准。
+
+完成标准：`maa version` 含 Core；`maa dir library` 下能找到 MaaCore 动态库；profile 的 `preset` / 地址与当前客户端一致；目标任务 `--dry-run` 通过。
+
+## Contents
+
+- [1. 安装 maa-cli](#1-安装-maa-cli)
+- [2. 安装 MaaCore 与资源](#2-安装-maacore-与资源)
+- [3. 游戏运行时（按平台）](#3-游戏运行时按平台)
+- [4. 写连接 profile](#4-写连接-profile)
+- [5. 连通性检查](#5-连通性检查)
+
+## 1. 安装 maa-cli
+
+探测：`uname -s`（或 Windows 的 `$env:OS`），以及 `command -v maa` / `command -v maa-cli`。
+
+### macOS
+
+推荐 Homebrew tap：
+
+```bash
+brew install MaaAssistantArknights/tap/maa-cli
+```
+
+预发行版用 `maa-cli-beta`。Linux 上的 Homebrew 同样走这个 tap。
+
+### Linux
+
+- Arch：`yay -S maa-cli`
+- Nix：`nix run nixpkgs#maa-cli`（已依赖 MaaCore，跳过第 2 步的 `maa install`）
+
+### Windows
+
+```bat
+winget install maa-cli
+```
+
+此后命令名是 `maa-cli`，不是 `maa`。升级用 `winget update maa-cli`。
+
+### 脚本 / 源码
+
+系统不受包管理器支持时：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/MaaAssistantArknights/maa-cli/main/install.sh | bash
+```
+
+Windows PowerShell：
+
+```powershell
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/MaaAssistantArknights/maa-cli/main/install.ps1" -OutFile install.ps1; .\install.ps1
+```
+
+Rust 开发者：`cargo install maa-cli --git https://github.com/MaaAssistantArknights/maa-cli.git --bin maa --tag stable --locked`
+
+国内访问 GitHub 失败时，让用户改 `$MAA_CONFIG_DIR/cli.toml` 里的 `api_url` / `download_url` 镜像；镜像字段说明在 [config.md](../../crates/maa-cli/docs/zh-CN/config.md) 的「CLI 相关配置」。
+
+## 2. 安装 MaaCore 与资源
+
+maa-cli 只是 CLI。没有 Core 就不能跑任务。
+
+```bash
+maa install
+```
+
+已装则 `maa update`。热更新资源：`maa hot-update`。即使开了热更新，基础资源仍要随 Core 安装。
+
+Windows：在 `install` 之前先装 VC++ 运行库：
+
+```bat
+winget install "Microsoft.VCRedist.2015+.x64" --override "/repair /passive /norestart" --uninstall-previous --accept-package-agreements --force
+```
+
+包管理器可选 Core（仅当 maa-cli 也是同一包管理器装的）：
+
+- Homebrew：`brew install MaaAssistantArknights/tap/maa-core`
+- Arch：`yay -S maa-assistant-arknights`
+
+`maa install` 下的是官方预编译 Core；包管理器编出来的可能略有差异。
+Core 通道 `Alpha` 只在 Windows 可用。
+
+确认：`maa version` 同时列出 maa-cli 与 MaaCore；`maa dir library`、`maa dir resource` 非空。
+
+## 3. 游戏运行时（按平台）
+
+maa-cli 只负责连上已有客户端。游戏、模拟器、PlayCover 都要用户（或你按官方文档协助用户）另行安装。
+
+### macOS：PlayCover + PlayTools（iOS 包）
+
+适用：Apple Silicon 上用 iOS 版明日方舟，追求原生流畅。Intel Mac 更常见的是 Android 模拟器，见下一节。
+
+MaaCore 这边：profile 设 `preset = "PlayCover"`。maa-cli 会：
+
+- 忽略 `adb_path`
+- 默认连 `127.0.0.1:1717`（可用 `address` 或 `--addr` 覆盖）
+- 强制 `touch_mode = MacPlayTools`
+- 加载 iOS 差分资源
+- 在 `startup` 且需要拉起游戏时，用 `open` 打开 PlayCover 容器里的 `.app`（官服 bundle `com.hypergryph.arknights`）。B 服没有 App Store / PlayCover 包。
+
+客户端与 PlayTools 不由 maa-cli 安装。按 [MAA macOS 手册 · PlayCover](https://maa.plus/docs/zh-cn/manual/device/macos.html) 做完这些，再让 maa-cli 去连：
+
+1. 安装手册指定的 PlayCover（MAA 要求用其文档中的 fork，不要假设任意 PlayCover 发行版都能用）。
+2. 在 PlayCover 里安装 iOS 版明日方舟。游戏更新后通常要重新装包。
+3. PlayCover 右键游戏 → 设置 → 绕过：启用 PlayChain、绕过越狱检测、插入内省库、**MaaTools**（即 PlayTools）。
+4. 启动游戏。标题栏出现 `[localhost:端口]` 才算 PlayTools 起来了。把该地址写入 profile（常见 `127.0.0.1:1717`）。
+5. 识别出错时，在 PlayCover 里把分辨率设到 1080p。
+6. 运行期间保持窗口可见：最小化、台前调度切走、移到其它桌面会导致截图失败。
+
+交互 `maa init` 选预设 `PlayCover` 时，地址填 PlayTools 的 `host:port`。
+
+### macOS：Android 模拟器
+
+PlayCover 不是唯一路径。macOS 也可以 ADB 连模拟器，此时用 `ADB` / `MaaTouch`，不用 `MacPlayTools`。
+
+|模拟器|maa-cli preset|备注|
+|---|---|---|
+|MuMu Player Pro|`MuMuPro`|默认 adb：`/Applications/MuMuPlayer.app/Contents/MacOS/MuMuEmulator.app/Contents/MacOS/tools/adb`；默认 `127.0.0.1:16384`|
+|BlueStacks Air|`ADB`|开「Android 调试（ADB）」；测试可用 MaaTouch + `127.0.0.1:5555`|
+|Android Studio AVD|`ADB`|自带 platform-tools；Android 10+ 上 MiniTouch 在 SELinux Enforcing 下不可用，改 MaaTouch/ADB|
+|夜神（Intel）|`ADB`|adb 常在 `/Applications/NoxAppPlayer.app/Contents/MacOS/adb`|
+
+模拟器必须已启动、ADB 开关已打开。用模拟器自带 `adb devices` 核对 serial，再写入 `address`。
+
+### Windows：模拟器 + ADB
+
+常见路径：模拟器 + ADB。`maa init` 可选 `Androws`（腾讯 Androws，默认 `127.0.0.1:5555`）或通用 `ADB`。
+
+- 优先使用模拟器自带 adb，把 `adb_path` 指到那个可执行文件。
+- 端口见 [连接说明](https://maa.plus/docs/zh-cn/manual/connection.html)。
+- 触控：兼容优先 `ADB`；多数模拟器可用 `MaaTouch`。`MacPlayTools` 只给 PlayCover。
+
+### Linux：Waydroid / AVD
+
+- **Waydroid**：profile `preset = "Waydroid"`。仍需本机 `adb`（默认 PATH 里的 `adb`）。maa-cli 会 `waydroid status`，必要时起 session，再 `waydroid adb connect`。分辨率至少 720p 且 16:9，例如：
+
+  ```bash
+  waydroid prop set persist.waydroid.width 1280
+  waydroid prop set persist.waydroid.height 720
+  ```
+
+  细节：[MAA Linux 手册 · Waydroid](https://maa.plus/docs/zh-cn/manual/device/linux.html)
+
+- **AVD / 其它**：`preset = "ADB"`，`adb_path` 指向 SDK `platform-tools/adb` 或发行版 `adb`。同样要求 16:9 且 ≥720p。
+
+Linux 上跑 MAA 桌面 GUI（Wine）与 maa-cli 是两条线；命令行任务走 maa-cli + 原生 Core。
+
+## 4. 写连接 profile
+
+选哪个 `preset` 见 [SKILL.md · 连接怎么选](SKILL.md#连接怎么选)。本节只写文件模板和触控等字段。
+
+目录：`$(maa dir config)/profiles/`。默认名 `default`，扩展名 json/toml/yaml 均可。本次运行换文件：`--profile 名字`。
+
+`maa init` 会交互询问预设（`MuMuPro` / `PlayCover` / `Waydroid` / `Androws` / `ADB`）、adb 路径、地址、触控模式。代理无人值守时直接写文件。
+
+PlayCover：
+
+```toml
+[connection]
+preset = "PlayCover"
+address = "127.0.0.1:1717"
+
+[instance_options]
+touch_mode = "MacPlayTools"
+```
+
+`touch_mode` 即使写错，PlayCover 预设也会被强制改成 `MacPlayTools`。
+
+Waydroid：
+
+```toml
+[connection]
+preset = "Waydroid"
+```
+
+通用 ADB（按实际 serial 改 `address`）：
+
+```toml
+[connection]
+preset = "ADB"
+adb_path = "adb"
+address = "127.0.0.1:5555"
+
+[instance_options]
+touch_mode = "MaaTouch"
+```
+
+非简中客户端：在 `startup` 里带 `client_type`，或在 profile 里设 `resource.global_resource`（`YoStarEN` / `YoStarJP` / `YoStarKR` / `txwy`）。iOS / PlayCover 会自动加 `platform_diff_resource = "iOS"`。
+
+## 5. 连通性检查
+
+按顺序排除，不要跳着改。
+
+1. `maa version`：没有 Core → 回到第 2 步。
+2. 游戏或模拟器窗口在前台（PlayCover 尤其不能最小化）。
+3. PlayCover：标题栏有 `[localhost:port]`，profile 地址与之一致。ADB：`"$adb_path" devices` 能看到 `device` 而不是 `offline`。
+4. `maa startup --dry-run` 通过后再去掉 `--dry-run`。需要拉起游戏时：`maa startup Official`（或对应 `client_type`）。
+5. 仍失败：`-v` 或 `MAA_LOG=debug`，日志目录 `maa dir log`。
+
+常见失败：
+
+- 连 `emulator-5554` 但模拟器实际是 `127.0.0.1:16384` 这类端口 → 改 `address` 或 `--addr`。
+- macOS 默认连 ADB，游戏却在 PlayCover 里 → 改 preset。
+- 多设备时 ADB 预设会拿 `adb devices` 的第一台 → 显式写 `address`。
+- MiniTouch + 新 Android 模拟器 → 改 `MaaTouch` 或 `ADB`。