Skip to content

Strengthen homepage with code-backed Solar architecture #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lisihao merged 2 commits into from
Jun 6, 2026
Merged

Strengthen homepage with code-backed Solar architecture #23

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8357b8a
Add code-backed Solar architecture map
lisihao Jun 6, 2026
2ca76a3
Strengthen homepage with code-backed architecture overview
lisihao Jun 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 109 additions & 27 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
[![Solar Harness](https://img.shields.io/badge/Solar-Harness-8b5cf6.svg)](harness/)
[![AI Native](https://img.shields.io/badge/AI--Native-Execution%20Fabric-14b8a6.svg)](#solar-是什么)

Solar is an AI-native operating system prototype for long-running, evidence-driven software work. It is not a chatbot, not a prompt collection, and not a simple multi-agent demo. Solar treats natural language as the control surface, requirements as compilable artifacts, AI products as schedulable physical operators, and software delivery as evidence-gated DAG execution.
Solar is an AI-native execution fabric for long-running, evidence-driven software work. It is not a chatbot, not a prompt collection, and not a simple multi-agent demo. Solar treats natural language as the control surface, requirements as compilable artifacts, AI products as schedulable physical operators, and software delivery as evidence-gated DAG execution.

中文一句话：**Solar 把老板的一句话编译成一支 AI 组织的自主行动。**

Expand All @@ -20,9 +20,9 @@ Solar 当前由三层组成：

| Layer | Directory | Role |
|---|---|---|
| **Solar Core** | `CLAUDE.md`, `agents/`, `skills/`, `rules/`, `hooks/`, `core/` | Claude/Codex-native workflow kernel: agents, skills, rules, hooks, persistent operating context. |
| **Solar Harness** | `harness/` | Requirement compiler, sprint control plane, DAG scheduler, worker lease, model fleet dispatch, evaluator, benchmark, and experience memory. |
| **Solar Knowledge** | `docs/`, `scripts/`, knowledge adapters, runtime-generated indices | Unified knowledge surface for docs, accepted artifacts, research evidence, and context maps. |
| **Solar Core** | `CLAUDE.md`, `agents/`, `skills/`, `rules/`, `hooks/`, `core/` | Claude/Codex-native workflow kernel: agents, skills, rules, hooks, and operating context. |
| **Solar Harness** | `harness/` | Requirement compiler, sprint control plane, TaskGraph runtime, actor/operator fleet, evaluator, benchmark, and experience memory. |
| **Solar Knowledge** | `docs/`, `scripts/`, research adapters, runtime-generated indices | Knowledge surface for docs, accepted artifacts, research evidence, source maps, and future context maps. |

Solar 的核心价值观：

Expand All @@ -34,6 +34,29 @@ Solar 的核心价值观：

---

## Why Solar is different

Most agent frameworks start with a model loop. Solar starts with an operating model.

```text
普通 Agent: prompt -> plan -> tool calls -> answer
Solar Harness: intent -> contract -> PRD/plan -> TaskGraph IR -> operator binding
-> lease -> dispatch -> handoff -> eval -> gate -> memory -> optimization
```

| Design axis | Conventional agent loop | Solar |
|---|---|---|
| User role | operator who keeps prompting | boss who sets goals and boundaries |
| Task unit | prompt or todo | file-backed contract + TaskGraph IR |
| Execution unit | model/API call | AI-capable physical operator |
| Scheduling | ad hoc tool choice | logical operator → actor/host binding |
| Parallelism | multiple chats or workers | DAG, write scope, leases, runtime state |
| Quality | model self-report or user inspection | handoff, eval, deterministic gates, parent gate |
| Memory | chat history or RAG | session log, projection, accepted artifacts, context maps |
| Optimization | manual prompt tuning | evaluator side-info, scorecards, replay, promotion gates |

---

## System Architecture

![Solar system architecture](docs/assets/solar-system-architecture.svg)
Expand All @@ -44,6 +67,28 @@ That surface may be a Claude Code pane, a Codex instance, DeepSeek Reasonix, a b

---

## Code-backed architecture map

The architecture is not just a slide. The repository already contains the first implementation layer of the runtime.

Read the full map here: **[`docs/solar-architecture-code-map.md`](docs/solar-architecture-code-map.md)**

| Architecture concept | Code surface | What it means |
|---|---|---|
| **Actor / Host model** | `harness/config/agent-actors.json`, `harness/config/actor-hosts.json` | Workers carry role, lease, mailbox, capability/risk/cost profile, quota, policy, evidence, and fallback ladder. Hosts model execution surfaces such as Claude Code sessions, Antigravity environments, tmux panes, Codex worktrees, browser profiles, local processes, and external workers. |
| **Logical operator catalog** | `harness/config/logical-operators.json` | Defines operators such as `DeepArchitect`, `RootCauseDebugger`, `ImplementationWorker`, `PatchWorker`, `TestDesigner`, `SecurityGate`, `QuotaBroker`, `ContextCompressor`, `DeepResearchBrowser`, and `TechnologyDiagramPainter`. |
| **Operator runtime** | `harness/lib/operator_runtime.py` | Validates task envelopes, checks operator state, acquires leases, writes inbox tasks, starts workers, writes heartbeats, and records results. |
| **DAG scheduler** | `harness/lib/graph_scheduler.py` | Turns planner `task_graph.json` into dispatch decisions with dependency readiness, write-scope batching, and parent-gate checks. |
| **Workflow / architecture guards** | `harness/lib/workflow_guard.py`, `harness/lib/architecture_guard.py` | Encodes lifecycle and package-first design policy as graph-time and dispatch-time checks. |
| **Capability capsules** | `harness/lib/capability_capsules.py`, `harness/config/capability-capsules.registry.yaml` | Packages capability intent, contracts, effects, bindings, verification, and operator compatibility into selectable governance units. |
| **Session log and projection** | `harness/lib/session_log.py`, `harness/lib/projection_engine.py` | Provides append-only event sourcing, replay, status projection, stale activity detection, and drift checks. |
| **Deep Research gate** | `harness/lib/research/evaluator.py` | Provides a model-free quality gate for research artifacts: source mix, authority, citation accuracy, unsupported-rate, novelty, insight density, and section evidence. |
| **Plugin framework** | `harness/lib/plugin_loader.py`, `harness/schemas/plugin.schema.json` | Loads and validates plugin manifests with scope, commands, capabilities, background behavior, eval packs, and rollback policy. |

**Core claim:** AI work should be compiled, scheduled, leased, observed, evaluated, and improved like a real runtime.

---

## Solar Harness: the Control Plane

Solar Harness turns a user goal into a controlled software delivery flow:
Expand All @@ -68,10 +113,12 @@ Key primitives:
|---|---|
| **Sprint Contract** | A file-backed engineering contract: objective, scope, constraints, acceptance, owner intent. |
| **TaskGraph IR** | Machine-readable DAG with `depends_on`, `read_scope`, `write_scope`, `required_capabilities`, `gate`, and `acceptance`. |
| **Physical Operator** | A concrete execution surface: tmux pane, Claude Code, Codex, browser profile, API worker, remote shell, local process. |
| **Actor** | A schedulable AI worker identity with role, capability profile, cost profile, quota, lease, mailbox, evidence, and fallback ladder. |
| **Host** | The concrete environment that carries actors: Claude Code session, tmux pane, Codex worktree, browser profile, Antigravity environment, local process, remote shell, or sandbox. |
| **Physical Operator** | A concrete execution surface that can run work. It may be a subscription UI, browser session, code agent, API worker, local model, or remote machine. |
| **Logical Operator** | Stable semantic work: compile requirement, build graph, implement code, run browser research, evaluate evidence, optimize artifact. |
| **Pane / Actor Lease** | Runtime ownership protocol to prevent multiple tasks from fighting over the same worker. |
| **Evidence ABI** | Handoff, eval, session log, deterministic gate, and accepted artifact schema. |
| **Lease** | Runtime ownership protocol to prevent multiple tasks from fighting over the same actor, pane, or operator. |
| **Evidence ABI** | Handoff, eval, session log, deterministic gate, result artifacts, and accepted artifact schema. |
| **Meta Harness** | Self-optimization layer for prompts, policies, capsules, evaluators, and routing rules. |

---
Expand All @@ -82,16 +129,24 @@ Key primitives:

Solar separates **what to do** from **who executes it**.

Examples of logical operators:

- `CompileRequirement`
- `GeneratePRD`
- `BuildTaskGraph`
- `ImplementCode`
- `RunBrowserResearch`
- `EvaluateEvidence`
- `UpdateContextMap`
- `OptimizeArtifact`
Examples of logical operators already modeled in the repository:

- `DeepArchitect`
- `RootCauseDebugger`
- `ImplementationWorker`
- `PatchWorker`
- `TestDesigner`
- `BenchmarkRunner`
- `SecurityGate`
- `QuotaBroker`
- `ContextCompressor`
- `DeepResearchBrowser`
- `DeepResearchGemini`
- `DeepResearchChatGPT`
- `WebwrightPlaywright`
- `BrowserUseMcp`
- `YoutubeTranscriptExtractor`
- `TechnologyDiagramPainter`

Examples of physical operators:

Expand All @@ -102,7 +157,7 @@ Examples of physical operators:
- GLM / DeepSeek / Claude subscription worker
- API model worker
- local model process
- remote Mac mini / devbox worker
- remote worker
- deterministic Python verifier

Why this matters:
Expand Down Expand Up @@ -135,7 +190,7 @@ This is the operating model:

| Role | Responsibility |
|---|---|
| **Boss / Operator** | Sets goal, boundary, budget, risk tolerance, and final approval policy. |
| **Boss / Operator** | Sets goal, boundary, budget, and final approval policy. |
| **PM** | Turns intent into requirements, acceptance, and non-goals. |
| **Planner** | Produces plan, architecture, TaskGraph IR, and capability plan. |
| **Scheduler** | Chooses ready nodes, batches safe parallel work, binds physical operators. |
Expand All @@ -146,21 +201,45 @@ This is the operating model:

---

## The deeper idea

Solar is trying to make an AI software organization behave like a disciplined system:

```text
Intent is compiled.
Work is typed.
Workers are leased.
Capabilities are governed.
Research is gated.
Events are replayable.
Completion is evidenced.
Policies can improve.
```

The user should not become the glue between tools, models, agents, browser tabs, terminals, and reports. The user should be able to act as the boss: set direction, approve important decisions, and receive verified outcomes.

---

## What Solar can do today

| Capability | Status | Notes |
|---|---|---|
| Solar Core install | Available | Installs Claude/Codex-facing agents, rules, skills, hooks, and core files. |
| Solar Harness local runtime | Available | File-backed sprint contracts, coordinator, queues, leases, builder/evaluator flow. |
| TaskGraph DAG scheduling | Available | Dependency gating, write-scope batching, capability matching, parent-gate checks. |
| Actor / host registry | Available | Models AI workers and execution surfaces with capability, cost, quota, lifecycle, mailbox, and evidence fields. |
| Operator runtime | Available | Leases operators, submits task envelopes, writes inbox files and heartbeats, records results, and blocks unavailable states. |
| Logical operator catalog | Available | Maps high-level work classes to capability requirements, concurrency limits, workflow stages, candidate actors, and fallback policy. |
| Multi-pane / TUI execution | Available | Product delivery panes plus builder lab style execution. |
| Model / operator registry | Available | Model aliases, physical operators, actors, hosts, capability/risk/cost profiles. |
| Capability capsule registry | Available / evolving | Stable and draft capsules for requirement compilation, research, understand-anything, guards, and resources. |
| Evidence-native evaluation | Available | Handoff, eval, node verdict, session logs, deterministic research gates. |
| Event-sourced runtime | Available | Append-only session logs and projection cache support replay, idempotency, drift detection, and status reconstruction. |
| Remote worker path | Available / evolving | Remote sync, dispatch, monitor, and verification scripts are present. |
| Plugin framework | Available / evolving | Harness can load and validate `harness/plugins/<id>/manifest.yaml` when plugin manifests are present. The public repo does not need to ship enabled third-party plugins by default. |
| Solar-bundled skills | Available | Repository skills are copied into `~/.claude/skills/` by `install.sh`. Counts may change with the repo. |
| Third-party skills | Optional | Installed separately through `SKILLS-INSTALL.md`; they are an enhancement, not required for the base install. |
| Deep Research OS | Evolving | Evidence extraction, citation checking, research evaluation, and report gates. |
| Deep Research OS | Evolving | Evidence extraction, citation checking, source authority policy, research evaluation, and report gates. |
| Context Map / PEEK-style layer | Planned / integrating | Orientation cache for repos, topics, vaults, and long-running projects. |
| Meta Harness self-optimization | Planned / integrating | Optimizes text artifacts using evaluator score, side-info, replay, and promotion gates. |
| Hard sandbox / write enforcement | Planned | Current design uses scope, lease, evaluator, and guards; stronger filesystem enforcement is a priority. |
Expand Down Expand Up @@ -227,7 +306,7 @@ Runtime boundary:
- local runtime: `~/.solar/harness/`
- generated runtime state: `run/`, `state/`, `logs/`, `cache/`, `vendor/`, `venvs/`

Runtime logs, databases, private trajectories, local model caches, credentials, and machine-local state should not be committed as source.
Runtime logs, databases, private trajectories, local model caches, and machine-local state should not be committed as source.

### Optional skills and plugins

Expand All @@ -236,7 +315,7 @@ Base install is intentionally conservative:
- Solar-bundled skills are copied from `skills/` into `~/.claude/skills/`.
- Third-party skill packs are optional; use [`SKILLS-INSTALL.md`](SKILLS-INSTALL.md) and ask the user before installing optional repositories.
- Harness plugin support is installed as framework code. Plugins must provide `harness/plugins/<id>/manifest.yaml` and pass plugin validation before they should be treated as usable.
- API keys are optional for install. If you need API-backed features, copy `.env.template` to `.env` and fill values locally. Do not commit `.env`.
- API-backed features can be configured locally with `.env.template`. Do not commit local environment files.

---

Expand All @@ -261,7 +340,10 @@ Base install is intentionally conservative:
A task is not complete because a model says it is complete. It is complete when evidence passes review.

7. **Self-optimization must be controlled**
Solar can optimize prompts, policies, capsules, and routing, but protected core changes require replay, canary, rollback, and human approval.
Solar can optimize prompts, policies, capsules, and routing, but core runtime changes should go through replay, review, and rollback planning.

8. **Runtime state must be separate from source**
Published source should stay clean; local queues, logs, state, machine details, and generated artifacts belong in runtime paths or sanitized fixtures.

---

Expand All @@ -271,7 +353,7 @@ Base install is intentionally conservative:
|---|---|---|
| 1 | **Public homepage + docs cleanup** | Keep README, install docs, and user guide aligned with the current architecture. |
| 2 | **Privacy and release hardening** | Template local host configs, remove machine fingerprints, add privacy scan and release gates. |
| 3 | **Operator runtime** | Formalize logical/physical operator schemas, leases, health, scorecards, and fallback ladders. |
| 3 | **Actor / operator runtime** | Formalize actor-host schemas, logical/physical operator schemas, leases, health, scorecards, and fallback ladders. |
| 4 | **Model fleet manager** | Subscription-aware routing, cost/quality/latency scoring, browser-native operators. |
| 5 | **Hard execution boundaries** | Write-scope enforcement, per-node worktrees, patch gates, permission policy, sandbox adapters. |
| 6 | **Context Map plane** | PEEK-style repo/topic/project maps with provenance, staleness, role-aware rendering. |
Expand All @@ -283,13 +365,13 @@ Base install is intentionally conservative:

## Current Boundary

Solar is a serious prototype, not a finished commercial operating system. The core abstractions are already visible: requirement compilation, TaskGraph IR, physical operator scheduling, evidence ABI, model fleet control, and self-optimization hooks.
Solar is a serious prototype, not a finished commercial operating system. The core abstractions are already visible: requirement compilation, TaskGraph IR, actor/host registry, physical operator scheduling, capability capsules, evidence ABI, model fleet control, event sourcing, DeepResearch gates, and self-optimization hooks.

The next engineering priority is to make these abstractions clean, safe, observable, and easy to install:

- remove machine-local details from public-facing config and docs;
- replace Mermaid diagrams with maintained SVG architecture assets;
- stabilize the public documentation around Core / Harness / Knowledge;
- keep SVG diagrams and homepage synchronized with the runtime architecture;
- stabilize public documentation around Core / Harness / Knowledge / Operators;
- strengthen privacy, release, and sandbox gates;
- expose the Harness runtime through cleaner APIs and dashboards.

Expand Down
Loading
Loading