@umacloud/knowledge 1.0.1

package/ai/ai-observability-and-oncall-runbook.md

@@ -0,0 +1,52 @@
+---
+id: ai-observability-and-oncall-runbook
+title: ai-observability-and-oncall-runbook
+domain: ai
+category: ai-observability-and-oncall-runbook.md
+difficulty: intermediate
+tags: [ai, ai可观测性与值班runbook, and, observability, oncall, runbook]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 开发：Excellent（11964948@qq.com）
+
+## AI可观测性与值班Runbook
+
+### 目标
+- 建立AI系统运行态监控、告警、处置、复盘的标准流程。
+
+### 适用范围
+- 适用于AI线上服务、Agent编排服务与RAG检索生成服务。
+
+### 观测指标
+- 质量指标：任务成功率、拒答率、幻觉率、用户满意度。
+- 稳定性指标：错误率、超时率、重试率、可用性。
+- 性能指标：P50/P95时延、工具调用耗时、队列长度。
+- 经济指标：token消耗、单请求成本、预算消耗速率。
+
+### 告警分级
+- P0：大面积不可用、越权风险、成本突增失控。
+- P1：核心指标持续劣化、成功率显著下降。
+- P2：局部场景异常、可降级运行。
+
+### 执行清单
+- 每个核心指标绑定负责人、阈值与处置动作。
+- 每类告警都有首响SLA与升级路径。
+- 值班交接必须包含未闭环告警与临时策略变更。
+
+### 处置清单
+- 先止损：关闭高风险能力或降级到安全兜底。
+- 再定位：按模型、检索、工具、策略层分段排查。
+- 后恢复：灰度恢复并持续观察关键指标。
+
+### 验收标准
+- 重大告警MTTR达到目标。
+- 告警误报率与漏报率有持续下降趋势。
+
+### 常见失败模式
+- 只监控系统指标，不监控AI质量与成本漂移。
+- 告警无分级，值班噪声过多导致真实事故漏检。
+
+### 回滚策略
+- 按开关逐层回退：策略层→路由层→模型层→功能层。
+- 回滚完成后进行复盘并沉淀预防动作。

package/ai/ai-rag-engineering-playbook.md

@@ -0,0 +1,42 @@
+---
+id: ai-rag-engineering-playbook
+title: ai-rag-engineering-playbook
+domain: ai
+category: ai-rag-engineering-playbook.md
+difficulty: intermediate
+tags: [ai, engineering, playbook, rag, rag工程作战手册]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 开发：Excellent（11964948@qq.com）
+
+## AI RAG工程作战手册
+
+### 目标
+- 构建高召回、高精度、低幻觉的检索增强生成系统。
+
+### 适用范围
+- 适用于知识问答、客服助手、内部检索助手和文档智能化场景。
+
+### 核心流程
+- 数据接入：来源可信校验、清洗去噪、结构化切片。
+- 索引构建：Embedding模型评估、分层索引、增量更新。
+- 检索策略：关键词+向量混合检索、重排序、查询改写。
+- 生成控制：引用约束、答案结构化、无证据拒答策略。
+
+### 执行清单
+- 文档分块策略和chunk overlap经过离线评测。
+- 召回率、MRR、NDCG等检索指标具备基线。
+- 生成结果必须可追溯到引用片段与版本。
+
+### 验收标准
+- 高价值问答场景正确率与可解释性达标。
+- 无证据回答比例和幻觉率低于阈值。
+
+### 常见失败模式
+- 文档切块过粗导致召回不准，过细导致语义破碎。
+- 忽略知识库更新延迟，线上内容与实际文档不一致。
+
+### 回滚策略
+- 检索异常时回切到上一个稳定索引快照。
+- 关闭激进查询改写，启用保守检索策略。

package/ai/ai-red-team-and-safety-evaluation.md

@@ -0,0 +1,42 @@
+---
+id: ai-red-team-and-safety-evaluation
+title: ai-red-team-and-safety-evaluation
+domain: ai
+category: ai-red-team-and-safety-evaluation.md
+difficulty: intermediate
+tags: [ai, ai红队测试与安全评估, and, evaluation, red, safety, team]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 开发：Excellent（11964948@qq.com）
+
+## AI红队测试与安全评估
+
+### 目标
+- 在上线前识别提示注入、越权调用、敏感泄漏、内容安全等高风险问题。
+
+### 适用范围
+- 适用于新能力上线前评估、重大变更回归与周期性安全体检。
+
+### 测试维度
+- 提示注入与策略绕过。
+- 工具越权与命令滥用。
+- 数据泄漏与隐私暴露。
+- 有害内容生成与安全边界突破。
+
+### 执行清单
+- 建立高危攻击语料库并持续更新。
+- 对关键路径执行自动化红队回归。
+- 每个高危用例必须定义阻断规则与处置动作。
+
+### 验收标准
+- 高危安全用例通过率达到阈值。
+- 红队阻断策略覆盖关键攻击面。
+
+### 常见失败模式
+- 只做一次性安全测试，缺少版本回归。
+- 对阻断误杀率无监控，导致业务不可用。
+
+### 回滚策略
+- 红队指标恶化时暂停发布并回滚到稳定策略版本。
+- 临时收紧策略阈值并启用人工审核兜底。

package/ai/ai-release-readiness-and-rollback-gate.md

@@ -0,0 +1,42 @@
+---
+id: ai-release-readiness-and-rollback-gate
+title: ai-release-readiness-and-rollback-gate
+domain: ai
+category: ai-release-readiness-and-rollback-gate.md
+difficulty: intermediate
+tags: [ai, ai发布就绪与回滚门禁, and, gate, readiness, release, rollback]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 开发：Excellent（11964948@qq.com）
+
+## AI发布就绪与回滚门禁
+
+### 目标
+- 将AI能力发布纳入可量化门禁，确保上线可控与可回退。
+
+### 适用范围
+- 适用于模型升级、提示词变更、工具链变更和策略变更场景。
+
+### 发布门禁
+- 准确性门禁：核心场景任务成功率达到目标阈值。
+- 安全性门禁：高危攻击用例通过率达到要求。
+- 性能门禁：P95时延与错误率满足SLO。
+- 成本门禁：单请求成本和日预算占比在阈值内。
+
+### 执行清单
+- 灰度流量策略、放量节奏、观察窗口已定义。
+- 功能开关可快速关闭，老版本可快速回切。
+- 发布责任人与应急联系人明确。
+
+### 验收标准
+- 四类门禁全部通过且无阻断缺陷。
+- 发布后观察期内关键指标稳定。
+
+### 常见失败模式
+- 只看离线效果，忽略真实流量下的成本和失败率。
+- 回滚脚本未演练，故障发生时恢复缓慢。
+
+### 回滚策略
+- 任一P0指标越线立即回滚到上一稳定版本。
+- 回滚后冻结变更并触发根因复盘。

package/ai/llm-agent-engineering-deep-dive.md

@@ -0,0 +1,57 @@
+---
+id: llm-agent-engineering-deep-dive
+title: llm-agent-engineering-deep-dive
+domain: ai
+category: llm-agent-engineering-deep-dive.md
+difficulty: intermediate
+tags: [agent, ai, deep, dive, engineering, llm, 工程深度知识库]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 开发：Excellent（11964948@qq.com）
+
+## LLM 与 Agent 工程深度知识库
+
+### 目标
+- 建立可控、可测、可审计的 AI 研发与运行标准。
+
+### 适用范围
+- 适用于基于LLM的Copilot、Agent、RAG与自动化决策系统。
+
+### 架构要点
+- 模型层：模型选择、上下文窗口、成本与延迟权衡。
+- 编排层：任务拆解、工具调用、失败重试、回退策略。
+- 约束层：输入约束、输出结构化、策略护栏、审批节点。
+- 评测层：离线评测、在线评估、回归基准。
+
+### 安全与风险控制
+- 防提示注入与越权工具调用。
+- 外部检索启用域名白名单与来源可信度控制。
+- 敏感操作必须有人审或双重确认。
+- 对模型幻觉设置事实核验与置信度阈值。
+
+### 评测体系
+- 任务成功率、正确率、稳定性、延迟、成本。
+- 对关键流程建立回归题集与基线答案。
+- 每次提示词或工具变更都触发回归评测。
+
+### 运维要求
+- 记录完整调用链：输入摘要、模型版本、工具轨迹、输出结果。
+- 建立异常分层告警：模型失败、工具失败、策略阻断。
+
+### 执行清单
+- 模型、提示词、工具版本均可追踪并可回放。
+- 关键场景离线评测与在线监控双覆盖。
+- 高风险动作具备人工确认与审计记录。
+
+### 验收标准
+- 准确率、安全性、时延、成本达到发布阈值。
+- 线上异常发现与处置链路可在SLO内闭环。
+
+### 常见失败模式
+- 只看单次演示效果，不做持续评测。
+- 工具权限过大，缺少审计与审批。
+
+### 回滚策略
+- 发现策略越权或质量严重退化时立即降级为保守模式。
+- 回切到上一稳定模型与提示词版本并冻结变更。

package/ai/prompt-and-tool-guardrails.md

@@ -0,0 +1,52 @@
+---
+id: prompt-and-tool-guardrails
+title: prompt-and-tool-guardrails
+domain: ai
+category: prompt-and-tool-guardrails.md
+difficulty: intermediate
+tags: [ai, and, guardrails, prompt, tool, 与工具调用护栏规范]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 开发：Excellent（11964948@qq.com）
+
+## Prompt 与工具调用护栏规范
+
+### 目标
+- 防止模型越权操作、错误调用工具或输出不可信内容。
+
+### 适用范围
+- 适用于所有Prompt模板、工具调用策略与Agent动作编排链路。
+
+### Prompt 规范
+- 目标明确：任务边界、输入输出格式、质量要求清晰。
+- 约束明确：禁止动作、敏感数据处理规则、失败回退策略。
+- 证据优先：要求输出依据来源，避免无依据断言。
+
+### 工具调用护栏
+- 权限最小化：按任务授予最少工具集。
+- 参数白名单：限制高风险参数范围。
+- 二次确认：写入、删除、部署类操作必须确认。
+- 审计留痕：记录调用时间、参数摘要、结果状态。
+
+### 失败处理
+- 工具失败时优先降级，不得无限重试。
+- 输出不确定时必须显式说明并请求补充信息。
+- 多次失败触发人工接管流程。
+
+### 执行清单
+- Prompt必须包含目标、边界、格式、拒答与降级规则。
+- 工具权限采用最小化策略并带参数白名单。
+- 高风险动作必须有人审并全量记录审计日志。
+
+### 验收标准
+- 越权调用拦截率和误调用率达到目标阈值。
+- 失败降级路径可用且用户可感知风险提示。
+
+### 常见失败模式
+- Prompt 缺少边界导致模型过度推断。
+- 工具权限过大导致潜在破坏性操作。
+
+### 回滚策略
+- 护栏策略异常时立即切换到保守规则模板。
+- 关闭高风险工具并回退到上一个稳定权限配置。

package/api/01-standards/enterprise-api-standards.md

@@ -0,0 +1,198 @@
+---
+id: enterprise-api-standards
+title: 企业级 API 设计标准（完整版）
+domain: api
+category: 01-standards
+difficulty: advanced
+tags: [api, rest, enterprise, openapi, contract, validation, pagination, error, versioning, security]
+quality_score: 95
+maintainer: platform-team@umadev.com
+last_updated: 2026-06-14
+---
+
+# 企业级 API 设计标准（完整版）
+
+## 资源建模
+
+### 命名约定
+```
+✅ 复数名词: /api/users, /api/orders, /api/products
+✅ 嵌套关系: /api/users/:userId/orders
+❌ 动词路径: /api/getUsers, /api/createOrder
+❌ 单数名词: /api/user, /api/order
+```
+
+### 路径层级
+- 一级：`/api/{resource}` — 集合操作（list / create）
+- 二级：`/api/{resource}/:id` — 单体操作（get / update / delete）
+- 三级：`/api/{resource}/:id/{sub}` — 子资源（`/api/users/:id/orders`）
+- 动作端点：`/api/{resource}/:id/action` — 非 CRUD 操作（`/api/orders/:id/cancel`）
+
+## HTTP 方法语义
+
+| 方法 | 幂等 | 安全 | 语义 | 典型状态码 |
+|------|------|------|------|-----------|
+| GET | ✅ | ✅ | 读取，不改数据 | 200 / 404 |
+| POST | ❌ | ❌ | 创建，非幂等 | 201 / 400 / 409 |
+| PUT | ✅ | ❌ | 完整替换 | 200 / 204 / 404 |
+| PATCH | ❌ | ❌ | 部分更新 | 200 / 404 |
+| DELETE | ✅ | ❌ | 删除 | 204 / 404 |
+
+## 分页（三种策略）
+
+### Offset 分页（简单列表）
+```json
+GET /api/products?page=2&limit=20
+
+Response:
+{
+  "data": [...],
+  "pagination": {
+    "page": 2,
+    "limit": 20,
+    "total": 150,
+    "totalPages": 8
+  }
+}
+```
+
+### Cursor 分页（大数据集 / 实时流）
+```json
+GET /api/events?cursor=eyJpZCI6MTIzfQ&limit=50
+
+Response:
+{
+  "data": [...],
+  "pagination": {
+    "nextCursor": "eyJpZCI6MTczfQ",
+    "hasMore": true
+  }
+}
+```
+
+### Keyset 分页（排序稳定）
+```json
+GET /api/orders?after=2024-01-15T10:30:00Z&limit=20
+```
+
+## 错误处理（统一错误信封）
+
+### 标准错误格式
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "The request was invalid",
+    "details": [
+      { "field": "email", "issue": "must be a valid email address" },
+      { "field": "quantity", "issue": "must be greater than 0" }
+    ],
+    "requestId": "req_abc123",
+    "timestamp": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+### 错误码分类
+| HTTP | error code | 场景 |
+|------|-----------|------|
+| 400 | VALIDATION_ERROR | 请求体校验失败 |
+| 401 | UNAUTHENTICATED | 缺少/无效 token |
+| 403 | FORBIDDEN | 权限不足 |
+| 404 | NOT_FOUND | 资源不存在 |
+| 409 | CONFLICT | 唯一约束冲突 |
+| 422 | UNPROCESSABLE | 业务逻辑校验失败 |
+| 429 | RATE_LIMITED | 超过速率限制 |
+| 500 | INTERNAL_ERROR | 服务器异常 |
+
+## 输入验证
+
+### 每个端点必须有
+```python
+# Python/FastAPI 示例
+from pydantic import BaseModel, EmailStr, constr
+
+class CreateOrderRequest(BaseModel):
+    product_id: str  # required
+    quantity: int = Field(ge=1, le=999)  # 1-999
+    notes: constr(max_length=500) | None = None  # optional, max 500
+```
+
+### 校验层次
+1. **类型校验** — 字段类型正确（string/int/bool）
+2. **格式校验** — email/url/uuid/date 格式
+3. **范围校验** — 数值在合理范围
+4. **业务校验** — 库存够不够、权限对不对
+5. **关联校验** — 外键引用存在
+
+## API 版本化
+
+### URL 路径版本（推荐）
+```
+/api/v1/users
+/api/v2/users
+```
+
+### Header 版本（备选）
+```
+GET /api/users
+Accept-Version: 2.0
+```
+
+### 版本弃用策略
+- 新版本发布时旧版本至少维护 6 个月
+- 响应头标注弃用：`Sunset: Sat, 31 Dec 2024 23:59:59 GMT`
+- `Deprecation: true` 头告知客户端迁移
+
+## 认证与授权
+
+### JWT Bearer Token
+```
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+```
+
+### 端点安全矩阵
+| 端点类型 | 认证 | 授权 |
+|---------|------|------|
+| 公开端点（login/register） | 无 | 无 |
+| 用户数据端点 | JWT | 只能访问自己的数据 |
+| 管理端点 | JWT + admin role | admin only |
+| 内部端点 | API key / mTLS | service-to-service |
+
+## 速率限制
+
+### 响应头
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 87
+X-RateLimit-Reset: 1700000000
+```
+
+### 429 响应
+```json
+{
+  "error": {
+    "code": "RATE_LIMITED",
+    "message": "Too many requests",
+    "retryAfter": 60
+  }
+}
+```
+
+## CORS 配置
+
+```http
+Access-Control-Allow-Origin: https://app.example.com
+Access-Control-Allow-Methods: GET, POST, PATCH, DELETE, OPTIONS
+Access-Control-Allow-Headers: Authorization, Content-Type
+Access-Control-Max-Age: 86400
+```
+
+## OpenAPI 契约要求
+
+每个 API 必须有完整的 OpenAPI 3.1 文档：
+- 每个端点有 `operationId`（唯一标识符）
+- 请求体有 JSON Schema `$ref`
+- 响应有所有可能的状态码 + schema
+- 安全方案明确声明
+- 示例（example）覆盖成功 + 错误场景

package/api/01-standards/rest-api-design-guide.md

@@ -0,0 +1,63 @@
+---
+id: rest-api-design-guide
+title: REST API 设计完全指南
+domain: api
+category: 01-standards
+difficulty: intermediate
+tags: [rest, api, design]
+quality_score: 92
+maintainer: api-team@umadev.com
+last_updated: 2026-03-29
+---
+
+# REST API 设计完全指南
+
+## 核心原则
+
+### 1. 资源命名
+```
+✅ 正确: /users, /orders
+❌ 错误: /getUsers, /createOrder
+```
+
+### 2. HTTP 方法
+- GET: 获取资源
+- POST: 创建资源
+- PUT: 完整更新
+- PATCH: 部分更新
+- DELETE: 删除资源
+
+### 3. 状态码
+- 200: 成功
+- 201: 已创建
+- 400: 请求错误
+- 401: 未授权
+- 403: 禁止访问
+- 404: 未找到
+- 500: 服务器错误
+
+## 实战示例
+
+### 分页
+```python
+@app.get("/users")
+async def list_users(page: int = 1, limit: int = 20):
+    offset = (page - 1) * limit
+    users = db.query(User).offset(offset).limit(limit).all()
+    total = db.query(User).count()
+    
+    return {
+        "data": users,
+        "meta": {"total": total, "page": page}
+    }
+```
+
+### 错误处理
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid email"
+  }
+}
+```

package/api/02-playbooks/api-pagination-playbook.md

@@ -0,0 +1,93 @@
+---
+id: api-pagination-playbook
+title: API 分页实战手册
+domain: api
+category: 02-playbooks
+difficulty: intermediate
+tags: [api, pagination, cursor, offset, performance, database, query, limit, offset]
+quality_score: 90
+maintainer: platform-team@umadev.com
+last_updated: 2026-06-14
+---
+
+# API 分页实战手册
+
+## 何时用哪种分页
+
+### Offset 分页（默认选择）
+适用：中小数据集（< 10 万行），用户需要跳页。
+
+```sql
+-- PostgreSQL
+SELECT * FROM products ORDER BY created_at DESC LIMIT 20 OFFSET 40;
+```
+
+问题：OFFSET 大时性能下降（数据库仍扫描跳过的行）。
+
+### Cursor 分页（大数据集）
+适用：时间线 / feed / 日志 / 事件流。
+
+```sql
+-- 用 WHERE 而非 OFFSET，利用索引
+SELECT * FROM events
+WHERE created_at < '2024-01-15T10:30:00Z'
+ORDER BY created_at DESC LIMIT 50;
+```
+
+cursor 编码：`base64(last_item.created_at + ':' + last_item.id)`。
+
+### Keyset 分页（排序稳定）
+适用：按唯一字段排序的大列表。
+
+```sql
+SELECT * FROM orders WHERE id > 12345 ORDER BY id LIMIT 20;
+```
+
+## 分页响应格式
+
+```json
+{
+  "data": [...],
+  "pagination": {
+    "page": 2,
+    "limit": 20,
+    "total": 1500,
+    "totalPages": 75,
+    "hasNext": true,
+    "hasPrev": true
+  }
+}
+```
+
+## 常见陷阱
+
+### 1. 忘记 total count
+```python
+# ❌ 只返回数据，客户端无法显示总页数
+return {"data": users}
+
+# ✅ 带 total
+return {"data": users, "pagination": {"total": total, ...}}
+```
+
+### 2. 默认 limit 过大
+```python
+# ❌ 默认返回全部
+@app.get("/users")
+def list_users(limit=None):
+    return db.query(User).limit(limit).all()
+
+# ✅ 默认 + 上限
+@app.get("/users")
+def list_users(limit: int = Field(default=20, le=100)):
+    return db.query(User).limit(limit).all()
+```
+
+### 3. 排序不稳定
+```sql
+-- ❌ 只按 created_at 排序，相同时间戳顺序不确定
+SELECT * FROM products ORDER BY created_at LIMIT 20;
+
+-- ✅ 加唯一字段做 tiebreaker
+SELECT * FROM products ORDER BY created_at DESC, id DESC LIMIT 20;
+```