# USER.md

本文件是这个用户在本项目内的主真源。
目标不是堆规则，而是让我在这个项目里越来越懂这个用户，稳定贴合其协作方式、判断方式、已拍板决策与反复踩过的坑。
工程、系统、安全与验证硬约束仍以 `AGENTS.md` 和更外层提示为准；若 `~/.codex/AGENTS.md` 与本文件冲突，以本文件为准。
未写进这里的内容，不默认视为本项目内已拍板决策或稳定偏好。

## 协作偏好

### 长期稳定偏好

- 默认先自己读项目、历史、日志、配置和运行痕迹；不要把本该我自己挖出来的东西再反问给用户。
- 默认直接推进；只在高风险分岔、破坏性操作或根因不明时停下来确认。
- 回答要直接、具体、贴当前对象，优先给证据链、调用链和真实落点；不要写成模板化汇报。
- 不确定就明确说不确定，不要假装完整。
- 已拍板方案不要反复推荐替代品；配置和偏好尽量收敛，别分散。
- 前端默认视觉标准：品牌主色固定为 `#2463EB`；浅色界面默认以白色 + `#2463EB` 为主，不再回到泛紫、泛青的 AI 套板。
- 前端默认交互和样式参考 `Linear` 的克制层级与节奏；所有用户可见内容默认使用中文，除非我明确要求保留英文。
- PMFlow 原型图默认标准：统一使用浅色白底 + `#2463EB` 主色；整体交互密度、节奏、层级、边界处理默认参考 `Linear` 的产品气质，但不照搬品牌元素；原型图内所有用户可见内容、页面标题、按钮、状态、说明、标注默认全部使用中文；默认需要考虑移动端适配，原型设计时同步关注移动端信息层级、导航结构、单手操作路径、底部安全区、滚动区域与关键交互在小屏上的可用性。
- PMFlow Logo 默认标准：以用户在本轮提供的品牌规范图为唯一 Logo 方向；主标识使用蓝色几何图标 + 深色 `PMFlow` 字标组合，图标主色沿用 `#2463EB`，字标使用深色中性黑灰；图标可独立用于应用图标、侧边栏、favicon、移动端入口和小尺寸场景；后续不要再重新发散生成其它 Logo 风格。
- PMFlow 移动端底部导航默认标准：项目创建前（新项目启动台 / 首次进入 / 草案确认流程）不展示全局底部导航，只保留顶部上下文、单列主内容、底部主 CTA 和 AI 底部抽屉；项目创建后进入正式应用壳，底部导航固定为 5 项且不得漂移：`空间`、`指挥台`、`待确认`、`动态`、`我的`。`空间` 是所有项目/想法/草案的上层入口，`指挥台` 是当前项目主工作面，`待确认` 聚合 AI 生成但需用户拍板的事项，`动态` 聚合 AI 进展/回写/系统事件，`我的` 承载账户、设置和个人偏好。具体项目内的 `工作台 / 开发执行 / 发布增长 / 项目记忆` 不进入底部导航，默认通过项目内二级入口、分段切换或更多菜单进入。
- PMFlow 同一功能原型一致性标准：同一功能一旦出现已确认原型或实现，后续再出图、改图或开发时必须先沿用该功能的既有定位、信息架构、导航壳、核心对象、状态标签和视觉语法；只能在此基础上新增状态、补充局部区域或做明确版本迭代，禁止把同一功能重新设计成另一套页面。若确实需要重构，必须先说明“旧版是什么、新版改什么、迁移影响是什么”，并得到明确确认。比如 `项目记忆` 必须区分为同一功能下的 `项目记忆主视图` 与 `项目记忆写入结果态`，二者应共享同一项目壳、对象分类、证据/确认/写入语义和右侧 AI 副驾规则，而不是两套互不相干的页面。
- PMFlow 高保真原型默认不能按“桌面原型画布宽度”锁死主内容区。桌面保真不等于固定画布：必须同时考虑普通桌面、超宽屏和小屏三档。默认规则是：
  - 普通桌面宽度保持原型密度与节奏；
  - 超宽屏必须继续扩展主内容区，或设置明确且足够宽的内容上限（如更合理的 wide container），不能让右侧出现大面积无意义留白；
  - 小屏必须改为堆叠/抽屉/分段，不允许直接压缩桌面三栏。
- 做 PMFlow 这类多栏产品时，默认先检查这三个点：`主内容是否被隐性画布宽度卡死`、`超宽屏是否吃满可用空间`、`右侧留白是否来自容器上限而不是业务布局本身`。
- 当前产品原型与首版体验默认面向个人开发者与 `1-10` 人小团队，采用 `solo-first, team-ready` 方向；不要按 `10-50` 人重型团队工具去设计。
- PMFlow 产品蓝图真源已沉淀到 `docs/PMFLOW_PRODUCT_BLUEPRINT.md`：PMFlow 是“对话驱动的 AI 产品执行操作系统”，不是聊天工具 + 项目管理工具，也不是 Jira 加 AI；后续产品/原型/实现默认围绕 `Project Thread -> Structured Extraction -> ChangeSet Review -> Project Memory -> Work Graph -> Execution Bridge -> Release/Growth Feedback` 主链推进。
- 团队方向已拍板为“AI-native team operating system”：单人版解决“一个人如何像团队一样推进”，团队版解决“小团队如何围绕 AI 维护的项目真相层，通过异步审查和人机混编执行协作”；不要退回传统多人维护任务表、开会同步、手动填状态的项目管理范式。
- PMFlow AI 可用状态已拍板为“双层表达”：用户端默认只表达客户可理解的业务影响、可继续动作和保护规则，不暴露供应商、路由、模型槽位、连接测试、trace、函数名或平台诊断；平台人员进入用户端也先看客户视图，只有显式平台诊断入口才看具体原因和 CTA。`/platform/*` 是平台 AI Ops 控制面，默认展示供应商、路由、诊断、模型槽位、失败样本和对应处理动作。
- PMFlow 产品推进执行标准已沉淀到 `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`：后续每次 PMFlow 产品推进任务完成后，Codex 默认要自己更新该文档的进度台账；新增/修改入口、API、Schema、边界时同步更新 `CLAUDE.md`、`ARCHITECTURE_INVENTORY.md`、`CODE_REFERENCE_INDEX.md`、`API_CONTRACTS.md` 或 `RUNTIME_GUARDRAILS.md`。新开线程继续产品推进时，必须先读 `USER.md`、产品蓝图、执行标准、`CLAUDE.md` 和代码索引，不得从头重想方案。
- 原型图与首版视觉交付默认只做浅色主题，不要求同时输出暗色模式；暗色模式属于后续产品实现能力，不作为当前原型标准。
- 后续只要我在本项目里让你“出原型图 / 重画原型 / 生成产品视觉稿”，若我没有额外说明，就自动沿用这套原型图标准，不要再回到深色、紫色系、英文 UI 或泛后台风格。

### 学习与更新方式

- 会话里要持续吸收用户纠正，不要让用户反复教同一件事。
- 用户纠正某次排障或分析方式时，要吸收背后的通用思路，迁移到后续问题中；不要只把反馈当成这一次案例的补丁。
- 学到的是方法论，不是死模板：后续先找最小对照/反证，再分层定位根因并验证；但要按具体问题调整，不要机械套步骤。
- 反复出现、会长期影响判断的偏好，要主动沉淀到本文件。
- 一次性情绪、临时波动和不影响后续决策的内容，不要频繁落盘。
- 非必要不要更新真源文件；只有新信息足够稳定、能减少误判或能减少用户重复纠正时，才值得更新。

## 判断优先级

### 什么时候才准问用户

- 先自己查。能从代码、配置、历史、日志里读出来的，别问用户。
- 只有这几种情况才停下来：
  - 要做破坏性操作
  - 方案真的分叉了
  - 根因没搞清，继续改大概率越改越歪
- 问的时候别铺垫，直接说：已经查到什么、卡在哪、要用户拍哪个板。

### 改错后的默认动作

- 错了就指出具体错点，别演。
- 能直接补就直接补，补完再说原因、影响和验证。
- 有扩散风险先止血，再继续修。
- 别把一次纠错搞成新的流程负担。

### 冲突时怎么取舍

- 先查主链、上下文、路由和证据，别上来就改 prompt、补词表、补正则。
- 显式 `reply/thread`、卡片动作和当前 requirement context 优先于旧 session 和记忆续写。
- 已经进入 `requirement_plan` / draft confirm 的线程，后续必须留在对应主链，不要掉回普通 QA。
- AI 架构类回答优先讲当前调用链、入口、路由和模型网关，不要退回通用技术栈摘要。
- 证据不足时直接说不确定，不要用模板化确定性答案补满。
- 已经定过的方案别来回摇。

## 已拍板技术决策

- 后端：FastAPI + Python 3.11+ + SQLAlchemy 2.x + Alembic
- 前端：React 18 + TypeScript + Vite
- UI / 样式：shadcn/ui 风格组件层 + Radix UI + Tailwind CSS
- 数据与缓存：PostgreSQL + pgvector + Redis
- 鉴权：OAuth2PasswordBearer + JWT
- 部署：Docker Compose
- 验证基线：后端 `python -m py_compile` + 相关单测；前端 `npm run build` + `tsc --noEmit`
- AI 路由对外名称：PMFlow 本地路由层
- AI 路由内部主名：`control_plane`
- 路由规则真源：`backend/.control_plane/pmflow-routing-rules.json`
- 模型策略：业务代码不要硬编码模型名；provider / tier / model 由路由规则决定
- Prompt 策略：新增或修改运行时 LLM prompt 不得直接写死在业务服务/API 中；必须先进入 Prompt 运营中心资产合同（`ai_prompts.py` 默认模板 + `ai_prompt_registry.py` 注册 + active `prompt_releases` 运行时读取），并在 `ai_call_logs` 写入 `prompt_key / prompt_release_id / prompt_source` 归因。历史 `needs_migration` 存量只能作为待迁移清单，不得作为新增写法。
- 历史路由命名已废弃，不再把旧名字当现行架构，也不再建议回退
- 以上栈默认不再主动建议替代方案，除非用户明确要求比较或迁移

## 反复踩过的坑 / 不要再做

- 把“AI 架构”答成通用技术栈总览，而不是当前调用链、入口、路由和模型网关。
- 证据不足时还给模板化的确定性答案。
- 短协议回复掉回通用 QA，不按当前 `thread` 和上一轮选项解释。
- 飞书连续追问时继续沿着旧上下文跑，不先尊重显式 `reply/thread`。
- 用户纠错后不先纠正当前主题，还带着旧主题继续扩写。
- 遇到链路问题先补 prompt、关键词、正则，而不是先查 routing、context、session、gatekeeper。
- 用 fallback、默认句、stub、模板话术冒充成功。
- 把本该直答的问题拖进过深推理、官样文章或汇报体输出。
- 做高保真原型时把页面按“桌面截图尺寸”做成隐性固定画布，导致超宽屏右侧出现大面积未使用留白；以后默认按“桌面保真 + 超宽屏扩展 + 小屏重排”三档检查，不再只盯原型图单一尺寸。

## 前端快回路与线程治理

### 前端任务分级

- `L1 微调类`：文案、字重、边框、间距、颜色、单元素位置。默认只允许 focused live 页确认或快验证，不默认跑 full build。
- `L2 视觉逻辑类`：响应式、跨屏对齐、布局算法、曲线路径、动画节奏。允许 `build + 多视口截图`，但不夹带无关文案和样式修补。
- `L3 结构治理类`：拆组件、拆路由、拆包、改 compose、改启动链路。必须单独线程处理，不和单页 comment 修复混做。

### 线程是否继续的判断规则

- 同一对象、同一路径、同一验证面，优先留在原线程直接做完。
- 满足任两条时，优先新开线程继续：需求从分析切到实现；目标文件集合明显变化；验证方式变化；用户开始要求“完整方案/全仓整治/顺手再修几个点”；同一核心文件重复读取；线程已经发生 context compaction；已经拖过 15 分钟还没形成第一个闭环。
- 当前改动已经能独立闭环时，不顺手带 unrelated fix；尤其不要把 `L1 微调` 混进 `L2 视觉逻辑` 或 `L3 结构治理`。

### 强制止损阈值

- 同一线程出现 `context_compacted` 后，如果任务仍未闭环，优先建议切新线程；出现两次 compaction，不再继续混合任务。
- 从用户发起到首次实际代码编辑超过 `8` 分钟，必须先说明卡点，不继续闷头探索。
- 同一核心文件读取超过 `2` 次，必须先总结当前判断，再决定是否继续读。
- 同一轮工具调用超过 `20` 次但仍没有形成首个有效闭环，必须收口范围或切线程。

### 前端验证预算

- `L1 微调类`：优先 `verify:login-fast` 或 focused screenshot，不默认跑 `npm run build`。
- `L2 视觉逻辑类`：优先 `verify:login-responsive` 或 `capture:login:matrix`，验证目标是跨尺寸一致，不是单视口碰巧正确。
- `L3 结构治理类`：独立线程里跑 `typecheck + build + focused smoke`，不拿页面 comment 回合承载。

## 当前知道但暂不处理的项目问题

- SQLite 已废弃，不作为当前运行时或正式技术方案；但少量历史测试夹具仍沿用 SQLite 内存库。
- `backend/tests/test_training_pipeline_service.py` 目前仍有历史 SQLite 测试夹具下的 `JSONB` 建表失败问题，这不是本轮改名引入的，需要单独清理测试基座。
- `backend/app/schemas/recipe.py` 与 `backend/app/schemas/skill.py` 仍有 Pydantic V2 的 class-based config deprecation 警告。
- 当前运行环境里的 `lark_oapi` / `websockets` 仍有上游 deprecation 警告，后续需要统一升级或兼容处理。
- Project Launch 失败页需要后续补产品化排查能力：展示本次请求耗时、后端 trace id、后端是否稍后成功生成草案，并提供“恢复最近草案”入口，用于定位前端超时/代理断开但后端实际成功的情况；当前先记录，不实现。