docs: codify PMFlow product delivery governance
This commit is contained in:
parent
2eaf8e9deb
commit
b52428f79e
31
AGENTS.md
31
AGENTS.md
|
|
@ -204,6 +204,37 @@ frontend/ # React 前端
|
|||
- 发生 context 不足时 → 停止并输出已完成部分
|
||||
声明 `[CONTEXT: LIMIT]`，不要截断输出
|
||||
|
||||
## 17. Codex 并行开发治理
|
||||
|
||||
- 多个 Codex 线程并行推进时，执行单位必须是 `Packet`，不得以模糊“大模块”并行开工。
|
||||
- 每个 Packet 开始前必须有任务包，至少声明 `packet_id / owner_thread / base_ref / read_scope / write_scope / forbidden_paths / shared_files / depends_on / merge_after / verification / docs_to_sync`。
|
||||
- 没有 `write_scope` 的任务不允许并行；`write_scope` 重叠的 Packet 必须串行。
|
||||
- 每轮并行最多一个 `contract / migration / router owner`；其他线程只能消费该 owner 已定义的稳定接口。
|
||||
- 并行线程默认使用独立分支 `codex/<packet_id>`，并优先使用独立 git worktree；不得在同一脏工作区里让多个线程直接写同一批文件。
|
||||
- 一个 Packet 对应一个短生命周期分支；Packet 完成、验证通过、文档同步完成后必须形成可审查 commit。复杂 Packet 可在同一分支内做多个逻辑完整 checkpoint commit，但禁止提交半成品、失败验证或越界改动。
|
||||
- Codex 完成 Packet 后必须自行执行 commit gate 判定：满足 `auto_commit` 条件时应自行提交；命中 `hold_no_commit` 时不得提交并报告阻塞；命中 `ask_before_commit` 时先说明事实再等用户拍板。具体判定以 `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md` 的 `Packet commit 协议` 为准。
|
||||
- 不允许在旧 Packet 分支上继续做新 Packet；新 Packet 必须从最新 integration base 或明确依赖分支重新开 `codex/<new_packet_id>`。
|
||||
- 合并前必须检查 `git diff --name-only`，确认没有写出 `write_scope`；越界改动必须拆回对应 Packet 或交给 integration owner。
|
||||
- 合并顺序固定为：Contract / migration → Backend service/API → Frontend API/store → UI/page → Docs/test/integration。
|
||||
- 每批并行开发必须指定一个 integration owner，负责共享文件合并、最终验证、文档同步和进度台账回写。
|
||||
|
||||
共享高冲突区默认同一时间只能一个 Packet 写：
|
||||
|
||||
- `backend/app/api/router.py`
|
||||
- `backend/app/models/__init__.py`
|
||||
- `backend/app/schemas/*.py` 中的跨域 schema
|
||||
- `backend/alembic/versions/*`
|
||||
- `frontend/src/router/index.tsx`
|
||||
- `frontend/src/api/base.ts`
|
||||
- `frontend/src/features/pmflow-os/store.tsx`
|
||||
- `CLAUDE.md`
|
||||
- `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||||
- `docs/architecture/API_CONTRACTS.md`
|
||||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||||
|
||||
若必须多人改共享文件，先由 integration owner 建立接口占位或合同，再让其它线程只改自己 owned 文件，最后由 integration owner 统一合并共享文件。
|
||||
|
||||
|
||||
## 安全约束（必须严格遵守）
|
||||
|
||||
|
|
|
|||
30
CLAUDE.md
30
CLAUDE.md
|
|
@ -8,6 +8,8 @@
|
|||
- 新增执行约定：计划类需求一旦确认进入实现阶段，默认连续执行到“实现完成 + 验证完成 + 统一回复验收结果”；仅在明确阻塞、高风险冲突、context 限制或用户主动中断时才中途打断。
|
||||
- 新增 bugfix 执行约定：缺陷修复/回归修复允许跨多个直接相关文件端到端完成，不再按文件数硬性拆分；但必须同时满足“改动范围围绕同一根因”“不夹带无关重构”“最终附带编译/测试验证”。大功能开发或结构性重构仍优先按子任务拆分。
|
||||
- 新增发布约定：凡后端代码或数据库迁移发生改动，完成编译/测试后必须继续执行当前环境对应的热部署/重启/重载步骤，确认服务已加载新版本；若当前机器不是部署环境、缺少权限或不具备热部署条件，必须在结果中明确说明未执行原因与阻塞点，禁止默认省略。
|
||||
- 新增前端快回路约定：`L1 微调` 默认走 `verify:login-fast` 或 focused screenshot，`L2 视觉逻辑` 默认走 `verify:login-responsive` 或 `capture:login:matrix`，出现 `context_compacted` 或超过 `8` 分钟仍未落代码时优先收口或切线程。
|
||||
- 新增并行开发约定：多个 Codex 线程并行推进时必须按 Packet 分派，声明 `read_scope / write_scope / forbidden_paths / shared_files / base_ref`，默认使用 `codex/<packet_id>` 独立分支和独立 worktree；共享高冲突文件只能由 integration owner 统一合并。
|
||||
- 下面各节中大量 `新增/更新/移除` 清单用于保留“当前架构库存”和关键入口索引，不等同于运行时主规范；行为约束与禁止项仍以 `AGENTS.md` 为准。
|
||||
|
||||
## 2. 项目定位
|
||||
|
|
@ -26,12 +28,16 @@ AIProjectManger/
|
|||
├── docker-compose*.yml # 容器编排
|
||||
├── mdproject/ # 执行计划与任务清单（中文为主）
|
||||
├── backend/ # FastAPI 后端
|
||||
├── frontend/ # React 前端
|
||||
├── frontend/ # React 前端（后台工作台 + 登录页）
|
||||
├── scripts/ # 根目录运维脚本
|
||||
└── docs/ # 额外文档
|
||||
```
|
||||
- 详细架构库存已迁到 [`docs/architecture/ARCHITECTURE_INVENTORY.md`](/Users/yuuuu/Documents/AIProjectManger/docs/architecture/ARCHITECTURE_INVENTORY.md)。
|
||||
- 本地预览端口现按职责拆分：`docker-compose.dev.yml` 的热更新开发前端固定占用 `5174`，`docker-compose.yml` 的静态生产预览前端默认改为 `5175`（可通过 `FRONTEND_PROD_PORT` 覆盖），避免再和 Vite live preview 抢端口。
|
||||
- `docs/architecture/` 当前包含：`MASTER_CONTRACT.md`、`RUNTIME_GUARDRAILS.md`、`CODE_REFERENCE_INDEX.md`、`API_CONTRACTS.md`、`DATAFLOW.md`、`TASK_BRIEF_TEMPLATE.md`、`ARCHITECTURE_INVENTORY.md`
|
||||
- `docs/PMFLOW_PRODUCT_BLUEPRINT.md` 是当前产品蓝图真源：定义 PMFlow 为“对话驱动的 AI 产品执行操作系统”，并锁定 `solo-first, team-ready`、项目真相层、待确认变更中心、执行桥、人机混编团队等产品方向。
|
||||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md` 是 PMFlow 产品推进执行标准：记录当前推进状态、Phase A-F 下一步、单次任务范围、Codex 并行推进协议、完成后进度回写规则和新线程接续标准；继续产品推进前必须先读。
|
||||
- `docs/PMFLOW_UI_CONTRACT.md` 是 PMFlow UI 契约真源：锁定 Logo、浅色白底 + `#2463EB`、移动端固定底部导航、用户动作/AI 操作/系统状态/待确认视觉语法、核心功能 canonical 契约和当前前端一致性审计；后续原型图和代码化原型不得绕过该文档。
|
||||
- `docs/superpowers/plans/` 保存实现计划，`docs/superpowers/specs/` 保存需求/方案规格，`docs/task_briefs/` 保存任务包产物与验收截图。
|
||||
- 当前与“统一 AI handoff / 全量业务结构化”直接相关的设计规格包括：`docs/superpowers/specs/2026-04-17-unified-project-ai-handoff.md`、`docs/superpowers/specs/2026-04-19-interaction-boundary-four-level-contract-design.md`、`docs/superpowers/specs/2026-04-20-full-business-structuring-and-conversation-baseline-design.md` 与 `docs/superpowers/specs/2026-04-20-business-golden20-refresh.md`；它们分别对应统一入口与项目型 AI 方向、四挡 interaction boundary、全量业务结构化与 58 条广覆盖语义矩阵，以及面向当前真实项目池和 plan mode 主链的 20 条核心黄金案例。
|
||||
|
||||
|
|
@ -89,6 +95,7 @@ frontend/
|
|||
├── e2e/ # Playwright 真实浏览器 E2E 用例
|
||||
├── src/
|
||||
│ ├── api/ # 接口封装
|
||||
│ ├── features/ # 新产品域与原型状态机（如 PMFlow OS / 个人空间 / 新项目启动台）
|
||||
│ ├── pages/ # 页面级组件（已目录化）
|
||||
│ ├── components/ # 通用组件与 SSTC/Inbox 共享组件
|
||||
│ ├── hooks/ # 自定义 hooks
|
||||
|
|
@ -102,16 +109,31 @@ frontend/
|
|||
```
|
||||
- 当前前端重点入口优先看：
|
||||
- `frontend/src/api/`（统一 API 封装）
|
||||
- `frontend/src/router/index.tsx`（顶层路由懒加载入口；登录页与 Layout 保持同步首屏，登录后默认主入口已切到 `/command-center`，`/space`、`/project-launch`、`/pmflow-os` 与 `/me` 是可直接打开的个人空间 / 新项目启动台 / PMFlow OS 项目上下文 / 我的账号入口，`/command-center` 也提供免登录产品预览壳，其余后台重页面按 route-level lazy 进入）
|
||||
- `frontend/src/features/personal-space/`（个人空间首页；本地 mock data 驱动继续推进、待我确认、AI 正在推进、暂存想法、草案箱和新建项目入口）
|
||||
- `frontend/src/features/project-launch/`（首次进入页 / 新项目启动台；默认调用真实 `frontend/src/api/pmflowLaunch.ts` draft/confirm API 创建项目，只有显式 `?demo=1` 或 `?dataSource=demo` 才启用本地 mock 演示状态机）
|
||||
- `frontend/src/features/pmflow-os/`（PMFlow OS 前端产品域；共享 truth store 已支持 `?projectId=<id>` 读取真实后端 projection，真实模式下 message、`proposed_items` extraction、ChangeItem `accept/edit/defer` 调后端，显式 `?demo=1` 才启用本地演示状态机）
|
||||
- `backend/app/api/pmflow_os_api/` + `backend/app/services/pmflow_os_projection_service.py` + `backend/app/services/pmflow_change_review_service.py` + `backend/app/schemas/pmflow_os.py` + `backend/app/models/pmflow_change_review.py`（PMFlow OS A3/C1 真实路径；提供 `truth-state`、`execution-summary`、thread message、`proposed_items` extraction、ChangeSet detail、ChangeItem `accept/edit/defer`；复用 `truth_nodes / tasks / semantic_facts / ai_project_control / dev_sync` 并投影 `pmflow_threads / pmflow_thread_messages / pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`；C1 不实现 commit）
|
||||
- `backend/app/api/pmflow_launch_api/` + `backend/app/services/pmflow_launch_service.py` + `backend/app/schemas/pmflow_launch.py` + `backend/app/models/pmflow_launch.py`（Project Launch Phase B 真实创建链；`drafts` 只写 `pmflow_launch_drafts`，`confirm` 在同一事务写真实 Project、启动线程、启动消息、初始 truth_nodes、tasks 与 semantic_facts seed）
|
||||
- `docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md`（PMFlow OS 产品合同真源；真实后端接入前先读，锁定本地 truth store 对象与 `truth_nodes / tasks / semantic_facts / ai_project_control / dev_sync` 的映射；Phase C1 review 表和审查 API 已实现，commit 仍未实现）
|
||||
- `frontend/src/pages/inbox/`（消息台）
|
||||
- `frontend/src/pages/ai-steward/`（AI 管家）
|
||||
- `frontend/src/components/ai-steward/`（问答浮窗、状态条、回答元卡片；`FloatingQAChat.tsx` 现会透传并回放 `project_operating_context / execution_recipe / fit_brief / external_recommendation / analysis_packet / recommended_next_step`，`QAConversationStatusBar.tsx` 与 `QAResponseMetaCard.tsx` 负责显性展示）
|
||||
- `frontend/src/pages/ai-config/mcp-config/`（AI Config -> Governance Tools 下的 MCP 模板接入中心）
|
||||
- `frontend/src/pages/query-route-governance/`（AI Config -> Governance Tools 下的 route/context 治理页）
|
||||
- `frontend/src/pages/semantic-facts-board/`（AI Config -> Governance Tools 下的 semantic facts 治理页）
|
||||
- `frontend/src/components/layout/LazyBoundary.tsx`（统一 route/page-section/dialog 级 loading skeleton）
|
||||
- `frontend/src/components/login/`（公开登录页组件目录；`LoginExperience.tsx` 负责双栏登录壳，`LoginWorkflowVisual.tsx` 负责左侧场景，`loginScene.ts` / `loginMath.ts` 拆出展示配置与路径几何，`login.css` 收口登录页专属样式）
|
||||
- `frontend/src/api/queryRouteGovernance.ts`（route/context 治理页前端 API）
|
||||
- `frontend/src/pages/scheduler-center/`（Mounted AI Console）
|
||||
- `frontend/src/components/sstc/`（SSTC 工作流组件）
|
||||
- `frontend/src/pages/user-skills/components/UserSkillsRadarPanel.tsx` 与 `frontend/src/pages/workload-detail/components/WorkloadTrendChart.tsx`（图表按页面内二级 chunk 拆分后的入口）
|
||||
- 页面目录化、Mounted AI Console、Inbox、AI Steward 与 Recipes/Projects/Users 等模块化拆分的详细库存见库存文档。
|
||||
- 顶层路由已改为 `React.lazy + Suspense`，统一 fallback 使用 `frontend/src/components/layout/LazyBoundary.tsx`；AI Steward / AI Config 页面按 active tab 只渲染当前可见区块，Projects/Users/图表页则把重对话框与图表从同步入口拆出。
|
||||
- `frontend/src/features/project-launch/` 是新项目启动台独立产品域：`types.ts / useProjectLaunchState.ts` 承载状态合同和真实 API 编排，`mockData.ts` 只在显式 demo 模式下使用；默认路径调用 `POST /pmflow-launch/drafts` 生成可审查草案，确认后调用 `POST /pmflow-launch/drafts/{draft_id}/confirm` 创建真实项目并跳转 `/pmflow-os?projectId=<id>`。`LaunchShell` 桌面端复用 `frontend/src/features/personal-space/components/SpaceChrome.tsx` 的空间左侧栏和顶部条，主画布仍由 `IntentInputPanel / AIProgressCanvas / HumanReviewCanvas / DraftEditCanvas / FailureStatePanel / SuccessTransitionPanel` 承接，移动端仍由 `MobileLaunchLayout` 承接；`frontend/src/pages/ProjectLaunchPage.tsx` 仅做薄入口。
|
||||
- `frontend/src/features/personal-space/` 是空间层入口：`mockData.ts` 固化本地项目、待确认、AI 推进、暂存想法与草案箱数据，`PersonalSpacePage.tsx` 承接桌面空间首页与独立移动布局，`components/SpaceChrome.tsx` 承接空间层左侧栏、顶部条与空间用量组件，并被 `/project-launch` 桌面首次新建壳复用；`frontend/src/pages/PersonalSpacePage.tsx` 仅做薄入口。
|
||||
- `frontend/src/features/pmflow-os/` 当前承载新的对话驱动前端产品域：`store.tsx` 提供共享 truth store；真实模式通过 `?projectId=<id>` 调用 `frontend/src/api/pmflowOs.ts` 读取后端 `ProjectTruthState` projection，并调用真实 message、`proposed_items` extraction、ChangeItem `accept/edit/defer` API，成功后 refetch truth-state；显式 `?demo=1` 才启用 `command_idle -> ai_extracting -> extraction_ready -> review_open -> writeback_success` 本地演示状态机，以及本地 `promoteAcceptedToGraph` 等演示动作。`pages/` 下包含 `CommandCenter / StructuredExtraction / ChangeReview / MemoryWritebackResult / WorkGraph / ExecutionBridge / ReleaseGrowth / TeamLayer / ProjectMemory / Account` 主页面；`ProjectMemoryPage` 在真实模式消费后端 `truth_nodes + semantic_facts` 的 `projectMemory` 投影，真实模式下 accepted/edited ChangeItem 不会进入 Project Memory，commit 留给 Phase C2。`components/` 下除了 `ProjectStageRail / ThreadComposer / ExtractionRail / ChangeGroupPanel / ObjectGraphSection / ContextPacketPanel / ExecutionTimeline / ReleaseGatePanel / TeamFeedPanel` 之外，新增 `ProjectStructuredLoop / PMFlowOsFrame / AccountControls / FeedbackPrimitives` 等行为组件，用来承接项目指挥台、结构化提取、待确认审查、项目记忆写入结果、项目内面包屑、项目切换器、账号退出登录交互，以及 `PageBanner / InlineNotice / HumanDecisionBar / ConfirmDialog / MobileBottomSheet` 这组契约化提示提醒组件；`components/MobileBottomNav.tsx` 是正式应用壳唯一移动底部导航，固定为 `空间 / 指挥台 / 待确认 / 动态 / 我的`。
|
||||
- 旧登录实现 `frontend/src/components/ui/sign-in.tsx` 与 `frontend/src/components/ui/demo.tsx` 已移除，`frontend/src/components/login/` 是当前唯一登录真源。
|
||||
|
||||
### 5.1 `frontend/src/components/sstc/` 目录说明（模块化拆分后）
|
||||
- `SSTCWorkspace.tsx`：SSTC 工作区主容器（组装各阶段组件）
|
||||
|
|
@ -154,13 +176,11 @@ frontend/
|
|||
```bash
|
||||
./start.sh dev # 推荐：docker-dev 热更新模式
|
||||
./stop.sh dev
|
||||
./devops/tunnel/start.sh # 公网穿透启动器（独立入口）
|
||||
./scripts/start_model_probe.sh # 独立模型连通性检测（中文日志）
|
||||
```
|
||||
|
||||
- 启动入口收敛：仅保留 2 个用户入口
|
||||
- 正常启动器：`./start.sh`
|
||||
- 公网穿透启动器：`./devops/tunnel/start.sh`
|
||||
- 启动入口收敛：用户入口统一使用 `./start.sh`。
|
||||
- 前端浏览器请求统一走同源 `/api`；开发环境由 Vite proxy 转发，生产环境由 nginx `/api` 反代到后端。
|
||||
- 运行脚本、模型探针、契约校验与 E2E 工具清单已迁到 [`docs/architecture/ARCHITECTURE_INVENTORY.md`](/Users/yuuuu/Documents/AIProjectManger/docs/architecture/ARCHITECTURE_INVENTORY.md)。
|
||||
- 当前新增的 requirement-plan 历史修复工具位于 `backend/scripts/repair_requirement_plan_history.py`，默认 dry-run，仅在显式 `--apply` 时写回 `mounted_draft_workspaces / mounted_topic_workspaces`。
|
||||
|
||||
|
|
|
|||
45
USER.md
45
USER.md
|
|
@ -14,6 +14,23 @@
|
|||
- 回答要直接、具体、贴当前对象，优先给证据链、调用链和真实落点；不要写成模板化汇报。
|
||||
- 不确定就明确说不确定，不要假装完整。
|
||||
- 已拍板方案不要反复推荐替代品；配置和偏好尽量收敛，别分散。
|
||||
- 前端默认视觉标准：品牌主色固定为 `#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 产品推进执行标准已沉淀到 `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 或泛后台风格。
|
||||
|
||||
### 学习与更新方式
|
||||
|
||||
|
|
@ -77,6 +94,34 @@
|
|||
- 遇到链路问题先补 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 回合承载。
|
||||
|
||||
## 当前知道但暂不处理的项目问题
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,515 @@
|
|||
# PMFlow 产品蓝图真源
|
||||
|
||||
版本日期：2026-04-24
|
||||
|
||||
本文档是 PMFlow 当前产品方向的长期真源。后续原型、前端实现、后端对象模型、AI 编排与商业化叙事默认以本文档为准；只有当用户明确拍板调整产品战略时，才更新本文档。
|
||||
|
||||
## 1. 最终定位
|
||||
|
||||
PMFlow 不是“聊天工具 + 项目管理工具”，也不是“Jira 加一个 AI 助手”。PMFlow 的最终定位是：
|
||||
|
||||
**面向软件技术/半技术创作者与 1-10 人 AI 产品团队的，对话驱动的 AI 产品执行操作系统。**
|
||||
|
||||
它要解决的不是“怎么把任务排得更整齐”，而是：
|
||||
|
||||
**把一个模糊创意持续压缩成可上线、可验证、可盈利的产品，并让人类、AI agent、IDE、Git、测试、发布和运营数据围绕同一份项目真相协同。**
|
||||
|
||||
外部表达可以更短：
|
||||
|
||||
**AI 产品从创意到上线和变现的执行操作系统。**
|
||||
|
||||
首版体验必须 `solo-first, team-ready`：
|
||||
|
||||
- `solo-first`：一个个人开发者、一人公司或小团队负责人，也能独立跑通创意到上线主链。
|
||||
- `team-ready`：底层必须从第一天支持成员归属、角色审查、确认链、证据链和执行回写，避免后续团队版重做。
|
||||
|
||||
PMFlow 不追求成为重型企业 PM 系统，不按 10-50 人传统研发组织的管理后台去设计。首版核心用户是个人开发者、一人公司、副业创业者、半技术产品创作者和 1-10 人 AI 应用小团队。
|
||||
|
||||
## 2. 产品边界
|
||||
|
||||
PMFlow 服务的项目类型是 AI 应用与传统软件 AI 转型项目。
|
||||
|
||||
覆盖范围：
|
||||
|
||||
- 原生 AI 应用：AI 客服、AI 写作、RAG 知识库、Agent 工作流、多模态生成工具等。
|
||||
- 垂直行业 AI 应用：教育、法律、财税、医疗辅助、运营自动化等。
|
||||
- Agent 应用：工作流 agent、多 agent 协作、后台任务 agent、组织内助手。
|
||||
- 传统软件 AI 转型：CRM、OA、ERP、工业软件、内部工具叠加 AI 能力。
|
||||
|
||||
不作为首版主目标：
|
||||
|
||||
- 完全无 AI 能力的传统软件项目。
|
||||
- 纯硬件产品。
|
||||
- 只有想法、没有落地意愿的概念收集。
|
||||
- 大企业 portfolio、复杂组织树、重审批采购、完整财务系统。
|
||||
|
||||
## 3. 核心战略判断
|
||||
|
||||
### 3.1 不做泛聊天，做项目型 AI 入口
|
||||
|
||||
聊天是操作语言，不是产品本体。用户可以从自然语言开始，但每次有效输入都要进入项目上下文、结构化对象、变更集、确认链或执行桥。
|
||||
|
||||
运行时和前端都禁止把 PMFlow 做成脱离业务对象的泛化聊天产品。
|
||||
|
||||
### 3.2 不做传统项目管理，做结构化项目真相层
|
||||
|
||||
项目管理不是另一个模块，而是 AI 从对话、截图、文档、IDE、Git、测试和数据源中持续抽取、更新、回写后的“工作表面”。
|
||||
|
||||
用户看到的不是数据库表，而是可审查、可编辑、可追溯的项目对象：
|
||||
|
||||
- 需求
|
||||
- 决策
|
||||
- 任务
|
||||
- 风险
|
||||
- 模型决策
|
||||
- 测试结果
|
||||
- 发布门禁
|
||||
- 增长实验
|
||||
- 收入信号
|
||||
|
||||
### 3.3 不做全自动黑箱，做监督式自治
|
||||
|
||||
PMFlow 的 AI 应该能自动提取、拆解、同步、预警、生成执行上下文、触发外部工具和回写状态，但高风险动作必须可见、可确认、可审计。
|
||||
|
||||
产品原则是：
|
||||
|
||||
**AI 自动推进标准流程，人类处理目标、判断、例外、确认和责任归属。**
|
||||
|
||||
禁止把“99% 自动驾驶”当成无条件产品原则。正确方向是监督式 agent 工作台。
|
||||
|
||||
### 3.4 不替代 IDE，做执行桥
|
||||
|
||||
开发执行主要发生在 Cursor、VS Code、Codex、GitHub Copilot、GitHub PR、测试系统等外部工具里。PMFlow 不自建完整 IDE，不把开发者关进平台。
|
||||
|
||||
PMFlow 应负责：
|
||||
|
||||
- 把需求、上下文、约束、验收标准、模型决策和风险推给开发工具。
|
||||
- 支持同步副驾式开发和异步后台 agent 执行。
|
||||
- 把提交、PR、测试、阻塞、执行日志和发布结果回写到项目真相层。
|
||||
|
||||
### 3.5 不把模型推荐做成独立头牌，而作为主链决策对象
|
||||
|
||||
模型推荐、成本估算和合规提示是 AI 应用开发的关键能力，但它们必须嵌入需求、预算、执行和发布主链，形成 `Model Decision` 对象，而不是独立模型市场。
|
||||
|
||||
## 4. 主交互模型
|
||||
|
||||
### 4.1 单线程双视图
|
||||
|
||||
PMFlow 的核心不是“双模式切换”，而是一个统一 `Project Thread` 的两种投影：
|
||||
|
||||
- `Conversation View`：对话视图。用户用自然语言提出想法、追问、判断、截图、上传材料、下达指令。
|
||||
- `Work Graph View`：工作图谱视图。同一条线程被实时映射成结构化项目对象、阶段、状态、证据和待确认变更。
|
||||
|
||||
用户不是从“聊天”切到“项目管理”，而是在同一个项目线程里切换语言流与工作流。
|
||||
|
||||
### 4.2 上下文副驾
|
||||
|
||||
原先的“AI 跟随”不作为模式名，升级为“上下文副驾”能力。它始终绑定四类上下文：
|
||||
|
||||
- 当前对象：需求、任务、发布、测试、增长实验、收入信号等。
|
||||
- 当前阶段：创意、验证、规划、开发、测试、发布、增长、变现。
|
||||
- 当前意图：理解、修改、决策、执行、复盘。
|
||||
- 当前风险：回答、草稿、正式更新、外部动作。
|
||||
|
||||
同一个统一 AI 在前台保持一致人格；后台根据上下文自动调度 Product Agent、PMO Agent、Dev Agent、QA Agent、Growth Agent、Ops Agent、Finance/Monetization Agent 等能力。前台不让用户先选多个 agent 标签页。
|
||||
|
||||
### 4.3 Action Ladder
|
||||
|
||||
所有 AI 动作必须分级：
|
||||
|
||||
- `Level 1: Answer`：只回答，不修改结构化数据。
|
||||
- `Level 2: Draft`：生成草稿，进入待审区。
|
||||
- `Level 3: Commit`：更新项目对象，必须显示 diff 和证据。
|
||||
- `Level 4: Execute`：触发外部动作，如创建任务、推送 IDE、发起测试、生成发布动作。
|
||||
|
||||
高敏感动作必须走 `Draft -> Review -> Confirm -> Execute`：
|
||||
|
||||
- 改需求范围。
|
||||
- 大批量创建或重排任务。
|
||||
- 委派开发到 IDE / agent。
|
||||
- 触发发布。
|
||||
- 修改定价、公开内容、营收目标。
|
||||
- 删除、归档或覆盖正式对象。
|
||||
|
||||
## 5. 核心产品表面
|
||||
|
||||
### 5.1 Space / 空间
|
||||
|
||||
空间是所有项目、想法、草案和待继续事项的上层入口。它不等同于传统项目列表，而是用户当前所有创意、项目和 AI 推进状态的个人工作面。
|
||||
|
||||
默认承载：
|
||||
|
||||
- 继续推进。
|
||||
- 待我确认。
|
||||
- AI 正在推进。
|
||||
- 暂存想法。
|
||||
- 草案箱。
|
||||
- 新建项目入口。
|
||||
|
||||
### 5.2 Project Launch / 新项目启动台
|
||||
|
||||
新项目启动台用于把一句创意、文档、截图或业务目标转成首个项目草案。它不是表单创建页，而是“意图输入 -> AI 结构化 -> 人类确认 -> 创建项目”的启动流。
|
||||
|
||||
首版可先用本地状态机和高保真原型验证体验，后续接真实后端对象。
|
||||
|
||||
### 5.3 Command Center / 指挥台
|
||||
|
||||
项目创建后的主工作面。推荐结构：
|
||||
|
||||
- 左侧：项目阶段轨道、项目入口、对象导航。
|
||||
- 中间：当前工作画布或对话主线程。
|
||||
- 右侧：上下文副驾。
|
||||
- 底部或主输入区：全局自然语言输入。
|
||||
|
||||
指挥台必须支持从对话直接进入结构化提取、待确认、项目对象和执行桥。
|
||||
|
||||
### 5.4 Structured Extraction / 本轮结构化提取
|
||||
|
||||
用户每次输入后，AI 不只回复文本，还要展示本轮提取结果：
|
||||
|
||||
- 新增了哪些对象。
|
||||
- 更新了哪些已有对象。
|
||||
- 哪些字段来自明确证据。
|
||||
- 哪些字段是 AI 推断。
|
||||
- 哪些内容需要确认。
|
||||
- 哪些内容证据不足。
|
||||
|
||||
这层解决“AI 到底理解成什么”的即时信任问题。
|
||||
|
||||
### 5.5 Change Review / 待确认中心
|
||||
|
||||
这是 PMFlow 区别于聊天工具的关键页面。AI 的结构化写入先形成业务 diff，再由用户接受、修改、暂缓或拒绝。
|
||||
|
||||
待确认中心聚合：
|
||||
|
||||
- AI 提议但未确认的对象。
|
||||
- 高风险改动。
|
||||
- 缺证据结论。
|
||||
- 范围、成本、发布和合规风险。
|
||||
- 需要不同角色异步审查的团队决策。
|
||||
|
||||
### 5.6 Work Graph / 项目工作台
|
||||
|
||||
工作台按阶段组织项目对象：
|
||||
|
||||
- 创意：Idea、Opportunity、Target User、Problem Statement、Solution Concept。
|
||||
- 验证：Assumption、Evidence、Competitor Insight、Market Signal。
|
||||
- 规划：Requirement、PRD、Milestone、Decision、Risk。
|
||||
- 开发：Task、Build Spec、Execution Thread、Code Change / PR。
|
||||
- 测试：Test Case、Test Run、Bug、Release Gate。
|
||||
- 发布：Release、Rollback Plan、Observation Metric。
|
||||
- 增长与变现：Growth Experiment、Channel、Conversion Signal、Revenue Signal。
|
||||
|
||||
工作台不是传统看板的替代品，而是结构化项目对象的主视图。对象可用列表、看板、时间线、关系图和表格等投影展示。
|
||||
|
||||
### 5.7 Execution Bridge / 执行桥
|
||||
|
||||
执行桥连接 PMFlow 与 IDE / agent / Git / 测试系统。
|
||||
|
||||
首版重点：
|
||||
|
||||
- 从 PMFlow 任务生成开发上下文包。
|
||||
- 生成适合 Cursor / VS Code / Codex / GitHub agent 使用的开发 prompt。
|
||||
- 把需求、约束、验收标准、模型决策和风险一起推送。
|
||||
- 监听提交、PR、测试结果和执行日志。
|
||||
- 自动回写任务状态、阻塞、测试结论和发布准备度。
|
||||
|
||||
执行桥必须同时支持：
|
||||
|
||||
- 同步副驾：开发者在 IDE 里实时协作。
|
||||
- 异步 agent：后台接任务、执行、开 PR、回写结果。
|
||||
|
||||
### 5.8 Release & Growth / 发布与增长
|
||||
|
||||
发布不是终点，而是进入增长和变现验证的入口。
|
||||
|
||||
首版只做轻量闭环：
|
||||
|
||||
- 发布准备度。
|
||||
- 发布风险。
|
||||
- 模型效果验证。
|
||||
- 关键指标观察。
|
||||
- 用户反馈聚类。
|
||||
- 首批增长实验建议。
|
||||
- 基础收入/转化信号。
|
||||
|
||||
不在首版做完整财务系统和完整合规平台。
|
||||
|
||||
### 5.9 Project Memory / 项目记忆
|
||||
|
||||
Project Memory 是项目的机器可读真相层，也是后续 AI 行动的优先上下文来源。
|
||||
|
||||
它管理已确认事实：
|
||||
|
||||
- 已确认目标。
|
||||
- 已确认用户群。
|
||||
- 已确认 MVP 范围。
|
||||
- 已确认需求。
|
||||
- 已确认技术约束。
|
||||
- 已确认模型决策。
|
||||
- 已确认优先级原则。
|
||||
- 已确认商业模式。
|
||||
- 已确认发布目标。
|
||||
|
||||
AI 后续行动优先引用 Project Memory，而不是无限依赖长聊天上下文。
|
||||
|
||||
### 5.10 Team Layer / 团队层
|
||||
|
||||
团队版不是传统“多人一起维护任务表”，而是人机混编协作层。
|
||||
|
||||
团队协作的核心不是更多字段、更多权限、更多会议，而是：
|
||||
|
||||
- 共享项目真相。
|
||||
- 异步审查与拍板。
|
||||
- 角色化收件箱。
|
||||
- 团队动态流。
|
||||
- Agent workforce 可见化。
|
||||
|
||||
## 6. 团队协作原则
|
||||
|
||||
PMFlow 的团队方向是：
|
||||
|
||||
**一个人如何像一个团队一样推进；一个小团队如何像一个更强的 AI 组织一样协作。**
|
||||
|
||||
团队版必须遵守三层协作模型。
|
||||
|
||||
### 6.1 共享项目真相
|
||||
|
||||
所有成员围绕同一份项目真相层工作。团队成员默认看到：
|
||||
|
||||
- 当前目标。
|
||||
- 已确认需求。
|
||||
- 待确认变更。
|
||||
- 当前风险。
|
||||
- 最新决策。
|
||||
- 执行状态。
|
||||
- 证据和来源。
|
||||
|
||||
先共享真相，再共享任务。
|
||||
|
||||
### 6.2 异步审查与拍板
|
||||
|
||||
团队协作的关键不是同步开会，而是在同一份结构化变更集上分角色审查：
|
||||
|
||||
- 产品负责人看价值、范围和优先级。
|
||||
- 开发负责人看实现复杂度、架构风险和技术约束。
|
||||
- QA 看回归范围和发布门禁。
|
||||
- 运营/增长看上线节奏、渠道和指标影响。
|
||||
- 创始人/负责人做最终取舍。
|
||||
|
||||
### 6.3 人机混编执行
|
||||
|
||||
团队由人类成员、AI agent、外部工具执行器和异步任务线程共同组成。
|
||||
|
||||
平台要让团队看到：
|
||||
|
||||
- 哪些 agent 正在工作。
|
||||
- 用了哪些上下文。
|
||||
- 产出了什么。
|
||||
- 阻塞在哪里。
|
||||
- 需要谁确认。
|
||||
|
||||
这比传统成员列表和任务看板更重要。
|
||||
|
||||
## 7. 底层对象模型
|
||||
|
||||
首版必须先定对象层，否则 UI 会漂。
|
||||
|
||||
### 7.1 横切核心对象
|
||||
|
||||
- `Thread`：项目对话线程。
|
||||
- `ProjectObject`：所有正式业务对象的统一抽象。
|
||||
- `ChangeSet`：AI 每轮建议的结构化变更集。
|
||||
- `Approval`：人工确认、修改、拒绝、暂缓记录。
|
||||
- `Evidence`：对象与对话、截图、文档、PR、测试、数据源之间的证据关系。
|
||||
- `ContextPacket`：当前页面/对象/阶段/意图/风险的上下文包。
|
||||
- `ExecutionRun`：外部工具或 agent 执行事实。
|
||||
- `AuditEvent`：关键动作审计。
|
||||
|
||||
### 7.2 首版业务对象
|
||||
|
||||
首版对象不要过多，优先打通主链：
|
||||
|
||||
- `Idea`
|
||||
- `Opportunity`
|
||||
- `Requirement`
|
||||
- `Decision`
|
||||
- `Task`
|
||||
- `ModelDecision`
|
||||
- `Risk`
|
||||
- `TestRun`
|
||||
- `Release`
|
||||
- `Metric`
|
||||
- `GrowthExperiment`
|
||||
- `RevenueSignal`
|
||||
|
||||
### 7.3 对象状态
|
||||
|
||||
正式对象必须区分状态：
|
||||
|
||||
- `draft`
|
||||
- `proposed`
|
||||
- `confirmed`
|
||||
- `executing`
|
||||
- `blocked`
|
||||
- `done`
|
||||
- `archived`
|
||||
|
||||
AI 生成不等于事实生效。只有经过确认、证据绑定或明确低风险规则允许的内容，才能成为项目真相。
|
||||
|
||||
## 8. AI Agent 编排
|
||||
|
||||
前台只有一个统一 AI，不暴露一排 agent 让用户选择。后台按任务自动编排：
|
||||
|
||||
- `Product Agent`：目标、需求、价值、范围、优先级。
|
||||
- `PMO Agent`：里程碑、依赖、风险、状态推进。
|
||||
- `Dev Agent`：开发上下文包、IDE prompt、PR 协作。
|
||||
- `QA Agent`：测试策略、用例、回归、发布门禁。
|
||||
- `Growth Agent`：数据解读、增长实验、转化优化。
|
||||
- `Ops Agent`：运营内容、渠道节奏、自动化任务。
|
||||
- `Finance/Monetization Agent`：定价、成本、收入信号、ROI。
|
||||
|
||||
前台只在必要时提示当前建议来自哪类专业能力，例如“当前由 QA Agent 检查发布风险”。
|
||||
|
||||
## 9. AI 应用专属能力如何放置
|
||||
|
||||
### 9.1 模型决策
|
||||
|
||||
模型智能评估与推荐作为 `ModelDecision` 对象嵌入需求宪章、任务拆解、预算估算、发布验证和复盘。
|
||||
|
||||
首版评估维度：
|
||||
|
||||
- 能力匹配度。
|
||||
- 成本适配度。
|
||||
- 合规/可用性。
|
||||
|
||||
模型推荐不是独立大模块，不作为首屏主卖点。
|
||||
|
||||
### 9.2 成本与 ROI
|
||||
|
||||
首版只做轻量：
|
||||
|
||||
- 模型/API 成本估算。
|
||||
- 实际调用成本回写。
|
||||
- 发布后基础转化和收入信号。
|
||||
- 单项目投入产出趋势。
|
||||
|
||||
不做完整财务系统、税务、现金流和多项目财务管理。
|
||||
|
||||
### 9.3 合规风控
|
||||
|
||||
首版只做发布门禁和风险提醒：
|
||||
|
||||
- 模型备案/来源风险。
|
||||
- 数据敏感性。
|
||||
- 内容安全风险。
|
||||
- 知识产权风险。
|
||||
- 对外发布风险。
|
||||
|
||||
不做完整合规平台，不把合规作为首版主功能墙。
|
||||
|
||||
## 10. V1 范围
|
||||
|
||||
V1 只打穿一条主链：
|
||||
|
||||
**创意输入 -> AI 结构化提取 -> 变更确认 -> 项目对象沉淀 -> 任务拆解 -> 推送 IDE / agent -> 开发与测试回写 -> 发布 -> 数据反馈 -> 下一轮迭代。**
|
||||
|
||||
V1 必须包含：
|
||||
|
||||
- 对话驱动的项目线程工作区。
|
||||
- 本轮结构化提取。
|
||||
- 待确认变更中心。
|
||||
- Project Memory 真相层。
|
||||
- Work Graph 项目工作台。
|
||||
- Execution Bridge 执行桥。
|
||||
- 轻量 ModelDecision / Cost / Release Check 卡片。
|
||||
- 基础团队可见性：成员归属、角色、审查对象预留。
|
||||
|
||||
V1 不做：
|
||||
|
||||
- 完整财务模块。
|
||||
- 完整合规平台。
|
||||
- 大而全协同体系。
|
||||
- 大企业组织树。
|
||||
- 多项目 portfolio。
|
||||
- 投融资、孵化生态、应用市场。
|
||||
- 复杂多 agent 前台角色系统。
|
||||
|
||||
## 11. V1.5 与 V2
|
||||
|
||||
### V1.5：Team-ready 补强
|
||||
|
||||
- 成员与角色归属。
|
||||
- Team Feed 团队动态流。
|
||||
- Decision Desk 决策台。
|
||||
- Role Inbox 角色收件箱。
|
||||
- 变更集多人异步审查。
|
||||
- 任务/PR/测试的跨角色通知。
|
||||
|
||||
### V2：Hybrid Human + Agent Team
|
||||
|
||||
- Agent Workforce 面板。
|
||||
- 多 agent 并行执行。
|
||||
- 跨人/跨 agent 协同。
|
||||
- 自动复盘与组织学习。
|
||||
- 更完整的增长实验与收入闭环。
|
||||
- 企业级权限、审计和私有化部署。
|
||||
|
||||
## 12. 北极星指标
|
||||
|
||||
不要把首版北极星指标设成普通 DAU。更重要的是主链效率：
|
||||
|
||||
- 从 idea 到首个可上线 MVP 的时间。
|
||||
- 从需求确认到首个 PR 的时间。
|
||||
- AI 提取变更被接受/修改/拒绝的比例。
|
||||
- 状态和进度自动回写覆盖率。
|
||||
- 发布门禁通过率。
|
||||
- 上线后进入下一轮迭代的项目占比。
|
||||
- 项目真相层对象有证据链接的比例。
|
||||
|
||||
## 13. 用户体验硬原则
|
||||
|
||||
- 用户可见语言默认中文。
|
||||
- 视觉默认浅色白底 + `#2463EB` 主色，参考 Linear 的克制层级、密度和节奏。
|
||||
- 移动端不是桌面压缩版，必须有单手路径、底部安全区、抽屉/分段/底部 CTA。
|
||||
- 项目创建前不展示正式应用底部导航；项目创建后移动端底部导航固定为 `空间 / 指挥台 / 待确认 / 动态 / 我的`。
|
||||
- 项目内 `工作台 / 开发执行 / 发布增长 / 项目记忆` 不进入底部导航，通过项目内二级入口、分段切换或更多菜单进入。
|
||||
- 不做泛后台风，不把 UI 画成表格管理系统。
|
||||
- 不让用户先理解一堆 agent 名词。用户只看当前任务、对象、风险和下一步。
|
||||
|
||||
## 14. 行业趋势依据
|
||||
|
||||
以下公开趋势作为方向依据，不作为逐字产品需求：
|
||||
|
||||
- OpenAI 在 2026-02-02 发布 Codex app，强调它是管理多个 agent、并行工作、长任务协作的 command center；这支持 PMFlow 做“监督式 agent 工作台”，而不是单纯聊天框。
|
||||
- OpenAI 在 2026-04-16 的 Codex 方向更新中继续强调自动继续长期任务、连接更多日常工具、记忆偏好和处理重复任务；这支持 PMFlow 的 Execution Bridge、Project Memory 和持续回写方向。
|
||||
- GitHub 在 2025-02-06 推出 Copilot agent mode，并在 2025-06-13 区分 IDE 内同步 agent mode 与后台 coding agent；这支持 PMFlow 同时设计同步副驾和异步后台 agent。
|
||||
- Atlassian Rovo 在 2025-07-09 强调 AI 要 built into workflow、chat that acts，并在 2025-08-26 强调基于组织知识的对话层、多步动作、记忆和个性化；这支持 PMFlow 的上下文副驾、项目真相层和动作确认。
|
||||
- Microsoft 2025 Work Trend Index 提出 Frontier Firm 与 agent boss，说明未来团队协作会转向人类管理 AI agent、组织人机混编执行；这支持 PMFlow 的 Team Layer 和 Agent Workforce。
|
||||
- MCP 已成为 AI 应用连接外部数据与工具的重要开放协议方向；PMFlow 应做开放操作层，而不是封闭黑箱。
|
||||
|
||||
参考链接：
|
||||
|
||||
- https://openai.com/index/introducing-the-codex-app/
|
||||
- https://openai.com/index/codex-for-almost-everything/
|
||||
- https://github.blog/news-insights/product-news/github-copilot-the-agent-awakens/
|
||||
- https://github.blog/developer-skills/github/less-todo-more-done-the-difference-between-coding-agent-and-agent-mode-in-github-copilot/
|
||||
- https://www.atlassian.com/blog/artificial-intelligence/rovo-chat-july-2025-updates
|
||||
- https://www.atlassian.com/blog/artificial-intelligence/rovo-chat-august-2025-updates
|
||||
- https://www.microsoft.com/en-us/worklab/work-trend-index
|
||||
- https://modelcontextprotocol.io/docs/start/tutorial
|
||||
|
||||
## 15. 不可偏离项
|
||||
|
||||
后续产品、原型和实现不得偏离以下判断：
|
||||
|
||||
- PMFlow 是对话驱动的 AI 产品执行操作系统，不是传统项目管理工具加 AI。
|
||||
- 聊天是操作语言，结构化对象和项目真相层才是产品内核。
|
||||
- 首版体验 `solo-first, team-ready`，不要按重型 10-50 人团队 PM 工具设计。
|
||||
- 团队版不是多人维护任务表，而是围绕 AI 维护的项目真相层进行异步审查和人机混编执行。
|
||||
- 前台统一 AI，不暴露复杂 agent 选择器；后台按上下文自动编排专业 agent。
|
||||
- AI 生成正式对象必须有 ChangeSet、Approval、Evidence 或等价的可审计机制。
|
||||
- 高风险动作必须可见、可确认、可回溯。
|
||||
- IDE / agent / Git / 测试 / 发布是外部执行主场，PMFlow 做上下文推送和结果回写。
|
||||
- 模型推荐、成本、合规是主链决策卡片，不是首版独立巨型模块。
|
||||
- V1 只打穿创意到首次上线和反馈迭代主链，不做大而全平台。
|
||||
|
|
@ -0,0 +1,866 @@
|
|||
# PMFlow 产品推进执行标准
|
||||
|
||||
版本日期：2026-04-24
|
||||
|
||||
本文档是 PMFlow 产品方案落地的推进标准。它回答四件事：
|
||||
|
||||
- 当前产品方案推进到哪里了。
|
||||
- 下一步应该继续往哪里推进。
|
||||
- 每次推进的范围、验收和文档回写怎么做。
|
||||
- 新开 Codex 线程时如何接续，避免重做、漏做或偏离方向。
|
||||
|
||||
产品方向真源仍以 `docs/PMFLOW_PRODUCT_BLUEPRINT.md` 为准。本文档不重新定义战略，只管理落地节奏和进度。
|
||||
|
||||
## 1. 当前推进判断
|
||||
|
||||
截至 2026-04-24，PMFlow 已经完成“产品方向收敛 + 前端本地高保真主链 + 后端局部控制面”的阶段，但还没有完成“真实数据闭环产品化”。
|
||||
|
||||
### 1.1 已经推进到位的部分
|
||||
|
||||
#### 产品方向
|
||||
|
||||
- 已明确 PMFlow 不是“聊天工具 + 项目管理工具”，而是“对话驱动的 AI 产品执行操作系统”。
|
||||
- 已明确首版方向为 `solo-first, team-ready`，面向个人开发者、一人公司、半技术产品创作者和 1-10 人 AI 应用小团队。
|
||||
- 已明确团队协作不是传统多人维护任务表，而是围绕 AI 维护的项目真相层进行异步审查和人机混编执行。
|
||||
- 已明确 V1 主链为：`创意输入 -> AI 结构化提取 -> 变更确认 -> 项目对象沉淀 -> 任务拆解 -> 推送 IDE / agent -> 开发与测试回写 -> 发布 -> 数据反馈 -> 下一轮迭代`。
|
||||
|
||||
真源：
|
||||
|
||||
- `docs/PMFLOW_PRODUCT_BLUEPRINT.md`
|
||||
- `USER.md`
|
||||
|
||||
#### 前端产品域
|
||||
|
||||
当前已经存在三条独立产品域：
|
||||
|
||||
- `frontend/src/features/personal-space/`
|
||||
- 空间入口。
|
||||
- 用本地 mock 展示继续推进、待我确认、AI 正在推进、暂存想法、草案箱和新建项目入口。
|
||||
- `frontend/src/features/project-launch/`
|
||||
- 新项目启动台。
|
||||
- 用本地状态机覆盖意图输入、AI 工作、人类确认、草案修改、失败态、创建成功态和移动端 bottom sheet。
|
||||
- `frontend/src/features/pmflow-os/`
|
||||
- PMFlow OS 项目内主体验。
|
||||
- 已有本地 truth store 和页面：`CommandCenter / StructuredExtraction / ChangeReview / MemoryWritebackResult / WorkGraph / ExecutionBridge / ReleaseGrowth / TeamLayer / ProjectMemory`。
|
||||
- 已有本地状态动作：`sendMessage -> generateExtraction -> acceptChange/editChange/deferChange -> promoteAcceptedToGraph -> pushTaskToExecution -> writeBackExecution -> publishRelease -> ingestGrowthSignal`。
|
||||
|
||||
当前性质：
|
||||
|
||||
- 这是产品主链的高保真原型和本地行为闭环。
|
||||
- 还不是正式后端数据闭环。
|
||||
- 不接真实 AI 提取，不写真实数据库，不消费真实项目对象。
|
||||
|
||||
#### 后端控制面
|
||||
|
||||
当前已经出现 AI 应用项目控制面的初步生产化能力：
|
||||
|
||||
- `backend/app/models/ai_project_control.py`
|
||||
- 模型目录、项目模型绑定、模型推荐快照、模型用量、模型评测。
|
||||
- Prompt Package。
|
||||
- IDE 工作区绑定、Repo 绑定、GitHub App 安装/仓库/webhook 投递。
|
||||
- TaskCodeLink、ProgressEvent、DevSession。
|
||||
- ReleaseValidationRun、FeedbackIngest、IterationRecommendation、RevenueEvent、ROISnapshot、ComplianceCheckRun、EvidencePack。
|
||||
- `backend/app/services/ai_project_control_service.py`
|
||||
- 模型推荐、模型绑定、prompt package、开发同步、GitHub/repo 绑定、进度事件、发布验证、反馈/收入/合规等服务能力。
|
||||
- `backend/app/api/sstc_api/model_control.py`
|
||||
- 模型推荐、模型绑定、模型用量、Prompt Package、发布验证、反馈摄取、收入记录、合规检查等接口。
|
||||
- `backend/app/api/dev_sync.py`
|
||||
- GitHub App 安装、仓库绑定、开发任务、项目 dev-sync summary、任务进度事件等接口。
|
||||
|
||||
当前性质：
|
||||
|
||||
- 后端已经有 V1 产品化需要的部分基础对象和接口。
|
||||
- 但它们还没有和 `frontend/src/features/pmflow-os/` 的本地 truth store 正式打通。
|
||||
- `ChangeSet / Approval / Evidence / Project Memory` 这条主产品链仍主要停留在前端本地态和旧 SSTC/semantic facts 体系之间，缺少统一的 PMFlow OS 产品级 API 合同。
|
||||
|
||||
### 1.2 当前缺口
|
||||
|
||||
当前最大缺口不是再讨论产品方向，而是：
|
||||
|
||||
**把已经成立的产品主链从本地原型推进成真实可用的数据闭环。**
|
||||
|
||||
关键缺口按优先级排序：
|
||||
|
||||
1. `Project Thread / ChangeSet / Evidence / Approval / Project Memory` 的前后端合同没有完全收口。
|
||||
2. `project-launch` 还没有接真实 AI 结构化、真实项目创建和真实草案确认。
|
||||
3. `pmflow-os` 本地 store 还没有接后端读写，当前仍是 mock truth store。
|
||||
4. `ChangeReview` 的接受、修改、暂缓还没有写入正式对象、审批记录和证据链。
|
||||
5. `ExecutionBridge` 页面还没有消费 dev-sync / GitHub / PromptPackage 真实接口。
|
||||
6. `ReleaseGrowth` 还没有把 release validation、feedback、revenue、ROI、compliance 真实数据串成发布后反馈循环。
|
||||
7. `TeamLayer` 仍是产品表达层，缺少真实成员角色、Role Inbox、Decision Desk、Team Feed 的数据模型和审查流程。
|
||||
|
||||
## 2. 下一步推进方向
|
||||
|
||||
下一步不要扩大战线，不要新增“大模块”。正确方向是：
|
||||
|
||||
**把 V1 主链真实闭环化。**
|
||||
|
||||
也就是从“本地高保真原型”推进到“真实项目对象 + 真实 AI 提取 + 真实确认写入 + 真实执行回写”。
|
||||
|
||||
### 2.1 下一阶段总目标
|
||||
|
||||
阶段目标命名为：
|
||||
|
||||
**V1 Productized Loop**
|
||||
|
||||
验收标准：
|
||||
|
||||
- 用户从 `/project-launch` 输入一个 AI 应用创意。
|
||||
- 后端生成可审查的结构化草案或变更集。
|
||||
- 用户确认后创建项目，并写入项目真相层。
|
||||
- 进入 `/command-center` 后能看到真实项目线程、结构化提取、待确认项和项目对象。
|
||||
- 用户接受变更后，正式对象、审批记录、证据链同步更新。
|
||||
- 至少一个任务能生成 Prompt Package，并进入 Execution Bridge。
|
||||
- Execution Bridge 能消费真实 dev-sync summary 或 progress event。
|
||||
- 发布/反馈页能消费至少一类真实 release validation / feedback / revenue / compliance 数据。
|
||||
|
||||
### 2.2 暂不推进的方向
|
||||
|
||||
下一阶段暂不推进：
|
||||
|
||||
- 完整财务系统。
|
||||
- 完整合规平台。
|
||||
- 企业组织树和复杂权限矩阵。
|
||||
- 多项目 portfolio。
|
||||
- 应用市场、投融资、孵化生态。
|
||||
- 前台多 agent 选择器。
|
||||
- 与产品主链无关的后台治理页扩展。
|
||||
|
||||
这些都不是当前瓶颈。
|
||||
|
||||
## 3. 推荐推进顺序
|
||||
|
||||
### 3.0 功能原型一致性治理
|
||||
|
||||
任何 PMFlow 核心功能在继续出图、重画、实现或新开线程接续前，必须先确认是否已有 canonical 功能契约。若已有契约，后续只能在该契约下新增状态、补充局部区域或做明确版本迭代，不能把同一功能重新设计成另一套页面。
|
||||
|
||||
功能契约至少包含：
|
||||
|
||||
- 功能定位
|
||||
- 页面/状态列表
|
||||
- 固定导航壳
|
||||
- 核心对象模型
|
||||
- 状态标签体系
|
||||
- 用户动作
|
||||
- AI 动作
|
||||
- 系统状态
|
||||
- 移动端规则
|
||||
- 不可随意改变的部分
|
||||
- 可扩展的部分
|
||||
|
||||
确认流程：
|
||||
|
||||
1. 先列出本轮涉及的功能清单。
|
||||
2. 每次只提交一个功能契约给用户确认。
|
||||
3. 用户确认后，才把该功能契约写入本文档或对应产品真源。
|
||||
4. 后续原型图、实现、验收都以已确认契约为准。
|
||||
5. 如需重构，必须先说明旧版是什么、新版改什么、迁移影响是什么，并得到明确确认。
|
||||
|
||||
当前需要逐个确认的功能清单：
|
||||
|
||||
- 新项目启动台
|
||||
- 个人空间首页
|
||||
- 项目指挥台
|
||||
- 本轮结构化提取
|
||||
- 决策与待确认
|
||||
- 项目记忆
|
||||
- 移动端底部导航
|
||||
- 项目切换器
|
||||
- 项目工作台
|
||||
- 开发执行联动
|
||||
- 发布与增长
|
||||
- 团队协作
|
||||
|
||||
### Phase A：产品合同收口
|
||||
|
||||
目标：
|
||||
|
||||
把 `pmflow-os` 本地类型、现有 SSTC/semantic facts/ai_project_control 后端对象和 V1 蓝图对象对齐。
|
||||
|
||||
范围：
|
||||
|
||||
- 梳理 `ProjectThread / ChangeSet / ChangeItem / Evidence / Approval / ProjectMemory / ExecutionRun` 的后端合同。
|
||||
- 明确哪些对象复用现有表，哪些需要新表或投影表。
|
||||
- 明确 `frontend/src/features/pmflow-os/types.ts` 如何映射到 API response。
|
||||
- 明确哪些接口走已有 `sstc_api` / `dev_sync`，哪些需要新增 `pmflow_os_api`。
|
||||
|
||||
产物：
|
||||
|
||||
- API/Schema 设计说明或直接 Pydantic schema。
|
||||
- 更新 `docs/architecture/CODE_REFERENCE_INDEX.md`。
|
||||
- 如新增表，必须 Alembic migration。
|
||||
|
||||
验收：
|
||||
|
||||
- 能回答“前端每一个本地对象从哪个后端字段来，写回到哪里去”。
|
||||
- 不能再出现前端原型对象和后端业务对象各讲各话。
|
||||
|
||||
### Phase B：Project Launch 真实创建链
|
||||
|
||||
目标：
|
||||
|
||||
把新项目启动台从本地状态机接到真实项目创建/草案确认主链。
|
||||
|
||||
范围：
|
||||
|
||||
- `/project-launch` 意图输入接真实 API。
|
||||
- AI 结构化结果必须产出可审查草案，而不是直接静默创建。
|
||||
- 用户确认后创建项目，并跳转真实 `/command-center`。
|
||||
- 创建结果必须写入项目真相层初始对象：Idea、Requirement、Decision、Risk、Task 或等价 SSTC 对象。
|
||||
|
||||
验收：
|
||||
|
||||
- 真实接口创建项目。
|
||||
- 失败时显式失败，不用 mock 冒充成功。
|
||||
- 创建成功后进入真实项目上下文。
|
||||
- 项目创建前移动端仍不展示正式底部导航。
|
||||
|
||||
### Phase C：Change Review 与 Project Memory 写入
|
||||
|
||||
目标：
|
||||
|
||||
让对话/结构化提取生成的 ChangeSet 能被接受、修改、暂缓，并写入正式项目对象和证据链。
|
||||
|
||||
当前拆分：
|
||||
|
||||
- C1：真实 Change Review 数据底座与审查状态机，已实现 `ChangeSet / ChangeItem / Approval / EvidenceLink` 表和 `accept / edit / defer`，但不 commit。
|
||||
- C2：提交入库，把已接受/已编辑 ChangeItem 写入 `truth_nodes / tasks / semantic_facts` 并完成高风险 approval gate。
|
||||
|
||||
范围：
|
||||
|
||||
- `StructuredExtractionPage` 接真实提取结果。
|
||||
- `ChangeReviewPage` 接真实 ChangeSet。
|
||||
- 接受/修改/暂缓动作调用后端。
|
||||
- C2 写入后 `ProjectMemoryPage / WorkGraphPage / TeamFeed` 能读到最新对象。
|
||||
|
||||
验收：
|
||||
|
||||
- ChangeSet 有 Evidence。
|
||||
- 高风险变更需要 Approval。
|
||||
- C1 接受后只进入 `accepted / edited / deferred` 审查状态，不进入 Project Memory。
|
||||
- C2 commit 后对象状态从 proposed/draft 进入 confirmed 或对应正式状态。
|
||||
- 暂缓后不进入项目真相层，但仍留审计。
|
||||
|
||||
### Phase D：Execution Bridge 真实开发同步
|
||||
|
||||
目标：
|
||||
|
||||
让 PMFlow 真正连接开发执行，而不是只展示执行概念。
|
||||
|
||||
范围：
|
||||
|
||||
- `ExecutionBridgePage` 消费 `devSyncApi`。
|
||||
- 任务能生成 Prompt Package。
|
||||
- 能绑定 repo 或展示 GitHub App 安装状态。
|
||||
- 能创建或读取 ProgressEvent。
|
||||
- 能把 PR/commit/test 信息回写到任务和 Team Feed。
|
||||
|
||||
验收：
|
||||
|
||||
- 至少一个真实任务能进入执行桥。
|
||||
- 能看到真实 Prompt Package 或 dev task。
|
||||
- 能看到真实 progress event。
|
||||
- 任务状态能随回写变化。
|
||||
|
||||
### Phase E：Release / Growth 轻量闭环
|
||||
|
||||
目标：
|
||||
|
||||
上线后反馈进入下一轮迭代，不停在“开发完成”。
|
||||
|
||||
范围：
|
||||
|
||||
- `ReleaseGrowthPage` 消费 release validation。
|
||||
- 支持 feedback ingest。
|
||||
- 支持 revenue event 或基础 ROI snapshot。
|
||||
- 支持 compliance check 的轻量门禁。
|
||||
- 反馈能生成 IterationRecommendation 或下一轮 ChangeSet。
|
||||
|
||||
验收：
|
||||
|
||||
- 发布前有门禁。
|
||||
- 发布后有反馈/收入/成本/合规至少一类真实信号。
|
||||
- 信号能回流为下一轮建议，不只是展示图表。
|
||||
|
||||
### Phase F：Team-ready 最小闭环
|
||||
|
||||
目标：
|
||||
|
||||
不做重型团队管理，但补齐小团队围绕项目真相层协作的最小能力。
|
||||
|
||||
范围：
|
||||
|
||||
- 成员归属。
|
||||
- 角色收件箱 Role Inbox。
|
||||
- Team Feed。
|
||||
- Decision Desk 或高风险变更多人审查。
|
||||
- Agent Workforce 的只读可见化。
|
||||
|
||||
验收：
|
||||
|
||||
- 不同角色看到不同待处理项。
|
||||
- 高风险 ChangeSet 能指定 reviewer/owner。
|
||||
- Team Feed 展示 AI 提取、人工确认、执行回写、测试/发布变化。
|
||||
|
||||
## 4. 单次任务范围标准
|
||||
|
||||
每次 Codex 执行产品推进任务，必须控制为一个“可闭环增量”，不要跨太多面。
|
||||
|
||||
### 4.1 默认范围
|
||||
|
||||
一次任务最多覆盖：
|
||||
|
||||
- 一个产品表面：如 Project Launch / Change Review / Execution Bridge。
|
||||
- 一个后端合同或服务切片。
|
||||
- 一个前端接入切片。
|
||||
- 对应测试。
|
||||
- 对应文档进度回写。
|
||||
|
||||
如果预计改动超过 5 个核心文件或超过约 200 行业务代码，必须先拆子任务，除非是同一根因的缺陷修复。
|
||||
|
||||
### 4.2 推荐任务模板
|
||||
|
||||
每次新任务开始前，先给自己明确：
|
||||
|
||||
- 本次要推进的 Phase。
|
||||
- 本次要打通的用户路径。
|
||||
- 涉及的前端入口。
|
||||
- 涉及的后端 API / service / model。
|
||||
- 本次不处理的边界。
|
||||
- 最小验证命令。
|
||||
- 完成后要更新的进度文档。
|
||||
|
||||
### 4.3 禁止范围漂移
|
||||
|
||||
产品推进任务里禁止顺手做：
|
||||
|
||||
- 无关视觉重构。
|
||||
- 无关后台治理页扩展。
|
||||
- 无关权限体系大改。
|
||||
- 无关 AI prompt 大改。
|
||||
- 无关模型路由策略调整。
|
||||
- 无关文案大清洗。
|
||||
|
||||
除非这些问题直接阻断本次用户路径。
|
||||
|
||||
### 4.4 Codex 并行推进协议
|
||||
|
||||
PMFlow 允许多个 Codex 线程并行推进，但并行单位必须是明确的 `Packet`，不能是“一个大模块”或“一个方向”。没有 `write_scope` 的任务不允许并行执行。
|
||||
|
||||
每个并行 `Packet` 开始前必须声明：
|
||||
|
||||
- `packet_id`
|
||||
- `phase`
|
||||
- `owner_thread`
|
||||
- `base_ref`
|
||||
- `read_scope`
|
||||
- `write_scope`
|
||||
- `forbidden_paths`
|
||||
- `shared_files`
|
||||
- `depends_on`
|
||||
- `merge_after`
|
||||
- `verification`
|
||||
- `docs_to_sync`
|
||||
|
||||
并行硬规则：
|
||||
|
||||
- 只有 `write_scope` 不重叠的 Packet 才允许并行。
|
||||
- 任意两个 Packet 若同时需要改 `router / schema / migration / shared API client / shared store / CLAUDE.md / CODE_REFERENCE_INDEX.md`，必须串行。
|
||||
- 每轮并行最多保留一个 `contract / migration / router owner`；其它线程只能消费该 owner 已定义的稳定接口。
|
||||
- 并行线程不得在自己的 `write_scope` 外做“顺手修复”；发现阻塞问题时，只记录到 integration notes 或新建后续 Packet。
|
||||
- 同一批并行开发必须指定一个 `integration owner`，负责最终合并共享文件、跑集成验证和更新进度台账。
|
||||
|
||||
### 4.5 V1 Productized Loop 默认并行切片
|
||||
|
||||
V1 主链并行开发默认按 lane 切分：
|
||||
|
||||
- `Contract Lane`：API / Schema / DB migration / 核心对象合同，只允许单线程拥有。
|
||||
- `Backend Lane`：service + route + tests，必须依赖 Contract Lane。
|
||||
- `Frontend Lane`：`frontend/src/api/` + React Query / store 接入，必须依赖稳定 API 合同。
|
||||
- `UI Lane`：页面展示、状态、交互、响应式，只能改功能域内组件，不能改 API 合同。
|
||||
- `Docs/Test Lane`：回归补充、文档同步、验证矩阵，可以和非共享代码并行，但最终由 integration owner 统一收口。
|
||||
|
||||
默认合并顺序：
|
||||
|
||||
1. Contract / migration
|
||||
2. Backend service / API
|
||||
3. Frontend API / store
|
||||
4. UI / page
|
||||
5. Docs / test / integration
|
||||
|
||||
### 4.6 Phase C2 并行试点拆包
|
||||
|
||||
当前下一阶段 `Phase C2：ChangeSet commit 入库` 默认拆成四个 Packet：
|
||||
|
||||
- `C2-contract`
|
||||
- Lane：`Contract Lane`
|
||||
- 目标：定义 commit API、写入规则、高风险 approval gate、响应合同和失败语义。
|
||||
- 写范围：PMFlow OS 产品合同、API 合同、schema 草案或对应设计文档。
|
||||
- 退出条件：后端和前端实现线程不需要再自行决定 API shape。
|
||||
- `C2-backend`
|
||||
- Lane：`Backend Lane`
|
||||
- 目标：实现 ChangeSet commit service、route、transaction、权限边界和后端测试。
|
||||
- 依赖：`C2-contract`
|
||||
- 写范围：`backend/app/api/pmflow_os_api/`、`backend/app/services/pmflow_change_review_service.py`、`backend/app/schemas/pmflow_os.py`、相关 tests；若需要 migration，必须回到 Contract Lane 串行处理。
|
||||
- `C2-frontend`
|
||||
- Lane：`Frontend Lane`
|
||||
- 目标：接入 commit API，更新 `pmflow-os` store、Change Review 状态和错误/成功反馈。
|
||||
- 依赖：`C2-contract`
|
||||
- 写范围：`frontend/src/api/pmflowOs.ts`、`frontend/src/features/pmflow-os/store.tsx`、`ChangeReviewPage` 或 owned 组件测试。
|
||||
- `C2-docs-verification`
|
||||
- Lane：`Docs/Test Lane`
|
||||
- 目标：同步产品推进台账、代码索引、API 合同、架构库存，并执行最终集成验证。
|
||||
- 依赖：`C2-backend`、`C2-frontend`
|
||||
- 写范围：文档和验证记录；共享文档由 integration owner 统一合并。
|
||||
|
||||
`C2-contract` 必须先完成；`C2-backend` 和 `C2-frontend` 只能在合同稳定后有限并行；最终必须由一个 integration owner 统一收口。
|
||||
|
||||
### 4.7 分支与 worktree 协议
|
||||
|
||||
并行开发默认使用独立分支和独立 worktree：
|
||||
|
||||
- 分支命名：`codex/<packet_id>`。
|
||||
- 每个 Packet 必须记录启动时的 `base_ref`。
|
||||
- 每个并行线程优先使用独立 git worktree，避免同一工作区文件互相覆盖。
|
||||
- 合并前必须检查当前分支是否落后主集成分支。
|
||||
- 合并前必须检查 `git diff --name-only`，确认没有写出 `write_scope`。
|
||||
- 触碰共享高冲突文件时，必须交由 integration owner 合并。
|
||||
|
||||
### 4.8 Packet commit 协议
|
||||
|
||||
并行开发不是“每改一行就提交”，也不是“多个 Packet 混在一个长期分支里攒”。默认规则：
|
||||
|
||||
- 一个 Packet 对应一个短生命周期分支：`codex/<packet_id>`。
|
||||
- Packet 完成、验证通过、文档同步完成后，必须形成至少一个可审查 commit。
|
||||
- Codex 必须自行执行 commit gate 判定，不把“该不该提交”默认丢给用户判断。
|
||||
- 复杂 Packet 可以在同一分支内做多个 checkpoint commit，但每个 commit 都必须是逻辑完整切片，不能提交半成品、失败验证或越界改动。
|
||||
- 不允许把多个不同 Packet 的实现混进同一个 commit。
|
||||
- 不允许在旧 Packet 分支上继续做新 Packet；新 Packet 必须从最新 integration base 或明确依赖分支重新开 `codex/<new_packet_id>`。
|
||||
- 如果新 Packet 依赖尚未合并的 `Contract Lane`，优先等待合同分支合入；确需提前开发时，必须以该合同分支作为 `base_ref`，并在任务包里写明 `depends_on / merge_after`。
|
||||
- integration owner 只合并通过 `Parallel Integration Gate` 的 Packet commit；未验证 commit 只能留在 Packet 分支内，不进入主集成分支。
|
||||
- 每个 Packet 合并后，旧 Packet 分支只用于追溯，不再追加新业务改动。
|
||||
|
||||
commit gate 判定：
|
||||
|
||||
- `auto_commit`：满足全部条件时，Codex 应自行提交当前 Packet 分支。
|
||||
- 当前改动全部在 `write_scope` 内。
|
||||
- 没有混入用户或其它线程的未归属改动。
|
||||
- 触碰共享高冲突文件时，当前线程就是该文件的 owner 或 integration owner。
|
||||
- 必要验证已通过；若验证无法执行，原因和影响已经写入结果与任务包。
|
||||
- 必要文档已同步。
|
||||
- commit 内容只包含当前 Packet。
|
||||
- `hold_no_commit`：满足任一条件时，Codex 不得提交，只能报告阻塞和证据。
|
||||
- 验证失败且失败与本 Packet 相关。
|
||||
- `git diff --name-only` 发现越界改动。
|
||||
- 工作区混入无法归属的用户改动或其它线程改动。
|
||||
- 发现 migration 多 head、合同不稳定、API shape 未定或依赖 Packet 未完成。
|
||||
- 需要破坏性删除、重置、强推、覆盖、批量迁移等高风险操作。
|
||||
- `ask_before_commit`：满足任一条件时，Codex 必须先说明事实并等用户拍板。
|
||||
- 用户明确要求只改不提交。
|
||||
- commit 需要包含共享高冲突文件，但当前线程不是 owner。
|
||||
- 验证无法运行且该 Packet 风险较高。
|
||||
- 需要把多个 Packet 的改动临时合在一个 commit 里。
|
||||
- 需要提交历史遗留脏改动才能让当前 Packet 自洽。
|
||||
|
||||
推荐 commit 节奏：
|
||||
|
||||
1. `contract` Packet：合同文档、schema 草案或 migration 约束稳定后 commit。
|
||||
2. `backend` Packet：后端实现和对应测试通过后 commit。
|
||||
3. `frontend` Packet：API/store/UI 接入和对应前端验证通过后 commit。
|
||||
4. `docs-verification` Packet：文档同步、最终验证记录和进度台账完成后 commit。
|
||||
|
||||
### 4.9 Parallel Integration Gate
|
||||
|
||||
每批并行开发结束后，integration owner 必须执行集成验收：
|
||||
|
||||
- `git diff --name-only` 检查每个 Packet 是否越界。
|
||||
- 后端改动：`python -m py_compile` + 相关 `pytest`。
|
||||
- 前端改动：`npm run typecheck` + `npm run build` + 相关 focused tests。
|
||||
- migration 改动：`alembic heads` 必须单 head；必要时执行 `alembic upgrade head`。
|
||||
- 文档：产品推进台账、代码索引、API 合同、架构库存同步完成。
|
||||
- 若后端或 migration 改动已经落地，按项目规则执行热部署/重启；若不能执行，必须明确写阻塞原因。
|
||||
|
||||
## 5. 每次完成后的进度回写标准
|
||||
|
||||
后续 Codex 每完成一个 PMFlow 产品推进任务，必须自己更新进度，不需要用户额外提醒。
|
||||
|
||||
### 5.1 必须更新的地方
|
||||
|
||||
每次完成后至少更新：
|
||||
|
||||
1. 本文档 `## 8. 进度台账`
|
||||
- 新增一条记录。
|
||||
- 写清完成内容、影响范围、验证结果、下一步建议。
|
||||
2. 如果新增/删除/重命名文件或入口：
|
||||
- 更新 `CLAUDE.md`
|
||||
- 更新 `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||||
- 更新 `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||||
3. 如果新增/修改 API/Schema：
|
||||
- 更新 `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||||
- 必要时更新 `docs/architecture/API_CONTRACTS.md`
|
||||
4. 如果新增运行边界、禁止项或系统行为约束：
|
||||
- 更新 `docs/architecture/RUNTIME_GUARDRAILS.md`
|
||||
5. 如果改变产品战略或不可偏离项：
|
||||
- 更新 `docs/PMFLOW_PRODUCT_BLUEPRINT.md`
|
||||
- 更新 `USER.md`
|
||||
|
||||
### 5.2 进度台账记录格式
|
||||
|
||||
每条记录必须包含：
|
||||
|
||||
- 日期。
|
||||
- Phase。
|
||||
- 状态：`done / partial / blocked`。
|
||||
- 完成内容。
|
||||
- 涉及文件。
|
||||
- 验证命令和结果。
|
||||
- 未完成或风险。
|
||||
- 下一步建议。
|
||||
|
||||
### 5.3 什么时候不用更新蓝图
|
||||
|
||||
普通实现、接 API、修 bug、补测试，不更新产品蓝图。
|
||||
|
||||
只有以下情况才更新蓝图：
|
||||
|
||||
- 用户改变产品定位。
|
||||
- V1 范围改变。
|
||||
- 团队方向改变。
|
||||
- 新增/删除核心产品表面。
|
||||
- 改变不可偏离项。
|
||||
|
||||
## 6. 新开线程接续标准
|
||||
|
||||
任何新 Codex 线程，如果用户要求继续 PMFlow 产品推进，必须先读：
|
||||
|
||||
1. `USER.md`
|
||||
2. `docs/PMFLOW_PRODUCT_BLUEPRINT.md`
|
||||
3. `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||||
4. `CLAUDE.md`
|
||||
5. `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||||
|
||||
然后再查当前目标相关代码。
|
||||
|
||||
新线程不得：
|
||||
|
||||
- 重新讨论 PMFlow 是否应该做对话驱动 OS。
|
||||
- 重新建议变成传统项目管理工具。
|
||||
- 重新发散大而全模块。
|
||||
- 忽略 `## 8. 进度台账` 直接从头设计。
|
||||
- 把本地原型当成真实后端闭环。
|
||||
- 把已有后端 `ai_project_control / dev_sync / sstc model_control` 忽略后重造一套。
|
||||
|
||||
## 7. 当前下一步推荐任务
|
||||
|
||||
当前最建议下一步执行：
|
||||
|
||||
**Phase C2：ChangeSet commit 入库。**
|
||||
|
||||
原因：
|
||||
|
||||
- A3 已完成真实只读投影，Phase B 已完成真实 Project Launch 创建链。
|
||||
- Phase C1 已把项目内消息、结构化候选、审查动作和证据链落到真实表。
|
||||
- 当前缺口是把已接受/已编辑的 ChangeItem 经 commit 写入 `truth_nodes / tasks / semantic_facts`，并补齐高风险 approval gate。
|
||||
|
||||
### 7.1 Phase A 建议拆成三个小任务
|
||||
|
||||
#### A1：对象合同映射
|
||||
|
||||
目标：
|
||||
|
||||
把 `frontend/src/features/pmflow-os/types.ts` 里的对象逐一映射到现有后端对象或新增对象。
|
||||
|
||||
输出：
|
||||
|
||||
- 一张合同映射表。
|
||||
- 明确复用 `TruthNode / Task / semantic facts / ai_project_control` 的边界。
|
||||
- 明确是否需要新增 `pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`。
|
||||
|
||||
#### A2：API 合同设计
|
||||
|
||||
目标：
|
||||
|
||||
定义 PMFlow OS 读写 API：
|
||||
|
||||
- 获取项目线程和当前 Project Memory。
|
||||
- 创建结构化提取请求。
|
||||
- 获取 ChangeSet。
|
||||
- 接受/修改/暂缓 ChangeItem。
|
||||
- 将确认结果写入 Work Graph / Project Memory。
|
||||
- 获取 Execution Bridge summary。
|
||||
|
||||
输出：
|
||||
|
||||
- Pydantic schema。
|
||||
- API 路由设计。
|
||||
- API response envelope。
|
||||
|
||||
#### A3：最小真实读路径
|
||||
|
||||
目标：
|
||||
|
||||
先让 `CommandCenter / ProjectMemory / WorkGraph` 从真实后端读取一个项目的摘要和正式对象。
|
||||
|
||||
输出：
|
||||
|
||||
- 前端 API 封装。
|
||||
- React Query 接入。
|
||||
- 本地 mock 降为 fallback/demo，不再是正式路径。
|
||||
- 最小测试。
|
||||
|
||||
## 8. 进度台账
|
||||
|
||||
### 2026-04-26 / Parallel Delivery Governance / done
|
||||
|
||||
完成内容：
|
||||
|
||||
- 新增 Codex 并行推进协议，明确并行单位必须是带 `read_scope / write_scope / forbidden_paths / shared_files / base_ref / merge_after` 的 Packet。
|
||||
- 建立 V1 Productized Loop 默认并行 lane：`Contract / Backend / Frontend / UI / Docs-Test`，并固定合同、后端、前端、UI、文档集成的合并顺序。
|
||||
- 将下一阶段 Phase C2 拆成 `C2-contract / C2-backend / C2-frontend / C2-docs-verification` 四个可分派 Packet，明确依赖和写范围。
|
||||
- 新增分支、worktree、Packet commit 与 commit gate 协议：并行线程默认使用 `codex/<packet_id>` 分支、记录 `base_ref`、优先独立 worktree；Packet 完成后由 Codex 自行判定 `auto_commit / hold_no_commit / ask_before_commit`，通过验证后形成可审查 commit，新 Packet 从最新 integration base 或明确依赖分支重新开分支。
|
||||
- 新增 `Parallel Integration Gate`，要求 integration owner 检查越界 diff、后端/前端/migration 验证、文档同步和热部署说明。
|
||||
|
||||
涉及文件：
|
||||
|
||||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||||
- `docs/architecture/TASK_BRIEF_TEMPLATE.md`
|
||||
- `AGENTS.md`
|
||||
- `CLAUDE.md`
|
||||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||||
|
||||
验证：
|
||||
|
||||
- 文档静态检查通过：新增协议覆盖并行前置条件、Packet 模板、write scope / forbidden paths、共享文件锁、branch / worktree / base ref、Packet commit、commit gate、merge order、integration gate。
|
||||
- 本轮只改治理文档，未新增代码、API、Schema 或 migration，未运行编译/单测。
|
||||
|
||||
未完成或风险：
|
||||
|
||||
- 当前仓库仍是大面积脏工作区；正式启动多线程并行前，需要先冻结当前改动归属，避免历史脏状态被误判为新冲突。
|
||||
|
||||
下一步建议：
|
||||
|
||||
- 以 `C2-contract` 作为第一条并行治理试点 Packet，先锁定 ChangeSet commit 合同，再分派后端和前端线程。
|
||||
|
||||
### 2026-04-25 / Phase A - PMFlow OS Product Contract / done
|
||||
|
||||
完成内容：
|
||||
|
||||
- 新增 PMFlow OS 产品合同，明确 `ProjectTruthState / Thread / Message / ChangeSet / ChangeItem / Evidence / Approval / Requirement / Decision / Task / Risk / ModelDecision / TestRun / Release / MetricSignal / ExecutionContext / TeamFeed` 的前后端映射。
|
||||
- 明确复用边界：正式项目对象优先复用 `truth_nodes / tasks / semantic_facts`，AI 应用控制面复用 `ai_project_control` 与 SSTC model_control，执行桥复用 `dev_sync / prompt_packages / progress_events`。
|
||||
- 明确建议新增但本轮不建表的 PMFlow OS 专属合同对象：`pmflow_threads / pmflow_thread_messages / pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`。
|
||||
- 定义 PMFlow OS API 草案：`truth-state / messages / extractions / change-set detail / accept / edit / defer / commit / execution-summary`。
|
||||
- 明确 `accept/edit/defer` 只改变审查状态，`commit` 才写入 `truth_nodes / tasks / semantic_facts` 等正式对象。
|
||||
|
||||
涉及文件：
|
||||
|
||||
- `docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md`
|
||||
- `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||||
- `CLAUDE.md`
|
||||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||||
|
||||
验证：
|
||||
|
||||
- 静态检查引用路径与核心对象完成。
|
||||
- 本轮只改文档，未新增代码、API、Schema 或 migration，未运行编译/单测。
|
||||
|
||||
未完成或风险：
|
||||
|
||||
- API 尚未实现，数据库 migration 尚未创建。
|
||||
- `truth_nodes.node_type` 的历史值需要在后续 projection 实现时做白名单映射。
|
||||
- `ChangeSet / Approval / EvidenceLink / Thread` 仍需后续实现真实表与服务。
|
||||
|
||||
下一步建议：
|
||||
|
||||
- 执行 A3 最小真实读路径：新增只读 `pmflow_os_api` projection，先实现 `GET /pmflow-os/projects/{project_id}/truth-state` 与 `GET /pmflow-os/projects/{project_id}/execution-summary`。
|
||||
|
||||
### 2026-04-25 / A3 - PMFlow OS 最小真实读路径 / done
|
||||
|
||||
完成内容：
|
||||
|
||||
- 新增只读后端入口 `backend/app/api/pmflow_os_api/`，注册 `GET /pmflow-os/projects/{project_id}/truth-state` 与 `GET /pmflow-os/projects/{project_id}/execution-summary`，统一返回 `{code,message,data}`。
|
||||
- 新增 `backend/app/services/pmflow_os_projection_service.py` 与 `backend/app/schemas/pmflow_os.py`，把 `ProjectTruthState` 投影接到真实后端对象：`Requirement / Decision / Risk / Release` 来自 `truth_nodes`，`Task` 来自 `tasks`，`Project Memory` 来自 `truth_nodes + semantic_facts`，`ExecutionContext` 来自 `dev-sync summary + prompt_packages + progress_events + repo/task code link`。
|
||||
- `Thread / ChangeSet / ChangeItem / Approval / EvidenceLink` 本轮没有稳定表，不用 mock 冒充；接口返回空集合并通过 `projectionWarnings` 明确说明。
|
||||
- 新增前端 API `frontend/src/api/pmflowOs.ts`，封装 `getPMFlowTruthState(projectId)` 与 `getPMFlowExecutionSummary(projectId)`。
|
||||
- `frontend/src/features/pmflow-os/store.tsx` 现支持 `?projectId=<id>` 通过 React Query 读取真实 `truth-state`；只有显式 `?demo=1` 或 `?dataSource=demo` 才启用本地 mock 演示动作。真实 API 失败时显示错误/空态，不静默 fallback 成 mock 成功。
|
||||
- `ProjectMemoryPage` 在真实模式下展示后端 `projectMemory.truthNodeFacts / semanticFacts`，不再把前端 mock 当作项目记忆来源。
|
||||
|
||||
涉及文件：
|
||||
|
||||
- `backend/app/api/pmflow_os_api/__init__.py`
|
||||
- `backend/app/services/pmflow_os_projection_service.py`
|
||||
- `backend/app/schemas/pmflow_os.py`
|
||||
- `backend/app/api/router.py`
|
||||
- `backend/tests/test_pmflow_os_projection_api.py`
|
||||
- `frontend/src/api/pmflowOs.ts`
|
||||
- `frontend/src/features/pmflow-os/store.tsx`
|
||||
- `frontend/src/features/pmflow-os/components/PMFlowOsFrame.tsx`
|
||||
- `frontend/src/features/pmflow-os/pages/CommandCenterPage.tsx`
|
||||
- `frontend/src/features/pmflow-os/pages/ProjectMemoryPage.tsx`
|
||||
- `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||||
- `CLAUDE.md`
|
||||
|
||||
验证：
|
||||
|
||||
- 静态路径检查完成。
|
||||
- 后端：`python -m py_compile`（Python 3.12 runtime）通过。
|
||||
- 后端：`pytest tests/test_pmflow_os_projection_api.py -q` 通过，覆盖空项目 truth-state、Project Memory projection、tasks projection、execution-summary 空态、tenant/project 权限边界。
|
||||
- 后端 router import smoke：`from app.api.router import api_router` 通过。
|
||||
- 前端：`npm run typecheck` 通过。
|
||||
- 前端：`npm run build` 通过。
|
||||
|
||||
剩余缺口：
|
||||
|
||||
- 本轮不新增 migration，因此 `Thread / ChangeSet / ChangeItem / Approval / EvidenceLink` 仍为空集合或 warning；后续 Phase C 再补真实表与 mutation。
|
||||
- `WorkGraph / ExecutionBridge / ReleaseGrowth` 仍有部分静态展示区，A3 只保证 truth store 与 Project Memory 真实读取入口，不做 UI 重画和完整页面数据替换。
|
||||
- 后端代码已改，但当前是在本地开发工作区执行验证，未连接运行中的部署服务；热部署/重启需要在实际部署环境执行。
|
||||
|
||||
### 2026-04-25 / Phase B - Project Launch 真实创建链 / done
|
||||
|
||||
完成内容：
|
||||
|
||||
- 新增 Phase B 专用启动链表 migration `backend/alembic/versions/20260425_add_pmflow_launch_tables.py`，只创建 `pmflow_launch_drafts / pmflow_threads / pmflow_thread_messages`；本轮未创建 `pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`。
|
||||
- 新增后端启动链入口 `backend/app/api/pmflow_launch_api/`，注册 `POST /pmflow-launch/drafts` 与 `POST /pmflow-launch/drafts/{draft_id}/confirm`，统一返回 `{code,message,data}`。
|
||||
- 新增 `backend/app/services/pmflow_launch_service.py` 与 `backend/app/schemas/pmflow_launch.py`：草案生成调用 `llm_service.generate_structured_object(function_name="pmflow_launch_draft_v1")` 并显式传 `routing_meta`；结构化失败返回明确错误或 warnings，不用模板句冒充成功。
|
||||
- confirm 在同一事务内锁定草案并创建 `Project / UserProject / PMFlowThread / PMFlowThreadMessage / truth_nodes / tasks / semantic_facts seed / OperationLog`，随后更新草案 `status=confirmed` 与 `confirmed_project_id`；重复 confirm 幂等返回同一 `project_id`，不重复写正式对象。
|
||||
- `truth_nodes.content` 与任务 payload 写入 `launch_draft_id / thread_id / thread_message_id / source=pmflow_launch_confirmed_draft / confidence / evidence`，确保初始 Project Memory 与 Task 能追溯到启动草案和首条用户输入。
|
||||
- A3 `truth-state` projection 已更新为优先读取 `pmflow_threads` 默认启动线程与 `pmflow_thread_messages`，Project Memory 仍只来自 `truth_nodes + semantic_facts`，不从 launch draft 直接拼。
|
||||
- 新增前端 API `frontend/src/api/pmflowLaunch.ts`，封装 `createPMFlowLaunchDraft` 与 `confirmPMFlowLaunchDraft`。
|
||||
- `frontend/src/features/project-launch/useProjectLaunchState.ts` 默认走真实 API；只有显式 `?demo=1` 或 `?dataSource=demo` 才启用本地演示状态机。draft/confirm 失败进入明确失败态，不静默跳 mock 成功态。
|
||||
- 新增 `/pmflow-os` route alias，创建成功后使用后端返回的 `/pmflow-os?projectId=<id>` 进入 A3 真实读路径。
|
||||
|
||||
涉及文件：
|
||||
|
||||
- `backend/alembic/versions/20260425_add_pmflow_launch_tables.py`
|
||||
- `backend/app/models/pmflow_launch.py`
|
||||
- `backend/app/api/pmflow_launch_api/__init__.py`
|
||||
- `backend/app/services/pmflow_launch_service.py`
|
||||
- `backend/app/schemas/pmflow_launch.py`
|
||||
- `backend/app/services/pmflow_os_projection_service.py`
|
||||
- `backend/app/config/ai_prompts_catalog/part_scenes_06.py`
|
||||
- `backend/app/services/llm_service/shared_part_01.py`
|
||||
- `backend/tests/test_pmflow_launch_api.py`
|
||||
- `backend/tests/test_pmflow_os_projection_api.py`
|
||||
- `frontend/src/api/pmflowLaunch.ts`
|
||||
- `frontend/src/features/project-launch/useProjectLaunchState.ts`
|
||||
- `frontend/src/features/project-launch/useProjectLaunchState.test.ts`
|
||||
- `frontend/src/router/index.tsx`
|
||||
- `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||||
- `CLAUDE.md`
|
||||
|
||||
验证：
|
||||
|
||||
- 后端：`python -m py_compile` 新增后端模块、migration、router、prompt 聚合文件通过。
|
||||
- 后端：`pytest tests/test_pmflow_launch_api.py tests/test_pmflow_os_projection_api.py -q` 通过，覆盖 draft 成功、结构化字段缺失、warnings、confirm 创建 Project/thread/message/truth_nodes/tasks、truth-state 回读、幂等、过期/跨 tenant/跨 user、rollback。
|
||||
- Alembic：`alembic upgrade head` 在本地开发 PostgreSQL 成功从 `20260421_finalize_v1_productization` 升级到 `20260425_add_pmflow_launch_tables`。
|
||||
- 前端：`npm run test -- src/features/project-launch/useProjectLaunchState.test.ts` 通过，覆盖真实 draft API、draft 失败、confirm 成功、confirm 失败不进成功态、显式 demo 分支。
|
||||
- 前端：`npm run typecheck` 通过。
|
||||
- 前端：`npm run build` 通过。
|
||||
|
||||
剩余缺口：
|
||||
|
||||
- Phase B 只覆盖首次 Project Launch 创建链；项目内后续 ChangeSet / ChangeItem / Approval / EvidenceLink 审查系统仍留给 Phase C。
|
||||
- 初始 `semantic_facts` seed 仅写用户确认后的 project-level facts；完整异步抽取和治理仍复用既有 semantic facts 管线。
|
||||
|
||||
### 2026-04-26 / Phase C1 - PMFlow Change Review 数据底座与审查状态机 / done
|
||||
|
||||
完成内容：
|
||||
|
||||
- 新增 C1 review 表 migration `backend/alembic/versions/20260426_add_pmflow_change_review_tables.py`，只创建 `pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`；未新增 commit 或 Phase C2 表。
|
||||
- 新增模型 `backend/app/models/pmflow_change_review.py`，所有表包含 `tenant_id`，并按 `tenant_id + project_id` 查询；`ChangeItem` 归属 `ChangeSet`，`Approval` 记录 `accept / edit / defer` 的 before/after，`EvidenceLink` 可引用 thread message。
|
||||
- 新增服务 `backend/app/services/pmflow_change_review_service.py`，实现项目内消息、`proposed_items` extraction、ChangeSet detail、accept/edit/defer 审查状态机；老项目无真实线程时仅允许 `default` 或 `thread-project-{project_id}` 懒创建默认线程。
|
||||
- 在 `backend/app/api/pmflow_os_api/` 扩展 `/pmflow-os` API：`POST /projects/{project_id}/threads/{thread_id}/messages`、`POST /projects/{project_id}/extractions`、`GET /projects/{project_id}/change-sets/{change_set_id}`、`POST /change-items/{change_item_id}/accept|edit|defer`，统一响应包络。
|
||||
- `PMFlowOSProjectionService` 已投影 `changeSets / changeItems / evidence / approvals`，`activeChangeSetId` 取最近 open ChangeSet，`loopStage` 映射为 `command_idle / extraction_ready / review_open`；Project Memory 仍只来自 `truth_nodes + semantic_facts`。
|
||||
- 前端 `frontend/src/api/pmflowOs.ts` 增加 Change Review API wrapper；`frontend/src/features/pmflow-os/store.tsx` 真实模式调用后端 message/extraction/accept/edit/defer，并在成功后 refetch truth-state。真实模式不再本地 promote accepted item，也不假装写入项目记忆；demo 模式仍需显式 `?demo=1` 或 `?dataSource=demo`。
|
||||
|
||||
涉及文件：
|
||||
|
||||
- `backend/alembic/versions/20260426_add_pmflow_change_review_tables.py`
|
||||
- `backend/app/models/pmflow_change_review.py`
|
||||
- `backend/app/services/pmflow_change_review_service.py`
|
||||
- `backend/app/api/pmflow_os_api/__init__.py`
|
||||
- `backend/app/schemas/pmflow_os.py`
|
||||
- `backend/app/services/pmflow_os_projection_service.py`
|
||||
- `backend/tests/test_pmflow_change_review_api.py`
|
||||
- `backend/tests/test_pmflow_os_projection_api.py`
|
||||
- `frontend/src/api/pmflowOs.ts`
|
||||
- `frontend/src/features/pmflow-os/store.tsx`
|
||||
- `frontend/src/features/pmflow-os/store.api.test.tsx`
|
||||
- `frontend/src/features/pmflow-os/pages/ChangeReviewPage.tsx`
|
||||
- `frontend/src/features/pmflow-os/components/ProjectStructuredLoop.tsx`
|
||||
- `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||||
- `docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md`
|
||||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||||
- `CLAUDE.md`
|
||||
|
||||
验证：
|
||||
|
||||
- 后端：`python -m py_compile` 新增后端模型、service、schema、router、migration 通过。
|
||||
- 后端：`pytest tests/test_pmflow_change_review_api.py tests/test_pmflow_os_projection_api.py tests/test_pmflow_launch_api.py -q` 通过，覆盖 message 懒创建线程、extraction、change items、evidence link、detail、accept/edit/defer、reviewed 自动推进、权限边界、truth-state 投影，以及 accepted/edited 不进入 Project Memory。
|
||||
- Alembic：`alembic heads` 返回 `20260426_add_pmflow_change_review_tables (head)`；`alembic upgrade head` 在本地开发 PostgreSQL 成功从 `20260425_add_pmflow_launch_tables` 升级到 `20260426_add_pmflow_change_review_tables`。
|
||||
- 前端：`npm run test -- src/features/pmflow-os` 通过。
|
||||
- 前端：`npm run typecheck` 通过。
|
||||
- 前端：`npm run build` 通过；Vite 仍提示既有循环 chunk warning，但构建成功。
|
||||
|
||||
剩余缺口：
|
||||
|
||||
- C1 不实现 `/commit`，不写 `truth_nodes / tasks / semantic_facts`；accepted/edited 仅代表审查状态，不代表 confirmed Project Memory。
|
||||
- `POST /extractions` 本轮只接收 `proposed_items`，不默认调用 LLM 结构化提取；AI extraction 主链留给后续阶段。
|
||||
- 高风险 `risk_level=high` 本轮只记录风险等级和 approval，commit gate 留给 C2。
|
||||
|
||||
下一步建议：
|
||||
|
||||
- 执行 Phase C2：实现 ChangeSet commit，把 `accepted / edited` ChangeItem 按对象类型写入正式 `truth_nodes / tasks / semantic_facts`，并补齐高风险 approval gate 与部分失败回滚/明细返回。
|
||||
|
||||
### 2026-04-24 / Product Blueprint / done
|
||||
|
||||
完成内容：
|
||||
|
||||
- 整理并落盘 PMFlow 产品蓝图真源。
|
||||
- 明确 PMFlow 是“对话驱动的 AI 产品执行操作系统”。
|
||||
- 明确 `solo-first, team-ready`、项目真相层、ChangeSet 待确认、Execution Bridge、人机混编团队等不可偏离项。
|
||||
|
||||
涉及文件：
|
||||
|
||||
- `docs/PMFLOW_PRODUCT_BLUEPRINT.md`
|
||||
- `USER.md`
|
||||
- `CLAUDE.md`
|
||||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||||
|
||||
验证：
|
||||
|
||||
- 文档新增与引用检查完成。
|
||||
- 无代码改动，未运行编译/测试。
|
||||
|
||||
下一步：
|
||||
|
||||
- 执行 Phase A：PMFlow OS 产品合同收口。
|
||||
|
||||
### 2026-04-24 / Delivery Standard / done
|
||||
|
||||
完成内容：
|
||||
|
||||
- 建立 PMFlow 产品推进执行标准。
|
||||
- 记录当前推进状态、下一阶段方向、Phase A-F 推进顺序、单次任务范围标准和完成后进度回写标准。
|
||||
- 明确新开线程必须先读蓝图、执行标准和代码索引，避免重做或漏做。
|
||||
|
||||
涉及文件：
|
||||
|
||||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||||
- `USER.md`
|
||||
- `CLAUDE.md`
|
||||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||||
|
||||
验证：
|
||||
|
||||
- 文档新增与引用检查完成。
|
||||
- 无代码改动，未运行编译/测试。
|
||||
|
||||
下一步：
|
||||
|
||||
- 从 A1 对象合同映射开始，把前端 `pmflow-os/types.ts` 与后端现有对象逐一对齐。
|
||||
|
|
@ -0,0 +1,513 @@
|
|||
# PMFlow UI Contract
|
||||
|
||||
版本日期：2026-04-24
|
||||
|
||||
本文档是 PMFlow 产品 UI 的长期真源。后续原型图、代码化原型、前端实现、移动端适配和验收截图必须以本文档为准。AI 生成图片只能作为方向参考，不能作为最终设计真源。
|
||||
|
||||
## 1. 总原则
|
||||
|
||||
PMFlow 的 UI 必须表达“对话驱动的 AI 产品执行操作系统”，而不是传统项目管理后台或普通 AI 聊天页。
|
||||
|
||||
核心体验必须稳定为：
|
||||
|
||||
```text
|
||||
用户表达意图 -> AI 自动推进 -> 用户确认落地 -> 系统写入项目真相层 -> 执行与结果回写
|
||||
```
|
||||
|
||||
后续任何页面都必须先判断自己属于哪一层：
|
||||
|
||||
- `空间层`：所有项目、想法、草案、待确认事项和 AI 推进状态的上层入口。
|
||||
- `启动层`：把想法/材料/模板转成项目草案。
|
||||
- `项目层`：围绕一个具体项目持续推进对话、结构化提取、待确认、工作图谱、执行桥和项目记忆。
|
||||
- `结果层`：展示确认、写入、执行、发布、增长等动作结果。
|
||||
|
||||
## 2. 品牌与视觉基线
|
||||
|
||||
### 2.1 Logo
|
||||
|
||||
PMFlow Logo 以用户已确认的品牌规范图为唯一方向：
|
||||
|
||||
- 主标识：蓝色几何图标 + 深色 `PMFlow` 字标。
|
||||
- 图标主色：`#2463EB`。
|
||||
- 字标颜色：深色中性黑灰。
|
||||
- 图标可独立用于应用图标、侧边栏、favicon、移动端入口和小尺寸场景。
|
||||
- 禁止重新发散生成其它 Logo 风格。
|
||||
- 空间壳与项目壳左上角品牌头必须统一使用 `PMFlowBrandHeader`，不得出现一处裸露品牌、一处卡片品牌的双样式漂移。
|
||||
|
||||
### 2.2 色彩
|
||||
|
||||
基础色：
|
||||
|
||||
```text
|
||||
primary: #2463EB
|
||||
background: #FFFFFF
|
||||
surface: #FFFFFF
|
||||
surface-subtle: #F8FAFF / #FBFCFF
|
||||
border: #E6EDF7 / #DFE7F3
|
||||
text-primary: slate-950
|
||||
text-secondary: slate-600
|
||||
text-muted: slate-500 / slate-400
|
||||
```
|
||||
|
||||
状态色：
|
||||
|
||||
```text
|
||||
AI 操作：浅蓝底 + #2463EB
|
||||
待确认：浅橙/浅蓝强调，不使用强警报红作为默认
|
||||
成功/已写入：克制绿色
|
||||
风险：低/中/高分级，红色只用于高风险
|
||||
系统状态：灰色
|
||||
```
|
||||
|
||||
禁止项：
|
||||
|
||||
- 不使用紫色系 AI 套板。
|
||||
- 首版不做暗色模式。
|
||||
- 不做营销页式渐变大背景。
|
||||
- 不做传统后台的重表格视觉。
|
||||
|
||||
### 2.3 字体与密度
|
||||
|
||||
- 页面标题应克制，适配工具型 SaaS，不使用营销页 hero 级夸张字号。
|
||||
- 面板标题、卡片标题和状态说明必须有清晰层级。
|
||||
- 字距保持默认，不使用负字距作为主要风格手段。
|
||||
- 卡片圆角默认不超过 `8-12px`，特殊浮层可略大但需克制。
|
||||
- 信息密度可以高，但必须通过分组、状态标签和视觉语法降低认知负担。
|
||||
|
||||
## 3. 视觉语法
|
||||
|
||||
PMFlow 必须稳定区分四类内容。
|
||||
|
||||
| 类型 | 含义 | 视觉表现 | 用户动作 |
|
||||
| --- | --- | --- | --- |
|
||||
| 用户动作 | 用户主动输入、确认、修改、补充、推进 | `#2463EB` 主按钮、明确输入区、固定决策栏 | 用户主动操作 |
|
||||
| AI 操作 | AI 自动理解、提取、拆解、生成、建议 | 浅蓝工作流、AI 图标、`AI 正在处理 / AI 已生成` 标签 | 用户查看、暂停、补充 |
|
||||
| 系统状态 | 保存、同步、时间、失败、权限、网络 | 灰色状态、轻提示、日志、错误块 | 用户重试或返回 |
|
||||
| 待确认 | 正式写入项目真相层前需要人类拍板 | 独立分组、`待你确认` 标签、风险/证据/影响范围 | 接受、修改、暂不落库 |
|
||||
|
||||
状态标签真源：
|
||||
|
||||
```text
|
||||
用户输入
|
||||
AI 正在处理
|
||||
AI 已生成
|
||||
待你确认
|
||||
已确认
|
||||
已写入项目记忆
|
||||
系统已保存
|
||||
生成失败
|
||||
```
|
||||
|
||||
规则：
|
||||
|
||||
- `AI 已生成` 不等于 `已确认`。
|
||||
- `待你确认` 不等于普通通知。
|
||||
- `已写入项目记忆` 只能在用户确认后出现。
|
||||
- 高风险内容必须展示证据和影响范围，不能只有标签。
|
||||
|
||||
### 3.1 提示、提醒与弹窗标准
|
||||
|
||||
PMFlow 的反馈系统必须服务于“AI 推进、人类拍板、系统留痕”，不能用通用后台式弹窗打断流程。所有提示先判断层级，再选择组件。
|
||||
|
||||
反馈层级：
|
||||
|
||||
| 层级 | 使用场景 | 推荐形态 | 是否打断用户 |
|
||||
| --- | --- | --- | --- |
|
||||
| 轻提示 | 保存成功、复制成功、普通同步完成、非关键操作反馈 | Toast | 不打断 |
|
||||
| 内联提示 | 表单字段错误、当前卡片缺证据、某个模块需要补充信息 | InlineNotice / FieldMessage | 不打断 |
|
||||
| 页面横幅 | 当前页面级状态，如 AI 正在生成、草案未确认、自动保存开启、权限只读 | PageBanner | 不打断，但应持续可见 |
|
||||
| AI 操作流 | AI 正在理解、提取、拆解、回写、失败重试 | AIOperationFeed / 右侧副驾 | 不打断，持续记录 |
|
||||
| 待确认提醒 | AI 生成内容即将写入项目记忆、影响范围较大、需要人类拍板 | HumanDecisionBar / ConfirmPanel | 半打断，必须明确决策 |
|
||||
| 确认弹窗 | 删除、覆盖、发布、邀请、权限变更、成本上限调整等不可逆或高影响动作 | ConfirmDialog | 打断 |
|
||||
| 任务弹窗 | 创建/编辑需求、任务、风险、集成配置等结构化录入 | FormDialog / Drawer | 轻打断 |
|
||||
| 结果页/过渡态 | 项目创建成功、批量写入完成、发布完成、导入完成 | ResultPanel / SuccessTransition | 不用普通弹窗替代 |
|
||||
|
||||
Toast 标准：
|
||||
|
||||
- 只用于短反馈，不承载关键业务事实、风险证据、确认动作或长文本。
|
||||
- 桌面端位置：右上角，避开顶部条，宽度 `320-380px`，圆角 `12px`，轻阴影，最多同时展示 3 条。
|
||||
- 移动端位置：底部导航上方或顶部安全区下方，不能遮挡底部主 CTA、底部导航和键盘。
|
||||
- 默认 3 秒自动消失；错误可延长到 5 秒；带操作按钮的 toast 必须可手动关闭。
|
||||
- 文案结构：`结果 + 对象`，必要时加一句原因；不要写“操作成功”这类空话。
|
||||
- 禁止用 toast 询问用户确认；确认必须使用决策栏、确认面板或确认弹窗。
|
||||
|
||||
内联提示与页面横幅标准：
|
||||
|
||||
- 内联提示贴近问题位置，优先放在输入框下方、卡片顶部或模块空态中。
|
||||
- 页面横幅用于当前页面级状态，放在主画布顶部，背景使用浅色，不抢主 CTA。
|
||||
- AI 相关横幅使用浅蓝底和 `#2463EB`，系统状态使用灰色，待确认使用浅橙或浅蓝，风险只在高风险时使用红色。
|
||||
- 横幅必须说明状态、影响和下一步，不只显示标签。
|
||||
|
||||
确认弹窗标准：
|
||||
|
||||
- 只用于高影响动作：删除、覆盖、发布、批量写入、权限变更、邀请外部成员、成本/模型配置变更。
|
||||
- 桌面端宽度默认 `480px`；涉及影响范围、证据列表或多选项时可用 `640px`；不得超过 `760px`，超过应改为页面或抽屉。
|
||||
- 弹窗结构固定为：标题、影响说明、对象/证据摘要、主要动作、次要动作；危险动作按钮使用克制红色。
|
||||
- 主按钮文案必须具体，例如 `确认写入项目记忆`、`发布当前版本`、`删除这条风险`，禁止只写 `确定`。
|
||||
- 次要按钮使用 `取消`、`返回修改`、`暂不处理` 等明确动作。
|
||||
- 高风险确认必须展示影响范围和可恢复性；不可恢复动作需要二次确认文案或显式对象名。
|
||||
|
||||
移动端弹层标准：
|
||||
|
||||
- 移动端优先使用 bottom sheet 或全屏流转，不直接压缩桌面弹窗。
|
||||
- 轻量选择、AI 引导、补充一句、筛选使用 bottom sheet。
|
||||
- 结构化编辑、草案修改、权限配置使用全屏页或半屏以上 sheet。
|
||||
- 底部固定确认按钮必须避开安全区和全局底部导航；键盘弹出时输入区不能被遮挡。
|
||||
|
||||
PMFlow 专属规则：
|
||||
|
||||
- AI 生成内容的提示必须带 `AI 已生成` 或 `AI 正在处理`，不能伪装成人工结果。
|
||||
- 正式写入项目记忆、需求、决策、任务或风险前，必须出现 `待你确认` 层级，不得只用 toast。
|
||||
- AI 操作失败必须给出失败原因、可恢复动作和是否已保留草稿；禁止静默失败。
|
||||
- 后台异步任务不能只靠 toast，必须在 `AI 正在推进 / 动态 / 右侧副驾` 留下可追溯记录。
|
||||
- 重要提示要能被再次找到；toast 消失后不可成为唯一证据来源。
|
||||
|
||||
## 4. 桌面布局规则
|
||||
|
||||
### 4.1 启动层
|
||||
|
||||
用于 `新项目启动台`。
|
||||
|
||||
结构：
|
||||
|
||||
```text
|
||||
轻量左侧栏 + 顶部轻上下文 + 中央主画布 + 右侧 AI 引导/操作/审查区
|
||||
```
|
||||
|
||||
规则：
|
||||
|
||||
- 项目创建前不展示完整项目导航。
|
||||
- 左侧只保留 `PMFlow / 新建项目 / 最近项目 / 模板 / 导入`。
|
||||
- 顶部只展示 `个人空间 / 当前创建状态`。
|
||||
- AI 不能直接创建正式项目，必须先生成草案并由用户确认。
|
||||
|
||||
### 4.2 空间层
|
||||
|
||||
用于 `个人空间首页`。
|
||||
|
||||
结构：
|
||||
|
||||
```text
|
||||
顶部空间栏 + 左侧空间导航 + 主区域继续推进/待我确认/暂存想法/草案箱 + 右侧 AI 正在推进
|
||||
```
|
||||
|
||||
规则：
|
||||
|
||||
- 空间层不是普通项目列表。
|
||||
- 核心是“现在有哪些东西可以继续推进”。
|
||||
- 不展示团队空间强切换。
|
||||
|
||||
### 4.3 项目层
|
||||
|
||||
用于 `项目指挥台 / 本轮结构化提取 / 决策与待确认 / 项目工作台 / 开发执行 / 发布与增长 / 团队协作 / 项目记忆`。
|
||||
|
||||
结构：
|
||||
|
||||
```text
|
||||
左侧完整项目导航 + 顶部项目上下文条 + 中央主画布 + 右侧上下文副驾
|
||||
```
|
||||
|
||||
固定项目导航：
|
||||
|
||||
```text
|
||||
指挥台
|
||||
项目工作台
|
||||
决策与待确认
|
||||
开发执行
|
||||
发布与增长
|
||||
团队协作
|
||||
项目记忆
|
||||
```
|
||||
|
||||
顶部项目上下文必须包含：
|
||||
|
||||
- `个人空间 / 当前项目名` breadcrumb。
|
||||
- 当前阶段。
|
||||
- 目标摘要。
|
||||
- 当前风险。
|
||||
- 待确认数量或当前状态。
|
||||
- 必要快速动作。
|
||||
|
||||
规则：
|
||||
|
||||
- 点击 `个人空间` 返回空间层。
|
||||
- 点击项目名打开项目切换器。
|
||||
- 左侧项目导航只承载项目内功能入口，不放项目切换卡、当前目标卡、最近项目列表或侧栏内新建项目入口；这些信息统一由顶部项目上下文条承载。
|
||||
- 项目层左侧栏的基础尺寸与空间层左侧栏保持一致：宽度 `244px`、内边距 `px-5 py-5`、背景 `#FBFCFF`、品牌到首组导航 `mt-8`、导航组内间距 `space-y-2`、分组间分割线 `my-7`、导航项高度 `44px`、圆角 `12px`、图标 `16px`，不得另起一套更宽、更紧或更重的侧栏样式。
|
||||
- 项目层页面不能各自发明不同的导航壳。
|
||||
|
||||
## 5. 移动端规则
|
||||
|
||||
### 5.1 创建前
|
||||
|
||||
`新项目启动台 / 首次进入 / 草案确认流程` 不展示全局底部导航。
|
||||
|
||||
结构：
|
||||
|
||||
```text
|
||||
顶部上下文 + 单列主内容 + 底部主 CTA + AI 底部抽屉
|
||||
```
|
||||
|
||||
### 5.2 创建后
|
||||
|
||||
正式应用壳底部导航固定为 5 项，顺序和命名不得漂移：
|
||||
|
||||
```text
|
||||
空间 / 指挥台 / 待确认 / 动态 / 我的
|
||||
```
|
||||
|
||||
含义：
|
||||
|
||||
- `空间`：所有项目、想法、草案的上层入口。
|
||||
- `指挥台`：当前项目主工作面。
|
||||
- `待确认`：AI 生成但需用户拍板的事项。
|
||||
- `动态`：AI 进展、执行回写、系统事件。
|
||||
- `我的`：账户、设置和个人偏好。
|
||||
|
||||
不进入底部导航：
|
||||
|
||||
```text
|
||||
工作台 / 开发执行 / 发布增长 / 项目记忆
|
||||
```
|
||||
|
||||
这些通过项目内二级入口、分段切换、更多菜单或卡片入口进入。
|
||||
|
||||
## 6. 核心功能契约
|
||||
|
||||
### 6.1 新项目启动台
|
||||
|
||||
功能定位：把一句想法、材料或模板交给 AI，生成结构化项目草案。
|
||||
|
||||
状态列表：
|
||||
|
||||
- 意图输入态
|
||||
- AI 工作态
|
||||
- 人类确认态
|
||||
- 草案修改态
|
||||
- 生成失败态
|
||||
- 创建成功过渡态
|
||||
- 移动端意图输入态
|
||||
- 移动端 AI 工作态
|
||||
- 移动端人类确认态
|
||||
|
||||
不可变项：
|
||||
|
||||
- 主流程固定为 `用户表达意图 -> AI 自动推进 -> 用户确认落地`。
|
||||
- AI 不直接创建正式项目。
|
||||
- 默认个人空间，不出现团队空间强选择。
|
||||
- 不展示完整复杂项目导航。
|
||||
|
||||
### 6.2 个人空间首页
|
||||
|
||||
功能定位：空间层入口，管理所有项目、想法、草案、待确认事项和 AI 正在推进的工作。
|
||||
|
||||
固定区域：
|
||||
|
||||
- 继续推进
|
||||
- 待我确认
|
||||
- AI 正在推进
|
||||
- 暂存想法
|
||||
- 草案箱
|
||||
- 新建项目入口
|
||||
|
||||
不可变项：
|
||||
|
||||
- 不做成传统项目列表。
|
||||
- 不做团队组织后台。
|
||||
- 不承载项目内完整工作台功能。
|
||||
|
||||
### 6.3 项目指挥台
|
||||
|
||||
功能定位：具体项目的主工作面，承载对话、结构化提取、待确认入口和下一步动作。
|
||||
|
||||
固定区域：
|
||||
|
||||
- 项目对话
|
||||
- 本轮结构化提取
|
||||
- 下一步建议
|
||||
- 上下文副驾
|
||||
|
||||
不可变项：
|
||||
|
||||
- 不是普通聊天页。
|
||||
- AI 生成内容必须先进入待确认或提取态。
|
||||
- 只有确认后才能显示写入项目记忆。
|
||||
|
||||
### 6.4 本轮结构化提取
|
||||
|
||||
功能定位：展示 AI 从本轮对话中生成的候选项目对象。
|
||||
|
||||
对象分组：
|
||||
|
||||
- 需求
|
||||
- 风险
|
||||
- 决策
|
||||
- 任务
|
||||
- 关联证据
|
||||
|
||||
不可变项：
|
||||
|
||||
- 尚未写入项目记忆。
|
||||
- 必须展示证据、置信度、影响范围和确认需求。
|
||||
|
||||
### 6.5 决策与待确认
|
||||
|
||||
功能定位：业务对象确认台，不是传统审批流。
|
||||
|
||||
固定动作：
|
||||
|
||||
- 接受
|
||||
- 修改
|
||||
- 暂不落库
|
||||
- 批量接受
|
||||
- 稍后处理
|
||||
|
||||
不可变项：
|
||||
|
||||
- AI 建议内容和将写入内容必须可区分。
|
||||
- 待确认项必须展示来源证据和影响范围。
|
||||
|
||||
### 6.6 项目记忆
|
||||
|
||||
功能定位：项目唯一可信事实层，承载已确认事实、决策、约束、证据和可复用上下文。
|
||||
|
||||
状态列表：
|
||||
|
||||
- 项目记忆主视图
|
||||
- 项目记忆写入结果态
|
||||
|
||||
共享对象分类：
|
||||
|
||||
- 已确认事实
|
||||
- 需求与范围
|
||||
- 决策
|
||||
- 约束与风险
|
||||
- 证据来源
|
||||
- 上下文包
|
||||
- 最近写入
|
||||
|
||||
不可变项：
|
||||
|
||||
- `项目记忆主视图` 与 `项目记忆写入结果态` 必须共享同一个项目壳、对象分类、状态标签和证据语义。
|
||||
- 写入结果态是项目记忆的状态页，不是另一套新功能。
|
||||
|
||||
### 6.7 项目切换器
|
||||
|
||||
功能定位：项目层内快速切换项目、暂存想法、草案和新建项目。
|
||||
|
||||
固定分组：
|
||||
|
||||
- 当前项目
|
||||
- 最近项目
|
||||
- 暂存想法
|
||||
- 草案箱
|
||||
- 新建项目
|
||||
- 搜索入口
|
||||
|
||||
不可变项：
|
||||
|
||||
- 不是团队空间切换器。
|
||||
- 切换项目不应中断 AI 正在推进的任务。
|
||||
|
||||
## 7. 共享组件真源
|
||||
|
||||
优先沉淀和复用这些组件：
|
||||
|
||||
```text
|
||||
PMFlowLogo / PMFlowBrand / PMFlowBrandHeader
|
||||
PMFlowShell
|
||||
PMFlowMobileShell
|
||||
StatusLabel
|
||||
AIOperationFeed
|
||||
EvidenceSnippet
|
||||
HumanDecisionBar
|
||||
ObjectChangeCard
|
||||
ProjectContextBar
|
||||
AICopilotPanel
|
||||
MobileBottomNav
|
||||
ProjectSwitcher
|
||||
ProjectMemoryBlock
|
||||
Toast
|
||||
InlineNotice
|
||||
PageBanner
|
||||
ConfirmDialog
|
||||
FormDialog
|
||||
MobileBottomSheet
|
||||
```
|
||||
|
||||
规则：
|
||||
|
||||
- 新功能优先复用这些组件，不重新发明状态标签、导航或 AI 操作流。
|
||||
- 如果需要新增组件，必须先判断能否作为共享组件沉淀。
|
||||
|
||||
## 8. 当前前端审计
|
||||
|
||||
### 8.1 已符合契约
|
||||
|
||||
- `frontend/src/features/project-launch/` 已具备本地状态机和 6 个桌面状态、3 个移动状态的基础结构。
|
||||
- `frontend/src/features/project-launch/types.ts` 已定义 `LaunchStage / LaunchInput / AIWorkStep / AIOperationItem / ProjectDraft` 等结构。
|
||||
- `frontend/src/features/personal-space/` 已覆盖继续推进、待我确认、AI 正在推进、暂存想法、草案箱和新建项目入口。
|
||||
- `frontend/src/features/pmflow-os/components/MobileBottomNav.tsx` 已收敛正式应用壳移动端底部导航，固定为 `空间 / 指挥台 / 待确认 / 动态 / 我的`，并按当前路由计算 active 状态。
|
||||
- `frontend/src/features/pmflow-os/components/FeedbackPrimitives.tsx` 已沉淀 `PageBanner / InlineNotice / HumanDecisionBar / ConfirmDialog / MobileBottomSheet`，用于页面级状态、局部提示、人类决策栏、高影响确认和移动端 bottom sheet。
|
||||
- `frontend/src/features/pmflow-os/types.ts` 已定义 `Thread / ChangeSet / ChangeItem / Evidence / Approval / Requirement / Decision / Task / Risk / ProjectTruthState` 等项目真相层对象。
|
||||
- `frontend/src/features/pmflow-os/components/chrome.tsx` 已沉淀 `PMFlowMark / PMFlowBrand / PMFlowBrandHeader / SurfacePill / ToneChip` 等部分基础视觉组件。
|
||||
- `frontend/src/features/pmflow-os/pages/ProjectMemoryPage.tsx` 与 `MemoryWritebackResultPage.tsx` 已分别具备项目记忆主视图和写入结果态雏形。
|
||||
|
||||
### 8.2 不一致与风险
|
||||
|
||||
- `ProjectMemoryPage.tsx` 的对象分类还不完整，缺少 `需求与范围 / 上下文包 / 最近写入` 的稳定分区。
|
||||
- `ProjectMemoryPage.tsx` 与 `MemoryWritebackResultPage.tsx` 共享语义不足，写入结果态更像独立结果页，后续需要在项目记忆契约下统一。
|
||||
- 状态标签存在多套实现：`statusPill / SurfacePill / ToneChip / StatusLabel`，应收敛为统一 `StatusLabel` 语义组件。
|
||||
- `AI 操作 / 用户动作 / 系统状态 / 待确认` 的视觉语法目前分散在页面代码里，缺少共享约束组件。
|
||||
- 提示、提醒和弹窗已有 PMFlow OS 产品域的初版共享组件层级，但旧后台、AI Steward 和部分历史页面仍未全面迁移；关键业务确认仍需持续避免落入 toast。
|
||||
|
||||
### 8.3 最小重构计划
|
||||
|
||||
第一步：不改页面结构，只修正一致性风险。
|
||||
|
||||
- 移动端底部导航已统一为 `空间 / 指挥台 / 待确认 / 动态 / 我的`。
|
||||
- `MobileBottomNav` 已抽出为共享组件，后续正式应用壳不得再重复实现底部导航。
|
||||
- `FeedbackPrimitives` 已抽出 PMFlow OS 反馈组件，新增页面级提示、内联提示、确认弹窗、移动端 bottom sheet 和人类决策栏时优先复用。
|
||||
- 统一状态标签命名和 tone。
|
||||
|
||||
第二步：统一项目记忆功能。
|
||||
|
||||
- 将 `ProjectMemoryPage` 明确为项目记忆主视图。
|
||||
- 将 `MemoryWritebackResultPage` 明确为项目记忆写入结果态。
|
||||
- 共享对象分类、证据组件、写入状态标签和右侧建议区规则。
|
||||
|
||||
第三步：统一项目层壳。
|
||||
|
||||
- `CommandCenter / StructuredExtraction / ChangeReview / ProjectMemory / MemoryWritebackResult` 必须复用同一个项目壳、顶部上下文和移动端导航。
|
||||
|
||||
### 8.4 优先共享组件清单
|
||||
|
||||
优先级 P0：
|
||||
|
||||
- `MobileBottomNav`
|
||||
- `StatusLabel`
|
||||
- `EvidenceSnippet`
|
||||
- `ObjectChangeCard`
|
||||
- `ProjectContextBar`
|
||||
- `InlineNotice`
|
||||
- `PageBanner`
|
||||
- `ConfirmDialog`
|
||||
|
||||
优先级 P1：
|
||||
|
||||
- `AIOperationFeed`
|
||||
- `HumanDecisionBar`
|
||||
- `MobileBottomSheet`
|
||||
- `FormDialog`
|
||||
- `AICopilotPanel`
|
||||
- `ProjectSwitcher`
|
||||
- `ProjectMemoryBlock`
|
||||
|
||||
## 9. 禁止项
|
||||
|
||||
- 禁止同一功能在不同线程或不同轮次重新画成另一套页面。
|
||||
- 禁止把状态页当成新功能页重新设计。
|
||||
- 禁止移动端底部导航漂移。
|
||||
- 禁止 AI 生成内容未经确认就显示为已确认事实。
|
||||
- 禁止为了追求“AI 感”引入紫色、深色、光效或营销页式装饰。
|
||||
- 禁止用 AI 生图作为最终实现真源。
|
||||
|
|
@ -17,13 +17,17 @@
|
|||
- `backend/.control_plane/pmflow-routing-rules.json`
|
||||
|
||||
## 3. 顶层库存
|
||||
- `docs/PMFLOW_PRODUCT_BLUEPRINT.md`：PMFlow 产品蓝图真源；锁定“对话驱动的 AI 产品执行操作系统”、`solo-first, team-ready`、项目真相层、ChangeSet 待确认、Execution Bridge 与人机混编团队方向
|
||||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`：PMFlow 产品推进执行标准；记录当前进度、Phase A-F 推进顺序、单次任务范围、Codex 并行推进协议、进度台账和新线程接续规则
|
||||
- `docs/PMFLOW_UI_CONTRACT.md`：PMFlow UI 契约真源；锁定 Logo、浅色白底 + `#2463EB`、移动端固定底部导航、四类视觉语法、核心功能 canonical 契约和当前前端一致性审计
|
||||
- `docs/INBOX_INLINE_OPS_3_PHASE_CHECKLIST.md`：消息台内联操作执行清单
|
||||
- `docs/architecture/MASTER_CONTRACT.md`：跨栈主契约
|
||||
- `docs/architecture/CODE_REFERENCE_INDEX.md`：新增代码参考入口与高频代码索引
|
||||
- `docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md`：PMFlow OS 产品合同真源；锁定前端 `ProjectTruthState / ChangeSet / Evidence / Approval / ExecutionContext` 与后端 `truth_nodes / tasks / semantic_facts / ai_project_control / dev_sync` 的复用边界；Phase C1 已实现 review 表和审查 API，commit 仍未实现
|
||||
- `docs/architecture/RUNTIME_GUARDRAILS.md`：运行边界、守门规则与已知运行假设
|
||||
- `docs/architecture/API_CONTRACTS.md`：接口/Schema 契约
|
||||
- `docs/architecture/DATAFLOW.md`：主链与数据流说明
|
||||
- `docs/architecture/TASK_BRIEF_TEMPLATE.md`：任务包模板
|
||||
- `docs/architecture/TASK_BRIEF_TEMPLATE.md`：并行安全任务包模板；用于声明 Packet 的 `base_ref / read_scope / write_scope / forbidden_paths / shared_files / verification / docs_to_sync`
|
||||
- `docs/superpowers/plans/`：实现计划
|
||||
- `docs/superpowers/specs/`：需求/方案规格
|
||||
- `docs/task_briefs/`：任务包产物与验收截图
|
||||
|
|
@ -36,6 +40,8 @@
|
|||
- `backend/app/api/feishu_api/`
|
||||
- `backend/app/api/rag_api/`
|
||||
- `backend/app/api/sstc_api/`
|
||||
- `backend/app/api/pmflow_launch_api/`
|
||||
- `backend/app/api/pmflow_os_api/`
|
||||
- `backend/app/api/signals_api/`
|
||||
- `backend/app/api/signal_sources_api/`
|
||||
- `backend/app/api/semantic_facts_api/`
|
||||
|
|
@ -86,6 +92,8 @@
|
|||
- `backend/app/utils/timezone.py`
|
||||
- `backend/app/utils/audited_write.py`
|
||||
- `backend/alembic/versions/`
|
||||
- `backend/app/main.py` 现已把模型连通性探测、飞书长连接、World Model 预热、调度器与后台队列消费收口为显式环境开关；开发环境可直接通过 `STARTUP_*` / `FEISHU_LONG_CONNECTION_ENABLED` 关闭重型副作用，避免热重载每次都付全量启动成本。
|
||||
- `backend/app/api/router.py` 现改为按模块路径动态注册路由；默认保持 `full`，并支持通过 `API_ROUTE_PROFILE` 与 `API_OPTIONAL_ROUTE_GROUPS` 在开发场景下裁掉重型 optional route group，减少 eager import 开销。
|
||||
|
||||
### 4.5 Mounted Runtime / 训练相关
|
||||
- `backend/app/models/reply_iteration.py`
|
||||
|
|
@ -94,6 +102,8 @@
|
|||
- `backend/app/models/query_route_memory.py`
|
||||
- `backend/app/models/semantic_fact.py`
|
||||
- `backend/app/models/semantic_fact_extraction_run.py`
|
||||
- `backend/app/models/pmflow_launch.py`
|
||||
- `backend/app/models/pmflow_change_review.py`
|
||||
- `backend/app/api/ai_steward_api/routes_reply_iteration.py`
|
||||
- `backend/app/api/ai_steward_api/routes_training_pipeline.py`
|
||||
- `backend/app/api/ai_steward_api/routes_mounted_ai.py`
|
||||
|
|
@ -159,6 +169,10 @@
|
|||
- `frontend/src/pages/knowledge-graph-context-board/`
|
||||
- `frontend/src/pages/semantic-facts-board/`
|
||||
- `frontend/src/pages/login/`
|
||||
- `frontend/src/components/login/`
|
||||
- `frontend/src/features/pmflow-os/pages/`
|
||||
- `frontend/src/features/pmflow-os/components/`
|
||||
- `frontend/src/features/personal-space/components/`
|
||||
- `frontend/src/pages/skill-tasks/`
|
||||
- `frontend/src/pages/skills/`
|
||||
- `frontend/src/pages/user-profile/`
|
||||
|
|
@ -169,11 +183,26 @@
|
|||
### 5.2 API 与共享模块
|
||||
- `frontend/src/api/aiPmo.ts`
|
||||
- `frontend/src/api/aiSteward.ts`
|
||||
- `frontend/src/components/marketing/`
|
||||
- `frontend/src/components/login/`
|
||||
- `frontend/src/components/layout/LazyBoundary.tsx`
|
||||
- `frontend/src/components/ai-steward/`
|
||||
- `frontend/src/components/ai-steward/QAConversationStatusBar.tsx`
|
||||
- `frontend/src/components/ai-steward/QAResponseMetaCard.tsx`
|
||||
- `frontend/src/components/ai-steward/QAResponseMetaCard.test.tsx`
|
||||
- AI Steward 问答浮窗现分三层显性化：`FloatingQAChat.tsx` 负责即时回答/历史回放归一化，`QAConversationStatusBar.tsx` 展示对象/来源/仓库/执行通道/plan handoff，`QAResponseMetaCard.tsx` 展示 `fit_brief / external_recommendation / recommended_next_step`，对应前端回归由 `FloatingQAChat.test.tsx` 与 `QAResponseMetaCard.test.tsx` 锁定。
|
||||
- 登录页与营销页仍共享 `frontend/src/components/marketing/` 的部分视觉基线；公开登录页现改由 `frontend/src/components/login/` 目录承载，其中 `LoginExperience.tsx` 负责登录壳层、`LoginWorkflowVisual.tsx` 负责左侧场景、`loginScene.ts` / `loginMath.ts` 拆出展示配置与路径几何、`login.css` 负责登录页专属样式边界，`frontend/src/pages/login/LoginPage.tsx` 继续负责真实鉴权、错误态和 redirect 提示；未登录访问 `/` 会经 `frontend/src/router/index.tsx` 直接重定向到 `/login`，无显式 `redirect` 的成功登录现在默认进入 `/command-center`。
|
||||
- 前端主包治理已切到“同步首屏最小集 + route/page-section lazy”模式：`frontend/src/router/index.tsx` 保留 `LoginPage / Layout` 这组同步入口，其余后台重页面通过 `React.lazy + Suspense` 懒加载；统一 fallback 在 `frontend/src/components/layout/LazyBoundary.tsx`。`frontend/src/features/personal-space/` 作为空间层入口，通过 `/space` 提供可直接打开的本地预览入口，承载继续推进、待我确认、AI 正在推进、暂存想法、草案箱与新建项目入口。`frontend/src/features/project-launch/` 作为首次进入页 / 新项目启动台产品域，通过 `/project-launch` 提供可直接打开的入口；Phase B 后默认调用真实 `pmflow-launch` draft/confirm API，创建成功态主动作跳转后端返回的 `/pmflow-os?projectId=<id>`，只有显式 `?demo=1` 或 `?dataSource=demo` 才启用本地 mock 状态机。`frontend/src/features/pmflow-os/` 作为新产品域，通过 `PMFlowOsProvider` 在应用根部挂载共享 truth store，并提供 `CommandCenter / ChangeReview / WorkGraph / ExecutionBridge / ReleaseGrowth / TeamLayer / ProjectMemory / Account` 主入口；当前 PMFlow OS 页面已切到专属轻壳，桌面端默认隐藏旧 TopBar，并由 `frontend/src/features/pmflow-os/components/PMFlowOsFrame.tsx` 统一承接“左侧稳定导航 + 顶部上下文条 + 中央视图 + 右侧 AI 副驾”的全局骨架，同时承接项目内 `个人空间 / 当前项目名` 面包屑和项目切换器；账号退出登录由 `frontend/src/features/pmflow-os/components/AccountControls.tsx` 统一承接桌面头像下拉、退出确认与移动端 bottom sheet，`frontend/src/features/pmflow-os/pages/AccountPage.tsx` 提供 `/me` 移动“我的”页；正式应用壳移动端底部导航统一由 `frontend/src/features/pmflow-os/components/MobileBottomNav.tsx` 承接；`/command-center` 额外提供免登录产品预览壳，`/pmflow-os` 是真实项目上下文 alias。主视觉按 `#2463EB + 白色` 的 Linear-like 高密度原型展开。`UsersPage` 把创建/删除/重置/导入/批量分配对话框拆为按需 chunk，`UserSkillsPage` 与 `WorkloadDetailPage` 的图表也分别拆到了 `frontend/src/pages/user-skills/components/UserSkillsRadarPanel.tsx` 与 `frontend/src/pages/workload-detail/components/WorkloadTrendChart.tsx`。
|
||||
- `frontend/src/features/personal-space/mockData.ts` 与 `PersonalSpacePage.tsx` 是空间首页本地真相和视图层；移动端为空间首页独立 App 布局，不直接压缩桌面卡片；`frontend/src/pages/PersonalSpacePage.tsx` 是薄入口。该域只表达个人空间，不做团队空间强切换、企业组织管理或传统项目列表后台。
|
||||
- `frontend/src/features/project-launch/types.ts`、`mockData.ts`、`useProjectLaunchState.ts` 是新项目启动台状态层；默认真实模式通过 `frontend/src/api/pmflowLaunch.ts` 生成草案并确认创建真实项目，API 失败进入明确失败态，不静默 fallback 成 mock 成功；`mockData.ts` 仅在显式 `?demo=1` 或 `?dataSource=demo` 下作为演示状态机使用。`components/LaunchShell.tsx` 负责桌面/移动分流，桌面端复用 `frontend/src/features/personal-space/components/SpaceChrome.tsx` 的空间左侧栏和顶部条，`LaunchCanvases.tsx` 和 `MobileLaunchLayout.tsx` 承接高保真图中的意图输入、AI 工作、人类确认、草案修改、生成失败、创建成功过渡与移动端 bottom sheet 交互。
|
||||
- `frontend/src/features/pmflow-os/store.tsx` 当前是 PMFlow OS 共享 truth store：`?projectId=<id>` 时通过 React Query 调用 `frontend/src/api/pmflowOs.ts` 读取真实 `GET /pmflow-os/projects/{project_id}/truth-state`，真实模式下项目内 message、`proposed_items` extraction、ChangeItem `accept/edit/defer` 均调用 `/pmflow-os` 后端并 refetch；只有显式 `?demo=1` 或 `?dataSource=demo` 时才启用本地 mock 演示状态机。真实读取/动作失败会进入错误/空态，不静默 fallback 成 mock 成功。
|
||||
- `frontend/src/features/pmflow-os/store.tsx` 仍保留演示用项目内 AI 结构化闭环状态机：`command_idle / ai_extracting / extraction_ready / review_open / writeback_success`。`frontend/src/features/pmflow-os/pages/StructuredExtractionPage.tsx` 是本轮结构化提取页，`ChangeReviewPage.tsx` 是决策与待确认中心，`MemoryWritebackResultPage.tsx` 是项目记忆写入结果页，`WorkGraphPage.tsx` 是项目工作台关系总览与对象投影视图，`ExecutionBridgePage.tsx` 是执行桥上下文包、PR/测试与回写状态页；A3 已接入后端 truth-state，C1 已接入真实 message/extraction/review 状态机，但仍不调用真实 AI 提取、不实现 commit、不把 mock 当真实失败 fallback。`ProjectMemoryPage.tsx` 在真实模式下展示后端 `truth_nodes + semantic_facts` 的 `projectMemory` 投影，accepted/edited ChangeItem 只留在 review 投影中，不进入 Project Memory。`frontend/src/features/pmflow-os/components/ProjectStructuredLoop.tsx` 提供 `StatusLabel / EvidenceSnippet / ObjectChangeCard / ProjectConversationPanel / StructuredExtractionPanel / ProjectAICopilotPanel` 等闭环组件，并复用契约化 `InlineNotice` 表达“未确认不得写入”的局部提示。
|
||||
- PMFlow OS 后端入口位于 `backend/app/api/pmflow_os_api/`，projection service 位于 `backend/app/services/pmflow_os_projection_service.py`，C1 审查状态机服务位于 `backend/app/services/pmflow_change_review_service.py`，Pydantic 合同位于 `backend/app/schemas/pmflow_os.py`；当前聚合 `truth_nodes / tasks / semantic_facts / ai_project_control / dev_sync`，`Thread / Message` 来自 `pmflow_threads / pmflow_thread_messages`，`ChangeSet / ChangeItem / Approval / EvidenceLink` 来自 `backend/app/models/pmflow_change_review.py` 对应真实表。C1 只实现 message、`proposed_items` extraction、ChangeSet detail、ChangeItem `accept/edit/defer`，不实现 commit，不写 `truth_nodes / tasks / semantic_facts`。
|
||||
- PMFlow Launch 后端 Phase B 创建链位于 `backend/app/api/pmflow_launch_api/`、`backend/app/services/pmflow_launch_service.py`、`backend/app/schemas/pmflow_launch.py` 与 `backend/app/models/pmflow_launch.py`；`POST /pmflow-launch/drafts` 只写 `pmflow_launch_drafts`，`POST /pmflow-launch/drafts/{draft_id}/confirm` 在同一事务内写 `projects / user_projects / pmflow_threads / pmflow_thread_messages / truth_nodes / tasks / semantic_facts seed / operation_logs`，并把 `launch_draft_id / thread_id / thread_message_id` 写入正式对象 metadata。
|
||||
- `frontend/src/features/pmflow-os/components/ChangeReviewGroup.tsx`、`WorkbenchPanel.tsx`、`ExecutionBridgeCards.tsx`、`PMFlowOsFrame.tsx`、`AccountControls.tsx`、`FeedbackPrimitives.tsx` 是高保真原型新增的行为组件层：分别承载变更 diff 审查块、工作台对象卡组、执行桥上下文/日志卡片、全局上下文条与 AI 副驾、账号菜单/退出登录确认交互，以及 `PageBanner / InlineNotice / HumanDecisionBar / ConfirmDialog / MobileBottomSheet` 这组提示、提醒、确认与移动端 bottom sheet 基础组件，避免再把这些业务片段内联塞回 `pages/`。
|
||||
- `frontend/vite.config.ts` 现补了固定 vendor chunk 分组（`framework / state-query / ui-radix / icons / charts / markdown`）与业务 chunk 分组（`ai-steward / sstc / governance`），目标是让登录页与基础导航不再背 AI Steward、SSTC、治理页和图表代码。
|
||||
- 旧登录残留 `frontend/src/components/ui/sign-in.tsx` 与 `frontend/src/components/ui/demo.tsx` 已删除，`frontend/src/components/login/` 成为唯一登录实现真源。
|
||||
- 前端开发链路已按职责拆分：`docker-compose.dev.yml` 下的 Vite 热更新开发前端固定占用 `5174`，静态生产预览前端默认改为 `5175`；`frontend/scripts/dev-entrypoint.sh` 避免每次容器启动都执行 `npm ci`，`frontend/scripts/login-live-check.mjs` 与 `package.json` 中的 `verify:login-fast / verify:login-responsive / verify:login-full`、`capture:login:matrix` 作为登录页快回路验证入口，截图产物统一落到 `frontend/output/login/`。
|
||||
- `frontend/src/api/taskBriefs.ts`
|
||||
- `frontend/src/api/modelRouting.ts`
|
||||
- `frontend/src/api/mcp.ts`
|
||||
|
|
@ -196,6 +225,7 @@
|
|||
- AI Steward 浮窗的“当前对象/来源模式/证据状态”必须直接消费 `/rag/ask` 与 QA session API 的显式 contract 字段，禁止在前端靠回答正文反推 internal/external 或 plan 状态。
|
||||
- 网页问答显式锚点 v1 只能消费稳定强锚点：项目页路径中的 `project_id` 与 URL query 中已显式存在的 `project_id/source_chat_id`；前端禁止自行猜测 `source_chat_id`。
|
||||
- `AI Config -> Governance Tools` 现新增 `/ai-config/mcp-config`、`/ai-config/query-route-governance` 与 `/ai-config/semantic-facts-board` 入口；三类治理页都只对 `BOSS/ADMIN` 开放。MCP 页负责模板化配置、后端直连/Local Bridge 状态展示、runtime probe、命令预览与本机确认；route/context 页负责 mismatch、clarify-heavy 与 negative feedback 样本排查；semantic facts 页负责 KPI、队列、对象表与详情抽屉。
|
||||
- PMFlow OS 原型页是前端独立产品域，不复用 `AI Steward` / `Project Board` 的旧信息架构；新页面只允许消费 `frontend/src/features/pmflow-os/store.tsx` 的共享状态和行为组件，避免把原型再拖回 SSTC/治理后台语义。个人空间首页与新项目启动台同样是独立产品域，只能分别消费 `frontend/src/features/personal-space/` 的本地 mock data 与 `frontend/src/features/project-launch/` 的本地状态机，禁止在首版中接后端、真实 AI 调用、真实项目创建 API、团队空间强切换或完整企业组织管理流程。
|
||||
|
||||
## 6. 工具与运行库存
|
||||
- `backend/scripts/repair_requirement_plan_history.py`
|
||||
|
|
@ -206,6 +236,9 @@
|
|||
- `frontend/playwright.config.ts`
|
||||
- `frontend/vitest.setup.ts`
|
||||
- `frontend/e2e/feishu-project-full-flow.spec.ts`
|
||||
- `frontend/scripts/dev-entrypoint.sh`
|
||||
- `frontend/scripts/login-live-check.mjs`
|
||||
- 前端到后端访问链路已收敛为同源 `/api`：开发环境由 Vite proxy 转发，生产环境由 nginx `/api` 反代；临时外网访问脚本与浏览器侧绝对 API base 配置已移除。
|
||||
|
||||
## 7. 维护建议
|
||||
- 想看“现在怎么跑、边界怎么定”：先看 `AGENTS.md`，再看 `CLAUDE.md`
|
||||
|
|
|
|||
|
|
@ -89,17 +89,41 @@
|
|||
- SSTC 负责人推荐接口：参考 `POST /projects/{project_id}/tasks/{task_id}/recommend-assignee`
|
||||
- SSTC 任务更新接口：参考 `PATCH /projects/{project_id}/tasks/{task_id}`
|
||||
- SSTC 发布创建接口：参考 `POST /projects/{project_id}/releases`
|
||||
- PMFlow OS 真实读路径与 C1 Change Review API：参考 `backend/app/api/pmflow_os_api/`、`backend/app/services/pmflow_os_projection_service.py`、`backend/app/services/pmflow_change_review_service.py`、`backend/app/schemas/pmflow_os.py`；只读提供 `GET /pmflow-os/projects/{project_id}/truth-state` 与 `GET /pmflow-os/projects/{project_id}/execution-summary`，复用 `truth_nodes / tasks / semantic_facts / ai_project_control / dev_sync`，并读取 `pmflow_threads / pmflow_thread_messages / pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`；C1 写 API 包括 thread message、`proposed_items` extraction、ChangeSet detail、ChangeItem `accept/edit/defer`，不实现 commit
|
||||
- Project Launch 真实创建链：参考 `backend/app/api/pmflow_launch_api/`、`backend/app/services/pmflow_launch_service.py`、`backend/app/schemas/pmflow_launch.py` 与模型 `backend/app/models/pmflow_launch.py`；接口为 `POST /pmflow-launch/drafts` 与 `POST /pmflow-launch/drafts/{draft_id}/confirm`，draft 只写 `pmflow_launch_drafts`，confirm 在同一事务内创建 `projects / user_projects / pmflow_threads / pmflow_thread_messages / truth_nodes / tasks / semantic_facts seed / operation_logs`
|
||||
- PMFlow Change Review 模型与 migration：参考 `backend/app/models/pmflow_change_review.py` 与 `backend/alembic/versions/20260426_add_pmflow_change_review_tables.py`；只包含 `pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`，本阶段不得新增或依赖 `/commit`
|
||||
|
||||
## 3. 前端参考
|
||||
- 新增前端 API 调用：参考 `frontend/src/api/sstc.ts`
|
||||
- PMFlow UI 契约真源：先读 `docs/PMFLOW_UI_CONTRACT.md`，再修改 `project-launch`、`personal-space`、`pmflow-os` 相关页面；该文档锁定 Logo、色彩、移动端底部导航、状态标签、AI 操作/用户动作/待确认视觉语法和核心功能 canonical 契约
|
||||
- PMFlow OS 产品合同真源：先读 `docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md`，再实现 `pmflow-os` 真实后端接入；该文档锁定 `ProjectTruthState / Thread / ChangeSet / ChangeItem / Evidence / Approval / Project Memory / ExecutionContext` 与 `truth_nodes / tasks / semantic_facts / ai_project_control / dev_sync` 的复用边界和后续 API 草案
|
||||
- 新增前端 API 调用：参考 `frontend/src/api/sstc.ts`；PMFlow OS 真实接入参考 `frontend/src/api/pmflowOs.ts` 的 `getPMFlowTruthState(projectId)`、`getPMFlowExecutionSummary(projectId)`、`createPMFlowThreadMessage`、`createPMFlowExtraction`、`getPMFlowChangeSet`、`acceptPMFlowChangeItem`、`editPMFlowChangeItem`、`deferPMFlowChangeItem`；Project Launch 创建链参考 `frontend/src/api/pmflowLaunch.ts` 的 `createPMFlowLaunchDraft` 与 `confirmPMFlowLaunchDraft`
|
||||
- AI Steward 页面入口：参考 `frontend/src/pages/ai-steward/`
|
||||
- AI Steward 问答浮窗与上下文显性化组件：参考 `frontend/src/components/ai-steward/FloatingQAChat.tsx`、`frontend/src/components/ai-steward/QAConversationStatusBar.tsx`、`frontend/src/components/ai-steward/QAResponseMetaCard.tsx`
|
||||
- AI Steward QA contract 前端类型（含 `analysis_packet`）：参考 `frontend/src/api/aiSteward.ts`
|
||||
- AI Steward handoff 元卡片回归：参考 `frontend/src/components/ai-steward/FloatingQAChat.test.tsx`、`frontend/src/components/ai-steward/QAResponseMetaCard.test.tsx`
|
||||
- AI Steward / QA session 前端 contract：参考 `frontend/src/api/aiSteward.ts`
|
||||
- PMFlow OS 前端 MVP 产品域：参考 `frontend/src/features/pmflow-os/`
|
||||
- 个人空间首页 / 空间层入口前端产品域：参考 `frontend/src/features/personal-space/` 与薄入口 `frontend/src/pages/PersonalSpacePage.tsx`；本地预览路由入口为 `/space`，覆盖继续推进、待我确认、AI 正在推进、暂存想法、草案箱与新建项目入口；空间层共享左侧栏、顶部条与空间用量组件在 `frontend/src/features/personal-space/components/SpaceChrome.tsx`，`/project-launch` 桌面首次新建壳也复用该组件
|
||||
- 新项目启动台 / 首次进入页前端产品域：参考 `frontend/src/features/project-launch/` 与薄入口 `frontend/src/pages/ProjectLaunchPage.tsx`；真实模式默认通过 `frontend/src/api/pmflowLaunch.ts` 调用后端 draft/confirm API，只有显式 `?demo=1` 或 `?dataSource=demo` 才启用 `mockData.ts` 本地演示状态机；本地预览路由入口为 `/project-launch`
|
||||
- PMFlow OS 共享 truth store 与主链状态动作：参考 `frontend/src/features/pmflow-os/store.tsx`；当前支持 `?projectId=<id>` 走 React Query 读取真实 `truth-state`，真实模式下 thread message、`proposed_items` extraction、ChangeItem `accept/edit/defer` 调后端并 refetch，不本地 promote 入 Project Memory；`?demo=1` 才启用本地 mock 演示状态机和本地动作；项目内 AI 结构化闭环状态机为 `command_idle / ai_extracting / extraction_ready / review_open / writeback_success`
|
||||
- PMFlow OS 产品页入口：参考 `frontend/src/features/pmflow-os/pages/CommandCenterPage.tsx`、`StructuredExtractionPage.tsx`、`ChangeReviewPage.tsx`、`MemoryWritebackResultPage.tsx`、`WorkGraphPage.tsx`、`ExecutionBridgePage.tsx`、`ReleaseGrowthPage.tsx`、`TeamLayerPage.tsx`、`ProjectMemoryPage.tsx`、`AccountPage.tsx`
|
||||
- PMFlow OS 行为组件：参考 `frontend/src/features/pmflow-os/components/ProjectStructuredLoop.tsx`、`ProjectStageRail.tsx`、`ThreadComposer.tsx`、`ExtractionRail.tsx`、`ChangeGroupPanel.tsx`、`ObjectGraphSection.tsx`、`ContextPacketPanel.tsx`、`ExecutionTimeline.tsx`、`ReleaseGatePanel.tsx`、`TeamFeedPanel.tsx`、`ChangeReviewGroup.tsx`、`WorkbenchPanel.tsx`、`ExecutionBridgeCards.tsx`、`PMFlowOsFrame.tsx`、`AccountControls.tsx`、`FeedbackPrimitives.tsx`、`MobileBottomNav.tsx`；其中 `ProjectStructuredLoop.tsx` 承接 `StatusLabel / EvidenceSnippet / ObjectChangeCard / ProjectConversationPanel / StructuredExtractionPanel / ProjectAICopilotPanel`，`PMFlowOsFrame.tsx` 承接项目内面包屑和项目切换器，`AccountControls.tsx` 承接桌面头像菜单、退出登录确认与移动端 bottom sheet，`FeedbackPrimitives.tsx` 承接 `PageBanner / InlineNotice / HumanDecisionBar / ConfirmDialog / MobileBottomSheet`，`MobileBottomNav.tsx` 承接正式应用壳移动端固定底部导航
|
||||
- PMFlow OS 原型状态回归测试：参考 `frontend/src/features/pmflow-os/store.test.ts`；真实 API 动作回归参考 `frontend/src/features/pmflow-os/store.api.test.tsx`
|
||||
- Project Launch 真实/演示分支回归测试：参考 `frontend/src/features/project-launch/useProjectLaunchState.test.ts`
|
||||
- 网页问答显式锚点与 AI Steward URL 构造：参考 `frontend/src/components/ai-steward/qaPageAnchor.ts`
|
||||
- Inbox 页面入口：参考 `frontend/src/pages/inbox/`
|
||||
- Inbox `plan_mode` 展开卡片与映射：参考 `frontend/src/components/inbox/InboxListItem.tsx`、`frontend/src/lib/inbox.ts`、`frontend/src/api/aiPmo.ts`
|
||||
- 登录页/营销页的共享视觉基线：参考 `frontend/src/components/marketing/MarketingFrame.tsx` 与 `frontend/src/components/marketing/MarketingVisuals.tsx`
|
||||
- 公开登录页入口：参考 `frontend/src/pages/login/LoginPage.tsx`、`frontend/src/components/login/LoginExperience.tsx`、`frontend/src/components/login/LoginWorkflowVisual.tsx`、`frontend/src/components/login/loginScene.ts`、`frontend/src/components/login/loginMath.ts` 与 `frontend/src/router/index.tsx`
|
||||
- 登录页分级验证：参考 `frontend/package.json` 中的 `verify:login-fast / verify:login-responsive / verify:login-full`、`capture:login:matrix`、`frontend/scripts/login-live-check.mjs` 与 `frontend/src/pages/login/LoginPage.test.tsx`
|
||||
- 顶层路由懒加载与统一 fallback：参考 `frontend/src/router/index.tsx` 与 `frontend/src/components/layout/LazyBoundary.tsx`
|
||||
- 顶层前端 Provider 入口：参考 `frontend/src/main.tsx`（`PMFlowOsProvider` + `RouterProvider`）
|
||||
- AI Steward tab 级懒加载入口：参考 `frontend/src/pages/ai-steward/AIStewardPage.tsx`
|
||||
- AI Config section 级懒加载入口：参考 `frontend/src/pages/ai-config/AIConfigPage.tsx`
|
||||
- 项目看板控制面/对话框懒加载入口：参考 `frontend/src/pages/project-board/ProjectBoardPage.tsx`
|
||||
- 用户页对话框懒加载入口：参考 `frontend/src/pages/users/UsersPage.tsx`
|
||||
- 图表二级 chunk 入口：参考 `frontend/src/pages/user-skills/components/UserSkillsRadarPanel.tsx` 与 `frontend/src/pages/workload-detail/components/WorkloadTrendChart.tsx`
|
||||
- Vite chunk 分组与 watch 忽略策略：参考 `frontend/vite.config.ts`
|
||||
- Scheduler Center / Mounted AI Console：参考 `frontend/src/pages/scheduler-center/`
|
||||
- SSTC 工作流组件：参考 `frontend/src/components/sstc/`
|
||||
- Model Routing 页面：参考 `frontend/src/pages/model-routing-config/`
|
||||
|
|
@ -119,6 +143,7 @@
|
|||
- Prompt registry：`backend/app/config/ai_prompt_registry.py`
|
||||
- External Query Planner Prompt：`backend/app/config/ai_prompts.py` 中的 `PROMPT_EXTERNAL_QUERY_PLAN`
|
||||
- External Answer Presenter Prompts：`backend/app/config/ai_prompts.py` 中的 `PROMPT_EXTERNAL_DIRECT_FACT_QA`、`PROMPT_EXTERNAL_SUMMARY_WITH_SOURCES_QA`、`PROMPT_EXTERNAL_COMPARE_WITH_SOURCES_QA`
|
||||
- 开发轻启动配置：参考 `backend/app/core/config.py`、`backend/app/main.py`、`backend/app/api/router.py` 与 `docker-compose.dev.yml`
|
||||
|
||||
## 5. 维护建议
|
||||
- 新增接口时：先更新本文档，再同步 `API_CONTRACTS.md`
|
||||
|
|
|
|||
|
|
@ -0,0 +1,353 @@
|
|||
# PMFlow OS Product Contract
|
||||
|
||||
版本日期：2026-04-26
|
||||
|
||||
本文档是 PMFlow OS 从本地高保真主链走向真实数据闭环的产品级合同。它锁定对象真源、读写边界、状态流转和后续开发接口，避免 `frontend/src/features/pmflow-os/` 继续围绕 mock store 扩散。A3 已完成真实只读 projection，Phase B 已完成 Project Launch 创建链，Phase C1 已完成 Change Review 数据底座与审查状态机；ChangeSet commit 入库仍未实现。
|
||||
|
||||
产品方向真源仍以 `docs/PMFLOW_PRODUCT_BLUEPRINT.md` 为准；UI 行为与状态标签以 `docs/PMFLOW_UI_CONTRACT.md` 为准；推进节奏以 `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md` 为准。
|
||||
|
||||
## 1. 合同结论
|
||||
|
||||
PMFlow OS V1 的主链是：
|
||||
|
||||
```text
|
||||
Project Thread
|
||||
-> Structured Extraction
|
||||
-> ChangeSet Review
|
||||
-> Project Memory / Work Graph commit
|
||||
-> Execution Bridge
|
||||
-> Release / Growth feedback
|
||||
```
|
||||
|
||||
当前复用边界：
|
||||
|
||||
- `Requirement / Decision / Risk / Release` 优先从 `truth_nodes` 投影，不新建另一套正式业务对象表。
|
||||
- `Task` 复用 `tasks`，并通过 `truth_node_id` 绑定需求/宪章/项目真相节点。
|
||||
- `Project Memory` 由 `truth_nodes + semantic_facts` 聚合投影；`semantic_facts` 是 read model，不是人工确认记录本身。
|
||||
- `ModelDecision / PromptPackage / ReleaseValidation / Feedback / Revenue / ROI / Compliance` 复用 `ai_project_control` 模型与 `sstc_api/model_control.py` 现有接口。
|
||||
- `ExecutionContext` 复用 `prompt_packages + repo_bindings + task_code_links + progress_events + dev_sync summary`。
|
||||
- `Thread / ThreadMessage` 已由 Phase B 落到 `pmflow_threads / pmflow_thread_messages`。
|
||||
- `ChangeSet / ChangeItem / Approval / EvidenceLink` 已由 Phase C1 落到 `pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`。
|
||||
|
||||
PMFlow OS 专属表：
|
||||
|
||||
```text
|
||||
pmflow_threads
|
||||
pmflow_thread_messages
|
||||
pmflow_change_sets
|
||||
pmflow_change_items
|
||||
pmflow_approvals
|
||||
pmflow_evidence_links
|
||||
```
|
||||
|
||||
当前仍未实现 `/commit`，因此 accepted/edited ChangeItem 不得被投影成 confirmed Project Memory。
|
||||
|
||||
## 2. 对象映射表
|
||||
|
||||
| 前端对象 | 后端来源 | 是否新增表 | 读 API | 写 API | 状态流转 | 证据/审计 | 风险点 |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| `ProjectTruthState` | 聚合投影：`projects`、`truth_nodes`、`tasks`、`semantic_facts`、PMFlow OS 专属 review 表、`ai_project_control`、`dev_sync` | 不直接建总表 | `GET /pmflow-os/projects/{project_id}/truth-state` | 由各子对象 API 写入 | `loopStage` 由最近线程、提取和审查状态计算 | 返回 customer-safe 状态，不暴露内部 raw label | 需要 projection service，不能由前端拼多个旧接口冒充 |
|
||||
| `Thread` | `pmflow_threads`；绑定 `project_id`、默认目标、当前阶段 | 是，Phase B 已建 | `truth-state` 内返回 | 创建项目时初始化，或 C1 `messages` 首次写入时懒创建 | `idle -> loading -> ready` 仅表示提取状态 | 线程本身是后续 ChangeSet 证据源 | 不能复用飞书 thread/session 作为唯一项目线程 |
|
||||
| `Message` | `pmflow_thread_messages`；可引用 Feishu/QA/message 来源 | 是，Phase B 已建 | `truth-state` 内返回 | `POST /pmflow-os/projects/{project_id}/threads/{thread_id}/messages` | C1 先写 `sent`，后续可扩 `analyzing/resolved/failed` | message id 可被 `EvidenceLink` 引用 | 写 message 不等于写项目真相层 |
|
||||
| `ChangeSet` | `pmflow_change_sets` | 是，Phase C1 已建 | `GET /pmflow-os/projects/{project_id}/change-sets/{change_set_id}` | `POST /pmflow-os/projects/{project_id}/extractions` 生成；C2 才实现 `commit` | C1：`open -> reviewed`；C2：`committed / partially_committed` | 记录生成来源、routing_meta、LLM call id、actor | 不能用 `truth_nodes` 直接模拟 ChangeSet；ChangeSet 是待确认变更包 |
|
||||
| `ChangeItem` | `pmflow_change_items` | 是，Phase C1 已建 | ChangeSet detail | C1：`accept / edit / defer`；C2：`commit` 后写正式对象 | C1：`pending_review -> accepted / edited / deferred`；C2：`committed / skipped` | 每项必须绑定 evidence ids 与 risk level | `accept` 只改审查状态，不得静默落库 |
|
||||
| `Evidence` | `pmflow_evidence_links` 投影，来源可为 message、truth_node、task、progress_event、release_validation、feedback、metric | 是，Phase C1 已建 link 表 | `truth-state`、ChangeSet detail | C1 随 extraction 创建 thread message evidence；C2 随 commit、execution/growth 回写扩展 | 证据不走业务状态，只可 active/archived | 必须记录 `source_type/source_id/excerpt/display_label` | `ai_project_control.EvidencePack` 只适合发布/合规证据包，不能替代通用证据链 |
|
||||
| `Approval` | `pmflow_approvals` | 是，Phase C1 已建 | `truth-state`、ChangeSet detail | C1：`accept / edit / defer` 写入；C2：commit gate 扩展 | `approved / edited / deferred / rejected` | 记录 actor、role、decision、before/after | 高风险变更必须有 approval 记录；C1 只记录，C2 才强制 gate |
|
||||
| `Requirement` | `truth_nodes.node_type in ('charter','requirement')` 投影；V1 可从 charter content 中拆分 requirement block | 否 | `truth-state` | `commit` accepted ChangeItem 后创建/更新 `truth_nodes` | `draft/proposed -> confirmed -> archived`，前端映射到 `draft/confirmed/done` | commit 时绑定 ChangeItem/EvidenceLink；semantic facts hook 后台抽取 | 当前 `TruthNode.node_type` 历史值不统一，需在 projection 层做白名单映射 |
|
||||
| `Decision` | `truth_nodes.node_type='decision'` 或 charter/review content 决策块投影 | 否 | `truth-state` | `commit` 写 `truth_nodes` | `draft/proposed -> confirmed` | 必须保留来源 ChangeItem 和 owner | 若历史没有 decision node，先从 charter content 投影，不新增前端-only 决策 |
|
||||
| `Task` | `tasks` + `truth_nodes` | 否 | `truth-state`；后续可复用 SSTC task board | `commit` 创建/更新 `tasks`；执行进度走 dev-sync | `draft -> in_progress -> blocked/done` | 任务来源 ChangeItem、验收标准、assignee 建议进入审计 | `tasks.status` 与前端状态枚举需 projection 映射 |
|
||||
| `Risk` | `truth_nodes.node_type='risk'` 或 charter/release/check content 风险块投影 | 否 | `truth-state` | `commit` 写 `truth_nodes` | `draft/proposed -> confirmed -> archived` | 高风险必须绑定 approval 与 mitigation | `ReleaseValidationRun.risk_items` 是发布检查结果，不等于正式风险对象 |
|
||||
| `ModelDecision` | `project_model_bindings`、`model_recommendation_snapshots`、`model_eval_runs` 投影 | 否 | `truth-state` 可聚合；细节复用 `/projects/{project_id}/model-recommendations`、`/model-usage` | `/model-binding` | `recommended -> active -> archived` 映射到前端 `confirmed/released` | selection_reason、snapshot_input、eval summary 作为证据 | 不做独立模型市场页，必须嵌入项目主链 |
|
||||
| `TestRun` | `model_eval_runs`、`release_validation_runs`、`progress_events(event_type=test*)` 投影 | 否 | `truth-state`、`execution-summary` | dev-sync progress event 或 release validation | `pending/running -> passed/failed/blocked` | 测试日志和 PR/commit 可作为 evidence | 当前没有通用 test_runs 表，V1 先按投影聚合 |
|
||||
| `Release` | `truth_nodes.node_type='release'` + `release_validation_runs` | 否 | `truth-state`；SSTC release APIs | SSTC release 创建；`run_release_validation` | `check_pending -> ready -> shipping -> live/watch` | release gate、rollback_plan、validation_summary | 发布对象和发布验证结果需要在 projection 中分清 |
|
||||
| `MetricSignal` | `feedback_ingests.metrics`、`revenue_events`、`roi_snapshots`、增长埋点结果投影 | 否 | `truth-state`；`/roi-snapshots` | `feedback-ingest`、`revenue-events` | `draft/proposed -> confirmed` | 指标来源和采样窗口必须展示 | 只做轻量反馈，不引入完整财务系统 |
|
||||
| `ExecutionContext` | `prompt_packages`、`repo_bindings`、`task_code_links`、`progress_events`、`dev_sessions` | 否 | `GET /pmflow-os/projects/{project_id}/execution-summary` 聚合 `GET /projects/{project_id}/dev-sync/summary` | `createPromptPackage`、`bindGithubRepo`、`createProgressEvent` | `queued -> pushed -> coding -> pr_open -> testing -> synced/failed` | progress events、deliveries、repo/PR/commit 是执行证据 | 不得重造 dev-sync；PMFlow OS 只做项目内执行投影 |
|
||||
| `TeamFeed / TeamInbox` | `pmflow_change_sets`、`pmflow_approvals`、`progress_events`、release/feedback 事件聚合 | 暂不新增专表，先 projection | `truth-state` | 由各业务动作写入源表 | feed item 不承载主状态 | 必须能追溯到源对象 | Phase F 才补 Role Inbox/Decision Desk 的真实模型 |
|
||||
|
||||
## 3. ProjectTruthState 后端投影
|
||||
|
||||
`GET /pmflow-os/projects/{project_id}/truth-state` 返回前端兼容结构，但数据必须由后端 projection service 组装：
|
||||
|
||||
```text
|
||||
project:
|
||||
projects + latest confirmed truth_nodes
|
||||
thread/messages:
|
||||
pmflow_threads + pmflow_thread_messages
|
||||
changeSets/changeItems/evidence/approvals:
|
||||
PMFlow OS 专属 review 表
|
||||
requirements/decisions/risks/releases:
|
||||
truth_nodes 投影
|
||||
tasks:
|
||||
tasks + related truth_nodes
|
||||
modelDecisions:
|
||||
model_recommendation_snapshots + project_model_bindings + model_eval_runs
|
||||
testRuns:
|
||||
release_validation_runs + model_eval_runs + progress_events(test)
|
||||
metricSignals:
|
||||
feedback_ingests + revenue_events + roi_snapshots
|
||||
feed/teamInbox:
|
||||
review/actions/progress/release/growth 事件聚合
|
||||
execution:
|
||||
dev-sync summary + prompt_packages + recent progress_events
|
||||
```
|
||||
|
||||
投影规则：
|
||||
|
||||
- `AI 已生成` 对应 `ChangeSet.open` 和 `ChangeItem.pending_review`，不得进入正式对象列表。
|
||||
- `待你确认` 对应 `ChangeItem.pending_review` 或高风险 `Approval.requested`。
|
||||
- `已确认` 对应 `ChangeItem.accepted/edited`，但尚未必然写入 Project Memory。
|
||||
- `已写入项目记忆` 只能在 `ChangeSet.commit` 成功写入 `truth_nodes / tasks / semantic_facts` 后出现。
|
||||
- `semantic_facts` 只用于 read-side facts-first 查询与 Project Memory projection，不作为人工确认动作记录。
|
||||
|
||||
## 4. API 合同草案
|
||||
|
||||
所有接口统一返回：
|
||||
|
||||
```json
|
||||
{ "code": 0, "message": "success", "data": {} }
|
||||
```
|
||||
|
||||
错误仍走项目现有失败包络与 HTTP 状态；客户可见错误必须明确失败原因，不得用 mock 或默认句冒充成功。
|
||||
|
||||
### 4.1 获取项目真相投影
|
||||
|
||||
```text
|
||||
GET /pmflow-os/projects/{project_id}/truth-state
|
||||
```
|
||||
|
||||
Response `data`：
|
||||
|
||||
```json
|
||||
{
|
||||
"loopStage": "extraction_ready",
|
||||
"lastWritebackAt": "2026-04-25T10:00:00+08:00",
|
||||
"project": {},
|
||||
"thread": {},
|
||||
"messages": [],
|
||||
"changeSets": [],
|
||||
"changeItems": [],
|
||||
"evidence": [],
|
||||
"requirements": [],
|
||||
"decisions": [],
|
||||
"tasks": [],
|
||||
"risks": [],
|
||||
"modelDecisions": [],
|
||||
"testRuns": [],
|
||||
"releases": [],
|
||||
"metricSignals": [],
|
||||
"approvals": [],
|
||||
"feed": [],
|
||||
"teamInbox": {},
|
||||
"activeChangeSetId": null,
|
||||
"selectedTaskId": null,
|
||||
"execution": {}
|
||||
}
|
||||
```
|
||||
|
||||
失败语义：
|
||||
|
||||
- `404 project_not_found`：项目不存在或不属于当前租户。
|
||||
- `403 forbidden`：当前用户不是项目成员或管理角色。
|
||||
- `409 projection_incomplete`：核心合同对象缺失，不能拼装可信 ProjectTruthState。
|
||||
|
||||
### 4.2 写入线程消息
|
||||
|
||||
```text
|
||||
POST /pmflow-os/projects/{project_id}/threads/{thread_id}/messages
|
||||
```
|
||||
|
||||
Request：
|
||||
|
||||
```json
|
||||
{
|
||||
"content": "用户输入",
|
||||
"source": "web",
|
||||
"attachments": []
|
||||
}
|
||||
```
|
||||
|
||||
行为：
|
||||
|
||||
- 只写 `pmflow_thread_messages`。
|
||||
- 可触发异步 extraction job，但不能直接写 `truth_nodes / tasks`。
|
||||
- 返回 message 和可选 `extraction_job_id`。
|
||||
|
||||
### 4.3 创建结构化提取
|
||||
|
||||
```text
|
||||
POST /pmflow-os/projects/{project_id}/extractions
|
||||
```
|
||||
|
||||
Request：
|
||||
|
||||
```json
|
||||
{
|
||||
"thread_id": "thread_123",
|
||||
"message_id": "msg_123",
|
||||
"scope": "latest_message",
|
||||
"proposed_items": [
|
||||
{
|
||||
"group": "new_object",
|
||||
"object_type": "Requirement",
|
||||
"title": "待审变更标题",
|
||||
"summary": "待审变更摘要",
|
||||
"payload": {},
|
||||
"confidence": 0.82,
|
||||
"risk_level": "medium"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
行为：
|
||||
|
||||
- C1 采用 `proposed_items` 最小闭环，不默认调用 LLM；后续 AI 结构化提取应在上游生成 proposed items 后调用该接口。
|
||||
- 生成 `pmflow_change_sets` 与 `pmflow_change_items`。
|
||||
- ChangeSet 默认 `open`，ChangeItem 默认 `pending_review`。
|
||||
- 生成 `pmflow_evidence_links`，至少绑定触发消息。
|
||||
- 不写 `truth_nodes / tasks / semantic_facts`。
|
||||
|
||||
失败语义：
|
||||
|
||||
- `422 invalid_proposed_items`：未提供可审查 proposed items，不生成 ChangeSet。
|
||||
- `404 message_not_found`：message 不属于当前 tenant/project/thread。
|
||||
|
||||
### 4.4 获取 ChangeSet
|
||||
|
||||
```text
|
||||
GET /pmflow-os/projects/{project_id}/change-sets/{change_set_id}
|
||||
```
|
||||
|
||||
Response `data`：
|
||||
|
||||
```json
|
||||
{
|
||||
"changeSet": {},
|
||||
"items": [],
|
||||
"evidence": [],
|
||||
"approvals": []
|
||||
}
|
||||
```
|
||||
|
||||
### 4.5 审查 ChangeItem
|
||||
|
||||
```text
|
||||
POST /pmflow-os/change-items/{change_item_id}/accept
|
||||
POST /pmflow-os/change-items/{change_item_id}/edit
|
||||
POST /pmflow-os/change-items/{change_item_id}/defer
|
||||
```
|
||||
|
||||
`edit` Request：
|
||||
|
||||
```json
|
||||
{
|
||||
"summary": "修改后的摘要",
|
||||
"diff": "修改后的业务 diff",
|
||||
"payload_patch": {}
|
||||
}
|
||||
```
|
||||
|
||||
行为：
|
||||
|
||||
- `accept`：仅将 ChangeItem 置为 `accepted`，写 `pmflow_approvals`，不写正式对象。
|
||||
- `edit`：保存人工修改后的 payload，状态为 `edited`，写 `pmflow_approvals`。
|
||||
- `defer`：状态为 `deferred`，不进入项目真相层，但保留审计。
|
||||
|
||||
失败语义：
|
||||
|
||||
- `409 changeset_not_open`：ChangeSet 非 open，不能继续审查。
|
||||
- `409 item_already_reviewed`：ChangeItem 已被接受、编辑、暂缓、提交或跳过，不重复写 approval。
|
||||
- `422 invalid_change_payload`：修改后的 payload 不满足对象合同。
|
||||
|
||||
### 4.6 提交 ChangeSet
|
||||
|
||||
Phase C1 尚未实现该接口；以下是 Phase C2 合同草案。
|
||||
|
||||
```text
|
||||
POST /pmflow-os/change-sets/{change_set_id}/commit
|
||||
```
|
||||
|
||||
行为：
|
||||
|
||||
- 只处理 `accepted / edited` 的 ChangeItem。
|
||||
- 按 `objectType` 写入正式对象：
|
||||
- `Requirement / Decision / Risk / Release` -> `truth_nodes`
|
||||
- `Task` -> `tasks` + 关联 `truth_nodes`
|
||||
- `ModelDecision` -> `project_model_bindings` 或绑定选择记录
|
||||
- `MetricSignal` -> 反馈/收入/ROI 相关记录，或生成下一轮 recommendation 草案
|
||||
- 创建或更新 `pmflow_evidence_links`。
|
||||
- 提交成功后触发 semantic facts 抽取/刷新。
|
||||
- ChangeSet 进入 `committed` 或 `partially_committed`。
|
||||
|
||||
失败语义：
|
||||
|
||||
- `409 no_accepted_items`：没有可提交项。
|
||||
- `409 high_risk_approval_required`：高风险项缺少 required approval。
|
||||
- `500 commit_partial_failed`：部分项写入失败，必须返回成功/失败 item 明细，不得全部冒充成功。
|
||||
|
||||
### 4.7 获取执行桥摘要
|
||||
|
||||
```text
|
||||
GET /pmflow-os/projects/{project_id}/execution-summary
|
||||
```
|
||||
|
||||
行为：
|
||||
|
||||
- 优先调用或复用 `GET /projects/{project_id}/dev-sync/summary`。
|
||||
- 额外补齐最近 Prompt Package、活动 repo、PR/commit/test progress event。
|
||||
- 返回前端 `ExecutionContext` 兼容结构与详细 dev task 列表。
|
||||
|
||||
## 5. ChangeSet 写入正式对象规则
|
||||
|
||||
`ChangeItem.objectType` 的提交规则：
|
||||
|
||||
| objectType | 正式写入目标 | 必填字段 | 写入后前端状态 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Requirement` | `truth_nodes(node_type='requirement')` 或 charter content requirement block | `title`、`summary`、`stage`、证据 | `confirmed` |
|
||||
| `Decision` | `truth_nodes(node_type='decision')` | `title`、`summary`、`owner`、证据 | `confirmed` |
|
||||
| `Task` | `tasks`，必要时创建关联 `truth_nodes` | `title`、`description/summary`、`priority`、`acceptanceCriteria` | `draft` 或 `in_progress` |
|
||||
| `Risk` | `truth_nodes(node_type='risk')` | `title`、`summary`、`riskLevel`、`mitigation`、证据 | `confirmed` |
|
||||
| `ModelDecision` | `project_model_bindings` 或 `model_recommendation_snapshots` 引用 | `catalog_item_id` 或推荐快照引用 | `confirmed` |
|
||||
| `Release` | `truth_nodes(node_type='release')` + release validation 引用 | `title`、`summary`、gate items | `check_pending/ready` |
|
||||
| `MetricSignal` | `feedback_ingests`、`revenue_events`、`roi_snapshots` 投影或 recommendation 草案 | source、value、window | `confirmed` |
|
||||
|
||||
禁止规则：
|
||||
|
||||
- 禁止 `accept` 时直接写正式对象。
|
||||
- 禁止没有 evidence 的高风险项进入 `commit`。
|
||||
- 禁止把 AI 生成内容直接投影为 `Project Memory` confirmed facts。
|
||||
- 禁止让前端用本地 `promoteAcceptedToGraph` 代替后端 commit。
|
||||
|
||||
## 6. Execution Bridge 复用合同
|
||||
|
||||
PMFlow OS 不重造开发执行系统。执行桥复用：
|
||||
|
||||
- `PromptPackage`：开发上下文包，创建接口为 `POST /projects/{project_id}/charters/{charter_id}/prompt-packages`。
|
||||
- `RepoBinding / GitHubAppInstallation / GitHubAppRepository`：仓库与 GitHub App 授权状态。
|
||||
- `TaskCodeLink`：任务与 branch/PR/commit 绑定。
|
||||
- `ProgressEvent`：commit、PR、test、manual progress 的统一回写事件。
|
||||
- `DevSession`：开发活跃会话。
|
||||
- `GET /projects/{project_id}/dev-sync/summary`：当前执行桥最小真实读路径。
|
||||
|
||||
`ExecutionContext` 字段映射：
|
||||
|
||||
| 前端字段 | 后端来源 |
|
||||
| --- | --- |
|
||||
| `taskId` | active dev task id |
|
||||
| `status` | `ProgressEvent.derived_task_status` + `Task.status` projection |
|
||||
| `prompt` | latest `PromptPackage.package_text` |
|
||||
| `commitLog` | recent `ProgressEvent.summary` / payload commit fields |
|
||||
| `prStatus` | `TaskCodeLink.pr_number` + progress event |
|
||||
| `testSummary` | test progress event / release validation summary |
|
||||
| `writebackStatus` | latest progress event workflow state |
|
||||
|
||||
## 7. 后续实施顺序
|
||||
|
||||
1. A3 最小真实读路径：已实现 `pmflow_os_api` read-only projection，提供 `truth-state` 与 `execution-summary`。
|
||||
2. Phase B：已把 `/project-launch` 的草案确认接入真实项目创建和初始 Project Memory 写入。
|
||||
3. Phase C1：已实现 ChangeSet/ChangeItem/Approval/EvidenceLink 表与 `accept / edit / defer` 审查 API。
|
||||
4. Phase C2：下一步实现 ChangeSet commit，把 `accepted / edited` 写入 `truth_nodes / tasks / semantic_facts` 并补齐高风险 approval gate。
|
||||
5. Phase D：把 `ExecutionBridgePage` 切到 `execution-summary` 和 dev-sync 真实数据。
|
||||
6. Phase E：把 Release/Growth 投影接入 release validation、feedback、revenue、ROI、compliance。
|
||||
|
||||
本文档若与后续实现不一致，必须先更新合同再改代码。
|
||||
|
|
@ -63,6 +63,9 @@
|
|||
- `response_contract`
|
||||
- `fallback_policy`
|
||||
- `execution_mode`
|
||||
- 开发环境启动必须允许显式关闭重型副作用：`STARTUP_MODEL_PROBE_ENABLED`、`FEISHU_LONG_CONNECTION_ENABLED`、`STARTUP_WORLD_MODEL_WARMUP_ENABLED`、`STARTUP_SCHEDULERS_ENABLED`、`STARTUP_BACKGROUND_WORKERS_ENABLED` 是当前唯一允许的 startup 开关；需要压缩热重载时，应优先通过这些环境变量降载，而不是在代码里硬删启动逻辑或把副作用偷偷移到 import side effect。
|
||||
- `backend/app/api/router.py` 的 optional route group 只能通过 `API_ROUTE_PROFILE` 与 `API_OPTIONAL_ROUTE_GROUPS` 控制；默认 `full` 保持现有全量 API，`lean` 只允许作为开发减载配置使用，禁止在运行时代码里基于请求内容或关键词动态裁路由。
|
||||
- 开发预览端口职责必须固定：`5174` 仅保留给源码热更新前端，`docker-compose.yml` 下的静态生产预览前端默认改用 `5175`（`FRONTEND_PROD_PORT` 可覆盖）；禁止再让 `5174` 在静态容器和 Vite dev server 之间来回漂移，避免浏览器验证和真实源码脱节。
|
||||
- 禁止再通过函数名片段、hint 常量或模板词在底层推断 tier、结构化输出或 fallback 策略。
|
||||
- 所有 LLM 调用禁止静默兜底与 stub 假成功；low 失败时必须优先强制升级到 high 重试并保留低/高两段日志，high 仍失败时才显式报错。
|
||||
- 用户可见问答链路（`function_name` 含 `answer/reply/qa`）禁止使用 `reasoning_content` 回退，避免思考过程外漏。
|
||||
|
|
|
|||
|
|
@ -1,25 +1,96 @@
|
|||
# Task Brief
|
||||
|
||||
## Meta
|
||||
- Generated At: {{GENERATED_AT}}
|
||||
- Base Ref: {{BASE_REF}}
|
||||
- Head Ref: {{HEAD_REF}}
|
||||
本模板用于 PMFlow Codex 单线程或并行 Packet 分派。并行任务必须填写 `Read Scope / Write Scope / Forbidden Paths`；没有 `write_scope` 的任务不允许并行执行。
|
||||
|
||||
## Changed Files
|
||||
{{CHANGED_FILES}}
|
||||
## Meta
|
||||
|
||||
- Packet ID: `{{PACKET_ID}}`
|
||||
- Phase: `{{PHASE}}`
|
||||
- Owner: `{{OWNER}}`
|
||||
- Generated At: `{{GENERATED_AT}}`
|
||||
- Base Ref: `{{BASE_REF}}`
|
||||
- Head Ref: `{{HEAD_REF}}`
|
||||
- Target Branch / Worktree: `{{TARGET_BRANCH_OR_WORKTREE}}`
|
||||
- Commit Strategy: `{{COMMIT_STRATEGY}}`
|
||||
- Commit Gate: `auto_commit / hold_no_commit / ask_before_commit`
|
||||
- Depends On: `{{DEPENDS_ON}}`
|
||||
- Merge After: `{{MERGE_AFTER}}`
|
||||
|
||||
## Goal
|
||||
|
||||
{{GOAL}}
|
||||
|
||||
## Current Truth Source
|
||||
|
||||
{{CURRENT_TRUTH_SOURCE}}
|
||||
|
||||
## Target Object / Contract
|
||||
|
||||
{{TARGET_OBJECT_OR_CONTRACT}}
|
||||
|
||||
## Scope
|
||||
{{SCOPE_SUMMARY}}
|
||||
|
||||
- Read Scope:
|
||||
{{READ_SCOPE}}
|
||||
|
||||
- Write Scope:
|
||||
{{WRITE_SCOPE}}
|
||||
|
||||
- Forbidden Paths:
|
||||
{{FORBIDDEN_PATHS}}
|
||||
|
||||
- Shared Files Touched:
|
||||
{{SHARED_FILES_TOUCHED}}
|
||||
|
||||
## Change Flags
|
||||
|
||||
- API Change: `yes/no` - {{API_CHANGE_DETAIL}}
|
||||
- Schema Change: `yes/no` - {{SCHEMA_CHANGE_DETAIL}}
|
||||
- Migration Change: `yes/no` - {{MIGRATION_CHANGE_DETAIL}}
|
||||
- Runtime Boundary Change: `yes/no` - {{RUNTIME_BOUNDARY_DETAIL}}
|
||||
- Feature Flag: {{FEATURE_FLAG}}
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
{{IMPLEMENTATION_NOTES}}
|
||||
|
||||
## Risks
|
||||
|
||||
{{RISKS}}
|
||||
|
||||
## Verification
|
||||
- Backend: `python3 -m py_compile backend/app`
|
||||
- Frontend: `npm run build` + `npx tsc --noEmit`
|
||||
## Rollback Plan
|
||||
|
||||
{{ROLLBACK_PLAN}}
|
||||
|
||||
## Verification Commands
|
||||
|
||||
- Backend: `{{BACKEND_VERIFICATION}}`
|
||||
- Frontend: `{{FRONTEND_VERIFICATION}}`
|
||||
- Migration: `{{MIGRATION_VERIFICATION}}`
|
||||
- Focused: `{{FOCUSED_VERIFICATION}}`
|
||||
|
||||
## Docs To Sync
|
||||
|
||||
{{DOCS_TO_SYNC}}
|
||||
|
||||
## Integration Notes
|
||||
|
||||
- Integration Owner: `{{INTEGRATION_OWNER}}`
|
||||
- Merge Order: `{{MERGE_ORDER}}`
|
||||
- Expected Commit(s): `{{EXPECTED_COMMITS}}`
|
||||
- Out-of-scope Findings:
|
||||
{{OUT_OF_SCOPE_FINDINGS}}
|
||||
|
||||
## Delivery Checklist
|
||||
|
||||
- [ ] `base_ref` recorded
|
||||
- [ ] `read_scope` and `write_scope` declared
|
||||
- [ ] `forbidden_paths` checked
|
||||
- [ ] Shared files reserved or assigned to integration owner
|
||||
- [ ] Code completed
|
||||
- [ ] Contracts synchronized
|
||||
- [ ] Docs synchronized
|
||||
- [ ] Build/lint/tests passed
|
||||
- [ ] Verification passed
|
||||
- [ ] Commit gate decision recorded
|
||||
- [ ] Packet commit created after verification
|
||||
- [ ] Integration gate passed
|
||||
|
|
|
|||
Loading…
Reference in New Issue