wilma

Wilma 技能

概述

Wilma 是芬兰的学校信息系统，供学校和市政机构与家长/监护人分享消息、新闻、考试、日程、家庭作业以及其他与学生相关的动态。

有两种方式可以访问 Wilma。两者返回的数据相同，JSON 格式也相同。

1. MCP 工具 — 如果有名为 wilma_* 的工具可用（WilmAI 连接器、桌面扩展或插件），请使用这些工具。无需使用 shell。
2. CLI — 否则请使用 wilma（或 wilmai）命令。运行时会输出 JSON（无需添加 --json），而 wilma help <command> 会显示用法、示例和 JSON 格式。

两种方式默认都涵盖每个孩子；传入 student / --student <number|name> 可将范围缩小到一名学生。结果按孩子返回：{ students: [{ student: { studentNumber, name, wilma? }, … }] }。时间采用芬兰时间，并带有时区偏移量（2026-10-02T13:37:00+03:00）——请原样报告，不要转换。为用户书写日期时，请遵循回复所用的语言：芬兰语 ke 7.10.（末尾带句点），英语 Wed 7 Oct。Wilma 自带的文本使用芬兰语格式；请转换格式，不要混用两种格式（不要写成 Wed 7.10）。

MCP 工具	CLI 命令
wilma_summary	wilma summary [--since <date>]
wilma_schedule	wilma schedule [today|tomorrow|week|next-week|<date>|<weekday>]
wilma_homework	wilma homework
wilma_upcoming_exams	wilma exams
wilma_grades	wilma grades
wilma_gradebook	wilma gradebook
wilma_lesson_notes	wilma notes [--date <date> | --days N]
wilma_lesson_notes_summary	wilma notes summary
wilma_list_messages / wilma_read_message	wilma messages / wilma messages <id>
wilma_list_news / wilma_read_news	wilma news / wilma news <id>
wilma_get_news_attachment	wilma news <id> download <resource>
wilma_list_printouts / wilma_get_printout	wilma printouts / wilma printouts <id>
wilma_account	wilma students, wilma accounts
wilma_find_school	wilma find-school <city>
—	wilma home（WilmAI Home，桌面应用：下载位置）
wilma_login	wilma login
wilma_logout	wilma logout

日期格式为 YYYY-MM-DD、today、yesterday 或 tomorrow。

登录

用户只需登录一次；登录信息会保存在其电脑上。

• **在用户自己的电脑上：**运行 wilma login（或调用 wilma_login）。这会在用户的浏览器中打开一个页面，供其选择学校的 Wilma 并登录。等待命令完成。
• 在用户看不到的云端电脑上（没有可访问的浏览器）：
  1. 询问孩子的学校所在城市（或学校名称）。运行 wilma find-school <city>（或调用 wilma_find_school），让用户从结果中选择——一个城市通常会有多个 Wilma（市立学校、私立学校、学院）。
  2. 请用户在你的机密信息或环境设置中添加 WILMA_USERNAME 和 WILMA_PASSWORD；如果账户使用两步验证，还要添加 WILMA_TOTP_SECRET，并将 WILMA_TENANT 设置为他们选择的 Wilma 地址。之后每条命令都可以在没有已保存登录信息的情况下运行。或者使用：wilma login --tenant <url> --username <name> --password-stdin。
• 不要在终端中不带参数运行 wilma 来查找信息：在终端中它会打开供用户使用的菜单；从程序中运行则会打印帮助信息。
• 绝不要要求用户在聊天中输入 Wilma 密码。
• 孩子使用不同的 Wilma（例如，一人就读市立学校，另一人就读私立学校）：用户可以在登录页面选择“添加另一个 Wilma”，也可以再运行一次 wilma login 来添加每个登录信息。所有已保存的登录信息会一起使用；之后每个孩子都会有一个标明其 Wilma 的 wilma 字段。wilma accounts 会列出登录信息。

后续命令会继续使用上次的 Wilma 会话，而不是每次都重新登录（每次登录都会让家长在自己的浏览器中退出 Wilma），因此可以连续运行多条命令。

如果用户想在浏览器中使用 Wilma，或要求你退出登录，请运行 wilma logout 或调用 wilma_logout（wilma-cli 2.2+）。这会结束 WilmAI 的 Wilma 会话，但保留已保存的登录信息。之后除非用户要求，否则不要运行其他 Wilma 命令：下一条命令会重新登录，并使用户在浏览器中的 Wilma 退出登录。

安装

npm i -g @wilm-ai/wilma-cli

核心任务

每日简报（从这里开始）

wilma summary
wilma summary --since yesterday

每个孩子：今天和下一个上学日的课程、即将到来的考试（如有起始时间则一并显示）、最近的家庭作业、从上一个上学日之后的课程备注（教师反馈和缺勤）、最近的公告，以及最近的和未读的消息（unread、replyCount）。--since <date> 只保留从该日期起的内容——用于定时每日运行。如果 Wilma 无法提供某部分，unavailable 会列出该部分。

课程表

wilma schedule tomorrow
wilma schedule week
wilma schedule next-week
wilma schedule 2026-03-10
wilma schedule thu --student <number|name>

默认显示本周。tomorrow 指下一个上学日；星期几（mon…sun，或芬兰语 ma…su）指下一个该星期几。课程会包含教师，以及 Wilma 提供时的 room。

家庭作业和考试

wilma homework
wilma exams

每场考试都包含日期、科目、名称、主题（需要复习的内容）和教师；如果学校提供了 time，则为考试开始时间（否则为 null）。

成绩

wilma grades       # recent exam grades
wilma gradebook    # course and report-card grades

成绩册（Suoritukset）是一个树状结构：科目 → 教学大纲 → 课程，每项都包含 grade、credits 和完成日期 date。课程代码以 LV 结尾的通常是学年（成绩单）成绩。列表为空表示目前还没有任何已评分内容。

课程备注（merkinnät）

wilma notes --date yesterday
wilma notes --days 14
wilma notes summary

教师对每节课的备注：积极反馈、行为评语、缺少课本或家庭作业，以及缺勤类别（病假、已说明、未说明）。默认查看一天（今天）；使用 --days N 查看最近 N 天，或使用 --from/--to 指定范围。教师通常会在上课期间或课后填写备注，因此早晨运行时请使用前一天（摘要已采用此前一天）。教师写下的内容会显示在 note 中。

notes summary 会统计本学年各 typeLabel 的备注数量（也可使用 --from/--to），例如因健康原因缺课的次数。

每条备注都包含 Wilma 课时表中的 start/end 时间（精确到课时）。subject 是课程代码（例如 MA_8LV = 数学，八年级；如果备注与课程无关则为空），typeLabel 是 Wilma 使用的芬兰语标签。

消息和公告

wilma messages
wilma messages --folder appointments
wilma messages <id>
wilma news
wilma news --older
wilma news <id>

消息列表会标记 unread 消息和 replyCount；wilma messages <id> 会返回包含 replies 的对话串。wilma news 会返回最新的带日期公告，以及所有置顶公告（pinned: true，例如学年公告）；--older 会添加较早的公告（archived: true，读取后会显示日期）。读取条目时无需使用 --student，除非连接了多个 Wilma。

打印文件

wilma printouts
wilma printouts <id> --output <directory>

学校提供的 PDF 文档，例如成绩单或缺勤报告（因学校而异）。

公告附件

请务必检查 wilma news <id> 返回的 resources 数组。每个资源都包含：

• id — 在公告内稳定不变（resource-1、resource-2，……）；下载命令也接受单独的数字（1）。
• label — 公告中的链接文本。
• url — 绝对 URL。
• authContext — "wilma"：下载时使用 Wilma 会话。"external"：下载时使用独立的、未经身份验证的请求，绝不会发送 Wilma 凭据（就像在已退出登录的浏览器中打开链接）。
• fileName — 当 URL 路径看起来像文件时提供的命名提示；即使是真实文件，也可能为 null。

可以尝试下载任何资源。 无法可靠地预先判断 URL 是公开提供文件、需要登录，还是普通网页，因此 CLI 不会猜测：它会尝试下载，并报告实际结果。当文档与用户的请求相关时，请尝试下载：

wilma news <news-id> download <resource-id> --output <directory>

处理返回的 status：

• downloaded — 文件已写入。使用返回的绝对 path，并以 contentType/sizeBytes 为准，而不要依据公告标签猜测。
• not_a_file — 链接返回的是网页，而不是文件。这通常表示文档需要登录（例如私有云盘分享链接），或者链接本身就是网页。请向用户说明；如果需要访问，请在经过用户授权且已通过外部服务身份验证的浏览器会话中打开 url。切勿循环重试下载。
• 错误（见下文）— 下载尝试本身失败（HTTP 错误、网络问题、超出大小限制）。请报告 message。

通过 --output 将下载文件保存在任务专用目录中（默认是当前工作目录）。绝不会覆盖现有文件——会在文件名后追加数字后缀。

优先使用资源元数据，而不是 content 中嵌入的 URL；content 是文本内容，仅包含链接的公告中可能为 null。

使用 MCP 工具时，wilma_get_news_attachment 会返回文件本身（文本以内嵌文本的形式返回、图片以图片形式返回、PDF 等其他文件以嵌入文件的形式返回），并采用相同的 not_a_file 处理方式。传入 save: true 还会将副本保存到用户的 Downloads/WilmAI 文件夹。

选择孩子

--student 接受学生编号、全名或名字或姓氏的开头部分（例如，Kiia 对应 "Kiia Example"）。名称无法识别或存在歧义时会报错（unknown_student / ambiguous_student）并列出孩子；不确定时，请使用 wilma students 中的编号或全名。

错误

错误同样以 JSON 格式返回：{ "status": "error", "code": "…", "message": "…" }（有时还包含 hint 和 cause）。退出代码 2 表示用法错误（invalid_argument、unknown_command — 请修正命令；wilma help <command>），3 表示 not_logged_in（见“登录”），1 表示其他错误：unknown_student、ambiguous_student、not_found、login_failed（保存的密码已失效——请让用户重新运行 wilma login）、mfa_required / mfa_failed、network、wilma_error。

MFA（两步验证）

如果 Wilma 账户启用了 MFA/TOTP，登录时需要身份验证器设置密钥（base32 密钥或 otpauth:// URI），才能无人值守地运行：

• wilma login： Wilma 要求输入设置密钥时，登录页面会提示输入，并将其与登录信息一同保存。
• 环境变量： 设置 WILMA_TOTP_SECRET。
• 单次使用： --totp-secret <base32-key|otpauth://...> 可用于任何命令，但命令行中的密钥会留在 shell 历史记录中；建议优先使用以上两种方式。

说明

• 如果 CLI 提示没有已保存的登录信息，请运行 wilma login（登录同一个 Wilma 会替换原有登录信息）。wilma accounts 会列出已保存的登录信息，wilma accounts remove <number> 会删除其中一项；wilma config clear 会删除所有已保存的登录信息。
• 此技能适用于 WilmAI CLI 2.x。如果 wilma --version 显示 1.x，请运行 wilma update（在此之前，scripts/wilma-cli.sh 会通过 npx 运行 2.x）。
• 更新。 有新版 WilmAI 时，命令会在 stderr 中输出 Update available: <old> → <new>（每天最多一次）。先完成用户的请求，再运行 wilma update；如果无法在此处安装软件，请告知用户。
• 回复、报名、报告缺勤。 WilmAI 只能读取 Wilma。用户想要回复消息、报名参加活动或报告缺勤时，请说明这一点并引导他们使用 Wilma，或使用同一项目提供的桌面应用 WilmAI Home；该应用可以完成这些操作（wilma home 会提供适用于其电脑的下载链接；不使用 CLI 时，请访问 https://wilm.ai/home）。仅在用户想进行上述操作或想要自己的 Wilma 应用时提及 Home；下载和安装由用户自行完成。
• 1.x 版本的命令写法（kids list、tenants、attendance list、<command> list、messages read <id>、news read <id>、news resource download …、--all-students）仍然有效。
• 受管设备上的 TLS 错误。 如果命令以 network 代码失败，且 cause 类似 UNABLE_TO_GET_ISSUER_CERT_LOCALLY，说明网络正在拦截 TLS，并使用 Node 不信任的私有根 CA 重新签署证书。请阅读 hint 并转告用户，不要重试。解决方法是使用 NODE_USE_SYSTEM_CA=1 运行 CLI（Node >=22.19/>=24.6），或运行 node --use-system-ca "$(command -v wilma)"（Node >=22.15）。切勿建议使用 NODE_TLS_REJECT_UNAUTHORIZED=0；它会完全禁用验证。npm install 能正常运行并不能证明 TLS 状况正常——npm 注册表通常不会被检查。

行动指南（适用于家长）

Wilma 中既有紧急事项，也有一般信息。为家长总结时，请优先关注需要采取行动的事项：

应包含以下事项：

• 需要采取行动或做好准备的事项（表格、回复、许可、需要携带的材料）。
• 有关学习用品缺失、作业、行为表现或原因不明的缺勤的课堂记录。
• 家长发起的对话串中的回复（消息列表中的 replyCount）。
• 提及截止日期或特定时间要求的事项。
• 描述日程变更或值得关注的活动的事项（出游、主题日、学校停课、考试）。
• 提及作业、考试或即将到来的截止日期的事项。

降低优先级的事项：

• 纯粹提供信息，不涉及行动、截止日期或日程影响的事项。
• 与目标时间段无关的一般公告。

如有疑问，请纳入总结，由家长自行判断。建议提供简短、结构清晰的总结，并注明日期和 ID。

脚本

scripts/wilma-cli.sh 会运行已安装的 wilma（或 wilmai）（如果版本为 2.x 或更高）；否则会通过 npx 运行最新的 2.x 版本。

链接

• GitHub： https://github.com/aikarjal/wilmai
• 网站： https://wilm.ai