本地 Agent 接入指南

1. 概述

Mini-HBUT 桌面版启动后会同时在本机启动一个仅供本机访问的 HTTP 服务，用于向同一台电脑上的 AI Agent、脚本或辅助工具开放只读的教务数据查询能力。整体模型非常简单：

• 服务仅绑定 127.0.0.1，局域网与其他设备不可达；
• 所有端点都是 GET 请求、只读语义，不会向教务系统发起任何写操作；
• 认证方式为请求头 Authorization: LocalToken <令牌>，令牌来自本机令牌文件；
• 数据由桌面版使用用户已登录的会话代为查询，Agent 不接触教务密码。

2. 前置条件

1. 安装并运行 Mini-HBUT 桌面版（本地服务随桌面版一起启动）；
2. 在 App 中登录学号账号，未登录时接口会返回 NOT_LOGGED_IN 提示；
3. 确认本机数据目录中存在令牌文件 %APPDATA%/mini-hbut/local-agent-token（内容为 64 位 hex 字符串）。

Windows 下 %APPDATA% 通常指向 C:/Users/<用户名>/AppData/Roaming； 在 PowerShell 或脚本中读取时请展开环境变量后再拼接路径。

3. 令牌获取与认证

App 启动后会自动生成本地代理令牌并写入令牌文件，路径固定为：

%APPDATA%/mini-hbut/local-agent-token

文件内容为一段 64 位 hex 字符串（去除首尾空白后使用）。调用接口时将其放入请求头：

Authorization: LocalToken <64位hex令牌>

4. 端点参考

以下三个端点覆盖当前全部能力，均为 GET 请求。示例中的 <端口> 为占位符， 实际端口以应用运行日志输出为准（见常见问题）。

# 读取令牌并请求基本档案（Git Bash / macOS / Linux）
TOKEN=$(cat "$APPDATA/mini-hbut/local-agent-token")

curl -s "http://127.0.0.1:<端口>/local/profile" \
  -H "Authorization: LocalToken $TOKEN"

{
  "student_id": "2312345678",
  "name": "张三",
  "gender": "男",
  "faculty": "计算机学院",
  "major": "计算机科学与技术",
  "class_name": "23计科1班",
  "grade": "2023"
}

TOKEN=$(cat "$APPDATA/mini-hbut/local-agent-token")

curl -s "http://127.0.0.1:<端口>/local/grades" \
  -H "Authorization: LocalToken $TOKEN"

{
  "terms": [
    {
      "term": "2024-2025-1",
      "gpa": 3.42,
      "courses": [
        {
          "course_name": "数据结构",
          "course_type": "必修",
          "credit": 3.0,
          "score": 92,
          "grade_point": 4.0
        }
      ]
    }
  ]
}

TOKEN=$(cat "$APPDATA/mini-hbut/local-agent-token")

curl -s "http://127.0.0.1:<端口>/local/timetable" \
  -H "Authorization: LocalToken $TOKEN"

{
  "term": "2024-2025-1",
  "weeks": 20,
  "courses": [
    {
      "name": "操作系统",
      "teacher": "李老师",
      "classroom": "教1-301",
      "week_start": 1,
      "week_end": 16,
      "day_of_week": 1,
      "section_start": 1,
      "section_end": 2
    }
  ]
}

响应体均为 JSON；以上结构为示意，用于说明字段含义与分组方式，新增字段将保持向后兼容。 成绩单按学期分组返回，课表以“星期 + 节次 + 周次区间”描述每门课的位置。

5. 错误处理

认证类错误通过 HTTP 状态码与响应体中的 error 字段区分：

HTTP/1.1 401 Unauthorized

{
  "error": "LOCAL_TOKEN_INVALID",
  "message": "本地令牌缺失、格式不正确或不匹配"
}

HTTP/1.1 401 Unauthorized

{
  "error": "NOT_LOGGED_IN",
  "message": "App 当前未登录，请先在 Mini-HBUT 中登录学号账号"
}

其余 5xx 表示本地服务内部异常；连接被拒绝通常意味着桌面版未启动或端口不正确。

6. Python 最小示例

import os
from pathlib import Path

import requests  # pip install requests

# 端口以 Mini-HBUT 运行日志输出的实际值为准，此处仅为占位
PORT = 0

base_url = 'http://127.0.0.1:' + str(PORT)
token_path = Path(os.environ['APPDATA']) / 'mini-hbut' / 'local-agent-token'
token = token_path.read_text(encoding='utf-8').strip()

resp = requests.get(
    base_url + '/local/profile',
    headers={'Authorization': 'LocalToken ' + token},
    timeout=5,
)

if resp.status_code == 401:
    body = resp.json()
    print('请求被拒绝:', body.get('error'), '-', body.get('message', ''))
else:
    print(resp.json())

7. Node.js 最小示例

// 需要 Node.js 18+（内置全局 fetch），以 ESM 方式运行
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import process from 'node:process';

// 端口以 Mini-HBUT 运行日志输出的实际值为准，此处仅为占位
const PORT = 0;

const baseUrl = 'http://127.0.0.1:' + String(PORT);
const tokenPath = join(process.env.APPDATA || '', 'mini-hbut', 'local-agent-token');
const token = readFileSync(tokenPath, 'utf8').trim();

const resp = await fetch(baseUrl + '/local/profile', {
  headers: { Authorization: 'LocalToken ' + token },
});

if (!resp.ok) {
  const body = await resp.json().catch(() => ({}));
  console.error('请求被拒绝:', resp.status, body.error);
} else {
  console.log(await resp.json());
}

8. 常见问题

9. 相关文档

• 数据共享说明：第三方网站经云端快照获取数据的机制
• OIDC 接入指南：需要正式身份认证时的标准接入方式
• 安全与隐私：凭据与数据的安全边界