AI 助手总是瞎猜项目架构？Terrain 让它站在正确的地方

荣江
0 阅读3分钟

在这里插入图片描述

Terrain — prepares the ground so agents don't have to guess where to stand.

🔗 GitHub：github.com/sopaco/terr…

你是否遇到过这样的场景？

接手一个新项目，打开数百个文件盲目搜索架构信息；让 AI 助手帮忙理解代码库，它却只能对着实时仓库盲目 grep；每次重构后，Wiki 文档和实际代码已经脱节，却没人注意到……

Terrain 就是为解决这些问题而生的。

它是一个面向人类开发者与 AI 编码助手的工程环境管理平台。指向一个 Git 仓库，Terrain 会自动扫描代码、生成架构文档、打包源码索引、构建知识体系——让每一个使用者（人或 AI）都能在几分钟内而不是几天内理解整个项目。

在这里插入图片描述

上图：Terrain 桌面端的项目列表界面，每个项目都带有新鲜度评分，一眼就能知道知识是否过时。

三大核心支柱

支柱比喻你得到什么
知识资产🗺️ 地图从代码中自动生成的 C4 架构文档和 Agent 上下文，始终与代码同步
Agent 工具链🛤️ 道路CodeGraph、RTK、Terrain CLI——一条命令装好所有工具
约定与工作流📍 路标Skills、AGENTS.md、四阶段 SDD 工作流——让 AI 按同一套规则工作

一份代码库，两类受众

Terrain 的核心理念是：同一份知识，同时服务人类和 AI。

受众获取路径格式
人类开发者.terrain/human/带 Mermaid 图表的叙述性 C4 文档
AI 编码助手.terrain/agent/context.md结构化架构概览（≤ 14 KiB）
AI 源码检索.terrain/agent/repomix.mdRepomix 源码包——按需 grep，非预加载
业务知识.terrain/knowledge/业务术语表和内部约定

在这里插入图片描述

知识工厂：从 Git 仓库出发，经过扫描、打包、上下文生成、文档产出，最终形成双轨知识资产。

为什么选择 Terrain？

  • 🕐 分钟级 onboarding — 注册仓库 → 运行初始化 → 获得完整 C4 文档集和 Agent 就绪上下文，把数天的熟悉成本压缩到几分钟
  • 🔄 增量更新 — 追踪 Git HEAD，只重新生成变更部分，而非全量重建
  • 📊 新鲜度评分 — 每份知识资产都有评分，Agent 会自动降低过时信息的权重
  • 🤝 统一 Agent 契约 — Claude Code、Codex、OpenCode、Cursor 都通过同一份 terrain tools 接口读取知识
  • ⚡ 原生 Rust 性能 — 单一二进制，无运行时、无数据库，scan/pack/search/freshness 全部离线执行
  • 🧩 工具链一键部署 — terrain env apply 按依赖顺序安装 CodeGraph、RTK 和预设 Skills

核心架构速览

graph TB
    subgraph 用户侧
        Desktop[Tauri 桌面应用<br/>Svelte 5 UI]
        CLI[CLI 终端]
    end
    subgraph 执行层
        Agent[terrain-agent<br/>ChatEngine · SDD · DeepWiki]
    end
    subgraph 核心层
        Core[terrain-core<br/>扫描 · 打包 · 检索 · 新鲜度]
    end
    subgraph 外部生态
        Repomix[repomix-core<br/>源码打包]
        CodeGraph[CodeGraph<br/>符号图谱]
        LLM[LLM 提供者<br/>OpenAI / Ollama]
        ACP[ACP Agent<br/>opencode 等]
    end

    Desktop -->|invoke + 流式事件| Agent
    CLI --> Agent
    Agent --> Core
    Agent --> LLM
    Agent --> ACP
    Core --> Repomix
    Core --> CodeGraph
    Core -->|&#34;增量刷新 + 新鲜度评分&#34;| Repomix

架构要点：

  • terrain-core 是领域核心，不执行 LLM，负责扫描、打包、检索、新鲜度评分等纯计算任务
  • terrain-agent 是执行层，负责编排 DeepWiki 问答、知识生成、SDD 工作流
  • 轻量任务走原生 LLM（ADK Runner），重度工具调用走 ACP 子进程
  • 所有 Rust 类型通过 ts-rs 自动生成 TypeScript 前端类型，确保 IPC 契约零漂移

开箱即用

# 预编译安装包（推荐）
# macOS / Windows 均可从 GitHub Releases 下载

# 或通过 npm 安装 CLI
npm install -g @terrain-ai/cli

# 注册项目并初始化
terrain init ./my-repo

# 向知识库提问
terrain ask query "项目的鉴权流程是怎样的？" --project my-repo

社区与生态

Terrain 脱胎于 Litho/deepwiki-rs（1.7k★），已经过大规模验证。它将 Litho 的文档能力扩展为完整的工程环境平台——加上环境标准化、工作流管理和 Agent 桥接层。

MIT 开源协议，期待你的贡献！

"Terrain prepares the ground so agents don't have to guess where to stand."

avatar
文章
阅读
粉丝