✨ feat(vscode): 代码阅读加 FastAPI 接口卡片：请求表（URL、方法、路径 / 查询参数、请求头、Cookie、请求体）、按状态码的响应表（成功、responses、函数里抛的异常、自动带的 422）；别的文件里的异常状态码、类型别名经工作区索引和语言扩展查
This commit is contained in:
cruldra committed
1 parent
1dfc0c7b1e
commit
0798f7d1c7
18 files changed
+1745
-28
No files matched your search
@@ -35,7 +35,7 @@
|
||||
| 函数、类、导入、常量、变量块 | 预览不显示一行译文，显示树形属性表；属性值里的类型、表达式照常直译 |
|
||||
| 字典 / 对象字面量 | 常量、变量的值是 Python 字典 / TypeScript 对象字面量时不挤成一长行：值写「字典 N 项」/「对象 N 项」，各项展开成「键 \| 值」两列的子行，值又是字典 / 对象时一层层往下展开；参数默认值照旧一行 |
|
||||
| 输入参数 | 排成带表头和边框的表格：名称 \| 类型 \| 默认值，表头写了「默认值」，格子里不再写「默认 」 |
|
||||
| 库规则 | 第四种插件：按库认出一种写法，把那块整个换成专门的卡片（内置 SQLAlchemy 规则：模型类 → 「数据表」卡片；内置 Celery 规则：`Celery(...)` → 「Celery 应用」卡片、`beat_schedule` → 「定时任务」卡片），或把那块认成契约里现成的一种属性表块（内置 enum 规则：Python 自带 enum 库的类 → 枚举块）。和语言插件、翻译插件一样写代码注册、只经契约拿信息；文件导入了规则关心的库才启用，由宿主按语言插件给的导入判断；卡片的用词归规则自己，认成的现成块照常由翻译插件排，webview 只画结构。见「库规则」 |
|
||||
| 库规则 | 第四种插件：按库认出一种写法，把那块整个换成专门的卡片（内置 SQLAlchemy 规则：模型类 → 「数据表」卡片；内置 Celery 规则：`Celery(...)` → 「Celery 应用」卡片、`beat_schedule` → 「定时任务」卡片；内置 dataclasses 规则：数据类 → 「数据类」卡片；内置 FastAPI 规则：挂在路由对象上的函数 → 「接口」卡片，请求、响应各一张表），或把那块认成契约里现成的一种属性表块（内置 enum 规则：Python 自带 enum 库的类 → 枚举块）。和语言插件、翻译插件一样写代码注册、只经契约拿信息；文件导入了规则关心的库才启用，由宿主按语言插件给的导入判断；卡片的用词归规则自己，认成的现成块照常由翻译插件排，webview 只画结构。见「库规则」 |
|
||||
| 枚举 | 枚举是一种块（种类「枚举」，紫色 #b180d7 / 亮色 #652d90），属性表：名称 / 说明 / 访问级别 / 装饰器 / 继承（有才显示）/ 成员 N 个，成员排成表格「成员 \| 值 \| 说明」。TypeScript 的 `enum` 是语言自己的写法，由语言插件报；Python 没有枚举语法，自带 enum 库的写法由库规则认成同一种块。两边同一种块、同一张表、同一个筛选种类，webview 只有一种画法 |
|
||||
| 异常 | 异常类是一种块（种类「异常」，红色 #f14c4c / 亮色 #cd3131，和「捕获」同一色系），属性表：名称 / 说明 / 访问级别 / 装饰器 / 继承 / 属性 N 个（表格「属性 \| 类型 \| 值 \| 说明」）/ 构造参数 N 个（表格同函数的输入参数），有才显示。异常是语言自己的概念，Python、TypeScript 都由语言插件认：父类是语言自带的异常类、同一文件里认出来的异常类，或名字按命名习惯以 Error / Exception（Python 还有 Warning）结尾。方法（含构造函数）照常是子块、默认收起。见「异常」 |
|
||||
| 规则自己查定义 | 规则可以把自己给的名字标成「引用」（Celery 任务表里的任务名），⌘ / Ctrl 悬停、点击这样的名字时由规则查定义（Celery 在整个工作区里找任务函数），其余名字照旧问语言扩展；webview 只有一条链接 / 跳转的路，样子、闪、挑选框、在预览里打开都一样。规则要在全工作区找东西时只描述要找什么（`WorkspaceIndex`），找文件、解析、缓存、跟着改动更新归宿主。见「规则自己查定义」 |
|
||||
@@ -126,7 +126,7 @@
|
||||
| enum 枚举 | `list-ordered` | else 否则 | `corner-down-right` | statement 语句 | `code` |
|
||||
| exception 异常 | `triangle-alert` | loop 循环 | `repeat` | comment 注释 | `message-square-text` |
|
||||
|
||||
库规则的种类用规则给的图标（`KindBadge.icon`）：SQLAlchemy 数据表 `database`、数据类 `package`、Celery 应用 `server-cog`、定时任务 `calendar-clock`。webview 按 lucide 图标名画（`lucide-react` 的全套图标），认不出的名字画虚线方块（`square-dashed`）。
|
||||
库规则的种类用规则给的图标（`KindBadge.icon`）：SQLAlchemy 数据表 `database`、数据类 `package`、Celery 应用 `server-cog`、定时任务 `calendar-clock`、FastAPI 接口 `globe`。webview 按 lucide 图标名画（`lucide-react` 的全套图标），认不出的名字画虚线方块（`square-dashed`）。
|
||||
- 右上角的图标按钮（原型组件 `Reader / BlockTools`，普通块、属性表块、库规则的卡片共用）：只有图标、不带字，名字写在悬停提示（`title`）和 `aria-label` 里；整排是 `role="group"`（`aria-label="块操作"`）。先是「问 AI」（sparkles 图标，点开 / 收起块下面的问答区，展开时带按下的底色、`aria-expanded`；文件不在工作区文件夹里时没有，见「问 AI」），再是「编辑 / 预览」切换：预览时铅笔「编辑」，编辑时眼睛「预览」、带按下的底色（`--vscode-toolbar-activeBackground`）。按钮宽 24px、高 20px（和种类图标同高），图标 14px、`descriptionForeground` 色；悬停 `--vscode-toolbar-hoverBackground`，键盘聚焦描 1px `--vscode-focusBorder`；Tab 能走到，回车 / 空格切换。
|
||||
- 种类图标和底色按种类区分（颜色见「颜色」）；注释块虚线框。
|
||||
- 内容两种状态，每块单独切：
|
||||
@@ -566,8 +566,9 @@ export type TokenRole =
|
||||
* 预览拿它向 VS Code 查定义、跳过去；译词、提示词没有。由从语法树叶子生成这段的一方填（模板直译引擎的译文和属性表）；
|
||||
* 第三方翻译插件可以不填，不填就不能跳。
|
||||
* reference：只有库规则给的段有，这段讲的东西由规则自己查定义（LibraryRule.resolve），不问语言扩展；这样的段必须带 offset。
|
||||
* color：这段自己的颜色（暗色、亮色主题各一个），盖过词性的颜色：库规则按库自己的配色上色（FastAPI 的 HTTP 方法用 Swagger UI 的颜色）。
|
||||
*/
|
||||
export interface Segment { text: string, role: TokenRole, offset?: number, reference?: RuleReference }
|
||||
export interface Segment { text: string, role: TokenRole, offset?: number, reference?: RuleReference, color?: ThemeColor }
|
||||
|
||||
/** 框的样式，决定框头图标和框的颜色：'iteration' 是写在表达式里的遍历，图标、颜色同「循环」块。 */
|
||||
export type GroupStyle = 'iteration'
|
||||
@@ -690,6 +691,7 @@ export interface RuleContext {
|
||||
displayLanguage?: string // 当前翻译插件的 displayLanguage；没有翻译插件时没有
|
||||
translate: (node: Node) => Inline[] // 借当前翻译插件的 expression；没有翻译插件时照抄源码
|
||||
doc: (node: Node) => Markdown | undefined // 借当前翻译插件的 doc
|
||||
lookup: (index: WorkspaceIndex, name: Node) => IndexEntry | undefined // name 指的定义在 index 里认出的那一项（见「规则认领时查别的文件里的定义」）；还没查到是 undefined
|
||||
}
|
||||
|
||||
// ── 规则自己查定义（见「规则自己查定义」）──
|
||||
@@ -703,7 +705,7 @@ export interface IndexedFile {
|
||||
source: string
|
||||
exists: (path: string) => boolean // 同一个工作区文件夹里有没有这个文件（只认 include 找到的）
|
||||
}
|
||||
export interface IndexEntry { key: string, name: SourceRange }
|
||||
export interface IndexEntry { key: string, name: SourceRange, value?: string } // value：规则从定义处读出、认领别的文件时要用的值（FastAPI：异常类的 status_code）
|
||||
|
||||
/** 规则在整个工作区里建的索引：规则只说看哪些文件、认出什么；找文件、预筛、解析、缓存、跟着改动更新归宿主。 */
|
||||
export interface WorkspaceIndex {
|
||||
@@ -735,7 +737,7 @@ export interface CodeReaderApi {
|
||||
```
|
||||
|
||||
- `activate()` 返回 `{ codeReader: CodeReaderApi }`；其他扩展声明 `extensionDependencies` 后用 `extensions.getExtension('clurdra.superpowers-vscode-clurdra')!.exports.codeReader` 注册。
|
||||
- 内置的 TypeScript、Python 语言插件、两个中文直译翻译插件和 SQLAlchemy、Celery、enum 库规则在 `activate()` 里通过同一个 API 注册（规则按这个顺序），没有旁路。
|
||||
- 内置的 TypeScript、Python 语言插件、两个中文直译翻译插件和 SQLAlchemy、Celery、enum、dataclasses、FastAPI 库规则在 `activate()` 里通过同一个 API 注册（规则按这个顺序），没有旁路。
|
||||
- 注册表变化时更新 `superpowers.codeReader.languageIds` 上下文，并让已打开的预览刷新。
|
||||
- 分工：语言插件只从语法树读出和语言无关的事实（facts，引用源码节点，不做正则匹配文字）；翻译插件决定属性名、枚举词（公共 / 是 / 默认导出）和值怎么译，也给筛选属性和值起名（`attributeNames`）。筛选属性的通用部分由宿主从 facts 推出（`attributes.ts` 的 `blockAttributes`），语言插件只在 `BlockShape.attributes` 里补自己语言特有的。第三方语言插件给函数、类、枚举、异常、导入、常量、变量块填 facts 就能用上任何翻译插件的属性表；自己语言的字典 / 映射字面量填进 `DeclaratorFacts.entries` 就能展开成子行（中文模板直译按字面量的节点类型查叫法，见 `ZhTable.mapLiterals`）。写在表达式里的遍历（推导式这类）由语言插件的 `iteration` 给结构（节点 → `IterationFacts`），翻译插件排成一个 `SegmentGroup`（中文直译是样式 `iteration`、框头是结果类型的译名）；webview 只认框的样式 id，不认语言。
|
||||
- 语言插件的信息只经契约到翻译插件：宿主翻每一块时把 `{ source, language }`（`SourceDocument`，language 是解析这份源码的语言插件）交给 `translate` / `describe`，翻译插件要词性、遍历结构都从 `language` 取，不 import 任何语言插件的模块（lint 规则挡住 `translators/` 下的非测试文件 import `languages/`）。所以第三方翻译插件（英文、AI 翻译）拿得到和内置翻译插件一样的信息，第三方语言插件也能配上任何翻译插件。
|
||||
@@ -755,7 +757,7 @@ export interface CodeReaderApi {
|
||||
- 认成现成的属性表块（`RuleFacts`）：`as` 是种类和 facts（`BlockFacts`，例如 `{ kind: 'enum', facts: EnumFacts }`），`absorbs` 同卡片。宿主把原块换成这种块（节点不变，头部是原块整条语句，子块是留下的），此后和语言插件报的这种块完全一样：翻译插件的 `describe` 排属性表、种类名取翻译插件的、颜色取这个种类的、筛选属性从 facts 推、块自己的名字从 facts 取。规则不给用词，也不给标签和颜色。只要检查并进来的是不是这块的子块。
|
||||
- 规则自己的卡片（`RuleCard`），下面几条都说的是它。
|
||||
- 卡片必须给：`kind`（写成「规则 id.名字」，宿主核对前缀；筛选记住的就是它，要稳定）、`badge`（种类的名字、暗 / 亮两种颜色和 lucide 图标名）、`rows`（用现成的 `PropertyRow`：属性名 + 着色的值或 Markdown，表格就是带 `columns` 的子行）、`absorbs`（并进来的子块）。可以给：`defines`（块自己的名字，跳到定义是它时闪整块）、`attributes`（自己的筛选属性）；表格子行填 `PropertyItem.defines`（字段名），跳到这个定义时只闪那一行。
|
||||
- 只经契约：规则拿到的是块（kind、node、header、children、facts）和 `RuleContext`；源码里的名字照抄时自己带下标（`Segment.offset`），表达式、类型交给 `context.translate`（当前翻译插件的 `expression`，名字带下标，⌘ + 点击、高亮各处出现照常），说明文字交给 `context.doc`（当前翻译插件的 `doc`，和别的「说明」一样按 Markdown 显示）。规则可以读自己那门语言的语法树（规则声明了 `languageIds`），但不 import 语言插件、翻译插件和宿主模块（`rules/contractOnly.test.ts` 检查 `rules/` 下非测试文件只 import `../contract` 和同目录的文件）。
|
||||
- 只经契约：规则拿到的是块（kind、node、header、children、facts）和 `RuleContext`；源码里的名字照抄时自己带下标（`Segment.offset`），表达式、类型交给 `context.translate`（当前翻译插件的 `expression`，名字带下标，⌘ + 点击、高亮各处出现照常），说明文字交给 `context.doc`（当前翻译插件的 `doc`，和别的「说明」一样按 Markdown 显示），别的文件里定义的名字交给 `context.lookup`（见「规则认领时查别的文件里的定义」）；库自己的配色（HTTP 方法）写在段的 `color` 上。规则可以读自己那门语言的语法树（规则声明了 `languageIds`），但不 import 语言插件、翻译插件和宿主模块（`rules/contractOnly.test.ts` 检查 `rules/` 下非测试文件只 import `../contract` 和同目录的文件）。
|
||||
- 用词归规则：属性名、表头、种类名、类型译名都在规则自己的词表里，按 `context.displayLanguage`（翻译插件的 `displayLanguage`）挑，没有这种语言的词表就用规则默认的那份；加一种显示语言就是给规则加一份词表。webview 只画结构，不认识「数据表」这些字。
|
||||
|
||||
### 启用、认领、优先
|
||||
@@ -778,6 +780,14 @@ export interface CodeReaderApi {
|
||||
- 盯着文件改动：改了只重看那一份；新建的加进来；删掉的（目录连里面的）去掉；规则认的时候问过在不在（`IndexedFile.exists`）的文件新建、删掉时，问过它的那几份跟着重看（Python 包路径看 `__init__.py`）；建索引期间的改动建好后补上；
|
||||
- 读不了、规则认的时候出错的文件记日志、跳过，别的照常。
|
||||
|
||||
### 规则认领时查别的文件里的定义
|
||||
|
||||
有的卡片要用到别的文件里的东西：FastAPI 接口里 `raise Forbidden(...)` 的状态码写在 `core/exceptions/schemas.py` 的 `class Forbidden` 上。规则照「规则自己查定义」描述一个 `WorkspaceIndex`，`entries` 认出的项带着规则要的值（`IndexEntry.value`，FastAPI：`"403"`）；认领时对源码里的名字（节点）调 `context.lookup(索引, 名字)`，拿到那个名字的定义在索引里的那一项。和「中文名」查别的文件里的定义是同一个办法：
|
||||
|
||||
- 怎么算：索引里有同名（键等于名字原文）的项，才问语言扩展这个名字的定义（`vscode.executeDefinitionProvider`，同 ⌘ + 点击）；定义处（文件、起始行列）正是索引里某一项的名字才算，同名的别处的类不算。索引里没有同名的项就是没有，不问语言扩展。同一份源码里同名的名字（几处 `raise Forbidden`）按第一处查、共用一个结果。
|
||||
- 什么时候查（宿主，`ruleLookups.ts` 的 `DocumentLookups`，不碰 VS Code）：认领是同步的，排视图数据时 `lookup` 只交出眼下知道的（没查到是 undefined），记下这一遍问了哪些名字；发出预览后再查，同一个版本同一个名字只查一次；查到的（键、值）和已知的不一样就按新结果重排一遍、重发文档。文档改了先用上一版查到的（不闪），新版本再查一遍，没变不重发。索引里有同名的项、语言扩展却没答（还没起来）时已知的不动，照「中文名」的间隔（1、2、4、8、16 秒）再查。
|
||||
- 没有工作区时（单元测试、没传 `lookup`）总是 undefined；规则要能照常出卡片，只是少了查不到的那部分。
|
||||
|
||||
### 内置：SQLAlchemy 数据表（Python）
|
||||
|
||||
`vscode/src/codeReader/rules/sqlalchemy.ts`，`libraries: ['sqlalchemy', 'flask_sqlalchemy']`。类块主体里有 `__tablename__`，或有赋值是 `mapped_column(...)` / `Column(...)`（`sa.Column`、`db.Column` 这类取最后一节）时认领，种类 `sqlalchemy.table`，标签「数据表」（暗 #e8a860 / 亮 #a3590d）。导入时起的别名按 `context.imports` 换回原名（`from sqlalchemy import Enum as SQLEnum`、`UUID as PgUUID`）。
|
||||
@@ -999,6 +1009,80 @@ export interface CodeReaderApi {
|
||||
|
||||
`__post_init__` 照常是卡片的子块。
|
||||
|
||||
### 内置：FastAPI 接口（Python）
|
||||
|
||||
`vscode/src/codeReader/rules/fastapi.ts`，`libraries: ['fastapi']`。原型：`code.js` 的「库规则：FastAPI 接口」一节（`ROUTE_SAMPLE`、`routeCard`），画板「库规则 · FastAPI 接口」；样例是 luffy 的 `user/routes.py`（`fixtures/routes.py`）、`skill_hub/routes.py`（`fixtures/skillHubRoutes.py`）、`user/console/routes.py`（节选在 `fixtures/consoleRoutes.py`）。种类 `fastapi.route`，名字「接口」，图标 `globe`，颜色暗 #61afef / 亮 #1a6fb5，和函数块一样默认收起子块。
|
||||
|
||||
- 认哪些函数：装饰器是 `@<路由对象>.<方法>(...)`，方法是 get / post / put / patch / delete / head / options / trace，路由对象是同一文件模块顶层 `X = APIRouter(...)` / `X = FastAPI(...)` 赋值出来的（`APIRouter`、`FastAPI` 从 fastapi 导入，别名、`fastapi.APIRouter` 也算）。路由对象从别的文件导入的、`@router.get` 不带括号的、`@router.websocket` 不认。几个路由装饰器时取第一个。
|
||||
- 整个函数块换成卡片，不并子块：函数体照常是子块；编辑范围同别的卡片，是整条语句（连装饰器的整个函数）。
|
||||
- 挂到应用上时再叠的前缀（别的文件里的 `include_router(prefix=…)`、`settings.API_V1_PREFIX`）URL 不算。
|
||||
|
||||
属性表（有才显示）：
|
||||
|
||||
| 行 | 内容 |
|
||||
| --- | --- |
|
||||
| 名称 | 函数名（function 色，带下标） |
|
||||
| 说明 | 函数的 docstring，同函数块；Markdown |
|
||||
| 标签 | 路由对象的 `tags=` 加装饰器的 `tags=`，字符串不带引号（string 色，带下标），「、」隔开 |
|
||||
| 异步 | 是 / 否（storage 色） |
|
||||
| 装饰器 | 路由装饰器以外的装饰器（`@cache(60)`），有才显示 |
|
||||
| 依赖 | 路由对象、装饰器的 `dependencies=[Depends(x)]` 写 `x`，参数上的 `Depends(x)` / `Security(x)` 写 `x（参数名）`，参数名是 `_` 的只写 `x`；`Depends()` 不带参数时 x 是参数的类型；照这个顺序，「、」隔开。x 是一个名字时按 function 色、带下标，别的写法交给翻译插件翻 |
|
||||
| 请求 | 值是 `方法 URL`（hint），下面一张表格「项 \| 值」，一项一行，没有的项不列：URL、方法、路径参数、查询参数、请求头、Cookie、请求体 |
|
||||
| 响应 | 值是各状态码用 ` / ` 连起来（hint），下面一张表格「状态码 \| 内容 \| 说明」，一个状态码一行，按状态码从小到大，不是三位数字的（`"5XX"`）排在最后 |
|
||||
|
||||
请求表：
|
||||
|
||||
- URL：路由对象的 `prefix` 加装饰器的路径；`{参数}` 按 variable 色，其余按 string 色，都带源码下标；写的不是字符串（`prefix=settings.X`）交给翻译插件翻。
|
||||
- 方法：大写，颜色用 Swagger UI 的配色（段的 `color`）：GET #61affe、POST #49cc90、PUT #fca130、PATCH #50e3c2、DELETE #f93e3e（暗色）；白底上照原色看不清，亮色主题取同色相深一些的 #1b6ac9、#18834f、#b35f00、#0f8a70、#cf2020；HEAD #b36bff / #9012fe、OPTIONS #4b92e0 / #0d5aa7（Swagger UI 的 #9012fe、#0d5aa7 在暗底上看不清，暗色调亮了）；TRACE 没有配色，按 keyword 色。
|
||||
- 路径参数、查询参数、请求头、Cookie：`名称: 类型`，逗号隔开，名称 variable 色带下标，类型交给翻译插件翻（`Annotated[T, …]` 写 T）；没标注的只写名称。
|
||||
- 请求体：只有一个时写它的类型（模型名），几个时（表单的几个字段）写 `名称: 类型` 一串。
|
||||
|
||||
参数放在哪儿，照 FastAPI 的规则，按下面的先后，第一条对上的算：
|
||||
|
||||
1. 写了 `Depends(...)` / `Security(...)`（默认值 `= Depends(x)`，或 `Annotated[T, Depends(x)]`）：依赖，不是请求带的。
|
||||
2. 名字在路径里（`{user_id}`、`{file_path:path}`，前缀和路径都算）：路径参数。
|
||||
3. 写了 `Path` / `Query` / `Header` / `Cookie` / `Body` / `Form` / `File`（同上两种写法）：照写的，`Header` 进「请求头」、`Cookie` 进「Cookie」，`Body` / `Form` / `File` 进「请求体」。
|
||||
4. 类型是别处写好的类型别名（`Int4Query = Annotated[int \| None, Query(...)]`、`FilterQuery = Annotated[FilterList, Depends(...)]`）：经工作区索引查到它的标记（见下），照 1、3 放。
|
||||
5. `Request`、`Response`、`WebSocket`、`HTTPConnection`、`BackgroundTasks`、`SecurityScopes`：FastAPI 自己填的，不列。
|
||||
6. 上传文件（`UploadFile`、`list[UploadFile]`）：请求体。
|
||||
7. 简单类型：查询参数。简单类型是 int、float、str、bool、bytes、complex、UUID、datetime、date、time、timedelta、Decimal、Any、EmailStr、HttpUrl、AnyUrl、SecretStr、`None`、`Literal[...]`、枚举类（别处定义的经索引查），和只包着它们的 `X | None`、`Optional` / `Union` / `list` / `set` / `tuple` / `Sequence` 这些；没标注类型的也是。
|
||||
8. 别的（Pydantic 模型、字典……）：请求体。
|
||||
|
||||
`*args`、`**kwargs` 不算。
|
||||
|
||||
响应表（同一个状态码的几处写在一行里：内容「、」隔开、去重，说明「；」隔开、去重）：
|
||||
|
||||
- 成功那一行：装饰器的 `status_code`（整数，或 `status.HTTP_201_CREATED` 这种常量），没写是 200；内容是 `response_model`，没写就用返回类型标注（`response_model=None`、`-> None` 没有内容）；说明是 `response_description`，没写是「成功」（comment 色）。
|
||||
- 路由对象和装饰器的 `responses={...}`：每一项一行，键是状态码（整数、`"404"`、常量；`"5XX"`、`"default"` 照写）；值是字典时 `"model"` 是内容、`"description"` 是说明，值不是字典时整个是内容；`**x` 不列。
|
||||
- 函数体里直接抛的异常（嵌套的函数、类、lambda 里的不算，只写 `raise` 的不算，`raise X from e` 算，调别的函数间接抛的不算）按状态码归：`HTTPException`（从 fastapi 或 starlette 导入）的状态码是 `status_code=` 或第一个位置参数，消息是 `detail=` 或第二个位置参数；别的类的状态码是类上的 `status_code = N`，经工作区索引查（下面），消息是第一个位置参数（或 `message=`、`detail=`）。内容是异常类名（type 色，带下标，⌘ + 点击到类的定义），说明是消息：字符串照写（comment 色），别的写法交给翻译插件翻。查不到状态码的异常（没查完、不是 HTTP 异常）不列。
|
||||
- 有参数或请求体（路径 / 查询 / 请求头 / Cookie / 请求体里有一项）时，422 那一行加上「参数校验失败 \| FastAPI 自动返回」（hint 色，淡）。
|
||||
- 状态码的颜色：小于 400 的绿色（暗 #2ea043 / 亮 #1a7f37，段的 `color`），别的 string 色；不是三位数字的照写、string 色。
|
||||
|
||||
别的文件里的定义（索引 `fastapi.names`，见「规则认领时查别的文件里的定义」）：看工作区里所有 `**/*.py`，预筛有 `status_code`、`Annotated` 或 `Enum` 才解析；从模块顶层认出：类上写了 `status_code = N`（带不带注解、`status.HTTP_403_FORBIDDEN` 这种常量也算）的类 → 值是状态码；父类是 enum 的枚举类型（Enum、IntEnum、StrEnum、Flag、IntFlag）的类 → `Enum`；`X = Annotated[T, Query(...)]` 这种类型别名 → 标记名（`Query`、`Path`、`Depends`……）。父类继承下来的 `status_code`（`class AccountFrozen(Forbidden)` 没自己写）不认。
|
||||
|
||||
样例（`fixtures/routes.py` 的 `update_user`，`Forbidden` 定义在 luffy 的 `core/exceptions/schemas.py`（`fixtures/appExceptions.py`），`status_code = 403`；测试里逐字核对）：
|
||||
|
||||
```
|
||||
名称: update_user
|
||||
说明: 更新用户信息。…
|
||||
标签: 用户管理
|
||||
异步: 是
|
||||
依赖: get_db（db）、get_current_user（current_user）
|
||||
请求: PUT /users/{user_id}
|
||||
URL | /users/{user_id}
|
||||
方法 | PUT
|
||||
路径参数 | user_id: Int4Path
|
||||
请求体 | UserUpdateRequest
|
||||
响应: 200 / 403 / 422
|
||||
200 | UserDetailResponse | 成功
|
||||
403 | Forbidden | 无权更新此用户信息；无权修改角色；无权修改启用状态；无权修改密码
|
||||
422 | 参数校验失败 | FastAPI 自动返回
|
||||
```
|
||||
|
||||
`skill_hub/routes.py` 的 `list_skills`：`查询参数 | query: 字符串 | 空, tag: 字符串 | 空, skip: 整数, limit: 整数`，依赖 `get_db（db）、get_current_user`（参数名是 `_`）；`user/console/routes.py` 的 `create_user`：成功那一行 `201 | UserDetailResponse | 成功`，请求体 `UserCreateRequest`。
|
||||
|
||||
配色：名称 function、标签 string、依赖名 function、「（参数名）」hint、表格第一列（项）hint、URL 同上、参数名 variable、类型按翻译插件、异常类名 type、消息和说明 comment、自动带的 422 hint。
|
||||
|
||||
## 解析运行时
|
||||
|
||||
- 依赖 `@vscode/tree-sitter-wasm`（VS Code 团队维护，包含 web-tree-sitter 运行时和 TypeScript / TSX / JavaScript / Python 语法包，版本配套）。
|
||||
@@ -1197,7 +1281,9 @@ type BlockView = BlockViewBase & ({ translation: PreviewText, doc?: Markdown } |
|
||||
|
||||
属性表里：说明按 comment，访问级别（公共 / 私有 / 受保护）和「作为」按 keyword，是 / 否按 storage，函数名称按 function，类名称按 type，未标注、无、N 个、字典 N 项、对象 N 项、展开、默认导出、全部、整个模块、匿名按 hint；输入参数表格的列名是界面文字（`descriptionForeground`），不是着色的词。推导式框里的「遍历」「的每个」「仅当」「取」「异步遍历」按 keyword，框头按「循环」块的种类色。父类名（TypeScript `extends` 后面、JavaScript `class_heritage` 里、Python 类名后面括号里直接写的名字）源码着色和属性表里都按 type。
|
||||
|
||||
种类（种类图标的颜色 + 块底 7% + 边框 35%；亮色主题同色系；图标见「预览（代码块树）」）：import 导入 #c586c0；function 函数 #dcdcaa；class 类、type 类型 #4ec9b0；enum 枚举 #b180d7（亮色 #652d90）；exception 异常 #f14c4c（亮色 #cd3131，和尝试、捕获、最终同一色系，更红一些）；field 字段、const 常量、variable 变量 #9cdcfe；if 条件、else 否则 #ce9178；loop 循环 #8f9cff；try 尝试、catch 捕获、finally 最终 #f48771；return 返回 #89d185；statement 语句 #9d9d9d；comment 注释 #6a9955（虚线框）；库规则的种类用规则给的颜色（`badge.color` 的 dark / light，webview 写在块的 style 上按主题挑），内置 SQLAlchemy 数据表 #e8a860 / #a3590d，Celery 应用 #98c379 / #4d7f17，定时任务 #56b6c2 / #127f8c，数据类 #ef7fb0 / #b3306c。编辑状态：底色 `--vscode-editor-background`，边框 `--vscode-focusBorder`。
|
||||
带自己颜色的段（`Segment.color`，库规则按库的配色给，例如 FastAPI 的 HTTP 方法、成功的状态码）：暗色、亮色两个写在元素的 style 上（`--color-dark` / `--color-light`），`.cr-colored` 按主题挑一个，盖过词性的颜色；词性照旧报（`role`）。
|
||||
|
||||
种类（种类图标的颜色 + 块底 7% + 边框 35%；亮色主题同色系；图标见「预览（代码块树）」）：import 导入 #c586c0；function 函数 #dcdcaa；class 类、type 类型 #4ec9b0；enum 枚举 #b180d7（亮色 #652d90）；exception 异常 #f14c4c（亮色 #cd3131，和尝试、捕获、最终同一色系，更红一些）；field 字段、const 常量、variable 变量 #9cdcfe；if 条件、else 否则 #ce9178；loop 循环 #8f9cff；try 尝试、catch 捕获、finally 最终 #f48771；return 返回 #89d185；statement 语句 #9d9d9d；comment 注释 #6a9955（虚线框）；库规则的种类用规则给的颜色（`badge.color` 的 dark / light，webview 写在块的 style 上按主题挑），内置 SQLAlchemy 数据表 #e8a860 / #a3590d，Celery 应用 #98c379 / #4d7f17，定时任务 #56b6c2 / #127f8c，数据类 #ef7fb0 / #b3306c，FastAPI 接口 #61afef / #1a6fb5。编辑状态：底色 `--vscode-editor-background`，边框 `--vscode-focusBorder`。
|
||||
|
||||
## 代码位置
|
||||
|
||||
@@ -1217,6 +1303,8 @@ vscode/src/codeReader/
|
||||
rules/celery.ts 内置 Celery 库规则：两张卡片、频率换算、任务名索引
|
||||
rules/enum.ts 内置 enum 库规则（Python）：枚举类认成枚举块，成员照 Python 的规则认
|
||||
rules/dataclass.ts 内置 dataclasses 库规则（Python）：数据类卡片，字段照 dataclasses 的规则认
|
||||
rules/fastapi.ts 内置 FastAPI 库规则（Python）：接口卡片（请求表、响应表），参数照 FastAPI 的规则放，异常类的状态码、类型别名、枚举经索引查
|
||||
ruleLookups.ts 库规则认领时查别的文件里的定义（RuleContext.lookup）：先交出已知的、记下问了什么，发出预览后查（索引 + 语言扩展查定义），变了叫宿主重发（不碰 VS Code）
|
||||
rules/pythonTree.ts Python 库规则共用的读语法树的办法（名字最后一节、字符串内容、调用的参数、别名、注解里的 X[...]、库里的名字）
|
||||
rules/segments.ts 库规则共用的拼属性表文字的办法
|
||||
rules/children.ts 库规则共用的挑子块的办法（成员连同紧挨在它前面的注释块、成员的说明节点）
|
||||
@@ -1302,6 +1390,9 @@ vscode/webview-ui/code-reader.html + src/codeReader/ 预览界面（React，Vit
|
||||
- Celery 规则：`fixtures/celeryApp.py` 的应用卡片和定时任务卡片逐字同上面的样例（列名、「12 条，另有展开 1 处」、行尾注释、条目里单独成行的注释、跨行的 `10⏎ * 60`、`每 get_settings().… 秒`、展开一行）；任务名是引用、下标指回源码原文；应用卡片的位置参数按参数顺序认、别的参数各一行、展开、属性 docstring、别名；没导入 celery、不是 `Celery(...)` 的不认；频率换算（秒数算式、`timedelta`、`crontab` 各种写法、`schedule`、换算不了的「每 X 秒」和照写法）；说明取哪些注释；条目名和任务名不同、没写任务名、任务名不是字符串、值不是字典、选项一列有才有；`conf.update(beat_schedule=…)`、不带 `beat_schedule` 的 `conf.update` 和 `autodiscover_tasks` 照常。任务名索引：显式 `name=`、默认「模块路径.函数名」（包、`src` 下的命名空间包、没有包）、`@shared_task` / `@shared_task()` / `@app.task` 不带括号 / 老写法 `@task`、`async def`、函数里的只认显式名字、`name=` 不是字符串的不认、同名几处都给、文件改了和新建 `__init__.py` 后跟着变、没有任务装饰器的文件不解析。
|
||||
- 枚举（`rules/enum.test.ts`、`languages/typescript.test.ts`）：`fixtures/enumModels.py` 的 `CommissionStatus` 逐字同上面的样例，`SecretScope` 的 docstring 当说明、没有说明列；种类 enum、叫「枚举」、访问级别同原来的类、没有标签（badge），编辑范围是整个类；Python 成员规则（dunder、sunder、私有名、`_ignore_`、lambda、`property`、`nonmember`、只写注解的不是成员，`auto()` 写「自动」，`member(x)` 取 x，说明取上面的注释块、行尾注释、属性 docstring，装饰器）；方法、嵌套类、不是成员的属性照源码顺序是子块，成员前面的注释并进来、最后面的留下，「编辑」写回整个类；类名、成员名的定义范围和带下标的词指回源码原文；没导入 enum、SQLAlchemy 的 `Enum`、不是枚举类型的父类不认，`import enum as e` 的 `e.IntEnum` 认。TypeScript：`enums.ts` 里 export / const / declare / 函数里的 enum 都是枚举块、JSDoc 进头部，写的值、自增算出的值（接不上数字就没有）、说明（上面的注释和 JSDoc、行尾注释，同一行的 JSDoc 讲下一个），访问级别；自增的值和「自动」按 hint。TypeScript 和 Python 同样的成员得到一样的种类、属性表行、列名和格子着色（除了 Python 多的「继承」）。宿主：规则认成现成属性表块时照语言插件报的这种块显示、并进来的不是子块时照常显示；webview 枚举块默认折叠。
|
||||
- 数据类（`rules/dataclass.test.ts`）：`fixtures/dataclassModels.py` 的 `SandboxAccess` 逐字同上面的样例，`AdminUserRow`、`RedirectPayResult`（`field(init=False, default=…)`）、`SmsSent`（`default_factory=dict`）的行；种类 `dataclasses.dataclass`、叫「数据类」、颜色、访问级别同原来的类；编辑范围是整个类、写回原样，`__post_init__` 是子块；类名、字段名的定义范围和带下标的词指回源码原文；装饰器的写法（别名、`dataclasses.dataclass`、`dc.dataclass`）认，pydantic 的、`other.dataclass` 不认，没导入 dataclasses 不认；每个选项的译法、默认值不讲、别的照写、`**x`、别的装饰器一行；字段规则（`ClassVar`、`typing.ClassVar` 留作子块，`InitVar` 的类型和「仅初始化时使用」，`KW_ONLY` 记号并进来、后面的字段「只能按名字传参」、单独写 `kw_only=False` 的「可按位置传参」），`field(...)` 的默认值、`default_factory`（名字、lambda）、各参数、`metadata` 照写、`doc=`，说明取上面的注释块、行尾注释、属性 docstring；没注解的类属性、字段中间的方法照源码顺序是子块，「编辑」写回整个类。
|
||||
- FastAPI 接口（`rules/fastapi.test.ts`）：`fixtures/routes.py` 的 `update_user` 逐字同上面的样例（查到 `Forbidden` 是 403 时四条消息写在一行，没查到时不列），名字、颜色、图标、列名、筛选属性、定义范围、编辑范围是整个函数、函数体是子块；着色（URL 的 `{参数}` / 路径、方法的 Swagger 颜色、成功的状态码绿色、自动带的 422 淡色，带下标的词指回源码原文）；`fixtures/skillHubRoutes.py` 的 `list_skills`（Annotated 里的 Query、`_` 的依赖）、`get_skill`（HTTPException 的 status_code / detail）、`install`（Request 不算、`-> None` 没有内容）；`fixtures/consoleRoutes.py` 的 `create_user`（`status_code=201`、Pydantic 模型、调别的函数间接抛的不算）、`list_users`（查到的类型别名 `FilterQuery` 是依赖、Literal 是简单类型）；参数放在哪儿的各条（路径里的名字含 `{x:path}`、各种标记两种写法、上传文件、枚举和类型别名查到的、Pydantic 模型、`Security`、`Depends()`）；标签、依赖、`responses=` 叠上路由对象的，`status.HTTP_…` 常量、`response_model=None`、`response_description`、`raise … from`、只写 `raise`、嵌套函数里的；`FastAPI()` 上的接口、别的装饰器一行；不认的（没导入、路由对象在别的文件、不是路由对象、`websocket`、不带括号）。跨文件（工作区索引 + 假的语言扩展）：`update_user` 的 `Forbidden` 按定义处查到 `core/exceptions/schemas.py` 的 403，同名的别处的类不算；索引认的类上的 `status_code`（带注解、常量）、枚举类、`Annotated` 类型别名，普通类不认。
|
||||
- 规则查别的文件里的定义（`ruleLookups.test.ts`）：第一遍当没查到、记下问了什么（同一索引同名的只记一处）；查到后叫重排，交出定义处正是的那一项；同一版本不再查；索引里没有同名的不问语言扩展，定义处不是索引里的项算没有，没变不叫重排；新版本先用上一版的、再查、变了才叫重排；语言扩展没答时已知的不动、隔一会儿再查。
|
||||
- 带自己颜色的词（webview `SegmentText.test.tsx`）：`cr-colored`，暗色、亮色写在 style 上。
|
||||
- 异常（`languages/exceptions.test.ts`，真实解析 + 中文直译 + 视图数据）：`fixtures/appExceptions.py` 的 `AppException`、`NotFound` 逐字同「异常」的样例（列名随有没有类型、说明变），`GatewayTimeout` 的多段说明，方法是子块；`fixtures/commerceExceptions.py` 16 个类都是异常、只有说明的四行、写了 `__init__` 的构造参数；认哪些类（自带的异常类、`Warning`、不合后缀的自带类 `StopIteration` / `KeyboardInterrupt`、`pkg.errors.AppException`、同一文件里写在后面的父类一层层往下传、泛型和别的父类混写，关键字参数、`Mapping[...]`、`*bases` 不算，函数里的类也认）；类属性（带不带注解、只写注解、说明取上面的注释块 / 行尾注释 / 属性 docstring，连着赋值、解构赋值、方法、讲方法的注释、最后面的注释留作子块），构造参数去掉 self、`*args` 开头的不去；`@dataclass` 的异常类照样是异常卡片；编辑范围是整个类、改卡片写回整个类，类名、属性名、参数名的定义范围和带下标的词指回源码原文；TypeScript `fixtures/exceptions.ts.txt`（`extends Error`、类字段含 static、参数属性、JSDoc、写在后面的父类、类表达式、`ns.X<T>`，父类名不合习惯的照常是类）、JavaScript 的类字段；TypeScript 和 Python 同样的异常得到一样的行和列名；筛选的种类叫「异常」、没有 badge；属性的中文名和去掉行尾记号。webview：异常块默认折叠（`viewState.test.ts`），跳到类名闪整块、属性名 / 构造参数名只闪表里那一行（`reveal.test.ts`）。
|
||||
- 筛选：块的属性（TS、TSX 有抽象、仅类型，JavaScript / JSX 没有这两个属性、属性表也没有这两行，Python 有访问级别、异步）；语言插件自己报的属性叠上去、盖过推出来的，kind 不变；文件里出现过的属性按契约顺序排、语言的排后面，值按第一次出现排、带所有层的块数，名字取翻译插件的、没有的显示 id，中文直译的名字和属性表一致；下拉框只给两种以上值的属性（或一种值正被去掉的），按钮上的字；全选 / 取消全选只动这份文件里的值、别的文件的去掉状态和别的属性不动、取消全选藏掉有这个属性的块（整棵子树）、再全选全回来；同一属性内「或」、不同属性「且」、没有这个属性不受影响、藏整棵子树、「已隐藏」只数直接筛掉的；筛选记在 `workspaceState`、新实例读得回来、所有订阅的预览收到、形状不对的当没有；跳到被筛掉的块临时露出路径、目标的子块照常筛、文档刷新只留正在编辑的。
|
||||
- 文件注释：键相对工作区文件夹、`/` 分隔，根和外面的路径没有键，手写的 `./`、结尾 `/` 规范掉；保存去空白、清空即删；文件改名、目录挪位置里面各层一起走、名字只是前缀相同的不动、跨工作区文件夹先取出再放进去；删目录连带里面的；读写：文件缺失 / 解析失败 / 不是对象返回空表、跳过不合法条目、建 `.spx`、键排序、删光留 `{}`；有注释 / 没注释的行的描述、悬停提示（Markdown 转义）、contextValue，和 `package.json` 里菜单的 when 子句对得上。
|
||||
|
||||
Reference in new issue
Block a user