You are viewing a plain text version of this content. The canonical link for it is here.

Posted to dev@maka.apache.org by "Astro-Han (via GitHub)" <gi...@apache.org> on 2026/09/08 10:56:05 UTC

[D] [DISCUSS] Make Maka easier to understand: benchmark-first homepage and a clearer README [maka]

GitHub user Astro-Han created a discussion: [DISCUSS] Make Maka easier to understand: benchmark-first homepage and a clearer README

Follow-up to #4307, with a concrete homepage prototype for feedback.

## The problem: a newcomer should understand Maka before understanding our architecture

Huajie Wang raised a useful point in our community discussion: when evaluating an unfamiliar agent or ADE, he visits its website to quickly understand what it is, what it can do, and whether it fits his work. The current homepage does not make that clear enough. We also discussed how the README's abstract language makes the same first encounter harder.

A product screenshot or a short demonstration can explain more than another paragraph about the harness. At the same time, “it can fix a failing test” is now a common capability. We need both a recognizable product and evidence that helps someone choose it.

## Proposal: lead with evidence, then show the product

The attached Chinese-language prototype explores four sections:

1. **Product identity + benchmark evidence.** Say that Maka is an open-source agent workspace, provide a download entry, and show the nine-harness comparison immediately. Five report tabs let readers inspect other experiments, with the model, result, caveat and report link changing together.
2. **A tangible workspace.** Show a polished Astryx conversation and result-inspection demo. This is explicitly example data, not a live agent or a promise that every illustrated detail is already shipped.
3. **How the product improves.** Connect evaluation findings to engineering choices and technical reading, including the event log as the source of execution history.
4. **A clear next step.** Download and try Maka on your own work.

## Evaluation-driven evolution, beyond one ranking

The nine-harness report is the default because it is our broadest published comparison in this set. But the story should be sustained evaluation, not one selected high score. The existing [evaluation reports](https://github.com/apache/maka/tree/main/docs/eval) also include a four-harness comparison, Maka vs OpenCode, an Ollama Cloud 0731 comparison, and Maka vs Kimi Code on K3.

These are different experiments on Terminal-Bench 2.1, **not five independent benchmarks or a directly comparable improvement curve**. Model/provider conditions, repetitions, infrastructure gaps and recovery accounting matter. Reports and per-task results should remain close to the headline numbers. Benchmarks are necessary evidence, not a guarantee for every user's work; showing limitations and regressions is part of earning trust.

## What changes in the README?

Use the same concrete product identity as the homepage. Lead with one sentence explaining Maka, a product image, a practical getting-started entry and a link to the evaluation evidence. Put architecture and terminology after that opening. The homepage can carry the visual narrative; the README should help a repository visitor understand and start using the project quickly.

## Design and implementation direction

The prototype uses real [Astryx templates and components](https://astryx.atmeta.com/templates): Side Gallery's composition, the AI Chat Conversation primitives, and native Table/ProgressBar/TabList elements. The website has its own responsive typography scale derived from Maka's theme; the embedded workspace retains the client's density. We keep Astro for the website. No Next.js migration is proposed.

This is a direction sketch, not a finished visual design or a replacement for the live site. Production work still needs bilingual copy, faithful product examples and the existing Apache/Incubator navigation and notices. References from the community, including Today.ai and agent/ADE websites, inform clarity and visual presentation rather than a request to copy their branding.

## Feedback requested

- If you did not know Maka, would this first screen tell you what it is and give you a reason to continue?
- Is benchmark evidence the right first-screen emphasis? What product information is still missing?
- Which real workflow should replace the example demo to best represent Maka?
- What should the first few paragraphs of the README say, and which terms should move deeper?
- Where does the visual design still feel too empty, too dense, or unlike Maka?

---

## 中文说明

这是 #4307 的一个具体方案补充，想结合长图请大家一起讨论。

华杰老师提到一个很重要的用户视角：面对一个不熟悉的 Agent / ADE，通常先看官网，希望快速知道“这是什么、有哪些核心能力、是不是自己需要的”。目前官网还不能很好地回答这些问题；我们也认为 README 的表达偏抽象，要求读者先理解理念，才看得到产品。

这版尝试把顺序改为：**首屏看到产品定位和评测证据 → 看到实际工作台 → 理解评测怎样推动技术演进 → 下载试用**。九臂比较默认展示，其余四份报告可以切换。它们是同一 Terminal-Bench 2.1 上的不同实验，不能当成五套 Benchmark，也不能连成能力增长曲线。比较条件、局限与逐题结果都应随成绩一起公开。

我们想表达的是“评测驱动演进”：不止公布一次好成绩，也公开发现了什么问题、做了什么改进、结果如何。Event Log 等架构创新和技术文章在这个基础上展开，让用户先理解价值，再理解实现。

README 则建议先给清楚的产品定义、产品图、上手入口和评测链接，再展开架构。官网和 README 应说同一种容易理解的语言。

长图是讨论原型，演示区已标明示例数据，视觉与文案仍待打磨。继续使用 Astro 和真正的 Astryx 组件；官网用适合阅读的字体比例，产品窗口保留客户端密度。

尤其想听大家反馈：第一眼是否看得懂？评测放首屏是否有吸引力？应该用哪个真实场景展示产品？README 哪些抽象表述最需要改？页面哪里还显得空、挤或不像 Maka？

AI assistance: Codex helped inspect the templates and reports, implement the prototype, capture the screenshot, and draft this discussion.

GitHub link: https://github.com/apache/maka/discussions/5031

----
This is an automatically sent email for dev@maka.apache.org.
To unsubscribe, please send an email to: dev-unsubscribe@maka.apache.org

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maka.apache.org
For additional commands, e-mail: dev-help@maka.apache.org

Re: [D] [DISCUSS] Make Maka easier to understand: benchmark-first homepage and a clearer README [maka]

Posted by "liuxiaocs7 (via GitHub)" <gi...@apache.org>.

GitHub user liuxiaocs7 added a comment to the discussion: [DISCUSS] Make Maka easier to understand: benchmark-first homepage and a clearer README

Thanks @Astro-Han — this is a valuable proposal and the diagnosis is spot on: a newcomer should understand *what Maka is and whether it fits their work* before our architecture. I also really appreciate the intellectual honesty (different experiments, not five benchmarks or a comparable curve; example data clearly labeled; showing limitations and regressions). That posture is itself trust-building for an incubating project.

I'm in favor of the direction. A few suggestions to de-risk and sharpen it:

**1. Ship the README improvements first — they're a low-cost, high-leverage quick win.** The README changes (one-sentence identity, product image, getting-started entry, link to evaluation evidence, architecture moved deeper) don't need to wait on the homepage redesign. Decoupling them lets us land value early and iterate the site separately.

**2. On the first screen, lead with identity + a real product demo; keep benchmarks as strong supporting evidence just below.** The stated goal is "what is it / is it for me," and a pass-rate table mostly answers "is it good." I'd open with a one-line positioning plus a tangible product view, then let the nine-harness comparison carry the evidence a scroll away. Benchmark-forward is powerful, but it may not be the thing that tells a stranger what Maka *is*.

**3. Confirm ASF compliance for competitor comparisons before making them first-screen.** Direct comparisons (Maka vs OpenCode, vs Kimi Code) on an official Apache (incubating) homepage touch trademark and "undue promotion" sensitivities. Worth aligning with the mentors on framing before this goes prominent — the eval reports themselves are fine; it's the comparison-forward presentation on the official site I'd check.

**4. Assign an owner for keeping the eval tabs current.** Five linked report tabs (model/result/caveat/report changing together) will rot if not updated each release, and a stale benchmark is worse than none. Naming who refreshes this per release keeps the first screen from becoming a liability.

**5. Use real, reproducible captured sessions rather than an idealized example demo.** This is the actual crux (your question "which real workflow should replace the example demo"). A polished mockup, even when labeled as example data, risks a first-run letdown if the real product looks different. A real, reproducible session that maps to the published eval work would double as evidence and product tour.

Happy to help on any of these — especially the README pass and sanity-checking that the eval numbers/tabs stay tied to the reports.

GitHub link: https://github.com/apache/maka/discussions/5031#discussioncomment-18357486

----
This is an automatically sent email for dev@maka.apache.org.
To unsubscribe, please send an email to: dev-unsubscribe@maka.apache.org

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maka.apache.org
For additional commands, e-mail: dev-help@maka.apache.org

Re: [D] [DISCUSS] Make Maka easier to understand: benchmark-first homepage and a clearer README [maka]

Posted by "Sun-GLiang (via GitHub)" <gi...@apache.org>.

GitHub user Sun-GLiang added a comment to the discussion: [DISCUSS] Make Maka easier to understand: benchmark-first homepage and a clearer README

**English**

@Astro-Han I agree with the goal of making Maka easier to understand, and with keeping evaluation evidence close to the product story. My preference would be to put an engaging product visualization on the first screen, followed immediately by the evaluation results.

My working assumption is that **Maka’s current potential users** are primarily developers and people already familiar with agents. Even for this audience, benchmark tables require interpretation and may not be the strongest first impression. The first screen should make someone want to keep looking; the next section should provide evidence that makes Maka worth trying. This changes the order of presentation while preserving the importance of the evaluations.

@liuxiaocs7 This is close to your suggestion of leading with positioning and a tangible product view. One direction I would like to explore is a **dynamic DAG built around a real task**: work branches out, independent tasks run in parallel, findings lead to additional work, and results come together into an inspectable outcome.

Crucially, it should show **how the main Session participates in building and evolving the DAG**. We should be able to see it submit an initial plan, yield while child Sessions execute, read results at checkpoints, and decide what to add or arrange next before reviewing and synthesizing the final results. Showing only child nodes lighting up would leave the actual coordination unexplained.

I also take your point about faithful demonstrations. This could be a website visualization derived from a reproducible run, paired with the actual product and its output, clearly distinguished from a screenshot of an existing DAG interface. The visual treatment still needs exploration; I am proposing the narrative rather than a finished design.

The sequence I have in mind is:

1. **First screen:** a compelling view of the task, coordination, and outcome, with clear positioning and a way to try Maka.
2. **Immediately below:** readable evaluation results, with conditions and links to the full reports.
3. **Further down:** selected product and design explanations, linking to the existing documentation and blog posts.

Users may also learn about Maka by asking AI. I consider the existing documentation sufficient for that path, so I would keep this redesign focused on the experience of people who actually visit the website.

@Astro-Han Would moving the evaluation comparison immediately below the hero still preserve the evaluation-driven story you want to tell? @liuxiaocs7 Would a visualization grounded in a real run, alongside the actual outcome, address your concern about an idealized demo—and is there a particular workflow you think would make the main Session’s role especially clear?

---

**中文**

@Astro-Han 我认同让 Maka 更容易理解的目标，也认同让评测证据紧密支撑产品叙事。我倾向于先用有吸引力的产品可视化作为首屏，紧接着展示评测结果。

我的基本判断是，**Maka 目前的潜在用户**主要是开发者和已经熟悉 Agent 的人。但即使面对这类用户，评测表格仍然需要理解和解读，未必适合作为最有吸引力的第一眼内容。首屏应该让人愿意继续看，下一部分则提供让人愿意尝试 Maka 的能力依据。这是调整呈现顺序，同时保留评测的重要性。

@liuxiaocs7 这与您提出的“定位和具体产品画面优先”比较接近。我想进一步探索的方向是：**围绕一个真实任务呈现动态 DAG**，展示工作如何展开、独立任务如何并行推进、如何根据执行中的发现追加工作，以及结果如何汇合为可检查的成果。

其中，尤其需要展示**主 Session 如何参与 DAG 的构建和演进**：提交初始计划，在子 Sessions 执行时让出本轮，在检查点读取结果，决定接下来增加或安排什么工作，最后检查并汇总结果。如果只是让子任务节点依次亮起，就没有讲清楚协作是如何组织起来的。

我也认同您对演示真实性的要求。这可以是一段依据可复现执行记录制作的官网可视化，搭配实际产品画面和产出，并明确区别于现有 DAG 界面的截图。具体视觉表现仍需要探索，目前提出的是叙事方向，而非已经完成的设计。

我设想的顺序是：

1. **首屏：** 有吸引力地展示任务、协作过程和成果，同时提供清晰定位与试用入口。
2. **紧接下一屏：** 展示容易理解的评测结果，保留比较条件和完整报告链接。
3. **后续内容：** 选择性地展开产品体验和设计说明，链接已有文档与博客。

用户也可能通过向 AI 提问来了解 Maka。我认为现有文档已经足够支撑这条路径，因此这次改版可以集中关注亲自访问官网的用户体验。

@Astro-Han 如果把评测比较紧接在首屏之后，是否仍能保留您希望表达的“评测驱动演进”？@liuxiaocs7 如果可视化依据真实执行制作，并搭配实际产出，是否能回应您对理想化演示的顾虑？您有没有认为特别适合展示主 Session 参与方式的工作流？


GitHub link: https://github.com/apache/maka/discussions/5031#discussioncomment-18368340

----
This is an automatically sent email for dev@maka.apache.org.
To unsubscribe, please send an email to: dev-unsubscribe@maka.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maka.apache.org
For additional commands, e-mail: dev-help@maka.apache.org

Re: [D] [DISCUSS] Make Maka easier to understand: benchmark-first homepage and a clearer README [maka]

Posted by "2BAB (via GitHub)" <gi...@apache.org>.

GitHub user 2BAB added a comment to the discussion: [DISCUSS] Make Maka easier to understand: benchmark-first homepage and a clearer README

I support making the product understandable before introducing the architecture, and the README improvements seem worth moving forward independently.

Reading the discussion, though, I still think the original question needs a clearer answer: **What distinguishes Maka today, and what problems would give someone a reason to choose it?** Benchmarks, product demos, and architecture articles can all help, but we first need to decide what product value they should communicate.

From the perspective of practical work, I would suggest organizing the story around three characteristics of Maka at its current stage.

**1. Model neutrality: use the model that fits your work.**

Maka provides the workspace and execution runtime while letting users choose models from different providers, local deployments, or compatible gateways.

This gives users a concrete choice to understand. We should explain supported integrations without implying that every model has identical capabilities or behavior.

**2. Designed for long tasks: keep track of progress, decisions, and uncertainty.**

The value of the event log, context management, and recovery mechanisms becomes clearer when connected to practical questions: Where did the task stop? Which results already exist? What is waiting for input? What can happen next after an interruption?

“Designed for long tasks” is a reasonable positioning, with reliability demonstrated through reproducible examples. Preserving history, restoring a pending interaction, and avoiding duplicate external effects are separate capabilities; each needs its own evidence.

**3. Beyond coding: coordinate different kinds of work toward one deliverable.**

For example:

> Combine sales data, customer feedback, and competitor research into recommendations for the next quarter, then deliver an analysis spreadsheet and a presentation.

Research and data analysis can proceed in parallel. Synthesis depends on those results. A key decision may require user input. The final artifacts need to remain consistent with that decision.

This is where Agent Graph / DAG can become meaningful to users: coordinating dependencies, parallel work, handoffs, and result aggregation. Users should be able to see how Maka organizes the work without first learning the scheduling architecture.

Under this framing, products such as ChatGPT Work and WorkBuddy are useful product references alongside harness comparisons with Pi and others.

**What this could mean for the homepage**

A possible opening direction is:

> **Your choice of model. Complex work, coordinated.**  
> Maka is an open-source agent workspace designed to coordinate tasks across tools, manage dependencies, and preserve the execution history of longer workflows.

I would pair this with a reproducible demonstration from the current product: parallel subtasks, a human decision, and results brought together. Showing how a changed requirement propagates into the final spreadsheet and presentation would make the benefit especially tangible.

Benchmarks should remain strong supporting evidence. A compact result and report link could sit near the opening, with the full comparisons below. To support the broader positioning, we should also evaluate workflows across files and tools, including output quality, elapsed time, cost, and required human intervention.

That would give the page a clearer sequence: what work users can delegate to Maka, how it handles that work, and what evidence supports the claims.

<details>
<summary>简体中文</summary>

我赞成先让新人理解产品，再展开架构；README 的改进也可以独立推进。

不过，读完上面的讨论，我觉得最初的问题还没有得到足够明确的回答：**Maka 当前的产品特色到底是什么？用户遇到什么问题时，会有理由选择它？** 评测、产品演示和架构文章都有帮助，但我们需要先明确，它们要共同说明什么产品价值。

我想从实际工作中需要解决的问题出发，试着归纳当前阶段 Maka 的三个特点。

**1. 模型中立：选择适合自己工作的模型。**

Maka 提供工作台和执行运行时，用户可以选择不同供应商的模型、本地部署的模型或兼容网关。

这是一个具体、容易理解的选择权。介绍时应说明支持范围，同时避免让用户误以为所有模型的能力与行为都完全一致。

**2. 为长程任务设计：管理进度、决定与不确定性。**

Event Log、上下文管理和恢复机制的价值，可以对应到几个实际问题：任务停在哪里？哪些结果已经产生？哪些步骤还在等待输入？中断后，接下来可以做什么？

“为长程任务设计”可以作为定位，可靠性则通过可复现的案例来证明。保留历史、恢复待答交互、避免重复的外部操作，是不同层次的能力，需要分别提供证据。

**3. Beyond coding：把不同类型的工作组织成完整交付。**

例如：

> 结合销售数据、客户反馈和竞品资料，提出下一季度的产品建议，并交付分析表与汇报材料。

资料收集和数据分析可以并行，综合判断需要等待上游结果，关键方向可能需要用户选择，最后的成果需要与这个决定保持一致。

Agent Graph / DAG 的价值，就体现在依赖管理、并行工作、任务交接和结果汇总上。用户应该能直接看到 Maka 怎样组织工作，而不必先学习调度架构。

按这个方向，除了与 Pi 等 harness 做技术比较，ChatGPT Work、WorkBuddy 这类产品也值得作为产品定位的参照。

**这对首页意味着什么**

首屏可以尝试这样的方向：

> **用你选择的模型，协调完成复杂工作。**  
> Maka 是一个开源 Agent 工作台，面向跨工具的任务编排、步骤之间的依赖管理，以及长程工作的执行历史保留。

旁边配一段当前产品可复现的真实任务演示，展示并行分工、人工决定和成果汇合。尤其可以展示：用户调整一个要求后，最终的分析表和汇报材料怎样一起更新。这会让价值更具体。

Benchmark 仍然是重要证据。首屏可以保留紧凑的成绩与报告入口，完整比较放在后面。要支撑更广泛的产品定位，还应该评测跨文件、跨工具的工作流程，包括交付质量、耗时、成本，以及需要多少次人工介入。

这样，页面的顺序会更清楚：用户可以把什么工作交给 Maka，它怎样处理这些工作，以及有哪些证据支持这些主张。

</details>

GitHub link: https://github.com/apache/maka/discussions/5031#discussioncomment-18368877

----
This is an automatically sent email for dev@maka.apache.org.
To unsubscribe, please send an email to: dev-unsubscribe@maka.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maka.apache.org
For additional commands, e-mail: dev-help@maka.apache.org

Re: [D] [DISCUSS] Make Maka easier to understand: benchmark-first homepage and a clearer README [maka]

Posted by "Astro-Han (via GitHub)" <gi...@apache.org>.

GitHub user Astro-Han edited a discussion: [DISCUSS] Make Maka easier to understand: benchmark-first homepage and a clearer README

Follow-up to #4307, with a concrete homepage prototype for feedback.

## The problem: a newcomer should understand Maka before understanding our architecture

A useful point raised in our community discussion was: when evaluating an unfamiliar agent or ADE, he visits its website to quickly understand what it is, what it can do, and whether it fits his work. The current homepage does not make that clear enough. We also discussed how the README's abstract language makes the same first encounter harder.

## Proposal: lead with evidence, then show the product

The attached Chinese-language prototype explores four sections:

## Evaluation-driven evolution, beyond one ranking

## What changes in the README?

## Design and implementation direction

## Feedback requested

---

## 中文说明

这是 #4307 的一个具体方案补充，想结合长图请大家一起讨论。

社区讨论中提到一个很重要的用户视角：面对一个不熟悉的 Agent / ADE，通常先看官网，希望快速知道“这是什么、有哪些核心能力、是不是自己需要的”。目前官网还不能很好地回答这些问题；我们也认为 README 的表达偏抽象，要求读者先理解理念，才看得到产品。

README 则建议先给清楚的产品定义、产品图、上手入口和评测链接，再展开架构。官网和 README 应说同一种容易理解的语言。

AI assistance: Codex helped inspect the templates and reports, implement the prototype, capture the screenshot, and draft this discussion.

GitHub link: https://github.com/apache/maka/discussions/5031

----
This is an automatically sent email for dev@maka.apache.org.
To unsubscribe, please send an email to: dev-unsubscribe@maka.apache.org

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maka.apache.org
For additional commands, e-mail: dev-help@maka.apache.org

Re: [D] [DISCUSS] Make Maka easier to understand: benchmark-first homepage and a clearer README [maka]

Posted by "Sun-GLiang (via GitHub)" <gi...@apache.org>.

GitHub user Sun-GLiang edited a comment on the discussion: [DISCUSS] Make Maka easier to understand: benchmark-first homepage and a clearer README

@Astro-Han @liuxiaocs7 I support making Maka more concrete and easier to understand. On the homepage sequence, I lean toward **a compelling product demonstration first, with evaluation results immediately below**.

My working assumption is that **Maka’s current potential users** are primarily developers and people already familiar with agents. But familiarity does not necessarily make a benchmark table the most engaging first impression. The hero can create interest; the evaluations can then provide evidence for trying Maka. This preserves @Astro-Han’s emphasis on evaluation while following @liuxiaocs7’s suggestion to show the product first.

One way to connect these ideas could be to build the demonstration around [Log Is the Runtime](https://github.com/apache/maka/blob/main/docs/blogs/log-is-the-runtime.md), making that design visible through a real task before introducing the architectural term.

For example, a dynamic DAG could show work unfolding in parallel, with the **main Session’s participation** visible throughout: it submits an initial plan, yields while child Sessions execute, reads committed results at checkpoints, and decides what to arrange next before reviewing and summarizing the outcome. The main Session makes those decisions, the scheduler advances eligible work, and the execution records provide the evidence behind the story.

The interaction could let visitors select a task node to inspect its recorded activity or result, then see how that result informed the main Session’s next decision. This would give the animation a concrete purpose: connecting **decisions, execution, and outcomes**, rather than simply showing nodes changing status.

@liuxiaocs7 To address your concern about idealized demos, this could be based on a reproducible run and paired with the actual product output. The website visualization should be clearly distinguished from an existing client interface. The exact task and visual treatment still need exploration.

The sequence I have in mind is:

1. **Hero:** an engaging task-to-outcome demonstration, clear positioning, and a way to try Maka.
2. **Immediately below:** readable evaluation results, with comparison conditions and full report links.
3. **Further down:** selected design explanations, including Log Is the Runtime, linked to the existing documentation and blogs.

I consider the existing documentation sufficient for users who ask AI to explain Maka, so I would keep this redesign focused on people visiting the website.

@Astro-Han Would this preserve the evaluation-driven story while giving the first screen a stronger product focus? @liuxiaocs7 Does grounding the interaction in a real run address your concern—and which task would best show the connection between the main Session’s decisions and a useful outcome?

<details>
<summary>简体中文</summary>

@Astro-Han @liuxiaocs7 我支持让 Maka 更具体、更容易理解的方向。在官网的内容顺序上，我更倾向于：**先用有吸引力的产品演示作为首屏，紧接着展示评测结果。**

我的基本判断是，**Maka 目前的潜在用户**主要是开发者和已经熟悉 Agent 的人。但熟悉 Agent，并不意味着评测表格就是最有吸引力的第一眼内容。首屏可以先激发兴趣，评测随后提供值得尝试的依据。这样既保留了 @Astro-Han 对评测的重视，也呼应了 @liuxiaocs7 关于产品优先的建议。

连接这两种思路的一种方式，是围绕 [Log Is the Runtime](https://github.com/apache/maka/blob/main/docs/blogs/log-is-the-runtime.zh-CN.md) 展开演示：先让访客通过一个真实任务看到这项设计的价值，再介绍架构术语。

例如，可以用动态 DAG 展示工作如何并行展开，同时让**主 Session 的参与**贯穿整个过程：提交初始计划，在子 Sessions 执行时让出本轮，在检查点读取已提交的结果，决定下一步安排，最后检查并汇总成果。主 Session 负责判断和安排，调度器推进满足条件的工作，执行记录则提供支撑这段叙事的事实依据。

交互上，可以让访客选择一个任务节点，查看相关执行记录或结果，再看到这个结果如何成为主 Session 下一步决定的依据。这样，动画就有了具体目的：把**决定、执行与成果**联系起来，而不只是展示节点切换状态。

@liuxiaocs7 对于您提出的理想化演示问题，可以依据一次可复现的执行制作可视化，并搭配实际产品产出。同时明确区分官网可视化与现有客户端界面。具体任务和视觉表现仍需要进一步探索。

我设想的顺序是：

1. **首屏：** 有吸引力地展示从任务到成果的过程，配合清晰定位和试用入口。
2. **紧接下一屏：** 展示易读的评测结果，保留比较条件和完整报告链接。
3. **后续内容：** 选择性地展开设计说明，包括 Log Is the Runtime，链接已有文档和博客。

对于通过 AI 了解 Maka 的用户，我认为现有文档已经足够。因此，这次改版可以集中关注亲自访问官网的用户体验。

@Astro-Han 这样的安排是否能保留“评测驱动”的叙事，同时让首屏更聚焦产品？@liuxiaocs7 以真实执行作为交互依据，是否能回应您对演示真实性的顾虑？哪个任务最能展示主 Session 的决定与有价值的最终成果之间的联系？

</details>


GitHub link: https://github.com/apache/maka/discussions/5031#discussioncomment-18368340

----
This is an automatically sent email for dev@maka.apache.org.
To unsubscribe, please send an email to: dev-unsubscribe@maka.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maka.apache.org
For additional commands, e-mail: dev-help@maka.apache.org

Re: [D] [DISCUSS] Make Maka easier to understand: benchmark-first homepage and a clearer README [maka]

Posted by "Sun-GLiang (via GitHub)" <gi...@apache.org>.

GitHub user Sun-GLiang deleted a comment on the discussion: [DISCUSS] Make Maka easier to understand: benchmark-first homepage and a clearer README

@Astro-Han @liuxiaocs7 I support making Maka more concrete and easier to understand. On the homepage sequence, I lean toward **a compelling product demonstration first, with evaluation results immediately below**.

My working assumption is that **Maka’s current potential users** are primarily developers and people already familiar with agents. But familiarity does not necessarily make a benchmark table the most engaging first impression. The hero can create interest; the evaluations can then provide evidence for trying Maka. This preserves @Astro-Han’s emphasis on evaluation while following @liuxiaocs7’s suggestion to show the product first.

One way to connect these ideas could be to build the demonstration around [Log Is the Runtime](https://github.com/apache/maka/blob/main/docs/blogs/log-is-the-runtime.md), making that design visible through a real task before introducing the architectural term.

For example, a dynamic DAG could show work unfolding in parallel, with the **main Session’s participation** visible throughout: it submits an initial plan, yields while child Sessions execute, reads committed results at checkpoints, and decides what to arrange next before reviewing and summarizing the outcome. The main Session makes those decisions, the scheduler advances eligible work, and the execution records provide the evidence behind the story.

The interaction could let visitors select a task node to inspect its recorded activity or result, then see how that result informed the main Session’s next decision. This would give the animation a concrete purpose: connecting **decisions, execution, and outcomes**, rather than simply showing nodes changing status.

@liuxiaocs7 To address your concern about idealized demos, this could be based on a reproducible run and paired with the actual product output. The website visualization should be clearly distinguished from an existing client interface. The exact task and visual treatment still need exploration.

The sequence I have in mind is:

1. **Hero:** an engaging task-to-outcome demonstration, clear positioning, and a way to try Maka.
2. **Immediately below:** readable evaluation results, with comparison conditions and full report links.
3. **Further down:** selected design explanations, including Log Is the Runtime, linked to the existing documentation and blogs.

I consider the existing documentation sufficient for users who ask AI to explain Maka, so I would keep this redesign focused on people visiting the website.

@Astro-Han Would this preserve the evaluation-driven story while giving the first screen a stronger product focus? @liuxiaocs7 Does grounding the interaction in a real run address your concern—and which task would best show the connection between the main Session’s decisions and a useful outcome?

<details>
<summary>简体中文</summary>

@Astro-Han @liuxiaocs7 我支持让 Maka 更具体、更容易理解的方向。在官网的内容顺序上，我更倾向于：**先用有吸引力的产品演示作为首屏，紧接着展示评测结果。**

我的基本判断是，**Maka 目前的潜在用户**主要是开发者和已经熟悉 Agent 的人。但熟悉 Agent，并不意味着评测表格就是最有吸引力的第一眼内容。首屏可以先激发兴趣，评测随后提供值得尝试的依据。这样既保留了 @Astro-Han 对评测的重视，也呼应了 @liuxiaocs7 关于产品优先的建议。

连接这两种思路的一种方式，是围绕 [Log Is the Runtime](https://github.com/apache/maka/blob/main/docs/blogs/log-is-the-runtime.zh-CN.md) 展开演示：先让访客通过一个真实任务看到这项设计的价值，再介绍架构术语。

例如，可以用动态 DAG 展示工作如何并行展开，同时让**主 Session 的参与**贯穿整个过程：提交初始计划，在子 Sessions 执行时让出本轮，在检查点读取已提交的结果，决定下一步安排，最后检查并汇总成果。主 Session 负责判断和安排，调度器推进满足条件的工作，执行记录则提供支撑这段叙事的事实依据。

交互上，可以让访客选择一个任务节点，查看相关执行记录或结果，再看到这个结果如何成为主 Session 下一步决定的依据。这样，动画就有了具体目的：把**决定、执行与成果**联系起来，而不只是展示节点切换状态。

@liuxiaocs7 对于您提出的理想化演示问题，可以依据一次可复现的执行制作可视化，并搭配实际产品产出。同时明确区分官网可视化与现有客户端界面。具体任务和视觉表现仍需要进一步探索。

我设想的顺序是：

1. **首屏：** 有吸引力地展示从任务到成果的过程，配合清晰定位和试用入口。
2. **紧接下一屏：** 展示易读的评测结果，保留比较条件和完整报告链接。
3. **后续内容：** 选择性地展开设计说明，包括 Log Is the Runtime，链接已有文档和博客。

对于通过 AI 了解 Maka 的用户，我认为现有文档已经足够。因此，这次改版可以集中关注亲自访问官网的用户体验。

@Astro-Han 这样的安排是否能保留“评测驱动”的叙事，同时让首屏更聚焦产品？@liuxiaocs7 以真实执行作为交互依据，是否能回应您对演示真实性的顾虑？哪个任务最能展示主 Session 的决定与有价值的最终成果之间的联系？

</details>


GitHub link: https://github.com/apache/maka/discussions/5031#discussioncomment-18368340

----
This is an automatically sent email for dev@maka.apache.org.
To unsubscribe, please send an email to: dev-unsubscribe@maka.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maka.apache.org
For additional commands, e-mail: dev-help@maka.apache.org

Re: [D] [DISCUSS] Make Maka easier to understand: benchmark-first homepage and a clearer README [maka]

Posted by "Astro-Han (via GitHub)" <gi...@apache.org>.

GitHub user Astro-Han edited a discussion: [DISCUSS] Make Maka easier to understand: benchmark-first homepage and a clearer README

Follow-up to #4307, with a concrete homepage prototype for feedback.

## The problem: a newcomer should understand Maka before understanding our architecture

## Proposal: lead with evidence, then show the product

The attached English-language prototype explores four sections:

## Evaluation-driven evolution, beyond one ranking

## What changes in the README?

## Design and implementation direction

## Feedback requested

AI assistance: Codex helped inspect the templates and reports, implement the prototype, capture the screenshot, and draft this discussion.

<details>
<summary>简体中文（含中文界面长图）</summary>

这是 #4307 的一个具体方案补充，想结合长图请大家一起讨论。

README 则建议先给清楚的产品定义、产品图、上手入口和评测链接，再展开架构。官网和 README 应说同一种容易理解的语言。

</details>

GitHub link: https://github.com/apache/maka/discussions/5031

----
This is an automatically sent email for dev@maka.apache.org.
To unsubscribe, please send an email to: dev-unsubscribe@maka.apache.org

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maka.apache.org
For additional commands, e-mail: dev-help@maka.apache.org