From fef2df119d4f886aace2adb50387448d50f53f44 Mon Sep 17 00:00:00 2001 From: john Date: Fri, 28 Aug 2026 20:45:41 +0800 Subject: [PATCH] docs(architecture): record Intent Layer V1 assessment against current runtime. Keep Context Stability First as the active plan, document reuse vs conflict, and freeze the 15-question answers so the next session does not redesign from scratch. Co-authored-by: Cursor --- .../chat-task-intent-layer-review-20260828.md | 2 + .../intent-layer-v1-assessment-20260828.md | 129 ++++++++++++++++++ 2 files changed, 131 insertions(+) create mode 100644 docs/architecture/intent-layer-v1-assessment-20260828.md diff --git a/docs/architecture/chat-task-intent-layer-review-20260828.md b/docs/architecture/chat-task-intent-layer-review-20260828.md index adfb9b3..81e3ae0 100644 --- a/docs/architecture/chat-task-intent-layer-review-20260828.md +++ b/docs/architecture/chat-task-intent-layer-review-20260828.md @@ -41,6 +41,7 @@ | [Intent Transaction Layer 设计](../intent-transaction-layer-design.md) | ITL 管**有副作用的创建动作**（提醒/定时）的 Draft→Confirm→Commit；本文管**多轮对话中的任务识别与执行移交**，两者并列，不应合并进同一分类器 | | [SSE 断线续播守卫](../regression-guards/h5-session-stream-replay.md) | 本文 P2 触及 `agent-run-gateway` session 路径，改动须重跑该守卫 | | [Orchestrator 边界](./memind-orchestrator-boundary.md) | 本文不改变 Portal = control plane、Goose/Orchestrator = execution 的划分 | +| [Intent Layer V1 对照评估](./intent-layer-v1-assessment-20260828.md) | 外部 Goal Lock / Planner / Evaluator 提案与现网对照；**不改变本文 §11 为当前开发主线** | --- @@ -562,3 +563,4 @@ direct-chat-service.mjs:141 | 2026-08-28 | 初版：R1–R3 根因核查、原 Task Runtime 方案评估、P0–P6 目标形态 | | 2026-08-28 | 增补 §11 最低影响实施方案：将 P2 的实现方式从 `execute_task` 修订为「让已有 LLM router 在聊天会话可达」，暂缓 tool calling；P1 收窄为仅 P1.1；P3 收窄为仅 `h5direct_` 纠偏 | | 2026-08-28 | 增补 §12 Memory V2 兼容性：三条注入路径现状、各阶段影响、四条强制要求 | +| 2026-08-28 | 交叉引用 [Intent Layer V1 对照评估](./intent-layer-v1-assessment-20260828.md)；开发顺序仍以本文 §11 为准 | diff --git a/docs/architecture/intent-layer-v1-assessment-20260828.md b/docs/architecture/intent-layer-v1-assessment-20260828.md new file mode 100644 index 0000000..6d8e4d7 --- /dev/null +++ b/docs/architecture/intent-layer-v1-assessment-20260828.md @@ -0,0 +1,129 @@ +# Intent Layer V1 与现网架构对照评估 + +日期: 2026-08-28 + +状态: 只读仓库核查完成；**不作为当前开发主线**。当前开发主线仍以 [聊天 ↔ 任务执行意图层评估](./chat-task-intent-layer-review-20260828.md) 的 Context Stability First（§11）为准。 + +适用范围: + +- 外部提案「TKMind Intent Layer V1」（Intent Relation → Goal Compiler → Goal Lock → Planner → Evaluator）。 +- 对照对象：`main` 上已落地的 Portal / goosed 主链路，以及同日的 chat-to-task 评估文档。 + +非目标: + +- 不把 V1 全文再抄进仓库。 +- 不在本文件中授权新建 goals/plans/tasks/observations/evaluations 表系。 +- 不替代 [Intent Transaction Layer](../intent-transaction-layer-design.md)（副作用 Draft→Confirm→Commit）。 + +--- + +## 0. 结论 + +V1 的核心原则成立：**Goal ≠ Plan，Replan ≠ Re-goal，Goose 应逐渐变成 Executor 而不是唯一总控。** + +但 V1 **不能作为当前第一刀**。同日核查已经证明：H5 上可观测的「意图飘忽」主要由路由层 R1–R3 造成（direct→agent 上下文丢失、纯聊天会话 LLM router 吸收态、direct 安全网放行 + 谎报文案）。Task Resolver / 九态 FSM / Working Memory 权威化 **修不了这三项**。 + +更准确的定位： + +| 问题域 | 谁负责 | 当前动作 | +|---|---|---| +| 普通聊天如何正确升级为 Agent，并带上历史 | [chat-task-intent-layer-review](./chat-task-intent-layer-review-20260828.md) §11 | 阶段 A 观测 → B 上下文注入 → C 打开已有 LLM router | +| Agent 已进入复杂执行后，如何锁 Goal、验证完成、安全 Replan | V1 中后期能力 | **后置**；仅在有数据证明「多步状态丢失」是主因后再试点 | + +两套问题可以同时成立，不能互相否决。当前仓库**尚未读取 goosed 内核**，因此不能断言复杂 Tool Loop 内不存在重复规划；同样也不能在没有 R1–R3 基线数据时先上 Global Planner。 + +--- + +## 1. 必须先纠正的三个前提 + +1. **主 Portal 持久化是 MySQL（InnoDB），不是 PostgreSQL。** `schema.sql` + `db.mjs`。Postgres 仅用于旁路（pgvector、MindSpace 用户数据空间、Goose session、Orchestrator checkpoint）。V1 草案中的 `UUID` / `JSONB` DDL 不能直接套用；`h5_plan_catalog` 已被订阅套餐占用，不能再当 Agent Plan 表名。 +2. **Memind 每轮只向 goosed 提交 `{ request_id, user_message }`**（`tkmind-proxy.mjs` `prepareSessionReplyBody`）。完整历史与 Tool Loop 在 goosed 会话内。Goal Lock 若只锁 Portal 字段，对模型注意力是软约束。 +3. **当前主路径上意图 LLM 往往是 0 次，不是「反复解释」。** 规则兜底恒返回 `direct_chat` / 0.72；LLM router 入口要求 `activeTaskContext.hasRecentAgentTask`。纯聊天会话形成吸收态。`MEMIND_CHAT_LLM_ROUTER_ENABLED=1` 在生产打开，不等于聊天会话里真的会调用该 LLM。 + +--- + +## 2. 与现网能力对照（可复用 / 冲突 / 后置） + +### 2.1 应复用，不要重建 + +| V1 组件 | 现网对应 | +|---|---| +| Conversation Gateway | `POST /api/agent/runs` → `agent-run-gateway` → `tkmind-proxy` | +| Intent Router（路径选择） | `chat-intent-router.mjs`（规则优先 + 可选 LLM + shadow + minConfidence） | +| Goal 存储 | `goal-run-service.mjs`：`h5_goal_runs` / `h5_goal_checkpoints` | +| Goal 注入 | `goal-run-context.mjs` `buildGoalContextEnvelope` | +| 历史注入 | `agent-run-gateway.mjs` `buildFreshSessionContext` / `appendFreshSessionContext`（16 条 / 12000 字符） | +| 审计事件 | `h5_agent_run_events`（已有 `intent_routed` 等） | +| SSE 生命周期 | 双通道 run + session；`h5_session_stream_events` replay；Portal id ≠ goosed Last-Event-ID | +| 同 session 串行 | `SESSION_RUN_CONFLICT`（direct session 豁免） | +| Capability → 实际工具 | `capabilities.mjs` `buildAgentExtensionPolicy`；搜索域另有 `mindsearch-config` routes→adapter | +| 副作用意图 | ITL：`h5_intent_drafts` + Draft→Confirm→Commit | + +### 2.2 与既有决策冲突（当前不要做） + +与 [chat-task-intent-layer-review](./chat-task-intent-layer-review-20260828.md) §2 / §6 及 [H5 Session 架构](../h5-session-architecture-20260706.md) 冲突： + +- 每轮阻塞式 Intent Relation LLM（CONTINUE/REFINE/EXPAND/CORRECT/NEW_GOAL/CANCEL） +- 九态 Conversation FSM（含不可观测的 UNDERSTANDING / PLANNING） +- Working Memory / Goal Contract 取代完整会话历史作为权威源 +- 新建第四/第五套任务存储（现已有 `h5_agent_runs`、`h5_goal_*`、`h5_tasks`、`h5_scheduled_tasks`、Orchestrator job） +- Router 升级为多步 Global Planner +- 把 goosed 改成无规划哑执行器（与「不改 goosed 协议」、worker affinity、proxy 已有 tool/finish/billing 职责冲突） + +### 2.3 原则正确、时机后置 + +- Goal Version + `goal_hash`（审计列，挂在现有 `h5_goal_runs`，不新建表） +- Completion Criteria + 独立 Evaluator（仅用户显式长任务） +- Tool Raw 与 Observation Summary 分离（goosed 会话里 tool 结果目前全量保留） +- Capability Registry 从搜索域推广到全工具（加在 `buildAgentExtensionPolicy` 之上，不另起注册中心） +- Error Taxonomy、Prompt 版本记入 `h5_agent_run_events` +- 面向 UI 的语义 SSE（理解/规划/搜索），走现有 taxonomy，未知事件必须可忽略 + +--- + +## 3. 对 V1「15 个关键问题」的稳定答案 + +依据 2026-08-28 仓库只读核查（Portal 代码；**不含 goosed 源码**）。 + +1. **意图被 LLM 重新解释几次？** 规则 fast-path 下路由 LLM = 0。规则未命中且 LLM router 启用且非 shadow 时 = 1。Goal Run 绑定可能再 +1。下游再加 1 次 direct 回复或 goosed（含内部 Tool Loop，次数在 goosed 内，本仓库不可见）。 +2. **谁能改执行方向？** `chat-intent-router` 的 route/skill/agent_brief；`applyAgentOrchestrationToUserMessage`；skill 长 prompt；`injectTaskRoutingHint`；vision 注入注脚；`extension_overrides`；会话压缩清空历史；goosed Tool Loop。 +3. **Goose 是否同时 Global + Local Planning？** 不完全。Portal 已拿走 route/skill/brief；Goose 在自持会话内做局部规划与工具循环。边界模糊，不是「Goose 什么都管」。 +4. **Tool Observation 是否污染 Context？** 是。全量留在 goosed conversation；Portal 只配对修复，不摘要。压缩阈值约 180 条 / 120k 字符后清空并注入 16 条摘要。 +5. **有无 Active Goal？** 有 Goal Run 实体，但 `h5_user_sessions` 无 `active_goal_id` / `conversation_state`。Goal Run 默认单 checkpoint，且受开关门控。 +6. **有无 Completion Criteria？** 无。近似物是 checkpoint 人工确认和交付启发式。 +7. **有无独立 Evaluator？** 无。Page Data / workflow validation 为 shadow。 +8. **Intent Layer 插入点？** 已存在：`agent-run-gateway` `executeRun` 内 `resolveRunRouting`（约 `chatIntentRouter.classify`）。需要的是让聊天会话能走到已有 LLM 分支，而不是再插一层。 +9. **Goal 放哪一层？** Portal MySQL（现有 `goal-run-service`）。不要只放 Redis，不要放进 goosed。 +10. **Goal Lock 能否不改 goosed？** 能做 Portal 侧只读字段 + hash，但是软约束；压缩、harness 每轮重建、多层前缀仍会稀释 Goal。 +11. **Planner 边界？** Portal：route、skill、scope、goal envelope、run 生命周期。Goose：session、工具选择与顺序、task 内推理、局部 retry。不要让 Portal 重做 tool 卡片 / Finish / 计费变换。 +12. **Phase 1 最小改哪些文件？** 与 review §11 阶段 B/C 一致：`chat-task-intent-config.mjs`、`chat-intent-router.mjs`、`agent-run-gateway.mjs`、`direct-chat-service.mjs`（去谎报）。不要先做 Planner。 +13. **可直接复用？** 见 §2.1。 +14. **必须新增？** 若只做 B/C：**不必新建表或新服务。** 完整 V1 才需要 Plan/Observation/Evaluation 等，当前全部 not found。 +15. **最大三个风险？** （1）再叠一套任务模型；（2）Goal Lock 对 goosed 自持历史无强制力；（3）每轮新 LLM + 流量从「direct 必注入记忆」转到「agent 默认不注入记忆」。 + +--- + +## 4. 下一步（开发顺序） + +以 review **§11 为准**（与 §5 目标形态冲突时也以 §11 为准）。 + +1. **把工作区 B/C 草稿从脏 `main` 挪到基于最新 `origin/main` 的开发分支**，只含意图层文件与对应测试；不要混入计费/认证。未批准前不 commit / 不 push / 不发 103。 +2. **阶段 A 观测**：0.72 兜底占比、direct→agent 升级频率、升级后失忆、shadow `wouldChangeRoute`。无基线则不扩大 C。 +3. **阶段 B**：direct→agent 接入 `appendFreshSessionContext`。Flag `MEMIND_DIRECT_ESCALATION_CONTEXT_ENABLED` 默认关 + canary。升级轮次 memory resolve 使用旧 sessionId。 +4. **阶段 C**：歧义闸门通过时规则返回 `null`，交给已部署 LLM router。先 `SHADOW=1`，再 canary。保留记忆召回 / FAQ / 寒暄硬规则。盯 Memory 注入率。 +5. **阶段 D 及 V1 后置**：仅当数据证明短句纠偏失败或「多步状态丢失」后再做。显式长任务复用 Goal Run，最多加 version/hash 列。 + +验收命令（B/C 落地后）：`node --test chat-intent-router.test.mjs agent-run-gateway.test.mjs direct-chat-service.test.mjs chat-task-intent-config.test.mjs`；`npm run verify:h5-session-patches`；可选 `node scripts/verify-chat-task-intent-layer.mjs`。 + +--- + +## 5. 与 chat-task 评估文档的关系 + +| 文档 | 角色 | +|---|---| +| [chat-task-intent-layer-review-20260828.md](./chat-task-intent-layer-review-20260828.md) | **现行开发规范**：R1–R3、Context Stability、§11 落地路径 | +| 本文 | **对外部 V1 提案的对照结论**，防止下一轮会话把 V1 当成未评估的新架构再设计一遍 | +| [intent-transaction-layer-design.md](../intent-transaction-layer-design.md) | 副作用动作，与聊天↔Agent 路由并列 | +| [h5-session-architecture-20260706.md](../h5-session-architecture-20260706.md) | Portal control plane / goosed execution；router 禁止多步 plan | + +V1 若在阶段 A/C 之后仍要推进，必须先满足 review §9：用观测证明主因是多步任务状态丢失，而不是 R1–R3 未修。届时优先复用 Goal Run，而不是新表系。