@gencode/cli

包定位

@gencode/cli 负责 CLI 入口与进程级执行编排。 它的作用是把 agent 执行能力包装成可以被外部系统消费的命令行为。

负责内容

这个包适合承载：

• CLI 入口
• 命令解析与分发
• 单次任务执行编排
• stdout 输出处理
• HTTP callback 适配
• websocket stream 适配
• 命令配置与运行时装配

不负责内容

这个包不应成为以下能力的主要归属位置：

• agent 领域逻辑
• 本该属于 @gencode/agents 的 session 核心行为
• 本该属于 @gencode/agents 的 memory 领域内部逻辑
• 应沉淀到 @gencode/shared 的共享协议定义

当前源码入口

阅读本包时，建议先看：

• src/bin.ts —— CLI 可执行入口
• src/program.ts —— 命令编排
• src/output.ts —— 输出处理
• src/config.ts —— 运行配置
• src/auth.ts —— 认证相关配置
• src/plugins-config.ts —— 插件配置装配
• src/logger.ts —— 日志工具

当前较有代表性的测试：

• src/build-config.test.ts
• src/logger.test.ts

当 dist/ 存在时，应将其视为生成产物，而不是主要编辑目标。

与其他包的关系

• @gencode/cli 依赖 @gencode/agents 提供真实的 agent 执行与领域能力
• @gencode/shared 应提供本包消费的稳定共享协议类型
• @gencode/web 应通过 CLI 使用能力，而不是绕过它直接调用 @gencode/agents

开发说明

当你在这里增加新 CLI 能力时：

• 保持所有进程外通信统一收口在这里
• 不要把领域所有权从 @gencode/agents 拉到 CLI 层
• 优先复用 @gencode/shared 中的共享协议结构
• 保持命令行为小、显式、可测试

可选 embedding 模型安装

智能主题拆分会使用 transformers.js 本地 embedding 模型做历史 topic 检索。 @gencode/cli 的 postinstall 只在安装环境显式设置 AIMAX_EMBEDDING_MODEL_URL 时下载模型；未设置时直接跳过，不访问网络。

推荐由部署系统提供企业内网模型包：

AIMAX_EMBEDDING_MODEL_URL=https://example.internal/aimax/bge-small-zh-v1.5.tar.gz \
AIMAX_EMBEDDING_MODEL_SHA256=<sha256> \
npm install -g @gencode/cli

下载后模型会放到 CLI 包安装目录的 models/ 下，并归一化为：

models/Xenova/bge-small-zh-v1.5/config.json

运行时 aimax run / aimax resume 会自动把该 models/ 根目录传给 @gencode/agents。如果 postinstall 被跳过或安装时使用了 --ignore-scripts，主题拆分仍可运行，但本地 embedding 检索会降级。

验证

在工作区根目录可运行：

pnpm -C source/packages/cli test
node --test source/packages/cli/scripts/download-embedding-model.node-test.mjs

工作区级验证：

pnpm -C source typecheck
pnpm -C source test

相关规格文档

• ../../../specs/system-overview.md
• ../../../specs/architecture-boundaries.md
• ../../../specs/development-workflow.md
• ../../../specs/repo-map.md