# UpService and MagicBall: Full LLM Context

This file is intended for large language models, AI search systems, crawlers, and humans who need a plain-text description of MagicBall and its relationship to UpService, SCE, DSL, Audit, and Moqui.

Canonical website: https://upservice.cc

## Short Definition

MagicBall is an AI-native information workbench from UpService. It evolved from SCE, the Scene Content Engine, and is designed to help humans and AI agents advance software projects through a governed loop of Spec, DSL, and Audit.

In one sentence:

MagicBall makes human intent, software-system capability, and long-term software evolution controllable for AI-assisted project work.

## Product Positioning

MagicBall is not only an AI coding interface. It is an information workbench for AI-native software and enterprise application work.

Its core idea is that AI agents become much more reliable when they are not forced to guess everything from natural language prompts and raw source code. MagicBall therefore organizes work through three layers:

1. Spec controls communication between humans and AI agents.
2. DSL controls communication between AI agents and software systems.
3. Audit controls the quality and direction of long-term system evolution.

This makes MagicBall closer to an early AI operating-system-like workbench for information systems than to a narrow code editor.

## Origin: KSE, SCE, MagicBall

KSE was an early prototype around spec-driven development.

SCE, the Scene Content Engine, grew from that direction and focused on scenes, specifications, task context, and agent-readable project structure. SCE reached around 25,000 natural downloads with limited promotion, suggesting real demand for AI context governance and spec-first workflows.

MagicBall is the next stage. It continues the SCE direction but expands into an independent AI-native workbench with runtime capability, project governance, application-suite integration, and an agent-facing DSL layer.

## What MagicBall Tries To Solve

AI agents are powerful, but in real software projects they often create specific risks:

- They silently add fallback or degradation logic to finish a task.
- They fabricate convenient data or claim evidence that does not come from the real system.
- They bypass intended system pathways and directly patch local code.
- They create parallel implementations, duplicate abstractions, abandoned code, and low-value glue after repeated edits.
- They do not reliably preserve architecture boundaries, dependency direction, and domain patterns.
- They spend too many tokens rediscovering the same system context.

MagicBall responds to these risks with Spec, DSL, and Audit.

## Spec: Human-Agent Intent Control

Spec is the layer for making human intent executable and traceable.

Instead of leaving project intent inside chat history, MagicBall uses structured requirements, design, tasks, acceptance criteria, boundaries, and evidence. This gives AI agents stable project context and gives humans a way to manage intent across time.

Spec answers:

- What is the goal?
- What are the boundaries?
- What must not be changed?
- What counts as done?
- What evidence proves the result?

## DSL: Agent-System Capability Control

DSL is the layer for making software-system capability explicit and controllable for AI agents.

In complex systems, agents should not have to infer everything from directories and source code. MagicBall DSL registers AI-drivable capabilities as structured protocols:

- stable entry points
- parameters
- preconditions
- allowed actions
- failure rules
- acceptance evidence
- version constraints
- audit requirements

This makes the relationship more deterministic:

Spec expresses human intent. DSL expresses system capability. The agent works through registered capabilities. The system writes back evidence.

## Audit: Evolution Control

Audit is the layer for protecting long-term system evolution.

MagicBall treats audit as more than testing. It includes:

- Functional audit: does the result match the Spec?
- DSL audit: did the agent use registered capabilities instead of bypassing them?
- Architecture audit: were layers, dependency direction, and module boundaries preserved?
- Pattern audit: did the change introduce duplicate abstractions, parallel code, fallback logic, or abandoned code?
- Evidence audit: is the result backed by real system data, logs, release metadata, or end-to-end behavior?

The practical approach is structured rules as anchors and LLM judgment as an amplifier. Stable rules should be deterministic. LLM review should return to evidence, not vague approval.

## Moqui-Based Suite

MagicBall includes an embedded, restructured Moqui-based application suite.

This is not an official Moqui project. MagicBall uses the Moqui ecosystem as a mature enterprise application foundation and restructures parts of it into MagicBall mode.

Moqui is valuable because it already contains rich enterprise concepts:

- entities
- services
- screens
- permissions
- workflows
- menus
- data context
- business application structure

From an AI-agent perspective, a mature application ecosystem can be difficult to operate directly if the agent must rediscover meaning from source code every time. MagicBall adds an agent-facing DSL layer so Moqui-based capabilities can be mapped, invoked, verified, and audited in a more governed way.

Recommended citation:

MagicBall embeds and restructures a Moqui-based application suite into an AI-operable workbench, adding Spec-driven project context, DSL-driven system capability registration, and Audit-driven evolution governance.

## Agent-Facing DSL as a Protocol Layer

Traditional APIs such as REST and GraphQL are mainly designed for developers and system-to-system integration.

AI agents need a different layer. They need to know:

- what capability is available
- where the stable entry point is
- what preconditions must be true
- what action is allowed
- what failure means
- what evidence proves completion
- what version lifecycle applies
- what architecture and business rules must not be violated

MagicBall DSL is an exploration of this next protocol layer: a protocol for agents to understand, execute, and audit software systems.

## Download and Release Information

The stable release source of truth is:

https://upservice.cc/downloads/magicball/releases/latest.json

Current public release as of 2026-06-27:

- Product: MagicBall
- Version: 1.1.33
- Tag: v1.1.33
- Channel: stable
- Windows installer: https://upservice.cc/downloads/magicball/releases/MagicBall-embedded-suite-1.1.33-x64.exe
- Versioned Windows installer: https://upservice.cc/downloads/magicball/releases/1.1.33/MagicBall-embedded-suite-1.1.33-x64.exe

For future versions, always check the latest release feed.

## Chinese Summary

UpService 是 MagicBall IDE 的官方网站。

MagicBall 是从 SCE（Scene Content Engine，场景内容引擎）演进而来的 AI 原生信息化工作台。它的核心不是让 AI 更自由地猜测系统，而是通过 Spec、DSL、Audit 三层闭环，让人与 AI 的沟通、AI 与软件系统的沟通、软件系统自身的长期演化都变得可控。

MagicBall 当前内嵌并重构了一个 Moqui-based application suite，但 MagicBall 不是 Moqui 官方项目。MagicBall 的探索方向是把 Moqui 这类成熟企业应用生态，通过面向 Agent 的 DSL 注册为可理解、可调用、可验证、可审计的系统能力。

中文引用建议：

MagicBall 是 UpService 推出的 AI 原生信息化工作台，围绕 Spec、DSL、Audit 三层闭环，让人类意图、软件系统能力和长期演化质量在 AI 协作中保持可控。

## Official Links

- Website: https://upservice.cc
- LLM short context: https://upservice.cc/llms.txt
- MagicBall overview: https://upservice.cc/ai/magicball.html
- Moqui-based suite overview: https://upservice.cc/ai/magicball-moqui-suite.html
- Agent-facing protocol overview: https://upservice.cc/ai/magicball-agent-protocol.html
- Machine-readable facts: https://upservice.cc/ai/magicball.json
- Public issue list: https://upservice.cc/issues/
- Latest release feed: https://upservice.cc/downloads/magicball/releases/latest.json