# @hasna/trash 中文文档

规范地址：https://npmcn.com/package/%40hasna/trash/

版本：0\.3\.5
npm 元数据更新时间：2026-11-03T11:41:29.697Z
中文译文更新时间：2026-11-17T11:45:06.472Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40hasna/trash
原文对照：https://npmcn.com/package/%40hasna/trash/?lang=original
项目主页：https://github.com/hasna/apps/tree/main/apps/trash#readme
源码仓库：https://github.com/hasna/apps

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

- 包体积（解压后）：6.9 MB，224 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- 首次发布：2026-09-11T11:11:09.114Z
- 最新版本发布：2026-11-03T11:41:29.528Z
- 近 30 天下载量：32522（2026-10-18 至 2026-11-16，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

代理人的可撤消删除 - 删除垃圾仓库中的地块, 同步到云, 过期于选中的保留

## 安装

```sh
npm install @hasna/trash
```

也可以使用：`pnpm add @hasna/trash`、`yarn add @hasna/trash`、`bun add @hasna/trash`

## README

# @ hasna/ 废物

代理人不可撤销删除 。 主机CLI、MCP和SDK的使用 `https://api.hasna.com/trash/v1`: PostgreSQL拥有元数据;已版本的S3存储已验证的回收胶囊. 一个站只在当地保存未完成的文件系统操作. 缺失的证书永远不会使本地元数据回落 .

## 代理工作流程

```sh
trash setup
trash doctor
trash put ./obsolete-folder
trash put /absolute/path/to/large-item --low-space
trash list --limit 20 --station station06 --path obsolete
trash info ENTRY_ID
trash restore ENTRY_ID
trash hold ENTRY_ID
trash retention ENTRY_ID --days 180
trash backup ENTRY_ID
trash pending
trash release
```

默认输出为压缩 JSON 。 除非有要求,列表最多包含20行,上限为100行,并有 `nextCursor`通过它使用 `--cursor`。列表从不返回文件内容或签名的传输 URL. `info` 获取完整的元数据记录。 过滤器包括站,代理,文字路径文本,类型,状态,备份状态和用户持有. 恢复和过期的记录需要一个明确的状态过滤器.

`trash guard -rf PATH` 接受壳钩的rm语法,并使用低空捕捉. 强制不授权未抓取删除. `trash guard --plan 'rm -rf ./build'` 显示不认证或文件系统更改的重写。 出站代码:0完成,1个使用/API失败,2个删除被拒绝.

脚本必须引用绝对路径( S)`~/.bun/bin/trash`)或将本目录先放入PATH上. 马科斯船 `/usr/bin/trash`,一个取出文件操作符而不是动词的查找器;一个非日志外壳可以先解出它,然后脚本 `trash pending` 然后尝试移动一个名为 `pending`。 。 。 . `trash doctor` 报道说,阴影是 `pathShadowing`。 。 。 .

全权证书决定通过 `@hasna/contracts`,包括仅所有者 `~/.hasna/trash/config/credentials`它的API基础是 `https://api.hasna.com/trash`; 客户端附件 `/v1`. 为每个车站提供单独签署的钥匙。 检测用途 `HASNA_TRASH_STATION`, (中文(简体) ), `HASNA_STATION`,tailscale的自有身份,再取主机名. 服务验证检测到的名称与所签名的证书题目相匹配;更改环境标签不能要求另一个站. 在提供或检测到时抓取记录代理名称、操纵和会话.

`trash doctor` 对照检测到的当地站点检查经认证的托管情况,并报告身份和待办业务。 它因未注册或不匹配的站台,无效的本地身份,认证失败或无法获取服务而出站. 它从来不登记一个站台或创建文件系统操作; 使用 `trash setup` 明确登记。 SDK 显示相同的只读检查为 `createTrash().doctor()`。此检查站接入,而不是本地的钩子安装或备份交付. `status` 财务报告和审定财务报表 `doctor` 报告服务器构建为 `serverVersion` 和当地的CLI作为 `clientVersion`,所以部署的服务器和安装的CLI不同,是可见的而不是模棱两可的.

提供操作员确认精确的书面金库版本,同时在激活密钥前保持当前状态. 临时版本的隐形性在15秒的限期内被重审;不匹配的版本,无效的信封或许可拒绝立即失效. 最初的缺失值只允许在检查目的地是否存在并报告没有分阶段版本后发放。 元数据省略了历史版本,而不包含标签,而且可以延后最近写作。 如果在写完之后确认失败, 请保存任务接收, 在再次引用之前核对准确的版本 : 失败的任务或空的阶段版本元数据不能确定没有写入证书 .

## 捕获、恢复和保留

编码代理会议及其历史从未被俘获或删除,包括 不活动会话、存档会话、个人笔录和每个祖先 文件夹。 日期性文件夹或已停止的进程不能使会话成为可支配的 : 特工还需要恢复 每个移除路径都拒绝抓取任何 这些根,一个里面的任何东西, 和包含一个的文件夹—— 在第一次API通话前托管客户端, 以及遗留的本地商店 (单位:千美元)`trash --local put`, (中文(简体) ), `createLocalTrash()`移动前:

-   克劳德代码 : `~/.claude`, (中文(简体) ), `~/.claude.json` 财务报告和审定财务报表 `CLAUDE_CONFIG_DIR`。 。 。 .
-   代码 : `sessions`, (中文(简体) ), `archived_sessions`, (中文(简体) ), `history.jsonl`, (中文(简体) ), `session_index.jsonl` 编辑 `state_N`编号 :`thread_history_N` 数据库 `~/.codex` 财务报告和审定财务报表 `CODEX_HOME`。 。 。 .
-   OpenCode 和 Sumi 代码 : `${XDG_DATA_HOME:-~/.local/share}/<tool>` 财务报告和审定财务报表 `${XDG_STATE_HOME:-~/.local/state}/<tool>`。 。 。 .
-   光标 : `~/.cursor`, (中文(简体) ), `~/Library/Application Support/Cursor` 财务报告和审定财务报表 `${XDG_CONFIG_HOME:-~/.config}/Cursor`。 。 。 .
-   DSH(TUI的绳子): `$DSH_HOME` (默认) `~/.dsh`)),持有TUI 会话日志和后端 `sessions` 商店,遗产 `~/.dsh-tui` 别名 和明确的 `DSH_TUI_SESSION_ROOT`。 。 。 .
-   反重力 : `~/.gemini/antigravity-cli`。 。 。 .
-   线条 : `~/.cline`。 。 。 .
-   列入清单的任何其他特工住所 `HASNA_TRASH_SESSION_ROOTS`,由 平台的路径分隔符( x)`:` 在macOS和Linux上, `;` )),在视窗上.

检查覆盖了同义链接的别名, 在macOS和Windows上, 大小写等同 拼写, 包括当一个中断的抓取已经制作出原始路径后 无. 当中断的抓取恢复时,它适用,所以路径具有 自成为会话历史后,从未删除; 被拒绝的恢复会保留 文档 `operation_interrupted` 编码并带有 `protected_session_history` 代码旁边。 已验证的还原物 路径仍然可用,因为通过回收站恢复已丢失的历史 支持的修补; 恢复完全创建其目的地, 永远不会 覆盖已存在的历史 。 这些根外的兄弟缓存路径是 不受影响.

1.  检查源头时不跟随同音符,并用活塞和活塞来创建私人胶囊.
2.  保留主机元数据,上传仅具有创建条件,并验证整个不可改变对象版本.
3.  确认来源没有改变 。 把它移动到一个私人兄弟中继目录中,并通过同能API操作执行去除.
4.  校正准确的远程版本,然后只删除未更改的捕获成员.

在压力下对磁盘使用 `trash put PATH --low-space`SDK (英语) `createTrash().put(PATH, { lowSpace: true })`,或 MCP 软件 `trash_put` 与 `lowSpace: true`。这读取并散开选定来源,只保留本地的私人清单和交易日记,将正常的回收胶囊直接流到S3,最多为64 KiB。 它避免了额外的本地复制有效载荷大小. 它仍然需要有限度的元数据磁盘空间(最多16个MIB清单加上它的收发和日记),以及经过认证的、可达到的服务。 一个完全完整的文件系统仍然可以拒绝元数据写入;它保存了源,从不会回到永久删除. 多个散列通过和上传时间仍然适用:这减少了磁盘的使用,而不是验证恢复的需要.

低空捕捉不会保留本地有效载荷:在其宿主物体被核实并完成清除之前,其路径上的源是被捕捉的字节的唯一副本. 在那之前,回收站从未移除过,一个失败或中断的投放就这样说:错误带有 `sourceRetained: true` 和消息命名源。 不以任何其他方式去除这种来源(a) `rm` 在警卫外, `find -delete`剧本, `git worktree remove`直至 `trash pending` 不再列出操作。 删除守护器只当主机条目被执行时才计算删除(`trashed`; 任何其他出口2有"没有被删除".

如果在记录出货单之后源变化或消失而不存在被存储的对象,则所记录的字节就不能再被上传了. `put` 财务报告和审定财务报表 `recover` 将此报告为 `payload_never_uploaded` (因为) `source_changed` 或者说 `source_missing`而不是验收失败,以及 `recover` 停止提供无法成功的重试。 当两个同时抓取一条路径的失败者发现源已去掉时,消息会取出胜者相同的条目来代替. 仅在流出时被修改的源是一个可重试中断(`capture_source_unstable`),而非被俘.

服务器保留一个条目 `uploading` 在 PUT 成功后直到验证,所以一个已死亡的 PUT 或一个丢失的 PUT 或验证响应可以留下一个完整的对象 `uploading` 输入. `trash pending` 因此,永远不要将这种失落的记录称为 " 失落的记录 " :随着来源的消失或改变 `condition: "payload_unverified"` 而建议是: `trash recover OPERATION_ID`,它询问服务器,如果对象存在,则执行抓取,否则报告 `payload_never_uploaded`。只有一份完全没有主机条目的记录(无法允许上传) `condition: "payload_never_uploaded"` 内 `pending`。 。 。 . `trash release OPERATION_ID --discard-incomplete` 丢弃这样的只显示记录(它删除了无内容,并保留了共链接目标),而条目是 `uploading` 它首先询问服务器本身:一个被验证的对象被执行,只有商店自己丢失(验证答案 404) `object_not_found`,该条目仍然 `uploading`)让记录去,任何其他答案都保持为: `payload_unverified`: 一个503 `object_store_unavailable` 404 命名缺失的条目或路径, 或一个服务器 `object_not_found`。 。 。 . `recover` 同样的答案一样对待,从不称这样的记录是无法恢复的. 低空记录,其来源仍然匹配 `condition: "payload_not_uploaded"`: 其来源是唯一的副本和 `trash recover OPERATION_ID` 结束了。 这个 `pending` 比较检查类型、模式、大小、同义链接目标和目录列表,不包含; `recover` 正在流出时证明内容 .

通过同一程序恢复低空操作 `pending` 财务报告和审定财务报表 `recover` 工作流程,包括执行或承诺后中断。 当地 `manifest-N.json` 是恢复元数据,而不是内容的独立副本;恢复已核实的远程胶囊的下载。 在恢复低空操作时使用抓取客户端版本或更新:更年长的客户端保留了无法读取的记录而不是猜测. 现有的基于胶囊的捕捉并还原保留了他们之前的行为. 2 GiB有效载荷限制仍然有效.

默认保留是 **被移送365天后**,每个去除时可配置 `trash put PATH --retention 1–365`,或之后与 `trash retention ENTRY_ID --days 1–365`。新的设置拒绝零、分数、超过365的数值和无限保留。 现有的较长或无限期的条目保留其最后期限。 明确搁置和待决,执行或失败的备份请求防止失效;独立持有的备份副本保留自己的监护权.

启用主归档后,现有的服务器维护勾选在承诺删除30天后,每个经核实的版本都符合资格。 标记过滤的 S3 生命周期规则将这些对象移动到 **S3 冰川弹性检索** 包括小于128个基B的胶囊。 该对象保留了它的桶,密钥和不可改变的版本. 保留时间不到30天的条目在炎热时到期。 配置 **无 S3 过期规则**:只有特拉什的持有-意识过期工人删除准确的合格版本并保留其元数据墓碑. 冰川有90天的最低存储电荷,因此更短的配置保留量在过渡后仍可能发生这一最小.

冷的恢复是同步的:

```sh
trash storage ENTRY_ID
trash retrieve ENTRY_ID --request-id UUID --version CURRENT_VERSION --days 1
trash retrieval ENTRY_ID
# After retrieval reports available:
trash restore ENTRY_ID
```

使用相同的请求ID和原始版本来调节丢失的响应. 检索使用Bulk,临时可配置1至7天。 提交的请求不能证明有字节可用 。 状态区分了队列,提交,等待,可用和关注,并带有观察时间戳和安全错误代码. 在单一的S3划界案之前,运行时间一直具有意图,并观察到不确定的结果而不自动重新提交。 留存期满前允许的检索通过其观察到的临时可用窗口保护有效载荷,主动恢复租赁保护下载。 恢复路径重新检查可用性并验证字节、模式和碰撞安全性。 这些主检索命令与备份归档请求分开.

服务器默认允许主归档 。 应用软件包返回的精确切换 `ARCHIVE_RULE` 在部署此版本之前, 在其已有的胶囊前缀上, 订约和收缩版本并恢复对象权限 。 准备状态拒绝缺失/改变的过渡规则或生命周期到期。 明确 `HASNA_TRASH_ARCHIVE_ENABLED=false` 禁用用于有意推出兼容性的主要档案维护。 在要求自动归档之前检查已部署的配置 。 直接去除不相干的现有S3对象不属于此工作流程.

回收调节在维修中断后得以存活。 在初始的72小时观察窗口后,一项未解决的请求继续保护版本 `attention`,而不自动重新提交。 一旦得到保护,就包括提供者的临时提供期限。 在明确开始新的检索意图之前先检查这些请求;仅靠时间就绝不允许删除未解决的检索。 归档标记和检索共享的限定维护批次公平 .

使用 `trash storage ENTRY_ID`, (中文(简体) ), `TrashApi.storage(ENTRY_ID)` 或 MCP 程序 `trash_storage` 检查一个选中的胶囊。 紧凑响应包含其条目ID/版本,提供商,存储类,可用状态,临时检索到期和观察时间. 服务器用一个元数据请求检查所记录的不可移动对象版本,大小和校验和;它不返回桶/键,下载链接或内容. 普通列表页面只保留元数据而不每输入 S3 调用. 可用性是一种观察,所以在允许下载前再次进行恢复检查.

恢复只创建目的地并核实每个文件 。 它拒绝一条被占领的道路。 在另一个车站恢复运行需要 `--to PATH`;原站道从未默默使用. 支持文件,目录,模式和同义链接对象. Capsules目前支持最多2个GiB的内容,10万成员,64个目录级别和一个16个MiB的快递. 扩展属性,ACL,所有权和硬链接关系没有被保留;特殊文件和特权模式比特被拒绝.

超过这些限制之一的俘虏拒绝与 `capture_too_large` 和自清除:限制行走是只读的,在任何中转移动之前运行,所以源头总是没有被触及,没有操作记录或部分中转被留下. 将超大小的树木分割成最多为~1.5 GiB的单位并捕捉出每个;由守卫的流量报告出像明确跳过此指针等碎片.

## 秘密抓获

`trash put <path> --secret` 将捕获标记为具有证书的:保留默认并封顶于 **7天时间** (单位:千美元)`--retention 1–7`, (中文(简体) ), `trash backup` 并拒绝扣留 `secret_backup_refused` 编号 : `secret_hold_refused`,拒绝使用 `secret_retrieve_refused` (一个窗口否则会重新设置保护并保持对象的热度),而冰川档案过渡(第30天)则无法被构建所达到. 该值先属于密件( O)`secrets set --stdin`,则 `--check`); 垃圾窗口仅用于在密件写入失败时恢复本地文件 。 国旗也执行服务器侧面,因此拒绝秘密类条目的延长保留请求(`invalid_secret_retention`); 缩短允许停留的时间. 其他所有捕捉行为都未变.

## 站台设置:从现有计划进行再规划

计划为经过审查的准确结果定下标杆,因此,在管理下移交后,每个站点提供者从现有计划中重新制定计划——具体内容在计划之内,没有 `spec.json` 需要磁盘 :

```bash
trash station plan --from-plan <station>-<provider>/PLAN.json --out <station>-<provider>/NEW_PLAN.json
trash station apply --plan <station>-<provider>/NEW_PLAN.json --expected-plan-digest <digest>
```

所排放的文件是一个新的计划(下一阶段或准备就绪),如同任何计划一样,带有摘要; `--from-plan` 拒绝结合 `--spec` 无效 `apply`编号 :`check`. 准备状态检查通过id验证所需来源及其sha256(变更后所需来源sha256拒绝使用) `removal_instruction_missing`; 改变的全源散列不会阻碍准备状态,也不会通过预期-散列参数。 更新后对每个站点提供者进行重新规划;完整的光谱形状和准备语义记录如下: `docs/station-setup.md` (运入包裹).

被捕获的树可能包含只读目录(0500). 移动一个即使对主人也需要自己的写入位,而空出一个需要在目录上比特而不是文件上比特,因此移动可以使所有者-写入位精确地为重命名而放松并恢复舞台副本上所录入的模式,并清理出在舞台目录上放出一比特后再取出. 胶囊保留了原始模式,所以一个还原模式可以复制.

## 中断

```sh
trash pending
trash release
trash release OPERATION_ID
trash release --dry-run
trash release OPERATION_ID --discard-incomplete
trash recover OPERATION_ID
trash recover CAPTURE_OPERATION_ID --duplicate-of EARLIER_TRASHED_ENTRY_ID
trash recover RESTORE_OPERATION_ID --to /new/empty/destination
```

上传失败使源不受影响 。 上传时更改的源被保存 。 中转后中断或API响应丢失,保留了胶囊,相机源和操作日记,直到恢复与权威状态相协调. 部分恢复得到保留; `recover --to` 可以选择新的目的地。 当重叠的捕捉到同一来源 留下一个已准备好的条目,没有它的原始路径, `recover --duplicate-of` 需要更早的 准确的,仍然可以回收的垃圾 在同一车站。 服务器在清理出本地胶囊之前,既验证不可变的物体,又输入复制件. 一个平地 `recover` 如果承诺成功,则完成清理,但其反应已丢失. `pending` 工作没有证书.

有效载荷的转移以进度为限制,而不是以固定的墙钟为限制:当没有字节为90秒移动时,有效载荷的转移即告失败;否则,有效载荷的传输在预算范围内运行(至少240秒;以及 `payload ÷ 256 KiB/s` 除了这个以外。 故障命名步骤( 上载或下载) , 距离有多远, 运行多久, 以及停止的原因, 并保持可重试.. `recover` 首先要求服务器验证所记录的对象,因此一个已经到达商店的上传(一个被停滞的套接字或丢失的响应)在不重放有效载荷的情况下进行调节. `trash put` 永不重复:它用2号出口拒绝,并保留来源.

只有当主机索引证明它是多余的时,才释放出一个胶囊,并且其他的操作都保留了,原因如下:

-   `trashed`编号 :`restored`:抓取或还原完成,被主机对象被验证并被执行去除,所以只有局部中转的残余. `trash pending` 在下次运行时自动释放这些; `trash release` 很明显.
-   `ready` 来源已经消失(从回收站外取出来源,或在其经核实的上传后中断捕获):行动已经完成——承诺 `trashed` 因此,该条目的保留适用 永无止境 `ready` 保留是关闭的,然后解除. `trash release OPERATION_ID` 选择实施;自动 `pending` 扫取只报.
-   `ready` 而源仍然在: 抓取被中断,没有完成. 胶囊被保存; `trash recover OPERATION_ID` 结束了.
-   `uploading` (上传未核实), `expired`编号 :`deleting` (没有主机对象被留下)和一个完全没有主机条目的操作: 胶囊可能是唯一的复制品,因此它被保存和报告. `trash release OPERATION_ID --discard-incomplete` 新增一个本地证据来证明一个中断的抓取从未被核实:虽然其原始来源仍然在其所记录的路径上存在,但是没有改变,而且还没有上演,但已上演的拷贝重复了它,并且只释放出本地中继器——源和主机条目没有被改变. 旗子是选入的,从来不被假设 `trash pending`,而一个已经消失、改变或已经上演的源头保留了胶囊.

较早的相同可回收删除总是胜过最终决定: 源已丢失的捕获, 服务器的回读匹配到更早的 `trashed` 保留条目 `recover OPERATION_ID --duplicate-of SURVIVOR_ID` 而不是被作为第二个独立条目.

操作目录只属于所有者 。 未知内容和校验和更改被保存备查. 锁从未被偷过 在持有文件系统锁时被杀死的过程会让它可见 : `recover` 财务报告和审定财务报表 `release` 报告记录的持有者,且仅 `--take-abandoned-lock` 澄清一个锁,并且只有在记录证明持有者已消失时(这个主机,pid不再运行,符号不变). 一个活的,无法读取的或其他主机持有者永远不会被接过;在手取出这种锁之前,先停止所有收发器写入器,并亲自验证所录入的主机/PID. 不删除整个集合以清除错误 .

记录也可以在锁入文件留下时消失:一个在最终文件之间被杀死的过程 `unlink` 并且锁的放出会留下残留物. `release ID` 然后报告本地条件——准确的id,它读取的操作目录,没有留待自由运行的中程——而不是主机设置出错,以及 `release ID --take-abandoned-lock` 澄清同一证据下的一个孤儿锁(这项地方决定不需要证明)。 一个无法读取的记录被报告为不可读并保存;其锁没有被取走.

## 备份交接

`trash backup ID` 标记单独的备份工人的条目。 它立即保护了垃圾复制品. 普通车站证书不能声称或完成备份工作。 需要完成 `trash:backup` 证书和收据 确切的文物, 持有备份和核实的恢复。 用户控件仍然独立.

私人备份适配器通过现有的备份应用程序导入. 制作交接器还需要S3版本、对象锁定和经核实的准确存档和清单版本的法律搁置。 备份失败让回收站保护活动. 工人的部署是一个单独的行动先决条件;要求备份不是移交完成的证据。 检查 `backup: "verified"` 和详细收据.

为了在废墟保留期后恢复,通过备份恢复档案,然后恢复档案 `payload.capsule`数字 :

```sh
trash restore-capsule /restored-backup/source/payload.capsule --to /new/destination
```

Capsule回收验证完整的文物并拒绝覆盖. 它不需要原始的 Trash API 证书或更改主机历史 .

## SDK 和 MCP 软件

```ts
import { createTrash, TrashApi } from '@hasna/trash/sdk';
const files = createTrash();
const entry = await files.put('./obsolete-folder', { agent: 'codex', retentionDays: 90 });
const page = await new TrashApi().list({ limit: 20, station: 'station06' });
await files.restore(entry.id);
```

运行 `trash-mcp --stdio` 用于标准的新线限制 MCP。 工具覆盖状态,设置,紧凑列表,细节,存储可用性,放出,还原,持有,保留,备份请求,待操作和恢复. 没有永久删除或原始blob工具被曝光. 变异报告紧凑的元数据以及固定的,被修改的错误.

这个 `hook-trash-guard` 一体化 `@hasna/hooks` 在重写支持的 shell 删除前验证 Hasna 二进制身份 。 弹壳钩只覆盖安装时的本地工具事件. 它不截取任意文件系统 syscalls,应用程序本地删除API,或代理文件编辑工具. 配置代理以使用"垃圾CLI"/"MCP"来进行清除并验证每个被安装的吊钩覆盖;外壳别名不是全系统执行.

`--local` 编号 : `HASNA_TRASH_LOCAL=1` 财务报告和审定财务报表 `createLocalTrash()` 明确选择离线存储。 它的条目没有主机站索引. 遗产配置,扫描,空和清洗命令仅适用于该商店.

## 服务与核查

`trash-serve` 监听 `0.0.0.0:8080` 默认。 配置 `HASNA_TRASH_DATABASE_URL`, (中文(简体) ), `HASNA_TRASH_API_SIGNING_KEY`, (中文(简体) ), `HASNA_TRASH_S3_BUCKET` 财务报告和审定财务报表 `HASNA_TRASH_S3_REGION`. AWS证书使用标准SDK链,包括ECS任务角色. 运行 `trash-serve migrate` 启动前分开。 移民只需要PostgreSQL权限. 公开 `/health`, (中文(简体) ), `/ready`, (中文(简体) ), `/version` 财务报告和审定财务报表 `/openapi.json` 描述服务; `/ready` 检查 PostgreSQL,桶的版本和生命周期限制.

每一次突变都要求 `Idempotency-Key`; 条目动作还需要当前数字 `If-Match` 版本。 重用密钥处理不同峡谷的请求冲突 。 服务处执行认证、租户范围、车站装订、吊销和工人许可.

```sh
bun run verify
TRASH_TEST_DATABASE_URL=postgresql://.../disposable_trash_test bun run test:postgres
```

PostgreSQL门进行真实的元数据/认证/HTTP/保留和CLI/MCP文件系统流,并带有明显标记的固定对象适配器. 这不是现场S3或部署接受。 发布接受单独需要真实对象转移,犬类API认证拒绝,原地站抓取/恢复,备份交接和准确的包/图像收发.

Symlink权限模式被保存在macOS上. Linux 仅支持 0777 symlink模式;包含其他链接模式的胶囊必须在macOS上还原. 在创建目的地之前,拒绝不兼容的恢复.

### 车站配置

`trash station check --station station02` 是一个只读的小型服务检查 : 检测到的身份、犬科认证、预期保留和清单 限制合同. `serviceReady` 不代表特工已经上钩了, MCP服务器或指令.

站台配置工作流程由已安装的钩和指令组成 客户。 通过普通软件包安装已核准的精确软件包版本 先是经理 仅通过 维护发送操作员;该工作流程从不发布或旋转密钥。 若为 经认证的状态说需要车站登记,使用 `trash setup` 当然 初步管理的即时创建仍然是指令行动.

向CLI提供1个站/供应商规格:

```text
trash station plan --spec /absolute/station-spec.json --out /absolute/new-plan.json
trash station apply --plan /absolute/new-plan.json --expected-plan-digest <returned-sha256>
```

规格使用方案 `hasna.trash.station-setup-spec/v1`它约束:

-   `station`, (中文(简体) ), `retentionDays`, (中文(简体) ), `provider` (单位:千美元)`codex`, (中文(简体) ), `claude` 或者说 `sumi`实际数 拥有者 `home`,选定项目 `cwd`,明确 `path`,当地 `providerHome` 财务报告和审定财务报表 `nativeConfig`。 。 。 .
-   `runtime: {path, sha256}` 和安装 `hooks`编号 :`instructions` 每一个 `{root, version, cliSha256}`。这些是精确的行刑针,不是允许的 安装任意可执行文件或替换以进行释放核查.
-   `managed: {targetHome, profileId, requiredSource: {id, sha256}}`,可选 `namespace: "claude" | "sumi"` 用于特定供应商项目清单。 键 实际为该配置文件选择的主机可回收删除指令. `targetHome` 是解析后管理的家庭:通过连锁实现的目标 报告为: `session refresh` 作为其真实的路径, 和光谱必须命名 已解决路径 .
-   `mcp: {configId, version, contentSha256, operationId}` 用于主机回收站 土生土长的 MCP Config. 现有的冲突条目还要求其 `replaceEntrySha256`。代码x还要求 `codex: {executable: {path, sha256}, tempRoot}`。 。 。 .

不属于证书值、任意命令参数或传输覆盖 本规格中。 客户使用正常的业主证书解析器. 本地目标必须位于该站的实际主人家中.

计划只揭示下一个需要的阶段:管理指令、钩子 注册、代码x信托、MCP注册或准备就绪。 应用它执行一个 保护所有者操作和返回 `replan_required`。在 下一个阶段 当多个所有者时, 每一个本地文件前身都会保持当前状态 触摸同一个文件。 计划产出文件是专有的、私人审查文物; 拥有应用程序者保留其权威来源和业务期刊. MCP规划可能编写私有指令操作元数据,但留下 本地配置不变.

在失败后保留原计划及任何返回的所有人操作ID. 在诉讼前通过该所有人解决不确定的结果;不产生 不同的操作只是为了掩盖失败 配置、认证、, 源漂移和不可用本地界面失败关闭 。 未管理提示 文件需要明确的指令,而不是自动覆盖.

一旦一个准备好的计划被记录下来,小的启动子集是:

```text
trash station check --plan /absolute/ready-plan.json
```

它检查犬科服务准入 固定的消费者 核实 守护, 当前管理指令和记录的本地 MCP 配置 . 它不安装,应用,准备MCP日记,捕获或还原文件. 改变配置需要新的计划. 对于新的克劳德准备计划,配置意味着用户和项目MCP定义, MCP 启用/ 失效选择、 信任和工具发布字段。 本地计数器 和缓存可更改而不取消此只读检查。 每个配置 写仍然需要精确的完整文件前身; 保留较旧的已准备好的计划 他们的原始完整档案检查 直到明确被新计划取代. 其产出保留 `mcpExecutionVerified: false` 财务报告和审定财务报表 `nativeAdoptionVerified: false`: 单独证明 新鲜的自带装入预定指令和MCP工具,实际上 截取一次性授权清除。 仅仅写入配置文件 没有证明。 将此项检查连接到支持的启动事件 也与人工引用无关.

SDK的出口 `planStationSetup`, (中文(简体) ), `applyStationSetup`, (中文(简体) ), `checkStationSetup`, (中文(简体) ), `parseStationSetupSpec` 及其分类规格/计划合同.

### 已挂载备份归档检索

`trash storage ID` 检查热的垃圾舱。 被扣押的备份档案有单独的寿命,在胶囊过期后仍可恢复。 已配置的备份工人拥有其桶,对象版本和供应商证书.

使用 `trash backup-inspect ID --version VERSION --request-id UUID` ,以便排队完成精确版本元数据. `trash backup-storage ID` 返回压缩缓存结果及其 `checkedAt` 时间; 它不执行新提供者的读取.

冷取是明确的: `trash backup-retrieve ID --version VERSION --request-id UUID --days 2 --tier Bulk --confirm`。选择批量或标准,以及1-7天;供应商收费。 在丢失的 API 响应后保留同样的请求UUID,版本和选项. 主机请求是队列收据,而不是可用字节的证明. 现有的辅助工作者报告 `queued`, (中文(简体) ), `running`, (中文(简体) ), `waiting`, (中文(简体) ), `complete` 或者说 `attention`,加上提供者的实际 `archived`, (中文(简体) ), `restoring` 或者说 `available` 观察和临时拷贝过期。 可用性不能建立经核实的文件系统还原 .

中断后, `trash backup-refresh ID --version VERSION --request-id ORIGINAL_UUID` 队列对原始意图的观察。 恢复的工作只能检查被保存的提供者请求;缺少或不确定的记录需要调节,并且绝不授权再次提交. 72小时后自动观测停止. 刷新保留原有的意图和尝试;它不会重设最后期限或解除任何搁置。 在完成的临时副本到期后,需要提出新的明确请求.

SDK曝光后 `TrashApi.archive/requestArchive/refreshArchive`; MCP 显示 `trash_backup_storage`, (中文(简体) ), `trash_backup_inspect`, (中文(简体) ), `trash_backup_retrieve` 财务报告和审定财务报表 `trash_backup_refresh`劳动者 `archive/claim`, (中文(简体) ), `archive/complete` 财务报告和审定财务报表 `archive/fail` 路径需要单独的 `trash:backup` 范围与活地租赁。 车站客户端从未收到桶道或AWS证书.

## 常见问题

### @hasna/trash 是什么？

代理人的可撤消删除 - 删除垃圾仓库中的地块, 同步到云, 过期于选中的保留

### 如何安装 @hasna/trash？

在项目目录运行 npm install @hasna/trash，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 trash、trash-mcp、trash-serve，可以用 npx trash 直接运行。

### @hasna/trash 支持 TypeScript 吗？

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

### @hasna/trash 支持 ESM 还是 CommonJS？

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

### @hasna/trash 可以商用吗？

@hasna/trash 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @hasna/trash 的下载量有多少？

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

### @hasna/trash 还在维护吗？

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

