A3S Code
  • 简体中文
  • v6.5.2

      • A3S Code TUI

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

      需要现成的终端编程智能体时使用 TUI；要构建自己的运行框架、IDE 扩展、 服务器工作进程、工作流运行器或产品界面时使用 SDK。

      界面结构

      组成部分仓库职责
      A3S Code SDKA3S-Lab/CodeRust 运行时 crate，以及 Node.js、Python 和 Go SDK。
      a3s codeA3S-Lab/a3s驱动 A3S Code 会话的终端编程智能体应用。
      A3S UseA3S-Lab/Use独立发布的 Browser、原生 Office、内置 OCR、可选 Office 兼容层，以及通过标准 MCP 与 Skill 投影到 Code 的签名外部应用能力。
      a3s-tuiA3S-Lab/TUICLI 使用的终端界面框架，不是智能体运行时。
      A3S 单体仓库A3S-Lab/a3s产品文档、发布编排、子模块版本固定与相关 crate。

      安装

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

      macOS / Linux
      Windows
      SHELLSCRIPT
      curl --proto '=https' --tlsv1.2 -LsSf \

        https://raw.githubusercontent.com/A3S-Lab/a3s/main/install.sh | sh

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

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

      SHELLSCRIPT
      a3s code

      a3s code resume <session-id>

      a3s code resume

      a3s code update

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

      配置

      TUI 按以下顺序发现配置：

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

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

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

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

      ACL
      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

          }

        }

      }

      会话恢复

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

      恢复时会保留该会话的模型及凭据来源、推理强度、执行模式 （default、plan 或 auto）和语法高亮主题。如果退出中断了 durable /goal，启动时 会显示“继续目标”与“保持暂停”：前者从下一次目标迭代继续，且不改变已恢复的执行模式； 后者进入会话并保持目标暂停，之后可用 /goal resume 继续。

      文件系统优先工作流

      TUI 面向工作区。它在仓库中启动时，可以加载 SDK 会话也会使用的文件系统优先约定：

      路径TUI 中的作用
      AGENTS.md加载到上下文中的项目说明。
      .a3s/config.acl项目本地模型、服务提供商、技能、存储和委派策略。
      .a3s/agents/可供 task、parallel_task 和自动委派使用的工作角色。
      .a3s/skills/ 与 skills/暴露给会话的可复用项目技能。
      .a3s/kb/TUI 知识工作流使用的项目知识库。

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

      通过 A3S Use 使用浏览器、办公文档与文字识别

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

      SHELLSCRIPT
      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 主程序就绪后，Code 会读取它带版本号的能力注册表，并同时监听代次与内容修订。 之后服务提供商变化，以及扩展的安装、升级、启用或禁用，都会把对应 MCP 与已校验的 SKILL.md 热插拔到当前会话。如果启动时缺少组件且首次准备被禁用或失败，则需要在 显式安装后重启 Code 一次；之后的能力变化不需要重启。

      /use 与 /use status 会显示 Use 可执行文件路径和版本、注册表收敛状态、 服务提供商就绪状态、MCP 连接与工具数量，以及技能的校验和加载状态。/use repair 只打印非破坏性的修复指引，绝不会自动执行安装或改变扩展状态。

      主编码模型有意看不到原始 mcp__use_* 定义；它通过 task 看到专用的 use 工作智能体，并把应用操作委派给它。Use 工作智能体只能看到 mcp__use_*，不能使用 命令行、工作区、无关 MCP 或递归委派工具。受管技能只提供领域指引，不能扩大权限。 用户可以直接说“用浏览器检查这个页面”“用 Office 更新这个工作簿”或“对这张扫描图做 文字识别”，无需手写工具名。能力不可用时，工作智能体会返回带类型的失败结果，不会 换用其他工具兜底。默认浏览器接口包含诊断和有边界的安装工具；缺少受管浏览器时， 只能在父 TUI 确认后由 Use 工作智能体请求安装。

      能力Code 接口服务提供商与确认行为
      浏览器mcp__use_browser__*使用已发现的浏览器，或通过需要父级 HITL 的修改请求安装受管服务提供商。封闭会话内的只读检查可直接执行；导航、联网读取、输入、点击与提交需要 HITL。
      原生 Officemcp__use_office__*使用带修订与冲突检查的有界原生 Office 包内核。封闭环境内的读取可直接执行；修改与破坏性保存需要 HITL。
      内置 OCRmcp__use_ocr__*通过 ONNX Runtime 在本地运行固定版本的 PP-OCRv6_small 检测与识别模型。诊断与提取均为封闭环境只读工具，源文件字节不会离开设备。

      MCP 行为元数据只能提升风险，不能降低父级策略。只有同时声明 readOnlyHint=true、openWorldHint=false 且不是破坏性操作时，才不需要额外确认。 缺少注解、开放世界、修改、破坏性或提交风险都会向父 TUI 请求确认；父级拒绝始终有效。 Office 修改绝不会被自动重试，尤其 use.office.outcome_unknown 表示变更可能已经 落地，工作智能体必须保留证据并停止。

      Code 也不会把 MCP 结果压扁成纯文本：outputSchema、structuredContent、图片、 文本或二进制资源、协议元数据和带 SHA-256 的有界制品都会进入正常的对话记录和 工具结果路径。

      运行时事件流

      TUI 将 AgentSession::stream() 视为事实来源。运行时事件驱动对话文本、工具调用 进度、规划状态、批准提示、记忆视图、Git 和文件面板、验证证据与可回放的运行状态。

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

      这个分层对产品构建者很重要：TUI 只是运行时上方的一个有主张的客户端。 SDK 嵌入方可以基于同样的会话、工具、事件、持久化与验证 API 构建不同控制面。

      斜杠命令

      内置斜杠命令包括：

      命令作用
      /model在已配置模型和已登录账号模型之间切换。
      /init分析工作区并生成 AGENTS.md。
      /config在编辑器中打开当前生效的 ACL 配置。
      /use / /use status / /use repair查看实时 A3S Use 能力状态，或打印不会自动执行的显式修复指引。
      /theme切换代码高亮主题。
      /flow选择或草拟工作流资源，用于本地开发与可选宿主集成。
      /agent选择智能体定义，用于本地开发与可选宿主集成。
      /mcp选择 MCP 服务资源，用于本地开发与可选宿主集成。
      /skill选择技能资源，用于本地开发与可选宿主集成。
      /okf选择 OKF 包，用于本地开发与知识包管理。
      /login 与 /logout登录或退出 os 端点对应的 A3S OS 账号。
      “打开视图”点击内联按钮，在原生窗口中打开最近验证过的本地报告或可信运行时视图。
      /plugin 与 /reload启用、禁用并重新扫描技能与插件。
      /ide打开工作区文件树和代码查看器。
      /memory浏览长期记忆。
      /kb把文本、文件或目录加入项目知识库。
      /ctx搜索历史会话、附加结果，或保存到记忆。
      /effort调整对所有服务提供商生效的宿主预算，并在其支持时传递原生推理强度。
      /compact总结并压缩对话上下文。
      /goal <text>为会话设置持续目标。
      /goal resume继续会话恢复时保持暂停的持久目标。
      /loop自动继续执行任务，直到完成或停止。
      /sleep把今天的工作整理进长期记忆。
      /help显示命令与快捷键。
      /fork从当前点分支出新的已保存会话。
      /clear重置对话。
      /auto切换到自动批准模式。
      /update将 CLI 升级到最新发行版。
      /exit退出 a3s code。

      部分命令只能在会话空闲时执行，因为它们会改变对话、模型、上下文或进程状态。

      推理强度与深度研究

      级别推理预算工具轮次续写次数并行任务数
      low2,04824044
      medium8,19280088
      high16,3841,2001212
      xhigh32,7681,8001616
      max65,5362,4002424
      ultracode65,5363,2003232

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

      深度研究当前先收集有数量上限的网页种子，再根据复杂度选择直接快速路径，或本地 parallel_task 轨道与有上限的后续回合。在函数即服务支持就绪前，A3S OS 运行时的 工具调用扇出保持禁用。

      在 TUI 输入 ? <query> 可启动深度研究。默认情况下，它允许直接网页访问和委派网页 工具；查询中包含 no web、do not use web 或 不要联网 时，这些网页路径会被 禁用，同时保留本地证据收集与后续深度。

      每次运行的制品位于：

      Text
      .a3s/research/<slug>/report.md

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

      已完成报告必须能够追溯到本次运行收集的来源。若证据收集或合成无法满足这个条件， A3S 会写入明确标注的低置信度深度研究恢复报告，而不是把无证据结论伪装成已完成报告。 本地 HTML 由仅环回地址、无需认证的查看器提供，因此退出登录时也可以通过 “打开视图”打开。

      无界面命令使用相同工作流：

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

      --local 只表示本地编排，仍允许网页证据；--local-only（也接受 --offline） 会强制禁用网络，--web 会显式启用网页与工作区证据。自然语言中的 no web 仅作为兼容性兜底。--os 当前禁用。无界面命令的所有阶段共同消耗 一个 60 秒绝对时限，其中宿主直接执行最多使用 20 秒；失败后仅用剩余预算执行 最多一轮兜底，并为取消与制品收尾保留最后 3 秒。若最终只能生成恢复报告， 制品仍会落盘，但命令会以错误状态结束。

      相关页面

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