linke-cli 0.1.0

package/src/schools/registry.js

@@ -0,0 +1,38 @@
+/**
+ * 学校适配器注册表。核心命令框架只依赖本文件暴露的接口，
+ * 不 import 任何学校特有模块——新增学校 = 新增 schools/<id>/ 目录
+ * 并在此注册（T3 验收 7：多学校扩展地基）。
+ */
+import { sdufeAdapter } from './sdufe/adapter.js'
+
+const adapters = new Map([[sdufeAdapter.id, sdufeAdapter]])
+
+/**
+ * 适配器接口契约（核心框架只调用这些成员）：
+ *   id, name, baseUrl
+ *   login({ userId, password, recognizeCaptcha }, { maxRetries, onProgress })
+ *     → { cookie, userInfo }
+ *   probeSession(cookie) → userInfo（过期抛 err.isJwLoginExpired）
+ *   fetchCurrentTerm(cookie) → string | null
+ *   fetchSchedule(cookie, { term, week }) → { weeks, remark? }
+ *   fetchScores(cookie, { term }) → rows[]
+ */
+export function getAdapter(schoolId) {
+  const adapter = adapters.get(schoolId)
+  if (!adapter) {
+    throw new Error(
+      `未知的学校适配器: ${schoolId}（当前支持: ${Array.from(adapters.keys()).join(', ')}）`
+    )
+  }
+  return adapter
+}
+
+/** 注册适配器（新学校接入入口；测试也用它注入 fake 适配器） */
+export function registerAdapter(adapter) {
+  if (!adapter || !adapter.id) throw new Error('适配器缺少 id')
+  adapters.set(adapter.id, adapter)
+}
+
+export function listAdapters() {
+  return Array.from(adapters.values()).map((a) => ({ id: a.id, name: a.name, baseUrl: a.baseUrl }))
+}

package/src/schools/sdufe/adapter.js

@@ -0,0 +1,220 @@
+/**
+ * 山财（sdufe）教务适配器：登录流程与数据抓取。
+ * 流程移植自 linke_App/services/auth/loginFlowService.js 与
+ * linke_App/utils/jwAutoLogin.js（本机直连教务的现役实现），
+ * 差异：验证码识别改调 cloudOcr（App 内同走 App.Captcha.Recognize）。
+ *
+ * 链路纪律：对 jw.sdufe.edu.cn 的所有请求都从用户本机发出；
+ * 云端只收验证码图片 base64（传图返文字）。
+ */
+import { extractCookieHeader, isJwLoginExpired, progress } from '../../util.js'
+import { networkError, credentialInvalid, loginRetryExhausted, LinkeError, EXIT } from '../../errors.js'
+import { computeEncoded } from './encoding.js'
+import {
+  parseUserData,
+  hasAuthenticatedProfileMarkers,
+  parseCurrentTerm,
+  parseScheduleHtml,
+  parseScoresHtml,
+} from './parsers.js'
+
+const USER_AGENT = 'Apifox/1.0.0 (https://apifox.com)'
+const REQUEST_TIMEOUT_MS = 20000
+
+export const sdufeAdapter = {
+  id: 'sdufe',
+  name: '山东财经大学（正方教务 jsxsd）',
+  baseUrl: 'http://jw.sdufe.edu.cn',
+
+  /**
+   * 教务 HTTP 请求（cookie 手动管理，redirect 跟随——与 uni.request 默认行为一致）。
+   * 返回 { status, text, arrayBuffer }。
+   */
+  async request(url, method, { body, cookie, expect = 'text' } = {}) {
+    let response
+    try {
+      response = await fetch(url, {
+        method,
+        redirect: 'follow',
+        headers: {
+          'User-Agent': USER_AGENT,
+          Accept: '*/*',
+          Connection: 'keep-alive',
+          ...(cookie ? { Cookie: cookie } : {}),
+          ...(body !== undefined ? { 'Content-Type': 'application/x-www-form-urlencoded' } : {}),
+        },
+        body,
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      })
+    } catch (err) {
+      throw networkError('请求教务系统', err)
+    }
+    const nextCookie = extractCookieHeader(response)
+    if (expect === 'buffer') {
+      return { status: response.status, buffer: Buffer.from(await response.arrayBuffer()), nextCookie }
+    }
+    return { status: response.status, text: await response.text(), nextCookie }
+  },
+
+  /** 获取会话种子（scode/sxh）与初始 Cookie */
+  async fetchSeed() {
+    const res = await this.request(`${this.baseUrl}/Logon.do?method=logon&flag=sess`, 'POST')
+    const parts = String(res.text || '').trim().split('#')
+    if (parts.length < 2 || !res.nextCookie) {
+      throw new LinkeError('SEED_FAILED', '获取教务会话种子失败', {
+        exitCode: EXIT.NETWORK,
+        hint: '教务系统可能暂不可达，稍后重试',
+      })
+    }
+    return { seedScode: parts[0] || '', seedSxh: parts[1] || '', cookie: res.nextCookie }
+  },
+
+  /** 获取验证码图片 base64 */
+  async fetchCaptcha(cookie) {
+    const res = await this.request(`${this.baseUrl}/verifycode.servlet`, 'GET', {
+      cookie,
+      expect: 'buffer',
+    })
+    const textPeek = res.buffer.subarray(0, 200).toString('utf8')
+    if (textPeek.includes('</html>')) {
+      throw new LinkeError('CAPTCHA_FAILED', '获取验证码图片失败（教务返回了页面而非图片）', {
+        exitCode: EXIT.NETWORK,
+        hint: '稍后重试；若持续出现，教务可能正在维护',
+      })
+    }
+    return res.buffer.toString('base64')
+  },
+
+  /** 提交登录。验证码错误 → isCaptchaError；密码错误 → isPasswordError */
+  async submitLogin({ userId, password, captcha, cookie, seedScode, seedSxh }) {
+    const encoded = computeEncoded(userId, password, seedScode, seedSxh)
+    if (!encoded) throw new Error('登录参数计算失败')
+    const form = [
+      ['userAccount', userId],
+      ['userPassword', password],
+      ['RANDOMCODE', captcha],
+      ['encoded', encoded],
+    ]
+      .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+      .join('&')
+    const res = await this.request(`${this.baseUrl}/Logon.do?method=logon`, 'POST', {
+      body: form,
+      cookie,
+    })
+    const text = res.text || ''
+    if (text.includes('验证码错误')) {
+      const err = new Error('验证码错误')
+      err.isCaptchaError = true
+      throw err
+    }
+    if (text.includes('密码错误')) {
+      const err = new Error('账号或密码错误')
+      err.isPasswordError = true
+      throw err
+    }
+    return res
+  },
+
+  /** 获取个人主页 HTML（登录确认 / session 探活） */
+  async fetchProfileHtml(cookie) {
+    const res = await this.request(`${this.baseUrl}/jsxsd/framework/xsMain_new.jsp`, 'GET', { cookie })
+    return res.text || ''
+  },
+
+  /**
+   * 完整登录：种子 → 验证码 → 云端识别 → 提交 → 主页确认。
+   * 验证码识别/验证码错误自动重试（整体重新取种子+验证码，maxRetries 次）。
+   * @returns {{ cookie: string, userInfo: object }}
+   */
+  async login({ userId, password, recognizeCaptcha }, { maxRetries = 3, onProgress = progress } = {}) {
+    let lastCaptchaError = null
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      onProgress(`获取教务会话（第 ${attempt}/${maxRetries} 次）...`)
+      const { seedScode, seedSxh, cookie } = await this.fetchSeed()
+      try {
+        onProgress('获取验证码图片...')
+        const captchaBase64 = await this.fetchCaptcha(cookie)
+        onProgress('云端识别验证码...')
+        const captcha = await recognizeCaptcha(captchaBase64)
+        if (!captcha) throw Object.assign(new Error('识别结果为空'), { isCaptchaError: true })
+
+        onProgress('提交登录...')
+        try {
+          await this.submitLogin({ userId, password, captcha, cookie, seedScode, seedSxh })
+        } catch (err) {
+          if (err.isCaptchaError) throw err
+          if (err.isPasswordError) throw credentialInvalid('教务返回密码错误')
+          throw err
+        }
+
+        onProgress('确认登录状态...')
+        const html = await this.fetchProfileHtml(cookie)
+        // 假登录检测（App 1.0.6/1.0.8 修复口径）
+        const isLoginPage =
+          typeof html === 'string' &&
+          html.includes('RANDOMCODE') &&
+          (html.includes('userAccount') || html.includes('userPassword'))
+        const userInfo = parseUserData(html)
+        if (isLoginPage || isJwLoginExpired(html) || !hasAuthenticatedProfileMarkers(html, userInfo)) {
+          throw Object.assign(new Error('假登录：主页未命中已登录特征'), { isCaptchaError: true })
+        }
+        return { cookie, userInfo }
+      } catch (err) {
+        if (err.isCaptchaError && attempt < maxRetries) {
+          lastCaptchaError = err
+          onProgress('验证码未通过，刷新重试...')
+          continue
+        }
+        if (err.isCaptchaError) {
+          lastCaptchaError = err
+          break
+        }
+        throw err
+      }
+    }
+    throw loginRetryExhausted(maxRetries)
+  },
+
+  /** 解析当前学期（课表页 select），失败返回 null */
+  async fetchCurrentTerm(cookie) {
+    const res = await this.request(`${this.baseUrl}/jsxsd/xskb/xskb_list.do`, 'GET', { cookie })
+    return parseCurrentTerm(res.text || '')
+  },
+
+  /** 抓课表：term 空 = 教务默认学期；week 空 = 全部周 */
+  async fetchSchedule(cookie, { term = '', week = '' } = {}) {
+    const form = `xnxq01id=${encodeURIComponent(term)}&zc=${encodeURIComponent(String(week))}`
+    const res = await this.request(`${this.baseUrl}/jsxsd/xskb/xskb_list.do`, 'POST', {
+      body: form,
+      cookie,
+    })
+    return parseScheduleHtml(res.text || '')
+  },
+
+  /** 抓成绩：term 空 = 全部学期 */
+  async fetchScores(cookie, { term = '' } = {}) {
+    const form = `kksj=${encodeURIComponent(term)}&xsfs=all`
+    const res = await this.request(`${this.baseUrl}/jsxsd/kscj/cjcx_list`, 'POST', {
+      body: form,
+      cookie,
+    })
+    return parseScoresHtml(res.text || '')
+  },
+
+  /** session 探活：返回当前登录用户信息；过期抛 isJwLoginExpired 错误 */
+  async probeSession(cookie) {
+    const html = await this.fetchProfileHtml(cookie)
+    if (isJwLoginExpired(html)) {
+      const err = new Error('jw login expired')
+      err.isJwLoginExpired = true
+      throw err
+    }
+    const userInfo = parseUserData(html)
+    if (!hasAuthenticatedProfileMarkers(html, userInfo)) {
+      const err = new Error('jw login expired')
+      err.isJwLoginExpired = true
+      throw err
+    }
+    return userInfo
+  },
+}

package/src/schools/sdufe/encoding.js

@@ -0,0 +1,24 @@
+/**
+ * 正方教务（jsxsd）登录密码加密。
+ * 与 App 端 services/auth/jwLoginService.js computeEncoded 逐字节同源；
+ * 算法：账号%%%密码 的前 20 个字符，每个字符后按 sxh 对应位数字
+ * 从 scode 头部取 N 个字符插入；20 字符之后原样拼接。
+ */
+export function computeEncoded(account, password, seedScode, seedSxh) {
+  if (!account || !password || !seedScode || !seedSxh) return ''
+  let scode = seedScode
+  const code = `${account}%%%${password}`
+  let encoded = ''
+  for (let i = 0; i < code.length; i++) {
+    if (i < 20) {
+      const n = parseInt(seedSxh.substring(i, i + 1), 10)
+      const take = Number.isNaN(n) ? 0 : n
+      encoded += code.substring(i, i + 1) + scode.substring(0, take)
+      scode = scode.substring(take, scode.length)
+    } else {
+      encoded += code.substring(i, code.length)
+      break
+    }
+  }
+  return encoded
+}

package/src/schools/sdufe/parsers.js

@@ -0,0 +1,165 @@
+/**
+ * 山财正方教务（jsxsd）页面解析器。
+ * 正则全部移植自现役实现，脱节时以仓库真实代码为准回灌：
+ * - 课表：linke_PHP/Api/src/app/Model/UserSchedule.php getSchedule()
+ *         + linke_App/utils/scheduleLoader.js（周循环抓取版）
+ * - 成绩：linke_PHP/Api/src/app/Model/UserScore.php reloadUserScoreRows()
+ * - 主页：linke_App/services/auth/jwLoginService.js parseUserData()
+ * - 学期：linke_App/utils/scheduleLoader.js fetchScheduleTerm()
+ */
+import { stripSpaces, isJwLoginExpired } from '../../util.js'
+import { parseError } from '../../errors.js'
+
+/** 解析个人主页：姓名/单位/专业/班级（用于登录确认与 status 展示） */
+export function parseUserData(html) {
+  if (!html || typeof html !== 'string') {
+    return { name: '', unit: '', discipline: '', class: '' }
+  }
+  const nameMatch = html.match(/<span class="blue f16 b">(.*?)<\/span>/)
+  const name = nameMatch ? nameMatch[1] : ''
+  const userMatches = html.matchAll(/middletopdwxxcont">(.*?)<\/div>/g)
+  const userData = Array.from(userMatches).map((m) => m[1])
+  if (userData.length < 3) {
+    return { name: name || '', unit: '', discipline: '', class: '' }
+  }
+  return {
+    name: name || '',
+    unit: userData[0] || '',
+    discipline: userData[1] || '',
+    class: userData[2] || '',
+  }
+}
+
+/** 主页 HTML 是否具备已登录特征（防"假登录成功"，1.0.6/1.0.8 修复口径） */
+export function hasAuthenticatedProfileMarkers(html, userInfo) {
+  if (typeof html !== 'string') return false
+  if (html.indexOf('middletopdwxxcont') !== -1) return true
+  if (html.indexOf('blue f16 b') !== -1) return true
+  if (html.indexOf('main_text main_color') !== -1) return true
+  return !!(userInfo && (userInfo.name || userInfo.unit || userInfo.discipline || userInfo.class))
+}
+
+/** 从课表页 select 中解析当前学期（形如 2025-2026-1），失败返回 null */
+export function parseCurrentTerm(html) {
+  if (!html || typeof html !== 'string') return null
+  const optionRegex = /<option\s+value="(\d{4}-\d{4}-\d)"(?:\s+selected="selected")?>(.*?)<\/option>/g
+  const matches = Array.from(html.matchAll(optionRegex))
+  if (matches.length === 0) return null
+  for (const match of matches) {
+    if (match[0].includes('selected="selected"')) return match[1]
+  }
+  return matches[0][1]
+}
+
+/**
+ * 解析课表页 HTML → { weeks: [[cell x7] xN], remark?: string[] }
+ * 单元格 { course, teacher, time, location }；空格为全空字段。
+ */
+export function parseScheduleHtml(html) {
+  if (isJwLoginExpired(html)) {
+    const err = new Error('jw login expired')
+    err.isJwLoginExpired = true
+    throw err
+  }
+  const cells = Array.from(html.matchAll(/kbcontent"\s?>(.*?)<\/div>/g)).map((m) => m[1])
+  if (cells.length < 35) {
+    throw parseError('课表（课程格不足 35，页面可能未正常返回）')
+  }
+  const parsed = cells.map((cell) => {
+    if (cell === '&nbsp;') return { course: '', teacher: '', time: '', location: '' }
+    const courseMatch = cell.match(/(.*?)<font title='老师'>/)
+    const teacherMatch = cell.match(/<font title='老师'>(.*?)<\/font>/)
+    const timeMatch = cell.match(/<font title='周次.*?'>(.*?)<\/font>/)
+    const locationMatch = cell.match(/<font title='教室'>(.*?)<\/font>/)
+    return {
+      course: courseMatch ? courseMatch[1] : '',
+      teacher: teacherMatch ? teacherMatch[1] : '',
+      time: timeMatch ? timeMatch[1] : '',
+      location: locationMatch ? locationMatch[1] : '',
+    }
+  })
+  const remarks = Array.from(
+    html.matchAll(/<\/th>.?<td.?colspan="7".?align="left">(.*?)<\/td>/g)
+  ).map((m) => m[1])
+  const weeks = []
+  for (let i = 0; i < parsed.length; i += 7) {
+    weeks.push(parsed.slice(i, i + 7))
+  }
+  const result = { weeks }
+  if (remarks.length > 0) result.remark = remarks
+  return result
+}
+
+const INVALID_SCORE_TEXTS = new Set(['-', '--', '---', '—', '暂无', '暂未录入', '未录入', '未公布', '无'])
+const TERM_RE = /^\d{4}-\d{4}-\d$/
+
+/**
+ * 解析成绩页 HTML → 行数组 [{ term, courseCode, courseName, scoreText, score, nature }]
+ * 口径与 PHP reloadUserScoreRows 一致：数值成绩限 0-100 记入 score，
+ * 等级制成绩保留 scoreText、score 为 null；无效占位文本丢弃。
+ * courseName 取成绩行内紧邻成绩的列（现役页面为课程名，列序变化时可能为空，
+ * 以 courseCode 为准）。
+ */
+export function parseScoresHtml(html) {
+  if (isJwLoginExpired(html)) {
+    const err = new Error('jw login expired')
+    err.isJwLoginExpired = true
+    throw err
+  }
+  const cleaned = stripSpaces(html)
+  const rows = []
+  const addRow = (term, courseCode, courseName, scoreText, nature) => {
+    term = String(term ?? '').trim()
+    courseCode = String(courseCode ?? '').trim()
+    scoreText = String(scoreText ?? '').trim()
+    if (!TERM_RE.test(term) || courseCode === '' || scoreText === '') return
+    if (INVALID_SCORE_TEXTS.has(scoreText)) return
+    let score = null
+    if (/^\d+(\.\d+)?$/.test(scoreText)) {
+      const numeric = Number(scoreText)
+      if (numeric < 0 || numeric > 100) return
+      score = Math.trunc(numeric)
+    }
+    rows.push({
+      term,
+      courseCode,
+      courseName: String(courseName ?? '').trim(),
+      scoreText,
+      score,
+      nature: String(nature ?? '').trim(),
+    })
+  }
+
+  // 变体一：行首带学期列（现役主口径，PHP matchesWithLeading）
+  const withLeading = Array.from(
+    cleaned.matchAll(
+      /<tr><td>.*?<\/td><td>(.*?)<\/td><tdalign=.*?>(.*?)<\/td><tdalign=.*?>(.*?)<\/td><!--控制成绩显示--><tdstyle=.*?><ahref=.*?>(.*?)<\/a><\/td><\/td><td>.*?<\/td><!--控制绩点显示--><td>.*?<\/td><td>.*?<\/td><td>(.*?)<\/td><td>.*?<\/td><td>.*?<\/td><\/tr>/g
+    )
+  )
+  for (const m of withLeading) {
+    const col1 = m[1] ?? ''
+    const col2 = m[2] ?? ''
+    if (TERM_RE.test(col1)) {
+      addRow(col1, col2, m[3], m[4], m[5])
+    } else if (TERM_RE.test(col2)) {
+      addRow(col2, col1, m[3], m[4], m[5])
+    }
+  }
+
+  // 变体二：legacy 无前导学期列（PHP matchesLegacy，仅在变体一整页零命中时启用）
+  if (rows.length === 0) {
+    const legacy = Array.from(
+      cleaned.matchAll(
+        /<tdalign=.*?>(.*?)<\/td><tdalign=.*?>(.*?)<\/td><!--控制成绩显示--><tdstyle=.*?><ahref=.*?>(.*?)<\/a><\/td><\/td><td>.*?<\/td><!--控制绩点显示--><td>.*?<\/td><td>.*?<\/td><td>(.*?)<\/td><td>.*?<\/td><td>.*?<\/td>/g
+      )
+    )
+    for (const m of legacy) {
+      addRow(m[2], m[1], '', m[3], m[4])
+    }
+  }
+
+  if (rows.length === 0) {
+    throw parseError('成绩（整页未命中任何成绩行）')
+  }
+  return rows
+}

package/src/session.js

@@ -0,0 +1,139 @@
+/**
+ * 鉴权状态机（T3 验收 3）：内建于每个数据命令，调用方无需知道「先登录」。
+ *
+ *   session 有效 → 直接用
+ *   session 缺失/过期 → 自动重登（云端验证码识别）
+ *   凭据失效（教务报密码错误）→ 报错让人介入（exit 2，提示 linke config）
+ *   业务请求中发现 session 失效 → 重登一次后重试
+ *
+ * session 落 ~/.linke-cli/session.json（0600，同凭据目录 0700）：
+ *   { cookie, userInfo, savedAt, expiresAt }
+ * 过期口径：教务 JSESSIONID 为不活动过期（实测约 30 分钟量级），
+ * 保守取 20 分钟无活动即重登；每次成功请求滑动续期。
+ */
+import fs from 'node:fs'
+import { sessionPath, configDir } from './config.js'
+import { recognizeCaptcha } from './cloudOcr.js'
+import { getAdapter } from './schools/registry.js'
+import { progress } from './util.js'
+
+const SESSION_TTL_MS = 20 * 60 * 1000
+const RETRY_ON_EXPIRED_ONCE = 1
+
+export function loadSession() {
+  try {
+    const raw = fs.readFileSync(sessionPath(), 'utf8')
+    const parsed = JSON.parse(raw)
+    if (!parsed || typeof parsed !== 'object' || !parsed.cookie) return null
+    return parsed
+  } catch {
+    return null
+  }
+}
+
+export function saveSession(adapter, cookie, userInfo) {
+  fs.mkdirSync(configDir(), { recursive: true })
+  const payload = {
+    school: adapter.id,
+    cookie,
+    userInfo: userInfo || {},
+    savedAt: new Date().toISOString(),
+    expiresAt: Date.now() + SESSION_TTL_MS,
+  }
+  fs.writeFileSync(sessionPath(), JSON.stringify(payload, null, 2) + '\n', { mode: 0o600 })
+  try {
+    fs.chmodSync(sessionPath(), 0o600)
+  } catch {
+    /* 非 POSIX 文件系统时忽略 */
+  }
+  return payload
+}
+
+export function touchSession(session) {
+  if (!session) return
+  session.expiresAt = Date.now() + SESSION_TTL_MS
+  try {
+    fs.writeFileSync(sessionPath(), JSON.stringify(session, null, 2) + '\n', { mode: 0o600 })
+  } catch {
+    /* 续期失败不影响本次请求 */
+  }
+}
+
+export function clearSession() {
+  const file = sessionPath()
+  if (fs.existsSync(file)) fs.rmSync(file)
+}
+
+export function isSessionUsable(session) {
+  return !!(session && session.cookie && Date.now() < session.expiresAt - 60_000)
+}
+
+/** 强制登录（忽略现有 session），成功后落盘 */
+export async function login(adapter, config) {
+  const recognize = (imageBase64) => recognizeCaptcha(config.apiBase, imageBase64)
+  const { cookie, userInfo } = await adapter.login(
+    { userId: config.userId, password: config.password, recognizeCaptcha: recognize },
+    { onProgress: progress }
+  )
+  return saveSession(adapter, cookie, userInfo)
+}
+
+/**
+ * 状态机主入口：保证 fn 在有效 session 下执行。
+ * @param {object} config resolveConfig() 的结果
+ * @param {(adapter, session) => Promise<any>} fn 业务函数
+ */
+export async function withSession(config, fn) {
+  const adapter = getAdapter(config.school)
+  let session = loadSession()
+  if (!isSessionUsable(session)) {
+    progress('教务 session 缺失或已过期，自动登录...')
+    session = await login(adapter, config)
+  }
+
+  let expiredRetries = RETRY_ON_EXPIRED_ONCE
+  while (true) {
+    try {
+      const result = await fn(adapter, session)
+      touchSession(session)
+      return result
+    } catch (err) {
+      if (err && err.isJwLoginExpired && expiredRetries > 0) {
+        expiredRetries -= 1
+        progress('教务 session 中途失效，自动重登后重试...')
+        session = await login(adapter, config)
+        continue
+      }
+      throw err
+    }
+  }
+}
+
+/** status 命令用：带本地判定与远端探活的完整状态 */
+export async function inspectSession(config) {
+  const adapter = getAdapter(config.school)
+  const session = loadSession()
+  const local = {
+    hasSession: !!session,
+    expiresAt: session ? new Date(session.expiresAt).toISOString() : null,
+    expired: session ? !isSessionUsable(session) : null,
+    userInfo: session?.userInfo || null,
+  }
+  let remote = null
+  if (session && isSessionUsable(session)) {
+    try {
+      const userInfo = await adapter.probeSession(session.cookie)
+      remote = { alive: true, userInfo }
+      touchSession(session)
+    } catch (err) {
+      if (err && err.isJwLoginExpired) {
+        remote = { alive: false }
+      } else {
+        remote = { alive: null, error: err.message }
+      }
+    }
+  }
+  return { local, remote }
+}
+
+export { SESSION_TTL_MS }

package/src/skill.js

@@ -0,0 +1,55 @@
+/**
+ * skill 说明书分发（T3 验收 5）：把随包分发的 SKILL.md 安装进
+ * 用户 agent 的 skills 目录。skill 保持极薄——只描述如何 shell 调用
+ * CLI，复杂度全部在 CLI 内（lark-cli 架构口径）。
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const SKILL_DIR_NAME = 'linke'
+
+function packagedSkillDir() {
+  const here = path.dirname(fileURLToPath(import.meta.url))
+  // src/ → 包根；npm 安装后 skills/ 随 files 字段一起分发
+  return path.join(path.dirname(here), 'skills', SKILL_DIR_NAME)
+}
+
+/** 常见 agent 的 skills 根目录（存在才视为目标；--path 可显式指定） */
+function detectSkillRoots() {
+  const home = os.homedir()
+  return [
+    path.join(home, '.agents', 'skills'),
+    path.join(home, '.claude', 'skills'),
+    path.join(home, '.zcode', 'skills'),
+  ].filter((dir) => fs.existsSync(path.dirname(dir)))
+}
+
+export function installSkill(explicitPath) {
+  const source = packagedSkillDir()
+  if (!fs.existsSync(path.join(source, 'SKILL.md'))) {
+    throw new Error(`随包 skill 说明书缺失：${source}/SKILL.md（安装包不完整）`)
+  }
+  const targets = explicitPath ? [explicitPath] : detectSkillRoots()
+  if (targets.length === 0) {
+    throw new Error(
+      '未探测到已安装 agent 的 skills 目录；用 --path <目录> 显式指定，' +
+        '例如: linke skill install --path ~/.agents/skills'
+    )
+  }
+  const installed = []
+  for (const root of targets) {
+    const dest = path.join(root, SKILL_DIR_NAME)
+    fs.mkdirSync(dest, { recursive: true })
+    for (const file of fs.readdirSync(source)) {
+      fs.copyFileSync(path.join(source, file), path.join(dest, file))
+    }
+    installed.push(dest)
+  }
+  return installed
+}
+
+export function skillSourceDir() {
+  return packagedSkillDir()
+}

package/src/util.js

@@ -0,0 +1,48 @@
+/**
+ * 通用工具：cookie 提取、教务 HTML 清洗、输出辅助。
+ * 口径与 App 端 linke_App/repositories/jwHttp.js、utils/jwLoginExpired.js 保持同源。
+ */
+
+/**
+ * 从 fetch Response 的 Set-Cookie 头提取 "k=v; k2=v2" 形式的 Cookie 头。
+ * 依赖 Node >= 18.14 的 headers.getSetCookie()。
+ */
+export function extractCookieHeader(response) {
+  const list = response.headers.getSetCookie ? response.headers.getSetCookie() : []
+  const pairs = []
+  for (const raw of list) {
+    const pair = String(raw).split(';')[0]
+    if (pair) pairs.push(pair.trim())
+  }
+  return pairs.join('; ')
+}
+
+/**
+ * 教务 HTML 预处理：删除空格（含全角）与换行。
+ * PHP 端与 App 端解析前都做同一处理，正则依赖此口径（<td align= 会变 <tdalign=）。
+ */
+export function stripSpaces(html) {
+  return String(html ?? '').replace(/[ \u3000\t\n\r]/g, '')
+}
+
+/**
+ * 教务「登录过期」判定：与 App 端 utils/jwLoginExpired.js 同源。
+ * 登录页通常短且含 </html>；部分情况直接返回"用户登录/请先登录"文案。
+ */
+export function isJwLoginExpired(html) {
+  if (!html || typeof html !== 'string') return false
+  const trimmed = html.trim()
+  if (trimmed.includes('</html>') && trimmed.length < 5000) return true
+  if (trimmed.includes('用户登录') || trimmed.includes('请先登录')) return true
+  return false
+}
+
+/** 进度信息走 stderr，保证 stdout 只有结构化 JSON（agent 解析契约） */
+export function progress(msg) {
+  process.stderr.write(`[linke] ${msg}\n`)
+}
+
+/** stdout 输出 JSON 结果 */
+export function emitJson(value) {
+  process.stdout.write(JSON.stringify(value, null, 2) + '\n')
+}