dsh-zju-lecture-note 2.2.4 → 2.2.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/technical.md CHANGED
@@ -25,6 +25,7 @@ dsh-zju-lecture-note/
25
25
  ├── zju_lecture/ # 核心库(纯标准库)
26
26
  │ ├── client.py # 智云课堂 API 客户端(TLS 校验 + 同域重定向)
27
27
  │ ├── cookies.py # Edge Cookie 读取与安全清理
28
+ │ ├── browser_login.py # 一键登录窗口:CDP 取 Cookie + 安全保存 + 清除
28
29
  │ ├── security.py # Cookie 校验 / redactor / 本地文件边界
29
30
  │ ├── paths.py # 工作区与相对路径解析
30
31
  │ ├── courseware.py # 课件文本提取(带路径校验)
@@ -42,6 +43,10 @@ dsh-zju-lecture-note/
42
43
  │ └── cli.py # 命令行入口
43
44
  ├── skills/zju-lecture-summarizer/ # 讲义生成 SOP(五段式模板 + 公式规范)
44
45
  ├── skills/zju-lecture-summarizer.manifest.json
46
+ ├── skills/zju-lecture-summarizer-help/ # 用户命令:登录辅助与故障排查
47
+ ├── skills/zju-lecture-summarizer-help.manifest.json
48
+ ├── skills/zju-lecture-summarizer-login/ # 用户命令:打开独立登录窗口 / 清除登录态
49
+ ├── skills/zju-lecture-summarizer-login.manifest.json
45
50
  ├── skills/scholia-notes/ # 填空式学习笔记 Skill(MIT,独立授权)
46
51
  │ ├── SKILL.md / LICENSE / README.md / THIRD_PARTY_NOTICES.md
47
52
  │ ├── references/ # API / 风格指南 / 排错 / 格式规范
@@ -62,7 +67,7 @@ dsh-zju-lecture-note/
62
67
 
63
68
  ```text
64
69
  回放 URL / sub_id
65
- → zju_fetch_transcript(公开字幕接口,按分钟 / 逐句 / 分块 / JSON)
70
+ → zju_fetch_transcript(先匿名,按分钟 / 逐句 / 分块 / JSON;鉴权条件见下)
66
71
  →(可选)zju_extract_courseware(本地课件校准术语)
67
72
  → Agent 写 Markdown
68
73
  → zju_write_note:命名 → 修公式 → 校验 → 写文件 → 排版同名 PDF
@@ -70,6 +75,35 @@ dsh-zju-lecture-note/
70
75
  →(compile)scholia PDF + 逐页 PNG
71
76
  ```
72
77
 
78
+ 字幕保留 `classroom.zju.edu.cn`:先匿名请求,**仅 HTTP 401/403** 时调用 `_resolve_cookie`
79
+ (进程缓存 → `ZJU_COOKIE` → `ZJU_COOKIE_FILE` → `zju_login` 保存的本机登录态 → Edge)
80
+ 解析 `_token`,用 Bearer 重试一次。
81
+ 兼容两种返回:`ainew` 用 `BeginSec` / `Text`,老课程 `ai` 用 `time` / `zhtext` / `entext`
82
+ (以第一条时间戳为相对零点换算秒数)。
83
+ 字幕鉴权属于核心链路,**不需要开启登录辅助工具**(`enableLoginTools` 只控制视频直链与读 Cookie 工具)。
84
+ 字幕请求**不发 Cookie 头**;官网实证同一课匿名 403、Bearer-only HTTP 200 / code 0、返回 942 条字幕,
85
+ 不需要更换主机。CLI 默认自动重试,`--no-login` 可关闭,`--cookie-file` 可指定本地文件;没有明文 token 参数。
86
+
87
+ ### 一键登录窗口(`zju_login`)
88
+
89
+ 读 Edge 数据库是次级路径:ABE 打开后,外部进程连 DPAPI 也解不开 v20 Cookie,退出 Edge 也没用。
90
+ 因此本机没有可用登录态、或登录态被服务端判定失效时,走独立登录窗口:
91
+
92
+ 1. `browser_login.py` 用 `--user-data-dir=<用户状态目录>/login-profile` 启动 Edge / Chrome,
93
+ 带 `--remote-debugging-port=0`;端口只绑 `127.0.0.1`,不碰用户日常 Edge。
94
+ 2. 浏览器打开用户给的课堂链接(仅 `https://*.zju.edu.cn`);用户在页面里完成 SSO / 2FA。
95
+ 3. 插件每 1.5s 通过 CDP `Storage.getCookies` 读取 Cookie,只保留课堂主机与
96
+ `.zju.edu.cn` 父域(`_token` 所在),排除其他 ZJU 子域与相似域名。
97
+ 4. 检测到可解析的 `_token` 后,`save_session()` 只保存 Cookie 头:
98
+ Windows 用 DPAPI(`CryptProtectData`,绑定当前用户),macOS / Linux 用 0600 文件;
99
+ 不保存账号密码。
100
+ 5. 关闭浏览器,`zju_login` 把 Cookie 放进本进程缓存;Agent 重试字幕一次。
101
+ 6. 服务端仍返回 401/403 时,`_forget_cookie("session")` 删除登录态与专用 profile,
102
+ 下次 `zju_login` 从真正的登录页开始,而不是重放死 Cookie。
103
+
104
+ `clear=true` 删除登录态与独立浏览器 profile;无图形界面、未安装浏览器或策略禁用远程调试时,
105
+ 返回 `no_browser` / `devtools_blocked`,此时才回退到 `ZJU_COOKIE_FILE` 高级方案。
106
+
73
107
  ## 2. 安装形态与依赖
74
108
 
75
109
  | 形态 | 载体 | 依赖 |
@@ -89,7 +123,7 @@ dsh-zju-lecture-note/
89
123
  4. 下载失败会写一个 6 小时的冷却标记,避免每写一份讲义都卡一次超时。
90
124
 
91
125
  `ZJU_TYPST_AUTO_INSTALL=0` 关闭自动安装;`ZJU_TYPST_MIRROR` 可给下载 URL 加镜像前缀
92
- (只影响传输路径,哈希仍按清单校验)。`zju_doctor` 报告上述全部状态,`install=true` 立即重试安装。
126
+ (只影响传输路径,哈希仍按清单校验)。`zju_doctor` 报告上述状态,`install=true` 立即重试安装;`login=true` 才读取本机登录态检查可用性。
93
127
 
94
128
  **离线编译**:6 个 `@preview` 包(scholia / frame-it / marginalia / theoretic / showybox / noteworthy)
95
129
  已 vendor 到 `zju_lecture/typst-packages/`,编译统一带 `--package-path` 与工作区内的
@@ -118,6 +152,15 @@ dsh plugin --profile desktop add file:/absolute/path/to/zju-lecture-agent-plugin
118
152
  本插件声明 `>=0.2.0-rc.2 <0.3.0-0`,不匹配时需要显式的版本豁免
119
153
  (`dsh plugin allow-version`)。
120
154
 
155
+ **GitHub 安装的 5 秒预检**:dsh 宿主在启动 pnpm 前会执行
156
+ `git -c credential.helper= ls-remote -- <repo> HEAD`,默认 5 秒超时
157
+ (`plugin-manager` 的 `githubConnectionTimeoutMs`,最小 1000ms)。超时报
158
+ `connection to github.com timed out after 5000ms`,此时 pnpm 尚未启动、profile 不会被修改。
159
+ dsh 只读 `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` / `NO_PROXY`,不读 Windows 系统代理,
160
+ git 也不读;浏览器能打开 GitHub 不代表预检能过。处置顺序:优先用 npm 包名安装(不走 GitHub);
161
+ 必须走 GitHub 源时给 git 配代理,并让 dsh 进程能读到同一组环境变量;或在 profile 的
162
+ `cordis.patch.yml` 里把 `plugin-manager` 的 `githubConnectionTimeoutMs` 调大后重启。
163
+
121
164
  **Python 探测顺序**:插件配置项 → 环境变量 `ZJU_PYTHON` → DeepSeek Harness 自带 Python →
122
165
  PATH 上的 `python3` / `python` / `py -3`。
123
166
 
@@ -144,24 +187,25 @@ PATH 上的 `python3` / `python` / `py -3`。
144
187
 
145
188
  ## 3. 工具与开关分层
146
189
 
147
- v2.0.1 起,「字幕 → 讲义 → PDF」主链路与所有可选能力解耦。每个模块有自己的工具、
148
- Skill 附录和系统提示;关掉就**不存在**,不占工具列表、不读登录态、不加载代码。
190
+ v2.0.1 起,「字幕 → 讲义 → PDF」主链路与投影、填空笔记等可选能力解耦;可选工具按开关注册。
191
+ 字幕鉴权与一键登录是核心链路的一部分:先匿名,401/403 后自动读取本机登录态,仍失败就由 `zju_login`
192
+ 打开独立登录窗口;登录辅助开关只控制两个可选辅助工具。
149
193
 
150
194
  | 分层 | 工具 | 依赖 | 默认 |
151
195
  | :--- | :--- | :--- | :--- |
152
- | **字幕主链路** | `zju_parse_url` / `zju_fetch_transcript` / `zju_extract_courseware` / `zju_check_note` / `zju_write_note`(含自动 PDF) / `zju_doctor` | 公开字幕接口 + 本地文件 + 可选 Typst | 始终开启 |
196
+ | **字幕主链路** | `zju_parse_url` / `zju_fetch_transcript` / `zju_extract_courseware` / `zju_check_note` / `zju_write_note`(含自动 PDF) / `zju_login` / `zju_doctor` | 字幕接口(先匿名,401/403 自动用本机登录态)+ 一键登录窗口 + 本地文件 + 可选 Typst | 始终开启 |
153
197
  | **填空笔记** | `zju_build_study_notes` + `scholia-notes` Skill | 本机 Typst | 关闭(`enableStudyNotes`) |
154
198
  | **投影抓取** | `zju_fetch_slides` | 登录态 + 截图下载 + PDF 合成 | 关闭(`enableSlides`) |
155
199
  | **投影插图** | (`zju_fetch_slides` 的子开关) | 依赖投影抓取 | 关闭(`embedSlideImages`) |
156
- | **登录辅助** | `zju_get_video_url` / `zju_read_browser_cookie` | 本机 Edge 或 `ZJU_COOKIE` / `ZJU_COOKIE_FILE` | 关闭(`enableLoginTools`) |
200
+ | **登录辅助** | `zju_get_video_url` / `zju_read_browser_cookie`;不影响字幕鉴权与 `zju_login` | 内存缓存 / `ZJU_COOKIE` / `ZJU_COOKIE_FILE` / 本机 Edge | 关闭(`enableLoginTools`) |
157
201
 
158
- - dsh 默认注册 **6** 个工具;`enableStudyNotes` +1、`enableSlides` +1、`enableLoginTools` +2,
159
- 全开 **10** 个。
202
+ - dsh 默认注册 **7** 个工具;`enableStudyNotes` +1、`enableSlides` +1、`enableLoginTools` +2,
203
+ 全开 **11** 个。
160
204
  - **`.volatile()` 字段是引用,不是布尔值**:dsh 把它们投影成 `{ get() }`,供插件在设置改动后
161
205
  读取新值。`lib/index.js` 的 `readSetting()` 统一解包;直接写 `config.enableSlides === true`
162
206
  会永远得到 `false`——2.1.1 修的「设置全开仍只有字幕」就是这个原因。新增设置项时务必走
163
207
  `readSetting()`,并补一条 ref 形状的测试。
164
- - MCP 未设置新变量时保持旧行为(10 个);仓库自带的 `zju-lecture.mcp.json` 默认关掉三个可选模块(6 个)。
208
+ - MCP 未设置新变量时保持旧行为(11 个);仓库自带的 `zju-lecture.mcp.json` 默认关掉三个可选模块(7 个)。
165
209
  - 关闭时:不注册对应工具、不加载对应模块、Skill 不追加对应附录;系统提示会说明
166
210
  「这个模块已关闭」,Agent 不会调用或假装调用。
167
211
  - 实现上,`lib/index.js` 用 `registerableTools()` 过滤;`mcp_server.available_tools()`
@@ -169,8 +213,19 @@ Skill 附录和系统提示;关掉就**不存在**,不占工具列表、不
169
213
  - `zju_lecture/__init__.py` 用 PEP 562 懒导出 `download_slides` / `build_slides_pdf` / `SlideError`;
170
214
  `mcp_server.py` 只在进入 `zju_fetch_slides` 分支时才导入 `zju_lecture.slides`
171
215
  (纯字幕进程的 `sys.modules` 里不会出现截图模块,有子进程测试守住)。
172
- - dsh 单独把 `zju_fetch_slides` 的超时提高到 600s(下载整节课截图用),其他工具仍用配置值。
216
+ - dsh 单独把 `zju_fetch_slides` / `zju_login` 的超时提高到 600s(下载截图 / 等待用户登录),
217
+ 其他工具仍用配置值。
173
218
  - 投影抓取与填空笔记互不依赖;登录辅助也与投影抓取解耦——投影工具会自己解析登录态。
219
+ - 投影截图默认下载到 `<工作区>/ppt-assets/<sub_id>/`(已 gitignore),Agent 挑 **3–8 张**
220
+ 关键页引用进讲义;接口没有文字层 / OCR,需要幻灯片原文时走 `zju_extract_courseware`。
221
+ - 登录辅助默认关闭(dsh `enableLoginTools=false`),只影响视频直链与读 Cookie 工具,不影响字幕。
222
+ `zju_login` 是核心工具,始终注册;字幕鉴权由字幕工具内部自动完成,不需模型先调读 Cookie 工具,
223
+ 也不新增工具或凭据参数。
224
+ - 三个用户命令:
225
+ - `zju-lecture-summarizer-help` 做 401/403、代理与依赖排查;
226
+ - `zju-lecture-summarizer-login` 只做「打开登录窗口 / 清除登录态」;
227
+ - `scholia-notes` 只在 `enableStudyNotes` 打开时进入模型技能目录。
228
+ 两个命令 Skill 都是 `userInvocable: true` / `modelInvocable: false`,不干扰正常的讲义生成。
174
229
 
175
230
  ### 环境变量
176
231
 
@@ -179,13 +234,15 @@ Skill 附录和系统提示;关掉就**不存在**,不占工具列表、不
179
234
  | `ZJU_PYTHON` | 指定 Python 解释器 |
180
235
  | `ZJU_WORKSPACE` | 相对路径的解析根;dsh 插件自动传入 session workspace |
181
236
  | `ZJU_BACKUP_DIR` | `zju_check_note` / `zju_write_note` 的备份目录(默认系统临时目录) |
182
- | `ZJU_COOKIE` / `ZJU_COOKIE_FILE` | 登录态(仅投影 / 视频直链需要) |
237
+ | `ZJU_COOKIE` / `ZJU_COOKIE_FILE` | 显式本机登录态(优先级最高);存在且损坏时会挡住 `zju_login`,字幕仅在 HTTP 401/403 后自动使用 |
238
+ | `ZJU_LOGIN_DIR` | `zju_login` 保存登录态与独立浏览器 profile 的目录(默认用户状态目录) |
239
+ | `ZJU_BROWSER_BIN` | 指定登录窗口使用的浏览器可执行文件(默认 Edge → Chrome → Chromium) |
183
240
  | `ZJU_RENDER_PDF` | 默认 `0`(MCP);对应 dsh `renderPdf`(默认开) |
184
241
  | `ZJU_TYPST_AUTO_INSTALL` | 缺 Typst 时自动下载安装(默认 `1`;dsh 对应 `typstAutoInstall`) |
185
242
  | `ZJU_TYPST_BIN` | 指定已有 Typst 可执行文件(优先级最高) |
186
243
  | `ZJU_TYPST_MIRROR` | Typst 下载 URL 的镜像前缀,例如 `https://ghfast.top/` |
187
244
  | `ZJU_TYPST_CACHE` | 覆盖 Typst 缓存目录(默认用户缓存;测试与换盘时用) |
188
- | `ZJU_ENABLE_STUDY_NOTES` / `ZJU_ENABLE_SLIDES` / `ZJU_EMBED_SLIDES` / `ZJU_ENABLE_LOGIN_TOOLS` | 可选模块开关 |
245
+ | `ZJU_ENABLE_STUDY_NOTES` / `ZJU_ENABLE_SLIDES` / `ZJU_EMBED_SLIDES` / `ZJU_ENABLE_LOGIN_TOOLS` | 可选模块开关;最后一项只控制登录辅助工具,字幕鉴权不受影响 |
189
246
  | `ZJU_ALLOW_SENSITIVE_PATHS` | 显式关闭本地敏感路径保护(不推荐) |
190
247
 
191
248
  相对路径解析顺序:绝对路径 → `ZJU_WORKSPACE` → `PWD` → 服务进程 cwd;都找不到时,
@@ -259,11 +316,20 @@ Skill 附录和系统提示;关掉就**不存在**,不占工具列表、不
259
316
 
260
317
  **标记块的边界**:框类装置与 `[证明]` 是「块」而不是「一行」——从标记行一直收到
261
318
  下一个标记行 / 标题 / 整行粗体的伪标题(`**周期函数的处理** \`[00:22]\``)。
262
- 块内的空行是段落分隔,`$$…$$`、列表、表格都留在装置里;`_render_block_sequence()`
319
+ 另有五种「作者显然在开新块」的结构也会收尾:引用 / 提示块(`>`)、
320
+ 以 `⚠` 开头的提醒段(qed 因此落在推导的最后一条公式之后,而不是列表末尾)、
321
+ 粗体小标题 + 冒号(可带时间码,如 `**矛盾从哪里来** \`[00:05]\`:…`;例题四段式的
322
+ `**题目**` / `**切入点**` / `**关键步骤**` / `**易错点**` 除外)、
323
+ 没加粗的「短引导词 + 时间码 + 冒号」(`推导要点 \`[00:43]\`:…`;`[证明]` 块除外,
324
+ 避免把证明截成两半),以及未知的中文标记
325
+ (如 `[推导]`:按 `[证明]` 的 Proof 样式兜底,斜体 `Proof.` + 块末 qed,不套框;
326
+ 其余未知标记排成加粗小标题)。块内的空行是段落分隔,
327
+ `$$…$$`、列表、表格都留在装置里;`_render_block_sequence()`
263
328
  负责把它们排成装置内容(块内段落不加 `#h(2em)`)。单段装置(`[直觉]` / `[练习]` /
264
329
  `[边注]` / `[强调]` …)仍只吃标记行那一句。
265
- 这条规则同时修掉两个实地问题:定理陈述里的块级公式被甩到框外;`[证明]` 遇到空行就
266
- 收尾,qed 方块停在一两行之后,读起来像「证明到这就结束了」。两条链路(
330
+ 这条规则同时修掉三个实地问题:定理陈述里的块级公式被甩到框外;`[证明]` 遇到空行就
331
+ 收尾,qed 方块停在一两行之后,读起来像「证明到这就结束了」;框一直收到下一个标题,
332
+ 把后续讲解、提示块和结论整段吞进框里。两条链路(
267
333
  `handout.py` 与 `study_notes.py`)用同一套口径;块内段落仍计入「方框:正文」的分母,
268
334
  避免比例检查误报。
269
335
 
@@ -345,6 +411,9 @@ Skill 附录和系统提示;关掉就**不存在**,不占工具列表、不
345
411
  `$1/r$` 不再把行距顶高,不必手改成 `r^{-1}`。
346
412
  - Markdown 的 `>` 引用块 → `#quoted[…]`(左侧细线 + 灰色小字)。Typst **没有** `>`
347
413
  引用语法,旧实现把 `>` 原样印进 PDF;多条 `> **字段**:…` 按行换行,不再粘成一句。
414
+ - `> [!IMPORTANT]`(GitHub alert)不再套方框,两条链路都渲染成 `#keypoint[…]`:
415
+ 取自规范的蓝色(`palette.thm` / `#33609B`)无框文字段落,标签「重点」加粗;
416
+ 其余 alert 类型(注意 / 说明 / 提示)在阅读版仍走提示块,填空版退化成带标签的灰色引用。
348
417
  - 方框预算按**最小**小节统计:`## 二、分章详解` 下挂 7 个 `### 2.x` 时逐 `2.x` 计数,
349
418
  不会把整章的框算到同一节。
350
419
  - GFM 表格 / `- ` 与 `1.` 列表 / 行内反引号在 `render_typst` 里有对应分支:表格 → `#table(…)`、
@@ -386,40 +455,70 @@ python tools/check_note.py --fix 讲义.md # 自动修正机械问题
386
455
 
387
456
  ### Cookie 从哪里来、到哪里去
388
457
 
389
- 1. 来源只有本地:内存缓存 → `ZJU_COOKIE` → `ZJU_COOKIE_FILE` → 本机 Edge;
458
+ 1. 来源只有本地:内存缓存 → `ZJU_COOKIE` → `ZJU_COOKIE_FILE` → `zju_login` 保存的登录态 → 本机 Edge;
390
459
  2. 校验:拒绝换行(HTTP 头注入)、空 name、超长;不合法只返回原因,不回显内容;
391
- 3. 使用:只放进发往 `classroom.zju.edu.cn` 的请求头;跨域重定向拒绝;
392
- 4. 缓存:仅 Python 子进程内存;
393
- 5. 回显:没有;工具 schema 中没有 cookie / reveal / domain 参数;
394
- 6. 日志:所有 stdout / stderr 经过 `SecretRedactor`;
460
+ 3. 使用:字幕先匿名,仅 HTTP 401/403 后自动读取本地登录态、解析 Bearer 重试一次;
461
+ 字幕不发 Cookie 头,Bearer 仅发往 `classroom.zju.edu.cn`,课堂 API 跨域重定向拒绝;投影边界见下;
462
+ 4. 缓存:Python 子进程内存;
463
+ 5. 回显:Cookie / 密码 / Bearer 没有;工具 schema 中没有 cookie / password / reveal / domain 参数。
464
+ 签名视频直链是例外,会作为预期结果返回给调用方;
465
+ 6. 日志:MCP 工具结果、异常、JSON-RPC 输出以及 Python `_log()` 经过 `SecretRedactor`;
466
+ 依赖模块直接写 stderr 的镜像 URL 尚未覆盖(见 [SECURITY.md](../SECURITY.md) §7.4);
395
467
  7. 临时文件:只读打开优先;必须复制时连同 `-wal` / `-shm` 一起复制(刚登录的行可能还在 WAL 里),
396
- 权限 0600,读完覆写并删除。
397
-
398
- Cookie 不是工具参数:`zju_fetch_slides` / `zju_get_video_url` 不接受 cookie 参数,
399
- `zju_read_browser_cookie` 也没有参数;登录态只能由本地配置或本机 Edge 提供。
468
+ 权限 0600,读完覆写并删除;
469
+ 8. 落盘:只有 `zju_login` 保存的登录态与独立浏览器 profile。登录态仅含 Cookie(不保存账号密码),
470
+ Windows 为 DPAPI 密文;macOS / Linux 为 **0600 权限的明文文件**。
471
+ `zju_login(clear=true)` 二者一起删除。CDP 只连接 `127.0.0.1` 随机端口,
472
+ 端口与浏览器生命周期由工具管理;端口本身没有应用层认证,见 SECURITY.md 的已知边界。
473
+
474
+ Cookie 不是正常工具参数:`zju_fetch_transcript` / `zju_fetch_slides` / `zju_get_video_url` 不接受 cookie 参数,
475
+ `zju_read_browser_cookie` 也没有参数;登录态只能由 `zju_login`、本地配置或本机 Edge 提供。
476
+ dsh 适配层目前对未声明额外字段的校验不完整,模型传入的 `cookie` / `token` / `password`
477
+ 不会被 Python 读取,但可能已进入宿主调用日志(见 [SECURITY.md](../SECURITY.md) §7.7)。
478
+ 字幕匿名成功时不读缓存、环境变量、文件或 Edge 凭据;401/403 后读不到凭据 / 遇到 ABE 时,
479
+ 调用 `zju_login` 打开独立登录窗口,不向模型索要 Cookie,也不保证关闭 Edge 能解决。
480
+ 显式配置优先:`ZJU_COOKIE` → `ZJU_COOKIE_FILE`;两者损坏都会挡住后续来源——诊断文本会明确要求先修/移除。
400
481
 
401
482
  ### 本地文件
402
483
 
403
- `zju_extract_courseware` 和 `zju_check_note` 只接受指定扩展名,并拒绝敏感文件名/目录
404
- (`.env*`、`*credential*`、`*.pem`、`Cookies`、`Login Data`、`.ssh`、`.dsh` 等)。
405
- 凭据类单词按分隔符**整词匹配**(`my-secret.txt` 拒绝、`secret sharing 第5章.md` 放行),
406
- `config.json` 这类通用名不再被拒。符号链接会先解析真实路径再判定。
407
- 确有必要时可用 `ZJU_ALLOW_SENSITIVE_PATHS=1` 显式关闭保护。
484
+ `zju_extract_courseware`、`zju_check_note` 与 `zju_build_study_notes` 的源文件读取只接受
485
+ 指定扩展名,并拒绝敏感文件名/目录(`.env*`、`*credential*`、`*.pem`、`Cookies`、
486
+ `Login Data`、`.ssh`、`.dsh` 等)。凭据类单词按分隔符**整词匹配**
487
+ (`my-secret.txt` 拒绝、`secret sharing 第5章.md` 放行),`config.json` 这类通用名不再被拒。
488
+ 符号链接会先解析真实路径再判定。确有必要时可用 `ZJU_ALLOW_SENSITIVE_PATHS=1` 显式关闭保护。
489
+
490
+ 写入边界并不完全统一:`zju_write_note`、截图输出和 PDF 工程限制在工作区;但
491
+ `zju_check_note(fix=true)` 与 `zju_build_study_notes(mode="patch")` 可以写回工作区外的
492
+ Markdown,且 `patch` 没有备份。这是待修复缺口(见 [SECURITY.md](../SECURITY.md) §7.3)。
493
+ 在修复前,只把工作区内的文件交给这两个写回分支。
408
494
 
409
495
  ### 网络
410
496
 
411
497
  - TLS 证书校验**永远不会被关闭**。信任库按 `certifi` → 随包 `cacert.pem` → 系统根证书三级回落;
412
498
  三级都不够时才失败,并返回原因 + 下一步(当前信任库、CA 张数、`HTTPS_PROXY`、该装什么)。
413
499
  - 瞬时故障(`IncompleteRead` / `SSLEOFError` / 超时 / 5xx)重试 3 次,指数退避 + 抖动;
414
- 证书校验失败**不重试**。
415
- - 跨域 302 直接拒绝,避免 `urllib` 把 `Cookie` 头重发到第三方域。
416
- - 投影截图只允许 `https://*.zju.edu.cn`;ZJU 的 `http://` 自动升级 HTTPS;
417
- Cookie 只给 ZJU 图片主机、不发 Bearer;跨主机重定向剥离凭据;写盘限制在工作区。
500
+ 证书校验失败**不重试**。字幕 HTTP 401/403 只做一次 Bearer 重试,不能循环尝试;
501
+ 区分 HTTP 状态、接口业务错误与本地凭据读取失败,不把 403 直接判为校园网限制或要求更换后端。
502
+ - 课堂 API 的 Cookie(投影 / 视频直链)与 Bearer 仅发往 `classroom.zju.edu.cn`;字幕不发 Cookie 头。
503
+ 课堂 API 的跨域 302 直接拒绝,避免 `urllib` 把 `Cookie` / `Authorization` 头重发到第三方域。
504
+ - 投影截图的**初始**地址只允许 `https://*.zju.edu.cn`;ZJU 的 `http://` 自动升级 HTTPS;
505
+ Cookie 只给 ZJU 图片主机。**当前实现仍有两个已知例外**:图片返回 401/403 时会把 Bearer
506
+ 重试到图片主机;跨主机重定向会剥离凭据,但目标没有逐跳校验,且同主机 HTTPS→HTTP
507
+ 或换端口不会剥离。由此可能形成降级泄凭据与盲 SSRF,见 [SECURITY.md](../SECURITY.md) §7.2。
508
+ 修复前应关闭投影下载,或在可信网络中只处理自己信任的课程。
509
+ - 可选的 Typst 自动安装会访问 GitHub 官方 Release,并通过 `ZJU_TYPST_MIRROR` 支持镜像;
510
+ `@preview` 包已 vendor,但底稿显式引用未 vendor 的包时仍可能访问包注册表。
418
511
 
419
512
  ### 数据会离开本机的部分
420
513
 
421
514
  字幕与课件文本会作为工具结果进入宿主模型上下文,由你选择的模型提供方处理——这是使用大模型
422
- 整理讲义的固有代价。插件本身不收集、不额外上传、不写遥测、不写用户目录。
515
+ 整理讲义的固有代价。`zju_get_video_url` 返回的签名 MP4 直链也会进入上下文,应视为短期凭证。
516
+ 插件本身不收集、不额外上传、不写遥测;除 `zju_login` 保存的本机登录态、独立浏览器 profile
517
+ (可用 `clear=true` 删除)、Typst 缓存与讲义/备份文件外,不写用户目录。
518
+
519
+ 自动修复备份默认位于系统临时目录的 `zju-lecture-backups/`,可用 `ZJU_BACKUP_DIR` 指定;
520
+ 在 POSIX 多用户机器上当前权限和可预测路径尚不安全(见 [SECURITY.md](../SECURITY.md) §7.6)。
521
+ `ZJU_TYPST_MIRROR` 不应包含凭据,`zju_doctor` 目前会原样显示它(§7.4)。
423
522
 
424
523
  ### 可机器验证
425
524
 
@@ -447,7 +546,7 @@ python tools/sync_palette.py --check # 只校验配色三处一致
447
546
  node tests/bridge_smoke.mjs # 端到端:拉起 Python 核心并调用一次工具
448
547
  node tests/bridge_error_smoke.mjs # 端到端:确认 MCP 的 isError 会冒泡成异常
449
548
  node tests/bridge_workspace_smoke.mjs # 端到端:相对路径按 session workspace 解析
450
- node tests/plugin_apply_smoke.mjs # 插件形态:默认 6 工具 / 打开后 10 工具
549
+ node tests/plugin_apply_smoke.mjs # 插件形态:默认 7 工具 / 打开后 11 工具
451
550
  node tests/client_settings_smoke.mjs # 设置页行注册与写字段
452
551
  python tools/refresh_ca_bundle.py --check # 检查随包 CA 是否完整(≥50 张根证书)
453
552
  python tools/smoke_test.py --sub-id <sub_id> # 对已安装包跑端到端冒烟(--dir 可指定包目录)
@@ -461,8 +560,13 @@ Cookie 不回显与错误 redaction、敏感本地文件拒绝、TLS 不降级
461
560
  讲义公式规范检查与自动修复、隐私扫描器自测、review 批次回归
462
561
  (行内代码不被改写、修复前备份、DOCX 段落保留、`chunked`/`json` 截断、切片时长、
463
562
  Cookie WAL 回放、ABE 探测、PDF 报错带解释器路径、bridge 超时语义、系统提示适用范围)、
563
+ 登录态安全存储 / Cookie 域过滤 / 登录 URL 白名单 / 失效清除 / `zju_login(clear=true)`、
464
564
  阅读版 PDF 的标记装置与真实编译、配色三处一致与字体可再分发性、填空笔记链路。
465
565
 
566
+ > 测试覆盖的是当前已实现行为,不等于安全审计结论。2026-11-06 的审查仍确认了
567
+ > 并发工作区、截图重定向、外部回写、镜像脱敏、隐私扫描与备份权限等待修复缺口,
568
+ > 清单见 [SECURITY.md](../SECURITY.md) 第 7 节。
569
+
466
570
  > 测试中的 `subprocess` / 管道 / 临时文件在受限沙箱里可能被拒绝;这是环境限制,不是插件缺陷。
467
571
 
468
572
  ## 10. 发布流程
@@ -484,7 +588,7 @@ npm view dsh-zju-lecture-note version # 验证
484
588
 
485
589
  - `package.json` 的 `prepublishOnly` 已挂「全量测试 + 隐私扫描」,测试红了发不出去。
486
590
  - registry 必须是 `https://registry.npmjs.org/`:国内镜像只读,`npm publish` 会 403。
487
- - 版本号不能覆盖:每次发布前必须 bump(六处对齐,见下节)。
591
+ - 版本号不能覆盖:每次发布前必须 bump(八处对齐,见下节)。
488
592
  - 发布后用户安装:`dsh plugin --profile desktop add dsh-zju-lecture-note`。
489
593
 
490
594
  `files` 字段是逐文件枚举的运行时清单(`lib/`、`mcp_server.py`、`zju_lecture/*.py`、`skills/`、
@@ -501,8 +605,8 @@ dsh 按 `peerDependencies` 校验运行时版本。若升级 dsh 后插件被跳
501
605
 
502
606
  ### 版本号
503
607
 
504
- 版本在**六处**对齐:`package.json`、`pyproject.toml`、`mcp_server.SERVER_VERSION`、
505
- `.minimax-plugin/plugin.json`、两个 Skill manifest(由 `tools/build_skill_manifest.py` 生成)。
608
+ 版本在**八处**对齐:`package.json`、`pyproject.toml`、`mcp_server.SERVER_VERSION`、
609
+ `.minimax-plugin/plugin.json`、四个 Skill manifest(由 `tools/build_skill_manifest.py` 生成)。
506
610
  `tests/test_dsh_plugin.py` 会断言。
507
611
 
508
612
  ### 插件市场条目
@@ -532,13 +636,17 @@ PY
532
636
  - **阅读版 PDF 的失败是软失败**:Markdown 照常写入,只返回 `PDF 跳过`;`zju_doctor` 能说明缺什么。
533
637
  - **字体覆盖的边界**:填空笔记的 `fonts:` 参数改不到 `note` / `sidenote` / `label-it`
534
638
  (上游包内直接读 `default-fonts`);随包字体通过 `cjk` 角色进入正文,已能覆盖绝大多数中文。
535
- - **网络依赖**:离线时字幕抓取、讲义写入、填空笔记编译(已 vendor 包与字体)都可用;
536
- 只有「首次安装 Typst」需要网络。
639
+ - **网络依赖**:字幕抓取需要网络,部分课程还需要本机登录态;讲义写入、填空笔记编译
640
+ (已 vendor 包与字体)可在本地完成,但首次安装 Typst 仍需要网络。
537
641
  - **投影截图没有文字层 / OCR**:接口只返回图片。需要幻灯片原文时让用户提供 `.pptx` 走
538
642
  `zju_extract_courseware`;模型不能看图时 Agent 只列截图索引,不臆造内容。
539
- - **Edge 登录态的两条死路**:Chromium 对 Cookie 数据库加独占锁;Edge 127+ 若启用应用绑定加密(ABE),
540
- v20 Cookie 连 DPAPI 也解不开。插件会读 `Local State` 判定 ABE 并直接指向 `ZJU_COOKIE_FILE`;
541
- 读库兜底复制会带上 `-wal` / `-shm` 并让 SQLite 回放 WAL。
643
+ - **Edge 登录态不再是唯一来源**:Chromium 对 Cookie 数据库加独占锁;Edge 127+ 若启用应用绑定加密(ABE),
644
+ v20 Cookie 连 DPAPI 也解不开。插件会读 `Local State` 判定 ABE,但不再把它当死路——
645
+ 推荐动作改为 `zju_login`(独立 profile + 浏览器进程内取 Cookie,与 ABE 无关)。
646
+ 读库兜底仍会带上 `-wal` / `-shm` 并让 SQLite 回放 WAL。
647
+ - **`zju_login` 的边界**:需要图形界面与允许本机远程调试的浏览器;企业策略 / 安全软件拦截时返回
648
+ `devtools_blocked`,无图形界面的服务器返回 `no_browser` 或启动失败,此时才用 `ZJU_COOKIE_FILE`。
649
+ 它不会读日常 Edge profile,也不会接收账号密码。
542
650
  - **PDF 课件**需要可选依赖 `pypdf`(`pip install pypdf`);其余格式零依赖。
543
651
  - **SSL / 代理**:信任库三级回落,真正会失败的是**代理做了 HTTPS 解密**或**系统时间偏差过大**;
544
652
  错误消息会给出当前信任库、CA 张数、代理环境变量与具体修法。插件不会关闭证书校验。
@@ -550,7 +658,7 @@ PY
550
658
  用 `python tools/privacy_scan.py --history` 检查,必要时重写历史并轮换凭证。
551
659
  - **形态别选错**:`tools/build_plugin.py` 产出的是 **MCode 插件包**;装进 dsh 用的是本仓库根目录的
552
660
  npm 包(`dsh plugin ... add`)。两者是两套安装方式,不要混。
553
- - **字幕接口公开,但请遵守平台条款**:一次一节课,不要批量抓取。
661
+ - **字幕可能需登录,请遵守平台条款**:只抓本人有权访问的回放,一次一节课,不要批量抓取。
554
662
 
555
663
  ## 12. 上游与归属
556
664
 
package/lib/client.js CHANGED
@@ -54,7 +54,7 @@ window.__ModuleLoader__.load({
54
54
  eyebrow: 'ZJU · CLASSROOM',
55
55
  heroTitle: 'Turn a replay into notes you actually re-read',
56
56
  heroBody:
57
- 'The transcript path is public and needs no login. The PDF is typeset locally — no extra model tokens.',
57
+ 'Transcripts are anonymous first; on 401/403 the plugin retries once with your local login. The PDF is typeset locally.',
58
58
  pipelineTranscript: 'Transcript',
59
59
  pipelineNotes: 'Markdown notes',
60
60
  pipelinePdf: 'Reading PDF',
@@ -73,9 +73,9 @@ window.__ModuleLoader__.load({
73
73
  coreTitle: 'Core pipeline',
74
74
  coreBadge: 'Always on',
75
75
  coreBody:
76
- 'Transcript fetch, local courseware, note writing and linting. These tools stay registered; they never read a browser cookie.',
76
+ 'Transcript fetch, local courseware, note writing, linting and one-click login stay registered. On 401/403, transcript tools read your local login automatically; if none is usable, the agent can open a separate login window with zju_login.',
77
77
  coreRowTitle: 'Transcript → notes → linting',
78
- coreRowHint: 'Public transcript API + local files. No login required.',
78
+ coreRowHint: 'Anonymous first; on 401/403, one retry with local login. If that fails, ask the agent to log in: a separate browser window opens, you sign in normally, and it closes by itself.',
79
79
  outputBody: 'Markdown is the source; the PDF is a typeset reading copy.',
80
80
  outputTitle: 'Reading output',
81
81
  outputBadge: 'Recommended',
@@ -110,11 +110,11 @@ window.__ModuleLoader__.load({
110
110
  imagesTitle: 'Reference screenshots in notes',
111
111
  imagesHint:
112
112
  'Only applies while projected-slide capture is on. Adds download time and vision tokens.',
113
- loginTitle2: 'Video URL and Edge cookie helpers',
113
+ loginTitle2: 'Video URL and credential tools',
114
114
  loginBody:
115
- 'Only needed for video download or Whisper; slide capture resolves its own login.',
115
+ 'Signing in is always available: type /zju-lecture-summarizer-login or ask the agent to log in to ZJU Classroom. It opens a separate browser window, never your daily Edge profile, so App-Bound Encryption does not matter; the login is saved securely on this machine (DPAPI on Windows; 0600 on macOS/Linux) (no password).',
116
116
  loginHint:
117
- 'Registers zju_get_video_url and zju_read_browser_cookie. Never echoes a cookie.',
117
+ 'The switches below only add zju_get_video_url and zju_read_browser_cookie; they never echo credentials. zju_login is a core tool and ignores this switch.',
118
118
  toolsNowHint:
119
119
  'Saved immediately, but loaded when DeepSeek Harness restarts: the running host keeps the tools it started with, and a new session inherits them.',
120
120
  saveIdle: '',
@@ -138,7 +138,7 @@ window.__ModuleLoader__.load({
138
138
  eyebrow: 'ZJU · 智云课堂',
139
139
  heroTitle: '把一节回放,变成会重读的讲义',
140
140
  heroBody:
141
- '字幕链路公开免登录;PDF 在本地排版,不额外消耗模型 token。',
141
+ '字幕先匿名;401/403 时自动用本机登录态重试一次。PDF 在本地排版,不额外消耗模型 token。',
142
142
  pipelineTranscript: '字幕',
143
143
  pipelineNotes: 'Markdown 讲义',
144
144
  pipelinePdf: '阅读 PDF',
@@ -157,9 +157,9 @@ window.__ModuleLoader__.load({
157
157
  coreTitle: '核心链路',
158
158
  coreBadge: '始终开启',
159
159
  coreBody:
160
- '字幕抓取、本地课件、讲义写入与校验。这些工具常驻,但从不读取浏览器登录态。',
160
+ '字幕抓取、本地课件、讲义写入、校验与一键登录常驻;401/403 时字幕工具自动读取本机登录态,仍不可用就由 Agent 调用 zju_login 打开独立登录窗口。',
161
161
  coreRowTitle: '字幕 → 讲义 → 校验',
162
- coreRowHint: '公开字幕接口 + 本地文件,无需登录态。',
162
+ coreRowHint: '先匿名;401/403 时自动用本机登录态重试一次。仍失败就让 Agent 登录:会弹出一个独立窗口,你正常登录后它自动关闭并安全保存登录态。',
163
163
  outputBody: 'Markdown 是源文件;PDF 是同一份内容的排版阅读版。',
164
164
  outputTitle: '阅读输出',
165
165
  outputBadge: '推荐',
@@ -191,10 +191,11 @@ window.__ModuleLoader__.load({
191
191
  imagesTitle: '把截图引用进讲义',
192
192
  imagesHint:
193
193
  '仅在投影抓取开启时生效;会增加下载时间与视觉 token。',
194
- loginTitle2: '视频直链与 Edge 登录态',
195
- loginBody: '只在下载视频或 Whisper 重识别时需要;投影抓取不依赖它。',
194
+ loginTitle2: '视频直链与登录态工具',
195
+ loginBody:
196
+ '登录入口始终可用:在对话里输入 /zju-lecture-summarizer-login,或直接说「登录智云课堂」。插件会打开一个独立的浏览器窗口(不碰你日常 Edge,ABE 不影响),你正常登录后窗口自动关闭,登录态安全保存在本机,不保存账号密码。',
196
197
  loginHint:
197
- '注册 zju_get_video_url 与 zju_read_browser_cookie;不会回显 Cookie。',
198
+ '下面的开关只额外注册 zju_get_video_url 与 zju_read_browser_cookie,不回显凭据;zju_login 是核心工具,不受本开关影响。',
198
199
  toolsNowHint: '保存后立即写回,但插件要完全重启 DeepSeek Harness 才按新配置加载:当前会话和新建会话都沿用启动时的工具集。',
199
200
  saveIdle: '',
200
201
  saveSaving: '正在保存…',
@@ -487,7 +488,7 @@ window.__ModuleLoader__.load({
487
488
  const embedSlideImages = enableSlides && value.embedSlideImages === true
488
489
  const ready = snapshot.status === 'ready'
489
490
  const disabled = !ready || !snapshot.writable || saveState === 'saving'
490
- const toolCount = 6
491
+ const toolCount = 7
491
492
  + (enableStudyNotes ? 1 : 0)
492
493
  + (enableSlides ? 1 : 0)
493
494
  + (enableLoginTools ? 2 : 0)
package/lib/index.js CHANGED
@@ -5,13 +5,14 @@
5
5
  * 以语音字幕 + 本地课件为主链路;投影 PPT 截图是可选模块,由 `enableSlides` 开关。
6
6
  * 产出带时间戳、公式可渲染的讲义。
7
7
  *
8
- * 实现方式:插件最多注册 10 个原生 dsh 工具(默认只注册 6 个核心工具,可选模块按设置打开),
8
+ * 实现方式:插件最多注册 11 个原生 dsh 工具(默认只注册 7 个核心工具,可选模块按设置打开),
9
9
  * 内部复用随包分发的 Python 核心(与 MCP 插件同一份 mcp_server.py),
10
10
  * 通过 JSON-RPC over stdio 调用,保证「MCP 插件」与「dsh 插件」的行为完全一致。
11
11
  *
12
- * 隐私约定:插件自身不写用户目录、不收集遥测、不回显 Cookie;随包 Skill
13
- * 通过 dsh 的技能注册表**在内存中**注册,而不是复制到 $DSH_HOME/skills,
14
- * 因此安装/卸载都不会在本机留下数据副本。
12
+ * 隐私约定:插件不回显 Cookie、不收集遥测;`zju_login` 只在本机用户状态目录
13
+ * 安全保存登录态与独立登录窗口配置(Windows DPAPI;macOS / Linux 0600),
14
+ * 可用 `zju_login(clear=true)` 一并删除;随包 Skill 通过 dsh 的技能注册表
15
+ * **在内存中**注册,而不是复制到 $DSH_HOME/skills。
15
16
  */
16
17
 
17
18
  import { createHash } from "node:crypto";
@@ -81,6 +82,8 @@ const name = "dsh-zju-lecture-note";
81
82
  const PLUGIN_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
82
83
 
83
84
  const SKILL_NAME = "zju-lecture-summarizer";
85
+ const HELP_SKILL_NAME = "zju-lecture-summarizer-help";
86
+ const LOGIN_SKILL_NAME = "zju-lecture-summarizer-login";
84
87
 
85
88
  /**
86
89
  * The projection appendix of the transcript skill.
@@ -99,6 +102,13 @@ const SLIDES_SKILL_FILE = join(PLUGIN_ROOT, "skills", SKILL_NAME, "SLIDES.md");
99
102
  * transcript-only session never sees instructions for a tool that was not
100
103
  * registered.
101
104
  *
105
+ * `zju-lecture-summarizer-help` is a user-invocable troubleshooting SOP for
106
+ * login / 401/403 / dependency questions. It is deliberately not advertised to
107
+ * the model so it cannot displace the main note-writing skill.
108
+ * `zju-lecture-summarizer-login` is the one-command login window: it invokes `zju_login`
109
+ * and nothing else, so a user can refresh the local login without starting a
110
+ * note task.
111
+ *
102
112
  * `scholia-notes` is the fill-in study-note workflow: it turns a lecture note
103
113
  * into a Typst notebook with blanks (see `zju_build_study_notes`). It has no
104
114
  * appendix and no feature gate.
@@ -110,6 +120,20 @@ const SKILL_SPECS = [
110
120
  when: "always",
111
121
  appendices: [{ path: SLIDES_SKILL_FILE, when: "slides" }],
112
122
  },
123
+ {
124
+ name: HELP_SKILL_NAME,
125
+ fallbackDescription: "登录辅助与故障排查(不读取/回显凭据)",
126
+ when: "always",
127
+ appendices: [],
128
+ invocation: { modelInvocable: false, userInvocable: true },
129
+ },
130
+ {
131
+ name: LOGIN_SKILL_NAME,
132
+ fallbackDescription: "打开独立登录窗口,保存本机登录态",
133
+ when: "always",
134
+ appendices: [],
135
+ invocation: { modelInvocable: false, userInvocable: true },
136
+ },
113
137
  {
114
138
  name: "scholia-notes",
115
139
  fallbackDescription: "把 STEM 讲义排成填空式学习笔记(Typst → PDF)",
@@ -145,8 +169,8 @@ const Config = Schema.object({
145
169
  enableSlides: Schema.boolean()
146
170
  .description(
147
171
  "启用「PPT 投影抓取」可选模块(默认关闭):开启后注册 zju_fetch_slides,"
148
- + "可从课堂回放抓取投影截图并合成 PDF。关闭时插件只走「语音字幕 + 本地课件」链路,"
149
- + "不注册投影工具、不读取浏览器登录态、不下载截图;字幕接口本身公开免登录。",
172
+ + "可从课堂回放抓取投影截图并合成 PDF。关闭时不注册投影工具、不下载截图;"
173
+ + "字幕鉴权由核心链路自动完成,与投影独立。",
150
174
  )
151
175
  .default(false)
152
176
  .volatile(),
@@ -158,9 +182,9 @@ const Config = Schema.object({
158
182
  .volatile(),
159
183
  enableLoginTools: Schema.boolean()
160
184
  .description(
161
- "启用登录辅助工具(默认关闭):zju_get_video_url 解析视频直链、"
162
- + "zju_read_browser_cookie 读取本机 Edge 登录态。投影抓取会自行解析登录态,"
163
- + "不依赖这两个工具;只有需要下载视频或 Whisper 重识别时才打开。",
185
+ "启用登录辅助工具(默认关闭):注册 zju_get_video_url 解析视频直链、"
186
+ + "zju_read_browser_cookie 读取本机 Edge 登录态。字幕鉴权与一键登录窗口"
187
+ + "(zju_login)都属于核心链路,不受本开关影响;投影抓取也独立解析登录态。",
164
188
  )
165
189
  .default(false)
166
190
  .volatile(),
@@ -254,7 +278,8 @@ const SYSTEM_PROMPT = [
254
278
  "用户只说「整理这节课」时按完整链路一次做完,不要只交字幕摘要;只有明确说「只要速记 / 只要 Markdown」时才省略这些增强内容。",
255
279
  "ASR 可靠度低时按 Skill 的数学规范复算,并在讲义开头写明需要人工复核的时间点;公式必须符合 Skill 的「公式书写规范」。",
256
280
  "交付时给出 Markdown 路径;有 PDF 时一并给出 PDF 路径。不要声称看过自己无法查看的图片。",
257
- "隐私边界:登录 Cookie 只在 Python 进程内存里,工具不接受、也不回显 Cookie 明文;不要向用户索要 Cookie,或把它写进对话、文件、命令。",
281
+ "隐私边界:登录态只在本机安全保存或进程内存中使用;工具不接受、也不回显 Cookie / 密码 / token 明文;不要向用户索要 Cookie,或把它写进对话、文件、命令。",
282
+ "字幕先匿名;401/403 时先自动使用本机登录态;仍失败就调用 zju_login(url=<这节课链接>) 打开独立登录窗口,让用户在窗口里正常登录(成功后自动关闭并安全保存),然后重试字幕一次。不要让用户开开发者工具、手工配置 Cookie 文件,也不要把 401/403 直接归因校园网。",
258
283
  ].join("\n");
259
284
 
260
285
  /**
@@ -285,9 +310,9 @@ function slideImageRule(enabled) {
285
310
  function slidesFeatureRule(enableSlides, embedSlideImages) {
286
311
  if (!enableSlides) {
287
312
  return "PPT 投影抓取已关闭(插件设置 enableSlides=false):本会话没有注册 zju_fetch_slides,"
288
- + "不要尝试抓取或引用投影截图,也不要为了投影去读取浏览器 Cookie;"
289
- + "只用语音字幕与本地课件生成讲义。用户明确要投影画面时,"
290
- + "告诉他在插件设置里打开「启用 PPT 投影抓取」后重试。";
313
+ + "不要尝试抓取或引用投影截图,也不要为了投影额外读取浏览器 Cookie;"
314
+ + "字幕鉴权由字幕工具自行处理,需要登录时用 zju_login。只用语音字幕与本地课件生成讲义。"
315
+ + "用户明确要投影画面时,告诉他在插件设置里打开「启用 PPT 投影抓取」后重试。";
291
316
  }
292
317
  return "PPT 投影抓取已开启(插件设置 enableSlides=true):" + slideImageRule(embedSlideImages);
293
318
  }
@@ -315,11 +340,16 @@ function studyFeatureRule(enabled) {
315
340
  }
316
341
 
317
342
  function loginFeatureRule(enabled) {
343
+ const core = "`zju_login` 不受本开关影响,始终可用:需要登录时调用它打开独立登录窗口,"
344
+ + "用户只需在窗口里正常登录,窗口会自动关闭并把登录态安全保存在本机;"
345
+ + "不要让用户开开发者工具、手工配置 Cookie 文件或把凭据贴进对话。"
346
+ + "字幕鉴权也不依赖本开关:先匿名,401/403 时自动读取本机登录态并用 Bearer 重试一次;"
347
+ + "仍失败就调用 zju_login,登录成功后重试字幕一次,不要反复重试、擅断校园网或更换后端。";
318
348
  return enabled
319
- ? "登录辅助工具已开启(zju_get_video_url / zju_read_browser_cookie):"
320
- + "只在确实需要视频直链或预读登录态时使用,二者都不会回显 Cookie。"
349
+ ? "登录辅助工具已开启(zju_get_video_url / zju_read_browser_cookie):仅在需要视频直链或手动检查登录态时调用,"
350
+ + "二者都不会回显 Cookie。" + core
321
351
  : "登录辅助工具已关闭(enableLoginTools=false):本会话没有注册 zju_get_video_url / "
322
- + "zju_read_browser_cookie,不要调用;投影抓取会自行解析登录态,不受影响。";
352
+ + "zju_read_browser_cookie,不要调用。" + core + "投影抓取也会自行解析登录态。";
323
353
  }
324
354
 
325
355
  /** Build the (short) task prompt for one configuration. */
@@ -351,6 +381,7 @@ const TOOL_PRESENT = {
351
381
  zju_extract_courseware: { title: "提取本地课件文本", kind: "read" },
352
382
  zju_check_note: { title: "检查/修正讲义渲染规范", kind: "edit" },
353
383
  zju_write_note: { title: "写入讲义(自动命名 + 写后校验 + PDF)", kind: "edit" },
384
+ zju_login: { title: "打开独立登录窗口(保存本机登录态)", kind: "edit" },
354
385
  zju_get_video_url: { title: "解析回放视频直链", kind: "fetch" },
355
386
  zju_read_browser_cookie: { title: "读取本机 Edge 登录态", kind: "read" },
356
387
  zju_build_study_notes: { title: "生成填空式学习笔记(Typst → PDF)", kind: "edit" },
@@ -435,14 +466,16 @@ function readBundledSkills(configOrSlides = {}) {
435
466
  const text = splitFrontmatter(readFileSync(appendixFile, "utf8")).body.trim();
436
467
  if (text) content = `${body.trimEnd()}\n\n---\n\n${text}\n`;
437
468
  }
438
- skills.push({
469
+ const descriptor = {
439
470
  name: spec.name,
440
471
  description: description || spec.fallbackDescription,
441
472
  content,
442
473
  path: file,
443
474
  source: `plugin:${name}`,
444
475
  provider: name,
445
- });
476
+ };
477
+ if (spec.invocation) descriptor.invocation = spec.invocation;
478
+ skills.push(descriptor);
446
479
  }
447
480
  return skills;
448
481
  }
@@ -551,7 +584,8 @@ function apply(ctx, config = {}) {
551
584
  || tool.name === "zju_check_note"
552
585
  || tool.name === "zju_build_study_notes"
553
586
  || tool.name === "zju_doctor";
554
- const toolTimeoutMs = tool.name === "zju_fetch_slides"
587
+ const slowTool = tool.name === "zju_fetch_slides" || tool.name === "zju_login";
588
+ const toolTimeoutMs = slowTool
555
589
  ? Math.max(timeoutMs, SLOW_TOOL_TIMEOUT_MS)
556
590
  : pdfCapable
557
591
  ? Math.max(timeoutMs, COMPILE_TOOL_TIMEOUT_MS)