lantern

<p align="center"> <img src="./docs/images/readme/hero.png" width="100%" alt="Lantern AI: A lamp to help you polish your comic story"> </p> <p align="center"> <img src="https://img.shields.io/badge/status-Continuously%20Developing-F2B84B" alt="Continuously Developing"> <a href="./LICENSE"><img src="https://img.shields.io/badge/open%20source-MIT-2E8B57" alt="Open source under the MIT License"></a> <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows-5B8DEF" alt="macOS and Windows"> <img src="https://img.shields.io/badge/Node.js-%3E%3D22.13-43853D" alt="Node.js 22.13 or newer"> </p> <p align="center"> <a href="https://github.com/lanseqingling/lantern/releases/latest">Download</a> · <a href="#Quick-Start">Quick Start</a> · <a href="#Current-Capability-Status">Current Capabilities</a> · <a href="./docs/README.md">Documentation</a> · <a href="#Accessing-External-Agents-with-MCP-and-Skill">MCP + Skill</a> </p> Lantern AI is an AI-powered comic creation workstation designed for individual comic creators. It integrates story, characters, scenes, storyboards, page layout, single-panel refinement, preview, and export into a continuously editable creative space, allowing product-internal and external agents to reuse the same creative capabilities and work boundaries through MCP and Skill. ## Product Design Lantern is based on the LCD work protocol, supporting collaboration between creators and agents within a unified comic canvas and controlled editing boundaries: - LCD Work Protocol: LCD uniformly expresses pages, panels, layers, panel content, and fixed asset versions, with the workstation, candidate preview, reading, and export sharing the same work facts. - Comic Canvas: Pages or scrolling sections are located in the center of the workstation, with assets, storyboards, reference images, and agent conversations revolving around the work; reference images only enter the final product after being explicitly placed into panels or pages. - Controlled Editing: UI and product-internal and external agents share semantic capabilities and work boundaries; ordinary editing can be undone, and generated, structured, and multi-object results first form candidates, which are then decided by the creator. ```text Workbench / Built-in Agent / External Agent (MCP + Skill) ↓ Controlled Semantic Capability ↓ Reversible Work Draft or Pending Candidate ↓ LCD Work ↓ Preview, Save, and Export ``` <p align="center"> <img src="./docs/images/readme/workbench-overview.png" width="100%" alt="Lantern AI Comic Workbench Main Interface"> </p> <p align="center">_{Comic Composition and Agent Collaboration Workbench}</p> ## Current Capability Status `✅` Accessed　`🟡` Partially Accessed　`❌` Not Accessed | Capability | UI Editor | Built-in Agent | MCP | |---|:---:|:---:|:---:| | Comic, episode, and story setting management | ✅ | ❌ | ✅ | | Asset card and multi-image management | ✅ | ❌ | ✅ | | Storyboard item editing | ✅ | ✅ | ❌ | | Text, cover, transition page, and scrolling section management | ✅ | ❌ | ❌ | | Panel structure, single-page and double-page layout | ✅ | ❌ | ❌ | | Image upload, placement, and cropping | ✅ | ❌ | 🟡 | | Dialogue, speech bubbles, and page content | ✅ | ❌ | ❌ | | Panel image, character, and scene asset generation | ✅ | ✅ | ❌ | | Candidate preview, application, and conflict protection | ✅ | ✅ | 🟡 | | Reading preview, import, and export | ✅ | ❌ | ❌ | | In-panel effects and performance-type speech bubbles | 🟡 | ❌ | ❌ | | Single-panel refinement | ❌ | ❌ | ❌ | | Page layout, multi-page, and multi-object generation | ❌ | ❌ | ❌ | | Dialogue AI, reading rhythm, and professional composition | ❌ | ❌ | ❌ | | Comic templates | ❌ | ❌ | ❌ | | Single-panel understanding | ❌ | ❌ | ❌ | | Full-page understanding | ❌ | ❌ | ❌ | | Comic analysis | ❌ | ❌ | ❌ | The table only shows the current entry coverage; specific splits, ranges, and differences between the three ends can be found in [Comic Capability Matrix](./docs/capabilities.md). ## Quick Start > Requires Node.js 22.13 or higher with npm. Current release verification covers macOS and Windows. It is recommended to download `lantern-<version>-source.zip` and the same version of `SHA256SUMS` from [GitHub Releases](https://github.com/lanseqingling/lantern/releases/latest). You can also directly obtain the source code: ```bash git clone https://github.com/lanseqingling/lantern.git cd lantern ``` Launch the application in the extracted or cloned directory: ```bash npm start ``` The first launch will prepare and lock dependencies and initialize local data. The workstation will open [http://localhost:18788](http://localhost:18788) by default. <details> <summary>Verifying the Downloaded Release Package</summary> macOS: ```bash shasum -a 256 -c SHA256SUMS ``` Windows PowerShell: ```powershell $archive = Get-ChildItem .\lantern-*-source.zip | Select-Object -First 1 $expected = (Get-Content .\SHA256SUMS).Split()[0].ToLower() $actual = (Get-FileHash $archive -Algorithm SHA256).Hash.ToLower() $actual -eq $expected ``` Verify and then extract the source code package. </details> ## Accessing External Agents with MCP and Skill To use Lantern with a compatible local agent, start Lantern and then run the agent in the Lantern directory: ```bash ./lantern agent:install ``` On Windows, use `lantern.cmd agent:install`. The command will identify the current agent, install the Lantern application-level Skill, and register the local MCP. Agents can only use the controlled capabilities explicitly opened by Lantern; after Lantern upgrades, port or credential changes, repeat the same command to synchronize. For detailed boundaries, see [Agent](./docs/agent.md) and [External Agent Access](./docs/external-agent.md). ## Running and Data In the source code or release directory, use `./lantern <command>` on macOS and `lantern.cmd <command>` on Windows. To execute `lantern` directly in any directory, run `npm link` once in the Lantern directory. | Command | Purpose | |---|---| | `./lantern start` | Start Lantern | | `./lantern status` | View current running status | | `./lantern stop` | Stop local services managed by Lantern | | `./lantern doctor` | Check environment, configuration, database, object files, and service status | | `./lantern agent:install` | Install or synchronize MCP and Skill | | `./lantern backup:create` | Create a consistent backup | | `./lantern backup:restore <backup-file>` | Restore a consistent backup | | System | Default Data Directory | |---|---| | macOS | `~/Library/Application Support/Lantern` | | Windows | `%APPDATA%\Lantern` | `lantern.db` saves works and task states, `objects/` saves images and export files, `config/` saves running configurations and model keys, and `logs/` saves logs. Deleting the installation directory or replacing the source code package will not delete these work data. Lantern launched from the GitHub Release source code package will check for the latest official version in the background after startup, with the same check result retained for 30 minutes. The settings page allows manual checks and one-click updates: Lantern downloads the Release ZIP, verifies `SHA256SUMS`, and completes extraction before replacing service files and restarting; the work data directory does not participate in the replacement. Git development directories and manually crafted source code directories without release markers will not be automatically overwritten. ### Backup and Restore Backups include works, work drafts, messages, tasks, candidates, snapshots, and local object files, excluding model keys, installation tokens, logs, or temporary files. Stop Lantern before backup and restore: ```bash ./lantern stop ./lantern backup:create ./lantern backup:restore "/path/to/lantern-backup-<time>.zip" ``` Verification will be performed before restoration; verification failure will not replace the current work. <details> <summary>Overwriting Running Settings</summary> | Variable | Purpose | |---|---| | `LANTERN_DATA_DIR` | Specify data directory | | `WEB_PORT` | Specify web port | | `API_PORT` | Specify local API port | | `LANTERN_NO_OPEN=1` | Do not open the browser automatically after startup | macOS example: ```bash LANTERN_DATA_DIR="$HOME/LanternData" WEB_PORT=3100 npm start ``` </details> ## Diagnosis and Support Scope When encountering startup or data issues, run: ```bash ./lantern doctor ``` The `doctor` checks Node.js version, data directory write permission, provider configuration permission, SQLite integrity, referenced object files, and running service health status, without displaying model keys or installation tokens. <details> <summary>Further Troubleshooting</summary> 1. Confirm that the web and API ports in `config/runtime.json` are not occupied. 2. View `logs/api.log` and `logs/web.log` in the data directory. 3. After correcting the issue, rerun `./lantern start`. </details> The current release unit is a runnable source code package, and no independent graphical installer is provided. Official releases are based on the actual verification results of GitHub Actions; current verification covers macOS 14 and Windows Server 2022, and Linux is not included in the support scope. ## Development and Building Development mode uses the same local data and service boundaries as formal startup: ```bash ./lantern dev ``` Common verification commands: ```bash ./lantern typecheck ./lantern test ./lantern test:integration ./lantern lint ./lantern build ``` On Windows, replace `./lantern` with `lantern.cmd`. Create distributable source code ZIP and SHA-256 verification files: ```bash ./lantern package:release ``` The output is written to `release/lantern-<version>-source.zip` and `release/SHA256SUMS`. After pushing a `v<version>` tag consistent with `package.json`, GitHub Actions will verify, package, and create a GitHub Release. ## Architecture and Documentation ```text Web (React / Vinext) → Fastify API → Domain Service / Capability → SQLite / Prisma → Local Task Runner → Model Provider → Local Object Storage ``` - `apps/web` is the browser workstation, and `apps/api` is the local API service listening only to loopback. - `packages/shared` provides LCD, workspace commands, and shared contracts; `packages/editor-core` and `packages/layout-engine` provide deterministic editing and page layout capabilities. - `packages/server` is responsible for local persistence and object storage; `packages/agent-runtime` is responsible for agent context, tasks, and model adaptation. Web UI, built-in agents, and external agents share domain services, editor capabilities, and work writing rules. | Document | Content | |---|---| | [Documentation Entrance](./docs/README.md) | Reading sequence of product, editor, LCD, and agent documentation | | [LCD](./docs/lcd.md) | Work structure, coordinates, layers, resource references, and write invariants | | [Agent](./docs/agent.md) | Agent capabilities, context, tasks, candidates, and extension boundaries | | [Development Boundary](./AGENTS.md) | Repository navigation, stable architecture boundaries, and delivery requirements | ## License and Feedback Lantern is open-sourced under the [MIT License](./LICENSE). If you encounter issues or wish to submit feature suggestions, use [GitHub Issues](https://github.com/lanseqingling/lantern/issues). Do not publicly disclose model keys, installation tokens, local paths, or unpublicized work content before submission.