模块地图
性质:结构索引,不是方案——本文只回答「有哪些模块、每个模块落在哪些文件、干什么」。 最后核对: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 |
按属主与租户判定会话可见、可写与列表范围 |
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 的条目、作业、召回观测;不是已取消的记忆管理面 |
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 投影,不改变执行行为 |
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 估算 |
pdftext.go、pdftool.go |
读取 PDF 文本层,不做扫描件 OCR | |
| 会话历史与网络检索 | search.go、websearch.go、webfetch.go |
search_history、web_search、web_fetch;全文落盘 |
| 延迟工具发现 | toolsearch.go |
BM25 检索 deferred 工具并按需激活 |
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 |
工具出口、模型输入与记忆入库前的脱敏与密钥拒收 |
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、计划模式写限制与恢复 |
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 表与写入端点已退役 |
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,不自动重放命令 |
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 |
1.10 清理、追踪与其他横切
| 小模块 | 落点 | 干什么 |
|---|---|---|
| 归档清扫 | archive_sweep.go |
软删保留窗口、wire 过窗清理与清扫租约 |
| 临时目录清扫 | tempsweep.go |
技能/工具 .staging、.trash 的 24 小时清理 |
| OTel run 埋点 | trace.go、trace_run.go |
run、模型、工具与内部步骤 span;观测不接管业务状态 |
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 测试
web/test/*.test.ts:chatpool、Markdown、鉴权刷新等单元测试。web/e2e/*.spec.ts:smoke、UI、文件、Markdown 预览、多会话与侧栏事件等 Playwright 场景。
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 切片配方、官方口径判定器、双臂运行与基线报告 |
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 真配置,不入库,也不进入架构页或截图 |