# @alwith/module-drive 中文文档

规范地址：https://npmcn.com/package/%40alwith/module-drive/

版本：0\.6\.2
npm 元数据更新时间：2026-11-05T13:00:53.546Z
中文译文更新时间：2026-11-06T15:37:10.586Z
软件包许可：SEE LICENSE IN LICENSE

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40alwith/module-drive
原文对照：https://npmcn.com/package/%40alwith/module-drive/?lang=original
项目主页：https://github.com/ALwith-ai/alwith-modules#readme
源码仓库：https://github.com/ALwith-ai/alwith-modules

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：18.4 MB，819 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：yjs ^13\.6\.33，react ^19\.3\.1，react-dom ^19\.3\.1，y-protocols ^1\.0\.7，y-websocket ^3\.1\.0，lucide-react ^1\.61\.0，@milkdown/ctx ^7\.22\.2，y-prosemirror ^1\.3\.7，@milkdown/core ^7\.22\.2，@milkdown/prose ^7\.22\.2，@milkdown/utils ^7\.22\.2，@tauri-apps/api ^3\.0\.0-alpha\.3，@alwith/module-editor ^0\.6\.0，@milkdown/plugin-collab ^7\.22\.2
- 首次发布：2026-10-22T10:35:17.378Z
- 最新版本发布：2026-11-05T13:00:53.144Z
- 近 30 天下载量：2880（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

预发共享驱动模块. 这个软件包将前端和私人本地 Drive 图书馆(`native/`); Tauri 插件 `alwith-drive` (crates.io)携带公共类型,打出的命令和交易的Rust API. 前端和库 ve

## 安装

```sh
npm install @alwith/module-drive
```

也可以使用：`pnpm add @alwith/module-drive`、`yarn add @alwith/module-drive`、`bun add @alwith/module-drive`

## README

# @ alwith/ 模块驱动

预发共享驱动模块. 这个软件包将前端和私人本地 Drive 图书馆(`native/`); Tauri 插件 `alwith-drive` (crates.io)携带公共类型,打出的命令和交易的Rust API. 前端和库版本总是相匹配. 该引擎取自AL With桌面; `desktop-provenance.json` (kept in the source,未发布)记录出源修订.

## 入境点

-   `@alwith/module-drive`:生成协议类型,传输接口和控制器.
-   `@alwith/module-drive/react`:控制器订阅,发射装置/设置/状态面板,权限,徽章,质量-删除确认,本地化和被绑入帮助器. 注入主机阴影控制与导航.
-   `@alwith/module-drive/content`:评论,Markdown/HTML集成,协作,前题,版本,知识活,聊天建议,跨项目移动和文件链接帮助者.
-   `@alwith/module-drive/tauri`数字 : `createTauriDriveTransport()` 超过插件的命令和 `drive:event`。 。 。 .
-   `@alwith/module-drive/commands`: 生成了已键入的插件命令和事件.
-   `@alwith/module-drive/styles.css`:有范围化的语义-token风格.

## 东道方合同

登记册 `.plugin(alwith_drive::init(Config::new(|app| ...).event_windows(["main"]).development_directory(development_directory)))`; 关闭打开一个 `DriveService` 从应用程序数据,共享所有者注册,默认本地目录,保留遗留的应用程序目录,设备身份和一个系统浏览器打开器. 启动失败由每个命令保存并返回 。 插件发送 `drive:event` 以新快照(生成/序列合同)取代一个已忽略的用户跳出的事件; 失败的运输流(队列溢出) 被报告为出错, 绝不是重同步 。 赠款 `alwith-drive:default` (单位:千美元)`allow-request`用于使用 Drive 的窗口. `alwith-drive:allow-session-request` (MCP和合作证书: `mcpSessionConfig`, (中文(简体) ), `collabSession`和 `alwith-drive:allow-collaborative-write` (单位:千美元)`writeCollaborativeDocument`)是单独的权限;授予每个应用程序与用户的 Drive 会话信任的窗口,例如桌面聊天窗口. 插件不将其限制在窗口标签上 。 保存从快照、日志和持续前端状态的证书 .

在获取初始快照前订阅 . `createDriveController` 缓冲此间隔并调和生成/序列间隙。 窗口的处理会停止它的收听器,而不是应用程序服务. 出发前 `app.state::<Drive>()`数字 : `begin_shutdown()` 一次,然后等待着 `shutdown()` (取消交易、排水和停止同步、结束事件交付),然后退出; `is_stopped()` 告诉出口钩让出口通过.

所有可以相接 Drive 根的本地文件系统突变必须贯穿 `DriveService::with_filesystem` (或 `with_collaborative_filesystem`, (中文(简体) ), `with_move_to_filesystem`)在主机路径授权后;放下未来会取消交易。 传递精确的写入目的地并删除源路径 。 它以完整的同步回合来序列本地更改,检查索引为只读/协作状态,并记录成功的去除意图. 这个粗糙的协调员可以在转移时延迟操作. 它不是一个OS sandbox:外部编辑和代理使用普通文件系统权限.

新的根必须默认为空. 主机可选择加入 `DriveService::with_existing_default_root()` ,以仅在已配置的默认根上采用已存在的文件。 这不会移动或删除文件,也不会放松对已注册根或自定义目录的所有权检查. 由cononical root,count/server和主机数据目录持续拥有所有权;重叠的root和被另一个剖面重用被拒绝. 遗留客户端不参与注册:共享默认目录需要相同的服务器/账户和严格的相继操作,之前的同步进程完全停止. 主机从 AL 升级并带有桌面通过 `OpenOptions::new().legacy_desktop(LegacyDesktopProfile { store, settings, index })` 改为 `DriveService::open`数字 : `store` 属于桌面 `drive.json` 已命名仓库( e)`baseUrl`, (中文(简体) ), `token`, (中文(简体) ), `deviceId`, (中文(简体) ), `localRoot`, (中文(简体) ), `userName`, (中文(简体) ), `settings` 联合国 `settings.json` (单位:千美元)`drive.*` (按键)和 `index` 联合国 `drive/index.sqlite3`当插件没有时 `profile.json` 然而, Drive 报告桌面配置已配置; 第一个需要它的操作( 通常为 `start`)识别账户,采用"桌面"目录,将索引(有WAL文件)移入配置文件,并用"桌面"的偏好,下载阈值,服务器配置和本地服务器覆盖来写入配置文件. 没有网络,操作就失败了,进口就待处理; `logout` 拒绝它。 桌面除索引之外的其他文件从未被更改,一个书面的配置文件,在或不签名的情况下,永远结束导入.

证书被存储在原生原子剖面文件(Unix上只有所有者的权限);保护主机OS上包含的应用数据目录. 日志保存本地文件 。 退位保留了被取出引擎的清理/剩余行为. 测试撤销时使用专用账户和临时目录.

## 当前边界

在获得实际服务和多客户接受之前,这仍然是一体化候选人。 专门小组单独提供 `launcher`, (中文(简体) ), `settings` 财务报告和审定财务报表 `status` 模式; 主机提供本地目录选择、导航、设置路由和外部打开。 它利用现有的工作空间,而不是制造出第二棵树. 下载偏好在保留暂停状态的同时修改了引擎的加载.

通过挂起选择内容集成 `DriveContentProvider`,将管理过的文档以 `CommentSurface`合并 `drivePreviewIntegrations` 输入共享编辑器主机。 供应 `saveDocument` 并跟踪协作所有权。 路线授权协作原子写入 `with_collaborative_filesystem`; 普通写作仍然受约束 `with_filesystem`。锁定源编辑与协作预览权限分开。 内容条目需要它的可选的 Milkdown, Yjs 和编辑端对等依赖性.

挂载 `DriveMassDeleteDialog` 在主窗口中独立于面板可见度. `ChatCondenseEntry` 选择主机首选项存储其30天 snooze; 将批准的工作传递给 `DriveCondense.initialJob`。将对话框所有权保留在临时上下文菜单之外。 主机选择他们的OS链接方案;避免声称另一个应用程序的注册协议.

存档默认已禁用 。 主办方通过现有对话拥有者获得明确同意,进行出口对话,并提供 `expectedGeneration` 每个上传。 本地代码在过滤和上传前重新检查同意,私会排除,工作空间标记和生成. 存档元数据包含散列和状态,而不是第二个对话商店. 为每个明确的会话工作空间确定知识和MCP配置。 在启动本地引擎前配置一个技能目录 .

清除意图是继承的内置引擎状态;不提供崩溃安全删除/移动恢复。 共享服务没有添加数据库迁移计划。 编辑器主机必须保存脏缓冲并检查预期的文件版本. 原生的工作空间大小限制在下载后仍然适用. 只云文件不能在本地编辑;协作文件需要明确的所有者适配器而不是普通的源写.

生成的JSON数字字段使用JavaScript数字,匹配了已存在的传输. JavaScript安全整数范围以外的值不支持;远程标识符保存字符串变体.

## 发展

```sh
bun install
bun run bindings   # regenerates src/generated/commands.ts and src/contract.ts from the plugin
bun test src
cargo test --manifest-path rust/Cargo.toml
bun run build
```

使用仓库 `scripts/build-npm.ts` 建会者. 当地图书馆建成后, `ALWITH_NATIVE_DIRECTORY=<target/debug> cargo test --manifest-path rust/Cargo.toml -- --ignored` 练习客户端对抗它。 只有在明确发布决定和真实的原生,多进程和被支持的平台验证后才能发布.

## 桌面能力

-   `DriveService::open(options, OpenOptions)` 添加主机选择 : `session_archive_directory` (内在会话存档), `default_preferences` (未选择任何配置文件的首选项;桌面使用) `knowledgeInject: true`和 `legacy_desktop` (上经. `DriveService::new(options)` 保持之前的行为.
-   会话归档: 与 `session_archive_directory`,在对话目录开始时驱动该目录,每5分钟一次 `archiveSyncNow`时 `sessionArchive` 正在打开, 跳过标为私下的会话 。 每发子弹 `archive` 活动(`syncing` 真实的,然后是假的 `archiveStatus` 报告本地档案。 没有目录, 主机会继续导出对话 `archiveSession`,以及 `archiveSyncNow` 是一个错误.
-   服务器覆盖 : `serverOverrides` 编号 : `setServerOverrides { overrides }` 读取和更改 `webBaseUrl`, (中文(简体) ), `collabRelayUrl`, (中文(简体) ), `transferConcurrency` (第1至64段) `maxUploadMb` (0无限制). 他们坚持在签注范围之外。 地址仅在服务器未发布客户端配置时才应用; `maxUploadMb` 输出到服务器限制。 运行中的引擎会重新启动, 并保留暂停状态 .
-   `moveToCloudDirectory { sources, directory }` 将驱动项移动到未降落在本地的云文件夹并回答 `cloudMove { moved, error }`。 。 。 .
-   `recheckCloudOnly` 答题 `cloudOnlyRecheck` 及其计数,引擎重新检查时会发出 `cloudOnly` 事件(合同生成2).
-   `searchUsers { query, limit? }`:1至50个用户,缺席时为20个.
-   `knowledgeContext` 每个工作空间缓存10分钟,然后通过任何配置、偏好或引擎变化来清除.

## 常见问题

### @alwith/module-drive 是什么？

预发共享驱动模块\. 这个软件包将前端和私人本地 Drive 图书馆\(native/\); Tauri 插件 alwith-drive \(crates\.io\)携带公共类型,打出的命令和交易的Rust API\. 前端和库 ve

### 如何安装 @alwith/module-drive？

在项目目录运行 npm install @alwith/module-drive，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.3\.1）、react-dom（^19\.3\.1）、@tauri-apps/api（^3\.0\.0-alpha\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @alwith/module-drive 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @alwith/module-drive 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @alwith/module-drive 可以商用吗？

@alwith/module-drive 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @alwith/module-drive 的下载量有多少？

根据 npm 官方下载统计，@alwith/module-drive 在 2026/10/06 – 2026/11/04 这 30 天内被下载 2,880 次，日均约 96 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @alwith/module-drive 还在维护吗？

最新版本 0\.6\.2 发布于 2026/11/05（2 天前）；至今共发布 15 个版本，其中过去 12 个月发布了 15 个；首次发布于 2026/10/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。