diff --git a/ARCHITECTURE.zh-CN.md b/ARCHITECTURE.zh-CN.md index 7cc86e8ead..4019cab3db 100644 --- a/ARCHITECTURE.zh-CN.md +++ b/ARCHITECTURE.zh-CN.md @@ -17,7 +17,7 @@ under the License. --> -[ENGLISH](./ARCHITECTURE.md) +[English](./ARCHITECTURE.md) # Maka 后端架构 @@ -27,7 +27,7 @@ flowchart LR C["Desktop / TUI / CLI / Bot"] --> H["Runtime Host"] H --> S["SessionManager"] - S --> R["AgentRun + Runtime Runner"] + S --> R["AgentRun + RuntimeKernel"] R --> T["Tool Runtime"] R --> L["Runtime Event Log"] S --> G["Agent Graph Control Plane"] diff --git a/DESIGN.md b/DESIGN.md index 110ce19bc0..b8c6263ecd 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -14,12 +14,10 @@ colors: surface-sunken-light: "oklch(0.945 0 0)" ink-light: "oklch(0.17 0.005 286)" surface-raised-dark: "oklch(0.205 0.004 286)" - surface-overlay-dark: "oklch(0.225 0.004 286)" + surface-overlay-dark: "oklch(0.223 0.004 286)" surface-base-dark: "oklch(0.18 0.004 286)" surface-sunken-dark: "oklch(0.14 0.004 286)" ink-dark: "oklch(0.95 0.004 286)" - info-light: "oklch(0.50 0.13 240)" - info-dark: "oklch(0.74 0.13 240)" success-light: "oklch(0.50 0.17 145)" success-dark: "oklch(0.60 0.17 145)" warning-light: "oklch(0.50 0.18 55)" @@ -181,7 +179,7 @@ The palette is cool-neutral and quiet; color is generated to spec, not picked by - **Brand mark** is fixed `#71a8fd`; it identifies Maka and is never the general CTA color. - **Interaction accent** follows the active palette for focus, selection, and live state; **links and accent-colored text use the solid tier** (§3). Astryx's own semantic components are the exception — `Badge` and `StatusDot` carry fixed literals inherited from the neutral theme and follow neither the palette nor the families below. -- **Status families** — `--success`, `--warning`, `--destructive` — are generated, not picked: one lightness per mode, each hue keeping its own chroma, every member clearing AA. These are Astryx's three statuses, and Maka has no fourth: there is **no `--info` colour**. "Info" is a semantic slot, not a hue — an informational surface paints with the accent and so follows the user's palette instead of introducing a second blue that competes with it. `` needed a different mechanism to get there: `.astryx-banner.info` re-declares the tint and the text colour **on the banner element itself**, and a declaration on the element beats any ancestor's by proximity whatever the layer. The only token route left — re-pointing `--color-text-blue` / `--color-background-blue` at the root — would also repaint `Badge color="blue"`, which this section keeps literal. It is converged by listing that selector on the unlayered accent bridge in `maka-tokens.css` — the same block, so the 0.24 construction is spelled once — with `--foreground` as its text, per the Tinted Surface Rule (§3); the solid accent is left to the banner's icon and button. The residual contrast spread within a mode is hue physics — at equal lightness, yellow carries more luminance than red — and flattening it would abandon the shared-lightness premise that makes them a family. All three are declared in one block, each carrying both modes in its value, because the time warning sat thirty lines from its siblings is the time it lost its dark value and dropped under AA unnoticed. A louder band at ~90% gamut chroma exists only for 8px status dots: dots must read at a glance, tinted surfaces must not shout. These are colors; what a state *means* is a separate vocabulary (§9). +- **Status families** — `--success`, `--warning`, `--destructive` — are generated, not picked: one lightness per mode, each hue keeping its own chroma, every member clearing AA. These are Astryx's three statuses, and Maka has no fourth: there is **no `--info` colour**. "Info" is a semantic slot, not a hue — an informational surface paints with the accent and so follows the user's palette instead of introducing a second blue that competes with it. `` needed a different mechanism to get there: `.astryx-banner.info` re-declares the tint and the text colour **on the banner element itself**, and a declaration on the element beats any ancestor's by proximity whatever the layer. The only token route left — re-pointing `--color-text-blue` / `--color-background-blue` at the root — would also repaint `Badge color="blue"`, which this section keeps literal. It is converged by listing that selector on the unlayered accent bridge in `maka-tokens.css` — the same block, so the 0.24 construction is spelled once — with `--foreground` as its text, per the Tinted Surface Rule (§3); the solid accent is left to the banner's icon and button. The residual contrast spread within a mode is hue physics — at equal lightness, yellow carries more luminance than red — and flattening it would abandon the shared-lightness premise that makes them a family. All three are declared in one block, each carrying both modes in its value, because when `--warning` last sat thirty lines from its siblings, it lost its dark value and dropped under AA unnoticed. A louder band at ~90% gamut chroma exists only for 8px status dots: dots must read at a glance, tinted surfaces must not shout. These are colors; what a state *means* is a separate vocabulary (§9). - **Tinted surfaces** are Astryx's own tokens: `--color-success-muted`, `--color-warning-muted`, `--color-error-muted` and `--color-accent-muted`. Product CSS reads those four names and nothing else; a hand-rolled `oklch(from var(--destructive) …)` at a call site is forbidden. **One rung, no border rung, no strong tier** — the shape upstream ships. All four are `oklch(from var(--{hue}) l c h / 0.24)`, the alpha the neutral theme's own pastels already sit at, so a Banner and a product row painted side by side read as one material. Same weight is not enough: they must be the same **construction**, because an opaque tint does not compose, and a tinted chip on a tinted panel then resolves to its parent's exact pixel and vanishes. The three status rungs are emitted by `makaTheme.ts`; `--color-accent-muted` needs the unlayered bridge in `maka-tokens.css` instead, because `maka.css` re-declares the accent pair at component level and a root rule in the same layer would lose. A border around any surface, tinted or not, is `--border`: the fill or the ink already states the status, and a second tinted edge repeating it is §4's One Means Rule. The five that tried it — the stat tile's four outline tones, the two tool-output edges, the sandbox and error copy buttons — are gone, and their status is carried by ink instead. The Maka `--{status}-wash` / `-wash-border` vocabulary this replaced was a second authority for the same surface — its two tiers and four rungs each grew a call site that disagreed with the rung beside it. Palette swatches are not tinted surfaces: a swatch's job is to show a palette's real colour, so its literals stay. - **The solid tier is deliberately not converged.** `--success` / `--warning` / `--destructive` remain Maka's names for status ink, dots and solid fills, while Astryx calls the same idea `--color-success` / `--color-warning` / `--color-error`. Only the tinted tier has one authority today. Converging the solid tier means moving status text, status dots and status buttons at once; it is a change of its own, not an omission from this one. - **Identity colors** (avatars, channel marks) live in one 4.2–4.8:1 contrast band; desaturation for muted states happens at constant OKLab lightness. diff --git a/README.md b/README.md index 82fcc0c17c..41f3de8904 100644 --- a/README.md +++ b/README.md @@ -171,7 +171,7 @@ packages/eval/ Experiment cells, attempts, results, and executor/subject packages/computer-use/ Computer-use backend selection, host lifecycle, and protocol adapters packages/cli/ TUI and non-interactive CLI packages/ui/ Shared conversation, Markdown, Artifact, and UI primitives -native/ Rust: the direct-peer addon for Runtime Host and the gitoxide helper +native/ Rust: the Runtime Host direct-peer addon and Windows task launcher, and the gitoxide helper website/ Astro source for maka.apache.org docs/ Architecture, product, security, privacy, and test contracts diff --git a/README.zh-CN.md b/README.zh-CN.md index fc8a4bfdd9..7695a97ffc 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -170,7 +170,7 @@ packages/eval/ Experiment cell、attempt、result 与 executor/subject a packages/computer-use/ Computer Use 后端选择、Host 生命周期和协议适配 packages/cli/ TUI 和非交互 CLI packages/ui/ 共享对话、Markdown、Artifact 与 UI primitives -native/ Rust：Runtime Host 的 direct-peer addon 与 gitoxide helper +native/ Rust：Runtime Host 的 direct-peer addon 与 Windows task launcher，以及 gitoxide helper website/ maka.apache.org 的 Astro 源码 docs/ 架构、产品、安全、隐私和测试契约 diff --git a/docs/agent-swarm.md b/docs/agent-swarm.md index c685914533..a4a0019ab2 100644 --- a/docs/agent-swarm.md +++ b/docs/agent-swarm.md @@ -65,7 +65,7 @@ For the mechanism underneath, see Swarm mode is mostly instruction, but not only instruction. Four things follow from it: -1. **System prompt.** `AiSdkBackend` appends `renderSwarmModePrompt()`. +1. **System prompt.** `AiSdkTurn` appends `renderSwarmModePrompt()`. 2. **Guaranteed tools.** The mode forces `agent_list`, `update_agent_graph`, `yield_agent_graph`, `agent_swarm_status` and `agent_output` into the turn's tool catalog. Graph mode requires the same set plus `view_agent_graph`; swarm diff --git a/docs/architecture/agent-graph-stream-scheduling-draft.zh-CN.md b/docs/architecture/agent-graph-stream-scheduling-draft.zh-CN.md index 1f8741588f..08cd7f2410 100644 --- a/docs/architecture/agent-graph-stream-scheduling-draft.zh-CN.md +++ b/docs/architecture/agent-graph-stream-scheduling-draft.zh-CN.md @@ -371,9 +371,9 @@ Structural reconciliation 也不拥有 resource permit 或 global fairness。Sha 主 Agent 既不是每条 record 必经的 node，也不是 child execution 内部 callback。它是 external supervisor，承担三类职责： -1. **Observe：**检查紧凑 schedule、topology、operator state、wait、failure 与 candidate result record。 -2. **Control：**添加 dependent work、follow up 已有 operator、stop/replace 失去价值的 work，并关闭 schedule。 -3. **Synthesize：**读取权威 child output、选择已提交 result record，并回答用户。 +1. **Observe**：检查紧凑 schedule、topology、operator state、wait、failure 与 candidate result record。 +2. **Control**：添加 dependent work、follow up 已有 operator、stop/replace 失去价值的 work，并关闭 schedule。 +3. **Synthesize**：读取权威 child output、选择已提交 result record，并回答用户。 这个位置同时保留自治与响应性。Operator 可以按照持久 control decision 推进，root Agent 仍然是普通 conversation participant。用户可以通过 host 观察或停止 Graph，而不把 supervisor 变成 data-delivery bottleneck。 diff --git a/docs/cli-npm-release.md b/docs/cli-npm-release.md index 1b6c7e47ee..499c2799dd 100644 --- a/docs/cli-npm-release.md +++ b/docs/cli-npm-release.md @@ -249,7 +249,6 @@ npmjs.com. Inspect the public tags after approval: ```sh -version=0.1.0 npm view maka-agent dist-tags --json --registry https://registry.npmjs.org/ ``` diff --git a/docs/cli-npm-release.zh-CN.md b/docs/cli-npm-release.zh-CN.md index 4806f54eed..64116a513a 100644 --- a/docs/cli-npm-release.zh-CN.md +++ b/docs/cli-npm-release.zh-CN.md @@ -224,7 +224,6 @@ npm stage approve "$stage_id" --registry https://registry.npmjs.org/ 获得批准后，检查公共 dist-tags： ```sh -version=0.1.0 npm view maka-agent dist-tags --json --registry https://registry.npmjs.org/ ``` diff --git a/packages/cli/README.zh-CN.md b/packages/cli/README.zh-CN.md index ede00ece8b..754f9e31a3 100644 --- a/packages/cli/README.zh-CN.md +++ b/packages/cli/README.zh-CN.md @@ -33,7 +33,7 @@ release commit 中的 [DISCLAIMER-WIP](https://github.com/apache/maka/blob/main/ [Maka podling 状态页](https://incubator.apache.org/projects/maka.html)。本段仅为中文说明， 英文免责声明以随包发布的 `DISCLAIMER-WIP` 为准。 -> **Beta：**CLI 仍在积极开发中，稳定版发布前，命令和本地数据格式可能发生变化。 +> **Beta**：CLI 仍在积极开发中，稳定版发布前，命令和本地数据格式可能发生变化。 ## 环境要求 diff --git a/packages/cli/src/acp/README.md b/packages/cli/src/acp/README.md index 5b5cc521b5..a07e598f56 100644 --- a/packages/cli/src/acp/README.md +++ b/packages/cli/src/acp/README.md @@ -135,7 +135,7 @@ be republished. Unarchiving permits a fresh publication. Generic MCP `ask` approval uses `admission: "mcp"` and the existing atomic Session grant mechanism with `mcp_tool` scope. It does not elevate provider trust or grant Host path access. Desktop MCP continues to use its existing capability. These wire -changes move the Host compatibility epoch from 175 to 176; grant storage needs no migration. +changes bumped the Host compatibility epoch (175 to 176 in #5386); grant storage needs no migration. Close/EOF stops execution, releases subscriptions, unregisters the corresponding capabilities and closes MCP transports before closing the shared Host connection. The stdio transport stops its direct child; launchers that spawn further processes diff --git a/packages/eval/README.md b/packages/eval/README.md index 60281188f8..eeb278b020 100644 --- a/packages/eval/README.md +++ b/packages/eval/README.md @@ -282,9 +282,9 @@ silently not for others. | Symptom | Cause | Fix | |---|---|---| -| `machine path is unavailable` at CLI start | A declared machine-path env var points at a directory that doesn't exist or isn't writable/searchable ([`install-preflight.ts:273,279`](src/install-preflight.ts)). | Point the env var at a real, accessible directory before running `maka eval run`. | +| `machine path is unavailable` at CLI start | A declared machine-path env var is unset or empty ([`install-preflight.ts:297,303`](src/install-preflight.ts)). A path that is set but unusable fails with a different message, such as `... is not a directory` or `... is not writable and searchable` ([`install-preflight.ts:285,289`](src/install-preflight.ts)). | Set the env var before running `maka eval run`. | | ` Python environment is unavailable or does not provide @` | The pinned Harbor/Pier Python distribution isn't installed at the expected version in the interpreter the env var points to ([`install-preflight.ts:155-157`](src/install-preflight.ts)). | Install/upgrade the framework's Python distribution to the pinned version, or point the env var at an interpreter that already has it. | -| `Docker CLI or daemon is unavailable: ...` | `docker version` failed — the Docker CLI isn't on PATH or the daemon isn't running ([`install-preflight.ts:172`](src/install-preflight.ts)). Only checked for Docker-based environments. | Start the Docker daemon / install the Docker CLI before running a Docker-environment spec. | +| `Docker CLI or daemon is unavailable: ...` | `docker version` failed — the Docker CLI isn't on PATH or the daemon isn't running ([`install-preflight.ts:173`](src/install-preflight.ts)). Only checked for Docker-based environments. | Start the Docker daemon / install the Docker CLI before running a Docker-environment spec. | | HTTP 451 with header `X-Maka-Eval-Egress-Rule: ` from inside a subject | The egress proxy blocked a request matching a benchmark/public-solution contamination rule (see [Egress audit and security model](#egress-audit-and-security-model)). | This is intentional — the subject reached a blocked URL. If the block is a false positive against a legitimate dependency, it needs a rule change, not a bypass. | | HTTP 503 with header `X-Maka-Eval-Egress-Rule: policy_error` | The egress proxy couldn't classify the request at all. | Check the request against the proxy's supported request shapes; this is a proxy-side gap, not a benchmark contamination hit. | | Result status `infra_failed`, reason `egress audit log missing` | The subject's egress audit log wasn't produced for a Harbor cell — this always wins over a subject timeout or a missing verifier reward. | Check that the egress-proxy Compose overlay came up for the cell; this indicates infrastructure, not subject, failure. | diff --git a/packages/ui/README.md b/packages/ui/README.md index ff26b5ba91..4133907dce 100644 --- a/packages/ui/README.md +++ b/packages/ui/README.md @@ -25,7 +25,7 @@ The published Astryx API is a fixed dependency boundary. New consumers adapt to ## Layer map -Four export surfaces, in the order to look: +Five export surfaces, in the order to look: | Surface | Role | Status | |---|---|---| diff --git a/scripts/release-cli-package.mjs b/scripts/release-cli-package.mjs index 383b7a41e5..f0a9fbc6bb 100644 --- a/scripts/release-cli-package.mjs +++ b/scripts/release-cli-package.mjs @@ -509,7 +509,7 @@ function copyReleaseDocuments() { ? '> **Developer snapshot:** This Nightly is not an Apache release and is not intended for production use. Its version is bound to one exact `apache/maka` commit.\n\n' : ''; const nightlyNoticeZhCn = nightlyVersion - ? '> **开发快照：**此 Nightly 不是 Apache Release，不用于生产环境；其版本只对应一个精确的 `apache/maka` commit。\n\n' + ? '> **开发快照**：此 Nightly 不是 Apache Release，不用于生产环境；其版本只对应一个精确的 `apache/maka` commit。\n\n' : ''; writeFileSync( join(stageRoot, 'README.md'), diff --git a/website/README.md b/website/README.md index 71499993fa..f8c36ddffa 100644 --- a/website/README.md +++ b/website/README.md @@ -48,4 +48,4 @@ Colour, radius and surface tokens are the desktop app's defaults, copied by valu | Push of a release-candidate tag (`v*-rc*`) | `site/-staging` | https://maka-.staged.apache.org | | `workflow_dispatch` with a `stage` name | `site/-staging` | https://maka-.staged.apache.org | -A `workflow_dispatch` without a `stage` name publishes only from `main`; any other ref fails instead of overwriting the live site. The published `.asf.yaml` carries just `publish: whoami: asf-site` and `staging: autostage: site/*`, the same layout Apache OpenDAL uses; the repository settings in the root `.asf.yaml` stay on `main`, the only branch asfyaml reads them from. Nothing else in the repository is published. +A `workflow_dispatch` without a `stage` name publishes only from `main`; any other ref fails instead of overwriting the live site. The published `.asf.yaml` carries just `publish: whoami: asf-site` and `staging: profile: ~, autostage: site/*`, the same layout Apache OpenDAL uses; the repository settings in the root `.asf.yaml` stay on `main`, the only branch asfyaml reads them from. Nothing else in the repository is published.