# @ai-matrx/associations 中文文档 规范地址：https://npmcn.com/package/%40ai-matrx/associations/ 版本：0\.14\.103 npm 元数据更新时间：2026-10-30T11:59:02.218Z 中文译文更新时间：2026-11-05T18:15:40.217Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40ai-matrx/associations 原文对照：https://npmcn.com/package/%40ai-matrx/associations/?lang=original 项目主页：https://github.com/AI-Matrix-Engine/aidream/tree/main/apps/shared/associations#readme 源码仓库：https://github.com/AI-Matrix-Engine/aidream ## 关键信息（来自 npm 元数据） - 包体积（解压后）：5.2 MB，60 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=20 - 运行依赖：4 个 - peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0 - 首次发布：2026-08-29T17:50:21.452Z - 最新版本发布：2026-10-30T11:59:01.935Z - 近 30 天下载量：92092（2026-10-05 至 2026-11-03，npm 官方下载统计） - 已发布版本数：387（近 12 个月 387 个） ## 中文简介 在 AI Matrx 平台上连接两个实体的一种方式:关联边缘词汇、生成的650个托肯实体类型注册、要求的 RPC 合同(assoc /cat /ues familys)和打入的端口 无头核心和React faces 绑定 t ## 安装 ```sh npm install @ai-matrx/associations ``` 也可以使用：`pnpm add @ai-matrx/associations`、`yarn add @ai-matrx/associations`、`bun add @ai-matrx/associations` ## README # @ai-matrx/协会 在AI Matrx平台上连接两个实体的方法: 关联边缘, 类别、最爱/最近和生成的实体类型词汇-已运出 matrx 客户端或企业应用程序安装的软件包. 包件装有"根"、"无头" `/core`,反应绑定 `/react`,以及软件包拥有的懒惰反应条目 `/react/lazy`: 服务 止住点 守卫 永不扔出结果漏斗 注册合并引擎, 可分解缓存商店、钩子和关联面相(卡、列表、, 拾取器、附件项目表、抓取工具栏)。 下面的一切 计划是有约束力的——它是包裹的产品. ```ts import { type EntityTypeToken, // generated from platform.entity_types ENTITY_TYPE_METADATA, // per-token schema/table/label/titleColumn/contentRole isEntityTypeToken, // runtime guard, narrows to the union type AssociationEdge, // one assoc_for_entity row (both directions) type AssociationsRpcResult, // the never-throw result envelope type DemandedRpcName, // the 27-function demanded RPC surface type AssociationsConfig, // the seven ports a host binds } from "@ai-matrx/associations"; ``` ```ts import { createAssociationsStore, // the ONE runtime object a host constructs } from "@ai-matrx/associations/core"; const store = createAssociationsStore({ dataSource: supabase, // structural subset of SupabaseClient identity: { requireUserId }, // throws when unauthenticated errorSink: (e) => report(e), // OPTIONAL — default screams to console entityOverlay: { file: { hrefFor: (id) => `/files/f/${id}` } }, // optional }); await store.load("task", taskId); // lazy, deduped, subscribable store.getEdges("task", taskId); // sync, stable idle default await store.add({ sourceType: "note", sourceId, targetType: "task", targetId }); store.titles.prime("task", taskId, "Renamed"); await store.favorites.setFavorite("note", noteId, true); // There is NO boot check to call (0.9.0). A database that cannot answer a // demanded function says so at the first real call: PostgREST returns // PGRST202 and the package screams `demanded_schema_violation` with a remedy. ``` `useContainerLinks({ containerType, containerId, orgId })` 是犬科动物 容器侧反相 API. 内容 `attach`, (中文(简体) ), `detach`,以及 `setPinned` 全部操作 瞄准精确的角色合格边缘; `setPinned` 保存了边缘的另一个 元数据字段. `AssociationCardGrid` 默认 `AssociationList` 适配器在没有主机接线的情况下曝光这些相同的操作. ```tsx // /react — the banner'd React binding (peer: react >=18; // @ai-matrx/design-system is a real dependency — the faces' chrome // installs automatically). Bind ONCE: import { AssociationsProvider, useAssociations, // the seven hooks keep the app originals' exact signatures AssociationCardGrid, // + AssociationCard / AssociationList / pickers / capture toolbar PrimaryEntityProvider, } from "@ai-matrx/associations/react"; ; ``` 有 Tailwind 语义符号的面相样式(`bg-card`, (中文(简体) ), `text-muted-foreground`,...):将此软件包注册为 Tailwind v4 源 消费应用( e)`@source "../node_modules/@ai-matrx/associations/dist"`(中文(简体) ) 同样的方式 `@ai-matrx/design-system` 文档. ## 要求的策略 这个软件包是 **感觉就像Python一样 `matrx-*` 软件包**: 没有 适应你的数据库 它需要我们的 一个不会搞我们计划的消费者 不是这个包裹的消费者。 它没有DDL(DB平台拥有;管理) 消费者利用我们的基础设施;它以三种方式满足需求: 文档(此处),键入(`DemandedRpcSignatures`,由活的 DB 生成), 并尖叫着第一个真正的电话(PGRST202~) `demanded_schema_violation`, (中文(简体) ), (有补救措施)。 每一次侵犯 **尖叫,永不堕落**。 。 。 . 1. **边缘.** `platform.associations(source_type, source_id, target_type, target_id, organization_id, label, metadata, role, position, created_by, created_at, deleted_at, …)` - 一个多形态的桌子,在5个圆顶上独一无二 `(source_type, source_id, target_type, target_id, role)` `NULLS NOT DISTINCT`。 。 。 . 类型列为 FK- 校验 `platform.entity_types.token`。 。 。 . 2. **仅限RPC.** 客户持有 **无赠款** {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}就放在桌子上 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢? 每一次行动都会发生 通过安全保卫局的27个职能 `DEMANDED_RPC_NAMES` (单位:千美元)`assoc_*` ×8, `conversation_file*` ×3, `agent_resource_*` ×2, `cat_*` ×5, `ues_*` ×4, `reference_search_candidates`,W6评论家族 `cmt_*` ×4). 那些读者只吃活的 `associations_live` 视图,所以墓碑语义学(一个被废弃的实体) 柔和地移动它的边缘;恢复它们) 由建筑支撑——这个 软件包从不写 `.is("deleted_at", null)` 过滤器。 DB的遗产 `assoc_link`编号 :`assoc_list`编号 :`assoc_unlink` 三重奏是故意不要求的. 3. **方向是登记拥有的:小-大.** 资源是 资源 目标容器`task → organization`, (中文(简体) ), `file → scope`) (中文(简体) ). DB 触发器 `trg_associations_auto_orient` 拒绝倒转的写出—— 此软件包 显示该错误的逐字字, 并且永远不会为您翻出一个边缘 . 4. **联系从来不是赠款.** 无障碍生活 `iam.permissions` 编号 : `iam.memberships`. 唯一被认可的协会-接入桥是DB-侧 运输`platform.association_types.conveys_max` − 可达到性)。 这个 软件包制作 **零准入决定**。 。 。 . 5. **缺失的函数尖叫.** 任何需要的RPC地图上的PGREST PGRST202 页:1 `demanded_schema_violation` 结果代码并总是到达您的 错误Sink:没有我们计划的数据库会产生一个毫不含糊的尖叫,而不是 一个神秘的祝酒词. ## 符号词汇——写作严格,读作宽容 `EntityTypeToken` 镜像 `platform.entity_types` 1:1(651个活化符号), 由 `pnpm gen:entity-types` 在这个包裹里。 扭曲策略 : - **写作是STRICT** 对照已安装的词汇表: 此版本的符号 在Postgres之前的密码里 并不知道警卫的失败 缺少 DB 类型。 问题在于 `pnpm up @ai-matrx/associations` (登记更改) 船舶为 **补丁释放**从来没有一个生弦扩大. - **读取是TOLERANT**: 边缘带有一个符号 知道通过倒置(默认图标、原始标签、没有门) 坠毁. ## 港口 -- -- 需要两个港口,其余港口为防御港口 一个 `AssociationsConfig`,每个主机绑定一次。 仅 **`dataSource`** 联合国 结构子集 `SupabaseClient` 回答要求的保护责任)和 **`identity`** 需要建造,因为没有它们 是你的应用程序的身份 没有软件包能发明它们. 其它所有船只都属于工作默认(C23——你超越了港口,你从不) 必须填满: | 端口 | 未绑定时默认 | | --- | --- | | `errorSink` | `createDefaultErrorSink()` - 标记 `console.error` 每个事件; 宣布 ONCE 不约束任何汇并指定补救. | | `windowShell` | `DefaultWindowShell` ——真正可拖放/可换放/可最大可换放/可换放/可换放/可换放/可换放/可换放/可换放/非模式窗口;640px下为全宽底卡. 仅为真实窗口 MANAGER( 盘点对接, 工作空间持续性) 装入此端口 . | | `capture` | 捆绑 `uploadFile(file, { folderPath, visibility })` 和包 传输文件输入,拖放,批量,摊位监督 和每一个响亮的结果。 捆绑 `requestUpload` 而当你拥有更丰富的管道。 没有路的芯片永远不会被制成. | | `pickerOverrides` | 包装 `AssociationPicker` 服务每个符号(地址列表、搜索、附件/调试、创建-当时关联页脚). | | `entityDoors` | `DoorControlsSlot` 使一个真正的标签 `target="_blank"` 从上下文起锚 `hrefFor`无路可走的标志 只会成为无路可走的门. | | `entityOverlay` | 公约栏,默认图标, `${label}s`没有门. | | `notifier` | 通过出错Sink发出警告,每一次用户提示失败仍然会到达出错Sink. (没有土司堆栈船:土司表面需要一个主机挂起的根,所以"默认"就是这个套件存在的无声无息的去防止. ) | | `authorDisplay` | `cmt_list`'非正常的作者字段,然后是"未知的用户"——永远不空白. | ## 代码分割——软件包拥有它 导入重脸从 **`@ai-matrx/associations/react/lazy`** 每个 第一次变形时就到达了自己的地段 没有 `next/dynamic`,没有 `ssr: false`, (中文(简体) ), 没有主机胶水 : ```tsx import { AssociationCardGrid } from "@ai-matrx/associations/react/lazy"; ``` 对于连接到端口的HOST组件,请使用同一接缝: ```tsx windowShell: { Window: lazyWindowShell(() => import("./hostWindow").then((m) => m.HostWindow)), }, pickerOverrides: { file: lazyPickerOverride(() => import("./hostPicker").then((m) => m.HostPicker)), }, ``` 每件拾取器应装订 `useAssociationPickerBridge(props)` 页:1 它的附着/调试写作——它带有响亮的部分结果、拒绝和 创建但无附件的报表,所以一个覆盖永远不会重新执行它们. ## 版本 被马特克丝重新占有 `latest` (单位:千美元)`workspace:*` 活塞内单体) ——从未被钉住。 登记符号更改 / 重新生成 / 补丁 . 合同变更 − 每套小/主要. ## 许可证 麻省理工学院 ## 常见问题 ### @ai-matrx/associations 是什么？ 在 AI Matrx 平台上连接两个实体的一种方式:关联边缘词汇、生成的650个托肯实体类型注册、要求的 RPC 合同\(assoc /cat /ues familys\)和打入的端口 无头核心和React faces 绑定 t ### 如何安装 @ai-matrx/associations？ 在项目目录运行 npm install @ai-matrx/associations，或使用 pnpm add / yarn add / bun add。 ### @ai-matrx/associations 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @ai-matrx/associations 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @ai-matrx/associations 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @ai-matrx/associations 可以商用吗？ @ai-matrx/associations 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @ai-matrx/associations 的下载量有多少？ 根据 npm 官方下载统计，@ai-matrx/associations 在 2026/10/05 – 2026/11/03 这 30 天内被下载 92,092 次，日均约 3,070 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @ai-matrx/associations 还在维护吗？ 最新版本 0\.14\.103 发布于 2026/10/30（6 天前）；至今共发布 387 个版本，其中过去 12 个月发布了 387 个；首次发布于 2026/08/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。