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

18 KiB
Raw Blame History

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

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

  • AGENTS.md：Codex/Coding Agent 的主规则入口（优先级最高的项目级约束）
  • CLAUDE.md：面向 Claude 风格的项目说明文档（补充背景）
  • 建议：规则放 AGENTS.md，架构/目录说明放 CLAUDE.md

2. 项目定位

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

3. 顶层目录（精简版）

AIProjectManger/
├── AGENTS.md                  # Agent 执行规则（建议优先维护）
├── CLAUDE.md                  # 现有 Claude 说明文档
├── start.sh / stop.sh         # 一键启动/停止入口
├── docker-compose*.yml        # 容器编排
├── mdproject/                 # 执行计划与任务清单（中文为主）
├── backend/                   # FastAPI 后端
├── frontend/                  # React 前端
├── scripts/                   # 根目录运维脚本
├── tests/                     # 根级测试（集成/脚本）
└── docs/                      # 额外文档
  • 新增：docs/INBOX_INLINE_OPS_3_PHASE_CHECKLIST.md（消息台内联操作三期执行清单）
  • 新增：docs/architecture/（架构契约文档目录，含 MASTER_CONTRACT.md/API_CONTRACTS.md/DATAFLOW.md/TASK_BRIEF_TEMPLATE.md）
  • 新增：docs/task_briefs/（增量任务包生成产物目录）
  • 新增：docs/task_briefs/sidebar_new_entries_20260312.png、docs/task_briefs/model_routing_override_effective_20260312.png（Step 8 页面验收截图）

4. 后端结构（backend/）

backend/
├── app/
│   ├── api/                   # 路由层（含 endpoints）
│   ├── core/                  # 配置、日志、核心能力
│   ├── dependencies/          # 鉴权/租户等依赖注入
│   ├── middleware/            # 请求中间件（审计上下文注入等）
│   ├── models/                # SQLAlchemy 模型
│   ├── schemas/               # Pydantic 模型
│   ├── services/              # 业务服务（AI/SSTC/集成）
│   ├── config/                # 配置与 prompt
│   └── utils/                 # 工具函数
├── alembic/                   # 数据库迁移
│   └── versions/
│       ├── 20260310_add_feishu_outbox_reply_hash.py  # 飞书 outbox 回执哈希幂等字段
│       ├── 20260311_add_pg_trgm_text_indexes.py      # pg_trgm 扩展与文本检索索引
│       ├── 20260311_add_kb_chunk_ivfflat_index.py    # knowledge_base_chunks 向量 IVFFlat 索引
│       ├── 20260311_add_operation_log_audit_fields.py # operation_logs 审计字段扩展(trace/path/caller)
│       ├── 20260311_add_ai_pmo_work_items_view.py    # ai_pmo_work_items 兼容视图（映射 work_items）
│       ├── 20260311_expand_user_workload_ratio_precision.py # user_workloads.workload_ratio 精度扩容(10,2)
│       └── 20260311_add_conversation_sessions_table.py # 飞书多轮会话上下文持久化表
├── scripts/                   # 后端运维/数据修复脚本
│   └── backfill_orphan_signal_links.py               # 回填孤立 signal 的 project_signal_links
├── requirements.txt           # Python 依赖
├── Dockerfile
└── tests/
  • 新增：backend/app/api/llm_providers.py（AI 管家 LLM provider preset 配置读取接口）
  • 新增：backend/app/services/ai_agent_kernel.py（双 Agent 共享决策内核：复杂度路由/执行门控/修正识别）
  • 新增：backend/app/utils/timezone.py（统一北京时间工具：now_cn_aware/now_cn_naive）
  • 新增：backend/app/utils/audited_write.py（写接口审计上下文、caller 归一、北京时间格式化）
  • 新增：backend/app/middleware/audit_context.py（请求级 trace/interface/caller 注入）
  • 新增：backend/app/api/audit.py（审计查询接口：GET /audit/operations）
  • 新增：backend/app/services/audit_query_service.py（operation_logs 过滤与序列化）
  • 新增：backend/app/services/signal_source_repair_service.py（脏信号源回填服务）
  • 新增：backend/alembic/versions/20260311_shift_all_timestamps_to_beijing.py（全库历史时间 +8h，数据库默认时区切到 Asia/Shanghai）
  • 新增：backend/tests/test_ai_pmo_work_item_decision_api.py（AI PMO 审批动作接口回归测试）
  • 新增：backend/alembic/versions/20260312_add_signal_planner_fields.py（signals 增加 planner 状态字段与索引）
  • 新增：backend/app/services/signal_strategic_analysis_service.py（Signal Planner 写回收口）
  • 新增：backend/app/services/feishu_outbox_service.py（复用 reply_hash 的 outbox 入队收口）
  • 新增：backend/app/services/signal_planner_service.py（Signal Planner 异步分析服务）
  • 新增：backend/app/services/model_routing_service.py（函数级模型路由配置服务）
  • 新增：backend/app/services/task_brief_service.py（增量任务包中心服务）
  • 新增：backend/app/api/model_routing.py（模型路由配置接口）
  • 新增：backend/app/api/task_briefs.py（任务包中心接口）
  • 新增：backend/tests/test_model_routing_api.py（模型路由接口回归测试）
  • 新增：backend/tests/test_task_briefs_api.py（任务包中心接口回归测试）
  • 移除：backend/.env.example（配置模板统一到根目录 .env.example）
  • 新增：backend/.openclaw/pmflow-routing-rules.json（容器内兼容同步副本，与根目录规则保持一致）

5. 前端结构（frontend/）

frontend/
├── src/
│   ├── api/                   # 接口封装
│   ├── pages/                 # 页面级组件
│   ├── components/
│   │   ├── ui/                # 基础 UI 组件
│   │   ├── inbox/             # 消息台 Feed 列表组件
│   │   └── sstc/              # SSTC 工作流组件（已模块化拆分）
│   ├── hooks/                 # 自定义 hooks
│   ├── lib/                   # 通用工具
│   ├── stores/                # 状态管理
│   ├── router/                # 路由
│   └── types/                 # TS 类型定义
├── package.json
└── vite.config.ts
  • 新增：frontend/src/components/inbox/InboxListItem.tsx（消息台 Feed 行组件，支持移动端与行内展开）
  • 新增：frontend/src/components/inbox/InboxActionPanel.tsx（消息台内联动作面板：缺少项目归属时的项目选择与确认关联）
  • 新增：frontend/src/lib/inboxTextMap.ts（消息台用户文案映射与标题清洗）
  • 新增：frontend/src/lib/formatInboxTime.ts（消息台相对时间与完整时间格式化）
  • 新增：frontend/src/components/ui/RoleBadge.tsx（角色徽章组件，支持多角色与可选数量限制）
  • 新增：frontend/src/components/ui/SkillBadge.tsx（技能徽章组件，默认显示 3 个并支持 +N）
  • 新增：frontend/src/api/taskBriefs.ts（任务包中心 API 封装）
  • 新增：frontend/src/api/modelRouting.ts（模型路由 API 封装）
  • 新增：frontend/src/pages/TaskBriefCenterPage.tsx（增量任务包中心页面）
  • 新增：frontend/src/pages/TaskBriefTemplatePage.tsx（任务包模板管理页面）
  • 新增：frontend/src/pages/TaskBriefRunsPage.tsx（任务包生成记录页面）
  • 新增：frontend/src/pages/ContractSyncBoardPage.tsx（契约同步看板页面）
  • 新增：frontend/src/pages/ModelRoutingConfigPage.tsx（模型路由配置页面）

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 可视化信息面板
  • 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
  • 已移除：scripts/start_legacy_local.sh、scripts/stop_legacy_local.sh（旧本地启动链路）
  • 新增：scripts/start_model_probe.sh（独立模型连通性检测启动器，输出中文日志并落盘）
  • 新增：scripts/model_probe.py（模型检测核心逻辑，读取 .env 并探测 low/high 路由模型）
  • 新增：scripts/gen_task_brief.sh（按 git diff 自动生成增量任务包文档）
  • 新增：scripts/check_contract_sync.sh（后端契约变更时强制校验前端类型与架构文档同步）

前端

cd frontend
npm run dev
npm run build

后端（本地直跑）

cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

7. 团队维护建议（简版）

  • 规则变更：只改 AGENTS.md
  • 结构变更：同步改 CLAUDE.md
  • API/契约变更：后端 schemas + 前端 types 同步更新

8. 服务边界约束（禁止越界）

  • 数据库写操作必须通过 Alembic migration，禁止直接 ALTER TABLE
  • 运行期禁止 DDL：database.py 钩子统一拦截 CREATE/ALTER/DROP/...，仅迁移路径允许执行
  • 新增接口必须遵循响应包络：{code, message, data}，不得裸返回
  • 禁止在 API 层写业务逻辑，业务逻辑归属 services/
  • 禁止在前端组件内直接调用 fetch，必须通过 frontend/src/api/ 封装层
  • 前端状态管理：服务端数据用 React Query，本地 UI 状态用 useState
  • 飞书回执发送仅允许 main.py 的 drain_loop 作为消费者，禁止在业务路径即时派发 outbox 发送任务
  • 所有写接口必须落审计日志（operation_logs）：至少包含 trace_id/interface_path/caller
  • created_at_beijing 为计算属性返回，禁止新增数据库物理列

9. 新增代码的参考模式

  • 新增后端接口：参考 backend/app/api/sstc.py 的结构
  • 模型路由配置接口：参考 backend/app/api/model_routing.py（GET/PUT /model-routing/functions/{function_name}，仅管理员可写并写入 operation_logs）
  • 任务包中心接口：参考 backend/app/api/task_briefs.py（/task-briefs/center/templates/runs/generate/contract-sync）
  • 审计查询接口：参考 backend/app/api/audit.py（GET /audit/operations）
  • 脏数据修复接口：参考 backend/app/api/ai_steward.py（POST /ai-steward/signal-sources/repair-dirty）
  • 配置读取类接口：参考 backend/app/api/llm_providers.py（GET /ai-steward/llm/providers）
  • 项目删除接口（DELETE /projects/{project_id}）：参考 backend/app/api/projects.py，先清理强依赖外键、再置空弱依赖外键、最后删除主记录（单事务提交）
  • 项目成员分配接口（PUT /projects/{project_id}/members）：参考 backend/app/api/projects.py + backend/app/services/project_member_service.py，要求显式传入 member_user_ids 并写入 user_projects
  • SSTC 总览接口（GET /projects/{project_id}/sstc/overview）：workload_health 返回成员明细 members[]（姓名/角色/负载比例/状态）用于头部卡片展示
  • AI PMO 审批接口（POST /ai-pmo/work-items/{work_item_id}/decision）：显式 approve/reject，reject 必须落 ignored（失效）并同步 decision_records.final_outcome
  • AI PMO 审批接口补充：approve + waiting_manual + project_id 走“快速返回 + 后台继续执行”，避免前端长时间阻塞
  • AI PMO 消息台列表接口（GET /ai-pmo/work-items）：返回 latest_policy_gate_code 与规范化 approval_requirement{required,reason,message}（来源于最新 decision_records 投影）
  • AI PMO 消息台列表接口补充：返回源消息上下文字段 source_message_text/source_captured_at/source_sender/source_channel_ref，用于详情页展示“原始输入”与事件时间
  • AI PMO 消息台列表接口补充：返回闭环语义字段 source_conversation_closure/closure_summary/implementation_modules/source_closure_turns，用于详情页展示“消息闭环 + 实现模块”
  • AI PMO 消息台历史回填补充：当 ingest_events.payload 闭环字段缺失或低质量时，优先回放 ai_processing_logs（同 feishu_message_id）并补充 qa_records 最近问答，避免 Redis 会话过期后仅剩单句摘要
  • AI PMO 消息台列表接口补充：过滤短口水话 query.read_only 项（如“怎么样了/在吗”），保留后端记录但不下发前端收件流
  • AI PMO signal_source.onboard 入库规则：优先使用闭环摘要写入 signals.summary，闭环对话写入 signals.content，并在 signals.strategic_analysis.source_context.implementation_modules 持久化实现模块
  • SSTC 信号列表接口（GET /projects/{project_id}/signals）标题生成规则：优先 signals.title，其次 signals.summary，最后回退 signals.content 去前缀文本
  • 信号源编排事务补充：SignalSourceOrchestrationService 内部调用 OpenClaw 指挥链使用隔离 Session，禁止把子链路 rollback 传播到外层 signal/work_item 事务
  • 新增前端 API 调用：参考 frontend/src/api/sstc.ts
  • 新增数据库表：参考 alembic/versions/ 最新 migration
  • 新增飞书事件处理：参考 backend/app/services/feishu_integration.py

10. 幂等与事务约束

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

11. 已知 BOUNDARY（不要幻构行为）

  • 飞书回调字段可能缺失文件名/大小，仅保证 attachment_id/key/type 可用
  • agents.defaults.timeoutSeconds 在 OpenClaw 网关行为未验证，当前以 LLM_REQUEST_TIMEOUT 环境变量为准
  • World Model 静态层已接入 Redis 缓存（key: wm:static:{tenant_id}:{project_id}，TTL 600s）
  • 写操作后主动 invalidate，动态层不缓存
  • AI PMO 意图识别已启用 LLM 主路径（AI_PMO_INTENT_LLM_ENABLED，默认开启）；当模型超时/不可用/结构化解析失败时自动降级到规则链路，不中断主流程
  • 环境变量以根目录 .env / .env.example 为唯一配置源；backend/.env 已移除且不再读取
  • OpenClaw 路由规则统一由根目录 .openclaw/pmflow-routing-rules.json 管理，容器通过 OPENCLAW_ROUTING_RULES_PATH 相对路径 ../.openclaw/pmflow-routing-rules.json 读取
  • Signal Planner 函数路由支持 integrations(type='model_routing') 覆盖配置；配置缺失时回退 OpenClaw 默认规则并记录告警
  • Signal Planner 结构化调用采用 25s 硬超时：超时或结构化不合法时自动写入降级 ai_planner(fallback_mode=true) 并收敛为 planner_status=completed
  • 模型命名统一使用裸模型名（如 GLM-4.7、MiniMax-M2.5），不使用供应商前缀模型名
  • 双 Agent 路由治理：默认启用 OPENCLAW_ROUTING_ENABLED=true、关闭 LLM_MIXED_ROUTING_ENABLED，复杂意图使用 classify_intent_complex 走 high-tier
  • 写操作链路统一产出 decision_trace（intent/tier/confidence/gate_code/correction_action）用于离线回放与分桶评分
  • AI PMO 意图仲裁默认开启（AI_PMO_INTENT_ARBITRATION_ENABLED=true）：规则与 LLM 写操作冲突时按 AI_PMO_INTENT_CONFLICT_POLICY=pending_manual 强制进入人工确认，不直接自动执行
  • project.create 启用槽位完整性闸门：无法从指令提取有效项目名时标记 slot_incomplete 并进入人工确认
  • 数据库与核心写入链路统一使用北京时间（Asia/Shanghai）：PostgreSQL 会话时区、数据库默认时区与核心 _utc_now* 写入入口均已切换到北京时间
  • 后端与脚本层已清零 datetime.utcnow()/timezone.utc：统一使用 backend/app/utils/timezone.py（now_cn_aware/now_cn_naive/CN_TZ）管理时间语义
  • operation_logs.created_at_beijing 为应用层计算字段（非 DB 列），审计查询接口返回时统一补齐
  • 历史脏信号源修复优先复用同项目已存在 signal_id，仅无法复用时才触发 capture-feishu 补录
  • 兼容 SQL 查询入口：ai_pmo_work_items 为视图别名（底层映射 work_items），避免历史脚本直接查旧表名失败