# 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 强拍板，再进入检索与回答主链。 - 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/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`