本项目构建了一个网关路由 AI 安全审计系统，采用"通用 Agent + 业务 Skill"分层设计，增量日检/存量月检。落地 Open 网关路由越权漏洞检测流程，通过 AI 批量筛查 + 人工深度验证的人机协同模式，为大规模 API 安全审计提供了可复用的智能化解决方案。充分发挥通用 Agent 能力，业务逻辑在 Skill 中快速迭代。

一、背景与技术方案

安全审计的核心挑战

随着平台 API 规模持续扩张，安全审计面临新的规模化挑战。

主要挑战：

• 覆盖面不足：抽样审计约覆盖 ~20%
• 时效性压力：新接口需要更快的安全评估
• 规则一致性：标准化检测规则难以沉淀

技术选型与建设契机

当前，以大型语言模型为基座的 AI Agent 在代码语义理解、逻辑推理与自动化执行等维度的能力已超预期成熟，工程落地准确率与稳定性得到大规模验证。这一技术跃迁使全量自动化安全审计从概念验证走向可靠实践。

传统人工抽样模式在数万条 API、数百个微服务的规模下已难以为继，而基于 AI Agent 的方案可实现 100% 路由覆盖与分钟级检测响应。本文将围绕这一契机，阐述如何构建贯穿全链路调用链的智能审计体系，解决覆盖面、时效性与规则一致性三大核心挑战。

二、技术架构

整体架构设计

架构说明：常规代码负责任务调度与结果存储，所有 AI 分析工作由超级 Agent 完成。具体项目分析告警时采用 AI 批量筛查 + 人工深度验证的人机协同模式。

具体项目分析告警时采用 AI 批量筛查 + 人工深度验证的人际协同模式：

场景化应用：

架构设计原则：通用 Agent + 业务 Skill 分离

设计优势：

• 通用 Agent 能力最大化：充分利用 Claude Code/OpenCode 的代码理解、推理分析、上下文管理、会话恢复等标准能力，不重复造轮子
• 业务逻辑快速迭代：检测规则、分析流程、报告格式等业务逻辑全部沉淀在 Skill 中，可随时调整优化
• 任务可追溯可复现：通过 --resume 恢复会话现场，任何分析过程都可回溯、可验证

Skill 层核心组成

gateway-route-vuln-analyzer/
├── SKILL.md # 核心：漏洞分析主流程 
│ ├── 检测决策树（Step 1-4）
│ ├── 危害评估规则
│ └── 报告输出模板 
├── references/ 
│ ├── unauthorized_patterns.md # 越权漏洞模式库
│ ├── logic_flaws.md # 逻辑漏洞检测指南
│ ├── data_classification.md # 数据敏感性分级
│ └── report_template.md # 标准化报告模板
└── scripts/ 
└── mcpcli-gateway # CLI入口（Token优化）

MCP 工具集设计

三、漏洞检测方法论（以越权为例）

越权漏洞精细化分类

基于公开漏洞案例库分析，细分越权漏洞类型：

检测决策流程

检测分四步，前两步设有短路退出以降低成本：

路由配置检查：检查 auth_config.public 和 required_scopes，配置无异常则跳过后续审计。登录态识别：遍历调用链查找认证节点，标准认证路由直接信任，跳过代码审计 代码审计（三维检测）。：检查权限注解（@PreAuthorize）、用户 ID 来源（登录态 vs 请求参数）、所有权校验（DB 过滤 vs 代码显式校验）。精细化危害评估：区分越权读取（数据敏感性）和越权操作（利益流向），输出风险等级与修复建议。

精细化危害评估机制

越权读取 - 数据敏感性评估

依据《数据安全法》确立的数据分类分级保护制度及《网络安全法》关于网络运营者数据安全管理义务的相关要求，通过 AI Agent 对源代码文本分析（基于变量名、字段类型、接口定义等代码特征进行技术推断），对路由功能返回涉及的数据资产进行分级评估。

越权操作 - 利益流向评估

四、技术优化：Token 成本降低 95%+

问题诊断

通过对多个会话日志的深入分析，识别出 Token 消耗的关键问题：

Token 消耗热点：

优化策略与效果

MCP → CLI 转换（mcp2cli）⭐核心优化

原理：将 MCP 工具暴露为 CLI 命令，避免每次会话加载 MCP 上下文。

# 优化前：MCP调用（需加载完整MCP上下文）
Claude → MCP Server → 工具执行
# 优化后：CLI调用（直接执行，无额外上下文）
Claude → Bash → mcp2cli → 工具执行

效果：节省 61% Token 消耗。

工具返回值优化 ⭐关键优化

问题：无参数调用返回完整文件（最大 1.47MB ≈ 500K tokens）。解决方案：为 gitlab_file 添加精准参数，实现按需提取。

效果：v2 vs v1 再节省 88%。

Early-Exit 模式

原理：标准认证路由直接信任，跳过冗余代码审计。

效果：标准认证场景节省 50-70%。

AI 友好返回格式 YAML

原理：YAML 天然比 JSON 的 Token 量更少，对 AI 阅读更友好，降低模型解析成本。

五、模型选型原则与决策框架

在路由安全审计场景下，模型选型需围绕准确率与召回率两大核心指标建立决策矩阵：

最终选型：满足 P0/P1/P2 三重约束的最优模型。选型理由：在召回率 100% 的候选模型中，qwen3.5-plus 以更低的单位成本实现可接受的准确率，是批量场景下的最优解。

局限性说明：

测试集局限性：上述结论基于独立手工标注测试集（100+ 样本），与生产告警数据相互隔离，仅可作为基线参考依据。模型迭代风险：大模型迭代更新速度极快，市场中或存在性能更优、成本更低的全新模型，暂未纳入本次评测范围

AI 不是替代人工，而是放大安全工程师的能力：AI 处理重复性筛查，人工聚焦深度分析和复杂判断。

六、方法论沉淀

定制化漏洞分析能力沉淀：针对 API 越权漏洞场景，构建专属漏洞分析技能体系，持续沉淀检测规则与标准化分析流程，保障规则具备落地实战有效性。精细化危害评估体系：严格区分越权读取与越权操作两类风险行为，引入利益流向分析维度，规避一刀切式风险评级，评估更贴合业务实际风险。Token 成本系统化优化：通过 MCP→CLI 格式转换 + 代码精准按需提取 + Early-Exit 提前终止三层优化方案，整体实现 Token 成本降幅 95%+。场景化分层模型选型：批量例行场景采用高性价比模型，核心关键场景启用高精度模型，在检测效果与使用成本之间实现最优平衡

七、误报分析与改进方向

误报根因分析

基于已完成的复核告警深度分析，识别出以下主要误报原因及改进方案：

针对性改进方案

强化信任边界追踪（解决 35% 误报）

问题：AI 发现中间层没校验就停止，直接认为存在漏洞，未追踪到最终数据操作层。方案：在 Skill 中增加指导规则：发现校验就停止，发现缺失就继续，必须追踪到信任边界，中间层不能下结论。

上下游参数一致性校验（解决 25% 误报）

问题：下游方法参数有越权可能，但上游调用时未传入资源 ID。方案：分析 Controller 层 Request 对象，确认是否包含资源 ID 字段。如果上游 Request 中无资源 ID 字段，判定为"仅操作当前用户数据"。

Dubbo 配置信息补充（解决 10% 误报）

问题：内部网关转 Dubbo 传参信息 AI 无法获取，导致认证判断错误。方案：引入 Open 网关 Dubbo 配置信息（通过内部管理平台获取），新增 MCP 工具 get_dubbo_config，获取路由的 Dubbo 调用配置。

# 新增工具
"get_dubbo_config": {
    "description": "获取路由的Dubbo调用配置和参数映射",
    "inputSchema": {"route_path": "string", "service_name": "string"}
}

响应体价值预判优化（解决 10% 误报）

问题：AI 将无敏感信息的读操作误判为越权。方案：细化响应体敏感性判断规则。不敏感（可忽略）：

纯状态码返回
通用配置信息（活动名称、时间、状态）
流程节点信息

后续规划

八、小结

网关路由 AI 驱动审计是一个面向 API 安全场景的智能化交付范式，将规模化安全审计升级为 AI 自动化检测 + 精细化危害评估 + Token 成本优化的标准化机制。它回答的问题：如何在网关路由规模快速扩张的背景下，实现安全漏洞的全量自动化检测，同时将成本控制在可接受范围。它证明的事：多个高危外网漏洞的实际发现，验证了 AI 在代码审计场景的有效性。单条成本 ¥0.23，某大型业务集群全量扫描一轮不到 1 万元，成本完全可控。人机协同模式有效：AI 批量筛查 + 人工深度验证，既保证效率又确保准确性。它沉淀的方法：MCP→CLI 转换、精准代码提取、Early-Exit 优化，可复用于其他 AI 安全审计场景。

九、附录

标准化告警报告模板

本项目输出标准化的漏洞分析报告，以下是模板结构：

## 漏洞分析报告

### 1. 路由信息
- 路由ID: [必填：从 analyze_route 返回的 route_id]
- 路径: [必填：分析的路由路径]
- 目标服务: [必填：目标服务名称]
- 描述: [必填：路由描述，如无则填"无"]

### 2. 接口功能分析
- 接口用途: [必填：简要说明接口用途]
- 业务场景: [必填：业务场景描述]
- 调用方: [必填：H5前端/APP客户端/小程序/其他服务]
- 数据敏感性评估:
  - 涉及数据类型: [必填：PII/金融数据/订单信息/配置信息等]
  - 敏感等级: [必填：critical/high/medium/low]
  - 影响用户范围: [必填：全平台用户/特定用户群/内部用户等]

### 3. 调用链分析
[必填：调用链树形展示，使用缩进表示层级关系，标记漏洞点]

示例格式：
[网关入口] (总耗时)
  └─ [认证服务]: [认证接口] (耗时) [认证节点]
  └─ [业务服务A]: [业务接口] (耗时) [漏洞点]
     └─ [业务服务B]: [数据库查询] (耗时)

关键中间件操作（只写与漏洞分析直接相关的部分）:
- SQL: [可选：列出执行的 SQL 操作类型]
- Redis: [可选：如有 Redis 操作则填写]
- MQ: [可选：如有 MQ 操作则填写]

### 4. 漏洞详情

⚠️ 说明：
- 如果发现漏洞，必须填写此章节
- 如果未发现漏洞，填写"未发现漏洞"并跳过后续小节

#### 漏洞 1: [必填：漏洞标题]
- 严重等级: [必填：critical/high/medium/low]
- 类型: [必填：越权读取/越权操作/逻辑漏洞/竞争条件]
- 漏洞位置:
  - 服务: [必填：漏洞所在服务名称]
  - 方法: [必填：漏洞所在方法名]
  - 文件: [必填：文件路径:行号]
  - 仓库链接: [必填：GitLab 代码链接]
  - Trace ID: [必填：对应的 trace_id]
- 问题描述: [必填：详细描述漏洞原因和利用机制]
- 调用链位置: [必填：标注漏洞在调用链中的位置]
- 问题代码: [必填：漏洞代码片段，包含行号]
- 漏洞危害:
  1. [必填：直接危害]
  2. [必填：间接危害]
  3. 潜在连锁攻击: [必填：可能的连锁攻击场景]
  4. 合规风险: [必填：法律合规风险]
- 修复建议:
  1. [必填：具体修复方案]
  2. [必填：具体修复方案]
  3. [可选：额外加固建议]

### 5. 分析置信度
- 置信度: [必填：高/中/低]
- 依据: [必填：说明置信度的判断依据]

### 6. 局限性
⚠️ 数据获取不全说明:

| 限制类型 | 说明 | 影响范围 | 建议操作 |
|----------|------|----------|----------|
| [限制类型] | [说明] | [影响范围] | [建议操作] |

### 7. 二方包依赖
- 涉及的二方包: [必填：group_id:artifact_id:version - 用途说明，如无则填"无"]
- 源码获取: [必填：已获取/未获取/不需要]

### 8. 涉及的微服务
⚠️ 重要：必须包含 commit_id 和 project_path

- [service_name1] (commit: [commit_id], project: [project_path])
- [service_name2] (commit: [commit_id], project: [project_path])

往期回顾

1. AI 驱动：从运营行为到自动化用例的智能化实践｜得物技术
2. 生成式召回在得物的落地技术分享与思考
3. 立正请站好：一个组件复用 Skill 的工程化实践｜得物技术
4. 财务数仓 Claude AI Coding 应用实战｜得物技术
5. 日志诊断 Skill：用 AI + MCP 一键解决 BUG｜得物技术

文 / 炁源

关注得物技术，每周更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。

一、项目背景

随着交易业务的快速增长，对质量保障工作提出了更高标准与全新要求。为提升研发体验和架构升级，大量后台页面经历从 Vue -> React -> 全栈的迁移过程。业务演进过程中，后台能力持续迭代与优化；团队在交付新能力的同时，同步保障存量链路的稳定与可预期行为。为进一步完善测试用例覆盖范围，高效支撑回归测试与重构验证工作，需通过技术手段升级质量保障模式，为业务与架构迭代提供更充分的质量支撑。

E2E 测试： 即端到端测试，是一种从用户视角出发，模拟真实操作验证应用完整业务流程的自动化测试方法。自动化生成用例： 用线上内部运营操作日志自动生成 E2E 测试用例，快速覆盖核心流程，解决用例缺失问题。智能元素定位： 自动识别重构等场景 UI 变化并调整定位策略，实现维护流程的自动化。平台化管理： 通过数据看板管理用例和执行结果，让 E2E 测试可追踪、可优化，提升测试效率。

基于以上分析，我们致力于构建一套自动化 + 智能化的 E2E 测试方案，该方案旨在支撑快速迭代开发模式，有效应对用例覆盖与重构验证等场景，从而在现有资源条件下，持续为业务快速迭代和技术架构升级提供可靠的质量保障。

二、价值收益

提供基于线上真实运营行为的自动化 E2E 测试能力，能够实际发现页面线上/重构等场景的体验问题。在页面重构等迭代任务中，通过优化回归测试流程与资源分配，有效进一步提升测试支持效率。测试的页面代码覆盖率≥X%；无代码覆盖率场景步骤执行成功率≥X%。

页面代码覆盖率：页面用例在测试过程中 运行的代码行数 / 该页面关联的所有代码行数 * 100%步骤执行成功率：页面用例在测试过程中 执行成功的步骤数 / 用例总步骤数 * 100%。

三、方案选型

传统 E2E（DOM）

	名词解释	核心差异
传统 E2E	基于 DOM 的测试方案，主要通过操作和验证浏览器中的页面元素，来模拟用户行为的测试方案。	定位方式：依赖 XPath/CSS 选择器。用例生成：手动编写或录制。维护成本：高（DOM 变化需手动更新用例）。

AI E2E

	名词解释	核心差异
AI E2E	指利用人工智能技术，增强传统 E2E 测试的智能化、自适应性和效率的测试方案。	定位方式：视觉识别、语义化分析（如按钮文本、图标）。用例生成：自动生成（基于用户行为日志或需求描述）。维护成本：低（AI 自动适应 UI 变化）。

方案对比

传统 E2E 优势： 贴近真实用户操作：实际触发页面渲染和事件。跨页面流程验证：适合测试多步骤业务场景（如登录→下单）。传统 E2E 劣势： 脆弱性：DOM 结构变化易导致用例失败（需频繁维护定位表达式）。执行速度慢：依赖浏览器渲染和网络请求。

AI E2E 优势： 降低维护成本：减少因 UI 微调导致的用例失败。提升覆盖率：AI 可探索非预期路径（如异常输入）。AI E2E 劣势： 黑盒性：AI 决策过程不透明，调试困难。高成本：需积累足够数据优化模型，复杂视觉处理需要更高性能。

基于上述对比分析，我们选用 AI 驱动的 E2E 测试方案，能够在支持重构场景的同时，显著提升用例生成的自动化水平，从而形成高效可持续的自动化测试解决方案。

四、AI 工具选型

	特征
Midscene	原生 JavaScript + WebExtensions API；开源 AI 驱动 UI 自动化工具； 支持 Playwright、Puppeteer 定制行为逻辑；支持 Dom 分析和视觉分析，如 Qwen-vl、Chain-vl。
browser-use	Python + 大语言模型（LLM）+ 浏览器驱动；基于 Playwright；同时支持视觉和非视觉模型；同时支持 DOM 分析和视觉分析。

Midscene优点： 基于 JS 技术栈，前端友好，开发成本较低；支持 Playwright、Puppeteer 定制行为逻辑；公开渠道反馈与迭代节奏相对清晰；支持 DOM 与视觉多模态分析。如上优点对工程化落地更友好。Midscene缺点： 调用视觉/大模型时存在 Token 消耗与成本。

browser-use优点： 支持 Playwright 定制行为逻辑；支持 DOM 与视觉分析，能力面较全。browser-use缺点： 同样存在 Token 消耗与成本；基于 Python 技术栈，有开发语言熟悉成本。

综合评估后采用 Midscene，主要考量：与现有技术栈匹配： 以 JavaScript 为主，便于与前端工程、现有工具链协同，降低接入与维护成本。能力与扩展方式符合需求： 支持 DOM 与视觉等多路径信息输入，并可在需要时用 Puppeteer / Playwright 补充确定性、可编排的自动化逻辑，覆盖模型不稳定或不适用的环节。工程化与定制空间： 定制与扩展路径清晰，便于按业务拆解控制流、做兜底与回归，贴合当前团队的交付方式。

五、流程设计

核心流程图：

Midscene 测试过程详情：

核心流程可以概括为：将运营真实操作记录转化为可执行的测试用例，并通过智能化的方式在测试环境中回放验证。具体实现链路分为四个阶段：

阶段一：智能用例生成——从“行为记录”到“可执行脚本”

这是整个流程的源头与起点，目标是实现测试用例的“自动化生产”。

阶段二：灵活执行触发——从“静态资产”到“动态任务”

本阶段负责调度，将静态的测试用例转化为具体的执行任务。

阶段三：AI驱动执行——从“指令”到“结果”的转化

阶段四：平台化数据运营——从“结果”到“决策”的质量闭环

通过这四个阶段的闭环，系统实现了从真实运营行为到自动化测试用例的完整转化，并将执行结果转化为可运营的质量数据。

六、技术亮点

基于真实环境中的运营行为生成测试用例

基于 Midscene+Qwen2.5-VL-72B 执行用例

AI 驱动的精准 UI 交互测试

代码覆盖率作为硬指标

七、平台化效果

我们在页面上实现了以下可运营能力，将 E2E 测试从黑盒脚本转变为可管理、可追踪、可复盘的平台系统。

整体数据看板

页面列表（入口）：

展示内容：按业务域 / 系统 / 负责人筛选、页面级 PV/UV、用例数量、步骤执行成功率、代码覆盖率等指标。系统能力：页面维度汇总视图，将访问热度（PV/UV）与自动化质量指标（成功率 / 覆盖率）结合，指导用例优先级（高 PV 页面优先铺用例、优先治理）。

用例详情视图

用例列表（抽屉）：

展示内容：每条用例绑定监控系统信息、点击行为数量、执行结果、步骤成功率、打标及备注、执行/删除操作。系统能力：以线上运营行为列表为用例数据，将 可执行性评估/识别执行结果与预期偏差/可信度（打标）统一实现。

执行详情（弹窗）：

展示内容：按步骤展示 CLICK 结果、详细错误堆栈/描述、页面截图缩略图、单步覆盖率、页面地址与 监控系统链接。系统能力：将每一步的线上行为与 E2E 执行对照落库，让失败从黑盒变为可复盘的证据链。

点击明细（单页面的用例序列）：

展示内容：点击序号、点击描述（如点击某某预览弹窗/眼睛按钮）、点击行为数量等。系统能力：系统会为 Click Scope 生成更可读的描述，便于非开发同学理解与复盘，也是后续策略库/稳定性治理的输入。

八、总结展望

面对交易业务快速增长、技术栈频繁迁移、测试资源紧张的多重挑战，我们成功实现了基于真实运营行为的 AI 驱动E2E 测试方案。通过 Midscene 的视觉 AI 能力结合 Puppeteer 的精准控制，实现了用例自动化生成、智能交互执行和质量数据闭环。

之后我们将持续优化 AI 模型的准确率和稳定性，逐步实现从「用例执行」到「质量预测」的升级。同时推动平台向标准化、智能化方向发展，让质量保障真正成为业务创新的加速器而非瓶颈。

往期回顾

1.生成式召回在得物的落地技术分享与思考

2.立正请站好：一个组件复用 Skill 的工程化实践｜得物技术 

3.财务数仓 Claude AI Coding 应用实战｜得物技术

4.日志诊断 Skill：用 AI + MCP 一键解决BUG｜得物技术

5.Redis 自动化运维最佳实践｜得物技术

文 /卓翎

关注得物技术，每周更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。

一、背景

推荐系统在提升用户体验的同时，也面临着信息茧房、兴趣收敛和内容同质化的挑战。随着用户与系统交互的深入，"推荐→用户反馈→再推荐"的闭环会逐渐强化用户的少数主兴趣，导致推荐结果趋同，降低用户的新鲜感与满意度。

生成式AI技术的快速发展为推荐系统带来了新的机遇。与传统的判别式匹配范式不同，生成式召回通过预测用户下一个可能点击的内容，实现从"匹配已知"到"预测潜在"的范式转变。在得物社区这一潮流生活方式平台上，用户对内容多样性和新颖性的需求尤为突出，这为生成式召回的探索提供了天然的场景。

基于此背景，得物启动了生成式召回方向的一期探索，旨在为下一代智能推荐系统的构建积累经验，探索推荐系统的 scaling-law 规律。

传统召回方法的局限性与生成式召回的动机

传统判别式ANN召回的局限性

• 时序信息建模不足：难以有效捕捉用户行为序列中的长期兴趣、短期偏好及其动态演变过程。
• 兴趣多样性受限： 基于历史行为的匹配范式容易收敛到少数高频兴趣点，难以拓展用户的兴趣广度。
• 匹配范式天花板：判别式兴趣建模受限于已有历史数据，难以预测用户未来的、潜在的兴趣方向。
• 兴趣融合能力弱：各兴趣点通常独立建模，缺乏对用户多兴趣间协同关系的端到端建模能力。

生成式召回的核心优势

• Next-Token Prediction 范式：通过预测用户下一个可能点击的内容，实现端到端的用户兴趣融合建模。
• 引导式召回机制：为生成式模型提供可控的、结构化的召回条件，确保召回内容的相关性与业务目标一致性。
• 时序依赖建模：基于 Transformer 架构，自然捕捉用户行为序列中的时序依赖关系。
• 兴趣预测能力：不仅能匹配已知兴趣，还能基于历史行为模式，预测用户的潜在兴趣方向。
• 端到端优化：从用户行为序列直接生成召回结果，减少中间环节的信息损失。
• 具有 scaling-law 规律：随着样本与模型规模的提升，能大幅提高模型的表达能力，提高线上的推荐效果。

二、技术方案

得物生成式召回系统采用 Generative Model 与 Rerank Model 联合训练的端到端设计，实现了生成与排序的协同优化。

Generative Model设计细节

生成式模型基于 Transformer 架构实现 Next-Token 生成任务，主要特征包括：

• 主序列特征：使用用户图文和视频的有效点击序列，以及对应的一 / 二 / 三级类目序列，截断最近 100 个行为；
• 首位 User Token 生成策略：联合训练辅助双塔模型产出首位 user_token，通过梯度隔离机制，确保生成任务与双塔任务的独立优化；
• 模型参数配置：采用当前 DeepRec 框架可承受的最大参数规模，配置为 n_layers=3，n_heads=4，dim=64，并加入 position embedding，增强时序建模能力。

Rerank Model设计细节

重排模型与生成式模型联合训练，通过多任务学习提升召回精度：

• 联合训练机制：通过召回目标同时训练 rerank 模型的 item 塔与 user 塔，与 Generative Model 共享底层特征表示；
• 多任务梯度平衡：设计合理的损失权重分配策略，确保生成任务与重排任务的梯度协同优化。

推理过程：从一级类目生成到精准召回

生成式召回在线上推理时遵循"生成→向量化→检索→重排"的四步流程，兼顾了生成式模型的预测能力与向量检索的效率。

一级类目生成

推理过程首先通过生成式模块的 Decoder 生成 Top-K 一级类目。经过离线 recall@100 参数搜索对比，确定 K=4 为最优配置，在召回效果与计算成本间取得平衡。生成的一级类目作为后续步骤的 “硬条件” 向量，为多兴趣建模提供结构化引导。

多兴趣向量构造

基于生成的 K 个一级类目，通过条件双塔的 user_tower 分别得到图文和视频的 K 个用户兴趣向量。这一设计实现了兴趣解耦，每个兴趣向量专注于特定类目下的用户偏好，避免了传统单向量表示中的兴趣混淆问题。

ANN召回与Rerank排序

各兴趣向量分别进行 ANN 向量检索，从候选池中召回相关 item。召回结果再由 Rerank 模型进行精细化打分排序，最终通过蛇形 Merge 策略将多个兴趣通道的结果融合，作为最终召回列表输出。

三、实验效果

为验证生成式召回的实际效果，我们在得物社区进行了严格的AB测试。结果也带来了社区线上指标的显著提升。验证了生成式算法的在得物落地的可行性，并预示着更大的探索潜力。

核心消费指标显著提升

生成式召回在多个核心消费指标上取得显著正向效果：

指标名称	相对提升(%)	显著性
人均推荐有效VV	+0.41%	显著
社区DAU均时长(秒)	+0.37%	显著
人均推荐总时长(秒)	+0.45%	显著
推荐曝光UV人均内容VV	+0.39%	显著

多样性指标改善

除了消费深度，生成式召回在兴趣广度拓展上也表现突出：

多样性指标	相对提升(%)	显著性
人均点击一级类目数	+0.18%	显著
人均点击三级类目数	+0.23%	显著
人均曝光三级类目数	+0.19%	显著

未来工程优化方向

基于一期实践经验，后续工程优化将聚焦于：

• 框架迁移：从 DeepRec 迁移至 DeepSea-Torch 框架，支持更大参数量与稀疏特征；
• 架构升级：探索 One-Rec 框架落地，统一生成式与判别式召回范式；
• 推理加速：研究模型压缩、量化等推理优化技术，进一步降低服务延迟；
• 成本优化：通过训练策略改进和资源调度优化，降低单位效果的成本。

四、总结与展望

得物生成式召回一期实践表明，通过 “生成预测 + 引导召回” 的技术路径，可以在可控成本下，同时实现用户消费深度与兴趣广度的双重提升，为下一代智能推荐系统的构建提供了重要参考。本次实践成功验证了生成式召回在工业级推荐场景的可行性与有效性。通过 Generative Model 与 Rerank Model 的联合训练架构，实现了从判别式匹配到生成式预测的成功范式迁移。技术方案在保持推荐相关性的同时，显著提升了兴趣探索能力，为打破信息茧房提供了新的技术路径。

当前方案以一级类目作为生成目标，这是考虑到类目体系的稳定性和可解释性。下一步将基于社区样本训练 Item Embedding，并将 Item Token 离散化与用户 Next-Token 生成任务联合训练。这一演进将实现从粗粒度到细粒度的兴趣预测，提升召回的精准度。

模型能力升级

通过框架迁移大幅提升模型参数量，支持大规模稀疏特征，探索更强大的生成式模型架构。具体方向包括：

• 扩展上下文窗口：从当前的 100 行为扩展到更长序列，更好建模用户长期兴趣；
• 改进注意力机制：研究稀疏注意力、线性注意力等高效注意力变体，平衡效果与效率。

与LLM结合的可能性

借鉴得物在基于大语言模型的新颖性推荐上的经验，生成式召回可与 LLM 知识增强结合。LLM 的世界知识可以帮助识别用户潜在但未明确表达的兴趣，而生成式模型则负责将这些兴趣转化为可执行的召回策略，形成知识增强的生成式召回新范式。

多模态与跨域生成

探索利用多模态信息生成更丰富的用户兴趣表示，并尝试跨业务域的生成式兴趣迁移。在得物的业务生态中，社区内容与电商商品之间存在天然关联，通过跨域生成式召回，可以实现从内容兴趣到商品需求的自然过渡，提升业务协同价值。

往期回顾

1.立正请站好：一个组件复用 Skill 的工程化实践｜得物技术

2.财务数仓 Claude AI Coding 应用实战｜得物技术 

3.日志诊断 Skill：用 AI + MCP 一键解决BUG｜得物技术

4.Redis 自动化运维最佳实践｜得物技术

5.Claude在得物App数仓的深度集成与效能演进

文 /流煜曦

关注得物技术，每周更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。

一、引言：财务数仓为什么需要AI？

财务数仓的特殊性

在电商数仓体系中，财务域是复杂度最高、容错率最低的领域。不仅因为财务对于数据准确性的要求高，也因为财务是横向域，与几乎所有的域都有数据交叉，因此对业务 Sense 的要求很高。财务数仓工程师本质上在做三件事：

• 业务翻译： 将交易、支付、资金、促销补贴、成本等数十个业务系统的数据，翻译成通用的财务语言；
• 资产架构： 从 ODS 到 DWD、DWS、ADS 层层构建，确保财务 UE、财务管报等公司核心指标算得准、算得快；
• 质量兜底： GMV 口径是否统一，退款是否扣减，分摊是否跨周期对齐，任何一个字段的偏差都可能导致错误的经营决策。

财务域的独特挑战在于：字段间存在严格的数学公式关系（正向－冲销＝冲销之后），业务规则涉及跨周期分摊，对于质量的要求极高。如果单纯依靠人工兜底，要么容易出错，要么需要冗余大量人力做复核。尤其是在交付压力大的时候，质量问题就更容易被忽视。

痛点聚焦

从财务数仓的特殊性出发，我们可以总结财务数仓的痛点，大体可以分为如下几类：

基本上，在需求承接的每个环节，都可能因为"人"的问题，带来隐患。

AI 大模型能带来什么改变

为了有效解决"人"的问题，比如催得太急、看不过来、没看仔细、理解错误等问题，我们引入 AI 来做改变。核心思路是：大模型的介入不是替代数仓开发工程师，而是在「需求理解 → 代码编写 → 质量测试 → 文档沉淀」每个环节注入强推理能力。利用 AI 来代替人做大量的重复性工作，同时减少低级错误概率。

那么为什么 AI 能做到这一点？从技术发展的趋势看，有三个核心能力支撑了这一变革：

• 超大上下文打破知识孤岛： 200k+ token 的上下文窗口，可以将表结构定义、词根字典、指标计算逻辑一次性注入模型的 “工作记忆”，实现基于全域元数据的推演，让大模型具有记忆；
• 业务语义的自动抽象与对齐： 大模型能理解 “日活”“留存率”“归因窗口” 等业务术语，并映射为具体 SQL 实现，减少因需求理解偏差导致的返工；Claude 在编码领域显著优于其他模型，是因为它能 “懂” 业务逻辑，而不是简单的机械执行；
• 突破人类极限的规范执行力： 人工在紧迫工期下规范遵守率通常明显下降，而大模型注入规范后，可稳定维持在高位。只要指令给得明确，大模型 “几乎” 不会出错。

参考：亚马逊 AWS 对于构建一个强大、具备自我纠错能力且能查询多种数据源的 Text-to-SQL 解决方案架构图。

二、应用场景概览：从「单点提效」到「全链路增强」

场景与提效预期

基于上述观点，在财务领域，大模型可以在哪些具体的环节落地呢？以下是根据笔者近期实践经验，列出的可落地场景及提效预期。

人机协作模式：数仓研发的「L3 时刻」

如果借用自动驾驶的分级标准，当前数仓大模型应用正处于从 L2（辅助驾驶）向 L3（有条件自动驾驶）过渡的阶段，即在明确的 Prompt 约束与规范文档支撑下，AI 能接管绝大部分标准化的执行动作。

在财务域的实践中，我们也是按照这套自动驾驶分级的方法，将日常工作拆解成了三级：

这种分工背后的逻辑是：规范执行是人类的短板、AI 的长板；业务判断是 AI 的短板、人类的长板。 人工在紧迫工期下对命名规范、分区约束、注释要求的遵守率通常明显下降，且容易因疲劳产生遗漏；而 AI 一旦"学会"了团队规范，输出的规范遵守度可稳定维持在较高水平。反过来，AI 无法替代的是那些需要理解业务上下文、权衡取舍、处理分歧的工作。

AI 对于数仓全链路研发的提效作用

学习 Andrej Karpathy 关于 ChatGPT 分享的内容时，最大的感受是：AI 最强的能力，是 "泛化"。 因此，如果我们可以把数仓研发的链路拆分清楚，那么 AI 必然能够对其中的每一个环节提效，最终带来研发效率的大幅度提升！

三、核心应用场景深度解析

AI OneData 标准化建模（财务核算数据项目）

背景：财务核算 OneData 为什么难搞？

因为：仅第一轮模型设计，就涉及百张以上的表、多个子域、十余个业务过程、数百个指标。如果考虑到后续的二次/三次迭代，工作量势必大到无法想象。在当前以交付为主的阶段，很难花费如此多的时间做基建。以某次核算项目为例，各层表数量分布如下：

同时，财务域的核心特征是来源多（全公司系统）、指标多（单表字段数众多），但以可累加指标为主。财务严格意义上没有原子指标，全是基于业务指标加工出来的派生指标，且一个财务指标往往有多种口径：业务口径、资金口径、财管报口径。并且，项目涉及多个子域（核算域、技术成本域、促销补贴域、商业化域、分析域），覆盖从「计费 → 核算 → 结算 → 财务分析」的端到端业务过程体系。如果要彻底理解核算 OneData 的构建，不仅要懂数仓，还要懂财务，还要熟悉公司财务系统，这个要求非常难做到！主要难点集中在四个方面：

口径溯源极其复杂： 大量逻辑在工程侧实现，绝大多数表缺失业务文档、技术文档、口径文档，口径逻辑需要基于代码猜测，存在错误可能性，溯源工作量巨大。

规范执行不一致： 财务域涉及表命名规范（DIM/DWD/DWS/ADM 各有格式要求）、时间周期规范（1d/7d/30d/wtd/mtd/ytd 等多种）、生命周期规范、刷新周期规范、标准字段英文命名原则（{主体}{业务场景}{币种标识}{度量类型}{时间单位}）。规范越细，人工遵守率越低。

跨域依赖复杂： 财务是横向域，与各业务域交叉。核算域依赖大量上游表，技术成本域需要从云服务、算法、产研人力、标注人力等多个来源接入数据。

文档输出繁琐： 每个 ADM 表都必须包含 OnePage 文档（OneData 方案最重要内容），加上口径文档、模型使用说明、下游 mapping 文档，文档间大量重复但需各写一遍。

所以，我们更需要通过 AI 的能力，来做一套新时代的建模方法论，以适应 “低投入、大设计” 的智能建模场景。

建模方法论：规范即 Prompt × 迭代收敛法 × 海量文件阅读

第一个方法论：规范沉淀是前提

AI 的输出质量完全取决于输入的规范文档质量。财务核算项目中，我们沉淀了完整的规范体系作为 Prompt 的核心输入，包括：

• 模型设计规范：表命名、时间周期、生命周期、刷新周期；
• 标准字段英文命名原则：{主体 /fin}{业务场景 / 费用类型}{币种标识}{度量类型}{时间单位}；
• 财务业务全链路设计理念：计费层 → 核算层 → 结算层 → 财务分析层；
• 业务过程总线矩阵：多个业务过程与多个维度的交叉关系；
• 数据质量监控规范：完整性、准确性、一致性、合规性、业务规则等多个大类。

第二个方法论：迭代是常态

不要期望 AI 一次给出完美结果。验证的关键是选择复杂字段进行抽查 —— 在财务场景中，重点验证涉及条件取值的字段（如分摊逻辑、冲销逻辑、多口径指标），对照 SQL 代码验证溯源路径。每次迭代的产物不只是修正后的输出，更重要的是规范文档的完善。因此，针对每次迭代的结果，快速识别要改动的点并修改，这一点就很重要。也就是说，AI 可以显著提升我们的迭代速度！

第三个方法论：海量文件阅读

因为超大的 Context，所以不仅可以把历史上已有的文档一次性灌入进去，也可以把原有设计链路的表和代码交给大模型理解，省去大量阅读和理解的时间。同时，能够帮我们精准地画出业务架构图，辅助数仓工程师理解业务、构建模型。例如财务数仓架构图，很多子模块的逻辑，都是大模型读取代码后输出思路，再由数仓团队整理形成的。

Prompt 和效果

将以上规范作为学习知识输入给模型，再把原始数据表给到模型，模型即可以产出建模建议。

Prompt 示例：

请读取以下规范文档：

• 数仓规范资产细则（含词根字典、命名规范）；
• 离线数仓开发规范白皮书；
• 团队 Cursor Rules；

分析目标表（输入对应的表名）的建表语句，按照数仓建模规范（ODS → DWD/DIM → DWS → ADM）的方式，输出重构后的建模建议。

第一次生成的效果展示了初步建模建议，在经过不断的调优和知识输入后，最终版本要丰富很多，形成了完整的财务核算数据 OneData 方案。

收益

经过一段时间的实施，第一版核算数据结构已经落地，效果如下：

• 效率提升显著： 百张表的口径溯源、文档输出等标准化工作大幅压缩；
• 规范遵守率大幅提升： 表命名、字段命名、时间周期等规范严格执行，遵守率较人工有明显改善；
• 可复用性强： 规范文档、工具脚本、Prompt 模板、工作流程 SOP 均可跨子域复用（已在核算域、技术成本域验证）；
• 数据质量监控体系： 基于口径逻辑自动推荐 DQC 规则（完整性、准确性、一致性、合规性、业务规则等多大类）。

AI SQL Coding 实践（财务 UE 表迭代案例）

实践思路

以财务 UE 表某次迭代为代表的案例，主要成果有：

• 代码结构优化，可读性大幅提升： 指标分段清晰、逻辑分层明确，维护成本明显降低；
• 代码开发速度提升： 在规范与口径已对齐的前提下，从需求到可上线代码耗时缩短；
• 性能优化： 整体基线提前完成，为下游留出更多缓冲时间。

那么，我们是如何实现这种成果的？主要靠两点，一是 PRD 快速阅读与理解，二是代码开发效率提升。

如何理解 SQL Coding 核心能力

PRD 阅读与理解方面，AI 能够帮我们实现：

快速将 PRD 中的目标、指标、维度、过滤条件提炼为结构化要点；对「大促期间」、「小仓卖家」、「冲销」等未精确定义的表述，自动生成待确认问题清单；输出「指标口径」「统计周期」「主键与粒度」等需确认条目。

代码开发效率提升方面，AI 能够帮我们实现：

基于词根、分层、命名规范与建表模板，生成符合数仓规范的 DDL 与 SELECT 语句；多维度聚合、归因逻辑、窗口函数、多层嵌套等复杂逻辑，由模型生成初版 SQL，人工校验微调；对存量长 SQL 进行分段、抽取公共逻辑、统一风格与注释。

实践中大模型显著提升点

财务 UE 表迭代需求使用 AI 开发后，具体效果如下：

指标结构分段、编码规范性、注释清晰度：

• 新表：按数仓分层与命名规范生成 DDL 与 SQL，指标按业务域/统计口径分段组织，注释完整（字段含义、口径说明、KEY 标记等），既符合规范又便于阅读。
• 旧表改造：在保留业务逻辑正确性的前提下，对历史「屎山」代码进行结构化改写——统一别名、补全注释、拆分过长子查询、显式写出分区过滤等，使后续维护与排查成本明显下降。
• 代码展示对比：改动前 vs 改动后，可从「可读性、规范遵守度、注释覆盖」等维度做对比分析。

代码撰写速度大幅度提升：

• AI Coding 的主要步骤：Step 1：整理需求 → 技术文档 将 BI 需求文档中的字段信息整理进技术文档，明确字段范围。
• Step 2：大模型分析字段来源 提示大模型读取 DWD 源码，分析哪些字段已存在、哪些需要新增关联。
• Step 3：大模型编写 ETL 代码 由大模型自动在 DWD → DWS → ADM 三层添加字段代码，输出改动代码集合。
• Step 4：命名规范校准 引入指标字典和 Cursor Rules，让大模型按规范重命名字段（去掉不规范后缀）。
• Step 5：测试 SQL 生成与跑数验证 大模型生成自测 SQL，逐步验证各层数据一致性，不通过时追问原因并溯源。

性能优化及自动调参：

• 自动识别性能瓶颈：结合执行计划、大表扫描、数据倾斜等常见问题，由模型分析 SQL 与表结构，指出潜在慢点。
• 优化建议生成：在分区裁剪、谓词下推、JOIN 顺序、中间结果物化等方面给出具体改写建议。
• 参数调优方案：针对 Spark/ODPS 等引擎的资源配置、并行度、倾斜处理参数，给出可落地的调优建议，供运维或开发同学选用。

基线优化提升案例：

• 原链路：多张表串行/并行产出，整体耗时较长。
• 新链路：经模型辅助做表合并与逻辑下沉，收敛至更少的表，整体耗时明显缩短。
• 优化效果：在保证口径一致的前提下，表数量与运行时间双降，基线提前完成，资源占用与调度依赖均得到简化。

AI 数据测试（财务 UE 表邮费迭代案例）

财务数据测试的特殊挑战

在数仓开发工作中，数据测试是保障数据质量的关键环节，但也是最复杂、最耗时的环节之一。特别是在财务类指标开发中，数据测试面临着多重挑战：

测试复杂度高，影响面广：

一个指标的改动往往不是孤立的，它会引发连锁反应，影响其他相关计算指标。在复杂的业务场景中，一个字段的修改可能需要同步验证数十个相关字段的正确性。这种复杂的依赖关系使得人工测试很难做到全面覆盖，容易出现遗漏

业务逻辑复杂，公式验证困难：

财务指标通常有明确的数学公式关系：正向 - 冲销 = 冲销之后：需要验证每个字段的正向值、冲销值、冲销之后值之间的计算关系；子项相加 = 汇总项：需要验证各个子项字段相加是否等于汇总字段；

财务的分摊逻辑涉及跨周期问题，难以验证：某些业务场景下，订单时间与收入确认时间不匹配，需要进行跨周期分摊，测试逻辑极其复杂。这些公式关系看似简单，但在实际测试中，需要考虑各种边界情况、精度问题、空值处理等，验证工作量巨大。

测试用例设计困难：

一个需求往往衍生出大量测试点，单纯凭借个人经验和能力，很难做到全面覆盖，容易出现测试盲区，包括：

• 字段级别的计算逻辑验证；
• 汇总关系的验证；
• 冲销逻辑的验证；
• 边界场景的验证；
• 精度问题的验证；
• 业务规则转化的验证。

业务语言到数据语言的转化困难：

业务人员描述的需求往往是自然语言，而数据测试需要将其转化为精确的数据验证逻辑。例如："退小仓场景下，卖家邮费出资放在第一笔收入冲销，挂在最后一单"；"邮费返利抵减技术服务费"；"跨周期分摊，商业化订单时间与交易订单时间不匹配"。

AI 在数据测试中的应用实践

那么，我们如何通过 AI，来解决这些复杂问题呢？以某次财务 UE 表邮费迭代项目为例，我们深度应用 AI 进行数据测试，取得了显著效果。

项目背景：

该项目涉及邮费相关字段的全面重构，包括：

• 迭代字段：修改多个邮费相关字段的计算逻辑；
• 新增字段：新增大批量邮费细分字段；
• 删除字段：废弃部分历史字段；
• 逻辑变更：邮费返利抵减逻辑调整、冲销逻辑优化等。

AI 应用场景：

1. 测试用例自动生成：向 AI 提出测试要求后，AI 能够自动生成完整的测试 SQL 和说明文档，包括：

• 正向-冲销=冲销之后的验证逻辑；
• 子项相加等于汇总项的验证逻辑；
• 业务规则转化的验证逻辑；
• 边界场景的验证逻辑。

2. 规则理解层面的测试补充：AI 能够从规则理解层面补充测试案例，如抽样验证、精度验证等，减少因理解不一致带来的质量问题。特别是在复杂的跨周期分摊场景中，AI 能够识别出人工容易忽略的测试点。

3. 复杂逻辑的逐步分析：针对复杂的业务逻辑，AI 能够逐步分析不符合预期的环节，帮助找到潜在的代码 Bug。例如在邮费冲销逻辑中，AI 能够分析退小仓场景下的多种分支情况，识别出逻辑漏洞。

4. 上下游影响分析：AI 能够分析一个字段的改动对上下游的影响，帮助识别需要同步验证的相关字段，避免遗漏。

5. 公式验证与精度问题诊断：AI 能够自动生成公式验证 SQL，并识别精度问题。在测试过程中，AI 能够区分真正的逻辑错误和可接受的精度误差，避免误报。

实际效果与收益

经过 AI 加持之后，效果和收益明显，包括：

开发效率提升：

测试 SQL 生成效率明显提升：从提出测试要求到生成完整测试 SQL，时间大幅缩短；测试用例覆盖度提升：AI 能够识别出人工容易忽略的测试点，测试覆盖更全面。

交付质量提升：

一次交付通过率显著提升：从规则理解层面补充测试案例，减少理解不一致带来的质量问题；针对复杂逻辑逐步分析，找到潜在代码 Bug；自动生成全面的测试用例，减少测试盲区。

问题发现能力提升：

AI 在测试过程中能够：发现人工难以发现的逻辑错误，识别精度问题并区分可接受的误差，分析复杂的业务规则转化问题，诊断上下游影响关系。

综合收益较高。通过 AI 辅助数据测试，整体交付质量大幅提升，主要体现在：测试覆盖更全面，减少遗漏，问题发现更及时，减少返工，测试效率更高，缩短测试周期，质量保障更可靠，提升交付信心。

AI 需求文档转换（财务 UE 表邮费复杂逻辑解读）

痛点

理解 PRD 和与业务产品反复核对口径，大约占数仓总体工作时间的较大比例。BI 需求文档往往复杂难懂，第一眼看过去看不懂。

实践案例：邮费 UE 迭代技术文档

以邮费 UE 迭代需求为例，BI 需求文档涉及大量字段口径调整、新增字段、废弃字段、冲销逻辑重写等复杂内容。例如通过飞书 MCP 让 Cursor 直接读取 BI 需求文档，大模型自动总结出两张表（DWS 层和 ADS 层）各自需要改什么。大模型输出的结论结构清晰，按表分类列出：

• 字段含义/口径调整（哪些字段的逻辑需要改）；
• 数据来源与计算点（应收邮费、实收邮费的新口径）；
• 新增字段清单（应收拆分、冲销相关、实收拆分、成本、UE 等）；
• 废弃字段清单（相关历史字段）；
• 冲销逻辑重点（退小仓规则）；
• 两表关系与实现顺序（先改 DWS 再改 ADS）。

Prompt 实例：读取「邮费逻辑梳理」文档内容，分析其文字描述与财务 UE 表的代码，分析要改动的点，帮我生成对应改动代码和改动原因注释。

通过这个分析结果，能够很快地定位要改动的代码，然后一步步理解业务逻辑和具体如何改动。

效果

经过这个过程快速 get 到 PRD 缺失的内容、快速对齐，总体沟通时间有效缩减。虽然在总时间占比上看似不高，但节省的是工程师最头疼的碎片化沟通时间。

四、总结与展望

核心价值

当前市场上，部分头部大厂由于自身产品策略的原因，限制了内部使用最新的大模型和 IDE 工具，导致一线使用大模型的效率受到制约。而我们则能够更灵活地选择最适合的工具组合，在使用技巧和经验积累上具备优势。例如，我们有如下两个方面的优势：

能力层面：

• 规范化规则遵守：注入规范后生成结果遵守度稳定维持在高位；
• 业务抽象能力：快速理解 PRD 中的目标、指标与口径，识别模糊点；
• 实际落地案例丰富：财务 UE 表迭代等项目已有可量化结果。

组织与场景层面：

• 模型选择灵活，不绑定单一厂商，按任务类型选用最优模型；
• 组织精简高效，从确定方向到试点上线路径清晰，试错迭代周期短；
• 离线数仓分层与规范稳定，模型易学易用、效果可预期；
• 离线任务可重跑、可回溯，模型产出便于充分校验后再上线。

未来展望

使用大模型的能力不仅仅局限在财务、局限在个人，也要向整个团队推广，包括：优先选择 1-2 个痛点明确、规范相对清晰的场景做试点；将有效的 Prompt 设计、上下文组织方式、测试用例模板等经验在团队内分享，形成可复用知识库；从「人做」为主转向「人定规则与口径、模型执行环节」的协作模式，让大模型成为数仓同学的日常助手。未来已来。

往期回顾

1.日志诊断 Skill：用 AI + MCP 一键解决BUG｜得物技术

2.Redis 自动化运维最佳实践｜得物技术 

3.Claude在得物App数仓的深度集成与效能演进

4.Claude Code + OpenSpec 正在加速 AICoding 落地：从模型博弈到工程化的范式转移｜得物技术

5.大禹平台：流批一体离线Dump平台的设计与应用｜得物技术

文 /丹克

关注得物技术，每周更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。

一、背景

在实际迭代开发中，不同需求的代码规模差异很大，有些需求涉及上千行代码，有些则只有一两行。且对于前端的代码验收，主要侧重在界面功能，通过功能验收，没法确保每一行代码都测试到的，以及功能的代码逻辑是否合理，是否健壮、是否规范等问题，都需要通过人工代码 CR 来进一步兜底验收代码的质量，尽量降低业务线上出错的可能。但当面对上千行的代码变更时，人工 CR 也是心有余而力不足。

传统的代码审查依赖人工，面对大规模代码变更时效率有限，而 AI 代码审查能够实现自动化、标准化的质量检查，有效补充人工审查的不足。

二、前端研发 CR 现状与可优化点

CR 现状

目前前端研发同学主要使用的代码质量保障工具有前端 Apex 插件智能体、Uraya 质量分检测。其中 Apex 插件智能体是通过前端研发自助点击或 git hook 自动触发 CR 智能体执行，智能体内定制了 CR 规则以及与 MCP 的结合，利用 Cursor IDE 的 Agent 能力进行本地 AI CR ，找出代码问题、本地解决问题。Uraya 质量分检测是在创建 MR 后，通过流水线自动触发，Uraya 质量分检测代码变更的质量分浮动，产出具体问题的记录，引导研发优化代码。

可优化点

1. 本地触发 CR 需要研发同学主动点击触发或者通过 Apex git hook 执行 CR 智能体，当开发的需求多、分支多、提交次数多的时候，时长容易漏触发、忘记点。
2. 对于 MR 评审人员，如果希望通过 Cursor CR 时，需要在本地通过调用 CR 智能体再执行一遍，获取 CR 结果，在目前 Cursor 按量计费的背景下，重复执行 CR 智能体的成本需要及时关注。
3. 当前流水线 Diff + 大模型 API 的 AI CR 方式，误报率较高，研发使用意愿较低。

三、AI CR 方案对比分析

基于以上现状分析，我们对不同 AI CR 方案进行了深入对比。

Cursor Agent CR 主要优势

流水线集成 CR 与本地 AI CR 差异

四、技术方案设计

结合目前现状与可优化点，我们期望能像 Uraya 质量分检测一样，在 MR 过程中通过流水线自动触发，中途每次代码提交也能自动触发，对于流水线中的 CR 不满意时，可以结合 Apex CR 智能体进行本地 CR 调整代码。

为此我们考虑结合 Cursor Agent CLI 在流水线中增加一个 AI CR 的任务，自动触发 Cursor Agent 代码 CR，并记录 CR 结论，及时展示给研发或者代码评审的同学，辅助代码质量优化。

整体链路设计如下：

1. 当研发创建 MR 后，流水线配置了 AI CR 检测流水线后，将会自动触发 Cursor Agent CR 任务。
2. 接收到检测任务后，将会前置将该仓库准备好，并将 MR 的信息以及制定的 CR 规则，一并交给 Cursor Agent CLI 执行，待执行完成，会得到一份 CR 报告。
3. 接收到检测任务完成后，目前会通过 MR 评论的方式添加到对应的 MR 中，引导用户查看。
4. 对于开发者视角，打开审查报告，可以根据审查出的问题，进行修改。
5. 对于 CR 人员视角，打开审查报告，可以根据审查出的问题，一键添加到评论，引导开发者修改。

五、MR 流水线接入与 AI CR 报告

自动触发

以下图 MR 为例，在 MR 流水线中，添加了仓库流水线 AI 检测的检测任务，当创建 MR 时，会自动触发执行一次，在 MR 未合入的过程中，每次代码变更也会自动触发。

添加审查报告评论

检测完成后会自动添加一条 MR 评论，通知研发已完成检测，可以点击查看 CR 报告。评论概览中有审查摘要，显示聚类问题的数量；还有审查总结，即对所有反馈的总结，概览问题。

AI CR 报告

以下为实际 MR 生成的 CR 报告，可以看到，报告主要包括：MR 的基础信息、问题的分类 Tab、问题的具体描述、问题的操作。

具体问题列表

首先报告列表会对问题进行聚类，分为严重问题、警告、建议三类，切换对应 Tab 可以看到问题列表。具体的问题信息，主要有类型、问题代码、修复后代码、描述、文件路径、行号、操作等列。

添加到评论

点击操作列的添加到评论，将会一键将相关问题的信息，生成格式化描述，添加到 MR 的评论中，提醒开发者关注问题、解决问题。

AI 智能解决

点击操作列的 Cursor 解决，将会一键将相关问题的信息，生成解决问题 Prompt，一键打开本地 Cursor ，创建 Agent 对话去解决问题。打开链接后，Cursor 会先接收 Prompt ，你可以简单浏览下，点击 Create Chat ，即可一键创建 Chat，回车执行修复。

Cursor Prompt 预览

Cursor Prompt 预览 确认填入 Chat 执行

复制 Prompt

点击复制 Prompt，支持一键复制修复问题 Prompt，可以放到期望的 IDE 里使用。如下图，就是复制的 Prompt 示例。

六、推荐研发流程实践

尽早创建 MR

当需求分支第一次提交后，就可以创建到 release 或 test 目标分支的 MR 了，后续每次提交代码都将会自动触发检测，产出 AI CR 报告。

研发自主查看与解决

研发收到 AI CR 报告的通知后，可以及时打开 CR 报告查看，确认反馈的疑问点是否需要调整，如果需要调整可以通过 Cursor 一键解决，将问题解决前置到提测以前，这样所有的改动可以尽可能的被测试同学验证到。

人工 CR

发布前最后的人工 CR 可以通过前置的 AI CR 发现与问题前置解决，大幅提升靠最后人工 CR 的反馈、修改等环节效率。特别是当业务需求代码量较大时，人工 CR 浏览的效率和质量也是无法保证的。

七、内置提示词工程

AI CR 其实就像给 AI 一个详细的检查清单。这个清单分两部分：一部分是基本规则，比如"你要扮演什么样的角色"、"按什么流程检查"；另一部分是具体的技术要点，比如"注意空指针问题"、"检查React用法是否正确"等。有了这个清单，AI 就能像有经验的程序员一样，系统地检查代码，发现各种潜在问题，让代码质量得到保障。

具体这个规则体系的结构如下：

.cursor/rules
├── 00-role-and-constraints.mdc          # 角色与约束 - 定义AI代码审查助手的角色和基本约束条件
├── 01-workflow-steps.mdc                # 工作流程步骤 - 描述代码审查的工作流程和步骤
├── 02-detection-standards.mdc           # 检测标准 - 定义代码问题的检测标准和准则
├── 03-output-format.mdc                 # 输出格式 - 规定代码审查结果的输出格式和规范
├── 04-best-practices.mdc                # 最佳实践 - 提供代码审查中的最佳实践建议
├── common                               # 通用规则目录 - 包含各种常见的代码问题检测规则
│   ├── 01-null-pointer-defense.md       # 空指针防御 - 防止空指针异常的最佳实践
│   ├── 02-react-hooks-usage.md          # React Hooks 使用 - React Hooks 的正确使用方式
│   ├── 03-data-merge-state.md           # 数据合并状态 - 处理数据合并时的状态管理问题
│   ├── 04-async-programming.md          # 异步编程 - 异步编程模式和常见陷阱
│   ├── 05-memory-leak-performance.md    # 内存泄漏性能 - 检测和防止内存泄漏问题
│   ├── 06-security-coding.md            # 安全编码 - 安全编程实践和漏洞防范
│   ├── 07-compatibility.md              # 兼容性 - 确保代码兼容性的检查点
│   ├── 08-git-conflict-detection.md     # Git 冲突检测 - 检测并解决 Git 合并冲突
│   ├── 09-code-quality.md               # 代码质量 - 代码质量评估和改进规则
│   ├── 10-resource-handling.md          # 资源处理 - 正确处理系统资源的规则
│   ├── 11-url-params.md                 # URL 参数 - URL 参数处理的安全和有效性检查
│   ├── 12-business-logic-consistency.md # 业务逻辑一致性 - 确保业务逻辑一致性的规则
│   └── 13-monorepo-dependency.md        # 大仓依赖 - Monorepo 架构中的依赖管理规则
└── README.md                            # 说明文档 - 规则系统的介绍和使用说明

八、模型选择

在 AI CR 环节，模型的选择需要考虑模型对于代码理解的复杂性、上下文长度需求以及推理准确性、模型的速度、模型的使用成本等考量。在 Cursor 的模型列表中，我们优先使用 Compose 1.5，当额度不足时，我们也会降级使用 Auto 模型。

以下为 Cursor auto 模型与 Composer 1.5 模型对比，可以看出，两个模型都找出了 4 个问题，但在时间上，Composer 1.5 进行需 44 秒即可完成，而 auto 模型需要 91 秒。

九、总结与规划

通过多个迭代实践与数据统计，Cursor Agent CR 挖掘的有效问题数可以达到 50% 左右，研发使用的意愿也相比原来有不少提升。当前我们也在将 AI CR 报告融合到 Cursor IDE 插件中，进一步融合到研发流程里。

随着 AI 生成代码在开发流程中越来越普遍，AI CR 的重要性将进一步凸显。相比传统的人工审查，AI 审查能够自动发现 AI 生成代码中可能存在的逻辑错误、安全性问题和规范性缺陷，提前在开发过程中消除隐患。同时，AI CR 还能确保 AI 生成的代码符合团队的技术规范和最佳实践，保持代码风格的一致性。为 AI 时代的开发流程提供了可靠的质保机制，让开发流程更加顺畅，是现代软件开发的重要保障。

往期回顾

1.从IDE到Terminal：适合后端宝宝体质的Claude Code工作流｜得物技术

2.AI编程能力边界探索：基于 Claude Code 的 Spec Coding 项目实战｜得物技术

3.搜索 C++ 引擎回归能力建设：从自测到工程化准出｜得物技术

4.得物社区搜推公式融合调参框架-加乘树3.0实战

5.深入剖析Spark UI界面：参数与界面详解|得物技术

文 /大圣

关注得物技术，每周更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。

一、背景介绍

随着业务规模与流量的持续高速增长，自建 Redis 集群面临着更高地性能与稳定性要求，对平台化、自动化运维能力也提出了新的挑战。为进一步提升资源利用效率、保障服务稳定运行，并更好地支撑业务快速发展，我们对 Redis 平台进行了自动化能力的建设与升级，通过系统化的平台能力优化，降低人工运维费力度，提升整体运维效率与服务质量。

Redis 使用现状

Redis 集群目前基于 ECS 进行部署，采用单机多实例、主从混合部署的架构模式，并将 Proxy 组件与数据节点混合部署，以提升 CPU 资源利用率与整体部署密度。当前集群已达到百 TB 级存储规模、数十万数据节点，支撑超大规模业务场景的稳定运行。

面临的挑战和问题

随着业务规模与流量的持续增长，平台在资源效能与运维效率方面面临着新的优化空间：资源池层面机器资源池的整体利用率仍有提升空间，需进一步优化资源调度与负载均衡策略。运维自动化层面告警自动化处理覆盖度有待提升，部分复杂运维场景仍需人工介入，流程效率可进一步优化。

集群架构

自建 Redis 由 ConfigServer、Redis-Proxy、Redis-Server 等核心组件构成。

自建 Redis 2.0（SDK标准版） 整体架构图如下所示：

一主一从，双区部署

ConfigServer

ConfigServer 是自建 Redis 系统中关键组件之一，跨多可用区多节点部署，采用 raft 协议实现 ConfigServer 组件高可用；ConfigServer 主要负责两方面职责：

• 负责 Proxy 添加与删除、group 创建与删除、Redis-server 实例添加与删除、Redis-server 实例手动主从切换、水平扩容与数据迁移等功能操作。
• 负责 Redis-server 实例故障检测与自动故障转移（主节点故障后自动主从切换）。

Redis-Proxy

Redis-Proxy 组件是自建 Redis 系统中的代理服务，负责接受客户端连接，然后转发客户端命令到后端相应的 Redis-server 实例，使得后端 Redis-server 集群部署架构对业务透明，Proxy 支持 Redis RESP 协议，业务访问 Proxy 就像访问一个单点 Redis 服务一样，业务可以把一个自建 Redis 集群当作一个容量无限大的单点 Redis 实例即可。

Redis-Server（Redis-Group）

Redis-server 组件为开源 Redis 版本基础上，增加槽 slot 同步迁移与异步迁移等相关功能；支持原生开源 Redis 的所有特性，比如支持 String、Hash、List、Set、ZSet 等常用数据结构，AOF 持久化、主从复制、Lua脚本等等。默认一主一从，可支持多从部署。

二、自动化运维能力

自动化运维

资源池自动化均衡调度

当前 Redis 资源池支持按内存使用率自动化均衡调度、按内存分配率自动化均衡调度、按 CPU 使用率均衡调度、支持指定机器凌晨迁移调度（隐患机器提前维护、凌晨资源池迁移优化下线等）等功能，核心流程为合理选择迁移节点。现在每天定时生成迁移计划，迁移任务默认每天凌晨定时执行。

资源池均衡任务管理

迁移 server 节点选择算法流程图

Redis 潮汐调度算法示意

选择 Server 节点原则

1. 机器选择：
2. 获取内存容量使用率超过指定百分比的机器。
3. 获取分配率超过指定百分比的机器。
4. 获取需要维护和迁移优化的机器。
5. 优先节点数量多的实例节点：这样可以在资源均衡的同时，使得同一集群节点也更均衡，同一集群节点尽可能分散到不同的机器上。
6. 优先实例等级为非 P0 的实例。
7. 优先从节点：从节点迁移对大部分业务都没有任何影响。
8. 分配率和内存容量一样，优先节点规格中等规格（1-4G）实例，再选择 1G-5G 规格实例，最后选择其他规格的节点。
9. 最后汇总迁移任务节点：
10. 优先处理需要维护和需要迁移优化的节点。
11. 去掉同一个集群同一个分组的 master 节点，避免对同一 group 分组进行操作。
12. 对于需要维护和迁移优化的机器上的 proxy：
13. 获取原来 proxy 版本，资源标签等信息，判断是否是特殊作用 proxy，部署新 proxy。
14. 调整旧 proxy：对于 sdk proxy 禁用 proxy，对于 slb 下 proxy，调整权重。

选择 server 迁移任务流程图

• 节点选择后生成迁移任务，前端可展示、确认、取消；
• 定时任务执行生成的迁移任务；
• 添加从节点、同步数据；
• 同步数据完成后如果迁移节点是从则删除节点；
• 同步数据完成后如果迁移节点是主则进行主从切换；
• 如果迁移节点是主进行主从切换后检查新主从关系，检查 proxy 拓扑更新等，如果有异常则告警迁移。

迁移 proxy 节点选择算法流程图

proxy 节点选择流程图

选择 Proxy 节点原则

1. 优先机器 CPU 负载峰值高的机器上 Proxy 节点；均衡调度阈值支持可配置，后续均衡后继续调整。
2. 需要先采集到 proxy 24 小时 CPU 峰值，排序后优先迁移机器上 CPU 峰值最高的，直到机器 CPU 峰值降到均衡调度阈值。
3. 每台机器每天只迁移 1 个 proxy。
4. 判断 proxy CPU 峰值高的个数（如果只有一个就不处理，如果大于等于 3 个 proxy CPU 峰值高则处理一个（超过配置的均衡调度阈值算高 CPU 使用率））。

Proxy 迁移任务流程图:

• 节点选择后生成迁移任务，前端可展示、确认、取消；
• 定时任务执行生成的迁移任务；
• 获取原来 proxy 版本，资源标签等信息，判断是否是特殊作用 proxy，部署新 proxy；
• 新 proxy 绑定 LB；
• 调整旧 proxy：对于 sdk proxy 禁用 proxy，对于 slb 下 proxy，调整权重。

收益

• 提升资源池内存与 CPU 利用率，优化整体资源使用效率。
• 合理管控资源超卖率，降低自动扩容失败率与告警发生率。
• 基于机器维护窗口，在凌晨低峰期执行调度与实例迁移，高效支撑隐患机器前置治理、资源池离线优化及节点下线等运维需求。

资源池分级维护和管理

对 ECS 机器资源和 LB 资源进行打标，根据特殊业务需要做不同资源池的隔离调度。

可对资源进行多维度筛选：比如按资源标签、CPU、可用区、是否重保等维度筛选。

可对机器上部署的节点信息进行迁移操作和查看机器详细监控等。

物理资源隔离：自建 Redis 通过对 ECS 机器资源打标，实现重保集群隔离，支持集群物理隔离，减少集群相互影响，支持资源分级维护和灰度测试验证，减少大面积变更影响，使用相对保守的资源水位阈值来减少重保集群的运维频次和任务调度。

Redis 资源池隔离方案示意

不同资源池资源阈值项设置：

资源池分配阈值

集群生命周期自动化管理

集群自动化部署

当前 Redis 支持自动化集群部署，集群交付时间缩短至分钟级。

当业务提交集群申请工单审批通过后，判断是否支持自建，如符合自建则自动化进行集群部署和部署结果校验，校验集群可用性后自动给业务交付集群信息，整个过程高效快速。集群部署成功或者失败都会发送消息通知。

部署结果成功通知

部署结果失败通知

集群垂直扩缩容自动化

当前 Redis 支持 server 垂直扩缩容，ecs-proxy、docker-proxy 扩容等工单自动化操作。

扩容方案

集群 server 垂直扩缩容，ecs-proxy、docker-proxy 扩容等场景在业务提单时给出扩缩容方案和校验，实现工单自动化操作。

集群水平扩缩容自动化

当前 Redis 支持 server 自动扩容分片，以支持更高的请求和负载。

Server 水平扩缩容任务管理

水平扩缩容执行任务详情

集群下线支持回收和重建

当前 Redis下线回收，支持立即销毁和重建恢复。

集群自动下线流程

• 工单审批通过后立即下线接入层：检测 proxy（ecs-proxy 和 docker-proxy）连接和 qps 请求，都没有则调整权重，下线接入层（ecs-proxy 和 docker-proxy）。
• 7 天内如有反馈问题，需要继续访问，则重建恢复集群正常访问。
• 7 天后无反馈下线集群所有资源（包括数据层数据，这里下线后不再支持回收重建）。

集群回收站管理

大 key 删除支持产品化可回滚

支持自建 Redis 和云 Redis 多 db 大 key 删除可回滚。支持控制台大 key 删除任务管理（立即执行删除、定时删除、回滚等）。

进行中的任务

历史删除任务

版本升级自动化

• 对有需要的集群支持将指定集群在指定时间进行滚动升级到指定版本。
• 自动化版本升级收敛，通过自动化任务在凌晨低峰期进行同版型系列滚动升级。
• 支持升级任务管理、修改时间、查看任务详情、升级进度，取消任务等。

版本升级任务

版本升级记录

工单自动化

当前所有运维工单都已完成工单自动化，如 Biz 申请、创建实例、密码申请、权限申请、实例升降配、实例架构升级、Server 版本升级、Server 水平扩容、删除 key、下线实例等均完成工单自动化。业务提单审批通过后自动校验执行，执行完成后自动发送工单执行结果通知。

总结：除了需求描述性（云 Redis 需求）的工单，其他均实现操作工单化标准化，工单自动化。

查询自动化

集群控制台支持命令查询、Key 模糊查询、Key 随机采样等，查询结果也支持 json 格式化、复制等功能。

支持查询历史缓存，查询耗时记录等。

告警自动化处理

告警入库收敛优化

• 告警触发后收敛至集群维度入库；
• 判断告警是否沉默中：如内存容量告警，部分特殊集群可以写满按淘汰策略淘汰，不用扩容，这种告警需要沉默；
• 判断告警是否超频：因为集群分片很多，同一集群同一指标不同分片每次触发阈值都会触发告警；
• 将告警信息按集群所属发送到对应的业务域：同一集群可能存在多个业务方使用，根据业务域纬度增加业务域大群告警通知，提高告警业务感知能力。

Server 分片内存容量告警自动扩容

自建 Redis 支持业务配置自动扩容，当集群容量超过预警水位线 80% 时，可自动进行垂直扩容，不需要人工介入运维，对业务无感，自动扩容在夜间无人值守的场景下，大大降低了集群容量激增带来的风险。

Redis 自动扩容开关

Server 自动扩容流程图：

Redis 自动扩容流程图

• 管控周期性任务获取监控平台 Redis 内存使用率超过 80% 的监控信息。
• 节点告警信息收敛到集群维度处理。
• 判断集群是否开启自动扩容：集群申请时会让业务填是否开启自动扩容，页面也可配置开启或者关闭自动扩容。
• 判断节点是否超过集群设置的 80% 扩容阈值。
• 判断最近一天是否扩容次数大于 3 次：如果 24 小时内扩容多次，说明可能增长异常，需要让告警发出。
• 判断扩容后容量是否大于设置的最大阈值（8G）：这里单个节点最大值为 8G，方便维护。
• 预检查扩容后分配是否大于机器内存：自动扩容后分配容量不能大于机器容量。如果大于机器容量则记录扩容失败信息，如果小于则可执行扩容操作，扩容操作后再持久化参数到 Redis 配置文件，然后记录节点扩容成功。

宕机场景告警收敛与自动化处理

机器维度的告警收敛，减少告警。

• 订阅机器宕机事件入库；
• Redis server 和 proxy Down 告警信息入库；
• Redis server 和 proxy Down 告警触发后判断所属机器是否有宕机事件；
• 如果告警所属机器没有机器宕机事件，则直接发送电话告警和飞书告警消息通知；
• 如果告警所属机器有机器宕机事件，则判断告警时间是否超过 5 分钟，如果 5 分钟后告警还没恢复则当前节点自动拉起失败，发送电话告警和飞书告警消息通知。如果节点自动拉起成功，则不会再触发告警。

宕机节点自动重启流程图：

针对夜间 Redis 实例机器宕机，引入自动化巡检和自动重启机制，减少夜间运维成本，提高夜间故障集群主备完整性恢复效率。

Redis 宕机自动恢复示意图

• 订阅机器宕机事件入库；
• 周期性任务查询宕机信息；
• 机器宕机加入事件队列，判断是否事件重复，重复则不加；
• 重启宕机上的节点，如果返回失败加入事件队列，支持重试 3 次；
• 发送重启结果消息通知。

收益

• 将告警信息按集群所属发送到对应的业务域，降低了告警后不断找人拉群的运维工作量。告警自动实时同步给业务，提高了业务告警实时性和告警感知能力。
• 通过告警入库收敛优化、宕机场景告警收敛优化和告警自动化处理，降低告警噪音 90% 以上。
• 通过 Server 分片内存容量告警自动扩容、机器宕机节点自动重启，极大降低运维成本和提高告警恢复效率。

自动化巡检推送

黑名单管理

对集群大 key、集群热 key、集群混用情况、集群成本等进行巡检，针对特殊场景的 key 支持集群维度、key 维度和 key 前缀维度的黑名单配置。

黑名单管理

大 key 巡检日报

每日按业务域维度巡检集群存量大key，推送巡检信息到对应业务域大群，大 key 巡检支持黑名单管理。点击实例 ID 可跳转查看 key 分析详情。

大 key 巡检日报

key 分析详情

热 key 巡检

实时将集群热 key 信息，推送巡检信息到对应业务域大群，热 key 支持黑名单设置。

集群热 key 实时巡检

实时热 key 分析

三、总结

通过持续构建与完善平台自动化运维体系，我们实现了 Redis 集群全生命周期运维的规范化、标准化与自动化，覆盖集群部署、垂直扩缩容、分片水平扩容、版本升级、集群生命周期管理、资源池多维度智能调度、自动化告警处理及常态化巡检等核心场景。整体运维流程实现少人化、无人化执行，大幅降低运维复杂度和人工运维费力度。依托运维工单化、流程自动化的建设思路，平台整体运维效率得到显著提升，为 Redis 服务长期高稳定、高可靠、高性能运行提供了坚实保障。

往期回顾

1.Claude在得物App数仓的深度集成与效能演进

2.Claude Code + OpenSpec 正在加速 AICoding 落地：从模型博弈到工程化的范式转移｜得物技术 

3.大禹平台：流批一体离线Dump平台的设计与应用｜得物技术

4.基于 Cursor Agent 的流水线 AI CR 实践｜得物技术

5.从IDE到Terminal：适合后端宝宝体质的Claude Code工作流｜得物技术

文 /陌叶

关注得物技术，每周一、三更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。

一、破局：AI 编码的真正瓶颈不是模型，是上下文管理

在软件开发的历史进程中，每一次效率的飞跃都伴随着抽象层次的提升。从汇编语言到高级语言，从手动内存管理到垃圾回收，开发者始终在寻求降低认知负荷的方法。进入 2026 年，生成式人工智能（GenAI）已成为编程领域不可或缺的力量。 然而，行业正经历从 “模型崇拜” 向 “工程落地” 的深刻转型，单纯依靠增加大语言模型（LLM）的参数规模已无法解决复杂业务逻辑中的幻觉与失控问题。

当前的共识是，AI 编码（AICoding）的真正瓶颈不在于模型的逻辑能力，而在于上下文管理（Context Management）的失效与开发意图（Intent）的模糊。

通过对 Anthropic 推出的 Claude Code（以下简称 CC）与 Fission AI 倡导的 OpenSpec 进行深度解构可以发现，两者正在通过 “代理化执行” 与 “规格化驱动” 双轮驱动，构建一套闭环的 AI 研发体系。这种结合不仅标志着 AI 编程工具从 IDE 插件向终端原生代理（Agentic Tool）的转变，更预示着 “规格驱动开发”（Spec-Driven Development, SDD）将成为企业级 AICoding 落地的核心范式。

在 AICoding 的早期阶段，开发者普遍认为只要模型足够强大，就能解决所有编程难题。然而，随着项目复杂度的增加，这种观点遭到了现实的挑战。研究表明，虽然 AI 编码助手的使用率在提升，但软件交付的稳定性却在下降。例如，Google 的 DORA 2024 报告指出，AI 采用率每增加 25%，交付稳定性反而下降 7.2%。

生产力悖论与认知负荷

AICoding 领域存在一个显著的 “生产力悖论”：开发者在使用 AI 时主观感知速度提升了 20%，但实际完成任务的时间却增加了 19%。这一现象的根源在于 AI 在处理长上下文时的效能衰减。随着任务推移，AI 往往会陷入修正循环（Fix/Test Loops），无法触及深层的业务功能，反而需要更多的人工干预。

模型的逻辑推理能力（Reasoning）在短小上下文中表现卓越，但在大型工程环境中，模型面临的是 “上下文中毒”（Context Poisoning）和 “注意力漂移”（Attention Drift）。当对话历史过长或包含过多无关代码时，模型的性能会呈现非线性下降。例如，GPT-4o 等先进模型在 1K Token 时的准确率为 99.3%，而当上下文扩展到 32K Token 时，准确率会暴跌至 69.7%。这种 “性能断崖” 意味着，单纯依靠扩大上下文窗口（Context Window）并不能解决问题。

上下文工程的兴起

上下文工程（Context Engineering）正在取代提示词工程（Prompt Engineering），成为 AICoding 的核心技术方案。上下文工程的核心不在于 “如何写更好的指令”，而在于 “如何为模型筛选最精准的 Token 集合”。

下表对比了传统缩放路径与上下文工程路径的局限性：

在大型组织中，上下文管理面临更严峻的挑战。很多关键决策并未记录在代码中，而是散落在飞书文档评论、群消息、会议或开发者的认知中。AI 代理在缺乏这些隐性知识（Implicit Knowledge）的情况下，生成的方案虽然符合语法，但却违背了架构初衷或业务约束。

上下文作为一等系统

现代 AI 代理架构开始将上下文视为一种具有自身架构、生命周期和约束的 “一等系统”。在这种视角下，上下文管理不再是临时的字符串拼接，而是一条精密的 “编译器管道”：

• 存储与呈现分离： 区分持久化的会话状态（Session）与单次模型调用的工作上下文（Working Context）。
• 显式转换： 通过命名的、有序的处理器（Processors）构建上下文，而非随机堆砌。
• 默认作用域： 每个子代理仅能看到执行任务所需的最小上下文，通过工具（Tools）按需获取更多信息。

二、Claude Code：把 AI 变成真正懂你项目的编码伙伴

Claude Code (CC) 是 Anthropic 推出的原生代理工具，它直接运行在终端中，具备读取文件、运行命令、执行重构以及自主验证的能力。与传统的 IDE 插件相比，CC 的核心优势在于其“代理循环”（Agentic Loop）和对上下文协议的深度掌控。

代理循环：收集、行动与验证

CC 的工作流程被定义为一个闭环系统，旨在模仿人类工程师的思维过程：

• Gather Context（收集上下文）： CC 不会盲目读取整个目录，而是通过文件搜索、Git 状态检查以及读取特定的 CLAUDE.md 文件来建立认知。
• Take Action（采取行动）： 基于推理，CC 可以跨多个文件执行编辑，或者利用终端工具（如 npm install、git commit）操作环境。
• Verify Results（验证结果）： 这是 CC 最具杀伤力的特性。它能自动运行测试、捕捉错误，并根据反馈调整方案。研究表明，带有验证步骤的 Coding 生成过程，其成功率远高于单次生成。

终端原生的工程哲学

CC 选择了终端而非图形界面作为主场，这体现了其 “代理优先” 的设计哲学。CC 遵循 Unix 哲学，支持管道（Pipe）、脚本化和自动化集成。这种设计使得 CC 能够与现有的 CI/CD 流程完美衔接，例如在 GitHub Actions 中自动执行代码审计。Anthropic 最新推出的 Code Review 功能，就是通过 Claude Code 基于 PR 的方式进行 bug 的追踪。

下表详细对比了 CC 与行业领先的 AI 编辑器 Cursor 的差异：

MCP 与“即时上下文”

CC 深度整合了模型上下文协议（Model Context Protocol, MCP）。MCP 是一个开放标准，允许 AI 代理安全地访问外部数据源。

为了应对大规模工具定义导致的上下文溢出，CC 引入了 “工具搜索” 和 “代码执行” 模式。代理不再一次性加载成千上万个 API 定义，而是通过编写代码按需调用 MCP 服务。例如，在分析大型数据库时，CC 不会加载全量数据，而是编写针对性的查询语句，仅将结果摘要读入上下文。这种 “按需加载” 策略极大地提升了 Token 的效用。

CLAUDE.md 与自动记忆

CC 引入了 CLAUDE.md 文件作为项目的 “操作手册”。这是一个置于根目录的 Markdown 文件，用于存储项目特定的编码标准、架构决策和测试指令。与临时提示词不同，CLAUDE.md 提供了持久的、跨会话的约束。

此外，CC 具备 “自动记忆”（Auto Memory）功能。它会自动在 MEMORY.md 中记录项目的构建命令、调试心得和用户的偏好设置。每当新会话启动时，CC 会加载这些记忆的前 200 行，从而确保 AI 在长期协作中能够 “越用越懂你”。

三、OpenSpec：给 AI 编码加上"规格书"，从失控到可沉淀

虽然 Claude Code 提供了强大的执行引擎，但在复杂业务中，AI 仍然可能因为意图不明而跑偏，最终导致交付的代码不符合预期。

OpenSpec 的出现为 AI 编码提供了 “规格说明书”，将 AICoding 从 “凭感觉写代码” 提升到了 “按规格执行任务” 的高度。

规格驱动开发 (SDD) 的兴起

OpenSpec 倡导的是一种 “规格驱动开发”（Spec-Driven Development）范式。其核心理念是：在写任何一行代码之前，先由人类与 AI 共同协商并锁定一份机器可读、人可评审的规格文档。

下表展示了 SDD 的三个演进阶段：

OpenSpec 的工件体系 (Artifacts)

OpenSpec 弃用了笨重的开发文档，转而采用一套轻量级的、面向 AI 优化的 Markdown 工件体系。每个变更（Change）都被组织在独立的文件夹中：

• proposal.md： 描述变更的初衷（Why）和范围（What）。
• specs/： 具体的逻辑规格，通常包含 “Scenario（场景）” 描述，通过具体的输入输出消除模糊性。
• design.md： 技术设计方案，包括本次变更涉及的数据库变更、接口调整等。
• tasks.md： 原子化的任务清单，作为 AI 的执行路径图。

解决上下文污染：提案、应用与归档

OpenSpec 最具洞察力的设计在于其生命周期管理。AI 在处理新任务时，最忌讳被旧任务的陈旧信息干扰。OpenSpec 的 “归档（Archive）” 机制解决了这一问题：

• Proposal 阶段： 建立一个独立的变更上下文，让 AI 只关注当前变更。
• Apply 阶段： AI 严格按照 tasks.md 执行，避免了盲目扫描全库导致的 Token 浪费。
• Archive 阶段： 任务完成后，临时变更文档被移入归档，核心规格更新至主规格文件。这保证了 AI 始终在一个 “卫生” 的上下文环境下工作，同时也为项目留下了可追溯的决策链路。

四 、实战：CC + OpenSpec 如何落地真实业务

在实际的企业业务场景中，如何整合这两大工具？答案在于将 OpenSpec 的标准化指令集注入到 Claude Code 的会话环境中。

案例实战：复杂业务逻辑的重构

假设一个电商项目需要重构其优惠券结算逻辑。在传统的 AI 辅助下，AI 可能会在修改 CouponService.java 时遗漏分布式锁，或者破坏原有的满减叠加规则。采用 CC + OpenSpec 模式，流程如下：

第一步：提案初始化

执行 /opsx:propose "重构优惠券结算逻辑，引入 Redis 分布式锁并支持多卷叠加"。CC 会在 openspec/changes/refactor-coupon-logic/ 下生成整套骨架。AI 会通过分析现有代码，在 spec.md 中自动列出已知的结算场景。

第二步：规格对齐与边界确认

这时不用急着让 AI 写代码，而是需要先审阅 spec.md。如果发现 AI 没考虑 “优惠券过期临界点” 的并发问题，可以直接要求 AI 修改规格：“在 spec.md 中增加过期校验场景，并要求使用 Lua 脚本保证原子性”。

第三步：受控应用（Apply）

一旦规格通过人工评审，就可以执行 /opsx:apply 了。这时，CC 就变成了完美的执行机器。它不再 “猜” 开发者的意图，而是对照 tasks.md 逐项实施。每一项修改后，它都会运行相关的测试。如果测试失败，CC 会自动分析错误并重新修复，直到该项 Task 标为 “完成”。

第四步、归档与知识固化

任务结束后，执行 /opsx:archive。原本散落在会话记录中的重构逻辑，现在变成了 openspec/specs/coupon-settlement.md 中的标准规格。当下一次另一个 AI 代理（或新入职同事）需要修改此模块时，它只需读取这份规格，即可获得完整的业务语境。

工具链对比：为何选择 OpenSpec

在 SDD 工具链中，OpenSpec 展现出了极高的工程性价比：

OpenSpec 的优势在于它不试图改变开发者的工具偏好。无论是使用 Claude Code、Cursor 还是 Aider，都可以无缝接入 OpenSpec 的规格管理层。

五、沉淀：让 AI 编码能力在团队中持续积累

AICoding 落地的终极目标不是让个体开发者写得更快，而是提升整个团队的知识资产质量。AI 编码能力不应随对话窗口的关闭而消失，而应作为 “团队记忆” 沉淀下来。

从个人技能到组织技能

团队可以通过自定义 Skill 和 MCP Server 来固化组织资产。

• Skill： 将公司特有的代码风格、安全审计清单，或者特定中间件的使用指南封装为 .claude/skills/。当团队成员使用 CC 时，AI 会自动加载这些技能，仿佛有一位资深架构师在时刻盯着每一行代码。
• MCP Server： 连接企业内部的向量数据库（如基于 Zilliz 的语义搜索），让 AI 代理能够从数千万行历史代码中找到最佳实践。

建立 AICoding 效能飞轮

AICoding 的成功落地需要建立一套正向循环的 “飞轮”：

• 规格积累： 每完成一个 PR，都强制更新对应的 OpenSpec 规格文件。
• 指令进化：发现 AI 反复犯的错，就将其转化为 CLAUDE.md 中的负向约束（Prohibited rules）。
• 并行执行： 利用 CC 的 Agent Teams 能力，让一个代理负责写规格，另一个代理负责审计代码，第三个代理负责集成测试。

角色转变：从 “码农” 到 “规格定义者”

在 CC + OpenSpec 模式下，软件工程师的角色正在发生质变。如果 AI 能够根据完美的描述生成任何代码，那么 “代码” 本身就变成了编译后的中间产物，而 “规格” 才是核心产品。领域专家（Domain Experts）的重要性显著提升，因为他们能提供最高质量的业务意图描述。这种趋势将迫使开发者从关注 “语法实现” 转向关注 “系统设计” 和 “逻辑严密性”。

六、结语：AICoding 落地的飞轮正在转动

在 2026 年，AICoding 已不再是科幻。Claude Code 提供的强大代理能力，配合 OpenSpec 提供的精密规格框架，为企业提供了一套可复制、可量化的研发新范式。

我们必须承认，AI 编码的瓶颈从来不是模型不够聪明，而是我们与 AI 之间的 “沟通带宽” 太低且 “上下文” 太脏。通过上下文工程化管理（CC）和意图标准化表达（OpenSpec），我们正在构建一套让 AI 能够长期、稳定产出的工程环境。

随着这一模式的普及，软件开发的门槛将进一步降低，而创新的上限将被无限拉高。AICoding 落地的飞轮已经转动，那些能够率先将 AI 编码能力转化为团队组织资产的企业，将在未来的数字化竞争中占据绝对的先机。毕竟，在 AI 时代，掌握了 “意图” 与 “上下文” 的人，才掌握了软件工程的未来。

参考文档：

1. thenewstack.io/context-is-…
2. github.blog/ai-and-ml/g…
3. solguruz.com/blog/spec-d…
4. medium.com/@eran.swear…
5. www.anthropic.com/engineering…
6. code.claude.com/docs/en/how…
7. www.anthropic.com/engineering…
8. code.claude.com/docs/en/bes…
9. dev.to/webdevelope…

往期回顾

1.大禹平台：流批一体离线Dump平台的设计与应用｜得物技术

2.基于 Cursor Agent 的流水线 AI CR 实践｜得物技术

3.从IDE到Terminal：适合后端宝宝体质的Claude Code工作流｜得物技术

4.AI编程能力边界探索：基于 Claude Code 的 Spec Coding 项目实战｜得物技术

5.搜索 C++ 引擎回归能力建设：从自测到工程化准出｜得物技术

文 /后羿

关注得物技术，每周更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。

一、背景

事情是这样的，之前对 AI 编程一直是观望态度，但是部门最近在做 AI 辅助编程 POC，有幸成为 POC 用户，用上了自己舍不得买的高级编程模型 （感谢公司）。尽管我自认为是一个在代码上很挑剔的人，但是试了下感觉居然还可以 （Go、React）！只能说还得是谷歌，调整重心略微发力，Gemini 3 表现确实很不错。既然尝到甜头了，觉得自己是时候好好地琢磨琢磨，研究研究，沉淀一套自己的工作流、方法论，解放自己的生产力，顺应潮流努力成为 AI 时代的受益者，而不是被淘汰的人！

新的开发范式需要搭建新的开发环境和匹配自己开发习惯的工作流，这就像刚学编程那会，需要挑一个自己喜欢的 IDE、熟悉 IDE 快捷键和优化 IDE 设置一样。过程中间肯定有阵痛，Java 开发者们回忆一下多年之前从 Eclipse 转 IDEA 那会的阵痛吧，但是磨刀不误砍柴工，阵痛之后一定是生产力提升。借本文分享下我摸索后的方案，供大家参考。

二、工具选型

目前 AI 辅助编程领域热火朝天，各种 GUI 工具、TUI 工具如雨后春笋让人目不暇接，这对于花心的强迫症选手（比如我）来说选型很困难。但是我觉得有两个基础认知可以帮助我们更好地做决定：

（一）AI 辅助编程工具由脑和手两部分组成。脑是外接的大模型 API，手是各个产品调教的提示词和内部工作流。按我理解，【脑】决定了工具的上限，【手】决定了工具的下限。在这个场景里，大模型就像是汽车里的发动机，而且所有型号的汽车支持的【发动机】规格都是通用的、统一的、标准化的。有了这个基础，我们可以随便选一个趁手的工具，然后自行按场景选配【合适】的【发动机】。

（二）AI 辅助编程当前是一个【千帆竞发】的热门领域，而且单纯就【工具】来说，这个领域【没有技术壁垒】。A 产品抛出的杀手级特性，不出半个月一定会有 B 产品跟进。毕竟现在软件迭代的速度借助 AI 提升了很多，A 产品验证过的想法，B 产品可以很快地跟进和实现。Claude Code CLI 的开发者就使用 Claude Code CLI 迭代 Claude Code CLI，有点绕口，大概就是【工具自举】的意思吧。

Claude Code CLI

综上，其实没啥纠结的，我们照着这两点来选型就好：1. 这个工具一定得便捷地支持模型插拔，就是我随时可以根据场景换一个更适合的、更便宜的、表现更好的大模型。而且这种插拔一定要简单。 2. 这个工具一定要有积极的维护者，不断地迭代、优化它的工作流、提示词。最好是一个商业化产品，因为商业化产品出于其商业目标，一定会投入资源积极进行迭代。 

当前满足这两个条件的，我想也就是 Claude Code CLI 了： 1. Claude Code CLI 是一个商业化产品，有专门的技术团队在不停地更新、迭代。 2. Claude Code CLI 可以非常便捷地支持大模型插拔，我可以随时根据成本、效率、体验来切换合适的大模型。因此，这个环节我选 【Claude Code CLI】。

后文以CC代指Claude Code CLI。

快速切换模型

我通过自定义 Shell 函数来实现便捷的模型切换，不同的场景、不同的任务使用不同的模型。基本原理就是，CC 支持环境变量注入 LLM 配置信息，因此我只需要按场景注入【行内临时环境变量】即可。

详见：Bash - 行内环境变量，Bash 是标准的 Shell 实现，其他 Shell 如 Zsh 都兼容其行为。

Shell配置

我到处弄了一堆免费的、收费的模型用，然后给他们取了我记得住的别名：

使用效果

为了兼容，设置了一个 claude 别名：

这样输入claude 时，默认使用智谱 GLM 模型。

脚本源码

Shell 脚本大概这样，可以修改后配置到自己的 ~/.zshrc 中。如果不熟悉 Shell，嫌麻烦也可以试试这个开源工具：farion1231/cc-switch。

# claude 默认
alias claude='zcc'
# Kimi
function kcc(){
    echo Kimi Claude Code...
    local model="kimi-k2.5"
    ANTHROPIC_BASE_URL="https://api.moonshot.cn/anthropic" \
    ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxxx" \
    ANTHROPIC_SMALL_FAST_MODEL="$model" \
    ANTHROPIC_DEFAULT_OPUS_MODEL="$model" \
    ANTHROPIC_DEFAULT_SONNET_MODEL="$model" \
    ANTHROPIC_DEFAULT_HAIKU_MODEL="$model" \
    CLAUDE_CODE_SUBAGENT_MODEL="$model" \
    launch_claude_code $@
}
# 智谱GLM
function zcc(){
    echo GLM Claude Code...
    ANTHROPIC_BASE_URL="https://open.bigmodel.cn/api/anthropic" \
    ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxxx" \
    launch_claude_code $@
}
# 七牛
function qcc(){
    echo QiNiu Claude Code...
    local model="minimax/minimax-m2.1"
    ANTHROPIC_BASE_URL="https://api.qnaigc.com" \
    ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxxx" \
    ANTHROPIC_SMALL_FAST_MODEL="$model" \
    ANTHROPIC_DEFAULT_OPUS_MODEL="$model" \
    ANTHROPIC_DEFAULT_SONNET_MODEL="$model" \
    ANTHROPIC_DEFAULT_HAIKU_MODEL="$model" \
    CLAUDE_CODE_SUBAGENT_MODEL="$model" \
    launch_claude_code $@
}
function launch_claude_code(){
    CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
#    clear
    command claude $@
}

三、开发环境

在当前的气氛下，我想我算是一个【古板】的开发者，我做不到【fire and forget】，或者说完全靠黑盒的自然语言对话来完成代码开发。

我还是只将 AI 当助手，还是想要白盒的掌控 AI 写的代码，还是希望最终交付的代码有我的风格、我的审美、我的品味。毕竟 AI 也只能帮我写代码，并不能帮我背锅。尽管我选择了 TUI 工具 Claude Code CLI，但是我还做不到全程只在终端操作，我还是习惯 JetBrains 特色的双栏 diff。

因此，当前我开发流程的起点还是传统的 IDE，比如我最喜欢的 JetBrains。每天上班第一件事是接水，第二件事就是打开 IDE。所以我需要想办法来将 GUI 工具和 TUI 工具流畅的衔接起来，减少代码开发时的频繁切换产生的割裂感！

多屏协作

如上图，我有 3 个显示器，我的构想是这样的：

1. MacBook 内置显示器 —— 常驻两个空间：一个用来打开浏览器，还有 VPN、网易云音乐、Finder 软件，用来承接各种临时的操作。一个用来打开飞书，用来沟通、协作。

2. 中间主屏 —— 常驻两个空间：一个用来打开浏览器，用来做各种【输出】。一个用来打开 IDE，专注于写代码、看代码，用标签页打开多个 Project。

3. 左边竖屏 —— 常驻两个空间：一个用来打开浏览器，用于看文档、查资料等各种【输入】。一个用来打开 TUI 工具，进行辅助编程！

GUI/TUI衔接

现在问题来了，我希望我的开发工作的【主轴】是 IDE，流程的起点是 IDE。但是我的 IDE 在中间屏幕，终端在左边屏幕，它俩是独立软件，没法协作、自动跟随切换 Project 的工作目录。我希望有个【自动化流程】，当我在 IDE 里切换项目的时候，CC 自动跟随切换！

衔接流程

我期待的流程是这样的：

因为某个原因，我在 IDE 里打开了一个项目 A → 准备写代码了，点击 IDE 里的某个【按钮】，左边屏幕自动【新建】一个项目 A 的 CC 会话终端并激活到前台显示  → 我跟左边的 CC 对话，让他干活 → 我在中间的 IDE 里评审、调试、诊断 → 因为某些原因我又要在 IDE 打开一个别的项目 B → 我再次点击那个【按钮】，左边屏幕自动【新建】一个项目 B 的 CC 会话终端并激活到前台显示 → 我在 IDE 里又切回了项目 A，我又点击了那个【按钮】，左边屏幕自动【切换】到 A 的 CC 会话终端并激活到前台显示。

好的想法已经有了，AI 时代就怕你没有想法，有想法就一定有办法实现！

代码实现

1. macOS 上的原生软件，大部分支持 AppleScript 自动化，也就是说我们可以写脚本驱动软件的行为、模拟人机交互，比如打开软件、新建 tab、点击按钮等。

2. JetBrains IDE 支持集成外部命令，也就是说：可以在 IDE 里点击一个按钮，自动执行一个 Shell 脚本或者别的可执行文件。

产品需求清晰了，接下来开始让 AI 干活！一顿沟通和调试之后，我们有了一个【自动化】创建 iTerm2 新标签的可执行脚本！

这是给大模型的需求提示词，大家可以按需选用，做个性化的调整：

## 📌 工具功能说明
请帮我创建一个 macOS 上的 iTerm2 自动化工具,主要功能包括:
### 核心需求
1. **智能窗口管理**:自动使用或创建 iTerm2 窗口
2. **项目标签管理**:为每个项目目录维护独立的标签页,支持标签复用
3. **三面板布局**:自动创建固定的三面板布局(上方一个全宽面板,下方两个并排面板)
4. **命令自动执行**:在每个面板中自动切换到项目目录并执行预定义的命令
### 使用场景
```bash
# 基本用法:在当前目录打开
./open-claude-in-iterm.sh
# 指定项目目录
./open-claude-in-iterm.sh /path/to/project
```
---
## 🎯 技术架构要求
### 技术栈
- **Shell 脚本** (open-claude-in-iterm.sh):参数处理、路径规范化、日志管理
- **AppleScript** (open-claude-in-iterm.applescript):iTerm2 自动化核心逻辑
- **依赖**:macOS、iTerm2、Bash
---
## 📋 详细功能规格
### 1. Shell 脚本 (open-claude-in-iterm.sh)
#### 参数处理
- **参数1**:项目目录(可选,默认当前目录)
- **自动处理**:相对路径转绝对路径
#### 面板命令配置
```bash
PAN1_CMD="claude"     # 上方面板命令
PAN2_CMD="claude"     # 左下面板命令
PAN3_CMD="claude"     # 右下面板命令
```
### 2. AppleScript (open-claude-in-iterm.applescript)
#### 主要流程
**步骤1:窗口管理**
- 检查 iTerm2 是否运行(未运行则自动启动)
- 使用当前激活的 iTerm2 窗口,如果没有则创建新窗口
**步骤2:标签管理(关键逻辑)**
- 在找到的窗口中,查找 `session.path` 变量等于项目目录的标签
- **复用逻辑**:如果找到现有标签 且 窗口不是新创建的 → 直接切换标签并返回
- **创建逻辑**:如果未找到标签 或 窗口是新创建的 → 创建新标签和布局
**步骤3:三面板布局创建**
```
布局示意图:
┌─────────────────────────┐
│   上方面板 (全宽)         │
│   执行: PAN1_CMD         │
├──────────────┬──────────┤
│  左下面板    │  右下面板 │
│  PAN2_CMD   │  PAN3_CMD │
└──────────────┴──────────┘
```
**分割顺序(重要)**:
1. 初始状态:一个全屏 session(上方面板)
2. 第一次分割:对上方 session 执行**水平分割**,创建下方面板
3. 第二次分割:对下方 session 执行**垂直分割**,创建右下面板
**步骤4:命令执行**
在每个面板中依次执行:
1. 切换到项目目录:`cd "/path/to/project"`
2. 清屏:`clear`
3. 等待 0.3 秒(确保目录切换完成)
4. 执行命令:`PAN_CMD`
5. 等待 0.5 秒(确保命令启动)
## ⚠️ 常见错误
- ❌ 符号链接未处理,导致找不到 AppleScript 文件
- ❌ 分割顺序错误,导致布局不正确
- ❌ 缺少 delay,导致命令执行失败或在错误目录执行
- ❌ 新窗口处理错误,导致多余空白标签
- ❌ 标签复用逻辑错误,导致同一项目创建多个标签
- ❌ 路径未引用,导致包含空格的路径失败

IDE配置

创建外部工具

添加到工具栏

使用效果

点击工具栏按钮后，自动在全屏的 iTerm2 窗口新建或激活项目目录下的 CC 会话，下图里就是 3 个项目。

四、多Agent协作

会的越多，让你干的就越多。既然 AI 那么牛，一个 CC 会话已经满足不了我膨胀的想法和需求了。我希望我可以同时支配多个 AI 开发工程师，而我变成 PM！所以参考酒米的思路，我给每个项目的终端，自动化的划分了 3 个子窗口，每个子窗口都是一个 CC 会话。效果大概这样：

主从架构

每个项目自动打开 3 个常驻的 AI 会话，我设想的工作流是这样的：

【架构师】上面的大屏，用贵的模型！专门用来跟我聊需求、对方案、产出任务列表。

【开发者】下面的两个小屏，用领域特定的模型，专门用来落地大屏架构师产出的方案和任务。比如前端需求用前端效果好的模型，后端需求用后端效果好的模型。

知人善用才是好 PM！这个模式也很匹配现实中的组织架构和成本取舍，现实中每个需求一般也都是由一个架构师和多个中高级开发者来协作完成！感谢热心市民无声雨，给我们小组共享了自己采购的纯血 Claude 模型，所以目前我用 Claude 模型来对方案，用 GLM 或者 MiniMax 来实施方案！

规范驱动开发(SDD)

主从智能体的协作很重要，我跟【架构师】聊了半天确定的方案和设计，需要有一个清晰的、对大模型友好的方案和任务文档作为【开发者】的输入。这就很巧，刚好最近在流行 SDD，规范驱动开发。大致就是模拟现实中的软件开发流程将开发生命周期拆分为 3 个阶段：

• 【proposal】需求对齐、方案设计、【任务细化】；
• 【apply】开发任务实施；
• 【archive】功能验收、文档沉淀

围绕这个流程，开源社区设计和研发了一系列对大模型非常友好的工具和提示词（比如 OpenSpec），【阶段 1】和【阶段 2】中间通过格式设计良好的【设计文档和任务文档】来进行上下文交接。

也就是说，我可以在上述的 3 窗口环境中，按照 SDD 流程来：【proposal】跟【架构师】交互，对齐需求、设计和任务 A → 【apply】让【开发者 1】着手完成任务 A → 【proposal】继续跟【架构师】交互，对齐需求、设计和任务 B → 【apply】让【开发者 2】着手完成任务 B → 【proposal】继续跟【架构师】交互，对齐需求、设计和任务 C → 【apply】让【开发者 1】着手完成任务 C → ……

五、CC拓展

CC 当然很厉害，但它本质上也就是一个朴素的 ReAct 模式智能体。

ReAct 这么火，大家肯定也都耳熟能详了，我们也就不说太多。当然 CC 团队围绕编程这个课题做了很多细致的提示词调优和内置工作流设计，这个我们黑盒的用就好了，也没必要关注太多。我们最需要关注的，是 CC 提供给我们使用者的【拓展点】，那些允许我们个性化设置的东西。

命令(command)

命令的本质就是预定义的提示词模板。目的是为了省事，不用每次都重复的输入类似的提示词。比如想让 CC 帮我提交代码，每次我们可能都要交代一大堆字，比如：

请调用 git diff --cached 获取当前暂存区的代码变动。
忽略所有的 node_modules 或二进制文件。
基于变动内容，判断这是一个 feat (新功能), fix (修复) 还是 chore (杂务)。
生成一个不超过 50 字符的标题，并在正文详细列出影响的文件。
由我确认后执行 git commit。”

就像写代码的时候将重复代码提取为一个独立方法一样，我们可以把这些可以复用的提示词固定成一个【命令】，后续使用的时候，直接输入命令名字就好。斜杠命令是一段提示词的快捷方式。

技能(skill)

技能和命令最大的差别就是：命令是用户主动提交的提示词，而技能是 Agent 自己决策后自动导入的提示词。当然技能包里除了提示词，一般还会携带一些配套的工具、脚本、命令或者文档。

比如，我安装了一个【html 转 pdf 的技能包】，这只能提示 CC 可以使用这个技能，但是具体用不用、什么时候用、怎么用都是 CC 自己规划、决策的。

子代理(subAgent)

SubAgents 是可以并行处理任务的独立 AI 代理，每个子代理拥有独立的上下文窗口，可以分配不同任务以提高效率。【主代理】的上下文窗口中包含有【子代理】的【简短】描述信息，可以基于这个描述信息规划、决策使用哪个子代理。

{
  "agents":{
    "code-reviewer":{
      "description":"专门负责代码审查的子代理",
      "model":"claude-opus-4-5",
      "instructions":"你是一个专业的代码审查专家,专注于检查代码质量、安全漏洞和性能问题。",
      "tools":["read","search","git"],
      "permissions":{
        "allowWrite":false
      }
    },
    "test-writer":{
      "description":"专门负责编写测试的子代理",
      "model":"claude-sonnet-4-5",
      "instructions":"你是一个测试工程师,专注于编写全面的单元测试和集成测试。",
      "tools":["read","write","bash"]
    },
    "doc-generator":{
      "description":"专门负责生成文档的子代理",
      "model":"claude-sonnet-4-5",
      "instructions":"你是一个技术文档专家,专注于生成清晰、准确的技术文档。",
      "tools":["read","write"]
    }
  }
}

独立上下文窗口的好处是：避免上下文污染和占用。比如我要在代码里找一个接口的所有实现类，这个就很适合子代理来做。主代理只需要交代给子代理接口名，然后就等子代理返回实现类列表。

这样在主代理的上下文窗口里，只会有子代理的输入和输出（几个类文件路径），而子代理在搜索过程中遍历文件、目录、读取文件内容产生的临时 token，不会对主代理产生影响。我目前认为 SubAgent 和 Skill 差不太多。不过我不确认 Skill 是不是在独立的上下文中执行。

MCP

MCP 和技能一样，都是由 CC 自主规划、决策使用的。差别有两个：

1. MCP 工具的说明信息占用的上下文太多了！不管是否被使用，每次都需要一口气提交所有工具的完整元信息（使用说明 + 出入参 Schema）供大模型规划、决策，占用大量上下文。而【技能】选择了【渐进式披露】，先向大模型提供少量关键信息，只有在大模型选择了使用技能时，才告诉大模型更多关于技能的补充说明信息，让大模型进一步推理、决策。

2. MCP 工具更多的偏向【远程 RPC】，基于网络来实现原子化的远程能力调用。而【技能】更多的偏向【本地 IPC】，具体能力更多通过【编排】本地脚本、本地命令来实现，有点像 stdio 模式下的 MCP。

钩子(hook)

hook 是在特定事件触发时自动执行的脚本，用于自定义工作流、拦截危险操作、自动格式化代码等。就类似 Linux NetFilter，CC 在很多地方植入了流程执行的劫持点，将流程上下文交给用户开发的脚本或者命令。

插件(plugin)

plugin 就是上述各种拓展打包、分发、安装的一种格式。你可以把它想象成 npm 包、pip 包、apk 包等我们比较熟悉的概念。然后我们可以按流程和格式建设插件市场，类似 pip-index、npm-index 等。

我没有细看流程和格式，但是大概也就是一个特定文件布局的 zip 文件包，里面有插件描述信息和各类拓展，比如可以包含：

• 5 个 Skills；
• 10 个斜杠命令；
• 3 个 MCP 服务器配置；
• 2 个 SubAgent 定义；
• 若干 Hooks。

六、CC技巧

飞书MCP

飞书官方提供了 MCP，我主要用它来读写飞书文档，蛮好用的，大家可以试试。比如我每周都要在固定目录下创建固定标题格式的【系统巡检文档】，所以我借助飞书 MCP 整了个自定义 Command 帮我自动创建这些文档去除重复劳动，感觉真香！之前每次都要手动建 3 个文档、选目录、改名字！

@模糊搜索

有时候我们需要精确的告诉 CC，哪个文件需要读或者改，其实不用从 IDE 里复制文件路径，直接在终端里模糊搜索就好了。

WebFetch

CC 默认集成了 WebFetch 命令，就是指定 URL 读取网页内容，这个理论上就是一个本地执行的 curl 命令，没有云端成本，不需要云端协作。但是有个问题：（一）CC 在访问地址之前，会先调用 anthropic.com 的一个风控接口，判断这个网络地址是否有安全风险。（二）政策原因，anthropic.com 会拒绝所有来自中国大陆、香港的请求，风控接口返回 404 或者其他。（三）风控不通过，WebFetch 失败。

在 ~/.claude/settings.json 中添加如下配置，禁用 WebFetch 工具前置的风控检查就好了。

{
  "skipWebFetchPreflight":true,
}

详见：linux.do/t/topic/114…

WebSearch

WebSearch 是需要云端协作的，需要有个搜索引擎服务提供能力。因为我们没有用官方的付费订阅，所以默认的 WebSearch 工具我们用不了，调用 WebSearch 工具得到的结果都是 0。

办法是去找一个免费或者收费的 MCP 服务。免费的我看大家都推荐 Brave<brave.com>，大家也可以找找别的。收费的也有很多，我看智谱的套餐里限量提供了 <联网搜索 MCP - 智谱 AI 开放文档>。也有很多按量付费的，大概几分钱一次，有需要的可以找找。

添加了 MCP 搜索工具后，建议禁用 CC 自带的 WebSearch 工具，不然每次跟大模型交互时，工具信息还会带给大模型，产生额外的 token 开销和推理误判。在 ~/.claude/settings.json 中添加如下配置：

{
  "permissions":{
    "deny":[
      "WebSearch"
    ]
  }
}

iTerm2通知

终端上的任务需要我们输入的时候，可以配置下，让 iTerm2 发出声音和通知。这样我们就不会因为忘记确认操作而阻塞进度。

详见：Optimize your terminal setup - Claude Code Docs

清空上下文

因为我们每个项目都复用一屏内的 3 个子窗口，一般不会重开。为了避免上下文溢出或者之前对话对新任务产生干扰，当我们完成一个任务时，需要及时的执行 /clear 命令，清空上下文，从 0 开始新对话。

如果任务没有完成，但是又不得不 clear，那么可以维护一个自定义命令，在 clear 后提示大模型根据 git status 看到的文件变更快速找回上下文。把 git 状态当作 AI 的 “短期记忆快照”，/clear 只清上下文，不清工作进度。

# Context Catch-up
当前对话已被 `/clear`，请通过 git 状态恢复上下文。
使用方式：
1. 阅读 `git status`（必要时结合 `git diff`）
2. 仅基于文件变更推断正在进行的任务
3. 延续现有实现思路，不要假设额外背景
4. 在未收到明确指令前，先给出你对当前上下文的判断
目标：
- 快速找回任务状态
- 避免旧对话或错误假设干扰新任务

注意力哨兵

在记忆文件里要求大模型扮演一个特别的角色，如果聊着聊着角色行为丢失了，说明大模型注意力失焦了，已经丢掉了你最开始的要求。这时候就该 clear 一下重开会话了。

拓展市场

为了便于相关个性化拓展物料的分发、便于大家搜索、安装，市面上已经有了相关的分发平台和便捷安装命令了。

1. skills.sh

2. www.aitmpl.com

状态行个性化

状态行显示在 Claude Code 会话界面底部，可以自定义显示的内容，比如git分支名、目录名、模型名等。推荐使github开源项目：claude-code-statusline-pro-aicodeditor，效果如下：

详见：github.com/HorizonWing…

七、总结

差生文具多，尽管我暂时还没有使用 CC 产出啥说得上来的东西，但是确实花了很多时间琢磨怎么让它用起来更顺手。一些不成熟的想法，希望可以给到大家启发。

参考：

1. www.ginonotes.com/posts/how-i…
2. www.cnblogs.com/knqiufan/p/…

往期回顾

1.AI编程能力边界探索：基于 Claude Code 的 Spec Coding 项目实战｜得物技术

2.搜索 C++ 引擎回归能力建设：从自测到工程化准出｜得物技术 

3.得物社区搜推公式融合调参框架-加乘树3.0实战

4.深入剖析Spark UI界面：参数与界面详解|得物技术

5.Sentinel Java客户端限流原理解析｜得物技术

文 /羊羽

关注得物技术，每周更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。

一、前言

10 天，2.5 万行代码，提效 36%。 基于 Claude Code 的 Spec Coding（规格驱动编码） 深度实战。通过 2,754 次工具调用，我们不仅完成了从 0 到 1 的前端项目搭建，更在“约束+示范+视觉”的三层规范体系下，摸清了 AI 编程的真实能力边界。本文将复盘这场实战，拆解如何用结构化工作流消除 AI 的不确定性，重构开发者的核心竞争力。

二、Spec Coding

什么是 Spec Coding 工作流

众所周知，Spec Coding（规格驱动编码）的核心思想是：在写代码之前，先写规格文档。通过 openspec 工具，每个功能变更都经历以下阶段：

Spec 工作流的实际价值

减少返工： 在 proposal 阶段明确为什么以及怎么做，避免实现完才发现方向不对。适合复杂功能： 对于需要跨多个文件多个层次的功能，tasks 分组让 AI 聚焦在当前步骤。可审计： 每个 Change 的完整决策链（proposal→design→specs→tasks）都留有记录，方便回溯。

三、项目是什么

一个标准企业级中后台搭建，包括表格、表单、卡片列表、数据看板等中后台常见核心功能，项目从零搭建到完成以下全部功能，全程使用 Claude Code 辅助开发。

四、数据概览

在这次使用Claude Code 做 Spec Coding的从0到1项目探索中，我们积累了一份完整的原始数据，以下所有数字均来自Claude Code对 109 个 .jsonl 会话文件的整体数据统计：

2,754 次工具调用的分布揭示了 AI 的"工作方式"， AI 自主完成的 738 次文件读取、550 次代码编辑、662 次终端命令执行，以及 208 次任务进度标记——几乎覆盖了一个研发日常工作的全部动作类型。

五、开发时间线：10 天的演进过程

阶段一：设计阶段

在动工之前，我们完成了产品方向的确认和 UI 设计稿、产品PRD的输出。过程主要使用 Cursor + 设计规范 Rules，直接从概念沟通到生成高保真 UI 稿（HTML文件），再生成标准的 PRD 需求描述，覆盖系统所有核心页面。这一阶段的产出是一套可直接用于开发对齐的视觉参考，也是后续 AI 生成代码时的重要上下文来源。

阶段二：项目搭建（2个工作日，20 条指令）

此阶段我们以问答式交互为主，聚焦于项目基础设施的搭建和简单需求的尝试。我们向 AI 提出架构问题，由 AI 给出方案，我们决策后执行。在这个过程中，AI 帮助我们熟悉技术栈、搭建项目结构、配置开发环境，并完成了第一个核心列表页面的开发，成功打通了前后端的数据链路。

阶段三：功能开发（4个工作日，89 条指令）

这是整个项目开发强度最高的阶段，我们引入了“规格驱动编码”（Spec Coding）的工作流，约 80% 的功能代码在此阶段完成。我们不再是简单地给 AI 下达指令，而是先与 AI 共同定义清晰的功能规格（Specification），然后 AI 基于这份“蓝图”自主进行编码。通过这种方式，我们高效地完成了包括授权管理、数据分析看板、文档树状结构等多个复杂功能的开发。

阶段四：细节打磨与生产部署（4个工作日，108 条指令）

最后阶段的工作重心转向功能迭代、系统重构和生产环境的部署排障。我们与 AI 一起，对已有功能进行了多轮优化，例如完善了核心业务流程、重构了侧边栏导航、修复了登录跳转逻辑等。同时，我们也对项目首页进行了深度的代码重构，解决了前期快速迭代中积累的技术债。最后，在部署阶段，我们遇到了复杂的构建问题，通过与 AI 的多轮分析和尝试，最终定位并解决了问题，成功将应用部署上线。

六、典型案例

案例一：AI 驱动产品设计

没有产品经理、没有 UI 设计师，一个工程师如何用 AI 独立完成从产品定义到高保真原型、再到研发文档的全流程。

背景：

传统意义上，从 0 到 1 开发一个企业级知识问答平台需要三个角色：产品经理（需求分析 + 用户路径 + PRD）、UI 设计师（交互稿 + 高保真设计稿）、工程师（编码实现）。这个项目设计过程中，通过让 AI 在不同阶段扮演不同角色，覆盖了全部三个职责。

让 AI 扮演产品经理：

在 Rules 中植入「首席产品专家」Persona 提示词，将 AI 从工程师的「急于执行」模式切换为产品经理的「先想清楚」模式，与 AI 聊清楚我们想干什么。

让 AI 扮演 UI 设计师：

在 Rules 中定义设计规范，通过对话式生成逐页产出高保真 HTML 文件，而不是源码：

让 AI 生成研发可读的 PRD：

基于产品经理角色，将 HTML 设计稿作为上下文，最后生成精确到组件行为级别的 PRD：

案例二：SDD 驱动前端功能研发

在已有系统上增量交付一个完整功能模块，SDD 如何保证「增量」功能快速开发，并系统性提升前后端联调效率。比如其中有个SSD需求开发「定时任务管理」完整模块，并且对接 6 个后端接口。这是 SDD 工作流第一次被完整运用于新功能模块开发，也是验证「SDD + MCP」前后端联调提效的关键场景。

页面功能开发： opsx:new 到 archive，人工指令 < 10 条，AI代码占比100%，交付完整任务管理模块（独立路由 + 完整 CRUD + 执行记录 + 检索结果）。

前后端联调： SDD + MCP 的联调路径：接口 URL → MCP直连文档 → 一次性获取字段、枚举、必填项 →  接口文件一次生成 → ****联调一次通过，6 个接口零联调返工。

研发效率： 同日额外交付了两个完整模块，3个独立完整模块，单日全部开发完成，按纯人工开发，当天人效提升3倍。

案例三：SDD 驱动系统重构

重构与新功能的根本差异：

新功能开发是「从无到有」：AI 可以大胆生成，错了删掉重来。重构是「在活体系统上动手术」：这种高风险对 AI 执行提出了截然不同的要求——不仅要知道改什么，更要知道不能改什么，以及按什么顺序改。 SDD 的价值正在于此：在动代码之前，把这三件事全部写清楚。

知识问答首页重构：

架构债务： 大量首页业务组件与公共组件混放、useChat 导出 20+ 方法（4 种无关职责混合）、ChatInterface 接收 17 个 props（参数3 层传递）。

执行TASKS： 9 组 34 个子任务，从「grep 确认组件当前归属」→「按新分层迁移」→「更新所有 import 路径」→「tsc 类型检查」→「冒烟验证」，每一步有明确输入和验收标准。

执行结果： 34个任务全部完成（含 4 个验证任务），AI 全程独立执行，人工干预 < 5 条指令。7个业务组件与公共组件完成解耦，useChat 拆为 3 个单职责 hook，ChatInterface 从 17 个 props 缩减至 6-8 个。

案例四：复杂问题排障

并不是所有编程相关的问题AI都可以解决，哪类工程问题从结构上超出了 AI 的能力边界？这里举一个遇到的场景。

其中有一天遇到一个测试环境构建失败的问题，结果过程约 4 小时，7 个会话、15+ 次方案尝试、59 条指令。整个项目单日指令最多的一天，也是 AI 独立解决能力最受限的一天。

这一天有一个值得注意的特征：AI 每次分析都是正确的——问题不在于 AI 的分析能力不足，而在于问题的结构性特征超出了 AI 的信息范围和反馈机制：

• 云服务器构建时发生，本地无法复现： 每次验证方案必须提交代码等待 CI（一轮约 10 分钟），AI 分析的是日志截图，无法感知「现在的 CI 环境还有哪些隐性配置」。

• 多根因互相掩盖，解决一层才暴露下一层： AI 每次分析都正确，但正确分析的只是当前暴露的那一层，问题全貌无法被单次分析覆盖。

• 隐性行为无文档，根因藏在依赖源码内部： Prisma postinstall 境外下载没有任何显式错误，引导AI 不得不深入阅读 node_modules 源码第 2319 行才能发现根因。这类「运行时行为藏在依赖内部、没有文档描述」的问题，超出了 AI 通过训练数据或当前上下文主动推断的范围。

最后确认的原因：

• .npmrc 历史副作用： 早期为跳过 @next/swc-darwin-arm64 在 Linux 下载而加入的 omit=optional，无意间也跳过了 @tailwindcss/oxide-linux-x64-gnu（Tailwind v4 的 native binding），postinstall 陷入循环等待
• Prisma v6 境外下载沉默卡死： AI 需要阅读 node_modules/@prisma/fetch-engine/dist/index.js 第 2319 行才能发现这个行为——postinstall 不报错、不超时，只是无限等待。
• pnpm 跨平台 lockfile 不一致： macOS arm64 生成的 lockfile 不含 Linux x64 的 native package；切回 npm 则 lockfile 被忽略，安装结果每次不同。

最终解法（4 小时探索后得出）：

• 锁定 tailwindcss@4.1.11，配置
• PRISMA_ENGINES_MIRROR=registry.npmmirror.com/-/binary/pr…
• 统一使用 pnpm，CI 命令同步更新，删除 .npmrc 中的 omit=optional。

七、代码规范落地：CLAUDE.md 和 Rules 的实际效果

规范体系设计思想：三层结构

本项目的规范体系是三个层次的协同约束， 每层解决不同的问题：

第一层：约束层（.claude/rules/）      ← 告诉 AI「禁止什么、必须怎样」
第二层：示范层（.claude/code-design/）← 告诉 AI「标准产出长什么样」
第三层：视觉层（.claude/ui-design/）  ← 告诉 AI「页面应该长什么样」

为什么需要三层？

只有「约束层」时，AI 知道规则但缺乏参考实现，容易在复杂场景下产生符合规则但不符合团队风格的代码。加入「示范层」和「视觉层」后，AI 可以直接对齐团队的标准产出，减少「虽然合法但不地道」的代码。

第一层：约束层（.claude/rules/）

7 个规范文件，分别约束不同维度：

.claude/rules/
├── ts.md          # TypeScript 规范（禁止 any、使用可选链等）
├── code-names.md  # 命名规范（kebab-case/camelCase/PascalCase）
├── comment.md     # 注释规范（JSDoc、@ai-context/@ai-rules 文件头）
├── lint.md        # 代码风格（单引号、文件末尾换行）
├── style.md       # 样式规范（Tailwind CSS、less 文件）
├── pages.md       # 页面目录结构规范（constants/services/hooks/components 分层）
└── service.md     # API 接口生成规范（fetch{Name}Api 命名、UniversalResp 泛型）

第二层：示范层（.claude/code-design/）

将项目常见场景预置完整的「标准模板代码」，AI 在生成新页面时可以直接参照，后续可以切换为skills：

.claude/code-design/
├── pro-table/          # 通用列表页模板（含搜索、分页、批量操作、行操作）
├── pro-form/           # 通用表单页模板（含创建/编辑双模式、字段验证）
├── editable-pro-table/ # 可编辑表格模板（含行内编辑、添加/保存/删除）
├── drawer/             # 抽屉组件模板（含标准打开/关闭逻辑）
├── compontent/         # 通用组件模板（含 README、Props 定义、使用示例）
└── utils/              # 工具函数模板

示范代码的作用不只是「看个格式」。以 pro-table 为例，当开发者让 AI「参考 .claude/code-design/pro-table 生成知识治理列表页」时，AI 直接继承了这套模式，一次就能生成符合团队风格的代码，无需多轮调整。

第三层：视觉层（.claude/ui-design/）

注意存放 HTML 设计稿，覆盖主要页面的视觉参考：

.claude/ui-design/
├── knowledge-spaces.html  # 知识空间列表页设计稿
├── search-strategy.html   # 检索配置页设计稿
├── space-detail.html      # 空间详情页设计稿
└── xxx设计稿

这些 HTML 文件可以直接在浏览器中打开预览，AI 也可以读取其中的结构和样式信息。实践中，提供 HTML 设计稿后，AI 生成的 UI 与设计意图的吻合度明显高于纯文字描述，尤其是布局结构、颜色方案、间距配置等细节。

规范约束的实际效果

正面效果（规范被遵循的案例）：

• 接口命名一致性： 所有接口函数均以 fetch{Name}Api 命名，类型以 I{Name}Req/Res 格式，整个项目 205 个文件保持高度一致。
• 目录分层被遵守： constants/、services/、hooks/、components/ 分层在每个新页面中都被正确创建。
• 代码模板被继承： CURD页面均参照了 pro-table 模板的 hooks 分离方式，代码结构高度一致。
• 使用可选链： 几乎所有数据访问都使用了 ?. 和 ??，有效避免运行时报错。

需要人工干预的案例：

• 2/24，AI 生成知识空间列表后，将所有代码写在单文件中，未按规范分层。通过一条追问后，AI 重构为正确结构。
• 2/27，AI 错误地使用了 .less 后缀，但项目实际配置使用 SCSS，在收到错误提示后立即修正。
• 出现 antd v5 废弃 API（destroyOnClose、dropdownStyle），AI 习惯于使用训练数据中更常见的旧 API，需要通过报警信息触发修正。

结论：

规范体系对 AI 的约束是有效的，但规范文件只是「约束」而非「能力」——只有「约束层」时，AI 知道不能做什么，但遇到复杂场景仍可能生成不够地道的代码；加入「示范层」和「视觉层」后，AI 有了对齐的锚点，输出质量和一致性明显提升。

八、MCP 工具：消除信息断层

在 AI 辅助前端开发中，有两类高频信息断层，在此项目中进行了接入：

接口文档断层： 接口文档在 API平台，AI 无法直接访问，只能靠用户手工复制字段，容易遗漏、版本不一致。需求文档断层： PRD、设计文档存在飞书云文档中，每次引用都需要用户打开→复制→粘贴到对话框，打断思路。

MCP 一：接口文档直连

通过该工具，AI 可以根据接口 URL 自动拉取完整接口文档——包括入参字段、出参结构、枚举值定义、必填项标注。累计被调用了 21 次，完成39个接口联调 ，覆盖了几乎所有接口的初次接入和更新迭代场景。服务端接口未生效之前，并且支持同步生成mock数据，减少后端依赖。interface.ts 类型定义质量非常高，字段注释完整，无需人工校对。

MCP 二：飞书云文档直读

通过该MCP工具，AI 可以直接读取飞书云文档的内容（PRD、设计说明、技术文档等），无需用户手工打开→复制→粘贴。

典型应用场景：

九、AI Spec Coding 经验总结

重新理解「AI 辅助编程」是什么

流行的说法是「AI 是你的 Copilot」。这个比喻在日常补全层面成立，但在 Spec Coding 实践之后，我更倾向于另一个模型：AI 是一个极度服从、无限耐心、但没有内部业务知识常识的「顶级执行者 」。

这个比喻捕捉了三个关键特征：

极度服从： AI 会一字不差地执行你写的规范，不会主动质疑「这样做合理吗」。这是优势，也是风险——规范写得越准确，执行越可靠；规范有歧义，AI 会选一个「看起来合理」的解释，而不是停下来问你。

无限耐心： 34 个任务的重构、9 组联调任务、跨会话的上下文恢复——这些在人类身上需要消耗大量意志力的事情，AI 做起来没有摩擦成本。本项目 208 次 TodoWrite 调用背后，是 AI 持续更新进度状态、从不嫌烦的特性。

没有内部业务常识： AI 不知道你们公司的部署环境是什么样的，不知道这个接口上周刚换过版本，不知道「这个交互做成这样用户会抱怨」。它只知道你告诉它的。这也是 3/4 生产构建排障花了大量时间的根本原因。

AI 的能力边界在哪里

从 10 天、2,754 次工具调用中，我们归纳出一个更精确的能力边界框架，而不是简单的「能做/不能做」：

真实项目中的并不是所有的需求都值得写一份 Spec。在真实的项目迭代中，我们需要根据需求颗粒度来选择协作模式。

小颗粒需求：对话框即扫即改

• 场景：改个文案、修个显隐逻辑、调整 CSS 间距。
• 策略：直接在 Cursor Chat  中对话。
• 理由：沟通成本低于编写规范的成本，AI 的即时反馈效率最高。

中颗粒标准化需求：基于Rules 或者 Skills 预设规范生成

• 场景：增加一个标准的 CRUD 页面、创建一个简单的业务组件。
• 策略：利用预设的 Cursor Rules 或 Skills（如 pro-table.mdc）。
• 理由：这类需求有强烈的“模式感”。只要规则定义清晰（如“执行流程：识别场景 -> 读取示例 -> 生成类型 -> 完成 UI”），AI 就能基于标准化模板高质量输出。

中大颗粒复杂功能：OpenSpec 深度协作

• 场景：重构核心逻辑、新增带有复杂业务逻辑的模块、无参考代码的新功能。
• 策略：OpenSpec 标准流 (SDD)。
• 理由：业务逻辑复杂时，AI 极易产生幻觉或需求偏移。通过 Spec 强制进行“先设计后编码”，可以确保 AI 的每一步都在既定轨道上，且 Spec 记录了设计的决策过程，对于后期维护价值巨大。

AI 失效的三种模式

经过本项目的实践，AI Coding 的失效不是随机的，而是可归类的：

模式一：规范真空

任务涉及的领域没有规范约束，AI 自行填充「合理默认值」。

• 表现：生成的代码功能正确，但风格/结构偏离团队约定。
• 发生频率：高（尤其在新功能开发初期）。
• 应对：在 CLAUDE.md 或 code-design 中补充对应规范，一次修复，全局生效。

模式二：信息孤岛

AI 掌握的信息是当前会话的快照，看不到系统外的状态。

• 表现：本地正常，CI 失败；AI 分析每次都对，但解的都是当前暴露的问题。
• 发生频率：低，但代价高。
• 应对：跨平台、跨环境的依赖要在架构设计阶段提前锁定；环境差异要写成规范前置处理。

模式三：任务目标模糊

AI 把「该问人的问题」当成「执行问题」来解决。

• 表现：用户说「优化一下首页」，AI 悄悄改了组件结构，而不是先澄清目标。
• 发生频率：中。
• 应对：Spec 工作流的 proposal 阶段强制要求先描述「Why」，避免 AI 自行填充目标。

开发者角色的重构

AI Coding 不是让开发者「消失」，而是让开发者的工作向上迁移：

这意味着：

规范设计能力成为 AI 时代开发者的核心竞争力——能写出让 AI 可靠执行的规范，价值比能写出同等功能代码更高。

系统性思维变得更重要——生产构建问题的排障经历说明，AI 可以帮你解决每一个局部问题，但无法帮你看到真实业务全局。

质量意识前移——过去 Code Review 在代码写完后进行，现在需要在 方案设计/任务执行 阶段就介入，而不是等 AI 执行完再纠错。

值得期待的方向

基于本项目的数据和经验，后续在以下方向可作深入探索：

规范体系的结构化积累： 每次踩坑后补充到 CLAUDE.md/rules，形成团队共享的「AI 执行约束库」。目前 7 条规范文件是手动维护的，下一步可以建立「踩坑→提炼规范→自动追加」的闭环。

MCP 工具链的纵向延伸： 本项目 MCP 仅覆盖了接口文档、飞书文档。后续针对设计稿、测试用例、发布平台、日志平台接入，可以进一步形成完整的AI Coding链路。

多 Agent 并行开发： 本项目开发过程中，发现大型任务执行等待时间较长，下一步可以尝试多Agen并发生成，同时开发不同功能模块。

一句话总结

AI Coding 的本质不仅仅是用 AI 写代码，而是用结构化的规范和工作流把不确定性消除在执行之前——AI 负责在确定性空间里高速执行，人负责维护和扩展那个确定性空间的边界。

10 天、217 条指令、2,754 次工具调用、25,546 行净增代码——这个数字背后，是一套让 AI 可以「看见」、「理解」、「遵守」团队约定的规范体系。规范是杠杆，AI 是力，Spec 工作流是支点。

本报告由claude code基于claude code 109 个真实历史会话、2,754 次工具调用记录生成，人工补充并校准，数据来源：~/.claude/projects/-Users-admin-Desktop-code-knowledge-qa/。

往期回顾

1.搜索 C++ 引擎回归能力建设：从自测到工程化准出｜得物技术

2.得物社区搜推公式融合调参框架-加乘树3.0实战 

3.深入剖析Spark UI界面：参数与界面详解|得物技术

4.Sentinel Java客户端限流原理解析｜得物技术

5.社区推荐重排技术：双阶段框架的实践与演进｜得物技术

文 /阳凯

关注得物技术，每周更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。