@h-ai/ai 1.0.0-beta.5 → 1.0.0-beta.7

package/models/agents/README.md

@@ -0,0 +1,48 @@
+# ACP Agent 镜像
+
+## 用途
+
+Codex/dsh 镜像为 `ai.acp` 的 builtin-service 提供原生 stdio 执行环境；Goose 镜像提供自身的原生 HTTP/WS 服务，通过 custom-service 接入。默认非 root 用户 node，不包含引擎 socket；不把 stdio 转成 HTTP/WS。
+
+## 构建与使用
+
+```sh
+pnpm --filter @h-ai/ai agent:build codex-acp
+pnpm --filter @h-ai/ai agent:build deepseek-harness --engine=podman
+pnpm --filter @h-ai/ai agent:build goose
+pnpm --filter @h-ai/ai agent:build codex-acp --engine=docker --java --rust --go
+```
+
+auto 默认先探测可用 Podman，再探测 Docker；显式选择不会降级。镜像标签来自各目录 agent.json。
+
+| 镜像                               | 必需程序                                                                      |
+| ---------------------------------- | ----------------------------------------------------------------------------- |
+| hai-ai/codex-acp:2.5.0             | codex-acp 2.5.0 + 原生 codex 0.165.0                                          |
+| hai-ai/deepseek-harness:0.2.1-rc.5 | dsh 0.2.1-rc.5，profile=acp                                                   |
+| hai-ai/goose:1.57.0                | 官方 Goose 1.57.0 Linux amd64 musl 二进制，校验固定 SHA256，原生 /acp HTTP/WS |
+
+所有镜像含 Git、Node 24、Python 3；可选 Java JDK、Rust/Cargo、Go。Git 缺失属于明确错误，不降级跳过。构建需要 Debian 和 npm 网络访问；版本升级应同步 manifest、Dockerfile、适配器和实际 Agent E2E。
+
+Agent 配置指定 builtin-service、adapter、image、modelIds；workspace 指定 volume、name、相同 image 和 engine。workspace 卷挂 `/workspace`，持久状态卷 `<name>-state` 挂 `/state`。Git/worktree 和 Agent 都在同样的容器路径执行，关闭容器不删除两个卷。Git 认证使用 workspace.environmentRefs，由宿主注入环境；不把密钥写进镜像。
+
+Podman 不继承其远程服务的代理变量。代理通过 Agent/workspace 的 environmentRefs 显式授予，并使用容器能访问的地址，不能直接使用宿主回环代理。
+
+完整 API 示例见 [ACP 接入指南](../../../cli/templates/skills/hai-ai/acp.md)。
+
+## Goose 原生远程服务
+
+Goose 使用 `goose serve --host 0.0.0.0 --port 3284`，在 `/acp` 同时提供 HTTP 和 WebSocket。镜像预启用 Developer 扩展；模型由 Goose 服务端通过 `GOOSE_PROVIDER`、`GOOSE_MODEL` 和供应商密钥变量维护，Hai 的 custom-service 不注入模型配置。OpenRouter 对应 `GOOSE_PROVIDER=openrouter` 和 `OPENROUTER_API_KEY`。服务凭据使用独立的 `GOOSE_SERVER__SECRET_KEY`，客户端用 `headerEnv` 注入 `X-Secret-Key`；不将密钥写在地址中。依据：[固定版本 ACP 文档](https://github.com/aaif-goose/goose/blob/v1.57.0/documentation/docs/gdk/acp/index.md)、[供应商配置](https://github.com/aaif-goose/goose/blob/v1.57.0/documentation/docs/getting-started/providers.md)。
+
+部署方启动容器，将工作区卷挂到 `/workspace`、状态卷挂到 `/state`，再登记 Hai 自定义服务。Hai 只管理 ACP 连接和原生会话；远程服务、卷、Git 与模型的生命周期由部署方管理。镜像当前只提供 linux/amd64；明确检查平台，不在其它架构上误装 x86 二进制。
+
+`tests/ai-acp-goose.e2e.test.ts` 对真实 Goose 服务分别验证 HTTP/WS 鉴权、随机文件读写、原生工具调用；仅当握手声明恢复能力时验收恢复，否则验证显式不支持。设置 `HAI_ACP_E2E_GOOSE=1`、`HAI_ACP_E2E_GOOSE_IMAGE=hai-ai/goose:1.57.0` 和 `OPENROUTER_APIKEY` 启用；`HAI_ACP_E2E_GOOSE_MODEL` 可覆盖测试型号，默认沿用 `HAI_ACP_E2E_MODEL`，再回退 qwen/qwen3.7-flash。模型服务会发生真实调用，测试报告与截图沿用 `test-results/acp-openrouter`，不记录凭据。
+
+## 验证
+
+AI 包的 `test:e2e` 包含原生 stdio/HTTP/WS、临时 Git remote 和容器卷测试。容器 E2E 用 `HAI_ACP_E2E_IMAGE` 指定已构建的镜像，`HAI_ACP_E2E_ENGINE` 可选 auto/podman/docker。未提供镜像时明确跳过容器测试，不能视为容器通过。`HAI_ACP_E2E_DSH_IMAGE` 开启真实 DeepSeek Harness 验收；native E2E 使用镜像内实际 Codex/dsh 和容器内测试模型 HTTP 服务，检查模型配置、认证、协议请求和返回文本。真实模型推理仍需部署方自己的模型端点，夹具推理不代表真实模型验收。
+
+连接真实 OpenRouter 的四组合（Codex/dsh × embedded/builtin-service）验收使用独立测试，核验实际工具读写与关闭后恢复，并保留脱敏 JSON 与截图。必须显式启用，普通开发与仅存在密钥时均不运行；操作步骤见 [真实模型验收](../../tests/ACP-OPENROUTER.md)。
+
+## 许可证
+
+Apache-2.0

package/models/agents/build.mjs

@@ -0,0 +1,66 @@
+import { spawn } from 'node:child_process'
+import { readFile } from 'node:fs/promises'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+async function main() {
+  const names = ['codex-acp', 'deepseek-harness', 'goose']
+  const [name, ...options] = process.argv.slice(2)
+  if (!names.includes(name))
+    throw new Error(`Select agent: ${names.join(', ')}`)
+  const selected
+    = options.find(value => value.startsWith('--engine='))?.slice(9) ?? 'auto'
+  if (!['auto', 'podman', 'docker'].includes(selected))
+    throw new Error('Invalid container engine')
+  for (const option of options) {
+    if (!['--java', '--rust', '--go', `--engine=${selected}`].includes(option))
+      throw new Error(`Unknown option: ${option}`)
+  }
+  async function run(command, args) {
+    await new Promise((resolve, reject) => {
+      const child = spawn(command, args, {
+        shell: false,
+        windowsHide: true,
+        stdio: 'inherit',
+      })
+      child.on('error', reject)
+      child.on('close', code =>
+        code === 0 ? resolve() : reject(new Error('Container command failed')))
+    })
+  }
+  let engine
+  for (const candidate of selected === 'auto'
+    ? ['podman', 'docker']
+    : [selected]) {
+    try {
+      await run(candidate, ['info'])
+      engine = candidate
+      break
+    }
+    catch {
+      /* 未就绪时尝试下一引擎；明确选择的引擎不会降级。 */
+    }
+  }
+  if (!engine)
+    throw new Error('No ready Podman/Docker engine')
+  const directory = fileURLToPath(new URL(`./${name}/`, import.meta.url))
+  const manifest = JSON.parse(
+    await readFile(new URL(`./${name}/agent.json`, import.meta.url), 'utf8'),
+  )
+  await run(engine, [
+    'build',
+    '--build-arg',
+    `WITH_JAVA=${options.includes('--java')}`,
+    '--build-arg',
+    `WITH_RUST=${options.includes('--rust')}`,
+    '--build-arg',
+    `WITH_GO=${options.includes('--go')}`,
+    '-t',
+    `${manifest.image}:${manifest.version}`,
+    directory,
+  ])
+}
+main().catch((error) => {
+  process.stderr.write(`${error.message}\n`)
+  process.exitCode = 1
+})

package/models/agents/codex-acp/Dockerfile

@@ -0,0 +1,25 @@
+FROM docker.io/library/node:24.22.1-bookworm-slim
+ARG DEBIAN_MIRROR=https://mirrors.tuna.tsinghua.edu.cn/debian
+ARG DEBIAN_SECURITY_MIRROR=https://mirrors.tuna.tsinghua.edu.cn/debian-security
+ARG WITH_JAVA=false
+ARG WITH_RUST=false
+ARG WITH_GO=false
+# 基础运行环境；可选语言在构建时选择，不在任务执行时临时安装。
+# 使用 Node 自带的公开 CA 引导 HTTPS，随后安装系统 CA；不关闭证书校验。
+RUN mkdir -p /etc/ssl/certs && node -e "require('node:fs').writeFileSync('/etc/ssl/certs/ca-certificates.crt', require('node:tls').rootCertificates.join('\\n'))"
+RUN set -eu; packages="git python3 python3-venv python3-pip ca-certificates"; \
+    case "$WITH_JAVA" in true) packages="$packages default-jdk-headless";; false) ;; *) exit 2;; esac; \
+    case "$WITH_RUST" in true) packages="$packages rustc cargo";; false) ;; *) exit 2;; esac; \
+    case "$WITH_GO" in true) packages="$packages golang";; false) ;; *) exit 2;; esac; \
+    sed -i -e "s|http://deb.debian.org/debian-security|${DEBIAN_SECURITY_MIRROR}|g" -e "s|http://deb.debian.org/debian|${DEBIAN_MIRROR}|g" /etc/apt/sources.list.d/debian.sources; \
+    apt-get -o Acquire::Retries=2 -o Acquire::http::Timeout=30 -o Acquire::https::Timeout=30 update; apt-get install -y --no-install-recommends $packages; \
+    rm -rf /var/lib/apt/lists/*; git --version; node --version; python3 --version
+# ACP 适配器和原生 Codex CLI 都是镜像的明确组成部分，版本需匹配。
+RUN npm install --global @agentclientprotocol/codex-acp@2.5.0 @openai/codex@0.165.0 \
+    && codex --version && codex-acp --version
+RUN mkdir -p /workspace /state && chown node:node /workspace /state
+USER node
+ENV HOME=/state
+WORKDIR /workspace
+ENTRYPOINT ["codex-acp"]
+CMD []

package/models/agents/codex-acp/agent.json

@@ -0,0 +1,16 @@
+{
+  "name": "codex-acp",
+  "package": "@agentclientprotocol/codex-acp",
+  "version": "2.5.0",
+  "image": "hai-ai/codex-acp",
+  "transports": [
+    "stdio"
+  ],
+  "command": "codex-acp",
+  "args": [],
+  "runtime": {
+    "package": "@openai/codex",
+    "version": "0.165.0",
+    "command": "codex"
+  }
+}

package/models/agents/deepseek-harness/Dockerfile

@@ -0,0 +1,23 @@
+FROM docker.io/library/node:24.22.1-bookworm-slim
+ARG DEBIAN_MIRROR=https://mirrors.tuna.tsinghua.edu.cn/debian
+ARG DEBIAN_SECURITY_MIRROR=https://mirrors.tuna.tsinghua.edu.cn/debian-security
+ARG WITH_JAVA=false
+ARG WITH_RUST=false
+ARG WITH_GO=false
+# 基础运行环境；可选语言在构建时选择，不在任务执行时临时安装。
+# 使用 Node 自带的公开 CA 引导 HTTPS，随后安装系统 CA；不关闭证书校验。
+RUN mkdir -p /etc/ssl/certs && node -e "require('node:fs').writeFileSync('/etc/ssl/certs/ca-certificates.crt', require('node:tls').rootCertificates.join('\\n'))"
+RUN set -eu; packages="git python3 python3-venv python3-pip ca-certificates"; \
+    case "$WITH_JAVA" in true) packages="$packages default-jdk-headless";; false) ;; *) exit 2;; esac; \
+    case "$WITH_RUST" in true) packages="$packages rustc cargo";; false) ;; *) exit 2;; esac; \
+    case "$WITH_GO" in true) packages="$packages golang";; false) ;; *) exit 2;; esac; \
+    sed -i -e "s|http://deb.debian.org/debian-security|${DEBIAN_SECURITY_MIRROR}|g" -e "s|http://deb.debian.org/debian|${DEBIAN_MIRROR}|g" /etc/apt/sources.list.d/debian.sources; \
+    apt-get -o Acquire::Retries=2 -o Acquire::http::Timeout=30 -o Acquire::https::Timeout=30 update; apt-get install -y --no-install-recommends $packages; \
+    rm -rf /var/lib/apt/lists/*; git --version; node --version; python3 --version
+RUN npm install --global @deepseek-ai/dsh@0.2.1-rc.5
+RUN mkdir -p /workspace /state && chown node:node /workspace /state
+USER node
+ENV HOME=/state
+WORKDIR /workspace
+ENTRYPOINT ["dsh"]
+CMD ["--profile", "acp"]

package/models/agents/deepseek-harness/agent.json

@@ -0,0 +1,14 @@
+{
+  "name": "deepseek-harness",
+  "package": "@deepseek-ai/dsh",
+  "version": "0.2.1-rc.5",
+  "image": "hai-ai/deepseek-harness",
+  "transports": [
+    "stdio"
+  ],
+  "command": "dsh",
+  "args": [
+    "--profile",
+    "acp"
+  ]
+}

package/models/agents/goose/Dockerfile

@@ -0,0 +1,34 @@
+FROM docker.io/library/node:24.22.1-bookworm-slim
+ARG DEBIAN_MIRROR=https://mirrors.tuna.tsinghua.edu.cn/debian
+ARG DEBIAN_SECURITY_MIRROR=https://mirrors.tuna.tsinghua.edu.cn/debian-security
+ARG WITH_JAVA=false
+ARG WITH_RUST=false
+ARG WITH_GO=false
+ARG GOOSE_DOWNLOAD_URL=https://github.com/aaif-goose/goose/releases/download/v1.57.0/goose-x86_64-unknown-linux-musl.tar.gz
+# Git/Node/Python 为基础环境，Goose 使用固定版本及固定 SHA256 的官方 musl 二进制。
+RUN mkdir -p /etc/ssl/certs && node -e "require('node:fs').writeFileSync('/etc/ssl/certs/ca-certificates.crt', require('node:tls').rootCertificates.join('\\n'))"
+RUN set -eu; packages="git python3 python3-venv python3-pip ca-certificates curl musl"; \
+    case "$WITH_JAVA" in true) packages="$packages default-jdk-headless";; false) ;; *) exit 2;; esac; \
+    case "$WITH_RUST" in true) packages="$packages rustc cargo";; false) ;; *) exit 2;; esac; \
+    case "$WITH_GO" in true) packages="$packages golang";; false) ;; *) exit 2;; esac; \
+    sed -i -e "s|http://deb.debian.org/debian-security|${DEBIAN_SECURITY_MIRROR}|g" -e "s|http://deb.debian.org/debian|${DEBIAN_MIRROR}|g" /etc/apt/sources.list.d/debian.sources; \
+    apt-get -o Acquire::Retries=2 -o Acquire::http::Timeout=30 -o Acquire::https::Timeout=30 update; \
+    apt-get install -y --no-install-recommends $packages; rm -rf /var/lib/apt/lists/*; \
+    git --version; node --version; python3 --version
+RUN test "$(uname -m)" = x86_64 && \
+    curl --fail --location --retry 2 --connect-timeout 30 --max-time 300 \
+      "${GOOSE_DOWNLOAD_URL}" \
+      --output /tmp/goose.tar.gz && \
+    echo '6c3a05e30e1a425dc06a410dbe24b3f3697c9721b1ea2340434ddda6b64267ae  /tmp/goose.tar.gz' | sha256sum --check - && \
+    mkdir /tmp/goose-install && tar -xf /tmp/goose.tar.gz -C /tmp/goose-install && \
+    install -m 0755 /tmp/goose-install/goose /usr/local/bin/goose && \
+    rm -rf /tmp/goose.tar.gz /tmp/goose-install && goose --version
+RUN mkdir -p /workspace /state/.config/goose && \
+    echo '{"extensions":{"developer":{"bundled":true,"enabled":true,"name":"developer","timeout":300,"type":"builtin"}}}' > /state/.config/goose/config.yaml && \
+    chown -R node:node /workspace /state
+USER node
+ENV HOME=/state
+WORKDIR /workspace
+EXPOSE 3284
+ENTRYPOINT ["goose"]
+CMD ["serve", "--host", "0.0.0.0", "--port", "3284"]

package/models/agents/goose/agent.json

@@ -0,0 +1,14 @@
+{
+  "name": "goose",
+  "version": "1.57.0",
+  "image": "hai-ai/goose",
+  "transports": ["http", "ws"],
+  "command": "goose",
+  "args": ["serve", "--host", "0.0.0.0", "--port", "3284"],
+  "source": "https://github.com/aaif-goose/goose/releases/tag/v1.57.0",
+  "artifact": {
+    "url": "https://github.com/aaif-goose/goose/releases/download/v1.57.0/goose-x86_64-unknown-linux-musl.tar.gz",
+    "sha256": "6c3a05e30e1a425dc06a410dbe24b3f3697c9721b1ea2340434ddda6b64267ae",
+    "platform": "linux/amd64"
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/ai",
   "type": "module",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.7",
   "description": "Hai Framework AI module (LLM, MCP, tools, and clients).",
   "license": "Apache-2.0",
   "exports": {
@@ -23,7 +23,8 @@
   "browser": "./dist/browser.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "models/agents"
   ],
   "publishConfig": {
     "access": "public"
@@ -41,11 +42,12 @@
   },
   "dependencies": {
     "@a2a-js/sdk": "^0.3.12",
-    "@h-ai/api-contract": "1.0.0-beta.5",
-    "@h-ai/core": "1.0.0-beta.5",
-    "@h-ai/datapipe": "1.0.0-beta.5",
-    "@h-ai/reldb": "1.0.0-beta.5",
-    "@h-ai/vecdb": "1.0.0-beta.5",
+    "@agentclientprotocol/sdk": "2.2.0",
+    "@h-ai/api-contract": "1.0.0-beta.7",
+    "@h-ai/core": "1.0.0-beta.7",
+    "@h-ai/datapipe": "1.0.0-beta.7",
+    "@h-ai/reldb": "1.0.0-beta.7",
+    "@h-ai/vecdb": "1.0.0-beta.7",
     "@modelcontextprotocol/sdk": "^1.32.1",
     "mem0ai": "^3.3.1",
     "nanoid": "^6.0.2",
@@ -80,6 +82,8 @@
     "model:prepare": "node models/build.mjs prepare",
     "model:build": "node models/build.mjs build",
     "model:run": "node models/build.mjs run",
-    "build:clean": "rimraf dist"
+    "build:clean": "rimraf dist",
+    "agent:build": "node models/agents/build.mjs",
+    "test:e2e": "vitest run tests/ai-acp.e2e.test.ts tests/ai-acp-transport.e2e.test.ts tests/ai-acp-container.e2e.test.ts tests/ai-acp-native.e2e.test.ts tests/ai-acp-openrouter.e2e.test.ts tests/ai-acp-goose.e2e.test.ts"
   }
 }