[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80112":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":8,"language":10,"languages":8,"totalLinesOfCode":8,"stars":11,"forks":12,"watchers":13,"openIssues":13,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":14,"forks30d":14,"starsTrendScore":18,"compositeScore":19,"rankGlobal":8,"rankLanguage":8,"license":8,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":22,"topics":23,"createdAt":8,"pushedAt":8,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":14,"starSnapshotCount":14,"syncStatus":15,"lastSyncTime":27,"discoverSource":28},80112,"sjtu-agent","kuan-er\u002Fsjtu-agent","kuan-er",null,"https:\u002F\u002Fkuan-er.github.io\u002Fsjtu-agent\u002F","Python",65,9,1,0,2,3,10,6,43.5,false,"main",true,[],"2026-06-12 04:01:26","# SJTU Agent\n\n[![Test](https:\u002F\u002Fgithub.com\u002Fkuan-er\u002Fsjtu-agent\u002Factions\u002Fworkflows\u002Ftest.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fkuan-er\u002Fsjtu-agent\u002Factions\u002Fworkflows\u002Ftest.yml)\n\n面向上海交通大学学生的校园助手，提供终端对话、Telegram \u002F 飞书 \u002F 微信 \u002F QQ Bot、提醒守护进程和 MCP Server。\n\nEnglish summary: A deployable Shanghai Jiao Tong University campus assistant with terminal chat, Telegram \u002F Feishu (Lark) \u002F WeChat \u002F QQ bots, reminder daemon, and MCP server.\n\n👉 **[项目展示页](https:\u002F\u002Fkuan-er.github.io\u002Fsjtu-agent)**\n\n如果这个项目对你有帮助，欢迎点一个 ⭐ Star，这对我很有意义！\n\n## 安装\n\nmacOS \u002F Linux:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fkuan-er\u002Fsjtu-agent.git && cd sjtu-agent && bash install.sh\n```\n\nWindows PowerShell:\n\n```powershell\ngit clone https:\u002F\u002Fgithub.com\u002Fkuan-er\u002Fsjtu-agent.git; cd sjtu-agent; powershell -ExecutionPolicy Bypass -File .\\install.ps1\n```\n\n安装脚本会自动完成：创建 `.venv`、安装依赖、安装 Playwright Chromium，然后直接启动 `sjtu-agent setup`。\n\nsetup 向导会先保存大模型 API 配置，然后依次引导保存校园平台凭据、自动创建 Canvas Token、从 Chrome 导入 Cookie，最后在 macOS 上一并安装 launchd 后台服务并**自动打开 Web UI**（`http:\u002F\u002F127.0.0.1:7860`）进行配置。在 setup 过程中可以直接用自然语言回答，也可以输入快捷命令：`status`、`help`、`skip`、`quit`、`open canvas`、`auto canvas`。\n\n## 安装进阶选项\n\n如果只想安装但不立刻进入 setup，或者想跳过 Chromium：\n\n```bash\n# macOS \u002F Linux\nbash install.sh --no-setup\nbash install.sh --skip-playwright\n```\n\n```powershell\n# Windows\n.\\install.ps1 -NoSetup\n.\\install.ps1 -SkipPlaywright\n```\n\n手动安装方式：\n\n```bash\npython3 -m venv .venv\nsource .venv\u002Fbin\u002Factivate  # Windows: .venv\\Scripts\\activate\npip install -U pip\npip install -e .\nsjtu-agent setup\n```\n\n## 配置致远一号 API（推荐）\n\n[致远一号](https:\u002F\u002Fzhiyuan.sjtu.edu.cn) 是上海交通大学官方提供的大模型服务平台，支持 OpenAI 兼容接口，交大师生可免费申请使用。\n\n**接入方式：** 安装完成后直接运行 `sjtu-agent setup`，setup 向导会在第一步引导你输入 API Key 并自动保存，无需手动编辑任何文件。\n\n如需手动配置，在运行时数据目录的 `.env` 文件中填入：\n\n```bash\nZHIYUAN_API_KEY=你的致远一号APIKey\n```\n\nBase URL 默认为 `https:\u002F\u002Fmodels.sjtu.edu.cn\u002Fapi\u002Fv1`，模型默认 `deepseek-chat`（即交大部署的 DeepSeek V3.2），无需额外修改。\n\n可用模型列表：\n\n| 调用名 | 说明 |\n|--------|------|\n| `deepseek-chat` | DeepSeek V3.2（**默认**）|\n| `deepseek-reasoner` | DeepSeek V3.2（推理模式）|\n| `glm-5` | GLM 5.0 |\n| `minimax` \u002F `minimax-m2.5` | MiniMax M2.5 |\n| `qwen3coder` | Qwen3-Coder-30B |\n| `qwen3vl` | Qwen3-VL-32B |\n\n**如何申请致远一号 API Key：**\n\n前往 [https:\u002F\u002Fzhiyuan.sjtu.edu.cn](https:\u002F\u002Fzhiyuan.sjtu.edu.cn)，使用 jAccount 登录后在「API 管理」中创建 Key。\n\n如果使用 DeepSeek 官方或其他 OpenAI 兼容接口，在 Web 配置页选择「自定义」，填入对应的 API Key、Base URL 和模型名即可。Base URL 只填服务根地址，不要填到 `\u002Fchat\u002Fcompletions`。\n\n---\n\n## 常用命令\n\n```bash\nsjtu-agent                # 启动主对话\nsjtu-agent setup          # 运行首次配置向导\nsjtu-agent doctor         # 查看当前配置状态和运行时路径\nsjtu-agent setup-config   # 从浏览器读取 Cookie 并生成 config.json\nsjtu-agent login --aihaoke\nsjtu-agent ddl --canvas-only\nsjtu-agent daily-report --test\nsjtu-agent telegram-bot --test\nsjtu-agent qq-bot --test\nsjtu-agent remind-check --list\nsjtu-agent mcp --http --port 8765\nsjtu-agent add-mcp-server my-tools --transport stdio --command python --arg D:\u002Fpath\u002Fto\u002Fserver.py\nsjtu-agent add-skill my-skill --content-file D:\u002Fpath\u002Fto\u002FSKILL.md\nsjtu-agent install-daemons\n```\n\n也可以直接以模块方式运行：\n\n```bash\npython -m sjtu_agent\n```\n\n几个常用的 setup 变体：\n\n```bash\nsjtu-agent setup\nsjtu-agent setup --yes --skip-cookie-import --skip-launchd\nsjtu-agent setup --yes --write-daemons-only --output-dir \u002Ftmp\u002Fsjtu-agent-launchd\n```\n\n## MCP 与技能扩展\n\nAgent 可将自身工具暴露为 MCP Server，也可加载外部 MCP Server 作为额外工具。外部 MCP Server 配置保存在 `config.json` 的 `mcp_servers` 字段中；已启用的 prompt-only 技能保存在 `skills.enabled` 字段中。\n\n添加自定义 MCP Server：\n\n```bash\nsjtu-agent add-mcp-server my-tools --transport stdio --command python --arg D:\u002Fpath\u002Fto\u002Fserver.py\nsjtu-agent add-mcp-server remote-tools --transport sse --url http:\u002F\u002F127.0.0.1:8765\u002Fsse\n```\n\n也可在对话中让 Agent「添加自定义 MCP Server」。首次对话触发调用仅会提示将信任外部命令或 URL，需用户明确确认后才继续。\n\n添加自定义 prompt-only 技能：\n\n```bash\nsjtu-agent add-skill my-skill --content-file D:\u002Fpath\u002Fto\u002FSKILL.md\nsjtu-agent list-skills\nsjtu-agent manage-skill disable my-skill\n```\n\n也可在对话中让 Agent 添加技能，并提供完整的 `SKILL.md` 内容或本地文件路径。\n\n如需更原生的 Agent 流程，可对 Agent 说「创建一个技能」并描述想要的行为。若需求不够明确，Agent 会追问补充信息；获得名称、触发条件和指令后，Agent 会通过 `create_skill` 创建技能。也可以通过 `list_skills` 和 `manage_skill` 列出、启用、禁用或删除技能。\n\n## macOS 后台服务\n\n在 macOS 上，可以直接用一条命令安装内置 launchd 服务：\n\n```bash\nsjtu-agent install-daemons\n```\n\n默认会把 LaunchAgent plist 写入 `~\u002FLibrary\u002FLaunchAgents`，并自动加载到当前用户会话。安装完成后会**自动在浏览器中打开 Web UI**（`http:\u002F\u002F127.0.0.1:7860`），可以在里面完成所有配置，包括 API Key、平台账号、Telegram Bot Token 等。\n\n- `web`：Web 配置界面，随系统启动，由 launchd 保活\n- `daily-report`：每天 `22:00` 运行一次\n- `remind-check`：每 `60` 秒运行一次\n- `telegram-bot`：登录后启动，并由 launchd 保活\n- `qq-bot`：登录后启动，并由 launchd 保活\n\n常见变体：\n\n```bash\nsjtu-agent install-daemons --write-only\nsjtu-agent install-daemons --services daily-report remind-check\nsjtu-agent install-daemons --daily-report-time 21:30 --remind-interval 120\n```\n\n这些后台服务会使用当前选定的 Python 解释器，以运行时数据目录为工作目录，并把日志写到 `~\u002FLibrary\u002FApplication Support\u002Fsjtu-agent\u002Flogs`。\n\n## Windows 后台服务\n\nWindows 提供两种后端选择：**Task Scheduler**（默认，适合定时任务）和 **psmux**（适合常驻进程）。\n\n### 通用方式（默认 Task Scheduler）\n\n```powershell\nsjtu-agent install-daemons\n```\n\n每天 22:00 日报 + 每 60s 提醒检查 + 登录时启动 Telegram\u002F飞书\u002F微信\u002FQQ Bot + Web UI。\n\n### 用 psmux 管理常驻进程\n\n[psmux](https:\u002F\u002Fgithub.com\u002Fpsmux\u002Fpsmux) 是 Windows 上的 tmux，可以创建后台分离会话来运行常驻 Bot，**不会弹出终端窗口**，启动\u002F停止\u002F检查方便。\n\n```powershell\n# 安装 psmux\nwinget install psmux\n\n# 只用 psmux 启动常驻 Bot（feishu\u002Ftelegram\u002Fwechat）\nsjtu-agent install-daemons --backend psmux --services feishu-bot telegram-bot\n\n# 定时任务（daily-report、remind-check）仍用 Task Scheduler\nsjtu-agent install-daemons --backend taskschd --services daily-report remind-check\n\n# 查看 psmux 服务状态\npsmux -L sjtu-agent ls\n```\n\n**两种后端的对比：**\n\n| | Task Scheduler (`taskschd`) | psmux |\n|---|---|---|\n| 适合 | 定时任务、开机启动 | 常驻进程守护 |\n| 弹窗 | `pythonw.exe` 无弹窗 | 无弹窗 |\n| 崩溃重启 | 手动 | 需手动重拉会话 |\n| 开机自启 | ✅ | ❌ |\n| 查看状态 | `schtasks \u002FQuery` | `psmux -L sjtu-agent ls` |\n| 停止服务 | `schtasks \u002FDelete` | `psmux kill-session -t \u003Cname>` |\n\n> **推荐组合**：`daily-report`、`remind-check` 用 taskschd（定时）；`feishu-bot`、`telegram-bot`、`wechat-bot`、`qq-bot`、`web` 用 psmux（常驻）。\n\n## 在飞书中使用 Bot\n\n> 每位用户需要**自建一个飞书应用**作为 bot 的\"外壳\"（飞书不支持公共多租户 bot，必须挂在你自己的组织\u002F账号下）。整个过程约 5 分钟。\n\n### 一、在飞书开放平台创建应用\n\n1. 打开 https:\u002F\u002Fopen.feishu.cn ，扫码登录（用手机飞书扫）\n2. 右上角进入 **「开发者后台」** → **「创建企业自建应用」**\n   - 应用名称：随便填，比如「SJTU Agent」\n   - 描述、图标随意\n3. 创建完成后，进入这个应用，记下左上角的 **App ID**（形如 `cli_xxxxxxxxxxxx`）和 **App Secret**\n\n### 二、开启机器人能力 + 权限\n\n在你新建的应用里：\n\n1. **「添加应用能力」** → 找到 **机器人** → 启用\n2. **「权限管理」** → 搜索并申请以下 3 个权限（点\"申请权限\"，无需审批立即生效）：\n   - `im:message`\n   - `im:message.p2p_msg:readonly`\n   - `im:message:send_as_bot`\n\n### 三、订阅消息事件（用长连接）\n\n1. **「事件与回调」** → **「事件配置」**\n2. 接收方式切换到 **「使用长连接接收事件」**（**不要**选回调 URL）\n3. **「添加事件」** → 搜索 `im.message.receive_v1`（接收消息 v2.0）→ 添加\n\n### 四、发布应用（关键步骤）\n\n> 没发布的话，飞书里搜不到你的 bot。\n\n1. **「版本管理与发布」** → **「创建版本」**\n   - 版本号填 `1.0.0`\n   - 可用范围：选「全部成员」或「指定成员（包含你自己）」\n2. 点 **「申请发布」**\n3. 个人开发者会进入\"待管理员审批\"状态：\n   - 如果你的飞书账号是个人版（用手机号注册的\"个人组织\"），你**自己就是管理员**——打开手机飞书 → 工作台 → 飞书管理后台 → 应用审核 → 通过即可\n   - 如果是学校\u002F公司的组织，找管理员审批\n\n### 五、在 SJTU-Agent 里填写配置\n\n1. 终端运行 `sjtu-agent web` 打开 WebUI\n2. 找到 **「🪶 飞书 Bot（Lark）」** 卡片，填入：\n   - **App ID**：第一步记下的 `cli_xxx`\n   - **App Secret**\n   - **允许的用户 open_id**：先**留空**，下一步再回来填\n3. 点 **「保存」**\n4. 点 **「🚀 启动飞书 Bot」**（macOS 会把它注册成后台服务，开机自启 + 崩溃自动重启）\n\n### 六、找到 bot 并锁定为只有你能用\n\n1. 打开飞书（手机\u002F电脑都行）\n2. **顶部搜索框搜你的应用名字** → 点头像 → 直接发消息（不用加好友）\n3. 第一次发完消息，bot 会回你 agent 的输出。同时**终端里**会打印一行：\n   ```\n   [feishu] ℹ 白名单为空，已允许所有人；建议把此 open_id 加入白名单：ou_xxxxxxxxxxxx\n   ```\n4. 复制那个 `ou_xxx`，回到 WebUI 飞书卡片的「允许的用户 open_id」里粘贴 → 保存 → 再点一次「🚀 启动飞书 Bot」重启即可\n\n至此 bot 只会响应你本人，其他人发消息会收到拒绝提示。\n\n### 常见问题\n\n| 现象 | 原因 \u002F 解决 |\n|---|---|\n| WebUI 里点启动报错 | macOS 支持一键启动；Windows 用 `sjtu-agent install-daemons --backend psmux --services feishu-bot`；其他系统手动 `sjtu-agent feishu-bot` |\n| 在飞书搜不到自己的 bot | 版本没发布 \u002F 审批没通过 \u002F 可见范围没包含你自己 |\n| bot 在线但不回消息 | 「事件与回调」没切到**长连接**，或没订阅 `im.message.receive_v1` |\n| 回 \"permission denied\" \u002F 报权限错 | 权限管理里漏申请了 `im:message:send_as_bot` |\n| 想验证 App ID\u002FSecret 对不对 | 终端跑 `sjtu-agent feishu-bot -- --test`（注意中间的 `--`） |\n| 想查自己的 open_id | 终端跑 `sjtu-agent feishu-bot -- --whoami`，然后随便发条消息 |\n\n## 在 QQ 中使用 Bot\n\n1. 登录 QQ 机器人平台（[q.qq.com\u002Fqqbot\u002Fopenclaw](https:\u002F\u002Fq.qq.com\u002Fqqbot\u002Fopenclaw\u002F)），创建机器人并获取 `AppID` \u002F `AppSecret`。\n2. 在对话里让 Agent 调用 `setup_qq`（或手动写入 `config.json` 的 `qq_app_id` \u002F `qq_app_secret`）。\n3. 启动 Bot：`sjtu-agent qq-bot`（可选先验证：`sjtu-agent qq-bot --test`）。\n4. 让要授权的 QQ 账号给 Bot 发一条消息，拿到「QQ 用户标识」（注意：不是 QQ 号）。\n5. 把该标识回填给 Agent，调用以下工具管理白名单：\n   - `qq_add_user`：添加白名单用户\n   - `qq_list_users`：查看白名单列表\n   - `qq_remove_user`：删除白名单用户\n6. 白名单修改后，重启 `sjtu-agent qq-bot` 生效。需要后台常驻可运行 `sjtu-agent install-daemons --services qq-bot`。\n\n### MATLAB 图表生成（可选）\n\n若本机安装了 MATLAB（R2020a+），Claude Code 在做作业时可自动调用 MATLAB 生成高质量矢量图表并嵌入 PDF 解答：\n\n1. Claude Code 编写 `_figures.m` 脚本（`figure(); plot(...); exportgraphics(gcf,'fig1.pdf','ContentType','vector')`）\n2. 通过 `matlab -batch` 运行脚本，生成矢量 PDF 图片\n3. 在 `_解答.tex` 中用 `\\includegraphics{fig1.pdf}` 嵌入，xelatex 编译后图表无损整合到 PDF 中\n\nMATLAB 路径可通过 `MATLAB_PATH` 环境变量自定义，未设置时自动搜索常见安装位置。若未安装 MATLAB，Claude Code 将回退到 Matplotlib。\n\n> MiKTeX（`winget install MiKTeX.MiKTeX`）用于 xelatex 编译 LaTeX 生成 PDF。需额外安装 ctex 中文宏包：`mpm --install ctex`。\n\n## 配置说明\n\n最重要的运行时文件有三个：\n\n- `config.json`：平台 Token、Cookie、Telegram 配置\n- `.env`：jAccount 和 MOOC 账号密码，以及致远一号 API Key\n- `agent_config.json`：大模型提供方、Base URL 和模型名（若已在 `.env` 填写 `ZHIYUAN_API_KEY` 则无需此文件）\n\n对于 Canvas，如果 Playwright 和 jAccount 凭据已经就绪，`sjtu-agent setup` 会优先尝试自动创建并保存 Token；如果自动流程失败，再回退到打开 `https:\u002F\u002Foc.sjtu.edu.cn\u002Fprofile\u002Fsettings` 并让你手动确认一次。\n\n## 运行时数据\n\n安装后的命令默认把运行时文件写到用户数据目录，而不是仓库根目录。\n\n- macOS: `~\u002FLibrary\u002FApplication Support\u002Fsjtu-agent`\n- Linux: `${XDG_DATA_HOME:-~\u002F.local\u002Fshare}\u002Fsjtu-agent`\n- Windows: `%APPDATA%\u002Fsjtu-agent`\n\n首次导入包时，如果仓库根目录里已经存在这些旧文件，会自动迁移过去：\n\n- `.env`\n- `config.json`\n- `agent_config.json`\n- `reminders.json`\n- `remind_state.json`\n- `mysjtu_catalog.json`\n- `.schedule_cache.json`\n\n## 发布说明\n\n这个仓库已经具备可安装、可分发的包结构和稳定入口；同时，为了保持现有行为稳定，核心平台适配逻辑仍然保留在顶层模块中。\n","SJTU Agent 是一个面向上海交通大学学生的校园助手，支持终端对话、多种即时通讯平台（如Telegram、飞书、微信、QQ）的Bot服务、提醒守护进程以及MCP服务器。其核心功能包括自动处理校园平台凭据、创建Canvas Token、从Chrome导入Cookie，并能通过自然语言与用户交互完成配置。特别适合需要高效管理学习和生活事务的交大师生使用。项目采用Python编写，易于部署且提供了详细的安装及配置指南，帮助用户快速上手。","2026-06-11 03:59:16","CREATED_QUERY"]