102 lines
3.7 KiB
Markdown
102 lines
3.7 KiB
Markdown
# 舆情分析技能：安装与调用说明
|
||
|
||
## 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。
|