PMFlow/CLAUDE.md

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

1. Agent 入口文件（你关心的“进项目先读什么”）

• AGENTS.md：Codex/Coding Agent 的主规则入口（优先级最高的项目级约束）
• CLAUDE.md：面向 Claude 风格的项目说明文档（补充背景）
• 建议：规则放 AGENTS.md，架构/目录说明放 CLAUDE.md
• 当前 AI 行为的系统宪章已在 AGENTS.md 中升级为“事实层 / 评审层 / 生成层 / 执行层”四层分治；所有新增 AI 业务默认按该宪章接入。CLAUDE.md 当前承载的是“架构说明 + 运行边界 + 目录库存”，不再假定自己只包含背景说明
• 新增执行约定：计划类需求一旦确认进入实现阶段，默认连续执行到“实现完成 + 验证完成 + 统一回复验收结果”；仅在明确阻塞、高风险冲突、context 限制或用户主动中断时才中途打断。
• 新增 bugfix 执行约定：缺陷修复/回归修复允许跨多个直接相关文件端到端完成，不再按文件数硬性拆分；但必须同时满足“改动范围围绕同一根因”“不夹带无关重构”“最终附带编译/测试验证”。大功能开发或结构性重构仍优先按子任务拆分。
• 新增发布约定：凡后端代码或数据库迁移发生改动，完成编译/测试后必须继续执行当前环境对应的热部署/重启/重载步骤，确认服务已加载新版本；若当前机器不是部署环境、缺少权限或不具备热部署条件，必须在结果中明确说明未执行原因与阻塞点，禁止默认省略。
• 下面各节中大量 新增/更新/移除 清单用于保留“当前架构库存”和关键入口索引，不等同于运行时主规范；行为约束与禁止项仍以 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。
• 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/superpowers/plans/ 保存实现计划，docs/task_briefs/ 保存任务包产物与验收截图。

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/adaptive_rag_service/（只读问答主链）
  • backend/app/services/llm_service/（显式 routing_meta 协议）
  • backend/app/services/integrations/feishu_integration_service/（飞书入站与卡片回调）
  • backend/app/services/signal/（信号接入、编排、planner、repair）
• 详细目录迁移、兼容壳清理与新增模块清单见库存文档。

5. 前端结构（frontend/）

frontend/
├── e2e/                       # Playwright 真实浏览器 E2E 用例
├── src/
│   ├── api/                   # 接口封装
│   ├── 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/pages/inbox/（消息台）
  • frontend/src/pages/ai-steward/（AI 管家）
  • frontend/src/pages/scheduler-center/（Mounted AI Console）
  • frontend/src/components/sstc/（SSTC 工作流组件）
• 页面目录化、Mounted AI Console、Inbox、AI Steward 与 Recipes/Projects/Users 等模块化拆分的详细库存见库存文档。

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
./devops/tunnel/start.sh  # 公网穿透启动器（独立入口）
./scripts/start_model_probe.sh  # 独立模型连通性检测（中文日志）

• 启动入口收敛：仅保留 2 个用户入口
  • 正常启动器：./start.sh
  • 公网穿透启动器：./devops/tunnel/start.sh
• 运行脚本、模型探针、契约校验与 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 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、模板句冒充成功；失败必须显式失败或标记待确认。
  • 运行时业务动作归因统一走“对象/上下文绑定 -> SemanticContextPacket -> SemanticDecision -> gatekeeper”。
  • backend/app 运行时代码禁止恢复散落的中文关键词、正则、looks_like_*、*_HINTS/*_KEYWORDS 业务拍板逻辑。
  • llm_service 只认显式 routing_meta 协议，不再靠函数名或 hint 推断 tier / contract / fallback。
  • 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 锁定
• 飞书入口层耦合已收敛：飞书真实入口已拆为三段职责链（预处理 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 已接入消息级幂等账本：TypedExecutor 以 source_system + source_message_id 作为 onboarding ledger key，重复提交只回放同一结果，不再重复跑信号源接入编排；回归由 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 已锁定回归
• 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 回归契约