← 返回演示门户
系统设计导读 →
交付流程 · 从客户需求到上线
六个必须阶段，每个阶段都写清输入、动作、产出与验收判据；
四个可选阶段按客户现状取舍，不做无谓的定制。
先看全局，再逐页展开每一步
问清谁用、答什么、数据在哪，把问题归到 9 类能力，划定验收问题集。
起独立实例，配模型接入，跑自检与冒烟。一条命令起全套。
清洗分块、建语料清单，需要分权就配规则目录，跑评测看命中率。
按业务分工拆智能体，写意图路由与节点编排，配容错策略。
令牌作用域收口、跨域白名单、限流；前端不留主令牌。
拿最终配置跑验收问题集，逐题核对答案与出处，跑九关回归。
判据是客户现状，不是"能不能做"：
| 阶段 | 什么时候需要 |
|---|---|
| 接口对接 | 已有业务系统需要被查询 |
| 嵌入客户系统 | 要在客户界面里出现 |
| 通知与工作流 | 需要主动提醒或自动处置 |
| 交付与运维 | 客户要自行运维或离线安装 |
都不需要时，交付就停在第六步；由我们托管则 D 也可跳过。
先问清三件事，再谈技术
客户的口头描述、现有文档、想解决的问题。
多数客户一开始说的是"想要个能回答问题的机器人"， 这不够 -- 要问出下面三件事。
《需求确认单》，含四项：
常见坑：客户说"随便先做个看看"就动手 -- 这是返工的最主要来源。 宁可多花半天问清，也不要用两周做错方向。
一条命令起全套，自检说了算
AK_LLM_BASE_URL 与两个档位ak doctorak smoke：健康检查 + 能力清单 + 一轮真实对话/healthz 全绿的输出ak doctor 的自检报告/healthz 返回 ok + 版本 + 租户 + 能力清单ak doctor 0 个 FAILak smoke 一轮真实对话拿到答案（不是只通网络）常见坑：模型起不来多半是显存不够或上下文设太大。
ak doctor 会直接报出原因，不要靠猜、也不要只 curl 一下端口就认为通了。
语料决定答得准不准
acl.filter 规则目录（hr / finance / ops）分权用目录实现：hr/ finance/ ops/
公开/，未授权目录对相应身份不可见。
| 指标 | 门槛 |
|---|---|
| 可答题通过率 | ≥ 85% |
| 出处命中率 | ≥ 85% |
| 陷阱题失败数 | 0（不编造） |
任一不达标，rag_eval 退出码非零，可直接进 CI 当门禁。
常见坑：不达标的题要逐条归因 -- 是语料没覆盖，还是检索没命中。 这两类的解法完全不同：前者补语料，后者调分块或换检索方式。
一个角色一个智能体
agents.yaml：意图路由 + 节点编排| 节点类型 | 作用 |
|---|---|
knowledge.vector | 语义检索，问法不同也能命中 |
knowledge.keyword | 关键词检索，无嵌入依赖、始终可用 |
database.sql | 只读业务库，走参数化模板 |
notify.webhook | 把结果推给责任人 |
llm | 生成答案，可指定模型档位 |
同一套提示词挂两个智能体、只换模型档位， 就能做 A/B 对比，不用改内核。
agents.yamlagent_id 直连可用常见坑：兜底智能体的关键词别放"怎么 / 如何"这类高频泛词， 否则会把专业问题抢走。经验是只放平台级词（如"制度 / 规定"）。
最容易被跳过、代价又最大的一步
这一步不用等联调，配置改起来最便宜，越早做越好。
这三条都是可执行的门禁，任一不达标即非零退出码， 能直接挂到 CI 上当回归。
常见坑：把主令牌写进前端"方便调试"，然后忘了删。
这类问题在代码评审时看不出来，只有跑 check-leak 才暴露。
正确做法是前端永远拿不到主令牌。
用最终配置跑，中途跑等于白跑
报告是 markdown，可以直接贴进交付文档， 不用再手工整理数字。
| 指标 | 门槛 |
|---|---|
| 可答题通过率 | ≥ 85% |
| 出处命中率 | ≥ 85% |
| 陷阱题 | 不编造（失败数 0） |
| 遗留问题 | 逐条有处理方式 |
说明：陷阱题全对只说明"没编造"，不代表语料完整； 所以两类指标要分开看，不能互相顶替。 常见坑：拿中途配置跑评测，结论到上线就不成立 -- 必须用最终版本。
接口对接与嵌入客户系统
做什么
产出与验收
做什么
产出与验收
通知与工作流、交付与运维
做什么
产出与验收
做什么
doctor + provenance（实例溯源）产出与验收
哪些能并行、哪些卡下一个
| 阶段 | 首家 | 复用 | 压缩点 |
|---|---|---|---|
| 1 需求澄清 | 1.5 天 | 0.5 天 | 复用问题集与确认单模板 |
| 2 环境与部署 | 1 天 | 0.25 天 | 一条命令起全套 |
| 3 知识库构建 | 2 天 | 1 天 | 语料处理脚本化 |
| 4 智能体编排 | 2 天 | 0.5 天 | 场景包复用 |
| 5 权限与安全 | 0.5 天 | 0.25 天 | 规则模板化 |
| 6 联调与验收 | 1.5 天 | 0.5 天 | 问题集与门禁自动化 |
| 合计 | 约 8.5 天 | 约 3 天 | 复用约为首家的 30% |
差异越小（同行业、同能力组合），复用交付越接近纯改值。
| 关系 | 说明 |
|---|---|
| 3 与 4 可并行 | 语料收集慢，等它时可先写编排骨架 |
| A 与 3 可并行 | 接口对接与知识库互不依赖 |
| 5 越早越好 | 权限配置改起来最便宜，不必等联调 |
| 6 必须最后 | 要拿最终配置与最终语料跑，中途跑等于白跑 |
| D 在验收后 | 打包内容要冻结，否则包与验收版本不一致 |
看这个阶段的输入是否齐备。输入没齐就动手，产出一定返工。
每条都有可执行的检查，不靠人工确认
| 门禁 | 检查内容 |
|---|---|
ak doctor | 镜像、容器、租户配置、交付文件完整性（逐文件 SHA256） |
check-tenant | 租户配置交给内核自己判定合法性 |
rag_eval | 可答题、陷阱题、出处命中率三项同时设门槛 |
check-leak | 客户侧凭据是否会随日志 / 响应 / 前端外泄 |
provenance | 这台机器装的是哪一版、内容指纹多少，可离线核验 |
security-sweep | 35 项安全自查（越权、伪造、穿越、限流、分权） |
verify-public-access | 22 项公网验收（证书、跳转、Cookie、端口暴露） |
audit-consistency | 仓库与线上逐文件比对，防"改了没同步" |
| 指标 | 门槛 | 本轮实测 |
|---|---|---|
| 可答题通过率 | ≥ 85% | 95.5%（63/66） |
| 出处命中率 | ≥ 85% | 98.5% |
| 陷阱题失败数 | 0 | 0 |
| 环境自检 | 0 FAIL | 0 FAIL |
| 安全自查 | 35 项全过 | 全过 |
这些数字是跑出来的，不是估的。交付文档里直接贴
rag_eval 生成的 markdown 报告即可。