10 KiB
TTKB:按任务选择的辅助知识
TTKB 是可选的外部知识源,不替代 Streamline 自有 PG 知识库及 kbContext。
任务不选择知识包时,TTKB prompt wrapper 原样返回原提示词;不会扫描包正文或自动安装。
本功能覆盖 Bugfix、Feature、Security 的创建、评估和执行,包括 Security 的重试路径。
用户看到什么
- 新建任务:在集群和平台对应的目录中勾选
space/package;默认不选。 - 任务卡片和详情:
TTKB × N表示选择了 N 个包,不表示整个包被采用。 - 复用的历史知识 / Streamline:原有 PG 注入条目、K 标签、模型报告的采纳情况及人工反馈。
- 本次使用的外部知识 / TTKB:成功直接读取的 Markdown/MDX 文档,包含包名、包内路径、标题、评估/执行阶段及重复读取次数;索引/README 单独标记为导航。
TTKB 面板的“使用”证据实际上是成功读取,不是模型确认采纳,更不是执行验证正确。
失败 Read、目录探测、Glob、仅出现在 prompt 中的包不计入。API 保留轮次,UI 聚合各轮,正文优先,默认显示 3 篇并可展开。
两块面板数据来源独立,TTKB 不写入 kb_claims / kb_injections,没有自动蒸馏或多语言改写知识正文。
管理员安装
使用卫星进程所属的 OS 用户安装;另一个用户的 HOME 不会被发现。先确保该用户已经安装可用的 TTKB CLI,并完成企业认证。以下参数以 ttkb install --help / ttkb update --help 为准;Streamline 不捆绑 CLI,也不负责其 npm 发布问题。
例如同一 Android 池的每台卫星都安装相同已审核版本:
ttkb install lemon8/lemon8-knowledge --global --version 0.0.45 --ai-tool cursor --no-package-paths --yes
Claude/Codex 节点将 --ai-tool 改为实际工具。版本号是示例,不是“当前最新”的承诺。优先固定版本或 commit,在池内统一更新。
若采用项目级安装,显式指定卫星的 AI_WORKSPACE,避免 CLI 自动选择 Git 根目录导致装到别处:
ttkb install lemon8/lemon8-knowledge --scope-root "$AI_WORKSPACE" --version 0.0.45 --ai-tool cursor --no-package-paths --yes
发现规则:
| 安装范围 | lock 文件 | 必须存在的原件目录 |
|---|---|---|
| 卫星用户全局 | $HOME/.ttkb/lock.json |
$HOME/.ttkb/packages/<space>/<package>/ |
| 卫星工作区 | $AI_WORKSPACE/.ttkb/lock.json |
$AI_WORKSPACE/.ttkb/packages/<space>/<package>/ |
同名包项目级覆盖全局。只扫描这两个 lock 及默认原件目录;不支持任意 --package-root / --package-base 的自定义布局。ttkb/cli 不作为业务包展示。原生 skill 投影目录不是包发现依据。
本地扫描缓存 60 秒,节点注册和心跳上报包 ID、version、commitId、description、skills,不上传本机绝对路径或知识正文。等待扫描缓存刷新和下一次心跳后,重新打开创建弹窗。
# 只读:核对目标控制面;示例为本地开发服务
curl 'http://127.0.0.1:5173/api/ttkb/packages?cluster=default&platform=android'
包需要 ready: true 才能选择:当前路由池中所有在线候选节点都有它,且 version/commitId 元组完全一致,每份至少有一个版本标识。不是全公司的所有机器,也不按包名中的 android/ios 推断平台。
不完整、版本不一致、尚未上报的新旧节点混合池会禁用选项;没有在线候选节点时也不可选。多集群建单要求在每个可能落点的池都可用。
Meego 导入或未明确平台的 Bugfix 在获知真实平台之前按全部候选平台保守校验,可能比纯文本指定平台更严格。
更新先预演,确认后在维护窗口统一执行:
ttkb update lemon8/lemon8-knowledge --global --dry-run
# 若确实要解除 pin 升到 HEAD 并纳入新增知识,管理员明确决定后执行:
ttkb update lemon8/lemon8-knowledge --global --to-latest --include-new --yes
生产池更推荐每台机器统一 install --version / --commit,而非各自在不同时间追 HEAD。不要在运行中的任务读取包文件时更新。
对原有系统的影响
- 数据库:
tasks、features、security各增加一个 nullable TEXTttkb_packages,保存 JSON ID 数组。旧行/未提供字段按空选择读取;不迁移或复制知识正文。 - API:创建接口新增可选
ttkbPackages: string[],去重、校验 ID(最多 20 项)及路由池可用性;非法或不可用的显式选择返回 400。新增目录及各任务类型的ttkb-usageGET 接口。 - 执行:原有
kbContext下发、K 标签和反馈链路保留;TTKB 只在选中后叠加辅助导航。当前代码、任务 spec 和 Streamline 已确认知识优先于 TTKB。没有额外在线翻译、embedding 或知识服务查询。 - 跨语言:复用独立多语言 MR !36 的 shared 词表,生成最多 24 个导航搜索词,不是事实或通用翻译,不修改知识包/PG 数据。
- 路径与子 agent:使用经本机验证的绝对原件路径及浅层入口。要求主会话直接 Read TTKB,不将 TTKB 查阅委托给子 agent;其他代码探索仍可委托。这是 prompt 约束,不是工具层隔离。
- 节点稳定性:被清理的未知节点发心跳得到 404,触发现有卫星重新注册完整地址/平台信息;正常心跳仍返回 200。此修复影响所有节点,不仅 TTKB,防止目录因幽灵心跳长期消失。
限制与风险
- 选择不是安全隔离:
--global还可能向 Agent 原生全局目录投影 Skills/Rules,Agent 可自行发现;不选择只保证 Streamline 不额外注入 TTKB 指引,不能阻止原生自动加载。不要把这当成权限边界,包内容需管理员审核。 - 不自动安装:没有自由输入未知包/下载/更新/单任务 worktree 安装。选中包在执行时缺失会告警并继续,不中断任务。
- 创建时校验不是执行时版本锁:任务只存包 ID,未固定版本/快照;创建后节点加入、掉线、目录更新可使可用性或内容漂移,调度器本身不新增包约束。
- 审计依赖格式和文件:只识别当前 stream-json 的直接 Read/read_file/readfile 及工具结果;Shell/cat、Grep 片段、子 agent 独立日志及其他未适配格式可能漏计。依赖卫星在线、日志保留和原文件存在,标题从当前文件读取,并非运行时内容快照。
- 审计不是无损历史库:每个日志默认最多扫描 100,000 行(
TTKB_USAGE_MAX_LINES);按日志尺寸/mtime 缓存,包文件单独更新不使缓存失效;每个进程的工作区缓存当前无 LRU。首次大日志扫描有 I/O 成本。运行中 UI 每 3 秒请求,后端缓存避免重复扫描相同日志。 - 无自动纠正历史记录:旧节点、遗失日志、漏执行 schema 迁移不能凭 UI 恢复。原有 kbContext 记录失败仍可能静默:提示词成功注入但
kb_injections为空,历史面板就不显示。TTKB 不修复该问题,也不能把读取等同采纳。 - 混合版本:旧卫星不会提供新目录/审计或执行新指引。若旧控制面先于新卫星接收带
ttkbPackages的请求,可能忽略该字段;发布完成前不要开放选择。自有 KB 的错误隐藏/刷新行为未在本 MR 改动。
发布与验收
本功能不是部署授权。生产操作按 CLAUDE.md 和部署 skill,由管理员在维护窗口执行。
- 独立多语言 MR !36 先合入;若为 squash 合并,TTKB 分支 rebase 到 main 时跳过已包含的多语言提交,再将 MR target 改为 main。不要把 TTKB 合进仍待审核的多语言源分支。
- 核对目标数据库及基线迁移齐全,再执行本 MR 的
drizzle/0024_ttkb_task_packages.sql(合入 main 时从 0021 改号,避免与已有0021_code_sidecars.sql前缀重复;当前仓库工具按文件执行,不按编号自动去重)。
# 预演默认只读;不会自动执行 DDL
bun scripts/apply-migration.ts drizzle/0024_ttkb_task_packages.sql
# 管理员核准正确目标库后才执行
bun scripts/apply-migration.ts drizzle/0024_ttkb_task_packages.sql --commit
- 核对新代码所需的全部基线 schema,尤其
0021_code_sidecars.sql/0022_kb_recall_links.sql/0023_product_profiles.sql,不能只看 TTKB 三列。迁移包含ADD COLUMN IF NOT EXISTS,但缺列依然会让新代码查询失败。 - 发布 control-server + web,并升级目标池 shared/satellite bundle;只重启 server 不会更新卫星 prompt。管理员预装相同版本包,等心跳目录 ready 后开放使用。
- 验收未选择任务行为不变、两类知识独立展示、成功读文档与导航区分、缺包/混合版本不可选、节点重新注册,以及 Bugfix/Feature/Security 对应接口。
- 观察派发/读取失败日志、400、心跳 404 后的注册恢复、目录 ready 比例、卫星 I/O。新增心跳 404 应随后转为成功注册,持续 404 需要排查。
回退
- 立即停止新任务使用:新建任务不选择包;这不改变已有任务的选择,没有专用全局 TTKB kill switch。已经启动的 Agent prompt 不会被撤回。
- 代码回退:安排已运行任务自然收尾或由管理员确认暂停,按正常发布流程回退 web/server/satellite 到已知版本;必须覆盖卫星 bundle。若仅撤销 TTKB,保留已审核的 !36 多语言基线;节点心跳修复可按独立提交保留。
- 保留 schema:不删除新增 nullable 列、任务选择、包文件或日志;旧版本忽略新增列,保留数据便于重新上线。不要执行破坏性 down migration。
- 包版本回退:管理员恢复原先记录的版本/commit,统一到整个池,再检查 ready;代码回退不会卸载全局技能投影,必要时由管理员单独处理。任何在途任务的包变更都需协调。
验证范围
bun run test、bun run typecheck、bun run build;TTKB 相关测试覆盖发现/覆盖关系/非法 ID、路由池一致性、空选择 prompt 不变、绝对路径与双语导航、直接成功文档读取/跨轮聚合、未知节点 404 后重新注册。
页面截图区分真实本地目录和显式标记的组件 fixture。fixture 用于验证布局、折叠、导航/正文、来源区分及空/不可用状态,不证明某个任务实际采纳,也不替代真机端到端验收。
已采集的页面状态和来源说明见 评审截图。