hank

🧵 实时的、按租户划分的代码结构 — Bobbin × Quipu 技术栈缺失的结构化信号

[hank](https://en.wikipedia.org/wiki/Hank_(textile)) 是一圈缠好的纱线， 在你工作时随时备用。**Hank** 以同样的方式维护代码库的实时结构图： 在基线处提取一次，然后叠加一个轻量级的开发者覆盖层，这样整个团队的人类和 agent 就能同时进行编辑，而不会破坏彼此的视图。它回答了 embedding 和 git-history 无法回答的问题 —— *谁调用了它，这个流程流向哪里，这个改动会破坏什么* —— 并且它能够**按租户**在代码仍在变动时，正确地回答这些问题。 ## 🧶 实际运行效果 ``` $ hank analyze src analyzed 7 file(s), 47 symbol(s) [tree-sitter] $ hank refs authenticate src src/auth.rs:18 authenticate (Function) [TreeSitter] $ hank status hank status base ref : main tenant : (single-tenant) tiers : treesitter quipu : enabled=false branch_model=named_graph ``` ## 🤔 为什么选择 Hank？—— 以及它的不同之处 结构化代码智能并不是什么新概念；最强大的工具各自证明了**一种**信号类型的 价值。Hank 刻意吸收了每种工具的最佳理念 —— 然后增加了它们都不具备的维度： **整个团队同时编辑、治理以及时间。** ### 核心卖点 - 🧵 **并发下依然正确** —— 唯一一个在整个团队的人类*和 agent* 同时编辑同一个基线时 依然保持正确的结构化引擎（共享的基础图 + 按租户的写时复制覆盖层）。 - 🔀 **融合，而非单一信号** —— 调用/数据流结构 *加上* 历史性的共同变更 *加上* embedding。 由数据流路径支撑的耦合是真实的；没有数据流支撑的则是重构坏味道 —— 只有融合才能区分它们。 - 🪢 **受治理且可时间旅行** —— 提交的事实会提升进入 [Quipu](https://github.com/scbrown/quipu)，成为经过 SHACL 验证的、双时态 RDF： 这是一个版本化的单一事实来源，而不是尽力而为的缓存。 - 💥 **将影响范围作为基础原语** —— *“这个改动会破坏什么”*，按租户划分 —— 它同时也兼作增量更新引擎。 - ⚡ **两级新鲜度** —— tree-sitter 级别的快速广度 + LSP 级别的精确深度，每个 事实都带有置信度标签，让 agent 知道它正在信任什么。 - 🛡️ **结构划定了 sandbox 范围** —— 按租户的影响范围限制了自治 agent 可以触及的 内容，并且可以充当*生成护栏*，而不仅仅是上下文。 - 🪙 **节省 token** —— 提供结构化的答案，而不是将文件堆砌进上下文。 ### 对比 | | **codebase-memory** | **Joern (CPG)** | **LSP / multilspy** | **Embeddings / co-change** | **Hank** | |---|:--:|:--:|:--:|:--:|:--:| | 快速的结构图，低 token 成本 | ✅ | ⚠️ | ❌ | ✅ | ✅ | | 调用图 + **数据流 / 污点分析** | ⚠️ | ✅ | ⚠️ | ❌ | ✅ | | 精确的 LSP 级类型 | 分层 | ❌ | ✅ | ❌ | 分层 | | 编辑时的增量新鲜度 | ✅ | ❌ | ✅ | ❌ | ✅ *(边界受限)* | | **团队并发编辑时依然正确** | ❌ | ❌ | ❌ | ❌ | ✅ *(按租户的覆盖层)* | | **受治理的、版本化的、可时间旅行的记录** | ❌ | ❌ | ❌ | ❌ | ✅ *(→ Quipu)* | | 影响范围界定了 **agent 信任边界** | ❌ | ❌ | ❌ | ❌ | ✅ | 每一项都证明了一部分 —— **[multilspy](https://github.com/microsoft/multilspy)** 证明了 LSP 事实也可以作为*生成护栏*，**[Joern](https://joern.io)** 证明了 Code Property Graph 和数据流，**codebase-memory** 证明了带有基于内容哈希的增量新鲜度的 轻量级独立分析器。Hank 在精神上最接近 codebase-memory， 并扩展了 Joern 风格的数据流、LSP 的精确度、**租户特性**，以及对 Quipu 的受治理映射。 ## 🧩 技术栈 —— 三个工具，各司其职 ``` edit / save / file-watch │ ▼ ┌──────────────────────────┐ promote on commit/merge ┌──────────┐ │ HANK │ ───────────────────────────► │ QUIPU │ │ base graph + overlays │ (SHACL-validated Turtle) │ EAVT log │ │ tree-sitter + LSP + CPG │ ◄─────────────────────────── │ SPARQL │ └────────────┬─────────────┘ SPARQL over committed code └──────────┘ │ blast radius (per tenant) ▼ ┌───────────────┐ broker/Aegis ┌──────────┐ │ Bobbin fusion │◄──(trust boundary)────│ agents │ │ + serving │───────────────────────►│ (polecat)│ └───────────────┘ explained context └──────────┘ ``` - **[Hank](https://github.com/scbrown/hank)**（本仓库）—— 提取并提供 实时的按租户结构。 - **[Quipu](https://github.com/scbrown/quipu)** —— 治理并对 已提交的记录进行版本控制（双时态 RDF / SPARQL / SHACL）。 - **[Bobbin](https://github.com/scbrown/bobbin)** —— 将所有内容与其 统计和 embedding 信号融合，并通过 MCP 提供带解释的上下文。 参见 [`docs/vision.md`](docs/vision.md) 了解宏伟愿景，以及 [`docs/hank-spec.md`](docs/hank-spec.md) 了解完整的构建规范。 ## 🪢 Hank + Quipu —— 这对组合解锁了什么 Hank 掌握*实时*结构；[Quipu](https://github.com/scbrown/quipu) 治理 *已提交*的记录（双时态 RDF，经 SHACL 验证，可通过 SPARQL 查询）。它们结合起来可以做任何一方都无法单独完成的事情： - **受治理的 SPARQL-over-code。** 将提交的结构作为有类型的、经过验证的事实进行查询 —— *“每一个没有测试的公共函数”、“违反了分层的模块”、“谁还在调用这个废弃的 API”* —— 而不是你希望保持最新的缓存。 - **历史之上的影响分析。** 双时态事实回答了*这个改动破坏了什么，以及 这种耦合是何时首次出现的* —— 这是一个考虑了代码是如何演变到这里的影响范围分析， 可以在任何时间点重放。 - **阻止或影响变更的本体规则。** 在 Quipu 中将架构约束编写为本体规则（在代码图之上应用 SHACL）；Hank 会 **实时且按租户**根据这些规则评估提议的修改，并在违规落地*之前*发出警告或阻止。 策略即本体 —— 一条新规则就是一次图断言，而不是一个新的定制 linter。 - **按租户的平行世界。** 共享的基线加上写时复制的覆盖层（Hank） 映射到 Quipu 的命名图上，这样整个团队就可以在不破坏彼此视图的情况下并发编辑 —— 且这一切都建立在一个始终保持可查询状态的单一**事实来源根节点**之上。 - **agent 信任边界。** 按租户的影响范围限定了自治 agent 可以触及的范围 —— 结构*定义了 sandbox* —— 通过 Aegis/broker 机制实现。 - **代码 ↔ 意图，相互关联。** Quipu 的溯源将结构事实与产生它们的决策和工作项联系起来 —— *“这个模块实现了哪个决策”、“哪些工单与这条代码路径同时出现。”* ## 🚀 快速开始 ### 安装 ``` # 从源码 — 将 `hank` 二进制文件放到你的 PATH 上 cargo install --path . # or: just install # 附带 MCP server 和额外的语言语法： cargo install --path . --features "mcp langs-extra" ``` ### 使用 ``` # 分析 tree 并列出其结构 hank analyze src hank refs src hank status # Call graph：callers/callees 和 blast radius hank callers src hank impact src --hops 5 # 函数内的 Data dependence hank dataflow src --var # 将参照结构（代码 + 文档）导出为 governed RDF Turtle hank export src --repo myrepo --format turtle # 通过 MCP (stdio) 为 agent 提供服务 hank serve # Edit-reactive：将 `hank hook post-edit` 接入 Claude Code PostToolUse hook # 以便在每次编辑时获取同步的 blast-radius 建议（参见 docs）。 # Shell completions hank completions bash > hank.bash ``` Hank 在 `[hank]` 表下共享该技术栈的 `.bobbin/config.toml` —— 参见 [配置参考](docs/book/src/reference/config.md)。 ## 🌳 支持的语言 Tree-sitter 结构提取（符号、文件内调用边、导入引用 —— 全部标记为 `TreeSitter`）已接入 Bobbin 的全套语法集。 **Rust** 始终会被构建；其余语言包含在 `langs-extra` feature 下 （`cargo build --features langs-extra`）。 | 语言 | Feature | 扩展名 | | -------------- | ------------- | ---------------------------------------------- | | Rust | *(始终开启)* | `.rs` | | TypeScript | `langs-extra` | `.ts` `.mts` `.cts` `.js` `.mjs` `.cjs` | | TSX / JSX | `langs-extra` | `.tsx` `.jsx` | | Python | `langs-extra` | `.py` `.pyi` | | Go | `langs-extra` | `.go` | | Java | `langs-extra` | `.java` | | C / C++ | `langs-extra` | `.c` `.h` `.cc` `.cpp` `.cxx` `.hpp` `.hh` `.hxx` | 每种语法都为位于 `src/extract/` 中共享的、与语言无关的遍历器提供了特定于语言的 `GrammarSpec`（语法 + 节点类型 → `SymbolKind` 映射 + 调用/导入提取）；`language_for_extension` 根据文件扩展名选择语法。参见 [FR-1](docs/hank-spec.md) 了解提取层的契约。 ## 🛠️ 开发 ``` just setup # install pre-commit hooks just build # cargo build just test # cargo test just lint # clippy -D warnings just check # full pre-push gate (fmt, clippy, markdownlint, file size) just docs build # build the mdBook ``` 约定记录在 [`AGENTS.md`](AGENTS.md) 中；贡献指南位于 [`CONTRIBUTING.md`](CONTRIBUTING.md)。始终使用 `just`，不要直接使用 `cargo`。 ## 📚 文档 - [规范说明](docs/hank-spec.md) —— 完整的 PRD 风格构建规范。 - [愿景](docs/vision.md) —— Bobbin × Hank × Quipu。 - [mdBook](docs/book/src/SUMMARY.md) —— 指南、概念和参考。 ## 许可证 [MIT](LICENSE) © 2026 Steve Brown

标签：AI辅助编程, DNS重绑定攻击, IPv6支持, Rust, SOC Prime, 云安全监控, 代码智能, 代码结构分析, 可视化界面, 开发工具, 网络流量审计, 调用图, 通知系统, 静态分析