# KeelBase **Repository Path**: rain6fish/KeelBase ## Basic Information - **Project Name**: KeelBase - **Description**: KeelBase 是全栈协议驱动的 AI 信任运行时基座。专注 Agent 安全，赋能企业构建可审计、可治理、可私有部署的业务安全 AI 应用平台。 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 8 - **Forks**: 2 - **Created**: 2026-08-10 - **Last Updated**: 2026-11-06 ## Categories & Tags **Categories**: ai **Tags**: AI工程化, 企业级安全基座, 全栈协议驱动, AI信任运行时, AI应用平台 ## README # KeelBase — Build and Run Business-safe AI Applications > **Build AI applications that enterprises can trust — from scratch or from existing systems.** Governed, auditable and private by default.

KeelBase governance and value landscape — enterprise applications (existing + AI-enabled, built with KeelBase) → Business-safe AI Runtime (onboarding · AI execution chain · governance · platform) → AI Agents & model services

> **Open-source Business-safe AI Runtime** — connect AI agents with existing business systems, **without replacing existing technology stacks**. **The KeelBase DNA** — *AI Generates. Architecture Constrains. Runtime Governs. Tests Verify. Humans Decide.* Business boundaries are enforced by the **Runtime**, not prompts; an Agent's **capability ≠ its authority**; trust is **proven by runnable verification**, not claimed; important actions are **recoverable**. Full engineering philosophy: [docs/keelbase-dna.md](docs/keelbase-dna.md). **Articles** — the long-form essays behind these decisions, on AI execution governance and AI audit evidence: [keelbase.hashnode.dev](https://keelbase.hashnode.dev/). --- ## 🚀 Try in 60 Seconds > Prefer instant? **Open the live demo** → [keelbase-demo](https://demo.keelbase.com.cn/user/) (`alex/Alex@2026$Demo` — workbench, ask "which customers need attention?"). Visit guide: [demo-live.md](docs/manual/demo-live.md). > > Or **watch the demo video** → [English demo (GitHub Pages)](https://rain6fish.github.io/KeelBase/video-en.html) · [China mirror](https://demo.keelbase.com.cn/demo/video-en.html) (4-min, with real system demos; download: [GitHub release](https://github.com/rain6fish/KeelBase/releases/tag/demo-videos)). > > Or **read the series** → [Runtime over Prompt](https://rain6fish.github.io/KeelBase/blog/runtime-over-prompt.html) · [Why AI Writes Need Risk Tiers](https://rain6fish.github.io/KeelBase/blog/why-ai-writes-need-risk-tiers.html). Docker only — one command brings up the entire application (backend + workbench + Admin Console + mobile preview), no build: ```bash docker run -d --name keelbase -p 3000:3000 ghcr.io/rain6fish/keelbase:latest ``` > No LLM API key needed to try it: when no cloud/local model is configured, the AI runs in **deterministic demo mode** — the full golden path (analyze → confirm → create → audit → revoke) works out of the box. Bring your own DeepSeek/Qwen/OpenAI/Ollama key (`-e DEEPSEEK_API_KEY=...`) for real LLM responses. > > **Reset to a clean demo state anytime**: `docker rm -f keelbase && docker run -d --name keelbase -p 3000:3000 ghcr.io/rain6fish/keelbase:latest` — data lives in the container's SQLite (no volume), so removing the container wipes demo data and the seed re-runs on next start. Then walk the golden path in 6 steps: ```text 1. Open http://localhost:3000 (workbench) — /admin is the Admin Console 2. Sign in — alex/Alex@2026$Demo, or admin/Admin@2026$KeelBase (consistent across all environments) 3. Ask: "Which customers are at the highest risk this week?" 4. Watch AI analyze real business data 5. Approve a follow-up task (human confirmation) 6. Open the audit trace (every action recorded & reversible) ``` Prefers a local demo? `./deploy/demo.sh` → http://localhost:3000 (opens the AI CRM Golden Flow workbench). --- ## 🎯 See AI Actually Do Business KeelBase's flagship **AI CRM** is not a demo — it's a working product loop: ```text You: "Which customers are at the highest risk this week?" KeelBase AI: 3 customers require attention… → Analyze customer risk → Read authorized orders and activities → Create a follow-up task → Ask for your confirmation → Write to the CRM → Record audit → Allow revoke ``` One business scenario says more than a list of twenty features. --- ## 🎯 Who It's For Two ways to meet KeelBase — one runtime underneath. **For AI-native builders** — ship an AI business application without rebuilding the foundation: - Generate a full business module (entities / CRUD / permissions / AI tools / audit) from a protocol in ~30 minutes — real, editable code, not a low-code engine - Bring your own LLM (cloud or local); data stays under your control **For teams with existing business systems** — you already run CRM / ERP / OA or a decade-old Java stack, and you want it to think: - Bridge existing systems in (OpenAPI / SQL schema / Java service) without rewriting them - AI acts as a business assistant on your real data — risk analysis, follow-ups, summaries, approvals - Private deployment: Docker / offline / local models — data never leaves your perimeter > **Standalone or connected** — KeelBase is a complete application development platform in its own right (generate full-stack business apps from a protocol), and a Business-safe AI Runtime for existing systems. No legacy system required. --- ## 🔐 Business-safe by Design ```text User Request → AI Understanding → Business Data → Tool Call → Permission Check → Human Confirmation → Side Effect → Audit → Revoke ``` > **AI can act — but only within explicit business boundaries.** - **User-scoped tools** — every call carries the authenticated user; AI acts inside that user's data scope — their own records, plus their organization's where the resource is org-scoped — and never outside it - **Human confirmation** — writes at higher risk levels require a human's explicit approval before execution; low-risk writes execute under the configured policy - **Audit & revoke** — actions land on a tamper-evident audit hash chain (audit granularity is configurable; the default records everything); AI-created side effects are tracked, and reversible for the tools that declare a way to undo them - **Explainable** — "why did the AI do that?" is answered by a decision trace, not a black box --- ## 🏗 Build — Protocol-Driven Generation Build AI applications from new business models or existing systems: - **Application Protocol** — a human/AI-readable schema describing an application - **`keelbase init`** — natural language / SQL schema / OpenAPI → Protocol → a complete business module with permissions, AI tools, confirmation, and audit - **AI Bridge** — connect a Java/legacy system; AI reads and acts on it under governance > Generated artifacts are **normal source code**. No proprietary runtime metadata. No drag-and-drop lock-in. --- ## ▶️ Run — AI Does Real Business Work - Tool calling, RAG, memory, sub-agents, proactive AI - AI reads and acts on **business data** — not just chat - Every tool call scoped, every write confirmed, every action audited --- ## 🔒 Trust — Governance & Audit Where KeelBase differs from a plain agent framework: - CASL row-level permissions · tool governance · write confirmation - Audit hash chain (tamper-evident) · side-effect idempotency · revoke - Decision trace · AI eval · prompt-injection defense ### Enterprise Safety Validation These aren't just claims — every one is verified by an executable test that ships with the repo: - ✓ **Permission boundary tests** — cross-user access denied via CASL (authorization matrix, asserted case by case) - ✓ **Tool governance tests** — abuse / confirmation-bypass / prompt-injection blocked (security eval — `scripts/verify-security-eval.sh`) - ✓ **Human approval tests** — writes stay untouched until a human confirms (Golden Flow e2e) - ✓ **Audit integrity tests** — audit hash chain verifies, tampering fails (`/audit/verify`) - ✓ **Agent behavior tests** — decision trace + business-safe agent benchmark (Run/Trust/Safety dimensions, `scripts/benchmark/agent-benchmark.mjs`) - ✓ **End-to-end business flow** — AI CRM: read → risk → task → confirm → write → audit → revoke (deterministic e2e) > **Boundaries matter** — what "audit / revoke / tamper-evident" does and does **not** promise (e.g. within-application only, not vs. DBA/root; revoke is scoped per `revokeClass`, not a cross-system rollback): [SECURITY.md → Trust Boundaries (Not-a-*)](SECURITY.md) --- ## 🏠 Deploy — Private by Design ```text Cloud LLM OR Local Model / Ollama → Local Embedding → Local RAG → Business-safe Agent → Local Audit ``` > **Run the entire AI application locally when your data cannot leave your environment.** Docker single-container · offline / intranet deploy · local models & embeddings. --- ## 🛠 Build Your First Application ```bash git clone --recurse-submodules https://github.com/rain6fish/KeelBase.git && cd KeelBase cd Server-NestJS && npm install && cp .env.example .env && cd .. npm run preflight # before anything else: Node / Docker / ports / .env / contract submodule node scripts/keelbase-init.mjs --spec specs/invoices.json ``` > `--recurse-submodules` is required: `Server-NestJS/specs/protocol` is a submodule holding the wire schemas and protocol vectors that the test suites read. Already cloned without it (or downloaded a ZIP — those never carry submodules)? Run `git submodule update --init --recursive`. `npm run preflight` reports that gap — and any other setup one — before you start. Natural Language → Module Spec → Protocol → Application Code → AI Tools → Governance. The CLI ships **with the repo** (`scripts/keelbase-init.mjs`) — no global install; `--desc "…"` generates from a sentence instead of a spec file (needs a model key configured). Full flow: [Build an AI CRM in 30 minutes](docs/manual/onboarding-30min.md) · [30-minute acceptance](docs/manual/30min-acceptance.md) · [Dev Challenge](docs/manual/dev-challenge.md) — 中文 · [EN](docs/manual/onboarding-30min-en.md) · [EN](docs/manual/30min-acceptance-en.md) · [EN](docs/manual/dev-challenge-en.md) --- ## 📦 Existing System AIization ```text Existing DB / OpenAPI / Java System → Application Protocol → Generated Module → AI Tools + Governance → Business Agent ``` Give a 10-year-old business system AI capability without rewriting it. ### Java Starter (Spring Boot) For Java/Spring teams: annotate existing `@RestController` methods with `@KeelbaseTool` and they become governed KeelBase AI tools — delegated identity, human-confirmed writes, audit and revocation are handled by the KeelBase runtime. No rewrite. Requires Spring Boot 3.x + Java 17+ (Boot 2 / Java 8 go through the API-proxy path). **Get started** — Maven `cn.com.keelbase:keelbase-spring-boot-starter` ([Maven Central](https://central.sonatype.com/artifact/cn.com.keelbase/keelbase-spring-boot-starter)) → [github.com/rain6fish/KeelBase-java-starter](https://github.com/rain6fish/KeelBase-java-starter) — 5-minute trial, reference projects (CRM / PM / Approval), development guide. --- ## 🧩 Architecture One main thread — **Build → Run → Trust → Private Deploy**: - **Build** — *Protocol-driven generation:* Application Protocol (conventions); AI generates the business modules — **AI-native Application Engineering, not a traditional low-code engine** - **Run** — *Business-safe Agent Runtime:* user-scoped tools, human-confirmed writes, full audit and revoke - **Trust / Private Deploy** — *Data Sovereignty:* data stays on-prem; AI stays accountable and reversible The core is UI-framework-agnostic; Flutter / Vue / React are Renderers ([architecture-boundary](docs/architecture-boundary.md) · [EN](docs/architecture-boundary-en.md)). ## 📍 Where KeelBase Sits > **KeelBase is a Business-safe AI Runtime** — it connects AI agents with existing business systems, adding identity, governance, auditability, and private deployment, **without replacing existing technology stacks**. ```text AI Applications / Agents Agent Frameworks LangGraph · AutoGen · CrewAI Custom Agents · MCP Clients ▲ │ identity · policy · governance │ audit · runtime · deployment ┌─────────────┐ │ KeelBase │ └─────────────┘ │ │ bridge · protocol · capability mapping ▼ Existing Business Systems CRM · ERP · OA · MES · Database ``` - **Up — the AI world (northbound):** any agent can enter governance. Agent frameworks connect via **open standards (MCP / OpenAPI / function calling)** — KeelBase does not re-build orchestration, agent loops, or memory strategies - **Down — the business world (southbound):** any existing system can become AI-capable. Business systems connect via the **Bridge** (protocol + capability mapping) — no rip-and-replace - **In between — the trust layer:** identity, policy, permission, human confirmation, side-effect control, audit & revoke, private deployment --- ## 🧬 The KeelBase family

The KeelBase family — a host adapter, two runtimes that are peers, the bridge, and the contract all of them consume

> KeelBase is **one protocol with several implementations and hosts** — not a set of competing > products. The contract is the source of truth; runtimes and hosts consume it, and none of them > owns it. Every repository here is **Apache-2.0**. ```text host adapters KeelBase-YuDao └ governance added to a mature enterprise platform (yudao) runtimes KeelBase (TypeScript) · KeelBase4J (Java / Spring) └ two carriers of the same protocol — peers, not translations bridge KeelBase-java-starter └ wire an existing Java/Spring system in as governed AI tools contract keelbase-contract └ wire schemas + conformance vectors + the version line they share ``` | Repository | Role | Stack | Status | |---|---|---|---| | [`KeelBase`](https://github.com/rain6fish/KeelBase) | Reference implementation · product documentation · demo | TypeScript · NestJS · Vue · Flutter · Taro | active | | [`KeelBase4J`](https://github.com/rain6fish/KeelBase4J) | The Java carrier of the same protocol | Java 17 · Spring Boot | active | | [`KeelBase-java-starter`](https://github.com/rain6fish/KeelBase-java-starter) | Wire an existing Java/Spring system in as governed AI tools | Maven · Gradle | 0.1.x | | [`KeelBase-YuDao`](https://github.com/rain6fish/KeelBase-YuDao) | Host adapter — the governance layer on a yudao platform | Java · Vue 3 | active | | [`keelbase-contract`](https://github.com/rain6fish/keelbase-contract) | The protocol itself — schemas, vectors, the version line | JSON Schema | v1.x | **Where to start** — see it run: [`KeelBase`](https://github.com/rain6fish/KeelBase) (60-second Docker) · make an existing Java system AI-capable: [`KeelBase-java-starter`](https://github.com/rain6fish/KeelBase-java-starter) · you already run yudao: [`KeelBase-YuDao`](https://github.com/rain6fish/KeelBase-YuDao) · implement the protocol: [`keelbase-contract`](https://github.com/rain6fish/keelbase-contract). **Read the series** — the long-form essays behind these decisions, on AI execution governance and AI audit evidence: [keelbase.hashnode.dev](https://keelbase.hashnode.dev/). Which contract version each runtime answers for is maintained **once**, in the main repository — see [Compatibility](https://github.com/rain6fish/KeelBase#-compatibility). It is not duplicated here. ## 🧭 Compatibility The protocol has its own version line, independent of any runtime's. This table says which **contract version a runtime answers for** — which objects it has committed to speaking. It is maintained from the first release rather than assembled when someone asks. | Runtime | Runtime version | Contract version | |---|---|---| | `KeelBase` (TypeScript) | `v1.3.1` | **v1.18.0** — bound as a submodule | | `KeelBase` (TypeScript) | `v1.3.0` | **v1.16.0** — bound as a submodule | | `KeelBase` (TypeScript) | `v1.2.0` | **v1.12.0** — bound as a submodule | | `KeelBase` (TypeScript) | `v1.1.0` | **v1.6.0** — bound as a submodule | | `KeelBase` (TypeScript) | `main`, **unreleased** | **v1.20.0** — bound as a submodule | | `KeelBase` (TypeScript) | `v1.0.11`, superseded | **v1.0.1** — carried in-tree; that release predates the contract repository | | [`KeelBase4J`](https://github.com/rain6fish/KeelBase4J) (Java) | `v0.1.0` | **v1.1.0** — vendored snapshot, taken from the contract repository | A runtime that is behind the current contract is not broken; it simply does not yet answer for the newer version's objects. What moves a runtime forward is a deliberate act — the contract never reaches into a runtime on its own. The unreleased row is there on purpose. If you are choosing what to deploy, the difference between what is published and what is on `main` is exactly what you need to see. --- ## 📚 Documentation > Every guide ships in **中文 and English** — pick your language below. - **Quick Start 快速开始** — [中文](docs/manual/quickstart.md) · [English](docs/manual/quickstart-en.md) - **Tutorial 零基础教程** — [中文](docs/manual/tutorial.md) · [English](docs/manual/tutorial-en.md) - **Concept Map 概念地图** — [中文](docs/manual/concepts.md) · [English](docs/manual/concepts-en.md) - **Rules Map 规则地图** — [中文](docs/manual/rules-map.md) · [English](docs/manual/rules-map-en.md) - **Build an AI CRM in 30 minutes 30 分钟构建 AI CRM** — [中文](docs/manual/onboarding-30min.md) · [English](docs/manual/onboarding-30min-en.md) - **30-Minute Acceptance 30 分钟验收** — [中文](docs/manual/30min-acceptance.md) · [English](docs/manual/30min-acceptance-en.md) - **Dev Challenge 开发者 30 分钟挑战** — [中文](docs/manual/dev-challenge.md) · [English](docs/manual/dev-challenge-en.md) - **FAQ 常见问题** — [中文](docs/manual/faq.md) · [English](docs/manual/faq-en.md) - **Operations 运维手册** — [中文](docs/manual/operations-zh.md) · [English](docs/manual/operations.md) - **Development 开发手册** — [中文](docs/manual/development-zh.md) · [English](docs/manual/development.md) - **Private AI Verification 私有 AI 验证** — [中文](docs/manual/private-ai-verification.md) · [English](docs/manual/private-ai-verification-en.md) - **Flagship Apps Spec 旗舰应用规格** — [中文](docs/flagship-applications.md) · [English](docs/flagship-applications-en.md) - **Enterprise Capabilities 企业能力声明** — [中文](docs/enterprise-capabilities.md) · [English](docs/enterprise-capabilities-en.md) - **Compliance Mapping 合规映射** — [中文](docs/manual/compliance-mapping.md) · [English](docs/manual/compliance-mapping-en.md) - **Product Language 产品语言词汇表** — [中文](docs/manual/product-language.md) · [English](docs/manual/product-language-en.md) - **Architecture Boundary 架构边界** — [中文](docs/architecture-boundary.md) · [English](docs/architecture-boundary-en.md) - **Authorization Architecture 权限架构** — [中文](docs/authorization-architecture.md) · [English](docs/authorization-architecture-en.md) - **External system integration 外部系统集成** - **AI Bridge 存量系统 AI 化** — [中文](docs/manual/ai-bridge.md) · [English](docs/manual/ai-bridge-en.md) - **Capability Declaration 轻量能力声明** — [中文](docs/manual/capability-declaration.md) · [English](docs/manual/capability-declaration-en.md) - **External CRM Demo 外部 CRM 接入演示** — [中文](docs/manual/external-crm-demo.md) · [English](docs/manual/external-crm-demo-en.md) - **Framework Adapter Agent 框架接入** — [中文](docs/manual/framework-adapter.md) · [English](docs/manual/framework-adapter-en.md) - **Java Starter (Spring Boot)** — turn Java/Spring methods into governed KeelBase AI tools with `@KeelbaseTool`: delegated identity, read/write confirmation, audit and revocation are all handled by the KeelBase runtime. → [GitHub: rain6fish/KeelBase-java-starter](https://github.com/rain6fish/KeelBase-java-starter) - **Customer scenario — legacy Java CRM × LangChain4j agent 客户场景样板** — one-page topology + phased PoC plan (bilingual) → [integrator-kit/java-crm-langchain4j-solution.md](docs/integrator-kit/java-crm-langchain4j-solution.md) - [CLAUDE.md](CLAUDE.md) (architecture & conventions) · [AGENTS.md](AGENTS.md) (AI build rules) · [SECURITY.md](SECURITY.md) - **Threat Model & Trust Boundaries 威胁模型与信任边界** — [中文](docs/security/threat-model.md) · [English](docs/security/threat-model-en.md) - **Versioning 版本策略（公开版本计划）** — [docs/versioning.md](docs/versioning.md)（中英双语） - **Explore all capabilities →** [docs/](docs/) --- ## 🤝 Community & Contributing - [Contributing](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · **Apache-2.0** licensed - **Issues & feature requests** → [github.com/rain6fish/KeelBase/issues](https://github.com/rain6fish/KeelBase/issues) - **Article series** → [Series index in Discussions](https://github.com/rain6fish/KeelBase/discussions/93) — AI Execution Governance · AI Audit Evidence - Demo accounts: `alex/Alex@2026$Demo` (workbench / mobile) · `admin/Admin@2026$KeelBase` (Admin Console) — consistent across all environments ## Repositories | Directory | Description | |-----------|-------------| | `Server-NestJS/` | NestJS backend (REST API) | | `Front-Flutter/` | Flutter main app (iOS / Android / Web) | | `Front-Taro/` | Taro H5 / mini-program app | | `Web-Admin-Vue/` | Web host — workbench + admin console, one shell (Vue3 + Element Plus) | | `Web-Admin-React/` | Admin console React preview (React 19 + MUI) | | `docs/` | Specs, requirements, manuals | ## Tech Stack Flutter 3.x · Vue3 + Element Plus · React 19 (preview) · NestJS 11 + TypeORM · SQLite / PostgreSQL · Redis + BullMQ · JWT + CASL · OpenAI-compatible LLMs (DeepSeek / Qwen / OpenAI / Claude / Gemini) · pino + Prometheus + OpenTelemetry · Docker / Nginx · CI (GitHub Actions)