⭐Terrain 开源地址https://github.com/sopaco/terrainMIT 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 对话通过 ACPTerrain 支持ACPAgent Client Protocol这是连接外部 Coding Agent 的标准协议。Claude Code、Codex、OpenCode、Cursor乃至最近大火的 DeepSeek HarnessDSH都可以通过terrain tools这条命令读取同一套分层知识仓库TerrainACP 协议写入仓库你的 Coding AgentsClaude CodeCodexOpenCodeCursorDeepSeek Harness (DSH)terrain tools(ACP 入口)三层知识宏观 · 中观 · 微观AGENTS.md · Skills · 工具链context.mdhuman/ 文档repomix 源码包接入之后Agent 的行为会发生质变从「盲 grep」变成「先看地图」。开工前先读context.md拿到宏观架构需要细节搜索human/文档和业务词汇表要看真实实现才按需从repomix源码包里精确切片。这一套下来Agent 对项目的理解速度、准确度、token 成本都会是另一个量级。 蹭个热点DeepSeek HarnessDSH也能无缝继承如果你最近关注 AI Coding一定注意到了 DeepSeek 开源、热度拉满的DeepSeek HarnessDSH——npx deepseek-ai/dsh web一行起跑模型、工具、Skill、会话、调度全部插件化「Everything is a plugin」。有意思的是DSH 最出圈的两个点恰好和 Terrain 的交付形态一模一样DSH 的机制Terrain 的对应物为什么能「无缝继承」Skill 插件SKILL.md预设 SkillsTerrain 的 Skills 就是标准 SKILL.md 形态放进 DSH 的 skills 目录即可加载工具插件terrain toolsCLIterrain tools是纯命令行 JSON stdoutDSH 工具插件可直接调用会话 / 调度ACP 知识层两者按标准协议互通不用各自重复实现所以 DSH 和 Terrain 是天然的「上下层」组合Terrain地图DeepSeek Harness手脚加载 Skill调用 CLI工具插件 · Skill 插件会话 · 调度preset Skills(标准 SKILL.md)terrain tools CLI(JSON stdout)三层知识资产DSH 负责「手脚」—— 工具、会话、多 Agent 调度Terrain 负责「地图」—— 让 DSH 一进来就知道你的仓库长什么样、该往哪走。一句话把 Terrain 的 Skill CLI 丢给 DSH它立刻获得全套项目知识访问能力几乎零改造。这正是「CLI SKILL 天然可被各类 Agent 继承」的最好例证。一键部署别再逐仓库「配环境」了「知识契约」最大的敌人是手工维护。Terrain 把部署做成了单条命令terrainenvapply这条命令会按正确的依赖顺序自动把工具链装好terrain-knowledge先读知识repomix再查源码索引codegraph后查符号关系rtk压缩 shell 输出它会自动完成三件事部署工具链—— 把 CodeGraph符号调用/影响查询、RTKshell 输出 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 HarnessDSH从此都不再「重新认识仓库」——它们一进来就知道该往哪走。开源地址github.com/sopaco/terrain MIT License⭐ 想告别「每个 Agent 都从零认识你的仓库」来 Star 一下把你的知识变成组织资产。下一篇除了知识Terrain 还把「需求 → 设计 → 代码 → 评审」做成了标准流程SDD——AI 协作开发从此可审查、可复现。
