如果你平时也在折腾开源编程智能体大概率遇到过这种尴尬工具能读代码、能改代码听英文指令的时候非常利索但中文需求稍微复杂一点它就开始“一本正经地跑偏”。我给手头这套开源编程智能体补了一层“中文数据核心”前后做了一个多月才把这类问题压到可以日常使用的程度。今天拿这个项目当例子把完整的设计思路、数据构建方式、接入工作流的几种做法以及踩过的坑都摊开聊一聊。内容主要面向两类人一是已经重度依赖编程智能体的人二是打算自己给 Agent 加数据能力的开发者。1. 为什么一个开源编程智能体需要补“中文数据核心”1.1 智能体缺的不是推理能力而是语境先说清楚一个容易被忽略的事实编程智能体的底层模型确实很聪明它能读你仓库里的代码能理解抽象语法树能按 diff 提 MR但它对“中文语境下的技术表达”理解得并不够。这不是翻译问题而是训练语料里的中文工程类内容占比太低。我举个特别典型的场景。你在一个订单系统里发现一个问题“用户点击加载更多之后出现了重复数据可能是分页导致的。”英文世界里处理分页习惯直接谈 page 和 size但中文电商场景里“加载更多”往往是游标分页、时间戳分页、或者类似 loadmore 的混合状态。智能体可能第一反应是去前端加防抖或者把 page 减一而不是去查服务端游标推进是否正确。原因很简单在它见过的大量英文语料里分页就是简单的页码。类似的差异还有太多了“登录态过期”要对应到刷新 token 逻辑“防止超卖”要想到库存扣减加锁“做个审批流”要匹配到工作流引擎。这些词在中文工程社区里都有默认的“打开方式”但在模型的英文高频语料里没被充分建立关联。我还观察到注释和命名层面的割裂。国内很多团队仓库是中文注释加英文命名智能体生成代码时容易把注释写成英文跟原有代码风格完全不搭。更难受的是它会把一些本来应该用简短中文说清楚的业务规则写成一大段英文说明看起来“很专业”实际上 Team 里没人想 review 这种内容。1.2 我为什么没有直接微调模型在做这套东西之前我认真想过要不要微调。最后放弃的原因很现实第一开源编程智能体现在普遍是“模型 工具调用 上下文工程”三层结构。其中模型权重只是影响因素之一你直接微调一个模型未必能让它的工具调用更准。真正影响“中文任务是否正确”的往往是它在行动前有没有拿到正确的背景说明和检索资料。第二微调代码模型的成本相当高。不是一次性训练成本的问题而是维护成本。工程场景里的语料变更很快今天你给团队内部某个 SDK 出了新版本旧数据又过时了需要反复标注和重新训练。这个节奏大多数小团队都扛不住。第三风险不可控。投喂代码类语料很容易引入格式偏好上的“偏科”。今天用户让你把所有注释改成中文明天另一个项目又全是英文注释你如果把这些都拿去微调模型会不知道怎么平衡。所以我最终选择了数据层的方案不动推理模型只动智能体能看见、能检索、能遵守的“数据包”。模型本身就那么聪明真正缺的是中文工程语境的上下文和行事规则那我把这部分数据补齐比改脑子更稳妥。1.3 “中文数据核心”到底是什么我给它下的定义是围绕一个小型工程场景整理成的一组可维护的中文技术文档、术语映射、代码规范样例以及配套的检索机制。它通过配置注入和按需检索两种方式参与对话不需要修改模型权重也不绑定某一家商业产品的格式。你可以把智能体想象成刚到一个团队实习的高材生。推理能力再强也不了解你们团队的约定、业务黑话和历史包袱。你这时候不该去给“实习生”做脑部手术而是应该给他一本入职手册再给他一个能查资料的内部 Wiki。我做的“中文数据核心”就是这两样东西。所以整个项目拆开看只有两件事把数据整理好再教会智能体怎么用这些数据。前者是知识工程问题后者是 Agent 工作流配置问题。2. “中文数据核心”的数据从哪里来怎么构建2.1 先盘点中文环境下到底缺哪些类型的内容我一开始犯过贪多的毛病想把所有中文技术内容都塞进去后来发现完全没必要。智能体在写代码时真正需要的并不是“中文大百科”而是那些和它当前工作内容强相关的领域材料。我在实际项目中把数据分成四层来盘点层级资料类型具体内容举例主要解决什么问题规则层编码规约、协作规范注释是否用中文、命名规范、提交信息语言让生成结果匹配团队风格术语层领域词和代码映射“用户 ID”对应 user_id“登录态”对应 session避免英文思维理解错中文业务生态层常用技术栈的避坑记录某个中间件的配置、某类框架在业务中的常规用法减少 API 误用样本层中文项目结构和方法片段公开库的中文 README、Wiki、文档片段给智能体做“参考案例”真正要重点做的不是语料层而是规则层和术语层。我原本以为最难的是让智能体“知道更多”后来发现最难的是让它“在动手前就知道自己应该按什么标准动手”。如果你不给它一个明确的行事标准它会把抓到的技术资料全都平均用力地往里塞结果反而是干扰。2.2 采集与清洗的三个核心动作数据来源我没有搞得太玄主要用了三类团队内部沉淀的中文文档、目标技术栈的中文资料、公司公开仓库里已有的中文注释和 Readme 片段。但有一说一分布式采集回来的原始语料直接喂给智能体是灾难。我从第一批测试里就体会到了不加清洗的数据不如不给数据。清洗工作核心有三步每一步都有我踩过的坑第一步是去噪。很多中文技术页面的正文里混着导航链接、弹窗文案、广告区块和代码高亮类的 HTML 残留。我写了一个比较粗的正则规则先做一轮正文抽取再去掉所有代码块之外的噪点标签。这个阶段不要追求 100% 干净目标是让文本的“信噪比”足够高后续做关键词检索时不会被“点击领取资料”这种句子干扰。第二步是去重。中文技术博客互相抄的情况比想象中严重如果只做精确哈希去重会留下大量“看起来不同、内容几乎一样”的页面。可以按段落做 minhash 或 simhash 近似去重以我的经验建议把相似阈值调到 0.6 左右宁可用得保守一些也别把同一批知识重复入库。代码示意如下from simhash import Simhash docs [...] filtered [] for text in docs: h Simhash(text) if all(h.distance(Simhash(old)) 10 for old in filtered): filtered.append(text)需要注意这个阈值要按自己的语料反复试我一开始直接套用一个开源项目里的经验值结果把两篇认真讨论不同侧重点的文章误判为重复导致知识盲区。后来改成“先按标题聚类再算正文相似度”效果稳定很多。第三步是过滤敏感信息和隐私痕迹。日志片段、密钥、内部域名这些内容一旦进入数据包再被写入智能体的对话上下文风险是成倍放大的。我在清洗链路里加入了一组自定义正则和一串禁止词表宁可多滤掉一些看似无害的样本也不要放有可能引发问题的半条记录。2.3 把语料组织成“智能体友好”的格式数据清洗完之后最容易被忽略的是“格式化”。智能体不是搜索引擎用户它没有耐心看一个几十万字的文档库你需要把所有内容组织成它能快速消费的片段。每个文档我都加了 metadata 头部类似这样--- title: 分页查询中的重复数据排查指南 scope: 订单服务 tags: [分页, 游标, loadmore, 重复数据] verified_date: 2024-11-20 ---后来我还在每个文档前面加了一个 3 行以内的摘要块。为什么因为开源编程智能体的工具有时会先返回文档路径模型再决定要不要读全文。有了摘要它可以在不打开完整文件的情况下做初步判断这能省下大量 token 和决策时间。还有一个细节文件名里的数字前缀。比如zh-core/ 00-INDEX.json 10-rules/zh-coding-rules.md 20-terms/domain-word-map.md 30-stack/redis-cn-deploy-pitfalls.md 40-samples/order-flow-zh.md 99-archive/前面的数字不是执行顺序而是让文件系统排序稳定避免同一类文件在 glob 模式下打乱顺序影响索引里输出的结果优先级。这个习惯帮我少踩了很多“明明配了规则但智能体随机抽了个次要文件”的坑。3. 怎么把这套“中文数据核心”接进智能体工作流3.1 不写代码的接入方案行为规范文件如果你的开源编程智能体只是拿来写单个仓库的代码最简单的方式是把它做成一堆行为规范文件。现在很多终端类代码智能体都约定读取AGENTS.md之类的指令文件你可以把这些配置文件放到项目根目录或者用户全局目录下。我当时在项目里放了一个精简版的规则文件内容大概是这样的# 项目通用中文协作约定 - 代码注释默认使用中文命名继续沿用英文 CamelCase。 - 接口字段命名一律 snake_case注释中写清业务含义。 - 日期时间字段统一为带时区的 ISO 8601 格式。 - 金额和数量计算禁止直接使用浮点类型。 - 接触“user_id”等查询字段时默认确认是否存在索引再讨论改写。注意规范文件不能写太长。模型每次接管任务都可能把这份文件全量塞进上下文你写成一本书本身就是一种噪声。我的经验是核心规则保持在 20 到 40 条之间超过 40 条后模型遵守率会明显下降因为注意力被分散了。这个方案最大的特点是“快”。你甚至不需要先采集大量语料只用半天时间把团队真正在乎的规则整理出来注入之后效果立刻可见。它适合作为整套数据核心的第一版 MVP。3.2 让智能体按需自己查资料轻量检索层规则文件解决的是“行为按什么标准”但解决不了“知识不够用”。比如团队内部有 50 篇关于订单服务的文档你不可能全塞进规则文件里这时候就需要给智能体提供一个检索工具。我不建议此时就上完整套 RAG 架构。开源编程智能体本身有很强的文件阅读能力和上下文能力你只需要给它一个足够轻量的“查文档入口”。我实际做的是三件事把切好的文档放进一个叫zh-core的目录生成一份 JSON 索引然后注册一个自定义 shell 工具告诉智能体遇到中文业务规则时先查索引。索引文件的结构大概是这样[ { path: zh-core/30-stack/redis-cn-deploy-pitfalls.md, title: Redis 在中文项目部署侧的一些注意点, tags: [redis, 部署, 缓存, 缓存穿透] }, { path: zh-core/40-samples/order-flow-zh.md, title: 订单流程的领域术语与常见业务状态, tags: [订单, 状态机, 支付, 退款] } ]再用一个简单的 Python 脚本让智能体能够调用import json import sys index json.load(open(zh-core/index.json)) keywords set(sys.argv[1:]) for item in index: tags set(item[tags]) if keywords tags: print(item[path], -, item[title])这个脚本其实朴素到不太像工程但它在实际使用中非常管用。因为开源智能体本身具备遍历文件系统的能力你不需要给它一个三百页的向量库你只需要让它多一个判断“遇到中文业务概念时先去看这些文档是否匹配”。它找到文档路径后自己会继续读内容比我在中间环节强行加一套向量检索还要自然。3.3 多工程统一维护把数据核心独立成 Git 仓库当我尝试把这套中文数据核心用到第二、第三个仓库时马上就遇到了重复维护的问题。单独复制文件是最蠢的做法改一个术语要同步三个仓库迟早逼疯。后来我把zh-core从应用仓库里剥离出来做成了一个独立的 Git 仓库并让它作为子模块挂到各个工程里。git submodule add https://your-git-host/zh-core.git zh-core这个方案的好处是显而易见的我在中心仓库里更新了一份文档所有工程拉到最新子模块后都能获得新知识。代价是需要对团队成员做一次简单的培训让他们知道zh-core不是业务代码不能随手往里加临时内容。如果团队里有人不太习惯 Git 子模块也可以退一步用 Git subtree管理方式略有不同但核心思想一致——数据核心要独立于业务代码存在并保持单向依赖。3.4 控制数据注入量别把上下文当成垃圾桶我观察到一个很普遍的现象一旦给智能体配置了检索能力你就容易产生“多塞一点才安全”的错觉结果上下文瞬间爆炸模型开始“抓不住重点”。我的经验是设置一套分级注入策略最高优先级的情境信息写进规则层文件每次任务开始必定加载中等优先级的术语和领域背景只在实际任务触及相关关键词时触发检索低优先级的长文档样例只允许智能体读取片段而不是全部塞入。我甚至会在提示词里明确一句“优先用摘要判断是否需要继续读取内容”让模型先浏览再决定而不是一股脑把整个文档读完。这套策略让我在 32k 上下文的编码环境里把一个中等规模任务触发数据核心后的额外 token 开销控制在 5% 以内。如果不控制一次任务全量载入三十份文档直接就会把上下文烧掉。4. 接入“中文数据核心”后实测效果有什么变化4.1 同样几个中文需求理解准确度明显更稳我不太想用“准确率提升百分之多少”这种无法验证的话说几个真实任务中的观察更直观。我拿“点击加载更多出现重复数据请排查”给增强前的智能体做任务它第一反应是“这条数据列表可能存在重复 key建议前端做去重”。增强之后它先分析了请求参数和分页游标状态给出的结论是“当前游标基于时间排序但数据写入时间相同导致翻页出现重复建议增加备排序字段”。后者的思路明显更贴近真实工程原因。还有一个例子是中文注释风格。增强前即便我在规则文件里写了“使用中文注释”它还是偶尔给出语义空泛的英文注释比如// check if data exists。增强后由于我加入了一批真实中文项目中的注释片段作为样例它开始能输出类似“判断当前订单是否已回写库存避免重复扣减”这种直接表达业务目的的中文注释。我也试过让它生成 Readme。增强前生成的 Readme 是标准英文项目模板的翻译腔增强后至少能保留原项目里的“工单”“审批流”“对账”这些业务词不会擅自改成英文概念。这在企业内部工具项目里感知特别明显。4.2 负面影响也存在需要观察的副作用但我也要提醒一句加了数据核心并不总是变好。由于注入的规则来自“我们团队当前的项目风格”它会把风格强加到一些不该强加的场景上。比如我让它生成一个开源库的示例代码它仍然按我们内部规范写“注释都用中文且包含业务上下文”结果和开源库本身的英文风格冲突了。这个副作用可以通过在规则层上标注适用范围来解决。我给规则文件加了 scope 标志比如某些规则只作用于src/目录下的业务代码不作用于examples/目录。开源智能体本身具备路径判断能力但前提是你得在配置中明确告诉它“什么时候该用什么时候不该用”。4.3 用一套中文需求回归清单做持续评测数据核心这东西很容易做着做着就“自我感觉良好”因为聊天记录里的某几次成功被你放大记忆了。为了防止这种错觉我整理了一份由 20 个中文自然语言任务组成的回归清单每次改动完数据包都跑一遍。这 20 个任务覆盖了注释生成、术语理解、问题排查、函数编写、接口文档生成。我每次跑完看三类结果是否在正确的文件上做了修改、逻辑是否符合中文业务常识、是否产生了与目标仓库风格完全冲突的输出。虽然不能替代完整测试但它能快速暴露“这次数据调整把旧能力搞坏了”的问题。这套回归清单最有价值的地方不在清单本身而在于它逼着我持续给“中文数据核心”建立基线。数据工程的唯一正确姿势就是不断迭代迭代的前提是有可靠的反馈回路。4.4 上下文和速度的影响我还测过数据核心对响应速度的拖累。规则文件注入本身几乎不增加耗时真正有影响的是检索环节。每触发一次检索命令大概会增加 1 到 3 秒的响应时间如果文档较大且模型决定读全文再加上几秒。这个速度对交互式使用来说可以接受但在批量自动执行任务时确实会拖慢整体节奏。我的建议是单次任务限制检索触发次数最多给三到五次查询机会给多了反而会让模型在多份资料里来回横跳迟迟不开始改代码。5. 过程中的常见问题与排查实录5.1 智能体就是不按索引去查文档怎么办这是我最开始遇到的第一个问题。索引文件配置好了但智能体在遇到中文需求时还是凭自己的“感觉”直接回答完全不看索引。排查下来才知道它并不是拒绝使用工具而是“根本没想到要使用”。解决办法是在规则文件里明确写一条“当任务涉及业务状态、领域术语、项目历史约定时先搜索 zh-core 索引”。有了这个显式触发条件模型的调用率立刻提高。不要指望模型从你的良好愿望里学会推断配置提示词时显式比含蓄重要一百倍。5.2 数据陈旧带来的误导比没有数据更糟数据包过时的问题很隐蔽。比如旧文档写“用户登录态的校验在 Gateway 层完成”实际上系统已经改成“服务内部通过 signature 校验”。智能体检索到旧文档后可能对排查路径产生严重的错误引导。我给文档增加了verified_date和superseded_by字段并设置了一个定期任务把超过 6 个月未更新的文档自动移入99-archive目录。索引脚本会默认跳过归档目录。这步操作成本很低但能把“过时知识污染”的概率控制在一个可接受的范围。5.3 中文关键词检索命中率偏低用英文关键词去搜中文文档经常搜不到这很正常但用中文关键词搜也容易因为分词问题导致命中不准。“登录态过期”和“登录超时”本质是同一种问题但用简单的字符串匹配就查不到彼此的文档。我后来在 metadata 里维护了一个同义词字段。不是那种大而全的词库而是围绕我们团队项目出现的几百个业务词。建立这个同义词库本身不需要技术含量只需要你在日常维护文档时顺手加一行 tags。一个月后你会收获一个非常精准的领域小词典。5.4 上下文膨胀之后模型开始变“笨”我在 3.4 里提过控制数据注入量这里再补一个具体坑。有一段时间我在规则文件里放了特别多“最佳实践”从命名规范到数据库设计原则都有结果模型在处理简单 bug 时反而束手束脚因为它的注意力不断被各种“规则”拉走。编程智能体在使用规范类数据时有一个特性给它 20 条规则它执行很好给它 200 条规则它就开始随机选择遵守。所以我把“硬规则”和“参考资料”分开。硬规则只保留少量真正有强制性的约定参考资料则全部放进索引里按需读取不再混入全量上下文。5.5 安全边界私有数据不能乱喂最后这个话题必须单独讲。如果你用的是云端托管的智能体服务你输入到这个系统里的聊天内容和代码片段都会经过外部接口。内部代码、客户信息这类敏感内容在测试阶段绝不能直接塞进去。即便你把模型部署在本地也需要留意检索工具会不会把不该读的文件路径暴露出来。我的处理方式是将数据核心划分为公共区和私有区。公共区可以跟随子模块发布私有区只在本地环境使用并且加入.gitignore。规则文件里还会写一条“不要在对话中粘贴内部密钥或客户敏感数据”既是提醒模型也是提醒每一个使用它的人。6. 后续扩展与我的维护建议6.1 把数据核心沉淀为一个可发布的“数据包”做到这一步我越来越觉得它不像普通代码工程而更像一个“数据产品”。每个文档的好坏取决于它能不能真实地回答一类高频问题。好的数据包应该有版本号有变更日志有和代码仓库一样的发版节奏。可以按季度发一个版本每版记录新收录的领域词条、删除的过时内容、以及对智能体行为的影响变化。后续如果开源其他人不需要看懂你的全部内部业务也能直接复用公共规则层和通用术语层大大降低重复造轮子的成本。6.2 兼容更多开源智能体配置目前不同开源编程智能体的配置文件格式尚未完全统一有读AGENTS.md的有读自定义settings.yaml的也有通过插件系统加载工具的。如果想让一个数据包服务多种智能体需要在不同的入口里重复声明引用关系。我建议不要为每一种格式单独维护一份完整副本而是把核心内容控制在纯 Markdown 目录里再用一层很薄的适配文件去对接不同智能体。像AGENTS.md或全局规范文件里只写“请参考 zh-core/00-INDEX.json”剩下的由索引和检索工具接管。6.3 从“给智能体做数据”延伸到“团队的工程知识管理”做着做着会发现一个更大的价值所谓中文数据核心真正起作用的机制是把组织里原本只存在于文档碎片和口头约定中的知识转成了机器可检索的高质量语料。所以后续维护不应该只靠我一个人。最好能让团队里的每个人在遇到典型中文需求时顺手把问题和解法沉淀成一个新词条。我目前采用的方式类似“提交即入库”在代码审查时如果发现某个问题的根因很典型就提炼出一篇短文档放进数据包。一个季度之后这套文档几乎会变成团队的中文工程手册智能体的表现也会随着数据包增长而持续改善。6.4 持续检验要相信数据但更要相信反馈和所有数据类系统一样中文数据核心没有“做完”的那一天。哪怕上线后效果很好也要持续关注新增任务类型是不是原有文档覆盖不到的。我给自己定了一条规矩每次遇到智能体效果变差先不怀疑模型而是先检查最近改过哪些数据。超过 80% 的“模型变蠢”其实都是数据或提示词侧引入的回归问题跟模型本身没有关系。最后分享一点我在实操中的体会如果只看技术手段这套东西做出来并不难难点在心态。你会不断面临“加数据还是减数据”“管太宽还是不管”的抉择。我在过程中最大的感受是中文数据核心表面上是技术工程本质上是产品设计你得先弄清楚团队每天都在让智能体重复踩哪些坑然后才能决定数据包里装什么。与其一口气追求大而全不如先挑三五个高频问题做出明显改善。我现在每次给智能体布置中文任务时已经敢把一些描述得很绕的业务需求直接交给它因为它至少知道该往哪个方向查、该用什么术语表达。这个变化比任何单次成功案例都更能说明数据工作真正产生了复利。