Agent Platform CLI（TypeScript）

Agent Platform CLI 的 TypeScript 实现。

公开 npm 包名为 ap-client，当前正式版本为 0.1.0，安装后使用 ap-cli 命令运行。

包发布到公共 npm registry：https://registry.npmjs.org。

本项目是可公开下载的专有软件，许可证声明为 UNLICENSED。公开下载不代表开源，也不授予使用、修改或再分发本软件的许可。

技术路线

项目采用 Bun 开发、Node.js 运行 的方案：

• 使用 Bun 安装依赖、运行测试和执行构建任务。
• 使用 TypeScript 开发，发布前构建为 JavaScript 产物。
• 使用命令清单驱动路由和帮助输出，使用 Vite 生成单文件 Node.js 构建产物。
• 使用 Bun Test 编写测试，使用 Biome 执行格式化和 Lint。
• 最终产物支持 Node.js 20 及以上版本，不要求 CLI 使用者安装 Bun。
• 生产代码仅使用 Node.js 标准能力、标准 Web API 和支持 Node.js 的依赖，禁止依赖 Bun 专属运行时 API。
• 本地门禁使用当前激活的 Node.js 直接验证构建产物；Node.js 20、22、24 的 CI 矩阵将在 CI 平台确定后接入。

安装

前置条件：Node.js 20 或更高版本。

npm install -g ap-client

安装完成后：

ap-cli --help
ap-cli --version

Phase 0：Python 兼容桥接

当前版本已经提供与 ap-client==0.1.20 对齐的完整命令帮助。尚未迁移为 Node 原生实现的业务 命令会委托给 Python ap 执行，原有 ~/.ap 配置继续沿用。

正式版版本绑定为 npm [email protected] → PyPI ap-client==0.1.20。受管 Python 环境 严格安装并校验该版本；PATH 中已有的 ap 仍按现有兼容策略优先使用且不做版本门禁。

ap-cli --help
ap-cli legacy status
ap-cli legacy install
ap-cli migration status

运行规则：

• PATH 中存在可执行的 ap 时始终优先使用，不限制其版本。
• PATH 中没有 ap 时，交互式首次运行会询问是否安装受管运行时；非交互式运行会提示执行 ap-cli legacy install，不会自行安装。
• 受管运行时需要本机预先安装 uv，使用 Python 3.11 和 ap-client==0.1.20，仅写入 ~/.ap/legacy。CLI 不会自动安装 uv，也不会改写 ~/.ap 下原有配置。
• legacy 命令失败时会提示检查实际 ap --version，建议版本为 0.1.20。
• Phase 0 支持 macOS 和 Linux。ap-cli job exec 暂不支持，后续将在 Node CLI 中原生实现。

可使用 ap-cli legacy status 检查 uv、PATH ap、受管 ap 和最终选用的运行时；使用 ap-cli migration status 查看每个命令当前采用 native、legacy 或 unsupported 策略。

更新记录

各版本的用户可见变化和已知限制见 CHANGELOG.md。

本地开发

开发环境需要 Bun 1.3.11：

bun install --frozen-lockfile
bun run dev -- --help
bun test
bun run build
node dist/index.js --help

提交评审前运行完整本地门禁：

bun run verify

该门禁依次检查格式、Lint、TypeScript 类型、Bun 测试、Vite 构建、Node.js 产物 smoke test 和 npm 发布内容预览。