Repository navigation
Expand file tree
/
Copy pathagentConfig.ts
More file actions
182 lines (171 loc) · 10.8 KB
/
Copy pathagentConfig.ts
File metadata and controls
182 lines (171 loc) · 10.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
import type { AgentConfig } from "@/types/agentConfig";
/**
* 本机开发默认地址(`langgraph dev`):环境变量没设时的唯一回落值。
* 单独抽成常量是为了让"默认值"只有一处,改的时候不会漏(注释、文档、脚本都引它)。
*/
export const DEFAULT_AGENT_BASE_URL = "http://127.0.0.1:2024";
/**
* 解析 Agent 服务地址:**构建期环境变量优先**,没设才回落到本机。
* 为什么要有它:Agent 之后是跑在**云服务器**上的(不是访客本机),
* 上线只该在构建环境里给一个变量,而不是改代码再提交一次。
* `PUBLIC_` 前缀是 Astro/Vite 的约定:只有它开头的变量会被注入到客户端产物里。
*/
function resolveAgentBaseUrl(): string {
// ⚠️ 用 `as` 收窄而不是直接点出来:`import.meta.env` 在类型上只有一组内建字段,
// 自定义变量要走索引访问,否则 `--isolatedDeclarations` 下的类型断言会炸。
const env = (import.meta as { env?: Record<string, string | undefined> }).env;
const fromEnv = env?.PUBLIC_AGENT_BASE_URL;
const url = typeof fromEnv === "string" ? fromEnv.trim() : "";
return url || DEFAULT_AGENT_BASE_URL;
}
/**
* 「博客前端 ↔ Agent 服务」接口契约配置(P5-0 冻结,需求 R-AGT-02 / R-AGT-07)
* ============================================================================
* 契约正文(端点、SSE 事件、最终答复取法、interrupt 约定、降级规则)在
* **`ARCH.md` §8.9「Agent 接口契约(P5-0 冻结)」**——这个文件只放"能被改的值",
* 不放任何判断逻辑(逻辑在 `src/utils/agent-client.ts`)。改契约口径请连带改那节与
* `scripts/verify-agent.mjs`。
*
* ⚠️ **P5-1 起本文件参与运行时**:桌宠的对话走 `src/utils/agent-client.ts`,
* 它读的就是这里的值。`enable: true` 时每个会话会现查 `assistant_id`、建一个线程;
* `enable: false` 时**一个请求都不发**,直接走本地 mock(`petConfig.mockReplies`)。
*
* 怎么改(每个字段都在下面单独标了):
* - 总开关 → `enable`
* - 换服务地址 → `baseUrl`
* - 换默认图 → `graphId`(可选值见 `knownGraphs`)
* - 觉得等太久 → `timeoutMs`
* - 换约定词 → `resumeWords`(**改了要同步后端 prompt 与 §8.9**,三个词是对好的暗号)
* - 想看请求细节 → `debug: true`(上线前记得改回 false)
* ============================================================================
*/
export const agentConfig: AgentConfig = {
/**
* 总开关。
* **true**(P5-2 起):桌宠对话走真实 Agent(`langgraph dev` / 上线后的网关),
* 连不上 / 超时 / 契约不符时由 `agent-client.ts` 按 §8.9.6 **降级**到 mock,不报错。
* **false**:一个网络请求都不发,完全走本地 mock 台词。
* 改成 true 之前先确认 `pnpm verify:agent` 是全绿或明确 SKIP。
*/
enable: true,
/**
* Agent 服务地址(**构建期可用环境变量覆盖,不要把本机地址写死成唯一来源**)。
* ============================================================================
* 取值顺序:
* ① `import.meta.env.PUBLIC_AGENT_BASE_URL`(Astro 只把 `PUBLIC_` 前缀的变量注入客户端);
* ② 没设 → 回落到本机开发地址 `http://127.0.0.1:2024`(`langgraph dev` 的默认端口)。
*
* 怎么用:
* · **本地开发**:什么都不用设 → 打本机 2024(就是现在的行为)。
* · **上线(推荐:同源反代)**:构建时给 `PUBLIC_AGENT_BASE_URL=/api/agent`
* (Nginx 把 `/api/agent/` 反代到 `127.0.0.1:2024`)。
* 为什么推荐同源反代:
* ① **没有 CORS 问题** —— 现在 `langgraph dev` 裸跑的 `ACAO` 是 `*`(见 B-14),
* 同源之后浏览器根本不发预检,前端也不必依赖对方改 CORS;
* ② SSE 只要在 Nginx 上 `proxy_buffering off`(`ARCH.md` §12.2 已经写好这段),
* 不用给前端加任何东西;
* ③ 后端端口不外露,限流/鉴权将来都落在这一层(B-14 的落点)。
* · **独立域名/网关**:也可以直接给完整 URL(`https://agent.example.com`),
* 或者指向 prd R-AGT-02 规划的那个网关 —— 前提是它实现了 §8.9 的端点序列。
*
* ⚠️ **前端只依赖这一个值**:直连(本机 2024)与反代(同源 `/api/agent`)两种形态
* 走的是同一份代码,换形态只需要改这个变量/环境变量,不用改任何别的文件。
* ⚠️ 不要加尾斜杠(适配层会兜底去掉,但配置里保持干净)。
* ============================================================================
*/
baseUrl: resolveAgentBaseUrl(),
/**
* 默认用哪张图。
* 取值必须是 `agent_-for_-blog/langgraph.json` 的 `graphs` 键之一(见 `knownGraphs`)。
* 为什么默认 `blog_agent`:它是唯一会按意图自己路由的主图(闲聊/检索/排行/推荐都走它),
* 前端只需要一个入口;等 P5 要做"只推荐"的独立入口时再显式传别的图。
* ⚠️ 改图**必须重启 `langgraph dev`**才生效(新增/删除图也是)——契约陷阱之一。
*/
graphId: "blog_agent",
/**
* **连接/首字节**超时(毫秒)——**不是**"整轮超时",两者在适配层里是分开的。
* ============================================================================
* 它只管三件事:`GET /ok`(另有一个更短的 2 秒探测超时)、建线程、
* **以及一次流式请求"拿到响应头之前"的那段时间**。
* 60 秒的依据:本机实测闲聊轮 3~8 秒、检索/推荐轮首字节一般 1~5 秒;
* 给到 60 秒是为了兼容"服务在排队/冷启动",而不是为了掐断答复。
*
* ⚠️ **长答复不受它管**(P5-1 实测教训):检索轮总耗时会抖到 30~120 秒,
* 如果拿一个 60 秒的绝对超时把整条流掐断,真机上会出现"聊到一半断掉"。
* 适配层的实际口径是三个**分开**的闸门(`agent-client.ts` 顶部常量):
* · 连接/首字节:`min(this, 20s)` —— 拿不到响应头就别耗着;
* · 流中途卡死:60 秒**没有任何新 chunk** 才判失败(LLM 正常几秒一个 chunk);
* · 硬上限:300 秒(兜底,防"永远挂着";与 Nginx 的 `proxy_read_timeout` 对齐)。
* 所以这个值调大调小都**不会**让答复被截断,只会影响"连不上/不响应"时多等多久。
*/
timeoutMs: 60000,
/**
* 已知存在的 4 张图(2026-09-26 实测 `POST /assistants/search` 的 `graph_id` 去重结果)。
* 契约测试会断言这 4 张都能在服务上找到;契约文档 §8.9 引用同一份清单。
* 后端加/删图时改这里(**同时重启服务**)。
*/
knownGraphs: [
"blog_agent",
"recommended_agent",
"collect_agent",
"extend_agent",
],
/**
* 「推荐链路」续跑时回给后端 `interrupt()` 的三个约定词。
* 后端在 `recommended_agent` 的 `collect_user_info` 节点会 `interrupt()` 问"篇幅大概多少字",
* 前端第二轮用 `command: { resume: <这里的某个词> }` 续跑。
* ⚠️ 这是**对好的暗号**:改词必须同时改后端 `agent_-for_-blog` 的 prompt 与 `ARCH.md` §8.9,
* 否则后端会把它当普通回答处理(不会报错,但推荐会跑偏)。
*/
resumeWords: {
/** 默认答案:让后端按站内常用字数范围替用户挑(用户没明说字数时用它) */
default: "不提供",
/** 用户明确给了字数/时长要求 */
provide: "需要",
/** 用户明确表示不需要后端代挑 */
decline: "不需要",
},
/**
* **线程失效重建时,把最近几轮对话重放给后端**(v1.99 新增,发起人 2026-10-10 拍板「可以改」)。
* ============================================================================
* 解决的是 `ARCH.md` §8.9.7 的未决项 **#5(线程是内存 checkpoint,重启即清空)** 与
* **#10(失效自愈是前端单方面行为,新线程没有上下文)**:旧口径是「接受忘掉,但不许永久降级」。
*
* 现在的口径:**新建线程时把最近 N 轮(人/AI 交替)+ 新问题一起放进 `input.messages`**。
* ⚠️ 这是**先量后改**,不是猜的(探针 `reports/_thread-replay-probe.mjs`,2026-10-10 打在真后端上):
* · ① 一次带 5 条 `input.messages`(4 条历史 + 1 条新问题)→ **HTTP 200**,后端的 `values`
* 快照里能看到整段历史(`messages` 数组 5 条);
* · ② 用一个它**不可能从库里知道**的暗号验"真的记得":历史里写「记住一个暗号:蓝鲸七号」→
* 新问题「我刚才让你记的那个暗号是什么?」→ 答复就是「**蓝鲸七号。**」;
* · ③ **反控**(只发那一句新问题、不带历史)→ 答复「……你什么时候让我记过暗号?我这边翻不到。」
* —— 证明 ② 的效果来自重放,而不是它瞎猜。
*
* ⚠️ **只在"自愈"那条路径上重放**(`agent-client.ts` 的 4xx 分支):正常轮次里线程自带上下文,
* 每轮都重放等于把同一段历史反复追加进线程状态(上下文翻倍、token 白烧)。
* ⚠️ 自愈时如果原 payload 是 `command:{resume}`(用户在回答 `interrupt`),**必须改成 `input`** ——
* 新线程根本没有待续跑的 `interrupt`,照发 `command` 只会再吃一个 4xx(等于自愈没做)。
* ⚠️ 重放的是**上屏文本**(历史区里看得见的那份,含我们给反问加的那句提示尾巴):
* 口径是"把用户看得见的上下文还给它",不是去猜模型内部状态。
* ============================================================================
*/
contextReplay: {
/** 开关:false = 回到旧口径(重建线程后从零开始) */
enable: true,
/** 重放最近几轮;3 轮 ≈ 6 条消息 + 当前这句,实测一轮约 1~2 KB */
rounds: 3,
/** 每条重放消息的截断上限(字符):检索轮的答复实测 480~520 字,留一倍余量 */
maxCharsPerMessage: 800,
},
/**
* 契约不符 / 连不上 / 超时 / 返回空时,是否回落到本地 mock 台词。
* **必须保持 true**(prd R-AGT-03 的硬要求:没有后端时不报错、不弹技术错误)。
* 只有"正在调试契约、想让失败显形"时才临时改 false。
*/
fallbackToMock: true,
/**
* 调试开关:把每次请求的 URL / 状态码 / SSE 事件名序列打到 console。
* 默认 false;`verify-agent.mjs` 与本地排查时用。**上线前确认是 false**
* (事件序列里会带 thread_id / run_id,不适合给访客看到)。
*/
debug: false,
};