@tencent/easy-dev

基于 ACP 协议的多仓 AI Coding 交互层。一个 Node 服务同时托管 前端 UI 与 API / WebSocket（单端口），并调用 Cursor、Codex、Claude Code 等 CLI Agent 完成 Coding 任务。

快速开始

# 内网（腾讯 npm）
npx @tencent/easy-dev start

# 外网（npmjs.com）
npx @alderzhang/easy-dev start

# 指定端口并启动后打开浏览器
npx @tencent/easy-dev start --port 9000 --open
# 或：npx @alderzhang/easy-dev start --port 9000 --open

# 中继 HTTPS：命令行或 ~/.easy-dev/config.json（不必再记一长串 ACP_*）
npx @tencent/easy-dev start --exposure relay --relay-url https://easy-dev-hub.woa.com:9444

# 查看状态 / 日志 / 重启 / 停止
npx @tencent/easy-dev status
npx @tencent/easy-dev logs -f
npx @tencent/easy-dev restart
npx @tencent/easy-dev stop

启动后访问终端打印的地址（默认 http://localhost:8787）。

命令

| 命令 | 说明 | | --- | --- | | start | 启动服务（默认后台；内置 supervisor，server 崩溃后自动重启） | | stop | 停止服务（结束 supervisor，不再拉起） | | restart | 重启服务 | | status | 查看运行状态（含健康检查、supervisor / server pid） | | logs | 查看服务日志 | | clone | 从 meta 仓一键导入项目（未全局安装时会先 npm install -g） |

配置优先级：命令行 > 环境变量 > <dataDir>/config.json > 内置默认。示例见仓库根 config.example.json；也可用 --config / EASY_DEV_CONFIG 指定文件。

start / restart 选项

| 选项 | 默认值 | 说明 | | --- | --- | --- | | --config <路径> | <dataDir>/config.json | JSON 配置文件 | | -p, --port <端口> | 8787（或 PORT） | 监听端口 | | -H, --host <地址> | 0.0.0.0（或 HOST；relay 未显式指定时收回 127.0.0.1） | 监听地址 | | -d, --data-dir <目录> | ~/.easy-dev（或 ACP_SRV_ROOT） | 数据目录（DB / worktree / meta 仓 / 日志 / PID） | | --exposure <模式> | none（或 ACP_EXPOSURE_MODE） | 暴露适配器：none / relay | | --relay-url <URL> | — | Relay Server 隧道入口（ACP_RELAY_URL） | | --relay-ca <路径> | — | 中继信任锚 CA（ACP_RELAY_CA） | | --relay-name <前缀> | — | 实例可读前缀（ACP_RELAY_NAME） | | --set <key=value> | — | 覆盖任意配置项（点路径，如 exposure.relay.poolSize=16） | | -f, --foreground | — | 前台运行（supervisor 占当前进程，适合调试 / 容器） | | -o, --open | — | 启动后自动打开浏览器 | | --tls-cert <路径> | — | HTTPS 证书 PEM（须与 --tls-key 成对） | | --tls-key <路径> | — | HTTPS 私钥 PEM | | --tls-ca <路径> | — | 可选 CA / 中间证书 PEM | | --tls / --https | — | 启用数据目录 certs/ 中的托管证书 |

自动重启：start 拉起常驻 supervisor，由其管理 server 子进程。原生崩溃（如 SIGABRT）也会被感知并按退避策略重启；5 分钟内连续崩溃过多会熔断退出，避免 crash loop。stop 会写入 stop 意图再结束 supervisor。

HTTPS

支持两条路径（可并存于文档/运维习惯，一次只选一种接入）：

1) 原生 HTTPS（应用直接挂证书）

证书默认落在数据目录：

~/.easy-dev/certs/
  tls.json      # { "enabled": true }
  cert.pem
  key.pem       # 权限 0600
  ca.pem        # 可选

也可用环境变量 / CLI 指向外部文件（优先级高于托管目录）：

export ACP_TLS_CERT=/path/to/cert.pem
export ACP_TLS_KEY=/path/to/key.pem
# 可选：ACP_TLS_CA=/path/to/ca.pem
npx @tencent/easy-dev start

# 或
npx @tencent/easy-dev start --tls-cert ./cert.pem --tls-key ./key.pem

Web「全局配置 → HTTPS」可上传 PEM、生成开发用自签证书、切换启用；变更后需 easy-dev restart。

启用原生 HTTPS 时，对外为 HTTPS；同一端口上的明文 HTTP 会 302 到 https://（按请求 Host 跳转）。Agent/MCP 仍走本机 loopback 明文 HTTP（避免自签证书导致 Agent 校验失败）。可用 ACP_LOOPBACK_HTTP_PORT 固定内部端口，默认由系统自动分配。

2) 反向代理终止 TLS（正式部署推荐）

应用保持 HTTP，并建议绑定本机：

HOST=127.0.0.1 npx @tencent/easy-dev start

Caddy 示例：

easy-dev.example.com {
  reverse_proxy 127.0.0.1:8787
}

Nginx 示例（需开启 WebSocket Upgrade）：

server {
  listen 443 ssl http2;
  server_name easy-dev.example.com;
  ssl_certificate     /path/to/fullchain.pem;
  ssl_certificate_key /path/to/privkey.pem;

  location / {
    proxy_pass http://127.0.0.1:8787;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
  }
}

前端会按页面协议自动使用 wss://；服务端已开启 trust proxy，可识别 X-Forwarded-Proto。

logs 选项

| 选项 | 默认值 | 说明 | | --- | --- | --- | | -f, --follow | — | 持续跟随输出 | | -n, --lines <行数> | 200 | 显示末尾行数 | | -d, --data-dir <目录> | ~/.easy-dev | 数据目录 |

前置依赖

• Node.js >= 20
• 至少一个 CLI Agent 在 PATH 中（如 cursor-agent、codex、claude 等）。Easy Dev 不代为安装这些 Agent。

数据目录

默认 ~/.easy-dev，包含：SQLite 数据库、各任务 worktree、meta 仓、日志（logs/）、进程 PID 文件（easy-dev.pid）、可选 config.json。可用 --data-dir 或环境变量 ACP_SRV_ROOT 覆盖。

本地开发

npm install    # 安装根依赖；postinstall 会自动安装 server / web 依赖
npm run dev      # 并行起 server(:8787) 与 vite dev(:5173)；server 用 tsx watch
npm run dev:stable  # 自托管推荐：server 不用 watch，避免 merge 改 server 源码时整进程重启
npm run build   # 构建 web 静态资源 + 打包混淆 server 到 dist

发布后可用性冒烟

推荐用仓库脚本一次发内外网（同一版本；外网包名为 @alderzhang/easy-dev，许可证仍为 UNLICENSED）：

# 凭证：内网 TENCENT_NPM_TOKEN 或 ~/.npmrc；外网 NPMJS_TOKEN 或 ~/.npmrc 的 registry.npmjs.org
npm run publish:all          # 校验/测试/构建一次 → 内网 + npmjs
npm run publish:internal     # 只发内网 @tencent/easy-dev
npm run publish:public       # 只发外网 @alderzhang/easy-dev（补发/重试）

不要直接 npm publish 发外网：源码 package.json.name 仍是 @tencent/easy-dev，且 publishConfig.registry 指向腾讯源。直接 npm publish 只适合内网（会跑 prepublishOnly + postpublish 冒烟）。

发布副本会去掉 postinstall / prepare 等安装生命周期脚本：这些只服务源码仓的 npm install（给 server/web/relay 装依赖）。打进用户包会被 npm 11+ 的 allow-scripts 默认拦截，且对发布布局是空操作。

publish:all 成功后按目标分别跑 scripts/smoke-npm-availability.sh：在 Docker 容器（默认 node:20-bullseye-slim，约 200MB）内按真实默认路径验证包可用——全新安装，以及旧版起服后 easy-dev update。外网冒烟直连 registry.npmjs.org（不挂本机 npmrc，避免默认走到腾讯镜像、刚发布的包 404）。发布后会先轮询 npm view name@version，等 packument 可见再安装——包名已存在、新版本未同步时安装精确版本会 ETARGET，不是 404。

npm run smoke:npm                 # 单独复跑内网（测 package.json 中的版本）
VERSION=0.2.7 npm run smoke:npm   # 指定版本
SMOKE_NPM_PKG=@alderzhang/easy-dev SMOKE_NPM_REGISTRY=https://registry.npmjs.org/ npm run smoke:npm

前置：本机 Docker；内网冒烟需要 ~/.npmrc（或 SMOKE_NPMRC）可访问腾讯源。外网 registry.npmjs.org 可无 token。无 Docker 时可设 SMOKE_NPM_OPTIONAL=1 跳过。镜像可用 SMOKE_NPM_IMAGE 换成内网加速源（勿用 alpine：native 依赖需要 glibc；也勿用 bookworm 系 node:20-slim，旧 Docker seccomp 可能无法跑 Node 20）。