# https://github.com/ionclaw-org/ionclaw 项目说明书

生成时间：2026-07-27 23:52:16 UTC

## 目录

- [IonClaw 概述与系统架构](#page-overview)
- [AI Provider、MCP 与 llama.cpp 集成](#page-providers)
- [跨平台原生应用（Android / iOS / tvOS / watchOS / Flutter）](#page-platforms)
- [Web 控制面板、技能系统与内置工具](#page-web-skills)

<a id='page-overview'></a>

## IonClaw 概述与系统架构

### 相关页面

相关主题：[AI Provider、MCP 与 llama.cpp 集成](#page-providers), [跨平台原生应用（Android / iOS / tvOS / watchOS / Flutter）](#page-platforms), [Web 控制面板、技能系统与内置工具](#page-web-skills)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/ionclaw-org/ionclaw/blob/main/README.md)
- [CLAUDE.md](https://github.com/ionclaw-org/ionclaw/blob/main/CLAUDE.md)
- [CMakeLists.txt](https://github.com/ionclaw-org/ionclaw/blob/main/CMakeLists.txt)
- [main/CMakeLists.txt](https://github.com/ionclaw-org/ionclaw/blob/main/main/CMakeLists.txt)
- [main/lib/include/ionclaw/Version.hpp](https://github.com/ionclaw-org/ionclaw/blob/main/main/lib/include/ionclaw/Version.hpp)
- [main/lib/include/ionclaw/ionclaw.h](https://github.com/ionclaw-org/ionclaw/blob/main/main/lib/include/ionclaw/ionclaw.h)
</details>

# IonClaw 概述与系统架构

IonClaw 是一个面向本地与嵌入式场景的 C++ AI Agent 运行时框架，提供模型推理、智能体调度、协议网关与 Web 管理界面等能力。截至最新发布版本 v1.0.5，项目已具备 llama.cpp 推理后端、MCP（Model Context Protocol）服务端与客户端、Smart Agent 子智能体（subagent）等核心特性。资料来源：[README.md:1-40]()

## 项目定位与核心能力

IonClaw 的目标是将"AI 模型推理 + Agent 编排 + 工具协议"打包成一个可独立部署、可交叉编译的二进制程序，主要面向需要离线或边缘部署 AI 能力的开发者。其核心能力包括：

- **本地推理**：集成 llama.cpp 作为默认 AI runtime，可在本地 CPU/GPU 上运行开源大语言模型。资料来源：[README.md:20-60]()
- **Agent 系统**：内置 Smart Agent 与 subagent 调度机制，支持多智能体协作与任务委派（v1.0.5 引入）。资料来源：[main/lib/include/ionclaw/ionclaw.h:1-40]()
- **MCP 协议**：同时支持 MCP Server 与 MCP Client，便于把 Agent 能力以标准化协议对外暴露或调用外部工具（v1.0.4 引入）。资料来源：[main/CMakeLists.txt:1-80]()
- **Web 管理界面**：自带嵌入式 Web 客户端（通过 `embed-resources.cmake` 将前端资源编译进二进制），方便浏览器端调试与控制。资料来源：[main/CMakeLists.txt:40-120]()
- **多语言支持**：运行时支持界面与提示词的多语言切换。资料来源：[README.md:60-90]()

## 仓库目录与构建结构

IonClaw 采用 CMake 作为顶层构建系统，顶层 `CMakeLists.txt` 负责跨模块的依赖组织与平台选项开关，而子目录 `main/` 则承载主进程、运行时库与嵌入式 Web 资源。资料来源：[CMakeLists.txt:1-60]()

构建产物的关键文件包括：

- `main/lib/include/ionclaw/Version.hpp`：集中维护版本号、构建信息与特性开关宏，是运行时判定能力的依据。资料来源：[main/lib/include/ionclaw/Version.hpp:1-30]()
- `main/lib/include/ionclaw/ionclaw.h`：公共 C/C++ 头文件，对外暴露运行时初始化、Agent 调度、MCP 注册等核心 API。资料来源：[main/lib/include/ionclaw/ionclaw.h:1-40]()
- `embedded_web.cpp`：由 `add_custom_command` 配合 `embed-resources.cmake` 生成的源码文件，把 Web 前端资源以 C++ 字节数组形式嵌入二进制。资料来源：[main/CMakeLists.txt:60-160]()

## 系统架构总览

下表总结了 IonClaw 的分层架构与各层职责，方便快速理解模块边界。

| 层级 | 主要组件 | 职责说明 |
|------|----------|----------|
| 表示层 | 嵌入式 Web 客户端（embedded_web.cpp） | 提供浏览器端 UI，通过 HTTP/WebSocket 与主进程通信 |
| 接口层 | MCP Server / MCP Client | 对外暴露 Agent 与工具能力，对内调用外部 MCP 服务 |
| 编排层 | Smart Agent、Subagent | 任务解析、计划生成、子智能体委派与上下文共享 |
| 运行时层 | llama.cpp 推理后端 | 本地 LLM 推理，支持 CPU 与 GPU 加速路径 |
| 基础设施层 | CMake 构建、Version.hpp、ionclaw.h | 版本特性开关、跨平台编译、公共 API 抽象 |

资料来源：[main/lib/include/ionclaw/ionclaw.h:1-40]() [main/lib/include/ionclaw/Version.hpp:1-30]() [main/CMakeLists.txt:1-160]()

## 关键工作流

以一次"用户通过 Web 发起任务"的典型调用为例，IonClaw 内部的协作流程可以概括为：

1. **请求接入**：嵌入式 Web 客户端通过本地 HTTP/WebSocket 将用户输入发送至主进程。资料来源：[main/CMakeLists.txt:60-160]()
2. **Agent 路由**：主进程根据当前会话上下文选择 Smart Agent，必要时创建 subagent 处理子任务。资料来源：[main/lib/include/ionclaw/ionclaw.h:1-40]()
3. **工具调用**：Agent 通过 MCP Client 调用已注册的外部工具，或通过 MCP Server 把自身能力暴露出去。资料来源：[README.md:40-90]()
4. **模型推理**：将整理后的 prompt 送入 llama.cpp runtime，获得模型输出。资料来源：[README.md:20-60]()
5. **结果回传**：推理结果与工具调用结果由 Smart Agent 聚合后回写到 Web 客户端。资料来源：[main/lib/include/ionclaw/ionclaw.h:1-40]()

## 构建与部署注意事项

由于 IonClaw 将 Web 前端以源码形式嵌入二进制，构建系统对 `embed-resources.cmake` 的依赖较为敏感：

- 若在 Windows MSVC 环境下出现 `fatal error C1083: Cannot open source file: "embedded_web.cpp"`，通常是 `add_custom_command` 未在依赖检查阶段触发资源生成所致，需清理 `build/` 后重新执行 CMake 配置。资料来源：[main/CMakeLists.txt:60-160]()
- 启用 llama.cpp 时应确认 CMake 顶层选项（如 `IONCLAW_WITH_LLAMACPP`）已开启，并链接对应的推理后端库。资料来源：[CMakeLists.txt:1-60]()
- MCP Server/Client 默认开关与具体协议版本应通过 `Version.hpp` 中的特性宏进行判定，避免硬编码。资料来源：[main/lib/include/ionclaw/Version.hpp:1-30]()

## 社区关注点速览

- **构建问题**：Issue #28 报告了 `embedded_web.cpp not generated` 的 MSVC 构建失败，是当前最受关注的可复现性问题。资料来源：[README.md:60-90]()
- **生态扩展**：v1.0.4 起原生支持 MCP Server/Client，v1.0.5 进一步引入 Smart Agent subagent，使项目具备更完整的多 Agent 编排能力。资料来源：[README.md:1-60]()
- **多语言**：通过运行时切换降低非英语用户的使用门槛。资料来源：[README.md:60-90]()

---

<a id='page-providers'></a>

## AI Provider、MCP 与 llama.cpp 集成

### 相关页面

相关主题：[IonClaw 概述与系统架构](#page-overview), [Web 控制面板、技能系统与内置工具](#page-web-skills)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [main/lib/include/ionclaw/provider/ProviderFactory.hpp](https://github.com/ionclaw-org/ionclaw/blob/main/main/lib/include/ionclaw/provider/ProviderFactory.hpp)
- [main/lib/include/ionclaw/provider/AnthropicProvider.hpp](https://github.com/ionclaw-org/ionclaw/blob/main/main/lib/include/ionclaw/provider/AnthropicProvider.hpp)
- [main/lib/include/ionclaw/provider/OpenAiProvider.hpp](https://github.com/ionclaw-org/ionclaw/blob/main/main/lib/include/ionclaw/provider/OpenAiProvider.hpp)
- [main/lib/include/ionclaw/provider/ClaudeCliProvider.hpp](https://github.com/ionclaw-org/ionclaw/blob/main/main/lib/include/ionclaw/provider/ClaudeCliProvider.hpp)
- [main/lib/include/ionclaw/provider/LlamaProvider.hpp](https://github.com/ionclaw-org/ionclaw/blob/main/main/lib/include/ionclaw/provider/LlamaProvider.hpp)
- [main/lib/include/ionclaw/provider/LlamaBackend.hpp](https://github.com/ionclaw-org/ionclaw/blob/main/main/lib/include/ionclaw/provider/LlamaBackend.hpp)
- [main/lib/include/ionclaw/mcp/McpClient.hpp](https://github.com/ionclaw-org/ionclaw/blob/main/main/lib/include/ionclaw/mcp/McpClient.hpp)
- [main/lib/include/ionclaw/mcp/McpServer.hpp](https://github.com/ionclaw-org/ionclaw/blob/main/main/lib/include/ionclaw/mcp/McpServer.hpp)
</details>

# AI Provider、MCP 与 llama.cpp 集成

## 概述与设计目标

ionclaw 的 AI 能力由三层可插拔组件构成：**Provider 抽象层**统一封装云端与本地推理后端；**MCP 客户端/服务器**桥接外部工具与上下文源；**llama.cpp** 作为本地推理运行时被原生集成进 Provider 体系。设计目标是让上层 Agent（如 v1.0.5 引入的 smart agent / subagent）无需关心后端差异，统一通过 `ProviderFactory` 选择 Anthropic、OpenAI、Claude CLI 或本地 llama.cpp 推理路径，并通过 MCP 协议接入工具。

资料来源：[main/lib/include/ionclaw/provider/ProviderFactory.hpp:1-40]()

## AI Provider 架构

### ProviderFactory 抽象入口

`ProviderFactory` 作为运行时工厂，根据配置或运行时参数返回对应 Provider 实现。它屏蔽了云端 HTTP、CLI 子进程与本地推理三种交互模式的差异，使调用方只面向统一接口。

资料来源：[main/lib/include/ionclaw/provider/ProviderFactory.hpp:40-120]()

### 云端 Provider：Anthropic / OpenAI

`AnthropicProvider` 与 `OpenAiProvider` 均实现统一的 Provider 接口，分别对接 Anthropic Messages API 与 OpenAI Chat Completions API，封装鉴权、流式响应与消息格式转换，二者保持请求/响应契约一致以便上层复用。

资料来源：
- [main/lib/include/ionclaw/provider/AnthropicProvider.hpp:1-80]()
- [main/lib/include/ionclaw/provider/OpenAiProvider.hpp:1-80]()

### CLI Provider：ClaudeCliProvider

`ClaudeCliProvider` 通过本地子进程方式调用 Claude CLI，适用于无法直接联网或需要复用已登录 CLI 会话的场景。它在 Provider 抽象下保留与 HTTP provider 相同的请求/响应契约，避免上层做适配分支。

资料来源：[main/lib/include/ionclaw/provider/ClaudeCliProvider.hpp:1-90]()

### 本地推理：LlamaProvider 与 LlamaBackend

`LlamaProvider` 是面向 llama.cpp 推理引擎的 Provider 实现。它通过内部 `LlamaBackend` 完成模型加载、token 化与推理循环，向上层暴露与云端 Provider 兼容的接口，从而实现“本地模型即服务”。社区 Issue #18 已确认 llama.cpp runtime 在 main 分支上得到支持（state=closed）。

资料来源：
- [main/lib/include/ionclaw/provider/LlamaProvider.hpp:1-120]()
- [main/lib/include/ionclaw/provider/LlamaBackend.hpp:1-120]()

## MCP 集成

MCP（Model Context Protocol）允许 ionclaw 既作为客户端消费外部工具与数据源，也能作为服务器向其他 Agent 暴露能力。`McpClient` 负责建立与远程 MCP server 的连接、发现可用 tools/resources 并在对话中注入工具调用结果；`McpServer` 则把 ionclaw 内部能力（如同源 MCP 工具、Provider 调用）暴露为 MCP 协议端点。该双向能力由 v1.0.4 的 PR #4（MCP server）与 PR #5（MCP client）引入。

资料来源：
- [main/lib/include/ionclaw/mcp/McpClient.hpp:1-100]()
- [main/lib/include/ionclaw/mcp/McpServer.hpp:1-100]()

## 端到端调用流程

| 阶段 | 组件 | 行为 |
|------|------|------|
| 入口 | Agent / subagent | 接收用户 prompt，决定是否需要工具 |
| Provider 选择 | ProviderFactory | 按配置选择 Anthropic/OpenAI/ClaudeCli/Llama Provider |
| 推理 | LlamaBackend 或 HTTP/CLI 后端 | 生成本轮回复或工具调用决策 |
| 工具 | McpClient | 调用外部 MCP server tool 并把结果回填上下文 |
| 输出 | Agent | 汇总并返回最终消息 |

资料来源：[main/lib/include/ionclaw/provider/ProviderFactory.hpp:40-120]()、[main/lib/include/ionclaw/mcp/McpClient.hpp:1-100]()

## 已知限制与社区反馈

- llama.cpp 后端依赖构建期正确链接 `llama` 库；若 CMake 未正确传递相关开关（例如 Issue #28 中提到的 `add_custom_command` / `embed-resources.cmake` 依赖链路缺失），可能导致本地 Provider 或嵌入资源不可用，问题模式与该 issue 报告的 `embedded_web.cpp not generated` 类似，属于构建依赖未满足。
- 当前公开头文件未披露针对 `LlamaProvider` 的官方速率限制或基准数据；接入前应在本地进行小批量对话验证，再决定是否替换默认云端 Provider。

资料来源：[main/lib/include/ionclaw/provider/LlamaProvider.hpp:1-120]()、[main/lib/include/ionclaw/provider/LlamaBackend.hpp:1-120]()、[main/lib/include/ionclaw/provider/ProviderFactory.hpp:40-120]()

---

<a id='page-platforms'></a>

## 跨平台原生应用（Android / iOS / tvOS / watchOS / Flutter）

### 相关页面

相关主题：[IonClaw 概述与系统架构](#page-overview), [Web 控制面板、技能系统与内置工具](#page-web-skills)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [apps/android/app/src/main/java/com/ionclaw/app/MainActivity.kt](https://github.com/ionclaw-org/ionclaw/blob/main/apps/android/app/src/main/java/com/ionclaw/app/MainActivity.kt)
- [apps/android/app/src/main/java/com/ionclaw/app/ui/PanelScreen.kt](https://github.com/ionclaw-org/ionclaw/blob/main/apps/android/app/src/main/java/com/ionclaw/app/ui/PanelScreen.kt)
- [apps/android/app/src/main/java/com/ionclaw/app/ui/ServerScreen.kt](https://github.com/ionclaw-org/ionclaw/blob/main/apps/android/app/src/main/java/com/ionclaw/app/ui/ServerScreen.kt)
- [apps/android/app/src/main/java/com/ionclaw/app/server/ServerViewModel.kt](https://github.com/ionclaw-org/ionclaw/blob/main/apps/android/app/src/main/java/com/ionclaw/app/server/ServerViewModel.kt)
- [apps/android/library/src/main/cpp/ionclaw_jni.cpp](https://github.com/ionclaw-org/ionclaw/blob/main/apps/android/library/src/main/cpp/ionclaw_jni.cpp)
- [apps/android/library/src/main/java/com/ionclaw/lib/IonClawNative.kt](https://github.com/ionclaw-org/ionclaw/blob/main/apps/android/library/src/main/java/com/ionclaw/lib/IonClawNative.kt)
</details>

# 跨平台原生应用（Android / iOS / tvOS / watchOS / Flutter）

## 概述与作用范围

ionclaw 的跨平台原生应用层是面向 Android、iOS、tvOS、watchOS 与 Flutter 的"原生壳"（native shell），其目标是把同一份 C++ 核心运行时——包含本地推理、MCP server/client（v1.0.4 起支持）以及 llama.cpp AI runtime（参见 issue #18，已合入主干）——直接嵌入到各平台进程内，避免依赖外部服务。该壳层与 Web 客户端共用一套构建机制；后者在打包时通过 `embed-resources.cmake` 生成 `embedded_web.cpp`，社区曾报告该文件缺失，见 issue #28。

本页以 Android 子工程作为唯一具备源码证据的实现进行说明；其他平台按相同分层组织，但本仓库中未检索到对应源码细节。

## 总体项目布局

`apps/` 目录按平台分子工程。Android 端进一步拆分为两个 Gradle 模块，以隔离 UI 与原生绑定：

| 模块 | 路径 | 角色 |
|---|---|---|
| `:app` | `apps/android/app/src/main/java/com/ionclaw/app/` | 应用入口、UI 屏幕、ViewModel |
| `:library` | `apps/android/library/` | JNI 桥接、C++ 原生库、Kotlin 封装 |

`app` 与 `library` 的拆分使 C++ 运行时可独立编译为原生库，并由未来其他壳工程（Flutter 插件、车载/TV 壳）复用，从而保持核心代码单一来源。

## Android 客户端实现

### 应用入口与 UI 屏幕

`MainActivity.kt` 是 Android 应用入口 Activity，承载整个 UI 树。UI 按职责分为两个屏幕文件：

- `PanelScreen.kt`：智能体交互面板，负责呈现主对话、工具调用结果以及 v1.0.5 引入的 smart agent subagent 视图。
- `ServerScreen.kt`：本地服务器配置与状态界面，展示启动/停止、监听信息等。

资料来源：[apps/android/app/src/main/java/com/ionclaw/app/MainActivity.kt:1-1]()、[apps/android/app/src/main/java/com/ionclaw/app/ui/PanelScreen.kt:1-1]()、[apps/android/app/src/main/java/com/ionclaw/app/ui/ServerScreen.kt:1-1]()。

### ViewModel 与本地服务器管理

`ServerViewModel.kt` 位于 `server` 子包内，作为服务器生命周期的持有者，把原生层回调的状态以可观察形式发布给上述两个屏幕。这种"屏幕—ViewModel—原生层"的三段式划分，使得 UI 不必直接持有 JNI 引用，降低原生对象在 Android 配置变更（旋转、进程回收等）下被误释放的风险。

资料来源：[apps/android/app/src/main/java/com/ionclaw/app/server/ServerViewModel.kt:1-1]()。

### 原生 C++ 集成（library 模块）

`:library` 模块同时包含 Kotlin 封装与 C++ 实现，二者一一对应：

- `IonClawNative.kt`：Kotlin 侧面向应用的 API，方法签名与 C++ 入口对应。
- `ionclaw_jni.cpp`：C++ 侧 JNI 桥接实现，把 Kotlin 调用桥接到 ionclaw 核心运行时。

通过这一对文件，应用进程可直接调用推理、MCP 客户端/服务器（v1.0.4）、子代理（v1.0.5）等能力，无需 IPC。

资料来源：[apps/android/library/src/main/cpp/ionclaw_jni.cpp:1-1]()、[apps/android/library/src/main/java/com/ionclaw/lib/IonClawNative.kt:1-1]()。

## 其他平台范围

虽然仓库中未列出 iOS / tvOS / watchOS / Flutter 对应的源码文件，但从 `apps/` 目录命名与 Android 参考实现的分层可推断预期形态：

- **iOS / tvOS / watchOS**：以 Xcode 工程链接同一份 C++ 核心，UI 壳分别为 UIKit/SwiftUI、tvOS 焦点模型与 watchOS 紧凑布局；语言桥接以 Objective-C++ 或 Swift C-interop 替代 `IonClawNative.kt`。
- **Flutter**：以 Dart FFI 或 Method Channel 复用 `libionclaw`，在 Android/iOS 上共享 Dart 层 UI，从而减少壳工程的重复实现。

若要在这些平台启用，需在各自工程中引用同一 C++ 核心并补齐对应桥接文件。

## 小结

跨平台原生应用层是 ionclaw 把 C++ 核心（推理、MCP、llama.cpp runtime——参见 issue #18）投递到不同设备形态的"薄壳"。Android 是当前源码证据最完整的参考实现：`MainActivity` 启动 → 两个 UI 屏幕（`PanelScreen` / `ServerScreen`）→ `ServerViewModel` 协调 → `IonClawNative` Kotlin 封装 → `ionclaw_jni.cpp` 桥接 → ionclaw 核心运行时。其他平台遵循相同分层，仅替换 UI 壳与语言桥接。构建侧请同时关注 `embed-resources.cmake` 与 issue #28 中的 `embedded_web.cpp not generated` 排查要点。

---

<a id='page-web-skills'></a>

## Web 控制面板、技能系统与内置工具

### 相关页面

相关主题：[IonClaw 概述与系统架构](#page-overview), [AI Provider、MCP 与 llama.cpp 集成](#page-providers)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [apps/web/src/main.js](https://github.com/ionclaw-org/ionclaw/blob/main/apps/web/src/main.js)
- [apps/web/src/App.vue](https://github.com/ionclaw-org/ionclaw/blob/main/apps/web/src/App.vue)
- [apps/web/src/router/index.js](https://github.com/ionclaw-org/ionclaw/blob/main/apps/web/src/router/index.js)
- [apps/web/src/pages/ChatPage.vue](https://github.com/ionclaw-org/ionclaw/blob/main/apps/web/src/pages/ChatPage.vue)
- [apps/web/src/pages/TaskBoard.vue](https://github.com/ionclaw-org/ionclaw/blob/main/apps/web/src/pages/TaskBoard.vue)
- [apps/web/src/pages/FilesPage.vue](https://github.com/ionclaw-org/ionclaw/blob/main/apps/web/src/pages/FilesPage.vue)
- [apps/web/CMakeLists.txt](https://github.com/ionclaw-org/ionclaw/blob/main/apps/web/CMakeLists.txt)
- [cmake/embed-resources.cmake](https://github.com/ionclaw-org/ionclaw/blob/main/cmake/embed-resources.cmake)
</details>

# Web 控制面板、技能系统与内置工具

## 1. 总体定位与嵌入式架构

ionclaw 的用户交互由两部分组成：基于 C++ 的主进程（`main` 二进制）与内嵌的 Vue 3 单页应用（`apps/web`）。前端的静态资源在构建阶段被 `cmake/embed-resources.cmake` 转换为 C++ 源文件 `embedded_web.cpp`，再由主进程直接对外提供 HTTP 服务，从而实现"一个二进制、零外部依赖"的部署形态。前端入口 `apps/web/src/main.js` 创建 Vue 应用、注册 Pinia 状态库与 Vue Router，并挂载到 `#app` 节点；`App.vue` 作为根组件承载整体布局（侧边栏 + 路由出口 + 顶部状态栏）。

资料来源：[apps/web/src/main.js:1-40]()
资料来源：[apps/web/src/App.vue:1-120]()
资料来源：[apps/web/CMakeLists.txt:1-120]()
资料来源：[cmake/embed-resources.cmake:1-80]()

> 社区反馈：在 Windows 上有用户报告 `embedded_web.cpp not generated`（[issue #28](https://github.com/ionclaw-org/ionclaw/issues/28)），原因是 `add_custom_command` 对前端产物目录的依赖在某些配置下未触发；该问题凸显了前端产物必须先于主二进制生成并被链接的耦合顺序。

## 2. Web 控制面板的页面组成

路由表 `router/index.js` 定义了三条主要路由，对应控制面板的三个核心页面：

- `/chat` → `ChatPage.vue`：与 AI Agent 对话、查看流式回复与工具调用结果。
- `/tasks` → `TaskBoard.vue`：以看板形式展示 Agent 任务与子任务（subagent）状态。
- `/files` → `FilesPage.vue`：浏览、上传工作区文件，辅助 Agent 进行文件级操作。

`ChatPage.vue` 是最核心的交互页：通过 WebSocket/SSE 与主进程的 Agent 运行时通信，渲染用户消息、AI 回复、思考过程以及工具调用卡片。`TaskBoard.vue` 将 Agent 内部的子任务以看板列（待办 / 进行中 / 已完成）呈现，对应 v1.0.5 引入的"smart agent subagent"特性。`FilesPage.vue` 暴露工作区文件系统，让用户能上传、预览、引用文件供 Agent 使用。

资料来源：[apps/web/src/router/index.js:1-60]()
资料来源：[apps/web/src/pages/ChatPage.vue:1-200]()
资料来源：[apps/web/src/pages/TaskBoard.vue:1-200]()
资料来源：[apps/web/src/pages/FilesPage.vue:1-200]()

## 3. 技能系统（Skill System）

ionclaw 的"技能"由两个层面构成：

1. **MCP 兼容层** —— v1.0.4 起同时支持 MCP Server 与 MCP Client（[PR #4](https://github.com/ionclaw-org/ionclaw/pull/4)、[PR #5](https://github.com/ionclaw-org/ionclaw/pull/5)），允许第三方以标准协议注册工具，Agent 在推理时按需调用。
2. **Subagent 委派** —— v1.0.5 引入的"smart agent subagent"（[PR #14](https://github.com/ionclaw-org/ionclaw/pull/14)）让主 Agent 可以委派子 Agent 处理特定任务，技能在子任务上下文中继承与裁剪。

技能在前端通过 `TaskBoard.vue` 的任务卡片进行可视化：每张卡片显示技能名称、调用次数、当前状态与子任务进度；用户也可在 `ChatPage.vue` 的工具调用气泡中查看每一次技能执行的输入与输出。

资料来源：[apps/web/src/pages/TaskBoard.vue:1-200]()
资料来源：[apps/web/src/pages/ChatPage.vue:1-200]()

## 4. 内置工具与运行时

主进程内置了一组工具供 Agent 调用，覆盖文件读写、Shell 执行、检索等常见操作；运行时方面，llama.cpp 已被纳入主分支支持（[issue #18](https://github.com/ionclaw-org/ionclaw/issues/18)），用户可在配置中切换本地推理后端。下图展示了从浏览器到 AI 后端的整体数据流：

```mermaid
graph LR
  Browser[浏览器] -->|HTTP/WS| Main[主进程 main]
  Main -->|embed| Web[embedded_web.cpp]
  Main --> Agent[Agent Runtime]
  Agent -->|MCP| MCPServer[MCP Server]
  Agent -->|tools| Builtin[内置工具]
  Agent --> LLM[llama.cpp / 其他后端]
```

## 5. 构建与排错提示

由于前端被嵌入到 C++ 二进制，**必须**先构建 `apps/web` 产物再构建主项目。Windows 用户如遇到 `embedded_web.cpp` 缺失，可手动进入 `apps/web/` 执行 `npm run build`，随后再次运行 CMake 重新生成资源；也可检查 `IONCLAW_WEB_DIST_DIR` 变量是否被正确传入（[issue #28](https://github.com/ionclaw-org/ionclaw/issues/28)）。Linux/macOS 用户通常不会遇到此问题，因为前端产物会作为 CMake 的 `add_custom_command` 依赖被自动生成。

资料来源：[apps/web/CMakeLists.txt:1-120]()
资料来源：[cmake/embed-resources.cmake:1-80]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：ionclaw-org/ionclaw

摘要：发现 12 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：能力坑 - 能力证据存在缺口。

## 1. 能力坑 · 能力证据存在缺口

- 严重度：high
- 证据强度：source_linked
- 发现：Sandbox install result is missing.
- 对用户的影响：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。
- 证据：evidence.evidence_gaps | https://github.com/ionclaw-org/ionclaw | Sandbox install result is missing.

## 2. 安装坑 · 安装命令尚未沙箱验证

- 严重度：medium
- 证据强度：runtime_trace
- 发现：当前 install_status=documented，还只是文档/元数据线索。
- 对用户的影响：命令可能缺步骤、过期或依赖本地环境，不能直接作为用户承诺。
- 复现命令：`git clone https://github.com/ionclaw-org/ionclaw.git`
- 证据：downstream_validation.install_status | https://github.com/ionclaw-org/ionclaw | install_status=documented; command=git clone https://github.com/ionclaw-org/ionclaw.git

## 3. 安装坑 · 来源证据：embedded_web.cpp not generated

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：embedded_web.cpp not generated
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/ionclaw-org/ionclaw/issues/28 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/ionclaw-org/ionclaw | host_targets=openclaw, mcp_host, claude_code, claude, cursor, chatgpt

## 5. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/ionclaw-org/ionclaw | README/documentation is current enough for a first validation pass.

## 6. 运行坑 · Quick Start 尚未实际跑通

- 严重度：medium
- 证据强度：source_linked
- 发现：quickstart_status=not_attempted。
- 对用户的影响：用户只能看到安装线索，不能确信 10 分钟内能形成最小可试路径。
- 证据：downstream_validation.quickstart_status | https://github.com/ionclaw-org/ionclaw | quickstart_status=not_attempted; sandbox_quickstart_status=missing

## 7. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/ionclaw-org/ionclaw | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/ionclaw-org/ionclaw | no_demo; severity=medium

## 9. 安全/权限坑 · 存在安全注意事项

- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 证据：risks.safety_notes | https://github.com/ionclaw-org/ionclaw | No sandbox install has been executed yet; downstream must verify before user use.

## 10. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/ionclaw-org/ionclaw | no_demo; severity=medium

## 11. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/ionclaw-org/ionclaw | issue_or_pr_quality=unknown

## 12. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/ionclaw-org/ionclaw | release_recency=unknown

<!-- canonical_name: ionclaw-org/ionclaw; human_manual_source: deepwiki_human_wiki -->