问题与方案库(doc/problems/)
性质:决策档案,不是方案真源。每条回答「当时遇到了什么问题、桌上有哪些候选、为什么选这个、代价是什么、今天还成不成立」。 收录判据:只收设计选择题——有备选、有代价、有裁定。纯 bug 修复只在它暴露设计问题时顺带收。 素材口径:
doc/(定了什么)+tmp/台账(当时怎么想)+git/代码(真做了什么)。三者冲突时以代码与用户原话为准。 最后核对:2026-10-31,共 43 条。模块划分与代码落点见 doc/53-模块地图.md。
0. 怎么用
- 想找「为什么是这个设计」:先按模块下表找到问题,再读那条的 §2「候选与代价」与 §5/§4「同族小裁定」。
- 想复核某条裁定今天是否仍成立:每条 §6/§4「证据」给了代码符号与复核命令;§7/§6「现状」写明「仍有效 / 已翻转 / 未落地」。
- 想新增一条:在
doc/problems/<问题名>/问题与方案.md落文件,问题名用一句中文问句(不带编号);写完回到本表登记一行,并在对应模块的 doc/53 小模块后加反链。词表:已落地/部分落地/方案已定·未施工/已翻转/待拍(有候选、没裁定,只记现状与代价)。
每篇固定六到七节:1 场景与病灶(讲一个会真实发生的失败故事)→ 2 候选与代价(表)→ 中间按需拆真身 → 同族小裁定(表)→ 证据(方案 § / 台账 § / 代码符号 / 复核命令 / 活体验收)→ 现状(仍有效 / 已翻转 / 未落地 + 同族链接)。
1. 技术路线
| 问题 | 一句话 | 状态 |
|---|---|---|
| 选Eino不选LangGraph | Agent 框架选 LangGraph.js(TS)还是 Eino(Go)? | 已定案(2026-09-24) |
2. 运行时装配与多租户
| 问题 | 一句话 | 状态 |
|---|---|---|
| 租户从第一天就在 | 多租户建模从第一天做,还是上线前再补? | 已落地 |
| 租户运行时怎么装配 | 每场 run 怎么把租户的模型/密钥/MCP/工具装配成运行时? | 已落地 |
| 会话默认私有 | 新建会话默认谁能看见?可见性怎么判? | 已落地 |
| 共享项目整条退役 | 共享项目这条产品线留着还是整条删? | 已裁(10-22) |
| 项目目录归谁 | 项目目录归项目、会话还是租户?文件落在哪? | 已落地 |
| 团队前端的边界 | 团队/邀请做到页面哪一步,哪些明确不做? | 已落地 |
3. 运行生命周期与崩溃
| 问题 | 一句话 | 状态 |
|---|---|---|
| 租户并发闸放进数据库 | 租户并发上限的闸放进程内还是 PG? | 已落地 |
| 崩溃前那半句要不要存 | 崩溃前未完成的那半句助手回复要不要落库? | 已落地(draft 已删) |
| 崩溃后这场run算什么状态 | 崩溃后 run 算什么状态、谁能续、怎么续? | 已落地 |
| 失败轮要不要留痕 | 失败/停止的 run 要不要留历史、留什么? | 已落地 |
| 删除会话是软删 | 删除是真删还是软删?连带删什么、留多久? | 已落地 |
| 并行度由谁裁 | 子代理/工具的并行度由进程 sem、租户槽还是跨 pod 池裁? | 待拍 |
4. 上下文、工具与安全
| 问题 | 一句话 | 状态 |
|---|---|---|
| 折叠线用什么数 | 上下文折叠的触发阈值按什么数算? | 已落地 |
| 搜索怎么接厂商 | web_search 怎么接不同厂商,结果放哪? |
已落地 |
| 同项目并发写文件怎么防 | 多 run 同项目并发写文件怎么互斥? | 已落地(项目闸退役) |
| 没有沙箱的系统怎么办 | Linux 没有 sandbox-exec 时 bash 怎么办? |
已落地 2026-11-03(Debian 活体待跑) |
| 工具三态守卫与审批回路 | 工具调用要不要三态闸 + 人工审批? | 整条不做(沙箱硬挡) |
| MCP进程进不进围栏 | MCP 服务进程要不要和 bash 进同一个沙箱围栏? | 已落地 |
| PII打码挂哪层 | PII 打码挂工具出口、模型输入口还是记忆入库前? | 已落地 |
5. 子代理
| 问题 | 一句话 | 状态 |
|---|---|---|
| 同名委派共享实例 | 同名子代理多次委派共享一个实例还是每次新建? | 部分落地 |
| 子代理窗口谁来压 | 子代理上下文谁压、什么时候压? | 已落地 |
| 子代理规格与工具边界 | 子代理能拿哪些工具、规格怎么生效? | 已落地 |
| 子代理档案放哪里 | 子代理过程档案存文件还是 PG 表?半截救不救? | 已落地 |
6. 技能、看板与等人
| 问题 | 一句话 | 状态 |
|---|---|---|
| 技能谁读谁执行 | 技能正文由谁读、谁执行,子代理看不看得到? | 部分落地(B1–B4) |
| 看板正本放哪里 | 任务看板的正本放进程内存还是 PG? | 已落地 |
| 等人现场放哪里 | ask_user 挂起时现场放内存还是 DB? |
已落地 |
7. 记忆与媒体
| 问题 | 一句话 | 状态 |
|---|---|---|
| 记忆要不要上向量 | 长期记忆要不要用向量检索,用什么索引? | 已落地 |
| 历史查找用什么索引 | 会话历史检索用什么索引? | 已落地 |
| 召回块放哪一层 | 召回块拼在 history 还是本轮输入? | 已落地 |
| 笔记按什么分区 | 笔记按什么维度分区、谁读得到? | 已落地 |
| 对话只存路径 | 对话里图片存字节还是存路径? | 已落地 |
| 图片只发一次 | 图片在什么时机回填进模型请求,发几次? | 已落地 |
8. API 与前端
| 问题 | 一句话 | 状态 |
|---|---|---|
| 响应信封统一 | JSON 接口成功/失败统一回什么形状? | 已落地 |
| 前端拉帧还是切流 | 集成方拉帧还是吃 SSE?前端要不要切? | 端点已落地·前端不切 |
| 变更同步用事件通道 | 多窗口数据失效靠轮询、WebSocket 还是事件流? | 已落地 |
| 用量怎么让用户看见 | token 用量怎么让用户看见? | 已落地 |
| 前端可用性欠账 | 后端有契约、页面没入口,欠账怎么排先修谁? | 已落地(A5 未做) |
| 界面验收双轨 | 界面改动怎么验收,观感怎么断言? | 双轨已落地·Eval 未施工 |
| 品牌只落Logo | 品牌资产放哪、接哪几处、要不要连带换主题? | 方案已定·未施工 |
9. 验收与仓库治理
| 问题 | 一句话 | 状态 |
|---|---|---|
| 验收机器化 | 验收脚本放 tmp 还是入库?期望字节真源在哪? | 已落地 |
| 仓库治理的机械闸 | 双远端怎么保证 GitHub 不领先?文档门面怎么不脱节? | 已落地 |
| 术语先大白话后学名 | 文档术语第一次出现怎么写才读得懂? | 已落地 |
10. 统计
- 43 条:已落地 33、部分落地 2(同名委派、技能)、端点已落地但刻意不切 1(拉帧/切流)、双轨已落地但 Eval 未施工 1(界面验收)、方案已定未施工 2(品牌、Linux 沙箱)、整条不做 1(工具三态/审批回路)、已定案 1(Eino)、已裁 1(共享项目退役)、待拍 1(并行度)。
- 未落地的两条(品牌、Linux 沙箱)不是「以后再说」:前者素材只在
tmp/、随时会丢;后者是 Linux 上 bash/租户 MCP fail closed 的真实功能缺口。 - 待拍的一条(并行度)只记现状与候选,没有裁定:先留着,等单机两级闸还是跨 pod 执行池的方向定了再动。