跳转至

OneTHU 独立 CLI / SDK 实施计划

目标： CLI 独立安装、构建、登录和运行学校服务及无界面插件；桌面端复用 SDK 并增加 GUI，MCP 复用相同服务入口。

架构： @onethu/core 与 @onethu/info-lib 继续承担学校协议。新增 @onethu/sdk 承担会话宿主、结构化服务、执行策略、资料归档与插件生命周期；@onethu/cli 提供终端与 MCP 协议。桌面应用注入原生网络、文件和确认界面，独立运行时注入 Node 实现。

技术： TypeScript / Node.js 20.18.1+、现有学校 SDK、ESM 分发、跨平台文件存储与子进程。默认单独运行；--desktop 显式连接现有桌面服务。

决策与权衡

  1. 产品命令仍叫 OneTHU CLI；嵌入包叫 OneTHU SDK；MCP 为工具协议，避免把协议名当成全部产品能力。
  2. 从现有业务代码抽出可注入的运行环境，避免维护第二套学校解析或重新启用已退役登录实现。Node 登录复用最新 InfoHelper 认证链。
  3. 独立 CLI 使用独立数据目录及稳定设备指纹，不读取桌面明文秘密。账号及 Cookie 只写本机私有目录，进程锁避免并发覆盖。桌面连接为明确模式，自动回退不得切换到另一个账户。
  4. 自动执行是设备本地授权，桌面开关默认关闭，独立 CLI 可显式配置。启用后省去每次确认；权限、账号、调用期限与结果不明时禁止自动重放仍有效。MCP 及插件不能自行授予此权限。
  5. 插件采用既有 JS / Rust manifest 和命令协议。安装时静态检查、默认禁用，运行本地受信代码。纯界面接口以明确 capability 返回，安装不会执行代码读取 manifest。
  6. 可用能力目录公布参数和宿主支持情况。GUI 专属能力清楚标注；不会把占位实现公布成可用服务。

实施与验证

1. Node 会话

  • 新增 packages/sdk/src/node/、src/auth/ 与 test/auth*。
  • 复用 InfoHelper 的 SM2、稳定指纹与二次验证，提供 restore/login/2fa/logout/status。
  • 验证 Cookie 跳转、持久化与独占锁、退出清理、敏感信息过滤。真实认证提交留给用户，不在测试中发验证码或新增信任设备。

2. 共享服务

  • 将网络学堂完整资料服务迁至 SDK，桌面文件改为注入适配器。
  • 共享目录、参数验证和脱敏；Node 适配学校查询、预约、日历、云盘等无 GUI 能力。
  • 资料下载保持 URL 限制、账号约束、超时、不覆盖文件和哈希验证。
  • 核对上一轮 CLI 用例，并增加无桌面进程的独立测试。

3. 插件

  • 新增 packages/sdk/src/plugins/，支持本地包 inspect/install/list/enable/disable/commands/call/uninstall。
  • JS 子进程与 Rust 既有 JSON-RPC，按 manifest 权限转发 SDK 调用。
  • 校验 ZIP 路径、大小、CRC、符号链接和平台入口；用自建插件验收，记录复杂 GUI 能力边界。

4. 终端与 MCP

  • CLI 默认启动独立 SDK，保留显式桌面连接。
  • 交互式登录从终端读取密码和二次验证码；自动脚本允许 stdin，禁止把密码写在命令参数中。
  • MCP stdio 直接承载 SDK；HTTP 服务仅绑定回环并使用本机凭据，拒绝浏览器跨域访问。
  • 提供 standalone build / pack，安装包包含所需编译产物，离开仓库也能运行。

5. 桌面授权与交付

  • SDK 纯策略模块供桌面和 Node 共用。高级设置新增自动执行本机开关，中英文明确作用范围。
  • 确保云同步、远程命令、插件无法开启该开关；关闭即时撤销尚未提交的请求。
  • 测试、文档、能力对照、独立安装验收及共享记忆更新。

本计划在当前未提交实现上继续，保留已有修改；完成后再按实际验收记录更新状态。

2026-10-25 实施记录

本轮在既有 CLI/MCP、MadModel 与学习资料修复的未提交工作上继续，未切换分支、覆盖用户更改或进行新发布。

已落地

  • packages/sdk：独立 Node 会话/2FA、稳定设备指纹、私有存储与目录锁；直接复用学校协议，注册学习、预约、校园信息、选课、邮箱、CalDAV、云盘、GitLab、外部作业及本地记忆。
  • packages/cli：默认独立运行，--desktop 显式复用图形宿主；登录、只读目录/Schema、命令、归档、stdio MCP；macOS/Windows 安装脚本包含 SDK bundle。
  • 设备自动执行策略：本地开关，默认逐次授权；来源、权限、账号 epoch、调用截止时间在最终提交前校验。MCP/模型/插件不能开启本机开关。
  • 共享任务引擎：interval/daily/once、课程资源变化、DDL、增量下载、通道授权、持久历史、暂停取消、只读有限重试、未知外发不重放。
  • 独立 daemon：私有令牌、随机回环端口、CLI 自动复用、前台与后台运行、当前用户的 LaunchAgent/Windows 计划任务注册命令。
  • 插件：本地目录/ZIP、静态 manifest 审核、默认禁用、JS worker/Rust JSON-RPC、取消与账号检查。运行的是用户批准的本地代码，不承诺 OS 沙箱。
  • 通知与 IM：本机收件箱、飞书、微信 iLink、HTTPS webhook；私聊对象固定绑定、事件去重、指令取消与重连；任务通知使用接收者绑定 ID。
  • 自然语言助手：OpenAI 兼容自填 API、显式工具范围、有限轮次/费用预算、短会话记忆。独立 MadModel 登录及微信扫码未新增，沿用嵌入接口/已有凭据。
  • 桌面：OneGUI 常驻任务列表、课程选择、目录和通知通道、创建/编辑/暂停/运行/历史/本机收件箱；原生下载可中止。OH 内建任务工具在最后接入核查中补齐。
  • 独立分发：CLI 包内嵌运行文件；SDK 单独产出不含 workspace 运行依赖的 tgz 和公开类型；附项目及第三方许可。

设计依据

研究 Hermes 的 cron persistence/execution/delivery 与 OpenClaw 的任务生命周期、持续会话和通知对象绑定。没有复制其源码；调度器和宿主端口在 OneTHU 中实现。确定性的学校检查与模型工具循环分开，检查本身无需模型调用。

实现过程中修复了多项跨模块问题：并发写失败不得释放别人的锁；异步授权等待结束后再次检查 epoch；插件反向调用保留原始账号守卫；断开 HTTP 请求取消执行；daemon 不合规令牌不能使进程退出；SDK 关闭时存储失败仍须释放进程与目录锁；配置持久化失败不能启用自动执行；IM 初始化必须在关闭时排空。

验证原则与边界

使用合成学校响应、本机 HTTP/WebSocket、隔离数据目录和真实子进程；不新增真实信任设备、不提交真实预约、不发真实邮件/IM。独立 runtime 端到端验证和此前桌面伴随 CLI 真实下载记录分别说明。

UI 验收包含真实组件的中英 1440px 与 390/430px 窄窗点击，报告位于 output/cli-task-ui-fixture/QA.md。Windows WebView、ACL、自启动、独立学校真实登录、真实 IM/模型尚待验收。静默时段、登录失效专门去重提醒、所有 GUI 页面迁入 SDK 不包含在本轮完成范围。

最终命令、产物校验和测试数字见 docs/plans/2026-10-25-cli-validation.md。用户指南：packages/cli/README.md / README.en.md；架构：docs/onethu-cli.md / docs/en/onethu-cli.md。