diff --git a/.dockerignore b/.dockerignore index b54f0f2ce..3855203d3 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,29 +1,42 @@ +# Docker build context filter. Patterns match from the repository root; +# `**/` makes one match at any depth. + +# VCS, caches and build output. The Dockerfile builds the browser UI and the +# npm trees itself, for the image's own platform: a node_modules or dist/ +# copied from a Windows or macOS checkout would carry the wrong native +# binaries, so none may enter the context. .git .gitignore -__pycache__ -*.py[cod] -*.log +.github +**/__pycache__ +**/*.py[cod] +**/*.log +**/node_modules +**/dist +**/build +**/*.egg-info .venv venv -node_modules -chroma_db __pypackages__ .cache .mypy_cache .pytype -build -dist +.pytest_cache +.ruff_cache .DS_Store -.github install.sh install.bat -*.egg-info OmniParser_CraftOS debug_images workspace +# Not needed to run CraftBot: the Rust installer (its target/ directory alone +# can be gigabytes) and the test suite. +launcher +tests + # --------------------------------------------------------------------------- -# Secrets and per-machine runtime state — never belongs in an image. +# Secrets and per-machine runtime state: never belongs in an image. # # `COPY . .` takes whatever is in the build context, i.e. a developer's working # tree, and the release workflow pushes the resulting image to a public @@ -33,6 +46,10 @@ workspace # exactly once, on someone's laptop. (Same failure as the old PyInstaller spec's # blanket app/data entry, which shipped 1.1 GB of one machine's memory index # and databases.) Keep this list in step with .gitignore. +# +# The image still gets every shipped default: app/config/.default.json +# and app/data/agent_file_system_template/ are copied into the /data volume on +# first start (app/state_sync.py). # --------------------------------------------------------------------------- # Secrets and credentials @@ -60,6 +77,10 @@ chroma_db_memory .craftbot **/.craftbot .craftbot-managed +.craftbot-image-id +.agent-ready +craftbot.pid +ui.json logs **/logs **/agent_logs.txt @@ -71,8 +92,11 @@ logs **/onboarding_config.json **/gui/config **/.whatsapp_web_sessions +# ...except the shipped templates the agent's files are created from. +!app/data/agent_file_system_template/USER.md +!app/data/agent_file_system_template/CONVERSATION_HISTORY.md -# Provisioned runtimes and build caches — re-fetched inside the image +# Provisioned runtimes and build caches: re-fetched inside the image runtime wheelhouse downloads-cache diff --git a/.env.example b/.env.example index 6d0ae0201..35aee4a58 100644 --- a/.env.example +++ b/.env.example @@ -1,43 +1,38 @@ -# CraftBot - Environment Configuration -# You need at least ONE API key from a supported LLM provider. - -# --- LLM Provider API Keys (set at least one) --- -OPENAI_API_KEY= -GOOGLE_API_KEY= -ANTHROPIC_API_KEY= -BYTEPLUS_API_KEY= - -# --- Optional: Remote Ollama server URL --- -REMOTE_MODEL_URL= -# --- Optional: OmniParser Gradio server URL --- -# Leave empty to use default http://localhost:7861 -# Or set to a remote/cloud Gradio URL -OMNIPARSER_BASE_URL= - -# Google (/google login) -GOOGLE_CLIENT_ID= -# Optional Figma OAuth app credentials. PAT connection works without these. -# Public apps need Figma approval; do not commit real client secrets. -FIGMA_CLIENT_ID= -FIGMA_CLIENT_SECRET= -GOOGLE_CLIENT_SECRET= - -# LinkedIn (/linkedin login) -LINKEDIN_CLIENT_ID= -LINKEDIN_CLIENT_SECRET= - -# Slack (/slack invite) -SLACK_SHARED_CLIENT_ID= -SLACK_SHARED_CLIENT_SECRET= - -# Telegram (/telegram invite) -TELEGRAM_SHARED_BOT_TOKEN= -TELEGRAM_SHARED_BOT_USERNAME= - -# Telegram (telegram user connect) -TELEGRAM_API_ID= -TELEGRAM_API_HASH= - -# Notion (/notion invite) -NOTION_SHARED_CLIENT_ID= -NOTION_SHARED_CLIENT_SECRET= +# CraftBot: optional environment variables +# +# API keys are NOT read from this file or from any .env file. Enter your LLM +# API key in the browser onboarding on first start (change it later under +# Settings). CraftBot stores it in app/config/settings.json in its data folder. +# +# Everything below is optional and read from the process environment: +# - Docker Compose: copy this file to .env next to docker-compose.yml. +# Compose reads .env and passes these values into the container. +# - Source install: set them in the terminal before running craftbot.py +# (macOS/Linux: export NAME=value, Windows PowerShell: $env:NAME = "value"). +# Leave a value empty to keep the default. + +# --- Proxy ------------------------------------------------------------------ +# Used by every download (Python, pip, npm, Node.js) and by CraftBot itself. +# Keep localhost in NO_PROXY so CraftBot can reach its own servers. +HTTPS_PROXY= +HTTP_PROXY= +NO_PROXY=localhost,127.0.0.1 + +# --- Mirrors ---------------------------------------------------------------- +# Python packages, e.g. https://pypi.tuna.tsinghua.edu.cn/simple +PIP_INDEX_URL= +# npm packages, e.g. https://registry.npmmirror.com +npm_config_registry= +# Embedding model download, e.g. https://hf-mirror.com +HF_ENDPOINT= +# URL rewrites for CraftBot's runtime downloads (Python, Node.js, PocketBase, +# embedding model): semicolon-separated prefix=replacement pairs. Downloads +# are still checked against their pinned SHA-256 checksums. +# e.g. https://nodejs.org/dist/=https://npmmirror.com/mirrors/node/ +CRAFTBOT_MIRRORS= + +# --- Location (source install only; the Docker image sets both itself) ------- +# Keep all CraftBot data and downloaded runtimes in this folder instead. +# CRAFTBOT_HOME=/path/to/craftbot-data +# Interface the UI and backend listen on (default: localhost only). +# CRAFTBOT_BIND_HOST=0.0.0.0 diff --git a/.github/workflows/install-e2e.yml b/.github/workflows/install-e2e.yml new file mode 100644 index 000000000..8d8370f00 --- /dev/null +++ b/.github/workflows/install-e2e.yml @@ -0,0 +1,197 @@ +name: Install E2E + +# A real install, start to finish, on every OS and architecture CraftBot +# ships for: the full locked dependency set, the Node sidecar and npm trees, +# then the agent started headless until it reports ready and the browser UI +# answers. Each job uses whatever Python the runner image ships with (never +# actions/setup-python): the point is to prove that the Python a user +# launches the install with does not matter. One job deliberately launches +# it with an old Python 3.8. +# +# State goes to a throwaway CRAFTBOT_HOME, so runtimes, data and the ready +# marker land in the job's temp directory. + +on: + pull_request: + paths: + - "install.py" + - "craftbot.py" + - "run.py" + - "main.py" + - "installer/**" + - "app/paths.py" + - "app/provision/**" + - "app/python_runtime.py" + - "app/node_runtime.py" + - "app/downloads.py" + - "requirements.txt" + - "requirements/**" + - "agent-app/spec/**" + - ".github/workflows/install-e2e.yml" + workflow_dispatch: + +concurrency: + group: install-e2e-${{ github.ref }} + cancel-in-progress: true + +jobs: + install: + name: Install E2E (${{ matrix.label }}) + runs-on: ${{ matrix.os }} + timeout-minutes: 90 + strategy: + fail-fast: false + matrix: + include: + - os: windows-latest + label: windows-x86_64 + python: python + - os: macos-15 + label: macos-arm64 + python: python3 + - os: macos-15-intel + label: macos-x86_64 + python: python3 + - os: ubuntu-22.04 + label: linux-x86_64 + python: python3 + - os: ubuntu-24.04-arm + label: linux-aarch64 + python: python3 + - os: ubuntu-22.04 + label: linux-x86_64, launched with Python 3.8 + python: python3.8 + old_python: true + + env: + PY: ${{ matrix.python }} + # Output reaches the log as it happens, and box-drawing characters + # survive a pipe on Windows. The launcher sets the same for its runs. + PYTHONUNBUFFERED: "1" + PYTHONIOENCODING: utf-8 + READY_TIMEOUT: "900" + + defaults: + run: + shell: bash + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install an old Python 3.8 to launch with + if: matrix.old_python + run: | + sudo add-apt-repository -y ppa:deadsnakes/ppa + sudo apt-get update + sudo apt-get install -y python3.8 + + - name: Prepare + run: | + set -euo pipefail + # Forward slashes on Windows too: both bash and Python accept them. + tmp="$RUNNER_TEMP" + if command -v cygpath >/dev/null 2>&1; then tmp="$(cygpath -m "$tmp")"; fi + mkdir -p "$tmp/craftbot-home" "$tmp/e2e-logs" + echo "E2E_TMP=$tmp" >> "$GITHUB_ENV" + echo "CRAFTBOT_HOME=$tmp/craftbot-home" >> "$GITHUB_ENV" + echo "launching interpreter: $(command -v "$PY")" + "$PY" -c 'import sys, platform; print(sys.version); print(platform.platform(), platform.machine())' + echo "STARTED_AT=$(date +%s)" >> "$GITHUB_ENV" + + # stdin is closed: an install that stops to ask a question fails here + # instead of hanging, exactly as it would behind the setup window. + - name: Install (install.py --no-launch) + timeout-minutes: 60 + run: | + set -uo pipefail + t0=$(date +%s) + "$PY" install.py --no-launch < /dev/null 2>&1 | tee "$E2E_TMP/e2e-logs/install.log" + code=${PIPESTATUS[0]} + echo "T_INSTALL=$(( $(date +%s) - t0 ))" >> "$GITHUB_ENV" + exit "$code" + + - name: Start headless (craftbot.py start --no-open-browser) + timeout-minutes: 20 + run: | + set -uo pipefail + t0=$(date +%s) + "$PY" craftbot.py start --no-open-browser < /dev/null 2>&1 | tee "$E2E_TMP/e2e-logs/start.log" + code=${PIPESTATUS[0]} + echo "T_START=$(( $(date +%s) - t0 ))" >> "$GITHUB_ENV" + echo "READY_FROM=$t0" >> "$GITHUB_ENV" + exit "$code" + + - name: Wait for the agent to report ready + run: | + set -euo pipefail + marker="$CRAFTBOT_HOME/.agent-ready" + deadline=$(( READY_FROM + READY_TIMEOUT )) + until [ -f "$marker" ]; do + if [ "$(date +%s)" -ge "$deadline" ]; then + echo "::error::$marker did not appear within ${READY_TIMEOUT}s of starting" + exit 1 + fi + sleep 5 + done + echo "T_READY=$(( $(date +%s) - READY_FROM ))" >> "$GITHUB_ENV" + echo "ready marker: $marker" + for f in craftbot.pid ui.json; do + if [ -f "$CRAFTBOT_HOME/$f" ]; then echo "$f: $(cat "$CRAFTBOT_HOME/$f")"; fi + done + + - name: The browser UI answers on port 7925 + run: | + set -uo pipefail + t0=$(date +%s) + code=000 + for _ in $(seq 1 60); do + code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 10 http://localhost:7925/ || true) + [ "$code" = "200" ] && break + sleep 2 + done + echo "T_HTTP=$(( $(date +%s) - t0 ))" >> "$GITHUB_ENV" + echo "http://localhost:7925/ answered HTTP $code" + [ "$code" = "200" ] || { echo "::error::http://localhost:7925/ answered HTTP $code, expected 200"; exit 1; } + + - name: Stop + if: always() + run: | + "$PY" craftbot.py stop < /dev/null || true + + - name: Timings + if: always() + run: | + total=$(( $(date +%s) - ${STARTED_AT:-$(date +%s)} )) + { + echo "### Install E2E timings: ${{ matrix.label }}" + echo + echo "Launched with \`$("$PY" --version 2>&1)\` ($PY)" + echo + echo "| Stage | Seconds |" + echo "|---|---|" + echo "| install.py --no-launch | ${T_INSTALL:-failed} |" + echo "| craftbot.py start | ${T_START:-not reached} |" + echo "| start to .agent-ready | ${T_READY:-not reached} |" + echo "| ready to HTTP 200 on :7925 | ${T_HTTP:-not reached} |" + echo "| total | $total |" + } | tee -a "$GITHUB_STEP_SUMMARY" + + - name: Collect logs + if: failure() + run: | + logs="$E2E_TMP/e2e-logs" + cp craftbot.log "$logs/" 2>/dev/null || true + if [ -d "$CRAFTBOT_HOME/logs" ]; then cp -R "$CRAFTBOT_HOME/logs" "$logs/state-logs"; fi + for f in craftbot.pid ui.json; do + cp "$CRAFTBOT_HOME/$f" "$logs/" 2>/dev/null || true + done + tail -n 80 craftbot.log 2>/dev/null || true + + - name: Upload logs + if: failure() + uses: actions/upload-artifact@v4 + with: + name: install-e2e-logs-${{ strategy.job-index }} + path: ${{ runner.temp }}/e2e-logs + if-no-files-found: ignore diff --git a/.github/workflows/launcher.yml b/.github/workflows/launcher.yml index 37739fade..305c1ec86 100644 --- a/.github/workflows/launcher.yml +++ b/.github/workflows/launcher.yml @@ -2,7 +2,13 @@ name: Launcher # CI for the native launcher in launcher/ (Rust + Slint). The Release # workflow builds and ships it; this one catches breakage on the way there, -# on every platform the launcher is shipped for. +# on every platform and architecture the launcher is shipped for. +# +# Linux binaries are built inside manylinux_2_28 (AlmaLinux 8, glibc 2.28), +# never on the runner's own Ubuntu: a binary links against the glibc it is +# built with, and one built on a current Ubuntu refuses to start on Ubuntu +# 20.04/22.04, Debian 11/12, RHEL 8/9 and most WSL installs. The binary is +# then started on those distributions, so the promise is tested, not assumed. on: push: @@ -15,11 +21,127 @@ on: - "launcher/**" - "app/provision/python_downloads.json" - ".github/workflows/launcher.yml" + workflow_dispatch: env: CARGO_TERM_COLOR: always jobs: + linux: + name: Linux ${{ matrix.arch }} (glibc 2.28) + runs-on: ${{ matrix.runner }} + container: quay.io/pypa/manylinux_2_28_${{ matrix.arch }} + strategy: + fail-fast: false + matrix: + include: + - arch: x86_64 + runner: ubuntu-24.04 + - arch: aarch64 + runner: ubuntu-24.04-arm + + defaults: + run: + shell: bash + working-directory: launcher + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Rust + working-directory: . + run: | + curl --proto '=https' --tlsv1.2 --retry 5 -sSf https://sh.rustup.rs \ + | sh -s -- -y --profile minimal --default-toolchain stable --component rustfmt,clippy + echo "$HOME/.cargo/bin" >> "$GITHUB_PATH" + + # Nothing here is linked: Slint loads X11, Wayland, OpenGL and + # fontconfig with dlopen. The headers let the build scripts that probe + # with pkg-config find what they look for. binutils is for the check. + - name: Build prerequisites + working-directory: . + run: dnf install -y fontconfig-devel libxkbcommon-devel libX11-devel binutils + + - name: Cache cargo + uses: Swatinem/rust-cache@v2 + with: + workspaces: launcher + prefix-key: native-manylinux_2_28-${{ matrix.arch }} + + - name: Format + if: matrix.arch == 'x86_64' + run: cargo fmt --all -- --check + + - name: Clippy + if: matrix.arch == 'x86_64' + run: cargo clippy --release --all-targets -- -D warnings + + - name: Test + run: cargo test --release + + - name: Build + run: cargo build --release + + - name: Check the glibc floor and linked libraries + run: bash packaging/linux/check_binary.sh target/release/CraftBotInstaller 2.28 + + - name: Upload binary + uses: actions/upload-artifact@v4 + with: + name: launcher-linux-${{ matrix.arch }} + path: launcher/target/release/CraftBotInstaller + retention-days: 7 + + # The binary from the job above, started on the oldest and newest releases + # of the distributions users actually run, with no desktop, no developer + # packages and no network. `--headless status` exercises startup, path + # resolution and the state poll without needing a display. + linux-distros: + name: Starts on Linux distributions (${{ matrix.arch }}) + needs: linux + runs-on: ${{ matrix.runner }} + strategy: + fail-fast: false + matrix: + include: + - arch: x86_64 + runner: ubuntu-24.04 + - arch: aarch64 + runner: ubuntu-24.04-arm + steps: + - name: Download binary + uses: actions/download-artifact@v4 + with: + name: launcher-linux-${{ matrix.arch }} + path: bin + + - name: Start on each distribution + shell: bash + run: | + set -uo pipefail + chmod +x bin/CraftBotInstaller + failed="" + for image in ubuntu:20.04 ubuntu:22.04 ubuntu:24.04 \ + debian:11 debian:12 debian:13 \ + almalinux:8 almalinux:9; do + echo "::group::$image" + out=$(docker run --rm --network none \ + --volume "$PWD/bin/CraftBotInstaller:/installer:ro" \ + "$image" /installer --headless status 2>&1) + code=$? + echo "$out" + echo "::endgroup::" + if [ "$code" -ne 0 ] || ! grep -q NotInstalled <<<"$out"; then + echo "::error::the launcher did not start on $image (exit $code)" + failed="$failed $image" + fi + done + if [ -n "$failed" ]; then + echo "failed on:$failed" + exit 1 + fi + test: name: Test (${{ matrix.os_label }}) runs-on: ${{ matrix.os }} @@ -27,14 +149,12 @@ jobs: fail-fast: false matrix: include: - # Build against the oldest supported glibc, not the moving latest - # runner (whose binaries cannot launch on older Ubuntu releases). - - os: ubuntu-22.04 - os_label: linux - os: windows-latest os_label: windows - - os: macos-latest - os_label: macos + - os: macos-15 + os_label: macos-arm64 + - os: macos-15-intel + os_label: macos-x86_64 defaults: run: @@ -46,8 +166,6 @@ jobs: - name: Set up Rust uses: dtolnay/rust-toolchain@stable - with: - components: rustfmt, clippy - name: Cache cargo uses: Swatinem/rust-cache@v2 @@ -55,24 +173,16 @@ jobs: workspaces: launcher prefix-key: native-${{ matrix.os }} - # Same insurance as the Release workflow: Slint has no C build deps, - # but a few crates probe for these headers. - - name: Linux build prerequisites - if: matrix.os_label == 'linux' - run: | - sudo apt-get update - sudo apt-get install -y libxkbcommon-dev libgl1-mesa-dev libfontconfig1-dev - - - name: Format - if: matrix.os_label == 'linux' - run: cargo fmt --all -- --check - - - name: Clippy - if: matrix.os_label == 'linux' - run: cargo clippy --release -- -D warnings - - name: Test run: cargo test --release - name: Build run: cargo build --release + + - name: Start headless + shell: bash + run: | + set -euo pipefail + export CRAFTBOT_HOME="$RUNNER_TEMP/launcher-home" + ./target/release/CraftBotInstaller --headless status | tee status.txt + grep -q NotInstalled status.txt diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 0b7310be2..d52e57277 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -27,12 +27,11 @@ jobs: - image_suffix: agent dockerfile: Dockerfile context: . - - image_suffix: omniparser - dockerfile: docker/omniparser/Dockerfile - context: . # 'desktop' image removed: app/gui was deleted with GUI mode - # (901ad92e) — its Dockerfile no longer exists, and this entry - # broke the first tag build afterwards. + # (901ad92e). Its Dockerfile no longer exists, and this entry + # broke the first tag build afterwards. 'omniparser' removed too: + # it served GUI mode only, disabled since V1.2.2, and + # docker-compose.yml no longer runs it. steps: - name: Checkout uses: actions/checkout@v4 @@ -110,7 +109,7 @@ jobs: run: | echo '{"use_conda": false, "gui_mode_enabled": false}' > config.json - # A missing lock does not break the BUILD — it breaks the user's + # A missing lock does not break the BUILD, it breaks the user's # install, minutes in and hundreds of MB down. Catch it here instead. - name: Require a lock for every platform we ship run: python scripts/generate_lock.py --check --require-all @@ -119,84 +118,282 @@ jobs: run: | python scripts/package_source.py + # The launcher installs a CraftBot-src.zip found beside it only when + # the VERSION inside matches its own, and craftbot.py reports that + # VERSION. It is written from the tag above and is not tracked, so the + # git-based file list leaves it out unless it is added here. + - name: Stamp VERSION into the payload + run: | + python - <<'EOF' + import zipfile + path = "dist/CraftBot-src.zip" + with zipfile.ZipFile(path) as zf: + present = "VERSION" in zf.namelist() + if not present: + with zipfile.ZipFile(path, "a", zipfile.ZIP_DEFLATED) as zf: + zf.write("VERSION", "VERSION") + with zipfile.ZipFile(path) as zf: + print("payload VERSION:", zf.read("VERSION").decode().strip()) + EOF + + # Every launcher checks the payload it downloads against this file + # before extracting it, whichever mirror it came through. + - name: Publish the payload checksum + working-directory: dist + run: | + sha256sum CraftBot-src.zip > CraftBot-src.zip.sha256 + cat CraftBot-src.zip.sha256 + - name: Upload source payload uses: actions/upload-artifact@v4 with: name: release-source - path: dist/CraftBot-src.zip + path: | + dist/CraftBot-src.zip + dist/CraftBot-src.zip.sha256 # ────────────────────────────────────────────── # The launcher: one native binary per platform, built from launcher/. # - # This replaced the old Python/Tk installer window. A native binary is one - # process with no bootloader and no unpacking step, which is what fixed the - # macOS bundle (two Dock icons, an inactive window, dropped taps). It needs - # no Python, Node or web runtime on the user's machine: it downloads the - # source payload above plus a portable Python, then runs craftbot.py - # install (install.py) and start (run.py) in the installed tree. + # A native binary is one process with no bootloader and no unpacking step, + # which is what fixed the macOS bundle (two Dock icons, an inactive window, + # dropped taps). It needs no Python, Node or web runtime on the user's + # machine: it downloads the source payload above plus a portable Python, + # then runs craftbot.py install (install.py) and start (run.py) in the + # installed tree. + # + # Signing runs only when its secrets are configured. Without them the + # build still ships, unsigned, with a warning, and the release notes give + # the extra steps each OS then asks for. # ────────────────────────────────────────────── - launcher: - name: Launcher (${{ matrix.os_label }}) - runs-on: ${{ matrix.os }} + + # Linux: built inside manylinux_2_28 (glibc 2.28) so the binary starts on + # Ubuntu 20.04+, Debian 10+, RHEL 8+ and WSL, then started on several of + # them before it ships. See launcher.yml for the same steps on every PR. + launcher-linux: + name: Launcher (linux-${{ matrix.arch }}) + runs-on: ${{ matrix.runner }} + container: quay.io/pypa/manylinux_2_28_${{ matrix.arch }} strategy: fail-fast: false matrix: include: - # Keep the installer compatible with glibc 2.35 (Ubuntu 22.04+). - - os: ubuntu-22.04 - os_label: linux - - os: windows-latest - os_label: windows - - os: macos-latest - os_label: macos - + - arch: x86_64 + runner: ubuntu-24.04 + - arch: aarch64 + runner: ubuntu-24.04-arm env: # build.rs bakes this into the binary; the launcher downloads the # matching CraftBot-src.zip from this tag's release. CRAFTBOT_VERSION: ${{ github.ref_name }} CARGO_TERM_COLOR: always - + defaults: + run: + shell: bash steps: - name: Checkout uses: actions/checkout@v4 - name: Set up Rust - uses: dtolnay/rust-toolchain@stable - with: - # Both macOS architectures, so the bundle is a universal binary and - # Intel Macs are not left out by macos-latest being arm64. - targets: ${{ matrix.os_label == 'macos' && 'aarch64-apple-darwin,x86_64-apple-darwin' || '' }} + run: | + curl --proto '=https' --tlsv1.2 --retry 5 -sSf https://sh.rustup.rs \ + | sh -s -- -y --profile minimal --default-toolchain stable + echo "$HOME/.cargo/bin" >> "$GITHUB_PATH" + + - name: Build prerequisites + run: dnf install -y fontconfig-devel libxkbcommon-devel libX11-devel binutils + # One cache per build environment: the container and the runner ABI + # differ, so their artifacts must never be shared. - name: Cache cargo uses: Swatinem/rust-cache@v2 with: workspaces: launcher - prefix-key: native-${{ matrix.os }} - - # Slint's Linux backend loads these at runtime through dlopen, and its - # build has no C dependencies — this is insurance for the few crates - # that probe for headers, not a runtime requirement for users. - - name: Linux build prerequisites - if: matrix.os_label == 'linux' - run: | - sudo apt-get update - sudo apt-get install -y libxkbcommon-dev libgl1-mesa-dev libfontconfig1-dev + prefix-key: native-manylinux_2_28-${{ matrix.arch }} - name: Test - if: matrix.os_label == 'linux' working-directory: launcher run: cargo test --release - - name: Build (Linux / Windows) - if: matrix.os_label != 'macos' + - name: Build working-directory: launcher run: cargo build --release - - name: Build (macOS, universal) - if: matrix.os_label == 'macos' + - name: Check the glibc floor and linked libraries + run: bash launcher/packaging/linux/check_binary.sh launcher/target/release/CraftBotInstaller 2.28 + + - name: Package + run: | + mkdir -p dist + cp launcher/target/release/CraftBotInstaller dist/CraftBotInstaller-linux-${{ matrix.arch }} + chmod +x dist/CraftBotInstaller-linux-${{ matrix.arch }} + ls -la dist/ + + - name: Upload launcher artifact + uses: actions/upload-artifact@v4 + with: + name: release-installer-linux-${{ matrix.arch }} + path: dist/CraftBotInstaller-linux-${{ matrix.arch }} + + launcher-linux-distros: + name: Launcher starts on Linux distributions (${{ matrix.arch }}) + needs: launcher-linux + runs-on: ${{ matrix.runner }} + strategy: + fail-fast: false + matrix: + include: + - arch: x86_64 + runner: ubuntu-24.04 + - arch: aarch64 + runner: ubuntu-24.04-arm + steps: + - name: Download launcher + uses: actions/download-artifact@v4 + with: + name: release-installer-linux-${{ matrix.arch }} + path: bin + + - name: Start on each distribution + shell: bash + run: | + set -uo pipefail + bin="bin/CraftBotInstaller-linux-${{ matrix.arch }}" + chmod +x "$bin" + failed="" + for image in ubuntu:20.04 ubuntu:22.04 ubuntu:24.04 \ + debian:11 debian:12 debian:13 \ + almalinux:8 almalinux:9; do + echo "::group::$image" + out=$(docker run --rm --network none \ + --volume "$PWD/$bin:/installer:ro" \ + "$image" /installer --headless status 2>&1) + code=$? + echo "$out" + echo "::endgroup::" + if [ "$code" -ne 0 ] || ! grep -q NotInstalled <<<"$out"; then + echo "::error::the launcher did not start on $image (exit $code)" + failed="$failed $image" + fi + done + if [ -n "$failed" ]; then + echo "failed on:$failed" + exit 1 + fi + + launcher-windows: + name: Launcher (windows) + runs-on: windows-latest + outputs: + signed: ${{ steps.sign-state.outputs.signed }} + env: + CRAFTBOT_VERSION: ${{ github.ref_name }} + CARGO_TERM_COLOR: always + HAS_SIGNING: ${{ secrets.AZURE_TENANT_ID != '' && secrets.AZURE_CLIENT_ID != '' && secrets.AZURE_CLIENT_SECRET != '' && secrets.TRUSTED_SIGNING_ENDPOINT != '' && secrets.TRUSTED_SIGNING_ACCOUNT != '' && secrets.TRUSTED_SIGNING_PROFILE != '' }} + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Rust + uses: dtolnay/rust-toolchain@stable + + - name: Cache cargo + uses: Swatinem/rust-cache@v2 + with: + workspaces: launcher + prefix-key: native-windows-latest + + - name: Build + working-directory: launcher + run: cargo build --release + + - name: Package + shell: bash + run: | + set -euo pipefail + mkdir -p dist + cp launcher/target/release/CraftBotInstaller.exe dist/CraftBotInstaller-windows.exe + ls -la dist/ + + # Authenticode through Azure Artifact Signing (formerly Trusted + # Signing). Unsigned, SmartScreen asks the user to confirm, and Windows + # 11 with Smart App Control on blocks the installer outright. + - name: Sign (Azure Artifact Signing) + if: env.HAS_SIGNING == 'true' + uses: azure/artifact-signing-action@v2 + with: + azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }} + azure-client-id: ${{ secrets.AZURE_CLIENT_ID }} + azure-client-secret: ${{ secrets.AZURE_CLIENT_SECRET }} + endpoint: ${{ secrets.TRUSTED_SIGNING_ENDPOINT }} + signing-account-name: ${{ secrets.TRUSTED_SIGNING_ACCOUNT }} + certificate-profile-name: ${{ secrets.TRUSTED_SIGNING_PROFILE }} + files: ${{ github.workspace }}\dist\CraftBotInstaller-windows.exe + file-digest: SHA256 + timestamp-rfc3161: http://timestamp.acs.microsoft.com + timestamp-digest: SHA256 + + - name: Verify the signature + if: env.HAS_SIGNING == 'true' + shell: pwsh + run: | + $sig = Get-AuthenticodeSignature dist\CraftBotInstaller-windows.exe + $sig | Format-List Status, StatusMessage, SignerCertificate, TimeStamperCertificate + if ($sig.Status -ne 'Valid') { throw "Authenticode signature is $($sig.Status)" } + + - name: Record signing state + id: sign-state + shell: bash + run: | + if [ "$HAS_SIGNING" = "true" ]; then + echo "signed=true" >> "$GITHUB_OUTPUT" + else + echo "::warning::Windows installer is NOT signed: set AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, TRUSTED_SIGNING_ENDPOINT, TRUSTED_SIGNING_ACCOUNT and TRUSTED_SIGNING_PROFILE to sign it." + echo "signed=false" >> "$GITHUB_OUTPUT" + fi + + - name: Upload launcher artifact + uses: actions/upload-artifact@v4 + with: + name: release-installer-windows + path: dist/CraftBotInstaller-windows.exe + + launcher-macos: + name: Launcher (macos, universal) + runs-on: macos-15 + outputs: + notarized: ${{ steps.notarize-state.outputs.notarized }} + env: + CRAFTBOT_VERSION: ${{ github.ref_name }} + CARGO_TERM_COLOR: always + HAS_CERT: ${{ secrets.MACOS_CERT_P12_BASE64 != '' && secrets.MACOS_CERT_PASSWORD != '' }} + HAS_NOTARY: ${{ secrets.APPLE_ID != '' && secrets.APPLE_TEAM_ID != '' && secrets.APPLE_APP_PASSWORD != '' }} + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Rust + uses: dtolnay/rust-toolchain@stable + with: + # Both architectures, so the bundle is a universal binary and Intel + # Macs are not left out by the arm64 build machine. + targets: aarch64-apple-darwin,x86_64-apple-darwin + + - name: Cache cargo + uses: Swatinem/rust-cache@v2 + with: + workspaces: launcher + prefix-key: native-macos-15 + + - name: Build (universal) working-directory: launcher run: | set -euo pipefail + # The oldest macOS the binary is built for is the one the launcher + # checks for, from the same constant. + MACOSX_DEPLOYMENT_TARGET="$(sed -n 's/^pub const MIN_MACOS: &str = "\(.*\)";/\1/p' src/preflight.rs)" + export MACOSX_DEPLOYMENT_TARGET + echo "MACOSX_DEPLOYMENT_TARGET=$MACOSX_DEPLOYMENT_TARGET" cargo build --release --target aarch64-apple-darwin cargo build --release --target x86_64-apple-darwin mkdir -p target/universal @@ -208,7 +405,6 @@ jobs: # sips and iconutil are both part of macOS; nothing to install. - name: Build the macOS app icon - if: matrix.os_label == 'macos' run: | set -euo pipefail iconset="$RUNNER_TEMP/craftbot.iconset" @@ -221,44 +417,113 @@ jobs: done iconutil -c icns "$iconset" -o craftbot_logo_1.icns - - name: Package - shell: bash + - name: Import the Developer ID certificate + if: env.HAS_CERT == 'true' + env: + MACOS_CERT_P12_BASE64: ${{ secrets.MACOS_CERT_P12_BASE64 }} + MACOS_CERT_PASSWORD: ${{ secrets.MACOS_CERT_PASSWORD }} run: | set -euo pipefail + keychain="$RUNNER_TEMP/signing.keychain-db" + keychain_password="$(openssl rand -base64 24)" + security create-keychain -p "$keychain_password" "$keychain" + security set-keychain-settings -lut 21600 "$keychain" + security unlock-keychain -p "$keychain_password" "$keychain" + printf '%s' "$MACOS_CERT_P12_BASE64" | base64 --decode > "$RUNNER_TEMP/cert.p12" + security import "$RUNNER_TEMP/cert.p12" -k "$keychain" \ + -P "$MACOS_CERT_PASSWORD" -T /usr/bin/codesign + rm -f "$RUNNER_TEMP/cert.p12" + security set-key-partition-list -S apple-tool:,apple:,codesign: \ + -s -k "$keychain_password" "$keychain" >/dev/null + security list-keychains -d user -s "$keychain" \ + $(security list-keychains -d user | tr -d '"') + identity="$(security find-identity -v -p codesigning "$keychain" \ + | awk -F'"' '/Developer ID Application/ {print $2; exit}')" + if [ -z "$identity" ]; then + echo "::error::the certificate holds no 'Developer ID Application' identity" + exit 1 + fi + echo "MACOS_SIGN_IDENTITY=$identity" >> "$GITHUB_ENV" + + - name: Bundle + run: | + set -euo pipefail + if [ "$HAS_CERT" != "true" ]; then + echo "::warning::macOS app is NOT Developer ID signed: set MACOS_CERT_P12_BASE64 and MACOS_CERT_PASSWORD to sign it. It is ad-hoc signed, and users must allow it in System Settings > Privacy & Security." + fi mkdir -p dist - case "${{ matrix.os_label }}" in - linux) - cp launcher/target/release/CraftBotInstaller dist/CraftBotInstaller-linux - chmod +x dist/CraftBotInstaller-linux - ;; - windows) - cp launcher/target/release/CraftBotInstaller.exe dist/CraftBotInstaller-windows.exe - ;; - macos) - REF="${{ github.ref_name }}" - launcher/packaging/macos/bundle.sh \ - launcher/target/universal/CraftBotInstaller dist "${REF#v}" - # ditto, not zip: it preserves the bundle's extended attributes - # and execute bits. A plain zip loses them and the app will not - # launch after the user unzips it. - ditto -c -k --keepParent dist/CraftBotInstaller.app dist/CraftBotInstaller-macos.zip - rm -rf dist/CraftBotInstaller.app - ;; - esac + REF="${{ github.ref_name }}" + launcher/packaging/macos/bundle.sh \ + launcher/target/universal/CraftBotInstaller dist "${REF#v}" + + # Notarized and stapled, the app opens on first launch with only the + # usual "downloaded from the internet" confirmation, offline included. + - name: Notarize and staple + id: notarize + if: env.HAS_CERT == 'true' && env.HAS_NOTARY == 'true' + env: + APPLE_ID: ${{ secrets.APPLE_ID }} + APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }} + APPLE_APP_PASSWORD: ${{ secrets.APPLE_APP_PASSWORD }} + run: | + set -euo pipefail + submission="$RUNNER_TEMP/CraftBotInstaller-notarize.zip" + ditto -c -k --keepParent dist/CraftBotInstaller.app "$submission" + xcrun notarytool submit "$submission" \ + --apple-id "$APPLE_ID" --team-id "$APPLE_TEAM_ID" --password "$APPLE_APP_PASSWORD" \ + --wait --timeout 30m --output-format json > "$RUNNER_TEMP/notary.json" + cat "$RUNNER_TEMP/notary.json" + status="$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1])).get("status", ""))' "$RUNNER_TEMP/notary.json")" + if [ "$status" != "Accepted" ]; then + id="$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1])).get("id", ""))' "$RUNNER_TEMP/notary.json")" + [ -n "$id" ] && xcrun notarytool log "$id" \ + --apple-id "$APPLE_ID" --team-id "$APPLE_TEAM_ID" --password "$APPLE_APP_PASSWORD" || true + echo "::error::notarization ended with status '$status'" + exit 1 + fi + xcrun stapler staple dist/CraftBotInstaller.app + xcrun stapler validate dist/CraftBotInstaller.app + spctl --assess --type execute --verbose=2 dist/CraftBotInstaller.app + echo "done=true" >> "$GITHUB_OUTPUT" + + - name: Record notarization state + id: notarize-state + run: | + if [ "${{ steps.notarize.outputs.done }}" = "true" ]; then + echo "notarized=true" >> "$GITHUB_OUTPUT" + else + if [ "$HAS_CERT" = "true" ]; then + echo "::warning::macOS app is signed but NOT notarized: set APPLE_ID, APPLE_TEAM_ID and APPLE_APP_PASSWORD to notarize it." + fi + echo "notarized=false" >> "$GITHUB_OUTPUT" + fi + + - name: Package + run: | + set -euo pipefail + # ditto, not zip: it preserves the bundle's extended attributes, + # the stapled ticket and execute bits. A plain zip loses them and + # the app will not launch after the user unzips it. + ditto -c -k --keepParent dist/CraftBotInstaller.app dist/CraftBotInstaller-macos.zip + rm -rf dist/CraftBotInstaller.app ls -la dist/ + - name: Remove the signing keychain + if: always() && env.HAS_CERT == 'true' + run: security delete-keychain "$RUNNER_TEMP/signing.keychain-db" || true + - name: Upload launcher artifact uses: actions/upload-artifact@v4 with: - name: release-installer-${{ matrix.os_label }} - path: dist/CraftBotInstaller-${{ matrix.os_label }}* + name: release-installer-macos + path: dist/CraftBotInstaller-macos.zip # ────────────────────────────────────────────── # Create GitHub Release with all artifacts # ────────────────────────────────────────────── release: name: Publish GitHub Release - needs: [docker, source, launcher] + needs: [docker, source, launcher-linux, launcher-linux-distros, launcher-windows, launcher-macos] runs-on: ubuntu-latest steps: - name: Download all artifacts @@ -267,35 +532,92 @@ jobs: path: release merge-multiple: true + # The install steps depend on what was signed in this run, so the + # notes are written here rather than fixed in this file. + - name: Write release notes + env: + WINDOWS_SIGNED: ${{ needs.launcher-windows.outputs.signed }} + MACOS_NOTARIZED: ${{ needs.launcher-macos.outputs.notarized }} + run: | + set -euo pipefail + notes=release-notes.md + { + echo '### Install CraftBot' + echo + echo 'Download the installer for your computer from the assets below and open it.' + echo 'It downloads and sets up everything CraftBot needs, including Python, Node.js' + echo 'and all dependencies. You do not need Git, Python or Node.js beforehand. The' + echo 'first install takes a few minutes.' + echo + echo '| Computer | Download |' + echo '|---|---|' + echo '| Windows 10 or 11 | `CraftBotInstaller-windows.exe` |' + echo '| macOS 12 or later, Apple silicon or Intel | `CraftBotInstaller-macos.zip` |' + echo '| Linux, x86_64 (Intel or AMD) | `CraftBotInstaller-linux-x86_64` |' + echo '| Linux, ARM64 | `CraftBotInstaller-linux-aarch64` |' + echo + echo '#### Windows' + echo + echo '1. Open `CraftBotInstaller-windows.exe`.' + echo '2. If Microsoft Defender SmartScreen shows "Windows protected your PC", select' + echo ' **More info**, then **Run anyway**.' + if [ "$WINDOWS_SIGNED" != "true" ]; then + echo + echo 'This build is not code-signed. On Windows 11 with Smart App Control turned on,' + echo 'Windows blocks unsigned installers; install from a terminal with the steps in' + echo 'the README instead.' + fi + echo + echo '#### macOS' + echo + if [ "$MACOS_NOTARIZED" = "true" ]; then + echo '1. Open `CraftBotInstaller-macos.zip` to unzip it.' + echo '2. Open **CraftBot Setup** and select **Open** when macOS asks to confirm an' + echo ' app downloaded from the internet.' + else + echo '1. Open `CraftBotInstaller-macos.zip` to unzip it, then open **CraftBot Setup**.' + echo ' macOS says it cannot verify the app. Select **Done**.' + echo '2. Open **System Settings > Privacy & Security** (on macOS 12, **System' + echo ' Preferences > Security & Privacy > General**), scroll down to **Security**,' + echo ' and select **Open Anyway** next to the message about CraftBot Setup.' + echo '3. Confirm with your password when asked. CraftBot Setup then opens.' + echo + echo 'You only need to do this once. This build is not notarized by Apple.' + fi + echo + echo '#### Linux' + echo + echo 'In a terminal, in the folder you downloaded it to:' + echo + echo '```bash' + echo 'chmod +x CraftBotInstaller-linux-x86_64 && ./CraftBotInstaller-linux-x86_64' + echo '```' + echo + echo 'On an ARM64 computer, use `CraftBotInstaller-linux-aarch64` in both places. The' + echo 'installer runs on any distribution with glibc 2.28 or later (Ubuntu 20.04,' + echo 'Debian 10, RHEL 8 and newer) and opens a window, so it needs a desktop session.' + echo + echo '### Behind a proxy or firewall' + echo + echo 'The installer uses your system proxy setting and the `HTTPS_PROXY` and' + echo '`NO_PROXY` variables. To download through a mirror, set `CRAFTBOT_MIRRORS` to' + echo 'semicolon-separated `prefix=replacement` pairs, for example' + echo '`https://github.com/=https://mirror.example.com/github/`. The CraftBot' + echo 'download is checked against its published SHA-256 checksum, whichever server it' + echo 'came from.' + echo + echo '### If the installer cannot download CraftBot' + echo + echo 'Download `CraftBot-src.zip` from the assets below and put it in the same folder' + echo 'as the installer before you open the installer. It uses that file instead of' + echo 'downloading it; Python, Node.js and the dependencies are still downloaded during' + echo 'setup. `CraftBot-src.zip.sha256` holds the checksum of `CraftBot-src.zip`.' + } > "$notes" + cat "$notes" + - name: Create GitHub Release uses: softprops/action-gh-release@v2 with: files: release/** generate_release_notes: true - body: | - ### Installer (Recommended) - Download the file for your platform from the assets below and run - it. The setup window lets you choose an install location, then - downloads `CraftBot-src.zip` from this release and sets up - everything it needs — Python, Node.js and all dependencies. You do - not need Git, Python or Node installed beforehand. - - | Platform | Download | How to run | - |---|---|---| - | Windows | `CraftBotInstaller-windows.exe` | Double-click it. | - | macOS | `CraftBotInstaller-macos.zip` | Unzip, then **right-click the app and choose Open**. | - | Linux | `CraftBotInstaller-linux` | `chmod +x CraftBotInstaller-linux && ./CraftBotInstaller-linux` | - - On macOS the right-click is required the first time: the app is not - yet signed with an Apple Developer ID, so double-clicking it shows - "cannot be opened because the developer cannot be verified". - Right-click → Open gives you an Open button that double-click does - not. You only need to do this once. - - First install takes a few minutes while the runtime is prepared. - - ### Manual install - If you'd rather skip the window, download both - `CraftBotInstaller-` and `CraftBot-src.zip`, place them - in the same folder, and run the installer — it'll use the local - payload instead of fetching from GitHub. + body_path: release-notes.md diff --git a/.gitignore b/.gitignore index 90bfd604a..847c10184 100644 --- a/.gitignore +++ b/.gitignore @@ -18,6 +18,9 @@ craftbot/generated_task_document/ # Installation receipt for the included Agent App (state, never source). .default-agent-app.json .default-agent-app.tmp +# Written by run.py at runtime: the live UI address and the service pid. +/ui.json +/craftbot.pid # Generated on macOS by the release workflow (sips + iconutil) for the # .app bundle's icon. Derived from craftbot_logo_1.png, not source. craftbot_logo_1.icns @@ -133,3 +136,17 @@ agent_file_system/*.local-backup # Per-install automatic startup preference (managed installs keep it in user data). /startup.json +# Runtime state CraftBot writes while it runs. Each is created on first start +# from a shipped default (app/config/.default.json, or the template in +# app/data/agent_file_system_template/), so `git pull` never collides with a +# user's API keys, settings or memory. See app/state_sync.py. +/app/config/settings.json +/app/config/mcp_config.json +/app/config/scheduler_config.json +/app/config/skills_config.json +/agent_file_system/MEMORY.md +/agent_file_system/ENTITIES.md +/agent_file_system/PROACTIVE.md +/craftbot.log +/service-env.json +/.update-keep/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c113d830c..198e8b877 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -52,6 +52,26 @@ git clone https://github.com//CraftBot.git cd CraftBot ``` +### Install and Run + +Any Python 3.8 or newer works. CraftBot downloads its own private Python 3.10 and Node.js 24, so you do not need to install Node.js (see [Getting Started](README.md#-getting-started) for details and troubleshooting). + +```shell +python craftbot.py install # Windows; use python3 on macOS and Linux +python craftbot.py logs # Show the last log lines if something fails +``` + +To work on CraftBot, stop the background service and run it in the foreground instead: + +```shell +python craftbot.py stop +python run.py # Browser UI (production build, rebuilt when sources change) +python run.py --dev-ui # Browser UI through the Vite dev server, with hot reload +python run.py --cli # Terminal UI +``` + +In a source checkout, CraftBot keeps its state (settings, agent files, memory, logs) inside the repository folder. Set `CRAFTBOT_HOME` to a different folder to run against separate, clean state. + --- # 📋 Workflow SOPs diff --git a/Dockerfile b/Dockerfile index 4e96292b9..ccb1f1737 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,59 +1,188 @@ -FROM python:3.10-slim +# syntax=docker/dockerfile:1 +# +# CraftBot in browser mode. +# +# docker compose up -d then open http://localhost:7925 +# +# Everything the app needs is installed at build time: Python 3.10 with the +# locked dependency set, Node.js 24, the compiled browser UI, the npm trees, +# PocketBase, Playwright's Chromium and the memory embedding model. A first +# start on a new named volume downloads nothing. +# +# All state lives in /data (a volume): settings and API keys, agent files, +# memory, logs and the user's home directory. The code in /app is replaceable. +# Keep NODE_VERSION on Node 24 or newer (MIN_NODE_MAJOR in app/node_runtime.py). +ARG PYTHON_VERSION=3.10 +ARG NODE_VERSION=24.19.0 + +# --------------------------------------------------------------------------- +# Browser UI: compiled once and served as static files at runtime. +# The output is plain HTML/JS, so this stage runs on the build host's own +# architecture even when the image targets another one. +# --------------------------------------------------------------------------- +FROM --platform=$BUILDPLATFORM node:${NODE_VERSION}-bookworm-slim AS frontend +ARG npm_config_registry +WORKDIR /src/app/ui_layer/browser/frontend +COPY app/ui_layer/browser/frontend/package.json app/ui_layer/browser/frontend/package-lock.json ./ +RUN npm install --no-audit --no-fund +COPY app/ui_layer/components/Mascot /src/app/ui_layer/components/Mascot +COPY app/ui_layer/browser/frontend ./ +# The default backend port, used when the serving process does not inject +# the live one into index.html (src/utils/connection.ts). +RUN VITE_BACKEND_PORT=7926 npx vite build + +# --------------------------------------------------------------------------- +# npm trees the backend runs: the Agent App tooling and the WhatsApp bridge. +# Built for the TARGET platform on the same Debian release as the runtime +# image, so any native module matches the system it will run on. +# --------------------------------------------------------------------------- +FROM node:${NODE_VERSION}-bookworm-slim AS node-runtime +FROM node-runtime AS node-deps +ARG npm_config_registry +# npm trees built for the target platform: the Agent App CLI and the WhatsApp bridge. +WORKDIR /src/agent-app +COPY agent-app ./ +RUN npm ci --ignore-scripts --include=dev --no-audit --no-fund +WORKDIR /src/craftos_integrations/providers/whatsapp_web +COPY craftos_integrations/providers/whatsapp_web/package.json craftos_integrations/providers/whatsapp_web/package-lock.json ./ +RUN npm install --no-audit --no-fund +# Collect every node_modules tree at its relative path, ready to lay over /app. +WORKDIR /src +RUN mkdir /out && find . -name node_modules -prune -exec cp -a --parents {} /out/ \; + +# --------------------------------------------------------------------------- +# Runtime image. +# --------------------------------------------------------------------------- +FROM python:${PYTHON_VERSION}-slim-bookworm + +# CRAFTBOT_HOME all CraftBot state goes to the /data volume. +# CRAFTBOT_BIND_HOST listen on every interface inside the container; +# docker-compose.yml publishes the ports on the host's +# loopback only. +# CRAFTBOT_PYTHON/NODE pin the image's Python 3.10 (in a virtualenv the +# runtime user owns, so the agent can still pip install +# an action's missing package) and Node, so CraftBot +# never downloads private copies. +# PLAYWRIGHT_BROWSERS_PATH, AGENT_APP_PB_CACHE +# Chromium and PocketBase, baked in at build time below. +# HOME caches and per-user files land in the volume and +# survive image rebuilds. ENV PYTHONDONTWRITEBYTECODE=1 \ PYTHONUNBUFFERED=1 \ - PIP_TIMEOUT=600 \ - PIP_PROGRESS_BAR=off + PIP_DISABLE_PIP_VERSION_CHECK=1 \ + PATH=/opt/venv/bin:$PATH \ + CRAFTBOT_HOME=/data \ + CRAFTBOT_BIND_HOST=0.0.0.0 \ + CRAFTBOT_PYTHON=/opt/venv/bin/python \ + CRAFTBOT_NODE=/usr/local/bin/node \ + PLAYWRIGHT_BROWSERS_PATH=/opt/ms-playwright \ + AGENT_APP_PB_CACHE=/opt/craftbot/pocketbase \ + HOME=/data/home +# System packages: tini (PID 1, forwards signals), git and curl (the agent's +# shell work and Agent App imports), tesseract (OCR), libgomp1 and libglib +# (native wheels). The X11/GUI packages are gone with GUI mode (V1.2.2). +# +# The Docker CLI and a bind mount of /var/run/docker.sock used to be here. +# Nothing in the codebase calls Docker, and the socket is the host's control +# plane: mounting it into a container that runs model-chosen commands hands +# that container root on the host. If a future feature needs Docker, give it +# a scoped proxy rather than the raw socket. +# +# Not version-pinned: the Debian release is fixed by the base image, and a +# pin breaks the build as soon as the archive publishes a security update. +ARG DEBIAN_FRONTEND=noninteractive +# hadolint ignore=DL3008 RUN apt-get update \ && apt-get install -y --no-install-recommends \ - build-essential \ - pkg-config \ - tesseract-ocr \ - libtesseract-dev \ - libgl1 \ - libglib2.0-0 \ - libsm6 \ - libxext6 \ - libxrender1 \ - scrot \ - xvfb \ - xauth \ - libxi6 \ - libxtst6 \ - x11-apps \ - fonts-dejavu \ + ca-certificates \ curl \ + fonts-dejavu-core \ + git \ + libglib2.0-0 \ + libgomp1 \ + tesseract-ocr \ + tini \ && rm -rf /var/lib/apt/lists/* -# The Docker CLI used to be installed here, paired with a bind mount of -# /var/run/docker.sock in docker-compose.yml. Nothing in the codebase ever -# called it: a repo-wide search for `docker exec`, `docker run`, `docker.sock`, -# `DOCKER_HOST` and the docker SDK finds no usage. The socket is the host's -# control plane, so mounting it into a container that executes model-chosen -# shell commands hands that container root on the host. Both are removed; if a -# future feature needs to drive Docker, give it a scoped proxy rather than the -# raw socket. +# Node.js 24 and its npm, from the official image of the pinned version. +COPY --from=node-runtime /usr/local/bin/node /usr/local/bin/node +COPY --from=node-runtime /usr/local/lib/node_modules /usr/local/lib/node_modules +RUN ln -s ../lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm \ + && ln -s ../lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx \ + && node --version && npm --version -WORKDIR /app +# Unprivileged runtime user. The agent executes commands the model chooses, +# so a bad command or an escape should not land as root. The UID is fixed so +# a host directory used instead of the named volume can be chowned to match: +# sudo chown -R 10001:10001 /path/to/craftbot-data +# /data is created here with this owner: a named volume is seeded from it on +# first use. +RUN groupadd --gid 10001 craftbot \ + && useradd --uid 10001 --gid 10001 --home-dir /data/home --no-create-home \ + --shell /usr/sbin/nologin craftbot \ + && mkdir -p /app /data/home /opt/venv /opt/craftbot/pocketbase \ + && chown craftbot:craftbot /app /data /data/home /opt/venv /opt/craftbot/pocketbase + +# Python dependencies from the committed lock for this architecture: the same +# hash-pinned closure every other install path uses (app/provision/deps.py). +# pip itself is pinned first, because the pip version decides how a lock is +# read (requirements/pip-bootstrap.txt). +USER 10001:10001 +ARG PIP_INDEX_URL +COPY --chown=10001:10001 requirements/ /tmp/requirements/ +RUN set -eu; \ + case "$(uname -m)" in \ + x86_64) plat=linux_x86_64 ;; \ + aarch64|arm64) plat=linux_aarch64 ;; \ + *) echo "CraftBot has no dependency lock for $(uname -m)." >&2; exit 1 ;; \ + esac; \ + /usr/local/bin/python3 -m venv /opt/venv; \ + py="$(python -c 'import sys; print("py%d%d" % sys.version_info[:2])')"; \ + lock="/tmp/requirements/lock-${plat}-${py}.txt"; \ + if [ ! -f "$lock" ]; then \ + echo "Missing requirements/lock-${plat}-${py}.txt. Generate it with scripts/generate_lock.py." >&2; \ + exit 1; \ + fi; \ + python -m pip install --no-cache-dir --require-hashes --no-deps -r /tmp/requirements/pip-bootstrap.txt; \ + python -m pip install --no-cache-dir --require-hashes --no-deps -r "$lock"; \ + rm -rf /tmp/requirements -COPY requirements.txt ./requirements.txt +# Chromium for the Mini Browser and browser automation, with the system +# libraries it needs (that part requires root, so it cannot happen at runtime). +USER 0:0 +RUN HOME=/root python -m playwright install --with-deps chromium \ + && chmod -R a+rX "$PLAYWRIGHT_BROWSERS_PATH" \ + && rm -rf /var/lib/apt/lists/* + +WORKDIR /app +COPY --from=node-deps --chown=craftbot:craftbot /out/ /app/ +COPY --chown=craftbot:craftbot . /app/ +COPY --from=frontend --chown=craftbot:craftbot /src/app/ui_layer/browser/frontend/dist /app/app/ui_layer/browser/frontend/dist -RUN pip install --no-cache-dir --upgrade pip \ - && pip install --no-cache-dir --timeout 600 -r requirements.txt +USER 10001:10001 -COPY . . +# Mark /app as a managed install (code here, state in CRAFTBOT_HOME), so the +# prebuilt UI is served as-is rather than rebuilt (app/paths.py, run.py). +# Then run the real install pipeline once. Everything above already satisfies +# most of it; what is left is fetched into the image: PocketBase (into +# AGENT_APP_PB_CACHE) and the memory embedding model (into /data/runtime, +# which seeds a new named volume). A failure fails the build, not the first +# start. The image id lets the entrypoint skip this check on later starts. +RUN python -c "from app.paths import mark_managed_install; mark_managed_install('/app')" \ + && printf '{\n "use_conda": false,\n "gui_mode_enabled": false\n}\n' > /app/config.json \ + && mkdir -p /tmp/craftbot-build-home \ + && HOME=/tmp/craftbot-build-home python install.py --no-launch < /dev/null \ + && rm -rf /tmp/craftbot-build-home \ + && cat /proc/sys/kernel/random/uuid > /app/.craftbot-image-id \ + && cp /app/.craftbot-image-id /data/.craftbot-image-id -# Run as an unprivileged user. The agent executes commands the model chooses, -# so a container escape or a bad command should not land as root. The UID is -# fixed (not auto-assigned) so a host bind mount can be chowned to match: -# sudo chown -R 10001:10001 ./workspace -# The directories the compose file bind-mounts are pre-created here so they -# exist with the right owner when no host directory is supplied. -RUN useradd --create-home --uid 10001 --shell /usr/sbin/nologin craftbot \ - && mkdir -p /app/workspace /app/logs \ - && chown -R craftbot:craftbot /app +EXPOSE 7925 7926 +VOLUME ["/data"] -USER craftbot +HEALTHCHECK --interval=30s --timeout=10s --start-period=180s --retries=3 \ + CMD ["python", "-c", "import urllib.request as u; u.build_opener(u.ProxyHandler({})).open('http://localhost:7925', timeout=8)"] -CMD ["python", "-m", "app.main"] +ENTRYPOINT ["tini", "-g", "--", "python", "/app/docker/entrypoint.py"] +CMD [] diff --git a/README.cn.md b/README.cn.md index 8bf067dde..cef8e05fb 100644 --- a/README.cn.md +++ b/README.cn.md @@ -56,30 +56,78 @@ ## 🧰 快速开始 -环境要求:Python 3.10+ · 浏览器模式需要 Node.js 18+ +**环境要求** + +- Windows 10 或 11(x64)、macOS 12 或更高版本(Apple Silicon 或 Intel),或 Linux(x86_64 或 ARM64) +- 至少 5 GB 可用磁盘空间 +- 一个 LLM 服务商的 API 密钥(例如 OpenAI、Anthropic、Google Gemini 或 OpenRouter),或通过 Ollama 运行的本地模型 +- 仅源码安装需要:Python 3.8 或更高版本。无需安装 Node.js。 + +### 方式一:安装程序(推荐,无需 Python 或 Git) + +从[最新发布页](https://github.com/CraftOS-dev/CraftBot/releases/latest)下载适合你系统的文件: + +| 系统 | 文件 | +|---|---| +| Windows(x64) | `CraftBotInstaller-windows.exe` | +| macOS(Apple Silicon 和 Intel) | `CraftBotInstaller-macos.zip` | +| Linux(x86_64) | `CraftBotInstaller-linux-x86_64` | +| Linux(ARM64) | `CraftBotInstaller-linux-aarch64` | + +打开后点击 **Install CraftBot**。安装程序会下载 CraftBot 所需的全部内容,启动 CraftBot,并在浏览器中打开它。 + +安装程序目前尚未进行代码签名,因此首次启动需要多一步操作: + +- **Windows:** 如果 SmartScreen 提示“Windows 已保护你的电脑”,点击 **更多信息**(More info),再点击 **仍要运行**(Run anyway)。 +- **macOS:** 解压后打开 `CraftBotInstaller.app`。在 macOS 15 及更高版本上,首次打开会被拦截:打开 **系统设置 > 隐私与安全性**,在关于 CraftBotInstaller 的提示旁点击 **仍要打开**(Open Anyway)并确认。在 macOS 12 至 14 上,右键点击该应用并选择 **打开**(Open)。 +- **Linux:** 为文件添加可执行权限,然后在桌面会话中运行(没有桌面环境的服务器请使用源码安装): + ```bash + chmod +x CraftBotInstaller-linux-x86_64 + ./CraftBotInstaller-linux-x86_64 + ``` + +### 方式二:从源码安装 + +电脑上已有的任意 Python 3.8 或更高版本即可。CraftBot 会下载自己专用的 Python 3.10 和 Node.js 24,不会改动系统中已安装的 Python 或 Node.js。 ```bash -# 1. 克隆仓库 -git clone https://github.com/CraftOS-dev/CraftBot.git +git clone --depth 1 https://github.com/CraftOS-dev/CraftBot.git cd CraftBot +``` -# 2. 安装、注册自启动并运行 CraftBot -python craftbot.py install +然后运行对应系统的安装命令: + +```bash +# Windows +python craftbot.py install # 或:py craftbot.py install + +# macOS 和 Linux +python3 craftbot.py install ``` -就这么简单。终端会自动关闭,CraftBot 在后台运行,浏览器自动打开。同时还会创建一个**桌面快捷方式**,方便你随时重新打开浏览器。 +- **没有 Git?** 在[仓库页面](https://github.com/CraftOS-dev/CraftBot)点击 **Code > Download ZIP**,解压后在解压出的文件夹中打开终端,运行同样的命令。 +- **没有 Python,或版本低于 3.8?** 请使用安装程序(方式一)。 + +首次安装大约需要下载 1 GB,在一般网络下需要几分钟。完成后,CraftBot 会在后台运行,在浏览器中打开 http://localhost:7925,并创建桌面快捷方式。如果 7925 或 7926 端口已被占用,CraftBot 会改用下一个空闲端口,并打印需要打开的地址。 + +首次启动时,浏览器中的引导流程会请你填写 LLM API 密钥。CraftBot 将其保存在 `app/config/settings.json` 中(之后可在设置中修改),不会从 `.env` 文件读取 API 密钥。 -**安装完成后管理服务:** +### 管理 CraftBot + +使用与安装时相同的 `python` 或 `python3` 命令: ```bash python craftbot.py start # 在后台启动 CraftBot python craftbot.py stop # 停止 CraftBot python craftbot.py restart # 重启 CraftBot python craftbot.py status # 查看运行状态以及是否已启用自启动 -python craftbot.py logs # 查看近期日志输出 -python craftbot.py uninstall # 停止运行、移除自启动并卸载所有依赖包 +python craftbot.py logs # 查看最近 50 行日志(更多:logs -n 200) +python craftbot.py uninstall # 停止运行、移除自启动并卸载依赖包 +python run.py --cli # 在终端中运行,而不是在浏览器中 ``` +使用安装程序的用户可以在安装程序窗口中完成同样的操作(**Start**、**Stop**、**Repair**、**Uninstall**)。 + > [!TIP] > 执行 `install` 或 `start` 之后会自动创建 **CraftBot 桌面快捷方式**。如果关闭了浏览器,双击该快捷方式即可重新打开。 @@ -149,63 +197,136 @@ CraftBot 嵌入在每个 Agent App 之中,并且**对其状态保持感知**: ## 🔧 故障排查与常见问题 -### 缺少 Node.js(浏览器模式) -运行 `python run.py` 时看到 **"npm not found in PATH"**: -1. 从 [nodejs.org](https://nodejs.org/) 下载(选择 LTS 版本) -2. 安装并重启终端 -3. 再次运行 `python run.py` +**先查看日志。** `python craftbot.py logs` 显示最近 50 行日志(更多:`logs -n 200`)。`install` 或 `start` 失败时,会打印日志末尾并以错误状态退出。`python craftbot.py doctor` 会逐项检查安装步骤,不做任何改动。在安装程序中可点击 **Open log**。 + +**重新运行安装是安全的。** `python craftbot.py install` 会跳过已成功的步骤,只重试其余步骤。在安装程序中可点击 **Repair**。 + +### 7925 或 7926 端口被占用 + +CraftBot 会改用下一个空闲端口,并打印需要打开的地址。如需自行指定端口: -**替代方案:** 使用 CLI 模式(不需要 Node.js): ```bash -python run.py --cli +python craftbot.py start --frontend-port 8925 --backend-port 8926 ``` -### 安装时依赖失败 -安装器现在会提供更详细的错误信息和解决方案。如果安装失败: -- **检查 Python 版本:** 确认已安装 Python 3.10+ (`python --version`) -- **检查网络连接:** 安装过程中需要下载依赖 -- **清理 pip 缓存:** 运行 `pip install --upgrade pip` 后再次尝试 +### 代理或公司网络 -### Playwright 安装失败 -Playwright Chromium 的安装是可选项。即使失败: -- Agent 在执行其他任务时**仍可正常工作** -- 可以先跳过,稍后再用 `playwright install chromium` 安装 -- 仅在使用 WhatsApp Web 集成时才需要 +所有下载(Python、pip、npm、Node.js)都会使用标准代理环境变量。请在安装前于同一个终端中设置: -更详细的排查请参阅 [INSTALLATION_FIX.md](INSTALLATION_FIX.md)。 +```bash +# macOS 和 Linux +export HTTPS_PROXY=http://proxy.example.com:8080 +export HTTP_PROXY=http://proxy.example.com:8080 +export NO_PROXY=localhost,127.0.0.1 +python3 craftbot.py install +``` ---- -## 🐳 使用容器运行 +```powershell +# Windows PowerShell +$env:HTTPS_PROXY = "http://proxy.example.com:8080" +$env:HTTP_PROXY = "http://proxy.example.com:8080" +$env:NO_PROXY = "localhost,127.0.0.1" +python craftbot.py install +``` -仓库根目录包含一份 Docker 配置,内含 Python 3.10、关键系统包(包括用于 OCR 的 Tesseract)以及 `requirements.txt` 中定义的所有 Python 依赖,确保 Agent 在隔离环境中也能稳定运行。 +对 TLS 流量进行检查的网络无需额外设置:CraftBot 信任操作系统证书库中的证书。 -下面是用容器运行 Agent 的步骤。 +### 下载缓慢或无法访问(例如在中国大陆) -### 构建镜像 +安装前将下载指向镜像: -在仓库根目录执行: +| 变量 | 用途 | 示例 | +|---|---|---| +| `PIP_INDEX_URL` | Python 包 | `https://pypi.tuna.tsinghua.edu.cn/simple` | +| `npm_config_registry` | npm 包 | `https://registry.npmmirror.com` | +| `HF_ENDPOINT` | 嵌入模型 | `https://hf-mirror.com` | +| `CRAFTBOT_MIRRORS` | Python、Node.js、PocketBase 和嵌入模型的下载 | 见下文 | + +`CRAFTBOT_MIRRORS` 是以分号分隔的 `prefix=replacement`(前缀=替换地址)URL 改写规则: ```bash -docker build -t craftbot . +export CRAFTBOT_MIRRORS="https://github.com/=https:///https://github.com/;https://nodejs.org/dist/=https://npmmirror.com/mirrors/node/" ``` -### 运行容器 +Python 依赖包和记忆嵌入模型仍会按固定的 SHA-256 校验值进行校验,因此镜像无法改变它们。Python 和 Node.js 运行时没有固定校验值,请只为它们使用你信任的镜像。在 Windows PowerShell 中,请用 `$env:NAME = "value"` 代替 `export` 设置变量。 + +### 没有桌面环境的服务器 -镜像默认以 `python -m app.main` 启动 Agent。如需交互式运行: +在服务器上从源码安装,并且不打开浏览器: ```bash -docker run --rm -it craftbot +python3 craftbot.py install --no-open-browser ``` -需要传入环境变量时,可以挂载一个 env 文件(例如基于 `.env.example`): +CraftBot 只监听 `localhost`,并且只接受以 `localhost` 访问的浏览器连接。要从自己的电脑访问,请建立一个以相同端口号转发两个端口的 SSH 隧道,然后在自己的电脑上打开 http://localhost:7925: ```bash -docker run --rm -it --env-file .env craftbot +ssh -L 7925:localhost:7925 -L 7926:localhost:7926 user@server ``` -通过 `-v` 挂载需要持久化到容器外的目录(例如数据或缓存目录),并根据你的部署需求调整端口或其他参数。镜像内置了 OCR(`tesseract`)所需的系统依赖和常见的 HTTP 客户端,让 Agent 可以直接在容器内处理文件和网络 API。 +`CRAFTBOT_BIND_HOST` 可以让 CraftBot 监听其他网络接口(Docker 镜像使用 `0.0.0.0`)。远程访问仍应通过 SSH 隧道进行。 + +### Linux:重启后 CraftBot 没有自动启动 + +自启动是一个 systemd 用户服务,因此需要 systemd 用户会话。如需在开机时无需登录即可启动 CraftBot,并在注销后继续运行,请执行一次: + +```bash +loginctl enable-linger $USER +``` + +在没有 systemd 的环境中(例如未启用 systemd 的 WSL),请在每次开机后运行 `python3 craftbot.py start`。 + +### macOS:安装程序被拦截 + +安装程序尚未进行代码签名。在 macOS 15 及更高版本上,先尝试打开一次,然后打开 **系统设置 > 隐私与安全性** 并点击 **仍要打开**(Open Anyway)。在 macOS 12 至 14 上,右键点击该应用并选择 **打开**(Open)。 + +### Windows:SmartScreen 拦截安装程序 + +点击 **更多信息**(More info),再点击 **仍要运行**(Run anyway)。出现该提示是因为安装程序尚未进行代码签名。 + +### Windows:输入 `python` 后打开了 Microsoft Store + +说明系统中没有安装 Python。请使用安装程序,或从 [python.org](https://www.python.org/downloads/) 安装 Python 后运行 `py craftbot.py install`。 + +### 将 CraftBot 的数据存放在其他位置 + +安装前将 `CRAFTBOT_HOME` 设置为某个文件夹(例如容量更大的磁盘上的文件夹),CraftBot 的全部数据和下载的运行时都会存放在那里。自启动会保留该设置。 + +### 浏览器功能(Playwright) + +Mini Browser 和浏览器自动化使用 Playwright 的 Chromium。即使它下载失败,CraftBot 的其余功能仍可正常使用。之后重新运行 `python craftbot.py install` 即可重试。 + +--- + +## 🐳 使用容器运行 + +Docker 镜像以浏览器模式运行 CraftBot,所需组件均已预装:Python 3.10 及其锁定的依赖、Node.js 24、浏览器界面、PocketBase 和 Playwright 的 Chromium。 + +在仓库根目录执行: + +```bash +docker compose up -d +``` + +首次构建需要几分钟。之后打开 http://localhost:7925,在引导流程中填写你的 LLM API 密钥。 + +设置与 API 密钥、Agent 文件、记忆和日志都保存在 `craftbot-data` 卷中,重启容器或重新构建镜像后依然保留。 + +```bash +docker compose logs -f craftbot # 实时查看日志 +docker compose ps # 查看状态(含健康检查) +docker compose down # 停止(数据卷会保留) +git pull && docker compose up -d --build # 更新到最新版本 +``` -镜像默认使用 Python 3.10,并已打包好 `requirements.txt` 中的依赖,因此 `python -m app.main` 开箱即用。 +- 端口只发布在 `127.0.0.1` 上,因为 CraftBot 界面本身没有登录机制。在远程服务器上请保持这一设置,并通过“故障排查”中介绍的 SSH 隧道连接。主机端口请保持为 7925 和 7926:CraftBot 只接受以 `localhost` 访问这两个端口的浏览器连接。 +- 在 shell 或 `docker-compose.yml` 同目录下的 `.env` 文件中设置的代理和镜像变量(`HTTPS_PROXY`、`PIP_INDEX_URL`、`HF_ENDPOINT`、`CRAFTBOT_MIRRORS` 以及 `.env.example` 中列出的其他变量)会传入容器。 +- Agent App 在容器内的 3100 至 3199 端口运行,目前还无法从主机浏览器打开。如需使用 Agent App,请使用安装程序或源码安装。 +- 不使用 Compose 时: + ```bash + docker build -t craftbot . + docker run -d --name craftbot -p 127.0.0.1:7925:7925 -p 127.0.0.1:7926:7926 --shm-size 1g -v craftbot-data:/data craftbot + ``` --- diff --git a/README.de.md b/README.de.md index d3f467af7..ad79ef993 100644 --- a/README.de.md +++ b/README.de.md @@ -56,30 +56,78 @@ Darüber hinaus bringt CraftBot alle Kernfunktionen eines universellen Agent-Fra ## 🧰 Erste Schritte -Voraussetzungen: Python 3.10+ · Node.js 18+ für den Browser-Modus +**Voraussetzungen** + +- Windows 10 oder 11 (x64), macOS 12 oder neuer (Apple Silicon oder Intel) oder Linux (x86_64 oder ARM64) +- Mindestens 5 GB freier Speicherplatz +- Ein API-Schlüssel eines LLM-Anbieters wie OpenAI, Anthropic, Google Gemini oder OpenRouter, oder ein lokales Modell über Ollama +- Nur für die Installation aus dem Quellcode: Python 3.8 oder neuer. Node.js wird nicht benötigt. + +### Option 1: Installer (empfohlen, ohne Python oder Git) + +Lade die passende Datei für dein System vom [neuesten Release](https://github.com/CraftOS-dev/CraftBot/releases/latest) herunter: + +| System | Datei | +|---|---| +| Windows (x64) | `CraftBotInstaller-windows.exe` | +| macOS (Apple Silicon und Intel) | `CraftBotInstaller-macos.zip` | +| Linux (x86_64) | `CraftBotInstaller-linux-x86_64` | +| Linux (ARM64) | `CraftBotInstaller-linux-aarch64` | + +Öffne die Datei und klicke auf **Install CraftBot**. Der Installer lädt alles herunter, was CraftBot braucht, startet CraftBot und öffnet es im Browser. + +Die Installer sind noch nicht codesigniert, daher ist beim ersten Start ein zusätzlicher Schritt nötig: + +- **Windows:** Wenn SmartScreen „Der Computer wurde durch Windows geschützt“ anzeigt, klicke auf **Weitere Informationen** (More info) und dann auf **Trotzdem ausführen** (Run anyway). +- **macOS:** Entpacke die Datei und öffne `CraftBotInstaller.app`. Ab macOS 15 wird der erste Start blockiert: Öffne **Systemeinstellungen > Datenschutz & Sicherheit**, klicke neben dem Hinweis zu CraftBotInstaller auf **Dennoch öffnen** (Open Anyway) und bestätige. Unter macOS 12 bis 14 klickst du stattdessen mit der rechten Maustaste auf die App und wählst **Öffnen** (Open). +- **Linux:** Mache die Datei ausführbar und starte sie in einer Desktop-Sitzung (auf einem Server ohne Desktop nutzt du die Installation aus dem Quellcode): + ```bash + chmod +x CraftBotInstaller-linux-x86_64 + ./CraftBotInstaller-linux-x86_64 + ``` + +### Option 2: Installation aus dem Quellcode + +Jedes Python ab Version 3.8, das bereits auf deinem Rechner ist, reicht aus. CraftBot lädt ein eigenes, privates Python 3.10 und Node.js 24 herunter und verändert das auf deinem System installierte Python oder Node.js nicht. ```bash -# 1. Repository klonen -git clone https://github.com/CraftOS-dev/CraftBot.git +git clone --depth 1 https://github.com/CraftOS-dev/CraftBot.git cd CraftBot +``` -# 2. Installieren, Autostart einrichten und CraftBot starten -python craftbot.py install +Führe dann den Installationsbefehl für dein System aus: + +```bash +# Windows +python craftbot.py install # oder: py craftbot.py install + +# macOS und Linux +python3 craftbot.py install ``` -Mehr ist nicht nötig. Das Terminal schließt sich von selbst, CraftBot läuft im Hintergrund weiter und der Browser öffnet sich automatisch. Zusätzlich wird eine **Desktop-Verknüpfung** angelegt, mit der du den Browser jederzeit wieder öffnen kannst. +- **Kein Git?** Klicke auf der [Repository-Seite](https://github.com/CraftOS-dev/CraftBot) auf **Code > Download ZIP**, entpacke die Datei, öffne ein Terminal im entpackten Ordner und führe denselben Befehl aus. +- **Kein Python oder älter als 3.8?** Nutze den Installer (Option 1). + +Die erste Installation lädt etwa 1 GB herunter und dauert bei einer üblichen Verbindung einige Minuten. Danach läuft CraftBot im Hintergrund, öffnet http://localhost:7925 im Browser und legt eine Desktop-Verknüpfung an. Ist Port 7925 oder 7926 bereits belegt, wählt CraftBot die nächsten freien Ports und gibt die Adresse aus, die du öffnen musst. -**Den Dienst nach der Installation verwalten:** +Beim ersten Start fragt das Onboarding im Browser nach deinem LLM-API-Schlüssel. CraftBot speichert ihn in `app/config/settings.json` (änderbar später unter Einstellungen) und liest keine API-Schlüssel aus einer `.env`-Datei. + +### CraftBot verwalten + +Verwende denselben Befehl `python` oder `python3` wie bei der Installation: ```bash python craftbot.py start # CraftBot im Hintergrund starten python craftbot.py stop # CraftBot stoppen python craftbot.py restart # CraftBot neu starten python craftbot.py status # Prüfen, ob CraftBot läuft und ob Autostart aktiv ist -python craftbot.py logs # Letzte Log-Ausgaben anzeigen +python craftbot.py logs # Die letzten 50 Logzeilen anzeigen (mehr mit logs -n 200) python craftbot.py uninstall # Stoppen, Autostart entfernen und Pakete deinstallieren +python run.py --cli # Im Terminal statt im Browser ausführen ``` +Mit dem Installer erledigst du dasselbe im Installer-Fenster (**Start**, **Stop**, **Repair**, **Uninstall**). + > [!TIP] > Nach `install` oder `start` wird automatisch eine **CraftBot-Desktop-Verknüpfung** erstellt. Wenn du den Browser geschlossen hast, öffnest du ihn per Doppelklick auf die Verknüpfung erneut. @@ -149,63 +197,136 @@ Baue, passe an und entwickle deine eigene Agent App weiter und reduziere deine A ## 🔧 Fehlerbehebung & häufige Probleme -### Node.js fehlt (für den Browser-Modus) -Wenn du beim Ausführen von `python run.py` **„npm not found in PATH"** siehst: -1. Lade die LTS-Version von [nodejs.org](https://nodejs.org/) herunter -2. Installiere sie und starte dein Terminal neu -3. Führe `python run.py` erneut aus +**Beginne mit dem Log.** `python craftbot.py logs` zeigt die letzten 50 Zeilen (mehr mit `logs -n 200`). Schlägt `install` oder `start` fehl, gibt der Befehl das Ende des Logs aus und beendet sich mit einem Fehler. `python craftbot.py doctor` prüft jeden Installationsschritt, ohne etwas zu verändern. Im Installer klickst du auf **Open log**. + +**Die Installation erneut auszuführen ist sicher.** `python craftbot.py install` überspringt bereits erfolgreiche Schritte und wiederholt nur den Rest. Im Installer klickst du auf **Repair**. + +### Port 7925 oder 7926 ist belegt + +CraftBot weicht auf die nächsten freien Ports aus und gibt die Adresse aus, die du öffnen musst. So legst du die Ports selbst fest: -**Alternative:** CLI-Modus verwenden (kein Node.js nötig): ```bash -python run.py --cli +python craftbot.py start --frontend-port 8925 --backend-port 8926 ``` -### Installation schlägt bei Abhängigkeiten fehl -Das Installationsprogramm liefert jetzt detaillierte Fehlermeldungen mit Lösungen. Wenn die Installation fehlschlägt: -- **Python-Version prüfen:** Stelle sicher, dass du Python 3.10+ hast (`python --version`) -- **Internetverbindung prüfen:** Während der Installation werden Abhängigkeiten heruntergeladen -- **Pip-Cache leeren:** `pip install --upgrade pip` ausführen und es erneut versuchen +### Proxy oder Firmennetzwerk -### Probleme bei der Playwright-Installation -Die Installation von Chromium für Playwright ist optional. Falls sie fehlschlägt: -- Der Agent **funktioniert trotzdem** für andere Aufgaben -- Du kannst diesen Schritt überspringen und später `playwright install chromium` ausführen -- Erforderlich ist Chromium nur für die WhatsApp-Web-Integration +Alle Downloads (Python, pip, npm, Node.js) verwenden die üblichen Proxy-Variablen. Setze sie vor der Installation im selben Terminal: -Eine ausführliche Fehlerbehebung findest du in [INSTALLATION_FIX.md](INSTALLATION_FIX.md). +```bash +# macOS und Linux +export HTTPS_PROXY=http://proxy.example.com:8080 +export HTTP_PROXY=http://proxy.example.com:8080 +export NO_PROXY=localhost,127.0.0.1 +python3 craftbot.py install +``` ---- -## 🐳 Mit Container ausführen +```powershell +# Windows PowerShell +$env:HTTPS_PROXY = "http://proxy.example.com:8080" +$env:HTTP_PROXY = "http://proxy.example.com:8080" +$env:NO_PROXY = "localhost,127.0.0.1" +python craftbot.py install +``` -Im Repository-Root liegt eine Docker-Konfiguration mit Python 3.10, wichtigen System-Paketen (inklusive Tesseract für OCR) und allen Python-Abhängigkeiten aus `requirements.txt`, damit der Agent auch in isolierten Umgebungen konsistent läuft. +Netzwerke, die TLS-Verkehr prüfen, brauchen keinen zusätzlichen Schritt: CraftBot vertraut den Zertifikaten im Zertifikatsspeicher deines Betriebssystems. -Hier sind die Schritte, um unseren Agent im Container zu starten. +### Langsame oder blockierte Downloads (zum Beispiel in Festlandchina) -### Image bauen +Leite die Downloads vor der Installation auf Mirrors um: -Im Repository-Root: +| Variable | Wofür | Beispiel | +|---|---|---| +| `PIP_INDEX_URL` | Python-Pakete | `https://pypi.tuna.tsinghua.edu.cn/simple` | +| `npm_config_registry` | npm-Pakete | `https://registry.npmmirror.com` | +| `HF_ENDPOINT` | Embedding-Modell | `https://hf-mirror.com` | +| `CRAFTBOT_MIRRORS` | Downloads von Python, Node.js, PocketBase und Embedding-Modell | siehe unten | + +`CRAFTBOT_MIRRORS` ist eine durch Semikolons getrennte Liste von URL-Umschreibungen im Format `prefix=replacement` (Präfix=Ersatz): ```bash -docker build -t craftbot . +export CRAFTBOT_MIRRORS="https://github.com/=https:///https://github.com/;https://nodejs.org/dist/=https://npmmirror.com/mirrors/node/" ``` -### Container starten +Python-Pakete und das Embedding-Modell für den Speicher werden weiterhin gegen fest hinterlegte SHA-256-Prüfsummen geprüft, ein Mirror kann sie also nicht verändern. Die Python- und Node.js-Laufzeiten sind nicht fest hinterlegt, verwende dafür nur einen Mirror, dem du vertraust. In Windows PowerShell setzt du Variablen mit `$env:NAME = "value"` statt `export`. + +### Server ohne Desktop -Das Image ist so konfiguriert, dass der Agent standardmäßig mit `python -m app.main` startet. So führst du es interaktiv aus: +Installiere CraftBot auf dem Server aus dem Quellcode, ohne einen Browser zu öffnen: ```bash -docker run --rm -it craftbot +python3 craftbot.py install --no-open-browser ``` -Wenn du Umgebungsvariablen übergeben musst, nutze eine env-Datei (zum Beispiel basierend auf `.env.example`): +CraftBot lauscht auf `localhost` und nimmt nur Browserverbindungen an, die an `localhost` gerichtet sind. Um CraftBot von deinem eigenen Rechner aus zu nutzen, öffne einen SSH-Tunnel, der beide Ports mit denselben Nummern weiterleitet, und öffne dann http://localhost:7925 auf deinem Rechner: ```bash -docker run --rm -it --env-file .env craftbot +ssh -L 7925:localhost:7925 -L 7926:localhost:7926 user@server ``` -Mounte mit `-v` Verzeichnisse, die außerhalb des Containers persistieren sollen (etwa Daten- oder Cache-Ordner), und passe Ports und weitere Flags an deine Deployment-Anforderungen an. Das Image bringt die System-Abhängigkeiten für OCR (`tesseract`) sowie gängige HTTP-Clients mit, damit der Agent im Container direkt mit Dateien und Netzwerk-APIs arbeiten kann. +`CRAFTBOT_BIND_HOST` lässt CraftBot auf einer anderen Netzwerkschnittstelle lauschen (das Docker-Image verwendet `0.0.0.0`). Für den Fernzugriff bleibt der SSH-Tunnel der vorgesehene Weg. + +### Linux: CraftBot startet nach einem Neustart nicht + +Der Autostart ist ein systemd-Benutzerdienst und braucht daher eine systemd-Benutzersitzung. Damit CraftBot beim Booten ohne Anmeldung startet und nach dem Abmelden weiterläuft, aktiviere einmalig Lingering: + +```bash +loginctl enable-linger $USER +``` + +Ohne systemd (zum Beispiel unter WSL ohne aktiviertes systemd) startest du CraftBot nach jedem Booten mit `python3 craftbot.py start`. + +### macOS: Der Installer wird blockiert + +Der Installer ist noch nicht codesigniert. Ab macOS 15 versuchst du einmal, ihn zu öffnen, öffnest dann **Systemeinstellungen > Datenschutz & Sicherheit** und klickst auf **Dennoch öffnen** (Open Anyway). Unter macOS 12 bis 14 klickst du mit der rechten Maustaste auf die App und wählst **Öffnen** (Open). + +### Windows: SmartScreen blockiert den Installer + +Klicke auf **Weitere Informationen** (More info) und dann auf **Trotzdem ausführen** (Run anyway). Die Warnung erscheint, weil der Installer noch nicht codesigniert ist. + +### Windows: `python` öffnet den Microsoft Store + +Python ist nicht installiert. Nutze den Installer oder installiere Python von [python.org](https://www.python.org/downloads/) und führe `py craftbot.py install` aus. + +### CraftBot-Daten an einem anderen Ort speichern + +Setze vor der Installation `CRAFTBOT_HOME` auf einen Ordner, damit alle CraftBot-Daten und heruntergeladenen Laufzeitumgebungen dort liegen, zum Beispiel auf einem größeren Laufwerk. Der Autostart übernimmt diese Einstellung. + +### Browser-Funktionen (Playwright) + +Der Mini Browser und die Browser-Automatisierung verwenden Playwrights Chromium. Schlägt dieser Download fehl, funktioniert der Rest von CraftBot trotzdem. Führe später `python craftbot.py install` erneut aus, um es nochmals zu versuchen. + +--- + +## 🐳 Mit Container ausführen + +Das Docker-Image führt CraftBot im Browser-Modus aus, mit allem vorinstalliert: Python 3.10 mit den festgelegten Abhängigkeiten, Node.js 24, die Browser-Oberfläche, PocketBase und Playwrights Chromium. + +Im Stammverzeichnis des Repositorys: + +```bash +docker compose up -d +``` + +Der erste Build dauert einige Minuten. Öffne danach http://localhost:7925 und gib im Onboarding deinen LLM-API-Schlüssel ein. + +Einstellungen und API-Schlüssel, Agent-Dateien, Gedächtnis und Logs liegen im Volume `craftbot-data` und bleiben bei Neustarts und neuen Image-Builds erhalten. + +```bash +docker compose logs -f craftbot # Log fortlaufend anzeigen +docker compose ps # Status inklusive Health-Check +docker compose down # Stoppen (das Daten-Volume bleibt erhalten) +git pull && docker compose up -d --build # Auf die neueste Version aktualisieren +``` -Standardmäßig nutzt das Image Python 3.10 und bündelt die Python-Abhängigkeiten aus `requirements.txt`, daher funktioniert `python -m app.main` sofort. +- Die Ports werden nur auf `127.0.0.1` veröffentlicht, weil die CraftBot-Oberfläche keine eigene Anmeldung hat. Belasse es auf einem entfernten Server dabei und verbinde dich über den SSH-Tunnel, der unter Fehlerbehebung beschrieben ist. Behalte die Host-Ports 7925 und 7926 bei: CraftBot nimmt auf diesen Ports nur Browserverbindungen an, die an `localhost` gerichtet sind. +- Proxy- und Mirror-Einstellungen (`HTTPS_PROXY`, `PIP_INDEX_URL`, `HF_ENDPOINT`, `CRAFTBOT_MIRRORS` und die übrigen in `.env.example`) werden an den Container übergeben, wenn sie in deiner Shell oder in einer `.env`-Datei neben `docker-compose.yml` gesetzt sind. +- Agent Apps laufen im Container auf den Ports 3100 bis 3199 und lassen sich noch nicht im Browser des Hosts öffnen. Für Agent Apps nutzt du den Installer oder die Installation aus dem Quellcode. +- Ohne Compose: + ```bash + docker build -t craftbot . + docker run -d --name craftbot -p 127.0.0.1:7925:7925 -p 127.0.0.1:7926:7926 --shm-size 1g -v craftbot-data:/data craftbot + ``` --- diff --git a/README.es.md b/README.es.md index 0a8fb038d..f47cf5868 100644 --- a/README.es.md +++ b/README.es.md @@ -56,32 +56,80 @@ Más allá de ser un agente de IA capaz de crear y operar sus propias herramient ## 🧰 Primeros pasos -Requisitos: Python 3.10+ · Node.js 18+ para el modo navegador +**Requisitos** + +- Windows 10 u 11 (x64), macOS 12 o posterior (Apple Silicon o Intel), o Linux (x86_64 o ARM64) +- Al menos 5 GB de espacio libre en disco +- Una clave de API de un proveedor de LLM como OpenAI, Anthropic, Google Gemini u OpenRouter, o un modelo local servido con Ollama +- Solo para la instalación desde el código fuente: Python 3.8 o posterior. No hace falta Node.js. + +### Opción 1: Instalador (recomendado, sin Python ni Git) + +Descarga el archivo para tu sistema desde la [última versión publicada](https://github.com/CraftOS-dev/CraftBot/releases/latest): + +| Sistema | Archivo | +|---|---| +| Windows (x64) | `CraftBotInstaller-windows.exe` | +| macOS (Apple Silicon e Intel) | `CraftBotInstaller-macos.zip` | +| Linux (x86_64) | `CraftBotInstaller-linux-x86_64` | +| Linux (ARM64) | `CraftBotInstaller-linux-aarch64` | + +Ábrelo y haz clic en **Install CraftBot**. El instalador descarga todo lo que CraftBot necesita, lo inicia y lo abre en tu navegador. + +Los instaladores todavía no tienen firma de código, así que el primer inicio necesita un paso adicional: + +- **Windows:** si SmartScreen muestra "Windows protegió su PC", haz clic en **Más información** (More info) y luego en **Ejecutar de todas formas** (Run anyway). +- **macOS:** descomprime el archivo y abre `CraftBotInstaller.app`. En macOS 15 o posterior el primer intento se bloquea: abre **Ajustes del Sistema > Privacidad y seguridad**, haz clic en **Abrir igualmente** (Open Anyway) junto al mensaje sobre CraftBotInstaller y confirma. En macOS 12 a 14, haz clic derecho en la app y elige **Abrir** (Open). +- **Linux:** haz el archivo ejecutable y ejecútalo desde una sesión de escritorio (en un servidor sin escritorio, usa la instalación desde el código fuente): + ```bash + chmod +x CraftBotInstaller-linux-x86_64 + ./CraftBotInstaller-linux-x86_64 + ``` + +### Opción 2: Instalar desde el código fuente + +Sirve cualquier Python 3.8 o posterior que ya tengas en tu equipo. CraftBot descarga su propio Python 3.10 y Node.js 24 privados y nunca modifica el Python ni el Node.js instalados en tu sistema. ```bash -# 1. Clona el repositorio -git clone https://github.com/CraftOS-dev/CraftBot.git +git clone --depth 1 https://github.com/CraftOS-dev/CraftBot.git cd CraftBot +``` -# 2. Instala, registra el autoinicio y lanza CraftBot -python craftbot.py install +Después ejecuta el comando de instalación para tu sistema: + +```bash +# Windows +python craftbot.py install # o bien: py craftbot.py install + +# macOS y Linux +python3 craftbot.py install ``` -Eso es todo. La terminal se cierra sola, CraftBot queda corriendo en segundo plano y el navegador se abre automáticamente. Además se crea un **acceso directo en el escritorio** para que puedas reabrir el navegador cuando quieras. +- **¿No tienes Git?** En la [página del repositorio](https://github.com/CraftOS-dev/CraftBot), haz clic en **Code > Download ZIP**, descomprímelo, abre una terminal en la carpeta descomprimida y ejecuta el mismo comando. +- **¿No tienes Python o es anterior a 3.8?** Usa el instalador (opción 1). + +La primera instalación descarga alrededor de 1 GB y tarda unos minutos con una conexión normal. Al terminar, CraftBot queda en segundo plano, abre http://localhost:7925 en tu navegador y crea un acceso directo en el escritorio. Si el puerto 7925 o 7926 ya está en uso, CraftBot elige los siguientes puertos libres y muestra la dirección que debes abrir. + +En el primer inicio, el onboarding del navegador te pide tu clave de API del LLM. CraftBot la guarda en `app/config/settings.json` (puedes cambiarla después en Ajustes) y no lee claves de API desde un archivo `.env`. -**Gestión del servicio tras la instalación:** +### Gestionar CraftBot + +Usa el mismo comando `python` o `python3` que en la instalación: ```bash python craftbot.py start # Inicia CraftBot en segundo plano python craftbot.py stop # Detiene CraftBot python craftbot.py restart # Reinicia CraftBot -python craftbot.py status # Comprueba si está corriendo y si el autoinicio está activo -python craftbot.py logs # Muestra la salida reciente de logs +python craftbot.py status # Comprueba si está en marcha y si el autoinicio está activo +python craftbot.py logs # Muestra las últimas 50 líneas del log (más con logs -n 200) python craftbot.py uninstall # Detiene, quita el autoinicio y desinstala los paquetes +python run.py --cli # Ejecuta en la terminal en lugar del navegador ``` +Si usas el instalador, puedes hacer lo mismo desde su ventana (**Start**, **Stop**, **Repair**, **Uninstall**). + > [!TIP] -> Tras `install` o `start` se crea automáticamente un **acceso directo de CraftBot en el escritorio**. Si cierras el navegador, basta con hacer doble clic en él para volver a abrirlo. +> Tras `install` o `start` se crea automáticamente un **acceso directo de CraftBot en el escritorio**. Si cierras el navegador, haz doble clic en él para volver a abrirlo. --- @@ -149,63 +197,136 @@ Construye, personaliza y haz evolucionar tu propia Agent App, y depende menos de ## 🔧 Solución de problemas y preguntas frecuentes -### Falta Node.js (para el modo navegador) -Si al ejecutar `python run.py` ves **"npm not found in PATH"**: -1. Descarga la versión LTS desde [nodejs.org](https://nodejs.org/) -2. Instálala y reinicia la terminal -3. Vuelve a ejecutar `python run.py` +**Empieza por el log.** `python craftbot.py logs` muestra las últimas 50 líneas (más con `logs -n 200`). Si `install` o `start` fallan, muestran el final del log y terminan con un error. `python craftbot.py doctor` revisa cada paso de la instalación sin cambiar nada. En el instalador, haz clic en **Open log**. + +**Volver a ejecutar la instalación es seguro.** `python craftbot.py install` omite los pasos que ya se completaron y reintenta el resto. En el instalador, haz clic en **Repair**. + +### Los puertos 7925 o 7926 ya están en uso + +CraftBot pasa a los siguientes puertos libres y muestra la dirección que debes abrir. Para elegir los puertos tú mismo: -**Alternativa:** Usa el modo CLI (no necesita Node.js): ```bash -python run.py --cli +python craftbot.py start --frontend-port 8925 --backend-port 8926 ``` -### La instalación falla por dependencias -El instalador ahora muestra mensajes de error detallados con posibles soluciones. Si falla: -- **Comprueba la versión de Python:** asegúrate de tener Python 3.10+ (`python --version`) -- **Comprueba la conexión a internet:** las dependencias se descargan durante la instalación -- **Limpia la caché de pip:** ejecuta `pip install --upgrade pip` y vuelve a intentarlo +### Proxy o red corporativa -### Problemas al instalar Playwright -La instalación de Chromium de Playwright es opcional. Si falla: -- El agente **seguirá funcionando** para el resto de tareas -- Puedes saltártelo e instalarlo más tarde con `playwright install chromium` -- Solo es necesario para la integración con WhatsApp Web +Todas las descargas (Python, pip, npm, Node.js) usan las variables de proxy estándar. Defínelas en la misma terminal antes de instalar: -Para una solución de problemas más detallada, consulta [INSTALLATION_FIX.md](INSTALLATION_FIX.md). +```bash +# macOS y Linux +export HTTPS_PROXY=http://proxy.example.com:8080 +export HTTP_PROXY=http://proxy.example.com:8080 +export NO_PROXY=localhost,127.0.0.1 +python3 craftbot.py install +``` ---- -## 🐳 Ejecutar con un contenedor +```powershell +# Windows PowerShell +$env:HTTPS_PROXY = "http://proxy.example.com:8080" +$env:HTTP_PROXY = "http://proxy.example.com:8080" +$env:NO_PROXY = "localhost,127.0.0.1" +python craftbot.py install +``` -La raíz del repositorio incluye una configuración Docker con Python 3.10, los paquetes de sistema clave (incluido Tesseract para OCR) y todas las dependencias de Python definidas en `requirements.txt`, de modo que el agente puede ejecutarse de forma consistente en entornos aislados. +Las redes que inspeccionan el tráfico TLS no requieren ningún paso adicional: CraftBot confía en los certificados del almacén de certificados de tu sistema operativo. -A continuación tienes las instrucciones para correr nuestro agente con un contenedor. +### Descargas lentas o bloqueadas (por ejemplo, en China continental) -### Construir la imagen +Antes de instalar, dirige las descargas a mirrors: -Desde la raíz del repositorio: +| Variable | Uso | Ejemplo | +|---|---|---| +| `PIP_INDEX_URL` | Paquetes de Python | `https://pypi.tuna.tsinghua.edu.cn/simple` | +| `npm_config_registry` | Paquetes de npm | `https://registry.npmmirror.com` | +| `HF_ENDPOINT` | Modelo de embeddings | `https://hf-mirror.com` | +| `CRAFTBOT_MIRRORS` | Descargas de Python, Node.js, PocketBase y el modelo de embeddings | ver abajo | + +`CRAFTBOT_MIRRORS` es una lista, separada por punto y coma, de reescrituras de URL con el formato `prefix=replacement` (prefijo=sustitución): ```bash -docker build -t craftbot . +export CRAFTBOT_MIRRORS="https://github.com/=https:///https://github.com/;https://nodejs.org/dist/=https://npmmirror.com/mirrors/node/" ``` -### Ejecutar el contenedor +Los paquetes de Python y el modelo de embeddings de la memoria se siguen verificando con checksums SHA-256 fijados, así que un mirror no puede cambiarlos. Los runtimes de Python y Node.js no están fijados, así que para ellos usa solo un mirror de confianza. En Windows PowerShell, define las variables con `$env:NAME = "value"` en lugar de `export`. + +### Servidor sin escritorio -La imagen está configurada para lanzar el agente con `python -m app.main` por defecto. Para ejecutarlo de forma interactiva: +Instala desde el código fuente en el servidor sin abrir un navegador: ```bash -docker run --rm -it craftbot +python3 craftbot.py install --no-open-browser ``` -Si necesitas pasar variables de entorno, usa un archivo env (por ejemplo, basado en `.env.example`): +CraftBot escucha en `localhost` y solo acepta conexiones del navegador dirigidas a `localhost`. Para usarlo desde tu propio equipo, abre un túnel SSH que reenvíe ambos puertos con los mismos números y luego abre http://localhost:7925 en tu equipo: ```bash -docker run --rm -it --env-file .env craftbot +ssh -L 7925:localhost:7925 -L 7926:localhost:7926 user@server ``` -Monta con `-v` los directorios que deban persistir fuera del contenedor (por ejemplo carpetas de datos o caché) y ajusta puertos u otros parámetros según tu despliegue. La imagen trae dependencias del sistema para OCR (`tesseract`) y clientes HTTP habituales, de modo que el agente pueda trabajar con archivos y APIs de red dentro del contenedor. +`CRAFTBOT_BIND_HOST` hace que CraftBot escuche en otra interfaz de red (la imagen de Docker usa `0.0.0.0`). Para el acceso remoto, el túnel SSH sigue siendo la vía recomendada. + +### Linux: CraftBot no arranca después de reiniciar + +El autoinicio es un servicio de usuario de systemd, por lo que necesita una sesión de usuario de systemd. Para que CraftBot arranque al encender el equipo sin iniciar sesión, y siga funcionando después de cerrarla, activa lingering una vez: + +```bash +loginctl enable-linger $USER +``` + +Sin systemd (por ejemplo, en WSL con systemd desactivado), ejecuta `python3 craftbot.py start` después de cada arranque. + +### macOS: el instalador está bloqueado + +El instalador todavía no tiene firma de código. En macOS 15 o posterior, intenta abrirlo una vez, luego abre **Ajustes del Sistema > Privacidad y seguridad** y haz clic en **Abrir igualmente** (Open Anyway). En macOS 12 a 14, haz clic derecho en la app y elige **Abrir** (Open). + +### Windows: SmartScreen bloquea el instalador + +Haz clic en **Más información** (More info) y luego en **Ejecutar de todas formas** (Run anyway). El aviso aparece porque el instalador todavía no tiene firma de código. + +### Windows: `python` abre Microsoft Store + +Python no está instalado. Usa el instalador, o instala Python desde [python.org](https://www.python.org/downloads/) y ejecuta `py craftbot.py install`. + +### Guardar los datos de CraftBot en otro lugar + +Antes de instalar, define `CRAFTBOT_HOME` con una carpeta para guardar allí todos los datos de CraftBot y los runtimes descargados, por ejemplo en un disco más grande. El autoinicio conserva este ajuste. + +### Funciones de navegador (Playwright) + +El Mini Browser y la automatización del navegador usan el Chromium de Playwright. Si su descarga falla, el resto de CraftBot sigue funcionando. Vuelve a ejecutar `python craftbot.py install` más tarde para reintentarlo. + +--- + +## 🐳 Ejecutar con un contenedor + +La imagen de Docker ejecuta CraftBot en modo navegador con todo preinstalado: Python 3.10 con sus dependencias fijadas, Node.js 24, la interfaz del navegador, PocketBase y el Chromium de Playwright. + +Desde la raíz del repositorio: + +```bash +docker compose up -d +``` + +La primera compilación tarda varios minutos. Después abre http://localhost:7925 e introduce tu clave de API del LLM en el onboarding. + +Los ajustes y claves de API, los archivos del agente, la memoria y los logs se guardan en el volumen `craftbot-data`, así que se conservan entre reinicios y nuevas compilaciones de la imagen. + +```bash +docker compose logs -f craftbot # Sigue el log +docker compose ps # Estado, incluido el health check +docker compose down # Detiene (el volumen de datos se conserva) +git pull && docker compose up -d --build # Actualiza a la última versión +``` -Por defecto, la imagen usa Python 3.10 y empaqueta las dependencias de Python de `requirements.txt`, así que `python -m app.main` funciona sin más. +- Los puertos solo se publican en `127.0.0.1`, porque la interfaz de CraftBot no tiene inicio de sesión propio. En un servidor remoto, mantenlo así y conéctate mediante el túnel SSH descrito en Solución de problemas. Mantén los puertos del host en 7925 y 7926: CraftBot solo acepta conexiones del navegador dirigidas a `localhost` en esos puertos. +- Los ajustes de proxy y mirrors (`HTTPS_PROXY`, `PIP_INDEX_URL`, `HF_ENDPOINT`, `CRAFTBOT_MIRRORS` y los demás de `.env.example`) se pasan al contenedor cuando están definidos en tu shell o en un archivo `.env` junto a `docker-compose.yml`. +- Las Agent Apps se ejecutan en los puertos 3100 a 3199 dentro del contenedor y todavía no se pueden abrir desde el navegador del host. Para trabajar con Agent Apps, usa el instalador o la instalación desde el código fuente. +- Sin Compose: + ```bash + docker build -t craftbot . + docker run -d --name craftbot -p 127.0.0.1:7925:7925 -p 127.0.0.1:7926:7926 --shm-size 1g -v craftbot-data:/data craftbot + ``` --- diff --git a/README.fr.md b/README.fr.md index a86581e57..e9fcc5c73 100644 --- a/README.fr.md +++ b/README.fr.md @@ -56,32 +56,80 @@ En plus d'être un agent IA capable de créer et d'opérer ses propres outils Sa ## 🧰 Pour commencer -Prérequis : Python 3.10+ · Node.js 18+ pour le mode navigateur +**Prérequis** + +- Windows 10 ou 11 (x64), macOS 12 ou ultérieur (Apple Silicon ou Intel), ou Linux (x86_64 ou ARM64) +- Au moins 5 Go d'espace disque libre +- Une clé API d'un fournisseur de LLM comme OpenAI, Anthropic, Google Gemini ou OpenRouter, ou un modèle local servi par Ollama +- Pour l'installation depuis les sources uniquement : Python 3.8 ou ultérieur. Node.js n'est pas nécessaire. + +### Option 1 : installateur (recommandé, sans Python ni Git) + +Téléchargez le fichier correspondant à votre système depuis la [dernière version publiée](https://github.com/CraftOS-dev/CraftBot/releases/latest) : + +| Système | Fichier | +|---|---| +| Windows (x64) | `CraftBotInstaller-windows.exe` | +| macOS (Apple Silicon et Intel) | `CraftBotInstaller-macos.zip` | +| Linux (x86_64) | `CraftBotInstaller-linux-x86_64` | +| Linux (ARM64) | `CraftBotInstaller-linux-aarch64` | + +Ouvrez-le et cliquez sur **Install CraftBot**. L'installateur télécharge tout ce dont CraftBot a besoin, le démarre et l'ouvre dans votre navigateur. + +Les installateurs ne sont pas encore signés, le premier lancement demande donc une étape supplémentaire : + +- **Windows :** si SmartScreen affiche « Windows a protégé votre ordinateur », cliquez sur **Informations complémentaires** (More info), puis sur **Exécuter quand même** (Run anyway). +- **macOS :** décompressez le fichier et ouvrez `CraftBotInstaller.app`. Sous macOS 15 ou ultérieur, la première ouverture est bloquée : ouvrez **Réglages Système > Confidentialité et sécurité**, cliquez sur **Ouvrir quand même** (Open Anyway) à côté du message concernant CraftBotInstaller, puis confirmez. Sous macOS 12 à 14, faites un clic droit sur l'app et choisissez **Ouvrir** (Open). +- **Linux :** rendez le fichier exécutable et lancez-le depuis une session de bureau (sur un serveur sans bureau, utilisez l'installation depuis les sources) : + ```bash + chmod +x CraftBotInstaller-linux-x86_64 + ./CraftBotInstaller-linux-x86_64 + ``` + +### Option 2 : installation depuis les sources + +N'importe quel Python 3.8 ou ultérieur déjà présent sur votre ordinateur convient. CraftBot télécharge son propre Python 3.10 et son propre Node.js 24, et ne modifie jamais le Python ou le Node.js installés sur votre système. ```bash -# 1. Cloner le dépôt -git clone https://github.com/CraftOS-dev/CraftBot.git +git clone --depth 1 https://github.com/CraftOS-dev/CraftBot.git cd CraftBot +``` -# 2. Installer, enregistrer le démarrage automatique et lancer CraftBot -python craftbot.py install +Lancez ensuite la commande d'installation pour votre système : + +```bash +# Windows +python craftbot.py install # ou : py craftbot.py install + +# macOS et Linux +python3 craftbot.py install ``` -C'est tout. Le terminal se ferme tout seul, CraftBot tourne en arrière-plan et le navigateur s'ouvre automatiquement. Un **raccourci de bureau** est créé pour vous permettre de rouvrir le navigateur quand vous voulez. +- **Pas de Git ?** Sur la [page du dépôt](https://github.com/CraftOS-dev/CraftBot), cliquez sur **Code > Download ZIP**, décompressez l'archive, ouvrez un terminal dans le dossier décompressé et lancez la même commande. +- **Pas de Python, ou une version antérieure à 3.8 ?** Utilisez l'installateur (option 1). + +La première installation télécharge environ 1 Go, ce qui prend quelques minutes avec une connexion courante. À la fin, CraftBot tourne en arrière-plan, ouvre http://localhost:7925 dans votre navigateur et crée un raccourci sur le bureau. Si le port 7925 ou 7926 est déjà utilisé, CraftBot choisit les ports libres suivants et affiche l'adresse à ouvrir. + +Au premier démarrage, l'onboarding dans le navigateur vous demande votre clé API LLM. CraftBot l'enregistre dans `app/config/settings.json` (modifiable plus tard dans les Réglages) et ne lit jamais de clé API depuis un fichier `.env`. -**Gérer le service après l'installation :** +### Gérer CraftBot + +Utilisez la même commande `python` ou `python3` que pour l'installation : ```bash -python craftbot.py start # Démarre CraftBot en arrière-plan -python craftbot.py stop # Arrête CraftBot -python craftbot.py restart # Redémarre CraftBot -python craftbot.py status # Vérifie s'il tourne et si le démarrage auto est activé -python craftbot.py logs # Affiche la sortie récente des logs -python craftbot.py uninstall # Arrête, supprime le démarrage auto et désinstalle les paquets +python craftbot.py start # Démarrer CraftBot en arrière-plan +python craftbot.py stop # Arrêter CraftBot +python craftbot.py restart # Redémarrer CraftBot +python craftbot.py status # Vérifier s'il tourne et si le démarrage automatique est actif +python craftbot.py logs # Afficher les 50 dernières lignes du journal (davantage avec logs -n 200) +python craftbot.py uninstall # Arrêter, retirer le démarrage automatique et désinstaller les paquets +python run.py --cli # Lancer dans le terminal plutôt que dans le navigateur ``` +Avec l'installateur, les mêmes actions sont disponibles dans sa fenêtre (**Start**, **Stop**, **Repair**, **Uninstall**). + > [!TIP] -> Après `install` ou `start`, un **raccourci CraftBot sur le bureau** est créé automatiquement. Si vous fermez le navigateur, il suffit de double-cliquer sur le raccourci pour le rouvrir. +> Après `install` ou `start`, un **raccourci CraftBot sur le bureau** est créé automatiquement. Si vous fermez le navigateur, double-cliquez sur le raccourci pour le rouvrir. --- @@ -149,63 +197,136 @@ Construisez, personnalisez et faites évoluer votre propre Agent App, et dépend ## 🔧 Dépannage et problèmes courants -### Node.js manquant (pour le mode navigateur) -Si vous voyez **« npm not found in PATH »** en lançant `python run.py` : -1. Téléchargez la version LTS depuis [nodejs.org](https://nodejs.org/) -2. Installez-la et redémarrez votre terminal -3. Relancez `python run.py` +**Commencez par le journal.** `python craftbot.py logs` affiche les 50 dernières lignes (davantage avec `logs -n 200`). Lorsque `install` ou `start` échoue, la commande affiche la fin du journal et se termine avec une erreur. `python craftbot.py doctor` vérifie chaque étape de l'installation sans rien modifier. Dans l'installateur, cliquez sur **Open log**. + +**Relancer l'installation ne pose aucun risque.** `python craftbot.py install` saute les étapes déjà réussies et ne réessaie que les autres. Dans l'installateur, cliquez sur **Repair**. + +### Les ports 7925 ou 7926 sont déjà utilisés + +CraftBot passe aux ports libres suivants et affiche l'adresse à ouvrir. Pour choisir les ports vous-même : -**Alternative :** Utilisez le mode CLI (Node.js non requis) : ```bash -python run.py --cli +python craftbot.py start --frontend-port 8925 --backend-port 8926 ``` -### L'installation échoue à cause des dépendances -L'installateur affiche désormais des messages d'erreur détaillés avec des pistes de résolution. Si l'installation échoue : -- **Vérifiez votre version de Python :** assurez-vous d'avoir Python 3.10+ (`python --version`) -- **Vérifiez votre connexion internet :** les dépendances sont téléchargées pendant l'installation -- **Videz le cache de pip :** lancez `pip install --upgrade pip` et réessayez +### Proxy ou réseau d'entreprise -### Problèmes d'installation de Playwright -L'installation de Chromium pour Playwright est optionnelle. Si elle échoue : -- L'agent **continue de fonctionner** pour les autres tâches -- Vous pouvez la sauter et l'installer plus tard via `playwright install chromium` -- Elle n'est nécessaire que pour l'intégration WhatsApp Web +Tous les téléchargements (Python, pip, npm, Node.js) utilisent les variables de proxy standard. Définissez-les dans le même terminal avant l'installation : -Pour un dépannage plus approfondi, voir [INSTALLATION_FIX.md](INSTALLATION_FIX.md). +```bash +# macOS et Linux +export HTTPS_PROXY=http://proxy.example.com:8080 +export HTTP_PROXY=http://proxy.example.com:8080 +export NO_PROXY=localhost,127.0.0.1 +python3 craftbot.py install +``` ---- -## 🐳 Lancer dans un conteneur +```powershell +# Windows PowerShell +$env:HTTPS_PROXY = "http://proxy.example.com:8080" +$env:HTTP_PROXY = "http://proxy.example.com:8080" +$env:NO_PROXY = "localhost,127.0.0.1" +python craftbot.py install +``` -La racine du dépôt contient une configuration Docker avec Python 3.10, les paquets système essentiels (dont Tesseract pour l'OCR) et toutes les dépendances Python définies dans `requirements.txt`, afin que l'agent tourne de manière cohérente dans des environnements isolés. +Les réseaux qui inspectent le trafic TLS ne demandent aucune étape supplémentaire : CraftBot fait confiance aux certificats du magasin de certificats de votre système d'exploitation. -Voici les étapes pour lancer notre agent dans un conteneur. +### Téléchargements lents ou bloqués (par exemple en Chine continentale) -### Construire l'image +Avant l'installation, redirigez les téléchargements vers des miroirs : -Depuis la racine du dépôt : +| Variable | Usage | Exemple | +|---|---|---| +| `PIP_INDEX_URL` | Paquets Python | `https://pypi.tuna.tsinghua.edu.cn/simple` | +| `npm_config_registry` | Paquets npm | `https://registry.npmmirror.com` | +| `HF_ENDPOINT` | Modèle d'embeddings | `https://hf-mirror.com` | +| `CRAFTBOT_MIRRORS` | Téléchargements de Python, Node.js, PocketBase et du modèle d'embeddings | voir ci-dessous | + +`CRAFTBOT_MIRRORS` est une liste de réécritures d'URL au format `prefix=replacement` (préfixe=remplacement), séparées par des points-virgules : ```bash -docker build -t craftbot . +export CRAFTBOT_MIRRORS="https://github.com/=https:///https://github.com/;https://nodejs.org/dist/=https://npmmirror.com/mirrors/node/" ``` -### Lancer le conteneur +Les paquets Python et le modèle d'embeddings de la mémoire restent vérifiés avec des sommes de contrôle SHA-256 épinglées : un miroir ne peut donc pas les modifier. Les environnements d'exécution Python et Node.js ne sont pas épinglés, n'utilisez donc pour eux qu'un miroir de confiance. Dans Windows PowerShell, définissez les variables avec `$env:NAME = "value"` au lieu de `export`. + +### Serveur sans bureau -Par défaut, l'image lance l'agent avec `python -m app.main`. Pour le lancer de manière interactive : +Installez depuis les sources sur le serveur sans ouvrir de navigateur : ```bash -docker run --rm -it craftbot +python3 craftbot.py install --no-open-browser ``` -Si vous devez passer des variables d'environnement, utilisez un fichier env (par exemple basé sur `.env.example`) : +CraftBot écoute sur `localhost` et n'accepte que les connexions de navigateur adressées à `localhost`. Pour l'utiliser depuis votre propre ordinateur, ouvrez un tunnel SSH qui redirige les deux ports avec les mêmes numéros, puis ouvrez http://localhost:7925 sur votre ordinateur : ```bash -docker run --rm -it --env-file .env craftbot +ssh -L 7925:localhost:7925 -L 7926:localhost:7926 user@server ``` -Montez avec `-v` les répertoires qui doivent persister en dehors du conteneur (par exemple les dossiers de données ou de cache) et ajustez les ports ou les autres flags en fonction de votre déploiement. L'image embarque les dépendances système nécessaires à l'OCR (`tesseract`) et des clients HTTP courants, pour que l'agent puisse manipuler des fichiers et des APIs réseau directement dans le conteneur. +`CRAFTBOT_BIND_HOST` fait écouter CraftBot sur une autre interface réseau (l'image Docker utilise `0.0.0.0`). Pour l'accès à distance, le tunnel SSH reste la méthode prévue. + +### Linux : CraftBot ne démarre pas après un redémarrage + +Le démarrage automatique est un service utilisateur systemd ; il a donc besoin d'une session utilisateur systemd. Pour que CraftBot démarre au boot sans ouverture de session et continue de tourner après la déconnexion, activez le lingering une fois : + +```bash +loginctl enable-linger $USER +``` + +Sans systemd (par exemple WSL sans systemd activé), lancez `python3 craftbot.py start` après chaque démarrage. + +### macOS : l'installateur est bloqué + +L'installateur n'est pas encore signé. Sous macOS 15 ou ultérieur, essayez de l'ouvrir une fois, puis ouvrez **Réglages Système > Confidentialité et sécurité** et cliquez sur **Ouvrir quand même** (Open Anyway). Sous macOS 12 à 14, faites un clic droit sur l'app et choisissez **Ouvrir** (Open). + +### Windows : SmartScreen bloque l'installateur + +Cliquez sur **Informations complémentaires** (More info), puis sur **Exécuter quand même** (Run anyway). L'avertissement apparaît parce que l'installateur n'est pas encore signé. + +### Windows : `python` ouvre le Microsoft Store + +Python n'est pas installé. Utilisez l'installateur, ou installez Python depuis [python.org](https://www.python.org/downloads/) puis lancez `py craftbot.py install`. + +### Stocker les données de CraftBot ailleurs + +Avant l'installation, définissez `CRAFTBOT_HOME` sur un dossier pour y conserver toutes les données de CraftBot et les environnements d'exécution téléchargés, par exemple sur un disque plus grand. Le démarrage automatique conserve ce réglage. + +### Fonctions de navigateur (Playwright) + +Le Mini Browser et l'automatisation du navigateur utilisent le Chromium de Playwright. Si son téléchargement échoue, le reste de CraftBot fonctionne quand même. Relancez `python craftbot.py install` plus tard pour réessayer. + +--- + +## 🐳 Lancer dans un conteneur + +L'image Docker exécute CraftBot en mode navigateur avec tout le nécessaire préinstallé : Python 3.10 et ses dépendances verrouillées, Node.js 24, l'interface du navigateur, PocketBase et le Chromium de Playwright. + +Depuis la racine du dépôt : + +```bash +docker compose up -d +``` + +La première construction prend plusieurs minutes. Ouvrez ensuite http://localhost:7925 et saisissez votre clé API LLM dans l'onboarding. + +Les réglages et clés API, les fichiers de l'agent, la mémoire et les journaux sont conservés dans le volume `craftbot-data` : ils survivent aux redémarrages et aux reconstructions de l'image. + +```bash +docker compose logs -f craftbot # Suivre le journal +docker compose ps # État, y compris le contrôle de santé +docker compose down # Arrêter (le volume de données est conservé) +git pull && docker compose up -d --build # Mettre à jour vers la dernière version +``` -Par défaut, l'image utilise Python 3.10 et embarque les dépendances Python de `requirements.txt`, donc `python -m app.main` fonctionne directement. +- Les ports ne sont publiés que sur `127.0.0.1`, car l'interface de CraftBot n'a pas de connexion propre. Sur un serveur distant, gardez ce réglage et connectez-vous via le tunnel SSH décrit dans la section Dépannage. Conservez les ports 7925 et 7926 côté hôte : CraftBot n'accepte sur ces ports que les connexions de navigateur adressées à `localhost`. +- Les réglages de proxy et de miroirs (`HTTPS_PROXY`, `PIP_INDEX_URL`, `HF_ENDPOINT`, `CRAFTBOT_MIRRORS` et les autres listés dans `.env.example`) sont transmis au conteneur lorsqu'ils sont définis dans votre shell ou dans un fichier `.env` à côté de `docker-compose.yml`. +- Les Agent Apps tournent sur les ports 3100 à 3199 dans le conteneur et ne peuvent pas encore être ouvertes depuis le navigateur de l'hôte. Pour travailler avec des Agent Apps, utilisez l'installateur ou l'installation depuis les sources. +- Sans Compose : + ```bash + docker build -t craftbot . + docker run -d --name craftbot -p 127.0.0.1:7925:7925 -p 127.0.0.1:7926:7926 --shm-size 1g -v craftbot-data:/data craftbot + ``` --- diff --git a/README.ja.md b/README.ja.md index d2063c084..a9a601d8e 100644 --- a/README.ja.md +++ b/README.ja.md @@ -56,32 +56,80 @@ ## 🧰 はじめに -必要条件: Python 3.10+ ・ ブラウザモードを使う場合は Node.js 18+ +**必要条件** + +- Windows 10 または 11(x64)、macOS 12 以降(Apple Silicon または Intel)、または Linux(x86_64 または ARM64) +- 5 GB 以上の空きディスク容量 +- LLM プロバイダー(OpenAI、Anthropic、Google Gemini、OpenRouter など)の API キー、または Ollama で動かすローカルモデル +- ソースからインストールする場合のみ: Python 3.8 以降。Node.js は不要です。 + +### 方法 1: インストーラー(推奨、Python や Git は不要) + +[最新リリース](https://github.com/CraftOS-dev/CraftBot/releases/latest)から、お使いのシステム用のファイルをダウンロードしてください。 + +| システム | ファイル | +|---|---| +| Windows(x64) | `CraftBotInstaller-windows.exe` | +| macOS(Apple Silicon と Intel) | `CraftBotInstaller-macos.zip` | +| Linux(x86_64) | `CraftBotInstaller-linux-x86_64` | +| Linux(ARM64) | `CraftBotInstaller-linux-aarch64` | + +ファイルを開いて **Install CraftBot** をクリックします。インストーラーが CraftBot に必要なものをすべてダウンロードし、CraftBot を起動してブラウザで開きます。 + +インストーラーはまだコード署名されていないため、初回の起動時に次の操作が 1 つ必要です。 + +- **Windows:** SmartScreen に「Windows によって PC が保護されました」と表示されたら、**詳細情報**(More info)をクリックし、**実行**(Run anyway)をクリックします。 +- **macOS:** ファイルを解凍して `CraftBotInstaller.app` を開きます。macOS 15 以降では最初の起動がブロックされます。**システム設定 > プライバシーとセキュリティ** を開き、CraftBotInstaller に関するメッセージの横にある **このまま開く**(Open Anyway)をクリックして確認します。macOS 12 から 14 では、アプリを右クリックして **開く**(Open)を選びます。 +- **Linux:** ファイルに実行権限を付け、デスクトップセッションから実行します(デスクトップのないサーバーではソースからインストールしてください)。 + ```bash + chmod +x CraftBotInstaller-linux-x86_64 + ./CraftBotInstaller-linux-x86_64 + ``` + +### 方法 2: ソースからインストール + +コンピューターにすでにある Python 3.8 以降であれば、どのバージョンでも使えます。CraftBot は専用の Python 3.10 と Node.js 24 を自分でダウンロードし、システムにインストールされている Python や Node.js は変更しません。 ```bash -# 1. リポジトリをクローン -git clone https://github.com/CraftOS-dev/CraftBot.git +git clone --depth 1 https://github.com/CraftOS-dev/CraftBot.git cd CraftBot +``` -# 2. インストール、自動起動の登録、CraftBotの起動 -python craftbot.py install +続いて、お使いのシステムに合わせてインストールコマンドを実行します。 + +```bash +# Windows +python craftbot.py install # または: py craftbot.py install + +# macOS と Linux +python3 craftbot.py install ``` -これだけです。ターミナルは自動で閉じ、CraftBotはバックグラウンドで稼働し、ブラウザが自動で開きます。再度ブラウザを開けるように**デスクトップショートカット**も作成されます。 +- **Git がない場合:** [リポジトリのページ](https://github.com/CraftOS-dev/CraftBot)で **Code > Download ZIP** をクリックし、解凍したフォルダーでターミナルを開いて同じコマンドを実行します。 +- **Python がない、または 3.8 より古い場合:** インストーラー(方法 1)を使ってください。 + +初回のインストールでは約 1 GB をダウンロードするため、一般的な回線で数分かかります。完了すると CraftBot はバックグラウンドで動作し、ブラウザで http://localhost:7925 を開き、デスクトップショートカットを作成します。ポート 7925 または 7926 が使用中の場合は、次に空いているポートを使い、開くべきアドレスを表示します。 -**インストール後のサービス管理:** +初回起動時には、ブラウザのオンボーディングで LLM の API キーを入力します。キーは `app/config/settings.json` に保存され(後から設定画面で変更できます)、CraftBot が `.env` ファイルから API キーを読み込むことはありません。 + +### CraftBot の管理 + +インストール時と同じ `python` または `python3` コマンドを使います。 ```bash -python craftbot.py start # CraftBotをバックグラウンドで起動 -python craftbot.py stop # CraftBotを停止 -python craftbot.py restart # CraftBotを再起動 -python craftbot.py status # 実行状態と自動起動の有無を確認 -python craftbot.py logs # 最近のログ出力を表示 -python craftbot.py uninstall # 停止・自動起動の解除・パッケージのアンインストール +python craftbot.py start # CraftBot をバックグラウンドで起動 +python craftbot.py stop # CraftBot を停止 +python craftbot.py restart # CraftBot を再起動 +python craftbot.py status # 稼働状況と自動起動の有無を確認 +python craftbot.py logs # 直近 50 行のログを表示(さらに見るには logs -n 200) +python craftbot.py uninstall # 停止し、自動起動を解除し、パッケージをアンインストール +python run.py --cli # ブラウザではなくターミナルで実行 ``` +インストーラーを使っている場合は、インストーラーのウィンドウから同じ操作ができます(**Start**、**Stop**、**Repair**、**Uninstall**)。 + > [!TIP] -> `install`や`start`の後には、**CraftBotのデスクトップショートカット**が自動で作成されます。ブラウザを閉じてしまったら、このショートカットをダブルクリックするだけで再び開けます。 +> `install`や`start`の後には、**CraftBotのデスクトップショートカット**が自動で作成されます。ブラウザを閉じてしまった場合は、このショートカットをダブルクリックすると再び開けます。 --- @@ -149,63 +197,136 @@ CraftBotはすべてのAgent Appに組み込まれており、**状態を常に ## 🔧 トラブルシューティングとよくある問題 -### Node.jsが見つからない (ブラウザモード) -`python run.py`を実行したときに **「npm not found in PATH」** と表示された場合: -1. [nodejs.org](https://nodejs.org/)からLTS版をダウンロード -2. インストール後、ターミナルを再起動 -3. もう一度`python run.py`を実行 +**まずログを確認してください。** `python craftbot.py logs` で直近 50 行を表示できます(さらに見るには `logs -n 200`)。`install` や `start` が失敗した場合は、ログの末尾を表示してエラーで終了します。`python craftbot.py doctor` は何も変更せずに各インストール手順を確認します。インストーラーでは **Open log** をクリックします。 + +**インストールは何度実行しても安全です。** `python craftbot.py install` は成功済みの手順を飛ばし、残りだけを再試行します。インストーラーでは **Repair** をクリックします。 + +### ポート 7925 または 7926 が使用中 + +CraftBot は次に空いているポートに切り替え、開くべきアドレスを表示します。ポートを自分で指定するには次のようにします。 -**代替手段:** 代わりにCLIモードを使用(Node.js不要): ```bash -python run.py --cli +python craftbot.py start --frontend-port 8925 --backend-port 8926 ``` -### 依存関係のせいでインストールに失敗する -インストーラーは詳細なエラーメッセージと対処法を表示するようになりました。失敗した場合: -- **Pythonのバージョンを確認:** Python 3.10以上か確認(`python --version`) -- **インターネット接続を確認:** インストール中に依存関係をダウンロードします -- **pipキャッシュをクリア:** `pip install --upgrade pip`を実行してからやり直す +### プロキシや社内ネットワーク -### Playwrightのインストールに失敗する -Playwright Chromiumのインストールは任意です。失敗しても: -- 他のタスクではエージェントは**問題なく動作**します -- スキップして、あとから`playwright install chromium`でインストール可能 -- WhatsApp Web連携を使う場合にのみ必要です +すべてのダウンロード(Python、pip、npm、Node.js)は標準のプロキシ環境変数を使います。インストールの前に、同じターミナルで設定してください。 -詳しいトラブルシューティングは [INSTALLATION_FIX.md](INSTALLATION_FIX.md) を参照してください。 +```bash +# macOS と Linux +export HTTPS_PROXY=http://proxy.example.com:8080 +export HTTP_PROXY=http://proxy.example.com:8080 +export NO_PROXY=localhost,127.0.0.1 +python3 craftbot.py install +``` ---- -## 🐳 コンテナで実行する +```powershell +# Windows PowerShell +$env:HTTPS_PROXY = "http://proxy.example.com:8080" +$env:HTTP_PROXY = "http://proxy.example.com:8080" +$env:NO_PROXY = "localhost,127.0.0.1" +python craftbot.py install +``` -リポジトリのルートには、Python 3.10、主要なシステムパッケージ(OCR用のTesseractを含む)、そして`requirements.txt`で定義されたすべてのPython依存関係を含むDocker構成が用意されており、隔離された環境でもエージェントを一貫して動かせます。 +TLS 通信を検査するネットワークでも追加の設定は不要です。CraftBot は OS の証明書ストアにある証明書を信頼します。 -以下は、コンテナでエージェントを動かすための手順です。 +### ダウンロードが遅い、またはつながらない(中国本土など) -### イメージをビルドする +インストールの前に、ダウンロード先をミラーに向けてください。 -リポジトリのルートから: +| 変数 | 用途 | 例 | +|---|---|---| +| `PIP_INDEX_URL` | Python パッケージ | `https://pypi.tuna.tsinghua.edu.cn/simple` | +| `npm_config_registry` | npm パッケージ | `https://registry.npmmirror.com` | +| `HF_ENDPOINT` | 埋め込みモデル | `https://hf-mirror.com` | +| `CRAFTBOT_MIRRORS` | Python、Node.js、PocketBase、埋め込みモデルのダウンロード | 下記参照 | + +`CRAFTBOT_MIRRORS` は、`prefix=replacement`(プレフィックス=置き換え先)形式の URL 書き換えルールをセミコロンで区切って並べたものです。 ```bash -docker build -t craftbot . +export CRAFTBOT_MIRRORS="https://github.com/=https:///https://github.com/;https://nodejs.org/dist/=https://npmmirror.com/mirrors/node/" ``` -### コンテナを実行する +Python パッケージとメモリ用の埋め込みモデルは、ミラーを使っても固定された SHA-256 チェックサムで検証されるため、ミラーがそれらを変えることはできません。Python と Node.js のランタイムはチェックサムが固定されていないため、信頼できるミラーだけを使ってください。Windows PowerShell では `export` の代わりに `$env:NAME = "value"` で変数を設定します。 + +### デスクトップのないサーバー -イメージは既定で`python -m app.main`を起動するように設定されています。インタラクティブに動かす場合: +サーバーでソースからインストールし、ブラウザは開かないようにします。 ```bash -docker run --rm -it craftbot +python3 craftbot.py install --no-open-browser ``` -環境変数が必要な場合は、envファイルを渡してください(例として`.env.example`を元に作成): +CraftBot は `localhost` で待ち受け、`localhost` 宛てのブラウザ接続だけを受け付けます。自分のコンピューターから使うには、両方のポートを同じ番号で転送する SSH トンネルを作成し、自分のコンピューターで http://localhost:7925 を開きます。 ```bash -docker run --rm -it --env-file .env craftbot +ssh -L 7925:localhost:7925 -L 7926:localhost:7926 user@server ``` -コンテナ外に永続化したいディレクトリ(データやキャッシュなど)は`-v`でマウントし、ポートやその他のフラグもデプロイ要件に応じて調整してください。コンテナにはOCR用(`tesseract`)や一般的なHTTPクライアントなどのシステム依存が同梱されているので、ファイル操作やネットワークAPIをコンテナ内でそのまま扱えます。 +`CRAFTBOT_BIND_HOST` を設定すると、CraftBot は別のネットワークインターフェースで待ち受けます(Docker イメージでは `0.0.0.0`)。リモートからのアクセスには、引き続き SSH トンネルを使ってください。 + +### Linux: 再起動後に CraftBot が起動しない + +自動起動は systemd のユーザーサービスなので、systemd のユーザーセッションが必要です。ログインしなくても起動時に CraftBot を開始し、ログアウト後も動かし続けるには、次のコマンドを一度実行します。 + +```bash +loginctl enable-linger $USER +``` + +systemd がない環境(systemd を有効にしていない WSL など)では、起動のたびに `python3 craftbot.py start` を実行してください。 + +### macOS: インストーラーがブロックされる + +インストーラーはまだコード署名されていません。macOS 15 以降では、一度開こうとした後に **システム設定 > プライバシーとセキュリティ** を開き、**このまま開く**(Open Anyway)をクリックします。macOS 12 から 14 では、アプリを右クリックして **開く**(Open)を選びます。 + +### Windows: SmartScreen がインストーラーをブロックする + +**詳細情報**(More info)をクリックし、**実行**(Run anyway)をクリックします。この警告は、インストーラーがまだコード署名されていないために表示されます。 + +### Windows: `python` を実行すると Microsoft Store が開く + +Python がインストールされていません。インストーラーを使うか、[python.org](https://www.python.org/downloads/) から Python をインストールして `py craftbot.py install` を実行してください。 + +### CraftBot のデータを別の場所に置く + +インストールの前に `CRAFTBOT_HOME` にフォルダーを指定すると、CraftBot のデータとダウンロードしたランタイムがすべてそこに保存されます(容量の大きいドライブなど)。自動起動でもこの設定が引き継がれます。 + +### ブラウザ機能(Playwright) + +Mini Browser とブラウザ自動化は Playwright の Chromium を使います。このダウンロードに失敗しても、CraftBot のほかの機能はそのまま使えます。後で `python craftbot.py install` をもう一度実行すると再試行します。 + +--- + +## 🐳 コンテナで実行する + +Docker イメージは、必要なものがすべてプリインストールされた状態で CraftBot をブラウザモードで実行します。内容は Python 3.10 とロックされた依存関係、Node.js 24、ブラウザ UI、PocketBase、Playwright の Chromium です。 + +リポジトリのルートで次を実行します。 + +```bash +docker compose up -d +``` + +初回のビルドには数分かかります。その後 http://localhost:7925 を開き、オンボーディングで LLM の API キーを入力します。 + +設定と API キー、エージェントのファイル、メモリー、ログは `craftbot-data` ボリュームに保存されるため、コンテナの再起動やイメージの再ビルド後も残ります。 + +```bash +docker compose logs -f craftbot # ログを追跡表示 +docker compose ps # ヘルスチェックを含む状態を確認 +docker compose down # 停止(データボリュームは残ります) +git pull && docker compose up -d --build # 最新バージョンに更新 +``` -既定ではPython 3.10を使い、`requirements.txt`のPython依存関係を取り込んでいるので、`python -m app.main`がすぐに動きます。 +- CraftBot の UI には独自のログイン機能がないため、ポートは `127.0.0.1` にのみ公開されます。リモートサーバーでもこの設定のままにし、トラブルシューティングで説明している SSH トンネルで接続してください。ホスト側のポートは 7925 と 7926 のままにしてください。CraftBot は、これらのポートへの `localhost` 宛てのブラウザ接続だけを受け付けます。 +- シェル、または `docker-compose.yml` と同じフォルダーの `.env` ファイルで設定したプロキシとミラーの変数(`HTTPS_PROXY`、`PIP_INDEX_URL`、`HF_ENDPOINT`、`CRAFTBOT_MIRRORS` と、`.env.example` に記載のその他の変数)は、コンテナに渡されます。 +- Agent App はコンテナ内のポート 3100 から 3199 で動作し、現時点ではホストのブラウザから開けません。Agent App を使う場合は、インストーラーまたはソースからのインストールを使ってください。 +- Compose を使わない場合: + ```bash + docker build -t craftbot . + docker run -d --name craftbot -p 127.0.0.1:7925:7925 -p 127.0.0.1:7926:7926 --shm-size 1g -v craftbot-data:/data craftbot + ``` --- diff --git a/README.ko.md b/README.ko.md index ff9d91656..c80c45fd7 100644 --- a/README.ko.md +++ b/README.ko.md @@ -56,32 +56,80 @@ ## 🧰 시작하기 -요구 사항: Python 3.10+ · 브라우저 모드는 Node.js 18+ 필요 +**요구 사항** + +- Windows 10 또는 11(x64), macOS 12 이상(Apple Silicon 또는 Intel), 또는 Linux(x86_64 또는 ARM64) +- 5 GB 이상의 여유 디스크 공간 +- LLM 제공업체(OpenAI, Anthropic, Google Gemini, OpenRouter 등)의 API 키, 또는 Ollama로 실행하는 로컬 모델 +- 소스 설치에만 필요: Python 3.8 이상. Node.js는 필요하지 않습니다. + +### 방법 1: 설치 프로그램(권장, Python과 Git 불필요) + +[최신 릴리스](https://github.com/CraftOS-dev/CraftBot/releases/latest)에서 사용 중인 시스템에 맞는 파일을 내려받으세요. + +| 시스템 | 파일 | +|---|---| +| Windows(x64) | `CraftBotInstaller-windows.exe` | +| macOS(Apple Silicon 및 Intel) | `CraftBotInstaller-macos.zip` | +| Linux(x86_64) | `CraftBotInstaller-linux-x86_64` | +| Linux(ARM64) | `CraftBotInstaller-linux-aarch64` | + +파일을 열고 **Install CraftBot**을 클릭합니다. 설치 프로그램이 CraftBot에 필요한 모든 것을 내려받고, CraftBot을 시작한 뒤 브라우저에서 엽니다. + +설치 프로그램은 아직 코드 서명이 되어 있지 않아 처음 실행할 때 한 단계가 더 필요합니다. + +- **Windows:** SmartScreen에 "Windows의 PC 보호" 메시지가 표시되면 **추가 정보**(More info)를 클릭한 다음 **실행**(Run anyway)을 클릭합니다. +- **macOS:** 파일의 압축을 풀고 `CraftBotInstaller.app`을 엽니다. macOS 15 이상에서는 처음 실행이 차단됩니다. **시스템 설정 > 개인정보 보호 및 보안**을 열고 CraftBotInstaller 관련 메시지 옆의 **그래도 열기**(Open Anyway)를 클릭한 뒤 확인합니다. macOS 12부터 14까지는 앱을 마우스 오른쪽 버튼으로 클릭하고 **열기**(Open)를 선택합니다. +- **Linux:** 파일에 실행 권한을 주고 데스크톱 세션에서 실행합니다(데스크톱이 없는 서버에서는 소스 설치를 사용하세요). + ```bash + chmod +x CraftBotInstaller-linux-x86_64 + ./CraftBotInstaller-linux-x86_64 + ``` + +### 방법 2: 소스에서 설치 + +컴퓨터에 이미 있는 Python 3.8 이상이면 어떤 버전이든 됩니다. CraftBot은 전용 Python 3.10과 Node.js 24를 직접 내려받으며, 시스템에 설치된 Python이나 Node.js는 변경하지 않습니다. ```bash -# 1. 저장소 클론 -git clone https://github.com/CraftOS-dev/CraftBot.git +git clone --depth 1 https://github.com/CraftOS-dev/CraftBot.git cd CraftBot +``` -# 2. 설치, 자동 시작 등록, CraftBot 실행 -python craftbot.py install +그다음 사용 중인 시스템에 맞는 설치 명령을 실행합니다. + +```bash +# Windows +python craftbot.py install # 또는: py craftbot.py install + +# macOS 및 Linux +python3 craftbot.py install ``` -이것이 전부입니다. 터미널은 자동으로 닫히고, CraftBot은 백그라운드에서 실행되며, 브라우저가 자동으로 열립니다. 언제든 다시 브라우저를 열 수 있도록 **데스크톱 바로가기**도 함께 만들어집니다. +- **Git이 없나요?** [저장소 페이지](https://github.com/CraftOS-dev/CraftBot)에서 **Code > Download ZIP**을 클릭하고, 압축을 푼 폴더에서 터미널을 열어 같은 명령을 실행하세요. +- **Python이 없거나 3.8보다 오래된 버전인가요?** 설치 프로그램(방법 1)을 사용하세요. + +첫 설치에서는 약 1 GB를 내려받으며, 일반적인 네트워크에서 몇 분 정도 걸립니다. 완료되면 CraftBot이 백그라운드에서 실행되고, 브라우저에서 http://localhost:7925를 열며, 데스크톱 바로가기를 만듭니다. 7925 또는 7926 포트가 이미 사용 중이면 CraftBot은 다음 빈 포트를 사용하고 열어야 할 주소를 출력합니다. -**설치 이후 서비스 관리:** +처음 시작할 때 브라우저 온보딩에서 LLM API 키를 입력합니다. CraftBot은 키를 `app/config/settings.json`에 저장하며(나중에 설정에서 변경 가능), `.env` 파일에서 API 키를 읽지 않습니다. + +### CraftBot 관리 + +설치할 때와 같은 `python` 또는 `python3` 명령을 사용합니다. ```bash -python craftbot.py start # CraftBot을 백그라운드에서 실행 +python craftbot.py start # 백그라운드에서 CraftBot 시작 python craftbot.py stop # CraftBot 중지 python craftbot.py restart # CraftBot 재시작 -python craftbot.py status # 실행 여부와 자동 시작 활성화 여부 확인 -python craftbot.py logs # 최근 로그 출력 확인 +python craftbot.py status # 실행 여부와 자동 시작 등록 여부 확인 +python craftbot.py logs # 최근 50줄의 로그 표시(더 보려면 logs -n 200) python craftbot.py uninstall # 중지, 자동 시작 해제, 패키지 제거 +python run.py --cli # 브라우저 대신 터미널에서 실행 ``` +설치 프로그램을 사용하는 경우 설치 프로그램 창에서 같은 작업을 할 수 있습니다(**Start**, **Stop**, **Repair**, **Uninstall**). + > [!TIP] -> `install` 또는 `start` 이후에는 **CraftBot 데스크톱 바로가기**가 자동으로 생성됩니다. 브라우저를 닫았다면 바로가기를 더블 클릭하여 다시 열면 됩니다. +> `install` 또는 `start` 이후에는 **CraftBot 데스크톱 바로가기**가 자동으로 생성됩니다. 브라우저를 닫았다면 바로가기를 더블 클릭하여 다시 열 수 있습니다. --- @@ -149,63 +197,136 @@ CraftBot은 모든 Agent App에 내장되어 있으며 그 **상태를 항상 ## 🔧 문제 해결 및 자주 발생하는 이슈 -### Node.js 누락 (브라우저 모드용) -`python run.py` 실행 시 **"npm not found in PATH"** 오류가 보인다면: -1. [nodejs.org](https://nodejs.org/)에서 다운로드 (LTS 버전 권장) -2. 설치 후 터미널 재시작 -3. 다시 `python run.py` 실행 +**먼저 로그를 확인하세요.** `python craftbot.py logs`는 최근 50줄을 보여 줍니다(더 보려면 `logs -n 200`). `install` 또는 `start`가 실패하면 로그의 마지막 부분을 출력하고 오류로 종료합니다. `python craftbot.py doctor`는 아무것도 변경하지 않고 각 설치 단계를 점검합니다. 설치 프로그램에서는 **Open log**를 클릭합니다. + +**설치는 다시 실행해도 안전합니다.** `python craftbot.py install`은 이미 성공한 단계를 건너뛰고 나머지만 다시 시도합니다. 설치 프로그램에서는 **Repair**를 클릭합니다. + +### 7925 또는 7926 포트가 이미 사용 중일 때 + +CraftBot은 다음 빈 포트로 옮기고 열어야 할 주소를 출력합니다. 포트를 직접 지정하려면 다음과 같이 실행합니다. -**대안:** CLI 모드를 사용하세요 (Node.js 불필요): ```bash -python run.py --cli +python craftbot.py start --frontend-port 8925 --backend-port 8926 ``` -### 의존성 때문에 설치가 실패할 때 -설치 프로그램이 이제 상세한 에러 메시지와 해결 방법을 제공합니다. 설치가 실패한다면: -- **Python 버전 확인:** Python 3.10 이상인지 확인 (`python --version`) -- **인터넷 연결 확인:** 설치 중에 의존성을 다운로드합니다 -- **pip 캐시 정리:** `pip install --upgrade pip` 실행 후 다시 시도 +### 프록시 또는 회사 네트워크 -### Playwright 설치 문제 -Playwright Chromium 설치는 선택 사항입니다. 실패하더라도: -- 다른 작업에서는 에이전트가 **정상적으로 동작**합니다 -- 일단 건너뛰고 나중에 `playwright install chromium`으로 설치할 수 있습니다 -- WhatsApp Web 연동을 사용할 때만 필요합니다 +모든 다운로드(Python, pip, npm, Node.js)는 표준 프록시 환경 변수를 사용합니다. 설치하기 전에 같은 터미널에서 설정하세요. -자세한 트러블슈팅은 [INSTALLATION_FIX.md](INSTALLATION_FIX.md)를 참고하세요. +```bash +# macOS 및 Linux +export HTTPS_PROXY=http://proxy.example.com:8080 +export HTTP_PROXY=http://proxy.example.com:8080 +export NO_PROXY=localhost,127.0.0.1 +python3 craftbot.py install +``` ---- -## 🐳 컨테이너로 실행 +```powershell +# Windows PowerShell +$env:HTTPS_PROXY = "http://proxy.example.com:8080" +$env:HTTP_PROXY = "http://proxy.example.com:8080" +$env:NO_PROXY = "localhost,127.0.0.1" +python craftbot.py install +``` -저장소 루트에는 Python 3.10, 주요 시스템 패키지(OCR을 위한 Tesseract 포함), 그리고 `requirements.txt`에 정의된 모든 Python 의존성을 포함하는 Docker 구성이 들어 있어, 격리된 환경에서도 에이전트를 일관되게 실행할 수 있습니다. +TLS 트래픽을 검사하는 네트워크에서도 추가 설정이 필요 없습니다. CraftBot은 운영 체제 인증서 저장소의 인증서를 신뢰합니다. -다음은 컨테이너로 에이전트를 실행하는 방법입니다. +### 다운로드가 느리거나 막힐 때(예: 중국 본토) -### 이미지 빌드 +설치하기 전에 다운로드 주소를 미러로 지정하세요. -저장소 루트에서 실행: +| 변수 | 용도 | 예시 | +|---|---|---| +| `PIP_INDEX_URL` | Python 패키지 | `https://pypi.tuna.tsinghua.edu.cn/simple` | +| `npm_config_registry` | npm 패키지 | `https://registry.npmmirror.com` | +| `HF_ENDPOINT` | 임베딩 모델 | `https://hf-mirror.com` | +| `CRAFTBOT_MIRRORS` | Python, Node.js, PocketBase, 임베딩 모델 다운로드 | 아래 참고 | + +`CRAFTBOT_MIRRORS`는 `prefix=replacement`(접두사=대체 주소) 형식의 URL 재작성 규칙을 세미콜론으로 구분한 목록입니다. ```bash -docker build -t craftbot . +export CRAFTBOT_MIRRORS="https://github.com/=https:///https://github.com/;https://nodejs.org/dist/=https://npmmirror.com/mirrors/node/" ``` -### 컨테이너 실행 +Python 패키지와 메모리 임베딩 모델은 미러를 거쳐도 고정된 SHA-256 체크섬으로 검증되므로, 미러가 이를 바꿀 수 없습니다. Python과 Node.js 런타임은 체크섬이 고정되어 있지 않으므로, 신뢰할 수 있는 미러만 사용하세요. Windows PowerShell에서는 `export` 대신 `$env:NAME = "value"`로 변수를 설정합니다. + +### 데스크톱이 없는 서버 -이미지는 기본적으로 `python -m app.main`으로 에이전트를 실행하도록 설정되어 있습니다. 인터랙티브하게 실행하려면: +서버에서 브라우저를 열지 않고 소스로 설치합니다. ```bash -docker run --rm -it craftbot +python3 craftbot.py install --no-open-browser ``` -환경 변수를 전달해야 한다면 env 파일을 전달하세요 (예: `.env.example`을 기반으로 작성): +CraftBot은 `localhost`에서만 수신하며, `localhost`로 접속한 브라우저 연결만 받습니다. 내 컴퓨터에서 사용하려면 두 포트를 같은 번호로 전달하는 SSH 터널을 연 다음, 내 컴퓨터에서 http://localhost:7925를 엽니다. ```bash -docker run --rm -it --env-file .env craftbot +ssh -L 7925:localhost:7925 -L 7926:localhost:7926 user@server ``` -컨테이너 바깥에 유지되어야 할 디렉터리(데이터, 캐시 등)는 `-v`로 마운트하고, 포트나 추가 플래그는 배포 환경에 맞춰 조정하세요. 이미지에는 OCR(`tesseract`)에 필요한 시스템 의존성과 흔히 쓰이는 HTTP 클라이언트가 포함되어 있어, 에이전트가 컨테이너 안에서도 파일과 네트워크 API를 다룰 수 있습니다. +`CRAFTBOT_BIND_HOST`를 설정하면 CraftBot이 다른 네트워크 인터페이스에서 수신합니다(Docker 이미지는 `0.0.0.0` 사용). 원격 접속에는 여전히 SSH 터널을 사용하세요. + +### Linux: 재부팅 후 CraftBot이 시작되지 않을 때 + +자동 시작은 systemd 사용자 서비스이므로 systemd 사용자 세션이 필요합니다. 로그인하지 않아도 부팅 시 CraftBot이 시작되고 로그아웃 후에도 계속 실행되게 하려면 다음 명령을 한 번 실행합니다. + +```bash +loginctl enable-linger $USER +``` + +systemd가 없는 환경(예: systemd를 켜지 않은 WSL)에서는 부팅할 때마다 `python3 craftbot.py start`를 실행하세요. + +### macOS: 설치 프로그램이 차단될 때 + +설치 프로그램은 아직 코드 서명이 되어 있지 않습니다. macOS 15 이상에서는 한 번 열기를 시도한 뒤 **시스템 설정 > 개인정보 보호 및 보안**을 열고 **그래도 열기**(Open Anyway)를 클릭합니다. macOS 12부터 14까지는 앱을 마우스 오른쪽 버튼으로 클릭하고 **열기**(Open)를 선택합니다. + +### Windows: SmartScreen이 설치 프로그램을 차단할 때 + +**추가 정보**(More info)를 클릭한 다음 **실행**(Run anyway)을 클릭합니다. 이 경고는 설치 프로그램이 아직 코드 서명되지 않았기 때문에 표시됩니다. + +### Windows: `python`을 입력하면 Microsoft Store가 열릴 때 + +Python이 설치되어 있지 않다는 뜻입니다. 설치 프로그램을 사용하거나, [python.org](https://www.python.org/downloads/)에서 Python을 설치한 뒤 `py craftbot.py install`을 실행하세요. + +### CraftBot 데이터를 다른 위치에 두기 + +설치하기 전에 `CRAFTBOT_HOME`을 폴더로 지정하면 CraftBot의 모든 데이터와 내려받은 런타임이 그 폴더(예: 용량이 큰 드라이브)에 저장됩니다. 자동 시작도 이 설정을 유지합니다. + +### 브라우저 기능(Playwright) + +Mini Browser와 브라우저 자동화는 Playwright의 Chromium을 사용합니다. 이 다운로드가 실패해도 CraftBot의 나머지 기능은 정상적으로 동작합니다. 나중에 `python craftbot.py install`을 다시 실행하면 재시도합니다. + +--- + +## 🐳 컨테이너로 실행 + +Docker 이미지는 필요한 모든 것이 미리 설치된 상태로 CraftBot을 브라우저 모드로 실행합니다. Python 3.10과 고정된 의존성, Node.js 24, 브라우저 UI, PocketBase, Playwright의 Chromium이 포함되어 있습니다. + +저장소 루트에서 다음을 실행합니다. + +```bash +docker compose up -d +``` + +첫 빌드에는 몇 분이 걸립니다. 그다음 http://localhost:7925를 열고 온보딩에서 LLM API 키를 입력합니다. + +설정과 API 키, 에이전트 파일, 메모리, 로그는 `craftbot-data` 볼륨에 저장되므로 컨테이너를 다시 시작하거나 이미지를 다시 빌드해도 유지됩니다. + +```bash +docker compose logs -f craftbot # 로그 실시간 보기 +docker compose ps # 헬스 체크를 포함한 상태 확인 +docker compose down # 중지(데이터 볼륨은 유지됨) +git pull && docker compose up -d --build # 최신 버전으로 업데이트 +``` -이미지는 기본적으로 Python 3.10을 사용하며 `requirements.txt`의 Python 의존성을 함께 패키징해 두었기 때문에, `python -m app.main`이 곧바로 동작합니다. +- CraftBot UI에는 자체 로그인 기능이 없으므로 포트는 `127.0.0.1`에만 공개됩니다. 원격 서버에서도 이 설정을 유지하고, 문제 해결 섹션에서 설명한 SSH 터널로 접속하세요. 호스트 포트는 7925와 7926으로 유지하세요. CraftBot은 이 포트로 `localhost`를 통해 접속한 브라우저 연결만 받습니다. +- 셸 또는 `docker-compose.yml`과 같은 폴더의 `.env` 파일에 설정한 프록시 및 미러 변수(`HTTPS_PROXY`, `PIP_INDEX_URL`, `HF_ENDPOINT`, `CRAFTBOT_MIRRORS`, 그리고 `.env.example`에 나열된 기타 변수)는 컨테이너로 전달됩니다. +- Agent App은 컨테이너 안의 3100~3199 포트에서 실행되며, 아직 호스트 브라우저에서 열 수 없습니다. Agent App을 사용하려면 설치 프로그램이나 소스 설치를 사용하세요. +- Compose 없이 실행하려면: + ```bash + docker build -t craftbot . + docker run -d --name craftbot -p 127.0.0.1:7925:7925 -p 127.0.0.1:7926:7926 --shm-size 1g -v craftbot-data:/data craftbot + ``` --- diff --git a/README.md b/README.md index 8c2b887c7..8f6443ced 100644 --- a/README.md +++ b/README.md @@ -56,33 +56,81 @@ Aside from being an AI agent that can create and operate its own SaaS tools, Cra ## 🧰 Getting Started -Requirements: Python 3.10+ · Node.js 18+ for browser mode +**Requirements** + +- Windows 10 or 11 (x64), macOS 12 or later (Apple Silicon or Intel), or Linux (x86_64 or ARM64) +- At least 5 GB of free disk space +- An API key from an LLM provider such as OpenAI, Anthropic, Google Gemini or OpenRouter, or a local model served by Ollama +- Source install only: Python 3.8 or newer. Node.js is not needed. + +### Option 1: Installer (recommended, no Python or Git needed) + +Download the file for your system from the [latest release](https://github.com/CraftOS-dev/CraftBot/releases/latest): + +| System | File | +|---|---| +| Windows (x64) | `CraftBotInstaller-windows.exe` | +| macOS (Apple Silicon and Intel) | `CraftBotInstaller-macos.zip` | +| Linux (x86_64) | `CraftBotInstaller-linux-x86_64` | +| Linux (ARM64) | `CraftBotInstaller-linux-aarch64` | + +Open it and click **Install CraftBot**. The installer downloads everything CraftBot needs, starts it and opens it in your browser. + +The installers are not code-signed yet, so the first launch needs one extra step: + +- **Windows:** if SmartScreen shows "Windows protected your PC", click **More info**, then **Run anyway**. +- **macOS:** unzip the file and open `CraftBotInstaller.app`. On macOS 15 or later the first attempt is blocked: open **System Settings > Privacy & Security**, click **Open Anyway** next to the message about CraftBotInstaller, and confirm. On macOS 12 to 14, right-click the app and choose **Open**. +- **Linux:** make the file executable and run it from a desktop session (on a server without a desktop, use the source install): + ```bash + chmod +x CraftBotInstaller-linux-x86_64 + ./CraftBotInstaller-linux-x86_64 + ``` + +### Option 2: Install from source + +Any Python 3.8 or newer already on your computer works. CraftBot downloads its own private Python 3.10 and Node.js 24 and never changes the Python or Node.js installed on your system. ```bash -# 1. Clone the repository -git clone https://github.com/CraftOS-dev/CraftBot.git +git clone --depth 1 https://github.com/CraftOS-dev/CraftBot.git cd CraftBot +``` -# 2. Install, register auto-start, and launch CraftBot -python craftbot.py install +Then run the install command for your system: + +```bash +# Windows +python craftbot.py install # or: py craftbot.py install + +# macOS and Linux +python3 craftbot.py install ``` -That's it. The terminal closes itself, CraftBot runs in the background, and the browser opens automatically. A **desktop shortcut** is created so you can reopen the browser anytime. +- **No Git?** On the [repository page](https://github.com/CraftOS-dev/CraftBot), click **Code > Download ZIP**, unzip it, open a terminal in the unzipped folder and run the same command. +- **No Python, or older than 3.8?** Use the installer (Option 1). + +The first install downloads about 1 GB, which takes a few minutes on a typical connection. When it finishes, CraftBot runs in the background, opens http://localhost:7925 in your browser and creates a desktop shortcut. If port 7925 or 7926 is already in use, CraftBot picks the next free ports and prints the address to open. + +On first start, the browser onboarding asks for your LLM API key. CraftBot stores it in `app/config/settings.json` (you can change it later under Settings) and does not read API keys from a `.env` file. -**Managing the service after install:** +### Managing CraftBot + +Use the same `python` or `python3` command as for the install: ```bash python craftbot.py start # Start CraftBot in the background python craftbot.py stop # Stop CraftBot python craftbot.py restart # Restart CraftBot python craftbot.py status # Check if it's running and if auto-start is enabled -python craftbot.py logs # See recent log output +python craftbot.py logs # Show the last 50 log lines (logs -n 200 for more) python craftbot.py autostart disable # Don't launch automatically at future logins python craftbot.py autostart enable # Restore automatic startup at login python craftbot.py autostart status # Check automatic startup registration python craftbot.py uninstall # Stop, remove auto-start, and uninstall packages +python run.py --cli # Run in the terminal instead of the browser ``` +Installer users can do the same from the installer window (**Start**, **Stop**, **Repair**, **Uninstall**). + > [!TIP] > After `install` or `start`, a **CraftBot desktop shortcut** is created automatically. It only opens the browser; it never starts or restarts CraftBot. Automatic startup runs CraftBot in the background when you log in after a restart, without opening a browser. If you disabled startup, run `python craftbot.py start` before using the shortcut. @@ -142,63 +190,136 @@ Build, customize, and evolve your own Agent App, and rely less on subscription t ## 🔧 Troubleshooting & Common Issues -### Missing Node.js (for Browser Mode) -If you see **"npm not found in PATH"** when running `python run.py`: -1. Download from [nodejs.org](https://nodejs.org/) (choose LTS version) -2. Install and restart your terminal -3. Run `python run.py` again +**Start with the log.** `python craftbot.py logs` shows the last 50 lines (`logs -n 200` for more). When `install` or `start` fails, it prints the end of the log and exits with an error. `python craftbot.py doctor` checks every install step without changing anything. In the installer, click **Open log**. + +**Re-running the install is safe.** `python craftbot.py install` skips the steps that already succeeded and retries the rest. In the installer, click **Repair**. + +### Ports 7925 or 7926 are already in use + +CraftBot moves to the next free ports and prints the address to open. To choose the ports yourself: -**Alternative:** Use CLI mode instead (no Node.js needed): ```bash -python run.py --cli +python craftbot.py start --frontend-port 8925 --backend-port 8926 ``` -### Installation Fails with Dependencies -The installer now provides detailed error messages with solutions. If installation fails: -- **Check Python version:** Make sure you have Python 3.10+ (`python --version`) -- **Check internet:** Dependencies are downloaded during installation -- **Clear pip cache:** `pip install --upgrade pip` and try again +### Proxy or corporate network -### Playwright Installation Issues -Playwright chromium installation is optional. If it fails: -- The agent will **still work fine** for other tasks -- You can skip it or install later: `playwright install chromium` -- Only needed for WhatsApp Web integration +Every download (Python, pip, npm, Node.js) uses the standard proxy variables. Set them in the same terminal before you install: -For detailed troubleshooting, see [INSTALLATION_FIX.md](INSTALLATION_FIX.md). +```bash +# macOS and Linux +export HTTPS_PROXY=http://proxy.example.com:8080 +export HTTP_PROXY=http://proxy.example.com:8080 +export NO_PROXY=localhost,127.0.0.1 +python3 craftbot.py install +``` ---- -## 🐳 Run with Container +```powershell +# Windows PowerShell +$env:HTTPS_PROXY = "http://proxy.example.com:8080" +$env:HTTP_PROXY = "http://proxy.example.com:8080" +$env:NO_PROXY = "localhost,127.0.0.1" +python craftbot.py install +``` -The repository root included a Docker configuration with Python 3.10, key system packages (including Tesseract for OCR), and all Python dependencies defined in `requirements.txt` so the agent can run consistently in isolated environments. +Networks that inspect TLS traffic need no extra step: CraftBot trusts the certificates in your operating system's certificate store. -Below are the setup instruction of running our agent with container. +### Slow or blocked downloads (for example in mainland China) -### Build the image +Point the downloads at mirrors before you install: -From the repository root: +| Variable | Used for | Example | +|---|---|---| +| `PIP_INDEX_URL` | Python packages | `https://pypi.tuna.tsinghua.edu.cn/simple` | +| `npm_config_registry` | npm packages | `https://registry.npmmirror.com` | +| `HF_ENDPOINT` | Embedding model | `https://hf-mirror.com` | +| `CRAFTBOT_MIRRORS` | Python, Node.js, PocketBase and embedding model downloads | see below | + +`CRAFTBOT_MIRRORS` is a semicolon-separated list of `prefix=replacement` URL rewrites: ```bash -docker build -t craftbot . +export CRAFTBOT_MIRRORS="https://github.com/=https:///https://github.com/;https://nodejs.org/dist/=https://npmmirror.com/mirrors/node/" ``` -### Run the container +Python packages and the memory embedding model are still checked against pinned SHA-256 checksums, so a mirror cannot change them. The Python and Node.js runtimes are not pinned, so only use a mirror you trust for those. In Windows PowerShell, set variables with `$env:NAME = "value"` instead of `export`. + +### Server without a desktop -The image is configured to launch the agent with `python -m app.main` by default. To run it interactively: +Install from source on the server without opening a browser: ```bash -docker run --rm -it craftbot +python3 craftbot.py install --no-open-browser ``` -If you need to supply environment variables, pass an env file (for example, based on `.env.example`): +CraftBot listens on `localhost` and only accepts browser connections addressed to `localhost`. To use it from your own computer, open an SSH tunnel that forwards both ports with the same numbers, then open http://localhost:7925 on your computer: ```bash -docker run --rm -it --env-file .env craftbot +ssh -L 7925:localhost:7925 -L 7926:localhost:7926 user@server ``` -Mount any directories that should persist outside the container (such as data or cache folders) using `-v`, and adjust ports or additional flags as needed for your deployment. The container ships with system dependencies for OCR (`tesseract`) and common HTTP clients so the agent can work with files and network APIs inside the container. +`CRAFTBOT_BIND_HOST` makes CraftBot listen on another interface (the Docker image uses `0.0.0.0`). For remote access, the SSH tunnel is still the supported way in. + +### Linux: CraftBot does not start after a reboot + +Auto-start is a systemd user service, so it needs a systemd user session. To start CraftBot at boot without logging in, and to keep it running after you log out, enable lingering once: + +```bash +loginctl enable-linger $USER +``` + +Without systemd (for example WSL with systemd disabled), run `python3 craftbot.py start` after each boot. + +### macOS: the installer is blocked + +The installer is not code-signed yet. On macOS 15 or later, try to open it once, then open **System Settings > Privacy & Security** and click **Open Anyway**. On macOS 12 to 14, right-click the app and choose **Open**. + +### Windows: SmartScreen blocks the installer + +Click **More info**, then **Run anyway**. The warning appears because the installer is not code-signed yet. + +### Windows: `python` opens the Microsoft Store + +Python is not installed. Use the installer, or install Python from [python.org](https://www.python.org/downloads/) and run `py craftbot.py install`. + +### Keeping CraftBot's data somewhere else + +Set `CRAFTBOT_HOME` to a folder before you install to keep all CraftBot data and downloaded runtimes there, for example on a larger drive. Auto-start keeps the setting. + +### Browser features (Playwright) + +The Mini Browser and browser automation use Playwright's Chromium. If its download fails, the rest of CraftBot still works. Re-run `python craftbot.py install` later to retry. + +--- + +## 🐳 Run with Container + +The Docker image runs CraftBot in browser mode with everything preinstalled: Python 3.10 with its locked dependencies, Node.js 24, the browser UI, PocketBase and Playwright's Chromium. + +From the repository root: + +```bash +docker compose up -d +``` + +The first build takes several minutes. Then open http://localhost:7925 and enter your LLM API key in the onboarding. + +Settings and API keys, agent files, memory and logs are kept in the `craftbot-data` volume, so they survive restarts and image rebuilds. + +```bash +docker compose logs -f craftbot # Follow the log +docker compose ps # Status, including the health check +docker compose down # Stop (the data volume is kept) +git pull && docker compose up -d --build # Update to the latest version +``` -By default the image uses Python 3.10 and bundles the Python dependencies from `requirements.txt`, so `python -m app.main` works out of the box. +- The ports are published on `127.0.0.1` only, because the CraftBot UI has no login of its own. On a remote server, keep it that way and connect through the SSH tunnel described under Troubleshooting. Keep the host ports at 7925 and 7926: CraftBot only accepts browser connections addressed to `localhost` on those ports. +- Proxy and mirror settings (`HTTPS_PROXY`, `PIP_INDEX_URL`, `HF_ENDPOINT`, `CRAFTBOT_MIRRORS` and the others listed in `.env.example`) are passed into the container when they are set in your shell or in a `.env` file next to `docker-compose.yml`. +- Agent Apps run on ports 3100 to 3199 inside the container and cannot be opened from the host browser yet. To work with Agent Apps, use the installer or the source install. +- Without Compose: + ```bash + docker build -t craftbot . + docker run -d --name craftbot -p 127.0.0.1:7925:7925 -p 127.0.0.1:7926:7926 --shm-size 1g -v craftbot-data:/data craftbot + ``` --- diff --git a/README.pt-BR.md b/README.pt-BR.md index 5c291235e..40f9d40b4 100644 --- a/README.pt-BR.md +++ b/README.pt-BR.md @@ -56,32 +56,80 @@ Além de ser um agente de IA capaz de criar e operar suas próprias ferramentas ## 🧰 Começando -Pré-requisitos: Python 3.10+ · Node.js 18+ para o modo navegador +**Pré-requisitos** + +- Windows 10 ou 11 (x64), macOS 12 ou posterior (Apple Silicon ou Intel), ou Linux (x86_64 ou ARM64) +- Pelo menos 5 GB de espaço livre em disco +- Uma chave de API de um provedor de LLM como OpenAI, Anthropic, Google Gemini ou OpenRouter, ou um modelo local servido pelo Ollama +- Apenas para a instalação pelo código-fonte: Python 3.8 ou posterior. O Node.js não é necessário. + +### Opção 1: Instalador (recomendado, sem Python nem Git) + +Baixe o arquivo do seu sistema na [versão mais recente](https://github.com/CraftOS-dev/CraftBot/releases/latest): + +| Sistema | Arquivo | +|---|---| +| Windows (x64) | `CraftBotInstaller-windows.exe` | +| macOS (Apple Silicon e Intel) | `CraftBotInstaller-macos.zip` | +| Linux (x86_64) | `CraftBotInstaller-linux-x86_64` | +| Linux (ARM64) | `CraftBotInstaller-linux-aarch64` | + +Abra o arquivo e clique em **Install CraftBot**. O instalador baixa tudo de que o CraftBot precisa, inicia o CraftBot e o abre no navegador. + +Os instaladores ainda não têm assinatura de código, então a primeira execução exige um passo extra: + +- **Windows:** se o SmartScreen mostrar "O Windows protegeu o computador", clique em **Mais informações** (More info) e depois em **Executar assim mesmo** (Run anyway). +- **macOS:** descompacte o arquivo e abra `CraftBotInstaller.app`. No macOS 15 ou posterior, a primeira tentativa é bloqueada: abra **Ajustes do Sistema > Privacidade e Segurança**, clique em **Abrir Mesmo Assim** (Open Anyway) ao lado da mensagem sobre o CraftBotInstaller e confirme. No macOS 12 a 14, clique com o botão direito no app e escolha **Abrir** (Open). +- **Linux:** torne o arquivo executável e execute-o a partir de uma sessão de desktop (em um servidor sem desktop, use a instalação pelo código-fonte): + ```bash + chmod +x CraftBotInstaller-linux-x86_64 + ./CraftBotInstaller-linux-x86_64 + ``` + +### Opção 2: Instalar pelo código-fonte + +Qualquer Python 3.8 ou posterior que já esteja no seu computador funciona. O CraftBot baixa seu próprio Python 3.10 e Node.js 24 privados e nunca altera o Python ou o Node.js instalados no seu sistema. ```bash -# 1. Clone o repositório -git clone https://github.com/CraftOS-dev/CraftBot.git +git clone --depth 1 https://github.com/CraftOS-dev/CraftBot.git cd CraftBot +``` -# 2. Instale, registre o autoinício e inicie o CraftBot -python craftbot.py install +Depois execute o comando de instalação do seu sistema: + +```bash +# Windows +python craftbot.py install # ou: py craftbot.py install + +# macOS e Linux +python3 craftbot.py install ``` -Pronto. O terminal se fecha sozinho, o CraftBot roda em segundo plano e o navegador abre automaticamente. Um **atalho na área de trabalho** é criado para que você possa reabrir o navegador quando quiser. +- **Sem Git?** Na [página do repositório](https://github.com/CraftOS-dev/CraftBot), clique em **Code > Download ZIP**, descompacte, abra um terminal na pasta descompactada e execute o mesmo comando. +- **Sem Python, ou com versão anterior à 3.8?** Use o instalador (opção 1). + +A primeira instalação baixa cerca de 1 GB, o que leva alguns minutos em uma conexão comum. Ao terminar, o CraftBot fica rodando em segundo plano, abre http://localhost:7925 no navegador e cria um atalho na área de trabalho. Se a porta 7925 ou 7926 já estiver em uso, o CraftBot escolhe as próximas portas livres e mostra o endereço a abrir. -**Gerenciando o serviço após a instalação:** +Na primeira execução, o onboarding no navegador pede sua chave de API do LLM. O CraftBot a guarda em `app/config/settings.json` (você pode alterá-la depois em Configurações) e não lê chaves de API de um arquivo `.env`. + +### Gerenciando o CraftBot + +Use o mesmo comando `python` ou `python3` da instalação: ```bash python craftbot.py start # Inicia o CraftBot em segundo plano python craftbot.py stop # Para o CraftBot python craftbot.py restart # Reinicia o CraftBot python craftbot.py status # Verifica se está rodando e se o autoinício está ativo -python craftbot.py logs # Exibe a saída recente dos logs -python craftbot.py uninstall # Para o serviço, remove o autoinício e desinstala os pacotes +python craftbot.py logs # Mostra as últimas 50 linhas do log (mais com logs -n 200) +python craftbot.py uninstall # Para, remove o autoinício e desinstala os pacotes +python run.py --cli # Executa no terminal em vez do navegador ``` +Quem usa o instalador pode fazer o mesmo pela janela do instalador (**Start**, **Stop**, **Repair**, **Uninstall**). + > [!TIP] -> Depois de `install` ou `start`, um **atalho do CraftBot na área de trabalho** é criado automaticamente. Se você fechar o navegador, basta dar duplo clique no atalho para abri-lo de novo. +> Depois de `install` ou `start`, um **atalho do CraftBot na área de trabalho** é criado automaticamente. Se você fechar o navegador, dê um duplo clique no atalho para abri-lo de novo. --- @@ -149,63 +197,136 @@ Construa, personalize e evolua sua própria Agent App, e dependa menos de ferram ## 🔧 Solução de problemas e dúvidas comuns -### Falta o Node.js (para o modo navegador) -Se ao rodar `python run.py` você vir **"npm not found in PATH"**: -1. Baixe a versão LTS em [nodejs.org](https://nodejs.org/) -2. Instale e reinicie o terminal -3. Rode `python run.py` novamente +**Comece pelo log.** `python craftbot.py logs` mostra as últimas 50 linhas (mais com `logs -n 200`). Quando `install` ou `start` falha, o comando mostra o final do log e termina com erro. `python craftbot.py doctor` verifica cada etapa da instalação sem alterar nada. No instalador, clique em **Open log**. + +**Executar a instalação de novo é seguro.** `python craftbot.py install` pula as etapas que já deram certo e tenta novamente apenas o restante. No instalador, clique em **Repair**. + +### As portas 7925 ou 7926 já estão em uso + +O CraftBot passa para as próximas portas livres e mostra o endereço a abrir. Para escolher as portas você mesmo: -**Alternativa:** Use o modo CLI (sem necessidade de Node.js): ```bash -python run.py --cli +python craftbot.py start --frontend-port 8925 --backend-port 8926 ``` -### A instalação falha por dependências -O instalador agora exibe mensagens detalhadas com possíveis soluções. Se a instalação falhar: -- **Verifique a versão do Python:** confirme que tem Python 3.10+ (`python --version`) -- **Verifique a internet:** as dependências são baixadas durante a instalação -- **Limpe o cache do pip:** rode `pip install --upgrade pip` e tente novamente +### Proxy ou rede corporativa -### Problemas na instalação do Playwright -A instalação do Chromium do Playwright é opcional. Se falhar: -- O agente **continua funcionando** para outras tarefas -- Você pode pular essa etapa e instalar depois com `playwright install chromium` -- Só é necessário para a integração com o WhatsApp Web +Todos os downloads (Python, pip, npm, Node.js) usam as variáveis de proxy padrão. Defina-as no mesmo terminal antes de instalar: -Para uma solução de problemas mais detalhada, veja [INSTALLATION_FIX.md](INSTALLATION_FIX.md). +```bash +# macOS e Linux +export HTTPS_PROXY=http://proxy.example.com:8080 +export HTTP_PROXY=http://proxy.example.com:8080 +export NO_PROXY=localhost,127.0.0.1 +python3 craftbot.py install +``` ---- -## 🐳 Rodar com container +```powershell +# Windows PowerShell +$env:HTTPS_PROXY = "http://proxy.example.com:8080" +$env:HTTP_PROXY = "http://proxy.example.com:8080" +$env:NO_PROXY = "localhost,127.0.0.1" +python craftbot.py install +``` -A raiz do repositório inclui uma configuração Docker com Python 3.10, pacotes de sistema essenciais (incluindo Tesseract para OCR) e todas as dependências Python definidas em `requirements.txt`, para que o agente rode de forma consistente em ambientes isolados. +Redes que inspecionam o tráfego TLS não exigem nenhum passo extra: o CraftBot confia nos certificados do repositório de certificados do seu sistema operacional. -Abaixo estão as instruções para rodar nosso agente em container. +### Downloads lentos ou bloqueados (por exemplo, na China continental) -### Construir a imagem +Antes de instalar, aponte os downloads para mirrors: -A partir da raiz do repositório: +| Variável | Uso | Exemplo | +|---|---|---| +| `PIP_INDEX_URL` | Pacotes Python | `https://pypi.tuna.tsinghua.edu.cn/simple` | +| `npm_config_registry` | Pacotes npm | `https://registry.npmmirror.com` | +| `HF_ENDPOINT` | Modelo de embeddings | `https://hf-mirror.com` | +| `CRAFTBOT_MIRRORS` | Downloads de Python, Node.js, PocketBase e do modelo de embeddings | veja abaixo | + +`CRAFTBOT_MIRRORS` é uma lista, separada por ponto e vírgula, de reescritas de URL no formato `prefix=replacement` (prefixo=substituição): ```bash -docker build -t craftbot . +export CRAFTBOT_MIRRORS="https://github.com/=https:///https://github.com/;https://nodejs.org/dist/=https://npmmirror.com/mirrors/node/" ``` -### Executar o container +Os pacotes Python e o modelo de embeddings da memória continuam sendo verificados por checksums SHA-256 fixados, então um mirror não consegue alterá-los. Os runtimes de Python e Node.js não são fixados, então use para eles apenas um mirror de confiança. No Windows PowerShell, defina as variáveis com `$env:NAME = "value"` em vez de `export`. + +### Servidor sem desktop -A imagem está configurada para iniciar o agente com `python -m app.main` por padrão. Para rodar de forma interativa: +Instale pelo código-fonte no servidor sem abrir um navegador: ```bash -docker run --rm -it craftbot +python3 craftbot.py install --no-open-browser ``` -Se precisar passar variáveis de ambiente, use um arquivo env (por exemplo, baseado em `.env.example`): +O CraftBot escuta em `localhost` e só aceita conexões do navegador endereçadas a `localhost`. Para usá-lo no seu próprio computador, abra um túnel SSH que encaminhe as duas portas com os mesmos números e depois abra http://localhost:7925 no seu computador: ```bash -docker run --rm -it --env-file .env craftbot +ssh -L 7925:localhost:7925 -L 7926:localhost:7926 user@server ``` -Monte com `-v` os diretórios que precisam persistir fora do container (por exemplo, pastas de dados ou cache) e ajuste portas ou outras flags conforme seu deploy. A imagem traz dependências de sistema para OCR (`tesseract`) e clientes HTTP comuns, para o agente trabalhar com arquivos e APIs de rede dentro do container. +`CRAFTBOT_BIND_HOST` faz o CraftBot escutar em outra interface de rede (a imagem Docker usa `0.0.0.0`). Para acesso remoto, o túnel SSH continua sendo o caminho recomendado. + +### Linux: o CraftBot não inicia depois de reiniciar + +O autoinício é um serviço de usuário do systemd, por isso precisa de uma sessão de usuário do systemd. Para que o CraftBot inicie no boot sem login e continue rodando depois do logout, ative o lingering uma vez: + +```bash +loginctl enable-linger $USER +``` + +Sem systemd (por exemplo, no WSL com o systemd desativado), execute `python3 craftbot.py start` depois de cada boot. + +### macOS: o instalador é bloqueado + +O instalador ainda não tem assinatura de código. No macOS 15 ou posterior, tente abri-lo uma vez, depois abra **Ajustes do Sistema > Privacidade e Segurança** e clique em **Abrir Mesmo Assim** (Open Anyway). No macOS 12 a 14, clique com o botão direito no app e escolha **Abrir** (Open). + +### Windows: o SmartScreen bloqueia o instalador + +Clique em **Mais informações** (More info) e depois em **Executar assim mesmo** (Run anyway). O aviso aparece porque o instalador ainda não tem assinatura de código. + +### Windows: `python` abre a Microsoft Store + +O Python não está instalado. Use o instalador, ou instale o Python pelo [python.org](https://www.python.org/downloads/) e execute `py craftbot.py install`. + +### Guardar os dados do CraftBot em outro lugar + +Antes de instalar, defina `CRAFTBOT_HOME` com uma pasta para guardar ali todos os dados do CraftBot e os runtimes baixados, por exemplo em um disco maior. O autoinício mantém essa configuração. + +### Recursos de navegador (Playwright) + +O Mini Browser e a automação do navegador usam o Chromium do Playwright. Se o download dele falhar, o restante do CraftBot continua funcionando. Execute `python craftbot.py install` de novo mais tarde para tentar outra vez. + +--- + +## 🐳 Rodar com container + +A imagem Docker executa o CraftBot no modo navegador com tudo pré-instalado: Python 3.10 com as dependências fixadas, Node.js 24, a interface do navegador, o PocketBase e o Chromium do Playwright. + +Na raiz do repositório: + +```bash +docker compose up -d +``` + +O primeiro build leva vários minutos. Depois abra http://localhost:7925 e informe sua chave de API do LLM no onboarding. + +Configurações e chaves de API, arquivos do agente, memória e logs ficam no volume `craftbot-data`, então são mantidos entre reinícios e novos builds da imagem. + +```bash +docker compose logs -f craftbot # Acompanha o log +docker compose ps # Status, incluindo o health check +docker compose down # Para (o volume de dados é mantido) +git pull && docker compose up -d --build # Atualiza para a versão mais recente +``` -Por padrão, a imagem usa Python 3.10 e empacota as dependências Python de `requirements.txt`, então `python -m app.main` funciona de cara. +- As portas são publicadas apenas em `127.0.0.1`, porque a interface do CraftBot não tem login próprio. Em um servidor remoto, mantenha assim e conecte-se pelo túnel SSH descrito em Solução de problemas. Mantenha as portas do host em 7925 e 7926: o CraftBot só aceita conexões do navegador endereçadas a `localhost` nessas portas. +- As configurações de proxy e mirrors (`HTTPS_PROXY`, `PIP_INDEX_URL`, `HF_ENDPOINT`, `CRAFTBOT_MIRRORS` e as demais listadas em `.env.example`) são repassadas ao container quando estão definidas no seu shell ou em um arquivo `.env` ao lado do `docker-compose.yml`. +- As Agent Apps rodam nas portas 3100 a 3199 dentro do container e ainda não podem ser abertas pelo navegador do host. Para trabalhar com Agent Apps, use o instalador ou a instalação pelo código-fonte. +- Sem o Compose: + ```bash + docker build -t craftbot . + docker run -d --name craftbot -p 127.0.0.1:7925:7925 -p 127.0.0.1:7926:7926 --shm-size 1g -v craftbot-data:/data craftbot + ``` --- diff --git a/README.zh-TW.md b/README.zh-TW.md index ec5dff2e1..cd8ea3eac 100644 --- a/README.zh-TW.md +++ b/README.zh-TW.md @@ -56,32 +56,80 @@ ## 🧰 快速開始 -環境需求: Python 3.10+ · 瀏覽器模式需要 Node.js 18+ +**環境需求** + +- Windows 10 或 11(x64)、macOS 12 或更新版本(Apple Silicon 或 Intel),或 Linux(x86_64 或 ARM64) +- 至少 5 GB 可用磁碟空間 +- 一組 LLM 服務商的 API 金鑰(例如 OpenAI、Anthropic、Google Gemini 或 OpenRouter),或透過 Ollama 執行的本機模型 +- 僅原始碼安裝需要:Python 3.8 或更新版本。不需要安裝 Node.js。 + +### 方式一:安裝程式(建議,不需要 Python 或 Git) + +從[最新發布頁面](https://github.com/CraftOS-dev/CraftBot/releases/latest)下載適合你系統的檔案: + +| 系統 | 檔案 | +|---|---| +| Windows(x64) | `CraftBotInstaller-windows.exe` | +| macOS(Apple Silicon 與 Intel) | `CraftBotInstaller-macos.zip` | +| Linux(x86_64) | `CraftBotInstaller-linux-x86_64` | +| Linux(ARM64) | `CraftBotInstaller-linux-aarch64` | + +開啟後點選 **Install CraftBot**。安裝程式會下載 CraftBot 需要的所有內容,啟動 CraftBot,並在瀏覽器中開啟。 + +安裝程式目前尚未進行程式碼簽署,因此第一次啟動需要多一個步驟: + +- **Windows:** 如果 SmartScreen 顯示「Windows 已保護您的電腦」,點選 **其他資訊**(More info),再點選 **仍要執行**(Run anyway)。 +- **macOS:** 解壓縮後開啟 `CraftBotInstaller.app`。在 macOS 15 或更新版本上,第一次開啟會被阻擋:開啟 **系統設定 > 隱私權與安全性**,在關於 CraftBotInstaller 的訊息旁點選 **強制打開**(Open Anyway)並確認。在 macOS 12 至 14 上,請在 App 上按右鍵並選擇 **打開**(Open)。 +- **Linux:** 為檔案加上執行權限,然後在桌面工作階段中執行(沒有桌面環境的伺服器請使用原始碼安裝): + ```bash + chmod +x CraftBotInstaller-linux-x86_64 + ./CraftBotInstaller-linux-x86_64 + ``` + +### 方式二:從原始碼安裝 + +電腦上已有的任何 Python 3.8 或更新版本都可以。CraftBot 會下載自己專用的 Python 3.10 與 Node.js 24,不會更動系統中已安裝的 Python 或 Node.js。 ```bash -# 1. 複製儲存庫 -git clone https://github.com/CraftOS-dev/CraftBot.git +git clone --depth 1 https://github.com/CraftOS-dev/CraftBot.git cd CraftBot +``` -# 2. 安裝、註冊自動啟動並執行 CraftBot -python craftbot.py install +接著執行對應系統的安裝指令: + +```bash +# Windows +python craftbot.py install # 或:py craftbot.py install + +# macOS 與 Linux +python3 craftbot.py install ``` -就這麼簡單。終端機會自動關閉,CraftBot 會在背景執行,瀏覽器也會自動開啟。同時還會建立一個**桌面捷徑**,方便你隨時重新打開瀏覽器。 +- **沒有 Git?** 在[儲存庫頁面](https://github.com/CraftOS-dev/CraftBot)點選 **Code > Download ZIP**,解壓縮後在該資料夾開啟終端機,執行相同的指令。 +- **沒有 Python,或版本低於 3.8?** 請使用安裝程式(方式一)。 + +第一次安裝約需下載 1 GB,在一般網路環境下需要幾分鐘。完成後,CraftBot 會在背景執行,在瀏覽器開啟 http://localhost:7925,並建立桌面捷徑。如果 7925 或 7926 連接埠已被占用,CraftBot 會改用下一個可用的連接埠,並顯示要開啟的網址。 -**安裝完成後管理服務:** +第一次啟動時,瀏覽器中的引導流程會請你輸入 LLM API 金鑰。CraftBot 會將金鑰儲存在 `app/config/settings.json`(之後可在設定中修改),不會從 `.env` 檔案讀取 API 金鑰。 + +### 管理 CraftBot + +使用與安裝時相同的 `python` 或 `python3` 指令: ```bash python craftbot.py start # 在背景啟動 CraftBot python craftbot.py stop # 停止 CraftBot -python craftbot.py restart # 重啟 CraftBot +python craftbot.py restart # 重新啟動 CraftBot python craftbot.py status # 查看執行狀態以及是否已啟用自動啟動 -python craftbot.py logs # 查看最近的日誌輸出 -python craftbot.py uninstall # 停止執行、移除自動啟動並解除安裝相依套件 +python craftbot.py logs # 顯示最近 50 行記錄(更多:logs -n 200) +python craftbot.py uninstall # 停止執行、移除自動啟動並解除安裝套件 +python run.py --cli # 在終端機中執行,而不是在瀏覽器中 ``` +使用安裝程式的使用者可以在安裝程式視窗中完成相同的操作(**Start**、**Stop**、**Repair**、**Uninstall**)。 + > [!TIP] -> 執行 `install` 或 `start` 之後,系統會自動建立 **CraftBot 桌面捷徑**。如果關閉了瀏覽器,雙擊捷徑即可重新打開。 +> 執行 `install` 或 `start` 之後,系統會自動建立 **CraftBot 桌面捷徑**。如果關閉了瀏覽器,雙擊捷徑即可重新開啟。 --- @@ -149,63 +197,136 @@ CraftBot 嵌入在每一個 Agent App 中,並且**對其狀態保持感知**: ## 🔧 疑難排解與常見問題 -### 缺少 Node.js (瀏覽器模式) -如果執行 `python run.py` 時看到 **「npm not found in PATH」**: -1. 從 [nodejs.org](https://nodejs.org/) 下載(選擇 LTS 版本) -2. 安裝完成後重啟終端機 -3. 再次執行 `python run.py` +**先查看記錄。** `python craftbot.py logs` 會顯示最近 50 行記錄(更多:`logs -n 200`)。`install` 或 `start` 失敗時,會顯示記錄的最後幾行並以錯誤狀態結束。`python craftbot.py doctor` 會逐一檢查每個安裝步驟,不做任何變更。在安裝程式中可點選 **Open log**。 + +**重新執行安裝是安全的。** `python craftbot.py install` 會略過已經成功的步驟,只重試其餘步驟。在安裝程式中可點選 **Repair**。 + +### 7925 或 7926 連接埠已被占用 + +CraftBot 會改用下一個可用的連接埠,並顯示要開啟的網址。若要自行指定連接埠: -**替代方案:** 改用 CLI 模式(不需 Node.js): ```bash -python run.py --cli +python craftbot.py start --frontend-port 8925 --backend-port 8926 ``` -### 安裝時相依套件失敗 -安裝程式現在會提供更詳細的錯誤訊息與解決方法。若安裝失敗: -- **檢查 Python 版本:** 確認已安裝 Python 3.10 以上(`python --version`) -- **檢查網路連線:** 安裝過程需要下載相依套件 -- **清除 pip 快取:** 執行 `pip install --upgrade pip` 之後再試一次 +### Proxy 或公司網路 -### Playwright 安裝問題 -Playwright Chromium 的安裝為選用項目。即使失敗: -- Agent 在其他任務上**仍可正常運作** -- 可以先略過,稍後再用 `playwright install chromium` 安裝 -- 只有在使用 WhatsApp Web 整合時才需要 +所有下載(Python、pip、npm、Node.js)都會使用標準的 Proxy 環境變數。請在安裝前於同一個終端機中設定: -更完整的排解請參考 [INSTALLATION_FIX.md](INSTALLATION_FIX.md)。 +```bash +# macOS 與 Linux +export HTTPS_PROXY=http://proxy.example.com:8080 +export HTTP_PROXY=http://proxy.example.com:8080 +export NO_PROXY=localhost,127.0.0.1 +python3 craftbot.py install +``` ---- -## 🐳 使用容器執行 +```powershell +# Windows PowerShell +$env:HTTPS_PROXY = "http://proxy.example.com:8080" +$env:HTTP_PROXY = "http://proxy.example.com:8080" +$env:NO_PROXY = "localhost,127.0.0.1" +python craftbot.py install +``` -儲存庫根目錄包含一份 Docker 設定,內含 Python 3.10、關鍵系統套件(含用於 OCR 的 Tesseract),以及 `requirements.txt` 中定義的所有 Python 相依套件,讓 Agent 在隔離環境中也能穩定運作。 +會檢查 TLS 流量的網路不需要額外設定:CraftBot 會信任作業系統憑證存放區中的憑證。 -以下是使用容器執行 Agent 的步驟。 +### 下載緩慢或無法連線(例如在中國大陸) -### 建立映像檔 +安裝前將下載來源指向鏡像站: -從儲存庫根目錄執行: +| 變數 | 用途 | 範例 | +|---|---|---| +| `PIP_INDEX_URL` | Python 套件 | `https://pypi.tuna.tsinghua.edu.cn/simple` | +| `npm_config_registry` | npm 套件 | `https://registry.npmmirror.com` | +| `HF_ENDPOINT` | 嵌入模型 | `https://hf-mirror.com` | +| `CRAFTBOT_MIRRORS` | Python、Node.js、PocketBase 與嵌入模型的下載 | 見下方 | + +`CRAFTBOT_MIRRORS` 是以分號分隔的 `prefix=replacement`(前綴=替換網址)URL 改寫規則: ```bash -docker build -t craftbot . +export CRAFTBOT_MIRRORS="https://github.com/=https:///https://github.com/;https://nodejs.org/dist/=https://npmmirror.com/mirrors/node/" ``` -### 執行容器 +Python 套件和記憶嵌入模型仍會以固定的 SHA-256 檢查碼驗證,因此鏡像站無法改變它們。Python 和 Node.js 執行環境沒有固定檢查碼,請只為它們使用你信任的鏡像站。在 Windows PowerShell 中,請用 `$env:NAME = "value"` 取代 `export` 來設定變數。 + +### 沒有桌面環境的伺服器 -映像檔預設會以 `python -m app.main` 啟動 Agent。如要互動式執行: +在伺服器上從原始碼安裝,且不開啟瀏覽器: ```bash -docker run --rm -it craftbot +python3 craftbot.py install --no-open-browser ``` -需要傳入環境變數時,可以指定一個 env 檔案(例如以 `.env.example` 為基礎): +CraftBot 只監聽 `localhost`,並且只接受以 `localhost` 連線的瀏覽器。若要從自己的電腦使用,請建立以相同連接埠號碼轉送兩個連接埠的 SSH 通道,然後在自己的電腦上開啟 http://localhost:7925: ```bash -docker run --rm -it --env-file .env craftbot +ssh -L 7925:localhost:7925 -L 7926:localhost:7926 user@server ``` -透過 `-v` 掛載需要持久化到容器外的目錄(例如資料或快取資料夾),並依部署需求調整 port 或其他參數。映像檔內建了 OCR(`tesseract`)所需的系統套件以及常見的 HTTP 客戶端,讓 Agent 可以直接在容器中處理檔案和網路 API。 +`CRAFTBOT_BIND_HOST` 可讓 CraftBot 監聽其他網路介面(Docker 映像檔使用 `0.0.0.0`)。遠端存取仍應透過 SSH 通道進行。 + +### Linux:重新開機後 CraftBot 沒有自動啟動 + +自動啟動是一個 systemd 使用者服務,因此需要 systemd 使用者工作階段。若要在開機時不需登入即可啟動 CraftBot,並在登出後繼續執行,請執行一次: + +```bash +loginctl enable-linger $USER +``` + +在沒有 systemd 的環境中(例如未啟用 systemd 的 WSL),請在每次開機後執行 `python3 craftbot.py start`。 + +### macOS:安裝程式被阻擋 + +安裝程式尚未進行程式碼簽署。在 macOS 15 或更新版本上,先嘗試開啟一次,然後開啟 **系統設定 > 隱私權與安全性** 並點選 **強制打開**(Open Anyway)。在 macOS 12 至 14 上,請在 App 上按右鍵並選擇 **打開**(Open)。 + +### Windows:SmartScreen 阻擋安裝程式 + +點選 **其他資訊**(More info),再點選 **仍要執行**(Run anyway)。出現這個警告是因為安裝程式尚未進行程式碼簽署。 + +### Windows:輸入 `python` 卻開啟了 Microsoft Store + +表示系統中沒有安裝 Python。請使用安裝程式,或從 [python.org](https://www.python.org/downloads/) 安裝 Python 後執行 `py craftbot.py install`。 + +### 將 CraftBot 的資料存放在其他位置 + +安裝前將 `CRAFTBOT_HOME` 設為某個資料夾(例如容量較大的磁碟上的資料夾),CraftBot 的所有資料與下載的執行環境都會存放在那裡。自動啟動會保留這項設定。 + +### 瀏覽器功能(Playwright) + +Mini Browser 與瀏覽器自動化使用 Playwright 的 Chromium。即使它下載失敗,CraftBot 的其他功能仍可正常使用。之後重新執行 `python craftbot.py install` 即可重試。 + +--- + +## 🐳 使用容器執行 + +Docker 映像檔以瀏覽器模式執行 CraftBot,所需元件皆已預先安裝:Python 3.10 及其鎖定的相依套件、Node.js 24、瀏覽器介面、PocketBase 與 Playwright 的 Chromium。 + +在儲存庫根目錄執行: + +```bash +docker compose up -d +``` + +第一次建置需要幾分鐘。完成後開啟 http://localhost:7925,並在引導流程中輸入你的 LLM API 金鑰。 + +設定與 API 金鑰、Agent 檔案、記憶與記錄都保存在 `craftbot-data` 磁碟區中,重新啟動容器或重新建置映像檔後依然保留。 + +```bash +docker compose logs -f craftbot # 即時查看記錄 +docker compose ps # 查看狀態(含健康檢查) +docker compose down # 停止(資料磁碟區會保留) +git pull && docker compose up -d --build # 更新到最新版本 +``` -映像檔預設使用 Python 3.10,並打包好 `requirements.txt` 中的相依套件,所以 `python -m app.main` 可以直接運作。 +- 連接埠只發布在 `127.0.0.1` 上,因為 CraftBot 介面本身沒有登入機制。在遠端伺服器上請維持這個設定,並透過「疑難排解」中說明的 SSH 通道連線。主機連接埠請維持 7925 與 7926:CraftBot 只接受以 `localhost` 連線到這兩個連接埠的瀏覽器。 +- 在 shell 或 `docker-compose.yml` 同一資料夾的 `.env` 檔案中設定的 Proxy 與鏡像變數(`HTTPS_PROXY`、`PIP_INDEX_URL`、`HF_ENDPOINT`、`CRAFTBOT_MIRRORS`,以及 `.env.example` 中列出的其他變數)會傳入容器。 +- Agent App 在容器內的 3100 至 3199 連接埠執行,目前還無法從主機的瀏覽器開啟。若要使用 Agent App,請使用安裝程式或原始碼安裝。 +- 不使用 Compose 時: + ```bash + docker build -t craftbot . + docker run -d --name craftbot -p 127.0.0.1:7925:7925 -p 127.0.0.1:7926:7926 --shm-size 1g -v craftbot-data:/data craftbot + ``` --- diff --git a/agent-app/tools/src/commands/pb.ts b/agent-app/tools/src/commands/pb.ts index c45579751..52ff4c1bb 100644 --- a/agent-app/tools/src/commands/pb.ts +++ b/agent-app/tools/src/commands/pb.ts @@ -18,6 +18,22 @@ import { pinnedPbVersion } from '../lib/paths.ts'; const RELEASE_BASE = 'https://github.com/pocketbase/pocketbase/releases/download'; +/** + * The URL to fetch after the user's CRAFTBOT_MIRRORS rewrites + * (";"-separated "prefix=replacement" pairs, first match wins), the same + * setting app/downloads.py applies to the Python, Node and model downloads. + */ +export function mirrorUrl(url: string, rules = process.env.CRAFTBOT_MIRRORS ?? ''): string { + for (const pair of rules.split(';')) { + const at = pair.indexOf('='); + if (at <= 0) continue; + const prefix = pair.slice(0, at).trim(); + const replacement = pair.slice(at + 1).trim(); + if (prefix && replacement && url.startsWith(prefix)) return replacement + url.slice(prefix.length); + } + return url; +} + export async function ensurePbBinary(): Promise { const version = pinnedPbVersion(); const cacheDir = osAdapter.pbCacheDir(version); @@ -30,7 +46,7 @@ export async function ensurePbBinary(): Promise { const zipPath = join(cacheDir, asset); log.step(`Downloading PocketBase v${version} (${asset})…`); - const res = await fetch(url, { redirect: 'follow' }); + const res = await fetch(mirrorUrl(url), { redirect: 'follow' }); if (!res.ok || res.body === null) { throw new Error(`Download failed (${res.status}) — ${url}`); } diff --git a/agent_core/core/impl/memory/manager.py b/agent_core/core/impl/memory/manager.py index 38c572c75..6ae64ebd9 100644 --- a/agent_core/core/impl/memory/manager.py +++ b/agent_core/core/impl/memory/manager.py @@ -108,10 +108,9 @@ def _is_embedding_function_conflict(err: Exception) -> bool: # matches, ~0.75 on topical, and drops below 0.50 for unrelated content. # That's the dynamic range hybrid scoring actually needs. # -# Override via the MEMORY_EMBEDDING_MODEL env var if you want to try -# bge-base-en-v1.5 (better, slower), e5-small-v2, or any other -# sentence-transformers model. Set to "default" to use ChromaDB's -# bundled ONNX MiniLM. +# It runs on ONNX Runtime (onnx_embedder.py), from model files provisioned at +# install time. Set MEMORY_EMBEDDING_MODEL=default to use ChromaDB's own +# MiniLM instead; no other model is supported. MEMORY_EMBEDDING_MODEL = _os.environ.get( "MEMORY_EMBEDDING_MODEL", "BAAI/bge-small-en-v1.5" ) @@ -274,7 +273,7 @@ def __init__( # Build the embedding function. Default ChromaDB uses MiniLM-L6-v2 # (weak — ~0.65 verbatim self-similarity). MEMORY_EMBEDDING_MODEL - # points to a stronger sentence-transformers model by default; if it + # points to a stronger model (bge-small on ONNX Runtime); if it # can't load, construction fails — retrieval thresholds are calibrated # for the configured model, so running with a substitute is worse than # not starting. @@ -338,7 +337,8 @@ def _open_collection(self, name: str, embedding_fn, metadata: Dict[str, Any]): ChromaDB persists the embedding-function name in the collection config and refuses get_or_create with a different one — happens when the - collection was first created without sentence-transformers loadable + collection was first created with a different embedder (the old + sentence-transformers one, or ChromaDB's default) and is reopened later with a real model. The index is a derived cache (source of truth is the markdown files), so dropping and rebuilding is safe; update() repopulates from disk on next call. @@ -374,38 +374,33 @@ def _build_embedding_function(): """ if MEMORY_EMBEDDING_MODEL == "default": return None # ChromaDB applies its bundled default - try: - from chromadb.utils.embedding_functions import ( - SentenceTransformerEmbeddingFunction, - ) - except ImportError as e: + if MEMORY_EMBEDDING_MODEL != "BAAI/bge-small-en-v1.5": raise RuntimeError( - "[MEMORY] sentence-transformers is required for the configured " - f"embedding model '{MEMORY_EMBEDDING_MODEL}'. Install with: " - "conda install -c conda-forge sentence-transformers" - ) from e + f"[MEMORY] MEMORY_EMBEDDING_MODEL={MEMORY_EMBEDDING_MODEL!r} is not " + "supported. Use the built-in BAAI/bge-small-en-v1.5 (unset the " + "variable) or 'default' for ChromaDB's MiniLM." + ) try: - return SentenceTransformerEmbeddingFunction( - model_name=MEMORY_EMBEDDING_MODEL + from agent_core.core.impl.memory.onnx_embedder import ( + OnnxBgeSmallEmbeddingFunction, ) + + return OnnxBgeSmallEmbeddingFunction() except (OSError, ImportError) as e: - # The constructor imports sentence-transformers → transformers → - # torch; a native-DLL failure (Windows without the VC++ - # Redistributable: WinError 126 on torch_python.dll; Linux - # without libgomp) lands here as a 40-line torch traceback. - # Still fatal by design (thresholds are calibrated to this - # model) — but say what to do. + # onnxruntime and chromadb's native module link the Visual C++ + # runtime on Windows; without it the import dies with a bare + # "DLL load failed". Fatal by design (thresholds are calibrated + # to this model), but say what to do. fix = ( "install the Visual C++ Redistributable " "(https://aka.ms/vs/17/release/vc_redist.x64.exe)" if sys.platform == "win32" - else "install libgomp1/libstdc++6 (apt-get install -y libgomp1 libstdc++6)" + else "run `python craftbot.py install` again (or Repair in the installer)" ) raise RuntimeError( - f"[MEMORY] The embedding stack for '{MEMORY_EMBEDDING_MODEL}' is " - f"installed but cannot load: {e}. Usual fix: {fix}, or re-run " - "`python install.py` (it checks this). Escape hatch: " + f"[MEMORY] The embedding model '{MEMORY_EMBEDDING_MODEL}' cannot " + f"load: {e}. Usual fix: {fix}. Escape hatch: " "MEMORY_EMBEDDING_MODEL=default (lower retrieval quality)." ) from e diff --git a/agent_core/core/impl/memory/onnx_embedder.py b/agent_core/core/impl/memory/onnx_embedder.py new file mode 100644 index 000000000..7c6f654d2 --- /dev/null +++ b/agent_core/core/impl/memory/onnx_embedder.py @@ -0,0 +1,99 @@ +"""BAAI/bge-small-en-v1.5 on ONNX Runtime: the memory embedder. + +The same model the memory system was calibrated on (every retrieval threshold +in tuning.py assumes its score range), run without torch. bge-small's +sentence-transformers config is CLS pooling followed by L2 normalisation +(1_Pooling/config.json: pooling_mode_cls_token), which is exactly what +__call__ does, so the vectors match the old sentence-transformers ones to +float tolerance. + +Why not sentence-transformers: it pulled in torch, which was 0.5 GB on +Windows/macOS and 2.6 GB of CUDA libraries on Linux, needed the Visual C++ +runtime to import, and has no Intel-Mac wheels at all. onnxruntime and +tokenizers were already dependencies (chromadb's own). +""" + +from __future__ import annotations + +from pathlib import Path +from typing import Any, Dict, List + +import numpy as np +from chromadb.api.types import Documents, EmbeddingFunction, Embeddings +from chromadb.utils.embedding_functions import register_embedding_function + +MODEL_ID = "BAAI/bge-small-en-v1.5" +MAX_TOKENS = 512 +BATCH_SIZE = 32 + + +def _model_dir() -> Path: + from app import embedding_model + + return embedding_model.ensure() + + +@register_embedding_function +class OnnxBgeSmallEmbeddingFunction(EmbeddingFunction[Documents]): + """ChromaDB embedding function backed by the provisioned ONNX model.""" + + def __init__(self) -> None: + import onnxruntime as ort + from tokenizers import Tokenizer + + directory = _model_dir() + self._tokenizer = Tokenizer.from_file(str(directory / "tokenizer.json")) + self._tokenizer.enable_truncation(max_length=MAX_TOKENS) + self._tokenizer.enable_padding(pad_id=0, pad_token="[PAD]") + options = ort.SessionOptions() + options.log_severity_level = 3 # errors only + self._session = ort.InferenceSession( + str(directory / "model.onnx"), + sess_options=options, + providers=["CPUExecutionProvider"], + ) + self._input_names = {i.name for i in self._session.get_inputs()} + + def __call__(self, input: Documents) -> Embeddings: # noqa: A002 (chroma's name) + vectors: List[np.ndarray] = [] + for start in range(0, len(input), BATCH_SIZE): + vectors.extend(self._embed(list(input[start : start + BATCH_SIZE]))) + return vectors + + def _embed(self, texts: List[str]) -> List[np.ndarray]: + encoded = self._tokenizer.encode_batch(texts) + feeds = { + "input_ids": np.array([e.ids for e in encoded], dtype=np.int64), + "attention_mask": np.array( + [e.attention_mask for e in encoded], dtype=np.int64 + ), + "token_type_ids": np.array([e.type_ids for e in encoded], dtype=np.int64), + } + feeds = {k: v for k, v in feeds.items() if k in self._input_names} + hidden = self._session.run(None, feeds)[0] # (batch, seq, 384) + cls = hidden[:, 0, :] + norms = np.linalg.norm(cls, axis=1, keepdims=True) + cls = cls / np.clip(norms, 1e-12, None) + return [row.astype(np.float32) for row in cls] + + @staticmethod + def name() -> str: + return "craftbot_onnx_bge_small" + + def get_config(self) -> Dict[str, Any]: + # The model location is resolved at build time, not stored: moving + # CRAFTBOT_HOME must not strand a collection's config. + return {"model": MODEL_ID} + + @staticmethod + def build_from_config(config: Dict[str, Any]) -> "OnnxBgeSmallEmbeddingFunction": + return OnnxBgeSmallEmbeddingFunction() + + def default_space(self) -> str: + return "cosine" + + def supported_spaces(self) -> List[str]: + return ["cosine", "l2", "ip"] + + def is_legacy(self) -> bool: + return False diff --git a/agent_file_system/ENTITIES.md b/agent_file_system/ENTITIES.md deleted file mode 100644 index 5bf7cb9e4..000000000 --- a/agent_file_system/ENTITIES.md +++ /dev/null @@ -1,713 +0,0 @@ -# Entity Registry - -Agent DO NOT edit this file. It is maintained by the system. - -## Overview - -Entities the agent knows about, and the connection records between memories and entities. -Under ## Entities: one entity name per line — the graph's entire entity set, created by the system's entity-judge pipeline. -Under ## Connections: one system-written record line per memory: [chunk-id] [pending|judged] names :: text preview. Name marks: plain = confirmed, ! = rejected, ? = awaiting the entity judge's decision. - -## Entities -list_action_sets -add_action_sets -user-profile-interview -MCPClient -mcp_config.json -mcp_client.reload -.credentials/.accounts.json -GitHub -PAT -AGENT.md -PROACTIVE.md -MEMORY.md -USER.md -EVENT_UNPROCESSED.md -skills_config.json -BBC Weather -Playwright -craftbot-skill-creator -craftbot-skill-improve -predict-stock-next-week -docx -pptx -xlsx -pdf -file-format -playwright-mcp -agent-app-creator -agent-app-modify -agent-app-manager -Agent App -compile-report-advance -agent_file_system/ENTITIES.md -memory_search -scheduler_config.json -recurring_add -recurring_read -schedule_task -scheduled_task_list -recurring_update_task -recurring_remove -schedule_task_toggle -remove_scheduled_task -CUSTOM_ACTION_GUIDE.md -read_file.py -craftos_integrations -integrations.py -check_integration_status -craftos_integrations/providers//INTEGRATION.md -openai -anthropic -Gemini -Sakana (Fugu) -SkillLoader.substitute_variables -INDEX_TARGET_FILES -MemoryManager -ChromaDB -chroma_db_memory/ -/help -/menu -/clear -/cls -/reset -/exit -/update -/upgrade -/tokens -/provider -CraftBot -ChatGPT -Codex -gpt-5.5 -gpt-5.4 -gpt-5.4-mini -gpt-5.3-codex-spark -openai_chatgpt_oauth.json -embedded_credentials.py -Slack -Notion -HubSpot -Outlook -Twitter -Atlassian -Telegram -Discord -LinkedIn -Jira -WhatsApp -Stripe -LINE -Lark -Gmail -Google Calendar -Google Drive -Google Docs -Google YouTube -agent_command.py -DEFAULT_SET_DESCRIPTIONS -web_research -document_processing -run_shell -http_request -send_message -send_message_with_attachment -end_turn -update_todos -set_requirement -spawn_subagent -grep_files -find_files -list_folder -stream_edit -write_file -web_search -web_fetch -describe_image -convert_to_pdf -convert_from_pdf -edit_pdf -read_pdf -convert_to_markdown -generate_image -generate_video -perform_ocr -ProactiveManager -manager.py -parser.py -types.py -PocketBase -A2App -agent-app -ActionSetManager -app/config/settings.json -app/ui_layer/commands/builtin/ -test_provider_connection -LLMConsecutiveFailureError -PROVIDER_CONFIG -provider_config.py -MODEL_REGISTRY -model_registry.py -LLMInterface -ModelFactory -reinitialize_llm -connection_test_models.json -app/config/connection_test_models.json -agent.reinitialize_llm -SkillMetadata -Skill -SkillsConfig -agent-app-importer -craftbot.json -agent-app/blueprint/ -MISSION_INDEX_TEMPLATE.md -FORMAT.md -GLOBAL_AGENT_APP.md -AGENT_APP.md -DEFAULT_ACTION_TIMEOUT -Loguru -ActionLibrary -ActionManager -ActionRouter -ActionExecutor -SessionManager -SessionRuntimeManager -TriggerService -TriggerStore -ContextEngine -Memory settings panel -BytePlus -OpenRouter -Ollama -Moonshot -Minimax -heartbeat-processor -AgentBase.react(trigger) -AgentBase -app/agent_base.py -session -run-start trigger -run -continue_work -IDENTIFY/SEARCH/INSTALL/WAIT/CONTINUE/REMEMBER -RECOGNIZE -CATEGORIZE -VALIDATE -SOUL.md -day-planner -week-planner -month-planner -skills/day-planner/SKILL.md -skills/week-planner/SKILL.md -skills/month-planner/SKILL.md -skills/heartbeat-processor/SKILL.md -EVENT.md -planner-maintained section -app/triggers/store.py -agent_core/core/impl/trigger/session_queue.py -fire_at -TriggerSource -app/triggers/sources.py -USER_MESSAGE -RUN_CONTINUATION -/skill enable -/skill disable -enabled_skills -disabled_skills -PROACTIVE_HEARTBEAT -proactive_manager.get_all_due_tasks() -file_operations -proactive -agent_app_approve_triggers -triggers.json -agent_app_convert -reference/source/ -operations.json -GLOBAL_AGENT_APP -ConfigWatcher -connect_integration -Models auth_type -Decision Rubric -claude-sonnet-4-6 -EventStreamManager -workspace/sessions// -memory.processing_threshold -diagnostic/README.md -diagnostic/logs/actions/ -logs//all.log -logs///.log -app/data/action/.py -classify_llm_error() -AUTH -CREDIT -MODEL -CONFIG -BLOCKED -settings.json -watchdog -run_coroutine_threadsafe -/mcp env -.accounts.json.corrupt -workspace/missions//INDEX.md -search_agent -research_agent -walk_verify -sub_task_end -agent_type -onboarding_config.json -/whatsapp login -telegram_bot -telegram_user -PROVIDER_INFO -model_settings.py -agent_core/core/impl/config/watcher.py -slow_mode -slow_mode_tpm_limit -LLMInterface._max_consecutive_failures -understand_video -app/triggers/runtime.py -agent_app_list_projects -agent_app_usage -TASK_HISTORY.md -memory-processing -memory-processor -event_stream_manager.set_skip_unprocessed_logging(True) -create_skill_scaffold -list_skills -use_skill -unload_skill -app/config/onboarding_config.json -reinitialize_image_gen -reinitialize_video_gen -settings_manager.reload -invalidate_settings_cache -app/data/action/memory_search.py -retrieve_full_content -stripe-mcp -app/action/action_set.py -clipboard_read -clipboard_write -@BotFather -Meta Cloud API -Meta Business -app/data/action/action_set_management.py -app/data/action/skill_management.py -list_available_integrations -disconnect_integration -app/data/action/integrations/integration_management.py -agent_app_scaffold -agentapp_ -agent_app_notify_ready -agent_app_http -app/scheduler/parser.py -app/proactive/parser.py -app/proactive/manager.py -agent_core/core/action_framework/registry.py -gpt-5.2 -deepseek -grok -qwen -mistral -shadcn -GeminiCacheManager -BytePlusCacheManager -bedrock -aws_credentials -endpoints.remote -endpoints.aws_region -glm -Gemini provider -google -MemoryFileWatcher -agent_core/core/impl/memory/memory_file_watcher.py -agent_core/core/impl/llm/interface.py -agent_core/core/impl/llm/errors.py -agent_core/core/impl/event_stream/manager.py -app/data/action/agent_app_actions.py -reference/requirements.md -manifest.json -pb_hooks -pb/pb_data/data.db -sync_skill_commands -Baileys -agent-app CLI -manage_integration_account -settings.oauth.slack -api_keys.google -api_keys_configured -VLM -MSG_AUTH -StdioTransport -github_issues -FRONTMATTER_PATTERN -Tan Wei Yang - -## Connections - -[c012546fdc09b] [judged] add_action_sets, list_action_sets :: Two ways to know what is currently active: 1. The current prompt's action list (always authoritative). 2. The `list_action_sets` action returns `{ available_... -[c013946fb2e70] [judged] user-profile-interview, !Skill :: The soft phase uses the `user-profile-interview` skill (see [skills/user-profile-interview/SKILL.md](skills/user-profile-interview/SKILL.md)). -[c03d43f74df08] [judged] !AUTH :: 23 integrations. Each has an `auth_type` that determines how connection happens: -[c0418a9d6c32f] [judged] mcp_config.json, MCPClient, !add_action_sets, !CONFIG, !mcp_client.reload :: `MCPClient.reload(config_path)` does the following on each `mcp_config.json` save: ``` 1. re-parse mcp_config.json 2. for each currently-connected server: if... -[c045e30d78756] [judged] .credentials/.accounts.json, !/tokens, !GitHub, !MEMORY.md, !PAT, !USER.md :: - ALWAYS tell the user what credentials you need and where to get them. Never paste a vague "give me your token". - ALWAYS confirm the credential format roug... -[c0482bddd00a4] [judged] AGENT.md, PROACTIVE.md, !CONFIG, !proactive, !Skill :: You are a self-improving agent. The harness exposes a set of mutable surfaces — config files, skill directories, action registry, memory, your own operationa... -[c04f7a276ab0a] [judged] FORMAT.md, !grep_files, !pdf, !pptx :: ``` 1. grep_files "## " agent_file_system/FORMAT.md -A 50 Read the file-type section in full. 2. grep_files "## global" agent_file_system/FORMAT.md... -[c0512e23357dc] [pending] Agent App, agent-app-creator, agent-app-manager, agent-app-modify, BBC Weather, compile-report-advance, craftbot-skill-creator, craftbot-skill-improve, docx, enabled_skills, file-format, pdf, Playwright, playwright-mcp, pptx, predict-stock-next-week, skills_config.json, xlsx, !CONFIG, !CraftBot, !list_folder, !Skill, ?agent-app :: The shipped `skills/` directory contains around 100+ entries. Most are disabled by default; flip them via `enabled_skills` in `skills_config.json` to use. Ex... -[c053ae80daee9] [judged] agent_file_system/ENTITIES.md, memory_search, !LINE, !memory-processing, !MEMORY.md :: `agent_file_system/ENTITIES.md` is the memory graph's registry: the named entities you know about, plus connection records linking each memory chunk to the e... -[c05414e412e87] [judged] Decision Rubric, PROACTIVE.md, recurring_add, recurring_read, recurring_remove, recurring_update_task, remove_scheduled_task, schedule_task, schedule_task_toggle, scheduled_task_list, scheduler_config.json, !/update, !CONFIG, !memory-processing, !proactive :: ``` PROACTIVE.md (preferred for user automations) scheduler_config.json (system + one-offs) ─────────────────────────────────────────────── ─────────────────... -[c05f31ca1dfc1] [judged] PROACTIVE.md, recurring_add, recurring_read, schedule_task, scheduled_task_list, scheduler_config.json, !/help, !CONFIG, !proactive :: User says: "remind me to drink water every 2 hours" or "set up a daily 7am morning briefing". ``` Step 1: Acknowledge and decide which mechanism - Time-based... -[c074316321199] [judged] :: - Adding/enabling an MCP server modifies your runtime tool surface. Tell the user before doing it. - If `env` requires credentials, ASK first. Do not write e... -[c083c8b4c4f72] [judged] :: Quick lookup of the terms used throughout this manual. Each entry points to the section that owns the full definition. Grep this section first when an unfami... -[c09154ff64964] [judged] CUSTOM_ACTION_GUIDE.md, read_file.py :: If you discover the harness is missing a capability you need repeatedly: 1. Read [app/data/action/CUSTOM_ACTION_GUIDE.md](app/data/action/CUSTOM_ACTION_GUIDE... -[c09399a4de511] [judged] !CONFIG, !GitHub :: ...ention_only`, GitHub `watch_repos`) — read/write via the integration's config actions where exposed. Other times to grep an INTEGRATION.md: - An action re... -[c098adbb94932] [judged] mcp_config.json, MCPClient, !add_action_sets, !CONFIG :: ``` mcp_config.json (your edit) │ ▼ MCPClient.initialize() at startup OR MCPClient.reload() on hot-reload │ ▼ for each enabled server: spawn subprocess (stdi... -[c09c5b2ee579b] [judged] mcp_config.json, !/reset, !/tokens, !CONFIG, !LLMConsecutiveFailureError, !session :: ...und → server may be disabled in `mcp_config.json` or the `action_set_name` not loaded. See `## MCP`. **Action limit / token limit reached (100%)** - There... -[c0a12a76474dd] [judged] app/ui_layer/commands/builtin/, craftos_integrations, Gmail, Google Calendar, Google Docs, Google Drive, Google YouTube, integrations.py, Telegram, telegram_bot, telegram_user, WhatsApp, !/help, !AUTH, !google, !list_available_integrations :: For each integration registered in the `craftos_integrations` package, a slash command `/{integration}` is auto-registered ([app/ui_layer/commands/builtin/in... -[c0a5a2fe3a490] [judged] check_integration_status, craftos_integrations, craftos_integrations/providers//INTEGRATION.md, Discord, GitHub, WhatsApp, !CONFIG, !web_search :: Connecting is one job; *using* an integration is another. A connected integration beats asking the user or a generic web search — check `check_integration_st... -[c0a774e2aea55] [judged] grep_files, logs//all.log, !RUN_CONTINUATION :: grep_files "run ended\|force-stopped\|RUN_CONTINUATION" logs//all.log -A 3 -[c0a7c1c081cee] [judged] AGENT.md, FORMAT.md, SOUL.md, USER.md, !/clear, !/provider, !CONFIG, !LINE, !proactive :: ASK the user before: - Editing AGENT.md or SOUL.md (they affect every future interaction). - Installing anything that runs new code (git clone, pip install, ... -[c0d17fb3d9c16] [judged] FORMAT.md, grep_files, !docx, !pdf, !pptx, !xlsx :: - Purpose: design and formatting standards for documents you generate. - Write access: user (preferences); you when the user supplies a new rule (with confir... -[c0d951a02d2c6] [judged] stream_edit, USER.md, workspace/missions//INDEX.md, !/clear, !/tokens, !LINE, !memory_search, !send_message :: The user's personality traits the agent should adapt to. ``` **When to edit:** - The user shares a stable preference: "I'm in Tokyo timezone now", "I prefer ... -[c0e1f62b4880c] [judged] day-planner, EVENT_UNPROCESSED.md, MEMORY.md, month-planner, PROACTIVE.md, scheduler_config.json, settings.json, week-planner, !/update, !CONFIG, !memory-processing, !proactive :: These ship pre-configured in [app/config/scheduler_config.json](app/config/scheduler_config.json) and run the system itself: ``` id schedule purpose ────────... -[c0f175dad4438] [judged] convert_from_pdf, convert_to_markdown, convert_to_pdf, docx, edit_pdf, file-format, FORMAT.md, pdf, pptx, read_pdf, stream_edit, xlsx, !Skill :: Document actions in the standard action set: ``` convert_to_markdown normalize office formats before further processing read_pdf read a PDF with page support... -[c0fbf50ae322e] [judged] end_turn, schedule_task, send_message, set_requirement, update_todos, !/update, !continue_work :: - Delivering the result with `continue_work=true` → the run never ends and you burn turns. Final messages end the run. - Ending a run silently with `end_turn... -[c0ffb636dbb6d] [judged] !/update, !session :: - Purpose: persona and preferences of the user. Read at the start of any user-facing task. - Write access: the agent (after confirming with the user); the on... -[c104ea29f9d83] [judged] stream_edit, !Skill :: Every install / edit needs a smoke test. If the smoke test fails: ``` 1. Revert the edit (stream_edit back, OR /mcp disable, OR /skill disable, OR delete a t... -[c10a0cbe54b8c] [judged] anthropic, aws_credentials, bedrock, BytePlus, claude-sonnet-4-6, deepseek, Gemini, glm, google, grok, Minimax, Moonshot, openai, OpenRouter, slow_mode, slow_mode_tpm_limit, !/provider, !/tokens, !AUTH, !find_files, !MODEL, !session, !VLM :: ...s remain after a prune) item_word_limit: int (default 150; words per stored memory item) model: llm_provider: any provider key registered in the code (see... -[c1170c00b3a56] [judged] Sakana (Fugu), !/provider, !CREDIT :: ... back. BAD_REQUEST / other Investigate before retrying. UNKNOWN ``` Sakana (Fugu) quirk: an HTTP 429 with `usage_limit_reached` is classified CREDIT (prep... -[c11bebaf04ecd] [judged] schedule_task, send_message, !/clear :: ...m" fire 9am tomorrow. ``` Schema reminder (full table is in "Scheduled task actions" above): ``` schedule_task( name="", instruction=" [args] invoke the skill directly ```... -[c141328a9846e] [judged] fire_at, list_folder, run_shell, !session :: ...il the user picks Continue/Stop. See ## Errors above. ModuleNotFoundError from a run_shell script the script needs a dependency. Install it via run_shell ... -[c15f8b9a137e2] [judged] anthropic, ChatGPT, Codex, CraftBot, gpt-5.3-codex-spark, gpt-5.4, gpt-5.4-mini, gpt-5.5, grok, openai, openai_chatgpt_oauth.json, !/provider, !/upgrade, !MODEL, !session :: Users can authenticate OpenAI or Grok by signing in to their paid subscription (browser OAuth) instead of pasting an API key. Credentials live in `.credentia... -[c17344809a9d3] [judged] !CONFIG :: ... Hot-reload behavior config files (auto-applies) ## Configs ``` For any improvement, the right question is: which surface should change? If you can't pick... -[c19fdeebb73b5] [judged] day-planner, heartbeat-processor, month-planner, week-planner, !/help, !/update, !proactive :: Today: - Object detection system: remove 502/python execution failures; verify API returns structured detections (bbox + labe... -[c30747cbdd0bd] [judged] MODEL_REGISTRY, model_registry.py, PROVIDER_CONFIG, provider_config.py, VLM, !/clear, !/provider, !CONFIG, !MODEL :: The set of providers is defined in code (PROVIDER_CONFIG in [provider_config.py](agent_core/core/models/provider_config.py), surfaced as [MODEL_REGISTRY](age... -[c31710e1060fa] [judged] AGENT.md, LLMConsecutiveFailureError, month-planner, proactive, PROACTIVE.md, recurring_add, recurring_update_task, settings.json, Skill, USER.md, !/update, !MODEL :: ``` Trigger Improvement type ──────────────────────────────────────────────────────────── ────────────────────────────────────── User explicit ask: "add an M... -[c32037d3e1426] [judged] spawn_subagent :: `spawn_subagent` returns `{status, result, ...}`. **Only `result` matters** — act on that. If `status` is `failed` or `timeout`, the brief is unusable: re-sc... -[c32619f49b1b3] [judged] bedrock, BytePlus, endpoints.remote, Gemini, google, Ollama, openai, OpenRouter, settings.json, !/provider, !MODEL :: In `settings.json` `endpoints`: ``` remote_model_url base URL for "remote" provider (Ollama or OpenAI-compat) remote alternate endpoint for remote (default h... -[c33632182aad9] [judged] AGENT.md, SOUL.md, USER.md :: Three files in your own file system are agent-editable: `AGENT.md`, `USER.md`, `SOUL.md`. Each affects a different surface, has different consent rules, and ... -[c33d92f135d20] [judged] mcp_config.json, MCPClient, Skill, !CONFIG, !MODEL :: MCP (Model Context Protocol) servers extend your tool inventory at runtime. Use MCP when you need a capability that no built-in action covers and no skill ca... -[c341b162e2b51] [judged] memory-processing, MEMORY.md, settings.json :: When MEMORY.md exceeds `memory.max_items` in settings.json (default 200), pruning kicks in: ``` 1. the pruning instruction is folded into the same memory-pro... -[c35830b5f2bb4] [judged] EVENT.md, find_files, list_folder, mcp_config.json, proactive, PROACTIVE.md, run_shell, web_fetch, web_search, !AUTH, !CONFIG :: **File / shell / Python action returns `status=error`** - Read the `message` field. It often points at the fix (file not found, permission, syntax error, mis... -[c359c7c61d4e1] [judged] anthropic, BytePlus, Gemini, LLMInterface, MODEL_REGISTRY, ModelFactory, Ollama, openai, reinitialize_llm, settings.json, !/provider, !CONFIG, !MODEL :: At construction (and on `reinitialize_llm`), `ModelFactory.create(provider, interface, model_override, ...)`: ``` 1. Looks up the provider in MODEL_REGISTRY[... -[c36305740d100] [judged] EVENT.md, grep_files, list_folder, logs//all.log, session, !LINE :: ...-troubleshooting workflow.** When an action returns an error you cannot decode from `message` alone: ``` 1. Identify the current run folder: list_folder l... -[c363d66b213cc] [pending] Agent App, agent-app-creator, agent-app-importer, agent-app-manager, agent-app-modify, ?agent-app :: ``` agent-app-creator start a new project (wizard, requirements, scaffold) agent-app-modify change an existing project (features, layout, fixes) agent-app-ma... -[c36e69cc096c9] [judged] :: - Purpose: personality, tone, behavior. Injected directly into the system prompt every turn. - Write access: user (primarily); you only on explicit user requ... -[c36f1738b692c] [judged] :: ``` /cred list list all stored credentials across integrations /cred status show connection status for every integration /cred integrations list available in... -[c372a2138fdb7] [judged] diagnostic/logs/actions/, diagnostic/README.md, Loguru, memory_search, session, !LINE :: ...ction_error, internal). Already on disk and indexed by memory_search. logs// project_root/logs// (ONE FOLDER PER APP RUN) runtime perspect... -[c37639b797dcf] [judged] EVENT.md, EVENT_UNPROCESSED.md, EventStreamManager, memory-processing, memory-processor, memory_search, session, !/reset, !LINE :: ... Multi-line payloads continue on subsequent lines. Auto-rotated when the size threshold is exceeded. **EVENT_UNPROCESSED.md** — this session's staging buf... -[c37764a03d354] [pending] Agent App, session, ?agent-app :: - `workspace/` (root): never auto-cleaned. Anything you save here persists until the user deletes it. - `workspace/sessions/{session_id}/`: created automatic... -[c3927877f2854] [judged] app/config/onboarding_config.json, onboarding_config.json, !CONFIG :: First-run state is tracked in [app/config/onboarding_config.json](app/config/onboarding_config.json). -[c39b90e70f8ce] [judged] :: Create `workspace/missions//INDEX.md` when ANY of: - Work spans multiple sessions or days. - Plan has more than ~10 todos. - User uses words li... -[c3a3bc047fbb4] [judged] onboarding_config.json, scheduler_config.json, Skill, !CONFIG :: ... the current run are unaffected until reloaded. log signature [SKILL] Reloaded skills_config ... scheduler_config.json callback scheduler.reload (async) e... -[c3c6ced3a9621] [judged] onboarding_config.json, USER.md, !CONFIG :: - If `hard_completed` is false, prefer asking the user for missing profile details over assuming. - If `soft_completed` is false, the soft interview is pendi... -[c3c9ea5aef0e7] [judged] list_skills, Skill, unload_skill, use_skill :: Two paths: **Path 1: User invocation via slash command.** When the user types `/ [args]`: ``` 1. The runtime invokes the skill directly — the run... -[c3ce6a9648ce3] [judged] bedrock, BytePlus, CraftBot, endpoints.remote, find_files, Gemini, google, LinkedIn, Notion, Ollama, OpenRouter, Outlook, session, Slack, web_search, !/provider, !/tokens, !MODEL :: ...rl file_index: prewarm_all_drives: bool (build the find_files index for all drives at boot) endpoints: remote_model_url: string (for "remote" provider, e.... -[c3d68c6388263] [pending] Agent App, agent-app/blueprint/, CraftBot, craftbot.json, manifest.json, PocketBase, reference/requirements.md, ?agent-app :: ...base.log, frontend_console.log └── .factory/ Factory machine state — do not touch ``` - `reference/requirements.md`: the contract. Any modify must append ... -[c3de9606b0fd9] [judged] stream_edit, write_file, !LINE :: - Use as a pair when modifying an existing file. - `read_file` returns the exact content with line numbers. - `stream_edit` applies a precise diff. - Preferr... -[c3ebccbbb24bb] [judged] AGENT.md, check_integration_status, list_action_sets, LLMConsecutiveFailureError, proactive, PROACTIVE.md, recurring_read, recurring_update_task, send_message, Skill, !/update, !CONFIG, !MODEL :: ... after the user asked for it) the propose step IS the request itself. Do not over-confirm. 5. EXECUTE - Use the right action / config edit (see per-catego... -[c41caea78caaa] [judged] send_message, session :: There is no wait-for-reply state. To ask the user something, make the question your final `send_message` — the run ends and the session sleeps until the next... -[c44759f0778d1] [judged] EVENT_UNPROCESSED.md, INDEX_TARGET_FILES, Memory settings panel, memory-processing, memory.processing_threshold, memory_search, scheduler_config.json, stream_edit, USER.md, !CONFIG :: memory-processing runs at most once daily (default 3am; the time is user-configurable from the Memory settings panel, which rewrites the `memory-processing` ... -[c45dc037f01a5] [judged] manager.py, Skill, SkillMetadata, SkillsConfig, !CONFIG :: A skill is a markdown file with structured instructions that get injected into your prompt when selected. Skills exist for reusable workflows and codified do... -[c472d546b0536] [judged] grep_files, logs//all.log :: grep_files "[LIMIT]" logs//all.log -A 2 -[c483c79403da9] [judged] AGENT.md, proactive, PROACTIVE.md, Skill, SOUL.md, USER.md :: - Cavalier installs ("might be useful"). Every MCP server / skill / integration is a tax on prompt size and a maintenance burden. Only install when there is ... -[c4918880123a2] [judged] workspace/missions//INDEX.md :: - Purpose: template for `workspace/missions//INDEX.md`. See `## Workspace`. - Write access: static template. DO NOT edit. - Read pattern: when starting... -[c4a02e324b05a] [judged] app/config/settings.json, chroma_db_memory/, memory-processing, MEMORY.md, memory.processing_threshold, memory_search, settings.json, !CONFIG :: In [app/config/settings.json](app/config/settings.json) `memory` block (see `## Configs`): ``` memory.enabled bool. If false, memory_search returns empty + n... -[c4ad96c0faa9e] [judged] proactive :: ...ly run when user is active - weekdays_only: Skip weekends - Custom conditions can be added as needed =====================================================... -[c4b1a0abbf634] [judged] :: - Added CRM contact: Tan Wei Yang (Account Manager) -[c589994c86718] [judged] BytePlus, Gemini, Minimax, Moonshot, openai, OpenRouter, VLM, !/provider, !reinitialize_image_gen, !reinitialize_video_gen :: ... for vision but only a text-only provider is configured, tell them to set a separate `vlm_provider`. Image generation falls back through providers in prio... -[c58a6873ff5b0] [pending] Agent App, ?agent-app :: - Purpose: global design rules applied to every Agent App project. - Write access: user (primarily). You only when the user supplies a new universal rule wit... -[c58d48f32aab9] [judged] add_action_sets, proactive, Skill, unload_skill, use_skill :: Any loaded action is callable on any turn. Expand or shrink the surface in place: ``` add_action_sets([...]) / remove_action_sets([...]) load / unload action... -[c5a2a4ce44e23] [judged] google, manage_integration_account, !/clear, !/provider :: ...ames are shared across the Google family for the same underlying account. Rules that matter to you: - **Every action for these integrations takes an optio... -[c5a6958bd9925] [judged] chroma_db_memory/ :: ... action to trigger it — do not fabricate one — and it costs nothing when no connections are pending. Troubleshooting: - An empty `## Entities` on a fresh ... -[c5b2b28daae08] [judged] session, !pdf :: - Always use absolute paths when invoking actions: `agent_file_system/workspace/<...>`. Never relative paths. - Inside an action result you may receive a pat... -[c5b2b7980d9e1] [judged] :: - It does NOT change your approach when an action fails. You must. - It does NOT pick a different action when one returns `status=error`. You must. - It does... -[c5c7c0de7a770] [judged] ActionExecutor, ActionLibrary, ActionManager, ActionRouter, ContextEngine, EVENT.md, EVENT_UNPROCESSED.md, EventStreamManager, LLMInterface, MCPClient, MemoryManager, proactive, PROACTIVE.md, ProactiveManager, scheduler_config.json, session, SessionManager, SessionRuntimeManager, Skill, TriggerService, !CONFIG :: You do not call these directly, but every action routes through them. Knowing what owns what helps you debug: ``` LLMInterface text + vision generation gatew... -[c5d9ac57d7854] [judged] proactive :: Evaluate each potential proactive task using a five-dimension rubric. Score each dimension from 1 to 5: | Dimension | 1 (Low) | 5 (High) | Description | |---... -[c5db825564a97] [pending] Agent App, AgentBase, AgentBase.react(trigger), app/agent_base.py, session, !continue_work, !end_turn, !run-start trigger, !send_message, ?agent-app :: You run inside `AgentBase.react(trigger)` at [app/agent_base.py](app/agent_base.py). The unit of work is a **session** (main, chat, or agent_app). A **run** ... -[c5f01db7be7ca] [judged] USER.md :: | Phase | What it does | Output | |---|---|---| | Hard onboarding | Wizard collects user_name, location, language, tone, proactivity, approval rules, messagi... -[c5f2c917ba6fc] [judged] AGENT.md, Skill, Slack, SOUL.md, USER.md, !/tokens, !CATEGORIZE, !CONFIG, !IDENTIFY/SEARCH/INSTALL/WAIT/CONTINUE/REMEMBER, !RECOGNIZE, !VALIDATE :: Replace the simple IDENTIFY/SEARCH/INSTALL/WAIT/CONTINUE/REMEMBER with this fuller cycle: ``` 1. RECOGNIZE - You see a gap, friction, or explicit user ask. -... -[c607f9d4d7d2c] [judged] day-planner, heartbeat-processor, month-planner, proactive, PROACTIVE.md, Skill, skills/day-planner/SKILL.md, skills/heartbeat-processor/SKILL.md, skills/month-planner/SKILL.md, skills/week-planner/SKILL.md, week-planner, !end_turn, !send_message :: Three time-horizon planners ship as separate skills, each owning one cadence: ``` day-planner (skills/day-planner/SKILL.md) daily 7am week-planner (skills/we... -[c60c1e91f47d6] [judged] AGENT.md, EVENT.md, MEMORY.md, proactive, PROACTIVE.md, recurring_update_task, USER.md, !/clear, !/update, !end_turn, !planner-maintained section, !send_message, !stream_edit :: ...set up — confirm first. **4. Is the Goals / Plan / Status section in PROACTIVE.md still accurate?** If a proactive task accomplished or invalidated someth... -[c60d5181b0056] [pending] Agent App, agent_core/core/impl/trigger/session_queue.py, app/triggers/sources.py, app/triggers/store.py, memory-processing, proactive, PROACTIVE_HEARTBEAT, schedule_task, session, Skill, TriggerSource, !fire_at, !RUN_CONTINUATION, !USER_MESSAGE, ?agent-app :: Triggers are durable rows in per-session queues ([app/triggers/store.py](app/triggers/store.py), [agent_core/core/impl/trigger/session_queue.py](agent_core/c... -[c61b6310b5b8e] [judged] disabled_skills, enabled_skills, Skill, skills_config.json, !/skill disable , !/skill enable , !CONFIG, !stream_edit :: A skill's enabled state is governed by its presence in `enabled_skills` vs `disabled_skills` in [app/config/skills_config.json](app/config/skills_config.json... -[c6284965f3947] [judged] app/agent_base.py, file_operations, heartbeat-processor, proactive, PROACTIVE_HEARTBEAT, proactive_manager.get_all_due_tasks(), recurring_update_task, session, settings.json, Skill, web_research, !/update :: Every 30 min (`0,30 * * * *`): ``` 1. fires a PROACTIVE_HEARTBEAT trigger for the main session 2. the pre-check in app/agent_base.py: proactive_manager.get_a... -[c6336eb62b7df] [pending] ?/update, ?Agent App, ?agent-app, ?agent-app CLI, ?agent_app_http, ?agent_app_usage, ?CraftBot, ?run_shell :: Read/write a project's live data with the agent-app CLI via `run_shell` (absolute paths required): ``` node /agent-app/tools/src/cli.ts data <... -[c63539466c131] [pending] Agent App, agent_app_approve_triggers, agent_app_convert, CraftBot, craftbot.json, operations.json, triggers.json, !fire_at, !reference/source/, ?agent-app :: ... through the adapter (destructive ops are shape-checked). Run during adoption after notify_ready and after every operations.json edit; the import isn't do... -[c643cd89e179f] [pending] Agent App, AGENT.md, FORMAT.md, GLOBAL_AGENT_APP, LINE, SOUL.md, USER.md, ?agent-app :: ``` Type of change File Consent rule ────────────────────────────────────────────────────── ──────────────── ────────────────────────────── Operational rule ... -[c66b19f71a998] [judged] anthropic, app/config/settings.json, claude-sonnet-4-6, disabled_skills, enabled_skills, mcp_config.json, openai, proactive, recurring_add, schedule_task, scheduler_config.json, settings.json, Skill, skills_config.json, !/provider, !api_keys_configured, !CONFIG, !MODEL, !stream_edit, !VALIDATE :: Switch LLM provider: ``` read_file app/config/settings.json stream_edit app/config/settings.json model.llm_provider: "openai" → "anthropic" model.llm_model: ... -[c66d456efc398] [judged] EVENT.md, EVENT_UNPROCESSED.md, EventStreamManager, memory-processing, memory-processor, MEMORY.md, session, Skill, workspace/sessions//, !memory.processing_threshold :: ``` 1. Action / message / system event happens | v 2. EventStreamManager appends to the writing (per-session full log, session's EVENT.md workspace/sessions/... -[c66e2601c5bc8] [pending] ?Agent App, ?agent-app, ?agent_app_list_projects, ?agent_app_notify_ready, ?agent_app_scaffold, ?agentapp_, ?search_agent, ?session :: ``` agent_app_scaffold(name, description, ...) Create a project: copies the blueprint, allocates ports, runs the requirements interview, then dispatches the ... -[c68cdfe68d7ab] [judged] LLMConsecutiveFailureError :: ...edin login` required → ask user to authenticate. - "send a fax" → state limitation, suggest email. **LOOP** - Symptoms: same action + same params + same e... -[c68f8051b7787] [judged] ContextEngine, EVENT.md, memory_search, session, Skill, !set_requirement :: What the LLM sees on each `_select_action` call: - Static system prompt (your role, policy, file-system map, environment). - The relevant slice of the sessio... -[c699be03b254d] [judged] proactive, recurring_update_task, !/update :: Every recurring task should record its outcome via `recurring_update_task add_outcome` so future executions can learn from history. The `outcome_history` fie... -[c69b6d393b114] [judged] anthropic, BytePlus, CraftBot, google, mcp_config.json, openai, OpenRouter, settings.json, !api_keys_configured, !CONFIG :: ...926; CraftBot browser frontend port) startup_ui: bool (auto-open browser at startup) api_keys_configured: (BOOKKEEPING - reflects which keys are non-empty... -[c6a97885a3cea] [judged] diagnostic/logs/actions/, diagnostic/README.md, EVENT.md, LINE, logs///.log, logs//all.log, Loguru, session :: ...ll input/output for individual actions. See diagnostic/README.md. ``` **Picking the right surface:** - "What did I do, and what did the harness say back?"... -[c6d0c85f21b16] [judged] app/data/action/.py, grep_files, LINE, list_action_sets :: You have three discovery paths. Pick by purpose. **1. By name (when you already know it).** Read the source: ``` read_file app/data/action/.py `... -[c6ddeaecffafb] [judged] find_files, LinkedIn, schedule_task, !send_message :: There are four failure types. Identify which one you are in, then follow the matching recovery. **TRANSIENT** - Symptoms: rate limit, transient 5xx, connecti... -[c6e4fdf5f7438] [judged] AGENT.md, memory_search, SOUL.md, USER.md :: After ANY edit: ``` For AGENT.md: 1. re-read the changed section in your next turn (it's now in your context). 2. confirm the front-matter version: bumped (i... -[c6e6656912fb9] [judged] GitHub, grep_files, mcp_config.json, Playwright, playwright-mcp, !CONFIG :: The shipped `mcp_config.json` contains roughly 157 server entries (most `enabled: false`). Examples of always-shipped, commonly-enabled ones: ``` filesystem ... -[c6e831b565a43] [judged] memory_search :: **Purpose.** User profile. Identity, communication preferences, agent-interaction rules, life goals, personality. Indexed by `memory_search` (see `## Memory`... -[c7021d82b8c0c] [judged] AGENT.md :: You do not call actions directly in code. You emit an action decision in your turn output. Format (illustrative): ``` {"action_name": "read_file", "parameter... -[c702f6b837ea3] [judged] classify_llm_error(), slow_mode, !/provider, !AUTH, !BLOCKED, !CONFIG, !CREDIT, !MODEL :: When an LLM call fails, `classify_llm_error()` sorts it into a category. The category tells you whether retrying helps and what to tell the user: ``` categor... -[c70c62b51b146] [judged] EVENT_UNPROCESSED.md, proactive, PROACTIVE.md, !CONFIG :: ...ns// (it's mission-internal) INDEX.md Recurring or scheduled task definitions PROACTIVE.md via recurring_* / schedule_* (or scheduler_ actions, NOT man... -[c7105e7b01d01] [judged] settings.json, !api_keys_configured, !CONFIG :: - JSON syntax errors silently keep the OLD config in memory. The reload fires, the parser fails, the manager logs the error, and the previous state remains a... -[c718107462654] [pending] A2App, Agent App, AGENT_APP.md, CraftBot, manifest.json, operations.json, pb_hooks, PocketBase, reference/requirements.md, walk_verify, !CONFIG, ?agent-app :: Agent App projects live at `agent_file_system/workspace/agent_app/_/`. Every project is a React frontend + a single PocketBase backend pr... -[c724a367e33a9] [pending] Agent App, memory_search, research_agent, spawn_subagent, walk_verify, web_fetch, !agent_type, !sub_task_end, ?agent-app :: ``` Online research (search the web, fetch pages, gather facts) → spawn_subagent("research_agent", ...) Agent App browser verification → walk_verify (usually... -[c727895a4143d] [judged] EVENT.md, memory_search, session, update_todos, workspace/missions//INDEX.md, !/update :: ``` - A scratch pad. Use workspace/sessions/{session_id}/ for that. - A todo list. Use update_todos. - A mission record. Use workspace/missions//INDEX.... -[c729f6083d0fc] [judged] list_action_sets, mcp_config.json, !CONFIG :: Sets are NOT hardcoded. They are discovered dynamically by scanning every registered action's `action_sets=[...]` declaration. Any name an action declares be... -[c732bdb841d79] [judged] run_shell, !/mcp env , !/upgrade, !CONFIG, !stream_edit :: ... remote unreachable. server connected, tool calls return missing or wrong env ask user for the key, set "unauthorized" / "missing API key" / "401" variabl... -[c7368caeb7741] [judged] .accounts.json.corrupt, google, !/provider :: ...rovider>.accounts.json` (one document per provider: primary + all accounts with alias/listen flags). A `.accounts.json.corrupt` sidecar means th... -[c7486a0d3dcfd] [judged] LINE, SOUL.md, !stream_edit :: **Purpose.** Personality, tone, voice, behavior style. **Injected directly into the system prompt every turn.** This is not a reference file — it shapes ever... -[c74ba229b107d] [judged] EVENT.md, grep_files, MEMORY.md, memory_search, proactive, PROACTIVE.md, USER.md :: ``` Question Tool ────────────────────────────────────────── ───────────────────────────── "What do I know about X?" memory_search(query="X") "What did the u... -[c750b08e3b0ba] [judged] grep_files, read_file.py :: - Returns `cat -n` formatted lines plus a `has_more` flag. - Default limit is 500 lines. Use `offset` and `limit` for targeted reads. - For files larger than... -[c789b12ca3165] [judged] grep_files :: When an action returns a very large output, the harness does NOT dump it into your context — it saves it to a file and gives you a short pointer instead. You... -[c78bf758a854b] [judged] update_todos, !/update :: Use `update_todos` whenever the work takes more than a couple of actions. Every todo begins with one of: ``` Collect: Gather inputs (read files, search, ask ... -[c78d9dbdc8aec] [judged] grep_files, LINE :: Three output modes: - `files_with_matches`: returns file paths only. Use for discovery ("which files contain X"). - `content`: returns matching lines with li... -[c79fe8fa47a88] [judged] Skill, !/clear, !/exit, !/reset :: If a user types a slash command and you receive the resulting run or message: - The runtime processes the command BEFORE you see it. Your role is to react to... -[c7c424c269772] [judged] Skill, !/provider, !CONFIG, !MODEL :: - The live LLM client's provider/model (requires a reinitialize — `/provider` or Settings UI save, see `## Models`). - An LLM call already in flight (uses th... -[c7c5b9e377ad9] [judged] session, !/provider, !MODEL :: - Always confirm with the user before switching provider. Session caches don't transfer across a provider change. - Always mask API keys in chat (`sk-***...*... -[c7d6f648be609] [judged] add_action_sets, grep_files, list_action_sets, mcp_config.json, Stripe, !CATEGORIZE, !CONFIG, !RECOGNIZE, !send_message, !stream_edit, !VALIDATE :: **Example 1: User asks for a missing capability** ``` User: "I want you to be able to manage my Linear issues." Agent: 1. RECOGNIZE: No built-in Linear integ... -[c7d997d726dcd] [judged] agent_core/core/impl/config/watcher.py, ConfigWatcher, watchdog, !CONFIG, !run_coroutine_threadsafe :: Source: [agent_core/core/impl/config/watcher.py](agent_core/core/impl/config/watcher.py) (`ConfigWatcher` singleton). ``` backend watchdog library if install... -[c7e7217509078] [judged] :: .... - **Self-detected logical loops.** The consecutive-failure breaker only catches LLM-call failures. If you keep choosing slightly different params for th... -[c7e8827299598] [judged] grep_files, logs//all.log :: grep_files "[MCP]" logs//all.log -A 3 -[c804fc1d55045] [pending] ?Agent App, ?agent-app, ?agent-app CLI, ?agent_app_http, ?agent_app_usage, ?BLOCKED, ?PocketBase, ?walk_verify :: ...No-op once the project runs. agent_app_report_finding(project_id, Inside a factory FIX round. ruled_out: causes you PROVED ruled_out?, blocked_question?) ... -[c81420f98d831] [judged] BLOCKED, CONFIG, CREDIT, LLMConsecutiveFailureError, LLMInterface, LLMInterface._max_consecutive_failures, MODEL, !AUTH, !USER_MESSAGE :: `LLMInterface._max_consecutive_failures = 5`. Non-transient failures (auth, credit, model, config, blocked, bad request) trip it immediately; transient ones ... -[c81708ede345d] [judged] onboarding_config.json, !CONFIG :: ...d_at: ISO timestamp | null user_name: string agent_name: string agent_profile_picture: string | null This file is NOT hot-reloaded. It is managed by the o... -[c819ef9af3ca8] [judged] proactive, !schedule_task :: ...minimum. Step 1 is non-optional for recurring tasks. **Anti-patterns when ending a proactive run:** - Ending the run without recording an outcome on a rec... -[c8317c630dedb] [judged] /whatsapp login, check_integration_status, connect_integration, Telegram, telegram_bot, telegram_user, WhatsApp, !AUTH :: ...→ connect_integration with token Default to whichever the user already mentioned. If unclear, ask. auth_type "interactive" (whatsapp) Requires a QR scan f... -[c8351953b4188] [judged] check_integration_status, Gmail, google, Google Calendar, Google Docs, Google Drive, Google YouTube, !BLOCKED :: ...Bot with the Google account you want, then tell me when you're done." User: "done" Agent: check_integration_status(integration_id="gmail") → if connected:... -[c839f08e63e68] [judged] end_turn, send_message, send_message_with_attachment, !grep_files :: ... action. - Use `send_message_with_attachment` when sending generated files; pass the workspace path. What NOT to send: - Internal reasoning ("I'm now thin... -[c83d446b183ea] [judged] CraftBot, proactive, send_message, send_message_with_attachment, Slack, Telegram, WhatsApp, !/update, !continue_work, !USER.md :: The user only sees what you send via `send_message` (or `send_message_with_attachment`). Everything else — actions, errors, internal reasoning — is invisible... -[c853298e4df0b] [judged] describe_image, generate_image, generate_video, memory_search, settings.json, VLM, !/provider, !MODEL :: The same provider serves up to five "interfaces": ``` LLM text generation. The main chat brain. Required. VLM vision-language model. Used for image actions (... -[c85727998580d] [judged] connect_integration, craftos_integrations, Discord, Notion, Slack, !/menu, !/provider, !/reset :: The fields each token integration needs (declared per integration in `craftos_integrations/providers//provider.py`; `connect_integration` returns `need... -[c85fa05f4f866] [judged] anthropic, LLMInterface, slow_mode, slow_mode_tpm_limit, !/provider, !/tokens :: If the user hits 429s (provider rate limit): ``` slow_mode: true pace requests slow_mode_tpm_limit: tokens per minute target. Common: 25000 for Anthropic... -[c86cf344e56b3] [judged] AGENT.md, !grep_files :: ...e/ per-agent sandbox under agent_file_system/ ## Workspace ``` If a term is missing, search the relevant section header (`grep_files "## " agent_fi... -[c86ee93672883] [judged] :: --- version: "1.0" last_updated: null # Auto-updated by system (format: YYYY-MM-DDTHH:MM:SSZ) --- -[c8820a8250156] [pending] Agent App, AGENT_APP.md, agent_app_usage, pb_hooks, PocketBase, reference/requirements.md, walk_verify, ?agent-app :: ``` 1. agent_app_usage(project_id) — get the operating manual. 2. Read the project's AGENT_APP.md (plan/index + file-ownership map) and reference/requirement... -[c89211a09bc71] [judged] :: - **Full Name:** (Ask the users for info) - **Preferred Name:** (Ask the users for info) - **Email:** (Ask the users for info) - **Location:** (Ask the users... -[c89b17a3b9805] [judged] agent_core/core/impl/memory/memory_file_watcher.py, app/data/action/memory_search.py, manager.py, memory_search, MemoryManager :: ...** Use it when you need to dig deeper on a specific question mid-run, beyond what got auto-injected. Code: [agent_core/core/impl/memory/manager.py](agent_... -[c8a356a73cf0c] [judged] CraftBot, craftbot-skill-creator, disabled_skills, enabled_skills, list_skills, Skill, skills_config.json, !CONFIG, !GitHub, !run_shell, !stream_edit, !web_search, !write_file :: Three paths, in order of preference: **1. Use the built-in `craftbot-skill-creator` skill.** ``` User runs: /craftbot-skill-creator or L... -[c8a869107089f] [judged] add_action_sets, proactive, schedule_task, Skill, unload_skill, use_skill :: 1. **Automatically per run** — workflow runs (memory, proactive, skill slash commands) and `schedule_task(action_sets=[...])` pre-load the sets a run needs. ... -[c8a9a4d0eb1ae] [pending] Agent App, end_turn, send_message, ?agent-app :: The input needs a short answer or 1-3 actions: ``` 1. Execute the action(s) if any are needed 2. Final send_message with the result ← this ends the run ``` T... -[c8b3896730cc4] [judged] AGENT.md, EVENT.md, SOUL.md, stream_edit, USER.md :: If a self-edit broke something or the user objects: ``` 1. AGENT.md: stream_edit back to the previous content. Bump version: again (every change deserves a v... -[c8b450581d776] [judged] agent_core/core/impl/llm/interface.py, LLMInterface, MODEL_REGISTRY, model_registry.py, model_settings.py, ModelFactory, PROVIDER_INFO, VLM, !/provider, !MODEL :: You generate every response through an LLM. The user can ask you to change provider or model in chat, and you can drive that change. This section covers: pro... -[c8b5deda4ec5e] [judged] proactive :: Prefer Proactive Assistance, Approval Required For, working hours, etc. -[c8c140ecd84c8] [judged] proactive, recurring_update_task, schedule_task, !/update :: A proactive task that runs and disappears without follow-up wastes the work. After ANY proactive task (recurring or one-time) finishes, the executing agent s... -[c8e860009ddfa] [judged] describe_image, pdf, read_pdf, understand_video, !grep_files :: - Repeated full reads of large files. Use `grep_files` plus offset reads instead. - Chaining four `read_file` calls when one `grep_files` would answer the qu... -[c8f299bc12e96] [judged] app/triggers/runtime.py, session, SessionRuntimeManager, !/clear :: - Each session has its own event stream, its own durable trigger queue, and a serial consumer loop (`SessionRuntimeManager`, [app/triggers/runtime.py](app/tr... -[c8f5aee7d8224] [judged] grep_files, LLMConsecutiveFailureError, logs//all.log :: grep_files "LLMConsecutiveFailureError\|MSG_CONSECUTIVE_FAILURE" logs//all.log -A 5 -[c8fbb700fb39e] [pending] ?Agent App, ?agent-app, ?agent-app CLI, ?agent_app_list_projects, ?agent_app_usage, ?web_search :: ... do it themselves, refuse, or web-search around it. sounds like something an app of yours already Agent App. agent_app_list_projects; on a match, does age... -[c9144ca09447b] [pending] Agent App, AGENT.md, AGENT_APP.md, FORMAT.md, GLOBAL_AGENT_APP, GLOBAL_AGENT_APP.md, MEMORY.md, MISSION_INDEX_TEMPLATE.md, proactive, PROACTIVE.md, SOUL.md, USER.md, !/update, ?agent-app :: Your persistent file system is `agent_file_system/`. Every file has a defined writer, reader, format, and update rule. Files marked `DO NOT EDIT` are managed... -[c91cc94f8bf04] [judged] list_folder, session :: ... logs for the timestamp of your action and look for `WARNING` or unexpected `ERROR` lines around it. **Rotation and freshness.** Logs rotate at 50 MB and ... -[c9380995b2007] [judged] day-planner, event_stream_manager.set_skip_unprocessed_logging(True), EVENT_UNPROCESSED.md, file_operations, heartbeat-processor, memory-processing, memory-processor, MEMORY.md, month-planner, proactive, PROACTIVE.md, PROACTIVE_HEARTBEAT, proactive_manager.get_all_due_tasks(), session, Skill, web_research, week-planner, !/reset :: Memory and proactive work run IN the main session — no separate task objects. The workflow's skills and action sets are loaded onto the session at run start ... -[c94fe46cbaf1b] [judged] /skill disable , /skill enable , create_skill_scaffold, disabled_skills, enabled_skills, Skill, skills_config.json, !CONFIG :: ``` /skill list [--all] list installed skills + enabled state /skill info show metadata + body of a skill /skill enable move a skill into enabl... -[c959f1ac75128] [judged] Skill :: When `allowed-tools` is non-empty in the frontmatter, the action filter narrows to ONLY those names while the skill is active. Use this for safety-critical s... -[c96e0c0e9d4a4] [judged] proactive, PROACTIVE.md :: You can operate proactively based on scheduled activations. Schedules can be hourly (every X hours), daily (at a specific time), weekly (on a specific day), ... -[c96e3ac32fb25] [judged] app/config/connection_test_models.json, app/config/onboarding_config.json, app/config/settings.json, connection_test_models.json, disabled_skills, mcp_config.json, onboarding_config.json, scheduler_config.json, settings.json, skills_config.json, !/provider, !CONFIG, !MODEL :: ``` app/config/settings.json model, API keys, OAuth, cache, browser, memory hot-reload app/config/mcp_config.json MCP server registry hot-reload app/config/s... -[c96eeac082785] [judged] :: Long-term goals worth aligning to. -[c9703c8bfcd60] [judged] MISSION_INDEX_TEMPLATE.md, !BLOCKED :: Template lives at [agent_file_system/MISSION_INDEX_TEMPLATE.md](agent_file_system/MISSION_INDEX_TEMPLATE.md). Required fields: - **Goal**: what "done" looks ... -[c9760bd6da76e] [judged] add_action_sets, disabled_skills, enabled_skills, mcp_config.json, Skill, skills_config.json, !CONFIG :: ..._name: string default "mcp_"; the action set tools register under } ] Patterns by transport: NPX (Node): transport="stdio" command="npx" args=["-y",... -[c977ee2d9caaa] [judged] Gmail, proactive, TASK_HISTORY.md, !/clear :: ...k, or wait for response BAD INSTRUCTION (too vague): "Check emails and summarize important ones." GOOD INSTRUCTION (detailed): "1. Connect to user's email... -[c9859dd4b7971] [pending] ?/update, ?Agent App, ?agent-app, ?agent-app CLI, ?AGENT_APP.md, ?agent_app_http, ?agent_app_scaffold, ?GLOBAL_AGENT_APP, ?GLOBAL_AGENT_APP.md, ?manifest.json, ?pb_hooks, ?reference/requirements.md, ?walk_verify :: - Hand-writing a scaffold instead of `agent_app_scaffold`. Manual scaffolds miss the kit, ports, and registration. - Editing `frontend/src/kit/` or system-ma... -[c99199a1c14a6] [judged] anthropic, api_keys_configured, settings.json, stream_edit, !/provider :: If the user just provides a new key for the CURRENT provider (e.g., they updated their Anthropic key): ``` 1. stream_edit settings.json api_keys./all.log, proactive, PROACTIVE.md, recurring_read, settings.json :: ``` 1. recurring_read(frequency="all", enabled_only=false) ← see all entries 2. read_file agent_file_system/PROACTIVE.md ← inspect raw 3. grep_files "[PROACT... -[ca1bbc8423cf0] [judged] api_keys_configured, app/config/settings.json, CraftBot, Gemini, google, LLMConsecutiveFailureError, reinitialize_image_gen, session, settings.json, stream_edit, VLM, !/provider, !CONFIG, !MODEL :: ...eam_edit does. Image / video gen change → Settings UI save (reinitialize_image_gen / _video_gen) ``` Procedure for a provider switch: ``` 1. Ensure api_ke... -[ca28f1f1c2358] [judged] check_integration_status, connect_integration, CraftBot, GitHub, Gmail, google, send_message, !/tokens, !continue_work :: A canonical chat-driven flow for `github`: ``` User: "connect my github" Agent: send_message(continue_work=true): "I can connect GitHub. I'll need a Personal... -[ca2c7465a83d3] [judged] !/update, !LINE :: - At task start (resuming a mission): read INDEX.md fully. Add a `Status` line for the new task. - During the task: append to `Key Findings` whenever you lea... -[ca314895c8a94] [pending] Agent App, agent_app_approve_triggers, agent_app_convert, agent_app_http, agent_app_list_projects, agent_app_notify_ready, agent_app_scaffold, agent_app_usage, Discord, GitHub, Gmail, google, Google Calendar, Google Docs, Google Drive, Google YouTube, HubSpot, Jira, Lark, LINE, LinkedIn, Notion, Outlook, recurring_add, recurring_read, recurring_remove, recurring_update_task, Slack, Stripe, Telegram, telegram_bot, Twitter, walk_verify, WhatsApp, !/update, ?agent-app :: ...ask, recurring_add, recurring_read, recurring_update_task, recurring_remove agent_app agent_app_scaffold, agent_app_list_projects, agent_app_notify_ready,... -[ca328ae77b514] [judged] :: The sub-agent starts BLANK. It cannot see your conversation, the user, memory, the current task, or anything you already know. So the `query` must be fully s... -[ca389355f590f] [judged] :: - **Language:** en - **Preferred Tone:** (Ask the users for info) - **Response Style:** (Ask the users for info) - **Preferred Messaging Platform:** (Ask the... -[ca3d20cbc088d] [judged] :: You operate inside a harness with multiple safety layers. Some failures are handled automatically; others require you to recover deliberately. Knowing which ... -[ca3e90abea531] [judged] :: Language, Preferred Tone, Response Style, Preferred Messaging Platform. -[ca47eaf122644] [judged] app/agent_base.py, disabled_skills, enabled_skills, invalidate_settings_cache, mcp_client.reload, mcp_config.json, settings.json, settings_manager.reload, Skill, skills_config.json, sync_skill_commands, !/provider, !CONFIG, !MODEL :: Every watched config has a specific reload callback registered at startup ([app/agent_base.py](app/agent_base.py) `_initialize_config_watcher`): ``` settings... -[ca6919a6694e3] [judged] app/data/action/memory_search.py, MEMORY.md, memory_search, retrieve_full_content :: `memory_search(query, top_k)` runs a hybrid relevance search over the indexed files ([app/data/action/memory_search.py](app/data/action/memory_search.py)): `... -[ca69b0aa7ff0c] [pending] ?A2App, ?Agent App, ?agent-app, ?CraftBot, ?craftbot.json, ?operations.json, ?settings.json, ?walk_verify :: ...built marketplace apps. As-is installs skip walk_verify. Marketplace source branch: settings.json agent_app.marketplace_ref (default "" = main; env CRAFTB... -[ca87df7e14022] [judged] CATEGORIZE, convert_to_markdown, docx, FORMAT.md, pdf, read_pdf, RECOGNIZE, send_message, stream_edit, Stripe, stripe-mcp, VALIDATE :: ...sk capability gap** ``` Mid-task, you need to call a Stripe API. No Stripe integration is connected. Agent (mid-task, simple flow): 1. RECOGNIZE: action a... -[ca8802cb53359] [judged] proactive, recurring_read, schedule_task :: ``` - One-off requests ("check the weather right now") → just do it inline. - Tasks with vague triggers or unclear stop conditions. - Tasks the user might fo... -[ca959d97c06b4] [judged] memory-processing, proactive, PROACTIVE_HEARTBEAT, scheduler_config.json, !CONFIG :: ...ls_config.json --> ``` File: app/config/scheduler_config.json enabled: bool master switch for the scheduler schedule... -[ca9e8e7374eba] [judged] heartbeat-processor, proactive, PROACTIVE.md :: The `conditions` array on a recurring task lets you filter executions: ``` {"type": "weekdays_only"} skip Saturday/Sunday {"type": "market_hours_only"} only ... -[caadcd4ad20d0] [pending] Agent App, app/action/action_set.py, Discord, generate_image, generate_video, GitHub, github_issues, Gmail, google, Google Calendar, Google Docs, Google Drive, Google YouTube, HubSpot, Jira, Lark, LINE, LinkedIn, list_action_sets, Notion, Outlook, proactive, schedule_task, schedule_task_toggle, scheduled_task_list, Slack, Stripe, Telegram, telegram_bot, telegram_user, Twitter, WhatsApp, ?agent-app :: ``` proactive schedule_task, scheduled_task_list, recurring_*, schedule_task_toggle, ... scheduler schedule_task, schedule_task_toggle (alongside proactive) ... -[cabed73b40b63] [judged] /mcp env , stream_edit, !/update, !CONFIG :: ``` /mcp list servers + connection state /mcp add [args...] register a stdio server /mcp add-json register from a full JSON entry /mc... -[cabf079fd0ac5] [judged] :: ...ion_framework/registry.py). When you read an action's `.py` file, these are the fields you will see: ``` name str required. Unique identifier the LLM uses... -[cabf16ac54c46] [pending] Agent App, day-planner, ?agent-app :: Today: Focus on Agent App execution and data hygiene. - Clock: show current weather (temperature + text condition) on th... -[cac5daf8b039b] [pending] Agent App, document_processing, proactive, Slack, ?agent-app :: `core` already covers files, shell, web, memory, scheduling, and messaging. Add sets only for: ``` Document generation document_processing Image / video gene... -[cac6804fdc0c3] [judged] USER.md, !LINE :: Self-improvement is not "add capabilities". It's "be measurably more useful to THIS user, on THEIR tasks, with the smallest necessary change". The best self-... -[cada226982d97] [judged] Skill :: ``` Need a capability and... an existing built-in action covers it → use the action (## Actions) a skill could compose existing actions → write/use a skill (... -[cae2ddf28f3bf] [judged] :: --- version: 8 purpose: agent operations manual --- -[cae6d800c8526] [judged] CONFIG, MODEL :: The agent's behavior is shaped by JSON config files under [app/config/](app/config/). When you need to change settings about yourself (model, API keys, MCP s... -[caf1ef383e294] [judged] check_integration_status, EVENT.md, list_available_integrations, memory_search, !web_search :: Your context window is not your knowledge. Before replying "I don't know", "I can't do that", or reaching for a generic web search, run the matching check be... -[caf3aff9210a1] [judged] AGENT.md, SOUL.md, USER.md :: ``` AGENT.md "How the harness works, and how to operate within it." (this file) USER.md "Who the user is and what they prefer." SOUL.md "How the agent sounds... -[caf90a03e4bb0] [pending] Agent App, AGENT.md, AGENT_APP.md, FORMAT.md, GLOBAL_AGENT_APP, GLOBAL_AGENT_APP.md, proactive, scheduler_config.json, Skill, SOUL.md, USER.md, !/provider, !CONFIG, !MODEL, ?agent-app :: For full step-by-step recipes per surface, follow these pointers. Do not duplicate them here. ``` Add an MCP server → ## MCP "Add or enable a server (recipe)... -[cb0742cfab827] [judged] api_keys_configured, CONFIG, logs//all.log, stream_edit, !write_file :: ``` 1. read_file see current state 2. decide what to change 3. stream_edit ... make the edit (preserves unrelated content) 4. wai... -[cb15f13bbeb56] [judged] AGENT.md, app/agent_base.py, app/proactive/manager.py, app/proactive/parser.py, app/scheduler/parser.py, Decision Rubric, manager.py, parser.py, proactive, PROACTIVE.md, PROACTIVE_HEARTBEAT, ProactiveManager :: ``` Decision Rubric (Impact / Risk / Cost / Urgency / Confidence, threshold) → PROACTIVE.md Permission Tiers (0-3 detailed contract) → PROACTIVE.md Recurring... -[cb1d028e3d91a] [judged] CONFIG, grep_files, LLMConsecutiveFailureError, logs//all.log, mcp_config.json, settings.json, stream_edit, !LINE :: grep_files "| ERROR " logs//all.log -A 5 ``` **Acting on what you find.** A log line is data, not a fix. The decision rules: ``` If the log shows then ─... -[cb2764e113ff7] [judged] add_action_sets, check_integration_status, connect_integration, CUSTOM_ACTION_GUIDE.md, disconnect_integration, list_action_sets, list_available_integrations, list_skills, logs//all.log, Skill, unload_skill, use_skill, !Discord, !GitHub, !Gmail, !google, !Google Calendar, !Google Docs, !Google Drive, !Google YouTube, !HubSpot, !Jira, !Lark, !LINE, !LinkedIn, !Notion, !Outlook, !Slack, !Stripe, !Telegram, !Twitter, !WhatsApp :: Built-in actions are Python files under [app/data/action/](app/data/action/). The action name does NOT always match the filename: ``` app/data/action/.... -[cb2777dc7077b] [pending] ?/provider, ?/update, ?Agent App, ?agent-app, ?agent-app CLI, ?AGENT_APP.md, ?anthropic, ?AUTH, ?chroma_db_memory/, ?ChromaDB, ?CONFIG, ?ConfigWatcher, ?connect_integration, ?continue_work, ?CraftBot, ?craftos_integrations, ?Decision Rubric, ?end_turn, ?EVENT.md, ?EVENT_UNPROCESSED.md, ?FORMAT.md, ?Gemini, ?GitHub, ?GLOBAL_AGENT_APP, ?GLOBAL_AGENT_APP.md, ?heartbeat-processor, ?INDEX_TARGET_FILES, ?Jira, ?LLMConsecutiveFailureError, ?LLMInterface, ?manage_integration_account, ?MEMORY.md, ?memory_search, ?MemoryManager, ?MISSION_INDEX_TEMPLATE.md, ?MODEL, ?MODEL_REGISTRY, ?Models auth_type, ?openai, ?PocketBase, ?proactive, ?PROACTIVE.md, ?PROACTIVE_HEARTBEAT, ?recurring_add, ?recurring_update_task, ?reinitialize_llm, ?schedule_task, ?scheduler_config.json, ?send_message, ?session, ?set_requirement, ?settings.json, ?Skill, ?Slack, ?slow_mode, ?SOUL.md, ?spawn_subagent, ?stream_edit, ?TriggerSource, ?update_todos, ?USER.md, ?VLM, ?walk_verify, ?workspace/missions//INDEX.md :: ... / ## Models auth_type integration auth flow shape: oauth/token/both/interactive/... ## Integrations ChromaDB vector store under chroma_db_memory/ powerin... -[cb27cafd14230] [judged] app/action/action_set.py, clipboard_read, clipboard_write, memory_search, Skill :: [app/action/action_set.py](app/action/action_set.py) `compile_action_list`: ``` required_sets = set(selected_sets) | {"core"} ``` You cannot opt out of `core... -[cb2c8a2c37cee] [judged] /tokens, @BotFather, CONFIG, Meta Business, Meta Cloud API, PAT, telegram_bot, !Atlassian, !GitHub, !Jira, !Telegram, !WhatsApp :: ...rver Members, etc.). 4. OAuth2 → URL Generator → bot scope + permissions → invite bot to server. telegram_bot bot_token (required — from @BotFather) Where... -[cb2dd32a3b183] [judged] /mcp env , CONFIG, mcp_config.json :: ``` /mcp list list configured MCP servers + enabled state /mcp add [args] register a new MCP server (stdio) /mcp add-json register fr... -[cb3359b878966] [judged] grep_files, memory-processing, memory_search, !LINE :: - Purpose: entity-graph registry — named entities plus memory→entity connection records. Powers the graph channel of `memory_search`. - Write access: ONLY th... -[cb36034d8ff6e] [judged] agent_core/core/action_framework/registry.py :: Every action is registered via the `@action` decorator at [agent_core/core/action_framework/registry.py](agent_core/core/action_framework/registry.py). When ... -[cb4b5ab79867f] [pending] Agent App, session, ?agent-app :: ``` Type of file → Destination final document the user should keep → workspace/ draft, sketch, intermediate state, scratch → workspace/sessions/{se... -[cb50e9c4e51d3] [judged] /help, file_operations, Skill, web_research :: ``` --- name: required. Snake-case or kebab-case. description: required. The LLM reads this to decide when to select. Be specific... -[cb58b60e847cc] [judged] CONFIG, CraftBot, proactive, scheduled_task_list, scheduler_config.json, settings.json :: ...sage output, or workspace files (depending on instruction). ``` **Verifying a one-shot is queued:** ``` scheduled_task_list() ← see all entries + next fir... -[cb66094731893] [judged] AUTH, CONFIG :: ``` stdio (subprocess, most common) transport: "stdio" command: "npx" | "uv" | "python" | "node" | args: [...] env: { KEY: VALUE } url: (omit) E... -[cb8884c160d60] [judged] /update, continue_work, send_message, session, set_requirement, update_todos :: Multi-step work, file outputs, irreversible operations, anything the user calls a "project": ``` set_requirement() ← FIRST move, be... -[cb98ac8b31352] [judged] app/scheduler/parser.py, parser.py, remove_scheduled_task, schedule_task, schedule_task_toggle, scheduled_task_list :: ``` schedule_task(name, instruction, schedule, priority?, enabled?, action_sets?, skills?, payload?) Adds a one-time, recurring, or immediate scheduled task.... -[cb9ef30d93377] [judged] proactive, PROACTIVE.md, recurring_add, recurring_read :: ``` recurring_add(name, frequency, instruction, time?, day?, priority?, permission_tier?, enabled?, conditions?) Adds a new recurring task to PROACTIVE.md. f... -[cba0891ac268c] [judged] Skill, unload_skill, use_skill :: ``` A directory: skills// ├── SKILL.md required └── optional, referenced by SKILL.md A SKILL.md file: YAML frontmatter (metadata) + mar... -[cbc1de9c16eca] [judged] app/config/onboarding_config.json, app/scheduler/parser.py, CONFIG, day-planner, heartbeat-processor, memory-processing, month-planner, onboarding_config.json, parser.py, proactive, PROACTIVE_HEARTBEAT, scheduler_config.json, Skill, week-planner :: ...eartbeat", "proactive_planner", "scheduled", ... } ] Schedule formats (parser at app/scheduler/parser.py): Natural: "every day at 3am" "every sunday at 5p... -[cbd76aecfb598] [judged] google, HubSpot, LinkedIn, Notion, Outlook, Slack :: Ten integrations support **multiple connected accounts**: the five Google services, Outlook, LinkedIn, Notion, HubSpot, and Slack. Each holds one **primary**... -[cbe72a4c38331] [judged] /provider, /update, add_action_sets, AGENT.md, AUTH, Models auth_type, proactive, recurring_update_task, settings.json :: ...the section that owns the full definition. Grep this section first when an unfamiliar term shows up. ``` action atomic unit the LLM picks each turn ## Act... -[cbea058402701] [judged] :: ``` The user can add more file-type sections (e.g., `## md`, `## csv`). Type-specific sections OVERRIDE `## global` for that file type. -[cbef4642a4b92] [judged] /provider, anthropic, BytePlus, claude-sonnet-4-6, deepseek, Gemini, gpt-5.2, grok, mistral, Ollama, openai, qwen :: When the user is undecided: ``` Goal Suggested provider ────────────────────────────────────────── ────────────────────────── General chat / coding / reasoni... -[cbf1fdd1ca06b] [judged] /tokens, AGENT.md, SOUL.md, USER.md :: - Editing AGENT.md for things that aren't operational rules (project state, one-off opinions, user-specific facts). - Editing USER.md for things that aren't ... -[cbf27bf19bf04] [judged] /update, continue_work :: `continue_work=true` = progress update, the run continues. Omitted or false = final message, the run ends. This flag is the run terminator — there is no sepa... -[cc00a9114c65d] [pending] Agent App, agent-app/blueprint/, app/data/action/agent_app_actions.py, CraftBot, PocketBase, shadcn, ?agent-app :: "Agent App" = generated web apps served from CraftBot. Every project is a React frontend (vendored kit, shadcn-conventional components) plus one PocketBase b... -[cc05aee71d03c] [judged] EVENT_UNPROCESSED.md, memory-processor, MEMORY.md, memory_search, !LINE :: - Purpose: distilled long-term memory. Survives across sessions. - Write access: ONLY the memory processor (daily 3am job, plus startup replay if EVENT_UNPRO... -[cc09df687b1ed] [judged] docx, file-format, FORMAT.md, pdf, pptx, send_message, xlsx :: ``` Short answer / explanation / summary / plan / code snippet / small table → inline chat (send_message) Long report / memo / formal document → PDF (default... -[cc0ec571840f0] [judged] /update, set_requirement, update_todos :: `update_todos` is your plan (the steps). `set_requirement` is your contract (what the finished output must contain). They are different things and you need b... -[cc1506391625d] [judged] add_action_sets, session, Skill, unload_skill, use_skill :: - Loaded sets belong to the session and persist across turns of a run. - `add_action_sets` / `remove_action_sets` mutate the selection at any time; workflow-... -[cc25bd6126c1a] [judged] Skill :: EVERY action — built-in, MCP-routed, or skill-spawned — returns a dict with at minimum: ``` { "status": "success" | "error", "message": "