A3S Code
  • 简体中文
  • v6.6.0

      • A3S Code

      A3S Code 是 a3s code 终端应用背后的 Rust Runtime，也可以单独接入 IDE、 Runner 或服务端。它负责 Agent Loop、上下文、工具调用、权限检查、子任务、 Workspace 访问，以及任务的保存和恢复。

      想直接在终端里使用，安装 a3s CLI。 想构建自己的产品，使用 Rust crate、Node.js 包、Python 包，或配合原生桥接程序 使用 Go module。它们输出同一套事件，因此不同界面不需要各写一套 Agent Loop。

      先选使用方式

      入口什么时候用仓库
      Rust / Node.js / Python / Go SDK把编码 Agent 接入 IDE、Runner、服务端或自己的 UIA3S-Lab/Code
      a3s code直接在终端里运行编码 AgentA3S-Lab/a3s
      a3s-tui构建终端界面，不包含 Agent RuntimeA3S-Lab/TUI
      A3S Web查看桌面任务界面和组件实现apps/web
      A3S Flow为 DynamicWorkflowRuntime 保存和恢复流程A3S-Lab/Flow

      主要能力

      领域可以做什么
      Agent 会话通过异步 SessionBuilder 创建绑定到 Workspace 的 AgentSession；支持 send、run、stream、取消、保存、恢复和清理。同一会话发生并发冲突时会立即报错。
      终端界面a3s code 把事件流显示成终端对话，并展示工具调用、确认提示、记忆、文件和会话状态。
      项目约定文件系统优先 介绍如何用 AGENTS.md、agent.acl、.a3s/agents/、skills/、tools/ 和 schedules/ 管理项目配置。
      工具内置文件、搜索、Shell、Git、网页、Batch、结构化输出、QuickJS、Skills、MCP 和子任务工具。模型发起的调用统一经过参数、权限、确认和取消检查。
      命令命令 说明 TUI 的斜杠命令，以及如何在 SDK 中注册自己的 /command。
      子任务通过 task、parallel_task、session.task(...) 和 session.tasks(...) 使用内置或自定义 Agent；自动委派可以单独开关。
      流程编排session.parallel、session.pipeline、阶段、Checkpoint、循环上限和预算记录，可用于编写固定且可恢复的工作流。
      定时任务AgentDir 可以通过 serveAgentDir / serve_agent_dir 运行定时 Turn；每个 Schedule 使用稳定的 schedule:<name> Session。
      安全权限策略、用户确认、预算、Workspace 路径检查、工具超时、Hook 和输出清理都会在执行过程中生效。
      WorkspaceWorkspace 后端 支持本地文件、应用提供的 Workspace、可选的 S3 兼容存储和 remote-git 服务。
      事件EventEnvelopeV1 是 Rust、Node.js、Python、Go 共用的事件格式；未知事件的 Payload 和 Metadata 也会保留。
      保存与恢复SessionSnapshotV1、Session ID、Auto-save、Run Event、Trace、Artifact、Loop / Workflow Checkpoint 和 Memory Store 用来恢复会话和回放运行过程。
      验证验证 支持验证命令、预设、结构化报告、摘要、Artifact、Trace Event 和 Run Replay。

      一次执行大致会经过这些步骤：

      Text
      Agent / AgentSession

        -> 收集项目上下文

        -> 可选 Plan

        -> 模型选择工具或子任务

        -> 检查权限，必要时询问用户

        -> 执行

        -> 发送事件和验证结果

        -> 保存会话

      安装

      想使用交互式终端应用时，运行对应平台的一键安装脚本：

      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。

      当你要把 A3S Code 嵌入自己的产品时，安装 SDK 包：

      SHELLSCRIPT
      npm install @a3s-lab/code

      pip install a3s-code

      cargo add a3s-code-core

      go get github.com/A3S-Lab/Code/sdk/go/v6

      配置

      A3S Code 使用 ACL。不要把真实 API Key、私有模型端点、本地配置路径或 tenant/user 标识提交到仓库；提交只通过环境变量解析凭据的模板。

      ACL
      default_model = "provider/model-id"

      max_parallel_tasks = 4

      auto_parallel = false

      

      providers "provider" {

        apiKey = env("PROVIDER_API_KEY")

        baseUrl = env("PROVIDER_BASE_URL")

      

        models "model-id" {

          tool_call = true

          limit = {

            context = 128000

            output = 4096

          }

        }

      }

      

      agent_dirs = ["./.a3s/agents"]

      skill_dirs = ["./skills"]

      storage_backend = "file"

      sessions_dir = ".a3s/sessions"

      auto_parallel = false 只关闭自动并行子智能体扇出。手动 parallel_task 和 SDK session.tasks(...) 仍然可用，除非你单独关闭手动委派。 本地 session 持久化需要把 storage_backend = "file" 和 sessions_dir 配对； SDK embedding 场景也可以直接传 typed FileSessionStore。

      使用 TUI

      在你希望 agent 检查的 workspace 中运行 a3s code：

      SHELLSCRIPT
      a3s code

      a3s code resume <session-id>

      a3s code update

      TUI 会按顺序发现配置：A3S_CONFIG_FILE、从当前目录向上查找的 .a3s/config.acl，以及 ~/.a3s/config.acl。 顶层 a3s update 命令会进入同一个 updater。

      使用 SDK

      TypeScript
      import { Agent } from '@a3s-lab/code';

      

      const agent = await Agent.create('agent.acl');

      const session = agent.session('/path/to/workspace', {

        planningMode: 'auto',

        permissionPolicy: {

          allow: ['read(*)', 'grep(*)', 'glob(*)'],

          ask: ['bash(*)', 'write(*)'],

          deny: ['write(**/.env*)', 'bash(rm -rf*)'],

          defaultDecision: 'ask',

          enabled: true,

        },

      });

      

      const result = await session.send('Find the authentication entry points.');

      console.log(result.text);

      console.log(result.verificationSummaryText);

      

      session.close();

      await agent.close();

      接着看

      • A3S Code TUI 说明安装、配置发现、斜杠命令和 Effort。
      • SDK 与 API说明 Go 模块和桥接程序的安装方式；后续 Go 示例会与 Node.js、Python 一起出现在各通用章节中。
      • 文件系统优先 介绍 AGENTS.md、ACL、AgentDir、Skill、工具和定时任务。
      • API 契约 列出经过集成测试的 Node.js API。
      • 会话 介绍创建、流式输出、运行状态、保存、恢复和取消。
      • 工具 介绍直接调用、错误类型、结构化输出和 QuickJS Program。
      • 任务 与 编排 介绍子 Agent 和固定工作流。
      • 安全、Hook 与 验证 介绍执行前、执行中和执行后的检查。
      • Memory 与 持久化 介绍跨会话信息和任务恢复。