文档: 设计文档与问题记录归档

docs/01-技术文档/团队级基建-部署与运维-2026-10-05.md

@@ -0,0 +1,36 @@
+# DevFlow 团队级基建 — 部署与运维
+
+> 2026-10-05 落地。架构定位见《数据存储架构-定稿-2026-10-05》(团队级 = 汇聚节点 + 对象存储)。
+
+## 资源清单
+
+| 资源 | 位置 | 版本/规格 | 用途 |
+|---|---|---|---|
+| PG 容器 `df-pg` | ecs-os(39.99.131.191) | PostgreSQL 18.6-alpine | devflow 团队库(服务端数据面) |
+| OSS 私有桶 `devflow-data` | 阿里云 cn-hongkong | 私有 ACL | 团队文件存储(温层,内容寻址) |
+| 域名 `df-oss.1216.top` | CNAME → devflow-data.oss-cn-hongkong.aliyuncs.com | HTTPS(泛域名证书已绑) | 桶访问入口 |
+
+## PG(df-pg)
+
+- 连接:`127.0.0.1:5432`(仅本机/内网,**不暴露公网**);服务端将来部署 ecs-os 时走 localhost
+- 库:`devflow`(容器首启自动创建);用户 postgres
+- 凭据:`/data/docker-apps/pg/.pg-credentials`(600 权限)
+- compose:`/data/docker-apps/pg/docker-compose.yml`(服务名=容器名 df-pg,数据卷自包含 `/data/docker-apps/pg/data`)
+- 备份:cron 每日 03:30 `/data/scripts/pg-backup.sh` → `/data/backup/pg/` 保留 7 份
+
+## OSS(devflow-data)
+
+- 访问:私有桶,读写须签名(oss2 AK:ops-kit/app.yml aliyun.accounts[4],即 zhub-site 归属主账号)
+- HTTPS:泛域名 `*.1216.top` 证书(suke-dev /etc/letsencrypt/live/1216.top)已绑 CNAME;归属验证 TXT 已用毕删除
+- 服务端用法:oss2 SDK 签发临时 URL 供客户端下载;上传走 SDK 直传
+- 续期注意:证书到期随泛域名统一续期(Let's Encrypt DNS-01),续期后需重新 put_bucket_cname(参考 cert-manage)
+
+## 升级记录
+
+- 2026-10-05 建 PG 16 当日即升 18.6(库空无损);compose 风格对齐 ecs-os 惯例(注释头/服务名=容器名/卷自包含);旧顶层卷 /data/pg-data 已清
+- 选型记录:文件桶定阿里云 OSS(七牛私有桶缺主账号 SK,qshell 双账号 uppt/lakeapp-suke 已确认;七牛保留公开 CDN 分工 img.1216.top)
+
+## 关联
+
+- 架构:《数据存储架构-定稿-2026-10-05》§六 团队级/平台级
+- 服务索引:kms/服务索引-全机器.md(df-oss/df-pg 两行)

docs/02-架构设计/专项设计/数据存储架构-定稿-2026-10-05.md

@@ -0,0 +1,59 @@
+# DevFlow 数据存储架构 — 定稿总结
+
+> 2026-10-05 AI-Ops 归纳。来源:四维评估(空间治理/换库对比/量级基准/分布式协同)全部结论收敛,条款详见 todo「基础设施走查-1005」与「上下文精细化管理」两段。
+
+## 一、三条定调(用户拍板)
+
+1. **量级前提**:全生态实测 ≈2.1GB(本机 ~/.claude 2.0G + 六容器实例 <25MB)×10 ≈ **21GB**;流水不进主库,主库 GB 级以内。
+2. **技术选型**:桌面端 **SQLite 不换**(换库是周级工程,PG 的优势场景用不上);**流水外置用文件**(Claude Code 自身先例:jsonl 存会话);**PG 属于未来云端服务端**(S3 多人时进,桌面不动)。
+3. **向量非必选**:知识库检索按无向量设计(关键词+标签+kind 分簇),embedding 相关字段与管道视为遗留物。
+
+## 二、分层架构
+
+```
+热层(主库 SQLite)     结构化条目:消息/任务/知识/审批 — GB 级内,D1-D3 治理
+   │ compress(相关性驱动,R 条款)
+温层(外置文件区)      流水 jsonl / 工具大结果(>30 天外置)/ 长文档 — 内容哈希 id,
+   │ distill(蒸馏)     按会话/任务索引,跨会话跨端可找回(C5=量级前提)
+冷层(知识库)          蒸馏条目:精巧即时、代谢进化(R7)、准入分级(R4)、无向量检索
+   │ inject(auto_inject,验证后准入)
+热层(反哺新会话)
+
+同步桥(横向):条目变更事件流(append-only)复用 u-relay/df-tunnel;
+各端 SQLite 离线自治;冲突普通条目 LWW、关键实体状态机(task_state_machine CAS 先例);
+云端多人(S3)时服务端 PG 作汇聚点。
+```
+
+## 三、统一条目模型(R8,架构轴)
+
+- 一条信息 = 唯一 id + 内容 + 溯源 parent 链 + 元数据(相关性/时效/频率/**归属/origin/修订**)
+- 生命周期状态机:hot → warm → cold → dead;compress/reload/distill/inject/merge/evict 都是状态转移
+- 四类卡(10-04 设计)/知识条目/外置件 = 同一 schema 的类型扩展;新策略可插拔、新存储后端 = warm 层 trait
+- **实施含义:C-m1 建模时四个分布式预留字段(归属/origin/修订/内容哈希)一次建齐,后续不再动地基**
+
+## 四、治理与度量
+
+- 空间:D1 VACUUM 止血(168MB→~70MB)/ D2a 结果 30 天外置 / D2b 月度定例 / D2c 文件:数据比 >1.5 告警
+- 知识代谢:R7 入库先查存量(update 路径)/ R4 准入分级(candidate 不注入,verified 或 reuse 达标)/ R7 精巧即时
+- 效果度量(R6):重载命中率 / 误压率 / 蒸馏采纳率;ai_messages 全程记录,评测基建现成
+
+## 五、落地序
+
+C-r0 验证后台化(独立先行)→ C-m1 建模(含四预留字段)→ C-m2 时机关联 → C-r1 按段重载 → C-m3 外置+蒸馏衔接(依赖知识库重审设计五步序)→ D 系列并行。
+
+## 六、团队级 / 平台级 演进(用户 10-05)
+
+原则:**演进不推翻** — 单机 → 团队级 → 平台级逐层加高,桌面端 SQLite 与统一条目模型永远不动;R8 预留的 scope/归属字段在此兑现(团队级 = scope 增加"团队"档,不是模型重构)。
+
+数据三分类定共享边界:
+- 私有(个人会话/上下文/记忆)→ 端内自治,永不上云
+- 团队共享(团队知识/任务/项目/审批规则/模板)→ 团队空间事件同步
+- 平台公共(跨团队知识/配额/审计)→ 平台层
+
+**团队级**:一台汇聚节点(常驻机器)跑服务端 + PG 从第一天启用;成员桌面端照常 SQLite;共享空间走条目事件同步,私有不出端。与 u-claw 生态同构(u-relay 汇聚 + 各端自治),即该模式的产品化。
+
+**平台级**:多租户 PG(小客户共享库+租户 id 行级 / 中型独立 schema / 大客户独立库,按规模分档)+ 温层升对象存储(内容寻址不变)+ 审计合规(events 表已有底子)+ API 网关/认证/配额服务层。
+
+三阶段存储引擎各就各位,无任何阶段需要改条目模型或推翻同步协议。
+
+> 关联文档:「上下文三层记忆-设计-2026-10-04」(实施主依据)/「知识库模型重审-精细化设计-2026-10-05」(冷层细则)/ todo R1-R9(风险条款全量)。

docs/02-架构设计/专项设计/知识库模型重审-精细化设计-2026-10-05.md

@@ -0,0 +1,67 @@
+# 知识库模型重审 — 精细化设计(用例法+推演法)
+
+> 2026-10-05 AI-Ops 分析移交。背景:C-m3(蒸馏衔接知识库)实施前,重审知识库模型能否承载 R4(防错误反哺)/R7(代谢进化)/R8(统一条目)职责。
+> 现状实证(devflow.db,knowledges 1073 条 / knowledge_events 2221 条):
+> - 字面厚实:confidence/reuse_count/verified/source_ref/embedding/kind 字段全有,update/archive/record_reuse/extract_now 命令齐备
+> - 实际停滞:verified 仅 23 条(2%);confidence 87% high(置信通胀,自动提取默认 high 无评估);无淘汰态在用;status_changed 仅 31 次(流转冻结);reuse>0 仅 20%;向量 0/1073(**设计按无向量走,用户 10-05 拍板**:不依赖、不维护、不承诺,embedding 字段视为遗留)
+> - 结论:骨架在,循环断。三条断链:蒸馏→查重→更新 断;注入→采纳→验证 断;时间→过时→淘汰 断。
+
+## 一、用例走查(六用例,标注断点)
+
+### UC1 蒸馏入库(会话收官 → 知识条目)
+目标流程:触发蒸馏 → 查重(关键词+标签+kind 主题) → 命中相似则 update(合并/增强/置信重估) → 未命中则 create candidate。
+现状断点:①查重只有关键词,同义异词查不出 → 同主题碎片堆积(kind=architecture_pattern 已 322 条)——缓解靠标签规范与 kind 主题分簇(设计基准无向量,不预留向量后路);②提取默认 confidence=high → 通胀;③查重命中后的 update 合并路径不存在(extract_now 只新增)。
+
+### UC2 检索注入(新会话 → 知识反哺)
+目标流程:用户消息 → 查询提取(关键词) → 候选 → **准入过滤(R4 门槛)** → 注入 → record_reuse。
+现状断点:①召回靠关键词,召回质量以标签规范与 kind 分簇保障;②准入门槛缺失——verified 仅 2%,强制则无可注入,不强制则错误知识直通 → 需**分级准入**:candidate 不注入;published 且(verified 或 reuse≥N)才可注入。
+已具备:record_reuse 有(216 条被引用),查询关键词提取(CJK bigram)在。
+
+### UC3 验证升格(candidate → verified / 打回)
+目标流程:注入后被实际采纳 → 采纳计数 → 达标升 verified;被用户纠正/结果证伪 → 降级打回。
+现状断点:验证只有手工通道(23 条);「注入→采纳→升格」自动链不存在;用户纠正信号无回写条目的通道。
+设计:events 增加 adopted(采纳)/contradicted(反驳)事件类型;adopted 计数达阈值自动升 verified;contradicted 触发降级+复核标记。
+
+### UC4 代谢(过时/重复/腐化)
+目标流程:周期或触发式 → 过时检测 → 重复聚类合并 → 久未用沉降(archive) → 被证伪淘汰。
+现状断点:archive 命令在但零使用;无周期任务;无聚类合并;status 流转冻结。
+设计:代谢三合一任务(手动命令先行,稳后挂定时):①候选→发布超时未验证的沉降;②同簇高相似聚类提示合并;③久未 referenced 的沉降。
+
+### UC5 溯源找回(条目 → 原始件)
+流程:source_ref → 原始消息(压缩后原文仍在库,可溯)/ 外置件(C-m3 落地后句柄)。
+现状:source_ref 字段有值但可溯性未验证;C-m3 外置区落地后需统一句柄(R8)。
+
+### UC6 跨会话/跨 agent 归属
+推演:多 agent 场景知识需分 scope。现状仅 source_project 单字段。设计:加 scope(会话/项目/全局)层级字段,注入按 scope 过滤。
+
+## 二、极端推演(五场景)
+
+- E1 知识冲突:同主题两条矛盾(旧 pitfall 与新结论相反)。设计:kind+主题聚类为冲突簇,新条目入簇时触发旧条目复核标记,人工/LLM 裁决后 superseded_by 指针淘汰败方。
+- E2 知识爆炸:万条量级下关键词检索劣化、注入筛选贵。前提:注入配额 top-k 上限;kind 分簇检索;标签规范。(万条量级仍走关键词+分簇,无向量前提)
+- E3 知识过时:框架升级后旧 pitfall 失效仍被注入。设计:条目加 applicability(适用条件/版本范围),环境变更触发复核。
+- E4 置信通胀:87% high 已失去区分度。设计:置信由证据推导——自动提取默认 medium;high 需(verified 或 reuse≥N 且无反驳);杜绝「无证据 high」。
+- E5 恶性循环:低质会话蒸馏出低质知识再反哺。设计:蒸馏来源带质量权重(采纳率高的会话产出才可 high),与 R4 门槛联动。
+
+## 三、模型与流程增量(在现有表上补,不推翻)
+
+1. **检索主路线 = 关键词,设计基准无向量(用户 10-05 拍板)**:查重与召回以现有关键词(CJK bigram)+ 标签 + kind 主题分簇实现并持续优化(标签规范、分簇细分、查询扩展);不做向量预留,embedding 相关字段与 spawn_embedding 管道视为遗留物,不维护不扩展。
+2. knowledges 补字段:scope、applicability(适用条件)、superseded_by(淘汰指针)、conflict_group(冲突簇)。
+3. 置信规则化:自动提取默认 medium;high 需证据(verified 或 reuse≥N 且无反驳)——治通胀(E4)。
+4. 事件扩型:events 增 adopted/contradicted;采纳计数驱动 UC3 升格,反驳驱动降级。
+5. 准入分级(R4):candidate 不注入;可注入 = published 且(verified 或 reuse≥N 且非 contradict 状态)。
+6. 蒸馏查重走 update 路径(R7 入口):相似度阈值命中 → 合并/增强/置信重估,只增不改的旧路径退役。
+7. 代谢任务(UC4):三合一,手动命令先行。
+8. 蒸馏来源质量权重(E5)。
+
+## 四、实施序与验收
+
+| 序 | 项 | 验收 |
+|---|---|---|
+| 1 | 准入分级(R4) | candidate 零注入;注入列表 100% 满足门槛 |
+| 2 | 蒸馏查重→update 路径(R7,关键词+标签+分簇) | 同主题条目数下降;新条目重复率 <5% |
+| 3 | 置信重估(E4) | high 占比 <60% 且与 verified/reuse 正相关 |
+| 4 | 代谢任务(UC4) | 沉降/淘汰有产出;status 流转事件 >收编前 10 倍 |
+| 5 | 冲突簇+时效(E1/E3) | 矛盾对可被检出并裁决 |
+
+> 关联:R4(准入)/R7(代谢)/R8(统一条目,本设计字段为 knowledge 侧投影)/C-m3(蒸馏衔接,依赖 1-3 项完成后可开 auto_inject)。
+> 数据基线快照(2026-10-05):1073 条 / 向量 0 / verified 23 / high 935 / reuse>0 216 / status_changed 31——改进后对照。

docs/02-架构设计/专项设计/飞书直连接入-形态修正与问题记录-2026-10-05.md

@@ -0,0 +1,44 @@
+# 飞书直连接入 — 形态修正设计与问题记录(2026-10-05)
+
+> 产出:AI-Ops(飞书 bot,只做分析/设计/问题记录);实施:devflow agent。
+> 背景:用户 10-05 在飞书群多轮拍板,推翻 df-im-gateway→u-relay 网关链路,定稿「桌面本地 WS 直连飞书开放平台」。
+
+## 一、形态拍板(用户令,已定稿)
+
+```
+飞书开放平台 ←WS长连接(出站,免公网回调)→ devflow 桌面端(内置飞书渠道) ⇄ ai-chat agent
+```
+
+- 参照形态:u-claw `feishu_channel.go`(官方 SDK `larksuite/oapi-sdk-go/v3` 的 `larkws.Client` 出站长连接 + REST API 回复,单进程闭环零中间件)
+- 旧网关链路(飞书→df-im-gateway→u-relay→df-tunnel→桌面端)在单机场景属绕行,推翻;原网关规划设计文档的 §十(云端多人演进预留)保留远期参考
+- 代价已确认:「桌面端关机 bot 不活」用户接受(先例:AI-Ops 即本机常驻)
+
+## 二、实施要点(交 devflow agent)
+
+1. **复用现有资产,勿新建 df-* 组件**(用户 10-05 明确):`crates/df-im-gateway/src/feishu.rs`(350 行,基于 larksuite-oapi-sdk-rs 0.3.12 channel 特性)的长连接内核可提炼,并入哪个现有 crate 由实施时定位(SDK 用法参考:公开 API `LarkClient::ws_client(dispatcher)` 直建,拿 `WsClientControl` 句柄做停机/诊断;AI-Ops 侧曾试建 df-feishu crate 已按要求撤销,其间验证过该路线可行:11 单测全过)
+2. **消息链路**:飞书 Inbound(文本/卡片动作)→ chat_id↔conversation_id 映射 → ai-chat 会话链路(GUI 同源)→ agent → 流式回飞书;先文本回复,卡片流式更新/审批卡放第二批次
+3. **Settings 契约**:app_settings 单键 `'feishu-config'` = JSON `{enabled, app_id, app_secret, whitelist[]}`(snake_case,存法对齐 `df-knowledge-config`)
+   - 注:AI-Ops 侧子代理已按此契约实现 Settings 面板于工作区(6 文件:`FeishuPanel.vue` 新增 + SettingsNav/searchIndex/Settings.vue/zh-en i18n 修改,vue-tsc 通过,未提交)。devflow agent 三选一:采纳 / 推翻重做 / 回退(`git checkout` 那 6 文件+删 FeishuPanel.vue)
+4. **白名单**:空=放行所有(与现 df-im-gateway main.rs 行为一致);open_id 按应用隔离,严禁从其他 bot 搬,须本应用实测获取(首启留空 → 用户发一条消息 → 日志取 open_id 回填)
+5. **凭证**:用户已在飞书开放平台建应用(10-05),经设置页录入;曾现「bot disabled」,接入验收前先在开放平台启用 bot
+
+## 三、问题记录 ①:ai-chat 交互消息闪现即消(未结,待复现)
+
+**现象**:用户 10-05 白天报告,ai-chat 对话页面消息闪现一下就消失,自述"又出现了"。
+
+**已锁机制**:前端乐观气泡被回滚移除(`useAiSend.ts:132/190/199` — IPC 失败即移除占位气泡)。**实锤:10-05 00:12 换装重启后 ai_messages 零写入**(`Roaming/top.1216.devflow/devflow.db`),白天发的消息后端一个没接住,闪现=回滚删除。
+
+**时间线**:10-05 00:03-00:12 凌晨会话(agent 自主)按攒批纪律以工作区状态 `bun tauri build` 打 NSIS 包,`DevFlowRedeploy` 计划任务强杀换装;00:35 攒批分组提交(8e1e56b 等);运行中二进制=`LOCALAPPDATA/devflow/devflow.exe`(00:11 产,48MB)。
+
+**候选根因**(按嫌疑序,未定):
+1. 换装后 agent 后端没接活,发消息 IPC 失败(spawn 前)——零写入吻合
+2. "无活跃对话"回滚路径(useAiSend.ts:190)——重启后活跃会话指针丢失
+3. 会话级:仅大会议(seq 4989 级)复现 → 嫌疑落"上下文管理信息组织"批次改动
+
+**已排除**:provider 配置完好(ai_providers 5 行);9-28 走查#5 队列误清已由 c10f0e4 修复(本次是同症状另一条路径);工作区现有改动与本问题无关(df-im-gateway/df-mcp/df-nodes/df-storage 等,系 devflow agent 在途工作)。
+
+**下一步(需现场)**:用户在 ai-chat 再发一条消息,同时记录三点:闪掉的是 user 气泡还是 assistant 占位;有无错误提示一闪而过;全部会话闪还是个别会话。前端 webview console(EBWebView CDP)是备选取证面。
+
+## 四、问题记录 ②:seq=0 system 消息(次要,顺手修)
+
+`ai_messages` 中发现 system 消息 `seq=0` 混于 seq=4951+ 序列(10-05 00:00:50,conv=84cb104c,内容为 assistant 风格"vision 技能已加载…")。seq 分配路径存在未走递增器的旁路,排序场景会被挤到队首。修复时一并核对 system 类消息的 seq 分配。