dsh-zju-lecture-note 2.2.6 → 2.2.8

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
@@ -5,8 +5,9 @@
5
5
 
6
6
  ## 1. 仓库结构与数据流
7
7
 
8
- 本仓库既是插件的**能力核心**,也是 **dsh 原生插件包的发布源**:Python 核心、MCP 服务器、
9
- 讲义 Skill,以及 dsh 用的 `package.json` / `cordis.patch.yml` / `lib/` 都在这里。
8
+ 本仓库既是插件的**能力核心**,也同时是两种入口的发布源:**dsh 原生插件包**与 **Agent Plugins 1.0
9
+ 通用包**。Python 核心、MCP 服务器、讲义 Skill,以及 dsh 用的 `package.json` / `cordis.patch.yml` / `lib/`
10
+ 和通用入口用的根 `plugin.json` / `mcp.json` 都在这里。
10
11
 
11
12
  ```text
12
13
  dsh-zju-lecture-note/
@@ -18,12 +19,14 @@ dsh-zju-lecture-note/
18
19
  │ ├── client.js # 浏览器半边:设置页 + 左栏「智云讲义」入口
19
20
  │ ├── tools.js # 生成物:dsh 工具定义
20
21
  │ └── tools.schema.json # 生成物:工具定义快照(供测试比对)
21
- ├── .minimax-plugin/plugin.json # MiniMax Code(MCode)插件清单
22
- ├── zju-lecture.mcp.json # MCP 服务器定义(stdio → node ./server.mjs)
22
+ ├── plugin.json # Agent Plugins 1.0 通用入口清单(组件位置固定在 skills/ 与 mcp.json)
23
+ ├── mcp.json # Agent Plugins 1.0 的 MCP 配置(stdio → node ./server.mjs)
24
+ ├── .minimax-plugin/plugin.json # 历史打包脚本使用的清单(tools/build_plugin.py)
25
+ ├── zju-lecture.mcp.json # 历史打包脚本使用的 MCP 定义(带 description / timeout)
23
26
  ├── server.mjs # 启动器:解析 Python 解释器并拉起 MCP 服务
24
27
  ├── mcp_server.py # MCP stdio 服务器(JSON-RPC 2.0,隐私边界在这里)
25
28
  ├── zju_lecture/ # 核心库(纯标准库)
26
- │ ├── client.py # 智云课堂 API 客户端(TLS 校验 + 同域重定向)
29
+ │ ├── client.py # 智云课堂 API 客户端(TLS 校验 + origin/SSRF 重定向校验)
27
30
  │ ├── cookies.py # Edge Cookie 读取与安全清理
28
31
  │ ├── browser_login.py # 一键登录窗口:CDP 取 Cookie + 安全保存 + 清除
29
32
  │ ├── security.py # Cookie 校验 / redactor / 本地文件边界
@@ -94,11 +97,13 @@ dsh-zju-lecture-note/
94
97
  2. 浏览器打开用户给的课堂链接(仅 `https://*.zju.edu.cn`);用户在页面里完成 SSO / 2FA。
95
98
  3. 插件每 1.5s 通过 CDP `Storage.getCookies` 读取 Cookie,只保留课堂主机与
96
99
  `.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,
100
+ 4. 检测到可解析的 `_token` 后,`save_session()` 只保存 Cookie 头,并且**只交给平台凭据库**:
101
+ Windows DPAPI(`CryptProtectData`)、macOS 登录钥匙串、Linux Secret Service(`secret-tool`);
102
+ 三者都不可用或 `ZJU_LOGIN_STORAGE=memory` 时只留在进程内存,不写文件。不保存账号密码。
103
+ 2.2.7 及更早版本在 POSIX 写下的明文 `session.bin` 会在首次读取时迁移并覆写删除。
104
+ 5. 关闭浏览器并删除 `login-profile`(浏览器那份 Cookie 副本),`zju_login` 把 Cookie 放进本进程缓存;
105
+ Agent 重试字幕一次。
106
+ 6. 服务端仍返回 401/403 时,`_forget_cookie("session")` 删除凭据项、旧文件与专用 profile,
102
107
  下次 `zju_login` 从真正的登录页开始,而不是重放死 Cookie。
103
108
 
104
109
  `clear=true` 删除登录态与独立浏览器 profile;无图形界面、未安装浏览器或策略禁用远程调试时,
@@ -109,9 +114,26 @@ dsh-zju-lecture-note/
109
114
  | 形态 | 载体 | 依赖 |
110
115
  | :--- | :--- | :--- |
111
116
  | dsh 原生插件 | 仓库根目录的 npm 包(`package.json` + `cordis.patch.yml` + `lib/`) | pnpm 装 peer;Python 3.9+;Typst 由插件自举 |
112
- | 标准 MCP + Skill | `server.mjs` 拉起 stdio MCP Server | PATH 上的 `node`;Python 3.9+ |
113
- | MiniMax Code 插件包 | `tools/build_plugin.py` 产出的 `dist/*.zip` | 同上 |
114
- | 命令行 | `python -m zju_lecture.cli` | Python 3.9+;`pypdf` 仅 PDF 课件需要 |
117
+ | Agent Plugins 1.0 通用包 | 仓库根的 `plugin.json` + `mcp.json` + `skills/` + `server.mjs` | PATH 上的 `node`;Python 3.9+ |
118
+
119
+ 对外只有这两个入口。两种补充手段不算独立入口:只认裸 MCP 的宿主直接抄根 `mcp.json` 的
120
+ `mcpServers` 段(把 `./server.mjs` 换成绝对路径);命令行用 `python -m zju_lecture.cli`
121
+ (Python 3.9+,`pypdf` 仅 PDF 课件需要)。`tools/build_plugin.py` 产出的 `dist/*.zip` 是历史
122
+ 打包脚本的 staged 产物,只含它自己的清单,根 `plugin.json` / `mcp.json` 不会混进去。
123
+
124
+ **通用入口的工作目录**:Agent Plugins 1.0 规定 `cwd` 省略时客户端**必须**以插件根为子进程工作目录,
125
+ 而 `zju_lecture/paths.py` 的解析顺序是 绝对路径 → `ZJU_WORKSPACE` → `PWD` → cwd,所以相对输出路径
126
+ 会落进安装目录。根 `mcp.json` 不写死 `ZJU_WORKSPACE`(用户工作区无法静态预知),由用户给绝对路径
127
+ 或自行补 env;dsh 链路不受影响,bridge 按会话工作区传 `ZJU_WORKSPACE` 与 cwd。根 `mcp.json` 也不用
128
+ `${PLUGIN_ROOT}` / `${PLUGIN_DATA}` 占位符——部分客户端不展开它们,`./server.mjs` 配合默认 cwd
129
+ 才是跨客户端写法。
130
+
131
+ **清单 schema 是封闭的**:`plugin.schema.json` 与 `mcp.schema.json` 都是 `additionalProperties: false`。
132
+ 根 `plugin.json` 只有 `$schema` / `name` 必填,`author` 必须是对象、`repository` 必须是字符串,
133
+ 没有 `icon` / `category` / `skills` / `mcpServers` 字段(组件位置固定:Skill 从 `skills/` 的直接子目录
134
+ 发现,MCP 从根 `mcp.json` 读)。根 `mcp.json` 的 stdio 项只允许 `type` / `command` / `args` / `env` / `cwd`,
135
+ 旧 `zju-lecture.mcp.json` 里的 `schemaVersion` / `description` / `timeout` 在这份 schema 下非法,
136
+ 所以两份文件并存、各自服务自己的入口。`tests/test_agent_plugins.py` 离线守这些约束。
115
137
 
116
138
  **Typst 自举**(v2.1.0):`zju_lecture/deps.py` 把「本机没装 Typst」从静默失败变成一次可解释的准备:
117
139
 
@@ -184,6 +206,10 @@ PATH 上的 `python3` / `python` / `py -3`。
184
206
  - `main` 占的是整列页面,页首要用 `calc(20px + var(--dsh-frame-top-clearance, 0px))` 留出
185
207
  窗口标题栏的高度,否则 Windows 上第一行会被标题栏压住。
186
208
  - 面板页把标题渲染成 `h1`(`asPage`),设置弹窗里仍是 `h2`(弹窗自己提供标题)。
209
+ - 四枚预设(省 Token / 复习模式 / 投影讲义 / 全功能)只是 `PRESET_SPECS` 里的批量写入;
210
+ 不保存「当前预设」状态。高亮由 `matchingPreset(moduleState(value))` 按 6 个子开关实时比较
211
+ 得出,所以点预设与手动拨到同样位置完全等价;任一开关不同就不高亮。选中态用
212
+ `.zju-preset.is-active` 的渐变底色 + 过渡,`aria-pressed` 同步。
187
213
 
188
214
  ## 3. 工具与开关分层
189
215
 
@@ -196,15 +222,24 @@ v2.0.1 起,「字幕 → 讲义 → PDF」主链路与投影、填空笔记等
196
222
  | **字幕主链路** | `zju_parse_url` / `zju_fetch_transcript` / `zju_extract_courseware` / `zju_check_note` / `zju_write_note`(含自动 PDF) / `zju_login` / `zju_doctor` | 字幕接口(先匿名,401/403 自动用本机登录态)+ 一键登录窗口 + 本地文件 + 可选 Typst | 始终开启 |
197
223
  | **填空笔记** | `zju_build_study_notes` + `scholia-notes` Skill | 本机 Typst | 关闭(`enableStudyNotes`) |
198
224
  | **投影抓取** | `zju_fetch_slides` | 登录态 + 截图下载 + PDF 合成 | 关闭(`enableSlides`) |
199
- | **投影插图** | (`zju_fetch_slides` 的子开关) | 依赖投影抓取 | 关闭(`embedSlideImages`) |
225
+ | **投影来源** | (`slidesAsSource` 子开关) | 依赖投影抓取;写讲义前抓取并下载,把幻灯片内容与字幕对照写入 | 关闭 |
226
+ | **投影插图** | (`embedSlideImages` 子开关) | 依赖投影抓取;只决定是否插入 3–8 张关键页 | 关闭 |
200
227
  | **登录辅助** | `zju_get_video_url` / `zju_read_browser_cookie`;不影响字幕鉴权与 `zju_login` | 内存缓存 / `ZJU_COOKIE` / `ZJU_COOKIE_FILE` / 本机 Edge | 关闭(`enableLoginTools`) |
201
228
 
202
229
  - dsh 默认注册 **7** 个工具;`enableStudyNotes` +1、`enableSlides` +1、`enableLoginTools` +2,
203
- 全开 **11** 个。
230
+ 全开 **11** 个。`slidesAsSource` / `embedSlideImages` 都是投影的子开关,不新增工具。
231
+ - **所有设置项都标 `.volatile()`**:dsh 只把 volatile 字段投影进配置表单,也只有这些字段能由
232
+ 设置页写入。2.2.7 起 `python` / `timeoutMs` / `registerSkill` 以及新增的 `typstPath` /
233
+ `typstMirror` 也一并纳入,设置页才覆盖「工具、依赖、解释器」三层,而不是只有模块开关。
234
+ 2.2.8 增加 `slidesAsSource`(投影作为讲义来源),设置页共 12 个可写字段。
204
235
  - **`.volatile()` 字段是引用,不是布尔值**:dsh 把它们投影成 `{ get() }`,供插件在设置改动后
205
236
  读取新值。`lib/index.js` 的 `readSetting()` 统一解包;直接写 `config.enableSlides === true`
206
237
  会永远得到 `false`——2.1.1 修的「设置全开仍只有字幕」就是这个原因。新增设置项时务必走
207
238
  `readSetting()`,并补一条 ref 形状的测试。
239
+ - **设置热更新**:只改 volatile 字段时,dsh 不重新执行 `apply()`,而是更新引用并发出
240
+ `loader/volatile-update`。插件监听该事件后重新同步工具、Skill、系统提示词(`text` 是 thunk,
241
+ 每次组装都重新读取配置)并把已启动的 Python 子进程作废,下一次调用用新环境变量拉起。
242
+ 因此保存后 Agent 下一轮就能读到;只有安装 / 更新插件本身仍需完全重启。
208
243
  - MCP 未设置新变量时保持旧行为(11 个);仓库自带的 `zju-lecture.mcp.json` 默认关掉三个可选模块(7 个)。
209
244
  - 关闭时:不注册对应工具、不加载对应模块、Skill 不追加对应附录;系统提示会说明
210
245
  「这个模块已关闭」,Agent 不会调用或假装调用。
@@ -216,8 +251,13 @@ v2.0.1 起,「字幕 → 讲义 → PDF」主链路与投影、填空笔记等
216
251
  - dsh 单独把 `zju_fetch_slides` / `zju_login` 的超时提高到 600s(下载截图 / 等待用户登录),
217
252
  其他工具仍用配置值。
218
253
  - 投影抓取与填空笔记互不依赖;登录辅助也与投影抓取解耦——投影工具会自己解析登录态。
219
- - 投影截图默认下载到 `<工作区>/ppt-assets/<sub_id>/`(已 gitignore),Agent 挑 **3–8 张**
220
- 关键页引用进讲义;接口没有文字层 / OCR,需要幻灯片原文时走 `zju_extract_courseware`。
254
+ - 投影有三个层次:`enableSlides` 只负责注册工具;`slidesAsSource` 决定是否把幻灯片作为
255
+ 讲义内容来源(写前必须抓取并下载一次);`embedSlideImages` 只决定是否插入 3–8 张关键页。
256
+ 两个子开关都关闭时,提示词仍要求写讲义前调用一次 `download=false` 核对清单,避免
257
+ 「打开了抓取开关但模型从不调用」。系统提示、Skill 附录和工具描述三处都写明顺序。
258
+ - 投影截图默认下载到 `<工作区>/ppt-assets/<sub_id>/`(已 gitignore);接口没有文字层 / OCR,
259
+ 需要幻灯片原文时走 `zju_extract_courseware`。模型不能读图时禁止臆造幻灯片文字,
260
+ 只在文末列截图索引。
221
261
  - 登录辅助默认关闭(dsh `enableLoginTools=false`),只影响视频直链与读 Cookie 工具,不影响字幕。
222
262
  `zju_login` 是核心工具,始终注册;字幕鉴权由字幕工具内部自动完成,不需模型先调读 Cookie 工具,
223
263
  也不新增工具或凭据参数。
@@ -231,18 +271,19 @@ v2.0.1 起,「字幕 → 讲义 → PDF」主链路与投影、填空笔记等
231
271
 
232
272
  | 变量 | 作用 |
233
273
  | :--- | :--- |
234
- | `ZJU_PYTHON` | 指定 Python 解释器 |
274
+ | `ZJU_PYTHON` | 指定 Python 解释器(dsh 对应 `python`,留空走自带解释器) |
235
275
  | `ZJU_WORKSPACE` | 相对路径的解析根;dsh 插件自动传入 session workspace |
236
276
  | `ZJU_BACKUP_DIR` | `zju_check_note` / `zju_write_note` 的备份目录(默认系统临时目录) |
237
277
  | `ZJU_COOKIE` / `ZJU_COOKIE_FILE` | 显式本机登录态(优先级最高);存在且损坏时会挡住 `zju_login`,字幕仅在 HTTP 401/403 后自动使用 |
238
278
  | `ZJU_LOGIN_DIR` | `zju_login` 保存登录态与独立浏览器 profile 的目录(默认用户状态目录) |
279
+ | `ZJU_LOGIN_STORAGE` | `os`(默认,使用平台凭据库)/ `memory`(不落盘,仅进程内);没有可用凭据库时自动等价 `memory` |
239
280
  | `ZJU_BROWSER_BIN` | 指定登录窗口使用的浏览器可执行文件(默认 Edge → Chrome → Chromium) |
240
281
  | `ZJU_RENDER_PDF` | 默认 `0`(MCP);对应 dsh `renderPdf`(默认开) |
241
282
  | `ZJU_TYPST_AUTO_INSTALL` | 缺 Typst 时自动下载安装(默认 `1`;dsh 对应 `typstAutoInstall`) |
242
- | `ZJU_TYPST_BIN` | 指定已有 Typst 可执行文件(优先级最高) |
243
- | `ZJU_TYPST_MIRROR` | Typst 下载 URL 的镜像前缀,例如 `https://ghfast.top/` |
283
+ | `ZJU_TYPST_BIN` | 指定已有 Typst 可执行文件(优先级最高;dsh 对应 `typstPath`) |
284
+ | `ZJU_TYPST_MIRROR` | Typst 下载 URL 的镜像前缀,例如 `https://ghfast.top/`(dsh 对应 `typstMirror`) |
244
285
  | `ZJU_TYPST_CACHE` | 覆盖 Typst 缓存目录(默认用户缓存;测试与换盘时用) |
245
- | `ZJU_ENABLE_STUDY_NOTES` / `ZJU_ENABLE_SLIDES` / `ZJU_EMBED_SLIDES` / `ZJU_ENABLE_LOGIN_TOOLS` | 可选模块开关;最后一项只控制登录辅助工具,字幕鉴权不受影响 |
286
+ | `ZJU_ENABLE_STUDY_NOTES` / `ZJU_ENABLE_SLIDES` / `ZJU_SLIDES_SOURCE` / `ZJU_EMBED_SLIDES` / `ZJU_ENABLE_LOGIN_TOOLS` | 可选模块开关;`ZJU_SLIDES_SOURCE` 把投影作为讲义来源,`ZJU_EMBED_SLIDES` 只控制插图;最后一项只控制登录辅助工具,字幕鉴权不受影响 |
246
287
  | `ZJU_ALLOW_SENSITIVE_PATHS` | 显式关闭本地敏感路径保护(不推荐) |
247
288
 
248
289
  相对路径解析顺序:绝对路径 → `ZJU_WORKSPACE` → `PWD` → 服务进程 cwd;都找不到时,
@@ -473,18 +514,20 @@ python tools/check_note.py --fix 讲义.md # 自动修正机械问题
473
514
  5. 回显:Cookie / 密码 / Bearer 没有;工具 schema 中没有 cookie / password / reveal / domain 参数。
474
515
  签名视频直链是例外,会作为预期结果返回给调用方;
475
516
  6. 日志:MCP 工具结果、异常、JSON-RPC 输出以及 Python `_log()` 经过 `SecretRedactor`;
476
- 依赖模块直接写 stderr 的镜像 URL 尚未覆盖(见 [SECURITY.md](../SECURITY.md) §7.4);
517
+ 依赖模块的镜像 URL 先由 `deps._redact_url()` 去掉 userinfo / query / fragment,
518
+ bridge.js 转发 stderr 前再做一层 JS 脱敏(见 [SECURITY.md](../SECURITY.md) §7.4);
477
519
  7. 临时文件:只读打开优先;必须复制时连同 `-wal` / `-shm` 一起复制(刚登录的行可能还在 WAL 里),
478
- 权限 0600,读完覆写并删除;
479
- 8. 落盘:只有 `zju_login` 保存的登录态与独立浏览器 profile。登录态仅含 Cookie(不保存账号密码),
480
- Windows 为 DPAPI 密文;macOS / Linux 为 **0600 权限的明文文件**。
481
- `zju_login(clear=true)` 二者一起删除。CDP 只连接 `127.0.0.1` 随机端口,
520
+ 权限 0600,读完覆写并删除;读取前还会清理一小时前的残留副本(进程被强杀的可能遗留)。
521
+ 8. 落盘:登录态只写入平台凭据库(Windows DPAPI 密文文件 / macOS 钥匙串项 / Linux Secret Service 项,
522
+ 均为静态加密;无可用后端时只在内存)。独立浏览器 profile 在提取凭据后被删除。
523
+ `zju_login(clear=true)` 清除凭据项、旧明文文件与 profile。CDP 只连接 `127.0.0.1` 随机端口,
482
524
  端口与浏览器生命周期由工具管理;端口本身没有应用层认证,见 SECURITY.md 的已知边界。
483
525
 
484
526
  Cookie 不是正常工具参数:`zju_fetch_transcript` / `zju_fetch_slides` / `zju_get_video_url` 不接受 cookie 参数,
485
527
  `zju_read_browser_cookie` 也没有参数;登录态只能由 `zju_login`、本地配置或本机 Edge 提供。
486
- dsh 适配层目前对未声明额外字段的校验不完整,模型传入的 `cookie` / `token` / `password`
487
- 不会被 Python 读取,但可能已进入宿主调用日志(见 [SECURITY.md](../SECURITY.md) §7.7)。
528
+ dsh 0.2.x 不为工具参数生成根级封闭声明,但 `handle_tool_call` 会按
529
+ `inputSchema.properties` 拒绝未声明的字段(`未知参数: cookie`),工具不执行
530
+ (见 [SECURITY.md](../SECURITY.md) §7.7)。
488
531
  字幕匿名成功时不读缓存、环境变量、文件或 Edge 凭据;401/403 后读不到凭据 / 遇到 ABE 时,
489
532
  调用 `zju_login` 打开独立登录窗口,不向模型索要 Cookie,也不保证关闭 Edge 能解决。
490
533
  显式配置优先:`ZJU_COOKIE` → `ZJU_COOKIE_FILE`;两者损坏都会挡住后续来源——诊断文本会明确要求先修/移除。
@@ -497,10 +540,11 @@ dsh 适配层目前对未声明额外字段的校验不完整,模型传入的
497
540
  (`my-secret.txt` 拒绝、`secret sharing 第5章.md` 放行),`config.json` 这类通用名不再被拒。
498
541
  符号链接会先解析真实路径再判定。确有必要时可用 `ZJU_ALLOW_SENSITIVE_PATHS=1` 显式关闭保护。
499
542
 
500
- 写入边界并不完全统一:`zju_write_note`、截图输出和 PDF 工程限制在工作区;但
501
- `zju_check_note(fix=true)` 与 `zju_build_study_notes(mode="patch")` 可以写回工作区外的
502
- Markdown,且 `patch` 没有备份。这是待修复缺口(见 [SECURITY.md](../SECURITY.md) §7.3)。
503
- 在修复前,只把工作区内的文件交给这两个写回分支。
543
+ 写入边界统一由 `paths.require_workspace_path()` 仲裁:`zju_write_note`、截图输出与 PDF
544
+ 工程限制在工作区;`zju_check_note(fix=true)` 与 `zju_build_study_notes(mode="patch")`
545
+ 在任何情况下都拒绝工作区外目标。读取工作区外课件只有
546
+ `zju_extract_courseware(allow_outside_workspace=true)` 一个显式入口,结果首行标注
547
+ 「已读取工作区外文件」,且仍受扩展名/凭据防护(见 [SECURITY.md](../SECURITY.md) §9)。
504
548
 
505
549
  ### 网络
506
550
 
@@ -512,10 +556,10 @@ Markdown,且 `patch` 没有备份。这是待修复缺口(见 [SECURITY.md](
512
556
  - 课堂 API 的 Cookie(投影 / 视频直链)与 Bearer 仅发往 `classroom.zju.edu.cn`;字幕不发 Cookie 头。
513
557
  课堂 API 的跨域 302 直接拒绝,避免 `urllib` 把 `Cookie` / `Authorization` 头重发到第三方域。
514
558
  - 投影截图的**初始**地址只允许 `https://*.zju.edu.cn`;ZJU 的 `http://` 自动升级 HTTPS;
515
- Cookie 只给 ZJU 图片主机。**当前实现仍有两个已知例外**:图片返回 401/403 时会把 Bearer
516
- 重试到图片主机;跨主机重定向会剥离凭据,但目标没有逐跳校验,且同主机 HTTPS→HTTP
517
- 或换端口不会剥离。由此可能形成降级泄凭据与盲 SSRF,见 [SECURITY.md](../SECURITY.md) §7.2。
518
- 修复前应关闭投影下载,或在可信网络中只处理自己信任的课程。
559
+ Cookie 只给 ZJU 图片主机。图片返回 401/403 时 Bearer 只重试到同一图片主机。
560
+ 重定向逐跳校验:目标必须是浙大主机,拒绝 HTTPS→HTTP、URL userinfo、IP 字面量与
561
+ 私网/loopback;跨 origin 时剥离 Cookie / Authorization / Proxy-Authorization,
562
+ 被阻止的跳转只写 diagnostics(见 [SECURITY.md](../SECURITY.md) §10)。
519
563
  - 可选的 Typst 自动安装会访问 GitHub 官方 Release,并通过 `ZJU_TYPST_MIRROR` 支持镜像;
520
564
  `@preview` 包已 vendor,但底稿显式引用未 vendor 的包时仍可能访问包注册表。
521
565
 
@@ -527,8 +571,10 @@ Markdown,且 `patch` 没有备份。这是待修复缺口(见 [SECURITY.md](
527
571
  (可用 `clear=true` 删除)、Typst 缓存与讲义/备份文件外,不写用户目录。
528
572
 
529
573
  自动修复备份默认位于系统临时目录的 `zju-lecture-backups/`,可用 `ZJU_BACKUP_DIR` 指定;
530
- 在 POSIX 多用户机器上当前权限和可预测路径尚不安全(见 [SECURITY.md](../SECURITY.md) §7.6)。
531
- `ZJU_TYPST_MIRROR` 不应包含凭据,`zju_doctor` 目前会原样显示它(§7.4)。
574
+ 目录按 0700 创建、备份文件 0600、文件名带 8 位随机后缀,写入前拒绝符号链接
575
+ (见 [SECURITY.md](../SECURITY.md) §7.6)。
576
+ `ZJU_TYPST_MIRROR` 仍不应包含凭据;`zju_doctor`、下载进度与异常只显示
577
+ `scheme://host[:port]/path`(§7.4)。
532
578
 
533
579
  ### 可机器验证
534
580
 
@@ -542,7 +588,7 @@ python tools/privacy_scan.py --tarball dist/*.tgz # npm 发布产物
542
588
 
543
589
  ```bash
544
590
  python -m unittest discover -s tests -v # 全部回归测试(含插件形态与隐私测试)
545
- python tools/build_plugin.py --validate # 按插件规范校验 MCode 包结构
591
+ python tools/build_plugin.py --validate # 校验历史打包脚本的产物结构
546
592
  python tools/check_note.py 讲义.md # 讲义渲染规范检查
547
593
  python tools/privacy_scan.py # 工作区隐私扫描
548
594
  python tools/privacy_scan.py --history # 连同 git 历史一起扫
@@ -573,9 +619,10 @@ Cookie WAL 回放、ABE 探测、PDF 报错带解释器路径、bridge 超时语
573
619
  登录态安全存储 / Cookie 域过滤 / 登录 URL 白名单 / 失效清除 / `zju_login(clear=true)`、
574
620
  阅读版 PDF 的标记装置与真实编译、配色三处一致与字体可再分发性、填空笔记链路。
575
621
 
576
- > 测试覆盖的是当前已实现行为,不等于安全审计结论。2026-11-06 的审查仍确认了
577
- > 并发工作区、截图重定向、外部回写、镜像脱敏、隐私扫描与备份权限等待修复缺口,
578
- > 清单见 [SECURITY.md](../SECURITY.md) 第 7 节。
622
+ > 2026-11-06 安全审查确认的问题已在 `fix/security-audit-2026-11` 分支全部修复,
623
+ > 每条都有独立回归测试(工作区隔离、重定向、边界、脱敏、掩码、权限、资源上限、
624
+ > 参数白名单、副作用确认、封面注入)。逐条 commit 与验证见
625
+ > [SECURITY.md](../SECURITY.md) 第 7 节。
579
626
 
580
627
  > 测试中的 `subprocess` / 管道 / 临时文件在受限沙箱里可能被拒绝;这是环境限制,不是插件缺陷。
581
628
 
@@ -598,7 +645,7 @@ npm view dsh-zju-lecture-note version # 验证
598
645
 
599
646
  - `package.json` 的 `prepublishOnly` 已挂「全量测试 + 隐私扫描」,测试红了发不出去。
600
647
  - registry 必须是 `https://registry.npmjs.org/`:国内镜像只读,`npm publish` 会 403。
601
- - 版本号不能覆盖:每次发布前必须 bump(八处对齐,见下节)。
648
+ - 版本号不能覆盖:每次发布前必须 bump(十处对齐,见下节)。
602
649
  - 发布后用户安装:`dsh plugin --profile desktop add dsh-zju-lecture-note`。
603
650
 
604
651
  `files` 字段是逐文件枚举的运行时清单(`lib/`、`mcp_server.py`、`zju_lecture/*.py`、`skills/`、
@@ -608,16 +655,18 @@ npm view dsh-zju-lecture-note version # 验证
608
655
  dsh 按 `peerDependencies` 校验运行时版本。若升级 dsh 后插件被跳过,请检查
609
656
  `@deepseek-ai/dsh-*` 的 peer 范围,或按 dsh 提示使用 `dsh plugin allow-version` 做精确版本豁免。
610
657
 
611
- ### MCode 插件包
658
+ ### 历史打包脚本产物
612
659
 
613
660
  `python tools/build_plugin.py --install --zip`;运行时文件清单在 `PACKAGE_FILES` / `PACKAGE_DIRS`,
614
- 新增文档文件时记得同步,否则装好的包里会出现断链。
661
+ 新增文档文件时记得同步,否则装好的包里会出现断链。产物只经由这两个清单收集,
662
+ 根 `plugin.json` / `mcp.json` **不会**混进去(`validate_package()` 会断言),因此它与通用入口互不遮蔽。
663
+ 通用 agent 客户端一律走仓库根的 Agent Plugins 1.0 清单,不需要这个脚本。
615
664
 
616
665
  ### 版本号
617
666
 
618
- 版本在**八处**对齐:`package.json`、`pyproject.toml`、`mcp_server.SERVER_VERSION`、
619
- `.minimax-plugin/plugin.json`、四个 Skill manifest(由 `tools/build_skill_manifest.py` 生成)。
620
- `tests/test_dsh_plugin.py` 会断言。
667
+ 版本在**十处**对齐:`package.json`、`pyproject.toml`、`mcp_server.SERVER_VERSION`、根 `plugin.json`、
668
+ `.minimax-plugin/plugin.json`、`adapters/claude_code/plugin.json`、四个 Skill manifest
669
+ (由 `tools/build_skill_manifest.py` 生成)。`tests/test_settings_v227.py` 会断言。
621
670
 
622
671
  ### 插件市场条目
623
672
 
@@ -666,8 +715,10 @@ PY
666
715
  并给出删除路径。
667
716
  - **git 历史**:历史中已有的个人路径/密钥不会因为当前文件干净而消失;
668
717
  用 `python tools/privacy_scan.py --history` 检查,必要时重写历史并轮换凭证。
669
- - **形态别选错**:`tools/build_plugin.py` 产出的是 **MCode 插件包**;装进 dsh 用的是本仓库根目录的
670
- npm 包(`dsh plugin ... add`)。两者是两套安装方式,不要混。
718
+ - **入口别选错**:装进 dsh 用的是本仓库根目录的 npm 包(`dsh plugin ... add`,包名或 `github:` 均可);
719
+ 通用 agent 客户端用的是同一份仓库根的 Agent Plugins 1.0 清单(`plugin.json` + `mcp.json` + `skills/`)。
720
+ dsh 的安装器与 loader 只读 `package.json`,根清单对它是惰性行李,两条安装路径互不影响。
721
+ `tools/build_plugin.py` 的 zip 是历史产物,不是这两个入口之一。
671
722
  - **字幕可能需登录,请遵守平台条款**:只抓本人有权访问的回放,一次一节课,不要批量抓取。
672
723
 
673
724
  ## 12. 上游与归属