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

2026-10-05 14:59:12 +08:00
parent 2eea0118db
commit d5766c2142
5 changed files with 280 additions and 0 deletions
@@ -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 两行)
@@ -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(风险条款全量)。
@@ -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——改进后对照。
@@ -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 分配。
@@ -107,3 +107,77 @@
  - 覆盖场景:意图增强/纠偏/递进(用户补充信息后发现之前目标提取偏了)
  - 优先级:中——价值高改动小,补全目标维护闭环
 ## 上下文精细化管理(对齐 10-04 三层记忆设计)+ 工程可行性(AI-Ops 分析移交)
 > 分析来源:凌晨窗口实测(221 轮/508 条,prompt 均值 71K/峰值 135K,压缩 ~120K 才触发,tool 结果 4.9KB×279 条,cargo 验证同步阻塞占 45%)。
 > 方向定调(用户 10-05):1M 窗口下调阈值意义不大;主轴 = 按任务相关性精细组织上下文 + 自主管理,外置内容长久可找回并持续蒸馏进知识库。
 > 对齐结论:本组需求与「上下文三层记忆-设计-2026-10-04」高度同路,实施以该设计为准,不平行立方案。映射:相关性压缩/结构化 → C-m1 记忆卡;压缩时机 → C-m2 信息增益信号;外置找回/蒸馏知识库 → C-m3 提炼链与知识库衔接。
 ### 实施序(按 10-04 分期 + 可行性排序)
 - [ ] **C-r0 验证命令后台化与降频**(独立,先行):全仓测试攒批收官一次(凌晨重复跑 2 次),中途只单包 check;长命令异步执行 + 完成回填。验收:>90s 同步等待占比 <15%(现状 45%)。
 - [ ] **C-m1 记忆卡产出**(10-04 分期一):按设计实施四类卡 + 渲染,压缩产物结构化。
 - [ ] **C-m2 压缩时机关联**(分期二):信息增益信号触发;AI-Ops 补充输入——相关性判据挂 pinned_goals,水位仅作失控兜底(窗口 80%),prompt_tokens 已逐轮在库可直读。
 - [ ] **C-r1 压缩可逆:按段重载**(AI-Ops 增量):compressed 原文全在库(status 标记未删),给 agent 按段重载手段,压缩从不可逆变可逆。
 - [ ] **C-m3 外置找回 + 蒸馏衔接**(分期三,依赖召回闭环):大内容外置区(上下文只留句柄 + 头部摘要,跨会话按任务索引,外置区是资产不是垃圾暂存);蒸馏接现有 knowledge 模块(提取侧 knowledge.rs、注入侧 knowledge_inject.rs 均已在)。
 ### 设计风险与工程可行性(R 条款,实施前必读)
 - **R1 相关性判别的成本账**:"LLM 按段自评"若逐段调用,压缩一次 = 几十次 LLM 调用,成本延迟反噬。要求:规则初筛粗分,LLM 只评模糊带;或随摘要生成批量一次判定。验收加一条:压缩动作自身成本 < 被省成本的 10%。
 - **R2 目标漂移误压**:pinned_goals 中途变更后,按旧目标判"无关"的段对新目标可能关键。压缩判定带目标版本标记;目标变更时对判无关段重估。
 - **R3 盲区问题(压缩可逆的边界)**:被压内容里可能有关键细节而 agent 不知道存在,重载依赖"想起"。缓解:记忆卡必须带检索锚点(关键字/路径/数字清单),不只是叙述摘要——四类卡若无此字段,实施时补。
 - **R4 错误知识反哺循环(最危险)**:蒸馏出错条目 → auto_inject 污染后续会话 → 错误自我强化。准入门槛必须先于注入开关:条目带溯源 + 置信标记,被验证/被引用后才升格可注入;先建评测集再开 auto_inject。
 - **R7 知识库代谢:只进不出必腐化(用户 10-05 拍板)**:现状知识库只加条目、无 update 进化机制。蒸馏入库必须先查存量——相似条目走 update(合并/修正/增强)而非新增,防同主题碎片堆叠;条目短小精准(单条单事实,宁短勿滥)、带时效(过期检测)与使用频率,常用上浮、久未用沉降、被证伪淘汰,形成代谢闭环(参照 u-claw 知识库冷热分层:沉降/激活/消亡/代谢)。知识不在多,在于精、巧、即时。
  - 精细化设计:`docs/02-架构设计/专项设计/知识库模型重审-精细化设计-2026-10-05.md`(六用例走查+五场景推演+实施序;现状实证:向量 0/1073、verified 2%、置信 87% high——三项地基数据)
 - **R8 架构统一性:三套体系并行 vs 统一条目模型(可扩张性/优雅性审查)**:现状压缩段(消息 id)、外置件(路径)、知识条目(知识 id)三套标识、三个模块并行,信息在热/温/冷三层流转时身份断裂,溯源靠约定。优雅解 = 统一信息条目模型:唯一 id + 内容 + 溯源 parent 链 + 元数据(相关性/时效/频率/归属),生命周期状态机 hot→warm→cold→dead,流转动作(compress/reload/distill/inject/merge/evict)即状态转移;新策略(相关性/时机/蒸馏)= 转移策略可插拔,新存储后端 = warm 层 trait 实现,四类卡/知识条目 = 同一 schema 的类型扩展。多 agent/云端多人预留:条目元数据现在就留归属字段(与设计 §十 演进预留对齐)。
 - **R5 外置区边界**:工具输出可能含密钥等敏感信息,外置明文落盘需权限面;清理策略(会话删除级联 vs 长期资产)需显式定,防两读。
 - **R6 效果度量**:无度量则无法迭代。三指标:重载命中率(重载后解决问题的比例)/ 误压率(重载回来说明压错的)/ 蒸馏采纳率(条目注入后被引用比例)。ai_messages 全程记录,评测基建现成,凌晨窗口数据即首个测试集。
 ### 分工口径
 - 10-04 设计(记忆卡结构/压缩时机/分期路线)= 实施主依据;本段增量 = R1-R6 风险条款 + C-r0/C-r1 两个设计外条目 + 水位兜底与相关性判据输入。
 - 数据复现:ai_messages 按 conversation_id + timestamp 可复现全部实测。口径:AI-Ops 2026-10-05。
 ## 提交纪律反馈-1005(AI-Ops 核查)
 > f6eb55b(11:56)审查:内容与敏感面✅,形式三处待改——①一笔混 4 功能(u-claw集成/WebChat/项目归档/审批重设计),下次按功能分组拆笔;②多主题细节下沉 body,不留空 body;③设计文档/问题记录独立「文档:」笔,不混功能提交。
 **根因(2026-10-05 AI-Ops 查证)**:提交纪律从未进入系统提示 — prompt.rs(981 行)工具纪律完备,「提交/commit/攒批」零命中;git 能力随工具下发而纪律未同源下发,违反本项目自己的「纪律随工具同源下发」原则(prompt.rs:213)。长会话中仅存于上下文的约定被稀释,提交质量全凭运气。
 - [ ] **P0(升级版,2026-10-05 拍板)行为规范数据化治理**:devflow 定位 ai-working,行为规范会持续增多,不走「每条硬编码 prompt.rs」。架构=三层(铁律层 prompt.rs 现有工具纪律不动 / 规范层知识库 review_rule 条目(提交规范 5 条落为首批,带 enabled/scope)/ 任务层 pinned_goals 已有)+ prompt.rs 增一个通用规范注入口(读启用的 review_rule 拼入 system_prompt,一处代码永久扩展点)。扩展=加条目零代码;治理复用知识库 R4/R7(置信/代谢);观测=违规事件反哺条目置信(与 UC3 同机制)。验收:提交规范 5 条以 review_rule 数据条目生效;新加一条规范不改代码。
 **首批规范条目扩容(2026-10-05 第二案,拆分提交卡循环触发停滞保护)**:任务策略类 2 条与提交规范同期落库——
 - *批量分类/分组任务*:先一次性取全貌(如 git show --stat),制定分组映射表再机械执行,禁止逐文件深潜分析(实证:56 文件拆分反复 grep 卡停靠)
 - *自换策略检查点*:同签名工具调用连续 2 次无新信息即主动停手换策略,不等熔断器(熔断是最后防线非第一反应)
 - *停滞保护提示增强*:停靠消息自动附疑似病因与建议方向(现状只说"补充新方向",用户无从下手)
 **审查修订(同日三维度红队)**:①review_rule 条目加 constraint 声明,注入时约束段「必须」句式独立成段,与参考记忆物理分开;先核 61 条存量语义纯度 ②注入配额:启用条目 ≤20 条/1.5K token,超出按 scope+置信+频次取 top,条目单条单规则 ③规范声明可执行性两级:可执行化(如提交规范→提交后确定性校验)配自动检查器,原则性走 LLM 低频抽查 ④agent 沉淀规范前一句话确认防误判临时要求;每轮组装读库保即时生效(成本实测);注入日志标记条目命中便于排查;管理 UI 复用知识库界面。
 ## 基础设施走查-1005:存储空间治理与进程自检(AI-Ops 分析移交)
 > 实测:DB 168MB,实数据仅 ~69MB(ai_messages content 22MB + tool_executions.result 41MB + 其他 ~7MB),近 100MB 为 SQLite 空闲页/碎片空转;WAL 15.9MB;增速 1-5MB/天。核心查询 14ms 当前无性能压力——问题是空间,不是速度。
 ### D1 空间止血(一次性)
 - [ ] **D1 VACUUM 回收**:①备份 DB 并登记台账(铁律)②关 devflow.exe(或空闲时)③`VACUUM` + `PRAGMA wal_checkpoint(TRUNCATE)`。预期 168MB → ~70MB。注意:VACUUM 全表锁,勿在会话进行中做。
 ### D2 空间机制(防再膨胀)
 - [ ] **D2a tool_executions.result 过期外置**:超 30 天的执行结果本体移出库落归档文件,库内留路径句柄(与 C5 外置同构,一套机制两处用)。预期消掉 41MB 最大头的增长。
 - [ ] **D2b 定例化**:月度 VACUUM + 启动时 WAL checkpoint(挂启动流程)。
 - [ ] **D2c 体积水位监控**:文件/实数据比 >1.5 告警,进 agent-monitor。
 - [ ] **D2d 归档会话消息过期**(阈值待用户拍板,建议 90 天):archive 会话的消息到期物理清理+VACUUM。
 ### D3 其他走查项(按优先级)
 - [ ] **D3a 换装后就绪自检**:换装重启后探测「DB 可写/IPC 通/provider 可达」再宣布就绪(凌晨换装引发消息闪失暂态的根治配套)。
 - [ ] **D3b timestamp 索引**:ai_messages 加 timestamp 索引(一条迁移,监控/统计类查询从全表扫变索引)。
 - [ ] **D3c 单连接 Mutex 复核**(08-02 存量 P1):挂机模式引入并发后复核触发条件是否已变,实测锁竞争再定方案。
 - [ ] **D3d df-nodes HTTP 连接池**(存量 P1):工作流高并发才触发,场景未到,标记缓治。
 > 分工口径:storage/migrations 机制内实施;D1 需用户配合关应用;D2d 阈值待拍板。走查口径:AI-Ops 2026-10-05。
 > 换库评估结论(用户问询 10-05):**现在不换**——PG 的 autovacuum/并发/网络优势在单机桌面场景用不上,迁移是周级工程;空间痛点 D1-D3 治理用 1/10 成本拿 80% 效果。云端多人(S3)启动时:**服务端用 PG**(多租户),桌面端 SQLite 不动(本地缓存/离线),同步桥连接——换库是分层不是替换。
 > 量级基准修正(用户 10-05:按全部 u-claw 实例+Claude Code 数据 ×10):实测全生态 ≈2.1GB(本机 ~/.claude 2.0G 大头是会话 jsonl 流水,六容器实例合计 <25MB),×10 ≈ 21GB。21GB 走分层不进主库——流水外置文件(Claude Code 自身即先例:jsonl 存会话不用 DB),主库装结构化条目,GB 级内 SQLite 稳定。结论不变:**现在不换库**;C5 外置分层从"优化项"升为"量级前提"。
 > **存储架构定稿**:`docs/02-架构设计/专项设计/数据存储架构-定稿-2026-10-05.md`(四维评估收敛:分层+统一条目模型+同步桥+治理度量,四预留字段随 C-m1 一次建齐)
 > 分布式跨端协同预留(用户 10-05):跨端协同靠同步层不靠换网络库——各端 SQLite 自治(离线优先),同步 = 条目级变更事件流(append-only)复用既有 u-relay/df-tunnel 通道;冲突普通条目 LWW、关键实体走状态机(task_state_machine CAS 先例);外置件用内容哈希做 id(去重/可验证/任意端拉取);云端多人时服务端 PG 作汇聚点。前提依赖 R8 统一条目模型——条目需带 origin(来源端)与修订标记,实施 C-m1 建模时一并落。