SJTU Agent 文档

Appearance

从零安装 ​

面向第一次配置开发环境的同学，按顺序照抄命令即可。全程约 20–30 分钟（大部分时间在等下载）。遇到概念不懂时查 AI 使用基础。

开始之前你需要

  1. 一台 Windows / macOS / Linux 电脑；
  2. Python 3.11 或更新版本（下面第二步会装）；
  3. Git（同上）;
  4. 能登录 jAccount，访问致远一号和学校系统建议在校园网环境下；校外是否需要 VPN 以官方说明为准。

第一步：拿到致远一号 API Key ​

  1. 打开 https://zhiyuan.sjtu.edu.cn，用 jAccount 登录；
  2. 在站内找到 API Key 管理页面，创建一个新 Key（各人名字随意，比如 sjtu-agent）；
  3. 立刻把 Key 复制保存好。它相当于你的账户钥匙，别发给别人、别截图外传。

具体页面入口可能随平台改版变化，站内找不到就看官方调用指南：https://claw.sjtu.edu.cn/guide/sjtu-api/。

第二步：装基础环境（Python + Git） ​

先检查电脑里有没有：打开终端，输入

bash
python --version   # Windows 若无输出试试: py -3 --version
git --version

版本号 ≥ 3.11 且 git 正常输出 → 跳过本步，直接去第三步。否则按系统装：

Windows

  1. 到 https://www.python.org/downloads/ 下载并运行 Python 安装器，第一屏务必勾选 "Add python.exe to PATH"（这是新手最常见的翻车点），再点 Install Now；
  2. 到 https://git-scm.com/download/win 安装 Git，一路默认即可；
  3. 重开一个 PowerShell 窗口（PATH 变更只对新窗口生效），再验证一次上面的版本命令。

macOS

bash
# 装 Git（会顺带装编译工具）
xcode-select --install

系统自带的 python3 往往版本偏旧，建议到 https://www.python.org/downloads/ 装最新版，或用 Homebrew：

bash
brew install python@3.13 git

Linux（以 Debian/Ubuntu 为例）

bash
sudo apt update && sudo apt install -y python3.12 python3-venv git

第三步：克隆仓库并一键安装 ​

选你顺手的位置存放项目（下例放在用户主目录），然后运行安装脚本——它会自动创建虚拟环境、装依赖、下载浏览器内核，最后直接进入配置向导。

powershell
git clone https://github.com/kuan-er/sjtu-agent.git
cd sjtu-agent
powershell -ExecutionPolicy Bypass -File .\install\install.ps1
bash
git clone https://github.com/kuan-er/sjtu-agent.git
cd sjtu-agent
bash install/install.sh

💡 不想进配置向导可加参数 --no-setup（Windows 用 -NoSetup）；网速差可加 --skip-playwright 先跳过浏览器内核下载，代价是之后无法自动登录 jAccount 抓数据。

第四步：配置向导（setup 向导） ​

脚本结束后会自动进入 sjtu-agent setup。按提示逐项走：

步骤会发生什么新手建议
1. 大模型选「致远一号」，粘贴第一步的 Key，向导会当场测试连通性直接选默认
2. 视觉模型（可选）用于识图（看照片里的题目、解析扫描件）。想省掉这一步？ 在第 1 步选 DeepSeek 官方并填模型名 deepseek-flash（V4.1 Flash），它原生支持看图，本步可直接 skip致远一号用户可跳过，不影响文字聊天
3. Playwright Chromium下载自动操作浏览器的内核，供自动登录 jAccount 拉课表/DDL 用建议安装
4. jAccount 账号填用户名（不是学号，通常是你登录 my.sjtu.edu.cn 的拼音名）和密码。只保存在本机 .env 文件里，用于自动 SSO建议填写；介意也可跳过，后续手动登录
5. MOOC 账号（可选）用于聚合中国大学 MOOC 的 DDL在用就填，不用就跳过
6. 后台服务（可选）注册定时任务（每日提醒检查等）先跳过，玩熟了再说

任何一步都可以求助或跳过，之后随时能重新跑 sjtu-agent setup 补配。

完成后验证一下状态：

bash
sjtu-agent doctor   # 应显示大模型已配置 + 各项路径正常

省力路线：让 Coding Agent 替你装 ​

照抄命令遇到报错不想自己查？可以请一个 Coding Agent 代劳——能读写文件、执行命令、自动排错的 AI 助手。推荐 DeepSeek Harness（简称 DSH，DeepSeek 官方开源的 Agent 框架：MIT 协议、代码公开可审，Windows / macOS / Linux 通用，自带浏览器界面）。同类还有 Claude Code 等。这不只是偷懒：熟练指挥 AI Agent 干活，本身就是大学四年最值得练的能力之一。本项目自己也大量靠 Coding Agent 开发（见 CONTRIBUTING 的「Coding Agent 辅助开发」）。

为什么把 ZCode 换成了 DSH

本指南此前推荐智谱 ZCode。2026 年 9 月 18 日，ZCode 被曝「代码库索引 / Repo Wiki」功能上线初期默认开启：生成 Repo Wiki 页面时会触发仓库数据（含历史版本）上传到云端，官方称页面生成后数据即销毁。智谱当日向用户致歉、称问题已修复，并宣布开源 ZCode 代码库、引入第三方审查（报道）。这类工具要读你的代码，还可能碰到 .env，数据去向必须能自己查证——所以我们改用开源可审的 DSH。这条教训对任何 Agent 都成立：装之前先弄清它会把你的代码发到哪儿。

用法很简单——先装 Node.js（官网下 LTS 版，一路「下一步」即可；DSH 跑在 Node.js 上），再克隆仓库、启动 DSH，然后说人话：

bash
# 1) 下载项目
git clone https://github.com/kuan-er/sjtu-agent.git

# 2) 启动 DSH（首次运行会提示下载，回车确认）
npx @deepseek-ai/dsh web

浏览器会自动打开 DSH 界面（默认 http://127.0.0.1:3080）。接着：

  1. 配模型：在 设置 → 模型 里填一个模型 Key——最省事是到 DeepSeek 开放平台 注册拿一个；已有致远一号 Key 的同学可以选「添加自定义提供方」把它接进来（API 地址 https://models.sjtu.edu.cn/api/v1、协议选 OpenAI 兼容、模型 deepseek-chat），细节与网关兼容性见 DSH《配置模型》；
  2. 开工作区：点「选择工作区」，把 sjtu-agent 文件夹添加进来并选中；
  3. 下指令：新建会话，把下面这段粘进去：
text
我是新手，第一次配置开发环境。请按 docs/guide/install.md 的流程帮我安装并配置这个项目，
我的系统是 Windows。每一步做什么先简单告诉我，遇到报错你来排查。

它会自动读仓库里的 AGENTS.md 获取项目引导，替你跑安装脚本、解释向导选项、卡住时看日志找原因。你只需要在它停下来提问时回答（选哪个、要不要装）。

唯一要自己动手的：输入凭据

jAccount 密码、API Key 这类敏感信息，在向导提示时自己敲进去，不要粘贴到和 Agent 的聊天里——聊天内容会留在会话记录中。让 Agent 干活，但凭据不外借（与安全三原则一脉相承）。

装完出问题也可以随时叫它帮忙：把 sjtu-agent doctor 的输出贴给它（注意先删掉里面的 Key），让它对照本页排错。DSH 目前处于开发者预览阶段、迭代较快，若卡在 DSH 自身（装不上、界面报错），可到它的 GitHub Discussions 找答案或提问。

第五步：第一次对话 ​

bash
sjtu-agent

进去先来一句「你好，请介绍一下你能帮我做什么」确认大脑在线，然后直接试真实功能（可能触发一次 jAccount 自动登录；弹出验证码时人工输入即可）：

text
这周有什么作业要交？
明天上午有课吗？
现在去哪吃？

回答慢或者一直转圈？看看是不是不在校园网/代理环境导致连不上学校系统，具体见排错手册。

第六步（可选）：换更好看的界面 / 绑定聊天软件 ​

bash
sjtu-agent web        # Web GUI，浏览器自动打开 http://127.0.0.1:7860
pip install -e ".[tui]" && sjtu-agent tui   # 全屏终端界面

想在飞书/微信/QQ 里随口使唤它，见 README 的多平台 Bot章节；飞书详细排错在这里。日常玩法直接翻话术库。

出问题了？ ​

症状处理
python 不是内部或外部命令 / 未找到 Python回第二步装 Python（Windows 别忘勾 Add to PATH），重开终端再试
版本低于 3.11卸载旧的另装新版，或用安装参数 --python 指定新装的 Python
PowerShell 提示"禁止运行脚本"你应该是直接双击/右键运行的 ps1；请按第三步原样整条复制运行（命令里已带 -ExecutionPolicy Bypass）
致远一号测试连接失败核对 Key 是否复制完整；确认网络能通 models.sjtu.edu.cn；限流规则看官方指南
查 DDL/课表失败多为 jAccount 登录问题（验证码/二次验证），见排错手册

都不行的话，带着 sjtu-agent doctor 的输出去 GitHub 提 issue（提问模板）；贴日志前确认里面没有密码和 API Key。