From b8cf5bf1d4b463fdba600bc314034fd20caa2527 Mon Sep 17 00:00:00 2001 From: Roy Lin <19165061825@163.com> Date: Mon, 27 Jul 2026 22:25:53 +0800 Subject: [PATCH] docs: add interactive playgrounds and refine site copy --- website/docs/public/social-card.svg | 20 +- website/docs/v6/en/_nav.json | 7 +- website/docs/v6/en/api/index.mdx | 40 +- website/docs/v6/en/guide/_meta.json | 7 + website/docs/v6/en/guide/index.mdx | 140 +- website/docs/v6/en/guide/persistence.mdx | 4 + .../docs/v6/en/guide/playground/_meta.json | 1 + website/docs/v6/en/guide/playground/index.mdx | 40 + website/docs/v6/en/guide/playground/tui.mdx | 47 + website/docs/v6/en/guide/playground/web.mdx | 41 + website/docs/v6/en/guide/security.mdx | 4 + website/docs/v6/en/guide/sessions.mdx | 4 + website/docs/v6/en/guide/tasks.mdx | 4 + website/docs/v6/en/guide/tools.mdx | 4 + website/docs/v6/en/guide/tui.mdx | 5 + website/docs/v6/en/guide/verification.mdx | 4 + website/docs/v6/en/index.mdx | 2 +- website/docs/v6/zh/_nav.json | 7 +- website/docs/v6/zh/api/index.mdx | 35 +- website/docs/v6/zh/guide/_meta.json | 7 + website/docs/v6/zh/guide/index.mdx | 117 +- website/docs/v6/zh/guide/persistence.mdx | 3 + .../docs/v6/zh/guide/playground/_meta.json | 1 + website/docs/v6/zh/guide/playground/index.mdx | 34 + website/docs/v6/zh/guide/playground/tui.mdx | 44 + website/docs/v6/zh/guide/playground/web.mdx | 38 + website/docs/v6/zh/guide/security.mdx | 3 + website/docs/v6/zh/guide/sessions.mdx | 3 + website/docs/v6/zh/guide/tasks.mdx | 3 + website/docs/v6/zh/guide/tools.mdx | 4 + website/docs/v6/zh/guide/tui.mdx | 5 + website/docs/v6/zh/guide/verification.mdx | 3 + website/docs/v6/zh/index.mdx | 2 +- website/rspress.config.ts | 13 +- .../theme/components/AgentBuildingBlocks.tsx | 339 ++++ website/theme/components/HomeLayout.tsx | 330 +-- website/theme/components/TuiPlayground.tsx | 505 +++++ website/theme/components/WebPlayground.tsx | 474 +++++ website/theme/index.tsx | 1 + website/theme/playgrounds.css | 1791 +++++++++++++++++ 40 files changed, 3800 insertions(+), 336 deletions(-) create mode 100644 website/docs/v6/en/guide/playground/_meta.json create mode 100644 website/docs/v6/en/guide/playground/index.mdx create mode 100644 website/docs/v6/en/guide/playground/tui.mdx create mode 100644 website/docs/v6/en/guide/playground/web.mdx create mode 100644 website/docs/v6/zh/guide/playground/_meta.json create mode 100644 website/docs/v6/zh/guide/playground/index.mdx create mode 100644 website/docs/v6/zh/guide/playground/tui.mdx create mode 100644 website/docs/v6/zh/guide/playground/web.mdx create mode 100644 website/theme/components/AgentBuildingBlocks.tsx create mode 100644 website/theme/components/TuiPlayground.tsx create mode 100644 website/theme/components/WebPlayground.tsx create mode 100644 website/theme/playgrounds.css diff --git a/website/docs/public/social-card.svg b/website/docs/public/social-card.svg index b3f1290..9188031 100644 --- a/website/docs/public/social-card.svg +++ b/website/docs/public/social-card.svg @@ -1,6 +1,6 @@ - A3S Code — governed coding-agent runtime - A3S Code keeps tools, policy, events, and durable evidence explicit. + A3S Code — Rust runtime for coding agents + Tool calls, approval, event streaming, and recovery for Rust, Node.js, and Python. @@ -27,12 +27,12 @@ - Build governed - coding agents. + Add a coding agent + to your product. - Tools, policy, events, and durable evidence - stay behind explicit runtime contracts. + Tool calls, approval, events, and recovery + for Rust, Node.js, and Python. @@ -40,7 +40,7 @@ - PRODUCT SURFACES + TERMINAL + SDKs @@ -48,17 +48,17 @@ - GOVERNANCE + PERMISSIONS + TOOLS - EVENTS + EVIDENCE + EVENTS + RECOVERY - ASYNC RUST RUNTIME + RUST AGENT RUNTIME TERMINAL RUST NODE.JS diff --git a/website/docs/v6/en/_nav.json b/website/docs/v6/en/_nav.json index 4ec4f14..b81685f 100644 --- a/website/docs/v6/en/_nav.json +++ b/website/docs/v6/en/_nav.json @@ -2,7 +2,12 @@ { "text": "Docs", "link": "/guide/", - "activeMatch": "^/guide/" + "activeMatch": "^/guide/(?!examples/|playground/)" + }, + { + "text": "Playground", + "link": "/guide/playground/", + "activeMatch": "^/guide/playground/" }, { "text": "Examples", diff --git a/website/docs/v6/en/api/index.mdx b/website/docs/v6/en/api/index.mdx index 5bf8a80..f740aca 100644 --- a/website/docs/v6/en/api/index.mdx +++ b/website/docs/v6/en/api/index.mdx @@ -1,21 +1,21 @@ --- -title: APIs and packages -description: Entry points for the A3S Code Rust, Node.js, and Python APIs and their shared runtime contract. +title: SDKs and APIs +description: Install the A3S Code Rust, Node.js, and Python SDKs and find their API documentation. --- -# APIs and packages +# SDKs and APIs -The four A3S Code product surfaces share one runtime kernel while serving -different integration needs. Treat each registry and +A3S Code provides Rust, Node.js, and Python SDKs. Install the `a3s` CLI when you +want the terminal application. Treat each registry and [GitHub Releases](https://github.com/A3S-Lab/Code/releases) as the source of truth for package versions and release status. -| Surface | Package or command | API entry | Use it for | -| -------- | ------------------ | -------------------------------------------------- | --------------------------------------------- | -| Terminal | `a3s code` | [A3S CLI](https://github.com/A3S-Lab/CLI) | Run the interactive coding product | -| Rust | `a3s-code-core` | [docs.rs](https://docs.rs/a3s-code-core) | Complete runtime API and extension traits | -| Node.js | `@a3s-lab/code` | [npm](https://www.npmjs.com/package/@a3s-lab/code) | Native N-API bindings and async event streams | -| Python | `a3s-code` | [PyPI](https://pypi.org/project/a3s-code/) | Synchronous and asynchronous PyO3 APIs | +| Entry | Package or command | Documentation | Use it for | +| -------- | ------------------ | -------------------------------------------------- | -------------------------------------------------- | +| Terminal | `a3s code` | [A3S CLI](https://github.com/A3S-Lab/CLI) | Run a coding agent directly in your terminal | +| Rust | `a3s-code-core` | [docs.rs](https://docs.rs/a3s-code-core) | Use the complete runtime API or extension traits | +| Node.js | `@a3s-lab/code` | [npm](https://www.npmjs.com/package/@a3s-lab/code) | Subscribe to async events in a Node.js application | +| Python | `a3s-code` | [PyPI](https://pypi.org/project/a3s-code/) | Use synchronous or asynchronous Python APIs | ## Install @@ -30,15 +30,19 @@ npm install @a3s-lab/code python -m pip install a3s-code ``` -## Cross-language contract +## What the SDKs share -Versioned events, durable snapshots, and explicit lifecycle methods form the -cross-language product boundary. Start with the -[API contract](/guide/api-contract), then continue to +All three SDKs use the same session lifecycle, event format, and snapshots. A UI +can subscribe to the same `AgentEvent` / `EventEnvelopeV1` stream and resume +saved work by session ID. + +Start with the [API contract](/guide/api-contract), then continue to [sessions](/guide/sessions), [tools](/guide/tools), [workspace backends](/guide/workspace-backends), and [persistence](/guide/persistence). -Replaceable host extension boundaries include `LlmClient`, `ContextProvider`, -`MemoryStore`, `SessionStore`, workspace services, tools, permissions, -confirmations, hooks, security providers, MCP transports, and graph stores. +When connecting your own infrastructure, you can replace `LlmClient`, +`ContextProvider`, `MemoryStore`, `SessionStore`, Workspace services, tools, +permission confirmation, hooks, MCP transports, and graph stores. To see how +events reach a UI first, open the +[A3S TUI and Web Playground](/guide/playground/). diff --git a/website/docs/v6/en/guide/_meta.json b/website/docs/v6/en/guide/_meta.json index aa7ef90..903e8c3 100644 --- a/website/docs/v6/en/guide/_meta.json +++ b/website/docs/v6/en/guide/_meta.json @@ -1,6 +1,13 @@ [ "index", "tui", + { + "type": "dir", + "name": "playground", + "label": "Playground", + "collapsible": true, + "collapsed": false + }, { "type": "dir", "name": "examples", diff --git a/website/docs/v6/en/guide/index.mdx b/website/docs/v6/en/guide/index.mdx index 203ef64..54418ce 100644 --- a/website/docs/v6/en/guide/index.mdx +++ b/website/docs/v6/en/guide/index.mdx @@ -1,62 +1,59 @@ --- title: 'Overview' -description: 'Rust coding-agent runtime and the execution core behind the a3s code terminal workspace' +description: 'Install A3S Code, understand its main features, and choose an SDK' --- # A3S Code -A3S Code is the Rust runtime behind `a3s code`. It keeps coding-agent sessions -observable while one runtime kernel owns context assembly, governed provider -and tool invocation, delegation, dynamic workflow execution, workspace access, -memory, persistence, verification evidence, and run replay. - -`a3s-code-core` is the embeddable Rust runtime. `a3s code` is the ready terminal -workspace shipped by the [`a3s` CLI](https://github.com/A3S-Lab/Cli); it drives -A3S Code sessions and renders their event stream with the -[`a3s-tui`](https://github.com/A3S-Lab/TUI) framework. - -Install the CLI when you want the interactive product. Install the Rust crate -when you are building another host, runner, IDE bridge, or controlled product -surface around the same runtime. - -## Surfaces - -| Name | Use it for | Repository | -| --------------- | ----------------------------------------------------------------------------- | ----------------------------------------------- | -| `a3s-code-core` | Embedding coding-agent sessions through the Rust runtime API. | [A3S-Lab/Code](https://github.com/A3S-Lab/Code) | -| `a3s code` TUI | Running the ready terminal coding-agent workspace. | [A3S-Lab/Cli](https://github.com/A3S-Lab/Cli) | -| `a3s-tui` | Building terminal UI surfaces; it is the UI framework, not the agent runtime. | [A3S-Lab/TUI](https://github.com/A3S-Lab/TUI) | -| A3S Flow | Durable workflow engine used by `DynamicWorkflowRuntime`. | [A3S-Lab/Flow](https://github.com/A3S-Lab/Flow) | -| A3S monorepo | Product docs, release orchestration, submodule pins, and related crates. | [A3S-Lab/a3s](https://github.com/A3S-Lab/a3s) | - -## Capability Map - -| Area | Current capability | -| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Agent sessions | Async-first `SessionBuilder` construction produces workspace-bound `AgentSession` values. Transcript operations are fail-fast single-flight and expose `send`, `stream`, run state, cancellation, persistence, memory, verification, and lifecycle cleanup. | -| TUI | [`a3s code`](/guide/tui) streams runtime events into a terminal workspace with tool activity, approvals, memory, files, sessions, local assets, effort profiles, DynamicWorkflowRuntime, and trusted view controls. | -| Filesystem-first | [Filesystem-first](/guide/filesystem-first) organizes `AGENTS.md`, ACL config, `.a3s/agents/`, `skills/`, `tools/`, and `schedules/` into a reviewable agent product interface. | -| Tools | Stable tool names cover files, search, shell, git, web fetch/search, structured output, QuickJS PTC programs, skills, MCP tools, child-task delegation, and native host-side `parallel_task`. Model, nested, delegated, and trusted host-direct calls use one invocation kernel with explicit origin policy. | -| Dynamic workflows | `DynamicWorkflowRuntime` uses A3S Flow to record replayable per-turn workflow and step history for `ultracode` and DeepResearch. It is separate from `/flow`, which manages workflow asset files and optional host integrations. | -| Delegation | Built-in roles and custom Markdown/YAML agents are available through `task`, `parallel_task`, and automatic delegation controls. | -| Memory | Default file-backed memory, recall, LLM extraction, `/memory`, `/ctx`, `/ctx save`, and `/sleep` support cross-session facts without flooding every prompt. | -| Safety | One run invocation context propagates identity, cancellation, events, and governance. Permission policies, HITL confirmation, budgets, workspace path checks, tool timeouts, hooks, and output sanitization feed the same provider/tool boundaries. | -| Workspaces | [Workspace Backends](/guide/workspace-backends) let built-in tools target local files, host-provided workspaces, optional S3-compatible storage, and optional remote-git services. | -| Events | `EventEnvelopeV1` is a lossless Rust/Node/Python wire shape with an open event type and preserved payload/metadata for future events. | -| Persistence | Atomic `SessionSnapshotV1` generations, memory/file stores, session IDs, auto-save, run snapshots/events, trace artifacts, loop/workflow checkpoints, memory recall, and retention caps support resumable sessions and replayable product state. | -| Verification | [Verification](/guide/verification) covers explicit verification commands, presets, structured reports, summaries, artifacts, trace events, and run replay evidence. | - -The execution shape is: +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, Workspace +access, and session recovery. + +Install the [`a3s` CLI](https://github.com/A3S-Lab/Cli) when you want to work in +a terminal. Use the Rust crate, Node.js package, or Python package when you are +building a product. They emit the same events, so every UI does not need its own +agent loop. + +## Choose an entry point + +| Entry | Use it when | Repository | +| ---------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------- | +| Rust / Node.js / Python SDKs | Adding a coding agent to an IDE, runner, service, or custom UI | [A3S-Lab/Code](https://github.com/A3S-Lab/Code) | +| `a3s code` | Running a coding agent directly in your terminal | [A3S-Lab/Cli](https://github.com/A3S-Lab/Cli) | +| `a3s-tui` | Building a terminal UI; it does not include the agent runtime | [A3S-Lab/TUI](https://github.com/A3S-Lab/TUI) | +| A3S Web | Studying the desktop task UI and its component implementation | [apps/web](https://github.com/A3S-Lab/a3s/tree/main/apps/web) | +| A3S Flow | Saving and resuming flows used by `DynamicWorkflowRuntime` | [A3S-Lab/Flow](https://github.com/A3S-Lab/Flow) | + +## What it includes + +| Area | What A3S Code provides | +| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Agent sessions | Create a Workspace-bound `AgentSession` with `SessionBuilder`; send, run, stream, cancel, save, resume, and close it. Concurrent transcript operations fail immediately instead of racing. | +| User interfaces | [`a3s code`](/guide/tui) renders the event stream in a terminal. The [Playground](/guide/playground/) shows the TUI and A3S Web flows in the docs. | +| Project files | [Filesystem-first](/guide/filesystem-first) explains `AGENTS.md`, ACL config, `.a3s/agents/`, `skills/`, `tools/`, and `schedules/`. | +| Tools | Built-in files, search, shell, Git, web, batch, structured output, QuickJS, Skills, MCP, and child-task tools. Model calls pass through argument, permission, confirmation, and cancellation checks. | +| Commands | [Commands](/guide/commands) covers TUI slash commands and custom `/command` handlers registered by an application. | +| Child tasks | Use `task`, `parallel_task`, `session.task(...)`, or `session.tasks(...)` with built-in and custom agents. Automatic delegation can be enabled separately. | +| Workflows | Use [`session.parallel`](/guide/orchestration), pipelines, phases, checkpoints, loop limits, and budget records for fixed, recoverable workflows. | +| Scheduled work | Run scheduled AgentDir turns through `serveAgentDir` / `serve_agent_dir`; each schedule keeps a stable `schedule:` session. | +| Access control | Apply permission rules, user confirmation, budgets, Workspace path checks, tool timeouts, hooks, and output cleanup during execution. | +| Workspaces | [Workspace backends](/guide/workspace-backends) support local files, application-provided workspaces, optional S3-compatible storage, and remote Git services. | +| Events | `EventEnvelopeV1` is shared by Rust, Node.js, and Python. Unknown event payloads and metadata are preserved. | +| Save and resume | Session snapshots, run events, traces, artifacts, loop/workflow checkpoints, and memory stores make sessions recoverable. | +| Verification | [Verification](/guide/verification) runs named checks and returns reports, summaries, artifacts, traces, and replay data. | + +A run roughly follows this path: ```text Agent / AgentSession - -> context assembly - -> optional planning and goal tracking - -> selected tools, delegated child tasks, or dynamic workflow steps - -> permission and confirmation policy + -> collect project context + -> optional plan + -> select tools or child tasks + -> check permission and ask the user when needed -> execution - -> trace, artifacts, memory, and verification evidence - -> compaction and persistence + -> publish events and verification results + -> save the session ``` ## Install @@ -73,9 +70,11 @@ cargo install a3s cargo install --git https://github.com/A3S-Lab/Cli ``` -Install the Rust runtime crate when embedding A3S Code: +Install an SDK when embedding A3S Code: ```bash +npm install @a3s-lab/code +pip install a3s-code cargo add a3s-code-core ``` @@ -111,7 +110,7 @@ sessions_dir = ".a3s/sessions" Manual `parallel_task` remains available unless manual delegation is disabled separately. -## Use The TUI +## Use the TUI Run `a3s code` from the workspace you want the agent to inspect: @@ -173,24 +172,23 @@ async fn main() -> anyhow::Result<()> { } ``` -Rust construction is async-first. The synchronous `Agent::session` method is a -strict compatibility path for an explicitly pre-initialized memory store and -other already-ready resources; async-only options return +Rust construction is async-first. The synchronous `Agent::session` method only +works when memory and the other required resources are already initialized; +options that require async setup return `CodeError::AsyncSessionBuildRequired`. A session-option MCP manager always uses -the async path for capability discovery. - -Direct Rust host tool calls are privileged control-plane operations. Gate them -in the embedding application before exposing them to users. - -## Entry Points - -- [A3S Code TUI](/guide/tui) explains install, config discovery, slash commands, effort profiles, dynamic workflows, optional runtime tools, and trusted views. -- [A3S CLI Code TUI](https://a3s-lab.github.io/a3s/docs/cli/code-tui) covers CLI startup, resume, update, smoke mode, and terminal lifecycle boundaries. -- [Filesystem-first](/guide/filesystem-first) covers reviewable project and AgentDir conventions. -- [Sessions](/guide/sessions) covers lifecycle, streaming, run state, persistence, and cancellation. -- [Commands](/guide/commands) distinguishes TUI commands from host command-registry handlers. -- [Tools](/guide/tools) covers direct tools, typed tool errors, structured output, and QuickJS programs. -- [Memory](/guide/memory) and [Persistence](/guide/persistence) cover reusable facts, session snapshots, and recovery paths. -- [Security](/guide/security) covers permissions, confirmations, hooks, and verification gates. -- [Verification](/guide/verification) covers command evidence, reports, and summaries. -- [Tasks](/guide/tasks) covers model-driven child-task delegation. +the async path while discovering tools. + +Calls such as `session.tool(...)` come from your application, not the model. +Check access in your application before exposing them to users. + +## Continue reading + +- [Playground](/guide/playground/) shows the A3S TUI, A3S Web, and the components used at each stage of a task. +- [A3S Code TUI](/guide/tui) explains installation, config discovery, slash commands, and effort profiles. +- [Filesystem-first](/guide/filesystem-first) covers `AGENTS.md`, ACL, AgentDir, Skills, tools, and schedules. +- [API contract](/guide/api-contract) lists the Node.js API covered by integration tests. +- [Sessions](/guide/sessions) covers creation, streaming, run state, saving, resuming, and cancellation. +- [Tools](/guide/tools) covers direct calls, typed errors, structured output, and QuickJS programs. +- [Tasks](/guide/tasks) and [orchestration](/guide/orchestration) cover child agents and fixed workflows. +- [Security](/guide/security), [hooks](/guide/hooks), and [verification](/guide/verification) cover checks before, during, and after execution. +- [Memory](/guide/memory) and [persistence](/guide/persistence) cover reusable facts and session recovery. diff --git a/website/docs/v6/en/guide/persistence.mdx b/website/docs/v6/en/guide/persistence.mdx index f89c516..71fbb3f 100644 --- a/website/docs/v6/en/guide/persistence.mdx +++ b/website/docs/v6/en/guide/persistence.mdx @@ -7,6 +7,10 @@ description: 'Saving and resuming sessions' Persistence lets a session survive process restarts and gives product surfaces a stable session ID. +A resumed session can repopulate task lists, execution history, and delivery +summaries. The [Playground](/guide/playground/) shows how the TUI and Web clients +arrange that information. + A3S Code persists three related but different things: | Object | Written by | Resumed by | Purpose | diff --git a/website/docs/v6/en/guide/playground/_meta.json b/website/docs/v6/en/guide/playground/_meta.json new file mode 100644 index 0000000..27bcc96 --- /dev/null +++ b/website/docs/v6/en/guide/playground/_meta.json @@ -0,0 +1 @@ +["index", "tui", "web"] diff --git a/website/docs/v6/en/guide/playground/index.mdx b/website/docs/v6/en/guide/playground/index.mdx new file mode 100644 index 0000000..7a4dbaf --- /dev/null +++ b/website/docs/v6/en/guide/playground/index.mdx @@ -0,0 +1,40 @@ +--- +title: 'Overview' +description: 'Explore A3S TUI, A3S Web, and the main components used to build a coding agent' +--- + +# Playground + +These previews are rendered directly in MDX. You can click through their states, +and they stay versioned with the docs. They do not connect to a model or run +commands; use them to understand how a UI consumes runtime events before +integrating the SDK. + +| Preview | What it shows | +| -------------------------------- | ---------------------------------------------------------------------------- | +| [A3S TUI](/guide/playground/tui) | Themes, run state, diffs, the file tree, and common terminal widgets | +| [A3S Web](/guide/playground/web) | The complete UI path from task input and tool calls to approval and delivery | + +## Components used to build an agent + +Select a stage to see what A3S Code already provides and where each component is +documented. + + + +The map follows a real task: define the agent and project rules, assemble +context, expose tools, check access, delegate work, then present events and save +the result. Each card links to the relevant chapter. + +## Preview scope + +- The playground changes local React state only. It never calls the A3S Code API. +- The TUI preview uses `a3s-tui` component names, its four built-in themes, and + the terminal layout used by the product. +- The Web preview follows the task flow and design tokens in `apps/web`. The + production application also connects sessions, workspaces, memory, and account + services. +- The implementation in + [`A3S-Lab/TUI`](https://github.com/A3S-Lab/TUI) and + [`apps/web`](https://github.com/A3S-Lab/a3s/tree/main/apps/web) + remains the source of truth. diff --git a/website/docs/v6/en/guide/playground/tui.mdx b/website/docs/v6/en/guide/playground/tui.mdx new file mode 100644 index 0000000..dfd8737 --- /dev/null +++ b/website/docs/v6/en/guide/playground/tui.mdx @@ -0,0 +1,47 @@ +--- +title: 'A3S TUI Playground' +description: 'Switch A3S TUI themes, run scenes, and terminal components directly in the docs' +--- + +# A3S TUI Playground + +Use the scene tabs to inspect a coding run, code changes, the Workspace tree, and +common terminal widgets. The four swatches select Dark, Light, Catppuccin, and +Tokyo Night. The checklist and component menu are interactive too. + + + +## Components represented in the preview + +| Scene | `a3s-tui` components | +| ---------- | ------------------------------------------------------------------------ | +| Run | `ActivityBlock`, `Checklist`, `TaskQueue`, `ToolStatusLine`, `StatusBar` | +| Changes | `DiffView`, `SectionHeader`, `GutterBlock`, `OutputBlock` | +| Workspace | `SplitPane`, `Tree`, `Breadcrumb`, `PreviewPanel`, `Viewport` | +| Components | `MenuPanel`, `Tabs`, `DataTable`, `Progress`, `ChoicePrompt`, `Toast` | + +`a3s-tui` also ships input, modal, log, metric, timeline, and subagent-status +components. See +[`src/components/mod.rs`](https://github.com/A3S-Lab/TUI/blob/main/src/components/mod.rs) +for the current exports. + +## How it consumes A3S Code events + +`a3s code` subscribes to `AgentSession::stream()`. Text deltas feed the +transcript, tool events update activity and tool logs, plans update checklists, +permission requests open a confirmation, and verification results feed output +and diff views. + +```text +AgentSession::stream() + -> TextDelta -> transcript + -> ToolCall* -> ActivityBlock / ToolLogView + -> Plan* -> Checklist / TaskQueue + -> PermissionAsk -> Confirm + -> Verification* -> OutputBlock / DiffView + -> End -> SessionStatus / StatusBar +``` + +The preview is rearranged to fit a documentation page and is not a replacement +for the terminal application. See [A3S Code TUI](/guide/tui) for installation +and commands, and [`A3S-Lab/TUI`](https://github.com/A3S-Lab/TUI) for source. diff --git a/website/docs/v6/en/guide/playground/web.mdx b/website/docs/v6/en/guide/playground/web.mdx new file mode 100644 index 0000000..9bb0149 --- /dev/null +++ b/website/docs/v6/en/guide/playground/web.mdx @@ -0,0 +1,41 @@ +--- +title: 'A3S Web Playground' +description: 'Try the A3S Web flow from task input through approval and delivery' +--- + +# A3S Web Playground + +The composer, execution stream, permission card, and result view are +interactive. Select “Run demo,” open the confirmation step, then allow the +operation to see the delivery summary. Denying it keeps the task at the current +tool call. + + + +## UI stages in a task + +| Stage | Main components | Data consumed | +| ---------- | ---------------------------------------------------------------------------- | --------------------------------------------------------- | +| Prepare | `NewTaskPreparation`, `TaskComposer`, `NewTaskWorkspaceControl` | Instructions, files, Skills, model, mode, and Workspace | +| Run | `ExecutionStream`, `ReasoningDisclosure`, `ToolCallTimeline` | Text, reasoning, tool lifecycle, and output | +| Confirm | `PermissionDecision` | Operation, reason, scope, risk, and timeout | +| Coordinate | `TaskRuntimeFloatingPanel`, `TaskRuntimePlanList`, `TaskRuntimeSubagentList` | Plans, child tasks, and their results | +| Deliver | `DeliverySummary`, `ChangesInspector`, `WorkspaceEditor` | Final response, verification, artifacts, and file changes | + +These components do not implement a second agent runtime. A3S Web projects A3S +Code session, event, permission, and Workspace data into a desktop UI. The same +backend can drive the TUI, an IDE extension, or your own frontend. + +## Where to start when integrating + +1. Create the task and subscribe to events with [sessions](/guide/sessions). +2. Update `ToolCallTimeline` from the lifecycle described under [tools](/guide/tools). +3. Connect approval buttons to Ask decisions from [security](/guide/security). +4. Present [plans and child tasks](/guide/tasks) in the runtime panel. +5. Read delivery state from [verification](/guide/verification) and + [persistence](/guide/persistence). + +See +[`COMPONENT_SPEC.md`](https://github.com/A3S-Lab/a3s/blob/main/apps/web/docs/COMPONENT_SPEC.md) +for the component contract and +[`apps/web`](https://github.com/A3S-Lab/a3s/tree/main/apps/web) for source. diff --git a/website/docs/v6/en/guide/security.mdx b/website/docs/v6/en/guide/security.mdx index f130636..4ef9acb 100644 --- a/website/docs/v6/en/guide/security.mdx +++ b/website/docs/v6/en/guide/security.mdx @@ -19,6 +19,10 @@ parent confirmation provider. Missing providers fail closed before a HITL request is emitted. Keep high-risk release or publish commands behind explicit policy. +`PermissionDecision` should explain the operation, reason, scope, and risk—not +just present two buttons. You can interact with it in the +[Confirm step of the Web Playground](/guide/playground/web). + ## Enforced Execution Boundary Permission policy decides whether an operation is allowed, denied, or needs diff --git a/website/docs/v6/en/guide/sessions.mdx b/website/docs/v6/en/guide/sessions.mdx index 1fe946c..407477f 100644 --- a/website/docs/v6/en/guide/sessions.mdx +++ b/website/docs/v6/en/guide/sessions.mdx @@ -7,6 +7,10 @@ description: 'Creating, streaming, resuming, and saving workspace-bound sessions `Agent` owns configuration and provider state. `Session` binds that agent to one workspace and one conversation lifecycle. +This is where UI integration usually begins. The +[A3S Web Playground](/guide/playground/web) shows how `ExecutionStream` +presents session events as task progress. + ```ts import { Agent } from '@a3s-lab/code'; diff --git a/website/docs/v6/en/guide/tasks.mdx b/website/docs/v6/en/guide/tasks.mdx index 160e587..828d164 100644 --- a/website/docs/v6/en/guide/tasks.mdx +++ b/website/docs/v6/en/guide/tasks.mdx @@ -12,6 +12,10 @@ when the runtime should proactively start specialist child agents for high-confidence work, and disable only automatic parallel fan-out with `autoParallel: false` when you want serial automatic delegation. +Web clients can present these states with `TaskRuntimePlanList` and +`TaskRuntimeSubagentList`. The +[Web Playground](/guide/playground/web) shows the matching runtime-panel layout. + ## Built-in Subagents | Agent | Use it for | diff --git a/website/docs/v6/en/guide/tools.mdx b/website/docs/v6/en/guide/tools.mdx index 5f08d49..202328f 100644 --- a/website/docs/v6/en/guide/tools.mdx +++ b/website/docs/v6/en/guide/tools.mdx @@ -10,6 +10,10 @@ session tool surface. That surface is assembled from the workspace capability set plus session-level integrations, so a non-local workspace can intentionally hide tools it cannot service. +To see tool events in a UI first, open the Run step in the +[A3S Web Playground](/guide/playground/web) or the Run scene in the +[TUI Playground](/guide/playground/tui). + ## Tool Surface | Layer | Tools | Registration rule | diff --git a/website/docs/v6/en/guide/tui.mdx b/website/docs/v6/en/guide/tui.mdx index 995328c..7265216 100644 --- a/website/docs/v6/en/guide/tui.mdx +++ b/website/docs/v6/en/guide/tui.mdx @@ -14,6 +14,11 @@ Use the TUI when you want the ready coding-agent product in a terminal. Use `a3s-code-core` when you are embedding the same runtime in another Rust host, runner, IDE bridge, or controlled product surface. +:::tip See the UI first +The [TUI Playground](/guide/playground/tui) lets you switch all four themes and +inspect run, diff, file-tree, and component views without installing the CLI. +::: + ## Surface Map | Surface | Repository | Responsibility | diff --git a/website/docs/v6/en/guide/verification.mdx b/website/docs/v6/en/guide/verification.mdx index 40f57e1..42c921c 100644 --- a/website/docs/v6/en/guide/verification.mdx +++ b/website/docs/v6/en/guide/verification.mdx @@ -17,6 +17,10 @@ Verification is session-scoped. The Rust core runs each command, records its exit status and output, and rolls every report up into a single summary that travels alongside the turn result. +Product UIs can place the summary in `DeliverySummary` and file-level results in +`ChangesInspector`. The [Web Playground result view](/guide/playground/web) +shows that composition. + ## Running Verification Commands A verification command is a small, named check: an `id`, a `kind`, a diff --git a/website/docs/v6/en/index.mdx b/website/docs/v6/en/index.mdx index 6020b30..d3118b4 100644 --- a/website/docs/v6/en/index.mdx +++ b/website/docs/v6/en/index.mdx @@ -1,7 +1,7 @@ --- pageType: home title: A3S Code -description: A governed coding-agent runtime with explicit tools, policy, events, and durable evidence. +description: A Rust runtime for coding agents with tool calls, approval, event streaming, and recovery. Available for Rust, Node.js, and Python. sidebar: false outline: false --- diff --git a/website/docs/v6/zh/_nav.json b/website/docs/v6/zh/_nav.json index 095c548..4d76d68 100644 --- a/website/docs/v6/zh/_nav.json +++ b/website/docs/v6/zh/_nav.json @@ -2,7 +2,12 @@ { "text": "文档", "link": "/guide/", - "activeMatch": "^/guide/" + "activeMatch": "^/guide/(?!examples/|playground/)" + }, + { + "text": "Playground", + "link": "/guide/playground/", + "activeMatch": "^/guide/playground/" }, { "text": "示例", diff --git a/website/docs/v6/zh/api/index.mdx b/website/docs/v6/zh/api/index.mdx index be63d87..0e55ef8 100644 --- a/website/docs/v6/zh/api/index.mdx +++ b/website/docs/v6/zh/api/index.mdx @@ -1,20 +1,20 @@ --- -title: API 与包 -description: A3S Code 的 Rust、Node.js 与 Python API 入口，以及跨语言运行时契约。 +title: SDK 与 API +description: 安装 A3S Code 的 Rust、Node.js 和 Python SDK，并找到对应 API 文档。 --- -# API 与包 +# SDK 与 API -A3S Code 的四个产品表面共享同一个运行时内核，但各自承担不同的集成职责。 -版本号与发布状态请以对应 Registry 和 +A3S Code 提供 Rust、Node.js 和 Python SDK。想直接使用终端应用，则安装 +`a3s` CLI。版本号与发布状态以对应 Registry 和 [GitHub Releases](https://github.com/A3S-Lab/Code/releases) 为准。 -| 表面 | 包或命令 | API 入口 | 适用场景 | -| -------- | --------------- | -------------------------------------------------- | ----------------------------- | -| Terminal | `a3s code` | [A3S CLI](https://github.com/A3S-Lab/CLI) | 直接运行交互式编码产品 | -| Rust | `a3s-code-core` | [docs.rs](https://docs.rs/a3s-code-core) | 完整 Runtime API 与扩展 Trait | -| Node.js | `@a3s-lab/code` | [npm](https://www.npmjs.com/package/@a3s-lab/code) | N-API 原生绑定与异步事件流 | -| Python | `a3s-code` | [PyPI](https://pypi.org/project/a3s-code/) | PyO3 原生包的同步和异步 API | +| 入口 | 包或命令 | 文档 | 适用场景 | +| -------- | --------------- | -------------------------------------------------- | ------------------------------------- | +| Terminal | `a3s code` | [A3S CLI](https://github.com/A3S-Lab/CLI) | 直接在终端运行编码 Agent | +| Rust | `a3s-code-core` | [docs.rs](https://docs.rs/a3s-code-core) | 使用完整 Runtime API 或实现扩展 Trait | +| Node.js | `@a3s-lab/code` | [npm](https://www.npmjs.com/package/@a3s-lab/code) | 在 Node.js 应用中订阅异步事件流 | +| Python | `a3s-code` | [PyPI](https://pypi.org/project/a3s-code/) | 在 Python 中使用同步或异步 API | ## 安装 @@ -29,14 +29,17 @@ npm install @a3s-lab/code python -m pip install a3s-code ``` -## 跨语言契约 +## 三种 SDK 共用什么 + +三种 SDK 使用相同的 Session 生命周期、事件格式和 Snapshot。界面可以订阅同一套 +`AgentEvent` / `EventEnvelopeV1`，保存后也可以按 Session ID 恢复。 -跨语言产品边界由版本化事件、持久化 Snapshot 和明确的生命周期方法组成。 先阅读 [API 契约](/guide/api-contract)，再根据需要进入 [会话](/guide/sessions)、[工具](/guide/tools)、 [Workspace 后端](/guide/workspace-backends) 和 [持久化](/guide/persistence)。 -可替换的宿主扩展边界包括 `LlmClient`、`ContextProvider`、`MemoryStore`、 -`SessionStore`、Workspace 服务、工具、权限、确认、Hook、安全提供者、MCP -Transport 和 Graph Store。 +接入自己的基础设施时，可以替换 `LlmClient`、`ContextProvider`、 +`MemoryStore`、`SessionStore`、Workspace 服务、工具、权限确认、Hook、MCP +Transport 和 Graph Store。想先看事件怎样进入界面，可以打开 +[A3S TUI 与 Web Playground](/guide/playground/)。 diff --git a/website/docs/v6/zh/guide/_meta.json b/website/docs/v6/zh/guide/_meta.json index ebb47e8..c31b5e7 100644 --- a/website/docs/v6/zh/guide/_meta.json +++ b/website/docs/v6/zh/guide/_meta.json @@ -1,6 +1,13 @@ [ "index", "tui", + { + "type": "dir", + "name": "playground", + "label": "Playground", + "collapsible": true, + "collapsed": false + }, { "type": "dir", "name": "examples", diff --git a/website/docs/v6/zh/guide/index.mdx b/website/docs/v6/zh/guide/index.mdx index 38f2e91..30f5cd2 100644 --- a/website/docs/v6/zh/guide/index.mdx +++ b/website/docs/v6/zh/guide/index.mdx @@ -1,59 +1,57 @@ --- title: '概览' -description: 'Rust coding-agent runtime 与 a3s code 终端工作区的执行内核' +description: 'A3S Code 的安装方式、主要能力和 SDK 入口' --- # A3S Code -A3S Code 是 `a3s code` 背后的 Rust runtime。它让 agent loop 保持可观测，并由 -同一个运行时内核负责上下文组装、受治理的 provider/tool 调用、权限策略、任务 -委派、workspace 访问、持久化、验证证据与 run replay。 - -`a3s-code` 是可嵌入的运行时和 SDK surface。`a3s code` 是 -[`a3s` CLI](https://github.com/A3S-Lab/Cli) 提供的交互式终端应用；它驱动 -A3S Code session，并用 [`a3s-tui`](https://github.com/A3S-Lab/TUI) 框架渲染 -事件流。想要现成 TUI 时安装 CLI；要构建自己的宿主、runner、IDE bridge 或产品 -UI 时安装 SDK。 - -## Surfaces - -| 名称 | 用途 | 仓库 | -| -------------- | ------------------------------------------------------------ | ----------------------------------------------- | -| `a3s-code` | 通过 Rust、Node.js 或 Python API 嵌入 coding-agent session。 | [A3S-Lab/Code](https://github.com/A3S-Lab/Code) | -| `a3s code` TUI | 运行现成的终端编程 agent。 | [A3S-Lab/Cli](https://github.com/A3S-Lab/Cli) | -| `a3s-tui` | 构建终端 UI surface；它是 UI 框架，不是 agent runtime。 | [A3S-Lab/TUI](https://github.com/A3S-Lab/TUI) | -| A3S Flow | `DynamicWorkflowRuntime` 使用的持久化 workflow engine。 | [A3S-Lab/Flow](https://github.com/A3S-Lab/Flow) | -| A3S monorepo | 产品文档、发布编排、submodule pin 与相关 crates。 | [A3S-Lab/a3s](https://github.com/A3S-Lab/a3s) | - -## 当前能力图 - -| 领域 | 当前能力 | -| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Agent 会话 | 异步优先的 `SessionBuilder` 构建 workspace-bound `AgentSession`。Transcript 操作使用 fail-fast single-flight，并暴露 `send`、`run`、`stream`、直接工具、run 状态、取消、持久化与生命周期清理。 | -| TUI | [`a3s code`](/guide/tui) 将运行时事件流渲染为终端 transcript，并提供 tool activity、approval、memory、file panel 与 session controls。 | -| 文件系统优先 | [文件系统优先](/guide/filesystem-first) 把 `AGENTS.md`、`agent.acl`、`.a3s/agents/`、`skills/`、`tools/` 与 `schedules/` 组织成可审查的 Agent 产品接口。 | -| 工具 | 稳定工具名覆盖文件、搜索、shell、git、web fetch/search、batch、结构化输出、QuickJS 程序化工具链、skills、MCP tools 与子任务委派。Model、nested、delegated 与 trusted host-direct call 通过同一个 invocation kernel，并携带显式 origin policy。 | -| 命令 | [命令](/guide/commands) 区分 TUI slash commands 与 SDK command registry，后者用于宿主自定义 `/command` handler。 | -| 委派 | 内置角色与自定义 Markdown/YAML agents 可通过 `task`、`parallel_task`、`session.task(...)`、`session.tasks(...)` 和自动委派控制使用。 | -| 编排 | [`session.parallel`](/guide/orchestration)、`session.pipeline`、workflow phases、可恢复 checkpoint、loop caps 与 workflow budget ledger 支持确定性的宿主侧 fan-out。 | -| 定时服务 | [AgentDir](/guide/agent-dir) 可通过 `serveAgentDir` / `serve_agent_dir` 运行定时 turn，每个启用 schedule 对应一个稳定的 `schedule:` session。 | -| 安全 | 单个 run invocation context 传递 identity、cancellation、event 与 governance。权限策略、HITL、budget、workspace 路径检查、工具超时、hook 和 output sanitization 进入统一 provider/tool 边界。 | -| Workspace | [Workspace 后端](/guide/workspace-backends) 让内置工具运行在本地文件、宿主提供的 workspace、可选 S3 兼容存储和可选 remote-git 服务上。 | -| 事件 | `EventEnvelopeV1` 是 Rust/Node/Python 共用的无损 wire shape，event type 保持开放，并为未来事件完整保留 payload/metadata。 | -| 持久化 | Atomic `SessionSnapshotV1` generation、memory/file store、session ID、auto-save、run snapshot/event、trace artifact、loop/workflow checkpoint、memory recall 与 retention cap 支持可恢复会话和可 replay 的产品状态。 | -| 验证 | [验证](/guide/verification) 覆盖显式验证命令、预设、结构化 reports、summaries、artifacts、trace events 与 run replay 证据。 | - -当前执行形态： +A3S Code 是 `a3s code` 终端应用背后的 Rust Runtime，也可以单独接入 IDE、 +Runner 或服务端。它负责 Agent Loop、上下文、工具调用、权限检查、子任务、 +Workspace 访问，以及任务的保存和恢复。 + +想直接在终端里使用，安装 [`a3s` CLI](https://github.com/A3S-Lab/Cli)。 +想构建自己的产品，使用 Rust crate、Node.js 包或 Python 包。它们输出同一套事件， +因此不同界面不需要各写一套 Agent Loop。 + +## 先选使用方式 + +| 入口 | 什么时候用 | 仓库 | +| --------------------------- | ------------------------------------------------ | ------------------------------------------------------------- | +| Rust / Node.js / Python SDK | 把编码 Agent 接入 IDE、Runner、服务端或自己的 UI | [A3S-Lab/Code](https://github.com/A3S-Lab/Code) | +| `a3s code` | 直接在终端里运行编码 Agent | [A3S-Lab/Cli](https://github.com/A3S-Lab/Cli) | +| `a3s-tui` | 构建终端界面，不包含 Agent Runtime | [A3S-Lab/TUI](https://github.com/A3S-Lab/TUI) | +| A3S Web | 查看桌面任务界面和组件实现 | [apps/web](https://github.com/A3S-Lab/a3s/tree/main/apps/web) | +| A3S Flow | 为 `DynamicWorkflowRuntime` 保存和恢复流程 | [A3S-Lab/Flow](https://github.com/A3S-Lab/Flow) | + +## 主要能力 + +| 领域 | 可以做什么 | +| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Agent 会话 | 通过异步 `SessionBuilder` 创建绑定到 Workspace 的 `AgentSession`；支持 `send`、`run`、`stream`、取消、保存、恢复和清理。同一会话发生并发冲突时会立即报错。 | +| 终端界面 | [`a3s code`](/guide/tui) 把事件流显示成终端对话，并展示工具调用、确认提示、记忆、文件和会话状态。 | +| 项目约定 | [文件系统优先](/guide/filesystem-first) 介绍如何用 `AGENTS.md`、`agent.acl`、`.a3s/agents/`、`skills/`、`tools/` 和 `schedules/` 管理项目配置。 | +| 工具 | 内置文件、搜索、Shell、Git、网页、Batch、结构化输出、QuickJS、Skills、MCP 和子任务工具。模型发起的调用统一经过参数、权限、确认和取消检查。 | +| 命令 | [命令](/guide/commands) 说明 TUI 的斜杠命令，以及如何在 SDK 中注册自己的 `/command`。 | +| 子任务 | 通过 `task`、`parallel_task`、`session.task(...)` 和 `session.tasks(...)` 使用内置或自定义 Agent；自动委派可以单独开关。 | +| 流程编排 | [`session.parallel`](/guide/orchestration)、`session.pipeline`、阶段、Checkpoint、循环上限和预算记录，可用于编写固定且可恢复的工作流。 | +| 定时任务 | [AgentDir](/guide/agent-dir) 可以通过 `serveAgentDir` / `serve_agent_dir` 运行定时 Turn；每个 Schedule 使用稳定的 `schedule:` Session。 | +| 安全 | 权限策略、用户确认、预算、Workspace 路径检查、工具超时、Hook 和输出清理都会在执行过程中生效。 | +| Workspace | [Workspace 后端](/guide/workspace-backends) 支持本地文件、应用提供的 Workspace、可选的 S3 兼容存储和 remote-git 服务。 | +| 事件 | `EventEnvelopeV1` 是 Rust、Node.js、Python 共用的事件格式；未知事件的 Payload 和 Metadata 也会保留。 | +| 保存与恢复 | `SessionSnapshotV1`、Session ID、Auto-save、Run Event、Trace、Artifact、Loop / Workflow Checkpoint 和 Memory Store 用来恢复会话和回放运行过程。 | +| 验证 | [验证](/guide/verification) 支持验证命令、预设、结构化报告、摘要、Artifact、Trace Event 和 Run Replay。 | + +一次执行大致会经过这些步骤： ```text Agent / AgentSession - -> 上下文组装 - -> 可选 planning - -> 选择工具或委派子任务 - -> 权限与确认策略 + -> 收集项目上下文 + -> 可选 Plan + -> 模型选择工具或子任务 + -> 检查权限，必要时询问用户 -> 执行 - -> trace、artifact 与验证证据 - -> 压缩与持久化 + -> 发送事件和验证结果 + -> 保存会话 ``` ## 安装 @@ -151,19 +149,14 @@ session.close(); await agent.close(); ``` -## 入口 - -- [A3S Code TUI](/guide/tui) 说明安装、配置发现、slash commands，以及 CLI 与 runtime 的区别。 -- [文件系统优先](/guide/filesystem-first)覆盖可审查的项目约定和 AgentDir 约定。 -- [API 契约](/guide/api-contract)说明经过集成测试的 Node SDK surface。 -- [会话](/guide/sessions)覆盖生命周期、streaming、run 状态、持久化与取消。 -- [命令](/guide/commands) 区分 TUI 命令和 SDK command registry 中的自定义处理器。 -- [工具](/guide/tools)覆盖直接工具、typed tool errors、结构化输出与 QuickJS programs。 -- [验证](/guide/verification)覆盖命令证据、reports 与 summaries。 -- [任务](/guide/tasks)覆盖模型驱动的子任务委派。 -- [编排](/guide/orchestration)覆盖宿主驱动的 fan-out、pipeline 与可恢复 workflow。 -- [安全](/guide/security)覆盖权限、确认、hooks 与验证 gate。 -- [Hooks](/guide/hooks)覆盖工具、prompt、skill、session 与 error 生命周期拦截。 -- [Agent Directory](/guide/agent-dir)覆盖持久化文件系统优先 agents、tools 与 schedules。 -- [Memory](/guide/memory) 与 [持久化](/guide/persistence)覆盖可复用事实、session snapshot 与恢复路径。 -- [Provider 配置](/guide/providers)覆盖 ACL provider 配置与环境变量注入。 +## 接着看 + +- [Playground](/guide/playground/) 展示 A3S TUI、A3S Web，以及任务各阶段会用到的组件。 +- [A3S Code TUI](/guide/tui) 说明安装、配置发现、斜杠命令和 Effort。 +- [文件系统优先](/guide/filesystem-first) 介绍 `AGENTS.md`、ACL、AgentDir、Skill、工具和定时任务。 +- [API 契约](/guide/api-contract) 列出经过集成测试的 Node.js API。 +- [会话](/guide/sessions) 介绍创建、流式输出、运行状态、保存、恢复和取消。 +- [工具](/guide/tools) 介绍直接调用、错误类型、结构化输出和 QuickJS Program。 +- [任务](/guide/tasks) 与 [编排](/guide/orchestration) 介绍子 Agent 和固定工作流。 +- [安全](/guide/security)、[Hook](/guide/hooks) 与 [验证](/guide/verification) 介绍执行前、执行中和执行后的检查。 +- [Memory](/guide/memory) 与 [持久化](/guide/persistence) 介绍跨会话信息和任务恢复。 diff --git a/website/docs/v6/zh/guide/persistence.mdx b/website/docs/v6/zh/guide/persistence.mdx index 288f3eb..eb7f659 100644 --- a/website/docs/v6/zh/guide/persistence.mdx +++ b/website/docs/v6/zh/guide/persistence.mdx @@ -7,6 +7,9 @@ description: '保存与恢复 session' 持久化让 session 可以跨进程恢复，也让产品界面拥有稳定 session ID。 +恢复后的 Session 可以重新填充任务列表、执行记录和交付摘要。 +[Playground](/guide/playground/) 展示了 TUI 与 Web 分别怎样安排这些信息。 + A3S Code 会持久化三种相关但不同的对象： | 对象 | 写入方 | 恢复入口 | 用途 | diff --git a/website/docs/v6/zh/guide/playground/_meta.json b/website/docs/v6/zh/guide/playground/_meta.json new file mode 100644 index 0000000..27bcc96 --- /dev/null +++ b/website/docs/v6/zh/guide/playground/_meta.json @@ -0,0 +1 @@ +["index", "tui", "web"] diff --git a/website/docs/v6/zh/guide/playground/index.mdx b/website/docs/v6/zh/guide/playground/index.mdx new file mode 100644 index 0000000..469992b --- /dev/null +++ b/website/docs/v6/zh/guide/playground/index.mdx @@ -0,0 +1,34 @@ +--- +title: '组件总览' +description: '直接查看 A3S TUI、A3S Web 和构建编码 Agent 所需的主要组件' +--- + +# Playground + +这里的预览直接由 MDX 渲染，可以点击、切换状态，也能跟随文档一起维护。它们不会 +连接模型或执行命令，适合在接入 SDK 前了解界面如何承接运行时事件。 + +| 预览 | 可以查看什么 | +| -------------------------------- | ------------------------------------------------------ | +| [A3S TUI](/guide/playground/tui) | 主题、执行状态、Diff、文件树，以及常用终端组件 | +| [A3S Web](/guide/playground/web) | 从任务输入、工具执行、权限确认到交付结果的完整界面流程 | + +## 构建 Agent 要用到哪些组件 + +选择一个阶段，可以看到 A3S Code 已经提供的组件，以及它们在文档中的位置。 + + + +这张图按一次任务的实际顺序排列：先定义 Agent 和项目规则，再准备上下文、开放工具、 +检查权限、拆分任务，最后把事件交给界面并保存结果。点击卡片可进入对应章节。 + +## 预览与正式产品的区别 + +- Playground 只切换本地 React 状态，不会调用 A3S Code API。 +- TUI 预览使用 `a3s-tui` 的组件名称、四套内置主题和实际终端布局。 +- Web 预览参照 `apps/web` 的任务流程和设计 Token，正式应用还会连接 Session、 + Workspace、Memory 与账号服务。 +- 组件实现以 + [`A3S-Lab/TUI`](https://github.com/A3S-Lab/TUI) 和 + [`apps/web`](https://github.com/A3S-Lab/a3s/tree/main/apps/web) + 源码为准。 diff --git a/website/docs/v6/zh/guide/playground/tui.mdx b/website/docs/v6/zh/guide/playground/tui.mdx new file mode 100644 index 0000000..e0c1474 --- /dev/null +++ b/website/docs/v6/zh/guide/playground/tui.mdx @@ -0,0 +1,44 @@ +--- +title: 'A3S TUI Playground' +description: '在文档中切换 A3S TUI 的主题、执行场景和终端组件' +--- + +# A3S TUI Playground + +切换上方场景可以查看一次编码任务的执行状态、代码 Diff、Workspace 文件树和常用 +终端组件；右上角四个色块分别对应 Dark、Light、Catppuccin 和 Tokyo Night。 +任务清单和组件菜单也可以点击。 + + + +## 预览里用了哪些组件 + +| 场景 | 对应的 `a3s-tui` 组件 | +| --------- | ------------------------------------------------------------------------ | +| 执行 | `ActivityBlock`、`Checklist`、`TaskQueue`、`ToolStatusLine`、`StatusBar` | +| 代码改动 | `DiffView`、`SectionHeader`、`GutterBlock`、`OutputBlock` | +| Workspace | `SplitPane`、`Tree`、`Breadcrumb`、`PreviewPanel`、`Viewport` | +| 组件浏览 | `MenuPanel`、`Tabs`、`DataTable`、`Progress`、`ChoicePrompt`、`Toast` | + +`a3s-tui` 还提供输入、弹窗、日志、指标、时间线和子 Agent 状态等组件。完整导出列表见 +[`src/components/mod.rs`](https://github.com/A3S-Lab/TUI/blob/main/src/components/mod.rs)。 + +## 它怎样接收 A3S Code 事件 + +`a3s code` 订阅 `AgentSession::stream()`。文本增量写入对话区，工具事件更新 +Activity 与 ToolLog，Plan 更新 Checklist，权限请求打开 Confirm，验证结果进入 +Output 和 Diff，Session 状态最终写入 StatusBar。 + +```text +AgentSession::stream() + -> TextDelta -> transcript + -> ToolCall* -> ActivityBlock / ToolLogView + -> Plan* -> Checklist / TaskQueue + -> PermissionAsk -> Confirm + -> Verification* -> OutputBlock / DiffView + -> End -> SessionStatus / StatusBar +``` + +预览采用文档尺寸重新排版，并不替代可运行的终端应用。安装和命令说明见 +[A3S Code TUI](/guide/tui)，组件源码见 +[`A3S-Lab/TUI`](https://github.com/A3S-Lab/TUI)。 diff --git a/website/docs/v6/zh/guide/playground/web.mdx b/website/docs/v6/zh/guide/playground/web.mdx new file mode 100644 index 0000000..4581382 --- /dev/null +++ b/website/docs/v6/zh/guide/playground/web.mdx @@ -0,0 +1,38 @@ +--- +title: 'A3S Web Playground' +description: '在文档中体验 A3S Web 从任务输入到权限确认和结果交付的界面流程' +--- + +# A3S Web Playground + +输入框、执行记录、权限卡片和结果页都可以操作。点击“运行演示”，再进入确认步骤； +允许后会看到交付摘要，拒绝则停在当前工具调用。 + + + +## 一次任务会经过哪些界面 + +| 阶段 | 主要组件 | 接收的数据 | +| ---- | ---------------------------------------------------------------------------- | ----------------------------------------- | +| 准备 | `NewTaskPreparation`、`TaskComposer`、`NewTaskWorkspaceControl` | 指令、文件、Skill、模型、模式和 Workspace | +| 执行 | `ExecutionStream`、`ReasoningDisclosure`、`ToolCallTimeline` | 文本、推理、工具生命周期和输出 | +| 确认 | `PermissionDecision` | 操作、原因、影响范围、风险和确认时限 | +| 协作 | `TaskRuntimeFloatingPanel`、`TaskRuntimePlanList`、`TaskRuntimeSubagentList` | Plan、子任务及其结果 | +| 交付 | `DeliverySummary`、`ChangesInspector`、`WorkspaceEditor` | 最终回复、验证状态、Artifact 和文件改动 | + +这些组件不是另一套 Agent Runtime。A3S Web 把 A3S Code 的 Session、Event、 +Permission 和 Workspace 数据投影成桌面界面；同一个后端也可以换成 TUI、IDE +扩展或自己的前端。 + +## 接入时从哪里开始 + +1. 用 [Session](/guide/sessions) 创建任务，并订阅事件流。 +2. 按 [工具](/guide/tools) 的生命周期更新 `ToolCallTimeline`。 +3. 遇到 Ask 决策时，用 [权限与安全](/guide/security) 对接确认按钮。 +4. 把 [Plan 与子任务](/guide/tasks) 显示在运行面板。 +5. 从 [验证](/guide/verification) 和 [持久化](/guide/persistence) 读取交付状态。 + +完整的组件约定见 +[`COMPONENT_SPEC.md`](https://github.com/A3S-Lab/a3s/blob/main/apps/web/docs/COMPONENT_SPEC.md)， +实现位于 +[`apps/web`](https://github.com/A3S-Lab/a3s/tree/main/apps/web)。 diff --git a/website/docs/v6/zh/guide/security.mdx b/website/docs/v6/zh/guide/security.mdx index 817370f..ea1395f 100644 --- a/website/docs/v6/zh/guide/security.mdx +++ b/website/docs/v6/zh/guide/security.mdx @@ -9,6 +9,9 @@ A3S Code 在创建 session 时暴露安全控制，并通过 session hook 暴露 委派子运行会继承所选 subagent 或 worker spec 的有边界权限。使用 `confirmationInheritance` 控制子运行的 Ask 决策，并把高风险发布命令放在显式 policy 后面。 +`PermissionDecision` 应该向用户说明操作、原因、影响范围和风险，而不只是放两个按钮。 +[Web Playground 的“确认”步骤](/guide/playground/web) 可以直接操作这个组件。 + ```ts const session = agent.session('/repo', { permissionPolicy: { diff --git a/website/docs/v6/zh/guide/sessions.mdx b/website/docs/v6/zh/guide/sessions.mdx index b0d53d2..99d71cd 100644 --- a/website/docs/v6/zh/guide/sessions.mdx +++ b/website/docs/v6/zh/guide/sessions.mdx @@ -7,6 +7,9 @@ description: '创建、流式输出、恢复和保存工作区绑定的 session' `Agent` 持有配置和 provider 状态。`Session` 把这个 agent 绑定到一个工作区和一次对话生命周期。 +界面通常从这里开始接入：[A3S Web Playground](/guide/playground/web) 展示了 +`ExecutionStream` 如何把 Session 事件显示成任务进度。 + ```ts import { Agent } from '@a3s-lab/code'; diff --git a/website/docs/v6/zh/guide/tasks.mdx b/website/docs/v6/zh/guide/tasks.mdx index 317d95a..5c87244 100644 --- a/website/docs/v6/zh/guide/tasks.mdx +++ b/website/docs/v6/zh/guide/tasks.mdx @@ -11,6 +11,9 @@ description: '使用 task、parallel_task 与 subagent 进行手动和自动委 specialist 子 agent 时启用它；如果只想让自动委派串行执行，可以用 `autoParallel: false` 关闭自动并行 fan-out。 +Web 界面可以用 `TaskRuntimePlanList` 和 `TaskRuntimeSubagentList` 展示这些状态。 +[Web Playground](/guide/playground/web) 中的执行面板给出了对应布局。 + ## 内置 Subagents | Agent | 适用场景 | diff --git a/website/docs/v6/zh/guide/tools.mdx b/website/docs/v6/zh/guide/tools.mdx index f7ffec6..c02b7f6 100644 --- a/website/docs/v6/zh/guide/tools.mdx +++ b/website/docs/v6/zh/guide/tools.mdx @@ -8,6 +8,10 @@ description: '工具选择、直接工具调用与验证证据' A3S Code 会保留工具注册表。`toolNames()` 返回当前 session 的工具表面。这个表面由 workspace capability 与 session 级集成共同组装；因此非本地 workspace 可以有意隐藏它无法提供服务的工具。 +想先看工具事件在界面中的效果，可以打开 +[A3S Web Playground](/guide/playground/web) 的“执行”步骤，或 +[TUI Playground](/guide/playground/tui) 的“执行”场景。 + ## 工具表面 | 层级 | 工具 | 注册规则 | diff --git a/website/docs/v6/zh/guide/tui.mdx b/website/docs/v6/zh/guide/tui.mdx index 884a07c..a7b3411 100644 --- a/website/docs/v6/zh/guide/tui.mdx +++ b/website/docs/v6/zh/guide/tui.mdx @@ -13,6 +13,11 @@ description: '安装、配置并使用 a3s code 终端应用' 需要现成的终端编程 agent 时使用 TUI；要构建自己的 harness、IDE 扩展、 server worker、workflow runner 或产品 UI 时使用 SDK 包。 +:::tip 先看界面 +[TUI Playground](/guide/playground/tui) 可以切换四套主题，并查看执行、Diff、 +文件树和常用组件。不需要安装 CLI。 +::: + ## Surface Map | Surface | 仓库 | 职责 | diff --git a/website/docs/v6/zh/guide/verification.mdx b/website/docs/v6/zh/guide/verification.mdx index 549e3cc..45cc5c7 100644 --- a/website/docs/v6/zh/guide/verification.mdx +++ b/website/docs/v6/zh/guide/verification.mdx @@ -11,6 +11,9 @@ import { Tab, Tabs } from '@rspress/core/theme'; 验证是会话级的。Rust 核心运行每条命令，记录其退出状态和输出，并将每份报告汇总为一份随回合结果一同返回的摘要。 +产品界面可以把摘要放进 `DeliverySummary`，把文件级结果放进 +`ChangesInspector`。[Web Playground 的结果页](/guide/playground/web) 展示了这种组合。 + ## 运行验证命令 一条验证命令就是一个小而具名的检查：一个 `id`、一个 `kind`、一段可读的 `description`，以及要运行的 `command`。当某个失败应被视为硬失败而非警告时，将该检查标记为 `required`。 diff --git a/website/docs/v6/zh/index.mdx b/website/docs/v6/zh/index.mdx index 471fc6f..f7488f8 100644 --- a/website/docs/v6/zh/index.mdx +++ b/website/docs/v6/zh/index.mdx @@ -1,7 +1,7 @@ --- pageType: home title: A3S Code -description: 可治理的编码 Agent 运行时，让工具、策略、事件与持久化证据保持显式。 +description: 用 Rust 构建的编码 Agent 运行时，支持工具调用、权限确认、事件流和任务恢复，并提供 Rust、Node.js、Python API。 sidebar: false outline: false --- diff --git a/website/rspress.config.ts b/website/rspress.config.ts index 18d7ad2..4d92811 100644 --- a/website/rspress.config.ts +++ b/website/rspress.config.ts @@ -10,13 +10,20 @@ export default defineConfig({ siteOrigin, title: 'A3S Code', description: - 'A governed coding-agent runtime with explicit tools, policy, events, and durable evidence.', + 'A Rust runtime for coding agents with tool calls, approval, event streaming, and recovery. Available for Rust, Node.js, and Python.', lang: 'zh', icon: '/favicon.svg', logo: '/a3s-code-mark.svg', logoText: 'A3S Code', outDir: 'doc_build', llms: true, + markdown: { + globalComponents: [ + path.join(__dirname, 'theme/components/AgentBuildingBlocks.tsx'), + path.join(__dirname, 'theme/components/TuiPlayground.tsx'), + path.join(__dirname, 'theme/components/WebPlayground.tsx'), + ], + }, multiVersion: { default: 'v6', versions: ['v6'], @@ -27,14 +34,14 @@ export default defineConfig({ label: '简体中文', title: 'A3S Code', description: - '可治理的编码 Agent 运行时，让工具、策略、事件与持久化证据保持显式。', + '用 Rust 构建的编码 Agent 运行时，支持工具调用、权限确认、事件流和任务恢复，并提供 Rust、Node.js、Python API。', }, { lang: 'en', label: 'English', title: 'A3S Code', description: - 'A governed coding-agent runtime with explicit tools, policy, events, and durable evidence.', + 'A Rust runtime for coding agents with tool calls, approval, event streaming, and recovery. Available for Rust, Node.js, and Python.', }, ], head: [ diff --git a/website/theme/components/AgentBuildingBlocks.tsx b/website/theme/components/AgentBuildingBlocks.tsx new file mode 100644 index 0000000..1165e8c --- /dev/null +++ b/website/theme/components/AgentBuildingBlocks.tsx @@ -0,0 +1,339 @@ +import { useState } from 'react'; +import { useLang, useSite, useVersion, withBase } from '@rspress/core/runtime'; + +type Locale = 'zh' | 'en'; + +type Localized = { + zh: string; + en: string; +}; + +type BuildingBlock = { + name: string; + description: Localized; + path: string; +}; + +type BuildingBlockGroup = { + id: string; + label: Localized; + summary: Localized; + blocks: BuildingBlock[]; +}; + +const groups: BuildingBlockGroup[] = [ + { + id: 'define', + label: { zh: '定义 Agent', en: 'Define the agent' }, + summary: { + zh: '先说明它是谁、要遵守哪些项目规则，以及可以加载哪些配置和 Skill。', + en: 'Describe the agent, the project rules it follows, and the configuration and Skills it can load.', + }, + blocks: [ + { + name: 'AGENTS.md', + description: { + zh: '随仓库保存的项目说明、命令和约束。', + en: 'Repository-owned instructions, commands, and constraints.', + }, + path: '/guide/agents-md.html', + }, + { + name: 'AgentDir', + description: { + zh: '用文件组织 Agent、工具和定时任务。', + en: 'Filesystem definitions for agents, tools, and schedules.', + }, + path: '/guide/agent-dir.html', + }, + { + name: 'A3S ACL', + description: { + zh: '配置模型、存储、目录和运行参数。', + en: 'Configure models, storage, directories, and runtime options.', + }, + path: '/guide/filesystem-config.html', + }, + { + name: 'Skills', + description: { + zh: '按需加载可复用的工作说明。', + en: 'Load reusable task instructions when they are needed.', + }, + path: '/guide/skills.html', + }, + ], + }, + { + id: 'think', + label: { zh: '准备上下文', en: 'Prepare context' }, + summary: { + zh: '选择模型，把项目文件、记忆和其他上下文控制在模型可处理的范围内。', + en: 'Choose a model and keep project files, memory, and other context within the model window.', + }, + blocks: [ + { + name: 'LlmClient', + description: { + zh: '连接内置 Provider，或注入自己的模型客户端。', + en: 'Use a built-in provider or inject your own model client.', + }, + path: '/guide/providers.html', + }, + { + name: 'ContextAssembler', + description: { + zh: '挑选、排序并限制送进模型的内容。', + en: 'Select, rank, and size the content sent to the model.', + }, + path: '/guide/context.html', + }, + { + name: 'MemoryStore', + description: { + zh: '保存可以跨会话复用的信息。', + en: 'Store information that can be reused across sessions.', + }, + path: '/guide/memory.html', + }, + ], + }, + { + id: 'act', + label: { zh: '执行操作', en: 'Take action' }, + summary: { + zh: '通过当前 Workspace 提供文件、命令、Git、网页、MCP 和自定义工具。', + en: 'Expose files, commands, Git, web, MCP, and custom tools through the current workspace.', + }, + blocks: [ + { + name: 'Built-in tools', + description: { + zh: '文件、搜索、Shell、Git、Web、Batch 和 Program。', + en: 'Files, search, shell, Git, web, batch, and program tools.', + }, + path: '/guide/tools.html', + }, + { + name: 'Workspace', + description: { + zh: '决定工具能访问什么，以及本地能力是否可用。', + en: 'Decide what tools can access and which local capabilities exist.', + }, + path: '/guide/workspace-backends.html', + }, + { + name: 'MCP', + description: { + zh: '接入外部工具服务。', + en: 'Connect external tool servers.', + }, + path: '/guide/mcp.html', + }, + { + name: 'Custom tools', + description: { + zh: '注册应用自己的工具和结构化结果。', + en: 'Register application tools and structured results.', + }, + path: '/guide/tools.html', + }, + ], + }, + { + id: 'control', + label: { zh: '控制权限', en: 'Control access' }, + summary: { + zh: '在工具执行前检查权限、询问用户、限制预算，并按需使用沙箱。', + en: 'Check permissions, ask the user, enforce budgets, and apply a sandbox before tools run.', + }, + blocks: [ + { + name: 'PermissionPolicy', + description: { + zh: '为工具配置 Allow、Ask 和 Deny 规则。', + en: 'Configure Allow, Ask, and Deny rules for tools.', + }, + path: '/guide/security.html', + }, + { + name: 'ConfirmationProvider', + description: { + zh: '把高风险操作交给用户确认。', + en: 'Ask the user before a higher-risk operation.', + }, + path: '/guide/security.html', + }, + { + name: 'Hooks & budgets', + description: { + zh: '在模型和工具生命周期中加入检查与额度限制。', + en: 'Add checks and limits to model and tool lifecycles.', + }, + path: '/guide/hooks.html', + }, + { + name: 'Sandbox', + description: { + zh: '限制命令能够写入和访问的范围。', + en: 'Limit what commands can write and access.', + }, + path: '/guide/isolation.html', + }, + ], + }, + { + id: 'coordinate', + label: { zh: '拆分任务', en: 'Coordinate work' }, + summary: { + zh: '把工作交给子 Agent，或用固定流程、队列和定时任务组织执行。', + en: 'Delegate to child agents or organize work with fixed workflows, queues, and schedules.', + }, + blocks: [ + { + name: 'Tasks', + description: { + zh: '让模型选择并启动子 Agent。', + en: 'Let the model select and start child agents.', + }, + path: '/guide/tasks.html', + }, + { + name: 'Teams', + description: { + zh: '定义可复用的 Agent 角色。', + en: 'Define reusable agent roles.', + }, + path: '/guide/teams.html', + }, + { + name: 'Orchestration', + description: { + zh: '用 Parallel、Pipeline 和 Checkpoint 编排固定流程。', + en: 'Build fixed flows with parallel, pipeline, and checkpoints.', + }, + path: '/guide/orchestration.html', + }, + { + name: 'Schedules', + description: { + zh: '按计划运行 AgentDir 中的任务。', + en: 'Run AgentDir tasks on a schedule.', + }, + path: '/guide/filesystem-schedules.html', + }, + ], + }, + { + id: 'observe', + label: { zh: '展示与恢复', en: 'Present and recover' }, + summary: { + zh: '把事件交给 TUI 或 Web 界面，并保存足够的信息来验证、排错和恢复任务。', + en: 'Feed events to a TUI or web UI and save enough state to verify, debug, and resume work.', + }, + blocks: [ + { + name: 'AgentEvent', + description: { + zh: '把文本、工具、计划和生命周期变化发送给界面。', + en: 'Send text, tools, plans, and lifecycle changes to the UI.', + }, + path: '/guide/sessions.html', + }, + { + name: 'Verification', + description: { + zh: '保存验证命令、报告和结果。', + en: 'Save verification commands, reports, and results.', + }, + path: '/guide/verification.html', + }, + { + name: 'Snapshot & checkpoint', + description: { + zh: '保存会话和执行进度，之后继续运行。', + en: 'Save session state and execution progress for later recovery.', + }, + path: '/guide/persistence.html', + }, + { + name: 'A3S TUI / Web', + description: { + zh: '把同一套运行事件显示成终端或桌面界面。', + en: 'Render the same runtime events in terminal or desktop interfaces.', + }, + path: '/guide/playground/', + }, + ], + }, +]; + +const text = { + zh: { + aria: '构建 Agent 的组件', + open: '打开文档', + }, + en: { + aria: 'Components for building an agent', + open: 'Open docs', + }, +}; + +function localized(value: Localized, locale: Locale) { + return value[locale]; +} + +export default function AgentBuildingBlocks() { + const locale: Locale = useLang() === 'zh' ? 'zh' : 'en'; + const labels = text[locale]; + const [activeId, setActiveId] = useState('act'); + const active = groups.find((group) => group.id === activeId) ?? groups[2]; + const version = useVersion(); + const { site } = useSite(); + const routePrefix = [ + version && version !== site.multiVersion.default ? version : '', + locale !== site.lang ? locale : '', + ] + .filter(Boolean) + .join('/'); + const route = (pathname: string) => { + const path = pathname.replace(/^\/+/, ''); + const parts = [routePrefix, path].filter(Boolean).join('/'); + return withBase(`/${parts}`); + }; + + return ( +
+
{String(index + 1).padStart(2, '0')} + {localized(group.label, locale)} + + ))} + + +
+
+ {localized(active.label, locale)} +

{localized(active.summary, locale)}

+
+
+ {active.blocks.map((block) => ( + + {block.name} + {localized(block.description, locale)} + {labels.open} → + + ))} +
+
+ + ); +} diff --git a/website/theme/components/HomeLayout.tsx b/website/theme/components/HomeLayout.tsx index 5d85a83..0b3ca10 100644 --- a/website/theme/components/HomeLayout.tsx +++ b/website/theme/components/HomeLayout.tsx @@ -43,48 +43,48 @@ const governanceFeatures: Feature[] = [ { index: '01', title: { - zh: '治理每一次副作用', - en: 'Govern every side effect', + zh: '每次工具调用都先过检查', + en: 'Check every tool call', }, body: { - zh: '参数校验、能力声明、权限、人工确认、Hook、预算、安全提供者与取消，共享同一条工具调用路径。', - en: 'Validation, capabilities, permissions, confirmation, hooks, budgets, security providers, and cancellation share one invocation path.', + zh: '修改文件、运行命令、操作 Git 和访问外部服务都会走同一套流程：校验参数、检查能力和权限，必要时先询问用户，再执行。', + en: 'File changes, shell commands, Git operations, and external requests use one path: validate the arguments, check capabilities and permissions, ask the user when needed, then run.', }, tags: ['policy', 'HITL', 'sandbox'], }, { index: '02', title: { - zh: '让上下文保持有界', - en: 'Keep context bounded', + zh: '大结果不会塞满上下文', + en: 'Keep large results out of the prompt', }, body: { - zh: '读取、搜索、命令输出、Git 与网页证据使用范围或游标；大型结果进入带预览、大小与哈希的有界 Artifact。', - en: 'Reads, searches, command output, Git, and web evidence use ranges or cursors. Large results become bounded artifacts with previews, sizes, and hashes.', + zh: '文件读取、搜索、命令输出、Git 结果和网页内容都支持范围或游标。内容过大时会保存为 Artifact，模型只接收预览、大小和哈希。', + en: 'File reads, searches, command output, Git results, and web pages support ranges or cursors. Oversized results become artifacts, while the model gets a preview, size, and hash.', }, tags: ['cursor', 'artifact', 'hash'], }, { index: '03', title: { - zh: '拥有自己的 UI', - en: 'Own the UI', + zh: '界面由你的产品来做', + en: 'Build the UI you want', }, body: { - zh: 'Core 发出 AgentEvent；SDK 流与持久化 Run 使用无损 EventEnvelopeV1。宿主可以选择呈现方式，而不必分叉 Agent Loop。', - en: 'Core emits AgentEvent while SDK streams and persisted runs use lossless EventEnvelopeV1. Hosts choose presentation without forking the agent loop.', + zh: 'Core 在执行过程中持续发出 AgentEvent，SDK 和持久化 Run 使用 EventEnvelopeV1。终端、IDE 或网页都能复用同一个 Agent Loop。', + en: 'Core emits AgentEvent throughout a run. SDK streams and persisted runs use EventEnvelopeV1, so a terminal, IDE, or web UI can render the same loop.', }, tags: ['AgentEvent', 'EventEnvelopeV1'], }, { index: '04', title: { - zh: '从证据恢复', - en: 'Resume from evidence', + zh: '任务中断后可以接着跑', + en: 'Resume without guessing', }, body: { - zh: 'SessionSnapshotV1 可以把会话、Run、Artifact、Trace、验证报告与子任务记录原子提交为一个 Generation。', - en: 'SessionSnapshotV1 can atomically commit sessions, runs, artifacts, traces, verification reports, and child-task records as one generation.', + zh: 'SessionSnapshotV1 会一起保存会话、Run、Artifact、Trace、验证结果和子任务记录，恢复时不用让模型猜之前做过什么。', + en: 'SessionSnapshotV1 saves the session, runs, artifacts, traces, verification results, and child-task records together, so interrupted work can continue from saved state.', }, tags: ['snapshot', 'replay', 'verification'], }, @@ -93,53 +93,53 @@ const governanceFeatures: Feature[] = [ const capabilityCards = [ { className: 'a3s-bento-card--wide a3s-bento-card--policy', - eyebrow: { zh: '调用内核', en: 'INVOCATION KERNEL' }, + eyebrow: { zh: '工具调用', en: 'TOOL CALLS' }, title: { - zh: '工具可用，不等于工具越权', - en: 'Available never means ungoverned', + zh: '哪些工具能用，由代码和配置决定', + en: 'Code and config decide which tools are available', }, body: { - zh: '文件、搜索、Shell、Git、Web、Batch、QuickJS、结构化生成与委派，都在 Workspace 能力和宿主策略允许时才暴露。', - en: 'Files, search, shell, Git, web, batch, QuickJS, structured generation, and delegation are exposed only when workspace capability and host policy allow.', + zh: '文件、搜索、Shell、Git、Web、Batch、QuickJS、结构化输出和子任务，只有在 Workspace 支持且权限允许时才会开放给模型。', + en: 'Files, search, shell, Git, web, batch, QuickJS, structured output, and child tasks are exposed only when the workspace supports them and policy allows them.', }, tags: ['files', 'shell', 'git', 'web', 'program', 'task'], }, { className: 'a3s-bento-card--models', - eyebrow: { zh: '模型适配', en: 'MODEL ADAPTERS' }, + eyebrow: { zh: '模型', en: 'MODELS' }, title: { - zh: '统一生命周期，不锁定提供商', - en: 'One lifecycle, no provider lock-in', + zh: '换模型，不用重写 Agent Loop', + en: 'Switch models without rewriting the loop', }, body: { - zh: 'Anthropic、智谱、OpenAI-compatible API，或宿主注入的 LlmClient。', - en: 'Anthropic, Zhipu, OpenAI-compatible APIs, or a host-injected LlmClient.', + zh: '支持 Anthropic、智谱、OpenAI-compatible API，也可以注入自己的 LlmClient。', + en: 'Use Anthropic, Zhipu, OpenAI-compatible APIs, or inject your own LlmClient.', }, tags: ['streaming', 'tools', 'structured output'], }, { className: 'a3s-bento-card--state', - eyebrow: { zh: '持久状态', en: 'DURABLE STATE' }, + eyebrow: { zh: '任务记录', en: 'RUN DATA' }, title: { - zh: 'Run、Trace、Artifact 与 Snapshot', - en: 'Runs, traces, artifacts, and snapshots', + zh: '保存运行记录，也能恢复现场', + en: 'Save the run and pick up where it stopped', }, body: { - zh: '原子快照、事件回放、验证证据、Checkpoint，以及可选的 State Graph / Flow 投影。', - en: 'Atomic snapshots, event replay, verification evidence, checkpoints, and optional State Graph / Flow projection.', + zh: '一次任务可以保存 Snapshot、事件、Trace、Artifact、验证结果和 Checkpoint；需要时再接 State Graph 或 Flow。', + en: 'Save snapshots, events, traces, artifacts, verification results, and checkpoints. Add State Graph or Flow only when you need them.', }, tags: ['atomic', 'replayable', 'auditable'], }, { className: 'a3s-bento-card--extend', - eyebrow: { zh: '扩展边界', en: 'EXTENSION BOUNDARIES' }, + eyebrow: { zh: '扩展', en: 'EXTENSIONS' }, title: { - zh: '用显式契约扩展运行时', - en: 'Extend through explicit contracts', + zh: '接入自己的工具和存储', + en: 'Bring your own tools and storage', }, body: { - zh: 'MCP、Skills、ContextProvider、MemoryStore、SessionStore、自定义工具与 Workspace 服务保持可替换。', - en: 'MCP, Skills, ContextProvider, MemoryStore, SessionStore, custom tools, and workspace services stay replaceable.', + zh: 'MCP、Skills、ContextProvider、MemoryStore、SessionStore、Workspace 服务和自定义工具都可以替换或扩展。', + en: 'Replace or extend MCP, Skills, ContextProvider, MemoryStore, SessionStore, workspace services, and custom tools.', }, tags: ['MCP', 'Skills', 'traits'], }, @@ -147,12 +147,12 @@ const capabilityCards = [ className: 'a3s-bento-card--wide a3s-bento-card--workspace', eyebrow: { zh: '工作区', en: 'WORKSPACE' }, title: { - zh: '代码智能与工具遵守同一个 Workspace', - en: 'Code intelligence and tools share one workspace boundary', + zh: '模型只会看到当前 Workspace 能做的事', + en: 'The model sees only what the workspace can do', }, body: { - zh: '符号、定义、引用、实现、诊断与修订信息由宿主选择的 Workspace 提供；不具备本地能力的后端不会向模型声明本地 Bash 或 Git。', - en: 'Symbols, definitions, references, implementations, diagnostics, and revisions come from the host-selected workspace. A backend without local capability never advertises local Bash or Git.', + zh: '代码导航与文件工具都来自你选择的 Workspace。远程或对象存储后端不能运行本地命令时，Bash 和 Git 就不会暴露给模型。', + en: 'Code navigation and file tools come from the workspace you select. If a remote or object-backed workspace cannot run local commands, Bash and Git are not shown to the model.', }, tags: ['symbols', 'diagnostics', 'local / S3 / remote'], }, @@ -165,8 +165,8 @@ const surfaces = [ packageName: 'a3s code', href: 'https://github.com/A3S-Lab/CLI', description: { - zh: '现成的交互式编码产品，渲染推理、工具、审批、任务进度与 Diff。', - en: 'The ready interactive coding product for reasoning, tools, approvals, task progress, and diffs.', + zh: '开箱即用的终端界面，可以查看推理、工具调用、确认提示、任务进度和 Diff。', + en: 'A ready-to-run terminal UI for reasoning, tool calls, approval prompts, task progress, and diffs.', }, command: 'brew install A3S-Lab/tap/a3s', }, @@ -176,8 +176,8 @@ const surfaces = [ packageName: 'a3s-code-core', href: 'https://crates.io/crates/a3s-code-core', description: { - zh: '完整的异步运行时 API 与公共扩展 Trait。', - en: 'The complete async runtime API and public extension traits.', + zh: '完整的异步 Runtime API，以及用于接入自定义能力的公共 Trait。', + en: 'The complete async runtime API, plus public traits for custom integrations.', }, command: 'cargo add a3s-code-core', }, @@ -187,8 +187,8 @@ const surfaces = [ packageName: '@a3s-lab/code', href: 'https://www.npmjs.com/package/@a3s-lab/code', description: { - zh: '基于 N-API 的原生绑定，覆盖生命周期、事件流、工具、Store、编排与 MCP。', - en: 'Native N-API bindings for lifecycle, streams, tools, stores, orchestration, and MCP.', + zh: '通过 N-API 提供原生绑定，覆盖会话、事件流、工具、存储、编排和 MCP。', + en: 'Native N-API bindings for sessions, event streams, tools, storage, orchestration, and MCP.', }, command: 'npm install @a3s-lab/code', }, @@ -198,8 +198,8 @@ const surfaces = [ packageName: 'a3s-code', href: 'https://pypi.org/project/a3s-code/', description: { - zh: '基于 PyO3 的原生包，提供同步与异步应用 API。', - en: 'A native PyO3 package with synchronous and asynchronous application APIs.', + zh: '通过 PyO3 提供原生包，同时支持同步和异步 API。', + en: 'A native PyO3 package with both synchronous and asynchronous APIs.', }, command: 'python -m pip install a3s-code', }, @@ -209,10 +209,10 @@ const runtimeLayers = [ { id: 'surfaces', code: 'L01 / SURFACES', - title: { zh: '产品入口', en: 'Product surfaces' }, + title: { zh: '接入方式', en: 'Ways to use it' }, body: { - zh: 'Terminal、Rust、Node.js 与 Python 进入同一套执行语义；呈现方式可以不同，Runtime Contract 保持一致。', - en: 'Terminal, Rust, Node.js, and Python enter the same execution semantics. Presentation varies while the runtime contract stays consistent.', + zh: '同一套 Runtime 可以直接跑在终端里，也可以通过 Rust、Node.js 或 Python 接进你的应用。接口不同，执行流程一致。', + en: 'Run the same runtime in a terminal or embed it through Rust, Node.js, or Python. The APIs differ; the execution flow stays the same.', }, tags: ['a3s code', 'Rust', 'Node.js', 'Python'], }, @@ -221,8 +221,8 @@ const runtimeLayers = [ code: 'L02 / AGENT API', title: { zh: 'Agent 与 Session', en: 'Agent and session' }, body: { - zh: 'Agent 持有解析后的配置与共享能力；AgentSession 把它们绑定到一个 Workspace 和一段对话生命周期。', - en: 'Agent owns resolved configuration and shared capabilities. AgentSession binds them to one workspace and conversation lifecycle.', + zh: 'Agent 读取配置并准备共享能力；AgentSession 把这些能力连接到一个项目目录和一段对话。', + en: 'Agent loads configuration and shared capabilities. AgentSession connects them to one project workspace and one conversation.', }, tags: ['Agent', 'AgentSession', 'lifecycle'], }, @@ -231,38 +231,38 @@ const runtimeLayers = [ code: 'L03 / INTELLIGENCE', title: { zh: '上下文、记忆与模型', en: 'Context, memory, and models' }, body: { - zh: 'ContextAssembler 排序并预算输入；Memory 保留可复用事实；模型适配器统一流、工具调用、结构化输出与取消。', - en: 'ContextAssembler ranks and budgets inputs, memory retains reusable facts, and model adapters normalize streaming, tool calls, structured output, and cancellation.', + zh: 'ContextAssembler 挑选输入并控制大小，Memory 保存可复用信息，模型适配器负责流式输出、工具调用、结构化结果和取消。', + en: 'ContextAssembler selects and sizes inputs, memory keeps reusable information, and model adapters handle streaming, tool calls, structured output, and cancellation.', }, tags: ['ContextAssembler', 'Memory', 'LlmClient'], }, { id: 'governance', code: 'L04 / GOVERNANCE', - title: { zh: '治理内核', en: 'Governance kernel' }, + title: { zh: '权限与执行检查', en: 'Permission and execution checks' }, body: { - zh: '每个副作用依次经过参数校验、能力检查、权限、人工确认、预算、安全提供者、沙箱与取消边界。', - en: 'Every side effect crosses argument validation, capability checks, permissions, human confirmation, budgets, security providers, sandboxing, and cancellation.', + zh: '工具真正执行前，Runtime 会校验参数并检查能力和权限；再按配置进行用户确认、预算限制、沙箱隔离或取消。', + en: 'Before a tool runs, the runtime validates its arguments and checks capabilities and permissions, then applies approval, budget, sandbox, and cancellation rules.', }, tags: ['validate', 'permission', 'confirm', 'budget'], }, { id: 'tools', code: 'L05 / WORKSPACE', - title: { zh: 'Workspace 与工具', en: 'Workspace and tools' }, + title: { zh: '项目文件与工具', en: 'Project files and tools' }, body: { - zh: '文件、搜索、Shell、Git、Web、代码智能、MCP、Skills 与委派只在 Workspace 能力和策略共同允许时注册。', - en: 'Files, search, shell, Git, web, code intelligence, MCP, Skills, and delegation register only when workspace capability and policy both allow.', + zh: '文件、搜索、Shell、Git、网页、代码导航、MCP、Skills 和子任务，会按当前 Workspace 的能力和权限开放。', + en: 'Files, search, shell, Git, web, code navigation, MCP, Skills, and child tasks are enabled according to the current workspace and its permissions.', }, tags: ['files', 'git', 'web', 'MCP', 'Skills'], }, { id: 'evidence', code: 'L06 / DURABILITY', - title: { zh: '事件与持久证据', en: 'Events and durable evidence' }, + title: { zh: '事件、记录与恢复', en: 'Events, records, and recovery' }, body: { - zh: 'AgentEvent 与 EventEnvelopeV1 向产品公开生命周期；Run、Trace、Artifact、验证报告和 SessionSnapshotV1 支持审计与恢复。', - en: 'AgentEvent and EventEnvelopeV1 expose lifecycle to products. Runs, traces, artifacts, verification reports, and SessionSnapshotV1 support audit and recovery.', + zh: 'AgentEvent 把执行过程交给界面；Run、Trace、Artifact、验证报告和 SessionSnapshotV1 用来排查问题、审计和恢复任务。', + en: 'AgentEvent feeds the execution stream to your UI. Runs, traces, artifacts, verification reports, and SessionSnapshotV1 support debugging, audit, and recovery.', }, tags: ['EventEnvelopeV1', 'Run', 'Artifact', 'Snapshot'], }, @@ -276,110 +276,130 @@ const runtimeLayers = [ const copy = { zh: { - eyebrow: 'OPEN SOURCE · ASYNC RUST RUNTIME', - titleLead: '构建可治理的', - titleAccent: '编码 Agent', + eyebrow: 'OPEN SOURCE · RUST AGENT RUNTIME', + titleLead: '把编码 Agent', + titleAccent: '接进你的产品', subtitle: - 'A3S Code 把 Agent Loop、Workspace 工具、模型适配、策略决策、版本化事件与持久化证据放在显式契约之后。', - docs: '开始使用', + 'A3S Code 是一个用 Rust 写的 Agent 运行时。它负责 Agent Loop、工具调用、权限确认、事件流和任务恢复，并提供 Rust、Node.js、Python API。', + docs: '查看文档', github: '查看 GitHub', copy: '复制', copied: '已复制', - turn: '一次受治理的 Turn', - proposal: '模型提出工具调用', - governed: '统一治理边界', - result: '结果成为事件与证据', - context: '上下文 + 记忆', - model: '模型适配器', - guard: '校验 → 权限 → 确认 → 预算 → 沙箱', + turn: '一次 Agent 执行会经过什么', + proposal: '模型请求调用工具', + governed: '执行前检查', + result: '执行结果写入事件记录', + context: '项目上下文 + 记忆', + model: '模型', + guard: '参数 → 权限 → 确认 → 预算 → 沙箱', evidence: 'Run · Trace · Artifact · Snapshot', - surfacesLabel: '一个运行时，四种产品表面', + record: '执行记录', + surfacesLabel: '四种接入方式，同一套 Runtime', whyEyebrow: 'WHY A3S CODE', - whyTitle: '可组合，也可问责。', + whyTitle: 'Agent 真正动手之前，先把规则定清楚。', whyBody: - '运行时把执行语义放在一个可观察、可替换、可持久化的边界里；UI、身份、凭据与部署策略仍由宿主拥有。', - architectureEyebrow: 'VISIBLE BY DESIGN', - architectureTitle: '责任链不是黑盒。', + '模型可以读写文件、运行命令和操作 Git，但每次调用仍会先检查参数和权限。你的应用决定给它哪些工具，也能拿到完整的执行记录。', + architectureEyebrow: 'HOW IT RUNS', + architectureTitle: '一层一层看清 Agent 在做什么。', architectureBody: - 'AgentSession 绑定 Workspace 与会话；模型只提出调用。每个副作用经过同一条治理路径，再以版本化事件和耐久证据向宿主公开。', + '从产品入口到 AgentSession、模型、权限检查、Workspace 工具和运行记录，每一层只负责一件事。把鼠标移到分层图上，可以查看它们各自的作用。', architectureAlt: - 'A3S Code 的受治理 Agent 运行时架构：模型、策略、工具、事件与持久化快照之间的显式流转。', - capabilitiesEyebrow: 'RUNTIME CAPABILITIES', - capabilitiesTitle: '能力丰富，授权明确。', + 'A3S Code 运行时分层图，展示接入方式、AgentSession、上下文、权限检查、工具与运行记录。', + capabilitiesEyebrow: 'WHAT YOU GET', + capabilitiesTitle: '需要什么，就打开什么。', capabilitiesBody: - 'Core 默认保持可嵌入。云存储、服务端和遥测是可选能力；自动压缩、目标、委派、沙箱、持久化与图投影都需要宿主显式配置。', - surfacesEyebrow: 'CHOOSE YOUR SURFACE', - surfacesTitle: '同一套执行语义，进入你的技术栈。', + 'Core 默认只提供可嵌入的基础运行时。云存储、服务端、遥测、自动压缩、子任务、沙箱和持久化，都由你的应用按需启用。', + surfacesEyebrow: 'USE IT YOUR WAY', + surfacesTitle: '想直接用，或接进自己的应用，都可以。', surfacesBody: - '直接运行终端产品，或通过 Rust、Node.js、Python 把同一个 Runtime 嵌入自己的 IDE、Runner、服务与产品界面。', - boundariesEyebrow: 'EXPLICIT BOUNDARIES', - boundariesTitle: 'Core 管执行，宿主管信任。', + '终端版可以立即运行；Rust crate、Node.js 和 Python 包提供同一套 Runtime，适合 IDE、Runner、服务端和自己的界面。', + boundariesEyebrow: 'WHAT STAYS YOURS', + boundariesTitle: '执行交给 Runtime，账号和权限留在你的应用里。', boundaryItems: [ - 'Core 是可嵌入运行时，不是托管 Agent 服务，也不是终端组件库。', - '独立的 A3S CLI 负责交互式 TUI、账户适配与呈现策略。', - '身份、凭据、部署和直接宿主工具的信任决策始终属于宿主。', + 'A3S Code Core 提供 Agent Runtime，不提供托管服务，也不规定界面应该长什么样。', + 'a3s code 的终端界面由独立的 A3S CLI 提供。', + '账号、凭据、部署方式，以及哪些应用工具可以直接调用，仍由你的应用决定。', ], - boundaryLink: '阅读架构与边界', - ctaTitle: '从一个可观察的 Turn 开始。', + boundaryLink: '查看架构说明', + boundaryCoreLabel: 'A3S CODE', + boundaryCoreRole: '执行 Agent 与工具', + boundaryContract: 'API 与事件', + boundaryHostLabel: '你的应用', + boundaryHostRole: '账号、权限与界面', + stackTitle: 'A3S CODE / 分层图', + stackHint: '移入查看这一层', + stackTop: '产品', + stackBottom: '记录', + ctaEyebrow: 'TRY IT', + ctaTitle: '先在一个项目里跑起来。', ctaBody: - '运行 a3s code，或把 a3s-code-core 嵌入你的产品。工具、策略、事件和证据从第一天起就是显式的。', - ctaPrimary: '阅读快速开始', - ctaSecondary: '查看 API 契约', - footer: - 'MIT licensed. Built in Rust. Designed for governed agent products.', + '安装 a3s code 直接体验，或者选择 Rust、Node.js、Python 包接入自己的产品。', + ctaPrimary: '查看快速开始', + ctaSecondary: '打开 Playground', + footer: 'MIT 开源 · Rust 编写 · 支持 Terminal / Rust / Node.js / Python', }, en: { - eyebrow: 'OPEN SOURCE · ASYNC RUST RUNTIME', - titleLead: 'Build governed', - titleAccent: 'coding agents', + eyebrow: 'OPEN SOURCE · RUST AGENT RUNTIME', + titleLead: 'Add a coding agent', + titleAccent: 'to your product', subtitle: - 'A3S Code keeps the agent loop, workspace tools, model adapters, policy decisions, versioned events, and durable evidence behind explicit contracts.', - docs: 'Get started', + 'A3S Code is a Rust agent runtime. It handles the agent loop, tool calls, approval, event streaming, and recovery, with APIs for Rust, Node.js, and Python.', + docs: 'Read the docs', github: 'View on GitHub', copy: 'Copy', copied: 'Copied', - turn: 'One governed turn', - proposal: 'The model proposes a tool call', - governed: 'One governance boundary', - result: 'Results become events and evidence', - context: 'context + memory', - model: 'model adapter', - guard: 'validation → permission → confirmation → budget → sandbox', + turn: 'What happens during one agent turn', + proposal: 'The model requests a tool', + governed: 'Checks before execution', + result: 'The result enters the event stream', + context: 'project context + memory', + model: 'model', + guard: 'arguments → permission → approval → budget → sandbox', evidence: 'Run · Trace · Artifact · Snapshot', - surfacesLabel: 'One runtime, four product surfaces', + record: 'run record', + surfacesLabel: 'Four ways in, one runtime', whyEyebrow: 'WHY A3S CODE', - whyTitle: 'Composable and accountable.', + whyTitle: 'Set the rules before the agent changes anything.', whyBody: - 'The runtime puts execution semantics behind one observable, replaceable, durable boundary. The host still owns UI, identity, credentials, and deployment policy.', - architectureEyebrow: 'VISIBLE BY DESIGN', - architectureTitle: 'The chain of responsibility is not a black box.', + 'The model can edit files, run commands, and operate Git, but every call is checked first. Your application decides which tools it gets and receives the full execution stream.', + architectureEyebrow: 'HOW IT RUNS', + architectureTitle: 'See what each part of the runtime does.', architectureBody: - 'AgentSession binds a workspace and conversation; the model only proposes calls. Every side effect crosses the same governance path, then returns as versioned events and durable evidence.', + 'The stack runs from product entry points through AgentSession, models, permission checks, workspace tools, and run records. Hover a layer to inspect its job.', architectureAlt: - 'A3S Code governed agent runtime architecture showing the explicit flow between model, policy, tools, events, and durable snapshots.', - capabilitiesEyebrow: 'RUNTIME CAPABILITIES', - capabilitiesTitle: 'Rich capability. Explicit authority.', + 'A3S Code runtime layers showing entry points, AgentSession, context, permission checks, tools, and run records.', + capabilitiesEyebrow: 'WHAT YOU GET', + capabilitiesTitle: 'Turn on only what your product needs.', capabilitiesBody: - 'Core stays embeddable by default. Cloud storage, serving, and telemetry are opt-in; compaction, goals, delegation, sandboxing, persistence, and graph projection require host configuration.', - surfacesEyebrow: 'CHOOSE YOUR SURFACE', - surfacesTitle: 'One execution model, in your stack.', + 'Core starts as an embeddable runtime. Cloud storage, serving, telemetry, compaction, child tasks, sandboxing, and persistence are enabled by your application when needed.', + surfacesEyebrow: 'USE IT YOUR WAY', + surfacesTitle: 'Run it in a terminal or embed it in your app.', surfacesBody: - 'Run the terminal product or embed the same runtime in an IDE, runner, service, or product UI through Rust, Node.js, and Python.', - boundariesEyebrow: 'EXPLICIT BOUNDARIES', - boundariesTitle: 'Core owns execution. The host owns trust.', + 'The terminal app is ready to use. The Rust crate, Node.js package, and Python package bring the same runtime to an IDE, runner, server, or custom UI.', + boundariesEyebrow: 'WHAT STAYS YOURS', + boundariesTitle: 'The runtime executes. Your app controls access.', boundaryItems: [ - 'Core is an embeddable runtime, not a hosted agent service or terminal widget library.', - 'The separate A3S CLI owns the interactive TUI, account adapters, and presentation policy.', - 'Identity, credentials, deployment, and trust decisions for direct host tools remain host-owned.', + '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.', ], - boundaryLink: 'Read architecture and boundaries', - ctaTitle: 'Start with one observable turn.', + boundaryLink: 'Read the architecture guide', + boundaryCoreLabel: 'A3S CODE', + boundaryCoreRole: 'RUNS AGENTS + TOOLS', + boundaryContract: 'APIs + EVENTS', + boundaryHostLabel: 'YOUR APP', + boundaryHostRole: 'OWNS UI + ACCESS', + stackTitle: 'A3S CODE / RUNTIME LAYERS', + stackHint: 'HOVER A LAYER', + stackTop: 'PRODUCT', + stackBottom: 'RECORDS', + ctaEyebrow: 'TRY IT', + ctaTitle: 'Try it in a real repository.', ctaBody: - 'Run a3s code or embed a3s-code-core. Tools, policy, events, and evidence are explicit from day one.', - ctaPrimary: 'Read the quick start', - ctaSecondary: 'Explore the API contract', - footer: - 'MIT licensed. Built in Rust. Designed for governed agent products.', + 'Install a3s code to start immediately, or choose the Rust, Node.js, or Python package for your own product.', + ctaPrimary: 'Open the quick start', + ctaSecondary: 'Open the playground', + footer: 'MIT licensed · Built in Rust · Terminal / Rust / Node.js / Python', }, }; @@ -498,7 +518,7 @@ function RuntimeDiagram({ labels }: { labels: (typeof copy)[Locale] }) { EventEnvelopeV1
- evidence + {labels.record} {labels.evidence}
@@ -512,7 +532,13 @@ type RuntimeLayerStyle = CSSProperties & { '--layer-index': number; }; -function LayeredRuntime({ locale }: { locale: Locale }) { +function LayeredRuntime({ + locale, + labels, +}: { + locale: Locale; + labels: (typeof copy)[Locale]; +}) { const [activeId, setActiveId] = useState('governance'); const activeLayer = runtimeLayers.find((layer) => layer.id === activeId) ?? runtimeLayers[3]; @@ -523,16 +549,16 @@ function LayeredRuntime({ locale }: { locale: Locale }) { onMouseLeave={() => setActiveId('governance')} >
- RUNTIME STACK / EXPLODED VIEW + {labels.stackTitle} - {locale === 'zh' ? '移入查看职责' : 'HOVER TO INSPECT'} + {labels.stackHint}
{runtimeLayers.map((layer, index) => (
- +
@@ -809,15 +835,15 @@ export function HomeLayout() {
@@ -839,7 +865,7 @@ export function HomeLayout() {
- START BUILDING + {labels.ctaEyebrow}

{labels.ctaTitle}

{labels.ctaBody}

@@ -850,7 +876,7 @@ export function HomeLayout() { {labels.ctaSecondary} diff --git a/website/theme/components/TuiPlayground.tsx b/website/theme/components/TuiPlayground.tsx new file mode 100644 index 0000000..6063798 --- /dev/null +++ b/website/theme/components/TuiPlayground.tsx @@ -0,0 +1,505 @@ +import { type CSSProperties, useState } from 'react'; +import { useLang } from '@rspress/core/runtime'; + +type Locale = 'zh' | 'en'; +type SceneId = 'session' | 'diff' | 'workspace' | 'components'; +type ThemeId = 'dark' | 'light' | 'catppuccin' | 'tokyo-night'; + +type Theme = { + id: ThemeId; + name: string; + palette: { + bg: string; + panel: string; + panelStrong: string; + text: string; + muted: string; + line: string; + blue: string; + green: string; + amber: string; + red: string; + purple: string; + }; +}; + +const themes: Theme[] = [ + { + id: 'dark', + name: 'Dark', + palette: { + bg: '#090b10', + panel: '#0f1218', + panelStrong: '#171b24', + text: '#e8edf4', + muted: '#7f8999', + line: '#29303c', + blue: '#6ca3ff', + green: '#46d39a', + amber: '#efb354', + red: '#ef767a', + purple: '#b493ff', + }, + }, + { + id: 'light', + name: 'Light', + palette: { + bg: '#f4f5f7', + panel: '#ffffff', + panelStrong: '#e9ebef', + text: '#1d222b', + muted: '#687180', + line: '#d5d9df', + blue: '#2465d8', + green: '#16845f', + amber: '#a8650c', + red: '#c33f48', + purple: '#6f50bf', + }, + }, + { + id: 'catppuccin', + name: 'Catppuccin', + palette: { + bg: '#1e1e2e', + panel: '#181825', + panelStrong: '#313244', + text: '#cdd6f4', + muted: '#9399b2', + line: '#45475a', + blue: '#89b4fa', + green: '#a6e3a1', + amber: '#f9e2af', + red: '#f38ba8', + purple: '#cba6f7', + }, + }, + { + id: 'tokyo-night', + name: 'Tokyo Night', + palette: { + bg: '#16161e', + panel: '#1a1b26', + panelStrong: '#24283b', + text: '#c0caf5', + muted: '#787c99', + line: '#3b4261', + blue: '#7aa2f7', + green: '#9ece6a', + amber: '#e0af68', + red: '#f7768e', + purple: '#bb9af7', + }, + }, +]; + +const copy = { + zh: { + aria: 'A3S TUI 组件预览', + themes: '主题', + scenes: { + session: '执行', + diff: '代码改动', + workspace: 'Workspace', + components: '组件', + }, + demo: '文档预览', + noBackend: '这里演示组件状态，不会运行命令或连接模型。', + taskTitle: '修复登录会话续期', + userPrompt: + '检查登录流程，修复 refresh token 失效后没有重新登录的问题，并补上测试。', + thinking: '正在检查 session 与 token 的调用路径', + readDone: '已读取 src/auth/session.rs', + searchDone: '找到 4 处 refresh_token 引用', + testRunning: '正在运行 auth::session 测试', + checklist: '任务清单', + items: ['定位失效分支', '更新会话恢复逻辑', '补充回归测试'], + changed: '2 个文件已修改', + diffSummary: '+18 -6', + workspaceTitle: '项目文件', + previewTitle: 'session.rs', + componentsTitle: '同一框架中的组件', + componentsHint: '选择一项查看终端组件如何组合。', + status: 'default · medium', + keys: 'Ctrl+T transcript /help commands Esc close', + }, + en: { + aria: 'A3S TUI component preview', + themes: 'Themes', + scenes: { + session: 'Run', + diff: 'Changes', + workspace: 'Workspace', + components: 'Components', + }, + demo: 'Docs preview', + noBackend: + 'This demonstrates component states; it does not run commands or connect to a model.', + taskTitle: 'Repair login session renewal', + userPrompt: + 'Inspect the login flow, fix re-authentication after a refresh token expires, and add tests.', + thinking: 'Inspecting session and token call paths', + readDone: 'Read src/auth/session.rs', + searchDone: 'Found 4 refresh_token references', + testRunning: 'Running auth::session tests', + checklist: 'Checklist', + items: [ + 'Locate the expiry branch', + 'Update session recovery', + 'Add a regression test', + ], + changed: '2 files changed', + diffSummary: '+18 -6', + workspaceTitle: 'Project files', + previewTitle: 'session.rs', + componentsTitle: 'Components in the same framework', + componentsHint: + 'Select an item to see how terminal components fit together.', + status: 'default · medium', + keys: 'Ctrl+T transcript /help commands Esc close', + }, +}; + +const componentSets = [ + { + name: 'Navigation', + components: 'MenuPanel · Tabs · Tree · TreePicker · Breadcrumb', + preview: 'menu', + }, + { + name: 'Agent activity', + components: + 'ActivityBlock · Checklist · TaskQueue · SubagentTracker · Timeline', + preview: 'activity', + }, + { + name: 'Tools & output', + components: + 'ToolLogView · ToolStatusLine · DiffView · OutputBlock · LogView', + preview: 'tools', + }, + { + name: 'Input & feedback', + components: 'PromptLine · Textarea · ChoicePrompt · Confirm · Toast', + preview: 'input', + }, +]; + +function terminalStyle(theme: Theme): CSSProperties { + return { + '--tui-bg': theme.palette.bg, + '--tui-panel': theme.palette.panel, + '--tui-panel-strong': theme.palette.panelStrong, + '--tui-text': theme.palette.text, + '--tui-muted': theme.palette.muted, + '--tui-line': theme.palette.line, + '--tui-blue': theme.palette.blue, + '--tui-green': theme.palette.green, + '--tui-amber': theme.palette.amber, + '--tui-red': theme.palette.red, + '--tui-purple': theme.palette.purple, + } as CSSProperties; +} + +export default function TuiPlayground() { + const locale: Locale = useLang() === 'zh' ? 'zh' : 'en'; + const labels = copy[locale]; + const [themeId, setThemeId] = useState('dark'); + const [scene, setScene] = useState('session'); + const [checked, setChecked] = useState([true, true, false]); + const [componentIndex, setComponentIndex] = useState(1); + const theme = themes.find((item) => item.id === themeId) ?? themes[0]; + + const toggleCheck = (index: number) => { + setChecked((current) => + current.map((value, itemIndex) => (itemIndex === index ? !value : value)), + ); + }; + + return ( +
+
+
+
+
+ {themes.map((item) => ( + + ))} +
+
+ +
+ {(Object.keys(labels.scenes) as SceneId[]).map((id) => ( + + ))} +
+ +
+
+ A3S CODE + ~/workspaces/a3s-code + 80 × 24 +
+ +
+ + +
+ {scene === 'session' && ( +
+
+
+ + {labels.taskTitle} +
+ 00:42 +
+
+ YOU +

{labels.userPrompt}

+
+
+

+ ◆ {labels.thinking} +

+

+ ✓ {labels.readDone} +

+

+ ✓ {labels.searchDone} +

+

+ ◌ {labels.testRunning} +

+
+
+ {labels.checklist} + {labels.items.map((item, index) => ( + + ))} +
+
+ )} + + {scene === 'diff' && ( +
+
+ DIFF VIEW + {labels.changed} + {labels.diffSummary} +
+
+ ▾ + src/auth/session.rs + +12 -4 +
+ 
+                  
+                    42 {'  '}match refresh_token(state).await {'{'}
+                  
+                  
+                    43- {'    '}Err(_) => return
+                    Err(AuthError::Expired),
+                  
+                  
+                    43+ {'    '}Err(AuthError::Expired) => {'{'}
+                  
+                  
+                    44+ {'      '}session.require_login().await?;
+                  
+                  
+                    45+ {'      '}session.retry_refresh().await
+                  
+                  
+                    46+ {'    }\n'}
+                  
+                  
+                    47 {'    '}result => result,
+                  
+                  
+                    48 {'  }'}
+                  
+
+
+ › + tests/auth_session.rs + +6 -2 +
+
+ )} + + {scene === 'workspace' && ( +
+
+
{labels.workspaceTitle}
+

+ ▾ a3s-code +

+

+ │ ▾ src +

+

+ │ │ session.rs +

+

+ │ │ permissions.rs +

+

+ │ └ tools.rs +

+

+ ├ ▸ tests +

+

+ └ Cargo.toml +

+
+
+
+ {labels.previewTitle} + Rust +
+ 
+                    
+                      1
+                      pub async fn refresh(
+                    
+                    
+                      2
+                      {'  '}session: &mut Session,
+                    
+                    
+                      3) -> Result<Token> {'{'}
+                    
+                    
+                      4
+                      {'  '}session.ensure_active().await?;
+                    
+                    
+                      5
+                      {'  '}session.token().await
+                    
+                    
+                      6
+                      {'\u007d'}
+                    
+
+
+
+ )} + + {scene === 'components' && ( +
+
+ {labels.componentsTitle} + {labels.componentsHint} +
+
+ +
+ {componentSets[componentIndex].name} +

{componentSets[componentIndex].components}

+
+ READY + ■■■■■■□□ 75% + ✓ workspace checked + › Continue +
+
+
+
+ )} +
+
+ +
+ PLAN + {labels.status} + ctx 38% + {labels.keys} +
+
+ +

{labels.noBackend}

+
+ ); +} diff --git a/website/theme/components/WebPlayground.tsx b/website/theme/components/WebPlayground.tsx new file mode 100644 index 0000000..c1dc183 --- /dev/null +++ b/website/theme/components/WebPlayground.tsx @@ -0,0 +1,474 @@ +import { useState } from 'react'; +import { useLang } from '@rspress/core/runtime'; + +type Locale = 'zh' | 'en'; +type ViewId = 'compose' | 'run' | 'permission' | 'result'; +type Decision = 'allowed' | 'denied' | null; + +const copy = { + zh: { + aria: 'A3S Web 任务流程预览', + demo: '文档预览', + noBackend: + '这里演示 A3S Web 的组件与状态切换，不会发送请求、修改文件或连接模型。', + tabs: { + compose: '准备', + run: '执行', + permission: '确认', + result: '结果', + }, + taskLibrary: '任务', + newTask: '新任务', + sessions: ['修复登录会话续期', '整理发布说明', '检查 API 兼容性'], + startTitle: '今天要处理什么？', + startHint: '描述任务，也可以加入文件、Skill 和 Workspace。', + prompt: + '检查登录流程，修复 refresh token 失效后没有重新登录的问题，并补上测试。', + attach: '添加上下文', + mode: 'Code', + effort: 'Medium', + send: '运行演示', + runningTitle: '修复登录会话续期', + runningHint: 'A3S Code 正在处理当前 Workspace', + instruction: + '检查登录流程，修复 refresh token 失效后没有重新登录的问题，并补上测试。', + reasoningTitle: '检查认证调用路径', + reasoning: + '先定位 refresh token 的读取与续期分支，再检查失效状态如何回到登录流程。', + toolRead: '读取 src/auth/session.rs', + toolSearch: '搜索 refresh_token', + toolTest: '运行 auth::session 测试', + plan: '计划', + planItems: ['定位失效分支', '更新会话恢复逻辑', '补充回归测试'], + nextPermission: '查看确认组件', + permissionTitle: '需要你的确认', + permissionHint: '只影响当前这一次操作', + operation: '即将执行', + operationValue: '运行 cargo test auth::session', + reason: '为什么需要', + reasonValue: '该命令会启动本地进程，当前权限规则要求先确认。', + scope: '影响范围', + scopeValue: '当前任务的 Workspace', + risk: '需要注意', + riskValue: '测试可能创建临时构建文件，不会访问 Workspace 之外的路径。', + deny: '拒绝', + allow: '允许一次', + denied: '已拒绝，本次操作不会执行。', + reset: '重新演示', + resultTitle: '任务已完成', + resultHint: '登录会话现在会在 refresh token 失效后要求重新登录。', + verified: '验证通过', + filesChanged: '2 个文件已修改', + tests: '4 项测试通过', + openChanges: '查看改动', + delivery: '交付摘要', + changedFiles: ['src/auth/session.rs', 'tests/auth_session.rs'], + }, + en: { + aria: 'A3S Web task-flow preview', + demo: 'Docs preview', + noBackend: + 'This demonstrates A3S Web components and state changes; it does not send requests, edit files, or connect to a model.', + tabs: { + compose: 'Prepare', + run: 'Run', + permission: 'Confirm', + result: 'Result', + }, + taskLibrary: 'Tasks', + newTask: 'New task', + sessions: [ + 'Repair login session renewal', + 'Prepare release notes', + 'Check API compatibility', + ], + startTitle: 'What would you like to work on?', + startHint: + 'Describe the task and optionally add files, Skills, and a Workspace.', + prompt: + 'Inspect the login flow, fix re-authentication after a refresh token expires, and add tests.', + attach: 'Add context', + mode: 'Code', + effort: 'Medium', + send: 'Run demo', + runningTitle: 'Repair login session renewal', + runningHint: 'A3S Code is working in the current Workspace', + instruction: + 'Inspect the login flow, fix re-authentication after a refresh token expires, and add tests.', + reasoningTitle: 'Inspect authentication call paths', + reasoning: + 'First locate refresh-token reads and renewal branches, then trace how an expired state returns to login.', + toolRead: 'Read src/auth/session.rs', + toolSearch: 'Search refresh_token', + toolTest: 'Run auth::session tests', + plan: 'Plan', + planItems: [ + 'Locate the expiry branch', + 'Update session recovery', + 'Add a regression test', + ], + nextPermission: 'Open confirmation', + permissionTitle: 'Your confirmation is required', + permissionHint: 'This applies only to this operation', + operation: 'About to run', + operationValue: 'cargo test auth::session', + reason: 'Why this is needed', + reasonValue: + 'This command starts a local process, so the current permission rules require confirmation.', + scope: 'Scope', + scopeValue: 'The current task Workspace', + risk: 'What to know', + riskValue: + 'The test may create temporary build files, but it cannot access paths outside the Workspace.', + deny: 'Deny', + allow: 'Allow once', + denied: 'Denied. This operation will not run.', + reset: 'Start over', + resultTitle: 'Task complete', + resultHint: + 'The login session now asks the user to sign in again after the refresh token expires.', + verified: 'Verified', + filesChanged: '2 files changed', + tests: '4 tests passed', + openChanges: 'Review changes', + delivery: 'Delivery summary', + changedFiles: ['src/auth/session.rs', 'tests/auth_session.rs'], + }, +}; + +function BrandMark() { + return ( + + ); +} + +export default function WebPlayground() { + const locale: Locale = useLang() === 'zh' ? 'zh' : 'en'; + const labels = copy[locale]; + const [view, setView] = useState('compose'); + const [decision, setDecision] = useState(null); + const [prompt, setPrompt] = useState(labels.prompt); + + const restart = () => { + setDecision(null); + setView('compose'); + setPrompt(labels.prompt); + }; + + const allow = () => { + setDecision('allowed'); + setView('result'); + }; + + return ( +
+
+
+
+ +
+ +
+ + + + +
+ {view === 'compose' && ( +
+
+ + + +

{labels.startTitle}

+

{labels.startHint}

+
+
+