From 57e23552d1e4c49a5fe6041d88784eac542c9f99 Mon Sep 17 00:00:00 2001 From: cruldra Date: Thu, 15 Oct 2026 20:08:59 +1100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs(code-reader):=20=E8=A7=84?= =?UTF-8?q?=E6=A0=BC=E8=A1=A5=E4=B8=8A=E5=87=BD=E6=95=B0=E4=BD=93=E9=87=8C?= =?UTF-8?q?=20let=E3=80=81=E8=BF=94=E5=9B=9E=E5=80=BC=E7=9A=84=20sqlx=20/?= =?UTF-8?q?=20axum=20=E5=8D=A1=E7=89=87=E5=92=8C=20sqlx=20=E5=87=BD?= =?UTF-8?q?=E6=95=B0=E5=86=99=E6=B3=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/superpowers/specs/code-reader/spec.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/superpowers/specs/code-reader/spec.md b/docs/superpowers/specs/code-reader/spec.md index a9a2604..9d369d0 100644 --- a/docs/superpowers/specs/code-reader/spec.md +++ b/docs/superpowers/specs/code-reader/spec.md @@ -1825,10 +1825,12 @@ react.component 23 文件导入了对应 crate 才启用（来源等于 crate 名，或以 `crate::` 开头）。tokio 不单独做卡片，异步已经写在函数上。样例 `fixtures/rustLibs.rs`。 +axum 的 `Router`、sqlx 的查询写在函数体里时，语句看整句、`let` 看初始值、返回块看返回的值（`rules/rustRows.ts` 的 `valueCard`，两条规则共用）。认领 `let` 时卡片第一行是「变量」（变量名照翻，卡片和这一行的定义范围都是它，同没认领时的变量块）；`let … else` 的 else、实参里的闭包照常是卡片的子块；块原来的「变量」「返回」概念照常排在卡片种类前面。 + - serde（`rules/serde.ts`，`libraries: ['serde']`）：`derive` 了 `Serialize` 或 `Deserialize` 的结构体。种类 `serde.struct`，标签「可序列化」，图标 `braces`，颜色同结构体（暗 #4ec9b0 / 亮 #267f99）。名称后面再标一个「可序列化」。`rename_all = "camelCase"` 收成选项「字段名改驼峰」。字段表多一列「序列化」：`rename` 写「改名 xxx」，`skip` / `skip_serializing` 写「不输出」，没标是「—」。说明里的 `@param` 同结构体对到字段表的「说明」列。 - thiserror（`rules/thiserror.ts`，`libraries: ['thiserror']`）：`derive` 了 `Error` 的枚举。种类 `thiserror.error`，标签「错误」，图标 `triangle-alert`，颜色同异常（暗 #f14c4c / 亮 #cd3131）。变体表「变体 | 何时 | 展示」：何时是变体上面的文档注释，展示是 `#[error("…")]` 的文案。变体上的 `#[from]` 或 `#[source]` 在展示后面标「透传来源」。 -- axum（`rules/axum.ts`，`libraries: ['axum']`）：处理函数上的 `#[get("/path")]`、`#[axum::post(…)]` 等（get / post / put / delete / patch / head / options / trace），或顶层语句里 `Router` 的 `.route(路径, get(函数))`。函数已经标了路由属性时，这句 `route` 不再单独成卡。种类 `axum.route`，标签「接口」，图标 `globe`，颜色同 FastAPI 接口（暗 #61afef / 亮 #1a6fb5）。属性表：名称、说明、异步（是）、请求（一项「方法」、一项「路径」、路径里的 `{名字}` 对上参数写成「路径参数」，`Path(id): Path` 写 `id: Uuid`）、参数（说明里写了 `@param` 才有：参数是 `Path(id)` 这类模式，不对名字，照写成「名称 \| 说明」表）、返回（`@return` 跟在后面）、异常（`@throws`）。 -- sqlx（`rules/sqlx.ts`，`libraries: ['sqlx']`）：`query!` / `query_as!` / `query_scalar!`。种类 `sqlx.query`，标签「查询」，图标 `database`，颜色暗 #ce9178 / 亮 #a31515。前面的注释同别的块，是卡片的「注释」一行（宿主插在第一行 SQL 后面）。SQL 原文等宽，参数 `$1` 对上传入的表达式，`query_as!` / `query_scalar!` 的第一个实参是返回类型，`query!` 的返回类型是「—」。 +- axum（`rules/axum.ts`，`libraries: ['axum']`）：处理函数上的 `#[get("/path")]`、`#[axum::post(…)]` 等（get / post / put / delete / patch / head / options / trace），或语句、`let` 的初始值、返回值里 `Router` 的 `.route(路径, get(函数))`（一句只出一张卡，讲链上最后写的那个 `route`）。函数已经标了路由属性时，这句 `route` 不再单独成卡。种类 `axum.route`，标签「接口」，图标 `globe`，颜色同 FastAPI 接口（暗 #61afef / 亮 #1a6fb5）。属性表：名称、说明、异步（是）、请求（一项「方法」、一项「路径」、路径里的 `{名字}` 对上参数写成「路径参数」，`Path(id): Path` 写 `id: Uuid`）、参数（说明里写了 `@param` 才有：参数是 `Path(id)` 这类模式，不对名字，照写成「名称 \| 说明」表）、返回（`@return` 跟在后面）、异常（`@throws`）。 +- sqlx（`rules/sqlx.ts`，`libraries: ['sqlx']`）：`query!` / `query_as!` / `query_scalar!` 宏，或 `query` / `query_as` / `query_scalar` 函数（参数是后面连着的 `.bind(…)`）。种类 `sqlx.query`，标签「查询」，图标 `database`，颜色暗 #ce9178 / 亮 #a31515。前面的注释同别的块，是卡片的「注释」一行（宿主插在第一行后面）。SQL 原文等宽，函数写法传进来的不是字符串（`&sql`）时照翻成一行；参数 `$1`、`$2`… 依次对上宏里 SQL 后面的实参或各个 `.bind`；`query_as!` 的第一个实参、`query_as::<_, T>` / `query_scalar::<_, T>` 尖括号里第二个类型是返回类型，`query!`、`query_scalar!`、`query` 和没写尖括号的返回类型是「—」。 - tauri（`rules/tauri.ts`，`libraries: ['tauri']`）：`#[tauri::command]` 的函数。种类 `tauri.command`，标签「桌面命令」，图标 `square-function`，颜色暗 #e5c07b / 亮 #9a6a00。名称后面再标「桌面命令」。参数表「名称 | 类型 | 来源」：`State<…>` 是「窗口状态」，其余是「调用方传入」；说明里的 `@param` 对上时多一列「说明」，`@return` 跟在「返回」后面，`@throws` 成「异常」表。 ## 命令规则 @@ -2341,7 +2343,7 @@ vscode/webview-ui/code-reader.html + src/codeReader/ 预览界面（React，Vit - 语言插件（`languages/bash.test.ts`，真实解析）：`fixtures/fetchRuntime.sh` 的代码块树（种类、行号、层级，同原型 `SHELL_BLOCKS`，原型略去的行也在）；elif / else 展平、while / for 的主体是子块、条件串和命令串；解释器（env、写死的路径）、选项（连写拆开、`-o`、`+`、`set --` 不是）、变量（local 一句几个、没值的、readonly 和顶层全大写写死的是常量）、函数（按位置的参数和名字、打印的几句、被 `$(…)` 拿去用、写了的 return）；命令的词（写死的文字、有展开的没有）和重定向；同一文件里的名字（函数、赋值、local、for、read、展开，第几个参数不算）；行尾 `# @Comment`。 - 中文直译（`translators/bashZh.test.ts`，走 `readBlockViews`）：`fetchRuntime.sh` 整份逐行同 `FETCH_READING`（即上面「Shell 脚本」的样例）；展开（长度、去头去尾、截取、没设时、替换、特殊变量）、条件、重定向、命令规则（不认识的选项照抄、没有规则的照抄）、`&&` / `||`、遍历、`$(dirname "$0")`、常量；字符串色 / 变量色 / 常量色；规则出错照抄命令并报告。 - 宿主：命令规则按语言、注册顺序给（`registry.test.ts`），shellscript 的 document 消息带命令规则读的译文、shell 的种类名、同一文件里的名字（`editor/documentMessage.test.ts`），跳到之前最近的定义、定义处算写入（`localSymbols.test.ts`）。 -- Rust（`languages/rust.test.ts`、`rules/rustLibs.test.ts`，真实解析）：`fixtures/rustLang.rs` 的导入、结构体、枚举、实现（方法挂在方法表的子行上）、函数（异步、函数体里 match 的各支）、特质（同实现）逐行同预览；函数体子块（执行器的 `device_resume`：let、let … else、if、隐式返回；if / else if let / else、match 的守卫和各支、排在最后的 if；三种循环；闭包、嵌套 fn、unsafe / async / 带标签的块、展平的 `{}`、实参里的闭包和 async 块；函数体里的注释；特质的默认方法和 impl Trait for 的方法没有可见性），调用的结构和跨几行写的调用；给结构体加一个字段，字段表那一行标成新增。`fixtures/rustComments.rs` 开头连着写的 `//` 合成一段，是文件的说明，预览是去掉 `//` 的三段 Markdown；别的注释挂到后面那一项（「注释」一行），行尾 `//` 不单独成块，`//!` 连着几行合成一段、是文件的说明，`///` 并进下一个函数当说明、普通注释同时是它的「注释」，`mod`、`impl` 身体里同一套。编译属性：Tauri `main.rs` 的 `cfg_attr` 卡片逐行（属性的着色、「非 调试构建」、「整个 crate」、windows 子系统的说明），别的文件顶层的 `allow` 是本模块、列出 lint 名，认不得的属性没有说明、不知道文件名时是所在模块，`cfg_attr` 里几个属性是一张表、套着的条件加括号，`isCrateRoot` 的几种路径。`fixtures/rustLibs.rs` 的 serde（改名、不输出、字段名改驼峰）、thiserror（展示、透传来源）、axum（方法、路径、路径参数）、sqlx、tauri 逐行同预览；没导入 serde 时 derive 仍是结构体；改 axum 的路径，路径那一格标成改过。`axum::routing` 这种来源算导入了 axum。 +- Rust（`languages/rust.test.ts`、`rules/rustLibs.test.ts`，真实解析）：`fixtures/rustLang.rs` 的导入、结构体、枚举、实现（方法挂在方法表的子行上）、函数（异步、函数体里 match 的各支）、特质（同实现）逐行同预览；函数体子块（执行器的 `device_resume`：let、let … else、if、隐式返回；if / else if let / else、match 的守卫和各支、排在最后的 if；三种循环；闭包、嵌套 fn、unsafe / async / 带标签的块、展平的 `{}`、实参里的闭包和 async 块；函数体里的注释；特质的默认方法和 impl Trait for 的方法没有可见性），调用的结构和跨几行写的调用；给结构体加一个字段，字段表那一行标成新增。`fixtures/rustComments.rs` 开头连着写的 `//` 合成一段，是文件的说明，预览是去掉 `//` 的三段 Markdown；别的注释挂到后面那一项（「注释」一行），行尾 `//` 不单独成块，`//!` 连着几行合成一段、是文件的说明，`///` 并进下一个函数当说明、普通注释同时是它的「注释」，`mod`、`impl` 身体里同一套。编译属性：Tauri `main.rs` 的 `cfg_attr` 卡片逐行（属性的着色、「非 调试构建」、「整个 crate」、windows 子系统的说明），别的文件顶层的 `allow` 是本模块、列出 lint 名，认不得的属性没有说明、不知道文件名时是所在模块，`cfg_attr` 里几个属性是一张表、套着的条件加括号，`isCrateRoot` 的几种路径。`fixtures/rustLibs.rs` 的 serde（改名、不输出、字段名改驼峰）、thiserror（展示、透传来源）、axum（方法、路径、路径参数）、sqlx、tauri 逐行同预览；函数体里 `let` 的初始值（`query!`、`query_as::<_, T>(…).bind(…)`、`let … else` 的 `query_scalar!`）和末尾的返回值（`Router` 的 `.route`、`query!`）出库卡片，「变量」一行是变量名、也是定义，卡片留着变量、返回概念，else 照常是子块；函数写法拼出来的 SQL 照翻、各个 `.bind` 依次是 `$1`、`$2`；没导入 serde 时 derive 仍是结构体；改 axum 的路径，路径那一格标成改过。`axum::routing` 这种来源算导入了 axum。 - Dockerfile： - 语言插件（`languages/dockerfile.test.ts`，真实解析）：两份 luffy 的 Dockerfile 的代码块树（同原型，后端的三行注释是阶段说明）；并块（紧挨着才并，空行、注释、别的指令隔开，COPY 要从同一个地方，ADD、heredoc 的 COPY 不并，第一个 FROM 之前的是顶层）；ONBUILD 和各种设置；facts（解析指令、阶段的名称 / 序号 / 说明 / 标签 / 摘要 / 平台 / 接着前面的阶段、构建参数和环境变量并块、健康检查两种写法和 NONE、启动）；嵌着的 shell 的几段（续行去掉、heredoc 正文）；数组写法的命令（VOLUME、SHELL 的数组不算）；同一文件里的名字（阶段名在 --from、--mount 的 from、FROM 里，变量）；中文名；着色。 - 中文直译（`translators/dockerfileZh.test.ts`，走 `readBlockViews`，RUN 交给 bash 的插件）：两份 luffy 的 Dockerfile 整份逐行同 `NEXT_READING`、`BACKEND_READING`；阶段的各种写法、变量的展开和注解、RUN 的选项 / 数组写法 / heredoc / 一条循环 / 带重定向的一串、没有 shell 插件时照抄、复制和 ADD、设置、健康检查、启动；阶段名和表里变量名的源码下标、RUN 的源码按 shell 着色。