Skip to content

northseadl/norix-skills / llm-agent-dev

llm-agent-dev

Unverified

LLM Agent engineering: pattern selection (12-mode matrix), data simulation, convergence iteration. Covers intent routing, function calling, ReAct, MCP, prompt chaining, guardrails, evaluation.

FileKindSize
SKILL.mdskill md17.6 KB
agents/openai.yamlconfig198 B
evals/evals.jsonconfig4.7 KB
references/convergence/iteration-protocol.mdmarkdown8.0 KB
references/eval-loop.mdmarkdown9.4 KB
references/feedback-protocol.mdmarkdown6.0 KB
references/intent-patterns.mdmarkdown5.8 KB
references/paradigms/context-engineering.mdmarkdown6.0 KB
references/paradigms/decision-tree.mdmarkdown2.7 KB
references/paradigms/memory-architecture.mdmarkdown4.0 KB
references/paradigms/observability.mdmarkdown4.5 KB
references/paradigms/pattern-matrix.mdmarkdown3.3 KB
references/paradigms/performance-benchmarking.mdmarkdown15.2 KB
references/paradigms/prompt-patterns.mdmarkdown5.0 KB
references/paradigms/safety-guardrails.mdmarkdown5.5 KB
references/paradigms/tool-design.mdmarkdown2.5 KB
references/patterns/01-crex-rule-router.mdmarkdown6.8 KB
references/patterns/02-slot-filling.mdmarkdown7.1 KB
references/patterns/03-function-calling.mdmarkdown3.9 KB
references/patterns/04-workflow-agent.mdmarkdown5.0 KB
references/patterns/05-react-agent.mdmarkdown3.4 KB
references/patterns/06-router-expert.mdmarkdown3.2 KB
references/patterns/07-mcp-tool-protocol.mdmarkdown5.0 KB
references/patterns/08-handoff-delegation.mdmarkdown4.7 KB
references/patterns/09-prompt-chaining.mdmarkdown3.0 KB
references/patterns/10-parallelizing.mdmarkdown3.2 KB
references/patterns/11-orchestrator-worker.mdmarkdown4.8 KB
references/patterns/12-evaluator-optimizer.mdmarkdown5.5 KB
references/scenarios/coding-assistant.mdmarkdown2.0 KB
references/scenarios/content-generation.mdmarkdown2.7 KB
references/scenarios/customer-service.mdmarkdown2.6 KB
references/scenarios/ecommerce-shopping.mdmarkdown4.2 KB
references/scenarios/food-ordering.mdmarkdown3.1 KB
references/scenarios/knowledge-qa.mdmarkdown2.6 KB
references/simulation/data-generation.mdmarkdown8.1 KB
references/skill-templates.mdmarkdown8.0 KB

references/paradigms/tool-design.md

View on GitHub
# 工具与 MCP 设计 (Tool & MCP Design)

> Agent 工具定义、调用约束与 MCP 集成的设计原则

## 工具设计三原则

### 1. 最小工具集

```
❌ 注册 50 个工具 → LLM 选择准确率下降
✅ 保持 5-15 个工具 → LLM 选择准确率 > 95%

如果需要超过 15 个工具 → 先用 Router 分域,每个域 ≤ 10 个工具
```

### 2. 自文档化

工具描述是给 LLM 看的文档,必须精心撰写:
- **做什么**: 1 句话说清功能
- **何时用**: 明确触发场景
- **何时不用**: 明确排除场景
- **参数**: 每个参数有清晰的语义描述
- **返回**: 说明返回数据的结构

### 3. 幂等 + 安全

- 查询类工具: 天然幂等
- 操作类工具: 必须有确认机制或幂等键
- 危险操作: 返回 "需确认" 而非直接执行

## MCP (Model Context Protocol) 集成

### 何时用 MCP

| 场景 | 推荐 | 理由 |
|------|------|------|
| 单服务 3-5 个工具 | 直接 Function Calling | MCP 过度设计 |
| 跨服务 10+ 工具 | MCP | 统一工具发现 + 标准化 |
| 需要插件生态 | MCP | 第三方工具注册 |
| 工具频繁变更 | MCP | 动态发现,无需重部署 |

### MCP Server 模式

```
Agent → [MCP Client] → [MCP Server: 商品] → search_products, get_detail
                     → [MCP Server: 订单] → query_order, cancel_order  
                     → [MCP Server: 搜索] → web_search, site_search
```

### 工具调用约束

```typescript
interface ToolConstraint {
  maxCallsPerTurn: number;      // 每轮最大调用次数: 建议 3-5
  timeoutMs: number;            // 单次调用超时: 建议 5000ms
  retryPolicy: {
    maxRetries: number;         // 最大重试: 2
    backoffMs: number;          // 退避时间: 1000ms
  };
  requiredConfirmation: boolean; // 是否需要用户确认
  auditLog: boolean;            // 是否记录审计日志
}
```

## 工具返回值设计

### 返回富上下文

```typescript
// ❌ 只返回原始数据
{ products: [{ id: '1', name: 'iPhone', price: 6999 }] }

// ✅ 返回上下文丰富的结果
{
  products: [{ id: '1', name: 'iPhone 16', price: 6999, stock: 'in_stock' }],
  totalCount: 42,
  queryTime: '0.12s',
  suggestion: '您也可以搜索 "iPhone 配件" 查看相关配件',
}
```

### 错误不要吞没

```typescript
// ❌ 吞掉错误,返回空
return { products: [] };

// ✅ 返回结构化错误
return {
  error: 'service_unavailable',
  message: '商品服务暂时不可用,请稍后重试',
  retryAfterMs: 5000,
};
```
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall