pod

package module

v0.8.3 Latest Latest Go to latest Published: Sep 22, 2026 License: MIT Imports: 12 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/veypi/aic-pod

Links

Open Source Insights

README ¶

aic-pod

设备端 fs、exec、browser/cua 与文件代理已统一采用 hosts_tools/1 三协议架构：Go 自管 Chrome，Desktop 仅提供默认可执行文件路径。

Browser 在后台运行真实 Chrome，统一实际版本的 UA、Client Hints、自动化标记和窗口尺寸，并持续复用独立 profile；具体行为见 Browser 运行环境。

AIC Pod 客户端 — 部署在 PC/服务器上，通过 NATS WebSocket 连接 AIC 平台，把本机能力（命令执行 / 文件操作 / 浏览器自动化 / 原生 GUI 自动化 / ssh·scp 转发）注册为 LLM 可调用的工具。

客户端	形态	核心能力
desktop（主产品）	Electron 壳 + Go 后端子进程	exec（沙箱 + 三域授权）、fs、browser（Go + Chrome）、cua（原生 GUI 自动化）
cli	单二进制 `aic`	exec（沙箱 + 三域授权，含 browser/cua/ssh/scp）、fs

安全模型见 docs/host_sandbox.md，架构见 docs/design.md，版本变更见 CHANGELOG.md。

配置

CLI 与 Desktop 共享同一份配置文件：os.UserConfigDir()/aic/config.yaml （macOS: ~/Library/Application Support/aic/config.yaml），任一端的修改（编辑文件 / 页面绑定）另一端启动即生效。

解析由 vigo/flags 承担：AutoRegister 声明字段，ConfigFile 声明文件，Parse 统一合并，优先级：显式 flag > 环境变量 > 配置文件 > 结构体默认。

配置读取允许容错：未知字段忽略，错误字段使用默认值并保留其他有效字段；文件无法读取或 YAML 整体损坏时使用默认配置启动，仍可用 aic config get|set 修复。读取时不覆盖原文件，只有保存配置时才写回。设置面（aic config）与启动读取共用 flags 的解析/原子写，只负责设备参数的业务校验。

环境变量	CLI flag	配置键	默认值	说明
`KEY`	`-key`	`key`		绑定凭证（必填），从 AIC 平台获取
`HOST`	`-host`	`host`	`https://ivec-ai.com`	平台地址（可带路径前缀，如 `http://127.0.0.1:4000/rses/aiv`；NATS 端点由此推断）
`WORK_DIR`	`-work_dir`	`work_dir`	系统临时目录	命令执行工作目录
`EXEC_TIMEOUT`	`-exec_timeout`	`exec_timeout`	`30m`	后台执行超时
`HOME_PATH`	`-home_path`	`home_path`	`/`	桌面端默认打开地址（host 后的路径，如 `/`、`/a`）
`FS_POLICY`	`-fs_policy`	`fs_policy`	`deny`	文件写默认立场：`deny`（仅内置根 + `fs_allow`）\| `open`（除 `fs_deny` 全放）
`FS_DENY` / `FS_ALLOW`	`-fs_deny` / `-fs_allow`	`fs_deny` / `fs_allow`	—	路径 glob 拒绝 / 显式允许（允许可覆盖拒绝；裸路径覆盖子树，glob 精确匹配）
`NET_POLICY`	`-net_policy`	`net_policy`	`open`	沙箱进程出站立场：`open` \| `deny`（仅 localhost）
`NET_DENY` / `NET_ALLOW`	`-net_deny` / `-net_allow`	`net_deny` / `net_allow`	—	出站目标 `host:port` 拒绝 / 允许（拒绝恒优先；内建 localhost:*）
`SSH_POLICY`	`-ssh_policy`	`ssh_policy`	`deny`	ssh/scp 目标立场：`deny` \| `open`
`SSH_DENY` / `SSH_ALLOW`	`-ssh_deny` / `-ssh_allow`	`ssh_deny` / `ssh_allow`	—	ssh 目标 `host[:port]` 拒绝 / 允许（拒绝恒优先）
`NO_SANDBOX`	`-no_sandbox`	`no_sandbox`	`false`	隐藏项：全局跳过 exec 沙箱（等同放弃进程级隔离，慎用；仅配置文件/flag/env 可改）

三域授权（fs/net/ssh × policy/deny/allow）的完整判定式、内置根与会话级临时 grant 语义见 docs/host_sandbox.md。

本机不监听任何端口（2026-09-22 去本地管理 API）：设置面 = UserConfigDir/aic/config.yaml， CLI 用 aic config get|set / aic bind|unbind 读写（JSON/凭证走 stdin/stdout）， desktop 设置窗经 Electron IPC spawn 同一套子命令；保存后重启后端进程生效。

安全模型

本机能力默认受两道闸控制：

三域授权（fs / net / ssh × policy / deny / allow）：每个域有默认立场（deny/open）、拒绝列表与显式允许列表（拒绝恒优先，显式允许可覆盖拒绝）；另有三类内置根（工作区、会话目录、系统临时目录）与会话级临时 grant（grant <域> <目标> 可加 --permanent 落盘）。
进程沙箱（exec 调用）：darwin sandbox-exec（Seatbelt）/ linux bubblewrap / windows 受限令牌；按授予等级选 profile（read-only / workspace-write），叠加环境变量清洗、资源限制与网络出站闸。无可用后端时 fail-closed（命令不执行，绝不裸跑）。

请求级 nosandbox 可显式申请免沙箱：required 恒提升 Critical(4) ⇒ 必转人工审批，且审批通过（granted 9）本身不豁免沙箱——免沙箱必须携带该标记单独审批。

CLI

安装

从 Releases 下载对应平台二进制，放入 PATH 即可。

用法

aic                                  # 连接运行（config.yaml 里 key 非空则自动连接平台）
aic config get | config set           # 读写本机设置（JSON 走 stdin/stdout）
aic bind | unbind                     # 绑定/解绑平台凭证（凭证走 stdin）
aic -key "<key>"               # 临时参数覆盖
# 查看全部参数：aic -h

临时参数（-host / -key / -work_dir / -exec_timeout / -home_path，或对应环境变量）只影响本次运行； 永久生效请直接编辑 UserConfigDir/aic/config.yaml（或 aic config set / desktop 设置窗，保存后重启后端生效）。

后台运行 (macOS/Linux)

nohup aic > aic.log 2>&1 &

Docker

构建并推送

make docker-build        # 编译 linux/amd64 并构建镜像 → veypi/aic-pod:latest
make docker-build-arm64  # 编译 linux/arm64 并构建镜像
make docker-push         # 推送到 Docker Hub

运行

# 最小启动
docker run -d --name aic-pod -e KEY="<key>" veypi/aic-pod:latest

# 完整参数
docker run -d \
  --name aic-pod \
  --restart unless-stopped \
  -e KEY="<key>" \
  -e WORK_DIR=/workspace \
  -e EXEC_TIMEOUT=30m \
  -e HOST=https://ivec-ai.com \
  -v /host/workspace:/workspace \
  veypi/aic-pod:latest

Docker 参数	说明
`--restart unless-stopped`	容器退出后自动重启
`-v /host:/workspace`	将宿主机目录挂载为命令执行工作目录
`-e KEY`	必填，从 AIC 平台获取的绑定凭证

查看日志

docker logs -f aic-pod

Browser / CUA

Desktop 提供 ui/1 交互工具：browser 控制 Electron 工作区标签页，cua 控制本机原生窗口。两者共用 target / snapshot / click / fill / type / press / scroll / wait 及结果格式。批量操作使用 run --code <JavaScript> 或 run --file <path>，两端注入相同 ui API；脚本在独立受限进程运行，每一步沿用原命令权限和错误语义。普通结果进入 content，图片经 image_data 投递；完整协议与能力边界见 docs/ui-protocol.md。

browser open https://example.com
browser snapshot
browser click @s<snapshot>:e1
cua target list
cua target use <window-target-id>
cua snapshot --image

Chrome 扩展已移除；desktop browser 直接使用 CDP，不依赖插件代码或同步脚本。

构建

产物：desktop 是主产品（aic-*），cli 是 aic-cli-*。

make                            # cli 当前平台 → dist/aic-cli-<os>-<arch>
make cli-all                    # cli 全平台（linux/darwin/windows × amd64/arm64）
make desktop-darwin-arm64       # desktop macOS → dist/AIC Desktop.app + aic-desktop-darwin-arm64.dmg
make desktop-darwin-amd64       # desktop macOS（Intel）
make desktop-windows-amd64      # desktop Windows exe（需先: brew install mingw-w64）
make desktop-all                # desktop 全平台（linux desktop 需容器/CI）
make docker-build               # 编译 cli + Docker 镜像
make docker-push                # 推送镜像
make release                    # 本地全量构建 + gh release create（需各平台工具链）
make clean                      # 清理

desktop 打包前自动同步内置 cua-driver（desktop/cua.json 固定版本 + sha256 → vendor/cua → resources/cua，三平台）；离线/受限网络用 npm run cua-sync -- --asset <已下载资产>。

发版流程：推送 tag v* 触发 CI（.github/workflows/build.yml）构建 desktop 全平台 + cli 全平台并创建 GitHub Release；版本号只改 cfg/config.go（带 v 前缀），desktop/package.json 由 make desktop-version 从 git describe 自动同步。

依赖：Node 22+（Electron/electron-builder）、Go（后端二进制 make backend-bin）、go-winres（windows cli 资源）。

Documentation ¶

Overview ¶

Package pod 是 AIC 本地客户端（aic-pod）的根包：host 会话装配（Start/Stop）。目录结构（对照 aic 服务端的分层）：

cfg/       配置中心：Options + Global、Version/DeviceType 二进制身份、日志文件写入
settings/  本机设置面（`aic config get|set` 的读/写模型，原 api 包逻辑）
libs/      客户端核心：host（NATS 会话运行时）、proto（协议信封签名）、
          vcore（虚拟指令）、exec_procs（进程托管）、utils（纯工具）
cli/       命令行版本（aic）：连接运行 / config / bind / unbind
desktop/   Electron 壳（main.js + preload.js）：Chromium 窗口 + Go 后端子进程

本地不监听任何端口（2026-09-22 去本地管理 API / code / 端口文件握手）：设置面 = config.yaml（Go 侧 flags 原子写），Electron 设置窗口经 IPC spawn `aic config|bind|unbind` 子命令读写；变更生效 = 重启后端子进程。

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func Start ¶

func Start() error

Start 启动 host 会话：已绑定（key 非空）自动连接平台，未绑定仅提示。

func Stop ¶

func Stop()

Stop 停止 host 会话（应用退出时调用）。

func Wake ¶ added in v0.5.5

func Wake() error

Wake 唤醒桌宠录音（aic wake 子指令）：经 desktop（Electron 主进程）的本地指令通道（unix socket UserConfigDir/aic/desktop.sock，换行分隔 JSON 请求/应答）转发 pet:cmd 事件给 pet 组件，效果等同 pet 页左键单击。仅 desktop 形态支持——socket 由 Electron 主进程创建；纯 cli（无桌面）拨号必失败。

Types ¶

This section is empty.

Source Files ¶

View all Source files

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cfg Package cfg 是 aic-pod 的配置中心（cli/desktop 共用同一份配置）： Options 结构体 + Global 全局有效配置，落盘 UserConfigDir/aic/config.yaml。	Package cfg 是 aic-pod 的配置中心（cli/desktop 共用同一份配置）： Options 结构体 + Global 全局有效配置，落盘 UserConfigDir/aic/config.yaml。
cli AIC CLI — 部署在 PC (Windows/macOS/Linux) 上的 host agent，通过 NATS 连接 AIC 平台。	AIC CLI — 部署在 PC (Windows/macOS/Linux) 上的 host agent，通过 NATS 连接 AIC 平台。
libs
browser Package browser owns the dedicated Chrome, pages, observations, downloads and viewers.	Package browser owns the dedicated Chrome, pages, observations, downloads and viewers.
browser/chrome Package chrome launches a dedicated Chrome and speaks CDP over inherited pipes.	Package chrome launches a dedicated Chrome and speaks CDP over inherited pipes.
cua Package cua owns native driver sessions, windows, snapshot tokens and input state.	Package cua owns native driver sessions, windows, snapshot tokens and input state.
exec_procs Package exec_procs owns command executions and output, never service business state.	Package exec_procs owns command executions and output, never service business state.
fsauth Package fsauth enforces the host's local filesystem policy as one ordered rule table (aic/docs/permission_rules.md): builtin deny rows first, then cfg fs_rules (permanent grants append there); the last matching row wins and unmatched paths fall back to fs_policy.	Package fsauth enforces the host's local filesystem policy as one ordered rule table (aic/docs/permission_rules.md): builtin deny rows first, then cfg fs_rules (permanent grants append there); the last matching row wins and unmatched paths fall back to fs_policy.
host Package host 是 AIC host agent 运行时（docs/instruction_sets_v2.md §6.2）： NATS 连接与认证、能力上报、心跳、fs/exec 方法分发、执行管理器装配、 granted_level 纵深检查（与 vcore 分级表同源）。	Package host 是 AIC host agent 运行时（docs/instruction_sets_v2.md §6.2）： NATS 连接与认证、能力上报、心跳、fs/exec 方法分发、执行管理器装配、 granted_level 纵深检查（与 vcore 分级表同源）。
hostauth
hostfs Package hostfs implements the structured fs/1 provider.	Package hostfs implements the structured fs/1 provider.
hosts_tool Package hosts_tool binds tools once for all transports.	Package hosts_tool binds tools once for all transports.
netauth Package netauth enforces exact host/port rules for net and ssh as one ordered rule table per domain (aic/docs/permission_rules.md): builtin rows first, then cfg <domain>_rules (permanent grants append there); the last matching row wins and unmatched targets fall back to <domain>_policy.	Package netauth enforces exact host/port rules for net and ssh as one ordered rule table per domain (aic/docs/permission_rules.md): builtin rows first, then cfg <domain>_rules (permanent grants append there); the last matching row wins and unmatched targets fall back to <domain>_policy.
policy Package policy defines the common execution-policy primitives.	Package policy defines the common execution-policy primitives.
proto Package proto 是 AIC 指令集 v2 的协议层唯一实现（docs/instruction_sets_v2.md §6）： subject 构造、请求/响应信封、HMAC-SHA256 签名与 canonical 输入、caps v2 结构、错误模型、路径展开算法（§2.1.1 可解析层）。	Package proto 是 AIC 指令集 v2 的协议层唯一实现（docs/instruction_sets_v2.md §6）： subject 构造、请求/响应信封、HMAC-SHA256 签名与 canonical 输入、caps v2 结构、错误模型、路径展开算法（§2.1.1 可解析层）。
rtc Package rtc transports hosts_rtc/1 over authenticated, reliable WebRTC channels.	Package rtc transports hosts_rtc/1 over authenticated, reliable WebRTC channels.
uiscript Package uiscript runs ui/1 orchestration in a disposable JS interpreter.	Package uiscript runs ui/1 orchestration in a disposable JS interpreter.
vcore Package vcore 是 AIC 指令集 v2 的指令实现层（docs/instruction_sets_v2.md §4/§5.4）： fs read/write/edit + 核心 8 虚拟指令（ls/rg/tree/curl/rm/mkdir/cp/mv）。	Package vcore 是 AIC 指令集 v2 的指令实现层（docs/instruction_sets_v2.md §4/§5.4）： fs read/write/edit + 核心 8 虚拟指令（ls/rg/tree/curl/rm/mkdir/cp/mv）。
protocol
fs Package fs defines structured filesystem locations and results, independent from AI text formatting and physical host path syntax.	Package fs defines structured filesystem locations and results, independent from AI text formatting and physical host path syntax.
hosts_nats Package hosts_nats binds a tool request to its authenticated destination and caller.	Package hosts_nats binds a tool request to its authenticated destination and caller.
hosts_rtc Package hosts_rtc defines authenticated calls and opaque RTC tool channels.	Package hosts_rtc defines authenticated calls and opaque RTC tool channels.
hosts_tools Package hosts_tools defines the transport-independent tool contract.	Package hosts_tools defines the transport-independent tool contract.
ui Package ui defines the shared browser/cua ui/1 command contract.	Package ui defines the shared browser/cua ui/1 command contract.
settings Package settings 是本机设置面（原 api 包 get_config/set_config 的逻辑，2026-09-22 随本地管理 API 一并从 HTTP 端点改为进程内调用）：	Package settings 是本机设置面（原 api 包 get_config/set_config 的逻辑，2026-09-22 随本地管理 API 一并从 HTTP 端点改为进程内调用）：