@numa-tech/numa 1.11.10

package/README.md

@@ -0,0 +1,602 @@
+# Numa
+
+公司内部研发平台的跨平台命令行入口。它同时面向研发人员、CI 和 AI 工具，提供：
+
+- 无需登录即可使用的环境诊断、配置和命令发现；
+- 沿用原项目的 Keycloak Authorization Code + PKCE 登录、离线刷新和本地安全缓存；
+- 需要登录或指定 Keycloak 角色的命令门禁；
+- 登录后自动进入只监听本机的网页控制台，并可随时重新打开；
+- 网页控制台提供身份概览、基础配置、命令发现和非交互命令执行；
+- 包含 Realm 角色、Client 角色和用户组的个人信息页；
+- 使用服务端托管的 Codex 账号启动官方 Codex CLI，客户端不保存 refresh token；
+- 通过领域化 `media` 命令安全调用平台托管的 TTS、视频、资产和素材库服务；
+- 兼容原有 stdio MCP 服务。
+
+## 环境与安装
+
+支持 Windows、macOS 和 Linux，要求 Node.js 20 或更高版本。
+
+默认从公共 npm registry 安装，无需修改用户级 npm 配置。如需显式固定 `@numa-tech` scope：
+
+```bash
+npm config set @numa-tech:registry=https://registry.npmjs.org/
+```
+
+公司私有 registry 仍受支持，可通过 `numa config --set registryUrl=<url>` 或 shortcut
+的 `--registry-url <url>` 显式选择。发布人员使用 `npm run publish:all`，脚本默认先把
+patch 版本加一，再将同一 tarball 依次推送到公共 npm 和公司私有 registry；脚本会跳过
+已存在的同版本。若其中一个仓库失败，使用 `--resume` 以当前版本补推，不会再次修改版本号。
+可用 `NUMA_PUBLIC_NPM_REGISTRY`、`NUMA_PRIVATE_NPM_REGISTRY` 覆盖两个发布目标。旧版配置
+中作为默认值保存的私有 registry 会自动迁移到公共 npm；迁移后显式设置的私有地址会保留。
+
+发布前需要在用户或 CI 的 `.npmrc` 中分别配置两个 registry 的令牌：
+
+```ini
+//registry.npmjs.org/:_authToken=${NPM_PUBLIC_TOKEN}
+//packages.aliyun.com/60371955c4393f5ed3b7baa8/npm/npm-registry/:_authToken=${NPM_PRIVATE_TOKEN}
+```
+
+脚本会在修改版本号之前运行公共 npm 的 `whoami` 和 `@numa-tech` scope 权限检查。使用验证器
+App 的本地交互发布会在公共 npm 推送前隐藏输入 6 位 OTP，并显式传给 `npm publish`；
+使用带 bypass 2FA 权限的 granular token 时直接回车即可。非交互环境可以临时提供
+`NUMA_PUBLIC_NPM_OTP`，更推荐使用 bypass 2FA granular token 或 npm trusted publishing。
+
+首次从本机发布公共包，或公共登录已经过期时，先运行：
+
+```bash
+npm login --registry=https://registry.npmjs.org/
+npm whoami --registry=https://registry.npmjs.org/
+npm org ls numa-tech --registry=https://registry.npmjs.org/
+```
+
+双仓库发布命令：
+
+```bash
+# 仅预览：1.11.9 -> 1.11.10，不修改文件、不访问 registry
+npm run publish:all -- --dry-run
+
+# 默认 patch：自动修改 package.json 和 package-lock.json，然后推送两个仓库
+npm run publish:all
+
+# minor / major / 指定完整版本
+npm run publish:all -- minor
+npm run publish:all -- major
+npm run publish:all -- 2.0.0
+
+# 某个仓库失败后，用当前版本补推；不会再次升级版本
+npm run publish:resume
+
+# 等价写法（注意中间必须有独立的 --）
+npm run publish:all -- --resume
+```
+
+脚本不会自动创建 Git commit 或 tag；发布成功后应提交版本文件。可先运行
+`npm whoami --registry=<registry-url>` 分别检查两个仓库的发布身份。
+
+macOS / Windows 日常启动 Codex 的推荐方式：
+
+```bash
+npx -y --prefer-online --registry=https://registry.npmjs.org/ @numa-tech/numa@latest codex shortcut install
+numa-codex
+numa-codex-app
+```
+
+需要直接使用完整 `numa` 管理命令时，可选全局安装：
+
+```bash
+npm install --global --registry=https://registry.npmjs.org/ @numa-tech/numa
+numa --version
+```
+
+无需安装直接运行：
+
+```bash
+npx -y --prefer-online --registry=https://registry.npmjs.org/ @numa-tech/numa@latest doctor
+```
+
+本地开发：
+
+```bash
+npm install
+npm run check
+npm link
+numa help
+```
+
+## 快速开始
+
+```bash
+# 公开命令，不需要登录
+numa doctor
+numa commands
+
+# 登录；成功后浏览器自动跳转到本地网页控制台
+numa login
+
+# 随时重新打开网页控制台
+numa console
+
+# 终端内配置仍然保留
+numa config
+
+# 查看包含角色信息的个人资料
+numa profile
+
+# 调用研发平台 API
+numa request /api/projects
+```
+
+非交互环境可完全通过参数初始化：
+
+```bash
+numa config \
+  --set output=json \
+  --set locale=zh-CN \
+  --set apiBaseUrl=https://rd.example.internal
+```
+
+## 命令与访问控制
+
+| 命令 | 访问级别 | 说明 |
+| --- | --- | --- |
+| `numa help [command]` | 公开 | 详细帮助、参数和示例 |
+| `numa commands [--json]` | 公开 | AI/脚本可读取的命令目录 |
+| `numa doctor` | 公开 | 检查 Node、平台、配置和登录缓存 |
+| `numa config` | 公开 | 打开配置页或参数化配置 |
+| `numa login` | 公开 | Keycloak PKCE 登录，成功后默认进入网页控制台 |
+| `numa console` | 公开 | 启动只监听本机的网页控制台 |
+| `numa auth status` | 公开 | 查看本地会话状态，不输出令牌 |
+| `numa auth logout` | 公开 | 删除本地登录缓存 |
+| `numa profile` | 需登录 | 当前用户、角色和用户组 |
+| `numa request <path>` | 需登录 | 携带令牌调用平台 API |
+| `numa request <path> --require-role <role...>` | 需角色 | 调用前检查指定角色之一 |
+| `numa admin context` | 需角色 | 要求 `platform-admin` 或 `numa-admin` |
+| `numa media capabilities` | 需登录 | 查询媒体 API、Provider 和版本能力 |
+| `numa media tts submit` | 需登录 | 提交 TTS 异步任务 |
+| `numa media video submit` | 需登录 | 提交视频生成异步任务 |
+| `numa media job inspect` | 需登录 | 查询异步任务状态 |
+| `numa media job resolve` | 需登录 | 按幂等键解析已有任务，避免重复付费提交 |
+| `numa media artifact pull` | 需登录 | 流式下载并校验产物 |
+| `numa media asset upload` | 需登录 | 流式 multipart 上传资产 |
+| `numa media library search/inspect/pull/publish` | 需登录 | 查询、锁定、下载和发布素材 |
+| `numa codex list` | 需登录 | 列出服务端账号元数据，不下载 refresh token |
+| `numa codex upload` | 需登录 | 批量上传 codex-multi-auth 管理的账号池 |
+| `numa codex use` | 需登录 | 选择账号并写入官方 ChatGPT 登录 |
+| `numa codex run` | 需登录 | 使用所选账号启动官方 Codex CLI |
+| `numa codex app` | 需登录 | 使用官方 ChatGPT 登录启动桌面 App |
+| `numa codex shortcut` | 公开 | 安装或删除 macOS/Windows 快捷命令与桌面入口 |
+| `numa codex status` | 公开 | 查看本地选择和官方登录状态 |
+| `numa codex reset` | 公开 | 重置本地选择和登录并清理旧 provider 残留 |
+| `numa serve` | 公开 | 启动兼容 MCP 服务 |
+
+`numa codex list` 的人类可读输出采用账号卡片：不显示账号服务地址和底层 ChatGPT UUID，
+只突出账号名称、当前选择以及短周期/长周期剩余额度。额度柱状图会随终端宽度缩放，
+高、中、低余额分别使用绿、黄、红提示；设置 `NO_COLOR=1` 可关闭颜色，设置
+`NUMA_ASCII=1` 可在不支持 Unicode 的终端使用 ASCII 轨道。`--json` 保留完整账号元数据，
+但同样不会返回账号服务地址。服务端返回的空额度窗口不会显示成“长周期 100%”；只有
+带窗口长度、重置时间或实际用量的窗口才会进入账号卡片。这里的“刷新”是额度窗口重置，
+不是 ChatGPT 订阅续费或订阅到期。服务端确认 refresh token 已失效后，账号卡片会标记
+“凭据已失效”，交互选择器会禁止选中该账号；显式指定该账号或凭据在启动期间失效时，
+CLI 会返回稳定错误码 `codex_account_needs_reauth`，需要管理员重新导入有效登录凭据。
+
+CLI 的本地角色检查用于快速反馈和隐藏无权限入口，不能替代服务端授权。内部平台 API 必须继续在服务端校验访问令牌、资源和角色。
+
+## 配置
+
+网页控制台的“基础配置”和 `numa config` 读写同一份配置。直接运行
+`numa config` 仍会打开终端配置页。当前基础配置包括：
+
+- `locale`：`zh-CN` 或 `en-US`；
+- `output`：`text` 或 `json`；
+- `apiBaseUrl`：内部研发平台 API 根地址，默认
+  `https://apps-gw-prd.mcisaas.com/mci-devops-platform`；
+- `registryUrl`：npm registry，默认公共 npm，也可配置公司私有 registry；
+- `checkUpdates`：是否检查 CLI 更新。
+
+读取或脚本化修改：
+
+```bash
+numa config --show
+numa config --show --json
+numa config --set output=json --set checkUpdates=false
+numa config --reset
+```
+
+配置位置遵循各平台约定：
+
+- Linux/macOS：`${XDG_CONFIG_HOME:-~/.config}/numa/config.json`
+- Windows：`%APPDATA%\numa\config.json`
+- 测试/隔离环境：可通过 `NUMA_CONFIG_DIR` 覆盖
+
+文件采用版本化 JSON 结构，后续可向后兼容地增加配置项。
+
+## 本地网页控制台
+
+`numa login` 完成 Keycloak 登录后，回调页会自动跳转到本机控制台。已有登录状态时可直接运行：
+
+```bash
+numa console
+
+# 只启动服务，不自动打开浏览器
+numa console --no-open
+
+# 登录后不保留网页控制台，适合脚本或 CI
+numa login --no-console --no-config --json
+```
+
+控制台展示当前身份、Realm/Client 角色、ChatGPT 账号、基础配置和机器可读命令目录。
+ChatGPT 账号页先读取 `codex-multi-auth` 的本地账号与额度缓存并立即展示，再使用当前
+Keycloak 会话连接平台补充当前用户可用账号、剩余 limit 和同步状态。平台不可用时页面
+保留本地结果并明确显示“远程同步失败”，不会把 access token 或 refresh token 返回给页面。
+命令执行器使用
+JSON argv 调用同一版 CLI，不经过 shell，并自动要求结构化 `--json` 输出。删除登录缓存、
+重置 Codex 或配置等操作需要显式确认；`serve`、`codex run`、`codex app`、
+`codex auth-agent` 等长驻、交互或会启动其他应用的命令仍应在终端运行。控制台由当前
+`numa` 进程托管，关闭使用时在终端按 `Ctrl+C` 停止。
+
+控制台不是新的远程管理服务：它只允许绑定 `127.0.0.1`、`::1` 或 `localhost`，默认端口
+为 `17654`。页面使用随机 HttpOnly/SameSite 会话 Cookie、CSRF token、严格 Host 校验和
+CSP。OIDC access/refresh token 始终保留在 CLI 进程及私有缓存中，不会返回给浏览器脚本；
+实际平台请求仍由服务端 Keycloak 授权决定。
+
+## 平台媒体服务
+
+自 1.8.0 起，`numa media` 通过当前 Keycloak 会话调用 `/api/v1/media`。第三方
+Seedance、语音和 OSS 凭据只存在于平台；CLI 不读取、不保存，也不输出这些凭据。
+这些命令直接调用平台 REST API，不经过 `numa_backend_request`，也没有新增媒体 MCP Tool。
+
+```bash
+# 查询 API 版本、Provider 和功能开关
+numa media capabilities --json
+
+# JSON 输入采用平台 lowerCamelCase 契约；重试时复用同一幂等键
+numa media tts submit \
+  --input narration.json \
+  --idempotency-key project-scene-01 \
+  --json
+
+numa media video submit \
+  --input seedance.json \
+  --idempotency-key project-shot-01 \
+  --json
+
+numa media job inspect job_123 --json
+
+# 网络中断导致提交结果不明时，先解析幂等键，不要直接重提付费任务
+numa media job resolve \
+  --type video \
+  --idempotency-key project-shot-01 \
+  --json
+
+# 目标文件必须不存在。CLI 先写同目录临时文件，校验后再原子重命名
+numa media artifact pull artifact_123 \
+  --output ./result.mp4 \
+  --sha256 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef \
+  --json
+
+# 文件以流式 multipart 上传，不编码进 JSON 或命令行参数；结果返回 artifactId
+numa media asset upload ./reference.png \
+  --kind image \
+  --project-id project_123 \
+  --idempotency-key reference-01 \
+  --json
+```
+
+素材库使用精确的 `id@semver` 引用。发布前先通过 `asset upload` 上传二进制，随后让
+manifest 的 `artifactId` 引用上传结果：
+
+```bash
+numa media library search --query product --cursor next_page --limit 20 --json
+numa media library inspect logo-main@1.2.0 --json
+numa media library pull logo-main@1.2.0 --output ./assets --json
+numa media library publish --manifest library-entry.json --json
+```
+
+`library publish` 首次创建接受 HTTP 201；同一 `id@semver` 和 SHA-256 的幂等重放接受
+HTTP 200。相同版本对应不同 SHA-256 时，平台应返回带 `code/message/requestId` 的 409。
+
+`--json` 的 CLI 外层是稳定的 snake_case envelope，例如 `{"ok":true,"job":...}`；
+`job`、`capabilities`、`entry` 等嵌套的平台 payload 原样保留 lowerCamelCase。首次提交
+任务成功时平台返回 HTTP 202；同一幂等键重放可返回 HTTP 200。两者都至少包含
+`jobId`、`status` 和 `requestId`。
+
+用户是否确认付费生成由上层 Skill 记录；真正的安全边界是平台 Grant、Quota 和服务端
+授权。CLI 不接受可伪造的 `--approval-id`。请求 JSON 可以包含只用于审计的
+`approvalContext`，但平台不得把其中的布尔值作为授权依据。
+
+`apiBaseUrl` 是服务根地址，可以是 `https://host`，也可以包含网关服务前缀，例如
+`https://host/mci-devops-platform`。后一种配置会把媒体路径解析成
+`/mci-devops-platform/api/v1/media/...`；已经带该前缀的兼容路径不会重复拼接。
+
+所有媒体 HTTP 调用只允许发送到 `apiBaseUrl` 的同源、同服务前缀地址。绝对外部 URL、
+`//host` 形式、反斜杠、路径穿越和内嵌 URL 凭据都会在附加 Bearer Token 前被拒绝。
+上传和下载错误会脱敏 Token 与常见签名参数；临时签名 URL 不进入稳定 JSON 输出。
+
+## Codex 远端账号
+
+`numa codex` 只使用官方 Codex 的 ChatGPT 文件登录模式。账号源主机或正式平台服务保管 OpenAI refresh token；客户端只获得 `access_token`、`id_token`、账号 ID 和到期时间，并写入官方 `~/.codex/auth.json`。模型请求由官方 Codex 直接发送，不经过 Numa 中转。
+
+Numa 会清理项目更名前旧版本写入的自定义 `model_provider = "mcex-codex"`、`auth.command`、动态 token helper 和桌面 provider 绑定，不需要删除整个 `~/.codex`。
+
+自 1.7.0 起，职责进一步收敛：numa 负责服务端账号分发、选择和短效凭据同步，`codex-multi-auth/cli` 负责把凭据应用到官方文件登录并返回脱敏状态。消费端不会调用 `codex-multi-auth` 的 OAuth 登录、本地账号池切换或 refresh token 刷新功能；真实 refresh token 仍只存在于服务端。升级期间 2.8.x 保留兼容写入路径，安装 `codex-multi-auth` 2.9.0 及以上后自动使用新的公共接口。
+
+默认连接生产网关；也可通过以下任一种方式显式覆盖：
+
+```bash
+numa codex list --server https://apps-gw-prd.mcisaas.com/mci-devops-platform/api
+export NUMA_CODEX_SERVICE_URL=https://apps-gw-prd.mcisaas.com/mci-devops-platform/api
+numa config --set apiBaseUrl=https://apps-gw-prd.mcisaas.com/mci-devops-platform
+```
+
+选择账号并启动：
+
+```bash
+# 管理员：把当前 codex-multi-auth 账号池批量上传到平台
+numa codex upload --server https://platform.example/api
+
+numa codex list
+numa codex use acct_xxx
+numa codex run
+
+# 每次启动前列出当前用户可用账号并交互选择
+numa codex run --select-account
+numa codex app . --select-account
+
+# 非交互脚本直接指定平台账号 ID
+numa codex run --account acct_xxx
+
+# 将参数原样交给官方 Codex
+numa codex run -- exec "完成这个长任务"
+numa codex run -- resume --last
+```
+
+### macOS / Windows 快捷入口
+
+日常使用优先安装快捷入口，无需全局安装 `@numa-tech/numa`。安装命令显式解析
+`@numa-tech/numa@latest`，生成的快捷入口也会在每次启动时使用 `--prefer-online`
+检查 npm 仓库中的最新客户端版本：
+
+```bash
+npx -y --prefer-online --registry=https://registry.npmjs.org/ @numa-tech/numa@latest codex shortcut install
+
+# 日常首选；首次运行会自动完成公司登录和账号选择
+numa-codex
+
+# 参数继续原样转发给官方 Codex
+numa-codex exec "完成这个任务"
+
+# 启动官方 Codex 桌面 App
+numa-codex-app
+```
+
+`--prefer-online` 会在启动时强制检查仓库元数据，`@latest` 避免复用项目内可能存在的旧版
+`@numa-tech/numa`；已经缓存的相同版本仍由 npm 复用。自动更新要求配置的 npm registry 可访问，
+并以仓库 `latest` dist-tag 指向的版本为准。已安装旧版快捷入口的用户重新执行一次上述安装
+命令，即可升级为自动检查最新版的包装脚本。快捷入口默认从公共 npm 获取 Numa CLI；
+启动 Codex 时仍按 `NUMA_CODEX_BIN`、PATH 中可用版本、包内版本的顺序选择。
+
+默认安装 `run` 和 `app` 两种入口。macOS 默认的 `--scope auto` 会先使用可写的
+`/usr/local/bin` 与 `/Applications`；没有系统级权限时自动降级到
+`~/.local/bin/numa-codex*` 与 `~/Applications/Numa Codex.app`，全程不会
+调用 `sudo`。可用 `--scope system` 或 `--scope user` 显式指定。Windows 写入用户 npm 命令目录，并在开始菜单
+创建 `Numa Codex`。macOS App Bundle 使用 ChatGPT macOS 应用内置图标，Windows 开始菜单
+入口使用由同一图标转换的 Windows 图标；来源和商标说明见 `THIRD_PARTY_NOTICES.md`。桌面入口默认绑定安装命令
+执行时的当前目录，也可显式指定：
+
+```bash
+npx -y --prefer-online --registry=https://registry.npmjs.org/ @numa-tech/numa@latest codex shortcut install --target app --workspace /path/to/project
+npx -y --prefer-online --registry=https://registry.npmjs.org/ @numa-tech/numa@latest codex shortcut install --target run --select-account
+npx -y --prefer-online --registry=https://registry.npmjs.org/ @numa-tech/numa@latest codex shortcut install --account acct_xxx
+```
+
+安装是幂等的，并拒绝覆盖同名的用户文件；确需替换时使用 `--force`。删除只处理安装清单中
+由 numa 管理的入口：
+
+```bash
+npx -y --prefer-online --registry=https://registry.npmjs.org/ @numa-tech/numa@latest codex shortcut remove
+```
+
+在 macOS/Windows 终端直接运行 `codex run` 且尚未安装默认快捷命令时，CLI 会用中文提示
+上述安装命令；检测到受管的 `numa-codex` 后不再重复提示。
+
+`numa codex upload` 默认读取当前 `codex-multi-auth` 存储上下文，也可使用
+`--storage <path>` 指定账号文件。整批上传会包含所有启用和停用账号；任一账号缺少
+refresh token 时整批终止，避免服务端形成不完整快照。令牌只通过带 Keycloak Bearer
+认证的 HTTPS 请求发送，不写入 CLI 输出。
+
+`@numa-tech/numa` 直接依赖官方 `@openai/codex`，因此发布到 npm 后，新主机可以用一条命令安装并启动：
+
+```bash
+npx -y --prefer-online --registry=https://registry.npmjs.org/ @numa-tech/numa@latest codex run --server https://platform.example/api
+```
+
+启动时会先运行 `codex --version` 做健康检查，依次使用 `NUMA_CODEX_BIN` 指定的入口、
+PATH 中已安装且可用的 Codex CLI、最后才使用 `@numa-tech/numa` 包内版本。这样已全局安装
+Codex 的主机不会受包内平台可选依赖缺失影响；外部版本不可用时会自动回退。设置
+`NUMA_USE_BUNDLED_CODEX=1` 可跳过 PATH 探测并强制使用包内版本。
+
+如果本机没有 Numa 会话，交互式 `run` 会先启动 Keycloak 登录。SSH 场景需要把登录回调端口转发到远端，例如 `ssh -L 8765:127.0.0.1:8765 host`。非交互环境必须预先运行 `numa login` 或提供 `NUMA_TOKEN_CACHE_PATH`。
+
+### Codex 桌面 App
+
+官方 Codex CLI、IDE 扩展和桌面 App 共享 `~/.codex/auth.json`。macOS/Windows 可直接运行：
+
+```bash
+numa codex app . \
+  --server https://platform.example/api
+```
+
+该命令会：
+
+1. 选择并验证服务端账号；
+2. 从服务端领取不含 refresh token 的官方登录凭据；
+3. 原子更新 ChatGPT 模式 `auth.json`；
+4. 清理项目更名前旧版 `mcex-codex` provider 残留；
+5. 直接启动官方 `codex app`。
+
+如果桌面 App 已经运行，需要完全退出后重新打开。`numa codex status` 可检查所选账号是否与官方登录文件匹配。
+
+### 前台官方登录同步
+
+需要验证官方订阅身份、插件目录和 `personalAccessToken` 认证效果时，可以让认证代理在前台运行：
+
+```bash
+numa codex auth-agent acct_xxx --replace-login
+```
+
+该命令会替换当前官方 Codex 登录，因此必须显式传入 `--replace-login`。代理仅支持官方 CLI 的文件凭据存储，并在首次替换前把已有 `~/.codex/auth.json` 备份为 `~/.codex/auth.json.numa-backup`。
+
+进入该模式时，代理会自动清理项目更名前遗留的 `mcex-codex` provider 和顶层选择。之后所有 CLI、IDE 和 App 都只读取官方登录文件。
+
+账号服务会专门刷新并返回 `access_token`、`id_token`、账号 ID 和到期时间，但绝不返回 OpenAI refresh token。客户端使用原子替换和 `0600` 权限写入 ChatGPT 模式 `auth.json`；其中 `refresh_token` 是每次凭据安装时由本机生成的 48 字节高熵随机占位值，不使用真实 refresh token 的格式或固定公共字符串。真实 refresh token 始终只在服务器。写入后代理运行：
+
+```bash
+codex -c 'cli_auth_credentials_store="file"' login status
+```
+
+`codex login --with-access-token` 只接受 Codex Personal/Agent access token，不能用于这里的 ChatGPT OAuth access token，因此代理不会调用该命令。
+
+前台会持续输出脱敏状态日志：
+
+```text
+2026-07-30T07:00:00.000Z INFO  auth.backup  已备份当前 Codex 文件登录: ~/.codex/auth.json.numa-backup
+2026-07-30T07:00:00.010Z INFO  agent.start  前台认证代理已启动；账号=Primary (acct_xxx)...
+2026-07-30T07:00:00.020Z INFO  token.fetch  正在从账号服务领取有效 access token
+2026-07-30T07:00:00.100Z INFO  token.received  已收到短效凭据；剩余=237小时...
+2026-07-30T07:00:00.110Z INFO  auth.write  正在原子更新 ChatGPT 模式 auth.json
+2026-07-30T07:00:00.400Z INFO  codex.verify.output  Logged in using ChatGPT
+2026-07-30T07:00:00.410Z INFO  token.installed  短效凭据已写入 auth.json 并经官方 Codex 验证
+```
+
+默认每 60 秒检查一次，剩余 1 小时时向服务端领取并安装新 token，从而尽量早于官方 App 自己的刷新尝试。token 本身不会出现在日志或命令参数中：
+
+```bash
+# 调整检查与提前刷新窗口
+numa codex auth-agent --replace-login \
+  --interval 30 \
+  --refresh-before 3600
+
+# 只安装和验证一次
+numa codex auth-agent --replace-login --once
+
+# JSON Lines 状态日志
+numa --json codex auth-agent --replace-login
+
+# 恢复首次运行前的文件登录
+numa codex auth-agent --restore
+```
+
+按 `Ctrl+C` 可停止前台代理。运行中的桌面 App 可能缓存旧凭据；日志出现 `app.reload` 提示、账号仍未切换或发生 `401` 时，需要完全退出后重新打开 App。当前仅支持 `--credential-store file`，不写入 Keychain。
+
+### 长任务与续期
+
+`numa codex run` 和 `numa codex app` 不再承担运行时续期。需要覆盖超过当前 access token 有效期的长任务时，应在独立前台终端持续运行 `numa codex auth-agent --replace-login`。代理默认每 60 秒检查一次，并在剩余 1 小时时向服务端领取新凭据、原子更新 `auth.json`。
+
+服务短暂不可用时，官方 Codex 可继续使用尚未过期的当前 access token；服务持续不可用直到 token 过期，或服务端 refresh 失败时，任务仍可能中断。客户端不会自行刷新，也不会持有真实 refresh token。
+
+本地敏感文件采用 `0600` 权限：
+
+- `${XDG_CONFIG_HOME:-~/.config}/numa/codex-selection.json`：服务地址和账号选择，不含 token；
+- `~/.codex/auth.json`：官方 ChatGPT 登录文件，包含短效 access/id token 和本机随机 refresh 占位值；
+- `~/.codex/auth.json.numa-backup`：首次替换前保留的原登录备份。
+
+运行 `numa codex reset` 会清理账号选择和旧 provider 残留；存在备份时恢复原登录，否则只在确认当前 `auth.json` 属于所选 numa 账号时移除它。该命令不会删除源主机账号。也可单独使用 `numa codex auth-agent --restore` 恢复备份。
+
+## 登录、个人信息与角色
+
+登录逻辑继续使用原项目的本地浏览器 PKCE 回调：
+
+```text
+http://127.0.0.1:8765/callback
+```
+
+成功后访问令牌和刷新令牌只写入本地令牌缓存，不会由 CLI 或 MCP 工具输出。`numa profile` 会聚合：
+
+- OIDC 用户资料；
+- `realm_access.roles`；
+- 各客户端的 `resource_access.<client>.roles`；
+- 用户组 `groups`。
+
+Keycloak 客户端需要允许：
+
+```text
+Valid redirect URIs:
+http://127.0.0.1:8765/callback
+http://localhost:8765/callback
+
+Web origins:
+http://127.0.0.1:8765
+http://localhost:8765
+```
+
+如需长期会话，还要允许 `offline_access`。
+
+### 认证环境变量
+
+| 变量 | 默认值 | 用途 |
+| --- | --- | --- |
+| `NUMA_KEYCLOAK_DISCOVERY_URL` | production numa realm | OIDC discovery，优先级最高 |
+| `NUMA_KEYCLOAK_ISSUER_URL` | 未设置 | 用于推导 discovery URL |
+| `NUMA_KEYCLOAK_BASE_URL` + `NUMA_KEYCLOAK_REALM` | 未设置 | 用于推导 issuer |
+| `NUMA_KEYCLOAK_CLIENT_ID` | `mcp-client` | OIDC client ID |
+| `NUMA_KEYCLOAK_CLIENT_SECRET` | 未设置 | 仅供 confidential client |
+| `NUMA_KEYCLOAK_REDIRECT_URI` | localhost callback | 完整回调覆盖 |
+| `NUMA_KEYCLOAK_SCOPES` | `openid profile email offline_access` | OAuth scopes |
+| `NUMA_TOKEN_CACHE_PATH` | `~/.config/numa/keycloak-token.json` | Keycloak 令牌缓存路径 |
+| `NUMA_AUTH_OPEN_BROWSER` | `true` | 是否自动打开浏览器 |
+| `NUMA_CONSOLE_HOST` | `127.0.0.1` | 网页控制台监听地址，只接受回环地址 |
+| `NUMA_CONSOLE_PORT` | `17654` | 网页控制台监听端口 |
+| `NUMA_BACKEND_BASE_URL` | 配置中的 `apiBaseUrl` | 平台 API 根地址，环境变量优先 |
+| `NUMA_BACKEND_ALLOW_ABSOLUTE_URLS` | `false` | 是否接受绝对 URL 输入；即使开启也严格限制为平台同源 |
+| `NUMA_CODEX_BIN` | 自动探测 | 显式指定官方 Codex CLI 可执行文件，优先级最高 |
+| `NUMA_USE_BUNDLED_CODEX` | `false` | 设为 `1` 时跳过 PATH 探测，强制使用 CLI 包内 Codex |
+
+## AI 和自动化调用
+
+所有命令都有 `--help`、访问级别、参数说明和示例：
+
+```bash
+numa help
+numa help request
+numa commands --json
+```
+
+AI 或 CI 应优先：
+
+1. 运行 `numa commands --json` 发现能力；
+2. 为业务命令添加全局 `--json`，获得稳定结构化结果；
+3. 根据退出码处理错误：`1` 通用失败、`3` 需要登录、`4` 缺少角色；
+4. 不读取或传播本地令牌文件。
+
+示例：
+
+```bash
+numa --json profile
+numa --json request /api/projects
+numa --json request /api/admin --require-role platform-admin
+```
+
+## MCP 兼容
+
+```json
+{
+  "mcpServers": {
+    "numa": {
+      "command": "numa",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+MCP 工具：
+
+- `numa_command_catalog`
+- `numa_auth_status`
+- `numa_auth_start_login`
+- `numa_auth_complete_login`
+- `numa_auth_whoami`
+- `numa_auth_logout`
+- `numa_backend_request`
+
+`numa_backend_request` 可传 `required_roles` 做 CLI 侧预检查；服务端仍须执行最终授权。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,13 @@
+# Third-party notices
+
+## ChatGPT application icon
+
+- Source application: ChatGPT for macOS
+- Source resources: `Contents/Resources/icon-chatgpt.icns` and `icon-chatgpt.png`
+- Retrieved from the locally installed application: 2026-08-05
+- Packaged ICNS SHA-256: `8ee5a24e1e32e33f976bc56943c2e8ad0a700449e6857741e543dc738648a2fb`
+- Derived ICO SHA-256: `4545a9e0b29627db6c7e2f6c27e7babede751559736b092b910966d72d6eb789`
+
+The Windows ICO is a format conversion of the ChatGPT application icon. ChatGPT, the application
+icon, and associated trademark rights belong to their respective owner. Inclusion of the icon does
+not imply endorsement by or affiliation with OpenAI.

package/dist/app-config.d.ts

@@ -0,0 +1,26 @@
+export type OutputFormat = "text" | "json";
+export type CliLocale = "zh-CN" | "en-US";
+export interface AppConfig {
+    schemaVersion: 2;
+    locale: CliLocale;
+    output: OutputFormat;
+    apiBaseUrl: string;
+    registryUrl: string;
+    checkUpdates: boolean;
+    initializedAt?: string;
+    updatedAt?: string;
+}
+export declare const DEFAULT_REGISTRY_URL = "https://registry.npmjs.org/";
+export declare const LEGACY_PRIVATE_REGISTRY_URL = "https://packages.aliyun.com/60371955c4393f5ed3b7baa8/npm/npm-registry/";
+export declare const DEFAULT_API_BASE_URL = "https://apps-gw-prd.mcisaas.com/mci-devops-platform";
+export declare const DEFAULT_APP_CONFIG: AppConfig;
+export declare function appConfigDirectory(): string;
+export declare function appConfigPath(): string;
+export declare function loadAppConfig(): Promise<AppConfig>;
+export declare function loadAppConfigSync(): AppConfig;
+export declare function hasAppConfig(): Promise<boolean>;
+export declare function saveAppConfig(config: AppConfig): Promise<AppConfig>;
+export declare function resetAppConfig(): Promise<void>;
+export declare const CONFIG_KEYS: readonly ["locale", "output", "apiBaseUrl", "registryUrl", "checkUpdates"];
+export type ConfigKey = (typeof CONFIG_KEYS)[number];
+export declare function updateConfigValue(config: AppConfig, expression: string): AppConfig;