⭐Terrain 开源地址：https://github.com/sopaco/terrain（MIT License）·给 AI Agent 铺好「地图 + 道路 + 路标」的高性能工程环境开源方案，欢迎 Star / Issue
如果你同时用 Claude Code、Codex、Cursor 写代码，你会发现一个荒诞的事实：
它们每天都在重复做同一件最笨的事——从零认识你的仓库。
- 新任务一开，Agent 先花几分钟 grep 目录结构，猜你的架构长什么样；
- 你把项目背景、业务术语、模块职责写进提示词，下次换个任务还得再写一遍；
- 同一套工具链（grep 优化、符号检索、输出压缩），每台机器都要重新配；
- 换了 Agent、换了模型，它对你项目的「理解」又要重新来过。
打个比方：你雇佣了几个顶尖工程师，但他们每次开工前都要求你重新介绍一遍公司——而且他们之间还不共享这份介绍。
这就是 AI 工程化时代最典型的浪费。而它的解药，是一份「知识契约」。
什么是「知识契约」？
知识契约，是让任何 Agent 都能一致地理解你项目的标准化约定。它回答三个问题：
- 这个项目是什么—— 架构怎么分层、模块怎么划分、边界在哪里；
- 去哪里找知识—— 文档在哪、源码索引在哪、业务术语怎么解释；
- 用什么工具干活—— 该用哪些 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 toolsCLI | terrain tools是纯命令行 + JSON stdout，DSH 工具插件可直接调用 |
| 会话 / 调度 | ACP 知识层 | 两者按标准协议互通，不用各自重复实现 |
所以 DSH 和 Terrain 是天然的「上下层」组合：
- DSH 负责「手脚」—— 工具、会话、多 Agent 调度；
- Terrain 负责「地图」—— 让 DSH 一进来就知道你的仓库长什么样、该往哪走。
一句话：把 Terrain 的 Skill + CLI 丢给 DSH，它立刻获得全套项目知识访问能力，几乎零改造。这正是「CLI + SKILL 天然可被各类 Agent 继承」的最好例证。
一键部署：别再逐仓库「配环境」了
「知识契约」最大的敌人是手工维护。Terrain 把部署做成了单条命令：
terrainenvapply这条命令会按正确的依赖顺序，自动把工具链装好：
它会自动完成三件事：
- 部署工具链—— 把 CodeGraph（符号调用/影响查询）、RTK（shell 输出 token 优化）、terrain CLI 装到
~/.terrain/bin/； - 安装预设 Skills—— 给 Agent 加载标准操作手册，教会它们「先读知识、再查关系、最后读源码」；
- 写入
AGENTS.md—— 在仓库里埋下导航路牌，让每个进入仓库的 Agent 都先走知识层。
从此，新人入职、新机器、新 Agent，都只需要一行命令，就能拥有和你完全一致的「项目认知」。
对团队意味着什么？
把「知识契约」落地，几个长期痛点会明显缓解：
| 场景 | 没有契约 | 有了契约 |
|---|---|---|
| 多 Agent 混用 | 每个 Agent 各读各的，理解参差 | 所有 Agent 读同一份契约，口径一致 |
| 提示词维护 | 项目背景散落在无数提示词里 | 背景沉淀进仓库，提示词只留任务本身 |
| 换人换机换 Agent | 重新教一遍「我们的项目」 | terrain env apply一键恢复认知 |
| 团队治理 | Agent 行为不可预期、不可审计 | 约定即路标，行为可预期、可审计 |
它把「教会 AI 理解项目」这件事，从「个人经验」变成了「组织资产」。
上手三步
# 1. 注册仓库，生成知识资产terrain init# 2. 一键部署 Agent 工具链 + 契约terrainenvapply# 3. 让 Agent 通过 ACP 读知识terrain tools search"用户认证模块如何设计"你的 Claude Code、Codex、Cursor，甚至刚接进来的 DeepSeek Harness（DSH），从此都不再「重新认识仓库」——它们一进来，就知道该往哪走。
🚀开源地址：github.com/sopaco/terrain （MIT License）
⭐ 想告别「每个 Agent 都从零认识你的仓库」？来 Star 一下，把你的知识变成组织资产。
下一篇：除了知识，Terrain 还把「需求 → 设计 → 代码 → 评审」做成了标准流程（SDD）——AI 协作开发从此可审查、可复现。
