Add Langfuse diagnostics and GiteeAI plugin

.spec-coding/features/anthropic-agent-skills/README.md

@@ -0,0 +1,38 @@
+# Anthropic Agent Skills 需求文档
+
+## 1. 概述
+在 BotSharp 中实现 Antrhopic 推出的 "Agent Skills" 标准。该标准采用“文件系统中心化”设计和“渐进式披露”范式。Agent 不会在初始阶段加载所有工具，而是根据任务需求动态发现、加载并执行能力。
+
+## 2. 核心组件 (基于文件系统的技能单元)
+每个 Skill 是一个独立的目录，包含以下核心文件：
+*   **`SKILL.md`**: 核心定义文件。
+    *   **YAML Frontmatter**: 包含 `name` (唯一标识) 和 `description` (用于发现)。
+    *   **Markdown Body**: 包含详细的 SOP (标准作业程序/指令)。这部分仅在加载后对 LLM 可见。
+*   **`scripts/`**: 包含可执行逻辑的代码文件 (如 `.py`, `.sh`)。
+*   **`resources/`**: (可选) 静态资源文件。
+
+## 3. 交互生命周期 (The Progressive Paradigm)
+系统需支持以下四个关键阶段：
+
+1.  **索引 (Indexing)**:
+    *   系统需扫描指定目录下所有的 Skill 文件夹。
+    *   解析每个 Skill 的 `SKILL.md` 中的 YAML 头信息。
+
+2.  **感知 (Awareness)**:
+    *   将所有已发现 Skill 的 `name` 和 `description` 注入到 Agent 的初始 System Prompt 中。
+    *   目的：让 LLM 知道有哪些技能“可用”，但不知道具体的指令细节。
+
+3.  **加载 (Loading)**:
+    *   **机制**: 提供内置工具 `load_skill(skill_name)` (或类似命名)。
+    *   **流程**: 当 LLM 决定使用某技能并调用此工具时，系统读取对应 `SKILL.md` 的 Markdown 正文。
+    *   **结果**: 将正文内容追加到当前的对话上下文中 (Context)，使 LLM 获得执行该任务的详细 SOP。
+
+4.  **调用 (Invocation)**:
+    *   **机制**: 提供内置工具 `run_skill_script(skill_name, script_file, args)` (方案A)。
+    *   **流程**: LLM 根据 SOP 中的指示，构造参数调用此工具。
+    *   **执行**: 系统在宿主环境中执行对应的 `scripts/` 下的代码文件 (支持 Python 等)，并将标准输出作为结果返回给 LLM。
+
+## 4. 技术约束
+*   **插件化**: 实现为 `BotSharp.Plugin.AgentSkills`。
+*   **脚本执行**: 需复用或扩展现有的 Python 执行能力，支持“预定义代码”的运行，而非仅支持 REPL 模式。
+*   **配置**: 需支持配置 Skill 库的根路径。

.spec-coding/features/anthropic-agent-skills/design.md

@@ -0,0 +1,203 @@
+# Anthropic Agent Skills 设计文档 (Design)
+
+## 1. 概述 (Overview)
+本设计旨在 BotSharp 中实现 Agent Skills 标准。通过一个新的插件 `BotSharp.Plugin.AgentSkills`，提供技能发现、动态加载和脚本执行的能力。该设计遵循“渐进式披露”原则，降低 Agent 的初始上下文负载。
+
+## 2. 架构 (Architecture)
+架构主要由以下几个核心组件组成：
+
+1.  **AgentSkillPlugin**: 插件入口，注册服务、配置和钩子。
+2.  **AgentSkillService**: 核心服务，负责扫描文件系统、解析 `SKILL.md`、缓存技能元数据。
+3.  **AgentSkillHook**: 实现 `IAgentHook`，在 Agent 加载阶段注入可用技能的摘要（Awareness）。
+4.  **Function Tools**:
+    *   `LoadSkillFn`: 实现 `IFunctionCallback`，用于动态加载技能详情。
+    *   `RunSkillScriptFn`: 实现 `IFunctionCallback`，用于执行技能脚本。
+5.  **ScriptExecutor**: 负责安全地在宿主环境中执行脚本（主要是 Python）。
+
+### 2.1 依赖关系
+*   `BotSharp.Abstraction`: 核心接口 (`IBotSharpPlugin`, `IAgentHook`, `IFunctionCallback`).
+*   `BotSharp.Plugin.PythonInterpreter`: 用于执行 Python 脚本。需要扩展以支持执行预定义文件。
+*   `YamlDotNet`: 用于解析 YAML Frontmatter。
+*   `System.Diagnostics.Process`: 用于执行外部脚本。
+
+## 3. 组件与接口 (Components & Interfaces)
+
+### 3.1 数据模型 (Models)
+
+为了准确解析 `SKILL.md` 的 YAML Frontmatter，我们需要定义对应的强类型模型：
+
+```csharp
+public class AgentSkill
+{
+    public string Name { get; set; }
+    public string Description { get; set; }
+    public string MarkdownBody { get; set; } // 正文指令内容
+    public string BaseDir { get; set; } // 技能所在的物理目录路径
+    public List<string> Scripts { get; set; } // 可执行脚本列表
+    public List<string> Resources { get; set; } // 静态资源列表
+}
+
+/// <summary>
+/// 用于 YAML 反序列化的中间模型
+/// </summary>
+public class SkillFrontmatter
+{
+    [YamlMember(Alias = "name")]
+    public string Name { get; set; }
+
+    [YamlMember(Alias = "description")]
+    public string Description { get; set; }
+}
+
+public class AgentSkillsSettings
+{
+    public string DataDir { get; set; } = "skills";
+}
+```
+
+### 3.2 核心服务 (AgentSkillService)
+
+`AgentSkillService` 应该注册为 **Singleton**，以维护技能缓存并处理热重载。
+
+*   **职责**:
+    1.  启动时递归扫描配置的 Skills 目录。
+    2.  解析 `SKILL.md` 并构建 `AgentSkill` 对象。
+    3.  维护 `ConcurrentDictionary<string, AgentSkill>` 缓存。
+    4.  使用 `FileSystemWatcher` 监听 `*.md` 文件的变更，实现 Hot Reload。
+
+```csharp
+public interface IAgentSkillService
+{
+    // 扫描并返回所有可用技能的摘要（Name & Description）
+    Task<List<AgentSkill>> GetAvailableSkills();
+
+    // 获取特定技能的详细信息（包含 MarkdownBody）
+    Task<AgentSkill> GetSkill(string name);
+
+    // 验证并获取脚本路径
+    string GetScriptPath(string skillName, string scriptFile);
+
+    // 手动刷新缓存（可选，配合 Watcher 使用）
+    Task RefreshSkills();
+}
+```
+
+### 3.3 生命周期钩子 (AgentSkillHook) (实现细节)
+
+**阶段一：发现 (Discovery)**
+*   **Hook**: `OnInstructionLoaded`
+*   **逻辑**:
+    1.  调用 `IAgentSkillService.GetAvailableSkills()`。
+    2.  构造“技能菜单”提示词：
+        ```text
+        You have access to the following specialized skills. If a task requires one, call the 'load_skill' function with the skill name.
+
+        - pdf-processing: Handles PDF files...
+        - data-analysis: Performs statistical analysis...
+        ```
+    3.  此段提示词作为 System Instruction 的一部分注入。
+
+**阶段二：激活 (Activation)**
+*   **Hook**: `OnInstructionLoaded` (再次触发时)
+*   **逻辑**:
+    1.  检查 `conversation_state` 中的 `active_skills` 列表。
+    2.  如果发现已激活的技能（例如 "pdf-processing"），从 `AgentSkillService` 获取其 `MarkdownBody`。
+    3.  将正文注入 Prompt：
+        ```text
+        ### ACTIVE SKILL: PDF PROCESSING
+        (Markdown content...)
+        ```
+
+**阶段三：执行 (Execution)**
+*   **Hook**: `OnFunctionsLoaded`
+*   **逻辑**:
+    1.  虽然 `run_skill_script` 是通用函数，但可以在此 Hook 中做权限校验或动态提示。
+    2.  确保 `load_skill` 和 `run_skill_script` 工具已添加到当前 Agent 的功能列表中。
+    3.  (可选) 遍历 `active_skills`，显式提示用户当前可执行的脚本列表（虽然主要依靠 Markdown Body 中的 SOP 指引）。
+
+### 3.4 工具 (Functions)
+
+#### LoadSkillFn
+*   **Name**: `load_skill`
+*   **Logic**:
+    1.  接收 `skill_name`。
+    2.  更新 `conversation_state["active_skills"]`，加入该技能。
+    3.  **关键**: 返回提示 "Skill '{skill_name}' activated. Please continue."，促使 LLM 在下一轮对话中利用新注入的 Prompt（因 `OnInstructionLoaded` 会在每轮生成 Prompt 时运行）。
+
+#### RunSkillScriptFn
+*   **Name**: `run_skill_script`
+*   **Input**: `skill_name`, `script_file`, `args` (string/json)
+*   **Logic**:
+    1. 验证 `skill_name` 和 `script_file` 合法性（防止目录遍历）。
+    2. 定位物理文件路径。
+    3. 启动 `python` 进程执行脚本。
+    4. 捕获 Standard Output 和 Standard Error。
+
+### 3.5 脚本执行增强 (BotSharp.Plugin.PythonInterpreter Extension)
+
+为了支持执行预定义的本地 Python 文件，我们需要扩展 `PyCodeInterpreter` 或提供新的服务接口。
+
+*   **新增接口**: `IPyScriptExecutor` (或在 `ICodeProcessor` 中增加方法)
+    ```csharp
+    public interface IPyScriptRunner
+    {
+        // 直接运行指定路径的 py 文件，并传入参数
+        Task<string> RunScript(string filePath, string args);
+    }
+    ```
+*   **实现逻辑**:
+    *   复用现有的 Python 环境配置 (`PythonInterpreterSettings`)。
+    *   使用 `Process.Start` 启动 python 进程。
+    *   Argument 传递：`python "path/to/script.py" "args_string"`。
+    *   在 `AgentSkill` 插件中，通过 DI 获取此服务来执行 `RunSkillScriptFn` 中的请求。
+
+## 4. 流程设计 (Flows)
+
+### 4.1 总体交互流程
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Agent
+    participant SkillHook
+    participant SkillService
+    participant LoadFn
+    participant RunFn
+    participant FileSystem
+
+    User->>Agent: "Start conversation"
+    Agent->>SkillHook: OnInstructionLoaded
+    SkillHook->>SkillService: GetAvailableSkills()
+    SkillService->>FileSystem: Scan SKILL.md
+    SkillService-->>SkillHook: List<Skill>
+    SkillHook-->>Agent: Inject "Available Skills..."
+
+    User->>Agent: "Help me process this PDF..."
+    Agent->>Agent: Decide to use 'pdf-processing'
+    Agent->>LoadSkillFn: Call load_skill("pdf-processing")
+    LoadSkillFn->>SkillService: GetSkill("pdf-processing")
+    SkillService->>FileSystem: Read Markdown Body
+    LoadSkillFn-->>Agent: Return Instructions (SOP)
+
+    Agent->>Agent: Read SOP, decide to run script
+    Agent->>RunSkillScriptFn: Call run_skill_script("pdf-processing", "analyze.py", ...)
+    RunSkillScriptFn->>FileSystem: Execute script
+    FileSystem-->>RunSkillScriptFn: StdOut / StdErr
+    RunSkillScriptFn-->>Agent: Return Result
+    Agent-->>User: "Here is the result..."
+```
+
+## 5. 错误处理 (Error Handling)
+*   **文件未找到**: 如果加载不存在的 Skill，返回明确错误 "Skill not found".
+*   **脚本安全**:
+    *   严禁 `script_file` 包含 `..` 或绝对路径。
+    *   仅允许执行 `scripts/` 子目录下的文件。
+*   **执行失败**: 脚本退出码非 0 时，捕获 Stderr 并以 "Execution Failed: ..." 格式返回。
+
+## 6. 测试策略 (Testing Strategy)
+*   **单元测试**: 针对 `AgentSkillService` 的 YAML 解析逻辑。
+*   **集成测试**:
+    *   构建一个真实的 `skills/test-skill` 目录。
+    *   模拟 Agent 调用流程，验证 System Prompt 注入是否正确。
+    *   验证 `load_skill` 是否返回各个 section。
+    *   验证 `run_skill_script` 能否执行简单的 python print 脚本。

.spec-coding/features/anthropic-agent-skills/requirements.md

@@ -0,0 +1,43 @@
+# Anthropic Agent Skills 需求文档 (Requirements)
+
+## 1. 概述 (Overview)
+本功能旨在为 BotSharp 引入 Anthropic 的 "Agent Skills" 标准支持。通过实现一个新的插件 `BotSharp.Plugin.AgentSkills`，允许 Agent 采用“渐进式披露”（Progressive Disclosure）模式进行交互。与传统的一次性加载所有工具不同，Agent 将首先感知可用技能的摘要，根据需要“加载”特定技能的详细指令，并通过通用接口“执行”技能中定义的脚本。
+
+## 2. 需求列表 (Requirements)
+
+### 2.1 技能索引与感知 (Indexing & Awareness)
+**用户故事**: 作为 BotSharp 管理员，我希望系统能自动发现指定目录下的技能，以便 Agent 在初始状态下知道有哪些能力可用，而无需预加载所有繁重的指令。
+
+*   **REQ-001**: 当 Agent 初始化或系统启动时，组件 **必须** 扫描配置的技能根目录。
+*   **REQ-002**: 当发现从属目录中包含 `SKILL.md` 时，系统 **必须** 解析其 YAML Frontmatter 以提取 `name` 和 `description`。
+*   **REQ-003**: 如果 YAML 解析成功，系统 **必须** 将格式化后的技能列表（包含名称和描述）注入到 Agent 的 System Prompt（或可用的 Context Window）中。
+*   **REQ-004**: 如果 `SKILL.md` 格式无效或元数据缺失，系统 **应该** 记录警告日志并跳过该技能，即不中断整体启动流程。
+
+### 2.2 技能加载 (Skill Loading)
+**用户故事**: 作为 LLM Agent，我希望在判断某个技能对当前任务有用时能够动态加载其详细指令，以便获取执行任务所需的标准作业程序（SOP）。
+
+*   **REQ-005**: 系统 **必须** 向 LLM 暴露一个名为 `load_skill`（或语义等效）的 Function Tool。
+*   **REQ-006**: 当 `load_skill` 被调用且 `skill_name` 有效时，系统 **必须** 读取对应 `SKILL.md` 的 Markdown 正文（Body）。
+*   **REQ-007**: 当获取到 Markdown 正文后，系统 **必须** 将其作为消息（System 或 User 角色）追加到当前的对话上下文中，使其对后续推理可见。
+*   **REQ-008**: 如果请求的 `skill_name` 不存在，工具调用 **必须** 返回明确的错误提示给 Agent。
+
+### 2.3 技能脚本执行 (Skill Invocation)
+**用户故事**: 作为 LLM Agent，我希望能通过一个通用的执行接口运行技能包中定义的脚本，以便按照 SOP 完成具体的操作。
+
+*   **REQ-009**: 系统 **必须** 向 LLM 暴露一个名为 `run_skill_script` 的 Function Tool，接受 `skill_name`, `script_file`, `args` 等参数。
+*   **REQ-010**: 当 `run_skill_script` 被调用时，系统 **必须** 验证请求的脚本文件是否存在于该技能的 `scripts/` 子目录下，防止路径遍历攻击。
+*   **REQ-011**: 如果脚本是 Python 文件（`.py`），系统 **必须** 调用宿主环境的 Python 解释器执行该脚本，并将 `args` 传递给进程。
+*   **REQ-012**: 当脚本执行完成，系统 **必须** 捕获标准输出（Stdout）作为工具的成功返回值。
+*   **REQ-013**: 如果脚本执行失败（退出码非0或抛出异常），系统 **必须** 捕获错误输出（Stderr）并将其包装为错误信息返回给 Agent。
+
+### 2.4 配置与扩展性 (Configuration & Extensibility)
+**用户故事**: 作为开发者，我希望能够灵活配置技能库的位置，并以插件形式集成此功能。
+
+*   **REQ-014**: 系统 **必须** 利用 BotSharp 的配置机制（如 `appsettings.json`）读取技能库的根路径（例如 `AgentSkills:DataDir`）。
+*   **REQ-015**: 如果未提供配置，系统 **应该** 默认使用应用工作目录下的 `skills` 文件夹。
+*   **REQ-016**: 所有功能 **必须** 封装在 `BotSharp.Plugin.AgentSkills` 项目中，通过实现 `IBotSharpPlugin` 接口进行服务注册。
+
+## 3. 验收标准示例 (Acceptance Criteria Example)
+*   **Case 1: 发现技能**: 在 `skills/pdf-processing/SKILL.md` 存在的情况下，启动 Agent，System Prompt 中应包含 "pdf-processing" 及其描述。
+*   **Case 2: 动态加载**: 对 Agent 说 "我要处理 PDF"，Agent 调用 `load_skill("pdf-processing")`，随后的 Prompt 中包含了 PDF 处理的具体步骤。
+*   **Case 3: 脚本执行**: Agent 调用 `run_skill_script("pdf-processing", "analyze.py", ...)`，系统成功执行本地 Python 脚本并返回结果字符串。

.spec-coding/features/anthropic-agent-skills/tasks.md

@@ -0,0 +1,30 @@
+# Implementation Tasks - Anthropic Agent Skills
+
+- [x] **Infrastructure - Create Plugin Project**: Create `BotSharp.Plugin.AgentSkills` project and register it in `BotSharp.csproj`.
+- [x] **Infrastructure - Define Data Models**: Create `AgentSkill` and `SkillFrontmatter` models to map `SKILL.md` structure.
+- [x] **Core Service - Implement AgentSkillService**:
+    - [x] Create `IAgentSkillService` and `AgentSkillService`.
+    - [x] Implement directory scanning and `SKILL.md` YAML parsing using `YamlDotNet`.
+    - [x] Implement `GetAvailableSkills` and `GetSkill` methods.
+    - [x] Implement `FileSystemWatcher` for hot reload support.
+- [x] **Hooks - Implement AgentSkillHook**:
+    - [x] Create `AgentSkillHook` inheriting `AgentHookBase`.
+    - [x] Implement `OnInstructionLoaded` for "Discovery" phase (inject available skills list).
+    - [x] Implement logic to inject active skill instructions for "Activation" phase.
+- [x] **Functions - Implement LoadSkillFn**:
+    - [x] Create `LoadSkillFn` implementing `IFunctionCallback`.
+    - [x] Implement logic to add skill to `active_skills` in conversation state.
+    - [x] Return appropriate message to prompt LLM for next step.
+- [x] **Execution - Extend Python Interpreter**:
+    - [x] Define `IPyScriptRunner` interface in `BotSharp.Plugin.PythonInterpreter`.
+    - [x] Implement `PyScriptRunner` to execute local `.py` files using `Process.Start`.
+    - [x] Register the new service in `PythonInterpreterPlugin`.
+- [x] **Functions - Implement RunSkillScriptFn**:
+    - [x] Create `RunSkillScriptFn` implementing `IFunctionCallback`.
+    - [x] Implement parameter validation (path security).
+    - [x] Use `IPyScriptRunner` to execute the requested script.
+- [x] **Testing - Integration**:
+    - [x] Create a sample `skills/demo-skill` structure.
+    - [x] Verify discovery (System Prompt injection).
+    - [x] Verify loading (Context injection).
+    - [x] Verify execution (Script result).

.vscode/extensions.json

@@ -0,0 +1,19 @@
+{
+  "recommendations": [
+    "aaron-bond.better-comments",
+    "codezombiech.gitignore",
+    "cpylua.language-postcss",
+    "editorconfig.editorconfig",
+    "esbenp.prettier-vscode",
+    "foxundermoon.shell-format",
+    "jasonnutter.search-node-modules",
+    "jock.svg",
+    "mikestead.dotenv",
+    "streetsidesoftware.code-spell-checker",
+    "stylelint.vscode-stylelint"
+  ],
+  "unwantedRecommendations": [
+    "nucllear.vscode-extension-auto-import",
+    "steoates.autoimport"
+  ]
+}

.vscode/mcp.json

@@ -0,0 +1,13 @@
+{
+  "servers": {
+    "SpecCodingMcpServer": {
+      "type": "stdio",
+      "command": "dotnet",
+      "args": [
+        "run",
+        "--project",
+        "C:\\workshop\\ai4c\\speccodingmcpserver\\src\\SpecCodingMcpServer\\SpecCodingMcpServer.csproj"
+      ]
+    }
+  }
+}