开箱配置、沙箱构建与 Playground 稳定性问题整理

[darkkid0]

背景

本地部署和使用过程中发现几类问题都指向同一个方向：开箱配置、跨平台构建、Playground 前端容错和运行产物管理还可以更稳一些。为了避免拆成太多 issue，这里合并成一个跟踪项，后续实现可以按 checklist 分 PR 处理。

待处理项

• 对齐数据库与 Compose 默认配置
• 让 sandbox Dockerfile 支持 arm64/Apple Silicon，或明确文档说明 amd64-only
• Mermaid 渲染失败时应优雅降级
• 改善运行中 subagent 时的角色切换和侧栏状态体验
• 完善 .gitignore，忽略轮转日志和 tiktoken cache

1. 数据库与 Compose 默认配置不一致

当前数据库默认配置、示例配置和 compose 暴露端口容易产生混淆：

• config.py 中 DatabaseConfig 的默认 host/port 会直接进入 database.init_engine 拼接 DSN。
• .z3r0/config.json.example、docker-compose.dev.yml、docker-compose.prod.yml 对 host/port 的语义需要保持一致。
• dev compose 里 pgAdmin 监听 5433，如果应用默认数据库端口也指向 5433，容易连到 pgAdmin 而不是 Postgres。

建议：明确本机运行、compose 内部访问、compose 暴露到宿主机三种场景的默认值，并同步 README / example config。

2. Sandbox Dockerfile 存在 amd64/x64 假设

sandbox/Dockerfile 中部分第三方工具下载地址硬编码了 x64/amd64 artifact，例如 agent-browser、observer_ward、projectdiscovery/httpx 等。在 Apple Silicon 或 arm64 Linux 环境构建时会失败或拿到错误架构二进制。

建议：

• 使用 Docker build 的 TARGETARCH 选择下载 artifact。
• 对没有 arm64 artifact 的工具给出明确错误或文档说明。
• Java 路径等也避免硬编码 amd64-only 路径，或提供兼容 symlink。

3. Mermaid 渲染失败应优雅降级

Playground 会把 markdown 中的 Mermaid 代码块渲染成图。如果模型生成的 Mermaid 语法不严格，前端应该显示错误状态和原始源码，而不是影响聊天内容的可用性。

建议：

• Mermaid renderer 捕获同步和异步渲染异常。
• 开启 Mermaid 的错误渲染抑制，避免额外 DOM/error 注入影响布局。
• Agent diagram instructions 中补充常见 Mermaid 语法约束，例如 node id、label quote、箭头语法等。

4. 运行中 subagent 的侧栏和角色切换体验不稳定

当 subagent 正在运行时，切换主 agent 角色可能造成上下文/归属混乱；同时用户关闭 subagent panel 后，缺少明显入口恢复查看，刷新或切换 session 后选择状态也容易丢失。

建议：

• 只要存在 running subagent，就禁用角色切换，并给出明确 tooltip。
• 在顶部操作区提供 Subagents 入口，允许重新打开/隐藏 panel。
• 按 session 记住当前选中的 subagent，刷新后尽量恢复。
• 对关闭时的自动弹出抑制逻辑保持可预期，避免刚关闭又被运行中任务自动打开。

5. 运行产物没有完整忽略

.gitignore 当前有 *.log，但不能匹配形如 .z3r0/app.log.2026-06-13 的轮转日志；.z3r0/tiktoken_cache/ 也会作为 untracked 文件出现。

建议增加忽略规则，例如：

.z3r0/app.log*
.z3r0/tiktoken_cache/

这可以减少本地运行后的 git status 噪音，也避免误提交运行缓存。