From 9046927c118c077009c9dc24b9dec925b649bcff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=87=A1=E8=BE=9E?= Date: Thu, 20 Aug 2026 11:58:35 +0800 Subject: [PATCH 1/4] feat: add in-repo maa-cli agent skill Give agents a usage guide for running maa-cli instead of scraping --help, including command routing and Depot/OperBox OCR limits. --- skills/maa-cli/SKILL.md | 90 +++++++++++++++++++++++++++++++++++ skills/maa-cli/reference.md | 93 +++++++++++++++++++++++++++++++++++++ 2 files changed, 183 insertions(+) create mode 100644 skills/maa-cli/SKILL.md create mode 100644 skills/maa-cli/reference.md diff --git a/skills/maa-cli/SKILL.md b/skills/maa-cli/SKILL.md new file mode 100644 index 00000000..55088b28 --- /dev/null +++ b/skills/maa-cli/SKILL.md @@ -0,0 +1,90 @@ +--- +name: maa-cli +description: >- + Operate MaaAssistantArknights maa-cli (command `maa` / `maa-cli`): install MaaCore, + run Fight/Infrast/Recruit/Mall/Copilot tasks, read dirs and activity, and explain + Depot/OperBox OCR limits. Use when the user mentions maa-cli, maa install, maa run, + maa fight, MaaCore, 明日方舟自动化, 仓库识别, 干员箱, or combining maa-cli with an agent. +--- + +# maa-cli 使用 + +面向 **调用 maa-cli 跑任务 / 查状态** 的 agent，不是改本仓库源码。 +改 crate、CI、FFI 请看仓库根目录 `AGENTS.md`。 +不要靠 `maa --help` 猜能力边界；命令语法细节以 `maa help ` 和 [reference.md](reference.md) 为准。 + +Windows 上用 winget 安装时，命令名是 `maa-cli`，下文的 `maa` 一律替换即可。 + +## 先分清三层数据 + +|平面|含义|要不要开游戏| +|---|---|---| +|catalog|静态表：MaaResource（`item_index.json` 等）或 ArknightsGameData|否| +|account|截图 OCR：仓库 Depot、干员箱 OperBox|要模拟器/客户端| +|action|点击游戏：Fight、基建、公招、信用商店|要| + +查技能数值、攻防、专精材料 → catalog（GameData），**不是** MaaResource，更不是 OCR。 +查「我有多少固源岩」→ account（Depot）。 +「帮我刷 1-7」→ action。 + +## 最小前置 + +1. 二进制可用：`maa version`。 +2. MaaCore 已装：`maa install`（已装则 `maa update`）。资源热更新：`maa hot-update`。 +3. 需要跑游戏任务时，设备已连接（ADB / PlayCover 等），配置用 `maa init` 或 `$MAA_CONFIG_DIR` 下的 profile。 +4. 配置目录：`maa dir config`（可用 `MAA_CONFIG_DIR` 覆盖）。 + +未装 Core 时不要编造任务结果。路径一律用 `maa dir …`，不要写死 `/usr/local` 或 `C:\Program Files`。 + +## 命令地图 + +### 管理 + +- `maa install` / `maa update`：安装或更新 MaaCore 与资源。 +- `maa self update`：更新 maa-cli 自身；包管理器安装的用户不要用这条。 +- `maa hot-update`：热更新资源仓库，不替换 Core 自带的基础资源。 +- `maa init`：交互初始化 profile。 +- `maa version` / `maa dir `。 + +### 预定义任务（会操作游戏） + +- `maa startup [client]` / `maa closedown [client]` +- `maa fight [stage]`（如 `1-7`；空则上次/当前关） +- `maa copilot ...`：作业 URI 用 `prts://` 或 `prts://s` 或本地 JSON；`maa://` 已弃用。 +- `maa sscopilot` / `maa paradoxcopilot` / `maa roguelike ` / `maa reclamation ` + +### 自定义任务 + +- 文件在 `$MAA_CONFIG_DIR/tasks/`，`maa run <文件名不含扩展名>`。 +- `maa list` 列出可用任务。 +- Depot / OperBox **没有** `maa depot` 这种预设子命令，只能写自定义任务，`type` 为 `Depot` 或 `OperBox`。 +- 任务类型与参数以 [MAA 集成文档](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/dev/docs/zh-cn/protocol/integration.md) 为准；maa-cli **不校验** 参数名，错了要等 Core 运行时才爆。 + +### 只读 / 工具 + +- `maa activity [client]`：当前活动关卡提示（catalog + 资源，不 OCR 背包）。 +- `maa convert`、`maa complete`、`maa cleanup`、`maa import`、`maa remainder`。 + +参数示例：`maa fight BB-7 -m 3` 用 3 瓶理智药。 +日常串联：`maa startup Official && maa fight 1-7 -m 3 && maa closedown`。 + +## 安全与默认策略 + +- **信用商店 `Mall` 会真的下单。** 自定义任务里的 `buy_first` / `blacklist` 是执行规则，不是建议。 +- **不要代买红票/黄票/绿票/情报凭证商店。** 当前 maa-cli 也没有这些店的只读扫描命令。若用户要购买建议：用 catalog 货盘 + 已有 Depot 材料，输出清单，默认不 click。 +- 不要把 OCR 快照当成完整账号资产。边界见 [reference.md](reference.md)。 +- 需要确认才执行会消耗源石（`--stone`）或清空理智的长时间 Fight。 + +## 给 agent 的输出习惯 + +跑任务后据实汇报：用了哪些命令、任务总结里的关卡/掉落/公招，以及 OCR 没覆盖的部分。 +引用物品用 `item_index.json` 的 id（如固源岩 `30012`），不要只写俗称。 +区分「Core 没这个功能」和「命令写错了」。 + +## 人类文档 + +- 安装：[docs/zh-CN/install.md](../../crates/maa-cli/docs/zh-CN/install.md) +- 使用：[docs/zh-CN/usage.md](../../crates/maa-cli/docs/zh-CN/usage.md) +- 配置与自定义任务：[docs/zh-CN/config.md](../../crates/maa-cli/docs/zh-CN/config.md) +- 示例任务：`crates/maa-cli/config_examples/tasks/daily.json` +- 命令与 OCR 边界：[reference.md](reference.md) diff --git a/skills/maa-cli/reference.md b/skills/maa-cli/reference.md new file mode 100644 index 00000000..9144890c --- /dev/null +++ b/skills/maa-cli/reference.md @@ -0,0 +1,93 @@ +# maa-cli 参考 + +SKILL.md 的补充。只在需要物品 ID、OCR 边界或商店建议时再读。 + +## 物品 ID（俗称） + +来自已安装的 MaaResource `item_index.json`（`maa dir resource`）。 + +|ID|名称|classifyType|备注| +|---|---|---|---| +|`4001`|龙门币|NORMAL|| +|`4002`|至纯源石|NORMAL|| +|`4003`|合成玉|NORMAL|| +|`4004`|高级凭证|NORMAL|黄票| +|`4005`|资质凭证|NORMAL|绿票| +|`4006`|采购凭证|NORMAL|红票| +|`REP_COIN`|情报凭证|NORMAL|| +|`3003`|赤金|NORMAL|| +|`7001`|招聘许可|NORMAL|| +|`7002`|加急许可|NORMAL|| +|`7003`|寻访凭证|NORMAL|| +|`7004`|十连寻访凭证|NORMAL|| +|`classic_gacha`|中坚寻访凭证|NORMAL|| +|`30012`|固源岩|MATERIAL|| + +`classifyType == MATERIAL` 才是 Depot 材料页模板白名单（芯片、精英材料、技能书、作战记录、模组数据块等）。票和货币是 `NORMAL`，不进该白名单。 + +## Depot / OperBox + +两者都是 MaaCore 任务类型，maa-cli 只在 callback 里把 JSON 打到日志，**不落盘、没有 `maa query`。** +自定义任务示例： + +```toml +[[tasks]] +type = "Depot" +``` + +Depot 是截图模板匹配 + 数量 OCR，不是读游戏内存，也不是「屏幕上有什么就扫什么」。 + +### Depot 实际覆盖 + +- 默认在仓库**材料**页滑动，只匹配 `MATERIAL` 模板。 +- 较新的 MaaCore（自 v6.14.2 起部分版本）会再点「全部」，硬编码再扫：`4002` `4003` `4001` `3003` `4006`（源石、合成玉、龙门币、赤金、红票）。 +- **默认不扫**：黄票 `4004`、绿票 `4005`、情报凭证、寻访/中坚寻访/十连、招聘许可、加急许可。这些多在消耗品或其它分页。 +- 理智在战斗 callback `SanityBeforeStage`，不在 Depot。 +- 信用点走 `Mall`，不是仓库。 + +### OperBox + +- 有：`id` / `name` / `own` / `elite` / `level` / `potential` / `rarity`。 +- 无：技能等级、专精、模组、信赖、基建技能解锁。 + +## Mall 与凭证店 + +`Mall` 只自动买**信用商店**，会真实点击购买。 +红/绿/黄票店、情报凭证店：**没有**预设扫描或自动购买。 + +凭证店「库存」是**本号本周期限购余量**，不是全服抢货。 +购买建议（只输出、不代买）需要： + +1. catalog：货盘与价格（GameData `shop_client_table` 等，红绿票店货盘相对稳定）。 +2. account：票余量（需扩 Depot 或商店顶栏 OCR，**现成命令没有**）。 +3. account：材料缺口（现有 Depot 材料页）。 +4. 限购余量：商店页 OCR 或自行记账（现成命令没有）。 + +不要声称已经根据黄/绿票余量给过精确可买清单，除非用户提供了这些数字或另有扫描结果。 + +## MaaResource vs GameData + +MaaResource（`maa install` 装的）够 OCR 和作业，不够养成 wiki： + +- 有：物品名、关卡掉落**种类**、干员职业/射程、基建技能**文案与排班效率**、公招 tags。 +- 无：攻防 HP、战斗技能各等级数值、天赋、专精/模组材料与解锁条件。 + +完整表用 ArknightsGameData（`character_table` / `skill_table` / `building_data` / `item_table` / `stage_table` / `uniequip_table`），适合 ingest 成 SQLite 再查。 +掉率用企鹅物流，不要写进 GameData。 + +## 常用 Fight 参数 + +- `-m/--medicine`：理智药数量。 +- `--stone`：源石；`--dr-grandet` 等 1 理智再确认。 +- `--times`：次数上限。 +- `-D30012=100`：指定掉落件数后停止，可重复。 +- `--series`：连战次数，`-1`～`6`。 + +日志：`MAA_LOG`，`-v`/`-q`，`--log-file`；任务总结可用 `--no-summary` 关掉。 + +## 自定义任务位置 + +- 任务：`$MAA_CONFIG_DIR/tasks/` +- 基建计划 JSON：`$MAA_CONFIG_DIR/infrast/`（必须 JSON，maa-cli 不按时段读计划文件，要用 `condition` + `plan_index`） +- 示例：`crates/maa-cli/config_examples/tasks/daily.json` +- Schema：`crates/maa-cli/schemas/task.schema.json` From 1ecd645187417ab2f3343c8f1d79329cf7d40728 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=87=A1=E8=BE=9E?= Date: Thu, 20 Aug 2026 12:21:59 +0800 Subject: [PATCH 2/4] docs: harden maa-cli agent skill for cold-start setup Give a bare agent enough runtime context to install, connect, and run maa-cli, and point AGENTS.md at the skill for end-user usage versus crate work. --- AGENTS.md | 2 + README.md | 1 + crates/maa-cli/docs/zh-CN/intro.md | 1 + skills/maa-cli/SKILL.md | 141 +++++++++++--------- skills/maa-cli/reference.md | 133 +++++++++---------- skills/maa-cli/setup.md | 206 +++++++++++++++++++++++++++++ 6 files changed, 356 insertions(+), 128 deletions(-) create mode 100644 skills/maa-cli/setup.md diff --git a/AGENTS.md b/AGENTS.md index 3a9258aa..c8f9b558 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -123,6 +123,8 @@ graph TD - Primary language is Simplified Chinese; add English when practical. - One paragraph per line; use `
` 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. +- 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/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/skills/maa-cli/SKILL.md b/skills/maa-cli/SKILL.md index 55088b28..7d1d591b 100644 --- a/skills/maa-cli/SKILL.md +++ b/skills/maa-cli/SKILL.md @@ -1,90 +1,109 @@ --- name: maa-cli description: >- - Operate MaaAssistantArknights maa-cli (command `maa` / `maa-cli`): install MaaCore, - run Fight/Infrast/Recruit/Mall/Copilot tasks, read dirs and activity, and explain - Depot/OperBox OCR limits. Use when the user mentions maa-cli, maa install, maa run, - maa fight, MaaCore, 明日方舟自动化, 仓库识别, 干员箱, or combining maa-cli with an agent. + 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.1" + tags: arknights maa-cli maacore --- -# maa-cli 使用 +# maa-cli -面向 **调用 maa-cli 跑任务 / 查状态** 的 agent，不是改本仓库源码。 -改 crate、CI、FFI 请看仓库根目录 `AGENTS.md`。 -不要靠 `maa --help` 猜能力边界；命令语法细节以 `maa help ` 和 [reference.md](reference.md) 为准。 +maa-cli 只服务《明日方舟》。它把任务交给已安装的 MaaCore，自己不识图、不点屏幕。 +本机命令多数是 `maa`；Windows winget 安装后是 `maa-cli`。先 `command -v maa`，没有再试 `maa-cli`。下文示例写 `maa`。 +旗标以 `maa help` / `maa help ` 为准。 -Windows 上用 winget 安装时，命令名是 `maa-cli`，下文的 `maa` 一律替换即可。 +**会点击购买或消耗源石的操作，先得到用户明确同意。** -## 先分清三层数据 +## 三层 -|平面|含义|要不要开游戏| -|---|---|---| -|catalog|静态表：MaaResource（`item_index.json` 等）或 ArknightsGameData|否| -|account|截图 OCR：仓库 Depot、干员箱 OperBox|要模拟器/客户端| -|action|点击游戏：Fight、基建、公招、信用商店|要| +会操作游戏的命令要求三层同时就绪。缺哪一层就补哪一层。 -查技能数值、攻防、专精材料 → catalog（GameData），**不是** MaaResource，更不是 OCR。 -查「我有多少固源岩」→ account（Depot）。 -「帮我刷 1-7」→ action。 +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`）。 -1. 二进制可用：`maa version`。 -2. MaaCore 已装：`maa install`（已装则 `maa update`）。资源热更新：`maa hot-update`。 -3. 需要跑游戏任务时，设备已连接（ADB / PlayCover 等），配置用 `maa init` 或 `$MAA_CONFIG_DIR` 下的 profile。 -4. 配置目录：`maa dir config`（可用 `MAA_CONFIG_DIR` 覆盖）。 +## 冷启动 -未装 Core 时不要编造任务结果。路径一律用 `maa dir …`，不要写死 `/usr/local` 或 `C:\Program Files`。 +完成标准：`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`。**完成：** 不会在提示符上卡住。 -### 管理 +## 连接怎么选 -- `maa install` / `maa update`：安装或更新 MaaCore 与资源。 -- `maa self update`：更新 maa-cli 自身；包管理器安装的用户不要用这条。 -- `maa hot-update`：热更新资源仓库，不替换 Core 自带的基础资源。 -- `maa init`：交互初始化 profile。 -- `maa version` / `maa dir `。 +|本机|游戏怎么跑|`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`。 +完整模板、分平台依赖、排错：读 [setup.md](setup.md) 对应平台小节。 -- `maa startup [client]` / `maa closedown [client]` -- `maa fight [stage]`（如 `1-7`；空则上次/当前关） -- `maa copilot ...`：作业 URI 用 `prts://` 或 `prts://s` 或本地 JSON；`maa://` 已弃用。 -- `maa sscopilot` / `maa paradoxcopilot` / `maa roguelike ` / `maa reclamation ` +最小 PlayCover profile： -### 自定义任务 +```toml +[connection] +preset = "PlayCover" +address = "127.0.0.1:1717" +``` -- 文件在 `$MAA_CONFIG_DIR/tasks/`，`maa run <文件名不含扩展名>`。 -- `maa list` 列出可用任务。 -- Depot / OperBox **没有** `maa depot` 这种预设子命令，只能写自定义任务，`type` 为 `Depot` 或 `OperBox`。 -- 任务类型与参数以 [MAA 集成文档](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/dev/docs/zh-cn/protocol/integration.md) 为准；maa-cli **不校验** 参数名，错了要等 Core 运行时才爆。 +最小 ADB profile： -### 只读 / 工具 +```toml +[connection] +preset = "ADB" +adb_path = "adb" +address = "emulator-5554" +``` -- `maa activity [client]`：当前活动关卡提示（catalog + 资源，不 OCR 背包）。 -- `maa convert`、`maa complete`、`maa cleanup`、`maa import`、`maa remainder`。 +## 命令怎么路由 -参数示例：`maa fight BB-7 -m 3` 用 3 瓶理智药。 -日常串联：`maa startup Official && maa fight 1-7 -m 3 && maa closedown`。 +|用户要|去做| +|---|---| +|装 / 更新 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://` 或 `prts://s`，或本地 JSON。 +自定义任务放 `$MAA_CONFIG_DIR/tasks/`。类型名与识别边界见 [reference.md](reference.md)。 +`Mall` 的 `buy_first` / `blacklist` 会在信用商店真实下单。 -- **信用商店 `Mall` 会真的下单。** 自定义任务里的 `buy_first` / `blacklist` 是执行规则，不是建议。 -- **不要代买红票/黄票/绿票/情报凭证商店。** 当前 maa-cli 也没有这些店的只读扫描命令。若用户要购买建议：用 catalog 货盘 + 已有 Depot 材料，输出清单，默认不 click。 -- 不要把 OCR 快照当成完整账号资产。边界见 [reference.md](reference.md)。 -- 需要确认才执行会消耗源石（`--stone`）或清空理智的长时间 Fight。 +## 何时读哪份文件 -## 给 agent 的输出习惯 +- 缺 cli / Core、要写 profile、连不上：读 [setup.md](setup.md) 里对应当前 OS 的那一节。 +- 自定义 `type`、URI、仓库/干员箱能扫到什么：读 [reference.md](reference.md) 对应小节。 -跑任务后据实汇报：用了哪些命令、任务总结里的关卡/掉落/公招，以及 OCR 没覆盖的部分。 -引用物品用 `item_index.json` 的 id（如固源岩 `30012`），不要只写俗称。 -区分「Core 没这个功能」和「命令写错了」。 +官方文档： -## 人类文档 +- 安装： +- 使用： +- 配置： -- 安装：[docs/zh-CN/install.md](../../crates/maa-cli/docs/zh-CN/install.md) -- 使用：[docs/zh-CN/usage.md](../../crates/maa-cli/docs/zh-CN/usage.md) -- 配置与自定义任务：[docs/zh-CN/config.md](../../crates/maa-cli/docs/zh-CN/config.md) -- 示例任务：`crates/maa-cli/config_examples/tasks/daily.json` -- 命令与 OCR 边界：[reference.md](reference.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 index 9144890c..d252d213 100644 --- a/skills/maa-cli/reference.md +++ b/skills/maa-cli/reference.md @@ -1,93 +1,92 @@ # maa-cli 参考 -SKILL.md 的补充。只在需要物品 ID、OCR 边界或商店建议时再读。 +任务类型和识别边界。旗标以 `maa help` 为准。 -## 物品 ID（俗称） +## Contents -来自已安装的 MaaResource `item_index.json`（`maa dir resource`）。 +- [子命令 vs 任务类型](#子命令-vs-任务类型) +- [Copilot URI](#copilot-uri) +- [客户端](#客户端) +- [物品 ID 与 Depot](#物品-id-与-depot) +- [OperBox / Mall](#operbox--mall) +- [安装资源里有什么](#安装资源里有什么) +- [条件与 batch](#条件与-batch) -|ID|名称|classifyType|备注| -|---|---|---|---| -|`4001`|龙门币|NORMAL|| -|`4002`|至纯源石|NORMAL|| -|`4003`|合成玉|NORMAL|| -|`4004`|高级凭证|NORMAL|黄票| -|`4005`|资质凭证|NORMAL|绿票| -|`4006`|采购凭证|NORMAL|红票| -|`REP_COIN`|情报凭证|NORMAL|| -|`3003`|赤金|NORMAL|| -|`7001`|招聘许可|NORMAL|| -|`7002`|加急许可|NORMAL|| -|`7003`|寻访凭证|NORMAL|| -|`7004`|十连寻访凭证|NORMAL|| -|`classic_gacha`|中坚寻访凭证|NORMAL|| -|`30012`|固源岩|MATERIAL|| - -`classifyType == MATERIAL` 才是 Depot 材料页模板白名单（芯片、精英材料、技能书、作战记录、模组数据块等）。票和货币是 `NORMAL`，不进该白名单。 - -## Depot / OperBox +## 子命令 vs 任务类型 -两者都是 MaaCore 任务类型，maa-cli 只在 callback 里把 JSON 打到日志，**不落盘、没有 `maa query`。** -自定义任务示例： +|能力|有子命令|自定义任务 `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`| -```toml -[[tasks]] -type = "Depot" -``` +自定义任务文件：`$MAA_CONFIG_DIR/tasks/`，`maa run `。 +基建计划 JSON：`$MAA_CONFIG_DIR/infrast/`（必须 JSON）。maa-cli 不按时段读计划文件，要用任务 `condition` 配 `plan_index`。 +Schema： +参数权威：[集成文档 · 任务类型](https://maa.plus/docs/zh-cn/protocol/integration.html) -Depot 是截图模板匹配 + 数量 OCR，不是读游戏内存，也不是「屏幕上有什么就扫什么」。 +`maa fight --help` 给出作战旗标。`--stone` 先确认；`-D<物品ID>=件数` 的 ID 来自 `item_index.json`（`maa dir resource`）。 -### Depot 实际覆盖 +未知 `connection.preset` 会被当成 `ADB` 并打警告。PlayCover 的别名是 `PlayTools`。 -- 默认在仓库**材料**页滑动，只匹配 `MATERIAL` 模板。 -- 较新的 MaaCore（自 v6.14.2 起部分版本）会再点「全部」，硬编码再扫：`4002` `4003` `4001` `3003` `4006`（源石、合成玉、龙门币、赤金、红票）。 -- **默认不扫**：黄票 `4004`、绿票 `4005`、情报凭证、寻访/中坚寻访/十连、招聘许可、加急许可。这些多在消耗品或其它分页。 -- 理智在战斗 callback `SanityBeforeStage`，不在 Depot。 -- 信用点走 `Mall`，不是仓库。 +## Copilot URI -### OperBox +优先 `prts://`（单份作业）或 `prts://s`（作业集）。 +也接受本地路径或 `file://`。 +`maa://` / `maa://s` 仍能用，但会告警弃用。 -- 有：`id` / `name` / `own` / `elite` / `level` / `potential` / `rarity`。 -- 无：技能等级、专精、模组、信赖、基建技能解锁。 +## 客户端 -## Mall 与凭证店 +|值|说明|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`|同左| -`Mall` 只自动买**信用商店**，会真实点击购买。 -红/绿/黄票店、情报凭证店：**没有**预设扫描或自动购买。 +## 物品 ID 与 Depot -凭证店「库存」是**本号本周期限购余量**，不是全服抢货。 -购买建议（只输出、不代买）需要： +票和货币的常用 ID（其余查 `item_index.json`）： -1. catalog：货盘与价格（GameData `shop_client_table` 等，红绿票店货盘相对稳定）。 -2. account：票余量（需扩 Depot 或商店顶栏 OCR，**现成命令没有**）。 -3. account：材料缺口（现有 Depot 材料页）。 -4. 限购余量：商店页 OCR 或自行记账（现成命令没有）。 +|ID|名称|classifyType|备注| +|---|---|---|---| +|`4001`|龙门币|NORMAL|| +|`4002`|至纯源石|NORMAL|| +|`4003`|合成玉|NORMAL|| +|`4004`|高级凭证|NORMAL|黄票| +|`4005`|资质凭证|NORMAL|绿票| +|`4006`|采购凭证|NORMAL|红票| +|`REP_COIN`|情报凭证|NORMAL|| +|`30012`|固源岩|MATERIAL|`-D` 示例常用| -不要声称已经根据黄/绿票余量给过精确可买清单，除非用户提供了这些数字或另有扫描结果。 +`classifyType == MATERIAL` 才是 Depot 材料页模板白名单。票和货币是 `NORMAL`。 -## MaaResource vs GameData +Depot 是自定义任务 `type = "Depot"`，截图模板匹配 + 数量 OCR。结果打在日志里，不落盘。 +部分 Core 会再扫「全部」页的源石/合成玉/龙门币/赤金/红票；黄票、绿票、情报凭证、寻访凭证、招聘许可以当前日志为准。 +理智在战斗 callback `SanityBeforeStage`。信用点走 `Mall`。 -MaaResource（`maa install` 装的）够 OCR 和作业，不够养成 wiki： +## OperBox / Mall -- 有：物品名、关卡掉落**种类**、干员职业/射程、基建技能**文案与排班效率**、公招 tags。 -- 无：攻防 HP、战斗技能各等级数值、天赋、专精/模组材料与解锁条件。 +OperBox 日志字段：`id` / `name` / `own` / `elite` / `level` / `potential` / `rarity`。技能等级、专精、模组、信赖不在结果里。 -完整表用 ArknightsGameData（`character_table` / `skill_table` / `building_data` / `item_table` / `stage_table` / `uniequip_table`），适合 ingest 成 SQLite 再查。 -掉率用企鹅物流，不要写进 GameData。 +`Mall` 只自动买信用商店，会真实点击购买。红/绿/黄票店和情报凭证店没有扫描或自动购买子命令。 +凭证店「库存」是本号本周期限购余量。没扫到的票余量和限购次数不当成已经读到。 -## 常用 Fight 参数 +## 安装资源里有什么 -- `-m/--medicine`：理智药数量。 -- `--stone`：源石；`--dr-grandet` 等 1 理智再确认。 -- `--times`：次数上限。 -- `-D30012=100`：指定掉落件数后停止，可重复。 -- `--series`：连战次数，`-1`～`6`。 +`maa install` 装的资源够识别图标和跑作业：物品名、关卡掉落种类、干员职业/射程、基建技能文案与排班效率、公招 tags。 +养成数值（攻防 HP、技能各等级、专精/模组材料）查游戏数据或 wiki。掉率查企鹅物流。 -日志：`MAA_LOG`，`-v`/`-q`，`--log-file`；任务总结可用 `--no-summary` 关掉。 +## 条件与 batch -## 自定义任务位置 +自定义任务可用 `Time` / `DateTime` / `Weekday` / `DayMod` / `OnSideStory` 以及 `And`/`Or`/`Not`。 +`timezone = "Official"` 用游戏日界（官服 UTC+4），不是东八区 0 点。 +当天 `DayMod` 余数：`maa remainder `。 -- 任务：`$MAA_CONFIG_DIR/tasks/` -- 基建计划 JSON：`$MAA_CONFIG_DIR/infrast/`（必须 JSON，maa-cli 不按时段读计划文件，要用 `condition` + `plan_index`） -- 示例：`crates/maa-cli/config_examples/tasks/daily.json` -- Schema：`crates/maa-cli/schemas/task.schema.json` +任务参数里的 `Input`/`Select` 在交互运行时会提问。`--batch` 用默认值；没有默认值就失败。 diff --git a/skills/maa-cli/setup.md b/skills/maa-cli/setup.md new file mode 100644 index 00000000..267f0d08 --- /dev/null +++ b/skills/maa-cli/setup.md @@ -0,0 +1,206 @@ +# 安装与运行时 + +在用户本机把 maa-cli 接到能打的明日方舟客户端。 +命令示例写 `maa`；winget 安装后改成 `maa-cli`。 +技能未写到的安装细节以 [install.md](https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/docs/zh-CN/install.md) 和 [config.md](https://github.com/MaaAssistantArknights/maa-cli/blob/main/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 的「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 + +目录：`$(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`。 From 24feb9fda74741fc29313d37dba39f031e989a77 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=87=A1=E8=BE=9E?= Date: Thu, 20 Aug 2026 13:10:41 +0800 Subject: [PATCH 3/4] docs: add mid-term design for the agent query surface OCR acquisition and on-demand query are the product; shop advice is only one consumer of those facts. --- AGENTS.md | 1 + DEVELOPMENT.md | 1 + docs/design/query-surface.md | 115 +++++++++++++++++++++++++++++++++++ skills/maa-cli/reference.md | 3 +- 4 files changed, 119 insertions(+), 1 deletion(-) create mode 100644 docs/design/query-surface.md diff --git a/AGENTS.md b/AGENTS.md index c8f9b558..c080235a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -124,6 +124,7 @@ graph TD - One paragraph per line; use `
` 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) 检查。 - 段落内不换行，每段仅一行，段落间空行分隔。非段落换行请用 `
`，不要用尾随空格。 +- 尚未实现、需要跨 MaaCore / maa-cli 讨论的方案放在 [`docs/design/`](docs/design/)（例如 [信息查询面](docs/design/query-surface.md)），不要写进用户手册或 `skills/maa-cli/` 当成已有命令。 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 +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/reference.md b/skills/maa-cli/reference.md index d252d213..339513d3 100644 --- a/skills/maa-cli/reference.md +++ b/skills/maa-cli/reference.md @@ -75,8 +75,9 @@ Depot 是自定义任务 `type = "Depot"`，截图模板匹配 + 数量 OCR。 OperBox 日志字段：`id` / `name` / `own` / `elite` / `level` / `potential` / `rarity`。技能等级、专精、模组、信赖不在结果里。 -`Mall` 只自动买信用商店，会真实点击购买。红/绿/黄票店和情报凭证店没有扫描或自动购买子命令。 +`Mall` 只自动买信用商店，会真实点击购买。红/绿/黄票店和情报凭证店没有扫描或自动购买子命令。没有 `maa snapshot` / `maa query`。 凭证店「库存」是本号本周期限购余量。没扫到的票余量和限购次数不当成已经读到。 +中期方向（OCR 扩采集 + 按需查询，决策是消费者）见 [信息查询面](../../docs/design/query-surface.md)。 ## 安装资源里有什么 From c5de274715bea452b87d5a1062371f1567c5d283 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=87=A1=E8=BE=9E?= Date: Thu, 20 Aug 2026 14:15:21 +0800 Subject: [PATCH 4/4] docs: point the skill at in-repo manuals and one connection table Keep preset routing in SKILL.md and profile templates in setup.md so the two files stop drifting. --- skills/maa-cli/SKILL.md | 30 +++++++----------------------- skills/maa-cli/reference.md | 2 +- skills/maa-cli/setup.md | 6 ++++-- 3 files changed, 12 insertions(+), 26 deletions(-) diff --git a/skills/maa-cli/SKILL.md b/skills/maa-cli/SKILL.md index 7d1d591b..1a59288e 100644 --- a/skills/maa-cli/SKILL.md +++ b/skills/maa-cli/SKILL.md @@ -8,7 +8,7 @@ description: >- license: AGPL-3.0-only metadata: author: MaaAssistantArknights - version: "0.2.1" + version: "0.2.2" tags: arknights maa-cli maacore --- @@ -42,6 +42,8 @@ maa-cli 只服务《明日方舟》。它把任务交给已安装的 MaaCore， ## 连接怎么选 +选 `preset` 用下表。写入文件的完整模板、分平台依赖、排错见 [setup.md](setup.md) 对应平台小节和「写连接 profile」。 + |本机|游戏怎么跑|`connection.preset`|默认地址| |---|---|---|---| |macOS|PlayCover 安装的 iOS 包|`PlayCover`|`127.0.0.1:1717`（以窗口标题 `[host:port]` 为准）| @@ -52,24 +54,6 @@ maa-cli 只服务《明日方舟》。它把任务交给已安装的 MaaCore， PlayCover 预设强制 `MacPlayTools`，并加载 iOS 资源。窗口保持可见。B 服没有 iOS 包。 本次运行覆盖地址：`maa fight 1-7 --addr 127.0.0.1:1717`。 -完整模板、分平台依赖、排错：读 [setup.md](setup.md) 对应平台小节。 - -最小 PlayCover profile： - -```toml -[connection] -preset = "PlayCover" -address = "127.0.0.1:1717" -``` - -最小 ADB profile： - -```toml -[connection] -preset = "ADB" -adb_path = "adb" -address = "emulator-5554" -``` ## 命令怎么路由 @@ -91,11 +75,11 @@ address = "emulator-5554" - 缺 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) ## 常见错误 diff --git a/skills/maa-cli/reference.md b/skills/maa-cli/reference.md index 339513d3..8eac7181 100644 --- a/skills/maa-cli/reference.md +++ b/skills/maa-cli/reference.md @@ -26,7 +26,7 @@ 自定义任务文件：`$MAA_CONFIG_DIR/tasks/`，`maa run `。 基建计划 JSON：`$MAA_CONFIG_DIR/infrast/`（必须 JSON）。maa-cli 不按时段读计划文件，要用任务 `condition` 配 `plan_index`。 -Schema： +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`）。 diff --git a/skills/maa-cli/setup.md b/skills/maa-cli/setup.md index 267f0d08..ba341e18 100644 --- a/skills/maa-cli/setup.md +++ b/skills/maa-cli/setup.md @@ -2,7 +2,7 @@ 在用户本机把 maa-cli 接到能打的明日方舟客户端。 命令示例写 `maa`；winget 安装后改成 `maa-cli`。 -技能未写到的安装细节以 [install.md](https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/docs/zh-CN/install.md) 和 [config.md](https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/docs/zh-CN/config.md) 为准。 +技能未写到的安装细节以 [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` 通过。 @@ -57,7 +57,7 @@ Invoke-WebRequest -Uri "https://raw.githubusercontent.com/MaaAssistantArknights/ 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 的「CLI 相关配置」。 +国内访问 GitHub 失败时，让用户改 `$MAA_CONFIG_DIR/cli.toml` 里的 `api_url` / `download_url` 镜像；镜像字段说明在 [config.md](../../crates/maa-cli/docs/zh-CN/config.md) 的「CLI 相关配置」。 ## 2. 安装 MaaCore 与资源 @@ -150,6 +150,8 @@ Linux 上跑 MAA 桌面 GUI（Wine）与 maa-cli 是两条线；命令行任务 ## 4. 写连接 profile +选哪个 `preset` 见 [SKILL.md · 连接怎么选](SKILL.md#连接怎么选)。本节只写文件模板和触控等字段。 + 目录：`$(maa dir config)/profiles/`。默认名 `default`，扩展名 json/toml/yaml 均可。本次运行换文件：`--profile 名字`。 `maa init` 会交互询问预设（`MuMuPro` / `PlayCover` / `Waydroid` / `Androws` / `ADB`）、adb 路径、地址、触控模式。代理无人值守时直接写文件。