AI 支持代理CLI

一个将你的机器变成AI驱动的遥控器 安装它,通过浏览器认证,你的团队可以发送 shell 命令, AI 聊天提示, 文件操作, 以及更多的—— 全部来自一个Web UI,结果流回实时.

┌──────────────┐  AppSync     ┌─────────────────┐  WebSocket/HTTP  ┌──────────────────┐
│   Web UI     │ ──────────── │   API Server    │ ─────────────── │  Agent CLI       │
│  (browser)   │  subscription│   (NestJS)      │  commands/result │  (your machine)  │
└──────────────┘              └─────────────────┘                  └──────────────────┘
                                                                     ├─ Claude Code
                                                                     ├─ Shell / PTY
                                                                     ├─ File I/O
                                                                     ├─ Git repos
                                                                     ├─ MCP server
                                                                     └─ VS Code tunnel

为什么?

• 远程 AI 对等编程 ——从Web UI中询问有关您代码库的问题;克洛德代码运行在代理机上,可以完全访问寄存器.
• 多租户,多项目 单一代理人管理不同租户的多个项目。 在苍蝇上添加/移动项目;代理热重载.
• 零配置实时 ——AppSync WebSocket订阅即时发送命令. 没有投票延误,没有港口转发.
• 默认安全 ——OAuth登录,6600配置权限,无ce被保护回调,SQL注射检测,路径穿行守护,环境消毒.

托管服务

最快的启动方式是管理服务 ai-support-agent.com (中文(简体) )。在那里创建一个账户,然后将 CLI 从框中连接到它 。 这些是内置默认, 所以不需要额外的标记 :

运行 ai-support-agent login 打开主机网络控制台( q)app.ai-support-agent.com)在浏览器中,在其中签名并选择租户和项目链接.

自我接待吗? CLI不与主机服务捆绑. 指着自己的部署 --url 编号 : --api-url (或 AI_SUPPORT_AGENT_API_URL 环境变量)——见 配置。 。 。 .

快速启动

npm install -g @ai-support-agent/cli

# Opens app.ai-support-agent.com in your browser → sign in → select tenant & project → done
ai-support-agent login

# Start the daemon (Ctrl-C to stop)
ai-support-agent start

就是这样。 代理机与服务器注册,同步项目配置,克隆寄存器,并开始监听命令.

Docker必须运行:每个项目默认在一个容器中运行,第一个 start 获取代理图像(参见 在 Docker 中运行) (中文(简体) ). 添加 --no-docker 直接在主机上运行.

添加更多项目

ai-support-agent add-project          # browser OAuth flow
ai-support-agent status               # verify registered projects

从个人访问托肯开始(代理范围)

代替浏览器 OAuth 流,您可以用 个人访问 托肯语( PAT) 在网络应用程序中为你自己发布。 发布PAT范围 包含 agent 以及他们 projectCode 设置,然后在您自己下启动代理 权限( “个人计划 ” ):

# The tenant comes from the token; the project is given with --project.
ai-support-agent start --token <tenantCode>:<tokenId>:<rawToken> --project <tenantCode>/<projectCode>

• 没有浏览器登录, 没有前端 login编号 :configure 需要步骤.
• --api-url 可选和默认的 API 生产(https://api.ai-support-agent.com) (中文(简体) ).
• 租户在 --project 必须匹配 PAT 的租户; 不匹配 在代理登记前被拒绝.
• 最好是通过 AI_SUPPORT_AGENT_TOKEN 环境变量,所以 在进程列表中没有出现( :ps aux) (中文(简体) ).

在 Docker 中运行

Docker 是默认值: plain ai-support-agent start 在容器中运行每个项目 --no-docker 选择退出本地模式.

ai-support-agent start              # Docker mode (default)
ai-support-agent start --no-docker  # run natively on the host instead

项目 dirs, ~/.claude/,以及 ~/.aws/ 自动挂载。 该容器与您的主机UID/GID运行.

基础图像. 给定版本的第一次运行获得 ai-support-agent:<version>数字 :

已公布的图像由此寄存器的发布工作流程构建 docker/Dockerfile 和相同的CLI版本, 所以对于一个未修改的设置拉和构建产生相同的图像.

一旦图像在本地存在, 它会被重新使用 —— 之后自定义 Docker 文件 没有 启动重建。 使用 :

ai-support-agent docker-diff-dockerfile   # compare your Dockerfile with the bundled default
ai-support-agent docker-build             # force a local rebuild after customising
ai-support-agent docker-ensure-image      # obtain the image if missing (pull or build)

作为背景服务运行

ai-support-agent service install      # install as a system service
ai-support-agent service start        # start the service
ai-support-agent service status       # check service status
ai-support-agent service stop         # stop the service
ai-support-agent service restart      # restart the service
ai-support-agent service uninstall    # remove the service

如何运作

1. 登记册 ——特工将其能力(壳,文件一/O,聊天,终端,vscode)发送给API.
2. 订阅 ——连接到AppSync进行实时命令发送.
3. 配置同步 ——从服务器上拉出项目设置,MCP配置和repo列表.
4. 执行 ——接收命令,在本地运行,溪流会逐个返回.

每个项目都按自己的儿童工序进行。 主进程监视 config.json 和不重新启动的热添加/删除项目.

支持的命令

聊天模式

模式解析为:代理配置 ~ 服务器默认 ~ 自动检测(是否) claude CLI 已安装).

内建的 MCP 服务器

代理船舶a 示范背景协议 claude Code 可以调用的服务器:

一般工具:

浏览器自动化工具( Playwright ) :

E2E 测试工具 :

CLI 参考

ai-support-agent <command> [options]

Commands:
  start              Start the agent daemon
  stop               Stop the running agent
  login              Authenticate via browser OAuth
  add-project        Add a project (browser OAuth)
  remove-project     Remove a project by code
  configure          Register with --token and --api-url
  status             Show agent status and registered projects
  set-language       Set display language (en | ja)
  set-auto-update    Configure auto-update (--enable | --disable | --channel)
  set-project-dir    Set project working directory
  docker-login       Login and start in Docker
  docker-build       Always build the Docker image for this version locally
                     (--dockerfile <path>)
  docker-ensure-image  Make the Docker image available: pull
                     ghcr.io/mbc-net/ai-support-agent-cli when nothing is
                     customised, build locally otherwise (--dockerfile <path>,
                     --no-image-pull)
  docker-diff-dockerfile  Show diff between a Dockerfile and the bundled default
  log-rotate         Read stdin and write to a size-rotating log file
                     (used by the per-project wrapper script)
  service            Manage agent background service

Global options:
  --lang <lang>      Override display language for this invocation
  --version          Show version

service 子命令

service install     Install the agent as a system background service
service uninstall   Uninstall the agent service
service start       Start the agent service
service stop        Stop the agent service
service restart     Restart the agent service
service status      Show service status

Options (install):
  --verbose          Show detailed installation info
  --no-docker        Install in native mode (skip Docker)

start 选项

--token <token>            Auth token or agent-scoped PAT (overrides config file)
--api-url <url>            API URL (defaults to the production API)
--verbose                  Enable debug logging
--heartbeat-interval <ms>  Heartbeat interval (default: 60000)
--no-auto-update           Disable auto-update for this session
--update-channel <channel> Release channel: latest | beta | alpha
--no-docker                Force native mode (skip Docker)
--dockerfile <path>        Custom Dockerfile path (overrides config and bundled default)
--no-dockerfile-sync       Skip writing the default Dockerfile to config dir
--no-image-pull            Never pull the base image from the container registry;
                           always build it locally (same as config
                           "dockerImagePull": "never"). By default an
                           uncustomised Dockerfile means the published
                           ghcr.io/mbc-net/ai-support-agent-cli image is pulled
                           instead of being rebuilt on this machine
--project <tenantCode/projectCode>  Start only the matching project; with --token
                                    it selects the project for a direct (PAT) start

set-project-dir 选项

--default <template>       Set default dir template (e.g. ~/projects/{projectCode})
--project <code> --path <path>  Set dir for a specific project

配置

存放于 ~/.ai-support-agent/config.json (模式) 0600:

{
  "agentId": "macbook-a1b2c3d4",       // auto-generated
  "createdAt": "2025-01-01T00:00:00Z",
  "lastConnected": "2025-06-15T09:00:00Z",
  "language": "en",                     // en | ja
  "agentChatMode": "claude_code",       // claude_code | api
  "defaultProjectDir": "~/.ai-support-agent/projects/{projectCode}",
  "autoUpdate": {
    "enabled": true,
    "autoRestart": true,
    "channel": "latest"                 // latest | beta | alpha
  },
  "projects": [
    {
      "projectCode": "MY_PROJECT",
      "token": "agt_xxxx",
      "apiUrl": "https://api.ai-support-agent.com",   // defaults to the hosted API
      "projectDir": "~/custom-path"     // optional override
    }
  ]
}

环境变量

优先级: CLI 旗 > 配置文件 > 环境变量.

项目目录结构

每个项目都有一个孤立的工作空间:

{projectDir}/
├── workspace/
│   ├── repos/          # Git-cloned repositories
│   ├── docs/           # Documentation from server
│   └── artifacts/      # Generated outputs
├── uploads/            # File uploads staging
└── .ai-support-agent/
    ├── cache/          # Temporary cache
    └── aws/            # AWS credential cache

警卫

发展

git clone https://github.com/mbc-net/ai-support-agent-cli.git
cd ai-support-agent-cli

npm install
npm run dev -- start --verbose    # development mode
npm test                          # run tests
npm run test:cov                  # coverage (95%+ thresholds enforced)
npm run build                     # compile to dist/

需要节点.js >= 20. node-pty 是终端/ PTY 会话的可选依赖.

许可证

麻省理工学院

错误

auth login/logout 页:1 env check/run/pull で承認済み環境設定を利用できます {\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}你应该知道 を参照してください。

.envを使うローカル開発(日本語)

空虚 API\Web\Voult local の設定リリースを承認・有効化します。利用者にはファイル出力用の export 権限を付与してください。

開発プロジェクトの .ai-support/env.yaml に接続先と識別子を設定します。秘密値はここへ書きません。

version: 1
apiUrl: https://api.example.test
tenant: example
project: support
profiles:
  local:
    service: api
    environment: local
    required: [DATABASE_URL]

.gitignore に .env.local 乌尔勒。

ai-support-agent auth login --url https://app.example.test --profile local --purpose export
# ブラウザーでログインし、設定取得を許可します。
ai-support-agent env pull --profile local --output .env.local
ai-support-agent auth logout --profile local --purpose export

.env 吉蒂格诺雷 run 権限を付与し、--purpose export を付けずにログインして ai-support-agent env run --profile local -- npm run dev を実行します。

空虚 :

auth login --purpose edit --session-duration 8h で編集用ログインを行い、 env add LOG_LEVEL --value debug编号 :env set LOG_LEVEL --value info で未承認の候補を作成します。 国 家 --from へ指定します。秘密値は --secret の非表示入力、または --secret --stdin を使用します。秘密値を --value に渡すことは禁止しています。 標準入力の末尾改行は保持し、除去する場合のみ --strip-final-newline を指定してください。

env diff --release <ID> → env approve --release <ID> → env stage --release <ID> --target <ID> → env activate --release <ID> --expected-active <現在のID> 同意部署。 初回有効化の --expected-active 有问题吗 none地方阶段。 本番では変更参加者による自己承認を拒否します。

本地 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++。 {\FN黑体\FS22\BORD1\SHAD0\3AHBE\4AH00\FSCX67\FSCY66\2CHFFFFFF\3CH808080}你觉得呢 自動更新はしません。実行用リースは別管理のままです。 国 家 env status --operation-id <ID> --purpose <用途> で確認し、 同じ要求を再送する場合だけ同じ --operation-id を使用します。再送可能期間は24時間です。

E2E 配置迁移

在部署此代理之前先部署带有指令范围E2E配置端点的API. 每个 E2E 执行模式在开始前都会执行一个命令约束的录入检查;代理从不回落到旧的只环境端点. 完成时在终端命令结果提交后使用单独的确认. 失败确认保留原始结果进行重试 .

当一个孩子仍在运行,终止使用信号/ kill/timeout,或浏览器会话清理失败时,配置录入仍然活跃. 正常的完成依赖于被支持的跑者普通浏览器/工人被撕毁;脚本不能拆分出背景过程. 历史工作和独立离散的后代在v2迁移前需要经过核实的操作员关闭. 仅凭最终执行状态并不能证明这些过程已经停止.

服务器设置配置完成

服务器设置结果交付和配置录入关闭是单独的确认. 代理商在等待结果的同时坚持有目地观察的完成证据 普通结果先提交 /agent/commands/:id/server-setup-configuration-complete。 。 。 . 遗失的确认保留原始结果、证据、实例身份和转让 用于重试。 API在接受终端结果后必须支持相同的结果重放. 此协议不扩展托肯; 过期的证书需要操作员调节 .

自动普通补全目前覆盖直接同步调试/ sassert/ set fact, 复制/文件/行内文件/块状文件/重置/stat/get url/组/用户/等待和授权的 key 模块,在成功完成 Ansible 进程和有效任务输出后。 同步/投放/通知 并排除任意验证命令。 Shell/ 命令任务和未审计的捆绑 即使UI报告成功,角色仍未解决. 他们的远程终止必须是 在配置切换前调节 。 继续运行的预定服务守护进程是 - 扩大自动覆盖范围需要审计 菜谱的任务生命周期,而不是要求所有服务停止.

哨兵完成使用专用远程状态探测器,需要明确 settled: true, (中文(简体) ), active: false 和匹配的安装运行ID。 单独成功的回收行动 保留可观察到的远程运行ID,用于主机扫描服务器对接. 混合食谱必须 也具有同步可认证的伴奏任务,并且没有超时或 取消 。 SSH 丢失, 缺失的探针字段, 仅局部进程终止, 和 UI 终端 状态从来不是远距离哨兵终止的证据.

每项设置索赔还附有: x-server-setup-instance-id,命令前生成 检索并保留待决结果。 恢复原始结果 身份; 重新启动的进程不得再次获取和执行命令。 居民 继续独立检查任务生成和复制身份. 跑步记录 data.serverSetupLocalTermination 只有在Ansible孩子出生后 观察 close 事件,不包括产卵失败;仅执行文件错误回调是不够的。 这是 当地终止的证据,包括在实际关闭的暂停/终止之后 ;不能确定远程终止。 恢复先前的哨兵收容 必须将其经认证的已保存的本地证据与适当范围远程证据结合起来. 没有这种证据的遗产处决仍然无法进行操作者和解.

哨兵入场关闭还需要原Ansible跑道成功完成. 取消、 超时或其他执行失败后解析的远程快照不会 排除已经分发的延迟远程启动。 这种接纳仍未得到解决 直至有较强的远程围栏或经独立核实的行动终止.