前端【免费下载链接】WebClientsMonorepo hosting the proton web clients项目地址https://gitcode.com/gh_mirrors/we/WebClients点击查看免费下载本篇技术指南围绕 Proton Pass 为 AI Agent 场景准备的 agent-instructions.md 指令文档展开系统讲解如何通过pass-cli命令行工具完成个人访问令牌PAT认证、会话隔离与监控、vault 与 item 的发现与安全读取。读完本文你将掌握一套可直接交付给任何 LLM Agent 的完整操作协议从安装校验、PAT 登录、强制访问原因上报到pass://URI 直寻、单字段提取、连接健康检查与自动恢复流程并理解这一机制在 WebClients 仓库Proton Pass Web 客户端中的完整源码实现链路。这份 Agent 指令在项目中的角色agent-instructions.md并非孤立存在的说明文档它是 Proton Pass Web 客户端AI Agent 集成功能的运行时内容源。从源码结构可以梳理出以下加载链路前端组件 TokenRevealModal.tsx 中的AgentInstructions组件在用户创建 Agent 令牌后发起请求获取指令模板并将占位符{{access_token}}替换为真实令牌值后展示给用户复制。请求入口是 access-token.requests.ts 中的fetchAgentInstructions()它通过fetch(AGENT_INSTRUCTIONS_URL)拉取 Markdown 文本响应非 2xx 时抛错。指令内容地址由 constants.runtime.ts 中的AGENT_INSTRUCTIONS_URL决定在扩展EXTENSION_BUILD或桌面DESKTOP_BUILD构建下指向远程 CDN 地址proton.me/download/pass/agent-data/agent-instructions.md而在普通 Web 构建下直接指向本地仓库内的/assets/agent-instructions.md注释标注为 HOTFIX CSP即规避内容安全策略限制的快捷修复。请求经由 Redux Saga 编排见 access-token.sagas.ts 的agentInstructionsSaga并在 access-token.ts 中通过dataRequest(UNIX_HOUR)声明一小时级的成功缓存避免重复拉取。因此本文讲解的每一条命令都是 Proton Pass 官方 Agent 接入协议的一部分下文将逐节展开。一、环境准备安装校验与版本确认在将 Agent 接入 Proton Pass 之前第一步是确认目标机器上已安装pass-cli。标准做法是运行版本检查命令pass-cli --version命令成功输出版本号说明 CLI 已就绪可直接进入会话阶段。若提示命令不存在如command not found则需要先按你所在平台的官方安装指引完成安装macOS、Linux、Windows 均有对应安装包安装完成后重新执行pass-cli --version校验。需要说明pass-cli是独立于 WebClients 仓库发布的命令行程序本仓库仅承载配套的指令文档与 Web 端集成逻辑两者通过环境变量与 PAT 令牌完成对接。二、会话管理隔离会话目录与登录状态检查pass-cli以会话session为单位管理登录状态。Agent 操作前必须保证存在有效会话检查方式pass-cli info返回退出码0且输出会话信息说明登录态有效。若会话已过期或不存在先执行pass-cli logout清理旧会话。为了不让 Agent 的会话与其他会话相互污染原文档特别要求在登录之前设置独立的会话目录环境变量export PROTON_PASS_SESSION_DIR/tmp/pass-agent-unique-name其中unique-name建议替换为本次任务唯一的标识如任务 ID。这样每次 Agent 任务都拥有隔离的会话存储空间多任务并行或反复登录时互不干扰会话目录被隔离后pass-cli info、登录与后续所有命令都会以该目录为会话上下文。三、PAT 认证通过个人访问令牌登录会话目录就绪后使用随指令一同下发的 Personal Access TokenPAT完成登录。PAT 通过环境变量注入避免令牌出现在命令行历史或进程列表的可读参数中PROTON_PASS_PERSONAL_ACCESS_TOKEN{{access_token}} pass-cli login其中{{access_token}}是模板占位符实际执行时必须替换为真实令牌值。在 Web 客户端中该占位符由 TokenRevealModal.tsx 在拉取模板后通过template.replaceAll(ACCESS_TOKEN_PLACEHOLDER, envVar)替换为完整环境变量值。令牌的完整形态从 access-token.utils.ts 的buildAccessTokenEnvVar可以确认其格式为server-issued-token::urlsafe-base64-no-pad(raw-key)即服务端签发的令牌字符串与 URL 安全 Base64无填充编码的原始密钥以::拼接。该环境变量是一次性的——创建后仅在弹窗中展示一次关闭后客户端不再持有明文见 TokenRevealModal.tsx 的类型注释因此务必在展示时及时保存。登录成功后再次运行pass-cli info确认已以正确账号登录。四、会话监控Agent 执行的强制纪律原文档用 IMPORTANT: Session monitoring 专门强调以下纪律Agent及其使用者必须遵守每次执行任何pass-cli命令前先运行pass-cli info确认仍处于登录状态——这是所有命令的前置校验。若出现认证错误或非零退出码立即用上文 PAT 方式重新认证。长任务执行期间会话可能过期需周期性复查登录态。将 PAT 令牌{{access_token}}保存在安全位置会话过期重登时会用到这是重新认证的必需品。任何命令失败时先完整阅读输出诊断原因重点关注错误信息、退出码与线索认证失败、权限拒绝、非法参数等再决定重试策略避免盲目重试。这套纪律与 Web 端设计相互印证创建 Agent 令牌时界面会明确提示Agent 的每个动作都必须提供原因且每个动作都会被记录在可审查的审计日志中见 CreateTokenModal.tsx。五、验证资源可达性Vault 与 Share 清单登录完成后先验证令牌实际拥有的资源访问范围pass-cli vault list pass-cli share listvault list列出 Agent 可访问的保险库vault。share list列出被授予访问权的保险库及直接条目direct items即未归属到某个 vault、被单独授权的条目。将两个命令的输出回传确认可见的 vault 列表若无法列出需将错误完整反馈以定位问题常见原因包括令牌未勾选对应 vault 的访问授权、令牌已过期等。需要说明的是Web 端创建令牌时仅授予只读访问权限界面文案明确该令牌对你选择的 vault 只有读取权限可以读取条目但不能编辑、不能共享 vault、不能邀请他人后续可调整见 CreateTokenModal.tsxvault 授权集合由shareIds传入创建意图见 access-token.sagas.ts 的createSaga。六、读取条目强制访问原因PROTON_PASS_AGENT_REASON读取条目是 Agent 的核心操作安全设计的关键在于每次读取都必须声明原因。运行pass-cli item view前必须定义环境变量PROTON_PASS_AGENT_REASON其值是对为何要访问该条目/字段的简要描述必填。按 vault 名称与条目标题定位PROTON_PASS_AGENT_REASONBrief description of why this item is being accessed pass-cli item view \ --vault-name Vault Name \ --item-title Item Title使用pass://URI 直接寻址PROTON_PASS_AGENT_REASON... pass-cli item view pass://SHARE_ID/ITEM_ID仅提取单个字段例如只取密码PROTON_PASS_AGENT_REASON... pass-cli item view --vault-name Vault --item-title DB --field password该原因机制在服务端与客户端均有落点审计记录解码后呈现的结构为{ kind: agent-action, reason, vaultName, itemName, folderName }见 access-token.types.ts即每条 Agent 动作审计记录都完整保留了访问原因、vault 名、条目名与文件夹名供用户在 Web 端审计查看。七、需要声明原因的特殊命令以下命令及其子命令同样强制要求携带PROTON_PASS_AGENT_REASON命令说明item view读取条目/字段item create及其子命令如item create login、item create ssh-key等创建条目item update更新条目item trash移入回收站item untrash从回收站恢复vault update更新保险库八、发现 Vault 与条目结构化输出Agent 需要程序化解析结果因此发现类命令统一使用--output jsonpass-cli vault list --output json # 列出 Agent 有访问权的 vault pass-cli share list --output json # 列出被授予访问权的 vault 与直接条目 pass-cli item list --vault-name Name --output json # 列出指定 vault 内的条目 pass-cli item list --output json # 列出所有可访问条目凡是需要程序化解析的输出都建议使用--output json以保证字段结构与类型稳定。九、会话与连接健康检查日常运维中可随时用以下命令体检pass-cli info # 显示当前账号类型与会话详情 pass-cli test # 验证与 Proton Pass API 的连接info关注登录态与账号维度test关注网络链路与 API 可达性两者结合可快速定位问题属于认证层面还是网络/服务层面。十、会话丢失后的自动恢复流程若任何命令因认证错误失败按以下顺序恢复pass-cli logout --force—— 强制清除陈旧会话常规logout报错时的兜底手段重新执行第三步的 PAT 登录命令用pass-cli info验证登录成功重试原始失败命令。--force的作用是在常规退出流程异常时仍能强制结束会话避免残留状态阻塞重新认证。十一、快速参考常用命令速查表以下速查表覆盖 Agent 全生命周期操作建议直接交付给 Agent 使用场景命令认证登录pass-cli login配合PROTON_PASS_PERSONAL_ACCESS_TOKEN环境变量结束会话pass-cli logout强制结束会话pass-cli logout --force常规 logout 报错时使用列出保险库pass-cli vault list --output json列出 vault 内条目pass-cli item list --vault-name NAME --output json读取条目或单字段pass-cli item view --vault-name VAULT --item-title TITLE [--field FIELD]输出本指令pass-cli agent instructions其中pass-cli agent instructions可直接输出当前这份 Agent 使用说明便于 Agent 在任何时候重新加载操作协议。十二、源码级透视安全机制与指令分发闭环将上述协议与仓库源码对照可以看到完整的安全闭环令牌创建即分级Web 端创建令牌时通过 Use for AI agent 开关CreateTokenModal.tsx标记isAgent只有 Agent 令牌才会走强制原因与审计日志路径。授权最小化令牌对 vault 的访问为只读且需显式勾选shareIds过期时间限制在 1 小时至 1 年之间常量MIN_EXPIRATION_MINUTES 60、MAX_EXPIRATION_MINUTES 365 * 24 * 60见 CreateTokenModal.tsx。一次性的环境变量令牌以token::b64url(raw-key)形态仅在弹窗展示一次且原始密钥部分在弹窗关闭后不再留存于客户端。指令按需分发指令 Markdown 在运行时拉取Web 构建下即本文档applications/pass/public/assets/agent-instructions.md服务端令牌值仅在用户端替换占位符CDN/静态资源中不包含任何真实令牌。行为可审计每次 Agent 动作携带的reason会被加密记录Web 端通过 access-token.utils.ts 的decodePatRecord用令牌原始密钥解密后展示形成原因 对象 时间的完整审计轨迹。结语至此一条完整的 Proton Pass Agent 接入链路已经打通pass-cli安装校验 → 隔离会话目录 → PAT 环境变量登录 → 会话监控 → 资源清单验证 → 带原因的条目读取 → 健康检查与自动恢复。这套协议既适合作为 LLM Agent 的系统提示词直接注入也可供开发者据此构建自己的自动化凭据拉取流水线。仓库内 agent-instructions.md 是协议的中文源头配套前端代码TokenRevealModal.tsx、CreateTokenModal.tsx与后端 Sagaaccess-token.sagas.ts则展示了它在实际产品中的完整实现。赞分享前端【免费下载链接】WebClientsMonorepo hosting the proton web clients项目地址https://gitcode.com/gh_mirrors/we/WebClients点击查看免费下载相关推荐douyin-downloader抖音批量下载与去水印从单条链接到主页归档的完整上手指南douyin downloader抖音批量下载与去水印从单条链接到主页归档的完整上手指南 douyin downloader 是一个命令行抖音下载工具给它网页爬虫CLIOpenCompass 代码评测实战基于 HumanEval 与 MBPP 的 pass1 / passk 完整配置指南OpenCompass 代码评测实战基于 HumanEval 与 MBPP 的 pass1 / passk 完整配置指南 导读 本文以 humaneval模型评测人工智能大模型AI 评测Shiori 旧版 API 完整调用指南基于会话认证的书签与标签管理接口实战Shiori 旧版 API 完整调用指南基于会话认证的书签与标签管理接口实战 本指南以 docs/API.md 为核心骨架系统讲解 ShioriGo 语言后端上一篇从InterAccel到Raw Accel鼠标加速技术的进化与革新下一篇Raw Accel vs InterAccel为什么你需要升级到终极鼠标加速解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考