protara 0.0.0-stage → 0.3.6

package/README.md

@@ -1,3 +1,103 @@
-# Temporary Holding Version
+# protara
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Protara 的**终端客户端**：在终端里与 Agent 对话、跑本机工具、按需审批。无 GUI、可管道、退出码规范。
+
+与桌面端共用同一份内核（同一套会话 / 权限判定 / 工具执行），区别只在呈现层。
+
+## 安装
+
+```bash
+npm i -g protara
+protara --version
+```
+
+要求 **Node.js ≥ 22.6**。
+
+> 如果你之前在本仓里 `npm link` 过，先 `npm unlink -g protara`，否则跑的还是仓库那份。
+
+## 第一次用：先登录
+
+CLI 用**独立的**登录态（`credentials.cli.json`），不与桌面端共享 —— 服务端的刷新令牌一次一换，共用一份会互相踢下线。
+
+```bash
+protara --login      # 走设备码：浏览器里确认一下就完成
+protara status       # 查登录态 / 凭据路径 / 终端指纹（排障入口）
+```
+
+## 用法
+
+```bash
+protara                                  # 交互界面（需要真 TTY）
+protara -p "帮我看下这个仓库"              # 一次性提问；stdout 只有答案正文
+cat log.txt | protara -p -               # 从管道读正文
+protara --json -p "…"                    # NDJSON 事件流（给脚本）
+protara --resume-last -p "继续"           # 续最近一条会话
+protara -C ~/proj --permission standard -p "跑一下测试"
+protara --help                           # 全部参数 + 退出码表
+```
+
+### 三种输出形态
+
+| 形态 | 用途 | stdout 内容 |
+|---|---|---|
+| 默认（TTY） | 人读 | 交互界面 |
+| `-p "…"` | 脚本 / 管道 | **只有答案正文**（逐字节） |
+| `--json` | 机器解析 | NDJSON 事件流，每行一个 JSON |
+
+`-p` 模式下 **stdout 保证纯净**：所有诊断走 stderr 且带 `protara:` 前缀，或写进日志文件。
+
+### 退出码
+
+| 码 | 含义 |
+|---|---|
+| 0 | 回合正常收尾 |
+| 1 | 回合失败或被停止 |
+| 2 | 用法错误 |
+| 3 | 未登录 / 凭据失效 |
+| 4 | 配额用尽 |
+| 5 | 审批未通过 |
+| 6 | 连接中断且无法附着 |
+| 7 | 会话 / Agent / 模型不存在 |
+| 130 | 收到 Ctrl-C（会先收掉本机后台进程） |
+
+### 审批
+
+管道和 CI 里没人能点确认框 ⇒ 默认立即按「未通过」结算（退出码 5）。要用更宽的权限，用
+`--permission <档位>` 在**建会话时**声明，或用 `--approval=remote` 在浏览器里点。
+
+⛔ 没有 `--yolo`：这个客户端不提供跳过审批的开关。
+
+## 日志
+
+诊断**默认写文件，不打到终端**（否则会把对话流冲散）：
+
+```
+$DESKTOP_HOME/logs/cli.log      # 默认 ~/.desktop-agents/logs/cli.log
+```
+
+- 按大小轮转（5 MB × 3 份）
+- `error` 级别带调用栈，`info` / `warn` 不带
+- 想当场看到诊断：`protara -v …`（`--verbose`）
+
+## 三条需要预先知道的代价
+
+1. **要单独登录一次**：CLI 与桌面端各用一份凭据（刷新令牌一次一换，共用会互相踢下线）。
+2. **连接器（MCP）的授权不跨客户端共享**：配置共享，但令牌不共享 ⇒ CLI 里每个 HTTP
+   连接器要重新「去认证」一次。
+3. **凭据目前是明文 `0600` 文件**（refresh 令牌寿命 30 天）。在共享机器上慎用 `--login`。
+
+## 当前未支持
+
+连接器「去认证」交互面板、计划条、作业角标面板、diff 分页、图片拖入、多行编辑框
+（TUI 逐行提交）、Windows 上的沙箱助手。
+
+## 环境变量
+
+| 变量 | 作用 |
+|---|---|
+| `DESKTOP_HOME` | 机器级根目录（默认 `~/.desktop-agents`）：账号、技能、日志都在这里 |
+| `PROTARA_ORIGIN` | 平台地址（等价于 `--origin`） |
+
+## 许可
+
+`UNLICENSED` —— 内部工具，不授权外部分发。

package/bin/protara.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * `protara` 的可执行入口（`bin/protara`）。
+ *
+ * ⚠️ 这是一个**极薄的垫片**，只有三件事：找到产物、调它、把退出码带出去。
+ * 所有逻辑都在 `dist/cli/index.cjs`（由 `scripts/build-main.mjs` 产出）。
+ *
+ * ## 为什么需要这一层（而不是直接 `main: dist/cli/index.cjs`）
+ *
+ * 1. `dist/cli/index.cjs` 是 **CJS**（包是 `type: module`，所以扩展名必须是 `.cjs`），
+ *    而 `bin` 的 shebang 指向 `node` —— 中间必须有一个能 `require` 的入口；
+ * 2. **产物不存在时要给人话**（「请先 npm run build」），而不是
+ *    `Cannot find module '…/dist/cli/index.cjs'` 这种把用户劝退的栈；
+ * 3. 退出码必须**显式**传出去（`process.exitCode = …`），否则一律是 0 —— 那会让
+ *    所有 CI 判据变成假绿。
+ */
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const bundle = join(here, '..', 'dist', 'cli', 'index.cjs')
+
+if (!existsSync(bundle)) {
+  process.stderr.write(
+    'protara: 还没有构建产物（dist/cli/index.cjs）。\n' +
+      'protara: 在仓库里跑一次 `npm run build:main` 即可。\n',
+  )
+  process.exitCode = 2 // 用法 / 环境错误，⛔ 不是「回合失败」
+} else {
+  const mod = await import(bundle)
+  const code = await mod.guardedMain(process.argv.slice(2))
+  process.exitCode = code
+}