tako 文档 GitHub

66 · 诉求对照:场景应用与生产就绪

性质:非方案(对照记录)。状态:✅ 2026-11-07 按代码核对。 日期:2026-11-07。 代码落点:正文各节点名文件与行号;本文不新增代码。 用途:把两组外部诉求——应用侧五句与平台工程十项——逐条对到 tako 的现状与缺口上。不作施工真源:任何一条要落地,须另立方案篇(doc/NN),并按「契约 → 存储 → 实现」的 loop 走。 合并记录:原 doc/66(应用侧)与 doc/67(平台侧)于 2026-11-07 合并为本篇;重叠项只写一次,平台侧对 Trace / Replay / 灰度 / 成本只补平台增量。

0. 两组诉求与总结论

0.1 应用侧五句

  1. 如何展示 Trace、Replay、灰度与成本治理;
  2. 不允许人工审核的资金、医疗、法律决策;
  3. 建立证据链:记录引用来源、工具调用、分析过程和执行 Trace,保证结果可追溯、可审计;
  4. 任务编排:完成信息搜集、交叉验证、结构化分析、报告生成;
  5. 可追溯与审计:记录数据来源、引用依据、工具调用和执行 Trace。

0.2 平台工程十项

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、按比例放量这类机制。今天能借的轴只有租户粒度:

所以真要做,最小形态是「按租户 / 按 agent 切模型或提示词版本」,不是按流量百分比。前提是先把「配置版本」从缓存键哈希升级成有历史、可回滚的一等对象——现在 configVersion 只算哈希,没有版本记录,也没有回滚动作。按比例灰度今天没有落点。

成本治理:有账本与日封顶,没有金额与预算语义

已有的:

没有的:

平台侧再补一句: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 句)

已经有的:

缺的三条:

  1. 没有「结论 → 来源」的绑定。 来源是工具记录,不是回复里的脚注;模型在正文写不写 URL、写不写「未能查证」,靠 web_search 描述段里的提示词,程序不代贴。结果能「可查」,但不能「每条断言自动指回一个来源字节」。
  2. PII 脱敏与审计保真打架。 工具回执在统一出口先打码再返回(internal/runengine/pii.go:195),所以落 runlog 的是打码版;用户原话落库是原文,只在进模型输入时打码(toSchemaMessages 一路)。也就是说:工具侧原始值不留存,用户侧原文留存。这是设计选择,不是 bug;但资金 / 医疗 / 法律审计需要「哪些字段必须保真、保真存在哪、谁能看」的分层,现在没有。
  3. 没有导出面。 审计导出已随商业化那一档拍为不做(doc/28 §15)。今天只能在库里或页面上看,交不出一个可交付的审计包。

这三条里,1 和 3 是工程量,2 是必须由你拍板的取舍。

1.4 任务编排:搜集 → 交叉验证 → 结构化分析 → 报告

积木齐了,编排语义没齐:

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,共四项。但有三个坑不能漏:

  1. workspace 必须是共享卷:cmd/yktako/main.go:225 一带的启动检查会在检测到上次使用主机不同时打警告——多副本不共享盘,文件就各读各的。
  2. 引擎不托管前端:server.go 里没有静态文件路由,web/dist 要由 Web 服务器(Nginx / OpenResty)另挂。
  3. PG 不是裸 PG:开 RAG 时要求 pg_search 扩展、shared_preload_libraries 预加载和 vector 依赖;缺一个引擎就 fail fast 退出(见 internal/runengine/dialogue.go:56 一带的报错文案)。

Model Gateway:有「目录 + 客户端工厂」,没有网关服务

已经有的三层:

它解决的是「用谁家的 key、走哪个模型」,属于客户端工厂,不是网关:没有统一入口、没有路由 / fallback / 限流 / 熔断 / 重试策略,也没有按模型累计成本与延迟的汇总面。GET /api/dev/model/resolve 只是把解析结果打出来给人看。

要往「网关」靠,最小增量不在部署一个代理进程,而在现有调用包装层上补 fallback 与预算;前提是先把「这一枪用的模型 ref、参数、供应商」记成可汇总的运行事实。

Redis / PostgreSQL / VectorDB:两个半

所以依赖清单应如实写成: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 重复采集:

  1. 健康面:/healthz(PG / Redis 探活)+ 版本 / 构建信息;
  2. 指标面:进行中 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 不是单独写一篇文档就完,它依赖两层前置:

3. 依赖顺序(只标顺序,不是方案)

  1. 部署与健康面:Compose 四件、共享 workspace、PG 扩展与密钥准备、/healthz 与基础指标。
  2. 运行配置快照:每场 run 记住当时的提示词 / 模型 / 工具集 / 技能集版本——版本管理与回滚的对象。
  3. 运行时开关与灰度:flag 能不改进程生效,再按租户 / agent 放量,才有「回滚到上一版」可言。
  4. 成本报表与 Runbook:前两层落地后,报表才有归因维度,Runbook 才有可写的确认与回退步骤。

4. 收尾:真正要补的五件事

  1. 把已有账本投影成展示面:trace / 成本 / 审计的页面或接口,读现成的 span、runlog、tenant_usage_daily,不新增采集。
  2. 把配置版本做成可回滚的对象:这是灰度与版本管理唯一的前置,也是今天最实的缺口。
  3. 给 PII 与审计保真分层:哪些字段必须保真、保真存在哪、谁能看、保留多久——这是取舍,不是工程量。
  4. 补部署与健康面:Compose、共享 workspace、/healthz 与基础指标,让「服务是否起来」有机器答案。
  5. 补停机与回滚语义:先有 drain,Runbook 才能写「发布 / 回滚」的安全步骤。

五件事里,前两件是「把已有数据摆上桌」,第三件需要单独拍板,后两件是平台工程的入场券。都不在本文施工;要动哪条,先立方案篇、写 todos、过契约拍。