docs: 规则分离到 roles 目录
This commit is contained in:
@@ -2,10 +2,14 @@
|
||||
|
||||
> TypeScript + Fastify 独立 AI 服务,集成 DeepSeek LLM,为后端提供异步 AI 任务。
|
||||
|
||||
## Git 提交规范
|
||||
## 规则与技能位置
|
||||
|
||||
- 提交信息必须简短且使用中文,不要使用英文长句。
|
||||
- 格式:`类型: 简述`,例如 `feat: 新增思维导图生成任务`、`fix: 修复任务队列TTL清理`、`docs: 补充环境变量说明`。
|
||||
- 通用规则(跨仓库):meta 仓库 `.agents/roles/`
|
||||
- 本仓库专属规则:`roles/`
|
||||
- `roles/task-queue.md`:任务队列设计(含「不要改动的契约」)
|
||||
- `roles/security-and-degradation.md`:安全边界与降级策略
|
||||
- 本仓库专属技能:本仓库暂无专属技能目录
|
||||
- Git 提交规范属通用规则,见 meta 仓库 `.agents/roles/commit-convention.md`,本文件不再重复。
|
||||
|
||||
## 技术栈
|
||||
|
||||
@@ -51,29 +55,6 @@ lpt-ai/src/
|
||||
| `generate-mind-map` | 从报告/残片生成思维导图大纲 | 0.3 | 4096 |
|
||||
| `compare-recall` | 用户回忆 vs 标准导图语义对比 | 0.2 | 4096 |
|
||||
|
||||
## 任务队列设计
|
||||
|
||||
- 异步任务模式:submit + poll,避免 LLM 长耗时(10-60s)超时。
|
||||
- **Worker 池**:并发度由 `LPT_AI_CONCURRENCY` 控制(默认 2)。
|
||||
不要改回单 worker 串行:N 个请求会等 N × LLM 耗时,客户端会先超时。
|
||||
- **退避重试**:429 / 5xx / 超时等瞬时抖动会重试(`LPT_AI_MAX_ATTEMPTS`,默认 3),
|
||||
4xx 客户端错误与「API Key 未配置」不重试。服务端返回的 `Retry-After` 优先于自算退避。
|
||||
- **相同输入复用**:以 `type + params` 的稳定哈希为幂等键。
|
||||
- 同键任务 pending/running → 合并为同一个任务,不重复调用 LLM(不重复计费)
|
||||
- 同键任务已完成且在 `LPT_AI_RESULT_CACHE_MS` 窗口内 → 复用结果
|
||||
- 同键任务已失败 → 新建(失败必须可重试)
|
||||
- 请求体传 `force: true` 可跳过复用(用户主动「重新生成」)
|
||||
- 也可传 `idempotencyKey` 显式指定幂等键
|
||||
- TTL 清理:按 `LPT_AI_CLEANUP_MS` 周期移除过期记录,同时清理幂等索引。
|
||||
- 异常隔离:单个任务失败不影响后续任务。
|
||||
- 管理面板日志:复用 `logStore`,记录最近 200 条请求/响应。
|
||||
|
||||
### 不要改动的契约
|
||||
|
||||
- `/ai/tasks` **必须固定返回 201**。Java 端 `AiServiceClient.submitTask()` 把非 201 视为提交失败,
|
||||
所以不能用 200 表达「复用了已有任务」;复用信息放在响应体的 `reused` / `status` 字段里。
|
||||
- `TaskRecord` 的 `status` / `result` / `error` 字段名被 Java 端轮询逻辑依赖,新增字段可以,改名不行。
|
||||
|
||||
## LLM 配置
|
||||
|
||||
```env
|
||||
@@ -100,27 +81,6 @@ LPT_AI_FETCH_ALLOWED_PORTS= # 抓取允许的额外端口(默认只有 80/
|
||||
|
||||
> 部署侧的变量在 `lpt-infra` 的 `dev/`、`prod/` configmap 里;本服务只读环境变量,默认值写在 `src/llm/client.ts` 与 `loadQueueConfig()` 里。
|
||||
|
||||
## 安全边界
|
||||
|
||||
本服务是 `ClusterIP` 且未被 Traefik 路由,公网不可达;但集群内任何工作负载都能访问它,因此仍有防护:
|
||||
|
||||
- **入站令牌(可选)**:设置 `LPT_AI_TOKEN` 后,`/ai/*` 与 `/admin` 都要求携带(header `x-api-token` 或 query `token`)。
|
||||
部署清单用 `secretKeyRef.optional: true` 引用 `lpt-secrets/lpt-ai-token`,**没设这个 key 也能正常启动**(此时不校验)。
|
||||
`lpt-be` 侧由 `lpt.ai-service.token` 提供,部署经 `LPT_AI-SERVICE_TOKEN` 注入。
|
||||
开发阶段可以不设,保持零摩擦;生产只需往 secret 加一个 key。
|
||||
- **限流**:`/ai/tasks` 按来源限流(默认 30 次/分钟),因为是单进程内存计数,属于粗粒度保护,不是精确配额。
|
||||
- **抓取加固**:`/fetch-title` 的目标由调用方给出,抓取前做四层校验 —— 协议白名单、端口白名单、**DNS 解析后逐个校验**(防解析到内网与 DNS rebinding)、**重定向逐跳校验**(防「首跳合法、次跳内网」);响应体截断到 512 KiB,且只在网页类型上取标题。
|
||||
- `/admin` 面板会展示完整 prompt 与学习内容,未设置令牌时会启动告警提示。
|
||||
|
||||
> `/fetch-title` 当前**全工作区零调用**(`lpt-fe` 走的是 `lpt-be` 的 `/utils/fetch-title`,用 Java 侧 `TitleFetcher`)。
|
||||
> 保留它是为了满足安全条目的验收;如需精简可连同本文件的抓取工具一并删除。
|
||||
|
||||
## 降级策略
|
||||
|
||||
- LLM API Key 未配置 → `/health` 返回 `llmAvailable: false`。
|
||||
- 后端(lpt-be)检测到 AI 不可用 → 自动切换到内置规则引擎(`BuiltinMindMapGenerator`)。
|
||||
- Java 后端是唯一调用方;本服务不直接暴露给前端(Service 是 `ClusterIP`,且 Traefik 未路由本服务)。
|
||||
|
||||
## 启动命令
|
||||
|
||||
```bash
|
||||
|
||||
@@ -0,0 +1,25 @@
|
||||
# 安全边界与降级策略
|
||||
|
||||
- **功能**:说明 lpt-ai 的入站令牌、限流、抓取加固、`/admin` 暴露边界,以及 LLM 不可用时的降级路径。
|
||||
- **何时用**:改动鉴权、限流、`/fetch-title` 抓取逻辑、`/admin` 暴露范围,或处理 LLM 不可用 / 降级行为时。
|
||||
|
||||
## 安全边界
|
||||
|
||||
本服务是 `ClusterIP` 且未被 Traefik 路由,公网不可达;但集群内任何工作负载都能访问它,因此仍有防护:
|
||||
|
||||
- **入站令牌(可选)**:设置 `LPT_AI_TOKEN` 后,`/ai/*` 与 `/admin` 都要求携带(header `x-api-token` 或 query `token`)。
|
||||
部署清单用 `secretKeyRef.optional: true` 引用 `lpt-secrets/lpt-ai-token`,**没设这个 key 也能正常启动**(此时不校验)。
|
||||
`lpt-be` 侧由 `lpt.ai-service.token` 提供,部署经 `LPT_AI-SERVICE_TOKEN` 注入。
|
||||
开发阶段可以不设,保持零摩擦;生产只需往 secret 加一个 key。
|
||||
- **限流**:`/ai/tasks` 按来源限流(默认 30 次/分钟),因为是单进程内存计数,属于粗粒度保护,不是精确配额。
|
||||
- **抓取加固**:`/fetch-title` 的目标由调用方给出,抓取前做四层校验 —— 协议白名单、端口白名单、**DNS 解析后逐个校验**(防解析到内网与 DNS rebinding)、**重定向逐跳校验**(防「首跳合法、次跳内网」);响应体截断到 512 KiB,且只在网页类型上取标题。
|
||||
- `/admin` 面板会展示完整 prompt 与学习内容,未设置令牌时会启动告警提示。
|
||||
|
||||
> `/fetch-title` 当前**全工作区零调用**(`lpt-fe` 走的是 `lpt-be` 的 `/utils/fetch-title`,用 Java 侧 `TitleFetcher`)。
|
||||
> 保留它是为了满足安全条目的验收;如需精简可连同本文件的抓取工具一并删除。
|
||||
|
||||
## 降级策略
|
||||
|
||||
- LLM API Key 未配置 → `/health` 返回 `llmAvailable: false`。
|
||||
- 后端(lpt-be)检测到 AI 不可用 → 自动切换到内置规则引擎(`BuiltinMindMapGenerator`)。
|
||||
- Java 后端是唯一调用方;本服务不直接暴露给前端(Service 是 `ClusterIP`,且 Traefik 未路由本服务)。
|
||||
@@ -0,0 +1,27 @@
|
||||
# 任务队列
|
||||
|
||||
- **功能**:定义 lpt-ai 异步任务队列(Worker 池、退避重试、相同输入幂等复用、TTL 清理)的行为与不可改契约。
|
||||
- **何时用**:改动 `/ai/tasks` 的提交/轮询、并发度、重试、幂等复用、TTL 清理、管理面板日志,或调整任务响应契约时。
|
||||
|
||||
## 任务队列设计
|
||||
|
||||
- 异步任务模式:submit + poll,避免 LLM 长耗时(10-60s)超时。
|
||||
- **Worker 池**:并发度由 `LPT_AI_CONCURRENCY` 控制(默认 2)。
|
||||
不要改回单 worker 串行:N 个请求会等 N × LLM 耗时,客户端会先超时。
|
||||
- **退避重试**:429 / 5xx / 超时等瞬时抖动会重试(`LPT_AI_MAX_ATTEMPTS`,默认 3),
|
||||
4xx 客户端错误与「API Key 未配置」不重试。服务端返回的 `Retry-After` 优先于自算退避。
|
||||
- **相同输入复用**:以 `type + params` 的稳定哈希为幂等键。
|
||||
- 同键任务 pending/running → 合并为同一个任务,不重复调用 LLM(不重复计费)
|
||||
- 同键任务已完成且在 `LPT_AI_RESULT_CACHE_MS` 窗口内 → 复用结果
|
||||
- 同键任务已失败 → 新建(失败必须可重试)
|
||||
- 请求体传 `force: true` 可跳过复用(用户主动「重新生成」)
|
||||
- 也可传 `idempotencyKey` 显式指定幂等键
|
||||
- TTL 清理:按 `LPT_AI_CLEANUP_MS` 周期移除过期记录,同时清理幂等索引。
|
||||
- 异常隔离:单个任务失败不影响后续任务。
|
||||
- 管理面板日志:复用 `logStore`,记录最近 200 条请求/响应。
|
||||
|
||||
### 不要改动的契约
|
||||
|
||||
- `/ai/tasks` **必须固定返回 201**。Java 端 `AiServiceClient.submitTask()` 把非 201 视为提交失败,
|
||||
所以不能用 200 表达「复用了已有任务」;复用信息放在响应体的 `reused` / `status` 字段里。
|
||||
- `TaskRecord` 的 `status` / `result` / `error` 字段名被 Java 端轮询逻辑依赖,新增字段可以,改名不行。
|
||||
Reference in New Issue
Block a user