Initial commit of integrated agent system

backend/skills/SKILL_TEMPLATE.md

@@ -0,0 +1,119 @@
+# Skill Template (Anthropic + AgentScope Aligned)
+
+> 用于定义可执行、可路由、可评估的技能规范。
+> 建议所有 `SKILL.md` 至少覆盖以下 6 个部分。
+
+---
+
+## Frontmatter Spec
+
+All `SKILL.md` files should begin with a YAML frontmatter block:
+
+```yaml
+---
+name: skill_name          # Required. Unique identifier for the skill.
+description: ...          # Required. One-line description of the skill.
+version: "1.0.0"          # Optional. Semantic version string.
+tools: [...]               # Optional. Tools provided or used by this skill.
+allowed_tools: [...]      # Optional. List of tool names permitted when this skill is active.
+denied_tools: [...]       # Optional. List of tool names denied when this skill is active.
+---
+```
+
+### Frontmatter Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Unique skill identifier (kebab-case recommended). |
+| `description` | string | Human-readable one-line description. |
+| `version` | string | Semantic version (e.g., `"1.0.0"`). |
+| `tools` | list[string] | Tools provided by or associated with this skill. |
+| `allowed_tools` | list[string] | Enumerates which tools are **permitted** when this skill is active. If set, only these tools may be used. |
+| `denied_tools` | list[string] | Enumerates which tools are **forbidden** when this skill is active. Denied tools take precedence over `allowed_tools`. |
+
+### Tool Restriction Rules
+
+- If **only** `allowed_tools` is set: only those tools are accessible.
+- If **only** `denied_tools` is set: all tools except those are accessible.
+- If **both** are set: `allowed_tools` defines the initial set, then `denied_tools` removes from it.
+- **Denial takes precedence**: a tool in `denied_tools` is always blocked even if also in `allowed_tools`.
+
+---
+
+## 1) When to use
+
+- 明确触发条件（任务类型、关键词、场景）。
+- 明确不应使用该技能的边界（避免误触发）。
+
+## 2) Required inputs
+
+- 列出最小必要输入（如 `tickers`、价格、组合状态、风险约束）。
+- 声明输入缺失时的处理规则（终止 / 降级 / 请求补充）。
+
+## 3) Decision procedure
+
+- 采用固定步骤，确保可复现。
+- 每一步说明目标、判据和产物（例如中间结论）。
+- 标明冲突处理逻辑（信号冲突、数据冲突、置信度冲突）。
+
+## 4) Tool call policy
+
+- 说明优先使用哪些工具组与工具。
+- 规定何时可以“无工具直接结论”，何时必须工具先证据后结论。
+- 规定工具失败、超时、返回异常时的替代动作。
+
+## 5) Output schema
+
+- 定义标准输出字段，便于下游 Agent 消费与评估。
+- 推荐包含：`signal`、`confidence`、`reasons`、`risks`、`invalidation`、`next_action`。
+- 若是组合决策技能，必须包含每个 ticker 的 `action` 与 `quantity`。
+
+## 6) Failure fallback
+
+- 规定在数据不足、信号冲突、风险超限、工具不可用时的降级策略。
+- 默认优先“保守 + 可解释 + 可执行”的输出。
+
+## Optional: Evaluation hooks
+
+定义技能的可评估指标，用于后续记忆/反思阶段写入长期经验。
+
+### 支持的指标类型
+
+| 指标类型 | 描述 | 适用技能 |
+|---------|------|---------|
+| `hit_rate` | 信号命中率 - 决策信号与实际结果的符合程度 | sentiment_review, technical_review |
+| `risk_violation` | 风控违例率 - 触发风控规则的次数 | risk_review, portfolio_decisioning |
+| `position_deviation` | 仓位偏离率 - 建议仓位与实际执行仓位的偏差 | portfolio_decisioning |
+| `pnl_attribution` | P&L 归因一致性 - 收益归因与实际收益的匹配度 | fundamental_review, valuation_review |
+| `signal_consistency` | 信号一致性 - 多来源信号的一致程度 | sentiment_review |
+| `decision_latency` | 决策延迟 - 从输入到决策的耗时 | portfolio_decisioning |
+| `tool_usage` | 工具使用率 - 工具调用次数与成功率的比值 | 所有技能 |
+| `custom` | 自定义指标 | 特定业务场景 |
+
+### 使用方式
+
+```python
+from backend.agents.base.evaluation_hook import EvaluationHook, MetricType
+
+# 在技能执行开始时
+evaluation_hook.start_evaluation(
+    skill_name="technical_review",
+    inputs={"tickers": ["AAPL"], "prices": {...}}
+)
+
+# 在技能执行过程中添加指标
+evaluation_hook.add_metric(
+    name="signal_confidence",
+    metric_type=MetricType.HIT_RATE,
+    value=0.85,
+    metadata={"method": "rsi", "threshold": 30}
+)
+
+# 在技能完成时记录结果
+evaluation_hook.record_outputs({"signal": "buy", "confidence": 0.8})
+evaluation_hook.complete_evaluation(success=True)
+```
+
+### 评估结果存储
+
+评估结果自动保存到 `runs/{run_id}/evaluations/{agent_id}/{skill_name}_{timestamp}.json`