protara 0.3.6 → 0.3.7

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
-protara --login      # 走设备码：浏览器里确认一下就完成
-protara status       # 查登录态 / 凭据路径 / 终端指纹（排障入口）
+# 方式一：从 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 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,7 +183,45 @@ $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` + 其他方式，或者告诉你「这个我做不了」。
+
+### ❌ 其他没做的
 
 连接器「去认证」交互面板、计划条、作业角标面板、diff 分页、图片拖入、多行编辑框
 （TUI 逐行提交）、Windows 上的沙箱助手。

package/dist/cli/index.cjs

@@ -51188,6 +51188,9 @@ var DEFAULT = {
   forceHeadless: false,
   verbose: false,
   login: false,
+  loginMethod: "ask",
+  username: null,
+  passwordFromStdin: false,
   logout: false,
   version: false,
   help: false,
@@ -51287,6 +51290,19 @@ function parseArgs(argv) {
       case "--login":
         out.login = true;
         break;
+      case "--password":
+        out.loginMethod = "password";
+        out.login = true;
+        break;
+      case "--username":
+        out.username = next("--username");
+        break;
+      case "--password-stdin":
+        out.passwordFromStdin = true;
+        out.loginMethod = "password";
+        out.login = true;
+        break;
+        break;
       case "--logout":
         out.logout = true;
         break;
@@ -51313,7 +51329,7 @@ function parseArgs(argv) {
   }
   if (positional.length > 0) {
     const [first, ...rest] = positional;
-    if (first === "login" || first === "logout" || first === "status") {
+    if (first === "login" || first === "logout" || first === "status" || first === "agents") {
       out.command = first;
     } else if (first !== void 0 && !out.prompt && !out.promptFromStdin) {
       out.prompt = [first, ...rest].join(" ");
@@ -51374,8 +51390,16 @@ var HELP_TEXT = `protara \u2014 \u4F18\u8054\u667A\u80FD\u6587\u6863\u7684\u7EC8
   -v, --verbose             \u628A\u8BCA\u65AD\u4E5F\u8F93\u51FA\u5230 stderr\uFF08\u9ED8\u8BA4\u53EA\u5199\u65E5\u5FD7\u6587\u4EF6\uFF09
       --approval <mode>     deny\uFF08\u9ED8\u8BA4\uFF0C\u65E0\u4EBA\u5E94\u7B54\u5373\u62D2\u6279\uFF09| remote\uFF08\u8D70\u6D4F\u89C8\u5668\u8FDC\u7A0B\u5BA1\u6279\uFF09
       --origin <url>        \u5E73\u53F0\u5730\u5740
-      --login / --logout    \u53EA\u767B\u5F55 / \u53EA\u9000\u51FA\uFF08\u8BBE\u5907\u7801\u6D41\uFF09
+      --login / --logout    \u53EA\u767B\u5F55 / \u53EA\u9000\u51FA
+                            \u4E0D\u52A0\u522B\u7684\u53C2\u6570\u65F6\uFF0C\u4F1A\u95EE\u300C1 \u8BBE\u5907\u7801 / 2 \u8D26\u53F7\u5BC6\u7801\u300D\uFF0C
+                            \u975E\u4EA4\u4E92\u73AF\u5883\uFF08CI / \u7BA1\u9053\uFF09\u81EA\u52A8\u6309\u8BBE\u5907\u7801\u8D70\uFF0C\u4E0D\u4F1A\u505C\u4E0B\u6765\u7B49\u8F93\u5165
+      --password            \u8DF3\u8FC7\u8BE2\u95EE\uFF0C\u76F4\u63A5\u7528**\u8D26\u53F7\u5BC6\u7801**\u767B\u5F55\uFF08SSH / CI \u91CC\u6CA1\u6709\u6D4F\u89C8\u5668\u65F6\u7528\uFF09
+      --username <name>     \u8D26\u53F7\u5BC6\u7801\u767B\u5F55\u7684\u7528\u6237\u540D\uFF08\u4E0D\u7ED9\u5C31\u4EA4\u4E92\u8F93\u5165\uFF09
+      --password-stdin      \u4ECE stdin \u8BFB\u5BC6\u7801\uFF08\u811A\u672C\u7528\uFF1Aecho "$PW" | protara login --password-stdin\uFF09
+                            \u26A0\uFE0F \u523B\u610F**\u4E0D\u63D0\u4F9B** "--password <\u660E\u6587>"\uFF1A\u90A3\u4F1A\u7559\u5728 shell \u5386\u53F2\u91CC\u3002
+                            \u975E\u4EA4\u4E92\u4E5F\u53EF\u7528\u73AF\u5883\u53D8\u91CF PROTARA_PASSWORD\u3002
   status                \u6253\u5370\u767B\u5F55\u6001 / \u51ED\u636E\u8DEF\u5F84 / \u7EC8\u7AEF\u6307\u7EB9\uFF08\u53EA\u8BFB\uFF0C\u6392\u969C\u7528\uFF09
+  agents                \u5217\u51FA\u5F53\u524D\u8EAB\u4EFD\u53EF\u7528\u7684 Agent\uFF08id / \u540D\u79F0 / \u9ED8\u8BA4\u6A21\u578B\uFF09
 
 \u9000\u51FA\u7801\uFF1A
   0 \u56DE\u5408\u6B63\u5E38\u6536\u5C3E    1 \u56DE\u5408\u5931\u8D25\u6216\u88AB\u505C\u6B62   2 \u7528\u6CD5\u9519\u8BEF      3 \u672A\u767B\u5F55 / \u51ED\u636E\u5931\u6548
@@ -88449,6 +88473,47 @@ var plaintextCodec = {
   decrypt: () => null
 };
 
+// src/cli/agent-selection.ts
+var BUILTIN_CLI_AGENT_ID = "cli";
+function isAgentUnavailable(err) {
+  if (typeof err !== "object" || err === null) return false;
+  const candidate = err;
+  if (candidate.status === 404) return true;
+  const text2 = typeof candidate.message === "string" ? candidate.message : String(err);
+  return /agent[_ -]?not[_ -]?found|不存在.*agent|agent.*不存在|没有可用的 agent/i.test(text2);
+}
+async function createSessionForCli(deps) {
+  const explicit = deps.explicit?.trim();
+  if (explicit) {
+    const session = await deps.create(explicit);
+    return { sessionId: session.id, choice: { agentId: explicit, source: "explicit" } };
+  }
+  try {
+    const session = await deps.create(BUILTIN_CLI_AGENT_ID);
+    return {
+      sessionId: session.id,
+      choice: { agentId: BUILTIN_CLI_AGENT_ID, source: "builtin" }
+    };
+  } catch (err) {
+    if (!isAgentUnavailable(err)) throw err;
+    const agents = await deps.listAgents();
+    const first = agents[0]?.id;
+    if (!first) {
+      throw err;
+    }
+    const session = await deps.create(first);
+    return {
+      sessionId: session.id,
+      choice: {
+        agentId: first,
+        source: "fallback-first",
+        warning: `\u8FD9\u4E2A\u670D\u52A1\u7AEF\u6CA1\u6709\u53EF\u7528\u7684\u5185\u7F6E CLI Agent\uFF08id="${BUILTIN_CLI_AGENT_ID}"\uFF09\uFF0C\u5DF2\u6539\u7528 "${first}"\u3002
+  \u26A0\uFE0F \u5B83\u7684\u5DE5\u5177\u6E05\u5355\u91CC\u53EF\u80FD\u6709\u6D4F\u89C8\u5668 / \u6587\u6863\u7F16\u8F91\u5DE5\u5177\uFF0C\u800C\u7EC8\u7AEF\u91CC\u8DD1\u4E0D\u4E86\uFF08\u4F1A\u8FD4\u56DE\u300C\u672C\u5BA2\u6237\u7AEF\u6CA1\u6709\u88C5\u914D\u2026\u901A\u9053\u300D\uFF09\u3002`
+      }
+    };
+  }
+}
+
 // src/core/host.ts
 function isNormalEnd(reason) {
   return reason === "reply" || reason === "done" || reason === "attached";
@@ -88979,21 +89044,21 @@ async function runOnce(options) {
       }
     }
     if (!sessionId) {
-      const agentId = args.agentId ?? (await runtime.api.agentsList())[0]?.id ?? "";
-      if (!agentId) {
-        writers.err("protara: usage: \u5E73\u53F0\u4E0A\u6CA1\u6709\u53EF\u7528\u7684 Agent\n");
-        return { exitCode: EXIT.USAGE, sessionId: null, turnId, reason: null, approvalBlocked };
-      }
-      const session = await runtime.api.sessionsCreate({
-        agent_id: agentId,
-        model_id: args.modelId ?? null,
-        workspace: args.workspace ?? process.cwd(),
-        // ⭐ 声明原样转出去（`sessionsCreate` 是唯一那一处；D10 静态守着）。
-        // ⚠️ `overrides` 是**必填**（服务端把它整段写进 metadata）：CLI 没有逐项微调，
-        //    给空对象 = 「只声明档位，不覆盖任何单项」。⛔ 别传 `null`（那等于没声明）。
-        permission: args.permission ? { preset: args.permission, overrides: {} } : null
+      const { sessionId: created, choice } = await createSessionForCli({
+        explicit: args.agentId,
+        listAgents: () => runtime.api.agentsList(),
+        create: (agentId) => runtime.api.sessionsCreate({
+          agent_id: agentId,
+          model_id: args.modelId ?? null,
+          workspace: args.workspace ?? process.cwd(),
+          // ⭐ 声明原样转出去（`sessionsCreate` 是唯一那一处；D10 静态守着）。
+          // ⚠️ `overrides` 是**必填**（服务端把它整段写进 metadata）：CLI 没有逐项微调，
+          //    给空对象 = 「只声明档位，不覆盖任何单项」。⛔ 别传 `null`（那等于没声明）。
+          permission: args.permission ? { preset: args.permission, overrides: {} } : null
+        })
       });
-      sessionId = session.id;
+      sessionId = created;
+      if (choice.warning) log("warn", choice.warning);
     }
   } catch (err) {
     return await fail2(err, null);
@@ -89631,20 +89696,19 @@ async function runTui(options) {
   const runTurn = async (message) => {
     if (!sessionId) {
       try {
-        const agents = await runtime.api.agentsList();
-        const agentId = options.args.agentId ?? agents[0]?.id ?? "";
-        if (!agentId) {
-          commitLive(["  \u2717 \u5E73\u53F0\u4E0A\u6CA1\u6709\u53EF\u7528\u7684 Agent"]);
-          return;
-        }
-        agentLabel = agentId;
-        const session = await runtime.api.sessionsCreate({
-          agent_id: agentId,
-          model_id: options.args.modelId ?? null,
-          workspace: options.args.workspace ?? process.cwd(),
-          permission: options.args.permission ? { preset: options.args.permission, overrides: {} } : null
+        const { sessionId: created, choice } = await createSessionForCli({
+          explicit: options.args.agentId,
+          listAgents: () => runtime.api.agentsList(),
+          create: (agentId) => runtime.api.sessionsCreate({
+            agent_id: agentId,
+            model_id: options.args.modelId ?? null,
+            workspace: options.args.workspace ?? process.cwd(),
+            permission: options.args.permission ? { preset: options.args.permission, overrides: {} } : null
+          })
         });
-        sessionId = session.id;
+        sessionId = created;
+        agentLabel = choice.agentId;
+        if (choice.warning) commitLive([`  \u26A0\uFE0F ${choice.warning.replace(/\n/g, "\n  ")}`, ""]);
         await runtime.prefs.rememberWorkspace(options.args.workspace ?? process.cwd());
       } catch (err) {
         commitLive([
@@ -89866,6 +89930,238 @@ async function printAuthStatus(runtime, options) {
 `);
   return EXIT.OK;
 }
+async function printAgents(runtime, options) {
+  const { writers, json } = options;
+  let agents;
+  try {
+    agents = await runtime.api.agentsList();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (json) {
+      writers.out(`${JSON.stringify({ ok: false, error: message })}
+`);
+    }
+    writers.err(
+      `protara: \u53D6 Agent \u5217\u8868\u5931\u8D25\uFF1A${message}
+protara: \u8BF7\u786E\u8BA4\u5DF2\u767B\u5F55\uFF08protara status\uFF09\u4E14\u80FD\u8FDE\u4E0A\u5E73\u53F0\uFF08--origin\uFF09
+`
+    );
+    return EXIT.TURN_FAILED;
+  }
+  if (json) {
+    writers.out(
+      `${JSON.stringify({
+        ok: true,
+        agents: agents.map((a) => ({ ...a, default: false }))
+      })}
+`
+    );
+    return EXIT.OK;
+  }
+  if (agents.length === 0) {
+    writers.err("protara: \u8FD9\u4E2A\u8EAB\u4EFD\u6CA1\u6709\u53EF\u7528\u7684 Agent\uFF08\u627E\u7BA1\u7406\u5458\u786E\u8BA4\u6743\u9650\uFF09\n");
+    return EXIT.OK;
+  }
+  writers.out(`\u2713 ${agents.length} \u4E2A\u53EF\u7528 Agent
+
+`);
+  for (const agent of agents) {
+    writers.out(`  ${agent.id.padEnd(18)}${agent.name}
+`);
+    if (agent.description && agent.description !== agent.name) {
+      writers.out(`      ${wrapOneLine(agent.description, 66)}
+`);
+    }
+    const defaultModel = agent.default_model?.id ?? null;
+    if (defaultModel) writers.out(`      \u9ED8\u8BA4\u6A21\u578B  ${defaultModel}
+`);
+    const others = agent.models.map((m) => m.id).filter((id) => id !== defaultModel);
+    if (others.length > 0) {
+      writers.out(`      \u53EF\u9009\u6A21\u578B  ${wrapOneLine(others.join(", "), 66)}
+`);
+    }
+    writers.out("\n");
+  }
+  writers.out(
+    `  \u5185\u7F6E  ${BUILTIN_CLI_AGENT_ID.padEnd(18)}\u7EC8\u7AEF\u4E13\u7528\uFF08\u9ED8\u8BA4\uFF09  \u2190 \u4E0D\u5728\u4E0A\u9762\u7684\u5217\u8868\u91CC
+`
+  );
+  writers.out("\n");
+  writers.out('\u7528\u6CD5\uFF1Aprotara --agent <id> -p "\u2026"     \u6307\u5B9A Agent\uFF08\u7701\u7565 = \u7528\u5185\u7F6E\u7684 cli\uFF09\n');
+  writers.out('      protara --agent <id> --model <id> -p "\u2026"   \u540C\u65F6\u6307\u5B9A\u6A21\u578B\n');
+  return EXIT.OK;
+}
+function wrapOneLine(text2, width) {
+  const oneLine2 = text2.replace(/\r?\n/g, " ").trim();
+  if (displayWidth(oneLine2) <= width) return oneLine2;
+  const parts = [];
+  let current2 = "";
+  for (const ch of oneLine2) {
+    if (displayWidth(current2 + ch) > width) {
+      parts.push(current2);
+      current2 = ch;
+    } else {
+      current2 += ch;
+    }
+  }
+  if (current2) parts.push(current2);
+  return parts.join("\n      ");
+}
+function readSecret(prompt, io) {
+  const stdin = io?.stdin ?? process.stdin;
+  const stderr = io?.stderr ?? process.stderr;
+  if (!stdin.isTTY || typeof stdin.setRawMode !== "function") {
+    return Promise.reject(
+      new Error(
+        "\u9700\u8981\u4EA4\u4E92\u5F0F\u7EC8\u7AEF\u624D\u80FD\u9690\u85CF\u8F93\u5165\u5BC6\u7801\u3002\u811A\u672C\u5316\u767B\u5F55\u8BF7\u7528\u73AF\u5883\u53D8\u91CF PROTARA_PASSWORD\uFF08\u6216 --password-stdin \u4ECE\u7BA1\u9053\u8BFB\uFF09\u3002"
+      )
+    );
+  }
+  stderr.write(prompt);
+  return new Promise((resolve23, reject) => {
+    let buffer = "";
+    const previousRaw = stdin.isRaw;
+    const cleanup = () => {
+      stdin.setRawMode?.(previousRaw ?? false);
+      stdin.removeListener("data", onData);
+      stdin.pause();
+    };
+    const onData = (chunk) => {
+      const text2 = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      for (const ch of text2) {
+        if (ch === "") {
+          cleanup();
+          stderr.write("\n");
+          reject(new Error("\u5DF2\u53D6\u6D88\uFF08Ctrl-C\uFF09"));
+          return;
+        }
+        if (ch === "\r" || ch === "\n") {
+          cleanup();
+          stderr.write("\n");
+          resolve23(buffer);
+          return;
+        }
+        if (ch === "\x7F" || ch === "\b") {
+          buffer = buffer.slice(0, -1);
+          continue;
+        }
+        if (ch < " ") continue;
+        buffer += ch;
+      }
+    };
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    stdin.on("data", onData);
+  });
+}
+async function runPasswordLogin(runtime, options) {
+  const { writers, log } = options;
+  const username = (options.username ?? "").trim() || await askUsername(options);
+  if (!username) {
+    writers.err("protara: usage: \u672A\u63D0\u4F9B\u7528\u6237\u540D\n");
+    writers.err("protara: \u7528 `protara login --password --username <\u540D\u5B57>`\uFF0C\u6216\u4E0D\u5E26 --username \u4EA4\u4E92\u8F93\u5165\n");
+    return EXIT.USAGE;
+  }
+  let password = options.password ?? "";
+  if (!password) {
+    try {
+      const read = options.readPassword ?? ((prompt) => readSecret(prompt));
+      password = await read(`protara: ${username} \u7684\u5BC6\u7801\uFF08\u8F93\u5165\u4E0D\u56DE\u663E\uFF09: `);
+    } catch (err) {
+      writers.err(`protara: auth-failed: ${err instanceof Error ? err.message : String(err)}
+`);
+      return EXIT.AUTH;
+    }
+  }
+  if (!password) {
+    writers.err("protara: usage: \u5BC6\u7801\u4E3A\u7A7A\n");
+    return EXIT.USAGE;
+  }
+  try {
+    const status = await runtime.auth.loginWithPassword(username, password);
+    log("info", `[auth] \u8D26\u53F7\u5BC6\u7801\u767B\u5F55\u6210\u529F\uFF1A${username}\uFF08channel=password\uFF09`);
+    const who = status.display_name ? `${status.display_name}${status.user_id ? `\uFF08u${status.user_id}\uFF09` : ""}` : `\u7528\u6237 ${username}`;
+    writers.err(`protara: \u5DF2\u767B\u5F55\uFF1A${who}
+`);
+    writers.err(`protara: \u51ED\u636E\u5199\u5165 ${runtime.store.path()}\uFF08CLI \u72EC\u5360\uFF0C\u4E0E\u684C\u9762\u7AEF\u4E92\u4E0D\u5F71\u54CD\uFF09
+`);
+    if (status.must_change_password) {
+      writers.err(
+        "protara: \u26A0\uFE0F \u8FD9\u4E2A\u8D26\u53F7\u9996\u6B21\u767B\u5F55\u9700\u8981\u5148\u6539\u5BC6\u7801\u3002\u8BF7\u7528\u6D4F\u89C8\u5668\u767B\u5F55\u5E73\u53F0\u6539\u5BC6\u540E\u518D\u56DE\u6765\u7528 CLI\uFF08\u6539\u5BC6\u524D\u591A\u6570\u64CD\u4F5C\u4F1A\u88AB\u62D2\u7EDD\uFF09\u3002\n"
+      );
+    }
+    return EXIT.OK;
+  } catch (err) {
+    const status = err.status;
+    const detail = err instanceof Error ? err.message : String(err);
+    const hasChineseDetail = /[一-龥]/.test(detail) && detail.length >= 4;
+    const hint = hasChineseDetail ? "" : status === 401 ? "\uFF08\u7528\u6237\u540D\u6216\u5BC6\u7801\u9519\u8BEF\uFF09" : status === 403 ? "\uFF08\u8D26\u53F7\u5DF2\u88AB\u7981\u7528\uFF0C\u8BF7\u8054\u7CFB\u7BA1\u7406\u5458\uFF09" : status === 422 ? "\uFF08\u7528\u6237\u540D\u6216\u5BC6\u7801\u683C\u5F0F\u4E0D\u5408\u6CD5\uFF09" : "";
+    writers.err(`protara: auth-failed: ${detail}${hint}
+`);
+    log("warn", `[auth] \u8D26\u53F7\u5BC6\u7801\u767B\u5F55\u5931\u8D25\uFF1A${username} status=${status ?? "?"}`);
+    return EXIT.AUTH;
+  }
+}
+async function askUsername(options) {
+  if (options.readUsername) {
+    return (await options.readUsername("protara: \u7528\u6237\u540D: ") ?? "").trim();
+  }
+  const answer = await readLineOnce({ prompt: "protara: \u7528\u6237\u540D: " });
+  return (answer ?? "").trim();
+}
+async function readLineOnce(options) {
+  const input = options.input ?? process.stdin;
+  if (!input.isTTY) return null;
+  const output = options.output ?? process.stderr;
+  const { createInterface: createInterface4 } = await import("node:readline");
+  return await new Promise((resolve23) => {
+    const rl = createInterface4({
+      input,
+      output,
+      terminal: options.terminal ?? true
+    });
+    let answered = false;
+    rl.question(options.prompt, (answer) => {
+      answered = true;
+      resolve23(answer);
+      rl.close();
+    });
+    rl.once("close", () => {
+      if (!answered) resolve23(null);
+    });
+  });
+}
+async function askLoginMethod(options) {
+  const { writers } = options;
+  const read = options.readLine ?? defaultReadLine;
+  writers.err("protara: \u767B\u5F55\u65B9\u5F0F\uFF1A\n");
+  writers.err("  1) \u8BBE\u5907\u7801\u767B\u5F55      \u2014\u2014 \u5728\u6D4F\u89C8\u5668\u91CC\u786E\u8BA4\u4E00\u4E0B\uFF08\u6709\u6D4F\u89C8\u5668\u65F6\u6700\u7701\u4E8B\uFF09\n");
+  writers.err("  2) \u7528\u6237\u540D\u5BC6\u7801\u767B\u5F55  \u2014\u2014 \u6CA1\u6709\u6D4F\u89C8\u5668\u65F6\u7528\uFF08SSH / CI\uFF09\n");
+  writers.err("  \u56DE\u8F66 = 1\uFF08\u8BBE\u5907\u7801\uFF09\n");
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const answer = await read("protara: \u9009\u62E9 [1/2]: ");
+    if (answer === null) {
+      writers.err("\nprotara: \u5DF2\u53D6\u6D88\u767B\u5F55\n");
+      return null;
+    }
+    const text2 = answer.trim();
+    if (text2 === "" || text2 === "1") return "device";
+    if (text2 === "2") return "password";
+    writers.err(`protara: \u53EA\u80FD\u8F93\u5165 1 \u6216 2\uFF08\u6536\u5230 ${JSON.stringify(text2)}\uFF09
+`);
+  }
+  writers.err("protara: \u8FDE\u7EED 3 \u6B21\u6CA1\u542C\u61C2\uFF0C\u5148\u6309\u8BBE\u5907\u7801\u767B\u5F55\uFF08\u8981\u5BC6\u7801\u767B\u5F55\u8BF7\u52A0 --password\uFF09\n");
+  return "device";
+}
+async function defaultReadLine(prompt) {
+  return await readLineOnce({ prompt });
+}
+function resolveLoginMethod(method, options) {
+  if (method !== "ask") return method;
+  if (!options.stdinIsTty || !options.stdoutIsTty) return "device";
+  return "ask";
+}
 
 // src/core/file-logger.ts
 var import_promises37 = require("node:fs/promises");
@@ -89910,25 +90206,47 @@ function createFileLogger(options) {
     for (let i = keep - 1; i >= 1; i -= 1) {
       const from = i === 1 ? file : `${file}.${i - 1}`;
       const to = `${file}.${i}`;
-      try {
-        if (i === keep - 1) await (0, import_promises37.unlink)(to).catch(() => {
+      if (i === keep - 1) {
+        await (0, import_promises37.unlink)(to).catch(() => {
         });
-        await (0, import_promises37.rename)(from, to);
-      } catch {
       }
+      await (0, import_promises37.rename)(from, to).catch(() => {
+      });
     }
     bytes = 0;
   };
-  const writeOne = async (line) => {
-    const text2 = format(line);
-    const size = Buffer.byteLength(text2, "utf8");
+  let dirReady = false;
+  const ensureDir = async () => {
+    if (dirReady) return;
+    await (0, import_promises37.mkdir)((0, import_node_path48.dirname)(file), { recursive: true });
+    dirReady = true;
+  };
+  const writeBatch = async (lines) => {
+    if (lines.length === 0) return;
     try {
-      await (0, import_promises37.mkdir)((0, import_node_path48.dirname)(file), { recursive: true });
-      await rotateIfNeeded(size);
-      await (0, import_promises37.appendFile)(file, text2, "utf8");
-      bytes += size;
-      written += 1;
-      if (options.alsoStderr) stderrWrite(text2);
+      await ensureDir();
+      let text2 = "";
+      for (const line of lines) {
+        const formatted = format(line);
+        const lineSize = Buffer.byteLength(formatted, "utf8");
+        if (bytes + Buffer.byteLength(text2, "utf8") + lineSize > maxBytes) {
+          if (text2) {
+            await (0, import_promises37.appendFile)(file, text2, "utf8");
+            bytes += Buffer.byteLength(text2, "utf8");
+            text2 = "";
+          }
+          await rotateIfNeeded(lineSize);
+        }
+        text2 += formatted;
+      }
+      if (text2) {
+        await (0, import_promises37.appendFile)(file, text2, "utf8");
+        bytes += Buffer.byteLength(text2, "utf8");
+      }
+      written += lines.length;
+      if (options.alsoStderr) {
+        for (const line of lines) stderrWrite(format(line));
+      }
     } catch (err) {
       if (!reportedFailure) {
         reportedFailure = true;
@@ -89940,6 +90258,23 @@ function createFileLogger(options) {
       }
     }
   };
+  let buffer = [];
+  const MAX_BATCH = 64;
+  let flushScheduled = false;
+  const flushBuffer = () => {
+    if (buffer.length === 0) return;
+    const batch = buffer;
+    buffer = [];
+    tail = tail.then(() => writeBatch(batch));
+  };
+  const scheduleFlush = () => {
+    if (flushScheduled) return;
+    flushScheduled = true;
+    queueMicrotask(() => {
+      flushScheduled = false;
+      flushBuffer();
+    });
+  };
   const log = (level, message, detail) => {
     if (!enabled) return;
     const suffix = detailTextOf(detail);
@@ -89947,8 +90282,9 @@ function createFileLogger(options) {
     const stack = level === "error" && detail instanceof Error && detail.stack ? `
     ${detail.stack.split("\n").slice(1).join("\n    ")}` : "";
     const text2 = suffix ? `${message} ${suffix}${stack}` : `${message}${stack}`;
-    const pending = { level, text: text2 };
-    tail = tail.then(() => writeOne(pending));
+    buffer.push({ level, text: text2 });
+    if (buffer.length >= MAX_BATCH) flushBuffer();
+    else scheduleFlush();
   };
   return {
     log,
@@ -89957,6 +90293,7 @@ function createFileLogger(options) {
     written: () => written,
     flush: async (timeoutMs = 2e3) => {
       const deadline = Date.now() + timeoutMs;
+      flushBuffer();
       await Promise.race([
         initialSizeDone,
         new Promise((resolve23) => setTimeout(resolve23, Math.max(0, deadline - Date.now())).unref?.())
@@ -90065,7 +90402,7 @@ function installCrashLogging(log) {
 
 // src/cli/index.ts
 function cliVersion() {
-  if ("0.3.6") return "0.3.6";
+  if ("0.3.7") return "0.3.7";
   try {
     const here = typeof __dirname === "string" ? `${__dirname}/../../package.json` : "";
     const pkg = JSON.parse((0, import_node_fs11.readFileSync)(here, "utf8"));
@@ -90114,6 +90451,37 @@ async function main(argv, env = process.env) {
     return EXIT.OK;
   }
   if (args.command === "login" || args.login) {
+    let method = resolveLoginMethod(args.loginMethod, {
+      stdinIsTty: Boolean(process.stdin.isTTY),
+      stdoutIsTty: Boolean(process.stdout.isTTY)
+    });
+    if (method === "ask") {
+      const choice = await askLoginMethod({ writers });
+      if (choice === null) return EXIT.AUTH;
+      method = choice;
+    }
+    if (method === "password") {
+      let password = null;
+      if (args.passwordFromStdin) {
+        password = await readPasswordFromStdin();
+        if (password === null) {
+          writers.err("protara: usage: --password-stdin \u4F46\u6CA1\u6709\u4ECE stdin \u8BFB\u5230\u5185\u5BB9\n");
+          return EXIT.USAGE;
+        }
+      } else if (env.PROTARA_PASSWORD) {
+        password = env.PROTARA_PASSWORD;
+      }
+      return await withRuntime(
+        args,
+        (runtime) => runPasswordLogin(runtime, {
+          writers,
+          log,
+          username: args.username,
+          password
+        }),
+        { writers, log, flushLog: () => fileLogger.flush() }
+      );
+    }
     return await withRuntime(args, (runtime) => runDeviceLogin(runtime, { writers, log }), {
       writers,
       log,
@@ -90134,6 +90502,13 @@ async function main(argv, env = process.env) {
       flushLog: () => fileLogger.flush()
     });
   }
+  if (args.command === "agents") {
+    return await withRuntime(args, (runtime) => printAgents(runtime, { writers, json: args.mode === "json" }), {
+      writers,
+      log,
+      flushLog: () => fileLogger.flush()
+    });
+  }
   const resolved = resolveMode(args, {
     stdoutIsTty: Boolean(process.stdout.isTTY),
     stdinIsTty: Boolean(process.stdin.isTTY)
@@ -90287,6 +90662,16 @@ function readStdin(timeoutMs = 0) {
     process.stdin.on("error", finish3);
   });
 }
+async function readPasswordFromStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    if (Buffer.concat(chunks).includes(10)) break;
+  }
+  const text2 = Buffer.concat(chunks).toString("utf8");
+  if (!text2) return null;
+  return text2.replace(/\r?\n[\s\S]*$/, "");
+}
 function makeAsk() {
   if (!process.stdin.isTTY) return void 0;
   return (question) => new Promise((resolve23) => {

package/package.json

@@ -2,7 +2,7 @@
   "//name": "⭐ 裸包名（2026-11-12 查过 registry.npmjs.org 上未被占用）。⚠️ npm 包名必须**全小写** —— 上级目录那个 `Protara`（大写 P）在 npm 上是**非法**的，`npm publish` 会直接 400。这也是必须拆独立包的原因之一。",
   "name": "protara",
   "//version": "⚠️ **由 `scripts/publish-cli.mjs` 在打包时写入**（取 `desktop-app/package.json` 的版本），⛔ 不要手改：两处版本漂移的症状是「npm 上是 0.3.6、包里 `--version` 打印 0.3.5」，而两个都看起来正常。",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Protara 的终端客户端：在终端里与 Agent 对话、跑本机工具、审批权限变更。无 GUI、可管道、退出码规范。",
   "//type": "CLI 产物是 CJS（`dist/cli/index.cjs`），而 bin 垫片是 ESM（`.mjs`）。`type: module` 让 `.mjs` 名正言顺，同时 `.cjs` 扩展名保证 CJS 解析。",
   "type": "module",
@@ -40,4 +40,4 @@
     "terminal",
     "desktop-agents"
   ]
-}
+}