multi-codex 0.7.0__py3-none-any.whl

multi_codex/doctor.py

@@ -0,0 +1,244 @@
+"""体检：只读地检查安装、配置、环境变量、各账号状态，以及配置与实际文件是否一致。
+
+不修复任何东西：已有的 `apply` 就是修复手段，这里只给出建议命令。不联网，不运行 `codex login status`。
+检查项与 fail / warn 条件见 feature-account-insight §5.1.3。
+"""
+
+import os
+import re
+import shutil
+import subprocess
+from typing import List, NamedTuple, Optional, Tuple
+
+from . import accounts, identity, migrate, platform, switch
+from .actions import CONFLICT, CREATE, DELETE, SKIP, UPDATE
+from .config import ConfigError, load_config
+from .fsutil import KIND_DIR, KIND_LINK, KIND_MISSING, entry_kind, expand
+
+OK = "ok"
+WARN = "warn"
+FAIL = "fail"
+
+# usage --live 依赖的 account/rateLimits/read 从 0.48.0 起提供。
+MIN_LIVE_CODEX_VERSION = (0, 48, 0)
+_VERSION_TIMEOUT_SEC = 10
+_VERSION_RE = re.compile(r"(\d+)\.(\d+)\.(\d+)")
+
+
+class Check(NamedTuple):
+    id: str
+    status: str
+    message: str
+    hint: Optional[str] = None
+    details: Tuple[str, ...] = ()
+
+
+def run_checks() -> List[Check]:
+    """依次执行全部检查。配置无法读取时，后面依赖配置的检查全部跳过。"""
+    checks = [_check_codex()]
+    try:
+        config, exists = load_config()
+    except ConfigError as exc:
+        checks.append(Check("config", FAIL, str(exc)))
+        checks.append(_check_migration())
+        return checks
+    if not exists:
+        checks.append(Check("config", WARN, "no configuration yet", "multi-codex add NAME"))
+        checks.append(_check_migration())
+        checks.append(_check_env())
+        return checks
+    checks.append(Check("config", OK, "loaded {} account(s)".format(len(config.accounts))))
+    checks.append(_check_migration())
+    checks.append(_check_path(expand(config.bin_dir)))
+    checks.append(_check_env())
+    checks.append(_check_default_dir(config))
+    checks.append(_check_drift(config))
+    identities = []
+    for name in config.accounts:
+        check, found = _check_account(config, name)
+        checks.append(check)
+        if found is not None:
+            identities.append((name, found))
+    checks.append(_check_duplicates(identities))
+    checks.append(_check_bindings(config))
+    return checks
+
+
+def _check_codex() -> Check:
+    path = shutil.which("codex")
+    if path is None:
+        return Check("codex", FAIL, "codex was not found in PATH", "install Codex CLI and put it on PATH")
+    try:
+        proc = subprocess.run([path, "--version"], stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+                              universal_newlines=True, timeout=_VERSION_TIMEOUT_SEC)
+        output = proc.stdout.strip()
+    except subprocess.TimeoutExpired:
+        return Check("codex", WARN, "{} --version did not finish within {}s".format(path, _VERSION_TIMEOUT_SEC))
+    except OSError as exc:
+        return Check("codex", WARN, "cannot run {} --version: {}".format(path, exc))
+    match = _VERSION_RE.search(output)
+    if match is None:
+        return Check("codex", WARN, "cannot parse the version of {}: {!r}".format(path, output[:100]))
+    version = tuple(int(part) for part in match.groups())
+    message = "{} ({})".format(output.splitlines()[-1] if output else match.group(0), path)
+    if version < MIN_LIVE_CODEX_VERSION:
+        return Check("codex", WARN, message + "; `usage --live` needs Codex 0.48.0 or newer", "upgrade Codex")
+    return Check("codex", OK, message)
+
+
+def _check_migration() -> Check:
+    try:
+        notice = migrate.pending_journal_notice()
+    except migrate.JournalError as exc:
+        return Check("migration", FAIL, str(exc),
+                     "move the complete data back to the source path, then delete {}".format(migrate.journal_path()))
+    if notice:
+        return Check("migration", FAIL, notice, "rerun the same `multi-codex migrate-default` command")
+    # restore 做到一半同样会拦下其它写命令，这里一并报告。
+    try:
+        restore = switch.load_restore_journal()
+    except switch.RestoreJournalError as exc:
+        return Check("migration", FAIL, str(exc), "check ~/.codex and the account directory, then delete {}".format(
+            switch.restore_journal_path()))
+    if restore:
+        return Check("migration", FAIL, "unfinished restore of {}".format(restore["name"]),
+                     "multi-codex restore {}".format(restore["name"]))
+    return Check("migration", OK, "no unfinished migration or restore")
+
+
+def _check_path(bin_dir: str) -> Check:
+    if platform.dir_on_path(bin_dir):
+        return Check("path", OK, "{} is in PATH".format(bin_dir))
+    return Check("path", WARN, "{} is not in PATH; codex-<name> launchers cannot be found".format(bin_dir),
+                 "add {} to PATH in your shell profile".format(bin_dir))
+
+
+def _check_env() -> Check:
+    found = [name for name in ("CODEX_HOME",) + platform.ISOLATION_BREAKING_ENV if os.environ.get(name)]
+    if not found:
+        return Check("env", OK, "no variables that override per-account isolation")
+    return Check("env", WARN, "set in this shell: {}; they override or bypass per-account isolation".format(
+        ", ".join(found)), "unset {}".format(" ".join(found)))
+
+
+def _check_default_dir(config) -> Check:
+    # default_source() 返回字面量 "~/.codex"，必须先展开；输出里仍用短写法 source 方便阅读。
+    source = platform.default_source()
+    path = expand(source)
+    kind = entry_kind(path)
+    if kind == KIND_MISSING:
+        return Check("default-dir", OK, "{} does not exist".format(source))
+    if kind == KIND_DIR:
+        return Check("default-dir", OK, "{} is a real directory (not migrated)".format(source))
+    if kind == KIND_LINK:
+        real = os.path.realpath(path)
+        for name in config.accounts:
+            if os.path.realpath(accounts.account_dir(config, name)) == real:
+                return Check("default-dir", OK, "{} links to account {}".format(source, name))
+        return Check("default-dir", WARN, "{} links to {}, which is not a registered account".format(source, real))
+    return Check("default-dir", WARN, "{} is neither a directory nor a link".format(source))
+
+
+def _check_drift(config) -> Check:
+    """复用收敛计划判断配置与文件是否一致。plan 只读文件系统，副作用都在动作的 run 回调里，这里不执行。
+
+    第二个参数必须传副本：plan_shared 会就地改写 new 的 managed_links（shared.py:92），
+    传同一个对象会让 old 也被改掉，计划结果就不再反映真实差异。
+    """
+    actions = accounts.plan(config, config.copy(), orphan_scope=accounts.ALL_ORPHANS)
+    conflicts = [action for action in actions if action.status == CONFLICT]
+    pending = [action for action in actions if action.status in (CREATE, UPDATE, DELETE)]
+    # skip 是持久状态（例如共享目录里本来就没有某项），apply 也消除不了，只作为说明列出。
+    notes = [action for action in actions if action.status == SKIP]
+    details = tuple(_describe(action) for action in conflicts + pending + notes)
+    if conflicts:
+        return Check("drift", FAIL, "{} conflict(s) with files multi-codex does not own".format(len(conflicts)),
+                     "resolve the conflicts listed below by hand", details)
+    if pending:
+        return Check("drift", WARN, "{} change(s) pending".format(len(pending)), "multi-codex apply", details)
+    return Check("drift", OK, "files match the configuration", None, details)
+
+
+def _describe(action) -> str:
+    text = "{} {} {}".format(action.status, action.kind, action.path)
+    return text + (" ({})".format(action.reason) if action.reason else "")
+
+
+def _check_account(config, name: str) -> Tuple[Check, Optional[identity.Identity]]:
+    check_id = "account:" + name
+    directory = accounts.account_dir(config, name)
+    if not os.path.isdir(directory):
+        return Check(check_id, FAIL, "account directory {} does not exist".format(directory),
+                     "multi-codex apply"), None
+    found = identity.read_identity(directory)
+    problems = []
+    hint = None
+    if found.login == identity.LOGIN_LOGGED_OUT:
+        problems.append("not logged in")
+        hint = "multi-codex login {}".format(name)
+    elif found.login == identity.LOGIN_UNREADABLE:
+        problems.append("auth.json cannot be read")
+        hint = "multi-codex login {}".format(name)
+    elif found.login == identity.LOGIN_KEYRING:
+        problems.append("credentials are in the system keyring (cli_auth_credentials_store = {!r}); "
+                        "the login cannot be read from files".format(found.store))
+    if os.path.islink(os.path.join(directory, "sessions")):
+        problems.append("sessions is a link; local usage data may belong to another account")
+    if problems:
+        return Check(check_id, WARN, "; ".join(problems), hint), found
+    return Check(check_id, OK, _identity_summary(found)), found
+
+
+def _identity_summary(found: identity.Identity) -> str:
+    if found.login == identity.LOGIN_CHATGPT:
+        return "logged in as {}{}".format(found.email or "(no email)",
+                                          " ({})".format(found.plan) if found.plan else "")
+    if found.login == identity.LOGIN_APIKEY:
+        return "logged in with an API key"
+    return "login type: {}".format(found.login)
+
+
+def _check_duplicates(identities) -> Check:
+    groups = identity.duplicate_groups(identities)
+    if not groups:
+        return Check("duplicates", OK, "no two accounts share one ChatGPT login")
+    return Check("duplicates", WARN, "; ".join("{} are logged in as the same ChatGPT account".format(
+        ", ".join(group)) for group in groups), "log one of them in with another ChatGPT account")
+
+
+def _check_bindings(config) -> Check:
+    """悬空的目录绑定：账号已注销或目录已删除。只报 warn，run 遇到时会给出明确的报错。"""
+    problems = []
+    for path in sorted(config.bindings):
+        name = config.bindings[path]
+        if config.find(name) is None:
+            problems.append("{} -> {} (account is not registered)".format(path, name))
+        elif not os.path.isdir(path):
+            problems.append("{} -> {} (directory does not exist)".format(path, name))
+    if problems:
+        return Check("bindings", WARN, "{} stale binding(s)".format(len(problems)),
+                     "multi-codex unbind <directory>", tuple(problems))
+    return Check("bindings", OK, "{} binding(s)".format(len(config.bindings)))
+
+
+def to_json(checks: List[Check]) -> dict:
+    return {
+        "version": 1,
+        "ok": not any(check.status == FAIL for check in checks),
+        "checks": [{"id": check.id, "status": check.status, "message": check.message, "hint": check.hint,
+                    "details": list(check.details)} for check in checks],
+    }
+
+
+def format_checks(checks: List[Check]) -> List[str]:
+    width = max(len(check.id) for check in checks)
+    lines = []
+    for check in checks:
+        lines.append("{:<4}  {}  {}".format(check.status, check.id.ljust(width), check.message))
+        for detail in check.details:
+            lines.append("      {}".format(detail))
+        if check.hint and check.status != OK:
+            lines.append("      fix: {}".format(check.hint))
+    counts = {status: sum(1 for check in checks if check.status == status) for status in (OK, WARN, FAIL)}
+    lines.append("{} ok, {} warn, {} fail".format(counts[OK], counts[WARN], counts[FAIL]))
+    return lines

multi_codex/fsutil.py

@@ -0,0 +1,250 @@
+"""文件系统工具：原子写入、路径判定、文件清单与校验、跳过特殊文件的复制。
+
+本模块只做与业务无关的文件操作，不读取配置，也不输出日志；
+调用方负责决定何时调用以及如何报告结果。
+"""
+
+import hashlib
+import os
+import shutil
+import stat
+import tempfile
+from typing import Callable, Dict, List, Optional, Tuple
+
+# entry_kind() 的返回值
+KIND_MISSING = "missing"
+KIND_LINK = "link"
+KIND_DIR = "dir"
+KIND_FILE = "file"
+# socket、FIFO、设备文件等运行时产物
+KIND_SPECIAL = "special"
+
+
+def expand(path: str) -> str:
+    """展开 `~` 并转成绝对路径；不解析软链，调用方需要真实路径时自行 realpath。"""
+    return os.path.abspath(os.path.expanduser(path))
+
+
+def is_under(path: str, root: str) -> bool:
+    """path 等于 root 或位于 root 之下。
+
+    必须按路径段比较：直接用 startswith(root) 会把 `~/.codex-shared`
+    误判为位于 `~/.codex` 之下。
+    """
+    root = root.rstrip(os.sep) or os.sep
+    if path == root:
+        return True
+    prefix = root if root.endswith(os.sep) else root + os.sep
+    return path.startswith(prefix)
+
+
+def entry_kind(path: str) -> str:
+    """按 lstat 判断目录项类型，不跟随软链；断开的软链返回 KIND_LINK。"""
+    try:
+        st = os.lstat(path)
+    except FileNotFoundError:
+        return KIND_MISSING
+    if stat.S_ISLNK(st.st_mode):
+        return KIND_LINK
+    if stat.S_ISDIR(st.st_mode):
+        return KIND_DIR
+    if stat.S_ISREG(st.st_mode):
+        return KIND_FILE
+    return KIND_SPECIAL
+
+
+def same_target(link_path: str, target: str) -> bool:
+    """link_path 解析后的真实路径是否与 target 的真实路径相同。
+
+    两边都用 realpath，这样 `~` 写法、多级软链或尾部斜杠都不影响判断。
+    """
+    return os.path.realpath(link_path) == os.path.realpath(target)
+
+
+def atomic_write(path: str, content: str, mode: int = 0o644) -> None:
+    """原子替换 path 的内容：写临时文件、fsync，再用 os.replace 覆盖。
+
+    进程在任何时刻被杀，path 要么是旧内容，要么是完整的新内容，
+    不会出现写了一半的文件。临时文件与目标在同一目录，保证 replace 不跨设备。
+    """
+    directory = os.path.dirname(path) or "."
+    os.makedirs(directory, exist_ok=True)
+    fd, tmp_path = tempfile.mkstemp(prefix=".multi-codex-", dir=directory)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(content)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.chmod(tmp_path, mode)
+        os.replace(tmp_path, path)
+    except BaseException:
+        try:
+            os.unlink(tmp_path)
+        except FileNotFoundError:
+            pass
+        raise
+    _fsync_dir(directory)
+
+
+def _fsync_dir(directory: str) -> None:
+    # 让 rename 本身落盘；部分文件系统不支持对目录 fsync，失败可以忽略。
+    try:
+        dir_fd = os.open(directory, os.O_RDONLY)
+    except OSError:
+        return
+    try:
+        os.fsync(dir_fd)
+    except OSError:
+        pass
+    finally:
+        os.close(dir_fd)
+
+
+def read_text(path: str) -> Optional[str]:
+    """读取 UTF-8 文本；文件不存在、不可读或不是文本时返回 None。"""
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            return handle.read()
+    except (OSError, UnicodeDecodeError):
+        return None
+
+
+def remove_path(path: str) -> None:
+    """删除一个目录项：软链只删链接本身，目录整体删除，普通文件直接删除。
+
+    路径不存在时什么也不做，便于中断后重跑时重复调用。
+    """
+    kind = entry_kind(path)
+    if kind == KIND_MISSING:
+        return
+    if kind == KIND_DIR:
+        _grant_owner_access(path)
+        shutil.rmtree(path)
+    else:
+        os.unlink(path)
+
+
+def _grant_owner_access(root: str) -> None:
+    """删除前给目录树里的每个目录补上本人的读、写、执行权限。
+
+    没有读或执行权限的目录，rmtree 既列不出内容也删不掉里面的文件；
+    而用 rmtree 的错误回调补权限再重试并不可靠（新版 rmtree 按文件描述符遍历，
+    回调拿到的函数可能是 os.open，直接重调会抛 TypeError）。
+    所以先自上而下补齐权限：父目录先改，os.walk 才能继续列出子目录。软链不跟随、不修改。
+    权限已齐全的目录不动：中途遇到无权修改的目录会抛错，此时已处理过的目录应尽量保持原样。
+    """
+    _add_owner_rwx(root)
+    for dirpath, dirnames, _filenames in os.walk(root, followlinks=False):
+        for name in dirnames:
+            full = os.path.join(dirpath, name)
+            if entry_kind(full) == KIND_DIR:
+                _add_owner_rwx(full)
+
+
+def _add_owner_rwx(path: str) -> None:
+    mode = stat.S_IMODE(os.lstat(path).st_mode)
+    if mode & stat.S_IRWXU != stat.S_IRWXU:
+        os.chmod(path, mode | stat.S_IRWXU)
+
+
+# 清单条目：(类型, 大小, SHA-256 或软链目标)。目录的大小与哈希固定为 0 和空串。
+ManifestEntry = Tuple[str, int, str]
+
+
+def build_manifest(root: str) -> Tuple[Dict[str, ManifestEntry], List[str]]:
+    """递归生成 root 的文件清单，返回 (清单, 跳过的特殊文件相对路径)。
+
+    软链不跟随，只记录链接目标；socket、FIFO、设备文件属于运行时产物，
+    不进清单，单独返回给调用方写日志。
+    """
+    manifest: Dict[str, ManifestEntry] = {}
+    skipped: List[str] = []
+    # onerror 必须抛出：os.walk 默认静默跳过读不了的目录，两侧清单会同样缺一整棵子树，
+    # 校验因此误判“一致”，随后 park 并删除备份，数据就丢了。
+    for dirpath, dirnames, filenames in os.walk(root, onerror=_raise, followlinks=False):
+        rel_dir = os.path.relpath(dirpath, root)
+        entries = [(name, True) for name in dirnames] + [(name, False) for name in filenames]
+        for name, _is_dir_hint in entries:
+            full = os.path.join(dirpath, name)
+            rel = name if rel_dir == "." else os.path.join(rel_dir, name)
+            kind = entry_kind(full)
+            if kind == KIND_LINK:
+                manifest[rel] = (KIND_LINK, 0, os.readlink(full))
+            elif kind == KIND_DIR:
+                manifest[rel] = (KIND_DIR, 0, "")
+            elif kind == KIND_FILE:
+                manifest[rel] = (KIND_FILE, os.lstat(full).st_size, _sha256(full))
+            elif kind == KIND_SPECIAL:
+                skipped.append(rel)
+    return manifest, skipped
+
+
+def _raise(exc: OSError) -> None:
+    raise exc
+
+
+def _sha256(path: str) -> str:
+    digest = hashlib.sha256()
+    with open(path, "rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def copy_tree(src: str, dst: str, on_progress: Optional[Callable[[str], None]] = None) -> List[str]:
+    """把 src 复制到尚不存在的 dst，返回跳过的特殊文件相对路径。
+
+    与 shutil.copytree 的区别：遇到 socket、FIFO、设备文件时跳过而不是报错
+    （copytree 会抛 `Operation not supported on socket` 并留下半份目标）。
+    软链按软链本身复制；普通文件用 copy2 保留权限位和时间戳。
+    目录权限在内容复制完后再设置，避免只读目录挡住后续写入。
+    on_progress 在每个普通文件复制后调用一次，供测试在复制中途注入中断。
+    """
+    skipped: List[str] = []
+    dir_modes: List[Tuple[str, str]] = []
+    os.makedirs(dst)
+    dir_modes.append((src, dst))
+    for dirpath, dirnames, filenames in os.walk(src, onerror=_raise, followlinks=False):
+        rel_dir = os.path.relpath(dirpath, src)
+        target_dir = dst if rel_dir == "." else os.path.join(dst, rel_dir)
+        for name in list(dirnames) + list(filenames):
+            full = os.path.join(dirpath, name)
+            target = os.path.join(target_dir, name)
+            kind = entry_kind(full)
+            if kind == KIND_LINK:
+                os.symlink(os.readlink(full), target)
+            elif kind == KIND_DIR:
+                os.mkdir(target)
+                dir_modes.append((full, target))
+            elif kind == KIND_FILE:
+                shutil.copy2(full, target, follow_symlinks=False)
+                if on_progress is not None:
+                    on_progress(target)
+            elif kind == KIND_SPECIAL:
+                skipped.append(os.path.relpath(full, src))
+    for source_dir, target_dir in reversed(dir_modes):
+        shutil.copystat(source_dir, target_dir, follow_symlinks=False)
+    return skipped
+
+
+def diff_manifests(expected: Dict[str, ManifestEntry], actual: Dict[str, ManifestEntry]) -> List[str]:
+    """返回两份清单不一致的相对路径（排序后），空列表表示完全一致。"""
+    mismatched = [rel for rel in expected if actual.get(rel) != expected[rel]]
+    mismatched.extend(rel for rel in actual if rel not in expected)
+    return sorted(set(mismatched))
+
+
+def display_path(path: str) -> str:
+    """把 HOME 下的路径缩写成 `~/…`，只用于给人看的输出。
+
+    脚本读取的输出（`path` 命令、`--json`）不得使用它：`~` 交给不经 shell 的程序时不会被展开。
+    HOME 为空或为 `/` 时不缩写，否则所有路径都会变成 `~` 开头。
+    """
+    home = os.path.expanduser("~")
+    if not home or home == os.sep:
+        return path
+    if path == home:
+        return "~"
+    if path.startswith(home + os.sep):
+        return "~" + path[len(home):]
+    return path

multi_codex/identity.py

@@ -0,0 +1,171 @@
+"""账号的凭据存储模式与登录身份：只读本地文件，从不联网，也不输出任何令牌。
+
+两类调用方：
+- 迁移预检（fix-keyring-migration）：凭据存在系统钥匙串时，迁移会改变目录真实路径，
+  Codex 按新路径算出的钥匙串键找不到旧条目，登录就丢了，所以要先知道存储模式；
+- list / usage / doctor（feature-account-insight）：显示每个账号登录的邮箱与套餐，检测重复登录。
+
+字段与取值都以 openai/codex 源码为准（基线 6b4daafd），出处见两份方案文档 §1 / §3。
+"""
+
+import base64
+import json
+import os
+import re
+from typing import Dict, Iterable, List, NamedTuple, Optional, Tuple
+
+STORE_FILE = "file"
+STORE_KEYRING = "keyring"
+STORE_AUTO = "auto"
+STORE_EPHEMERAL = "ephemeral"
+
+# 未设置时 Codex 的默认值（上游 config/defaults.toml:6）。
+DEFAULT_STORE = STORE_FILE
+
+# 系统级配置层，优先级低于账号目录里的 config.toml（上游 config/src/loader/mod.rs:79）。
+SYSTEM_CONFIG = "/etc/codex/config.toml"
+# 测试专用：把系统级配置换成临时文件，避免开发机上真实的 /etc/codex/config.toml 影响结果。
+SYSTEM_CONFIG_ENV = "MULTI_CODEX_TEST_SYSTEM_CONFIG"
+
+LOGIN_CHATGPT = "chatgpt"
+LOGIN_APIKEY = "apikey"
+LOGIN_LOGGED_OUT = "logged-out"
+LOGIN_KEYRING = "keyring"
+LOGIN_UNREADABLE = "unreadable"
+LOGIN_OTHER = "other"
+
+_AUTH_CLAIMS = "https://api.openai.com/auth"
+_PROFILE_CLAIMS = "https://api.openai.com/profile"
+
+# 只认顶层的 `cli_auth_credentials_store = "..."`，值可用单引号或双引号，允许行尾注释。
+_STORE_LINE = re.compile(r"""^\s*cli_auth_credentials_store\s*=\s*(?:"([^"]*)"|'([^']*)')\s*(?:#.*)?$""")
+
+
+class Identity(NamedTuple):
+    """一个账号目录的登录状态。
+
+    user_id、workspace_id 只用于比较重复登录，不显示、不写进 JSON。
+    plan 是 id_token 签发时的套餐，下次刷新令牌后才会更新。
+    """
+    login: str
+    email: Optional[str]
+    plan: Optional[str]
+    user_id: Optional[str]
+    workspace_id: Optional[str]
+    store: str
+
+
+def _system_config_path() -> str:
+    return os.environ.get(SYSTEM_CONFIG_ENV) or SYSTEM_CONFIG
+
+
+def _read_store_key(path: str) -> Optional[str]:
+    """在第一个表头之前找 cli_auth_credentials_store；找不到或读不了时返回 None。
+
+    Python 3.8 没有 tomllib，这里只做最小解析。已知局限：多行字符串中以 `[` 开头的行会被当成表头，
+    带引号的键名识别不了。两种情况都按“没有这个键”处理，最坏是漏报，与没有这项检查时一样。
+    """
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as handle:
+            lines = handle.read().splitlines()
+    except OSError:
+        return None
+    for line in lines:
+        if line.strip().startswith("["):
+            # 这个键属于顶层 ConfigToml，写在任何表（如 [profiles.x]）里都不生效。
+            return None
+        match = _STORE_LINE.match(line)
+        if match:
+            return match.group(1) if match.group(1) is not None else match.group(2)
+    return None
+
+
+def credentials_store(account_dir: str) -> Tuple[str, Optional[str]]:
+    """返回 (存储模式, 取值来源文件)。两层都没有设置时返回 (file, None)。
+
+    按 Codex 的配置层优先级：账号目录的 config.toml（User 层）高于系统级配置（System 层）。
+    托管配置、MDM、项目目录 .codex/ 中的设置不在考虑范围内（方案 §2 非目标）。
+    """
+    for path in (os.path.join(account_dir, "config.toml"), _system_config_path()):
+        value = _read_store_key(path)
+        if value is not None:
+            return value, path
+    return DEFAULT_STORE, None
+
+
+def _decode_jwt_payload(token: str) -> Optional[dict]:
+    """只做 base64url 解码，不验签，与 Codex 自己读 id_token 的方式一致（上游 token_data.rs:129-140）。"""
+    parts = token.split(".")
+    if len(parts) < 2:
+        return None
+    payload = parts[1] + "=" * (-len(parts[1]) % 4)
+    try:
+        claims = json.loads(base64.urlsafe_b64decode(payload.encode("ascii")).decode("utf-8"))
+    except (ValueError, UnicodeError):
+        return None
+    return claims if isinstance(claims, dict) else None
+
+
+def _text(value: object) -> Optional[str]:
+    return value if isinstance(value, str) and value else None
+
+
+def read_identity(account_dir: str) -> Identity:
+    """读取一个账号目录的登录身份（判定顺序见 feature-account-insight §5.1.1）。
+
+    令牌只在本函数内部解码，不放进返回值，也不出现在任何异常信息里。
+    """
+    store, _ = credentials_store(account_dir)
+    if store == STORE_KEYRING:
+        # keyring 模式只读钥匙串、不回落读文件（上游 storage.rs:310-313），
+        # 从 file 模式切过来时残留的 auth.json 不代表当前登录。
+        return Identity(LOGIN_KEYRING, None, None, None, None, store)
+    path = os.path.join(account_dir, "auth.json")
+    if not os.path.lexists(path):
+        login = LOGIN_KEYRING if store == STORE_AUTO else LOGIN_LOGGED_OUT
+        return Identity(login, None, None, None, None, store)
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            data = json.load(handle)
+    except (OSError, ValueError):
+        return Identity(LOGIN_UNREADABLE, None, None, None, None, store)
+    if not isinstance(data, dict):
+        return Identity(LOGIN_UNREADABLE, None, None, None, None, store)
+
+    tokens = data.get("tokens")
+    id_token = tokens.get("id_token") if isinstance(tokens, dict) else None
+    if isinstance(id_token, str) and id_token:
+        claims = _decode_jwt_payload(id_token)
+        if claims is None:
+            return Identity(LOGIN_UNREADABLE, None, None, None, None, store)
+        auth = claims.get(_AUTH_CLAIMS)
+        auth = auth if isinstance(auth, dict) else {}
+        profile = claims.get(_PROFILE_CLAIMS)
+        profile = profile if isinstance(profile, dict) else {}
+        email = _text(claims.get("email")) or _text(profile.get("email"))
+        user_id = _text(auth.get("chatgpt_user_id")) or _text(auth.get("user_id"))
+        workspace_id = _text(auth.get("chatgpt_account_id")) or _text(tokens.get("account_id"))
+        return Identity(LOGIN_CHATGPT, email, _text(auth.get("chatgpt_plan_type")), user_id, workspace_id, store)
+    if data.get("auth_mode") == "apikey" or _text(data.get("OPENAI_API_KEY")):
+        return Identity(LOGIN_APIKEY, None, None, None, None, store)
+    return Identity(LOGIN_OTHER, None, None, None, None, store)
+
+
+def duplicate_groups(identities: Iterable[Tuple[str, Identity]]) -> List[List[str]]:
+    """找出登录了同一个 ChatGPT 账号和同一个工作区的账号组（每组至少两个）。
+
+    同一个邮箱在不同工作区登录不算重复：它们的额度互相独立。
+    任一 ID 缺失的账号不参与比较，否则两个都缺 ID 的账号会被误判为同一个。
+    """
+    groups: Dict[Tuple[str, str], List[str]] = {}
+    for name, identity in identities:
+        if identity.login == LOGIN_CHATGPT and identity.user_id and identity.workspace_id:
+            groups.setdefault((identity.user_id, identity.workspace_id), []).append(name)
+    return [names for names in groups.values() if len(names) > 1]
+
+
+def display_login(identity: Identity) -> str:
+    """list 表格中 LOGIN 列的取值。"""
+    if identity.login == LOGIN_CHATGPT:
+        return identity.email or "chatgpt"
+    return {LOGIN_APIKEY: "api-key", LOGIN_LOGGED_OUT: "-"}.get(identity.login, identity.login)