@baoanaz/cviauto 0.6.5 → 0.6.8

package/dist/templates/common/bundled-skills/trellis-channel/references/forum.md

@@ -1,25 +1,18 @@
-# Forum Channels
+# 论坛频道（Forum Channels）
 
-Forum channels are durable, topic-style channels. They are created with
-`--type forum` at channel-creation time and are immutable after that. They are
-not normal chat streams: the default read path is
-**forum summary -> one thread timeline -> current context**.
+论坛频道是持久化、主题式的频道。在频道创建时通过 `--type forum` 指定，创建后不可更改。它们不是普通的聊天流：默认的阅读路径是
+**论坛摘要（forum summary） -> 单个线程时间线（one thread timeline） -> 当前上下文（current context）**。
 
-## Forum vs Regular Channel
+## 论坛 vs 普通频道
 
-A channel's type is set with `--type` on `channel create` and never changes:
+频道类型在 `channel create` 时通过 `--type` 设置，且永不改变：
 
-- `chat` (default) — flat message timeline. `channel messages` always renders
-  the event stream. Forum-only flags such as `--thread` and `--action` are
-  rejected here.
-- `forum` — thread-oriented. `channel messages` without filters renders a
-  thread-board summary instead of raw events. The `post`, `forum`, `thread`,
-  and `thread rename` subcommands only apply to forum channels.
+- `chat`（默认）—— 扁平消息时间线。`channel messages` 始终渲染事件流。论坛专用 flags 如 `--thread` 和 `--action` 在此处会被拒绝。
+- `forum` —— 面向线程（thread-oriented）。不带过滤条件的 `channel messages` 渲染线程面板摘要而非原始事件。`post`、`forum`、`thread` 和 `thread rename` 子命令仅适用于论坛频道。
 
-Both types share the same scope model (`--scope project` is the default;
-`--scope global` puts the channel in the cross-project bucket).
+两种类型共享相同的作用域模型（scope model）（`--scope project` 为默认值；`--scope global` 将频道放入跨项目桶中）。
 
-## Create A Forum Channel
+## 创建论坛频道
 
 ```bash
 cviauto channel create design-feedback \
@@ -30,14 +23,11 @@ cviauto channel create design-feedback \
   --by main
 ```
 
-Use `--scope project` for a board scoped to one repo, `--scope global` for a
-cross-project board.
+使用 `--scope project` 创建限定于单个仓库的面板，使用 `--scope global` 创建跨项目面板。
 
-## Threads: Open, Comment, Status, Summary
+## 线程（Threads）：打开、评论、状态、摘要
 
-Threads live inside a forum channel. Each thread is identified by a stable
-`--thread <key>` (lowercase kebab-case is conventional). The first action on
-a thread is `opened`; everything afterwards uses the same `--thread` key.
+线程存在于论坛频道内部。每个线程通过稳定的 `--thread <key>` 标识（约定使用小写 kebab-case）。对线程的第一个操作是 `opened`；之后的所有操作使用相同的 `--thread` key。
 
 ```bash
 cviauto channel post design-feedback opened \
@@ -69,22 +59,16 @@ cviauto channel post design-feedback summary \
   --summary "Adopted the option-B layout; ticket TRELLIS-123 owns the fix."
 ```
 
-Key distinctions:
+关键区别：
 
-- `--description` is the **durable** thread description (the answer to "what
-  is this thread about?"). It is set on `opened` and edited by re-running
-  `post` with `--description`.
-- `--text` / `--stdin` / `--text-file` is the **event body** — the comment or
-  payload attached to this specific timeline entry.
-- `--labels` and `--assignees` are CSV and **replace** the current value; they
-  do not append.
-- `--summary` is the rolling thread summary. Setting it on `status closed` is
-  the standard way to mark a thread resolved with context.
+- `--description` 是**持久化**的线程描述（回答"这个线程是关于什么的？"）。在 `opened` 时设置，通过重新运行带 `--description` 的 `post` 来编辑。
+- `--text` / `--stdin` / `--text-file` 是**事件正文（event body）**—— 附属于此特定时间线条目的评论或负载。
+- `--labels` 和 `--assignees` 是 CSV 格式，会**替换**当前值而非追加。
+- `--summary` 是滚动线程摘要。在 `status closed` 时设置它是标记线程已解决并附带上下文的标准方式。
 
-`--thread` is required for every action except `opened` (where it is also
-required in practice — there is no anonymous thread).
+每个操作都需要 `--thread`，除了 `opened`（实际上也需要 —— 不存在匿名线程）。
 
-## Read A Forum
+## 阅读论坛
 
 ```bash
 cviauto channel messages design-feedback --scope global
@@ -93,53 +77,45 @@ cviauto channel thread design-feedback login-empty-state --scope global
 cviauto channel messages design-feedback --scope global --raw --thread login-empty-state
 ```
 
-If a peer says "I commented on the forum", run `channel forum` first to see
-which thread changed, then drill into that thread with `channel thread <name>
-<thread>`. Do not jump straight to ad-hoc `events.jsonl` parsing.
+如果同伴说"我在论坛上评论了"，先运行 `channel forum` 查看哪个线程有变化，然后用 `channel thread <name> <thread>` 深入该线程。不要直接跳到临时的 `events.jsonl` 解析。
 
-## Context
+## 上下文（Context）
 
-Context entries are durable background that should always be in scope when
-reading a channel or a thread. They are **not** timeline events; they are
-projected separately and replayed for every reader.
+上下文条目（context entries）是持久化的背景信息，在阅读频道或线程时应始终处于作用域内。它们**不是**时间线事件；它们被单独投影，并为每个读者重放。
 
-Use the `context` subcommands. The legacy `--linked-context-file` /
-`--linked-context-raw` flags on `create` and `post` are deprecated aliases
-that fold into the canonical `--context-file` / `--context-raw`.
+使用 `context` 子命令。旧版的 `--linked-context-file` / `--linked-context-raw` flags（在 `create` 和 `post` 上）是已弃用的别名，会被折叠到规范的 `--context-file` / `--context-raw` 中。
 
-### Add Context
+### 添加上下文
 
 ```bash
-# Channel-level context (whole forum)
+# 频道级上下文（整个论坛）
 cviauto channel context add design-feedback \
   --scope global \
   --raw "Upstream feedback board; please link tasks before opening threads."
 
-# Thread-level context (one thread)
+# 线程级上下文（单个线程）
 cviauto channel context add design-feedback \
   --scope global \
   --thread login-empty-state \
   --file "$PWD/.cviauto/tasks/05-13-login-redesign/design.md"
 ```
 
-- `--thread <key>` switches between channel-level and thread-level context.
-- `--file` paths **must be absolute**; relative paths are rejected.
-- `--raw` is plain text inline content.
-- Both flags are repeatable; at least one is required for `add` / `delete`.
-- `--as <agent>` records authorship; defaults to `main`.
+- `--thread <key>` 在频道级上下文和线程级上下文之间切换。
+- `--file` 路径**必须为绝对路径**；相对路径会被拒绝。
+- `--raw` 是纯文本内联内容。
+- 两个 flags 均可重复使用；`add` / `delete` 至少需要一个。
+- `--as <agent>` 记录作者身份；默认为 `main`。
 
-### List Context
+### 列出上下文
 
 ```bash
 cviauto channel context list design-feedback --scope global
 cviauto channel context list design-feedback --scope global --thread login-empty-state --raw
 ```
 
-`--raw` on `list` emits one JSON entry per line (useful for piping); without
-it you get a human-readable `file <path>` / `raw <truncated text>` listing.
-An empty store prints `(no context)`.
+`list` 上的 `--raw` 每行输出一个 JSON 条目（适用于管道）；不带它时，会得到人类可读的 `file <path>` / `raw <truncated text>` 列表。空存储打印 `(no context)`。
 
-### Delete Context
+### 删除上下文
 
 ```bash
 cviauto channel context delete design-feedback \
@@ -148,24 +124,21 @@ cviauto channel context delete design-feedback \
   --raw "stale note"
 ```
 
-You delete by **value**, not by id: pass the same `--file` or `--raw` value
-that was added. Repeat the flag to delete multiple entries in one call.
+按**值**而非 id 删除：传入与添加时相同的 `--file` 或 `--raw` 值。重复该 flag 可在一次调用中删除多个条目。
 
-### Reading Order
+### 阅读顺序
 
-When reading a thread, work top-down:
+阅读线程时，按自上而下的顺序：
 
-1. Thread `description` (the durable "what is this about").
-2. Context entries (channel-level + thread-level).
-3. Timeline (`opened`, `comment`, `status`, `summary`).
+1. 线程 `description`（持久化的"这是关于什么的"）。
+2. 上下文条目（频道级 + 线程级）。
+3. 时间线（`opened`、`comment`、`status`、`summary`）。
 
-If a context file is missing or unreadable, state that explicitly and
-continue with the remaining data — do not fabricate the content.
+如果上下文文件缺失或不可读，明确说明并继续使用剩余数据 —— 不要凭空编造内容。
 
-## Title Projection
+## 标题投影（Title Projection）
 
-`title` projects a stable display title onto the channel without renaming the
-storage address. The channel `name` you pass to every command stays the same.
+`title` 将稳定的显示标题投射到频道上，而不重命名存储地址。你传给每个命令的频道 `name` 保持不变。
 
 ```bash
 cviauto channel title set design-feedback \
@@ -175,16 +148,13 @@ cviauto channel title set design-feedback \
 cviauto channel title clear design-feedback --scope global
 ```
 
-- `title set` requires `--title`.
-- `--as <agent>` records authorship; defaults to `main`.
-- This is a presentation-layer change. Tooling and scripts keep using the
-  original channel name.
+- `title set` 需要 `--title`。
+- `--as <agent>` 记录作者身份；默认为 `main`。
+- 这是表现层（presentation-layer）的变更。工具和脚本继续使用原始频道名称。
 
-## Thread Rename
+## 线程重命名（Thread Rename）
 
-`thread rename` is the correction path when a thread was opened with the
-wrong key (typo, wrong slug convention, etc.). Threads do not support hard
-deletion — rename is the supported corrective action.
+`thread rename` 是当线程以错误的 key（拼写错误、slug 约定错误等）打开时的修正路径。线程不支持硬删除 —— 重命名是支持的纠正操作。
 
 ```bash
 cviauto channel thread rename design-feedback old-key new-key \
@@ -192,24 +162,21 @@ cviauto channel thread rename design-feedback old-key new-key \
   --as main
 ```
 
-- `--as <agent>` is **required**.
-- `post <name> rename` is rejected — you must use `thread rename`.
+- `--as <agent>` **必须**提供。
+- `post <name> rename` 会被拒绝 —— 必须使用 `thread rename`。
 
-## Deletion Discipline
+## 删除原则（Deletion Discipline）
 
-Do not model single-comment deletion or hard thread deletion as normal
-workflow. Forum threads are append-only collaboration history. To correct
-state, use:
+不要将单条评论删除或线程硬删除建模为正常工作流。论坛线程是仅追加的协作历史。要纠正状态，请使用：
 
-- `post ... status` to mark a thread closed / blocked / etc.
-- `post ... summary` to record the resolution.
-- `post ... --labels` to re-label (replaces the set).
-- `thread rename` to correct a bad thread key.
+- `post ... status` 将线程标记为 closed / blocked 等。
+- `post ... summary` 记录解决方案。
+- `post ... --labels` 重新打标签（替换整个集合）。
+- `thread rename` 纠正错误的线程 key。
 
-## Internal Changelog Pattern
+## 内部 Changelog 模式
 
-A common use of a global forum channel is an internal release / runtime
-changelog. One thread per notable change keeps history searchable:
+全局论坛频道的一个常见用途是内部发布/运行时 changelog。每个显著变更一个线程，保持历史可搜索：
 
 ```bash
 cviauto channel create release-notes \
@@ -229,5 +196,4 @@ cviauto channel post release-notes opened \
   --text-file /tmp/release-notes.md
 ```
 
-Use stable, descriptive thread keys (e.g. `release-2026-q1`,
-`runtime-event-schema-change`) so later readers can find them by name.
+使用稳定、描述性的线程 key（如 `release-2026-q1`、`runtime-event-schema-change`），以便后续读者能按名称找到它们。

package/dist/templates/common/bundled-skills/trellis-channel/references/progress-debugging.md

@@ -1,134 +1,113 @@
-# Progress And Debugging
+# 进度与调试（Progress And Debugging）
 
-Pretty output is for operators. Raw output is the audit log. Subcommands
-(`forum`, `thread`, `messages`, `context`) are the audit *interface* — reach
-for them before grepping `events.jsonl` by hand.
+格式化输出（pretty output）面向运维人员。原始输出（raw output）是审计日志。子命令（`forum`、`thread`、`messages`、`context`）是审计的**接口**——在手动 grep `events.jsonl` 之前，请优先使用它们。
 
-## Pretty vs `--raw`
+## Pretty 输出 vs `--raw`
 
-`cviauto channel messages <channel>` renders a compact, human-readable view:
-timestamps, identities, kind, and a short body. It is meant for operators
-scanning a channel, not for diagnostics.
+`cviauto channel messages <channel>` 渲染紧凑、人类可读的视图：时间戳、身份标识、kind 和简短正文。它面向扫描通道的运维人员，而非诊断用途。
 
-Pretty output can and will truncate:
+Pretty 输出会且将会截断以下内容：
 
-- long progress deltas (`text_delta`, partial tool args)
-- tool names and command lines
-- multi-line status fields and structured `detail` blobs
-- forum thread titles past the column budget
+- 较长的 progress 增量（`text_delta`、部分工具参数）
+- 工具名称和命令行
+- 多行状态字段和结构化的 `detail` 数据块
+- 超出列宽限制的 forum 线程标题
 
-When something looks "off" — a worker appears stuck, a progress line ends
-mid-word, an action field shows `...` — switch to `--raw`. Raw mode emits
-one JSON event per line exactly as it lives in `events.jsonl`, so nothing
-is dropped.
+当某些内容看起来"不对劲"——worker 看起来卡住了、progress 行在单词中间截断、action 字段显示 `...`——请切换到 `--raw`。Raw 模式每行输出一条 JSON 事件，与 `events.jsonl` 中的内容完全一致，因此不会有任何内容被丢弃。
 
 ```bash
-# Pretty (operator view)
+# Pretty（运维视图）
 cviauto channel messages <channel> --kind done --last 10
 cviauto channel messages <channel> --kind error --last 10
 
-# Raw (diagnostic view) — one JSON per line
+# Raw（诊断视图）— 每行一条 JSON
 cviauto channel messages <channel> --raw --kind progress --last 20
 cviauto channel messages <channel> --raw --last 50
 ```
 
-Rule of thumb: never diagnose a worker from a truncated progress line.
+经验法则：永远不要根据截断的 progress 行来诊断 worker。
 
-### Rebuild Streaming Text
+### 重建流式文本
 
-To reconstruct what a model actually streamed during a turn, concatenate
-`detail.text_delta` from progress events:
+要重建模型在某个 turn 中实际流式输出的内容，将 progress 事件中的 `detail.text_delta` 拼接起来：
 
 ```bash
 cviauto channel messages <channel> --raw --kind progress --last 80 \
   | python3 -c 'import json,sys; [print((json.loads(l).get("detail") or {}).get("text_delta",""), end="") for l in sys.stdin if l.strip()]'
 ```
 
-## Stalled Worker Diagnosis
+## 停滞 Worker 诊断
 
-Symptom: `cviauto channel list` shows the worker as running, but no new
-events appear in `messages` and `wait` keeps timing out.
+症状：`cviauto channel list` 显示 worker 正在运行，但 `messages` 中没有新事件出现，且 `wait` 持续超时。
 
-Triage order:
+排查顺序：
 
-1. **Locate the channel files.** Use `list --all --all-projects` if you are
-   not sure which bucket the channel lives in.
+1. **定位通道文件。** 如果不确定通道属于哪个 bucket，使用 `list --all --all-projects`。
 
    ```bash
    cviauto channel list --all --all-projects
    CHAN=~/.cviauto/channels/<bucket>/<channel>
    ```
 
-2. **Confirm the supervisor and worker PIDs are alive.**
+2. **确认 supervisor 和 worker 的 PID 仍在运行。**
 
    ```bash
    cat "$CHAN/<worker>.pid"            # supervisor PID
-   cat "$CHAN/<worker>.worker-pid"     # actual CLI subprocess PID
+   cat "$CHAN/<worker>.worker-pid"     # 实际 CLI 子进程 PID
    ps -p "$(cat "$CHAN/<worker>.pid")"
    ps -p "$(cat "$CHAN/<worker>.worker-pid")"
    ```
 
-   If the supervisor PID is gone but the channel still lists the worker,
-   you have a ghost entry — clean it with
-   `cviauto channel kill <name> --as <worker> --force`.
+   如果 supervisor PID 已不存在但通道仍列出该 worker，说明存在幽灵条目——使用
+   `cviauto channel kill <name> --as <worker> --force` 清理。
 
-3. **Tail the worker log.** This is the canonical place to see provider /
-   MCP / tool startup output that never makes it onto the channel.
+3. **跟踪 worker 日志。** 这是查看 provider / MCP / 工具启动输出（这些输出永远不会出现在通道上）的权威位置。
 
    ```bash
    tail -f "$CHAN/<worker>.log"
    ```
 
-4. **Check the last raw events.** A worker that emitted `progress` but no
-   `message`/`done` is usually mid-stream or blocked on a tool call:
+4. **检查最后几条 raw 事件。** 一个发出了 `progress` 但没有 `message`/`done` 的 worker 通常处于流式输出中或被工具调用阻塞：
 
    ```bash
    cviauto channel messages <channel> --raw --last 50
    ```
 
-Common "alive but silent" causes:
+常见的"存活但静默"原因：
 
-- Provider cold start before the first token (long, but eventually moves).
-- A blocking MCP server during startup — visible in the worker log.
-- Worker is waiting for a tool result whose subprocess hung.
-- Prompt is huge / model is rate-limited; check provider-side errors in the
-  worker log.
+- Provider 在首个 token 之前的冷启动（耗时较长，但最终会推进）。
+- 启动期间有阻塞的 MCP 服务器——可在 worker 日志中看到。
+- Worker 正在等待工具调用结果，但其子进程已挂起。
+- 提示词过大 / 模型被限速；检查 worker 日志中的 provider 侧错误。
 
-## Progress Event Interpretation
+## Progress 事件解读
 
-A `progress` event represents an in-flight piece of work. Its shape varies
-by `action` field, but the load-bearing fields are always under `detail`:
+`progress` 事件表示进行中的工作。其形态随 `action` 字段变化，但核心字段始终在 `detail` 下：
 
-- `detail.text_delta` — incremental model output (concatenate across events
-  to rebuild the streamed reply).
-- `detail.tool_name`, `detail.tool_input` — tool call about to run or
-  currently running.
-- `detail.status` — short string used by long-running actions
-  (`starting`, `running`, `flushing`, `done`).
-- `detail.action` — semantic label (e.g. `status` for thread heartbeats).
+- `detail.text_delta` — 增量模型输出（跨事件拼接可重建流式回复）。
+- `detail.tool_name`、`detail.tool_input` — 即将运行或正在运行的工具调用。
+- `detail.status` — 长耗时操作使用的简短字符串（`starting`、`running`、`flushing`、`done`）。
+- `detail.action` — 语义标签（例如线程心跳使用 `status`）。
 
-Progress events are **noisy** by design. `wait` ignores them unless you
-pass `--include-progress`. When you do want to see them, prefer:
+Progress 事件**在设计上就是嘈杂的**。`wait` 默认忽略它们，除非传入 `--include-progress`。当确实需要查看它们时，推荐使用：
 
 ```bash
 cviauto channel messages <channel> --raw --kind progress --last 80
 ```
 
-A stream that emits progress at a steady cadence but never closes with
-`done`/`error`/`message` is the classic shape of a hung tool call —
-inspect the worker log for the subprocess.
+一个以稳定节奏持续发出 progress 但从未以 `done`/`error`/`message` 结束的流，是工具调用挂起的典型形态——检查 worker 日志中的子进程。
 
-## Wait Semantics (Quick Reference)
+## Wait 语义（快速参考）
 
-`channel wait` watches `events.jsonl` from EOF and wakes on:
+`channel wait` 从 EOF 开始监视 `events.jsonl`，并在以下事件上醒来：
 
 - `message`
 - `done`
 - `error`
 - `killed`
-- `progress` only with `--include-progress`
+- `progress`（仅当带 `--include-progress` 时）
 
-Useful filters:
+实用过滤器：
 
 ```bash
 cviauto channel wait T --as main --from check --kind done --timeout 15m
@@ -137,73 +116,58 @@ cviauto channel wait T --as worker --tag interrupt --timeout 1h
 cviauto channel wait T --as main --thread release-note --action status --timeout 10m
 ```
 
-Exit codes: `0` matched, `124` timeout, `1`/`2` errors. On `wait --all`
-timeout, stderr names the workers still missing.
+退出码：`0` 匹配成功，`124` 超时，`1`/`2` 错误。在 `wait --all` 超时时，stderr 会列出仍然缺失的 worker。
 
-## Auditing `events.jsonl` — Use Subcommands, Not `grep`
+## 审计 `events.jsonl` — 使用子命令，而非 `grep`
 
-Every channel persists its full history at `$CHAN/events.jsonl`. It is
-tempting to `tail` / `grep` / `jq` this file directly during debugging.
-Don't make it a habit, and **never** do it for forum channels.
+每个通道的完整历史记录持久化在 `$CHAN/events.jsonl` 中。调试时直接对该文件使用 `tail` / `grep` / `jq` 是很有诱惑力的。不要养成这个习惯，并且**绝对不要**对 forum 通道这样做。
 
-Why subcommands first:
+优先使用子命令的原因：
 
-- `messages` already replays the file with filters (`--kind`, `--from`,
-  `--last`, `--tag`, `--thread`, `--action`) and gives you `--raw` for the
-  exact JSON. Anything you would write a one-liner for, `messages` already
-  does.
-- `wait` consumes the same file with EOF semantics — re-implementing that
-  with `tail -f | jq` will drop events under load and misorder them under
-  rotation.
-- `context` materializes a worker's inbox view, including cursor state.
-  Hand-rolled filters do not respect `<worker>.inbox-cursor`.
+- `messages` 已经可以带过滤器（`--kind`、`--from`、`--last`、`--tag`、`--thread`、`--action`）重放文件，并提供 `--raw` 获取精确的 JSON。任何你想用一行命令完成的事情，`messages` 已经做到了。
+- `wait` 以 EOF 语义消费同一个文件——用 `tail -f | jq` 重新实现会在线程压力下丢失事件，并在轮转时乱序。
+- `context` 可以物化 worker 的收件箱视图，包括游标状态。手工编写的过滤器不会遵循 `<worker>.inbox-cursor`。
 
-### Forum channels: never parse `events.jsonl` directly
+### Forum 通道：永远不要直接解析 `events.jsonl`
 
-Forum channels multiplex many logical threads onto a single `events.jsonl`.
-Each event carries `thread`, `action`, and tag fields that the forum
-subcommands know how to fold together. Parsing the file by hand will:
+Forum 通道将多个逻辑线程多路复用到一个 `events.jsonl` 上。每个事件都携带 `thread`、`action` 和标签字段，forum 子命令知道如何将它们整合在一起。手工解析该文件会：
 
-- Mix threads together and make a thread look incoherent.
-- Miss thread lifecycle events (open / status / close) that change how
-  later events should be interpreted.
-- Ignore worker inbox cursors, so you will "see" events a worker has
-  already consumed and assume they are pending.
+- 将线程混在一起，使某个线程看起来不连贯。
+- 遗漏线程生命周期事件（open / status / close），这些事件会改变后续事件的解读方式。
+- 忽略 worker 收件箱游标，因此你会"看到" worker 已经消费过的事件，并误以为它们仍是待处理的。
 
-Use the forum-aware views instead:
+请改用 forum 感知的视图：
 
 ```bash
-# List logical threads inside the forum channel
+# 列出 forum 通道内的逻辑线程
 cviauto channel forum list <channel>
 
-# Inspect one thread end-to-end
+# 端到端检查一个线程
 cviauto channel thread show <channel> <thread>
 
-# Replay messages for a thread (supports --raw, --kind, --last)
+# 重放某线程的消息（支持 --raw、--kind、--last）
 cviauto channel messages <channel> --thread <thread> --raw --last 100
 
-# What a specific worker still has pending
+# 某个特定 worker 仍未处理的内容
 cviauto channel context <channel> --as <worker>
 ```
 
-Direct reads of `events.jsonl` are reserved for the case where the CLI
-itself is suspect — e.g. confirming an event was actually persisted, or
-diffing against `<worker>.inbox-cursor` while debugging the supervisor.
+直接读取 `events.jsonl` 仅保留用于 CLI 本身可疑的场景——例如确认某个事件确实已持久化，或在调试 supervisor 时对比 `<worker>.inbox-cursor`。
 
-## Common Failures
+## 常见故障
 
-| Symptom | Cause | Fix |
+| 症状 | 原因 | 修复方法 |
 |---|---|---|
-| `cviauto: command not found` | CLI not installed globally | install the internal Cviauto CLI package |
-| `wait` exits immediately | wrong filter or identity collision | use distinct `--as`, inspect raw messages |
-| zsh errors on message text | shell interpreted punctuation | use `--stdin` or `--text-file` |
-| progress line is cut off | pretty output truncation | use `messages --raw --kind progress` |
-| worker never speaks | provider startup / prompt / MCP delay | inspect `<worker>.log`, `ps`, raw events |
-| channel not found in another cwd | project bucket mismatch | `cd` to project, use `--scope global`, or `list --all-projects` |
-| ghost worker in list | supervisor died without cleanup | `cviauto channel kill <name> --as <worker> --force` |
-| forum thread looks scrambled | parsed `events.jsonl` directly | use `forum`, `thread`, `messages --thread` |
+| `cviauto: command not found` | CLI 未全局安装 | `npm install -g @mindfoldhq/cviauto` |
+| `wait` 立即退出 | 错误的过滤器或身份冲突 | 使用不同的 `--as`，检查 raw 消息 |
+| zsh 对消息文本报错 | shell 解释了标点符号 | 使用 `--stdin` 或 `--text-file` |
+| progress 行被截断 | pretty 输出截断 | 使用 `messages --raw --kind progress` |
+| worker 永远不会发言 | provider 启动 / 提示词 / MCP 延迟 | 检查 `<worker>.log`、`ps`、raw 事件 |
+| 在另一个 cwd 中找不到通道 | 项目 bucket 不匹配 | `cd` 到项目目录，使用 `--scope global`，或 `list --all-projects` |
+| 列表中显示幽灵 worker | supervisor 已退出但未清理 | `cviauto channel kill <name> --as <worker> --force` |
+| forum 线程看起来混乱 | 直接解析了 `events.jsonl` | 使用 `forum`、`thread`、`messages --thread` |
 
-## Storage Layout
+## 存储布局
 
 ```text
 ~/.cviauto/channels/
@@ -221,6 +185,4 @@ diffing against `<worker>.inbox-cursor` while debugging the supervisor.
         └── <worker>.spawnlock
 ```
 
-Agents normally use the CLI, not direct file reads. Direct file reads are
-for debugging when CLI views are insufficient — and even then, never on a
-forum channel's `events.jsonl`.
+Agent 通常使用 CLI 而非直接读取文件。直接读取文件仅用于 CLI 视图不足以满足需求的调试场景——即便如此，也绝对不要直接读取 forum 通道的 `events.jsonl`。