linyuhang
/
PMFlow
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
PMFlow/docs/architecture/ARCHITECTURE_INVENTORY.md

46 KiB
Raw Blame History

ARCHITECTURE INVENTORY

1. 目的

  • 本文档承接 PMFlow 的架构库存与关键入口索引。
  • CLAUDE.md 保留当前架构说明、运行边界和参考模式。
  • 本文档记录当前模块分布、重要子包、关键脚本与前端页面分组，后续架构变更统一在此同步。

2. 同步规则

  • 任何影响目录结构、主入口、模块归属、前后端页面/API 分组、脚本布局的架构变更，都必须同步更新：
    • CLAUDE.md
    • docs/architecture/ARCHITECTURE_INVENTORY.md
  • API/Schema 契约变更仍需同步：
    • docs/architecture/API_CONTRACTS.md
    • 对应前端 types/api 封装
  • 路由/函数名/运行时流向变更仍需同步：
    • docs/architecture/DATAFLOW.md
    • 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，Phase C2 backend/frontend 已实现 atomic commit
  • docs/architecture/RUNTIME_GUARDRAILS.md：运行边界、守门规则与已知运行假设
  • docs/architecture/API_CONTRACTS.md：接口/Schema 契约
  • docs/architecture/DATAFLOW.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/：任务包产物与验收截图

4. 后端库存

4.1 API 路由分组

  • backend/app/api/ai_steward_api/
  • backend/app/api/ai_pmo_api/
  • 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/
  • backend/app/api/skill_tags_api/
  • backend/app/api/ai_logs_api/

4.2 AI PMO 与语义主链

  • backend/app/services/ai_pmo/ai_pmo_kernel/
  • backend/app/services/ai_pmo/ai_pmo_kernel_ingress_flow/
  • backend/app/services/ai_pmo/project_operating_context_builder.py
  • backend/app/services/ai_pmo/ai_pmo_typed_executor_execute/
  • backend/app/services/ai_pmo/ai_pmo_typed_executor_discovery/
  • backend/app/services/ai_pmo/semantic_context/
  • backend/app/services/ai_pmo/workflow_semantic_planner/
  • backend/app/services/ai_pmo/draft_confirm_handler.py

4.3 问答、模型与生成

  • backend/app/services/adaptive_rag_service/
  • backend/app/services/adaptive_rag_service/internal_query_context.py
  • backend/app/services/adaptive_rag_service/mixin_project_fit_brief.py
  • backend/app/services/adaptive_rag_service/mixin_query_route_gateway.py
  • backend/app/services/adaptive_rag_service/mixin_query_route_governance.py
  • backend/app/schemas/project_operating_context.py
  • backend/app/services/external_query_service/
  • backend/app/services/semantic_fact_service/
  • backend/app/services/semantic_fact_service/hooks.py
  • backend/app/services/llm_service/
  • backend/app/services/ai_steward_service/
  • backend/app/services/feedback_center/
  • backend/app/services/task_brief_service.py
  • backend/app/config/ai_prompts.py
  • backend/app/config/ai_prompts_catalog/
  • backend/app/config/ai_prompt_registry.py
  • backend/app/services/model/model_routing/service.py
  • backend/app/services/model/model_config.py

4.4 集成、信号与运行时

  • backend/app/services/integrations/feishu_integration_service/
  • backend/app/services/integrations/feishu_outbox/service.py
  • backend/app/services/integrations/feishu_signal_pipeline/
  • backend/app/services/signal/signal_capture_service/
  • backend/app/services/signal/signal_source_orchestration/
  • backend/app/services/signal/signal_source_repair/
  • backend/app/services/signal/signal_planner/
  • backend/app/services/signal/draft_generator_service.py
  • backend/app/core/startup/
  • backend/app/utils/thread_context.py
  • 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
  • backend/app/models/training_pipeline.py
  • backend/app/models/mounted_ai_runtime.py
  • 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

4.6 结构归并结果

  • backend/app/services/ 根目录已目录化收敛，新增服务优先进入对应子包。
  • API canonical 入口优先使用 *_api/ 子包，不再优先引用顶层兼容壳。
  • 运行时业务动作归因优先走“对象/上下文绑定 -> SemanticContextPacket -> SemanticDecision -> gatekeeper”。
  • non-plan query.answer 现已在 AdaptiveRAG 内增加 Query Route Gateway：只消费上游单次结构化 query_profile/source_policy/effective_source_policy 与显式 hint，结合 ProjectOperatingContext 归一化产出 route_mode / decision_origin / reply_contract / probe_snapshot(contract audit) / execution_recipe，不再在运行时执行 internal/external probe 或 route memory 强拍板，再进入检索与回答主链。
  • query semantics 上游真源也已继续收口：PROMPT_RAG_QUERY_SEMANTICS + mixin_core_intent.py 现在只把 query_profile(needs_private_context, needs_freshness, confidence) 与 BusinessSemanticFrame 写回运行时，subject_focus / query_profile.referenced_objects 已从 production backend 移除，不再参与 route snapshot、session scope continuity 或任何 read-side 分流。
  • WorkflowSemanticPlanner 冷启动 bundle 现已补上四挡 interaction_boundary 合同：decision_schema.py 定义 InteractionBoundaryPacket / AnswerControlDecision / SelfReviewResult，planner 会把显式 status / recommendation / draft / execute 边界与识别出的 workflow_plans 合成 answer_control，并把 requested_level / forbidden_levels / effective_level / blocked_workflows 落进 bundle diagnostics。对“只给建议/先别出草稿”这类 recommendation-only 问法，planner 允许识别到底层 signal_source_flow，但最终会按 boundary 把 bundle 降回 query_flow，避免误滑到 draft_pending_confirm；旧的无 boundary bundle 仍走兼容透传，不会压坏既有写链路。
  • AdaptiveRAG 与 AI PMO 主链里几个最容易回流硬语义的入口也已继续收口：project progress fast answer 只按结构化 interaction_level / goal_kind / resource_role / expected_answer_shape 决定是否绕开 fast path；casual chat 直答只消费 message_intent=casual_chat 的结构化结果；typed executor 对 project_lookup 直答只认结构化 message_intent=project_lookup(_question) + query_semantics，不再被 项目列表/项目清单/项目#123 这类词面带偏；signal 数量和“先分析再入库”这类分析模式也只读 requested_count / analysis_mode / operation_intent_contract，不再从自然语言里额外解析“3个信号/先分析后入库”。
  • internal config 这条 read-side 也继续结构化了：AdaptiveRAGTargetResolutionMixin 不再把泛化 resource_role=config 自动映射成 config:system，必须依赖显式 object_binding 区分 config:model_routing 与 config:mcp_template_center；对应的 deep guard 直答也拆成模型路由和 MCP 配置两个子口径。
  • 项目化影响判断不再必须依赖外部实时抓取才能保住“直接影响”那一行：AdaptiveRAGFastAnswerProjectMainMixin 现在会根据 goal_kind=impact_judgment / expected_answer_shape=impact_chain 保留结构化 external_impact 渲染，避免 WMS/税控/评论流这类高频影响问法退回普通项目周报。
  • AdaptiveRAG 的 follow-up clarification 现在也继续往结构化真源收：mixin_followup_anchor.py 不再在 runtime 用“第几条/标签名/最近回复 match_text”去消费 pending_clarification；query_route_selection / followup_anchor_selection 都先经过统一结构化澄清解析，再把选中的 source_policy_hint / query_semantics_overrides / selected_qa_id 透回 mixin_answer_mainline.py。这样用户说“内部那个 / 第二条”后，主链会带着明确的 route override 或 anchor QA id 继续，不会再把原问题拿回去后靠最近回复词面重猜。
  • internal Operation Contract / Target Resolver 已按 business-frame-first 收口：mixin_target_resolution.py 现在只消费 goal_kind / target_scope / resource_role / project_binding / object_binding / expected_answer_shape 来判定 project / task / signal / config / feature / doc / user 绑定，不再让 subject_focus / referenced_objects 这类 coarse 字段单独拍板内部对象类型。
  • internal object/domain clarify 继续往下一层时，当前由 backend/app/services/adaptive_rag_service/internal_domain_catalog.py 提供 catalog 真源；catalog 已覆盖 project / task / signal / config / feature / doc / user 这批 internal domain。mixin_target_resolution.py 会在只确认大域（如 resource_role=config 或 resource_role=doc）但尚未唯一落到子对象时生成 candidate_summary，mixin_answer_payload.py / mixin_answer_precheck.py / mixin_followup_anchor.py 再把它转成 internal_target_selection pending clarification，并在 follow-up 后回填 query_semantics_overrides 继续主链。
  • AdaptiveRAG read-side 那批旧 compatibility consumer 也已一起收口：shared_utils.py 统一提供 BusinessSemanticFrame -> structured entity/project binding 归一化，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 现在只看这层结构化结果决定 project / task / signal / config / feature / doc / user 的快答、检索、deep guard 与 internal query plan，不再读取 subject_focus / referenced_objects 做二次业务分流。
  • ProjectOperatingContext 当前由 project_operating_context_builder.py 统一组装：最小范围固定为“当前项目 + 当前仓库摘要 + 页面/线程锚点”；world model 建完后会回填 resolved_project_id / repo_scope，再供 Query Route Gateway、mixin_project_fit_brief.py 与 answer payload 消费。
  • analysis_packet 现作为单独的 analysis layer 增量接到问答主链：analysis_packets.py 定义 project_fit_analysis / external_impact_analysis / internal_explain_analysis / followup_explain_analysis 这组 typed packet，analysis_packet_builder.py 只消费 ProjectOperatingContext / ExecutionRecipe / fit_brief / external_recommendation / InternalContextPacket / clarification 等 runtime truth 组包，不从回答正文反推。当前 richer packet 会把 current_subject / candidate_position / rejected_position / reason_chain 这类对象级分析字段显式落盘，避免 presenter 再用泛句补戏；共享 richer project snapshot 由 analysis_project_snapshot_loader.py 统一补 tasks/signals + description/summary + analysis_object_refs，供 AdaptiveRAG payload 和 Feishu presenter 复用。最新 snapshot loader 已 fail-closed：没有真实结构锚点时，不再从 task/signal 标题描述推 fit_candidate_* / fit_rejected_* / primary_* 关系，也不再生成 task_signal_scores / signal_task_links 这类 token-overlap 产物；builder 主路径只消费显式 object ref、精确文本绑定和唯一候选这三类非语义结构证据。
  • analysis_packet_builder.py 里原来那层“工程任务/信号源占位/展示层”词面 second-guess 已继续收掉：generic fallback、direct-match generic 分支和 internal explain target fallback 现在都不再靠 _looks_like_engineering_task / _looks_like_signal_placeholder / _task_presentation_hint / token-overlap / partial-name match 去反驳上游对象关系；没有显式 ref 时只能诚实降级，最多允许“唯一候选”这种纯结构兜底。
  • internal query.answer 的下一阶段基线已经确认：Query Route Gateway 之后不再直接靠快答分支拍板，而是统一进入 Operation Contract -> Target Resolver -> Query DSL Plan -> InternalContextPacket -> 白名单受控执行器 -> semantic facts 优先 -> verifier 主链；InternalContextPacket 由 backend/app/services/adaptive_rag_service/internal_query_context.py 定义，并作为 internal executor / verifier / runtime summary 的运行时单一真源；相关设计规格见 docs/superpowers/specs/2026-04-15-internal-query-dsl-plan-design.md 与 docs/superpowers/specs/2026-04-15-semantic-facts-read-model-design.md。
  • internal 主链现已补上 packet 预检：mixin_answer_mainline.py 在组完 InternalContextPacket 后，会先拦截 missing packet / missing operation contract / target clarify / missing query plan contract 这类上下文不完整场景，再决定是否进入 deterministic fast path、internal model-config fast path、GLM semantic fast path 或 retrieval；query_semantics 对 operation_contract / target_resolution / query_plan 的镜像也已收口到单点兼容写回。
  • external query.answer 已完成 second-pass 收口：Query Route Gateway 之后统一进入 backend/app/services/external_query_service/，按 ProjectFitBrief -> External Query Planner -> External Query Gateway -> External Provider Registry -> MCP adapter 优先 -> bounded fallback live search -> external answer verifier -> ExternalContextPacket -> ExternalAnswerPresenter 执行；planner 会显式消费 fit_brief_summary / project_scope_hint / recommendation_goal / project_object_anchors / signal_source_objectives，其中 formal object anchors 优先来自 ProjectFitBrief.signal_source_anchors，项目任务目标锚点来自 ProjectFitBrief.signal_source_objectives，不再拿 feature capability 名称或固定类别模板直接冒充 formal project object；payload 会拆出 fit_brief / external_recommendation，AdaptiveRAG external probe、freshness fetch 与 external route retrieval 已接到这条链上，并对 external sources 执行 fail-closed 过滤。当前 planner 还补了 recommendation query seed guard：命中“推荐外部信号源”问法时，会优先把当前项目任务目标和 formal anchor 驱动的 query 排到 search_queries 前面，避免 structured planner 用 industry best practices / external data sources 这类泛化词覆盖掉更贴当前项目的 seed query；同时 interaction_level=recommendation 会从统一语义规划层经 answer_control/source_policy_hint 透传到 ExternalQueryPlan，recommendation 分支不再由 presenter 本地 cue list 单独拍板。presenter.py 使用独立 external-only prompt 家族，并强制区分 verifier_blocked / no_relevant_results / retrieval_failed / indirect_only，不再回流 industry_trend/external_trend scene prompt；对 recommendation ask，presenter 现在会先生成 SignalSourceRecommendationPacket(candidates + caveat)，再渲染成业务中文的 1/2/3 候选建议，确保输出真的贴当前项目对象，而不是只靠自由文本兜一句“先看上游输入”。同时仍保留 overclaim guard：当结构化候选或文本里出现百分比、已确认、无需验证等高确定性措辞时，会 fail-closed 回退到 customer-safe candidate 文案。相关设计规格见 docs/superpowers/specs/2026-04-15-external-query-gateway-design.md。
  • non-plan recommendation -> signal-source write 当前已补齐结构 carry-over：external recommendation 不再只返回文本，SignalSourceRecommendationPacket 里的 candidate set 绑定会经 reply_anchor_qa_context + action_contract 一路沉到 signal_source.onboard 执行结果，并在 follow-up 把推荐的写进系统 / 确认入库 时由 mixin_followup_project_signal_resume.py 重建回 operation_intent_contract(candidate_set_binding/candidate_refs/project_binding)。signal_source.onboard 直写链会在 signal 已 materialize 且项目关联成功后把业务结果视为 succeeded，同时仅通过 post_process_status / signal_source_workflow.status 暴露后续 onboarding/manual 状态；ai_pmo_reply_renderer.py 也会把批量 signal source 直写回执渲染成自然业务中文，而不是 requirement draft 或 pending-manual 漂移文案。
  • QA session detail 持久化现已补齐 routing_snapshot.response_payload：mixin_core_intent.py 在写 QARecord 时会把 project_operating_context / execution_recipe / fit_brief / external_recommendation / analysis_packet / handoff_mode / can_enter_plan / recommended_next_step 一并归档，mixin_qa_session_list_ops_p1.py 再将其投影给 AI Steward 历史回放，避免即时回答与 session detail 出现两套合同。
  • Feishu QA 呈现现与共享 analysis packet 对齐：mixin_receive_routing.py 会先基于 project_operating_context 读取当前项目实体快照，再调用 analysis_packet_builder.py 生成共享 analysis_packet，之后才进入“受控改写 -> blocked-entity 校验 -> deterministic fallback”的渠道 presenter。运行时会同时校验 fixed opener、标签摘要、内部 packet 术语（如 analysis_packet / missing_mapping / next_step / focus_objects / reason_chain）以及未入选实体泄漏；若任一条件不满足，则 fail-closed 回退到 packet-based deterministic 文本。同时保留 draft_pending_confirm / requirement_plan_followup / pending_manual 优先走 action card，避免把飞书回归修成单纯文案 bypass。最新 qa_direct 还新增了一层中文化 presentation policy：内部现状问题若原始 answer 泄出 Project database / signal_total / 当前盘面 / 建议动作 / External Freshness Guard 这类英文或内部术语，会优先回退成共享 packet 文本，并最多只追加一行中文来源说明；外部信号源 recommendation ask 若已有推荐正文，则优先直出推荐正文，再补同样的中文来源说明；对 sparse project-fit 这类 packet，deterministic fallback 也会转成人话解释，不再原样暴露 packet 缺口字段。
  • Feishu project.create 预填与 QA fallback 现继续去 lexical 化：project create 相关字段不再由 _extract_project_scope / _extract_project_intent_fields / _is_contextual_project_request / heuristic_* 之类 helper 从用户原话里扣词，而统一消费 _extract_project_prefill() 的结构化 suggested_name / suggested_description / suggested_scope；QA fallback 也不再用 _pick_feishu_entity_by_keywords 按“摘要/拉取/推送”等关键词挑实体，改成只按共享 packet/select entity 的结构顺序兜底。
  • analysis_packet_builder.py 的 sparse project-fit fallback 也往结构化真源继续收：当前如果 preferred/rejected 对象缺失，会直接按“结构对象缺失”降级，不再靠“解释层/当前主链”这类占位词表决定 sparse fallback 分支。
  • unified handoff 当前补有最小 rollback guard：shared_utils.py 提供 env flag 解析，mixin_query_route_gateway.py / mixin_answer_retrieval.py / mixin_answer_payload.py 分别支持独立关闭 execution_recipe 增强、fit_brief + external_recommendation 构建、以及默认 offer_after_answer 呈现，不需要回退 ingress/context 真源。
  • analysis_packet 当前也带独立 rollout guard：PMFLOW_ENABLE_ANALYSIS_PACKET_FAMILY=0 时，AdaptiveRAG payload / session replay / Feishu presenter 会回退到旧 handoff truth + 旧 presenter，避免影响 project_operating_context / execution_recipe / fit_brief / external_recommendation 真源。
  • query.answer 的客户可见回答展示也已确认独立基线：运行时证据必须拆成 customer_safe 与 admin_debug 双视图，客户侧统一消费中文化 display_label，禁止直接暴露 raw_source_label、机器来源或内部术语；external answer presenter 的 prompt 输入也必须保持 external-only，仅允许消费经 verifier 通过的外部证据摘要与计划摘要；相关设计规格见 docs/superpowers/specs/2026-04-15-answer-presentation-policy-design.md。
  • 下一阶段的全量业务结构化基线已确认：在 InteractionBoundaryPacket / AnswerControlDecision 之上继续引入 BusinessSemanticFrame、AnswerShapeContract、RecommendationCandidateSet、ClarificationDelta / CorrectionDelta 与 OperationIntentContract，把 recommendation、clarification/correction、casual chat、non-planmode direct signal-source write 统一收口到同一语义真源；并以 58 条广覆盖业务语义矩阵作为完整回归基线、以 docs/superpowers/specs/2026-04-20-business-golden20-refresh.md 里的 20 条当前项目池黄金案例作为日常 P0/P1 spot check 集。
  • semantic_fact_service 已升级为统一基线：semantic_facts / semantic_fact_extraction_runs 读模型、ORM 提交钩子自动收集对象变更并 upsert ingest_events(channel=semantic_fact_extract)、统一 worker 抽取/失活，以及 internal query 的 facts-first 主路径。
  • semantic facts 自动抽取覆盖 project / task / signal / document / user / requirement(charter) / release / review 八类业务对象；manual retry 与 backfill 走同一队列、同一 worker，不再开旁路。
  • MCP 模板接入中心已接入 backend/app/api/mcp_api/ + backend/app/services/mcp_config/：租户内统一保存 MCP 模板 catalog、server 配置 bundle、命令预览、validate 结果、runtime probe 与 pending_local_apply / user_confirmed / not_required 状态；backend_direct 模板既支持远程 streamable_http（如 microsoft_learn），也支持后端内建 backend_adapter runtime（如 duckduckgo），本地 stdio 模板只输出 Local Bridge/兼容 host 接入说明，服务端不直写客户机器 ~/.codex/config.toml。
  • query_route_memories 作为独立路由记忆表，承接 QARecord 的 route audit、feedback 回灌和离线评估样本，不复用原 answer-quality 资产表。
  • query_route_memories 现已补 manager-only 只读治理入口：backend/app/api/rag_api/routes_route_governance.py + mixin_query_route_governance.py 负责 /rag/query-route-governance/summary|items|items/{id}，统一暴露 reply_contract / probe_snapshot / query_profile / feedback_outcome 审计快照，但 v1 不做在线自动调路由。
  • backend/tests/test_runtime_structured_semantics_contract.py 与 backend/tests/test_feishu_pipeline_queue_contract.py 共同守门 runtime 结构化语义收口，锁定飞书入口、signal capture、reply/runtime routing 不得回流旧词法拍板 helper。
  • backend/tests/test_external_query_planner.py 现已补进 external fallback 回归，锁定 planner fallback 只能产出 generic external plan，不得再根据 weather/news/public_model/... 之类对象映射在运行时硬分 query_kind。

5. 前端库存

5.1 页面分组

  • frontend/src/pages/inbox/
  • frontend/src/pages/ai-steward/
  • frontend/src/pages/scheduler-center/
  • frontend/src/pages/project-board/
  • frontend/src/pages/projects/
  • frontend/src/pages/users/
  • frontend/src/pages/recipes/
  • frontend/src/pages/feishu-config/
  • frontend/src/pages/ai-config/
  • frontend/src/pages/model-routing-config/
  • frontend/src/pages/ai-config/mcp-config/
  • frontend/src/pages/query-route-governance/
  • frontend/src/pages/task-brief-center/
  • frontend/src/pages/task-brief-runs/
  • frontend/src/pages/task-brief-template/
  • frontend/src/pages/charter-detail/
  • frontend/src/pages/contract-sync-board/
  • frontend/src/pages/dashboard/
  • 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/account-settings/
  • frontend/src/features/personal-space/components/
  • frontend/src/pages/skill-tasks/
  • frontend/src/pages/skills/
  • frontend/src/pages/user-profile/
  • frontend/src/pages/user-skills/
  • frontend/src/pages/workload-detail/
  • frontend/src/pages/workloads/

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。P0 公共壳冻结后，大模块 route 归属为：/space 归 Space lane，/project-launch 是启动层入口，/pmflow-os 与 /command-center / /change-review / /execution-bridge / /release-growth 归 Main Flow lane，/me 归 Account Settings lane，/settings 当前仅为 reserved route、尚未实现，新增必须由 Shell / Integration owner 串行处理。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/account-settings/ 作为 Account Settings 产品域，通过 /me 提供个人资料、默认语言、AI 回答深度、证据展示偏好、待确认/执行回写/发布门禁/失败提醒通知偏好和账户操作入口；该域通过 frontend/src/api/accountSettings.ts 建立前端合同，有 token 时优先调用已挂入 backend/app/api/router.py 的 backend/app/api/account_settings_api/ GET /account-settings/me / PUT /account-settings/me 同步当前账号偏好，后端不可用时明确回落本机暂存，不修改 OAuth/JWT/auth core。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 入口并委托 Account Settings 域渲染设置页；正式应用壳移动端底部导航统一由 frontend/src/features/pmflow-os/components/MobileBottomNav.tsx 承接，固定为 空间 / 指挥台 / 待确认 / 动态 / 我的，其中 动态 当前仍是 /command-center 占位。/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/PersonalSpacePage.tsx 是空间首页视图层，frontend/src/api/space.ts 是空间工作面只读聚合 API：从 projects summary、PMFlow OS truth-state 与 execution-summary 生成继续推进、待确认、发布关注、执行中 / AI 正在推进、暂存想法、草案箱、最近项目摘要；Space P3 的 releaseAttention 优先消费 truth-state.releases 中由 release validation run 投影出的 release 状态与检查项，把“发布验证阻塞 / 发布验证待确认”显示到 /space，没有发布验证投影时才回落到 execution-summary.releaseGate 的发布候选或发布门禁阻塞；发布验证缺失时显示明确空态，不虚构验证结果。项目主动作进入 /pmflow-os?projectId=<id>，待确认项进入 /change-review?projectId=<id>&changeSetId=<id>，发布关注项进入 /release-growth?projectId=<id>，执行中项进入 /execution-bridge?projectId=<id>；暂存想法后端只读聚合尚未接入时只显示 empty/warning，不使用 mock 数据冒充真实内容；移动端为空间首页独立 App 布局，不直接压缩桌面卡片，并保留最近项目区块；frontend/src/pages/PersonalSpacePage.tsx 是薄入口。该域只表达个人空间和主流程导航，不做团队空间强切换、企业组织管理、Project Memory 写入、ChangeSet 状态写入、ProgressEvent 写入、ReleaseValidationRun 写入或发布执行。
  • 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/account-settings/AccountSettingsPanel.tsx 是 /me 设置页实现：桌面端为个人资料摘要 + 分区设置面板，移动端为分组列表 + MobileBottomSheet 编辑；当前覆盖个人资料、默认语言、AI 回答深度、证据展示偏好、待确认、执行回写、发布门禁和失败提醒通知偏好，并在通知偏好区展示页面内提醒消费说明。frontend/src/api/accountSettings.ts 是前端合同层；有 token 时优先调用 backend/app/api/account_settings_api/，失败时回落浏览器本机暂存；P2 新增 shouldShowAccountNotification 与 getAccountNotificationConsumption，将四类通知偏好映射为本地 UI 的待确认、Execution Bridge、Release/Growth 和失败提醒显示/静默状态；P3 新增 getReleaseGateNotificationPreference(settings, event)，把 Release/Growth 的 release_gate_* / release_validation_* 事件映射到 releaseGate 偏好，把 failed_event 映射到 failureAlert 偏好，并返回 inAppEnabled / desktopPreference / emailDigestPreference 供后续 Main Flow 页面消费。该合同不代表邮件、桌面推送或系统通知中心已接入。backend/app/schemas/account_settings.py 定义账号偏好合同，backend/app/services/account_settings_service.py 当前复用既有 integrations 表按 tenant_id + user_id 保存 account_settings_preferences 配置包，backend/app/api/router.py 已挂载该 API；未改用户表、OAuth/JWT/auth core 或 PMFlow OS truth store。
  • 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 与 GET /pmflow-os/projects/{project_id}/execution-summary，真实模式下项目内 message、proposed_items extraction、ChangeItem accept/edit/defer、ChangeSet commit、Execution Handoff create/consume、execution progress writeback、release validation run create 与 release feedback ingest 均调用 /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/测试与回写状态页；ReleaseGrowthPage.tsx 真实模式读取 execution-summary.releaseGate、latestValidationRun 与 releaseSignals，从 branch、commit、PR、test、failed evidence 展示 可发布 / 阻塞 / 需要人工确认 / 缺少证据 判断、阻塞原因、下一步动作、发布验证记录和发布后 feedback/revenue/recommendation 信号，缺少发布后信号时显示 empty/warning，不执行发布命令、不展示 mock 发布结果；同时读取 Account notification preference helper，用 releaseGate 偏好控制发布门禁强调提醒，用 failureAlert 偏好控制失败强调提醒，偏好关闭时只静默提醒表达强度，不隐藏 release evidence、阻塞原因、审计状态、validation run 或 releaseSignals；静态发布/增长原型只保留在显式 demo 模式。A3 已接入后端 truth-state，C1 已接入真实 message/extraction/review 状态机，C2 已接入真实 ChangeSet commit，Phase D 已接入真实 execution-summary/dev-sync，D.2 已接入 POST /execution-handoffs 创建 PromptPackage + handoff_created progress event，P1 已接入 POST /execution-handoffs/{prompt_package_id}/consume 创建 handoff_consumed progress event 并把 execution status 投影为 coding，Release Growth P1 已接入 execution evidence gate，Release Validation P1 已接入 POST /release-validation-runs 创建 ReleaseValidationRun 快照，Release Feedback P1 已接入 POST /release-feedback-ingests 写入 FeedbackIngest 并生成 IterationRecommendation；当前仍不调用真实 AI 提取，不把 mock 当真实失败 fallback。ProjectMemoryPage.tsx 在真实模式下展示后端 truth_nodes + semantic_facts 的 projectMemory 投影，accepted/edited ChangeItem 只有 commit 成功后才进入 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，Change Review / commit 服务位于 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；C2 backend/frontend 已实现 POST /pmflow-os/change-sets/{change_set_id}/commit 与真实模式前端接入，默认 atomic，将 Requirement / Decision / Risk 写入 truth_nodes，将 Task 写入 truth_nodes(node_type='task') + tasks，高风险项强制 approval gate；D.2 已实现 POST /pmflow-os/projects/{project_id}/execution-handoffs，校验 task/repo project 边界，生成/复用 PromptPackage(package_kind='execution_handoff') 并写 ProgressEvent(event_type='handoff_created') 起点；P1 已实现 POST /pmflow-os/projects/{project_id}/execution-handoffs/{prompt_package_id}/consume，校验 execution handoff package 后更新 PromptPackage.package_payload.latest_handoff.handoff_state=consumed 并写 ProgressEvent(event_type='handoff_consumed', derived_task_status='coding')；Release Growth P1 在 ExecutionSummaryProjection.releaseGate 中从 ProgressEvent 推导发布门禁状态，失败事件 fail-closed 阻塞发布，无证据返回 empty/warning；Release Validation P1 新增 POST /pmflow-os/projects/{project_id}/release-validation-runs，复用现有 ReleaseValidationRun 模型固化当前 releaseGate 快照、人工决策、证据、阻塞原因和下一步动作，并在 releaseGate.latestValidationRun 返回最新记录；Release Feedback P1 新增 POST /pmflow-os/projects/{project_id}/release-feedback-ingests，复用现有 FeedbackIngest / IterationRecommendation，在 ExecutionSummaryProjection.releaseSignals 中返回真实发布后 feedback、revenue event 和 iteration recommendation 读模型；这些步骤都不直接执行本机命令、真实发布命令、外部支付或真实推送；ModelDecision / MetricSignal 在 C2 V1 仍 fail-closed。
  • 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
  • frontend/src/api/knowledgeGraph.ts
  • frontend/src/api/semanticFacts.ts
  • frontend/src/api/queryRouteGovernance.ts
  • frontend/src/api/mountedAi.ts
  • frontend/src/api/feedbackCenter.ts
  • frontend/src/api/sstc.ts
  • frontend/src/components/inbox/
  • frontend/src/components/sstc/
  • frontend/src/pages/scheduler-center/components/
  • frontend/src/pages/ai-steward/components/
  • frontend/src/lib/

5.3 前端结构边界

  • 页面级编排逻辑优先收敛到 pages/*/ 子目录。
  • API 调用统一走 frontend/src/api/，不在页面或组件内直接 fetch。
  • frontend/src/components/sstc/ 继续作为 SSTC 共享组件目录维护。
  • 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/治理后台语义。个人空间首页、新项目启动台和 Account Settings 同样是独立产品域：Space 只能通过 frontend/src/api/space.ts 做项目摘要、PMFlow OS truth-state / execution-summary 的只读聚合并跳回主流程；Project Launch 默认走真实 draft/confirm 创建链，只有显式 demo 参数才使用本地状态机；Account Settings 只管理个人资料、偏好和通知，不改 OAuth/JWT/auth core、PMFlow OS truth store、Project Memory、ChangeSet 或 Execution Bridge 写回。

6. 工具与运行库存

  • backend/scripts/repair_requirement_plan_history.py
  • scripts/start_model_probe.sh
  • scripts/model_probe.py
  • scripts/gen_task_brief.sh
  • scripts/check_contract_sync.sh
  • 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
  • 想看“模块都搬到哪里了、目录怎么分组”：看本文档
  • 想看“接口/数据流契约”：看 docs/architecture/API_CONTRACTS.md 与 docs/architecture/DATAFLOW.md