union-py-app-stream-chat 1.0.0

package/README.md

@@ -0,0 +1,85 @@
+# GLM 运维智能助手 (OpsAssistant)
+
+基于智谱 GLM 大模型的运维平台运行表现问答服务。
+
+## 项目结构
+
+```
+glm-ops-assistant/
+├── config/
+│   └── config.yaml              # 配置文件（API Key、模型参数、过滤规则等）
+├── src/
+│   ├── api/
+│   │   └── routes.py            # View 层 - FastAPI 路由接口
+│   ├── service/
+│   │   └── chat_service.py      # Service 层 - 业务逻辑（问题筛选、流程编排）
+│   ├── manager/
+│   │   ├── llm_manager.py       # Manager 层 - GLM SDK 调用封装
+│   │   └── session_manager.py   # Manager 层 - 多轮会话管理
+│   ├── core/
+│   │   └── config_loader.py     # 核心工具 - 配置加载（支持环境变量覆盖）
+│   └── models/
+│       └── schemas.py           # Pydantic 数据模型
+├── tests/
+│   └── test_chat_service.py     # 单元测试
+├── main.py                      # 服务入口
+├── requirements.txt             # 依赖清单
+└── README.md
+```
+
+## 快速开始
+
+### 1. 安装依赖
+
+```bash
+pip install -r requirements.txt
+```
+
+### 2. 配置
+
+编辑 `config/config.yaml`，填入你的 GLM API Key：
+
+```yaml
+llm:
+  api_key: "your-api-key-here"
+  model: "glm-4-flash"
+```
+
+或通过环境变量覆盖：
+
+```bash
+export LLM_API_KEY="your-api-key"
+export LLM_MODEL="glm-4-flash"
+```
+
+### 3. 启动服务
+
+```bash
+uvicorn main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+启动后访问文档：`http://localhost:8000/docs`
+
+## API 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/api/v1/chat` | 普通对话（非流式） |
+| POST | `/api/v1/chat/stream` | 流式对话（SSE） |
+| POST | `/api/v1/session/clear` | 清空会话历史 |
+| GET | `/api/v1/session/info` | 获取会话信息 |
+| GET | `/api/v1/health` | 健康检查 |
+
+## 多轮对话
+
+通过 `session_id` 标识会话，系统自动维护上下文历史。历史记录保存在内存中，支持 TTL 过期清理。
+
+## 问题筛选
+
+服务会自动判断用户问题是否与**系统运行表现**相关（CPU、内存、磁盘、网络、告警、故障等）。
+
+不符合条件的问题会被直接拒绝，返回预设提示语。筛选关键词和提示语可在 `config.yaml` 中自定义。
+
+## 流式输出
+
+调用 `/api/v1/chat/stream` 接口，服务端使用 SSE 协议逐字推送模型生成内容。

package/config/config.example.yaml

@@ -0,0 +1,60 @@
+# GLM 运维助手配置文件示例
+
+llm:
+  api_key: "your-api-key-here"
+  model: "glm-4.7-flash"
+  base_url: "https://open.bigmodel.cn/api/paas/v4/"
+  max_tokens: 4096
+  temperature: 0.7
+  top_p: 0.9
+
+system:
+  name: "Uops-Assistant"
+  description: "联合运维智能客服"
+  system_prompt: |
+    你是网络支付清算平台（网联平台）联合运维的智能客服助手，面向联合运维成员单位（银行、支付机构等）提供咨询与指引服务。
+    回答时应准确引用《网络支付清算平台联合运维运行实践指引V1.0》中的具体指标阈值和处置策略，用专业但易懂的语言回复。
+
+filter:
+  enabled: true
+  allowed_keywords:
+    - "网联"
+    - "联合运维"
+    - "运维"
+    - "生产变更"
+    - "变更"
+    - "生产运行"
+    - "运行"
+    - "系统成功率"
+    - "业务成功率"
+    - "异常"
+    - "故障"
+    - "定级"
+    - "关闭渠道"
+    - "联合处置"
+    - "大型单位"
+    - "中型单位"
+    - "小型单位"
+    - "银行"
+    - "支付"
+    - "清算"
+  rejection_message: "抱歉，我是联合运维智能客服，只能回答与联合运维相关的问题，例如生产变更、生产运行、故障定级、周期评价、业务范围等。请重新描述您的问题。"
+
+tools:
+  api_base: "http://localhost:3000/api"
+  max_rounds: 5
+
+rag:
+  enabled: true
+  knowledge_dir: "knowledge"
+  persist_dir: ".chroma"
+  collection: "ops_knowledge"
+  embedding_model: "embedding-3"
+  embedding_max_chars: 6000
+  top_k: 5
+  chunk_size: 1200
+  rebuild_on_startup: false
+
+session:
+  max_history: 20
+  ttl_seconds: 3600

package/knowledge/files/scenario-netunion-runtime-risk-v1.md

@@ -0,0 +1,111 @@
+---
+kb_id: "scenario-netunion-runtime-risk-v1"
+title: "网络支付清算平台生产运行风险场景"
+doc_type: "scenario"
+domain: "联合运维"
+business_modules: ["签约", "解约", "快捷支付", "付款", "退款", "代收", "网关支付"]
+source_doc: "网络支付清算平台联合运维运行实践指引V1.0.md"
+source_version: "V1.0"
+source_section: "5.2.1 存在运行风险"
+effective_date: ""
+owner: "联合运维知识库"
+confidentiality: "内部"
+risk_level: "medium"
+applicable_roles: ["网联平台", "异常方", "影响方", "成员单位"]
+tags: ["生产运行", "运行风险", "系统成功率", "业务成功率", "平均耗时", "交易请求数量", "带宽容量"]
+status: "active"
+---
+
+# 网络支付清算平台生产运行风险场景
+
+## 1. 适用范围
+
+本条目适用于网络支付清算平台联合运维覆盖的生产运行场景。当生产运行中出现风险隐患，但尚未扩大为明确业务异常时，用于判断是否触发风险关注和排查处置。
+
+适用业务包括签约、解约、快捷支付、付款、退款、代收、网关支付等主要业务。
+
+## 2. 场景定义
+
+“存在运行风险”是指相关运行指标已经出现异常趋势，异常方应重点关注并尽快排查。如果风险持续出现、间歇性多次出现，或异常影响迅速扩大，应升级到业务异常场景进行处置。
+
+## 3. 触发条件
+
+符合下列任意一项指标，即触发“存在运行风险”处置策略。
+
+| 指标 | 大型单位 | 中型单位 | 小型单位 | 持续时间 | 是否系统决策指标 |
+| --- | --- | --- | --- | --- | --- |
+| 平均系统成功率 | `<99.99%` 且系统失败笔数 `>100` | `<99.99%` 且系统失败笔数 `>50` | `<99.99%` 且系统失败笔数 `>10` | `5min` | 是 |
+| 业务成功率 | 与前一分钟正常情况相比下降幅度 `>20%` | 与前一分钟正常情况相比下降幅度 `>20%` | 与前一分钟正常情况相比下降幅度 `>20%` | 无固定持续时间 | 否，参考指标 |
+| 平均耗时 | `>=1000ms` | `>=1000ms` | 未规定 | `2min` | 是 |
+| 交易请求数量 | 与前一分钟正常情况相比下降幅度 `>20%` | 与前一分钟正常情况相比下降幅度 `>20%` | 与前一分钟正常情况相比下降幅度 `>20%` | 无固定持续时间 | 否，参考指标 |
+| 带宽容量 | `>60%` | `>60%` | `>60%` | 无固定持续时间 | 预警指标 |
+
+说明：业务成功率和交易请求数量为参考指标，不作为系统自动决策指标。当场景触达参考指标时，应先与相关方排查确认，再进行处置。
+
+## 4. 处置策略
+
+| 角色 | 处置要求 | 风险说明 |
+| --- | --- | --- |
+| 异常方 | 重点关注相关指标，尽快排查原因，消除运行风险 | 查询、排查类动作可自动辅助；涉及生产变更时需另行确认 |
+| 影响方 | 保持关注，及时同步信息 | 一期仅建议关注和同步，不自动执行降流或关闭渠道 |
+| 网联平台 | 可根据联合运维机制协调异常方和影响方同步信息 | 平台协调动作应保留审计记录 |
+
+## 5. 关联指标
+
+| 指标 | 口径 |
+| --- | --- |
+| 系统失败数量 | 统计时间段内未接收到返回信息，以及系统返回码非 `00000000` 的交易数量总和 |
+| 系统成功率 | `(系统请求数量 - 系统失败数量) / 系统请求数量 * 100%`，保留小数点后 4 位 |
+| 业务成功率 | `(系统请求数量 - 业务失败数量) / 业务请求数量 * 100%`，保留小数点后 4 位 |
+| 平均耗时 | 单笔交易耗时累计总和 / 系统请求数量 |
+
+## 6. 关联函数
+
+一期可关联以下只读查询类函数：
+
+```yaml
+function_name: "query_runtime_metrics"
+display_name: "查询运行指标"
+function_type: "read"
+description: "查询指定业务、机构、时间窗口内的系统成功率、业务成功率、平均耗时、交易请求数量、系统失败数量等运行指标。"
+risk_level: "low"
+requires_confirmation: false
+required_permissions: ["metrics:read"]
+input_schema:
+  business_module: "业务模块，例如快捷支付、退款、付款"
+  org_name: "成员单位名称，可选"
+  org_type: "单位分类，可选：大型单位、中型单位、小型单位"
+  time_range: "查询时间范围，例如最近5分钟、最近30分钟"
+output_schema:
+  system_success_rate: "系统成功率"
+  business_success_rate: "业务成功率"
+  avg_latency_ms: "平均耗时，单位毫秒"
+  request_count: "系统请求数量"
+  system_failed_count: "系统失败数量"
+  bandwidth_usage_rate: "带宽容量占用率"
+```
+
+## 7. 模型回答要求
+
+当用户询问运行风险判断时，模型应：
+
+1. 先识别单位分类、业务模块和时间窗口。
+2. 如果缺少运行指标数据，应建议或调用只读查询函数获取数据。
+3. 判断是否满足任一触发条件。
+4. 区分系统决策指标和参考指标。
+5. 给出异常方、影响方和平台方的处置建议。
+6. 不得直接执行降流、关闭渠道、重启、回滚等生产操作。
+
+## 8. 检索提示
+
+用户可能这样提问：
+
+1. “系统成功率低于 99.99% 算不算风险？”
+2. “平均耗时超过 1 秒要怎么处理？”
+3. “快捷支付成功率下降 20% 是什么级别？”
+4. “带宽超过 60% 是否需要处置？”
+5. “运行风险阶段异常方和影响方分别要做什么？”
+
+## 9. 来源依据
+
+本条目基于《网络支付清算平台联合运维运行实践指引V1.0》第 `5.2.1 存在运行风险` 归纳整理，并引用附录 A 中部分运行指标定义。

package/knowledge/files/severity-netunion-runtime-classification-v1.md

@@ -0,0 +1,112 @@
+---
+kb_id: "severity-netunion-runtime-classification-v1"
+title: "网络支付清算平台运行故障定级规则"
+doc_type: "severity"
+domain: "联合运维"
+business_modules: ["签约", "解约", "快捷支付", "付款", "退款", "代收", "网关支付"]
+source_doc: "网络支付清算平台联合运维运行实践指引V1.0.md"
+source_version: "V1.0"
+source_section: "5.3 运行故障定级；5.4 故障善后处置"
+effective_date: ""
+owner: "联合运维知识库"
+confidentiality: "内部"
+risk_level: "medium"
+applicable_roles: ["网联平台", "异常方", "影响方", "成员单位"]
+tags: ["生产运行", "故障定级", "异常交易笔数", "异常持续时间", "账务调整"]
+status: "active"
+---
+
+# 网络支付清算平台运行故障定级规则
+
+## 1. 适用范围
+
+本条目适用于网络支付清算平台联合运维生产运行过程中，对故障影响程度进行定级，并确定善后处置时限。
+
+## 2. 定级原则
+
+故障定级依据“异常影响”和“异常持续时间”两个维度判断。两个维度之间是“或”的关系，满足其中任意一项即可定级。当同时满足多个故障定级标准时，按最高级别确定故障等级。
+
+## 3. 故障定级标准
+
+| 故障级别 | 单位分类 | 异常影响 | 异常持续时间 |
+| --- | --- | --- | --- |
+| 轻微故障 | 大型单位 | 异常交易笔数 `[1000,25000)` | `<10min` |
+| 轻微故障 | 中型单位 | 异常交易笔数 `[1000,10000)` | `<30min` |
+| 轻微故障 | 小型单位 | 异常交易笔数 `[500,5000)` | `<60min` |
+| 一般故障 | 大型单位 | 异常交易笔数 `[25000,50000)` | `[10min,30min)` |
+| 一般故障 | 中型单位 | 异常交易笔数 `[10000,25000)` | `[30min,60min)` |
+| 一般故障 | 小型单位 | 异常交易笔数 `[5000,10000)` | `[60min,120min)` |
+| 严重故障 | 大型单位 | 异常交易笔数 `>=50000` | `>=30min` |
+| 严重故障 | 中型单位 | 异常交易笔数 `>=25000` | `>=60min` |
+| 严重故障 | 小型单位 | 异常交易笔数 `>=10000` | `>=120min` |
+
+## 4. 善后处置时限
+
+| 故障级别 | 善后处置要求 |
+| --- | --- |
+| 轻微故障 | 应在 1 个自然日内完成账务调整 |
+| 一般故障 | 应在 2 个小时内完成账务调整 |
+| 严重故障 | 应在 30 分钟内完成账务调整 |
+
+说明：对于账务调整，故障方应在处理完成后第一时间与网联平台同步信息，否则视为未及时调整。
+
+## 5. 上报监管参考场景
+
+网联平台将根据相关要求，对以下故障情形按日上报至中国人民银行支付结算司：
+
+| 场景 | 条件 |
+| --- | --- |
+| 场景 1 | 平台或成员机构引起业务影响超过 10 万笔 |
+| 场景 2 | 平台引起的业务影响超过 5 分钟 |
+| 场景 3 | 主要成员机构故障影响超过 10 分钟，含间歇性或未完全恢复 |
+| 场景 4 | 其他成员机构引起业务影响超过 30 分钟，含间歇性或未完全恢复，且故障期间平均系统成功率为日常均值的 50% 以下 |
+| 场景 5 | 其余触发舆情影响的安全事件 |
+
+## 6. 关联函数
+
+一期可关联以下只读查询类函数：
+
+```yaml
+function_name: "query_incident_impact"
+display_name: "查询故障影响"
+function_type: "read"
+description: "查询指定业务、机构、时间窗口内的异常交易笔数、异常持续时间和成功率变化，用于辅助故障定级。"
+risk_level: "low"
+requires_confirmation: false
+required_permissions: ["incident:read", "metrics:read"]
+input_schema:
+  business_module: "业务模块"
+  org_name: "成员单位名称"
+  org_type: "单位分类"
+  time_range: "故障或异常时间范围"
+output_schema:
+  abnormal_transaction_count: "异常交易笔数"
+  abnormal_duration_minutes: "异常持续时间，单位分钟"
+  avg_system_success_rate: "故障期间平均系统成功率"
+  suggested_severity: "按规则计算出的建议故障级别"
+```
+
+## 7. 模型回答要求
+
+当用户要求判断故障级别时，模型应：
+
+1. 明确单位分类是大型、中型还是小型。
+2. 获取或询问异常交易笔数和异常持续时间。
+3. 按“异常影响或异常持续时间满足其一即可定级”的规则判断。
+4. 若多个条件命中不同级别，按最高级别输出。
+5. 同时给出账务调整时限和是否可能触发监管上报参考场景。
+6. 不得仅凭主观描述定级，缺少关键数据时应说明需要补充。
+
+## 8. 检索提示
+
+用户可能这样提问：
+
+1. “异常交易 3 万笔算什么故障？”
+2. “大型单位异常持续 15 分钟是什么级别？”
+3. “一般故障要多久完成账务调整？”
+4. “严重故障的判断标准是什么？”
+5. “影响超过 10 万笔是否需要上报？”
+
+## 9. 来源依据
+
+本条目基于《网络支付清算平台联合运维运行实践指引V1.0》第 `5.3 运行故障定级` 和第 `5.4 故障善后处置` 归纳整理。

package/knowledge//350/201/224/345/220/210/350/277/220/347/273/264/347/237/245/350/257/206/345/272/223/345/273/272/347/253/213/350/247/204/350/214/203.md

@@ -0,0 +1,272 @@
+# 联合运维知识库建立规范
+
+## 1. 建设目标
+
+联合运维知识库用于支撑运维智能助手在一期阶段完成“只读问答 + 查询类 Function Call”的能力建设。知识库应帮助系统准确识别用户问题所属的业务模块、运行场景、风险等级、处置策略、可用查询能力和引用依据。
+
+一期知识库的核心目标如下：
+
+1. 支持 RAG 检索识别业务场景和业务模块。
+2. 支持大模型基于权威资料回答运维制度、指标阈值、处置策略、故障定级等问题。
+3. 支持大模型理解可用的查询类 Function Call，但不直接执行变更类动作。
+4. 支持检索结果可追溯到原始文档、章节和版本。
+5. 支持后续扩展到诊断类、操作类和审批类能力。
+
+## 2. 文档分类
+
+知识库文档按内容类型分为以下几类：
+
+| 类型 | 编码前缀 | 说明 | 示例 |
+| --- | --- | --- | --- |
+| 业务模块 | `biz` | 描述业务范围、业务链路、参与方、上下游依赖 | 快捷支付、退款、付款 |
+| 运行场景 | `scenario` | 描述生产运行风险、业务异常、关闭渠道、恢复等场景 | 成功率下降、耗时升高 |
+| 处置策略 | `sop` | 描述不同角色在不同场景下应采取的动作 | 异常方排查、影响方降流 |
+| 指标规则 | `metric` | 描述指标定义、阈值、计算口径 | 系统成功率、平均耗时 |
+| 故障定级 | `severity` | 描述故障等级、触发条件、善后要求 | 轻微、一般、严重 |
+| 变更管理 | `change` | 描述生产变更评估、通知、异常处置、质量评价 | 变更影响评估 |
+| 函数说明 | `function` | 描述可调用函数的用途、参数、权限、返回值 | 查询告警、查询指标 |
+| 评价规则 | `evaluation` | 描述周期评价对象、周期、指标、权重和定级 | 周/月/年评价 |
+
+## 3. 单篇知识文档格式
+
+每个知识条目建议使用 Markdown 文件保存，并使用 YAML Front Matter 描述元数据。正文结构应稳定，便于切分、检索和展示。
+
+```markdown
+---
+kb_id: "scenario-netunion-runtime-risk-v1"
+title: "网络支付清算平台生产运行风险场景"
+doc_type: "scenario"
+domain: "联合运维"
+business_modules: ["签约", "解约", "快捷支付", "付款", "退款", "代收", "网关支付"]
+source_doc: "网络支付清算平台联合运维运行实践指引V1.0.md"
+source_version: "V1.0"
+source_section: "5.2.1 存在运行风险"
+effective_date: ""
+owner: "联合运维知识库"
+confidentiality: "内部"
+risk_level: "low"
+applicable_roles: ["网联平台", "异常方", "影响方", "成员单位"]
+tags: ["生产运行", "风险", "系统成功率", "平均耗时", "带宽"]
+status: "active"
+---
+
+# 标题
+
+## 1. 适用范围
+
+## 2. 触发条件
+
+## 3. 处置策略
+
+## 4. 关联指标
+
+## 5. 关联函数
+
+## 6. 检索提示
+
+## 7. 来源依据
+```
+
+## 4. 元数据规范
+
+| 字段 | 必填 | 说明 | 示例 |
+| --- | --- | --- | --- |
+| `kb_id` | 是 | 全局唯一 ID，建议使用英文、数字和短横线 | `severity-netunion-runtime-v1` |
+| `title` | 是 | 知识条目标题 | `运行故障定级规则` |
+| `doc_type` | 是 | 文档分类 | `severity` |
+| `domain` | 是 | 所属领域 | `联合运维` |
+| `business_modules` | 是 | 适用业务模块，可为空数组但字段必须存在 | `["快捷支付", "退款"]` |
+| `source_doc` | 是 | 来源文档文件名 | `网络支付清算平台联合运维运行实践指引V1.0.md` |
+| `source_version` | 是 | 来源版本 | `V1.0` |
+| `source_section` | 是 | 来源章节 | `5.3 运行故障定级` |
+| `effective_date` | 否 | 生效日期，未知可留空 | `2026-01-01` |
+| `owner` | 是 | 维护责任方 | `联合运维知识库` |
+| `confidentiality` | 是 | 密级 | `内部` |
+| `risk_level` | 是 | 知识对应的操作风险 | `low` |
+| `applicable_roles` | 是 | 适用角色 | `["异常方", "影响方"]` |
+| `tags` | 是 | 检索标签 | `["故障", "定级"]` |
+| `status` | 是 | 状态 | `active` |
+
+`risk_level` 建议枚举：
+
+| 值 | 含义 | 一期处理策略 |
+| --- | --- | --- |
+| `low` | 查询、解释、制度说明 | 可直接回答或调用只读函数 |
+| `medium` | 诊断建议、影响判断 | 可回答，可建议查询，不自动变更 |
+| `high` | 涉及降流、关停、重启、扩容、回滚 | 一期只给建议，不执行 |
+| `critical` | 涉及生产高危或不可逆动作 | 必须转人工审批 |
+
+## 5. 正文内容规范
+
+### 5.1 适用范围
+
+说明该知识条目适用于哪些业务、系统、角色和场景。范围要明确，避免出现“所有情况均适用”这类模糊表述。
+
+### 5.2 触发条件
+
+凡是涉及阈值、时间、比例、数量的内容，必须结构化表达。建议使用表格。
+
+示例：
+
+| 指标 | 大型单位 | 中型单位 | 小型单位 | 持续时间 | 是否决策指标 |
+| --- | --- | --- | --- | --- | --- |
+| 平均系统成功率 | `<99.99% 且系统失败笔数 >100` | `<99.99% 且系统失败笔数 >50` | `<99.99% 且系统失败笔数 >10` | `5min` | 是 |
+
+### 5.3 处置策略
+
+处置策略必须按角色拆分，至少区分：
+
+1. 平台方。
+2. 异常方。
+3. 影响方。
+4. 变更发起方。
+5. 变更影响方。
+
+动作应使用明确动词，例如“通知”“排查”“同步”“降流”“暂停发送”“灰度恢复”。涉及高风险动作时，必须标记“需人工确认”。
+
+### 5.4 关联指标
+
+指标必须引用统一指标口径。指标定义应尽量沉淀为独立 `metric` 条目，业务条目中只引用。
+
+常见指标包括：
+
+1. 系统请求数量。
+2. 系统失败数量。
+3. 业务失败数量。
+4. 系统成功率。
+5. 业务成功率。
+6. 平均耗时。
+7. 正常服务时间。
+8. 异常持续时间。
+
+### 5.5 关联函数
+
+一期只登记查询类函数。函数说明可以进入知识库，但执行权限由 Function Call 层控制。
+
+函数说明建议格式：
+
+```yaml
+function_name: "query_runtime_metrics"
+display_name: "查询运行指标"
+function_type: "read"
+description: "查询指定业务、机构、时间窗口内的系统成功率、业务成功率、平均耗时和交易量。"
+risk_level: "low"
+requires_confirmation: false
+required_permissions: ["metrics:read"]
+input_schema:
+  business_module: "业务模块，例如快捷支付、退款"
+  org_type: "单位分类，例如大型单位、中型单位、小型单位"
+  time_range: "查询时间范围"
+output_schema:
+  system_success_rate: "系统成功率"
+  business_success_rate: "业务成功率"
+  avg_latency_ms: "平均耗时"
+  request_count: "系统请求数量"
+  failed_count: "系统失败数量"
+```
+
+### 5.6 检索提示
+
+为提升 RAG 命中率，每篇知识条目应维护自然语言检索提示，包括用户可能的问法。
+
+示例：
+
+1. “系统成功率低于多少算运行风险？”
+2. “平均耗时超过 2 秒要怎么处理？”
+3. “大型单位异常交易多少笔需要升级？”
+
+### 5.7 来源依据
+
+必须记录来源文档、版本和章节。若为人工总结，应标明“基于来源章节归纳”，避免将推理内容伪装成原文。
+
+## 6. 内容切分规范
+
+为了兼顾召回准确性和上下文完整性，建议按“一个知识点一条文档”的方式切分。
+
+切分原则：
+
+1. 一个场景一条，例如“存在运行风险”“出现业务异常-联合处置”“出现业务异常-关闭渠道”。
+2. 一个规则一条，例如“运行故障定级”“故障善后处置”。
+3. 一个函数一条，例如“查询运行指标函数说明”。
+4. 单条正文建议控制在 800 到 1500 个中文字符，复杂表格类条目可适当放宽。
+5. 不要把整份制度原文作为一个向量文档直接入库。
+6. 表格必须保留表头，避免阈值脱离适用对象。
+7. 涉及“或”“且”“大于等于”“小于”等逻辑关系时，必须保留原始逻辑。
+
+## 7. 命名规范
+
+文件名建议格式：
+
+```text
+{doc_type}-{domain_or_system}-{topic}-v{version}.md
+```
+
+示例：
+
+```text
+scenario-netunion-runtime-risk-v1.md
+severity-netunion-runtime-classification-v1.md
+function-netunion-query-runtime-metrics-v1.md
+```
+
+中文标题可以放在 `title` 字段中，文件名建议使用英文，便于程序处理和跨平台同步。
+
+## 8. RAG 入库字段建议
+
+入库时建议至少写入以下字段：
+
+| 字段 | 来源 | 用途 |
+| --- | --- | --- |
+| `content` | Markdown 正文 | 向量检索 |
+| `title` | Front Matter | 展示和关键词检索 |
+| `doc_type` | Front Matter | 检索过滤 |
+| `business_modules` | Front Matter | 业务模块过滤 |
+| `tags` | Front Matter | 关键词召回 |
+| `source_doc` | Front Matter | 溯源 |
+| `source_section` | Front Matter | 溯源 |
+| `risk_level` | Front Matter | 工具调用安全控制 |
+| `applicable_roles` | Front Matter | 角色匹配 |
+| `status` | Front Matter | 过滤废弃条目 |
+
+## 9. 质量校验规范
+
+每条知识入库前应检查：
+
+1. 是否有唯一 `kb_id`。
+2. 是否能追溯到来源文档和章节。
+3. 是否包含适用范围。
+4. 阈值是否保留单位、比较符和持续时间。
+5. 处置策略是否按角色拆分。
+6. 是否标注风险等级。
+7. 是否存在过期或冲突内容。
+8. 是否包含检索提示。
+9. 是否避免把高风险操作描述成可自动执行。
+10. 是否与已有知识条目重复或冲突。
+
+## 10. 一期推荐知识库目录
+
+```text
+trainingDocs/
+  knowledgeBase/
+    联合运维知识库建立规范.md
+    samples/
+      scenario-netunion-runtime-risk-v1.md
+      scenario-netunion-business-exception-joint-handling-v1.md
+      scenario-netunion-business-exception-channel-close-v1.md
+      severity-netunion-runtime-classification-v1.md
+      metric-netunion-runtime-indicators-v1.md
+      function-netunion-query-runtime-metrics-v1.md
+```
+
+一期建议优先沉淀以下条目：
+
+1. 业务范围与单位分类。
+2. 生产运行风险场景。
+3. 业务异常联合处置场景。
+4. 业务异常关闭渠道场景。
+5. 处置升级策略。
+6. 恢复策略。
+7. 运行故障定级。
+8. 故障善后处置。
+9. 运行指标定义。
+10. 查询类函数说明。

package/main.py

@@ -0,0 +1,46 @@
+"""
+GLM 运维助手 - 入口文件
+运行方式:
+    uvicorn main:app --host 0.0.0.0 --port 8000 --reload
+"""
+
+import sys
+from pathlib import Path
+
+# 将项目根目录加入 sys.path，确保无论从哪里启动都能找到 src 包
+PROJECT_ROOT = Path(__file__).parent.resolve()
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from src.api.routes import router
+
+app = FastAPI(
+    title="OpsAssistant",
+    description="运维平台运行表现智能助手 - 基于 GLM 大模型",
+    version="1.0.0",
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(router, prefix="/api/v1")
+
+@app.get("/")
+def root():
+    return {
+        "service": "OpsAssistant",
+        "version": "1.0.0",
+        "docs": "/docs",
+    }
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)