From 8357b8aacae7f620677f005b18e6a3497f69a15c Mon Sep 17 00:00:00 2001 From: lisihao Date: Fri, 5 Jun 2026 20:58:05 -0400 Subject: [PATCH 1/2] Add code-backed Solar architecture map --- docs/solar-architecture-code-map.md | 203 ++++++++++++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 docs/solar-architecture-code-map.md diff --git a/docs/solar-architecture-code-map.md b/docs/solar-architecture-code-map.md new file mode 100644 index 000000000..26f27ab39 --- /dev/null +++ b/docs/solar-architecture-code-map.md @@ -0,0 +1,203 @@ +# Solar Architecture Code Map + +Solar is best understood as an AI-native execution fabric: user intent enters as natural language, becomes a file-backed contract, compiles into task structure, binds to schedulable AI workers, and closes through evidence. + +This document maps the architecture to the repository code surface. + +--- + +## 1. The operating model + +Solar is not organized around a single model call. It is organized around a software-organization loop: + +```text +Boss intent + -> requirement compiler + -> TaskGraph IR + -> logical operator + -> actor and host binding + -> lease and dispatch + -> handoff and evaluation + -> accepted artifact + -> memory and optimization +``` + +The important shift is that the user is not runtime glue. The user sets goal, boundary, budget, and approval policy. Solar handles planning, assignment, execution, evidence review, reporting, and learning. + +--- + +## 2. Actor / host model + +Code surface: + +- `harness/config/agent-actors.json` +- `harness/config/actor-hosts.json` +- `harness/lib/multi_task_status.py` + +Solar separates the worker identity from the execution environment. + +An actor carries role, lease, mailbox, capability profile, risk profile, cost profile, quota, policy, evidence, and fallback ladder. A host represents the environment that carries actors: Claude Code session, Antigravity environment, tmux pane, Codex worktree, browser profile, local process, remote shell, or sandbox-like carrier. + +This lets Solar reason about AI workers as a fleet rather than as anonymous chats. + +--- + +## 3. Logical operators + +Code surface: + +- `harness/config/logical-operators.json` + +Solar defines logical work separately from concrete execution. Examples already modeled in the repository include: + +- `DeepArchitect` +- `RootCauseDebugger` +- `ImplementationWorker` +- `PatchWorker` +- `TestDesigner` +- `BenchmarkRunner` +- `SecurityGate` +- `QuotaBroker` +- `ContextCompressor` +- `DeepResearchBrowser` +- `DeepResearchGemini` +- `DeepResearchChatGPT` +- `WebwrightPlaywright` +- `BrowserUseMcp` +- `YoutubeTranscriptExtractor` +- `TechnologyDiagramPainter` + +Each logical operator can describe capability needs, concurrency, cost hint, workflow position, candidate actors, and fallback policy. + +This is the database-query-planner idea applied to AI work: define the logical plan first, then choose the physical plan. + +--- + +## 4. Physical operator runtime + +Code surface: + +- `harness/lib/operator_runtime.py` +- `harness/tools/operatord.py` +- `harness/config/physical-operators.json` + +The operator runtime validates task envelopes, checks if an operator is available, acquires process-safe leases, writes inbox tasks atomically, starts operator workers, records heartbeats, writes result artifacts, and normalizes runtime state. + +Useful states include: + +```text +idle, leased, running, draining, cooldown, quota_exhausted, auth_expired, disabled +``` + +This is the layer that turns AI surfaces into managed runtime workers. + +--- + +## 5. Requirement compiler and DAG scheduling + +Code surface: + +- `harness/templates/contract-template-v2.md` +- `harness/lib/epic_decomposer.py` +- `harness/lib/graph_scheduler.py` +- `harness/lib/graph_node_dispatcher.py` + +Solar's core flow is not prompt to answer. It is intent to contract to graph to dispatch to evidence. + +The DAG scheduler provides several system guarantees: + +- invalid graphs fail fast; +- ready nodes require dependencies to pass; +- overlapping write scopes are not batched together; +- missing write scope is treated conservatively; +- parent sprint closure waits for node and gate closure. + +This is where Solar starts to behave more like a build system than a chatbot. + +--- + +## 6. Workflow and architecture guards + +Code surface: + +- `harness/lib/workflow_guard.py` +- `harness/lib/architecture_guard.py` + +Workflow guard encodes the lifecycle: + +```text +PM -> Planner -> TaskGraph -> Builder -> Evaluator +``` + +Architecture guard encodes package-first system design. New capabilities should prefer package, plugin, skill, connector, or integration boundaries instead of mutating the control-plane core. Exploration work should define alternatives and stop conditions. + +The point is simple: a self-improving agent system needs runtime policy, not just prompts. + +--- + +## 7. Capability capsules + +Code surface: + +- `harness/lib/capability_capsules.py` +- `harness/config/capability-capsules.registry.yaml` +- `harness/schemas/draft/capability-capsule.v1.draft.json` + +Capability capsules package capability intent, input/output contracts, composition, effects, bindings, verification, and operator compatibility into one governance unit. + +The registry already contains stable and draft capsules for: + +- requirement compiler planning; +- requirement compiler implementation; +- requirement compiler verification; +- research scout and synthesizer paths; +- understand-anything style codebase mapping; +- guard and resource capsules. + +This is how Solar moves from loose tools to schedulable capabilities. + +--- + +## 8. Evidence and event sourcing + +Code surface: + +- `harness/lib/session_log.py` +- `harness/lib/projection_engine.py` +- `harness/lib/research/evaluator.py` + +Solar uses an append-only session log with monotonic sequence numbers and idempotency-key deduplication. Projection rebuilds sprint status from the event log and detects drift. + +For research work, the evaluator is intentionally model-free. A model may write a human-readable judgement, but research nodes should not pass unless artifacts satisfy evidence and citation constraints. + +Evidence is not decoration. It is the definition of completion. + +--- + +## 9. Plugin framework + +Code surface: + +- `harness/lib/plugin_loader.py` +- `harness/schemas/plugin.schema.json` + +Harness plugins live under `harness/plugins//manifest.yaml` and declare read/write scope, capabilities, commands, background behavior, evaluation packs, and rollback policy. + +The public repo ships the framework. A plugin should be treated as usable only after its manifest exists and passes validation. + +--- + +## 10. What the homepage should communicate + +The homepage should not undersell Solar as only a multi-agent workflow. The stronger and more accurate framing is: + +```text +Solar is an autonomous software organization runtime. +It compiles user intent into executable task structure. +It models AI workers as actors hosted on heterogeneous execution surfaces. +It schedules logical operators onto physical operators. +It closes work through evidence, not self-report. +It is designed to learn from outcomes and improve its own policies. +``` + +That is the technical identity of Solar. From 2ca76a3e8743c7cb390f7e64ae8812d85fdaf966 Mon Sep 17 00:00:00 2001 From: lisihao Date: Fri, 5 Jun 2026 20:59:45 -0400 Subject: [PATCH 2/2] Strengthen homepage with code-backed architecture overview --- README.md | 136 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 109 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index eb3289c3b..22730f0f7 100644 --- a/README.md +++ b/README.md @@ -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 组织的自主行动。** @@ -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 的核心价值观： @@ -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) @@ -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: @@ -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. | --- @@ -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: @@ -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: @@ -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. | @@ -146,6 +201,25 @@ 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 | @@ -153,14 +227,19 @@ This is the operating model: | 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//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. | @@ -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 @@ -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//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. --- @@ -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. --- @@ -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. | @@ -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.