92 KiB
92 KiB
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/ # 根目录运维脚本
└── 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/
│ ├── __init__.py # app 包入口（根目录轻量化后保留）
│ ├── api/ # 路由层（含 endpoints）
│ ├── core/ # 配置、日志、核心能力
│ │ └── startup/ # 启动阶段拆分模块（db guard/outbox/ingress async/draft expiry/probe/warmup）
│ ├── deps.py # 共享依赖导出（get_db/AsyncSessionLocal）
│ ├── dependencies/ # 鉴权/租户等依赖注入
│ ├── middleware/ # 请求中间件（审计上下文注入等）
│ ├── models/ # SQLAlchemy 模型
│ ├── schemas/ # Pydantic 模型
│ ├── services/ # 业务服务（AI/SSTC/集成）
│ ├── config/ # 配置与 prompt
│ └── utils/ # 工具函数（timezone / audited_write / thread_context）
├── 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 # 飞书多轮会话上下文持久化表
│ ├── 20260316_add_ai_orchestration_ingress_async_fields.py # ai_orchestration_runs 入站异步重试字段扩展
│ ├── 20260323_add_work_item_draft_confirmation_fields.py # work_items 草稿确认字段与索引
│ ├── 20260324_add_project_create_idempotency_indexes.py # 项目创建幂等索引：活动项目标题大小写无关唯一
│ └── 20260327_cleanup_model_routing_legacy_names.py # model_routing 旧函数名清理与重命名迁移
├── scripts/ # 后端运维/数据修复脚本
│ ├── backfill_orphan_signal_links.py # 回填孤立 signal 的 project_signal_links
│ ├── dev/ # 开发辅助脚本（check_users/seed_all）
│ └── legacy/ # 历史脚本（仅保留兼容参考，不作为主流程）
├── tests/ # 后端回归测试
│ ├── test_draft_confirm_handler.py
│ ├── test_ai_service_core_runtime.py
│ ├── test_rag_route_contract.py
│ ├── test_ai_pmo_task_intent_contract.py
│ ├── test_ai_pmo_ingress_mainline.py
│ ├── test_ai_pmo_qa_http_mainline_e2e.py
│ ├── test_context_cache_profile_catalog.py
│ ├── test_ai_pmo_tactical_brain_contract.py
│ ├── test_adaptive_rag_mainline_contract.py
│ ├── test_ai_pmo_execution_ledger_contract.py
│ ├── test_feishu_card_action_contract.py
│ ├── test_feishu_pipeline_queue_contract.py
│ ├── test_feishu_long_connection_tls_contract.py
│ ├── test_feishu_receive_orchestration_contract.py
│ ├── test_signal_planner_contract.py
│ ├── test_ai_prompt_registry_contract.py
│ ├── test_model_routing_service.py
│ ├── test_model_routing_migration.py
│ └── test_sstc_tasks_ai_breakdown_contract.py
├── requirements.txt # Python 依赖
└── Dockerfile
- 新增：
backend/app/api/llm_providers.py（AI 管家 LLM provider preset 配置读取接口） - 新增：
backend/app/services/model/model_config.py（模型 provider / tier 默认值的唯一配置读取器，读取backend/.openclaw/pmflow-routing-rules.json） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/ai_agent_kernel.py（双 Agent 共享决策内核：复杂度路由/执行门控/修正识别） - 新增：
backend/app/core/startup/ai_pmo_ingress_async.py（AI PMO 入站异步任务轮询启动循环） - 新增：
backend/app/utils/timezone.py（统一北京时间工具：now_cn_aware/now_cn_naive） - 新增：
backend/app/utils/audited_write.py（写接口审计上下文、caller 归一、北京时间格式化） - 新增：
backend/app/utils/thread_context.py（飞书线程/消息锚点归一 + 外部问答conversation_scope_key生成：reply/root/thread 用于 reply anchor，稳定会话 scope 默认使用chat_id + sender_open_id，不再用source_message_id作为外部连续会话真锚点） - 新增：
backend/app/services/adaptive_rag_service/mixin_followup_anchor.py（外部问答追问锚定与候选澄清：单候选自动绑定、多候选文本编号澄清、元追问优先锚定最近 PMFlow 回复） - 新增：
backend/app/middleware/audit_context.py（请求级 trace/interface/caller 注入） - 新增：
backend/app/api/audit.py（审计查询接口：GET /audit/operations） - 新增：
backend/app/services/audit_query_service/service.py（operation_logs 过滤与序列化） - 新增：
backend/app/services/signal_source_repair_service.py（脏信号源回填服务） - 更新：
backend/app/services/signal/signal_source_orchestration/mixin_registry_execute.py（需求点归一化/去重与materialize_requirement_sources落库 helper，raw_context记录来源与原始需求点） - 更新：
backend/app/services/signal/signal_capture_service/mixin_new_project.py、mixin_capture_legacy.py（飞书new_project自动立项收口，项目创建与信号源落库失败即回滚，避免半成功状态） - 新增：
backend/alembic/versions/20260311_shift_all_timestamps_to_beijing.py（全库历史时间 +8h，数据库默认时区切到 Asia/Shanghai） - 新增：
backend/alembic/versions/20260327_add_external_qa_followup_state.py（qa_sessions增加external_conversation_key，qa_session_states增加外部追问待澄清状态字段） - 新增：
backend/alembic/versions/20260327_add_qa_record_followup_anchor_fields.py（qa_records增加外部会话 scope / reply anchor / 路由快照字段，支撑跨 session 追问锚定与元追问追溯） - 新增：
backend/alembic/versions/20260312_add_signal_planner_fields.py（signals 增加 planner 状态字段与索引） - 新增：
backend/app/services/signal/signal_planner/signal_strategic_analysis_service.py（Signal Planner 写回收口） - 新增：
backend/app/services/integrations/feishu_outbox/service.py（复用 reply_hash 的 outbox 入队收口） - 新增：
backend/app/services/signal/draft_generator_service.py（写操作草稿生成服务：草稿结构化产出 + 24h 过期） - 新增：
backend/app/services/ai_pmo/draft_confirm_handler.py（草稿确认处理器：确认/修改/取消 + 幂等保护） - 新增：
backend/app/core/startup/draft_expiry_worker.py（草稿超时取消后台扫描任务） - 新增：
backend/app/core/startup/model_probe.py（启动期模型连通性探针：优先走 DB 里的实际引擎配置，失败不污染 provider circuit） - 新增：
backend/app/services/sstc/charter_payload.py（轻量宪章上下文提取模块：供 Signal Planner / SSTC 共享，避免导入环） - 新增：
backend/app/services/task_breakdown.py（任务拆解业务对象归一、技能标签回填、自动指派阈值判断） - 新增：
backend/app/services/ai_pmo/consultant_dispatch.py（轻量顾问式统一调度合同与注册表：保留现有业务 Prompt 拆分，统一生成domain/mode/risk_level/missing_fields/allow_execute/next_action） - 新增：
backend/app/config/ai_prompt_registry.py（prompt registry / manifest，统一登记 prompt 场景、调用入口与契约） - 更新：
backend/app/config/ai_prompts.py（默认角色 Prompt 调整为“产品经理（立项评审）”，强调查重、MVP、前景与需求清单） - 更新：
backend/app/config/ai_prompts_catalog/part_02.py（PROMPT_DRAFT_GENERATOR增加 active_projects / similar_projects / MVP / prospect / requirements 评审字段） - 更新：
backend/app/api/tasks.py（/tasks/breakdown统一结构化任务业务对象输出，支持可选project_id/charter_id，与 SSTC 宪章上下文和技能词表统一） - 更新：
backend/app/schemas/common.py（TaskBreakdownRequest增加可选project_id/charter_id） - 更新：
backend/app/services/sstc/charter_data.py（新增任务拆解上下文/技能词表/ prompt 拼装共享 helper） - 更新：
backend/app/config/ai_prompts_catalog/part_01.py（PROMPT_TASK_BREAKDOWN统一为结构化任务业务对象输出） - 更新：
backend/app/config/ai_prompts_catalog/part_03.py（PROMPT_DECOMPOSE_TASKS统一读取request/project/charter/modules结构化上下文，并输出task_key/title/required_skill_names/required_skill_tag_ids/depends_on_task_keys/risk/confidence/evidence_refs） - 新增：
backend/tests/test_ai_service_core_runtime.py（AIService 运行时回归：统一收敛 llm_service、缓存命中与流式兼容输出） - 新增：
backend/tests/test_rag_route_contract.py（RAG 双入口契约回归：asked_via/action_mode/message_intent/mixed_signal_part统一透传） - 新增：
backend/tests/test_ai_pmo_task_intent_contract.py（AI PMOtask.create一等 typed intent 契约回归：意图识别、路由归一与执行器分派） - 新增：
backend/tests/test_ai_pmo_ingress_mainline.py（AI PMO 主链入口回归：/ai-pmo/process-text手工问答入口、mixed sidecar 透传、draft_pending_confirm优先分支） - 新增：
backend/tests/test_ai_pmo_qa_http_mainline_e2e.py（AI PMO/QA HTTP 主链集成回归：/rag/ask只读问答、mixed 两段输出、/ai-pmo/process-text草稿待确认） - 新增：
backend/tests/test_context_cache_profile_catalog.py（Context Cache 功能目录契约回归：AI Steward 统一指向/rag/ask） - 新增：
backend/tests/test_ai_pmo_tactical_brain_contract.py（TacticalBrain 执行动作契约回归：query.answer/work_item.resume/project_signal.*映射） - 新增：
backend/app/services/adaptive_rag_service/mixin_answer_mainline.py（AdaptiveRAG 基础问答主链编排：运行时准备 + 只读主路径执行） - 新增：
backend/tests/test_adaptive_rag_mainline_contract.py（AdaptiveRAG 入口分层契约回归：read 路径绕过写确认 gate、write 路径命中确认 gate、feishu write 仍走主链） - 新增：
backend/tests/test_ai_pmo_execution_ledger_contract.py（执行账本/动作参数来源契约回归：action_contract归一、账本幂等 key、状态映射） - 新增：
backend/tests/test_sstc_tasks_ai_breakdown_contract.py（SSTC 手动 AI 拆任务契约回归：宪章上下文压缩、prompt 注入、技能词表透传） - 更新：
backend/app/services/ai_pmo/ai_pmo_kernel/mixins/ingress/ai_pmo_kernel_mixins_ingress_storage.py（新增统一action_contract组装、operation_execution_ledgerupsert、账本状态归一） - 更新：
backend/app/services/ai_pmo/ai_pmo_kernel_ingress_flow/mixin_auto.py（自动执行与草稿待确认路径接入统一执行账本，日志operation_code对齐action_contract） - 更新：
backend/app/services/ai_pmo/ai_pmo_kernel_ingress_flow/mixin_prepare_manual.py（waiting_manual路径接入统一执行账本与动作参数来源约束） - 新增：
backend/app/services/integrations/feishu_integration_service/mixin_card_action.py（飞书卡片动作解析与草稿确认回调处理） - 新增：
backend/app/services/integrations/feishu_integration_service/mixin_receive_prepare.py（飞书消息入口预处理：上下文抽取、空文本分支、附件标准化） - 新增：
backend/app/services/integrations/feishu_integration_service/mixin_receive_capture_flow.py（飞书消息入口执行流：capture 持久化、异常回执、结果收尾） - 新增：
backend/tests/test_feishu_card_action_contract.py（飞书卡片回调契约回归：动作解析与事件分发） - 新增：
backend/tests/test_feishu_pipeline_queue_contract.py（飞书待确认队列契约回归：action card 元数据与 follow-up 唯一目标约束） - 新增：
backend/tests/test_feishu_receive_orchestration_contract.py（飞书入口编排契约回归：bot 过滤、空文本分支、capture/finalize 编排） - 新增：
backend/tests/test_adaptive_rag_external_followup_contract.py（外部 QA 连续追问契约：真实 session 复用、最近回复锚定、编号澄清选择） - 新增：
backend/tests/test_external_qa_followup_migration.py（外部 QA 会话 migration 回归：列/索引新增与回滚） - 新增：
backend/tests/test_draft_generator_service.py（草稿生成服务回归：PM 评审草稿包含相似项目、MVP、前景与需求清单） - 新增：
backend/tests/test_signal_planner_contract.py（Signal Planner 契约回归：最新宪章加载、prompt 注入、无宪章降级） - 新增：
backend/tests/test_ai_prompt_registry_contract.py（Prompt registry 契约回归：覆盖率与元数据完整性） - 新增：
backend/tests/test_prompt_profile_bundle_contract.py（默认角色 prompt bundle 契约回归：PMFlow PMO 语气、职责边界与协作口径） - 新增：
backend/alembic/versions/20260324_add_project_create_idempotency_indexes.py（活动项目标题大小写无关唯一索引，收口项目创建重复写入） - 新增：
backend/alembic/versions/20260326_add_task_breakdown_payload_fields.py（tasks 拆解业务对象 JSONB 字段：ai_breakdown_payload/manual_overrides） - 新增：
backend/alembic/versions/20260326_create_feedback_center_tables.py（统一反馈学习中心双表建模与 QA/Signal/Task 初始回填） - 新增：
backend/alembic/versions/20260326_add_ai_call_log_routing_fields.py（ai_call_logs新增planned_tier/executed_tier/routing_decision/route_source/route_rule_name/routing_config_*路由追溯字段） - 新增：
backend/alembic/versions/20260327_cleanup_model_routing_legacy_names.py（model_routing旧函数名重命名/清理：project_draft_analysis_glm47_fallback->ai_pmo_signal_title_refine，删除旧残留键） - 新增：
backend/app/api/ai_steward_api/routes_feedback_center.py（AI Steward 反馈中心接口：summary/list/detail/review/reason-catalog；summary 支持window_days/source_group趋势作用域） - 新增：
backend/app/models/feedback_center.py（FeedbackCenterRecord/FeedbackCenterRecordRevision统一反馈中心模型） - 新增：
backend/app/schemas/feedback_center.py（反馈中心 summary/list/detail/review/reason-catalog 对应 Pydantic 模型） - 新增：
backend/app/services/feedback_center/（反馈中心服务层：service.py/mappers.py/reason_catalog.py；summary 产出metrics/trend/insights学习仪表盘） - 新增：
backend/tests/test_feedback_center_service.py（反馈中心服务回归：tenant/project 过滤、review 修订、映射与原因候选） - 新增：
backend/tests/test_feedback_center_api.py（反馈中心 API 回归：路由、权限与三类来源回填） - 新增：
backend/tests/test_feedback_center_migration.py（反馈中心迁移回归：历史回填_insert_record可安全写入 JSON 载荷，避免 Alembic 在 SQLite/PostgreSQL 上因 dict/list bind 失败） - 新增：
backend/tests/test_daily_briefing_service.py（每日简报回归：北京时间 naive 时间窗、任务更新采集与空响应边界） - 新增：
backend/tests/test_ai_steward_project_from_text_contract.py（AI Stewardproject-from-text契约回归：code/message/data包络与signal_sources字段） - 新增：
backend/tests/test_signal_source_requirement_materialization.py（需求点 -> 信号源注册项归一/去重/原始上下文回归） - 新增：
backend/tests/test_feishu_new_project_signal_sources.py（飞书new_project自动立项回归：摘要失败显式报错、信号源随项目同步落库） - 新增：
backend/tests/test_model_routing_service.py（双层模型路由契约回归：safety拒绝、runtime/query 一致、override 只存tier_alias、ai_call_logs仅记录 tier 级路由元信息） - 新增：
backend/tests/test_model_routing_migration.py（model_routing迁移回归：旧函数名键重命名/删除后仍保留低高层路由语义） - 更新：
backend/app/services/feedback_center/service.py（summary 输出新增 metrics 学习指标、决策洞察insights，并支持window_days/source_group的趋势分析作用域） - 更新：
backend/app/schemas/feedback_center.py（summary 增加 metrics / trend / insights 结构，并回传source_group） - 新增：
backend/app/services/signal_planner_service.py（Signal Planner 异步分析服务） - 新增：
backend/app/services/model/model_routing/service.py（函数级模型路由配置服务） - 新增：
backend/app/services/task_brief_service.py（增量任务包中心服务） - 新增：
backend/app/services/model_context_bundle_service.py（low/high 路由上下文组包/能力汇总/消费验证服务） - 新增：
backend/app/api/model_routing.py（模型路由配置接口） - 新增：
backend/app/api/task_briefs.py（任务包中心接口） - 更新：
backend/app/api/ai_steward_api/routes_capture.py、schemas.py、shared.py（POST /ai-steward/project-from-text统一code/message/data包络，返回signal_sources） - 更新：
backend/app/api/knowledge_graph.py（新增capability-summary与verify-context-consumption接口） - 更新：
backend/app/services/llm.py（按 function_name 注入 DDL 接口化硬约束，默认直连 GLM 严格失败；本地 Ollama 仅允许知识库问答链路按开关启用） - 更新：
backend/app/api/llm_engines.py（新增PUT /ai-steward/llm-engines/settings，维护本地知识库问答开关） - 更新：
backend/app/api/ai_steward.py（移除/ai-steward/command/dispatchOpenClaw 指挥规划入口） - 更新：
backend/app/services/ai_steward.py（零配置项目创建任一步 LLM 失败直接报错，不再回退默认草稿） - 更新：
backend/app/services/signal_source_orchestration_service.py（信号源 onboarding 规划与 worker 执行失败均 fail-fast，不再回退 heuristic/fallback 摘要） - 更新：
backend/app/services/project_knowledge_graph.py（新增ai_model -> governance_policy -> interface治理图谱同步能力，增量任务新增model_guardrails阶段） - 移除：
backend/.env.example（配置模板统一到根目录.env.example） - 新增：
backend/app/utils/project_command_utils.py（项目创建标题/描述提取与归一化辅助） - 新增：
backend/app/services/ai_pmo_intent_routing.py（AI PMO 意图/路由常量与解析器收口，统一family.action路由映射） - 新增：
backend/app/services/ai_pmo/workflow_semantic_planner/（统一业务语义规划层：唯一允许承载 workflow bundle 语义关键词/正则/兼容 helper 的目录） - 新增：
backend/app/models/reply_iteration.py（回复质量迭代模型：QualityAsset/QualityAssetPair/JudgeRun/OptimizerCandidate/PromptRelease） - 新增：
backend/app/models/training_pipeline.py（训练/微调管线模型：TrainingDataset/TrainingJob/TrainingEvaluation/TrainedModelArtifact/TrainedModelDeployment） - 新增：
backend/app/services/reply_iteration/service.py（反馈中心提升为学习资产、裁判分桶、候选改动、prompt release trial 服务） - 新增：
backend/app/services/training_pipeline/service.py（训练数据集、训练作业、评测、artifact promote、deployment 决策服务） - 新增：
backend/app/services/prompt_release/service.py（只读 QA prompt release 版本管理与 serving 渲染优先级） - 新增：
backend/app/api/ai_steward_api/routes_reply_iteration.py（AI Steward 回复质量闭环接口：反馈提升、judge-runs、candidates、prompt-releases、trials） - 新增：
backend/app/api/ai_steward_api/routes_training_pipeline.py（AI Steward 训练管线接口：datasets、jobs、evaluations、artifacts、deployments） - 新增：
backend/alembic/versions/20260327_add_reply_iteration_training_tables.py（回复质量迭代/训练管线主迁移：学习资产表、prompt release、训练数据集、训练作业与 experiment 扩展字段） - 新增：
backend/tests/test_reply_iteration_service.py、test_training_pipeline_service.py、test_reply_iteration_api.py、test_reply_iteration_training_migration.py（回复质量闭环与训练管线基础回归） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/ai_pmo_workflow_runtime.py（AI PMOContextAssembler+WorkflowRegistry/WorkflowHandler运行时骨架） - 新增：
backend/app/services/ai_pmo_decision_runtime.py（AI PMO 决策脑层：Strategic/Tactical/Simulation/ExecutionPolicy/DecisionEngine） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/ai_pmo_reply_renderer.py（AI PMO 回执渲染出口ReplyRenderer） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/ai_pmo_typed_executor.py（AI PMO typed 执行层组合入口） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/ai_pmo_typed_executor_common.py（TypedExecutor 共享常量/依赖） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/ai_pmo_typed_executor_mixins_parse.py（TypedExecutor 解析与批量分析逻辑） - 新增：
backend/app/services/ai_pmo/ai_pmo_typed_executor_discovery/（TypedExecutor discover 候选上下文逻辑） - 新增：
backend/app/services/ai_pmo/ai_pmo_typed_executor_execute/（TypedExecutor execute/create/source-onboard 落库逻辑） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/ai_pmo_kernel_runtime.py（AI PMO kernel 组合入口） - 新增：
backend/app/services/ai_pmo_kernel_common.py（Kernel 共享常量/依赖） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/compositions/ingress.py（Kernel ingress 组合入口） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel_ingress_flow/（Kernel 入站主流程编排） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/mixins/ingress/ai_pmo_kernel_mixins_ingress_storage.py（Kernel 入站事件/工作项写入） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/mixins/ingress/ai_pmo_kernel_mixins_ingress_render.py（Kernel 入站结果组装与输出辅助） - 更新：
backend/app/services/ai_pmo/ai_pmo_kernel_ingress_flow/mixin_auto.py（写操作改为“先起草后确认”，状态进入draft_pending_confirm） - 更新：
backend/app/services/ai_pmo/ai_pmo_kernel_ingress_flow/mixin_entry.py（会话命中draft_pending_confirm时优先路由草稿确认处理） - 更新：
backend/app/models/work_item.py（新增draft_content/draft_expires_at/draft_version/confirm_message_id） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/compositions/world_model.py（Kernel world-model 组合入口） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel_world_model_core/（Kernel world-model 核心构建与缓存） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/mixins/world_model/ai_pmo_kernel_mixins_world_model_session.py（Kernel 会话继承与会话态维护） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel_world_model_aggregates/（Kernel 组合摘要构建器） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/compositions/intent.py（Kernel intent 组合入口） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/mixins/intent/ai_pmo_kernel_mixins_intent_rules.py（Kernel 规则意图与槽位守卫） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/mixins/intent/ai_pmo_kernel_mixins_intent_llm.py（Kernel LLM 意图识别与仲裁） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/mixins/intent/ai_pmo_kernel_mixins_intent_resolve.py（Kernel 最终意图解析入口） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/compositions/followup.py（Kernel followup 组合入口） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/mixins/followup/ai_pmo_kernel_mixins_followup_records.py（followup 决策/计划/回执写入） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/mixins/followup/ai_pmo_kernel_mixins_followup_routing.py（followup 候选定位与恢复分发） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/mixins/followup/ai_pmo_kernel_mixins_followup_project_signal.py（project_signal followup 组合入口） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/mixins/followup/ai_pmo_kernel_mixins_followup_project_signal_actions.py（project_signal commit/refresh/cancel 动作执行） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/mixins/followup/ai_pmo_kernel_mixins_followup_project_signal_resume.py（project_signal 目标工作项恢复闭环） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/mixins/followup/ai_pmo_kernel_mixins_followup_verification.py（followup 执行校验与工具函数） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/compositions/closure.py（Kernel closure 组合入口） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/mixins/closure/ai_pmo_kernel_mixins_closure_helpers.py（Kernel 闭环通用归一化工具） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/mixins/closure/ai_pmo_kernel_mixins_closure_data.py（Kernel 闭环历史上下文回放） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel/mixins/closure/ai_pmo_kernel_mixins_closure_payload.py（Kernel 闭环语义与来源上下文组装） - 更新：
backend/app/services/ai_pmo/ai_pmo_kernel/mixins/（新增closure/followup/ingress/intent/world_model分组目录与__init__.py包声明，降低同层文件密度） - 更新：
backend/app/services/ai_pmo/ai_pmo_kernel/compositions/（新增组合入口分组目录，根目录仅保留 runtime/agent/domain 等真正入口） - 更新：
backend/app/services/ai_pmo/（新增 AI PMO 领域分组目录，统一收敛ai_pmo_cadence/ai_pmo_decision/ai_pmo_intent/ai_pmo_kernel/ai_pmo_kernel_common_core/ai_pmo_kernel_ingress_flow/ai_pmo_kernel_world_model_aggregates/ai_pmo_kernel_world_model_core/ai_pmo_typed_executor_discovery/ai_pmo_typed_executor_execute） - 更新：
backend/app/services/model/（新增模型能力分组目录，统一收敛model_capability/model_context_bundle/model_routing/prompt_profile） - 更新：
backend/app/services/integrations/（新增集成能力分组目录，统一收敛integration_core/feishu_integration_service/feishu_long_connection_core/feishu_outbox/feishu_signal_pipeline/wecom） - 更新：
backend/app/services/signal/（新增信号能力分组目录，统一收敛signal_capture_service/signal_planner/signal_source_orchestration/signal_source_repair/symbol_index） - 移除：
backend/app/services/ai_pmo_kernel_service.py（顶层兼容壳清理，统一改为backend/app/services/ai_pmo/ai_pmo_kernel/子包） - 新增：
backend/app/services/integrations/feishu_signal_pipeline/（飞书信号管道按职责拆分的服务包，所有子文件 <= 300 行） - 新增：
backend/app/services/integrations/feishu_signal_pipeline/service.py（组合入口，按 mixin 聚合能力） - 新增：
backend/app/services/integrations/feishu_signal_pipeline/shared_core.py、shared_schema_utils.py（共享常量/正则/Schema/工具函数拆分） - 新增：
backend/app/services/integrations/feishu_signal_pipeline/mixin_*.py（按职责拆分的处理流、gate、followup、queue、序列化、提取分类等实现） - 更新：
backend/app/services/feishu_signal_pipeline.py（降级为兼容入口，仅导出包内FeishuSignalPipelineService） - 新增：
backend/app/api/feishu_api/（飞书接口按配置/长连接/消息发送/连通性测试拆分的子模块目录） - 新增：
backend/app/api/feishu_api/router.py（飞书 API 聚合路由） - 新增：
backend/app/api/feishu_api/card_action_routes.py（飞书卡片按钮回调 HTTP 接口） - 新增：
backend/app/api/feishu_api/config_routes.py（飞书配置相关接口） - 新增：
backend/app/api/feishu_api/long_connection_routes.py（飞书长连接状态与重启接口） - 新增：
backend/app/api/feishu_api/message_routes.py（飞书消息与卡片发送接口） - 新增：
backend/app/api/feishu_api/test_routes.py（飞书连通性测试接口） - 新增：
backend/app/api/feishu_api/schemas.py（飞书 API 请求模型） - 新增：
backend/app/api/feishu_api/helpers.py（飞书 API 公共辅助函数） - 更新：
backend/app/api/feishu.py（降级为兼容入口，仅导出聚合router） - 新增：
backend/app/api/sstc_api/（SSTC 路由按领域拆分：signals/charters/tasks/releases/reviews/overview/ai-routing） - 新增：
backend/app/api/sstc_api/shared.py（SSTC 路由层公共依赖导入） - 更新：
backend/app/api/sstc.py（降级为兼容入口，仅导出聚合router） - 新增：
backend/app/services/sstc/（SSTC 业务辅助能力拆分：signal/charter/governance/entity_lookup/review） - 新增：
backend/app/services/sstc/charter_payload.py（轻量宪章上下文提取模块：供 Signal Planner / SSTC 共享，避免导入环） - 新增：
backend/app/services/llm_service/（LLM 服务按职责拆分的 mixin 包，所有子文件 <= 300 行） - 更新：
backend/app/services/llm.py（降级为兼容入口，导出LLMService与llm_service） - 新增：
backend/app/services/signal/signal_capture_service/（主动信号捕获服务按入口/编排/分析/新项目拆分） - 更新：
backend/app/services/signal_capture.py（降级为兼容入口） - 新增：
backend/app/services/project_knowledge_graph_service/（知识图谱服务按 CRUD/增量同步/守卫/快照拆分） - 更新：
backend/app/services/project_knowledge_graph.py（降级为兼容入口） - 新增：
backend/app/services/context_cache_service/（上下文缓存服务按缓存核心/画像/快照/失效钩子拆分） - 更新：
backend/app/services/context_cache.py（降级为兼容入口） - 新增：
backend/app/config/ai_prompts_catalog/（Prompt 常量分片目录，按part_01..part_04+part_scenes_01..part_scenes_06管理） - 更新：
backend/app/config/ai_prompts.py（兼容聚合入口，保留build_default_role_prompt_bundle并显式导出 prompt registry helpers） - 新增：
backend/app/api/signals_api/（signals 路由拆分为 list/create、ingest/fetch、feedback 子模块） - 新增：
backend/app/api/wecom_api/（wecom 路由拆分为 config/webhook/messaging 子模块） - 新增：
backend/app/api/endpoints/skill_api/（人员能力图谱路由拆分为 tags/bindings/workload/recommend 子模块） - 更新：
backend/app/api/ai_logs.py、backend/app/api/ai_logs_utils.py→backend/app/api/ai_logs_api/routes.py、backend/app/api/ai_logs_api/helpers.py（AI 日志 API 收敛到独立子包） - 更新：
backend/app/api/signal_sources.py、backend/app/api/signal_sources_models.py、backend/app/api/signal_sources_utils.py→backend/app/api/signal_sources_api/routes.py、backend/app/api/signal_sources_api/schemas.py、backend/app/api/signal_sources_api/helpers.py（信号源 API 收敛到独立子包） - 更新：
backend/app/api/skill_tags.py、backend/app/api/skill_tags_contracts.py→backend/app/api/skill_tags_api/routes.py、backend/app/api/skill_tags_api/contracts.py（技能标签 API 收敛到独立子包） - 更新：
backend/app/api/router.py、backend/app/api/__init__.py（直接引用*_api子模块路由，移除顶层兼容壳依赖） - 移除：
backend/app/api/ai_pmo.py、backend/app/api/ai_steward.py、backend/app/api/model_capability.py、backend/app/api/projects.py、backend/app/api/rag.py、backend/app/api/sstc.py、backend/app/api/users.py、backend/app/api/feishu.py、backend/app/api/signals.py、backend/app/api/wecom.py（顶层兼容壳清理） - 约定：
backend/app/api/rag_api/__init__.py与backend/app/api/ai_steward_api/__init__.py只做聚合与 tags，canonical prefix 由shared.py/ 子模块 router 持有，禁止包级 prefix 再重复叠加导致/rag/rag/...或/ai-steward/ai-steward/... - 更新：
backend/check_users.py、backend/seed_all.py、backend/init_db.py→backend/scripts/dev/check_users.py、backend/scripts/dev/seed_all.py、backend/scripts/legacy/init_db.py（backend 根目录散落脚本归档） - 新增：
backend/app/config/operation_catalog_core/（operation catalog 按模型/构造器/领域条目拆分） - 更新：
backend/app/dispatcher.py、backend/app/dispatcher_rules.py（未被引用，按废弃文件移除） - 更新：
backend/app/seed_projects.py、backend/app/seed_projects_helpers.py→backend/app/utils/seed_projects.py、backend/app/utils/seed_projects_helpers.py（示例数据初始化脚本归并到 utils） - 更新：
backend/app/database.py、backend/app/events.py、backend/app/events_models.py、backend/app/websocket.py→backend/app/core/database.py、backend/app/core/events.py、backend/app/core/events_models.py、backend/app/core/websocket.py（核心基础设施归并到 core） - 更新：
backend/app/main_db_guard.py、backend/app/main_feishu_outbox.py、backend/app/main_warmup.py、backend/app/main_model_probe.py→backend/app/core/startup/（启动阶段职责归并） - 更新：
backend/app/state.py（无引用，按废弃文件移除） - 新增：
backend/app/__init__.py、backend/app/deps.py（根目录仅保留__init__.py / main.py / deps.py） - 更新：
backend/app/services/顶层兼容壳批量清理（如ai_service.py/llm.py/scheduler_center.py/signal_capture.py/...），统一改为直接引用对应子包（ai_service_core/llm_service/scheduler_center_core/signal_capture_service/...） - 更新：移除
backend/app/services/alignment_orchestrator.py空文件（无引用） - 新增：
backend/app/services/ai_pmo/ai_pmo_kernel_world_model_aggregates/、backend/app/services/ai_pmo/ai_pmo_kernel_world_model_core/、backend/app/services/ai_pmo/ai_pmo_kernel_common_core/（kernel world-model/common 拆分） - 更新：
backend/app/services/ai_pmo_kernel_runtime.py、backend/app/services/ai_agent_kernel.py、backend/app/services/ai_pmo_domain_workflow.py及backend/app/services/ai_pmo_kernel_mixins_*.py→backend/app/services/ai_pmo/ai_pmo_kernel/（AI PMO kernel 子包化，清理 services 根目录散落文件） - 更新：
backend/app/services/ai_orchestration_run_service.py→backend/app/services/ai_orchestration_run/service.py（编排运行账本服务子包化） - 新增：
backend/app/services/ai_orchestration_run/ingress_worker.py（AI PMO 入站消息异步消费、重试与最终回执发送） - 更新：
backend/app/services/ai_pmo_reply_renderer.py、backend/app/services/ai_pmo_review_service.py、backend/app/services/ai_pmo_typed_executor.py、backend/app/services/ai_pmo_typed_executor_common.py、backend/app/services/ai_pmo_typed_executor_mixins_parse.py、backend/app/services/ai_pmo_workflow_runtime.py→backend/app/services/ai_pmo/ai_pmo_kernel/（AI PMO 执行与回执运行时收敛到 kernel 子包） - 更新：
backend/app/services/cost_optimization_service.py、backend/app/services/model_lifecycle_service.py→backend/app/services/model/model_capability/（模型能力相关服务收敛） - 更新：
backend/app/services/signal_strategic_analysis_service.py→backend/app/services/signal/signal_planner/signal_strategic_analysis_service.py（Signal Planner 分析写回服务归并） - 移除：
backend/app/services/llm_client.py（全仓库无引用，按废弃文件清理） - 更新：
backend/app/services/analyzer.py、backend/app/services/fetcher.py→backend/app/services/signal/signal_capture_service/impact_analyzer.py、backend/app/services/signal/signal_capture_service/external_fetcher.py（信号接入分析/抓取能力归并） - 更新：
backend/app/services/plane.py→backend/app/services/integrations/integration_core/plane_service.py（Plane 兼容服务归并到 integration_core） - 更新：
backend/app/services/lark.py→backend/app/services/integrations/integration_core/lark_service.py（Lark 兼容服务归并到 integration_core） - 更新：
backend/app/services/workload_alert_service.py→backend/app/services/workload/workload_alert_service.py（负载告警服务归并到 workload 子包） - 更新：
backend/app/services/task_persistence.py（兼容壳移除，统一直接引用backend/app/services/task_persistence_core/） - 更新：
backend/app/services/project_member_service.py→backend/app/services/project_member/service.py（项目成员分配服务子包化） - 更新：
backend/app/services/recipe_service.py→backend/app/services/recipe/service.py（食谱服务子包化） - 更新：
backend/app/services/model_routing_service.py→backend/app/services/model/model_routing/service.py（模型路由服务子包化） - 更新：
backend/app/services/prompt_profile_service.py→backend/app/services/model/prompt_profile/service.py（Prompt 画像服务子包化） - 更新：
backend/app/services/feishu_outbox_service.py→backend/app/services/integrations/feishu_outbox/service.py（飞书 outbox 服务子包化） - 更新：
backend/app/services/wecom_integration.py→backend/app/services/integrations/wecom/service.py（企业微信集成服务子包化） - 更新：
backend/app/services/skill_score_service.py→backend/app/services/skill/skill_score_service.py（技能评分服务归并到 skill 子包） - 更新：
backend/app/services/auth.py、backend/app/services/audit_query_service.py、backend/app/services/notification_service.py、backend/app/services/operation_catalog_service.py、backend/app/services/operation_log_service.py→backend/app/services/*/service.py（同名服务子包化，services根目录不再保留.py文件） - 更新：
backend/app/services/根目录.py已清零（全部收敛到子包），仅保留目录化服务结构
5. 前端结构（frontend/）
frontend/
├── src/
│ ├── api/ # 接口封装
│ ├── pages/ # 页面级组件
│ │ ├── ai-config/ # AI Config 页面模块目录（types/constants/components/sections）
│ │ ├── ai-steward/ # AI Steward 页面模块目录（types/constants/components/sections）
│ │ ├── charter-detail/ # Charter Detail 页面模块目录
│ │ ├── contract-sync-board/ # Contract Sync Board 页面模块目录
│ │ ├── dashboard/ # Dashboard 页面模块目录
│ │ ├── feishu-config/ # Feishu Config 页面模块目录（helpers/components）
│ │ ├── inbox/ # Inbox 页面模块目录（helpers/components）
│ │ ├── knowledge-graph-context-board/ # KG Context Board 页面模块目录
│ │ ├── login/ # Login 页面模块目录
│ │ ├── model-routing-config/ # Model Routing Config 页面模块目录
│ │ ├── project-board/ # Project Board 页面模块目录（helpers/components）
│ │ ├── projects/ # Projects 页面模块目录（helpers/components）
│ │ ├── recipes/ # Recipes 页面模块目录（helpers/components）
│ │ ├── scheduler-center/ # Scheduler Center 页面模块目录
│ │ ├── skill-tasks/ # Skill Tasks 页面模块目录
│ │ ├── skills/ # Skills 页面模块目录
│ │ ├── task-brief-center/ # Task Brief Center 页面模块目录
│ │ ├── task-brief-runs/ # Task Brief Runs 页面模块目录
│ │ ├── task-brief-template/ # Task Brief Template 页面模块目录
│ │ ├── user-profile/ # User Profile 页面模块目录
│ │ ├── user-skills/ # User Skills 页面模块目录
│ │ ├── users/ # Users 页面模块目录（helpers/components）
│ │ ├── workload-detail/ # Workload Detail 页面模块目录
│ │ └── workloads/ # Workloads 页面模块目录
│ ├── 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/api/knowledgeGraph.ts（KG 能力汇总与 low/high 消费验证 API） - 更新：
frontend/src/api/aiSteward.ts（移除 OpenClaw dispatch 封装，新增 LLM 引擎 CRUD / settings 封装） - 更新：
frontend/src/pages/CharterDetailPage.tsx、ContractSyncBoardPage.tsx、DashboardPage.tsx、KnowledgeGraphContextBoardPage.tsx、LoginPage.tsx、ModelRoutingConfigPage.tsx、SchedulerCenterPage.tsx、SkillTasksPage.tsx、SkillsPage.tsx、TaskBriefCenterPage.tsx、TaskBriefRunsPage.tsx、TaskBriefTemplatePage.tsx、UserProfilePage.tsx、UserSkillsPage.tsx、WorkloadDetailPage.tsx、WorkloadsPage.tsx（统一降级为轻量入口，转发到pages/*/子目录） - 新增：
frontend/src/pages/charter-detail/CharterDetailPage.tsx、contract-sync-board/ContractSyncBoardPage.tsx、dashboard/DashboardPage.tsx、knowledge-graph-context-board/KnowledgeGraphContextBoardPage.tsx、login/LoginPage.tsx、model-routing-config/ModelRoutingConfigPage.tsx（剩余核心页面目录化收敛） - 新增：
frontend/src/pages/scheduler-center/SchedulerCenterPage.tsx、skill-tasks/SkillTasksPage.tsx、skills/SkillsPage.tsx、task-brief-center/TaskBriefCenterPage.tsx、task-brief-runs/TaskBriefRunsPage.tsx、task-brief-template/TaskBriefTemplatePage.tsx（任务/调度/技能页面目录化收敛） - 新增：
frontend/src/pages/user-profile/UserProfilePage.tsx、user-skills/UserSkillsPage.tsx、workload-detail/WorkloadDetailPage.tsx、workloads/WorkloadsPage.tsx（用户与负载页面目录化收敛） - 更新：
frontend/src/pages/InboxPage.tsx（降级为轻量入口，转发到pages/inbox/InboxPage） - 新增：
frontend/src/pages/inbox/helpers.ts（Inbox 页面 tab 过滤、排序、project-scope 判断 helper） - 新增：
frontend/src/pages/inbox/components/InboxFiltersPanel.tsx（Inbox 页面顶部筛选/搜索/tab 面板拆分） - 新增：
frontend/src/pages/inbox/InboxPage.tsx（Inbox 页面编排层，主文件聚焦状态与动作流转） - 更新：
frontend/src/api/aiPmo.ts（新增草稿决策 API：decideDraftWorkItem，并扩展工作项 draft 字段） - 更新：
frontend/src/lib/inbox.ts（支持draft_pending_confirm卡片映射与三动作按钮） - 更新：
frontend/src/types/inbox.ts（新增草稿动作类型revise_draft/cancel_draft） - 更新：
frontend/src/pages/RecipesPage.tsx（降级为轻量入口，转发到pages/recipes/RecipesPage） - 新增：
frontend/src/pages/recipes/helpers.ts（Recipes 页面默认表单与分类常量） - 新增：
frontend/src/pages/recipes/components/CreateRecipeDialog.tsx、AnalyzeRecipeDialog.tsx（Recipes 页面手动创建/AI 识别弹窗拆分） - 新增：
frontend/src/pages/recipes/RecipesPage.tsx（Recipes 页面编排层，主文件聚焦列表筛选与状态） - 更新：
frontend/src/pages/FeishuConfigPage.tsx（降级为轻量入口，转发到pages/feishu-config/FeishuConfigPage） - 新增：
frontend/src/pages/feishu-config/helpers.ts（Feishu Config 表单与状态类型、默认配置常量） - 新增：
frontend/src/pages/feishu-config/components/SetupGuideCard.tsx（Feishu Config 配置指南卡片拆分） - 新增：
frontend/src/pages/feishu-config/FeishuConfigPage.tsx（Feishu Config 页面编排层，主文件聚焦状态与交互） - 更新：
frontend/src/pages/AIConfigPage.tsx（降级为轻量入口，转发到pages/ai-config/AIConfigPage） - 新增：
frontend/src/pages/ai-config/types.ts、frontend/src/pages/ai-config/constants.ts（AI Config 类型与常量集中管理） - 新增：
frontend/src/pages/ai-config/components/GovernanceToolsCard.tsx、StatusBadge.tsx、PriorityBadge.tsx（AI Config 复用展示组件） - 新增：
frontend/src/pages/ai-config/sections/OverviewTab.tsx、ConfigureTab.tsx、KnowledgeTab.tsx、AdvancedTab.tsx（AI Config 分阶段 UI 拆分） - 新增：
frontend/src/pages/ai-config/AIConfigPage.tsx（AI Config 页面编排层，主文件仅保留状态与事件编排） - 更新：
frontend/src/pages/AIStewardPage.tsx（降级为轻量入口，转发到pages/ai-steward/AIStewardPage） - 新增：
frontend/src/pages/ai-steward/types.ts、frontend/src/pages/ai-steward/constants.ts（AI Steward 类型与常量集中管理） - 新增：
frontend/src/pages/ai-steward/components/FeatureOverviewCards.tsx（AI Steward 首页功能卡片组件） - 新增：
frontend/src/pages/ai-steward/components/BriefingPrintDocument.tsx、BriefingSectionCard.tsx、BriefingDetailDrawer.tsx（AI Steward 简报中心打印导出模板、固定高度项目分组卡片与右侧详情抽屉） - 新增：
frontend/src/pages/ai-steward/sections/OverviewTab.tsx、CreateProjectTab.tsx、SignalsTab.tsx、ConflictsTab.tsx、BlockersTab.tsx、BriefingTab.tsx、EngineTab.tsx、FeedbackCenterTab.tsx（AI Steward 分阶段 UI 拆分） - 新增：
backend/app/services/executive_briefing_service.py、backend/app/api/ai_steward_api/routes_executive_briefing.py（老板晨报聚合服务与 manager-only 接口，配置持久化复用Integration(type='executive_briefing')，快照复用PortfolioSnapshot(scope_type='executive_brief')） - 新增：
backend/app/services/tenant_briefing_service.py、backend/tests/test_daily_briefing_v2_api.py（租户级简报统一内核与daily-briefing-v2viewer scope 过滤回归） - 新增：
backend/tests/test_executive_briefing_api.py、backend/tests/test_ai_pmo_cadence_scheduler.py（老板晨报接口包络、配置落库、管理群文案与调度时间窗回归） - 更新：
backend/app/services/ai_pmo/ai_pmo_cadence/service.py、mixin_builders.py、mixin_snapshots.py、backend/app/services/scheduler_center_core/ai_pmo_cadence.py（新增executive_briefcadence type，支持租户级晨报快照生成与管理群 outbox 推送） - 更新：
backend/app/services/executive_briefing_service.py（读取snapshot时若命中旧结构快照，会自动按当前代码重建新版 payload，避免简报中心默认打开仍停留在无详情/无精准跳转的旧结构） - 更新：
frontend/src/api/aiSteward.ts（新增 cognitive conflicts / blockers /daily-briefing-v2/ executive briefing API 封装，AI Steward 页面不再直接fetch） - 更新：
frontend/src/pages/ai-steward/AIStewardPage.tsx、components/FeatureOverviewCards.tsx、sections/OverviewTab.tsx、sections/BriefingTab.tsx（晨报中心与每日简报共享snapshot/live模式；前端只保留一个“简报中心”入口，支持固定高度卡片、项目分组预览、右侧详情抽屉、精准跳转与完整详细导出） - 更新：
frontend/src/pages/ai-steward/sections/CreateProjectTab.tsx（零配置创建结果区内联展示signal_sources分组，复用现有 AI Steward 页面，不新增独立路由） - 新增：
frontend/src/pages/ai-steward/components/feedback-center/FeedbackList.tsx、FeedbackDetail.tsx、ReasonPicker.tsx、MetricsPanel.tsx、TrendPanel.tsx（反馈中心三栏工作台、指标页与趋势页组件；趋势页支持7/30 天与all/task/qa/signal局部筛选，并提供洞察卡、原因筛选与一键钻取） - 新增：
frontend/src/pages/ai-steward/components/feedback-center/TrendPanel.tsx的趋势决策版布局（Scope / KPI / Insights / Drilldown / Evidence） - 更新：
frontend/src/pages/ai-steward/sections/FeedbackCenterTab.tsx（趋势页钻取联动列表筛选，支持 reason_code / source_type 的局部跳转） - 更新：
frontend/src/pages/ai-steward/components/feedback-center/FeedbackList.tsx（列表增加原因筛选器，支持趋势页高频原因钻取） - 新增：
frontend/src/api/feedbackCenter.ts（统一反馈中心 API 封装） - 新增：
frontend/src/pages/ai-steward/AIStewardPage.tsx（AI Steward 页面编排层，主文件聚焦状态与事件） - 更新：
frontend/src/api/aiSteward.ts、frontend/src/api/base.ts（新增createProjectFromText，并兼容{code,message,data}响应包络） - 新增：
frontend/src/lib/api.ts、apiError.ts、display.ts、datetime.ts、inbox.ts、inboxTextMap.ts、formatInboxTime.ts、feishuEventMode.ts、sessionGuard.ts、rbac.ts、title.ts、utils.ts、zhCN.ts（前端兼容工具与消息台/AI Steward 展示格式化层） - 更新：
frontend/src/pages/ProjectBoardPage.tsx（降级为轻量入口，转发到pages/project-board/ProjectBoardPage） - 新增：
frontend/src/pages/project-board/helpers.ts（Project Board 信号筛选状态与 PMO 工作项文本归一 helper） - 更新：
frontend/src/pages/project-board/ProjectBoardPage.tsx（支持从简报中心 URL 参数恢复stage与signal_*筛选条件） - 新增：
frontend/src/pages/project-board/components/CreateCharterDialog.tsx、ProjectSettingsDialog.tsx（Project Board 大体量弹窗组件拆分） - 新增：
frontend/src/pages/project-board/ProjectBoardPage.tsx（Project Board 页面编排层） - 更新：
frontend/src/pages/ProjectsPage.tsx（降级为轻量入口，转发到pages/projects/ProjectsPage） - 新增：
frontend/src/pages/projects/helpers.ts（Projects 页面链路阶段、状态样式、权限与错误解析 helper） - 新增：
frontend/src/pages/projects/components/ProjectQueryDialog.tsx、DeleteProjectDialog.tsx（Projects 页面查询/删除弹窗拆分） - 新增：
frontend/src/pages/projects/ProjectsPage.tsx（Projects 页面编排层，主文件聚焦状态与事件） - 更新：
frontend/src/pages/UsersPage.tsx（降级为轻量入口，转发到pages/users/UsersPage） - 新增：
frontend/src/pages/users/helpers.ts（Users 页面角色/密码/CSV 预览 helper 聚合） - 新增：
frontend/src/pages/users/components/DeleteUserDialog.tsx、ResetPasswordDialog.tsx、ImportUsersDialog.tsx、BulkAssignDialog.tsx（Users 页面大体量弹窗组件拆分） - 新增：
frontend/src/pages/users/UsersPage.tsx（Users 页面编排层，主文件聚焦状态与事件） - 更新：
frontend/src/pages/AIStewardPage.tsx（移除 OpenClaw 指挥调度入口，新增本地 LLM 开关与严格失败边界说明） - 移除：
frontend/src/components/ai-steward/OpenClawCommanderPanel.tsx（OpenClaw 指挥调度面板）
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.tsxuseSSTCWorkspaceOrchestration.tssstcUtils.tsSSTCCharterStagePanel.tsxSSTCSignalStagePanel.tsxSSTCTaskStagePanel.tsxSSTCExecutionBoardPanel.tsxSSTCReleaseStagePanel.tsxSSTCReviewStagePanel.tsxSSTCReleaseCreateDialog.tsxSSTCReviewCreateDialog.tsxSSTCTaskCreateDialog.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/...，仅迁移路径允许执行 - 运行环境数据库仅允许 PostgreSQL（
postgresql+asyncpg）；禁止回落 SQLite - 新增接口必须遵循响应包络：
{code, message, data}，不得裸返回 - 项目创建时自动生成的信号源必须落到现有
SignalSourceRegistry，前端仅允许在现有 AI Steward 创建结果区内联展示，禁止新增独立信号源页面或独立持久化模型 create_project_from_natural_language支持透传requested_member_user_ids；AI PMO 草稿确认时必须把推荐负责人并入项目创建事务，确保项目、主信号、信号源、成员关系一次性落库，禁止确认后再事后补成员- 禁止在 API 层写业务逻辑，业务逻辑归属
services/ - 禁止在前端组件内直接调用
fetch，必须通过frontend/src/api/封装层 - 前端状态管理：服务端数据用 React Query，本地 UI 状态用
useState - 老板晨报链路只允许
BOSS/ADMIN访问；GET /ai-steward/executive-briefing的snapshot/live语义必须分离，live禁止覆盖PortfolioSnapshot(scope_type='executive_brief') daily-briefing-v2必须复用同一份租户级简报内核：先算 tenant payload，再按viewer_scope=tenant_full|personal过滤；禁止老板晨报与每日简报各自维护独立统计口径- 简报 item 的卡片摘要、抽屉详情、导出报告与跳转目标必须复用同一份结构化字段（
id/detail_lines/meta/target.params）；禁止页面、导出、跳转各自拼接不同文案导致事实不一致 - 简报中心只允许展示具备真实业务定位的对象：项目信号必须绑定真实
project_id，信号源必须有真实来源名/标识，人员负载必须绑定真实user_id；禁止把未归属信号用“待处理事项”等兜底标题伪装成老板待办 - 老板晨报调度配置统一落在
Integration(type='executive_briefing')，禁止新增独立晨报配置表；管理群自动推送必须复用现有feishu_reply_outbox - 晨报/日报导出首版只允许前端“当前所见”打印导出（浏览器
print/ PDF），禁止新增后端二进制 PDF 生成服务 - 飞书回执发送仅允许
main.py的 drain_loop 作为消费者，禁止在业务路径即时派发 outbox 发送任务 - 所有写接口必须落审计日志（
operation_logs）：至少包含trace_id/interface_path/caller created_at_beijing为计算属性返回，禁止新增数据库物理列- low/high 双层路由（
classify_intent_ai_pmo_kernel、classify_intent_complex）与openclaw_command_dispatch必须遵循 DDL 接口化约束：禁止直连 SQL DDL，命中时强制输出ddl_api_required - low/high 上下文注入仅允许通过
ModelContextBundleService统一组包：固定三段knowledge_graph/task_template/contract_sync，禁止在业务服务散落拼接 prompt 上下文 - AI PMO
signal.create在用户显式要求“先分析再入库 / 自行分析”时，若批量信号结构化分析失败，禁止回退规则标题直接入库，必须返回失败安全态 - 所有 LLM 调用禁止静默兜底与 stub 假成功；low 失败时必须优先强制升级到 high 重试并保留低/高两段日志，high 仍失败时才显式报错，禁止用固定兜底文案冒充成功结果
- 禁止模型兜底回复文案：模型失败、超时、空响应、结构化解析失败时，必须返回真实错误原因；禁止输出“系统处理中/请稍后重试”等固定文案冒充成功结果
- AdaptiveRAG
adaptive_rag_answer_normal空响应必须显式抛错并交由 high failover 处理；禁止在生成层直接回落为“补充问题细节后重试”之类的兜底回复 - 用户可见问答链路（
function_name含answer/reply/qa）禁止使用reasoning_content回退，避免思考过程外漏 - AdaptiveRAG 场景化 Prompt 选择器必须在
mixin_deep_guard_answer.py组装 Prompt 前执行，并遵循固定优先级：成员负载 > 趋势（项目关联 external_trend / 通用 industry_trend） > mixed > AI PMO 入口 > 默认 RAG - 通用行业趋势问答（如“宠物行业最新动态”）不得注入数据库、项目历史、用户历史或外部实时搜索结果；只有显式带项目上下文时才允许走
external_trend，对“不要提项目/别提项目”这类否定语句不能误判为项目上下文 - mixed 场景回复必须强制两段格式输出：
[回答]与[已收到需求] ...，已入库处理，禁止把需求段落并入问答段落 - 飞书与 AI PMO 入口（含
message_intent=mixed）问答链路必须绕过 deterministic/snapshot/glm_semantic 快路径，统一落到场景化 Prompt 生成，避免旧确定性清单回复覆盖场景格式 - 本地
ollama仅允许知识库问答链路使用，且必须通过llm_engine.settings.enable_local_kb_qa显式开启；未开启时运行期与连通测试都不可用 - AI Steward 零配置创建任一步 LLM 失败、超时或 JSON 非法时必须直接报错，禁止回退默认 analysis/signal/charter/tasks 草稿
- Signal Source Onboarding 的 planner/worker 任一步失败必须显式报错或标记 failed，禁止 heuristic/fallback 兜底计划与“最小闭环”摘要
- AI Steward 不再暴露 OpenClaw 指挥规划入口，
/ai-steward/command/dispatch视为下线路径 - AI PMO 写操作（
project.create/signal.create/signal_source.onboard）默认先生成草稿并进入draft_pending_confirm，未确认前禁止自动执行入库；project.create的 Feishu 文本入口先转待确认卡片，点击后才允许执行 - 草稿确认只认显式
reply_to_message_id+ 明确草稿动作（确认/修改/取消）或显式work_item_id；草稿确认必须校验draft_version，并通过confirm_message_id防重放；草稿超时取消统一由draft_expiry_worker+feishu_reply_outbox处理 - AI PMO 执行层必须统一产出
execution_result.action_contract与action_param_source，并写入operation_execution_ledger；禁止在执行链路旁路写副作用且不入账 - AI PMO 写操作幂等以消息级锚点为准：优先使用
source_message_id/feishu_message_id作为执行账本幂等键，标题/正文仅用于业务内容，不得参与重复执行判定 - PMFlow 业务语义治理：会决定
project.create / signal_source.onboard / followup.* / query vs execute的中文关键词、正则、looks_like_*、*_HINTS/*_KEYWORDS只能定义在backend/app/services/ai_pmo/workflow_semantic_planner/或 prompt/catalog 配置层；其他目录仅允许做文本清洗、ID/URL/repo/locator 抽取与结构化结果解析 scripts/semantic_lint.py+scripts/semantic_lint_baseline.txt为语义治理守门脚本；CI 会阻止新的散落语义进入非 allowlist 目录，baseline 仅记录已知兼容残留- 只读问答链路的 prompt 读取优先级固定为：
prompt registry manifest 校验 -> active prompt release -> 代码 seed prompt fallback；业务服务禁止直接绕过PromptReleaseService拼接已纳管的 read-only QA prompt - 回复质量迭代与训练管线的原始反馈入口统一复用
feedback_center_records/qa_records/ai_call_logs；新增quality_assets/training_datasets只能作为派生层，禁止再造平行原始数据主表 - 训练/微调 artifact 只能先进入
trained_model_artifacts -> trained_model_deployments内部候选链路，再绑定到low/high逻辑槽位；禁止在产品/API/日志直接暴露训练后真实底模名
9. 新增代码的参考模式
- 新增后端接口：参考
backend/app/api/sstc.py的结构 - 项目创建接口：参考
backend/app/api/ai_steward_api/routes_capture.py（POST /ai-steward/project-from-text统一{code,message,data}，返回signal_sources） - 模型路由配置接口：参考
backend/app/api/model_routing.py（GET/PUT /model-routing/functions/{function_name}，仅管理员可写并写入operation_logs） model-routing只暴露逻辑层字段：function_name/tier_alias/source/rule_name/rule_priority/last_execution；PUT仅接受tier_alias=low|high- 回复质量闭环接口：参考
backend/app/api/ai_steward_api/routes_reply_iteration.py（POST /ai-steward/feedback-center/items/{id}/promote、/reply-iteration/judge-runs/candidates/prompt-releases/trials） - 训练/微调管线接口：参考
backend/app/api/ai_steward_api/routes_training_pipeline.py（GET/POST /ai-steward/training/datasets/jobs、GET /training/jobs/{id}/evaluations、POST /training/artifacts/{id}/promote、POST /training/deployments/{id}/decision） - 任务包中心接口：参考
backend/app/api/task_briefs.py（/task-briefs/center/templates/runs/generate/contract-sync） - KG 上下文闭环接口：参考
backend/app/api/knowledge_graph.py（GET /ai-steward/knowledge-graph/capability-summary、POST /ai-steward/knowledge-graph/verify-context-consumption） - 需求点落信号源：参考
backend/app/services/signal/signal_source_orchestration/mixin_registry_execute.py（materialize_requirement_sources负责归一、去重与raw_context持久化） - 审计查询接口：参考
backend/app/api/audit.py（GET /audit/operations） - 脏数据修复接口：参考
backend/app/api/ai_steward.py（POST /ai-steward/signal-sources/repair-dirty） - LLM 引擎设置接口：参考
backend/app/api/llm_engines.py（PUT /ai-steward/llm-engines/settings，仅管理员可修改本地知识库问答开关） - 飞书捕获模拟接口：
POST /ai-steward/signal/capture-feishu在direct_reply_required=true时会同步写入feishu_reply_outbox，并返回reply_outbox_enqueued/reply_outbox_id便于链路自检 - 配置读取类接口：参考
backend/app/api/llm_providers.py（GET /ai-steward/llm/providers） - 老板晨报接口：参考
backend/app/api/ai_steward_api/routes_executive_briefing.py（GET /ai-steward/executive-briefing?mode=snapshot|live、GET/PUT /ai-steward/executive-briefing/config，仅BOSS/ADMIN可访问） - 每日简报 v2 接口：参考
backend/app/api/ai_steward_api/routes_brief_blockers.py（GET /ai-steward/daily-briefing-v2?mode=snapshot|live，普通成员返回个人版，BOSS/ADMIN返回全租户版） - 模型配置唯一来源：参考
backend/app/services/model/model_config.py（统一读取backend/.openclaw/pmflow-routing-rules.json内的provider_defaults/tier_defaults/rules） - 模型配置热更新后，LLM provider circuit 会在下一次调用时自动清空旧熔断状态，避免旧配置失败污染新配置的连通性判断
- 启动期模型探针只做连通性观测，不应把探针失败写回 provider circuit；否则会误伤真实业务请求
- AI Steward 指挥规划接口已移除：
POST /ai-steward/command/dispatch - 项目删除接口（
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 恢复接口（
POST /ai-pmo/work-items/{work_item_id}/resume）：支持action=continue|commit|refresh|cancel，复用同一闭环恢复入口 - AI PMO 草稿决策接口（
POST /ai-pmo/work-items/{work_item_id}/draft-decision）：支持action=confirm|revise|cancel，与飞书“确认/修改/取消”行为一致 - AI PMO 路由包（
backend/app/api/ai_pmo_api/__init__.py）只负责聚合与 tags，/ai-pmo前缀只能由子模块共享 router 挂一次，禁止包级与模块级重复叠加前缀导致/ai-pmo/ai-pmo/...路径 - RAG 问答主入口契约（
POST /rag/ask）：HTTP 入口已收敛到AIPMOKernelService.process_ingress主链；请求侧统一透传asked_via/action_mode/message_intent/mixed_signal_part，由ingress_options.rag_request_context下传到 query executor 并映射到AdaptiveRAGService.answer_question，返回侧从 ingressrag_result/direct_reply_text组装兼容响应 - RAG / AI 管家顾问合同：
POST /rag/ask返回体会透传consultant_dispatch={domain,mode,risk_level,missing_fields,allow_execute,next_action}；该合同由backend/app/services/ai_pmo/consultant_dispatch.py统一生成，飞书 mention 回复与 AI 管家问答共享同一份模式判断 - RAG / AI Steward 路由包（
backend/app/api/rag_api/__init__.py、backend/app/api/ai_steward_api/__init__.py）不再重复挂包级 prefix；路由 canonical 由shared.py内的共享 router 统一承担，避免运行中出现/rag/rag/*、/ai-steward/ai-steward/* - AI PMO 消息台列表接口（
GET /ai-pmo/work-items）：返回latest_policy_gate_code与规范化approval_requirement{required,reason,message}（来源于最新decision_records投影） - AI PMO 消息台列表接口补充：返回草稿字段
draft_content/draft_expires_at/draft_version/confirm_message_id，用于草稿确认卡片渲染 - 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持久化实现模块 - 通用任务拆解接口（
POST /tasks/breakdown）统一返回结构化任务业务对象，支持project_id/charter_id上下文与 Plane 同步 - SSTC 信号列表接口（
GET /projects/{project_id}/signals）标题生成规则：优先signals.title，其次signals.summary，最后回退signals.content去前缀文本 - SSTC 宪章详情接口（
GET /projects/{project_id}/charters/{charter_id}）alignment_records[]补充user_name/confirmed_at，用于前端展示“对齐成员 + 对齐时间” - SSTC AI 拆解接口（
POST /projects/{project_id}/charters/{charter_id}/tasks/ai-breakdown）执行任务标题去重（同次 + 历史任务），返回skipped_duplicates/auto_assigned_count，并落ai_breakdown_payload/manual_overrides - SSTC 负责人推荐接口（
POST /projects/{project_id}/tasks/{task_id}/recommend-assignee）直接消费required_skill_tag_ids语义，不再把技能 ID 当字符串 - SSTC 任务更新接口（
PATCH /projects/{project_id}/tasks/{task_id}）会把人工修改写入manual_overrides，供后续 AI 重跑识别覆盖层 - SSTC 发布创建接口（
POST /projects/{project_id}/releases）新增已关联任务拦截：若task_ids命中历史发布计划已绑定任务，返回409+detail.task_ids - 信号源编排补充：
SignalSourceOrchestrationService已停止运行时调用旧 command-first 执行链，统一改为“GLM 分析后直接调用服务写入”，编排结果字段对外收敛为execution - 新增前端 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可用 - 项目创建返回的
signal_sources仅作为 AI Steward 创建结果区的内联展示，现阶段不新增独立页面路由；底层持久化统一复用现有SignalSourceRegistry - 老板晨报首版的
external_metrics只返回占位区块，不接 CRM / BI / 收入系统，也不允许伪造经营指标 - 老板晨报调度默认值为
08:30 + workdays + Asia/Shanghai；若delivery_target_ref未配置，调度器仍生成快照，但只记录告警、不静默伪装成已推送 daily-briefing-v2与老板晨报当前只做同会话内snapshot/live同步，不引入 WebSocket 推送；导出仅复用浏览器打印能力- 若当天
executive_brief快照仍是旧结构（缺少id/detail_lines/meta等字段），读取snapshot时会自动按当前事实重建新版 payload；因此默认快照优先保证可交互与可导出，而不是强行返回半旧版结构 - 未匹配项目的孤立 signal 不再进入简报中心卡片；这类数据仅保留在信号工作台中处理，避免老板视图出现无项目、无负责人、无真实定位的伪待办
- 简报中心首页卡片固定高度并允许内部滚动；完整明细统一放在右侧详情抽屉与打印导出中，移动端退化为全屏 Dialog，不新增第二套详情页
- 飞书长连接 websocket 在本地/CI 环境默认使用
certifiCA bundle 作为信任链；如需自定义 CA，可通过FEISHU_LONG_CONNECTION_SSL_CERT_FILE或SSL_CERT_FILE覆盖 - 飞书长连接状态分为两层：
last_received_at/last_received_message_id表示 SDK 回调已收到事件，last_event_at表示 worker 完成处理；排查“没吃进去”时必须优先看last_received_* - 飞书长连接会话应复用
Integration.config中已有的encrypt_key/verification_token；配置保存时若未显式修改这两个字段，必须保留现有值，避免 SDK 因缺失事件密钥而拒收消息 - LLM 主链按
OPENCLAW_ROUTING_ENABLED走 OpenClaw 路由规则（backend/.openclaw/pmflow-routing-rules.json）；请求超时统一以LLM_REQUEST_TIMEOUT环境变量为准 - 路由配置唯一真源固定为
backend/.openclaw/pmflow-routing-rules.json；根目录.openclaw仅允许不存在，禁止再挂载/app/.openclaw - LLM 非结构化响应仅在非用户可见链路且显式开启
LLM_REASONING_CONTENT_FALLBACK时，才允许从reasoning_content回退；answer/reply/qa链路一律禁用该回退 - World Model 静态层已接入 Redis 缓存（key:
wm:static:{tenant_id}:{project_id}，TTL 600s） - 写操作后主动 invalidate，动态层不缓存
- AI PMO 意图识别已切换
model-only：_resolve_intent仅接受 LLM 结构化结果，不再走规则/正则兜底链路 - AI PMO / Feishu 执行门已取消置信度阈值拦截与高风险人工复核：
confidence仅保留在decision_trace/ processing log 中作观测，不再作为自动执行的 reject 条件；当前门禁仅保留force_manual与correction_action - 模型默认值与 provider/tier 映射以
backend/.openclaw/pmflow-routing-rules.json为唯一配置源；.env/.env.example仅保留 API key 与运行开关，OPENCLAW_ROUTING_RULES_PATH只用于定位这份文件 - 调用层与路由页面只使用
low/high两层语义；safety已废弃并从配置校验、运行时解析、前端选项中移除 - AI Steward 项目创建与 LLM 主链不再在业务层手写
*_glm47_fallback -> GLM-5跨函数升级；项目分析函数名与高低层模型选择统一由backend/.openclaw/pmflow-routing-rules.json决定 - Signal Planner 函数路由支持
integrations(type='model_routing')的tier_alias覆盖；配置缺失时按 OpenClawlow/high规则解析，不再直接暴露真实模型名 - Signal Planner 结构化调用采用
25s硬超时：超时或结构化不合法时标记失败并通知人工重试，不再写入降级ai_planner(fallback_mode=true) - AI Steward 用户侧已移除 OpenClaw 指挥规划入口；后续项目分析主链以 GLM 严格失败直出为准
- 飞书业务命令命中旧 command-first 路由时，仅返回“已下线”阻断提示，不再触发实际执行
- 真实模型名仅保留在
backend/.openclaw/pmflow-routing-rules.json与内部解析流程中；调用页面、查询接口、ai_call_logs不直接暴露 provider/model - 双层路由治理：低/高层函数统一由 OpenClaw 规则命中到
low/high逻辑槽位（含classify_intent_ai_pmo_kernel的双层命中） - low/high DDL 治理图谱的模型来源统一读取
backend/.openclaw/pmflow-routing-rules.json中的provider_defaults/tier_defaults；不再依赖LLM_ROUTING_LOW_MODEL/LLM_ROUTING_HIGH_MODEL作为主配置 - 写操作链路统一产出
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强制进入人工确认，不直接自动执行 - 飞书
qa_llm回复已增加事实熔断：命中“数据库迁移/DDL/Alembic/让我直接处理/模型失败了所以没分析”等漂移语句时，自动回退固定模板，禁止对外宣称未证实执行动作 - 飞书
humanized_reply与 RAG 问答 Prompt 已显式禁止思考过程外显；回复链路会过滤以“让我先/让我尝试/我来看看/我先查/让我看看/我需要先”开头的前置段落 - 数据库与核心写入链路统一使用北京时间（
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），避免历史脚本直接查旧表名失败 signal_source.onboard已加入工作流门禁旁路：进入执行阶段后按闭环结果返回succeeded/pending_manual/failed_safe，不再被前置仿真门禁直接拦截为waiting_manual- 飞书入站已拆分“短确认同步快路径 + 非短确认异步队列”：短确认命中会话窗口时直接继承上轮意图并同步执行；其余消息先回“已收到，正在处理”后由
ai_orchestration_runs异步 worker 执行与重试 - 飞书会话与问答上下文键已改为线程/消息锚点优先：优先
reply_to_message_id/root_message_id/thread_id/source_message_id，避免 sender 级最近会话复用串线；草稿确认还需要回查feishu_reply_outbox.sent_message_id，以便把“回复草稿消息”的线程锚点映射回对应 work_item - 准确率优先通道默认深度回答：
feishu/lark/feishu_group/feishu_dm/pmflow/pmflow_manual/ai_pmo/ai_pmo_ui统一按高精度通道处理；Feishu 入口遇到 query / ignore / question-like 消息时优先 sync-first，不再先入异步 ACK-first 队列，只有明确 write intent 才允许走异步回执 - Feishu 现在是双通道：消息事件继续走长连接，但
card.action.trigger的卡片按钮回调必须单独配置 HTTP callback（/api/feishu/card-action）；路由会优先使用Integration.config中的encrypt_key/verification_token做验签与解密，若签名与当前控制台配置短暂不一致，则对卡片按钮回调启用 permissive fallback 继续派发，保证按钮可用；回调响应现在优先返回toast反馈，避免无效卡片结构触发 Feishu 侧报错，入库/处理结果再由 outbox 群聊回执补充，但生产环境仍建议保持 token / key 与控制台一致 - 飞书回复线程锚点抽取同时兼容 event 顶层与 message/content 内字段，并对 event/message 的嵌套结构做递归兜底；若 Feishu SDK 返回的 reply 关系字段在更深层对象里，也必须纳入线程锚点，不可只读
message.content - 飞书异步入站队列在
ai_orchestration_runs.result_payload.task_payload中必须保留thread_context，worker 重放时不得仅依赖source_message_id，否则 reply-thread 会在异步链路丢锚点 - 飞书纯问答直答不再注入群聊级
project_id兜底上下文；只有显式 reply-thread / follow-up 线程锚点命中时，才允许继承上一轮语义上下文，禁止把群里最近项目当成普通新问题的默认场景 - 外部渠道
asked_by=None的 QA 也必须 materialize 到真实qa_sessions：统一用external_conversation_key复用会话，并允许qa_session_states持久化pending_clarification - 外部 QA 的
external_conversation_key在 Feishu 场景下必须写稳定conversation_scope_key：默认chat_id + sender_open_id，仅 sender_open_id 缺失时才降级到chat_id + sender；禁止再把source_message_id当成连续问答 scope key - “这个/刚才/那条” 这类外部追问默认按连续对话处理：同线程/同发送者最近 5 分钟内仅 1 条 PMFlow 回复时直接绑定；有 2-3 条候选时返回文本编号澄清；只有完全无锚点时才返回
no_anchor_found - 外部 QA 若存在显式
reply_to_message_id，必须优先按消息级锚定处理：先反查feishu_reply_outbox.sent_message_id还原被引用的 PMFlow 回复；若消息 ID 无法映射，也要回退到当前入站消息携带的closure_turns/closure_dialogue恢复上一轮机器人回复，再回退到 session/recent candidates；禁止把“直接引用机器人回复”的消息仍判成无锚点 - 外部 QA 的“追问歧义”与“模型/上游失败”必须分开：前者返回
clarification_code（如ambiguous_recent_reply/no_anchor_found）及候选列表，后者继续保留真实 provider/空响应错误，禁止共用模糊兜底文案 - 外部 QA 的
qa_records必须持久化conversation_scope_key/source_message_id/source_chat_id/source_sender_open_id/reply_to_message_id/root_message_id/anchor_kind/anchor_ref/routing_snapshot，用于回答“为什么没接上上一条”“为什么走了候选澄清”“上一条回复走的是 low 还是 high” - 元追问（如“哪个模型回复的”“为什么那条报错”“你刚才那句什么意思”）必须优先锚定最近一条 PMFlow 回复；对外只允许返回
planned_tier/executed_tier/route_source/route_rule_name/routing_decision这类 low/high 路由语义，禁止暴露真实 provider/model 名称 - Prompt release 目前只接入只读回复链路（AdaptiveRAG / query.read_only）；写操作 workflow 仍使用代码 prompt 与显式人工 gate，避免训练试验误触执行副作用
- 训练自动化/影子回放当前只允许覆盖只读问答链路；
project.create/signal.create/signal_source.onboard/task.create等写操作 workflow 继续排除在自动训练与自动试验之外 - 成员/负载类问答（如“杨宇现在负载情况如何”）会优先走
users + user_workloads的确定性直查；只有姓名/账号能唯一匹配时才直接返回数据库负载答案，不再把项目列表或历史上下文混入负载结论 - 会话命中
session.last_intent=draft_pending_confirm不再自动劫持普通消息；只有明确reply_to_message_id且消息本身是草稿动作，或显式work_item_id命中挂起草稿时，才进入草稿确认处理器 - 飞书 follow-up 状态追问不再猜测“最近一条处理项”；只有显式 reply 锚点或唯一业务目标匹配时才允许继续查询，避免多个话题并行时串线
- 草稿确认成功后执行路径复用
followup恢复链路，目标 work_item 在同事务内完成状态迁移与decision_records.final_outcome更新 - 飞书回复 outbox 已支持
text + interactive card双通道：执行场景命中draft_pending_confirm/pending_manual时优先入队按钮卡片；卡片消息仍经 outbox 异步派发（不走业务路径同步直发） - 飞书长连接
card.action.trigger不能复用普通消息的纯入队 callback；专用 card action HTTP 回调必须先完成验签/解密并同步返回可见toast响应，再把事件交给异步 worker/业务服务处理，否则 Feishu 会直接报200340 - Feishu 长连接 SDK 的 websocket client 在后台线程内必须绑定 thread-local event loop；不能复用 FastAPI 主事件循环，否则会触发
this event loop is already running并引发连接重试风暴/额度耗尽 - AI PMO 回执渲染器
ReplyRenderer已按operation_code收口 CRUD 写回执：project/task/personnel/knowledge/notification的成功态与待确认态都必须从execution_result.action_contract/ intent 参数生成可读文案，禁止再回落成泛化“已收到并入库”提示 - 飞书入口已按职责拆分为“预处理/捕获执行/结果回执”三层：
mixin_receive.py仅保留编排，mixin_receive_prepare.py负责传输解析与上下文抽取，mixin_receive_capture_flow.py负责 capture 持久化与回执收尾 ai_orchestration_runs.project_id允许为空：用于承载尚未完成项目归属判定的入站异步任务；既有signal_source_onboarding运行仍按显式project_id写入/ai-pmo/process-text问答链路在 AdaptiveRAG 内通过asked_via=pmflow_manual识别为 AI PMO 入口；mixed 场景通过message_intent=mixed透传触发专用 Prompt 与两段输出格式化/rag/ask已改为经 AI PMO kernel ingress 主链执行（与飞书长连接、/ai-pmo/process-text同链路）；query 执行阶段通过rag_request_context保留session_id/new_session/thinking_mode/action_mode/sync_requirement/message_intent/mixed_signal_part- AdaptiveRAG
answer_question入口已拆为“双阶段”：_prepare_answer_runtime（会话/上下文/动作模式解析）+_execute_base_answer_mainline（基础问答主路径）；写确认ackgate 仅在sync_requirement=true && action_mode in write/read_write && 非 feishu时触发 - AI PMO ingress 执行路径（
waiting_manual/draft_pending_confirm/auto execute）已统一写入operation_execution_ledger，operation_code与execution_result.action_contract一致；账本状态统一映射为applied/pending_manual/pending_confirmation/failed PROMPT_DECOMPOSE_TASKS技能标签来源已改为运行时动态注入：优先读取skill_tags（按sort_order/name），为空时才回退默认技能集合
12. 技术债务清单
mixin_auto.py_safe_intNameError：已通过显式导入_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已接入消息级幂等账本：Feishusource_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已锁定回归 - 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 PMOprocess_ingress主链继续执行；回调 HTTP 现在会同步返回 toast 反馈，确保点击按钮后至少有可见结果；backend/tests/test_feishu_card_action_contract.py已补卡片构造与continue回归契约