伸美 AI 增长董事会

当前提交、版本和现役见 STATUS。目录、端口和检索见 维护地图。对话生成 HTML 的步骤见 从对话生成 HTML 驾驶舱。产品仍 PARTIAL。

最近生产记录（STATUS 的 2026-10-09 现场记录）：产品 VERSION 见 STATUS，DSH 0.1.7-rc.2，固定 upstream 477b4f42；杭州 current 以 STATUS 的带日期现场记录为准，HANDOVER 只保留历史入口快照。该记录中的本地 A/B/C 候选没有部署，新的插件候选未激活。产品仍 PARTIAL；局部合成验证不能替代真实模型、完整业务 UAT、生产准入及回退证据。后续发布必须从 clean reviewed commit 生成新的 immutable artifact，禁止 git pull 或现场编译。

主仓当前快照（2026-10-17）：本轮治理与状态文档已合并，最新 main SHA 以 Git 实查和 STATUS 为准。主仓继续承担 DSH pin、profile、跨插件合同、组合验证和交付文档；CRM、知识、看板和其他业务能力由独立插件仓维护。PR #121 的历史事实仍见PR #121 合并后事实记录。单插件的实际更新步骤见插件更新指南，职责、清理和 DSH 升级边界见维护、清理与升级手册。SDK 分发仍 BLOCKED，产品仍 PARTIAL，未授权的生产/发布门禁仍保持未执行。

A/B/C 集成记录（2026-10-08）是历史证据：单插件更新与取消、固定宿主进程级恢复、HTML headed 验收和 SDK 信任盘查见本轮集成验收。它不替代当前主仓合并状态，也不代表新的 Release。

下方9月5–10日的决策、端口和候选追加保留为历史记录，不作为当前服务或Git HEAD。

AI 黑客松作品 · 多渠道客户资产诊断 · 受控自由问数与人群决策

历史价值定稿（2026-09-05）：已确认让老板拍板一个有边界的天猫内部跨渠道客户增长试点，主线是“渠道 × 首购商品 × 后续购买”。见 CEO 价值与首版决策方案。本段保留当时决策语境；当前运行和公网事实以 STATUS/HANDOVER 为准。

历史交付（2026-09-10）：competition 集成 #112 和 7 项审查修复 #114 已合入 main 788b5b1；PR 与合并后的主线 CI 均通过。独立合成浏览器已验证连续成板、失败重试、保存布局重开及行动草稿 v2，见 修复 QA。当时按 产品验收与发布准备账本 记录；单位来源修复已完成本地验证、五库恢复、候选切换和局部真实复测。后续验收与关闭状态以带日期的 STATUS/TODOS 和证据为准。

候选追加：4325/18083 均为 84b0ac8，模型配置和原资产保持，现有 2 块板、10 条结果、原草稿 v2；单位/标识/自动保存表述在本次真实用例通过，完整 T13 及 B0 404 仍开放，见当前记录。

---

项目简介

本仓库源自多渠道 CRM 分析系统。目标是把既有分析能力组织成 CEO 决策产品：AI 准备机会、证据和行动草案，老板决定优先级、资源和继续/停止条件。第一版围绕可观察的首购与后续购买，不宣称完整生命周期或已验证增长。

当前保留的 Mission 演示基线使用合成数据，支持受控问数与审批后的合成人群草稿；它不等于新版多轮工作台和驾驶舱已交付。真实业务数据库不进入公开演示链。

核心价值与边界

• 看清不同渠道和首购商品的客户后续买了什么，形成可验证的经营机会，不只给渠道排名。
• 老板拍板试点方向、负责人、资源上限和退出条件；人群核对与具体执行属于运营职责。
• 目标工作台以可信追问、证据和分析复用支持决策，不把“每天唯一 Mission”作为新版强制入口。
• 稳定 user_id 关联的是可观察订单旅程，不是因果获客归因；缺少成本与干预证据时不判断利润最优。
• 现有审批后仅生成合成 DRAFT_EXPORT，演示 holdout 比例不是通用实验设计，不自动触达真实用户。
• 公开演示使用代码生成的合成数据与 manifest；流程演示不证明真实业务收益。

---

快速开始

1. 从公共仓库克隆并创建 feature 分支。Mac 开发、杭州生产和回滚边界见 Mac 开发到杭州生产链路；当前提交、版本和现役状态看 STATUS。

   git clone https://github.com/tyuanww/fuqing-crm-analytics.git
   cd fuqing-crm-analytics
   git switch -c codex/
   

   GitHub CLI 用户可以先运行 gh auth setup-git，让 Git 使用当前 tyuanww 登录态。
2. Node 24.19.0 已写入 .nvmrc。进入仓库后可运行 nvm use；没有 nvm 时直接用 ./scripts/dsh-dev/run.sh diagnose，它会选择已安装的 Node 24。Python 仍要求 3.14+。本仓库没有 .codegraph/ 时不需要初始化 CodeGraph。
3. 端口、目录和哪份历史不要搜，见 维护地图。
4. 驾驶舱怎么生成 HTML，见 操作说明。验证范围见 当前验证入口。完整 B0 检查命令是 node scripts/dsh-b0/pipeline.mjs --check --python /absolute/python3.14。

rc2 稳定交付入口

插件作者若只修改一个独立包，先看 DSH 插件作者 Quickstart 和维护、清理与升级手册，不要重复执行整仓发布。

只更新一个插件时，按插件更新指南走“插件仓 build/test/pack → 插件 CI → 主仓组合合同 → 新 candidate 身份链”的顺序；没有对应输入就保持 NOT_RUN，不借用旧回执。

在候选提交上先运行本地合同；已有固定 runtime bundle 时再做只读发布检查。首次候选没有 runtime 时，直接运行正式 preflight，由它生成同一份 immutable artifact：

pnpm dsh doctor
pnpm dsh verify --scope local
DSH_UPSTREAM_RUNTIME_BUNDLE=/absolute/pinned/runtime.tar.zst \
  pnpm dsh doctor --release
DSH_UPSTREAM_RUNTIME_BUNDLE=/absolute/pinned/runtime.tar.zst \
  pnpm dsh preflight --check --python /absolute/python3.14 --tag dsh--check
# 首次候选直接走这条；它会自己构建固定 runtime
pnpm dsh preflight --python /absolute/python3.14 --tag dsh-

verify --scope local 的绿色结果只代表 synthetic 合同通过；默认 verify 或 --scope release 仍要求 WSL2/WAL、15 分钟 SLI 和 host HTTP 证据。正式 preflight 才会联网准备固定 runtime、构建插件并生成候选包；已有 runtime 时，doctor --release 与 preflight --check 只读复核，不启动服务、不读取真实 DuckDB、也不创建 artifact。

插件说明、选区编辑和比赛看板的细节留在各自文档里，不放在这一节。

历史演示

下面的命令启动旧的本地分析栈（8000 与 15173）。它不是现在的 6677 驾驶舱。不要把它当成默认启动，也不要拿它打开归档库。

1. 启动本地演示

./scripts/ops/start-stack.sh

• 后端 API: http://127.0.0.1:8000
• 前端界面: http://127.0.0.1:15173（start-stack 默认；裸 npm run dev 仍可能是 5173）
• API 文档（无需登录）: http://127.0.0.1:8000/docs

演示结束后恢复冷存：

./scripts/ops/stop-stack.sh

Mission 的合成数据和环境配置见 docs/hackathon/README.md。

2. ETL 增量更新（仅既有私有分析环境）

PYTHONPATH="$(pwd)" /Users/yourname/homebrew/bin/python3 scripts/run_etl.py --update

3. 即席查询 CLI（/ad-hoc-query skill, Sprint 171 v2.0）

# 10 个面向用户的子命令（skill 另有 18 个工具入口）: daily-gsv / yoy-battle / channel-slice /
#   two-year-overview / new-old-customer / rfm-repurchase /
#   top-n / export-excel / dq-report / ask NL 路由
PYTHONPATH="$(pwd)" python3 scripts/ad_hoc_query.py  [args]
# 详: .claude/skills/ad-hoc-query/SKILL.md

4. 测试

PYTHONPATH="$(pwd)" pytest backend/tests/ -v              # 后端单测
cd frontend-vue3 && npx playwright test                   # E2E

---

状态 SSOT

短表入口 — 详细历史在 docs/history/，不要在 STATUS 堆编年。

---

文档导航

完整文档索引 + 跨文档一致性见 docs/README.md。速查：

---

架构原则

本节订单/退款规则属于既有私有CRM，不自动套用于新synthetic分析。新渠道路径的净支付有效单、同刻排序和N日成熟窗口采用 版本化拟定合同，须独立金标准验证，不能混用分母。

1. 语义层唯一真实数据源：口径只定义一次，禁止在 Service 中硬编码 SQL
2. 双保险过滤：is_refund=FALSE 且 order_status!='交易关闭'
3. 契约层外置：所有 Pydantic 模型统一从 backend/contracts/schemas.py 导入
4. 前端只做展示：禁止前端计算 YOY/占比等业务指标
5. 连接零泄漏：DuckDB 连接必须 try/finally 关闭

详细项目结构见 docs/README.md。

---

运维安全 / 磁盘治理

6 层防护详情见 docs/operating/ship.md 跟 Sprint 6 P0-3 落地说明。

紧急清理:

PYTHONPATH="$(pwd)" python3 scripts/etl/cli.py --cleanup-tmp

---

核心技术栈

---

core 数据指标