-1分钟上手智能文档（6附件）

使用手册

下载链接与社区

📌
提问前先仔细阅读手册，特别是常见问题部分！
提问前先仔细阅读手册，特别是常见问题部分！
提问前先仔细阅读手册，特别是常见问题部分！
蓝奏云（密码：cb9q）
123 网盘
Github Releases
Github Repo
QQ 群：616128504
QQ 频道：pd13095635（可直接浏览器访问）

常见问题

QQ 群和 QQ 频道有什么区别？

原计划只用 QQ 频道，但是某些时候很不方便，所以又开了个 QQ 群。

是否支持汉化版？

目前不支持。

是否支持 NIA 培育？

目前不支持。

是否支持 DMM？

支持。

是否支持手机？只能电脑用吗？

目前必须有电脑才能使用。后期有计划移植到手机上。

下载与安装

系统要求

在开始安装 kaa 之前：
如果你打算在模拟器上使用 kaa，先检查模拟器是否满足这些设置要求：
分辨率：必须是 1280x720
系统版本：Android 10+（Q，API 29），这是游戏的要求
已开启游戏加速器或代理且网络通畅
 
如果打算使用 DMM 版，最佳游戏分辨率为 720x1280，另外三个分辨率也可使用，但是效果可能没有那么好。
 
此外，必须关闭汉化插件。汉化版的支持仍在计划中。

我应该用哪种方法安装？

对于一般用户，使用下面的「普通方法」安装就可以了。
如果你知道如何使用 Python，且电脑上安装了 Python 3.10 或 Conda，那么也可以使用「高级方法」进行安装。

普通方法

前往蓝奏云（密码：cb9q）或 123 网盘或 Github Releases 下载最新版本的 kaa 启动器（kaa-bootstrap）。
下载下来后，解压，然后可以看到有下面这些文件：
kaa-bootstrap 文件内容
双击「启动 .bat」，kaa 就会开始安装。安装需要的时间因网速而异。安装过程中可能会出现「安装 / 更新时红色字体提示 403」错误，解决方案参考链接。
安装完成后，如果没有报错，kaa 会自动打开一个网页，这个网页就是 kaa 的主界面。
如果报错了，前往 QQ 群或 Github Issue 进行提问。

高级方法

琴音小助手通过 pip 分发，因此你可以执行下面的命令来安装：
Bash
# 需要 Python 3.10
pip install ksaa
ℹ️
提示
琴音小助手的缩写是「kaa」（Kotone's Auto Assist），但是「kaa」已经被其他包占用了，因此改用「ksaa」（Kotone'S Auto Assist）。
不过为了避免依赖冲突，你最好创建虚拟环境，并在虚拟环境中安装 kaa。
安装完成后，只需要运行 kaa 命令即可启动 GUI 界面：
Bash
kaa
需要注意的是，配置文件 config.json 默认自动在工作目录下生成。因此你最好每次都在同一个地方运行 kaa，否则可能会出现找不到配置文件的情况。必要情况下，可以通过 -c/--config 参数指定配置文件路径。
ℹ️
提示
通过 pip 安装的 kaa 并不会自动检查更新。如果新版本发布了，你需要自己执行 pip install -U ksaa 来更新 kaa。

游戏设置

建议开启下面这些设置：
【培育】演出跳过设置
 
 
跳过支援卡剧情 [ON]
 
跳过各培育开始时的说明交流 [ON]
 
跳过定期公演『初』的「在意的事情」交流 [ON]
跳过亲密度交流内的影像 [ON]
 
 
【培育】交流快进设置
[ ] 不快进交流
[x] 快进交流
快进未读交流 [ON]
 
【培育】领取指引显示设置
[x] 显示领取指引
[ ] 不显示领取指引
 
 

kaa 设置

启动 kaa 后，首先进入「设置」选项卡，然后参考下面的说明进行配置。
一些见名知意的配置会跳过说明。

模拟器设置

首先根据你用的模拟器选择不同的类型。MuMu 模拟器和雷电模拟器用户可以直接选择前两个，其他模拟器用户选择「自定义」。DMM 用户选择「DMM」。

MuMu12

【选择多开实例】
首先需要点击「刷新」载入模拟器信息。
如果你有多开，选择自己多开的名称。如果多开，一般列表里只有一个选项，选择那个即可。
【后台保活】
对应 MuMu 模拟器设置里的这个：
如果模拟器设置里有开启，则 kaa 里也需要开启。

雷电

和上面 MuMu 模拟器一样的设置方式，这里不再说明。

DMM

DMM 版不需要额外设置。

自定义

【ADB IP 设置】
一般情况下不需要修改，保持默认值（127.0.0.1 或 localhost）不变即可。
如果需要连接远程模拟器，参见「远程连接」一节。
【ADB 端口】
一般在模拟器的设置里可以查询到。
如果你有多开的话，上面的默认端口可能不适用，你要自己找到多开对应的端口。
【检查并启动模拟器／模拟器 exe 路径／ADB 模拟器名称／模拟器启动参数】
勾选后「检查并启动模拟器」，kaa 启动时会自动检查模拟器是否已启动，如果没有，会尝试启动模拟器，然后再开始运行。
启动模拟器需要设置「模拟器 exe 路径」才能生效。如果你多开了模拟器，可能需要填写「模拟器启动参数」。
「ADB 模拟器名称」一般无需填写。这个对应的是 adb devices 命令中输出的设备名称。

共同设置

【截图方法】
目前有以下五种方法：
类型
稳定性
速度
适用于
是否推荐
特点
adb
稳定
较慢
所有模拟器
✔️作为备用选项
 
adb_raw
不太稳定
快
所有模拟器
❌已废弃
截图更新不及时可能导致某些情况下卡住
uiautomator2
不太稳定
快
所有模拟器
⚠️不太推荐
截图压缩可能导致某些情况下卡住（bug）
windows
较稳定
非常快
DMM
✔非常推荐
脚本运行时不可操作电脑
remote_windows
较稳定
较慢
DMM
🐞一般用于调试
用于控制另一台电脑上的游戏，较少使用
nemu_ipc
稳定
非常快
MuMu 12
✔非常推荐
 
（速度快慢是相对的，具体视设备性能和模拟器不同而定）
✒️
提示
对于 DMM 版用户：
暂停 / 恢复快捷键：Ctrl + F4
停止快捷键：Ctrl + F3
【最小截图间隔】
一般保持默认，不需要修改。如果你的电脑性能较低，可以适当提高间隔（比如 0.1、0.2 秒）。

商店购买 / 活动费 / 礼物 / 工作设置

没有什么要注意的。

培育设置

首先切换到「培育」选项卡。点击新建培育。
【方案名称】【方案描述】
随便填。
【培育模式】
任选，建议 PRO/MASTER。
【要培育的偶像】
✒️
提示：可以打字搜索。
要注意的是不同的皮肤算不同的偶像，详见未找到 ID 为「xxx」的偶像卡。
【培育次数】
如果 AP 不足会跳过剩下的次数。如果之前有未完成的培育，继续未完成的培育也算一次。
【自动编成回忆】
使用游戏内的自动编成回忆。注意，自动编成会覆盖掉原有的编成。
如果不勾选，可以指定要使用的回忆编成编号。
如果既不自动编成，也不指定编号，那么 kaa 会使用游戏默认选中的编成（一般是上次使用的）。（即将废弃，不建议使用）
【自动编成支援卡】
目前必须勾选。勾选与不勾选都是启用。
【使用支援强化 pt 提升】【 使用笔记数提升】
【关注租借了支援卡的制作人】
【文化课时自习选项】
【SP 课程优先】
【行动优先级】
每一周会按照这里指定的优先顺序，选择第一个可用的行动。
「推荐行动」指的是「あさり先生」的推荐提示。
【推荐卡检测模式】
正常模式：快
严格模式：慢，准确率更高
使用「藤田ことね」进行培育时，必须使用严格模式。对于其他的偶像，正常模式足够使用。
【检测并跳过交流】
默认开启。如果你前面开启了游戏的跳过未读交流，那么建议这里关闭，否则需要保持开启。

使用

完成设置后，点击页面最后的「保存设置」，然后重启 kaa。
对于 DMM 版，需要确保游戏画面完整（没有一部分在屏幕外或者被任务栏遮挡）。
检查无误后，在「状态」选项卡里点击「启动」，或者在「任务」选项卡里选择要执行的任务后点击「执行任务」。

高级

远程执行

「远程执行」指的是 kaa 与游戏在两台不同的电脑上运行。
通常情况下不需要远程执行，也不建议远程执行。因为数据需要在两台电脑之间通过网络来回传输，导致截图时间上升，脚本速度变慢。

模拟器

如果你想要连接其他电脑上的模拟器，确保你已经在目标电脑的模拟器上设置了允许远程 ADB 连接。
安全起见，有些模拟器不支持远程连接 ADB，那么你需要自己写个脚本转发 TCP 连接。比如模拟器地址为 127.0.0.1:5555，转发脚本监听 0.0.0.0:5556，kaa 中地址填写 192.168.x.xxx:5556，你的脚本只需要负责接受来自 kaa 的连接、与模拟器建立连接，然后转发模拟器和 kaa 之间的数据。
转发脚本的实现可以参考这里。

DMM

首先在目标电脑上以管理员身份启动远程服务器：
Bash
kaa remote-server
# 这个命令具体在哪个位置见「命令行接口」一节
然后在「ADB IP 地址」中填写目标电脑的 IP 地址，「ADB 端口」填写 8000。

命令行接口

如果你用的是启动器，kaa 命令行可执行文件位于「kaa-bootstrap-0.2.0\WPy64-310111\python-3.10.11.amd64\Scripts\kaa.exe」。你可以直接调用这个文件，不需要激活 Python 环境。
如果是通过其他方法安装，比如 Conda，可能需要先激活环境，再执行 「kaa」命令。
 
命令行接口具体用法参阅帮助输出：
Bash
kaa -h # 显示总帮助
kaa task -h # 显示 task 子命令的帮助
常用命令如下：
Bash
kaa task invoke a b c # 执行任务 a b c
kaa task invoke * # 执行所有任务
kaa task list # 列出所有任务的名称、描述、ID
当使用 DMM 版时，别忘记以管理员身份运行 kaa！（只有执行任务时需要管理员权限，其他如列出任务不需要）
ℹ️
提示
对于 Windows 11 24H2 及以上的版本，可以启用系统内置的 sudo 命令。
对于 Windows 11 24H2 以下及 Windows 10，可以安装「gsudo」作为替代，或手动在管理员终端中执行。

编程接口

为了调用 kaa，你可以在你的 Python 环境中安装 ksaa 模块，或者直接使用「kaa-bootstrap」中附带的 Python 环境。
环境配置完成后，你可以通过kotonebot.kaa.main模块中的 Kaa 类来调用琴音小助手中的功能。具体用法参阅源码「kotonebot\kaa\main\cli.py」。
⚠️
注意：不要创建多个 Kaa 实例，也不要多线程执行多个 Kaa 实例。
如果你想添加新的任务，参阅 开发文档 。

错误自查

培育方案「xxx」不存在

【错误类型】ProduceSolutionNotFoundError
【错误原因】
你误删除了 conf/produce 文件夹下的文件
程序 bug，导致保存了曾经存在现在不存在的培育方案
【解决方案】
前往「设置」中的「培育设置」，检查是否选中了任何培育方案。如果没有，需要选中你想要使用的方案。如果目前没有任何方案，可以前往「培育」新建方案。
 
如果有选中方案，前往「培育」中查看该方案是否存在。如果不存在，「设置」中需要另行选择一个存在的方案。
如果方案存在，可能是程序 bug 导致。可以尝试重启 kaa，在「设置」里再次选中刚刚的方案，并点击保存。
如果问题依旧，前往「反馈」导出报告后联系开发者。

培育方案「xxx」（路径 xxx）存在无效配置，载入失败

【错误类型】ProduceSolutionInvalidError
【错误原因】
可能是由于你从较新的 kaa 版本降级到了旧版，导致配置文件格式不兼容。
【解决方案】
目前升级时只会备份主配置文件，不会备份培育配置，因此你只能删除有问题的配置。

未找到 ID 为「xxx」的偶像卡

【错误类型】IdolCardNotFoundError
【错误原因】
这个问题一般是你没有选择正确的皮肤导致。同一张偶像卡可能会有多个换皮版本，游戏内叫做「アナザー ver.」（部分汉化版译为「另一个 ver.」）。图中圈出来的就是换皮卡：
【解决方案】
目前 kaa 不会自动切换皮肤，因此你需要保证游戏内那张卡选中的皮肤和 kaa 里选中的是同一个皮肤，如果不是，需要手动切换。
比如上面第二张图的皮肤在 kaa 里应该选：
皮肤的名称也可以在培育选人界面上方看到：

未找到启动器「kaa.exe」

【错误类型】LauncherNotFoundError
【错误原因】
文件 kaa.exe 丢失。正常情况下不应该出现这个错误。
【解决方案】
检查 kaa.exe 是否存在。
如果不存在，且你使用的仍然是旧版启动器（kaa-bootstrap v0.2.0 及以前的版本），请先更新到新版启动器（> v0.3.0）。
如果存在，联系开发者寻求帮助。

请以管理员身份运行 kaa。

【错误类型】ElevationRequiredError
【错误原因】-
【解决方案】
如果你是双击 kaa.exe 启动的小助手，首先尝试重启。启动过程中应该会自动获取管理员权限，如果没有，说明这是个 bug，请前往 QQ 群或 Github 反馈。
如果你是其他方式启动的，那么需要你手动以管理员方式启动 kaa。

请先升级启动器到 xxx 以上版本

【错误类型】-
【错误原因】-
【解决方案】
在「下载链接与社区」里找到最新版本的启动器（kaa-bootstrap），下载后覆盖解压到现在已有的 kaa 目录下，完成升级，然后再尝试之前的操作。

培育时乱出牌

如果用的是琴音，「推荐卡检测模式」中需要选择「严格模式」。
如果问题依旧，前往 QQ 群中寻求帮助。

DMM 版怎么后台执行？

目前不支持。

DMM 下鼠标在动但是脚本点击没有效果

使用 DMM 版时必须通过右键「启动（Windows）.bat」，选择以管理员身份运行来启动脚本。
极小概率下，杀毒软件（如火绒）可能会导致此问题，可用尝试关闭杀毒软件后再试。

模拟器下启动脚本后没任何反应，也没报错

分辨率是否为 1280x720（或 720x1280）
是否关闭汉化插件
如果都没问题，前往 QQ 群或 GitHub 提问或反馈 bug。

一直卡在 Trying to go home...

手动切换到游戏首页，看看问题是否解决
检查模拟器分辨率是否正确（1280x720）
如果问题持续，前往 QQ 群或 GitHub 提问或反馈 bug。

ValueError: cannot connect to 127.0.0.1:5555: 由于目标计算机积极拒绝，无法连接

首先检查你的端口号是否正确。
若是，尝试关闭模拟器和 kaa，然后打开任务管理器，搜索“adb.exe”，结束所有搜索结果，然后启动模拟器和 kaa 再试。

安装 / 更新时红色字体提示 403

关闭代理或加速器后等待一段时间再尝试。如果依旧有问题，尝试更换网络环境。

启动时 ModuleNotFoundError: No module named 'xxxx'

某些模块安装时失败了，目前原因未知。可以尝试从 123 网盘或 Github Release 中下载「完整版」kaa 再试。

只能安装 v2025.3.9.4 版本，无法更新 kaa

v2025.3.9.4 以后的版本只支持 Python 3.10，更新或更旧的 Python 都不行。你可以改用 conda 等虚拟环境，或改用启动器（kaa-bootstrap）。

培育报错：idol = next(idol_iterator) StopIteration

检查你有没有设置要培育的偶像。
 

贡献

目前 kaa 有下面这些周边任务，如果你有意向共同开发 kaa，可以从下面这些入手，或者从 GitHub Issue 中入手：
UI 重写
由于后续计划支持 Android 版，为了便于移植，可能选择的方案有
任意 Python 后端框架 + 任意 Web Javascript 框架
PySide
不能用 PyQt-Fluent-Widgets，因为这个库似乎不支持触摸，也不支持 PySide
Flet / Flutter
汉化版本支持（计划中）
通知推送
需要支持更多平台
模拟器控制
包括自动扫描系统上安装的模拟器，获取多开信息，自动猜测端口号等
移植 kaa 到 Android 上
核心问题是目前依赖过多，相当一部分依赖没有预编译包，需要手动编译（尤其是 rapidocr）
另一个问题是如何通过 Pyjnius 调用 Shizuku 或无障碍 API
以及下面这些核心任务：
调度
记录每个任务的上次执行时间，规划下次执行时间
定时唤起 kaa 并执行任务
跳过重复执行的任务
支持 NIA 培育