Java 端 RAG 数据摄取管道（解析、切块、嵌入）

• 速率控制与限流
• 失败重试
• 断点续跑与幂等

批量 Embedding 需：速率控制（按 Provider 的 TPM/并发限制限流，用令牌桶/队列控制批次大小与速率）；失败重试（429/限流按指数退避重试，可重试错误重试，不可重试错误记录并跳过）；断点续跑（记录处理进度/水位线，重跑时从断点继续，不重复已成功的块）；幂等（用文档/块 ID 作为去重键，重复处理不产生重复向量）。提交前记录"待处理块"清单，成功后标记完成，失败入队重试，避免重复计费（重试不重复记账）与漏块（失败的块必须重试或标记失败）。

批量管道的关键是"有界速率 + 可靠重试 + 可续跑 + 幂等"。速率防限流，重试防临时失败，断点续跑防重复，幂等防重复计费。进度与去重键是可靠性的核心。

• 增量更新
• 版本一致性
• 删除传播

保证一致性：文档更新时，新版本向量入库与旧版本删除要原子/有序，避免新旧混用。策略：文档带版本号，向量索引用元数据记录版本；更新时先写新版本向量，再删除旧版本向量（或标记旧版本失效，检索时过滤）——保证检索只返回最新版本。删除传播：文档删除时，把其所有块向量按文档 ID 删除，不遗漏。用"版本号 + 文档 ID 索引"实现增量与删除：检索时按当前版本过滤，删除时按文档 ID 批量清理。可加入"可见延迟"（入库到可见的间隔）与对账（定期核对文档与向量一致性）。

一致性核心是"版本隔离 + 删除传播"。版本号让新旧不混用，文档 ID 让删除不遗漏。引入可见延迟与对账兜底，保证索引与源文档最终一致。

• 权限元数据
• 检索期过滤
• 审计

摄取时把权限元数据写入向量记录：tenantId、文档级 ACL、可见范围、权限版本。检索时用这些元数据做过滤（向量库按元数据过滤 + 数据库 RLS/ACL 校验），使检索期过滤可行。权限元数据必须有来源与变更记录（可审计）：记录谁授权、何时、权限版本，权限变更时同步更新相关向量元数据或标记失效。审计覆盖：文档摄取时的权限、权限变更、检索时的授权校验。确保"检索结果 = 用户有权访问的文档"。

权限元数据是"检索期过滤的输入"。摄取时标注权限，检索时过滤，权限变更同步更新，审计记录全程。可审计性保证权限模型可追溯、可验证。

• 摄取指标
• 可观测性
• SLA 设定

摄取管道可观测性应覆盖：解析成功率（文档解析失败率）、切块数分布（每文档块数、块大小分布）、Embedding 延迟（平均/P95）、索引可见延迟（文档入库到可检索的时间）、失败项与重试次数、吞吐。SLA 设定：按管道阶段设定——解析成功率（如 >99%）、可见延迟（如 P95 < 5min）、嵌入失败率（如 <1%）、吞吐（每单位时间处理量）。SLA 要可量化、可监控、可告警，并区分"新鲜度 SLA"（文档多快可见）与"质量 SLA"（解析/嵌入成功率）。

可观测性覆盖"解析→切块→嵌入→可见"全链路，SLA 按阶段设定（新鲜度 + 质量）。指标与 SLA 是摄取管道可靠性的基础，暴露瓶颈与失败。

• 资源隔离
• 线程池/连接池隔离
• 优先级

摄取批任务与在线请求必须资源隔离：独立线程池（摄取用专门的批处理线程池/虚拟线程，在线用响应线程池）、独立连接池（Embedding 客户端、向量库、DB 各用独立连接池，避免争抢）、独立队列与限流。摄取任务限速（限流、批大小）避免占满连接；在线请求有更高优先级与配额。用 Bulkhead 隔离，摄取故障不影响在线查询。监控两者资源占用，防止摄取挤占导致查询延迟。

隔离是"资源维度分离"。批任务与在线请求争抢线程/连接，会互相拖垮。独立线程池、连接池、队列 + 限流保证摄取不拖垮查询，是资源治理的关键。

• 敏感检测
• 脱敏/拦截
• 审计

摄取时做敏感检测（正则/密钥格式/分类器识别个人信息、密钥、令牌）。命中时策略二选一：脱敏（替换/掩码敏感字段后入库，保留可检索性）或拦截（不入库，标记并告警）。同时保留审计记录：文档来源、命中类型、脱敏/拦截动作、处理人/时间、原因。敏感策略可配置（按文档类型/租户），脱敏需保证可检索性（如人名掩码后仍可检索类别）。审计满足合规与追溯。

敏感数据治理是"检测 + 处置 + 审计"。检测识别，脱敏或拦截处置，审计追溯。脱敏需平衡可检索与隐私，拦截适用于高风险。审计证据是合规关键。

• 适合委托的任务
• 不可委托的任务
• 人机分工

适合委托 AI 的：代码解释、样板/胶水代码、测试初稿、迁移分析、重构草稿、文档生成——这些是"可验证、低风险、重复性"的任务。必须由人负责的：架构决策（系统边界、数据模型、技术选型）、安全判断（权限、鉴权、敏感数据、威胁模型）、不可逆操作（删除、迁移）、合规与业务规则。AI 可辅助但不决断。分工原则：AI 做"可验证的产出"，人做"责任决策"；AI 产出需人审查与验证。

分工是"可验证 vs 不可逆/高风险"。AI 适合产出可被编译/测试/审查验证的内容，人必须承担架构、安全、不可逆决策。明确边界避免 AI 越权决定高风险事项。

• 任务描述完整性
• 约束与边界
• 验收标准

向 Coding Agent 提供结构化任务：明确问题（业务动机）、约束（范围、依赖、性能）、验收标准（可验证的完成定义）、允许路径（允许修改的文件/命令）、禁止操作（禁止修改的文件、禁止的命令、禁止的权限）。把边界写清楚，避免 Agent 无边界试错（改无关文件、执行危险命令、越权）。验收标准要可验证（编译、测试、命令输出）。提供"完成定义"（DoD）让 Agent 知道何时停止。

无边界试错来自"边界不清"。明确问题、约束、验收、允许/禁止，让 Agent 在边界内高效执行。可验证的完成定义防止 Agent 无限探索或自述完成。

• 任务拆解
• 业务动机澄清
• 验收标准

委托前拆解：先明确"为什么"（业务动机、目标、用户价值），再确定"做什么"（需求、接口、验收标准）。"为什么"让 Agent 理解意图、避免做错方向；"做什么"给出可验证的验收标准（具体、可测试、包含边界与成功条件）。拆解成可独立验证的子任务，每个子任务有明确输入输出与验收。验收标准应可验证（测试、编译、行为断言），而非模糊描述。动机与验收结合，让 Agent 既理解意图又知道如何验证。

"为什么"解决方向，"做什么"解决验证。拆解成子任务让步骤可验证、可回退。清晰的动机 + 可验证的验收，是高质量委托的前提。

• 高风险任务识别
• 人机分工
• 监督与审批

高风险任务必须由人主导，AI 只能辅助：涉及金钱（支付、退款、定价）、权限（授权、提权、访问控制变更）、数据迁移（生产数据、不可逆变更）、安全相关（密钥、生产配置）、合规与法律。人负责最终决策与执行审批，AI 提供草稿、分析、建议、代码初稿，但最终由人审查、批准、执行。建立"人工审批"机制：高风险操作需人工确认，AI 不能自动执行。审计记录人与 AI 的分工。

高风险任务的边界是"不可逆 + 高影响 + 合规"。人保留决策与执行权，AI 只辅助。人工审批机制是安全治理的关键，防止 AI 越权执行高风险操作。

• 上下文最小化
• 泄密风险
• 依赖信息

"最小充分上下文"指只给 Agent 完成任务所需的最少上下文，兼顾"减少泄密"与"足够依赖"。权衡：充分上下文要包含任务所需的关键依赖（相关文件、接口、约定），否则 Agent 反复试错或走偏；但过多上下文（尤其是无关文件、敏感数据）会增大泄密面与 token 成本。做法：按需提供（只给相关文件/接口/依赖），敏感信息用脱敏/摘要，边界外信息不提供。通过"任务需要什么"而非"全部给"来决定上下文，减少泄密同时保证足够。

权衡是"信息充分 vs 泄密面"。最小充分 = 只给完成任务必需的依赖，敏感信息脱敏。这既保证 Agent 效率，又减少泄密与成本。按需供给是核心原则。

• 任务分解
• 独立验证
• 共享约束

大型任务拆分：按依赖关系/模块边界拆成可独立验证的子任务，每个子任务有明确输入输出、验收标准与依赖，可独立编译/测试。共享约束必须传给每个 sub-agent：仓库规范（风格、命名、hook）、安全红线（禁止操作、敏感数据）、架构约定（分层、接口）、运行环境（命令、依赖）、验收标准与完成定义。共享约束保证各子任务行为一致、不冲突。子任务间依赖明确（谁先谁后），避免并行冲突。

拆分是"可独立验证 + 边界清晰"。共享约束（规范、安全、架构、验收）必须传给每个 sub-agent，保证一致性。依赖关系约束避免并行冲突。

• 权限/范围判断
• 范围膨胀
• 最小权限

当 AI 请求更多文件或权限时，判断："是否与当前任务直接相关"、"是否违反最小权限原则"、"是否可用现有信息替代"。建立审批机制：请求新文件/权限需说明理由，人工审查是否必要；敏感文件/权限默认拒绝，仅按需临时授予。防止范围膨胀：设置范围边界（只读哪些路径、允许哪些命令），超出边界需重新审批；记录授权历史，识别逐步膨胀（爬坡式授权）。用"最小权限 + 审批 + 边界"控制范围。

范围膨胀是"逐步授权"导致的。判断必要性与最小权限原则，审批机制拦截，边界控制。防止"今天多一点、明天多一点"的权限爬坡。

• 并行处理
• 依赖关系
• 冲突避免

多文件改动并行处理需：先做依赖分析，识别文件依赖关系（A 依赖 B、共享文件、接口契约），按依赖拓扑排序（无依赖的并行，有依赖的顺序）；每个 sub-agent 只改自己负责的文件集，避免共享文件（共享文件需协调或串行）；用统一接口契约约束各子任务（先定接口，再并行实现），避免接口冲突；合并时用版本控制与冲突检测。共享文件/接口要先冻结契约，再并行开发。

并行冲突来自"资源竞争"。依赖分析 + 拓扑排序 + 冻结共享契约 + 工作集隔离，避免冲突。共享契约先定，各子任务并行实现，减少合并冲突。

• 规则冲突/过时发现
• 权威来源
• 规则治理

Agent 发现规则冲突/过时：规则文件带版本/来源标记，Agent 检测到冲突时提示（如 AGENTS.md 与 CLAUDE.md 冲突），用"优先级规则"（明确优先级，如 AGENTS.md > 全局 > 插件）消歧。团队维护唯一权威来源：集中管理规则文件（单一仓库），版本化、审查、去重；冲突时以权威来源为准；过时规则定期清理（审计 + 标注 deprecated）。规则变更走评审流程，避免多人各自维护导致漂移。Agent 发现冲突时上报而非随意按某条执行。

规则治理核心是"单一权威来源 + 优先级 + 冲突上报"。集中管理、版本化、优先级消歧，Agent 冲突时上报而非自作主张。防止规则漂移与相互矛盾。

• 权限审批
• 最小权限
• 审计

当 Agent 请求更多权限时：评估必要性（是否任务必需）、风险（读敏感文件/执行危险命令）、最小权限（能否用更小权限替代）。建立审批流程：请求需说明理由，人工审批；高危权限（生产命令、敏感文件、网络）默认拒绝，按需临时授予并设时限。记录授权（谁、何时、授予什么、用途）用于审计。防止"批量授权"——按需授予，避免一次授权过多。权限授予后监控使用，异常回收。

权限治理是"最小权限 + 审批 + 审计 + 时限"。请求需理由与审批，高危默认拒绝、临时授予、时限回收。审计追溯授权。防止权限滥用与泄露。

• 上下文不足的后果
• 上下文过多的后果
• 平衡

不给上下文，AI 缺乏依赖信息（接口、约定、相关文件），只能猜测并反复试错，浪费时间且易产出错误。"给过多上下文"会让 AI 走偏：大量无关信息稀释关键信息，注意力分散，可能关注错误部分、被噪声带偏、产生幻觉或过度设计。平衡：给"最小充分上下文"——只含完成任务所需的关键信息（相关文件、接口、约束、验收），去除无关与噪声。明确"哪些相关"帮助 AI 聚焦。

上下文是"信噪比"问题。太少导致猜测试错，太多导致噪声走偏。最小充分上下文聚焦关键信息，平衡效率与正确性。目标是对齐任务、减少歧义。

• 任务模板
• 输出格式约束
• 结构化 diff

用 Issue/PR 模板约束输出：模板规定必填字段（问题、方案、影响面、测试、验收），要求 Agent 输出结构化信息（改动文件、变更说明、测试结果、风险），避免无结构 diff。模板强制"完成定义"（DoD）与"变更说明"（改动什么、为什么、如何验证），使 diff 可审查、可归因。模板还约束提交规范（小 diff、原子提交、清晰 message）。结构化输出让 review 高效、可追溯。

任务模板是"输出的结构化约束"。通过必填字段与 DoD 强制 Agent 提供可审查信息，避免无结构 diff。结构化输出是高效审查与责任追踪的基础。

• 日志恢复
• 断点续委派
• 失败定位

失败后应利用日志定位失败点（编译错误、测试失败、运行异常），提取已完成的部分与失败信息，重新委派时给出"上次进度 + 失败原因 + 修复方向"，避免从头开始。保存任务中间产物（已改文件、测试、日志），作为恢复上下文。重新委派时明确"在上次基础上继续"，而非重做。用日志缩小假设范围，把失败信息作为新任务的输入。可保存"会话快照"让 AI 从断点继续。

恢复的关键是"保留进度 + 定位失败"。日志给失败原因，中间产物给已完成部分，重新委派带着新上下文继续。避免重复劳动，提高委托效率。

• 硬约束与软建议
• 规则分级
• 强制执行

仓库规则应分级：硬约束（安全红线、不可逆操作、数据隐私、合规）——必须遵守，违反会阻断（CI 门禁、Hook 拦截）；软建议（代码风格、命名、注释偏好）——建议性，可偏离但需理由。用标记（如 [HARD]/[SOFT] 或优先级）区分，配置强制执行机制（硬约束由 Hook/CI 强制，软建议由 lint/提示）。Agent 对硬约束无条件遵守，对软建议可权衡。分级让规则既守住红线又不约束过度。

分级是"安全红线 vs 风格偏好"的区分。硬约束强制（安全、合规），软建议弹性（风格）。强制执行机制 + 明确分级，让 Agent 知道哪些必须守、哪些可权衡。

• 可验证证据
• 自述不可信
• 完成定义

Agent 自述"已完成"不可靠，因为 AI 可能产生幻觉、判断错误或未真正执行。必须要求可验证证据：实际命令输出（编译、测试、lint 的 stdout）、测试报告（通过/失败、覆盖率）、运行截图（UI/行为）。证据让"完成"可验证、可复现、可审计。把"提供证据"作为完成定义与验收标准的一部分，Agent 无法自述完成，必须以输出证明。这防止"看起来完成但实际错误"。

可验证证据是"完成"的证明。自述可能幻觉，证据可复现。完成定义要求"证据驱动"，杜绝自述完成。核心是"可验证而非可声称"。

• 日志驱动定位
• 假设缩小
• 系统化调试

失败后应基于日志系统化定位：编译错误（精确到行与类型）→ 测试失败（断言与用例）→ 运行日志（异常栈、状态）→ 用日志缩小假设范围（哪些代码路径、哪些假设被推翻）。提出可验证的假设，用最小改动验证，而非随机改代码。每次失败记录"假设 → 验证 → 结论"，逐步逼近根因。用二分/最小复现缩小范围，避免反复随机改动。

调试是"日志 → 假设 → 验证"的循环。日志缩小范围，假设可验证，最小改动验证。随机改代码是低效试错，系统化调试才高效。

• 原子提交
• diff 大小控制
• 可撤销

小步修改要求每个提交是原子、可独立验证的，diff 越小越易审查、回滚、归因。控制方法：按单一关注点切分（一个功能/修复一个提交），避免混合改动；大改动拆成多个小提交（重构、实现、测试分开）；diff 大小阈值（如 <200 行）作为约束，超限拆分。每个提交保持可编译、可测试（不引入半成品状态）。小步提交提升可审查性与可回滚性。

原子提交是"小、独立、可验证"。diff 控制让审查高效、回滚精确、归因清晰。拆分关注点与阈值约束，保证每个提交是完整可验证的单元。

• 完成定义
• 可验证证据
• 证据类型

"AI 自述完成"不等于真正完成，因为自述是主观声明，可能源于幻觉、误判或未执行。真正完成需可验证证据：命令输出（编译/build/test/lint 的 stdout）、测试报告（通过数量、断言结果）、运行截图（UI、行为、端到端）、日志（运行日志、trace）。证据使完成可复现、可审查、可审计。完成定义应明确"以证据为准"，Agent 必须提供证据而非自述。证据类型按任务（代码/配置/UI）选择。

完成的判据是"可验证证据"而非"自述"。证据可复现、可审查。把证据纳入完成定义，杜绝"自述完成"。核心是"证明完成而非声称完成"。

• 日志定位
• 错误假设反向
• 根因分析

通过日志反向定位错误假设：编译错误揭示类型/API 假设错误（引用了不存在的接口）；测试失败揭示行为假设错误（断言未满足）；运行时异常揭示状态/环境假设错误（空指针、配置缺失）。从"日志与预期的差异"反推 AI 的错误假设（如假设了错误的 API、错误的数据格式、错误的环境）。把日志作为证据，对照任务要求，找出假设偏差并修正。记录"假设 → 日志 → 偏差"帮助定位。

日志是"假设的证伪工具"。日志与预期差异揭示错误假设。反向定位即从失败反推假设偏差，系统化修正而非盲目改。

• Spec 驱动开发
• 接口/数据/安全/回滚
• 设计文档

RFC/Design Doc 应包含：接口（API 定义、请求/响应、错误码、版本）、数据（数据模型、存储、迁移、一致性）、安全（鉴权、权限、敏感数据、威胁模型）、回滚（回滚方案、兼容性、灰度）。这些约束让设计可评审、实现可对齐、变更可回滚。Spec 先于实现，作为实现与测试的基准。安全与回滚约束是硬性要求，接口与数据是契约。Design Doc 评审通过后进入实现，避免边做边改。

Spec 驱动是"先设计后实现"。接口、数据、安全、回滚四要素构成完整契约，让实现可对齐、可评审、可回滚。安全与回滚是变更的底线。

• Plan/Act 分离
• 破坏性操作审查
• 重新审批

Plan 与 Act 分离让 Agent 先输出计划（改动、影响面、测试计划），人工审查后再执行，从而在"执行前"审查潜在破坏性操作（删除、强制推送、改生产配置、迁移）。重新审批时机：计划与实际偏离（新发现破坏性操作）、范围扩大（涉及未计划的文件/权限）、风险上升（新增高危操作）、深层依赖变化。重新审批让破坏性操作不经手就执行。分离机制保证"先审后执行"。

Plan/Act 分离是"执行前审查"的机制。破坏性操作在计划中暴露，审查拦截。偏离计划/范围扩大/风险上升时重新审批，防止计划外破坏性操作。

• diff 控制
• 提交边界
• 可撤销与归因

控制：diff 小（单一关注点、<200 行）、提交边界清晰（一个功能一个提交）、回归范围明确（影响面测试）。可撤销：每个提交可独立回滚（revert），不依赖其他提交；可归因：提交关联任务/Agent/版本，记录变更说明。按"可撤销、可归因"设计提交，保证每一步安全。回归范围通过影响面分析确定测试集，避免遗漏。

可撤销与归因来自"原子提交 + 清晰边界"。小 diff、单一关注点、回滚独立、变更归因，让每一步可控、可追溯。回归范围明确保证变更验证充分。

• 危险操作识别
• 审批粒度
• 审批机制

危险操作必须重新审批：删除（文件、数据、分支）、强制推送（--force）、改生产配置、数据迁移、权限变更、网络/外部操作、不可逆命令。审批粒度：按"风险等级"界定——高危操作（不可逆、影响生产）需人工审批；中危需确认；低危可自动。审批到"具体操作"而非"整个计划"，粒度过粗（整个计划）会漏掉危险操作，过细（每行）则繁琐。危险操作设审批清单，计划中包含时强制审批。

审批的核心是"危险操作拦截"。按风险等级界定审批粒度，高危人工审批、低危自动。审批到具体危险操作，避免漏审与过度繁琐。

• Plan 产物
• 人工评审
• 评审后执行

让 Agent 的 Plan 阶段产出结构化产物：diff preview（改动预览）、影响面（改动影响哪些模块/依赖）、测试计划（验证方案）、风险与回滚。这些产物进入人工评审流程（如 PR/评审工作流），评审通过后才允许执行。机制：计划产物存为可审查的工件（文件/PR），评审人确认后解锁执行；执行可自动或半自动。评审通过是"门禁"，未通过则反馈修改计划。Plan 产物可执行、可审查、可审计。

关键是"评审门禁"。Plan 产物可审查（diff、影响面、测试计划），评审通过才执行。把评审设为执行前提，保证破坏性操作经手。结构化产物提升评审效率。

• 断言完整性
• 同源实现
• 测试有效性

测试"全部通过"不能证明有效，可能断言迎合当前实现（同源实现、空断言、只测 happy path）。确认方法：审查断言是否覆盖需求（输入/输出/边界/错误路径），检查断言强度（非空断言、具体值、逆向验证）；用"变异测试"（改实现看测试能否捕获）验证测试有效性；审查测试是否与实现同源（复用实现逻辑推导断言）；用需求用例（而非实现）设计断言。加入边界用例与失败路径测试，避免只测 happy path。

测试有效性是"能否捕获缺陷"。断言覆盖需求而非实现，变异测试验证，避免同源与空断言。测试的价值在于"能抓住错误"，而非"通过"。

• 探索原型隔离
• feature branch
• 短生命周期

探索原型（vibe coding）应隔离在 feature branch，避免直接进 main。最佳实践：prototype 用独立分支/或临时分支，短生命周期（快速迭代、快速验证、快速废弃）；验证通过后经评审/测试再合并进 main；原型明确标记（如 @Initial 或 prototype 目录），不污染主干；原型不与生产代码混。短生命周期防止长期分支的合并冲突与漂移。原型验证后的"教训"沉淀为正式实现。

探索与生产隔离是"分支隔离 + 短生命周期"。原型在 feature branch 快速迭代，验证后受控合并，避免污染主干。短生命周期减少冲突与漂移。

• 效率指标
• 生成量 vs 质量
• 小步价值

"AI 生成代码量"不反映真实效率，因为大量代码可能质量差、需返工、审查负担重。真实效率应衡量"通过审查 + 测试通过"的有效产出（小步、可验证、可合并）。大量生成想当然地迎合"产量"但制造返工与风险。小步（小 diff、可验证）通过审查与测试，才是真正推动进度的产出。用"有效产出"（合并的、通过的）而非"生成量"衡量效率。

效率指标应反映"有效产出"而非"生成量"。生成量可能制造返工，小步通过审查与测试才是有效推进。衡量"投产的、通过的"而非"生成的"。

• 空断言
• happy path only
• 断言完整性

避免空断言与 happy path only：建立断言完整性 checklist——每个测试有明确断言（非空、具体值、异常）；覆盖正常路径、边界（空、极值、最大）、错误路径（异常、错误输入）、状态转换（幂等、顺序）；断言结果而非实现细节；用逆向/多值验证（断言具体输出）。review 时检查断言强度，杜绝"没有断言/只测成功"。用需求用例设计断言，覆盖各分支。

断言完整性是"测试有效性"的保障。checklist 覆盖"有断言、边界、错误、状态"维度，避免空断言与 happy path。审查断言强度，保证测试能捕获缺陷。

• Plan 阶段安全评审
• 风险暴露
• 安全门禁

让 Plan 阶段包含安全审查：要求 Agent 在计划中列出——引入的依赖（版本、许可证、风险）、涉及的数据访问（权限、敏感数据）、暴露的接口（鉴权）、部署与配置（密钥、权限）。用安全 checklist 引导 Agent 暴露风险，计划评审时审查安全项。把安全风险纳入 Plan 产物（依赖清单、安全影响、威胁分析），评审通过才执行。CI 中集成 SCA（依赖漏洞）、secret 扫描，配合 Plan 安全审查。

Plan 阶段暴露安全是"前置审查"。通过安全 checklist 让 Agent 在计划中列出依赖、权限、数据、接口风险，评审拦截。配合 SCA/secret 扫描自动检测。

• 代码标记
• 探索与生产区分
• 可追溯

探索性代码应明确标记：注释（说明是探索/原型、未验证）、TODO（遗留待办）、AI-Generated 标记（标识来源，便于审查与追溯）。标记让代码可区分"探索"与"生产"，避免误把原型当生产；待办项可追踪；AI 来源可审计。标记规范化（统一格式），探索代码尽量隔离（分支/目录），转正时移除标记并补充测试。

标记是"可追溯与可区分"。探索/原型/ AI 来源标记 + TODO，让代码状态清晰、可审查、可追溯。转正时清理标记并补测试。

• ETL 管道组织
• 切块策略
• 配置化

Spring AI 的 ETL 管道按 Reader→Transformer→Writer 组织：Reader 读取源文档（PDF、Word、Web），Transformer 做解析、切块、清洗、结构化，Writer 写入向量库/存储。切块策略选型：按 token（固定大小，简单、控制请求大小）、按语义（按段落/标题，保留语义完整性）、父子块（父子分别索引，检索父块上下文，适合长文档）。可配置化：通过配置选择切块策略与参数（块大小、重叠、策略），按文档类型/业务调整。管道组件可组合、可配置、可测试。

ETL 管道是"读取→转换→写入"的流水线。切块策略影响检索质量，按 token 简单、语义保留上下文、父子块增强长文档。配置化让策略按场景调整。

• 双写
• 影子对比
• 无缝升级

Embedding 升级需回填（用新模型重新嵌入所有文档）且不中断服务。做法：双写——新文档同时用新旧模型嵌入，写入新索引；影子对比——回填时新旧向量并行检索，对比结果质量（召回、相关性），验证后再切换。策略：先建新索引（新旧并行），影子对比评估，达标后切换检索到新索引并停旧索引；回填任务分批进行，不阻塞在线。版本标记（embedding 版本）区分新旧向量，保证检索只用同版本向量（避免向量空间不匹配）。

无缝升级的关键是"双写 + 影子对比 + 版本隔离"。新旧并行、影子对比验证、分版本切换，避免向量空间不匹配与中断。版本标记保证检索一致性。

• 成功信号
• 可验证性
• 反馈闭环

为 Agent 提供可验证的成功信号：明确的测试命令（运行后输出通过）、日志（可检查关键状态）、截图（UI/行为验证）。成功信号让 Agent 能自验证"是否完成"，形成反馈闭环。信号要具体、可执行（Agent 可运行并检查）、可判读（知道的成功标准）。把成功信号写入完成定义，Agent 依据信号判断完成而非自述。信号也用于人工验收。

成功信号是"Agent 的自验证手段"。测试/日志/截图作为可验证的成功标准，让 Agent 判断完成、形成闭环。信号可执行、可判读、可验收。

• 完成定义
• 可验证性
• 运行结果

完成定义要可验证：用"编译通过"、"测试通过（含边界）"、"Lint 无错误"、"运行结果符合预期"等客观标准，而非主观描述。写清楚"如何验证"（命令、断言、预期输出），让 Agent 与审查者都能执行验证。完成定义包含：成功标准（通过命令）、边界（哪些用例）、质量（lint/覆盖率）、验收动作。可验证的完成定义让"完成"可判据、可复现。

完成定义的价值在于"可客观验证"。用编译/测试/lint/运行结果作为判据，写明验证方式，避免主观自述。可执行、可判读、可复现。

• 开发闭环
• 小步迭代
• 审查

执行闭环：先澄清问题（明确需求/边界）→ 制定计划（改动、影响、测试）→ 小步修改（小 diff、原子提交）→ 编译（即时反馈）→ 测试（验证）→ 审查（评审、反馈）。每步小循环，快速反馈、易回滚、可归因。避免一次性大改（难审查、难定位、风险高）。闭环强调"小步快跑 + 每步验证"，问题澄清避免方向错误，审查保证质量。

闭环是"小步 + 验证 + 评审"。小步修改降低风险，编译/测试即时反馈，审查保证质量。避免大改的难审查与高风险。小步迭代是高效开发的关键。

• 解析工具
• 表格/图片/OCR
• 失败隔离

Java 解析：Apache Tika 处理多格式（PDF/Word/HTML），PDFBox 处理 PDF 底层（表格、图片）。表格：提取结构化格式（保留行列，或转为文本/表格标记）；图片与扫描件：OCR（Tesseract）提取文字，但准确率有限需评估；HTML 用解析器提取正文。解析失败隔离：单文档失败不阻塞整批——记录失败、重试、跳过并标记，批任务继续；失败文档单独重试/告警。设置解析超时与大小限制，防止单个文档拖垮批。

解析是"多格式 + 复杂内容 + 失败隔离"。表格/图片/OCR 需专门处理，失败隔离（单失败不阻塞批）保证吞吐。超时与限制防单文档拖垮。

• 幂等设计
• 去重键
• 重跑一致性

幂等设计：用文档/块唯一 ID（如文档哈希 + 块序号）作为去重键，写入向量时带唯一键；向量库支持 UPSERT（按唯一键覆盖）或先查再写，重跑同一文档时覆盖而非追加，避免重复向量。进度记录（已处理块 ID）与去重表保证重跑不重复。Spring Batch 用 JobInstance/Step 幂等，消息消费用幂等消费（去重表）。重跑时先清理旧版本再写入新版本（或按版本覆盖）。

幂等核心是"唯一键 + UPSERT/覆盖"。重跑同一文档按唯一键覆盖而非追加，进度与去重表防重复。Spring Batch 与消息消费的幂等机制保证重跑一致。

• 增量同步
• 水位线
• 删除传播

增量同步用水位线（记录上次同步位置/时间戳）与变更事件（源系统的变更通知、lastModified、webhook）识别新增/变更文档。水位线推进：同步成功后才推进，避免丢变更。删除传播：源文档删除时，通过变更事件/删除列表识别，同步移除对应向量与索引（按文档 ID 删除），避免孤儿向量。S3 用事件/对象版本，Confluence 用 API + 时间，数据库用变更日志（CDC）。增量减少全量成本，删除传播保证一致性。

增量同步是"水位线 + 变更事件"。水位线识新增/变更，删除传播移除孤儿向量。增量提效、删除一致。CDC/事件驱动是增量同步的关键。

• 规则分层
• 版本化
• 审查

仓库规则分层：全局规则（用户级，跨项目）、项目规则（AGENTS.md，仓库级）、工具规则（CLAUDE.md、Cursor Rules，工具特定）、目录规则（子目录）。分层明确适用范围与优先级（项目 > 全局，具体 > 通用）。规则与代码一起版本化（存仓库、走 PR 审查、可回滚），防止规则漂移。规则变更走审查流程（同代码 review），保证规则质量与可追溯。

规则分层是"适用范围 + 优先级"。版本化 + 审查防漂移，规则随代码演进。规则即代码，需评审、可回滚、可追溯。

• 原型转正时机
• 正式化流程
• 门禁

原型应停止 Vibe Coding 并转正：当原型被验证可行、需要进入生产/多用户使用时。转正时机：功能验证通过、开始被正式依赖、需要稳定性/安全/合规时。转正流程：写正式规格（需求、接口、约束）、补测试（单元/集成/边界）、加安全门禁（SCA、secret、权限评审）、清理探索代码与标记、评审后合并。明确"探索何时结束"的判据（验证完成、进入生产），避免草率转正或无限探索。

转正判据是"验证通过 + 进入生产"。转正需正式规格、测试、安全门禁，清理探索痕迹。明确时机避免"原型直接上线"的风险。