linke-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Linke App contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# linke-cli
+
+林课教务 CLI：把山财教务（正方 jsxsd）的只读查询能力封装为本机命令行
+工具，供人类与 AI agent（Claude Code / ZCode 等）通过 shell 调用。
+
+架构对标 lark-cli：**CLI 承载全部复杂度，skill 保持极薄**。随包分发一份
+skill 说明书（`skills/linke/SKILL.md`），一条命令装入 agent 的 skills 目录。
+
+## 安装与初始化
+
+```bash
+npm install -g linke-cli   # 或 npx linke-cli <命令>
+linke config               # 交互式录入学号/密码（输入不回显）
+linke schedule             # 直接用，登录全自动
+```
+
+要求 Node.js ≥ 18.14，零运行时依赖。
+
+## 命令
+
+| 命令 | 说明 |
+|---|---|
+| `linke config [--clear]` | 录入/清除教务凭据（存 `~/.linke-cli/config.json`，权限 600） |
+| `linke status` | 配置与会话状态（JSON） |
+| `linke login` | 强制重登（平时自动，排障用） |
+| `linke scores [--term 2025-2026-1]` | 成绩（缺省全部学期，JSON） |
+| `linke schedule [--term ...] [--week 3]` | 课表（缺省当前学期全部周，JSON） |
+| `linke schools` | 列出学校适配器 |
+| `linke skill install [--path DIR]` | 安装 skill 说明书到 agent skills 目录 |
+| `linke logout` | 清除本机 session（保留凭据） |
+
+stdout 只输出业务 JSON；进度与错误走 stderr。exit code 契约见
+`src/errors.js` 与 `skills/linke/SKILL.md`。
+
+## 安全设计
+
+- **凭据不出现在命令行参数、shell 历史与任何日志**：只经 `linke config`
+  交互式录入（密码不回显），落盘 `~/.linke-cli/config.json`（0600，目录 0700）。
+- **登录请求从用户本机直发教务系统**，不经云服务器代理转发。
+- **云端只做无状态验证码识别**（传图返文字，`App.Captcha.Recognize`），
+  学号/密码/cookie 不离开本机。
+- **鉴权状态机内建于每个命令**：session 有效直接用、过期自动重登、
+  凭据失效才报错（exit 2）提示重新 `linke config`。
+- **一期只读**：不提供选课/退课/评教等有副作用的接口。
+
+## 学校适配器分层
+
+核心命令框架（`src/bin.js`、`src/session.js`）不含任何学校特有逻辑；
+山财全部逻辑收在 `src/schools/sdufe/`（登录流程、页面解析、密码加密），
+经 `src/schools/registry.js` 暴露统一接口。新增学校 = 新增
+`src/schools/<id>/` 适配器目录并注册。
+
+## 开发
+
+```bash
+git clone <repo> && cd linke-cli
+npm link          # 本地注册 linke 命令
+npm test          # 解析器/加密对拍与行为测试
+```
+
+解析器正则与现役实现同源（`linke_PHP` Model 层 + uni-app 端本机直连
+实现），教务页面改版时以两处现役代码为准回灌。

package/bin/linke.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * linke-cli 入口。参数解析与命令分发，业务逻辑在 src/。
+ */
+import { runCli } from '../src/bin.js'
+
+runCli(process.argv.slice(2)).then(
+  (code) => {
+    process.exitCode = code ?? 0
+  },
+  (err) => {
+    // runCli 内部已负责分类报错；这里是最后的兜底，避免裸栈打到 stdout
+    console.error(`[linke] 未预期错误：${err && err.message ? err.message : err}`)
+    process.exitCode = 1
+  }
+)

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "linke-cli",
+  "version": "0.1.0",
+  "description": "林课 CLI：把山财教务能力（课表/成绩只读查询）封装为本机命令行工具，供用户 agent 通过 shell 调用。登录请求从本机直发教务系统，验证码识别调用林课云端无状态 OCR 接口。",
+  "type": "module",
+  "bin": {
+    "linke": "./bin/linke.mjs"
+  },
+  "engines": {
+    "node": ">=18.14"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "keywords": [
+    "sdufe",
+    "jw",
+    "cli",
+    "agent-skill"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ChuHanModel/linke-cli.git"
+  },
+  "homepage": "https://github.com/ChuHanModel/linke-cli#readme",
+  "bugs": {
+    "url": "https://github.com/ChuHanModel/linke-cli/issues"
+  }
+}

package/skills/linke/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: linke
+version: 0.1.0
+description: "林课教务查询 CLI（山东财经大学正方教务）：查课表、查成绩、看教务登录状态。当用户问「我这学期课表」「今天有什么课」「我的成绩/绩点」「挂了什么课」「教务登录状态」等教务只读信息时使用。登录全自动（验证码云端识别），无需用户介入。"
+metadata:
+  requires:
+    bins: ["linke"]
+  cliHelp: "linke help"
+---
+
+# 林课教务查询（linke-cli skill）
+
+linke 是装在用户本机的教务只读查询工具（山东财经大学，正方 jsxsd 系统）。
+复杂度全在 CLI 内；本 skill 只教你如何在 shell 里调用它。
+
+## 前置检查
+
+```bash
+linke status
+```
+
+- `configured: false` → 用户还没配置凭据。**引导用户本人**在终端运行
+  `linke config`（交互式录入学号密码，输入不回显）。**你不代输密码、
+  不把密码写进任何命令**——凭据只经用户本人的终端进入 `~/.linke-cli/`。
+- `configured: true` 即可用，无需关心登录：每个命令内置鉴权状态机，
+  session 过期自动重登，只有凭据失效才需要人介入。
+
+## 命令
+
+| 需求 | 命令 |
+|---|---|
+| 本学期课表（全部周） | `linke schedule` |
+| 指定学期课表 | `linke schedule --term 2025-2026-1` |
+| 单周课表 | `linke schedule --week 3` |
+| 全部成绩 | `linke scores` |
+| 指定学期成绩 | `linke scores --term 2025-2026-1` |
+| 登录/配置状态 | `linke status` |
+| 强制重登（排障用） | `linke login` |
+
+## 输出契约
+
+- **stdout 只有 JSON**（进度与提示都在 stderr），直接解析 stdout 即可。
+- 课表：`{ term, week, weeks: [[7 个格子] × 节次], remark? }`；每格
+  `{ course, teacher, time, location }`，空格子四字段全空串。`weeks` 外层
+  下标 = 节次-1，内层下标 = 星期-1（周一=0）。
+- 成绩：行数组 `[{ term, courseCode, courseName, scoreText, score, nature }]`；
+  数值成绩 `score` 为 0-100 整数，等级制（优/良/合格等）`score` 为 null、
+  看 `scoreText`。`courseName` 取自成绩行内紧邻成绩的列，个别页面列序
+  不同时可能为空，以 `courseCode` 为准。
+
+## 报错自救（exit code）
+
+| exit code | 含义 | 你的动作 |
+|---|---|---|
+| 0 | 成功 | 解析 stdout |
+| 2 | 凭据失效（教务报密码错误） | 引导用户本人重新运行 `linke config`，不要自行重试 |
+| 3 | 验证码自动识别连续未通过 | 直接重试一次同一命令；仍失败告知用户稍后再试 |
+| 4 | 网络不可达（教务或云端识别） | 告知用户检查网络后重试 |
+| 5 | 解析失败（教务页面改版） | 告知用户到 linke-cli 仓库提 issue，不要反复重试 |
+| 6 | 未配置凭据 | 引导用户本人运行 `linke config` |
+
+stderr 末行「提示:」是面向用户的自救说明，可直接转述。
+
+## 使用纪律
+
+1. **只读**：本 CLI 只提供课表/成绩/状态查询。选课、退课、评教提交等
+   有副作用的操作一律不提供——用户提出此类需求时说明超出能力范围，
+   不要尝试用任何方式绕过。
+2. **凭据纪律**：密码只存在于用户本机 `~/.linke-cli/`（权限 600）。
+   不询问、不存储、不转发用户密码；需要录入时只引导用户本人跑
+   `linke config`。
+3. **频次纪律**：教务系统对高频请求有风控，连续查询之间保持间隔，
+   不做轮询；一次问答内同一命令不重复执行超过 2 次。
+4. 数据口径：成绩/课表数据实时来自教务系统，如与预期不符先用
+   `linke status` 确认登录身份（返回的 userInfo 含姓名/学院/专业/班级）。

package/src/bin.js

@@ -0,0 +1,217 @@
+/**
+ * 命令分发与参数解析（零依赖手写，不引 commander）。
+ * 输出契约：stdout 只有业务 JSON；进度与错误走 stderr；
+ * exit code 见 src/errors.js EXIT 表（与 SKILL.md 同步）。
+ */
+import { resolveConfig, saveConfig, clearConfig, redactConfig, DEFAULT_SCHOOL, DEFAULT_API_BASE } from './config.js'
+import { configMissing, LinkeError } from './errors.js'
+import { listAdapters, getAdapter } from './schools/registry.js'
+import {
+  withSession,
+  login as forceLogin,
+  inspectSession,
+  clearSession,
+} from './session.js'
+import { installSkill, skillSourceDir } from './skill.js'
+import { ask, askPassword } from './prompt.js'
+import { emitJson, progress } from './util.js'
+
+const USAGE = `linke —— 林课教务 CLI（只读查询，供 agent / 人类使用）
+
+用法:
+  linke config [--school sdufe] [--api-base URL]   交互式录入学号/密码（存 ~/.linke-cli/，权限 600）
+  linke config --clear                             清除本机凭据
+  linke status                                     配置与教务会话状态（JSON）
+  linke login                                      强制重新登录（状态机平时自动做）
+  linke scores [--term 2025-2026-1]                成绩查询（缺省=全部学期）
+  linke schedule [--term 2025-2026-1] [--week 3]   课表查询（缺省=当前学期全部周）
+  linke schools                                    列出可用学校适配器
+  linke skill install [--path ~/.agents/skills]    安装 agent skill 说明书
+  linke logout                                     清除本机教务 session（保留凭据）
+  linke help                                       本帮助
+
+说明:
+  登录请求从本机直发教务系统；验证码图片仅用于云端识别（传图返文字）。
+  每个数据命令内置鉴权状态机：session 有效直接用，过期自动重登，
+  凭据失效才报错（exit 2，重新 linke config）。stdout 仅输出 JSON。`
+
+function parseArgs(argv) {
+  const positional = []
+  const flags = {}
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i]
+    if (!token.startsWith('--')) {
+      positional.push(token)
+      continue
+    }
+    const body = token.slice(2)
+    const eq = body.indexOf('=')
+    if (eq !== -1) {
+      flags[body.slice(0, eq)] = body.slice(eq + 1)
+      continue
+    }
+    if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
+      flags[body] = argv[i + 1]
+      i += 1
+    } else {
+      flags[body] = true
+    }
+  }
+  return { positional, flags }
+}
+
+function requireConfig() {
+  const config = resolveConfig()
+  if (!config) throw configMissing()
+  return config
+}
+
+async function cmdConfig(flags) {
+  if (flags.clear) {
+    clearConfig()
+    clearSession()
+    progress('已清除本机凭据与 session')
+    return 0
+  }
+  const school = String(flags.school || DEFAULT_SCHOOL)
+  getAdapter(school) // 校验适配器存在
+  const apiBase = String(flags['api-base'] || DEFAULT_API_BASE)
+
+  process.stderr.write(`配置林课教务凭据（学校适配器: ${school}）\n`)
+  const userId = await ask('学号: ')
+  if (!userId) {
+    progress('学号为空，已取消')
+    return 1
+  }
+  const password = await askPassword('教务密码（输入不回显）: ')
+  if (!password) {
+    progress('密码为空，已取消')
+    return 1
+  }
+  saveConfig({ school, userId, password, apiBase })
+  clearSession() // 凭据变更后旧 session 一律作废
+  progress(`已保存到 ~/.linke-cli/config.json（权限 600）。运行 linke login 验证，或直接运行任意查询命令。`)
+  return 0
+}
+
+async function cmdStatus() {
+  const config = resolveConfig()
+  const adapters = listAdapters()
+  if (!config) {
+    emitJson({ configured: false, adapters, skill: skillSourceDir() })
+    return 0
+  }
+  const sessionInfo = await inspectSession(config)
+  emitJson({
+    configured: true,
+    config: redactConfig(config),
+    adapters,
+    session: sessionInfo,
+    skill: skillSourceDir(),
+  })
+  return 0
+}
+
+async function cmdLogin() {
+  const config = requireConfig()
+  const adapter = getAdapter(config.school)
+  const session = await forceLogin(adapter, config)
+  emitJson({ ok: true, userInfo: session.userInfo })
+  return 0
+}
+
+async function cmdScores(flags) {
+  const config = requireConfig()
+  const term = flags.term ? String(flags.term) : ''
+  const rows = await withSession(config, (adapter, session) =>
+    adapter.fetchScores(session.cookie, { term })
+  )
+  emitJson(rows)
+  return 0
+}
+
+async function cmdSchedule(flags) {
+  const config = requireConfig()
+  let term = flags.term ? String(flags.term) : ''
+  const week = flags.week !== undefined ? String(flags.week) : ''
+  const result = await withSession(config, async (adapter, session) => {
+    if (!term) {
+      term = (await adapter.fetchCurrentTerm(session.cookie)) || ''
+      if (!term) progress('未能解析当前学期，交给教务默认值')
+      else progress(`当前学期: ${term}`)
+    }
+    const schedule = await adapter.fetchSchedule(session.cookie, { term, week })
+    return { term: term || null, week: week || null, ...schedule }
+  })
+  emitJson(result)
+  return 0
+}
+
+async function cmdSchools() {
+  emitJson(listAdapters())
+  return 0
+}
+
+async function cmdSkillInstall(flags) {
+  const explicit = flags.path && flags.path !== true ? String(flags.path) : ''
+  const installed = installSkill(explicit)
+  emitJson({ ok: true, installed })
+  return 0
+}
+
+async function cmdLogout() {
+  clearSession()
+  progress('已清除本机教务 session（凭据保留）')
+  return 0
+}
+
+function printUsage() {
+  process.stderr.write(USAGE + '\n')
+  return 0
+}
+
+export async function runCli(argv) {
+  try {
+    return await dispatch(argv)
+  } catch (err) {
+    if (err instanceof LinkeError) {
+      process.stderr.write(`[linke] ${err.code}: ${err.message}\n`)
+      if (err.hint) process.stderr.write(`提示: ${err.hint}\n`)
+      return err.exitCode
+    }
+    process.stderr.write(`[linke] UNEXPECTED: ${err && err.message ? err.message : err}\n`)
+    return 1
+  }
+}
+
+async function dispatch(argv) {
+  const { positional, flags } = parseArgs(argv)
+  const command = positional[0] || 'help'
+
+  if (flags.help || flags.h) return printUsage()
+
+  switch (command) {
+    case 'help':
+      return printUsage()
+    case 'config':
+      return cmdConfig(flags)
+    case 'status':
+      return cmdStatus()
+    case 'login':
+      return cmdLogin()
+    case 'scores':
+      return cmdScores(flags)
+    case 'schedule':
+      return cmdSchedule(flags)
+    case 'schools':
+      return cmdSchools()
+    case 'skill':
+      if (positional[1] !== 'install') return printUsage()
+      return cmdSkillInstall(flags)
+    case 'logout':
+      return cmdLogout()
+    default:
+      process.stderr.write(`未知命令: ${command}\n\n`)
+      return printUsage()
+  }
+}

package/src/cloudOcr.js

@@ -0,0 +1,54 @@
+/**
+ * 云端验证码识别客户端。
+ *
+ * 合规定位（T3 上下文 ①）：只使用「传图返文字」的无状态能力——
+ * 验证码图片 base64 发往林课云端 App.Captcha.Recognize，云端不接触
+ * 学号/密码/cookie；登录请求本身从用户本机直发教务系统。
+ *
+ * 签名口径与 App 端 repositories/appApi.js 同源：
+ *   signMain = md5("Linke" + service + signTime)，signTime 为 Unix 秒。
+ */
+import crypto from 'node:crypto'
+import { networkError } from './errors.js'
+
+const SERVICE = 'App.Captcha.Recognize'
+const SIGN_KEY = 'Linke'
+
+function buildSignedUrl(apiBase) {
+  const signTime = Math.floor(Date.now() / 1000)
+  const signMain = crypto.createHash('md5').update(SIGN_KEY + SERVICE + String(signTime)).digest('hex')
+  const base = apiBase.replace(/\?.*$/, '')
+  return `${base}?service=${encodeURIComponent(SERVICE)}&signMain=${signMain}&signTime=${signTime}`
+}
+
+/**
+ * 识别验证码图片。
+ * @param {string} apiBase PhalApi 入口地址
+ * @param {string} imageBase64 纯 base64（可带 data URI 前缀，会剥离）
+ * @returns {Promise<string>} 识别文字（小写，教务验证码不区分大小写）
+ */
+export async function recognizeCaptcha(apiBase, imageBase64) {
+  const pure = imageBase64.includes(',') ? imageBase64.split(',')[1] || imageBase64 : imageBase64
+  let response
+  try {
+    response = await fetch(buildSignedUrl(apiBase), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json;charset=utf-8' },
+      body: JSON.stringify({ image_base64: pure }),
+      signal: AbortSignal.timeout(20000),
+    })
+  } catch (err) {
+    throw networkError('云端验证码识别', err)
+  }
+  let body
+  try {
+    body = await response.json()
+  } catch (err) {
+    throw networkError('云端验证码识别（响应解析）', err)
+  }
+  if (body && body.ret == 200 && body.data) {
+    if (body.data.result) return String(body.data.result).toLowerCase()
+    if (body.data.error) throw new Error(`云端识别返回错误：${body.data.error}`)
+  }
+  throw new Error('云端识别返回格式异常')
+}

package/src/config.js

@@ -0,0 +1,93 @@
+/**
+ * 本机配置与凭据存储。
+ *
+ * 安全口径（T3 验收 1）：
+ * - 凭据只存 ~/.linke-cli/config.json，文件权限 0600、目录 0700；
+ * - 凭据只经 `linke config` 交互式录入，不提供命令行参数传入，
+ *   因此不会出现在 shell 历史与进程列表；
+ * - 任何日志/错误输出不包含 password 字段。
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+export const DEFAULT_SCHOOL = 'sdufe'
+export const DEFAULT_API_BASE = 'https://api.linketeam.com/Api/public/index.php'
+
+export function configDir() {
+  return path.join(os.homedir(), '.linke-cli')
+}
+
+export function configPath() {
+  return path.join(configDir(), 'config.json')
+}
+
+export function sessionPath() {
+  return path.join(configDir(), 'session.json')
+}
+
+function ensureDirPrivate(dir) {
+  fs.mkdirSync(dir, { recursive: true })
+  // 目录收紧为 0700（仅当权限过宽时）
+  try {
+    const mode = fs.statSync(dir).mode & 0o777
+    if (mode !== 0o700) fs.chmodSync(dir, 0o700)
+  } catch {
+    /* 非 POSIX 文件系统时忽略 */
+  }
+}
+
+/** 读取配置；不存在返回 null */
+export function loadConfig() {
+  const file = configPath()
+  if (!fs.existsSync(file)) return null
+  try {
+    const raw = fs.readFileSync(file, 'utf8')
+    const parsed = JSON.parse(raw)
+    if (!parsed || typeof parsed !== 'object') return null
+    return parsed
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 写入配置。凭据字段落盘后立即收紧为 0600。
+ * 返回写好的配置（不含明文密码的日志版本由 redactConfig 生成）。
+ */
+export function saveConfig(config) {
+  ensureDirPrivate(configDir())
+  const file = configPath()
+  fs.writeFileSync(file, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 })
+  fs.chmodSync(file, 0o600)
+  return config
+}
+
+/** 用于展示/日志的脱敏配置（密码只留长度） */
+export function redactConfig(config) {
+  if (!config) return null
+  return {
+    school: config.school,
+    userId: config.userId,
+    passwordLength: config.password ? String(config.password).length : 0,
+    apiBase: config.apiBase || DEFAULT_API_BASE,
+  }
+}
+
+/** 解析生效配置：合并默认值；未配置返回 null */
+export function resolveConfig() {
+  const config = loadConfig()
+  if (!config || !config.userId || !config.password) return null
+  return {
+    school: config.school || DEFAULT_SCHOOL,
+    userId: config.userId,
+    password: config.password,
+    apiBase: config.apiBase || DEFAULT_API_BASE,
+  }
+}
+
+/** 清除凭据配置文件 */
+export function clearConfig() {
+  const file = configPath()
+  if (fs.existsSync(file)) fs.rmSync(file)
+}

package/src/errors.js

@@ -0,0 +1,69 @@
+/**
+ * 统一错误分类。exit code 契约同时写进了 skill 说明书（skills/linke/SKILL.md），
+ * 改动这里必须同步改说明书。
+ */
+export class LinkeError extends Error {
+  /**
+   * @param {string} code 机器可读错误码
+   * @param {string} message 人类可读信息（不得包含密码等凭据）
+   * @param {object} options
+   * @param {number} options.exitCode
+   * @param {string} options.hint 自救提示（给 agent / 用户看）
+   * @param {boolean} options.isLoginExpired 内部标记：教务 session 失效，可重登重试
+   */
+  constructor(code, message, options = {}) {
+    super(message)
+    this.name = 'LinkeError'
+    this.code = code
+    this.exitCode = options.exitCode ?? 1
+    this.hint = options.hint ?? ''
+    this.isLoginExpired = options.isLoginExpired ?? false
+    this.cause = options.cause
+  }
+}
+
+export const EXIT = {
+  OK: 0,
+  GENERAL: 1,
+  CREDENTIAL_INVALID: 2,
+  LOGIN_RETRY_EXHAUSTED: 3,
+  NETWORK: 4,
+  PARSE: 5,
+  NOT_CONFIGURED: 6,
+}
+
+export function configMissing() {
+  return new LinkeError('CONFIG_MISSING', '尚未配置教务账号凭据', {
+    exitCode: EXIT.NOT_CONFIGURED,
+    hint: '请先运行: linke config （交互式录入学号与密码，凭据只存本机 ~/.linke-cli/，权限 600）',
+  })
+}
+
+export function credentialInvalid(detail = '') {
+  return new LinkeError('CREDENTIAL_INVALID', `教务账号或密码错误${detail ? `（${detail}）` : ''}`, {
+    exitCode: EXIT.CREDENTIAL_INVALID,
+    hint: '请重新运行: linke config 录入正确凭据',
+  })
+}
+
+export function loginRetryExhausted(attempts) {
+  return new LinkeError('LOGIN_RETRY_EXHAUSTED', `验证码自动识别连续 ${attempts} 次未通过，登录未完成`, {
+    exitCode: EXIT.LOGIN_RETRY_EXHAUSTED,
+    hint: '稍后重试同一命令即可（会自动重登）；若持续失败，可能是云端识别服务或教务系统异常，运行 linke status 检查',
+  })
+}
+
+export function networkError(action, cause) {
+  return new LinkeError('NETWORK', `${action}失败：网络不可达或服务异常`, {
+    exitCode: EXIT.NETWORK,
+    hint: '检查本机网络（教务系统为校内可达的 http://jw.sdufe.edu.cn，云端识别为 https://api.linketeam.com）后重试',
+    cause,
+  })
+}
+
+export function parseError(what) {
+  return new LinkeError('PARSE', `解析${what}失败：教务页面结构可能已变化`, {
+    exitCode: EXIT.PARSE,
+    hint: '这是适配器正则与教务页面脱节，请到 linke-cli 仓库提 issue 注明发生时间',
+  })
+}

package/src/prompt.js

@@ -0,0 +1,39 @@
+/**
+ * 交互式输入（TTY）。密码输入不回显——不依赖第三方库，
+ * 用 readline + 自定义 output 实现（非 TTY 环境直接报错，
+ * 拒绝从管道读密码以免凭据进入 shell 历史/日志链路）。
+ */
+import readline from 'node:readline'
+import { Writable } from 'node:stream'
+import { LinkeError, EXIT } from './errors.js'
+
+export function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close()
+      resolve(String(answer || '').trim())
+    })
+  })
+}
+
+export function askPassword(question) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new LinkeError(
+      'NO_TTY',
+      '当前环境不是交互式终端，无法安全录入密码',
+      { exitCode: EXIT.GENERAL, hint: '请在真实终端中运行: linke config' }
+    )
+  }
+  // 提示写真实 stdout，回显走哑流：密码字符不落到终端，也就进不了终端回滚缓冲
+  process.stdout.write(question)
+  const devnull = new Writable({ write(_chunk, _enc, cb) { cb() } })
+  const rl = readline.createInterface({ input: process.stdin, output: devnull })
+  return new Promise((resolve) => {
+    rl.question('', (answer) => {
+      process.stdout.write('\n')
+      rl.close()
+      resolve(String(answer || ''))
+    })
+  })
+}