diff --git a/CHANGELOG.md b/CHANGELOG.md index f3dc15c..855b62c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ ## Unreleased ### Added +- **文档**:中层标准库 Mid 之后缺口盘点与 Mid2(M7–M10)设计/路线——[stdlib-gaps-after-mid.md](doc/research/stdlib-gaps-after-mid.md) · [stdlib-mid2.md](doc/design/stdlib-mid2.md) · [stdlib-mid2.md](doc/roadmap/stdlib-mid2.md)。 ### Fixed - **`host_query` / GLOBAL_HOST**:嵌套 `call_registered` 结束后恢复外层宿主指针,不再清空;`web_listen` 多轮 `invoke`(中间再调插件)不再报 `no active host context`。 diff --git a/doc/README.md b/doc/README.md index 0fbce99..7b1b39b 100644 --- a/doc/README.md +++ b/doc/README.md @@ -32,6 +32,11 @@ | [design/stdlib.md](design/stdlib.md) | **标准库:内置 + `lib/` + 错误约定** | | [design/stdlib-i18n.md](design/stdlib-i18n.md) | **标准库中英命名:靠库文件名区分,无 lang 开关** | | [design/stdlib-modules.md](design/stdlib-modules.md) | **L1:文件/系统/时间/JSON/网络/数学/外联/插件** | +| [design/stdlib-mid.md](design/stdlib-mid.md) | **中层 Mid M1–M6(已落地)** | +| [design/stdlib-mid2.md](design/stdlib-mid2.md) | **中层 Mid2:datetime / url / toml / html / fs++** | +| [research/stdlib-gaps-after-mid.md](research/stdlib-gaps-after-mid.md) | **Mid 之后缺口盘点**(对照 Python/Go) | +| [roadmap/stdlib-mid.md](roadmap/stdlib-mid.md) | **Mid M1–M6 路线(done)** | +| [roadmap/stdlib-mid2.md](roadmap/stdlib-mid2.md) | **Mid2 M7–M10 路线(规划)** | | [design/stdlib-math.md](design/stdlib-math.md) | **数学库(数值/随机/作图/轻量求解)** | | [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— 已落地** | | [design/ext-abi.md](design/ext-abi.md) | **原生插件 C ABI v1**(`lib/plugin`) | diff --git a/doc/design/stdlib-mid.md b/doc/design/stdlib-mid.md index a6584dc..bf79291 100644 --- a/doc/design/stdlib-mid.md +++ b/doc/design/stdlib-mid.md @@ -4,7 +4,7 @@ |---|---| | 状态 | **M1–M6 已落地** | | 日期 | 2026-09-07 | -| 相关 | [stdlib.md](stdlib.md) · [stdlib-modules.md](stdlib-modules.md) · [ext-abi.md](ext-abi.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) | +| 相关 | [stdlib.md](stdlib.md) · [stdlib-modules.md](stdlib-modules.md) · [ext-abi.md](ext-abi.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) · **后续** [stdlib-mid2.md](stdlib-mid2.md) · [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md) | | 目标 | 在接下来数个发版周期内,把「通用编程」能力沉到 **L0.5 宿主 + L1 `.mq.md`**,减少「凡是稍有能力就必须 ABI 插件」的路径依赖 | --- @@ -123,10 +123,12 @@ OS / 算法库(精选 crate,默认 features 最小化) | **M3** | `hash` / `哈希` · `secrets` / `机密` | sha256 / hmac;token | **done** | | **M4** | `csv` / `逗号表` · `text` 加厚 | parse / stringify;contains / replace | **done** | | **M5** | `table` 加厚 · `cli` / `命令行` | sort / zip;flags | **done** | -| **M6** | `log` / `日志` · `uuid` / `标识` | level 日志;v4 | 薄 host 或纯 mq | -| **可选** | `yaml` / `Toml` | 仅当 public/catalog 强需求 | 慎入 | +| **M6** | `log` / `日志` · `uuid` / `标识` | level 日志;v4 | **done** | +| **可选(Mid1)** | `yaml` | 默认 **不做** | 见 Mid2:优先 TOML | -**刻意延后:** 完整 `datetime` 时区库、连接池、异步 runtime、模板引擎、完整 `collections` 类型系统——等中层前几波用起来再议。 +**Mid1 刻意延后、现已升格到 Mid2:** 日历/时区、URL 解析 —— 见 [stdlib-mid2.md](stdlib-mid2.md) · [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md)。 + +**仍不准入 Mid:** 连接池、异步 runtime、模板引擎、完整 `collections` 类型系统、HTTP 服务端 / SQLite(`ext/`)。 --- diff --git a/doc/design/stdlib-mid2.md b/doc/design/stdlib-mid2.md new file mode 100644 index 0000000..66598e3 --- /dev/null +++ b/doc/design/stdlib-mid2.md @@ -0,0 +1,139 @@ +# 设计:中层标准库第二波(Mid2 · M7–M10) + +| | | +|---|---| +| 状态 | **Draft · 锁定方向** | +| 日期 | 2026-09-08 | +| 缺口盘点 | [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md) | +| 路线图 | [stdlib-mid2.md](../roadmap/stdlib-mid2.md) | +| 宪法 | [stdlib-mid.md](stdlib-mid.md) §3(准入 / 不准入 **不变**) | +| 目标 | 在 M1–M6 之上补「日历 · URL · 配置 · HTML 安全 · fs 再厚」,仍保持宿主面积极小 | + +--- + +## 0. 一句话 + +**Mid2 = 第二档通用原语,不是第二套 stdlib。** 仍落在 `lib/` + 薄 `host_*`;禁止借机引入 YAML 全家桶、HTTP 服务端、数据库。 + +--- + +## 1. 分层与禁止 + +| 允许 | 禁止 | +|------|------| +| 新 `lib/*.mq.md` 中英对偶 | 新开 `lib-mid2/` 目录树 | +| 少数 `host_datetime_*` / `host_url_*` / `host_toml_parse` | 为 Mid 新增 ABI 插件 | +| 加厚既有 `fs` / `encoding` / `net` / `text` | 把 `ext/web` 能力下沉进 `lib/net` 服务端 | +| TOML **只读** | 完整 YAML 1.2、任意对象反序列化 | +| HTML **转义** | 模板引擎 / CSS 选择器引擎 | + +--- + +## 2. M7 — `datetime` + `url` + +### 2.1 `lib/datetime.mq.md` / `lib/日期时间.mq.md` + +| 函数(英) | 中文建议 | 行为 | +|------------|----------|------| +| `now` | `现在` | 返回结构化时刻(见下)或 ISO 文本(二选一,实现时锁定) | +| `from_unix` / `to_unix` | `自戳` / `成戳` | 秒级;可选 `ms` | +| `parse` | `解析` | 支持 RFC3339 / 常见 `YYYY-MM-DD[ HH:MM:SS]` | +| `format` | `格式化` | strftime 子集或命名样式 `rfc3339`/`date`/`time` | +| `add` | `加` | `days`/`hours`/`minutes`/`seconds` 具名 | +| `in_zone` | `时区` | IANA 名或 `+08:00`;失败 → 诊断 | + +**结构化时刻(建议 map)**:`{unix, zone, iso}` 或宿主不透明柄 + `_type=datetime`。优先 **map + 稳定字段**,便于 GFM/table 协作。 + +**刻意不做**:农历、营业日、完整 tzdb 热更新 UI、闰秒政治。 + +### 2.2 `lib/url.mq.md` / `lib/地址.mq.md`(或并入 `net`) + +| 函数 | 行为 | +|------|------| +| `parse` | → `{scheme, userinfo, host, port, path, query, fragment}` | +| `query_parse` | `a=1&b=2` → map(多值用列表) | +| `query_stringify` | map → query | +| `join` | base + relative(可选,可二期) | + +既有 `net.url_encode` **保留**;文档写清:编码单段用 `net`/`encoding`,解析整 URL 用 `url`。 + +**验收**:金样解析带 query 的 HTTPS URL;往返 query。 + +--- + +## 3. M8 — `toml` + `html` + `encoding` 加厚 + +### 3.1 `lib/toml.mq.md` / `lib/Toml.mq.md`(或 `配置表`) + +| 函数 | 行为 | +|------|------| +| `parse` | TOML 文本 → Marqdo map/list(只读) | + +**不做** `stringify`(首版);需要写出时继续用 JSON。动机对齐 PEP 680:配置引导,而非通用文档格式战争。 + +### 3.2 HTML 转义 + +二选一(实现时定一): + +- A:`lib/html.mq.md` · `escape` / `unescape` +- B:`text.html_escape` / `text.html_unescape` + +推荐 **A**(安全语义独立可见)。 + +### 3.3 `encoding` 加厚 + +| 函数 | 行为 | +|------|------| +| `base32_encode` / `base32_decode` | RFC 4648 | +| (可选)`percent_decode` | 与 `url` 协作 | + +--- + +## 4. M9 — `fs` 加厚 + +| 函数 | 行为 | +|------|------| +| `make_dirs` | 递归创建 | +| `remove_tree` | 递归删除(目录) | +| `stat` | `{size, mtime_unix, is_file, is_dir}` | +| `walk` | 返回路径列表(深度优先或广度;文档锁定) | + +**不做**:权限 ACL、watch/inotify、硬链接全家桶。 + +--- + +## 5. M10 — 收口糖(可选) + +| 项 | 说明 | +|----|------| +| `lib/stats` 或 `math.mean`/`median`/`stdev` | 极薄;非 pandas | +| `log` 结构化字段 | 可选 `fields=` map;非完整 slog 生态 | +| `zip` 读写 | **默认跳过**;有明确 Release 需求再开 | + +--- + +## 6. 宿主与 WASM + +| Host | WASM | +|------|------| +| `datetime` / `url` / `toml` / `html` / `fs.stat` | 尽量可进;IANA tz 数据体积需评估(可 host-only + 文档标注) | +| `fs.walk` / `remove_tree` | host-only 可接受 | + +新 crate 写进 [dependencies.md](dependencies.md);禁止顺手拉大型框架。 + +--- + +## 7. 作者面风格 + +- 中英分文件;形参表声明全部可选并转发 `host_*`。 +- 数据优先 GFM / `table`;`json` 仍只 parse/stringify/quote。 +- 每波:设计短文 → host → lib → `tests/lib/*` → `public/features` 短页。 + +--- + +## 8. 完成定义(Mid2 整包) + +1. 作者可用 `datetime` + `url` + `toml.parse` + `html.escape` 写配置驱动脚本,无需 foreign。 +2. `fs.stat` / `make_dirs` 金样绿。 +3. 研究文高优先级缺口标 closed;YAML/模板/sqlite 仍标明 won't。 +4. [stdlib-modules.md](stdlib-modules.md) 总表更新;`stdlib.md` 状态改为 Mid2 进行中/完成。 diff --git a/doc/design/stdlib-modules.md b/doc/design/stdlib-modules.md index 80dd592..6c3bd6b 100644 --- a/doc/design/stdlib-modules.md +++ b/doc/design/stdlib-modules.md @@ -2,10 +2,10 @@ | | | |---|---| -| 状态 | **核心已落地**;**中层 Mid:M1–M6 已落地** · [stdlib-mid.md](stdlib-mid.md) / [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) | -| 日期 | 2026-09-07 | +| 状态 | **核心已落地**;**Mid M1–M6 已落地**;**Mid2 规划中** · [stdlib-mid2.md](stdlib-mid2.md) / [roadmap/stdlib-mid2.md](../roadmap/stdlib-mid2.md) | +| 日期 | 2026-09-08 | | 原则 | 全部经 frontmatter **导入**;除 JSON 外中英分文件;内核保持少而精;**通用能力优先 Mid,插件留给领域核** | -| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-mid.md](stdlib-mid.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [**module-namespace.md**](module-namespace.md)(导入命名空间;**M1/M2 已落地**:`库.成员` / `库.对象.成员` / `use`) | +| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-mid.md](stdlib-mid.md) · [stdlib-mid2.md](stdlib-mid2.md) · [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [**module-namespace.md**](module-namespace.md)(导入命名空间;**M1/M2 已落地**:`库.成员` / `库.对象.成员` / `use`) | --- @@ -42,6 +42,8 @@ **中层已落地:** M1–M6(含 log / uuid)— 见 [stdlib-mid.md](stdlib-mid.md) · [stdlib-log-uuid.md](stdlib-log-uuid.md)。 +**下一波 Mid2(规划,未进表):** `datetime` · `url` · `toml`(只读)· `html.escape` · `fs` 再厚 — [stdlib-mid2.md](stdlib-mid2.md) · [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md)。 + 设计细节:[stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md)。 --- diff --git a/doc/design/stdlib.md b/doc/design/stdlib.md index 7ed0262..e2502e4 100644 --- a/doc/design/stdlib.md +++ b/doc/design/stdlib.md @@ -2,13 +2,14 @@ | | | |---|---| -| 状态 | **S0–S3 + 核心 L1 已落地 · 中层 L1(Mid)规划中** | -| 日期 | 2026-09-07 | -| 相关 | [keywords.md](keywords.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [**stdlib-mid.md**](stdlib-mid.md) · [module-namespace.md](module-namespace.md) · [ext-abi.md](ext-abi.md) | +| 状态 | **S0–S3 + 核心 L1 已落地 · Mid M1–M6 已落地 · Mid2(M7–M10)规划中** | +| 日期 | 2026-09-08 | +| 相关 | [keywords.md](keywords.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [**stdlib-mid.md**](stdlib-mid.md) · [**stdlib-mid2.md**](stdlib-mid2.md) · [module-namespace.md](module-namespace.md) · [ext-abi.md](ext-abi.md) | > **多语言库命名**:见 [stdlib-i18n.md](stdlib-i18n.md)(不设 `lang:`;中英分文件)。 > **L1 模块清单**(含 math/foreign/plugin):见 [stdlib-modules.md](stdlib-modules.md)。 -> **中层标准库(数个版本)**:通用原语沉 `lib/`、减少「事事插件」——设计 [stdlib-mid.md](stdlib-mid.md) · 路线 [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md)。 +> **中层标准库 Mid(M1–M6)**:已落地——[stdlib-mid.md](stdlib-mid.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md)。 +> **中层第二波 Mid2**:日历/URL/TOML/HTML/fs++ ——[stdlib-mid2.md](stdlib-mid2.md) · [roadmap/stdlib-mid2.md](../roadmap/stdlib-mid2.md) · 缺口 [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md)。 > **`ext/` 不是 stdlib**:官方可选扩展见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。 --- @@ -19,7 +20,8 @@ |----|------| | **L0 内置** | 解释器内:`print` `input` `len` `str` `int` `type` `trim` `split` `join` `at`(`type` 可含 `map`) | | **L1 核心** | 已有 [`lib/`](../../lib/):fs/sys/time/json/net/math/foreign/plugin/table/text/… | -| **L1 中层(Mid)** | 规划中:re / encoding / path / hash / csv / … — 仍在 `lib/`,见 [stdlib-mid.md](stdlib-mid.md) | +| **L1 中层(Mid)** | **已落地** re / encoding / path / hash / secrets / csv / text++ / table++ / cli / log / uuid — [stdlib-mid.md](stdlib-mid.md) | +| **L1 Mid2** | **规划**:datetime / url / toml / html / fs++ — [stdlib-mid2.md](stdlib-mid2.md) | | **官方 ext** | [`ext/`](../../ext/)(`.mq.md` + 可选原生插件);`MARQDO_EXT`;**不属于** L1;插件仅领域热路径 | | **L2** | catalog / 用户站收录(随发版);应主要靠核心+中层、默认无插件 | diff --git a/doc/research/stdlib-gaps-after-mid.md b/doc/research/stdlib-gaps-after-mid.md new file mode 100644 index 0000000..6b495aa --- /dev/null +++ b/doc/research/stdlib-gaps-after-mid.md @@ -0,0 +1,144 @@ +# 调研:Mid M1–M6 之后标准库还缺什么 + +| | | +|---|---| +| 状态 | **调研笔记 · 缺口盘点(M1–M6 闭环之后)** | +| 日期 | 2026-09-08 | +| 基线 | **v0.3.7+** · Mid M1–M6 **done** | +| 已落地设计 | [stdlib-mid.md](../design/stdlib-mid.md) · [stdlib-modules.md](../design/stdlib-modules.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) | +| 补齐设计 | [stdlib-mid2.md](../design/stdlib-mid2.md) | +| 实现路线 | [stdlib-mid2.md](../roadmap/stdlib-mid2.md) | +| 外部对照 | Python stdlib([use-case 索引](https://www.socratopia.app/library/python-programming-ai-era-en/chapter-15) · [PEP 680 tomllib](https://peps.python.org/pep-0680/))· Go `strings`/`regexp`/`encoding/*`/`crypto`/`path`/`time`/`net/url` · Node 内置 vs userland | + +--- + +## 0. 一句话结论 + +**M1–M6 已把「写日常脚本 / 多数扩展库不再事事插件」的硬缺口补齐。** 相对 Python / Go 的「通用原语层」,Marqdo **不再缺** 正则、编解码、路径、哈希、CSV、集合糖、CLI、日志、UUID。 + +仍缺的是 **第二档通用能力**:日历与时区、URL/查询串、配置格式(优先 TOML)、HTML 安全转义、文件系统再厚一点(`mkdir -p` / 元数据 / 递归删除)、轻量统计。这些**值得开 Mid2(M7+)**,但**不应**再开一轮「事事插件」;也**不要**把 YAML 全家桶、HTTP 服务端、SQLite、图像/ML 塞进 `lib/`。 + +--- + +## 1. 已有基线(不是缺口) + +| 族 | Marqdo | 对标 | +|----|--------|------| +| 文本 / 正则 | `text`++ · `re` | Python `str`/`re` · Go `strings`/`regexp` | +| 编解码 | `encoding`(base64/hex)· `net.url_encode` | Go `encoding/base64`/`hex` · Python `base64`/`binascii` | +| 路径 / 文件 | `path` · `fs`(含 copy/move/temp) | Go `path/filepath` · Python `pathlib`(子集) | +| 完整性 / 机密 | `hash` · `secrets` | Go `crypto` 子集 · Python `hashlib`/`secrets` | +| 表数据 | `csv` · `table`++ · `json` | Go `encoding/csv`/`json` · Python `csv`/`json` | +| CLI / 可观测 | `cli` · `log` · `uuid` | Python `argparse`/`logging`/`uuid`(窄) | +| 时间(极简) | `time`:unix/ms · format · parse · sleep | **远薄于** Python `datetime`/`zoneinfo` · Go `time` | +| 网络客户端 | `net`:HTTP/SSE/cookie/multipart/markdown | Go `net/http` **客户端**侧;服务端在 `ext/web` | +| 数学 | `math`(含公式/作图) | Python `math` + 教学向扩展 | + +准入宪法仍见 [stdlib-mid.md](../design/stdlib-mid.md) §3:跨领域、难写对、解锁无插件写库、宿主面积极小。 + +--- + +## 2. 对照总表(按「脚本作者是否还要 foreign / 自造轮子」) + +| 能力 | Python / Go 常态 | Marqdo 现状 | 缺口级别 | Mid2 建议 | +|------|------------------|-------------|----------|-----------| +| 日历日期 / 时区 / timedelta | `datetime`+`zoneinfo` · `time` | 仅 unix 戳 + 简单 format/parse | **高** | **M7** `datetime` | +| URL 解析 / 查询串 | `urllib.parse` · `net/url` | 仅 `url_encode` | **高** | **M7** `url`(或并入 `net`) | +| 配置 TOML 只读 | `tomllib`(PEP 680) | 无 | **中高** | **M8** `toml`(只读优先) | +| 配置 YAML | 第三方;**故意不进** CPython | 无 | **低 / 慎入** | 默认 **不做**;与 Python 同理(复杂度/安全) | +| HTML / XML 转义 | `html` · `html/template` 转义 | 无(`markdown_parse` ≠ 转义) | **中** | **M8** `html` 或 `text.html_escape` | +| `mkdir -p` / 递归删 / stat | `pathlib`/`shutil` | `make_dir`/`remove` 偏浅 | **中** | **M9** `fs` 加厚 | +| 文件元数据(size/mtime) | `os.stat` · `Path.stat` | 无一等 API | **中** | **M9** | +| base32 / percent 完整 | `base64.b32*` · `url` | 无 base32 | **低–中** | **M8** `encoding` 加厚 | +| 轻量统计 | `statistics` | `math` 无 mean/median | **低–中** | **M10** `stats` 或 `math` 薄加 | +| 计数 / 默认字典 / deque | `collections` | `table` 可凑 | **低** | 优先用 `table`;必要时 M10 `collections` 极薄 | +| 组合迭代 | `itertools` | 无 | **低** | 多数可用 `table`;**延后** | +| 模板引擎 | Jinja / Go `text/template` | 无 | **不准入 Mid** | 应用层 / 未来 ext | +| SQLite 客户端 | `sqlite3` · `database/sql` | **`ext/web` `# db`** | **不准入** | 保持扩展 | +| HTTP 服务端 | — | **`ext/web`** | **不准入** | 已关闭(宿主波次另文) | +| 密码哈希 Argon2 | 第三方 / 框架 | `ext/web` 已有 | **不准入 Mid** | 安全产品面 | +| 完整 TLS/证书 API | `ssl` · `crypto/tls` | 客户端 HTTPS 由 ureq | **不准入** | 宿主实现细节即可 | +| 压缩 zip/tar | `zipfile` · `archive/zip` | 无 | **低** | 可选 M10;体积敏感 | +| 环境 `.env` | 第三方;Go 常自写 | **`sys.load_dotenv` 已有** | 无 | — | + +--- + +## 3. 分项说明(高优先级) + +### 3.1 日历 / 时区(M7 候选之首) + +**问题** +脚本与站点大量需要「今天」「本地日界」「RFC3339」「时区换算」。现有 `time.parse`/`format` 够演示,不够「难写对」的日历语义(闰秒除外,但 DST / offset 已够劝退字符串拼接)。 + +**对照** +Python 强调 **aware datetime + zoneinfo**;Go `time.Location` 是日常依赖。Mid 原文已把「完整 datetime 时区库」标为刻意延后——M1–M6 完成后应升格。 + +**建议窄 API(设计文锁定)** +`now` / `parse` / `format` / `add`(天/时)/ `to_unix` / `from_unix` / 可选 `in_zone`(IANA 或固定 offset)。**不做**完整历法 UI、农历、业务假期库。 + +### 3.2 URL 与查询串 + +**问题** +`url_encode` 只解决「编码一段」;解析 `https://a/b?x=1&y=2#frag`、合并 query、取 path 仍靠 `re` 自造。浏览器代理 / `invoke` / webhook 场景高频。 + +**建议** +`url.parse` → `{scheme,host,path,query,fragment}`;`url.query_parse` / `query_stringify`;与 `url_encode` 边界写进 `net` vs 新 `lib/url`。 + +### 3.3 TOML vs YAML + +**外部事实** +Python 因 **打包引导**(`pyproject.toml`)接受只读 `tomllib`([PEP 680](https://peps.python.org/pep-0680/));YAML 多次被拒:规范复杂、实现难维护、安全面大。 + +**对 Marqdo** +catalog / 工具配置若走向 TOML,只读 `toml.parse` 性价比高。YAML:**默认不准入 Mid**;若 public 强需求,单独 ADR,且优先「JSON 超集子集」而非完整 1.2。 + +### 3.4 HTML 转义 + +**问题** +`ext/web` 与浏览器 WASM 拼 HTML 时,缺 `escape` 易 XSS。这是「难写对 / 安全相关」的经典 stdlib 项(Python `html.escape`)。 + +**建议** +极薄:`html.escape` / `unescape`(或挂 `text`)。**不做** DOM / 模板语言。 + +### 3.5 文件系统再厚 + +**问题** +`make_dir` 是否递归、`remove` 是否递归、无 `stat`(size/mtime)、无 `walk`——脚本仍会 `foreign` 或脆弱字符串。 + +**建议** +`fs.make_dirs` · `fs.remove_tree` · `fs.stat` · 可选 `fs.walk`(返回路径列表,非惰性迭代器协议)。 + +--- + +## 4. 明确「不是缺口」 + +| 项 | 说明 | +|----|------| +| Mid M1–M6 清单本身 | 已收口;不要用本表重开 base64/re | +| HTTP 服务 / DB / Agent | `ext/*`;见 [ext-hosting](ext-hosting-gaps.md) | +| Dense embedding / 向量库默认化 | OKF 路线不变 | +| 完整 `collections` / `itertools` 类型系统 | 语言没有泛型迭代协议;用 `table` | +| 「对齐 Python 模块个数」 | 反模式;对齐**用例与难写对** | + +--- + +## 5. 优先级建议(转入 Mid2) + +| 优先级 | 波次草案 | 内容 | +|--------|----------|------| +| **高** | **M7** | `datetime`(日历/时区子集)+ `url`(parse/query) | +| **高** | **M8** | `toml` 只读 + `html.escape` + `encoding` base32 | +| **中** | **M9** | `fs` 加厚(dirs/stat/walk) | +| **低** | **M10** | `stats` 薄 · 可选 zip · 结构化 log 字段 | +| **won't** | — | 完整 YAML · 模板引擎 · sqlite 进 `lib/` | + +--- + +## 6. 与其它文档 + +| 文档 | 关系 | +|------|------| +| [stdlib-mid2.md](../design/stdlib-mid2.md) | **补齐设计(作者 API + 边界)** | +| [stdlib-mid2.md](../roadmap/stdlib-mid2.md) | 实现波次 M7–M10 | +| [stdlib-mid.md](../design/stdlib-mid.md) | Mid1 宪法;本调研不改准入原则 | +| [web-net-capabilities.md](../design/web-net-capabilities.md) | 网络服务端能力在 ext,不进 Mid2 | diff --git a/doc/roadmap/next-phase.md b/doc/roadmap/next-phase.md index 614332a..ed4b61c 100644 --- a/doc/roadmap/next-phase.md +++ b/doc/roadmap/next-phase.md @@ -18,7 +18,7 @@ | **诊断** | 语句级 `path:line:col: message`;字节码指令带 `spans`;errors 金样例双后端断言位置 | **P0 完成** | | **view** | 结构 + 执行 + 源码 + 函数大纲/搜索;无断点 | 文档浏览器 | | **debug** | 独立 `marqdo debug`:断点 / 单步 / locals(树遍历) | **P3-D3 v1** | -| **标准库** | 核心 L1 已完成([stdlib-modules.md](../design/stdlib-modules.md));下一主线 = **中层 Mid**([stdlib-mid.md](../design/stdlib-mid.md) · [stdlib-mid 路线](stdlib-mid.md)) | **P2 完成;Mid M1–M6 规划中** | +| **标准库** | 核心 L1 + Mid M1–M6 已完成([stdlib-modules.md](../design/stdlib-modules.md));下一主线 = **Mid2**([stdlib-mid2.md](../design/stdlib-mid2.md) · [stdlib-mid2 路线](stdlib-mid2.md) · [缺口](../research/stdlib-gaps-after-mid.md)) | **P2 + Mid1 完成;Mid2 规划中** | | **模块** | [module-namespace.md](../design/module-namespace.md):**M1+M2 已落地**(库名绑定、`库.成员` / `use`;无扁平合并) | — | 用户点名的三件事都对,但**不能并行硬开**:断点调试依赖「可信位置 + 可暂停执行」;标准库依赖稳定运行时与 I/O;`input` 在 CLI 与 view 是两条路径。 diff --git a/doc/roadmap/stdlib-mid.md b/doc/roadmap/stdlib-mid.md index a9e9e01..bf9ebf8 100644 --- a/doc/roadmap/stdlib-mid.md +++ b/doc/roadmap/stdlib-mid.md @@ -2,9 +2,10 @@ | | | |---|---| -| 状态 | **M1–M6 已落地** | +| 状态 | **M1–M6 已落地**(收口) | | 日期 | 2026-09-07 | | 设计 | [stdlib-mid.md](../design/stdlib-mid.md) | +| 后续 | [stdlib-mid2.md](stdlib-mid2.md) · [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md) | | 相关 | [stdlib-modules.md](../design/stdlib-modules.md) · [next-phase.md](next-phase.md) · [ext-cli.md](../design/ext-cli.md) | > **不预标 SemVer。** 每一波随当时产品发版合入;下文用 **M1…M6** 波次名。每波须可单独演示、可回滚。 diff --git a/doc/roadmap/stdlib-mid2.md b/doc/roadmap/stdlib-mid2.md new file mode 100644 index 0000000..db50824 --- /dev/null +++ b/doc/roadmap/stdlib-mid2.md @@ -0,0 +1,88 @@ +# 路线图:中层标准库第二波(M7–M10) + +| | | +|---|---| +| 状态 | **Active · 规划** | +| 日期 | 2026-09-08 | +| 设计 | [stdlib-mid2.md](../design/stdlib-mid2.md) | +| 缺口 | [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md) | +| 前序 | [stdlib-mid.md](stdlib-mid.md)(**M1–M6 done**) | +| 基线 | v0.3.7+ | + +> **不预标 SemVer。** 波次名 **M7…M10**;每波可单独演示、可回滚。 + +--- + +## 0. 总序 + +```text +M7 时间与地址 datetime + url +M8 配置与安全字面 toml(只读) + html.escape + encoding/base32 +M9 文件再厚 fs make_dirs / remove_tree / stat / walk +M10 收口糖(可选) stats 薄 · log 字段 · (zip 默认跳过) +``` + +原则: + +1. 继承 Mid1 宪法:通用、难写对、小宿主、可冻 API。 +2. **TOML 优先于 YAML**(对齐 PEP 680 教训)。 +3. 不阻塞宿主 / ext 产品线;但新「通用」ABI 插件默认拒绝。 + +--- + +## 1. 波次明细 + +### M7 — datetime + url — **todo** + +| 交付 | 说明 | +|------|------| +| `lib/datetime` · `日期时间` | now/parse/format/add/unix/zone 子集 | +| `lib/url` · `地址`(或 `net` 加厚) | parse · query_parse/stringify | +| Host | `host_datetime_*` · `host_url_*` | +| 金样 | `tests/lib/datetime-smoke` · `url-smoke` | +| public | 短页「解析带时区的时间戳 / 拆 query」 | + +**刻意不做:** 农历、完整 tz 管理 UI、URL 规范化全部 WHATWG 边角。 + +### M8 — toml + html + encoding — **todo** + +| 交付 | 说明 | +|------|------| +| `lib/toml` 只读 `parse` | 配置引导 | +| `lib/html` `escape`/`unescape` | XSS 底线 | +| `encoding` base32 | RFC 4648 | +| 金样 | `toml-smoke` · `html-escape-smoke` · `encoding-base32` | + +**刻意不做:** YAML;TOML stringify(可后期)。 + +### M9 — fs 加厚 — **todo** + +| 交付 | 说明 | +|------|------| +| `make_dirs` / `remove_tree` / `stat` / `walk` | 见设计文 | +| 金样 | `fs-mid2-smoke` | + +### M10 — 可选收口 — **todo** + +| 交付 | 说明 | +|------|------| +| `stats` 或 `math` 均值/中位数 | 薄 | +| `log` 可选 `fields=` | 非远程 sink | +| zip | **默认跳过** | + +--- + +## 2. 进度勾选 + +- [ ] M7 datetime + url +- [ ] M8 toml + html + base32 +- [ ] M9 fs 加厚 +- [ ] M10 可选 +- [ ] 研究文高优先级缺口 → closed +- [ ] `stdlib-modules.md` / `stdlib.md` 状态同步 + +--- + +## 3. 成功标准 + +对外可宣称:在 Mid1(文本/路径/哈希/CSV/CLI/日志)之上,**日历、URL、TOML 配置、HTML 转义、实用 fs** 无需外联即可完成常见脚本与 catalog 工具——领域能力仍在 `ext/`。