feat(lite): add FlowLLM Lite CLI runner with BaseFlow and BaseConfig

- Introduce flowllm.lite module with BaseConfig and BaseFlow classes
- Add CLI interface with 'fl' command for lightweight flow execution
- Implement flow registration system with @register decorator
- Create demo flow example showing config-driven execution
- Add comprehensive README documentation for FlowLLM Lite usage
- Register 'fl' command in pyproject.toml with claude-agent-sdk dependency
- Remove unused file I/O constants from flowllm/constants.py
- Update main README with minimal CLI flow section and improved formatting

Author: jinliyl

README.md

@@ -18,20 +18,29 @@
   <strong>FlowLLM: Build LLM applications with ease.</strong><br>
 </p>
 
-FlowLLM is a configuration-driven LLM application framework that organizes workflows, service entrypoints, and long-lived components with **Service, Job, Step, and Component**.
+FlowLLM is a configuration-driven LLM application framework that organizes workflows, service entrypoints, and
+long-lived components with **Service, Job, Step, and Component**.
 
-## Core Features
+## ✨ Core Features
 
 - **Configuration-driven**: Starts from `flowllm/config/default.yaml`, with config files and dot-notation overrides.
 - **Unified path**: `CLI / Client -> Service -> Application -> Job -> Step -> Component`.
 - **Flexible Jobs**: Supports sync, streaming, background, and scheduled tasks exposed through HTTP or MCP.
-- **Pluggable components**: Extend Steps, Services, Clients, LLMs, Embeddings, Embedding Stores, and Agent Wrappers through registry `R`.
+- **Pluggable components**: Extend Steps, Services, Clients, LLMs, Embeddings, Embedding Stores, and Agent Wrappers
+  through registry `R`.
+
+## 🆕 Minimal CLI Flow
+
+FlowLLM also includes `flowllm.lite`, a tiny local CLI flow runner for scripts that do not need the full service
+framework.
+It maps `fl --action --field value` to a Pydantic config and a small ordered `BaseFlow`.
+See [FlowLLM Lite](flowllm/lite/README.md) for the full minimal CLI flow design.
 
 <p align="center">
   <img src="docs/figure/flowllm-architecture.svg" alt="FlowLLM Architecture" width="92%">
 </p>
 
-## Quick Start
+## 🚀 Quick Start
 
 ### Installation
 
@@ -63,7 +72,8 @@ pip install -e ".[full]"
 flowllm start
 ```
 
-The default service address is `127.0.0.1:2333`, and the default workspace is `.flowllm/`. Startup automatically creates:
+The default service address is `127.0.0.1:2333`, and the default workspace is `.flowllm/`. Startup automatically
+creates:
 
 ```text
 .flowllm/
@@ -80,7 +90,7 @@ flowllm start workspace_dir=/tmp/flowllm-demo service.host=127.0.0.1 service.por
 
 See the [Quick Start](docs/en/quick_start.md) for more startup and invocation examples.
 
-## Calling Jobs
+## 🧩 Calling Jobs
 
 After the service starts, CLI commands other than `start` call server-side Jobs with the same name through the client:
 
@@ -112,18 +122,19 @@ curl -N http://127.0.0.1:2333/stream_demo \
 
 Built-in Jobs:
 
-| Job | Backend | Description |
-| --- | --- | --- |
-| `version` | `base` | Returns the FlowLLM package version. |
-| `health_check` | `base` | Returns a component health-check summary. |
-| `help` | `base` | Lists registered Jobs and their metadata. |
-| `demo` | `base` | Two-step echo example. |
-| `add` | `base` | Adds two numbers. |
-| `stream_demo` | `stream` | Streams the input text character by character. |
+| Job            | Backend  | Description                                    |
+|----------------|----------|------------------------------------------------|
+| `version`      | `base`   | Returns the FlowLLM package version.           |
+| `health_check` | `base`   | Returns a component health-check summary.      |
+| `help`         | `base`   | Lists registered Jobs and their metadata.      |
+| `demo`         | `base`   | Two-step echo example.                         |
+| `add`          | `base`   | Adds two numbers.                              |
+| `stream_demo`  | `stream` | Streams the input text character by character. |
 
-## Configuration
+## ⚙️ Configuration
 
-The default configuration is located at `flowllm/config/default.yaml`. Root configuration sections include application parameters, service, Jobs, and Components:
+The default configuration is located at `flowllm/config/default.yaml`. Root configuration sections include application
+parameters, service, Jobs, and Components:
 
 ```yaml
 service:
@@ -159,24 +170,25 @@ You can also specify a YAML or JSON configuration file:
 flowllm start config=/path/to/app.yaml
 ```
 
-Configuration parsing supports `${VAR}`, `${VAR:-default}`, booleans, numbers, JSON lists and dictionaries, and automatic `null` conversion.
+Configuration parsing supports `${VAR}`, `${VAR:-default}`, booleans, numbers, JSON lists and dictionaries, and
+automatic `null` conversion.
 
-## Code Framework
+## 🏗️ Code Framework
 
 FlowLLM's core layering is:
 
 ```text
 CLI / Client -> Service -> Application -> Job -> Step -> Component
 ```
 
-| Layer | Role |
-| --- | --- |
+| Layer         | Role                                                                                                                            |
+|---------------|---------------------------------------------------------------------------------------------------------------------------------|
 | `Application` | Loads configuration, creates the workspace, assembles Service, Components, and Jobs, and starts lifecycles in dependency order. |
-| `Service` | Exposes servable Jobs as HTTP routes or MCP tools. |
-| `Job` | Orchestrates externally callable capabilities or background processes by executing Steps in order. |
-| `Step` | Atomic workflow operation that reads and writes `RuntimeContext`, `Response`, and streaming queues. |
-| `Component` | Long-lived infrastructure such as LLMs, Embeddings, Embedding Stores, and Agent Wrappers. |
-| `Registry` | Global registry `R`, which looks up implementations by `(component_type, backend_name)`. |
+| `Service`     | Exposes servable Jobs as HTTP routes or MCP tools.                                                                              |
+| `Job`         | Orchestrates externally callable capabilities or background processes by executing Steps in order.                              |
+| `Step`        | Atomic workflow operation that reads and writes `RuntimeContext`, `Response`, and streaming queues.                             |
+| `Component`   | Long-lived infrastructure such as LLMs, Embeddings, Embedding Stores, and Agent Wrappers.                                       |
+| `Registry`    | Global registry `R`, which looks up implementations by `(component_type, backend_name)`.                                        |
 
 Minimal example for adding a Step:
 
@@ -211,11 +223,13 @@ jobs:
       - backend: reverse_step
 ```
 
-After adding an implementation, make sure the module is imported in the package `__init__.py`; otherwise, the registration decorator will not run. See the [code framework](docs/en/framework.md) for details.
+After adding an implementation, make sure the module is imported in the package `__init__.py`; otherwise, the
+registration decorator will not run. See the [code framework](docs/en/framework.md) for details.
 
-## MCP Service
+## 🔌 MCP Service
 
-When the service backend is set to `mcp`, FlowLLM exposes non-streaming Jobs with `enable_serve: true` as MCP tools. `StreamJob` is not exposed by MCP Service.
+When the service backend is set to `mcp`, FlowLLM exposes non-streaming Jobs with `enable_serve: true` as MCP tools.
+`StreamJob` is not exposed by MCP Service.
 
 ```yaml
 service:
@@ -227,26 +241,27 @@ service:
 
 MCP transport supports `stdio`, `sse`, and `streamable-http`.
 
-## Documentation
+## 📚 Documentation
 
 - [Quick Start](docs/en/quick_start.md)
 - [Code Framework](docs/en/framework.md)
 - [Contributing](docs/en/contributing.md)
 - [FlowLLM Development Skill](skills/flowllm_dev/SKILL.md)
 
-## Open Source and Contributing
+## 🤝 Open Source and Contributing
 
-FlowLLM is licensed under Apache 2.0. Before contributing, read the [contribution guide](docs/en/contributing.md) and [development skill](skills/flowllm_dev/SKILL.md), then run:
+FlowLLM is licensed under Apache 2.0. Before contributing, read the [contribution guide](docs/en/contributing.md)
+and [development skill](skills/flowllm_dev/SKILL.md), then run:
 
 ```bash
 pre-commit run --all-files
 pytest
 ```
 
-## License
+## 📄 License
 
 This project is open source under the Apache License 2.0. See [LICENSE](./LICENSE) for details.
 
-## Star History
+## ⭐ Star History
 
 [![Star History Chart](https://api.star-history.com/svg?repos=flowllm-ai/flowllm&type=Date)](https://www.star-history.com/#flowllm-ai/flowllm&Date)

README_ZH.md

@@ -20,18 +20,24 @@
 
 FlowLLM 是一个配置驱动的 LLM 应用框架，用 **Service、Job、Step、Component** 组织工作流、服务入口和长期组件。
 
-## 核心特性
+## ✨ 核心特性
 
 - **配置驱动**：默认从 `flowllm/config/default.yaml` 启动，支持配置文件和 dot notation 覆盖。
 - **统一链路**：`CLI / Client -> Service -> Application -> Job -> Step -> Component`。
 - **多种 Job 形态**：支持同步、流式、后台和定时任务，并可通过 HTTP 或 MCP 暴露。
 - **可插拔组件**：通过注册表 `R` 扩展 Step、Service、Client、LLM、Embedding、Embedding Store 和 Agent Wrapper。
 
+## 🆕 极简 CLI Flow
+
+FlowLLM 也包含 `flowllm.lite`，这是一个极简的本地 CLI flow 运行器，适合不需要完整服务框架的脚本场景。
+它把 `fl --action --field value` 映射到 Pydantic config 和一个顺序执行的 `BaseFlow`。
+完整设计见 [FlowLLM Lite](flowllm/lite/README.md)。
+
 <p align="center">
   <img src="docs/figure/flowllm-architecture.svg" alt="FlowLLM Architecture" width="92%">
 </p>
 
-## 快速开始
+## 🚀 快速开始
 
 ### 安装
 
@@ -80,7 +86,7 @@ flowllm start workspace_dir=/tmp/flowllm-demo service.host=127.0.0.1 service.por
 
 更多启动和调用示例见 [快速开始](docs/zh/quick_start.md)。
 
-## 调用 Job
+## 🧩 调用 Job
 
 启动服务后，CLI 的非 `start` 命令会通过 client 调用服务端同名 Job：
 
@@ -112,16 +118,16 @@ curl -N http://127.0.0.1:2333/stream_demo \
 
 内置 Job：
 
-| Job | backend | 说明 |
-| --- | --- | --- |
-| `version` | `base` | 返回 FlowLLM 包版本。 |
-| `health_check` | `base` | 返回组件健康检查摘要。 |
-| `help` | `base` | 列出已注册 Job 及其 metadata。 |
-| `demo` | `base` | 两步 echo 示例。 |
-| `add` | `base` | 两数相加示例。 |
-| `stream_demo` | `stream` | 将输入按字符流式输出。 |
+| Job            | backend  | 说明                     |
+|----------------|----------|------------------------|
+| `version`      | `base`   | 返回 FlowLLM 包版本。        |
+| `health_check` | `base`   | 返回组件健康检查摘要。            |
+| `help`         | `base`   | 列出已注册 Job 及其 metadata。 |
+| `demo`         | `base`   | 两步 echo 示例。            |
+| `add`          | `base`   | 两数相加示例。                |
+| `stream_demo`  | `stream` | 将输入按字符流式输出。            |
 
-## 配置
+## ⚙️ 配置
 
 默认配置位于 `flowllm/config/default.yaml`。配置根节点包括应用参数、服务、Job 和 Component：
 
@@ -161,22 +167,22 @@ flowllm start config=/path/to/app.yaml
 
 配置解析支持 `${VAR}`、`${VAR:-default}`、bool、数字、JSON list/dict 和 `null` 自动转换。
 
-## 代码框架
+## 🏗️ 代码框架
 
 FlowLLM 的核心分层如下：
 
 ```text
 CLI / Client -> Service -> Application -> Job -> Step -> Component
 ```
 
-| 层级 | 作用 |
-| --- | --- |
+| 层级            | 作用                                                         |
+|---------------|------------------------------------------------------------|
 | `Application` | 加载配置，创建 workspace，装配 Service、Component 和 Job，并按依赖顺序启动生命周期。 |
-| `Service` | 将可服务的 Job 暴露为 HTTP 路由或 MCP 工具。 |
-| `Job` | 外部可调用能力或后台流程的编排单元，按顺序执行 Step。 |
-| `Step` | 工作流原子操作，读写 `RuntimeContext`、`Response` 和流式队列。 |
-| `Component` | 长期存在的基础设施，例如 LLM、Embedding、Embedding Store、Agent Wrapper。 |
-| `Registry` | 全局注册表 `R`，按 `(component_type, backend_name)` 查找实现。 |
+| `Service`     | 将可服务的 Job 暴露为 HTTP 路由或 MCP 工具。                             |
+| `Job`         | 外部可调用能力或后台流程的编排单元，按顺序执行 Step。                              |
+| `Step`        | 工作流原子操作，读写 `RuntimeContext`、`Response` 和流式队列。              |
+| `Component`   | 长期存在的基础设施，例如 LLM、Embedding、Embedding Store、Agent Wrapper。  |
+| `Registry`    | 全局注册表 `R`，按 `(component_type, backend_name)` 查找实现。         |
 
 新增 Step 的最小示例：
 
@@ -213,9 +219,10 @@ jobs:
 
 新增实现后要确保模块在包的 `__init__.py` 中被 import，否则注册装饰器不会执行。更多细节见 [代码框架](docs/zh/framework.md)。
 
-## MCP 服务
+## 🔌 MCP 服务
 
-将 service backend 改成 `mcp` 后，FlowLLM 会把非流式、`enable_serve: true` 的 Job 暴露为 MCP tool。`StreamJob` 不会被 MCP Service 暴露。
+将 service backend 改成 `mcp` 后，FlowLLM 会把非流式、`enable_serve: true` 的 Job 暴露为 MCP tool。`StreamJob` 不会被 MCP
+Service 暴露。
 
 ```yaml
 service:
@@ -227,26 +234,27 @@ service:
 
 MCP transport 支持 `stdio`、`sse` 和 `streamable-http`。
 
-## 文档
+## 📚 文档
 
 - [快速开始](docs/zh/quick_start.md)
 - [代码框架](docs/zh/framework.md)
 - [开源与贡献](docs/zh/contributing.md)
 - [FlowLLM 开发 Skill](skills/flowllm_dev/SKILL.md)
 
-## 开源与贡献
+## 🤝 开源与贡献
 
-FlowLLM 使用 Apache 2.0 许可证。贡献前请阅读 [贡献指南](docs/zh/contributing.md) 和 [开发 Skill](skills/flowllm_dev/SKILL.md)，并尽量运行：
+FlowLLM 使用 Apache 2.0 许可证。贡献前请阅读 [贡献指南](docs/zh/contributing.md)
+和 [开发 Skill](skills/flowllm_dev/SKILL.md)，并尽量运行：
 
 ```bash
 pre-commit run --all-files
 pytest
 ```
 
-## License
+## 📄 License
 
 This project is open source under the Apache License 2.0. See [LICENSE](./LICENSE) for details.
 
-## Star 历史
+## ⭐ Star 历史
 
 [![Star History Chart](https://api.star-history.com/svg?repos=flowllm-ai/flowllm&type=Date)](https://www.star-history.com/#flowllm-ai/flowllm&Date)

flowllm/constants.py

@@ -5,11 +5,3 @@
 FLOWLLM_DEFAULT_HOST = "127.0.0.1"
 
 FLOWLLM_DEFAULT_PORT = 2333
-
-# File IO limits and truncation marker.
-DEFAULT_MAX_BYTES = 50 * 1024
-MAX_FILE_READ_BYTES = 200 * 1024 * 1024
-TRUNCATION_NOTICE_MARKER = "<<TRUNCATION_NOTICE>>"
-
-# Oversized images return path & metadata only (no base64).
-DEFAULT_MAX_IMAGE_BYTES = 5 * 1024 * 1024

flowllm/lite/README.md

@@ -0,0 +1,77 @@
+# FlowLLM Lite
+
+`flowllm.lite` is a tiny local CLI flow runner. It is intentionally separate from the full FlowLLM application framework.
+
+It keeps only four concepts:
+
+- `BaseConfig`: define input parameters with Pydantic.
+- `BaseFlow`: hold `config` and `context`, then execute steps in order.
+- `register`: bind an action name to a flow class.
+- `fl`: read an action and CLI arguments, run the flow, and print JSON output.
+
+## Usage
+
+```shell
+fl --list
+fl --demo --x 1 --y 2
+```
+
+Output:
+
+```json
+{"result": 3}
+```
+
+The command format is:
+
+```shell
+fl --action --field value --another-field value
+```
+
+Rules:
+
+- The first argument is the action and must look like `--action`.
+- The remaining arguments must appear in pairs: `--field value`.
+- `-` in CLI argument names is converted to `_` in Python field names.
+- Values are read as strings first, then converted by Pydantic through `BaseConfig`.
+- The final result only includes fields declared in `output_keys`.
+
+## Writing a Flow
+
+```python
+from flowllm.lite import BaseConfig, BaseFlow, register
+
+
+class AddConfig(BaseConfig):
+    x: int
+    y: int
+
+
+@register("add")
+class AddFlow(BaseFlow[AddConfig]):
+    output_keys = ["result"]
+
+    def build_steps(self):
+        return [self.add]
+
+    def add(self):
+        self.context["result"] = self.config.x + self.config.y
+```
+
+Run it:
+
+```shell
+fl --add --x 1 --y 2
+```
+
+## Design Constraints
+
+Lite flow is designed to be direct to read and easy to change:
+
+- One flow class maps to one action.
+- One step is a zero-argument method that reads from `self.config`.
+- Steps pass intermediate values through `self.context`.
+- `build_steps()` declares execution order explicitly.
+- `output_keys` declares final output explicitly.
+
+This implementation does not handle service startup, remote calls, plugin orchestration, complex dependency injection, or streaming protocols. Use the full FlowLLM framework when those capabilities are needed.