#A3S Code TUI

a3s code 是 A3S Code 的交互式终端应用。它由 a3s CLI 发布，嵌入 a3s-code-core 运行时，并使用 a3s-tui 渲染运行时事件流。

需要现成的终端编程 agent 时使用 TUI；要构建自己的 harness、IDE 扩展、 server worker、workflow runner 或产品 UI 时使用 SDK 包。

#Surface Map

#安装

先运行对应平台的一键安装脚本：

curl --proto '=https' --tlsv1.2 -LsSf \
  https://raw.githubusercontent.com/A3S-Lab/a3s/main/install.sh | sh

[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
irm https://raw.githubusercontent.com/A3S-Lab/a3s/main/install.ps1 | iex

脚本会选择当前系统与架构对应的发布包并校验 SHA-256。也可以使用 brew install a3s-lab/tap/a3s 或 cargo install a3s。

安装后，在希望 Agent 检查的 Workspace 中运行：

a3s code
a3s code resume <session-id>
a3s code resume
a3s code update

顶层 a3s update 命令也会被 CLI 接受，并路由到同一个 updater。

#配置

TUI 按以下顺序发现配置：

1. A3S_CONFIG_FILE
2. 从当前目录向上查找的 .a3s/config.acl
3. ~/.a3s/config.acl

TUI 使用 .a3s/config.acl 作为项目本地配置。SDK 示例经常使用 agent.acl，因为 embedders 会通过 Agent.create("agent.acl") 显式传入 配置路径。二者都是 ACL 文件；关键区别在于由谁发现文件。 可选 A3S OS endpoint 使用 os = "https://..." 配置。

/ide 与 /config 共用同一套全屏编辑器。文件树使用终端安全的文件类型与目录 符号、语义化图标颜色和对齐的展开标记；编辑器标题、文件 metadata 与带分隔线的 行号 gutter 复用同一图标来源，不依赖 emoji 或 Nerd Font。

不要把真实 key、私有 provider URL、tenant 标识或用户本地路径提交到仓库。 公开模板应通过环境变量解析凭据：

default_model = "provider/model-id"
os = env("A3S_OS_URL")

providers "provider" {
  apiKey = env("PROVIDER_API_KEY")
  baseUrl = env("PROVIDER_BASE_URL")

  models "model-id" {
    tool_call = true
    limit = {
      context = 128000
      output = 4096
    }
  }
}

#会话恢复

Core session 快照会自动保存到 <workspace>/.a3s/tui/sessions/v1/sessions，TUI 自己维护的逐 session 状态保存在 <workspace>/.a3s/tui/session-state/v1。退出后，CLI 会打印完整的 a3s code resume <session-id> 命令；启用颜色输出时，该命令会高亮显示。不带 id 的 a3s code resume 会恢复当前 workspace 中最新的 saved session。

恢复时会保留该 session 的模型及 credential source、effort profile、执行模式 （default、plan 或 auto）和语法高亮主题。如果退出中断了 durable /goal，启动时 会显示 Resume goal 与 Leave paused：前者从下一次 goal iteration 继续，且不改变已恢复的 执行模式；后者进入 session 并保持 goal 暂停，之后可用 /goal resume 继续。

#文件系统优先工作流

TUI 面向 workspace。它在仓库中启动时，可以加载 SDK session 也会使用的 filesystem-first 约定：

这些文件让行为可审查，但不会绕过运行时边界。权限策略、确认提示、 workspace 检查、工具可见性、响应契约与验证仍然通过 A3S Code 执行路径。

#通过 A3S Use 使用 Browser、Office 与 OCR

A3S Use 是独立发布的 first-use 组件。终端接管前，a3s code 会复用健康安装；网络和 自动准备策略允许时，会安装经过校验的 release。--offline、A3S_OFFLINE=1 和 A3S_NO_AUTO_INSTALL=1 始终禁止该修改。准备失败不会阻止 Code 启动，并会通过 /use 保持可诊断。runtime 与模型资源也可以显式提前准备：

a3s install use --source release
a3s install use/browser

# 可选的 OfficeCLI 兼容 provider；原生 Office 已内置在 Use 中。
a3s install use/office

# 安装或修复固定版本的本地 PP-OCRv6 模型。
a3s install use/ocr
a3s use ocr doctor --json

当 Use 主程序 ready 后，Code 会读取它带版本的 capability registry， 并同时监听 generation 与内容 revision。之后 provider 变化，以及 extension 的安装、升级、 启用或禁用，都会把对应 MCP 与已校验的 SKILL.md 热插拔到当前 session。如果启动时缺少 首次准备被禁用或失败，则需要在显式安装后重启 Code 一次；之后的 capability 变化不需要重启。

/use 与 /use status 会显示 Use binary 路径/版本、registry 收敛状态、provider readiness、MCP 连接与工具数量，以及 Skill 的校验/加载状态。/use repair 只打印非破坏性的 修复指引，绝不会自动执行安装或改变 extension 状态。

主 coding model 有意看不到原始 mcp__use_* definitions；它通过 task 看到专用的 use worker，并把应用操作委派给该 worker。Use worker 只能看到 mcp__use_*，不能使用 shell、workspace、无关 MCP 或递归委派工具。受管 Skill 只提供领域指引，不能扩大权限。 用户可以直接说“用 Browser 检查这个页面”“用 Office 更新这个工作簿”或“对这张扫描图做 OCR”，无需手写工具名。能力不可用时，worker 会返回 typed failure，不会换用其他工具兜底。 默认 Browser surface 包含 doctor 和有界安装工具；缺少 managed Browser 时，只能在父 TUI 确认后由 Use worker 请求安装。

MCP behavior metadata 只能提升风险，不能降低父级策略。只有同时声明 readOnlyHint=true、openWorldHint=false 且不是 destructive 的操作才无额外确认。 缺少 annotations、open-world、mutation、destructive 或 submit 风险都会向父 TUI 请求 确认；父级 deny 始终有效。Office mutation 绝不会被自动重试，尤其 use.office.outcome_unknown 表示变更可能已经落地，worker 必须保留证据并停止。

Code 也不会把 MCP 结果压扁成纯文本：outputSchema、structuredContent、图片、 text/blob resources、协议 metadata 和带 SHA-256 的有界 artifacts 都会进入正常的 transcript/tool-result 路径。

#Runtime Event Stream

TUI 将 AgentSession::stream() 视为事实来源。运行时事件驱动 transcript 文本、 tool-call 进度、planning 状态、approval prompt、memory view、git/file panel、 verification evidence 与可 replay 的 run state。

Ctrl+T 打开完整、实时的语义会话 transcript，其中包括用户与 助手消息、plan、每个工具的完整生命周期与完整输出、subagent 状态，以及当前仍在 流式生成的 Markdown 尾部。

这个分层对产品构建者很重要：TUI 只是 runtime 上方的一个有主张的客户端。 SDK embedders 可以基于同样的 session、tool、event、persistence 与 verification API 构建不同控制面。

#Slash Commands

内置 slash commands 包括：

部分命令只能在 session 空闲时执行，因为它们会改变 conversation、model、 context 或 process state。

#Effort 与 DeepResearch

low 到 max 保持 Codex 原生 reasoning.effort 映射，并关闭运行时自动委派； task 与 parallel_task 仍可被明确调用。只有 ultracode 会启用自动委派、 自动规划与动态工作流指引。仅用于生成最终回答的 synthesis continuation 不会再次 启动子 Agent。

DeepResearch 当前先收集 bounded web seed，再根据复杂度选择 direct fast path 或本地 parallel_task tracks 与 bounded follow-up rounds。在 Function-as-a-Service support 就绪前，A3S OS Runtime tool-call fan-out 保持禁用。

在 TUI 输入 ? <query> 可启动 DeepResearch。默认情况下，它允许 Direct Web 和 delegated web tools；query 中包含 no web、do not use web 或 不要联网 时， 这些 web paths 会被禁用，同时保留本地 evidence collection 与 follow-up depth。

每次 run 的 artifacts 位于：

.a3s/research/<slug>/report.md
.a3s/research/<slug>/index.html

completed report 必须能够追溯到本次 run 收集的 sources。若 evidence collection 或 synthesis 无法满足这个条件，A3S 会写入明确标注、low-confidence 的 DeepResearch Recovery Report，而不是把 unsupported conclusion 伪装成 completed report。本地 HTML 由 loopback-only、no-auth viewer 提供，因此 signed out 时也可以通过 Open view 打开。

Headless command 使用相同 workflow：

a3s code deepresearch [--local|--os] [--local-only|--web] <query>

--local 只表示本地编排，仍允许 web evidence；--local-only（也接受 --offline） 会强制禁用网络，--web 会显式启用 web + workspace evidence。自然语言中的 no web 仅作为 compatibility fallback。--os 当前禁用。headless command 的所有阶段共同消耗 一个 60 秒 absolute deadline，其中 host-direct 最多使用 20 秒；失败后仅用剩余预算执行 最多一轮 fallback，并为取消与 artifact 收尾保留最后 3 秒。若最终只能生成 recovery report，artifacts 仍会落盘，但 command 会以 error 结束。

#相关页面

1. 文件系统优先
2. 会话
3. 命令
4. 工具
5. 安全