@michaelxwb/code-flow 0.5.1

package/src/core/code-flow/scripts/cf_user_prompt_hook.py

@@ -0,0 +1,402 @@
+#!/usr/bin/env python3
+"""Unified UserPromptSubmit Hook: inject matching specs into context.
+
+This hook works for both Claude Code and Codex adapters. It extracts:
+1. File paths from the prompt (for context_tags)
+2. Keywords from the prompt (for prompt_tags via extract_prompt_tags)
+
+Both tag sets are used to match specs for injection.
+
+Input (stdin): {"prompt": "...", "session_id": "..."}
+Output (stdout): {"hookSpecificOutput": {"hookEventName": "UserPromptSubmit", "additionalContext": "..."}}
+or empty on no-op
+"""
+import json
+import os
+import re
+import sys
+import cf_log
+from cf_core import (
+    _log,
+    assemble_context,
+    build_effective_mapping,
+    build_spec_catalog,
+    resolve_quality_loop,
+    debug_log,
+    ensure_utf8_io,
+    estimate_tokens,
+    extract_context_tags,
+    extract_prompt_tags,
+    fallback_domains_for_context,
+    load_config,
+    load_inject_state,
+    match_domains,
+    match_specs_by_tags,
+    normalize_path,
+    read_matched_specs,
+    resolve_compress,
+    resolve_inject_mode,
+    resolve_session_id,
+    save_inject_state,
+    select_specs_tiered,
+)
+
+# Pseudo spec-path key used in prompt_inject_window to dedup catalog emission.
+_CATALOG_KEY = "__catalog__"
+
+# Match bare paths, @-prefixed paths, and backtick-quoted paths.
+# Right boundary uses an ASCII-only negative lookahead instead of \b. Python's
+# \b is Unicode-aware on every platform, so "src/cli.js中" never terminated
+# the match — common Chinese phrasing dropped real paths. The explicit ASCII
+# class is locale- and OS-independent, so Windows/macOS/Linux behave the same.
+# Character class includes `\` so Windows-style paths (`src\cli.js`) pasted
+# from Explorer also match; `normalize_path()` downstream converts to `/`.
+_PATH_RE = re.compile(r'[@`]?([a-zA-Z0-9_.][a-zA-Z0-9_./\\\-]*\.[a-zA-Z]{1,6})(?![a-zA-Z0-9_])')
+_EXT_RE = re.compile(r'\.(py|js|ts|go|rs|java|rb|cs|cpp|c|h)$')
+
+
+def extract_paths_from_prompt(prompt: str) -> list:
+    """Extract candidate file paths referenced in prompt text."""
+    paths = []
+    seen = set()
+    for m in _PATH_RE.finditer(prompt):
+        candidate = normalize_path(m.group(1).lstrip('@`'))
+        # Require at least one slash or a meaningful extension to reduce noise
+        if candidate in seen:
+            continue
+        if '/' in candidate or _EXT_RE.search(candidate):
+            paths.append(candidate)
+            seen.add(candidate)
+    return paths
+
+
+def _emit_catalog(
+    project_root: str,
+    sid: str,
+    inject_config: dict,
+    budget_cfg: dict,
+    effective_mapping: dict,
+    quality_loop: dict = None,
+) -> None:
+    """Inject the compact spec catalog (inject.mode=catalog, no path evidence).
+
+    The model does the semantic spec selection itself by reading the catalog;
+    dedup reuses prompt_inject_window under the pseudo key _CATALOG_KEY so the
+    catalog re-surfaces after dedup_window prompts (auto-compaction recovery).
+    """
+    try:
+        catalog_max = int(budget_cfg.get("catalog_max", 200))
+    except (ValueError, TypeError):
+        catalog_max = 200
+    catalog = build_spec_catalog(project_root, effective_mapping, catalog_max)
+    if not catalog:
+        debug_log(f"user_prompt_hook catalog_empty session={sid}", project_root)
+        return
+
+    state = load_inject_state(project_root)
+    same_session = state.get("session_id") == sid
+    if same_session:
+        injected_specs = set(state.get("injected_specs") or [])
+        prompt_window = dict(state.get("prompt_inject_window") or {})
+        prompt_count = int(state.get("prompt_count") or 0) + 1
+    else:
+        injected_specs = set()
+        prompt_window = {}
+        prompt_count = 1
+
+    try:
+        dedup_window = int(inject_config.get("dedup_window", 5))
+    except (ValueError, TypeError):
+        dedup_window = 5
+
+    last = prompt_window.get(_CATALOG_KEY)
+    emit = (
+        dedup_window <= 0
+        or last is None
+        or prompt_count - int(last) >= dedup_window
+    )
+    if emit:
+        prompt_window[_CATALOG_KEY] = prompt_count
+    save_inject_state(project_root, {
+        "session_id": sid,
+        "injected_specs": sorted(injected_specs),
+        "last_file": state.get("last_file", "") if same_session else "",
+        "prompt_count": prompt_count,
+        "prompt_inject_window": prompt_window,
+    })
+
+    if not emit:
+        debug_log(
+            f"user_prompt_hook catalog_deduped session={sid} prompt_count={prompt_count}",
+            project_root,
+        )
+        return
+
+    debug_log(
+        f"user_prompt_hook catalog_injected tokens={estimate_tokens(catalog)} "
+        f"prompt_count={prompt_count} session={sid}",
+        project_root,
+    )
+    if quality_loop and quality_loop.get("enabled"):
+        cf_log.append_event(
+            project_root, "inject",
+            {"specs": ["__catalog__"], "mode": "catalog", "source": "catalog"},
+            sid,
+        )
+    payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "UserPromptSubmit",
+            "additionalContext": catalog,
+        }
+    }
+    if os.environ.get("CF_DEBUG") == "1":
+        payload["debug"] = {"mode": "catalog", "prompt_count": prompt_count}
+    sys.stdout.write(json.dumps(payload, ensure_ascii=False))
+
+
+def main() -> None:
+    try:
+        ensure_utf8_io()
+        raw = sys.stdin.read()
+        if not raw.strip():
+            return
+        data = json.loads(raw)
+        prompt = data.get("prompt", "")
+        if not isinstance(prompt, str) or not prompt.strip():
+            return
+
+        project_root = os.getcwd()
+        
+        # Resolve session_id consistently with PreToolUse hook
+        sid = resolve_session_id(data)
+        debug_log(
+            f"user_prompt_hook start session={sid} "
+            f"prompt_len={len(prompt)} prompt_head={prompt[:200]!r}",
+            project_root,
+        )
+
+        config = load_config(project_root)
+        if not config:
+            debug_log(f"user_prompt_hook no_config session={sid}", project_root)
+            return
+
+        inject_config = config.get("inject") or {}
+        if inject_config.get("auto") is False:
+            return
+        compress_enabled = resolve_compress(inject_config)
+
+        mapping = config.get("path_mapping") or {}
+        effective_mapping = build_effective_mapping(project_root, mapping)
+
+        budget_cfg = config.get("budget") or {}
+        l1_budget = 1700
+        map_max = 400
+        try:
+            l1_budget = int(budget_cfg.get("l1_max", 1700))
+        except (ValueError, TypeError):
+            pass
+        try:
+            map_max = int(budget_cfg.get("map_max", 400))
+        except (ValueError, TypeError):
+            pass
+
+        # Derive context_tags from file paths mentioned in the prompt
+        candidate_paths = extract_paths_from_prompt(prompt)
+        context_tags: set = set()
+        matched_domains: set = set()
+        for cp in candidate_paths:
+            context_tags.update(extract_context_tags(cp))
+            matched_domains.update(match_domains(cp, effective_mapping))
+
+        # NEW: Extract prompt_tags from user prompt keywords
+        prompt_tags = extract_prompt_tags(prompt)
+        debug_log(f"user_prompt_hook paths={candidate_paths} context_tags={sorted(context_tags)} prompt_tags={sorted(prompt_tags)}", project_root)
+
+        # Catalog mode: prompts without explicit path evidence get the compact
+        # spec catalog and the model pulls relevant specs itself — keyword-table
+        # guessing systematically missed open vocabulary. Path-bearing prompts
+        # (matched_domains non-empty here means a prompt path hit a domain
+        # pattern) keep deterministic full injection: paths are strong evidence.
+        mode = resolve_inject_mode(inject_config)
+        quality_loop = resolve_quality_loop(config)
+
+        # FEAT-04 信号①：纠正句式 → correction 事件（仅本地，NFR-SEC-01）。
+        # 配对（信号②）由 cf-learn 离线完成，hook 热路径只记原始事件。
+        if quality_loop["correction_capture"]:
+            from cf_checks import detect_correction
+            correction = detect_correction(prompt)
+            if correction:
+                cf_log.append_event(
+                    project_root, "correction",
+                    {"phrase": correction["phrase"],
+                     "prompt_head": prompt[:200],
+                     "files": candidate_paths},
+                    sid,
+                )
+                debug_log(
+                    f"user_prompt_hook correction phrase={correction['phrase']!r}",
+                    project_root,
+                )
+
+        if mode == "catalog" and not matched_domains:
+            _emit_catalog(
+                project_root, sid, inject_config, budget_cfg,
+                effective_mapping, quality_loop,
+            )
+            return
+
+        # Fallback: unresolved domains → prefer domain-name hint in tags, then all domains
+        if not matched_domains:
+            matched_domains = fallback_domains_for_context(effective_mapping, context_tags)
+            debug_log(f"user_prompt_hook fallback_domains={sorted(matched_domains)}", project_root)
+
+        # Strict tag-based matching per domain. No bulk-load fallback: when a
+        # Tier 1 spec's tags don't intersect (context_tags ∪ prompt_tags), the
+        # spec is NOT injected. Tier 0 (_map.md) uses "*" so navigation still
+        # reaches the model. Re-inject every call (session dedup removed).
+        all_matched = []
+        for domain in matched_domains:
+            domain_cfg = effective_mapping.get(domain) or {}
+            specs_config = domain_cfg.get("specs") or []
+            matched, _ = match_specs_by_tags(specs_config, context_tags, prompt_tags)
+            if matched:
+                specs = read_matched_specs(
+                    project_root, domain, matched, compress=compress_enabled
+                )
+                all_matched.extend(specs)
+
+        if not all_matched:
+            debug_log(f"user_prompt_hook no_specs_matched session={sid}", project_root)
+            return
+
+        selected = select_specs_tiered(all_matched, l1_budget, map_max)
+        if not selected:
+            return
+
+        # Load state with session isolation (deferred until after match success)
+        state = load_inject_state(project_root)
+        same_session = state.get("session_id") == sid
+        if same_session:
+            injected_specs = set(state.get("injected_specs") or [])
+            prompt_window = dict(state.get("prompt_inject_window") or {})
+            prompt_count = int(state.get("prompt_count") or 0) + 1
+        else:
+            injected_specs = set()
+            prompt_window = {}
+            prompt_count = 1
+
+        # TTL-window dedup: skip specs re-injected within the last N prompts in
+        # this session. dedup_window <= 0 disables dedup (every call re-injects).
+        # The window bounds — not removes — re-injection, so an auto-compaction
+        # that drops earlier context can still recover specs after N prompts.
+        try:
+            dedup_window = int(inject_config.get("dedup_window", 5))
+        except (ValueError, TypeError):
+            dedup_window = 5
+
+        if dedup_window > 0:
+            emitted = [
+                s for s in selected
+                if (s["path"] not in prompt_window)
+                or (prompt_count - int(prompt_window[s["path"]]) >= dedup_window)
+            ]
+        else:
+            emitted = list(selected)
+
+        # Compare by path so this stays correct if `emitted` is ever rebuilt
+        # from copies instead of filtered references to the same dicts.
+        emitted_paths = {s["path"] for s in emitted}
+        skipped = [s["path"] for s in selected if s["path"] not in emitted_paths]
+
+        # Catalog-mode path turns also carry the catalog (same dedup window):
+        # the path pins one domain's full specs, the catalog keeps every other
+        # spec reachable for cross-domain asks ("改 cli.js 部署 hook 脚本"
+        # would otherwise lose the scripts constraints entirely).
+        catalog_text = ""
+        if mode == "catalog":
+            last = prompt_window.get(_CATALOG_KEY)
+            catalog_due = (
+                dedup_window <= 0
+                or last is None
+                or prompt_count - int(last) >= dedup_window
+            )
+            if catalog_due:
+                try:
+                    catalog_max = int(budget_cfg.get("catalog_max", 200))
+                except (ValueError, TypeError):
+                    catalog_max = 200
+                catalog_text = build_spec_catalog(
+                    project_root, effective_mapping, catalog_max
+                )
+                if catalog_text:
+                    prompt_window[_CATALOG_KEY] = prompt_count
+
+        # Always persist prompt_count so the dedup window keeps advancing even
+        # on fully-deduped turns. Preserve PreToolUse-owned fields verbatim.
+        for s in emitted:
+            prompt_window[s["path"]] = prompt_count
+        save_inject_state(project_root, {
+            "session_id": sid,
+            "injected_specs": sorted(injected_specs | {s["path"] for s in emitted}),
+            "last_file": state.get("last_file", "") if same_session else "",
+            "prompt_count": prompt_count,
+            "prompt_inject_window": prompt_window,
+        })
+
+        if not emitted and not catalog_text:
+            debug_log(
+                f"user_prompt_hook dedup_all_skipped session={sid} "
+                f"prompt_count={prompt_count} skipped={skipped}",
+                project_root,
+            )
+            return
+
+        debug_log(
+            f"user_prompt_hook injected={[s['path'] for s in emitted]} "
+            f"skipped={skipped} catalog_appended={bool(catalog_text)} "
+            f"prompt_count={prompt_count} session={sid}",
+            project_root,
+        )
+
+        if quality_loop["enabled"]:
+            cf_log.append_event(
+                project_root, "inject",
+                {"specs": [s["path"] for s in emitted],
+                 "mode": mode, "source": "prompt",
+                 "catalog_appended": bool(catalog_text)},
+                sid,
+            )
+
+        parts = []
+        if emitted:
+            parts.append(assemble_context(emitted, "## Active Specs (auto-injected)"))
+        if catalog_text:
+            parts.append(catalog_text)
+        payload = {
+            "hookSpecificOutput": {
+                "hookEventName": "UserPromptSubmit",
+                "additionalContext": "\n\n".join(parts),
+            }
+        }
+        if os.environ.get("CF_DEBUG") == "1":
+            payload["debug"] = {
+                "mode": mode,
+                "candidate_paths": candidate_paths,
+                "domains": sorted(matched_domains),
+                "context_tags": sorted(context_tags),
+                "prompt_tags": sorted(prompt_tags),
+                "matched_specs": [s["path"] for s in emitted],
+                "deduped_specs": skipped,
+                "prompt_count": prompt_count,
+                "dedup_window": dedup_window,
+            }
+
+        sys.stdout.write(json.dumps(payload, ensure_ascii=False))
+
+    except Exception as exc:
+        _log(f"cf_user_prompt_hook error: {exc}")
+        return
+
+
+if __name__ == "__main__":
+    main()

package/src/core/code-flow/specs/backend/_map.md

@@ -0,0 +1,56 @@
+# Backend Retrieval Map
+
+> AI 导航地图：定位后端代码结构和关键模块。可由 `/cf-learn --map` 重生成，建议按真实项目手动校准。
+
+## Purpose
+
+后端服务，负责 API 暴露、业务逻辑与数据持久化。默认假设为分层架构（API → Service → Model）。
+
+## Architecture
+
+- Framework: 任意 Web 框架（FastAPI / Express / Spring / Gin 等）
+- ORM/Driver: 与数据库匹配的官方/主流驱动
+- Database: 关系型为主（PostgreSQL / MySQL），可叠加缓存（Redis）
+- Auth: Token-based（JWT / OAuth2 / Session）
+- Async: 必要时引入消息队列或后台任务（Celery / Bull / BullMQ）
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/main.*` | 应用入口，初始化框架、路由、中间件 |
+| `src/api/router.*` | 路由注册，统一前缀与版本 |
+| `src/services/` | 业务逻辑实现，禁止跨层调用 ORM |
+| `src/models/` | 数据模型定义（ORM / Schema） |
+| `src/crud/`（或 `repositories/`） | 数据访问层，业务只依赖此抽象 |
+| `src/config/` | 配置加载，环境变量优先 |
+
+## Module Map
+
+```
+src/
+├── api/         # 接口层：路由 + 请求/响应 schema 校验
+├── services/    # 业务逻辑层：纯函数为主，便于测试
+├── models/      # 数据模型（ORM 或 ODM）
+├── crud/        # 数据访问层（repositories），业务只调 CRUD 不碰 ORM
+├── migrations/  # DB 迁移脚本（可回滚或幂等）
+├── errors/      # 错误码→message 常量，按业务模块拆分
+├── schemas/     # DTO / 请求响应类型
+├── middleware/  # 认证、日志、限流、CORS
+├── utils/       # 工具函数，无业务依赖
+└── config/      # 配置与环境变量
+```
+
+## Data Flow
+
+```
+Request → Middleware(auth/log) → Router → Handler(API)
+        → Service(业务) → Model(DB/Cache) → Response
+```
+
+## Navigation Guide
+
+- 新增 API → `api/` 加路由 + `schemas/` 定义请求响应 + `services/` 实现业务
+- 新增表 → `models/` 定义模型 + `migrations/` 加迁移脚本
+- 错误处理 → 抛业务异常类，由中间件统一转 HTTP 响应
+- 配置项 → `config/` 集中管理，禁止散落 `os.environ`/`process.env`

package/src/core/code-flow/specs/backend/code-quality-performance.md

@@ -0,0 +1,47 @@
+---
+description: 写后端代码时适用：错误处理、测试、超时重试、缓存等质量与性能约束
+---
+
+# Backend Code Quality & Performance
+
+## Examples
+
+> ✅/❌ 对照示例对 AI 的引导远强于规则条文——新写规范优先用这个格式（cf-learn 候选会自动生成草稿）。
+
+✅ 显式错误处理
+
+```python
+try:
+    result = service.call()
+except ServiceError as exc:
+    logger.warning("call failed: %s", exc)
+    raise
+```
+
+❌ 静默吞异常
+
+```python
+try:
+    result = service.call()
+except Exception:
+    pass
+```
+
+
+## Rules
+- 所有公开函数 / 方法必须有类型注解（type hints / 类型签名）
+- 异常必须显式处理或显式上抛，禁止 `except Exception: pass` / `catch (e) {}` 静默吞掉
+- 外部依赖调用（HTTP / RPC / DB）必须设置超时，关键调用补重试 + 指数退避
+- 单元测试覆盖核心业务路径：happy path + 边界 + 错误分支，每个需求 ≥ 1 个用例
+
+## Patterns
+- 缓存可计算结果以减少重复 IO，明确缓存 key、TTL 与失效策略
+- 重 IO 用异步或批处理，CPU 密集任务下沉到 worker / 队列
+- 资源（连接、文件、锁）使用 `with` / `using` / `defer` 确保释放
+- 性能敏感路径加监控指标（QPS / P95 延迟 / 错误率）
+
+## Anti-Patterns
+- 禁止在请求链路中吞掉异常导致客户端拿到错误结果却无日志
+- 禁止无超时的外部调用（容易导致线程 / 协程泄漏）
+- 禁止用循环模拟批量操作（DB 批量 / 网络批量必须用原生批量 API）
+- 禁止把缓存失败当致命错误，缓存层必须可降级为直接查询

package/src/core/code-flow/specs/backend/database.md

@@ -0,0 +1,39 @@
+---
+description: 涉及数据库/ORM/迁移/查询时适用：schema 与数据访问约束
+---
+
+# Backend Database
+
+## Examples
+
+✅ 参数化查询，明确列出字段
+
+```python
+cur.execute("SELECT id, name FROM users WHERE email = %s", (email,))
+```
+
+❌ 字符串拼接用户输入（SQL 注入）+ `SELECT *`
+
+```python
+cur.execute(f"SELECT * FROM users WHERE email = '{email}'")
+```
+
+## Rules
+- 所有 SQL 必须参数化，禁止字符串拼接 / 模板插值用户输入
+- 迁移脚本必须可回滚，或写成幂等脚本（`IF NOT EXISTS` / `ON CONFLICT`）
+- 事务边界明确：跨表写入必须在同一事务内，禁止"半提交"状态
+- 涉及索引/锁的 schema 变更必须评估线上影响，大表慎用 `ALTER TABLE` 阻塞操作
+- 每个 model 必须有对应 CRUD 抽象层（`crud/<model>.py` 或 `repositories/<Model>Repo`），业务代码只调 CRUD，禁止在 service / handler 直接写 ORM 查询或裸 SQL
+
+## Patterns
+- 读写分离场景显式标注读库/写库，强一致读走主库
+- N+1 查询用预加载（`joinedload` / `include` / `Preload`）解决
+- 大批量写入分批 + commit，避免单事务过大
+- 缓存与数据库一致性：先写库再失效缓存（`cache-aside`）
+- CRUD 基类统一实现 `get / list / create / update / delete / bulk_*`，子类只扩展模型特有查询
+
+## Anti-Patterns
+- 禁止在事务内发起外部 HTTP / RPC 调用，超时会导致连接池耗尽
+- 禁止在循环中执行单条 `INSERT` / `UPDATE`，必须批量化
+- 禁止在 ORM 之外手写 SQL 时绕过参数绑定
+- 禁止用 `SELECT *` 上线，明确列出字段控制传输与索引

package/src/core/code-flow/specs/backend/directory-structure.md

@@ -0,0 +1,42 @@
+---
+description: 新建/移动后端文件时适用：目录结构与模块组织约束
+---
+
+# Backend Directory Structure
+
+## Examples
+
+✅ 魔法值集中到 `constants/`，命名引用
+
+```python
+# constants/order.py
+ORDER_PAID = 1
+# service：if order.status == ORDER_PAID: ...
+```
+
+❌ 业务代码散落硬编码字面量
+
+```python
+if order.status == 1 and role == "admin":   # 魔法数字 / 魔法字符串
+    ...
+```
+
+## Rules
+- 接口层放 `api/`，业务逻辑放 `services/`，数据模型放 `models/`，禁止跨层倒置依赖
+- 入口文件（`main.*`）只做框架装配，不写业务代码
+- 配置统一放 `config/`，禁止在业务代码中直接读 `os.environ` / `process.env`
+- 常量集中放 `constants/`，按业务模块拆分（`constants/order.py`、`constants/user.py`），禁止在业务代码中散落硬编码字面量（魔法数字 / 字符串 / 状态码）
+- 数据访问层独立放 `crud/` 或 `repositories/`，业务层依赖 CRUD 抽象，不直接依赖 ORM
+- 新增一级目录必须同步更新导航地图与 `__init__` / `index` 索引
+
+## Patterns
+- 模块按业务域拆分（如 `services/order/`、`services/user/`），目录深度建议 ≤ 3 层
+- 公共工具放 `utils/`，无业务依赖；与业务相关的 helper 放对应 service 子目录
+- 常量命名用 UPPER_SNAKE_CASE，枚举优先使用语言原生 `Enum`
+- 测试目录与源码同构（`tests/services/order/test_*`）
+
+## Anti-Patterns
+- 禁止在根目录堆放脚本与临时代码，临时脚本放 `scripts/` 并命名清晰
+- 禁止在 `models/` 里写业务逻辑，模型仅定义结构与简单关联
+- 禁止把常量直接写在业务代码里（如 `if status == 1` / `role == "admin"`），必须引用 `constants/` 中的命名常量
+- 禁止单文件超过 500 行或单函数超过 50 行

package/src/core/code-flow/specs/backend/logging.md

@@ -0,0 +1,38 @@
+---
+description: 涉及日志/调试/监控时适用：日志级别、格式、追踪约束
+---
+
+# Backend Logging
+
+## Examples
+
+✅ 结构化字段 + 脱敏 + 保留堆栈
+
+```python
+logger.info("login", extra={"user_id": uid, "request_id": rid})
+logger.error("pay failed", exc_info=True)
+```
+
+❌ 明文 token + `print` 吞掉堆栈
+
+```python
+print(f"login token={token}")          # 泄露敏感字段 + 非日志框架
+logger.error("failed")                 # 丢失原始错误与上下文
+```
+
+## Rules
+- 关键路径（请求入口、外部调用、DB 写入、异常分支）必须输出结构化日志
+- 日志中禁止出现明文密码、token、身份证号等敏感字段，需在记录前脱敏
+- 每条请求日志必须包含 `request_id`，串联整个调用链
+- 日志级别遵循：`DEBUG`（开发）/ `INFO`（业务事件）/ `WARN`（可恢复异常）/ `ERROR`（需告警）
+
+## Patterns
+- 统一字段命名：`request_id`、`user_id`、`route`、`status`、`latency_ms`、`error`
+- 异常日志必须带堆栈（`exc_info=True` 或等价机制）
+- 高频路径用采样日志，避免 IO 阻塞主流程
+- 日志输出到 stdout/stderr，由部署环境采集，禁止业务代码写文件
+
+## Anti-Patterns
+- 禁止在循环或热路径中无脱敏地打印请求体
+- 禁止用 `print` / `console.log` 替代日志框架
+- 禁止吞掉异常仅打 `logger.error("failed")`，必须保留原始错误与上下文

package/src/core/code-flow/specs/backend/platform-rules.md

@@ -0,0 +1,43 @@
+---
+description: 涉及 API 设计/部署/配置/版本兼容时适用：平台规则
+---
+
+# Backend Platform Rules
+
+## Examples
+
+✅ 走统一封装 + 错误码常量
+
+```python
+return success(data)
+raise BizError(ORDER_NOT_FOUND)   # 错误码定义在 errors/order.py
+```
+
+❌ handler 手拼响应结构 + 硬编码 message
+
+```python
+return {"code": 1, "message": "order not found", "data": None}
+```
+
+## Rules
+- API 变更必须保持向后兼容；破坏性变更走新版本路径（`/v2/...`）并保留旧版本至少一个发布周期
+- 配置项分环境管理（dev / staging / prod），敏感值走密钥管理服务，禁止入库
+- 新增外部依赖必须更新部署文档与 `requirements` / `package.json` 锁文件
+- 灰度 / 实验性功能必须由 feature flag 控制，默认关闭
+- API 响应必须走统一封装：`success(data)` / `fail(code, message?)`，handler 禁止手写 `{code, message, data}` 字面量
+- 错误码 → message 映射定义为常量，按业务模块拆分（`errors/order.py`、`errors/user.py`），错误码全局唯一，禁止重复
+
+## Patterns
+- API 响应统一结构：`{ code, message, data }`（`code=0` 表示成功），全项目一致
+- 错误码命名空间：模块前缀 + 顺序号（如订单错误码 `10xxx`、用户 `20xxx`），便于定位归属
+- 异常 → 错误码：自定义业务异常类携带 `code`，由中间件统一转 `fail(code)` 响应
+- 配置加载优先级：环境变量 > 配置文件 > 默认值
+- 健康检查端点（`/healthz`、`/readyz`）必须独立于业务认证
+- 部署前跑 smoke test，覆盖核心路径
+
+## Anti-Patterns
+- 禁止在生产环境开启 `DEBUG` / 详细堆栈输出
+- 禁止把 secret 写进代码库或 dev 配置文件
+- 禁止破坏性 API 变更不通知调用方直接发布
+- 禁止 feature flag 长期遗留，上线稳定后必须清理
+- 禁止在 handler 里直接拼响应结构或硬编码错误 message，必须引用 `errors/` 常量并走 `success / fail` 封装