# @coda-console/resource-manager 中文文档

规范地址：https://npmcn.com/package/%40coda-console/resource-manager/

版本：0\.8\.1
npm 元数据更新时间：2026-11-09T10:55:11.759Z
中文译文更新时间：2026-11-10T09:35:57.159Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40coda-console/resource-manager
原文对照：https://npmcn.com/package/%40coda-console/resource-manager/?lang=original
项目主页：https://github.com/sealiu1997/coda_plugins_resource_manager#readme
源码仓库：https://github.com/sealiu1997/coda_plugins_resource_manager

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

- 包体积（解压后）：486 kB，51 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2026-11-04T11:53:42.085Z
- 最新版本发布：2026-11-09T10:55:11.303Z
- 近 30 天下载量：1798（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

会话旁的只读文件浏览器：浏览会话工作目录，预览文本和图片，把路径交给对话。

## 安装

```sh
npm install @coda-console/resource-manager
```

也可以使用：`pnpm add @coda-console/resource-manager`、`yarn add @coda-console/resource-manager`、`bun add @coda-console/resource-manager`

## README

# 资源管理器

Coda 插件：会话旁的文件浏览器。浏览这个会话的工作目录，读文本和图片，把路径交给对话。只读。

-   **Mac**：在会话侧栏里，和对话并排。
-   **iPhone**：在会话右上角菜单里打开，点文件在资源页里切到预览，系统返回（左上「‹」、左边缘侧滑）回到打开它的那一层。iPad 和 iPhone Duo 用同一套界面，没有单独适配。

## 功能

-   两种视图：**列表**（目录树，按需展开，超大目录分页显示）和**图标**（一次看一层，每个条目是类型图标加名字，名字最多两行，`package.json` 这样的名字优先在扩展名前折行）。在「更多」菜单（Mac）或「⋯」菜单（iPhone）的「显示」›「视图」里切换，全局一份，两种视图各自保留滚动位置。
-   **Mac 照 Finder**：**按下**就选中（不等松开），**双击**打开——文件在侧栏里切到预览，文件夹在列表里展开或收起、在图标视图里进入；单击展开箭头只展开，选中不变；按下空白取消选中；右键和按住 Control 的左键不改选中；右键菜单第一项是「打开」（文件夹在列表里写「展开」「收起」），不能打开的条目没有。**iPhone** 轻点就打开（文件夹展开或进入，文件在页内切到预览，不另开页面）。
-   **按键的质感**（`0.7.2`）：两端按下就有底色反馈（页面自己加状态，不靠 `:active`；快点一下也看得到，滑动时不闪；菜单开着时点外面那一下只关菜单），Mac 的按钮是箭头光标；菜单有阴影，iPhone 的菜单出现时有淡入加缩放；iPhone 打开文件、属性页和返回（含侧滑）是滑动过渡，图标视图进出目录是淡入。系统打开「减弱动态效果」后所有动画和过渡都不做，按下反馈照常。没有触感（契约没有这个接口）。
-   图标视图回上一层：iPhone 用系统的返回，Mac 点头部最左边的返回键或按 ⌘↑，退回的那一层里选中刚才进去的文件夹。**没有预览面板**：只有一个侧栏，也没有面包屑。
-   **Mac 的键盘**：点一下目录树或图标视图让它拿到焦点（Tab 也能进来），↑ ↓ 移动选中（图标视图按行列走），列表里 → 展开、← 收起或选中所在的文件夹，图标视图里 ← → 选左右的条目；⌘↓ 同双击（打开、展开、进入）；⌘↑ 在图标视图里回上一层，在预览里返回目录树或图标视图；⌘F 聚焦搜索框。搜索框里 ↓ 进结果，Esc 清空；结果里 Esc 回搜索框。不做多选、按字母跳转，Return 和空格也没绑定。读屏的 `aria-activedescendant` 没做（见 `docs/backlog.md`）。
-   文本预览（带行号，可跨行选中复制，最多读 1 MiB）和图片预览（PNG、JPEG、GIF、WebP、SVG，最多 8 MiB）。
-   代码按语言上色：三十多种常见语言，只按文件名和扩展名认，不猜内容，深浅各一套配色；认不出的显示纯文本。超过 128 KiB 的文件不上色，说明区注明「不高亮」。用的是近似的语法规则，不是语法检查，个别文件会认错（如 `.h` 一律按 C++，`.m` 一律按 Objective-C），不保证完整支持。
-   Agent 一轮结束后，已展开的目录和正在看的文件自动更新。
-   每行带修改日期和大小：Mac 在名字右边（按日期排序时显示日期，否则显示大小，侧栏很窄时隐藏），iPhone 在名字下面一行。右键或长按的菜单里有大小和完整修改时间。文件夹不显示大小（列表和菜单都没有），只有修改日期。
-   可以按名称、种类、日期、大小排序，在「更多」菜单（Mac）或「⋯」菜单（iPhone）的「显示」›「排序」里选，当前项有对勾。两种视图用同一个排序。每种排序的方向固定：名称、种类升序，日期、大小降序（最新、最大在前），没有升降序切换。超过 2 万条的目录，日期和大小排序不可用，退回按名称并提示。排序全局一份，换了排序滚动位置回到顶部，选当前项什么都不做。
-   **文件名搜索**（`0.8.0`）：目录树和图标视图顶上常驻一个搜索框，Mac 按 ⌘F 聚焦它（选中里面的字）。有字时列表换成结果，清空（Esc 或清除按钮）回到原来的浏览，展开、滚动、选中都还在。搜整个工作目录（后台逐层走，先浅后深），只比**名字**，不比路径（带斜杠的词找不到）：不分大小写、包含就算，中文和分解形式的字（如 `é` 的两种写法）都能找到。始终不进 `.git`、`node_modules`（它们自己能作为结果），隐藏文件跟「显示隐藏文件」开关，不跟着链接进目录，不读 `.gitignore`。最多 500 条，最多看 20 万项或 5 秒，到了就停并注明「没搜完」，只显示已找到的；每次重新走树，没有索引。结果按「名字以搜索词开头的在前、浅的在前、再按名称」排，不跟「显示」菜单的排序走。每行是图标、名字（匹配的部分加粗）、所在目录（Mac 在右边，iPhone 在第二行）。Mac 单击选中、双击或 ⌘↓ 打开，↑ ↓ 移动；iPhone 轻点打开；右键或长按有「打开」「添加到聊天」「复制路径」「在目录中显示」「属性」。「在目录中显示」逐级展开（图标视图是进入它所在的目录）并把它选中、滚到中间；这期间你点、滚、按键、打开东西就停下，不会和你抢。结果里打开文件夹也是先定位再展开（或进入）它。刷新、「一轮结束」和切换「显示隐藏文件」会重搜；搜索词和结果不存进会话状态，页面重建后是空的。iPhone 的系统返回：结果里打开的预览或属性页返回到结果，结果本身不算一级。
-   **文件内查找**（`0.8.0`）：只找打开的这个文本文件。Mac 在侧栏预览或独立窗口里按 ⌘F，iPhone 在预览头部「⋯」菜单里点「查找」，预览头部下面出现查找条：输入框、「3/17」、上一个、下一个、完成。不分大小写，高亮全部匹配，当前这一处颜色更深并滚到可见区；回车或 ⌘G 下一个，Shift+回车或 ⇧⌘G 上一个（首尾循环）；Esc 或「完成」关闭。最多标 10000 处，超过写「10000+」，导航只在前 10000 处里走。图片、二进制、读取中、读不到的文件没有查找（⌘F 不拦，菜单里没有这一项）。文件内容变了（刷新、Agent 一轮结束）时查找词和查找条留着、重新找，当前这一处取离原来最近的；打开别的文件、换了根目录、关预览，查找条一并关闭。高亮用浏览器的 Custom Highlight API，不支持的环境只计数、上一个下一个和滚动，不标颜色。有长行的文件（和代码上色共用的门槛：有一行超过 5000 字，如压缩过的 JS）不标高亮，只计数、上一个下一个和滚动：长行里注册高亮会让浏览器同步重画整行，页面会卡死（实测 50 KiB 单行超过 20 秒）。当前这一处文字用正文色，不显示代码着色。
-   **worktree 会话的标题**（`0.8.1`）：Coda 的 worktree 目录以一串 UUID 命名，只看目录名认不出项目。会话的工作目录是 worktree 时，根目录标题（Mac 目录树上方、iPhone 顶部工具条、图标视图头部）写成「项目名 worktree-编号」，如 `ActaView worktree-c037`：项目名是 Coda 里这个会话所属项目的名字（粗体；默认就是原仓库的文件夹名，在 Coda 里改过名字时显示改后的），后缀用常规字重、浅灰、小一号；编号是目录名（UUID）的前 4 位，目录名不是 UUID 时取整个目录名。放不下时依次：后缀缩成 `wt-编号`（完整写法超过可用宽度的 90% 就缩，不贴边），再把项目名从中间省略（至少留 2 个字，`wt-编号` 不动），最后整段从尾部省略；拖侧栏、转屏时重算。Mac 目录树的标题比以前大一号（普通文件夹名也是）；悬停标题显示完整路径，属性页的名称和路径不变；iPhone 的系统返回里是纯文字的完整写法。项目名从 Coda 的项目列表取（会话详情里的项目 id，加上 `agents` 回答里的项目列表，这两样都不是文档写明的接口，集中在 `lib/root.mjs` 一处；列表缓存一分钟，查不到 id 时重取），不读 git 元数据，也不读工作目录之外的任何文件；取不到、或者会话的工作目录不是 worktree 时，照旧显示文件夹名。
-   切换会话时换成新会话的内容，切回来恢复展开状态和滚动位置。
-   右键（Mac）或长按（iPhone）一行：添加到聊天、复制相对路径、复制绝对路径、属性。「添加到聊天」把相对路径接在输入框已有文字后面；指向工作目录外或已失效的链接、不能打开的条目没有这一项。成功时底部提示「已添加到输入框」，约 2 秒消失；写不进去时改为复制，提示「没能写入输入框，已复制」；剪贴板也写不进去时提示「没能写入，也没能复制」。
-   **选中文字右键（只有 Mac）**：在文件预览（侧栏和独立窗口）里选中文字后右键，有「添加到聊天（内容）」「添加到聊天（位置）」「复制」。位置是 `src/app.ts:12-18`，只选一行时是 `src/app.ts:12`，只精确到行。选中的内容太长放不进一条消息时直接复制，提示「选中内容太长，已复制」。iPhone 用系统自带的选区菜单，不加这一项。
-   属性页：行菜单里选「属性」，在当前页里打开一层，用系统的返回退出。显示种类、大小、链接到、位置、完整路径、修改和创建时间、权限；文件夹的大小在打开后统计，不跟随链接，最多 20 万项或 5 秒，超出时显示下限（如「超过 3.2 GiB（已统计 20 万项）」），一轮结束后已有的结果标「上次统计」，可以重新统计。
-   **写入输入框用的是 Coda 没有公开的接口**，以后可能失效或改变；失效时「添加到聊天」会改为复制路径或文字。**已知风险**：输入框里的附件还在上传时添加，上传完成后，这段时间里打的字和那个附件可能消失；刚打完字的一瞬间添加，也可能丢掉这几个字。
-   Mac：把文件拖到输入框也行；预览可以开到独立窗口；工具栏只有一个「更多」按钮，按下弹出菜单：刷新、显示隐藏文件、「显示」›。鼠标移到「显示」或点它，在菜单左边弹出二级菜单（视图和排序）；侧栏太窄放不下时，在菜单里切到下一层，顶上一行「返回」。侧栏预览头部最左边的「返回」回到目录树或图标视图。
-   iPhone：长按出同样的菜单；目录树页（或图标视图）右上角「⋯」里有刷新、显示隐藏文件和「显示」，点「显示」在菜单里切到下一层（视图和排序），顶上一行「返回」；预览时只有一行标题（预览头部），「⋯」在头部右边，里面只有刷新和「复制路径」。
-   默认隐藏 `.git`、`.DS_Store`，Mac 在工具栏的「更多」菜单里、iPhone 在目录树页右上角的「⋯」里可切换显示全部。

只能读这个会话的工作目录。指向工作目录之外的符号链接只显示，不能打开。

## 安装

在 Coda 的「设置 › 插件 › 商店」里找到「资源管理器」安装；也可以用「从 npm 添加…」填 `@coda-console/resource-manager`。

也可以在「设置 › 插件 › 从仓库添加…」里填 `sealiu1997/coda_plugins_resource_manager`，版本留空即跟随默认分支。

装好后，在会话侧栏的标签里打开「资源管理器」。

## 开发

不需要安装依赖，也没有构建步骤；第三方代码只有 `view/vendor/highlight/` 下原样复制的 highlight.js（升级方法见三期设计第 15.2 节）。Node 由 Coda 提供（`$CODA_NODE`）。

```sh
# 测试，也可以用 npm test。Node 24 上不能写成 node --test test/
"$CODA_NODE" --test test/*.test.mjs

# 不进 Coda，用假的 window.coda 在浏览器里看真实页面
"$CODA_NODE" test/harness/server.mjs <会话A的目录> [会话B的目录] [端口]

# 真实布局的断言和截图：无头 Chrome 打开 Mac 侧栏、iPhone 竖屏和横屏的目录树、图标视图与资源页里的预览（浅色、深色），
# 量行高、工具条、菜单和二级菜单的位置和尺寸，图标视图的单元格和滚动。自己起服务和临时目录，用完删掉；截图在系统临时目录里，路径在最后打印。
# 失败时退出码非 0。Chrome 不在默认位置时把路径作参数传入
"$CODA_NODE" test/harness/layout.mjs [Chrome 的路径]

# 契约检查，<提交> 用 coda-console/coda-plugins 的提交号
npx --yes github:coda-console/coda-plugins#<提交> . --manifest
```

在这台机器上试改时，「从仓库添加…」填本机仓库的绝对路径，版本填分支名。Coda 只读取已提交的内容，未提交的改动看不到。

`test/harness/` 用的是普通浏览器，不是 Coda 客户端里的 WebKit，改完还要在客户端里看一遍。

## 文档

-   [一期设计](https://npmcn.com/package/%40coda-console/resource-manager/docs/design/phase-1.md)：消息协议、路径校验和页面规则。
-   [二期设计](https://npmcn.com/package/%40coda-console/resource-manager/docs/design/phase-2.md)：iPhone 适配和独立文件视图。
-   [三期设计](https://npmcn.com/package/%40coda-console/resource-manager/docs/design/phase-3.md)：文件信息和排序、右键操作和类型图标、图标视图。
-   [可选需求清单](https://npmcn.com/package/%40coda-console/resource-manager/docs/backlog.md)：之后可能做的需求。
-   [评审准则](https://npmcn.com/package/%40coda-console/resource-manager/.coda/review.md)。

## 发布

1.  改 `package.json` 的 `version`，合并到 `main`。
2.  运行 `gh workflow run publish.yml --ref main`。工作流先看这个版本是不是已在 npm 上，已有就跳过。

工作流用 npm 可信发布，不需要令牌。只有手动运行才会发布，合并到 `main` 不会自动发布。

发布后 npm 可能要约 10 分钟才公开，工作流最多等 15 分钟确认。超时会显示失败，但摘要写着「发布已接受，公开确认超时，不要重发」：包已经发出，不要重跑工作流，先到 npm 上查这个版本。

首次发布要先有包，可信发布才能配置：在本机 `npm login` 后手动运行 `npm publish --access public`，再到 npm 上 `@coda-console/resource-manager` 的设置里配置可信发布，仓库填 `sealiu1997/coda_plugins_resource_manager`，流程文件填 `publish.yml`，并勾选允许 `npm publish`（Allow npm publish）。新配置默认只允许 `npm stage publish`，不勾选的话工作流的发布步骤会被拒绝。之后就按上面的步骤走。

## 许可

MIT。

第三方：`view/vendor/highlight/` 里是 [highlight.js](https://highlightjs.org/) 11.12.0 的浏览器构建，BSD-3-Clause 许可，版权声明和许可全文在同目录的 `LICENSE`，文件原样复制，没有修改。

## 常见问题

### @coda-console/resource-manager 是什么？

会话旁的只读文件浏览器：浏览会话工作目录，预览文本和图片，把路径交给对话。

### 如何安装 @coda-console/resource-manager？

在项目目录运行 npm install @coda-console/resource-manager，或使用 pnpm add / yarn add / bun add。

### @coda-console/resource-manager 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/coda-console\_\_resource-manager 是否存在。

### @coda-console/resource-manager 支持 ESM 还是 CommonJS？

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

### @coda-console/resource-manager 可以商用吗？

@coda-console/resource-manager 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @coda-console/resource-manager 的下载量有多少？

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

### @coda-console/resource-manager 还在维护吗？

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