PMFlow/USER.md

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、后端是否稍后成功生成草案，并提供“恢复最近草案”入口，用于定位前端超时/代理断开但后端实际成功的情况；当前先记录，不实现。