11 KiB

Raw Permalink Blame History

status	date
active	2026-06-05

feat: AgentKit CLI + 独立部署能力

类型: feat 文件: docs/plans/2026-06-05-007-feat-agentkit-cli-deployment-plan.md 深度: Standard — 新增 CLI 模块 + 部署配置改造，涉及 6 个新文件 + 4 个修改

问题框架

AgentKit v2 Phase 1 + Phase 2 已实现 12 个核心模块、544 个测试通过，但无法独立部署和使用：

无 CLI — 没有 agentkit 命令行工具，只能写 Python 脚本或手动敲 uvicorn 命令
无 __main__.py — 不能 python -m agentkit 启动
无 init 脚手架 — 新用户不知道如何初始化配置
Dockerfile 硬编码 GEO — CMD 直接调用 configs.geo_server，不是通用入口
无生产级 docker-compose — 只有 docker-compose.test.yml（测试用），缺少生产部署配置

架构总览

agentkit CLI (Typer)
├── agentkit init          → 生成 agentkit.yaml + .env.example + skills/ + docker-compose.yaml
├── agentkit serve         → uvicorn agentkit.server.app:create_app --factory
├── agentkit task submit   → AgentKitClient.submit_task()
├── agentkit task status   → AgentKitClient.get_task_status()
├── agentkit task list     → AgentKitClient.list_tasks()
├── agentkit task cancel   → AgentKitClient.cancel_task()
├── agentkit skill list    → SkillRegistry.list_skills() (本地) 或 API (远程)
├── agentkit skill load    → SkillLoader.load_from_file() (本地)
├── agentkit skill info    → Skill 详情
├── agentkit usage         → LLMGateway.get_usage_summary()
├── agentkit health        → /api/v1/health
└── agentkit version       → importlib.metadata.version()

核心设计决策：CLI 是薄封装层，底层复用已有的 AgentKitClient（远程模式）和 create_app() + 各 Registry（本地模式）。

关键技术决策

KTD-1: CLI 框架选择 Typer

决策: 使用 Typer（而非 Click 或 argparse）

理由:

与 FastAPI 同作者，类型注解驱动，团队学习成本最低
底层基于 Click，可无缝使用 Click 生态
Rich 集成提供开箱即用的彩色输出、表格、进度条
自动生成帮助文档和 shell 补全
项目已使用 Pydantic v2 + 类型注解，Typer 风格完美契合

KTD-2: 双模式运行（本地 vs 远程）

决策: CLI 支持两种运行模式

本地模式（默认）: 直接 import 模块执行，无需 Server 运行
远程模式（--server-url）: 通过 HTTP API 调用 AgentKit Server

理由: 开发调试时直接本地运行更方便；生产环境通过 Server 远程调用更安全。agentkit task submit 在本地模式下直接创建 Agent 执行，在远程模式下调用 API。

KTD-3: 配置文件格式 agentkit.yaml

决策: 使用 YAML 格式，支持 ${ENV_VAR} 环境变量替换

理由: 与现有 configs/llm_config.yaml 格式一致，复用 _substitute_env_vars() 逻辑。YAML 比 TOML 更适合嵌套配置，比 JSON 支持注释。

KTD-4: Dockerfile 入口改为 CLI

决策: Dockerfile ENTRYPOINT 改为 agentkit CLI，CMD 默认 serve

理由: 统一入口，支持 docker run agentkit task submit ... 等一次性命令，比硬编码 uvicorn 更灵活。

实施单元

U1. CLI 框架搭建 + `serve` + `version` + `health`

Goal: 建立 CLI 模块骨架，实现最基础的 3 个命令

Dependencies: 无

Files:

src/agentkit/cli/__init__.py (新建)
src/agentkit/cli/main.py (新建) — Typer app + serve/version/health 命令
src/agentkit/__main__.py (新建) — python -m agentkit 入口
pyproject.toml (修改) — 添加 typer>=0.12 依赖 + [project.scripts] 入口点
Dockerfile (修改) — ENTRYPOINT 改为 agentkit

Approach:

main.py 创建 app = typer.Typer() 并注册子命令
serve 命令调用 uvicorn.run() 启动 create_app() 工厂函数
version 命令使用 importlib.metadata.version("fischer-agentkit")
health 命令调用 http://localhost:{port}/api/v1/health
__main__.py 简单调用 app()
pyproject.toml 添加 [project.scripts] agentkit = "agentkit.cli.main:app"

Test scenarios:

agentkit version 输出正确版本号
agentkit serve --help 显示帮助信息
agentkit health 在 server 未运行时返回连接错误
agentkit health 在 server 运行时返回健康状态
python -m agentkit version 等同于 agentkit version
Dockerfile ENTRYPOINT 正确执行 agentkit serve

Verification: pip install -e . && agentkit version 输出版本号

U2. `task` 命令组（submit/status/list/cancel）

Goal: 实现任务管理的 CLI 命令

Dependencies: U1

Files:

src/agentkit/cli/task.py (新建) — task 子命令组
src/agentkit/cli/main.py (修改) — 注册 task 子命令

Approach:

task submit:
- 本地模式: 创建 Agent → 执行任务 → 输出结果
- 远程模式: AgentKitClient.submit_task() / submit_task_async()
- --mode sync|async 控制同步/异步
- --stream 启用 SSE 流式输出
task status <task_id>: 调用 AgentKitClient.get_task_status()
task list: 调用 AgentKitClient.list_tasks()，Rich 表格输出
task cancel <task_id>: 调用 AgentKitClient.cancel_task()
输入数据通过 --input 参数（JSON 字符串）或 --input-file 参数（JSON 文件路径）

Test scenarios:

agentkit task submit --skill content_generator --input '{"topic":"AI"}' 提交同步任务
agentkit task submit --mode async --skill content_generator --input '{"topic":"AI"}' 返回 task_id
agentkit task status <task_id> 显示任务状态
agentkit task list 列出所有任务
agentkit task list --status completed 过滤已完成任务
agentkit task cancel <task_id> 取消运行中任务
agentkit task submit --input-file input.json 从文件读取输入
远程模式下所有命令正确调用 API
本地模式下直接执行无需 Server

Verification: agentkit task submit --help 显示完整帮助

U3. `skill` 命令组（list/load/info）

Goal: 实现技能管理的 CLI 命令

Dependencies: U1

Files:

src/agentkit/cli/skill.py (新建) — skill 子命令组
src/agentkit/cli/main.py (修改) — 注册 skill 子命令

Approach:

skill list: 列出已注册技能，Rich 表格输出（name, mode, description）
skill load <path>: 从 YAML 文件加载技能到 Registry
skill info <name>: 显示技能详情（config 完整信息）
本地模式直接操作 SkillRegistry，远程模式调用 /api/v1/skills API

Test scenarios:

agentkit skill list 列出所有技能
agentkit skill load ./my_skill.yaml 加载技能
agentkit skill info content_generator 显示技能详情
无技能注册时 skill list 显示空列表
加载无效 YAML 文件报错

Verification: agentkit skill list 输出技能表格

U4. `init` 命令 + `usage` 命令

Goal: 实现项目初始化和用量查询

Dependencies: U1

Files:

src/agentkit/cli/init.py (新建) — init 命令
src/agentkit/cli/usage.py (新建) — usage 命令
src/agentkit/cli/main.py (修改) — 注册 init/usage 子命令
src/agentkit/cli/templates.py (新建) — 模板文件内容（agentkit.yaml、.env.example、docker-compose.yaml、示例 skill）

Approach:

init 命令:
- 交互式引导（使用 Typer prompt）或 --non-interactive 使用默认值
- 生成文件: agentkit.yaml, .env.example, skills/example_skill.yaml, docker-compose.yaml
- agentkit.yaml 包含 server/llm/memory/skills/logging 配置
- .env.example 包含 API key 占位符
- docker-compose.yaml 包含 agentkit + redis + postgres 服务
- 如果文件已存在，询问是否覆盖
usage 命令:
- 本地模式: 从 LLMGateway.UsageTracker 获取统计
- 远程模式: 调用 /api/v1/llm/usage API
- --agent 过滤特定 Agent
- --format table|json 输出格式

Test scenarios:

agentkit init 在空目录生成完整配置文件
agentkit init --non-interactive 使用默认值生成
agentkit init 文件已存在时提示覆盖
生成的 agentkit.yaml 包含所有必要配置段
生成的 .env.example 包含 API key 占位符
生成的 docker-compose.yaml 包含 3 个服务
agentkit usage 显示用量统计表格
agentkit usage --agent content_generator 过滤特定 Agent
agentkit usage --format json 输出 JSON 格式

Verification: mkdir /tmp/test-init && cd /tmp/test-init && agentkit init && ls -la 看到生成的文件

U5. Dockerfile 改造 + 生产级 docker-compose

Goal: 改造部署配置，支持 CLI 入口 + 生产部署

Dependencies: U1

Files:

Dockerfile (修改) — ENTRYPOINT 改为 agentkit
docker-compose.yaml (新建) — 生产部署配置
.dockerignore (修改/新建) — 排除 tests/docs

Approach:

Dockerfile:
- ENTRYPOINT ["agentkit"]
- CMD ["serve", "--host", "0.0.0.0", "--port", "8001"]
- 复制 configs/ 目录到镜像
- 保持多阶段构建 + 非 root 用户
docker-compose.yaml:
- agentkit 服务: build ., command: serve, ports: 8001, env_file: .env
- redis 服务: redis:7-alpine, healthcheck
- postgres 服务: pgvector/pgvector:pg15, healthcheck, volume
- agentkit depends_on redis + postgres (condition: service_healthy)
.dockerignore: 排除 tests/, docs/, .git/, pycache/

Test scenarios:

docker build -t agentkit . 构建成功
docker run agentkit version 输出版本号
docker run agentkit serve 启动 Server
docker-compose up 启动完整环境
docker-compose exec agentkit agentkit health 健康检查通过

Verification: docker build -t agentkit . && docker run agentkit version

U6. README 更新 + 集成测试

Goal: 更新文档，添加 CLI 使用示例，编写集成测试

Dependencies: U1-U5

Files:

README.md (修改) — 添加 CLI 使用章节
tests/unit/test_cli.py (新建) — CLI 命令测试

Approach:

README 添加:
- CLI 安装和快速开始
- 所有命令的使用示例
- Docker 部署说明
- agentkit init 生成的文件结构说明
测试:
- 使用 typer.testing.CliRunner 测试所有命令
- Mock 远程 API 调用
- 测试 init 生成的文件内容

Test scenarios:

agentkit --help 显示所有子命令
agentkit task --help 显示 task 子命令
agentkit init --non-interactive 生成正确文件
agentkit skill list 在无技能时显示空列表
agentkit version 输出格式正确
agentkit usage 在无用量时显示空表格

Verification: pytest tests/unit/test_cli.py -v 全部通过

范围边界

包含

CLI 模块（Typer 框架）
__main__.py 入口
init 脚手架生成
Dockerfile 改造
生产级 docker-compose
README 更新

不包含

交互式 REPL 模式（后续可加）
Web UI 管理界面
CI/CD pipeline 配置
Kubernetes 部署配置
插件市场/注册中心

执行顺序

U1 (CLI 骨架) → U2 (task) + U3 (skill) + U4 (init/usage) 并行 → U5 (Docker) → U6 (README + 测试)

U2/U3/U4 互相独立，可并行实现。U5 依赖 U1（Dockerfile 需要 CLI 入口）。U6 依赖所有前置单元。

11 KiB Raw Permalink Blame History Unescape Escape

feat: AgentKit CLI + 独立部署能力

问题框架

架构总览

关键技术决策

KTD-1: CLI 框架选择 Typer

KTD-2: 双模式运行（本地 vs 远程）

KTD-3: 配置文件格式 agentkit.yaml

KTD-4: Dockerfile 入口改为 CLI

实施单元

U1. CLI 框架搭建 + serve + version + health

U2. task 命令组（submit/status/list/cancel）

U3. skill 命令组（list/load/info）

U4. init 命令 + usage 命令

U5. Dockerfile 改造 + 生产级 docker-compose

U6. README 更新 + 集成测试

范围边界

包含

不包含

执行顺序

11 KiB

Raw Permalink Blame History

U1. CLI 框架搭建 + `serve` + `version` + `health`

U2. `task` 命令组（submit/status/list/cancel）

U3. `skill` 命令组（list/load/info）

U4. `init` 命令 + `usage` 命令