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

16 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/INBOX_INLINE_OPS_3_PHASE_CHECKLIST.md：消息台内联操作执行清单
  • docs/architecture/MASTER_CONTRACT.md：跨栈主契约
  • docs/architecture/CODE_REFERENCE_INDEX.md：新增代码参考入口与高频代码索引
  • docs/architecture/RUNTIME_GUARDRAILS.md：运行边界、守门规则与已知运行假设
  • docs/architecture/API_CONTRACTS.md：接口/Schema 契约
  • docs/architecture/DATAFLOW.md：主链与数据流说明
  • docs/architecture/TASK_BRIEF_TEMPLATE.md：任务包模板
  • 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/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/

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/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 强拍板，再进入检索与回答主链。
  • ProjectOperatingContext 当前由 project_operating_context_builder.py 统一组装：最小范围固定为“当前项目 + 当前仓库摘要 + 页面/线程锚点”；world model 建完后会回填 resolved_project_id / repo_scope，再供 Query Route Gateway、mixin_project_fit_brief.py 与 answer payload 消费。
  • 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，其中 formal object anchors 现优先来自 ProjectFitBrief.signal_source_anchors，不再拿 feature capability 名称直接冒充 formal project object；payload 会拆出 fit_brief / external_recommendation，AdaptiveRAG external probe、freshness fetch 与 external route retrieval 已接到这条链上，并对 external sources 执行 fail-closed 过滤；当前 presenter.py 使用独立 external-only prompt 家族，并强制区分 verifier_blocked / no_relevant_results / retrieval_failed / indirect_only，不再回流 industry_trend/external_trend scene prompt；相关设计规格见 docs/superpowers/specs/2026-04-15-external-query-gateway-design.md。
  • QA session detail 持久化现已补齐 routing_snapshot.response_payload：mixin_core_intent.py 在写 QARecord 时会把 project_operating_context / execution_recipe / fit_brief / external_recommendation / handoff_mode / can_enter_plan / recommended_next_step 一并归档，mixin_qa_session_list_ops_p1.py 再将其投影给 AI Steward 历史回放，避免即时回答与 session detail 出现两套合同。
  • Feishu QA 呈现现与同一份 handoff payload 对齐：mixin_receive_routing.py 会先基于 project_operating_context 读取当前项目实体快照，再走“两段式 presenter”：第一段用结构化 analysis plan 只挑 1-2 个当前项目实体并写清 conclusion / focus_entities / missing_mapping / next_step；第二段才允许自然化改写最终 qa_direct 文本。运行时会同时校验 fixed opener、标签摘要以及未入选实体泄漏；若任一条件不满足，则 fail-closed 回退到 analysis-plan deterministic 文本。同时保留 draft_pending_confirm / requirement_plan_followup / pending_manual 优先走 action card，避免把飞书回归修成单纯文案 bypass。
  • 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 真源。
  • 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。
  • 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/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/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/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、队列、对象表与详情抽屉。

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

7. 维护建议

  • 想看“现在怎么跑、边界怎么定”：先看 AGENTS.md，再看 CLAUDE.md
  • 想看“模块都搬到哪里了、目录怎么分组”：看本文档
  • 想看“接口/数据流契约”：看 docs/architecture/API_CONTRACTS.md 与 docs/architecture/DATAFLOW.md