FOCO CLI

FOCO 备考平台的命令行工具，供团队成员通过终端或 AI 编码工具（Cursor、Claude Code 等）调用。

安装

npm install -g foco-cli

登录

foco login --dev              # 本地开发服务器 (localhost:3001)
foco login https://your.com   # 指定服务器
foco auth status              # 查看状态
foco auth logout              # 登出

凭证存储在 ~/.foco/config.json。

命令参考

认证

| 命令 | 说明 | |------|------| | foco login [--dev] [-u <user> -p <pass>] | 登录 | | foco auth status | 查看状态 | | foco auth logout | 登出 |

考试 (exams)

| 命令 | 说明 | |------|------| | foco exams list | 列表 | | foco exams show <id> | 详情 | | foco exams create --code <code> --name <name> | 创建 | | foco exams update <id> | 更新 | | foco exams delete <id> [--cascade] [-f] | 删除（--cascade 级联删除关联数据） |

CFA 等级 (cfa-levels)

CFA 考试的层级结构：Level I / Level II / Level III。

| 命令 | 说明 | |------|------| | foco cfa-levels list --exam-id <id> | 列表 | | foco cfa-levels show <id> | 详情 | | foco cfa-levels create --exam-id <id> --code <code> --name <name> | 创建 | | foco cfa-levels update <id> | 更新 | | foco cfa-levels delete <id> | 删除 |

CFA 科目 (cfa-subjects)

每个等级下的科目（如 Ethical Standards、Quantitative Methods 等）。

| 命令 | 说明 | |------|------| | foco cfa-subjects list --level-id <id> | 列表 | | foco cfa-subjects show <id> | 详情 | | foco cfa-subjects create --level-id <id> --code <code> --name <name> | 创建 | | foco cfa-subjects update <id> | 更新 | | foco cfa-subjects delete <id> | 删除 |

CFA 学习模块 (cfa-modules)

科目下的学习模块。

| 命令 | 说明 | |------|------| | foco cfa-modules list --subject-id <id> | 列表 | | foco cfa-modules show <id> | 详情 | | foco cfa-modules create --subject-id <id> --code <code> --name <name> | 创建 | | foco cfa-modules update <id> | 更新 | | foco cfa-modules delete <id> | 删除 |

CFA 考点 (cfa-knowledge-points)

模块下的考点，支持 qa / knowledge / summary_note 三种类型。

| 命令 | 说明 | |------|------| | foco cfa-knowledge-points list [--exam-id <id>] [--type <type>] | 列表 | | foco cfa-knowledge-points create --exam-id <id> --type <type> --title <t> --content <c> | 创建 | | foco cfa-knowledge-points update <id> | 更新 | | foco cfa-knowledge-points delete <id> | 删除 |

type 可选值：qa | knowledge | summary_note

CFA 产品配置 (cfa-config)

| 命令 | 说明 | |------|------| | foco cfa-config show | 查看 CFA 产品配置 | | foco cfa-config set-customer-service-qr --file <path> | 发布 CFA 客服二维码 |

客服二维码仅支持 PNG、JPEG、WebP，最大 2MB；服务端要求图片为边长 300-2000 px 的正方形。

IIQE 卷 (iiqe-units)

IIQE 考试的卷别（卷一保险、卷三汽车等）。

| 命令 | 说明 | |------|------| | foco iiqe-units list --exam-id <id> | 列表 | | foco iiqe-units show <id> | 详情 | | foco iiqe-units create --exam-id <id> --code <code> --name <name> | 创建 | | foco iiqe-units update <id> [--required-product-id <id>] | 更新（可绑定付费产品） | | foco iiqe-units delete <id> | 删除 |

IIQE 大纲 (iiqe-syllabi)

每卷下的大纲版本，有版本标签和激活状态。

| 命令 | 说明 | |------|------| | foco iiqe-syllabi list --unit-id <id> | 列表 | | foco iiqe-syllabi show <id> | 详情 | | foco iiqe-syllabi update <id> | 更新 | | foco iiqe-syllabi delete <id> | 删除 |

IIQE 章节 (iiqe-sections)

大纲下的树形章节结构，支持多级嵌套（parentId）。

| 命令 | 说明 | |------|------| | foco iiqe-sections list --syllabus-id <id> | 列表 | | foco iiqe-sections show <id> | 详情 | | foco iiqe-sections update <id> [--parent-id <id>] | 更新 | | foco iiqe-sections delete <id> | 删除 |

版本 (editions)

发布后的考试版本快照（基于 CFA level / IIQE unit 构建），状态流转 draft → published → retired。

| 命令 | 说明 | |------|------| | foco editions list [--paper-type <t>] [--status <s>] | 列表（paper-type: cfa_level|iiqe_unit；status: draft|published|retired） | | foco editions show <id> | 详情 | | foco editions create --paper-type <t> --paper-id <id> --name <n> | 创建（基于 level/unit 构建快照） | | foco editions update <id> [--name <n>] [--description <t>] [--clear-description] | 更新（仅 draft 可改 name/description） | | foco editions delete <id> | 删除（已发布版本需先 retire） | | foco editions publish <id> | 发布（重建快照，自动下架同 paper 旧版本） | | foco editions retire <id> | 下架（仅 published 可下架） | | foco editions export <id> [-o <path>] [--stdout] | 导出 Markdown（默认写 <版本名>.md；--stdout 输出到终端便于管道） |

题目 (questions)

| 命令 | 说明 | |------|------| | foco questions list [--exam-id <id>] [--type <type>] [--keyword <kw>] | 列表 | | foco questions reconcile-revisions | 为当前内容与最新历史不一致的题目补一条 revision | | foco questions show <id> | 详情 | | foco questions links --question-id <id> | 查看题目挂载到哪些 CFA 考点 | | foco questions links --kp-id <id> | 查看 CFA 考点下挂载了哪些题目 | | foco questions link-kp --question-id <id> --kp-id <id> [--role primary] | 挂载题目到 CFA 考点 | | foco questions link-kp --file <path> --dry-run | 预览批量挂载 | | foco questions link-kp --file <path> --apply | 执行批量挂载 | | foco questions unlink-kp --question-id <id> --kp-id <id> | 移除题目与 CFA 考点的挂载关系 | | foco questions format --id <id> [--fields <f>] [--apply] | AI 格式化题目 | | foco questions update-title --id <id> --title <t> | 更新标题 | | foco questions update-title --file <path> | 批量更新标题 |

type 可选值：single | multiple | true_false

批量挂载文件格式：

[
  { "questionId": "721", "knowledgePointId": "1", "role": "primary" }
]

教材 (textbooks)

| 命令 | 说明 | |------|------| | foco textbooks list | 教材列表 | | foco textbooks show <id> | 教材详情 | | foco textbooks content <id> --section-id <id> \| --module <n\|mN> [-o path] | 读取 section / Learning Module 子树纯文本（默认 stdout） | | foco textbooks export-questions <id> [-o path] | 导出已关联题目 | | foco textbooks reference-module-stats [-o path] | 统计 Mock/Pack1000 等参考题在各 Learning Module 的题量与占比 | | foco textbooks links remap <id> --file <path> [--apply] | 事务型批量迁移章节关联，默认 dry-run |

# 按 Learning Module 或章节读取教材纯文本
foco textbooks content 12 --module 3
foco textbooks content 12 --module m3 -o data/m3.txt
foco textbooks content 12 --section-id 2147

# 默认统计 Mock + Pack1000，按 -o 后缀导出
foco textbooks reference-module-stats -o data/mock-pack1000-module-counts.md
foco textbooks reference-module-stats -o data/mock-pack1000-module-counts.csv
foco textbooks reference-module-stats --export-format json --stdout

# 指定题集（alias / id / key）
foco textbooks reference-module-stats --sets mock,pack1000

批量迁移文件格式：

{
  "reason": "修复 Ethics 参考题章节挂载",
  "items": [
    { "linkId": "1543", "sectionId": "2147" }
  ]
}

foco textbooks links remap 12 --file data/ethics-remap.json
foco textbooks links remap 12 --file data/ethics-remap.json --apply

数据库备份 (backups)

| 命令 | 说明 | |------|------| | foco backups create | 立即在服务器生成数据库备份 | | foco backups list | 查看服务器备份、格式与保留策略 | | foco backups download <name> [-o path] | 下载备份，默认拒绝覆盖已有文件 |

foco backups create
foco backups list
foco backups download backup-20260717-150000.dump \
  -o data/pgsql-backups/backup-20260717-150000.dump

商品 (products)

| 命令 | 说明 | |------|------| | foco products list [--product-type <type>] | 列表 | | foco products show <id> | 详情 | | foco products create --product-type <type> --ref-id <id> --title <t> | 创建 | | foco products update <id> | 更新 | | foco products delete <id> | 删除 |

product-type 可选值：exam_level | iiqe_unit

激活码 (activation-codes)

| 命令 | 说明 | |------|------| | foco activation-codes list [--batch-no <no>] [--status <s>] | 列表 | | foco activation-codes create-batch --sku-id <id> --count <n> [--batch-no <no>] | 批量生成 |

工单 (issues)

| 命令 | 说明 | |------|------| | foco issues list [--status <s>] [--priority <p>] [--assignee-id <id>] [--related-id <id\|me>] [--search <kw>] | 列表，搜索支持标题/描述/编号 | | foco issues show <id> | 详情（含 relatedParties） | | foco issues create --title <title> [options] | 创建（可选 --related-ids） | | foco issues update <id> [options] | 更新（--related-ids 全量替换相关者） | | foco issues comment <id> -m <text> | 添加评论 | | foco issues comments <id> | 查看评论列表 | | foco issues edit-comment <id> --comment-id <cid> -m <text> | 编辑评论 | | foco issues delete-comment <id> --comment-id <cid> | 删除评论 |

status：backlog | todo | in_progress | done | cancelled priority：urgent | high | medium | low | none

foco issues create \
  --title "知识点模块开关" \
  --description "按考试配置显示哪些模块" \
  --priority high \
  --labels "frontend,backend" \
  --assignee-id 2 \
  --related-ids 3,4 \
  --due-date 2026-06-01

# 查看我作为相关者的工单
foco issues list --related-id me

# 清空相关者
foco issues update FOCO-123 --related-ids ""

Epic 目标 (epics)

| 命令 | 说明 | |------|------| | foco epics list | 列表 | | foco epics show <id> | 详情 | | foco epics create --title <t> | 创建 | | foco epics update <id> | 更新 |

项目 (projects)

| 命令 | 说明 | |------|------| | foco projects list | 列表 | | foco projects show <id> | 详情 | | foco projects create --name <n> --slug <s> | 创建 | | foco projects update <id> | 更新 | | foco projects delete <id> | 删除 |

开发日志 (changelogs)

| 命令 | 说明 | |------|------| | foco changelogs list | 列表 | | foco changelogs create --date <YYYY-MM-DD> --content <md> | 创建 | | foco changelogs update <id> --content <md> | 更新 |

每日站会 (huddles)

| 命令 | 说明 | |------|------| | foco huddles list [--date <YYYY-MM-DD>] | 列表 | | foco huddles show <id> | 详情 | | foco huddles create --date <YYYY-MM-DD> --content '<json>' | 创建 | | foco huddles update <id> --content '<json>' | 更新 | | foco huddles delete <id> | 删除 |

content 格式：[{"sectionName":"今日工作","content":"..."}]

知识库 (knowledge-base)

| 命令 | 说明 | |------|------| | foco knowledge-base list [--category <cat>] | 列表 | | foco knowledge-base show <id> | 详情 | | foco knowledge-base create --title <t> --slug <s> | 创建 | | foco knowledge-base update <id> | 更新 | | foco knowledge-base delete <id> | 删除 |

category：culture | product | tech | cli-docs | ops | management | general

帮助文章 (help-articles)

| 命令 | 说明 | |------|------| | foco help-articles list | 列表 | | foco help-articles show <id> | 详情 | | foco help-articles create --title <t> --slug <s> | 创建 | | foco help-articles update <id> | 更新 | | foco help-articles delete <id> | 删除 |

讨论 (threads)

| 命令 | 说明 | |------|------| | foco threads list | 列表 | | foco threads show <id> | 详情 | | foco threads update <id> --status <s> | 更新状态 | | foco threads reply <id> -m <text> | 回复 |

status：open | resolved | closed

反馈 (feedback)

| 命令 | 说明 | |------|------| | foco feedback list [--state <s>] [--labels <l>] | 列表 | | foco feedback show <number> | 详情 | | foco feedback create --title <t> | 创建 | | foco feedback update <number> | 更新 |

管理员 (admins)

| 命令 | 说明 | |------|------| | foco admins list | 列表 | | foco admins show <id> | 详情 | | foco admins create --username <u> --password <p> | 创建 | | foco admins update <id> | 更新 | | foco admins disable <id> | 禁用 | | foco admins enable <id> | 启用 |

用户 (users)

| 命令 | 说明 | |------|------| | foco users list [--keyword <kw>] | 列表 |

订单 (orders)

| 命令 | 说明 | |------|------| | foco orders list [--status <s>] | 列表 |

仪表盘 (dashboard)

| 命令 | 说明 | |------|------| | foco dashboard overview [--range <7d\|30d>] | 总览 | | foco dashboard learning [--range <7d\|30d>] | 学习数据 | | foco dashboard products [--range <7d\|30d>] | 商品数据 |

统计 (stats)

| 命令 | 说明 | |------|------| | foco stats | 查看统计数据 |

集成配置

| 命令 | 说明 | |------|------| | foco opencode-server get | 查看 OpenCode Server 配置 | | foco opencode-server set [--url <url>] [--password <pw>] | 更新配置 | | foco ai-config get | 查看 AI 模型配置 | | foco ai-config set [--api-key <key>] [--model <model>] | 更新配置 |

AI 提示词 (prompt-groups / prompt-templates)

| 命令 | 说明 | |------|------| | foco prompt-groups list | 分组列表 | | foco prompt-groups show <id> | 分组详情 | | foco prompt-groups create --name <n> --slug <s> | 创建分组 | | foco prompt-templates list <groupId> | 模板列表 | | foco prompt-templates create <groupId> --name <n> | 创建模板 | | foco prompt-templates update <id> | 更新模板 |

自更新

| 命令 | 说明 | |------|------| | foco update | 检查新版本 | | foco upgrade | 升级到最新版 |

输出格式

所有命令输出结构化 JSON：

{ "status": "ok", "data": { ... } }

错误时输出到 stderr，返回非零退出码。

开发

cd cli
npm run dev       # tsx 热重载开发
npm run build     # TypeScript 编译

发布

cd cli
npm run dist      # build + pack
npm publish --access public --registry https://registry.npmjs.org/