The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
docs: document TinyChannels v2 and TinyAgents ownership boundaries
Steven Enamakel254e0ca0dfe8
diff --git a/crates/openhuman-core/src/channels/README.md b/crates/openhuman-core/src/channels/README.mdindex 920668f24e..722371f34d 100644--- a/crates/openhuman-core/src/channels/README.md+++ b/crates/openhuman-core/src/channels/README.md@@ -26,6 +26,12 @@ its account authorization and session policy. Host callbacks handle onlycapabilities the module cannot own, such as scoped media access, voice, andevent publication.+The TinyChannels v2 bus is also the source of the typed channel and web-event+wire contracts. OpenHuman passes those values across the module boundary and+keeps only host-specific routing, authorization, and lifecycle data around+them. It does not maintain a parallel provider API or re-map canonical web+output events in the host.+## Hosted and relay pathsHosted-channel messages arrive through the backend socket and are handled by@@ -34,6 +40,11 @@ private module runtime for progressive delivery. The module owns drafts,typing, retries, and idempotent final delivery; the host callback provides thecaptured managed REST transport.+Agent execution uses the shared TinyAgents turn runner. OpenHuman selects the+agent, applies account and approval policy, binds the session, and supplies+host capabilities. TinyAgents owns generic admission, queueing, and turn-run+mechanics; TinyChannels owns provider transport and delivery behavior.+Gateway-relayed inbound messages use [`providers/relay/`](./providers/relay/README.md).The host preserves authenticated relay provenance outside serialized messagemetadata, then runs the message through the same routing and agent policy as adiff --git a/crates/openhuman-core/src/web_chat/README.md b/crates/openhuman-core/src/web_chat/README.mdindex 125505a96d..48f639ed5e 100644--- a/crates/openhuman-core/src/web_chat/README.md+++ b/crates/openhuman-core/src/web_chat/README.md@@ -11,8 +11,15 @@ alone can supply:| Owner | Owns | OpenHuman's host seam || --- | --- | --- |-| TinyAgents harness | Generic turn admission and run-queue mechanics, exposed to the host through `tinyagents_harness::turn_runner` | [`QueuedPayload`](../agent/queued_turn.rs) carries product metadata; [`runner.rs`](./runner.rs) and [`turn_host.rs`](./turn_host.rs) adapt web-chat policy and ports. |-| TinyChannels module | Projection of canonical output events onto typed web events, with per-turn `seq` | [`surface.rs`](./surface.rs) calls the compiled module through `tinychannels-bus`; the host keeps routing and process-wide event publication. |+| TinyAgents harness | Generic turn admission, run-queue mechanics, and work tracking through `tinyagents_harness::turn_runner` | [`QueuedPayload`](../agent/queued_turn.rs) carries product metadata; [`runner.rs`](./runner.rs) and [`turn_host.rs`](./turn_host.rs) supply web-chat policy and host ports. |+| TinyChannels v2 module and bus | Canonical typed web-event wire contract, generated/shared event types, and projection of output events with per-turn `seq` | [`surface.rs`](./surface.rs) adapts the host to the compiled module through `tinychannels-bus`; OpenHuman retains routing stamps and process-wide event publication. |++OpenHuman owns the product boundary around those engines: the `channel.web_*`+RPC and socket handlers, input validation and attachment trust, approvals,+session checkout, reply persistence, terminal policy, and host event delivery.+It does not own a second turn queue or a web-output event mapper. The host+adapter translates the module's canonical event type into the process bus+envelope without changing its wire payload.Hosted channel domain events are dispatched through this module's `start_chat`via `channels/bus/subscriber.rs`; those turns share the web-chat runner. Relay@@ -119,10 +126,11 @@ SSE stream, the TUI and the hosted channel subscriber.idle record and tells the runner when model or tool work opens and closes(`WorkStarted` / `WorkFinished`, TinyAgents' `turn_runner::WorkTracker`), thenhands it to the runner, which calls `WebEvents::progress` in order. That is- `ProgressProjection::on_event` (`progress.rs`), the one consumer: it maps the- event to the canonical output vocabulary (`progress_map.rs`), publishes it- through the compiled TinyChannels module over TinyBus (`surface.rs`), and does the host's side effects in- the same pass: the run ledger (`progress_ledger.rs`), the `TurnStates`+ `ProgressProjection::on_event` (`progress.rs`), the one host consumer: it+ adapts `AgentProgress` to TinyChannels' typed `ChannelOutputEvent` inputs+ (`progress_map.rs`) and asks the compiled module to project them onto the+ web wire (`surface.rs`). It also does host side effects in the same pass:+ the run ledger (`progress_ledger.rs`), the `TurnStates`mirror, the tracing export (`progress_trace.rs`, `journal_shadow.rs`),first-token timing and the throttled live `turn_cost`. An`inference_heartbeat` every `INFERENCE_HEARTBEAT_SECS` (20 s) keeps a longdiff --git a/docs/gitbooks/en/developing/architecture/agent-harness.md b/docs/gitbooks/en/developing/architecture/agent-harness.mdindex ac5b7ea934..209884c452 100644--- a/docs/gitbooks/en/developing/architecture/agent-harness.md+++ b/docs/gitbooks/en/developing/architecture/agent-harness.md@@ -7,10 +7,13 @@ icon: layer-group# Agent harness-`crates/openhuman-core/src/agent/` is the host side of an agent turn: the-tool-call loop and its dialects, sub-agent dispatch and archetypes, sessions-and resume, triage, hooks, interrupts and cost accounting, all wrapped around-the TinyAgents harness rather than reimplementing it.+`crates/openhuman-core/src/agent/` is the host side of an agent turn. TinyAgents+owns the generic tool-call loop, call parsing, session identity and transcript+replay, and reusable turn-runner mechanics. OpenHuman adapts those primitives+to product policy and host ports: provider selection, access and approvals,+session persistence, sub-agent product behavior, interruption policy, and cost+accounting. TinyChannels owns provider implementations and the canonical typed+channel and web-event contracts.## Embedding OpenHuman as a library@@ -93,7 +96,7 @@ Some settings remain runtime-wide for every agent (the live autonomy policy'sconfig sub-agents re-read); the crate README lists them under "Stillruntime-wide".-Every agent turn runs through the published [`tinyagents`](https://crates.io/crates/tinyagents) harness. There are three entry points: `Agent::turn`, the channel and CLI bus path, and `run_subagent`. All of them go through the adapter seam in [`crates/openhuman-core/src/agent/tinyagents/`](https://github.com/tinyhumansai/openhuman/tree/main/crates/openhuman-core/src/agent/tinyagents) (`TurnSpec::run`). Context trimming is `MessageTrimMiddleware`, and cancellation is the tinyagents steering channel. Policy stop hooks (budget, thread-goal and iteration caps) fire through a `StopHookMiddleware` ([`tinyagents/stop_hooks.rs`](https://github.com/senamakel/openhuman/blob/epic/7964-channel-v2/crates/openhuman-core/src/agent/tinyagents/stop_hooks.rs)) that pauses the run on the first stop vote. The channel route forwards live `AgentProgress` like the chat route. The shared `TurnProgress` seam lives in `agent/session_host/tool_progress.rs`.+Every agent turn runs through the published [`tinyagents`](https://crates.io/crates/tinyagents) harness. There are three entry points: `Agent::turn`, the channel and CLI bus path, and `run_subagent`. All of them go through the adapter seam in [`crates/openhuman-core/src/agent/tinyagents/`](https://github.com/tinyhumansai/openhuman/tree/main/crates/openhuman-core/src/agent/tinyagents) (`TurnSpec::run`). Context trimming is `MessageTrimMiddleware`, and cancellation is the TinyAgents steering channel. Product policy stop hooks (budget, thread-goal and iteration caps) are installed by OpenHuman through `StopHookMiddleware` ([`tinyagents/stop_hooks.rs`](https://github.com/senamakel/openhuman/blob/epic/7964-channel-v2/crates/openhuman-core/src/agent/tinyagents/stop_hooks.rs)). Web chat admission and queue mechanics use TinyAgents' `TurnRunner`; OpenHuman's `web_chat` host supplies ingress, session checkout, approvals, persistence, and terminal-event policy. Channel provider transport and the typed web-event schema/projection are supplied by the TinyChannels v2 module over TinyBus. OpenHuman publishes those canonical events on its process event bus and retains only host routing metadata. The shared `TurnProgress` seam lives in `agent/session_host/tool_progress.rs`.Multi-agent orchestration runs on the tinyagents graph layer, through `tinyagents-orchestration`'s `parallel` module, the host `spawn_parallel` adapter and the shared `graph::orchestration` `TaskStore` lifecycle primitives re-exported from [`orchestration/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-core/src/agent/orchestration/mod.rs):@@ -113,7 +116,7 @@ OpenHuman depends on the split TinyAgents 2.1 crate family by path into the vend- No scripting runtime. There is no `repl` or Rhai scripting feature and no `rhai_workflows` tool. Rhai still appears as a dependency of `tinyflows` for its own JSON-query stack, unrelated to the agent harness.- Ownership map: model construction → `inference::provider::create_chat_model*`; durable graph checkpoints → TinyAgents' `SqliteCheckpointer`; generic detached executor state → `DetachedTaskRegistry`; controller-facing durability → OpenHuman SQL/JSON run ledgers (`running_subagents`, `workflow_runs`, `agent_teams`, `command_center`). The generic harness/graph/middleware/event primitives are used as-is.-The agent harness is the runtime that turns a user message (or a webhook fire, or a cron tick) into a complete, tool-using LLM interaction. It owns the tool-call loop, sub-agent dispatch, the trigger-triage pipeline, and the hook surface around them. It does not own provider HTTP transport, tool implementations, prompt-section assembly or memory storage. Those are separate domains the harness composes.+The agent harness turns a user message, webhook event, or cron tick into a complete, tool-using interaction. TinyAgents owns the generic loop and reusable execution primitives. OpenHuman supplies the product-specific sub-agent and trigger workflows, policy hooks, and host capabilities. Provider transport and channel normalization belong to TinyChannels; tool implementations, prompt assembly, and memory storage belong to their respective domains.This page walks through what happens in one turn, then zooms in on each of the moving parts.@@ -121,13 +124,14 @@ This page walks through what happens in one turn, then zooms in on each of the mEvery turn goes through the same lifecycle, whether the user just typed a message, a Telegram webhook fired or a 9am cron ticked:-Messaging-channel ingress is prepared by the configured TinyChannels module-through typed bus operations. OpenHuman applies account authorization and-host policy, then supplies the persistence ports used by TinyAgents' session-and transcript machinery. TinyAgents owns generic turn execution, session-identity, and transcript replay. Provider transport and normalization stay in-TinyChannels; OpenHuman owns account authorization, approvals, and the host-adapters and persistence implementations.+Messaging-channel ingress is prepared by the configured TinyChannels v2 module+through typed bus operations and shared wire types. OpenHuman applies account+authorization and host policy, then supplies the persistence ports used by+TinyAgents' session and transcript machinery. TinyAgents owns generic turn+execution, session identity, transcript replay, and the reusable turn runner.+Provider transport, normalization, and canonical web-output projection stay in+TinyChannels; OpenHuman owns account authorization, approvals, session and+delivery policy, and the host adapters and persistence implementations.```text┌─ inbound ─────────────────────────────────────────────────────────┐diff --git a/docs/gitbooks/en/developing/architecture/frontend.md b/docs/gitbooks/en/developing/architecture/frontend.mdindex 45839f599a..bd34fca13f 100644--- a/docs/gitbooks/en/developing/architecture/frontend.md+++ b/docs/gitbooks/en/developing/architecture/frontend.md@@ -70,7 +70,11 @@ message; the frontend does not persist local paths or inline media bytes asconversation content. The core resolves those references within the trustedturn context before calling a model. Web chat, TUI, and relayed web progressshare the TinyChannels compiled web-output projection; provider delivery keeps-its separate channel terminal event.+its separate channel terminal event. TinyChannels v2 owns the canonical typed+web-event schema and projection, while TinyAgents owns generic chat turn+admission and queue mechanics. OpenHuman's core adapts both to its RPC, socket,+session, approval, and process-event-bus boundaries; the frontend consumes the+resulting event contract and does not implement provider or agent-runner logic.### Entry pointsdiff --git a/docs/gitbooks/en/features/channels.md b/docs/gitbooks/en/features/channels.mdindex a68dc2316a..0885222c75 100644--- a/docs/gitbooks/en/features/channels.md+++ b/docs/gitbooks/en/features/channels.md@@ -12,11 +12,13 @@ A channel is a messaging app the agent uses to talk to you. You message the agenChannel providers normalize platform messages into typed envelopes and sendtyped replies through the configured provider. OpenHuman keeps account policy,authorization, agent execution, and durable conversation sessions in the host;-provider transport runs in the TinyChannels module behind its bus contract.+provider transport runs in the TinyChannels v2 module behind its bus contract.The host communicates with the module through typed TinyBus requests andcallbacks: it does not link provider implementations. The module prepares-provider identity and ordered message parts; OpenHuman checks access, selects-the agent, and binds the message to its durable session before running a turn.+provider identity and ordered message parts and owns the canonical typed+channel and web-event contracts; OpenHuman checks access, selects the agent,+and binds the message to its durable session before running a turn. Generic+turn admission and queue mechanics come from TinyAgents.## What a channel doesdiff --git a/docs/gitbooks/en/features/chat.md b/docs/gitbooks/en/features/chat.mdindex 3cf6b6c930..2d2f23172e 100644--- a/docs/gitbooks/en/features/chat.md+++ b/docs/gitbooks/en/features/chat.md@@ -86,6 +86,11 @@ image, audio, video, or file content to the model route. Voice notes retaintyped audio and transcript metadata in the conversation, so they can bereplayed after reload; dictation sends text only.+The chat host owns its RPC and socket surface, input and approval policy,+session checkout, and durable reply delivery. TinyAgents supplies generic turn+admission and queue mechanics. TinyChannels supplies the canonical typed web+event contract and output projection shared with TUI and relayed web progress.+## Keyboard| Shortcut | Action |diff --git a/docs/gitbooks/zh/features/channels.md b/docs/gitbooks/zh/features/channels.mdnew file mode 100644index 0000000000..fa99d99e3c--- /dev/null+++ b/docs/gitbooks/zh/features/channels.md@@ -0,0 +1,84 @@+---+description: >-+ OpenHuman 可双向交互的消息应用:消息如何到达代理、回复和主动消息如何发送,+ 以及各个渠道如何登录。+icon: messages-square+---++# 消息渠道++渠道是代理用来与你交流的消息应用。你可以在平时使用的平台上给代理发消息,代理也会在那里回复。渠道与[集成](integrations/README.md)不同:集成主要供代理读取信息,例如邮箱、日历或 CRM;渠道则支持双向对话。++渠道提供方会把平台消息规范化为带类型的信封,并通过配置的提供方发送带类型的回复。OpenHuman 在主机侧负责账户策略、授权、代理执行和持久化对话会话;提供方传输由 TinyChannels v2 模块通过总线契约运行。主机通过带类型的 TinyBus 请求和回调与模块通信,不会链接提供方实现。模块会准备提供方身份和有序消息部分,并拥有规范的带类型渠道与 Web 事件契约;OpenHuman 检查访问权限、选择代理,并在运行轮次前将消息绑定到持久化会话。通用轮次准入和排队机制由 TinyAgents 提供。++## 渠道的工作方式++渠道包含两个方向。++**接收消息。** 提供方模块会把消息、地址、发送者和有序内容规范化为带类型的信封。OpenHuman 主机应用授权和路由策略,然后启动或恢复持久化对话会话。部分平台支持 `/models` 和 `/model` 命令,可为该发送者的会话切换模型。Telegram 还支持远程控制命令。++**发送消息。** 带类型的回复内容由提供方模块发送到原回复目标;平台支持时会保留线程地址。Web 聊天、TUI 和中继的 Web 事件共用 TinyChannels Web 输出模块投影代理进度;网关也可能发送独立的、面向提供方的终止事件。触发器或定时任务启动时,即使没有收到新消息,渠道也可以主动发送消息。只有配置了默认投递目标的渠道才会收到主动消息;其他渠道会被跳过。++平台支持时,渠道可以显示正在输入状态、流式发送草稿、以线程方式回复、发送媒体或语音便笺,以及添加表情回应。这些能力由各提供方决定:模块会报告已配置提供方支持的功能,OpenHuman 不会模拟不支持的操作。++## 支持的渠道++OpenHuman 有 15 种渠道提供方,其中 14 种内置于已发布的桌面应用。WhatsApp Web 受 `whatsapp-web` 构建功能控制,而已发布应用未启用该功能,因此无法在应用中开启。应用内 Web 聊天是内置功能,不属于渠道提供方。另有一个独立的 `cli` 渠道供 `openhuman-core` 终端程序使用。应用中有八种渠道提供设置流程:Telegram、Discord、Web、iMessage、Lark/Feishu、DingTalk、Email 和元宝。其余渠道需要手动在 `config.toml` 中启用。++| 渠道 | 方向 | 接收传输方式 | 凭据 | 设置界面 |+| --- | --- | --- | --- | --- |+| Telegram | 双向 | Bot API 长轮询 | 通过 OpenHuman 托管私聊连接,或使用自己的 BotFather 令牌 | 有 |+| Discord | 双向 | Gateway | 自有机器人令牌、OAuth 安装或托管账户关联 | 有 |+| Web | 双向 | 应用内 | 内置,无需设置(本地) | 有 |+| iMessage | 双向 | macOS 信息(AppleScript) | 仅本地,无凭据(需要“完全磁盘访问”权限) | 有 |+| Lark / Feishu | 双向 | WebSocket 或 webhook | 自有应用 ID 和密钥 | 有 |+| DingTalk | 双向 | Stream Mode WebSocket | 自有客户端 ID 和密钥 | 有 |+| 元宝(Yuanbao) | 双向 | WebSocket | 自有 AppID 和 AppSecret | 有 |+| Slack | 双向 | Events/socket | 自有机器人令牌 | `config.toml` |+| WhatsApp | 双向 | Meta Cloud webhook | 自有访问令牌 | `config.toml` |+| IRC | 双向 | 持久连接 | 自有服务器和昵称 | `config.toml` |+| Signal | 双向 | signal-cli REST 事件 | 自有已关联的 signal-cli 账户 | `config.toml` |+| Mattermost | 双向 | REST API 轮询 | 自有机器人令牌 | `config.toml` |+| QQ | 双向 | WebSocket | 自有机器人凭据 | `config.toml` |+| Linq | 双向(短信) | Webhook | 自有 API 令牌 | `config.toml` |+| Email | 双向 | IMAP IDLE 和 SMTP | 自有邮箱凭据 | 有 |++WhatsApp 还有一个实验性的点对点版本,由 `whatsapp-web` 功能控制。使用 webhook 的渠道通过 HTTP 推送接收消息,因此需要提供方可访问的 HTTPS 端点。++Telegram 支持输入状态指示和实时草稿更新。审批交互取决于提供方声明的能力和配置的渠道界面。Discord 增加了原生线程回复。媒体、语音和地址功能也因提供方和配置能力而异。Web 支持富文本,且完全在本地运行。+++Email 是原生、自托管的连接器,不需要第三方代理。它通过 IMAP IDLE 推送接收邮件,因此新邮件通常在数秒内到达代理。根据 RFC 要求,连接大约每 29 分钟刷新一次。回复通过 SMTP 发送,并支持完整附件;你可以使用自己配置的任意邮件服务商和地址。++`allowed_senders` 列表控制哪些发件人可以联系代理。请设置为你信任的地址。在 `config.toml` 中,空列表表示拒绝所有人。连接设置界面的行为不同:空白字段会变成 `["*"]`,允许所有发件人。如果不希望陌生人向代理发消息,请不要留空。++## 凭据方式++渠道支持三种登录方式。++- **通过 OpenHuman 托管连接。** 由 OpenHuman 后端代理的一键加密连接。适用于 Telegram(直接给托管机器人发消息)和 Discord(关联账户或通过 OAuth 安装)。令牌不会存储在本机。+- **使用自己的凭据。** 你提供机器人令牌、API 密钥和密钥,或应用凭据。Telegram(BotFather 令牌)、Discord、Slack、WhatsApp、Lark/Feishu、DingTalk、元宝、Signal、Mattermost、QQ、Linq、IRC 和 Email 均支持此方式。你拥有最高控制权,同时也负责平台账户、速率限制和 webhook 端点。+- **本地运行,无需凭据。** Web 聊天和 iMessage 不需要令牌。Web 在桌面应用内运行。iMessage 通过 AppleScript 操作本机 macOS 信息应用,因此需要授予“完全磁盘访问”权限。两者都会将消息保留在本机。++任何方式的密钥都会经过 OpenHuman 凭据层处理,并在静态存储时加密(参见[隐私与安全](privacy-and-security.md))。在界面中管理的渠道不会把明文密钥写入 `config.toml`。++## 连接渠道++请在左侧边栏的**连接 > 渠道**中设置渠道,而不是在“设置”中。打开该标签页,选择平台卡片,然后按照设置卡片操作:++- **Discord。** 选择通过 OpenHuman 托管连接(关联账户或通过 OAuth 安装机器人),也可以粘贴自己的机器人令牌。+- **Telegram。** 给 OpenHuman 托管机器人发消息以关联账户,或粘贴 BotFather 令牌。++Slack 作为应用连接在**连接 > OAuth**中,让代理可以读取和操作 Slack。它不会作为可双向对话的渠道出现在“渠道”标签页中。++## 选择默认渠道++在**连接 > 渠道**中可以选择当前路由。没有指定收件人时,主动消息(例如定时任务和触发器发出的消息)会使用该路由。默认值是应用内 Web 聊天。更改默认渠道会立即生效,无需重启,面板也会显示当前渠道。对收到的消息进行回复时,总是返回原渠道,不受默认设置影响。++## 延伸阅读++- [集成](integrations/README.md):代理读取上下文的数据源目录。+- [触发器](integrations/triggers.md):触发主动渠道消息的实时事件。+- [隐私与安全](privacy-and-security.md):凭据存储位置和后端边界。+- [操作系统密钥环与密钥存储](os-keyring-and-secret-storage.md):渠道密钥的静态保护。diff --git a/docs/gitbooks/zh/features/chat.md b/docs/gitbooks/zh/features/chat.mdnew file mode 100644index 0000000000..e9376dcea9--- /dev/null+++ b/docs/gitbooks/zh/features/chat.md@@ -0,0 +1,100 @@+---+description: >-+ 聊天界面:输入框、斜杠命令、提及、模型与思考强度选择器、上下文环、+ 工具时间线、审批、子代理卡片、文件和对话线程。+icon: comments+---++# 聊天++聊天几乎承载了所有工作。一次对话轮次可以调用工具、启动子代理、向你提问、等待审批、生成文件并记录自己的费用。聊天记录会按顺序显示整个过程。++从侧边栏打开**聊天**,或按 `⌘N` 新建对话。++## 输入框++输入框支持富文本,因此输入 `/` 时会出现命令标签,弹出菜单也会跟随光标。输入框周围还有:++- **附件**。核心接受图片、PDF、Office 文档和归档文件。聊天消息保存的是受作用域限制的不透明引用,而不是本地路径或内嵌媒体字节。每轮开始时,受信任的主机在当前轮次上下文中解析引用,并把支持的内容交给模型路由;不支持的文档类型会使用提取出的文本或归档文件列表。+- **模型**和**思考强度**。两者只影响当前对话,不会更改全局设置。+- **上下文环**。显示当前线程的上下文窗口使用情况。点击可查看明细,包括各子代理产生的费用。+- **语音**。点击即可说话,也可以把当前轮次交给实时语音代理。参见[语音](native-tools/voice.md)。+- **吉祥物按钮**。输入框为空时,点击会打开全屏[吉祥物](mascot/README.md)场景。++### 斜杠命令++输入 `/` 可查看内置命令(`/new`、`/clear`、`/stop`、`/plan`、`/build`)、核心命令,以及已安装的技能和工作流。++### 提及++输入 `@` 可搜索记忆,并查找当前线程已经生成的文件。提及会变成标签,让代理拿到明确引用,无需猜测。++## 查看一轮对话++每轮助手回复会按发生顺序,将推理和工具调用放在同一个区块中。++- 工具调用按工具类型显示。搜索会展示查询和来源;Shell 调用会显示命令和退出码;失败时显示原因而不是堆栈跟踪。所有工具都在核心中运行,不会在浏览器里运行。+- 回复下方会以徽章显示来源,最多展示四个,其余以数量表示。+- 对话轮次会显示耗时和费用。上下文环会把费用归到对应的子代理。+- **在对话中查找**(`⌘F`)只搜索当前线程。右侧边栏可在不同轮次间跳转。++助手回复可以复制、重新生成、点赞或点踩(选择会被记住)、朗读或导出为 Markdown。你也可以编辑并重新发送自己的消息;这会创建一个分支,分支选择器可切换不同版本。++## 需要你参与时++代理可能因四种原因暂停,每种情况都会在对话中显示:++| 暂停原因 | 你会看到什么 |+| --- | --- |+| 审批 | 卡片会显示工具名称和一行经过脱敏的说明。你可以批准一次、始终允许该工具,或拒绝。参见[审批](approval-gate.md)。 |+| 权限 | 连接器或提供方需要授权。卡片会要求该提供方所需的字段。 |+| 澄清 | 代理提出一个直接问题并等待回答。 |+| 计划审阅 | 代理提出计划。你可以批准、拒绝,或提供反馈要求修改。 |++后台或定时轮次没有人可以询问。实时聊天之外产生的审批请求会收集到一个待处理列表中,供你之后决定。十分钟内未决定的请求会被拒绝。++## 子代理++轮次委派工作时,每个子代理都有自己的卡片。卡片包含嵌套对话记录、状态、子代理等待你回复时使用的输入框,以及取消按钮。委派是异步的,因此父代理可以继续工作,同时卡片逐步显示结果。分离运行的后台代理、定时任务和记忆同步会收集在单独的收件箱卡片中,不会打断当前线程。++## 代理生成的文件++代理为你生成的内容(例如文档、演示稿、图片或渲染结果)会成为一个产物。输入框上方的标签会打开面板,你可以下载、在所在文件夹中查看或删除。只有已完成的产物会在重启后保留。失败的产物可以重试。++## 工作流提案++如果你要求自动化,代理会提出一个图。提案只会经过验证,不会立即保存。卡片会显示节点列表,并提供三个选项:保存并启用、忽略,或在画布中打开。只有通过这张卡片才能将提案保存为自动化。参见[工作流](workflows.md)。++## 对话线程++侧边栏会列出你的对话。你可以新建、选择、重命名和删除对话(删除前会要求确认)。不同线程可以同时运行,因此某个对话中的耗时任务不会阻塞其他对话。++线程可以包含代理设置的目标和待办清单。它们会以固定列表和显示 token 预算的横幅呈现。目前还不能在界面中编辑它们。++长对话会被压缩,而不是截断。压缩会封存之前的内容,并开始一个指向已封存内容的新一代记录。磁盘上的内容不会删除,但模型只会读取最新一代。目前没有浏览旧代记录的界面。++在 Web 聊天中,附件以带类型的内容部分传递。核心会把上传内容保存在持久化用户消息记录中,并通过受作用域限制的不透明引用访问;消息引用不使用本地文件路径或 base64 数据。轮次运行时,受信任的主机会解析这些引用,并将支持的图片、音频、视频或文件内容交给模型路由。语音便笺会在对话中保留带类型的音频和转写元数据,因此重新加载后仍可播放;听写只发送文本。++聊天主机负责自己的 RPC 和 socket 接口、输入与审批策略、会话检出以及回复的持久化投递。TinyAgents 提供通用轮次准入和排队机制。TinyChannels 提供规范的带类型 Web 事件契约和输出投影,并与 TUI 及中继 Web 进度共用。++## 键盘快捷键++| 快捷键 | 操作 |+| --- | --- |+| `⌘K` / `⌘P` | 打开命令面板 |+| `⌘N` | 新建对话 |+| `⌘F` | 在当前对话中查找 |+| `⌘B` | 切换侧边栏 |+| `⌘,` | 打开设置 |+| `⌘/` 或 `?` | 显示快捷键列表 |++## 尚未提供的功能++侧边栏目前没有线程搜索、置顶、文件夹或归档功能。界面暂时不能设置线程目标或勾选待办事项,也不能浏览压缩后的历史代。界面中有后续建议标签,但目前没有内容生成它们,因此这一行会保持为空。++## 延伸阅读++- [记忆](memory.md):代理回答前会回忆什么,以及回答后会写入什么。+- [编排器](orchestration.md):委派工作如何规划。+- [可用工具](native-tools/README.md):工具卡片会调用哪些工具。+- [通知与活动](notifications-and-activity.md):你离开页面时轮次结束会发生什么。