初始化
This commit is contained in:
1 parent
34474bd5fc
commit
b638b541d0
3008 files changed
+837699
No files matched your search
@@ -0,0 +1,40 @@
|
||||
---
|
||||
name: sentiment-analysis
|
||||
description: 调用外部舆情分析 AG-UI 网关,实时解析思考与正文流,并输出统一 NDJSON 或 Markdown 结果。
|
||||
license: Proprietary
|
||||
version: 1.0.0
|
||||
allowed-tools:
|
||||
- bash
|
||||
---
|
||||
|
||||
# 舆情分析
|
||||
|
||||
当用户需要研判新闻事件、社会热点、品牌声誉、风险传播或某一主题的舆情态势时,使用本技能调用已配置的外部舆情分析服务。
|
||||
|
||||
## 执行规则
|
||||
|
||||
1. 必须实际执行本技能目录中的 `scripts/sentiment_stream.py`,不要根据常识虚构分析结果。
|
||||
2. 默认使用 `--format markdown`,将脚本最终输出原样或经简短整理后回复用户。
|
||||
3. 当调用方需要消费实时增量时,使用 `--format ndjson`。每行都是一个 JSON 事件,可直接按 `type` 渲染:
|
||||
- `thinking_delta`:思考文本增量;
|
||||
- `answer_delta`:正文文本增量;
|
||||
- `done`:完整结果;
|
||||
- `error`:调用失败。
|
||||
4. 只有在用户明确需要结合上一轮结果时,才通过 `--messages-file` 传入历史消息。历史文件必须是 JSON 数组,元素为 `{role, id, content}`。
|
||||
5. 不得在回答、日志或产物中输出接口配置中的用户名、密码或 Authorization 请求头。
|
||||
|
||||
## 调用命令
|
||||
|
||||
在技能运行目录执行:
|
||||
|
||||
```bash
|
||||
python scripts/sentiment_stream.py --question "请分析某主题近期的舆情态势" --format markdown
|
||||
```
|
||||
|
||||
需要给调用方提供可实时消费的标准化流时:
|
||||
|
||||
```bash
|
||||
python scripts/sentiment_stream.py --question "请分析某主题近期的舆情态势" --format ndjson
|
||||
```
|
||||
|
||||
完整安装、鉴权配置、历史消息和事件格式见 `docs/调用与安装说明.md`。
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"api_url": "https://gw.y.sit.4.cn/alg/stream/report-agent",
|
||||
"timeout_seconds": 300,
|
||||
"verify_tls": true,
|
||||
"auth": {
|
||||
"username": "",
|
||||
"password": "",
|
||||
"username_env": "SENTIMENT_AGENT_AUTH_USERNAME",
|
||||
"password_env": "SENTIMENT_AGENT_AUTH_PASSWORD"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,101 @@
|
||||
# 舆情分析技能:安装与调用说明
|
||||
|
||||
## 1. 包内容
|
||||
|
||||
安装包 `sentiment-analysis.skill` 是 ZIP 格式,解压后包含以下文件:
|
||||
|
||||
```text
|
||||
sentiment-analysis/
|
||||
├── SKILL.md
|
||||
├── config/
|
||||
│ └── sentiment-agent.json # 接口地址与鉴权配置(独立文件)
|
||||
└── scripts/
|
||||
└── sentiment_stream.py # AG-UI SSE 调用与流式转换脚本
|
||||
```
|
||||
|
||||
脚本只使用 Python 标准库,不需要额外执行 `pip install`。
|
||||
|
||||
## 2. 安装到技能管理
|
||||
|
||||
1. 打开系统的「技能管理」。
|
||||
2. 选择「导入/安装技能」,上传 `sentiment-analysis.skill`。
|
||||
3. 在安装预览中确认技能名称为 `sentiment-analysis`,安装到「我的技能」。
|
||||
4. 在技能列表启用该技能;如需让某个智能体使用,再在该智能体的技能配置中勾选「舆情分析」。
|
||||
|
||||
安装后,技能目录通常是 `/mnt/skills/custom/sentiment-analysis/`。实际容器挂载目录以部署配置为准。
|
||||
|
||||
## 3. 配置接口与鉴权
|
||||
|
||||
接口地址单独保存在:
|
||||
|
||||
```text
|
||||
config/sentiment-agent.json
|
||||
```
|
||||
|
||||
默认已填入当前舆情网关地址。鉴权不写入安装包,推荐在运行技能的环境中设置:
|
||||
|
||||
```bash
|
||||
export SENTIMENT_AGENT_AUTH_USERNAME='你的用户名'
|
||||
export SENTIMENT_AGENT_AUTH_PASSWORD='你的密码'
|
||||
```
|
||||
|
||||
脚本优先读取这两个环境变量。仅在受控的内网测试环境,也可以将 `auth.username` 和 `auth.password` 填入 `config/sentiment-agent.json`;不要将带有真实密码的配置提交到代码仓库或上传到公共技能广场。
|
||||
|
||||
如需切换环境,只改 `config/sentiment-agent.json` 中的 `api_url`,不需要修改脚本或重新打包。`timeout_seconds` 为一次请求的连接与读取超时上限,`verify_tls` 生产环境应保持 `true`。
|
||||
|
||||
## 4. 调用方法
|
||||
|
||||
进入技能目录后运行:
|
||||
|
||||
```bash
|
||||
python scripts/sentiment_stream.py \
|
||||
--question "请分析某主题近一周的舆情态势、风险点和建议" \
|
||||
--format markdown
|
||||
```
|
||||
|
||||
`markdown` 适用于普通智能体对话:脚本在上游完成后输出可直接回复给用户的 Markdown。
|
||||
|
||||
若调用端能够持续读取标准输出,改用 `ndjson` 可获得实时标准化事件:
|
||||
|
||||
```bash
|
||||
python scripts/sentiment_stream.py \
|
||||
--question "请实时分析某主题的舆情" \
|
||||
--format ndjson
|
||||
```
|
||||
|
||||
每行是一个完整 JSON,不需要再解析上游 AG-UI 的字段差异:
|
||||
|
||||
| `type` | 含义 | 关键字段 |
|
||||
| --- | --- | --- |
|
||||
| `run_started` | 上游开始运行 | `threadId`, `runId` |
|
||||
| `thinking_delta` | 思考文本增量 | `messageId`, `delta` |
|
||||
| `answer_delta` | 正文文本增量 | `messageId`, `delta` |
|
||||
| `run_finished` | 上游运行结束 | `threadId`, `runId` |
|
||||
| `done` | 本次完整结果汇总 | `reasoning`, `answer` |
|
||||
| `error` | 安全的错误说明 | `message` |
|
||||
|
||||
## 5. 传入多轮历史
|
||||
|
||||
先准备一个 JSON 数组,例如 `history.json`:
|
||||
|
||||
```json
|
||||
[
|
||||
{"role": "user", "id": "u-1", "content": "请先分析某主题的总体舆情"},
|
||||
{"role": "assistant", "id": "a-1", "content": "此前分析结论……"}
|
||||
]
|
||||
```
|
||||
|
||||
再调用:
|
||||
|
||||
```bash
|
||||
python scripts/sentiment_stream.py \
|
||||
--messages-file history.json \
|
||||
--question "请补充近三天的风险变化" \
|
||||
--format markdown
|
||||
```
|
||||
|
||||
脚本会把历史与本轮问题转换为上游所需的 `messages`,并自动生成缺省的 `threadId`、`runId` 和本轮消息 `id`。也可通过 `--thread-id`、`--run-id` 显式传入,方便调用方关联日志。
|
||||
|
||||
## 6. 与当前前端的关系
|
||||
|
||||
该包是独立的技能调用方式,不修改现有舆情分析前端页面。脚本本身已经实时输出规范化 NDJSON;若未来有新的调用端需要逐字展示,只需消费这些 NDJSON 行,而不用再次对接或解析外部 AG-UI SSE。
|
||||
+295
@@ -0,0 +1,295 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Invoke the configured AG-UI sentiment gateway and normalize its SSE stream.
|
||||
|
||||
This script intentionally uses only Python's standard library, so an installed
|
||||
skill does not need to install an extra dependency. It accepts the external
|
||||
AG-UI stream and prints one normalized JSON object per line (NDJSON) as soon as
|
||||
each event arrives, which makes it suitable for a caller that renders a live
|
||||
stream. ``--format markdown`` is a convenience mode for ordinary agent calls.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import base64
|
||||
import json
|
||||
import os
|
||||
import ssl
|
||||
import sys
|
||||
import uuid
|
||||
from collections.abc import Iterable, Iterator
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
from urllib.error import HTTPError, URLError
|
||||
from urllib.request import HTTPSHandler, Request, build_opener
|
||||
|
||||
|
||||
DEFAULT_CONFIG_PATH = Path(__file__).resolve().parents[1] / "config" / "sentiment-agent.json"
|
||||
VALID_ROLES = {"user", "assistant"}
|
||||
|
||||
|
||||
class SentimentAgentError(RuntimeError):
|
||||
"""A safe, user-facing error from the external sentiment gateway."""
|
||||
|
||||
|
||||
def load_config(path: Path) -> dict[str, Any]:
|
||||
"""Read and validate the skill's separate gateway configuration file."""
|
||||
|
||||
try:
|
||||
raw = json.loads(path.read_text(encoding="utf-8"))
|
||||
except FileNotFoundError as exc:
|
||||
raise SentimentAgentError(f"未找到技能配置文件:{path}") from exc
|
||||
except json.JSONDecodeError as exc:
|
||||
raise SentimentAgentError(f"技能配置文件不是合法 JSON:{path}") from exc
|
||||
if not isinstance(raw, dict):
|
||||
raise SentimentAgentError("技能配置文件根节点必须是 JSON 对象。")
|
||||
|
||||
api_url = str(raw.get("api_url") or "").strip()
|
||||
if not api_url.startswith(("https://", "http://")):
|
||||
raise SentimentAgentError("请先在 config/sentiment-agent.json 配置有效的 api_url。")
|
||||
return raw
|
||||
|
||||
|
||||
def _read_auth_value(auth: dict[str, Any], key: str) -> str:
|
||||
"""Read a credential, allowing the deployment environment to override JSON."""
|
||||
|
||||
env_name = str(auth.get(f"{key}_env") or "").strip()
|
||||
if env_name:
|
||||
env_value = os.getenv(env_name)
|
||||
if env_value:
|
||||
return env_value
|
||||
return str(auth.get(key) or "")
|
||||
|
||||
|
||||
def build_headers(config: dict[str, Any]) -> dict[str, str]:
|
||||
"""Create upstream request headers without ever printing credentials."""
|
||||
|
||||
headers = {
|
||||
"Content-Type": "application/json",
|
||||
"Accept": "text/event-stream",
|
||||
}
|
||||
auth = config.get("auth")
|
||||
if not isinstance(auth, dict):
|
||||
return headers
|
||||
username = _read_auth_value(auth, "username")
|
||||
password = _read_auth_value(auth, "password")
|
||||
if username and password:
|
||||
token = base64.b64encode(f"{username}:{password}".encode("utf-8")).decode("ascii")
|
||||
headers["Authorization"] = f"Basic {token}"
|
||||
return headers
|
||||
|
||||
|
||||
def load_history(path: Path | None) -> list[dict[str, str]]:
|
||||
"""Read a caller-supplied AG-UI history file and validate its safe subset."""
|
||||
|
||||
if path is None:
|
||||
return []
|
||||
try:
|
||||
raw = json.loads(path.read_text(encoding="utf-8"))
|
||||
except FileNotFoundError as exc:
|
||||
raise SentimentAgentError(f"未找到历史消息文件:{path}") from exc
|
||||
except json.JSONDecodeError as exc:
|
||||
raise SentimentAgentError(f"历史消息文件不是合法 JSON:{path}") from exc
|
||||
if not isinstance(raw, list):
|
||||
raise SentimentAgentError("历史消息文件必须是 JSON 数组。")
|
||||
|
||||
messages: list[dict[str, str]] = []
|
||||
for index, item in enumerate(raw, start=1):
|
||||
if not isinstance(item, dict):
|
||||
raise SentimentAgentError(f"历史消息第 {index} 项必须是对象。")
|
||||
role = str(item.get("role") or "")
|
||||
content = str(item.get("content") or "").strip()
|
||||
if role not in VALID_ROLES or not content:
|
||||
raise SentimentAgentError(f"历史消息第 {index} 项需要非空 role(user/assistant) 和 content。")
|
||||
message_id = str(item.get("id") or f"history-{index}-{uuid.uuid4()}")
|
||||
messages.append({"role": role, "id": message_id, "content": content})
|
||||
return messages
|
||||
|
||||
|
||||
def build_payload(
|
||||
*,
|
||||
thread_id: str,
|
||||
run_id: str,
|
||||
question: str,
|
||||
history: list[dict[str, str]],
|
||||
) -> dict[str, Any]:
|
||||
"""Build the AG-UI request body documented by the external gateway."""
|
||||
|
||||
text = question.strip()
|
||||
if not text:
|
||||
raise SentimentAgentError("问题不能为空。")
|
||||
return {
|
||||
"threadId": thread_id,
|
||||
"runId": run_id,
|
||||
"state": {},
|
||||
"tools": [],
|
||||
"context": [],
|
||||
"forwardedProps": {},
|
||||
"messages": [
|
||||
*history,
|
||||
{"role": "user", "id": f"message-{uuid.uuid4()}", "content": text},
|
||||
],
|
||||
}
|
||||
|
||||
|
||||
def parse_sse_payloads(lines: Iterable[bytes]) -> Iterator[dict[str, Any]]:
|
||||
"""Yield JSON payloads from an SSE byte stream, including an unterminated last frame."""
|
||||
|
||||
data_lines: list[str] = []
|
||||
|
||||
def flush() -> dict[str, Any] | None:
|
||||
if not data_lines:
|
||||
return None
|
||||
joined = "\n".join(data_lines)
|
||||
data_lines.clear()
|
||||
try:
|
||||
parsed = json.loads(joined)
|
||||
except json.JSONDecodeError:
|
||||
return None
|
||||
return parsed if isinstance(parsed, dict) else None
|
||||
|
||||
for raw_line in lines:
|
||||
line = raw_line.decode("utf-8", errors="replace").rstrip("\r\n")
|
||||
if not line:
|
||||
payload = flush()
|
||||
if payload is not None:
|
||||
yield payload
|
||||
continue
|
||||
if line.startswith("data:"):
|
||||
data_lines.append(line[5:].lstrip(" "))
|
||||
|
||||
payload = flush()
|
||||
if payload is not None:
|
||||
yield payload
|
||||
|
||||
|
||||
def normalize_agui_event(payload: dict[str, Any], *, thread_id: str, run_id: str) -> dict[str, Any] | None:
|
||||
"""Convert an upstream AG-UI event to the stable, UI-friendly event contract."""
|
||||
|
||||
event_type = str(payload.get("type") or "")
|
||||
message_id = str(payload.get("message_id") or payload.get("messageId") or "")
|
||||
delta = payload.get("delta")
|
||||
text_delta = delta if isinstance(delta, str) else ""
|
||||
|
||||
if event_type == "RUN_STARTED":
|
||||
return {"type": "run_started", "threadId": thread_id, "runId": run_id}
|
||||
if event_type == "THINKING_TEXT_MESSAGE_START":
|
||||
return {"type": "thinking_start", "messageId": message_id}
|
||||
if event_type == "THINKING_TEXT_MESSAGE_CONTENT":
|
||||
return {"type": "thinking_delta", "messageId": message_id, "delta": text_delta}
|
||||
if event_type == "THINKING_TEXT_MESSAGE_END":
|
||||
return {"type": "thinking_end", "messageId": message_id}
|
||||
if event_type == "TEXT_MESSAGE_START":
|
||||
return {"type": "answer_start", "messageId": message_id}
|
||||
if event_type == "TEXT_MESSAGE_CONTENT":
|
||||
return {"type": "answer_delta", "messageId": message_id, "delta": text_delta}
|
||||
if event_type == "TEXT_MESSAGE_END":
|
||||
return {"type": "answer_end", "messageId": message_id}
|
||||
if event_type == "RUN_FINISHED":
|
||||
return {"type": "run_finished", "threadId": thread_id, "runId": run_id}
|
||||
if event_type == "RUN_ERROR":
|
||||
message = str(payload.get("message") or "舆情分析服务返回错误。")
|
||||
raise SentimentAgentError(message)
|
||||
return None
|
||||
|
||||
|
||||
def stream_events(config: dict[str, Any], payload: dict[str, Any]) -> Iterator[dict[str, Any]]:
|
||||
"""Call the configured gateway and yield normalized events as soon as they arrive."""
|
||||
|
||||
verify_tls = bool(config.get("verify_tls", True))
|
||||
timeout_seconds = float(config.get("timeout_seconds", 300))
|
||||
if timeout_seconds <= 0:
|
||||
raise SentimentAgentError("timeout_seconds 必须大于 0。")
|
||||
|
||||
request = Request(
|
||||
str(config["api_url"]),
|
||||
data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
|
||||
headers=build_headers(config),
|
||||
method="POST",
|
||||
)
|
||||
ssl_context = ssl.create_default_context() if verify_tls else ssl._create_unverified_context()
|
||||
opener = build_opener(HTTPSHandler(context=ssl_context))
|
||||
try:
|
||||
with opener.open(request, timeout=timeout_seconds) as response:
|
||||
for upstream in parse_sse_payloads(response):
|
||||
normalized = normalize_agui_event(
|
||||
upstream,
|
||||
thread_id=str(payload["threadId"]),
|
||||
run_id=str(payload["runId"]),
|
||||
)
|
||||
if normalized is not None:
|
||||
yield normalized
|
||||
except HTTPError as exc:
|
||||
raise SentimentAgentError(f"舆情分析服务请求失败(HTTP {exc.code})。") from exc
|
||||
except URLError as exc:
|
||||
raise SentimentAgentError("无法连接舆情分析服务,请检查接口地址和网络。") from exc
|
||||
except TimeoutError as exc:
|
||||
raise SentimentAgentError("舆情分析服务响应超时。") from exc
|
||||
|
||||
|
||||
def write_ndjson(events: Iterable[dict[str, Any]]) -> None:
|
||||
"""Write every normalized event immediately for real-time consumers."""
|
||||
|
||||
reasoning = ""
|
||||
answer = ""
|
||||
for event in events:
|
||||
if event["type"] == "thinking_delta":
|
||||
reasoning += str(event.get("delta") or "")
|
||||
elif event["type"] == "answer_delta":
|
||||
answer += str(event.get("delta") or "")
|
||||
print(json.dumps(event, ensure_ascii=False), flush=True)
|
||||
print(json.dumps({"type": "done", "reasoning": reasoning, "answer": answer}, ensure_ascii=False), flush=True)
|
||||
|
||||
|
||||
def write_markdown(events: Iterable[dict[str, Any]]) -> None:
|
||||
"""Collect the stream for a normal chat-friendly Markdown result."""
|
||||
|
||||
reasoning = ""
|
||||
answer = ""
|
||||
for event in events:
|
||||
if event["type"] == "thinking_delta":
|
||||
reasoning += str(event.get("delta") or "")
|
||||
elif event["type"] == "answer_delta":
|
||||
answer += str(event.get("delta") or "")
|
||||
if reasoning:
|
||||
print("<details><summary>分析过程</summary>\n\n" + reasoning + "\n\n</details>\n")
|
||||
print(answer or "舆情分析服务未返回正文。")
|
||||
|
||||
|
||||
def parse_args() -> argparse.Namespace:
|
||||
parser = argparse.ArgumentParser(description="调用舆情分析 AG-UI 流式网关。")
|
||||
parser.add_argument("--question", required=True, help="本轮需要分析的问题。")
|
||||
parser.add_argument("--thread-id", default=f"sentiment-{uuid.uuid4()}", help="会话标识,默认自动生成。")
|
||||
parser.add_argument("--run-id", default=f"run-{uuid.uuid4()}", help="运行标识,默认自动生成。")
|
||||
parser.add_argument("--messages-file", type=Path, help="可选的历史消息 JSON 文件。")
|
||||
parser.add_argument("--config", type=Path, default=DEFAULT_CONFIG_PATH, help="网关配置 JSON 文件。")
|
||||
parser.add_argument("--format", choices=("ndjson", "markdown"), default="ndjson", help="输出格式,默认 ndjson。")
|
||||
return parser.parse_args()
|
||||
|
||||
|
||||
def main() -> int:
|
||||
args = parse_args()
|
||||
try:
|
||||
config = load_config(args.config)
|
||||
payload = build_payload(
|
||||
thread_id=args.thread_id,
|
||||
run_id=args.run_id,
|
||||
question=args.question,
|
||||
history=load_history(args.messages_file),
|
||||
)
|
||||
events = stream_events(config, payload)
|
||||
if args.format == "markdown":
|
||||
write_markdown(events)
|
||||
else:
|
||||
write_ndjson(events)
|
||||
return 0
|
||||
except SentimentAgentError as exc:
|
||||
if args.format == "ndjson":
|
||||
print(json.dumps({"type": "error", "message": str(exc)}, ensure_ascii=False), flush=True)
|
||||
else:
|
||||
print(f"舆情分析调用失败:{exc}", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Reference in new issue
Block a user