fm-cli

fm-cli 是 FM Platform 的本地命令行控制面，面向人工操作和本地 Agent。CLI 通过 OAuth2 Authorization Code + PKCE 登录平台，再使用当前用户身份调用后端 /agent/cli/** 能力。

本地项目路径

| 项目 | 路径 | 说明 | |------|------|------| | 后端平台 | E:\project\workspace\fm\fm-platform | OAuth2 Server、Agent CLI Gateway、能力清单、审计日志 | | 前端平台 | E:\project\workspace\fm\fm-platform-ui | OAuth2 授权确认页和平台管理界面 | | CLI | E:\project\workspace\fm\fm-cli | 本地 Agent 控制平台的命令行工具 | | Agent Skills | E:\project\workspace\fm\fm-agent-skills | 面向用户端本地 Agent 分发的 fm-* Skill |

构建

go test ./...
go build -o fm-cli.exe .

带版本信息构建：

.\scripts\build.ps1 -Version 0.1.1
.\fm-cli.exe version
.\fm-cli.exe version --json

跳过测试构建：

.\scripts\build.ps1 -Version 0.1.1 -SkipTests

生成 npm/Gitee 发布用的多平台产物：

.\scripts\release.ps1 -Version 0.1.1

产物会输出到 dist/，包含 Windows、Linux、macOS 的 amd64/arm64 压缩包，以及 checksums.txt。脚本默认同步更新根目录 checksums.txt，便于 npm 包校验下载产物；仅本地验证时可加 -NoPackageChecksums。

npm 安装脚本默认优先从 Gitee Release 下载二进制产物：

https://gitee.com/evanhon-work/fm-cli/releases/download/v<version>/<archive>

可通过 FM_CLI_BINARY_URL 指定完整下载地址，或通过 FM_CLI_BINARY_BASE_URL 指定基础地址；均会优先于默认 Gitee/GitHub 地址。

安装到 AI Agent

fm-cli install 会完成三件事：

• 写入本地 CLI 配置：web_url、api_url。
• 通过 npx skills add 从 https://skills.evanhon.top 分发本地 Agent Skill。
• 让 Agent 知道必须通过 fm-cli 控制平台，并能按业务域自动触发。

默认 Skill 分发模式是 npx：

• 默认执行：

npx skills add https://skills.evanhon.top --skill '*' -g -a '*' -y

• 默认会分发 3 个 Skill：
  • fm-system：用户、部门、角色、菜单、岗位。
  • fm-codeless：表单、列表、公式。
  • fm-workflow：流程分类、流程详情、流程创建。
• --agent all 是默认值，会传给 npx skills -a '*'；--agent codex 会传 codex；--agent claude 会映射为 claude-code；--agent auto 当前等价于 all。
• --skills-source <source> 默认是 https://skills.evanhon.top，也可配合 --local-skills 指定本地开发目录，例如 E:\project\workspace\fm\fm-agent-skills。

本地 Agent 发现入口来自 fm-agent-skills。服务端 /agent/cli/skills 返回的是按当前登录用户权限过滤后的平台运行时文档，例如 form-designer、list-designer、workflow-designer、formula、icon。Agent 进入某个领域后，应按 Skill 提示继续使用 fm-cli skills read <name> --refresh 读取平台当前版本文档。

发布到 npm 后，可使用一行命令安装：

npx @fm-platform/fm-cli@latest install

默认会写入正式环境地址：

web_url = https://fm.evanhon.top
api_url = https://fm.evanhon.top/prod-api

如果需要连接其它环境，可以在 npx 安装时直接指定：

npx @fm-platform/fm-cli@latest install --web-url https://fm.evanhon.top --api-url https://fm.evanhon.top/prod-api

例如本地开发环境：

npx @fm-platform/fm-cli@latest install --web-url http://localhost:5666 --api-url http://localhost:8080

交互终端下，npm 包装层安装向导会先安装/升级全局 fm-cli，再写配置和 Skill，并可继续触发 OAuth2 登录。--login、--skip-login、--skip-global-install 是 npm 包装层参数，不是原生 fm-cli.exe install 参数。常用控制参数：

npx @fm-platform/fm-cli@latest install --login
npx @fm-platform/fm-cli@latest install --agent codex --skip-login
npx @fm-platform/fm-cli@latest install --agent all --skip-login
npx @fm-platform/fm-cli@latest install --skip-global-install --skip-login
npx @fm-platform/fm-cli@latest install --skills-source E:\project\workspace\fm\fm-agent-skills

本地已构建二进制时，可直接执行：

.\fm-cli.exe install
.\fm-cli.exe install --agent codex
.\fm-cli.exe install --skills-source E:\project\workspace\fm\fm-agent-skills
.\fm-cli.exe install --no-skill

--agent 支持 all、codex、claude、auto。默认 all 会安装到 npx skills 支持的所有 Agent；auto 当前也按 all 处理。安装后需要重启 AI Agent，使其重新加载 fm-* Skill。

AI Agent 辅助安装时，可以让 Agent 执行：

请安装 FM Platform CLI，并运行：
npx @fm-platform/fm-cli@latest install
安装后帮我确认 fm-cli doctor --json 可以执行，然后提醒我重启 AI Agent。

当前 npm 包装层已就绪；发布前需要先发布 npm 包，并发布对应的原生二进制 release assets。

卸载本地 Agent 集成：

.\fm-cli.exe uninstall
.\fm-cli.exe uninstall --agent claude
.\fm-cli.exe uninstall --keep-config --keep-auth
.\fm-cli.exe uninstall --dry-run --json

默认卸载会撤销/清理 OAuth2 token、删除本地配置文件，并删除已安装的 fm-* Skill；没有安装记录时回退删除 fm-system、fm-codeless、fm-workflow。命令不会删除当前正在运行的 fm-cli.exe；npm 全局包装层可通过 npm uninstall -g @fm-platform/fm-cli 删除。

登录

默认 Web 地址是 https://fm.evanhon.top，默认 API 地址是 https://fm.evanhon.top/prod-api。 auth login 默认申请 openid userinfo agent；其中 agent 用于访问平台 /agent/cli/** 控制面，具体业务能力仍按当前用户的平台权限校验。

.\fm-cli.exe auth login
.\fm-cli.exe auth status --verify
.\fm-cli.exe whoami --json

指定平台地址：

.\fm-cli.exe auth login --web-url https://fm.evanhon.top --api-url https://fm.evanhon.top/prod-api

浏览器授权回调页只负责提示授权结果；最终是否登录成功以命令行换取 token 并保存配置后的输出为准。

退出登录会撤销本地 token，并尽量撤销服务端 token：

.\fm-cli.exe auth logout

Agent 通用命令

.\fm-cli.exe agent list
.\fm-cli.exe agent list --json --refresh
.\fm-cli.exe agent schema /user/query --json
.\fm-cli.exe agent call /user/query --data '{"pageNum":1,"pageSize":10}' --json

写操作建议先 dry-run，再复用同一个 request-id 执行：

.\fm-cli.exe user delete --user-ids 999999 --dry-run
.\fm-cli.exe user delete --user-ids 999999 --yes --request-id <request-id>

Skill 文档

.\fm-cli.exe skills list
.\fm-cli.exe skills read form-designer --refresh
.\fm-cli.exe skills read list-designer --refresh
.\fm-cli.exe skills read workflow-designer --refresh

本地 Agent 应通过 fm-agent-skills 触发业务域 Skill，并通过 fm-cli 调用平台，不直接拼后端 HTTP 接口，不读取本地 token 文件。

领域快捷命令

系统管理：

.\fm-cli.exe user list --page-size 10
.\fm-cli.exe user detail --user-name admin
.\fm-cli.exe dept list
.\fm-cli.exe role list
.\fm-cli.exe menu list
.\fm-cli.exe post list

无代码和流程：

.\fm-cli.exe form list
.\fm-cli.exe form components
.\fm-cli.exe form dict-data --dict-type sys_user_sex
.\fm-cli.exe list models
.\fm-cli.exe formula functions
.\fm-cli.exe workflow categories
.\fm-cli.exe workflow spel --page-size 1

写操作统一支持 --dry-run、--yes、--request-id、--json。

输出契约

• 成功 JSON 保持命令原始响应结构，不额外包一层 ok=true。
• CLI 失败时输出稳定错误 envelope：ok=false、code、message、hint。
• doctor --json 是诊断命令例外，保留顶层 ok。
• 本地 Agent 调用 agent call 和领域快捷命令后，应按后端 code == 200 判断业务成功。

审计查询

.\fm-cli.exe audit list --page-size 5
.\fm-cli.exe audit list --api-name /user/delete --write=true --json
.\fm-cli.exe audit get <request-id>

审计查询依赖后端已包含 /agent/cli/audit/** 接口，并已执行 fm-platform\sql\18-alter-agent-audit-cli-request-index.sql。

Completion

Cobra 已内置 completion 生成：

.\fm-cli.exe completion powershell
.\fm-cli.exe completion bash
.\fm-cli.exe completion zsh

PowerShell 临时加载示例：

.\fm-cli.exe completion powershell | Out-String | Invoke-Expression

诊断

.\fm-cli.exe doctor
.\fm-cli.exe doctor --json

doctor 会检查本地配置、Web/API 连通性、OAuth2 token、用户信息、Agent 能力和 Skill 服务。已执行过 fm-cli install 时，doctor 会报告本地 Agent Skill 安装记录；升级 Skill 使用 fm-cli agent-skills update。