上下文枢纽 Context Hub(context-hub-vscode)
IDE 与 AI 编码 Agent 之间的上下文中间件:决定给 Agent 看什么、以什么密度看、带去哪里。
需求来源:../需求/3.md,PRD 工作区 ../需求/context-engineering-prd/(已定版 v1.0.0)。
目录结构
src/
types.ts 领域类型与常量(阶段、来源、三档判定、能力清单)
types/vscode.d.ts 扩展实际用到的 VS Code API 最小类型声明
extension.ts 扩展入口:命令注册、状态栏、采集器、面板接线
panel/capturePanel.ts 捕获面板 Webview(内联样式,无外部资源)
core/ 纯逻辑层,不依赖 vscode,可独立单测
stages.ts captureContext 阶段状态机
collector.ts 五类来源采集与逐项选择
pack.ts 上下文包结构化字段与打包
tokens.ts token 估算与超预算裁剪顺序
stale.ts 陈旧三档判定、签名提取、压缩报告
snippet.ts 触发词展开与变量注入
output.ts 输出 schema 校验与修复重试
tidy.ts 基础输出整理
capabilities.ts 免费/Pro/团队分层、宽限期、席位
transfer.ts 跨 Agent 续接计划与 prompt 渲染
expiration.ts 过期提醒三态
promptVersions.ts Prompt 版本化与 A/B 对比
test/core.test.mjs 20 个用例,覆盖上述全部纯逻辑
构建与测试
npm install
npm run compile # tsc
npm run test # node --test
npm run verify # 两者一起
本机若未安装依赖,可直接复用工作区内已装的 TypeScript:
& "..\需求\context-engineering-prd\node_modules\.bin\tsc.cmd" -p .
运行方式(重要)
dist/extension.js 里的 require("vscode") 只存在于 VS Code 的**扩展宿主(Extension Host)**中,因此不能用 Node 直接运行,node dist/extension.js 必然报 Cannot find module 'vscode'。
推荐方式一:在 VS Code 里按 F5 运行「运行扩展(上下文枢纽)」。它会启动一个临时的扩展开发宿主窗口,在其中执行命令面板 上下文枢纽:捕获当前开发状态 验证功能。调试配置见 .vscode/launch.json。
推荐方式二:打包成 vsix 安装到正式 VS Code:
npx @vscode/vsce package
code --install-extension context-hub-vscode-1.0.0.vsix
需求实现映射
需求实现映射
| 需求 |
实现位置 |
关键行为 |
| REQ-001 一键捕获 |
extension.ts 三处入口 + collector.ts |
命令面板 / 资源管理器右键 / 状态栏按钮共用 runCapture |
| REQ-002 来源逐项选择 |
collector.ts toGroups |
五类来源可单独取消,取消后不计入 token |
| REQ-003 结构化字段 |
types.ts ContextPackage |
objective、仓库分支、来源分组、token 统计 |
| REQ-004 打包预览 |
panel/capturePanel.ts |
面板展示压缩前/后 token 与压缩比 |
| REQ-005 打包反馈 |
pack.ts packageFeedback |
写入 .ctx.json 并复制到剪贴板 |
| REQ-006 空内容降级 |
pack.ts + stages.ts |
无内容不打包,状态机 RESET 回到空闲 |
| REQ-007 片段展开 |
snippet.ts expandSnippet |
触发词整词匹配,现场替换不跳转 |
| REQ-008 输出整理 |
tidy.ts |
只调格式不改结论,本地渲染 |
| REQ-009 跨 Agent 续接 |
transfer.ts |
Agent 运行中禁用、过期禁用,prompt/writeFile 两条路径 |
| REQ-010 陈旧分类 |
stale.ts classifyStale |
RETAIN / COMPRESS_TO_SIGNATURE / EVICT,两可时选压缩 |
| REQ-011 预算裁剪 |
tokens.ts planTrim |
按 note→terminal→diff→tab→selection 顺序裁剪并展示顺序 |
| REQ-012 Prompt 版本化 |
promptVersions.ts |
通过率优先,其次平均 token,最后失败样例数 |
| REQ-013 团队 schema |
capabilities.ts canUseTeamSchema |
席位用满时拒绝并给出原因 |
| REQ-014 格式锁定修复 |
output.ts repairWithRetry |
按上限重试,每次重试可见上次校验结论 |
| REQ-015 变量注入校验 |
snippet.ts + output.ts |
未解析变量进入校验失败态并列出原因 |
| REQ-016 能力分层 |
capabilities.ts |
宽限期结束只关 Pro 命令,三项免费能力保持可用 |
| REQ-017 最小侵入 |
capturePanel.ts |
单一 Webview 面板,用完即关 |
| REQ-018 本地隐私边界 |
tidy.ts TIDY_GUARANTEES |
全程本地处理,无网络请求 |
| REQ-019 阶段状态机 |
stages.ts |
五阶段单一状态机,非法迁移返回原因 |
| REQ-020 过期提醒 |
expiration.ts |
fresh / expiring / expired 三态文案 |
已知边界(当前未实现)
- 终端与手写备注采集:
terminal、note 两组目前返回空,需在备注中手动补充。采集器接口已预留,接入方式见 collector.ts 的 SourceProvider。
- token 为估算值:采用字符比例估算(约 1 token / 3.35 字符),未接入真实 tokenizer,面板数字应理解为估算。
- 跨 Agent 续接只出计划:
transfer.ts 生成续接计划与 prompt 文本,尚未自动写入目标 Agent 的运行环境。
- Prompt 版本历史未接 Git:
showPromptVersions 目前读不到提交历史,仅展示本地记录,需接 git log 后补齐。
- 陈旧判定轮次为近似值:扩展内按文件访问顺序近似轮次,未按真实 Agent 引用记录统计。
- 未做视觉与集成验证:纯逻辑层已单测,但
extension.ts 的 VS Code API 接线未在真实编辑器中跑过;建议用 F5 调试配置实测捕获与打包。
后续迭代建议
- 把
extension.ts 里的接线逻辑抽成可注入的宿主接口,让 Webview 面板也能被单测覆盖。
- 陈旧判定接入真实的 Agent 引用记录(谁在第几轮引用了哪个文件)。
- 续接真正写入 Cline 的
.context-hub/context.json 并做端到端验证。
- Prompt 版本历史接
git log,按提交差异行数与通过率排版本。