tako 文档 GitHub

16 · 能力复刻总规划

性质:总纲(master plan)。一份文件看全 tako 要模仿什么、做到哪了、下一步做什么。 各层的详细设计散在 doc/16–61(历史交接与变更台账在 doc/log/;旧线 01–15、18 与引擎 v3/v4/v5 在 doc/archive/),完整索引见 doc/README.md。本文只做索引、状态与排序,不重复展开细节。 版本口径:v6 是第六代运行引擎与其文档集的代际编号,不是对外服务版本或 API 版本。 状态口径:✅ 已落地 · 🔶 部分落地 · ⬜ 未做。 状态基线:2026-11-16(按 v6 代码与 doc 落点逐行复核;doc/35–51 已并入 §2 与 §2c;doc/52 技能方案已立项、已点头;A1–A4、B1–B8、C1–C5、D1、E1 已落地(2026-10-28:两张表 + GET /api/skills + POST /api/skills/rescan 租户级与全量 + 详情端点 + <available_skills> 目录与三个技能工具(read_skill/use_skill 已换真身,read_skill_file 已换真身)+ 子代理剔除 + runs/:id/skills 真派生 + use_skill 打开本场技能根只读围栏、bash 出站网络放开 + B7 正文用完让位(D33)+ B8 skill-ops 记录块(D31)+ C1 安装/更新/删除 + C2 来源/命令解析与原生抓取(SSRF 口径、116109/116108、POST /api/skills/preview)+ C3 对话内安装 HITL(skill_install 只提议,approve 后程序装盘;skills_changed 事件)+ C4 技能页(列表/详情/开关/上传/删除,PATCH /api/skills/:name)+ C5 预览卡与安装确认卡(preview 补 selected/files、SkillInstallCard 按帧渲染、对话工具卡)+ D1 依赖三处同源(use_skill 标签带 requires/missing、列表/详情 missing[] 现查、GET /api/skills/:name/check;子进程 PATH 与围栏绑定同一份读根(D39)+ E1 技能作用域(manager 规格的 skills:/exclude_skills: 落 skill_policy 列;目录过滤 + 解析时点四处同判,范围外同 116001 字节;普通子代理写作用域入口 400)+ E2 禁用开关(PATCH /api/skills/:name 只写 skill_disables,目录与三个技能工具同判 116107;删除同事务清禁用行;skills_changed 事件)+ F1 工具上传写面(GET/POST/DELETE /api/tools,工具根不进表、staging→.trash→rename、额度预留、tools_changed 事件)+ F2 工具根常开(整棵只读进围栏、每个 <name>/bin 前置进子进程 PATH,普通子代理同样可用)+ F3 工具区前端(列表/上传/覆盖确认/删除;技能详情缺依赖处跳转预填))),G1 收口(tempsweep.go 的 24h .staging/.trash 清扫 + rescan 对账)也已落地,24 拍全部收口——2026-10-28 复审修订了方案内容(含执行模型翻案:manager 自己读正文自己执行;第十四轮补工具上传通道 D36:/api/tools 单文件、工具根按租户常开;第十五轮放开 bash 出站网络 D37、use_skill 报缺依赖 D38;第十六轮 PATH 按围栏过滤 D39)。2026-10-31 增补 doc/54 运行级 OTel 追踪:A1–A9 全部落地(OTel GenAI 语义 span → OTLP/CozeLoop;run 根 + chat/execute_tool/tako.step.* 子 span;内容开关 OTEL_INSTRUMENTATION_GENAI_CAPTURE_CONTENT,.env 默认 SPAN_ONLY),能力表见 §2 #14。2026-11-01:doc/54 增补第二出口 Langfuse(LANGFUSE_*,与 CozeLoop 可并存双发;实测 gen_ai.* 原生映射与 v2 observations 读回,§3.1)。2026-11-01:doc/57 网络抓取落地(父池加 web_fetch,走 DeepSeek Fetch、整页落盘 .tako/fetch/,researcher 继承、coder 白名单不动),与 doc/22 的搜索构成「搜索找链接 → 抓取读原文」两步。2026-11-01:doc/58 读分页与输出留存已落地(read_file 改成分页:入参 offset/limit、head/tail 删掉、每页 2000 行 / 50KB / 单行 2000 字符、页脚恒带总行数与下一个 offset、「>200KB 直接报错」撤掉;bash 改留尾:每流 64,000 字节尾窗 + 全文落盘 .tako/bash/<runId>/<seq>.out(64MB/流,装不下全文就删文件不报路径)+ 回路径 + 30 天清扫,能力表见 §2 第 1 行)。2026-11-01:doc/59 工具调用可见性已落地(对话页删掉「只认技能三件」的白名单,每一次工具调用都画成卡:帧与 runlog 两条路径按 toolCallId 配对、摘要行 + 展开看参数/回执、失败按「错误:」前缀标「失败」、参数 2,000 / 回执 8,000 字符截断;翻掉 doc/52 C5 的窄口,能力表见 §2 #15)。2026-11-01:doc/60 前端多会话并发已落地(前端从「全局一个 useChat()」改成每个打开过的会话一个实例:切走不打断轮询,草稿/排队/游标随会话保留;空对话在输入区选项目落点、侧栏项目行「+」直接开新对话;删除/换租户/上限 8 收口;侧栏「运行中」先走本 tab 本地信号,刷新/跨端的运行状态留 P1;能力表见 §2 #16)。2026-11-03:Linux bash/租户 MCP 沙箱已落地——Debian 12 用 bubblewrap(bwrap):后端探测先真跑 seatbelt、再真跑 bwrap,失败回 none 并继续 fail closed;bwrap 逐个卸 user/pid/ipc/uts/cgroup、不卸 net(对齐 D37 出站网络),/usr 只读、/etc 只白名单、只 bind 会话根可写;启动日志一行 bash sandbox: seatbelt|bwrap|none(原因)。macOS 行为逐字节不变;Debian 活体脚本 scripts/acceptance/linux_sandbox.sh 已入库,但开发机没有 Linux 环境,活体尚未跑(见 doc/problems/没有沙箱的系统怎么办)。2026-11-03:§2b 增补「外部对照引入」候选组(浏览器操作/跨子代理黑板/run 级预算中断/受限 RSI 实验),来源是外部通用 Agent 能力清单对 tako 的缺口分析(对照载体为本地材料,不入库);同批把根 README 能力清单补齐(工具分级、配额闸、前端多会话、三层验收等缺行)并新增「下一步做什么」「架构」(mermaid)、「五个关键取舍」「失败与教训」四节与 MIT LICENSE。§0、§3、§5 的旧线表述保留为立项史料,当前能力状态以 §0.1 现状快照与 §2 表为准。2026-11-03 增补:doc/47 §5.5 提问分段与对话宽度——一场 run 仍一条 Σ assistant 行,payload 按 ask_user/submit_plan/skill_install 记 segments(rune 偏移);历史、收口、实时同套切段,问题卡与答案用户气泡按真实先后排开;对话列去掉 45rem 上限铺满内容区(助手气泡 100%、用户 78%)。无提问 run 的 runlog 字节不变。2026-11-10:doc/70 多 Agent 编排与持久 Task V1 已落地(四张 agent_* 表 + 八端点 117xxx + 三模型工具 + 任务页;活体五场 single/busy/dag/crash/two_replicas + 浏览器停止/恢复链走查;能力表见 §2 #9),同批回填 doc/40 §4.2c(117xxx 码表)与 doc/46 §7.7(两类任务事件 + SSE 心跳与 last_event_id 续读)。2026-11-11:doc/72 多 Agent 编排下一阶段已落地(有界计划修订 + agent_plan_revisions 审计、Task HITL 与 run_questions.expires_at、GET /api/workspaces/:id/task-attention 聚合、tk:agent-task-wake 事件唤醒 + PG 对账;契约用例 51–54 + 活体四场 + V1 五场回归),同批回填 doc/40 §4.2c(117106–117108、115102)与 §2c 第四个临时键。2026-11-11:doc/73 协调通知与交付恢复已落地(通知 pending→claimed→consumed/failed 全态、agent_notification_attempts 审计、失败详情与人工重试端点、同 run epoch+1 崩溃续跑、结果/产物定位与只读交付工具面、前端恢复闭环;契约用例 55–56 + 十场活体 109 条 + doc/72 与 V1 全量回归),同批回填 doc/40 §4.2c(117003、117109、117110)与 §2c 第 4 行。2026-11-12:doc/74 并行任务工作区隔离已落地——Task/DAG 不认识 Git;LLM 决定节点、依赖与隔离需求;WorkspaceProvider 按真实项目选择 Git worktree 或普通目录副本;引擎执行创建、结果验收与发布协调;prompt 只指导模型配合。Git 状态与目录哈希不进 PG,Provider 状态和不可变结果在共享持久卷;新增 workspace_*.go 八件与 agent_task_artifact.go(artifact / retry-publication)、发布准入与项目级 PG 事务锁、业务码 117111–117113;活体四场 git 51/directory 42/publication 34/crash 57 + 契约用例 57–59 + 既有 70–73 回归全绿;§0.1、§2 #9、§2c 与 §5.1 同批翻 ✅。2026-11-12:新增 doc/75(方案已点头、与 76 合并施工包待审)——先判目标可行性,再选 doc/72 同组修订或继任组;handoff 文件保存 replanOf/原因/复用引用,不新建跨组依赖边、不重置预算。新增 doc/76(方案已点头、与 75 合并施工包待审)——项目目录拆为 content 用户内容根 + runtime 运行资源根,异步 shared/isolated 都不把中间结果直接写 content,最终才发布;存量复制校验后切换,删除整个项目容器但不误删租户技能/工具与用户记忆。用户级 skill/plugin 明确本期不做。2026-11-13:doc/77 对话页右侧任务面板已落地——当前项目 Task 常驻对话页,处理项就在页面内打开;复用任务页的 TasksView 与详情抽屉,不复制第二套实现;事件、事件流重连与窗口聚焦都从服务端重拉;≤860px 不渲染。纯前端(web/src/App.vue、web/src/TasksView.vue),无新增接口、契约字节零变化;headless 走查九项全过,能力表见 §2 #17、互斥规则见 §2c。2026-11-13:doc/75 目标重规划与继任编排组、doc/76 项目内容目录与运行资源容器已落地(与 74 合并成一个施工包)——重规划先判 goalAssessment.outcome,feasible 才建继任组(successor.json + handoff 文件),handoff 记 replanOf/原因/可复用结果 (taskId,resultRevision),深度上限 8、预算不重置、原组先收口;项目目录收成容器 content/(用户内容根)+ runtime/{orchestrations,tmp,media,memory}(运行资源根),异步 workspaces 与不可变结果都在 runtime,最终 Task 末尾发布进 content,整容器删除带 cleanup=done|pending 与 project_cleanups 补偿;活体 goal_replan 124/crash 46/layout 36/迁移 51/项目删除 10 + 契约用例 58/60/61–63 + 70–74 全量回归。2026-11-13:doc/78 对话页右侧工作区已落地——把 doc/77 的右侧任务面板扩成 项目目录/任务/Todo/文件 多标签工作区,可收起为窄条;新增两个只读端点(GET /api/runs/:id/changed-files 从 runlog 工具调用行派生本轮写入/编辑路径、GET /api/runs/:id/tasks 读 run_tasks),助手回复结尾列改动文件、点开在右侧查看;取代 doc/77 §3「Todo 不进面板」;快闸 + 契约用例 65(21 步)+ 浏览器活体(收起/恢复、目录树、文件查看、Todo、≤860px)通过,能力表见 §2 #17。2026-11-14:项目里的 .md 文件按 markdown 渲染显示(doc/79,细节见 doc/48 §10)——对话页右侧文件标签与项目页文件列表两个入口都渲染 md、默认预览态、可切「原文」;排版样式抽成全局 .md-body 三处共用(scoped 样式不跨组件,抄不进第二个组件);渲染复用 markdown.ts 既有管线(marked + DOMPurify),md 用 breaks: false、气泡仍 breaks: true。纯前端、契约字节零变化;前端单测 8 条 + playwright 2 条新断言全绿。2026-11-15:doc/82 可组合执行原语与后台任务已落地——bash 从 30 秒进程总寿命改为前台等待窗口(默认 30s,可配置),超时保留进程转后台 job 返回 bj_…,补输出读取/有限等待/停止(SIGKILL 整进程组)/持久通知与失联恢复(owner watcher 续租写终态、sweeper 对账 interrupted);wait_task 让当前 run 就地认领通知(claimed_in_place=true,不建 run、不写 attempt 行)避免重复交付;组内并发按 workspace_mode 取值(shared=1、isolated=2);新增路径账本 GET /api/orchestrations/:id/journey 只读投影;契约用例 82–83 + expected.json 同批 + 活体四脚本(bash job 62/0、编排 49/49、journey 22/0、orchestration 回归)+ spotcheck 37/0 + 浏览器走查(桌面/移动端)全绿;能力表见 §2 #9、下一步表见 §3。 同步纪律:本文是结论页,doc/README.md 是目录页——产品能力增减、状态翻转、落地收口,两页必须同一批更新。 只更目录会怎样:下一场会话按 README 的「第一次进仓库」顺序读完本文,以为 doc/35–44 这些现行真源不存在,得再翻索引才看到结论——本文最值钱的那一格(现状)就成了假的,而且假在最能省事的地方。 自检:scripts/check-master-plan.sh(比对本文与 README §1 的现行真源编号,漏引即非零退出)。

0. 定位与边界

tako 是什么:从 pi 式 agent 循环长出来的 AI 工作伙伴,单入口产品(cmd/yktako)。核心是"一个能自主干活、带任务看板、带工具安全、能长时间跑任务的 agent"。

tako 不是什么:不是知识库 / RAG 产品。RAG、记忆这些能力会被借鉴进来,但只作为支撑 agent 干活的横切能力,绝不反客为主把 tako 变成"以文档检索为中心"的系统。这条边界是本文所有取舍的总闸(见 §4 护栏)。

tako 也不是协同编辑产品(2026-10-22 形态收窄,doc/42):一个员工 = 一个项目,项目里的文件由他的多场 session 共享;团队共享账号、额度与审计,不共享文件。 不做「共享文件的多人在线同时修改」——那是协同编辑(CRDT/OT、在线状态、冲突合并、版本历史),是另一个量级的产品,不在本项目范围。

技术栈:Go + Eino(CloudWeGo)。主线在 yk-tako-eino/。

0.1 现状快照(2026-11-16)

先看这一节再往下读:tako 今天是什么、不是什么、还欠什么。逐项状态与代码落点在 §2 表,专项设计在 §6 索引。

是什么:一个多租户的 agent 运行时(Go + Gin + Eino + PostgreSQL + Redis(asynq) + Redpanda(记忆 pipeline 模式的派送)+ Vue 前端)。用户发一句话,引擎起一个 run,模型可以在里面调 bash、读写文件、搜历史、搜网络、委派子代理;帧流式回给页面;崩了能续跑;隔天的对话能召回。

不是什么:不是知识库/RAG 产品(§4 护栏)。记忆和召回只作支撑 agent 干活的横切能力。

已经能用的(✅)

面 做了什么 方案
身份与隔离 注册登录、租户、成员与邀请、会话归属、团队运行时装配 doc/28、doc/34、doc/36
对话与流式 四个产品 API 的帧契约、拉与 SSE 两种运输、客户端双游标 reconcile 19v6-01/02、doc/31
前端多会话 单主视图 + 后台保留:每个打开过的会话一个实例,切走不打断;空对话可选项目落点;侧栏标本 tab 运行中 doc/60
工具与围栏 bash 沙箱(macOS seatbelt / Linux bwrap)、工作区文件围栏、同文件并发写防护、MCP 进程围栏、PII 脱敏(人工审批不做) doc/06、19v6-05/08、doc/33、doc/41
上下文 压缩、中途折叠、溢出救援、media 只存 path、用量可见 19v6-07/09/10、doc/24、doc/27、doc/32
子代理 委派折叠、coder/researcher 规格与护栏、持久档案与 resume doc/23、doc/25、doc/26、doc/39
多 Agent 编排 持久 Task 与固定 DAG(doc/70,2026-11-10 落地):模型 delegate_task/create_orchestration 派发、整组原子创建、独立执行 session 与 run、依赖推进与失败阻断传播、显式恢复接管(同 run epoch+1)、整组单次交付回来源会话;任务页全量可见(停止/恢复/详情);目标不可行时判可行性后建继任组、复用上一组结果(doc/75,2026-11-13);bash 前台等待超时转后台 job(输出/停止/通知/失联恢复)、wait_task 就地认领通知、路径账本 GET /api/orchestrations/:id/journey(doc/82,2026-11-15) doc/70、doc/72、doc/73、doc/74、doc/75、doc/82(四张 agent_* 表 + background_jobs + 端点 + 任务页;活体 single/busy/dag/crash/two_replicas/attention/revision/wakeup/workspace/publication/goal_replan/bash job/journey 全在 scripts/acceptance/)
记忆 记忆双模式(doc/65,2026-11-10 落地):pipeline = PG 两层(resident/recall)+ Redpanda 派工抽取(inrun/postrun)+ BM25 召回 + search_memory;markdown = USER.md / MEMORY.md 同步直写,不启动抽取与 MQ。对话召回(dialogue_chunks)两模式共用 doc/65(doc/29 线一被其取代;线二仍现行)
治理 项目容器(content 用户内容根 + runtime 运行资源根,doc/76,2026-11-13)、单场删除、保留窗口与清扫器、Redis 临时键收敛 doc/35、doc/37、doc/38、doc/76
任务看板 四把记账工具 + PG 正本 run_tasks + task 帧 + 前端看板块(活得过崩溃) doc/41
可观测 运行级 trace(OTel GenAI 语义 → CozeLoop / Langfuse OTLP,可双发):run 根 span + 模型/工具/内部步骤子 span + 内容开关(默认开、可一键关) doc/54
契约一致性 所有 JSON 接口统一 {code,message,data} 信封 doc/40、19v6-01/04
验收 快闸(go test 钉契约字节)+ 活体(scripts/acceptance/,机器真源 expected.json,红了退出码非零)+ 公开题标定(scripts/bench/:行 schema、官方口径判定器、切片配方 + slice_hash、批量 runner、报告;口径见 doc/56 §4.7) scripts/acceptance/、internal/runengine/contract_test.go、doc/19v6-04、doc/56
崩溃续跑 在途轮次崩溃可续(客户端触发,引擎不自动巡检) doc/30

还欠的(⬜,按影响排序)

  1. IM / cron 入口(#8b)——多入口还没第二个入口。

不在欠账里(都是已拍不做,别当漏项捡回来):团队计费 / API key / SSO / 组织共享 / 审计导出(2026-10-22 用户裁,与运行时关系不大的商业化、合规项,doc/28 §15,2026-10-23 复核维持);框架拦截式的工具审批 gate(模型没问、框架替它拦;目录内动作已由 plan 审核兜住,越界由沙箱围栏硬挡,doc/41 §3.1)。注意这与 plan 审核 + ask_user 不是同一样东西——后者是模型主动问人,2026-10-23 已落地(doc/47)。

方案去向(2026-10-22/23 的方案均已落地):

一句话判断:核心循环(登录 → 发消息 → 调工具 → 收帧 → 记住 → 能续)已经跑通——成功路径、失败路径、长对话路径、崩溃续跑路径四条都验过(失败留痕与召回块活过折叠见下方两条,任务看板活过 kill -9 见 doc/41,问/方案挂起活过 kill -9 见 doc/47)。剩下的是产品外围:协作与界面长尾(IM/cron 等),不是地基;商业化那一档已拍不做(doc/28 §15)。地基那几处硬的已经补齐——PII 脱敏与任务看板、plan 审核与 ask_user 2026-10-23 先后落地(doc/41、doc/47);框架拦截式的工具审批仍不做(bash 与 MCP 的越界都由沙箱围栏硬挡 → 不需要框架替模型拦),与人主动问人是两条线。

2026-10-22:失败侧的一处地基欠账已还——失败那一轮原先什么都不留(页面刷新即消失、模型下一枪接不上); 现改为**「已产出的内容」照常落库**(runlog 有半截回答与工具行、mh 同样落;「失败且无产出」那一档仍是一行不写), 且缺 tool 结果的调用会补一条「没拿到结果」的合成行(否则下一枪的 provider 会 400)。形状见 doc/19-v6/19v6-03。

2026-10-22:记忆侧的一处地基欠账已还——召回块原先会被 mid-run 折叠抹掉 (长对话里模型看不见当轮召回的内容)。现改为:召回块进「本轮输入」并写回 mh 的 seq=1, 折叠重建时文本从 mh 取 → 块活过折叠(doc/29 §6.1/§6.4)。

1. 参考实现的分工(翻译原则,承 doc/05 §5)

参考物 路径 从它这里拿什么 不拿什么
Octop ref-agent/Octop(真正实现在 harness-pkg/harness-agent) "要什么":功能规格、行为对照、能力清单、设计思路。定位最接近 tako 它是 Python + deepagents/LangGraph,代码翻不动也不该翻
Eino ADK 框架本身 "怎么做":ChatModelAgent / middleware / prebuilt / compose,一律用 Eino 正式做法 —
WeKnora ref-agent/WeKnora Eino 缺失类库的 Go 参考:RAG、记忆蒸馏、向量检索、混合召回的工程写法 它的产品定位(知识库/问答为中心)不借鉴
Pi Agent ref-agent/pi(TS monorepo,~98K stars) 极简哲学 + 上下文创新:4 原语够用论、树状会话历史(对话像 git 分支)、Skills 开放标准分发模式、场景化 evals 框架 它是 TypeScript,代码不翻;极简哲学取其神不抄其形
Hermes Agent ref-agent/hermes-agent(Python,Nous Research) 自演化 + 记忆体系:background_review 后台轨迹复审 + /learn 蒸馏(勘正 2026-10-12 实读:learning_graph 名不副实——它是桌面端/TUI 的「学习可视化图」装配,不是归纳引擎;真正的轨迹→经验归纳在 agent/background_review.py + /learn + curator.py)、memory_provider 可插拔记忆分层(agent/memory_provider.py:84 钩子组 + 召回双通道:恒定块冻结进 system prompt、按需召回注入当轮 user 消息)、skill_usage 使用追踪与淘汰、22+ 平台 transports 抽象、训练数据导出飞轮 它功能膨胀(16000+ 文件),只取思路不取实现
其他项目 开放 好的思路都可参考(Codex 提权模型、MemGPT 记忆分工等) —

一句话纪律:"要不要做"听 Octop,"怎么做"听 Eino,"Eino 缺的类库"听 WeKnora,"创意与差异化"听 Pi + Hermes。

2. 能力总表(产品视角)

梯队仅标记 ⬜ 待建 项,✅ 已完成不涉及排序。

梯队 含义 选择标准
T1 核心 + 面试杀手锏 产品基石;能从 Pi / Hermes 偷到别人没有的思路
T2 创意差异化 产品亮点;面试加分的"独特故事"
T3 基础设施 / 延后 有价值但不急,等核心扎实再补
# 能力 状态 参考来源 可借鉴点(Pi / Hermes / 其他) 梯队 落点
1 主循环 + 工具(时间/计算/bash/文件) ✅ deepagents 核心 — — internal/runengine(worker / tools / filetools / bash);读分页与输出留存:doc/58(2026-11-01 已落地)——read_file 改成分页读(入参 offset/limit,head/tail 删掉;每页 2000 行 / 50KB / 单行 2000 字符;页脚恒带总行数与下一个 offset;「超 200KB 直接报错」撤掉,长文件读得到中间);bash 改留尾(每流 64,000 字节尾窗)+ 全文落盘 .tako/bash/<runId>/<seq>.out(64MB/流;装不下全文就删文件、不报路径)+ 回路径 + 30 天清扫
2 工具安全:命令守卫 / 文件守卫 / PII + 人工审批 🔶 Octop security/tool_guard、middleware/* — — 工作区围栏 internal/runengine/filetools.go ✅ + bash 沙箱 internal/runengine/sandbox.go ✅(2026-10-22 实测:越界读/写全被沙箱拒绝 → bash 按范围硬挡,不需要人审);同文件并发写防护(flock 写锁 + 写前指纹比对 + run 级基准表,2026-10-22 落地;写盘改原子替换——同目录临时文件 + rename,2026-11-10 随 doc/71 落地,internal/runengine/{filefp.go,filelock.go,atomicfile.go})✅;MCP 进程同款围栏(围栏根 = 该租户目录,2026-10-22 落地,mcp.go/sandbox.go)✅;PII 脱敏 ✅(2026-10-23 落地,internal/runengine/pii.go)——三处挂载点:工具统一出口 wrapToolErrors(含 MCP 工具)+ 模型输入唯一转换口 toSchemaMessages(折叠后仍防得住)+ 记忆入库前(密钥类整条拒收、证件类打码),掩码规则与金样在 pii_test.go;人工审批不做(越界由围栏硬挡,无需挂起问人);Linux 沙箱 2026-11-03 已落地——Debian 12 用 bwrap(逐个卸命名空间、不卸 net、只 bind 会话根可写;probe 失败仍 fail closed),租户 MCP 走同一后端,启动日志一行 `bash sandbox: seatbelt
3 任务看板:Plan / Tasks / Actions 三层分离 ✅ 自研记账工具 — — v6 已重建(2026-10-23,doc/41):PG 表 run_tasks(正本在库里,不在进程内存)+ 四把工具(TaskCreate/TaskUpdate/TaskList/TaskGet)+ kind=task 帧(帧 kind 词表 7→8)+ 前端看板块;活得过崩溃(kill -9 → 重启 → resume,崩前建的行一条没丢且续跑里继续建行,scripts/acceptance/taskboard_crash.sh 可重跑)。三层里只新建了 Tasks 层:Plan 层由 doc/47 的计划审核与追问机制承担,不与 Todo 混成一层、Actions 层就是既有的 ReAct 工具(与 task 无外键),另三件明确不做(Action↔︎Task 双射 / 自动勾选 / 拓扑强制)。旧线见 doc/01、02、07
4 上下文管理 · 压缩 ✅ Octop compaction — — internal/runengine/compact.go(含中途折叠与溢出救援;见 doc/12、13、19v6-09)
4b 上下文管理 · media_offload(图片落盘换占位符) ✅(旧线代码已删;v6 已落地,见 doc/32) Octop middleware/media_offload.py — — internal/runengine/media.go + web/(doc/32:存储纪律半边 A1–A2 + 模型可见半边 A3-1–A3-5 + PDF 文本层 A8-1/A8-2;对话只存 path,模型看图已落地——A3-1/A3-2 把当前 user 图与 read_media_file 回执在下一枪还原成 image part,A3-3 收成「本 run 成功回复后不再重复发送」;扫描件 OCR 与音视频已拍不做)
4c 上下文管理 · context_usage(用量可见/可决策) ✅(可见半边;可决策半边=用户看数自行决定,无自动动作) Octop middleware/context_usage.py Pi 4 原语的 token 极简哲学 T1 internal/runengine(usage 帧 / runlog payload)+ web/(doc/24 计数与滤思考、doc/27 A1–A3)
5 子代理(tool 变子 agent,上下文隔离) ✅(T3 与进程内折叠 ✅;T4/T5 2026-10-20 落地) Octop subagents/;Eino ADK Pi 工具即子代理挂载模式;Hermes skills_hub 技能注册/去重/演化 T1 internal/runengine/agents.go、agents/(doc/17 §6、doc/23 coder 规格、doc/25、doc/26)
5b 子代理持久档案与 resume(跑完的子代理还能接着问) ✅ Octop checkpoint;Kimi wire.jsonl 只取「每实例一份追加式 wire 文件」的形态,不取事件溯源协议 T1 internal/runengine/{agents.go,subagent_wire.go,resume_subagent.go}(doc/39 S1–S3;wire 落在会话目录 .tako/subagents/,无 PG 表;半截实例不做重接,对齐 doc/30「放弃半截、client 重发」);前端列表与「继续」入口 2026-10-23 由 doc/44 落地
6 记忆(长期) ✅ Hermes memory_provider 接口钩子组(prefetch/sync_turn/on_pre_compress)与召回双通道、background_review 轨迹复审(learning_graph 已勘正,见 §1);T-Mem 算法参考仍是论文本体 T1 internal/runengine/{memory.go,memory_pipeline.go,memory_queue.go,memory_search.go,memory_store.go,memory_mode.go,memory_dispatch.go,memory_markdown.go,notes.go,dialogue.go,worker.go}(2026-11-10 起 doc/65 已落地:pipeline 模式 = 两层 memory_items + Redpanda 派工 + 消费者三段流抽取 + BM25 召回 + search_memory;markdown 模式 = USER.md / MEMORY.md 同步直写、不启动抽取与 MQ;doc/29 线一(recall.go/worker.go 旧循环)被取代,线二 dialogue_chunks 仍现行。旧 doc/29 的 Go 侧词法召回与 recall.go 已退役)
7 断点恢复与流式 · 内存 checkpoint + interrupt 审批 ⬜(旧线 ✅,代码随翻篇删除)→ 2026-10-22 已定不做 Eino checkpoint/interrupt — — v6 未建;在途恢复走 #7c;旧线见 doc/08、09。已定不做:bash 的越界由沙箱围栏硬挡(实测越界读/写全被拒)、MCP 的越界进了同款围栏(围栏根 = 该租户目录,doc/33)→ 没有需要「挂起问人」的场景,doc/41 的 Loop A 已整条取消(2026-10-23),本行随之退役
7b 断点恢复与流式 · Web 事件落 SQLite + 按 seq 回放 ✅(v6 等价能力;旧 SQLite 方案已删) 自研 — — internal/runengine(frames / runlog)+ web/(doc/19-v6;旧线见 doc/10、15)
7c 断点恢复与流式 · 在途轮次崩溃续跑 🔶 Octop checkpoint Pi session-backends 持久化会话 T3 internal/runengine/journal.go、worker.go、resume_test.go、web/src/{api,chat}.ts、web/src/App.vue(doc/30 A1–A5 + A8 前端 reattach;A6 裁为客户端触发式恢复、server 巡检不做;A7 回归收口已跑)
7d 断点恢复与流式 · API 面通用流式(SSE 端点) ✅ OpenAI/Anthropic 流式 API 的消费方期待 — T2 internal/runengine/server.go(stream 端点;doc/31 A1–A3;拉是正确性、流是优化,四 API 零改动)
8 多入口统一路由 · Web(SSE/审批/续传/停止) 🔶(登录 / 聊天 / 续传 / plan 审核 + ask_user ✅(doc/47) / 停止 ✅(doc/48 A3,2026-10-23 接上前端入口);框架拦截式工具审批不做) Octop HarnessProcessor — — web/ + internal/runengine/{server.go,questions.go,waittools.go,plangate.go,store.go,pgstore.go}(doc/19-v6、doc/34、doc/47;2026-10-23 界面走查欠账(17 条现象 / 14 项修复)已由 doc/48 全部落地;2026-11-03 提问分段与对话宽度:一场 run 一条 Σ 行按等人工具记 segments 偏移,历史/实时同套切段,问答独立成卡与用户气泡;对话列去 45rem 上限铺满,见 doc/47 §5.5)
8b 多入口统一路由 · IM / cron ⬜ tako 自扩 Hermes 22+ 平台 transports/ 抽象;cron/ 定时任务 T3 待建
8c 多入口统一路由 · MQ 同步写入 ⬜(只记不做) — — — 见本文 §5「明确不做」与记忆 mq-before-browser(旧指针 doc/14 已不存在)
9 多用户、多 Agent ✅(多租户 / 登录 / 团队 agent 配置 / 团队前端 ✅;多 Agent 协作 ✅ 2026-11-10——doc/70 V1:持久 Task + 固定 DAG 编排;下一阶段 doc/72 ✅ 2026-11-11 已落地:有界修订 / Task HITL / 左侧提醒 / 事件唤醒 + PG 对账;doc/73 ✅ 2026-11-11 已落地:通知全态、attempt 审计、崩溃同 run 续跑、人工重试与结果定位);doc/74 ✅ 2026-11-12 已落地:并行任务工作区隔离、结果交接与发布恢复(Git/Directory Provider、不可变结果、发布准入与受阻重试);doc/75 ✅ 2026-11-13 已落地:可行性判定(goalAssessment.outcome == feasible)→ 同组修订或继任组;successor.json + handoff 文件 + 不可变结果复用((taskId,resultRevision)),深度上限 8、预算不重置、原组先收口;doc/82 ✅ 2026-11-15 已落地:bash 前台等待超时转后台 job(输出读取/有限等待/停止/通知/失联恢复)、wait_task 就地认领通知去重、组内并发 shared=1/isolated=2,不新增用户 DAG 模式或 JS 引擎;页面补路径账本 GET /api/orchestrations/:id/journey,从持久记录展示计划版本、失败/取消节点、结果复用与交付尝试 Octop HarnessAgentManager;Comma 持久 Task;Hermes Kanban apps/desktop 多会话 GUI T3 internal/runengine/agent_task_*.go(存储/图/调度/交付/执行/修订/处理项)+ questions.go + cmd/yktako/main.go + web/src/{TasksView.vue,App.vue}(doc/28 A0–A6、doc/34 R1–R5/U1、doc/36、doc/70、doc/72、doc/73;doc/74 新增 workspace_*.go 八件与 agent_task_artifact.go、shared/Git/Directory 执行环境,已落地;doc/75 新增 agent_task_{successor,handoff}.go 与 GET /api/orchestrations/:id/handoff、POST /api/orchestrations/:id/successors,已落地;计费、API key、SSO、组织共享、审计导出整批已拍不做(2026-10-22 用户裁,doc/28 §15,2026-10-23 复核维持)——真要对外卖再翻案)
9b 团队协作前端(工作区切换 · 成员与邀请) ✅ Hermes Kanban(前置形态) — T2 web/src/{App.vue,MembersView.vue,InviteLanding.vue,PendingInvites.vue,auth.ts}(doc/36 G1/G3+F1–F3)
10 对话内容 → 召回(借鉴 WeKnora,非转型;PG 词面全文检索,语义/向量路线 2026-10-18 已裁) ✅ WeKnora IndexMessageToKB —(受 §4 护栏约束,不做成 RAG 产品) T3 internal/runengine(dialogue_chunks + pg_search;doc/29)
11 MCP client(stdio,工具直接进池) ✅ Octop 接入位;WeKnora mcp/ WeKnora untrusted notice 随数据走 + 千级规模才上目录代理的判断;Claude Code mcp.json 惯例 T2 internal/runengine/mcp.go、mcpconf.go(doc/33 A1–A4;HTTP/deferred/常驻在后置拍,见 doc/33 §9)
12 项目目录(workspace):会话与产出按项目归置(2026-10-22 形态收窄:项目变成个人的,跨成员共享项目与项目闸一并退役,见 doc/42) ✅ Octop apps/desktop 多会话 GUI — T2 internal/runengine/{product_store.go,session_access.go,media.go}(doc/35 A1–A8c;项目页 2026-10-23 由 doc/44 落地;文件清单与取回 2026-10-23 由 doc/48 B1 落地——GET /api/workspaces/:id/files + 项目页文件区,agent 写出的文件用户能看见、预览、带走;doc/76 ✅ 2026-11-13 已落地:项目容器 = content/ 用户内容根 + runtime/{orchestrations,tmp,media,memory} 运行资源根,异步中间结果不直接进 content,最终发布才写入;存量离线迁移 -migrate-project-layout,删除整个容器带 `cleanup=done
13 删除与档案清理:连带删会话 · 单场删除 · 保留窗口与清扫器 ✅ Octop 清理 — T2 internal/runengine/{pgstore.go,product_api.go,session_access.go,archive_sweep.go,worker.go}、cmd/yktako/main.go(doc/37 D1–D4;-archive-ttl 默认 168h;114002 退役;D-l 项目记忆按 scope 随删、user 记忆保留,2026-11-10 随 doc/65 落地(pgstore.go 删除事务 + memory_migrate.go,活体 memory_project_delete_live.sh 9/9);删除按钮与确认弹窗 2026-10-23 由 doc/44 落地)
14 运行级可观测性(OTel GenAI trace → CozeLoop / Langfuse,可双发) ✅(A1–A9 已落地 2026-10-31;Langfuse 出口 2026-11-01) OTel GenAI 语义 / CozeLoop 与 Langfuse 的 OTLP 接入 gen_ai.* 是跨后端公共语言(换 Tempo/Jaeger 不改埋点);内容按规范开关控制;usage 口径钉死为对话账本,与 usage 帧逐值对账 T3 internal/observability/ + internal/runengine/{trace.go,trace_run.go}(doc/54)
15 对话里的工具调用可见性(每一次调用都上屏) ✅(2026-11-01 A1–A2) 自研(doc/52 C5 卡片机制的推广) 数据一直在帧与 runlog 里,缺的只是「不按工具名筛」这一层;卡片默认一行摘要、展开看参数与回执原文,失败看「错误:」前缀。2026-11-03 起等人工具边界把正文切段(segments),问答块可按真实先后排开;普通工具仍只分卡片上下两块 — web/src/{chat.ts,App.vue,api.ts}、internal/runengine/{store.go,pgstore.go,types.go}(doc/59、doc/47 §5.5)
16 前端多会话并发(单主视图 + 后台保留) ✅(2026-11-01 A1–A6) Octop apps/desktop 多会话 GUI 后端本来就允许多会话并发(会话闸只锁同一场、租户容量闸默认 8),限制全在前端单例;切走只换激活实例,不打断旧实例的轮询与计数 — web/src/{App.vue,chat.ts,chatpool.ts}、web/{test,e2e}/(doc/60;后端零改动、契约字节零变化;刷新/跨端的运行状态留 P1:列表接口加 liveRunId)
17 对话页右侧工作区(项目目录/任务/Todo/文件多标签、可收起;回复结尾列改动文件) ✅(doc/77 → doc/78 2026-11-13 落地) 自研(复用 doc/70–75 的任务页与 doc/76 的目录读面) 病根是「派发在对话、执行在后台、可观察面却在另一页」,以及 agent 写完文件用户不知道改了哪些;面板不复制第二套列表与详情,任务标签把 TasksView 嵌入并复用同一张详情抽屉,处理条复用 task-attention;新增项目目录树(懒展开、目录在前)与文件查看,以及每轮回复结尾的「改动的文件」回执;收起后留窄条入口,≤860px 整栏不渲染(Todo 条改到输入区上方) — internal/runengine/{runviews.go,server.go}(GET /api/runs/:id/changed-files、GET /api/runs/:id/tasks)、web/src/{App.vue,ChatDock.vue,WorkspaceTree.vue,WorkspaceFileView.vue,RunChangedFiles.vue,RunTodoPanel.vue,TasksView.vue,ProjectsView.vue,markdown.ts,markdown.css}(doc/78;契约用例 65;2026-11-14 doc/79:文件视图里的 .md 按 markdown 渲染显示、默认预览态可切「原文」,排版走全局 .md-body 三处共用——纯前端、契约字节零变化)

2b. 表外创意池(不在原计划,从 Pi / Hermes 深度调研中挖掘)

以下能力不在原始 10 项里。从 Pi(~25 个独特功能点)和 Hermes(~90 个功能点)中精选, 按"对 tako 产品价值 × 面试叙事力 × Go 落地可行性"筛选。

上下文与成本创新

能力 来源 一句话 梯队
Prompt Cache 神圣边界 Hermes prompt_cache_boundary 把缓存边界作为一等公民——system prompt 的静态前缀由 builder 声明,LRU 上限 32 条/4MB,一切设计决策为缓存让路 T1
Surface 切换不重建 Prompt Hermes surface_switch 切 UI(桌面↔︎TUI)时保留 prompt 字节,surface 指引通过 per-turn user message 注入;220K 会话从 1% 缓存命中跳到 100% T2
微压缩(逐轮折叠) Hermes micro_compaction 把旧 user/assistant 轮次折叠为单条摘要标记;默认关闭因为会破坏缓存——揭示了压缩与缓存的根本张力 T2
缓存感知图片驱逐 Hermes image_eviction_policy 不按"保留最新 N 张"驱逐,而是按 provider 限制(20 张/24MB)批量驱逐,每次驱逐都破坏缓存所以最小化频率 T3

安全与护栏

能力 来源 一句话 梯队
智能审批(辅助 LLM 风险评级) Hermes approval_smart 用小模型评估 shell 命令风险(APPROVE/DENY/ESCALATE);关键细节:评估前剥离 shell 注释防注入 T1
过期覆写阻断 Hermes file_tools_write_guards agent 从未读过某文件的当前内容 → 禁止覆写,防止幻觉内容覆盖真实数据 T1
加密 Vault + 不透明句柄 Hermes vault_store + redact 密钥加密存储,模型只通过 opaque handle 交互,tool 输出经精确值 redaction 后才进上下文 T2
SSRF 防护 + DNS 重绑定闭合 Hermes url_safety 在 TCP connect 时重新检查策略(不只是 resolve 时);TUN 代理(Mihomo/Clash)fake-IP 白名单 T2
自仓库守卫 Hermes self_repo_guard 阻止 agent 对支撑自身运行的 git 仓库执行 checkout/rebase/pull 等破坏性操作 T2
ESTOP 紧急停止 Hermes estop 磁盘上一个哨兵文件,存在即停一切 agent 活动——最简单的安全兜底 T3

Agent 能力创新

能力 来源 一句话 梯队
树状会话历史 Pi tree-based session 对话像 git 分支——压缩 = 子树折叠,支持分支探索,Go 生态独一无二 T2
侧问题(/btw)+ 缓存对等分叉 Hermes side_question 回答旁支问题但不污染主上下文;分叉保持缓存对等(相同 prompt 前缀)不破坏主会话缓存 T2
编程式工具调用(PTC) Hermes code_execution_tool LLM 写脚本一次调多个 tool(而非逐个 round-trip);Unix socket 连持久会话内核,5 分钟超时/50 次调用上限 T2
混合代理(MoA) Hermes moa_loop 多个参考模型各出答案,最终模型综合;隐私过滤防止参考模型输出泄漏到主上下文 T2
后台审查分叉 Hermes background_review 独立后台子代理审查对话,提取记忆/skill——agent 在不阻塞用户的情况下变聪明 T2
模糊查找替换 + Unicode 归一化链 Hermes fuzzy_match LLM 生成的替换文本常有智能引号/em dash/NBSP 等偏差;有序归一化链逐级放宽匹配 T3
重复循环检测 Hermes repetition_guard 检测模型陷入重复动作循环并介入——防止烧 token T3

产品体验与差异化

能力 来源 一句话 梯队
成就引擎 Hermes hermes-achievements 50+ 成就,铜/银/金/钻/奥林匹克分级,多条件触发,隐藏成就——游戏化驱动使用 T2
桌面宠物 Hermes agent/pet 动画宠物反映 agent 活动状态;用户说"good bot"触发情感反应——让 agent 有"生命感" T2
Skill 使用追踪与淘汰 Hermes skill_usage / skill_ledger 记录每个 skill 的调用频次、token 消耗、成功率,自动淘汰低效 skill。前置的「技能包 + 加载事件」在 doc/52(2026-10-27 立项,已点头未施工):本期只做精确加载记录(从 runlog 的 load_skill/read_skill_file 行派生),不做因果归因与自动淘汰 T2
场景化 Eval 框架 Pi packages/evals + Hermes evals/ 不做通用 BLEU/ROUGE,按任务场景跑回归(完成率/步骤数/token 消耗)——方案 doc/45(2026-10-23 立项,待点头):场景 = 准备/动作/判定/证据四件套,判定按「锁在被测系统还是模型身上」分 K/S/B/C 四组、判定 = M=M(跑 M 次全过)、红的成因分归因(只有引擎回归与低于基线拦门禁),语料 = 17 条四组目录。另有 doc/83(2026-11-16 迁入 doc/ 的思路稿,待点头):把评测定成「给真实任务、重复跑多次、查任务结束后的真实世界状态、留完整轨迹」,与 Anthropic 的 Agent Eval 工程实践同调;与 doc/45 已拍板口径并存,取代关系待裁定,裁定前不动 doc/45 口径、不开工。外部基准选型见 doc/56(2026-10-31 立项;2026-11-01 第一批已施工、G1 已跑完出数、且装上 dsh 臂跑出两臂配对;11-02 凌晨 k=5 首轮基线跑完(tako Pass@5 24/25 · pass^5 20/25,dsh 23/25 · 14/25,§4.10):scripts/bench/——行 schema + 判定器(内置 GAIA 官方 scorer 三支,--selftest 对照官方源码)+ 切片配方与 slice_hash(题面不入库)+ 批量 runner(支持多臂配对)+ 报告;口径落纸在 doc/56 §4.7,GAIA 25 题两轮单臂实测出数在 §4.8:题面本身 2/25,题面 + 尾句 21/25——差的全在「答案长什么样」;两臂配对在 §4.9:tako 22/25 vs dsh 20/25,但同臂隔一小时重跑的逐题分歧率(7/25 = 28%)比两臂之间(6/25 = 24%)还大——换 harness 的影响不如把同一 harness 重跑一遍,所以这轮不给两臂排名):公开基准测的是模型 + 它自带的 harness,不是 tako;GAIA L1 25 题切片是唯一现在能直接跑 tako 的公开基准,SWE-bench 先在 Linux 服务器以 mini-swe-agent 跑模型基线(服务器 Docker 可用),tako 级等引擎镜像 + bash 容器后端(容器当围栏) T2
流式 TTS + 打断检测 Hermes tts_streaming 句子级分块流式语音合成;TTL 门控闩锁防快速重触发——全双工语音交互 T3

运维与可靠性

能力 来源 一句话 梯队
错误分类管线 Hermes error_classifier 20+ 类型错误(auth/rate_limit/context_overflow/image_too_large…)各映射到具体恢复策略 T1
辅助客户端自动降级链 Hermes auxiliary_client 主 provider → OpenRouter → 自定义端点 → 直连 API;402 欠费自动穿透到下一个 T2
多凭证池 + 模型级冷却 Hermes credential_pool 多 API key per provider,429 只冷却对应模型不影响兄弟模型——精细限流 T2
管道式进程死亡检测 Hermes mcp_death_supervisor 父进程死亡时管道读端立即 EOF——零 CPU 开销、瞬时检测,替代轮询 T3
透明文件系统检查点(影子 Git) Hermes checkpoint_manager 用独立 GIT_DIR/GIT_INDEX 做内容寻址去重检查点,不污染用户项目仓库 T3
生成围栏任务状态机 Hermes hosted_room_driver SQLite 持久化执行,generation-fenced 更新防过期写入;有界保留(30 天/2048 任务) T3
训练数据导出 Hermes trajectory export 把 agent 执行轨迹导出为 RL 微调数据集(数据飞轮) T3

外部对照引入(2026-11-03)

来源:按外部通用 Agent 能力清单对 tako 逐条对照得出的缺口分析(2026-11-03 引入,对照载体为本地材料,不入库)。与上面各组的差别:不是从 Pi/Hermes 调研挖的,是按外部岗位能力模型对出来的缺口;是否做、何时做均未拍板。

能力 来源 一句话 梯队
浏览器操作(Work Agent) 外部能力清单 DOM/无障碍树/截图理解页面,点击、输入、滚动、上传下载,每步操作后重新观察而不是盲跑脚本——tako 现有输入只有文本与图片,无浏览器回路 待评估
跨子代理产物黑板 外部能力清单 子代理之间经结构化产物(而非聊天记录)协作的共享区;现有 run_tasks 是单 Agent 看板,跨代理共享未建 待评估
run 级预算中断 外部能力清单 现有配额是租户日 token(§2c 闸在数据库);run 级预算(步数/token/时长)超限自动中断 待评估
受限自修改(RSI)实验 外部能力清单 固定评测集 + 沙箱内生成/评测候选 Harness 版本 + 晋级/拒绝/回滚;地基是 doc/45(场景化 Eval)与 doc/56(配对协议与 pass^k 基线) 待评估

2c. 横切契约(不是单条产品能力,但每个接口/每套存储都得遵守)

这五样是纪律不是功能:不做不会「少一个能力」,做了之后每个新接口/新存储位都得照着来。规则写在根 AGENTS.md,方案在这里。

契约 状态 是什么(人话) 落点
响应信封统一 ✅ 所有 JSON 接口,成功失败都回同一个壳:{"code":数字,"message":"弹窗文案","data":业务体}。code=0 是成功,非 0 是业务失败码;message 直接给页面弹窗;data 里才是这个接口自己的内容。HTTP 状态码照旧给网关分类用。两样不进信封:媒体(图片)的二进制成功体、SSE 帧面。 internal/runengine/{auth.go,server.go,mcp.go,product_api.go,archive_sweep.go,envelope_test.go}、web/src/{api.ts,chat.ts}(doc/40 A7-1…A7-8;码表在 doc/40 §4)
临时键形态 ✅ Redis 里的临时态收敛成四个键:tk:runlive(run 活着)与 tk:runepoch(这一轮是谁)随 run 生灭;tk:events:<tid>(租户事件流,doc/46)随租户生灭——易失通知:删除/改名成功后 XADD、MAXLEN ~1000 有界截断、租户归档时 DEL,丢了 client 全量拉追回真相(拉是正确性,流是优化);tk:agent-task-wake(doc/72)是 Task 调度器内部唤醒流,MAXLEN ~1000,只带「可能有工作」的诊断字段,丢事件由启动/定时 PG 对账兜住,不是审计存储、不分配给浏览器。tk:draft:* 退役——定稿正文的归属改由 turn 承载,run 存活哨兵改由 runepoch 承载,所以定稿路径不再读 Redis。 internal/runengine/{redisstore.go,store.go,server.go,worker.go,events.go,agent_task_scheduler.go}(doc/38、doc/46、doc/72 §8;存储真源 19v6-03)
闸在数据库 ✅ 所有「最多同时跑几个」这类闸都必须落在数据库里,不许留在应用层读-判-写。会话闸 = runs 表部分唯一索引 one_live_run_per_session(插入冲突 = 409 112101);租户并发闸 = AcquireRun 事务内的 pg_advisory_xact_lock + 活 run 计数(超上限 = 429 113001)。数与放行必须在同一笔事务、期间持一把所有副本共享的锁——否则两个请求都读到「还没满」就都放行(实测:上限 2 能进来 4 场)。判定数与放行的那两条语句不能合成一条 SQL:READ COMMITTED 下一条语句只拿一次快照,合成一条会拿到等锁之前的快照,照超发。 internal/runengine/{store.go,scope.go,server.go,product_api.go}(doc/43;会话闸见 19v6-03,租户闸见 doc/43 §4)
工作区结果发布协调 ✅(doc/74 已落地 2026-11-12) 并行 Task 的最终不可变结果经验证后才能发布回项目。引擎排除其他活 run,新 run 准入与发布标记共用项目级 PG 事务锁;Provider 检查项目是否已变化并执行对应 Git/Directory 发布。PG 只存通用结果版本、发布状态与执行/发布代次,不存 commit、分支或文件哈希;外部编辑器和用户终端仍是非合作写者。 internal/runengine/{store.go,pgstore.go,workspace_publish.go,workspace_result.go,workspace_provider.go,workspace_git.go,workspace_directory.go};已落地
重规划 handoff ✅(doc/75 已落地 2026-11-13) 继任组目录中的 handoff.md 用 frontmatter 保存 replanOf、复用 (taskId,resultRevision)、深度与次数,正文记录为什么重规划、为什么新建及不得重放的动作。程序读 frontmatter,人读正文;successor.json 未完整落盘前继任组停在 preparing、不调度,不把自由文本当机器契约。 internal/runengine/agent_task_{successor,handoff,tools,api,store,scheduler,delivery,runner}.go;GET /api/orchestrations/:id/handoff + POST /api/orchestrations/:id/successors;业务码 117004/117114/117115/117116
项目内容/运行资源分离 ✅(doc/76 已落地 2026-11-13) 项目目录拆成 content/ 与 runtime/:普通用户文件只看 content;异步 shared/isolated 工作现场、不可变结果、tmp、媒体与项目 MEMORY.md 归 runtime。中间结果不直接进 content,最终发布才进入;删除项目清整个容器,但租户技能/工具、系统技能与用户记忆不动。 internal/runengine/project_layout.go、scope.go、worker.go、workspace_*.go、media*.go、memory_markdown.go;DeleteWorkspaceCascade + CleanupProjectStorage + project_cleanups 补偿;离线迁移 cmd/yktako/main.go -migrate-project-layout
验收可机器重跑 ✅(两层在跑;第三层场景化 Eval 方案已出、待点头) 契约字节的期望不能只以散文形式存在。两层:快闸(contract_test.go——信封字节序、session/frames/log 响应字节、帧 kind 词表、业务码值;不打模型、不用 API Key,每拍收尾随 go test 跑)+ 活体(scripts/acceptance/——机器真源 expected.json + 断言器,红打 ❌、退出码非零)。散文版在 19v6-04,与机器真源同批改。第三层(场景化 Eval):前两层断的是"接口有没有按约定回",断不了"活有没有干完"——2026-10-23 PII 挂载点选错(只挂首轮→折叠后复活)时两层全绿。方案见 doc/45(2026-10-23 立项,待点头;判定分 K/S/B/C 四组——按「判定锁在被测系统还是模型身上」分,判定 = M=M(跑 M 次全过,M=5),不通过也逐次记录,红了再分归因:只有引擎回归与低于基线拦门禁) 前两层:scripts/acceptance/{expected.json,assert_contract.py,matrix.py,spotcheck.sh,check-expected.sh,taskboard_crash.sh,events_live.sh}、yk-tako-eino/internal/runengine/contract_test.go(规则见根 AGENTS.md「验收:两台机器,各管一段」);第三层:scripts/eval/(待建,doc/45)
变更端点发事件 ✅ 自 doc/46 起,「删除/改名/不可忽略的状态翻转」类端点成功后必须 publishEvent(XADD tk:events:<tid>,只带 {type,id}、不携带状态),或显式登记不发的原因;事件流是优化不是真源——客户端收到后让本地失效、永远跟一次重拉,PG 才是真相(前端失效逻辑在 web/src/mutation.ts,广播与 SSE 两个源同喂一个 dispatch)。持久 Task 的两类事件(agent_tasks_changed/agent_orchestrations_changed,doc/70)与 SSE 心跳、last_event_id 续读见 doc/46 §7.7。 internal/runengine/{events.go,product_api.go,agent_task_*.go}(doc/46 §3.3/§4/§7.7;用例 9 的活体判红在 scripts/acceptance/events_live.sh,字节快闸 TestContractStreamEventBytes)
等人现场落库 ✅ run 中途要向人要素(ask_user 追问、submit_plan 方案审批)时,不许用进程内阻塞等:先落 run_questions 一行(kind/status/tool_call_id/args + CAS 一答终答),再发 kind=question 帧,worker 轮询库里的行;进程崩了由 resume 重放 journal + 行状态接回现场(pending 重发帧接着等、answered 把答案注回、无行才回中断文本)。多副本下谁跑 worker、人在哪个入口答,都靠这张表对齐。 internal/runengine/{questions.go,waittools.go,journal.go,worker.go,server.go}、web/src/chat.ts(doc/47 §3、§5;崩溃活体 scripts/acceptance/question_crash.sh)
同一详情抽屉两处打开时定位互斥 ✅(doc/77 2026-11-13 落地) 任务页与对话页右侧面板复用同一个 TasksView 与详情抽屉,而对话页是 v-show 常驻——切到任务页时对话页 DOM 仍在。两处必须各持一份定位参数(taskFocus / dockFocus)与各自的 nonce:左侧处理项只写任务页那份,面板只写自己那份。共享一份会让隐藏页面消费同一 nonce,Teleport 出一张重复抽屉。 web/src/App.vue(taskFocus/dockFocus);后端无改动
同一份内容在多处显示 ✅(doc/79,2026-11-14) 同一段内容要在两个以上地方显示(聊天气泡与项目里的 md 文件都渲染 markdown)时:样式只写一份——放全局样式表 + 一个中性类名(.md-body),不许把某个组件的 :deep() 段抄进第二个组件(Vue 的 scoped 样式不跨组件,抄过去一条都不生效);状态各管各的——「原文/预览」这类看法状态按内容所在的容器记(对话页切文件复位、项目页按文件名记表),两个入口互不影响;容器专属的覆盖留在原处(深色用户气泡的反色覆盖不进共享表)。 web/src/markdown.css、web/src/markdown.ts(renderSafe(text, opts?)、MD_BODY_CLASS)、web/src/{App.vue,WorkspaceFileView.vue,ProjectsView.vue}(doc/48 §10)

3. 当前重心:子代理(#5)

2026-10-22 状态:本节是立项时的思路留档。子代理已落地(doc/17 §6、doc/23、doc/25、doc/26),并补上持久档案与 resume(doc/39);「下一步动作」里的 doc/17 已产出,施工真源由 doc/25 取代。当前未做项见 §0.1 与 §2 的 ⬜/🔶 行。

要解决的问题:某些 tool 会把主 agent 上下文撑爆(疯狂刷 tool 输出、读大文档、翻一堆文件)。

Octop 的答案(=要什么):

tako 怎么做(=Eino 落地,待出实施计划):

下一步动作:去 harness-pkg/harness-agent + Eino ADK 摸清"子 agent 以 tool 挂载 + 上下文隔离"的落地方式,出 doc/17-子代理实施计划.md。

4. 借鉴 WeKnora 的护栏(对话 → RAG / 记忆)

用户明确:想把 WeKnora 偏"通用 agent"的能力借鉴过来(例如把对话内容存进 RAG 供后续召回),但不想让 tako 变成 WeKnora 那种以 RAG 为定位的项目。护栏如下:

  1. 正本永远是结构化存储(event_log / messages 表),向量库只是可重建的派生副本——用于语义模糊召回,不用于精确回放/审计/恢复。(依据:WeKnora 里 embedding 模型一旦索引不可换、需重建,删会话时两侧同步清理)
  2. 双写是手段不是目的:结构化表管"精确、按序、可恢复",向量库管"语义召回",两种查询模式互不替代,所以才双写(承 §Q:为什么双写)。tako 引入 RAG 时沿用这个分工,但只在"agent 需要回忆历史"这一场景服务 agent,不做面向用户的知识库检索产品。
  3. 召回结果进 agent 上下文,不进 UI 主流程:RAG 是 agent 的一个 tool / 中间件("记忆召回"),产出喂给模型,而不是把 tako 的界面改成"搜索框 + 文档列表"。
  4. 可延后、可关:RAG / 记忆属于 #6、#10,排在子代理之后。没落地前 tako 已是完整可用的 agent;落地后也应能通过配置关闭,退回纯结构化存储。

5. 排序与纪律

2026-10-22 状态:下面的排序保留立项时的顺序作为历史;T1 三项(#5 子代理、#6 记忆、#4c 用量)的主体均已落地(#5 的 T4/T5 已于 2026-10-20 落地,#5b 的持久档案与 resume 已于 2026-10-21 落地)。当前待做项以 §0.1 与 §5.1 为准。

按梯队排序(与 §2 梯队列对应):

T1 · 核心 + 面试杀手锏(先做):

  1. 子代理(#5) ← 当前重心。借鉴 Pi 工具即子代理挂载 + Hermes skills_hub 注册/演化
  2. 记忆(#6) — 子代理做完后紧接着。借鉴 Hermes learning_graph 经验归纳 + memory_provider 分层
  3. context_usage(#4c) — 与子代理配套补齐。media_offload(#4b)旧线已提前做完(代码随翻篇删除);v6 重做已落地(doc/32,2026-10-21 收口)

T2 · 创意差异化(核心做完后挑有趣的做): 4. 树状会话历史(§2b)— 借鉴 Pi tree-based session,压缩 = 子树折叠,Go 生态独一无二 5. Skill 使用追踪(§2b)— 借鉴 Hermes skill_usage,子代理/skill 的调用频次与淘汰 6. 场景化 Eval 框架(§2b)— 借鉴 Pi evals + Hermes 场景化 evals,按任务回归而非通用指标

T3 · 基础设施 / 延后: 7. 崩溃续跑(#7c) — 已落地(doc/30 A1–A5 + A8 前端 reattach,2026-10-21);server 端 自动巡检裁掉,恢复走客户端触发(显式「继续这一轮」按钮) 8. IM / cron 入口(#8b) 9. 多用户多 Agent(#9) 10. 对话→召回(#10)— 受 §4 护栏约束;PG 词面全文检索方案并入 doc/29(语义召回已裁,2026-10-18)

明确不做 / 暂缓:

纪律(承 doc/05 §4):

5.1 当前待做(2026-11-16)

排法:先补地基(能不能给别人用),再补外围(好不好用),最后补差异化(值不值得讲)。 2026-10-23 变化:原第 1、2 项(PII 脱敏、v6 任务看板)已落地(doc/41)→ 从待做里划掉;三处前端欠账已落地(doc/44)、界面可用性欠账 17 拍已落地(doc/48)、随后第二次走查的 12 项缺陷已落地(doc/49)→ 一并划掉;「人工审批」不在列表里——它已被拍为不做(越界由沙箱围栏硬挡,doc/33、doc/41 §3.1);商业化那一档(团队计费 / API key / SSO / 组织共享 / 审计导出)也不在列表里——2026-10-22 用户裁不做、移出路线图(doc/28 §15),2026-10-23 复核维持(理由:与运行时关系不大的商业化、合规项)。

序 待做项 能力号 依据 为什么排这个位置
1 IM / cron 入口 #8b §2b Hermes transports/ 多入口的第二个入口;也是 doc/30 §12「无 client 可触发」那类场景的素材
2 多 Agent 协作 已落地(2026-11-10) #9 doc/70(Comma 持久 Task / Hermes 依赖调度 / Octop 同伴互调三参照) 持久 Task + 固定 DAG V1 已施工验收:活体五场 + 浏览器停止/恢复链;动态改图留下一版
3 多 Agent 下一阶段 已落地(2026-11-11) #9 doc/72 有界计划修订(含累计预算与版本审计)+ Task HITL(含等待超时)+ 左侧“需要我处理” + 事件唤醒与 30 秒 PG 对账;契约用例 51–54 + 活体四场(修订 68、HITL 48、处理项 39、唤醒 14)+ V1 五场回归 + 浏览器四类处理项与修订时间线走查全绿
4 协调通知与交付恢复(✅ 2026-11-11 已落地) #9 doc/73 区分执行失败与交付失败;崩溃同 run epoch+1 续跑、error/停止由人工创建新处理尝试(agent_notification_attempts 审计);结果文件定位、通知消费确认、交付只读工具面、旧执行者防写与双副本防重;失败详情/人工重试端点 + 前端恢复闭环
5 并行任务工作区隔离(✅ 已落地 2026-11-12) #9 doc/74 LLM 决定编排与隔离需求;Provider 按真实项目选择 Git worktree 或非 Git 目录副本;引擎负责创建、结果验收、发布与恢复。Task/PG 不含 Git 内部字段,Provider 状态和不可变结果在共享持久卷;含双副本、崩溃、项目变化与部分发布验收。默认 shared 不变;活体四场 + 契约 57–59 + 70–73 回归全绿
6 目标重规划与继任编排组(✅ 已落地 2026-11-13) #9 doc/75 先判目标可行性(goalAssessment.outcome),再选 doc/72 同组修订或继任组;handoff 文件保存 replanOf、原因与结果复用,原组先收口、预算不重置、外部副作用不自动重放;不可行时告诉用户,不创建新组。与 doc/76 合并一个施工包:活体 goal_replan 124/crash 46 + 契约用例 61–63 + 双副本并发(一条继任行、202/409 117114)
7 项目内容目录与运行资源容器(✅ 已落地 2026-11-13) #12 doc/76 用户只看 content,异步工作区/结果/tmp/媒体/项目记忆归 runtime;shared/isolated 中间结果均不直接进 content,最终发布才写入;存量复制校验后切换(离线命令),删除整个项目容器,不误删租户与用户资产;用户级 skill/plugin 不做。活体 layout 36/迁移 51/项目删除 10 + 契约用例 58/60 + 74 回归 publication 34 全绿
8 §2b 创意池:树状会话历史、Skill 使用追踪、场景化 Eval(方案 doc/45 待点头) §2b Pi / Hermes 差异化叙事;其中场景化 Eval 是回归的地基,别放到最后
9 可组合执行原语与后台任务(✅ 2026-11-15 已落地) #1 / #9 / #17 doc/82 bash 30 秒从进程总寿命改为前台等待窗口(超时转后台 job 返回 bj_…),补输出读取/有限等待/停止(SIGKILL 整进程组)/持久通知与多副本失联处理(owner watcher 续租写终态 + sweeper 对账 interrupted);wait_task 就地认领通知(claimed_in_place=true,不建 run、不写 attempt 行)避免重复交付;DAG 继续按真实依赖创建与修订,不新增用户模式或 JS 引擎;组内并发按 workspace_mode 取值(shared=1、isolated=2);页面补路径账本 GET /api/orchestrations/:id/journey(只读投影:计划版本、失败/取消节点、结果复用、交付尝试,刷新与换副本一致);契约用例 82–83 + 活体四脚本 + spotcheck 37/0 + 浏览器走查全绿

2026-11-07 立项:记忆按读取契约分两层——常驻「必见」、召回「用到才见」——但并表:notes 并入 memory_items,layer 列(resident|recall)分流,查询只许打 resident_notes/recall_items 两个视图;两层共用一条 scope 归属轴(user|workspace|tenant,产品语言的 project 即 workspace),kind 全撤(常驻预算并为一档 2200 rune),管理面一个端点两 tab、两层都开手工 POST;方案 doc/65 已成文、待点头。它不翻现有能力表(记忆仍标 ✅),落的是「常驻层删了不会从召回层复活、召回层同一件事只留一行、改口可追、过期能退场、用户能删」这条质量线;施工前不进上表排序。同日五稿(用户指示后回填):① 记忆线的删除归属定了——不再「不动」,随项目连带删清,doc/37 补 D-l(未施工);② 相似度判定整体搬到 PG 的 BM25,Go 侧不再切中文词;③ 证据时间不新增列,由 source_run_id → runs.finished_at 推导;④ 八稿并表(用户拍):两表合一、layer 分流、kind 全撤、scope 统一、写入线判定标准单源、管理面合并——原「不并表」裁定作废,以 doc/65 八稿为准;⑤ 九稿补第二路消费(用户拍):search_memory 工具——as_of 时点回放(Graphiti 查询语义,落为我们的列:认知期 created_at+翻转时刻、现实期 valid_from 新增+expires_at∪supersede 链)、include_history 历史链遍历,纯 SQL 无额外 LLM 调用。十稿(同日,用户质疑后采纳):召回时机从「run 起手一次」改「每个用户回合一次(含首句)」,注入块按回合追加、常驻快照不动。十一稿(同日,并发写裁决):同分区写用 workspace 级 advisory 锁串行化(扩到场后判决事务),锁外真并发由证据时间(runs.finished_at+source_seq,对话位置)裁决谁最新、created_at 只作展示排序——用户设想的「多写者并发、到达反转」场景由锁 + 证据时间双保险兜住。十二稿(同日):在场写入按用户指定的 master/subagent 分界落地——master 判需 → 派抽取子代理(读历史 + LLM 分析 + 写库),与用户明说「记住」的同步直写并存;子代理不替代场后判决管线(并发子代理互不可见,三层兜底照旧)。

2026-11-08 需求登记:子代理级模型配置——每个 agent 可配自己的模型(doc/65 十三稿的 B2 抽取子代理是首个新消费者:单轮 search + 判决,适合挂便宜模型)。后端已有此位:AgentProfile.ModelRef(agents.go:638,profile 设了就生效、没设继承主模型);缺口 = 管理 UI 没有改它的入口(出厂 agents/*.md 规格里也没有模型字段)。方案未成文——落在记忆改造的施工里顺手做,或单独立项,用户定。同日十四稿:B2 派工队列化——master 判需 = 登记 memory_jobs(kind='inrun'),worker 领活才派抽取子代理 run;背压(在跑上限 4)、崩溃恢复(租约重领 + ON CONFLICT 幂等)、派工成本降到一次 INSERT;新增出厂规格 agents/extractor.md。十五稿(同日):领取以「结果保序」落地——反连接领取被否(用户拒绝复杂 SQL),改平查询(SKIP LOCKED),同 session 乱序只产生瞬时双写、由写锁 + 证据时间 + 场后管线对齐最终结果;scope 不进锁/队列 key(锁 key = workspace,三种 scope 同锁串行);用户设想的「session 求余分区」不落物理队列;MQ(asynq)为可选叫醒信号(payload=job_id、真相在库、默认关),开物理队列时形状 = Redis 分 key + 消费者拉起抽取子代理 run。十六稿(同日,用户拍「不要数据库当队列」):派送移 asynq(Redis)——queue = memory:{hash(session)%8} 求余分区、单消费者顺序处理(执行保序回归);memory_jobs 只做状态账本(消费者先原子认领 DB 行、幂等挡重复投递;attempts 管 1/5/30 退避与 3 次 failed,asynq retry=1 防双头重试);对账器 day one 兜底 INSERT+send 双写(超龄 pending / 租约过期 running 重发);换队列 = 换 enqueue/consumer 两个函数,换数据库不再威胁队列。消费者是独立 run(分析逻辑与引擎解耦、不占主上下文、可崩溃续跑);trace 透传——job 带 source run/session/seq 与 tenant/user/workspace,OTel trace context 从生产 run 传到消费 run(doc/54)。22 条重复的计数口径、RAG 关掉时的召回行为、schema 迁移路径三处本轮不写。

2026-11-09 · doc/65 现行方案重构:上面 2026-11-07~08 两段只保留为演进记录,施工口径以 doc/65 本稿为准。记忆改为两种独立模式:pipeline = PG memory_items 两层 + 统一抽取代理 + Redpanda;markdown = 用户 USER.md 与项目 MEMORY.md 同步直写,不启动抽取/MQ。取消记忆管理面与管理 API;inrun 由 master 登记 target_layer,postrun 永不写常驻;证据时间改取原话 runlog_entries.created_at,不再取 runs.finished_at;项目删除只清 scope='workspace' 记忆、保留 user 行。Redpanda 负责正常路径按 session 分区顺序,PG memory_jobs、postrun 前置条件与对账器负责故障正确性;候选全量扫描但按 token 分批,写事务用 workspace advisory lock,幂等不再依赖正文去重。Markdown 采用 Hermes 式锁内重读 + 操作式修改 + 原子 rename,多副本用 PG advisory lock;Rakazo 的真实内置存储已核为 PG document + revision。方案仍待点头、未施工,不翻现有能力表状态。

2026-11-09 · 文件写入竞争方案:新增 doc/71(待点头、未施工),把「写者互斥、写入依据新鲜、读者只见完整文件」拆开:普通共享写入采用短锁 + 版本校验 + 同目录临时文件原子 rename;多副本协调可用 PG advisory lock,但不把 PG 事务说成能回滚文件系统;长并行 coding 任务归 doc/70 评审独立 worktree + 显式合并,不引入 CRDT。doc/61 仍是当前已落地机制说明,doc/65 的 Markdown 记忆文件消费同一原则;bash/外部编辑器的非合作写边界明确保留。

2026-11-10 · doc/65 + doc/71 短写入落地:记忆双模式与文件短写入三件套施工、活体验收完毕。pipeline = 两层 memory_items + Redpanda 按会话分区派工 + 消费者三段流抽取(extractEntries → screenCandidates → finalActions)+ 候选全量扫描 + workspace advisory lock 写事务 + 1/5/30 分钟退避三次失败 + 对账器补投;markdown = USER.md / MEMORY.md 同步直写、不启动抽取/MQ/BM25;两模式互切 = 改 TAKO_MEMORY_MODE 重启(存量迁移在启动装配期跑)。观测口 items/jobs/recall 的字段集换代、markdown 模式统一 409 118001(不返回空数组)。同批:doc/37 D-l 落地(项目记忆按 scope 随删);write_file/edit_file/记忆文件写盘统一走 atomicfile.go 原子替换。机器真源:expected.json 用例 35–38 + 快闸 TestContractMemoryObserveBytes;活体六件在 scripts/acceptance/memory_*.sh(pipeline_live 20/20、markdown_live 26/26、migrate_live 42/42、file_race 11/11、project_delete 9/9、redpanda_crash 真 broker kill -9 补投)。

2026-10-24 增补:界面这一格开始还账——doc/50 的侧栏二级树已全部落地(A1–A4 2026-10-24、A5 2026-11-15 收口),doc/51 的视觉重做 U1–U7 已落地(token 层 + 中性现代风 + 侧栏三段式 + 三页骨架 + 气泡统一 + 手机抽屉,四档实测见该篇 §7)。两篇都不新增能力、不改后端契约,所以不进上表;它们决定的是「地基已通的能力,人看不看得见、用不用得顺」。

2026-10-28 立项:技能(Agent Skills)方案 doc/52 已成文、已点头;A1–A4、B1–B8、C1–C5、D1、E1、E2、F1、F2、F3、G1 已落地(2026-10-28),24 拍全部收口。B1 让技能第一次被模型看见:<available_skills> 目录只拼 manager 的 Instruction,read_skill/use_skill/read_skill_file 三个工具进 manager 池(本拍占位统一回 116001),普通子代理在入口快照里被剔掉四个保留名;帧与 runlog 同时带上 toolCallId。B2 让正文真的读得进来:read_skill 按名字查本租户视界内的行、过禁用闸(116107)、读盘剥 frontmatter、把 &/< 转义后包成 <skill name source bytes>…</skill>(不带 path;bytes 是技能目录里普通文件之和);超 16,384 token(cl100k)或 64KB 回 116116、不截断,计数器由技能工具自己持(-compact-window=0 时照判);名字查不到与别的租户同名都回 116001,存在性不跨租户泄漏。B3 让技能根真的可用:use_skill 成功即把该技能根只读放进本场围栏(盒子按 run 从空起、写仍只在项目根、隔壁没 use_skill 过的技能看不见、普通子代理拿空盒),同时放开 bash 出站网络(入站不开;租户 MCP 走同一条 profile,/private/etc/ssl 只读让 HTTPS 能起;顺带修了 -workspace 相对路径时租户 MCP 全被判围栏外的隐藏 bug)。它补的是「流程知识放哪」:本地 Markdown 包 + run 装配时的目录(只进 manager)+ manager 自己读正文、自己执行(2026-10-28 翻案,取消内置 skill agent),正文里的步骤展开成看板任务——正文是说明书、任务是替身,压缩时正文可折、任务不折,任务按会话可读上一场(D34:TaskList 带上一场未完成行与说明,用户续做时说的「第 3 步」就是看板的 #3);普通子代理不读也不执行技能;目录由 PG 的 skill_rows 提供(系统技能与团队技能都在共享 PVC 上,run 装配不扫盘,盘上偏离靠 rescan);不做技能市场、目录不截断(成本只有作用域/禁用两把闸,不做技能搜索);安装入口认上传包、来源串与 npx skills add … 命令串(解析后原生抓取,不执行 npx)。缺依赖有得补(2026-10-28 第十四轮,D36):owner/admin 可经 /api/tools 上传单个可执行文件到租户工具根(文件级校验、不执行不探测),工具根按租户常开(所有角色含普通子代理可用),技能根仍按证据收窄——团队自己补 ffmpeg,不必等运维;2026-10-28 第十五轮:bash 围栏放开出站网络(D37,租户 MCP 一并生效,入站不开),use_skill 返回时现查 requires 并在标签上给 missing(D38,缺了不阻断开读,只提示「请管理员上传」);B4 让资源真的读得进来:read_skill_file 在这个技能的资源根内解析 path——拒绝对路径与任何一段 ..,EvalSymlinks 后判包含(软链跳根同 116114),入口 SKILL.md 用 os.SameFile 认出并指向 read_skill,目录回不递归条目、文件回 {name,path,type,content,bytes},超 64KB/16,384 token 报 116115 且不带部分内容;GET /api/runs/:id/skills 从 runlog 真派生(toolCallId 配对、seq 排序、path 只在 read_skill_file 行)。B5 让任务记得自己替谁办事:run_tasks 加 skill_name,TaskCreate 时按本 run 最近一次 use_skill 盖戳(read_skill 不盖、use_skill 后没建任务就一行不多),看板每行带「(技能:名字)」、kind=task 帧带顶层 skillName——D34 的跨 run 续做与 D35 的执行权恢复从此有索引可用。B6 让看板跨 run 接得上、执行权跟着看板回来:TaskList 的读侧再拼一段「上一场」(最近一场的未完成行 + 说明:description;全完成只一行提示),写回执与 kind=task 帧不带;run 装配时按看板里已有的 skill_name 把技能根补回 bash 盒子(续跑查本 run、新 run 查上一场,逐项重判 valid/未禁用/盘上根在),「已经生成 todos 就继续跑,还没生成就重新加载」有了确定性判据。第十六轮:子进程 PATH 只留围栏读得到的目录(D39,围栏外解释器报 command not found 而不是 Operation not permitted)。D1 让依赖从「存着」变成「三处同源地用」:use_skill 成功标签带 requires="…" missing="…"(read_skill 逐字节不带;missing 是调用那一刻现查、不阻断),列表/详情的 missing[] 与它同源,GET /api/skills/:name/check 回 {dependencies:[{name,found,path?}],checkedOn:"host"}(安装响应用同一形状);PATH 与沙箱 profile 共用 sandboxReadRoots,检查说找到的可执行文件与 bash 解析到的是同一个(D39)。E1 让「看得见哪些」变成可收窄的配置:manager 那一行的 md 可写 skills:/exclude_skills:(JSON 面 skillPolicy,存进 skill_policy 列),二选一、同写拒载;作用域在装配期过滤目录,并在 read_skill/use_skill/read_skill_file/D35 看板恢复四处解析时点同判——范围外的名字与「表里没有」同回 116001 同字节;普通子代理写 allow/exclude 在入口 400(md 导入与 JSON 同判),显式 inherit 放行;skills: [] = 一个都不要;活体抓到 UpdateAgent 漏写该列的洞并补回归测试。E2 让「不用它」也能被明确表达:PATCH /api/skills/:name 只往 skill_disables 写一行/删一行(两方向都幂等),不碰 skill_rows、不碰盘;目录装配与三个技能工具读同一张表——禁用后目录里没有它、点名调用回 116107「这个技能已被禁用,请先在管理页恢复」;正在跑的 run 技能盒子不回缩(已开的执行权不中途收回);写面 owner/admin,viewer 403、未登录 401;禁用/恢复各发一条 skills_changed(doc/46 §7.6 字节 {seq,type,id,at},不带 action);删除技能同一事务连坐清禁用行,重装同名回 enabled:true。F1 让「缺个 ffmpeg」有入口:GET/POST/DELETE /api/tools 把一个可执行文件落到 <tenant>/tools/<name>/bin/<name>(0755),工具根不进表(列表就是扫盘,跳过 . 开头——半成品不能被用);128MB 上限 413 116118、名字白名单+预留名 bash/sh/env+空文件 400 116117、ReserveStorage 额度 429 113001;staging→.trash→rename 与技能安装同一把锁;写入 owner/admin、列表全员可读;删除先过白名单;成功后发 tools_changed。方案已点头、落地前不进上表排序。F2 已落(2026-10-28):工具根对所有角色常开——<tenant>/tools 整棵进 bash 围栏的只读白名单(写仍只在项目根),每个 <name>/bin 前置进子进程 PATH(跳过 . 开头,宿主 PATH 用同一份围栏读根过滤),依赖检查同走这条——所以装上的工具当场能用、which python3 仍解析宿主那个,普通子代理跑 hello 成功而技能根对它照旧关着。F3 已落(2026-10-28):管理页多了「工具」区——列表带「被技能引用」、上传(同名覆盖先确认)、删除,技能详情里缺哪个依赖就点「上传 <名字>」跳过来预填;页面不提供「检测」,能不能跑仍由 run 里的 bash 回答。

已拍不做 / 远期缝:团队计费 / API key / SSO / 组织共享 / 审计导出整批不做(2026-10-22 用户裁,与运行时关系不大的商业化、合规项,移出路线图;doc/28 §15——2026-10-23 复核维持。注意:API key 与 SSO 是"对外卖 / 进公司大门"的门,不是运行时的门,真要卖再翻案,底座不差:本地账号/membership/审计表都在,tenant_usage_daily 已按租户按天记用量);hosted mode 不接(19v6-06 裁定,client mode 是终态底座);扫描件 OCR 与音视频不做(doc/32);文件短写入的版本校验与原子替换已随 doc/71 落地;MQ 同步写入只记不做。

6. 关联文档索引

完整索引见 doc/README.md;以下是本文直接引用的文档。逐篇的状态与代码落点在 README §1(那才是目录页),本文只做能力视角的指向。

v6 运行引擎文档集(契约与存储真源):doc/19-v6 — 19v6-01 契约(四个 API 的请求/响应字节)、19v6-02 reconcile 与双游标、19v6-03 存储形态与生命周期、19v6-04 验收(curl 手打)、19v6-05 tool loop(T 系列)、19v6-06 工具分级与 deferred tools、19v6-07 compact、19v6-08 文件工具族(F 系列)、19v6-09 溢出修复层、19v6-10 mid-run fold、19v6-90 演进记录。

能力分篇