ai-project-manage-cli (apm)

AI 项目管理后端的命令行工具与 SDK（包名 ai-project-manage-cli，可执行文件 apm）。

全局帮助：apm --help；各子命令可加 --help 查看参数说明。

配置文件

默认路径：~/.config/apm/config.json；若设置了 $XDG_CONFIG_HOME，则为 $XDG_CONFIG_HOME/apm/config.json。

典型字段：baseUrl、token、employeeId（由 apm login 写入）；可选 wsPort（员工 WebSocket 端口，供 apm ws 使用）。

apm config

读写本机配置（键名与 npm config 风格一致）。

| 命令 | 说明 | |------|------| | apm config set base-url <url> | 服务根地址（不含末尾 /） | | apm config get base-url | 打印已配置的 base-url | | apm config set ws-port <1–65535> | 员工 WebSocket 端口 | | apm config get ws-port | 打印当前解析到的 ws 端口（未配置时有内置默认） |

apm login / apm logout

apm config set base-url http://localhost:3000
apm login -u <员工ID>                    # 交互输入 CLI 口令；或 --password（勿写入 shell 历史）
apm login -u <员工ID> --url <url>       # 登录并覆盖/写入 base-url
apm logout                               # 清除 token、employeeId，保留 base-url（及 ws-port 等）

apm init

在当前项目中：初始化标准 .apm 目录；将内置 skills 安装到 .apm/skills（按技能子目录删除后全量复制）；将 templates/commands 中的命令文件合并到 .cursor/commands（按文件名写入/覆盖，不删除其它已有文件）。需在含 .cursor、.apm 或 .git 的项目根（或向上查找）下执行。

apm init

apm deploy-frontend

将本地构建产物目录递归上传到 MinIO（S3 兼容），对象键规则为 {分支名}/dist/{相对路径}。上传前会清空该分支在存储中的已有前缀；上传完成后会为当前 MINIO_BUCKET 设置匿名可读对象（s3:GetObject）桶策略，便于 HTTP 直链访问。

环境与凭证

• 不需要 apm login：本命令不访问业务 HTTP API。
• MinIO 连接信息只从 process.env 读取 MINIO_*；执行前会尝试加载当前工作目录下固定路径 .apm/.env（若某键在环境中已存在，则不会被 .env 覆盖）。
• 常用变量示例：MINIO_ENDPOINT、MINIO_PORT、MINIO_USE_SSL、MINIO_BUCKET、MINIO_ACCESS_KEY、MINIO_SECRET_KEY。

请在含有 .apm/.env 的目录作为当前目录运行（例如在 monorepo 根目录执行，而不是在子项目目录下）。

用法示例

apm deploy-frontend feat/foo
# 默认上传当前目录下的 ./dist

apm deploy-frontend feat/foo --dir ./apps/fe/dist

本仓库内联调

在仓库根目录已配置 .apm/.env 的前提下，可在 packages/cli 下执行（会先切到 monorepo 根再调用 deploy-frontend，以便读到根目录的 .apm/.env）：

cd packages/cli
rushx build
rushx apm:deploy-frontend:test

默认将 packages/cli/dist 上传到 MinIO 前缀 cli-publish-test/dist/，用于验证 MinIO 连通与上传逻辑。

凭证与哪些命令需要登录

除 config、init、login、logout、update、ws、chat、deploy-frontend、deploy-backend 外，其余子命令会在执行前从配置文件读取 baseUrl、token、employeeId；未配置完整时会提示先执行 apm login。

apm ws 可单独用 --url、--token 覆盖配置文件，不依赖上述 preAction 注入逻辑。

apm comment（需求内容版本评论）

| 子命令 | 说明 | |--------|------| | comment update | 提交评论正文：仅「已创建」状态可写，成功后变为「待处理」 | | comment process | 将指定版本下你名下「待处理」评论标为已处理并创建新版本（同步需求正文） |

apm comment update --id <评论id> --content "评论正文"

apm comment process --requirement-id <需求id> --version-seq <n> --content "新版本正文"
apm comment process --requirement-id <需求id> --version-seq <n> --content-file ./updated.md

--version-seq 为该需求下的版本序号，与界面 v1、v2 一致（不是数据库里的版本行 id）。

apm requirement

requirement version content

按需求 id 与版本序号获取该版本正文（stdout 输出 JSON，含 content、comments 等）。

apm requirement version content --requirement-id <需求id> --version-seq <n>

requirement test-case import

从 UTF-8 JSON 数组文件批量导入测试用例；元素字段与单条创建一致（如 title、steps，可选 expectedResult、status）。

apm requirement test-case import --requirement-id <需求id> --file ./cases.json

requirement branch set-status

更新分支状态，两种方式二选一：

1. 按分支记录 id（branches/list 返回的 id）：

apm requirement branch set-status --branch-id <分支记录id> --status <状态>

2. 按需求 id + 远程分支名（精确匹配）：

apm requirement branch set-status \
  --requirement-id <需求id> \
  --branch-name <远程分支名> \
  --status <状态>

状态取值与后端一致，例如：CREATED、IN_DEVELOPMENT、PENDING_TEST、MERGED。

requirement defect set-status

按缺陷 id 更新状态。

apm requirement defect set-status --defect-id <id> --status <状态>

apm ws

启动员工 WebSocket 客户端，连接后等待服务端推送（Ctrl+C 退出）。

常用选项：

• --version：打印当前 CLI 包版本后退出
• -u, --url：服务根地址（覆盖配置中的 base-url）
• --token：员工 token（可覆盖配置文件）
• -p, --port：WebSocket 端口（覆盖 apm config 中的 ws-port）
• --employee-id：仅用于日志展示，可选

员工 CLI 口令

员工 CLI 口令在库中为可配置项；在 Web 端维护员工节点时填写，或通过后端员工更新接口设置后再执行 apm login。

SDK

本包导出 createApmClient、requestConfig 等，供在 Node 中调用与 CLI 相同的 HTTP API；详见包内 package.json 的 exports 与 dist 类型声明。