442 lines
44 KiB
Markdown
442 lines
44 KiB
Markdown
# 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. 顶层目录（精简版）
|
||
```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/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/probe/warmup）
|
||
│ ├── deps.py # 共享依赖导出（get_db/AsyncSessionLocal）
|
||
│ ├── dependencies/ # 鉴权/租户等依赖注入
|
||
│ ├── middleware/ # 请求中间件（审计上下文注入等）
|
||
│ ├── models/ # SQLAlchemy 模型
|
||
│ ├── schemas/ # Pydantic 模型
|
||
│ ├── services/ # 业务服务（AI/SSTC/集成）
|
||
│ ├── config/ # 配置与 prompt
|
||
│ └── utils/ # 工具函数
|
||
├── alembic/ # 数据库迁移
|
||
│ └── versions/
|
||
│ ├── 20260310_add_feishu_outbox_reply_hash.py # 飞书 outbox 回执哈希幂等字段
|
||
│ ├── 20260311_add_pg_trgm_text_indexes.py # pg_trgm 扩展与文本检索索引
|
||
│ ├── 20260311_add_kb_chunk_ivfflat_index.py # knowledge_base_chunks 向量 IVFFlat 索引
|
||
│ ├── 20260311_add_operation_log_audit_fields.py # operation_logs 审计字段扩展(trace/path/caller)
|
||
│ ├── 20260311_add_ai_pmo_work_items_view.py # ai_pmo_work_items 兼容视图（映射 work_items）
|
||
│ ├── 20260311_expand_user_workload_ratio_precision.py # user_workloads.workload_ratio 精度扩容(10,2)
|
||
│ └── 20260311_add_conversation_sessions_table.py # 飞书多轮会话上下文持久化表
|
||
├── scripts/ # 后端运维/数据修复脚本
|
||
│ ├── backfill_orphan_signal_links.py # 回填孤立 signal 的 project_signal_links
|
||
│ ├── dev/ # 开发辅助脚本（check_users/seed_all）
|
||
│ └── legacy/ # 历史脚本（仅保留兼容参考，不作为主流程）
|
||
├── requirements.txt # Python 依赖
|
||
├── Dockerfile
|
||
└── (tests 已移除)
|
||
```
|
||
- 新增：`backend/app/api/llm_providers.py`（AI 管家 LLM provider preset 配置读取接口）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_agent_kernel.py`（双 Agent 共享决策内核：复杂度路由/执行门控/修正识别）
|
||
- 新增：`backend/app/utils/timezone.py`（统一北京时间工具：`now_cn_aware/now_cn_naive`）
|
||
- 新增：`backend/app/utils/audited_write.py`（写接口审计上下文、caller 归一、北京时间格式化）
|
||
- 新增：`backend/app/middleware/audit_context.py`（请求级 trace/interface/caller 注入）
|
||
- 新增：`backend/app/api/audit.py`（审计查询接口：`GET /audit/operations`）
|
||
- 新增：`backend/app/services/audit_query_service/service.py`（operation_logs 过滤与序列化）
|
||
- 新增：`backend/app/services/signal_source_repair_service.py`（脏信号源回填服务）
|
||
- 新增：`backend/alembic/versions/20260311_shift_all_timestamps_to_beijing.py`（全库历史时间 +8h，数据库默认时区切到 Asia/Shanghai）
|
||
- 新增：`backend/alembic/versions/20260312_add_signal_planner_fields.py`（signals 增加 planner 状态字段与索引）
|
||
- 新增：`backend/app/services/signal_planner/signal_strategic_analysis_service.py`（Signal Planner 写回收口）
|
||
- 新增：`backend/app/services/feishu_outbox/service.py`（复用 reply_hash 的 outbox 入队收口）
|
||
- 新增：`backend/app/services/signal_planner_service.py`（Signal Planner 异步分析服务）
|
||
- 新增：`backend/app/services/model_routing/service.py`（函数级模型路由配置服务）
|
||
- 新增：`backend/app/services/task_brief_service.py`（增量任务包中心服务）
|
||
- 新增：`backend/app/services/model_context_bundle_service.py`（双模型上下文组包/能力汇总/消费验证服务）
|
||
- 新增：`backend/app/api/model_routing.py`（模型路由配置接口）
|
||
- 新增：`backend/app/api/task_briefs.py`（任务包中心接口）
|
||
- 更新：`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_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_kernel/ai_pmo_reply_renderer.py`（AI PMO 回执渲染出口 `ReplyRenderer`）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_typed_executor.py`（AI PMO typed 执行层组合入口）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_typed_executor_common.py`（TypedExecutor 共享常量/依赖）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_typed_executor_mixins_parse.py`（TypedExecutor 解析与批量分析逻辑）
|
||
- 新增：`backend/app/services/ai_pmo_typed_executor_mixins_discovery.py`（TypedExecutor discover 候选上下文逻辑）
|
||
- 新增：`backend/app/services/ai_pmo_typed_executor_mixins_execute.py`（TypedExecutor execute/create/source-onboard 落库逻辑）
|
||
- 新增：`backend/app/services/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_kernel/ai_pmo_kernel_mixins_ingress.py`（Kernel ingress 组合入口）
|
||
- 新增：`backend/app/services/ai_pmo_kernel_mixins_ingress_flow.py`（Kernel 入站主流程编排）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_kernel_mixins_ingress_storage.py`（Kernel 入站事件/工作项写入）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_kernel_mixins_ingress_render.py`（Kernel 入站结果组装与输出辅助）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_kernel_mixins_world_model.py`（Kernel world-model 组合入口）
|
||
- 新增：`backend/app/services/ai_pmo_kernel_mixins_world_model_core.py`（Kernel world-model 核心构建与缓存）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_kernel_mixins_world_model_session.py`（Kernel 会话继承与会话态维护）
|
||
- 新增：`backend/app/services/ai_pmo_kernel_mixins_world_model_aggregates.py`（Kernel 组合摘要构建器）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_kernel_mixins_intent.py`（Kernel intent 组合入口）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_kernel_mixins_intent_rules.py`（Kernel 规则意图与槽位守卫）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_kernel_mixins_intent_llm.py`（Kernel LLM 意图识别与仲裁）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_kernel_mixins_intent_resolve.py`（Kernel 最终意图解析入口）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_kernel_mixins_followup.py`（Kernel followup 组合入口）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_kernel_mixins_followup_records.py`（followup 决策/计划/回执写入）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_kernel_mixins_followup_routing.py`（followup 候选定位与恢复分发）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_kernel_mixins_followup_project_signal.py`（project_signal followup 组合入口）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_kernel_mixins_followup_project_signal_actions.py`（project_signal commit/refresh/cancel 动作执行）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_kernel_mixins_followup_project_signal_resume.py`（project_signal 目标工作项恢复闭环）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_kernel_mixins_followup_verification.py`（followup 执行校验与工具函数）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_kernel_mixins_closure.py`（Kernel closure 组合入口）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_kernel_mixins_closure_helpers.py`（Kernel 闭环通用归一化工具）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_kernel_mixins_closure_data.py`（Kernel 闭环历史上下文回放）
|
||
- 新增：`backend/app/services/ai_pmo_kernel/ai_pmo_kernel_mixins_closure_payload.py`（Kernel 闭环语义与来源上下文组装）
|
||
- 移除：`backend/app/services/ai_pmo_kernel_service.py`（顶层兼容壳清理，统一改为 `backend/app/services/ai_pmo_kernel/` 子包）
|
||
- 新增：`backend/app/services/feishu_signal_pipeline/`（飞书信号管道按职责拆分的服务包，所有子文件 <= 300 行）
|
||
- 新增：`backend/app/services/feishu_signal_pipeline/service.py`（组合入口，按 mixin 聚合能力）
|
||
- 新增：`backend/app/services/feishu_signal_pipeline/shared_core.py`、`shared_schema_utils.py`（共享常量/正则/Schema/工具函数拆分）
|
||
- 新增：`backend/app/services/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/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/llm_service/`（LLM 服务按职责拆分的 mixin 包，所有子文件 <= 300 行）
|
||
- 更新：`backend/app/services/llm.py`（降级为兼容入口，导出 `LLMService` 与 `llm_service`）
|
||
- 新增：`backend/app/services/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 管理）
|
||
- 更新：`backend/app/config/ai_prompts.py`（兼容聚合入口，保留 `build_default_role_prompt_bundle`）
|
||
- 新增：`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/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_kernel_world_model_aggregates/`、`backend/app/services/ai_pmo_kernel_world_model_core/`、`backend/app/services/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_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_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_kernel/`（AI PMO 执行与回执运行时收敛到 kernel 子包）
|
||
- 更新：`backend/app/services/cost_optimization_service.py`、`backend/app/services/model_lifecycle_service.py` → `backend/app/services/model_capability/`（模型能力相关服务收敛）
|
||
- 更新：`backend/app/services/signal_strategic_analysis_service.py` → `backend/app/services/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_capture_service/impact_analyzer.py`、`backend/app/services/signal_capture_service/external_fetcher.py`（信号接入分析/抓取能力归并）
|
||
- 更新：`backend/app/services/plane.py` → `backend/app/services/integration_core/plane_service.py`（Plane 兼容服务归并到 integration_core）
|
||
- 更新：`backend/app/services/lark.py` → `backend/app/services/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_routing/service.py`（模型路由服务子包化）
|
||
- 更新：`backend/app/services/prompt_profile_service.py` → `backend/app/services/prompt_profile/service.py`（Prompt 画像服务子包化）
|
||
- 更新：`backend/app/services/feishu_outbox_service.py` → `backend/app/services/feishu_outbox/service.py`（飞书 outbox 服务子包化）
|
||
- 更新：`backend/app/services/wecom_integration.py` → `backend/app/services/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/
|
||
├── 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 能力汇总与双模型消费验证 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/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/sections/OverviewTab.tsx`、`CreateProjectTab.tsx`、`SignalsTab.tsx`、`ConflictsTab.tsx`、`BlockersTab.tsx`、`BriefingTab.tsx`、`EngineTab.tsx`（AI Steward 分阶段 UI 拆分）
|
||
- 新增：`frontend/src/pages/ai-steward/AIStewardPage.tsx`（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/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 可视化信息面板
|
||
- `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
|
||
```
|
||
|
||
### 后端（本地直跑）
|
||
```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}`，不得裸返回
|
||
- 禁止在 API 层写业务逻辑，业务逻辑归属 `services/`
|
||
- 禁止在前端组件内直接调用 `fetch`，必须通过 `frontend/src/api/` 封装层
|
||
- 前端状态管理：服务端数据用 React Query，本地 UI 状态用 `useState`
|
||
- 飞书回执发送仅允许 `main.py` 的 drain_loop 作为消费者，禁止在业务路径即时派发 outbox 发送任务
|
||
- 所有写接口必须落审计日志（`operation_logs`）：至少包含 `trace_id/interface_path/caller`
|
||
- `created_at_beijing` 为计算属性返回，禁止新增数据库物理列
|
||
- low/high 双模型（`classify_intent_ai_pmo_kernel`、`classify_intent_complex`）与 `openclaw_command_dispatch` 必须遵循 DDL 接口化约束：禁止直连 SQL DDL，命中时强制输出 `ddl_api_required`
|
||
- 双模型上下文注入仅允许通过 `ModelContextBundleService` 统一组包：固定三段 `knowledge_graph/task_template/contract_sync`，禁止在业务服务散落拼接 prompt 上下文
|
||
- AI PMO `signal.create` 在用户显式要求“先分析再入库 / 自行分析”时，若批量信号结构化分析失败，禁止回退规则标题直接入库，必须返回失败安全态
|
||
- 所有 LLM 调用禁止模型级兜底：禁止高阶升级、Safety 引擎、应急直连、stub 假成功；模型异常、超时或结构化输出不合法时必须显式报错
|
||
- 本地 `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` 视为下线路径
|
||
|
||
## 9. 新增代码的参考模式
|
||
- 新增后端接口：参考 `backend/app/api/sstc.py` 的结构
|
||
- 模型路由配置接口：参考 `backend/app/api/model_routing.py`（`GET/PUT /model-routing/functions/{function_name}`，仅管理员可写并写入 `operation_logs`）
|
||
- 任务包中心接口：参考 `backend/app/api/task_briefs.py`（`/task-briefs/center/templates/runs/generate/contract-sync`）
|
||
- KG 上下文闭环接口：参考 `backend/app/api/knowledge_graph.py`（`GET /ai-steward/knowledge-graph/capability-summary`、`POST /ai-steward/knowledge-graph/verify-context-consumption`）
|
||
- 审计查询接口：参考 `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`）
|
||
- 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 消息台列表接口（`GET /ai-pmo/work-items`）：返回 `latest_policy_gate_code` 与规范化 `approval_requirement{required,reason,message}`（来源于最新 `decision_records` 投影）
|
||
- AI PMO 消息台列表接口补充：返回源消息上下文字段 `source_message_text/source_captured_at/source_sender/source_channel_ref`，用于详情页展示“原始输入”与事件时间
|
||
- AI PMO 消息台列表接口补充：返回闭环语义字段 `source_conversation_closure/closure_summary/implementation_modules/source_closure_turns`，用于详情页展示“消息闭环 + 实现模块”
|
||
- AI PMO 消息台历史回填补充：当 `ingest_events.payload` 闭环字段缺失或低质量时，优先回放 `ai_processing_logs`（同 `feishu_message_id`）并补充 `qa_records` 最近问答，避免 Redis 会话过期后仅剩单句摘要
|
||
- AI PMO 消息台列表接口补充：过滤短口水话 `query.read_only` 项（如“怎么样了/在吗”），保留后端记录但不下发前端收件流
|
||
- AI PMO `signal_source.onboard` 入库规则：优先使用闭环摘要写入 `signals.summary`，闭环对话写入 `signals.content`，并在 `signals.strategic_analysis.source_context.implementation_modules` 持久化实现模块
|
||
- SSTC 信号列表接口（`GET /projects/{project_id}/signals`）标题生成规则：优先 `signals.title`，其次 `signals.summary`，最后回退 `signals.content` 去前缀文本
|
||
- 信号源编排补充：`SignalSourceOrchestrationService` 已停止运行时调用旧 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` 可用
|
||
- 当前 LLM 主链默认直连引擎，不再依赖 OpenClaw 网关；请求超时统一以 `LLM_REQUEST_TIMEOUT` 环境变量为准
|
||
- LLM 非结构化响应在 `content` 为空且存在 `reasoning_content` 时，可按需回退读取 `reasoning_content`（开关：`LLM_REASONING_CONTENT_FALLBACK`，默认关闭）
|
||
- World Model 静态层已接入 Redis 缓存（key: `wm:static:{tenant_id}:{project_id}`，TTL 600s）
|
||
- 写操作后主动 invalidate，动态层不缓存
|
||
- AI PMO 意图识别默认 `rule-first`：`AI_PMO_INTENT_LLM_ENABLED=true` 时，LLM 仅在规则低置信或 `default_query_fallback` 场景作为末位兜底；模型超时/不可用/结构化解析失败时回退规则链路，不中断主流程
|
||
- 环境变量以根目录 `.env` / `.env.example` 为唯一配置源；`backend/.env` 已移除且不再读取
|
||
- Signal Planner 函数路由支持 `integrations(type='model_routing')` 覆盖配置；配置缺失时默认直连 GLM
|
||
- Signal Planner 结构化调用采用 `25s` 硬超时：超时或结构化不合法时标记失败并通知人工重试，不再写入降级 `ai_planner(fallback_mode=true)`
|
||
- AI Steward 用户侧已移除 OpenClaw 指挥规划入口；后续项目分析主链以 GLM 严格失败直出为准
|
||
- 飞书业务命令命中旧 command-first 路由时，仅返回“已下线”阻断提示，不再触发实际执行
|
||
- 模型命名统一使用裸模型名（如 `GLM-4.7`、`MiniMax-M2.5`），不使用供应商前缀模型名
|
||
- 双 Agent 路由治理：默认直连 `GLM`，复杂意图仍使用 `classify_intent_complex`，不再经过 OpenClaw 控制平面
|
||
- 双模型 DDL 治理图谱的模型来源优先读取显式模型配置；缺失时回退 `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/让我直接处理/模型失败了所以没分析”等漂移语句时，自动回退固定模板，禁止对外宣称未证实执行动作
|
||
- `project.create` 启用槽位完整性闸门：无法从指令提取有效项目名时标记 `slot_incomplete` 并进入人工确认
|
||
- 数据库与核心写入链路统一使用北京时间（`Asia/Shanghai`）：PostgreSQL 会话时区、数据库默认时区与核心 `_utc_now*` 写入入口均已切换到北京时间
|
||
- 后端与脚本层已清零 `datetime.utcnow()/timezone.utc`：统一使用 `backend/app/utils/timezone.py`（`now_cn_aware/now_cn_naive/CN_TZ`）管理时间语义
|
||
- `operation_logs.created_at_beijing` 为应用层计算字段（非 DB 列），审计查询接口返回时统一补齐
|
||
- 历史脏信号源修复优先复用同项目已存在 `signal_id`，仅无法复用时才触发 `capture-feishu` 补录
|
||
- 兼容 SQL 查询入口：`ai_pmo_work_items` 为视图别名（底层映射 `work_items`），避免历史脚本直接查旧表名失败
|
||
- `signal_source.onboard` 已加入工作流门禁旁路：进入执行阶段后按闭环结果返回 `succeeded/pending_manual/failed_safe`，不再被前置仿真门禁直接拦截为 `waiting_manual`
|