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

🔗 GitHub：https://github.com/sopaco/terrain

一个真实的困境

你的团队同时使用 Claude Code、Codex、OpenCode 和 Cursor。每个助手都有自己的理解方式——Claude 读取 AGENTS.md，Cursor 读取 .cursorrules，Codex 有自己的上下文机制。

结果是什么？

• 同一个项目，每个 AI 的理解都不一样
• 你在每个工具里重复配置"项目规则"
• AI 助手之间互相矛盾的回答让开发者困惑
• 新加入的 AI 工具需要重新"教育"

Terrain 提供了一个统一的知识契约——让所有 AI 编码助手读取同一份知识，以同一套规则工作。

---

三层知识体系：一个契约，两类消费者

Terrain 将知识资产分为三层，所有 AI Agent 都通过 terrain tools 接口访问同一份数据：

层级	资产	Agent 如何消费
宏观	agent/context.md	预加载的架构概览（≤ 14 KiB），Agent 的"第一印象"
中观	human/、knowledge/	按需搜索和读取文档
微观	agent/repomix.md	精准 grep 源码切片——Agent 的唯一源码入口

无论底层是哪个 AI 引擎，DeepWiki 的问答都基于同一份三层知识体系，回答附带精确引用。

---

terrain tools：一个接口适配所有 Agent

外部编码 Agent（Claude Code、Codex、OpenCode、Cursor）无需关心底层实现，只需调用 terrain tools 即可获取知识：

# 获取项目宏观架构上下文
terrain tools read-context --project my-repo

# 全文搜索知识库
terrain tools search --project my-repo --pattern "authenticate"

# 在源码索引中精准搜索
terrain tools grep-pack --project my-repo --pattern "handler"

# 查看知识新鲜度
terrain tools freshness --project my-repo

所有命令输出 JSON，可无缝集成到任何 Agent 的工具调用中。这意味着：

• Claude Code 可以在执行前先 read-context 了解全局架构
• Codex 可以用 grep-pack 精准定位相关代码，而非盲目 grep
• Cursor 可以用 search 获取业务术语的准确定义
• OpenCode 可以通过 ACP 子进程直接驱动 Terrain 的完整工作流

---

环境集成：一次配置，处处生效

terrain env apply 一键为所有 Agent 部署标准化的工具链：

组件	作用
Skills	标准化工作流程指令（知识查询、SDD、Ask、架构分析）
CodeGraph	符号调用关系图谱 — 谁调用了谁
RTK	压缩 Shell 输出，节省 Token
AGENTS.md	统一的项目约定片段——所有 Agent 读取同一份

Terrain 的 Agent 环境配置界面，一键安装所有 Agent 所需的 Skills、工具链和约定文件。

---

核心技术：为什么能"统一"？

Rust 作为唯一真源

Terrain 的 IPC 契约以 Rust 结构体为唯一真源，通过 ts-rs 自动生成 TypeScript 类型。这意味着：

• 前端展示、CLI 输出、Agent 接口共享同一套类型定义
• 新增字段时不会出现在某个通道"有字段、另一个通道没有"的类型漂移问题
• 所有类型变更通过 bun run gen:types 统一重新生成

双引擎执行架构

设计哲学：知识逻辑（core）与 LLM/ACP 执行（agent）彻底分离。

• terrain-core 不依赖任何 LLM，独立完成扫描、打包、检索、新鲜度评分
• terrain-agent 负责编排问答、SDD、上下文生成等需要 LLM 的工作流
• 轻量任务（文档生成、需求分析）走原生 LLM（OpenAI/Ollama），重度工具调用走 ACP 子进程
• 当 LLM 不可用时，fallback_search_reply 确保 Agent 仍能基于知识库给出回答

信任模型

当不同来源的信息冲突时，Terrain 定义了明确的优先级：

repomix 源码 > CodeGraph > context.md > human 文档

当知识新鲜度评分低于 50 时，Agent 会自动降低宏观上下文的权重——绝不基于过时信息给出建议。

---

快速开始

# 安装并部署 Agent 工具链
terrain env apply

# 验证环境状态
terrain env status

# 让 Agent 查询知识
terrain ask query "项目的模块划分是怎样的？" --project my-repo --stream

---

适合谁？

• 使用多种 AI 编码助手的团队 — 告别每个工具单独配置的噩梦
• 希望 AI 助手之间有"共同知识"的技术负责人 — 统一的知识契约消除矛盾
• ACP 集成者 — 将 terrain tools 接入任何兼容 Agent-client-protocol 的工具
• 想要标准化 Agent 工作流的团队 — 通过 Skills 和 AGENTS.md 统一行为

“一份代码库，一套契约，所有 Agent 读取同一份知识。”