| name | koog-dev |
| description | Koog 开发工具包：梳理 Tools/MCP/Prompt/LLM 参数/记忆/压缩/审核等规范并产出模板。用户提到 Koog、ToolRegistry、MCP、AskUser、ChatMemory 时调用。 |
Koog 开发 SKILL 工具包（koog-dev）
你什么时候该用它
- 你要在 Koog 上开发/改造 Agent（Basic / Functional / Graph / Planner）
- 你要实现或接入工具（Tool / SimpleTool / ToolRegistry）
- 你要把工具调用轨迹写进 Prompt（toolCall / toolResult）
- 你要接 MCP（stdio / SSE）并桥接到 ToolRegistry
- 你要接入 ChatMemory / LongTermMemory / HistoryCompression
- 你要做内容审核（输入/输出/工具三段式）
- 你要做模型参数与能力降级（LLMParams / LLMCapability）
输出物（工具包结构）
规范总览（最重要的 10 条）
- API Key 只从环境变量/安全存储读取，禁止硬编码
- 必设
maxIterations/maxAgentIterations 防止循环成本失控
- Tool 入参用 object schema（
@Serializable data class Args(...)），避免 schema 初始化问题
- Tool 描述/参数描述必须清晰，输出尽量结构化（便于二段式扩写/后处理）
- 工具必须注册进
ToolRegistry，Agent 才能调用
- 不确定/信息不足时必须走
AskUser 工具（不要靠猜）
- 长对话必须启用
HistoryCompression，并按需 preserveMemory
- ChatMemory 负责短期对话历史；LongTermMemory 负责长期可检索记忆（默认建议显式写入）
- 接 MCP 时要明确传输方式（stdio/SSE）、ServerInfo、版本与工具来源隔离
- 内容审核默认开启：输入前审、输出前审、工具边界审
关键 API 与调用方式（对照表）
Tools / ToolRegistry
- 工具基类：
Tool<Args, Result>、SimpleTool<Args>
- 注册：
ToolRegistry { tools(myTool) }
- 参考：见 koog-reference.md
Prompt DSL（含 toolCall/toolResult）
- DSL 入口：
ai.koog.prompt.dsl.prompt
- 工具消息：
toolCall(id, tool, args) / toolResult(id, tool, output)
- 参考：见 koog-reference.md
LLM 参数与模型能力
- Prompt 级参数：
LLMParams(temperature, toolChoice, numberOfChoices, maxTokens, schema, ...)
- 能力检测：
LLModel.supports(LLMCapability.Tools) 等
- 参考：见 koog-reference.md
MCP
记忆与压缩
- ChatMemory：
ChatHistoryProvider + ChatMemory feature（短期对话历史）
- LongTermMemory：
SearchStorage/WriteStorage + SimilaritySearchStrategy + SystemPromptAugmenter
- HistoryCompression：
nodeLLMCompressHistory / llmCompressHistory() / preserveMemory
- 参考：见 koog-reference.md
内容审核
关键配置清单（照单对齐）
Agent 运行参数（最小必配）
systemPromptllmModeltemperaturemaxIterationstoolRegistry（可选，但只要你需要 tools 就必须）
LLMParams（Prompt 级推荐）
temperaturemaxTokenstoolChoicenumberOfChoicesschemaspeculation
Model Capabilities（能力检测/降级）
- Core：
Temperature、Tools、ToolChoice、MultipleChoices、Speculation
- Schema：
Schema.JSON.Basic、Schema.JSON.Standard
- Media/Text：
Vision.Image、Document、Embed、Completion、PromptCaching、Moderation
ChatMemory / LongTermMemory / HistoryCompression
- ChatMemory：
sessionId（建议 userId+agentId+场景），ChatHistoryProvider（持久化实现）
- LongTermMemory：
namespace（建议 userId_agentId）、SimilaritySearchStrategy(topK, similarityThreshold)、SystemPromptAugmenter
- HistoryCompression：
- Strategy：
WholeHistory / FromLastNMessages(n) / Chunked(chunkSize) / FactRetrievalHistoryCompressionStrategy
preserveMemory（避免压缩误删关键 memory 消息）
MCP
- Transport：stdio / SSE
McpServerInfo(url, command?)- Client meta：
name、version
工程模板（可直接复制）
1) 入口：创建 Agent + 注入 ToolRegistry
见：KoogDevEntry.kt
2) 配置模块：统一管理 Provider/Model/Key/Iterations/温度
见：KoogDevConfig.kt
3) 工具模块：SimpleTool + Args schema + 错误处理
见：ExampleAddTool.kt
4) MCP 模块：stdio/SSE → ToolRegistry
见：McpRegistryFactory.kt
5) Prompt 模块：toolCall/toolResult 写入 Prompt（可选）
见：PromptTemplates.kt
错误处理方案（落地必配）
- 工具执行失败：工具内部捕获异常并返回可解释错误字符串；必要时将错误映射为“可重试/不可重试”
- AskUser：信息不足时必须走工具追问；选项为空时允许自由输入
- 重试/超时：在业务调用工具/外部 API 时设置超时；在 Agent 侧用
maxIterations 限制循环
- 截断：提高
maxTokens、减少无关历史、启用 history compression
常见问题排查（FAQ）
- 工具不被调用：检查是否注册到
ToolRegistry；检查 systemPrompt 是否明确“优先用工具”；检查模型是否支持 LLMCapability.Tools
- 工具参数解析失败：确认 Args 是
@Serializable data class 且为 object schema；减少可选字段数量；用 @LLMDescription 补语义
- 模型输出不稳定：降
temperature；强化输出格式；必要时上 JSON schema
- 长对话越聊越慢：启用
HistoryCompression；拆分 sessionId；把长期偏好写入 LongTermMemory
- MCP 工具不可用：确认 transport（stdio/SSE）连通；确认
McpServerInfo；确认 ToolRegistry 来源隔离
验证（模拟环境）
- 只验证 SDK 接口可调用（不依赖真实 LLM 网络）：运行 smoke test（需将本 SKILL 的测试文件复制到你的工程 test 源集后执行）
./gradlew test
./gradlew :baseKit:compileDebugKotlin
./gradlew :app:compileDebugKotlin
部署/集成步骤（复制即用）
- 把 toolkit 目录里的模板复制到你的工程（建议路径：
<module>/src/main/java/.../koog/）
- 根据你的平台替换配置来源（Android：设置页/EncryptedStorage；Server：ENV/Secrets）
- 先跑 smoke test（上面命令），再替换为真实 promptExecutor（OpenAI/Anthropic/Google/DeepSeek/Ollama 等）
