multi-claude-cli 0.4.0__py3-none-any.whl

multi_claude/sessions.py

@@ -0,0 +1,195 @@
+"""会话交接：把一条 Claude 会话从一个账号复制到另一个账号（方案 feature-session-handoff）。
+
+Claude 把会话存成 `<配置目录>/projects/<编码后的工作目录>/<会话ID>.jsonl`，旁边的同名目录
+放子代理记录与存成文件的大段工具输出。目录名编码是“非字母数字字符换成 -”，超过 200 字符时
+截断再接一段 Claude 内部的哈希；本模块不复刻那段哈希，目标账号直接沿用来源账号里已有的目录名。
+
+只复制，不移动、不删除来源，也不改写会话内容；目标里已有不同内容的同 ID 会话时默认拒绝。
+"""
+
+import os
+import re
+import shutil
+import tempfile
+from typing import Dict, List, NamedTuple, Optional, Tuple
+
+from . import statusline
+from .fsutil import build_manifest, copy_tree, diff_manifests
+
+# Claude 2.1.286 的 `tx`：编码后的目录名超过这个长度就截断并接哈希。
+ENCODED_LIMIT = 200
+SESSION_ID_PATTERN = re.compile(r"^[A-Za-z0-9-]+$")
+
+COPIED = "copied"
+UNCHANGED = "unchanged"
+CONFLICT = "conflict"
+
+
+class HandoffError(Exception):
+    """找不到目录或会话、复制失败等，对应退出码 1。"""
+
+
+class Plan(NamedTuple):
+    session_id: str
+    # 找到会话目录时用的工作目录写法；续聊命令必须 cd 到这个写法，目标账号才会按同一目录名找会话
+    cwd: str
+    # 来源账号里的项目目录；目标账号沿用它的目录名
+    source_dir: str
+    target_dir: str
+    # 截到最后一个换行后的会话内容
+    content: bytes
+    # copied（将要 / 已经复制）、unchanged 或 conflict
+    state: str
+
+
+def encode(path: str) -> str:
+    return re.sub(r"[^a-zA-Z0-9]", "-", path)
+
+
+def cwd_variants(environ: Dict[str, str]) -> List[str]:
+    """Claude 编码时用的是物理路径还是 $PWD 没有核实，两种都试；$PWD 必须与当前目录是同一个目录。"""
+    variants = [os.getcwd()]
+    pwd = environ.get("PWD")
+    if pwd and os.path.isabs(pwd) and pwd not in variants:
+        try:
+            if os.path.samefile(pwd, variants[0]):
+                variants.append(pwd)
+        except OSError:
+            pass
+    return variants
+
+
+def project_dir(account_dir: str, variants: List[str]) -> Tuple[str, str]:
+    """在账号的 projects/ 下找当前工作目录对应的目录，返回 (目录, 命中的工作目录写法)；没有或有多个时抛 HandoffError。"""
+    projects = os.path.join(account_dir, "projects")
+    try:
+        names = os.listdir(projects)
+    except OSError:
+        names = []
+    found: List[Tuple[str, str]] = []
+    for variant in variants:
+        encoded = encode(variant)
+        if len(encoded) <= ENCODED_LIMIT:
+            matches = [encoded] if encoded in names else []
+        else:
+            # 超长路径的目录名后缀是 Claude 内部哈希，只能按截断后的前缀找。
+            prefix = encoded[:ENCODED_LIMIT] + "-"
+            matches = [name for name in names if name.startswith(prefix)]
+        for name in matches:
+            path = os.path.join(projects, name)
+            if os.path.isdir(path) and path not in [item[0] for item in found]:
+                found.append((path, variant))
+    if not found:
+        raise HandoffError("no sessions for {} in {}".format(variants[0], projects))
+    if len(found) > 1:
+        raise HandoffError("several session directories match {}: {}".format(
+            variants[0], ", ".join(item[0] for item in found)))
+    return found[0]
+
+
+def pick_session(directory: str, requested: Optional[str], current: Optional[str]) -> str:
+    """选会话：--session 优先；其次当前会话（仅当它在这个目录里）；最后取修改时间最新的一条。"""
+    if requested is not None:
+        if not os.path.isfile(os.path.join(directory, requested + ".jsonl")):
+            raise HandoffError("session {} not found in {}".format(requested, directory))
+        return requested
+    if current and SESSION_ID_PATTERN.match(current) and os.path.isfile(os.path.join(directory, current + ".jsonl")):
+        return current
+    candidates = [name[:-len(".jsonl")] for name in os.listdir(directory)
+                  if name.endswith(".jsonl") and os.path.isfile(os.path.join(directory, name))]
+    if not candidates:
+        raise HandoffError("no sessions in {}".format(directory))
+    return max(candidates, key=lambda sid: os.stat(os.path.join(directory, sid + ".jsonl")).st_mtime_ns)
+
+
+def plan(source_account_dir: str, target_account_dir: str, variants: List[str],
+         requested: Optional[str], current: Optional[str]) -> Plan:
+    source_dir, cwd = project_dir(source_account_dir, variants)
+    session_id = pick_session(source_dir, requested, current)
+    with open(os.path.join(source_dir, session_id + ".jsonl"), "rb") as handle:
+        raw = handle.read()
+    # 来源会话可能正在追加，只取到最后一个完整行，避免目标里出现半行 JSON。
+    end = raw.rfind(b"\n")
+    if end < 0:
+        raise HandoffError("session {} has no complete lines yet".format(session_id))
+    content = raw[:end + 1]
+    target_dir = os.path.join(target_account_dir, "projects", os.path.basename(source_dir))
+    return Plan(session_id, cwd, source_dir, target_dir, content,
+                _state(source_dir, target_dir, session_id, content))
+
+
+def _state(source_dir: str, target_dir: str, session_id: str, content: bytes) -> str:
+    target_file = os.path.join(target_dir, session_id + ".jsonl")
+    target_extra = os.path.join(target_dir, session_id)
+    if not os.path.lexists(target_file) and not os.path.lexists(target_extra):
+        return COPIED
+    try:
+        with open(target_file, "rb") as handle:
+            same_file = handle.read() == content
+    except OSError:
+        same_file = False
+    return UNCHANGED if same_file and _same_extra(os.path.join(source_dir, session_id), target_extra) else CONFLICT
+
+
+def _same_extra(source: str, target: str) -> bool:
+    has_source, has_target = os.path.isdir(source), os.path.lexists(target)
+    if not has_source or not has_target:
+        return has_source == has_target
+    if not os.path.isdir(target) or os.path.islink(target):
+        return False
+    return not diff_manifests(build_manifest(source)[0], build_manifest(target)[0])
+
+
+def execute(handoff: Plan, force: bool) -> List[str]:
+    """按计划复制，返回 --force 时生成的备份路径。
+
+    同名目录先落位、会话文件最后落位：会话文件出现就说明这次复制是完整的。
+    任一步失败时删除本次的临时项；已落位的目录保留，再次运行时会参与冲突判定，不会被静默覆盖。
+    """
+    session_id = handoff.session_id
+    target_file = os.path.join(handoff.target_dir, session_id + ".jsonl")
+    target_extra = os.path.join(handoff.target_dir, session_id)
+    backups = []
+    if handoff.state == CONFLICT:
+        if not force:
+            raise RuntimeError("conflict must be handled by the caller")
+        # 备份名不以 .jsonl 结尾，Claude 不会把它当成会话列出来。
+        for path in (target_file, target_extra):
+            if os.path.lexists(path):
+                backup = statusline._backup_path(path)
+                os.rename(path, backup)
+                backups.append(backup)
+    os.makedirs(handoff.target_dir, exist_ok=True)
+    source_extra = os.path.join(handoff.source_dir, session_id)
+    if os.path.isdir(source_extra):
+        staging = os.path.join(handoff.target_dir, ".multi-claude-{}.tmp".format(session_id))
+        # 上次复制中途被杀会留下临时目录，它从未落位、不属于任何会话，直接清掉再复制。
+        _remove_tree(staging)
+        try:
+            copy_tree(source_extra, staging)
+            os.rename(staging, target_extra)
+        except BaseException:
+            _remove_tree(staging)
+            raise
+    fd, tmp_path = tempfile.mkstemp(prefix=".multi-claude-{}.".format(session_id), suffix=".jsonl.tmp",
+                                    dir=handoff.target_dir)
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(handoff.content)
+            handle.flush()
+            os.fsync(handle.fileno())
+        # 会话里可能有提示词与代码，与 Claude 自己写的会话文件一样只给属主读写。
+        os.chmod(tmp_path, 0o600)
+        os.replace(tmp_path, target_file)
+    except BaseException:
+        try:
+            os.unlink(tmp_path)
+        except FileNotFoundError:
+            pass
+        raise
+    return backups
+
+
+def _remove_tree(path: str) -> None:
+    if os.path.lexists(path):
+        shutil.rmtree(path, ignore_errors=True)

multi_claude/shared.py

@@ -0,0 +1,130 @@
+"""共享资源链接的计划（方案 §5.1.10，沿用 multi-codex §5.1.6）。
+
+每个账号可以把 CLAUDE.md、skills 等条目软链到同一个共享目录。
+判断“是不是本工具建的链接”只看 Account.managed_links：链接本身带不了受管标记，
+而用户很可能早就手工建过指向同一共享目录的链接，这类链接关闭共享时不能删。
+"""
+
+import os
+from typing import List, Optional
+
+from . import platform
+from .actions import CONFLICT, CREATE, DELETE, SKIP, UNCHANGED, UPDATE, Action
+from .config import Account, Config
+from .fsutil import KIND_LINK, KIND_MISSING, entry_kind, expand, same_target
+
+
+def plan_shared(new: Config, account: Account, account_dir: str,
+                old_shared_dir: Optional[str], adopt: bool = False) -> List[Action]:
+    """为一个账号生成共享链接动作，并就地更新 account.managed_links。
+
+    adopt 为真时（`add --adopt`），已经指向对应共享条目、但不在名单里的软链会被写进名单（接管），
+    链接本身不动。只接管“指向正确”的软链：指向别处的软链和真实目录照旧判冲突，
+    以免把用户另有用途的东西交给工具，之后关闭共享时被删掉。
+
+    old_shared_dir 是变更前的共享目录：修改 shared.dir 后，
+    仍指向旧目录的受管链接需要改指向新目录，而不是被当成“指向别处”的冲突。
+    """
+    actions: List[Action] = []
+    desired = {}
+    if account.shared:
+        if not new.shared_dir:
+            return [Action(CONFLICT, "shared-link", account_dir,
+                           "shared.dir is not configured; run `multi-claude init --shared-dir DIR`")]
+        shared_root = expand(new.shared_dir)
+        for item in new.shared_items:
+            if item in account.shared_exclude:
+                # 不进 desired：本工具建过的这项链接会走下面“该项关闭共享”的删除分支，用户自建的不动。
+                continue
+            source = os.path.join(shared_root, item)
+            if entry_kind(source) == KIND_MISSING:
+                actions.append(Action(SKIP, "shared-link", os.path.join(account_dir, item),
+                                      "not present in shared dir {}".format(shared_root), quiet=True))
+                continue
+            desired[item] = source
+
+    managed = set(account.managed_links)
+    old_root = expand(old_shared_dir) if old_shared_dir else None
+    kept: List[str] = []
+
+    for item, source in desired.items():
+        link = os.path.join(account_dir, item)
+        kind = entry_kind(link)
+        if kind == KIND_MISSING:
+            actions.append(Action(CREATE, "shared-link", link, "-> " + source,
+                                  _create_link(source, link)))
+            kept.append(item)
+        elif kind == KIND_LINK and same_target(link, source):
+            if item in managed:
+                actions.append(Action(UNCHANGED, "shared-link", link))
+                kept.append(item)
+            elif adopt:
+                # 没有文件操作：接管只体现在 config.json 的 managed_links 里。
+                actions.append(Action(UPDATE, "shared-link", link, "adopted"))
+                kept.append(item)
+            else:
+                actions.append(Action(UNCHANGED, "shared-link", link))
+        elif kind == KIND_LINK and item in managed and _points_to(link, old_root, item):
+            actions.append(Action(UPDATE, "shared-link", link, "-> " + source,
+                                  _replace_link(source, link)))
+            kept.append(item)
+        else:
+            reason = "a link to another location" if kind == KIND_LINK else "a real {}".format(
+                "directory" if kind == "dir" else "file")
+            actions.append(Action(CONFLICT, "shared-link", link,
+                                  "already exists as {}".format(reason)))
+
+    for item in account.managed_links:
+        if item in desired:
+            continue
+        link = os.path.join(account_dir, item)
+        kind = entry_kind(link)
+        if kind == KIND_MISSING:
+            continue
+        if kind == KIND_LINK and (_points_to(link, old_root, item) or
+                                  _points_to(link, expand(new.shared_dir) if new.shared_dir else None, item)):
+            actions.append(Action(DELETE, "shared-link", link, "sharing disabled for this item",
+                                  _unlink(link)))
+        else:
+            # 用户已把它换成了别的东西，不再归本工具管理；从名单里移除，但不动它。
+            actions.append(Action(SKIP, "shared-link", link,
+                                  "no longer the link multi-claude created; left untouched"))
+
+    # 保持与 shared_items 相同的顺序，便于人工阅读 config.json。
+    order = {item: index for index, item in enumerate(new.shared_items)}
+    account.managed_links = sorted(set(kept), key=lambda item: order.get(item, len(order)))
+    return actions
+
+
+def plan_remove_links(account: Account, account_dir: str, shared_dir: Optional[str]) -> List[Action]:
+    """账号被注销时，删除本工具建立、且仍指向共享目录的链接。"""
+    actions: List[Action] = []
+    root = expand(shared_dir) if shared_dir else None
+    for item in account.managed_links:
+        link = os.path.join(account_dir, item)
+        if entry_kind(link) == KIND_LINK and _points_to(link, root, item):
+            actions.append(Action(DELETE, "shared-link", link, "account removed", _unlink(link)))
+    return actions
+
+
+def _points_to(link: str, shared_root: Optional[str], item: str) -> bool:
+    return shared_root is not None and same_target(link, os.path.join(shared_root, item))
+
+
+def _create_link(source: str, link: str):
+    def run() -> None:
+        platform.create_link(source, link)
+    return run
+
+
+def _replace_link(source: str, link: str):
+    def run() -> None:
+        os.unlink(link)
+        platform.create_link(source, link)
+    return run
+
+
+def _unlink(link: str):
+    def run() -> None:
+        os.unlink(link)
+    return run

multi_claude/shellpath.py

@@ -0,0 +1,33 @@
+"""生成“把目录加进 PATH”的一行命令（方案 feature-clearer-help §5.1.3）。
+
+只生成给用户看的提示文字，不改任何 shell 配置文件。按 $SHELL 选择配置文件：
+macOS 的 bash 登录 shell 读 ~/.bash_profile，其它系统的交互 bash 读 ~/.bashrc；fish 用 fish_add_path。
+install.sh 里有同一张表的 shell 实现，两边要保持一致。
+"""
+
+import os
+from typing import Optional
+
+
+def add_to_path_command(directory: str, shell: Optional[str], system: str) -> Optional[str]:
+    """返回可直接粘贴运行的命令；不认识的 shell、或目录里有单引号（无法安全写进单引号串）时返回 None。"""
+    if "'" in directory:
+        return None
+    name = os.path.basename(shell or "")
+    export_line = "export PATH=\"{}:$PATH\"".format(directory)
+    if name == "zsh":
+        return "echo '{}' >> ~/.zshrc".format(export_line)
+    if name == "bash":
+        profile = "~/.bash_profile" if system == "Darwin" else "~/.bashrc"
+        return "echo '{}' >> {}".format(export_line, profile)
+    if name == "fish":
+        return "fish_add_path '{}'".format(directory)
+    return None
+
+
+def path_hint(directory: str, shell: Optional[str], system: str) -> str:
+    """提示用户把 directory 加进 PATH 的完整一句话（cli 与 doctor 共用）。"""
+    command = add_to_path_command(directory, shell, system)
+    if command is None:
+        return "add it to PATH in your shell profile"
+    return "run: {}, then open a new terminal".format(command)

multi_claude/statusline.py

@@ -0,0 +1,196 @@
+"""statusLine 包装与用量采集（方案 feature-statusline-usage）。
+
+`statusline install FILE` 把设置文件里已有的 statusLine 命令包成
+`<multi-claude 路径> statusline-hook <原命令>`。Claude Code 刷新状态栏时用 `/bin/sh -c` 执行它，
+并把一段 JSON 写进 stdin。钩子入口在 hook.py：它把 stdin 交给后台进程里的 capture，
+自己用 exec 把进程交给 `/bin/sh -c <原命令>`，状态栏的输出、退出码与不包装时完全相同。
+
+钩子靠环境里的 `CLAUDE_CONFIG_DIR` 认账号（default 身份不设它），不读凭据、不联网。
+钩子的 stdout 就是状态栏内容，所以采集过程中不得向 stdout 输出任何东西，采集失败也只能静默。
+"""
+
+import json
+import os
+import shlex
+import shutil
+import stat
+import time
+from datetime import datetime, timedelta
+from typing import Mapping, NamedTuple, Optional, Tuple
+
+from . import accounts, usage
+from .config import Account, Config, load_config
+from .fsutil import atomic_write
+from .hook import HOOK_COMMAND
+
+EXECUTABLE = "multi-claude"
+# 同一账号的状态栏约 300 ms 刷新一次；数值没变时一分钟内只落盘一次。
+THROTTLE = timedelta(seconds=60)
+
+# install / uninstall 的结果
+WRAPPED = "wrapped"
+REWRAPPED = "rewrapped"
+UNCHANGED = "unchanged"
+RESTORED = "restored"
+NOT_INSTALLED = "not installed"
+
+
+class StatuslineError(Exception):
+    """设置文件或其中的 statusLine 不合法，对应退出码 1；文件未被修改。"""
+
+
+class Result(NamedTuple):
+    state: str
+    # 实际改写的文件（FILE 是软链时为它指向的文件）
+    target: str
+    # 改写前的备份；没有写入（无变化或 --dry-run）时为 None
+    backup: Optional[str]
+    # 改写后的 statusLine 命令
+    command: str
+
+
+def wrap(executable: str, original: str) -> str:
+    """包装后的命令。两段都用 shlex.quote：/bin/sh 对单引号串不做任何展开，钩子收到的参数与原命令逐字节相同。"""
+    return "{} {} {}".format(shlex.quote(executable), HOOK_COMMAND, shlex.quote(original))
+
+
+def unwrap(command: str) -> Optional[Tuple[str, str]]:
+    """若 command 是本工具包装过的命令，返回 (multi-claude 路径, 原命令)；否则返回 None。"""
+    try:
+        parts = shlex.split(command)
+    except ValueError:
+        return None
+    if len(parts) == 3 and parts[1] == HOOK_COMMAND and os.path.basename(parts[0]) == EXECUTABLE:
+        return parts[0], parts[2]
+    return None
+
+
+def install(path: str, executable: str, dry_run: bool = False) -> Result:
+    """包装 path 中的 statusLine 命令；已包装且路径相同时不改动，路径变了则改用新路径。"""
+    target, data, command = _load(path)
+    wrapped = unwrap(command)
+    if wrapped is not None and wrapped[0] == executable:
+        return Result(UNCHANGED, target, None, command)
+    original = wrapped[1] if wrapped is not None else command
+    new_command = wrap(executable, original)
+    state = REWRAPPED if wrapped is not None else WRAPPED
+    return Result(state, target, _save(target, data, new_command, dry_run), new_command)
+
+
+def uninstall(path: str, dry_run: bool = False) -> Result:
+    """把 path 中包装过的 statusLine 命令还原成原命令；没有包装时不改动。"""
+    target, data, command = _load(path)
+    wrapped = unwrap(command)
+    if wrapped is None:
+        return Result(NOT_INSTALLED, target, None, command)
+    return Result(RESTORED, target, _save(target, data, wrapped[1], dry_run), wrapped[1])
+
+
+def _load(path: str) -> Tuple[str, dict, str]:
+    # 改软链指向的文件而不是替换软链本身：~/.claude-shared 下的设置文件常被各账号软链引用。
+    target = os.path.realpath(path)
+    try:
+        with open(target, "r", encoding="utf-8") as handle:
+            raw = handle.read()
+    except FileNotFoundError:
+        raise StatuslineError("{} does not exist".format(target))
+    except (OSError, UnicodeDecodeError) as exc:
+        raise StatuslineError("cannot read {}: {}".format(target, exc))
+    try:
+        data = json.loads(raw)
+    except ValueError as exc:
+        raise StatuslineError("{} is not valid JSON: {}".format(target, exc))
+    if not isinstance(data, dict):
+        raise StatuslineError("{} is not a JSON object".format(target))
+    status_line = data.get("statusLine")
+    if (not isinstance(status_line, dict) or status_line.get("type") != "command"
+            or not isinstance(status_line.get("command"), str) or not status_line["command"].strip()):
+        raise StatuslineError("no command statusLine in {}".format(target))
+    return target, data, status_line["command"]
+
+
+def _save(target: str, data: dict, command: str, dry_run: bool) -> Optional[str]:
+    """先备份再原子写入；只改 statusLine.command，其它键（padding、refreshInterval 等）原样保留。"""
+    if dry_run:
+        return None
+    data["statusLine"]["command"] = command
+    mode = stat.S_IMODE(os.stat(target).st_mode)
+    backup = _backup_path(target)
+    shutil.copy2(target, backup)
+    atomic_write(target, json.dumps(data, indent=2, ensure_ascii=False) + "\n", mode=mode)
+    return backup
+
+
+def _backup_path(target: str) -> str:
+    base = "{}.multi-claude-bak.{}".format(target, time.strftime("%Y%m%d_%H%M%S"))
+    candidate, index = base, 1
+    # 同一秒内连续执行两次时不覆盖前一份备份。
+    while os.path.lexists(candidate):
+        candidate = "{}.{}".format(base, index)
+        index += 1
+    return candidate
+
+
+def capture(data: bytes, environ: Mapping[str, str], now: datetime) -> None:
+    """把 stdin JSON 里的 rate_limits 存成所属账号的快照；没有数据、认不出账号时什么也不做。"""
+    payload = json.loads(data.decode("utf-8"))
+    if not isinstance(payload, dict):
+        return
+    windows = usage.statusline_windows(payload.get("rate_limits"))
+    if windows is None:
+        # 非 Pro/Max 订阅、或会话还没收到第一次 API 响应时没有 rate_limits。
+        return
+    config, exists = load_config()
+    if not exists:
+        return
+    account = account_for(config, environ.get("CLAUDE_CONFIG_DIR"))
+    if account is None:
+        return
+    path = usage.snapshot_path(account)
+    if _recently_captured(path, windows, now):
+        return
+    directory = accounts.account_dir(config, account.name)
+    document = {
+        "schema_version": usage.SNAPSHOT_SCHEMA_VERSION,
+        "captured_at": now.isoformat(),
+        # 读取时与账号当前目录比较，目录被换掉后旧快照不再采用。
+        "config_dir": os.path.realpath(directory),
+        # 读取时与当前登录比较，同一目录换了登录后旧快照不再采用。
+        "account_uuid": usage.current_account_uuid(usage.global_state_path(account.identity, directory)),
+        "rate_limits": windows,
+    }
+    os.makedirs(os.path.dirname(path), mode=0o700, exist_ok=True)
+    # 同一账号的多个会话会同时写：原子替换保证读到的总是某一次完整的快照。
+    atomic_write(path, json.dumps(document, indent=2) + "\n", mode=0o600)
+
+
+def account_for(config: Config, config_dir: Optional[str]) -> Optional[Account]:
+    """按 Claude 进程的 CLAUDE_CONFIG_DIR 找账号；未设置时就是 default 身份账号（它靠不设该变量使用 ~/.claude）。
+
+    比较真实路径：经软链或带 `~` 的写法指向同一目录也能认出。
+    """
+    if not config_dir:
+        return config.default_account()
+    real = os.path.realpath(os.path.expanduser(config_dir))
+    for account in config.accounts.values():
+        if os.path.realpath(accounts.account_dir(config, account.name)) == real:
+            return account
+    return None
+
+
+def _recently_captured(path: str, windows: dict, now: datetime) -> bool:
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            previous = json.load(handle)
+    except (OSError, ValueError):
+        return False
+    if not isinstance(previous, dict) or previous.get("rate_limits") != windows:
+        return False
+    try:
+        captured_at = datetime.fromisoformat(previous.get("captured_at"))
+    except (TypeError, ValueError):
+        return False
+    if captured_at.tzinfo is None:
+        return False
+    # 快照时间在未来（时钟回拨）时不算“刚写过”，重新写一次把时间纠正回来。
+    return timedelta(0) <= now - captured_at < THROTTLE