docs: compress README demo GIFs

The section opened with the fixed 18K/12K thresholds it replaced and
justified the uncapped compaction count by the ceiling that came before
it. A reader evaluating Orkas needs the current design, not its history.

Keeps every current-state fact: the top-down derivation, the trigger
shares as the only tunable surface, the floor-share fuse, no ceiling on
successful passes, and the three guards that bound wasted work.

Co-Authored-By: Claude Opus 5 <[email protected]>

README.md

@@ -1,37 +1,70 @@
 # Orkas
 
-**An open-source, local-first AI workforce for complex work.**
+**Command a team of AI agents from one desktop chat — not one chatbot.**
 
-Orkas is an open-source, local-first AI workforce. A super-powered **Commander** coordinates specialist agents to complete complex work together. It runs as a desktop app on macOS, Windows, and Linux; your conversations, files, agent configs, and model keys stay local, and model calls go straight to your provider.
+Orkas is an open-source, local-first multi-agent desktop app. Describe a goal; its **Commander** plans the work, handles the general parts itself, and coordinates specialist agents in parallel or in sequence. **Nine specialist agents ship with the app**, ready the moment you launch it, out of 30 in the marketplace. Bring your own model keys — Claude · OpenAI · Gemini · DeepSeek · Kimi · GLM · Qwen · MiniMax · Doubao. macOS · Windows · Linux.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
 [![Stars](https://img.shields.io/github/stars/Orkas-AI/Orkas?style=social)](https://github.com/Orkas-AI/Orkas/stargazers)
+[![Release](https://img.shields.io/github/v/release/Orkas-AI/Orkas?color=blue)](https://github.com/Orkas-AI/Orkas/releases)
 [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-blue)](https://orkas.ai?source=gh-orkas)
 [![Download](https://img.shields.io/badge/download-orkas.ai-black)](https://orkas.ai?source=gh-orkas)
 [![X: @leochenpm](https://img.shields.io/badge/X-%40leochenpm-black?logo=x)](https://x.com/leochenpm)
 
 [English](./README.md) · [简体中文](./README.zh-CN.md)
 
-![Orkas demo](./resources/app-ui/demo.gif)
+---
 
-> One super-powered Commander turns your goal into an executable path, does the general work itself, and coordinates specialist agents when the job needs a team. No flowcharts, no orchestration code. Your conversations, files, and API keys never leave your machine.
+**You:** *"Research the top 5 competitors, write it up, and turn it into a deck."*
+
+**Orkas:** the Commander breaks the goal into steps and runs them across specialists — **DeepResearcher** gathers and verifies the sources, **ContentWriter** drafts the report, **PptMaker** builds the slides. One chat, one shared plan, finished files on your disk.
+
+![Orkas demo: the Commander turns a goal into a step-by-step plan, dispatches it to specialist agents, and delivers the finished file](./resources/app-ui/demo-en.gif)
 
 ---
 
-## What is Orkas?
+## Agents that ship with the app
 
-- **Open-source, local-first AI workforce** — a desktop GUI where you direct a coordinated workforce of specialist AI agents through one chat. Not a single chatbot, not a code framework, not a hosted SaaS.
-- **A super-powered Commander** — the Commander understands context, breaks down goals, chooses the right agents, skills, connectors, and tools, and directly handles general analysis, writing, research, file work, and automation when no specialist is a better fit.
-- **Specialist agents that work together** — agents can run in parallel or in sequence, each with focused skills, memory, and task context, so complex work can move across coding, research, data, video, and slides.
-- **Open-source ecosystem, locally orchestrated** — plug in external CLI coding agents (Claude Code, Codex, OpenCode, Cline) and onboard open-source projects like HyperFrames as local tools, all coordinated by the same Commander.
+Installed and ready the first time you launch Orkas — each with its own skills, memory, and tools.
+
+| Agent | What it does |
+| --- | --- |
+| **DeepResearcher** | Evidence-grounded research — plans the investigation, verifies sources, flags contradictions, ships an auditable report with citations |
+| **ContentWriter** | Turns a goal, source material, or a rough draft into publish-ready posts, articles, newsletters, and case studies |
+| **PptMaker** | Turns a topic, outline, or document into an attractive, editable, reviewable PPTX deck |
+| **ProductDeveloper** | Repo-aware engineering — implement a PRD, fix bugs, refactor, review code, with verifiable results |
+| **OfficeWorker** | Create, edit, check, and deliver Word / Excel / PowerPoint / PDF files, one at a time or in batches |
+| **VideoStudio** | Make and edit video — narration, AI presenters, captions and dubbing, highlight clips, localization |
+| **ImageStudio** | Posters, covers, social images, infographics — HTML/CSS/SVG first, image models when the shot needs them |
+| **UIDesigner** | Product goals, PRDs, screenshots, or Figma material into editable, HTML-first UI deliverables |
+| **SeoGeoAgent** | Give it a URL — technical audit, content quality, Core Web Vitals, GEO citability, health score, ranked fix list |
+
+**More on the built-in agents →** [orkas.ai/agents](https://orkas.ai/agents/?source=gh-orkas) · **Browse all 30 →** [agent marketplace](https://orkas.ai/views/marketplace/gs/agents/?source=gh-orkas) · or just describe what you need and the Commander builds a custom agent for you.
+
+---
+
+## Why Orkas
+
+- **A super-powered Commander** — understands context, breaks down goals, chooses the right agents, skills, connectors, and tools, and directly handles analysis, writing, research, file work, and automation when no specialist is a better fit.
+- **Drives the open-source ecosystem** — plug in external CLI coding agents (Claude Code, Codex, OpenCode, Cline) and onboard open-source projects like HyperFrames as local tools, all coordinated by the same Commander.
 - **Local-first by design** — conversations, files, API keys, knowledge bases, and custom agents all stay on your disk. Model calls go straight from your machine to the provider — never through Orkas servers.
-- **Bring your own LLM keys** — plug in Claude, OpenAI, Gemini, DeepSeek, Kimi, GLM, Qwen, MiniMax, or Doubao. Mix providers across agents. No vendor lock-in.
-- **Self-evolving workforce** — each agent has its own private skills and memory, and improves through reflection after each task.
+- **No vendor lock-in** — mix providers across agents: one on Claude, another on DeepSeek, another on a local endpoint.
+- **Agents that get better** — each agent has its own private skills and memory, and improves through reflection after each task.
 
 > ⭐ If Orkas is useful to you, a star helps more people find the project.
 
 ---
 
+## Download
+
+Packaged installers for macOS and Windows. Linux runs from source today — see [Quick start](#quick-start).
+
+- **macOS Apple Silicon** → [Orkas-mac-arm64.dmg](https://orkas.ai/download/?source=gh-orkas&entry_point=github_readme&os=mac&arch=arm64&download=1)
+- **macOS Intel** → [Orkas-mac-x64.dmg](https://orkas.ai/download/?source=gh-orkas&entry_point=github_readme&os=mac&arch=x64&download=1)
+- **Windows x64** → [Orkas-Setup.exe](https://orkas.ai/download/?source=gh-orkas&entry_point=github_readme&os=win&download=1)
+
+---
+
 ## What can you build with it?
 
 - **Automate recurring reports & market research** — a specialist agent gathers, summarizes, and ships a weekly report.
@@ -43,24 +76,17 @@ Orkas is an open-source, local-first AI workforce. A super-powered **Commander**
 
 ---
 
-## Download
-
-- **Get the app** → [orkas.ai](https://orkas.ai?source=gh-orkas) (macOS · Windows installers)
-- **Run from source** → see [Quick start](#quick-start) below (currently required on Linux)
-
----
-
 ## How Orkas compares
 
 | Tool | What it is | How Orkas differs |
 | --- | --- | --- |
-| **LangChain** | A developer framework/library for building LLM apps and agents — code-first, embedded in your own Python/JS app. | Orkas is a local-first AI workforce you direct through chat, not by writing orchestration code. Data and keys stay local by default. |
+| **LangChain** | A developer framework/library for building LLM apps and agents — code-first, embedded in your own Python/JS app. | Orkas is a local-first multi-agent desktop app you direct through chat, not by writing orchestration code. Data and keys stay local by default. |
 | **CrewAI** | A Python framework for orchestrating role-playing autonomous agents — you define crews and agents in code. | Orkas brings multi-agent orchestration into a desktop app, with **local-first storage** and per-agent self-evolution built in. |
 | **Cloud agent platforms** (SaaS orchestrators) | Server-hosted; conversations, files, and API keys live on the vendor's infrastructure. | Orkas is **local-first**: everything stays on your machine, and model API calls go straight to the provider — never archived by Orkas. |
-| **OpenClaw** | A single always-on personal assistant reaching you across messaging channels. | Orkas gives you a local-first AI workforce: the Commander coordinates specialist agents from one desktop chat, and OpenClaw plugs in as an Orkas CLI backend. |
-| **Hermes-Agent** | Nous Research's self-improving personal agent (TUI + multi-channel gateway). | Orkas is a desktop GUI for a local-first AI workforce, with per-agent private skills and meta-cognition — and Hermes-Agent plugs in as an Orkas CLI backend. |
+| **OpenClaw** | A single always-on personal assistant reaching you across messaging channels. | Orkas gives you a team rather than one assistant: the Commander coordinates specialist agents from one desktop chat, and OpenClaw plugs in as an Orkas CLI backend. |
+| **Hermes-Agent** | Nous Research's self-improving personal agent (TUI + multi-channel gateway). | Orkas is a local-first multi-agent desktop app, with per-agent private skills and meta-cognition — and Hermes-Agent plugs in as an Orkas CLI backend. |
 
-**Orkas is for you if** you want a local-first AI workforce (not one assistant), a desktop GUI with file drop-in and visual agent management, and your data, keys, and agents on your own disk rather than a vendor cloud.
+**Orkas is for you if** you want a team of agents rather than one assistant, a desktop GUI with file drop-in and visual agent management, and your data, keys, and agents on your own disk rather than a vendor cloud.
 
 **Not for you if** you just want a single all-purpose chatbot, a fully hosted/cloud team where your data lives on a vendor's servers, or a pure code library to embed in your own app.
 
@@ -71,37 +97,40 @@ Orkas is an open-source, local-first AI workforce. A super-powered **Commander**
 ## FAQ
 
 **What is Orkas?**
-Orkas is an open-source, local-first AI workforce. A super-powered Commander coordinates specialist agents to complete complex work together — not a single chatbot, not a code framework, not a hosted SaaS.
+Orkas is an open-source, local-first multi-agent desktop app. A super-powered Commander plans your goal and coordinates specialist agents to complete it together — nine of them ship with the app. Not a single chatbot, not a code framework, not a hosted SaaS.
 
 **Is Orkas a local LLM?**
 No. Orkas runs on your machine but calls the models you choose through your own API keys (or a local model endpoint). It orchestrates agents and tools — it is not itself a model.
 
+**Can I use local models like Ollama or LM Studio?**
+Yes. Add them under **Settings → AI Providers → Custom (OpenAI-compatible)** and point the base URL at your local endpoint. You can run one agent on a local model and another on a hosted one in the same chat.
+
 **Where are my API keys and data stored?**
 On your disk. Conversations, files, knowledge bases, agents, and keys stay local; model calls go straight from your machine to the provider and are never proxied or archived by Orkas.
 
 **Does Orkas work offline?**
 The app is fully offline-capable — only the model calls need network. Point agents at a local model endpoint and you can run without the cloud.
 
+**Do I need an Orkas account?**
+The packaged desktop app asks you to sign in when you first launch it. The source build in this repository has no account layer at all — it boots straight into the app. Either way your model keys are your own and stay on your machine.
+
 **Can Orkas drive Claude Code and other CLI coding agents?**
 Yes. Beyond its own Commander and specialist agents, Orkas can drive external CLI coding agents — Claude Code, Codex, OpenCode, Cline — as local subprocesses, and onboard open-source projects like HyperFrames, all directed from the same chat.
 
 **How is Orkas different from Claude Desktop / CrewAI / LangChain?**
-Claude Desktop is a single assistant; CrewAI and LangChain are code-first frameworks. Orkas is a local-first AI workforce: the Commander coordinates specialist agents, keeps data and keys local, and gives each agent its own private skills and memory. See the [full comparisons](https://orkas.ai/compare/orkas-vs-langchain?source=gh-orkas).
+Claude Desktop is a single assistant; CrewAI and LangChain are code-first frameworks. Orkas is a local-first multi-agent desktop app: the Commander coordinates specialist agents, keeps data and keys local, and gives each agent its own private skills and memory. See the [full comparisons](https://orkas.ai/compare/orkas-vs-langchain?source=gh-orkas).
+
+**Which platforms does Orkas support?**
+macOS (Apple Silicon and Intel) and Windows 10+ have packaged installers. Linux runs from source today — same app, no installer yet. The source build needs Node 20+ and Python 3.
 
 **Is Orkas free and open source?**
-Yes — MIT licensed. Bring your own model keys; you only ever pay your model providers.
+Yes — the app is MIT licensed and free to use. Bring your own model keys and you pay only your model providers; Orkas never takes a cut. Optionally, the desktop app also offers a built-in **Orkas model** for people who don't want to manage API keys — that one is billed by Orkas in credits (membership or credit packs). It is entirely opt-in, and every other feature works on your own keys. [Pricing →](https://orkas.ai/pricing/?source=gh-orkas)
 
 ---
 
 ## Quick start
 
-Packaged installers are currently available for macOS and Windows. Linux users should follow the source instructions below.
-
-- **macOS Apple Silicon** -> [Orkas-mac-arm64.dmg](https://orkas.ai/download/?source=gh-orkas&entry_point=github_readme&os=mac&arch=arm64&download=1)
-- **macOS Intel** -> [Orkas-mac-x64.dmg](https://orkas.ai/download/?source=gh-orkas&entry_point=github_readme&os=mac&arch=x64&download=1)
-- **Windows x64** -> [Orkas-Setup.exe](https://orkas.ai/download/?source=gh-orkas&entry_point=github_readme&os=win&download=1)
-
-To run from source:
+Want a packaged installer instead? See [Download](#download) above. To run from source — currently the way to run Orkas on Linux:
 
 **Requirements**: Node 20+ · Python 3 · macOS / Windows 10+ / recent Linux
 
@@ -118,7 +147,7 @@ run.cmd            # Windows
 
 ## Screenshots
 
-![Orkas home screen](./resources/app-ui/home-en.jpg)
+![Orkas home screen: sidebar with Commander, Agents, Skills, Connectors and Library, and a task box with quick-start templates](./resources/app-ui/home-en.jpg)
 
 ---
 
@@ -126,28 +155,57 @@ run.cmd            # Windows
 
 > Full design and hard constraints → [`CLAUDE.md`](./CLAUDE.md)
 
-### Group chat: visibility slicing + a single scheduling primitive
+### Three dispatch verbs, and the rule for choosing between them
 
-In one chat there's the Commander, N specialist agents, and you — but **each agent does not see the same conversation**.
+The Commander is the only actor holding dispatch tools — workers and agents have none. Which verb it picks decides who the user hears from and whether the Commander stays in the loop:
 
-- **Visibility slicing** — the main conversation is one full jsonl; each agent only gets a slice (`from==me ∨ to∋me ∨ mentions∋me`). A worker never reads the full main conversation — saves tokens and prevents private context from leaking across agents.
-- **One scheduling primitive** — every dispatch (the Commander's `dispatch_to`, the user's `@`, plan steps) funnels into the same `enqueue` primitive. No parallel routing paths.
-- **Shared plan** — when agents collaborate, the Commander writes progress into one `plan.md`, visible to every member.
+| Verb | User sees the agent's reply | Result returns to the Commander | Commander's turn |
+| --- | --- | --- | --- |
+| `hand_off_to({ to, message })` | yes | no | ends — the agent's reply stands as the answer |
+| `dispatch_to({ to, message })` | yes | yes | continues with a named next step |
+| `run_worker({ to, task })` | no — private input | yes | continues |
 
-### Agent dispatch: structured channels, not `@` in prose
+The Commander has to name its concrete next action *before* it may choose `dispatch_to`; if all that remains is restating the agent's reply, the rule forces `hand_off_to`. That single constraint is what stops a multi-agent chat from ending in a redundant re-summary of what you already read. Emitting several `run_worker` calls in one response runs them concurrently.
 
-- **Structured dispatch** — Commander-to-agent dispatches go through the `dispatch_to({to, message})` tool call; `@` in prose is not treated as a dispatch signal (the user's `@` is still recognized — UX unchanged).
-- **Deferred wake-up** — a `dispatch_to` only stages; the recipient wakes only after the Commander's turn finishes, preventing premature execution.
-- **Turn-based safety stop** — the runaway guard counts turns (`MAX_WORKER_TURNS=100`), not wall-clock time, so a slow-but-progressing LLM isn't killed.
+### One runtime, bounded fan-out
 
-### Self-evolution: `meta/` + self-managed skills
+Each conversation has a single FIFO runtime, and top-level turns run through it serially; parallelism happens *inside* a turn as nested in-process dispatch ([`bus.ts`](./src/main/features/group_chat/bus.ts)). Two separate semaphores bound it — `globalSlots = 10` across all users, and `dispatchSlots = 4` for nested dispatches (`ORKAS_MAX_DISPATCH_CONCURRENCY`).
 
-Each agent maintains, in its own directory:
+Nested runs deliberately skip `globalSlots`: the parent turn already holds a slot, so a nested acquire would deadlock as parent-waits-on-child. That shortcut is safe only because dispatch tools belong to the Commander alone, so the semaphore is never acquired re-entrantly — the deadlock is ruled out by construction, not by a timeout.
 
-- **`meta/COMPETENCE.md`** — what it's good / not good at.
-- **`meta/LEARNING_STRATEGIES.md`** — methods that have worked for it.
+### Context budget: derived from the model, not a fixed number
 
-After each task the agent reflects and updates these; on the next task `meta/` is fed back into the system prompt, so experience shapes the next run. Via the `skill_manage` tool an agent can also crystallize "how I solved X" into a **private** skill, reused directly next time.
+Every compaction threshold is derived from the model in use, so one policy fits a 32K window and a 1M one alike ([`context-budget.ts`](./src/core-agent/src/agent/context-budget.ts)):
+
+```
+usableInput   = contextWindow − maxOutputTokens − safety
+messageBudget = max(usableInput × 0.2, usableInput − systemPrompt − toolDefs)
+```
+
+Every trigger is a share of `messageBudget` — 0.3 for the in-turn layer, 0.2 for cross-turn history, 0.1 for one round's inline tool results — and everything else derives from its trigger, so the shares are the only tunable surface. They sum to well under 1, leaving room for injected runtime state and for the growth that happens between a trigger firing and its summary landing. The `max` is a fuse: when a large tool set would otherwise swallow the window, messages keep a floor share instead of computing a negative budget.
+
+A run compacts as many times as it needs to — there is deliberately **no ceiling on successful passes**. What is bounded is wasted work instead: a fingerprint check refuses to compact identical state twice, a minimum-savings threshold rejects passes that would free too little, and three consecutive failures stop LLM-backed compaction.
+
+Summarization loses detail, so what an agent must not forget is kept as structure rather than prose. A workspace ledger of files written, files read, and commands run survives compaction ([`workspace-state.ts`](./src/core-agent/src/agent/workspace-state.ts)), and a spin detector — two or more compactions plus 75% of the tool budget consumed — nudges the agent once to re-anchor on that ledger instead of re-deriving work it just summarized away.
+
+### Memory: hybrid retrieval over a local index
+
+A knowledge base is a SQLite index built on your machine — FTS5 for full text, stored vectors for similarity ([`memory/`](./src/core-agent/src/memory)). Documents are chunked at 512 lines with 64 lines of overlap; a query runs both ways and the two ranked lists merge by reciprocal rank fusion, weighted 0.7 vector to 0.3 keyword. Agents reach it through `memory_search` and `memory_read`, over stored documents and past sessions alike.
+
+Embeddings are computed **on device** by a bundled ONNX model (`bge-small-zh-v1.5`, ~95 MB, fetched once during install), so indexing a knowledge base sends nothing anywhere. Cloud embedding providers — OpenAI, Gemini, Voyage, Mistral — are available if you prefer them.
+
+### Four independent runaway guards
+
+- **Turn ceiling** — `MAX_WORKER_TURNS = 100` counts turns, not wall-clock time, so a slow-but-progressing model isn't killed.
+- **Per-turn tool rounds** — Commander 120, named agent 100, ephemeral worker the schema default ([`actor-budgets.ts`](./src/main/features/group_chat/actor-budgets.ts)), pinned by unit tests so they can't silently drift.
+- **`loop_detection`** — nudges the model after N consecutive identical or near-duplicate tool calls.
+- **Tool-idle watchdog** — for turns that stall rather than loop.
+
+### Self-evolution: signal-triggered, not after every task
+
+Each agent keeps `meta/COMPETENCE.md` (what it is and isn't good at) and `meta/LEARNING_STRATEGIES.md` (methods that have worked for it), both fed back into its system prompt on the next run.
+
+Reflection is not a fixed counter. A weighted trigger scores six signals — `error_recovery`, `user_correction`, `complexity`, `known_weakness`, `weakness_succeeded`, `skill_ineffective` — and reviews only when the total clears a threshold, generating the review prompt from whichever signal dominated ([`metacognition.ts`](./src/core-agent/src/evolution/metacognition.ts)). Through `skill_manage` an agent can also crystallize "how I solved X" into a **private** `SKILL.md` that it can use from the next turn on.
 
 ---
 

README.zh-CN.md

@@ -1,37 +1,70 @@
 # Orkas
 
-**开源、本地优先的 AI 工作团队，用来协同完成复杂工作。**
+**在一个桌面对话里指挥一支 AI 智能体团队 —— 而不是单个聊天机器人。**
 
-Orkas 是一个开源、本地优先的 AI 工作团队。一个超强**指挥官**会协调多个专业智能体，共同完成复杂工作。它是运行在 macOS、Windows、Linux 上的桌面应用；你的对话、文件、智能体配置和模型 key 默认留在本机，模型调用直连你选择的服务商。
+Orkas 是一个开源、本地优先的多智能体桌面应用。你描述目标，**指挥官**规划路径、亲自完成通用部分，并调度专业智能体并行或串行执行。**9 个专业智能体随应用内置**，启动即可用，marketplace 中共有 30 个。自带模型 key —— Claude · OpenAI · Gemini · DeepSeek · Kimi · GLM · Qwen · MiniMax · Doubao。支持 macOS · Windows · Linux。
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
 [![Stars](https://img.shields.io/github/stars/Orkas-AI/Orkas?style=social)](https://github.com/Orkas-AI/Orkas/stargazers)
+[![Release](https://img.shields.io/github/v/release/Orkas-AI/Orkas?color=blue)](https://github.com/Orkas-AI/Orkas/releases)
 [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-blue)](https://orkas.ai?source=gh-orkas)
 [![Download](https://img.shields.io/badge/download-orkas.ai-black)](https://orkas.ai?source=gh-orkas)
 [![X: @leochenpm](https://img.shields.io/badge/X-%40leochenpm-black?logo=x)](https://x.com/leochenpm)
 
 [English](./README.md) · [简体中文](./README.zh-CN.md)
 
-![Orkas 演示](./resources/app-ui/demo.gif)
+---
 
-> 一个超强指挥官会把你的目标转成可执行路径，亲自处理通用工作，并在任务需要团队时协调专业智能体。无需流程图、无需编排代码。你的对话、文件和 API key 始终不离开本机。
+**你：**“调研这个领域的 5 个竞品，写成报告，再做成一份 PPT。”
+
+**Orkas：** 指挥官把目标拆成步骤，分派给专业智能体 —— **DeepResearcher** 检索并核验来源，**ContentWriter** 撰写报告，**PptMaker** 制作幻灯片。同一个对话、同一份计划，成品文件落在你的硬盘上。
+
+![Orkas 演示：指挥官把目标拆成分步计划，分派给专业智能体，并交付成品文件](./resources/app-ui/demo.gif)
 
 ---
 
-## Orkas 是什么？
+## 随应用内置的智能体
 
-- **开源、本地优先的 AI 工作团队** —— 一个桌面 GUI，让你在同一个对话里指挥多个协同工作的专业智能体。不是单个聊天机器人，不是代码框架，也不是托管 SaaS。
-- **超强指挥官** —— 指挥官理解上下文、拆解目标、选择合适的智能体、技能、连接器和工具；当没有更合适的专家时，也能直接处理分析、写作、调研、文件处理和自动化。
-- **专业智能体共同完成复杂工作** —— 智能体可以并行或串行执行，每个智能体都有自己的技能、记忆和任务上下文，复杂工作可以跨代码、研究、数据、视频和幻灯片推进。
-- **本地编排开源生态** —— 接入外部 CLI 编程智能体（Claude Code、Codex、OpenCode、Cline），并把 HyperFrames 等开源项目作为本地工具接入，全部由同一个指挥官协调。
+首次启动 Orkas 即已安装可用，每个都有自己的技能、记忆和工具。
+
+| 智能体 | 能做什么 |
+| --- | --- |
+| **DeepResearcher** | 证据型深度研究 —— 拆解问题、检索多源、核验引用、标注矛盾点，输出可复核的带引用报告 |
+| **ContentWriter** | 把一句目标、资料或草稿写成可发布内容 —— 社媒成稿、文章、newsletter、教程、案例 |
+| **PptMaker** | 把主题、提纲或文档做成好看、实用、可编辑、可复核的 PPTX |
+| **ProductDeveloper** | 仓库级研发 —— 把 PRD、issue、bug 报告落成最小代码变更、工程测试与可审计验证 |
+| **OfficeWorker** | 创建、编辑、检查并交付 Word / Excel / PowerPoint / PDF，单个或批量处理 |
+| **VideoStudio** | 做视频也剪视频 —— 解说动画、AI 口播数字人、字幕配音、高光切片、本地化 |
+| **ImageStudio** | 海报、封面、社媒图、信息图 —— 优先用 HTML/CSS/SVG 生成，需要时再调用图片模型 |
+| **UIDesigner** | 把产品目标、PRD、截图或 Figma 材料转成以 HTML 呈现、可连续修改的 UI 设计产物 |
+| **SeoGeoAgent** | 给一个 URL —— 技术审计、内容质量、核心网页指标、GEO 可引用性评分、健康分与分级行动清单 |
+
+**了解内置智能体 →** [orkas.ai/agents](https://orkas.ai/agents/?source=gh-orkas) · **浏览全部 30 个 →** [智能体 marketplace](https://orkas.ai/views/marketplace/gs/agents/?source=gh-orkas) · 或者直接描述你的需求，让指挥官为你定制一个。
+
+---
+
+## 为什么选 Orkas
+
+- **超强指挥官** —— 理解上下文、拆解目标、选择合适的智能体、技能、连接器和工具；当没有更合适的专家时，也能直接处理分析、写作、调研、文件处理和自动化。
+- **驱动开源生态** —— 接入外部 CLI 编程智能体（Claude Code、Codex、OpenCode、Cline），并把 HyperFrames 等开源项目作为本地工具接入，全部由同一个指挥官协调。
 - **本地优先设计** —— 对话、文件、API key、知识库、自定义智能体全部留在你的硬盘上。模型调用从你的机器直连服务商，绝不经过 Orkas 服务器。
-- **自带大模型 key** —— 接入 Claude、OpenAI、Gemini、DeepSeek、Kimi、GLM、Qwen、MiniMax、Doubao，不同智能体可混用不同服务商，无厂商锁定。
-- **自我进化的工作团队** —— 每个智能体拥有自己私有的技能与记忆，并在每次任务后通过复盘自我改进。
+- **无厂商锁定** —— 不同智能体可混用不同服务商：一个用 Claude，一个用 DeepSeek，一个接本地模型端点。
+- **会自我进化的智能体** —— 每个智能体拥有自己私有的技能与记忆，并在每次任务后通过复盘自我改进。
 
 > ⭐ 如果 Orkas 对你有用，点个 star 能帮助更多人发现这个项目。
 
 ---
 
+## 下载
+
+macOS 和 Windows 提供安装包。Linux 目前需从源码运行 —— 见 [快速开始](#快速开始)。
+
+- **macOS Apple 芯片** → [Orkas-mac-arm64.dmg](https://orkas.ai/download/?source=gh-orkas&entry_point=github_readme&os=mac&arch=arm64&download=1)
+- **macOS Intel** → [Orkas-mac-x64.dmg](https://orkas.ai/download/?source=gh-orkas&entry_point=github_readme&os=mac&arch=x64&download=1)
+- **Windows x64** → [Orkas-Setup.exe](https://orkas.ai/download/?source=gh-orkas&entry_point=github_readme&os=win&download=1)
+
+---
+
 ## 你能用它做什么？
 
 - **自动化周期性报告与市场调研** —— 一个专业智能体负责收集、汇总并产出每周报告。
@@ -43,24 +76,17 @@ Orkas 是一个开源、本地优先的 AI 工作团队。一个超强**指挥
 
 ---
 
-## 下载
-
-- **获取应用** → [orkas.ai](https://orkas.ai?source=gh-orkas)（macOS · Windows 安装包）
-- **从源码运行** → 见下方 [快速开始](#快速开始)（Linux 当前需使用此方式）
-
----
-
 ## Orkas 与同类工具对比
 
 | 工具 | 它是什么 | Orkas 的不同之处 |
 | --- | --- | --- |
-| **LangChain** | 面向开发者的框架/库，用于构建 LLM 应用与智能体 —— 代码优先，嵌入你自己的 Python/JS 应用中。 | Orkas 是一个通过对话指挥的本地优先 AI 工作团队，而不是靠你写编排代码。数据与 key 默认留在本地。 |
+| **LangChain** | 面向开发者的框架/库，用于构建 LLM 应用与智能体 —— 代码优先，嵌入你自己的 Python/JS 应用中。 | Orkas 是一个通过对话指挥的本地优先多智能体桌面应用，而不是靠你写编排代码。数据与 key 默认留在本地。 |
 | **CrewAI** | 一个 Python 框架，用于编排扮演角色的自治智能体 —— 你用代码定义 crew 和智能体。 | Orkas 把多智能体编排带进桌面应用，内置**本地优先存储**与每个智能体的自我进化。 |
 | **云端智能体平台**（SaaS 编排器） | 服务器托管；对话、文件、API key 都存在厂商的基础设施上。 | Orkas **本地优先**：一切留在你的机器上，模型 API 调用直连服务商 —— 绝不被 Orkas 归档。 |
-| **OpenClaw** | 一个常驻的单一个人助理，跨即时通讯渠道触达你。 | Orkas 提供本地优先的 AI 工作团队：指挥官在一个桌面对话里协调多个专业智能体，且 OpenClaw 可作为 Orkas 的 CLI 后端接入。 |
-| **Hermes-Agent** | Nous Research 的自我改进个人智能体（TUI + 多渠道网关）。 | Orkas 是面向本地优先 AI 工作团队的桌面 GUI，每个智能体拥有私有技能与元认知 —— 且 Hermes-Agent 可作为 Orkas 的 CLI 后端接入。 |
+| **OpenClaw** | 一个常驻的单一个人助理，跨即时通讯渠道触达你。 | Orkas 给你的是一支团队而非单个助理：指挥官在一个桌面对话里协调多个专业智能体，且 OpenClaw 可作为 Orkas 的 CLI 后端接入。 |
+| **Hermes-Agent** | Nous Research 的自我改进个人智能体（TUI + 多渠道网关）。 | Orkas 是一个本地优先的多智能体桌面应用，每个智能体拥有私有技能与元认知 —— 且 Hermes-Agent 可作为 Orkas 的 CLI 后端接入。 |
 
-**如果你想要的是：**一个本地优先的 AI 工作团队（而非单个助理）、一个支持拖入文件与可视化管理智能体的桌面 GUI、并希望数据/key/智能体都在自己的硬盘上而非厂商云端 —— 那么 Orkas 适合你。
+**如果你想要的是：**一支智能体团队而非单个助理、一个支持拖入文件与可视化管理智能体的桌面 GUI、并希望数据/key/智能体都在自己的硬盘上而非厂商云端 —— 那么 Orkas 适合你。
 
 **以下情况 Orkas 不适合你：**只想要一个万能单点聊天机器人、想要一个数据托管在厂商服务器上的全云端团队、或想要一个嵌入自己应用的纯代码库。
 
@@ -71,37 +97,40 @@ Orkas 是一个开源、本地优先的 AI 工作团队。一个超强**指挥
 ## 常见问题（FAQ）
 
 **Orkas 是什么？**
-Orkas 是一个开源、本地优先的 AI 工作团队。一个超强指挥官会协调多个专业智能体，共同完成复杂工作 —— 不是单个聊天机器人，不是代码框架，也不是托管 SaaS。
+Orkas 是一个开源、本地优先的多智能体桌面应用。一个超强指挥官规划你的目标，并协调多个专业智能体共同完成 —— 其中 9 个随应用内置。不是单个聊天机器人，不是代码框架，也不是托管 SaaS。
 
 **Orkas 是本地大模型吗？**
 不是。Orkas 运行在你的机器上，但通过你自己的 API key（或本地模型端点）调用你选择的模型。它编排智能体与工具，本身不是模型。
 
+**能用 Ollama、LM Studio 这类本地模型吗？**
+可以。在 **设置 → AI 服务商 → 自定义（OpenAI 兼容）** 中添加，把 base URL 指向你的本地端点即可。同一个对话里，一个智能体用本地模型、另一个用云端模型也没问题。
+
 **我的 API key 和数据存在哪里？**
 在你的硬盘上。对话、文件、知识库、智能体和 key 都留在本地；模型调用从你的机器直连服务商，绝不被 Orkas 代理或归档。
 
 **Orkas 能离线用吗？**
 应用本身可完全离线运行 —— 只有模型调用需要网络。把智能体指向本地模型端点，就能脱离云端运行。
 
+**需要注册 Orkas 账号吗？**
+安装包版本在首次启动时会要求登录。本仓库的源码版本完全没有账号模块，启动后直接进入应用。两种方式下，模型 key 都是你自己的，并且留在本机。
+
 **Orkas 能驱动 Claude Code 等 CLI 编程智能体吗？**
 能。除了自己的指挥官与专业智能体，Orkas 还能把外部 CLI 编程智能体（Claude Code、Codex、OpenCode、Cline）作为本地子进程驱动，并接入 HyperFrames 等开源项目，全部在同一个对话里指挥。
 
 **Orkas 和 Claude Desktop / CrewAI / LangChain 有什么不同？**
-Claude Desktop 是单个助理；CrewAI 和 LangChain 是代码优先的框架。Orkas 是一个本地优先 AI 工作团队：指挥官协调多个专业智能体，数据与 key 留在本地，每个智能体拥有私有技能与记忆。见[逐项对比](https://orkas.ai/compare/orkas-vs-langchain?source=gh-orkas)。
+Claude Desktop 是单个助理；CrewAI 和 LangChain 是代码优先的框架。Orkas 是一个本地优先的多智能体桌面应用：指挥官协调多个专业智能体，数据与 key 留在本地，每个智能体拥有私有技能与记忆。见[逐项对比](https://orkas.ai/compare/orkas-vs-langchain?source=gh-orkas)。
+
+**支持哪些平台？**
+macOS（Apple 芯片与 Intel）和 Windows 10+ 提供安装包。Linux 目前从源码运行 —— 功能相同，只是还没有安装包。源码运行需要 Node 20+ 与 Python 3。
 
 **Orkas 免费且开源吗？**
-是的 —— MIT 许可证。自带模型 key，你只需为你的模型服务商付费。
+是的 —— 应用本身 MIT 许可证、免费使用。自带模型 key 时，你只需为你的模型服务商付费，Orkas 不抽成。此外，桌面版还提供一个可选的内置 **Orkas 模型**，供不想自己配置 key 的用户使用 —— 这部分由 Orkas 按 credits 计费（会员或 credits 包）。它完全可选，其余所有功能用你自己的 key 即可。[价格 →](https://orkas.ai/pricing/?source=gh-orkas)
 
 ---
 
 ## 快速开始
 
-目前 macOS 和 Windows 提供安装包；Linux 用户请按照下方步骤从源码运行。
-
-- **macOS Apple 芯片** → [Orkas-mac-arm64.dmg](https://orkas.ai/download/?source=gh-orkas&entry_point=github_readme&os=mac&arch=arm64&download=1)
-- **macOS Intel** → [Orkas-mac-x64.dmg](https://orkas.ai/download/?source=gh-orkas&entry_point=github_readme&os=mac&arch=x64&download=1)
-- **Windows x64** → [Orkas-Setup.exe](https://orkas.ai/download/?source=gh-orkas&entry_point=github_readme&os=win&download=1)
-
-从源码运行：
+想直接用安装包？见上方 [下载](#下载)。以下是从源码运行的方式 —— 也是目前在 Linux 上运行 Orkas 的方式：
 
 **环境要求**：Node 20+ · Python 3 · macOS / Windows 10+ / 较新的 Linux
 
@@ -118,7 +147,7 @@ run.cmd            # Windows
 
 ## 截图
 
-![Orkas 主界面](./resources/app-ui/home-zh.jpg)
+![Orkas 主界面：左侧为指挥官、智能体、技能、连接器与资料库，中间是任务输入框与快捷模板](./resources/app-ui/home-zh.jpg)
 
 ---
 
@@ -126,28 +155,57 @@ run.cmd            # Windows
 
 > 完整设计与硬约束 → [`CLAUDE.md`](./CLAUDE.md)
 
-### 群聊：可见性切片 + 单一调度原语
+### 三个派发动词，以及选哪个的规则
 
-一个对话里有指挥官、N 个专业智能体和你 —— 但**每个智能体看到的对话并不相同**。
+指挥官是唯一持有派发工具的角色 —— worker 和智能体都没有。选哪个动词，决定了用户听谁说话、以及指挥官是否留在回合里：
 
-- **可见性切片** —— 主对话是一份完整 jsonl；每个智能体只拿到属于自己的切片（`from==me ∨ to∋me ∨ mentions∋me`）。worker 永远读不到完整主对话 —— 既省 token，又防止私有上下文在智能体间泄漏。
-- **单一调度原语** —— 每一次分派（指挥官的 `dispatch_to`、用户的 `@`、计划拆出的步骤）都汇入同一个 `enqueue` 原语，没有并行的路由路径。
-- **共享计划** —— 多智能体协作时，指挥官把进度写进同一份 `plan.md`，对每个成员可见。
+| 动词 | 用户看得到智能体的回复 | 结果回传给指挥官 | 指挥官的回合 |
+| --- | --- | --- | --- |
+| `hand_off_to({ to, message })` | 是 | 否 | 结束 —— 智能体的回复本身就是答案 |
+| `dispatch_to({ to, message })` | 是 | 是 | 继续执行一个已命名的下一步 |
+| `run_worker({ to, task })` | 否 —— 作为私有输入 | 是 | 继续 |
 
-### 智能体分派：结构化通道，而非散文里的 `@`
+指挥官必须**先**说出自己具体的下一步动作，才可以选 `dispatch_to`；如果剩下的事只是复述智能体的回复，规则就强制它改用 `hand_off_to`。正是这一条约束，让多智能体对话不会以"把你刚读过的内容再总结一遍"收尾。在同一次回复里发出多个 `run_worker` 调用，它们会并发执行。
 
-- **结构化分派** —— 指挥官与智能体之间的分派必须走 `dispatch_to({to, message})` 工具调用；散文里的 `@` 不被识别为分派信号（用户的 `@` 仍按文本识别 —— 用户体验不变）。
-- **延迟唤醒** —— 一次 `dispatch_to` 只做暂存；接收方 worker 要等指挥官当前回合结束后才被唤醒，避免过早执行。
-- **基于回合的安全停止** —— 失控保护计的是回合数（`MAX_WORKER_TURNS=100`）而非墙钟时间，因此一个慢但在推进的 LLM 不会被误杀。
+### 单一运行时，有界扇出
 
-### 自我进化：`meta/` + 自管理技能
+每个对话只有一个 FIFO 运行时，顶层回合串行通过它；并行发生在回合**内部**，以进程内嵌套派发的形式（[`bus.ts`](./src/main/features/group_chat/bus.ts)）。两个独立的信号量为它设界 —— 跨所有用户的 `globalSlots = 10`，以及用于嵌套派发的 `dispatchSlots = 4`（可用 `ORKAS_MAX_DISPATCH_CONCURRENCY` 覆盖）。
 
-每个智能体在自己的目录里维护：
+嵌套运行刻意跳过 `globalSlots`：父回合已经占着一个槽位，嵌套获取会造成"父等子"的死锁。这个捷径之所以安全，只因为派发工具专属于指挥官，信号量不可能被重入获取 —— 死锁是被构造排除的，而不是靠超时兜底。
 
-- **`meta/COMPETENCE.md`** —— 我擅长什么 / 不擅长什么。
-- **`meta/LEARNING_STRATEGIES.md`** —— 对我有效的方法。
+### 上下文预算：由模型推导，而不是写死一个数
 
-每次任务后智能体复盘并更新它们；下次任务时 `meta/` 会作为系统提示的一部分回喂进去，让经验真正影响下一次运行。通过 `skill_manage` 工具，智能体还能把"我是如何解决 X 的"结晶成一个**私有**技能，下次直接复用。
+每个压缩阈值都由当前使用的模型推导而来，因此同一套策略既适配 32K 窗口，也适配 1M 窗口（[`context-budget.ts`](./src/core-agent/src/agent/context-budget.ts)）：
+
+```
+usableInput   = 上下文窗口 − 最大输出 token − 安全余量
+messageBudget = max(usableInput × 0.2, usableInput − 系统提示 − 工具定义)
+```
+
+每个触发阈值都是 `messageBudget` 的一个份额 —— 回合内层 0.3、跨回合历史 0.2、单轮内联工具结果 0.1 —— 其余参数都由触发阈值派生，因此这几个份额是唯一的可调面。它们的总和远小于 1，留出的余量用于回灌的运行时状态，以及"触发发生到摘要落地"之间仍在继续的增长。那个 `max` 是保险丝：当工具集大到会吃掉整个窗口时，消息仍保有一个底线份额，而不是算出一个负预算。
+
+一次运行需要压缩多少次就压缩多少次 —— **成功压缩的次数刻意不设上限**。真正设界的是无效功：指纹校验拒绝对同一状态重复压缩，最小收益阈值拒绝那些释放太少的压缩，连续三次失败则停止 LLM 压缩。
+
+摘要必然丢细节，所以智能体绝不能忘的东西不交给散文承载。一份记录"写过哪些文件、读过哪些文件、跑过哪些命令"的工作台账会以结构形式挺过压缩（[`workspace-state.ts`](./src/core-agent/src/agent/workspace-state.ts)）；另有一个空转检测 —— 压缩两次以上且工具预算已消耗 75% —— 会提醒智能体一次，让它回到台账重新锚定，而不是把刚被摘要掉的工作再推导一遍。
+
+### 记忆：本地索引上的混合检索
+
+资料库是一份构建在你本机的 SQLite 索引 —— 用 FTS5 做全文、用存储的向量做相似度（[`memory/`](./src/core-agent/src/memory)）。文档按 512 行切块、块间重叠 64 行；一次查询两路并发，两个排序结果用 reciprocal rank fusion 融合，权重为向量 0.7、关键词 0.3。智能体通过 `memory_search` 与 `memory_read` 访问它，检索范围同时覆盖存入的文档和历史会话。
+
+嵌入向量**在本机计算**，由随包的 ONNX 模型完成（`bge-small-zh-v1.5`，约 95 MB，安装时下载一次），因此建立资料库索引不会把任何内容发出去。如果你更愿意用云端嵌入服务，OpenAI、Gemini、Voyage、Mistral 也都支持。
+
+### 四道互相独立的失控保护
+
+- **轮次上限** —— `MAX_WORKER_TURNS = 100` 计的是回合数而非墙钟时间，因此一个慢但在推进的模型不会被误杀。
+- **每回合工具轮数** —— 指挥官 120、具名智能体 100、临时 worker 用 schema 默认值（[`actor-budgets.ts`](./src/main/features/group_chat/actor-budgets.ts)），由单元测试钉死，不会悄悄漂移。
+- **`loop_detection`** —— 连续 N 次相同或近似重复的工具调用后提醒模型。
+- **工具空闲看门狗** —— 针对卡住而非打转的回合。
+
+### 自我进化：由信号触发，而非每次任务都做
+
+每个智能体维护 `meta/COMPETENCE.md`（我擅长什么 / 不擅长什么）和 `meta/LEARNING_STRATEGIES.md`（对我有效的方法），两者都会在下一次运行时回喂进它的系统提示。
+
+复盘不是固定计数器。一个加权触发器为六个信号打分 —— `error_recovery`、`user_correction`、`complexity`、`known_weakness`、`weakness_succeeded`、`skill_ineffective` —— 只有总分越过阈值才触发复盘，并依据占主导的那个信号生成复盘提示（[`metacognition.ts`](./src/core-agent/src/evolution/metacognition.ts)）。通过 `skill_manage`，智能体还能把"我是如何解决 X 的"结晶成一份**私有** `SKILL.md`，从下一回合起即可使用。
 
 ---
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "orkas",
-  "version": "2026.8.25",
+  "version": "2026.8.11",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "orkas",
-      "version": "2026.8.25",
+      "version": "2026.8.11",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "orkas",
-  "version": "2026.8.25",
+  "version": "2026.8.11",
   "private": true,
   "description": "Orkas desktop — Electron + Node one-piece app",
   "main": "bootstrap.cjs",

src/renderer/index.html

@@ -1691,7 +1691,6 @@
     };
   </script>
   <script src="./modules/math.js"></script>
-  <script src="./modules/sidebar-sections.js"></script>
   <script src="./modules/sidebar-resize.js"></script>
 </body>
 </html>

test/e2e/sidebar_e2e_sections.spec.ts

@@ -1,26 +0,0 @@
-import { expect, test } from './fixtures/orkas';
-
-test.describe('sidebar sections', () => {
-  test('collapses and expands Projects and Tasks from their title controls', async ({ orkas }) => {
-    if (!orkas.page) throw new Error('Orkas renderer is unavailable');
-    const page = orkas.page;
-    const projectsToggle = page.locator('#projects-section-toggle');
-    const tasksToggle = page.locator('#tasks-section-toggle');
-
-    await expect(projectsToggle).toHaveAttribute('aria-expanded', 'true');
-    await expect(tasksToggle).toHaveAttribute('aria-expanded', 'true');
-
-    await projectsToggle.locator('.sidebar-section-title').click();
-    await expect(projectsToggle).toHaveAttribute('aria-expanded', 'false');
-    await expect(page.locator('#projects-list')).toBeHidden();
-
-    await tasksToggle.locator('.sidebar-section-title').click();
-    await expect(tasksToggle).toHaveAttribute('aria-expanded', 'false');
-    await expect(page.locator('#conversation-list')).toBeHidden();
-
-    await projectsToggle.locator('.sidebar-section-title').click();
-    await tasksToggle.locator('.sidebar-section-title').click();
-    await expect(projectsToggle).toHaveAttribute('aria-expanded', 'true');
-    await expect(tasksToggle).toHaveAttribute('aria-expanded', 'true');
-  });
-});