66 · 诉求对照:场景应用与生产就绪
性质:非方案(对照记录)。状态:✅ 2026-11-07 按代码核对。 日期:2026-11-07。 代码落点:正文各节点名文件与行号;本文不新增代码。 用途:把两组外部诉求——应用侧五句与平台工程十项——逐条对到 tako 的现状与缺口上。不作施工真源:任何一条要落地,须另立方案篇(
doc/NN),并按「契约 → 存储 → 实现」的 loop 走。 合并记录:原doc/66(应用侧)与doc/67(平台侧)于 2026-11-07 合并为本篇;重叠项只写一次,平台侧对 Trace / Replay / 灰度 / 成本只补平台增量。
0. 两组诉求与总结论
0.1 应用侧五句
- 如何展示 Trace、Replay、灰度与成本治理;
- 不允许人工审核的资金、医疗、法律决策;
- 建立证据链:记录引用来源、工具调用、分析过程和执行 Trace,保证结果可追溯、可审计;
- 任务编排:完成信息搜集、交叉验证、结构化分析、报告生成;
- 可追溯与审计:记录数据来源、引用依据、工具调用和执行 Trace。
0.2 平台工程十项
- Docker Compose 部署方案;
- Model Gateway 模型网关;
- Redis、PostgreSQL、VectorDB 基础设施;
- Trace、Metrics、Monitoring 可观测性;
- Replay 回放调试;
- Prompt / Model / RAG / Tool 版本管理;
- Feature Flag 功能开关;
- 灰度发布与回滚;
- 成本治理;
- 上线 Runbook。
0.3 总结论
应用侧:证据链(第 3、5 句)是 tako 的地基,数据已经落库,缺的是拼成一份能交付的审计面;展示与治理(第 1 句)成熟度参差——Trace 与用量账本已有、Replay 只有崩溃续跑那一层、灰度是零;决策边界(第 2 句)与编排语义(第 4 句)是两条产品线,前者只能靠「工具面里没有那个能力」来保证,后者缺任务图。第 3 与第 5 句内容高度重叠,本文合成一节讲。
平台侧:有 3 项、半有 3 项、无 4 项。 有:Trace、用量账本、PG / Redis 底座;半有:模型目录(不是网关)、版本号(只有一个自增字段)、Replay 的过程数据(没有回放工具);无:Docker Compose、Metrics / 健康检查 / 告警、运行时 Feature Flag、灰度与回滚、上线 Runbook(成本治理是「有账本、无金额」)。
这十五项不是并列 checklist,依赖顺序是:部署与健康面 → 运行配置快照 → 开关 / 灰度 / 回滚 → 成本报表与 Runbook。Runbook 是前面几层的结果,不是最后一个独立任务。
1. 应用侧
1.1 Trace / Replay / 灰度 / 成本治理
这四个词常被并成一句,但成熟度完全不同,必须拆开说。
Trace:已落地,缺展示入口
引擎按 OTel GenAI 语义发 run 根 span、每枪模型调用的 chat 子 span、每次工具执行的 execute_tool 子 span(internal/runengine/journal.go:104),以及召回、折叠、准入、定稿等内部步骤 span,传输走 OTLP,可双发 CozeLoop / Langfuse。机制与字段清单见 doc/54。
缺的是给人看的入口:web/src 里没有任何 trace 相关代码;今天要看 trace,只能去外部观测平台,或者拉 frames / runlog 自己按 eventOffset 拼时间线。要「展示」,不需要新建采集——把已有 span 或 runlog 投影成一个 GET /api/runs/:id/trace 就够。
一个前提:模型入参出参这类内容属性由环境开关控制,未设时默认不写(internal/observability/trace.go:163 的 parseCapture)。审计要看「模型当时看到了什么」,必须把这个开关打开;开发库的 .env 已设。
Replay:必须拆成两层,否则会承诺做不到的事
第一层是崩溃续跑的真重放。 run_journal 是这场 run 的崩溃账本;进程死后续跑时,replayJournal(internal/runengine/journal.go:171)把已完成轮次规范重放成模型输入、turn 与定稿原料。但账本终态即删(internal/runengine/pgstore.go:718),所以它只服务「在途恢复现场」,不是历史回放。
第二层是历史复现。 靠 runlog_entries 的全序记录(user / assistant / tool_call / tool_result)重建「当时看到了什么、调了什么、回了什么」。这层能回答「过程可复原」,但不能承诺「重跑得到同一答案」——doc/56 §4.9 的实测里,同一 harness、同一批题隔一小时重跑,逐题分歧率 28%,比两臂之间的差异还大。产品话术应写「可复原过程」,不写「可重放结果」。
平台视角再补一句:没有单独的「失败 run 快照」留存,也没有一键回放工具。课程里「保存输入 / 上下文 / 工具结果 / Agent 状态」四项,前三项有过程记录,第四项(可重入的 Agent 状态)本来就不存在——tako 的挂起靠 run_questions 行与 journal 重放,不靠可达的 checkpoint。
灰度:代码里是零
internal/ 与 web/ 里查不到 canary、feature flag、按比例放量这类机制。今天能借的轴只有租户粒度:
- 租户自己的模型 ref 与密钥,按
tenant + ref + 配置版本解析(internal/runengine/tenantmodel.go:29); - 租户 agent 规格:
tenant_agents行里带Spec(提示词)、ModelRef、ToolPolicy、SkillPolicy(internal/runengine/product_api.go:1360一带)。
所以真要做,最小形态是「按租户 / 按 agent 切模型或提示词版本」,不是按流量百分比。前提是先把「配置版本」从缓存键哈希升级成有历史、可回滚的一等对象——现在 configVersion 只算哈希,没有版本记录,也没有回滚动作。按比例灰度今天没有落点。
成本治理:有账本与日封顶,没有金额与预算语义
已有的:
- 每枪模型调用发一条
usage帧,页面据此显示 token 用量(doc/27); tenant_usage_daily按租户按天累计 token(internal/runengine/scope.go:202);- 租户有
daily_tokens、并发 run 数、子代理数、存储字节四个上限(internal/runengine/scope.go:178一带); - 日 token 配额在 run 起手拦一次,超了把这场 run 直接收成
error(internal/runengine/worker.go:567一带)。
没有的:
- 价格表——token 没有换算成钱,也没有「这次 run 花了多少」的归因;
- 按 run / 按会话的预算与告警;
- 超配额的明确语义:现在是 run 起手一次判断,中途不会停,用户也拿不到「哪一步超了、还剩多少」的解释。
平台侧再补一句:tenant_usage_daily 是全局唯一账本,没有环境维度、没有供应商 / 模型维度。所以「成本报表」即使做了页面,也只能按租户按天给一个 token 数——换算成钱还缺价格表,按模型归因还缺「每枪用哪家」的汇总。
结论:能做「用量看板 + 粗粒度日封顶」,做不了「成本归因 / 预算告警」。
1.2 不允许人工审核的资金、医疗、法律决策
这句话有两种读法,答案相反,必须先拆开。
读法一:这类决策必须有人复核。 tako 只有「模型主动问人」:ask_user 追问与 submit_plan 方案审批,都先落 run_questions 一行再等人答,崩溃后续跑能接回现场(doc/47)。但没有「框架强制审批」:进计划模式是模型自己判断后调 enter_plan_mode(internal/runengine/plangate.go:1 的注释),框架拦截式审批已在 2026-10-23 拍为不做(doc/16 第 53 行的「不在欠账里」段)。所以做不到「这类决策一定过人」的硬保证。
要真保证,只能让工具面里不存在那个能力:不接支付、下单、开具、签章这类有外部副作用的工具,只给只读凭证。提示词保证不了——doc/16 同一段也写了这条边界:越界靠沙箱与围栏硬挡,不靠模型自觉。
读法二:这类决策不允许人审,要全自动。 那就要关掉 plan gate,并接受没有任何硬保证;这与 tako 当前的设计方向相反,不建议。
对这类场景,tako 现实的位置是:取证、出草案、留证据,执行那一步交给人或外部系统。
1.3 证据链与可追溯审计(对应第 3、5 句)
已经有的:
- 工具调用与结果:runlog 按 seq 全序记 user / assistant / tool_call / tool_result,帧与历史按
toolCallId配对(doc/59),子代理行带 agent 归属。这是「谁在什么时候、拿什么参数、调了什么、得到什么」的原始记录。 - 数据来源:
web_search的结果全文落<workspace>/.tako/search/<runId>_<n>.md,工具回执只给来源、条数、路径与 token 数(internal/runengine/websearch.go:5);web_fetch全文落.tako/fetch/(doc/57);read_file与bash的输出按 doc/58 留档。 - 执行过程:实时帧流(Redis
runlive)+ trace span(跨 run 可检索)+run_tasks看板(模型自己的计划与状态,doc/41)。 - 审计表:
audit_log记成员、角色与平台管理员变更(internal/runengine/members_store.go:13)。
缺的三条:
- 没有「结论 → 来源」的绑定。 来源是工具记录,不是回复里的脚注;模型在正文写不写 URL、写不写「未能查证」,靠
web_search描述段里的提示词,程序不代贴。结果能「可查」,但不能「每条断言自动指回一个来源字节」。 - PII 脱敏与审计保真打架。 工具回执在统一出口先打码再返回(
internal/runengine/pii.go:195),所以落 runlog 的是打码版;用户原话落库是原文,只在进模型输入时打码(toSchemaMessages一路)。也就是说:工具侧原始值不留存,用户侧原文留存。这是设计选择,不是 bug;但资金 / 医疗 / 法律审计需要「哪些字段必须保真、保真存在哪、谁能看」的分层,现在没有。 - 没有导出面。 审计导出已随商业化那一档拍为不做(doc/28 §15)。今天只能在库里或页面上看,交不出一个可交付的审计包。
这三条里,1 和 3 是工程量,2 是必须由你拍板的取舍。
1.4 任务编排:搜集 → 交叉验证 → 结构化分析 → 报告
积木齐了,编排语义没齐:
- 信息搜集:
web_search/web_fetch/read_file/bash,加上 researcher 子代理(agents/researcher.md,工具护栏见 doc/26)。 - 交叉验证:没有专门机制。靠模型多调几次工具、自己在正文里比对;看板能记步骤,不会替你判断「两个来源冲突」。
- 结构化分析 / 报告生成:
run_tasks四把工具(internal/runengine/tasktools.go)+ coder 子代理(doc/23)+ 文件工具写产物,终稿落 runlog。 - 缺的是任务图:现在是一条主链 + 进程内派子代理,没有分支、汇合、依赖、失败重试,也没有 A2A / agent card。要做,最小改动是把
run_tasks从「清单」升级成「带依赖的任务」,而不是引入一个编排框架——这和 doc/41 的既有形态是同一条线。
2. 平台工程侧
2.1 部署与基础设施
Docker Compose:没有
仓库里没有 Dockerfile、docker-compose.yml、CI workflow。今天的启动方式是 scripts/dev.sh(本地起 PG / Redis / 引擎 / Vite)或 go run ./cmd/yktako。生产部署的计划(git tag + GitHub Actions + SSH + 1Panel / OpenResty)只记在本地部署笔记与 secrets/ 里,不在 doc/,也不在仓库脚本里。
要凑出一个 Compose,进程清单其实很短:引擎二进制 + web/dist 静态文件 + PG + Redis,共四项。但有三个坑不能漏:
- workspace 必须是共享卷:
cmd/yktako/main.go:225一带的启动检查会在检测到上次使用主机不同时打警告——多副本不共享盘,文件就各读各的。 - 引擎不托管前端:
server.go里没有静态文件路由,web/dist要由 Web 服务器(Nginx / OpenResty)另挂。 - PG 不是裸 PG:开 RAG 时要求
pg_search扩展、shared_preload_libraries预加载和vector依赖;缺一个引擎就 fail fast 退出(见internal/runengine/dialogue.go:56一带的报错文案)。
Model Gateway:有「目录 + 客户端工厂」,没有网关服务
已经有的三层:
internal/config/provider-catalog.json:厂商目录(id / 协议 / baseURL / 模型清单 / vision 标记);internal/config/resolve.go:把TAKO_MODEL、TAKO_PROVIDER_<NAME>_API_KEY、TAKO_PROVIDER_<NAME>_BASE_URL解析成厂商 + 模型 + 密钥;internal/runengine/tenantmodel.go:按tenant + ref + 配置版本建并缓存客户端;租户密钥用seal2(TAKO_DATA_KEY)加密落库,平台进程里的*_API_KEY会被从租户环境里剔掉。
它解决的是「用谁家的 key、走哪个模型」,属于客户端工厂,不是网关:没有统一入口、没有路由 / fallback / 限流 / 熔断 / 重试策略,也没有按模型累计成本与延迟的汇总面。GET /api/dev/model/resolve 只是把解析结果打出来给人看。
要往「网关」靠,最小增量不在部署一个代理进程,而在现有调用包装层上补 fallback 与预算;前提是先把「这一枪用的模型 ref、参数、供应商」记成可汇总的运行事实。
Redis / PostgreSQL / VectorDB:两个半
- PostgreSQL 是唯一真源:会话、run、模型消息、runlog、看板、提问、技能、用量、审计都在 PG。建表走
AutoMigrate(internal/runengine/pgstore.go:499注释写明「dev 迁移方式,无迁移文件」)。 - Redis 只存两个键:
tk:runlive(帧列表)与tk:runepoch(接管令牌),见internal/runengine/redisstore.go。它不是队列:go.mod里没有 asynq,worker 是进程内 goroutine,run 的并发靠 PG 上的部分唯一索引与租约。 - VectorDB 没有独立组件:召回线用
pg_search的 BM25(internal/runengine/dialogue.go:187),vector扩展只是安装pg_search时的依赖;代码里没有 embedding 生成,也没有向量相似度查询。
所以依赖清单应如实写成:PG(含 pg_search / vector 扩展)+ Redis(临时态)+ 共享 workspace,不是课程里默认的「Redis + PG + 独立 VectorDB」三件套。
2.2 可观测性:Trace 有,Metrics / Monitoring 是零
Trace 见 §1.1:run 根 span、每枪 chat、每次 execute_tool、内部步骤 span 都已落地,OTLP 双发;内容属性默认不写,靠 OTEL_INSTRUMENTATION_GENAI_CAPTURE_CONTENT 打开(internal/observability/trace.go:163)。
Metrics 与监控面是零:没有 /metrics、没有 Prometheus 客户端、没有健康检查端点、没有告警规则;日志是 stdout 的 log.Printf,靠外部收集。课程列的业务指标、模型指标、Agent 指标、安全指标,今天没有一条有现成读数。
最小形态是两层,不要和 trace 重复采集:
- 健康面:
/healthz(PG / Redis 探活)+ 版本 / 构建信息; - 指标面:进行中 run 数、失败率、P95 延迟、token 消耗、工具失败率、配额命中次数。数据大多已在 PG / 用量账本里,缺的是暴露口径。
2.3 版本、开关、灰度与回滚
版本对象:碎片化,且缺「运行配置快照」
| 对象 | 今天在哪 | 有没有版本 |
|---|---|---|
| 系统提示词 | 代码常量(internal/config/model.go:18) |
跟二进制走 |
| 计划模式提示词 | 代码常量(internal/runengine/plangate.go) |
跟二进制走 |
| Agent 规格 | agent_defaults / tenant_agents 行 |
agent_defaults.Version 自增;tenant_agents 无版本列 |
| 模型 | 模型 ref + 厂商目录文件 | 无版本对象 |
| 工具 | 二进制里的注册代码 | 无版本元数据 |
| 技能 | skill_rows |
无版本列 |
| RAG | 派生索引 dialogue_chunks |
无策略版本;可 --rebuild-dialogue 重建 |
agent_defaults.Version 只在导入时自增(internal/runengine/product_store.go:238 / :251),只增不留旧值,没有历史表,也没有回滚动作。
更关键的是:runs 行不存模型 ref,也不存提示词 / 工具集 / 技能集的版本(internal/runengine/pgstore.go:46 的字段清单)。模型 ref 只散落在 runlog 的 assistant / tool 行的 Model 列(pgstore.go:109)。一场 run 结束后,无法从 run 本身回答「当时用的是哪版提示词、哪些工具、哪个模型参数」。这是版本管理与回滚共同的缺口——没有快照,回滚就没有对象。
Feature Flag:只有启动期环境开关
全仓没有运行时 flag。能改的只有启动期环境变量:TAKO_MODEL、TAKO_MEMORY_EXTRACT / TAKO_MEMORY_RECALL / TAKO_RAG、OTel 内容开关、各类 TTL 与配额默认值。改一个要重启进程;没有按租户 / 用户 / 比例 / 风险等级的开关,也没有管理面。
注意别把「env 开关」改名叫 flag 就算完成:真 flag 要能不重启生效、有归属、有变更记录,还要能回答「这个租户现在拿到的是哪一档」。
灰度发布与回滚:没有,且有一个硬缺口
没有 canary、按比例放量、A/B 观察。唯一可用轴是租户粒度配置(tenant_settings 的模型配置、tenant_agents 的规格),但改了就生效,没有观察窗口,也没有回滚点。
agent_defaults.Version 只增不留旧值,回滚等于手抄旧内容;部署回滚等于换二进制 tag。
最硬的一处不是配置回滚,而是在途 run:全仓没有 signal.Notify / 优雅停机逻辑,重启会直接把在途 run 打断。接回依赖租约过期后的显式 POST /api/runs/:id/resume,没有启动扫描自动接管。所以「可回滚」必须先回答:回滚那几分钟里正在跑的 run 怎么办——是等在途跑完、拒绝新 run(drain),还是允许被打断后由人手动 resume。今天没有答案。
最小形态:先把配置写入改成「新增版本行 + 切换指针」,再做按租户 / agent 的开关;停机先补 drain 语义,再谈灰度。
2.4 上线 Runbook:没有
仓库里最接近的是 scripts/dev.sh 与 scripts/acceptance/README.md 的「怎么起一个隔离引擎」。真正的上线手册是零:依赖版本与安装、必填密钥、模型密钥、数据库迁移语义、构建与发布、健康检查、回滚步骤、故障处置、备份策略,都不在仓库。
Runbook 不是单独写一篇文档就完,它依赖两层前置:
- 健康面(§2.2):没有探活,Runbook 的「确认服务起来了」只能靠手 curl;
- 停机语义(§2.3):没有 drain,Runbook 的「发布 / 回滚」写不出安全步骤。
3. 依赖顺序(只标顺序,不是方案)
- 部署与健康面:Compose 四件、共享 workspace、PG 扩展与密钥准备、
/healthz与基础指标。 - 运行配置快照:每场 run 记住当时的提示词 / 模型 / 工具集 / 技能集版本——版本管理与回滚的对象。
- 运行时开关与灰度:flag 能不改进程生效,再按租户 / agent 放量,才有「回滚到上一版」可言。
- 成本报表与 Runbook:前两层落地后,报表才有归因维度,Runbook 才有可写的确认与回退步骤。
4. 收尾:真正要补的五件事
- 把已有账本投影成展示面:trace / 成本 / 审计的页面或接口,读现成的 span、runlog、
tenant_usage_daily,不新增采集。 - 把配置版本做成可回滚的对象:这是灰度与版本管理唯一的前置,也是今天最实的缺口。
- 给 PII 与审计保真分层:哪些字段必须保真、保真存在哪、谁能看、保留多久——这是取舍,不是工程量。
- 补部署与健康面:Compose、共享 workspace、
/healthz与基础指标,让「服务是否起来」有机器答案。 - 补停机与回滚语义:先有 drain,Runbook 才能写「发布 / 回滚」的安全步骤。
五件事里,前两件是「把已有数据摆上桌」,第三件需要单独拍板,后两件是平台工程的入场券。都不在本文施工;要动哪条,先立方案篇、写 todos、过契约拍。