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

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

5. 前端结构（frontend/）

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

5.1 frontend/src/components/sstc/ 目录说明（模块化拆分后）

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

5.2 修改前必须执行 FIND_USAGE 的 SSTC 组件清单

  • SSTCWorkspace.tsx
  • useSSTCWorkspaceOrchestration.ts
  • sstcUtils.ts
  • SSTCCharterStagePanel.tsx
  • SSTCSignalStagePanel.tsx
  • SSTCTaskStagePanel.tsx
  • SSTCExecutionBoardPanel.tsx
  • SSTCReleaseStagePanel.tsx
  • SSTCReviewStagePanel.tsx
  • SSTCReleaseCreateDialog.tsx
  • SSTCReviewCreateDialog.tsx
  • SSTCTaskCreateDialog.tsx

6. 运行命令（高频）

根目录

./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_REQUEST_TIMEOUT 为准。
    • World Model 静态层已接入 Redis 缓存（wm:static:{tenant_id}:{project_id}，TTL 600s），写操作后主动 invalidate，动态层不缓存。
    • signal_sources 仅作为 AI Steward 创建结果区的内联展示；项目看板与 SSTC 信号阶段统一只读正式 Signal。

12. 技术债务清单

  • mixin_auto.py _safe_int NameError：已通过显式导入 _safe_int + 回归测试锁定，避免后续共享导出调整导致运行时未定义
  • AI 入口主链已统一：飞书长连接（capture_from_feishu）、/ai-pmo/process-text 与 /rag/ask 已统一收敛到 AIPMOKernelService.process_ingress 主链；/rag/ask 通过 rag_ask_contract.build_kernel_ingress_kwargs 透传 RAG 上下文（session_id/new_session/thinking_mode/action_mode/...），query 执行后由 build_rag_response_payload 保持 HTTP 响应兼容，回归由 test_rag_route_contract.py、test_ai_pmo_qa_http_mainline_e2e.py、test_ai_pmo_ingress_mainline.py 锁定
  • Unified Project Operating Context 已接到问答入口：/rag/ask、/ai-pmo/process-text 与 kernel ingress 现会先透传最小 project_operating_context（当前项目、当前仓库摘要、页面/线程锚点），AdaptiveRAG 的 Query Route Gateway 进一步产出 execution_recipe；external 主链会在需要时补 fit_brief，回答 payload 同步暴露 project_operating_context / execution_recipe / fit_brief / external_recommendation / analysis_packet / recommended_next_step / handoff_mode，回归由 test_project_operating_context_contract.py、test_rag_route_contract.py、test_ai_pmo_qa_http_mainline_e2e.py、test_external_query_planner.py、test_mcp_external_query_bridge.py、test_adaptive_rag_mainline_contract.py、test_analysis_packet_contract.py 锁定
  • 飞书入口层耦合已收敛：飞书真实入口已拆为三段职责链（预处理 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 到 Inbox 展开区，回归由 test_ai_pmo_qa_http_mainline_e2e.py、test_ai_pmo_ingress_mainline.py、FloatingQAChat.test.tsx、QAResponseMetaCard.test.tsx、InboxListItem.test.tsx 锁定
  • 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 做仓库级守门
  • 结构化 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 回归契约