comate-cli 0.12.5__tar.gz → 0.12.6b2__tar.gz

comate_cli-0.12.6b2/.python-version

@@ -0,0 +1 @@
+3.12

{comate_cli-0.12.5 → comate_cli-0.12.6b2}/CHANGELOG.md

@@ -4,6 +4,10 @@
 
 ### Added
 
+- Interpreter Migration（macOS/Linux）：CLI 不在 Python 3.12 上、并且没有待更新的新版本时，第一次启动在界面之前显示一行提示，之后的启动显示全屏提示，只有「立即迁移」和「跳过」。「立即迁移」把**当前版本**（`<包名>==<当前版本>`，带发行版的安装参数）用 `--python 3.12` 重装，成功后提示重启，本次启动停止；失败只显示一行原因（uv 输出的最后一行），继续在当前 Python 上进入界面。「跳过」不记住，下次启动再问。已经在 3.12、editable 安装、PATH 里没有 uv、Windows 都不提示；有待更新的新版本时只显示更新提示（接受更新会顺带迁移到 3.12）。文案四种语言齐全。
+- Event loop 冻结看门狗：界面动画 / 计时停住超过 2 秒时，独立线程把主线程当时的调用栈连同最近的首轮阶段名、busy / staging / 动画状态写进 `~/.comate/logs/agent.log`（WARNING），同一次冻结在 2 秒、5 秒、15 秒各记一次；默认开启，设 `COMATE_TUI_LOOP_WATCHDOG=0` 关闭。原有的「TUI event loop lag detected」日志现在带阶段名，且空闲态（无请求、无动画）的停顿超过 2 秒也记一条 INFO，不再静默（阈值 `AGENT_SDK_TUI_EVENT_LOOP_IDLE_LAG_THRESHOLD_S`）。此前冻结日志只能说明停了多久，说不出停在哪，多次 3–37 秒冻结因此无法归因。
+- 思考时长：隐藏 thinking 时，一段思考正常结束后，loading 行括号里的呼吸黄 badge 换成静态暗灰的时长短语，显示 3 秒后消失。短语与 badge 逐档对应：`thought for 8s with high effort`（max / xhigh / high 同句式）、`ultra thought for 8s`、`thought for 8s`（medium / 无生效档）、`thought briefly for 8s`（low）；60 秒及以上显示 `1m 5s`。不足 1 秒、中断、stream 重试、思考中途打开 thinking 显示、turn 结束时都不显示。固定英文，不随界面语言变化；不写 scrollback。
+- MCP 工具搜索（SDK）：MCP 工具很多时，工具 schema 改为按需加载——模型先只看到工具名清单，需要时调用内置 `ToolSearch` 加载，下一步才能调用该工具。默认 `auto`（延迟候选 schema ≥ 生效窗口 10% 且数量 ≥ 30 时启用），可用环境变量 `COMATE_AGENT_SDK_TOOL_SEARCH`（`auto` / `auto:P` / `auto:P:C` / `on` / `off`）调整。首次启用时终端提示一次；`/context` 拆分显示 MCP 工具与已加载 / 延迟候选数；单个 MCP 工具定义超过窗口 5% 时启动后警告。comate-cli 与 comate-rpc 的 `comate-agent-sdk` 下限抬到 0.12.20（SDK 同步升版，新事件 `ToolSearchEnabledEvent`）。
 - 规则双目录（SDK）：条件规则（带 `paths:` 的规则文件）现在也从项目 `.claude/rules/` 与用户 `~/.claude/rules/` 读取，Claude Code 里配好的路径规则搬到 comate 下直接生效——Read 命中路径注入 reminder，Edit / Write 预检同样拦截注入；user 层受 user setting source 门控，项目层受 project 门控。同一层级内 `.agent/rules` 与 `.claude/rules` 的同名文件（按相对路径）只加载 `.agent` 那份，被遮蔽路径记 info 日志；用户层与项目层之间不去重，两份都加载。`paths` 支持逗号分隔字符串（`paths: "src/**, lib/**"` 拆成多个模式，剥掉首尾空白与引号），YAML 列表形式不变；rules 目录下指向目录的符号链接跟进（做环检测，同一真实目录只进一次）；`.agents/rules/` 不读。目录、去重、逗号、符号链接四项改动作用在统一扫描入口上，常驻规则同样受益。
 - 技能扫描根加入 `.agents`（SDK；含 CLI `/skills` 菜单来源判定修正）：`npx skills add` 装进 `.agents/skills/` 的技能直接被发现、可通过 Skill 工具调用，`.claude/skills/` 下指向它的符号链接不会让它列两次；运行中再装一个，下一轮用户输入后热发现也能看到。扫描根顺序即优先级，同名先到先得：项目 `.agent/skills` → `.agents/skills` → `.claude/skills`；用户 `~/.agent/skills` → `~/.agents/skills` → `~/.config/agents/skills` → `~/.claude/skills`，两层各受对应 setting source 门控。四类扫描根下以 `.` 开头的子目录一律跳过（不当作 skill 也不当作 namespace）。`/skills` 菜单的同名去重与来源判定改按真实路径（扫描根与 skill 目录两边 resolve 后再比），符号链接 skill 归入正确分组、不再兜底成 user，project 组副标题自动列出 `.agents/skills`。
 - MCP 工具停用（SDK 部分，菜单在后续版本）：`.mcp.json` 的 server 条目新增可选字段 `disabled_tools`（字符串数组，写 server 自报的原始工具名，精确匹配、不支持通配符），列出的工具不再发给模型、子 agent 点名也拿不到；没列出的工具与 server 新增的工具照常加载，名单里写了 server 不提供的名字不报错。代码里传的 `mcp_servers`（含 `type: "sdk"`）认同一个字段。新增存盘函数 `comate_agent_sdk.mcp.set_mcp_server_disabled_tools(alias, names, *, scope, project_root)`：只改该条目的这一个字段，空名单即删除字段，对 `{"enabled": false}` 墓碑条目报错。新增 `AgentRuntime.set_mcp_disabled_tools(alias, names)`：会话中途改名单，不重连任何 server，下一次模型请求生效（实测 3 台 × 50 个工具单次约 2.4ms）。一台 server 的工具全部停用时它保持连接，但它的 instructions 不再发给模型。旧版本 SDK 会忽略这个字段并加载全部工具。
@@ -68,6 +72,9 @@
 
 ### Changed
 
+- Self-Update 固定到 Python 3.12：`comate update`、启动时的「立即更新」、Windows 旁装，以及 Windows 自动路径不可用时显示的手动修复命令，都让新版本装在 Python 3.12 上（uv 命令带 `--python 3.12`；机器上没有 3.12 时 uv 会自动下载）。原因：uv 在读包之前就选好解释器，并且忽略 `requires-python` 的上限，所以以前用户会跑在 3.11 / 3.13 / 3.14 等不同版本上，而且不带 `--python` 的重装会把已经在 3.12 上的环境换成别的版本。白牌发行版在 `install_args` 里自己指定了 `--python` 时，以白牌的为准。`requires-python` 不变，3.11–3.13 继续支持。决策见 ADR 0055。
+- 简中用户更新时，uv 需要下载的 Python 改走国内镜像（npmmirror 的 python-build-standalone），不再依赖 GitHub；进程内重装和 Windows 旁装都生效。你自己设置了 `UV_PYTHON_INSTALL_MIRROR` 时以你的为准；其他语言环境不变。
+- resume 选择器的预览键由 Ctrl+V 改为 Ctrl+A：VS Code、Windows Terminal 等终端把 Ctrl+V 截成粘贴，按下后剪贴板文本会落进搜索框，进不了预览。搜索模式下也可以按 Ctrl+A 预览，Esc 或再按 Ctrl+A 关闭后回到搜索框，搜索词保持不变；代价是搜索框内 Ctrl+A 不再移到行首。
 - 0.12.4 测试版里的随包 `/pr`（别名 `/mr`）改名为 `/open-pr`（别名 `/open-mr`），功能不变。原因：`pr` 是常见的第三方 skill 名，旧名会挡住用户自己装的同名 skill。`/pr`、`/mr` 不再有效，也没有改名提示。
 - 用户装的 skill 现在可以覆盖同名的随包命令（`/commit`、`/learn`、`/implement-plan`、`/open-pr` 等）：`/<名字>` 调用 skill，不提示，和 project/user 自定义命令覆盖随包命令一样。skill 只占了随包命令的某个别名时，随包命令只失去这个别名。skill 被禁用或随插件卸载后，随包命令自动回来。`user-invocable: false` 的 skill 不占名字。核心命令（`/help`、`/model` 等）与用户自己写的同名自定义命令仍然优先于 skill；这种冲突改为每个名字每个进程只提示一次（以前每次启动、切换会话、加载插件都会输出一条英文 WARNING），提示按界面语言显示，并说明模型仍可以通过 Skill 工具调用这个 skill。见 ADR-0038。
 - 思考被折叠时，loading 行括号里的呼吸黄短语不再随机挑，改为按这次请求真实生效的思考档位挑词：ultracode → `ultra thinking`、max / xhigh / high → `thinking some more with <档位> effort`（如 `thinking some more with high effort`）、medium → `thinking`、low → `light thinking`；auto 且模型无默认档、模型不支持调档、off 时显示 `thinking`，不再出现低档却显示 `ultra thinking` 的情况。档位取端点降档后的实际值（与 statusline 一致），每次请求开始思考时读一次，一轮中途开 ultracode 后下一次请求即生效。颜色、位置、出现时机不变；短语在中文 / 日文界面下也保持英文。
@@ -91,6 +98,10 @@
 
 ### Fixed
 
+- 切换窗口后运行中的任务被中断、输入框多出 `[O[I`：终端开着焦点上报（DECSET 1004，
+  例如 Windows PowerShell 经 ssh 连到远程服务器）时，窗口失焦 / 得焦会发 `ESC[O` / `ESC[I`。
+  prompt_toolkit 不认识这两条序列，把它们拆成 Esc 加两个普通字符，Esc 就中断了本轮。
+  现在这两条序列被整段忽略，主界面与所有弹窗都不再被切窗口误触发；真按 Esc 照常中断。
 - `comate update` 在依赖包刚发布时解析失败：更新命令只刷新 CLI 自身的索引缓存，
   依赖（如 `comate-agent-sdk`）仍用旧缓存，uv 报 `No solution found`。macOS/Linux
   进程内更新与 Windows 分阶段安装现在都改用 `uv tool install --refresh`，刷新全部

{comate_cli-0.12.5 → comate_cli-0.12.6b2}/CONTEXT.md

@@ -5,13 +5,33 @@ Canonical language for Comate CLI command discovery, slash input completion, men
 ## Menu Panel Language
 
 **Menu Panel（菜单面板）**:
-由 slash 命令打开的暂态操作界面。多个菜单使用一致的视觉与导航规则，关闭后返回对话输入。Menu Panel 打开期间，Status Bar 不显示。
-_Avoid_: menu output（菜单输出）, history block（历史块）
+由 slash 命令或 Job Indicator 打开的暂态操作界面，嵌在底部交互带里，不切换屏幕。多个菜单使用一致的视觉与导航规则，关闭后返回对话输入。Menu Panel 打开期间，Status Bar 不显示。
+_Avoid_: menu output（菜单输出）, history block（历史块）, 全屏 picker（会话内面板不再使用全屏界面）
 
 **Status Bar（状态栏）**:
-底部交互带最下方的一行。左列显示 Transient Status Message，没有消息时显示权限模式提示；右列显示会话信息（模型、分支、上下文余量等）。Menu Panel 打开期间隐藏；工具审批、向用户提问、退出确认不属于 Menu Panel，不隐藏它。
+底部交互带最下方的一行。左列显示 Transient Status Message，没有消息时显示权限模式提示和 Job Indicator；右列显示会话信息（模型、分支、上下文余量等）。用户可以把键盘焦点从输入框移到 Status Bar，在 Job Indicator 之间选择。Menu Panel 打开期间隐藏；工具审批、向用户提问、退出确认不属于 Menu Panel，不隐藏它。
 _Avoid_: footer（Menu Panel 自己有页脚）, bottom toolbar（prompt_toolkit 的术语，本项目不使用）, 补全状态行（与 Status Bar 共用同一个位置，但是另一个东西）
 
+**Job Indicator（后台任务指示）**:
+Status Bar 左列里按类别显示的后台 job 数量，例如 `2 agents`、`1 shell`、`1 workflow`、`1 MCP call`。类别：agents（agent job）、shells（bash 与 monitor job）、workflows（workflow job）、mcp（MCP 后台调用）。只统计仍在运行或待命的 job；数量为 0 的类别不显示。选中一个 Job Indicator 并确认，会打开该类别的菜单。它取代了输入框上方常驻的 jobs 面板。
+_Avoid_: pill（口头说法）, jobs 面板（已删除的旧区域）, 后台任务栏
+
+**Jobs Menu（后台任务菜单）**:
+列出本会话后台 job 的 Menu Panel，可以查看 job 详情和停止 job。从 Job Indicator 打开时只列该类别的 job；从 `/ps` 打开时列出全部类别。workflow 类别打开的是 workflows 菜单，不是 Jobs Menu。
+_Avoid_: ps picker, jobs picker（已删除的全屏版本）
+
+**Job Activity（job 活动）**:
+后台 agent job 最近一次工具调用的单行英文描述，例如 `Running tasklist …`、`Reading identity.py`。工具开始时出现，显示到该 job 的 turn 结束为止；工具执行完、模型思考期间仍显示上一个工具。固定英文，不跟随界面语言。
+_Avoid_: current tool line（SDK 里的原始字符串 `Tool(k=v…)`，是另一个东西）, 工具行
+
+**MCP 进度行（MCP Progress Line）**:
+下游 MCP server 推送的最近一条进度文字，SDK 把它清洗成一行。前台调用时显示在折叠容器的嵌套行里，后台调用时显示在 Jobs Menu 的行里。内容来自外部 server，什么语言都可能。
+_Avoid_: Job Activity（那是 agent job 的工具调用描述，由 CLI 生成，固定英文）
+
+**Job 结算行（Job Settlement Line）**:
+后台 job 结算（进入 idle 或终态）时写入 scrollback 的一条记录：首行是身份和状态，⎿ 副行是指标和结果。每种 kind 有自己的模板。固定英文，不跟随界面语言。
+_Avoid_: 完成行（它也用于 idle、stopped、dismissed）, 终态行（idle 不是终态）, job_event（代码里的 entry 类型名）
+
 **Settings Edit Session（设置编辑会话）**:
 从打开设置面板到保留或取消更改的一次编辑过程。更改即时保存；保留操作接受这些更改，取消操作撤销本次仍未被外部再次修改的更改。
 _Avoid_: settings draft（设置草稿）, save-on-close（关闭时才保存）
@@ -81,9 +101,13 @@ The display-only cadence at which complete assistant text lines leave the line-s
 _Avoid_: typewriter effect (that is character-level), throttling (that is the scrollback drain), rate limiting
 
 **Thinking Badge**:
-The short English phrase in the breathing-yellow part of the loading line's status suffix, shown only while the model thinks and thinking display is off. It names the thinking effort that the in-flight request actually uses (the applied level, or ultracode when that switch is on). It is chosen when a request starts to think and does not change until that request ends. When no applied level is known, it shows the neutral word `thinking`. It is a word, not a color: it never takes the effort level colors.
+The short English phrase in the breathing-yellow part of the loading line's status suffix, shown only while the model thinks and thinking display is off. It names the thinking effort that the in-flight request actually uses (the applied level, or ultracode when that switch is on). It is chosen when a request starts to think and does not change until that request ends. When no applied level is known, it shows the neutral word `thinking`. It is a word, not a color: it never takes the effort level colors. When the thinking ends normally, a Thought Duration takes its place.
 _Avoid_: effort badge, hidden thinking label, random thinking word
 
+**Thought Duration**:
+The past-tense counterpart of the Thinking Badge: a short English phrase such as `thought for 8s with high effort` that takes the badge's place in the loading line's status suffix for 3 seconds after a hidden thinking ends normally (at a text or tool call boundary). Each effort level's phrase mirrors that level's badge, and the level is the one frozen when the badge was chosen. The time runs from the request's first thinking delta to that boundary, in whole seconds. It appears only for a thinking that stayed hidden from start to end and lasted at least 1 second; an interrupt, a stream retry, turning thinking display on, or the end of the turn leaves none. It is static faint text, not breathing yellow, because the thinking is over. It never goes to scrollback.
+_Avoid_: thinking time, thinking timer, elapsed thinking badge
+
 **Tool Args Progress**:
 The `↓ N tokens` part of the loading line's status suffix: an estimate of how large the arguments of the tool call the model is still generating have grown so far. It appears only after the arguments pass a visibility threshold, and it can only move when the provider delivers the arguments incrementally; a provider that delivers them in one piece at the end leaves nothing to show. It concerns the main agent's in-flight request only.
 _Avoid_: token 下行状态 (reads as network bytes), download progress, output token counter
@@ -170,6 +194,10 @@ _Avoid_: marketplace url (too narrow), repo (only one of the forms)
 A registered plugin source, named by its own manifest rather than by whatever the user typed. One Marketplace Source resolves to at most one Marketplace, however it is spelled.
 _Avoid_: plugin store, registry (the registry is the collection of Marketplaces)
 
+**Effective Installation**:
+An installed-plugin record that applies to the current project: either a user-scope record, or a local-scope record whose project path is the current project. A local-scope record for another project is not an Effective Installation here, even though it exists in the registry.
+_Avoid_: installed (ambiguous: the registry may hold records that do not apply here), known plugin
+
 ## CLI Self-Update Language
 
 **Self-Update**:
@@ -196,6 +224,10 @@ _Avoid_: symlink swap, shim update, rename dance
 The rule that a completed Self-Update takes effect only for processes started afterwards. Running sessions keep their version until they exit.
 _Avoid_: hot upgrade, live upgrade
 
+**Interpreter Migration**:
+Reinstalling the *same* installed CLI version onto the target Python runtime (3.12, ADR 0055), offered at launch on macOS/Linux when the CLI runs on another interpreter and no newer version is pending. It is not a Self-Update (the version does not change), but it obeys Restart-to-Apply and reuses the in-process reinstall path. It always needs the user's confirmation in the launch prompt, because rebuilding the tool environment can break other running sessions.
+_Avoid_: runtime upgrade, Python update, re-pin
+
 ## Tool Result Display Language
 
 **Tool Result Preview**:
@@ -228,6 +260,32 @@ _Avoid_: discard input (the pre-existing lossy clear), undo (there is no in-plac
 A short-lived hint occupying the status bar's left column, dismissed by timeout or the next real keypress, whichever comes first. It is interaction feedback, not history: it never enters scrollback.
 _Avoid_: toast, notification, system message (that is the scrollback form)
 
+**Loading Tip**:
+The single faint line under the loading spinner while a turn runs (`Tip: …`). Normal tips rotate through a shuffled static pool. A tip changes after 12 s of total on-screen time, or, once it has been on screen for 1 s in total, while it is hidden (for example, while a tool runs), so each gap between tool calls shows a different tip. A one-shot tip tells the user about a state the system already handled (for example, MCP tools now load on demand): it jumps the queue once, counts only after it is actually rendered, and never comes back. No Loading Tip enters scrollback (ADR 0052).
+_Avoid_: hint (overloaded with Transient Status Message), system message (that is the scrollback form)
+
+**System Message**:
+A scrollback entry that comes from the CLI or the SDK, not from the model or a tool, with a severity of info, warning, or error. Warnings that SDK or CLI code logs and the CLI forwards into scrollback are System Messages too.
+_Avoid_: log line, notice (as user-facing words)
+
+## Image Chip Language
+
+**Image Chip（图片 chip）**:
+输入框中代表一张已粘贴图片的字面量 `[Pasted image #k: label]`。它是图片在草稿里的唯一可见形式；编号 `k` 只在输入框内对齐图片，与模型看到的 `[Image #N]` 无关。
+_Avoid_: image placeholder（与长文本折叠占位符 `[Pasted Content N chars]` 混淆）, 图片占位符
+
+**Chip Ledger（chip 账本）**:
+当前草稿中 chip 编号到图片数据的映射。提交时只有字面量仍在文本中的账本条目会随消息发出。
+_Avoid_: image map, 图片缓存
+
+**Orphan Chip（孤儿 chip）**:
+仍在 Chip Ledger 中、但字面量已不在输入框文本里的图片。提交时它被丢弃。
+_Avoid_: dropped placeholder, 丢失的占位符
+
+**Dead Chip Literal（失效 chip 字面量）**:
+格式与 Image Chip 相同、但 Chip Ledger 中没有对应图片的文本，常见于召回的输入历史。它只是文字，不代表图片。
+_Avoid_: 历史图片, stale chip
+
 ## Terminal Tab Language
 
 **Session Title**:
@@ -325,10 +383,13 @@ _Avoid_: lag log, profiler output (the profiler records phase durations, not a s
 
 - A **Marketplace** takes its name from its manifest, never from the **Marketplace Source** the user typed; duplicate detection therefore compares resolved sources, not names or spellings.
 - Adding a **Marketplace** is never silent: the user confirms the **Marketplace Source** once before any clone or download starts, whether the source was typed into the panel or prefilled from a slash command argument.
+- Every plugin panel that reports "installed" (a checkmark, a count, a list of installed plugins) means **Effective Installation** for the current project, and uses the same rule the plugin loader uses to decide what to load. Registry membership alone never counts as installed.
+- Manual plugin update and **Plugin Auto Update** act on a plugin key, not on an **Effective Installation**: every record under that key (the user-scope record and every project's local-scope record) moves to the same version together. Display is per project; update is per plugin. There is no per-project version.
 
 - **Self-Update** and **Plugin Auto Update** are separate concepts with separate vocabularies: a **Version Check** orders versions, plugin **Update Detection** only compares for equality. Neither triggers the other.
 - A **Side-Install** followed by an **Entrypoint Flip** is one Self-Update strategy; an in-process reinstall of the current installation is another. Which one applies is a property of the platform, not of the user's choice.
 - **Restart-to-Apply** holds for every Self-Update strategy and mirrors the plugin **Update Effectiveness Boundary**: on-disk state changes, the running process does not.
+- **Interpreter Migration** and **Self-Update** both rebuild the installation on the target Python, but only a Self-Update changes the version. A pending Self-Update takes priority: accepting it completes the migration as a side effect, so the launch never offers both before the TUI starts. (The background Version Check can still add an update hint inside the TUI after a migration hint or prompt; the next launch then offers only the update.) Windows has no Interpreter Migration (a Side-Install of the same version is treated as already staged); Windows users reach the target Python through their next Self-Update.
 
 - A **Session Title** is a fact of the session, not of the **Session Report**: it exists whether or not a report backend is configured, and the report only mirrors it. **Durable Title Completion** is therefore judged from the session's own metadata.
 - A **Session Title** is generated from the session's earliest **Committed Title Input**, never from the latest one. A resumed session without a title is titled from its original first input, so the title does not change to whatever was typed after resume.
@@ -349,6 +410,10 @@ _Avoid_: lag log, profiler output (the profiler records phase durations, not a s
 - The bottom interaction band shows at most one "working" signal at a time. During a **Stall Status** the loading line carries it and the **Task List Panel** is hidden entirely; when the Stall Status ends, the Task List Panel returns unchanged.
 - Running tools are not a **Stall Status**: the running-tool list and the **Task List Panel** may share the screen.
 
+- No submit path destroys an **Image Chip** it cannot use: a **Core Slash Command**, a **Custom Command**, a **Skill Slash Command**, a feedback draft, or a rejected submit leaves the unused chips and their **Chip Ledger** entries in the input box. Only a plain user message carries images to the model.
+- `!` shell mode never accepts an **Image Chip**: an image paste is refused, and a pasted image path stays plain text.
+- An **Orphan Chip** comes only from the user changing the input text (editing, or recalling input history over the draft); the CLI never creates one by itself. A **Dead Chip Literal** never looks like an **Image Chip** in the input box.
+
 ## Flagged ambiguities
 
 - 代码里的 `_menu_panel_active()` 实际含义是“使用共享 `MenuPanel` 外壳”，不含 `/statusline`、marketplace 安装、`/goal edit`，因此与本术语表的 **Menu Panel**（slash 命令打开的暂态操作界面）并不等价。判断 **Status Bar** 是否隐藏另用独立集合，不复用它。

{comate_cli-0.12.5 → comate_cli-0.12.6b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: comate-cli
-Version: 0.12.5
+Version: 0.12.6b2
 Summary: Comate terminal CLI built on comate-agent-sdk
 Project-URL: Homepage, https://github.com/AndyLee1024/agent-sdk
 Project-URL: Repository, https://github.com/AndyLee1024/agent-sdk
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: <3.14,>=3.11
 Requires-Dist: charset-normalizer==3.4.7
-Requires-Dist: comate-agent-sdk<0.13,>=0.12.21
+Requires-Dist: comate-agent-sdk<0.13,>=0.12.23
 Requires-Dist: comate-rpc<0.2,>=0.1.4
 Requires-Dist: concurrent-log-handler>=0.9.25
 Requires-Dist: curl-cffi==0.13.0

{comate_cli-0.12.5 → comate_cli-0.12.6b2}/comate_cli/main.py

@@ -841,6 +841,11 @@ def main(argv: list[str] | None = None, *, profile=None) -> None:
             sys.stderr.write(f"{exc}\n")
             raise SystemExit(exc.exit_code) from exc
 
+    # 放在 --version / update / mcp 之后：这几条路径不起 TUI，不付 prompt_toolkit 导入开销。
+    from comate_cli.terminal_agent import focus_events
+
+    focus_events.install()
+
     noise_guard = _ShutdownNoiseGuard()
     noise_guard.install()
 
@@ -882,6 +887,8 @@ def main(argv: list[str] | None = None, *, profile=None) -> None:
             sys.stderr.write("Error: -p requires a prompt argument or stdin input\n")
             raise SystemExit(1)
         print_message = "\n\n".join(parts)
+        # 无人值守监视的默认费用护栏；用户配置仍可在 agent 构建时覆盖。
+        os.environ.setdefault("COMATE_MONITOR_MAX_TIMEOUT_MS", "600000")
 
     interactive = not rpc_mode and print_message is None
     if interactive:

{comate_cli-0.12.5 → comate_cli-0.12.6b2}/comate_cli/mcp_cli.py

@@ -4,7 +4,9 @@ import argparse
 import asyncio
 import json
 import logging
+import re
 import sys
+import threading
 from pathlib import Path
 from typing import Any
 
@@ -19,15 +21,21 @@ from comate_agent_sdk.mcp import (
     write_mcp_servers_to_path,
 )
 from comate_agent_sdk.mcp.cwd import format_stdio_cwd_resolution, resolve_stdio_cwd
-from comate_agent_sdk.mcp.types import McpServerConfig
+from comate_agent_sdk.mcp.oauth import McpAuthError, authenticate_server, clear_server_auth
+from comate_agent_sdk.mcp.token_store import TokenStore, server_key
+from comate_agent_sdk.mcp.types import REMOTE_TRANSPORTS, McpServerConfig
 from comate_agent_sdk.utils.paths import PathInput
 
+from comate_cli.terminal_agent.browser_open import open_browser_best_effort
 from comate_cli.terminal_agent.figures import (
     CHECK_MARK,
     CROSS_MARK,
     ELLIPSIS,
+    WARNING_ICON,
 )
 
+logger = logging.getLogger(__name__)
+
 _WRITABLE_SCOPES: tuple[str, ...] = ("user", "project", "local")
 
 
@@ -42,6 +50,16 @@ class _McpArgumentParser(argparse.ArgumentParser):
         raise McpCliError(message)
 
 
+def _add_oauth_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--client-id", dest="client_id", help="OAuth client id (http/sse only)")
+    parser.add_argument(
+        "--client-secret",
+        dest="client_secret",
+        help="OAuth client secret, written to the config as given; prefer ${ENV_VAR}",
+    )
+    parser.add_argument("--callback-port", dest="callback_port", help="Fixed OAuth callback port")
+
+
 def _build_parser(command_name: str = "comate") -> argparse.ArgumentParser:
     parser = _McpArgumentParser(
         prog=f"{command_name} mcp",
@@ -96,9 +114,7 @@ def _build_parser(command_name: str = "comate") -> argparse.ArgumentParser:
         default=False,
         help="Overwrite if server already exists in the same scope",
     )
-    add_parser.add_argument("--client-id", dest="client_id")
-    add_parser.add_argument("--client-secret", action="store_true", default=False)
-    add_parser.add_argument("--callback-port")
+    _add_oauth_arguments(add_parser)
     add_parser.add_argument("name")
     add_parser.add_argument("command_or_url", nargs="?")
 
@@ -116,9 +132,7 @@ def _build_parser(command_name: str = "comate") -> argparse.ArgumentParser:
         default=False,
         help="Overwrite if server already exists in the same scope",
     )
-    add_json_parser.add_argument("--client-id", dest="client_id")
-    add_json_parser.add_argument("--client-secret", action="store_true", default=False)
-    add_json_parser.add_argument("--callback-port")
+    _add_oauth_arguments(add_json_parser)
     add_json_parser.add_argument("name")
     add_json_parser.add_argument("json")
 
@@ -148,6 +162,18 @@ def _build_parser(command_name: str = "comate") -> argparse.ArgumentParser:
         help="Delete from scope; omitted means auto-detect",
     )
 
+    auth_parser = subparsers.add_parser(
+        "auth",
+        help="Authorize a remote (http/sse) MCP server in the browser",
+    )
+    auth_parser.add_argument("name")
+    auth_parser.add_argument(
+        "--clear",
+        action="store_true",
+        default=False,
+        help="Delete the stored credentials of this server",
+    )
+
     serve_parser = subparsers.add_parser(
         "serve",
         help=f"Start {command_name} as an MCP stdio server (tools: query, reply)",
@@ -222,6 +248,10 @@ def _normalize_add_unknown_args(unknown: list[str]) -> list[str]:
     return list(unknown)
 
 
+def _looks_like_url(token: str) -> bool:
+    return token.strip().lower().startswith(("http://", "https://"))
+
+
 def _split_add_args(argv: list[str]) -> tuple[list[str], list[str]]:
     if not argv or argv[0] != "add":
         return list(argv), []
@@ -249,35 +279,21 @@ def _split_add_args(argv: list[str]) -> tuple[list[str], list[str]]:
         "-e",
         "--env",
         "--client-id",
+        "--client-secret",
         "--callback-port",
     }
-    flag_options = {"--force", "--client-secret"}
-    remote_tail_value_options = {"-H", "--header", "--client-id", "--callback-port"}
-    remote_tail_flag_options = {"--client-secret"}
+    flag_options = {"--force"}
     transport = "stdio"
 
     index = 0
     while index < len(before_separator):
         token = before_separator[index]
         if positional_count >= 2:
-            if transport in {"http", "sse"} and token in remote_tail_value_options:
-                option_args.append(token)
-                if index + 1 < len(before_separator):
-                    option_args.append(before_separator[index + 1])
-                index += 2
-                continue
-            if transport in {"http", "sse"} and token in remote_tail_flag_options:
-                option_args.append(token)
-                index += 1
-                continue
-            if transport in {"http", "sse"} and any(
-                token.startswith(f"{option}=")
-                for option in remote_tail_value_options
-                if option.startswith("--")
-            ):
-                option_args.append(token)
-                index += 1
-                continue
+            # 远程 server 没有子进程参数：URL 后的 token 全部交给 argparse，
+            # 选项顺序不影响结果，未知 token 由 argparse 点名报错（ADR 0054）。
+            if transport in {"http", "sse"} or _looks_like_url(positional_args[1]):
+                remote_tail = before_separator[index:]
+                return ["add", *option_args, *positional_args, *remote_tail], after_separator
             extra_args.extend(before_separator[index:])
             break
 
@@ -323,15 +339,7 @@ def _build_add_server_config(
     command_or_url = str(args.command_or_url or "").strip()
     remainder = [str(item) for item in list(getattr(args, "extra_args", []) or [])]
 
-    if (
-        getattr(args, "client_id", None)
-        or bool(getattr(args, "client_secret", False))
-        or getattr(args, "callback_port", None)
-    ):
-        raise McpCliError(
-            f"OAuth flags are not supported by {command_name} mcp add yet. "
-            "Use headers for token-based HTTP/SSE MCP servers, or add a native oauth object via .mcp.json."
-        )
+    oauth = _oauth_from_flags(args)
 
     if transport in {"http", "sse"}:
         if env_entries:
@@ -347,8 +355,12 @@ def _build_add_server_config(
         }
         if headers:
             cfg["headers"] = headers
+        if oauth:
+            cfg["oauth"] = oauth
         return cfg  # type: ignore[return-value]
 
+    if oauth:
+        raise McpCliError(_OAUTH_FLAGS_REMOTE_ONLY)
     if header_entries:
         raise McpCliError("--header is only supported for http/sse transport")
     stdio_args = list(remainder)
@@ -356,6 +368,10 @@ def _build_add_server_config(
         command_or_url = stdio_args.pop(0)
     if not command_or_url:
         raise McpCliError("stdio transport requires command after <name>")
+    if _looks_like_url(command_or_url):
+        raise McpCliError(
+            f"'{command_or_url}' looks like a remote URL; add --transport http or --transport sse"
+        )
 
     env = _parse_env_entries(env_entries)
     cfg = {
@@ -369,12 +385,32 @@ def _build_add_server_config(
     return cfg  # type: ignore[return-value]
 
 
-def _has_oauth_flags(args: argparse.Namespace) -> bool:
-    return bool(
-        getattr(args, "client_id", None)
-        or bool(getattr(args, "client_secret", False))
-        or getattr(args, "callback_port", None)
-    )
+_OAUTH_FLAGS_REMOTE_ONLY = "--client-id/--client-secret/--callback-port are only supported for http/sse transport"
+
+_ENV_REFERENCE_RE = re.compile(r"^\$\{[A-Za-z_][A-Za-z0-9_]*\}$")
+
+
+def _oauth_from_flags(args: argparse.Namespace) -> dict[str, Any]:
+    """把 OAuth flag 转成配置里的 `oauth` 对象；没有 flag 时返回空 dict。"""
+    oauth: dict[str, Any] = {}
+    client_id = getattr(args, "client_id", None)
+    if client_id is not None:
+        oauth["client_id"] = str(client_id)
+    client_secret = getattr(args, "client_secret", None)
+    if client_secret is not None:
+        oauth["client_secret"] = str(client_secret)
+        if not _ENV_REFERENCE_RE.match(str(client_secret)):
+            sys.stderr.write(
+                f"{WARNING_ICON} --client-secret is stored in the config file as plain text; "
+                "consider an environment variable reference such as '${MY_CLIENT_SECRET}'.\n"
+            )
+    callback_port = getattr(args, "callback_port", None)
+    if callback_port is not None:
+        try:
+            oauth["callback_port"] = int(str(callback_port))
+        except ValueError:
+            raise McpCliError(f"Invalid --callback-port value: {callback_port!r}") from None
+    return oauth
 
 
 def _load_servers_by_scope(*, scope: str, project_root: PathInput | None) -> dict[str, McpServerConfig]:
@@ -402,6 +438,8 @@ def _render_health_status(
         return f"{CHECK_MARK} Connected"
     if normalized == "connecting":
         return f"{ELLIPSIS} Connecting"
+    if normalized == "needs-auth":
+        return f"{WARNING_ICON} Needs authentication"
     if reason:
         return f"{CROSS_MARK} {reason}"
     return f"{CROSS_MARK} Not connected"
@@ -488,6 +526,9 @@ def _cmd_add(
         raise McpCliError("Server name cannot be empty")
 
     config = _build_add_server_config(args, command_name=command_name)
+    if "oauth" in config:
+        target_path = scope_mcp_path(scope=scope, project_root=project_root)  # type: ignore[arg-type]
+        config = validate_server_config(alias=name, cfg=dict(config), path=target_path)
     path, existed = _write_server_to_scope(
         name=name,
         config=config,
@@ -508,12 +549,6 @@ def _cmd_add_json(
     project_root: PathInput | None,
     command_name: str = "comate",
 ) -> None:
-    if _has_oauth_flags(args):
-        raise McpCliError(
-            f"OAuth flags are not supported by {command_name} mcp add-json yet. "
-            "Use headers for token-based HTTP/SSE MCP servers, or add a native oauth object via .mcp.json."
-        )
-
     scope = str(args.scope)
     name = str(args.name).strip()
     if not name:
@@ -525,6 +560,12 @@ def _cmd_add_json(
         raise McpCliError(f"Invalid JSON: {exc}") from exc
     if not isinstance(raw, dict):
         raise McpCliError("MCP server JSON must be an object")
+    oauth = _oauth_from_flags(args)
+    if oauth:
+        if str(raw.get("type") or "stdio").strip().lower() not in REMOTE_TRANSPORTS:
+            raise McpCliError(_OAUTH_FLAGS_REMOTE_ONLY)
+        existing = raw.get("oauth")
+        raw["oauth"] = {**(existing if isinstance(existing, dict) else {}), **oauth}
 
     target_path = scope_mcp_path(scope=scope, project_root=project_root)  # type: ignore[arg-type]
     config = validate_server_config(alias=name, cfg=raw, path=target_path)
@@ -582,14 +623,105 @@ def _cmd_remove(
             exit_code=1,
         )
 
-    servers.pop(name, None)
+    removed = servers.pop(name, None)
     path = scope_mcp_path(scope=scope, project_root=project_root)  # type: ignore[arg-type]
     write_mcp_servers_to_path(path=path, servers=servers)
+    if isinstance(removed, dict) and str(removed.get("type", "stdio")).strip().lower() in REMOTE_TRANSPORTS:
+        # 删除 server 不应在本机留下它的凭据；delete 同时去掉"已清除"标记
+        TokenStore().delete(server_key(name, dict(removed)))
     sys.stdout.write(
         f"Removed MCP server '{name}' from {scope} scope: {path.expanduser()}\n"
     )
 
 
+def _resolve_remote_server(name: str, *, project_root: PathInput | None) -> dict[str, Any]:
+    resolved = _read_effective_server_with_source(name=name, project_root=project_root)
+    if resolved is None:
+        raise McpCliError(f"MCP server '{name}' not found.", exit_code=1)
+    cfg = dict(resolved[0])
+    server_type = str(cfg.get("type", "stdio")).strip().lower()
+    if server_type not in REMOTE_TRANSPORTS:
+        raise McpCliError(
+            f"MCP server '{name}' uses {server_type} transport; only http/sse servers support authorization.",
+            exit_code=1,
+        )
+    return cfg
+
+
+def _read_pasted_callback(loop: asyncio.AbstractEventLoop, pasted: asyncio.Future[str]) -> None:
+    """后台读 stdin 的第一行非空输入作为回调 URL。
+
+    用 daemon 线程而不是 `asyncio.to_thread`：浏览器回调先到时，阻塞在 readline 的线程无法取消，
+    `asyncio.run` 退出时会等默认线程池里的线程，命令就卡住不退出。
+    """
+
+    def _resolve(line: str) -> None:
+        if not pasted.done():
+            pasted.set_result(line)
+
+    def _read() -> None:
+        try:
+            for line in sys.stdin:
+                if line.strip():
+                    loop.call_soon_threadsafe(_resolve, line.strip())
+                    return
+        except (OSError, ValueError, RuntimeError):
+            # stdin 关闭或 loop 已结束：只剩浏览器回调这一条路
+            return
+
+    threading.Thread(target=_read, name="mcp-auth-stdin", daemon=True).start()
+
+
+def _show_authorization_url(name: str, url: str) -> None:
+    sys.stdout.write(
+        f"Authorize '{name}' in your browser:\n\n  {url}\n\n"
+        "If the browser cannot reach this machine (e.g. over SSH), paste the full callback URL "
+        "from the browser address bar here and press Enter.\n"
+    )
+    sys.stdout.flush()
+    # 尽力而为，失败时用户照样可以手动打开上面的 URL。没有图形界面（SSH）不打开，避免 w3m / lynx
+    # 抢走终端、用户没法粘贴回调 URL；打开放在 daemon 线程里，不阻塞等回调的 event loop。
+    open_browser_best_effort(url)
+
+
+async def _authenticate(name: str, cfg: dict[str, Any], token_store: TokenStore) -> None:
+    loop = asyncio.get_running_loop()
+    pasted: asyncio.Future[str] = loop.create_future()
+    _read_pasted_callback(loop, pasted)
+    await authenticate_server(
+        name,
+        cfg,
+        token_store=token_store,
+        on_authorization_url=lambda url: _show_authorization_url(name, url),
+        manual_callback=pasted,
+    )
+
+
+def _cmd_auth(args: argparse.Namespace, *, project_root: PathInput | None) -> None:
+    name = str(args.name).strip()
+    if not name:
+        raise McpCliError("Server name cannot be empty")
+    cfg = _resolve_remote_server(name, project_root=project_root)
+    token_store = TokenStore()
+
+    if args.clear:
+        clear_server_auth(name, cfg, token_store=token_store)
+        sys.stdout.write(f"Cleared authorization for '{name}'.\n")
+        return
+
+    try:
+        asyncio.run(_authenticate(name, cfg, token_store))
+    except KeyboardInterrupt:
+        raise McpCliError("Authorization cancelled.", exit_code=130) from None
+    except McpAuthError as exc:
+        raise McpCliError(str(exc), exit_code=1) from exc
+    sys.stdout.write(
+        f"Authenticated '{name}'.\n"
+        "A running comate session does not reconnect by itself: "
+        "press Reconnect in /mcp, or start a new session.\n"
+    )
+
+
 def _cmd_serve(args: Any, *, project_root: PathInput | None = None) -> None:
     # stdout 是 MCP stdio 协议通道：日志强制落 stderr
     logging.basicConfig(level=logging.INFO, stream=sys.stderr, force=True)
@@ -696,6 +828,14 @@ def _cmd_get(
             lines.append("  Headers:")
             for key in sorted(headers.keys()):
                 lines.append(f"    {key}: {headers[key]}")
+        oauth = cfg.get("oauth") or {}  # type: ignore[attr-defined]
+        oauth_parts: list[str] = []
+        if isinstance(oauth, dict) and oauth.get("client_id"):
+            oauth_parts.append("client_id configured")
+        if isinstance(oauth, dict) and oauth.get("callback_port") is not None:
+            oauth_parts.append(f"callback_port {oauth['callback_port']}")
+        if oauth_parts:
+            lines.append(f"  OAuth: {', '.join(oauth_parts)}")
     else:
         lines.append(f"  Command: {str(cfg.get('command', '')).strip()}")  # type: ignore[attr-defined]
         raw_args = cfg.get("args") or []  # type: ignore[attr-defined]
@@ -746,6 +886,7 @@ def run_mcp_command(
         "list": _cmd_list,
         "get": _cmd_get,
         "remove": _cmd_remove,
+        "auth": _cmd_auth,
         "serve": _cmd_serve,
     }
     handler = handlers.get(command)