pulsareon/dstalk
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add metadata validation script and module documentation

Browse Source 
- Introduced a new Python script `check_agents_metadata.py` for validating agent metadata, including YAML parsing, rating ranges, and cross-references.
- Added usage instructions and exit codes for the script.
- Created a new markdown file `模块目录和功能说明.md` to outline the directory structure and functionality of the modules.
- Added a text file `说明此文件不可AI修改.txt` to specify that certain files should not be modified by AI, including important information about the `dstalk` framework and its modules.
This commit is contained in:
XiuChengWu
2026-05-31 00:00:58 +08:00
parent 3cc9ee95e4
commit f2da0f2ed4
43 changed files with 2467 additions and 800 deletions
Download Patch File Download Diff File Expand all files Collapse all files

113
plugins/anthropic/src/anthropic_plugin.cpp
View File

@@ -1,3 +1,10 @@
/*
* @file anthropic_plugin.cpp
* @brief Anthropic Claude Messages API provider plugin with streaming support.
* Anthropic Claude Messages API 提供者插件，支持流式输出。
* Copyright (c) 2026 dstalk contributors. GPLv3.
*/
#include "dstalk/dstalk_host.h"
#include "dstalk/dstalk_services.h"
@@ -11,14 +18,14 @@
namespace json = boost::json;
// ============================================================================
// 全局指针 — W17.4: std::atomic 保护 on_shutdown 与 service 函数并发读写
// 全局指针 — W17.4: std::atomic 保护 on_shutdown 与 service 函数并发读写 / Global pointers — W17.4: std::atomic protects concurrent read/write between on_shutdown and service functions
// ============================================================================
static std::atomic<const dstalk_host_api_t*> g_host{nullptr};
static std::atomic<dstalk_http_service_t*> g_http{nullptr};
static dstalk_config_service_t* g_config = nullptr;
// ============================================================================
// 配置数据
// 配置数据 / Config data
// ============================================================================
struct PluginConfig {
std::string provider;
@@ -29,19 +36,21 @@ struct PluginConfig {
double temperature = 0.7;
};
static PluginConfig g_cfg;
static std::string g_tools_json; // W21.2: cached by configure(), consumed by chat/chat_stream
static std::string g_tools_json; // W21.2: 由 configure() 缓存，供 chat/chat_stream 使用 / cached by configure(), consumed by chat/chat_stream
// ============================================================================
// 安全擦除：用 volatile 写零循环防止编译器优化
// 安全擦除：用 volatile 写零循环防止编译器优化 / Secure erase: write zero loop through volatile to prevent compiler optimization
// ============================================================================
// 通过 volatile 写入零来安全擦除内存，防止编译器优化 / Securely zero out memory by writing through volatile to prevent compiler optimization.
static void secure_zero(void* p, size_t n) {
volatile char* vp = (volatile char*)p;
while (n--) *vp++ = 0;
}
// ============================================================================
// 辅助：提取 host / target
// 辅助：提取 host / target / Helper: extract host / target
// ============================================================================
// 将 URL 解析为 scheme、host、port 和 target path 组件 / Parse a URL into scheme, host, port, and target path components.
static bool extract_host_port(const std::string& url,
std::string& scheme_out, std::string& host_out,
std::string& port_out, std::string& target_out)
@@ -65,8 +74,9 @@ static bool extract_host_port(const std::string& url,
}
// ============================================================================
// 构建 Anthropic headers JSON
// 构建 Anthropic headers JSON / Build Anthropic headers JSON
// ============================================================================
// 构建包含 x-api-key 和 anthropic-version 的 JSON headers 对象 / Build the JSON headers object containing x-api-key and anthropic-version.
static std::string build_headers_json()
{
json::object h;
@@ -76,8 +86,11 @@ static std::string build_headers_json()
}
// ============================================================================
// 构建 Anthropic JSON 请求体
// 构建 Anthropic JSON 请求体 / Build Anthropic JSON request body
// ============================================================================
// 构建 Anthropic Messages API 的完整 JSON 请求体。
// 按 Anthropic 规范将 system 消息提取为顶层 system 字段 / Build the full JSON request body for the Anthropic Messages API.
// Extracts system messages as a top-level "system" field per Anthropic spec.
static std::string build_request_json(
const dstalk_message_t* history, int history_len,
const std::string& user_input,
@@ -89,7 +102,7 @@ static std::string build_request_json(
root["max_tokens"] = g_cfg.max_tokens;
root["stream"] = stream;
// 提取 system 消息作为顶层字段
// 提取 system 消息作为顶层字段 / Extract system messages as top-level field
std::string system_prompt;
json::array msgs;
@@ -106,7 +119,7 @@ static std::string build_request_json(
msgs.push_back(obj);
}
// 追加当前用户输入
// 追加当前用户输入 / Append current user input
{
json::object obj;
obj["role"] = "user";
@@ -124,7 +137,7 @@ static std::string build_request_json(
root["temperature"] = g_cfg.temperature;
}
// W21.2: tools 定义传递给 API
// W21.2: tools 定义传递给 API / Pass tools definition to API
if (!tools_json.empty()) {
root["tools"] = json::parse(tools_json);
}
@@ -133,8 +146,11 @@ static std::string build_request_json(
}
// ============================================================================
// 解析非流式响应
// 解析非流式响应 / Parse non-streaming response
// ============================================================================
// 将非流式 JSON 响应体解析为 dstalk_chat_result_t。
// 处理 text 和 tool_use content block，将 tool_use 转换为 OpenAI 格式 / Parse a non-streaming JSON response body into a dstalk_chat_result_t.
// Handles text and tool_use content blocks, converting tool_use to OpenAI format.
static void parse_response(const char* body, int http_status,
dstalk_chat_result_t& r)
{
@@ -169,7 +185,7 @@ static void parse_response(const char* body, int http_status,
auto obj = jv.as_object();
auto content = obj["content"].as_array();
if (!content.empty()) {
// W21.2: 提取 text 和 tool_use content blocks
// W21.2: 提取 text 和 tool_use content blocks / Extract text and tool_use content blocks
std::string text_content;
json::array tool_use_blocks;
@@ -181,7 +197,7 @@ static void parse_response(const char* body, int http_status,
if (btype == "text") {
text_content = json::value_to<std::string>(bobj["text"]);
} else if (btype == "tool_use") {
// 转换为 OpenAI 兼容格式: {id, type:"function", function:{name, arguments}}
// 转换为 OpenAI 兼容格式: {id, type:"function", function:{name, arguments}} / Convert to OpenAI-compatible format: {id, type:"function", function:{name, arguments}}
json::object tc;
tc["id"] = bobj["id"];
tc["type"] = "function";
@@ -206,7 +222,7 @@ static void parse_response(const char* body, int http_status,
r.error = nullptr;
return;
} else if (!tool_use_blocks.empty()) {
// tool-only 响应
// tool-only 响应 / tool-only response
r.content = nullptr;
r.ok = 1;
r.error = nullptr;
@@ -235,15 +251,15 @@ static void parse_response(const char* body, int http_status,
}
// ============================================================================
// SSE 事件解析（Anthropic 格式: event/content_block_delta)
// SSE 事件解析（Anthropic 格式: event/content_block_delta) / SSE event parsing (Anthropic format: event/content_block_delta)
// ============================================================================
// W21.2: 按 content_block index 累积 Anthropic tool_use 增量
// W21.2: 按 content_block index 累积 Anthropic tool_use 增量 / Accumulate Anthropic tool_use increments by content_block index
struct ToolCallAccum {
int index = -1;
std::string id;
std::string name;
std::string arguments; // 从 input_json_delta.partial_json 累积
std::string arguments; // 从 input_json_delta.partial_json 累积 / accumulated from input_json_delta.partial_json
};
struct StreamContext {
@@ -252,10 +268,15 @@ struct StreamContext {
void* userdata;
std::string accumulated;
bool saw_data_line = false;
std::vector<ToolCallAccum> tool_calls; // W21.2: 按 index 累积 tool_use content blocks
std::vector<ToolCallAccum> tool_calls; // W21.2: 按 index 累积 tool_use content blocks / accumulate tool_use content blocks by index
};
// W21.2: 解析 Anthropic SSE 事件，含 tool_use content_block 增量解析
// W21.2: 解析 Anthropic SSE 事件，含 tool_use content_block 增量解析 / Parse Anthropic SSE events with tool_use content_block incremental parsing
// 解析单个 Anthropic SSE "data:" JSON 事件。处理 content_block_start、
// content_block_delta (text_delta/input_json_delta) 和 message_stop。
// 如果产生了 content token 则返回 true，否则返回 false / Parse a single Anthropic SSE "data:" JSON event. Handles content_block_start,
// content_block_delta (text_delta/input_json_delta), and message_stop.
// Returns true if a content token was produced, false otherwise.
static bool parse_sse_data(const std::string& data, std::string& token_out,
StreamContext* ctx)
{
@@ -268,7 +289,7 @@ static bool parse_sse_data(const std::string& data, std::string& token_out,
std::string type = json::value_to<std::string>(*type_ptr);
if (type == "content_block_start") {
// content_block_start 可能为 tool_use
// content_block_start 可能为 tool_use / content_block_start may be tool_use
auto* cb = obj.if_contains("content_block");
if (!cb || !cb->is_object()) return false;
auto& cb_obj = cb->as_object();
@@ -311,7 +332,7 @@ static bool parse_sse_data(const std::string& data, std::string& token_out,
return true;
}
} else if (delta_type == "input_json_delta" && ctx) {
// W21.2: 累积 tool_use arguments 分片
// W21.2: 累积 tool_use arguments 分片 / Accumulate tool_use arguments fragments
auto* pj = dobj.if_contains("partial_json");
if (pj && pj->is_string()) {
auto* idx_ptr = obj.if_contains("index");
@@ -326,18 +347,19 @@ static bool parse_sse_data(const std::string& data, std::string& token_out,
}
} else if (type == "message_stop") {
token_out.clear();
return true; // 流结束
return true; // 流结束 / stream end
}
// 忽略: message_start, content_block_stop, ping, message_delta
// 忽略: message_start, content_block_stop, ping, message_delta / Ignore: message_start, content_block_stop, ping, message_delta
} catch (...) {
// 解析失败忽略
// 解析失败忽略 / Ignore parse failures
}
return false;
}
// ============================================================================
// configure
// configure / configure
// ============================================================================
// 配置插件：provider、endpoint、auth、model 和生成参数 / Configure the plugin with provider, endpoint, auth, model, and generation parameters.
static int my_configure(const char* provider, const char* base_url,
const char* api_key, const char* model,
int max_tokens, double temperature)
@@ -352,7 +374,7 @@ static int my_configure(const char* provider, const char* base_url,
const auto* h = g_host.load(std::memory_order_acquire);
if (h) {
// W21.2: 从 tools service 缓存 tools_json，供 chat/chat_stream 复用
// W21.2: 从 tools service 缓存 tools_json，供 chat/chat_stream 复用 / Cache tools_json from tools service for reuse in chat/chat_stream
auto* tools_svc = reinterpret_cast<const dstalk_tools_service_t*>(
h->query_service("tools", 1));
if (tools_svc && tools_svc->get_tools_json) {
@@ -381,8 +403,9 @@ static int my_configure(const char* provider, const char* base_url,
}
// ============================================================================
// chat
// chat / chat
// ============================================================================
// 非流式 chat completion：发送 history + user input，返回完整响应 / Non-streaming chat completion: send history + user input, return full response.
static dstalk_chat_result_t my_chat(
const dstalk_message_t* history, int history_len,
const char* user_input,
@@ -447,26 +470,27 @@ static dstalk_chat_result_t my_chat(
}
// ============================================================================
// chat_stream
// chat_stream / chat_stream
// ============================================================================
// 行回调
// 行回调 / SSE line callback
// SSE 行回调：解析每个 Anthropic SSE 行并将文本 token 转发给用户 / SSE line callback: parses each Anthropic SSE line and forwards text tokens to user.
static int sse_line_callback(const char* line, void* userdata)
{
try {
auto* ctx = static_cast<StreamContext*>(userdata);
if (!line || !line[0]) return 1; // 空行，继续
if (!line || !line[0]) return 1; // 空行，继续 / empty line, continue
std::string line_str(line);
// SSE 格式: "data: <json>"
// SSE 格式: "data: <json>" / SSE format: "data: <json>"
if (line_str.rfind("data: ", 0) == 0) {
std::string data = line_str.substr(6);
std::string token;
if (parse_sse_data(data, token, ctx)) {
ctx->saw_data_line = true;
if (token.empty()) {
// message_stop
// message_stop / message_stop
return 0;
}
ctx->accumulated += token;
@@ -475,7 +499,7 @@ static int sse_line_callback(const char* line, void* userdata)
}
}
}
// "event: ..." 行和其他 -> 忽略
// "event: ..." 行和其他 -> 忽略 / "event: ..." lines and others -> ignored
return 1;
} catch (const std::exception& e) {
const auto* h = g_host.load(std::memory_order_acquire);
@@ -488,6 +512,9 @@ static int sse_line_callback(const char* line, void* userdata)
}
}
// 流式 chat completion：以 stream=true 发送 history + user input，通过回调传递 token。
// 累积 tool_use blocks 并在结束时序列化 / Streaming chat completion: send history + user input with stream=true, deliver tokens
// via callback. Accumulates tool_use blocks and serializes them at end.
static dstalk_chat_result_t my_chat_stream(
const dstalk_message_t* history, int history_len,
const char* user_input,
@@ -531,7 +558,7 @@ static dstalk_chat_result_t my_chat_stream(
r.http_status = status_code;
// 检查错误状态
// 检查错误状态 / Check error status
if (status_code < 200 || status_code >= 300) {
r.ok = 0;
if (response_body && response_body[0]) {
@@ -560,7 +587,7 @@ static dstalk_chat_result_t my_chat_stream(
if (response_body) host->free(response_body);
// W21.2: 成功条件 = 有内容 OR 有 tool_calls（tool-only 响应如 function calling）
// W21.2: 成功条件 = 有内容 OR 有 tool_calls（tool-only 响应如 function calling） / Success = has content OR has tool_calls (tool-only responses like function calling)
bool has_content = !ctx.accumulated.empty();
bool has_tool_calls = !ctx.tool_calls.empty();
@@ -575,7 +602,7 @@ static dstalk_chat_result_t my_chat_stream(
r.content = has_content
? host->strdup(ctx.accumulated.c_str()) : nullptr;
// W21.2: 序列化累积的 tool_calls 为 JSON（兼容 OpenAI tool_calls 格式）
// W21.2: 序列化累积的 tool_calls 为 JSON（兼容 OpenAI tool_calls 格式） / Serialize accumulated tool_calls to JSON (OpenAI-compatible format)
if (has_tool_calls) {
json::array tc_array;
for (auto& tc : ctx.tool_calls) {
@@ -614,8 +641,9 @@ static dstalk_chat_result_t my_chat_stream(
}
// ============================================================================
// free_result
// free_result / free_result
// ============================================================================
// 释放 chat result 结构体中所有主机分配的字符串字段 / Free all host-allocated string fields in a chat result struct.
static void my_free_result(dstalk_chat_result_t* result)
{
const auto* h = g_host.load(std::memory_order_acquire);
@@ -626,7 +654,7 @@ static void my_free_result(dstalk_chat_result_t* result)
}
// ============================================================================
// 服务 vtable
// 服务 vtable / Service vtable
// ============================================================================
static dstalk_ai_service_t g_service = {
&my_configure,
@@ -636,8 +664,9 @@ static dstalk_ai_service_t g_service = {
};
// ============================================================================
// 生命周期
// 生命周期 / Lifecycle
// ============================================================================
// 插件初始化：查询 http 和 config 服务，注册 ai.anthropic 服务 / Plugin init: query http and config services, register ai.anthropic service.
static int on_init(const dstalk_host_api_t* host)
{
try {
@@ -666,6 +695,7 @@ static int on_init(const dstalk_host_api_t* host)
}
}
// 插件关闭：从内存安全擦除 API key，清空服务指针 / Plugin shutdown: securely erase API key from memory, null out service pointers.
static void on_shutdown()
{
try {
@@ -686,12 +716,12 @@ static void on_shutdown()
}
// ============================================================================
// 插件描述符
// 插件描述符 / Plugin descriptor
// ============================================================================
static dstalk_plugin_info_t g_info = {
/* .name = */ "anthropic-ai",
/* .version = */ "1.0.0",
/* .description = */ "Anthropic Claude AI provider (Messages API)",
/* .description = */ "Anthropic Claude AI provider (Messages API) / Anthropic Claude AI 提供者 (Messages API)",
/* .api_version = */ DSTALK_API_VERSION,
/* .dependencies = */ { "http", "config", NULL },
/* .on_init = */ on_init,
@@ -699,6 +729,7 @@ static dstalk_plugin_info_t g_info = {
/* .on_event = */ nullptr,
};
// 必须入口点：返回插件描述符给主机 / Mandatory entry point: returns the plugin descriptor to the host.
extern "C" DSTALK_PLUGIN_EXPORT dstalk_plugin_info_t* dstalk_plugin_init(void)
{
return &g_info;