Files
streamline/docs/ttkb-integration.md
2026-11-16 17:26:44 -08:00

116 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 池的每台卫星都安装相同已审核版本:
```bash
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 根目录导致装到别处:
```bash
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,不上传本机绝对路径或知识正文。等待扫描缓存刷新和下一次心跳后,重新打开创建弹窗。
```bash
# 只读:核对目标控制面;示例为本地开发服务
curl 'http://127.0.0.1:5173/api/ttkb/packages?cluster=default&platform=android'
```
包需要 `ready: true` 才能选择:**当前路由池中所有在线候选节点**都有它,且 version/commitId 元组完全一致,每份至少有一个版本标识。不是全公司的所有机器,也不按包名中的 android/ios 推断平台。
不完整、版本不一致、尚未上报的新旧节点混合池会禁用选项;没有在线候选节点时也不可选。多集群建单要求在每个可能落点的池都可用。
Meego 导入或未明确平台的 Bugfix 在获知真实平台之前按全部候选平台保守校验,可能比纯文本指定平台更严格。
更新先预演,确认后在维护窗口统一执行:
```bash
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。不要在运行中的任务读取包文件时更新。
## 对原有系统的影响
1. **数据库**:`tasks`、`features`、`security` 各增加一个 nullable TEXT `ttkb_packages`,保存 JSON ID 数组。旧行/未提供字段按空选择读取;不迁移或复制知识正文。
2. **API**:创建接口新增可选 `ttkbPackages: string[]`,去重、校验 ID(最多 20 项)及路由池可用性;非法或不可用的显式选择返回 400。新增目录及各任务类型的 `ttkb-usage` GET 接口。
3. **执行**:原有 `kbContext` 下发、K 标签和反馈链路保留;TTKB 只在选中后叠加辅助导航。当前代码、任务 spec 和 Streamline 已确认知识优先于 TTKB。没有额外在线翻译、embedding 或知识服务查询。
4. **跨语言**:复用独立多语言 MR !36 的 shared 词表,生成最多 24 个导航搜索词,不是事实或通用翻译,不修改知识包/PG 数据。
5. **路径与子 agent**:使用经本机验证的绝对原件路径及浅层入口。要求主会话直接 Read TTKB,不将 TTKB 查阅委托给子 agent;其他代码探索仍可委托。这是 prompt 约束,不是工具层隔离。
6. **节点稳定性**:被清理的未知节点发心跳得到 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,由管理员在维护窗口执行。
1. 独立多语言 MR !36 先合入;若为 squash 合并,TTKB 分支 rebase 到 main 时跳过已包含的多语言提交,再将 MR target 改为 main。不要把 TTKB 合进仍待审核的多语言源分支。
2. 核对目标数据库及基线迁移齐全,再执行本 MR 的 `drizzle/0024_ttkb_task_packages.sql`(合入 main 时从 0021 改号,避免与已有 `0021_code_sidecars.sql` 前缀重复;当前仓库工具按文件执行,不按编号自动去重)。
```bash
# 预演默认只读;不会自动执行 DDL
bun scripts/apply-migration.ts drizzle/0024_ttkb_task_packages.sql
# 管理员核准正确目标库后才执行
bun scripts/apply-migration.ts drizzle/0024_ttkb_task_packages.sql --commit
```
3. 核对新代码所需的**全部**基线 schema,尤其 `0021_code_sidecars.sql` / `0022_kb_recall_links.sql` / `0023_product_profiles.sql`,不能只看 TTKB 三列。迁移包含 `ADD COLUMN IF NOT EXISTS`,但缺列依然会让新代码查询失败。
4. 发布 control-server + web,并升级目标池 shared/satellite bundle;只重启 server 不会更新卫星 prompt。管理员预装相同版本包,等心跳目录 ready 后开放使用。
5. 验收未选择任务行为不变、两类知识独立展示、成功读文档与导航区分、缺包/混合版本不可选、节点重新注册,以及 Bugfix/Feature/Security 对应接口。
6. 观察派发/读取失败日志、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 用于验证布局、折叠、导航/正文、来源区分及空/不可用状态,不证明某个任务实际采纳,也不替代真机端到端验收。
已采集的页面状态和来源说明见 [评审截图](ttkb-evidence/README.md)。