PMFlow/CLAUDE.md

# PMFlow 项目结构说明（CLAUDE.md）

## 1. Agent 入口文件（你关心的“进项目先读什么”）
- `AGENTS.md`：Codex/Coding Agent 的主规则入口（优先级最高的项目级约束）
- `CLAUDE.md`：面向 Claude 风格的项目说明文档（补充背景）
- 建议：规则放 `AGENTS.md`，架构/目录说明放 `CLAUDE.md`
- 当前 AI 行为的系统宪章已在 `AGENTS.md` 中升级为“事实层 / 评审层 / 生成层 / 执行层”四层分治；所有新增 AI 业务默认按该宪章接入。`CLAUDE.md` 当前承载的是“架构说明 + 运行边界 + 目录库存”，不再假定自己只包含背景说明
- 新增执行约定：计划类需求一旦确认进入实现阶段，默认连续执行到“实现完成 + 验证完成 + 统一回复验收结果”；仅在明确阻塞、高风险冲突、context 限制或用户主动中断时才中途打断。
- 新增 bugfix 执行约定：缺陷修复/回归修复允许跨多个直接相关文件端到端完成，不再按文件数硬性拆分；但必须同时满足“改动范围围绕同一根因”“不夹带无关重构”“最终附带编译/测试验证”。大功能开发或结构性重构仍优先按子任务拆分。
- 新增发布约定：凡后端代码或数据库迁移发生改动，完成编译/测试后必须继续执行当前环境对应的热部署/重启/重载步骤，确认服务已加载新版本；若当前机器不是部署环境、缺少权限或不具备热部署条件，必须在结果中明确说明未执行原因与阻塞点，禁止默认省略。
- 新增前端快回路约定：`L1 微调` 默认走 `verify:login-fast` 或 focused screenshot，`L2 视觉逻辑` 默认走 `verify:login-responsive` 或 `capture:login:matrix`，出现 `context_compacted` 或超过 `8` 分钟仍未落代码时优先收口或切线程。
- 新增并行开发约定：多个 Codex 线程可以按 `Main Flow / Space / Account Settings / Shell Integration` 等大模块 lane 长期并行，但实际执行仍必须按 Packet 分派，声明 `module_lane / read_scope / write_scope / forbidden_paths / shared_files / cross_lane_inputs / cross_lane_outputs / base_ref`，默认使用 `codex/<packet_id>` 独立分支和独立 worktree；共享路由、导航、Provider、API base 和文档只能由 integration owner 统一合并。当前 P0 已冻结 route 归属：`/space` 归 Space，`/pmflow-os / /command-center / /change-review / /execution-bridge / /release-growth` 归 Main Flow，`/me` 归 Account Settings，`/settings` 仅为 reserved route、尚未实现。
- 下面各节中大量 `新增/更新/移除` 清单用于保留“当前架构库存”和关键入口索引，不等同于运行时主规范；行为约束与禁止项仍以 `AGENTS.md` 为准。

## 2. 项目定位
- 项目名：`PMFlow / Neural Sync`
- 形态：AI 原生项目管理系统（多租户 + 角色权限 + SSTC 工作流）
- 技术栈：
  - 后端：`FastAPI + SQLAlchemy + Alembic`
  - 前端：`React + TypeScript + Vite + Tailwind + Radix + React Query`

## 3. 顶层目录（精简版）
```text
AIProjectManger/
├── AGENTS.md                  # Agent 执行规则（建议优先维护）
├── CLAUDE.md                  # 当前架构说明与运行边界
├── start.sh / stop.sh         # 一键启动/停止入口
├── docker-compose*.yml        # 容器编排
├── mdproject/                 # 执行计划与任务清单（中文为主）
├── backend/                   # FastAPI 后端
├── frontend/                  # React 前端（后台工作台 + 登录页）
├── scripts/                   # 根目录运维脚本
└── docs/                      # 额外文档
```
- 详细架构库存已迁到 [`docs/architecture/ARCHITECTURE_INVENTORY.md`](/Users/yuuuu/Documents/AIProjectManger/docs/architecture/ARCHITECTURE_INVENTORY.md)。
- 本地预览端口现按职责拆分：`docker-compose.dev.yml` 的热更新开发前端固定占用 `5174`，`docker-compose.yml` 的静态生产预览前端默认改为 `5175`（可通过 `FRONTEND_PROD_PORT` 覆盖），避免再和 Vite live preview 抢端口。
- `docs/architecture/` 当前包含：`MASTER_CONTRACT.md`、`RUNTIME_GUARDRAILS.md`、`CODE_REFERENCE_INDEX.md`、`API_CONTRACTS.md`、`DATAFLOW.md`、`TASK_BRIEF_TEMPLATE.md`、`ARCHITECTURE_INVENTORY.md`
- `docs/PMFLOW_PRODUCT_BLUEPRINT.md` 是当前产品蓝图真源：定义 PMFlow 为“对话驱动的 AI 产品执行操作系统”，并锁定 `solo-first, team-ready`、项目真相层、待确认变更中心、执行桥、人机混编团队等产品方向。
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md` 是 PMFlow 产品推进执行标准：记录当前推进状态、Phase A-F/P8 下一步、单次任务范围、Codex 并行推进协议、完成后进度回写规则和新线程接续标准；继续产品推进前必须先读。P8 Main Flow 已把 reviewer routing 只读模型推进到 review request、reviewer decision 和 approval audit，后续剩余推荐是 Space/Account 消费面与 integration 收口到 personal attention。
- `docs/PMFLOW_UI_CONTRACT.md` 是 PMFlow UI 契约真源：锁定 Logo、浅色白底 + `#2463EB`、移动端固定底部导航、用户动作/AI 操作/系统状态/待确认视觉语法、核心功能 canonical 契约和当前前端一致性审计；后续原型图和代码化原型不得绕过该文档。
- `docs/superpowers/plans/` 保存实现计划，`docs/superpowers/specs/` 保存需求/方案规格，`docs/task_briefs/` 保存任务包产物与验收截图。
- 当前与“统一 AI handoff / 全量业务结构化”直接相关的设计规格包括：`docs/superpowers/specs/2026-04-17-unified-project-ai-handoff.md`、`docs/superpowers/specs/2026-04-19-interaction-boundary-four-level-contract-design.md`、`docs/superpowers/specs/2026-04-20-full-business-structuring-and-conversation-baseline-design.md` 与 `docs/superpowers/specs/2026-04-20-business-golden20-refresh.md`；它们分别对应统一入口与项目型 AI 方向、四挡 interaction boundary、全量业务结构化与 58 条广覆盖语义矩阵，以及面向当前真实项目池和 plan mode 主链的 20 条核心黄金案例。

## 4. 后端结构（`backend/`）
```text
backend/
├── app/
│   ├── api/                   # 路由层（canonical 入口优先使用 *_api/ 子包）
│   ├── core/                  # 配置、日志、启动与核心能力
│   ├── dependencies/          # 鉴权/租户等依赖注入
│   ├── middleware/            # 请求中间件
│   ├── models/                # SQLAlchemy 模型
│   ├── schemas/               # Pydantic 模型
│   ├── services/              # 业务服务（已目录化收敛）
│   ├── config/                # 配置与 prompt
│   └── utils/                 # 通用工具
├── alembic/                   # 数据库迁移真源
├── scripts/                   # 后端运维/修复脚本（含历史 backfill / requirement-plan 修复）
├── tests/                     # 后端回归测试
├── requirements.txt
└── Dockerfile
```
- 当前后端重点入口优先看：
  - `backend/app/api/` 下的 `*_api/` 子包与聚合 router
  - `backend/app/services/ai_pmo/`（AI PMO 主链、Mounted Runtime、semantic context）
  - `backend/app/services/ai_pmo/project_operating_context_builder.py` + `backend/app/schemas/project_operating_context.py`（统一 `ProjectOperatingContext / ProjectFitBrief / ExecutionRecipe` 合同；`/rag/ask`、`/ai-pmo/process-text`、kernel ingress 会先补当前项目/仓库/线程锚点，再给 Query Route Gateway、fit brief builder 与 answer payload 消费）
  - `backend/app/schemas/analysis_packets.py` + `backend/app/services/analysis_packet_builder.py` + `backend/app/services/analysis_project_snapshot_loader.py`（统一 analysis packet family：在 runtime truth 之上增量生成 `project_fit_analysis / external_impact_analysis / internal_explain_analysis / followup_explain_analysis`；当前 richer packet 已显式带 `current_subject / candidate_position / rejected_position / reason_chain` 这类对象级分析字段，供 Web、Feishu、QA session replay 的分析型展示消费；shared loader 统一补 richer `tasks/signals + description/summary + analysis_object_refs`，但 loader 现已 fail-closed，不再从 task/signal 标题描述推 task-signal 关系或 fit 对位；builder 主路径只吃显式 object ref、精确文本绑定和唯一候选这类非语义结构证据，不再使用 token-overlap、partial-match 或本地词表 second-guess 上游关系）
  - `backend/app/services/adaptive_rag_service/mixin_target_resolution.py`（internal target resolution 现已按 business-frame-first 收口：`goal_kind / target_scope / resource_role / project_binding / object_binding / expected_answer_shape` 先决定 project/task/signal/config/feature/doc/user 绑定；session follow-up project binding、internal domain clarify 与 semantic filter 都只看结构化 frame，不再靠 `subject_focus / referenced_objects` 这类 coarse 字段拍板对象）
  - `backend/app/services/adaptive_rag_service/shared_utils.py` + `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`（AdaptiveRAG read-side 兼容层现已统一改成 business-frame-first：deterministic query、fast answer、structured DB retrieval、deep guard、feature evidence 与 internal query plan 都只消费 `BusinessSemanticFrame / target_resolution / query_plan` 归一化后的结构，不再用 `subject_focus / referenced_objects` 做 project/task/signal/config/feature/doc/user 的二次分流）
  - `backend/app/config/ai_prompts.py` + `backend/app/services/adaptive_rag_service/mixin_core_intent.py` + `backend/app/services/adaptive_rag_service/mixin_query_route_gateway.py` + `backend/app/services/adaptive_rag_service/mixin_session_state.py`（query semantics 上游真源已同步切到 `business_frame + query_profile(needs_private_context, needs_freshness, confidence)`：production backend 不再生成、透传或持久化 `subject_focus / query_profile.referenced_objects`，route snapshot、follow-up scope continuity 与 session state 只保留 project/target/business-frame binding 这组结构）
  - `backend/app/services/adaptive_rag_service/`（只读问答主链；`mixin_query_route_gateway.py` 负责 non-plan `query.answer` 的 internal/external/uncertain 来源合同归一化、contract 审计与显式来源回复合同；`mixin_project_fit_brief.py` 负责 current-project customer-safe fit brief；`mixin_answer_retrieval.py` 现已把 `route_mode=external` 接到独立外部查询主链，并在 payload 暴露 `fit_brief / external_recommendation`；internal 路径新增 `internal_query_context.py` 里的 `InternalContextPacket` 作为 `Operation Contract -> Target Resolver -> Query DSL Plan -> 受控执行器 -> semantic facts 优先 -> verifier` 的运行时单一真源）
  - `backend/app/services/adaptive_rag_service/mixin_fast_answer_project_main.py` + `backend/app/services/ai_pmo/ai_pmo_typed_executor_execute/mixin_execute_query_project.py` + `backend/app/services/ai_pmo/ai_pmo_kernel/ai_pmo_typed_executor_mixins_parse.py`（runtime 去 lexical fallback 的关键入口：project progress fast answer bypass 现在只吃结构化 `interaction_level / goal_kind / resource_role / expected_answer_shape`；casual chat 直答只吃 `message_intent=casual_chat`；project lookup 直答只吃结构化 `message_intent=project_lookup(_question) + query_semantics`；signal 数量与 strict analysis 只吃结构化 `requested_count / analysis_mode / operation_intent_contract`，不再从自然语言里靠词表/正则判断）
  - `backend/app/services/adaptive_rag_service/mixin_target_resolution.py` + `backend/app/services/adaptive_rag_service/mixin_deep_guard_answer.py`（internal config 主链：`resource_role=config` 不再默认降成泛化 `config:system`；必须靠显式 `object_binding` 区分 `config:model_routing` 与 `config:mcp_template_center`，并分别走模型路由快答与 MCP 配置快答）
  - `backend/app/services/adaptive_rag_service/internal_domain_catalog.py` + `mixin_target_resolution.py` + `mixin_followup_anchor.py` + `mixin_answer_precheck.py` + `mixin_answer_payload.py`（internal object/domain clarify 主链：当前 catalog 已覆盖 `project / task / signal / config / feature / doc / user`；当 internal query 只确认到大域、还没唯一命中子对象时，先产出 `internal_target_selection` 澄清协议；follow-up 选项会回填 `query_semantics_overrides` 再继续受控检索，避免“澄清后继续复读旧答案”）
  - `backend/app/config/ai_prompts.py`（`PROMPT_RAG_QUERY_SEMANTICS` 现在明确要求 internal domain 问答把 `resource_role / object_binding` 打出来；模型配置示例绑定 `config:model_routing`，MCP 配置示例绑定 `config:mcp_template_center`，功能/文档问法则分别绑定 `resource_role=feature/doc`）
  - `backend/app/services/adaptive_rag_service/mixin_followup_anchor.py` + `mixin_answer_mainline.py`（follow-up 澄清恢复主链：`query_route_selection / followup_anchor_selection` 现在先走统一结构化澄清解析，再把 `source_policy_hint / query_semantics_overrides / selected_qa_id` 透回主链；用户澄清“第二条/内部那个”后，不再靠本地词面去猜上一轮回复或 option）
  - `backend/app/services/integrations/feishu_signal_pipeline/mixin_intent_gate_core.py` + `mixin_context_prefill_a.py` + `mixin_context_prefill_b.py` + `mixin_serialization.py`（Feishu `project.create` 预填链现在统一吃 `_extract_project_prefill()` 的结构化 `suggested_name / suggested_description / suggested_scope`，不再在 runtime 用 `_extract_project_scope / _extract_project_intent_fields / _is_contextual_project_request / heuristic_*` 之类词面 helper 扣项目字段）
  - `backend/app/api/rag_api/routes_route_governance.py`（manager-only 的 route/context 治理接口：`/rag/query-route-governance/summary|items|items/{id}`，只读暴露 `query_route_memories` 的 summary/list/detail）
  - `backend/app/services/external_query_service/`（external `query.answer` 主链：`External Query Planner -> External Query Gateway -> External Provider Registry -> MCP 优先 -> bounded fallback live search -> verifier -> ExternalContextPacket -> ExternalAnswerPresenter`；其中 `schemas.py` 负责结构化 plan/evidence/context packet，`presenter.py` 负责 external-only 回答生成。当前已额外支持“推荐外部信号源”问法：recommendation ask 的进入条件优先来自统一语义规划层透传到 `ExternalQueryPlan.interaction_level=recommendation` 的结构化层级，不再由 presenter 本地 cue list 拍板；命中后不再退回 `external_verifier_blocked` 拒答，而是先产出 `SignalSourceRecommendationPacket(candidates + caveat)`，再渲染成业务中文的 `top-N candidate + why`；recommendation 结果现在还会同步沉成可 carry-over 的 candidate set 绑定（`candidate_set_id + candidates + materialization payload`），供 reply-anchor follow-up 继续走 non-plan `signal_source.onboard` 直写链，不再默认 requirement draft；即使当前外部公开资料仍在校验，也只允许显式标成“推荐，不是已验证事实”，不能滑回架构腔或边界空话）
  - `backend/app/services/mcp_config/`（MCP 模板接入中心：catalog、bundle 持久化、后端直连 runtime probe / Microsoft Learn 检索桥接、Local Bridge 接入说明与本机确认状态）
  - `backend/app/services/semantic_fact_service/`（semantic facts 读模型、八类业务对象统一抽取/失活、ORM 提交钩子入队、治理看板查询）
  - `backend/app/api/semantic_facts_api/`（semantic facts 治理后台接口：overview / objects / detail / reextract / backfill）
  - `backend/app/api/mcp_api/`（MCP 模板接入中心后台接口：catalog / servers / validate / confirm-client-apply）
  - `backend/app/services/llm_service/`（显式 `routing_meta` 协议）
  - `backend/app/services/integrations/feishu_integration_service/`（飞书入站与卡片回调；`mixin_receive_routing.py` 的 `qa_direct` 现已支持 recommendation ask 直出推荐正文，并把原始 `Project database / signal_total / 当前盘面 / 建议动作 / External Freshness Guard` 这类内部/英文术语压成单行中文来源说明）
  - `backend/app/services/signal/`（信号接入、编排、planner、repair）
- 本轮新增的问答路由审计存储为 `backend/app/models/query_route_memory.py`，通过 `backend/alembic/versions/20260415_add_query_route_memories.py` 建表；只用于 route audit / feedback 回灌 / 离线评估，不做在线自动调参。
- 本轮新增的语义事实读模型为 `backend/app/models/semantic_fact.py` 与 `backend/app/models/semantic_fact_extraction_run.py`，通过 `backend/alembic/versions/20260415_add_semantic_facts.py` 建表；用于内部查询的 facts-first 命中与异步抽取审计。
- 本轮新增的外部查询 fallback、fit brief 与展示回归测试位于 `backend/tests/test_external_query_planner.py`、`backend/tests/test_mcp_external_query_bridge.py`、`backend/tests/test_internal_query_context_packet.py` 与 `backend/tests/test_adaptive_rag_mainline_contract.py`；它们一起锁定“Query Route Gateway 不再跑 runtime probes、External Query Planner fallback 不再按对象重分类、fit brief 会显式进入 external planner、external answer presenter 必须区分 `verifier_blocked / no_relevant_results / retrieval_failed / indirect_only`、external freshness follow-up 不再靠硬编码词表”。
- 详细目录迁移、兼容壳清理与新增模块清单见库存文档。

## 5. 前端结构（`frontend/`）
```text
frontend/
├── e2e/                       # Playwright 真实浏览器 E2E 用例
├── src/
│   ├── api/                   # 接口封装
│   ├── features/              # 新产品域与原型状态机（如 PMFlow OS / 个人空间 / 新项目启动台）
│   ├── pages/                 # 页面级组件（已目录化）
│   ├── components/            # 通用组件与 SSTC/Inbox 共享组件
│   ├── hooks/                 # 自定义 hooks
│   ├── lib/                   # 通用工具
│   ├── stores/                # 状态管理
│   ├── router/                # 路由
│   └── types/                 # TS 类型定义
├── package.json
├── playwright.config.ts
└── vite.config.ts
```
- 当前前端重点入口优先看：
  - `frontend/src/api/`（统一 API 封装）
  - `frontend/src/router/index.tsx`（顶层路由懒加载入口；登录页与 Layout 保持同步首屏，登录后默认主入口已切到 `/command-center`，`/space`、`/project-launch`、`/pmflow-os` 与 `/me` 是可直接打开的个人空间 / 新项目启动台 / PMFlow OS 项目上下文 / 我的账号入口，`/command-center` 也提供免登录产品预览壳，其余后台重页面按 route-level lazy 进入）
  - `frontend/src/features/personal-space/`（个人空间首页；通过 `frontend/src/api/space.ts` 只读聚合项目摘要、PMFlow OS truth-state / execution-summary，承载继续推进、待确认、AI 正在推进、草案箱和最近项目入口）
  - `frontend/src/features/project-launch/`（首次进入页 / 新项目启动台；默认调用真实 `frontend/src/api/pmflowLaunch.ts` draft/confirm API 创建项目，只有显式 `?demo=1` 或 `?dataSource=demo` 才启用本地 mock 演示状态机）
  - `frontend/src/features/account-settings/`（`/me` 个人中心与设置；通过 `frontend/src/api/accountSettings.ts` 管理个人资料、默认语言、AI 回答深度、证据展示偏好和通知偏好，移动端使用分组列表与 bottom sheet，不进入 auth core）
  - `frontend/src/features/pmflow-os/`（PMFlow OS 前端产品域；共享 truth store 已支持 `?projectId=<id>` 读取真实后端 projection，真实模式下 message、`proposed_items` extraction、ChangeItem `accept/edit/defer`、ChangeSet `commit`、review decision、Team reviewer routing、单条 iteration recommendation -> ChangeSet draft 与同组 iteration recommendation 批量 -> ChangeSet draft 均调后端，显式 `?demo=1` 才启用本地演示状态机）
  - `backend/app/api/pmflow_os_api/` + `backend/app/services/pmflow_os_projection_service.py` + `backend/app/services/pmflow_change_review_service.py` + `backend/app/schemas/pmflow_os.py` + `backend/app/models/pmflow_change_review.py`（PMFlow OS A3/C1/C2/P8 真实路径；提供 `truth-state`、`execution-summary`、thread message、`proposed_items` extraction、ChangeSet detail、ChangeItem `accept/edit/defer`、ChangeSet `commit`、review decision、execution handoff/progress writeback、release validation run、release feedback ingest、Team reviewer routing、recommendation change-set draft 与 recommendation group change-set draft；复用 `truth_nodes / tasks / semantic_facts / ai_project_control / dev_sync / FeedbackIngest / IterationRecommendation` 并投影 `pmflow_threads / pmflow_thread_messages / pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`；`truth-state.reviewerRouting` 是 `{status, warningCode, summary, items}` 合同，生成建议审查人/原因/来源/风险/跳转 URL，并投影 `reviewDecision / approvalState / requestedAt / decidedAt / decisionReason`；`POST /pmflow-os/change-sets/{change_set_id}/review-decisions` 支持 request_review/approve/request_changes/reject，复用 `PMFlowApproval` 审计，不自动 commit；C2 commit 默认 atomic，`ModelDecision / MetricSignal` 暂 fail-closed）
  - `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`（Project Launch Phase B 真实创建链；`drafts` 只写 `pmflow_launch_drafts`，`confirm` 在同一事务写真实 Project、启动线程、启动消息、初始 truth_nodes、tasks 与 semantic_facts seed）
  - `docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md`（PMFlow OS 产品合同真源；真实后端接入前先读，锁定本地 truth store 对象与 `truth_nodes / tasks / semantic_facts / ai_project_control / dev_sync` 的映射；Phase C1 review 表和审查 API 已实现，Phase C2 backend/frontend commit 已实现）
  - `frontend/src/pages/inbox/`（消息台）
  - `frontend/src/pages/ai-steward/`（AI 管家）
  - `frontend/src/components/ai-steward/`（问答浮窗、状态条、回答元卡片；`FloatingQAChat.tsx` 现会透传并回放 `project_operating_context / execution_recipe / fit_brief / external_recommendation / analysis_packet / recommended_next_step`，`QAConversationStatusBar.tsx` 与 `QAResponseMetaCard.tsx` 负责显性展示）
  - `frontend/src/pages/ai-config/mcp-config/`（AI Config -> Governance Tools 下的 MCP 模板接入中心）
  - `frontend/src/pages/query-route-governance/`（AI Config -> Governance Tools 下的 route/context 治理页）
  - `frontend/src/pages/semantic-facts-board/`（AI Config -> Governance Tools 下的 semantic facts 治理页）
  - `frontend/src/components/layout/LazyBoundary.tsx`（统一 route/page-section/dialog 级 loading skeleton）
  - `frontend/src/components/login/`（公开登录页组件目录；`LoginExperience.tsx` 负责双栏登录壳，`LoginWorkflowVisual.tsx` 负责左侧场景，`loginScene.ts` / `loginMath.ts` 拆出展示配置与路径几何，`login.css` 收口登录页专属样式）
  - `frontend/src/api/queryRouteGovernance.ts`（route/context 治理页前端 API）
  - `frontend/src/pages/scheduler-center/`（Mounted AI Console）
  - `frontend/src/components/sstc/`（SSTC 工作流组件）
  - `frontend/src/pages/user-skills/components/UserSkillsRadarPanel.tsx` 与 `frontend/src/pages/workload-detail/components/WorkloadTrendChart.tsx`（图表按页面内二级 chunk 拆分后的入口）
- 页面目录化、Mounted AI Console、Inbox、AI Steward 与 Recipes/Projects/Users 等模块化拆分的详细库存见库存文档。
- 顶层路由已改为 `React.lazy + Suspense`，统一 fallback 使用 `frontend/src/components/layout/LazyBoundary.tsx`；AI Steward / AI Config 页面按 active tab 只渲染当前可见区块，Projects/Users/图表页则把重对话框与图表从同步入口拆出。
- `frontend/src/features/project-launch/` 是新项目启动台独立产品域：`types.ts / useProjectLaunchState.ts` 承载状态合同和真实 API 编排，`mockData.ts` 只在显式 demo 模式下使用；默认路径调用 `POST /pmflow-launch/drafts` 生成可审查草案，确认后调用 `POST /pmflow-launch/drafts/{draft_id}/confirm` 创建真实项目并跳转 `/pmflow-os?projectId=<id>`。`LaunchShell` 桌面端复用 `frontend/src/features/personal-space/components/SpaceChrome.tsx` 的空间左侧栏和顶部条，主画布仍由 `IntentInputPanel / AIProgressCanvas / HumanReviewCanvas / DraftEditCanvas / FailureStatePanel / SuccessTransitionPanel` 承接，移动端仍由 `MobileLaunchLayout` 承接；`frontend/src/pages/ProjectLaunchPage.tsx` 仅做薄入口。
- `frontend/src/features/personal-space/` 是空间层入口：`PersonalSpacePage.tsx` 承接桌面个人工作面与独立移动单手布局，`frontend/src/api/space.ts` 只读聚合 `projects` summary、PMFlow OS `truth-state`、`execution-summary` 并生成 `nextActionQueue` 我的下一步队列、继续推进、待确认、发布关注、发布后反馈关注、下一轮迭代草稿关注、AI 正在推进、草案箱、最近项目摘要；Space P6 的下一步队列按高风险待确认、发布阻塞/失败证据、handoff consumed 后缺少后续 progress、下一轮 draft、发布后反馈/收入/合规信号排序，点击只跳 `/change-review?projectId=<id>&changeSetId=<id>`、`/execution-bridge?projectId=<id>` 或 `/release-growth?projectId=<id>`；Space P3 的发布关注优先消费 `truth-state.releases` 的 release validation 投影，没有验证投影时才回落 `execution-summary.releaseGate`；Space P4/P5 的发布后反馈/下一轮草稿关注只读消费 `execution-summary.releaseSignals`；不在 Space 写 Project Memory、ProgressEvent、ReleaseValidationRun、FeedbackIngest、RevenueEvent、ComplianceCheckRun、ChangeSet 状态或发布执行。`components/SpaceChrome.tsx` 承接空间层左侧栏、顶部条与空间用量组件，并被 `/project-launch` 桌面首次新建壳复用；`frontend/src/pages/PersonalSpacePage.tsx` 仅做薄入口。
- `frontend/src/features/account-settings/` 是 Account Settings 独立产品域：`AccountSettingsPanel.tsx` 承接 `/me` 桌面设置页、移动端分组列表与 bottom sheet，`frontend/src/api/accountSettings.ts` 定义个人资料、默认语言、AI 回答深度、证据展示偏好和四类通知偏好合同；当前已有账号同步 API fallback、本地 UI 通知消费模型、Release/Growth 偏好 helper、post-release / next change review 偏好 helper，以及 `getAccountReminderConsumption(settings, event)` 提醒强度消费合同，支持 `reminderIntensity=silent|normal|prominent` 与 `evidenceDisplay=compact|expanded`；`releaseGate / failureAlert / pendingConfirmation / executionWriteback` 只影响页面内提醒表达强度和证据展开方式，不代表真实邮件、桌面推送或系统通知中心已接入，也不得隐藏真实业务证据或审计状态，不改 OAuth/JWT/auth core；`frontend/src/features/pmflow-os/pages/AccountPage.tsx` 仅做薄入口并复用既有退出登录 bottom sheet。
- `frontend/src/features/pmflow-os/` 当前承载新的对话驱动前端产品域：`store.tsx` 提供共享 truth store；真实模式通过 `?projectId=<id>` 调用 `frontend/src/api/pmflowOs.ts` 读取后端 `ProjectTruthState` projection，并调用真实 message、`proposed_items` extraction、ChangeItem `accept/edit/defer`、ChangeSet `commit`、review decision、Execution Handoff create/consume、execution progress writeback、release validation run create、release feedback ingest、单条 iteration recommendation -> ChangeSet draft 与同组 iteration recommendation 批量 -> ChangeSet draft API，成功后 refetch truth-state / execution-summary；显式 `?demo=1` 才启用 `command_idle -> ai_extracting -> extraction_ready -> review_open -> writeback_success` 本地演示状态机，以及本地 `promoteAcceptedToGraph` 等演示动作。`pages/` 下包含 `CommandCenter / StructuredExtraction / ChangeReview / MemoryWritebackResult / WorkGraph / ExecutionBridge / ReleaseGrowth / TeamLayer / ProjectMemory / Account` 主页面；`ChangeReviewPage` 真实模式可请求审查、通过、要求修改或拒绝当前 ChangeSet，展示审查状态、建议 reviewer、审查意见和 high-risk approval gate，但不自动 commit；`TeamLayerPage` 真实模式读取 `state.reviewerRouting` 展示 ready/empty/warning、待审 ChangeSet、来源、风险等级、建议审查人或 fallback role、审查原因、待审 item 数、证据数、审查状态、审查意见和请求/决策时间，动作跳转 `/change-review?projectId=<id>&changeSetId=<id>`；`ExecutionBridgePage` 已支持创建 handoff、运行端领取确认和执行进度回写；`ReleaseGrowthPage` 真实模式展示 `execution-summary.releaseGate`、execution evidence、阻塞原因、下一步动作、`latestValidationRun` 和 `releaseSignals`，可创建 release validation run、摄取发布后 feedback、展示 recommendation quality grouping、从真实 recommendation 单条或同组批量生成下一轮待确认 ChangeSet draft，并消费 Account notification preference 静默强调型提醒，但不隐藏真实证据、审计状态或发布后信号；静态发布/增长原型仅保留在显式 demo 模式；后端只记录 review decision/progress/release gate/release validation/release feedback/recommendation draft 元数据，不执行本机命令、真实发布命令、外部支付、真实推送、自动 Project Memory commit 或正式任务创建；`ProjectMemoryPage` 在真实模式消费后端 `truth_nodes + semantic_facts` 的 `projectMemory` 投影，真实模式下 accepted/edited ChangeItem 只有 commit 成功后才进入 Project Memory。`components/` 下除了 `ProjectStageRail / ThreadComposer / ExtractionRail / ChangeGroupPanel / ObjectGraphSection / ContextPacketPanel / ExecutionTimeline / ReleaseGatePanel / TeamFeedPanel` 之外，新增 `ProjectStructuredLoop / PMFlowOsFrame / AccountControls / FeedbackPrimitives` 等行为组件，用来承接项目指挥台、结构化提取、待确认审查、项目记忆写入结果、项目内面包屑、项目切换器、账号退出登录交互，以及 `PageBanner / InlineNotice / HumanDecisionBar / ConfirmDialog / MobileBottomSheet` 这组契约化提示提醒组件；`components/MobileBottomNav.tsx` 是正式应用壳唯一移动底部导航，固定为 `空间 / 指挥台 / 待确认 / 动态 / 我的`。
- 旧登录实现 `frontend/src/components/ui/sign-in.tsx` 与 `frontend/src/components/ui/demo.tsx` 已移除，`frontend/src/components/login/` 是当前唯一登录真源。

### 5.1 `frontend/src/components/sstc/` 目录说明（模块化拆分后）
- `SSTCWorkspace.tsx`：SSTC 工作区主容器（组装各阶段组件）
- `useSSTCWorkspaceOrchestration.ts`：工作区编排 Hook（状态聚合、请求编排、事件路由）
- `sstcUtils.ts`：SSTC 工具函数（数据转换、状态判断、通用 helper）
- `SSTCSignalStagePanel.tsx`：信号阶段面板
- `SSTCCharterStagePanel.tsx`：宪章阶段面板
- `SSTCTaskStagePanel.tsx`：任务阶段面板
- `SSTCExecutionBoardPanel.tsx`：执行看板阶段面板
- `SSTCReleaseStagePanel.tsx`：发布阶段面板
- `SSTCReviewStagePanel.tsx`：复盘阶段面板
- `SSTCTaskCreateDialog.tsx`：任务创建弹窗
- `SSTCReleaseCreateDialog.tsx`：发布创建弹窗
- `SSTCReviewCreateDialog.tsx`：复盘创建弹窗
- `AIVisibilityPanel.tsx`：AI 可视化信息面板
- `FeedbackSummaryCard.tsx`：反馈中心摘要卡片（任务阶段/执行看板复用）
- `SSTCGlobalHeader.tsx`：SSTC 全局头部
- `SSTCStageNav.tsx`：阶段导航
- `SSTCChainView.tsx`：链路视图
- `SSTCRiskFloatPanel.tsx`：风险浮层
- `SignalContentHoverCard.tsx`：信号内容悬浮卡片
- `charterModules.ts`：宪章模块配置与映射

### 5.2 修改前必须执行 `FIND_USAGE` 的 SSTC 组件清单
- `SSTCWorkspace.tsx`
- `useSSTCWorkspaceOrchestration.ts`
- `sstcUtils.ts`
- `SSTCCharterStagePanel.tsx`
- `SSTCSignalStagePanel.tsx`
- `SSTCTaskStagePanel.tsx`
- `SSTCExecutionBoardPanel.tsx`
- `SSTCReleaseStagePanel.tsx`
- `SSTCReviewStagePanel.tsx`
- `SSTCReleaseCreateDialog.tsx`
- `SSTCReviewCreateDialog.tsx`
- `SSTCTaskCreateDialog.tsx`

## 6. 运行命令（高频）
### 根目录
```bash
./start.sh dev      # 推荐：docker-dev 热更新模式
./stop.sh dev
./scripts/start_model_probe.sh  # 独立模型连通性检测（中文日志）
```

- 启动入口收敛：用户入口统一使用 `./start.sh`。
- 前端浏览器请求统一走同源 `/api`；开发环境由 Vite proxy 转发，生产环境由 nginx `/api` 反代到后端。
- 运行脚本、模型探针、契约校验与 E2E 工具清单已迁到 [`docs/architecture/ARCHITECTURE_INVENTORY.md`](/Users/yuuuu/Documents/AIProjectManger/docs/architecture/ARCHITECTURE_INVENTORY.md)。
- 当前新增的 requirement-plan 历史修复工具位于 `backend/scripts/repair_requirement_plan_history.py`，默认 dry-run，仅在显式 `--apply` 时写回 `mounted_draft_workspaces / mounted_topic_workspaces`。

### 前端
```bash
cd frontend
npm run dev
npm run build
npm test
npm run e2e:feishu
```

### 后端（本地直跑）
```bash
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

## 7. 团队维护建议（简版）
- 规则变更：只改 `AGENTS.md`
- 结构变更：同步改 `CLAUDE.md` + `docs/architecture/ARCHITECTURE_INVENTORY.md`
- 运行边界 / 已知 runtime 假设变更：同步改 `AGENTS.md` + `docs/architecture/RUNTIME_GUARDRAILS.md`
- API/契约变更：后端 `schemas` + 前端 `types` 同步更新

## 8. 服务边界约束（禁止越界）
- 当前必须立即遵守的摘要规则以 `AGENTS.md` 第 8 节为准。
- 长运行边界、跨链路守门细节、失败语义和已知 runtime 假设已迁到 [`docs/architecture/RUNTIME_GUARDRAILS.md`](/Users/yuuuu/Documents/AIProjectManger/docs/architecture/RUNTIME_GUARDRAILS.md)。
- 当前最重要的摘要只保留：
  - 写操作必须经 Alembic / 受控执行器 / outbox / 审计日志，禁止业务路径直写或同步直发。
  - 用户可见核心业务内容禁止 fallback、stub、模板句冒充成功；失败必须显式失败或标记待确认。
  - MCP 模板接入中心只保存模板参数、命令预览、runtime probe 和手动确认状态；`backend_direct` 模板可由 PMFlow 后端直连（远程 `streamable_http` MCP 或内建 `backend_adapter` runtime），`stdio` 模板只能走 Local Bridge / 兼容 MCP host；禁止从服务端直写宿主机 `~/.codex/config.toml` 或替客户执行本机命令。
  - 运行时业务动作归因统一走“对象/上下文绑定 -> `SemanticContextPacket` -> `SemanticDecision` -> gatekeeper”。
  - `backend/app` 运行时代码禁止恢复散落的中文关键词、正则、`looks_like_*`、`*_HINTS/*_KEYWORDS` 业务拍板逻辑。
  - `llm_service` 只认显式 `routing_meta` 协议，不再靠函数名或 hint 推断 tier / contract / fallback。
  - 内部只读查询必须走 `Operation Contract -> Target Resolver -> Query DSL Plan -> InternalContextPacket -> 白名单受控执行器 -> semantic facts 优先 -> verifier`，其中 mainline 要先做 packet 预检，`query_semantics` 只作上游 scratchpad/兼容镜像并且只允许单点兼容写回；禁止继续充当 internal executor 或 verifier 的运行时真源，同时禁止自由 SQL 和无证据脑补。
  - `semantic_facts` 自动抽取统一走 ORM 提交钩子 -> `ingest_events(channel=semantic_fact_extract)` -> 统一 worker，支持 `project/task/signal/document/user/requirement/release/review` 八类对象；禁止在各路由散落手工 enqueue。
  - AI Steward、Requirement Plan、Signal Source、AdaptiveRAG 等核心链路的详细 guardrails 统一以 `RUNTIME_GUARDRAILS.md` 为准。

## 9. 新增代码的参考模式
- 详细的接口、页面与服务参考入口已迁到 [`docs/architecture/CODE_REFERENCE_INDEX.md`](/Users/yuuuu/Documents/AIProjectManger/docs/architecture/CODE_REFERENCE_INDEX.md)。
- 当前只保留高价值摘要：
  - 新增后端接口：优先参考 `backend/app/api/sstc_api/` 的结构
  - 新增前端 API 调用：优先参考 `frontend/src/api/sstc.ts`
  - 新增数据库表：参考 `alembic/versions/` 最新 migration
  - 新增飞书事件处理：参考 `backend/app/services/integrations/feishu_integration_service/`
  - 更细的 AI Steward / RAG / AI PMO / Signal / SSTC / 前端页面入口索引统一以 `CODE_REFERENCE_INDEX.md` 为准

## 10. 幂等与事务约束
- 所有入站事件必须经过 `ingest_events` 幂等去重
- 飞书回复必须经过 `feishu_reply_outbox`，禁止同步直接发送
- 飞书回复发送幂等：`reply_hash = MD5(source_message_id + reply_text)`，同租户下 `status=sent` 的相同哈希不得重复发送
- 跨表写操作必须在同一个数据库事务内完成

## 11. 已知 BOUNDARY（不要幻构行为）
- 详细已知运行边界与环境假设统一维护在 [`docs/architecture/RUNTIME_GUARDRAILS.md`](/Users/yuuuu/Documents/AIProjectManger/docs/architecture/RUNTIME_GUARDRAILS.md)。
- 当前高价值摘要只保留：
  - 飞书回调字段可能缺失文件名/大小，仅保证 `attachment_id/key/type` 可用。
  - 真实飞书网页 E2E 依赖本机已登录的 Chrome/Feishu 会话，结果校验统一走数据库探针。
  - 路由配置唯一真源固定为 `backend/.control_plane/pmflow-routing-rules.json`；请求超时统一以 `LLM_REQUEST_TIMEOUT` 为准。
  - World Model 静态层已接入 Redis 缓存（`wm:static:{tenant_id}:{project_id}`，TTL 600s），写操作后主动 invalidate，动态层不缓存。
  - `signal_sources` 仅作为 AI Steward 创建结果区的内联展示；项目看板与 SSTC 信号阶段统一只读正式 `Signal`。

## 12. 技术债务清单
- [x] `mixin_auto.py` `_safe_int` NameError：已通过显式导入 `_safe_int` + 回归测试锁定，避免后续共享导出调整导致运行时未定义
- [x] AI 入口主链已统一：飞书长连接（`capture_from_feishu`）、`/ai-pmo/process-text` 与 `/rag/ask` 已统一收敛到 `AIPMOKernelService.process_ingress` 主链；`/rag/ask` 通过 `rag_ask_contract.build_kernel_ingress_kwargs` 透传 RAG 上下文（`session_id/new_session/thinking_mode/action_mode/...`），query 执行后由 `build_rag_response_payload` 保持 HTTP 响应兼容，回归由 `test_rag_route_contract.py`、`test_ai_pmo_qa_http_mainline_e2e.py`、`test_ai_pmo_ingress_mainline.py` 锁定
- [x] Unified Project Operating Context 已接到问答入口：`/rag/ask`、`/ai-pmo/process-text` 与 kernel ingress 现会先透传最小 `project_operating_context`（当前项目、当前仓库摘要、页面/线程锚点），AdaptiveRAG 的 `Query Route Gateway` 进一步产出 `execution_recipe`；external 主链会在需要时补 `fit_brief`，回答 payload 同步暴露 `project_operating_context / execution_recipe / fit_brief / external_recommendation / analysis_packet / recommended_next_step / handoff_mode`，回归由 `test_project_operating_context_contract.py`、`test_rag_route_contract.py`、`test_ai_pmo_qa_http_mainline_e2e.py`、`test_external_query_planner.py`、`test_mcp_external_query_bridge.py`、`test_adaptive_rag_mainline_contract.py`、`test_analysis_packet_contract.py` 锁定
- [x] 飞书入口层耦合已收敛：飞书真实入口已拆为三段职责链（预处理 `mixin_receive_prepare.py` / capture 执行 `mixin_receive_capture_flow.py` / 编排 `mixin_receive.py`）；`mixin_receive.py` 不再混合传输解析、附件标准化、capture 异常兜底与收尾回执逻辑，分层边界通过 `test_feishu_receive_orchestration_contract.py` 锁定
- [x] `task.create` 已升级为一等 typed intent：`IntentResolver/RouteResolver` 新增 `task.create` 常量与 `task.create` 路由族；TypedExecutor 已接入任务落库执行（含 `project_id`/任务标题槽位守卫、对齐 Charter 校验、`persist_task` 写入）；`WorkflowRegistry`、`ReplyRenderer`、`followup` 校验与草稿确认闭环已纳入 `task.create`；并补 `test_ai_pmo_task_intent_contract.py` 回归锁定
- [x] `task.create` 已接入消息级幂等账本：Feishu `source_message_id/feishu_message_id` 作为 `task.create` 账本 key，重复确认只回放同一结果，不再重复落库；回归由 `test_feishu_pipeline_queue_contract.py` 锁定
- [x] `signal_source.onboard` 已接入消息级幂等账本与 non-plan 直写 carry-over：TypedExecutor 以 `source_system + source_message_id` 作为 onboarding ledger key，重复提交只回放同一结果，不再重复跑信号源接入编排；recommendation candidate set 会经 `reply_anchor_qa_context + action_contract` 沉到执行结果里，供后续 `把刚才推荐的写进系统 / 确认入库` 继续走 `prepare_write -> confirm_write -> execute_write` 直写链，而不是默认 requirement draft；回归由 `test_ai_pmo_signal_source_onboard_contract.py` 锁定
- [x] AdaptiveRAG 职责已完成首轮收敛：`answer_question` 入口已分层为 `prepare runtime` 与 `base mainline` 两段，写确认逻辑通过 `_should_trigger_write_ack_gate` 独立门控；基础问答主路径不再与写确认判断混写在同一函数体。分层契约由 `test_adaptive_rag_mainline_contract.py` 锁定（read 绕过 ack、write 命中 ack、feishu write 维持主链）
- [x] 执行层已形成统一执行账本与参数来源约束：ingress 执行路径统一通过 `KernelIngressStorageMixin` 生成 `execution_result.action_contract`（固定 `param_source=decision.execution_plan.actions+workflow_route+execution_result`）并写入 `operation_execution_ledger`（`applied/pending_manual/pending_confirmation/failed`）；`mixin_auto.py`、`mixin_prepare_manual.py` 的 `operation_code` 日志来源已对齐 `action_contract`，回归由 `test_ai_pmo_execution_ledger_contract.py` 锁定
- [x] QA/RAG 路由契约双轨已收敛：`/ai-steward/rag/ask` 兼容入口已移除，问答统一收敛到 `POST /rag/ask`；参数构造与 tenant 解析收口在 `backend/app/api/rag_ask_contract.py`，前端 `FloatingQAChat` 与 Context Cache API 目录均已对齐，`backend/tests/test_rag_route_contract.py` 与 `backend/tests/test_context_cache_profile_catalog.py` 已锁定回归
- [x] 三模式交互上下文基线已显性化：`/rag/ask`、QA session detail 与 session state replay 现统一透出 `route_decision / clarification_code / clarification_candidates / answer_mode / grounding_status / evidence_pack / project_operating_context / execution_recipe / fit_brief / external_recommendation / analysis_packet / handoff_mode / can_enter_plan / recommended_next_step`；前端 `FloatingQAChat` 会在即时回答与历史回放两条路径都接入这批字段，`QAConversationStatusBar` 与 `QAResponseMetaCard` 显式展示当前对象、来源模式、仓库/执行通道、项目画像、分析结果、外部推荐状态与下一步；`/ai-pmo/process-text` 与 `GET /ai-pmo/work-items` 现同步投影 `plan_mode / plan_status / requirement_plan_context_summary` 到 Inbox 展开区，回归由 `test_ai_pmo_qa_http_mainline_e2e.py`、`test_ai_pmo_ingress_mainline.py`、`FloatingQAChat.test.tsx`、`QAResponseMetaCard.test.tsx`、`InboxListItem.test.tsx` 锁定
- [x] AI 管家浮窗交互已与 Grounding Runtime 对齐：回答区已切到 markdown 渲染，顾问标签升级为显式交互按钮；`consultant_mode_preference` 只用于 `/rag/ask` 内部重答，`允许执行` 明确交接到 `/ai-pmo/process-text`，避免 query/execute 边界回退到旧的一锅煮
- [x] Retrieval source registry / metadata 已统一：AdaptiveRAG 检索链已建立统一 source registry / metadata normalizer，`citations[]/sources_used[]` 直接消费标准字段 `source_type/source_id/chunk_id/target_url/project_id/updated_at/permission_scope/source_priority`；`doc/url/feishu/pmflow/graph/db` 的来源元数据与排序键已收口，并由 `test_rag_route_contract.py`、`test_adaptive_rag_mainline_contract.py` 锁定
- [x] 语义治理 baseline 已清零：`backend/app` 运行时代码中的 `looks_like_* / *_HINTS / *_KEYWORDS` 残留已清空，主链统一改为对象/上下文绑定 + `SemanticContextPacket -> SemanticDecision -> gatekeeper`；`scripts/semantic_lint_baseline.txt` 已清空，并由 `scripts/semantic_lint.py` 与 `backend/tests/test_semantic_lint.py` 做仓库级守门
- [x] 结构化 runtime 收口回归已补齐：`backend/tests/test_runtime_structured_semantics_contract.py` 额外锁定 `backend/app` 运行时代码里 `_is_question_like / _is_project_lookup_question / _is_capability_question / classify_intent_complex` 等旧语义拍板残留不得回流；`backend/tests/test_feishu_pipeline_queue_contract.py` 同步覆盖 `followup` 线程锚点优先与 signal capture 不再依赖问句词法兜底
- [ ] 历史 Feishu 队列 / `feishu_items` 兼容链仍未完全退场：飞书真实入口、卡片动作、文本 queue followup，以及 `project_knowledge_graph` 的主增量/API 命名都已切到 `work_item` 主链；当前剩余债务主要是 `feishu_items` 存量读链路、历史 pending 事件兼容消费，以及 legacy `feishu_delta` 证据/回放兼容壳。后续需在历史存量清空后正式封存该兼容层
- [x] AdaptiveRAG 向量检索 legacy fallback 已移除：`AdaptiveRAGRetrievalVectorMixin._retrieve_vector_context()` 现在只支持 PostgreSQL/pgvector 主路径；非 PostgreSQL 或 PG 查询失败时直接返回空结果，不再回退 Python 侧 legacy 扫描，边界由 `test_adaptive_rag_mainline_contract.py` 锁定
- [x] 历史 Alembic 链幂等性缺陷已修复：`add_users_table_rbac.py` 的 PostgreSQL ENUM 创建已改为显式创建 + 列类型 `create_type=False` 复用，`userrole/userstatus` 不再在同一条 migration 内重复建型；回归由 `test_add_users_table_rbac_migration.py` 锁定
- [ ] 食谱图片上传仍是示例桩实现：`backend/app/services/recipe/service.py` 仍以模拟 URL 代替对象存储，`POST /recipes/upload-image` 也还停留在示例接口形态；若该模块继续保留，需要补齐真实对象存储接入、租户隔离与统一 `{code,message,data}` 响应包络，否则应明确标注为非核心示例模块
- [x] LLM 运行时仍未完全收敛：`ai_service_core._invoke_with_retry` 与 `stream_chat` 已统一走 `llm_service`；旧 `_get_llm` 路径已显式禁用，并补回归测试锁定
- [x] QA 主链自动化测试覆盖已补齐：`backend/tests/` 已覆盖问答/RAG 主路径与关键场景；新增 `test_ai_pmo_qa_http_mainline_e2e.py` 通过 HTTP 层锁定 `/rag/ask` 的 `qa_readonly/mixed` 契约以及 `/ai-pmo/process-text` 的 `draft_pending_confirm` 主链返回，配合 `test_ai_pmo_ingress_mainline.py`、`test_ai_pmo_task_intent_contract.py`、`test_ai_pmo_tactical_brain_contract.py` 形成稳定回归基线
- [x] 飞书交互闭环已补齐：执行场景回执在 `draft_pending_confirm/pending_manual` 下优先生成按钮卡片并经 outbox 异步发送；`card.action.trigger` 已覆盖 `confirm/revise/cancel/continue` 回调分发，分别复用 `DraftConfirmHandler.handle_api_decision` 与 AI PMO `process_ingress` 主链继续执行；回调 HTTP 现在会同步返回 toast 反馈，确保点击按钮后至少有可见结果；`backend/tests/test_feishu_card_action_contract.py` 已补卡片构造与 `continue` 回归契约