核心系统如何全面使用 AI Coding

✦ 先给结论 ✦

CORE THESIS

不追求 100% 代码由 AI 编写，追求 100% 研发环节有 AI 参与

AI 负责理解、整理、生成、检查和反馈；人负责目标、业务语义、架构取舍、风险判断与最终责任。核心系统中的确定性规则和交易仍由 Core 执行。

01

先辅助，再自治

先让 AI 给方案和草稿，再执行受约束的小任务。只有当任务可自动验证、可快速审查、可安全回滚时，才逐步提高自动化程度。

02

AI 左移，质量前置

AI 越早参与需求和方案，纠错成本越低；AI 参与越深，测试、审查、安全扫描、权限控制和回滚机制越要前置。

03

小步推进，结果负责

不做一次性重写，不用大提交掩盖不确定性。每轮只解决一个明确问题，留下计划、变更、验证和复盘证据。

✦ 一 · 先解决 AI 看不懂、改不动、验不完 ✦

现有技术体系适合“人驱动”的标准化交付，但不天然适合 AI 协作。参考当前 Vxlink 架构，系统包含 19 个 Spring Boot 微服务，并深度依赖低代码平台、跨服务调用、配置中心和分布式中间件。

当前工程 19 个微服务 多个仓库、接口、配置、数据状态和部署单元

阻力一

架构碎片化

一次需求常跨多个服务、Feign 接口、消息、配置和数据库。AI 难以判断完整修改边界，编译、联调和回归链路也过长。

阻力二

平台锁定

生成代码、模块结构、插件机制和运行配置与平台深度绑定。隐含约定多，既增加 AI 上下文，也抬高自主维护、迁移和升级成本。

传统优势：团队熟悉、基础设施完整、常规交付快 AI 化代价：理解边界难、修改范围大、验证反馈慢

所以第一步不是采购更多 AI 工具，而是让工程变得可理解、可修改、可验证。

✦ 二 · 建立全流程 AI 开发闭环 ✦

AI Coding 不能只停在 IDE 补全。团队要把 AI 放进从业务问题到线上反馈的每个环节，同时明确人、AI 和系统各自的责任。

发现问题→定义需求→设计方案→拆解任务→开发验证→评审发布→运行复盘

线上结果回流到需求模板、规则文件、测试资产和知识库，形成下一轮更准确的上下文。

环节 AI 主要工作人的责任与门禁必须沉淀的产物

01 发现问题

汇总反馈、日志、工单和数据异常，归类高频问题与可能原因。

确认是否值得做、业务价值和优先级。

问题陈述、证据、影响范围。

02 定义需求

补齐场景、规则、边界、反例、异常流和验收标准。

确认业务语义、非目标、合规要求和成功标准。

结构化 PRD、规则表、验收清单。

03 设计方案

阅读调用链和历史决策，给出方案、影响面、风险与回滚路径。

决定架构边界、数据方案、兼容策略和长期成本。

ADR、接口契约、数据变更与风险清单。

04 拆解任务

定位文件和依赖，拆成可独立验证的小任务，生成测试计划。

确认范围没有遗漏，也没有无关扩张。

任务计划、文件清单、测试点。

05 开发实现

按现有风格修改代码、补测试、解释变更，并保持提交小而清晰。

开发者拥有代码，处理业务判断、复杂异常和关键取舍。

代码、测试、迁移脚本、变更说明。

06 测试验证

运行单元、契约、集成、回归、安全和性能检查，分析失败原因。

按风险等级决定测试深度，确认真实场景与历史兼容。

测试报告、覆盖证据、残余风险。

07 评审发布

生成 diff 摘要、风险提示、发布步骤、监控项和回滚方案。

Reviewer 对语义、安全和可维护性负责；Owner 批准上线。

评审记录、发布单、回滚预案。

08 运行复盘

监控指标和日志，辅助定位异常，整理事故时间线和改进项。

判断是否回滚，主持复盘，并决定规则如何更新。

复盘报告、新用例、新规则、新知识。

每个环节只接受结构化输入，输出可验证产物。 没有验收标准，不进入开发；没有验证证据，不进入发布。

✦ 六 · 测试环境数据：让验证既逼真又安全 ✦

AI Coding 要真正介入测试环节，第一个要解决的不是"AI 怎么写测试"，而是"AI 拿什么来测"。测试环境的数据如果太假，自动化测试只是一场自欺欺人；直接用生产数据，又踩上合规红线。核心矛盾是：测试既要尽可能逼真生产，又绝不能暴露真实个人信息。

核心矛盾

为什么要为测试数据单独设计方案？

很多团队的测试库长期用几条手工 INSERT 的"张三李四"就算完事。这样的数据测个流程通不通还行，但遇到金额边界、日期计算、状态流转、批量压力和异常路径，假数据根本覆盖不到。AI 生成的代码如果只在假数据上通过验证，上线后第一笔真实交易就可能出问题。

风险一

失真数据 → 虚假安全感

字段长度、金额分布、空值比例、编码格式与生产不一致。测试全绿，上线就挂。

风险二

直接拷贝生产 → 合规事故

手机号、身份证、银行卡、地址一旦进入测试库，就是数据泄露的源头。监管和审计都不会手软。

风险三

环境漂移 → 验证失效

表结构改了测试库没跟上，或测试数据长期不刷新，AI 验证通过的代码在真实环境完全不可用。

测试数据构造的四层方法

LAYER 01

基础字典与配置数据

币种、码值、产品码、机构号、费率表、参数表等不依赖个人的参考数据。

来源：直接从生产同步或版本管理；不含个人信息，可放心使用。

LAYER 02

规则化生成的业务实体

客户、账户、合同、卡号等核心实体，用程序按生产规则批量生成：相同字段格式、相同校验规则、相似的分布特征，但内容虚构。

关键：保持数据结构、约束、索引、状态码与生产一致，让 SQL 执行计划不走样。

LAYER 03

脱敏后的生产子集

从生产库抽取有代表性的样本子集（如某地区某产品近三月），再对敏感字段做不可逆脱敏：姓名、手机、证件号、地址、邮箱等。

脱敏算法必须不可逆（哈希、替换、泛化），且保持关联一致性（同一客户在所有表的 ID 映射统一）。

LAYER 04

AI 增强的合成数据

在脱敏样本基础上，用生成模型或统计模型放大数据量：保持分布特征、相关性和边界，生成用于压力和回归测试的扩充集。

合成数据仅用于性能和回归场景；不可用于涉及真实客户权益验证的场景。

六条操作原则

把测试数据当成一条独立的数据流水线

01

绝不直接拷贝生产

任何从生产到测试的流动，都必须经过脱敏网关；禁止 DBA 手动 mysqldump 后直接导入测试库。

02

脱敏不可逆

使用哈希、格式保留替换、区间泛化或假名化；禁止可逆加密当作脱敏。

03

保持关联一致性

同一身份在所有表、所有层级中必须映射到同一个脱敏 ID，否则关联查询和外键校验会失真。

04

数据版本化、可重建

测试数据集要版本管理，能按标签重建；不能只靠"当前测试库那堆不知道谁改过的数据"。

05

贴近生产分布

金额、账龄、地区、产品、状态的比例应接近生产统计，否则 AI 优化的 SQL 执行计划在真实环境会走偏。

06

自动化数据供给

CI 流水线启动测试环境时，自动拉取对应版本的测试数据集，避免环境差异带来的"我这好好的"问题。

生产数据 只读抽取子集 按时间、地区、产品抽样

→

脱敏网关 不可逆脱敏 + ID 映射 哈希 / 替换 / 泛化

→

数据增强 规则生成 + AI 合成 补齐边界与规模

→

版本化测试数据集 自动供给 CI 与本地 可审计、可重建

核心结论

测试环境的最终目标不是"数据越多越好"，而是让 AI 每次验证都在接近生产的土壤上进行，同时保证没有任何真实个人信息进入测试链路。把这层做好了，AI 参与测试才有意义；做不好，AI 生成的测试通过得再漂亮，也只是给生产事故写好了剧本。

✦ 三 · 用风险分级守住核心系统底线 ✦

不能让所有需求走同一套流程，也不能因为 AI 看起来“很有把握”就降低审查。质量门禁应由业务风险和变更半径决定，而不是由谁写代码决定。

L1

低风险

文案、样式、内部工具、无状态小改动。

AI 可完成实现与基础验证，人做快速确认。

L2

一般风险

普通业务逻辑、查询接口、非关键流程。

必须有单测、代码评审和可回滚发布。

L3

高风险

资金、账务、权限、租户、批量任务和数据迁移。

双人评审、集成回归、灰度和专项核对。

L4

关键风险

核心交易规则、不可逆操作、监管与重大资损场景。

架构评审、人工审批、演练、审计和明确责任人。

六条不可跳过的门禁

范围门禁变更只能落在确认过的文件、接口和数据边界内。

测试门禁新增行为必须有自动化测试；历史行为必须有回归证据。

评审门禁AI 可以辅助审查，但不能替代责任人的最终签字。

权限门禁生产数据、密钥、发布和高风险 Tool 默认最小权限。

回滚门禁不可快速回退的改动，必须降低自动化等级。

审计门禁保留需求、计划、提示、执行、测试、审批和发布记录。

防止“信任退化”：AI 越稳定，人越容易跳过检查。系统必须用自动门禁代替记忆，用抽检和事故复盘持续校准规则。

✦ 四 · 先建设 AI 能工作的工程底座 ✦

模型能力只是上限，工程环境决定实际产出。团队要把隐含经验变成机器可读、流程可执行、结果可验证的公共资产。

01

统一上下文

领域词典、模块边界、接口契约、数据字典、历史决策和运行手册有唯一来源。

02

规则文件

把代码规范、架构约束、安全红线、测试要求和提交规则写成 AI 可读取的仓库规则。

03

快速验证

提供一键启动、稳定测试数据、分层测试和快速 CI，让 AI 每次修改后立即得到反馈。

04

安全工具链

通过受控 Tool、MCP 或函数调用访问代码、日志、文档和环境，按角色授权并完整审计。

05

知识闭环

评审意见、线上故障、用户反馈和优秀实践持续回写规则、用例与知识库。

06

模型可替换

流程、上下文和评测不绑定单一模型；用任务结果选择模型，而不是用模型品牌定义流程。

团队知识的优先级

代码与自动化测试›正式规范与 ADR›接口和数据契约›知识库与历史记录›聊天记忆

越靠前越接近真实运行状态。知识库负责解释“为什么”，代码和测试负责证明“现在是什么”。

✦ 五 · 把系统改造成 AI 友好的形态 ✦

最终目标不是把 19 个微服务原样交给 AI，而是逐步收敛为更简单的工程体系：Agent 负责理解、规划和编排，AMC Core 负责确定性规则与交易。

STEP 1

微服务收敛

先统一仓库、构建、测试和本地运行，再按业务事务合并强耦合服务，减少跨服务上下文。

19 个服务 → AMC Core + 少量边界服务

STEP 2

去平台锁定

冻结新增生成代码，把 auto 逻辑和隐含插件约定迁移成清晰、可维护、可测试的领域代码。

平台生成 → 自主领域代码

STEP 3

AI Coding 工程化

补齐领域知识、规则文件、契约测试、一键环境、快速 CI、权限和评测闭环。

AI 能理解、修改、验证

STEP 4

系统能力 Agent 化

把稳定领域能力封装成 Tool，增加规划、记忆、知识检索、人工审批、评测和审计。

AI Coding → AMC Agent

目标架构：四个清晰部署单元

01

AMC Agent Platform

Planner / Orchestrator、领域 Agent、Tool Registry、Memory、Knowledge、Guardrail 与 Human-in-the-loop。

02

AMC Core

模块化单体，承载资产、项目、案件、登记、还款、账单、支付、档案、征信、权限、流程和审计。

03

Integration Hub

统一连接银行、征信、电子签章、支付、渠道和文件存储，隔离外部系统变化。

04

Data & Knowledge

统一业务库、对象与档案存储、事件与审计日志、向量知识库和模型评测数据。

Agent理解目标、拆解任务、选择工具、编排流程

AMC Core执行确定性业务规则、数据变更和核心交易

高风险动作必须经过权限校验、人工审批、完整审计和可回退设计

✦ 六 · 180 天落地路线 ✦

不从“全员买工具”开始，也不从“重构所有系统”开始。先选一条真实业务链路跑通闭环，再把有效规则复制到团队和架构。

0—30 天

建立基线，跑通一个试点

选一个低到中风险、边界清晰、可度量的真实需求；补齐需求模板、仓库规则、测试命令和人工审批点。

交付：一条端到端 AI 辅助链路 + 第一版团队规范。

31—90 天

覆盖全流程，建立质量门禁

把 AI 接入需求、设计、开发、测试、评审、发布和复盘；上线风险分级、CI 检查、权限审计和知识回写。

交付：团队可重复使用的研发工作流，而不是个人技巧。

91—180 天

收敛工程，缩短验证链路

统一构建与本地环境，优先合并强耦合服务，逐步迁移平台生成逻辑，补齐契约测试和领域知识。

交付：AI 能完整理解、修改和验证的核心工程。

180 天以后

把稳定能力封装为 Agent Tool

从只辅助研发，扩展到辅助资产分析、案件运营、档案处理和风险判断；高风险动作继续由 Core 和人工门禁控制。

交付：可评测、可审计、可运营的 AMC Agent 能力。

管理层只看结果，不看“AI 写了多少代码”

交付效率需求到上线周期、等待时间、返工次数

质量结果一次验收通过率、逃逸缺陷、回滚和事故

工程健康构建与测试时长、变更半径、环境成功率

AI 有效性建议采纳率、人工改写量、失败类型和任务完成率

知识复用规则命中、用例复用、重复问题下降和新人上手时间

风险控制越权次数、敏感数据暴露、门禁拦截和审计完整性

✦ 11 · 实战操作篇 · 第二阶段 ✦

CORE SYSTEM TRANSFORMATION

再改项目：先盘点影响面，再决定哪些依赖该拆

第二阶段不是直接让 AI 重写系统，也不是把飞速中心能力一股脑抛弃。先把入口、代码、数据、身份、权限、租户、流程和外部依赖画清楚；之后分别决定保留、隔离、迁移或下线。

TARGET 核心系统收缩为模块化单体

一个核心代码库、一个领域模型、一条主发布链；模块边界清楚，不等于把所有代码搅在一起。

FE前端并行

页面、路由、状态和接口契约逐页迁移。

BE后端并行

按业务模块收口接口、规则和数据访问。

OPS运维并行

环境、发布、日志、监控和回退同步建设。

KEEP

保留

有稳定价值、替换成本高的数据库、缓存、消息队列、对象存储，以及成熟的认证、组织、审计等平台能力，盘点后可以继续保留。

CUT

砍掉

无明确用户、无使用数据、长期无人维护的功能。站内信若可被钉钉 / 企微通知替代，就停止新增能力，只保留必要历史查询。

AI REBUILD

AI 重构

需求清楚但代码质量差、测试缺失、改一次坏一次的模块，先补行为测试，再让 Coding Agent 在新边界内重写。

MIGRATE

逐步自建

长期卡住的下载等关键链路，先加监控，再做新旧双路由和灰度迁移，稳定后才关闭旧实现。

第一件事不是写代码，而是做一张“影响面盘点表”

01

功能入口

菜单、按钮、定时任务、消息消费者、开放 API 分别从哪里进入？

02

代码归属

涉及哪些仓库、模块、生成代码、公共包和配置中心？

03

数据影响

读写哪些表、缓存、索引、文件和消息主题？是否需要历史迁移？

04

外部依赖

飞速中心、流程中心、企微、对象存储或其他服务调用了什么？失败如何表现？

05

真实使用

近 30 / 90 天调用量、活跃用户、失败率、峰值和人工兜底次数是多少？

06

迁移决策

保留、砍掉、重构还是迁移？负责人、窗口、验收证据和回退开关是什么？

MIGRATION CARD

每个被改造模块都要填完这张卡

模块 / 能力: 下载中心
当前调用方: 订单、报表、审计导出
当前痛点: 大文件超时、状态不可见、失败需人工重试
目标方案: 异步任务 + 文件存储 + 状态查询
切换方式: 按租户灰度，新失败自动回旧链路
完成证据: 成功率、P95 时间、告警、回退演练

PARALLEL, NOT CHAOTIC

前端、后端、运维齐头并进，但共用同一份契约

前端

建立页面与旧接口映射表
用 Mock / 契约先行解耦后端进度
逐页加新旧开关和错误兜底
记录关键路径埋点与用户行为

后端

按领域建立模块边界，不按技术层随意互调
先兼容旧契约，再逐步收敛新接口
把外部依赖包进 Adapter，业务代码不直连
对关键行为补集成测试和数据校验

运维

统一开发、测试、预发、生产配置差异
建设新旧链路日志、指标和 Trace 对比
发布必须支持灰度、开关和一键回退
切换前完成容量评估与故障演练

共同基线：OpenAPI / 接口样例、错误码、事件结构、数据口径、状态机、Feature Flag 和验收用例必须版本化；任何一侧修改都要触发另外两侧检查。

✦ 七 · 平台能力解耦 ✦

CAPABILITY INVENTORY FIRST

去飞速中心不是清空平台能力：先盘点，再下刀

要去掉的是核心业务对平台实现细节的强耦合，不是把成熟的用户、认证、组织、租户和审计能力全部重写一遍。每项能力必须先确认价值、边界、数据归属和替换风险，再决定保留还是迁移。

谁是数据源哪些系统在调用故障影响范围安全与合规要求本地定制程度替换和运维成本是否有可回退方案

A直接保留

成熟、稳定、非业务差异化能力，暂时不动。

B保留能力，隔离调用

继续使用飞速中心，但通过 Adapter、同步表或事件解耦。

C逐步迁回核心系统

与本项目业务规则强相关，平台已成为迭代瓶颈。

D停止使用

没有真实价值、可以被现有渠道替代，且无合规保留要求。

平台能力	初步处理建议	具体怎么处理	下刀前必须查清
用户中心与登录认证A / B	认证能力优先保留，先隔离调用，不急着自建密码、MFA、找回和会话安全。	核心系统建立 Identity Adapter 和内部稳定的 `user_id`；登录仍可走飞速中心，但业务表不直接保存平台临时 Token 或 SDK 对象。	账号唯一键、登录方式、禁用与离职流程、Token 生命周期、MFA、单点登录、账号合并和历史用户映射。
用户资料与组织架构B	保留权威数据源，在核心系统建立只读投影或缓存。	通过事件或定时任务同步部门、岗位、上级和状态；核心业务读取本地快照，平台短时不可用时不应拖垮全部查询。	组织数据由谁维护、变更延迟要求、离职删除规则、跨组织兼职、历史部门以及企微通讯录是否也是数据源。
权限管理B / C	认证与通用角色可以保留；订单、档案、审批等业务权限逐步迁回核心系统。	先盘点角色、菜单、接口、数据范围和对象级权限，再建立统一 Authorization Adapter。平台提供身份和基础角色，核心系统负责领域权限判定。	RBAC / ABAC 规则、角色继承、部门数据范围、本人数据、临时授权、超级管理员、前后端校验差异和越权审计。
多租户控制B / C	租户主数据可以暂时保留，但租户隔离必须在核心系统内可独立执行和验证。	统一 Tenant Context，让 `tenant_id` 贯穿请求、数据库、缓存、消息、定时任务、文件目录、搜索索引和日志；不能只依赖飞速中心在入口处过滤。	租户创建与停用、用户跨租户、数据隔离模式、共享数据、缓存键、消息消费、批处理、文件路径、导出和运维查询是否会串租户。
审计、登录日志与安全策略A / B	合规链路优先保留；若要迁移，必须先双写并完成审计验收。	核心系统补充业务操作审计，平台继续保留登录和账号安全日志。统一关联用户、租户、请求和业务对象，避免两边日志无法串联。	法定保存期限、日志防篡改、敏感字段脱敏、查询权限、告警策略以及历史日志能否迁出。
代码自动生成C	优先剥离，因为它直接限制研发能否独立修改和交付。	冻结生成基线，把结果、模板或替代脚本收进仓库；确认不依赖平台也能新增字段、接口和页面。	生成输入、模板版本、覆盖规则、二次手改区域、隐藏公共包和发布阶段是否仍会调用平台。
流程中心B / C	先通过 Workflow Adapter 隔离，再按流程复杂度决定保留引擎还是迁移具体流程。	通用审批可继续保留；与核心领域强绑定、频繁卡住迭代的状态机，逐条影子运行后迁回。	节点、条件、角色、回调、超时、撤回、加签、抄送、历史实例和在途流程如何处理。
企微与消息渠道B	保留渠道能力，但核心业务只能调用统一通知接口。	登录、通讯录、消息、机器人和审批分别封装；通知使用 Outbox、幂等键、重试和降级渠道。	Token 刷新、限流、回调验签、重复消息、失败补偿、敏感信息和企微不可用时的业务影响。

MULTI-TENANT RED LINE

多租户不能靠"记得加 tenant_id 条件"来保证。

必须有统一上下文、默认数据过滤、跨租户显式授权和自动化隔离测试。任何新链路只要数据库、缓存、消息、文件、搜索或日志中有一处没有租户边界，就不能切生产流量。

盘点完成后，再按三个战役下刀

01

先剥离代码自动生成

把"能不能开发"从平台手里拿回来

盘点生成器输入、模板版本、生成目录和二次手改点。
冻结一版可运行基线，把生成结果纳入仓库和测试。
把必须保留的生成逻辑迁为仓库内脚本；能手写维护的直接停止生成。
连续两个迭代不调用飞速中心仍可新增字段、接口和页面，才算完成。

02

再替换流程中心

先还原真实状态机，再决定自研到什么程度

导出流程定义、节点、条件、角色、超时、撤回、加签和回调清单。
把业务规则与流程引擎调用分开，建立统一 Workflow Adapter。
先选一个低风险流程做影子运行，对比新旧节点与最终结果。
双写期间每日核对实例数、状态和审批结果；有差异立即切回旧路。

03

最后处理企微集成

把渠道能力降级为可替换适配器

盘点登录、通讯录、消息、机器人、回调和审批分别被谁调用。
统一封装身份、组织、通知三类接口，核心业务不出现企微 SDK 对象。
消息走 Outbox 与幂等键，渠道失败不阻塞主业务事务。
验证 Token 刷新、限流、重试、重复回调和降级通知后再切量。

GATE 1 梳理完成

调用方、数据、负责人和风险没有"未知"。

→

GATE 2 新链可验证

契约测试、影子流量、监控和回退开关齐备。

→

GATE 3 灰度可回退

小流量稳定，数据核对通过，故障演练完成。

→

GATE 4 旧链可删除

观察期结束、无调用、文档与资产完成归档。

AI 在改造中的正确位置

适合交给 AI：跨仓检索调用链、生成依赖清单、补契约测试、批量改 Adapter、生成迁移脚本草稿、对比新旧结果。
必须由人决定：砍哪些功能、业务口径、数据迁移窗口、权限模型、生产切流和旧系统下线。
每个任务的交付包：影响面、Diff、测试证据、数据核对、监控面板、灰度计划、回退步骤、业务验收人。

去中心依赖不是重写所有基础能力，而是先决定什么继续复用、什么需要隔离、什么必须迁回，再用可观察、可灰度、可回退的方式一点点下刀。

✦ 八 · 实战操作篇 · 代码自检 ✦

PERIODIC AI CODE AUDIT

AI 写的代码，要让 AI 定期回头检查

AI 很擅长沿着当前任务继续加代码，却不一定会主动确认旧页面、旧接口、旧配置和兼容逻辑是否已经退出。项目连续迭代后，最容易出现的不是功能完全重复，而是新实现上线了，旧实现仍留在仓库里。

先审计只读检查，不立刻修改

→

再确认证据、入口、调用方都核对

→

后清理分批提交，每批都可回退

把代码自检做成固定制度，而不是想起来才问一次

每周

轻量冗余扫描

检查无引用文件、误提交缓存、废弃 API 导出、重复小工具和长期隐藏入口。

产物：候选清单，不改代码

每个大版本前

新旧链路核对

重点检查路由、接口、模型、配置、任务状态机和启动入口是否存在双栈。

产物：退役计划与兼容期限

每月

结构性健康检查

统计超大文件、重复基础设施、跨模块拷贝和职责不断膨胀的服务。

产物：重构候选与成本评估

重大迁移后

旧实现退出检查

新页面、新流程、新配置或新任务体系上线后，确认旧入口是否真的停止使用。

产物：删除证据与观察期记录

TEAM SKILL

团队应固定一个 `code-health-audit` Skill

所有项目使用同一套审计维度、优先级和证据格式。项目自己的 AGENTS.md 只补充目录、架构边界、测试命令和"哪些双实现是刻意保留的"，避免不同 Agent 每次用不同标准得出完全不同的结论。

统一扫描范围：路由、生产引用、API、数据模型、配置、脚本、测试和生成产物。
统一证据：文件路径、行号、生产入口、调用方、替代实现和删除风险。
统一优先级：P0 明确冗余，P1 架构双栈，P2 小型重复或结构债务。
统一边界：第一次只出报告，不删除文件、不改接口、不自动提交。

READ-ONLY AUDIT PROMPT提示词：当前项目有没有哪些冗余的设计？

请在当前干净的 master 分支上，对项目做一次"只读静态审计"。
先不要修改、删除、格式化或提交任何文件。

目标：回答"当前项目有没有哪些冗余的设计？"
重点不是泛泛评价代码质量，而是找出多次迭代后没有完全退出的旧实现。

请检查：
1. 当前路由、菜单和真实生产入口；
2. 没有生产引用的页面、组件、服务、API 和测试；
3. 同一业务能力的新旧两套命令、模型、配置或状态机；
4. 重复的轮询、重试、路径校验、状态转换和设置存取逻辑；
5. 超大页面、超大服务是否承担了过多职责并制造重复；
6. 启动脚本、跨平台入口、缓存、编译产物和生成代码；
7. 看似重复但实际上承担兼容、快照、审计或领域隔离职责的设计。

每个结论必须提供：
- 文件路径与行号；
- 当前生产入口和调用方；
- 已经替代它的新实现；
- 为什么判断为冗余；
- 删除或合并可能影响什么；
- 建议归类：直接删除 / 标记废弃 / 逐步迁移 / 暂时保留；
- 建议优先级：P0 / P1 / P2。

最后输出：
1. 总体判断和优先级表；
2. 每项冗余的证据与建议；
3. "不应误判为冗余"的设计；
4. 分批清理顺序；
5. 本次实际检查过的命令，以及未运行的测试。

没有文件和调用证据时，不要下结论；不确定时标记"待人工确认"。

EVIDENCE GATE 没有"入口 + 引用 + 替代实现 + 风险"四项证据，就不能建议删除。

尤其是权限、租户、审计、规则快照、兼容查询表和领域 Job，看起来重复并不代表可以合并。AI 必须先证明它理解这些结构为什么存在。

真实示例：一次静态审计找出的七类冗余

下面是某档案管理项目在干净的 master 上执行只读静态审计后的结果。它的价值不在具体文件名，而在于输出同时包含数量、生产入口、替代方案和清理风险。

优先级	冗余点	审计判断	下一动作
P0	无生产入口的旧页面、组件和测试	明确冗余，约 1907 行生产代码和 2333 行陈旧测试	再次核对动态引用后分批删除
P0	Git 中误提交的缓存和编译产物	明确冗余，会持续制造无意义 Diff	从 Git 索引移除并核对忽略规则
P1	新旧两套 PDF 拆分命令链并存	业务架构双栈，旧前端函数已无生产调用方	先废弃旧入口，再收口到新 Job 服务
P1	`LlmConfig` 与 `ModelProviderConfig` 双配置体系	一次性迁移逻辑已经变成长期运行时负担	正式迁移数据，删除查询期兼容
P1	多套前端任务轮询实现	间隔不同合理，但生命周期和并发控制重复	抽取统一 `useJobPolling`
P1	多个超大页面和超大服务	不属于死代码，但职责过多，持续制造隐性重复	按业务用例和领域边界拆分
P2	执行模式、路径校验和状态转换函数重复	规模较小，但安全策略可能逐渐不一致	统一基础机制，保留业务语义

01无生产入口代码：AI 不能只搜文件名，还要从路由和真实引用反推展开 / 收起

审计先从 frontend/src/router/index.ts 建立当前页面清单，再反向检查组件引用，发现 FileInspector.vue、ArchiveTray.vue、CabinetRuleSettingsDialog.vue、旧任务列表和详情页等已经没有生产入口。

生产代码约 1907 行

旧页面、旧组件和没有入口的设置面板。

对应测试约 2333 行

仍在验证已经退出生产路径的旧实现。

第一轮收益约 4240 行

删除前先把仍有价值的行为测试迁到当前组件。

不能机械删除：某设置面板虽然没有入口，但运行时仍读取它对应的配置。此时必须决定"恢复编辑入口"还是"取消可配置设计"，不能只删 UI 留下半套能力。

02PDF 拆分双链路：结果关系表可以留，旧执行入口必须退出展开 / 收起

OLDTask Step + split_service

旧的 SPLIT_PDF/start、summary、results 和前端 startSplit 等函数仍留在仓库。

→

NEWPdfSplitJobService

当前 UI 已使用独立 Job、详情页、文件、分段、页面决策和日志模型。

正确处理不是一次删除所有旧模型，而是先停旧命令入口、检查外部调用方，把执行统一到新服务；仍被文件详情使用的 PdfSplitResult 可以暂时作为结果关系表保留。

03配置双栈：一次性迁移不能永久藏在每次查询里展开 / 收起

旧的 LlmConfig 和新的 ModelProviderConfig 同时存在，新配置查询还会尝试从旧表自动迁移。原本应该执行一次的数据库迁移，因此变成了长期兼容路径。

通过正式数据库迁移写入新模型。
所有业务统一从 provider resolver 读取配置。
删除旧前端 API 和旧后端接口。
明确隐藏设置到底应该正式开放还是彻底移除。

04重复基础设施：业务间隔可以不同，轮询生命周期不必复制五遍展开 / 收起

多个页面分别实现启动、停止、终态判断、卸载清理、静默刷新和异常处理。建议统一成可配置的 useJobPolling，至少处理页面隐藏暂停、请求互斥、任务切换取消和终态自动停止。

useJobPolling({
    load,
    shouldContinue,
    interval: 2000,
    immediate: true,
    pauseWhenHidden: true
})

05"上帝文件"：不能直接删除，但要识别它正在制造多少重复展开 / 收起

示例项目中五个最大文件合计超过 1.5 万行。扫描服务同时处理发现、OCR、额度、进度、暂停恢复和失败重试；生命周期服务同时处理清单、计划、执行、复核、质检和交付物。

审计结论不应只是"文件太长"，而要给出按用例拆分的目标，例如 coordinator、discovery、progress、checkpoint、recognition pipeline 和 retry service。

06小型重复：统一存取机制，不要强行统一业务语义展开 / 收起

路径校验、文件 ID、状态转换和枚举设置存取等辅助函数适合收口，尤其路径安全策略不能存在多个略有差异的版本。但档案整理和 PDF 拆分仍应拥有各自的执行模式、默认 Agent 和请求模型。

07仓库卫生：启动入口和缓存产物也属于架构成本展开 / 收起

跨平台脚本并不天然冗余，但统一入口必须符合平台语义。macOS / Linux、Windows 和 make dev 可以分别保留，Makefile 应按系统分发，而不是在所有平台固定调用 PowerShell。

已经被 Git 跟踪的 SQLite 缓存、__pycache__ 和 .pyc 即使后来写进 .gitignore，仍要从 Git 索引中主动移除。

FALSE POSITIVE CHECK

这些设计看起来重复，但不能被 AI 随手合并

原生 Agent 与工作流 Agent：执行语义和依赖路径不同，不应为了统一重新绑回同一平台。
共享模板与本地实例：一个负责版本控制，一个保存本地配置和认证状态。
任务规则快照与实时规则：任务执行后必须冻结当时规则，不能读取后来修改的设置。
稳定文件 ID 与当前可见列表：稳定 ID 用于保证筛选和重扫后仍指向同一文件。
不同领域 Job 表：可以统一轮询和状态基础设施，但不应强行合并业务字段差异很大的领域模型。

自检报告不是结束，必须转成分批可执行的清理计划

第一批 · 低风险 明确冗余先退出

移除缓存和编译产物
删除确认无入口的旧页面与组件
迁移或删除对应陈旧测试
删除无调用方的前端 API 导出

第二批 · 业务双栈 先废弃，再迁移

记录旧接口调用并通知调用方
新旧链路影子对比
执行入口收口到新服务
观察期后删除旧命令

第三批 · 配置收口 正式迁移数据

编写一次性数据库迁移
统一配置解析入口
删除运行时 bootstrap
明确隐藏功能的产品策略

第四批 · 结构重构 最后拆大文件

先抽统一轮询和安全工具
补行为与契约测试
按用例拆服务和页面
每次只移动一个边界

AUDIT DONE

一次合格的自检不是"AI 说代码有点乱"。它必须能回答：哪里冗余、证据是什么、为什么形成、什么不能删、先清哪一批、如何验证以及怎么回退。

最终判断

AI 开发的胜负手，不在模型，而在工程体系

真正的全流程 AI 开发，不是让 AI 一口气写完整个系统，而是让每个环节都有可靠的 AI 副驾，每次变更都有清晰边界、自动验证、人工责任和知识回流。

先把团队流程变成 AI 可执行的流程，再把核心系统变成 AI 可理解的系统，最后才把稳定业务能力变成 Agent。

理解了 AI 开发的核心逻辑之后，让我们换一个领域——
看看 AI 如何应用于具体的金融场景，解决个贷不良资产的处置难题。