PMFlow/docs/superpowers/specs/2026-04-17-unified-project-ai-handoff.md

Unified Project AI Handoff

Purpose

这份文档是给下一窗口直接续写用的 handoff。

目标不是继续把 internal / external / planmode 当成 3 个割裂模式分别修，而是做一个统一入口的项目型 AI：

• 先理解当前项目
• 必要时获取外部资料
• 再决定是否把结论 handoff 给 plan

当前仓库里把三条链分开讨论，只是因为飞书上下文和短句 follow-up 很容易串线；最终产品形态不是“3 个分离模式”，而是“1 个懂项目的统一 AI”。这里的 planmode 只是对话简称；落到 repo 真名时，统一指 plan_mode 顶层 gate 和其后的 requirement_plan / draft_pending_confirm 主链，不新增一个新的 runtime route 名。

User-Aligned Goal

用户当前明确要的是：

一个懂 PMFlow 当前项目、能看当前仓库摘要、能结合外部资料做判断、再自然推进计划的 AI。

不是：

• 泛化聊天产品
• 单纯外部搜索框
• 单纯 requirement-plan 助手
• 靠关键词和正则硬切模式的路由器

Confirmed Defaults

这些是已经在对话里拍板过的默认策略，下一窗口不要再重新猜。

0. 禁止回到硬性语义和正则路由

这是硬约束，不是建议：

• 不准新增关键词仓去硬切 internal / external / planmode
• 不准新增正则路由 helper 去抢统一入口的决策权
• 不准把“像不像某类问题”当成执行层主判断依据
• 不准再用散落运行时代码的硬性语义拍板修飞书问题

允许做的是：

• 基于显式锚点
• 基于统一 Project Operating Context
• 基于单次结构化语义结果
• 基于统一 execution_recipe

不允许做的是：

• “看到适合吗就大概率 external”
• “看到怎么推进就直接 plan”
• “看到配置/系统/模型这些词就直接 internal”

1. 默认多意图策略

固定为 A：

• 先给基于当前项目的判断结论
• 再明确给一个“是否基于这个结论进入 plan”的下一步

不是：

• 先追问用户要不要开 plan
• 也不是只要像建议题就直接进 plan
• 也不能覆盖已命中的 plan_mode 强锚点或 active requirement / draft 主链

2. 默认上下文范围

固定为：

• 当前项目
• 当前仓库摘要
• 当前线程 / 页面 / reply 强锚点

这里的“当前仓库”按 repo 现状应理解成“运行时拿得到的 codebase snapshot / repo summary”，不是默认已经拥有全 workspace、全语言、全目录的完整理解；当前 codebase overview 仍偏 backend snapshot，这一点要保持诚实。

暂不默认扩到：

• 用户名下所有项目
• 整个租户 portfolio

原因：先把当前项目型 AI 稳住，避免重新回到全局聊天串线。

3. Internal / External / Plan 的关系

不是三个平级产品模式，而是：

• internal：内部事实、对象状态、项目画像、适配约束
• external：外部资料、方案、生态、官方信息、可核验证据
• planmode：后续推进能力，不应该抢掉“判断题”的第一响应；repo 真正落地时仍由 plan_mode gate 和 requirement_plan / draft_pending_confirm 主链承接

推荐的执行顺序是：

统一上下文 -> 统一入口裁决 -> internal/external 产出 -> plan handoff

4. External 允许吃 internal fit brief，但 final answer 仍 external-only

这是一个关键边界：

• internal 可以先生成 Project Fit Brief
• external planner 可以用这个 brief 去约束外部检索
• 但 external 最终正文和外部证据仍必须保持 external-only contract
• 这个 brief 只能作为 pre-retrieval planning input，不放宽单一 source_policy 和“不混搜 internal + external 证据”的 repo 现有边界

也就是：

• 可以“先懂项目，再去搜外部”
• 不可以“把内部事实混成外部证据一起答”

Root Problem Statement

用户当前最不满意的，不是单独某一条链不够强，而是：

1. 飞书里的统一入口很混乱

同一句话系统经常分不清：

• 是在问内部系统问题
• 是在问外部问题
• 还是想基于外部问题顺手进入 plan

2. 复合意图问题没有被好好处理

像这些问题最典型：

• 这个适合吗
• 那要不要接
• 这个方案适不适合我们当前项目
• 那怎么推进

这些其实天然同时包含：

• 当前项目画像
• 外部资料判断
• 是否进入 plan 的手势

如果入口没有统一上下文层，就会继续在三条链之间乱跳。

3. 历史上加过太多硬性语义、关键词、正则，会让系统越修越乱

当前方向已经明确：

• 不准再在执行层补散落业务语义规则
• 不准再靠问题“长得像什么”去硬切模式
• 不准再用正则和硬编码语义兜底飞书入口
• 必须回到对象/上下文优先

Current Plan Of Record

当前正式计划文件：

2026-04-17-unified-project-operating-context-and-three-lane-handoff.md

这份计划不是“只做上下文”的计划，而是：

• 先补统一上下文层
• 再统一入口裁决
• 再整合 internal / external / planmode

只是执行顺序上，先修地基，再接三路。

New Requirement Added After Plan Draft

用户补了一个非常重要的要求：

飞书问题清单还不够，必须先收集并固化，再开始真正实现。

所以计划里已经新增了前置 Task 0：

• 先做 Feishu 问题清单 + 黄金对话样例
• 再做统一上下文和三路整合

这是一个硬前置，不应跳过。

Feishu Problem Inventory Direction

下一窗口优先应该收的问题类型包括：

1. reply/thread 锚点丢失或绑错
2. internal / external / planmode 误分流
3. 外部问答后续一句话错误掉进 internal 或 plan
4. “适不适合 / 推荐什么 / 怎么推进” 这类复合问题被拆错
5. 同群同人 scope 串线
6. 旧 active context 劫持新问题
7. 明明该继续 plan，却掉回 query.answer
8. 明明只是问结论，却被直接拉进 plan
9. 卡片动作和纯文本行为不一致
10. Web 和 Feishu 对同一句话给出不同链路

这些不只是问题分类，还应该进一步整理成黄金对话样例和回归测试。

User-Visible Gains To Preserve

下一窗口如果继续设计或实现，不要只谈架构，要一直回到这些“实际收益”。

场景 1：外部工具是否适合当前 PMFlow 项目

用户问：

OpenAI Docs 这种能力适不适合我们现在这个项目？

目标行为：

• 先基于当前项目判断适不适合
• 明确说明原因、代价、适配点
• 再给一个“是否进入 plan”的下一步

不是：

• 泛泛讲功能
• 直接进 plan
• 或掉成纯 external 搜索

场景 2：飞书线程里一句“这个适合吗”

目标行为：

• 能认出当前线程正在讨论哪个对象
• 能站在当前项目上回答“适不适合”
• 先答结论，再给 plan 入口

场景 3：结合当前 repo 判断外部方案

用户问：

如果我们想把 GitHub repo 信号也接进来，现在仓库里有没有基础？

目标行为：

• internal 先看当前 repo / current project capability
• external 再补行业做法和方案证据
• 最后回答成一个贴当前项目的判断

场景 4：战略判断题

用户问：

semantic facts 这条线还值不值得继续做？

目标行为：

• internal 知道当前项目已经做到哪
• external 辅助做对照
• 回答成一个项目管理判断，而不是搜索结果堆砌

场景 5：自然接到 plan

用户在上一轮判断后只回一句：

那按这个推进

目标行为：

• 直接 handoff 给 plan
• 不再重新问 internal / external / plan 是哪种模式

What This Work Should Solve

如果这轮做完，至少应该明显改善这三件事：

1. 用户不用反复重述“我是说当前 PMFlow 项目”
2. 外部判断题不再和 planmode 争第一响应
3. 飞书短句 follow-up 不再在三路之间随机乱跳

What This Work Does Not Automatically Solve

要对下一窗口保持诚实边界：

这轮统一上下文和三路整合，不自动等于修完所有飞书历史 bug。

如果底层仍存在这些问题，还需要单独查：

• canonical thread mapping 本身出错
• reply outbox / sent_message_id -> source_message_id 归一化异常
• card action 回流上下文丢失
• Feishu transport 层事件字段不完整

也就是说：

这轮会解决“入口理解和三路 handoff 混乱”的大头问题， 但不是自动包治所有 Feishu 基础设施问题。

Recommended Starting Point For The Next Window

不要直接进实现。

下一窗口最合适的顺序是：

1. 打开并继续使用这两份文件：
   • 2026-04-17-unified-project-ai-handoff.md
   • 2026-04-17-unified-project-operating-context-and-three-lane-handoff.md
2. 先执行计划里的 Task 0
3. 先把 Feishu 问题清单 + 黄金对话样例 写出来
4. 再决定是否继续进入上下文层实现

One-Line Summary

下一窗口要接着做的，不是“继续拆 3 个模式”，而是：

先把飞书问题清单收完整，再把 internal / external / plan 收到统一项目上下文下面。

补充硬约束：

整个过程中不准回到硬性语义、关键词仓或正则路由。

Final Architecture Baseline

这部分是本轮已经拍板的终态基线，下一窗口不应再偏离。

1. PMFlow 的目标形态是 统一项目型 AI，不是 3 个割裂模式。
2. 顶层一定先有 Project Operating Context，默认范围固定为：
   • 当前项目
   • 当前仓库摘要
   • 当前线程 / 页面 / reply 强锚点 这里的“当前仓库”是运行时可取得的 repo summary，不默认等于全仓库完整理解。
3. 顶层仍先尊重 repo 现有的 plan_mode gate；只有非 plan 主链的 recommendation / query 流程，才继续产出统一的 execution_recipe，再决定：
   • 走 internal
   • 走 external
   • 还是在回答后 handoff 给 planmode
4. internal 的职责是：
   • 内部对象事实
   • 当前项目画像
   • fit brief
   • 适配约束
5. external 的职责是：
   • 外部资料
   • 官方/公开证据
   • 可核验推荐
   • 外部影响判断
6. 这里的 planmode 只是对话简称，repo 真正落地仍是 plan_mode gate + requirement_plan / draft_pending_confirm 主链。
7. planmode 不再抢第一响应。 默认策略固定为 A：
   • 先给基于当前项目的判断结论
   • 再给一个明确的 plan handoff 下一步
8. external 可以消费 internal 生成的 fit brief，但 final external answer 仍必须保持 external-only：
   • 不混 internal 证据
   • 不把 system_snapshot / user_snapshot / project_context / internal context_blocks 重新注入 external presenter
   • 不放宽单一 source_policy 和 v1 不混搜 internal + external 的 repo 基线
   • 最终展示仍遵守 customer_safe / admin_debug 双视图边界
9. 强锚点优先级高于默认策略：
   • 显式 reply/thread
   • 显式 work_item_id
   • 已绑定 active requirement / draft context 这些命中后可以直接进入 plan 主链。
10. 飞书问题必须先通过 问题清单 + 黄金样例 + 回归测试 验收，不能只看架构是否漂亮。
11. 整个方案禁止回到硬性语义、关键词仓和正则路由。

一句话终态：

先理解当前 PMFlow 项目，再决定内部取证、外部取证和计划推进如何接棒；默认先答判断，再给计划入口。