A3S Code

A3S Code 是 a3s code 背后的 Rust Runtime。也可以嵌进 IDE、Runner、服务端或桌面应用，复用同一套 Agent 循环：工具、权限、子任务、工作区搜索，以及会话的保存和恢复。

默认 profile 是 local-code：Agent 循环、工作区工具、策略、事件，以及纯 Rust 的 a3s-vec 词法检索。read 对 JPEG/PNG/GIF/WebP 返回图片附件；OpenAI 兼容路径在工具结果里保留 image_url。项目规则写在 AGENTS.md，Worker 放在 .a3s/agents/。

设计规则

规则	含义
默认变薄	Core `default` = `local-code`。Advanced 评估、server、无头搜索需显式开启。
Grep ≠ a3s-vec	精确 `grep` 负责匹配；trigram 只缩小候选，失败就回退。排序检索用 `bm25`。
单一委派路径	多条目扇出使用 `task` / `session.tasks`。不要恢复 `parallel_task`。
仅 Active 记忆	Durable 服务路径为 `active_recall`。拒绝 Candidate shadow。
Gate 先要证据	证据不完整或存在 retention 缺口时，Gate 不可宣称已完成评估。
宿主拥有产品策略	评审 rubric、Cloud 审计与 UI 确认留在 Core 之外。

想直接在终端里使用，安装 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`、steer、interrupt、取消、保存、恢复和清理。同一会话发生并发冲突时会立即报错。
终端界面	`a3s code` 把事件流显示成终端对话，并展示工具调用、确认提示、记忆、文件和会话状态。
项目约定	文件系统约定介绍 `AGENTS.md`、`agent.acl`、`.a3s/agents/` 和 `skills/`。
工具	内置文件、二进制安全的本地下载、搜索、Shell、Git、网页、Batch、结构化输出、QuickJS、Skills、MCP 和子任务工具。模型调用统一经过参数、权限、确认、取消、确定性结果投影与证据记录。
命令	命令说明 TUI 的斜杠命令，以及如何在 SDK 中注册自己的 `/command`。
子任务	通过模型可见的 `task`，或宿主侧 `session.task(...)` 与 `session.tasks(...)` 使用内置或自定义 Agent；单项聚焦执行，多项独立任务并发扇出。
任务调度	一个 Agent 级优先级调度器在 Session、直接工具、detached 子任务和宿主工作流之间共享本地执行容量，并提供 FIFO、老化、取消和占用快照。
流程编排	`session.parallel`、`session.pipeline`、阶段、Checkpoint、循环上限和预算记录，可用于编写固定且可恢复的工作流。
Worker agents	通过 `.a3s/agents/` 加载定义，供 `task` / 自动委派使用。
安全	权限策略、用户确认、预算、Workspace 路径检查、工具超时、生命周期 Hook 和输出清理都会在执行过程中生效。
Workspace	Workspace 后端支持本地文件、应用提供的 Workspace、可选的 S3 兼容存储和 remote-git 服务；原生 Harness 可用 detached Git worktree 隔离会话。
工作区检索	工作区检索提供异步 Session 文本目录、纯 Rust a3s-vec FTS/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。

v9.0.0 新增内容

事实日志控制。 编码运行只通过折叠事实日志选择下一步转移。确认和提问停到回答事实出现，进程内计时器不会替它们做决定。缺失的工具结果在恢复时只执行一次。
Meta Harness。 宿主在同一份事实日志上组合有序的 components：内置 system、tools、budget、compact、infer，以及已注册的 host:<id> 组件。权限投影和完成门禁仍由 Core 掌控。不传 harness 时保持默认 coding_actor 树。
Go 模块主版本升到 v9。 请导入 github.com/A3S-Lab/Code/sdk/go/v9，替换原来的 v8 模块路径。

同属 v9.0.0（曾以 v8.7.0 打 tag，从未发布）

a3s-vec 词法 FTS。 工作区 FTS 改用纯 Rust a3s-vec（a3s_vec_fts_v1）。磁盘上的 zvec_rust_fts_v1 generation 不兼容，会重建。
web_search 有可用结果即成功。 默认级联是 API，然后 HTTP/RSS，最后 headless。非空可用行是 complete 或 partial 成功；结构门槛只决定是否继续级联。JSON 保持结果数组（#161）。

v8.6.0 新增内容

图片 read + OpenAI 工具图片。 read 以 Attachment 图片结果返回 JPEG/PNG/GIF/WebP，与工具描述一致。OpenAI 兼容客户端在工具结果中保留 image_url，而不是压成纯文本（#156 / #152）。
隔离目录 orphan 清理。 create_worktree 前会清理空的非 worktree .a3s-isolate-* 同级目录，避免崩溃后的 bind 残留阻塞下一次隔离（#155）。
Layer C 在线预算余量。 Bailian Flash 在线外层预算（工作区检索与 harness loop）对齐到 420s，且不放宽内核断言（#155）。
仍包含 8.5 的完成门禁、Search 3.1.4、SDK 宿主契约、GLM base_url 拼接，以及 trigram grep。

v8.5.6 新增内容

未验证的工作区改动不能完成。 改过工作区的一轮保持未完成，除非有一份 Passed 的验证报告绑定该变更 digest，或宿主豁免覆盖该 digest。助手正文不算，宿主豁免也不能由模型授予。
Search 3.1.4。 具名引擎可以使用可选计费提供方 tinyfish、bocha、 aliyun、tencent、firecrawl。它们不进入默认级联。
SDK 宿主契约。 Node、Python、Go 暴露 sync_global_mcp_servers / global_mcp_status、会话审查、结果账本，以及 Core 上已有的可序列化 SessionOptions 字段。trait object 宿主钩子仍然省略。

v8.5.5 新增内容

GLM Coding Plan base_url 拼接。 类似 https://open.bigmodel.cn/api/coding/paas/v4 的基础地址会正确拼接到 /chat/completions，不会加 /v1，也不会重复 /paas/v4。
更快的字面量 grep（CODE-G1，自 8.5.1）。 在 .a3s-code/grep-trigram 下建失败可回退的 trigram 缓存。精确正则仍在 Code 里跑，这条路径不打开持久 a3s-vec FTS。
会话存储 WAL flock（自 8.5.1）。 并发写者在 flock 下重读持久最大序号；坏 WAL 可以隔离，宿主从快照继续。
仍包含 8.4 的小 harness 默认，以及 8.3 的耐久 / 信任改动。

早期 v8.4.0 新增内容

库与 SDK 默认变薄：a3s-code-core 默认 local-code（纯 Rust a3s-vec-fts）； Node / Python / Go SDK crate 默认 a3s-vec-fts。产品嵌入需要时再显式启用 advanced-harness、server 和/或 headless-search。
模型可见的 parallel_task 已移除；多条目扇出统一使用 task 工具。对应的 Node / Python / Go 辅助 API 一并删除。
Durable Memory 服务路径仅为 Active（active_recall）。Candidate shadow 模式已移除；抽取仍可写入 Candidate，直至宿主激活。
内置 update_plan 清单工具，以及宿主侧 set_output_language / outputLanguage（Rust 与各 SDK）。
SDK capabilities 发布为 a3s-code/sdk-capabilities/v2， tier: baseline | advanced。
Gate 模式评估在证据不完整时 fail-close；首性原则 E2E 与 Harness 收口手册见 manual/FIRST_PRINCIPLES_E2E.md 与 manual/HARNESS_CONVERGENCE.md。
延续 8.3 耐久/信任内核（可协商 Session Store、工具结果信任标签、工作区来源快照、可失败 FFI 初始化，以及宿主侧不可变内容 / Checkpoint 钩子）。

早期 v8.3.0 新增内容

Session Store 耐久性可协商（KRN-6）。内置 memory / file 适配器会精确声明聚合 CAS、append-only WAL、写者租约 fencing、可选 AES-256-GCM 静态加密、提交 watch，以及引用感知的 Artifact GC。
每个工具结果都带有类型化信任标签（KRN-5）：trusted、workspace data 或 external。Rust 与四种 SDK 都暴露无密钥的 model_middleware_health 计数器。
工作区检索把结果绑定到可防篡改的来源快照（KRN-4）。持久 BM25 / a3s-vec 索引在 Windows 与 Linux 上通过发布资格验证，包括在原生打开前剥离 Windows \\?\ 路径。
Node.js / Python 的 FFI 运行时初始化可失败（KRN-9）。 TASK_ADMISSION_AT_CAPACITY 在各 SDK 上映射一致。
Linux arm64 Python Wheel 使用 manylinux_2_39_aarch64（glibc 2.39+）； Linux x86_64 仍为 manylinux_2_28。

早期 v8.2.0 新增内容

steer 会在活动 Run 的下一个安全点加入更新指令；interrupt 会协作式停止 Provider、工具、工作流和委派任务。幂等回执与可选的预期 Turn 字段可以拒绝重复或过期的界面操作。
pre_run_control 可以门控控制请求，post_run_control 观察每次持久回执变化； run_control_applied 会进入共用事件协议与持久 Run 历史。
默认提示词现在由精简执行循环、运行时权威契约、仓库工具 schema 和安全边界分层组成。文件、工具输出与网页内容都按不可信数据处理；完成声明必须有证据，但提示词不会取代宿主的权限、确认或沙箱。
发布资格测试使用配置中的两个 DeepSeek 模型，真实覆盖工具与 Hook 参数改写、长程编码、SubAgents、Skills、PTC、可重放动态工作流，以及在线 steer/interrupt。
动态工作流的私有 program 实现步骤不再重复请求权限，脚本中的实际工具仍完整受治理。QuickJS ctx.readFile() 现在返回文件文本；ctx.read() 继续保留带行号的工具结果，供审计型脚本使用。

早期 v8.1 新增内容

web_search 使用 a3s-search v3.1.0。Google、Baidu、Bing 和 Brave 的浏览器引擎默认使用 Moli；Chrome/Chromium 与 Lightpanda 仍可显式选择。首次使用按 sidecar、经过校验的用户缓存、系统可执行文件、带 Digest 的 HTTPS 下载顺序发现。
Moli 安装采用原子暂存、Receipt 和跨进程锁，默认位置为 ~/.cache/a3s-code/moli（也可设置 A3S_CODE_MOLI_CACHE_DIR）。第二个 A3S Code 进程会等待首次安装并复用同一个可执行文件。若宿主必须禁止网络，设置 auto_download_moli = false，缺少运行时时会 fail-closed。
Rust、Node.js、Python 和 Go 都公开相同的 sdk_capabilities 清单、状态图操作、 Moli 诊断和类型化搜索配置。使用清单做能力发现，不要解析包内文件来猜测能力。
Node 原生平台包和 Python Wheel 都包含对应目标的 Moli sidecar 及来源元数据。 Linux musl 包会明确写入 MOLI_UNAVAILABLE，因为上游 Moli 没有发布 musl 二进制；这类主机应提供系统 Moli 或选择其他后端。

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/v9。

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 中的 Moli 层、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/v9

v8.5.1 的 Python 包通过每个平台一个 cp310-abi3 Wheel 支持 CPython 3.10 至 3.14。Intel Mac 使用 macosx_12_0_x86_64 Wheel，最低需要 macOS 12。请参阅 Python Wheel 平台了解 Bootstrap 流程，以及 No module named pip 的修复命令。

配置

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"

search {
  headless {
    backend = "moli"
    auto_download_moli = true
    max_tabs = 4
  }
}

auto_parallel = false 只关闭自动并行子智能体扇出。手动 task 调用和 SDK session.tasks(...) 扇出仍然可用，除非你单独关闭手动委派。

SDK 包会优先选择随包提供的 Moli sidecar。源码构建或精简 Core 可以设置 A3S_CODE_MOLI_EXECUTABLE 指向已校验的可执行文件；否则首次搜索会把固定版本下载到共享缓存。本地 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 一起出现在各通用章节中。
会话介绍创建、流式输出、运行状态、保存、恢复和取消。
工具介绍直接调用、错误类型、结构化输出和 QuickJS Program。
安全、Hook 与验证介绍执行前、执行中和执行后的检查。
工作区检索介绍显式语义开关、切块、生命周期、质量指标和 CPU-only 安全默认值。
任务与编排介绍子 Agent 和固定工作流。
Memory 与持久化介绍跨会话信息和任务恢复。
文件系统约定覆盖 AGENTS.md、ACL、Skill 与 .a3s/agents/ worker。
API 契约列出经过集成测试的 Node.js API。

#A3S Code

#设计规则

#先选使用方式

#主要能力

#v9.0.0 新增内容

#同属 v9.0.0（曾以 v8.7.0 打 tag，从未发布）

#v8.6.0 新增内容

#v8.5.6 新增内容

#v8.5.5 新增内容

#早期 v8.4.0 新增内容

#早期 v8.3.0 新增内容

#早期 v8.2.0 新增内容

#早期 v8.1 新增内容

#v7.0 的历史新增内容

#安装

#配置

#使用 TUI

#使用 SDK

#接着看

A3S Code

设计规则

先选使用方式

主要能力

v9.0.0 新增内容

同属 v9.0.0（曾以 v8.7.0 打 tag，从未发布）

v8.6.0 新增内容

v8.5.6 新增内容

v8.5.5 新增内容

早期 v8.4.0 新增内容

早期 v8.3.0 新增内容

早期 v8.2.0 新增内容

早期 v8.1 新增内容

v7.0 的历史新增内容

安装

配置

使用 TUI

使用 SDK

接着看