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/CHANGELOG.md +154 -2
- package/README.md +77 -46
- package/SECURITY.md +169 -66
- package/docs/technical.md +101 -50
- package/lib/bridge.js +288 -79
- package/lib/client.js +1013 -758
- package/lib/index.js +349 -75
- package/lib/tools.js +28 -3
- package/lib/tools.schema.json +23 -3
- package/mcp.json +21 -0
- package/mcp_server.py +186 -44
- package/package.json +5 -2
- package/plugin.json +19 -0
- package/server.mjs +118 -0
- package/skills/scholia-notes/references/prelude.typ +9 -1
- package/skills/scholia-notes.manifest.json +3 -3
- package/skills/zju-lecture-summarizer/SKILL.md +14 -4
- package/skills/zju-lecture-summarizer/SLIDES.md +42 -5
- package/skills/zju-lecture-summarizer-help/SKILL.md +3 -3
- package/skills/zju-lecture-summarizer-help.manifest.json +4 -4
- package/skills/zju-lecture-summarizer-login/SKILL.md +1 -1
- package/skills/zju-lecture-summarizer-login.manifest.json +4 -4
- package/skills/zju-lecture-summarizer.manifest.json +6 -6
- package/zju_lecture/browser_login.py +174 -210
- package/zju_lecture/cli.py +50 -2
- package/zju_lecture/client.py +95 -18
- package/zju_lecture/cookies.py +43 -4
- package/zju_lecture/courseware.py +37 -2
- package/zju_lecture/credential_store.py +621 -0
- package/zju_lecture/deps.py +114 -17
- package/zju_lecture/handout.py +29 -3
- package/zju_lecture/note_lint.py +34 -10
- package/zju_lecture/paths.py +57 -2
- package/zju_lecture/prelude.typ +9 -1
- package/zju_lecture/slides.py +73 -35
- package/zju_lecture/study_notes.py +40 -4
package/docs/technical.md
CHANGED
|
@@ -5,8 +5,9 @@
|
|
|
5
5
|
|
|
6
6
|
## 1. 仓库结构与数据流
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
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
|
-
├──
|
|
22
|
-
├──
|
|
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
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
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
|
-
|
|
|
113
|
-
|
|
114
|
-
|
|
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
|
-
|
|
|
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
|
-
-
|
|
220
|
-
|
|
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
|
-
|
|
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.
|
|
480
|
-
|
|
481
|
-
`zju_login(clear=true)`
|
|
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
|
|
487
|
-
|
|
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
|
-
|
|
501
|
-
|
|
502
|
-
|
|
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
|
|
516
|
-
|
|
517
|
-
|
|
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
|
-
|
|
531
|
-
|
|
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 #
|
|
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
|
-
>
|
|
577
|
-
>
|
|
578
|
-
>
|
|
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
|
-
###
|
|
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
|
-
|
|
619
|
-
`.minimax-plugin/plugin.json`、四个 Skill manifest
|
|
620
|
-
`tests/
|
|
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
|
-
-
|
|
670
|
-
|
|
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. 上游与归属
|