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

8.4 KiB
Raw Blame History

DATAFLOW

PMFlow AI Agent OS Runtime Flow

  1. User turns enter the product surface through POST /space/pmflow-ai/threads for the first message, POST /space/pmflow-ai/threads/{thread_id}/messages for continuation, or compatibility POST /space/ai-concierge/ask.
  2. The product API persists pmflow_ai_threads / pmflow_ai_messages as the user-visible transcript. Each assistant turn creates a durable pmflow_agent_runs execution row before answer synthesis. QA records are transcript/history only.
  3. PMFlowAgentRuntimeService creates the durable run first, then delegates execution to PMFlowAIAgentRunService.
  4. PMFlowAIAgentRunService first builds a GoalFrame, records the user goal, desired output, object-binding candidates, evidence requirements, success criteria and customer-safe boundaries, then asks the LLM Step Planner for one next action at a time.
  5. The planner can only choose tools from AGENT_TOOL_CONTRACTS, including inspect_space_collections, inspect_project_operating_state, external_search, saved-idea reads and pending-confirmation reads. It must not use old route plans, answer contracts or fixed business enums.
  6. Each selected tool writes observations into the observation ledger, then PMFlowAIAgentEvidenceNormalizer converts raw observations into source_quality, claim ledger entries, boundary ledger entries and gaps. Raw snippets/tool payloads are not valid final-answer material.
  7. PMFlowAIAgentStateCritic checks whether GoalFrame + Claim Ledger + Boundary Ledger + Gap Ledger satisfies the user goal. If not, it must state what is missing, whether another retry would change state, and whether to continue, narrow, ask the user or stop blocked.
  8. PMFlowAIAgentAnswerRuntime builds terminal state only from the ledgers and answer intent plan, then composes the natural customer answer. The quality gate blocks internal terms, fixed templates, empty answers and missing lead claim/boundary.
  9. PMFlowAgentRuntimeService projects those real goal/planner/tool/normalizer/critic/answer steps into pmflow_agent_steps, pmflow_agent_observations, pmflow_agent_artifacts, pmflow_agent_verifications and pmflow_agent_memories.
  10. The thread API returns a customer-safe projection: thread_id, continuous messages[], and the latest assistant message with content, work_log, inline artifacts, actions and confirmations.
  11. PMFlowAIWorkspace at /space/pmflow-ai renders the durable thread list, continuous transcript and per-message work log. It must not render raw run ids, step ids, verification target refs or English status labels as the default user experience.

PMFlow AI Compatibility Flow

  1. POST /space/ai-concierge/ask remains for old clients, but it calls the same Agent OS runtime and returns the same projection.
  2. Old Turn Runtime, EvidenceToolRegistry, CustomerAnswerPresentationService and Operating Runtime modules may be used as tool/rendering/compatibility assets.
  3. They must not decide the main run, override final answer unconditionally, or expose internal verification labels such as project_object_required_for_world_state.

Signal Planner Flow (Post-Commit Async)

  1. AIPMOKernelService creates signal (signal.create) in transaction.
  2. Transaction commits.
  3. Background task triggers SignalPlannerService.analyze(signal_id, tenant_id, ...).
  4. Planner service opens isolated AsyncSessionLocal and loads context:
    • signal content/project context
    • project members (user_projects -> users -> user_workloads -> user_skill_bindings -> skill_tags)
  5. Planner calls llm_service.generate_structured_object(function_name="signal_planner_analyze") with hard wait timeout (25s).
  6. Structured success:
    • SignalStrategicAnalysisService.merge_and_save(...)
    • update signals.planner_status=completed
    • write planner payload into strategic_analysis.ai_planner
  7. Structured invalid / timeout fallback:
    • build degraded planner payload (fallback_mode=true)
    • still merge_and_save(...) and mark signals.planner_status=completed
  8. Hard failure (DB write / unexpected exception):
    • SignalStrategicAnalysisService.mark_failed(...)
    • update signals.planner_status=failed
    • try enqueue compensate reply via FeishuOutboxService.enqueue(...)

Model Routing / Route Lab Flow

  1. Hidden frontend ModelRoutingConfigPage at /platform/route-lab reads function-level routing diagnostics from /model-routing/functions/{function_name}.
  2. The visible UI is read-only: platform operators can inspect rule source, tier, recent execution and historical override traces, but cannot save function-level overrides from the page.
  3. Backend PUT /model-routing/functions/{function_name} remains a platform-protected compatibility/internal write API and persists overrides into integrations(type='model_routing').
  4. LLMService resolves function-level override at runtime before default control-plane rules.

Query Route Gateway Flow

  1. AIPMOKernelService.process_ingress() 先完成 plan_mode gate；命中 reply/thread、work_item_id、active requirement context、draft/workspace lock 时继续留在 requirement/draft 主链。
    • 若已绑定 active requirement context 且用户显式说 退出需求模式，必须先把当前带 active draft 的 live requirement topic 挂起，再回到普通 query.answer；同 scope 下后续 idle query topic 不得抢走这次绑定。
  2. 非 plan_mode 的 query.answer 进入 TypedExecutor._execute_query_intent()，在调用 AdaptiveRAG.answer_question() 前先执行 preview_query_route_decision(...)。
  3. AdaptiveRAGQueryRouteGatewayMixin 产出单次结构化 query_profile（needs_private_context / needs_freshness / referenced_objects），并分别运行：
    • InternalProbe：config_hit_count / private_object_hit_count / private_scope_hit / vector_top1_score / vector_topk_support / graph_fact_hit_count
    • ExternalProbe：freshness_required / trusted_domain_hit_count / answerable_page_hit_count / cross_source_agreement / external_entity_hit
  4. Gateway 结合 query_route_memories 的相似样本先验，输出 route_mode / effective_source_policy / decision_origin / reply_contract / probe_snapshot。
  5. 若 route_mode=internal，内部只读查询必须先生成 Query DSL Plan：统一收口 query_type=existence/count/list/status/explain/diagnose/compare/unknown、entity_type、answer_contract、filters、scope 与 retrieval_policy；协议短回复、模式控制、执行动作必须在此之前就被 gate 掉，不得混入 DSL 规划。
  6. Bounded Executor 只按白名单模板执行内部查询：
    • 优先查 semantic_facts
    • facts 不足时再做 db/graph/doc/config 的受控 fallback retrieval
    • 全程自动绑定 tenant_id
    • 不接收自由 SQL
  7. Answer Verifier 在出站前检查“问法合同、证据合同、来源合同”是否一致；若发现 existence/status/compare 被答成 total count、或证据与结果不符，必须重试或显式失败。
  8. AdaptiveRAG.answer_question() 只消费已经收口好的 route 决策和对应结果：internal 只走受控内部查询主链；external 统一走 External Query Planner -> External Query Gateway -> External Provider Registry -> MCP adapter 优先（当前已接通 Microsoft Learn backend-direct runtime）-> bounded fallback live search -> external answer verifier -> ExternalContextPacket -> ExternalAnswerPresenter，禁止再直接混入内部检索结果，也禁止回流旧的 industry_trend/external_trend scene prompt；uncertain 仅允许 external-first 或 clarification。
  9. external presenter 只读取 external-only 输入：
    • question
    • plan summary
    • verified external evidence
    • source summaries 若 verifier 未通过或 evidence 为空，则直接返回“证据不足/需澄清”，不得混入 system_snapshot / user_snapshot / project_context / internal retrieval 补答案。
  10. 回答完成后：
  • QARecord.routing_snapshot、citations、sources_used 继续落盘
  • query_route_memories 追加或更新该次样本
  • QAFeedback / FeedbackCenterRecord 后续会把 route feedback 回写到 query_route_memories.feedback_outcome

Task Brief Flow

  1. Frontend chooses template / trigger generate.
  2. Backend task_brief_service stores template and run records in integrations(type='task_briefs').
  3. Generation run writes summary + artifact path.
  4. /task-briefs/center aggregates latest generated cards for sidebar center.