a4phone配置说明

本文章详解 a4phone 的配置文件与全部状态文件：~/.a4phone/ 目录下的 config.json 核心配置项、mode.json、last.json、daemon.json、日志文件、DSH 续聊队列与更新缓存，帮助你理解每个文件的作用与字段含义。

1. 目录总览

a4phone 全部状态文件统一存放在 ~/.a4phone/（%USERPROFILE%\.a4phone）目录下：

文件	用途	读写方
`config.json`	核心配置（话题、服务器、超时等）	配置读写
`mode.json`	当前交互模式（out / home）	模式管理
`last.json`	最近会话记录	Stop / turn/end 事件写入，续聊读取
`daemon.json`	守护进程信息（PID、日志路径、启动时间）	守护进程管理
`daemon.log`	守护进程运行日志	守护进程
`dsh-jobs/`	DSH 续聊文件队列（req / resp JSON）	a4p 与 dsh-hook 插件
`dsh-heartbeat.json`	DSH 插件心跳	dsh-hook 插件
`dsh-logs/`	DSH Hook 事件日志（JSONL）	dsh-hook 插件
`pending-batch.json`	续聊积压批次持久化	续聊守护进程
`update-cache.json`	版本更新检查缓存	更新检查

旧版本的家目录散点文件（.a4phone.json、.a4phone-mode.json 等）会在启动时自动迁移到 ~/.a4phone/（幂等，无旧文件时仅建目录）。

2. config.json 核心配置

~/.a4phone/config.json 由 a4p setup 生成，可手动编辑：

{
  "topic": "a4p-3f2a9c1b7d4e5f60",
  "server": "https://ntfy.sh",
  "timeout": 60,
  "planTimeout": 300,
  "resumeTimeout": 1800,
  "checkUpdates": true,
  "updateIntervalHours": 6
}

2.1 配置项说明

配置项	默认值	说明
`topic`	空	主话题名称（`a4p-xxxx`），手机订阅与推送的目标；置空则关闭手机推送
`server`	`https://ntfy.sh`	ntfy 服务器地址，可改为自建服务（如 `http://192.168.1.10:8080`）
`timeout`	`60`	手机交互（提问/权限）超时秒数，超时回退终端
`planTimeout`	`300`	计划确认（ExitPlanMode）超时秒数
`resumeTimeout`	`1800`	单轮续聊超时秒数（默认 30 分钟）
`checkUpdates`	`true`	版本更新检查开关，`false` 关闭
`updateIntervalHours`	`6`	更新检查间隔（小时）

3. 状态文件详解

3.1 mode.json 当前模式

{
  "mode": "out"
}

out 外出模式（手机优先）/ home 终端优先模式（默认）。由 a4p out / a4p home 写入，Hook 每次事件重新读取，即时生效。

3.2 last.json 最近会话

Stop 事件（或 DSH turn/end）触发时写入，续聊路由的依据：

{
  "session_id": "ab12cd34ef56...",
  "cwd": "C:\\my-project",
  "agent": "Claude Code",
  "transcript_path": "C:\\Users\\xxx\\.claude\\projects\\...\\xxx.jsonl",
  "ts": 1755324000000
}

字段	说明
`session_id`	最近会话 ID
`cwd`	会话工作目录
`agent`	来源 Agent（Claude Code / Codex / DSH）
`transcript_path`	会话记录文件路径（Codex fork 后会更新）
`ts`	记录时间戳（毫秒）

3.3 daemon.json 守护进程信息

{
  "pid": 12345,
  "logPath": "C:\\Users\\xxx\\.a4phone\\daemon.log",
  "startedAt": "2026-08-16T10:00:00.000Z"
}

由 a4p listen 写入，--stop / --status / uninstall 读取。

4. DSH 相关文件

4.1 dsh-jobs/ 续聊队列

a4p 与 dsh-hook 插件之间的文件队列协议：

文件	写入方	说明
`req-<id>.json`	a4p	续聊请求：`{ id, sessionId?, text, ts }`，原子写入
`resp-<id>.json`	插件	续聊响应：`{ id, ok, reply?, reasonKind?, error?, sessionId? }`，读走后删除

4.2 dsh-heartbeat.json 心跳

{
  "alive": true,
  "ts": 1755324000000
}

dsh-hook 插件每次轮询刷新，a4p 据此判断 dsh web 是否在运行（心跳超过 10 秒视为未运行，续聊快速失败）。

4.3 dsh-logs/ Hook 事件日志

文件	记录内容
`task-complete.jsonl`	任务完成事件（会话、轮次、reasonKind）
`question-asked.jsonl`	提问工具调用（问题与选项）
`permission-request.jsonl`	审批请求与决策

5. 续聊与更新缓存

5.1 pending-batch.json 积压批次

续聊守护进程忙时到达的手机消息合并为一个批次持久化到该文件；守护进程重启/崩溃后自动恢复处理，不丢消息。批次取走后文件删除（at-most-once）。

5.2 update-cache.json 更新缓存

{
  "lastCheck": 1755324000000,
  "knownLatest": "1.4.2",
  "version": "1.3.0"
}

字段	说明
`lastCheck`	上次检查时间（限频）
`knownLatest`	已提醒过的最新版本（去重，同一版本只提醒一次）
`version`	写入时的本地版本（1.4.2 起，本地升级后忽略限频立即检查）

6. 常见问题

问：如何切换到自建 ntfy 服务器？

答：编辑 ~/.a4phone/config.json 的 server 字段为自建服务地址，如 http://192.168.1.10:8080，手机订阅地址同步使用该服务器。

问：如何关闭手机推送只保留电脑弹窗？

答：把 config.json 的 topic 置空，或运行 a4p uninstall 完全卸载。

问：配置文件损坏会怎样？

答：读取失败时按默认值兜底（topic 为空、服务器 ntfy.sh、各超时默认值），行为安全，不会崩溃。

问：如何清空最近会话记录？

答：删除 ~/.a4phone/last.json 即可，续聊会提示"暂无最近会话"。