A3S Code
  • 简体中文
  • v8.3.0

      • A3S Code

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

      8.3.0 强化耐久性与信任内核：可协商的 Session Store 保证、工具结果信任标签、 工作区来源快照、可失败的 SDK 运行时初始化，以及 Node.js / Python / Go 上的宿主 不可变内容、Checkpoint 导出与能力批处理钩子。持久 BM25 检索与 Windows 原生 索引路径已通过发布资格矩阵验证。

      想直接在终端里使用，安装 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 Flow为 DynamicWorkflowRuntime 保存和恢复流程A3S-Lab/Flow

      主要能力

      领域可以做什么
      Agent 会话通过异步 SessionBuilder 创建绑定到 Workspace 的 AgentSession；支持 send、run、stream、steer、interrupt、取消、保存、恢复和清理。同一会话发生并发冲突时会立即报错。
      终端界面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 和输出清理都会在执行过程中生效。
      WorkspaceWorkspace 后端 支持本地文件、应用提供的 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。

      v8.3.0 新增内容

      • Session Store 耐久性可协商（KRN-6）。内置 memory / file 适配器会精确声明聚合 CAS、append-only WAL、写者租约 fencing、可选 AES-256-GCM 静态加密、提交 watch， 以及引用感知的 Artifact GC。宿主必须先检查 SessionStoreCapabilities 再依赖 对应语义。
      • 每个工具结果都带有类型化信任标签（KRN-5）：trusted、workspace data 或 external。Run 绑定的模型调用会在预算 / 证据 / 生成阶段前先准入提示词信任； 外部结果在完成脱敏审查前 fail-closed。Rust 与四种 SDK 都暴露无密钥的 model_middleware_health 计数器。
      • 工作区检索把结果绑定到可防篡改的来源快照（KRN-4）。派生索引重建后结果仍有效； 清单、资格、目录或内容变化会使旧结果失效。
      • Node.js / Python 的 FFI 运行时初始化可失败（KRN-9）：Tokio spawn / import 失败 会返回稳定错误，而不再直接 panic。TASK_ADMISSION_AT_CAPACITY 在各 SDK 上映射 一致。
      • Node.js、Python、Go 暴露宿主侧不可变内容适配器、实时 Checkpoint 导出 sink、 仅 Skill 的能力批处理，以及投影后的中间件健康信息。sdk/evaluation/ 下的共享 fixture 记录了线协议契约。
      • 主会话提示词与显式能力边界对齐：Auto / 预分析不再静默切换 Explore / Plan 等 专用提示词；宿主选择的 AgentStyle 会安装匹配的权限与工具契约。
      • 持久 BM25 / zvec 索引在 Windows 与 Linux 上通过发布资格验证，包括在原生打开前 剥离 Windows \\?\ 路径，并让持久协调器在初始 Absent 状态后继续存活。
      • Linux arm64 Python Wheel 使用 manylinux_2_39_aarch64（glibc 2.39+）以匹配 捆绑的 zvec 运行时；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/v8。

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

      v8.3.0 的 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 标识提交到仓库；提交只通过环境变量解析凭据的模板。

      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 一起出现在各通用章节中。
      • 文件系统优先 介绍 AGENTS.md、ACL、AgentDir、Skill、工具和定时任务。
      • API 契约 列出经过集成测试的 Node.js API。
      • 会话 介绍创建、流式输出、运行状态、保存、恢复和取消。
      • 工具 介绍直接调用、错误类型、结构化输出和 QuickJS Program。
      • 工作区检索介绍显式语义开关、切块、生命周期、质量指标和 CPU-only 安全默认值。
      • 任务 与 编排 介绍子 Agent 和固定工作流。
      • 安全、Hook 与 验证 介绍执行前、执行中和执行后的检查。
      • Memory 与 持久化 介绍跨会话信息和任务恢复。