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

100 KiB
Raw Blame History

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. 顶层目录（精简版）

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。
  • 本地预览端口现按职责拆分：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 已完成 Review Decision Loop、Space review attention queue、Account review decision preference 与 integration 收口；仍不新增 route/nav、不接真实通知中心。
  • 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/）

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、/space/ai-concierge/ask、/ai-pmo/process-text、kernel ingress 会先补当前项目/仓库/线程锚点，Space 入口额外透传结构化 surface_context / tenant_project_context，再给 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/pmflow_agent_runtime/service.py + backend/app/services/pmflow_ai_agent_runtime/agent_run_service.py + backend/app/services/pmflow_ai_agent_runtime/agent_step_planner.py + backend/app/services/pmflow_ai_agent_runtime/agent_tool_registry.py + backend/app/services/pmflow_ai_agent_runtime/agent_state_critic.py + backend/app/services/pmflow_ai_agent_runtime/agent_answer_runtime.py（Space 用户侧 PMFlow AI 当前主控。/space/pmflow-ai 与兼容 /space/ai-concierge/ask 必须先由 PMFlowAgentRuntimeService.run_space_turn() 创建 durable pmflow_agent_runs，再委托 PMFlowAIAgentRunService 执行 LLM Step Planner -> typed tool -> Observation Ledger -> State Critic -> Terminal Answer State -> Answer Runtime；pmflow_agent_runtime/loop.py 与 answer.py 只保留 legacy compatibility，不得恢复为产品主控。市场/外部/机会类问题不能由能力介绍或空间项目列表直接回答，必须经过 external_search 和机会发现/验证类 tool 形成目标相关 observation，或者返回客户安全证据边界。）
    • backend/app/schemas/pmflow_ai_turn_runtime.py + backend/app/services/pmflow_ai_turn_contract.py + backend/app/services/pmflow_ai_turn_runtime_service.py + backend/app/services/pmflow_ai_turn_state_reviser.py + backend/app/services/pmflow_ai_evidence_tool_registry.py + backend/app/services/pmflow_ai_evidence_absorber.py + backend/app/services/pmflow_ai_evidence_authority.py（兼容 Space Turn Runtime 资产，不再是 /space/pmflow-ai 产品主控；/space/ai-concierge/ask 不再先调用 route planner，也不再让 answer_contract / source_strategy / allowed_executors / task_type 决定 action。PMFlowAITurnState 是兼容 turn 合同，包含 turn_goal / object_state / evidence_state / action_state / sufficiency_state / answer_state / runtime_steps，并在 QA session response payload 中保存可 replay snapshot；Packet A/B/C/D/E/F/G/H 后额外以 candidate_frames / selected_frame / observations / operation_gaps / state_revisions / verification_failures / customer_packet_draft 作为 Observation-driven WorkingState 骨架。Packet 1/2 后 pmflow_ai_turn_contract.py 是目标评估输出进入 runtime/reviser 前的唯一归一与校验层，集中处理 operation_kind / source_policy / target_scope / answer_shape / system_action_hint 矩阵；旧 decision_type / evidence_needs 只允许在这里兼容，不能再在 runtime、Reviser 或 ActionSelector 中散落恢复主控。Packet 3/4 后 build_turn_presentation_contract_from_runtime_payload() 是 Space AI 主交互展示合同的唯一生成入口，interaction_request 只能来自 runtime 的用户可处理 gap；rag_ask_contract.ensure_customer_interaction_request() 只规范化已有结构化请求，不再从旧 route plan、missing fields、limitations、answer_canvas.next_actions 或正文补造追问。PMFlowAITurnStateReviser 负责优先消费归一后的 goal_frames / operation_gaps，同时优先消费 tool payload 的 runtime_observation、按 can_answer_operations 修正 sufficiency/customer packet draft，并把 verification failure 回流 state revision；当 collection observation 证明 fact_list 可回答时，可把误判 frame 修正为 list_collection。select_next_minimal_action() 优先消费 selected_frame.operation_kind。Packet D/F 后 action 队列由 refresh_action_state_from_working_state() 按 selected_frame / operation_gaps / system_action_hint / observations / performed_actions 动态派生，旧 candidate action 队列只作为可被覆盖的兼容字段，evidence_needs 不再直接构造工具队列或 sufficiency flags。Packet E/F 后 _infer_turn_hypothesis() 主输出是 goal_frames / operation_gaps，answer_shape / decision_type / evidence_needs / raw needs_user_input 只作为 legacy 兼容输入；旧字段冲突时不得覆盖 direct goal frame，raw needs_user_input 不能单独生成阻塞追问。Packet X/Y/Z 后 PMFlowAIEvidenceAuthority 会按结构化 primary_object / binding_strength / selected_frame / project_operating_evidence_packet(s) 做证据权威判断：强绑定项目的状态、进展、推进建议在读取匹配项目运行态证据前，必须先 inspect_project_status，并阻止 external_search / external_fetch 抢首步；final verifier 若发现错误来源或缺项目运行态证据，会把 inspect_project_status 写回 system gap 继续循环。Packet H 后集合类答案优先由 _render_collection_answer_from_working_state() 确定性输出列表，已有可回答 observation 时 verifier 必须禁止 interaction_request。Packet C 后 PMFlowAIEvidenceToolRegistry 的只读工具必须返回 runtime_observation，包含观察类型、对象类型、items、可回答 operation 和剩余缺口；absorb_evidence() 不能再因任意 finding/source 直接设置 can_answer_now。answer_process_packet.steps 来自真实 action loop，不再由前端固定展示“已检查范围”。Packet 7 后前端 SpaceAIConcierge 不再发送 message_intent / quick_prompt，completed 过程只渲染后端 answer_process_packet.steps，pending 态只表达等待真实 runtime 步骤，不从快捷入口、问题文案、thinking mode 或本地 stage 合成候选步骤；历史详情必须返回 pmflow_ai_turn_state 与 turn_presentation_contract。Packet 6 后 PMFlowAIEvidenceToolRegistry 是唯一 evidence tool 执行入口，inspect_surface_context / inspect_saved_ideas / inspect_internal_projects / resolve_project_objects / inspect_project_status / external_search / external_fetch 只返回事实、来源、置信度、目标相关性和剩余缺口，不生成 implication 或 judgement；PMFlowAIEvidenceAbsorber 是唯一 evidence -> finding/implication/gap/judgement 吸收层，且不会把 final answer 反灌成证据；CustomerAnswerPresentationService 只按 final TurnState/CustomerEvidencePacket 的 answer_shape 表达，不再按 quick intent、旧 route contract、packet 名称或旧 answer_type 场景枚举重判展示。旧 orchestrator、runtime kernel、SpaceAIExecutionContract、TaskGraph、SpaceProjectLookupService、SpaceAIGeneralEvidenceSynthesisService 主控文件已删除，不能再作为 API 主链或 analyzer 早返回。）
    • Packet AE 后，PMFlowAIEvidenceAuthority 作为 Source Authority Gate 继续保留兼容类名：它可声明本轮权威真源是否需要工具、哪些首步 action 禁止、是否可直接回答、使用哪个 renderer 和客户安全过程 label。explain_assistant 必须走 pmflow_assistant_contract / static_product_contract，只保留 synthesize_answer，不得被旧 external/project gap 改写成查外部或查项目，也不得展示内部 token 或“证据不足”兜底。回归见 backend/tests/test_pmflow_ai_source_authority_packet_ae.py。
    • Packet AF 后，backend/app/services/pmflow_ai_static_contract_registry.py 是静态产品合同注册表；Source Authority 只返回 contract_key 和 gate 决策，runtime renderer、CustomerEvidencePacket 来源/限制/置信度、过程 step label 都从合同读取。静态身份/能力边界回答不得继续内联在 pmflow_ai_turn_runtime_service.py，也不得恢复问句关键词判断。回归见 backend/tests/test_pmflow_ai_static_contract_packet_af.py。
    • Packet AI/AJ/AK/AL 后，用户侧 PMFlow AI 的“能不能说”成为 TurnState 一等状态：PMFlowAIDisclosureState 由 _infer_turn_hypothesis() 的 disclosure_policy 经 pmflow_ai_turn_contract.py 归一后落入 PMFlowAITurnState.disclosure_state。触及 PMFlow 内部实现、技术架构、源码、字段、prompt、模型供应商、内部路由、trace、函数名、工具调用细节或服务架构实现时，必须走 protected_internal_refusal.v1，优先级高于 assistant_identity.v1；Source Authority 只允许 synthesize_answer，Verifier 只校验保护合同是否 faithfully 出站，不做答案文本关键词兜底。回归见 backend/tests/test_pmflow_ai_disclosure_policy_packet_ai_aj_ak_al.py。
    • Packet AM 后，用户侧 PMFlow AI 最终合成前必须进入 Answer Runtime：PMFlowAITurnState 新增 PMFlowAIAnswerObjective / PMFlowAIAnswerPlan / PMFlowAIAnswerDraft / PMFlowAIAnswerQualityFinding，_run_state_answer_synthesis() 先刷新回答目标、回答计划、证据用法、表达边界和 draft source，再调用 renderer 生成候选答案，并在 payload 暴露 answer_runtime_packet。_compose_state_answer() 只能消费 Answer Runtime packet 与 customer-safe TurnState，不得把 renderer 或 prompt 当成终局主控，也不得用新增场景关键词、固定模板或问句枚举解决重复回答问题。回归见 backend/tests/test_pmflow_ai_answer_runtime_packet_am.py。
    • Packet AN 后，静态产品合同和保护拒答合同不再存储整段终局答案：PMFlowAIStaticContractRegistry 只保存 required_claims / customer_safe_capabilities / source_summary / limitations 这类合同材料，_render_source_authority_answer_from_turn_state() 必须经 Answer Runtime materialize 本轮 draft；PMFlowAIAnswerVerifierRegistry 不再做全文相等校验，而是要求 final payload 带 answer_runtime_packet、合同 source summary 和披露边界/目标/计划闭环。回归见 backend/tests/test_pmflow_ai_answer_runtime_packet_an.py。
    • Packet AO 后，Answer Runtime 增加出站前 quality gate：_apply_answer_quality_gate() 会检查 draft 是否为空、是否泄漏内部运行时术语、是否回显 answer plan 策略语句、静态/保护合同材料是否真实进入 Answer Runtime；命中时写入 PMFlowAIAnswerQualityFinding 并重写为客户安全 draft，payload 的 answer_runtime_packet.quality_findings 可用于 replay/诊断。该 gate 只消费 Answer Objective/Plan/Draft 与 TurnState，不读用户问句关键词、不新增场景模板。回归见 backend/tests/test_pmflow_ai_answer_runtime_packet_ao.py。
    • Packet AP 后，旧 _sanitize_state_answer() 出口兜底已删除，renderer 只产出 draft，所有出站质量问题统一进入 Answer Quality Gate。Gate 对重写后的 draft 再做一次复检；若复检仍泄漏内部术语或仍不是有效客户答案，则写入 post_revision_quality_failed 并返回客户安全 fail-closed 边界答案，禁止把失败 draft 出站。回归见 backend/tests/test_pmflow_ai_answer_runtime_packet_ap.py。
    • Packet AQ 后，项目运行态 verification 对正文的约束必须先合入 draft，再进入 Answer Quality Gate；project_operating_answer_verification 注入 answer / customer_evidence_packet / answer_canvas 的动作、边界和原因必须先做客户安全文本投影，过滤内部运行时术语。最终 answer_runtime_packet.draft.answer_text 要对应出站答案内容，禁止 verification 后处理绕过质量门禁或把内部词汇塞进 canvas/packet。回归见 backend/tests/test_pmflow_ai_answer_runtime_packet_aq.py。
    • Packet AR/AS/AT 后，用户侧最终客户 payload 增加统一出站门禁：sanitize_customer_rag_payload() 会从即时响应剥离 answer_runtime_packet / evidence_findings / project_operating_answer_verification_packet / pmflow_ai_turn_state / pmflow_ai_route_plan / route_decision / trace/tool/debug 等内部包；_persist_space_direct_payload() 在写 QA history routing_snapshot.response_payload 前也使用同一份 sanitized customer payload，避免历史回放泄漏；嵌套 display packet 会丢弃 prompt_key / raw_source_label / routing_meta / answer_plan / structured_evidence 等内部 key，tenant_project_context_packet 的可答/保护范围改为客户可读标签。回归见 backend/tests/test_pmflow_ai_customer_payload_packets_ar_as_at.py。
    • Packet AU 后，用户侧最终表达材料先归一到 PMFlowAITerminalAnswerState：Claim Ledger / Boundary Ledger / Attempt Ledger / AnswerIntentPlan 是后续自然表达器的唯一终局材料层。Verifier failure 的 reason/internal_diagnostic 只允许进入内部诊断；客户可见只能消费 customer_safe_summary / customer_safe_effect 生成 claim 和 boundary。_build_verification_blocked_payload() 不再把 verifier reason 直接拼进 answer/limitations，也不再默认把所有 blocked 都解释成“项目运行证据不足”；sanitize_customer_rag_payload() 会递归清理 terminal state 里的 internal_diagnostic。回归见 backend/tests/test_pmflow_ai_terminal_answer_state_packet_au.py。
    • Packet AV 后，Verifier failure 必须携带 verification_delta，把 claim_deltas / boundary_deltas / attempt_delta / retry_would_change_state / customer_safe_effect / internal_diagnostic 结构化返回；next_action_hint 不再天然驱动重试。PMFlowAITurnRuntimeService.run_space_turn() 在每个 final payload 校验点都先检查 _verification_failure_allows_retry()，若 retry_would_change_state=false 则直接进入 terminal-state blocked payload，不再把同一 TurnState 反复送回 synthesize_answer。PMFlowAITurnStateReviser 也只在 retry 会改变状态时创建 system action gap，避免 verification_synthesize_answer 这类无效 gap 回流。回归见 backend/tests/test_pmflow_ai_verification_delta_packet_av.py。
    • Packet AW 后，AnswerIntentPlan 升级为终局表达策略层：_plan_terminal_answer_intent() 从 Claim/Boundary Ledger 选择 lead_claim_id / lead_boundary_id，生成 opening_move / user_value_focus / answer_moves / composition_guidance / anti_template_rules / structure_preference / detail_level。该层只决定“本轮怎么说”，不写最终正文、不按 terminal_status/failure_type 选择固定模板，也不读用户问句关键词做路由；短边界问题优先自然短段落，材料丰富时才允许紧凑分组，始终禁止固定“判断依据/证据边界/下一步”三段式。回归见 backend/tests/test_pmflow_ai_answer_intent_planner_packet_aw.py。
    • Packet AX 后，terminal blocked/rewrite 出口接入通用自然表达器：_render_terminal_state_fallback() 现在委托 _compose_terminal_customer_answer() 按 AnswerIntentPlan + Claim/Boundary Ledger 生成自然短段落或紧凑列表，再由 _critique_terminal_customer_answer() 检查空答、内部运行时术语、固定标题模板、重复句和 lead claim/boundary 丢失；Answer Quality Gate 的 _revise_answer_from_quality_findings() 也优先使用同一 terminal composer 修复失败 draft。该层不是 Customer Failure Presenter，不按问题场景、failure_type 或关键词写固定回复。回归见 backend/tests/test_pmflow_ai_natural_answer_composer_packet_ax.py。
    • Packet AY 后，旧 state fallback 和 quality fail-closed 固定句进一步收口：_render_state_answer_fallback() 不再手写“我的判断/证据和含义/下一步建议”段落，而是构建 PMFlowAITerminalAnswerState 后走 terminal composer；_render_answer_quality_fail_closed() 强制重建不含失败 draft 的干净 terminal state，避免 answer_draft_claim 把 TurnState/evidence_findings/runtime_steps 这类坏内容带回用户答案，最终仍泄漏时只返回短边界句。回归见 backend/tests/test_pmflow_ai_terminal_fallback_unification_packet_ay.py。
    • Packet AZ 后，展示层不再二次模板化 runtime 答案：CustomerAnswerPresentationService._standardize_canvas_direct_answer() 只做客户安全清洗、来源尾巴移除、去掉历史生成的 结论/判断依据 标题和长度裁剪，不再把长文本改写成 **结论** / **判断依据**；_render_state_shape_answer() 不再按 answer_type 加“综合判断/可执行建议/当前状态/依据/还需要确认”等前缀，只返回 customer-safe facts/fallback 的自然串联。回归见 backend/tests/test_customer_answer_presentation_golden.py。
    • Packet AG 后，backend/app/services/pmflow_ai_answer_renderer_registry.py 是最终表达候选选择层；_run_state_answer_synthesis() 只调用 registry 选择的 static_contract / collection_snapshot / project_operating_packet / open_judgement / llm_state_compose / safe_fallback 候选，再执行对应 renderer。新增 deterministic renderer 必须先登记 registry，禁止继续在主循环堆 _render_* if 链。回归见 backend/tests/test_pmflow_ai_answer_renderer_packet_ag.py。
    • Packet AH 后，backend/app/services/pmflow_ai_answer_verifier_registry.py 是 final payload 出站校验层；_verify_runtime_payload() 只委托 registry。required authority evidence、static contract faithfulness、项目运行态 coverage、interaction request 权限和 collection answer shape 都在 registry 校验，新增 verifier policy 不得回到 runtime 内联 if 链。回归见 backend/tests/test_pmflow_ai_answer_verifier_packet_ah.py。
    • backend/app/services/pmflow_ai_turn_object_ledger.py（Packet I 的 Session Object Ledger；Space AI 每轮只从真实返回 payload 的 customer_packet_draft.items / runtime_observation.items / answer_canvas.object_refs / customer_interaction_context_packet 提取客户安全对象，写入 qa_session_states.context_capsules，并回填 customer_interaction_context_packet.current_focus_object / last_shown_objects / recent_objects。下一轮只有弱指代且目标框架需要单对象 inspection/execution 时，才允许用 ledger 绑定 primary_object(binding_strength=session_object_ledger)；有可执行系统证据 gap 时先 read/probe，不把系统缺口 label 变成用户追问。）
    • Packet J 后，Space AI 续问必须先过 topic switch 和目标相关性门禁：object_binding_decision 可拒绝上一轮 focus 或创建新 focus；scope_gap 只表达对象边界变化，不触发项目状态读取；非单对象 guide_execution 不因 ledger 存在读取旧项目；PMFlowAIEvidenceAbsorber 会过滤 off-topic 项目证据，旧项目 status/surface facts 不能支撑新项目/新方向判断；答案合成出口会清理 evidence_findings / TurnState / problem_frame 等内部运行时术语泄漏。
    • backend/app/schemas/project_operating_evidence.py + backend/app/services/pmflow_ai_project_execution_observation.py + backend/app/services/pmflow_ai_evidence_coverage_gate.py（Packet K/L/Q/R/S/T 的项目执行态 observation adapter、项目全流程 evidence packet、facet reader、coverage gate 与最终答案 verification；inspect_project_status 读取 PMFlow OS truth-state / execution-summary 后必须输出项目阶段、当前执行任务、验收/发布门禁、阻塞项、候选任务、项目记忆等客户安全 facts，并在 structured_evidence.project_operating_evidence_packet(s) 中同步返回 ProjectOperatingEvidencePacket。Packet R 后 build_project_operating_evidence_packet() 只做装配，具体读取由 _read_command_state / _read_workbench_state / _read_decision_review_state / _read_execution_state / _read_quality_test_state / _read_release_growth_state / _read_team_state / _read_project_memory_state / _read_risk_blocker_state / _read_recent_timeline_state 承接，分别消费 reviewerRouting / feed / testRuns / releaseSignals / recentProgressEvents / recentDeliveries / artifactReview / deliveryArtifacts 等 PMFlow OS 投影；Packet S 后 PMFlowAIEvidenceAbsorber 会把 tool structured evidence 合并进 TurnState.evidence_state.structured_evidence，coverage gate 只按 packet facet coverage profile 判断 project_stage / current_execution_state / active_or_next_tasks / blockers_or_gate，不再读取中文 finding 文案。Packet T 后 _project_operating_answer_verification_packet() 会把 packet 的 safe_next_actions / blocked_actions / missing_or_partial_facets 转成 project_operating_answer_verification.v1，并约束正文、CustomerEvidencePacket 和 answer_canvas 的可推进动作、不可直接做边界与证据边界。status_answer / execution_guidance + current_project 覆盖不足时先低风险 probe，不直接 synthesize。）
    • Packet AA/AB 后，PMFlowAITurnRuntimeService.run_space_turn() 的 fallback synthesis 也必须经过 _verify_runtime_payload()；verifier 失败时若有可执行 next_action_hint，runtime 会先执行对应只读 action、吸收 observation、重新合成并再次校验，仍失败才返回客户安全 blocked payload，禁止未经 verifier 通过的 final answer 出站。强绑定项目且已有 ProjectOperatingEvidencePacket 时，_render_project_operating_answer_from_turn_state() 优先作为 deterministic renderer，直接用项目全流程 facet、safe actions、blocked actions、answer boundaries 和 coverage 输出项目状态与推进建议，不再把项目运行态 packet 丢给通用 LLM 淡化成“无法提供/请补充”。
    • Packet AC/AD 后，Space AI 出口层只做客户安全展示和耗时补充，不再改写 runtime 真过程：attach_answer_process_timing() 不得把已有 runtime step 的 blocking/status/duration_ms 改成固定值，也不得补造步骤；项目运行态来源通过 _customer_source_label() 出站为“项目运行态证据”，项目对象解析/内部项目数据出站为“项目数据”，不再丢弃或泛化成“PMFlow 上下文”。
    • Packet M/N 后，Space AI turn loop 在 can_answer_now=true 前仍会检查未完成的可执行系统 gap，先执行低风险 read/probe 再合成；PMFlowAIThreadWorkspace 的 collected_inputs / pending_questions / evidence_requirements 会通过 ResearchWorkspace 持久化到 qa_session_states.active_workspace，下一轮合并结构化 PMFlowAITurnDelta 继续推进新项目/新想法工作区，不再靠 transcript、关键词或前端按钮文案恢复上下文。
    • Packet O/P 后，开放方向在允许带假设回答且没有强项目绑定时，PMFlowAITurnRuntimeService 会用 TurnState/workspace slot 生成客户安全初判，不再因为没有 evidence findings 退成“不能判断”；需要追问时，runtime 会把 workspace pending questions 与 user-actionable gaps 组织成同一个 stepper，避免一轮只问一个模板问题。
    • 开放方向判断默认先答再标缺口：普通“我想做 X，你觉得怎么样/能不能做”不能直接阻塞成通用追问，PMFlowAITurnRuntimeService 应在 TurnState 中给出 can_answer_now=true / can_answer_with_assumptions=true，把目标用户、痛点、最小闭环、验证信号作为非阻塞缺口；只有写入/执行前置条件不满足、对象范围会显著改变结论或 runtime 明确不可假设回答时，才返回 blocking interaction_request。
    • PROMPT_SPACE_AI_INTERACTION_OPTION_PLANNER（Space AI 追问选项规划；开放合成答案生成后，基于用户原话、customer-safe packet、已生成答案和 fallback interaction request 生成贴合当前语义的 questions[].options[]，避免通用候选误配到具体场景；只做客户可见选项规划，不做路由、检索、写入或事实确认）
    • backend/app/services/space_runtime_context_builder.py + backend/app/services/pmflow_ai_evidence_tool_registry.py + backend/app/schemas/customer_answer.py + backend/app/services/customer_answer_presentation_service.py（用户侧 PMFlow AI 的空间上下文、EvidenceTool 注册入口、客户答案合同与展示层。旧 project_mvp_scope_recommendation_service.py / project_mvp_readiness_service.py / project_risk_assessment_service.py / space_capacity_assessment_service.py 直出服务已删除；MVP/风险/容量只能作为 PMFlowAIEvidenceToolRegistry 内的只读 evidence adapter 或 inspect_surface_context / inspect_project_status 的结构化证据进入 TurnState，输出事实、来源、置信度、目标相关性和缺口，不得直接生成 implication/judgement、不得决定 answer shape、不得早返回、不得靠 answer_contract/source_strategy/allowed_executors 或问句关键词抢链路。CustomerEvidencePacket.answer_type 已降为开放字符串承接 runtime answer_shape；CustomerAnswerPresentationService 只渲染 final TurnState 的 strategic_judgement / status_answer / clarification / execution_guidance / fact_list / composite_answer / general_answer，未知旧 packet 名称统一按 general_answer 表达。Composer/Verifier 只能消费 final TurnState/customer-safe packet，禁止消费 raw snapshot、字段名、trace 或 prompt key；返回 payload 带 answer_canvas / customer_interaction_context_packet / answer_process_packet，分别承接可展开内容、客户可见对象锚点和本轮真实执行步骤）
    • Packet U/V 后，CustomerAnswerPresentationService.build_answer_process_packet() 不再按 answer_type 生成固定过程步骤，只保留显式 process_steps/runtime_steps；_customer_source_summaries() 无来源时返回空列表，不再补 PMFlow 上下文。前端 SpaceAIConcierge 同步改为 sources 为空就不展示来源行，不再补 个人空间/PMFlow 上下文。
    • backend/app/services/adaptive_capacity_service.py（项目级容量读写边界仍归主链能力；Space AI 用户侧只能读取 space_capacity_packet.v1 作为 evidence fact，不通过独立容量问答服务直出答案，不写 override、不自动派任务、不请求审查、不写 ChangeSet）
    • backend/app/services/project_copilot_service.py + backend/app/api/pmflow_os_api/ + backend/app/schemas/pmflow_os.py（项目级 AI 副驾 truth-bound 入口：POST /pmflow-os/projects/{project_id}/project-copilot/ask 会按项目成员边界重建 PMFlow OS truth-state / execution summary，解析当前 surface + object_anchor，生成服务端权威 project_copilot_context_packet.v1、answer_canvas、客户对象锚点和过程包；当前 deterministic renderer model_calls=0，只做解释、候选建议、审查说明、执行交接准备建议和主流程路由，不写 thread message、不触发 extraction、不 commit ChangeSet、不写 Project Memory、不执行命令、不发布）
    • 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（platform AI Ops 的 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/（platform AI Ops 的 semantic facts 治理后台接口：overview / objects / detail / reextract / backfill）
    • backend/app/api/mcp_api/（MCP 模板接入中心后台接口：catalog / servers / validate / confirm-client-apply）
    • backend/app/api/ai_routing.py + backend/app/services/ai_routing_governance_service.py（AI 路由与供应商产品化控制台：团队策略接口属于客户空间 AI 使用设置；overview/admin-console/diagnostics/capability-slots 属于 platform AI Operations Console，要求 platform.ai_routing.manage；backend/.control_plane/pmflow-routing-rules.json 是 baseline rule pack，能力槽位保存到 integrations(type='ai_capability_slots')，但只有发布后的 active.slots 会被 runtime tier 解析消费，draft 只用于平台编辑/校验/发布；发布校验按 SLOT_REQUIREMENTS 检查供应商声明能力、capability_probe live evidence 与后端派生 effective_capabilities，缺能力、缺证据或证据过期返回 critical 并阻止 protected slot publish，长上下文声明窗口只算 declared_only 不算 verified，low 缺 probe 只 warning；团队策略只保存到 integrations(type='ai_team_policy')；在 API_ROUTE_PROFILE=lean 下也必须加载）
    • backend/app/config/ai_function_runtime_profiles.py + backend/app/services/ai_function_runtime_profile_service.py（Function Runtime Profile 配置真源；当前将 Project Launch 草案生成与 PMFlow Change Review 变更抽取的生成预算、修复预算、temperature、响应模式、前台等待、provider/job 超时、最大重试、大输入策略、冒烟结果和发布版本保存到 integrations(type='ai_function_runtime_profiles')，业务场景路由只展示场景内“生成运行合同”，运行时只消费已发布 active profile，draft 必须先 validate + smoke 再 publish；active profile 会实际控制 HTTP provider timeout、外层任务/调用超时、transient retry budget、large 输入预处理和前端 foreground wait 窗口）
    • backend/app/api/ai_call_traces_api.py + backend/app/services/ai_call_trace_service.py + backend/app/services/ai_scene_runtime_policy.py + backend/app/models/ai_call_log.py（platform AI Operations Console 的 AI 调用审计与场景超时策略入口；GET /ai-call-traces* 要求 platform.ai_routing.manage，只读 ai_call_logs，展示脱敏 prompt/response、provider/model/slot/routing meta、token/cost/latency、错误诊断和 runtime_policy；structured_timeout 必须独立展示为“模型超时”，不得与 JSON 无效/空响应混淆；llm_service 写入 trace_id / user_id / provider / model / latency_ms / routing_meta / prompt_key / prompt_release_id / prompt_source，并在 provider_request_payload / provider_response_payload / provider_attempts 保存真实上游 provider 请求、响应与重试尝试链；token 优先读取上游 usage.prompt_tokens/completion_tokens/total_tokens，没有 usage 时才使用兼容估算；AISceneRuntimePolicyService 为 Project Launch 等业务场景写入 provider_timeout_seconds / job_timeout_seconds / input_bucket 等显式策略；审计响应区分 raw provider code 与 provider_label/runtime_label/engine_name，并返回 function_label/scene_label 中文展示字段；DashScope 供应商编码统一为 dashscope，不得恢复旧 provider code；平台详情只展示完整脱敏 provider payload，不返回原始 headers 或密钥）
    • backend/app/api/prompt_assets_api.py + backend/app/services/prompt_assets_service.py + backend/app/services/prompt_runtime_service.py + backend/app/config/ai_prompt_registry.py + backend/app/config/ai_prompt_eval_rubrics.py（platform AI Ops 的 Prompt 运营中心；GET /prompt-assets* 要求 platform.ai_routing.manage，聚合 registry、默认 seed prompt、active/draft prompt_releases、prompt_release_checks 门禁状态、分层 prompt_golden_cases、prompt_replay_runs / prompt_replay_case_results、调用质量摘要、跨客户空间 PMFlow OS pmflow_ai_feedback_events 用户反馈、optimizer_candidates 优化候选、调用点和迁移状态；POST /prompt-assets/{prompt_key}/releases* 允许 managed_release 创建/激活/回滚，允许 guarded_release 创建候选版本但激活必须先通过 variable contract / schema smoke / golden replay 门禁；release replay 支持 contract_smoke 与 llm_compare，LLM replay 通过 llm_service 和显式 routing_meta 走本地路由层，结果记录 baseline/candidate AI call log、judge score/label/reason 与风险标记；non-blocking golden case 失败只进入 warning/人工复核，blocking case 失败才阻塞发布；PMFlow OS 负反馈只生成待复核 JudgeRun / OptimizerCandidate，不得直接改 active prompt 或自动发布；GET /prompt-assets/{prompt_key}/releases/{release_id}/watch-summary 提供 release 级 24h/7d 质量观察和健康/复核/回滚建议；inline_discovered / needs_migration 不能冒充已配置生效；运行时调用点通过 PromptRuntimeService 或 PromptReleaseService 读取 active release 并把 prompt_key/release/source 写入 AI 调用日志，格式失败回退默认模板；PMFLOW_SEMANTIC_CONTEXT_DECISION_PROMPT / PROMPT_PMFLOW_AI_TURN_GOAL_STATE_ASSESSOR / PROMPT_PMFLOW_AI_TURN_STATE_ANSWER_SYNTHESIZER / PROMPT_CUSTOMER_ANSWER_COMPOSER / PROMPT_CUSTOMER_ANSWER_VERIFIER / PROMPT_RAG_QUERY_SEMANTICS / PROMPT_RAG_FOLLOWUP_ANCHOR_SEMANTICS / PROMPT_RAG_PENDING_CLARIFICATION_SELECTION_SEMANTICS 已完成运行时迁移；PROMPT_PMFLOW_AI_ROUTE_PLANNER 只作为 legacy/deprecated prompt key 留在运营清单，不得被 Space AI runtime 调用）
    • backend/app/api/llm_engines.py（platform AI Operations Console 的“供应商与凭据”写入口，提供供应商新增/编辑/启用/删除/连通测试、能力矩阵声明 capabilities、registry-driven capability_probe runtime evidence、后端派生 effective_capabilities 与引擎设置；能力探测默认 full 覆盖 basic chat、结构化、JSON Schema、工具、流式和长上下文声明门禁，要求 platform.ai_routing.manage，API_ROUTE_PROFILE=lean 下也必须加载）
    • backend/app/api/model_routing.py（platform AI Operations Console 的隐藏 Route Lab 诊断接口，要求 platform.ai_routing.manage，API_ROUTE_PROFILE=lean 下也必须加载；运营导航不暴露函数级编辑入口）
    • backend/app/api/auth.py + backend/app/services/phone_auth_service.py + backend/app/models/phone_verification_code.py（手机号验证码登录、自注册与邀请绑定链路；users.phone_e164 是全局手机号身份，开发环境可返回 dev_code 便于本地验证）
    • backend/app/api/workspaces_api.py + backend/app/services/workspace_service.py + backend/app/models/tenant_membership.py + backend/app/models/tenant_invitation.py（solo-first/team-ready 空间成员兼容层：数据库沿用 tenants，产品语义为个人空间/团队空间；注册自动创建个人空间，手机号邀请加入团队空间不剥夺个人空间，退出团队后回到个人空间；backend/alembic/versions/20260428_repair_admin_yangyu_workspace_state.py 负责历史 admin/yangyu 当前空间与旧团队空间数据修复）
    • backend/app/api/space_api/ + backend/app/services/space_saved_idea_service.py + backend/app/schemas/space.py + backend/app/models/saved_idea.py（Personal Space 暂存想法真实闭环；saved_ideas 是 pre-project idea seed，只保存未成型想法、原始输入、来源、准备度、缺失问题、结构化 enrichment 元数据和草案关联，不写 Project Memory、ChangeSet 或执行回写；创建/编辑原始输入时尝试 space_saved_idea_enrichment_v1，prompt key 为 PROMPT_SAVED_IDEA_ENRICHMENT 并经 PromptRuntimeService 读取平台 active release、写入 prompt 归因；AI 失败显式落 ai_failed/system_baseline；promote 只生成 Project Launch 草案并回到人工确认链，确认前不创建项目）
    • backend/app/models/platform_membership.py + backend/app/services/platform_access_service.py（PMFlow 平台方账号平面：platform_memberships 和 env bootstrap 只给 PMFlow 内部 PLATFORM_ADMIN / AI_OPS 等角色发放 platform.* capability；客户空间 OWNER/REVIEWER 不等于平台管理员）
    • 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/）

frontend/
├── e2e/                       # Playwright 真实浏览器 E2E 用例
├── public/                    # 静态资源；`brand/` 是 PMFlow Logo / favicon 源资产
├── src/
│   ├── api/                   # 接口封装
│   ├── features/              # 新产品域与原型状态机（如 PMFlow OS / 个人空间 / 新项目启动台）
│   ├── pages/                 # 页面级组件（已目录化）
│   ├── components/            # 通用组件与 SSTC 等共享组件
│   ├── hooks/                 # 自定义 hooks
│   ├── lib/                   # 通用工具
│   ├── stores/                # 状态管理
│   ├── router/                # 路由
│   └── types/                 # TS 类型定义
├── package.json
├── playwright.config.ts
└── vite.config.ts
  • 当前前端重点入口优先看：
    • frontend/public/brand/ + frontend/public/avatars/ + frontend/src/components/brand/PMFlowLogo.tsx + frontend/src/components/brand/PMFlowUserAvatar.tsx（PMFlow Logo 源资产、系统默认头像资产，当前提供 3 张男性、3 张女性默认头像；应用壳、营销页、登录视觉和 favicon 不再各自手绘旧标，账号头像不再依赖随机外链头像）
    • frontend/src/api/（统一 API 封装）
    • frontend/src/router/index.tsx（顶层路由懒加载入口；登录页与 Layout 保持同步首屏；/command-center 保留免登录产品预览壳；/space、/space/ideas、/space/drafts、/space/projects、/space/settings/members、真实 /project-launch、/pmflow-os、/change-review、/structured-extraction、/memory-writeback-result 与 /me 均需登录；/project-launch?demo=1 或 ?dataSource=demo 是唯一匿名启动台演示入口；旧 /projects、/users*、/workloads* 和 /dashboard 只做兼容跳转；空间管理入口走 workspace role，/platform/* 和平台治理页走 platform_context.capabilities）
    • frontend/src/auth/RouteBoundary.tsx、frontend/src/lib/rbac.ts、frontend/src/lib/apiError.ts、frontend/src/lib/pendingIntent.ts（前端身份边界、workspace/platform capability 判断、产品化 API 错误分类与登录续接 pending intent 真源；用户可见 UI 禁止直接展示 Axios/FastAPI 原始 401/403/5xx 文案；pending intent 只能恢复输入或承接已生成的 Project Launch 草案，不得登录后自动重放真实写请求）
  • frontend/src/features/personal-space/（个人空间首页与空间二级收件箱；PersonalSpacePage.tsx 通过 frontend/src/api/space.ts 聚合项目摘要、PMFlow OS truth-state / execution-summary / execution-capabilities 与真实 GET /space/saved-ideas，并兼容消费旧 AI PMO waiting_manual / draft_pending_confirm 工作项，首页只预览暂存想法、草案箱和最近项目的少量高优先级条目；SpaceCollectionPages.tsx 承接 /space/ideas 暂存想法二级页和 /space/drafts 草案箱二级页，支持筛选、搜索、补充、归档、转 Project Launch 草案或回主流程确认；暂存想法只能推进到 Project Launch 草案确认链，不直接写项目真相层）
    • frontend/src/features/project-launch/（首次进入页 / 新项目启动台；默认调用真实 frontend/src/api/pmflowLaunch.ts draft job/revise/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 才启用本地演示状态机；components/ProjectCopilot.tsx 是项目级 AI 副驾统一入口，承接项目壳弹出副驾和 CommandCenter / WorkGraph / ProjectMemory / TeamLayer / ReleaseGrowth / ExecutionBridge 的上下文副驾投影，真实模式下副驾追问/补充/指令调用 frontend/src/api/pmflowOs.ts::askPMFlowProjectCopilot 与后端 POST /pmflow-os/projects/{project_id}/project-copilot/ask，不再走 thread message + extraction；页面级副驾不得再用静态 demo 内容补位；ChangeReviewAiCopilotPanel 保留为 ChangeSet 审查专用派生面板）
    • 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/D10 真实路径；提供 truth-state、execution-summary、thread message、proposed_items extraction、ChangeSet detail、ChangeItem accept/edit/defer、ChangeSet commit、review decision、execution handoff/progress writeback、execution runtime credential、signed runtime package pull、signed runtime result ingest、execution acceptance decision、execution memory writeback、release validation run、release feedback ingest、Team reviewer routing、recommendation change-set draft 与 recommendation group change-set draft；项目主链“发送并提取”使用独立 change_review protected scene、pmflow_change_review_extraction_v1 Function Runtime Profile 与 PROMPT_PMFLOW_CHANGE_REVIEW_EXTRACTION，不再复用 Project Launch draft prompt/function；复用 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；D9 新增 PMFlowExecutionRuntimeCredential 和 pmflow_execution_runtime_credentials migration，D10 新增签名执行包领取，运行端签名拉包只返回执行上下文，签名回流只记录执行事实 metadata，不执行命令、不发布、不写 Project Memory；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；POST /pmflow-os/projects/{project_id}/execution-memory-writebacks 只允许在执行证据与验收通过后写 execution_memory_writeback_v1 ProgressEvent，release gate 必须等该写回完成才 ready；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 真实创建链；draft-jobs/revise 写 pmflow_launch_draft_jobs 并任务化生成草案，兼容 drafts 只写 pmflow_launch_drafts，confirm 在同一事务写真实 Project、启动线程、启动消息、初始 truth_nodes、tasks 与 semantic_facts seed）；backend/app/api/legacy_ai_steward_api.py 仅保留旧文本创建接口的 410 迁移响应，并在 lean profile 下始终挂载
    • 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/ai-steward/（历史 AI Steward 页面迁移占位；/ai-steward 只做 legacy redirect，不再作为产品入口）
    • frontend/src/components/ai-steward/（AI 问答共享展示组件与旧问答浮窗兼容代码；当前产品壳不再全局挂载 FloatingQAChat，空间页由 frontend/src/features/personal-space/components/SpaceAIConcierge.tsx 承接入口，并复用 QAMarkdownContent 等展示能力）
    • backend/app/api/ai_readiness_api/ + backend/app/services/ai_readiness_service.py + frontend/src/api/aiReadiness.ts + frontend/src/features/ai-readiness/（空间级 AI 就绪合同；由 /space、真实 /project-launch、项目级 AI 副驾、/ai-config?tab=setup 与 /platform/* 共同消费；Project Launch readiness 默认由后端从平台运行租户供应商、published active structured 槽、scene registry、能力证据和最近 24h pmflow_launch_draft_v1 日志推导；单次最近生成失败只作为平台 warning，24h 内已有成功且连续失败少于 3 次时用户端仍保持可生成，连续失败达到阈值才进入 recovering；本机状态只允许 test 或 VITE_AI_READINESS_LOCAL_OVERRIDE=true 覆盖；平台 AI Ops 可触发不写草案/项目的结构化 smoke，该 smoke 固定以平台运行租户执行并作为全局恢复证据）
    • frontend/src/pages/ai-config/AIConfigPage.tsx + frontend/src/pages/ai-config/constants.ts + frontend/src/pages/ai-config/components/AISetupWizard.tsx（空间级 AI 使用设置；/ai-config 及其子路由必须使用空间配置壳 SpaceSidebar + SpaceTopBar，不得切入项目工作台侧栏；/ai-config?tab=setup 是 AI 可用状态与项目生成能力门禁入口，连接、知识、团队策略和 Prompt 策略继续承载客户空间 AI 使用治理；平台供应商、全局路由、route/context、semantic facts 不在客户空间暴露，只有带 platform_context.capabilities 的平台 AI Ops 才能看到供应商/路由/诊断 CTA）
    • frontend/src/pages/ai-routing/ + frontend/src/api/aiRouting.ts + frontend/src/api/aiSteward.ts + backend/app/services/ai_routing_scene_contracts.py（TeamAIPolicyPage.tsx 是客户空间负责人策略视图；PMFlow 平台 AI Ops 运行总览已合并进 /platform，旧 /platform/ai-routing-console 只做兼容跳转；AI 运行层保留明确子菜单：/platform/ai-routing-providers 供应商与凭据、/platform/ai-routing-slots 能力槽位、/platform/ai-routing-scenes 业务场景路由、/platform/ai-routing-costs 成本/配额/缓存、/platform/ai-routing-failures 失败诊断；业务场景路由是 Scene Contract & Impact Console，只读展示后端 scene_contract、场景健康度、release gate、active/draft runtime、能力缺口、发布影响、筛选排序和确定性修复动作，不在运营页展开函数名；sceneContracts.ts 仅作为后端合同缺失时的前端 fallback；供应商页展示并编辑 capabilities 能力矩阵，能力槽位页展示 active 当前版本、draft 编辑区、发布校验、发布阻塞、能力覆盖/缺口与回滚动作；业务场景路由的修复动作会 deep-link 到槽位、供应商和失败诊断页并自动聚焦 scene/slot/capability；共享实现集中在 AIRoutingOperationsPages.tsx，继续只消费脱敏 admin-console 聚合数据）
    • frontend/src/pages/platform/AICallTracesPage.tsx + frontend/src/api/aiCallTraces.ts（PMFlow 平台 AI Ops 的 AI 调用审计页面；入口 /platform/ai-call-traces 位于“质量与事件层”，支持按状态、供应商、模型、函数、业务场景、能力槽位、prompt_key、prompt_source、trace、时间窗口和关键词筛选，列表展示脱敏预览，详情展示 prompt 版本归因、完整脱敏 provider 请求/响应 payload、上游尝试链、失败归因、场景 timeout 策略和建议动作；prompt-attributed 详情可一键沉淀 Golden case；客户空间、Space、Project Launch 和项目级 AI 副驾不得暴露该入口）
    • frontend/src/pages/platform/PromptAssetsPage.tsx + frontend/src/api/promptAssets.ts（PMFlow 平台 AI Ops 的 Prompt 运营中心；入口 /platform/prompt-assets 位于“质量与事件层”，展示 prompt key、业务场景、family、风险、发布策略、默认模板、active release、draft 数、门禁状态、最新 replay、调用点和迁移缺口；详情弹层承载基础信息、模板 Diff、版本历史、发布门禁、回放评审、质量归因和运行信息，managed_release 可创建草稿/激活/回滚，guarded_release 可创建候选、运行契约回放或 LLM 回放并通过门禁后激活；回放结果展示 judge score/label/reason、baseline/candidate call id、风险标记，右侧发布概览展示 release watch 建议；质量归因页可查看 7 天调用、失败、默认回退、成本估算、PMFlow 用户赞同/不赞同反馈、负反馈原因、优化候选、失败样本 deep-link，并从失败调用生成带 case_type/priority/scenario/tags 的 golden case；待迁移项只读并展示原因；客户空间、Space、Project Launch 和项目级 AI 副驾不得暴露 prompt 正文）
    • frontend/src/pages/model-routing-config/（隐藏 Route Lab；入口 /platform/route-lab，旧 /platform/model-routing-config、/ai-config/model-routing-config 与裸 /model-routing-config 仅兼容跳转；页面只读展示函数级规则、最近执行与历史 override 痕迹，不在平台侧栏中暴露）
    • frontend/src/pages/ai-config/mcp-config/（AI 使用设置 -> MCP 模板接入中心）
    • frontend/src/pages/platform/PlatformChrome.tsx + frontend/src/pages/platform/PlatformConsolePage.tsx（PMFlow 平台 AI Operations Console 专属应用壳与首页；/platform/* 不复用旧项目工作台侧栏/顶部条，侧栏按“运行总览 / AI 运行层 / 工具与外部能力层 / 上下文与语义层 / 质量与事件层”组织，只展示当前 platform capability 可进入的运营工具；旧 /ai-config/* 平台诊断路径只做兼容跳转）
    • frontend/src/pages/query-route-governance/（platform AI Operations Console -> route/context 治理页）
    • frontend/src/pages/semantic-facts-board/（platform AI Operations Console -> semantic facts 治理页）
    • frontend/src/components/layout/LazyBoundary.tsx（统一 route/page-section/dialog 级 loading skeleton）
    • frontend/src/components/login/（公开登录页组件目录；LoginExperience.tsx 负责双栏登录壳，LoginForm.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、AI Steward QA 组件与 Recipes/Projects/Users 等模块化拆分的详细库存见库存文档；旧独立收件页已退场，待处理能力收敛到 /space、/change-review、/team-layer 与 /me。
  • 顶层路由已改为 React.lazy + Suspense，统一 fallback 使用 frontend/src/components/layout/LazyBoundary.tsx；/ai-steward 只保留迁移重定向，tab=create 迁到 /project-launch，tab=engine 迁到 /ai-config，tab=feedback-center 有 project_id 时迁到 /release-growth?projectId=<id>、否则迁到 /space，其它 legacy tab 迁到 /space；AI 使用设置页面按 active tab 只渲染当前可见区块，Projects/Users/图表页则把重对话框与图表从同步入口拆出。
  • frontend/src/features/ai-readiness/ 是空间级 AI 就绪状态前端合同：types.ts 定义状态与 blocker，readiness.ts 负责角色权限、后端 readiness 查询、test/dev override 和 useAIReadiness()，components.tsx 提供顶部状态胶囊与卡片。真实门禁以 GET /ai-readiness/project-launch 为准；localStorage 只允许测试或显式本地覆盖，不再作为生产 readiness 真源。
  • frontend/src/features/project-launch/ 是新项目启动台独立产品域，也是新建项目唯一用户入口：types.ts / useProjectLaunchState.ts 承载状态合同和真实 API 编排，真实模式必须登录并优先调用 POST /pmflow-launch/draft-jobs 创建 AI 草案生成任务，轮询 GET /pmflow-launch/draft-jobs/{job_id} 获取完成草案，确认后调用 POST /pmflow-launch/drafts/{draft_id}/confirm 创建真实项目并跳转 /pmflow-os?projectId=<id>；“补充一句”通过真实输入弹层创建 merge_supplement revision，已有草案时调用 POST /pmflow-launch/drafts/{draft_id}/revise，运行中的旧 job 由后端标记 superseded，禁止硬编码追加补充句或用 UI 暂停动画冒充 AI 可暂停/续写；旧 POST /ai-steward/project-from-text 只返回 410 迁移错误，不得绕过草案确认直接写正式对象；mockData.ts 只在显式 ?demo=1 或 ?dataSource=demo 匿名演示模式下使用，真实模式的进度、操作流、审查建议、附件引用和计数必须来自当前输入、后端 job/草案、warnings/evidence，不得展示 DevWeekly 周报 demo 内容。401/无 token 不得展示 Request failed with status code 401 或归类为网络异常，必须保存输入到 pending intent 并提示重新登录后继续。真实模式下若 AIReadiness.canGenerateProjectDraft=false，LaunchShell 渲染 AISetupRequiredPanel，用户端默认只看到“先记录项目想法，AI 草案生成暂不可用”的客户视图；空间负责人可查看空间 AI 状态，平台 AI Ops 可通过显式平台诊断卡查看具体 cause/CTA；不提供空项目创建入口，避免在缺少结构化上下文时提前创建项目壳；低信息输入（如纯问候、缺少产品/用户/问题线索）由后端 input_needs_more_info 422 门禁拦截并回到补充输入态；demo 模式不受该门禁影响。LaunchShell 桌面端复用 frontend/src/features/personal-space/components/SpaceChrome.tsx 的空间左侧栏和顶部条，主画布仍由 IntentInputPanel / AIProgressCanvas / HumanReviewCanvas / DraftEditCanvas / FailureStatePanel / SuccessTransitionPanel 承接，移动端仍由 MobileLaunchLayout 承接；frontend/src/pages/ProjectLaunchPage.tsx 仅做薄入口。
  • Project Launch 的“保存为暂存想法”必须调用 POST /space/saved-ideas 写真实 saved_ideas，成功后 /space#saved-ideas 可见；它只保存 pre-project idea，不生成草案、不创建项目、不写项目记忆。保存/完善时会优先用 PROMPT_SAVED_IDEA_ENRICHMENT 走 Prompt 运营中心 active release 做结构化完整度判断，返回 enrichment_status / enrichment_payload / missing_questions / readiness_score；问候、测试词或无实质想法输入必须判为 needs_more_info 和 0 准备度；AI 不可用时只能显式显示系统初判，不冒充 AI 结论。/space 里点击“生成项目草案”才调用 POST /space/saved-ideas/{idea_id}/promote，生成 draft 后通过 pending intent 进入 Project Launch human_review，仍需用户确认才创建正式项目。
  • frontend/src/features/personal-space/ 是登录后的空间层入口：PersonalSpacePage.tsx 承接桌面个人工作面与独立移动单手布局，frontend/src/api/space.ts 只读聚合 projects summary、PMFlow OS truth-state、execution-summary、execution-capabilities，并兼容消费旧 AI PMO waiting_manual / draft_pending_confirm 工作项，生成 nextActionQueue 我的下一步队列、执行准备度、我的今日容量、继续推进、待确认、review attention、发布关注、发布后反馈关注、下一轮迭代草稿关注、AI 正在推进、草案箱、缺项目归属补全、最近项目摘要；这些空间聚合以后端项目可见性为准，OWNER/REVIEWER 看租户级团队视图，BUILDER/OPERATOR 只看本人拥有或 user_projects 绑定项目，legacy 工作项只看本人拥有或本人项目绑定项。未登录访问 /space 必须跳登录，不展示个人空间语义。Space 首屏消费 frontend/src/features/ai-readiness/ 双层合同：用户端默认显示客户可理解的 AI 可用状态、业务影响和可继续动作，普通成员/空间负责人/平台人员进入用户端都不默认看到供应商、路由、连接测试、模型槽位、trace 或函数名；空间负责人额外看到空间 AI 状态、团队策略和工具连接入口；平台 AI Ops 仅通过显式平台诊断卡或 /platform/* 查看具体 cause/CTA。顶部条展示统一 readiness pill，管理员侧边栏显示 /ai-config?tab=setup 与 /space/settings/members 入口；/space/projects 是所有项目视图，旧 /projects 只做兼容跳转。components/SpaceAIConcierge.tsx 是空间级 AI 管家入口：只围绕个人空间、跨项目下一步、待确认、执行中、草案、暂存想法和 AI 能力状态工作，通过 /space/ai-concierge/* 产品接口注入空间上下文包并复用 QA 历史/会话能力；前端不得直接依赖 optional /rag/* 路由，历史读取失败只影响历史视图，不阻断新会话提问；真实写操作只能给跳转或待确认建议，不声称已执行。全局 Layout 不再挂载旧 FloatingQAChat 悬浮球，项目页仍使用项目级 AI 副驾。Space 左侧导航只承载稳定空间目的地，当前保留“空间首页”“所有项目”和管理员“AI 使用设置 / 成员与权限”；最近项目、暂存想法、草案箱、待我确认、AI 正在推进属于空间首页内部工作台模块，不作为一级侧栏导航。Space P6 的下一步队列按高风险待确认、发布阻塞/失败证据、handoff consumed 后缺少后续 progress、下一轮 draft、发布后反馈/收入/合规信号排序；Space P7 新增 review_attention，只读消费 truth-state.reviewerRouting，按高风险待我审、request_changes / rejected 后待处理、reviewer_missing warning、普通 pending review 排序进入“我的下一步”；旧 missing_project_scope 只允许在 Space 选择项目后复用 POST /ai-pmo/work-items/{id}/decision 继续既有审计链，不新增旁路接口，不直接写项目真相层。动作只跳 /change-review?projectId=<id>&changeSetId=<id>、已有 /team-layer?projectId=<id>、/execution-bridge?projectId=<id>、/release-growth?projectId=<id> 或复用旧工作项决策 API；执行准备度只读展示工具连接、待确认、待审查、待验收和阻塞原因，今日容量只读展示有效容量、人工触点、剩余容量、动态建议结构、系统解释和 AI 预处理可释放时间，不写项目业务对象；Space P3/P4/P5 仍只读消费 release validation 与 releaseSignals；不在 Space 写 Project Memory、PMFlowApproval、ProgressEvent、ReleaseValidationRun、FeedbackIngest、RevenueEvent、ComplianceCheckRun、ChangeSet 状态、容量 override 或发布执行，不虚构 reviewer、审查意见、待审 ChangeSet、工具连接、执行能力或容量计划。components/SpaceChrome.tsx 承接空间层左侧栏、顶部条与空间用量组件；/project-launch 桌面首次新建壳复用同一空间 Chrome，但不在左侧展示工作台区块 badge；frontend/src/pages/PersonalSpacePage.tsx 仅做薄入口。 - Space AI Concierge 用户侧边界：frontend/src/features/personal-space/components/SpaceAIConcierge.tsx 通过 /space/ai-concierge/ask 传原始问题 + 结构化 surface_context，后端先用 SpaceRuntimeContextBuilder 重建可见项目、任务计数、暂存想法和下一步摘要，然后直接进入 PMFlowAITurnRuntimeService.run_space_turn()。该入口只回答 PMFlow 产品/操作、当前租户项目与空间状态、下一步指导和带来源的外部公开信息；入口不得先由 route planner、TaskGraph、execution contract 或 analyzer 分支抢主控。interaction_submission 只转成 PMFlowAITurnDelta 的原始问题、answers 和 supplement，旧 intent_hint / evidence_mode / primary_subject 推导字段已从 schema 删除，禁止按 question_id、按钮文案、中文关键词或选项值推导 intent/source/subject。PMFlowAITurnState 的 evidence_needs + sufficiency_state 决定 surface/internal/external/synthesize/clarify action；可见项目只能作为 context object，不能自动替代 primary object。Packet 8/9 的行为回归由 backend/app/config/pmflow_ai_turn_runtime_golden_cases.py、backend/app/services/pmflow_ai_turn_runtime_golden_replay.py 与 backend/tests/test_pmflow_ai_turn_runtime_golden_replay.py 锁定，scripts/semantic_lint.py 负责阻止旧推导字段和散落语义拍板回流。代码、内部架构、数据库表、prompt key、trace、函数名、模型供应商和 raw source label 只能在 /platform/* 诊断侧出现。最终答案由 CustomerAnswerPresentationService 基于 customer-safe packet 生成，不能把 raw snapshot 或字段名喂给用户侧 composer；前端先显示普通聊天气泡，用户点 quick_actions 后再展开 answer_canvas，answer_process_packet 可带步骤耗时用于前端归因展示。
    • Space AI 旧 analyzer 边界：space_ai_task_graph_service.py / space_ai_execution_contract.py / pmflow_ai_runtime_kernel.py / pmflow_ai_conversation_orchestrator.py 已删除。项目查找、状态、风险、容量、MVP 等能力都必须先由 TurnState 判断目标、对象锚点和证据缺口，再按白名单 evidence tool 读取证据。工具只读返回 facts/findings/gaps/sources，不写 Project Memory、不提交 ChangeSet、不写 review decision、不发起执行、不发布、不自动派任务、不写 capacity override。
    • 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) 提醒强度消费合同，以及 getReviewDecisionNotificationPreference(settings, event) review decision 偏好合同；支持 reminderIntensity=silent|normal|prominent 与 evidenceDisplay=compact|expanded，并覆盖 review_requested / review_approved / review_changes_requested / review_rejected / high_risk_approval_required；releaseGate / failureAlert / pendingConfirmation / executionWriteback 只影响页面内提醒表达强度和证据展开方式，不代表真实邮件、桌面推送或系统通知中心已接入，也不得隐藏真实业务证据、reviewerRouting、approval 或审计状态，不改 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、execution acceptance decision、execution memory writeback、release validation run create、release feedback ingest、单条 iteration recommendation -> ChangeSet draft、同组 iteration recommendation 批量 -> ChangeSet draft、capacity-plan 与 capacity override simulate/apply API，成功后 refetch truth-state / execution-summary / capacity plan；显式 ?demo=1 才启用本地演示状态机。pages/ 下包含 CommandCenter / StructuredExtraction / ChangeReview / MemoryWritebackResult / WorkGraph / ExecutionBridge / ReleaseGrowth / TeamLayer / ProjectMemory / Account 主页面；ChangeReviewPage 真实模式可请求审查、通过、要求修改或拒绝当前 ChangeSet，展示审查状态、建议 reviewer、审查意见和 high-risk approval gate，但不自动 commit；其顶部识别统计、待确认列表和右侧 AI 副驾评估只能由后端 changeSets / changeItems / evidence 派生，没有真实待审项时显示空态，不得用 demo 的知识库搜索、混合召回、固定风险/建议/计数补位；TeamLayerPage 真实模式读取 state.reviewerRouting、execution-capabilities 与 capacity-plan，展示待审 ChangeSet、建议 reviewer、审查状态、执行能力、个人执行准备度、工具准备度、团队今日容量、动态基线、瓶颈、AI 预处理建议、负责人模拟/应用容量 override 与调整记录；capacity override 只写审计，不自动分派、不自动审查、不写 ChangeSet；ExecutionBridgePage 已支持创建 handoff、运行端领取确认、执行进度回写、验收拍板与“回写项目记忆”动作，验收通过不再被当成 Project Memory 写回；ReleaseGrowthPage 真实模式展示 execution-summary.releaseGate、execution evidence、阻塞原因、下一步动作、latestValidationRun 和 releaseSignals，release gate 只有测试、验收与 execution_memory_writeback 证据齐备才 ready；静态发布/增长原型仅保留在显式 demo 模式；后端只记录 review decision/progress/release gate/release validation/release feedback/recommendation draft/capacity override 元数据，不执行本机命令、真实发布命令、外部支付、真实推送、自动 Project Memory commit、自动任务分配或正式任务创建；ProjectMemoryPage 在真实模式优先消费后端 project-memory/overview 读模型，二级页承接 /project-memory/items|assets|context-packs|writebacks，单条点击进入右侧抽屉；读模型失败时才降级展示 truth-state.projectMemory 兼容投影。components/ 下除了 ProjectStageRail / ThreadComposer / ExtractionRail / ChangeGroupPanel / ObjectGraphSection / ContextPacketPanel / ExecutionTimeline / ReleaseGatePanel / TeamFeedPanel 之外，新增 ProjectStructuredLoop / PMFlowOsFrame / AccountControls / FeedbackPrimitives 等行为组件；components/MobileBottomNav.tsx 是正式应用壳唯一移动底部导航，固定为 空间 / 指挥台 / 待确认 / 动态 / 我的。
  • ProjectTruthState.feed 现在是 Team Feed 只读动态流，由 backend/app/services/pmflow_os_projection_service.py 聚合 review request、review decision、ChangeSet 状态、execution progress 与 release gate 事件；TeamLayerPage 复用 TeamFeedPanel 展示 state.feed，只做摘要、空态和跳转，不写审批、不写 ChangeSet、不写通知，也不在真实模式用 mock 动态补齐。
  • 旧登录实现 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. 运行命令（高频）

根目录

./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。
  • 当前新增的 requirement-plan 历史修复工具位于 backend/scripts/repair_requirement_plan_history.py，默认 dry-run，仅在显式 --apply 时写回 mounted_draft_workspaces / mounted_topic_workspaces。

前端

cd frontend
npm run dev
npm run build
npm test
npm run e2e:feishu

后端（本地直跑）

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。
  • 当前最重要的摘要只保留：
    • 写操作必须经 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。
  • 当前只保留高价值摘要：
    • 新增后端接口：优先参考 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。
  • 当前高价值摘要只保留：
    • 飞书回调字段可能缺失文件名/大小，仅保证 attachment_id/key/type 可用。
    • 真实飞书网页 E2E 依赖本机已登录的 Chrome/Feishu 会话，结果校验统一走数据库探针。
    • 路由配置唯一真源固定为 backend/.control_plane/pmflow-routing-rules.json；普通 LLM 请求超时以 LLM_REQUEST_TIMEOUT 为默认，保护型结构化场景以 Function Runtime Profile active 合同里的 provider_timeout_seconds 为准。
    • World Model 静态层已接入 Redis 缓存（wm:static:{tenant_id}:{project_id}，TTL 600s），写操作后主动 invalidate，动态层不缓存。
    • signal_sources 仅作为历史创建结果区的兼容展示字段；项目看板与 SSTC 信号阶段统一只读正式 Signal。

12. 技术债务清单

  • mixin_auto.py _safe_int NameError：已通过显式导入 _safe_int + 回归测试锁定，避免后续共享导出调整导致运行时未定义
  • AI 入口主链已统一：飞书长连接（capture_from_feishu）、/ai-pmo/process-text、/space/ai-concierge/ask 与 /rag/ask 已统一收敛到 AIPMOKernelService.process_ingress 主链；/rag/ask 通过 rag_ask_contract.build_kernel_ingress_kwargs 透传 RAG 上下文（session_id/new_session/thinking_mode/action_mode/surface_context/...），query 执行后由 build_rag_response_payload 保持 HTTP 响应兼容，客户侧即时响应再经 sanitize_customer_rag_payload() 清洗，回归由 test_rag_route_contract.py、test_ai_pmo_qa_http_mainline_e2e.py、test_ai_pmo_ingress_mainline.py 锁定
  • Unified Project Operating Context 已接到问答入口：/rag/ask、/space/ai-concierge/ask、/ai-pmo/process-text 与 kernel ingress 现会先透传最小 project_operating_context（当前项目、当前仓库摘要、页面/线程锚点），Space 入口额外透传 surface_context 并在客户响应暴露 tenant_project_context_packet / research_contract；AdaptiveRAG 的 Query Route Gateway 进一步产出 execution_recipe；external 主链会在需要时补 fit_brief，回答 payload 同步暴露 project_operating_context / execution_recipe / fit_brief / external_recommendation / external_project_fit_packet / 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 锁定
  • Query/RAG 路由语义与客户展示 prompt 已迁移到 Prompt 运营中心运行时：pmflow_semantic_context_decision 通过 SemanticDecisionService 读取 PMFLOW_SEMANTIC_CONTEXT_DECISION_PROMPT active release；pmflow_ai_route_planner / customer_answer_composer / customer_answer_verifier / rag_query_semantics / rag_followup_anchor_semantics / rag_pending_clarification_selection_semantics 通过 PromptRuntimeService 读取对应 active release，并在 ai_call_logs.routing_meta 写入 prompt_key / prompt_release_id / prompt_source。
  • 飞书入口层耦合已收敛：飞书真实入口已拆为三段职责链（预处理 mixin_receive_prepare.py / capture 执行 mixin_receive_capture_flow.py / 编排 mixin_receive.py）；mixin_receive.py 不再混合传输解析、附件标准化、capture 异常兜底与收尾回执逻辑，分层边界通过 test_feishu_receive_orchestration_contract.py 锁定
  • 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 回归锁定
  • task.create 已接入消息级幂等账本：Feishu source_message_id/feishu_message_id 作为 task.create 账本 key，重复确认只回放同一结果，不再重复落库；回归由 test_feishu_pipeline_queue_contract.py 锁定
  • 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 锁定
  • AdaptiveRAG 职责已完成首轮收敛：answer_question 入口已分层为 prepare runtime 与 base mainline 两段，写确认逻辑通过 _should_trigger_write_ack_gate 独立门控；基础问答主路径不再与写确认判断混写在同一函数体。分层契约由 test_adaptive_rag_mainline_contract.py 锁定（read 绕过 ack、write 命中 ack、feishu write 维持主链）
  • 执行层已形成统一执行账本与参数来源约束：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 锁定
  • 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 已锁定回归
  • 三模式交互上下文基线已显性化：/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，旧独立收件页已退场，相关待处理状态由 Space 兼容读模型消费
  • AI 管家浮窗交互已与 Grounding Runtime 对齐：回答区已切到 markdown 渲染，顾问标签升级为显式交互按钮；consultant_mode_preference 只用于 /rag/ask 内部重答，允许执行 明确交接到 /ai-pmo/process-text，避免 query/execute 边界回退到旧的一锅煮
  • 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 锁定
  • 语义治理 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 做仓库级守门。Space Turn Runtime 额外禁止 PMFlowAITurnDelta 恢复 intent_hint / evidence_mode / primary_subject 旧推导字段，并通过 pmflow_ai_turn_runtime_golden_cases.py / PMFlowAITurnRuntimeGoldenReplay 按行为合同回归，不以固定答案文本或场景枚举为基线
  • 结构化 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 证据/回放兼容壳。后续需在历史存量清空后正式封存该兼容层
  • AdaptiveRAG 向量检索 legacy fallback 已移除：AdaptiveRAGRetrievalVectorMixin._retrieve_vector_context() 现在只支持 PostgreSQL/pgvector 主路径；非 PostgreSQL 或 PG 查询失败时直接返回空结果，不再回退 Python 侧 legacy 扫描，边界由 test_adaptive_rag_mainline_contract.py 锁定
  • 历史 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} 响应包络，否则应明确标注为非核心示例模块
  • LLM 运行时仍未完全收敛：ai_service_core._invoke_with_retry 与 stream_chat 已统一走 llm_service；旧 _get_llm 路径已显式禁用，并补回归测试锁定
  • 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 形成稳定回归基线
  • 飞书交互闭环已补齐：执行场景回执在 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 回归契约