tako 文档 GitHub

模块地图

性质:结构索引,不是方案——本文只回答「有哪些模块、每个模块落在哪些文件、干什么」。 最后核对:2026-11-16(代码基线 a3ee354)。 口径:一层 = 顶层模块(谁负责什么);二层 = 小模块(落点文件 + 一句话职责)。 代码路径均相对 yk-tako-eino/;文档路径相对 doc/。 本文与 doc/README.md(目录页)分工:README 说「哪篇文档能施工」,本文说「代码在哪一块」。四张系统说明页在 线上架构总览(本地 doc/assets/tako-architecture.html)。

0. 一眼看全

0.1 顶层模块

# 顶层模块 位置 负责什么
1 运行引擎 internal/runengine/ HTTP、run 生命周期、工具、同步子代理、持久 Task、后台命令、记忆与项目文件
2 模型与配置 internal/config/ 厂商目录、环境变量发现、模型客户端构建、系统提示词
3 可观测装配 internal/observability/ OTel 出口、内容序列化与采集开关
4 服务入口 cmd/yktako/ 唯一入口:工程参数、依赖连接、引擎与后台对账循环起停
5 出厂子代理规格 agents/ coder / researcher 的 Markdown + YAML 规格
6 前端 web/ Vue 3 + Vite 工作台:对话、项目、任务、文件、技能、工具与团队
7 验收与运维脚本 scripts/ 开发环境、远端同步、文档检查、契约与活体验收、基准与海报导出
8 文档体系 doc/ 现行方案与结构索引;log/ 是记录,archive/ 是整代归档

0.2 规模(本次实盘点,取约数)

部分 文件与行数
Go 非测试代码(internal/ + cmd/) 127 个文件,约 5.35 万行;其中 runengine 120 个约 5.20 万行
runengine 测试 106 个文件,约 3.30 万行
前端 web/src(Vue / TS / CSS) 29 个文件,约 1.71 万行
前端 web/test + web/e2e 12 个文件,约 1200 行
活体验收 Shell(不含 Python 机器真源与共享库) 39 个脚本,约 7600 行

规模只用于理解仓库形状,不作为质量指标。runengine 仍是单 Go 包、文件平铺;下面的小模块按职责划分,不表示真实目录层级。

1. 运行引擎(internal/runengine/)

1.1 运行时装配与模型密钥

小模块 落点 干什么
RunProfile 装配 profile.go 为一场 run 拼模型、工具、MCP、技能、子代理和记忆边界
模型解析 tenantmodel.go 租户模型表 → 生效模型 ref → 可调用模型实例
密钥密封 secretseal.go API Key 落库前加密、使用时解密
数据范围 scope.go 用户/租户/项目/会话范围、目录寻址、容量与存储额度
会话可见性 session_access.go 按属主与租户判定会话可见、可写与列表范围

方案:doc/28、doc/34、doc/42

1.2 身份、团队与产品 API

小模块 落点 干什么
认证与响应信封 auth.go access/refresh、中间件、业务码与 code → message → data
身份存储 identity_store.go 用户、租户、成员、refresh token、日用量
成员与审计 members_store.go、tenant_api.go 成员角色、邀请以外的成员管理、审计读写
产品面 API product_api.go、product_store.go 项目、Agent 配置、邀请、运行时配置、模型预览与 dev 探针
技能与工具 API skills.go、skills_scan.go、toolroots.go 技能目录/重扫/禁用与租户可执行文件管理
记忆观测 API server.go、memory_store.go pipeline 的条目、作业、召回观测;不是已取消的记忆管理面

方案:doc/36、doc/40、doc/52、doc/65

1.3 run 生命周期、帧与客户端读取

小模块 落点 干什么
路由与 run API server.go 创建/停止/续跑 run,拉帧、run SSE、session 与 log、媒体出口
执行权与定稿 store.go AcquireRun / EndRun / StopRun / RenewLease;唯一运行、租约、容量事务
Redis 临时面 redisstore.go tk:runlive:<runId> LIST 与 tk:runepoch:<runId> STRING;帧读写与代次检查
worker 与 tool loop worker.go、tools.go、agentlog.go 装配输入,模型—工具循环,写帧、结果与终态
journal 与恢复 journal.go、resume_subagent.go run 逐步意图/结果与重放;后者负责同步子代理完整档案恢复
账号变更事件 events.go tk:events:<tid> Stream、tk:agent-task-wake Stream 与账号 SSE
run 只读视图 runviews.go 本轮 Todo 与改动文件 HTTP 投影,不改变执行行为

方案:doc/19-v6、doc/30、doc/31、doc/46、doc/78

1.4 上下文、媒体与历史查询

小模块 落点 干什么
compact compact.go 窗口预算、分阶段压缩与摘要输入
mid-run fold midfold.go run 与子代理中途折叠
溢出处理 guard.go、overflow.go 溢出识别、救援压缩与有限重试
文件/技能记录继承 fileops.go、skillops.go、skillslim.go 从真实调用记录继承路径与技能操作,不依赖模型记性
媒体 media.go、media_send.go、media_tokens.go 媒体落盘、按需回填模型与 token 估算
PDF pdftext.go、pdftool.go 读取 PDF 文本层,不做扫描件 OCR
会话历史与网络检索 search.go、websearch.go、webfetch.go search_history、web_search、web_fetch;全文落盘
延迟工具发现 toolsearch.go BM25 检索 deferred 工具并按需激活

方案:doc/19-v6/19v6-07、doc/32、doc/57、doc/58

1.5 工具、沙箱与同步子代理

小模块 落点 干什么
文件工具 filetools.go、readwindow.go 读写、编辑、目录、搜索、分页读取与媒体文件读取
文件短写入 filelock.go、filefp.go、atomicfile.go 锁内版本校验、PG advisory lock、本机降级与同目录原子替换
bash 与输出 bash.go、bashspill.go 前台执行、输出尾部与全文路径;后台生命周期见 §1.8
沙箱与 PATH sandbox.go、subprocesspath.go macOS seatbelt / Linux bwrap、技能与工具根只读范围、PATH 过滤
MCP mcp.go、mcpconf.go stdio MCP、工具命名与进程围栏
同步子代理 agents.go 规格加载、工具策略、同步派发与结果折叠
子代理 wire subagent_wire.go 会话目录 .tako/subagents/<sa>.jsonl 追加式档案
PII pii.go 工具出口、模型输入与记忆入库前的脱敏与密钥拒收

方案:doc/23、doc/25、doc/33、doc/39、doc/41、doc/71

1.6 技能、Todo 与等人记录

小模块 落点 干什么
技能工具与范围 skilltools.go、skillscope.go、skillbox.go 读取/使用技能、资源读取、作用域与当前 run 可只读技能根
技能安装 skillinstall.go、skillsource.go、skillfetch.go、skillresolve.go 包上传、来源解析、SSRF 防护、预览与安装
依赖与恢复 skilldeps.go、skillrestore.go requires 现查与续跑技能范围恢复
对话内安装确认 skillask.go staging → run_questions(kind=install) → 管理员确认后装盘
run 内 Todo tasktools.go run_tasks 与 TaskCreate/Update/List/Get;不是持久 Task
等人与 Plan questions.go、waittools.go、plangate.go ask/plan 持久现场、答案 CAS、计划模式写限制与恢复

方案:doc/41、doc/47、doc/52

1.7 记忆与对话召回

小模块 落点 干什么
模式与类型 memory_mode.go、memory_types.go、memory_store.go pipeline / markdown 选择、表模型与观测读取
pipeline memory_pipeline.go、memory_write.go、memory_text_guard.go resident/recall 写入、候选筛选与最终动作
派送与消费 memory_queue.go、memory_dispatch.go、memory_redpanda.go Redpanda 按 session 派送、消费、租约与对账补投
查询与召回 memory_search.go BM25、search_memory 时点与历史链
Markdown memory_markdown.go USER.md 与 runtime/memory/MEMORY.md 同步操作式写入
迁移 memory_migrate.go 旧 memory_items 与 notes 迁移、模式互切;notes 随后退役
对话块 dialogue.go dialogue_chunks 原文块与两种模式共用的召回线
常驻记忆快照 notes.go run 起手渲染并冻结常驻快照,两种模式各有来源;旧 notes 表与写入端点已退役

方案:doc/65、doc/29(线二仍现行)、doc/37(按 scope 删除)

1.8 持久 Task、编排、交付与后台命令

小模块 落点 干什么
Task 模型与图 agent_task_types.go、agent_task_graph.go、agent_task_store.go 编排组、Task、依赖、状态、结果与组内并发
模型工具与 API agent_task_tools.go、agent_task_api.go delegate/create/wait/submit、任务查询、停止与恢复
调度与执行 agent_task_scheduler.go、agent_task_runner.go 事件唤醒 + PG 对账、ready 领取、独立 session/run
有界修订 agent_task_revision.go、agent_task_revision_api.go planRevision、追加/取消未来工作与版本时间线
通知与交付 agent_task_delivery.go、agent_task_recovery.go 通知认领、消费/失败、attempt、交付恢复与人工重试
处理提醒 agent_task_attention.go 待答、计划决策、中断、交付失败与发布受阻聚合
继任与 handoff agent_task_successor.go、agent_task_handoff.go feasible 校验、继任组、复用、noReplay 与深度限制
执行历程 orchestration_journey.go 从持久记录派生计划、终态、复用、继任与交付时间线
后台 bash bash_job.go bj_…、输出/等待/停止、owner 租约、终态与通知
后台命令对账 bash_job_sweeper.go owner 失联后收 interrupted,不自动重放命令

方案:doc/70、doc/72、doc/73、doc/75、doc/82

1.9 工作现场、结果发布与项目容器

小模块 落点 干什么
Provider 接口与引擎 workspace_provider.go、workspace_engine.go Task/DAG 与 Git 细节解耦,统一准备现场、验收与发布
Git Provider workspace_git.go 已有 Git 仓库需要隔离修改时使用 worktree
Directory Provider workspace_directory.go 非 Git 项目使用目录副本、变更清单与冲突检查
不可变结果与验证 workspace_result.go、workspace_verify.go、agent_task_artifact.go 结果版本、产物、verifyCommand 与重试发布
发布协调 workspace_publish.go 项目级事务协调、项目变化检查与发布恢复
项目布局 project_layout.go layout.json、content/、runtime/{orchestrations,tmp,media,memory}
存量迁移 project_migrate.go 复制 → 校验 → 原子切换,不做新旧双读
删除补偿 project_cleanup.go 整容器清理与 project_cleanups pending 补偿
工作区视图 workspace_view.go 将 Provider 状态投成 API 可读信息,不把 Git 字段塞进 PG

方案:doc/74、doc/75、doc/76

1.10 清理、追踪与其他横切

小模块 落点 干什么
归档清扫 archive_sweep.go 软删保留窗口、wire 过窗清理与清扫租约
临时目录清扫 tempsweep.go 技能/工具 .staging、.trash 的 24 小时清理
OTel run 埋点 trace.go、trace_run.go run、模型、工具与内部步骤 span;观测不接管业务状态

方案:doc/37、doc/52、doc/54

2. 模型配置与观测(internal/config/、internal/observability/)

小模块 落点 干什么
厂商目录 internal/config/catalog.go、provider-catalog.json 协议、base URL、模型清单与视觉能力
环境发现与解析 internal/config/resolve.go ResolvedProvider → ResolvedModel,含 Ollama 特例
模型客户端与提示词 internal/config/model.go 构建 ToolCallingChatModel、系统提示与执行策略
模型注册表 internal/config/modelregistry.go 按 ref 构建与指纹缓存
OTel 装配 internal/observability/ OTLP 出口、CozeLoop/Langfuse、内容采集开关与序列化

3. 服务入口(cmd/yktako/)

main.go 是唯一可执行入口:解析工程参数,连接 PG/Redis/Redpanda,执行启动迁移,创建 store/worker/router,并启动 Task 调度、后台命令对账、记忆对账、归档清理和 HTTP 服务。

与长任务相关的参数包括 -task-interval、-task-input-timeout、-bash-foreground-wait、-wait-window、-job-lease-* 与 -job-reconcile-interval。当前代码默认 bash 前台等待窗口为 30 秒;以旗标与环境变量实际值为准。

4. 出厂子代理规格(agents/)

文件 职责
agents/coder.md 可改文件、写脚本、跑命令的执行规格
agents/researcher.md 调研与资料整理规格,排除 bash

规格使用 YAML frontmatter + 正文指令。同步子代理与持久 Task 可以复用执行规格,但两者的等待与恢复语义仍由 §1.5 和 §1.8 分别决定。

5. 前端(web/)

5.1 状态与基础设施

小模块 落点 干什么
API 与类型 src/api.ts、src/configureApi.ts run/Task/job/项目/团队/配置端点与响应类型
鉴权 src/auth.ts token、刷新三态、租户切换;代理 5xx 不误判登出
变更同步 src/mutation.ts BroadcastChannel + 账号 SSE,统一失效并重拉
对话状态 src/chat.ts、src/chatpool.ts 帧/历史/工具卡/提问组装与每会话实例池
Markdown src/markdown.ts、src/markdown.css marked + DOMPurify 与共享 .md-body
全局样式 src/base.css 设计变量、布局与响应式基础

5.2 页面与组件

小模块 落点 干什么
主壳与侧栏 src/App.vue 对话、项目/会话树、导航、处理提醒、页面分支与移动端抽屉
项目页 src/ProjectsView.vue 项目、会话、文件清单、Markdown 预览与删除补偿提示
右侧工作区 src/ChatDock.vue、WorkspaceTree.vue、WorkspaceFileView.vue 目录、任务、Todo、文件与后台命令标签
本轮视图 src/RunTodoPanel.vue、RunChangedFiles.vue run 内 Todo 与改动文件回执
任务页 src/TasksView.vue Task/编排详情、修订、发布、后台命令与执行历程;可嵌入右侧工作区
交付恢复 src/NotificationRecovery.vue 交付失败详情、人工重试与结果定位
技能与工具 src/SkillsView.vue、SkillInstallCard.vue、ToolsView.vue 技能目录/安装/禁用与工具根上传/删除
团队 src/MembersView.vue、InviteLanding.vue、PendingInvites.vue 成员、邀请落地与待处理邀请
配置与通用组件 src/Configure.vue、PlanDoc.vue、ConfirmDialog.vue Agent/模型/MCP 配置、方案渲染与确认框

5.3 测试

方案:doc/50、doc/60、doc/77、doc/78、doc/80、doc/81

6. 验收与运维脚本(scripts/)

小模块 落点 干什么
开发环境 scripts/dev.sh Redis + PostgreSQL + 引擎 + Vite;status/stop/restart
双远端同步 scripts/sync-remotes.sh 先 GitHub origin,成功后再 AtomGit atomgit
文档布局与总纲检查 scripts/check-doc-layout.sh、check-master-plan.sh 文档归档布局与 doc/README ↔︎ doc/16 引用一致性
架构页检查 scripts/check-architecture-pages.mjs 四页 JSON、节点/连线、导航、代码与文档链接、当前机制最低事实集
海报导出 scripts/export-architecture-poster.sh 从总览 HTML 的 ?poster=1 导出 3840×2822 PNG
契约机器真源 scripts/acceptance/expected.json、assert_contract.py 可判红的期望响应与真实端点断言
用例与抽验 scripts/acceptance/matrix.py、spotcheck.sh、check-expected.sh 实跑矩阵、存储/可见性抽验与散文用例号一致性
run/记忆活体 taskboard_crash.sh、question_crash.sh、memory_*.sh kill -9、问答、双模式、迁移、文件竞争、项目删除与 broker 崩溃
Task 活体 agent_task_{single,busy,dag,crash,two_replicas,revision,hitl,attention,wakeup,delivery_recovery,wait,demo}_live.sh 单件、依赖、双副本、修订、提问、提醒、唤醒、交付与主动等待
工作区与重规划 workspace_{git,directory,publication,crash}_live.sh、goal_replan*_live.sh Provider、发布、崩溃、继任与复用
项目与后台命令 project_layout*_live.sh、bash_job*_live.sh、orchestration_live.sh 布局迁移、后台命令、执行历程与整组回归
基准 scripts/bench/ GAIA 切片配方、官方口径判定器、双臂运行与基线报告

方案:doc/45(待点头)、doc/56、doc/70、doc/82

7. 文档与运行时产物

7.1 文档归属

位置 是什么
doc/README.md 目录页:现行真源、历史存档、非方案内容与记录
doc/16-能力复刻总规划.md 结论页:能力现状与下一步;与目录页同批更新
doc/19-v6/ v6 核心契约、存储、tool loop 与上下文机制
doc/70-多Agent编排与Task/ Task 方案集与参照调研
doc/assets/tako-*.html 系统总览、run、编排、数据四张说明页;导读而非施工真源
doc/problems/ 设计问题与候选的决策档案
doc/log/ 交接、施工记录与文章,不作现行施工真源
doc/archive/ 被整代取代的旧线与 v3/v4/v5

7.2 运行时产物(不入库)

位置 是什么
yk-tako-eino/workspace/ 租户、项目、会话、技能、工具与系统技能等共享存储根
yk-tako-eino/tmp/ 本地隔离引擎与施工运行产物
根 tmp/ 执行期施工包与返工记录,验收后按纪律留档并清理
yk-tako-eino/.env、mcp.json 本机秘密与 MCP 真配置,不入库,也不进入架构页或截图