# PMFlow 项目结构说明（CLAUDE.md） ## 1. Agent 入口文件（你关心的“进项目先读什么”） - `AGENTS.md`：Codex/Coding Agent 的主规则入口（优先级最高的项目级约束） - `CLAUDE.md`：面向 Claude 风格的项目说明文档（补充背景） - 建议：规则放 `AGENTS.md`，架构/目录说明放 `CLAUDE.md` - 当前 AI 行为的系统宪章已在 `AGENTS.md` 中升级为“事实层 / 评审层 / 生成层 / 执行层”四层分治；所有新增 AI 业务默认按该宪章接入。`CLAUDE.md` 当前承载的是“架构说明 + 运行边界 + 目录库存”，不再假定自己只包含背景说明 - 新增执行约定：计划类需求一旦确认进入实现阶段，默认连续执行到“实现完成 + 验证完成 + 统一回复验收结果”；仅在明确阻塞、高风险冲突、context 限制或用户主动中断时才中途打断。 - 新增 bugfix 执行约定：缺陷修复/回归修复允许跨多个直接相关文件端到端完成，不再按文件数硬性拆分；但必须同时满足“改动范围围绕同一根因”“不夹带无关重构”“最终附带编译/测试验证”。大功能开发或结构性重构仍优先按子任务拆分。 - 新增发布约定：凡后端代码或数据库迁移发生改动，完成编译/测试后必须继续执行当前环境对应的热部署/重启/重载步骤，确认服务已加载新版本；若当前机器不是部署环境、缺少权限或不具备热部署条件，必须在结果中明确说明未执行原因与阻塞点，禁止默认省略。 - 新增前端快回路约定：`L1 微调` 默认走 `verify:login-fast` 或 focused screenshot，`L2 视觉逻辑` 默认走 `verify:login-responsive` 或 `capture:login:matrix`，出现 `context_compacted` 或超过 `8` 分钟仍未落代码时优先收口或切线程。 - 新增并行开发约定：多个 Codex 线程可以按 `Main Flow / Space / Account Settings / Shell Integration` 等大模块 lane 长期并行，但实际执行仍必须按 Packet 分派，声明 `module_lane / read_scope / write_scope / forbidden_paths / shared_files / cross_lane_inputs / cross_lane_outputs / base_ref`，默认使用 `codex/` 独立分支和独立 worktree；共享路由、导航、Provider、API base 和文档只能由 integration owner 统一合并。当前 P0 已冻结 route 归属：`/space` 归 Space，`/pmflow-os / /command-center / /change-review / /execution-bridge / /release-growth` 归 Main Flow，`/me` 归 Account Settings，`/settings` 仅为 reserved route、尚未实现。 - 下面各节中大量 `新增/更新/移除` 清单用于保留“当前架构库存”和关键入口索引，不等同于运行时主规范；行为约束与禁止项仍以 `AGENTS.md` 为准。 ## 2. 项目定位 - 项目名：`PMFlow / Neural Sync` - 形态：AI 原生项目管理系统（多租户 + 角色权限 + SSTC 工作流） - 技术栈： - 后端：`FastAPI + SQLAlchemy + Alembic` - 前端：`React + TypeScript + Vite + Tailwind + Radix + React Query` ## 3. 顶层目录（精简版） ```text AIProjectManger/ ├── AGENTS.md # Agent 执行规则（建议优先维护） ├── CLAUDE.md # 当前架构说明与运行边界 ├── start.sh / stop.sh # 一键启动/停止入口 ├── docker-compose*.yml # 容器编排 ├── mdproject/ # 执行计划与任务清单（中文为主） ├── backend/ # FastAPI 后端 ├── 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/P8 下一步、单次任务范围、Codex 并行推进协议、完成后进度回写规则和新线程接续标准；继续产品推进前必须先读。P8 已完成 Review Decision Loop、Space review attention queue、Account review decision preference 与 integration 收口；仍不新增 route/nav、不接真实通知中心。 - `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 条核心黄金案例。 ## 4. 后端结构（`backend/`） ```text backend/ ├── app/ │ ├── api/ # 路由层（canonical 入口优先使用 *_api/ 子包） │ ├── core/ # 配置、日志、启动与核心能力 │ ├── dependencies/ # 鉴权/租户等依赖注入 │ ├── middleware/ # 请求中间件 │ ├── models/ # SQLAlchemy 模型 │ ├── schemas/ # Pydantic 模型 │ ├── services/ # 业务服务（已目录化收敛） │ ├── config/ # 配置与 prompt │ └── utils/ # 通用工具 ├── alembic/ # 数据库迁移真源 ├── scripts/ # 后端运维/修复脚本（含历史 backfill / requirement-plan 修复） ├── tests/ # 后端回归测试 ├── requirements.txt └── Dockerfile ``` - 当前后端重点入口优先看： - `backend/app/api/` 下的 `*_api/` 子包与聚合 router - `backend/app/services/ai_pmo/`（AI PMO 主链、Mounted Runtime、semantic context） - `backend/app/services/ai_pmo/project_operating_context_builder.py` + `backend/app/schemas/project_operating_context.py`（统一 `ProjectOperatingContext / ProjectFitBrief / ExecutionRecipe` 合同；`/rag/ask`、`/ai-pmo/process-text`、kernel ingress 会先补当前项目/仓库/线程锚点，再给 Query Route Gateway、fit brief builder 与 answer payload 消费） - `backend/app/schemas/analysis_packets.py` + `backend/app/services/analysis_packet_builder.py` + `backend/app/services/analysis_project_snapshot_loader.py`（统一 analysis packet family：在 runtime truth 之上增量生成 `project_fit_analysis / external_impact_analysis / internal_explain_analysis / followup_explain_analysis`；当前 richer packet 已显式带 `current_subject / candidate_position / rejected_position / reason_chain` 这类对象级分析字段，供 Web、Feishu、QA session replay 的分析型展示消费；shared loader 统一补 richer `tasks/signals + description/summary + analysis_object_refs`，但 loader 现已 fail-closed，不再从 task/signal 标题描述推 task-signal 关系或 fit 对位；builder 主路径只吃显式 object ref、精确文本绑定和唯一候选这类非语义结构证据，不再使用 token-overlap、partial-match 或本地词表 second-guess 上游关系） - `backend/app/services/adaptive_rag_service/mixin_target_resolution.py`（internal target resolution 现已按 business-frame-first 收口：`goal_kind / target_scope / resource_role / project_binding / object_binding / expected_answer_shape` 先决定 project/task/signal/config/feature/doc/user 绑定；session follow-up project binding、internal domain clarify 与 semantic filter 都只看结构化 frame，不再靠 `subject_focus / referenced_objects` 这类 coarse 字段拍板对象） - `backend/app/services/adaptive_rag_service/shared_utils.py` + `mixin_deterministic_query_core.py` + `mixin_fast_answer_project_main.py` + `mixin_fast_answer_semantic_p1.py` + `mixin_deterministic_query_count.py` + `mixin_deterministic_query_list.py` + `mixin_retrieval_router_db.py` + `mixin_deep_guard_answer.py` + `mixin_answer_mainline.py` + `mixin_manifest_feature_p2.py`（AdaptiveRAG read-side 兼容层现已统一改成 business-frame-first：deterministic query、fast answer、structured DB retrieval、deep guard、feature evidence 与 internal query plan 都只消费 `BusinessSemanticFrame / target_resolution / query_plan` 归一化后的结构，不再用 `subject_focus / referenced_objects` 做 project/task/signal/config/feature/doc/user 的二次分流） - `backend/app/config/ai_prompts.py` + `backend/app/services/adaptive_rag_service/mixin_core_intent.py` + `backend/app/services/adaptive_rag_service/mixin_query_route_gateway.py` + `backend/app/services/adaptive_rag_service/mixin_session_state.py`（query semantics 上游真源已同步切到 `business_frame + query_profile(needs_private_context, needs_freshness, confidence)`：production backend 不再生成、透传或持久化 `subject_focus / query_profile.referenced_objects`，route snapshot、follow-up scope continuity 与 session state 只保留 project/target/business-frame binding 这组结构） - `backend/app/services/adaptive_rag_service/`（只读问答主链；`mixin_query_route_gateway.py` 负责 non-plan `query.answer` 的 internal/external/uncertain 来源合同归一化、contract 审计与显式来源回复合同；`mixin_project_fit_brief.py` 负责 current-project customer-safe fit brief；`mixin_answer_retrieval.py` 现已把 `route_mode=external` 接到独立外部查询主链，并在 payload 暴露 `fit_brief / external_recommendation`；internal 路径新增 `internal_query_context.py` 里的 `InternalContextPacket` 作为 `Operation Contract -> Target Resolver -> Query DSL Plan -> 受控执行器 -> semantic facts 优先 -> verifier` 的运行时单一真源） - `backend/app/services/adaptive_rag_service/mixin_fast_answer_project_main.py` + `backend/app/services/ai_pmo/ai_pmo_typed_executor_execute/mixin_execute_query_project.py` + `backend/app/services/ai_pmo/ai_pmo_kernel/ai_pmo_typed_executor_mixins_parse.py`（runtime 去 lexical fallback 的关键入口：project progress fast answer bypass 现在只吃结构化 `interaction_level / goal_kind / resource_role / expected_answer_shape`；casual chat 直答只吃 `message_intent=casual_chat`；project lookup 直答只吃结构化 `message_intent=project_lookup(_question) + query_semantics`；signal 数量与 strict analysis 只吃结构化 `requested_count / analysis_mode / operation_intent_contract`，不再从自然语言里靠词表/正则判断） - `backend/app/services/adaptive_rag_service/mixin_target_resolution.py` + `backend/app/services/adaptive_rag_service/mixin_deep_guard_answer.py`（internal config 主链：`resource_role=config` 不再默认降成泛化 `config:system`；必须靠显式 `object_binding` 区分 `config:model_routing` 与 `config:mcp_template_center`，并分别走模型路由快答与 MCP 配置快答） - `backend/app/services/adaptive_rag_service/internal_domain_catalog.py` + `mixin_target_resolution.py` + `mixin_followup_anchor.py` + `mixin_answer_precheck.py` + `mixin_answer_payload.py`（internal object/domain clarify 主链：当前 catalog 已覆盖 `project / task / signal / config / feature / doc / user`；当 internal query 只确认到大域、还没唯一命中子对象时，先产出 `internal_target_selection` 澄清协议；follow-up 选项会回填 `query_semantics_overrides` 再继续受控检索，避免“澄清后继续复读旧答案”） - `backend/app/config/ai_prompts.py`（`PROMPT_RAG_QUERY_SEMANTICS` 现在明确要求 internal domain 问答把 `resource_role / object_binding` 打出来；模型配置示例绑定 `config:model_routing`，MCP 配置示例绑定 `config:mcp_template_center`，功能/文档问法则分别绑定 `resource_role=feature/doc`） - `backend/app/services/adaptive_rag_service/mixin_followup_anchor.py` + `mixin_answer_mainline.py`（follow-up 澄清恢复主链：`query_route_selection / followup_anchor_selection` 现在先走统一结构化澄清解析，再把 `source_policy_hint / query_semantics_overrides / selected_qa_id` 透回主链；用户澄清“第二条/内部那个”后，不再靠本地词面去猜上一轮回复或 option） - `backend/app/services/integrations/feishu_signal_pipeline/mixin_intent_gate_core.py` + `mixin_context_prefill_a.py` + `mixin_context_prefill_b.py` + `mixin_serialization.py`（Feishu `project.create` 预填链现在统一吃 `_extract_project_prefill()` 的结构化 `suggested_name / suggested_description / suggested_scope`，不再在 runtime 用 `_extract_project_scope / _extract_project_intent_fields / _is_contextual_project_request / heuristic_*` 之类词面 helper 扣项目字段） - `backend/app/api/rag_api/routes_route_governance.py`（platform AI Ops 的 route/context 治理接口：`/rag/query-route-governance/summary|items|items/{id}`，只读暴露 `query_route_memories` 的 summary/list/detail） - `backend/app/services/external_query_service/`（external `query.answer` 主链：`External Query Planner -> External Query Gateway -> External Provider Registry -> MCP 优先 -> bounded fallback live search -> verifier -> ExternalContextPacket -> ExternalAnswerPresenter`；其中 `schemas.py` 负责结构化 plan/evidence/context packet，`presenter.py` 负责 external-only 回答生成。当前已额外支持“推荐外部信号源”问法：recommendation ask 的进入条件优先来自统一语义规划层透传到 `ExternalQueryPlan.interaction_level=recommendation` 的结构化层级，不再由 presenter 本地 cue list 拍板；命中后不再退回 `external_verifier_blocked` 拒答，而是先产出 `SignalSourceRecommendationPacket(candidates + caveat)`，再渲染成业务中文的 `top-N candidate + why`；recommendation 结果现在还会同步沉成可 carry-over 的 candidate set 绑定（`candidate_set_id + candidates + materialization payload`），供 reply-anchor follow-up 继续走 non-plan `signal_source.onboard` 直写链，不再默认 requirement draft；即使当前外部公开资料仍在校验，也只允许显式标成“推荐，不是已验证事实”，不能滑回架构腔或边界空话） - `backend/app/services/mcp_config/`（MCP 模板接入中心：catalog、bundle 持久化、后端直连 runtime probe / Microsoft Learn 检索桥接、Local Bridge 接入说明与本机确认状态） - `backend/app/services/semantic_fact_service/`（semantic facts 读模型、八类业务对象统一抽取/失活、ORM 提交钩子入队、治理看板查询） - `backend/app/api/semantic_facts_api/`（platform AI Ops 的 semantic facts 治理后台接口：overview / objects / detail / reextract / backfill） - `backend/app/api/mcp_api/`（MCP 模板接入中心后台接口：catalog / servers / validate / confirm-client-apply） - `backend/app/api/ai_routing.py` + `backend/app/services/ai_routing_governance_service.py`（AI 路由与供应商产品化控制台：团队策略接口属于客户空间 AI 使用设置；overview/admin-console/diagnostics/capability-slots 属于 platform AI Operations Console，要求 `platform.ai_routing.manage`；`backend/.control_plane/pmflow-routing-rules.json` 是 baseline rule pack，能力槽位保存到 `integrations(type='ai_capability_slots')`，但只有发布后的 `active.slots` 会被 runtime tier 解析消费，draft 只用于平台编辑/校验/发布；发布校验按 `SLOT_REQUIREMENTS` 检查供应商声明能力、`capability_probe` live evidence 与后端派生 `effective_capabilities`，缺能力、缺证据或证据过期返回 critical 并阻止 protected slot publish，长上下文声明窗口只算 `declared_only` 不算 verified，low 缺 probe 只 warning；团队策略只保存到 `integrations(type='ai_team_policy')`；在 `API_ROUTE_PROFILE=lean` 下也必须加载） - `backend/app/config/ai_function_runtime_profiles.py` + `backend/app/services/ai_function_runtime_profile_service.py`（Function Runtime Profile 配置真源；当前将 Project Launch 草案生成与 PMFlow Change Review 变更抽取的生成预算、修复预算、temperature、响应模式、前台等待、provider/job 超时、最大重试、大输入策略、冒烟结果和发布版本保存到 `integrations(type='ai_function_runtime_profiles')`，业务场景路由只展示场景内“生成运行合同”，运行时只消费已发布 active profile，draft 必须先 validate + smoke 再 publish；active profile 会实际控制 HTTP provider timeout、外层任务/调用超时、transient retry budget、large 输入预处理和前端 foreground wait 窗口） - `backend/app/api/ai_call_traces_api.py` + `backend/app/services/ai_call_trace_service.py` + `backend/app/services/ai_scene_runtime_policy.py` + `backend/app/models/ai_call_log.py`（platform AI Operations Console 的 AI 调用审计与场景超时策略入口；`GET /ai-call-traces*` 要求 `platform.ai_routing.manage`，只读 `ai_call_logs`，展示脱敏 prompt/response、provider/model/slot/routing meta、token/cost/latency、错误诊断和 `runtime_policy`；`structured_timeout` 必须独立展示为“模型超时”，不得与 JSON 无效/空响应混淆；`llm_service` 写入 `trace_id / user_id / provider / model / latency_ms / routing_meta / prompt_key / prompt_release_id / prompt_source`，并在 `provider_request_payload / provider_response_payload / provider_attempts` 保存真实上游 provider 请求、响应与重试尝试链；token 优先读取上游 `usage.prompt_tokens/completion_tokens/total_tokens`，没有 usage 时才使用兼容估算；`AISceneRuntimePolicyService` 为 Project Launch 等业务场景写入 `provider_timeout_seconds / job_timeout_seconds / input_bucket` 等显式策略；审计响应区分 raw provider code 与 `provider_label/runtime_label/engine_name`，并返回 `function_label/scene_label` 中文展示字段；DashScope 供应商编码统一为 `dashscope`，不得恢复旧 provider code；平台详情只展示完整脱敏 provider payload，不返回原始 headers 或密钥） - `backend/app/api/prompt_assets_api.py` + `backend/app/services/prompt_assets_service.py` + `backend/app/services/prompt_runtime_service.py` + `backend/app/config/ai_prompt_registry.py` + `backend/app/config/ai_prompt_eval_rubrics.py`（platform AI Ops 的 Prompt 运营中心；`GET /prompt-assets*` 要求 `platform.ai_routing.manage`，聚合 registry、默认 seed prompt、active/draft `prompt_releases`、`prompt_release_checks` 门禁状态、分层 `prompt_golden_cases`、`prompt_replay_runs / prompt_replay_case_results`、调用质量摘要、跨客户空间 PMFlow OS `pmflow_ai_feedback_events` 用户反馈、`optimizer_candidates` 优化候选、调用点和迁移状态；`POST /prompt-assets/{prompt_key}/releases*` 允许 `managed_release` 创建/激活/回滚，允许 `guarded_release` 创建候选版本但激活必须先通过 variable contract / schema smoke / golden replay 门禁；release replay 支持 `contract_smoke` 与 `llm_compare`，LLM replay 通过 `llm_service` 和显式 `routing_meta` 走本地路由层，结果记录 baseline/candidate AI call log、judge score/label/reason 与风险标记；non-blocking golden case 失败只进入 warning/人工复核，blocking case 失败才阻塞发布；PMFlow OS 负反馈只生成待复核 `JudgeRun / OptimizerCandidate`，不得直接改 active prompt 或自动发布；`GET /prompt-assets/{prompt_key}/releases/{release_id}/watch-summary` 提供 release 级 24h/7d 质量观察和健康/复核/回滚建议；`inline_discovered` / `needs_migration` 不能冒充已配置生效；低风险运行时调用点通过 `PromptRuntimeService` 读取 active release 并把 prompt_key/release/source 写入 AI 调用日志，格式失败回退默认模板） - `backend/app/api/llm_engines.py`（platform AI Operations Console 的“供应商与凭据”写入口，提供供应商新增/编辑/启用/删除/连通测试、能力矩阵声明 capabilities、registry-driven `capability_probe` runtime evidence、后端派生 `effective_capabilities` 与引擎设置；能力探测默认 full 覆盖 basic chat、结构化、JSON Schema、工具、流式和长上下文声明门禁，要求 `platform.ai_routing.manage`，`API_ROUTE_PROFILE=lean` 下也必须加载） - `backend/app/api/model_routing.py`（platform AI Operations Console 的隐藏 Route Lab 诊断接口，要求 `platform.ai_routing.manage`，`API_ROUTE_PROFILE=lean` 下也必须加载；运营导航不暴露函数级编辑入口） - `backend/app/api/auth.py` + `backend/app/services/phone_auth_service.py` + `backend/app/models/phone_verification_code.py`（手机号验证码登录、自注册与邀请绑定链路；`users.phone_e164` 是全局手机号身份，开发环境可返回 `dev_code` 便于本地验证） - `backend/app/api/workspaces_api.py` + `backend/app/services/workspace_service.py` + `backend/app/models/tenant_membership.py` + `backend/app/models/tenant_invitation.py`（solo-first/team-ready 空间成员兼容层：数据库沿用 `tenants`，产品语义为个人空间/团队空间；注册自动创建个人空间，手机号邀请加入团队空间不剥夺个人空间，退出团队后回到个人空间；`backend/alembic/versions/20260428_repair_admin_yangyu_workspace_state.py` 负责历史 admin/yangyu 当前空间与旧团队空间数据修复） - `backend/app/api/space_api/` + `backend/app/services/space_saved_idea_service.py` + `backend/app/schemas/space.py` + `backend/app/models/saved_idea.py`（Personal Space 暂存想法真实闭环；`saved_ideas` 是 pre-project idea seed，只保存未成型想法、原始输入、来源、准备度、缺失问题、结构化 enrichment 元数据和草案关联，不写 Project Memory、ChangeSet 或执行回写；创建/编辑原始输入时尝试 `space_saved_idea_enrichment_v1`，prompt key 为 `PROMPT_SAVED_IDEA_ENRICHMENT` 并经 `PromptRuntimeService` 读取平台 active release、写入 prompt 归因；AI 失败显式落 `ai_failed/system_baseline`；`promote` 只生成 Project Launch 草案并回到人工确认链，确认前不创建项目） - `backend/app/models/platform_membership.py` + `backend/app/services/platform_access_service.py`（PMFlow 平台方账号平面：`platform_memberships` 和 env bootstrap 只给 PMFlow 内部 `PLATFORM_ADMIN / AI_OPS` 等角色发放 `platform.*` capability；客户空间 `OWNER/REVIEWER` 不等于平台管理员） - `backend/app/services/llm_service/`（显式 `routing_meta` 协议） - `backend/app/services/integrations/feishu_integration_service/`（飞书入站与卡片回调；`mixin_receive_routing.py` 的 `qa_direct` 现已支持 recommendation ask 直出推荐正文，并把原始 `Project database / signal_total / 当前盘面 / 建议动作 / External Freshness Guard` 这类内部/英文术语压成单行中文来源说明） - `backend/app/services/signal/`（信号接入、编排、planner、repair） - 本轮新增的问答路由审计存储为 `backend/app/models/query_route_memory.py`，通过 `backend/alembic/versions/20260415_add_query_route_memories.py` 建表；只用于 route audit / feedback 回灌 / 离线评估，不做在线自动调参。 - 本轮新增的语义事实读模型为 `backend/app/models/semantic_fact.py` 与 `backend/app/models/semantic_fact_extraction_run.py`，通过 `backend/alembic/versions/20260415_add_semantic_facts.py` 建表；用于内部查询的 facts-first 命中与异步抽取审计。 - 本轮新增的外部查询 fallback、fit brief 与展示回归测试位于 `backend/tests/test_external_query_planner.py`、`backend/tests/test_mcp_external_query_bridge.py`、`backend/tests/test_internal_query_context_packet.py` 与 `backend/tests/test_adaptive_rag_mainline_contract.py`；它们一起锁定“Query Route Gateway 不再跑 runtime probes、External Query Planner fallback 不再按对象重分类、fit brief 会显式进入 external planner、external answer presenter 必须区分 `verifier_blocked / no_relevant_results / retrieval_failed / indirect_only`、external freshness follow-up 不再靠硬编码词表”。 - 详细目录迁移、兼容壳清理与新增模块清单见库存文档。 ## 5. 前端结构（`frontend/`） ```text frontend/ ├── e2e/ # Playwright 真实浏览器 E2E 用例 ├── public/ # 静态资源；`brand/` 是 PMFlow Logo / favicon 源资产 ├── src/ │ ├── api/ # 接口封装 │ ├── features/ # 新产品域与原型状态机（如 PMFlow OS / 个人空间 / 新项目启动台） │ ├── pages/ # 页面级组件（已目录化） │ ├── components/ # 通用组件与 SSTC 等共享组件 │ ├── hooks/ # 自定义 hooks │ ├── lib/ # 通用工具 │ ├── stores/ # 状态管理 │ ├── router/ # 路由 │ └── types/ # TS 类型定义 ├── package.json ├── playwright.config.ts └── vite.config.ts ``` - 当前前端重点入口优先看： - `frontend/public/brand/` + `frontend/src/components/brand/PMFlowLogo.tsx` + `frontend/src/components/brand/PMFlowUserAvatar.tsx`（PMFlow Logo 源资产、统一读取组件与本地品牌头像；应用壳、营销页、登录视觉和 favicon 不再各自手绘旧标，账号头像不再依赖随机外链头像） - `frontend/src/api/`（统一 API 封装） - `frontend/src/router/index.tsx`（顶层路由懒加载入口；登录页与 Layout 保持同步首屏；`/command-center` 保留免登录产品预览壳；`/space`、`/space/ideas`、`/space/drafts`、`/space/projects`、`/space/settings/members`、真实 `/project-launch`、`/pmflow-os`、`/change-review`、`/structured-extraction`、`/memory-writeback-result` 与 `/me` 均需登录；`/project-launch?demo=1` 或 `?dataSource=demo` 是唯一匿名启动台演示入口；旧 `/projects`、`/users*`、`/workloads*` 和 `/dashboard` 只做兼容跳转；空间管理入口走 workspace role，`/platform/*` 和平台治理页走 `platform_context.capabilities`） - `frontend/src/auth/RouteBoundary.tsx`、`frontend/src/lib/rbac.ts`、`frontend/src/lib/apiError.ts`、`frontend/src/lib/pendingIntent.ts`（前端身份边界、workspace/platform capability 判断、产品化 API 错误分类与登录续接 pending intent 真源；用户可见 UI 禁止直接展示 Axios/FastAPI 原始 401/403/5xx 文案；pending intent 只能恢复输入或承接已生成的 Project Launch 草案，不得登录后自动重放真实写请求） - `frontend/src/features/personal-space/`（个人空间首页与空间二级收件箱；`PersonalSpacePage.tsx` 通过 `frontend/src/api/space.ts` 聚合项目摘要、PMFlow OS truth-state / execution-summary / execution-capabilities 与真实 `GET /space/saved-ideas`，并兼容消费旧 AI PMO `waiting_manual / draft_pending_confirm` 工作项，首页只预览暂存想法、草案箱和最近项目的少量高优先级条目；`SpaceCollectionPages.tsx` 承接 `/space/ideas` 暂存想法二级页和 `/space/drafts` 草案箱二级页，支持筛选、搜索、补充、归档、转 Project Launch 草案或回主流程确认；暂存想法只能推进到 Project Launch 草案确认链，不直接写项目真相层） - `frontend/src/features/project-launch/`（首次进入页 / 新项目启动台；默认调用真实 `frontend/src/api/pmflowLaunch.ts` draft job/revise/confirm API 创建项目，只有显式 `?demo=1` 或 `?dataSource=demo` 才启用本地 mock 演示状态机） - `frontend/src/features/account-settings/`（`/me` 个人中心与设置；通过 `frontend/src/api/accountSettings.ts` 管理个人资料、默认语言、AI 回答深度、证据展示偏好和通知偏好，移动端使用分组列表与 bottom sheet，不进入 auth core） - `frontend/src/features/pmflow-os/`（PMFlow OS 前端产品域；共享 truth store 已支持 `?projectId=` 读取真实后端 projection，真实模式下 message、`proposed_items` extraction、ChangeItem `accept/edit/defer`、ChangeSet `commit`、review decision、Team reviewer routing、单条 iteration recommendation -> ChangeSet draft 与同组 iteration recommendation 批量 -> ChangeSet draft 均调后端，显式 `?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/C2/P8 真实路径；提供 `truth-state`、`execution-summary`、thread message、`proposed_items` extraction、ChangeSet detail、ChangeItem `accept/edit/defer`、ChangeSet `commit`、review decision、execution handoff/progress writeback、release validation run、release feedback ingest、Team reviewer routing、recommendation change-set draft 与 recommendation group change-set draft；项目主链“发送并提取”使用独立 `change_review` protected scene、`pmflow_change_review_extraction_v1` Function Runtime Profile 与 `PROMPT_PMFLOW_CHANGE_REVIEW_EXTRACTION`，不再复用 Project Launch draft prompt/function；复用 `truth_nodes / tasks / semantic_facts / ai_project_control / dev_sync / FeedbackIngest / IterationRecommendation` 并投影 `pmflow_threads / pmflow_thread_messages / pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`；`truth-state.reviewerRouting` 是 `{status, warningCode, summary, items}` 合同，生成建议审查人/原因/来源/风险/跳转 URL，并投影 `reviewDecision / approvalState / requestedAt / decidedAt / decisionReason`；`POST /pmflow-os/change-sets/{change_set_id}/review-decisions` 支持 request_review/approve/request_changes/reject，复用 `PMFlowApproval` 审计，不自动 commit；C2 commit 默认 atomic，`ModelDecision / MetricSignal` 暂 fail-closed） - `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 真实创建链；`draft-jobs/revise` 写 `pmflow_launch_draft_jobs` 并任务化生成草案，兼容 `drafts` 只写 `pmflow_launch_drafts`，`confirm` 在同一事务写真实 Project、启动线程、启动消息、初始 truth_nodes、tasks 与 semantic_facts seed）；`backend/app/api/legacy_ai_steward_api.py` 仅保留旧文本创建接口的 410 迁移响应，并在 lean profile 下始终挂载 - `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 已实现，Phase C2 backend/frontend commit 已实现） - `frontend/src/pages/ai-steward/`（历史 AI Steward 页面迁移占位；`/ai-steward` 只做 legacy redirect，不再作为产品入口） - `frontend/src/components/ai-steward/`（AI 问答共享展示组件与旧问答浮窗兼容代码；当前产品壳不再全局挂载 `FloatingQAChat`，空间页由 `frontend/src/features/personal-space/components/SpaceAIConcierge.tsx` 承接入口，并复用 `QAMarkdownContent` 等展示能力） - `backend/app/api/ai_readiness_api/` + `backend/app/services/ai_readiness_service.py` + `frontend/src/api/aiReadiness.ts` + `frontend/src/features/ai-readiness/`（空间级 AI 就绪合同；由 `/space`、真实 `/project-launch`、项目级 `AI 副驾`、`/ai-config?tab=setup` 与 `/platform/*` 共同消费；Project Launch readiness 默认由后端从平台运行租户供应商、published active `structured` 槽、scene registry、能力证据和最近 24h `pmflow_launch_draft_v1` 日志推导；单次最近生成失败只作为平台 warning，24h 内已有成功且连续失败少于 3 次时用户端仍保持可生成，连续失败达到阈值才进入 recovering；本机状态只允许 test 或 `VITE_AI_READINESS_LOCAL_OVERRIDE=true` 覆盖；平台 AI Ops 可触发不写草案/项目的结构化 smoke） - `frontend/src/pages/ai-config/AIConfigPage.tsx` + `frontend/src/pages/ai-config/constants.ts` + `frontend/src/pages/ai-config/components/AISetupWizard.tsx`（空间级 AI 使用设置；`/ai-config` 及其子路由必须使用空间配置壳 `SpaceSidebar + SpaceTopBar`，不得切入项目工作台侧栏；`/ai-config?tab=setup` 是 AI 可用状态与项目生成能力门禁入口，连接、知识、团队策略和 Prompt 策略继续承载客户空间 AI 使用治理；平台供应商、全局路由、route/context、semantic facts 不在客户空间暴露，只有带 `platform_context.capabilities` 的平台 AI Ops 才能看到供应商/路由/诊断 CTA） - `frontend/src/pages/ai-routing/` + `frontend/src/api/aiRouting.ts` + `frontend/src/api/aiSteward.ts` + `backend/app/services/ai_routing_scene_contracts.py`（`TeamAIPolicyPage.tsx` 是客户空间负责人策略视图；PMFlow 平台 AI Ops 运行总览已合并进 `/platform`，旧 `/platform/ai-routing-console` 只做兼容跳转；AI 运行层保留明确子菜单：`/platform/ai-routing-providers` 供应商与凭据、`/platform/ai-routing-slots` 能力槽位、`/platform/ai-routing-scenes` 业务场景路由、`/platform/ai-routing-costs` 成本/配额/缓存、`/platform/ai-routing-failures` 失败诊断；业务场景路由是 Scene Contract & Impact Console，只读展示后端 `scene_contract`、场景健康度、release gate、active/draft runtime、能力缺口、发布影响、筛选排序和确定性修复动作，不在运营页展开函数名；`sceneContracts.ts` 仅作为后端合同缺失时的前端 fallback；供应商页展示并编辑 capabilities 能力矩阵，能力槽位页展示 active 当前版本、draft 编辑区、发布校验、发布阻塞、能力覆盖/缺口与回滚动作；业务场景路由的修复动作会 deep-link 到槽位、供应商和失败诊断页并自动聚焦 scene/slot/capability；共享实现集中在 `AIRoutingOperationsPages.tsx`，继续只消费脱敏 `admin-console` 聚合数据） - `frontend/src/pages/platform/AICallTracesPage.tsx` + `frontend/src/api/aiCallTraces.ts`（PMFlow 平台 AI Ops 的 AI 调用审计页面；入口 `/platform/ai-call-traces` 位于“质量与事件层”，支持按状态、供应商、模型、函数、业务场景、能力槽位、prompt_key、prompt_source、trace、时间窗口和关键词筛选，列表展示脱敏预览，详情展示 prompt 版本归因、完整脱敏 provider 请求/响应 payload、上游尝试链、失败归因、场景 timeout 策略和建议动作；prompt-attributed 详情可一键沉淀 Golden case；客户空间、Space、Project Launch 和项目级 AI 副驾不得暴露该入口） - `frontend/src/pages/platform/PromptAssetsPage.tsx` + `frontend/src/api/promptAssets.ts`（PMFlow 平台 AI Ops 的 Prompt 运营中心；入口 `/platform/prompt-assets` 位于“质量与事件层”，展示 prompt key、业务场景、family、风险、发布策略、默认模板、active release、draft 数、门禁状态、最新 replay、调用点和迁移缺口；详情弹层承载基础信息、模板 Diff、版本历史、发布门禁、回放评审、质量归因和运行信息，`managed_release` 可创建草稿/激活/回滚，`guarded_release` 可创建候选、运行契约回放或 LLM 回放并通过门禁后激活；回放结果展示 judge score/label/reason、baseline/candidate call id、风险标记，右侧发布概览展示 release watch 建议；质量归因页可查看 7 天调用、失败、默认回退、成本估算、PMFlow 用户赞同/不赞同反馈、负反馈原因、优化候选、失败样本 deep-link，并从失败调用生成带 case_type/priority/scenario/tags 的 golden case；待迁移项只读并展示原因；客户空间、Space、Project Launch 和项目级 AI 副驾不得暴露 prompt 正文） - `frontend/src/pages/model-routing-config/`（隐藏 Route Lab；入口 `/platform/route-lab`，旧 `/platform/model-routing-config`、`/ai-config/model-routing-config` 与裸 `/model-routing-config` 仅兼容跳转；页面只读展示函数级规则、最近执行与历史 override 痕迹，不在平台侧栏中暴露） - `frontend/src/pages/ai-config/mcp-config/`（AI 使用设置 -> MCP 模板接入中心） - `frontend/src/pages/platform/PlatformChrome.tsx` + `frontend/src/pages/platform/PlatformConsolePage.tsx`（PMFlow 平台 AI Operations Console 专属应用壳与首页；`/platform/*` 不复用旧项目工作台侧栏/顶部条，侧栏按“运行总览 / AI 运行层 / 工具与外部能力层 / 上下文与语义层 / 质量与事件层”组织，只展示当前 platform capability 可进入的运营工具；旧 `/ai-config/*` 平台诊断路径只做兼容跳转） - `frontend/src/pages/query-route-governance/`（platform AI Operations Console -> route/context 治理页） - `frontend/src/pages/semantic-facts-board/`（platform AI Operations Console -> semantic facts 治理页） - `frontend/src/components/layout/LazyBoundary.tsx`（统一 route/page-section/dialog 级 loading skeleton） - `frontend/src/components/login/`（公开登录页组件目录；`LoginExperience.tsx` 负责双栏登录壳，`LoginForm.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、AI Steward QA 组件与 Recipes/Projects/Users 等模块化拆分的详细库存见库存文档；旧独立收件页已退场，待处理能力收敛到 `/space`、`/change-review`、`/team-layer` 与 `/me`。 - 顶层路由已改为 `React.lazy + Suspense`，统一 fallback 使用 `frontend/src/components/layout/LazyBoundary.tsx`；`/ai-steward` 只保留迁移重定向，`tab=create` 迁到 `/project-launch`，`tab=engine` 迁到 `/ai-config`，`tab=feedback-center` 有 `project_id` 时迁到 `/release-growth?projectId=`、否则迁到 `/space`，其它 legacy tab 迁到 `/space`；AI 使用设置页面按 active tab 只渲染当前可见区块，Projects/Users/图表页则把重对话框与图表从同步入口拆出。 - `frontend/src/features/ai-readiness/` 是空间级 AI 就绪状态前端合同：`types.ts` 定义状态与 blocker，`readiness.ts` 负责角色权限、后端 readiness 查询、test/dev override 和 `useAIReadiness()`，`components.tsx` 提供顶部状态胶囊与卡片。真实门禁以 `GET /ai-readiness/project-launch` 为准；localStorage 只允许测试或显式本地覆盖，不再作为生产 readiness 真源。 - `frontend/src/features/project-launch/` 是新项目启动台独立产品域，也是新建项目唯一用户入口：`types.ts / useProjectLaunchState.ts` 承载状态合同和真实 API 编排，真实模式必须登录并优先调用 `POST /pmflow-launch/draft-jobs` 创建 AI 草案生成任务，轮询 `GET /pmflow-launch/draft-jobs/{job_id}` 获取完成草案，确认后调用 `POST /pmflow-launch/drafts/{draft_id}/confirm` 创建真实项目并跳转 `/pmflow-os?projectId=`；“补充一句”通过真实输入弹层创建 `merge_supplement` revision，已有草案时调用 `POST /pmflow-launch/drafts/{draft_id}/revise`，运行中的旧 job 由后端标记 `superseded`，禁止硬编码追加补充句或用 UI 暂停动画冒充 AI 可暂停/续写；旧 `POST /ai-steward/project-from-text` 只返回 410 迁移错误，不得绕过草案确认直接写正式对象；`mockData.ts` 只在显式 `?demo=1` 或 `?dataSource=demo` 匿名演示模式下使用，真实模式的进度、操作流、审查建议、附件引用和计数必须来自当前输入、后端 job/草案、warnings/evidence，不得展示 DevWeekly 周报 demo 内容。401/无 token 不得展示 `Request failed with status code 401` 或归类为网络异常，必须保存输入到 pending intent 并提示重新登录后继续。真实模式下若 `AIReadiness.canGenerateProjectDraft=false`，`LaunchShell` 渲染 `AISetupRequiredPanel`，用户端默认只看到“先记录项目想法，AI 草案生成暂不可用”的客户视图；空间负责人可查看空间 AI 状态，平台 AI Ops 可通过显式平台诊断卡查看具体 cause/CTA；不提供空项目创建入口，避免在缺少结构化上下文时提前创建项目壳；低信息输入（如纯问候、缺少产品/用户/问题线索）由后端 `input_needs_more_info` 422 门禁拦截并回到补充输入态；demo 模式不受该门禁影响。`LaunchShell` 桌面端复用 `frontend/src/features/personal-space/components/SpaceChrome.tsx` 的空间左侧栏和顶部条，主画布仍由 `IntentInputPanel / AIProgressCanvas / HumanReviewCanvas / DraftEditCanvas / FailureStatePanel / SuccessTransitionPanel` 承接，移动端仍由 `MobileLaunchLayout` 承接；`frontend/src/pages/ProjectLaunchPage.tsx` 仅做薄入口。 - Project Launch 的“保存为暂存想法”必须调用 `POST /space/saved-ideas` 写真实 `saved_ideas`，成功后 `/space#saved-ideas` 可见；它只保存 pre-project idea，不生成草案、不创建项目、不写项目记忆。保存/完善时会优先用 `PROMPT_SAVED_IDEA_ENRICHMENT` 走 Prompt 运营中心 active release 做结构化完整度判断，返回 `enrichment_status / enrichment_payload / missing_questions / readiness_score`；问候、测试词或无实质想法输入必须判为 `needs_more_info` 和 0 准备度；AI 不可用时只能显式显示系统初判，不冒充 AI 结论。`/space` 里点击“生成项目草案”才调用 `POST /space/saved-ideas/{idea_id}/promote`，生成 draft 后通过 pending intent 进入 Project Launch `human_review`，仍需用户确认才创建正式项目。 - `frontend/src/features/personal-space/` 是登录后的空间层入口：`PersonalSpacePage.tsx` 承接桌面个人工作面与独立移动单手布局，`frontend/src/api/space.ts` 只读聚合 `projects` summary、PMFlow OS `truth-state`、`execution-summary`、`execution-capabilities`，并兼容消费旧 AI PMO `waiting_manual / draft_pending_confirm` 工作项，生成 `nextActionQueue` 我的下一步队列、执行准备度、我的今日容量、继续推进、待确认、review attention、发布关注、发布后反馈关注、下一轮迭代草稿关注、AI 正在推进、草案箱、缺项目归属补全、最近项目摘要；这些空间聚合以后端项目可见性为准，`OWNER/REVIEWER` 看租户级团队视图，`BUILDER/OPERATOR` 只看本人拥有或 `user_projects` 绑定项目，legacy 工作项只看本人拥有或本人项目绑定项。未登录访问 `/space` 必须跳登录，不展示个人空间语义。Space 首屏消费 `frontend/src/features/ai-readiness/` 双层合同：用户端默认显示客户可理解的 AI 可用状态、业务影响和可继续动作，普通成员/空间负责人/平台人员进入用户端都不默认看到供应商、路由、连接测试、模型槽位、trace 或函数名；空间负责人额外看到空间 AI 状态、团队策略和工具连接入口；平台 AI Ops 仅通过显式平台诊断卡或 `/platform/*` 查看具体 cause/CTA。顶部条展示统一 readiness pill，管理员侧边栏显示 `/ai-config?tab=setup` 与 `/space/settings/members` 入口；`/space/projects` 是所有项目视图，旧 `/projects` 只做兼容跳转。`components/SpaceAIConcierge.tsx` 是空间级 AI 管家入口：只围绕个人空间、跨项目下一步、待确认、执行中、草案、暂存想法和 AI 能力状态工作，通过 `/space/ai-concierge/*` 产品接口注入空间上下文包并复用 QA 历史/会话能力；前端不得直接依赖 optional `/rag/*` 路由，历史读取失败只影响历史视图，不阻断新会话提问；真实写操作只能给跳转或待确认建议，不声称已执行。全局 `Layout` 不再挂载旧 `FloatingQAChat` 悬浮球，项目页仍使用项目级 `AI 副驾`。Space 左侧导航只承载稳定空间目的地，当前保留“空间首页”“所有项目”和管理员“AI 使用设置 / 成员与权限”；最近项目、暂存想法、草案箱、待我确认、AI 正在推进属于空间首页内部工作台模块，不作为一级侧栏导航。Space P6 的下一步队列按高风险待确认、发布阻塞/失败证据、handoff consumed 后缺少后续 progress、下一轮 draft、发布后反馈/收入/合规信号排序；Space P7 新增 `review_attention`，只读消费 `truth-state.reviewerRouting`，按高风险待我审、`request_changes / rejected` 后待处理、`reviewer_missing` warning、普通 pending review 排序进入“我的下一步”；旧 `missing_project_scope` 只允许在 Space 选择项目后复用 `POST /ai-pmo/work-items/{id}/decision` 继续既有审计链，不新增旁路接口，不直接写项目真相层。动作只跳 `/change-review?projectId=&changeSetId=`、已有 `/team-layer?projectId=`、`/execution-bridge?projectId=`、`/release-growth?projectId=` 或复用旧工作项决策 API；执行准备度只读展示工具连接、待确认、待审查、待验收和阻塞原因，今日容量只读展示有效容量、人工触点、剩余容量、动态建议结构、系统解释和 AI 预处理可释放时间，不写项目业务对象；Space P3/P4/P5 仍只读消费 release validation 与 releaseSignals；不在 Space 写 Project Memory、PMFlowApproval、ProgressEvent、ReleaseValidationRun、FeedbackIngest、RevenueEvent、ComplianceCheckRun、ChangeSet 状态、容量 override 或发布执行，不虚构 reviewer、审查意见、待审 ChangeSet、工具连接、执行能力或容量计划。`components/SpaceChrome.tsx` 承接空间层左侧栏、顶部条与空间用量组件；`/project-launch` 桌面首次新建壳复用同一空间 Chrome，但不在左侧展示工作台区块 badge；`frontend/src/pages/PersonalSpacePage.tsx` 仅做薄入口。 - `frontend/src/features/account-settings/` 是 Account Settings 独立产品域：`AccountSettingsPanel.tsx` 承接 `/me` 桌面设置页、移动端分组列表与 bottom sheet，`frontend/src/api/accountSettings.ts` 定义个人资料、默认语言、AI 回答深度、证据展示偏好和四类通知偏好合同；当前已有账号同步 API fallback、本地 UI 通知消费模型、Release/Growth 偏好 helper、post-release / next change review 偏好 helper、`getAccountReminderConsumption(settings, event)` 提醒强度消费合同，以及 `getReviewDecisionNotificationPreference(settings, event)` review decision 偏好合同；支持 `reminderIntensity=silent|normal|prominent` 与 `evidenceDisplay=compact|expanded`，并覆盖 `review_requested / review_approved / review_changes_requested / review_rejected / high_risk_approval_required`；`releaseGate / failureAlert / pendingConfirmation / executionWriteback` 只影响页面内提醒表达强度和证据展开方式，不代表真实邮件、桌面推送或系统通知中心已接入，也不得隐藏真实业务证据、reviewerRouting、approval 或审计状态，不改 OAuth/JWT/auth core；`frontend/src/features/pmflow-os/pages/AccountPage.tsx` 仅做薄入口并复用既有退出登录 bottom sheet。 - `frontend/src/features/pmflow-os/` 当前承载新的对话驱动前端产品域：`store.tsx` 提供共享 truth store；真实模式通过 `?projectId=` 调用 `frontend/src/api/pmflowOs.ts` 读取后端 `ProjectTruthState` projection，并调用真实 message、`proposed_items` extraction、ChangeItem `accept/edit/defer`、ChangeSet `commit`、review decision、Execution Handoff create/consume、execution progress writeback、release validation run create、release feedback ingest、单条 iteration recommendation -> ChangeSet draft、同组 iteration recommendation 批量 -> ChangeSet draft、capacity-plan 与 capacity override simulate/apply API，成功后 refetch truth-state / execution-summary / capacity plan；显式 `?demo=1` 才启用本地演示状态机。`pages/` 下包含 `CommandCenter / StructuredExtraction / ChangeReview / MemoryWritebackResult / WorkGraph / ExecutionBridge / ReleaseGrowth / TeamLayer / ProjectMemory / Account` 主页面；`ChangeReviewPage` 真实模式可请求审查、通过、要求修改或拒绝当前 ChangeSet，展示审查状态、建议 reviewer、审查意见和 high-risk approval gate，但不自动 commit；其顶部识别统计、待确认列表和右侧 AI 副驾评估只能由后端 `changeSets / changeItems / evidence` 派生，没有真实待审项时显示空态，不得用 demo 的知识库搜索、混合召回、固定风险/建议/计数补位；`TeamLayerPage` 真实模式读取 `state.reviewerRouting`、`execution-capabilities` 与 `capacity-plan`，展示待审 ChangeSet、建议 reviewer、审查状态、执行能力、个人执行准备度、工具准备度、团队今日容量、动态基线、瓶颈、AI 预处理建议、负责人模拟/应用容量 override 与调整记录；capacity override 只写审计，不自动分派、不自动审查、不写 ChangeSet；`ExecutionBridgePage` 已支持创建 handoff、运行端领取确认和执行进度回写；`ReleaseGrowthPage` 真实模式展示 `execution-summary.releaseGate`、execution evidence、阻塞原因、下一步动作、`latestValidationRun` 和 `releaseSignals`；静态发布/增长原型仅保留在显式 demo 模式；后端只记录 review decision/progress/release gate/release validation/release feedback/recommendation draft/capacity override 元数据，不执行本机命令、真实发布命令、外部支付、真实推送、自动 Project Memory commit、自动任务分配或正式任务创建；`ProjectMemoryPage` 在真实模式优先消费后端 `project-memory/overview` 读模型，二级页承接 `/project-memory/items|assets|context-packs|writebacks`，单条点击进入右侧抽屉；读模型失败时才降级展示 `truth-state.projectMemory` 兼容投影。`components/` 下除了 `ProjectStageRail / ThreadComposer / ExtractionRail / ChangeGroupPanel / ObjectGraphSection / ContextPacketPanel / ExecutionTimeline / ReleaseGatePanel / TeamFeedPanel` 之外，新增 `ProjectStructuredLoop / PMFlowOsFrame / AccountControls / FeedbackPrimitives` 等行为组件；`components/MobileBottomNav.tsx` 是正式应用壳唯一移动底部导航，固定为 `空间 / 指挥台 / 待确认 / 动态 / 我的`。 - `ProjectTruthState.feed` 现在是 Team Feed 只读动态流，由 `backend/app/services/pmflow_os_projection_service.py` 聚合 review request、review decision、ChangeSet 状态、execution progress 与 release gate 事件；`TeamLayerPage` 复用 `TeamFeedPanel` 展示 `state.feed`，只做摘要、空态和跳转，不写审批、不写 ChangeSet、不写通知，也不在真实模式用 mock 动态补齐。 - 旧登录实现 `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 工作区主容器（组装各阶段组件） - `useSSTCWorkspaceOrchestration.ts`：工作区编排 Hook（状态聚合、请求编排、事件路由） - `sstcUtils.ts`：SSTC 工具函数（数据转换、状态判断、通用 helper） - `SSTCSignalStagePanel.tsx`：信号阶段面板 - `SSTCCharterStagePanel.tsx`：宪章阶段面板 - `SSTCTaskStagePanel.tsx`：任务阶段面板 - `SSTCExecutionBoardPanel.tsx`：执行看板阶段面板 - `SSTCReleaseStagePanel.tsx`：发布阶段面板 - `SSTCReviewStagePanel.tsx`：复盘阶段面板 - `SSTCTaskCreateDialog.tsx`：任务创建弹窗 - `SSTCReleaseCreateDialog.tsx`：发布创建弹窗 - `SSTCReviewCreateDialog.tsx`：复盘创建弹窗 - `AIVisibilityPanel.tsx`：AI 可视化信息面板 - `FeedbackSummaryCard.tsx`：反馈中心摘要卡片（任务阶段/执行看板复用） - `SSTCGlobalHeader.tsx`：SSTC 全局头部 - `SSTCStageNav.tsx`：阶段导航 - `SSTCChainView.tsx`：链路视图 - `SSTCRiskFloatPanel.tsx`：风险浮层 - `SignalContentHoverCard.tsx`：信号内容悬浮卡片 - `charterModules.ts`：宪章模块配置与映射 ### 5.2 修改前必须执行 `FIND_USAGE` 的 SSTC 组件清单 - `SSTCWorkspace.tsx` - `useSSTCWorkspaceOrchestration.ts` - `sstcUtils.ts` - `SSTCCharterStagePanel.tsx` - `SSTCSignalStagePanel.tsx` - `SSTCTaskStagePanel.tsx` - `SSTCExecutionBoardPanel.tsx` - `SSTCReleaseStagePanel.tsx` - `SSTCReviewStagePanel.tsx` - `SSTCReleaseCreateDialog.tsx` - `SSTCReviewCreateDialog.tsx` - `SSTCTaskCreateDialog.tsx` ## 6. 运行命令（高频） ### 根目录 ```bash ./start.sh dev # 推荐：docker-dev 热更新模式 ./stop.sh dev ./scripts/start_model_probe.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`。 ### 前端 ```bash cd frontend npm run dev npm run build npm test npm run e2e:feishu ``` ### 后端（本地直跑） ```bash cd backend pip install -r requirements.txt uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 ``` ## 7. 团队维护建议（简版） - 规则变更：只改 `AGENTS.md` - 结构变更：同步改 `CLAUDE.md` + `docs/architecture/ARCHITECTURE_INVENTORY.md` - 运行边界 / 已知 runtime 假设变更：同步改 `AGENTS.md` + `docs/architecture/RUNTIME_GUARDRAILS.md` - API/契约变更：后端 `schemas` + 前端 `types` 同步更新 ## 8. 服务边界约束（禁止越界） - 当前必须立即遵守的摘要规则以 `AGENTS.md` 第 8 节为准。 - 长运行边界、跨链路守门细节、失败语义和已知 runtime 假设已迁到 [`docs/architecture/RUNTIME_GUARDRAILS.md`](/Users/yuuuu/Documents/AIProjectManger/docs/architecture/RUNTIME_GUARDRAILS.md)。 - 当前最重要的摘要只保留： - 写操作必须经 Alembic / 受控执行器 / outbox / 审计日志，禁止业务路径直写或同步直发。 - 用户可见核心业务内容禁止 fallback、stub、模板句冒充成功；失败必须显式失败或标记待确认。 - MCP 模板接入中心只保存模板参数、命令预览、runtime probe 和手动确认状态；`backend_direct` 模板可由 PMFlow 后端直连（远程 `streamable_http` MCP 或内建 `backend_adapter` runtime），`stdio` 模板只能走 Local Bridge / 兼容 MCP host；禁止从服务端直写宿主机 `~/.codex/config.toml` 或替客户执行本机命令。 - 运行时业务动作归因统一走“对象/上下文绑定 -> `SemanticContextPacket` -> `SemanticDecision` -> gatekeeper”。 - `backend/app` 运行时代码禁止恢复散落的中文关键词、正则、`looks_like_*`、`*_HINTS/*_KEYWORDS` 业务拍板逻辑。 - `llm_service` 只认显式 `routing_meta` 协议，不再靠函数名或 hint 推断 tier / contract / fallback。 - 内部只读查询必须走 `Operation Contract -> Target Resolver -> Query DSL Plan -> InternalContextPacket -> 白名单受控执行器 -> semantic facts 优先 -> verifier`，其中 mainline 要先做 packet 预检，`query_semantics` 只作上游 scratchpad/兼容镜像并且只允许单点兼容写回；禁止继续充当 internal executor 或 verifier 的运行时真源，同时禁止自由 SQL 和无证据脑补。 - `semantic_facts` 自动抽取统一走 ORM 提交钩子 -> `ingest_events(channel=semantic_fact_extract)` -> 统一 worker，支持 `project/task/signal/document/user/requirement/release/review` 八类对象；禁止在各路由散落手工 enqueue。 - AI Steward、Requirement Plan、Signal Source、AdaptiveRAG 等核心链路的详细 guardrails 统一以 `RUNTIME_GUARDRAILS.md` 为准。 ## 9. 新增代码的参考模式 - 详细的接口、页面与服务参考入口已迁到 [`docs/architecture/CODE_REFERENCE_INDEX.md`](/Users/yuuuu/Documents/AIProjectManger/docs/architecture/CODE_REFERENCE_INDEX.md)。 - 当前只保留高价值摘要： - 新增后端接口：优先参考 `backend/app/api/sstc_api/` 的结构 - 新增前端 API 调用：优先参考 `frontend/src/api/sstc.ts` - 新增数据库表：参考 `alembic/versions/` 最新 migration - 新增飞书事件处理：参考 `backend/app/services/integrations/feishu_integration_service/` - 更细的 AI Steward / RAG / AI PMO / Signal / SSTC / 前端页面入口索引统一以 `CODE_REFERENCE_INDEX.md` 为准 ## 10. 幂等与事务约束 - 所有入站事件必须经过 `ingest_events` 幂等去重 - 飞书回复必须经过 `feishu_reply_outbox`，禁止同步直接发送 - 飞书回复发送幂等：`reply_hash = MD5(source_message_id + reply_text)`，同租户下 `status=sent` 的相同哈希不得重复发送 - 跨表写操作必须在同一个数据库事务内完成 ## 11. 已知 BOUNDARY（不要幻构行为） - 详细已知运行边界与环境假设统一维护在 [`docs/architecture/RUNTIME_GUARDRAILS.md`](/Users/yuuuu/Documents/AIProjectManger/docs/architecture/RUNTIME_GUARDRAILS.md)。 - 当前高价值摘要只保留： - 飞书回调字段可能缺失文件名/大小，仅保证 `attachment_id/key/type` 可用。 - 真实飞书网页 E2E 依赖本机已登录的 Chrome/Feishu 会话，结果校验统一走数据库探针。 - 路由配置唯一真源固定为 `backend/.control_plane/pmflow-routing-rules.json`；普通 LLM 请求超时以 `LLM_REQUEST_TIMEOUT` 为默认，保护型结构化场景以 Function Runtime Profile active 合同里的 `provider_timeout_seconds` 为准。 - World Model 静态层已接入 Redis 缓存（`wm:static:{tenant_id}:{project_id}`，TTL 600s），写操作后主动 invalidate，动态层不缓存。 - `signal_sources` 仅作为历史创建结果区的兼容展示字段；项目看板与 SSTC 信号阶段统一只读正式 `Signal`。 ## 12. 技术债务清单 - [x] `mixin_auto.py` `_safe_int` NameError：已通过显式导入 `_safe_int` + 回归测试锁定，避免后续共享导出调整导致运行时未定义 - [x] AI 入口主链已统一：飞书长连接（`capture_from_feishu`）、`/ai-pmo/process-text` 与 `/rag/ask` 已统一收敛到 `AIPMOKernelService.process_ingress` 主链；`/rag/ask` 通过 `rag_ask_contract.build_kernel_ingress_kwargs` 透传 RAG 上下文（`session_id/new_session/thinking_mode/action_mode/...`），query 执行后由 `build_rag_response_payload` 保持 HTTP 响应兼容，回归由 `test_rag_route_contract.py`、`test_ai_pmo_qa_http_mainline_e2e.py`、`test_ai_pmo_ingress_mainline.py` 锁定 - [x] Unified Project Operating Context 已接到问答入口：`/rag/ask`、`/ai-pmo/process-text` 与 kernel ingress 现会先透传最小 `project_operating_context`（当前项目、当前仓库摘要、页面/线程锚点），AdaptiveRAG 的 `Query Route Gateway` 进一步产出 `execution_recipe`；external 主链会在需要时补 `fit_brief`，回答 payload 同步暴露 `project_operating_context / execution_recipe / fit_brief / external_recommendation / analysis_packet / recommended_next_step / handoff_mode`，回归由 `test_project_operating_context_contract.py`、`test_rag_route_contract.py`、`test_ai_pmo_qa_http_mainline_e2e.py`、`test_external_query_planner.py`、`test_mcp_external_query_bridge.py`、`test_adaptive_rag_mainline_contract.py`、`test_analysis_packet_contract.py` 锁定 - [x] 飞书入口层耦合已收敛：飞书真实入口已拆为三段职责链（预处理 `mixin_receive_prepare.py` / capture 执行 `mixin_receive_capture_flow.py` / 编排 `mixin_receive.py`）；`mixin_receive.py` 不再混合传输解析、附件标准化、capture 异常兜底与收尾回执逻辑，分层边界通过 `test_feishu_receive_orchestration_contract.py` 锁定 - [x] `task.create` 已升级为一等 typed intent：`IntentResolver/RouteResolver` 新增 `task.create` 常量与 `task.create` 路由族；TypedExecutor 已接入任务落库执行（含 `project_id`/任务标题槽位守卫、对齐 Charter 校验、`persist_task` 写入）；`WorkflowRegistry`、`ReplyRenderer`、`followup` 校验与草稿确认闭环已纳入 `task.create`；并补 `test_ai_pmo_task_intent_contract.py` 回归锁定 - [x] `task.create` 已接入消息级幂等账本：Feishu `source_message_id/feishu_message_id` 作为 `task.create` 账本 key，重复确认只回放同一结果，不再重复落库；回归由 `test_feishu_pipeline_queue_contract.py` 锁定 - [x] `signal_source.onboard` 已接入消息级幂等账本与 non-plan 直写 carry-over：TypedExecutor 以 `source_system + source_message_id` 作为 onboarding ledger key，重复提交只回放同一结果，不再重复跑信号源接入编排；recommendation candidate set 会经 `reply_anchor_qa_context + action_contract` 沉到执行结果里，供后续 `把刚才推荐的写进系统 / 确认入库` 继续走 `prepare_write -> confirm_write -> execute_write` 直写链，而不是默认 requirement draft；回归由 `test_ai_pmo_signal_source_onboard_contract.py` 锁定 - [x] AdaptiveRAG 职责已完成首轮收敛：`answer_question` 入口已分层为 `prepare runtime` 与 `base mainline` 两段，写确认逻辑通过 `_should_trigger_write_ack_gate` 独立门控；基础问答主路径不再与写确认判断混写在同一函数体。分层契约由 `test_adaptive_rag_mainline_contract.py` 锁定（read 绕过 ack、write 命中 ack、feishu write 维持主链） - [x] 执行层已形成统一执行账本与参数来源约束：ingress 执行路径统一通过 `KernelIngressStorageMixin` 生成 `execution_result.action_contract`（固定 `param_source=decision.execution_plan.actions+workflow_route+execution_result`）并写入 `operation_execution_ledger`（`applied/pending_manual/pending_confirmation/failed`）；`mixin_auto.py`、`mixin_prepare_manual.py` 的 `operation_code` 日志来源已对齐 `action_contract`，回归由 `test_ai_pmo_execution_ledger_contract.py` 锁定 - [x] QA/RAG 路由契约双轨已收敛：`/ai-steward/rag/ask` 兼容入口已移除，问答统一收敛到 `POST /rag/ask`；参数构造与 tenant 解析收口在 `backend/app/api/rag_ask_contract.py`，前端 `FloatingQAChat` 与 Context Cache API 目录均已对齐，`backend/tests/test_rag_route_contract.py` 与 `backend/tests/test_context_cache_profile_catalog.py` 已锁定回归 - [x] 三模式交互上下文基线已显性化：`/rag/ask`、QA session detail 与 session state replay 现统一透出 `route_decision / clarification_code / clarification_candidates / answer_mode / grounding_status / evidence_pack / project_operating_context / execution_recipe / fit_brief / external_recommendation / analysis_packet / handoff_mode / can_enter_plan / recommended_next_step`；前端 `FloatingQAChat` 会在即时回答与历史回放两条路径都接入这批字段，`QAConversationStatusBar` 与 `QAResponseMetaCard` 显式展示当前对象、来源模式、仓库/执行通道、项目画像、分析结果、外部推荐状态与下一步；`/ai-pmo/process-text` 与 `GET /ai-pmo/work-items` 现同步投影 `plan_mode / plan_status / requirement_plan_context_summary`，旧独立收件页已退场，相关待处理状态由 Space 兼容读模型消费 - [x] AI 管家浮窗交互已与 Grounding Runtime 对齐：回答区已切到 markdown 渲染，顾问标签升级为显式交互按钮；`consultant_mode_preference` 只用于 `/rag/ask` 内部重答，`允许执行` 明确交接到 `/ai-pmo/process-text`，避免 query/execute 边界回退到旧的一锅煮 - [x] Retrieval source registry / metadata 已统一：AdaptiveRAG 检索链已建立统一 source registry / metadata normalizer，`citations[]/sources_used[]` 直接消费标准字段 `source_type/source_id/chunk_id/target_url/project_id/updated_at/permission_scope/source_priority`；`doc/url/feishu/pmflow/graph/db` 的来源元数据与排序键已收口，并由 `test_rag_route_contract.py`、`test_adaptive_rag_mainline_contract.py` 锁定 - [x] 语义治理 baseline 已清零：`backend/app` 运行时代码中的 `looks_like_* / *_HINTS / *_KEYWORDS` 残留已清空，主链统一改为对象/上下文绑定 + `SemanticContextPacket -> SemanticDecision -> gatekeeper`；`scripts/semantic_lint_baseline.txt` 已清空，并由 `scripts/semantic_lint.py` 与 `backend/tests/test_semantic_lint.py` 做仓库级守门 - [x] 结构化 runtime 收口回归已补齐：`backend/tests/test_runtime_structured_semantics_contract.py` 额外锁定 `backend/app` 运行时代码里 `_is_question_like / _is_project_lookup_question / _is_capability_question / classify_intent_complex` 等旧语义拍板残留不得回流；`backend/tests/test_feishu_pipeline_queue_contract.py` 同步覆盖 `followup` 线程锚点优先与 signal capture 不再依赖问句词法兜底 - [ ] 历史 Feishu 队列 / `feishu_items` 兼容链仍未完全退场：飞书真实入口、卡片动作、文本 queue followup，以及 `project_knowledge_graph` 的主增量/API 命名都已切到 `work_item` 主链；当前剩余债务主要是 `feishu_items` 存量读链路、历史 pending 事件兼容消费，以及 legacy `feishu_delta` 证据/回放兼容壳。后续需在历史存量清空后正式封存该兼容层 - [x] AdaptiveRAG 向量检索 legacy fallback 已移除：`AdaptiveRAGRetrievalVectorMixin._retrieve_vector_context()` 现在只支持 PostgreSQL/pgvector 主路径；非 PostgreSQL 或 PG 查询失败时直接返回空结果，不再回退 Python 侧 legacy 扫描，边界由 `test_adaptive_rag_mainline_contract.py` 锁定 - [x] 历史 Alembic 链幂等性缺陷已修复：`add_users_table_rbac.py` 的 PostgreSQL ENUM 创建已改为显式创建 + 列类型 `create_type=False` 复用，`userrole/userstatus` 不再在同一条 migration 内重复建型；回归由 `test_add_users_table_rbac_migration.py` 锁定 - [ ] 食谱图片上传仍是示例桩实现：`backend/app/services/recipe/service.py` 仍以模拟 URL 代替对象存储，`POST /recipes/upload-image` 也还停留在示例接口形态；若该模块继续保留，需要补齐真实对象存储接入、租户隔离与统一 `{code,message,data}` 响应包络，否则应明确标注为非核心示例模块 - [x] LLM 运行时仍未完全收敛：`ai_service_core._invoke_with_retry` 与 `stream_chat` 已统一走 `llm_service`；旧 `_get_llm` 路径已显式禁用，并补回归测试锁定 - [x] QA 主链自动化测试覆盖已补齐：`backend/tests/` 已覆盖问答/RAG 主路径与关键场景；新增 `test_ai_pmo_qa_http_mainline_e2e.py` 通过 HTTP 层锁定 `/rag/ask` 的 `qa_readonly/mixed` 契约以及 `/ai-pmo/process-text` 的 `draft_pending_confirm` 主链返回，配合 `test_ai_pmo_ingress_mainline.py`、`test_ai_pmo_task_intent_contract.py`、`test_ai_pmo_tactical_brain_contract.py` 形成稳定回归基线 - [x] 飞书交互闭环已补齐：执行场景回执在 `draft_pending_confirm/pending_manual` 下优先生成按钮卡片并经 outbox 异步发送；`card.action.trigger` 已覆盖 `confirm/revise/cancel/continue` 回调分发，分别复用 `DraftConfirmHandler.handle_api_decision` 与 AI PMO `process_ingress` 主链继续执行；回调 HTTP 现在会同步返回 toast 反馈，确保点击按钮后至少有可见结果；`backend/tests/test_feishu_card_action_contract.py` 已补卡片构造与 `continue` 回归契约