From f58c3e1cca86ae499b614a7cc44e4d83e6ca91ec Mon Sep 17 00:00:00 2001 From: roylin Date: Tue, 8 Sep 2026 21:01:13 +0800 Subject: [PATCH] docs: rewrite landing and README copy in plain language Drop the feature-laundry-list tone on the home page and release notes so the product reads like engineer docs, not generated marketing. Co-authored-by: Cursor --- README.md | 34 +++++------- README.zh-CN.md | 31 +++++------ website/docs/v8.5.1/en/guide/index.mdx | 32 +++++------ website/docs/v8.5.1/zh/guide/index.mdx | 25 ++++----- website/theme/components/home-copy.ts | 77 +++++++++++++------------- 5 files changed, 92 insertions(+), 107 deletions(-) diff --git a/README.md b/README.md index 2a30ea57..a6b6210f 100644 --- a/README.md +++ b/README.md @@ -17,12 +17,10 @@ MIT license

-**A3S Code** is an async Rust runtime for building governed coding agents. The -library default is a **thin coding harness** (`local-code`): agent loop, -workspace tools, policy, events, and bundled lexical retrieval. Advanced -evaluation, server, and headless search stay opt-in. Side effects, evidence, -and recovery sit behind explicit contracts — from Rust, Node.js, Python, Go, or -`a3s code`. +**A3S Code** is an async Rust runtime for coding agents. By default it ships a +small harness (`local-code`): the agent loop, workspace tools, policy, events, +and lexical search. Heavier pieces (evaluation, server, headless search) stay +opt-in. Use it from Rust, Node.js, Python, Go, or `a3s code`.

Start · @@ -36,24 +34,22 @@ and recovery sit behind explicit contracts — from Rust, Node.js, Python, Go, o ## What's new in 8.5 -Workspace search planes stay separate; session-store reopen recovers under flock: - -- **`grep` candidate pruning (CODE-G1).** Default `local-code` builds an - in-tree trigram filter under `.a3s-code/grep-trigram` so literal needles open - fewer files before the exact regex scan. Non-literals and index failures fail - open. Exact matches remain owned by Code — this path never opens durable zvec - FTS (`mode: "bm25"` stays the ranked plane). -- **Session-store WAL flock (8.5.1).** Concurrent writers re-read the durable - max sequence under a cross-process flock; corrupt WALs can be quarantined so - hosts continue from durable snapshots. +- **Faster `grep` (CODE-G1).** For literal searches, `local-code` builds a small + trigram cache under `.a3s-code/grep-trigram` so fewer files need a full regex + pass. If the cache misses or the pattern is not literal, it just falls back. + Exact match still comes from Code's own `grep` — this never opens the durable + zvec FTS index (`bm25` stays for ranked search). +- **Safer session reopen (8.5.1).** Writers take a cross-process flock, re-read + the durable sequence, and can quarantine a bad WAL instead of minting + colliding IDs. Docs: [a3s-lab.github.io/Code](https://a3s-lab.github.io/Code/) (`v8.5.1`). ### Earlier lines -- **8.4** — thin `local-code` defaults, unified `task` fan-out, Active-only - durable memory, `update_plan`, SDK capabilities v2. -- **8.3** — negotiable session-store durability, typed tool-result trust, +- **8.4** — smaller `local-code` defaults, one `task` path for fan-out, + Active-only durable memory, `update_plan`, SDK capabilities v2. +- **8.3** — session-store durability options, typed tool-result trust, workspace source snapshots, fallible FFI init, host checkpoint hooks. - **8.0+** — run-owned spacetime, generation-exact capabilities, portable checkpoints, convergent workflows. Full history: diff --git a/README.zh-CN.md b/README.zh-CN.md index c79861eb..43509ca5 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -17,10 +17,10 @@ MIT license

-**A3S Code** 是用于构建受治理编码 Agent 的异步 Rust 运行时。库的默认配置是 -**变薄的编码 Harness**（`local-code`）：Agent 循环、工作区工具、策略、事件与 -捆绑词法检索。Advanced 评估、server 与无头搜索保持显式启用。副作用、证据与 -恢复都放在显式契约之后 — 可通过 Rust、Node.js、Python、Go，或 `a3s code` 使用。 +**A3S Code** 是做编码 Agent 的异步 Rust 运行时。默认是一套够用的小 harness +（`local-code`）：Agent 循环、工作区工具、策略、事件，以及词法搜索。评估、 +server、无头搜索这些更重的能力需要显式打开。可用 Rust、Node.js、Python、Go， +或直接跑 `a3s code`。

起步 · @@ -34,22 +34,20 @@ ## 8.5 有什么新内容 -工作区搜索平面保持分离；会话存储重开在 flock 下恢复： - -- **`grep` 候选裁剪（CODE-G1）。** 默认 `local-code` 在 - `.a3s-code/grep-trigram` 下构建进程内 trigram 过滤器，使字面量模式在精确 - 正则扫描前打开更少文件。非字面量与索引失败会失败开放。精确匹配仍由 Code - 拥有 — 该路径不会打开持久 zvec FTS（排序检索仍用 `mode: "bm25"`）。 -- **会话存储 WAL flock（8.5.1）。** 并发写者在跨进程 flock 下重读持久最大 - 序号；可隔离损坏的 WAL，使宿主从持久快照继续。 +- **更快的 `grep`（CODE-G1）。** 字面量搜索时，`local-code` 会在 + `.a3s-code/grep-trigram` 下建一个小的 trigram 缓存，先缩小文件范围再做精确 + 正则。缓存不可用或不是字面量时直接回退。精确匹配仍走 Code 自己的 `grep`， + 不会碰持久 zvec FTS（排序检索继续用 `bm25`）。 +- **会话重开更稳（8.5.1）。** 写者先拿跨进程 flock，再读持久序号；坏掉的 WAL + 可以隔离，避免并发写出冲突 ID。 文档：[a3s-lab.github.io/Code](https://a3s-lab.github.io/Code/)（`v8.5.1`）。 ### 更早的版本线 -- **8.4** — 变薄的 `local-code` 默认、统一 `task` 扇出、仅 Active 的 Durable +- **8.4** — 更小的 `local-code` 默认、统一用 `task` 做扇出、仅 Active 的 Durable Memory、`update_plan`、SDK capabilities v2。 -- **8.3** — 可协商会话存储耐久、类型化工具结果信任、工作区源快照、可失败 FFI +- **8.3** — 会话存储耐久选项、类型化工具结果信任、工作区源快照、可失败 FFI init、宿主 checkpoint 钩子。 - **8.0+** — Run 拥有的时空组合、generation-exact 能力、可移植检查点、收敛工作流。 完整历史见 [CHANGELOG.md](CHANGELOG.md)。Go 模块路径： @@ -69,9 +67,8 @@ cd /path/to/your/project a3s code ``` -终端产品流推理、工具活动、审批、任务 -进展和差异。使用 `a3s code resume` 恢复持续工作或 -`a3s code resume `。 +终端里会流式显示推理、工具、审批、任务进度和 diff。恢复会话用 +`a3s code resume` 或 `a3s code resume `。 ### 嵌入运行时 diff --git a/website/docs/v8.5.1/en/guide/index.mdx b/website/docs/v8.5.1/en/guide/index.mdx index fb05f418..74010081 100644 --- a/website/docs/v8.5.1/en/guide/index.mdx +++ b/website/docs/v8.5.1/en/guide/index.mdx @@ -7,23 +7,20 @@ import { Tab, Tabs } from '@rspress/core/theme'; # A3S Code -A3S Code is the Rust runtime behind the `a3s code` terminal application. You can -also embed it in an IDE, runner, service, or desktop application. It handles the -agent loop, context, tool calls, permission checks, child tasks, asynchronous -Workspace retrieval, durable evidence, and session recovery. +A3S Code is the Rust runtime behind `a3s code`. Embed it in an IDE, runner, +service, or desktop app when you need the same loop outside the terminal: tools, +permissions, child tasks, workspace search, and session save/resume. -Version 8.5.1 keeps the thin `local-code` harness and separates workspace search -planes: exact `grep` (with optional in-tree trigram candidate pruning) never -opens durable zvec FTS, while `bm25` remains the ranked lexical path. Session -stores recover corrupt WALs under a cross-process flock so concurrent writers -cannot mint colliding sequences. +In 8.5.1, literal `grep` can use a small trigram cache so it opens fewer files +first; ranked search still goes through `bm25` / zvec. Session stores take a +flock on reopen so a bad WAL does not mint colliding sequence numbers. ## Design rules | Rule | Meaning | | --------------------------- | ------------------------------------------------------------------------------------------------------ | | Thin default | Core `default` = `local-code`. Advanced evaluation, server, and headless search are explicit features. | -| Grep ≠ zvec | Exact `grep` is match authority; trigram pruning is fail-open only. Ranked retrieval uses `bm25`. | +| Grep ≠ zvec | Exact `grep` owns matches; trigram pruning only narrows candidates and fails open. Use `bm25` to rank. | | One delegation path | Multi-item fan-out uses `task` / `session.tasks`. Do not restore `parallel_task`. | | Active-only memory | Durable serving is `active_recall`. Candidate shadow mode is refused. | | Evidence before Gate claims | Incomplete or retention-gapped evidence cannot satisfy Gate evaluation. | @@ -65,14 +62,13 @@ same events, so every UI does not need its own agent loop. ## What is new in v8.5.1 -- Default `local-code` **trigram pruning for `grep`** (`CODE-G1`): literal - needles build a fail-open candidate cache under `.a3s-code/grep-trigram` - without opening durable zvec FTS. Exact regex matching stays in Code. -- **Session-store WAL flock recovery**: concurrent writers re-read the durable - max sequence under a cross-process flock; hosts can quarantine a corrupt WAL - and continue from durable snapshots. -- Carries forward the 8.4 thin harness (Active-only memory, unified `task`, - `update_plan`, SDK capabilities v2) and the 8.3 durability/trust kernel. +- **Faster literal `grep` (`CODE-G1`).** Builds a fail-open trigram cache under + `.a3s-code/grep-trigram`. Exact regex still runs in Code; durable zvec FTS is + not opened on this path. +- **Session-store WAL flock.** Concurrent writers re-read the durable max + sequence under flock; a corrupt WAL can be quarantined so the host keeps + going from snapshots. +- Still includes the 8.4 smaller harness and the 8.3 durability/trust work. ## Earlier v8.4.0 additions diff --git a/website/docs/v8.5.1/zh/guide/index.mdx b/website/docs/v8.5.1/zh/guide/index.mdx index 2777bf5b..c9fe0130 100644 --- a/website/docs/v8.5.1/zh/guide/index.mdx +++ b/website/docs/v8.5.1/zh/guide/index.mdx @@ -7,20 +7,19 @@ import { Tab, Tabs } from '@rspress/core/theme'; # A3S Code -A3S Code 是 `a3s code` 终端应用背后的 Rust Runtime，也可以单独接入 IDE、 -Runner 或服务端。它负责 Agent Loop、上下文、工具调用、权限检查、子任务、 -异步 Workspace 检索、持久证据，以及任务的保存和恢复。 +A3S Code 是 `a3s code` 背后的 Rust Runtime。也可以嵌进 IDE、Runner、服务端或 +桌面应用，复用同一套 Agent 循环：工具、权限、子任务、工作区搜索，以及会话的 +保存和恢复。 -8.5.1 保持变薄的 `local-code` Harness，并分离工作区搜索平面：精确 `grep` -（可选进程内 trigram 候选裁剪）不会打开持久 zvec FTS，而 `bm25` 仍是排序词法 -路径。会话存储在跨进程 flock 下恢复损坏的 WAL，避免并发写者铸造冲突序号。 +8.5.1 里，字面量 `grep` 可以先用小的 trigram 缓存缩小文件范围；排序检索仍走 +`bm25` / zvec。会话存储重开时会拿 flock，坏 WAL 不会再写出冲突序号。 ## 设计规则 | 规则 | 含义 | | ---------------- | -------------------------------------------------------------------------- | | 默认变薄 | Core `default` = `local-code`。Advanced 评估、server、无头搜索需显式开启。 | -| Grep ≠ zvec | 精确 `grep` 是匹配权威；trigram 裁剪仅失败开放。排序检索使用 `bm25`。 | +| Grep ≠ zvec | 精确 `grep` 负责匹配；trigram 只缩小候选，失败就回退。排序检索用 `bm25`。 | | 单一委派路径 | 多条目扇出使用 `task` / `session.tasks`。不要恢复 `parallel_task`。 | | 仅 Active 记忆 | Durable 服务路径为 `active_recall`。拒绝 Candidate shadow。 | | Gate 先要证据 | 证据不完整或存在 retention 缺口时，Gate 不可宣称已完成评估。 | @@ -61,13 +60,11 @@ Runner 或服务端。它负责 Agent Loop、上下文、工具调用、权限 ## v8.5.1 新增内容 -- 默认 `local-code` 的 **`grep` trigram 裁剪**（`CODE-G1`）：字面量模式在 - `.a3s-code/grep-trigram` 下构建失败开放的候选缓存，且不会打开持久 zvec FTS。 - 精确正则匹配仍由 Code 拥有。 -- **会话存储 WAL flock 恢复**：并发写者在跨进程 flock 下重读持久最大序号；宿主 - 可隔离损坏的 WAL，并从持久快照继续。 -- 延续 8.4 变薄 Harness（仅 Active 记忆、统一 `task`、`update_plan`、SDK - capabilities v2）以及 8.3 耐久/信任内核。 +- **更快的字面量 `grep`（`CODE-G1`）。** 在 `.a3s-code/grep-trigram` 下建失败可 + 回退的 trigram 缓存。精确正则仍在 Code 里跑，这条路径不打开持久 zvec FTS。 +- **会话存储 WAL flock。** 并发写者在 flock 下重读持久最大序号；坏 WAL 可以隔离， + 宿主从快照继续。 +- 仍包含 8.4 的小 harness 默认，以及 8.3 的耐久 / 信任改动。 ## 早期 v8.4.0 新增内容 diff --git a/website/theme/components/home-copy.ts b/website/theme/components/home-copy.ts index 60de8069..ef1cadda 100644 --- a/website/theme/components/home-copy.ts +++ b/website/theme/components/home-copy.ts @@ -1,10 +1,10 @@ export const copy = { zh: { - eyebrow: 'OPEN SOURCE · EMBEDDABLE AGENT RUNTIME', + eyebrow: '开源 · 可嵌入的 Agent Runtime', titleLead: '把 A3S Code', titleAccent: '接进现有产品', subtitle: - 'A3S Code 8.5 是变薄的受治理编码 Harness：默认 local-code、统一 task 扇出、Active-only 记忆、可协商耐久与信任边界、精确 grep 与排序检索分离（可选 trigram 裁剪）、异步工作区检索与事件恢复。可直接运行 a3s code，或通过 Rust / Node.js / Python / Go SDK 嵌入产品。', + '跑编码 Agent 时，工具调用先过权限再执行；会话能保存、能恢复。默认配置够用，复杂能力按需打开。终端直接跑 a3s code，或用 Rust / Node.js / Python / Go SDK 嵌进你的产品。', docs: '开始使用', github: '查看 GitHub', copy: '复制', @@ -19,31 +19,31 @@ export const copy = { guard: '参数 → 权限 → 确认 → 预算 → 沙箱', evidence: 'Run · Trace · Artifact · Snapshot', record: '执行记录', - surfacesLabel: '五种接入方式，同一套 Runtime', + surfacesLabel: '五种入口，同一套 Runtime', whyEyebrow: 'WHY A3S CODE', - whyTitle: '工具执行之前，先检查参数、权限和确认状态', + whyTitle: '模型想动文件或跑 Shell 时，先过你的规则', whyBody: - '模型给出的工具调用不会直接落到文件系统或 Shell。Runtime 先完成检查，再把执行事件和结果交给应用。', + '工具参数不会直接落地。Runtime 先做参数、权限和确认检查，再执行，并把过程事件回给你的应用。', architectureEyebrow: 'HOW IT RUNS', - architectureTitle: '用 Python 走完一次执行', + architectureTitle: '用 Python 看完一次完整调用', architectureBody: - '示例使用仓库中实际提供的 a3s_code API。滚动或点击步骤，代码会逐步加入 Session、上下文限制、权限、事件流和持久化。', + '下面的例子就是仓库里的 a3s_code API。点步骤，看 Session、权限、事件流和持久化是怎么加上去的。', architectureAlt: - 'A3S Code 一次执行的交互流程图，展示任务规划、进度追踪、并行子智能体、报告制品和 RemoteUI 渐进式界面。', + '一次 A3S Code 执行的示意：规划、进度、子 Agent、报告和 RemoteUI。', capabilitiesEyebrow: 'WHAT YOU GET', - capabilitiesTitle: 'Runtime 提供的五类能力', + capabilitiesTitle: 'Runtime 本身提供什么', capabilitiesBody: - '基线 Harness 默认不含 Advanced 评估、server 与无头搜索；语义检索由宿主主动开启。基础搜索不依赖 Embedding、Rerank 或向量数据库。', + '默认不带 Advanced 评估、server 和无头搜索。基础搜索不需要 Embedding 或向量库；语义检索由你的应用自己打开。', surfacesEyebrow: 'USE IT YOUR WAY', - surfacesTitle: '直接运行 CLI，或使用四种 SDK', + surfacesTitle: '终端直接跑，或嵌进四种 SDK', surfacesBody: - '终端版用于直接操作项目；Rust crate、Node.js 包、Python 包和 Go module 用于 IDE、Runner、服务端或自有界面。', + '在仓库里用 a3s code；要做 IDE、Runner 或自有界面，用 Rust / Node.js / Python / Go。', boundariesEyebrow: 'WHAT STAYS YOURS', - boundariesTitle: 'Runtime 负责执行；应用负责账号、凭据和界面', + boundariesTitle: 'Runtime 管执行；账号和界面归你', boundaryItems: [ - 'A3S Code Core 提供 Agent Runtime，不提供托管服务，也不规定界面应该长什么样。', - 'a3s code 的终端界面由独立的 A3S CLI 提供。', - '账号、凭据、部署方式，以及哪些应用工具可以直接调用，仍由你的应用决定。', + 'Core 只提供 Agent Runtime，不是托管服务，也不规定 UI。', + '终端界面来自独立的 A3S CLI。', + '账号、凭据、部署，以及哪些业务工具能直接调，都由你的应用决定。', ], boundaryLink: '查看架构说明', boundaryCoreLabel: 'A3S CODE', @@ -103,20 +103,20 @@ export const copy = { tutorialLayers: '当前负责的层', tutorialScroll: '继续向下', ctaEyebrow: 'TRY IT', - ctaTitle: '从一个只读任务开始', + ctaTitle: '先在已有仓库里跑一次', ctaBody: - '安装 a3s code 后，在已有仓库里执行一次检查；需要嵌入时再选择 Rust、Node.js、Python 或 Go SDK。', + '装好 a3s code，找个项目试一下。要嵌进产品时，再选 Rust、Node.js、Python 或 Go。', ctaPrimary: '查看快速开始', ctaSecondary: '查看 API', footer: - 'MIT 开源 · Rust 编写 · 支持 Terminal / Rust / Node.js / Python / Go', + 'MIT · 用 Rust 写的 · Terminal / Rust / Node.js / Python / Go', }, en: { - eyebrow: 'OPEN SOURCE · EMBEDDABLE AGENT RUNTIME', + eyebrow: 'Open source · embeddable agent runtime', titleLead: 'Add A3S Code', titleAccent: 'to an existing product', subtitle: - 'A3S Code 8.5 is a thin governed coding harness: local-code defaults, unified task fan-out, Active-only memory, negotiable durability and trust boundaries, exact grep separated from ranked retrieval (optional trigram pruning), asynchronous workspace retrieval, and recoverable events. Run a3s code or embed the Rust, Node.js, Python, or Go SDK.', + 'A coding-agent runtime that checks tools before they run, keeps sessions recoverable, and stays small by default. Run a3s code in a repo, or embed the Rust, Node.js, Python, or Go SDK.', docs: 'Get started', github: 'View on GitHub', copy: 'Copy', @@ -131,31 +131,31 @@ export const copy = { guard: 'arguments → permission → approval → budget → sandbox', evidence: 'Run · Trace · Artifact · Snapshot', record: 'run record', - surfacesLabel: 'Five ways in, one runtime', + surfacesLabel: 'Five entry points, one runtime', whyEyebrow: 'WHY A3S CODE', - whyTitle: 'Check arguments, permissions, and approvals before execution', + whyTitle: 'Tool calls hit your rules before the filesystem or shell', whyBody: - 'Model tool calls do not go straight to the filesystem or shell. The runtime completes its checks first, then sends execution events and results to the application.', + 'The model cannot touch files or run commands until the runtime checks arguments, permissions, and approvals. Then it executes and streams events back to your app.', architectureEyebrow: 'HOW IT RUNS', - architectureTitle: 'Follow one complete run in Python', + architectureTitle: 'Walk through one Python run', architectureBody: - 'The example uses the actual a3s_code API in this repository. Scroll or select a step to add the Session, context limits, policy, event stream, and persistence.', + 'This uses the real a3s_code API from the repo. Click the steps to see Session, policy, events, and persistence get added.', architectureAlt: - 'An interactive A3S Code run showing task planning, progress tracking, parallel subagents, report artifacts, and a progressive RemoteUI view.', + 'A sample A3S Code run: planning, progress, subagents, a report, and RemoteUI.', capabilitiesEyebrow: 'WHAT YOU GET', - capabilitiesTitle: 'Five parts of the runtime', + capabilitiesTitle: 'What the runtime ships with', capabilitiesBody: - 'The baseline harness omits Advanced evaluation, server, and headless search by default. The host opts into semantics; baseline search needs no embedding model, reranker, or vector database.', + 'Advanced evaluation, server, and headless search stay off unless you turn them on. Basic search does not need embeddings or a vector DB.', surfacesEyebrow: 'USE IT YOUR WAY', - surfacesTitle: 'Run the CLI or use one of four SDKs', + surfacesTitle: 'CLI in a repo, or four SDKs in your product', surfacesBody: - 'Use the terminal app directly in a repository. Use the Rust crate, Node.js package, Python package, or Go module in an IDE, runner, server, or custom interface.', + 'Run a3s code locally. For an IDE, runner, or your own UI, pick Rust, Node.js, Python, or Go.', boundariesEyebrow: 'WHAT STAYS YOURS', - boundariesTitle: 'The runtime executes; the app owns accounts and access', + boundariesTitle: 'We run the agent; you own accounts and UI', boundaryItems: [ - 'A3S Code Core provides the agent runtime. It is not a hosted service and does not dictate your UI.', - 'The a3s code terminal interface comes from the separate A3S CLI.', - 'Accounts, credentials, deployment, and direct access to application tools remain under your control.', + 'Core is an agent runtime, not a hosted service, and it does not dictate your UI.', + 'The terminal UI comes from the separate A3S CLI.', + 'Accounts, credentials, deployment, and which app tools are callable stay yours.', ], boundaryLink: 'Read the architecture guide', boundaryCoreLabel: 'A3S CODE', @@ -215,13 +215,12 @@ export const copy = { tutorialLayers: 'ACTIVE LAYER', tutorialScroll: 'KEEP SCROLLING', ctaEyebrow: 'TRY IT', - ctaTitle: 'Start with a read-only task', + ctaTitle: 'Try it in a repo you already have', ctaBody: - 'Install a3s code and run one inspection in an existing repository. Choose the Rust, Node.js, Python, or Go SDK when you are ready to embed it.', + 'Install a3s code and run it once. Embed later with Rust, Node.js, Python, or Go if you need to.', ctaPrimary: 'Open the quick start', ctaSecondary: 'Open the API reference', - footer: - 'MIT licensed · Built in Rust · Terminal / Rust / Node.js / Python / Go', + footer: 'MIT · built in Rust · Terminal / Rust / Node.js / Python / Go', }, };