| name | llm-agent-dev |
| description | 指导开发基于大模型的 Agent 后端应用。当用户需要设计 Agent 架构、实现工具系统（Bash/Grep/Glob/文件操作）、构建上下文管理管道、开发 LLM 服务层、实现 Agent 执行循环、设计上下文压缩策略、开发结构化输出、集成 Skill/MCP 系统、或实现定时任务与自主 Agent 时使用此 Skill。即使用户只是提到"写一个 Agent"、"LLM 应用"、"工具调度"、"上下文管理"等关键词，也应主动触发。 |
LLM Agent 应用开发规范
基于上下文工程（Context Engineering）的 Agent 后端架构设计。核心理念：上下文工程是设计原则，Agent Harness 是构建目标。
开始之前
在开始构建之前，确认两件事：
- 编程语言：本 Skill 的示例代码默认使用 TypeScript，支持 Python / TypeScript / Rust / Go 等，根据所选语言调整实现风格
- 构建版本：V0 Demo 版（完整骨架，快速理解 Agent 运行原理）还是 V1 基础版（生产可用，含调度/压缩/权限）
详见 references/architecture.md——该文档是从零构建 Agent 的第一站，定义了两个版本的完整目录结构和模块边界。
架构四大支柱
Agent 后端的核心由四个相互协作的模块构成：
- 上下文管理 — 编排注入给 LLM 的完整输入（系统提示词、短期记忆、长期记忆、相关文档、结构化输出约束）
- 工具系统 — 定义工具能力、管理调度流程、控制权限审批、裁剪输出结果
- LLM 模块 — 多模型接入的服务层，通过工厂模式创建具体实例，提供统一的 complete/chat 接口
- Agent 运行空间 — Agent 的执行形态（单体/多体/协同）与运行环境（定时任务/主动触发/KAIROS 模式）
这四个模块通过执行引擎（Engine）串联：LLM 输出 → 解析 tool_calls → 工具调度执行 → 结果回填上下文 → 循环直到完成。
模块导航
根据你当前的开发需求，阅读对应的 reference 文件：
| 你在做什么 | 去读 |
|---|
| 从零构建 Agent、理解整体架构、选择版本（V0/V1） | references/architecture.md |
| 设计上下文管道、压缩策略、记忆模块、结构化输出 | references/context/overview.md |
| 开发工具（Bash/Grep/文件操作）、工具调度、权限审批 | references/tools/overview.md |
| 接入多个 LLM、设计服务层和工厂模式 | references/llm/llm-service.md |
| 设计 Agent 形态、执行循环、定时任务 | references/agent-runtime/agent-patterns.md |
| 搭建评估体系、多类型 Agent 评估策略、评估器实现 | references/agent-evaluation/overview.md |
| RAG、Skill 集成等基础设施 | references/foundations/overview.md |
| 工程实践经验与常见陷阱 | references/practices/ |
所有代码示例位于 examples/ 目录，文档中通过路径引用。
注意事项
这些是基于实际开发中反复出现的失败模式总结的：
- 上下文污染：工具错误信息不精确导致 LLM 在错误方向上反复重试。设计工具时确保错误输出能准确反映真正原因
- 上下文膨胀：工具输出未裁剪直接回填，导致上下文窗口被低价值信息占满。必须有 OutputTruncator 机制
- 压缩时机误判：过早压缩丢失关键决策信息，过晚压缩导致窗口溢出。压缩应在 token 使用率达到阈值时触发，而非固定轮次
- 工具描述模糊：description 写得太笼统，LLM 无法判断何时使用该工具。工具描述需包含 Instructions 指明使用场景和限制
- 记忆模块的"过时问题"：用户记忆整理时的误解会持续污染后续交互，记忆需要有更新和精简机制
