AvatarTHU

简体中文 · English

把网络学堂的课程资料、作业处理和本人审阅串起来的本地课程助手。

Go 后台 + Electron 桌面 App。 工作台、报告编辑和菜单栏属于同一个 App，点击菜单栏直接打开工作台。同步、10 分钟保活和作业执行仍由独立的 Go 进程负责；关闭窗口或退出 App 不会停止后台。完整发布包已包含桌面运行组件，用户无需单独安装 Python、Node.js 或 Go。

下载最新版本 · 反馈问题 · 来源与许可证

从零开始安装 · 复制给 Agent 自动配置

macOS 菜单栏监控

下图使用虚构的演示作业与复审记录，不代表真实作业完成或模型复审结果。卡片是程序生成的 JSON 的本地渲染预览，云文档是实际飞书正文截图。截图仅保留产品内容，不包含姓名、头像、学号、账号、私人链接或真实课程资料。详见截图说明。

查看当前版本与复审状态，打开完整文档，填写修改意见；由本人决定是否提交。

作业描述、编号要求和结果表分节呈现，先看需要做什么，再看这一版做出了什么。

产物使用原生附件，可以直接预览或下载；文档末尾保留每轮复审的结论、具体评论和待核对项。

首次使用按下面六步完成。不需要克隆仓库或安装 Go、Python。 需要本人的网络学堂账号，以及按分工选用并已登录的 Claude Code 或 Codex CLI；首次网络学堂登录需要 Chrome，Windows 也支持 Edge。飞书可选，不影响本地工作流。也可以直接使用下方的 Agent 配置提示词。

打开 Releases，选择最新可用版本并展开 Assets；目前提供 Alpha 预发布版本。

macOS / Linux 可用 uname -m 查看架构；Windows 可在“设置 → 系统 → 系统信息”查看系统类型。下载同一版本的 SHA256SUMS，用 shasum -a 256 文件名（macOS）、sha256sum 文件名（Linux）或 Get-FileHash 文件名 -Algorithm SHA256（PowerShell）与其中对应文件的值核对，然后解压。

macOS 发布包中的 AvatarTHU.app 包含桌面工作台和菜单栏，请保留在 avatarthu 同一目录，初始化会一起安装。Windows/Linux 同样保留 AvatarTHU/ 目录。用户不需要另装桌面运行环境。

在解压目录打开终端。macOS / Linux：

chmod +x avatarthu
./avatarthu init --no-login --no-start

Windows PowerShell：

.\avatarthu.exe init --no-login --no-start

初始化把程序安装到用户目录并配置命令入口，随后在新终端中直接使用 avatarthu。Windows 若新终端尚未刷新用户 PATH，可以重新登录系统；安装命令打印的完整路径也可以直接使用。macOS 首次打开下载程序时若被系统拦截，可在“系统设置 → 隐私与安全性”允许打开。当前预发布二进制尚未做 Apple 公证或 Windows 代码签名。

新开终端后检查：

avatarthu --version

这一步只安装和初始化。直接运行不带参数的 init 会登录并启动后台，适合工具与配置已就绪的使用者。

主写和复审分别选择 harness，选项均为 Claude Code 或 Codex CLI。只有选中的工具需要安装和登录；两个角色都选 Claude 时只需要 Claude，都选 Codex 时只需要 Codex。先用 avatarthu configure --writer claude --reviewer codex 保存分工（按自己的选择调整），再检查工具。已有可用安装可直接复用；缺少时运行 avatarthu tools 查看安装方法，也可参照后面的工具说明。运行所选 CLI 完成登录后退出交互会话，再检查：

avatarthu tools
avatarthu doctor

预期标为“当前分工需要”的 CLI 都显示“可启动，登录检查通过”。这不代表已验证实时额度或完成了作业；实际写作与复审会使用你自己的 CLI 账号和额度。工具未就绪时仍可只同步材料，先不执行第 6 步。

avatarthu configure --writer claude --reviewer codex --poll-interval 12h --max-review-rounds 3
avatarthu login thu
avatarthu keepalive run

这里选择 Claude 主写、Codex 复审；分别修改 --writer 和 --reviewer 即可，两者都支持 claude、codex，也可以选同一个 harness。12h 可换成 30m、6h 或 1d；保活固定每 10 分钟。两边沿用各自默认模型。

login thu 在 macOS 优先复用 Chrome 中已有的网络学堂登录；不可用时打开 AvatarTHU 自己的浏览器窗口，由本人完成 SSO / 双因素认证。Windows 使用 Chrome 或 Edge。不依赖 Selenium、ChromeDriver 或外部 AutoThu 程序。

keepalive run 返回的 state 应为 valid，表示学校会话可用。

只在本地使用： 全新安装默认关闭飞书，直接执行下方同步命令即可。已有配置需要关闭飞书时，运行 avatarthu notifications off。

需要飞书卡片和云文档： 先执行以下命令，按引导完成应用配置和本人授权。缺少 Lark CLI 时可通过本机 npm 安装；未准备 Node.js/npm 的使用者也可先使用纯本地模式。

avatarthu login lark --no-start

此处的 --no-start 用于先完成配置；不带它会直接启动后台。随后执行首次同步：

avatarthu run --sync-only
avatarthu status

预期显示“同步完成”，课程材料出现在 ~/.avatarthu/courses/，发现的待交作业显示为 queued。没有待交作业时列表为空也是正常的。这一步会下载材料，不会启动主写或复审；启用飞书时会推送未读公告，并在保存成功回执后标为已读。

avatarthu service start
avatarthu status
avatarthu keepalive status

后台会开始处理已发现的待交作业，不需要等 12 小时；12 小时是后续课程扫描间隔。首次使用会处理当前扫描发现的全部符合条件的待交作业。若只想先试一份，暂不启动后台，用 avatarthu run --task 作业编号 在前台处理；编号可从 status 获取。

初次启动后再次运行 status：调度进程应为 running，网络学堂应为 valid；如启用飞书，actions、messages 连接应为 ready。复审通过后作业进入 awaiting，可从 status 打开本地审阅页，或在飞书收到卡片并打开云文档。需要本人补充时会显示 needs_student，执行失败时显示 failed 及原因。没有新作业时不会凭空生成审阅卡片。

看到后台运行后可以关闭终端，也可以退出负责安装的 Agent。系统服务会在用户登录后自动启动；电脑休眠期间暂停，唤醒后补查。只有本人对当前版本的卡片确认提交才会上传作业；本地模式需本人在学校网页提交。

网络学堂每 10 分钟保活，同时访问网页入口和课程接口；临时连接失败会在 1 分钟后重试。会话失效时，后台会尝试用专用浏览器中已有的统一登录状态恢复；若学校要求重新输入密码或双因素认证，仍需本人完成。登录窗口会正常退出以保存浏览器状态，后台不会填写密码或验证码。

把下面整段复制给能操作本机终端的 Agent，例如 Claude Code 或 Codex。代码块右上角可一键复制；可先修改下面的偏好。Agent 可以完成下载安装、检查、配置和后台启动，学校登录、扫码、双因素认证及系统授权仍由你本人完成。

请在这台电脑上安装并配置 AvatarTHU，实际执行配置，不要只给教程。
项目：https://github.com/Sskift/AvatarTHU
先阅读仓库当前 README.md（英文可读 README.en.md），以实际版本的命令和帮助为准。

我的偏好（仅首次安装时作为默认；已有配置先保留）：
- 主写 harness：claude（可选 claude / codex）
- 复审 harness：codex（可选 claude / codex，可以与主写相同）
- 课程扫描：12h；每版最多复审 3 轮；保活使用内置 10 分钟间隔
- 飞书：关闭（可改为开启，向我本人发送卡片和云文档）

请按顺序完成：
1. 检查操作系统、CPU 架构、已有 avatarthu、Claude Code、Codex CLI、浏览器和可选 Lark CLI。保留已有数据、登录和默认模型，不覆盖已有作业或账号配置；已有安装只补齐缺项。若已有后台在运行，报告状态并跳过首次安装、同步与启动。
2. 如未安装 AvatarTHU，从本项目 GitHub Releases 选择最新可用的非草稿版本，包括预发布版。选择匹配系统与架构的压缩包，用同版本 SHA256SUMS 校验后解压。不要依赖 /releases/latest 一定存在，不要从第三方下载，也不要为运行 AvatarTHU 安装 Python、Go 或克隆源码编译。
3. 使用解压后的程序执行 init --no-login --no-start。macOS 保留同目录的 AvatarTHU.app，让初始化一起安装菜单栏组件。检查 avatarthu --version；当前终端 PATH 未刷新时使用安装输出的完整路径继续。数据统一通过 ~/.avatarthu 访问，Windows 使用 %USERPROFILE%\.avatarthu；不要放进仓库。
4. 运行 avatarthu tools。先按我选择的主写和复审 harness 保存配置；已有配置保留，除非我明确要求更改。只安装分工需要的 Claude Code 或 Codex CLI。引导我在所选 CLI 中完成登录，再运行 avatarthu doctor；未选用的工具缺失不应阻止配置完成。沿用各 CLI 默认模型，不修改或比较模型。不要把工具安装成功说成作业已经验证正确。
5. 全新安装按上述偏好执行 avatarthu configure --writer claude --reviewer codex --poll-interval 12h --max-review-rounds 3（若我修改了偏好，相应调整参数）；已有配置保留原分工和间隔，除非我明确要求更改。运行 avatarthu login thu，再运行 avatarthu keepalive run，确认 state=valid。密码、验证码和扫码由我在官方登录界面完成，不要要求我把凭据贴进聊天。
6. 若选择飞书，执行 avatarthu login lark --no-start，复用现有登录或引导我完成应用配置与授权；缺少可选依赖时明确说明。若选择本地模式，全新安装保持飞书关闭；不要擅自修改已有飞书绑定。
7. 后台尚未运行时，执行 avatarthu run --sync-only，再用 avatarthu status 检查课程和作业列表。此步骤不启动写作或复审；启用飞书会推送未读公告并在成功后标已读。不要做真实作业提交测试。
8. 所选模型 CLI 和学校登录就绪后，执行 avatarthu service start 并检查 avatarthu status、avatarthu keepalive status。确认调度进程 running、学校会话 valid；选择飞书时还应检查 actions/messages 是否 ready。macOS 还用 avatarthu menubar status 检查菜单栏，必要时运行 avatarthu menubar start。后台将处理已发现的待交作业并使用我的 CLI 额度；以后按设定间隔扫描，无需负责安装的 Agent 一直在线。
9. 汇报实际版本、安装和数据路径、主写/复审分工、扫描/保活间隔、飞书是否启用、后台状态、已有审阅入口及停止命令 avatarthu service stop。任何步骤受阻，都说明具体原因和下一条操作，不把未完成项说成已完成；缺少工具时可停在仅同步阶段。

提交作业必须等待我本人对当前版本的卡片操作；不要点击提交按钮或模拟回调。保留每轮独立复审意见，不用虚构结果展示配置成功。不要输出 Cookie、token、应用密钥或个人课程内容。

运行 avatarthu tools 可查看安装方式，avatarthu doctor 显示两个执行器的路径、版本、登录及所需参数，但只有当前分工需要的工具会影响检查是否通过。找不到程序、未登录、额度限制、网络问题、权限不足、版本不兼容和默认配置不可用会分别给出说明。

如果已有 Node.js/npm，可安装两种 CLI：

npm install -g @anthropic-ai/claude-code @openai/codex
claude
codex
avatarthu doctor

也可以使用 Claude Code 原生安装 和 Codex 官方安装方式。AvatarTHU 不强制安装 Node.js；只有选择 npm 安装外部 CLI 时才需要。

avatarthu configure --poll-interval 12h
avatarthu service start
avatarthu status
avatarthu keepalive status

1. 网络学堂保活固定每 10 分钟。 验证课程接口，保存服务端更新的 Cookie；可复用本项目浏览器配置中的有效 SSO 会话。需要重新认证时明确提示 avatarthu login thu。
2. 课程扫描默认每 12 小时。 支持 30m、6h、12h、1d 等设置，最低一分钟。同步失败后 15 分钟重试。
3. 本人修改意见每分钟检查。 不需要等到下一轮课程扫描；作业运行期间，同一个 Go 进程继续保活。
4. 休眠期间无法运行。 电脑唤醒后按实际时间补查；macOS 由 LaunchAgent、Windows 由当前用户任务计划程序负责启动与恢复。Windows 不需要管理员服务或保存系统密码；需保持用户已登录。Linux 提供 systemd 用户服务。

service start 不重复启动已运行的进程。service stop 停止调度、保活和飞书监听；保留所有数据。avatarthu daemon 可以直接在前台运行。

可以让另一台常开电脑运行 Go 保活进程，本机仍负责 App、课程同步和作业。两台电脑安装相同版本的原生程序；先确认本机能够通过已有 SSH 配置免交互连接远端，且已验证并保存其主机密钥。

在常开电脑上配置并启动：

avatarthu configure --keepalive-only
avatarthu service start

在本机设置远端 SSH 主机和原生程序路径，然后立即检查：

avatarthu configure --keepalive-host home --keepalive-binary C:/Users/skift/.avatarthu/bin/avatarthu.exe
avatarthu keepalive run

程序路径不能包含空格或 shell 字符。远端 Windows 数据保存在 %USERPROFILE%\.avatarthu，任务计划程序使用当前已登录用户，无需保存 Windows 密码。独立模式不启动课程扫描、作业执行、飞书监听或工作台。也可用 avatarthu daemon --keepalive-only 前台运行。

远端每 10 分钟验证网页入口和课程接口并保存更新后的会话。本机在保活或课程访问前按间隔通过 SSH 获取最新 Cookie；本机睡眠或关机不影响远端。传输走 SSH，不另开网络监听端口。第一次运行时，如果远端尚未登录，会验证并接收本机现有会话；普通同步不会用本机旧会话覆盖远端的有效会话。

需要本人认证时，仍在本机运行 avatarthu login thu。登录成功后自动把新会话交给远端；如果远端暂不可达，同步请求会保存在本机，连接恢复后重试。远端不可达时，本机继续尝试本地保活并在状态中记录 remote_error。学校强制重新认证仍需本人完成；常开保活不能保证永久免登录。

avatarthu keepalive status 的 source 为 ssh:home 时表示最近一次使用了远端会话。关闭远端保活使用 avatarthu configure --keepalive-host ''；远端用 avatarthu service stop 停止。更改独立模式后需重启对应后台进程。

完整发布包同时提供 Go 命令和 Electron App。保留解压目录中的 AvatarTHU.app（macOS）或 AvatarTHU/（Windows/Linux），运行 ./avatarthu init --no-login --no-start 安装；已有课程、登录和作业记录保留。macOS 的 Electron Framework 链接与可执行权限在打包和安装时保持原样。

avatarthu app 打开桌面工作台。macOS 左键点击菜单栏校徽显示同一个窗口，右键显示快捷菜单；待审阅数量仍显示在菜单栏。快捷菜单中的作业直达详情，设置直达 App 内的设置页面。启动第二个实例只激活已有窗口。

课程、附件、PDF 预览、报告编辑和产物都在 App 中查看。界面使用内部 avatarthu://workspace 地址，访问后台的凭证只保留在主进程中；普通工作台操作不打开外部浏览器。网络学堂登录和明确点击的飞书外部链接仍使用系统浏览器。

菜单栏和窗口共用最新状态。App 监听本机状态文件的原子更新并主动通知界面，唤回窗口、系统唤醒和操作完成后立即校准；每 5 秒的本机检查用于补漏，不增加学校轮询或模型请求。状态刷新保留正在输入的设置、报告草稿和文件筛选。界面资源随 App 打包，更新界面可以单独重启 App，不必中断 Go 后台正在执行的作业。

顶部只保留“同步课程”：点击后立即连接网络学堂，同步课程、课件、公告和作业，完成后自动更新界面。本机状态自动刷新。课程同步在 Go 后台的独立循环运行，不等待主写、复审或局部编辑；重复点击合并到同一次同步。运行中作业的输入快照保持不变，新的材料和远端关闭状态会先持久保存，在该作业释放锁后应用，其他课程与作业正常更新。

关闭窗口会隐藏到菜单栏；退出 App 仅退出界面。课程同步和作业任务继续由 Go 后台运行。macOS 登录时可自动启动菜单栏；Windows App 维护自己的登录启动项。设置页提供后台启停、CLI 检查、网络学堂登录、保活检查和失败任务恢复。停止菜单栏和停止后台是独立操作。

avatarthu menubar start|stop|status 保留兼容。旧的 avatarthu web 现在也打开 App；avatarthu edit 作业编号 直接进入 App 内的报告编辑器。--no-open 仅用于旧入口与诊断兼容。

# Claude 主写，Codex 独立复审
avatarthu configure --writer claude --reviewer codex

# 也可以分别选用相同的 harness；复审仍是全新会话
avatarthu configure --writer codex --reviewer codex
avatarthu configure --writer claude --reviewer claude

# 只更换一个角色，保留另一个角色
avatarthu configure --reviewer claude

# 每版最多自动复审 3 轮；0 表示不限
avatarthu configure --max-review-rounds 3

四种组合都支持。在 App 设置中分别选择主写和复审。新配置从下一版作业生效，当前版本及中断恢复继续使用该版本保存的分工；旧的 --mode claude-codex / --mode codex-claude 命令和配置仍兼容。未被当前配置或运行中版本选用的 CLI 不阻止处理。

每个阶段使用新进程、新会话、新工作目录；两边分别使用自己的默认模型配置。AvatarTHU 不指定、比较或约束模型。

复审者只收到原始作业、课件和当前候选文件，不传主写对话、自查记录、之前的修改意见或复审结论，并关闭该次会话的记忆、额外规则发现和外部工具集成。它独立读取题目、检查答案和产物，必要时自行复算或运行。这里实现的是输入与会话隔离；本机 CLI 仍受其自身权限与执行环境约束。

复审不通过时，把具体评论交给主写，在新会话中修改后再复审。每轮完成的评论和检查记录都持久保存，即使中途退出也不会丢掉已完成的复审。达到轮数上限仍未通过时交给本人处理，不呈现为可直接提交。

如果主写明确缺少必须由本人提供的录音、实测数据或现场条件，系统在完成一次独立复审后暂停为 needs_student，由 status 显示待补事项。补齐材料并提出修改后，新版本把上次未通过的意见交给主写继续处理；复审者仍只读取原题和本版产物。代码或分析中可自行修复的问题继续按原有流程修改。

本人确认无需提交的作业，可运行 avatarthu ignore 作业编号 --reason "无需补交"。作业标记为已忽略，不再处理或刷新提醒，后续材料同步也不会重新排队；历史产物、复审和卡片记录保留。正在处理的作业需要等当前处理结束，已提交或提交结果待确认的作业不能改为忽略。

也可在工作台的作业详情点击 忽略作业，按需填写原因。课程作业列表默认显示未忽略的作业，切换到 已忽略 可查看记录并点击 恢复作业；命令行使用 avatarthu restore 作业编号。恢复后沿用忽略前的状态；如果忽略期间材料已变化，则排队重新核对，历史产物和卡片回执保留。

复审会区分产物问题与环境限制。沙箱无法打开图形窗口等情况单独记录，不当成程序损坏反复要求重写；复审结合源码、独立计算和实际运行截图判断。关键行为缺少足够证据时仍不会批准。

主写与复审共享同一份交付风格要求：报告简明，实验按“做了什么—观察到什么—结论”展开；运行命令集中在短 README，代码只保留必要注释，流程记录与修改历史单独保存。没有指定模板时默认宋体正文、黑体标题、Times New Roman 英文数字和三线表，不加页眉页脚；字体替代如实记录，PDF 渲染检查。提交仅含题目要求与运行必需的文件，不额外加入 AI 工具声明或自我评价；题目要求的披露仍须如实填写。精简不能删掉必答内容、原始实验证据或必要依赖，也没有统一页数要求。这些规则每次自动传给两个角色，不依赖历史会话或手工重复提醒。

主写自查由系统单独保存和展示，不得再次放进交付下载件。复审启动前会检查候选 ZIP 中是否包含保留文件 review.md，防止把自评藏在复核包中传给复审者；发现时保留现场并阻止启动复审。

主写和复审进程都设置 AVATARTHU_HEADLESS=1，后台只运行算法及命令行检查，不创建 Tkinter/Cocoa 窗口。需要验证界面事件时，先替换 Tkinter 模块并使用假控件检查状态；Mock 检查不算真实窗口验证。作业应把 --test 与 GUI 入口分开，在该环境变量下直接阻止 GUI 启动。已有真实截图可以复用，缺少的界面验证如实记录。

交叉复审能发现遗漏和错误，但不等于数学、实验或程序正确性的保证。最终审阅和提交决定始终由本人作出。

avatarthu login lark
avatarthu notifications off
avatarthu notifications on

飞书登录会复用本地 Lark CLI 的有效登录态；没有配置时引导创建应用与授权。未安装 Lark CLI 时，login lark 可通过本机 npm 安装到 AvatarTHU 的工具目录。不同飞书账号不能直接接管已有作业的确认权限。

1. 未读公告先归档、发给本人，成功送达回执落盘后才标已读。标记失败只重试标记，避免重复发消息。不开飞书时保持未读。
2. 有待交作业时下载题目附件、描述和课件，在该作业目录内完成主写与复审。
3. 会话里只发审阅卡片。每份作业只使用一份云文档，修改后更新同一个链接，全部产物嵌在其中；历次独立复审仍保留在文末。文档固定五部分：作业描述、完成情况与关键结果、完整产物、审阅与操作、历次独立复审。支持有序列表、公式、表格和实际结果图；报告通过原生 PDF / Office 附件预览，保留原始排版。
4. 可以在文档批注后点击“按文档批注修改”，也可以直接在卡片写意见、回复当前卡片，或在本地使用 avatarthu revise 作业编号 --feedback "修改意见"。
5. 只有本人当前版本卡片上的提交操作才会上传。版本、卡片消息、随机凭据和本地文件哈希必须匹配，并再次核对学校端要求、附件和截止时间。修改后旧卡片失效。
6. 提交状态先落盘再请求学校接口。超时、断连等导致结果未知时，不自动重试上传，由本人去网络学堂核对。
7. 从第二版起，文档前部显示本版改动：修改意见的处理说明、仍未解决的事项、上版审阅入口和产物附件，以及真实文件变化。文本、代码和 ZIP 包内文件可以逐行对照；PDF、Office 等保留前后版本文件入口。修改说明标为主写记录，独立复审者仍只收到原题与当前候选产物。缺少或已改变的历史文件会明确提示，不虚构差异。

纯本地模式会生成同样分节的 HTML 审阅页，用 avatarthu status 查看路径；提交需本人在学校网页操作。启用飞书后可把现有版本发布为云文档与卡片，无需重做作业。

运行 avatarthu app，或点击菜单栏校徽，直接进入桌面工作台。界面通过 App 内部连接访问 Go 后台，课程与文件保持原来的本机存储位置。

1. 总览： 查看课程、待审阅作业、处理进度和网络学堂、飞书、Claude、Codex 的状态。
2. 课程： 按学期与课程查找作业、课件、附件和公告。上传补充资料到课程的 courseware/user/；后续扫描会将材料变化纳入作业处理。
3. 文件： 按课程逐层浏览目录，每次只显示当前层级；作业按 submission/、submission.zip、workspace/、presentation/ 组织，历史版本留在展示目录下。顶部路径可逐级返回，搜索只筛选当前目录。预览 PDF、图片、文本、HTML 和 ZIP，随时下载；自己上传的补充资料可以重命名或移到本机回收目录 data/workspace-trash/。旧作业按相同层级展示，保留原文件和下载链接。
4. 产物： 按作业列出交付入口，进入作业后查看当前与历史交付、独立复审意见，以及编辑报告。进入报告编辑页可多段提建议、直接修改正文、提交定稿并同步其他产物。正式提交仍通过当前版本的飞书卡片确认。
5. 设置与状态： 分别选择主写和复审 harness，设置课程同步间隔，查看最近同步结果。顶部“同步课程”立即触发独立同步；已有任务继续按原分工执行，保活保持每 10 分钟一次。

App 会启动已安装的后台，并在重启后重新连接。原来的本机书签入口继续兼容；日常使用从 App 或菜单栏进入，跨设备仍使用飞书。

运行 avatarthu edit 作业编号，或在 App 的作业详情中进入报告编辑。编辑器与工作台使用同一窗口，保存和 Agent 操作仍由 Go 后台处理；主写、复审和真实提交的约束保持不变。

App 内的编辑页会在后台恢复后自动重连。原有本机编辑入口和草稿继续兼容，日常使用不需要复制地址或访问令牌。若后台端口被其他程序占用，App 会显示连接异常，课程扫描和保活仍独立运行。

1. 自己改字。 点击 HTML 正文中的段落，在侧栏直接修改，预览与草稿自动保存。Markdown 页签支持精确编辑，修改对照展示原文和草稿；可以下载 Markdown 或带截图的源文件包。
2. 定点调用 Agent。 可选择一段，或点击“多段选择”勾选若干段落；支持不相邻段落、Shift 连选、⌘ / Ctrl 点击增减，以及拖选跨段文字。侧栏列出完整选区，写一条意见即可让同一个 Agent 一起修改。相邻段落可合并改写，不相邻片段分别展示原文与建议，未选内容保留。也可在段落输入框或 Markdown 中精确圈定文字。当前主写 harness 使用默认模型、新会话返回建议；你选择“采用全部修改”或“保留原文”后才写入草稿。若选区已被手动改动，会保留现稿并提示重新选择。
3. 提交成品。 按钮把提交当时的正文和图片交给主写。它以定稿措辞为准，同步 PDF、HTML、报告源文件包、代码包内的报告和其他受影响文件，然后进行独立复审；未通过则带意见继续修改。页面显示处理进度，结果仍更新到同一个飞书文档。
4. 查看新版。 完成后载入新版正文，检查相关产物。载入前会备份旧草稿；提交后继续输入的内容留作后续修改，不影响已接收的定稿。提交到网络学堂仍由你在最新飞书卡片上确认。

编辑页的 “HTML 审阅稿” 可打开独立阅读页，“下载 HTML” 导出单个文件，正文、排版和截图都在其中，离线也能看。也可运行 avatarthu edit --export-html 作业编号 导出当前草稿。新生成的 report.md 会自动转换为 report.html，与其他产物一起送交独立复审和发布。

草稿、图片、请求回执和备份保存在该作业的 editor/ 目录。原来冻结的产物和卡片回执继续保留。局部修改与主写、复审共用现有工作队列；后台重启后会用新会话恢复中断的局部修改，历次执行日志分别保留。页面顶部显示排队、执行时长、重试和完成状态。局部修改每次最多执行 10 分钟（配置的阶段超时更短时采用该值）；网络或超时失败会在一分钟后重新排队，连续失败 3 次后停止。登录、额度等问题直接显示处理方法，可点“重新尝试”，也可用 avatarthu retry --tool codex 或 claude 恢复。局部编辑会核对当前交付文件；需要改代码时会在建议中说明，采用文字后通过“提交成品”同步相关产物。多页面保存冲突时保留当前文字并提示下载备份，再刷新载入已保存的草稿。

后续生成的报告同时交付 report.md 和 report-source.zip（Markdown 与相对路径图片），每版都进入同一个审阅文档。旧报告如果没有可编辑源文件，可以在 Markdown 页签粘贴正文。本地编辑页只监听本机，飞书继续提供远程审阅与通知入口。

提交包只压缩一层。主写用 submission_files 明确选择题目要求的最小完整文件集，展示、编辑下载件单独保存。每份作业根目录只保留 submission/、submission.zip、workspace/、presentation/ 四项；所有新建文件与中间目录均使用英文 ASCII 名称。

avatarthu files 作业编号 校验并显示顶层提交文件夹，avatarthu export 作业编号 返回对应 ZIP。已有副本被修改时会报错并保留。指定独立下载件的导出位于 workspace/exports/rN/。这两个命令都不上传作业或修改已有卡片。

App 的“设置与状态”和 avatarthu status 会显示飞书连接失败的原因、连续失败次数和下次重试时间。应用连接冲突、授权、权限或 CLI 版本问题每 15 分钟重试；临时断网按 1、2、4、8、15 分钟逐步延长间隔。修复后可在设置中点“重连飞书”，或运行 avatarthu reconnect lark。请求重连不会提前把红灯变绿；只有监听真正就绪才清除异常。

同一飞书应用被其他设备或程序监听时，需要停止原监听，或为 AvatarTHU 选择另一个应用的 Lark CLI profile：

lark-cli profile list
avatarthu login lark --profile my-avatar

这里填写已经配置好的 profile 名称；应用密钥交给 Lark CLI 管理。AvatarTHU 固定使用选中的配置和该配置中登录的本人身份，不改变 Lark CLI 的全局默认配置。切换应用后，可以用 avatarthu resend 作业编号 补发当前版本卡片，附上最新审阅文档；旧卡片的提交入口随之失效，历史回执仍保留。补发失败后再次运行会沿用同一次发送请求，避免重复消息。

后台每 15 秒更新本地心跳；超过 90 秒未更新，或当前调度阶段超过期限，菜单栏会提示异常。模型执行按该阶段的超时设置判断，不会把正常的长时间主写／复审当成失联。异常提示不会自动重启后台或重试作业提交。网络学堂保活仍是同一 Go 进程每 10 分钟一次。

登录失效、额度或频率限制、CLI 版本不兼容、权限或默认配置问题会暂停该工具的自动重试，避免每 15 分钟重复失败。网络、超时等暂时性错误仍在 15 分钟后重试。修复账号或环境后，可在 App 设置中点击“恢复 Codex 任务”或“恢复 Claude 任务”，或运行：

avatarthu retry --tool claude
avatarthu retry --tool codex

恢复操作只将失败的主写／复审作业重新排队，后台从已完成阶段继续；不会提交作业，也不会重试提交结果未知的任务。它沿用该版本已经保存的主写／复审分工。学校保活、公告同步和飞书回调继续运行。

统一入口为 ~/.avatarthu，Windows 对应 %USERPROFILE%\.avatarthu。macOS 新安装将数据实体放在 ~/.local/share/avatarthu，以 ~/.avatarthu 作为符号链接。已有的历史数据根继续使用，不强制迁移；courses/ 也可以是指向历史 data/courses/ 的入口。完整约定见目录规范。

~/.avatarthu/
├── bin/avatarthu                  # 原生可执行文件
├── apps/AvatarTHU.app             # Electron 桌面 App 与菜单栏
├── config.json                   # 分工、扫描频率、CLI 路径
├── session.json                  # 本人网络学堂会话
├── browser-profile/              # 本项目的浏览器登录配置
├── courses/
│   └── semester/course-id/
│       ├── course.json
│       ├── notices/              # 公告原文和元数据
│       ├── courseware/           # 增量下载课件
│       └── homework/assignment-id/
│           ├── submission/       # Files to submit
│           ├── submission.zip    # Matching single-layer ZIP
│           ├── workspace/        # Inputs, runs, drafts, experiments, state
│           └── presentation/     # Display artifacts, frozen versions, reviews
├── data/                         # 全局任务索引、调度与送达回执
├── logs/                         # 后台和执行错误日志
└── tools/                        # 可选安装的 Lark CLI

旧路径、文件字节和回执保持兼容。整理时旧现场收进 workspace/legacy/，展示资料收进 presentation/；旧位置保留兼容入口，新作业根目录只保留四项。详见目录规范。所有课程和运行数据均保存在 Git 外。

avatarthu run                     # 立即扫描并处理
avatarthu run --sync-only         # 只同步、下载及推送公告
avatarthu run --task 作业编号      # 同步后只处理指定作业
avatarthu keepalive run           # 立即保活并尝试恢复登录
avatarthu app                     # 打开桌面工作台
avatarthu edit                    # 编辑报告、局部调用 Agent、提交定稿
avatarthu files 作业编号          # 校验冻结文件及提交目录，打印路径
avatarthu export 作业编号         # 返回当前 submission.zip 路径
avatarthu status                  # 服务、登录、作业和审阅入口
avatarthu service stop            # 停止后台，保留数据
avatarthu menubar status          # macOS 菜单栏状态
avatarthu uninstall               # 停用后台与菜单栏，仍保留数据

开发桌面版还需要 Node.js 22.12+。先运行 npm ci --prefix desktop，使用 npm test --prefix desktop 和 npm run test:app --prefix desktop 验证桌面交互；go run ./cmd/release 构建完整发布包，--cli-only 仅构建 Go 命令。旧 Swift 菜单栏源文件保留作历史参考，不再进入新发布包。

开发者使用 Go 1.27.1 和 Node.js 22.12+。后台使用 CGO_ENABLED=0 构建；完整发布包包含 Electron App、Go 后台及第三方许可证。使用者无需安装开发工具。

go test ./...
go vet ./...
CGO_ENABLED=0 go build -trimpath -o build/avatarthu ./cmd/avatarthu
go run ./cmd/release --os windows --arch amd64 --out dist

CI 在 macOS、Windows 和 Linux 上检查核心工作流与全新安装。发布支持 macOS arm64 / amd64、Windows amd64 / arm64、Linux amd64 / arm64，附带 SHA256SUMS 与第三方许可证。

当前为 Alpha，适合愿意自行审阅作业、反馈问题的使用者试用。需要长期跨账号验证学校端变化、不同课程材料与各平台浏览器认证。仓库与 Release 已公开，欢迎试用和提交 Issue。

网络学堂相关接口和 macOS 会话导入改写自 AutoThu 及我们的登录、保活贡献，已经内置在本项目中。来源与许可证见 THIRD_PARTY.md。