arkclaw-webchat-cli 0.6.1__tar.gz → 0.9.0__tar.gz

{arkclaw_webchat_cli-0.6.1 → arkclaw_webchat_cli-0.9.0}/.gitignore

@@ -5,3 +5,7 @@ dist/
 build/
 .pytest_cache/
 .ruff_cache/
+
+# macOS / local agent state
+.DS_Store
+.agentkit/

{arkclaw_webchat_cli-0.6.1 → arkclaw_webchat_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arkclaw-webchat-cli
-Version: 0.6.1
+Version: 0.9.0
 Summary: CLI to chat with an ArkClaw EE space's Claw over enterprise SSO — zero permanent AK/SK.
 Author: ArkClaw Team
 Keywords: arkclaw,cli,ee,openclaw,sso,sts
@@ -14,6 +14,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Requires-Dist: keyring>=24.0
+Requires-Dist: msgpack>=1.0
 Requires-Dist: typer>=0.12.0
 Requires-Dist: websockets>=12.0
 Provides-Extra: dev
@@ -31,7 +32,7 @@ at a prompt and for another agent/script (`--json` + exit codes).
 ```bash
 arkclaw init        # one-time interactive setup (asks only what it can't auto-detect)
 arkclaw login       # browser SSO
-arkclaw agents      # list the claws you can chat
+arkclaw agents      # list the agents you can chat
 arkclaw chat ci-xxxxxxxx
 ```
 
@@ -40,10 +41,14 @@ arkclaw chat ci-xxxxxxxx
 ## What it can do
 
 - **Log in as you** — browser SSO (PKCE), short-lived token, auto-refresh. No AK/SK, no client secret, nothing permanent on disk but a token in your OS keychain.
-- **List your agents** — `arkclaw agents` shows the claws you've chatted with (kept locally; add one with `arkclaw chat ci-...`).
+- **List your agents** — `arkclaw agents` shows the agents in your accessible claws (add a claw by chatting it once: `arkclaw chat ci-...`).
+- **Manage agents** — `agents create` / `agents delete` add or remove named agents in a claw, right from the terminal.
 - **Chat** — interactive REPL or one-shot `-m`, streaming token-by-token, with a live "what's it doing" spinner and tool-event trace.
 - **Talk to a specific claw** — by id (`chat ci-...`) or by name (`chat 答疑助手`).
 - **Manage a claw's files** — read/write its managed workspace files (`AGENTS.md`, `SOUL.md`, `MEMORY.md`, …) with `ls` / `pull` / `push`.
+- **Upload & download any file** — push arbitrary files into the claw's *real* workspace filesystem and pull results back (a whole directory comes as a `.tar`) with `upload` / `download` / `mkdir` / `ls <path>`, over the Silk file service (needs a Silk-enabled claw).
+- **Large-product storage** — a separate IDS *netdisk* plane for big artifacts/videos: `netdisk create-space` / `ls` / `upload` / `download` / `mkdir` / `rm`.
+- **Read past conversations** — list an agent's sessions, then pull a full transcript with `arkclaw history <会话ID>` (over the `chat.history` ws RPC; `--json` to export, `-o` to a file).
 - **Fan out** — send one message to many claws in parallel.
 - **Be scripted** — every command takes `--json` (one clean `{ok,data,error}` envelope on stdout) and returns a typed exit code.
 
@@ -64,6 +69,9 @@ git clone <repo> && cd ee-claw
 uv venv && uv pip install -e .
 ```
 
+> **Contributing / hacking on the CLI?** Start with [`AGENTS.md`](./AGENTS.md) —
+> dev setup, the three gates, code map, invariants, and how to add a command/provider/transport.
+
 ---
 
 ## Quick start
@@ -99,14 +107,21 @@ straight to `arkclaw login https://your-space...`. See **[Configuration](#config
 |---|---|
 | `arkclaw init [address]` | One-time interactive setup. Saves the address + (only what isn't auto-discovered) the CLI client and STS role to `~/.arkclaw/defaults.json`, so later commands need no env/flags. |
 | `arkclaw login [space-url]` | Browser SSO login. Uses `init` defaults if you omit the URL. `--transport a2a --endpoint <url>` for an agent endpoint. `--clawid ci-...` sets a default claw. Bare `arkclaw login` re-logs into the previous space. |
-| `arkclaw agents` | List the claws you've used from this machine (local history, newest first) + your default claw. Add a claw by chatting it once (`arkclaw chat ci-...`). Not a space-wide directory. |
+| `arkclaw agents` | List the agents in your accessible claws (verified over the ws; inaccessible claws are pruned). Candidate claws = the ones you've used from this machine + your default — add one by chatting it once (`arkclaw chat ci-...`). Not a space-wide directory. |
+| `arkclaw agents create` | Create a named agent in a claw: `--name` `--role` `--soul` (+ optional `--description`, repeatable `--skill`). Then `chat <claw> --agent <agentId>`. |
+| `arkclaw agents delete <agent>` | Delete a named agent by agentId (`a-...`) or display name. Asks for confirmation unless `--yes`; the `main` agent is protected. |
 | `arkclaw chat [TARGET] [MSG]` | Chat. `TARGET` = a claw id (`ci-...`), an agent name (from `agents`), or a profile. With `MSG` → one-shot; without → interactive REPL. `-f` attach files, `-o` write the reply, `--session NAME` name the conversation, `--approve-all` auto-approve tool runs. |
 | `arkclaw <name>` | Shortcut: `arkclaw 答疑助手` ≡ `arkclaw chat 答疑助手`. |
-| `arkclaw ls` | List the claw's managed workspace files. |
-| `arkclaw pull <name> [local]` | Download a managed file to local disk. |
-| `arkclaw push <local> [name]` | Write a local text file into a managed file. |
+| `arkclaw ls [path]` | No `path` → the claw's managed brain files. With `path` → that workspace directory over Silk (the real filesystem). |
+| `arkclaw pull <name> [local]` | Download a **managed** file to local disk. |
+| `arkclaw push <local> [name]` | Write a local text file into a **managed** file. |
+| `arkclaw upload <local> [remote]` | Upload **any** file into the claw's workspace filesystem (Silk). Defaults to the basename at the workspace root. |
+| `arkclaw download <remote> [local]` | Download a workspace file from the claw (Silk); a directory comes as `<name>.tar`. |
+| `arkclaw mkdir <path>` | Create a directory in the claw workspace (Silk; parent must exist). |
+| `arkclaw netdisk <cmd>` | IDS netdisk (large products/videos), a separate storage plane: `create-space` / `ls` / `upload` / `download` / `mkdir` / `rm`. Configured via `IDS_*` env. |
 | `arkclaw fanout "<msg>" --clawid ci-a --clawid ci-b` | Same message to many claws in parallel. |
-| `arkclaw sessions` | Recent chat sessions on this machine. |
+| `arkclaw sessions [claw]` | An agent's conversations from the server (`--agent` to pick one), newest first — resume with `chat --session <会话ID>`, read with `history <会话ID>`, fork with `--new`. Falls back to the local record when offline / a2a. |
+| `arkclaw history <session>` | Print a past conversation's full transcript (ws `chat.history`). `<session>` = a 会话ID from `sessions`, a label, or a full `agent:…` key. Tool steps hidden unless `--show-tools`; `--json` dumps every message; `-o` writes a plain-text log. openclaw only. |
 | `arkclaw profile save/use/list` | Named snapshots of the session config (multi-space / multi-claw). |
 | `arkclaw doctor` | Self-check: login freshness, keychain, pool/STS/endpoint reachability. |
 | `arkclaw schema --json` | Machine-readable command surface (for agents/tooling). |
@@ -132,12 +147,21 @@ arkclaw chat ci-xxxx -f notes.md -m "review" -o out.md   # attach context, save
 
 ---
 
-## Files
+## Files & storage
+
+The CLI moves files across **three distinct planes** — pick by what you're carrying:
+
+| Plane | Commands | What lives there |
+|---|---|---|
+| **Managed brain** | `ls` · `pull` · `push` | The claw's own config files (`AGENTS.md`, `SOUL.md`, …). A fixed allow-list, not a general store. |
+| **Workspace (Silk)** | `ls <path>` · `upload` · `download` · `mkdir` | The claw's *real* working filesystem — arbitrary files, uploads, agent outputs, subdirectories. |
+| **Netdisk (IDS)** | `netdisk …` | A separate large-object store for big products/videos, on a dedicated storage account. |
 
-`ls` / `pull` / `push` operate on a claw's **managed workspace files** — its
-"brain": `AGENTS.md`, `SOUL.md`, `MEMORY.md`, `TOOLS.md`, `IDENTITY.md`,
-`USER.md`, `HEARTBEAT.md`. (This is not a general file store — arbitrary
-filenames are rejected.)
+### 1. Managed brain files — `ls` / `pull` / `push`
+
+The claw's "brain": `AGENTS.md`, `SOUL.md`, `MEMORY.md`, `TOOLS.md`,
+`IDENTITY.md`, `USER.md`, `HEARTBEAT.md`. A fixed allow-list — arbitrary
+filenames are rejected; `push` only writes text.
 
 ```bash
 arkclaw ls                          # list them (defaults to your default claw)
@@ -147,6 +171,51 @@ arkclaw push ./agents.md AGENTS.md  # write a managed file
 arkclaw ls --clawid ci-other        # a different claw
 ```
 
+### 2. Workspace filesystem — `upload` / `download` / `mkdir` / `ls <path>`
+
+The claw's **real** working filesystem (`/root/.openclaw/workspace`), over the
+Silk file service. Paths are workspace-relative. Use it to feed an agent input
+files and to retrieve whatever it produces.
+
+```bash
+arkclaw upload ./input.png             # → workspace root (basename)
+arkclaw upload ./data.csv runs/data.csv  # → a subpath
+arkclaw mkdir runs                     # parent must exist (non-recursive)
+arkclaw ls runs                        # list a workspace directory
+arkclaw download runs/output.mp4 ./out.mp4   # pull a result back
+arkclaw download runs ./runs.tar       # a directory downloads as a .tar
+```
+
+- **Requires a Silk-enabled claw.** A claw you can chat but that isn't
+  provisioned into Silk is rejected with a clear "未启用文件服务(Silk)" error
+  (`ErrClawInstanceNotFound`); Silk runs the *same* per-user gate as chat.
+- **Upload cap** is server-side (~25 MB per file); larger uploads return a clear
+  "文件超出上传上限" error.
+- There is **no `rm`** here — workspace deletes aren't exposed as a command.
+
+### 3. Netdisk (IDS) — `netdisk …`
+
+A separate storage plane for large products/videos, on a **dedicated IDS
+account** (not your SSO identity). Configured entirely from `IDS_*` env vars
+(provisioned by the storage team). Create a space once, then pass its `SpaceID`:
+
+```bash
+arkclaw netdisk create-space my-space            # → prints the SpaceID
+arkclaw netdisk mkdir outputs --space spc-...
+arkclaw netdisk upload ./final.mp4 outputs/final.mp4 --space spc-...
+arkclaw netdisk ls outputs/ --space spc-...
+arkclaw netdisk download outputs/final.mp4 ./final.mp4 --space spc-...
+arkclaw netdisk rm outputs/final.mp4 --space spc-...   # asks unless --yes
+```
+
+`create-space` also takes `--description`; `ls` takes `--limit N` to cap entries.
+
+| Env | Purpose |
+|---|---|
+| `IDS_BASE_URL` / `IDS_REGION` / `IDS_SERVICE` / `IDS_INSTANCE_ID` | Endpoint + routing for the IDS instance. |
+| `IDS_AK` / `IDS_SK` (+ `IDS_ACCOUNT_ID`) | Static credentials for the storage account… |
+| `IDS_ROLE_TRN` | …or assume a role via SSO instead of static AK/SK. |
+
 ---
 
 ## For agents / automation
@@ -183,15 +252,18 @@ values via env:
 | `ARKCLAW_CLIENT_ID` | The CLI's public OAuth client id for the pool. |
 | `ARKCLAW_ROLE_TRN` | STS role that mints the ChatToken (openclaw). |
 | `ARKCLAW_REGION` / `ARKCLAW_SPACE_ID` | Override region / space (usually auto). |
+| `ARKCLAW_API_HOST` / `ARKCLAW_API_SERVICE` | **Advanced/testing.** Point the control-plane calls at a non-production plane (host + SigV4 service). See the note below. |
 
 Other config: `~/.arkclaw/defaults.json` (`init` answers, 0600), `~/.arkclaw/session.json` (routing, 0600), `~/.arkclaw/cmdpolicy.json` (tool-approval allow/deny), OS keychain (tokens).
 
 > **Escape hatch (admin/test):** `arkclaw login <url> --transport openclaw --static-creds` uses `VOLCENGINE_ACCESS_KEY`/`SECRET_KEY` from the env instead of SSO — convenient for CI, but it's account-level keys, not identity-through.
 
+> **Control-plane override (advanced/testing):** by default every control-plane call (chat/terminal token mints, file/fleet actions, `doctor`) targets `arkclaw.<region>.volcengineapi.com` with SigV4 service `arkclaw`. Setting `ARKCLAW_API_HOST` + `ARKCLAW_API_SERVICE` retargets them — e.g. a non-production plane. The service is also the IAM action prefix, so a non-default service needs the matching role permissions. The host receives the **signed request including live temporary credentials**, so it must be a host you trust — only `*.volcengineapi.com` is accepted.
+
 ---
 
 ## Notes
 
-- `ls`/`pull`/`push` and a bare `chat` use your **default claw** (set at login, or the last one you opened in the browser); override with `--clawid` (or `chat ci-...`).
-- File commands cover the claw's **managed** files only; arbitrary file drop isn't exposed by the API.
+- `ls`/`pull`/`push`, `upload`/`download`/`mkdir`, and a bare `chat` use your **default claw** (set at login, or the last one you opened in the browser); override with `--clawid` (or `chat ci-...`).
+- `pull`/`push` reach the claw's **managed** files; `upload`/`download` reach its **workspace filesystem** (Silk, arbitrary files); `netdisk …` is a **separate** storage plane on its own account.
 - Nothing is hardcoded per space — the CLI reads what the space serves.

{arkclaw_webchat_cli-0.6.1 → arkclaw_webchat_cli-0.9.0}/README.md

@@ -7,7 +7,7 @@ at a prompt and for another agent/script (`--json` + exit codes).
 ```bash
 arkclaw init        # one-time interactive setup (asks only what it can't auto-detect)
 arkclaw login       # browser SSO
-arkclaw agents      # list the claws you can chat
+arkclaw agents      # list the agents you can chat
 arkclaw chat ci-xxxxxxxx
 ```
 
@@ -16,10 +16,14 @@ arkclaw chat ci-xxxxxxxx
 ## What it can do
 
 - **Log in as you** — browser SSO (PKCE), short-lived token, auto-refresh. No AK/SK, no client secret, nothing permanent on disk but a token in your OS keychain.
-- **List your agents** — `arkclaw agents` shows the claws you've chatted with (kept locally; add one with `arkclaw chat ci-...`).
+- **List your agents** — `arkclaw agents` shows the agents in your accessible claws (add a claw by chatting it once: `arkclaw chat ci-...`).
+- **Manage agents** — `agents create` / `agents delete` add or remove named agents in a claw, right from the terminal.
 - **Chat** — interactive REPL or one-shot `-m`, streaming token-by-token, with a live "what's it doing" spinner and tool-event trace.
 - **Talk to a specific claw** — by id (`chat ci-...`) or by name (`chat 答疑助手`).
 - **Manage a claw's files** — read/write its managed workspace files (`AGENTS.md`, `SOUL.md`, `MEMORY.md`, …) with `ls` / `pull` / `push`.
+- **Upload & download any file** — push arbitrary files into the claw's *real* workspace filesystem and pull results back (a whole directory comes as a `.tar`) with `upload` / `download` / `mkdir` / `ls <path>`, over the Silk file service (needs a Silk-enabled claw).
+- **Large-product storage** — a separate IDS *netdisk* plane for big artifacts/videos: `netdisk create-space` / `ls` / `upload` / `download` / `mkdir` / `rm`.
+- **Read past conversations** — list an agent's sessions, then pull a full transcript with `arkclaw history <会话ID>` (over the `chat.history` ws RPC; `--json` to export, `-o` to a file).
 - **Fan out** — send one message to many claws in parallel.
 - **Be scripted** — every command takes `--json` (one clean `{ok,data,error}` envelope on stdout) and returns a typed exit code.
 
@@ -40,6 +44,9 @@ git clone <repo> && cd ee-claw
 uv venv && uv pip install -e .
 ```
 
+> **Contributing / hacking on the CLI?** Start with [`AGENTS.md`](./AGENTS.md) —
+> dev setup, the three gates, code map, invariants, and how to add a command/provider/transport.
+
 ---
 
 ## Quick start
@@ -75,14 +82,21 @@ straight to `arkclaw login https://your-space...`. See **[Configuration](#config
 |---|---|
 | `arkclaw init [address]` | One-time interactive setup. Saves the address + (only what isn't auto-discovered) the CLI client and STS role to `~/.arkclaw/defaults.json`, so later commands need no env/flags. |
 | `arkclaw login [space-url]` | Browser SSO login. Uses `init` defaults if you omit the URL. `--transport a2a --endpoint <url>` for an agent endpoint. `--clawid ci-...` sets a default claw. Bare `arkclaw login` re-logs into the previous space. |
-| `arkclaw agents` | List the claws you've used from this machine (local history, newest first) + your default claw. Add a claw by chatting it once (`arkclaw chat ci-...`). Not a space-wide directory. |
+| `arkclaw agents` | List the agents in your accessible claws (verified over the ws; inaccessible claws are pruned). Candidate claws = the ones you've used from this machine + your default — add one by chatting it once (`arkclaw chat ci-...`). Not a space-wide directory. |
+| `arkclaw agents create` | Create a named agent in a claw: `--name` `--role` `--soul` (+ optional `--description`, repeatable `--skill`). Then `chat <claw> --agent <agentId>`. |
+| `arkclaw agents delete <agent>` | Delete a named agent by agentId (`a-...`) or display name. Asks for confirmation unless `--yes`; the `main` agent is protected. |
 | `arkclaw chat [TARGET] [MSG]` | Chat. `TARGET` = a claw id (`ci-...`), an agent name (from `agents`), or a profile. With `MSG` → one-shot; without → interactive REPL. `-f` attach files, `-o` write the reply, `--session NAME` name the conversation, `--approve-all` auto-approve tool runs. |
 | `arkclaw <name>` | Shortcut: `arkclaw 答疑助手` ≡ `arkclaw chat 答疑助手`. |
-| `arkclaw ls` | List the claw's managed workspace files. |
-| `arkclaw pull <name> [local]` | Download a managed file to local disk. |
-| `arkclaw push <local> [name]` | Write a local text file into a managed file. |
+| `arkclaw ls [path]` | No `path` → the claw's managed brain files. With `path` → that workspace directory over Silk (the real filesystem). |
+| `arkclaw pull <name> [local]` | Download a **managed** file to local disk. |
+| `arkclaw push <local> [name]` | Write a local text file into a **managed** file. |
+| `arkclaw upload <local> [remote]` | Upload **any** file into the claw's workspace filesystem (Silk). Defaults to the basename at the workspace root. |
+| `arkclaw download <remote> [local]` | Download a workspace file from the claw (Silk); a directory comes as `<name>.tar`. |
+| `arkclaw mkdir <path>` | Create a directory in the claw workspace (Silk; parent must exist). |
+| `arkclaw netdisk <cmd>` | IDS netdisk (large products/videos), a separate storage plane: `create-space` / `ls` / `upload` / `download` / `mkdir` / `rm`. Configured via `IDS_*` env. |
 | `arkclaw fanout "<msg>" --clawid ci-a --clawid ci-b` | Same message to many claws in parallel. |
-| `arkclaw sessions` | Recent chat sessions on this machine. |
+| `arkclaw sessions [claw]` | An agent's conversations from the server (`--agent` to pick one), newest first — resume with `chat --session <会话ID>`, read with `history <会话ID>`, fork with `--new`. Falls back to the local record when offline / a2a. |
+| `arkclaw history <session>` | Print a past conversation's full transcript (ws `chat.history`). `<session>` = a 会话ID from `sessions`, a label, or a full `agent:…` key. Tool steps hidden unless `--show-tools`; `--json` dumps every message; `-o` writes a plain-text log. openclaw only. |
 | `arkclaw profile save/use/list` | Named snapshots of the session config (multi-space / multi-claw). |
 | `arkclaw doctor` | Self-check: login freshness, keychain, pool/STS/endpoint reachability. |
 | `arkclaw schema --json` | Machine-readable command surface (for agents/tooling). |
@@ -108,12 +122,21 @@ arkclaw chat ci-xxxx -f notes.md -m "review" -o out.md   # attach context, save
 
 ---
 
-## Files
+## Files & storage
+
+The CLI moves files across **three distinct planes** — pick by what you're carrying:
+
+| Plane | Commands | What lives there |
+|---|---|---|
+| **Managed brain** | `ls` · `pull` · `push` | The claw's own config files (`AGENTS.md`, `SOUL.md`, …). A fixed allow-list, not a general store. |
+| **Workspace (Silk)** | `ls <path>` · `upload` · `download` · `mkdir` | The claw's *real* working filesystem — arbitrary files, uploads, agent outputs, subdirectories. |
+| **Netdisk (IDS)** | `netdisk …` | A separate large-object store for big products/videos, on a dedicated storage account. |
 
-`ls` / `pull` / `push` operate on a claw's **managed workspace files** — its
-"brain": `AGENTS.md`, `SOUL.md`, `MEMORY.md`, `TOOLS.md`, `IDENTITY.md`,
-`USER.md`, `HEARTBEAT.md`. (This is not a general file store — arbitrary
-filenames are rejected.)
+### 1. Managed brain files — `ls` / `pull` / `push`
+
+The claw's "brain": `AGENTS.md`, `SOUL.md`, `MEMORY.md`, `TOOLS.md`,
+`IDENTITY.md`, `USER.md`, `HEARTBEAT.md`. A fixed allow-list — arbitrary
+filenames are rejected; `push` only writes text.
 
 ```bash
 arkclaw ls                          # list them (defaults to your default claw)
@@ -123,6 +146,51 @@ arkclaw push ./agents.md AGENTS.md  # write a managed file
 arkclaw ls --clawid ci-other        # a different claw
 ```
 
+### 2. Workspace filesystem — `upload` / `download` / `mkdir` / `ls <path>`
+
+The claw's **real** working filesystem (`/root/.openclaw/workspace`), over the
+Silk file service. Paths are workspace-relative. Use it to feed an agent input
+files and to retrieve whatever it produces.
+
+```bash
+arkclaw upload ./input.png             # → workspace root (basename)
+arkclaw upload ./data.csv runs/data.csv  # → a subpath
+arkclaw mkdir runs                     # parent must exist (non-recursive)
+arkclaw ls runs                        # list a workspace directory
+arkclaw download runs/output.mp4 ./out.mp4   # pull a result back
+arkclaw download runs ./runs.tar       # a directory downloads as a .tar
+```
+
+- **Requires a Silk-enabled claw.** A claw you can chat but that isn't
+  provisioned into Silk is rejected with a clear "未启用文件服务(Silk)" error
+  (`ErrClawInstanceNotFound`); Silk runs the *same* per-user gate as chat.
+- **Upload cap** is server-side (~25 MB per file); larger uploads return a clear
+  "文件超出上传上限" error.
+- There is **no `rm`** here — workspace deletes aren't exposed as a command.
+
+### 3. Netdisk (IDS) — `netdisk …`
+
+A separate storage plane for large products/videos, on a **dedicated IDS
+account** (not your SSO identity). Configured entirely from `IDS_*` env vars
+(provisioned by the storage team). Create a space once, then pass its `SpaceID`:
+
+```bash
+arkclaw netdisk create-space my-space            # → prints the SpaceID
+arkclaw netdisk mkdir outputs --space spc-...
+arkclaw netdisk upload ./final.mp4 outputs/final.mp4 --space spc-...
+arkclaw netdisk ls outputs/ --space spc-...
+arkclaw netdisk download outputs/final.mp4 ./final.mp4 --space spc-...
+arkclaw netdisk rm outputs/final.mp4 --space spc-...   # asks unless --yes
+```
+
+`create-space` also takes `--description`; `ls` takes `--limit N` to cap entries.
+
+| Env | Purpose |
+|---|---|
+| `IDS_BASE_URL` / `IDS_REGION` / `IDS_SERVICE` / `IDS_INSTANCE_ID` | Endpoint + routing for the IDS instance. |
+| `IDS_AK` / `IDS_SK` (+ `IDS_ACCOUNT_ID`) | Static credentials for the storage account… |
+| `IDS_ROLE_TRN` | …or assume a role via SSO instead of static AK/SK. |
+
 ---
 
 ## For agents / automation
@@ -159,15 +227,18 @@ values via env:
 | `ARKCLAW_CLIENT_ID` | The CLI's public OAuth client id for the pool. |
 | `ARKCLAW_ROLE_TRN` | STS role that mints the ChatToken (openclaw). |
 | `ARKCLAW_REGION` / `ARKCLAW_SPACE_ID` | Override region / space (usually auto). |
+| `ARKCLAW_API_HOST` / `ARKCLAW_API_SERVICE` | **Advanced/testing.** Point the control-plane calls at a non-production plane (host + SigV4 service). See the note below. |
 
 Other config: `~/.arkclaw/defaults.json` (`init` answers, 0600), `~/.arkclaw/session.json` (routing, 0600), `~/.arkclaw/cmdpolicy.json` (tool-approval allow/deny), OS keychain (tokens).
 
 > **Escape hatch (admin/test):** `arkclaw login <url> --transport openclaw --static-creds` uses `VOLCENGINE_ACCESS_KEY`/`SECRET_KEY` from the env instead of SSO — convenient for CI, but it's account-level keys, not identity-through.
 
+> **Control-plane override (advanced/testing):** by default every control-plane call (chat/terminal token mints, file/fleet actions, `doctor`) targets `arkclaw.<region>.volcengineapi.com` with SigV4 service `arkclaw`. Setting `ARKCLAW_API_HOST` + `ARKCLAW_API_SERVICE` retargets them — e.g. a non-production plane. The service is also the IAM action prefix, so a non-default service needs the matching role permissions. The host receives the **signed request including live temporary credentials**, so it must be a host you trust — only `*.volcengineapi.com` is accepted.
+
 ---
 
 ## Notes
 
-- `ls`/`pull`/`push` and a bare `chat` use your **default claw** (set at login, or the last one you opened in the browser); override with `--clawid` (or `chat ci-...`).
-- File commands cover the claw's **managed** files only; arbitrary file drop isn't exposed by the API.
+- `ls`/`pull`/`push`, `upload`/`download`/`mkdir`, and a bare `chat` use your **default claw** (set at login, or the last one you opened in the browser); override with `--clawid` (or `chat ci-...`).
+- `pull`/`push` reach the claw's **managed** files; `upload`/`download` reach its **workspace filesystem** (Silk, arbitrary files); `netdisk …` is a **separate** storage plane on its own account.
 - Nothing is hardcoded per space — the CLI reads what the space serves.

{arkclaw_webchat_cli-0.6.1 → arkclaw_webchat_cli-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arkclaw-webchat-cli"
-version = "0.6.1"
+version = "0.9.0"
 description = "CLI to chat with an ArkClaw EE space's Claw over enterprise SSO — zero permanent AK/SK."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -24,6 +24,7 @@ dependencies = [
     "typer>=0.12.0",
     "websockets>=12.0",
     "keyring>=24.0",
+    "msgpack>=1.0",
 ]
 
 [project.optional-dependencies]

{arkclaw_webchat_cli-0.6.1 → arkclaw_webchat_cli-0.9.0}/src/ee_claw/attachments.py

@@ -11,11 +11,25 @@ import pathlib
 from ee_claw.errors import ValidationError
 from ee_claw.transport.base import Attachment
 
-MAX_FILE_BYTES = 64 * 1024
-MAX_TOTAL_BYTES = 256 * 1024
+# Text attachments inline into the prompt, so they stay tight; binary ones
+# (images, pdf, …) ride the native chat.send `attachments` field and only need
+# to fit under the server's ws payload cap (~25MB; base64 inflates ×4/3).
+MAX_FILE_BYTES = 64 * 1024                 # per text file (inlined into the prompt)
+MAX_BINARY_FILE_BYTES = 10 * 1024 * 1024   # per binary file (native attachment)
+MAX_TOTAL_BYTES = 12 * 1024 * 1024         # across all attachments in one turn
 MAX_FILES = 32
 
 
+def _is_text(content: bytes) -> bool:
+    """UTF-8-decodable → treat as text (inline-able); otherwise binary (rides
+    the native attachment field as raw bytes)."""
+    try:
+        content.decode("utf-8")
+        return True
+    except UnicodeDecodeError:
+        return False
+
+
 def collect_files(paths: list[str]) -> tuple[list[Attachment], list[str]]:
     """Read files (and directories, shallow-recursively) into attachments.
     Returns ``(attachments, notices)`` — notices describe everything that was
@@ -54,11 +68,20 @@ def collect_files(paths: list[str]) -> tuple[list[Attachment], list[str]]:
         except OSError as e:
             notices.append(f"读不了 {f}: {e.__class__.__name__}")
             continue
-        if len(content) > MAX_FILE_BYTES:
-            notices.append(f"{f.name} 截断到 {MAX_FILE_BYTES // 1024}KB(原 {len(content)} 字节)")
-            content = content[:MAX_FILE_BYTES]
+        if _is_text(content):
+            # text inlines into the prompt — truncating just shortens context
+            if len(content) > MAX_FILE_BYTES:
+                notices.append(f"{f.name} 截断到 {MAX_FILE_BYTES // 1024}KB(原 {len(content)} 字节)")
+                content = content[:MAX_FILE_BYTES]
+        elif len(content) > MAX_BINARY_FILE_BYTES:
+            # NEVER truncate binary — half an image is corrupt; skip it, loudly
+            notices.append(
+                f"{f.name} 超出 {MAX_BINARY_FILE_BYTES // 1024 // 1024}MB 二进制上限,已跳过"
+                f"(原 {len(content)} 字节)"
+            )
+            continue
         if total + len(content) > MAX_TOTAL_BYTES:
-            notices.append(f"总量超出 {MAX_TOTAL_BYTES // 1024}KB,从 {f.name} 起丢弃")
+            notices.append(f"总量超出 {MAX_TOTAL_BYTES // 1024 // 1024}MB,从 {f.name} 起丢弃")
             break
         total += len(content)
         mime = mimetypes.guess_type(f.name)[0] or "application/octet-stream"