智能体工程环境 sopaco/terrain

Terrain

Terrain 先把地面铺好，智能体就不用猜自己该站在哪儿。

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

English · 简体中文

应用预览

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

从左到右：带新鲜度评分的项目列表、自动生成的 C4 文档、基于知识的问答，以及一条命令搞定智能体工具安装。

目录

- Terrain 是什么？
- 安装
- 快速上手
- 命令行命令参考
- 为什么选 Terrain？
- 架构
- 生态
- 从 Litho 到 Terrain
- License

Terrain 是什么？

Terrain 是一套标准化、对 AI 友好的工程环境。把它指向一个 Git 仓库，它会交付三样东西：

terrain_caseflow

- 🗺️ 工程知识——始终同步的 C4 文档和智能体上下文，从你的代码产出，供人类和 AI 智能体共同消费。
- 🤝 一份共享的智能体契约——技能、AGENTS.md 和命令行工具，让每个编程智能体都用同一种方式读项目，而不是对着线上仓库盲目 grep。
- ⚙️ 自动部署的工具链——一条命令装好智能体需要的东西（CodeGraph、RTK、预设技能）；不用每个仓库都折腾一遍。

它既能作为桌面应用（GUI）运行，也能作为命令行运行——该选哪个，见快速上手。

三大支柱

| 支柱 | 比喻 | 你得到什么 |
| 知识资产 | 地图 | .terrain/ 里的双轨文档，从代码产出 |
| 智能体工具 | 道路 | CodeGraph、RTK 和 Terrain 命令行 |
| 约定与工作流 | 路标 | 技能、AGENTS.md 和四阶段 SDD 工作流 |

同一份代码库，两类读者：

| 读者 | 路径 | 格式 |
| Humans | .terrain/human/ | 带 Mermaid 图的叙事型 C4 文档 |
| AI agents | .terrain/agent/context.md | 结构化架构概览（≤ 14 KiB） |
| Source index | .terrain/agent/repomix.md | Repomix 打包文件——按需 grep/read，不预加载 |
| Domain terms | .terrain/knowledge/ | 业务术语表和内部约定 |

知识工厂

为什么它更胜一筹

- 增量更新——跟踪 Git HEAD，只重新生成变化的部分，而不是整个知识库。
- 新鲜度评分——每份资产都带评分；智能体会降低低于 50 分的上下文权重。
- 所有智能体共用一套契约——Claude Code、Codex、OpenCode 和 Cursor 都通过 terrain tools 读取相同的分层。
- 一条命令搞定工具链——terrain env apply 按依赖顺序安装 CodeGraph、RTK 和预设技能。
- 工作流可审查——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_<version>_macos_aarch64.dmg |
| Windows（x64） | Terrain_<version>_windows_x64.exe |

未签名构建——首次启动提示。 安装包尚未用 Apple Developer ID / Authenticode 证书签名，所以两个平台都会弹出一次性警告。下载文件是完整的；继续操作见下文。

macOS——「Terrain is damaged / should be moved to the Trash」

这是 Gatekeeper 在拦，不是文件损坏。从互联网下载的文件带有 com.apple.quarantine 属性，macOS 拒绝启动带此标记的未签名应用。把 Terrain.app 复制到 /Applications 后，移除该标记：

xattr -cr /Applications/Terrain.app

Windows——SmartScreen 提示「Windows protected your PC」

点击 More info → Run anyway。每个构建版本只会出现一次。

方式 2——从源码构建

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

前置条件

- Rust——stable 工具链（MSRV 1.94；见 rust-toolchain.toml）
- Node.js / Bun——前端工具链和可选的 Node 工具
- LLM 接入（可选）——兼容 OpenAI 的 API、Ollama 或 LM Studio（在桌面应用的 Settings 面板里配置）
- 主流编码智能体（可选）——例如 Codex、DeepSeek Harness 或 Claude Code，用来做知识组装和 SDD 代码生成

构建

Clone and install frontend dependencies
git clone https://github.com/sopaco/terrain.git
cd terrain
bun install

Build Rust workspace (CLI + libraries)
cargo build --release

CLI binary
./target/release/terrain --help

Desktop app (development)
bun run dev:app

快速上手

该用哪个入口？

| | 桌面应用（GUI） | 命令行 |
| 最适合 | 日常探索代码库、写文档 | 研发基础设施、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 片段。

命令行也包含在内：环境集成会把它部署到 ~/.terrain/bin/terrain，所以你随时可以切到终端，不用另外安装。

路径 B —— 命令行（基础设施、CI、智能体流水线）

无头机器上，从 npm 安装命令行：

npm install -g @terrain-ai/cli # or: bunx @terrain-ai/cli <command>

然后在脚本或流水线里驱动同一套知识管线：

1. Register a repository
terrain assets register ./my-repo --slug my-repo

2. Full initialization: scan + C4 docs + agent context
terrain init ./my-repo

3. Ask the knowledge base
terrain ask query "How does authentication flow through this project?" --project my-repo

4. Cheap refresh after commits (skips doc regeneration)
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"

命令行命令参考

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

知识资产

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

环境标准化

| 命令 | 用途 |
| terrain env status | 查看已安装哪些技能、工具和 AGENTS.md 片段 |
| terrain env plan | 预览 apply 会改动什么 |
| terrain env apply | 按依赖顺序安装技能、CodeGraph、RTK 和 AGENTS.md |
| terrain tools <command> --project <slug> | 给外部智能体用的 JSON API —— read-context、search、read-doc、grep-pack、freshness |

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

为什么选 Terrain？

上手一个新代码库，通常要花好几天读源码和过时的 wiki 页面。Terrain 把这段时间压缩到几分钟：注册仓库，跑一次初始化，就能拿到一整套 C4 文档，外加一份智能体可直接用的上下文包。

| 没有 Terrain | 有 Terrain |
| 架构知识散落在 wiki、Slack 和资深工程师脑子里 | 工程知识资产直接从真实代码库生成 |
| AI 助手盲目 grep 线上仓库 | 智能体先读 context.md，再按需读取 repomix 切片 |
| 每次重构后文档都和代码脱节 | 增量更新 + 新鲜度跟踪；知识随 Git 分支一起走 |
| 每个团队都要重新摸索「怎么让 AI 上手我们的仓库」 | 环境集成会安装技能、CodeGraph、RTK 和 AGENTS.md 片段 |

为谁而建：

- 开发者，正在探索或记录某个代码库
- 技术负责人，想要紧贴代码的架构文档
- 团队，正在引入 AI 编程助手，需要一份共享的知识契约
- CI/CD 流水线，在合并时重新生成知识资产
- ACP 集成方，把 terrain tools 接入 Claude Code、Codex、OpenCode 或兼容的智能体

架构

系统总览

terrain_caseflow
人类使用 桌面应用 或 命令行；外部编码智能体通过 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 < 50 时，降低宏观上下文的权重。

② 智能体工具链 —— 道路

terrain env apply 安装导航层，让智能体不必即兴发挥：

| 组件 | 用途 |
| 工具 | ~/.terrain/bin/ —— CodeGraph、RTK、terrain 命令行（terrain tools 用于 ACP） |
| 技能 | 标准操作手册 —— terrain-knowledge → repomix → codegraph → rtk |
| AGENTS.md | 托管片段 —— 知识优先工作流、代码用 repomix、shell 用 RTK |

③ 约定与工作流 —— 路标

SDD 定义一条可重复的路径；每个阶段产出一份可评审的 Markdown 产物：

| 阶段 | 输出 | 引擎 |
| 需求 | 1.requirements.md | 原生 LLM |
| 技术设计 | 2.tech-design.md | 原生 LLM |
| 代码生成 | 3.implementation.md + 仓库变更 | ACP 智能体 |
| 代码评审 | 4.code-review.md | 原生 LLM |

terrain sdd run --project my-repo --phase requirements

会话输出位于 ~/.terrain/sdd/{project}/sessions/{id}/outputs/（本地，不纳入版本管理）。知识流水线使用同样的可恢复模式 —— 研究检查点位于 .terrain/.litho-agent/。

运行时

graph LR
Chan[Desktop · CLI] --> Intel[terrain-agent]
Chan --> Core[terrain-core]
Intel --> Core
Intel --> LLM[LLM]
Intel --> ACP[ACP]
Core --> FS[".terrain/ · Git · registry"]

Core 处理 scan、pack、search、freshness 和 env，无需 LLM。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 的索引，供智能体使用 |
| 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 中 |

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

从 Litho 到 Terrain

Terrain 的知识引擎直接继承自 Litho——以 deepwiki-rs（1.7k★）发布的 AI 文档生成器。Litho 在规模化场景下验证了核心命题——从代码生成架构文档，保持同步，让智能体可直接使用。Terrain 把这套实践打磨成平台：增量更新取代全量重新生成，广泛适配各种语言与框架，为外部智能体提供 ACP 访问，并把 Litho Book 阅读器和问答内置到桌面应用。

一句话：如果你喜欢用 Litho 写文档，Terrain 就是 Litho 的知识内核加上围绕它的环境、工作流和智能体桥接。

许可证

MIT——见 LICENSE。