docs: Evaluate LangChain4j for SKILLS mechanism integration

docs-dev/copilot/langchain4j-skills-integration-evaluation-zh.md

@@ -0,0 +1,328 @@
+# LangChain4j 与 SKILLS 机制集成评估
+
+**创建日期**: 2026-02-18  
+**问题**: 评估引入 LangChain4j 来实现 SKILLS 机制  
+**状态**: ✅ 评估完成 - 建议不做改动
+
+---
+
+## 执行摘要
+
+**结论：不建议引入 LangChain4j 来实现 SKILLS 机制。**
+
+Browser4 现有的 SKILLS 机制设计优秀、功能丰富，并符合业界标准 (agentskills.io)。LangChain4j 已经在 LLM 通信层得到了恰当的使用。额外的集成不会带来任何好处，反而会增加复杂度并损失现有功能。
+
+---
+
+## 现状分析
+
+### 1. 现有 SKILLS 实现
+
+Browser4 在 `pulsar-agentic` 模块中已经实现了完善的 SKILLS 机制：
+
+#### 核心组件
+
+| 组件 | 作用 |
+|------|------|
+| `Skill.kt` | Skill 接口，包含元数据、执行和生命周期 |
+| `SkillRegistry.kt` | 管理 skill 的注册、发现和执行 |
+| `SkillBootstrap.kt` | 启动时自动加载 skills |
+| `SkillDefinitionLoader.kt` | 从目录结构加载 skills |
+| `DefinitionBackedSkill.kt` | 基于 SKILL.md 定义的 skill |
+
+#### 架构特性
+
+```
+SKILLS 架构:
+├── 渐进式披露 (Progressive Disclosure)
+│   ├── 发现阶段: 仅加载 name + description (~100 tokens)
+│   ├── 激活阶段: 加载完整 SKILL.md 内容
+│   └── 执行阶段: 按需加载 scripts/references/assets
+├── 基于资源的结构
+│   ├── SKILL.md (元数据 + 指令)
+│   ├── scripts/ (可执行代码)
+│   ├── references/ (详细文档)
+│   └── assets/ (模板、配置)
+├── 生命周期管理
+│   ├── onLoad() - 初始化
+│   ├── execute() - 任务执行
+│   ├── onUnload() - 清理
+│   └── validate() - 依赖检查
+└── 依赖解析
+    └── Skills 之间可以声明依赖关系
+```
+
+#### 规范遵从
+
+遵循 **Agent Skills** 规范 (https://agentskills.io):
+- 标准化的目录结构
+- SKILL.md 中的 YAML frontmatter
+- 渐进式披露设计模式
+- 可选目录 (scripts, references, assets)
+
+### 2. 现有 LangChain4j 使用情况
+
+LangChain4j (v1.5.0) 已经集成用于 LLM 通信：
+
+**模块**: `pulsar-core/pulsar-third/pulsar-llm/`
+
+**核心类**:
+- `BrowserChatModel` - LangChain4j 兼容的聊天模型接口
+- `CachedBrowserChatModel` - 带缓存的模型包装器
+- `ChatModelFactory` - 为各种提供商创建模型 (OpenRouter, DeepSeek, Dashscope, Volcengine, OpenAI)
+
+**当前用途**:
+- ✅ LLM 通信 (chat completions)
+- ✅ 消息格式标准化
+- ✅ 多提供商支持
+- ✅ 响应缓存
+
+**未用于**:
+- ❌ 工具调用框架
+- ❌ Agent 编排
+- ❌ 服务定义
+
+---
+
+## 集成方案评估
+
+### 方案一: 使用 LangChain4j 的 Tool/Service 框架
+
+**描述**: 用 LangChain4j 的内置工具框架替换 Browser4 的 SKILLS
+
+**优点**:
+✓ 标准的 AI 工具调用框架  
+✓ 自动参数解析  
+✓ 内置 JSON schema 生成  
+
+**缺点**:
+✗ **丢失渐进式披露**: LangChain4j 工具没有分阶段加载机制  
+✗ **丢失生命周期管理**: 无 onLoad/onUnload/validate 钩子  
+✗ **丢失资源结构**: 无 SKILL.md, scripts/, references/, assets/  
+✗ **丢失依赖解析**: 工具之间无依赖管理  
+✗ **需要大量重构**: 用更简单的系统替换已工作的系统  
+
+**结论**: ❌ **不推荐** - 会丢失关键功能
+
+---
+
+### 方案二: 使用 LangChain4j 类型进行通信
+
+**描述**: 保留现有 SKILLS 架构，但使用 LangChain4j 的消息类型
+
+**优点**:
+✓ 标准化的消息格式  
+✓ 理论上更好的 LLM 兼容性  
+✓ 对现有架构改动最小  
+
+**缺点**:
+✗ **仅为通信层增加依赖**: 只是做类型转换  
+✗ **当前 ToolSpec 已经工作**: 没有观察到兼容性问题  
+✗ **阻抗不匹配风险**: 不同的类型系统和假设  
+✗ **维护负担**: 保持两个类型系统同步  
+
+**结论**: ❌ **不推荐** - 增加复杂度而无收益
+
+---
+
+### 方案三: 混合方案 - 选择性集成
+
+**描述**: 在特定功能上使用 LangChain4j，保留 Browser4 的 SKILLS
+
+**可能的用例**:
+- JSON schema 生成
+- 流式响应处理
+- 对话历史管理
+- 重试/错误处理工具
+
+**优点**:
+✓ 针对特定任务利用 LangChain4j 的优势  
+✓ 保留 Browser4 独特的 SKILLS 架构  
+✓ 对现有代码影响最小  
+✓ 可以逐步采用  
+
+**缺点**:
+✗ **增加复杂度**: 维护两个框架  
+✗ **边界不清**: 何时使用哪个框架？  
+✗ **映射开销**: 类型系统之间转换  
+✗ **有限的效用**: 大多数功能已存在  
+
+**结论**: ⚠️ **边际价值** - 仅对特定工具有用，不适用于核心 SKILLS
+
+---
+
+## 功能对比
+
+| 功能 | Browser4 SKILLS | LangChain4j Tools |
+|------|----------------|-------------------|
+| **发现机制** | ✅ 渐进式 (摘要 → 完整文档) | ❌ 全有或全无 |
+| **资源结构** | ✅ SKILL.md + scripts/ + references/ + assets/ | ❌ 仅代码 |
+| **生命周期钩子** | ✅ onLoad, onUnload, validate | ❌ 无 |
+| **依赖管理** | ✅ Skill 间依赖 | ❌ 无依赖管理 |
+| **元数据** | ✅ 丰富 (作者, 版本, 标签, 许可) | ⚠️ 基础 (名称, 描述) |
+| **参数解析** | ✅ 自定义验证 | ✅ 从签名自动生成 |
+| **JSON Schema** | ⚠️ 手动 | ✅ 自动 |
+| **执行模式** | ✅ 异步/协程安全 | ✅ 同步/异步支持 |
+| **工具调用** | ✅ 与 LLM 配合工作 | ✅ 与 LLM 配合工作 |
+| **行业标准** | ✅ agentskills.io 规范 | ⚠️ LangChain4j 特定 |
+
+---
+
+## 推荐方案
+
+### ✅ 保持当前架构
+
+**不要引入 LangChain4j 来实现 SKILLS 机制。**
+
+#### 理由
+
+1. **Browser4 的 SKILLS 已经设计优秀**
+   - 遵循业界标准 (agentskills.io)
+   - 渐进式披露优化 token 使用
+   - 基于资源的结构支持复杂 skills
+   - 完善的生命周期管理
+   - Skills 间依赖解析
+
+2. **LangChain4j 已经得到恰当使用**
+   - 用于 LLM 通信 (chat models)
+   - 兼容多个提供商
+   - 关注点清晰分离
+   - 与 SKILLS 功能无重叠
+
+3. **集成无明显收益**
+   - LangChain4j 的工具框架**比** Browser4 的 SKILLS **简单**
+   - 迁移会**损失功能**
+   - 现有系统对所有用例**工作良好**
+   - 无性能或兼容性问题
+
+4. **符合项目原则**
+   - 来自 `docs-dev/copilot/tasks/pulsar-agents.md`:
+     > "不引入外部编排框架（如 LangChain）— 先内部最小实现。"
+   - 内部 SKILLS 实现已经完成且成功
+
+5. **风险与收益分析**
+   - **风险**: 高 (大量重构, 功能丢失, 复杂度增加)
+   - **收益**: 无 (无功能改进, 无性能提升)
+
+---
+
+## 替代方案: 增强现有系统
+
+不引入 LangChain4j，而是对现有系统进行**渐进式改进**:
+
+### 1. 改进 JSON Schema 生成
+
+**问题**: 从 `ToolSpec` 手动创建 JSON schema
+
+**解决方案**: 添加自动 schema 生成工具
+
+```kotlin
+object ToolSpecSchemaGenerator {
+    fun generateJsonSchema(toolSpec: ToolSpec): JsonObject {
+        // 自动从 ToolSpec 生成 JSON schema
+    }
+}
+```
+
+**收益**: 无需外部依赖自动化 schema 生成
+
+### 2. 标准化工具调用格式
+
+**问题**: 隐式格式约定
+
+**解决方案**: 文档化并验证 ToolSpec → LLM 格式
+
+```kotlin
+data class ToolCallFormat(
+    val name: String,
+    val arguments: Map<String, Any>,
+    val callId: String? = null
+)
+```
+
+**收益**: 明确契约, 更好的验证
+
+### 3. 改进 SKILLS 文档
+
+**问题**: 示例和指南有限
+
+**解决方案**: 扩展文档
+
+**任务**:
+- [ ] 添加 5 个以上示例 skills (PDF 处理, API 调用, 数据转换等)
+- [ ] 文档化 skill 开发最佳实践
+- [ ] 创建带模板的 skill 开发指南
+- [ ] 添加故障排除部分
+- [ ] 文档化渐进式披露模式
+
+### 4. 添加 Skill 测试框架
+
+**问题**: 没有专门的 skills 测试工具
+
+**解决方案**: 创建测试辅助工具
+
+```kotlin
+class SkillTestSupport {
+    fun createMockContext(): SkillContext { ... }
+
+    suspend fun testSkillExecution(
+        skill: Skill,
+        params: Map<String, Any>
+    ): SkillResult { ... }
+}
+```
+
+**收益**: 更好的测试, 更高质量的 skills
+
+---
+
+## 结论
+
+### 总结
+
+Browser4 的 SKILLS 机制是一个**设计优秀、功能丰富的系统**，超越了 LangChain4j 工具框架的能力。当前架构:
+
+✅ 遵循业界标准 (agentskills.io)  
+✅ 支持渐进式披露以提高 token 效率  
+✅ 提供丰富的元数据和生命周期管理  
+✅ 支持 skills 间依赖解析  
+✅ 基于资源的定义 (SKILL.md, scripts 等)  
+
+LangChain4j 已经恰当地用于 **LLM 通信**，与 SKILLS 功能无重叠。
+
+### 决定
+
+**状态**: ✅ **当前架构已是最优**
+
+**行动**: ✅ **无需改动**
+
+**未来工作**: ⚠️ **考虑渐进式增强** (JSON schema 生成, 更多示例, 测试框架)
+
+---
+
+## 参考资料
+
+### 内部文档
+
+- [Agent Skills 规范](../agentic/skills/specification.md)
+- [Skills 实现指南](../agentic/skills/implementation-guide.md)
+- [Skills 框架](../copilot/skills-framework.md)
+- [英文完整评估](./langchain4j-skills-integration-evaluation.md)
+
+### 外部资源
+
+- [Agent Skills 官方网站](https://agentskills.io)
+- [LangChain4j 文档](https://docs.langchain4j.dev/)
+
+### 代码位置
+
+- SKILLS 核心: `pulsar-agentic/src/main/kotlin/ai/platon/pulsar/agentic/skills/`
+- LLM 集成: `pulsar-core/pulsar-third/pulsar-llm/`
+- 示例 Skills: `pulsar-agentic/src/main/resources/skills/`
+
+---
+
+**文档版本**: 1.0  
+**最后更新**: 2026-02-18  
+**作者**: Browser4 开发团队  
+**状态**: 最终版 - 无需采取行动