olares-shared

olares-cli 共享规则

在使用运行时技能前，先阅读这份简明入口。它提供活动配置文件模型、平台入口，以及身份验证继续/停止规则——任务确定所属技能后所需的信息。只有当前任务触发详细参考内容时，才加载这些内容。

• 套件地图：各技能负责哪些任务，以及 olares-cli 不在 PATH 中时如何安装。任务尚未分配给某个技能时，请阅读此文；已分配技能的任务无需重复阅读。

阅读答案

每个基于配置文件的命令树都使用相同方式指定机器可读输出：-o json（--json 表示相同请求，仅为兼容旧脚本而保留）。在此模式下失败的动词会通过 stderr 返回 {"error":{"code","message","retryable","action"}}，且 stderr 不包含其他内容，因此可以整体解析。

如果 .error.code 存在，值得据此分支处理；目前，这适用于恢复方式与其他所有故障都不同的情况：auth_no_profile、auth_not_logged_in、auth_token_expired、auth_token_invalidated 和 timeout，以及 Router 从上游报告的任何错误。其他错误都会以 unclassified 返回，完整说明位于 .message 中。因此，请先读取错误代码；如果没有收到预期的代码，应改用错误消息，而不是自行假定其含义。只有在故障提供相关信息时，才会包含 retryable 和 action；缺少这些字段表示未知，而非“否”。

有些命令树还会提供自己的结果文档（Market 的生命周期动词会报告 .status 和 .finalState）；如果有，请以该文档为准。

平台入口

• Olares 平台模型：用户空间存储、uid/gid 1000、受保护的 Home 目录、应用/命名空间网络、系统中间件和 Olares 版本语义。处理涉及这些概念的文件、chart、集群或设置任务时，请阅读此文。
• 应用状态机：生命周期转换、允许的操作、后端超时、串行下载、running 语义和不可靠的进度信息。处理 Market 操作或运行时诊断时，请阅读此文。
• 配置文件与身份验证：登录/导入流程、配置文件状态、令牌存储和刷新行为。仅在处理配置文件或身份验证恢复时阅读此文。

活动配置文件

一个配置文件对应一个 Olares 实例和一个 Olares 身份。每条基于配置文件的命令都会针对当前选定项执行；不支持按命令指定 --profile 覆盖项。

命令	用途
olares-cli profile list	显示配置文件、当前选定项、身份验证状态和缓存的 Olares 版本
olares-cli profile whoami	显示所选配置文件的身份和角色；其他技能据此判断是管理员还是普通用户
olares-cli profile use <name|->	切换选定项；- 返回上一个配置文件
olares-cli profile login	使用密码和可选的 TOTP 进行身份验证
olares-cli profile import	从刷新令牌引导初始化
olares-cli profile remove <name>	移除配置文件及其凭据

使用 olares-cli profile --help 查看标志，并参阅身份验证参考了解登录或恢复方式。

身份验证就绪状态检查

默认继续：

• logged-in、expired 和 pending 均可继续；过期的访问令牌通常会在下一个请求时刷新，而 pending 是由平台签发、但其授权尚未兑换的配置文件。
• 对于 never 和 invalidated，应停止并执行 profile login 或 profile import；但如果 SOURCE 为 platform(<app>)，则表示该配置文件由平台签发给应用程序：此时 login、import 和 remove 均会被拒绝，本地无法创建或撤销该授权，恢复方式是重新安装或修复该应用程序。应用容器内完全没有配置文件时，处理方式也相同——应说明需要修复应用程序，而不是要求登录。
• 对于 unknown 或无法解析的令牌，应运行业务命令，并根据其类型化错误采取相应措施，而不是猜测。

不要对每条命令都预先检查身份验证。CLI 会刷新令牌，并在身份验证被拒绝时重试一次。只有当 CLI 明确说明凭据缺失或已失效，或在持续收到 401/459 后给出登录操作提示时，才停止并要求登录。403 权限拒绝、网络错误或 5xx 都不代表需要登录。绝不要围绕身份验证错误构建重试循环。

安全与升级处理

• 绝不要将密码放入命令参数中。请使用交互式提示或 --password-stdin。
• 绝不要打印访问令牌或刷新令牌。导入时应从机密环境变量或机密管理器读取。
• 执行登录、更换凭据、选择含糊不清的目标，或执行超出用户授权任务范围的操作前，请先询问。
• 在已授权的图表部署/调试任务中，安装、升级、重启、卸载和彻底重新安装都是常规循环步骤；无需为每条命令再次询问。