「拍拍·谛听」（PaiPai DiTing）是面向拍拍二手与循环业务近 100 个微服务的核心业务知识平台。系统秉持“以代码为信源，洞鉴全域业务；以「拍拍·谛听」灵耳，通晓百级微服务”的核心准则，通过深入解析 100 多个 Java 微服务的源代码、中间件契约与环境配置，逆向推导并结构化沉淀业务领域知识，并在日常产品与研发进行需求定界、存量逻辑冲突排查、跨服务影响面评估与技术方案生成时提供端到端智能辅助。

flowchart TB
    subgraph IN ["【第一块 · 输入源】近 100 个核心微服务工程全息资产接入"]
        direction LR
        S1["<b>[JSF / RPC 契约]</b><br/>接口契约 · 方法签名 · 泛型求解"]
        S2["<b>[JMQ 消息拓扑]</b><br/>广播/顺序 Topic · 事务监听与重试"]
        S3["<b>[MyBatis / JED]</b><br/>1024 水平分表规则 · JimDB 缓存映射"]
        S4["<b>[Ducc 动态配置]</b><br/>业务动态开关 · 灰度白名单规则"]
        S1 ~~~ S2 ~~~ S3 ~~~ S4
    end

    subgraph KB ["【第二块 · 核心层】拍拍·谛听 四层全息业务知识金字塔 (自底向上蒸馏)"]
        direction BT
        L1["<b>【L1 事实底座】</b> 编译级 AST 语法树 IR · 跨模块符号求解 · 确定性物理调用拓扑"]
        L2["<b>【L2 业务卡片】</b> 接口业务规则说明书 · 前置校验 · 算价排他决策矩阵"]
        L3["<b>【L3 服务画像】</b> 100+ 微服务业务职责画像 · 独占数据表归属矩阵"]
        L4["<b>【L4 全局业务】</b> 端到端跨微服务时序拓扑 · 正向提单与逆向 Saga 分布式补偿闭环"]
        L1 ==>|1. 叶子方法自底向上 Map-Reduce 蒸馏| L2
        L2 ==>|2. 领域服务能力聚类与主表归属划界| L3
        L3 ==>|3. RPC 与 JMQ 跨服务依赖时序缝合| L4
    end

    subgraph OUT ["【第三块 · 消费终端】三大日常研发工具场景"]
        direction LR
        W1["<b>[Web 智能需求工作台]</b><br/>PRD 需求秒级圈定微服务<br/>存量代码排他互斥冲突预警"]
        W2["<b>[JoyCoder Agent 研发助手]</b><br/>标准只读 MCP 协议通信<br/>7 大原子工具排障证据链闭环"]
        W3["<b>[JoyCoder AI IDE 协同]</b><br/>本地 Sidecar 实时上下文感知<br/>&lt;200ms 编码阶段分片防灾雷达"]
        W1 ~~~ W2 ~~~ W3
    end

    IN ==>|Java CLI 编译级静态解析与符号求解| KB
    KB ==>|统一知识服务网关 · 两阶段混合检索| OUT

    classDef inStyle fill:#eff6ff,stroke:#2563eb,stroke-width:1.5px,color:#1e3a8a;
    classDef kbStyle fill:#fffbeb,stroke:#d97706,stroke-width:1.5px,color:#78350f;
    classDef outStyle fill:#ecfdf5,stroke:#059669,stroke-width:1.5px,color:#064e3b;
    class S1,S2,S3,S4 inStyle;
    class L1,L2,L3,L4 kbStyle;
    class W1,W2,W3 outStyle;

用户应当拿到什么

知识服务专注于业务知识提取、代码逻辑还原与变更影响推导。实际的代码编写与提交由开发者或 IDE 处理，真实的线上交易执行与补偿重试由原业务系统运行。

文档采用典型电商交易闭环作为示例：涵盖下单算价、库存预占、支付核销、履约拆单及逆向退款补偿等微服务集群。K1、K2 表示知识库发布版本。

工作台四大核心入口

• 智能方案（做需求）：输入 PRD 文本，一键完成两阶段混合检索，秒级圈定微服务，输出技术方案与时序图。
• 业务知识（查业务）：按 L4 业务域、L3 服务画像、L2 接口卡片层级浏览，支持人工补充“业务潜规则批注”。
• 影响分析（评影响）：输入拟修改的 JSF 接口、JMQ Topic 或数据库表，查出完整的上下游爆炸半径雷达。
• 知识保鲜（看同步）：查看 100 个微服务代码仓库的最新扫描状态、代码哈希变更、言犀质检记录与行云 CI 同步流水线。

从业务知识浏览进入问答，页面带入当前选中的知识对象、服务范围和生效版本，无需重复检索；切换版本后重新加载对应知识。

角色与权限边界

一人可兼任多项职责，权限由京东内部统一身份权限系统鉴权。查询中若发生权限变更，服务按新权限动态拦截受限内容的返回。

新人与多角色 3 分钟极速作业实操指引

为帮助刚刚入职 0.5~1.5 年的初级产品经理、初级研发与初级测试同学快速跨越百级微服务架构认知壁垒，系统提供三大角色的“日常 3 步保命实操指南”与“黑话白话对照表”：

1. 业务与技术名词“白话翻译机”（初级同学秒懂字典）

2. 👩‍💼 初级产品经理极速操作流（PRD 冲突排查 3 步法）

【第一步：输入新需求草案】
在「拍拍·谛听」Web 工作台粘贴新 PRD 核心描述：
“拍拍二手数码大促：用户购买自营手机时，允许在享受满 3000 减 300 跨店满减的同时，叠加使用 100 元品类东券。”
                  ⬇️ (系统后台毫秒级并发检索 100+ 微服务资产)
【第二步：查看系统秒级定界体检报告】
① 涉及责任微服务：自动圈定 3 个 (promo-engine-service, trade-order-service, settle-account)
② ⚠️ 存量互斥高危预警：
   - 存量规则：promo-engine 中 checkDiscountStack() 默认执行排他策略 (tag & 0x0400 == 0)；
   - 依赖配置：受 Ducc 动态开关 promo.tiered.stack.whitelist 控制；
   - 业务决策建议：如需全量开放，需提报财务审批修改 Ducc 白名单配置，无需重构订单底层状态机。
                  ⬇️
【第三步：一键导出技术可行性初稿】
点击“生成方案初稿”，直接将涉及微服务、交互时序图、改动范围附在 PRD 附录中，研发评审一把过！

3. 👨‍💻 初级研发防灾保命手册（IDE 编码实时避坑）

在 IntelliJ IDEA 中打开代码编写时，借助 JoyCoder 插件实时感知分片与爆炸半径约束，无需死记硬背底层配置：

❌ 错误示范：遗漏分片键（IDE 立即波浪线标红阻断）

// 初级研发在 OrderQueryServiceImpl.java 中编写的新查询方法：
public OrderInfo queryOrderByOrderId(Long orderId) {
    // ⚠️ 致命缺陷：order_info 是 1024 张水平分库分表，未传 user_pin！
    // IDE Gutter 立即亮起红色高危警报图标 🚨：
    // [拍拍·谛听防灾雷达] 拦截原因：order_info 为水平拆分表 (is_sharded=true)，
    // 缺少必要分片键 user_pin，将触发 1024 张分表广播扫描，可能引发数据库 CPU 击穿！
    return orderMapper.selectByOrderId(orderId);
}

✅ 一键智能修复示范（按 Alt + Enter 采纳建议）

// 修复后：严格携带 user_pin 路由键入参
public OrderInfo queryOrderByOrderId(String userPin, Long orderId) {
    // [拍拍·谛听防灾雷达] ✅ 路由键 user_pin 已绑定，单库单表精准定位 (<2ms)
    return orderMapper.selectByPinAndOrderId(userPin, orderId);
}

4. 🕵️‍♀️ 初级测试全链路用例设计指南（Saga 逆向链路覆盖）

初级测试人员根据 L4 全局时序拓扑，可以 100% 不漏用例地设计出全套测试矩阵：

产品范围与运行约束

1. 环境约束：知识库全流程（源码扫描、语义提取、模型推理、向量检索、存储）100% 运行于京东内网，严禁连接外部公网，大模型调用全部通过京东内网言犀 / JoyCoder 接口完成。
2. 事实约束：知识库推导依据为静态源码、配置中心（Ducc）与接口契约，不直接查询生产在线交易事务库；若需核对具体订单事实，通过只读归档或经授权的数据源提取。
3. 架构参考：四层知识架构的生成细节、数据契约、JED MySQL 与 Vearch 存储设计见 TRD 主方案。

业务人员与研发可以从统一知识目录查阅“整单取消与履约拒收后，系统如何流转退款与退券”，无需事先去翻找具体属于哪个 Git 仓库或哪段底层实现。

从业务名称找到资料

业务知识库按 L4 业务域（交易、营销、履约、结算等）、L3 微服务职责画像、L2 接口业务卡片 三级树状组织。选择“交易核心域”，进入“订单逆向补偿”，再点击“退款与退券核心逻辑”，即可直观查看业务规则、责任微服务、涉及的数据表及关联依据。

系统搜索支持业务术语（通过内部黑话词典对齐）、已确认别名，以及底层技术符号（如 JSF 接口全限定名、JMQ Topic、Controller URL 路径、类名与方法名）。

针对同名或相似接口，展示所属微服务、应用模块与适用条件，供用户选择。页面清晰标明检索范围、匹配度与生效版本；未命中时支持调整关键词或服务范围重新检索。

看清结构化业务卡片（L2）

接口业务卡片将原本晦涩的 Java 代码转化为业务人员与研发均可读懂的结构化文档，包含 5 大核心要素：

卡片下方提供代码调用树跳转入口（精确到 类名#方法名 及关键代码行），并标识规则的审阅状态与新鲜度（如“已审阅”、“待刷新”）。研发可在此一键提交“人工业务背景批注”，永久沉淀代码之外的业务潜规则。

[!NOTE] 生产级 L2 规则卡片示例：营销促销服务 calcOrderPrice

• 所属微服务与契约：jd-promo-engine · jsf://com.jd.promo.service.PromoCalcJsfService#calcOrderPrice
• 业务意图：针对提单入参，校验选中的优惠券与活动合法性，计算阶梯满减金额并生成分摊凭据
• 前置拦截条件：
  • ① pin 不能为空且黑名单风控核验通过（拦截码：PROMO_USER_BLOCKED）；
  • ② 优惠券模板状态必须为 ACTIVE 且当前时间在领用有效期内；
  • ③ 互斥与排他校验：跨店满减与自营东券默认互斥，受 Ducc 动态开关 promo.tiered.stack.enabled=false 控制。
• 状态机与存储：只读 JED MySQL promo_template_00~15，不变更订单状态机
• 外部副作用：调用 JimDB 原子锁占用优惠券配额 lock:coupon:${coupon_id}（TTL=30s）
• 静态代码依据：CouponCalcServiceImpl.java:112-168 · 对应 Git Commit a8c9e4f · 言犀核验门禁：已审阅通过

还原端到端跨服务业务流程（L4）

流程视图将散落在数十个微服务中的单点接口规则串联为端到端时序与协作链路。图中清晰区分同步接口调用（JSF / HTTP）、异步消息传递（JMQ）以及状态对齐检查点。

以典型电商订单逆向流转为例：

1. 触发步骤：订单中心收到履约拒收或用户取消事件；
2. 跨服务协作：订单服务调用营销算价服务退还优惠权益，调用支付服务执行原路退款；
3. 异步解耦：发送订单状态变更 JMQ 消息，下游履约与账务微服务订阅消费完成拆单清理与记账；
4. 异常恢复：退券超时或失败时，由订单恢复调度任务扫描待办重试，确保最终一致性。

每个节点均可下钻展开对应的微服务画像与接口卡片，返回时保持原流程位置不变。四层知识的生成机制见 TRD 系统与资料接入。

知道还缺哪些部分

微服务知识库提供全局覆盖率视图：

• 微服务接入覆盖：清晰展示 100 个微服务中已解析、解析中、解析受阻的服务清单；
• 接口归属台账：支持双向追溯——从业务场景查看涉及的所有对外入口，从对外入口反查归属的业务域。遇到未关联业务场景的批处理入口标为“未归属”，场景要求某项功能却未在代码中找到实现时标为“受阻”；
• 安全与权限保护：业务名称、详情卡片与代码依据严格按当前登录者的权限过滤，未授权服务不泄露敏感代码与配置。

研发与产品人员可以在工作台直接输入新需求（PRD 文档或一句话改动），知识库通过两阶段混合检索（Vearch 向量 + MySQL 符号）与静态依赖图谱展开，自动输出包含微服务定位、代码级改动点、存量逻辑冲突预警与上下游影响面的技术分析报告。

从需求检查改动影响

输入一段新业务需求（如：“大促期间允许特定白名单商品在命中跨店满减的同时叠加使用东券，并在履约时打标优先发货”），系统执行固定三步流水线：

1. 第一步（两级语义圈定范围）：
   • 提取需求中的核心领域词，检索 Vearch 中的 L3 服务职责画像，从 100 个微服务中精准锁定相关的 3~5 个服务（如：营销算价、订单核心、履约拆单）；
   • 在锁定的微服务内继续检索 L2 业务卡片，召回 Top-8 张最核心的接口规则卡片。
2. 第二步（静态依赖图谱确定性展开）：
   • 自动拉取目标接口关联的 上游 JSF 调用方服务、下游订阅对应 JMQ Topic 的消费服务、读写的逻辑数据表（标明是否水平分表） 及当前线上生效的 Ducc 动态配置项。
3. 第三步（言犀对比推理出方案）：
   • 对比【新需求 PRD】与【现有存量代码规则】，由言犀大模型生成结构化《需求分析与技术改造方案初稿》。

报告结构与核心内容

生成的《技术方案初稿》严格按研发标准结构组织：

• 精准改动定位（改哪里？）：明确列出需要修改的微服务名称、对外契约 URN（JSF/HTTP/JMQ），具体到 类名#方法名；
• 存量规则还原与冲突预警（⚠️ 重点！）：还原线上现有判定逻辑（如现有代码中“东券与跨店阶梯满减互斥且 Ducc 开关 promo.tiered.stack.enabled=false”），高亮冲突点并给出兼容建议；
• 分库分表与数据风险预警：若改动涉及水平分库分表（is_sharded=true），强制检查查询条件是否携带分片路由键（如 user_pin），严禁跨分片全表扫描；
• 跨服务上下游影响面（会影响谁？）：100% 列出上游调用方与下游消息订阅方，评估入参/出参及消息体格式兼容性；
• 调用时序图：输出改造后的 Mermaid 跨服务交互时序图。

完整样板：《百亿补贴跨店满减叠加东券技术改造方案初稿》全息穿透

以下为线上真实输入一段大促营销 PRD 后的端到端解析输出全貌，直观体现系统从微服务定位、代码级分支比对、Ducc 开关排他识别到分库分表防灾的完整输出能力：

1. 业务输入 (Input PRD Snippet)

需求背景与业务规则描述： “2026年618大促百亿补贴专场，针对自营及指定 POP 商家（白名单 tag 掩码 0x0400），允许在参与跨店阶梯满减（满300减40）的同时，叠加使用品类专享东券（面额10~50元不等）。 若发生单品售后逆向退款，必须依循商品行现金分摊权益，优先扣减东券抵扣金额，退还剩余实付现金；履约拆单结算时，向结算中心透传叠加优惠后的商家实结金额。”

2. 系统输出：《技术改造方案初稿》(Generated Engineering Blueprint)

一、 涉及微服务与代码定位 (Target Microservices & Code Anchors)

二、 存量逻辑冲突预警与架构建议 (Rule Conflict & Architectural Recommendation)

[!WARNING] 存量代码排他冲突拦截 (Severity: HIGH)

• 冲突点定位：存量代码 trade-promo-engine 中 DiscountMutexChecker#isMutex(promoTypeA, promoTypeB) 第 84 行存在硬编码互斥规则：

  if (typeA == PromoType.TIERED_MANJIAN && typeB == PromoType.DONG_COUPON) {
      return Boolean.TRUE; // 存量默认阶梯满减与东券排他互斥！
  }
  

• 线上 Ducc 开关现状：命名空间 trade.promo.switch 下配置项 promo.tiered.stack.enabled=false（当前全站阻断叠加）。
• 架构兼容建议：
  1. 严禁直接修改全量 Ducc 开关；应在 Ducc 新增商家/商品白名单配置项 promo.tiered.stack.whitelist.pins；
  2. 在 DiscountMutexChecker 引入商品标签位运算判断 (itemTag & 0x0400) == 0x0400，仅在命中白名单且 Ducc 开关开启时放行叠加；未命中者保持原互斥逻辑，保障全站大盘基线稳定。

三、 存储与分库分表防灾约束 (Storage & Sharding Safeguards)

• 涉及数据表：order_discount_detail_0000 ~ order_discount_detail_1023（水平拆分 1024 表，is_sharded=true）。
• 强制路由检查：优惠分摊明细表采用 user_pin 作为分片键（Sharding Key）。SQL 变更或新增查询必须在 WHERE 条件中显式携带 user_pin = #{userPin}。严禁基于 order_id 单字段进行无分片键查询，避免触发 1024 个分库分表广播扫描导致数据库 CPU 击穿。

四、 跨服务交互时序图 (Mermaid Sequence Diagram)

sequenceDiagram
    autonumber
    participant Client as 客户端 / 结算页
    participant Promo as 营销算价 (promo-engine)
    participant Ducc as 配置中心 (Ducc)
    participant Order as 订单核心 (order-core)
    participant Settle as 结算中心 (settle-account)

    Client->>Promo: 1. 提交算价 (cart_items, coupon_ids)
    Promo->>Ducc: 2. 读取 promo.tiered.stack.whitelist
    alt 命中华尔街白名单 (tag & 0x0400)
        Promo->>Promo: 允许跨店满减与东券双重叠加分摊
    else 普通商品
        Promo->>Promo: 触发存量排他剔除东券
    end
    Promo-->>Client: 3. 返回各商品行优惠分摊明细
    Client->>Order: 4. JSF 提交订单 createOrder()
    Order->>Order: 5. 携带 user_pin 写入优惠分表 (1024表)
    Order->>Settle: 6. 发送 JMQ order_created 消息
    Settle-->>Settle: 7. 异步核算商家应收与平台补贴款

读懂答案和依据

除输入完整 PRD 外，系统支持日常业务答疑（如：“优惠券叠加规则在哪里判定？”、“全球购商品为何不能与普通商品混购？”）：

• 答案与代码事实绑定：回答直接指出负责的微服务与方法名，展示核心分支逻辑与 Ducc 配置开关；
• 区分假设与代码事实：用户在问题中假设的前提（如“假设订单金额为 100 元”）与代码静态规则严格区分说明；
• 证据抽屉：点击答案中的引用标记，右侧抽屉展开对应的代码片段、注释与版本信息，支持一键跳转到对应知识卡片。

金额问题怎样回答

在涉及金额计算、优惠分摊与退款限额的问题中，系统严格遵循静态代码中的算法实现，绝不大模型幻觉臆测：

1. 分摊规则依循代码：展示原价、满减券、东券分摊的确定性代码公式与取整余分分配规则（如按商品行行号确定性分配）；
2. 区分在途与实付：明确区分当前实付现金、在途占用与已退款金额，引用支付中心 pay_record 流水与资金事实；
3. 退款限额硬约束：回答中明确指出退款上限受限于该行商品的现金权益凭据，杜绝跨商品行超额退款。

处理过程与异常结果

从已有问答继续追问时，系统保留上一轮的上下文与已定位的微服务，支持多轮深入细化方案。

除了人类工程师在 Web 工作台使用外，「拍拍·谛听」知识服务支持 AI Agent（包括无人值守任务 Agent、研发辅助 Agent）通过标准工具接口（Tool Calling / MCP 协议）调用知识库，自动化完成业务链路调查、上下游依赖探查与技术方案推演。

核心只读能力与工具接口（Tool Contracts）

接入「拍拍·谛听」知识服务的 Agent 可以发现并调用以下 7 项标准化原子能力（符合 schemas/tool-contracts.schema.json 强类型契约）：

具体强类型 Schema 与错误码定义见 TRD 查询与接入设计。

Agent 跨服务自动化调查典型流程

当 Agent 收到“排查优惠券分摊计算在哪个服务执行、为什么大促期间部分订单未成功叠加”的任务时：

sequenceDiagram
    autonumber
    actor User as [研发/业务工程师]
    participant Agent as [JoyCoder Agent 研发助手]
    participant KB as [拍拍·谛听 知识网关 (MCP)]

    rect rgb(239, 246, 255)
    Note over User,KB: 阶段一：目标资产定位 (粗粒度路由)
    User->>Agent: 调查满减叠券异常逻辑与生效开关
    Agent->>KB: 1. search_knowledge(query="满减 叠券 规则", types=["MICROSERVICE","RULE"], page_size=5)
    KB-->>Agent: 命中微服务 trade-promo-calc 及规则 rule:tiered_promo_calc
    end

    rect rgb(254, 243, 199)
    Note over Agent,KB: 阶段二：规则深入解析与配置核验 (L2 卡片)
    Agent->>KB: 2. get_business_rule(rule_id="rule:tiered_promo_calc")
    KB-->>Agent: 返回 L2 业务卡片 (含互斥分支与 Ducc 开关 promo.tiered.stack.enabled)
    end

    rect rgb(240, 253, 244)
    Note over Agent,KB: 阶段三：调用拓扑溯源与证据链交付 (L1 AST 溯源)
    Agent->>KB: 3. trace_impact(target="trade-promo-calc#calculatePrice", change_type="BEHAVIOR")
    KB-->>Agent: 返回上游调用方 trade-order-core 及触发代码行 OrderSubmitValve:142
    Agent->>KB: 4. get_evidence(evidence_id="ev:promo:142")
    KB-->>Agent: 返回不可变源码证据（JavaParser AST 代码片段与当前 Commit SHA）
    Agent-->>User: 综合输出根因报告 (指出互斥判定行与当前生效的 Ducc 开关 promo.tiered.stack.enabled)
    end

1. 目标资产定位：调用 search_knowledge，命中相关微服务及核心业务规则；
2. 规则深入解析：调用 get_business_rule 读取该接口的 L2 业务卡片，发现其中的排他校验规则及控制该逻辑的 Ducc 配置项 promo.tiered.stack.enabled；
3. 调用依赖溯源：调用 trace_impact 逆向反查调用方微服务，准确定位是由订单核心服务在提单校验时发起的调用；
4. 获取不可变源码证据：调用 get_evidence 抓取经过 AST 降噪的真实 Java 代码行与 Commit 指纹，向用户交付包含代码源头支撑的确定性根因报告。

保留调查中的版本和范围

在多轮自动化调查中，Agent 必须保持对调查版本、业务实例关联与证据链范围的确定性锁定：

• 版本冻结机制：Agent 发起调查时绑定固定的知识库发布版本指纹（Generation ID / Commit Hash），后续所有多跳工具调用均在该确定版本下执行，防止因底层代码持续合并产生前后矛盾的“漂移幻觉”；
• 权限与范围快照：访问权限取用户个人权限与 Agent 客户端授权的交集，在多轮对话中缓存权限令牌，无人值守服务 Agent 使用独立服务账号授权；
• 严格只读沙箱：所有 Agent 工具均为严格只读（Read-Only），仅提供规则解释、代码定位与影响推导，绝不执行任何写代码、提交 Git、调用业务写接口或修改生产配置的破坏性操作。

中断后继续

针对涉及数十个微服务的复杂跨服务长程调查，系统提供完备的会话状态持久化与断点续查能力：

• 状态快照与断点恢复：Agent 的每次工具调用入参、中间执行结果与候选节点列表均持久化于会话上下文中。当遇到网络中断、大模型速率受限（Rate Limit）或用户主动暂停时，可凭借 session_id 和断点令牌一键恢复现场，继续后续调查；
• 长任务流式输出：支持通过 Server-Sent Events (SSE) 实时流式推送分析进度（如：“已圈定 3 个微服务 -> 展开 AST 调用图 -> 比对 Ducc 规则冲突 -> 正在起草方案”）；
• 动态取消与预算保护：支持随时取消耗时过长的未决任务；单次会话设定严格的最大工具调用深度（默认 5 跳）与 Token 预算，超限自动截断并返回已有阶段性成果与未查范围说明。

研发工程师在本地 IntelliJ IDEA 中进行业务开发与代码修改时，通过京东内部编程助手 JoyCoder（基于标准 MCP 协议） 实时联动本微服务知识库，实现“编码前看约束规则、编码中看上下游依赖、编码后看改动影响扩散”。

在编辑前取得相关知识

开发者在 IDEA 中打开某个微服务工程（如 jd-order-core），光标停留在 OrderExportServiceImpl.java 的业务方法上，点击 JoyCoder 侧边栏的“查看业务约束”或使用快捷指令：

1. 工作区自动对齐：IDE 插件自动读取本地 Git 仓库的远程地址（如 git@coding.jd.com:trade/jd-order-core.git）和当前类路径，向知识库发起契约映射；
2. 约束卡片一键拉取：知识库秒级返回该方法对应的 L2 业务规则卡片，高亮展示：
   • 当前方法必须满足的前置业务校验（如防重幂等、用户风控限制）；
   • 当前方法涉及的 Ducc 动态开关及默认行为；
   • 关联的领域实体状态机流转约束（如订单只能从 WAIT_PAY 变迁到 PAID）。

先看约束，再看影响

当研发修改了某个核心接口的 DTO 字段、新增了状态枚举值、或者调整了 JMQ 消息结构时，在提交代码前即可在 IDE 内一键执行“变更影响面扫描”：

跳转证据与继续编辑

• 高保真证据跳转：点击知识卡片中的代码依据，IDE 自动打开本地对应文件并高亮定位到指定行。若本地代码已修改与知识库版本存在差异，IDE 明确提示“本地代码已改动，当前依据基于线上知识版本 K1”；
• 端侧防抖与本地 L1 缓存（防止并发网关雪崩）：
  • IDE Sidecar 进程内置 3 秒光标停留防抖与 500 个最近符号的本地 LRU 内存缓存；连续敲击代码时不盲目发送探测请求；
  • 知识服务网关对单 ERP 实施 100 QPS 令牌桶限流，在大促封板前集中修改代码的高峰期，保障系统稳定与极低延迟；
• 上下文防污染：开发者在本地切换 Git 分支或保存文件修改时，IDE 插件立即停用旧的上下文缓存，重新向知识库拉取最新基线，杜绝迟到或过期建议污染编码窗口。

知识库作为本地 IDE 的只读智能顾问，为开发提供严谨的架构与业务约束，不越权直接修改本地文件，代码的保存、编译与 Git Commit 完全遵循原有的开发规范。

工作区匹配与 MCP 协议契约实现见 TRD 查询与接入设计。

微服务代码处于持续高频迭代中。知识库如果依赖人工编写或定期的全量离线重建，不出两周就会严重过时腐烂。本系统采用 「行云 CI 流水线 Webhook 增量同步 + 单方法级哈希比对 + 逆向调用树向上染色重算」 机制，确保微服务合并主干分支后，知识库在 45 秒内 自动保鲜。

行云 CI 增量更新核心闭环

当研发在京东 Coding 平台将代码合并到主干分支（Master/Release）时，触发自动化同步流程：

flowchart TB
    subgraph S1 ["【阶段一 · 增量捕获】CI 触发与变更文件识别"]
        direction LR
        A["<b>[Coding / Git]</b><br/>主干分支 Merge"] --> B["<b>[行云 CI]</b><br/>流水线 Webhook 触发"]
        B --> C["<b>[git diff]</b><br/>增量感知提取变更文件"]
        A ~~~ B ~~~ C
    end

    subgraph S2 ["【阶段二 · 门禁比对】方法清洗与哈希门禁核验"]
        direction LR
        D["<b>[JavaParser]</b><br/>AST 静态扫描提取方法"] --> E["<b>[SHA-256]</b><br/>规范化计算 code_hash"]
        E --> F{"比对 MySQL 缓存表<br/>方法哈希是否实质变化？"}
        D ~~~ E ~~~ F
    end

    subgraph S3 ["【阶段三 · 分支处置】零成本旁路 vs 局部拓扑重算"]
        direction LR
        subgraph Bypass ["0 Token 极速旁路 (无实质变化)"]
            G["<b>[0 Token 旁路]</b><br/>直接复用历史业务规则摘要与画像"]
        end
        subgraph Rebuild ["局部染色重算 (实质变化 Dirty Node)"]
            direction TB
            H["<b>[大模型增量蒸馏]</b><br/>仅重算变更方法 (&lt;1.5K Token)"]
            I["<b>[调用拓扑回溯]</b><br/>沿 caller_methods 逆拓扑染色"]
            J["<b>[局部刷新]</b><br/>重建受影响的 1~3 张 L2 接口卡片"]
            K["<b>[双写持久化]</b><br/>刷新 JED 与 Vearch 索引 (&lt;45s)"]
            H --> I --> J --> K
        end
    end

    S1 ==>|1. 触发差量静态扫描| S2
    F -- "未变化 (仅格式/注释)" --> Bypass
    F -- "实质变化 (代码逻辑变更)" --> Rebuild

    classDef trigStyle fill:#eff6ff,stroke:#2563eb,stroke-width:1.5px,color:#1e3a8a;
    classDef gateStyle fill:#fffbeb,stroke:#d97706,stroke-width:1.5px,color:#78350f;
    classDef bypassStyle fill:#f0fdf4,stroke:#059669,stroke-width:2px,color:#064e3b;
    classDef dirtyStyle fill:#fef2f2,stroke:#dc2626,stroke-width:1.5px,color:#991b1b;
    classDef storeStyle fill:#f5f3ff,stroke:#7c3aed,stroke-width:1.5px,color:#4c1d95;

    class A,B,C trigStyle;
    class D,E,F gateStyle;
    class G bypassStyle;
    class H,I,J dirtyStyle;
    class K storeStyle;

1. 秒级变更识别：通过 git diff 识别本次 Merge 涉及的具体 .java 源码和 XML 配置文件；
2. 零模型开销过滤：对变更方法计算清洗后的代码哈希（code_hash），若哈希与缓存表一致（如仅调整了日志格式、格式化缩进），直接复用老摘要，不调用大模型；
3. 公共基础包防级联风暴阻断：当多个微服务共用的二方包（如 trade-common-dto.jar）合并时，启动契约级语义差量检测。若仅新增可选字段且未改变现有业务方法逻辑，直接阻断向上扩散，避免触发全网百级微服务无差别重算的雪崩灾难；
4. 精准局部重算：仅当方法业务代码发生真实变更（标记为 Dirty Node）时，调用言犀重新生成百字业务摘要（耗时约 23 秒），并沿反向调用链（caller_methods）向上回溯，仅刷新直接受影响的 13 张 L2 接口卡片与微服务画像；
5. 性能收益：单次代码提交平均仅耗时 30~45 秒，消耗 Token 极低（< 5,000 Token），实现“代码天天变，知识永最新”。

人工业务背景批注层（解决最后 10% 业务潜规则）

代码能精准反映“系统现在是怎么跑的”，但往往无法体现“当年为什么要这么写”（例如某些特定枚举值是历史某次联名卡大促专项遗留）：

• 一键补充批注：产品经理与研发在 Web 工作台浏览任意 L2 接口卡片、数据表或枚举时，点击右上角 「➕ 补充业务背景批注」，输入历史背景或特殊排他原因；
• 批注永久沉淀：批注存入 JED MySQL 的 kb_human_annotation 表，与契约 URN 强绑定；
• 代码重扫永不丢失：即使后续微服务代码合并触发增量重构，人工补充的批注永久保留，绝不被自动化扫描覆盖，并在每次在线做需求问答时作为最高优先级上下文注入言犀大模型，形成“机器自动推导 90% + 人工经验点睛 10%”的越用越聪明闭环。

知识纠错与反馈处理流

用户在查看技术方案或业务答案时，若发现规则描述不准或存在偏差，可提交纠错工单：

增量更新与存储架构详细定义见 TRD 更新发布与运行。

本方案的建设成效以真实研发效能提升、代码改动定位准确率、以及线上真实需求（PRD）盲测指标为客观衡量标准，确保知识库在研发日常工作中真正可用、好用。

从查业务到检查改动

验收使用包含电商正向履约与逆向退款补偿的典型微服务集群作为测试基线，涵盖正向提单、营销算价、库存预占、支付核销、履约拆单及取消补偿等核心链路。

黄金评测集与量化验收硬指标

系统正式上线前，采用近半年内 已上线的 20 个真实线上需求（PRD） 组成黄金评测集（以最终实际合并上线的代码文件与方法作为标准答案 Ground Truth），进行双盲自动化评估：

内部能力需要哪些依据

技术合同与 Schema 详细定义见 TRD 合同与验收。

方案设计与技术决策 FAQ：核心疑问深度解析 (Technical FAQ & Design Rationale)

在业务方案定界、跨团队研发协同及方案评审过程中，技术人员与业务人员往往会就系统边界、大模型稳定性与分布式生产安全提出关键疑问。以下是本知识服务在系统架构与业务逻辑层面的权威解答：