a4phone项目总览与快速开始

a4phone 是一个通过 ntfy.sh 实现 Claude Code / Codex / DSH（DeepSeek Harness）远程手机交互的开源 npm 包：任务完成时在电脑弹窗并把 AI 最后输出的一段话推送到手机；AI 提问或请求权限时在手机上点选按钮或直接输入文字作答；出门在外时向手机发送文字即可远程续聊最近会话，形成完整的远程对话闭环。本文章为文档库入口，概述项目背景、功能全景、安装与快速开始，并给出各功能文档的导航。

源码仓库

• a4phone 源码（GitHub），本项目的开源仓库，可查看源码、提交 Issue 或参与贡献。
• a4phone npm 包，通过 npm 安装使用。

1. 项目简介

a4phone 以 a4p 为命令行入口，通过 Hook（Claude Code / Codex）与 Cordis 插件（DSH）拦截 AI 助手的会话事件，借助免费的 ntfy.sh 推送服务在手机与电脑之间传递通知、提问、权限决策与续聊消息。整个项目零第三方依赖（仅使用 ntfy.sh 免费服务，不依赖 Google 服务），安装一个包、运行一条命令即可完成全部配置。

1.1 项目定位

1.2 功能全景

安装与使用教程可参考仓库中的 一键配置DeepSeek Harness等Agent桌面、手机提醒教程，本文档库侧重功能介绍与机制解析。

2. 安装

a4phone 通过 npm 全局安装，一条命令即可完成：

npm install -g a4phone

2.1 安装前置条件

2.2 验证安装

a4p --version    # 输出当前版本号，如 1.4.2
a4p help         # 显示全部命令帮助

3. 快速开始

3.1 运行安装引导

a4p setup

a4p setup 会自动完成以下全部配置：

1. 生成独一无二的话题名称（如 a4p-xxxx），写入 ~/.a4phone/config.json
2. 在 ~/.claude/settings.json 注册三个 Hook（Stop / AskUserQuestion / PermissionRequest）
3. 在 ~/.codex/config.toml 追加 Codex Hook 配置（保留原有设置）
4. 检测到 DSH 环境（~/.dsh/profiles/web 存在）时，把内置 dsh-hook 插件挂载到 cordis.patch.yml
5. 默认启动续聊守护进程（a4p listen 后台运行）
6. 默认注册 Windows 开机自启（启动文件夹写入隐藏 VBS）
7. 在终端显示订阅二维码

3.2 手机订阅话题

用手机 ntfy App 扫描终端显示的二维码，或手动输入话题名称订阅。建议在订阅设置中开启"即时交付"，否则消息需要手动刷新才能收到。

3.3 切换外出模式

a4p out      # 外出模式：提问/权限请求优先推送手机
a4p status   # 查看当前模式

3.4 发送测试通知

a4p test

手机收到"测试通知：如果手机收到，配置正常。"即表示配置成功。

4. 工作原理

4.1 交互总流程

4.2 远程续聊闭环

5. 状态文件一览

a4phone 全部状态文件统一存放在 ~/.a4phone/ 目录：

详细字段说明见配置说明。

6. 文档导航