# 舆情分析技能：安装与调用说明

## 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。