API 参考

REST API 接口文档，用于集成和扩展 AxonCog 功能

快速开始

# 启动 API 服务

axoncog serve --port 8080

# 测试 API

curl http://localhost:8080/api/status

认证方式

大部分 API 需要在请求头中携带 API Key：

Authorization: Bearer YOUR_API_KEY

API Key 可通过 axoncog key generate 命令生成

对话

POST/api/chat

需认证

发送消息并获取 AI 回复

请求体 (JSON)

字段	类型	必填	说明
message	string	是	用户消息内容
session_id	string	否	会话 ID，不传则创建新会话
agent_id	string	否	指定 Agent ID
stream	boolean	否	是否使用流式输出 (默认: false)

响应结构

{
  "id": "string - 消息 ID",
  "content": "string - 回复内容",
  "role": "string - 角色 (assistant)",
  "created_at": "string - ISO 时间戳",
  "tokens_used": "number - 消耗的 Token 数"
}

GET/api/chat/history

需认证

获取会话历史记录

查询参数

参数名	类型	必填	说明
session_id	string	是	会话 ID
limit	number	否	返回数量限制 (默认: 50)

DELETE/api/chat/session/:id

需认证

删除指定会话

Agent 管理

GET/api/agents/list

需认证

获取所有 Agent 列表

POST/api/agents/create

需认证

创建新的 Agent

请求体 (JSON)

字段	类型	必填	说明
name	string	是	Agent 名称
model	string	是	使用的模型 ID
system_prompt	string	否	系统提示词
skills	string[]	否	技能 ID 列表

PUT/api/agents/:id

需认证

更新 Agent 配置

DELETE/api/agents/:id

需认证

删除 Agent

上下文

GET/api/context

需认证

获取当前上下文状态

响应结构

{
  "activity_type": "string - 当前活动类型",
  "active_window": "string - 活动窗口标题",
  "focused": "boolean - 是否处于专注状态",
  "work_duration": "number - 工作时长(秒)",
  "break_suggestions": "array - 休息建议"
}

GET/api/context/activities

需认证

获取活动历史记录

记忆

GET/api/memory/list

需认证

获取记忆列表

查询参数

参数名	类型	必填	说明
query	string	否	搜索关键词
tag	string	否	标签过滤
limit	number	否	(默认: 20)

POST/api/memory/store

需认证

存储新记忆

请求体 (JSON)

字段	类型	必填	说明
content	string	是	记忆内容
importance	number	否	重要性 0-1 (默认: 0.5)
tags	string[]	否	标签列表

DELETE/api/memory/:id

需认证

删除指定记忆

技能

GET/api/skills/list

需认证

获取所有技能列表

POST/api/skills/create

需认证

创建新技能

POST/api/skills/:id/execute

需认证

执行指定技能

RAG 知识库

POST/api/rag/documents/upload

需认证

上传文档到知识库

请求体 (JSON)

字段	类型	必填	说明
file	File	是	文档文件
collection	string	否	知识库集合名 (默认: default)

POST/api/rag/search

需认证

搜索知识库

请求体 (JSON)

字段	类型	必填	说明
query	string	是	搜索查询
top_k	number	否	(默认: 5)
collection	string	否

系统

GET/api/status

获取系统状态

响应结构

{
  "version": "string - 系统版本",
  "uptime": "number - 运行时长(秒)",
  "cpu_usage": "number - CPU 使用率",
  "memory_usage": "number - 内存使用率",
  "active_agents": "number - 活跃 Agent 数"
}

GET/api/providers

需认证

获取可用模型提供商列表

GET/api/cost/stats

需认证

获取成本统计

Rust SDK

如果你使用 Rust 开发，可以直接使用我们的 SDK：

Cargo.toml

[dependencies]
axoncog-sdk = "0.1"

示例代码

use axoncog_sdk::{Client, Config, Message};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建客户端
    let client = Client::new(Config {
        api_key: "your-api-key".to_string(),
        base_url: "http://localhost:8080".to_string(),
        ..Default::default()
    });

    // 发送消息
    let response = client
        .chat()
        .send(Message::user("你好，请帮我分析这段代码"))
        .await?;

    println!("回复: {}", response.content);
    println!("消耗 Token: {}", response.tokens_used);

    // 获取上下文
    let context = client.context().get_current().await?;
    println!("当前活动: {}", context.activity_type);

    // 存储记忆
    client.memory().store(MemoryEntry {
        content: "用户偏好使用 Rust".to_string(),
        importance: 0.7,
        tags: vec!["preference".to_string()],
    }).await?;

    Ok(())
}

错误码参考

状态码	含义	说明
200	成功	请求成功处理
400	请求错误	请求参数无效或缺失
401	未认证	缺少或无效的 API Key
403	禁止访问	没有权限执行该操作
404	未找到	请求的资源不存在
429	请求过多	超过速率限制，请稍后重试
500	服务器错误	内部服务器错误
503	服务不可用	服务暂时不可用，请稍后重试

工具配置返回文档