comate-cli 0.12.3__tar.gz → 0.12.4__tar.gz

{comate_cli-0.12.3 → comate_cli-0.12.4}/CHANGELOG.md

@@ -4,6 +4,51 @@
 
 ### Added
 
+- 规则双目录（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 会忽略这个字段并加载全部工具。
+- `/mcp` 工具列表可按工具启用 / 停用：每行前显示 `[x]`（启用）/ `[ ]`（停用），停用的工具仍留在列表里；Space 切换当前行并立刻写回该 server 所在层的 `.mcp.json`（`disabled_tools` 字段），不重连任何 server，下一次模型请求生效，agent 忙碌时也可切换；Enter 仍进工具详情，详情页多一行启用 / 停用状态。存盘失败时勾选不变，菜单里显示一行错误。server 详情页有停用时显示 `Tools: 5 / 40 tools`，整台 Enable 后的「tools loaded」只数启用的工具；一台 server 的工具全部停用后 `View tools` 入口仍在，可以进去重新启用。新文案三语齐全。comate-cli 的 `comate-agent-sdk` 下限抬到 0.12.15（SDK 同步升版）。
+- 空闲修剪提示与开关：SDK 使用方升级后默认启用空闲修剪（会话空闲超 3 小时后，新一轮发出前把较早的 Read / Bash 等可重取工具结果换成占位符，少付缓存已凉后的全价重读），可用 `AgentConfig(idle_pruning=False)` 关闭；CLI 用户可在 settings.json 顶层写 `"idle_pruning": false` 关闭（不写 = 开，三层合并）。修剪真的发生时终端显示一行「已清理 N 条较早的工具结果，约省 X tokens（空闲 H 小时）」，模型随后重读文件不再是莫名其妙的动作；resume 后已清理条目保持占位符，不重复修剪、不重复提示。
+- `--system-prompt <文本>` / `--system-prompt-file <路径>`：用自己的文字替换 system prompt 的开头段（agent 是谁、怎么干活）；`--append-system-prompt <文本>` / `--append-system-prompt-file <路径>`：在护栏之后追加。参数名对齐 Claude Code，但与 Claude Code 不同的是护栏段（运行环境说明、工作纪律、危险操作确认、汇报规范等）始终保留。替换与追加可同时使用；同类的文本版与文件版同时给、值为空、文件读不了或为空都会当场退出并按界面语言提示。`--rpc-*` 与 `-p` 同样生效，一个进程下所有新会话共用；resume 旧会话时沿用会话创建时的 system prompt，界面会给出提示，`/clear` 后生效。白牌 `system_role` 语义不变：只换品牌身份句，编码规则保留。
+- ctrl+b 把正在前台跑的 shell 命令转到后台：对模型调用的 Bash 工具和 `!` 本地命令都生效。同一个进程原样移交给后台 job（不重启不杀），模型 Bash 的工具结果立刻回「用户已转后台 + job_id + 输出尾部」让模型继续本轮；`!` 命令静默记一条 reminder、解锁输入框。后台跑完走既有 job 完成通知叫模型；想停用 `/ps`。运行面板与 `!` 活动区在 Bash 跑时显示「ctrl+b 转后台」提示，`/help` 多一行说明。没有可转后台的命令时按键只闪一条提示；子 agent 里的 Bash 不受影响。tmux 用户需按两次 ctrl+b。
+- `!` shell 模式：空输入框敲 `!` 进入 shell 模式，回车后命令在本地直接执行（跳过权限审批、与模型共享持久 cwd），滚动区显示 `! cmd` + 紧贴其下的 `⎿` 输出块（stderr 红、stdout 不红、空输出标 `(No output)`、控制码剥净、长输出截断可 Ctrl+O 看全文）。命令结束后模型自动简短回应一轮；运行期间敲的提问并入同一轮。运行中锚点下方实时显示最后 5 行输出与耗时；超过 60 秒自动转后台并解锁输入框，后台跑完再叫模型；Esc/Ctrl+C 中断不叫模型并把命令回填到输入框。忙时 `!cmd` 排队，回合结束后按顺序执行。
+- 代码托管平台整合第一刀（提示词层）：`<git_env>` 新增 `Main branch:`（PR/MR 的 base 分支）与
+  `Remote:`（github.com → 用 `gh`，gitlab.com → 用 `glab`；企业自建实例靠 settings `scm.hosts`
+  映射）两行；Bash 工具规则新增「Pull requests and merge requests」段，gh 与 glab 写法并列。
+  发行版署名进 `<git_env>` 的 `Attribution:` 段（commit trailer `Co-Authored-By: <产品名>` 与
+  PR/MR 尾注 `🤖 Generated with <产品名>`），`DistributionProfile` 新增 `product_url` /
+  `attribution_email`，settings `scm.attribution=false` 可关。Bash 子进程默认注入
+  `GIT_EDITOR=true` 与 `GH_PROMPT_DISABLED=1`（用户自设值优先），git/gh 不再可能挂在交互提示上。
+- 代码托管平台整合第二刀（只读放行开关）：settings `scm.readonly_cli=true` 时，`gh` / `glab` 的
+  最小只读子命令集（查看/列出 PR、MR、issue、CI run、release，`auth status`）进入 Bash 自动放行，
+  不再每条弹确认；默认关。开了也守得严：`--repo` 指向别的仓库、URL 位置参数、`--web`、
+  `--show-token`、`--hostname`、`--watch`、`--jq`（jq 内建能读环境变量）、`api` / `search` / `secret`
+  与一切写形态仍然询问。
+- 代码托管平台整合第三刀（slash 命令）：随包新增 `/commit [focus or message hint]` 与
+  `/open-pr [title hint]`（别名 `/open-mr`）。两者是 default scope 的 markdown 命令，模板先预执行
+  `git status` / `git diff --stat` / `git log` 把上下文塞进提示词，模型再按 Bash 工具的 git 纪律
+  与 PR/MR 流程执行；`/open-pr` 会先提交未提交的改动、`git push -u`，再按 `<git_env>` 的 `Remote:`
+  选 `gh` 或 `glab` 开（或更新）请求并回 URL。创建请求那一步走正常权限确认，不临时放行。
+  自定义命令 frontmatter 新增 `aliases:`，按 project > user > default 分配；project/user 命令的别名
+  撞上已占用名字时提示一次，随包命令的别名被高优先级命令盖掉时静默（覆盖语义）。
+- 代码托管平台整合第四刀（状态栏）：`/statusline` 新增第 15 项「PR / MR Status」，默认关。开了之后
+  每轮结束在后台探测当前分支的 PR / MR（GitHub 走 `gh pr view --json`，GitLab 走
+  `glab api projects/:id/merge_requests`），60 秒缓存，状态栏只读缓存不等探测；显示
+  `PR #12 ✓` / `✗` / `·` / `draft`、`MR !45`（GitLab 只区分 draft）。默认分支上不探测，没有请求不显示；
+  gh / glab 没装或没登录在状态栏左侧提示一次后本会话停用，连续两次探测超过 4 秒或任一次超时也停用；
+  退出时进行中的探测被取消并 kill 子进程。
+- 输入框裸词 `ultracode`：普通消息里按空白切出的整词 `ultracode`（不分大小写；紧贴标点 / 引号 /
+  括号、带空格写法都不算）在输入框里显示为深紫流光（与 `/effort` 刻度尺 ultracode 格同色），发送那一刻等价于 `/effort ultracode`
+  但只改本会话、不写 settings（忙时也立即翻开关）；发行版配了 `ultracode_notice` 时先弹确认框，
+  取消则消息留在输入框；这个词保留在发给模型的消息里，scrollback 回显静态染紫。
+- ultracode 的 SDK 侧含义升级为「Workflow 激活点 + 不计成本的探索发现」：开着时 Workflow 预算放宽，
+  内层 agent 带「宁可多读，不要早停」前言，探索产出约定落 `.scratch/<feature>/research/`。
+- Workflow 预算分两档：普通档收紧为并发 4 / 每跑 20 次 agent 调用（有意克制，教材 Scale 表
+  随之改为 ≤5 / ≤10 / ≤16），ultracode 档放宽为并发 10 / 每跑 100 次；单 agent 超时两档都不变。
+- Workflow 唤起改为提示词约束：ultracode 关着时模型不主动起 workflow，只在用户用自己的话要了
+  （如 workflow / 工作流 / 编排 / 动态工作流）或明确同意模型的建议时才起；代码层不再按用户文字
+  判定拒绝，只靠预算上限兜底。
+
 - assistant 正文刷入终端改为按行节拍：整行按固定间隔进入底部暂存窗，不再模型吐多快
   屏幕刷多快。默认每行 500 毫秒；空行不占间隔；积压越多放得越快（每 20 行加一倍速，最快 4 倍），
   永远不一次性倒出；
@@ -16,16 +61,48 @@
   支持的终端（VS Code 2025-12 起、Windows Terminal、iTerm2、kitty、WezTerm、Alacritty、
   Ghostty）整帧上屏，底部带 6fps 重画与暂存窗逐行变化不再闪烁；不支持的终端忽略该
   私有模式。只在 POSIX 真 tty 上启用，`COMATE_CLI_NO_SYNC_OUTPUT=1` 可关闭。
+- 首启向导新增 GMI Cloud 预设（SDK `PROVIDER_PRESETS`，id `gmi_cloud`）：OpenAI 协议，
+  端点 `https://api.gmi-serving.com/v1`，LOW 用 `Qwen/Qwen3.8-27B`，MID / HIGH 用
+  `Qwen/Qwen3.8-Max`。该端点还没有方言映射，effort / thinking 参数暂按默认 openai 行为发送，
+  见 `docs/issues/2026-10-09-gmi-cloud-dialect/`。
 
 ### Changed
 
+- 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 后下一次请求即生效。颜色、位置、出现时机不变；短语在中文 / 日文界面下也保持英文。
+- 常驻规则进置顶区（SDK）：规则目录（`~/.agent/rules`、`~/.claude/rules`、项目 `.agent/rules`、`.claude/rules`）里没有有效 `paths:` 的文件——没有 frontmatter、frontmatter YAML 写坏、`paths` 只写了 `**` 之类全匹配——不再被丢弃，而是像 Claude Code 一样启动就加载，和 AGENTS.md 一起常驻。顺序：用户 AGENTS.md → 用户层常驻规则 → 项目 AGENTS.md 链 → 项目层常驻规则（同层 `.agent` 先、`.claude` 后）。进模型的是剥掉 frontmatter 和 HTML 注释后的正文；置顶区文件清单带上每条规则的路径与 token 数；compact、`/clear`、resume 后仍在。user 层受 user setting source 门控，项目层受 project 门控；计入置顶区既有的 token 告警阈值，不截断。**行为变更**：`.agent/rules` 下以前被静默丢弃的无 `paths` 文件从本版起生效。
+- 首启向导（Provider setup）整体重做，照 `/effort` 刻度尺模式改为自绘组件 `preflight_wizard_ui.WizardScreenUI`，不再借用共用的 `SelectionMenuUI`：六屏统一「标题 / 空行 / 内容 / 空行 / 键位提示」顶部对齐骨架；选项行改为 `❯ label` 无圆点、项间不留空行；provider 屏只在选中项下方显示一行 preset 说明；API key / endpoint / 模型名输入屏去掉边框；确认屏的 JSON 预览改为对齐缩进的静态块；键位提示只写真正绑定的键（去掉并不存在的 k/j）。其它菜单不受影响。
+- `/effort` 的 `ultracode` 改绑 `max` 档（原 `xhigh`）：选 ultracode = 最高思考档 + workflows
+  多 agent 编排；`/effort max` 或 `auto` 关开关，`xhigh` 变回普通档。刻度尺描述改为
+  「max + workflows」。
+- 不支持 effort 的模型上开 ultracode，结果行不再只说「当前模型不支持 effort，设置已保存但
+  不会发送」——workflows 那一半其实已经开了。现在分开说「ultracode 已开启」和「max 已保存
+  但不会发送」；刻度尺 ultracode 格附注同步改为「思考力度不生效，仅 workflows」，
+  不再套用普通档位的「该模型不支持」。
 - 新版本提示统一指向 `comate update`：macOS/Linux 的启动一行提示与全屏弹窗「立即更新」
   标签不再展示 `uv tool install …` 长串（与 Windows 对齐），措辞改为「退出后运行」；
   更新失败的兜底文案仍保留完整 uv 修复命令。源码 editable 安装下自更新必然被拒，
   启动检测与第二次启动弹窗两个入口现在直接静音；PATH 缺 uv 不静音。
+- compact 期间底部 loading 文案由 `Compacting context...`（三个半角点）改为
+  `Compacting context…`（单个省略号字符）：与 `Running…` 等其它进行时状态词、
+  以及设计稿 docs/superpowers/specs/2026-05-18-auto-compact-awareness-design.md
+  已写的写法对齐，少占两列宽。
 
 ### Fixed
 
+- `comate update` 在依赖包刚发布时解析失败：更新命令只刷新 CLI 自身的索引缓存，
+  依赖（如 `comate-agent-sdk`）仍用旧缓存，uv 报 `No solution found`。macOS/Linux
+  进程内更新与 Windows 分阶段安装现在都改用 `uv tool install --refresh`，刷新全部
+  缓存后再解析。Windows 手动修复命令本来带 `--reinstall`（隐含 `--refresh`），
+  不受影响。旧版本用户可先运行 `uv cache clean comate-agent-sdk`，或手动执行
+  `uv tool install comate-cli==<版本> --force --refresh-package comate-cli
+  --refresh-package comate-agent-sdk`。
+- macOS 11/12 上 `uv tool install comate-cli` 失败（`pypdfium2-5.13.0-py3-none-macosx_13_0_arm64.whl is not compatible`）：
+  SDK 依赖的 pypdfium2 从 5.12 起只出 macOS 13+ 的安装包，老系统上 uv 退回源码编译，编出来仍是
+  macOS 13 的包，装不上；和 Python 版本无关。comate-agent-sdk 0.12.10 把它限制在 `<5.10`（5.9.0 支持
+  macOS 11+），已发布的 CLI 重装即可拿到修复。SDK 新增测试检查锁定依赖在 macOS 11 arm64 上都有现成安装包。
+- 首启向导在矮终端里 provider 列表被裁掉、光标移到看不见的项上仍可回车的问题：旧实现写死 `page_size=10`（公版已有 12 个 preset）且选项窗不滚动。现在内容区按终端高度自适应、按行滚动、选中项永远可见，`Showing a-b/n` 只报真正画出来的项；极矮终端按「空行 → 提示 → 标题」顺序让步，至少保住 3 行选项。
 - assistant 正文在底部暂存窗比刷进 scrollback 后更亮：scrollback 正文自 2026-07-07 起不上前景色、
   跟随终端默认色，而暂存窗仍钦定近白 `#F1F4F8`，两边分家；且行内代码之后的字被 Rich 的
   恢复默认色指令拉回终端默认，同一行两档亮度。现在暂存窗正文同样交给终端默认前景色

{comate_cli-0.12.3 → comate_cli-0.12.4}/CONTEXT.md

@@ -1,6 +1,20 @@
 # Comate CLI Domain Model
 
-Canonical language for Comate CLI command discovery, transient terminal display, session reporting boundaries, and plugin auto update.
+Canonical language for Comate CLI command discovery, slash input completion, menu panels, transient terminal display, session reporting boundaries, and plugin auto update.
+
+## Menu Panel Language
+
+**Menu Panel（菜单面板）**:
+由 slash 命令打开的暂态操作界面。多个菜单使用一致的视觉与导航规则，关闭后返回对话输入。Menu Panel 打开期间，Status Bar 不显示。
+_Avoid_: menu output（菜单输出）, history block（历史块）
+
+**Status Bar（状态栏）**:
+底部交互带最下方的一行。左列显示 Transient Status Message，没有消息时显示权限模式提示；右列显示会话信息（模型、分支、上下文余量等）。Menu Panel 打开期间隐藏；工具审批、向用户提问、退出确认不属于 Menu Panel，不隐藏它。
+_Avoid_: footer（Menu Panel 自己有页脚）, bottom toolbar（prompt_toolkit 的术语，本项目不使用）, 补全状态行（与 Status Bar 共用同一个位置，但是另一个东西）
+
+**Settings Edit Session（设置编辑会话）**:
+从打开设置面板到保留或取消更改的一次编辑过程。更改即时保存；保留操作接受这些更改，取消操作撤销本次仍未被外部再次修改的更改。
+_Avoid_: settings draft（设置草稿）, save-on-close（关闭时才保存）
 
 ## Slash Command Language
 
@@ -9,20 +23,48 @@ A slash command backed by a hardcoded Python handler registered in `SLASH_COMMAN
 _Avoid_: builtin command (ambiguous), native command
 
 **Default Custom Command**:
-A markdown-resource slash command shipped inside the `comate_cli` package under `terminal_agent/builtin_commands/`. Loaded via the custom-command pipeline (frontmatter + template), with `source_scope = "default"` on the *source* axis. User-authored custom commands of the same name override it.
+A markdown-resource slash command shipped inside the `comate_cli` package under `terminal_agent/builtin_commands/`. Loaded via the custom-command pipeline (frontmatter + template), with `source_scope = "default"` on the *source* axis. User-authored custom commands and Skill Slash Commands of the same name override it. A command may declare `aliases:` in its frontmatter (e.g. `/open-pr` → `/open-mr`). Aliases are assigned in scope priority order (`project > user > default`); an alias that is already taken (Core Slash Command name, another command's name, or a higher-priority alias) is dropped — silently for Default Custom Commands (override semantics), with a one-time warning for project/user commands, and as a startup error when a Default Custom Command alias would shadow a Core Slash Command.
 _Avoid_: builtin command (ambiguous), bundled command
 
 **Execution Axis** (`SlashCommandSource`):
 Describes how a registered command is dispatched. Values: `"builtin"` (hardcoded handler), `"custom"` (markdown template render), `"skill"` (skill slash). Orthogonal to the Source Axis.
 
+**Skill Slash Command**:
+The slash entry of a runtime skill that is enabled and user-invocable. Its name is the skill's call name; plugin skills carry a `namespace:` prefix and so never collide with plain names. A skill that is disabled or declares `user-invocable: false` has no slash entry and claims no name. When its name is shadowed by a higher-priority command, the skill stays callable by the model through the Skill tool; only the slash entry is lost, and the user is told once per name per process.
+_Avoid_: skill command (ambiguous with custom command)
+
+**Skill Slash Mention**:
+A complete call name of a model-visible skill appearing in prose with a valid whitespace/punctuation boundary before and after. A mention is the authorization fact that drives the model-visible reminder injection and, together with Inline Skill Invocation, the in-prose highlight; a typing-in-progress prefix is never a mention.
+_Avoid_: slash reference, skill authorization (names the effect), partial mention
+
+**Inline Skill Invocation**:
+A complete call name of a user-only skill (user-invocable, `disable-model-invocation: true`) appearing in prose with the same boundaries as a Skill Slash Mention. The system loads that skill's prompt into the user's turn right after the user's text, the way a Head Slash call does; it never authorizes the model.
+_Avoid_: inline slash command, middle slash invocation, mention (names the authorization path)
+
+**Skill Slash Token**:
+The incomplete slash-prefixed fragment at the cursor while typing: the slash plus the name characters typed so far, whitespace-free. The raw material of middle skill completion. It becomes a Skill Slash Mention only when the typed characters are the complete call name.
+_Avoid_: partial mention, prefix mention
+
+**Head Slash / Middle Slash**:
+The two position classes of a Skill Slash Token in the input box. Head Slash: the whole buffer is one token — the head command menu's territory, matched by subsequence fuzzy completion. Middle Slash: a token after a whitespace boundary inside the buffer — the middle skill completion's territory, matched by Trailing Segment Match. A slash at the start of a later line is a Middle Slash; only buffer position zero is Head.
+_Avoid_: 行首/中段 as canonical terms, line-initial slash (wrong for later lines), in-prose slash
+
+**Trailing Segment Match**:
+The matching semantics of middle skill completion: a Skill Slash Command matches when its full name, or the segment after its last namespace colon, starts with the typed name characters case-insensitively. `/grill` matches `mattpocock-skills:grilling` via its trailing segment. Mention judgment never follows this relaxation.
+_Avoid_: substring match, fuzzy match (the head menu's semantics)
+
+**Middle Slash Preview**:
+The gray text after a Middle Slash token at the end of the input: the remaining characters of the chosen Skill Slash Command's name, or of its trailing segment when it matches through that segment alone. It is display-only; only Tab acts on it, and Tab always writes the full slash name.
+_Avoid_: ghost text, inline suggestion, 灰字建议
+
 **Source Axis** (`CustomSlashCommand.source_scope`):
 Describes where a markdown-template command's definition lives. Values: `"project"`, `"user"`, `"plugin"`, `"default"`. Determines override priority only.
 
 **Reserved Name Set** (`builtin_names`):
-The set of names derived from `SLASH_COMMAND_SPECS` (Core Slash Commands) that user-authored custom commands may not shadow. A custom command whose name collides with this set is silently skipped with a warning during discovery. **Default Custom Command names do NOT belong to this set** — they are overrideable by design.
+The set of names derived from `SLASH_COMMAND_SPECS` (Core Slash Commands) that user-authored custom commands and Skill Slash Commands may not shadow. A custom command whose name collides with this set is silently skipped with a warning during discovery. **Default Custom Command names do NOT belong to this set** — they are overrideable by design.
 
 **Override Priority Chain**:
-`project > user > default` (plus `plugin` registered independently at runtime). When a Default Custom Command and a user/project custom command share a name, the higher-priority scope wins silently (no warning); only the winning entry reaches the registry.
+Core Slash Command > project custom > user custom > Skill Slash Command > Default Custom Command (plus namespaced `plugin` commands registered independently at runtime). Core Slash Commands are the Reserved Name Set and are never shadowed. A user-authored custom command beats a Skill Slash Command of the same name, and the user is told once. A Default Custom Command yields silently to any higher-priority entry, including a skill that takes only one of its aliases; it keeps its other names and comes back as soon as the shadowing skill is disabled or removed. Only the winning entry reaches the registry. Skills outrank Default Custom Commands on purpose (ADR-0038).
 
 ## Streaming Display Language
 
@@ -38,6 +80,18 @@ _Avoid_: Markdown parsing, lexer detection
 The display-only cadence at which complete assistant text lines leave the line-split pipeline and enter the stream staging window: one line per fixed interval, blank lines free, and a backlog that speeds the cadence up smoothly (one extra multiple per 20 pending lines, capped at 4x) but never dumps everything at once. It never delays thinking lines, tool entries, or scrollback commits of already staged content, and it holds nothing that ContextIR or the transcript depend on.
 _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.
+_Avoid_: effort badge, hidden thinking label, random thinking word
+
+**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
+
+**Buffered Tool Args**:
+A provider behavior in which a streaming response holds back a tool call's name and arguments and delivers them in one piece at the end, instead of incrementally as they are generated. While it lasts, nothing tells the CLI that a tool call has begun, so Tool Args Progress cannot appear. Some endpoints buffer by default and stream incrementally only when the request opts in.
+_Avoid_: 攒包, non-streaming tool call (the response is still a stream)
+
 **Immutable Scrollback Commit**:
 The point at which staged terminal output is appended to terminal scrollback and can no longer be replaced. An open Streaming Markdown Container remains transient until its closing boundary or a normal turn boundary makes it complete.
 _Avoid_: history render, live Markdown rerender
@@ -106,6 +160,16 @@ _Avoid_: auto update enablement (inverted semantics), plugin pin (no version pin
 The invariant that an update changes only on-disk plugin state. The running session keeps its already-loaded resources until the next startup or an explicit user reload. A background update therefore never shifts agent behavior mid-session.
 _Avoid_: hot reload, live update
 
+## Plugin Marketplace Language
+
+**Marketplace Source**:
+The coordinate a user types to reach a marketplace: a GitHub `owner/repo` shorthand, a git URL (https or ssh), or a direct `marketplace.json` URL. It is only an address; it carries no name.
+_Avoid_: marketplace url (too narrow), repo (only one of the forms)
+
+**Marketplace**:
+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)
+
 ## CLI Self-Update Language
 
 **Self-Update**:
@@ -178,6 +242,50 @@ _Avoid_: window title, OSC title, process title (each names one channel, not the
 What the session currently needs from the user, as one of three values: idle (nothing running), busy (a turn or long command is running), needs-you (execution is paused on a tool approval or a question to the user). It is the only input that selects the Tab Title glyph.
 _Avoid_: spinner state, running flag, blocked
 
+## Model Tier Language
+
+**Provider-Pool Level**:
+The SDK's machine contract for the three model slots a session carries: `LOW`, `MID`, `HIGH`. It is what `settings.json` (`llm_levels*`), session metadata, the token ledger, subagent frontmatter and the RPC protocol (`comate --rpc-stdio` / `--rpc-ws`; terms in `packages/comate_rpc/CONTEXT.md`) store and exchange. Never shown to the user by the CLI.
+_Avoid_: model level (user-facing), LLM level (user-facing label)
+
+**Model Tier**:
+The user-facing name of a Provider-Pool Level: **Lite** (`LOW`), **Pro** (`MID`), **Elite** (`HIGH`). A pure display vocabulary owned by the client, derived from one mapping module, never persisted and never sent to the SDK.
+_Avoid_: level (in any user-visible text), Max (OpenWorker's transitional name for `HIGH`, being retired), Ultra
+
+**Tier Tagline**:
+The one-line purpose statement shown next to a Model Tier wherever a model name follows it (tier menu, first-run wizard): Lite "Quick answers, small edits", Pro "Everyday coding", Elite "Deep reasoning, hardest problems". `/config` appends a cost clause to the same tagline. Markers such as "(default)" and "(current)" are appended by the display layer, never written into the tagline.
+_Avoid_: level description, help text
+
+## Next-Step Suggestion Language
+
+**Next-Step Suggestion**:
+A short, single-line prediction of what the user would naturally type next, generated once after a user-authored turn completes normally and shown as gray ghost text in the empty input box. It predicts the user's words, not the assistant's advice: it is never an evaluation, a question, or a new idea. It is one-shot per turn: once accepted, or dismissed by any input, busy transition, mode change or session replacement, it does not return for that turn.
+_Avoid_: completion / 补全 (that continues text the user already typed), prediction (names the mechanism), placeholder (that is the queued-message hint's slot), prompt suggestion (Claude Code's name)
+
+**Suggestion Acceptance**:
+The explicit key action that copies a Next-Step Suggestion into the input box as real text, leaving the user to edit or submit it. Acceptance never submits. `Enter` on an empty box never accepts.
+_Avoid_: auto-submit, one-key send
+
+## Bottom Band Status Language
+
+**Task List Panel**:
+The list of the run's tasks shown in the bottom interaction band while the session is busy and unfinished tasks exist. Its title line normally carries the "working" signal (breathing dot, elapsed time, interrupt hint), so the standalone loading line stays hidden while it is shown.
+_Avoid_: todo panel, tasklist (spoken shorthand only)
+
+**Stall Status**:
+A state in which the run is alive but does not advance any task: context compaction in progress, or an LLM retry backoff countdown. Only the countdown counts as Stall Status; the retried request itself does not.
+_Avoid_: blocking status ("blocking" in this repo means blocking the event loop), waiting state
+
+## Event Loop Health Language
+
+**Event Loop Lag**:
+The measured gap between two consecutive UI ticks that exceeds the lag threshold. It tells how long the loop did not run, not where it was stuck. A lag that occurs while the TUI is idle is still an Event Loop Lag; whether it is recorded is a detector choice, not part of the term.
+_Avoid_: slow turn (an awaited operation that is slow does not stop the loop), UI stutter
+
+**Loop Freeze Snapshot**:
+The main-thread stack captured from outside the loop while an Event Loop Lag is still in progress, together with the most recent first-turn phase name. It is the attribution evidence for a lag; the lag log alone is not.
+_Avoid_: lag log, profiler output (the profiler records phase durations, not a stuck stack)
+
 ## Relationships
 
 - A **Core Slash Command** is always registered with `source="builtin"` on the Execution Axis. Its name belongs to the **Reserved Name Set** and cannot be overridden by any markdown-template command.
@@ -187,6 +295,12 @@ _Avoid_: spinner state, running flag, blocked
 - **Default Custom Commands** are loaded from package resources via `importlib.resources`, parsed by the same frontmatter pipeline as project/user commands, and subject to the **Override Priority Chain** at registration time.
 - A **Default Custom Command** parse failure is a developer-visible error (raised at discovery), not a user-visible warning, because package resources are trusted input maintained by the comate_cli maintainers.
 - The **Reserved Name Set** gates discovery only; it prevents user-authored markdown commands from shadowing **Core Slash Commands**, and only Core Slash Commands.
+- Only a **Middle Slash** token enters middle skill completion; a **Head Slash** token belongs to the head command menu.
+- **Trailing Segment Match** never turns a **Skill Slash Token** into a **Skill Slash Mention**: a mention still requires the complete call name with valid boundaries.
+- Under **Trailing Segment Match**, a full-name prefix match always outranks a match through the trailing segment alone; trailing segments only fill in when no full-name prefix matches.
+- In middle skill completion, model-visible candidates outrank user-only candidates; user-only skills only fill in when no model-visible skill matches.
+- Only a user-only skill forms an **Inline Skill Invocation**; a model-visible skill named in prose is always a **Skill Slash Mention**. An Inline Skill Invocation loads the skill and never authorizes the model; a mention authorizes the model and never loads the skill.
+- A **Middle Slash Preview** and Tab always pick the same Skill Slash Command; Tab writes its full slash name even when the preview only completed the trailing segment.
 - **Fence Boundary Recognition** belongs to the streaming lifecycle: `EventRenderer` preserves container atomicity, while Rich remains responsible for Markdown parsing, selecting the first info-string word as the lexer name, syntax highlighting, and plaintext fallback for unknown lexers.
 - A fenced code opening or closing delimiter may have zero to three leading spaces. Four or more leading spaces retain Markdown's indented-code semantics and must not open or close a fenced container.
 - A normally completed turn may add a synthetic closing delimiter before the **Immutable Scrollback Commit**. An interrupted turn discards its uncommitted container instead.
@@ -209,6 +323,9 @@ _Avoid_: spinner state, running flag, blocked
 - The **Update Effectiveness Boundary** holds for both Plugin Auto Update and manual plugin updates: neither may mutate the running session's loaded resources.
 - An **Auto Update Opt-out** affects only Plugin Auto Update; it does not disable manual per-plugin updates.
 
+- 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.
+
 - **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.
@@ -219,6 +336,22 @@ _Avoid_: spinner state, running flag, blocked
 - **Attention State** follows the TUI's single busy switch plus the two pause points (tool approval, question to the user). Background job completion and the exit confirmation dialog do not change it.
 - **Attention State** never animates: each state maps to exactly one glyph, so the terminal is written only on state changes and title changes.
 
+- A **Model Tier** is a rendering of a **Provider-Pool Level**, not a second identity: `/model lite` and `/model LOW` name the same slot, and the CLI translates user input back to the Provider-Pool Level before calling the SDK.
+- The word "tier" is reserved for user-visible text; the word "level" stays on the SDK contract, settings keys and RPC fields. Effort has its own ladder (`low`…`max`); a Model Tier name must never coincide with an effort level name.
+- **Tier Taglines** exist in exactly one place; every surface (tier menu, statusline, `/config`, wizard, preflight summary, endpoint warnings) derives from it.
+
+- A **Next-Step Suggestion** is generated only when the **Attention State** is idle after a turn that ended with `completed`; interrupted or failed turns, and turns not authored by the user, never produce one.
+- A **Next-Step Suggestion** and an Idle Recap may both follow the same turn; they occupy different surfaces (input box vs. scrollback) and neither suppresses the other.
+- **Suggestion Acceptance** follows the inline-completion PRD rule that `Enter` submits only the user's real input; this deliberately differs from Claude Code, where an empty-box `Enter` submits the suggestion.
+- A **Safe Clear** after **Suggestion Acceptance** returns an empty box without the suggestion: the suggestion is one-shot.
+
+- A **Transient Status Message** raised while a **Menu Panel** hides the **Status Bar** is not shown and is not deferred; it expires unseen. Menu Panels report their own feedback in their own footer or in scrollback, never through the Status Bar.
+- 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.
+
 ## Flagged ambiguities
 
-- None currently. The original "builtin" collision between Execution Axis and Source Axis has been resolved by reserving "builtin" for Core Slash Commands and introducing "default" for the new shipped markdown resources.
+- 代码里的 `_menu_panel_active()` 实际含义是“使用共享 `MenuPanel` 外壳”，不含 `/statusline`、marketplace 安装、`/goal edit`，因此与本术语表的 **Menu Panel**（slash 命令打开的暂态操作界面）并不等价。判断 **Status Bar** 是否隐藏另用独立集合，不复用它。
+
+- OpenWorker still shows `HIGH` as **Max** (ADR-0017/0019); the agreed family-wide name is **Elite** (ADR-0023). Until OpenWorker is updated, the same Provider-Pool Level has two display names across products.
+- The original "builtin" collision between Execution Axis and Source Axis has been resolved by reserving "builtin" for Core Slash Commands and introducing "default" for the new shipped markdown resources.

{comate_cli-0.12.3 → comate_cli-0.12.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: comate-cli
-Version: 0.12.3
+Version: 0.12.4
 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,8 @@ 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.8
+Requires-Dist: comate-agent-sdk<0.13,>=0.12.18
+Requires-Dist: comate-rpc<0.2,>=0.1.4
 Requires-Dist: concurrent-log-handler>=0.9.25
 Requires-Dist: curl-cffi==0.13.0
 Requires-Dist: httpx<0.29.0,>=0.28.1

{comate_cli-0.12.3 → comate_cli-0.12.4}/comate_cli/distribution.py

@@ -152,6 +152,11 @@ class DistributionProfile:
     # 发行版策略文案：用户选 ultracode 时先弹确认框、切换后结果行再补一行。
     # None（公版默认）= 不弹、不补。单语纯文本，由 overlay 决定语言。
     ultracode_notice: str | None = None
+    # 署名：commit trailer `Co-Authored-By: <product_name> <attribution_email>` 与
+    # PR/MR 尾注 `🤖 Generated with [<product_name>](<product_url>)`。
+    # None = 尾注不带链接 / trailer 不带邮箱；settings `scm.attribution=false` 可整体关闭。
+    product_url: str | None = None
+    attribution_email: str | None = None
 
     def __post_init__(self) -> None:
         for field_name in ("product_name", "command_name", "package_name"):