329 lines
100 KiB
Markdown
329 lines
100 KiB
Markdown
# 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 已完成 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/`）
|
||
```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`、`/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/`）
|
||
```text
|
||
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. 运行命令（高频）
|
||
### 根目录
|
||
```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 请求超时以 `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. 技术债务清单
|
||
- [x] `mixin_auto.py` `_safe_int` NameError：已通过显式导入 `_safe_int` + 回归测试锁定，避免后续共享导出调整导致运行时未定义
|
||
- [x] 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` 锁定
|
||
- [x] 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` 锁定
|
||
- [x] 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`。
|
||
- [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`，旧独立收件页已退场，相关待处理状态由 Space 兼容读模型消费
|
||
- [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` 做仓库级守门。Space Turn Runtime 额外禁止 `PMFlowAITurnDelta` 恢复 `intent_hint / evidence_mode / primary_subject` 旧推导字段，并通过 `pmflow_ai_turn_runtime_golden_cases.py` / `PMFlowAITurnRuntimeGoldenReplay` 按行为合同回归，不以固定答案文本或场景枚举为基线
|
||
- [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` 回归契约
|