CostAffective-MCP

完整安装指南及针对不同平台的版本：costwise-mcp.vercel.app/docs/install

快速安装（Linux / macOS / Windows（通过 WSL））

推荐方式——一条命令：

curl -fsSL https://raw.githubusercontent.com/okyashgajjar/costwise-mcp/main/install.sh | bash

该脚本会完成所有操作：

1. 在 Windows 上检测 Git Bash / MSYS，并自动通过 WSL 执行
2. 检查是否安装了 Go，若未安装则安装
3. 检查是否安装了 C 编译器（CGO 依赖项），若未安装则安装
4. 克隆仓库并从源代码构建
5. 安装到 /usr/local/bin/costwise
6. 检测 AI 编码客户端，并询问要连接哪些客户端
7. 为所选客户端配置 MCP（除非使用 --no-skill，否则还会安装会话技能）

Windows（原生 PowerShell）

除非你已安装 Go 和 gcc，否则不推荐此方式。请手动构建：

git clone https://github.com/okyashgajjar/costwise-mcp.git
cd costwise-mcp
$env:CGO_ENABLED=1
go build -o costwise.exe ./cmd/costwise/

或者使用推荐方式——安装 WSL（Windows 10 2004+ / Windows 11）：

# In PowerShell as Administrator:
wsl --install

# Then in WSL:
curl -fsSL https://raw.githubusercontent.com/okyashgajjar/costwise-mcp/main/install.sh | bash

macOS / Linux（手动构建）

需要 Go 1.25+ 和 C 编译器（CGO 为必需项——请参阅下方的构建说明）。

git clone https://github.com/okyashgajjar/costwise-mcp.git
cd costwise-mcp
CGO_ENABLED=1 go build -o costwise ./cmd/costwise/
sudo mv costwise /usr/local/bin/
costwise --version

包含架构和示例的交互式工具目录：costwise-mcp.vercel.app/tools

检索工具

search_code

由原生 Bluge 倒排索引和 Tree-sitter 驱动的语义仓库搜索。

*原因：*自然语言问题（“缓存在哪里实现？”）应直接返回相关作用域，而不是列出文件让模型逐个打开。全新的 Bluge 索引原生支持快速 BM25/TF-IDF 评分、模糊匹配和同义词扩展，无需 AI 开销。

示例：Where is caching implemented?

find_symbol

查找符号的定义位置。

原因：“X 定义在哪里”是最常见的导航问题。查询结果应是一个位置，而不是一个文件。

示例：Find UserService

read_symbol

按名称返回符号的完整实现代码。

原因：“给我看看 X 是如何工作的”应只需读取索引中的一段行范围，而不是转储整个文件，或让 Agent 循环搜索来重建代码主体。

示例：Show the body of GetOrCreateRepoSession

find_references

查找符号的所有用法。

*原因：*影响分析（“这项更改会破坏什么？”）需要预先计算出所有用法，而不是实时搜索整个代码树。CostWise 现已支持标准 LSIF（dump.lsif）数据导入，可提供 100% 准确、经编译器验证的引用。如果无法使用 LSIF，则会平滑回退到 Tree-Sitter 正则表达式近似匹配。

示例：Where is UserService used?

find_callers

查找调用某个函数的函数。

*原因：*理解调用链应读取已存储的调用关系，而不是让模型通过阅读调用方文件来重建调用链。

示例：What calls processPayment()?

说明：search_code 已在内部采用精确文本/全文搜索策略，因此无需单独使用工具即可匹配字面文本。若要对文件执行原始正则表达式搜索，请使用宿主提供的原生文件搜索功能。

维护工具

get_repository_summary

仓库的令牌预算概览：语言、按符号数量排名靠前的模块，以及关键符号。传入 module 可深入查看某个目录，传入 budget（small / medium / large）可限制输出。

原因： 这通常是会话中的首次调用，因此也是最先进入缓存上下文并一直保留的内容。早期版本会为每个目录输出一行，还会输出完整的逐目录链，且没有限制——对于大型单体仓库，这会产生数万个令牌，并在整个会话中持续占用缓存。现在输出有严格上限：无论仓库有多大，输出都会保持精简；需要时可通过 module 按需获取详情。

index_repository

手动刷新或重建仓库索引。通常不需要，因为看门狗会自动重新索引。

上下文控制工具（V2）

这些工具用于解决上述缓存成本问题。它们能让模型将大量内容和持久事实无损地保留在常驻窗口之外。

remember

将一条简短的持久事实（决策、入口点或注意事项）保存到每个仓库专属的存储中，这样每次相关时就不必在对话中重复说明。

原因： 模型每轮都重新推导或重新粘贴的事实，只会徒增缓存开销。把它们记下来；需要时再读回。

stash_context

将一大段内容（整个文件、很长的命令或测试输出、生成的报告）暂存到对话之外，并返回一个简短的句柄。内容不会丢失——完整内容会写入磁盘，之后仍可重新获取。

原因： 这是最直接的窗口大小控制手段。将一份 5,000 行的日志直接粘贴到对话中，在本会话剩余的每一轮里都会被重新读取，并可能重新写入缓存。暂存后只需约 20 个令牌（句柄），且仅在需要时才取回相关片段。

示例：暂存一份 5,000 行的日志，在上下文中只保留约 20 个令牌。

recall

只取回所需内容：按句柄取回暂存内容中符合预算的片段，或取回匹配的已记忆事实，而不是重新阅读整个内容。

原因：“按需查询获取输出”是这个循环中的读取环节。与 stash_context 结合后，流程就变成：暂存庞大的内容，然后仅取回与查询匹配的行，并控制在令牌预算内。

循环：stash_context（暂存）→ recall（仅取回所需片段）→ remember（保留持久结论）。内容始终可以恢复；上下文窗口保持精简。

了解典型会话从第一条命令到最终答案的全过程，以及有多少令牌不会进入上下文窗口。

步骤 1 — 安装并建立索引

curl -fsSL https://raw.githubusercontent.com/okyashgajjar/costwise-mcp/main/install.sh | bash
# Script detects OS, installs Go + C compiler if needed,
# builds binary, detects AI coding clients, and writes MCP config.
# The server auto-indexes your repo on first connection.

步骤 2 — 开始编码会话

你的 AI Agent 通过 MCP 连接到 CostWise。连接后，Agent 会收到约 275 个令牌的会话技能说明，从而知道要使用 stash/recall/remember，而不是将内容直接粘贴到上下文中。

步骤 3 — 提出导航问题

Agent 不会倾倒整个文件，而是调用：

find_symbol("UserService")
→ user_service.go:142

read_symbol("UserService")
→ func (s *UserService) Create(ctx context.Context, req *CreateRequest) (*User, error) {
      // full body returned, not the whole file
  }

开销：约 50 个令牌。不使用 CostWise 时，Agent 会将 user_service.go（可能超过 500 行）读入上下文窗口。

步骤 4 — 追踪影响范围

你问：“谁调用了 validateInput？”Agent 会调用：

find_callers("validateInput")
→ processPayment (payment.go:310)
  → validateOrder (order.go:88)
    → validateInput (validator.go:45)

开销：约 30 个令牌。不使用 CostWise 时，Agent 会逐个打开文件，阅读调用方并重建调用链。数百个令牌会进入上下文窗口。

步骤 5 — 运行测试并遇到失败

测试失败，并生成了 2,000 行日志。Agent 不会将整份日志直接粘贴到上下文中，而是：

stash_context(label="test-failure-output", content=<full 2000-line log>)
→ Stashed → abc123 (~28,000 tokens kept out of context)

句柄的开销：上下文中约 20 个令牌。完整日志保留在磁盘上。

步骤 6 — 调查失败原因

recall(source="abc123", query="FAIL|panic|error")
→ test_service_test.go:42: TestCreateUser FAILED
    expected: 201, got: 500
    error: database connection refused

开销：约 40 个令牌（仅包含匹配的行）。不使用 CostWise 时，Agent 会重新读取或重新粘贴整份 2,000 行日志。

步骤 7 — 记住发现

remember(key="db-conn-fix", fact="Database connection refused in tests — check DB_HOST env var in .env.test")
→ Remembered "db-conn-fix"

开销：约 20 个令牌，并会在本次会话的剩余时间以及后续会话中保留。

步骤 8 — 稍后回忆事实

recall(query="db fix")
→ db-conn-fix: Database connection refused in tests — check DB_HOST env var in .env.test

无需重新推导修复方法。开销：约 15 个令牌。

总结

在完整会话中，这些节省累积起来，可使常驻上下文窗口中的令牌减少 80% 以上，而且后续每一轮所需读取的缓存也更少。

测试不同规模仓库中 CostWise 服务端的“真实且未经修饰”的令牌占用：

小型仓库（约 50 个文件）

• 朴素的全仓库上下文开销：约 12,500 个令牌
• get_repository_summary（small）：286 个令牌（0.01 秒）
• search_code（精确匹配）：4 个令牌（0.31 秒）
• read_symbol：24 个令牌（0.01 秒）
• 相比朴素读取的平均令牌节省率：99.16%

中型仓库（约 250 个文件）

• 朴素的全仓库上下文开销：约 62,500 个令牌
• get_repository_summary（small）：528 个令牌（0.04 秒）
• search_code（精确匹配）：4 个令牌（0.60 秒）
• read_symbol：24 个令牌（0.03 秒）
• 相比朴素读取的平均令牌节省率：99.70%

大型仓库（约 1,000 个文件）

• 朴素的全仓库上下文开销：约 250,000 个令牌
• get_repository_summary（small）：517 个令牌（0.18 秒）
• search_code（精确匹配）：4 个令牌（4.38 秒）
• read_symbol：24 个令牌（0.37 秒）
• 相比朴素读取的平均令牌节省率：99.93%

存在的原因： 上述上下文控制工具只有在模型实际使用它们时才有帮助。若任由模型按默认方式行事，它会毫不犹豫地把整个文件直接贴出来。costwise-session 技能是一小段会话感知指南，用来在每次会话中教会模型一次精简工作流，之后便会自动应用——将大型输出交给 stash_context / recall 处理，用 remember 持久保存重要事实，并优先进行精准检索，而不是读取整个文件。

它刻意设计得很精简（约 275 个 token）。这是每次会话固定的一次性开销，只要能避免一次大型内容块进入上下文窗口，就能收回成本。

它通过两种方式提供，因此无需你持续操作，就能在任何地方使用：

1. 自动适用于每种编辑器。 MCP 服务通过协议的 instructions 字段提供指南。每个 MCP 客户端连接时都会加载这些指南——包括 Claude Code、Cursor、Codex、OpenCode、Antigravity，以及任何其他兼容 MCP 的客户端。无需配置，也无需为每种编辑器准备单独文件。

2. 作为原生 Claude Code 技能。 运行 costwise install 还会写入 ~/.claude/skills/costwise-session/SKILL.md（使用 --no-skill 可选择不安装）。你可以直接管理它：

   costwise skill install      # write the skill (global)
   costwise skill install --local   # write it into the current project only
   costwise skill uninstall    # remove it
   costwise skill print        # print the guidance for manual placement in any tool
   

对于会读取自身规则或说明文件的编辑器，运行 costwise skill print 会输出相应指南，供你粘贴使用。这两种提供方式都基于同一份权威内容。

交互式架构图及组件深入介绍：costwise-mcp.vercel.app/architecture

面向企业的功能：

• 零延迟冷启动： 集成我们的 GitHub Action（costwise-action），在 CI/CD 上预先计算 SQLite cache.db。本地启动时，CostWise 会立即下载预先计算好的构建产物。
• 团队共享缓存： 配置 COSTWISE_PG_URL，连接 Postgres 后端，而非本地 SQLite。开发者 A 暂存的内容和记住的事实，会立即对开发者 B 可用。
• 策略引擎： 使用 costwise validate，根据集中管理的 costwise-architecture.yaml 配置执行严格的 AST 架构边界检查。

AI Client (MCP Host)
    │
    ├── stdio transport ──► costwise serve (MCP Server)
    │                           │   advertises session guidance via the MCP instructions field
    │                           │
    │                           ├── Session Manager (per-repo, persistent across tool calls)
    │                           ├── Repository State Manager
    │                           ├── Watchdog
    │                           ├── Shared Indexer
    │                           │
    │                           ├── Tree-sitter Parser
    │                           ├── Symbol Index
    │                           ├── Reference Index
    │                           ├── Call Graph Index
    │                           │
    │                           ├── search_code ───────────► tree-sitter AST match
    │                           ├── find_symbol ───────────► SymbolDB lookup
    │                           ├── read_symbol ───────────► SymbolDB body read
    │                           ├── find_references ───────► SymbolDB reference search
    │                           ├── find_callers ──────────► SymbolDB call graph
    │                           ├── get_repository_summary ► KnowledgeStore (token-budgeted)
    │                           ├── index_repository ──────► SharedIndexer
    │                           ├── remember ──────────────► per-repo durable facts
    │                           ├── stash_context ─────────► large blobs parked out of context
    │                           └── recall ────────────────► query-scoped read-back

每个仓库的所有状态（索引、暂存内容、事实）都存放在该仓库的本地索引目录中，因此不同仓库之间不会相互覆盖。

1. 移除 MCP 客户端配置（这也会移除会话技能）：

costwise uninstall --all

2. 删除二进制文件：

Linux / macOS：

rm -f "$(command -v costwise)"

Windows：

Remove-Item (Get-Command costwise).Source -Force

所有 CostWise 数据都存放在两个位置。以下说明了需要时如何查找和删除这些数据。

仓库级存储（.mycli-fts/）

在每个已建立索引的仓库根目录下创建。包含该仓库专属的所有内容：

清除某个仓库的所有数据：

rm -rf /path/to/your/repo/.mycli-fts

索引会在下次会话时自动重建。

全局存储（/tmp/）

所有仓库共用。这里有个已知的隐患——这些数据并非按仓库隔离，可能会互相覆盖：

rm -f /tmp/repo_memory.db /tmp/discovery_memory.db

欢迎各种形式的贡献，包括修复错误、新增语言解析器、改进检索器、完善文档和基准测试。

完整详情请参阅 CONTRIBUTING.md。

贡献者的重要文档：

• 置信度与准确性评分 — 全面介绍每个检索工具如何评分、排序并应用置信度阈值。涵盖 FTS、Tree-sitter、Grep、Reference、Call Graph、Architecture、Flow Graph 以及 Query/Answer Type 分类器的精确公式、置信度上限、质量门槛和决策逻辑。

快速开始：

git clone https://github.com/okyashgajjar/costwise-mcp.git
cd costwise-mcp
CGO_ENABLED=1 go build ./...
CGO_ENABLED=1 go test ./...

适合新手的议题：

• 为新语言添加 Tree-sitter 语法
• 修复共享 /tmp/ 数据库路径互相覆盖的问题（需要按仓库隔离路径）
• 改进特定答案类型的压缩
• 为远程部署添加 SSE/HTTP 传输
• 编写更好的基准测试

不知道从哪里开始？可以创建议题寻求指导。

git clone https://github.com/okyashgajjar/costwise-mcp.git
cd costwise-mcp
CGO_ENABLED=1 go build ./...
CGO_ENABLED=1 go test ./...

在 Ubuntu/Debian 上：sudo apt install gcc libsqlite3-dev。在 macOS 上：Xcode Command Line Tools。在 Windows 上：MinGW-w64。

存在的原因： 模型应当知道它正在查询的索引是否可信。CostWise 跟踪三种状态，并据此采取相应行为。

Agent 模式可在需要时自动建立索引；交互模式会先提示。

探索详细的使用场景案例：costwise-mcp.vercel.app/use-cases

• AI 编码 Agent — 通过压缩后的作用域级查询减少令牌开销，并将大型内容移出上下文，让长会话保持低成本。
• 大型单体仓库 — 使用 SQLite 索引以微秒级速度查询，而非扫描磁盘；预算受限的摘要无论仓库规模如何都能保持精简。
• 代码审查 — 追踪调用方层级，审查新增变更的影响。
• 仓库审计 — 生成文件分布、语言占比和结构摘要。
• MCP 开发 — 为 stdio 协议、fsnotify 监视器、tree-sitter 映射和 MCP instructions 字段提供参考实现。

costwise doctor 会检查：

• 二进制文件是否存在及其权限
• PATH 是否可见
• 各客户端的 MCP 配置
• 服务启动情况
• 仓库状态

仍然无法解决？运行 costwise doctor，并附上输出内容提交 issue。

通过安装脚本（install.sh），支持所有具备 Go 1.25+ 和 C 编译器的平台；该脚本会自动完成工具链设置：

• Linux amd64 / arm64
• macOS amd64 / arm64（Intel 和 Apple Silicon）
• Windows amd64

Linux amd64 和 Windows amd64 提供预构建的发布二进制文件。其他所有平台均由安装脚本从源代码构建。