智能体工程环境sopaco/terrain

Terrain

Terrain 铺好地基，让智能体不必再猜测该站在哪里。

面向人类开发者和 AI 编码助手的工程环境管理——知识是地图，工具是道路，约定是路标。

English · 简体中文

Agent Ready
License: MIT

应用预览

| 项目概览 | 工程知识 | DeepWiki 问答 | 智能体环境 |
|------------------|------------------------------|--------------|-------------------|
|  |  |  |  |

从左到右：带新鲜度评分的项目列表、自动生成的 C4 文档、基于知识的问答，以及一键式智能体工具配置。

目录

- 什么是 Terrain？
- 安装
- 快速开始
- CLI 命令参考
- 为什么选择 Terrain？
- 架构
- 生态系统
- 从 Litho 到 Terrain
- 许可证

什么是 Terrain？

Terrain 是一个标准化、对 AI 友好的工程环境。将它指向一个 Git 仓库，它就会提供三样东西：

terrain_caseflow

- 🗺️ 工程知识——始终同步的 C4 文档和智能体上下文，由你的代码生成，供人类和 AI 智能体共同使用。
- 🤝 共享的智能体契约——Skills、AGENTS.md 和 CLI，让每个编码智能体都以相同方式阅读项目，而不是盲目地在实时仓库中 grep。
- ⚙️ 自动部署的工具链——一条命令即可安装智能体所需的一切（CodeGraph、RTK、预设 Skills）；无需为每个仓库重复折腾。

它可以作为桌面应用（GUI）或 CLI 运行——请参阅快速开始了解该选择哪一个。

三大支柱

| 支柱 | 比喻 | 你将获得 |
|--------|----------|--------------|
| 知识资产 | 地图 | .terrain/ 中由代码生成的双轨文档 |
| 智能体工具链 | 道路 | CodeGraph、RTK 和 Terrain CLI |
| 约定与工作流 | 路标 | Skills、AGENTS.md 和四阶段 SDD 工作流 |

同一套代码库，面向两类受众：

| 受众 | 路径 | 格式 |
|----------|------|--------|
| 人类 | .terrain/human/ | 带 Mermaid 图表的叙述性 C4 文档 |
| AI 智能体 | .terrain/agent/context.md | 结构化架构概览（≤ 14 KiB） |
| 源码索引 | .terrain/agent/repomix.md | Repomix 打包——按需 grep/读取，不预加载 |
| 领域术语 | .terrain/knowledge/ | 业务术语表和内部约定 |

知识工厂

为何脱颖而出

- 增量式——跟踪 Git HEAD，仅重新生成发生变化的部分，而非整个知识库。
- 新鲜度评分——每个资产都带有评分；智能体会对低于 50 分的上下文降权。
- 面向所有智能体的统一契约——Claude Code、Codex、OpenCode 和 Cursor 通过 terrain tools 读取相同的分层。
- 一条命令搞定工具链——terrain env apply 按依赖顺序安装 CodeGraph、RTK 和预设 Skills。
- 可审查的工作流——SDD 将需求 → 设计 → 代码生成 → 审查转化为 Markdown 产物。

性能与集成

- 原生 Rust 核心——单一二进制文件，无运行时，无数据库。扫描、打包、搜索、新鲜度和环境完全离线运行，不调用 LLM。
- 跨平台——为 macOS（Apple Silicon）和 Windows x64 提供预构建桌面安装程序，并在 npm 上提供 @terrain-ai/cli 用于无头机器和 CI。
- 对流水线友好——每次 terrain tools 调用都输出 JSON 到 stdout，terrain ask query --stream 输出 NDJSON 事件流，因此 Terrain 无需胶水代码即可接入 CI 任务、PR 检查和智能体循环。

安装

方式 1——预构建安装程序（推荐）

从 GitHub Releases 下载适用于你平台的软件包并打开——无需 Rust 或 Node 工具链。

| 平台 | 资产 |
|----------|-------|
| macOS（Apple Silicon） | Terrain__macos_aarch64.dmg |
| Windows（x64） | Terrain__windows_x64.exe |

未签名构建——首次启动提示。 安装程序尚未使用 Apple Developer ID / Authenticode 证书签名，因此两个平台都会弹出一次性警告。下载文件是完整的；请参阅下文以继续。

macOS——“Terrain 已损坏 / 应移到废纸篓”

这是 Gatekeeper 的行为，并非文件损坏。从互联网下载的文件带有 com.apple.quarantine 属性，macOS 拒绝启动带有该标志的未签名应用。将 Terrain.app 复制到 /Applications 后移除该标志：

xattr -cr /Applications/Terrain.app

Windows——SmartScreen“Windows 已保护你的电脑”

点击 更多信息 → 仍要运行。每个构建版本仅出现一次该提示。

方式 2——从源码构建

适用于不受支持的平台、自定义补丁，或为 Terrain 本身做贡献。

前置条件

- Rust——稳定工具链（MSRV 1.94；参见 rust-toolchain.toml）
- Node.js / Bun——前端工具链及可选的基于 Node 的工具
- LLM 访问（可选）—— 兼容 OpenAI 的 API、Ollama 或 LM Studio（在桌面应用的 Settings 面板中配置）
- 主流编码代理（可选）—— 例如 Codex、DeepSeek Harness 或 Claude Code，用于知识组合和 SDD 代码生成

构建

克隆并安装前端依赖
git clone https://github.com/sopaco/terrain.git
cd terrain
bun install

构建 Rust 工作区（CLI + 库）
cargo build --release

CLI 二进制文件
./target/release/terrain --help

桌面应用（开发模式）
bun run dev:app

快速开始

我应该使用哪个入口点？

| | 桌面应用（GUI） | CLI |
|---|---|---|
| 最适合 | 日常探索和记录代码库 | 研发基础设施、CI/CD、无头服务器、代理流水线 |
| 你能获得什么 | 所有内容都已预先接好：项目列表、新鲜度评分、C4 文档、问答、环境设置、SDD | 15 个可脚本化的子命令，带 JSON 输出，用于自动化 |
| 需要什么 | 除可选的 LLM 端点外无需其他 | 无需显示器；通过 npm 安装，或让环境集成来部署它 |
| 典型用法 | 在应用中点击浏览 | 在流水线中运行 terrain init、terrain ask query、terrain tools … |

路径 A —— 桌面应用（从这里开始）

该应用捆绑了完整流程，因此无需你自己组合任何内容。

1. 安装并打开 Terrain（参见安装）。
2. 添加项目 —— 将 Terrain 指向本地 Git 仓库。
3. 运行初始化 —— Terrain 扫描仓库，生成六份 C4 文档，并写入 .terrain/。
4. 阅读或提问 —— 在内置阅读器中浏览生成的文档，或在 DeepWiki 问答中提问并获得带引用的答案。
5. 接入你的代理 —— 在 Agent environment 屏幕中一键安装 Skills、CodeGraph、RTK 以及托管的 AGENTS.md 片段。

CLI 已包含在内：环境集成会将其部署到 ~/.terrain/bin/terrain，因此你可以在任何时候切换到终端，而无需单独安装。

路径 B —— CLI（基础设施、CI、代理流水线）

对于无头机器，从 npm 安装 CLI：

npm install -g @terrain-ai/cli   # 或：bunx @terrain-ai/cli

然后从脚本或流水线中驱动相同的知识流水线：

1. 注册一个仓库
terrain assets register ./my-repo --slug my-repo

2. 完整初始化：扫描 + C4 文档 + 代理上下文
terrain init ./my-repo

3. 向知识库提问
terrain ask query "How does authentication flow through this project?" --project my-repo

4. 提交后低成本刷新（跳过文档重新生成）
terrain refresh ./my-repo

典型的 CI 用法 —— 在合并时重新生成知识，然后在作业日志中报告新鲜度：

terrain refresh .
terrain project freshness-cached --project my-repo

外部代理（Claude Code、Codex、OpenCode、Cursor）通过 JSON API 拉取相同的知识：

terrain tools list-projects
terrain tools read-context --project my-repo
terrain tools grep-pack --project my-repo --pattern "authenticate"

CLI 命令参考

你最常用的命令。每个命令都接受全局 --repo-path 覆盖参数。

知识资产

| 命令 | 用途 |
|---------|---------|
| terrain assets register  --slug  | 将仓库注册到本地注册表 |
| terrain init [path] | 完整初始化 — 扫描 + C4 文档 + 智能体上下文 |
| terrain refresh [path] | 快速刷新 — 扫描 + 重新打包 + 上下文，跳过文档生成 |
| terrain ask query  --project  | 基于知识库的自然语言问答（--stream 输出 NDJSON） |
| terrain search  | 对生成的知识进行全文搜索 |
| terrain project overview --project  | 新鲜度评分、文档数量和路径 |

环境标准化

| 命令 | 用途 |
|---------|---------|
| terrain env status | 检查已安装的 Skills、工具和 AGENTS.md 片段 |
| terrain env plan | 预览 apply 将会更改的内容 |
| terrain env apply | 按依赖顺序安装 Skills、CodeGraph、RTK 和 AGENTS.md |
| terrain tools  --project  | 供外部智能体使用的 JSON API — read-context、search、read-doc、grep-pack、freshness |

完整 CLI 指南： Terrain CLI 指南 — 全部 15 个子命令，包括 SDD（sdd run）、token 用量（usage）和流水线内部机制（assets …）。

为什么选择 Terrain？

加入一个新代码库通常意味着要花几天时间阅读源代码和过时的 wiki 页面。Terrain 将这一过程压缩到几分钟：注册一个仓库，运行初始化，即可获得完整的 C4 文档集以及可供智能体使用的上下文包。

| 没有 Terrain | 使用 Terrain |
|------------------|---------------|
| 架构知识分散在 wiki、Slack 和资深工程师的头脑中 | 工程知识资产从实际代码库中生成 |
| AI 助手盲目地在实时仓库中 grep | 智能体先读取 context.md，然后读取有针对性的 repomix 切片 |
| 每次重构后文档都会与代码脱节 | 增量更新 + 新鲜度跟踪；知识随 Git 分支一起流转 |
| 每个团队都要重新发明"如何让 AI 加入我们的仓库" | 环境集成会安装 Skills、CodeGraph、RTK 和 AGENTS.md 片段 |

适用对象：

- 开发者，正在探索或记录代码库
- 技术负责人，希望架构文档与代码保持紧密同步
- 团队，正在采用 AI 编码助手并需要共享的知识契约
- CI/CD 流水线，在合并时重新生成知识资产
- ACP 集成者，将 terrain tools 接入 Claude Code、Codex、OpenCode 或兼容的智能体

架构

系统概览

terrain_caseflow
人类使用桌面应用或 CLI；外部编码代理通过 terrain tools（JSON stdout）使用同一契约。资产存放在仓库内（.terrain/ 随分支一起移动）；~/.terrain/registry.json 仅保存项目指针。

① 知识资产——地图

来自同一工厂的双轨输出——面向人的叙述性 human/，面向机器的结构化 agent/。

生产（scan/pack 离线运行；LLM/ACP 处已注明）：

Git ──scan──► index.md
──pack──► repomix.md
──context (LLM)──► context.md
──docs (ACP)──► human/ + .litho-agent/ checkpoints
──track──► freshness.json

消费——DeepWiki 和 terrain tools 共享相同的三个层：

| 层 | 来源 | API |
|-------|--------|-----|
| 宏观 | agent/context.md | read-context |
| 中观 | human/、knowledge/ | search、read-doc |
| 微观 | agent/repomix.md | grep-pack → read-pack-file |

当来源冲突时：repomix > CodeGraph > context.md > human/。当 freshness_score  Intel[terrain-agent]
Chan --> Core[terrain-core]
Intel --> Core
Intel --> LLM[LLM]
Intel --> ACP[ACP]
Core --> FS[".terrain/ · Git · registry"]

Core 在没有 LLM 的情况下处理 scan、pack、search、freshness 和 env。Agent 编排 DeepWiki、知识生成、SDD 和上下文生成——轻量任务通过原生 LLM，重度使用工具的工作通过 ACP 子进程。

.terrain/ 目录（按项目）

{your-repo}/.terrain/
├── index.md                 # Project index (from scan)
├── agent/
│   ├── context.md           # Macro architecture context for agents
│   ├── repomix.md           # Source pack (generated, often gitignored)
│   └── meta.json            # Pack metadata
├── human/                   # 工程知识文档（1.Overview.md、2.Architecture.md……）
├── knowledge/               # 领域术语表和约定
├── .meta/
│   ├── sync.json            # 扫描同步状态
│   └── freshness.json       # 资产新鲜度评分
└── .litho-agent/            # Litho/知识研究工作区（临时）

生态系统

Terrain 与你 AI 工作流中已在使用的工具协同工作：

| 组件 | 角色 |
|-----------|------|
| Claude Code / Codex / OpenCode / ACP agents | 在隔离进程中执行知识组合、SDD 代码生成和工具调用 |
| Repomix | 将源代码打包为便于 grep 的索引，供 agent 使用 |
| CodeGraph | 通过 bunx codegraph 进行符号调用者/被调用者/影响查询 |
| RTK | 压缩 shell 输出以节省 token（npm 上的 @terrain-ai/rtk，或 ~/.terrain/bin/rtk） |
| Terrain CLI | 扫描、资产、用于 ACP 的 terrain tools（npm 上的 @terrain-ai/cli，或 ~/.terrain/bin/terrain） |
| Preset Skills | preset_skills/ 中的 LLM 工作流指令（knowledge、SDD、Ask、Context） |
| DeepWiki / Litho Book | 基于知识的问答和 Markdown 阅读器，集成在桌面 UI 中 |

编码 agent 的信任模型：当来源冲突时，repomix source > CodeGraph > context.md > human docs。

从 Litho 到 Terrain

Terrain 的知识引擎是 Litho 的直接继承者，Litho 是以 deepwiki-rs（1.7k★）发布的 AI 文档生成器。Litho 大规模验证了核心论点——从代码生成架构文档，保持同步，使其可供 agent 使用。Terrain 将这一实践强化为一个平台：增量更新而非完全重新生成、广泛的语言和框架适配、面向外部 agent 的 ACP 访问，以及内置于桌面应用中的 Litho Book 阅读器和问答。

简而言之：如果你喜欢 Litho 的文档功能，Terrain 就是 Litho 的知识核心加上围绕它的环境、工作流和 agent 桥接。

许可证

MIT — 参见 LICENSE。