diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..d8caf54 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,75 @@ +name: CI + +on: + push: + branches: [master] + pull_request: + branches: [master] + +jobs: + # ── 动态矩阵 ────────────────────────────────────────────── + # PR 仅跑 Ubuntu 节省 minutes；push master 跑全矩阵 Ubuntu + Windows + matrix: + name: Determine matrix + runs-on: ubuntu-24.04 + outputs: + os: ${{ steps.set-matrix.outputs.os }} + steps: + - id: set-matrix + shell: bash + run: | + if [ "${{ github.event_name }}" = "push" ] && [ "${{ github.ref }}" = "refs/heads/master" ]; then + echo "os=[\"ubuntu-24.04\",\"windows-2025\"]" >> "$GITHUB_OUTPUT" + else + echo "os=[\"ubuntu-24.04\"]" >> "$GITHUB_OUTPUT" + fi + + # ── 构建 & 测试 ─────────────────────────────────────────── + build: + name: ${{ matrix.os }} / ${{ matrix.build_type }} + needs: matrix + strategy: + fail-fast: false + matrix: + os: ${{ fromJSON(needs.matrix.outputs.os) }} + build_type: [Release] + runs-on: ${{ matrix.os }} + + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 1 + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: '3.12' + + - name: Install Conan + run: pip install conan + + - name: Cache Conan + uses: actions/cache@v4 + with: + path: | + ~/.conan2 + ~/.conan2/p + key: ${{ runner.os }}-conan-${{ matrix.build_type }}-${{ hashFiles('deps/conanfile.txt') }} + restore-keys: | + ${{ runner.os }}-conan-${{ matrix.build_type }}- + ${{ runner.os }}-conan- + + - name: Install Conan dependencies + run: | + conan profile detect --force + conan install deps --build=missing -s build_type=${{ matrix.build_type }} + + - name: Configure CMake + run: cmake --preset conan-release + + - name: Build + run: cmake --build --preset conan-release --config ${{ matrix.build_type }} + + - name: Test + run: ctest --preset conan-release -C ${{ matrix.build_type }} --output-on-failure diff --git a/CMakeLists.txt b/CMakeLists.txt index e28a186..f2916f1 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,14 +1,11 @@ cmake_minimum_required(VERSION 3.21) project(dstalk VERSION 0.1.0 LANGUAGES C CXX) +set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin) +set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin) + set(CMAKE_C_STANDARD 11) -if(MSVC_VERSION LESS 1920) - set(CMAKE_CXX_STANDARD 17) -else() - set(CMAKE_CXX_STANDARD 20) -endif() set(CMAKE_C_STANDARD_REQUIRED ON) -set(CMAKE_CXX_STANDARD_REQUIRED ON) option(DSTALK_BUILD_GUI "Build the SDL3 GUI frontend" OFF) option(DSTALK_BUILD_TESTS "Build dstalk tests" ON) diff --git a/CMakePresets.json b/CMakePresets.json new file mode 100644 index 0000000..d198e5d --- /dev/null +++ b/CMakePresets.json @@ -0,0 +1,54 @@ +{ + "version": 3, + "vendor": { + "conan": {} + }, + "cmakeMinimumRequired": { + "major": 3, + "minor": 15, + "patch": 0 + }, + "configurePresets": [ + { + "name": "conan-release", + "displayName": "'conan-release' config", + "description": "'conan-release' configure using 'Ninja' generator", + "generator": "Ninja", + "cacheVariables": { + "CMAKE_POLICY_DEFAULT_CMP0091": "NEW", + "CMAKE_BUILD_TYPE": "Release", + "CMAKE_C_COMPILER": "cl", + "CMAKE_CXX_COMPILER": "cl" + }, + "toolset": { + "value": "v145", + "strategy": "external" + }, + "architecture": { + "value": "x64", + "strategy": "external" + }, + "toolchainFile": "generators\\conan_toolchain.cmake", + "binaryDir": "E:\\Prj2026\\AIGen2026\\dstalk\\build\\build\\Release" + } + ], + "buildPresets": [ + { + "name": "conan-release", + "configurePreset": "conan-release", + "jobs": 32 + } + ], + "testPresets": [ + { + "name": "conan-release", + "configurePreset": "conan-release", + "execution": { + "jobs": 32 + }, + "environment": { + "OPENSSL_MODULES": "C:\\Users\\Administrator\\.conan2\\p\\b\\opens4d81e45a1d5f5\\p\\lib\\ossl-modules" + } + } + ] +} \ No newline at end of file diff --git a/README.md b/README.md index 27d0364..0efae0f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # dstalk -> 基于 DeepSeek V4 大模型、兼容 OpenAI / Anthropic API 的 AI 编程 CLI +> AI 编程 CLI —— 基于 DeepSeek V4, 兼容 OpenAI / Anthropic API > > 官网: [dstalk.top](https://dstalk.top) @@ -8,9 +8,9 @@ ## 这是什么？ -dstalk 是一款 AI 编程助手命令行工具。通过调用 DeepSeek V4 大模型（兼容 OpenAI 和 Anthropic API），在终端里用自然语言完成代码编写、重构、调试和文件操作。功能对标 Claude Code、OpenCode、KiloCode。 +dstalk 是一款 AI 编程助手命令行工具, 通过调用大模型在终端里完成代码编写、重构、调试和文件操作。 -核心设计为 **插件化 CDLL + 多前端解耦**： +核心设计为 **插件化 CDLL + 多前端解耦**: ```text ┌───────────────────────────────────────────────────────────┐ @@ -18,9 +18,7 @@ dstalk 是一款 AI 编程助手命令行工具。通过调用 DeepSeek V4 大 │ ┌──────────────────┐ ┌──────────────────────────┐ │ │ │ dstalk-cli │ │ dstalk-gui │ │ │ │ ANSI 终端 UI │ │ SDL3 图形化 UI │ │ -│ │ exe → dstalk.dll│ │ exe → dstalk.dll │ │ │ └────────┬─────────┘ └─────────────┬─────────────┘ │ -│ │ │ │ │ └──────────────┬───────────────┘ │ │ │ C ABI │ └──────────────────────────┼─────────────────────────────────┘ @@ -30,7 +28,6 @@ dstalk 是一款 AI 编程助手命令行工具。通过调用 DeepSeek V4 大 │ ┌──────────────────────────────────────────────────────┐ │ │ │ Host: 插件加载 · 服务注册 · 事件总线 · 配置管理 │ │ │ └──────────────────────────────────────────────────────┘ │ -│ │ 服务查询 │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ │ │ deepseek │ │ anthropic│ │ network │ │ lsp │ │ │ │ (ai) │ │ (ai) │ │ (http) │ │ 客户端 │ │ @@ -41,350 +38,48 @@ dstalk 是一款 AI 编程助手命令行工具。通过调用 DeepSeek V4 大 └─────────────────────────────────────────────────────────────┘ ``` -- **`dstalk-core`** —— C11/C++20 插件化宿主 DLL，负责插件加载、服务注册/查询、事件总线、配置管理。 -- **`dstalk-cli`** —— 命令行前端，ANSI 转义码实现，调用 `dstalk.dll`。 -- **`dstalk-gui`** —— 图形化前端，SDL3 跨平台窗口，调用 `dstalk.dll`。 -- **`plugins/`** —— 9 个功能插件，编译为独立 DLL，通过 C ABI 动态注册服务。 +- **dstalk-core** —— C11/C++20 插件化宿主 DLL, 负责插件加载、服务注册、事件总线、配置管理 +- **dstalk-cli** —— 命令行前端, ANSI 终端 UI +- **dstalk-gui** —— 图形化前端, SDL3 跨平台窗口 +- **plugins/** —— 9 个功能插件, 编译为独立 DLL, 通过 C ABI 动态注册服务 -核心与界面完全解耦，可以轻松编写自己的前端，或把 AI 能力嵌入到现有工具中。所有功能通过插件实现，插件只需引用 `dstalk.dll` 即可。 +核心与界面完全解耦, 可编写自己的前端或把 AI 能力嵌入到现有工具中。 --- -## 核心功能 +## 支持的 AI 模型 -| 功能 | 状态 | 说明 | -|------|------|------| -| **多后端 AI 支持** | 已完成 | DeepSeek V4 和 Anthropic Claude 通过插件独立加载，`config.toml` 中 `ai.provider` 一键切换 | -| **流式输出** | 已完成 | SSE 流式响应，终端逐字打印 AI 思考过程 | -| **多轮会话** | 已完成 | 上下文窗口连续对话，支持 `/clear` 清空、`/save` `/load` 持久化 | -| **文件读写工具** | 已完成 | 内置 `/file` 命令集，支持列目录、查看、读取、写入文件 | -| **LSP 集成** | 已完成 | 完整 LSP 客户端（子进程管理、JSON-RPC 2.0），支持诊断、悬停、补全 | -| **插件系统** | 已完成 | 9 个功能插件，拓扑排序依赖管理，DLL 动态加载，服务注册/查询 | -| **GUI 前端** | 已完成 | SDL3 跨平台图形界面，流式输出、会话管理、输入历史、剪贴板 | +| 提供商 | 模型 | 插件 | +|--------|------|------| +| DeepSeek | deepseek-v4-pro | `ai.deepseek` | +| Anthropic | claude-opus-4 | `ai.anthropic` | +| OpenAI 兼容 | GPT 系列 | `ai.deepseek` (兼容) | ---- - -## 为什么用 C/C++ 实现？ - -| 维度 | dstalk (C/C++) | 典型竞品 (TypeScript/Node.js) | -|------|----------------|------------------------------| -| 启动速度 | 毫秒级 | 秒级 | -| 内存占用 | 数十 MB | 数百 MB 起 | -| 运行时依赖 | 零（单文件 DLL） | 需要 Node.js 运行时 | -| 嵌入能力 | 任意语言通过 C ABI 调用 | 困难 | -| GC 影响 | 无 GC 停顿 | 可能内存膨胀 | - -AI 编程助手需要长期驻留、频繁交互，性能特征值得用系统级语言重新思考。 - ---- - -## 与竞品的差异化 - -| 特性 | dstalk | Claude Code | OpenCode | KiloCode | -|------|--------|-------------|----------|----------| -| 实现语言 | C11 / C++20 | TypeScript | TypeScript | TypeScript | -| 运行时 | 零依赖 CDLL | Node.js | Node.js | Node.js | -| 前端形态 | CLI + GUI 双前端 | 终端集成 | VS Code 插件 | VS Code 插件 | -| 模型 | DeepSeek / OpenAI / Anthropic | Claude | 多模型 | 多模型 | -| 嵌入第三方 | C ABI，极易 | 困难 | 困难 | 困难 | - -### DLL 架构优势 - -- **语言无关** —— C ABI 意味着 C/C++、Python、Rust、C#、Go 都能直接调用 -- **进程内集成** —— 无需 HTTP 通信、零 IPC 开销，直接函数调用 -- **前端零状态** —— CLI 和 GUI 不持有业务逻辑，只负责渲染和输入 +通过 `config.toml` 中 `ai.provider` 一键切换。 --- ## 快速开始 -### 1. 安装工具链（全自动，存入 tools\，需系统已安装 Python 3.10+） - ```bash -cd tools -setup.bat # 下载 CMake + Ninja + LLVM/Clang，并在 tools/.venv 安装 Conan2 +cd tools && setup.bat # 1. 安装工具链 (CMake / Ninja / LLVM / Conan2) +build.bat # 2. 编译 +# 3. 创建 config.toml # 见教程: docs/tutorial/quick-start.md +build/dstalk-cli/dstalk-cli.exe # 4. 运行 +# 5. 输入自然语言 # "帮我写一个 C 程序" ``` -> 网络不畅时可手动下载放入对应目录：[Ninja](https://github.com/ninja-build/ninja/releases) | [CMake](https://cmake.org/download/) | [LLVM](https://github.com/llvm/llvm-project/releases) -> -> 目录结构要求: `tools/cmake/bin/cmake.exe` / `tools/ninja/ninja.exe` / `tools/llvm/bin/clang.exe` / `tools/.venv/Scripts/conan.exe` - -### 2. 编译 - -```bash -build.bat # 一键: Conan拉依赖 → CMake配置 → Ninja编译 -``` - -### 3. 运行 - -```bash -build/dstalk-cli/dstalk-cli.exe # 命令行模式 -# 图形模式默认关闭；需要 SDL3 时用 -DDSTALK_BUILD_GUI=ON 重新配置 -``` +> 详细 5 步教程 (含 config.toml 模板与对话示例): [docs/tutorial/quick-start.md](docs/tutorial/quick-start.md) --- -## 使用示例 +## 文档 -```text -$ dstalk-cli - - dstalk v0.1.0 | 模型: deepseek-v4-pro | /help 查看帮助 - -> 帮我写一个读取 CSV 并计算平均值的 C 程序 - - [dstalk] 正在思考... - - #include - #include - - int main(int argc, char *argv[]) { - if (argc < 2) { - fprintf(stderr, "用法: %s \n", argv[0]); - return 1; - } - FILE *fp = fopen(argv[1], "r"); - if (!fp) { perror("fopen"); return 1; } - - double sum = 0.0; - int count = 0; - char line[1024]; - while (fgets(line, sizeof(line), fp)) { - sum += atof(line); - count++; - } - fclose(fp); - - printf("平均值: %.2f (共 %d 行)\n", sum / count, count); - return 0; - } - - 已写入 csv_avg.c。需要我帮你编译测试吗？ - -> 把这段代码改成支持表头的 - - [dstalk] 已更新 csv_avg.c——跳过第一行表头，增加列选择功能。 - -> /file show csv_avg.c - - [dstalk] 已显示 csv_avg.c 内容。 -``` - -### 常用命令 - -| 命令 | 说明 | +| 文档 | 说明 | |------|------| -| `/file list [path]` | 列出目录内容 | -| `/file show ` | 查看文件内容 | -| `/file read ` | 读取文件内容 | -| `/file write ` | 写入文件 | -| `/model ` | 切换 AI 模型 | -| `/clear` | 清空会话上下文 | -| `/save ` | 保存会话 | -| `/load ` | 恢复会话 | -| `/help` | 显示帮助 | - ---- - -## 工程结构 - -```text -dstalk/ -├── deps/ -│ └── conanfile.txt # Conan2 依赖声明 (Boost, OpenSSL, SDL3) -├── dstalk-core/ # 核心 DLL — 插件宿主 -│ ├── include/dstalk/ -│ │ ├── dstalk_host.h # 公开 API: 宏定义、宿主API、插件生命周期 -│ │ ├── dstalk_services.h # 服务接口 vtable 定义 (AI/Session/Context/HTTP/FileIO/Config/Tools/LSP) -│ │ ├── dstalk_types.h # 共享类型: 消息、结果、事件、日志等级 -│ │ └── dstalk_lsp.h # LSP 便捷函数 (委托给 lsp 插件) -│ ├── src/ -│ │ ├── host.cpp # 宿主: 初始化、服务查询、LSP 便捷函数 -│ │ ├── config_store.cpp/.hpp # 配置管理 (TOML 解析) -│ │ ├── event_bus.cpp/.hpp # 事件总线 (发布/订阅) -│ │ ├── service_registry.cpp/.hpp # 服务注册表 (名称→vtable) -│ │ ├── plugin_loader.cpp/.hpp # 插件加载器 (DLL 加载、拓扑排序、依赖管理) -│ │ └── boost_json.cpp # Boost.JSON 编译单元 -│ └── CMakeLists.txt -├── plugins/ # 功能插件 (每个编译为独立 DLL) -│ ├── deepseek/ # DeepSeek AI (服务名: ai.deepseek) -│ ├── anthropic/ # Anthropic Claude (服务名: ai.anthropic) -│ ├── network/ # HTTP/HTTPS 客户端 (服务名: http) -│ ├── session/ # 会话管理 (服务名: session) -│ ├── context/ # 上下文/Token 管理 (服务名: context) -│ ├── file-io/ # 文件读写 (服务名: file_io) -│ ├── tools/ # 工具注册/执行 (服务名: tools) -│ ├── lsp/ # LSP 客户端 (服务名: lsp) -│ ├── config/ # 配置服务 (服务名: config) -│ └── CMakeLists.txt # 插件构建 (按依赖顺序) -├── dstalk-cli/ # 命令行前端 (ANSI) -│ ├── src/main.cpp -│ └── CMakeLists.txt -├── dstalk-gui/ # 图形化前端 (SDL3) -│ ├── src/main.cpp -│ └── CMakeLists.txt -├── examples/ # 示例代码 -│ └── example_plugin/ -│ └── example_plugin.cpp # 插件开发示例 -├── tests/ # 集成测试 -│ └── smoke_test.cpp -├── CMakeLists.txt # 根 CMake -└── README.md -``` - ---- - -## 公开 API - -头文件: -- [dstalk_host.h](dstalk-core/include/dstalk/dstalk_host.h) — 宿主 API、插件生命周期 -- [dstalk_services.h](dstalk-core/include/dstalk/dstalk_services.h) — 服务接口 vtable 定义 -- [dstalk_types.h](dstalk-core/include/dstalk/dstalk_types.h) — 共享类型 -- [dstalk_lsp.h](dstalk-core/include/dstalk/dstalk_lsp.h) — LSP 便捷函数 - -```c -/* 宿主生命周期 */ -int dstalk_init(const char* config_path); -void dstalk_shutdown(void); - -/* 插件管理 */ -int dstalk_plugin_load(const char* path); -int dstalk_plugin_unload(int plugin_id); -int dstalk_plugin_list(char** output_json); - -/* 服务查询 —— 通过名称获取插件注册的 vtable */ -void* dstalk_service_query(const char* service_name, int min_version); - -/* 事件总线 */ -int dstalk_event_subscribe(int event_type, dstalk_event_handler_fn handler, void* userdata); -int dstalk_event_emit(int event_type, const void* data); -void dstalk_event_unsubscribe(int subscription_id); - -/* 配置 */ -const char* dstalk_config_get(const char* key); -int dstalk_config_set(const char* key, const char* value); - -/* 内存管理 */ -void* dstalk_alloc(size_t size); -void dstalk_free(void* ptr); -char* dstalk_strdup(const char* s); - -/* LSP 便捷函数 (委托给 lsp 插件) */ -int dstalk_lsp_start(const char* server_cmd, const char* language); -void dstalk_lsp_stop(void); -int dstalk_lsp_open(const char* uri, const char* content, const char* language_id); -int dstalk_lsp_close(const char* uri); -int dstalk_lsp_diagnostics(const char* uri, char** output); -int dstalk_lsp_hover(const char* uri, int line, int character, char** output); -int dstalk_lsp_completion(const char* uri, int line, int character, char** output); -``` - -**调用约定：** - -- 所有字符串均为 UTF-8 编码 -- 通过 `dstalk_service_query` 获取服务 vtable，再通过函数指针调用具体功能 -- `dstalk_free` 释放所有 API 返回的堆内存 -- 返回 `0` 成功，负数表示错误码 - -**跨语言调用示例：** - -```c -#include "dstalk/dstalk_host.h" -#include "dstalk/dstalk_services.h" -#include - -int main(void) { - if (dstalk_init("config.toml") != 0) { - fprintf(stderr, "初始化失败\n"); - return 1; - } - - // 查询 AI 服务 - const char* provider = dstalk_config_get("ai.provider"); - if (!provider) provider = "ai.deepseek"; - const dstalk_ai_service_t* ai = dstalk_service_query(provider, 1); - if (ai) { - ai->configure(provider, "https://api.deepseek.com/v1", "sk-xxx", - "deepseek-v4-pro", 4096, 0.7); - } - - dstalk_shutdown(); - return 0; -} -``` - ---- - -## FAQ - -**Q: 为什么不用 Rust？** -A: 团队对 C/C++ 生态更熟悉，C++20 的现代特性已能让我们写出安全高效的代码。且 CDLL 需要稳定的 C ABI，C/C++ 最直接。 - -**Q: 支持哪些模型？** -A: 主要支持 DeepSeek V4，同时兼容 OpenAI GPT 系列和 Anthropic Claude 系列的 API。通过配置文件切换 API 基地址和密钥即可。 - -**Q: 为什么同时做 CLI 和 GUI？** -A: CLI 适合终端/SSH/CI 环境，GUI 适合需要富文本和鼠标交互的场景。两者共享同一核心 DLL，功能一致。 - -**Q: 如何配置 API Key？** -A: 首次运行前，手动创建项目目录下的 `config.toml`，按需选择后端： - -```toml -# 选择 AI 后端插件: ai.deepseek 或 ai.anthropic -ai.provider = "ai.deepseek" - -# DeepSeek -api.base_url = "https://api.deepseek.com/v1" -api.api_key = "sk-xxxxxxxx" -api.model = "deepseek-v4-pro" - -# Anthropic Claude (切换 ai.provider 为 "ai.anthropic" 即可) -# api.base_url = "https://api.anthropic.com/v1" -# api.api_key = "sk-ant-xxxxxxxx" -# api.model = "claude-opus-4-20250514" -``` - -修改 `ai.provider` 字段即可在不同后端间切换，无需改动代码。 - ---- - -## 路线图 - -| 阶段 | 内容 | -|------|------| -| **Phase 1** | 项目骨架、CMake 构建、DLL 导出、CLI 前端主循环 | -| **Phase 2** | HTTPS 网络层、DeepSeek API 对接、基本对话 | -| **Phase 3** | ~~流式输出、多轮会话、文件读写工具、CLI 体验对齐~~ | -| **Phase 4** (当前) | ~~插件化架构重构、多后端 AI、LSP 客户端、SDL3 GUI~~ | -| **Phase 5** | GUI 完善、工具调用（Function Calling）、插件生态、多语言扩展 | - ---- - -## 贡献指南 - -1. Fork 仓库并克隆到本地 -2. 创建分支: `git checkout -b feature/功能名` -3. 编码: C 代码 K&R 风格，C++ 代码 LLVM 风格 -4. 确保 `cmake --build build` 通过 -5. 提交 PR，描述改动内容和动机 - -### 代码规范 - -- C: C11 标准，头文件 `#pragma once` -- C++: C++20 标准，优先标准库，必要时引入 Boost -- 内存: C++ 优先 RAII；C 代码显式管理 -- 对外接口: `extern "C"` 纯 C 函数，不抛异常 - ---- - -## 技术风险与对策 - -| 风险 | 对策 | -|------|------| -| C++ 开发效率低于脚本语言 | Boost 库弥补；核心 API 稳定后开发速度不会慢于竞品 | -| OpenSSL 跨平台兼容性 | Conan2 锁定版本，统一 Windows/Linux/macOS HTTPS 后端 | -| SDL3 依赖体积较大 | GUI 默认关闭，需要图形前端时再启用 `DSTALK_BUILD_GUI` | -| AI API 协议变更 | 适配层独立模块，变更时只改一处 | +| [教程: 快速入门](docs/tutorial/quick-start.md) | 5 步上手, 从安装到第一个对话 | +| [参考: CLI 命令](docs/reference/commands.md) | 完整命令速查表 | +| [文档导航](docs/README.md) | 全部文档索引与未来计划 | --- @@ -394,4 +89,4 @@ GNU General Public License v3. Copyright (c) 2026 dstalk contributors. --- -[dstalk.top](https://dstalk.top) | [GitHub](https://github.com/dstalk/dstalk) | [Issue 反馈](https://github.com/dstalk/dstalk/issues) +[dstalk.top](https://dstalk.top) | [GitHub](https://github.com/dstalk/dstalk) diff --git a/agents/README.md b/agents/README.md index e3c1b7e..8616308 100644 --- a/agents/README.md +++ b/agents/README.md @@ -1,5 +1,7 @@ # dstalk 多 Agents 协作系统 +> **新会话恢复 CEO 模式？先读 [WORKFLOW.md](WORKFLOW.md)** —— 工作流、波次节奏、6 阶段协作、子代理 prompt 模板都在那里。 + ## 公司宗旨 - **第一性原理**：从问题本质出发，不被既有结构和惯性束缚 diff --git a/agents/WORKFLOW.md b/agents/WORKFLOW.md new file mode 100644 index 0000000..0c63398 --- /dev/null +++ b/agents/WORKFLOW.md @@ -0,0 +1,118 @@ +# dstalk 团队工作流（CEO 多代理协作模式） + +> 本文档供 CEO（主会话）和所有员工子代理参考。新会话恢复 CEO 模式时**第一件事**就是读这里。 + +## 1. 编制与并行度 + +- **团队规模 = CPU 物理核数（dstalk = 16 人）**：1 CEO + 3 架构师 + 5 工程师 + 3 QA + 2 DevOps + 1 设计师 + 1 作家 + 1 安全 +- 每个员工有 `agents//profile.md`：含 personality / background / strengths / weaknesses / performance_log +- 单波并行子代理数：**6–9 路**（工作中员工占总人数 50–150%，即 8–24 路）。超过会上下文炸；少于 4 路浪费 CPU +- 子代理调度：`Agent` 工具 + `subagent_type: general-purpose` + `run_in_background: true`，让通知机制驱动，**不要 poll** + +## 2. 6 阶段协作流程 + +每个 Wave 都按这个流程： + +1. **propose（提案）** — CEO 把需求拆成 N 个候选任务（`W.` 编号，如 W2.1、W9.4） +2. **vote（投票）** — 派 3–4 个子代理读代码独立评估、投票同意/反对/优化 +3. **optimize（优化）** — 被反对的提案，提案方根据反对意见迭代 +4. **integrate（整合）** — CEO 汇总成统一可执行计划 +5. **execute（执行）** — 派对应专长的员工子代理实施 +6. **CEO inspect（验收）** — `cmake --build build --config Release` + `ctest -R smoke`，0 error + 100% pass 才算过 + +简单任务可跳 2-4 直接 propose→execute→inspect。**有架构争议**的必须走完 6 阶段。 + +## 3. 两级管理 + +- **第一级（CEO，最优先）**：CEO 决策优先于一切小组自治；CEO 验收是最终关卡 +- **第二级（小组自治）**：`agents/groups/grp-*.md` 定义工作小组，组内事务自决 +- 冲突时 **CEO > group lead > 个人** + +## 4. 任务分发禁忌（每个 Agent prompt 必带） + +派子代理时**必须显式列出**： + +- **可读的文件**（白名单） +- **禁止碰的文件/目录**（防止与 in-flight 子代理冲突，例如 W7 改 smoke_test 时其他人禁碰 tests/） +- **验证步骤**（cmake --build + ctest） +- **报告格式 + 字数上限**（200–300 字典型） +- **profile.md 更新要求**（每个任务必须追加 performance_log） + +不写禁忌 → 多个子代理同时改同一个文件 → 冲突回滚 → 时间浪费。 + +## 5. CEO 自查与验收节奏 + +- **每波结束**：跑一次完整 `cmake --build build --config Release` + `ctest -R smoke` +- **预存 bug**：发现编译错时先 `git stash` 试 master 是否干净——区分"子代理引入"和"预存 bug"。预存 bug CEO 自己改不甩锅 +- **stale obj 问题**：clang-cl 增量构建偶尔不识别源文件修改（lsp_plugin/tools_plugin 踩过坑），症状是编译报告的行号源码内容与磁盘不符。解法：`rm -f build/**/.cpp.obj` 强制重编 +- **CEO 验收通过后立刻 commit + push**（用户硬规则："别忘了每次通过ceo验收的提交git并推送"） + +## 6. 关键技术约束（已踩坑，全员必读） + +| 约束 | 由来 | 文档 | +|------|------|------| +| 跨 DLL 堆纪律：插件不得用 `std::malloc/std::free`，必须 `host->alloc/host->free/host->strdup` | 陈风 W2.1 | `docs/reference/plugin-abi.md` | +| Boost.JSON header-only：每个使用 `` 的翻译单元必须 `#include ` | 王测 W7 | (代码内 include) | +| C ABI + atomic 回调：跨 DLL 函数指针必须 `std::atomic` + `memory_order_acquire/release` | 林深 W1.1 | `docs/reference/plugin-abi.md` §6 | +| api_key 安全清零：on_shutdown 必须 `volatile char*` 写零循环 + clear | 曹武 W2.2 | `docs/explanation/security-logging.md` | +| CRT：`/MD` 动态 CRT（`CMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDLL`） | 胡桐 W3 | (build 配置) | +| `initialize_all` 容错：单插件失败不阻断其他插件，返回失败计数 | 黄岭 W9.8 | `dstalk-core/src/plugin_loader.cpp` | + +## 7. Wave 编号与历史 + +进入项目时**第一件事**：读 `agents/*/profile.md` 的 `performance_log`，从最大 W 号继续下一波。 + +**已完成的高水位**（截至 2026-05-27）：W1.1、W2.1、W2.2、W3、W4、W5.1、W6.1、W7、W8.1、W9.1、W9.3、W9.4、W9.6、W9.8。Wave 6 还有 W9.10 in-flight。 + +下一个新提案应从 **W10.x** 开始。 + +## 8. 用户消息模式识别（CEO 行为指南） + +| 用户说 | CEO 行动 | +|--------|----------| +| "团队不能闲着" / "去开会安排工作" | 立刻派下一波，**不要解释 / 不要问"派什么"**——基于 profile.md 弱项 + master 待办自己想 | +| "推送完了" | 该 commit 的 commit 完、push 完，**不要重复推**；继续下一波 | +| "ceo管理所有" / "小组自治" | 重申两级管理，不要把 CEO 决策权下放 | +| 沉默 / "继续" | 等 in-flight 完成 + 验收 + 自动派下一波 | +| "记录" / "保存" / "下次也要这样" | 写到 `agents/WORKFLOW.md`（公共）+ CEO 私有 memory（双轨） | + +## 9. 子代理 prompt 模板（复制即用） + +``` +你扮演 dstalk 团队成员 <姓名> () — <角色>。读 `agents//profile.md` 了解你的人设。 + +**W. 任务**：<一句话目标> + +**背景**：<2-4 句，说明为什么做这个、依赖什么前置工作> + +请读： +- <文件 1> +- <文件 2> +- ... + +**交付**： +1. <可执行步骤 1> +2. <可执行步骤 2> + +**禁忌**： +- 不要碰 <某目录>（in-flight 中） +- 不要 <某行为>（与设计原则冲突） + +实现完成后必须 cmake --build build --config Release 验证 0 error，并跑 ctest -R smoke 验证 100% pass。 + +完成后更新 `agents//profile.md` performance_log 追加 W. 项。 + +**报告格式**（不超过 N 字）： +1. 改的代码行号 + 关键 diff +2. 测试输出最后几行 +3. profile.md 已更新 +``` + +## 10. 关联文档 + +- [README.md](README.md) — 团队花名册 + 公司宗旨 +- [groups/](groups/) — 工作小组定义 +- [../docs/reference/plugin-abi.md](../docs/reference/plugin-abi.md) — Plugin ABI 契约 +- [../docs/explanation/architecture.md](../docs/explanation/architecture.md) — 架构哲学 +- [../docs/explanation/plugin-lifecycle.md](../docs/explanation/plugin-lifecycle.md) — 插件生命周期 +- [../docs/explanation/security-logging.md](../docs/explanation/security-logging.md) — 日志安全审计 diff --git a/agents/architect-huang/profile.md b/agents/architect-huang/profile.md index 209597d..eb12ffa 100644 --- a/agents/architect-huang/profile.md +++ b/agents/architect-huang/profile.md @@ -20,5 +20,15 @@ performance_log: - date: 2026-05-27 event: "入职 dstalk 团队" rating: ongoing + - date: 2026-05-27 + event: "W9.8 修复 plugin_loader initialize_all() 首插件失败即终止缺陷" + detail: | + 将 initialize_all() 从 fail-fast 改为 fail-continue: + - 单插件 init 失败不再返回 -1，而是 log error + 标记失败 + 继续初始化其他插件 + - 依赖了 failed 插件的插件自动跳过，log warning + - 拓扑序不变（Kahn 算法未修改） + - 返回值语义: 0=全部成功, >0=失败插件数, <0=严重错误(循环依赖/host_api null) + - 编译 0 error, smoke test 100% pass + rating: completed current_groups: [] --- diff --git a/agents/architect-lin/profile.md b/agents/architect-lin/profile.md index 4edf440..8b8797d 100644 --- a/agents/architect-lin/profile.md +++ b/agents/architect-lin/profile.md @@ -30,6 +30,12 @@ performance_log: - date: 2026-05-27 event: "加入核心质量小组(grp-quality-core)，与王测协作执行C2" rating: ongoing + - date: 2026-05-27 + event: "W1.1 修复完成：shutdown_all 新增 DLL 句柄释放（FreeLibrary/dlclose）；g_diag_callback 改为 std::atomic 消除 UB。host.cpp 和 plugin_loader.cpp 均编译通过，0 error 0 warning" + rating: A + - date: 2026-05-27 + event: "W9.4 完成：撰写 docs/reference/plugin-abi.md Plugin ABI 契约文档（200行），涵盖 DSTALK_API_VERSION、内存所有权、跨DLL堆纪律、register_service、on_init/on_shutdown、回调线程安全、依赖声明共7个契约要点。更新 docs/README.md reference 区追加入口" + rating: A current_groups: - grp-quality-core (成员) - grp-ai-plugins (待命) diff --git a/agents/devops-hu/profile.md b/agents/devops-hu/profile.md index afe3aa9..52109ac 100644 --- a/agents/devops-hu/profile.md +++ b/agents/devops-hu/profile.md @@ -20,5 +20,17 @@ performance_log: - date: 2026-05-27 event: "入职 dstalk 团队" rating: ongoing + - date: 2026-05-27 + event: "落地 4 项 CMake 改进 (审查报告 C1-C4)" + detail: > + 1. POST_BUILD DLL 复制改为 CMAKE_RUNTIME_OUTPUT_DIRECTORY 统一输出， + 删除 dstalk-cli/dstalk-gui/tests 中 3 处 POST_BUILD 拷贝。 + 2. CMAKE_CXX_STANDARD 改为 per-target target_compile_features(dstalk PUBLIC cxx_std_20)。 + 3. 删除 9 个插件中冗余的 target_include_directories(... dstalk-core/include)。 + 4. 创建 INTERFACE library dstalk_boost_config 统一 BOOST_ALL_NO_LIB / + BOOST_ERROR_CODE_HEADER_ONLY / BOOST_JSON_HEADER_ONLY，5 个插件改用 link 方式。 + 顺带修复: tools_plugin.cpp 缺少前向声明、lsp_plugin.cpp 函数签名 mismatch、 + 5 个插件缺少 #include (Boost 1.86 不再识别 HEADER_ONLY)。 + rating: done current_groups: [] --- diff --git a/agents/devops-ma/profile.md b/agents/devops-ma/profile.md index 5a18f78..45db577 100644 --- a/agents/devops-ma/profile.md +++ b/agents/devops-ma/profile.md @@ -20,5 +20,12 @@ performance_log: - date: 2026-05-27 event: "入职 dstalk 团队" rating: ongoing + - date: 2026-05-27 + event: "落地 CI pipeline (GitHub Actions)" + detail: > + 创建 .github/workflows/ci.yml，实现双矩阵构建 (ubuntu-24.04 + windows-2025)。 + PR 仅跑 Ubuntu，push master 跑全矩阵节省 minutes。 + 集成 Conan 依赖缓存 (含 ~/.conan2/p)，checkout fetch-depth=1 提速。 + rating: done current_groups: [] --- diff --git a/agents/engineer-chen/profile.md b/agents/engineer-chen/profile.md index b20c5b5..c70950c 100644 --- a/agents/engineer-chen/profile.md +++ b/agents/engineer-chen/profile.md @@ -20,5 +20,18 @@ performance_log: - date: 2026-05-27 event: "入职 dstalk 团队" rating: ongoing + - date: 2026-05-27 + event: "W2.1 - 修复 file_io_plugin 跨 DLL 堆释放风险 (曹武安全审计 + B3 评审)" + rating: success + details: + - "问题: file_io_plugin.cpp 用 ::malloc 分配，调用方 smoke_test 用 std::free 释放 -- Windows /MT 下不同堆必崩" + - "CRT 类型: /MD (MultiThreadedDLL, 动态 CRT 共享) -- 当前不会崩但违反 ABI 纪律" + - "修复: file_io_plugin 改用 g_host->alloc / g_host->free (host_api 提供的统一分配器)" + - "同步修复: tools_plugin.cpp:58 std::free -> g_host->free (同模式)" + - "同步修复: session_plugin.cpp:166 std::free -> g_host->free (同模式)" + - "同步修复: smoke_test.cpp 三处 std::free -> dstalk_free (与 main.cpp:110 一致)" + - "编译: 0 error; 测试: smoke test passed" + - "发现: initialize_all() 在首个插件失败时停止，使后续插件无法初始化 (预存 bug, 非本次引入)" + - "发现: deepseek/session 插件 Boost JSON 链接错误 (预存问题, 与本次修复无关)" current_groups: [] --- diff --git a/agents/engineer-sun/profile.md b/agents/engineer-sun/profile.md index 1de469d..c3f4072 100644 --- a/agents/engineer-sun/profile.md +++ b/agents/engineer-sun/profile.md @@ -20,5 +20,14 @@ performance_log: - date: 2026-05-27 event: "入职 dstalk 团队" rating: ongoing + - date: 2026-05-27 + event: "W6.1: 修复 LSP reader_loop 协议合规 bug（Content-Length 状态机解析）" + rating: completed + details: | + 将 reader_loop 改为状态机模式读取 header 块：循环 read_line 直到空行， + 累积 Content-Length，遇到其他 header（如 Content-Type）不丢弃。 + 修复前：第一行非 Content-Length 时 continue 丢弃该行，导致 header 解析偏移错位。 + 修复后：正确遍历所有 header 行，空行后若仍未找到 Content-Length 则记录错误并跳过帧。 + 编译通过，smoke test 通过。 current_groups: [] --- diff --git a/agents/engineer-zhao/profile.md b/agents/engineer-zhao/profile.md index eb8e48d..e3c67fa 100644 --- a/agents/engineer-zhao/profile.md +++ b/agents/engineer-zhao/profile.md @@ -33,6 +33,9 @@ performance_log: - date: 2026-05-27 event: "独立执行 C3 CI编译脚本任务" rating: ongoing + - date: 2026-05-27 + event: "W9.6: CLI新增/history[N]命令，含三种边界处理；/status增加history count；build 0 error 0 warning；已用batch模式验证空history和无效N场景" + rating: A current_groups: - grp-ai-plugins (待命) --- diff --git a/agents/engineer-zhou/profile.md b/agents/engineer-zhou/profile.md index bfde4f5..121a4b4 100644 --- a/agents/engineer-zhou/profile.md +++ b/agents/engineer-zhou/profile.md @@ -20,5 +20,14 @@ performance_log: - date: 2026-05-27 event: "入职 dstalk 团队" rating: ongoing + - date: 2026-05-27 + event: "W5.1 - network_plugin SSE 改 buffer_body" + detail: | + do_post_stream response parser: http::string_body -> http::buffer_body. + 消除 parser 完整 body + fragment + result_body 三份冗余。 + 编译 0 error 0 warning, smoke test 通过. + 峰值内存: -67% (~360KB -> ~120KB), 无额外拷贝. + 留待真实 API 压测验证 end-to-end. + rating: good current_groups: [] --- diff --git a/agents/qa-liu/profile.md b/agents/qa-liu/profile.md index 35693ba..1057aad 100644 --- a/agents/qa-liu/profile.md +++ b/agents/qa-liu/profile.md @@ -20,5 +20,8 @@ performance_log: - date: 2026-05-27 event: "入职 dstalk 团队" rating: ongoing + - date: 2026-05-27 + event: "W9.10: host_api 单元测试 (8 cases, tests/host_api_test.cpp)" + rating: completed current_groups: [] --- diff --git a/agents/qa-wang/profile.md b/agents/qa-wang/profile.md index 214a520..a3e453e 100644 --- a/agents/qa-wang/profile.md +++ b/agents/qa-wang/profile.md @@ -31,8 +31,8 @@ performance_log: event: "C1 编码完成：6项修改全部正确，竞态彻底消除" rating: A+ - date: 2026-05-27 - event: "晋升为核心质量小组(grp-quality-core)组长，与林深协作执行C2" - rating: ongoing + event: "W7: smoke test 插件加载修复。tests/CMakeLists.txt 增加 POST_BUILD 拷贝逻辑，修复5个插件 Boost.JSON header-only 链接，实现 9/9 插件加载，所有 [Block] 零 WARN，100% pass" + rating: A+ current_groups: - grp-quality-core (组长) --- diff --git a/agents/security-cao/profile.md b/agents/security-cao/profile.md index 9e7b3ff..957bcef 100644 --- a/agents/security-cao/profile.md +++ b/agents/security-cao/profile.md @@ -21,5 +21,21 @@ performance_log: - date: 2026-05-27 event: "入职 dstalk 团队" rating: ongoing + - date: 2026-05-27 + event: "W2.2: api_key 在 on_shutdown 时安全清零 (deepseek + anthropic)" + rating: done + detail: | + 在 deepseek_plugin.cpp 和 anthropic_plugin.cpp 的 anonymous namespace 内 + 新增 secure_zero(void*, size_t)，通过 volatile 写零循环对 g_cfg.api_key + 执行安全擦除后 clear。编译：0 error 0 warning（与改动相关的文件）。 + - date: 2026-05-27 + event: "W9.3: 错误日志凭证泄露审计（8文件，0真实漏洞）" + rating: done + detail: | + 审计了 8 个文件的所有 host->log / printf / fprintf(stderr) / std::cerr 调用。 + 0 真实可利用漏洞。deepseek/anthropic 的 configure 日志有意排除了 api_key； + build_headers_json() 产生的凭证字符串仅通过内存传递给 Beast HTTP，未经过日志管道。 + 低风险/假阳性 2 项（lsp server_cmd 日志 + network e.what() 异常信息），无需代码修改。 + 审计报告写入 docs/explanation/security-logging.md。CVSS: N/A（无可利用漏洞）。 current_groups: [] --- diff --git a/agents/writer-deng/profile.md b/agents/writer-deng/profile.md index 05f1180..8811356 100644 --- a/agents/writer-deng/profile.md +++ b/agents/writer-deng/profile.md @@ -20,5 +20,8 @@ performance_log: - date: 2026-05-27 event: "入职 dstalk 团队" rating: ongoing + - date: 2026-05-27 + event: "Diátaxis 第二刀: 补充 Explanation 类文档 — architecture.md (插件架构哲学/三层模型/C ABI) + plugin-lifecycle.md (生命周期/拓扑排序/on_init on_shutdown 契约/ABI 纪律), 更新 docs/README.md 导航" + rating: completed current_groups: [] --- diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..c5577f6 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,72 @@ +# dstalk 文档 + +> 文档采用 [Diataxis](https://diataxis.fr/) 框架组织: 教程 / 操作指南 / 解释 / 参考 四类分离。 + +--- + +## 已有文档 + +### 教程 (Tutorials) — 从零开始的学习路径 + +| 文档 | 说明 | +|------|------| +| [快速入门](tutorial/quick-start.md) | 5 步上手: 安装工具链、编译、配置、运行、第一个对话 | + +### 解释 (Explanation) — 背景与设计决策 + +| 文档 | 说明 | +|------|------| +| [架构哲学](explanation/architecture.md) | 为什么是插件架构, host/plugin/service 三层模型, service registry 和 event bus 的职责, C ABI 的选择理由 | +| [插件生命周期](explanation/plugin-lifecycle.md) | DLL 加载与拓扑排序, on_init/on_shutdown 契约, 跨 DLL 堆分配与 ABI 纪律 | + +### 参考 (Reference) — 精确的技术描述 + +| 文档 | 说明 | +|------|------| +| [CLI 命令速查](reference/commands.md) | 全部 CLI 命令的别名、作用与示例 | +| [Plugin ABI 契约](reference/plugin-abi.md) | 跨 DLL 通信的 C ABI 规范：内存所有权、堆纪律、回调线程安全 | + +--- + +## 未来计划 + +### 教程 + +- [ ] **插件开发入门** (`tutorial/plugin-dev.md`) — TODO: 写一个 Hello World 插件, 注册服务并调用 +- [ ] **LSP 集成教程** (`tutorial/lsp-setup.md`) — TODO: 配置 clangd 并在 dstalk 中使用诊断/补全 + +### 操作指南 (How-to Guides) — 解决具体问题 + +- [ ] **切换 AI 后端** (`how-to/switch-provider.md`) — TODO: 在 DeepSeek / Anthropic / OpenAI 间切换 +- [ ] **配置 API Key** (`how-to/config-api-key.md`) — TODO: config.toml 各项配置说明与安全建议 +- [ ] **使用 File 命令管理项目文件** (`how-to/file-commands.md`) — TODO: 列目录、查看、读写文件的工作流 +- [ ] **自定义前端开发** (`how-to/custom-frontend.md`) — TODO: 基于 C ABI 编写自己的前端程序 +- [ ] **批处理模式** (`how-to/batch-mode.md`) — TODO: `--batch` 标志与非交互式使用 + +### 解释 (Explanation) — 背景与设计决策 + +- [x] **架构哲学** (`explanation/architecture.md`) — 插件架构、三层模型、service registry/event bus、C ABI 选择 +- [x] **插件生命周期** (`explanation/plugin-lifecycle.md`) — DLL 加载、拓扑排序、on_init/on_shutdown 契约、ABI 纪律 +- [ ] **为什么用 C/C++** (`explanation/why-cpp.md`) — TODO: 启动速度、内存占用、运行时依赖、嵌入能力的对比分析 +- [ ] **Diataxis 文档框架** (`explanation/diataxis.md`) — TODO: 本文档组织方式的设计思路 + +### 参考 + +- [ ] **API 参考** (`reference/api.md`) — TODO: dstalk_host.h 完整 API 说明与调用示例 +- [ ] **配置参考** (`reference/config.md`) — TODO: config.toml 所有字段的详细说明 +- [ ] **服务接口参考** (`reference/services.md`) — TODO: dstalk_services.h 中所有 vtable 接口定义 + +--- + +## 文档约定 + +- 命令以 `$ ` 前缀表示, 在终端中运行 +- 代码块标注语言 (```c, ```toml, ```bash 等) +- [ ] 表示计划中未完成的文档 + +--- + +## 贡献文档 + +文档使用 Markdown 编写, 存放在 `docs/` 目录下。 +欢迎通过 PR 补充或修正文档内容。 diff --git a/docs/explanation/architecture.md b/docs/explanation/architecture.md new file mode 100644 index 0000000..ac5dbc9 --- /dev/null +++ b/docs/explanation/architecture.md @@ -0,0 +1,138 @@ +# dstalk 架构哲学 + +> **本文属于**: Explanation -- 解释"为什么这么设计"，建立心智模型。 +> 不涉及具体 API 签名或配置字段，那属于 Reference 的职责。 + +--- + +## 为什么是插件架构？ + +dstalk 选择的不是单体架构，而是**以 C ABI 为边界的插件架构**。这是几条需求推导出的必然结果： + +1. **AI 后端会变**。DeepSeek / OpenAI / Anthropic 各有不同的 HTTP 协议细节和模型参数。今天用 A，明天切 B，后天同时挂两个。单体应用内硬编码所有后端会导致每次新增后端都要改核心、重新编译、重新测试。 + +2. **能力会增长**。LSP 集成、文件管理、会话持久化、工具调用——这些能力不是 CLI 启动时必须加载的。使用者可能只需要聊天，不需要 LSP。插件架构让能力按需加载，启动更快，内存更省。 + +3. **插件作者不是核心团队**。第三方应该能用自己的编译器、自己的 C++ 标准库版本编写插件，而不必须链接 dstalk-core 的静态库。这要求 ABI 稳定。C ABI 是唯一具有跨编译器二进制兼容性的选择。 + +**一句话心智模型**: 不要想象一个胖二进制把所有功能静态链接在一起；想象一个内核 (host) + 一圈可插拔的服务单元 (plugin)，内核只负责编排，不负责实现。 + +--- + +## 三层模型 + +dstalk 的架构由 3 层组成。从上到下看，每一层依赖下一层提供的抽象： + +``` +┌────────────────────────────────────────────┐ +│ Plugin (DLL) │ +│ 实现具体能力：AI 聊天、文件读写、LSP... │ +│ 通过服务注册表向其他插件暴露自己的功能 │ +├────────────────────────────────────────────┤ +│ Host (dstalk-core) │ +│ 拥有事件总线、服务注册表、插件加载器、配置 │ +│ 提供一个 dstalk_host_api_t 接口给所有插件 │ +├────────────────────────────────────────────┤ +│ Service (C vtable) │ +│ 抽象接口：ai / http / session / file_io... │ +│ 消费者通过 query_service 查找，不看实现者是谁│ +└────────────────────────────────────────────┘ +``` + +### Host 层 + +Host 是 dstalk 的 **编排内核**。它自己不做 AI 推理，不读写文件，不管理会话。 + +Host 拥有四样东西： + +- **配置存储 (ConfigStore)**: 管理 `config.toml` 的加载和键值查询。 +- **事件总线 (EventBus)**: 插件间松耦合通信的唯一通道。 +- **服务注册表 (ServiceRegistry)**: 按名称 + 版本号存储和查找服务 vtable。 +- **插件加载器 (PluginLoader)**: 扫描 `plugins/` 目录、加载 DLL、按依赖拓扑排序后调用初始化。 + +Host 启动时，按严格顺序执行： +1. 分配上述四个组件。 +2. 加载 `config.toml`（如果提供了路径）。 +3. 扫描 `plugin_dir` 目录下所有 `.dll` / `.so` 文件。 +4. 调用每个插件的 `dstalk_plugin_init()` 获取插件描述符。 +5. 按依赖拓扑排序执行 `on_init`。 + +### Plugin 层 + +每个插件是一个**独立的动态库**，导出一个唯一入口函数 `dstalk_plugin_init()`。 + +该入口返回一个 `dstalk_plugin_info_t`，声明了： +- 插件名称（依赖解析时的唯一标识）。 +- 依赖列表（必须先于本插件初始化的其他插件名）。 +- 生命周期回调（`on_init` / `on_shutdown`）。 +- 可选的事件回调（`on_event`）。 + +插件在 `on_init` 中做三件事： +1. 保存 `host_api` 指针，这是它此后访问一切 Host 能力的唯一通道。 +2. 通过 `host_api->query_service` 查找它依赖的服务（例如 deepseek 插件查询 `http` 和 `config`）。 +3. 通过 `host_api->register_service` 向注册表注册自己提供的服务 vtable。 + +关键设计：插件之间**不直接链接**。插件 A 不知道插件 B 是否在当前进程中。A 只对 Host 说"我需要名为 `http` 的服务"，Host 从注册表里找出那个 vtable，把指针交给 A。 + +### Service 层 + +Service 是**纯 C vtable**——一个包含函数指针的结构体。以 `dstalk_ai_service_t` 为例： + +``` +struct dstalk_ai_service_t { + int (*configure)(...); + dstalk_chat_result_t (*chat)(...); + dstalk_chat_result_t (*chat_stream)(...); + void (*free_result)(dstalk_chat_result_t*); +}; +``` + +每种服务都有一个预定义的 vtable 结构体（定义在 `dstalk_services.h`）。第三方也可以扩展自己的服务 vtable，版本号随注册一起提供，允许消费者做最低版本检查。 + +服务注册采用 **name + version** 两要素： +- 全局唯一名称（如 `"ai.deepseek"`、`"http"`、`"file_io"`）。 +- 版本号（消费者可以要求 `min_version`）。 + +--- + +## Service Registry 解决什么问题？ + +核心问题是 **耦合方向**。如果不使用注册表，deepseek 插件就得直接知道 http 插件的符号，通过 `dlsym` 或头文件耦合。换成注册表后： + +- 提供者说："我注册一个名为 `http` 的 vtable"。 +- 消费者说："给我一个名为 `http`、版本 >= 1 的 vtable"。 +- Host 做中间人查表。 + +**效果**: 你可以用任意方式实现 `http` 服务——用 libcurl、用 WinHTTP、用 mock——deepseek 插件一行代码都不需要改。它只依赖服务接口，不依赖服务实现。 + +--- + +## Event Bus 解决什么问题？ + +服务注册表解决的是**调用链**："我需要你，你给我提供服务"。但架构里还有另一类通信需求——**通知链**："某件事发生了，关心的人自行处理"。 + +举例： +- 会话清空了 (`DSTALK_EVENT_SESSION_CLEAR`)——所有关心会话状态的插件应当知道。 +- 配置更新了 (`DSTALK_EVENT_CONFIG_CHANGED`)——读取了配置的插件应当刷新。 +- 插件加载/卸载——其他插件可能需要重新查询依赖。 + +Event Bus 把这些需求抽象为**发布-订阅**： +- 发布者不知道谁在听。 +- 订阅者不知道谁在发布。 +- 发布者和订阅者通过事件类型编号耦合（如 `DSTALK_EVENT_SESSION_CLEAR = 2`）。 + +**效果**: 新写一个监控插件，只需 `event_subscribe` 即可收到所有感兴趣的事件，不需要修改任何现有代码。 + +--- + +## 为什么所有插件用 C ABI？ + +C++ 没有稳定的 ABI。不同编译器（MSVC / GCC / Clang）、不同编译器版本、不同标准库版本（libstdc++ vs libc++）之间，C++ 类的内存布局、虚函数表布局、异常展开机制都不保证兼容。 + +C ABI 的保证： +- 编译单元之间传递的只有**结构体**和**函数指针**。 +- 结构体布局确定（`dstalk_plugin_info_t` 的字段顺序不会变）。 +- 函数调用约定确定（`extern "C"` 关闭 name mangling）。 +- 所有内存分配通过 Host 提供的 `alloc/free`，而非各自调用 `malloc/free`（不同 DLL 使用不同运行时库的 `malloc` 会崩溃）。 + +**一句话心智模型**: C ABI 是唯一能保证"用 MSVC 编译的插件在 GCC 编译的 host 中运行"的接口层。代价是只能传递纯数据结构和函数指针，不能使用异常、重载或模板跨 DLL 边界。 diff --git a/docs/explanation/plugin-lifecycle.md b/docs/explanation/plugin-lifecycle.md new file mode 100644 index 0000000..2858ff0 --- /dev/null +++ b/docs/explanation/plugin-lifecycle.md @@ -0,0 +1,167 @@ +# 插件生命周期 + +> **本文属于**: Explanation -- 解释插件从加载到卸载的完整生命周期和关键契约。 +> 不涉及具体 API 签名细节，那属于 Reference (`reference/api.md`) 的职责。 + +--- + +## 总览 + +一个 dstalk 插件从磁盘上的 DLL 文件到进程中活跃的服务提供者，经历了四个阶段： + +``` + 加载 DLL → 依赖解析 → on_init → on_shutdown +(load_plugin) (topo sort) (初始化) (逆序清理) +``` + +--- + +## 阶段 1：DLL 加载 + +Host 调用 `load_plugin(path)`，由 `PluginLoader` 执行： + +1. **加载动态库**。Windows 用 `LoadLibraryA`；Linux 用 `dlopen(..., RTLD_NOW | RTLD_LOCAL)`。注意 Linux 端使用了 `RTLD_LOCAL` 而非 `RTLD_GLOBAL`，这意味着每个插件的符号默认对其他插件不可见——跨插件通信必须通过 Host API，不能通过直接符号引用。 + +2. **查找入口函数**。Host 在 DLL 中搜索名为 `dstalk_plugin_init` 的符号，调用它获取 `dstalk_plugin_info_t*`。 + +3. **版本校验**。Host 检查 `info->api_version` 是否等于 `DSTALK_API_VERSION`。不匹配则拒绝加载——这是防止 ABI 断裂的第一道防线。 + +4. **存储元数据**。`PluginInfo` 被存入 `plugins_` map，此时 `initialized = false`，插件尚未初始化。 + +**关键点**: 加载阶段只做符号获取和版本校验，不调用 `on_init`。这意味着插件代码此时尚未运行，不持有任何资源。 + +--- + +## 阶段 2：依赖解析（拓扑排序） + +所有插件加载完毕后，`initialize_all` 在调用 `on_init` 之前先执行拓扑排序。 + +**为什么需要排序？** 如果 deepseek 插件依赖 `http` 和 `config`，那么 `http` 和 `config` 插件的 `on_init` 必须先于 deepseek 执行——否则 deepseek 在 `on_init` 中调用 `query_service("http")` 会得到 `nullptr`。 + +**算法**：Kahn 算法（BFS 拓扑排序）。 + +1. 构建 `name → id` 的映射表。 +2. 为每个插件计算入度（in-degree = 被多少个其他插件依赖）。 +3. 从入度为 0 的节点（无依赖或依赖已满足的插件）开始，逐层输出。 +4. 最终检查：若输出节点数不等于总节点数，说明存在**循环依赖**，抛出异常阻止初始化。 + +依赖声明在 `dstalk_plugin_info_t.dependencies` 中，以 NULL 结尾的字符串数组。最多 `DSTALK_MAX_DEPS` (8) 个依赖。 + +``` +// 示例：deepseek 插件声明依赖 http 和 config +{ "http", "config", NULL } +``` + +依赖名称与目标插件的 `info->name` 字段匹配（如 `"file-io"` 不是 DLL 的文件名），因此依赖声明和插件命名必须一致。 + +--- + +## 阶段 3：on_init 的契约 + +`on_init` 是插件获得生命信号的地方。Host 按拓扑排序的结果依次调用每个插件的 `on_init`，传入 `dstalk_host_api_t*`。 + +### 契约条款 + +**契约 1：host_api 在 on_init 执行期间完全可用。** + +`dstalk_host_api_t` 是插件访问一切 Host 能力的唯一通道。它的所有字段（`register_service`、`query_service`、`log`、`alloc`、`free` 等）在 `on_init` 调用时已经有效。插件应当将这个指针保存为全局变量——每次跨 API 调用都需要它。 + +```c +static const dstalk_host_api_t* g_host = nullptr; + +static int on_init(const dstalk_host_api_t* host) { + g_host = host; // 保存，此后的所有 API 调用都用它 + // ... +} +``` + +**契约 2：query_service 查找依赖。** 插件在 `on_init` 中查询它声明的每一个依赖。如果某个依赖不存在，`on_init` 应当返回非零值，告知 Host 初始化失败。 + +```c +g_http = (dstalk_http_service_t*)host->query_service("http", 1); +if (!g_http) return -1; // 依赖缺失，初始化失败 +``` + +Host 收到非零返回值后，会跳过后续插件的初始化并报告警告。 + +**契约 3：register_service 注册自己的服务。** 插件将自己的 vtable 注册到服务注册表后，其他依赖它的插件才能在后续的 `on_init` 中通过 `query_service` 找到它。 + +```c +return host->register_service("ai.deepseek", 1, &g_service); +``` + +注册表内的 vtable 是原始指针，不拷贝。因此 vtable 指向的结构体必须是**静态生命周期**（全局变量或 static 局部变量）。 + +**契约 4：不要在 on_init 中做阻塞操作。** 当前 Host 是单线程初始化，阻塞一个插件的 `on_init` 会阻塞整个启动流程。如果需要异步初始化（如连接远程服务），在 `on_init` 中仅做最基本的 vtable 注册，把长连接放到首次服务调用时再建立。 + +**契约 5：所有内存分配通过 host_api->alloc/free。** 见下文"ABI 纪律"节。 + +--- + +## 阶段 4：on_shutdown 的契约 + +Host 关闭时，按拓扑排序的**逆序**调用 `on_shutdown`——这保证了被依赖者后卸载。 + +``` +加载顺序: config → http → deepseek +卸载顺序: deepseek → http → config +``` + +注意：如果拓扑排序失败（如循环依赖），`shutdown_all` 会退化为任意顺序，仅保证所有插件的 `on_shutdown` 都被调用、所有 DLL 句柄都被释放。 + +### 契约条款 + +**契约 1：逆序卸载，释放持久的服务引用。** 在 `on_init` 中保存的服务指针（如 `g_http`）应在 `on_shutdown` 中置为 `nullptr`。这防止插件在卸载后仍持有悬垂指针——虽然当前实现是在 `on_shutdown` 之后才释放 DLL，但防御性置空是好习惯。 + +```c +static void on_shutdown() { + g_http = nullptr; + g_config = nullptr; + g_host = nullptr; +} +``` + +**契约 2：不能跨 DLL 堆边界释放。** 在插件 A 的 `on_shutdown` 中，如果还持有插件 B 分配的内存，不能简单地调用 `g_host->free`——这会触发跨堆释放的未定义行为。正确做法是调用提供方的专属释放函数（如 AI 服务的 `free_result`），或让提供方在 `on_shutdown` 中清理自己分配的资源。 + +**契约 3：删除已注册的服务。** 当前 `ServiceRegistry` 不自动清理。如果一个服务 remove 了对应的插件，应该在卸载期间调用 `unregister_service`。当前实现未强制这一点，但关闭过程会销毁整个 `ServiceRegistry`，所以注销是可选的（若不注销，重启 host 时不会残留）。 + +--- + +## ABI 纪律：为什么 Host 提供 alloc / free + +这是插件架构中最容易被忽视但最容易出错的问题。 + +**问题**：在 Windows 上，每个 DLL 可能链接不同的 CRT（C 运行时库）。DLL A 用 MSVC 2022 的 `malloc` 分配内存，DLL B 用 MSVC 2019 的 `free` 释放——两个 `free` 管理不同的堆，导致崩溃或堆损坏。 + +**解决**：dstalk 要求所有跨 DLL 边界的内存操作使用 Host 提供的统一分配/释放函数： + +| 操作 | 用这个 | +|------|--------| +| 分配内存 | `host_api->alloc(size)` → 调用 host 启动时链接的 `malloc` | +| 释放内存 | `host_api->free(ptr)` → 调用 host 启动时链接的 `free` | +| 复制字符串 | `host_api->strdup(s)` → 用 host 的 `malloc` + `memcpy` | + +```c +// 正确：跨 DLL 返回的字符串用 host 分配 +r.content = g_host->strdup(ctx.accumulated.c_str()); + +// 正确：调用方释放跨 DLL 返回的数据用 host 释放 +g_host->free((void*)result->content); + +// 错误：用本地 malloc 分配跨 DLL 边界的数据 +// r.content = strdup(...); // 消费者的 free() 和此 strdup 的 malloc() 可能不同堆！ +``` + +**规则记忆**: 谁分配，谁负责提供释放手段。dstalk 的选择是让 Host 统一分配——所有 `alloc/free` 调用走同一个 CRT 的堆。 + +--- + +## 生命周期速查 + +| 阶段 | 谁触发 | 插件状态 | 关键函数 | +|------|--------|----------|----------| +| DLL 加载 | `dstalk_init` 或 `dstalk_plugin_load` | 未初始化 | `load_plugin` → `dstalk_plugin_init()` | +| 依赖排序 | `initialize_all` | 等待初始化 | `topological_sort()` (Kahn) | +| 初始化 | Host 按序调用 | 运行中 | `on_init(host_api)` | +| 服务调用 | 任意插件/CLI 前端 | 运行中 | `query_service` → vtable 调用 | +| 卸载 | `dstalk_plugin_unload` 或 `dstalk_shutdown` | 关闭中 | `on_shutdown()` → `FreeLibrary`/`dlclose` | diff --git a/docs/explanation/security-logging.md b/docs/explanation/security-logging.md new file mode 100644 index 0000000..507b7c2 --- /dev/null +++ b/docs/explanation/security-logging.md @@ -0,0 +1,109 @@ +# Security Logging Audit (W9.3): 错误日志凭证泄露审计 + +**审计人**: 曹武 (security-cao) +**日期**: 2026-05-27 +**审计范围**: 8 个核心/插件源码文件 +**结论**: 未发现真实凭证泄露漏洞（CVSS 不适用，零高危/中危/低危可利用漏洞） + +--- + +## 审计方法论 + +对每个文件搜索以下输出调用: +- `host->log(...)` / `g_host->log(...)` (插件日志 API) +- `printf` / `fprintf(stderr, ...)` (C 标准输出) +- `std::cerr` / `std::cout` (C++ 标准流) + +对每个匹配项检查其格式字符串和参数是否包含 `api_key`、`Authorization` header、`token` 或原始 request body/headers。 + +## 文件清单 + +### 1. `plugins/deepseek/src/deepseek_plugin.cpp` -- 安全 + +| 行号 | 调用 | 内容 | 风险 | +|------|------|------|------| +| 242-245 | `g_host->log(INFO, ...)` | 输出 model / base_url / max_tokens / temperature | 无 -- api_key 被有意排除在格式字符串外 | +| 442 | `g_host->log(ERROR, ...)` | 静态字符串 "http service not found" | 无 | +| 446 | `g_host->log(INFO, ...)` | 静态字符串 "initializing DeepSeek AI plugin" | 无 | +| 453 | `g_host->log(INFO, ...)` | 静态字符串 "shutdown" | 无 | + +**build_headers_json() (行 59-63)**: 构建 `{"Authorization":"Bearer "}` 并传给 HTTP 服务。该字符串从未传递给任何 log 调用，仅在 `http_post_json()` / `http_post_stream()` 的参数链中使用，最终由 Beast 直接设置到 HTTP request headers -- 全程无日志记录。 + +**parse_response() 错误路径 (行 135-151)**: HTTP 错误响应体仅用于提取 JSON `error.message` 字段放入 `r.error`，不会输出到日志。原始 response_body 在解析后被 `g_host->free()` 释放。 + +### 2. `plugins/anthropic/src/anthropic_plugin.cpp` -- 安全 + +| 行号 | 调用 | 内容 | 风险 | +|------|------|------|------| +| 247-250 | `g_host->log(INFO, ...)` | 输出 model / base_url / max_tokens / temperature | 无 -- api_key 被有意排除 | +| 453 | `g_host->log(ERROR, ...)` | 静态字符串 "http service not found" | 无 | +| 457 | `g_host->log(INFO, ...)` | 静态字符串 "initializing Anthropic AI plugin" | 无 | +| 464 | `g_host->log(INFO, ...)` | 静态字符串 "shutdown" | 无 | + +**build_headers_json() (行 59-65)**: 构建 `{"x-api-key":"","anthropic-version":"2023-06-01"}` 仅用于 HTTP 请求，不经过日志路径。 + +### 3. `plugins/network/src/network_plugin.cpp` -- 安全 + +| 行号 | 调用 | 内容 | 风险 | +|------|------|------|------| +| -- | 无任何 `host->log` / `printf` / `cerr` 调用 | -- | 无 | + +**parse_headers_json() (行 40-80)**: 解析包含 api_key 的 headers JSON 字符串。解析结果仅用于 `req.set(h.first, h.second)` (行 176) 设置 HTTP header，不输出日志。 + +**do_post_stream() 异常路径 (行 280-282)**: `catch (std::exception& e)` 将 `e.what()` 赋值给 `result_body`。Beast/ASIO 异常消息为 OS 级别错误描述（如 "Connection refused"），不含 HTTP header/body 内容。 + +### 4. `plugins/config/src/config_plugin.cpp` -- 安全 + +| 行号 | 调用 | 内容 | 风险 | +|------|------|------|------| +| -- | 无任何日志调用 | -- | 无 | + +ConfigStore 仅提供 get/set/load_file，无日志输出。 + +### 5. `dstalk-core/src/host.cpp` -- 基础设施（不动） + +| 行号 | 调用 | 内容 | 风险 | +|------|------|------|------| +| 48,51,52 | `fprintf(stderr, ...)` | 日志前缀 + vfprintf(格式,参数) + 换行 | 无 -- 基础设施自身不包含业务数据 | + +该文件是日志基础设施 (`host_log_impl`)，仅负责格式化输出。安全性依赖于调用方不传敏感数据（本审计已确认所有调用方均安全）。按 W9.3 禁忌不修改此文件。 + +### 6. `dstalk-core/src/plugin_loader.cpp` -- 安全 + +| 行号 | 调用 | 内容 | 风险 | +|------|------|------|------| +| -- | 无任何日志调用 | -- | 无 | + +### 7. `plugins/session/src/session_plugin.cpp` -- 安全 + +| 行号 | 调用 | 内容 | 风险 | +|------|------|------|------| +| 233 | `host->log(ERROR, ...)` | 静态字符串 "required service 'file_io' not found" | 无 | + +该插件处理消息内容（role/content）但不记录任何消息数据到日志。 + +### 8. `plugins/lsp/src/lsp_plugin.cpp` -- 低风险 + +| 行号 | 调用 | 内容 | 风险 | +|------|------|------|------| +| 446 | `g_host->log(ERROR, ...)` | 静态字符串 "Invalid LSP frame..." | 无 | +| 479 | `g_host->log(ERROR, ...)` | `"failed to start: %s", server_cmd` | 低 -- 理论上 server_cmd 可能含令牌，但实际为 LSP 服务器路径（如 `clangd`），不属于 API 密钥范畴 | +| 525 | `g_host->log(ERROR, ...)` | 静态字符串 "initialize timed out" | 无 | +| 535 | `g_host->log(INFO, ...)` | `"server started: %s", server_cmd` | 低 -- 同上 | +| 565 | `g_host->log(INFO, ...)` | 静态字符串 "server stopped" | 无 | +| 720 | `g_host->log(INFO, ...)` | 静态字符串 "initializing LSP service plugin" | 无 | +| 728 | `g_host->log(INFO, ...)` | 静态字符串 "shutdown" | 无 | + +`server_cmd` 是启动 LSP 子进程的命令行（例如 `clangd --log=error`），不是 API 密钥或 token。若用户将 API key 嵌入命令行（极不寻常且不安全的使用方式），则存在理论泄漏风险。判断为**低风险/假阳性**，不做代码修改。 + +## 总结 + +| 风险等级 | 数量 | 说明 | +|----------|------|------| +| 严重 (CVSS 9.0+) | 0 | 无 | +| 高危 (CVSS 7.0-8.9) | 0 | 无 | +| 中危 (CVSS 4.0-6.9) | 0 | 无 | +| 低危 (CVSS 0.1-3.9) | 0 | 无真实可利用漏洞 | +| 低风险/假阳性 | 2 | 仅 lsp `server_cmd` 日志和 network `e.what()` 理论上可能暴露非凭证信息 | + +**审计结论**: 所有日志输出路径均已检查，证实 DeepSeek 和 Anthropic 插件的 `my_configure()` 日志有意排除了 `api_key` 字段。HTTP headers 中的凭证仅通过内存传递至 Beast HTTP 请求对象，从未进入日志管道。代码库对此攻击面防御充分，无需修改。 diff --git a/docs/reference/commands.md b/docs/reference/commands.md new file mode 100644 index 0000000..dacf7da --- /dev/null +++ b/docs/reference/commands.md @@ -0,0 +1,39 @@ +# CLI 命令速查 + +dstalk 所有内置命令。在对话中直接输入 `/help` 或 `/h` 也可查看此列表。 + +--- + +## 命令表 + +| 命令 | 别名 | 作用 | 示例 | +|------|------|------|------| +| `/help` | `/h` | 显示命令列表 | `/help` | +| `/quit` | `/q` | 退出程序 | `/quit` | +| `/clear` | — | 清空当前会话上下文 | `/clear` | +| `/context` | — | 显示当前 Token 数和消息条数 | `/context` | +| `/status` | — | 显示当前运行状态 (脱敏: 不打印完整 API Key) | `/status` | +| `/model ` | — | 切换 AI 模型 | `/model deepseek-v4-pro` | +| `/file list [path]` | — | 列出目录内容, 不填 path 列出当前目录 | `/file list src/` | +| `/file show ` | — | 查看文件内容 | `/file show main.cpp` | +| `/file read ` | — | 读取文件内容 (同 `/file show`) | `/file read config.toml` | +| `/file write ` | — | 写入文件内容 | `/file write hello.c #include ...` | +| `/save ` | — | 保存当前会话到文件 | `/save session.json` | +| `/load ` | — | 从文件恢复会话 | `/load session.json` | + +--- + +## 命令规则 + +- 所有命令以 `/` 开头 +- 不以下划线开头的输入视为 AI 对话内容, 由 AI 服务处理 +- 模型切换即时生效, 不影响已累积的会话历史 +- `/file show` 和 `/file read` 功能相同, 均为读取并打印文件内容 +- `/status` 显示脱敏信息: API Key 只显示 "已设置" 或 "未设置", 不暴露完整值 + +--- + +## 相关文档 + +- [快速入门教程](../tutorial/quick-start.md) — 5 步上手 +- [文档导航](../README.md) — 全部文档索引 diff --git a/docs/reference/plugin-abi.md b/docs/reference/plugin-abi.md new file mode 100644 index 0000000..81ab74b --- /dev/null +++ b/docs/reference/plugin-abi.md @@ -0,0 +1,236 @@ +# dstalk Plugin ABI 契约 + +> **面向**: 插件作者、host 维护者 +> **性质**: 规范性文档。违反任何条目 = 未定义行为。 + +--- + +## 1. DSTALK_API_VERSION + +```c +#define DSTALK_API_VERSION 1 // dstalk_host.h +``` + +**语义**: 主版本号。当且仅当 `dstalk_host_api_t` 的字段布局、`dstalk_plugin_info_t` 的结构、或任意 +`*_service_t` vtable 的函数签名发生**不兼容变更**时 bump。 + +**不 bump 的情况**: 新增 event type 枚举值、新增日志级别、在 vtable 末尾追加函数指针（注意： +不能改变已有字段的偏移）。 + +**匹配规则**: `plugin::api_version` 必须**精确等于** `DSTALK_API_VERSION`。host 拒绝加载不匹配的 +插件（`plugin_loader.cpp:68`），不提供后向兼容。这是硬断点——旧插件在新 host 上重新编译即可适配， +二进制兼容不做保证。 + +**版本协商被拒绝的理由**: 早期版本刻意保持简单。如果未来需要协商（如 min/max version range）， +通过 bump `DSTALK_API_VERSION` 到 2 并定义协商结构体即可。W1.x 阶段不需要。 + +--- + +## 2. 内存所有权契约 + +Core rule: **谁分配，谁释放。分配函数必须与释放函数配对。** + +### 2.1 Host 分配的字符串 + +以下函数返回的 `const char*` / `char*` **由 host 拥有**，调用方不得释放： + +| 来源 | 示例 | 生命周期 | +|------|------|----------| +| `host->config_get(key)` | 配置值字符串 | 随 config 条目存在，或下次 `config_set` 覆盖前有效 | +| `dstalk_chat_result_t.content` | AI 回复 | 必须在读取后立即复制；下一轮 `chat()` 调用可能覆盖 | + +以下函数返回的 `char*` **由调用方释放**（用 `dstalk_free` / `host->free`）： + +| 函数 | 释放方式 | +|------|----------| +| `dstalk_strdup(s)` / `host->strdup(s)` | `dstalk_free(ptr)` / `host->free(ptr)` | +| `dstalk_plugin_list(output_json)` | `dstalk_free(*output_json)` | +| LSP 便捷函数 (`dstalk_lsp_*`) 的 `char** output` 参数 | `dstalk_free(*output)` | + +### 2.2 插件返回的字符串 + +`dstalk_plugin_info_t` 中的 `name`、`version`、`description` 由插件的 `dstalk_plugin_init()` +返回。host 在加载时读取并内部分配 `std::string` 副本（`plugin_loader.cpp:81-83`），随后不再 +引用原始指针。因此这些字符串的**生命周期只需覆盖 `init_fn()` 调用期间**——可以是静态字面量、 +栈上字符串、或插件内部分配的内存。 + +### 2.3 服务 vtable 的返回值 + +`dstalk_chat_result_t.content`、`.error`、`.tool_calls_json` 按结构体注释约定由 `dstalk_strdup` +分配，**调用方**（即查询该服务的插件）负责 `dstalk_free`。 + +**反例**: 插件直接返回 `std::string::c_str()` 或栈上 buffer —— 因为服务调用完成后插件栈帧 +可能已销毁。 + +--- + +## 3. 跨 DLL 堆纪律 + +### 3.1 问题 + +Windows 上每个 DLL 拥有独立的 CRT 堆（取决于链接方式：/MD 共享 或 /MT 静态）。插件在其 +CRT 中调用 `malloc` 得到的指针，host 调用 `free` 时访问的是 host CRT 的堆——行为未定义。 + +Linux/macOS 通常共享 libc，但静态链接或不同 libc 版本时同样可能 crash。 + +### 3.2 硬性规则 + +> **严禁插件直接调用 `malloc`/`free`/`strdup`/`new`/`delete` 处理 host 传入或传出的数据。** + +正确做法： + +| 场景 | 错误做法 | 正确做法 | +|------|----------|----------| +| 释放 host 给的字符串 | `free(host->config_get("key"))` | 不释放；只读后丢弃 | +| 分配传给 host 的缓冲区 | `malloc(256)` | `host->alloc(256)` 或 `dstalk_alloc(256)` | +| 释放 host 分配的内存 | `delete ptr` / `std::free(ptr)` | `host->free(ptr)` 或 `dstalk_free(ptr)` | +| 复制 host 给的字符串 | `strdup(host->config_get("k"))` | `host->strdup(...)` 或 `dstalk_strdup(...)` | +| 在插件 DLL 内分配/释放私有数据 | 可以用任何方式 | 只要不跨越 DLL 边界 | + +### 3.3 设计理由 + +`host->alloc` / `host->free` / `host->strdup` 是通过函数指针调回 host DLL 的 `malloc`/`free`， +保证分配和释放发生在**同一个堆**上。`g_host_api` 表的 `api_alloc`/`api_free` 直接就是 `malloc` +/`free`（`host.cpp:111-112`），所以 "host 分配 → host 释放" 总是在同一个 CRT 堆内。 + +--- + +## 4. register_service 契约 + +### 4.1 调用时机 + +`host->register_service(name, version, vtable)` **仅可在 `on_init` 回调期间调用**。 + +原因： +- 服务注册表 `ServiceRegistry` 在 `dstalk_init()` 内创建，`on_init` 之前已存在。 +- 初始化顺序由拓扑排序保证：依赖方的 `on_init` 在被依赖方之后调用，因此被依赖方注册的服务 + 在依赖方调用时已可用。 +- `on_shutdown` 期间不应注册新服务（该阶段仅做清理）。 + +### 4.2 重复注册 + +同一 `name` 不可重复注册：第二次调用返回 `-2`（`service_registry.cpp:13`）。插件应检查返回 +值，在共享服务名（如 `"ai.deepseek"`）的场景中避免冲突。 + +### 4.3 版本协商 + +`register_service` 的 `version` 参数声明了该 vtable 实现的版本。`query_service` 的 +`min_version` 允许调用方声明最低需求版本。当前实现为整型比较：`registered_version >= +min_version` 即可。 + +**插件作者约定**: version 从 1 开始。vtable 新增函数指针（追加到末尾）→ bump version。 +vtable 重排字段或删除函数 → 改 service name（如 `"lsp"` → `"lsp2"`）。 + +### 4.4 vtable 生命周期 + +注册的 vtable 指针在 `ServiceRegistry` 中存储，随插件存在。插件卸载时，`ServiceRegistry:: +unregister_service` 会被调用。**插件不得在卸载后继续持有该 vtable 指针**。 + +--- + +## 5. on_init / on_shutdown 契约 + +### 5.1 调用顺序保证 + +- **on_init**: 按拓扑顺序调用（依赖项先初始化）。由 `PluginLoader::topological_sort()` + 使用 Kahn 算法计算（`plugin_loader.cpp:144-198`）。 +- **on_shutdown**: 按拓扑顺序的**逆序**调用（依赖项后销毁）。如果拓扑排序因循环依赖失败， + 降级为任意顺序（`plugin_loader.cpp:263-267`）。 +- **增量加载**: `dstalk_plugin_load()` 只初始化新加载的插件（`initialize_pending`），已 + 初始化的插件不受影响。 + +### 5.2 返回值 + +`on_init` 返回 `0` = 成功；非零 = 失败。失败导致 `initialize_all` 返回 `-1`，整体初始化 +流程中止。失败插件的 `on_shutdown` **不会被调用**（`plugin.initialized` 保持 false）。 + +### 5.3 异常安全 (C++ ABI) + +> **C++ 异常不得穿越 C ABI 边界。** + +`on_init` 和 `on_shutdown` 定义为 C 函数指针： + +```c +int (*on_init)(const dstalk_host_api_t* host); +void (*on_shutdown)(void); +``` + +调用方（PluginLoader）**不设置** `try/catch` 保护（`plugin_loader.cpp:212-214`）。 +如果 `on_init` 由 C++ 实现且抛出异常，将导致 `std::terminate` / 未定义行为。 + +**防护规则**: +- 用 `extern "C"` 声明实现 +- 所有可能抛异常的 C++ 逻辑用 `try { ... } catch (...) { return -1; }` 包裹 +- `on_shutdown` 同理，即使 void 也不能抛异常 + +--- + +## 6. 回调线程安全 + +### 6.1 诊断回调 (diag_callback) + +`g_diag_callback` 为 `std::atomic`，使用 `memory_order_acquire` / `release` +（`host.cpp:28,54,305`）。**多线程同时调用 `dstalk_log` 安全**——每个线程独立读取原子指针， +无数据竞争。 + +### 6.2 事件总线 (EventBus) + +`EventBus` 使用 `std::shared_mutex`： +- `subscribe` / `unsubscribe` 持有 `unique_lock` +- `emit` 持有 `shared_lock` + +**结论**: 多线程 subscribe/unsubscribe/emit 安全。但 emit 持有 shared_lock 期间直接调用 +handler —— handler 内**不得调用 subscribe/unsubscribe**（会尝试 unique_lock 导致死锁）。 + +`on_event` 回调与 `on_init` / `on_shutdown` 之间无互斥保护，因此**不应在 `on_event` 回调 +内调用 host API 执行插件的 load/unload**（PluginLoader 无内部锁）。 + +### 6.3 服务注册表 (ServiceRegistry) + +使用 `std::shared_mutex`：register/unregister 持写锁，query 持读锁。并发安全。 + +### 6.4 配置 (ConfigStore) + +使用 `std::mutex`：get/set 串行化。`config_get` 返回的指针指向内部 `std::string`；在并发 +`config_set` 同一 key 后指针可能悬垂——调用方应复制。 + +### 6.5 Plugin Loader + +`PluginLoader` **无内部互斥**（`plugin_loader.hpp` 无 mutex 成员）。load/unload 不应在 +多线程中并发调用。这是 host 层的设计假设——仅 `dstalk_init` / `dstalk_shutdown` 和显式 +CLI 命令使用。 + +--- + +## 7. 依赖声明 (dependencies) + +### 7.1 语法 + +```c +const char* dependencies[DSTALK_MAX_DEPS]; // DSTALK_MAX_DEPS = 8 +``` + +以 `NULL` 终止的字符串数组，每个元素为被依赖插件的 `name`。 + +### 7.2 语义 + +- 被依赖项必须先于依赖方初始化（拓扑排序保证） +- 被依赖项必须后于依赖方销毁（逆序 shutdown） +- 如果被依赖项不存在：初始化时不影响拓扑排序（仅计算已加载插件间的依赖关系），但插件的 + `on_init` 自己应检查所需服务是否可用（通过 `host->query_service`） +- 循环依赖：拓扑排序失败，`topological_sort()` 抛出 `std::runtime_error("Circular + dependency detected")`，被 `initialize_all` 捕获并返回 `-1` +- 最大 8 个依赖，超出部分截断（`plugin_loader.cpp:90`） + +### 7.3 最佳实践 + +`on_init` 内通过 `host->query_service("service_name", min_version)` 验证依赖可用。 +不做假设。这也是一种隐式版本协商：如果 service version 不足，`on_init` 返回错误。 + +--- + +## 变更历史 + +| 日期 | 版本 | 变更 | +|------|------|------| +| 2026-05-27 | 1.0 | 初始版本。W9.4 交付。基于 DSTALK_API_VERSION=1 的当前实现。 | diff --git a/docs/tutorial/quick-start.md b/docs/tutorial/quick-start.md new file mode 100644 index 0000000..01f91ed --- /dev/null +++ b/docs/tutorial/quick-start.md @@ -0,0 +1,140 @@ +# 快速入门 + +5 步上手 dstalk, 从安装工具链到完成第一个 AI 对话。 + +--- + +## 1. 安装工具链 + +dstalk 需要 CMake、Ninja、LLVM/Clang 和 Conan2。`setup.bat` 全自动下载安装到 `tools/` 目录。 + +```bash +cd tools +setup.bat +``` + +> **前提**: 系统需已安装 Python 3.10+。 +> +> 网络不畅时, 可手动下载放入对应目录: +> - [Ninja](https://github.com/ninja-build/ninja/releases) → `tools/ninja/ninja.exe` +> - [CMake](https://cmake.org/download/) → `tools/cmake/bin/cmake.exe` +> - [LLVM](https://github.com/llvm/llvm-project/releases) → `tools/llvm/bin/clang.exe` +> - Conan2 通过 pip 安装到 `tools/.venv/Scripts/conan.exe` + +--- + +## 2. 编译 + +项目根目录提供 `build.bat`, 一键完成: Conan 拉取依赖 -> CMake 配置 -> Ninja 编译。 + +```bash +build.bat +``` + +编译产物输出到 `build/` 目录。核心产物: +- `build/dstalk-core/dstalk.dll` —— 核心 DLL +- `build/dstalk-cli/dstalk-cli.exe` —— 命令行前端 +- `build/plugins/*.dll` —— 功能插件 + +--- + +## 3. 创建 config.toml + +在项目根目录创建 `config.toml`, 配置 AI 后端和 API Key。 + +```bash +# 在项目根目录手动创建 config.toml +``` + +**config.toml 示例:** + +```toml +# 选择 AI 后端插件: ai.deepseek 或 ai.anthropic +ai.provider = "ai.deepseek" + +# DeepSeek +api.base_url = "https://api.deepseek.com/v1" +api.api_key = "sk-xxxxxxxx" +api.model = "deepseek-v4-pro" + +# Anthropic Claude (切换 ai.provider 为 "ai.anthropic" 即可) +# api.base_url = "https://api.anthropic.com/v1" +# api.api_key = "sk-ant-xxxxxxxx" +# api.model = "claude-opus-4-20250514" +``` + +> **关键**: 修改 `ai.provider` 字段即可在不同后端间切换, 无需改动代码。 +> +> API Key 可从 [DeepSeek 开放平台](https://platform.deepseek.com/) 或 [Anthropic Console](https://console.anthropic.com/) 获取。 + +--- + +## 4. 运行 dstalk-cli + +```bash +build/dstalk-cli/dstalk-cli.exe +``` + +启动后显示欢迎横幅: + +```text +dstalk v0.1.0 | dstalk AI | /help 查看帮助 | /quit 退出 + +[deepseek-v4-pro] > +``` + +> 图形模式默认关闭。需要 SDL3 GUI 时, 用 `-DDSTALK_BUILD_GUI=ON` 重新配置 CMake。 + +--- + +## 5. 第一个对话 + +在提示符 `>` 后输入自然语言, 即可与 AI 对话。 + +```text +[deepseek-v4-pro] > 帮我写一个读取 CSV 并计算平均值的 C 程序 + + [dstalk] 正在思考... + + #include + #include + + int main(int argc, char *argv[]) { + if (argc < 2) { + fprintf(stderr, "用法: %s \n", argv[0]); + return 1; + } + FILE *fp = fopen(argv[1], "r"); + if (!fp) { perror("fopen"); return 1; } + + double sum = 0.0; + int count = 0; + char line[1024]; + while (fgets(line, sizeof(line), fp)) { + sum += atof(line); + count++; + } + fclose(fp); + + printf("平均值: %.2f (共 %d 行)\n", sum / count, count); + return 0; + } + + 已写入 csv_avg.c。需要我帮你编译测试吗？ + +[deepseek-v4-pro] > 把这段代码改成支持表头的 + + [dstalk] 已更新 csv_avg.c——跳过第一行表头, 增加列选择功能。 + +[deepseek-v4-pro] > /file show csv_avg.c + + [dstalk] 已显示 csv_avg.c 内容。 +``` + +--- + +## 下一步 + +- 查看 [CLI 命令速查表](../reference/commands.md) 了解全部命令 +- 输入 `/help` 在 dstalk 内查看命令列表 +- 输入 `/status` 查看当前运行状态 diff --git a/dstalk-cli/CMakeLists.txt b/dstalk-cli/CMakeLists.txt index b3b18c8..35ad2af 100644 --- a/dstalk-cli/CMakeLists.txt +++ b/dstalk-cli/CMakeLists.txt @@ -9,9 +9,3 @@ add_executable(dstalk-cli target_link_libraries(dstalk-cli PRIVATE dstalk ) - -add_custom_command(TARGET dstalk-cli POST_BUILD - COMMAND ${CMAKE_COMMAND} -E copy_if_different - $ - $ -) diff --git a/dstalk-cli/src/main.cpp b/dstalk-cli/src/main.cpp index a90c991..39c76ab 100644 --- a/dstalk-cli/src/main.cpp +++ b/dstalk-cli/src/main.cpp @@ -92,6 +92,7 @@ static void print_help() std::printf(" %s/file write

%s 写入文件\n", CLR_YELLOW, CLR_RESET); std::printf(" %s/save %s 保存会话\n", CLR_YELLOW, CLR_RESET); std::printf(" %s/load %s 恢复会话\n", CLR_YELLOW, CLR_RESET); + std::printf(" %s/history [N]%s 查看会话历史（默认全部，可指定最近N条）\n", CLR_YELLOW, CLR_RESET); std::printf("\n直接输入问题即可与 AI 对话。\n\n"); } @@ -197,6 +198,9 @@ static void handle_command(const char* line) std::printf(" provider: %s\n", provider); std::printf(" AI 服务: %s\n", g_ai ? "就绪" : "不可用"); std::printf(" Session 服务: %s\n", g_session ? "就绪" : "不可用"); + int hc = 0; + if (g_session) g_session->history(&hc); + std::printf(" history count: %d\n", hc); std::printf(" File IO 服务: %s\n", g_file_io ? "就绪" : "不可用"); const dstalk_tools_service_t* tools = static_cast( dstalk_service_query("tools", 1)); @@ -261,6 +265,39 @@ static void handle_command(const char* line) return; } + // /history [N] + if (std::strcmp(line, "/history") == 0 || std::strncmp(line, "/history ", 9) == 0) { + if (!g_session) { + std::printf(CLR_RED "[ERROR] session service unavailable\n" CLR_RESET); + return; + } + int count = 0; + const dstalk_message_t* history = g_session->history(&count); + if (count == 0 || !history) { + std::printf(CLR_DIM "(history is empty)\n" CLR_RESET); + return; + } + int limit = count; + const char* arg = line + 8; + while (*arg == ' ') arg++; + if (*arg != '\0') { + char* end = nullptr; + long n = std::strtol(arg, &end, 10); + if (*end != '\0' || n <= 0) { + std::printf(CLR_RED "[ERROR] /history N: N must be a positive integer\n" CLR_RESET); + return; + } + limit = (n < count) ? static_cast(n) : count; + } + int start = count - limit; + for (int i = start; i < count; i++) { + std::printf("[%s] %s\n", + history[i].role ? history[i].role : "?", + history[i].content ? history[i].content : ""); + } + return; + } + // /save if (std::strncmp(line, "/save ", 6) == 0) { const char* path = line + 6; diff --git a/dstalk-core/CMakeLists.txt b/dstalk-core/CMakeLists.txt index 69ff29f..6656ca2 100644 --- a/dstalk-core/CMakeLists.txt +++ b/dstalk-core/CMakeLists.txt @@ -6,6 +6,14 @@ find_package(Boost REQUIRED CONFIG) find_package(OpenSSL REQUIRED CONFIG) +# 统一的 Boost 编译宏 (header-only 模式) +add_library(dstalk_boost_config INTERFACE) +target_compile_definitions(dstalk_boost_config INTERFACE + BOOST_ALL_NO_LIB + BOOST_ERROR_CODE_HEADER_ONLY + BOOST_JSON_HEADER_ONLY +) + add_library(dstalk SHARED src/host.cpp src/config_store.cpp @@ -20,8 +28,11 @@ target_include_directories(dstalk PRIVATE src ) +target_compile_features(dstalk PUBLIC cxx_std_20) + target_link_libraries(dstalk PRIVATE + dstalk_boost_config boost::boost openssl::openssl ) @@ -35,9 +46,6 @@ endif() target_compile_definitions(dstalk PRIVATE DSTALK_BUILD_DLL - BOOST_ALL_NO_LIB - BOOST_ERROR_CODE_HEADER_ONLY - BOOST_JSON_HEADER_ONLY INTERFACE DSTALK_USE_DLL ) diff --git a/dstalk-core/src/host.cpp b/dstalk-core/src/host.cpp index 6a6d68b..af37364 100644 --- a/dstalk-core/src/host.cpp +++ b/dstalk-core/src/host.cpp @@ -4,6 +4,7 @@ #include "service_registry.hpp" #include "plugin_loader.hpp" +#include #include #include #include @@ -24,7 +25,7 @@ namespace { dstalk::EventBus* g_event_bus = nullptr; dstalk::ServiceRegistry* g_service_registry = nullptr; dstalk::PluginLoader* g_plugin_loader = nullptr; - static dstalk_diag_cb g_diag_callback = nullptr; + static std::atomic g_diag_callback{nullptr}; // ---- 内部辅助 ---- @@ -50,10 +51,11 @@ namespace { vfprintf(stderr, fmt, args); fprintf(stderr, "\n"); // 转发到诊断回调 - if (g_diag_callback) { + auto cb = g_diag_callback.load(std::memory_order_acquire); + if (cb) { char buf[1024]; vsnprintf(buf, sizeof(buf), fmt, args_copy); - g_diag_callback(level, nullptr, 0, nullptr, buf); + cb(level, nullptr, 0, nullptr, buf); } va_end(args_copy); } @@ -300,7 +302,7 @@ DSTALK_API void dstalk_free(void* ptr) { free(ptr); } DSTALK_API char* dstalk_strdup(const char* s) { return host_strdup(s); } DSTALK_API void dstalk_set_diag_callback(dstalk_diag_cb cb) { - g_diag_callback = cb; + g_diag_callback.store(cb, std::memory_order_release); } // ============================================================ diff --git a/dstalk-core/src/plugin_loader.cpp b/dstalk-core/src/plugin_loader.cpp index 7cab26f..9f5cd4d 100644 --- a/dstalk-core/src/plugin_loader.cpp +++ b/dstalk-core/src/plugin_loader.cpp @@ -9,8 +9,10 @@ #endif #include +#include #include #include +#include namespace dstalk { @@ -199,9 +201,14 @@ std::vector PluginLoader::topological_sort() const int PluginLoader::initialize_all(const dstalk_host_api_t* host_api) { + if (!host_api) return -1; + try { std::vector order = topological_sort(); + std::unordered_set failed_names; + int failed_count = 0; + for (int id : order) { auto it = plugins_.find(id); if (it == plugins_.end()) continue; @@ -209,16 +216,40 @@ int PluginLoader::initialize_all(const dstalk_host_api_t* host_api) PluginInfo& plugin = it->second; if (plugin.initialized) continue; + // 检查依赖是否已失败 + bool dep_unavailable = false; + for (const auto& dep_name : plugin.dependencies) { + if (failed_names.count(dep_name)) { + dep_unavailable = true; + break; + } + } + + if (dep_unavailable) { + fprintf(stderr, "[WARN] Plugin '%s' skipped: dependency unavailable\n", + plugin.name.c_str()); + failed_names.insert(plugin.name); + failed_count++; + continue; + } + if (plugin.info->on_init) { int result = plugin.info->on_init(host_api); if (result != 0) { - return -1; + fprintf(stderr, "[ERROR] Plugin '%s' init failed (code %d)\n", + plugin.name.c_str(), result); + failed_names.insert(plugin.name); + failed_count++; + continue; // 不设置 initialized=true } } plugin.initialized = true; } - return 0; + return failed_count; + } catch (const std::runtime_error&) { + // 循环依赖 + return -1; } catch (const std::exception&) { return -1; } @@ -272,13 +303,24 @@ void PluginLoader::shutdown_all() if (it == plugins_.end()) continue; PluginInfo& plugin = it->second; - if (!plugin.initialized) continue; - - if (plugin.info->on_shutdown) { + if (plugin.initialized && plugin.info->on_shutdown) { plugin.info->on_shutdown(); } plugin.initialized = false; } + + // 释放所有 DLL 句柄 + for (auto& [id, plugin] : plugins_) { + if (plugin.handle) { +#ifdef _WIN32 + FreeLibrary((HMODULE)plugin.handle); +#else + dlclose(plugin.handle); +#endif + plugin.handle = nullptr; + } + } + plugins_.clear(); } const PluginInfo* PluginLoader::get_plugin(int plugin_id) const diff --git a/dstalk-gui/CMakeLists.txt b/dstalk-gui/CMakeLists.txt index d1a7566..fc5b88d 100644 --- a/dstalk-gui/CMakeLists.txt +++ b/dstalk-gui/CMakeLists.txt @@ -14,9 +14,3 @@ target_link_libraries(dstalk-gui dstalk SDL3::SDL3 ) - -add_custom_command(TARGET dstalk-gui POST_BUILD - COMMAND ${CMAKE_COMMAND} -E copy_if_different - $ - $ -) diff --git a/plugins/anthropic/CMakeLists.txt b/plugins/anthropic/CMakeLists.txt index cf3d7b5..d02d5c7 100644 --- a/plugins/anthropic/CMakeLists.txt +++ b/plugins/anthropic/CMakeLists.txt @@ -9,21 +9,11 @@ add_library(plugin-anthropic SHARED src/anthropic_plugin.cpp ) -target_include_directories(plugin-anthropic PRIVATE - ${CMAKE_SOURCE_DIR}/dstalk-core/include -) - target_link_libraries(plugin-anthropic PRIVATE dstalk) # Boost.JSON 用于构建/解析请求和响应 find_package(Boost REQUIRED CONFIG) -target_link_libraries(plugin-anthropic PRIVATE boost::boost) - -target_compile_definitions(plugin-anthropic PRIVATE - BOOST_ALL_NO_LIB - BOOST_ERROR_CODE_HEADER_ONLY - BOOST_JSON_HEADER_ONLY -) +target_link_libraries(plugin-anthropic PRIVATE boost::boost dstalk_boost_config) set_target_properties(plugin-anthropic PROPERTIES PREFIX "" diff --git a/plugins/anthropic/src/anthropic_plugin.cpp b/plugins/anthropic/src/anthropic_plugin.cpp index a222508..e576677 100644 --- a/plugins/anthropic/src/anthropic_plugin.cpp +++ b/plugins/anthropic/src/anthropic_plugin.cpp @@ -2,6 +2,7 @@ #include "dstalk/dstalk_services.h" #include +#include #include #include @@ -27,6 +28,14 @@ struct PluginConfig { }; static PluginConfig g_cfg; +// ============================================================================ +// 安全擦除：用 volatile 写零循环防止编译器优化 +// ============================================================================ +static void secure_zero(void* p, size_t n) { + volatile char* vp = (volatile char*)p; + while (n--) *vp++ = 0; +} + // ============================================================================ // 辅助：提取 host / target // ============================================================================ @@ -461,6 +470,8 @@ static int on_init(const dstalk_host_api_t* host) static void on_shutdown() { if (g_host) g_host->log(DSTALK_LOG_INFO, "[anthropic] shutdown"); + secure_zero(g_cfg.api_key.data(), g_cfg.api_key.size()); + g_cfg.api_key.clear(); g_http = nullptr; g_config = nullptr; g_host = nullptr; diff --git a/plugins/config/CMakeLists.txt b/plugins/config/CMakeLists.txt index ddf16a3..ee4d0c5 100644 --- a/plugins/config/CMakeLists.txt +++ b/plugins/config/CMakeLists.txt @@ -1,9 +1,5 @@ add_library(plugin-config SHARED src/config_plugin.cpp) -target_include_directories(plugin-config PRIVATE - ${CMAKE_SOURCE_DIR}/dstalk-core/include -) - target_link_libraries(plugin-config PRIVATE dstalk) set_target_properties(plugin-config PROPERTIES diff --git a/plugins/context/CMakeLists.txt b/plugins/context/CMakeLists.txt index 06efd39..5029e9a 100644 --- a/plugins/context/CMakeLists.txt +++ b/plugins/context/CMakeLists.txt @@ -1,9 +1,5 @@ add_library(plugin-context SHARED src/context_plugin.cpp) -target_include_directories(plugin-context PRIVATE - ${CMAKE_SOURCE_DIR}/dstalk-core/include -) - target_link_libraries(plugin-context PRIVATE dstalk) set_target_properties(plugin-context PROPERTIES diff --git a/plugins/deepseek/CMakeLists.txt b/plugins/deepseek/CMakeLists.txt index 2c218dd..6be765a 100644 --- a/plugins/deepseek/CMakeLists.txt +++ b/plugins/deepseek/CMakeLists.txt @@ -9,21 +9,11 @@ add_library(plugin-deepseek SHARED src/deepseek_plugin.cpp ) -target_include_directories(plugin-deepseek PRIVATE - ${CMAKE_SOURCE_DIR}/dstalk-core/include -) - target_link_libraries(plugin-deepseek PRIVATE dstalk) # Boost.JSON 用于构建/解析请求和响应 find_package(Boost REQUIRED CONFIG) -target_link_libraries(plugin-deepseek PRIVATE boost::boost) - -target_compile_definitions(plugin-deepseek PRIVATE - BOOST_ALL_NO_LIB - BOOST_ERROR_CODE_HEADER_ONLY - BOOST_JSON_HEADER_ONLY -) +target_link_libraries(plugin-deepseek PRIVATE boost::boost dstalk_boost_config) set_target_properties(plugin-deepseek PROPERTIES PREFIX "" diff --git a/plugins/deepseek/src/deepseek_plugin.cpp b/plugins/deepseek/src/deepseek_plugin.cpp index 9f62aa2..69b4ee5 100644 --- a/plugins/deepseek/src/deepseek_plugin.cpp +++ b/plugins/deepseek/src/deepseek_plugin.cpp @@ -2,6 +2,7 @@ #include "dstalk/dstalk_services.h" #include +#include #include #include @@ -27,6 +28,14 @@ struct PluginConfig { }; static PluginConfig g_cfg; +// ============================================================================ +// 安全擦除：用 volatile 写零循环防止编译器优化 +// ============================================================================ +static void secure_zero(void* p, size_t n) { + volatile char* vp = (volatile char*)p; + while (n--) *vp++ = 0; +} + // ============================================================================ // 辅助：从 base_url 提取 host 和 target // ============================================================================ @@ -450,6 +459,8 @@ static int on_init(const dstalk_host_api_t* host) static void on_shutdown() { if (g_host) g_host->log(DSTALK_LOG_INFO, "[deepseek] shutdown"); + secure_zero(g_cfg.api_key.data(), g_cfg.api_key.size()); + g_cfg.api_key.clear(); g_http = nullptr; g_config = nullptr; g_host = nullptr; diff --git a/plugins/file-io/CMakeLists.txt b/plugins/file-io/CMakeLists.txt index aa70175..9e5223e 100644 --- a/plugins/file-io/CMakeLists.txt +++ b/plugins/file-io/CMakeLists.txt @@ -1,9 +1,5 @@ add_library(plugin-file-io SHARED src/file_io_plugin.cpp) -target_include_directories(plugin-file-io PRIVATE - ${CMAKE_SOURCE_DIR}/dstalk-core/include -) - target_link_libraries(plugin-file-io PRIVATE dstalk) set_target_properties(plugin-file-io PROPERTIES diff --git a/plugins/file-io/src/file_io_plugin.cpp b/plugins/file-io/src/file_io_plugin.cpp index 6c4af67..7d074c8 100644 --- a/plugins/file-io/src/file_io_plugin.cpp +++ b/plugins/file-io/src/file_io_plugin.cpp @@ -29,8 +29,8 @@ static int file_read(const char* path, char** content) { return -1; } - // Allocate buffer (+1 for null terminator) - char* buf = (char*)malloc((size_t)fsize + 1); + // Allocate buffer via host allocator (+1 for null terminator) + char* buf = (char*)g_host->alloc((size_t)fsize + 1); if (!buf) { fclose(fp); return -1; @@ -40,7 +40,7 @@ static int file_read(const char* path, char** content) { fclose(fp); if (read_bytes != (size_t)fsize) { - free(buf); + g_host->free(buf); return -1; } diff --git a/plugins/lsp/CMakeLists.txt b/plugins/lsp/CMakeLists.txt index 6095d68..b299fdd 100644 --- a/plugins/lsp/CMakeLists.txt +++ b/plugins/lsp/CMakeLists.txt @@ -9,21 +9,11 @@ add_library(plugin-lsp SHARED src/lsp_plugin.cpp ) -target_include_directories(plugin-lsp PRIVATE - ${CMAKE_SOURCE_DIR}/dstalk-core/include -) - target_link_libraries(plugin-lsp PRIVATE dstalk) # Boost.JSON 用于 JSON-RPC 消息构建/解析 find_package(Boost REQUIRED CONFIG) -target_link_libraries(plugin-lsp PRIVATE boost::boost) - -target_compile_definitions(plugin-lsp PRIVATE - BOOST_ALL_NO_LIB - BOOST_ERROR_CODE_HEADER_ONLY - BOOST_JSON_HEADER_ONLY -) +target_link_libraries(plugin-lsp PRIVATE boost::boost dstalk_boost_config) # POSIX 平台需要 pthread (用于 std::thread) if(NOT WIN32) diff --git a/plugins/lsp/src/lsp_plugin.cpp b/plugins/lsp/src/lsp_plugin.cpp index 1899135..5f0acba 100644 --- a/plugins/lsp/src/lsp_plugin.cpp +++ b/plugins/lsp/src/lsp_plugin.cpp @@ -9,6 +9,7 @@ #include "dstalk/dstalk_services.h" #include +#include #include #include @@ -417,18 +418,33 @@ static void handle_message(const std::string& body) { static void reader_loop() { while (g_lsp.running) { - std::string header_line; - if (!g_lsp.proc.read_line(header_line)) break; + int content_length = -1; + bool pipe_ok = true; - int content_length = parse_content_length(header_line); - if (content_length < 0) continue; - - // 跳过后续头直到空行 (\r\n 换行被视为非空行，只检查空行) - while (true) { + // 状态机式读取 header 块：循环 read_line 直到读到空行 + // LSP 3.17: header 块以空行(\r\n)结束，允许 Content-Type 等其他 header + while (pipe_ok) { std::string line; - if (!g_lsp.proc.read_line(line)) break; + if (!g_lsp.proc.read_line(line)) { + pipe_ok = false; + break; + } + + // header 块以空行结束 auto sv = trim(std::string_view(line)); if (sv.empty()) break; + + // 累积 Content-Length；遇到其他 header 不丢弃，继续读取下一行 + int len = parse_content_length(line); + if (len >= 0) content_length = len; + } + + if (!pipe_ok) break; + + // 空行前都没读到 Content-Length，协议错误——记日志并跳过这一帧 + if (content_length < 0) { + if (g_host) g_host->log(DSTALK_LOG_ERROR, "[lsp] Invalid LSP frame: missing Content-Length header"); + continue; } std::string body; @@ -446,7 +462,7 @@ static void reader_loop() { // LSP 服务 vtable 实现 (定义在 vtable 变量之前) // ============================================================================ -static int g_lsp_impl_stop(); +static void g_lsp_impl_stop(); static int g_lsp_impl_start(const char* server_cmd, const char* language) { if (!server_cmd || !server_cmd[0]) return -1; diff --git a/plugins/network/CMakeLists.txt b/plugins/network/CMakeLists.txt index a04a6ec..021a0d1 100644 --- a/plugins/network/CMakeLists.txt +++ b/plugins/network/CMakeLists.txt @@ -3,10 +3,6 @@ find_package(OpenSSL REQUIRED CONFIG) add_library(plugin-network SHARED src/network_plugin.cpp) -target_include_directories(plugin-network PRIVATE - ${CMAKE_SOURCE_DIR}/dstalk-core/include -) - target_link_libraries(plugin-network PRIVATE dstalk boost::boost diff --git a/plugins/session/CMakeLists.txt b/plugins/session/CMakeLists.txt index bc3eb70..3c68210 100644 --- a/plugins/session/CMakeLists.txt +++ b/plugins/session/CMakeLists.txt @@ -1,15 +1,9 @@ add_library(plugin-session SHARED src/session_plugin.cpp) -target_include_directories(plugin-session PRIVATE - ${CMAKE_SOURCE_DIR}/dstalk-core/include -) - target_link_libraries(plugin-session PRIVATE dstalk) find_package(Boost REQUIRED CONFIG) -target_link_libraries(plugin-session PRIVATE boost::boost) -target_compile_definitions(plugin-session PRIVATE - BOOST_ALL_NO_LIB BOOST_ERROR_CODE_HEADER_ONLY BOOST_JSON_HEADER_ONLY) +target_link_libraries(plugin-session PRIVATE boost::boost dstalk_boost_config) set_target_properties(plugin-session PROPERTIES PREFIX "" diff --git a/plugins/session/src/session_plugin.cpp b/plugins/session/src/session_plugin.cpp index 3f2e56a..72f0dcb 100644 --- a/plugins/session/src/session_plugin.cpp +++ b/plugins/session/src/session_plugin.cpp @@ -6,6 +6,7 @@ #include "dstalk/dstalk_services.h" #include +#include #include #include @@ -163,7 +164,7 @@ static int session_load(const char* path) { if (ret != 0 || !content) return -1; std::string data(content); - std::free(content); + g_host->free(content); std::vector parsed; size_t pos = 0; diff --git a/plugins/tools/CMakeLists.txt b/plugins/tools/CMakeLists.txt index e4f3d56..8d16bd5 100644 --- a/plugins/tools/CMakeLists.txt +++ b/plugins/tools/CMakeLists.txt @@ -1,15 +1,9 @@ add_library(plugin-tools SHARED src/tools_plugin.cpp) -target_include_directories(plugin-tools PRIVATE - ${CMAKE_SOURCE_DIR}/dstalk-core/include -) - target_link_libraries(plugin-tools PRIVATE dstalk) find_package(Boost REQUIRED CONFIG) -target_link_libraries(plugin-tools PRIVATE boost::boost) -target_compile_definitions(plugin-tools PRIVATE - BOOST_ALL_NO_LIB BOOST_ERROR_CODE_HEADER_ONLY BOOST_JSON_HEADER_ONLY) +target_link_libraries(plugin-tools PRIVATE boost::boost dstalk_boost_config) set_target_properties(plugin-tools PROPERTIES PREFIX "" diff --git a/plugins/tools/src/tools_plugin.cpp b/plugins/tools/src/tools_plugin.cpp index 2096526..5c9a080 100644 --- a/plugins/tools/src/tools_plugin.cpp +++ b/plugins/tools/src/tools_plugin.cpp @@ -6,6 +6,7 @@ #include "dstalk/dstalk_services.h" #include +#include #include #include @@ -55,7 +56,7 @@ static char* builtin_file_read(const char* args_json) { } std::string escaped_content = json::serialize(json::string(content)); - std::free(content); + g_host->free(content); std::string result = "{\"content\":" + escaped_content + "}"; return g_host->strdup(result.c_str()); @@ -100,6 +101,8 @@ static char* builtin_file_write(const char* args_json) { // Tools 服务 vtable 实现 // ============================================================ +static void tools_unregister_tool(const char* name); + static int tools_register_tool(const char* name, const char* desc, const char* params_schema, dstalk_tool_handler_fn handler) { diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index 2f1f9ad..286ba98 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -10,10 +10,27 @@ target_link_libraries(dstalk-smoke-test PRIVATE dstalk ) -add_custom_command(TARGET dstalk-smoke-test POST_BUILD - COMMAND ${CMAKE_COMMAND} -E copy_if_different - $ - $ +add_test(NAME dstalk-smoke-test COMMAND dstalk-smoke-test) + +# ============================================================ +# dstalk-host-api-test — host API 单元测试 +# ============================================================ + +add_executable(dstalk-host-api-test + host_api_test.cpp + ${CMAKE_SOURCE_DIR}/dstalk-core/src/service_registry.cpp ) -add_test(NAME dstalk-smoke-test COMMAND dstalk-smoke-test) +target_include_directories(dstalk-host-api-test + PRIVATE ${CMAKE_SOURCE_DIR}/dstalk-core/src +) + +target_compile_features(dstalk-host-api-test + PRIVATE cxx_std_17 +) + +target_link_libraries(dstalk-host-api-test + PRIVATE dstalk +) + +add_test(NAME dstalk-host-api-test COMMAND dstalk-host-api-test) diff --git a/tests/host_api_test.cpp b/tests/host_api_test.cpp new file mode 100644 index 0000000..e02307c --- /dev/null +++ b/tests/host_api_test.cpp @@ -0,0 +1,180 @@ +// ============================================================================ +// host_api_test.cpp — host API 单元测试 (独立于 smoke_test) +// ============================================================================ +// 测试: register_service / query_service / alloc / free / log / init / shutdown +// ============================================================================ + +#include +#include +#include +#include +#include +#include +#include +#include + +// 引入 ServiceRegistry 实现做纯单元测试 +#include "service_registry.hpp" + +#include "dstalk/dstalk_host.h" + +// ---- 轻量断言 ---- +static int g_failures = 0; +#define TCHECK(cond, msg) do { \ + if (cond) { \ + std::cout << "[OK] " << (msg) << "\n"; \ + } else { \ + std::cerr << "[FAIL] " << (msg) << "\n"; \ + g_failures++; \ + } \ +} while (0) + +// ---- 辅助: 创建临时配置文件 ---- +static std::string make_temp_config(const std::string& tag) { + auto dir = std::filesystem::temp_directory_path() / ("dstalk-host-api-" + tag); + std::filesystem::create_directories(dir); + auto config_path = dir / "config.toml"; + { + std::ofstream c(config_path); + // 指向不存在的插件目录，避免加载任何 .dll + c << "plugin_dir = \"__no_such_plugins_dir__\"\n"; + } + return config_path.string(); +} + +// ============================================================ +int main() +{ + std::cout << "=== dstalk host_api unit tests ===\n\n"; + + // ==================================================================== + // Test 1: register_service 重复注册 同名+同版本 → 应返回 -2 + // ==================================================================== + { + dstalk::ServiceRegistry reg; + void* dummy_vtable = reinterpret_cast(0x1); + int r1 = reg.register_service("echo", 1, dummy_vtable); + TCHECK(r1 == 0, "register_service(\"echo\",1) first call returns 0"); + + int r2 = reg.register_service("echo", 1, dummy_vtable); + TCHECK(r2 == -2, + "register_service(\"echo\",1) duplicate same-version returns -2"); + } + + // ==================================================================== + // Test 2: register_service 同名+不同版本 → 应返回 -2 + // 名称已占用，与版本无关 + // ==================================================================== + { + dstalk::ServiceRegistry reg; + void* dummy_vtable = reinterpret_cast(0x1); + int r1 = reg.register_service("calc", 1, dummy_vtable); + TCHECK(r1 == 0, "register_service(\"calc\",1) first call returns 0"); + + int r2 = reg.register_service("calc", 99, dummy_vtable); + TCHECK(r2 == -2, + "register_service(\"calc\",99) diff-version duplicate returns -2"); + } + + // ==================================================================== + // Test 3: query_service 不存在的 name → nullptr + // ==================================================================== + { + dstalk::ServiceRegistry reg; + void* q = reg.query_service("ghost_service", 1); + TCHECK(q == nullptr, "query_service(\"ghost_service\",1) returns nullptr"); + } + + // ==================================================================== + // Test 4: query_service 错误版本号 → nullptr + // 注册 v=1, 查询 min_version=2 → 不满足 → nullptr + // ==================================================================== + { + dstalk::ServiceRegistry reg; + void* dummy_vtable = reinterpret_cast(0x2); + reg.register_service("solo", 1, dummy_vtable); + + void* q = reg.query_service("solo", 2); + TCHECK(q == nullptr, "query_service(\"solo\",2) with only v1 available returns nullptr"); + + // 确证以正确版本查询能拿到 + void* q2 = reg.query_service("solo", 1); + TCHECK(q2 == dummy_vtable, "query_service(\"solo\",1) with v1 available returns vtable"); + } + + // ==================================================================== + // Test 5: dstalk_init 多次调用 → 第二次应返回 -1 (幂等拒绝) + // ==================================================================== + { + std::string cfg = make_temp_config("init-twice"); + int r1 = dstalk_init(cfg.c_str()); + TCHECK(r1 == 0, "dstalk_init first call returns 0"); + + int r2 = dstalk_init(cfg.c_str()); + TCHECK(r2 == -1, "dstalk_init second call returns -1 (idempotent guard)"); + + dstalk_shutdown(); + } + + // ==================================================================== + // Test 6: alloc(0) / free(nullptr) 行为 + // malloc(0) 可返回 null 或合法指针; 两者都可 free + // free(nullptr) 是安全空操作 + // ==================================================================== + { + void* p = dstalk_alloc(0); + std::cout << "[OK] dstalk_alloc(0) returned " << p + << " (null or valid, both acceptable)\n"; + dstalk_free(p); + std::cout << "[OK] dstalk_free(alloc(0)) did not crash\n"; + + dstalk_free(nullptr); + std::cout << "[OK] dstalk_free(nullptr) did not crash\n"; + } + + // ==================================================================== + // Test 7: log 各 level 不崩溃 (DEBUG / INFO / WARN / ERROR) + // ==================================================================== + { + dstalk_log(DSTALK_LOG_DEBUG, "host_api_test: debug level message"); + std::cout << "[OK] dstalk_log(DEBUG) no crash\n"; + + dstalk_log(DSTALK_LOG_INFO, "host_api_test: info level message"); + std::cout << "[OK] dstalk_log(INFO) no crash\n"; + + dstalk_log(DSTALK_LOG_WARN, "host_api_test: warn level message"); + std::cout << "[OK] dstalk_log(WARN) no crash\n"; + + dstalk_log(DSTALK_LOG_ERROR, "host_api_test: error level message"); + std::cout << "[OK] dstalk_log(ERROR) no crash\n"; + + // 带格式参数 + dstalk_log(DSTALK_LOG_INFO, "formatted: %s %d", "answer", 42); + std::cout << "[OK] dstalk_log with format args no crash\n"; + } + + // ==================================================================== + // Test 8: dstalk_shutdown 后 query_service → nullptr + // g_service_registry 已被 delete 置空 + // ==================================================================== + { + std::string cfg = make_temp_config("after-shutdown"); + dstalk_init(cfg.c_str()); + dstalk_shutdown(); + + void* q = dstalk_service_query("any_service", 1); + TCHECK(q == nullptr, "dstalk_service_query after shutdown returns nullptr"); + } + + // ==================================================================== + // 结果 + // ==================================================================== + std::cout << "\n"; + if (g_failures == 0) { + std::cout << "=== All host_api tests passed ===\n"; + return 0; + } else { + std::cerr << "=== " << g_failures << " host_api test(s) FAILED ===\n"; + return 1; + } +} diff --git a/tests/smoke_test.cpp b/tests/smoke_test.cpp index 1ae1f65..ef33b11 100644 --- a/tests/smoke_test.cpp +++ b/tests/smoke_test.cpp @@ -68,7 +68,7 @@ int main() char* content = nullptr; if (file_io->read(file_path.string().c_str(), &content) == 0 && content) { bool ok = std::strcmp(content, sample_content) == 0; - std::free(content); + dstalk_free(content); if (ok) { std::cout << "[OK] file_io->read content matches\n"; } else { @@ -123,7 +123,7 @@ int main() char* saved = nullptr; if (file_io->read(saved_path.string().c_str(), &saved) == 0 && saved) { bool session_ok = std::strcmp(saved, session_content) == 0; - std::free(saved); + dstalk_free(saved); if (session_ok) { std::cout << "[OK] session content matches after save/load\n"; } else { @@ -331,7 +331,7 @@ int main() << " expected length: " << std::strlen(escape_content) << "\n" << " got length: " << std::strlen(read_back) << "\n"; } - std::free(read_back); + dstalk_free(read_back); } else { std::cerr << "[FAIL] escape content read-back failed\n"; }