Terrain—prepares the ground so agents don’t have to guess where to stand.
🔗 GitHub：https://github.com/sopaco/terrain
你是否遇到过这样的场景？
接手一个新项目，打开数百个文件盲目搜索架构信息；让 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.md | Repomix 源码包——按需 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
核心架构速览
架构要点：
terrain-core是领域核心，不执行 LLM，负责扫描、打包、检索、新鲜度评分等纯计算任务terrain-agent是执行层，负责编排 DeepWiki 问答、知识生成、SDD 工作流- 轻量任务走原生 LLM（ADK Runner），重度工具调用走 ACP 子进程
- 所有 Rust 类型通过 ts-rs 自动生成 TypeScript 前端类型，确保 IPC 契约零漂移
开箱即用
# 预编译安装包（推荐）# macOS / Windows 均可从 GitHub Releases 下载# 或通过 npm 安装 CLInpminstall-g@terrain-ai/cli# 注册项目并初始化terrain init ./my-repo# 向知识库提问terrain ask query"项目的鉴权流程是怎样的？"--projectmy-repo社区与生态
Terrain 脱胎于 Litho/deepwiki-rs（1.7k★），已经过大规模验证。它将 Litho 的文档能力扩展为完整的工程环境平台——加上环境标准化、工作流管理和 Agent 桥接层。
MIT 开源协议，期待你的贡献！
“Terrain prepares the ground so agents don’t have to guess where to stand.”
