npm - @wisdomgarden/torque-knowledge - Versions diffs - 0.1.2 → 1.0.3 - Mend

@wisdomgarden/torque-knowledge 0.1.2 → 1.0.3

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.

Files changed (5) hide show

package/README.md +37 -7
package/dist/.meta.json +2 -2
package/dist/components.db +0 -0
package/dist/torque-components.md +51 -50
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -12,8 +12,8 @@
 | 文件 | 给谁 | 是什么 |
 | --- | --- | --- |
-| `dist/torque-components.md` | **diting**（`lms-web` 的 CI code review） | 选型决策树 + 可用组件全表 + 硬约束 + 禁止事项。带 diting 认的 frontmatter（单行 `keywords` / `globs`），解包进它的 `rule_dirs` 就能被召回 |
-| `dist/components.db` | **`lms-web` 的本地 MCP** | SQLite 组件目录，`search_component()` 的数据源。44 个组件的导出名、英文描述、keywords 和完整 props |
+| `dist/torque-components.md` | **diting**（`lms-web` 的 CI code review） | 选型决策树 + 可用组件清单 + 硬约束 + 禁止事项。**只有清单和策略，没有组件细节** —— 细节查 `components.db`。带 diting 认的 frontmatter（单行 `keywords` / `globs`），解包进它的 `rule_dirs` 就能被召回 |
+| `dist/components.db` | **`lms-web` 的本地 MCP** + **diting** | SQLite 组件目录，MCP `search_component()` 和 diting `query_ui_components` 共同的数据源。44 个组件的导出名、英文描述、keywords 和完整 props |
 | `dist/.meta.json` | CI / 下游漂移检测 | `{ knowledge, torque, generatedAt }` —— 这份知识是哪个版本、描述的又是哪个 torque 版本 |
 ## 版本与 `@wisdomgarden/torque` 相互独立
@@ -50,7 +50,7 @@ src/handwritten/*.md                       ← 人工提炼的正文片段
         └──> scripts/gen.mjs ──> dist/
 ```
-机械的部分（扫源码、解析 props、产 db 和组件全表）在 `gen.mjs` 里，每次 `pnpm build`
+机械的部分（扫源码、解析 props、产 db 和组件清单）在 `gen.mjs` 里，每次 `pnpm build`
 都跑。需要判断力的部分（读懂 readme 提炼选型/约束、复核英文描述）在
 `.claude/skills/torque-knowledge/` 这个 skill 里。
@@ -73,13 +73,43 @@ node scripts/check-changes.mjs                # 有变化就顺便重新生成
 - **组件清单从 barrel 推，不要 `readdir`。** `components/sticky-box.tsx` 是裸文件、
   没有目录也没有 readme，但公开导出 `StickyBox`；`_inner/` 则不该暴露。barrel 两个问题都没有。
-- **`components.db` 的 schema 是硬契约。** `lms-web` 的 reader 按字段名取值，
-  改了名那边静默返回 `undefined`，不会报错。
+- **`components.db` 的 schema 是硬契约，而且有两个消费端。** `lms-web` 的 MCP 和 diting 的
+  `query_ui_components` 都按字段名取值，改了名两边都静默返回 `undefined`，不会报错。
+  **表名 `components` 也是契约** —— diting 不认文件名，它在 `rule_dirs` 下逐个 SQLite
+  文件试探「有没有 `components` 表」来发现这份目录，所以文件名能改、表名不能。
 - **db 保持默认的 `DELETE` journal 模式，不要设 WAL。** WAL 标记会持久化进 db header，
   产物在只读目录下会直接打不开。
+- **md 只放「有什么」和「怎么选」，组件细节一律留给 `components.db`。** 清单里只有
+  组件名和导出名，没有描述 —— 用途、完整 props、readme 里的注意事项都按需查 db。
+  两条界线：
+  - **不能砍到只剩组件名。** kebab → Pascal 有一串不规则的（`form-wrapper` →
+    `FormItemWrapper`、`provider` → `UiProvider`、`tab` → `Tabs`、`message` →
+    `messages`），而且好几个组件导出多个名字。少了导出名，模型要么多查一次 db
+    才能写 `import`，要么猜错一个标识符。这一列 1 KB，买的是「不用查就能正确导入」。
+  - **也不能整节砍掉。** 模型不知道有什么就不会去查 —— 「不知道自己不知道」。
+    这份文件的全部意义就是防止它自己造一个组件或直接用 mantine 原生的。
+  - **要明说「一次能查多个」。** 清单没有描述，模型选型时手上是一串候选，逐个查就是
+    逐个 round trip。这句话不绑参数形态（空格分隔还是数组由两端实现决定），只说能力。
 - **`torque-components.md` 的 frontmatter 是 diting 的硬契约**：`keywords` / `globs`
-  必须单行逗号分隔（它用 `^keywords:\s*(.*?)$` 解析，多行 YAML 数组会静默变成空），
-  且**不能**设 `alwaysApply: true`（那等于每次 review 都全量注入）。
+  必须单行逗号分隔（它用 `^keywords:\s*(.*?)$` 解析，多行 YAML 数组会静默变成空）。
+- **不设 `alwaysApply: true`，但这份 md 事实上每次 review 都全量注入。** 别以为
+  `alwaysApply: false` 拦住了什么。召回是 **keywords 驱动**的，而且是对**整个 diff**
+  做子串匹配 —— `rule_loader.py` 的 `load_matched_rules` 把「改动文件路径 + 完整 diff」
+  拼成一个 `search_text`，然后 `if kw in search_text_lower`。我们的 keywords 里有
+  `ui` / `text` / `tab`，而 `build` 含 `ui`、`context` 含 `text`、`table` 含 `tab` ——
+  任何非空 diff 基本必中。而 keywords 一命中就 `continue`，`globs` 那条路径根本走不到。
+  `globs` 本身也很宽，只是宽得没那么彻底：`_match_glob` 把 `**/*` 压成 `*` 再交给
+  Python `fnmatch`，而 `fnmatch` 的 `*` 是匹配 `/` 的，所以 `globs: src/**/*.{tsx,ts}`
+  等于「路径里含 `src/` 的任何 `.ts`/`.tsx`」—— lms-web 有 5974 个这样的文件，另有
+  296 个在 `testing/` 下（那些只有 keywords 能召回）。
+  全量注入本身是可以接受的（组件选型规则本来就该对每个 tsx 生效，14.5 KB 不是大头），
+  **但想收敛只能剪 keywords，收窄 `globs` 一个字节都省不下来。** 而剪掉 `ui` / `component`
+  这类泛词，模型主动 `search_project_rules` 时的召回也跟着掉 —— 同一个旋钮的两个方向，
+  所以现状是刻意的选择，不是疏漏。
+- **别在 `.md` 里写某一端专有的工具名**（`search_component()` 之类）。这份 md 是给
+  diting 读的，而那个名字只存在于 lms-web 的 MCP，diting 里没有；写了模型会照着调，
+  拿一个 "tool not found" 白烧一轮探索预算。指数据文件（`components.db`）两端都成立。
 - **`gen.mjs` 不写回 `src/fallback.json`。** 缺 entry 就报错退出，由人补。
   写回会让 `pnpm build` 变成改动被追踪源文件的操作。
 - **不要给这个包加 npm 依赖。** 它会被解包进 CI 环境，只用 Node 内置模块。

package/dist/.meta.json CHANGED Viewed

@@ -1,5 +1,5 @@
 {
-  "knowledge": "0.1.2",
+  "knowledge": "1.0.3",
   "torque": "0.1.2",
-  "generatedAt": "2026-09-16T14:28:56.156Z"
+  "generatedAt": "2026-09-17T08:48:43.743Z"
 }

package/dist/components.db CHANGED Viewed

Binary file

package/dist/torque-components.md CHANGED Viewed

@@ -6,7 +6,7 @@ keywords: torque, component, ui, mantine, layout, button, icon-button, link-butt
 # Torque UI 组件库
-> 由 `@wisdomgarden/torque-knowledge@0.1.2` 生成，对应 `@wisdomgarden/torque@0.1.2`。
+> 由 `@wisdomgarden/torque-knowledge@1.0.3` 生成，对应 `@wisdomgarden/torque@0.1.2`。
 > 不要手改 —— 它是 npm 包解包出来的，下次装依赖就被覆盖。
 ## 导入方式
@@ -64,57 +64,58 @@ Server Component 序列化不了。
 Client Component 都安全。Mantine 的 `component={ReactComponent}` 只能在 Client
 Component 里用（函数跨 Server/Client 边界无法序列化）。
-## 可用组件全表
+## 可用组件清单
 全部从 `@wisdomgarden/torque`（lms-web 侧是 `@/ui/base`）导出。
-完整 props 和完整描述查 `components.db`（MCP 的 `search_component()`），这里只给选型用的一句话。
-| 组件 | 导出名 | 何时使用 |
-| --- | --- | --- |
-| button | `Button` | General-purpose button with multiple variants (primary,… |
-| icon-button | `IconButton` | Icon-only button built on Button |
-| link-button | `LinkButton` | Button-looking navigation component with native <a> sem… |
-| link-icon-button | `LinkIconButton` | Icon-only navigation component with IconButton appearan… |
-| tooltip | `Tooltip` | Hover tooltip for short contextual help text or to reve… |
-| popover | `Popover`, `PopoverTarget`, `PopoverDropdown` | Floating popover component that displays content near a… |
-| drawer | `Drawer`, `DrawerManager`, `drawers` | Side panel sliding in from the right by default, with a… |
-| bottom-drawer | `BottomDrawer` | Bottom sheet that slides up from the bottom edge |
-| modal | `Modal` | PC-side modal dialog with a custom header (title + clos… |
-| menu | `Menu` | Responsive action menu |
-| message | `messages` | Imperative lightweight toast shown top-center, auto-clo… |
-| notifications | `notifications`, `Notification` | Imperative global notification popup shown top-right, a… |
-| alert | `Alert`, `AlertSkeleton` | Inline status banner with built-in icon, semantic color… |
-| sticky-box | `StickyBox` | Pin a block to the top or bottom of its nearest scroll… |
-| tag | `Tag` | Compact label/badge for categorization, status, or meta… |
-| tab | `Tabs`, `TabsTab`, `TabsList`, `TabsPanel` | Primary tab navigation with Tabs, TabsList, TabsPanel,… |
-| table | `Table`, `TableSkeleton` | Data table with sortable columns, row selection, and a… |
-| table-pagination | `TablePagination`, `Pagination`, `getPaginationRange` | Standard pagination bar for tables: page numbers, a per… |
-| tree | `Tree` | Hierarchical tree component for displaying nested data… |
-| tree-select | `TreeSelect` | Hierarchical tree selector with dropdown support, check… |
-| virtualized-tree-select | `VirtualizedTreeSelect` | Virtualized hierarchical tree dropdown for selecting fr… |
-| date-picker | `DatePicker`, `TimePicker`, `DateTimePicker`, `DateRangePicker` | Date and time selection components including DatePicker… |
-| filter | `Filter`, `IconFilter`, `MultiFilter` | Filter triggers built on Select/MultiSelect that open a… |
-| data-filter | `DataFilter` | The shared, business-agnostic container for data-filter… |
-| base-input | `BaseInput`, `BaseInputTarget`, `BaseInputWrapper` | Foundation input component providing the base structure… |
-| form-wrapper | `FormItemWrapper`, `FormItemWrapperDefaultsProvider`, `useFormItemWrapperDefaults` | Wrap a form field with a consistent label, helper text,… |
-| text-input | `TextInput` | Standard single-line text input field |
-| text-area | `TextArea` | Multi-line text input for longer free-form content such… |
-| number-input | `NumberInput` | Numeric text field with increment/decrement stepper but… |
-| password-input | `PasswordInput` | Password field with a show/hide visibility toggle |
-| checkbox | `Checkbox` | Checkbox for a single boolean choice and CheckboxGroup… |
-| radio | `Radio` | Radio button and RadioGroup for mutually exclusive sing… |
-| switch | `Switch`, `SwitchGroup` | Toggle switch for a single boolean on/off setting |
-| select | `Select` | Single-value dropdown selector |
-| multi-select | `MultiSelect` | Multi-value selector rendered as an input field with se… |
-| combobox | `Combobox`, `useCombobox`, `useComboboxContext` | Compound dropdown selection component with desktop Popo… |
-| box | `Box` | The most basic layout primitive, a drop-in replacement… |
-| text | `Text` | Text rendering primitive built on Box, adding font size… |
-| flex | `Flex` | Generic flexbox container with full CSS flex control |
-| group | `Group` | Horizontal row layout with default center alignment, wr… |
-| stack | `Stack` | Vertical column layout with default stretch alignment a… |
-| paper | `Paper` | Visual surface container (card/panel) with raised backg… |
-| unstyled-button | `UnstyledButton` | Button without any default styling — a blank slate for… |
-| provider | `UiProvider`, `UiContext`, `DefaultUiLink`, `useLocale` | UiProvider is the single configuration entry point for… |
+**下面只有清单，没有细节。** 每个组件的用途、完整 props、readme 里的注意事项都在组件目录 `components.db` 里 —— 选型和写 props 之前，用你当前环境提供的组件查询工具查一下，不要靠名字猜。
+**一次可以查多个组件。** 把这一轮要用到的候选一起传进去、一趟全拿回来，不要一个一个查。
+| 组件 | 导出名 |
+| --- | --- |
+| button | `Button` |
+| icon-button | `IconButton` |
+| link-button | `LinkButton` |
+| link-icon-button | `LinkIconButton` |
+| tooltip | `Tooltip` |
+| popover | `Popover`, `PopoverTarget`, `PopoverDropdown` |
+| drawer | `Drawer`, `DrawerManager`, `drawers` |
+| bottom-drawer | `BottomDrawer` |
+| modal | `Modal` |
+| menu | `Menu` |
+| message | `messages` |
+| notifications | `notifications`, `Notification` |
+| alert | `Alert`, `AlertSkeleton` |
+| sticky-box | `StickyBox` |
+| tag | `Tag` |
+| tab | `Tabs`, `TabsTab`, `TabsList`, `TabsPanel` |
+| table | `Table`, `TableSkeleton` |
+| table-pagination | `TablePagination`, `Pagination`, `getPaginationRange` |
+| tree | `Tree` |
+| tree-select | `TreeSelect` |
+| virtualized-tree-select | `VirtualizedTreeSelect` |
+| date-picker | `DatePicker`, `TimePicker`, `DateTimePicker`, `DateRangePicker` |
+| filter | `Filter`, `IconFilter`, `MultiFilter` |
+| data-filter | `DataFilter` |
+| base-input | `BaseInput`, `BaseInputTarget`, `BaseInputWrapper` |
+| form-wrapper | `FormItemWrapper`, `FormItemWrapperDefaultsProvider`, `useFormItemWrapperDefaults` |
+| text-input | `TextInput` |
+| text-area | `TextArea` |
+| number-input | `NumberInput` |
+| password-input | `PasswordInput` |
+| checkbox | `Checkbox` |
+| radio | `Radio` |
+| switch | `Switch`, `SwitchGroup` |
+| select | `Select` |
+| multi-select | `MultiSelect` |
+| combobox | `Combobox`, `useCombobox`, `useComboboxContext` |
+| box | `Box` |
+| text | `Text` |
+| flex | `Flex` |
+| group | `Group` |
+| stack | `Stack` |
+| paper | `Paper` |
+| unstyled-button | `UnstyledButton` |
+| provider | `UiProvider`, `UiContext`, `DefaultUiLink`, `useLocale` |
 ## 硬约束

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@wisdomgarden/torque-knowledge",
-  "version": "0.1.2",
+  "version": "1.0.3",
   "description": "Machine-readable knowledge artifact for @wisdomgarden/torque — component catalog (SQLite) and AI coding rules (Markdown). Consumed by CI code review and local AI tooling, not by application runtime.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",