@cryer/star-cli 0.3.5 → 0.3.7

package/README.md

@@ -46,55 +46,84 @@ Without `npm link` you can run the bundle directly: `node dist/main.js` (re-run
 
 ## Configuration
 
-Config file: `~/.star-cli/config.toml` (project-level override: `.star/config.toml` in cwd; CLI flags win over both).
+Config file: `~/.star-cli/config.toml` (set the `STAR_HOME` environment variable to use a different home than `~/.star-cli`; project-level override: `.star/config.toml` in cwd, sandboxed to safe keys only; CLI flags win over both).
 
 ```toml
-defaultModel = "gpt"
-permissionMode = "ask"   # ask | auto | readonly | yolo | plan
-contextMaxTokens = 100000
+defaultModel = "gpt"              # name of the [[models]] block used by default
+permissionMode = "ask"            # ask | auto | readonly | yolo | plan
+contextMaxTokens = 100000         # context window in tokens (per-model override below)
+# compactThresholdTokens = 80000  # optional auto-compaction trigger in tokens; defaults to the
+                                  # context window and is clamped to it (top-level only — there is
+                                  # no per-model override). /compact always compacts, regardless.
 # Max model round-trips ("steps") per turn between progress checkpoints — one
 # step is a reply plus the tool calls it asked for; retries and auto-continue
 # nudges don't count. Reaching the cap while tools still execute resets it
 # with a notice instead of stopping the turn; 0 disables the cap entirely.
 maxSteps = 100
-# compactThresholdTokens = 80000   # optional auto-compaction trigger in tokens; defaults to the
-                                  # context window. /compact always compacts, regardless of this.
-contextCompaction = "summary"   # summary | truncate — how over-budget history is compacted
-# Seconds with no stream output before a stalled response is ended gracefully
-# (some relays never close the stream). The first token gets a fixed 120s allowance.
-streamIdleTimeoutSec = 20
-# sessionBudgetUsd = 5          # optional per-session cost cap in USD; unset = no cap
-notifyBell = true              # ring the terminal bell when a long turn finishes (REPL only)
-notifyBellThresholdSec = 10    # turns shorter than this stay silent
+contextCompaction = "summary"     # summary | truncate — how over-budget history is compacted
+streamMaxRetries = 5              # extra attempts per model request on transient failures
+                                  # (network error, 429/5xx, idle cutoff, empty reply); 0 disables
+streamIdleTimeoutSec = 20         # seconds with no stream output before a stalled response is
+                                  # ended gracefully (some relays never close the stream)
+streamFirstChunkTimeoutSec = 300  # seconds to wait for the very first content part — slow
+                                  # thinking-model endpoints can stay silent for minutes
+maxAutoContinues = 2              # nudges for consecutive unproductive text-only replies before
+                                  # the turn is handed back; tool calls reset the count; 0 disables
+doomLoopThreshold = 3             # consecutive identical tool calls before the loop refuses the
+                                  # repeat and tells the model to change approach; 0 disables
+gitSnapshots = true               # track the whole working tree each turn (internal repo outside
+                                  # your .git) so /undo and /redo also cover bash-made changes
+# sessionBudgetUsd = 5            # optional per-session cost cap in USD; unset = no cap
+notifyBell = true                 # ring the terminal bell when a long turn finishes (REPL only)
+notifyBellThresholdSec = 10       # turns shorter than this stay silent
 
 [permissions]
-# persistent allow-rules, written automatically when you pick "a" (always) on a permission prompt
-allow = ["bash(npm test)", "read_file"]   # <tool> or <tool(<pattern>)>, * is a glob wildcard
-# persistent deny-rules — checked after the hard safety rules; they beat auto mode
-# and allow-rules (yolo still bypasses everything)
+# persistent allow-rules, written automatically when you pick "a" (always) on a permission prompt.
+# Syntax: <tool> or <tool(<pattern>)>, * is a glob wildcard. A bash rule is matched per command
+# segment (the command line is split on shell separators): an allow rule must match EVERY segment,
+# and any command substitution or file redirection disables auto-allow entirely.
+allow = ["bash(npm test)", "read_file"]
+# persistent deny-rules — checked after the hard safety rules; a deny matching ANY segment beats
+# auto mode and allow-rules (yolo still bypasses everything)
 deny = ["bash(rm -rf *)"]
 
 [[providers]]
 name = "openai"
-protocol = "openai-compatible"
+protocol = "openai-compatible"    # openai-compatible | anthropic | openai-responses
 baseURL = "https://api.openai.com/v1"
-apiKeyEnv = "OPENAI_API_KEY"
-# protocol = "openai-responses"  # for relays exposing only /v1/responses
+apiKeyEnv = "OPENAI_API_KEY"      # recommended: name of the env var holding the key — keys live in
+                                  # ~/.star-cli/.env (written by /connect), never in this file
+# apiKey = "sk-..."               # inline key instead of apiKeyEnv (not recommended)
+# headers = { "X-Title" = "star-cli" }   # extra HTTP headers sent with every request
+# protocol = "openai-responses"   # for relays exposing only /v1/responses
 
 [[models]]
-name = "gpt"
-provider = "openai"
-model = "gpt-4o"
-# optional per-model context window — overrides the top-level contextMaxTokens
-# for compaction and the ctx % in the status bar
-# contextMaxTokens = 272000
-# optional per-model pricing in USD per 1M tokens — enables the $ estimate in
-# /cost and /usage. promptPrice prices input tokens (system prompt, history,
-# @file contents, tool results — resent every turn, so the bulk of usage);
-# completionPrice prices output tokens (the model's replies and tool calls —
-# less volume, usually the pricier rate). BOTH fields are required together.
+name = "gpt"                      # referenced by defaultModel and -m
+provider = "openai"               # name of a [[providers]] block
+model = "gpt-4o"                  # model id sent to the API
+# maxTokens = 8192                # cap on generated tokens per reply
+# contextMaxTokens = 272000       # per-model context window — overrides the top-level
+                                  # contextMaxTokens for compaction and the ctx % in the status bar
+# temperature = 1                 # sampling temperature forwarded on every request. Unset = the AI
+                                  # SDK default applies (ai@4 sends 0 — it does NOT omit the field),
+                                  # so endpoints that mandate one explicit value (kimi-for-coding/k3
+                                  # accept only 1) MUST set it here.
+# reasoningEffort = "high"        # reasoning intensity for thinking models, forwarded verbatim as
+                                  # reasoning_effort on every request. Level naming varies by
+                                  # provider (low/medium/high are common; some add minimal/max...).
+                                  # Unset = server default. Ignored for anthropic. The /model
+                                  # picker also offers these levels after a model pick.
+# streamIdleTimeoutSec = 60       # per-model overrides of the global stream watchdog timeouts
+# streamFirstChunkTimeoutSec = 600
+# optional per-model pricing in USD per 1M tokens — enables the $ estimate in /cost and /usage.
+# promptPrice prices input tokens (system prompt, history, @file contents, tool results — resent
+# every turn, so the bulk of usage); completionPrice prices output tokens (the model's replies and
+# tool calls — less volume, usually the pricier rate). BOTH fields are required together.
 promptPrice = 2.5
 completionPrice = 10
+# cacheReadPrice = 0.25           # optional price for cache-read prompt tokens; unset = OpenAI-style
+                                  # cached tokens bill at promptPrice and Anthropic-style cache
+                                  # reads are not billed
 
 [[providers]]
 name = "claude"
@@ -110,13 +139,45 @@ model = "claude-sonnet-4-20250514"
 [[hooks]]
 event = "PostToolUse"                  # PreToolUse | PostToolUse | Stop
 matcher = "edit_file|write_file"       # optional regex on the tool name; matches all tools when omitted
-command = "biome check --write ."
-# timeoutSec = 30                      # optional per-hook timeout
+command = "biome check --write ."      # PreToolUse exiting with code 2 blocks the tool (stderr
+                                       # becomes its result); Stop fires on every turn end
+# timeoutSec = 30                      # optional per-hook timeout (default 30; on timeout the hook
+                                       # is allowed through with a warning)
 ```
 
 API keys resolve from the environment variable first (`apiKeyEnv`), then the `apiKey` field in the config file. On startup Star CLI also loads `~/.star-cli/.env` (dotenv-style `KEY=VALUE` lines) into the environment without overwriting variables that are already set — this is where `/connect` stores the keys it collects, so `config.toml` only ever references the variable name, never the key itself.
 
-The fastest way to set up a provider is the `/connect` wizard inside the REPL: pick a preset (OpenAI, Anthropic, Kimi/Moonshot, DeepSeek) or a custom endpoint, paste the API key (masked while typing), name a model, and it appends the `[[providers]]`/`[[models]]` blocks to `config.toml` (existing content and comments preserved), writes the key to `~/.star-cli/.env` (as `STAR_API_KEY_<NAME>`, file mode 600 where the platform honors it), and optionally makes the new model the default — all without restarting.
+The fastest way to set up a provider is the `/connect` wizard inside the REPL: pick a preset (OpenAI, Anthropic, Kimi/Moonshot, DeepSeek) or a custom endpoint, paste the API key (masked while typing), name a model, and it appends the `[[providers]]`/`[[models]]` blocks to `config.toml` (existing content and comments preserved), writes the key to `~/.star-cli/.env` (as `STAR_API_KEY_<NAME>`, file mode 600 where the platform honors it), and optionally makes the new model the default — all without restarting. The written `[[models]]` block comes with `contextMaxTokens = 128000` and `temperature = 1` (a safe default — coding models like kimi-for-coding/k3 reject any other value; lower it only for models that allow it) plus zero placeholder prices — edit all three to the real limits and rates as needed.
+
+### Using a relay (中转站)
+
+Third-party relays usually front one of the standard wire formats: set `protocol` to `openai-responses` when the relay exposes the Responses API (`/responses`), otherwise `openai-compatible` (`/chat/completions`).
+
+Many relays buffer a whole generation before flushing — tens of seconds to minutes can pass without a single SSE chunk, which looks like a dead stream. Star CLI timestamps the raw response bytes of every request: as long as bytes keep flowing (including SSE heartbeat comments the SDK itself swallows) the stream watchdog is extended instead of cutting the relay off mid-generation, bounded by a 10-minute cap on total part silence so a heartbeat-only zombie can't hang a turn. If a relay still triggers frequent idle timeouts, raise the model's own watchdogs:
+
+```toml
+[[providers]]
+name = "kimi"
+protocol = "openai-responses"
+baseURL = "https://api.kimi.com/coding/v1"   # official Kimi coding endpoint
+apiKeyEnv = "STAR_API_KEY_KIMI"
+
+[[models]]
+name = "kimi"
+provider = "kimi"
+model = "kimi-for-coding"
+temperature = 1        # mandatory here — the endpoint rejects any other value
+contextMaxTokens = 128000
+# raise these when the relay buffers long generations:
+# streamIdleTimeoutSec = 60        # default 20
+# streamFirstChunkTimeoutSec = 600 # default 300
+```
+
+### Environment variables
+
+- `STAR_HOME` — overrides `~/.star-cli` as the data home (config, sessions, `.env`, memory, debug log).
+- `STAR_DEBUG` — any non-empty value enables stream diagnostics appended to `~/.star-cli/debug.log`, one JSON object per line.
+- `STAR_NO_NOTIFY=1` — disables the terminal bell without touching the config.
 
 
 ## CLI flags
@@ -171,9 +232,7 @@ star --clear-sessions all     delete every stored session
 
 Keys: `ESC` / `Ctrl+C` interrupts the current stream — the partial reply generated so far stays on screen (and in the session history) with a dim `[interrupted]` marker; on a permission prompt: `y` allow, `n` deny, `a` always allow — the generated allow-rule (e.g. `bash(npm test)`) is saved to `permissions.allow` in the config file and survives restarts. Write/edit prompts include a colored diff preview of the pending change. `Shift+Tab` cycles the permission mode for the session (`ask` → `auto` → `readonly` → `plan`; not saved to config). Input editing: arrow keys move the cursor, `Ctrl+A`/`Ctrl+E` jump to start/end, `Ctrl+U`/`Ctrl+K` delete before/after the cursor, `Ctrl+W` deletes the previous word, up/down recall history (persisted to `~/.star-cli/history` across sessions, capped at 50 entries, consecutive duplicates collapsed, slash commands and key-repeat garbage never recorded); while a recalled entry is unmodified up/down keep switching entries, but once you edit the text — or are typing your own multi-line input — up/down move the cursor between lines instead. `Ctrl+R` starts a reverse history search: type to filter (case-insensitive, newest match first), `Ctrl+R`/`↑` for older matches, `↓` for newer, `Enter` to accept the match into the input, `ESC`/`Ctrl+C`/`Ctrl+G` to cancel and restore what you had. Multi-line input: use `Ctrl+J` (or `Alt+Enter`), or end the line with `\` and press `Enter` — pasted multi-line text is kept intact. Pasting a large block (10+ lines or 500+ characters in one go) collapses it into a dim `[pasted #N: L lines]` placeholder so the input box stays compact; the full text is restored into what gets submitted, and `Backspace` removes the placeholder as a unit. A huge paste that the terminal delivers in several chunks is reassembled (via bracketed paste where the terminal supports it) and still collapses into a single placeholder. Typing `/` shows slash-command suggestions with their usage — prefix matches first, then fuzzy subsequence matches; `↑`/`↓` to highlight, `Tab` (or `→` at end of input) to complete, `ESC` to dismiss, and an unknown command name gets a `Did you mean: …` hint. Typing `@` completes file paths relative to the working directory with the same keys; directories end in `/` so `Tab` descends, and `node_modules`, `.git`, `dist` and `.starignore` entries are skipped. `Alt+V` pastes an image from the clipboard as an attachment (each one shows as `[image attached: clipboard.png]` above the input; uses PowerShell on Windows, pngpaste/osascript on macOS, xclip on Linux). Images larger than 2000px on the longest side are automatically downsampled to fit (keeping the aspect ratio, via platform-native tools — no extra installs on Windows/macOS; ImageMagick or ffmpeg on Linux); when resizing isn't possible the original is kept and a warning is shown. `Ctrl+V` also works where the terminal passes it through — Windows Terminal binds Ctrl+V to its own paste, so use `Alt+V` there. While a turn is streaming you can keep typing: submitted prompts (and `!` bangs) queue up as dimmed entries and auto-send in order once the turn finishes; `ESC` during a turn aborts it and clears the queue (the partial reply is kept, marked `[interrupted]`). Pressing `ESC` twice within half a second while idle retracts your last prompt and restores its text into the input for editing.
 
-While the model is working, a spinner (`- \ | /`) shows `star is thinking…`; reasoning models also stream a dimmed tail of their thinking (last ~200 chars), which collapses to a one-line summary once the answer starts. Streamed replies, reasoning, tool output and todo titles are sanitized for display (tabs expanded to two spaces, control bytes and raw escape sequences stripped) so relayed model output cannot corrupt the terminal or leave stale frames piling up; long todo lists collapse to a 10-row window around the active task and long typeahead queues to their first 5 entries, keeping the live area well below terminal height.
-
-The status bar shows the working directory (full path on wide terminals), the git branch, the model, the permission mode, context usage as a percentage of the model's context window (its own `contextMaxTokens` when set, else the top-level one), the session prompt-cache hit rate when the provider reports cache usage (`cache: 42%`, or `cache: Not provided` when it never does), the session cost when the model has pricing configured, and total tokens.
+The status bar shows the working directory (full path on wide terminals), the git branch, the model, the permission mode, context usage as a percentage of the model's context window (its own `contextMaxTokens` when set, else the top-level one), the session prompt-cache hit rate when the provider reports cache usage (`cache: 42%`, or `cache: Not provided` when it never does), the session cost when the model has pricing configured, and total tokens. Model replies render as markdown (headings, emphasis, code blocks, tables) directly in the terminal. Decorative icons use emoji on terminals known to render them double-width (Windows Terminal, VS Code, Kitty, …) and fall back to plain symbols elsewhere so the display never desyncs; force a style with `STAR_ICONS=emoji|plain`.
 
 ## !shell passthrough
 
@@ -289,7 +348,7 @@ A `.starignore` file in the working directory hides paths from the agent: the `g
 
 ## Built-in tools
 
-`read_file`, `write_file`, `edit_file`, `glob`, `grep`, `bash`, `web_fetch`, `web_search` (DuckDuckGo, no API key needed), `todo_read`, `todo_write`, `task_list`, `task_output`, `task_kill`, `subagent`, `skill`, `remember` — each declares a permission level (`read` / `write` / `exec`) enforced by the permission gate. Hard safety rules (dangerous shell commands, paths outside the working directory, secret files like `.env` / private keys) are denied in `ask` / `auto` / `readonly` and cannot be overridden by allow-rules.
+`read_file`, `read_image` (attach an image file to the conversation mid-session — screenshots, mockups; png/jpg/gif/webp, auto-downsampled past 2000px), `write_file`, `edit_file`, `glob`, `grep`, `bash`, `web_fetch`, `web_search` (DuckDuckGo, no API key needed), `todo_read`, `todo_write`, `task_list`, `task_output`, `task_kill`, `subagent`, `skill`, `remember` — each declares a permission level (`read` / `write` / `exec`) enforced by the permission gate. Hard safety rules (dangerous shell commands, paths outside the working directory, secret files like `.env` / private keys) are denied in `ask` / `auto` / `readonly` and cannot be overridden by allow-rules.
 
 The `subagent` tool (`exec` level, so it is hidden in plan mode and denied in readonly) spawns a child agent loop with the same built-in tools to handle a focused, self-contained subtask — research, exploration, or an isolated change — and returns the child's final report as the tool result. Subagents run one level deep (a subagent cannot spawn further subagents), share the parent's permission mode and confirmation prompt, and their conversation is not persisted to the session.
 

package/README.zh-CN.md

@@ -46,54 +46,81 @@ star -p "hi"             # non-interactive print mode
 
 ## 配置
 
-配置文件：`~/.star-cli/config.toml`（项目级覆盖：当前目录下的 `.star/config.toml`；CLI 参数优先于两者）。
+配置文件：`~/.star-cli/config.toml`（可用环境变量 `STAR_HOME` 把数据目录改为 `~/.star-cli` 以外的位置；项目级覆盖：当前目录下的 `.star/config.toml`，经过沙箱过滤只保留安全键；CLI 参数优先于两者）。
 
 ```toml
-defaultModel = "gpt"
-permissionMode = "ask"   # ask | auto | readonly | yolo | plan
-contextMaxTokens = 100000
+defaultModel = "gpt"              # 默认使用的 [[models]] 块名称
+permissionMode = "ask"            # ask | auto | readonly | yolo | plan
+contextMaxTokens = 100000         # 上下文窗口（token 数，下方可按模型覆盖）
+# compactThresholdTokens = 80000  # 可选的自动压缩触发阈值（token 数）；默认为上下文窗口本身，
+                                  # 且会被钳制到窗口以内（仅顶层键——没有按模型覆盖）。
+                                  # /compact 无视此阈值，总是执行压缩。
 # 每回合在进度检查点之间允许的最大模型往返（"step"）数——一个 step 是
 # 一次回复加上它请求的所有工具调用；重试和 auto-continue nudge 不占 step。
 # 到达上限时若工具仍在执行，会发提示并重置额度而不是终止回合；0 表示完全不限。
 maxSteps = 100
-# compactThresholdTokens = 80000   # optional auto-compaction trigger in tokens; defaults to the
-                                  # context window. /compact always compacts, regardless of this.
-contextCompaction = "summary"   # summary | truncate — how over-budget history is compacted
-# Seconds with no stream output before a stalled response is ended gracefully
-# (some relays never close the stream). The first token gets a fixed 120s allowance.
-streamIdleTimeoutSec = 20
-# sessionBudgetUsd = 5          # optional per-session cost cap in USD; unset = no cap
-notifyBell = true              # ring the terminal bell when a long turn finishes (REPL only)
-notifyBellThresholdSec = 10    # turns shorter than this stay silent
+contextCompaction = "summary"     # summary | truncate —— 历史超出预算时的压缩方式
+streamMaxRetries = 5              # 单次模型请求在瞬时失败（网络错误、429/5xx、idle 截断、
+                                  # 空回复）时的额外重试次数；0 表示禁用
+streamIdleTimeoutSec = 20         # 流没有任何输出的秒数，超过后将停滞的响应优雅结束
+                                  #（有些中转站从不关闭流）
+streamFirstChunkTimeoutSec = 300  # 等待第一个内容分片的秒数——慢速思考模型端点在接受请求后
+                                  # 可能静默数分钟
+maxAutoContinues = 2              # 连续无产出的纯文本回复在被 nudge 多少次后交还回合；
+                                  # 工具调用会重置计数；0 表示禁用
+doomLoopThreshold = 3             # 连续相同工具调用达到此次数后，循环拒绝执行该重复调用
+                                  # 并要求模型换思路；0 表示禁用
+gitSnapshots = true               # 每回合用内部 git 仓库（位于你的 .git 之外）跟踪整个工作树，
+                                  # 使 /undo 和 /redo 也能覆盖 bash 造成的改动
+# sessionBudgetUsd = 5            # 可选的每会话成本上限（美元）；不设置 = 无上限
+notifyBell = true                 # 长回合结束时响终端铃（仅 REPL）
+notifyBellThresholdSec = 10       # 短于此耗时的回合不响铃
 
 [permissions]
-# persistent allow-rules, written automatically when you pick "a" (always) on a permission prompt
-allow = ["bash(npm test)", "read_file"]   # <tool> or <tool(<pattern>)>, * is a glob wildcard
-# persistent deny-rules — checked after the hard safety rules; they beat auto mode
-# and allow-rules (yolo still bypasses everything)
+# 持久 allow 规则——在权限提示上选择 "a"（始终允许）时自动写入。
+# 语法：<tool> 或 <tool(<pattern>)>，* 是 glob 通配符。bash 规则按命令分段匹配
+#（命令行先按 shell 分隔符切分）：allow 规则必须匹配每一段，且命令中含有命令替换
+# 或文件重定向时完全不会自动放行。
+allow = ["bash(npm test)", "read_file"]
+# 持久 deny 规则——在硬性安全规则之后检查；deny 命中任意一段即优先于 auto 模式和
+# allow 规则（yolo 仍然绕过一切）
 deny = ["bash(rm -rf *)"]
 
 [[providers]]
 name = "openai"
-protocol = "openai-compatible"
+protocol = "openai-compatible"    # openai-compatible | anthropic | openai-responses
 baseURL = "https://api.openai.com/v1"
-apiKeyEnv = "OPENAI_API_KEY"
-# protocol = "openai-responses"  # for relays exposing only /v1/responses
+apiKeyEnv = "OPENAI_API_KEY"      # 推荐：存放密钥的环境变量名——密钥本体放在
+                                  # ~/.star-cli/.env（由 /connect 写入），绝不出现在本文件
+# apiKey = "sk-..."               # 不用 apiKeyEnv 而直接内联密钥（不推荐）
+# headers = { "X-Title" = "star-cli" }   # 随每次请求发送的额外 HTTP 头
+# protocol = "openai-responses"   # 适用于只暴露 /v1/responses 的中转站
 
 [[models]]
-name = "gpt"
-provider = "openai"
-model = "gpt-4o"
-# optional per-model context window — overrides the top-level contextMaxTokens
-# for compaction and the ctx % in the status bar
-# contextMaxTokens = 272000
-# optional per-model pricing in USD per 1M tokens — enables the $ estimate in
-# /cost and /usage. promptPrice prices input tokens (system prompt, history,
-# @file contents, tool results — resent every turn, so the bulk of usage);
-# completionPrice prices output tokens (the model's replies and tool calls —
-# less volume, usually the pricier rate). BOTH fields are required together.
+name = "gpt"                      # 被 defaultModel 和 -m 引用
+provider = "openai"               # 某个 [[providers]] 块的 name
+model = "gpt-4o"                  # 发送给 API 的模型 id
+# maxTokens = 8192                # 单次回复的生成 token 上限
+# contextMaxTokens = 272000       # 按模型的上下文窗口——覆盖顶层 contextMaxTokens，
+                                  # 用于压缩和状态栏的 ctx 百分比
+# temperature = 1                 # 采样温度，随每次请求发送。不设置 = 应用 AI SDK 默认值
+                                  #（ai@4 会发送 0——它不会省略该字段），所以只接受某个固定值的
+                                  # 端点（kimi-for-coding/k3 只接受 1）必须在此显式设置。
+# reasoningEffort = "high"        # 思考模型的推理强度，每次请求原样以 reasoning_effort 发送。
+                                  # 档位命名因服务商/模型而异（常见 low/medium/high，部分还有
+                                  # minimal/max 等），因此接受任意字符串，由服务端校验。
+                                  # 不设置 = 服务端默认。anthropic 协议下忽略。
+                                  # /model 选完模型后也会接着让你选择推理强度。
+# streamIdleTimeoutSec = 60       # 按模型覆盖全局的流看门狗超时
+# streamFirstChunkTimeoutSec = 600
+# 可选的按模型定价（美元/1M token）——启用 /cost 和 /usage 中的美元估算。
+# promptPrice 为输入 token 定价（系统提示词、历史、@file 内容、工具结果——每回合重发，
+# 是用量的大头）；completionPrice 为输出 token 定价（模型的回复和工具调用——量较少，
+# 通常单价更贵）。两个字段必须同时设置。
 promptPrice = 2.5
 completionPrice = 10
+# cacheReadPrice = 0.25           # 可选的缓存读取输入 token 价格；不设置 = OpenAI 风格的缓存
+                                  # token 按 promptPrice 计费，Anthropic 风格的缓存读取不计费
 
 [[providers]]
 name = "claude"
@@ -108,14 +135,45 @@ model = "claude-sonnet-4-20250514"
 
 [[hooks]]
 event = "PostToolUse"                  # PreToolUse | PostToolUse | Stop
-matcher = "edit_file|write_file"       # optional regex on the tool name; matches all tools when omitted
-command = "biome check --write ."
-# timeoutSec = 30                      # optional per-hook timeout
+matcher = "edit_file|write_file"       # 可选的工具名正则；省略时匹配所有工具
+command = "biome check --write ."      # PreToolUse 以退出码 2 退出会阻止该工具
+                                       #（stderr 成为工具结果）；Stop 在每回合结束时触发
+# timeoutSec = 30                      # 可选的单钩子超时（默认 30；超时 = 放行并警告）
 ```
 
 API 密钥优先从环境变量解析（`apiKeyEnv`），其次是配置文件中的 `apiKey` 字段。启动时 Star CLI 还会把 `~/.star-cli/.env`（dotenv 风格的 `KEY=VALUE` 行）加载进环境变量，且不会覆盖已存在的变量——`/connect` 收集的密钥就存放在这里，因此 `config.toml` 只引用变量名，永远不会包含密钥本身。
 
-配置服务商最快的方式是 REPL 内的 `/connect` 向导：选择预设（OpenAI、Anthropic、Kimi/Moonshot、DeepSeek）或自定义端点，粘贴 API 密钥（输入时掩码显示），命名一个模型，它会把 `[[providers]]`/`[[models]]` 块追加到 `config.toml`（保留已有内容与注释），把密钥写入 `~/.star-cli/.env`（以 `STAR_API_KEY_<NAME>` 为名，在支持的平台上文件权限为 600），并可选择将新模型设为默认——全程无需重启。
+配置服务商最快的方式是 REPL 内的 `/connect` 向导：选择预设（OpenAI、Anthropic、Kimi/Moonshot、DeepSeek）或自定义端点，粘贴 API 密钥（输入时掩码显示），命名一个模型，它会把 `[[providers]]`/`[[models]]` 块追加到 `config.toml`（保留已有内容与注释），把密钥写入 `~/.star-cli/.env`（以 `STAR_API_KEY_<NAME>` 为名，在支持的平台上文件权限为 600），并可选择将新模型设为默认——全程无需重启。写入的 `[[models]]` 块默认带 `contextMaxTokens = 128000` 和 `temperature = 1`（稳妥的默认值——kimi-for-coding/k3 这类 coding 模型拒绝任何其他取值；仅在模型允许时才调低它），另有占位的零价格——可按需改成真实的限额与费率。
+
+### 使用中转站（relay）
+
+第三方中转站通常前置某种标准线路格式：中转支持 Responses API（`/responses`）时把 `protocol` 设为 `openai-responses`，否则用 `openai-compatible`（`/chat/completions`）。
+
+很多中转站会把整段生成缓冲起来再一次性下发——几十秒到几分钟可能没有任何 SSE 分片，看起来像流已死亡。Star CLI 会对每次请求的原始响应字节做时间戳检测：只要还有字节在流动（包括 SDK 自己会吞掉的 SSE 心跳注释），流看门狗就会延长等待而不是中途掐断正在缓冲生成的中转站，并以 10 分钟的总分片静默上限兜底，避免只剩心跳的僵尸连接挂住整个回合。如果某个中转站仍频繁触发 idle 超时，可以调大该模型自己的看门狗：
+
+```toml
+[[providers]]
+name = "kimi"
+protocol = "openai-responses"
+baseURL = "https://api.kimi.com/coding/v1"   # Kimi 官方 coding 端点
+apiKeyEnv = "STAR_API_KEY_KIMI"
+
+[[models]]
+name = "kimi"
+provider = "kimi"
+model = "kimi-for-coding"
+temperature = 1        # 此处必须设置——该端点拒绝任何其他取值
+contextMaxTokens = 128000
+# 中转站长时间缓冲整段生成时可调大：
+# streamIdleTimeoutSec = 60        # 默认 20
+# streamFirstChunkTimeoutSec = 600 # 默认 300
+```
+
+### 环境变量
+
+- `STAR_HOME` —— 把数据目录从 `~/.star-cli` 改为其他位置（配置、会话、`.env`、记忆、调试日志）。
+- `STAR_DEBUG` —— 任意非空值即启用流诊断日志，追加写入 `~/.star-cli/debug.log`，每行一个 JSON 对象。
+- `STAR_NO_NOTIFY=1` —— 不改配置即可禁用终端响铃。
 
 
 ## CLI 参数
@@ -170,9 +228,7 @@ star --clear-sessions all     delete every stored session
 
 按键：`ESC` / `Ctrl+C` 中断当前流——已生成的部分回复保留在屏幕上（以及会话历史中），并带暗色 `[interrupted]` 标记；在权限提示上：`y` 允许，`n` 拒绝，`a` 始终允许——生成的 allow 规则（如 `bash(npm test)`）会保存到配置文件的 `permissions.allow` 中，重启后依然有效。写入/编辑提示包含待变更内容的彩色 diff 预览。`Shift+Tab` 在会话内循环切换权限模式（`ask` → `auto` → `readonly` → `plan`；不保存到配置）。输入编辑：方向键移动光标，`Ctrl+A`/`Ctrl+E` 跳到行首/行尾，`Ctrl+U`/`Ctrl+K` 删除光标前/后的内容，`Ctrl+W` 删除前一个单词，上/下键回忆历史（跨会话持久化到 `~/.star-cli/history`，上限 50 条，连续重复自动折叠，斜杠命令与按键重复的垃圾输入从不记录）；当回忆出的条目未被修改时，上/下键继续在条目间切换，而一旦你编辑了文本——或正在输入自己的多行内容——上/下键改为在行之间移动光标。`Ctrl+R` 启动反向历史搜索：输入以过滤（不区分大小写，最新匹配优先），`Ctrl+R`/`↑` 找更早的匹配，`↓` 找更新的，`Enter` 将匹配接进输入框，`ESC`/`Ctrl+C`/`Ctrl+G` 取消并恢复你原有的内容。多行输入：使用 `Ctrl+J`（或 `Alt+Enter`），或以 `\` 结尾再按 `Enter`——粘贴的多行文本会原样保留。一次性粘贴大块内容（10+ 行或 500+ 字符）会折叠成暗色占位符 `[pasted #N: L lines]`，让输入框保持紧凑；完整文本会在提交时还原，`Backspace` 可将占位符整体删除。终端分多个块送达的超长粘贴会被重新组装（在支持的终端上通过 bracketed paste），并仍然折叠为单个占位符。输入 `/` 会显示斜杠命令建议及其用法——前缀匹配优先，然后是模糊子序列匹配；`↑`/`↓` 高亮，`Tab`（或在输入末尾按 `→`）补全，`ESC` 关闭，未知命令名会给出 `Did you mean: …` 提示。输入 `@` 会以同样的按键补全相对工作目录的文件路径；目录以 `/` 结尾以便用 `Tab` 下钻，`node_modules`、`.git`、`dist` 和 `.starignore` 条目会被跳过。`Alt+V` 把剪贴板中的图片作为附件粘贴（每张图片在输入框上方显示为 `[image attached: clipboard.png]`；Windows 上使用 PowerShell，macOS 上使用 pngpaste/osascript，Linux 上使用 xclip）。最长边超过 2000px 的图片会自动缩放以符合限制（保持宽高比，使用平台原生工具——Windows/macOS 无需额外安装；Linux 上使用 ImageMagick 或 ffmpeg）；无法缩放时保留原图并显示警告。在终端透传的地方 `Ctrl+V` 也可用——Windows Terminal 把 Ctrl+V 绑定为自己的粘贴，请在那里使用 `Alt+V`。回合流式输出期间你可以继续输入：提交的提示（和 `!` bang）会以暗色条目排队，回合结束后按序自动发送；回合中按 `ESC` 会中止该回合并清空队列（部分回复保留，标记为 `[interrupted]`）。空闲时半秒内连按两次 `ESC` 会撤回你上一条提示，并把原文恢复进输入框供编辑。
 
-模型工作时，加载动画（`- \ | /`）显示 `star is thinking…`；推理模型还会以暗色流式展示其思维尾部（最后约 200 字符），回答开始后折叠为一行摘要。流式回复、推理内容、工具输出和 todo 标题在显示前都会做净化处理（制表符展开为两个空格，剥离控制字节和原始转义序列），因此经中转的模型输出无法破坏终端或留下堆积的残留帧；长 todo 列表折叠为围绕活动任务的 10 行窗口，长预输入队列只显示前 5 条，让实时区域远低于终端高度。
-
-状态栏显示工作目录（宽终端上显示完整路径）、git 分支、模型、权限模式、上下文用量占模型上下文窗口的百分比（模型自身设置了 `contextMaxTokens` 时用它，否则用顶层值）、服务商上报缓存用量时的会话提示词缓存命中率（`cache: 42%`，从不上报时显示 `cache: Not provided`）、模型配置了定价时的会话成本，以及 token 总数。
+状态栏显示工作目录（宽终端上显示完整路径）、git 分支、模型、权限模式、上下文用量占模型上下文窗口的百分比（模型自身设置了 `contextMaxTokens` 时用它，否则用顶层值）、服务商上报缓存用量时的会话提示词缓存命中率（`cache: 42%`，从不上报时显示 `cache: Not provided`）、模型配置了定价时的会话成本，以及 token 总数。模型回复会以 Markdown 形式直接在终端渲染（标题、强调、代码块、表格等）。装饰图标在已知能正确双宽渲染 emoji 的终端（Windows Terminal、VS Code、Kitty 等）上使用 emoji，其他终端回退为纯符号以避免显示错位；也可用 `STAR_ICONS=emoji|plain` 强制指定。
 
 ## !shell 直通
 
@@ -288,7 +344,7 @@ star -p "what's wrong in this UI?" --image screenshot.png --image mockup.jpg
 
 ## 内置工具
 
-`read_file`、`write_file`、`edit_file`、`glob`、`grep`、`bash`、`web_fetch`、`web_search`（DuckDuckGo，无需 API 密钥）、`todo_read`、`todo_write`、`task_list`、`task_output`、`task_kill`、`subagent`、`skill`、`remember`——每个都声明一个权限级别（`read` / `write` / `exec`），由权限门禁强制执行。硬性安全规则（危险 shell 命令、工作目录之外的路径、`.env` / 私钥等机密文件）在 `ask` / `auto` / `readonly` 下被拒绝，且无法被 allow 规则覆盖。
+`read_file`、`read_image`（会话中把图片文件带给模型——截图、设计稿等；支持 png/jpg/gif/webp，超过 2000px 自动降采样）、`write_file`、`edit_file`、`glob`、`grep`、`bash`、`web_fetch`、`web_search`（DuckDuckGo，无需 API 密钥）、`todo_read`、`todo_write`、`task_list`、`task_output`、`task_kill`、`subagent`、`skill`、`remember`——每个都声明一个权限级别（`read` / `write` / `exec`），由权限门禁强制执行。硬性安全规则（危险 shell 命令、工作目录之外的路径、`.env` / 私钥等机密文件）在 `ask` / `auto` / `readonly` 下被拒绝，且无法被 allow 规则覆盖。
 
 `subagent` 工具（`exec` 级别，因此在计划模式下隐藏，在 readonly 下被拒绝）派生一个带相同内置工具的子代理循环，处理专注、自包含的子任务——调研、探索或一处孤立的改动——并把子代理的最终报告作为工具结果返回。子代理只运行一层（子代理不能再派生子代理），共享父代理的权限模式与确认提示，其对话不持久化到会话。