Shop Gate 是建立在通用 Data Agent 与开源 PI Agent 执行内核之上的零售电商经营分析应用。用户用自然语言提出经营问题，Retail Domain Pack 会组合商品/类目实体解析、真实行为数据、Skills、工具、Mission 和可视化规则，生成可运行工作空间，并通过自动验证、视觉检查、产物契约和评测链路把结果收敛到“好看、可用、可追溯”。同一套框架可以继续接入其他业务 Domain Pack，而不把业务规则写回 Agent 内核。
生成内容仅用于经营复盘和辅助决策；金额为合成口径，不构成采购、定价或交易指令。
如果你是第一次打开这个项目，先选择模型与 Memory 运行方式，再把本地环境跑起来。核心链路是：真实数据进入本地库，Agent 基于 skills 生成工作空间，平台再用验证和评测把结果收紧。
- 通用 Data Agent：使用版本化 Task、Dataset、Connector、Domain Pack、Agent Profile、Delivery Pack 和 Execution Plan 合同组合业务能力；
DataAgentApplicationCatalog让 Profile Adapter 负责 workspace 初始化，项目和任务同时持久化 Profile/Domain/Delivery/capability 版本锁与 SHA-256。当前零售实现是retail.core（Profileshopgate.retail-ops），通用 Next.js 交付实现是workspace.next-dashboard。完整边界与新业务接入流程见 Data Agent 平台与 Domain Pack 架构。 - AI 工作台：任务入口、项目聊天、工作空间预览、任务记录和自动修复链路。
- 经营数据底座：PostgreSQL + TimescaleDB + Redis，承载应用状态、行为事件、商品/类目日聚合、合成主数据和导入任务状态。
- 数据服务：Python/FastAPI 后端，提供经营摘要、行为漏斗、类目经营榜、商品池、库存风险、渠道口径、实体解析与数据导入接口。
- 商品运营：商品池、品类池、渠道口径、价格带与库存风险、观察池和商品/类目实体解析。
- 经营情报中心：围绕观察池生成证据型经营日报，沉淀类目经营榜、异动摘要、运行历史和推送回执（推送回执待通知渠道配置）。
- LLM-first Query Rewrite：
preview与正式执行都由项目选中的模型生成 schema v4 语义合同，时间范围、宽域范围和 answer-only 意图必须有原文字面证据；实体 Resolver 独立确认商品/类目。模型不可用时停止规划和预取，不以关键词结果冒充成功。 - PI Agent 执行内核 + Shop Gate 治理层：
@earendil-works/pi-agent-core负责完整多轮 Agent loop，模型可通过外部 OpenAI-compatible 网关接入，也可为项目显式选择 DeepSeek 官方直连；外部网关不属于本项目，Shop Gate 只依赖其公开 HTTP 协议。Shop Gate 保留上下文治理、信息增益 Observation Ledger、受信副作用工具的人工批准/编辑/拒绝、PostgreSQL generation job/事务 outbox、独立 Worker registry、数据库全局 Worker 槽位、按用户公平 claim、用户排队/运行双层结构配额、项目编排/AgentRun/Mission 分层 lease 与 fencing、共享文件系统资源锁、durable run/approval/operation ledger、预算、取消和显式结果提交。审批等待会把 AgentRun 原子切到waiting并写公开 checkpoint，决策通过后才允许 prepare/execute；Worker 丢失则关闭旧 attempt 并重新规划，不复用已批准的旧调用。Worker 启动时会持久注册进程身份与心跳，并拒绝加入全局容量配置不一致的存活集群；运行治理中心直接展示进程、槽位和队列事实。HTTP 入口只负责接收与调度，经营规划/取数由独立应用服务完成；生产 Worker 与本地 inline 模式都使用 schema v3 execution envelope，按 Profile handler 执行并核对项目、request、workspace、跨平台 scope 和组合哈希。Memory Recall 与受治理知识准备快照随任务固化，避免排队后重复检索导致 evidence 与实际输入漂移。PiAgent*类型和结构化 JSON 合同由通用治理层定义，Domain Pack 只注入领域能力；内核不内置零售工具、dashboard 路径或业务 Mission。版本与边界见 PI Agent 采用与治理边界。 - Skills 能力层：仓库
.pi/**是唯一权威源，通过 registry/lock、版本与 SHA-256 完整性校验；项目初始化把参考镜像配置到 workspace.pi/skills，Agent 执行按 source-first/package-fallback 规则只读编译有界上下文，不从 workspace 镜像发现能力，也不解析旧 Skill ID。 - 业务与治理：业务知识中心、评测平台和运行治理中心共同覆盖能力知识、交付契约、生成质量、工作空间健康、运行 trace 和集中日志。
- 受治理上下文接入：通过独立 HTTP 契约组合 Memory Usage Receipt 与 AKEP ContextPack，Agent 前落无正文联合清单，Mission 验收后记录 AKEP Usage，用户明确评价后再分别回传 Memory Outcome 与 AKEP Feedback；不共享数据库或源码。
- 生成代码隔离：build/preview 默认进入 Linux user、mount、network、PID namespace，工作区只读且不注入平台密钥；preview 只经工作区 Unix Socket 对浏览器开放，并获得一条固定目标的无凭据 commerce-data 桥接，不能访问其他宿主服务或外网。
第一次启动按下面顺序来。npm install 的 postinstall 会创建缺失的 .env 和 .env.local；也可以显式执行 ensure:env。不要把整份 .env.example 复制到 .env.local，后者只应保存本机凭据与少量覆盖。
npm install
npm run ensure:env使用外部模型网关时，只需在 .env.local 添加该服务签发的受限客户端凭据：
MODELPORT_API_KEY="replace-with-scoped-external-gateway-client-key"本地 Qwen 是默认模型，日常 DeepSeek 可通过外部模型网关使用。网关上游凭据只保存在外部服务；如果明确使用官方直连，则在 Shop Gate 注入 DEEPSEEK_API_KEY，并显式选择 deepseek-v4-flash。Memory 是独立可选组件，可用 SHOPGATE_MEMORY_ENABLED=0 完全关闭。
跨平台作用域采用 Consumer + Workspace 两层隔离：外部模型网关客户端凭据固定绑定 Shop Gate 项目账本，Memory 使用 Shop Gate 独占 tenant，AKEP 每轮只查询 shared Space 与当前 Project.id 派生的 project Space；统一作用域摘要写入数据库和 workspace evidence。详见 联合上下文与项目隔离。
| 运行方式 | .env.local 最小配置 |
额外动作 |
|---|---|---|
| 推荐：Qwen + 外部网关 DeepSeek | MODELPORT_API_KEY=... |
在外部网关配置 Qwen 与 DeepSeek provider |
| 只使用 Qwen | MODELPORT_API_KEY=... |
外部网关客户端 Key 只授权 local_qwen 即可 |
| DeepSeek 官方直连 | DEEPSEEK_API_KEY=... |
项目/全局设置选择 deepseek-v4-flash |
| 不启用 Memory | SHOPGATE_MEMORY_ENABLED=0 |
无需启动或配置 Memory 服务 |
完整的文件优先级、可复制组合、生产 secret 边界和验证命令见 配置、模型接入与可选组件指南。
npm run db:up
npm run db:init如需集中日志和 Grafana 排查界面，可再启动本地可观测性组件：
npm run obs:up在项目根目录启动完整开发栈。npm run dev 调用 scripts/dev/run-full.js，先启动或复用 commerce-data，再由 run-web.js 完成端口选择、环境文件同步、稳定 CSS 生成、数据库 schema 检查、Next dev 缓存清理和 Web 启动：
npm run dev默认访问 http://localhost:3000。如果 3000 被占用，启动器会在 3000-3099 内选择可用端口并同步 .env / .env.local 中的 PORT、WEB_PORT 和 NEXT_PUBLIC_APP_URL。生成项目预览端口池从 4100 开始；本地 Loki 默认映射到宿主机 33100，不要把主前端长期放到这些端口上。
不启动 Loki/Grafana 时，运行治理中心会自动降级到本地文件日志；不启动 commerce-data 后端时，商品运营与经营情报页面只能展示有限兜底信息。
| 入口 | 地址 | 说明 |
|---|---|---|
| AI 工作台 | http://localhost:3000 |
创建任务、进入项目聊天和预览 |
| 商品运营 | http://localhost:3000/commerce-platform |
商品池（分页/排序）、品类池、渠道口径与价格带库存风险 |
| 经营情报 | http://localhost:3000/operations-briefing |
经营日报、类目经营榜、观察池与日报生成/持久化 |
| Skills 管理 | http://localhost:3000/skills |
编辑、发布、回滚和导入核心 skills |
| 业务知识中心 | http://localhost:3000/business-knowledge |
查看零售能力、典型场景、交付规范和执行依赖 |
| 运行治理中心 | http://localhost:3000/ops-platform |
统一查看 Worker/队列、服务依赖、工作空间交付、生成链路和运行日志 |
| 评测平台 | http://localhost:3000/eval-platform |
运行评测、管理评测集、查看队列和报告 |
| 场景 | 命令 |
|---|---|
| 完整开发环境（前端 + commerce-data） | npm run dev |
| 仅启动主前端 | npm run dev:web |
| 仅启动 commerce-data 后端 | npm run dev:commerce |
| 指定主前端端口 | npm run dev -- --port 3000 |
| 单元与后端测试 | npm test |
| 确定性发布质量门 | npm run release:check |
| 含依赖审计与运行态诊断 | npm run release:check:full |
| 数据库启动 | npm run db:up && npm run db:init |
| 数据库检查 | npm run db:doctor |
| 本地单次消费 generation job | PI_AGENT_DISPATCH_MODE=worker npm run worker:generation:once |
| 导入或重建零售数据 | cd services/commerce-data && uv run shopgate-commerce-import --help |
| 检查公开零售基准契约 | npm run check:retail-e2e |
| 要求最近一次真实零售 E2E 证据 | npm run check:retail-e2e -- --require-evidence |
| 初始化/维护登录管理员 | npm run auth:bootstrap |
| 验证完整用户生命周期 | npm run auth:verify |
| 清理过期认证数据与配额预留 | npm run auth:cleanup |
| Redis CLI | npm run redis:cli |
| 可观测性启动 | npm run obs:up |
| 可观测性日志 | npm run obs:logs |
| Skills 检查 | npm run check:skills |
| 验证修复链路检查 | npm run check:validation-repair |
| 首页视觉 smoke | npm run check:homepage |
| 全平台响应式视觉 smoke | 启动 Web 后运行 npm run check:platform-visuals |
| commerce-data 后端 | cd services/commerce-data && uv run shopgate-commerce-api |
| 后端质量门 | cd services/commerce-data && uv run ruff check . && uv run pytest |
| 文档本地链接检查 | npm run check:docs |
| 四类生成模板真实构建 | npm run check:scaffold-templates |
| 模型配置边界检查 | npm run check:ai-provider-boundary |
| 模型目录与凭据连通性检查 | npm run check:models |
| Qwen、外部网关 DeepSeek、Memory 基础契约联调 | npm run check:integrations |
| 外部模型网关、Memory、AKEP 30 题真实体验验收 | npm run check:triad-experience |
| 四组自然语言变体、共 120 题真实压力验收 | npm run check:triad-experience:large |
| 50 题 Qwen + Memory + AKEP 持久闭环验收 | 先在 AKEP 运行 pnpm seed:shopgate-acceptance-50 -- --output=<manifest>，再运行 npm run check:memory-knowledge-50 -- --manifest=<manifest>；数据默认保留 |
| 创建真实任务、生成 Workspace 并验收预览 | npm run check:task-e2e -- --campaign=<批次>（完整通过后自动清理测试项目） |
配置、架构和运行文档统一从 docs/README.md 进入；数据库与 E2E 清理先读 数据生命周期与安全清理，不要凭表名或创建时间直接删除数据。
项目知识集中放在 docs/。根 README 只放少量入口，完整索引看 文档总览。
| 你要做什么 | 入口 |
|---|---|
| 不知道从哪篇开始 | 文档总览与角色路径 |
想选择模型、关闭 Memory 或理解 .env |
配置、模型接入与可选组件指南 |
| 想系统了解项目 | 文档总览 |
| 想参与开发或判断代码放哪 | 项目结构与分层边界 / 模块边界 |
| 想理解或扩展 Agent 框架 | PI Agent 采用与治理边界 / PI Agent 架构 |
| 想查接口、字段或数据源口径 | API 总览 / 数据字典 / 零售数据接入 |
| 想做经营日报 | 经营情报 / API 总览 |
| 想排障或做发布前检查 | 运行手册 / 故障排查 |
| 想启用登录或配置权限/用量配额 | 用户、权限、配额与会话管理 |
| 想接入、使用或排查用户记忆 | 用户记忆服务接入、使用与效果验证 |
| 想理解 Memory、Knowledge 与 Shop Gate 的联合归因 | 联合上下文与结果归因 |
| 想看后续优先级 | 持续完善路线图 |
如果是第一次接触项目，建议按这个顺序读：
| 阶段 | 文档 | 目标 |
|---|---|---|
| 先找阅读路径 | 文档总览与角色路径 | 按启动、开发、排障、策略、评测、skills 等目标选择阅读顺序 |
| 选择运行拓扑 | 配置、模型接入与可选组件指南 | 选择外部模型网关、官方直连和 Memory 开关 |
| 先建立全局图 | 架构总览 | 知道产品、数据、生成和质量四条主线 |
| 再跑通本地环境 | 基础设施配置 | 拉起数据库、后端、前端和可选观测组件 |
| 理解内部组件 | 内部组件学习指南 | 把页面、服务、数据、Skills、验证和运维串起来 |
| 学会生成链路 | 生成工作空间契约 | 理解 run plan、data、evidence、validation 和 repair plan |
| 学会数据与商品运营 | 零售数据接入 | 理解行为事件、商品池、渠道口径和合成主数据 |
| 学会查接口和字段 | API 总览 / 数据字典 | 知道页面读哪个接口、字段来自哪里 |
| 学会 Skills | Skills 治理规范 | 知道如何修改、发布、打包和验证 skill |
| 看后续优先级 | 持续完善路线图 | 知道哪些事该先做，哪些事暂时不该做 |
文档维护也算项目能力的一部分。改代码时如果改变了页面入口、组件职责、数据字段、环境变量、SQL 或 skill 行为，请同步更新对应文档；具体写法见 文档写作风格指南。
以下内容默认不进入 Git：.env、.env.local、.next/、node_modules/、data/、tmp/、public/uploads/、public/generated/、services/commerce-data/.venv/、services/**/.ruff_cache/。
首次使用需要的 PostgreSQL / TimescaleDB SQL 放在 sqls/。生成工作空间源码和大产物放在 data/projects/，平台数据库只保存索引、状态和摘要。
npm run obs:up 会拉起 Loki、Grafana 和 Grafana Alloy。Alloy 会采集 Docker 容器日志，并读取 tmp/runtime/*.log、评测队列日志和 Next.js dev 日志写入 Loki。Loki 容器端口 3100 默认映射到宿主机 33100；Grafana 容器端口 3000 默认映射到 http://localhost:33012，账号密码来自 .env。运行治理中心的“日志”页会优先展示 Loki 集中日志，同时保留本地文件日志兜底。
主前端不再接入 next-rspack 或自定义 bundler 切换逻辑。npm run dev 直接启动 next dev，Next.js 16 在开发态使用自己的默认链路；项目侧只保留启动前后的工程保护：
scripts/dev/setup-env.js：确保.env、.env.local、data/projects/存在，并写入主前端端口、应用 URL 和预览端口池。scripts/dev/run-web.js：生成稳定 Tailwind CSS，探测降级组件恢复情况，必要时同步 Prisma schema，清理过期 Next dev lock/cache，再启动npx next dev。scripts/build/run-build.js：生产构建入口；默认跳过耗时的 per-route output tracing，需要桌面或 standalone 产物时使用npm run build:standalone。
.env 中的 SHOPGATE_DEGRADATION_MODE 控制组件缺失时的行为：auto 适合本地开发，可选组件缺失时自动降级；strict 适合 CI/生产，必需组件缺失会失败；offline 会跳过多项可选外部组件探测，优先使用本地兜底。只关闭一个组件应使用其 ENABLED=0，例如不启用 Memory 使用 SHOPGATE_MEMORY_ENABLED=0，不要为了关闭单一组件切到 offline。完整开关见 配置指南。