# @atcute/password-session 中文文档

规范地址：https://npmcn.com/package/%40atcute/password-session/

版本：1\.0\.2
npm 元数据更新时间：2026-07-16T00:10:26.961Z
中文译文更新时间：2026-11-09T20:25:40.384Z
软件包许可：0BSD

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

原始 npm 页面：https://www.npmjs.com/package/%40atcute/password-session
原文对照：https://npmcn.com/package/%40atcute/password-session/?lang=original
源码仓库：https://github.com/mary-ext/atcute

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

- 包体积（解压后）：25.2 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：3 个
- peer 依赖：@atcute/identity ^2\.0\.0，@atcute/lexicons ^2\.0\.0
- 首次发布：2026-02-24T09:29:07.704Z
- 最新版本发布：2026-07-16T00:10:26.758Z
- 近 30 天下载量：1748（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

aT 协议基于密码的会话管理

## 安装

```sh
npm install @atcute/password-session
```

也可以使用：`pnpm add @atcute/password-session`、`yarn add @atcute/password-session`、`bun add @atcute/password-session`

## README

# @ atcute/ password- session

基于密码的AT 协议服务的会话管理. 管理访问/更新代号生命周期, 401自动刷新,通过回调持续会话.

对于基于浏览器的应用程序,选择基于 OAuth 的认证。 当使用密码认证时,请使用应用程序 密码而不是主账户证书.

```sh
npm install @atcute/password-session @atcute/client @atcute/bluesky
```

## 使用量

### 登录

```ts
import { Client, ok } from '@atcute/client';
import { PasswordSession } from '@atcute/password-session';

import type {} from '@atcute/bluesky';

const session = await PasswordSession.login(
    { service: 'https://bsky.social', identifier: 'you.bsky.social', password: 'your-app-password' },
    {
        onUpdate(data) {
            // called on login and token refresh — persist the session
            localStorage.setItem('session', JSON.stringify(data));
        },
        onDelete(data) {
            // called on logout or session invalidation — clean up
            localStorage.removeItem('session');
        },
    },
);

const rpc = new Client({ handler: session });

const data = await ok(rpc.get('com.atproto.server.getSession'));
console.log(data.did);
```

### URL 简称

对于 bots 和脚本,请使用 URL 的快手 `await using` 自动登录 :

```ts
await using session = await PasswordSession.login('https://handle:app-pass@bsky.social');
const rpc = new Client({ handler: session });
```

### 续会

在不重新进入全权证书的情况下继续开会:

```ts
const saved = localStorage.getItem('session');
if (saved) {
    const session = await PasswordSession.resume(JSON.parse(saved), {
        onUpdate(data) {
            localStorage.setItem('session', JSON.stringify(data));
        },
        onDelete(data) {
            localStorage.removeItem('session');
        },
    });
    const rpc = new Client({ handler: session });
}
```

### 带有证书倒置的缓存会话

对于既存有证书又存有缓存会话的bot, `login()` 能够尝试缓存会话 首先返回到新认证 :

```ts
const session = await PasswordSession.login('https://handle:app-pass@bsky.social', {
    session: loadFromDisk(),
    onUpdate(data) {
        saveToDisk(data);
    },
});
```

### 懒惰的建筑

如果您不需要前置验证, 请直接构造 。 符号在 401 上懒散地刷新 :

```ts
const session = new PasswordSession(savedData, { onUpdate, onDelete });
const rpc = new Client({ handler: session });
```

### 清理

删除无效会话服务器侧, 不恢复 :

```ts
await PasswordSession.delete(savedData);
```

## 调用

| 回调 | 何时 | 会话状态 |
| --- | --- | --- |
| `onUpdate` | 登录成功, 令牌刷新成功 | 活动( 更新) |
| `onUpdateFailure` | 符号刷新暂时失败( 网络) | 活动(保留) |
| `onDelete` | 登录成功, 会话无效 | 已销毁 |
| `onDeleteFailure` | 暂时停用( 网络) | 活动(保留) |

所有回调收到 `this: PasswordSession` 上下文,不能抛出.

## 常见问题

### @atcute/password-session 是什么？

aT 协议基于密码的会话管理

### 如何安装 @atcute/password-session？

在项目目录运行 npm install @atcute/password-session，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@atcute/identity（^2\.0\.0）、@atcute/lexicons（^2\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @atcute/password-session 支持 TypeScript 吗？

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

### @atcute/password-session 支持 ESM 还是 CommonJS？

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

### @atcute/password-session 可以商用吗？

@atcute/password-session 使用 0BSD 许可。几乎没有限制：可自由使用、修改和分发，连保留版权声明也不要求。以上为概括，不构成法律意见，请以许可原文为准。

### @atcute/password-session 的下载量有多少？

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

### @atcute/password-session 还在维护吗？

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