🏮 蓬莱 PenglaiAgent 0.3.1 — 里程碑版本

自托管 AI 管家，住在飞书、微信和终端里。Mac/Windows 原生桌面客户端 + Runtime Hub 中枢 + 自动升级全链路。

PenglaiAgent 0.3.1 — self-hosted AI butler living in Feishu, WeChat and your terminal. Native Mac/Windows desktop clients, Runtime Hub execution layer, and a complete auto-update pipeline.

✨ 这个版本为什么重要 / Why this release matters

0.3.1 是里程碑级别的发布：不只是修 bug，更是让蓬莱可持续升级、可安全迁移、可长期维护的底层基建闭环。

0.3.1 is a milestone release: it's not just bug fixes — it closes the loop on upgradeable, migratable, maintainable infrastructure.

三大支柱 / Three pillars:

支柱 Pillar	你能得到什么 What you get
🔄 迁移机制 Migration	从 0.2.x / 0.3.0 升级不丢数据，换机可备份恢复
🚀 自动升级链路 Auto-update	桌面应用一键自升级，未来发版只需推 tag
🧩 版本号动态化 Dynamic versioning	全仓库不再硬编码版本号，发版只改一处

🆕 全新功能 / New features

1. 数据备份 / 恢复 / 旧版清理三件套

```bash
penglai backup # 完整备份 mykey + memory + sqlite + wxbot + 桌面配置
penglai restore [路径] # 从备份恢复（默认最近一次）
penglai uninstall-legacy # 清理旧版本 launchd/systemd 服务 + 提示删旧目录
```

Full data backup / restore / legacy cleanup — never lose your config when upgrading or switching machines.

2. `penglai setup --only` 局部补配

只想重配飞书，不想重走大模型 API Key 全流程？现在可以：

```bash
penglai setup --only feishu # 只配飞书，其余原样保留
penglai setup --only llm # 只换大模型
penglai setup --only wechat # 只配微信
penglai setup --only identity # 只改管家名/称呼
penglai setup --only channels # 多渠道选择
penglai setup --only abilities # 能力面板
penglai setup --only companion # 切换主动陪伴开关
```

支持 7 个模块独立补配，其余配置原子保留。（修复 issue #2）

3. `penglai config` 原子配置管理

```bash
penglai config backup # 原子备份 mykey.py
penglai config restore [名称] # 恢复（恢复前自动再存档一次当前配置）
penglai config status --json # 配置概览（供桌面端调用）
```

4. 桌面端 9 模块控制面 + 双层升级 UI

Chat / Runs / Channels / Abilities / Companion / Diagnostics / Logs / Update / Security 九个模块。升级入口两层：主界面 + 配置向导界面（万一卡在配置界面也能升级）。

5. Runtime Hub 稳态化

TaskRun 状态机闭合：`WAITING_PERMISSION → RUNNING → SUCCEEDED`
崩溃恢复：重启时自动把僵尸 TaskRun 标记 failed
SQLite TOCTOU 修复（`BEGIN IMMEDIATE`）
owner 消息走 control API，多入口共享同一个 GA 会话

6. 主动陪伴四档模式

`off` / `quiet` / `present` / `active` 四档差异化；active 模式连续 SILENT 自动升级冷却；companion 事件在下一轮 prompt 可见（context 闭环）。

7. doctor 诊断闭环

每个红项都附带"下一步命令"，不再只说有问题。新增旧版本残留进程检测 + setup 完成后自动冒烟验证 LLM 可用性。

🔧 重要修复 / Important fixes

P0 级（致命 bug，对抗路审计发现）

自动升级永远显示"无更新"：Rust 返回 `has_update`，前端检查 `available`，字段名不匹配。已统一修复。
首次安装后卡在 bootstrap 模式：`start_bridge_with_config` 检测到 bridge 已运行就跳过 spawn，导致运行时端点 503。现在会检测 bootstrap 模式并先停后启。
workflow 版本号硬编码 40+ 处：tag 触发、if 条件、文件名全部硬编码 v0.3.1，未来发版要改几十处。已全部动态化。

P1 级（体验问题）

飞书扫码 poll 无 error 分支：poll 异常时前端无限轮询无反馈。已加 error 分支 + 清晰提示。
XSS 防护不全：部分后端返回值直接插入 innerHTML。已全部改用 `escHtml()`。
setup 窗口误退出：主窗口未就绪时隐藏 setup 会导致应用退出。已改为保守退出逻辑。
Windows 上 mykey.py 变只读：`os.chmod(0o600)` 在 Windows 上会塌缩成 read-only。已跨平台适配。
Mac DMG 报"已损坏"：Tauri 默认 linker-signed app 的 Sealed Resources=none。CI 已加 adhoc 重签名 + 重新生成 updater 产物。

CI/发布链路修复

`PENGLAI_VERSION=0.0.0` 导致 main CI 失败：非 tag 构建时版本号硬编码为 0.0.0，与 Tauri 实际产物版本号不匹配。已改为从 Cargo.toml 动态读取。
latest.json URL 包含换行符：`jq -Rs . <<<"$url"` 的 bash here-string 陷阱，URL 末尾带 `\n` 导致升级请求失败。已改为 `printf '%s' "$url" | jq -Rs .`。
`github.ref_name[1:]` 表达式无效：GitHub Actions 不支持字符串切片，返回 null。已改为 shell `${GITHUB_REF_NAME#v}`。

🏗️ 底层基建里程碑 / Infrastructure milestones

迁移机制 —— 可升级、可换机、可回退

三层兜底，确保数据不丢：

用户主动层：`penglai backup/restore` 完整数据备份恢复
安装器防御层：install.sh / install.ps1 在 `rm -rf` 前自动备份用户数据，解压后恢复；版本不可识别时拒绝继续
旧版本清理层：`penglai uninstall-legacy` 清服务 + 桌面端 `detect_legacy_penglai` 向导启动前检测提示

迁移流程：旧版本 `penglai backup` → 安装 0.3.1 → 新版本 `penglai restore` →（可选）`penglai uninstall-legacy`

自动升级链路 —— 六道关卡全通

未来发版只需 `git push origin v0.3.x`，CI 自动完成：

用 `TAURI_SIGNING_PRIVATE_KEY` 签名升级包（.app.tar.gz / -setup.exe）
Mac adhoc 重签名后重新生成 updater 产物（修复"damaged"）
自动生成 `latest.json` 发布到 Release
前端 `check_app_update` / `install_app_update` 调 tauri-plugin-updater
fallback.html 配置界面也能升级
运行时层 `penglai update --apply` 独立走 git ff-only + 预检 + 健康检查 + 失败回滚

版本号动态化 —— 未来发版只改一处

Python 层：`penglai_runtime/init.py` 的 `VERSION` 常量（唯一定义点）
桌面端：tauri.conf.json / Cargo.toml / package.json 三处
CI：tag 触发时 `${GITHUB_REF_NAME#v}` 自动提取；非 tag 时从 Cargo.toml 读取
tag 触发条件：`v*` 支持所有未来版本号，无需每次改 workflow

📥 安装 / Install

桌面端（推荐新用户）/ Desktop (recommended)

macOS (Apple Silicon)：下载 DMG，拖到 Applications。首次打开：系统设置 → 隐私与安全性 → 仍要打开。
Windows x64：下载安装包运行。SmartScreen → 更多信息 → 仍要运行。

命令行 / Command line

```bash
curl -fsSL https://raw.githubusercontent.com/kevinchennewbee/PenglaiAgent/main/install.sh | sh
```

从 0.3.0 升级 / Upgrade from 0.3.0

```bash
penglai update --apply # 自动预检 + 后台重启 + 失败回滚
```

从 0.2.x 迁移 / Migrate from 0.2.x

```bash

旧版本上

penglai backup

安装 0.3.1（install 脚本会自动防御性备份兜底）

curl -fsSL https://raw.githubusercontent.com/kevinchennewbee/PenglaiAgent/main/install.sh | sh

新版本上

penglai restore
penglai uninstall-legacy # 可选：清理旧服务
```

⚠️ 已知限制 / Known limitations

代码签名：macOS DMG 和 Windows 安装包未经 Apple Developer ID / Windows Authenticode 签名（社区项目无 Developer Program 会员）。Gatekeeper/SmartScreen 首次会拦截，手动"仍要打开"即可。Tauri 应用内的自动升级签名（ed25519）已配置，应用内自升级可校验安装。
平台支持：macOS 仅 Apple Silicon（M 系列），Intel Mac 不支持。Docker 自 0.3.0 起全面撤出。
桌面端架构：桌面端必须与 penglai 安装在同一台电脑上，不支持连接远程主机上的 penglai。
升级路径：从 0.2.x 升级建议用上面的迁移流程，不建议直接 `penglai update`。
IM 渠道：飞书是验证最充分的渠道，其余渠道为实验性支持。

🙏 致谢 / Thanks

感谢所有提 issue、反馈问题、参与测试的用户。特别感谢 @larrylinli 提出的三个 issue（#2 #3 #4），推动了 `setup --only` 局部补配、飞书接入诊断、桌面端架构说明的改进。

完整变更记录 / Full changelog：v0.3.0...v0.3.1

PenglaiAgent 0.3.0 — a self-hosted AI Runtime Hub for ordinary users.

Bring a working, listening, speaking agent to your desktop, Feishu, WeChat, terminal, and voice. Memory, channel credentials, logs, and local voice processing stay on your own machine by default.

What's new in 0.3.0

Runtime Hub: Unified execution layer for all channels (Feishu, WeChat, terminal, desktop). FIFO queuing, task auditing, session persistence.
Desktop clients: Native Mac (Apple Silicon) and Windows (x64) apps with complete setup wizard, multi-session chat, system tray, update detection, channel/ability management.
Complete setup wizard: Language → LLM selection (12 providers with live connectivity test) → IM channel setup (Feishu QR scan, WeChat, etc.) → Identity naming → Capability panel (voice/TTS/companion/critic/intel) → Config writing and launch verification.
Local voice loop: The FunASR / SenseVoice line lets Penglai listen locally (speech transcription, emotion labels, acoustic events). MOSS-TTS-Nano adds local speaking, turning text replies into speech. Both sides can run on local CPU, and voice data does not need to leave your machine.
Update mechanism: penglai update --check and one-click --apply with automatic backup and rollback.
Memory system: 4-layer architecture (L1 index → L2 facts → L3 SOPs → L4 session logs), action-verified only.
Supplementary config: Channel and ability management panel in desktop settings — re-enable channels or abilities post-install without re-running the full wizard.
Doctor diagnostics: Full system health check integrated into both CLI and desktop.

Install

Desktop (recommended for new users)

macOS: Download the DMG, drag to Applications. On first open, go to System Settings → Privacy & Security → Open Anyway.
Windows: Download the installer, run it. SmartScreen → More Info → Run Anyway.

Command line

curl -fsSL https://raw.githubusercontent.com/kevinchennewbee/PenglaiAgent/main/install.sh | sh

Important notes

macOS and Windows installers are unsigned. You will need to bypass Gatekeeper/SmartScreen. This is because we are a community project without Apple Developer Program membership.
Apple Silicon only for macOS. Intel Mac not supported.
Upgrade from 0.2.x is not guaranteed stable; fresh install recommended.
Feishu is the most validated IM channel. Other channels are progressively field-tested.
Docker is no longer supported in 0.3.0. There is no Dockerfile, docker-compose, docker-install, GHCR image, or container deployment path.

Releases: kevinchennewbee/PenglaiAgent

PenglaiAgent 0.3.1