LuBan.AIAgent 2026.10.9.1

English | 中文

LuBan.AIAgent

作者: yswenli | 联系邮箱: yswenli@outlook.com | 代码仓库: https://github.com/yswenli/luban-framework

基于 Microsoft Agent Framework 的 AI Agent 库，让大模型具备思考、规划、调用工具和自主执行的能力。

Related Projects: LuBan.Framework | LuBan.DI | LuBan.AIFlow | LuBan.Web.Core

为什么需要它？

• 想让 LLM 调用工具完成任务，但 MCP / Function Calling 的实现细节令人头疼？
• Skill 管理、工具注册、会话持久化各自需要单独实现，维护成本高？
• 模型 Provider 切换困难——从 Provider A 换到 Provider B 需要重写大量代码？
• 缺少中间件机制——日志、策略控制、权限拦截难以扩展？

LuBan.AIAgent 提供完整的 AI Agent 基础设施，从 Agent 运行时、多模型路由、技能系统、工具系统、会话存储到中间件管道——开箱即用。

快速预览

// 注册服务
services.AddSingleton<IChatClient>(sp => CreateChatClient());
services.AddLuBanAgent(configuration);

// 创建 Agent
var factory = serviceProvider.GetRequiredService<ILuBanAgentFactory>();
var agent = await factory.CreateAsync(
    systemPrompt: "你是一个浏览器自动化助手",
    toolGroups: new[] { "browser" });

// 执行任务
var response = await agent.RunAsync("打开百度并搜索 LuBan Framework");
Console.WriteLine(response.Text);

技术栈

安装

dotnet add package LuBan.AIAgent

安装 Playwright 浏览器（使用浏览器工具时需要）：

npx playwright@1.61.0 install chromium

功能总览

核心引擎

组件注册表架构

Skills、MCPs、Rules 采用统一的三级优先级注册表模式：

加载时机：

• 启动时：加载硬编码组件 + config.json 全局配置
• 工作区切换时：加载工作区文件，自动合并

工作区目录结构：

.luban-agent/
├── skills/          # 工作区级 Skill
│   └── my-skill/
│       └── SKILL.md
├── mcps/            # 工作区级 MCP 服务器
│   └── my-mcp.json
└── rules/           # 工作区级规则
    └── my-rule.json

工具系统

内置工具

脚本执行说明：Shell 工具会自动探测运行环境（Windows 优先 pwsh > powershell > cmd，类 Unix 优先 bash > sh），并按解释器自动适配参数风格与引用方式，执行结果中回传实际使用的 shell/shellPath/platform。Lua 工具基于内嵌 MoonSharp 软沙箱执行，无需外部 lua 解释器，沙箱不具备文件系统与系统命令能力，结果通过 print 输出。

LLM Wiki 知识库（opt-in）

wiki 是 opt-in 工具组：ToolGroups 为 null（表示全部）时不包含本组，只有在 ToolGroups 中显式点名 "wiki" 时才注入。

目录布局：

wiki/
├── SCHEMA.md        # 维护规范（承载 LLM 创作约定）
├── index.md         # 页面清单（由服务维护，勿手写）
├── log.md           # 变更日志（由服务维护，勿手写）
├── overview.md      # 总览
├── sources/         # 来源摘要，一源一页
├── entities/        # 实体
├── concepts/        # 概念
└── queries/         # 问答沉淀

frontmatter 约定：每个页面以 YAML frontmatter 开头，包含 title、type（source | entity | concept | overview | query）、tags、sources（相对工作区根的来源路径）、created、updated。

源格式支持：

表格单元格内的 | 会转义为 \|，换行转为 <br>，保证生成的 Markdown 表格不被破坏。

配置（LuBanAgent:Tools:Wiki）：Enabled（默认 true）、TopK（默认 8）、IncludeRawDefault（默认 false）、MaxResultChars（默认 8000）。

后台索引与工作区显式指定：

• IRetrievalService.IndexDirectoryAsync(path, glob, force, IProgress<IndexProgress>? progress, cancellationToken, workspaceId)：索引过程不再占用方法级写锁（写锁仅包裹存储写入），嵌入调用串行化（内部信号量），并通过 IndexProgress 上报 IndexStage.Scanning / Embedding / Deleting / Done，调用方可放到后台任务执行并展示进度。
• 检索与 wiki 的全部方法新增可选参数 string? workspaceId = null：显式指定目标工作区（由 IWikiContext.WorkspaceRootFor(workspaceId) 解析根目录），不传时沿用 IWikiContext.WorkspaceRoot。
• 语义搜索改为在全部候选（不再抽样）上计算余弦相似度，并以 Score 降序、ChunkId 升序排序，保证同分结果可复现。
• 破坏性变更：IVectorStore 的 8 个方法均新增 string? workspaceId = null，IRetrievalService.IndexDirectoryAsync 第 4 个参数由 force 之后的布尔/无变为 IProgress<IndexProgress>?。自定义实现者需同步签名（不传 workspaceId 时行为保持为默认工作区）。
• 索引文件白名单（行为变更）：ChunkerFactory.ShouldIndex 只按扩展名判断，白名单 = 各 ICodeChunker 已注册扩展名 + .txt/.csv/.tsv/.log/.properties/.xlsx；.xlsx 在读取时经 ExcelExtractor（MiniExcel）提取为 Markdown 后再切块/嵌入（提取结果为「## sheet 名 + markdown 表格」，按 sheet 分节切块，语言标识 excel）；无专用切块器的纯文本（.txt/.csv/.tsv/.log/.properties）走滑动窗口兜底。白名单之外的扩展名（.docx/.pdf/.ps1/.exe 等）与无扩展名文件一律不索引；单文件索引 IndexFileAsync 同样受白名单与大小上限约束。白名单内但内容含 NUL 字节或全空白的内容在读取阶段跳过。扫描阶段不再预读文件内容（二进制判断移到读取阶段），并剪枝排除目录（.git/bin/obj/node_modules/dist/packages/.vs/.idea/target）与重解析点，避免在云盘/网络目录上因文件水合与杀软扫描长时间卡顿。
• ChunkerFactory.EnumerateFiles(root, pattern) 为公开的逐层安全枚举（剪枝排除目录与重解析点、单层不可访问时跳过该层、跨 pattern 去重），索引、wiki 页面枚举（WikiService.EnumeratePages）与 CLI/桌面端预扫共用，保证各处统计口径一致。
• 表格提取上限与截断告警：ExcelExtractor.ExtractAsync(filePath, maxChars, cancellationToken) 可指定单文件字符上限；索引侧使用 ExcelExtractor.IndexingMaxChars（200 万字符，远宽于摄入侧的 TextExtractor.MaxChars = 20 万），超出时截断并写入 IndexReport.Warnings（不再静默丢数据）。提取在线程池执行，等待期间可响应取消。
• IndexDirectoryAsync 在枚举阶段即按目录上报 IndexStage.Scanning（IndexProgress.CurrentFile 为当前目录，Total 为已发现的可索引文件数），调用方无需额外预扫即可显示「正在扫描：<目录>（已发现 N 个）…」。

Skill 系统

内置 Skill

文件化 Skill

支持通过 SKILL.md 文件定义自定义 Skill，兼容 OpenCode 格式：

---
name: my-skill
description: "技能描述"
category: custom
---

# Skill 指令内容

这里是 Skill 的提示词模板...

存储位置（按优先级）：

• 项目级: <workspace>/.luban-agent/skills/<skill-id>/SKILL.md
• 用户级: %LocalAppData%/LuBan/AIAgent/skills/<skill-id>/SKILL.md

优先级：硬编码（DI）> 工作区文件 > config.json

Rule 系统

MCP 系统

会话系统

附件系统

规则拦截

安全与确认

多 Agent 编排系统

主 Agent 解析复合任务 → 拆解 DAG 任务图谱 → 分发 SubAgent 执行（串行 / 并行混合编排）。

使用指南

1. 配置与注册

{
  "LuBanAgent": {
    "DefaultModel": "openai:gpt-4o",
    "SystemPrompt": "你是一个智能助手。",
    "MaxToolLoopIterations": 10,
    "Session": {
      "CompactTargetMessages": 20,
      "CompactThreshold": 10
    }
  }
}

// 注册服务
services.AddSingleton<IAppConfigReader>(myConfigManager);
services.AddSingleton<IProviderRouter>(myProviderRouter);
services.AddLuBanAgent(configuration);

2. 多模型路由

// 使用 provider:model 格式路由到不同模型
// IProviderRouter 根据 ModelId 中的 provider 前缀自动分发
var agent = await factory.CreateAsync(modelName: "qwen:qwen-plus");

// 切换 Provider 只需更改前缀
var agent2 = await factory.CreateAsync(modelName: "openai:gpt-4o");

3. 工具注册与使用

// 创建 Agent 时指定工具组
var agent = await factory.CreateAsync(
    toolGroups: new[] { "browser", "filesystem" });

// Agent 自动选择并调用工具
var response = await agent.RunAsync("列出 src 目录下所有 .cs 文件并统计代码行数");

// 流式运行
await foreach (var update in agent.RunStreamingAsync("帮我分析这段代码"))
{
    Console.Write(update.Text);
}

4. Skill 管理

// 获取 Skill 注册表
var skillRegistry = serviceProvider.GetRequiredService<SkillRegistry>();

// 列出所有 Skill
var skills = skillRegistry.GetAll();

// 执行 Skill
var context = new SkillContext
{
    Agent = agent,
    UpdateStatus = status => Console.WriteLine($"状态: {status}")
};
var result = await skillRegistry.Get("brainstorming")
    .ExecuteAsync(context, "我想实现一个用户登录功能");

5. 自定义工具插件

public class MyToolPlugin : ILuBanToolPlugin
{
    public string GroupName => "my-tools";
    public string? Description => "自定义工具集";

    public IReadOnlyList<AIFunction> GetTools(IServiceProvider sp, ToolGroupOptions? toolsOptions = null)
    {
        // 返回自定义工具函数
        return new List<AIFunction> { /* ... */ };
    }

    public bool IsEnabled(LuBanAgentOptions options) => true;
}

// 注册
services.AddSingleton<ILuBanToolPlugin, MyToolPlugin>();

6. 自定义 Skill

方式一：文件化 Skill（推荐）

在项目级或用户级目录创建 SKILL.md 文件：

# 项目级目录
<workspace>/.luban-agent/skills/my-skill/SKILL.md

# 用户级目录
%LocalAppData%/LuBan/AIAgent/skills/my-skill/SKILL.md

SKILL.md 格式：

---
name: my-translator
description: "将文本翻译成英文"
category: custom
---

# 翻译助手

请将用户提供的内容翻译成英文。

## 要求
- 保持原文的语气和风格
- 使用地道的英文表达

方式二：代码定义 Skill

public class MyCustomSkill : SkillBase
{
    public override string Id => "my-custom-skill";
    public override string Name => "我的自定义 Skill";
    public override string Description => "自定义 Skill 示例";
    public override string Category => "custom";
    public override string? PromptTemplate => "自定义提示词模板...";

    public override async Task<SkillResult> ExecuteAsync(SkillContext context, string input)
    {
        UpdateStatus(context, "正在处理...");
        var result = await CallAgentAsync(context, input);
        return SkillResult.Ok(result ?? "");
    }
}

// 注册
services.AddSingleton<ISkill, MyCustomSkill>();

7. 自定义规则

public class MyRule : RuleBase
{
    public override string Id => "my-rule";
    public override string Name => "我的规则";
    public override int Priority => 50;

    public override bool IsApplicable(RuleContext context)
        => context.ActionType == "file-write";

    public override Task<RuleResult> ExecuteAsync(RuleContext context)
    {
        var path = context.Arguments.GetValueOrDefault("path")?.ToString();
        if (path?.Contains("secret") == true)
            return Task.FromResult(RuleResult.DenyResult("禁止访问包含 secret 的路径"));
        return Task.FromResult(RuleResult.AllowResult());
    }
}

// 注册
services.AddSingleton<IRule, MyRule>();

8. 外部插件加载

{
  "LuBanAgent": {
    "ExternalPlugins": ["MyCompany.AgentPlugins", "ThirdParty.Tools"]
  }
}

通过配置 ExternalPlugins 指定程序集名称，框架会自动扫描并注册其中实现了 ILuBanToolPlugin 的类型。

9. 多 Agent 任务编排

{
  "LuBanAgent": {
    "Orchestration": {
      "Enabled": true,
      "PlannerReasoningEffort": "none",
      "MaxNodes": 10,
      "MaxParallelism": 5,
      "DefaultNodeTimeoutSeconds": 0,
      "MaxReplanAttempts": 3,
      "ReflectionTimeoutSeconds": 0,
      "DefaultToolGroups": []
    }
  }
}

• Enabled：启用后向模型暴露两个编排工具——plan_task（由模型自行判定复合任务并生成任务图谱）与 run_orchestration（按 plan_task 返回的 graphId 执行）。是否编排完全交由模型决策，框架不再做启发式或自动判定。
• 规划固定使用 LLM 规划器；PlannerModel 为 null 时继承主模型，PlannerReasoningEffort 建议设为 none 以关闭推理模型的思考输出、显著缩短规划耗时。

SubAgent 角色系统：规划器可为每个节点指定角色（analyst/researcher/coder/writer），角色提供专业系统提示词和默认工具组。内置 4 个角色，支持通过工作区扩展自定义角色。

工作区编排扩展

进入 /agi 工作区时自动加载以下目录：

• .luban-agent/roles/*.json：自定义 SubAgent 角色，同名覆盖内置角色。格式：{ "name": "...", "systemPromptTemplate": "... {prompt} ...", "defaultToolGroups": [...] }。

多模型路由

注册 IProviderRouter 后，TaskNode.ModelName（格式 provider:model）与 OrchestrationOptions.PlannerModel 会路由到对应 Provider；路由失败自动回退默认模型并记录警告。未注册路由时行为不变。

编排判定

是否编排完全由模型决定：框架向模型暴露 plan_task 与 run_orchestration 两个工具，模型自行判断输入是否为复合任务并生成/执行图谱，框架不再做启发式预过滤或自动判定。

动态重规划：当关键节点失败导致整体状态为 failed 时，编排器自动触发反思阶段：

1. 反思：LLM 分析失败节点及其直接依赖的输出，判断是否可修复
2. 重规划：LLM 生成修正节点（fix_{attempt}_ 前缀）；指向已成功节点的依赖会被解析并内联为 prompt 文本，避免引用不在修正图谱中的节点
3. 重试：执行修正图谱，最多尝试 MaxReplanAttempts 次（默认 3）

// 直接调用编排器
var orchestrator = serviceProvider.GetRequiredService<IOrchestrator>();
var result = await orchestrator.RunAsync("调研 LuBan 框架并生成对比报告");

Console.WriteLine($"整体状态: {result.OverallStatus}");
Console.WriteLine($"重规划次数: {result.ReplanningAttempts}");
Console.WriteLine($"最终输出:\n{result.FinalOutput}");

// 带进度回调执行（不丢最终结果）：规划/节点级事件实时回调，返回值仍是完整编排结果
var result2 = await orchestrator.RunAsync(
    graph,
    onProgress: p => Console.WriteLine($"{p.EventType}: {p.Message}"),
    cancellationToken: default);

编排由模型调用 plan_task / run_orchestration 两个工具触发，执行发生在工具调用内部， 进度不再随对话流产出。框架通过 IOrchestrationProgressSink（默认注册 no-op 实现）广播 OrchestrationProgress（EventType / NodeId / Message / NodeResult / Activity / ElapsedMs）， 宿主可注册自定义 Sink（如 CLI 的 TuiOrchestrationProgressSink）在规划与节点执行期间逐条渲染进度。 进度事件类型包含：PlanningStarted、PlanningCompleted、NodeStarted、NodeCompleted、 NodeFailed、NodeSkipped（关键前驱失败导致后继被跳过，逐节点上报）、ReflectionStarted、 NodeActivity（节点内部思考/工具调用明细）。

编排执行流程：

1. 规划阶段：ITaskPlanner 将自然语言任务拆解为 DAG 任务图谱（模板优先，LLM 回退）
2. 校验阶段：TaskGraph.Validate 检查无环、依赖存在、无重复 ID
3. 调度阶段：DagScheduler 基于 Kahn 拓扑排序分层执行，同层节点并行
4. 上下文传递：节点 prompt 中的 {dep:xxx} 占位符由 ContextStore 替换为前驱输出
5. 错误处理：关键节点失败时跳过后继节点；非关键节点失败时继续执行
6. 结果聚合：终点节点（无后继）的输出聚合为 FinalOutput

记忆上下文注入：编排入口（Orchestrator.ExecuteGraphAsync）会通过 ContextInjectBuilder 构建工作区长期记忆与规则上下文， 一次性写入 TaskGraph.SharedContext（仅填充一次，重规划生成的修正图谱继承同一份），再由 SubAgentFactory 追加到每个 SubAgent 的系统提示词，使子代理与主 Agent 对话共享同一份工作区记忆。常规对话路径则由 SessionChatHistoryProvider 直接把召回结果作为 System 消息注入，两条路径共用同一个 ContextInjectBuilder。

关键概念：

• 关键节点（IsCritical = true）：失败时阻止后继节点执行，整体状态为 failed
• 非关键节点：失败时后继节点继续执行，整体状态为 partial
• 占位符：{dep:节点id} 引用前驱节点输出，运行时自动替换
• 并行度：MaxParallelism 限制同层最大并行节点数，0 表示不限制
• 共享上下文（SharedContext）：工作区记忆/规则上下文，由编排入口构建并注入所有子代理

10. 错误处理与自动重试

框架对所有 LLM/API 调用做统一错误分类（结构化优先：HTTP 状态码 + error.code），最终失败抛出 AgentApiException，宿主渲染 Error.FriendlyMessage 即可：

配置（appsettings.json 的 LuBanAgent 节）：

"ApiRetry": {
  "Enabled": true,
  "MaxAttempts": 3,
  "BaseDelayMs": 1000,
  "BackoffFactor": 2,
  "MaxDelayMs": 30000
}

重试进度回调（由宿主在启动时设置，回调在调用线程执行）：

options.Value.OnApiRetry = notice =>
    Console.WriteLine($"{notice.Category} 将在 {notice.Delay.TotalSeconds:F0}s 后重试（第 {notice.Attempt} 次）");

说明：

• 流式调用仅在首个 token 产出前重试；已产出内容后中断不会重试，避免内容重复。
• 容错中间件包裹在 FunctionInvokingChatClient 之内，每个工具轮次的 API 调用独立重试。
• OpenAI SDK 的内置重试（ClientRetryPolicy.Default，默认再重试 3 次）已在宿主侧禁用，重试次数与进度提示以本配置为准。
• 编排规划期的可识别 API 故障不再静默降级为常规对话，而是按分类结果透出。
• 会话摘要压缩失败会降级为「跳过压缩」继续对话，不再打断主对话。

11. 工具确认与终止语义

• 拒绝即终止：用户在工具确认中选择「拒绝」时，宿主立即终止当前对话回合（保留已输出内容）。CLI 与 Codex 均显示「已拒绝，本轮终止」；CLI 被拒工具块显示「已被用户拒绝」，Codex 确认卡显示「已拒绝」、工具卡显示框架中性结果「工具调用被拒绝或已取消」。
• 等待无限期：工具确认与工作区授权均无限期等待用户响应，无超时兜底；Esc 可随时取消本轮（CLI 显示「任务已取消」，Codex 显示「已取消」）。
• 子代理代确认：编排子代理不会向用户弹确认；其工具调用在需要人工确认时，由主代码按「本轮已允许集合」代判——命中放行，否则返回子代理专用拒绝结果（不代表用户拒绝）。
• 本轮允许集合：ToolConfirmationContext.AllowedThisTurn 不再公开；宿主使用 AllowThisTurn(toolName) 写入、框架使用 IsAllowedThisTurn(toolName) 读取。
• 子代理等待无限期：Orchestration.DefaultNodeTimeoutSeconds 与 ReflectionTimeoutSeconds 默认 0（无限期）；显式配置大于 0 时才限时，节点仍可用 TimeoutSeconds 单独覆盖。
• 规划不再「长时间无响应」：Orchestration.PlannerReasoningEffort 控制规划/反思调用的推理强度，推理模型（如 glm-5）默认开思考时会在规划阶段输出大量 reasoning 内容，单次规划耗时可达 1 分钟以上；建议设为 "none" 关闭（默认 null 表示不传递该参数，兼容不支持 reasoning_effort 的非推理模型）。

支持的 AI Provider

项目结构

LuBan.AIAgent/
├── Abstractions/
│   ├── ILuBanToolPlugin.cs            # 工具插件接口
│   ├── ToolPluginRegistry.cs          # 插件注册表
│   ├── ToolConfirmationService.cs     # 工具执行确认服务
│   ├── ToolAttribute.cs               # 工具标注特性
│   ├── ToolResult.cs                  # 工具结果
│   └── IIdentifiable.cs               # 可标识组件接口
├── Configuration/
│   ├── IAppConfigReader.cs            # 应用配置只读接口
│   ├── IProviderRouter.cs             # Provider 路由接口
│   ├── CustomSkillConfig.cs           # 自定义 Skill 配置
│   ├── CustomRuleConfig.cs            # 自定义规则配置
│   ├── McpServerConfig.cs             # 外部 MCP 服务器配置
│   ├── LuBanAgentOptions.cs           # Agent 配置选项
│   ├── BrowserToolOptions.cs          # 浏览器工具选项
│   ├── FileSystemToolOptions.cs       # 文件系统工具选项
│   ├── ScriptToolOptions.cs           # 脚本工具选项
│   ├── WebToolOptions.cs              # Web 工具选项
│   ├── RetrievalToolOptions.cs        # 检索工具选项
│   ├── LocalMemoryOptions.cs          # 本地记忆选项
│   ├── ModelEndpointOptions.cs        # 模型端点选项
│   ├── OrchestrationOptions.cs        # 编排选项
│   ├── WikiToolOptions.cs             # Wiki 工具选项
│   └── ToolGroupOptions.cs            # 工具组配置
├── Infrastructure/
│   ├── PlaywrightSession.cs           # Playwright 会话管理
│   ├── ProcessRunner.cs               # 进程执行器
│   ├── LuaScriptRunner.cs             # 内嵌 MoonSharp Lua 沙箱执行器
│   ├── ShellEnvironmentDetector.cs    # Shell 运行环境探测与命令构造
│   └── PathGuard.cs                   # 路径安全守卫
├── Tools/
│   ├── Browser/BrowserToolPlugin.cs   # 浏览器工具
│   ├── FileSystem/FileSystemToolPlugin.cs  # 文件系统工具
│   ├── Script/ScriptToolPlugin.cs     # 脚本执行工具
│   ├── Web/WebToolPlugin.cs           # Web 工具
│   ├── Context/
│   │   └── CompactContextToolPlugin.cs # 上下文压缩工具
│   ├── LocalMemory/LocalMemoryToolPlugin.cs  # 本地记忆工具
│   ├── Retrieval/RetrievalToolPlugin.cs # 语义检索工具
│   ├── Wiki/                          # LLM Wiki 知识库工具
│   │   ├── WikiToolPlugin.cs          # wiki 工具插件（opt-in）
│   │   └── WikiToolGroup.cs           # wiki 工具实现
│   └── Orchestration/                 # 编排工具
│       ├── OrchestrationToolPlugin.cs # 编排工具插件
│       └── OrchestrationToolGroup.cs  # 编排工具组
├── Skills/
│   ├── ISkill.cs                      # Skill 接口（含 PromptTemplate）
│   ├── SkillBase.cs                   # Skill 基类
│   ├── SkillRegistry.cs               # Skill 注册表（合并多来源）
│   ├── SkillLoader.cs                 # SKILL.md 文件加载器
│   ├── SkillMdParser.cs               # SKILL.md 解析器
│   ├── FileSkill.cs                   # 文件级 Skill 适配器
│   ├── CustomSkill.cs                 # 自定义 Skill 适配器
│   └── BuiltIn/
│       ├── BrainstormingSkill.cs      # 头脑风暴
│       ├── CodeReviewSkill.cs         # 代码审查
│       ├── DocumentationSkill.cs      # 文档生成
│       ├── CodeRefactorSkill.cs       # 代码重构
│       ├── TestGenerationSkill.cs     # 测试生成
│       ├── CodeExplainSkill.cs        # 代码解释
│       ├── DebugAssistantSkill.cs     # 调试助手
│       ├── GitCommitSkill.cs          # Git 提交
│       └── FindSkillsSkill.cs         # 技能发现
├── Rules/
│   ├── IRule.cs                       # 规则接口
│   ├── RuleBase.cs                    # 规则基类
│   ├── RuleEngine.cs                  # 规则引擎
│   ├── RuleCheckedAIFunction.cs       # 规则检查装饰器
│   ├── CustomRule.cs                  # 自定义规则适配器
│   └── BuiltIn/
│       └── PathAccessRule.cs          # 路径访问规则
├── MCP/
│   ├── IMCPClient.cs                  # MCP 客户端接口
│   ├── StdioMCPClient.cs              # stdio JSON-RPC 客户端
│   ├── MCPRegistry.cs                 # MCP 注册表
│   ├── MCPToolPlugin.cs               # MCP 工具插件
│   └── BuiltIn/
│       └── FileSystemMCPClient.cs     # 文件系统 MCP 客户端
├── Attachments/
│   ├── IAttachmentProcessor.cs        # 附件处理器接口
│   ├── DefaultAttachmentProcessor.cs  # 默认实现（图片/文本）
│   ├── AttachmentInfo.cs              # 附件元数据
│   ├── AttachmentKind.cs              # 附件类型枚举
│   ├── ProcessedAttachment.cs         # 处理结果
│   └── AttachmentMessageBuilder.cs    # 附件 → ChatMessage 装配
├── Sessions/
│   ├── ISessionManager.cs             # 会话管理接口
│   ├── AttachmentRecord.cs            # 附件持久化记录
│   └── SessionChatHistoryProvider.cs  # 会话历史提供者
├── Retrieval/
│   ├── IRetrievalService.cs           # 语义检索接口
│   ├── RetrievalService.cs            # 检索服务实现
│   ├── IndexProgress.cs               # 索引进度模型（阶段/已完成/总数/当前文件）
│   └── Chunkers/                     # 代码切块器
├── Wiki/                              # LLM Wiki 知识库服务
│   ├── IWikiService.cs                # wiki 服务接口
│   ├── IWikiContext.cs                # 工作区上下文接口
│   ├── WikiService.cs                 # wiki 服务实现（index/log/索引维护）
│   ├── WikiDefaults.cs                # 默认 schema 文案
│   ├── WikiFrontmatter.cs             # YAML frontmatter 解析/渲染
│   ├── WikiPageSerializer.cs          # 页面序列化
│   ├── WikiSlug.cs                    # 文件名 slug 生成
│   ├── Models.cs                      # 页面/索引/lint 模型
│   └── Extractors/                    # 源文件提取器（txt/md/json/csv/xml/html/xlsx）
├── Utils/Text/
│   ├── TextUtils.cs                   # 文本处理工具
│   ├── NGramExtractor.cs              # N-Gram 提取器
│   └── WildcardMatcher.cs             # 通配符匹配
├── LocalMemory/
│   ├── ILocalMemoryService.cs         # 本地记忆服务接口
│   ├── ILocalMemoryStore.cs           # 本地记忆存储接口
│   ├── IWorkspaceContextProvider.cs   # 工作区上下文提供者接口
│   ├── LocalMemoryService.cs          # 本地记忆服务
│   ├── MemoryCategories.cs            # 记忆分类
│   └── MemoryEntry.cs                 # 记忆条目模型
├── Orchestration/                     # 多 Agent 编排子系统
│   ├── IOrchestrator.cs               # 编排器接口
│   ├── Orchestrator.cs                # 编排器默认实现
│   ├── DagScheduler.cs                # DAG 调度器（拓扑分层并行）
│   ├── SubAgentFactory.cs             # SubAgent 工厂
│   ├── SubAgentRoleRegistry.cs        # SubAgent 角色注册表
│   ├── ContextStore.cs                # 跨节点上下文存储
│   ├── Models/                        # 数据模型
│   │   ├── TaskGraph.cs               # 任务图谱
│   │   ├── TaskNode.cs                # 任务节点
│   │   ├── TaskNodeStatus.cs          # 节点状态枚举
│   │   ├── SubAgentSpec.cs            # SubAgent 规格
│   │   ├── SubAgentRole.cs            # SubAgent 角色定义
│   │   ├── NodeResult.cs              # 节点结果
│   │   ├── OrchestrationResult.cs     # 编排结果
│   │   ├── OrchestrationProgress.cs   # 进度事件
│   │   ├── ProgressEventType.cs       # 进度事件类型
│   │   └── ReflectionResult.cs        # 反思结果与重规划上下文
│   ├── Planner/                       # 任务规划器
│   │   ├── ITaskPlanner.cs            # 规划器接口
│   │   └── LlmTaskPlanner.cs          # LLM 规划器
│   ├── GraphPlanStore.cs              # 任务图谱暂存
│   ├── IOrchestrationProgressSink.cs  # 编排进度出口
│   └── Exceptions/                    # 异常定义
│       ├── TaskPlanningException.cs   # 规划异常
│       └── NodeExecutionException.cs  # 节点执行异常
├── LuBanAgent.cs                      # Agent 实例
├── LuBanAgentFactory.cs               # Agent 工厂
├── LuBanAgentExtensions.cs            # DI 扩展方法
├── SanitizingChatClient.cs            # 聊天客户端消毒器
├── AIFunctionFactoryHelper.cs         # AI 函数工厂辅助类
└── ILuBanAgentFactory.cs              # Agent 工厂接口

小贴士

• 模型路由使用 provider:model 格式，新增 Provider 只需通过 IAppConfigReader / 宿主实现添加
• 10 大内置工具组覆盖浏览器自动化、文件操作、脚本执行、Web 请求、语义检索、上下文压缩、本地记忆、MCP、多 Agent 编排、LLM Wiki 知识库（opt-in）
• ToolConfirmationService 对写入、删除、执行等危险操作自动要求用户确认
• FileSystemToolOptions.AllowedRoots 限制文件访问范围，防止 Agent 越权操作
• 会话历史自动持久化，支持长对话压缩（SummarizingChatReducer），上下文永不丢失；启动对话时显示最近历史，快速了解上下文
• 自定义 Skill/Rule/MCP 持久化，配置保存到本地文件，重启后自动加载
• 文件化 Skill：支持通过 SKILL.md 文件定义 Skill，兼容 OpenCode 格式，项目级/用户级目录自动加载
• 规则拦截在工具执行前自动检查，支持 deny/allow/modify
• MCP 工具集成，外部 MCP 服务器工具自动暴露给 Agent
• 通过 ExternalPlugins 配置可热加载外部工具插件程序集
• 结合 LuBan.AIFlow 可对接 RagFlow / Dify / Coze 等 AI 平台
• 多 Agent 编排：复合任务自动拆解为 DAG，SubAgent 串行/并行混合执行，支持关键节点失败跳过、超时控制、上下文传递
• 附件支持：IAttachmentProcessor 统一处理图片与文本文件；图片本地缩放后以 base64 DataContent 发送，大文本仅注入路径指引；会话仅持久化路径与元数据

许可证

MIT