← 返回演示门户
系统设计导读
架构约束 · 定制深度 · 交付形态（可打印 / 可投屏）
面向多个中小型企业交付智能体系统 —— 哪些是冻结主干，哪些是可定制部分
层内逻辑可配置，层间契约永不改
读法：四层竖着站，箭头只朝下；部署层横向包住所有层，提供打包、配置、可观测、双模式开关。红框是硬红线——违反任一条，多客户复用就崩。
95% 的客户差异停在前两档
升降规则 能停在 D1 就不下 D2；每下一层成本约 ×3。D3 只允许"新增实现"，不允许"修改已有实现"。
主干一份，客户 N 个
蓝色 = 必填维度
每张卡片对应配套文档里的一组规则（共 67 条，字段：维度 / 配置项 / 取值 / 默认值 / 影响范围）。客户提需求时，先把它翻译成这十个维度的取值，再动手。
哪些要改、哪些可以直接不动
| 改动对象 | 仓库管理 warehouse |
图书馆管理 library |
咨询问答 qa_consult |
文件解读 doc_reading |
说明 |
|---|---|---|---|---|---|
| tenant.yaml | 必改 | 必改 | 必改 | 必改 | 主体/行业、风格、术语、权限合规、配额——四类场景都跑不掉 |
| agents.yaml | 必改 | 必改 | 必改 | 必改 | 引用场景包、绑定工具、写降级链 |
| datasources.yaml | 必改 5–8 条 SQL | 必改 馆藏/借阅/规则 | 可留空 | 不用 | 只有涉及结构化查询的场景才需要 |
| prompts/<租户>/ | 必改 | 必改 | 必改 | 必改 | 角色设定、术语、拒答口径 |
| .env | 必改 | 必改 | 必改 | 必改 | 数据源 DSN、对象存储、模型、密钥占位 |
| 场景包本身 | 首建 1 次 | 首建 1 次 | 首建 1 次 | 首建 1 次 | 平台资产，进 config/scenarios/，之后所有客户复用 |
| 写新代码 | 可能有 WMS 接口 | 可能有 ILS 接口 | 无 | 可能有 OCR |
只有"要接现有能力做不到的外部系统"时才写插件 |
| 以下四项四类场景完全一致：一律不动 | |||||
| 四层主干代码 | 不动 | 不动 | 不动 | 不动 | src/** 一行不改 |
| config/base/* 与 deploy/** | 不动 | 不动 | 不动 | 不动 | 能力默认值、部署工件、健康检查 |
| CLI / 管理台 / 错误码 | 不动 | 不动 | 不动 | 不动 | 工具链与运维面 |
| 本地 / 线上切换机制 | 不动 | 不动 | 不动 | 不动 | 只靠 AK_ENV 与 .env 文件 |
五元组 → 决策树 → 定档 → 选包/造包
单位：人日
| 工作项 | 首次 | 复用 |
|---|---|---|
| 场景包 pack | 新建 1 次 | 0（直接引用） |
| 数据源对接 | 逐个字段确认 | 换视图名即可 |
| 语料处理 | 清洗 + 分块 + 建清单 | 同流程，量相当 |
| 提示词 | 从零写 | 改主体词与语气 |
| 权限与安全 | 按需求配 | 规则模板化 |
| 评测与验收 | 重新出题 | 问题集复用 |
复用率取决于相似度，不是取决于"我们想省"： 同行业 + 同能力组合时最接近纯改值；跨行业则 pack 要重造，省不了那么多。
10 个仓库分开维护，谁改谁负责
先定拓扑再动工
仓库拓扑 先定拓扑再动工：平台侧四个主仓（core / web / sdk-js / deploy）加每客户一个配置仓，一次规划到位。其余仓按需创建、互不影响，避免以后拆仓牵动 CI 与镜像构建路径。
开箱即用 三条命令、十分钟、零外网：
| 步骤 | 命令 | 说明 |
|---|---|---|
| 1 | git clone .../agentstack-deploy.git | 只拉交付仓，其余仓按 BOM 版本拉镜像，不必全量克隆 |
| 2 | Copy-Item .env.example .env.local | 全流程只需改这一个 env 文件 |
| 3 | docker compose -f compose.core.yml -f compose.local.yml up -d | 启动顺序：postgres 健康 → migrate 一次性作业 → api 健康 → web 健康 |
| ✓ | 打开 http://localhost:8080 | 自带 demo 租户 + 20 份样例语料 + demo 智能体，开箱即可对话 |
| 离线 | ak pack offline --tag acme-1.0.0 | 内网客户用：镜像 tar + compose + 安装脚本 + SHA256 校验 |
可嵌入 五级嵌入 + 前后端分离，唯一耦合面就是那份 API 契约：
唯一耦合面是 API 契约
同一套内核，能力由配置启用
内核提供 9 类标准化能力。哪一类在哪个实例启用，完全由配置决定——不启用就不加载，也不必改代码。三列分别对应三套真实运行的实例。
| 能力 | 层级 | 职责与安全边界 | 生产实例 demo2 |
对话演示 demo-demo |
能力演示 demo-caps |
|---|---|---|---|---|---|
| llm.openai | core | 对话主模型，OpenAI 兼容接口；凭据只在内核容器 | 启用 | 启用 | 启用 |
| embedding.openai | core | 文本向量化（bge-m3 / 1024 维），供向量检索使用 | 启用 | 启用 | 启用 |
| knowledge.vector | core | 向量检索（余弦 top_k）；嵌入异常时回落关键词检索 | 启用 | 启用 | 启用 |
| knowledge.keyword | core | 关键词检索（中文 2 字滑窗），不依赖任何外部服务 | 启用 | 启用 | 启用 |
| ingest.file | optional | 文件解析：docx / xlsx / 文本层 pdf / md / txt / csv，上传即入库 | 启用 | 启用 | 启用 |
| tool.http | optional | 受限 HTTP 调用：域名白名单 + 超时 + 响应截断 | — | 启用 | 启用 |
| database.sql | optional | 业务库只读：只读事务 + 表白名单 + 单语句 + 超时 + 行数上限 | — | — | 启用 |
| notify.webhook | optional | 通知推送（企微 / 钉钉 / 飞书 / 通用），带重试与最小间隔限流 | — | — | 启用 |
| knowledge.external | optional | 按标准契约调用客户已有知识库服务，不搬迁数据 | — | — | 启用 |
依赖关系由内核在启动期校验：例如向量检索依赖嵌入能力，配了向量却没配嵌入，服务会直接启动失败并给出原因，而不是运行到查询时才报错。
同一套代码、不同配置
同一套代码起三个实例，但它们的用途不同：对外演示只挂其中两个，第三个用于验证生产形态。
| 实例 | 租户 | 门户入口 | 用途 |
|---|---|---|---|
| 能力演示 | demo-caps |
接入门户 | 9 类能力全开、6 个智能体。门户里绝大部分演示页（客户知识库、语料分权、业务库、上传解析、通知推送、套餐、鉴权等）都走它。 |
| 对话演示 | demo-demo |
接入门户 | 6 类能力、3 个智能体。门户首屏的「智能问答」与「多租户隔离」用它。 |
| 生产样板 | demo2 |
不接门户 | 以真实客户形态长期运行（独立数据库、7 份语料、单智能体），用于验证"能上生产"：环境自检、交付完整性、问答评测都在它上面跑。 |
把三者放在同一台机器上是为了演示与被验证；正式交付时按"一个客户一套实例"部署，实例之间不共享。
每一条都有可执行的检查，不靠人工确认
| 门禁 | 检查内容 |
|---|---|
doctor 环境自检 | 镜像、容器、租户配置、交付文件完整性（逐文件 SHA256 比对） |
check-leak 泄漏门禁 | 客户侧凭据是否会随日志、响应、前端外泄 |
provenance 实例溯源 | 这台机器装的是哪一版、内容指纹是多少，可离线核验 |
rag_eval 问答评测 | 可答题、陷阱题、出处命中率三项同时设门槛 |
security-sweep | 35 项安全自查（越权、伪造、穿越、限流、分权） |
verify-public-access | 22 项公网验收（证书、跳转、Cookie、端口暴露） |
真开页面、真点按钮，覆盖单测与接口测试够不到的一层。
| 脚本 | 覆盖 |
|---|---|
| 全量回归 | 13 个页面渲染 + 能力真跑 + 视觉基线 |
| 手机响应式 | 3 种机型 x 16 页：溢出、字号、可点区域 |
| 多页面架构 | 门户与独立页共用同一份逻辑 |
| CSP 回归 | 安全策略不挡自己的脚本与同源框架 |
| 引用渲染 | 引用可点开、外部片段与内部全文两条路径 |
这些门禁的价值在于可重复执行：换一台机器、换一个客户环境， 跑同一套脚本就能得到同一结论，不依赖谁的经验或记忆。
全篇收束
四层骨架与层间契约一次定死；客户的差异全部落在配置层。 这样多客户复用才成立，而不是每家改一次代码。
改值 / 改配置 / 引用或新建 pack / 新增能力实现。 越往下越贵，所以能停在 D1 就不上 D2，95% 的客户停在前两档。
六个必须阶段 + 四个可选阶段，每步都有可执行的判据。 质量不靠人工确认，靠门禁脚本给结论。
五级嵌入从 HTTP 到渠道机器人，唯一耦合面是那份 API 契约。 客户按"愿不愿意改前端"选一级即可。
| 项 | 数值 | 说明 |
|---|---|---|
| 能力类型 | 9 类 | core 与 optional 两层 |
| 自动化测试 | 722 项 | 内核 625 + 交付 41 + SDK 56 |
| 对外契约 | 5 份 | OpenAPI / SSE / Schema / 错误码 / 外部知识库 |
| 运维脚本 | 34 个 | 自检、溯源、打包、备份、门禁 |
| 运行实例 | 3 套 | 同上代码、不同配置 |
设计文档（总纲 2105 行 / 四部 / 30 项定案）配套本页， 供工程执行使用。