protara 0.3.6 → 0.3.9

package/README.md

@@ -19,14 +19,74 @@ protara --version
 
 CLI 用**独立的**登录态（`credentials.cli.json`），不与桌面端共享 —— 服务端的刷新令牌一次一换，共用一份会互相踢下线。
 
+### 两种登录方式：`--login` 会问你一句
+
+```bash
+protara --login
+```
+
+```
+protara: 登录方式：
+  1) 设备码登录      —— 在浏览器里确认一下（有浏览器时最省事）
+  2) 用户名密码登录  —— 没有浏览器时用（SSH / CI）
+  回车 = 1（设备码）
+protara: 选择 [1/2]:
+```
+
+- **1 / 回车** → 设备码：浏览器里确认一下就完成
+- **2** → 用户名密码：接着问用户名（回显），密码**不回显**
+
+**为什么密码登录需要被发现**：SSH 到远程机器、CI、纯终端环境里拿不到浏览器时，设备码走不通
+（`user_code` 可以手输，但那要另一台设备先打开浏览器）。这时密码登录是唯一可用的路径。
+
+### 直接指定，跳过询问
+
+```bash
+protara --login --password                # 跳过菜单，直接用账号密码
+protara --login --password --username alice   # 用户名也给定
+```
+
+⚠️ **非交互环境（CI / 管道）不会弹菜单**，自动按设备码走 —— 脚本里 `protara --login`
+的行为与以前完全一致，不会被卡在等输入。
+
+### 脚本化登录（CI / 自动化）
+
+```bash
+# 方式一：从 stdin 读（推荐，密码不进 shell 历史、不进 ps）
+echo "$MY_PASSWORD" | protara --login --password-stdin --username alice
+
+# 方式二：环境变量
+PROTARA_PASSWORD="$MY_PASSWORD" protara --login --password --username alice
+```
+
+⚠️ **刻意没有 `--password <明文>`**：那会把密码写进 shell 历史、`ps` 的命令行、以及 CI 日志。
+这不是没做，是不提供。
+
+⚠️ 密码输入**一个字符都不回显**（连 `*` 都没有）—— 终端回滚、tmux `capture-pane`、
+屏幕共享都可能留下屏幕内容，密码长度也是信息。
+
+### 首登会被要求改密
+
+如果输出里有这句：
+
+```
+protara: ⚠️ 这个账号首次登录需要先改密码。请用浏览器登录平台改密后再回来用 CLI
+```
+
+说明服务端判了 `must_change_password`。**令牌是有效的**（登录确实成功了），但改密前多数
+操作会被拒绝。去 Web 端改一次密码再回来。
+
+### 排障
+
 ```bash
-protara --login      # 走设备码：浏览器里确认一下就完成
-protara status       # 查登录态 / 凭据路径 / 终端指纹（排障入口）
+protara status    # 登录态 / 凭据路径 / 作用域根 / 终端指纹
 ```
 
 ## 用法
 
 ```bash
+protara agents                           # 列出可用 Agent（含 id / 默认模型）
+protara --agent <id> -p "…"              # 指定 Agent 提问
 protara                                  # 交互界面（需要真 TTY）
 protara -p "帮我看下这个仓库"              # 一次性提问；stdout 只有答案正文
 cat log.txt | protara -p -               # 从管道读正文
@@ -46,6 +106,43 @@ protara --help                           # 全部参数 + 退出码表
 
 `-p` 模式下 **stdout 保证纯净**：所有诊断走 stderr 且带 `protara:` 前缀，或写进日志文件。
 
+### 切换 Agent
+
+先看有哪些（`--agent` 要的是 `id`，不是名字）：
+
+```bash
+protara agents
+```
+
+```
+✓ 2 个可用 Agent
+
+  desktop           优联智能文档（默认）
+      面向内部文档平台的通用助手：能读写工作区文件、跑命令、查技能库
+      默认模型  claude-sonnet-4
+      可选模型  gpt-4o
+
+  code-reviewer     代码审查助手
+      默认模型  claude-sonnet-4
+```
+
+然后指定：
+
+```bash
+protara --agent code-reviewer -p "审查一下这个 diff"
+protara --agent code-reviewer --model gpt-4o -p "…"     # 同时换模型
+```
+
+**不给 `--agent` 时用内置的 `cli` Agent**（终端专用：工具清单里没有浏览器 / 文档编辑，
+因为那两套运行时装不进这个 3.3 MB 的包）。它**不出现在上面的列表里** ——
+它是 CLI 的实现细节，不是给你选的。
+
+⚠️ **Agent 在「建会话」那一刻冻结**，之后不能中途切换 —— 想换就开一个新会话
+（不加 `--session` / `--resume-last` 就是新会话）。这是服务端的口径：
+会话的 `agent_id` 创建后不可变，因为权限档位、技能集、工具清单都在那时定下了。
+
+`protara agents --json` 给脚本用：`{ ok: true, agents: [...] }`（`default: true` 标出默认那个）。
+
 ### 退出码
 
 | 码 | 含义 |
@@ -86,10 +183,65 @@ $DESKTOP_HOME/logs/cli.log      # 默认 ~/.desktop-agents/logs/cli.log
    连接器要重新「去认证」一次。
 3. **凭据目前是明文 `0600` 文件**（refresh 令牌寿命 30 天）。在共享机器上慎用 `--login`。
 
-## 当前未支持
+## 能做什么 / 不能做什么
+
+CLI 与桌面端**共用同一份工具执行器**，但装配不同 —— 差别只有「有没有那个运行时」。
+
+### ✅ 能用的本机工具（13 条）
+
+| 类别 | 工具 |
+|---|---|
+| 文件读写 | `read` / `write` / `edit` / `delete`（废纸篓通道缺省，见下） |
+| 查找 | `grep` / `find` / `glob` / `ls` |
+| 执行 | `bash`（任意命令、可后台） |
+| 技能 | `load_skill` |
+| 传输 | `upload_file` / `download_file`（只要登录态） |
+
+外加：**MCP 连接器工具**（`mcp.json` 与桌面端共享，但授权令牌不共享）、
+`tool_search`（连接器工具的延迟加载检索）。
+
+### ❌ 不能用的两条（会**明确告诉你**，不静默失败）
+
+| 工具 | CLI 里的返回 |
+|---|---|
+| `browser`（浏览器操作） | `本客户端没有装配浏览器通道（找不到随包分发的 bsk 运行时）…` |
+| `univer`（文档编辑） | `本客户端没有装配文档编辑通道（找不到随包分发的 univer 运行时）…` |
+
+**为什么**：这两个能力依赖**随包分发的大体积运行时**，而 npm 包只有 3.3 MB：
+
+| 载荷 | 体积 |
+|---|---|
+| `bsk`（浏览器操作二进制，含 Chromium 驱动） | 23 MB |
+| `univer`（文档编辑：Node 运行时 + 公式/排版/导入导出四份原生模块） | **2.0 GB** |
+
+把 2 GB 塞进 npm 包不现实（npm 单包上限 500 MB，且装一次要几分钟）。
+所以 CLI 里这两条**如实拒绝**，⛔ 不会偷偷用 `bash` 去跑 —— 那会绕过整条权限口径。
+
+> 需要浏览器自动化 / 文档编辑：请用**桌面端**（它随包带了这两套载荷）。
+> 在 CLI 里模型会看到这两条工具（清单与桌面端同一份），调用后收到上面那句拒绝，
+> 然后自己改用 `bash` + 其他方式，或者告诉你「这个我做不了」。
+
+### ✅ 交互界面里的键盘
+
+| 键 | 作用 |
+|---|---|
+| `Enter` | 发送 |
+| `Alt+Enter` / `Ctrl+J` | **换行**（可写多行，2026-11-12 起支持） |
+| `Ctrl+C` | 中断当前回合；空闲时退出（会先收掉本机后台进程） |
+| `Ctrl+D` | 退出（**输入框为空时**；有内容时是删掉光标后的字符） |
+| `Ctrl+U` / `Ctrl+K` | 删到行首 / 行尾 |
+| `Ctrl+P` 或 `/plan` | 展开 / 收起任务计划条 |
+
+模型中途要你决定时（`ask_user` 工具），界面会画出选项让你选序号或直接打字；
+没有交互终端（`-p` / CI）时默认回一条「用户取消」让模型换思路 ——
+要让它自动取第一项就用 `--ask-user=first`（⚠️ 会静默替你决定，慎用）。
+
+### ❌ 其他没做的
+
+连接器「去认证」交互面板、作业角标面板、diff 分页、图片拖入、Windows 上的沙箱助手。
 
-连接器「去认证」交互面板、计划条、作业角标面板、diff 分页、图片拖入、多行编辑框
-（TUI 逐行提交）、Windows 上的沙箱助手。
+> ⚠️ 这份清单要与代码保持一致：**计划条**与**多行编辑框**已在 2026-11-12 实现
+> （见 `docs/desktop-cli-tui-pi-reuse-design.md` §14），已从上表移走。
 
 ## 环境变量