tako 文档 GitHub

doc/ 文档索引

性质:索引,不是方案。本文只回答「这篇文档是什么、能不能照着施工、代码在哪、被谁取代」。 最后核对:2026-11-16。 状态口径:✅ 已落地 · 🔶 部分落地/待收口 · ⬜ 未做 · 存档 = 历史材料,不作施工面。 代码路径均相对 yk-tako-eino/。

0. 先读哪篇

第一次进仓库,按这个顺序:

  1. 根 README.md:项目是什么、怎么把引擎和前端跑起来。
  2. 系统说明页:总览 → 单场 run → 长任务与编排 → 数据与存储。先建立结构,再读契约。(上面是线上版;离线看就克隆仓库后打开 doc/assets/ 下的同名 HTML——GitHub 上点 HTML 文件只会显示源码。)
  3. 本索引:分清哪些文档能施工、哪些只是历史。
  4. 19-v6/19-运行引擎架构-v6.md:v6(第六代引擎,非服务版本)文档集总入口。
  5. 契约与存储四篇,按这个顺序读:

想在浏览器里读: 在线 https://ykworm.github.io/yk-tako/;本地 doc/html/ 下每个 md 都有一页网页版(站点首页 doc/index.html · 本索引的网页版 doc/html/index.html),由 scripts/build-doc-html.py 从 md 自动生成。内容以 md 为准——网页版是同批生成的读物,改了 md 要重跑脚本,别直接改 html。

按任务查:

不要先读: doc/archive/(旧线 01–15、18 与引擎 v3/v4/v5)与 doc/log/(历史交接与文章)。这些是历史材料,不是现行施工面。

1. 现行真源(施工按这些)

2. 历史存档(doc/archive/,不作施工面)

归档按两代分组,逐篇清单见 doc/archive/README.md。

正文里出现 doc/01–doc/15、doc/18、doc/19-v3/v4/v5、docs/superpowers/ 这类旧路径,都是当时的位置;按文件名到对应分组里找。

分组 内容 入口
old-line v6 之前的旧线方案与交接(01–15、18、XX、handoff-doc24),以及旧线 Web UI / MAF 的计划与设计(plans/、specs/) archive/old-line/
engine 运行引擎 v3/v4/v5 archive/engine/

3. 非方案内容

位置 文档 状态 说明
doc/blog/ 叶子才是根:被 Eino 中断契约坑掉的一天 非方案 工程故事;不作施工面
doc/ 53-模块地图 非方案 代码结构索引:顶层模块与小模块 → 落点文件与职责;讲「代码在哪一块」,不讲「该怎么施工」
doc/ 55-Go 少见玩法辑录 非方案 代码阅读笔记:flock / SSE / Lua CAS / seatbelt 等 20 处不常见写法的落点、动机与代价;不作施工面
doc/ 62-nanoMuse 记忆设计调研 非方案,调研记录 2026-11-04 读浙大开源个人 agent nanoMuse(Meta Muse 的开源平替,本地 clone 于 ref-agent/nanoMuse/)的记忆模块源码:写时防重/读时检索/闲时整理/全程留账四条机制与对 tako 记忆(doc/29)的借鉴清单;借鉴条目落地须另立方案篇;不作施工面
doc/ 63-参照实现对照:子代理与折叠回查 非方案,对照记录 2026-11-05 把根 README 里的对照表搬来正文:子代理(规格/回传/续跑/工具权限/嵌套/模型/运行形态)与折叠回查两张表,kimi 侧带代码指针、tako 侧带落点;只作对照阅读,不作施工真源
doc/ 66-诉求对照:场景应用与生产就绪 非方案,对照记录 2026-11-07 把两组外部诉求(应用侧:Trace/Replay/灰度/成本、高敏决策与人工审核、证据链、任务编排;平台侧:Compose/模型网关/基础设施/Metrics/版本管理/Feature Flag/灰度回滚/成本/Runbook)合到一篇逐条对现状:有 3、半有 3、无 4,并给依赖顺序;原 doc/66 与 doc/67 同日合并于此,不作施工真源
doc/ 68-记忆检索的故事演示 非方案,演示读物 2026-11-08:doc/65 §4.4 search_memory 语义的故事版演示——一场搬家 + 六个问题,覆盖 as_of 现实回放、include_history 改口链、removed 删除边界、过期退场;认知回放只作对比说明,现行工具不开放;参考脉络 Zep/Graphiti(借查询语义、不抄图谱存储);不作施工真源
doc/ 69-参照实现对照:rakazo 与 octop 非方案,对照记录 2026-11-08:读 rakazo(ref-agent/rakazo/)与 Octop(ref-agent/Octop/)源码的对照——agent 管理(rakazo 的 Bot+Subagent 双形态、octop 的 Expert→Agent→Team 三层)、plugin(rakazo「静态声明不执行代码」vs octop「plugin.yaml+main.py 可执行包」)、skill(三家同构的 SKILL.md);结论:rakazo 无 expert、octop 有、tako 无 plugin/expert/协作;只作对照阅读,不作施工真源
doc/problems/ 问题与方案库(43 条) 非方案 决策档案:每条一个设计选择题——当时遇到什么、桌上有哪些候选、为什么这么裁、代价是什么、今天还成不成立;按模块分组,并在 doc/53 各小模块后反链
doc/assets/ 系统架构总览 非方案,交互图 2026-11-16 重基线:约 20 个责任节点讲清前端、接入、run worker、长任务、结果发布、模型、扩展与存储;点节点/连线看输入输出、代码与真源。静态版 tako-architecture.png(3840×2822)由 scripts/export-architecture-poster.sh 派生。四页共享 tako-architecture.css/js,scripts/check-architecture-pages.mjs 检查数据与链接
doc/assets/ 单场 run 生命周期 非方案,交互图 从 POST /api/runs 到定稿、记忆与显式续跑;含九种帧、runlog/模型输入/journal 分工、问答与 compact
doc/assets/ 长任务与多 Agent 编排 非方案,交互图 持久 Task、依赖调度、wait_task、shared/isolated、结果发布、后台 bash、通知恢复、同组修订与继任组
doc/assets/ 数据、状态与存储 非方案,交互图 PostgreSQL 当前模型、四类 Redis 临时状态、项目 content/runtime、会话 wire、记忆双模式与多副本共享卷边界
doc/html/ 在线站点 · 本地入口 doc/index.html、doc/html/index.html 非方案,网页版 2026-11-16:每个已入库 md 对应一页网页版,由 scripts/build-doc-html.py(pandoc gfm→html5)生成并重写链接——doc 之间的链接转成 html、代码与脚本链接转成 GitHub blob、仓库里没有的(tmp/ 施工包、ref-agent 参考实现)去掉链接保留文字。只转已被 git 跟踪的 md(doc/interview/ 等被 .gitignore 挡住的私有材料不入站);内容以 md 为准,改了 md 要重跑脚本。--check 只比对不写盘、--audit-only 只查断链,都可进机器验收;.github/workflows/pages.yml 负责发布

4. doc/log/ 记录

doc/log/ 只放某一时刻的交接、执行台账与文章,按日期命名,不作为施工真源;需要了解「当时为什么这么做」时再读。清单与说明见 log/README.md。

日期 文档 类型 说明
2026-09-30 未提交改动审查交接 交接 旧线未提交改动审查
2026-10-07 v6 现状与能力差距 交接 v6 现状快照与 pi/WeKnora 差距
2026-10-08 pre-T3 落地 执行交接 T3 之前的 lease/T1/T2
2026-10-08 子代理设计素材 素材盘点 子代理设计的已核实素材
2026-10-09 Deferred loading:把工具 schema 移出前缀 文章 前缀缓存与工具 schema
2026-10-12 溢出修复层一期落地 执行交接 检出/救援链/截断检出
2026-10-16 溢出修复层二期 B2/B3 执行交接 guard 救援链+槽位落库
2026-10-19 多租户运行时现状交接 现状交接 多租户全改后代码停在哪
2026-11-02 GAIA k=5:一个模型,两个 harness 文章 tako/dsh 两臂 k=5 可靠性对照
2026-11-03 文档归属重构 变更记录 docs/ 并入 doc/、旧线归档、机器闸落地;执行流水见同目录 tasks.md
2026-11-09 记忆两层方案演进 演进记录 2026-11-07~08 的改稿过程;现行双模式方案以 doc/65 为准,本文不作施工真源

5. 新增/修改文档的规则

  1. 编号与位置
    • 主系列:doc/NN-短标题.md,编号递增,不复用已删编号。
    • v6 子系列:doc/19-v6/19v6-NN-短标题.md;index 与演进记录分别是 19-运行引擎架构-v6.md、19v6-90-演进记录.md。
    • 交接/文章:doc/log/YYYY-MM-DD-短标题.md;变更记录:doc/log/<YYYY-MM-DD>-<方案名>/。
    • 执行期台账:tmp/<方案名>/(本地,不入库),验收后按第 8 条留档。
  2. 头注必须写四件事:性质(方案/实现真源/讨论稿/存档)、状态(✅/🔶/⬜)、日期、代码落点。写了“未定案”的文档不能被当成施工真源引用。
  3. 替代关系写在头注:新文档取代旧文档时,旧文档头注加“已被 X 取代”,新文档写“取代 Y”;不删除旧文。
  4. 同一机制只留一份真源:其他文档只写指针,不复制条款;发现两处冲突,先改真源,再改指针。
  5. 代码落点必须是真实路径:没有代码就写 —(文档/验收/记录),不要写已删除的包。
  6. 新增或改状态时同步本索引:同一提交里更新对应行;纯错别字修正除外。 动了产品能力的增减或状态翻转,同批还要更新 doc/16(§2 能力表 + §2c 横切契约 + 头注基线日期)——本索引是目录页,doc/16 是结论页,两个都得更,只更一边总纲的「现状」就是假的。收尾跑 scripts/check-master-plan.sh(比对本表 §1 的现行真源编号与 doc/16 的引用,漏引即失败)。
  7. 四类归属:现行真源(doc/ 顶层编号文档)、决策档案(doc/problems/)、记录(doc/log/)、归档(doc/archive/)。四者不互相冒充。 时效变化不搬家,只改状态:一篇方案过时了就在头注改状态或标「已取代」;只有被整代取代(旧线、旧引擎代际)才进 doc/archive/。
  8. 施工包留档:开工前由主 Agent 写 tmp/<方案名>/施工包.md 并交用户确认;开发模型随后一次完成大任务,机器验收后由主 Agent 终审。用户验收后,施工包原样搬进 doc/log/<YYYY-MM-DD>-<方案名>/build.md 并加状态头,此后冻结;结论提炼进同目录 README.md,随后删 tmp/<方案名>/。build.md 只记「当时怎么施工的」,与 doc/NN 冲突时以 doc/NN 为准。