🦜Zé Papagaio
← HomeDocs

Changelog

Version history and changes for Zé Papagaio.

v0.1.29latest2026-04-27
  • •🐛 安装程序仍然在「检查所需端口...」处静默退出 —— 在 0.1.28 修复未覆盖的另外 3 个位置。bash 3.2 macOS 的 `set -e` 传播 bug 出现在 populate_docker_ps_cache（`[ "$ZE_DOCKER_PS_CACHE_LOADED" = "1" ] && return 0` 在首次调用时失败，影响**每一次** fresh 安装）、find_existing_vaults（相同形式，影响没有先前 Obsidian vault 的用户），以及读取 CONFIG_ENV 的端口复用 for-loop（`__existing=$(grep | pipe)` 在 pipefail 下当 grep 找不到键时中断）。全部替换为 `if cmd; then return 0; fi` + pipe 上加 `|| true`。彩蛋：在 npm-wrapper 中加入 `prepublishOnly` 守卫 —— 检测到 2 个已知 pattern 的回归就拒绝 publish。
v0.1.282026-04-27
  • •🐛 macOS 上当第一个默认端口被占用时，安装程序会静默退出 —— 0.1.27 未能覆盖的严重 bug。check_port_free 使用了 `cmd; return $?` —— 在 macOS bash 3.2（/bin/bash 默认版本）中，set -e 会传播到 if 中调用的函数内部，这是与 bash 4+/5 不同的历史行为。当 python3 socket.bind 返回 != 0（端口被占）时，脚本在到达 return $? 之前就中止 —— 用户看到的是「端口扫描时静默退出」。Bash 4+ 没有这种行为，所以在 Linux 上能通过。修复：将所有 `cmd; return $?` 替换为 `if cmd; then return 0; else return 1; fi`（POSIX 形式，可在任何 bash 版本捕获 exit code）。已复现并验证。
v0.1.272026-04-27
  • •🐛 在 macOS 上 Docker Desktop 唤醒缓慢时端口预检查会卡住。0.1.26 中，is_our_container_on_port 每测试一个端口就调用一次 docker ps —— 而 find_free_port 每个 service 最多扫描 100 个备选 × 6 个 services = 最坏情况下达 600 次调用。在 Docker Desktop 处于 sleeping 状态的 macOS 上（每次调用 1-2 秒），pre-flight 会卡住 10-20 分钟。修复：docker ps 只缓存一次，通过 kill -0 轮询实现 3 秒超时（可移植到 bash 3.2 macOS，不依赖 coreutils 的 timeout）。彩蛋：find_free_port 中加入进度指示器（每测试 10 个端口打印一个 .），让其他人不再误以为卡死。
v0.1.262026-04-24
  • •🚀 install.sh 端口预检查：在启动 Redis/Neo4j/MinIO/Infinity 之前，验证默认端口是否空闲。如有冲突，建议下一个空闲端口（接受 Y/n/自定义端口）或通过 --auto-port 自动选择。compose.yml 现在读取 ${ZE_REDIS_PORT:-6379} 等，选择持久化到 ~/.config/zepapagaio/env。新命令 ze portas（别名 ports）列出所有当前端口，并高亮与默认不同的端口。
v0.1.252026-04-23
  • •✨ seeds/skills-library/ 中新增两个技能：bash-portability-macos（bash 脚本跨越 Linux↔macOS 时的 10 个具体陷阱——bash 3.2、BSD vs GNU、flock keg-only、get.docker.com、4 字节表情、locale 等）和 docker-multi-arch-and-rosetta（在 Apple Silicon 上处理仅 amd64 的镜像、docker manifest inspect、platform 覆盖、何时值得使用 Rosetta）。在任何全新安装中都可通过 skill-autopilot 使用。
v0.1.242026-04-23
  • •🔧 Apple Silicon 上 docker compose up 因为 michaelf34/infinity:latest-cpu 只有 amd64 版本而报错 'no matching manifest for linux/arm64/v8'。在 rag compose 中添加 platform: linux/amd64——ARM Mac 上 OrbStack/Docker Desktop 通过 Rosetta 2 运行，性能损失约 2-3 倍但对个人 vault 使用无感。
v0.1.232026-04-23
  • •🔧 pipx 未找到导致 macOS 上 testing 组件安装失败。现在调用 pkg_install pipx（mac 上用 brew，Linux 上用 apt/dnf/pacman），并为无包管理器的环境添加了 python3 -m pip install --user pipx + PATH 导出的回退方案。
v0.1.222026-04-22
  • •🔧 找到了 macOS 上横幅为空的根本原因：在 bash 3.2 的 LC_CTYPE=C 下直接赋值 4 字节 emoji 字面量（PARROT_INLINE="🦜"）会产生空字符串。🦜 是 U+1F99C（BMP 外，UTF-8 占 4 字节）——macOS 的 /bin/bash 在 locale 为 C 时无法保留这些字节于字面量赋值中。即使终端是 UTF-8，Node spawn 可能继承 LC_CTYPE=C。修复：通过 printf '\xf0\x9f\xa6\x9c'（原始十六进制字节）设置，与 locale 无关。
v0.1.212026-04-22
  • •🔧 macOS 上横幅将 $PARROT_INLINE 渲染为空。0.1.20 的检测使用了 inline elif case ... esac; then——这种语法 bash 3.2（仍是 macOS /bin/bash 的默认）解析行为不可预测。改写为 bash 3.2 兼容代码，并在顶部设置显式 > 回退以避免变量为空。
v0.1.202026-04-22
  • •🔧 即使在 Mac 上横幅也会退回到 ASCII 字符 > 而不是 🦜。旧检测要求 3 个条件同时满足（TTY + locale charmap + LANG），通过 npx 运行时 Node 的管道会破坏 isatty 检查。修复：macOS 始终使用表情（Terminal.app/iTerm2/Warp 自 ~2010 起原生渲染）；Linux 仍使用基于 locale 的检测。
v0.1.192026-04-22
  • •🔧 横幅显示 $PARROT_INLINE 字面量而不是 🦜 表情。heredoc 使用了单引号（<<'EOF'），阻止了 bash 变量展开。改为 <<EOF——现在可以正确渲染 🦜（不支持表情的终端显示为 >）。
v0.1.182026-04-22
  • •🔧 macOS：date -Iseconds 在 BSD date 上不存在。已替换为可移植的 date -u +%Y-%m-%dT%H:%M:%SZ（install.sh 和 scripts/ze）——之前会无声产生损坏的时间戳。
  • •🔧 macOS：sed -i 'X' file 与 BSD sed 不兼容（BSD 需要 sed -i '' 'X' file）。OBSIDIAN_API_KEY 改写在 macOS 会失败。改为 grep -v + mv，在 GNU 和 BSD 上行为一致。
v0.1.172026-04-22
  • •🔧 macOS：安装调用了 curl get.docker.com | sh，但它仅支持 Linux。现在检测 macOS 并提供两种选项：OrbStack（brew install --cask orbstack）或 Docker Desktop（brew install --cask docker）。两者在 macOS 上都无法完全自动化——都需要接受许可并启动 app 以启动守护进程。
  • •🔧 macOS：docker compose 插件检查试图下载 Linux 二进制。Docker Desktop 和 OrbStack 已内置 docker compose；如在 macOS 上不可用，消息现在提示「app 未运行，请打开 Docker Desktop/OrbStack」。
  • •🔧 macOS：'docker 未运行' 的回退调用了 systemctl start docker，macOS 没有此命令。消息已改为适合平台的提示。
v0.1.162026-04-22
  • •🔧 macOS Apple Silicon：安装时报错 'Falha ao instalar flock'。Homebrew 将 util-linux 作为 keg-only 安装（二进制在 /opt/homebrew/opt/util-linux/bin，不在 PATH 中）以避免与 macOS 原生 uuid.h 冲突。安装程序现在会检测 macOS 并将 keg-only 目录添加到会话 PATH。
  • •🔧 flock 现在是可选项。如果不可用，安装会继续并给出警告，vault-autocommit 将在无锁情况下运行——git commit 是原子操作，最坏情况仅是产生冗余提交。git、curl、python3 仍为硬性依赖。
v0.1.152026-04-22
  • •✨ 新的默认嵌入提供商：本地 Infinity。Docker 容器运行 intfloat/multilingual-e5-small（384 维，多语言），无需 API 密钥、零边际成本、离线运行。语义搜索现在默认 100% 本地。
  • •安装程序现在会询问使用哪个嵌入提供商：本地 Infinity（默认）或 OpenAI。如果选择 Infinity，OPENAI_API_KEY 变为可选（只有 multimodal 组件需要）。
  • •🔧 install.sh 现在对孤立容器具有幂等性——在 up 之前运行 docker compose down --remove-orphans。解决上次安装中途被中断时的名称冲突问题。
  • •🔧 server.py 不再自动为 ZE_EMBED_BASE_URL 追加 /v1。用户传入提供商期望的精确路径（Infinity v2: 不带 /v1；OpenAI: https://api.openai.com/v1）。可无障碍指向 Ollama、LocalAI 等其他 OpenAI 兼容后端。
v0.1.142026-04-22
  • •🔒 Security: Neo4j was previously bound to 0.0.0.0 despite docs stating loopback-only. Fixed in components/graph/docker-compose.yml — both ports (7474, 7687) now bind to 127.0.0.1, matching Redis and MinIO. Users running 0.1.13 or earlier on untrusted networks (cafés, coworking WiFi) should update immediately.
  • •Added SECURITY.md with coordinated disclosure channel, supported versions, and known limitations (including the user-wide hook scope caveat).
  • •Added CHANGELOG.md (this file) and repository/bugs fields in package.json for vendor auditability.
  • •🙏 Thanks to Pedro Ernesto (SOC 2 analyst) for the comprehensive security review that made this release possible.
v0.1.132026-04-13
  • •Python 3.14 compatibility: pysqlite3-binary now uses a conditional marker (`python_version < '3.14'`). On 3.14+ the code falls back to stdlib sqlite3 — modern Pythons already ship with enable_load_extension. Before this fix, initial vault indexing would fail on Macs running Python 3.14 because pysqlite3-binary only has wheels up to cp313.
v0.1.122026-04-13
  • •Neo4j auto-recovery fixed: component bind mount (not a named volume) is now actually cleaned when credentials go stale
  • •Post-boot auth check via cypher-shell: if the .env password does not match the one persisted in the volume (Neo4j ignores NEO4J_AUTH on non-empty volumes), the installer resets and restarts automatically
v0.1.112026-04-13
  • •Auto-recovery: install.sh detects containers in bad state (crashed, volumes with stale credentials) and cleans them up before reinstalling
v0.1.102026-04-13
  • •Neo4j password is now generated automatically (32 chars), like Redis and MinIO — no more confusing "will be created now" prompt
v0.1.92026-04-13
  • •Neo4j password validation: requires a minimum of 8 characters (Neo4j rejects shorter passwords and would crash the container)
v0.1.82026-04-13
  • •Neo4j startup timeout bumped from 60s to 180s (first boot on Mac Docker Desktop takes longer due to virtualization)
  • •Heartbeat every 30s while waiting for Neo4j, with dead-container detection to avoid unnecessary waits
v0.1.72026-04-13
  • •macOS bash 3.2 compatibility: fixed "unbound variable" error when no Obsidian vault was found
  • •Removed `local` usage outside functions that broke the multi-vault selection flow
v0.1.62026-04-13
  • •Parrot emoji 🦜 with automatic ASCII fallback for terminals without Unicode support
v0.1.52026-04-13
  • •Auto-install dependencies: Docker, uv, Claude Code, Node.js, Obsidian — all installed automatically if missing
  • •Automatic Obsidian vault creation: detects existing vaults or creates a new one with .obsidian/, plugins, git init, and welcome note
  • •Fix: pysqlite3-binary fallback for Pythons without enable_load_extension (common on Ubuntu via apt)
  • •Fix: autoMemoryDirectory now set in settings.json — Claude recognizes Zé after install
  • •Post-install screen redesigned: parrot ASCII art, step-by-step usage tutorial, and useful commands
  • •Default vault renamed to ~/cofre/ai-zepapagaio to avoid collision with existing vaults
v0.1.42026-04-12
  • •macOS compatibility: fallback for realpath -m (GNU/Linux-only flag)
v0.1.32026-04-12
  • •Install counter: anonymous ping at end of install, API on site, live display in hero
  • •Site favicon replaced with green parrot icon (was Vercel default)
  • •Nav reorganized: fewer items, no overflow, hamburger menu on mobile
  • •Architecture diagram in docs replaced from ASCII to styled HTML cards
  • •Docs and changelog are now fully multilingual (pt-BR + en complete)
v0.1.22026-04-12
  • •Installer now detects Obsidian and auto-registers the obsidian MCP server
  • •Skills section added to the website landing page
  • •Documentation and changelog pages added to the site
v0.1.12026-04-11
  • •60 seed skills shipped (API design, debugging, Next.js, security, and more)
  • •Auto-index images: hook automatically indexes relevant images without asking
  • •npm packaging — npx zepapagaio init now works out of the box
v0.1.0Phase 22026-04-11
  • •Unified Docker Compose — all services in a single compose.yml
  • •Cache layer: Redis for tool call, RAG, and GitHub API caching
  • •Storage layer: MinIO with buckets for images (30d TTL), test artifacts, and vault attachments
  • •Multimodal pipeline: screenshot → GPT-4o-mini description → vault note → RAG index
  • •Testing: Robot Framework + headless Playwright in isolated container
  • •New hooks: auto-extract graph entities, auto-index images
  • •New CLI commands: ze cache, ze imagem, ze testa, ze parar, ze voltar
v0.0.1Phase 12026-04-10
  • •vault-rag MCP: semantic search via OpenAI embeddings + sqlite-vec
  • •vault-graph MCP: Neo4j knowledge graph with Cypher queries
  • •Autocommit hook: automatic git commits on vault changes
  • •CLI ze: ze status, ze lembra, ze puxa, ze grafo, ze desinstala, ze doctor
  • •Seed memory files: initial notes for bootstrapping a new vault
  • •Obsidian MCP integration (optional, requires Local REST API plugin)