# 架构

`szu-cli` 应当提供稳定的命令入口，同时允许内部执行方式替换。

## 分层

```text
用户或 agent
  -> szu-cli CLI
  -> 命令模块
  -> 网关解析
  -> 浏览器后端
  -> 校园网页系统
```

## CLI 层

职责：

- 解析命令和参数。
- 路由到具体功能模块。
- 默认输出适合人阅读的文本。
- 传入 `--json` 时输出稳定 JSON。
- 把内部失败映射为稳定错误码和退出码。

agent 只应依赖这一层，不应依赖内部网页实现。

## 命令模块

每类校园能力放在自己的模块中。当前模块包括：

- `doctor`：本地环境检查。
- `auth`：登录状态和登录流程。
- `skill`：随包 skill 路径和安装。
- `notice`：公文通列表、搜索、详情和下载。
- `course`：我的课表。
- `program`：全校培养方案查询。
- `timetable`：全校班级课表查询。
- `grade`：成绩查询。
- `growth`：成长记录、绩点、学分和排名查询。
- `ideology`：思政与社会实践学分查询。
- `completion`：学业完成、模块完成度和模块课程查询。
- `lecture`：创新领航讲座可报名状态和学习进度查询。
- `electricity`：电费余额和用电记录查询。
- `library`：图书馆馆藏查询。
- `cnki` / `wanfang`：学术数据库元数据查询。

模块不应直接打印内容，应返回结构化结果。

## 网关解析

部分服务只能在校园网或 WebVPN 下访问。网关解析层负责决定：

- 直接校园网 URL；
- WebVPN URL；
- 或在两者都不可用时返回结构化错误。

当前优先支持 direct 校园网路径，WebVPN 后续应接入同一个解析层。

## 浏览器后端

首选后端是 Playwright 持久化浏览器 profile：

```text
~/.szu-cli/browser-profile/
```

用户通过正常网页完成登录，CLI 后续复用本地 profile。

后端职责：

- 打开页面。
- 识别登录页。
- 等待页面进入可解析状态。
- 读取可见 DOM 或稳定网络响应。
- 避免高频轮询。

## 适配器策略

每个校园页面使用小型适配器描述：

- 入口 URL。
- 需要登录的信号。
- 选择器或响应结构。
- 解析规则。
- 规范化输出结构。
- 已知失败模式。

适配器应优先解析用户能正常看到的页面或稳定响应，不应依赖绕过访问控制的隐藏接口。

## Skill 层

skill 是给 agent 的可选使用指南：说明何时调用 `szu-cli`、如何解释错误、哪些行为不能做。

skill 不应复制浏览器自动化或校园业务逻辑。