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、服务端或自己的 UI	A3S-Lab/Code
`a3s code`	直接在终端里运行编码 Agent	A3S-Lab/a3s
`a3s-tui`	构建终端界面，不包含 Agent Runtime	A3S-Lab/TUI
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`，或宿主侧 `session.task(...)` 与 `session.tasks(...)` 使用内置或自定义 Agent；单项聚焦执行，多项独立任务并发扇出。
任务调度	一个 Agent 级优先级调度器在 Session、直接工具、detached 子任务和宿主工作流之间共享本地执行容量，并提供 FIFO、老化、取消和占用快照。
流程编排	`session.parallel`、`session.pipeline`、阶段、Checkpoint、循环上限和预算记录，可用于编写固定且可恢复的工作流。
定时任务	AgentDir 可以通过 `serveAgentDir` / `serve_agent_dir` 运行定时 Turn；每个 Schedule 使用稳定的 `schedule:<name>` Session。
安全	权限策略、用户确认、预算、Workspace 路径检查、工具超时、生命周期 Hook 和输出清理都会在执行过程中生效。
Workspace	Workspace 后端支持本地文件、应用提供的 Workspace、可选的 S3 兼容存储和 remote-git 服务；原生 Harness 可用 detached Git worktree 隔离会话。
工作区检索	工作区检索提供异步 Session 文本目录、增量 BM25、可选宿主 Embedding、精确内存向量、Hybrid RRF 与可选确定性 CPU Rerank，不依赖向量数据库。
事件	`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。

v7.0 新增内容

Session-owned Workspace Retrieval 会异步构建一个有界文本目录，复用增量 BM25 Posting，并可发布精确内存向量分区；Session 构建不会等待索引，也不需要向量数据库。
语义检索必须由宿主显式开启。Exact、Glob、BM25、Code Intelligence、RRF 和可选的确定性 Reranker 都在本地 CPU 上运行；需要语义检索时，宿主可以注入进程内 CPU Embedding 回调。
Rust、Node.js、Python 和 Go 统一提供 Typed Line、Fixed-window、Recursive Chunking、Readiness 与 Batching 指标、可选确定性 Rerank、取消、当前源摘要校验和有界清理。非文本文件在切块和 Embedding 之前就会被排除。
模型边界 Run 证据会绑定实际能力与 Policy Identity、检索 Generation、输入形状、重复 Tool result 上下文和归一化 Usage，同时不会新增保存 Prompt、源文本、向量、凭据或端点明文。

Go 使用方必须改用 v7 Module 路径： github.com/A3S-Lab/Code/sdk/go/v7。

v6.9 引入了共享优先级/FIFO 调度器、有界个人与项目指令链、受治理生命周期 Hook、隔离 Harness Git worktree、确定性 Tool-result 证据和精确 Cognitive-package Generation Binding。

v6.8 只向模型呈现一套紧凑的 search 模式，统一 grep、glob 和零依赖 BM25 排序；同时以一个模型可见的 task 模式覆盖聚焦任务与有界并发扇出。旧的宿主直调别名仍可读取，但不再消耗模型工具 Schema Token。本版本还为 Headless 宿主增加精确、重放安全的 Run 准入，并通过 Node.js、Python 和 Go SDK 返回统一的快照与重放状态。

v6.7 的本地 download 工具会通过 SSRF 安全的重定向校验，把 HTTP(S) 资源流式写入相邻临时文件；它支持自适应 1–4 连接 Range 传输，并可在原子提升前校验 64 位 expected_sha256。这是受权限与 HITL 治理的工作区修改操作，远端工作区后端不会注册。详见工具。

搜索使用结构门控级联：Core 默认 feature 中的 Chrome/Chromium 层、HTTP/RSS 引擎，然后是原生 API。完整级联仍未达到结构化检索要求时会失败关闭，不会把弱候选当成成功证据，也不需要外部语义验证器或重排序 API。委派上下文共享 bulkhead、重试预算和相同请求合并，详见工具。

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

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/v7

配置

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 只关闭自动并行子智能体扇出。手动 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(*)', 'search(*)'],
    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。
工作区检索介绍显式语义开关、切块、生命周期、质量指标和 CPU-only 安全默认值。
任务与编排介绍子 Agent 和固定工作流。
安全、Hook 与验证介绍执行前、执行中和执行后的检查。
Memory 与持久化介绍跨会话信息和任务恢复。

#A3S Code

#先选使用方式

#主要能力

#v7.0 新增内容

#安装

#配置

#使用 TUI

#使用 SDK

#接着看

A3S Code

先选使用方式

主要能力

v7.0 新增内容

安装

配置

使用 TUI

使用 SDK

接着看