# 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 必须记录启动时的 `base_ref`。 - 每个并行线程优先使用独立 git worktree，避免同一工作区文件互相覆盖。 - 合并前必须检查当前分支是否落后主集成分支。 - 合并前必须检查 `git diff --name-only`，确认没有写出 `write_scope`。 - 触碰共享高冲突文件时，必须交由 integration owner 合并。 ### 4.8 Packet commit 协议 并行开发不是“每改一行就提交”，也不是“多个 Packet 混在一个长期分支里攒”。默认规则： - 一个 Packet 对应一个短生命周期分支：`codex/`。 - Packet 完成、验证通过、文档同步完成后，必须形成至少一个可审查 commit。 - Codex 必须自行执行 commit gate 判定，不把“该不该提交”默认丢给用户判断。 - 复杂 Packet 可以在同一分支内做多个 checkpoint commit，但每个 commit 都必须是逻辑完整切片，不能提交半成品、失败验证或越界改动。 - 不允许把多个不同 Packet 的实现混进同一个 commit。 - 不允许在旧 Packet 分支上继续做新 Packet；新 Packet 必须从最新 integration base 或明确依赖分支重新开 `codex/`。 - 如果新 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 已把项目内消息、结构化候选、审查动作和证据链落到真实表。 - C2-contract 已锁定 commit API、原子提交规则、响应合同和失败语义。 - 当前缺口是按合同把已接受/已编辑的 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 / G0 Freeze + C2 Contract / done 完成内容： - 将当前非删除工作区成果直接 checkpoint 到 `master`，形成 `b52428f docs: codify PMFlow product delivery governance` 与 `e04ea4d chore: checkpoint current PMFlow workspace` 两个提交；删除痕迹未提交，避免未确认地固化旧截图、表格、tunnel 脚本和临时文件删除。 - 收口 Phase C2 commit 合同：`POST /pmflow-os/change-sets/{change_set_id}/commit` 的请求体、权限、原子提交模式、响应结构、错误码、高风险 approval gate、C2 V1 objectType 白名单和 ProjectTruthState 投影规则。 - 明确 C2 V1 默认 `mode=atomic`，任一 eligible item 写入失败时整个 commit 回滚，禁止半写入 Project Memory。 - 明确 C2 必须实现 `Requirement / Decision / Task / Risk`；`Release` 可选；`ModelDecision / MetricSignal` 暂缓并必须 fail-closed。 涉及文件： - `docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md` - `docs/architecture/API_CONTRACTS.md` - `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md` 验证： - `git status --short --branch` 已确认 checkpoint 后仅剩未提交删除痕迹。 - `git diff --cached --name-status` 阶段检查未发现删除项被纳入 checkpoint。 - 本轮 C2-contract 只改合同文档，未新增代码、Schema 或 migration，未运行编译/单测。 未完成或风险： - 工作区仍有未提交删除痕迹，需用户单独确认是否删除或恢复。 - C2 后端 route/service/schema 与前端 API/store 尚未实现。 下一步建议： - 执行 `C2-backend`：实现 atomic ChangeSet commit service、route、权限、事务、高风险 gate 与后端测试。 - 合同稳定后并行执行 `C2-frontend`：接入 commit API，替换真实模式下的 demo-only `promoteAcceptedToGraph`。 ### 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/` 分支、记录 `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=` 通过 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=` 进入 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` 与后端现有对象逐一对齐。