782 lines
123 KiB
Markdown
782 lines
123 KiB
Markdown
# PMFlow 项目结构说明（CLAUDE.md）
|
||
|
||
## 1. Agent 入口文件（你关心的“进项目先读什么”）
|
||
- `AGENTS.md`：Codex/Coding Agent 的主规则入口（优先级最高的项目级约束）
|
||
- `CLAUDE.md`：面向 Claude 风格的项目说明文档（补充背景）
|
||
- 建议：规则放 `AGENTS.md`，架构/目录说明放 `CLAUDE.md`
|
||
- 当前 AI 行为的系统宪章已在 `AGENTS.md` 中升级为“事实层 / 评审层 / 生成层 / 执行层”四层分治；所有新增 AI 业务默认按该宪章接入，`CLAUDE.md` 仅保留结构与背景说明
|
||
- 新增执行约定：计划类需求一旦确认进入实现阶段，默认连续执行到“实现完成 + 验证完成 + 统一回复验收结果”；仅在明确阻塞、高风险冲突、context 限制或用户主动中断时才中途打断。
|
||
|
||
## 2. 项目定位
|
||
- 项目名：`PMFlow / Neural Sync`
|
||
- 形态：AI 原生项目管理系统（多租户 + 角色权限 + SSTC 工作流）
|
||
- 技术栈：
|
||
- 后端：`FastAPI + SQLAlchemy + Alembic`
|
||
- 前端：`React + TypeScript + Vite + Tailwind + Radix + React Query`
|
||
|
||
## 3. 顶层目录（精简版）
|
||
```text
|
||
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/superpowers/plans/`（本地实现计划与执行拆解文档目录）
|
||
- 新增：`docs/task_briefs/`（增量任务包生成产物目录）
|
||
- 新增：`docs/task_briefs/sidebar_new_entries_20260312.png`、`docs/task_briefs/model_routing_override_effective_20260312.png`（Step 8 页面验收截图）
|
||
|
||
## 4. 后端结构（`backend/`）
|
||
```text
|
||
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 旧函数名清理与重命名迁移
|
||
│ ├── 20260405_add_mounted_ai_runtime_tables.py # Mounted Runtime 建表迁移
|
||
│ ├── 20260405_add_mounted_runtime_plan_state_fields.py # Mounted Runtime plan_status / conversation_scope_key 字段
|
||
│ └── 20260406_add_mounted_runtime_active_draft_fields.py # Mounted draft active work item / message anchor 字段
|
||
├── 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
|
||
│ └── test_sstc_charter_release_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/signal_source_repair/service.py`（脏信号源回填服务：优先回填既有 Signal，不足时物化正式 Signal）
|
||
- 更新：`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/20260331_add_qa_record_runtime_fields.py`（`qa_records` 增加 `answer_mode/grounding_status/policy_version/citations/sources_used/evidence_pack/tool_trace/retrieval_metrics`，用于 Grounding Runtime 持久化与回放）
|
||
- 新增：`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_steward_service/mixin_creation_normalize_persist.py`（项目创建归一化阶段新增技能标签解析 + `recommend_personnel` 自动指派；项目、宪章、任务落库时同步写入 `assignee_id/ai_recommended_assignees`）
|
||
- 新增：`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`（轻量顾问式统一调度合同与注册表：当前仅保留给 `/rag/ask` 等顾问式问答合同使用；已退出 Feishu mention 主回复与 AI PMO ingress capture 主链）
|
||
- 新增：`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，并把 `derived_artifacts.task_seeds/verification_metrics/risk_gates` 暴露给下游）
|
||
- 更新：`backend/app/config/ai_prompts_catalog/part_01.py`（`PROMPT_TASK_BREAKDOWN` 统一为结构化任务业务对象输出）
|
||
- 更新：`backend/app/config/ai_prompts_catalog/part_03.py`（`PROMPT_GENERATE_CHARTER` 改为输出 `modules/field_status/field_evidence/readiness/derived_artifacts`；`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 PMO `task.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_qa_record_runtime_fields_migration.py`（QA Runtime migration 回归：`qa_records` runtime/evidence 字段新增与回滚）
|
||
- 新增：`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_ledger` upsert、账本状态归一）
|
||
- 更新：`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_sstc_charter_release_contract.py`（SSTC 宪章总确认/发布验证契约回归：readiness 阻断、verification metrics 来源约束）
|
||
- 新增：`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 Steward `project-from-text` 契约回归：`code/message/data` 包络与 `signal_sources` 字段）
|
||
- 新增：`backend/tests/test_signal_source_requirement_materialization.py`（需求点 -> 信号源注册项归一/去重/原始上下文回归）
|
||
- 新增：`backend/tests/test_signal_source_repair_materialization.py`（历史 registry 修复回归：优先回填项目内既有 Signal，否则物化正式 Signal）
|
||
- 新增：`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/dispatch` OpenClaw 指挥规划入口）
|
||
- 更新：`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/services/ai_pmo/semantic_context/`（OpenCow 风格语义上下文子模块：统一 `SemanticContextPacket/ModeCard/SemanticDecision/DecisionGateResult` 契约、`SemanticContextAssembler`、`SemanticDecisionGatekeeper` 与 `SemanticDecisionService`；当前已接入 ingress shadow 观测，并为 intent/query-scene 主链提供 direct metadata 替代语义入口）
|
||
- 新增：`backend/app/models/reply_iteration.py`（回复质量迭代模型：`QualityAsset/QualityAssetPair/JudgeRun/OptimizerCandidate/PromptRelease`）
|
||
- 新增：`backend/app/models/training_pipeline.py`（训练/微调管线模型：`TrainingDataset/TrainingJob/TrainingEvaluation/TrainedModelArtifact/TrainedModelDeployment`）
|
||
- 新增：`backend/app/models/mounted_ai_runtime.py`（Mounted Runtime 运行时模型：`MountedTopicWorkspace/MountedDraftWorkspace/MountedConversationRun/MountedAgentTrace/MountedSourceActivation/MountedToolCapabilityPolicy`；`MountedTopicWorkspace` 额外承载 `conversation_scope_key + plan_status`，用于同群同人 topic 隔离与 plan 状态机；`MountedDraftWorkspace` 额外承载 `active_work_item_id + latest_source_message_id + latest_reply_message_id`，用于当前 active draft 绑定与 reply anchor 锚定）
|
||
- 新增：`backend/app/services/reply_iteration/service.py`（反馈中心提升为学习资产、裁判分桶、候选改动、prompt release trial 服务；支持 `backfill_mounted_training_assets_from_feedback`：从真实 `feedback_center_records + qa_records` 回填 golden/failure、preference pair 与 judge runs，供 mounted runtime 真实业务训练使用）
|
||
- 新增：`backend/app/services/training_pipeline/service.py`（训练数据集、训练作业、评测、artifact promote、deployment 决策服务；支持 `bootstrap_mounted_training_wave`：自动从 mounted runtime 质量资产生成 `teacher_dev_set / teacher_eval_frozen_set / sft / preference`，并启动 low/high 训练波次；mounted wave 会立刻消费本次 queued jobs，产出 completed job/evaluation/acceptance gate；当 failure 样本带 `corrected_answer` 时会自动合成 synthetic golden / preference pair）
|
||
- 新增：`backend/app/services/prompt_release/service.py`（只读 QA prompt release 版本管理与 serving 渲染优先级）
|
||
- 新增：`backend/app/services/mounted_ai_runtime_service.py`、`backend/app/services/mounted_ai_runtime_write_service.py`（Mounted Runtime 读模型与写路径：来源/主题/run 查询、source activation / tool policies / training ops / hard cases / replay-run 管理，以及 ingress topic/run/trace/source-activation 落库；当某来源存在 active activation 白名单时，仅命中的 scope 才进入 mounted tracking；run detail 会返回 rich trace：`input_summary/output_summary/tool_trace`，并暴露 `topic/draft/semantic_packet_summary/semantic_decision/semantic_gate_result/semantic_diff`；写路径会持久化 `conversation_scope_key`、显式 `plan_status` 与 semantic shadow 观测结果）
|
||
- 新增：`backend/app/api/ai_steward_api/routes_reply_iteration.py`（AI Steward 回复质量闭环接口：反馈提升、judge-runs、candidates、prompt-releases、trials，以及 `POST /ai-steward/reply-iteration/backfill-mounted-assets` 真实业务训练资产回填入口）
|
||
- 新增：`backend/app/api/ai_steward_api/routes_training_pipeline.py`（AI Steward 训练管线接口：datasets、jobs、evaluations、artifacts、deployments，以及 `POST /ai-steward/training/mounted-wave` 一键训练波次入口、`POST /ai-steward/training/jobs/{id}/run` 单 job 执行入口）
|
||
- 新增：`backend/app/api/ai_steward_api/routes_mounted_ai.py`、`backend/app/schemas/mounted_ai_runtime.py`（Mounted Runtime 控制台接口：sources/source-activations/tool-policies/topics/runs/run-detail/cutover-status/eval-suites/training-ops/hard-cases，以及 admin/source-activation、admin/tool-policy、admin/replay-run）
|
||
- 新增：`backend/alembic/versions/20260327_add_reply_iteration_training_tables.py`（回复质量迭代/训练管线主迁移：学习资产表、prompt release、训练数据集、训练作业与 experiment 扩展字段）
|
||
- 新增：`backend/alembic/versions/20260405_add_mounted_ai_runtime_tables.py`（Mounted Runtime 建表迁移：topic workspace、draft workspace、conversation run、agent trace、source activation、tool capability policy）
|
||
- 新增：`backend/alembic/versions/20260405_add_mounted_runtime_plan_state_fields.py`（Mounted Runtime 计划态增强迁移：`mounted_topic_workspaces` 新增 `conversation_scope_key / plan_status`，支撑同群同人多 topic 隔离与 plan 状态机）
|
||
- 新增：`backend/alembic/versions/20260406_add_mounted_runtime_active_draft_fields.py`（Mounted Runtime active draft 锚点迁移：`mounted_draft_workspaces` 新增 `active_work_item_id / latest_source_message_id / latest_reply_message_id`，支撑 session-first 草稿确认与最新回包锚定）
|
||
- 新增：`backend/tests/test_reply_iteration_service.py`、`test_training_pipeline_service.py`、`test_reply_iteration_api.py`、`test_reply_iteration_training_migration.py`（回复质量闭环与训练管线基础回归）
|
||
- 新增：`backend/tests/test_mounted_ai_runtime_models.py`、`test_mounted_ai_runtime_migration.py`、`test_mounted_ai_runtime_api.py`、`test_mounted_ai_runtime_write_service.py`（Mounted Runtime 模型/迁移/API/写路径回归）
|
||
- 新增：`backend/app/services/ai_pmo/ai_pmo_kernel/ai_pmo_workflow_runtime.py`（AI PMO `ContextAssembler` + `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/signal/signal_capture_service/mixin_capture_entry.py`（Feishu capture 在 source activation 存在 active 白名单规则时，未命中 scope 的 chat 直接返回 `mounted_runtime_scope_not_activated`，不再继续进入 kernel/queue）
|
||
- 更新：`backend/app/services/signal/signal_capture_service/mixin_capture_entry.py`（kernel 未处理或 capture 主链异常时会回滚当前 session 并把真实失败原因写入 `direct_reply_text`，不再回退统一“系统处理中出现异常”伪成功文案）
|
||
- 更新：`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` 时优先路由草稿确认处理，并把 ingress 主链同步写入 Mounted Runtime 的 topic/run/trace；除主脑 `ConversationOrchestrator` 外，还会额外记录 `PlanCoach/Clarifier/DraftSynthesizer/Executor` 等 specialist trace；`query.answer` + `business_review/assignee` 场景会在 runtime 中收口到 `plan/chat`，不再伪装成 `execute/Executor`；query-scene 强制改为优先读取 direct metadata，不再在主链回填 `semantic_bundle`；kernel 失败改为 `logger.exception` 保留完整 traceback）
|
||
- 更新：`backend/app/services/ai_pmo/ai_pmo_typed_executor_execute/mixin_execute_query_project.py`（query `failed_safe` 只在 SQLAlchemy session 已进入 failed/inactive 状态时回滚，避免把同链路的 ingest/work_item 一起回滚掉；需求收敛/范围建议/负责人推荐/项目存在性查询会优先走 deterministic 直答，不再默认落到 heavy RAG；query executor 对 `message_intent/consultant_mode_preference/advise_subtype/force_thinking_mode` 改为 direct metadata first，旧 `semantic_bundle.diagnostics` 仅保留兼容兜底；`requirement_plan` followup 在存在 active workspace 时优先按 mounted runtime 状态与字段增量续接，不再先依赖旧 planner 猜 continuation；“一个 AI 客服工具，这个项目有吗”这类问句会直接返回项目事实库命中结果）
|
||
- 更新：`backend/app/services/ai_pmo/ai_pmo_kernel/mixins/intent/ai_pmo_kernel_mixins_intent_resolve.py`、`ai_pmo_kernel_mixins_intent_llm.py`、`backend/app/services/ai_pmo/ai_pmo_kernel/mixins/ingress/ai_pmo_kernel_mixins_ingress_render.py`（意图解析主链移除 `signal_source.onboard` 的 pre-LLM 规则锁；LLM metadata 不再注入 `semantic_bundle`；capture result 仅生成 `direct_metadata_compat` 形式的兼容语义包，不再为回包临时重跑 `workflow_semantic_planner`）
|
||
- 更新：`backend/app/services/adaptive_rag_service/mixin_followup_anchor.py`、`mixin_fast_answer_project_main.py`（standalone 项目存在性问句不再误判成 referential followup；项目风险/阻塞问句在无任务拆解时返回“缺任务分解、缺里程碑、缺负责人推进节奏”的风险代理信号，不再给空泛兜底）
|
||
- 更新：`backend/app/services/ai_pmo/ai_pmo_typed_executor_discovery/mixin_discover.py`、`backend/app/services/ai_pmo/ai_pmo_kernel/mixins/intent/ai_pmo_kernel_mixins_intent_resolve.py`（discovery mixin 补齐 `_safe_int/_utc_now_naive` 导入，消除真实 discovery 执行时的 `NameError`；`signal_source.onboard` 不再走 pre-LLM 规则锁，主链保持 model-only，再由后续 route/gate 约束）
|
||
- 更新：`backend/app/services/ai_pmo/ai_pmo_kernel/mixins/intent/ai_pmo_kernel_mixins_intent_rules.py`（canonical intent builder 现在保留 `project.update/task.* / personnel.* / knowledge.* / notification.*` 等 mutation intent，避免 LLM 已识别的写操作被错误降级成 `ignore`）
|
||
- 更新：`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/`）
|
||
```text
|
||
frontend/
|
||
├── e2e/ # Playwright 真实浏览器 E2E 用例
|
||
├── 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
|
||
├── playwright.config.ts
|
||
└── 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/mountedAi.ts`（Mounted Runtime 控制台 API：sources/source-activations/tool-policies/topics/runs/run-detail/cutover-status/eval-suites/eval-suite-detail/training-ops/hard-cases/admin actions，以及 `startTrainingWave`）
|
||
- 更新：`frontend/src/api/aiSteward.ts`（移除 OpenClaw dispatch 封装，新增 LLM 引擎 CRUD / settings 封装）
|
||
- 更新：`frontend/src/api/aiSteward.ts`（新增 AI 管家 QA 封装：`/rag/ask`、QA sessions、feedback、会话改名；浮窗不再直接 `fetch`）
|
||
- 更新：`frontend/src/api/aiPmo.ts`（新增 `processText` 封装，供 AI 管家浮窗把“允许执行”显式交接到 AI PMO Kernel）
|
||
- 新增：`frontend/src/components/ai-steward/QAMarkdownContent.tsx`（AI 管家问答 markdown 渲染组件：统一列表/引用/代码块/长路径换行）
|
||
- 更新：`frontend/src/components/ai-steward/FloatingQAChat.tsx`（回答区改为 markdown 渲染；浮窗顾问动作升级为整组可交互 chips：`深入思考`、`给建议`、`先澄清`、`一起想`、`先劝退`、风险解释、`允许执行` 确认交接、`先别执行` 回填 `next_action`）
|
||
- 更新：`frontend/package.json`（新增 `react-markdown`、`remark-gfm`、`remark-breaks` 依赖，供 AI 管家问答渲染）
|
||
- 更新：`frontend/package.json`（新增真实飞书网页 E2E 脚本：`npm run e2e:feishu` / `npm run e2e:feishu:debug`）
|
||
- 新增：`frontend/playwright.config.ts`（Playwright 真实飞书网页自动化配置）
|
||
- 新增：`frontend/e2e/feishu-project-full-flow.spec.ts`（真实飞书网页 5 轮对话自动化：新需求 -> 三轮修改 -> 确认 -> 校验项目/信号源/宪章/任务/负责人）
|
||
- 更新：`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/scheduler-center/components/MountedAISourceStatusPanel.tsx`、`MountedAISourceActivationPanel.tsx`、`MountedAIToolGuardrailsPanel.tsx`、`MountedAITopicsPanel.tsx`、`MountedAIRunsPanel.tsx`、`MountedAIRunReplayPanel.tsx`、`MountedAIOrchestrationGraphPanel.tsx`、`MountedAIContextLayersPanel.tsx`、`MountedAISemanticPacketPanel.tsx`、`MountedAISemanticDecisionPanel.tsx`、`MountedAIShadowDiffPanel.tsx`、`MountedAITrainingOpsPanel.tsx`、`MountedAIEvalScoreboardPanel.tsx`、`MountedAIHardCasesPanel.tsx`、`MountedAIAcceptancePanel.tsx`（Mounted AI Console 来源状态、白名单 cutover、tool guardrails、topic workspace、run 列表、replay 详情、agent 编排图、context layers、semantic packet / decision / shadow diff、training ops、eval score board、hard cases 与验收门槛面板；其中 source activation / tool guardrails 已支持前台编辑，run replay 支持直接触发 `admin/replay-run`，training ops 已支持直接发起 mounted training wave，并展示 recent datasets / recent jobs / acceptance gate）
|
||
- 更新：`frontend/src/pages/scheduler-center/SchedulerCenterPage.tsx`（Scheduler Center 升级为 Mounted AI Console：接入 mounted runtime 查询与 admin actions，支持 source activation、tool policy、run replay、training wave 的前台操作，并支持通过 `mountedRunId` 查询参数直接定位 run；run detail 区新增 semantic packet / decision / gate / shadow diff 观测区）
|
||
- 新增：`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`，并扩展 `mounted_ai_run` 收件项来源）
|
||
- 更新：`frontend/src/components/inbox/InboxListItem.tsx`（Inbox 详情面板兼容 mounted runtime run 来源，展示 mounted source/message/reply 上下文）
|
||
- 更新：`frontend/src/pages/inbox/InboxPage.tsx`（Inbox 接入 Mounted Runtime runs，把澄清、负责人建议、执行中/完成等 run 视图并入收件箱）
|
||
- 更新：`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-v2` viewer 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_brief` cadence 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.tsx`
|
||
- `useSSTCWorkspaceOrchestration.ts`
|
||
- `sstcUtils.ts`
|
||
- `SSTCCharterStagePanel.tsx`
|
||
- `SSTCSignalStagePanel.tsx`
|
||
- `SSTCTaskStagePanel.tsx`
|
||
- `SSTCExecutionBoardPanel.tsx`
|
||
- `SSTCReleaseStagePanel.tsx`
|
||
- `SSTCReviewStagePanel.tsx`
|
||
- `SSTCReleaseCreateDialog.tsx`
|
||
- `SSTCReviewCreateDialog.tsx`
|
||
- `SSTCTaskCreateDialog.tsx`
|
||
|
||
## 6. 运行命令（高频）
|
||
### 根目录
|
||
```bash
|
||
./start.sh dev # 推荐：docker-dev 热更新模式
|
||
./stop.sh dev
|
||
./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`（后端契约变更时强制校验前端类型与架构文档同步）
|
||
|
||
### 前端
|
||
```bash
|
||
cd frontend
|
||
npm run dev
|
||
npm run build
|
||
npm run e2e:feishu
|
||
```
|
||
|
||
### 后端（本地直跑）
|
||
```bash
|
||
cd backend
|
||
pip install -r requirements.txt
|
||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
## 7. 团队维护建议（简版）
|
||
- 规则变更：只改 `AGENTS.md`
|
||
- 结构变更：同步改 `CLAUDE.md`
|
||
- API/契约变更：后端 `schemas` + 前端 `types` 同步更新
|
||
|
||
## 8. 服务边界约束（禁止越界）
|
||
- 数据库写操作必须通过 Alembic migration，禁止直接 `ALTER TABLE`
|
||
- 运行期禁止 DDL：`database.py` 钩子统一拦截 `CREATE/ALTER/DROP/...`，仅迁移路径允许执行
|
||
- 运行环境数据库仅允许 PostgreSQL（`postgresql+asyncpg`）；禁止回落 SQLite
|
||
- 新增接口必须遵循响应包络：`{code, message, data}`，不得裸返回
|
||
- `SignalSourceRegistry` 仅作为信号源接入/幂等内部表；用户可见的项目“信号源/信号”统一落到正式 `Signal`，SSTC 信号阶段只展示 `Signal`，禁止新增独立 registry 展示页面或第二套用户口径
|
||
- `create_project_from_natural_language` 支持透传 `requested_member_user_ids`；AI PMO 草稿确认时必须把推荐负责人并入项目创建事务，确保项目、主信号、信号源、成员关系一次性落库，禁止确认后再事后补成员
|
||
- AI Steward `project-from-text` 归一化阶段必须优先走人员能力图谱：先解析 `required_skill_tag_ids`，再调用 `recommend_personnel` 生成 `assignee_id/ai_recommended_assignees`，禁止绕过能力图谱直接拍脑袋分配
|
||
- 禁止在 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 仍失败时才显式报错，禁止用固定兜底文案冒充成功结果
|
||
- 禁止模型兜底回复文案：模型失败、超时、空响应、结构化解析失败时，必须返回真实错误原因；禁止输出“系统处理中/请稍后重试”等固定文案冒充成功结果
|
||
- 核心业务内容零兜底：宪章、信号分析、任务拆解、项目建议、范围边界、风险判断、资源计划、对齐结论等用户可见核心业务内容，禁止用默认文案、模板句子、占位字段或 stub 数据冒充真实生成结果；AI 失败、证据不足或结构化失败时，必须显式失败或标记为“待确认/证据不足/生成失败”
|
||
- 核心业务完成态不得仅按字段非空判定；必须能区分“真实生成 / 人工填写 / 模板占位 / 生成失败”，技术层 fallback 仅允许用于重试、缓存、解析修复、传输兼容等基础设施环节，禁止上浮成用户可见业务结论
|
||
- SSTC 宪章 AI 预填充必须输出并持久化 `field_status/field_evidence/readiness/derived_artifacts`；`ready_for_confirm=true` 的前提是必填字段文本存在、字段状态为 `valid` 且具备字段级证据，禁止仅凭字段非空、模板句子或 `module_confirmations` 进入完成态
|
||
- SSTC 宪章总确认（`alignment/confirm`）必须先校验 `readiness`；存在 `generation_failed/evidence_insufficient/generic_text/conflict_blocked` 任一 blocker 时禁止确认并保持任务阶段锁定
|
||
- SSTC 发布验证清单必须优先消费 `derived_artifacts.verification_metrics`，其次才允许读取宪章 KPI；禁止再回退 3 条通用默认验收项
|
||
- AdaptiveRAG `adaptive_rag_answer_normal` 空响应必须显式抛错并交由 high failover 处理；禁止在生成层直接回落为“补充问题细节后重试”之类的兜底回复
|
||
- AdaptiveRAG/OpenClaw 问答主链若遇到 `reasoning_content` 非空但 `content` 为空，必须先执行一次“请直接输出答案”定向重试；若 `finish_reason=length|max_tokens` 且仍为空，还必须至少执行一次扩容重试，禁止第一次空正文后直接失败
|
||
- 用户可见问答链路（`function_name` 含 `answer/reply/qa`）禁止使用 `reasoning_content` 回退，避免思考过程外漏
|
||
- `integrations(type='model_routing')` 的 runtime tier override 不得把 `adaptive_rag_answer_normal` / `adaptive_rag_answer_deep` 这类用户可见 QA 主函数降级到 `low`；这两个函数必须优先服从 OpenClaw 的 high reasoning 规则，防止网页/飞书问答被后台 override 锁死在低档
|
||
- AdaptiveRAG 场景化 Prompt 选择器必须在 `mixin_deep_guard_answer.py` 组装 Prompt 前执行，并遵循固定优先级：成员负载 > 趋势（项目关联 external_trend / 通用 industry_trend） > mixed > AI PMO 入口 > 默认 RAG
|
||
- 飞书中的“想聊需求 / 先别创建 / 先收敛第一版”类探索问题必须先由 `workflow_semantic_planner` 标记为 `message_intent=requirement_plan`，再统一落到 `PROMPT_AI_PMO_REQUIREMENT_PLAN_QA` 的需求收敛场景；该场景禁止落回“五大口径”评审或直接自动创建
|
||
- `requirement_plan` 现在必须是多轮状态机，而不是单轮问一句：`ExecuteQueryProjectMixin` 要把同线程/同群同人的需求收敛状态持久化到 `mounted_topic_workspaces + mounted_draft_workspaces`，每轮只推进 1 个关键问题，信息足够后直接整理成 Feishu 友好的需求草稿
|
||
- `requirement_plan` 不允许再把“同群同人”直接等同于“同一个需求 topic”：Mounted Runtime 必须用 `conversation_scope_key` 归并会话范围，再用显式 `topic_key` 区分具体需求；用户说“另一个需求 / 换个需求 / 不是这个需求 / 聊个新需求”时必须新开 topic，并把旧 topic 置为 `suspended`
|
||
- `requirement_plan` 的 topic resolver 不能只靠显式关键词：当同会话存在 active plan workspace，且新消息是新的需求起手式、与当前 topic card/draft 的重叠度明显偏低时，必须按 `candidate_new_topic` 优先切新 topic；尤其旧 topic 已处于 `awaiting_execute_confirm / plan_ready` 时，不得继续把“关于 openclaw 批量部署”这类低重叠消息续写到“A 股打分工具”草稿上
|
||
- `workflow_semantic_planner` 必须把“先按技术指标来 / 主要给投顾看 / 先做成飞书日报 / 每天收盘后更新”这类短槽位回答继续识别为 `message_intent=requirement_plan`，禁止第二轮开始掉回普通 query 或高阶 RAG
|
||
- `workflow_semantic_planner` 也必须把通用需求收敛里的短槽位回答继续识别为 `message_intent=requirement_plan`，例如“先给内部 PM 和研发负责人用 / 飞书总结就行 / 每次会后半小时内整理出来”；这类碎片化回复不得因为没有新 `semantic_bundle` 就退回普通 query
|
||
- `ExecuteQueryProjectMixin` 对 `message_intent=requirement_plan` 的查询必须优先走 mounted runtime 直答快路径：默认只输出自然短话术，每轮最多只保留 1 个关键问题；当 `scoring_basis/target_user/output_form/cadence/first_scope` 收集完成时，必须直接整理成需求草稿，禁止继续空转追问
|
||
- `requirement_plan` 的 Mounted Runtime 状态必须显式落库到 `MountedTopicWorkspace.plan_status`：至少区分 `idle / collecting / options_ready / plan_ready / awaiting_execute_confirm / suspended`，禁止只靠 `draft.state` 或 `metadata_json` 猜当前阶段
|
||
- 新的 OpenCow 风格语义上下文链必须先组装 `SemanticContextPacket`，再由模型返回 `SemanticDecision`，最后由 gatekeeper 决定 `plan_status`；当前 shadow 结果已进入 Mounted Runtime 观测，同时 intent/query-scene 主链已切到 direct metadata，不得再把 `semantic_bundle` 当作主链真源或绕过统一执行门禁
|
||
- 正在收敛中的 `requirement_plan` 必须支持普通人碎片化回复：像“技术指标吧 / 给投顾看 / 飞书日报就行 / 每天收盘后发”这种单字段短句，即使缺少新的 `semantic_bundle`，只要同线程/同群同人存在 active plan workspace，也必须自动续接当前需求收敛，不得回落到通用 query 或高阶 RAG
|
||
- `requirement_plan` 的追问节奏必须像自然聊天：上一轮只确认新增信息、下一轮只问一个缺口；初始描述中的“每日/自动”不能过早推断成已确认的更新频率，避免少问关键问题或提前出草稿
|
||
- `requirement_plan` 必须按 profile 区分场景：`scoring` 需求继续收集 `打分依据/目标用户/输出形式/更新频率/第一版范围`，`generic` 需求收集 `输入材料/目标用户/输出形式/响应时效/第一版范围`；像“会议纪要提待办”这类普通工具需求，禁止再复用“这个分数怎么打”的旧问题模板
|
||
- `generic requirement_plan` 的 `A/B/C` 选项只能出现在 active requirement session 的 `collecting` 轮次里，并且只允许绑定当前缺口字段（如 `target_user / output_form / cadence`）；普通闲聊、query.answer、非 requirement followup 必须继续保持自由文案，禁止全局套用选项模板
|
||
- 用户显式说“聊个新需求 / 另一个需求 / 跟上一个无关”时，AI PMO 必须先清掉当前会话里继承的旧 `current_project_id`，避免后续短回复继续被旧项目上下文污染
|
||
- 裸 `A/B/C/确认/你自行推荐` 这类低信息量回复，如果没有命中当前 active requirement session 或待确认草稿，必须直接提示“当前没有进行中的收敛轮次/草稿”，禁止再回落到 `query.answer` 检索图谱并生成旧项目结论
|
||
- 飞书私聊中的“答错了/不对/调用高级模型/用更强模型/重新回答”必须被识别为 `correction_escalation` 指令：优先复用上一轮上下文主题并强制深度回答，禁止把这类话术当成新的系统配置查询
|
||
- `POST /rag/ask` 在 `rag_request_context` 或统一语义规划层命中 `business_review/correction_escalation` 时，必须强制留在 `query.read_only` 主链并进入对应 QA Prompt；禁止因为 LLM 意图分类把“分析/MVP/重答”误送到 `signal.create -> draft_pending_confirm`
|
||
- Feishu 新消息即使被低阶 LLM 先判成 `project.create`，只要统一语义规划层从原句识别出 `requirement_plan/business_review/correction_escalation`，就必须在 ingress `_coerce_intent_for_query_scene` 阶段强制拉回 `query.answer`；Mounted Runtime 记录 `mode_after/agent` 时必须优先读取顶层 direct metadata，`semantic_bundle.diagnostics` 只允许作为兼容回退，禁止因顶层 `route_metadata` 缺字段把真实 `plan` 记成 `chat`
|
||
- 飞书入口的高精度同步判定不能只看 `primary_workflow`；只要 `WorkflowSemanticPlanner` 的 `diagnostics.message_intent=requirement_plan`，就必须优先返回 `semantic:requirement_plan` 并直接同步进入 AI PMO kernel，转发 `semantic_bundle`，禁止再先入异步队列发送 `已收到，正在处理` ACK
|
||
- “高级模型是否启用/模型路由是否启用/当前是否高配”这类运行态问题，只有命中运行态配置、路由快照、引擎配置或真实调用记录时才允许下结论；若证据只有页面目录、代码图谱或功能清单，回复必须明确为“无法仅凭静态资料确认”
|
||
- 通用行业趋势问答（如“宠物行业最新动态”）不得注入数据库、项目历史、用户历史或外部实时搜索结果；只有显式带项目上下文时才允许走 `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` 处理
|
||
- 飞书历史队列协议已停用：卡片动作与文本 followup 只允许走 `work_item_id + work_item.resume/draft_confirm` 主链；禁止新增或恢复 `queue_pending_confirm`、`queue_item_id`、`_maybe_handle_queue_followup` 这类旧 `feishu_items` 队列交互入口
|
||
- 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/日志直接暴露训练后真实底模名
|
||
- training deployment 的 `accepted` 决策默认受 acceptance gate 约束：若已存在 `teacher_eval_frozen_set` 且 frozen eval 未完成、低于 90，或严重 blocker 未清零，则禁止接受候选 deployment
|
||
|
||
## 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`、`POST /ai-steward/reply-iteration/backfill-mounted-assets`、`/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`、`POST /training/jobs/{id}/run`、`GET /training/jobs/{id}/evaluations`、`POST /training/artifacts/{id}/promote`、`POST /training/deployments/{id}/decision`、`POST /training/mounted-wave`；mounted wave 会自动生成 `teacher_dev_set / teacher_eval_frozen_set / sft / preference` 并启动并执行 low/high 训练波次）
|
||
- Mounted Runtime 控制台接口：参考 `backend/app/api/ai_steward_api/routes_mounted_ai.py`（`GET /ai-steward/mounted-ai/sources|source-activations|tool-policies|topics|runs|runs/{id}|cutover-status|eval-suites|eval-suites/{id}|training-ops|hard-cases`，以及 `POST /ai-steward/mounted-ai/admin/source-activation|tool-policy|replay-run`，统一 `{code,message,data}` 包络）；其中 `runs/{id}` 必须返回 `topic/draft/semantic_packet_summary/semantic_decision/semantic_gate_result/semantic_diff`，`cutover-status` 必须返回模块级旧脑退役视图：`legacy_cutover_state / retired_item_count / active_item_count / legacy_cutover_items[]`
|
||
- 任务包中心接口：参考 `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`、`POST /ai-steward/knowledge-graph/sync/work-items`；旧 `POST /ai-steward/knowledge-graph/sync/feishu` 仅保留兼容别名）
|
||
- 需求点落信号源：参考 `backend/app/services/signal/signal_source_orchestration/mixin_registry_execute.py`（`materialize_requirement_sources` 负责归一、去重、`raw_context` 持久化，并为每条 registry 同步绑定/物化正式 `Signal`）
|
||
- 审计查询接口：参考 `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/consultant_mode_preference`，由 `ingress_options.rag_request_context` 下传到 query executor 并映射到 `AdaptiveRAGService.answer_question`，返回侧从 ingress `rag_result`/`direct_reply_text` 组装兼容响应
|
||
- RAG 空回答保护：`POST /rag/ask` 若 `answer` 与 `reply_text` 同时为空，必须返回失败包络，禁止再用“当前暂无可用回答。”之类兜底文案冒充成功结果
|
||
- RAG Grounding Runtime 合同补充：`POST /rag/ask` 的成功返回统一透传 `answer_mode/grounding_status/policy_version/citations/sources_used/evidence_pack/tool_trace/retrieval_metrics`；`AdaptiveRAG` 内部允许通过兼容层把异构 `sources` 映射成稳定 citation 结构，但业务语义判断仍只允许放在 `workflow_semantic_planner`
|
||
- 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` 统一生成，当前仅供 RAG / AI Steward 顾问式问答透传，已不再驱动 Feishu mention 回复或 AI PMO ingress capture 主链
|
||
- RAG 顾问模式偏好约束：`consultant_mode_preference` 只允许取 `clarify/advise/challenge/brainstorm/execute`，且仅影响回答风格与 prompt wrapper；它不能替代 `workflow_semantic_planner` 去决定 `query vs execute`
|
||
- 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}/ai-prefill`）固定写回 `modules/field_status/field_evidence/readiness/derived_artifacts`，AI 失败或字段缺证据时不得再补模板文案
|
||
- 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}/releases/{release_node_id}/verification/generate`）只允许从 `derived_artifacts.verification_metrics` 或宪章 KPI 生成校验项；两者都为空时返回 `409`
|
||
- 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` 可用
|
||
- 真实飞书网页 E2E 依赖本机已登录的 Chrome/Feishu 会话；默认读取 `FEISHU_USER_DATA_DIR=~/Library/Application Support/Google/Chrome` + `FEISHU_PROFILE_DIRECTORY=Default`，若本机 Chrome 正在占用该 profile，请改用独立 profile 或先关闭 Chrome
|
||
- 真实飞书网页 E2E 只负责浏览器发消息与页面诊断，结果校验统一走数据库探针；validation runner 现会优先从 `frontend/playwright-report/feishu-web/index.html` 恢复上次成功运行的 `FEISHU_CHAT_URL/FEISHU_CHAT_NAME/userDataDir`，其次回退到 acceptance profile
|
||
- 显式命名的新项目请求（例如“这个需求先叫 FeishuWebFlow-*”）不得仅因正文出现历史项目标题就自动绑定已有 `project_id`；若确需复用已有项目，必须由显式 `project_id` / 项目指代或后续确认链路决定
|
||
- 项目创建返回的 `signal_sources` 仅作为 AI Steward 创建结果区的内联展示；项目看板与 SSTC 信号阶段统一只读正式 `Signal`，`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 环境默认使用 `certifi` CA 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` 链路一律禁用该回退
|
||
- OpenClaw 高阶问答链默认可能把客户端超时抬到 `OPENCLAW_AGENTS_DEFAULT_TIMEOUT_SECONDS + 5s`；飞书真实追问若命中 high reasoning，排查“长时间无回复”时必须同时看 `空content定向重试`、`空content扩容重试` 和最终 `capture_done/outbox_written`
|
||
- World Model 静态层已接入 Redis 缓存（key: `wm:static:{tenant_id}:{project_id}`，TTL 600s）
|
||
- 写操作后主动 invalidate，动态层不缓存
|
||
- AI PMO 意图识别已切换 `model-only`：`_resolve_intent` 仅接受 LLM 结构化结果，不再走规则/正则兜底链路
|
||
- `semantic_context` 新链当前状态：ingress shadow 观测已落库，intent/query-scene/render 主链已切到 direct metadata，旧 `semantic_bundle/workflow_semantic_planner` 仍仅在部分 requirement-plan executor / followup 兼容路径中生效；后续删旧规则时应继续以 Mounted Runtime 观测页核对 shadow diff
|
||
- IT 五轮 requirement plan 现以 `MountedDraftWorkspace.active_work_item_id + latest_*_message_id` 锚定当前 active draft；历史未绑定这些字段的旧草稿不会自动认领，需先重新生成当前草稿后再确认/修改
|
||
- 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` 覆盖；配置缺失时按 OpenClaw `low/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`（优先按 `source/source_identifier`，再按标题/摘要近似匹配）；仅无法复用时才直接物化新的正式 `Signal`，不再触发 `capture-feishu` 补录
|
||
- 兼容 SQL 查询入口：`ai_pmo_work_items` 为视图别名（底层映射 `work_items`），避免历史脚本直接查旧表名失败
|
||
- `signal_source.onboard` 已加入工作流门禁旁路：进入执行阶段后按闭环结果返回 `succeeded/pending_manual/failed_safe`，不再被前置仿真门禁直接拦截为 `waiting_manual`
|
||
- 飞书入站已拆分“短确认同步快路径 + 非短确认异步队列”：短确认命中会话窗口时直接继承上轮意图并同步执行；其余消息先回“已收到，正在处理”后由 `ai_orchestration_runs` 异步 worker 执行与重试
|
||
- 飞书会话与问答上下文键已改为“显式线程锚点优先 + 私聊稳定 actor scope”：存在 `reply_to_message_id/root_message_id/thread_id` 时继续按线程锚点建 key；无显式锚点时私聊/外部连续问答默认复用 `chat_id + sender_open_id`，不得再使用 `source_message_id` 把每条消息切成新会话。草稿确认仍需回查 `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 的短元追问（如“这是什么情况”“详细说下”“怎么回事”）若命中显式 `reply_to_message_id`，或同会话/同 scope 在 5 分钟内仅存在 1 条最近 PMFlow 回复候选，必须直接走 `meta_followup` 快路径解释上一条回复；若上一条本身是 `LLM empty content / 系统处理失败 / 未执行` 回执，必须优先用自然语言解释失败原因，禁止再漂移回高阶项目检索链
|
||
- 外部 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”
|
||
- `qa_records` 现阶段还必须持久化 Grounding Runtime 字段：`answer_mode/grounding_status/policy_version/citations/sources_used/evidence_pack/tool_trace/retrieval_metrics`；旧 `sources/domains_used/routing_snapshot` 继续保留兼容，禁止只改接口不落库
|
||
- 元追问（如“哪个模型回复的”“为什么那条报错”“你刚才那句什么意思”）必须优先锚定最近一条 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` 命中挂起草稿时，才进入草稿确认处理器
|
||
- 项目存在性查询（如“这个项目有吗/有没有这个系统”）必须优先走项目事实库直答；禁止把这类内部事实已可回答的问题继续送入高档 RAG，再因空内容/重试失败把真实查询打成失败
|
||
- `signal_source.onboard` 显式接入请求必须在 intent resolve 阶段先于 LLM 锁定到写操作草稿链；“先不要执行，先出草稿”类接入话术默认进入 `draft_pending_confirm`，禁止再漂移成 discovery/query followup
|
||
- 飞书 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/consultant_mode_preference`
|
||
- AdaptiveRAG `answer_question` 入口已拆为“双阶段”：`_prepare_answer_runtime`（会话/上下文/动作模式解析）+ `_execute_base_answer_mainline`（基础问答主路径）；写确认 `ack` gate 仅在 `sync_requirement=true && action_mode in write/read_write && 非 feishu` 时触发
|
||
- 高准确通道不再按 `asked_via` 一刀切强制 deep：`count/list/status/existence` 由 `AdaptiveRAG` retrieval planner 优先回落到 `fast_path`，`snapshot-only + weak evidence` 则要求进入 `clarify` 或 `blocked`；该 planner 只负责 retrieval/runtime 决策，禁止接管 `query vs execute / project.create / signal_source.onboard / followup.*`
|
||
- AI 管家浮窗顾问按钮边界：`深入思考` 与整组 `给建议/先澄清/一起想/先劝退` chips 都属于 `/rag/ask` 内部重答；`允许执行` 必须先确认，再显式交接到 `/ai-pmo/process-text`，禁止把执行动作继续伪装成 RAG 重答；`先别执行` 只允许回填 `next_action` 到输入框，不得偷偷触发写操作
|
||
- 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. 技术债务清单
|
||
- [x] `mixin_auto.py` `_safe_int` NameError：已通过显式导入 `_safe_int` + 回归测试锁定，避免后续共享导出调整导致运行时未定义
|
||
- [x] 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` 锁定
|
||
- [x] 飞书入口层耦合已收敛：飞书真实入口已拆为三段职责链（预处理 `mixin_receive_prepare.py` / capture 执行 `mixin_receive_capture_flow.py` / 编排 `mixin_receive.py`）；`mixin_receive.py` 不再混合传输解析、附件标准化、capture 异常兜底与收尾回执逻辑，分层边界通过 `test_feishu_receive_orchestration_contract.py` 锁定
|
||
- [x] `task.create` 已升级为一等 typed intent：`IntentResolver/RouteResolver` 新增 `task.create` 常量与 `task.create` 路由族；TypedExecutor 已接入任务落库执行（含 `project_id`/任务标题槽位守卫、对齐 Charter 校验、`persist_task` 写入）；`WorkflowRegistry`、`ReplyRenderer`、`followup` 校验与草稿确认闭环已纳入 `task.create`；并补 `test_ai_pmo_task_intent_contract.py` 回归锁定
|
||
- [x] `task.create` 已接入消息级幂等账本：Feishu `source_message_id/feishu_message_id` 作为 `task.create` 账本 key，重复确认只回放同一结果，不再重复落库；回归由 `test_feishu_pipeline_queue_contract.py` 锁定
|
||
- [x] `signal_source.onboard` 已接入消息级幂等账本：TypedExecutor 以 `source_system + source_message_id` 作为 onboarding ledger key，重复提交只回放同一结果，不再重复跑信号源接入编排；回归由 `test_ai_pmo_signal_source_onboard_contract.py` 锁定
|
||
- [x] AdaptiveRAG 职责已完成首轮收敛：`answer_question` 入口已分层为 `prepare runtime` 与 `base mainline` 两段，写确认逻辑通过 `_should_trigger_write_ack_gate` 独立门控；基础问答主路径不再与写确认判断混写在同一函数体。分层契约由 `test_adaptive_rag_mainline_contract.py` 锁定（read 绕过 ack、write 命中 ack、feishu write 维持主链）
|
||
- [x] 执行层已形成统一执行账本与参数来源约束：ingress 执行路径统一通过 `KernelIngressStorageMixin` 生成 `execution_result.action_contract`（固定 `param_source=decision.execution_plan.actions+workflow_route+execution_result`）并写入 `operation_execution_ledger`（`applied/pending_manual/pending_confirmation/failed`）；`mixin_auto.py`、`mixin_prepare_manual.py` 的 `operation_code` 日志来源已对齐 `action_contract`，回归由 `test_ai_pmo_execution_ledger_contract.py` 锁定
|
||
- [x] QA/RAG 路由契约双轨已收敛：`/ai-steward/rag/ask` 兼容入口已移除，问答统一收敛到 `POST /rag/ask`；参数构造与 tenant 解析收口在 `backend/app/api/rag_ask_contract.py`，前端 `FloatingQAChat` 与 Context Cache API 目录均已对齐，`backend/tests/test_rag_route_contract.py` 与 `backend/tests/test_context_cache_profile_catalog.py` 已锁定回归
|
||
- [x] AI 管家浮窗交互已与 Grounding Runtime 对齐：回答区已切到 markdown 渲染，顾问标签升级为显式交互按钮；`consultant_mode_preference` 只用于 `/rag/ask` 内部重答，`允许执行` 明确交接到 `/ai-pmo/process-text`，避免 query/execute 边界回退到旧的一锅煮
|
||
- [x] Retrieval source registry / metadata 已统一：AdaptiveRAG 检索链已建立统一 source registry / metadata normalizer，`citations[]/sources_used[]` 直接消费标准字段 `source_type/source_id/chunk_id/target_url/project_id/updated_at/permission_scope/source_priority`；`doc/url/feishu/pmflow/graph/db` 的来源元数据与排序键已收口，并由 `test_rag_route_contract.py`、`test_adaptive_rag_mainline_contract.py` 锁定
|
||
- [x] 语义治理 baseline 已清零：散落在 `feishu_signal_pipeline`、`signal_capture_service`、`ai_pmo_api` 的 `*_HINTS/*_RE` 规则常量已迁回 `workflow_semantic_planner`，`scripts/semantic_lint_baseline.txt` 已清空，并由 `scripts/semantic_lint.py` 与 `backend/tests/test_semantic_lint.py` 做仓库级守门
|
||
- [ ] 历史 Feishu 队列 / `feishu_items` 兼容链仍未完全退场：飞书真实入口、卡片动作、文本 queue followup，以及 `project_knowledge_graph` 的主增量/API 命名都已切到 `work_item` 主链；当前剩余债务主要是 `feishu_items` 存量读链路、历史 pending 事件兼容消费，以及 legacy `feishu_delta` 证据/回放兼容壳。后续需在历史存量清空后正式封存该兼容层
|
||
- [x] AdaptiveRAG 向量检索 legacy fallback 已移除：`AdaptiveRAGRetrievalVectorMixin._retrieve_vector_context()` 现在只支持 PostgreSQL/pgvector 主路径；非 PostgreSQL 或 PG 查询失败时直接返回空结果，不再回退 Python 侧 legacy 扫描，边界由 `test_adaptive_rag_mainline_contract.py` 锁定
|
||
- [x] 历史 Alembic 链幂等性缺陷已修复：`add_users_table_rbac.py` 的 PostgreSQL ENUM 创建已改为显式创建 + 列类型 `create_type=False` 复用，`userrole/userstatus` 不再在同一条 migration 内重复建型；回归由 `test_add_users_table_rbac_migration.py` 锁定
|
||
- [ ] 食谱图片上传仍是示例桩实现：`backend/app/services/recipe/service.py` 仍以模拟 URL 代替对象存储，`POST /recipes/upload-image` 也还停留在示例接口形态；若该模块继续保留，需要补齐真实对象存储接入、租户隔离与统一 `{code,message,data}` 响应包络，否则应明确标注为非核心示例模块
|
||
- [x] LLM 运行时仍未完全收敛：`ai_service_core._invoke_with_retry` 与 `stream_chat` 已统一走 `llm_service`；旧 `_get_llm` 路径已显式禁用，并补回归测试锁定
|
||
- [x] QA 主链自动化测试覆盖已补齐：`backend/tests/` 已覆盖问答/RAG 主路径与关键场景；新增 `test_ai_pmo_qa_http_mainline_e2e.py` 通过 HTTP 层锁定 `/rag/ask` 的 `qa_readonly/mixed` 契约以及 `/ai-pmo/process-text` 的 `draft_pending_confirm` 主链返回，配合 `test_ai_pmo_ingress_mainline.py`、`test_ai_pmo_task_intent_contract.py`、`test_ai_pmo_tactical_brain_contract.py` 形成稳定回归基线
|
||
- [x] 飞书交互闭环已补齐：执行场景回执在 `draft_pending_confirm/pending_manual` 下优先生成按钮卡片并经 outbox 异步发送；`card.action.trigger` 已覆盖 `confirm/revise/cancel/continue` 回调分发，分别复用 `DraftConfirmHandler.handle_api_decision` 与 AI PMO `process_ingress` 主链继续执行；回调 HTTP 现在会同步返回 toast 反馈，确保点击按钮后至少有可见结果；`backend/tests/test_feishu_card_action_contract.py` 已补卡片构造与 `continue` 回归契约
|