千语使用指南

系统要求

灵动岛需要支持灵动岛的 iPhone。其他符合系统要求的 iPhone 可以使用课程表、普通通知和相应的锁屏实时活动。

下面的安装说明以从源码运行项目为例。若你已经安装了千语，可以直接跳到「第三节：第一次使用」。

获取项目

打开 GitHub 仓库，选择 Code → Download ZIP，解压到本地。也可以用终端克隆：

git clone https://github.com/RealWR1D/QIAN-YU.git
cd QIAN-YU
open "QIAN YU.xcodeproj"

在 Xcode 中打开的是 QIAN YU.xcodeproj，运行方案选择 QIAN YU。

在 Mac 上运行

1. 在 Xcode 顶部的运行设备中选择 My Mac。
2. 按 Command + R 编译并启动。
3. 首次打开后进入设置，按需配置通知和 AI。

以后可以直接打开已编译的 App。在 Xcode 左侧找到 Products 下的应用产物，右键选择 Show in Finder，然后在 Finder 中双击打开。项目源码有变化时，需要重新编译，变化才会进入 App。

在 iPhone 上运行

1. 在 Xcode 的账户设置中登录自己的 Apple 账户。
2. 用数据线连接 iPhone，解锁并按提示信任这台 Mac。
3. 在项目的 Signing & Capabilities 中，为主应用和小组件目标选择自己的签名团队。
4. 如果出现 Bundle Identifier 或 App Group 的签名错误，先检查错误提示。主应用与小组件的共享组必须一致；随意只改其中一个，会影响共享课程数据。
5. 在 Xcode 顶部选择这台 iPhone，按 Command + R。
6. 如果系统要求开发者模式，在 iPhone 的 设置 → 隐私与安全性 → 开发者模式 中开启，按提示重启并确认。Apple 提供了开发者模式官方说明。
7. 如果安装后提示开发者尚未受信任，在 设置 → 通用 → VPN 与设备管理 中按系统提示信任对应的开发者，再打开千语。

建议按下面的推荐顺序完成初始设置：

1. 进入 设置，填写希望千语称呼你的名字。
2. 打开 每日提醒与上课通知，按需授予系统通知权限。
3. 设置 开学第一周起始日期，核对页面显示的当前教学周。
4. 在课程表中手动添加课程，或导入学校提供的 .ics 课表。
5. 点击 发送测试通知，等待约 3 秒，确认通知能够正常弹出。
6. 需要 AI 时，再填写接口、模型和 API Key，点击 测试当前配置。
7. 需要天气问候时，选择自己的常用城市和区。
8. 需要睡眠联动时，完成两项快捷指令自动化，再打开应用内的对应开关。

主要页面包括陪伴、课程表、专注和设置。Mac 使用侧边栏切换，iPhone 使用底部标签切换。

先设置教学周

进入 设置 → 每日提醒与上课通知 → 开学第一周起始日期，填写学校实际的第一教学周起始日期。通常应使用学校规定的第一周周一，不能只凭报到日期推算。

教学周用于判断单双周、指定周次和下一门课，也会影响课程通知、每日推送、小组件及日历同步。这里的「第几周」是学期教学周，不是系统日历中的全年周数。

手动添加课程

在 课程表 的右上角菜单选择 手动添加课程，填写：

• 课程名称：必填，建议与学校课表一致。
• 教室或地点：用于课程展示和通知提示。
• 教师：选填。
• 星期、开始时间、结束时间：结束时间必须晚于开始时间。
• 周数模式：每周、单周或双周，并设置起止教学周。
• 指定具体周次：不规则排课可直接填写，例如 1,2,4,7。
• 提前提醒时间：控制这门课的课前预警时间（如提前 15 分钟）。
• 课程颜色：方便在课表中区分各门课程。

查看、修改与停用

课表可以切换教学周，也可以查看 全学期总表。查看其他周只是改变当前浏览内容，不会把系统通知切换成那一周的日期；查看后可以选择 回到本周。

通过右上角 课程管理 可以搜索课程名称、教师或教室，查看并修改同名课程的不同安排。课程表单中的 启用课程提醒 同时决定课程是否参与有效课程计算。关闭后，这门课会退出下一课、提醒、每日课程统计及日历同步的计算。

.ics 是标准的 iCalendar 日历文件。应先从学校教务课表系统或相关工具导出文件，再交给千语导入。截图或 PDF 无法直接识别导入。

导入步骤

1. 在课程表菜单选择 导入 .ics 日历课表，选择文件。
2. iPhone 也可以在「文件」或附件的分享菜单中选择千语（或 QIAN YU）。
3. 检查导入预览中的名称、星期、时间、地点和周次，勾选需要导入的课程。
4. 选择导入方式，确认后保存。

同名、同星期、同时间，并且教室及教师信息相容的课程可以自动合并。因此重复追加同一份文件通常不会生成一整套重复课程。

在课程表菜单中选择 同步至 Apple 系统日历，根据提示允许日历访问权限。

同步后，打开系统「日历」，会找到专属的 QIAN YU 课表 日历。千语会根据教学周生成实际日期上的课程事件，包含课程时间、地点和说明。

进入 设置 → 每日提醒与上课通知 → 上课提醒与学期教学周：

• 启用课前千语智能通知：按照各门课设置的提前提醒时间，提示课程名、教室和上课时间。
• 启用课后千语收尾关怀：在下课时提醒收拾随身物品、喝水活动，并结合接下来的课程安排给予贴心提示。

系统允许排队的本地通知数量有限。课程较多时，应用优先安排近期通知，并在后续打开应用或系统允许刷新时续排。

入口位于 设置 → 每日提醒与上课通知。全新安装时的默认时间与发送规则如下：

午饭时间如何计算

应用把 开始时间早于 12:00 的课程 判定为上午课程，取其中最后的结束时间：

• 早于 11:00 结束：11:30 提醒。
• 11:00 或之后结束：在下课时间准时提醒。
• 没有上午课程：使用你设定的固定午饭时间（默认 12:00）。

千语不会在后台轮询手机是否睡着，而是通过 iPhone 的「快捷指令」自动化把起床与就寝动作传递给应用。

早晨自动化配置

1. 打开 iPhone 的 快捷指令 → 自动化，新增个人自动化。
2. 触发器选择「睡眠」专注模式的 关闭时。
3. 将自动化设置为 立即运行，关闭「运行前询问」。
4. 添加千语的 睡眠已结束 动作，保存自动化。

就寝自动化配置

1. 新增另一项自动化。
2. 触发器选择「睡眠」专注模式的 开启时。
3. 设置为 立即运行。
4. 添加千语的 准备睡觉 动作并保存。

两项均配置完成后，回到千语的推送设置页，开启 已配置睡眠自动化 开关。

天气设置位于每日推送页面，用于早晨问候。默认常用地点是 深圳市南山区，首次使用建议修改为自己的城市。

手动选择城市和区

1. 在 常用城市 / 区 输入框填写地名（例如「成都市武侯区」）。
2. 点击 查找城市与区。
3. 在搜索结果中点击选择正确的地点，确认保存。

使用当前位置

点击 使用当前位置，授权使用期间定位，应用会单次获取位置并转换为对应城市。天气数据来自 Open-Meteo，预报会提前缓存，无法取得天气时问候会自动省略天气字段，不影响正常问候。

入口位于 设置 → AI 模型驱动（OpenAI 协议兼容）。支持任意遵循 OpenAI Chat Completions 协议的服务商及本地模型。

配置顺序

1. 在 服务商预设 中选择服务商或自定义。
2. 核对并填写 接口地址（例如 https://api.openai.com/v1）。
3. 填写你的 API Key（支持点击眼睛按钮查看或隐藏）。
4. 点击 刷新模型列表 选择模型，或直接手动输入 模型 ID。
5. 点击 测试当前配置，若显示「连接测试通过」即配置成功。

在每日推送页打开 用 AI 生成每日问候。它沿用设置中的 AI 模型，自动为各个时段生成自然关怀文案：

文案通常在打开应用或系统允许后台刷新时提前生成并缓存，通知到点准时弹出，不会临时等待 API 网络响应。

在陪伴页输入文字发送，即可与陈千语聊天。配置 AI 后将基于大模型实时对话；无配置时使用内置语料。

修改角色人设

进入 设置 → 关于应用 → 角色人设：

1. 编辑人设文本，调整性格口吻、称呼偏好与回复习惯。
2. 点击 保存。
3. 从下一条对话开始即可应用全新人设。

打开专注页，选择对应模式与专注时长：

计时基于绝对时间戳计算，应用切到后台或息屏不会中断计时。支持锁屏实时活动与灵动岛展示。

添加课程小组件

长按 iPhone 主屏幕空白处，搜索 千语 或 QIAN YU，添加课程小组件。小组件会展示当前教学周和接下来的课程安排。

实时活动与灵动岛

启动番茄钟后，锁屏与灵动岛会自动激活进度环与剩余时间展示。

Mac 菜单栏常驻

在 Mac 上运行时，菜单栏会显示千语常驻图标，点击可查看下节课倒计时或进行轻量聊天。

欢迎前往 GitHub Issues 提交反馈与功能建议。反馈时建议附带：

• 设备型号与系统版本（例如 iPhone 15 Pro, iOS 17.5 / MacBook Air M2, macOS 14.4）。
• 出问题的具体页面与操作复现步骤。
• 截图或控制台错误日志（请务必遮盖 API Key 及个人隐私信息）。