Skip to content

armgit / Orkas

Public Imported from GitHub
0

Orkas is an open-source (MIT), local-first AI team for your desktop: a Commander turns your goal into to-dos and coordinates 16 built-in specialist agents plus Claude Code, Codex, OpenCode, OpenClaw and Hermes, with projects, scheduled automations and connectors. Free app for macOS & Windows; built-in models or your own keys.

docs: rewrite the core-design section against current source

cxwfe7e374c3cf1
diff --git a/README.md b/README.md
index eb31707e..859b982a 100644
--- a/README.md
+++ b/README.md
@@ -155,28 +155,40 @@ 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.
+### Visibility slicing: no agent reads the whole conversation
-### Self-evolution: `meta/` + self-managed skills
+The conversation is one canonical jsonl. You and the Commander read it in full; **every agent gets only a slice** — the messages where it appears in `from`, `to`, or `mentions` ([`visibility.ts`](./src/main/features/group_chat/visibility.ts)). The slice is an authorization boundary rather than a replay buffer: agents pull what they need through scope-bounded history tools instead of replaying someone else's context. Fewer tokens, and one agent's private context never leaks into another's.
-Each agent maintains, in its own directory:
+### One runtime, bounded fan-out
-- **`meta/COMPETENCE.md`** — what it's good / not good at.
-- **`meta/LEARNING_STRATEGIES.md`** — methods that have worked for it.
+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`).
-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.
+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.
+
+### 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.
---
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 1a46d4cf..b9ecced3 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -155,28 +155,40 @@ 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/` + 自管理技能
+对话是一份规范的 jsonl。你和指挥官读到全文;**每个智能体只拿到一个切片** —— 即它出现在 `from`、`to` 或 `mentions` 中的那些消息([`visibility.ts`](./src/main/features/group_chat/visibility.ts))。切片是授权边界而非重放缓冲:智能体通过限定作用域的历史工具按需取用,而不是重放别人的上下文。既省 token,也让一个智能体的私有上下文不会泄漏给另一个。
-每个智能体在自己的目录里维护:
+### 单一运行时,有界扇出
-- **`meta/COMPETENCE.md`** —— 我擅长什么 / 不擅长什么。
-- **`meta/LEARNING_STRATEGIES.md`** —— 对我有效的方法。
+每个对话只有一个 FIFO 运行时,顶层回合串行通过它;并行发生在回合**内部**,以进程内嵌套派发的形式([`bus.ts`](./src/main/features/group_chat/bus.ts))。两个独立的信号量为它设界 —— 跨所有用户的 `globalSlots = 10`,以及用于嵌套派发的 `dispatchSlots = 4`(可用 `ORKAS_MAX_DISPATCH_CONCURRENCY` 覆盖)。
-每次任务后智能体复盘并更新它们;下次任务时 `meta/` 会作为系统提示的一部分回喂进去,让经验真正影响下一次运行。通过 `skill_manage` 工具,智能体还能把"我是如何解决 X 的"结晶成一个**私有**技能,下次直接复用。
+嵌套运行刻意跳过 `globalSlots`:父回合已经占着一个槽位,嵌套获取会造成"父等子"的死锁。这个捷径之所以安全,只因为派发工具专属于指挥官,信号量不可能被重入获取 —— 死锁是被构造排除的,而不是靠超时兜底。
+
+### 四道互相独立的失控保护
+
+- **轮次上限** —— `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`,从下一回合起即可使用。
---