dsh-learning-assistant 0.0.2 → 0.1.0
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/README.md +41 -7
- package/assets/collect/README.md +55 -0
- package/assets/skills/course-inbox-sync.md +182 -0
- package/assets/skills/course-material-digest.md +173 -0
- package/assets/skills/one-to-one-tutor.md +320 -0
- package/assets/tools/pdf/pdf-render.ps1 +30 -0
- package/assets/tools/pptx-digest.py +99 -0
- package/assets/tools/pptx-map.py +98 -0
- package/assets/tools/pptx-media.py +101 -0
- package/assets/tools/qq-group-msg.py +258 -0
- package/assets/tools/qq-group-sync.py +265 -0
- package/docs//345/215/217/344/275/234/345/274/200/345/217/221.md +18 -10
- package/lib/client.js +110 -0
- package/lib/{index.d.mts → index.d.ts} +3 -1
- package/lib/index.js +392 -0
- package/package.json +8 -7
- package/src/client/settings.tsx +6 -4
- package/src/index.ts +36 -11
- package/src/practice/learn/api.mjs +393 -0
- package/src/practice/learn/cli.mjs +175 -0
- package/src/practice/learn/curriculum.mjs +292 -0
- package/src/practice/learn/handoff.mjs +73 -0
- package/src/practice/learn/jsonschema.mjs +171 -0
- package/src/practice/learn/mapping.mjs +90 -0
- package/src/practice/learn/progress.mjs +247 -0
- package/src/practice/learn/schema/curriculum.schema.json +88 -0
- package/src/practice/learn/schema/handoff.schema.json +56 -0
- package/src/practice/learn/schema/node-practice-map.schema.json +28 -0
- package/src/practice/learn/schema/progress.schema.json +66 -0
- package/src/practice/learn/schemas.mjs +53 -0
- package/src/practice/learn/store.mjs +247 -0
- package/src/practice/public/app.js +883 -0
- package/src/practice/public/index.html +19 -0
- package/src/practice/public/ink.js +349 -0
- package/src/practice/public/learn.css +20 -0
- package/src/practice/public/learn.js +329 -0
- package/src/practice/public/style.css +326 -0
- package/src/practice/public/vendor/katex/contrib/auto-render.min.js +1 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_AMS-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Caligraphic-Bold.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Caligraphic-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Fraktur-Bold.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Fraktur-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Main-Bold.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Main-BoldItalic.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Main-Italic.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Main-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Math-BoldItalic.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Math-Italic.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_SansSerif-Bold.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_SansSerif-Italic.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_SansSerif-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Script-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Size1-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Size2-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Size3-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Size4-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Typewriter-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/katex.min.css +1 -0
- package/src/practice/public/vendor/katex/katex.min.js +1 -0
- package/src/practice//346/234/215/345/212/241.mjs +443 -0
- package/src/practice//346/240/241/351/252/214/351/242/230/347/233/256.mjs +114 -0
- package/src/practice//347/255/211/345/276/205/346/217/220/344/272/244.mjs +100 -0
- package/src/practice-service.ts +99 -0
- package/src/practice-tool.ts +91 -0
- package/src/skills.ts +156 -0
- package/lib/client.d.mts +0 -10
- package/lib/client.mjs +0 -87
- package/lib/index.mjs +0 -29
package/README.md
CHANGED
|
@@ -2,30 +2,64 @@
|
|
|
2
2
|
|
|
3
3
|
DeepSeek Harness 的「学习助手」插件:把现在手工跑的一套带学流程固化成插件。
|
|
4
4
|
|
|
5
|
-
>
|
|
6
|
-
>
|
|
5
|
+
> 现状:**三大板块全部接线(v0.1.0)**。三个内嵌技能、参数化采集脚本(QQ)、
|
|
6
|
+
> 练习台按需启停(`practice_desk` 工具 + 随包服务)已就位;企微/微信采集**待开发**(不随包)。
|
|
7
|
+
> 验收:`node tests/自检.mjs`(22 用例)+ `node tests/验收.mjs`(22 用例)+ `npm run check`。
|
|
7
8
|
|
|
8
9
|
## 三个板块
|
|
9
10
|
|
|
10
11
|
| 板块 | 内容 | 现状 |
|
|
11
12
|
|---|---|---|
|
|
12
|
-
| 资料整理 | QQ(NapCat)自动收群文件落盘;企微走 UIA 采集;微信 4.x 待社区适配 |
|
|
13
|
-
| 知识整理与讲解 | 按学科选讲解方案;思维导图 + 讲解提示词 |
|
|
14
|
-
| 学习助手数据 | 现有练习台:课程计划、学习历史、作答记录 |
|
|
13
|
+
| 资料整理 | QQ(NapCat)自动收群文件落盘;企微走 UIA 采集;微信 4.x 待社区适配 | **QQ 脚本已入仓**(`assets/tools`);企微/微信待开发,正本在学习区 `tools/` |
|
|
14
|
+
| 知识整理与讲解 | 按学科选讲解方案;思维导图 + 讲解提示词 | **三技能已内嵌**(`src/skills.ts` → `assets/skills/`) |
|
|
15
|
+
| 学习助手数据 | 现有练习台:课程计划、学习历史、作答记录 | **已接线**:`practice_desk` 工具按需起停随包服务(`src/practice/`),收编已有健康实例 |
|
|
15
16
|
|
|
16
|
-
使用侧:用户说「帮我学 xx」→ 按所选方案整理并讲解 →
|
|
17
|
+
使用侧:用户说「帮我学 xx」→ 按所选方案整理并讲解 → 出题自测(练习台机制与学习区一致)。
|
|
17
18
|
|
|
18
19
|
## 目录
|
|
19
20
|
|
|
20
21
|
```
|
|
21
|
-
src/index.ts 宿主半:
|
|
22
|
+
src/index.ts 宿主半:skills / tools 注册、配置 schema
|
|
23
|
+
src/skills.ts 内嵌技能提供者(rank 700,让位工作区同名技能)
|
|
24
|
+
src/practice-service.ts 练习台服务管理:健康探测收编 / 随包拉起 / 卸载清理
|
|
25
|
+
src/practice-tool.ts practice_desk 工具(open / status / stop)
|
|
26
|
+
src/practice/服务.mjs 练习台服务(--data-root 参数化;兼容传统布局)
|
|
27
|
+
src/practice/learn/ 课程计划与进度数据层(LEARN_WORKSPACE/LEARN_DATA_ROOT 参数化)
|
|
28
|
+
src/practice/等待提交.mjs 收件箱探针(--base 参数化)
|
|
29
|
+
src/practice/校验题目.mjs 题库校验器
|
|
30
|
+
src/practice/public/ 前端(app.js / learn.js / ink.js 白板 / 离线 KaTeX)
|
|
22
31
|
src/client/index.tsx 浏览器半:slot 注册入口
|
|
23
32
|
src/client/settings.tsx 设置 → 学习助手(三分区页面)
|
|
33
|
+
assets/skills/ 三个技能正文(不含任何本机值,附录自动追加部署事实)
|
|
34
|
+
assets/tools/ 采集与整理脚本(QQ/NapCat、pptx/pdf 工具;企微/微信待开发)
|
|
35
|
+
assets/collect/README.md 采集脚本配置说明(数据根落点约定)
|
|
36
|
+
练习台/ 知识整理/ 测试 fixture(合成数据,非真实课程)
|
|
37
|
+
tests/自检.mjs 数据层端到端(22 用例,LEARN_DATA_ROOT 指向临时目录)
|
|
38
|
+
tests/验收.mjs HTTP 层端到端(22 用例,随机端口起随包服务)
|
|
24
39
|
cordis.patch.yml 把插件插进 profile 层叠栈
|
|
25
40
|
docs/设计路线.md 分阶段路线、岔路口、成本
|
|
26
41
|
docs/发布手册.md 发 npm、别人怎么装、怎么收到新版本
|
|
27
42
|
```
|
|
28
43
|
|
|
44
|
+
## 数据布局(dataRoot)
|
|
45
|
+
|
|
46
|
+
`dataRoot` 配置指向一个「工作区式」目录:
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
<dataRoot>/
|
|
50
|
+
├── 练习台/
|
|
51
|
+
│ ├── _题库/<科目>/<练习id>.json 题目
|
|
52
|
+
│ ├── _记录/<科目>/*.json 每次提交的答卷
|
|
53
|
+
│ ├── _笔迹/<科目>/*.png 白板手写原图(一题一张)
|
|
54
|
+
│ └── _收件箱/待处理.jsonl 提交流水(多对话共用)
|
|
55
|
+
└── 学习助手数据/
|
|
56
|
+
├── subjects/<科目>/ 课程计划 + 进度 + 映射 + 交接
|
|
57
|
+
└── _history/ 覆盖前的旧版本(回滚兜底)
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
默认 `<DSH_HOME>/learning-assistant/data`;把 `dataRoot` 指到学习区工作区即可直接复用
|
|
61
|
+
现有题库与进度,零迁移。练习台收件箱探针 / 校验器等固定命令见内嵌技能 `one-to-one-tutor`。
|
|
62
|
+
|
|
29
63
|
## 开发
|
|
30
64
|
|
|
31
65
|
```powershell
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# 资料采集脚本(板块①)
|
|
2
|
+
|
|
3
|
+
> **范围(2026-11-18 拍板)**:本目录只随包分发 **QQ(NapCat OneBot)** 一条路线。
|
|
4
|
+
> 企业微信(UIA)与微信 4.x **待开发**,不随包分发;学习区的验证脚本正本留在
|
|
5
|
+
> `learning/tools/im-collect/` 与 `learning/tools/`,待方案成熟后再进来。
|
|
6
|
+
|
|
7
|
+
把学习区手工验证过的 QQ 收取路线带进插件包,**参数化后开源**:所有部署事实
|
|
8
|
+
(端点、令牌、群号白名单、下载根、台账位置)都从配置读取,正文与代码不携带真实值。
|
|
9
|
+
|
|
10
|
+
## QQ 群文件 / 群消息(NapCat OneBot 11 HTTP,纯 API 零 UIA)
|
|
11
|
+
|
|
12
|
+
| 脚本 | 用途 |
|
|
13
|
+
|---|---|
|
|
14
|
+
| `qq-group-sync.py` | 列出白名单群的群文件并增量下载(对账按大小+MD5,状态记台账 JSON) |
|
|
15
|
+
| `qq-group-msg.py` | 抓群消息/公告/群作业卡,正则抽 DDL 候选 → `<数据根>/qq群消息.json`、`ddl_qq.json` |
|
|
16
|
+
|
|
17
|
+
前置:NapCat 壳进程已登录(`napcat.bat -q <QQ号>` 快速登录,免扫码;用完即关)。
|
|
18
|
+
注意:NapCat 跑着时不能开桌面 QQ(同账号互踢);请求体必须平铺参数(不是 `{action, params}` 信封)。
|
|
19
|
+
|
|
20
|
+
两个脚本共用同一套配置面:
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
命令行 > 环境变量 > --config JSON
|
|
24
|
+
NAPCAT_ENDPOINT OneBot HTTP 端点(默认 http://127.0.0.1:3000)
|
|
25
|
+
NAPCAT_TOKEN Bearer 令牌
|
|
26
|
+
NAPCAT_GROUPS "群号=科目=群名,群号=科目=群名"
|
|
27
|
+
QQ_SYNC_DEST 群文件下载根;QQ_SYNC_STATE 台账 JSON 路径
|
|
28
|
+
QQ_MSG_OUT 群消息输出目录(=数据根)
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## 企业微信 / 微信(待开发占位)
|
|
32
|
+
|
|
33
|
+
- **企业微信**:UIA 白名单采集在学习区已验证(wecom-automation,增量约 7 秒/群),
|
|
34
|
+
但注入器依赖特定客户端版本,尚不成熟——**不随包分发**,待开发后接入。
|
|
35
|
+
- **微信 4.1.x**:UIA 大门焊死(主窗只剩渲染空壳),等社区适配,**不做承诺**。
|
|
36
|
+
|
|
37
|
+
## 硬红线
|
|
38
|
+
|
|
39
|
+
- 只读附件与群文件列表,**不解密**任何聊天数据库,不 OCR。
|
|
40
|
+
- 白名单纪律:每次任务只碰配置点名的群,其他群一律不读不点。
|
|
41
|
+
- 协议端按需启动用完即关,不做常驻进程。
|
|
42
|
+
|
|
43
|
+
## 采集产物落点约定
|
|
44
|
+
|
|
45
|
+
全部落在插件配置的**数据根目录**(`dataRoot`)下:
|
|
46
|
+
|
|
47
|
+
```
|
|
48
|
+
<数据根>/
|
|
49
|
+
├── qq群文件台账.json QQ 群文件对账台账
|
|
50
|
+
├── qq群消息.json 群消息/公告/作业卡
|
|
51
|
+
└── ddl_qq.json QQ 侧 DDL 候选
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
群文件下载根(`QQ_SYNC_DEST` / `--dest`)独立配置,可指向任意工作区。
|
|
55
|
+
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
# course-inbox-sync(跨平台课程资料同步 + 作业 DDL 提醒)
|
|
2
|
+
|
|
3
|
+
> 触发词:**「更新学习进度」**、「同步课程资料」、「看看有没有新课件」、「作业 DDL 提醒」、「跨平台收件箱」。
|
|
4
|
+
> 目的:用户不必自己从 QQ / 微信 / 企业微信往工作区拖文件。助手自动扫描各平台**已落盘的附件**,
|
|
5
|
+
> 与「知识整理」比对,找出没整理完的资料并自行补上;同时从附件正文抽取作业 DDL 并提醒。
|
|
6
|
+
|
|
7
|
+
## 0. 硬红线(先读,再动手)
|
|
8
|
+
|
|
9
|
+
1. **只读附件,不解密、不 OCR、不读聊天记录。**
|
|
10
|
+
三平台的聊天正文数据库全部自带加密(QQNT = SQLCipher;微信 4.1.x = 自定义 SQLCipher 4;企微 = 私有加密),
|
|
11
|
+
没有任何值得依赖的通用解密方案。**不要为了「读聊天记录」去装第三方解密框架或注入客户端**——
|
|
12
|
+
账号封禁风险远大于收益。群文件/群消息走协议端(NapCat OneBot HTTP)或客户端 UIA,聊天正文数据库一律不碰。
|
|
13
|
+
2. **QQ 群文件走 NapCat 协议端**(OneBot 11 HTTP):`assets/tools/qq-group-sync.py` 批量列出并下载群文件。
|
|
14
|
+
**代价:NapCat 跑着时不能开桌面 QQ(同账号互踢)**;NapCat 一停,QQ 这条线就断。
|
|
15
|
+
兜底路线:用户在 QQ 客户端手动点「下载全部」→ 文件落下载目录 → 采集器扫该目录。
|
|
16
|
+
3. **不重复劳动**:开工前必读 `知识整理\_进度.md`(资料台账)与 `知识整理\_源清单.md`(原件清单)。
|
|
17
|
+
4. **台账只由主代理串行更新**,子代理一律不许碰台账、源清单、DDL、收件待办与数据根目录。
|
|
18
|
+
5. **总览计数必须程序化重算**,不可手填(口径写在台账的「怎么更新这个文件」)。
|
|
19
|
+
6. PDF/PPT 解析**一律用现成库**,不要自研解析器:`assets/tools/source-text.py`(pypdf 择优)+
|
|
20
|
+
`assets/tools/pptx-digest.py`(文本版 PPTX)+ `assets/tools/pptx-media.py --extract` +
|
|
21
|
+
`assets/tools/pdf-render.ps1`(图片版/扫描件走渲染看图)。**不做 OCR**。
|
|
22
|
+
7. 回答用中文;只给结论;改文件只报「路径:行号 + 改了什么」。
|
|
23
|
+
8. **白名单纪律**:采集只碰配置里点名的群;其他群一律不读不点。QQ 的群号白名单、
|
|
24
|
+
NapCat 地址与令牌、各平台的落盘根目录,都由部署方通过插件配置 / 环境变量提供(见文末「部署适配」),
|
|
25
|
+
本技能正文不携带任何真实群号或令牌。
|
|
26
|
+
|
|
27
|
+
## 1. 五层流水线(脚本已就位)
|
|
28
|
+
|
|
29
|
+
| 层 | 脚本 / 产物 | 说明 |
|
|
30
|
+
|---|---|---|
|
|
31
|
+
| L1 采集 | `assets/tools/collect-sync.py`(部署可另带本机版) | 扫描各平台落盘根(见下) |
|
|
32
|
+
| L2 比对 | `<数据根>/平台收件箱.json`、`知识整理\_收件待办.md` | 与 `_源清单.md` + `_进度.md` 比对,MD5 去重 |
|
|
33
|
+
| L3 补做 | 成品 md 落 `知识整理\<科目>\` | 按 course-material-digest 的四路线 A/B/C/D |
|
|
34
|
+
| L4 台账 | `知识整理\_进度.md` | 主代理串行改明细 + 程序化重算总览 |
|
|
35
|
+
| L5 DDL | `<数据根>/ddl.json`、`知识整理\_DDL.md` | 附件正文正则抽截止时间;可建定时任务每日推送 |
|
|
36
|
+
|
|
37
|
+
### L1 扫描根(按部署配置,典型形态)
|
|
38
|
+
|
|
39
|
+
| 平台 | 典型落盘形态 | 能拿到什么 |
|
|
40
|
+
|---|---|---|
|
|
41
|
+
| 微信 | `msg\file\<YYYY-MM>\`(账号目录下按月明文落盘) | **主力来源**,收到的文件 |
|
|
42
|
+
| 企业微信 | `WXWork\<账号id>\Cache\File\<YYYY-MM>\` | 按月明文落盘的附件 |
|
|
43
|
+
| QQ(NapCat 自动) | 群文件下载根(如 `D:\QQ课程资料\<科目>\`) | 协议端自动下载的群文件,主力来源 |
|
|
44
|
+
| QQ(手动兜底) | 浏览器/QQ 下载目录 | 用户手动点下载的文件 |
|
|
45
|
+
| 本地 | 课程资料正本目录、零散下载目录 | 正本与散件 |
|
|
46
|
+
|
|
47
|
+
### QQ 群文件自动下载(NapCat 协议端)
|
|
48
|
+
|
|
49
|
+
- **启动**:NapCat 壳进程(`napcat.bat -q <QQ号>` 快速登录,免扫码);用完即关(不用常驻)。
|
|
50
|
+
- **OneBot HTTP**:`http://127.0.0.1:<port>/<action>`,头 `Authorization: Bearer <token>`。
|
|
51
|
+
⚠️ 请求体必须是**平铺参数**(`{"group_id":"123"}`),**不能**用 `{action, params}` 信封
|
|
52
|
+
(`get_group_root_files` 会报 Schema compilation error)。
|
|
53
|
+
⚠️ `file_id` 是**会话级**的,每次调用都变,用完即弃。
|
|
54
|
+
- **下载**:`qq-group-sync.py --list` 只列、`--only <gid>` 单群、`--max-mb 60` 大小上限、`--dest <根>` 下载根 →
|
|
55
|
+
落 `<下载根>/<科目>\`,状态记 `<数据根>/qq群文件台账.json`。
|
|
56
|
+
- **群消息/群公告**:`qq-group-msg.py` → `<数据根>/qq群消息.json`
|
|
57
|
+
(kind ∈ text/file/announce/homework;群公告 base64 在 com.tencent.mannounce;群作业卡在 com.tencent.tuwen.lua 的 group.homework)。
|
|
58
|
+
- 地址 / 令牌 / 群号表由部署配置给出(见「部署适配」)。
|
|
59
|
+
|
|
60
|
+
### 命令
|
|
61
|
+
|
|
62
|
+
```
|
|
63
|
+
# 全流程(扫描 + 抽取正文 + 出待办 + DDL)
|
|
64
|
+
python tools\collect-sync.py --phase all --include-manifest
|
|
65
|
+
# 只扫描(秒级)
|
|
66
|
+
python tools\collect-sync.py --phase scan
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
- `--phase scan|extract|all`、`--only-new`、`--limit N`、`--include-manifest`(把清单内文件也抽正文,用于发现旧 DDL)
|
|
70
|
+
- 抽取结果缓存进 `平台收件箱.json`(按 `path|mtime`),重复跑不重复解析
|
|
71
|
+
- **⚠️ 长任务必须分离启动**:`Start-Process -RedirectStandardOutput` 后**不要** `WaitForExit`(DSH 里会超时),
|
|
72
|
+
改成再单独轮询输出文件 mtime
|
|
73
|
+
|
|
74
|
+
## 2. PDF / PPTX 抽取的两种姿势(都别自研)
|
|
75
|
+
|
|
76
|
+
**PDF(有文字层)** —— pypdf 逐页在两种模式里取信息量更大者:
|
|
77
|
+
|
|
78
|
+
```python
|
|
79
|
+
from pypdf import PdfReader
|
|
80
|
+
for i, pg in enumerate(reader.pages, 1):
|
|
81
|
+
lay = pg.extract_text(extraction_mode="layout") or "" # 版式模式
|
|
82
|
+
dft = pg.extract_text() or "" # 默认模式
|
|
83
|
+
t = lay if dens(lay) >= dens(dft) else dft # 取更长的那个
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
- **只用 layout 单模式会退化**(实测有讲义只剩几百字),**只用默认模式会把汉字顺序打乱**
|
|
87
|
+
(出现「定义于区域设函数」这种倒序)→ **必须逐页择优**(`source-text.py` 已封装)。
|
|
88
|
+
- **公式上下标、分数线、希腊字母会丢字形**:能确定照抄,不能确定写「(公式字形缺失)」,**绝不猜测补写**。
|
|
89
|
+
- 提取结果落 `知识整理\_源文本\<科目>\<名字>.md`,逐页写 `## Page N`。
|
|
90
|
+
|
|
91
|
+
**PPTX** —— `pptx-digest.py <input.pptx> [output.md]`(文本版,直接抓 `<a:t>` + `<m:t>`)。
|
|
92
|
+
整页图片版(`TEXT_CHARS=0`)走 `pptx-media.py --extract <dir>` 导出原图,再分批看图,**不 OCR**。
|
|
93
|
+
|
|
94
|
+
**扫描件/图片版 PDF** —— `powershell -ExecutionPolicy Bypass -File tools\pdf-render.ps1 -srcDir <目录> -outDir <目录> [-width 1500]`,
|
|
95
|
+
输出在 `<outDir>\<pdf名>\p01.png`。重活交子代理,**一次 16 页一片**。
|
|
96
|
+
|
|
97
|
+
## 3. L3 补做:四路线
|
|
98
|
+
|
|
99
|
+
| 路线 | 条件 | 做法 |
|
|
100
|
+
|---|---|---|
|
|
101
|
+
| A | 文本版 PPTX(`TEXT_CHARS>0`) | `pptx-digest.py` → 子代理写成品 |
|
|
102
|
+
| B | 整页图片版 PPTX | `pptx-media.py` 导出 → 子代理看图 |
|
|
103
|
+
| C | 文本 PDF | pypdf 择优 → `_源文本\` → 子代理写成品 |
|
|
104
|
+
| D | 扫描 PDF / 图片 PDF | `pdf-render.ps1` → 子代理看图(重活先跟用户确认) |
|
|
105
|
+
|
|
106
|
+
**成品格式(course-material-digest 的四段式)**:
|
|
107
|
+
|
|
108
|
+
```
|
|
109
|
+
# <标题> —— 知识整理
|
|
110
|
+
|
|
111
|
+
> 原始文件(绝对路径):... 页数、抽取方式、缺失标注约定
|
|
112
|
+
|
|
113
|
+
## 1. 思维导图 (mermaid mindmap)
|
|
114
|
+
## 2. 分节详解 ← 2.1 / 2.2 ...
|
|
115
|
+
## 3. 公式与结论速查
|
|
116
|
+
## 4. 考点分布 ← 只用源文本里明写的百分比,其余写「未标注」
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
- **mermaid 节点文字禁含 ( ) [ ]**
|
|
120
|
+
- 源文本没写的百分比**绝不编造**,一律「未标注」
|
|
121
|
+
- 覆盖已有文件前**必须先 read**
|
|
122
|
+
- 子代理只回 `DONE <文件名> pages=16 chars=N`
|
|
123
|
+
|
|
124
|
+
## 4. L4 台账更新(主代理串行,勿外包)
|
|
125
|
+
|
|
126
|
+
1. 改该行状态(⬜→✅)+ 填成品相对路径
|
|
127
|
+
2. **总览每一格都照明细逐行程序化重算**,不手填(按 `### <课程>` 分节解析表格行、跳过含 ~~ 的行与状态含「误挂/不计入」的行、识别 ✅/🟨/🟡/⬜)
|
|
128
|
+
3. 合并重复行并注明
|
|
129
|
+
4. 改「最后更新」日期
|
|
130
|
+
5. **规模列要和实测一致**:页数用 pypdf 实测值(PDF 可能有增量更新,字节扫描 `/Type/Page` 计数会翻倍,别信)
|
|
131
|
+
|
|
132
|
+
## 5. L5 DDL 抽取
|
|
133
|
+
|
|
134
|
+
- 关键字:`截止|ddl|提交|上交|答辩|有效期|deadline|前交|交卷|交回|最迟|不晚于|逾期|迟交|作业要求`
|
|
135
|
+
- **必须同句出现日期/时间才收**(避免把「提交程序」当 DDL)
|
|
136
|
+
- PDF 排版会把日期数字拆开(`10.1 1日` → `10.11日`),先 `re.sub(r"(?<=\d)\s+(?=\d)", "", sent)` 归一
|
|
137
|
+
- 缺年份按「距今 > 200 天算去年」推断
|
|
138
|
+
- 产物 `知识整理\_DDL.md`(表)+ `<数据根>/ddl.json`;状态「已过期 / 今天到期 / 剩 N 天」
|
|
139
|
+
- **已知口径**:DDL 只能从**附件正文**读;老师在聊天里纯打字发的截止时间读不到
|
|
140
|
+
|
|
141
|
+
### DDL 扫描器(唯一入口)
|
|
142
|
+
|
|
143
|
+
`ddl-scan.py` 是 DDL 层的唯一生成者(`collect-sync.py` 的同名分支已废弃):
|
|
144
|
+
|
|
145
|
+
```
|
|
146
|
+
& "<python>" tools\ddl-scan.py
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
- 数据源:`知识整理\_源文本\**\*.md` **全文**(不截断)+ `<数据根>/qq群消息.json`
|
|
150
|
+
- 产物:`<数据根>/ddl.json` + `知识整理\_DDL.md`(抬头写明「勿手改,改脚本」)
|
|
151
|
+
- 规则要点:日期必须紧邻「提交/上交/交卷/交回/答辩」,或整句 ≤200 字且含「考试/测验/小测」+日期;长段落取**匹配点 ±60 字窗口**(整段丢弃会漏掉真 DDL);负向词 `不作提交|不提交|可选练习|不交` 等
|
|
152
|
+
- QQ 群作业卡(kind=homework)只有布置日没有截止日 → 单列 _DDL.md 底部「待确认」区,不进主表
|
|
153
|
+
|
|
154
|
+
### 定时推送(可选)
|
|
155
|
+
|
|
156
|
+
需要每日提醒时,用调度工具建一个每日任务:先跑 `ddl-scan.py` 刷新,再读 `_DDL.md` 汇报今天到期与未来 7 天到期的作业。
|
|
157
|
+
建之前先列出现有任务,避免重复。
|
|
158
|
+
|
|
159
|
+
## 6. 执行清单(「更新学习进度」时按这个走)
|
|
160
|
+
|
|
161
|
+
1. 读 `知识整理\_进度.md` + `知识整理\_收件待办.md`(**不要整份读 _源清单.md,1000+ 行,用 grep**)
|
|
162
|
+
2. `python tools\collect-sync.py --phase all --include-manifest`(分离启动 + 轮询输出)
|
|
163
|
+
3. 看 `_收件待办.md`:哪些是本区课程的未整理资料
|
|
164
|
+
4. 缺的原文用第 2 节的姿势抽成 `_源文本\`
|
|
165
|
+
5. 派子代理写成品(提示词模板见第 3 节;**必须禁止子代理改台账**)
|
|
166
|
+
6. 主代理串行回写 `_进度.md`(明细 + 程序化重算总览)
|
|
167
|
+
7. 复核 `_DDL.md`,把未过期的 DDL 直接在对话里告诉用户
|
|
168
|
+
8. 收工时告诉用户:新增整理了哪几份、还剩哪些没整理、DDL 情况
|
|
169
|
+
|
|
170
|
+
## 7. 环境坑(别再踩)
|
|
171
|
+
|
|
172
|
+
- 输出中文要加 `[Console]::OutputEncoding=[System.Text.Encoding]::UTF8`;**Python 脚本别 print 中文**,写 UTF-8 文件再读
|
|
173
|
+
- DSH 沙箱里子进程管道受限:优先在当前会话内联跑,别绕
|
|
174
|
+
- 沙箱临时目录不可写 → **pip 装不了包**,缺库只能用现成解释器或换实现
|
|
175
|
+
- 把 Python 源码塞进 JS 字符串时 `\U` `\d` 等转义会炸 → 用 `String.raw` + 占位符,或 `Out-File -Encoding UTF8` 写脚本再跑
|
|
176
|
+
- PowerShell 写含中文的 Python 脚本 → `Out-File -Encoding UTF8` 写脚本再跑,别把源码直接塞进 JS 字符串
|
|
177
|
+
|
|
178
|
+
## 8. 部署适配
|
|
179
|
+
|
|
180
|
+
本技能的脚本在插件包 `assets/tools/` 下;**扫描根、群号白名单、NapCat 地址与令牌、各平台账号目录**
|
|
181
|
+
都是部署方环境的事实,从插件配置或数据根的清单文件读取,正文不写死。
|
|
182
|
+
数据产物(`平台收件箱.json`、`ddl.json`、`qq群文件台账.json`、`qq群消息.json`)落在插件配置的**数据根目录**下。
|
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
# 课程资料整理(course-material-digest)
|
|
2
|
+
|
|
3
|
+
把课程原始资料变成**准确**的知识材料。核心原则:**读原始文件(读图),不读 OCR;宁可少写,不许猜。**
|
|
4
|
+
|
|
5
|
+
> **部署适配(先读)**:本技能由「学习助手」插件内嵌提供。文中工具脚本随插件 assets 提供(`assets/tools/`),
|
|
6
|
+
> Python 解释器、工作区路径等本机实际值见本文末尾**自动追加的「插件环境附录」**;
|
|
7
|
+
> 附录缺省时按括号里的默认值理解。
|
|
8
|
+
|
|
9
|
+
## 第 -1 步(必做):**原件一定在硬盘上,先定位,再动手**
|
|
10
|
+
|
|
11
|
+
> ⛔ **反模式(真踩过,代价是白干一大轮 + 用户被弹窗打扰)**:
|
|
12
|
+
> 一上来就去翻笔记软件 / 导出件里的课件副本。
|
|
13
|
+
> **那些副本是截图、是附件副本,正本几乎永远还在磁盘上。**
|
|
14
|
+
> 读截图 = 慢、贵、还可能 OCR 出错。**先找磁盘原件。**
|
|
15
|
+
|
|
16
|
+
**确定性规则**(按顺序,能停就停 —— **前两步几乎是免费的**):
|
|
17
|
+
|
|
18
|
+
1. **先查表(零成本)**:工作区 `知识整理\README.md` 的「课程 → 正本位置」对照表,
|
|
19
|
+
或 `_源清单.md` 顶部的「⚡ 速查:课程 → 磁盘原件在哪」。命中就到此为止,直接读磁盘原件。
|
|
20
|
+
2. **表里没有,再按月份找**:微信按 `msg\file\<YYYY-MM>\` 的目录结构落盘收到的文件(以实际安装为准),
|
|
21
|
+
月份目录基本连续。**文件名和幻灯片数对得上,就是原件。**
|
|
22
|
+
3. **还找不到** → 直接问用户要原件路径,或让用户确认这份资料有没有电子原件。
|
|
23
|
+
**不要**自己去翻截图做 OCR —— 公式 OCR 出来就是垃圾(见「硬性纪律」)。
|
|
24
|
+
|
|
25
|
+
**Lesson**:曾有三次课程讲义的原件就躺在下载目录的月份文件夹里,但跳过了第 1、2 步直接去找二手截图副本,
|
|
26
|
+
白干一大轮。所以:**先查表,再动手**。
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 第 0 步(必做):先查进度,别重复劳动
|
|
31
|
+
|
|
32
|
+
开工前读:
|
|
33
|
+
|
|
34
|
+
1. `知识整理\_进度.md` —— **进度台账**。要做的单元如果已经是 ✅,直接告诉用户「这个已经做过了,成品在 X」,**不要重做**。
|
|
35
|
+
2. `知识整理\README.md` —— 项目总览 + **「课程 → 正本位置」对照表**。
|
|
36
|
+
3. `知识整理\_源清单.md` —— 源文件盘点。⚠️ **不要整份读**:它常有 1000+ 行(微信散件明细占大头),
|
|
37
|
+
整份读会被截断、白烧上下文。**先用顶部速查表**;要查具体文件用 `grep` 按课程名或文件名搜。
|
|
38
|
+
|
|
39
|
+
**完工后必须回到 `_进度.md` 更新那一行**(状态 + 成品相对路径 + 顶部总览计数)。不更新 = 下一个会话会重复劳动。
|
|
40
|
+
|
|
41
|
+
> 台账里标 🟨 的行表示「原始文字已抽好、成品未出」,**不需要重新解析文件**,直接读 `_源文本\` 即可。
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## 第 1 步:判断素材类型
|
|
46
|
+
|
|
47
|
+
```powershell
|
|
48
|
+
& "<python>" tools\pptx-media.py "<文件.pptx>" # 完整报告:media 构成、格式、大小、第1页 XML 统计
|
|
49
|
+
& "<python>" tools\pptx-digest.py "<文件.pptx>" # stdout 打 SLIDES= / TEXT_CHARS= / PICS=
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
| 判定 | 处理路线 |
|
|
53
|
+
|---|---|
|
|
54
|
+
| `TEXT_CHARS` 明显 > 0 | **A. 文本版** → 直接抽,零误差,最快 |
|
|
55
|
+
| `TEXT_CHARS≈0` 且 `PICS≈SLIDES` | **B. 整页图片版** → 导出原图 → 逐张看图 |
|
|
56
|
+
| PDF:`/FontFile` > 0 **且**文本算子(Tj/TJ)多 | **C. 文本 PDF** → 直接抽 |
|
|
57
|
+
| PDF:`/FontFile` = 0 **且**文本算子≈0、`/Image` 多 | **D. 扫描 PDF** → 渲染成图 → 看图(**重活,先跟用户确认值不值得做**) |
|
|
58
|
+
|
|
59
|
+
> ⚠️ **判 PDF 别只看 `/Font` 计数,不可靠。** 决定性的两个信号是 **`/FontFile`(嵌入字体)** 和 **文本算子 Tj/TJ**。
|
|
60
|
+
> 实测反例:某数电教材 `/Font=10` 但 `/FontFile=0`、Tj+TJ=8 → 真扫描件;而某 PDF `/FontFile=0` 却有上万个文本算子 → 真文本 PDF。
|
|
61
|
+
> 另一个坑:**纯字面量粗测对现代 PDF 会失效**——页对象藏在压缩对象流里,页数会读成 0。**必须先 zlib 解压再统计。**
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## 路线 A:文本版 PPTX(零误差)
|
|
66
|
+
|
|
67
|
+
```powershell
|
|
68
|
+
& "<python>" tools\pptx-digest.py "<文件.pptx>" "知识整理\_源文本\<课程>\<单元>.md"
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
脚本按文档顺序抓 `<a:t>`(普通文本)与 `<m:t>`(OMML 公式文本),输出 Markdown。
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## 路线 B:整页图片版 PPTX(最常用)
|
|
76
|
+
|
|
77
|
+
这类 PPT 每页就是一张整页截图,**没有文字层,OCR 也没用**。必须看图。
|
|
78
|
+
|
|
79
|
+
```powershell
|
|
80
|
+
& "<python>" tools\pptx-media.py "<文件.pptx>" --extract "知识整理\_源图\<课程>-<序号>"
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
导出 `image1.png` ~ `imageN.png`(第 N 页 = imageN.png;可用 `ppt/slides/_rels/slideN.xml.rels` 复核映射,
|
|
84
|
+
见 `tools\pptx-map.py`)。**media 编号顺序 ≠ 页序,不能靠猜。**
|
|
85
|
+
|
|
86
|
+
然后**派子代理分片看图**,每片 16 页。子代理提示词必须包含:
|
|
87
|
+
|
|
88
|
+
- 该片的**图片绝对路径清单**
|
|
89
|
+
- 每页格式:`## 第 N 页:<标题>` + 要点 + `公式:$...$` + `图示:<一句话>`
|
|
90
|
+
- **每个公式完整抄成 LaTeX。禁止出现「略 / 等等 / 类似地 / 以此类推」。**
|
|
91
|
+
- 纯标题页写「(过渡页)」;看不清写「(字迹不清)」,**不许瞎猜**
|
|
92
|
+
- **只把结果写进文件**,返回一行 `DONE <文件名> pages=16 chars=N` —— 不要把全文塞回主上下文
|
|
93
|
+
|
|
94
|
+
产出放 `知识整理\_讲稿\<课程>-<序号>\slides-001-016.md` 等。
|
|
95
|
+
|
|
96
|
+
**质检**(必做,很便宜)——程序化核验:
|
|
97
|
+
|
|
98
|
+
- 页码 1~N 是否全覆盖、无缺失、无重复
|
|
99
|
+
- LaTeX 公式(`$$...$$` 与 `$...$`)出现次数
|
|
100
|
+
- `略|等等|类似地|以此类推|字迹不清|无法辨认` 的命中数(应为 0 或极少)
|
|
101
|
+
|
|
102
|
+
有缺页就**只补那一片**,不要重跑全部。
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## 第 2 步:汇总成成品
|
|
107
|
+
|
|
108
|
+
拿全部逐页笔记,写 `知识整理\<课程>\<单元>.md`:
|
|
109
|
+
|
|
110
|
+
```markdown
|
|
111
|
+
# 《课程》第X章:<标题> —— 知识整理
|
|
112
|
+
|
|
113
|
+
> 本整理基于课件 **N 页原图逐页识读**(不是 OCR),公式为准确转录。
|
|
114
|
+
> 课件来源:`<原始文件绝对路径>`
|
|
115
|
+
|
|
116
|
+
## 1. 思维导图 ← Mermaid mindmap
|
|
117
|
+
## 2. 分节详解 ← 按**知识点**重组,不按页罗列
|
|
118
|
+
## 3. 公式速查表 ← 表格:| 名称 | 公式 | 说明 |
|
|
119
|
+
## 4. 考点分布 ← 表格:| 模块 | 占比 | 重点 |
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
- **按知识点重组**,不要「第 1 页讲…第 2 页讲…」的流水账
|
|
123
|
+
- 保留**具体数值与例题**(频率、周期、系数、答案)—— 复习时最有用
|
|
124
|
+
- 保留**易错点**(老师标红 / 打问号的地方)
|
|
125
|
+
- **Mermaid mindmap 节点文本不要含 `(` `)` `[` `]` 等符号**,会破坏渲染。例如写 `系统通用框图 y 等于 T 作用于 x`,不要写 `y=T[x]`
|
|
126
|
+
- 汇总这种长文档**交给子代理写**,只让它回一行 `DONE chars=N`
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## 目录约定
|
|
131
|
+
|
|
132
|
+
```
|
|
133
|
+
知识整理\
|
|
134
|
+
├── README.md ← 项目总览
|
|
135
|
+
├── _进度.md ← 进度台账(每次完工必须更新)
|
|
136
|
+
├── _源清单.md ← 源文件盘点
|
|
137
|
+
├── <课程>\<单元>.md ← 正式成品
|
|
138
|
+
├── _源文本\<课程>\...md ← 从 PPT 直接抽的文字(零误差原料)
|
|
139
|
+
├── _源图\<课程>-<序号>\imageN.png ← 从纯图片 PPT 无损导出的原图
|
|
140
|
+
└── _讲稿\<课程>-<序号>\slides-*.md ← 逐页看图笔记(中间产物)
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
`_` 开头的是原料/中间产物;正式成品放 `<课程>\` 下。
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## 硬性纪律
|
|
148
|
+
|
|
149
|
+
- **准确第一**:看不清就写「字迹不清」,绝不猜。猜错比不写危害大得多。
|
|
150
|
+
- **不做 OCR**:系统 OCR 读公式是垃圾(`f(t)`→`无@)`、`冲激`→`冫中激`)。有原图就看原图。
|
|
151
|
+
- **不要打印长表格**:子代理把结果写文件,只回一行摘要。
|
|
152
|
+
- **覆盖已存在的文件前必须先 read**(fs-observation-policy 会拒绝未读就写)。
|
|
153
|
+
- 如果原始 PPTX 是**整页图片版**,同时告诉用户「这份 PPT 本身没有文字层,只能看图」,
|
|
154
|
+
并按第 -1 步的月份目录找找有没有别的版本(通常对得上,幻灯片数一致)。
|
|
155
|
+
|
|
156
|
+
---
|
|
157
|
+
|
|
158
|
+
## 环境与踩坑
|
|
159
|
+
|
|
160
|
+
- 🚨 **起子进程不要用 `Start-Process powershell.exe`** —— 会**在用户屏幕上弹出 PowerShell 窗口**。
|
|
161
|
+
默认在当前会话**内联**跑:
|
|
162
|
+
|
|
163
|
+
```powershell
|
|
164
|
+
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
|
|
165
|
+
& "<脚本路径>" -Arg ...
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
只有确实需要硬超时杀进程时才用 `Start-Process`,且**必须加 `-WindowStyle Hidden`**。
|
|
169
|
+
- 本机常为 Windows PowerShell 5.1(无 pwsh 7)→ shell 是 `C:\WINDOWS\System32\WindowsPowerShell\v1.0\powershell.exe`;
|
|
170
|
+
跑 `.ps1` **必须**加 `-ExecutionPolicy Bypass`(内联用 `-Scope Process` 那次),否则报 `AuthorizationManager 检查失败 / UnauthorizedAccess`。
|
|
171
|
+
- 脚本文件存 **UTF-8 带 BOM**,否则 PowerShell 5.1 读中文乱码。
|
|
172
|
+
- Python:见文末附录(需要 python-pptx / lxml / Pillow 的场景用带这些库的解释器)。
|
|
173
|
+
- 路径含中文和空格,命令里务必加引号。
|