AI导哈

代码智能扩展

pi-kota是一款为TypeScript和JavaScript代码库提供持久化、依赖感知的智能编码助手，通过KotaDB实现依赖图查询、代码搜索和变更影响分析等功能，有效管理上下文窗口。

  • by coctostan
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 coctostan/pi-kota

使用说明

首都

不会占用上下文窗口的代码智能。

A. π 该扩展为您的编码代理提供了一个持久的、具有依赖性意识的大脑，用于TypeScript和JavaScript存储库——由 城市 数据 库 与MCP相比，它具有内置的上下文修剪功能，可以保持长会话的清晰度。

✨ 它做什么

问题 皮科塔的回答
代理反复读取大文件以回答“什么取决于X？” kota_deps --来自持久索引的即时依赖图
30轮会话因过时的工具输出而膨胀 上下文修剪删除了旧的有效载荷，保留了意义+再水合路径
影响分析要求代理手动跟踪导入 kota_impact --更改影响摘要，固定以使其在修剪后仍能存活
大型工具结果破坏了上下文预算 自动截断+blob缓存——可按需恢复完整输出

简短版本

KotaDB = persistent code index (deps, symbols, usages, impact)
pi-kota = thin wrapper + context governor (bounded output, pruning, blob cache)

您可以对代码库进行快速、有界的查询，而不会在对话中积累原始文件转储。

🔧 工具

六个精心策划的工具，默认情况下所有输出都有限制：

工具 它做什么
kota_index 索引或重新索引当前存储库（无提示）
kota_search 代码搜索-- paths, compact，或 snippet 输出模式
kota_deps 依赖关系图查询（依赖关系、依赖关系或两者）
kota_usages 查找整个仓库中某个符号的所有用法
kota_impact 分析变更影响——风险面、受影响的文件、推荐的测试
kota_task_context 总结一组文件的deps+影响（非常适合任务规划）

⌨️ 命令

命令 描述
/kota status 显示进程状态、仓库根、索引状态、配置源
/kota index 触发器索引（如果启用，则要求确认）
/kota evict-blobs 清除旧的/超大的blob缓存条目（尽最大努力）
/kota restart 重置KotaDB连接（下一个工具调用重新连接）
/kota reload-config 从磁盘重新加载配置

🧹 上下文治理

pi-kota通过两层防止上下文膨胀：

1.LLM上下文修剪 (context 事件）

  • 保持最后N圈不变（默认值：2）
  • 年长的 read, bash，以及 kota_search 结果被紧凑的补液指针所取代
  • 自适应模式在令牌使用率攀升时加强修剪

2.刀具结果截断 (tool_result 事件）

  • 大的 kota_* 输出被截断为 maxToolChars
  • 完整输出已保存到blob缓存(~/.pi/cache/pi-kota/blobs/)
  • 截断的恢复结果中包含Blob ID

📦 先决条件

pi-kota 通过 Bun 生成 KotaDB：

bun --version    # required

npm install 运行非阻塞Bun可用性检查(scripts/check-bun.js)如果Bun缺失，则打印PATH引导。

Bun PATH故障排除

如果启动失败，则：

pi-kota: 'bun' not found on PATH

安装Bun并确保您的shell PATH包含Bun的bin目录（通常 ~/.bun/bin).

🚀 安装

作为pi包（推荐）

# Global install (default) — available in all pi projects
pi install git:github.com/coctostan/pi-kota

# Project-local install — only for the current repo (writes to .pi/settings.json)
pi install -l git:github.com/coctostan/pi-kota

默认情况下， pi install 是 全球 并将该包添加到 ~/.pi/agent/settings.json. 使用 -l 为了一个 项目本地 安装（将其添加到 .pi/settings.json).

对于可复制的安装，您可以选择固定到git标签（或提交SHA），例如：

pi install -l git:github.com/coctostan/pi-kota@v0.1.0

npm发布后，您还可以按包名安装：

pi install pi-kota

您还可以手动编辑设置文件：

{
  "packages": ["git:github.com/coctostan/pi-kota"]
}

本地开发

克隆仓库并安装依赖项：

git clone https://github.com/coctostan/pi-kota.git
cd pi-kota
npm install

然后将pi指向项目中要使用它的扩展入口点（例如在 .pi/settings.json):

{
  "extensions": ["../pi-kota/src/index.ts"]
}

⚙️ 配置

配置文件是分层的——全局默认值，然后是项目覆盖：

范围 路径
全球 ~/.pi/agent/pi-kota.json
项目 .pi/pi-kota.json

默认配置

{
  "kota": {
    "toolset": "core",
    "autoContext": "off",
    "confirmIndex": true,
    "connectTimeoutMs": 10000,
    "command": "bun",
    "args": ["x", "kotadb@next", "--stdio", "--toolset", "core"]
  },
  "prune": {
    "enabled": true,
    "keepRecentTurns": 2,
    "maxToolChars": 1200,
    "adaptive": true
  },
  "blobs": {
    "enabled": true,
    "dir": "~/.pi/cache/pi-kota/blobs",
    "maxAgeDays": 7,
    "maxSizeBytes": 52428800
  },
  "log": {
    "enabled": false,
    "path": "~/.pi/cache/pi-kota/debug.jsonl"
  }
}

关键选项

选项 默认值 描述
kota.autoContext "off" 自动注入任务上下文： "off", "onPaths" （提示中有1-3个文件路径）， "always"
kota.confirmIndex true 运行时索引前提示 /kota index （以及其他基于确认的流程）。注： kota_index 工具不提示。
kota.connectTimeoutMs 10000 Kota MCP启动的连接超时（毫秒）
prune.keepRecentTurns 2 在修剪之前保持完好无损
prune.maxToolChars 1200 截断前每个工具结果的最大字符数
prune.adaptive true 当上下文使用率高时，加强修剪
blobs.enabled true 将完整截断的输出保存到blob缓存
blobs.dir "~/.pi/cache/pi-kota/blobs" Blob缓存目录
blobs.maxAgeDays 7 清除比此旧的斑点（由使用 /kota evict-blobs)
blobs.maxSizeBytes 52428800 清除最旧的blob，直到缓存小于此大小（由使用 /kota evict-blobs)
log.enabled false 启用调试JSONL日志记录（尽最大努力，永远不会使扩展崩溃）
log.path "~/.pi/cache/pi-kota/debug.jsonl" 调试日志文件路径

🛠️ 发展

npm install
npm test
npm run test:e2e
npm run typecheck

建筑

src/
├── index.ts          # Extension entry — events, commands, tool registration
├── runtime.ts        # Runtime state + path normalization
├── config.ts         # Layered config loading (global + project)
├── prune.ts          # Context pruning logic + adaptive settings
├── autocontext.ts    # Auto task-context injection rules
├── blobs.ts          # Blob cache writes
├── paths.ts          # File path extraction from prompts
├── text.ts           # Text truncation utilities
├── toolResult.ts     # Tool result truncation decisions
└── kota/
    ├── mcp.ts        # MCP stdio client (KotaDB connection)
    ├── tools.ts      # Budgeted tool calls + name mapping
    ├── schemas.ts    # TypeBox schemas for kota_* tool params
    └── ensure.ts     # Index confirmation flow

设计参考

看 docs/design.md 设计背景（草稿；README+ src/* 是出货行为的真实来源）。

🙏 归因

pi kota建在 城市 数据 库，由创建 尼科·贝隆非常感谢Nico设计和维护为该扩展提供动力的代码智能引擎。

📄 许可证

麻省理工学院——见 许可证 了解详情。

相关 MCP