a4phone版本更新说明

本文章以流水线式记录 a4phone 从 1.0.0 到当前版本（1.6.0）的完整演进过程：按版本从新到旧逐版本列出新增功能（feat）、问题修复（fix）与行为变化，并标注每个版本引入的能力所对应的功能文档，方便按版本追溯功能来源。

1. 版本演进总览

2. 版本明细

1.6.0 — ZCode 支持与桌面弹窗守护进程代发（2026-09-01）

• 新增：ZCode（智谱桌面端）完整支持——a4p setup 自动把三个 Hook（Stop / AskUserQuestion / PermissionRequest）写入 ~/.zcode/cli/config.json（事件块挂在 hooks.events 下并显式开启 hooks.enabled，保留原有 MCP、插件等设置）；a4p hook zcode 标识触发方，通知标题动态显示 ZCode
• 新增：ZCode 远程续聊——headless 调用 zcode.cjs --prompt <消息> --resume <会话> --json --mode yolo，从 JSON 输出的 response 字段取回复推回手机
• 新增：ZCode 续聊模型跟随——续聊前从会话 rollout 记录读取实际使用的模型并与 provider 定义一并同步写入 ~/.zcode/cli/config.json，桌面端切换模型后续聊自动跟随；a4p setup 时写入默认模型配置
• 新增：桌面弹窗改由常驻守护进程代发——hook 进程（尤其 ZCode）退出时会被执行端口杀掉整棵进程树，fire-and-forget 的气泡来不及渲染；hook 原子写请求文件 ~/.a4phone/notify-queue/，守护进程每 2 秒扫描代发，停运期间积压超过 60 秒自动丢弃，守护进程不在时回退直接弹窗
• 修复：系统通知弹窗加 windowsHide，消除每次弹气泡时闪出的 PowerShell 黑窗
• 变更：AskUserQuestion 触发的 PermissionRequest 跳过桌面通知（ZCode 对一次提问会同时触发 PreToolUse 与 PermissionRequest 两次 hook，避免重复通知与误导文案）

对应文档：任务完成通知、AI提问交互、权限请求交互、远程续聊、后台守护进程与开机自启、命令参考。

1.5.2 — DSH workspace 记账缺陷文档化（2026-08-27）

• 修复：标注 DSH workspace 记账归组缺陷为临时外部方案——dsh-hook 插件提供"孤儿会话自愈"兜底：把已持久化但未计入任何 workspace 项目的会话按 header.cwd 归入对应项目（必要时自动新建 workspace 记录），幂等只补缺口，可经插件配置 healWorkspaces: false 关闭；该方案是 DSH 官方修复记账缺陷前的过渡措施，官方修复后应评估移除

对应文档：DSH支持与插件挂载。

1.5.1 — DSH 挂载模板修复（2026-08-26）

• 修复：DSH 挂载移除出厂模板 [] 占位符——默认模板占位符 [] 本身就是一个完整的 YAML 文档，原样保留再往后追加条目会变成双 YAML 文档，DSH 启动解析报错导致 profile 启动失败；追加前移除占位符

对应文档：DSH支持与插件挂载。

1.5.0 — DSH 多 profile 自动发现与批量挂载 + 桌面通知（2026-08-25）

• 新增：DSH 多 profile 自动发现与批量挂载——a4p setup 扫描 ~/.dsh/profiles/ 下所有含 cordis.yml 的 profile（web / tui / dsh-tui 及后续新装变体）逐个挂载 dsh-hook 插件，不再只处理 web
• 新增：守护进程周期补挂——a4p listen 启动时及每 10 分钟重扫 profiles，新装 profile 自动补挂，无需重跑 setup
• 新增：提问 / 权限请求补桌面通知——Claude Code / Codex / ZCode 与 DSH 的提问、权限请求触发时先弹桌面通知（home 模式同样提示）

对应文档：DSH支持与插件挂载、后台守护进程与开机自启、AI提问交互、权限请求交互。

1.4.3 — 审查 6 项修复（2026-08-16）

• 修复：更新检查失败背退限频 + 命令短超时——查询失败也记录检查时间（按 30 分钟背退重试），离线/慢网下不再每次命令都重试网络；命令级检查超时降至 3 秒，避免挂起的 fetch 拖住命令退出
• 修复：DSH 续聊失败推手机——心跳过期、超时、插件中途退出三个分支均推送"续聊失败"及原因到手机，不再干等无反馈
• 修复：DSH subagent 完成不推送——仅顶层会话推送任务完成通知，子代理轮次只记日志
• 修复：DSH 无选项提问跳过——提问无选项时无法手机作答，跳过推送直接回退终端
• 修复：积压批次 at-most-once——批次一经交给续聊管线即删除持久化文件（取批即删），进程崩溃不会导致同一条手机消息重复注入会话

对应文档：自动更新提醒、DSH支持与插件挂载、任务完成通知、AI提问交互、远程续聊。

1.4.2 — 浏览器链接兜底 + 更新检查修复（2026-08-16）

• 新增：提问推送附带响应话题浏览器链接兜底——未订阅响应话题的用户也可打开网页版直接回复（自由作答 / 编号回复均支持）
• 修复：更新检查本地版本升级后忽略限频立即检查——避免旧缓存把升级后的首次检查推迟一整个间隔（缓存新增 version 字段）

对应文档：AI提问交互、自动更新提醒。

1.4.1 — 纯数字回复修复（2026-08-16）

• 修复：纯数字自由文本（如编号回复「4」）被 JSON.parse 误判为 JSON 对象而丢失——ntfy 消息解析区分 JSON 对象与原始值，纯数字按文本返回

对应文档：AI提问交互。

1.4.0 — 默认守护进程 + 开机自启（2026-08-16）

• 新增：a4p setup 默认启动续聊守护进程（无需手动 a4p listen）
• 新增：Windows 开机自启——启动文件夹写入隐藏 VBS，登录时自动运行守护进程；新命令 a4p autostart（--on / --off / 状态），无需管理员权限
• 新增：更新提醒命令级也推手机——a4p status / a4p resume 等命令发现新版本时终端提示 + 手机推送（与守护进程共用去重缓存）
• 变更：a4p uninstall 一并移除守护进程与开机自启

对应文档：后台守护进程与开机自启、自动更新提醒。

1.3.0 — 自动更新提醒（2026-08-16）

• 新增：版本更新检查——守护进程启动时及每 updateIntervalHours 小时（默认 6）查询 npm registry（npmmirror 优先、官方兜底），发现新版本推送手机提醒
• 新增：限频与去重（同一新版本只提醒一次，缓存 ~/.a4phone/update-cache.json）
• 新增：checkUpdates / updateIntervalHours 配置项

对应文档：自动更新提醒。

1.2.1 — 续聊积压合并与持久化（2026-08-15）

• 修复：续聊积压合并——忙时到达的手机消息合并为一个批次一次性续聊（不再逐条排队），任意数量积压最多只多产生一个续聊轮次
• 新增：积压批次持久化到 ~/.a4phone/pending-batch.json，守护进程重启/崩溃后自动恢复，不丢消息
• 修复：排空循环修复，批次处理不会停顿

对应文档：远程续聊。

1.2.0 — DSH 会话远程续聊（2026-08-15）

• 新增：DSH 远程续聊——手机文字经文件队列交给 dsh web 进程内的插件，agent.followup 直接注入桌面正在运行的同一个会话，手机消息与 AI 回复实时出现在桌面会话里，无会话锁冲突
• 新增：文件队列协议（~/.a4phone/dsh-jobs/）与心跳检测（dsh-heartbeat.json），dsh web 未运行快速失败而非干等超时

对应文档：DSH支持与插件挂载。

1.1.7 — 多选项降级作答（2026-08-15）

• 修复：提问选项超过 3 个时（ntfy 按钮上限）自动降级为文本编号列表 + 文字作答，回复对应编号即可选中选项

对应文档：AI提问交互。

1.1.6 — DSH 插件挂载（2026-08-14）

• 新增：a4p setup 检测到 DSH 环境时自动把内置 dsh-hook 插件挂载到 web profile 的 cordis.patch.yml，DeepSeek Harness 获得任务完成通知、提问作答、权限审批手机交互
• 新增：Codex 续聊 fork——会话被窗口占用时自动 fork 成新线程续聊，无需关闭原窗口
• 新增：状态文件目录化（统一迁移到 ~/.a4phone/）、卸载清理

对应文档：DSH支持与插件挂载。

1.1.5 — 远程续聊主话题 + 后台守护进程（2026-08-08）

远程续聊能力正式成型：

• 新增：续聊守护进程从独立 {topic}-cmd 话题改为监听主话题——手机向订阅的通知话题发文字即可续聊，无需额外话题
• 新增：a4p listen 后台守护进程模式（无窗口、日志写文件）
• 新增：Claude Code 续聊（claude --resume <会话> --continue -p）与 Codex 续聊（codex exec resume）

对应文档：远程续聊、后台守护进程与开机自启。

1.1.x — Codex 支持与包名整理（2026-08-06）

• 新增：a4p setup 自动写入 Codex 配置（~/.codex/config.toml），支持 Codex 的 request_user_input 提问与 Hook 触发
• 新增：a4p setup 报告 Claude Code 与 Codex 双向配置状态
• 新增：通知标题按触发方动态显示（Claude Code / Codex）
• 新增：a4p --version 与 a4p help 命令
• 变更：包名曾尝试改为 @eogee/a4phone 作用域包，最终回退为 a4phone 并发布 1.1.3
• 修复：AskUserQuestion 触发的 PermissionRequest 直接放行，不再推送冗余原始 JSON

1.0.0 — 远程手机交互初版（2026-08-06）

a4phone 首个版本，基于 Claude Code Hook 实现远程手机交互：

• 新增：a4p setup 安装引导，生成话题、注册 Claude Code Hook、显示订阅二维码
• 新增：任务完成通知——Stop 事件触发电脑弹窗 + 手机推送（含 AI 最后输出）
• 新增：AI 提问交互——AskUserQuestion 推送到手机点选作答
• 新增：权限请求交互——PermissionRequest 手机 Approve / Deny
• 新增：a4p out / a4p home 双模式切换

对应文档：任务完成通知、AI提问交互、权限请求交互、双模式切换。

3. 升级说明

• 升级命令：npm install -g a4phone
• 升级后建议重启续聊守护进程：a4p listen --stop && a4p listen
• 自 1.6.0 起桌面弹窗由守护进程从 ~/.a4phone/notify-queue/ 代发，请确保守护进程在运行（a4p listen --status 查看）；未运行时自动回退为直接弹窗
• ZCode 支持：重新执行 a4p setup 会写入 ZCode Hook 与默认模型配置（需 ZCode 桌面端已安装），重启 ZCode 会话后 Hook 生效
• 若插件代码有更新（DSH），建议重启 dsh web 使新插件代码生效
• 配置与状态文件向后兼容，升级无需重新配置；新功能（如开机自启、更新提醒）随新版本代码生效