From a71feea4fd68c8380097d7e9d06da8e4ff945f26 Mon Sep 17 00:00:00 2001
From: cat-shark <1716967236@qq.com>
Date: Sat, 1 Aug 2026 00:13:08 +0800
Subject: [PATCH] docs: migrate .pi/SYSTEM.md to AGENTS.md

---
 .pi/SYSTEM.md => AGENTS.md | 63 ++++++++++++++++----------------------
 1 file changed, 27 insertions(+), 36 deletions(-)
 rename .pi/SYSTEM.md => AGENTS.md (67%)

diff --git a/.pi/SYSTEM.md b/AGENTS.md
similarity index 67%
rename from .pi/SYSTEM.md
rename to AGENTS.md
index 3250d1b..2d24895 100644
--- a/.pi/SYSTEM.md
+++ b/AGENTS.md
@@ -1,29 +1,28 @@
 # LPT AI 服务（lpt-ai）
 
-> TypeScript + Fastify 独立 AI 服务，集成 SiliconFlow LLM，为后端提供异步 AI 任务
+> TypeScript + Fastify 独立 AI 服务，集成 SiliconFlow LLM，为后端提供异步 AI 任务。
 
 ## Git 提交规范
-- 提交信息使用**中文**，简洁描述变更内容
-- 格式：`类型: 简述`，如 `feat: 新增思维导图生成任务`、`fix: 修复任务队列TTL清理`、`docs: 补充环境变量说明`
 
----
+- 提交信息使用中文，简洁描述变更内容。
+- 格式：`类型: 简述`，例如 `feat: 新增思维导图生成任务`、`fix: 修复任务队列TTL清理`、`docs: 补充环境变量说明`。
 
 ## 技术栈
-- **运行时**: Node.js 20+
-- **框架**: Fastify 5
-- **LLM**: SiliconFlow OpenAI 兼容接口（Qwen/Qwen2.5-32B-Instruct）
-- **依赖**: 零外部依赖（除 fastify）
 
----
+- 运行时：Node.js 20+
+- 框架：Fastify 5
+- LLM：SiliconFlow OpenAI 兼容接口（Qwen/Qwen2.5-32B-Instruct）
+- 运行时依赖：除 fastify 外无其他外部依赖
 
 ## 项目结构
-```
+
+```text
 lpt-ai/src/
 ├── index.ts          → 服务入口（加载 .env，启动 Fastify）
 ├── routes/ai.ts      → AI 路由（health, tasks, fetch-title）
 ├── llm/
 │   ├── client.ts     → LLM 客户端（SiliconFlow 接口）
-│   ├── prompts.ts    → Prompt 模板（3种任务类型）
+│   ├── prompts.ts    → Prompt 模板（3 种任务类型）
 │   └── prompts.test.ts
 ├── task-queue.ts     → 异步任务队列
 └── admin/
@@ -32,8 +31,6 @@ lpt-ai/src/
     └── store.ts      → 日志存储
 ```
 
----
-
 ## API 端点（5 个）
 
 | 方法 | 路径 | 说明 |
@@ -44,8 +41,6 @@ lpt-ai/src/
 | POST | `/fetch-title` | 抓取网页标题 |
 | GET | `/admin` | 管理面板（查看最近 200 条日志） |
 
----
-
 ## 支持的任务类型
 
 | 类型 | 说明 | 温度 | Max Tokens |
@@ -54,20 +49,16 @@ lpt-ai/src/
 | `generate-mind-map` | 从报告/残片生成思维导图大纲 | 0.3 | 4096 |
 | `compare-recall` | 用户回忆 vs 标准导图语义对比 | 0.2 | 4096 |
 
----
-
 ## 任务队列设计
-- **异步任务模式**: submit + poll，避免 LLM 长耗时（10-60s）超时
-- **单线程 Worker**: `setImmediate` 链，同一时刻只处理一个 LLM 调用，防止 API 限流
-- **TTL 清理**: 5 分钟一次，移除完成超过 1 小时的记录
-- **异常隔离**: 单个任务失败不影响后续任务
-- **管理面板日志**: 复用 `logStore`，记录最近 200 条请求/响应
 
----
+- 异步任务模式：submit + poll，避免 LLM 长耗时（10-60s）超时。
+- 单线程 Worker：`setImmediate` 链，同一时刻只处理一个 LLM 调用，防止 API 限流。
+- TTL 清理：5 分钟一次，移除完成超过 1 小时的记录。
+- 异常隔离：单个任务失败不影响后续任务。
+- 管理面板日志：复用 `logStore`，记录最近 200 条请求/响应。
 
 ## LLM 配置
 
-### 环境变量（`.env`）
 ```env
 LLM_API_URL=https://api.siliconflow.cn/v1/chat/completions
 LLM_API_KEY=                    # 必填，未配置时 /health 返回 llmAvailable: false
@@ -76,38 +67,38 @@ LLM_TIMEOUT_MS=60000            # 单次 LLM 调用超时
 PORT=5199
 ```
 
-### 降级策略
-- LLM API Key 未配置 → `/health` 返回 `llmAvailable: false`
-- 后端（lpt-be）检测到 AI 不可用 → 自动切换到内置规则引擎（`BuiltinMindMapGenerator`）
+## 降级策略
 
----
+- LLM API Key 未配置 → `/health` 返回 `llmAvailable: false`。
+- 后端（lpt-be）检测到 AI 不可用 → 自动切换到内置规则引擎（`BuiltinMindMapGenerator`）。
+- Java 后端是唯一调用方；本服务不直接暴露给前端，不做鉴权（部署在内网）。
 
 ## 启动命令
+
 ```bash
-npm install        # 安装依赖
+npm install
 npm run dev        # 开发模式（tsx watch，热重载）
 npm run build      # 编译 TypeScript
 npm run start      # 生产模式
 npm run test       # 测试
 ```
 
----
-
 ## Docker
-- 多阶段构建：`node:20-alpine` 编译 → `node:20-alpine` 运行
-- 暴露端口：5199
-- 健康检查：`curl http://localhost:5199/health`
 
----
+- 多阶段构建：`node:20-alpine` 编译 → `node:20-alpine` 运行。
+- 暴露端口：5199。
+- 健康检查：`curl http://localhost:5199/health`。
 
 ## 关联项目
+
 | 项目 | 路径 | 端口 | 说明 |
 |------|------|------|------|
 | lpt-be | `../lpt-be/` | 5157 | Spring Boot 后端，通过 `lpt.ai-service.url` 调用本服务 |
 | lpt-fe | `../lpt-fe/` | 5158 | Vue 3 前端，不直接调用本服务 |
 
 ## 调用关系
-```
+
+```text
 lpt-be (5157) ──HTTP POST /ai/tasks──→ lpt-ai (5199)
 lpt-be (5157) ──HTTP GET  /ai/tasks/:id──→ lpt-ai (5199)
 ```