177 lines
10 KiB
Markdown
177 lines
10 KiB
Markdown
# 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/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/mixin_query_route_gateway.py`
|
||
- `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，归一化产出 `route_mode / decision_origin / reply_contract / probe_snapshot(contract audit)`，不再在运行时执行 internal/external probe 或 route memory 强拍板，再进入检索与回答主链。
|
||
- internal `query.answer` 的下一阶段基线已经确认：`Query Route Gateway` 之后不再直接靠快答分支拍板，而是统一进入 `Operation Contract -> Target Resolver -> Query DSL Plan -> 白名单受控执行器 -> semantic facts 优先 -> verifier` 主链；相关设计规格见 `docs/superpowers/specs/2026-04-15-internal-query-dsl-plan-design.md` 与 `docs/superpowers/specs/2026-04-15-semantic-facts-read-model-design.md`。
|
||
- external `query.answer` 已完成 first-pass 收口：`Query Route Gateway` 之后统一进入 `backend/app/services/external_query_service/`，按 `External Query Planner -> External Query Gateway -> External Provider Registry -> MCP adapter 优先 -> bounded fallback live search -> external answer verifier` 执行；AdaptiveRAG external probe、freshness fetch 与 external route retrieval 已接到这条链上，并对 external sources 执行 fail-closed 过滤；相关设计规格见 `docs/superpowers/specs/2026-04-15-external-query-gateway-design.md`。
|
||
- `query.answer` 的客户可见回答展示也已确认独立基线：运行时证据必须拆成 `customer_safe` 与 `admin_debug` 双视图，客户侧统一消费中文化 `display_label`，禁止直接暴露 `raw_source_label`、机器来源或内部术语；相关设计规格见 `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` 状态；远程 `streamable_http` 模板可由 PMFlow 后端直连，本地 `stdio` 模板只输出 Local Bridge/兼容 host 接入说明，服务端不直写客户机器 `~/.codex/config.toml`。
|
||
- `query_route_memories` 作为独立路由记忆表，承接 `QARecord` 的 route audit、feedback 回灌和离线评估样本，不复用原 answer-quality 资产表。
|
||
- `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/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/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/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 Config -> Governance Tools` 现新增 `/ai-config/mcp-config` 与 `/ai-config/semantic-facts-board` 入口；两类治理页都只对 `BOSS/ADMIN` 开放。MCP 页负责模板化配置、后端直连/Local Bridge 状态展示、runtime probe、命令预览与本机确认；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`
|