by-framework 0.2.2.dev9__tar.gz → 0.2.2.dev11__tar.gz

by_framework-0.2.2.dev11/.codex/hooks.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/map-stop-hook.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

by_framework-0.2.2.dev11/.github/workflows/deploy-smoke-test.yml

@@ -0,0 +1,66 @@
+name: Deploy Smoke Test
+
+# Validates deploy/'s Dockerfile + docker-compose.yml actually deliver a
+# message through the full pipeline - client sends -> Redis control stream
+# -> Worker consumes -> Worker replies -> Redis data stream -> client reads
+# - using examples/echo_worker.py, built from THIS commit's source (not the
+# last PyPI release; see deploy/Dockerfile's BY_FRAMEWORK_SOURCE=local mode).
+# See docs/architecture/production-deployment.md.
+
+on:
+  pull_request:
+    paths:
+      - "deploy/**"
+      - "examples/**"
+      - "src/by_framework/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/deploy-smoke-test.yml"
+  push:
+    branches:
+      - main
+      - master
+    paths:
+      - "deploy/**"
+      - "examples/**"
+      - "src/by_framework/**"
+  workflow_dispatch:
+
+jobs:
+  smoke-test:
+    runs-on: ubuntu-latest
+    env:
+      BY_FRAMEWORK_SOURCE: local
+      WORKER_CLASS: examples.echo_worker.EchoWorker
+      REDIS_HOST: localhost
+      REDIS_PORT: "6379"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Install by-framework (for the verify client script below)
+        run: uv sync
+
+      # --wait blocks until every service with a healthcheck (redis, and now
+      # worker's own /readyz-backed HEALTHCHECK - see
+      # docs/architecture/worker-readiness-endpoint.md) reports healthy, and
+      # fails the step if that doesn't happen in time. This is the actual
+      # verification that the readiness endpoint works end to end in a real
+      # container - not just that the Python contract tests pass.
+      - name: Build and start Redis + Worker via deploy/docker-compose.yml
+        run: |
+          docker compose -f deploy/docker-compose.yml up --build -d --wait --wait-timeout 60
+
+      - name: Send a message and verify the Worker echoes it back
+        run: uv run python examples/send_and_verify.py
+
+      - name: Worker logs
+        if: always()
+        run: docker compose -f deploy/docker-compose.yml logs worker
+
+      - name: Tear down
+        if: always()
+        run: docker compose -f deploy/docker-compose.yml down -v

by_framework-0.2.2.dev11/.github/workflows/verify.yml

@@ -0,0 +1,16 @@
+name: verify
+on: [push, pull_request]
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - name: resolve map base ref
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            echo "MAP_BASE_REF=${{ github.event.pull_request.base.sha }}" >> "$GITHUB_ENV"
+          elif git cat-file -e "${{ github.event.before }}" 2>/dev/null; then
+            echo "MAP_BASE_REF=${{ github.event.before }}" >> "$GITHUB_ENV"
+          fi
+      - run: bash scripts/verify.sh

by_framework-0.2.2.dev11/AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

by_framework-0.2.2.dev11/CLAUDE.md

@@ -0,0 +1,205 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) and Codex when working with code in this repository. (`AGENTS.md` is a symlink to this file — one copy, no drift between agent ecosystems.)
+
+## North Star
+
+`by-framework-python` lets agent workloads scale horizontally across Redis
+Streams without losing execution identity or silently corrupting shared
+state under partial failure — a worker restart, Cluster-mode operation, a
+misconfigured plugin, or a delayed `ask_user` reply. When a trade-off isn't
+covered by an explicit rule, prefer a change that fails loudly (raise,
+warn-log) or degrades safely (no-op, skip) over one that could silently
+drop, duplicate, orphan, or misroute an execution, a message, or a
+heartbeat — this repo's fix-commit history is dominated by exactly that
+failure shape.
+
+## Core mental model
+
+1. **Control plane vs. data plane are separate Redis Streams, never
+   conflated.** Commands travel on per-agent-type control streams
+   (competitive consume via consumer groups); output travels on
+   session-scoped data streams. Misrouting one onto the other silently
+   breaks delivery.
+2. **An execution's identity must survive suspend/resume, not just
+   request/response.** A task can suspend (`ask_user`, or a `call_agent`
+   hop) and later resume via a `RESUME` dispatch that must reattach to the
+   *original* `execution_id` via the registry lookup — treating every
+   dispatch as "mint a new execution" silently orphans the suspended one.
+   This was the single most-recurring bug class in this repo's history (fix
+   90764e1, closing #75/#76/#77).
+
+## Project Overview
+
+`by-framework` is a distributed, high-performance Agent scheduling engine built on Redis Streams. It provides a framework for building AI agents with self-driven orchestration and sandbox isolation capabilities.
+
+## Build Commands
+
+```bash
+# Install dependencies
+make install
+
+# Format code (isort + ruff + pyink)
+make format
+
+# Lint code (pylint + ruff)
+make lint
+
+# Run all tests
+make test
+
+# Run a single test file
+uv run pytest tests/worker/test_gateway_worker.py
+
+# Run tests matching a pattern
+uv run pytest -k "test_name_pattern"
+```
+
+## Architecture
+
+### Core Data Flow
+
+```
+Client → Redis Input MQ (queue:ctrl:{agent_type}) → GatewayWorker
+                                                              ↓
+                                                       Redis Data MQ (queue:data:stream)
+                                                              ↓
+                                                         WebSocket Backend
+```
+
+### Key Components
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| `GatewayWorker` | `src/by_framework/worker/worker.py` | Abstract base class for workers; implement `get_capabilities()` and `process_command()` |
+| `AgentContext` | `src/by_framework/worker/context.py` | Runtime context for task execution; emits chunks, states, artifacts; calls other agents |
+| `run_worker()` | `src/by_framework/worker/app.py` | Main entry point for starting a worker |
+| `GatewayClient` | `src/by_framework/client/client.py` | Sends commands to Redis Streams |
+| `ByaiGatewayClient` | `src/by_framework/client/byai_client.py` | GatewayClient with ByaiMessageInterceptor |
+| `Plugin` | `src/by_framework/core/extensions/plugin.py` | Abstract base for extensible plugins with lifecycle hooks |
+| `PluginRegistry` | `src/by_framework/core/extensions/registry.py` | Manages plugin registration and discovery |
+
+### Protocol System
+
+Commands and events are defined in `src/by_framework/core/protocol/`:
+- `commands.py` - `AskAgentCommand`, `CancelTaskCommand`, `ResumeCommand`
+- `events.py` - `StreamChunkEvent`, `StateChangeEvent`, `ArtifactEvent`
+- `message_header.py` - `MessageHeader` with session_id, trace_id, message_id
+
+### Plugin Lifecycle Hooks
+
+Plugins can implement: `on_worker_startup`, `on_worker_shutdown`, `on_task_start`, `on_task_complete`, `on_task_error`, `on_task_cancel`
+
+### Redis Key Patterns
+
+- `byai_gateway:ctrl:agent_type:{agent_type}` — Control stream; competitive consume per agent type
+- `byai_gateway:ctrl:worker:{worker_id}` — Direct per-worker routing
+- `byai_gateway:session:{session_id}:data_stream` — Session-scoped output events
+- `byai_gateway:registry:worker:online:{worker_id}` — Heartbeat TTL key
+- `byai_gateway:task_group:{group_id}` — Scatter-gather group tracker
+
+Connection precedence and Cluster-mode/key-schema-versioning details: see
+the Reference map below, not repeated here.
+
+## Test Structure
+
+Tests are organized by module in `tests/`:
+- `tests/common/` - Logger, redis client, config, exceptions
+- `tests/core/` - Registry, protocol, history
+- `tests/worker/` - Worker, context, processor, sandbox
+- `tests/client/` - Client functionality
+- `tests/plugin/` - Plugin system and discovery
+- `tests/integration/` - Cross-component flows (scatter-gather, callbacks, ask_user)
+
+## Code Style
+
+- **Import sorting**: isort
+- **Formatting**: ruff-format + pyink
+- **Linting**: pylint (with `pylintrc`) + ruff
+- **Testing**: pytest with pytest-asyncio
+
+Pre-commit hooks are configured in `.pre-commit-config.yaml` and run isort, ruff, pylint, pyink, and general checks.
+
+## Development Notes
+
+- Package is at `src/by_framework/` (configured in `pyproject.toml`)
+- `pythonpath = ["src"]` is set in pytest config
+- Redis 7.0+ is required for Streams functionality
+- Worker capabilities are declared via `get_capabilities()` and used for task routing
+
+## Cross-cutting invariants
+
+- **An explicitly-passed kwarg must never be silently discarded because a
+  config object's corresponding field defaults to `None`/"unset."** Incident:
+  fix 6ec070c — `redis_client.init_redis()` let `config.max_connections`
+  (default `None`, meaning "not specified") unconditionally override an
+  explicitly-passed `max_connections` kwarg, discarding
+  `worker/app.py`'s `max_concurrency`-derived pool size. Correct form:
+  `if config.<field> is not None: value = config.<field>` — only let the
+  config object win when it was actually set. No dedicated guard yet;
+  applies to any new `Optional[...] = None` config field.
+
+- **Plugin/trace hook code must fail soft (log + return/`None`), never raise
+  into the primary task-execution or worker-startup path.** Incident: fix
+  8b5bf93 — `LangfusePlugin._build_default_tracer()` used to `raise
+  RuntimeError` when Langfuse env vars were unset, which would have broken
+  worker startup for anyone with the plugin auto-discovered but
+  unconfigured; changed to log + return `None`, with every call site guarded.
+  Reinforced by `core/extensions/registry.py`'s `_execute_hook()`, which
+  wraps every plugin lifecycle hook in try/except + timeout handling so no
+  hook exception ever propagates to the caller. Correct form: any new
+  plugin/trace integration point must degrade to a no-op (logged) rather
+  than raising.
+
+## Iron rules
+
+<!-- No process rules (test invocation, release steps) have caused an
+     incident yet — entries land here only via a real trigger (see
+     "Maintaining this map" below), never invented up front. -->
+
+## Reference map
+
+| When you're working on... | Read first |
+|---|---|
+| any source file | `docs/architecture/KEY_FILES.md` — find the file's entry |
+| Redis connection setup, cluster-mode, or key-schema versioning (`RedisConfig`, `RedisKeys`, `_get_redis()`, admin-index writes) | `docs/architecture/redis-cluster-mode.md` |
+| Worker deployment/production-readiness — README's 部署 section, `__main__.py` CLI flags, `run_worker()`'s signature, or shutdown/signal handling | `docs/architecture/production-deployment.md` |
+| Worker readiness/health-check endpoint (`WorkerHealthServer`, `/readyz`, `--health-port`) — building it, or touching anything that changes what "ready" means | `docs/architecture/worker-readiness-endpoint.md` |
+
+## Maintaining this map
+
+The map grows only on triggers — never speculatively:
+
+1. **After an incident** — write the postmortem in `docs/incidents/`
+   (append-only is legal there), then ask "what grep would have prevented
+   this" → a new guard, or an append to an existing one.
+2. **After editing a load-bearing file** — rewrite its KEY_FILES entry in
+   place. Behaviour changed means the entry changes; never append history.
+3. **Same mistake twice** — triage into exactly one layer:
+   machine-checkable → guard in `scripts/verify.sh`'s CHECKS;
+   cross-cutting → quad bullet above;
+   domain detail → docs/ file + a Reference-map row.
+4. **Explored a subsystem to do a task and no doc held it** — diarize it into
+   `docs/architecture/<x>.md` + a Reference-map row while the understanding is
+   hot. Don't make the next agent re-read the same files to learn the same
+   thing.
+5. **A rule is already known — no incident needed** — someone states a
+   requirement up front (deployment steps, a naming convention, whatever).
+   Don't wait for it to bite twice: triage it right now, same three-way
+   split as every other find. Machine can check it → write a guard per
+   `docs/architecture/GUARD_AUTHORING.md`, register it in `verify.sh`'s
+   `CHECKS`. Only judgement can check it → a quad-bullet above — **unless
+   two or more existing bullets already cover the same concern** (e.g.
+   several deployment steps), in which case lift the whole cluster into a
+   `docs/` file + Reference-map row instead of adding a third bullet. Same
+   move as "Diarize a subsystem" for file entries: one doc per concern
+   beats a pile of bullets that only gets noticed at the next size-cap
+   surgery. Domain detail from the start → a `docs/` file + a Reference-map
+   row, no waiting to accumulate.
+
+Guards: `bash scripts/verify.sh` before every push (kept under 30s).
+Growth enforcement: `check-entry-freshness.sh` warns in verify on stale
+entries, unindexed new source files, and untriaged fix commits; the Stop
+hook (`scripts/map-stop-hook.sh`, wired into `.claude/settings.json` and
+`.codex/hooks.json`) blocks session end once until stale entries are
+rewritten or declared unchanged.

{by_framework-0.2.2.dev9 → by_framework-0.2.2.dev11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: by-framework
-Version: 0.2.2.dev9
+Version: 0.2.2.dev11
 Summary: 分布式 Agent 调度框架
 License-File: LICENSE
 Requires-Python: >=3.12
@@ -250,6 +250,13 @@ async def main():
 asyncio.run(main())
 ```
 
+A runnable version of this pair lives at
+[`examples/echo_worker.py`](examples/echo_worker.py) (Worker) and
+[`examples/send_and_verify.py`](examples/send_and_verify.py) (client — blocks
+until it sees the echoed reply) — the same pair `deploy/`'s CI smoke test
+drives end to end, see
+[`docs/architecture/production-deployment.md`](docs/architecture/production-deployment.md).
+
 ---
 
 ## Core Concepts
@@ -602,7 +609,7 @@ Tests are organized by module under `tests/`:
 
 ```bash
 # 1. Start Redis
-docker run -d --name by-redis -p 6379:6379 registry:7-alpine
+docker run -d --name by-redis -p 6379:6379 redis:7-alpine
 
 # 2. Start a Worker
 python -m by_framework \
@@ -621,11 +628,27 @@ python -m by_framework --worker-class my_agent.MyAgent --worker-id worker-02 &
 python -m by_framework --worker-class my_agent.MyAgent --worker-id worker-03 &
 ```
 
+`&` is fine for a quick local check but isn't real process supervision — for
+an actual deployment, use the reference Dockerfile, Compose file, and
+Kubernetes Deployment under [`deploy/`](deploy/):
+
+```bash
+# Docker Compose — N supervised replicas, distinct worker ids, restart policy
+docker compose -f deploy/docker-compose.yml up --build --scale worker=3
+
+# Kubernetes — same idea as a Deployment
+kubectl apply -f deploy/kubernetes/worker-deployment.yaml
+```
+
+The CLI also exposes `--redis-password`, `--redis-username`, `--redis-mode`,
+and `--redis-cluster-nodes` (all mirrored by the `REDIS_*` env vars used in
+the Compose/Kubernetes examples above) — see `python -m by_framework --help`.
+
 ### Reliability
 
 - **Message persistence:** Messages are stored in Redis Streams until explicitly acknowledged (`XACK`). Unacknowledged messages are redelivered on Worker restart.
 - **Durable config:** Agent config snapshots are persisted to Redis, so a restarted Worker recovers the last-known plugin configuration.
-- **Gradual shutdown:** `WorkerRunner` drains in-flight tasks before shutting down, acknowledging completed work.
+- **Graceful shutdown:** `WorkerRunner` drains in-flight tasks before shutting down, acknowledging completed work. This is wired to both `SIGINT` (Ctrl+C) and `SIGTERM` — the signal `docker stop`/Kubernetes pod termination actually send — so it fires under real container orchestration, not just an interactive terminal. Give it enough `stop_grace_period`/`terminationGracePeriodSeconds` to cover your longest task (see the `deploy/` examples), since a hard `SIGKILL` after the grace period skips the drain entirely.
 - **Separate data path:** Data output goes to session-scoped streams independently of control, so backend consumers are decoupled from Worker scaling.
 
 ### Logging

{by_framework-0.2.2.dev9 → by_framework-0.2.2.dev11}/README.md

@@ -221,6 +221,13 @@ async def main():
 asyncio.run(main())
 ```
 
+A runnable version of this pair lives at
+[`examples/echo_worker.py`](examples/echo_worker.py) (Worker) and
+[`examples/send_and_verify.py`](examples/send_and_verify.py) (client — blocks
+until it sees the echoed reply) — the same pair `deploy/`'s CI smoke test
+drives end to end, see
+[`docs/architecture/production-deployment.md`](docs/architecture/production-deployment.md).
+
 ---
 
 ## Core Concepts
@@ -573,7 +580,7 @@ Tests are organized by module under `tests/`:
 
 ```bash
 # 1. Start Redis
-docker run -d --name by-redis -p 6379:6379 registry:7-alpine
+docker run -d --name by-redis -p 6379:6379 redis:7-alpine
 
 # 2. Start a Worker
 python -m by_framework \
@@ -592,11 +599,27 @@ python -m by_framework --worker-class my_agent.MyAgent --worker-id worker-02 &
 python -m by_framework --worker-class my_agent.MyAgent --worker-id worker-03 &
 ```
 
+`&` is fine for a quick local check but isn't real process supervision — for
+an actual deployment, use the reference Dockerfile, Compose file, and
+Kubernetes Deployment under [`deploy/`](deploy/):
+
+```bash
+# Docker Compose — N supervised replicas, distinct worker ids, restart policy
+docker compose -f deploy/docker-compose.yml up --build --scale worker=3
+
+# Kubernetes — same idea as a Deployment
+kubectl apply -f deploy/kubernetes/worker-deployment.yaml
+```
+
+The CLI also exposes `--redis-password`, `--redis-username`, `--redis-mode`,
+and `--redis-cluster-nodes` (all mirrored by the `REDIS_*` env vars used in
+the Compose/Kubernetes examples above) — see `python -m by_framework --help`.
+
 ### Reliability
 
 - **Message persistence:** Messages are stored in Redis Streams until explicitly acknowledged (`XACK`). Unacknowledged messages are redelivered on Worker restart.
 - **Durable config:** Agent config snapshots are persisted to Redis, so a restarted Worker recovers the last-known plugin configuration.
-- **Gradual shutdown:** `WorkerRunner` drains in-flight tasks before shutting down, acknowledging completed work.
+- **Graceful shutdown:** `WorkerRunner` drains in-flight tasks before shutting down, acknowledging completed work. This is wired to both `SIGINT` (Ctrl+C) and `SIGTERM` — the signal `docker stop`/Kubernetes pod termination actually send — so it fires under real container orchestration, not just an interactive terminal. Give it enough `stop_grace_period`/`terminationGracePeriodSeconds` to cover your longest task (see the `deploy/` examples), since a hard `SIGKILL` after the grace period skips the drain entirely.
 - **Separate data path:** Data output goes to session-scoped streams independently of control, so backend consumers are decoupled from Worker scaling.
 
 ### Logging

{by_framework-0.2.2.dev9 → by_framework-0.2.2.dev11}/README_zh.md

@@ -221,6 +221,11 @@ async def main():
 asyncio.run(main())
 ```
 
+可运行的完整版本见 [`examples/echo_worker.py`](examples/echo_worker.py)（Worker）和
+[`examples/send_and_verify.py`](examples/send_and_verify.py)（客户端，会一直等到收到回显再退出）——
+`deploy/` 下的 CI 冒烟测试用的就是这一对，见
+[`docs/architecture/production-deployment.md`](docs/architecture/production-deployment.md)。
+
 ---
 
 ## 核心概念
@@ -592,11 +597,27 @@ python -m by_framework --worker-class my_agent.MyAgent --worker-id worker-02 &
 python -m by_framework --worker-class my_agent.MyAgent --worker-id worker-03 &
 ```
 
+`&` 适合本地快速验证，但不是真正的进程编排——实际部署请使用
+[`deploy/`](deploy/) 目录下的参考 Dockerfile、Compose 文件和 Kubernetes
+Deployment：
+
+```bash
+# Docker Compose —— N 个受进程守护的副本，各自独立的 worker id、重启策略
+docker compose -f deploy/docker-compose.yml up --build --scale worker=3
+
+# Kubernetes —— 同样的思路，写成 Deployment
+kubectl apply -f deploy/kubernetes/worker-deployment.yaml
+```
+
+CLI 现在也支持 `--redis-password`、`--redis-username`、`--redis-mode`、
+`--redis-cluster-nodes`（与上面 Compose/Kubernetes 示例里用的 `REDIS_*`
+环境变量一一对应）——见 `python -m by_framework --help`。
+
 ### 可靠性
 
 - **消息持久化：** 消息存储在 Redis Streams 中，直到显式确认（`XACK`）。未确认的消息在 Worker 重启后重新投递。
 - **配置持久化：** Agent 配置快照持久化到 Redis，Worker 重启后恢复上次已知配置。
-- **优雅退出：** `WorkerRunner` 在退出前排空进行中的任务，确认已完成的工作。
+- **优雅退出：** `WorkerRunner` 在退出前排空进行中的任务，确认已完成的工作。这一逻辑同时挂在 `SIGINT`（Ctrl+C）和 `SIGTERM`——也就是 `docker stop`/Kubernetes Pod 终止实际发送的信号——上，因此在真实容器编排下也能触发，而不仅是交互式终端里的 Ctrl+C。请给 `stop_grace_period`/`terminationGracePeriodSeconds` 留出覆盖最长任务耗时的余量（见 `deploy/` 示例），因为宽限期后的强制 `SIGKILL` 会完全跳过排空过程。
 - **数据与控制分离：** 数据输出到会话级 Stream，与 Worker 扩缩容解耦。
 
 ### 日志

by_framework-0.2.2.dev11/deploy/Dockerfile

@@ -0,0 +1,61 @@
+# syntax=docker/dockerfile:1
+#
+# Template Dockerfile for a by-framework Worker. This installs the published
+# `by-framework` package from PyPI and expects YOUR worker code (the module
+# containing your GatewayWorker subclass) to sit next to this Dockerfile in
+# the build context - copy this file into your own project and adjust the
+# COPY line and the default --worker-class below.
+#
+# Build:  docker build -f deploy/Dockerfile -t my-agent-worker .
+# Run:    docker run --rm -e REDIS_HOST=redis my-agent-worker \
+#           --worker-class my_agent.MyAgent
+
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PATH="/opt/venv/bin:${PATH}"
+
+WORKDIR /app
+
+# Pin this in production (e.g. --build-arg BY_FRAMEWORK_VERSION=0.2.2).
+ARG BY_FRAMEWORK_VERSION=""
+# "pypi" (default - for downstream projects) or "local" (used only by this
+# repo's own .github/workflows/deploy-smoke-test.yml, to validate this
+# Dockerfile against a PR's code before it's ever released). Leave this
+# alone unless you're working on by-framework-python itself.
+ARG BY_FRAMEWORK_SOURCE="pypi"
+
+# Replace this with your own worker package/module.
+COPY . /app/worker
+ENV PYTHONPATH=/app/worker
+
+# In "local" mode, /app/worker above IS the by-framework-python checkout, so
+# install it editable from there instead of from PyPI.
+RUN uv venv /opt/venv \
+    && if [ "$BY_FRAMEWORK_SOURCE" = "local" ]; then \
+        uv pip install --python /opt/venv/bin/python -e /app/worker; \
+    else \
+        uv pip install --python /opt/venv/bin/python \
+            "by-framework${BY_FRAMEWORK_VERSION:+==${BY_FRAMEWORK_VERSION}}"; \
+    fi
+
+COPY deploy/entrypoint.sh /entrypoint.sh
+
+# Opt-in readiness endpoint (see
+# docs/architecture/worker-readiness-endpoint.md) - BYAI_WORKER_HEALTH_PORT
+# is run_worker()'s own env-var fallback for --health-port, so this alone
+# is enough to turn it on; no CMD change needed even if you override
+# --worker-class below.
+ENV BYAI_WORKER_HEALTH_PORT=8080
+EXPOSE 8080
+
+# Readiness only - see the hard rule in
+# docs/architecture/worker-readiness-endpoint.md: never turn this into a
+# liveness/restart-on-unhealthy check. urlopen() raises (non-zero exit) on
+# the endpoint's real 503, so this actually fails on "not ready" - unlike
+# a healthcheck that only checks "did the server respond at all".
+HEALTHCHECK --interval=10s --timeout=3s --start-period=10s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/readyz', timeout=3)"
+
+ENTRYPOINT ["/entrypoint.sh"]
+CMD ["--worker-class", "my_agent.MyAgent"]

by_framework-0.2.2.dev11/deploy/docker-compose.yml

@@ -0,0 +1,70 @@
+# Illustrates the README's "水平扩展"/"Horizontal Scaling" section as a real
+# orchestration form instead of backgrounded shell processes: N Worker
+# replicas, same agent type, distinct worker ids (see entrypoint.sh),
+# competing for the same Redis control stream via a consumer group.
+#
+# Usage (downstream project, default my_agent.MyAgent + published PyPI package):
+#   docker compose -f deploy/docker-compose.yml up --build --scale worker=3
+#
+# Usage (this repo's own CI smoke test - see
+# .github/workflows/deploy-smoke-test.yml - builds from local source and
+# runs examples/echo_worker.py instead):
+#   BY_FRAMEWORK_SOURCE=local WORKER_CLASS=examples.echo_worker.EchoWorker \
+#     docker compose -f deploy/docker-compose.yml up --build
+
+services:
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  worker:
+    build:
+      context: ..
+      dockerfile: deploy/Dockerfile
+      args:
+        BY_FRAMEWORK_SOURCE: ${BY_FRAMEWORK_SOURCE:-pypi}
+    depends_on:
+      redis:
+        condition: service_healthy
+    # Mirrors deploy/Dockerfile's HEALTHCHECK - redeclared here (Compose
+    # would otherwise just inherit the image's own) so this file is a
+    # self-contained example of the readiness endpoint's wiring, and so any
+    # future service added here can depend on
+    # `worker: condition: service_healthy` without having to go trace
+    # through the Dockerfile to confirm one exists. Readiness only - never
+    # liveness, see docs/architecture/worker-readiness-endpoint.md.
+    #
+    # No host port published for 8080/readyz on purpose: this file's
+    # documented `--scale worker=N` usage above would collide trying to
+    # publish the same fixed host port for every replica. The healthcheck
+    # itself needs no host port - Compose evaluates it inside the
+    # container's own network. deploy-smoke-test.yml verifies it via
+    # `up --wait`.
+    healthcheck:
+      test:
+        [
+          "CMD",
+          "python",
+          "-c",
+          "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/readyz', timeout=3)",
+        ]
+      interval: 10s
+      timeout: 3s
+      start_period: 10s
+      retries: 3
+    environment:
+      REDIS_HOST: redis
+      REDIS_PORT: "6379"
+      # REDIS_PASSWORD, REDIS_USERNAME, REDIS_MODE, REDIS_CLUSTER_HOST, etc.
+      # all follow RedisConfig.from_env() - see docs/architecture/redis-cluster-mode.md.
+      BYAI_WORKER_CONCURRENCY: "50"
+    command: ["--worker-class", "${WORKER_CLASS:-my_agent.MyAgent}"]
+    # Give WorkerRunner._shutdown() room to drain in-flight tasks before
+    # Compose escalates to SIGKILL on `docker compose down`/stop.
+    stop_grace_period: 30s

by_framework-0.2.2.dev11/deploy/entrypoint.sh

@@ -0,0 +1,13 @@
+#!/bin/sh
+# Uses `exec` so the Python process replaces this shell as PID 1, receiving
+# SIGTERM directly - a shell left as PID 1 does not forward signals to its
+# child by default, which would silently defeat the graceful-shutdown fix in
+# by_framework.worker.app (see docs/architecture/production-deployment.md).
+#
+# `$(hostname)` gives every replica a distinct worker id with no extra
+# wiring: Docker Compose assigns each scaled replica a unique container
+# hostname, and Kubernetes sets a Pod's hostname to its Pod name by default -
+# so the same entrypoint works unchanged under `docker compose up --scale`
+# and a Kubernetes Deployment.
+set -e
+exec python -m by_framework --worker-id "worker-$(hostname)" "$@"

by_framework-0.2.2.dev11/deploy/kubernetes/worker-deployment.yaml

@@ -0,0 +1,62 @@
+# Minimal reference Deployment for a by-framework Worker. Replaces the
+# README's shell-`&` "水平扩展" example with a real, supervised, restart-on-
+# failure orchestration form. Adjust image/replicas/resources for your setup.
+#
+# readinessProbe ONLY below - see docs/architecture/worker-readiness-endpoint.md.
+# Do NOT add a livenessProbe pointed at /readyz (or at anything else,
+# absent a separate deliberate design for one): a Worker's health depends
+# on Redis being reachable, and wiring this to liveness would mean a
+# transient Redis outage kills and restarts every Worker replica
+# simultaneously - a self-inflicted restart storm strictly worse than the
+# outage itself. A failing readinessProbe never kills anything; it only
+# stops this replica from being counted, which is exactly what "not
+# ready" should do.
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: my-agent-worker
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: my-agent-worker
+  template:
+    metadata:
+      labels:
+        app: my-agent-worker
+    spec:
+      # WorkerRunner._shutdown() drains in-flight tasks on SIGTERM before
+      # exiting; give it real room before Kubernetes escalates to SIGKILL.
+      # Must be >= the longest task this Worker is expected to run.
+      terminationGracePeriodSeconds: 30
+      containers:
+        - name: worker
+          image: my-agent-worker:latest
+          args: ["--worker-class", "my_agent.MyAgent"]
+          env:
+            - name: REDIS_HOST
+              value: redis
+            - name: REDIS_PORT
+              value: "6379"
+            # REDIS_PASSWORD/REDIS_USERNAME: prefer a Secret + secretKeyRef.
+            # REDIS_MODE/REDIS_CLUSTER_HOST: see docs/architecture/redis-cluster-mode.md.
+            - name: BYAI_WORKER_CONCURRENCY
+              value: "50"
+            - name: BYAI_WORKER_HEALTH_PORT
+              value: "8080"
+          ports:
+            - name: readiness
+              containerPort: 8080
+          readinessProbe:
+            httpGet:
+              path: /readyz
+              port: readiness
+            periodSeconds: 5
+            timeoutSeconds: 3
+            failureThreshold: 3
+          resources:
+            requests:
+              cpu: "250m"
+              memory: "256Mi"
+            limits:
+              memory: "512Mi"