这期的标题写的是“写了但没写进去批了但没批完”如果你也在做企业级AI项目大概率能瞬间get到这两个状态有多折磨人。我们团队这期迭代的主题是本地部署的知识库助手和底层的Java AI Agent应用平台按理说方向明确、需求清楚但真到复盘的时候一看方案文档出来一摞代码合进主干的没几个审批流上亮着“已通过”的绿灯实际上还卡在后面的节点没人管。这篇迭代日记就是想把这期踩过的坑、调过的参、拆解过的流程都摊开来聊聊适合正在做企业级AI交付、或者被需求变更和审批链路折磨的研发、产品和测试同学参考。1. 标题拆解两个“断层”卡住了整个迭代我先解释一下什么叫“写了但没写进去”。这不是指代码写错了而是说在整个迭代周期里团队产出了大量文档、方案、设计稿但真正落到主干分支、进入发布列表的东西少得可怜。产品写了十几页PRD研发做了技术预研报告评审会开了一轮又一轮最后版本发布时一看功能列表还是上上期那几项。“批了但没批完”就更常见了。企业级项目绕不开审批尤其是AI项目牵扯到数据权限、模型调用、安全合规审批链路比普通业务系统长得多。但让人崩溃的是我在OA里看到状态变成“已通过”以为万事大吉结果研发联调到一半才发现那只是第一个节点的审批人点头了后面的环节还挂着。这种“半程通过”比“未通过”更坑因为它会让人误以为流程已经走完。这两个现象背后其实是同一个问题企业级AI项目的迭代过程远比“写代码-提交-上线”要复杂。需求的不确定性、审批节点的不可控性、跨团队协作的信息差任何一个环节断掉都会让前面投入的精力变成沉默成本。这一期我们就在对付这两个“断层”过程很折腾但收获也确实不小。1.1 需求侧的“假性推进”方案出了一版又一版代码一行没动先说需求层面。上上期我们启动了“私有化知识库问答助手”这个项目产品团队花了两周写PRD方案评审改了三四轮技术预研报告也产出了不少看起来一切都在推进。但真正进入开发排期的只有“文档解析与索引”这一个模块其余内容全部停留在了“方案确认可用”的阶段。这其实是企业级AI项目的通病。用户抛出“我要一个能回答业务问题的机器人”这种需求听着简单翻译成技术需求就变成私有数据接入、权限隔离、多轮对话、流式输出、检索效果调优等一系列子任务。每个子任务单拎出来都能做一个迭代。但早期阶段没人愿意砍需求都怕漏掉关键场景结果就是方案越堆越多真正写进代码的越来越少。这期我们采取了一个比较强硬的做法评审时产品必须回答“这个需求在本期的验收标准是什么”回答不出来就不排期。没有验收标准的需求默认记为“待进一步评估”而不是“已确认”。这个动作看起来只是在文档上加了几行字但它逼着所有人把“我觉得可以做”和“我们这期要交付”划清界限直接砍掉了一大批弹性需求。1.2 代码侧的“隐身成果”分支开了但永远合不回主干就算研发真的写完了代码也不代表就能合进去。我们用的是GitLab的MR流程要求至少两个reviewer。AI项目里的代码天然比普通CRUD难审涉及模型调用逻辑、Prompt拼接、数据过滤规则reviewer要理解业务上下文才能给出有效意见。这期有个典型例子知识库助手的“文档权限过滤”功能研发同学代码写完了自测也过了但MR挂在那里一周没人合。第一个reviewer看了三天才回第二个reviewer提了8条评论改完又是一轮。等处理完版本分支已经重建了两次光解决冲突就花了大半天。比这更伤的是另一个案例。有同事花两周做了一个“对话日志审计”模块为了应对模型供应商接口升级还提前写了兼容层。结果需求优先级调整整个模块被移出本期迭代。代码没删但也没合进主干就这么躺在本地分支里成了一块“隐形成果”。这类代码最危险因为过两个迭代没人记得它存在过下次重新实现一遍的概率极高。2. 审批链路别让“半程通过”坑了下游环节企业级AI项目的审批场景我梳理了一下至少包括这么几类需求变更审批、文档或数据权限申请、模型接口上线审批、版本发布审批、GPU或向量数据库等资源申请。每一类都有独立的审批流和审批人节点还不一样。这期最让我头大的是一个数据权限申请。我在审批系统里看到状态是“已通过”就让研发开始联调。结果联调到一半测试同学说权限还没生效一查发现系统显示“已通过”的只是直属leader那一环后面还有数据治理组和安全合规两个节点没走。更巧的是这两个节点的审批人一个在休假一个被拉去处理紧急事件整个流程直接挂起研发只能停下来干等。2.1 “半程通过”为什么会浪费掉整个项目的节奏后来我认真想了一下“半程通过”最坑的不是等待本身而是它会诱导下游环节提前启动然后被硬生生打断。人等机器至少还有个预期人等人是最消耗耐心的。研发停下手头工作去等一个不知道什么时候能完成的审批回来还要重新加载上下文这个切换成本远不止表面看到的几个小时。我们复盘时发现问题根源在于审批系统的状态展示粒度太粗。“已通过”到底是指当前节点通过还是整个流程通过系统没说清楚。我们团队在协作工具里定了一个话术规范凡是跨部门协同事项禁止笼统说“批了”必须写明“已完成XX节点剩余XX节点”。同时在任务卡上增加“审批进度”字段区分未开始、审批中、已通过三类状态避免歧义。2.2 把审批从“串行确认”改成“分类分级”审批链路慢很多时候不是审批人不负责而是流程设计把“审核”变成了重复“确认”。安全合规组对每个权限申请都要看一遍申请理由但他们并不了解业务上下文最后只能看个大概等于走个形式。后来我们换了一种思路做“分类分级审批”低风险变更直接走单人审批甚至自动通过比如文档修正、不影响数据访问的代码提交中风险变更走两个节点比如涉及模型调用但数据不落地的功能高风险变更才走完整链路比如对外接口、数据导出、批量权限变更。分类上线后审批量少了大概四成而高风险环节的审批质量反而提升了因为审批人终于有时间真正看内容了。2.3 审批状态不透明的连锁反应审批状态不透明还会引发一个连锁反应下游工作“假启动”。我们有个知识库模块产品以为数据权限已经批好就开始给核心客户演示了结果演示前一天发现测试环境的权限配置还不对临时回退到演示账号。这种问题在对外演示的时候格外致命。所以这期我们特别强调所有涉及审批的资源申请必须在需求描述里写清楚预期时长。比如“数据权限审批预期3~5个工作日”不要默认半天能过。跨部门协作时宁可把预期说长一点让排期有缓冲也不要等到任务中断了再去催流程。3. 测试用例在复杂迭代里的复用、管理与维护这期除了研发侧的卡顿测试团队也反馈了一个很实际的问题。知识库助手和底层平台两个项目组并行开发都涉及文件解析、向量检索、权限过滤这些功能但各自的用例维护在不同的地方结果同一个功能被重复测试、重复写用例而且版本一升级就开始互相踩脚。3.1 用例的管理和复用其实是两件事我们原本以为只要有一个在线用例库就算管理了。后来发现如果用例没有清晰的目录结构和标签体系它就只是一个带着搜索框的Excel。跨项目组复用时团队A建的用例团队B根本找不到找到了也不敢用因为不知道它对应的产品版本是不是最新的。我们后来把用例库做成了三层结构。第一层按业务域分比如知识库、问答对话、权限中心、审计日志第二层按功能模块分比如文档解析、检索排序、权限过滤、流式输出第三层按测试类型分比如功能、接口、回归、兼容性。再用组合标签来定位比如“知识库-文档解析-回归”跨项目组搜索的成本一下子就降下来了。3.2 复用最大的坑用例版本和产品版本不同步复用之后遇到的第一个大坑是版本不同步。平台项目组说“我修了检索排序的逻辑”知识库项目组还在用旧的回归用例跑测试跑出一堆失败所有人开始排查最后发现是环境串了根本不是功能问题。我们后来定了一条硬规则用例和代码一样按迭代打标签。用例的主干永远对应当前产品主干发布分支对应发布分支任何跨项目组复用的用例改动必须走变更记录不能悄悄改。这听起来像常识但实际执行的时候很多测试同学觉得小题大做直到踩过一次跨组回归的雷之后大家才认真遵守。3.3 用L1/L2/L3三级标签解决跨组复用的难题跨项目组复用一个比较实用的方案是把用例分成三个级别L1是核心主流程用例L2是功能级用例L3是分支细节用例。跨项目组只强制复用L1L2按需引用L3建议各项目组自己维护。举个例子知识库助手和审计平台都需要验证“对话日志是否记录完整”这是L1级用例两个项目组共用一套脚本。但“日志导出格式是否符合要求”这类细节不同项目组的标准不一样就属于L3级各自维护就行。这样做的好处是核心用例有人统一维护业务细节又能保持灵活。我们统计过光靠复用L1用例回归测试时间就省了大概三成。4. 唯一写进去也批完的本地部署知识库助手这期迭代虽然各种卡顿但有一个模块是真真切切“写了、写进去了、也批完了”的就是企业级本地部署的知识库助手。这个模块也是我们Java AI Agent应用平台上跑得最稳的一个应用值得单独拿出来说说。4.1 为什么企业内部落地AI先从知识库助手开始很多项目一上来就想做“数字员工”或者“全流程智能助理”这种宏大的目标在企业内部往往最难落地。知识库助手之所以适合先做是因为它的边界足够清晰私有数据进来模型出去中间是检索和权限控制。对企业来说把内部文档变成可问答的知识资产比做一个大而全的智能体要靠谱得多。我们的部署方式是纯内网环境用Docker Compose编排整个系统分为四个部分向量数据库、文档解析服务、检索服务、Agent编排服务。数据不离开内网模型可以接本地部署的开源模型也可以走内部的模型网关灵活性比较高。这套架构的好处是每一层都能独立升级和排查问题不会因为一个模块出问题导致整套服务不可用。4.2 RAG链路里最值得反复调试的三个参数知识库助手的核心是RAG检索增强生成链路而这条链路里有三个参数我们调了很多次每一次调整对最终效果的影响都很直接。第一个是文本分块大小。我们默认设置是500字符加50字符重叠。中文场景下建议稍微调小一点400到600这个区间比较稳。块太大细节容易丢失检索时召回的内容粒度太粗块太小语义被切碎相关性判断会失真。第二个是检索TopK。一开始我们设了20个候选结果召回一堆无关片段反而拉低了回答准确率。后来改成默认5个候选加一个重排环节效果好很多。第三个是相关性阈值我们定在0.45到0.6之间做过滤低于阈值的片段直接不返回。别用0.3这种太低的值否则噪声会把答案带偏。4.3 知识库权限过滤落地时踩过的三个坑知识库助手最核心的不是“能回答”而是“谁能问什么”。我们的方案是在文档解析入库时把文档ID、所属部门、可见范围作为元数据写入向量库检索的时候把用户身份信息作为过滤条件一起传入。听起来不复杂但做起来是真麻烦。第一个坑是向量数据库的元数据过滤能力。我们最早用的版本不支持复杂的IN条件过滤导致部门相关的权限查询跑不出来后来升级了版本才解决。第二个坑是部门层级关系的同步。组织架构数据需要下发到本地数据量大了之后全量同步很慢后来改成按需增量拉取才把同步时间降下来。第三个坑是过滤顺序。我们最终确定为先按用户身份过滤元数据再做语义检索最后再做一次权限复核。这个顺序可以最大程度避免越权内容在检索阶段就被召回。4.4 知识库助手背后的Java Agent应用平台知识库助手只是我们Java AI Agent应用平台上的一个应用实例平台本身解决的是通用能力的复用Agent编排、工具调用、模型网关、会话管理、审核日志。每个新应用不需要从零搭一套基础设施。选Java技术栈做Agent平台最大的好处是和企业内部系统集成非常省事。用户体系、组织架构、权限中心、审批流系统都是现成的用Java生态直接对接就行。相比从零造轮子这套方案的最大优势就是稳尤其是在企业内网环境里兼容性和可维护性都经得起考验。5. 迭代复盘把“写了”和“批了”变成显式状态这期迭代结束后我们做的第一件事不是追责而是把流程调整了一遍争取让“写了但没写进去、批了但没批完”这两类问题在下一期尽可能少出现。5.1 需求评审增加“验收口径”这道门槛以后每次评审产品必须回答一个问题这个需求在本期的验收标准是什么没有具体验收标准的需求默认不进开发排期只记录为“待进一步评估”。这一条能有效过滤掉大量“觉得可以做”的模糊需求让团队把精力集中在真正能交付的事情上。5.2 MR增加“生命周期标签”每周五做一次仓库快照给每个MR打上标签包括待评审、评审中、待合并、已合并、已夭折。每周五下午快照一次仓库状态凡是“待合并”状态超过三天的MR系统自动提醒项目负责人。这个动作看着微不足道但帮我们捡回来了好几条被遗忘的分支很多“写了但没写进去”的代码就是这么被找回来的。5.3 审批流状态统一话术禁止简单说“批了”我们要求所有涉及审批的跨部门协作消息必须写明已完成哪个节点、还剩哪些节点。审批状态在任务工具里统一展示为未开始、审批中、已通过不再用模棱两可的词语。这不能直接加快审批速度但能避免大量因信息不对称造成的等待和返工。5.4 测试用例复用清单每月过一遍每个月抽半天时间让几个项目组的测试负责人一起过一遍L1用例清单哪些用例需要升级、哪些已经失效、哪些跨组复用了但没人维护。这半天时间花得很值至少能避免因为用例失管导致的跨组回归事故。这期迭代下来我最大的感触是企业级AI项目里最折磨人的往往不是模型效果不达标而是流程里的隐性浪费。“写了但没写进去”是需求和代码之间的断层“批了但没批完”是流程和结果之间的断层。代码和模型能力决定项目上限而流程管理决定的是下限——下限不稳上限再高也很难稳定产出。最后分享一个小习惯。我每周五下午会花半小时把“本周写了什么、批了什么、下周要动什么”三份清单过一遍。不是为了汇报而是为了及时发现哪些事情卡住了、哪些事情可能要被遗忘。很多看似不起眼的拖延和搁置都是这么被提前捞回来的。