# 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](/Users/yuuuu/Documents/AIProjectManger/docs/superpowers/plans/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](/Users/yuuuu/Documents/AIProjectManger/docs/superpowers/specs/2026-04-17-unified-project-ai-handoff.md)
   - [2026-04-17-unified-project-operating-context-and-three-lane-handoff.md](/Users/yuuuu/Documents/AIProjectManger/docs/superpowers/plans/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 项目，再决定内部取证、外部取证和计划推进如何接棒；默认先答判断，再给计划入口。`