⭐ Terrain 开源地址：https://github.com/sopaco/terrain（MIT License）·给 AI Agent 铺好「地图 + 道路 + 路标」的高性能工程环境开源方案，欢迎 Star / Issue

---

如果你同时用 Claude Code、Codex、Cursor 写代码，你会发现一个荒诞的事实：

它们每天都在重复做同一件最笨的事——从零认识你的仓库。

• 新任务一开，Agent 先花几分钟 grep 目录结构，猜你的架构长什么样；
• 你把项目背景、业务术语、模块职责写进提示词，下次换个任务还得再写一遍；
• 同一套工具链（grep 优化、符号检索、输出压缩），每台机器都要重新配；
• 换了 Agent、换了模型，它对你项目的「理解」又要重新来过。

打个比方：你雇佣了几个顶尖工程师，但他们每次开工前都要求你重新介绍一遍公司——而且他们之间还不共享这份介绍。

这就是 AI 工程化时代最典型的浪费。而它的解药，是一份 「知识契约」。

---

什么是「知识契约」？

知识契约，是让任何 Agent 都能一致地理解你项目的标准化约定。它回答三个问题：

1. 这个项目是什么 —— 架构怎么分层、模块怎么划分、边界在哪里；
2. 去哪里找知识 —— 文档在哪、源码索引在哪、业务术语怎么解释；
3. 用什么工具干活 —— 该用哪些 CLI、按什么顺序、遵循什么约定。

Terrain 把这套契约做成了可以在仓库里托管、随分支流转、一键部署的资产，而不是靠提示词「人肉传递」：

契约组件	作用	形态
知识资产	项目的地图	.terrain/ 中的双轨文档 + 上下文
AGENTS.md	导航路牌	引导 Agent 优先走知识层，再碰源码
预设 Skills	操作手册	标准工作流：先读知识 → 再查关系 → 后读源码
工具链	干活的手脚	CodeGraph（符号检索）、RTK（输出压缩）、terrain CLI

一份契约，写一次，所有 Agent 共用。
你不再需要向每个 Agent 重复解释你的项目——它们自己读契约。

---

如何让「外部 Agent」和 Terrain 对话？通过 ACP

Terrain 支持 ACP（Agent Client Protocol），这是连接外部 Coding Agent 的标准协议。Claude Code、Codex、OpenCode、Cursor，乃至最近大火的 DeepSeek Harness（DSH），都可以通过 terrain tools 这条命令，读取同一套分层知识：

接入之后，Agent 的行为会发生质变：从「盲 grep」变成「先看地图」。

• 开工前，先读 context.md 拿到宏观架构；
• 需要细节，搜索 human/ 文档和业务词汇表；
• 要看真实实现，才按需从 repomix 源码包里精确切片。

这一套下来，Agent 对项目的理解速度、准确度、token 成本，都会是另一个量级。

---

🔥 蹭个热点：DeepSeek Harness（DSH）也能无缝继承

如果你最近关注 AI Coding，一定注意到了 DeepSeek 开源、热度拉满的 DeepSeek Harness（DSH）——npx @deepseek-ai/dsh web 一行起跑，模型、工具、Skill、会话、调度全部插件化，「Everything is a plugin」。

有意思的是，DSH 最出圈的两个点，恰好和 Terrain 的交付形态一模一样：

DSH 的机制	Terrain 的对应物	为什么能「无缝继承」
Skill 插件（SKILL.md）	预设 Skills	Terrain 的 Skills 就是标准 SKILL.md 形态，放进 DSH 的 skills 目录即可加载
工具插件	terrain tools CLI	terrain tools 是纯命令行 + JSON stdout，DSH 工具插件可直接调用
会话 / 调度	ACP 知识层	两者按标准协议互通，不用各自重复实现

所以 DSH 和 Terrain 是天然的「上下层」组合：

• DSH 负责「手脚」 —— 工具、会话、多 Agent 调度；
• Terrain 负责「地图」 —— 让 DSH 一进来就知道你的仓库长什么样、该往哪走。

一句话：把 Terrain 的 Skill + CLI 丢给 DSH，它立刻获得全套项目知识访问能力，几乎零改造。 这正是「CLI + SKILL 天然可被各类 Agent 继承」的最好例证。

---

一键部署：别再逐仓库「配环境」了

「知识契约」最大的敌人是手工维护。Terrain 把部署做成了单条命令：

terrain env apply

这条命令会按正确的依赖顺序，自动把工具链装好：

它会自动完成三件事：

1. 部署工具链 —— 把 CodeGraph（符号调用/影响查询）、RTK（shell 输出 token 优化）、terrain CLI 装到 ~/.terrain/bin/；
2. 安装预设 Skills —— 给 Agent 加载标准操作手册，教会它们「先读知识、再查关系、最后读源码」；
3. 写入 AGENTS.md —— 在仓库里埋下导航路牌，让每个进入仓库的 Agent 都先走知识层。

从此，新人入职、新机器、新 Agent，都只需要一行命令，就能拥有和你完全一致的「项目认知」。

---

对团队意味着什么？

把「知识契约」落地，几个长期痛点会明显缓解：

场景	没有契约	有了契约
多 Agent 混用	每个 Agent 各读各的，理解参差	所有 Agent 读同一份契约，口径一致
提示词维护	项目背景散落在无数提示词里	背景沉淀进仓库，提示词只留任务本身
换人换机换 Agent	重新教一遍「我们的项目」	terrain env apply 一键恢复认知
团队治理	Agent 行为不可预期、不可审计	约定即路标，行为可预期、可审计

它把「教会 AI 理解项目」这件事，从「个人经验」变成了「组织资产」。

---

上手三步

# 1. 注册仓库，生成知识资产
terrain init

# 2. 一键部署 Agent 工具链 + 契约
terrain env apply

# 3. 让 Agent 通过 ACP 读知识
terrain tools search "用户认证模块如何设计"

你的 Claude Code、Codex、Cursor，甚至刚接进来的 DeepSeek Harness（DSH），从此都不再「重新认识仓库」——它们一进来，就知道该往哪走。

🚀 开源地址：github.com/sopaco/terrain （MIT License）
⭐ 想告别「每个 Agent 都从零认识你的仓库」？来 Star 一下，把你的知识变成组织资产。

---

下一篇：除了知识，Terrain 还把「需求 → 设计 → 代码 → 评审」做成了标准流程（SDD）——AI 协作开发从此可审查、可复现。