概述

系列定位：在项目中要搭建出完整的Harness Engineering四层文档体系，基本分为6步，接下来我会通过本系列共 6 篇文章，指导从零搭建 Harness Engineering 四层文档体系，最终实现从 BRD/PRD 到代码交付的一站式 AI 开发与自检闭环。

本篇定位：第 1 步——在编写任何业务代码之前，建立项目入口文件和架构基线文档，为后续所有文档和 AI Agent 行为提供锚点。

1. 为什么第一步是"项目入口 + 架构基线"

1.1 核心问题

当你用 IDEA 新建一个 Java 项目时，面对的是空工程。此时 AI Agent 对你的项目一无所知：

  • 项目用什么技术栈？版本是什么？
  • 模块怎么划分？依赖方向是什么？
  • 数据怎么流转？有哪些核心流程？
  • 代码资产有哪些基类和接口可以复用？

如果这些信息不存在，后续的 Rules 层（硬性约束）无从写起——因为你无法约束一个尚未定义的架构。

1.2 本步要解决的三件事

问题解决方式产出文件
AI Agent 不知道项目"是什么"编写项目入口文件AGENTS.md、README.md
AI Agent 不知道"怎么分层"编写架构知识文档docs/architecture/overview.md、boundaries.md、data-flow.md、code-assets.md
所有 .md 文件缺乏统一的元信息规范建立文档元信息 front matter 规范每个文件的 YAML 头

2. 需要创建的文件清单

项目根/
├── AGENTS.md                              # AI Agent 项目入口
├── README.md                              # 项目整体说明
└── docs/
    └── architecture/
        ├── overview.md                    # 系统架构概览
        ├── boundaries.md                  # 模块边界与依赖约束
        ├── data-flow.md                   # 数据流转路径
        └── code-assets.md                 # 代码资产清单

共 6 个文件，全部是 Markdown 文档，不涉及任何代码。

3. 逐个文件编写指南

3.1 AGENTS.md— AI Agent 的"第一印象"

定位

AGENTS.md 是 AI Agent 进入项目后读取的第一个文件，类似于人类新员工的"入职手册"，AGENTS.md是写地图，不是写百科全书。它必须在一屏内传达：项目是做什么的、技术栈是什么、去哪里找更多信息。

关键设计原则
  • AGENTS.md 控制在 50-100 行。超过就说明你在写百科全书了
  • “你想做什么 → 去哪里看” 比 "这是什么"更有效——面向任务而非面向知识
  • 硬性规则单独列出，这些是 CI 会强制验证的，不是 “建议”。
必须包含的章节
# AGENTS.md

## 项目简介
{一段话描述项目做什么、解决什么问题、核心技术选型}

## 技术栈基线（不允许擅自升级）
- JDK: {版本}
- Spring Boot: {版本}
- {其他关键依赖及版本}
{每个版本后标注"不可升级"的约束}

## 快速导航
| 你想做什么 | 去哪里看 |
|-----------|---------|
| 查看 Rules 层规则 | .qoder/rules/*.md |
| 查看 Skills 层技能 | .qoder/skills/*.md |
| 了解系统架构 | docs/architecture/*.md |
{...}

## 硬性规范（CI 强制验证，违反即拒绝合并）
| 规则 | 禁止 | 验证方式 |
|------|------|---------|
| 模块依赖只能向上：common→dal→business→ext→app→runner | 反向依赖/跨层引用 | ArchUnit |
| JSON 统一用 FastJSON 1.2.83 | Jackson / Gson | PMD |
| HTTP 统一用 OkHttp3 + HttpClientFactory | RestTemplate / Apache HttpClient | PMD |

## 提交规范
- feat: 新功能
- fix: 修复 Bug
- refactor: 重构
- docs: 文档变更
- test: 测试
- chore: 构建/配置
编写要点
  1. 技术栈基线必须精确到版本号：AI Agent 会严格遵循这些版本约束。如果写 JDK 1.8，AI 就不会用 var、record 等 Java 9+ 语法。当技术栈多时可以单独放入一个文档
  2. 快速导航表是文档索引的入口：后续 5 步创建的所有文档都要在此表中注册
  3. 保持精简：控制在 50~100 行以内，AI Agent 每次任务都会加载此文件
实际示例
---
last_updated: 2026-06-26
status: active          # active | deprecated | draft
owner: @zhangsan
---

# AGENTS.md

## 项目简介
第三方数据交换平台，对接XXX/XXX/XXX等供应商，完成数据采集、加工、分片批量编排与结果持久化。

## 技术栈基线（不允许擅自升级）
技术栈基线详见 `.qoder/rules/always-on.md` 第 1 节（JDK 1.8 / Spring Boot 2.3 / MyBatis-Plus 3.4 / FastJSON 唯一 / OkHttp3 统一）。

## 快速导航（你想做什么 → 去哪里看）

| 你想做什么 | 去哪里看 |
|-----------|---------|
| **— Rules 层（始终生效，CI 强制验证）** | |
| 写代码前确认技术红线 | .qoder/rules/always-on.md |
| 确认开发流程顺序/门禁 | .qoder/rules/agent-workflow.md |
| 不确定类/方法怎么命名 | .qoder/rules/java-code-style.md |
| 写测试时不确定框架/Mock 策略 | .qoder/rules/java-testing.md |
| **— Skills 层（按场景触发）** | |
| 收到 PRD 要开发 | .qoder/skills/prd-to-code.md |
| 全流程编排/断点恢复 | .qoder/skills/flow-orchestration.md |
| 设计文档写好了要评审 | .qoder/skills/design-review.md |
| 新增供应商对接 | .qoder/skills/add-vendor-adapter.md |
| 新增数据库表 | .qoder/skills/add-entity-mapper.md |
| 新增对外 API 接口 | .qoder/skills/add-api-endpoint.md |
| 提交前检查文档健康度 | .qoder/skills/doc-gardening.md |
| 交付前自动治理巡检 | .qoder/skills/auto-governance.md |
| **— Wiki 层（按需查阅）** | |
| 设计新功能前查有哪些基类可复用 | docs/architecture/code-assets.md |
| 确认模块归属和依赖方向 | docs/architecture/boundaries.md |
| 设计功能时参考数据怎么流转 | docs/architecture/data-flow.md |
| 不确定异常怎么抛/错误码怎么定 | docs/conventions/error-handling.md |
| 不确定日志格式/traceId 怎么传 | docs/conventions/logging.md |
| Linter 报错后查规则详情和修复指引 | docs/conventions/linter-rules.md |
| 写 PRD 时参照模板 | docs/reference/prd-template.md |
| 业务方提需求时参照 BRD→PRD 指南 | docs/reference/brd-to-prd-guide.md |
| 查/新增错误码 | docs/reference/error-codes.md |
| 查/新增 API 定义 | docs/reference/api.spec.yaml |
| 写设计文档时用模板 | docs/design/_template.md |
| PR 提交前逐项自检 | docs/changes/pr-checklist.md |
| 变更前做影响分析 | docs/changes/impact-analysis.md |
| 了解整体 AI Coding 开发流程 | docs/ai-coding-guide.md |
| **— 自动化层脚本** | |
| 环境前置检查 | build/automation/scripts/pre-check.ps1 |
| Git Worktree 自动化管理 | build/automation/scripts/worktree-manager.ps1 |
| 采集构建/测试/Linter 客观数据 | build/automation/scripts/collect-sidecar.ps1 |
| 自动衰减检测 | build/automation/scripts/decay-detector.ps1 |
| 生成治理报告 | build/automation/scripts/governance-report.ps1 |
| 文档全景索引一致性检测 | build/automation/scripts/index-sync-check.ps1 |
| **— 代码定位** | |
| 找启动入口 | exchange-runner/.../WebApplication.java |
| 找 HTTP 控制器 | exchange-runner/.../controller/ |
| 找 SOA 同步单笔服务 | exchange-soa-service/.../SyncSingleService.java |
| 批量调度入口（XXL-JOB） | exchange-runner/.../ShardingScheduler.java |
| 找供应商适配器 | exchange-ext/exchange-ext-{tianchuang,youmeng,baihang}/ |
| Maven 环境与 Nacos 配置 | pom.xml (profiles 章节) |

## 硬性规则（CI 强制验证，违反即拒绝合并）

| 规则 | 禁止 | 验证方式 |
|------|------|---------|
| 模块依赖只能向上：common→dal→business→ext→app→runner | 反向依赖/跨层引用 | ArchUnit |
| JSON 统一用 FastJSON 1.2.83 | Jackson / Gson | PMD |
| HTTP 统一用 OkHttp3 + HttpClientFactory | RestTemplate / Apache HttpClient | PMD |
| 数据库用 DalManager.of(beanName) | 直接注入 Mapper | PMD |
| 事务用 TransactionTemplate 编程式 | @Transactional 注解 | PMD |
| 日志用 @Slf4j + 占位符 | LoggerFactory / System.out | Checkstyle |
| 注入用 @Resource / 构造器 | 字段级 @Autowired | Checkstyle |
| 线程池用 BatchExecutorTemplate / Builder | 裸 new ThreadPoolExecutor | PMD |
| 限流用 Resilience4j + RateLimitFactory | 自行实现限流 | PMD |
| traceId 用 @MDC + ContextHolder | 线程切换丢失 traceId | PMD |
| 配置用 Nacos | 硬编码环境地址/密钥 | Checkstyle |
| commit 前缀：feat/fix/refactor/docs/test/chore | 无前缀或不规范 | Git Hook |
| 交付前必须通过自动治理巡检 | 跳过巡检直接交付 | agent-workflow.md §8 |
| 完整规则 → `.qoder/rules/` 全部 4 个文件 | | |

关键提醒：此文件会在后续步骤中持续更新——每新增一个 Rules、Skills 或 Wiki 文件，都要在"快速导航"表中注册对应条目。

3.2 README.md — 面向人类的入口

定位

README.md 面向人类开发者（非 AI），提供项目概览、模块拓扑、启动方式和环境准备。与 AGENTS.md 互补：AGENTS.md 偏"约束"，README.md 偏"说明"。

建议包含的章节
  • 项目简介（1~2 段话）
  • 模块拓扑图（ASCII 或 Mermaid）
  • 技术栈表（与 AGENTS.md 一致，但可更详细）
  • 环境准备（JDK、Maven、MySQL、Redis 版本要求）
  • 启动方式（本地开发、测试、生产）
  • 模块说明链接（指向各模块的 readme.md）
实际示例
---
last_updated: 2026-06-26
status: active
owner: @zhangsan
---

# app-exchange-port

第三方系统数据交换平台，对接天创/友盟/百行等外部供应商，完成数据采集、加密转换、分片批量编排与结果持久化。

## 技术栈

| 层面 | 选型 |
|------|------|
| JDK | 1.8 |
| 框架 | Spring Boot 2.3.12 + Spring Cloud Hoxton.SR12 + Alibaba Cloud 2021.1 |
| 持久化 | MyBatis-Plus 3.4.3 + MySQL 8.0.28 + Dynamic Datasource |
| 缓存 | Redis + Caffeine |
| 调度 | XXL-JOB 2.2.0 |
| HTTP | OkHttp3 3.14.9（统一客户端） |
| JSON | FastJSON 1.2.83（唯一序列化库） |
| 限流 | Resilience4j |
| 配置中心 | Nacos |
| 测试 | JUnit 5.6.3 + Mockito 3.12.4 |

> 完整技术约束见 `.qoder/rules/always-on.md`

## 模块结构

依赖只能向上流动，严禁反向依赖或跨层引用：
common → dal → business → ext → app → runner          （Web 部署链路）
common → dal → business → ext → soa-service → app-soa → deploy-set  （SOA 部署链路）

| 模块 | 职责 |
|------|------|
| exchange-common | 通用基础设施：trace / juc / cache / scheduler / http / sentinel / event |
| exchange-dal | 仓储层：entity / mapper / manager / datasource |
| exchange-business | 核心业务层：core(async/sync/lifecycle) / base / ext / infra |
| exchange-ext | 供应商适配层：tianchuang（天创）/ youmeng（友盟）/ baihang（百行） |
| exchange-app | 应用编排层：config / trigger / admin / facade |
| exchange-runner | Web 部署包：WebApplication + controllers |
| exchange-api | SOA 接口契约（独立发布，仅依赖 Lombok） |
| exchange-soa-service | SOA 服务实现：SyncSingleService + RateLimitDelegate |
| exchange-app-soa | SOA 应用配置 |
| exchange-deploy-set | 部署集合（pom 聚合）→ exchange-soa-runner |
| exchange-test | 集成测试集 |

## 快速开始

### 环境要求

- JDK 1.8
- Maven 3.6+
- MySQL 8.0
- Redis
- Nacos（⚠️ exchange-test 模块下的 `app-exchange-port.yml` 需与 Nacos 上 `namespace=dev1` 保持一致）

### 构建

```bash
mvn clean package -DskipTests

### 启动

项目有两个部署入口：

| 部署形态 | 启动类 | 模块 | 用途 |
|---------|--------|------|------|
| Web 应用 | `com.jzsk.exchange.WebApplication` | exchange-runner | 批量调度、手动触发、管理运维、监控 |
| SOA 服务 | `com.jzsk.exchange.SoaRunner` | exchange-deploy-set/exchange-soa-runner | 同步单笔请求（Dubbo/HTTP） |

## 运维接口

| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 批量执行 | GET | `/schedule/triggerBatch/{YYYY-MM-DD~HH}/{planId}/{sourceIds}` | 手动触发批量数据交换。时间到小时，如 `2024-12-23~09` |
| 数据分片 | GET | `/schedule/trigger/{clusterSize}/{clusterIndex}` | 指定集群规模和机器索引执行分片 |
| 监控面板 | GET | `/monitor` | 查看线程池（阻塞任务数/线程参数）、全局配置、业务配置 |
| ⚠️ 重置数据 | GET | `/schedule/reset/{YYYY-MM-DD~HH}/{tb_name}` | 清理目标表数据，**仅限测试环境**。时间作为验证密码，`{tb_name}` 为目标表名 |

> **日志排查**：基于 traceId 查找上下文，主/子线程 traceId 可关联查询，搜索关键词 `start,parentTraceId=` 或 `start,preTraceId=`

## 重要配置

| 配置项 | 说明 | 备注 |
|--------|------|------|
| `exchange.biz.global` | 全局业务配置 | — |
| `exchange.biz.global.close` | 全局开关 | 关闭后阻塞下一批扫描 |
| `exchange.biz.global.executors` | 线程池配置 | ⚠️ 阻塞队列数不可修改 |
| `spring.redis` | Redis 客户端配置 | ⚠️ 目前不可动态修改 |
| `spring.redis.pool` | Redis 连接池 | — |
| `xxl.job` | XXL-JOB 分布式调度配置 | — |

## 开发指南

| 你想做什么 | 去哪里看 |
|-----------|---------|
| 了解 AI Coding 规范化开发流程 | [docs/ai-coding-guide.md](docs/ai-coding-guide.md) |
| AI Agent 项目入口（导航地图） | [AGENTS.md](AGENTS.md) |
| 查看技术红线和 CI 验证规则 | `.qoder/rules/always-on.md` |
| 了解系统架构和数据流转 | [docs/architecture/overview.md](docs/architecture/overview.md) |
| 确认模块边界和依赖方向 | [docs/architecture/boundaries.md](docs/architecture/boundaries.md) |
| 查看可复用的基类/接口清单 | [docs/architecture/code-assets.md](docs/architecture/code-assets.md) |

## 文档目录

docs/
├── architecture/    架构知识（overview / boundaries / code-assets / data-flow）
├── conventions/     编码规范（naming / error-handling / testing / logging / linter-rules）
├── design/          功能设计文档（_template + feature-*.md）
├── reference/        参考资料（prd-template / api.spec.yaml / error-codes）
├── changes/          变更管理（pr-checklist / impact-analysis）
└── plans/           迭代计划（current-sprint / backlog）

## 变更记录

见 [CHANGELOG.md](CHANGELOG.md)

3.3 docs/architecture/overview.md — 架构概览

定位

这是 Wiki 层的第一个文档，为 AI Agent 提供系统全局视角。AI Agent 在 PRD 解析阶段会加载此文件理解项目全貌。

必须包含的章节
章节内容为什么 AI 需要知道
定位项目解决什么问题帮助 AI 理解业务上下文
技术栈明细全部技术选型及版本决定 AI 能使用哪些技术
模块全景所有 Maven 模块及其职责AI 需要知道代码放在哪个模块
部署入口启动类和部署形态AI 需要知道在哪里暴露接口
核心流程一句话概括主要业务流程AI 需要理解数据流转方向
编写模板
---
last_updated: 2026-06-29
status: active
owner: @zhangsan
---

# 系统架构概览

## 定位
{一段话：项目解决什么问题，核心能力是什么}

## 技术栈
| 层面 | 技术选型 |
|------|---------|
| JDK | 1.8 |
| 框架 | Spring Boot 2.3.12 + Spring Cloud |
| 持久化 | MyBatis-Plus + MySQL |
| 缓存 | Redis + Caffeine |
| HTTP | OkHttp3 + HttpClientFactory |
| JSON | FastJSON |
| 配置中心 | Nacos |
| 测试 | JUnit 5 + Mockito |

## 模块全景
{ASCII 图或 Mermaid，展示所有 Maven 模块及其层次关系}

## 部署入口
| 部署形态 | 入口类 | 模块 | 职责 |
|---------|--------|------|------|
| Web 应用 | WebApplication | {module} | {职责} |
| SOA 服务 | {Runner} | {module} | {职责} |

## 核心流程
{用编号列表概括 1~3 个核心业务流程，详见 data-flow.md}
实际示例
---
last_updated: 2026-03-28
status: active          # active | deprecated | draft
owner: @zhangsan
---

# 系统架构概览

## 定位

app-exchange-port 是一个第三方系统数据交换平台，负责对接天创（Tianchuang）、友盟（Youmeng）、百行（Baihang）等外部供应商，完成数据采集、加密转换、分片批量编排、结果持久化与文件处理。

## 技术栈

| 层面 | 技术选型 |
|------|---------|
| JDK | 1.8 |
| 框架 | Spring Boot 2.3.12 + Spring Cloud Hoxton.SR12 + Alibaba Cloud 2021.1 |
| 持久化 | MyBatis-Plus 3.4.3 + MySQL 8.0.28 + Dynamic Datasource 3.5.0 + HikariCP 3.4.5 |
| 缓存 | Redis (Lettuce / Jedis 3.3.0) + Caffeine 2.8.8 |
| 调度 | XXL-JOB 2.2.0 + 自研 @Trigger/@Job 调度框架 |
| HTTP | OkHttp3 3.14.9 + HttpClientFactory |
| 限流 | Resilience4j-ratelimiter + RateLimitFactory |
| 监控 | CAT + 自研 HttpMonitorInterceptor |
| JSON | FastJSON 1.2.83 |
| 对象映射 | MapStruct 1.5.2 + Lombok 1.18.12 |
| 配置中心 | Nacos（namespace: dev1 / test1 / pre / prod） |
| 消息 | RocketMQ (ons-client 1.8.8) |
| 测试 | JUnit 5.6.3 + Mockito 3.12.4 |

## 模块全景
\```
app-exchange-port (root pom)
├── exchange-common          通用基础设施：trace / juc / cache / scheduler / http / sentinel / event
├── exchange-dal             仓储层：entity / mapper / manager / datasource
├── exchange-business        核心业务层：core(async/sync/lifecycle) / base / ext / infra
├── exchange-ext             供应商适配层（pom 聚合）
│   ├── exchange-ext-tianchuang   天创适配器
│   ├── exchange-ext-youmeng      友盟适配器（文件批处理）
│   └── exchange-ext-baihang      百行适配器
├── exchange-app             应用编排层：config / trigger / admin / facade
├── exchange-runner          Web 部署包：WebApplication + controllers
├── exchange-api             SOA 接口契约（独立发布，仅依赖 Lombok）
├── exchange-soa-service     SOA 服务实现：SyncSingleService + RateLimitDelegate
├── exchange-app-soa         SOA 应用配置
├── exchange-deploy-set      部署集合（pom 聚合）
│   └── exchange-soa-runner  SOA 部署包
└── exchange-test            集成测试集
\```

## 双部署入口

| 部署形态 | 入口类 | 模块 | 职责 |
|---------|--------|------|------|
| Web 应用 | `WebApplication` | exchange-runner | 批量调度、手动触发、管理运维、监控 |
| SOA 服务 | SOA Runner | exchange-deploy-set/exchange-soa-runner | 同步单笔请求（Dubbo/HTTP） |

## 核心流程

1. **同步单笔**：外部系统 → SOA 接口 → `SyncSingleService.request()` → 限流 → 构造上下文 → HTTP 调用供应商 → 结果解析 → 返回
2. **异步批量**：XXL-JOB 触发 → `PlanLifecycleTrigger.trigInit()` → 数据分片 → 分区任务执行（同步/异步） → 结果持久化 → 文件处理（友盟）

详细流程见 [data-flow.md](data-flow.md)。

3.4 docs/architecture/boundaries.md — 模块边界与依赖约束

定位

这是整个 Harness 体系最关键的架构文档之一。 AI Agent 在每次影响分析（PRD-to-Code Step 2）时都会加载此文件，判断代码应该放在哪个模块、依赖是否合规。

必须包含的内容
  1. 依赖方向图（ASCII 图，清晰展示谁依赖谁）
  2. 铁律声明（依赖只能向上流动，禁止反向/跨层）
  3. 各模块职责（每个模块的"做什么"和"不做什么"）
  4. 跨模块约束（如数据库访问方式、配置注册方式、扩展点规则）
编写模板
---
last_updated: 2026-06-29
status: active
owner: @zhangsan
---

# 模块边界与依赖约束

## 依赖方向图
{ASCII 图：从底层到高层展示模块依赖关系}

**铁律：依赖只能向上流动，禁止反向依赖或跨层引用。**

## 各模块职责

### {module-common}
- **职责**：通用基础设施，业务无关
- **内容**：{列出此模块包含的核心功能}
- **禁止**：{明确列出不能做的事}

### {module-dal}
- **职责**：仓储层，操作数据库
- **内容**：Entity / Mapper / Manager / 数据源配置
- **禁止**：包含业务逻辑

{...其他模块}

## 跨模块约束
| 约束 | 说明 |
|------|------|
| 数据库访问方式 | {如通过 DalManager.of()} |
| 配置注册方式 | {如在何处注册} |
| 扩展点规则 | {如新增供应商必须新建子模块} |
编写要点
  • 每个模块的"禁止"项与 Rules 层的硬性约束一一对应
  • 依赖方向图必须使用 ASCII 或 Mermaid，确保 AI Agent 能解析
  • 模块职责描述要精确到"子目录"级别
实际示例
---
last_updated: 2026-03-28
status: active          # active | deprecated | draft
owner: @zhangsan
---

# 模块边界与依赖约束

## 依赖方向图

\```
exchange-common          ← 最底层，无项目内依赖
      ↑
exchange-dal             ← 依赖 common
      ↑
exchange-business        ← 依赖 dal + common
      ↑
exchange-ext (聚合)      ← 依赖 business
  ├── ext-tianchuang
  ├── ext-youmeng
  └── ext-baihang
      ↑
exchange-app             ← 依赖全部 ext 子模块
      ↑
exchange-runner          ← 依赖 app（Web 部署包）

exchange-api             ← 独立模块，仅依赖 Lombok，独立发布 0.0.1.RELEASE
      ↑
exchange-soa-service     ← 依赖 api + ext-tianchuang + ext-baihang
      ↑
exchange-app-soa         ← 依赖 soa-service
      ↑
exchange-deploy-set / exchange-soa-runner  ← 依赖 app-soa（SOA 部署包）
\```

**铁律：依赖只能向上流动，禁止反向依赖或跨层引用。**

## 各模块职责

### exchange-common
- **职责**：通用基础设施，业务无关
- **内容**：trace（traceId 传播）、juc（线程池/闭锁）、cache（Redis 锁/布隆过滤器）、scheduler（@Trigger/@Job 调度框架）、http（HttpClientFactory/监控拦截器）、sentinel（限流/CAT 监控）、event（EventBus）、shutdown（优雅停机）
- **禁止**：引入任何业务模块依赖

### exchange-dal
- **职责**：仓储层，操作数据库
- **内容**：entity（DO 模型）、mapper（MyBatis-Plus Mapper）、manager（Manager 模板方法封装）、datasource（数据源配置）
- **禁止**：包含业务逻辑；直接被 ext/runner 引用

### exchange-business
- **职责**：核心业务逻辑
- **内容**：
  - `core/` — 接口规范与核心编排（async 异步流程、sync 同步流程、lifecycle 生命周期）
  - `base/` — 对 core 接口的通用基础实现（HttpJsonPostRequestProcessor、HttpResultParserStrategy）
  - `ext/` — 增强功能（通知等）
  - `infra/` — 基础设施（InfraExecutorFactory）
  - `exception/` — 业务异常定义
- **禁止**：直接依赖具体供应商 SDK

### exchange-ext（及子模块）
- **职责**：按供应商接口规范定制适配器
- **模式**：每个子模块继承 business 中的抽象基类（InputConvertor、HttpResultParser、PortResultConvertor、PlanPartitionTaskProcessor 等）
- **ext-tianchuang**：天创 AES 加密 + MD5 签名 + 同步请求
- **ext-youmeng**：友盟文件批处理（CSV 读取、OSS 上传、批量计算、超时判定、布隆过滤）
- **ext-baihang**：百行征信数据对接
- **禁止**：被其他 ext 子模块互相引用

### exchange-app
- **职责**：全流程编排与全局配置
- **内容**：config（BizConfiguration/RedisConfiguration/AppConfig）、trigger（PlanLifecycleTrigger/AsyncTrigger/AsyncCompleteTrigger）、admin（管理操作）、facade（查询门面）
- **禁止**：直接操作 HTTP 客户端或数据库 Mapper

### exchange-runner
- **职责**：Web 部署入口
- **内容**：WebApplication 启动类、controllers（Schedule/Admin/Monitor/JobInfo/JobLifeCycle/TargetData）、ShardingScheduler（XXL-JOB 分片调度）
- **禁止**：包含核心业务逻辑，仅做请求转发与触发

### exchange-api
- **职责**：SOA 接口契约定义
- **内容**：SyncSingleRequestProvider 接口、RequestDTO/ResponseDTO、CodeEnum
- **特点**：独立版本号 0.0.1.RELEASE，独立发布到 Nexus，仅依赖 Lombok

### exchange-soa-service
- **职责**：SOA 接口实现
- **内容**：SyncSingleService（同步单笔）、HttpJsonPostRateLimitDelegate（限流委托）

## 跨模块约束

| 约束 | 说明 |
|------|------|
| Manager 模式 | 数据库操作必须通过 `DalManager.of(beanName)` 获取 Manager 实例，禁止直接注入 Mapper |
| 配置注册 | 供应商配置类需在 `BizConfiguration.preInitAppConfig()` 中注册到 PortConfigFactory / PlanConfigFactory |
| 扩展点 | 新增供应商必须新建 ext 子模块，禁止在 business 中硬编码供应商逻辑 |

3.5 docs/architecture/data-flow.md — 数据流转

定位

描述系统中数据如何在模块间流转。AI Agent 在设计文档生成阶段（Step 3）会参考此文件，确保新功能的数据流转路径与现有架构一致。

必须包含的内容
  1. 每种核心流程的调用链路图（从入口到出口的完整路径）
  2. 关键数据结构说明（DTO、Context、Config 等）
  3. 数据库表流转（数据从哪个表流到哪个表）
  4. 跨线程的上下文传播（如 traceId 传播机制）
编写要点
  • 使用 ASCII 流程图，每个节点标注所属模块和类名
  • 关键数据结构用表格列出，标明所属模块
  • 一个流程一个章节，不要混在一起
实际示例
---
last_updated: 2026-03-28
status: active          # active | deprecated | draft
owner: @zhangsan
---

# 数据流转

## 流程一：同步单笔请求（SOA）

\```
外部调用方
  │
  ▼
SyncSingleRequestProvider.request(RequestDTO)        ← exchange-api 接口契约
  │
  ▼
SyncSingleService.request()                           ← exchange-soa-service
  │
  ├─ 1. 参数校验（macro.portId / macro.appId / body.reqId / body.userId / body.phoneMd5）
  ├─ 2. 通过 PortConfigFactory.getPortConfig(portId) 获取供应商端口配置
  ├─ 3. 通过 PlanContextFactory.initContext(appId, portId) 构造计划上下文
  ├─ 4. 构造 PortRequestContext（含 SourceData、PortRequest、PortTraceInfo）
  │
  ▼
HttpJsonPostRateLimitDelegate.execute(context)        ← 限流委托
  │
  ├─ Resilience4j RateLimiter 获取许可
  │
  ▼
HttpJsonPostRequestProcessor                          ← exchange-business/base
  │
  ├─ InputConvertor.buildInput()                      ← ext 模块（如 TCInputConvertor）
  │    └─ 供应商特定的加密/签名逻辑（AES / MD5）
  ├─ HttpClientFactory 获取 OkHttp 客户端
  ├─ 发起 HTTP POST 请求
  │
  ▼
HttpResultParserStrategy                              ← exchange-business/base
  │
  ├─ HttpResultParser.parse()                         ← ext 模块（如 TCHttpResultParser3605）
  │    └─ 解析供应商返回的加密响应体
  ├─ PortResultConvertor.convert()                    ← ext 模块（如 TCPortResultConvertor）
  │    └─ 转换为统一 ResponseBodyDTO
  │
  ▼
ResponseDTO.successInstance(body)                     ← 返回调用方
\```

### 关键数据结构

| 结构 | 模块 | 说明 |
|------|------|------|
| `RequestDTO` | exchange-api | macro(portId, appId) + body(reqId, userId, phoneMd5, ext) |
| `ResponseDTO` | exchange-api | macro(success, code, message) + body(reqId, content) |
| `PortRequestContext` | exchange-business | 封装端口请求上下文（ExchangePortRefWrap + PortRequest + PortTraceInfo） |
| `SyncPortConfig` | exchange-business | 供应商端口配置（url, tokenId, 限流参数等） |

---

## 流程二：异步批量分片执行（XXL-JOB）

\```
XXL-JOB 调度中心
  │
  ▼
ShardingScheduler / ScheduleController                ← exchange-runner
  │
  ├─ ShardingUtil.getShardingVo() 获取分片参数（shardIndex / clusterSize）
  ├─ 构造 SchedulerScope + PlanSchedulerContext
  │
  ▼
PlanLifecycleTrigger.trigInit()                       ← exchange-app
  │
  ▼
PlanTaskInitializer                                    ← exchange-business/core/lifecycle
  │
  ├─ 1. 按 planId 查询 SourceData 未处理数据量
  ├─ 2. 按 clusterSize / shardIndex 计算分片 Segment（startId ~ endId）
  ├─ 3. 创建 PlanExecRecord（计划执行记录）
  ├─ 4. 创建 PlanDetailExecRecord（明细执行记录）
  ├─ 5. 创建 PlanPartitionTask / PlanDetailPartitionTask（分区任务）
  │
  ▼
PlanPartitionTaskDriver                                ← exchange-business/core/lifecycle
  │
  ├─ 遍历分区任务
  ├─ PlanPartitionTaskProcessor.process()             ← 同步: SyncPlanPartitionTaskProcessor / 异步: 自定义
  │    │
  │    ├─ 按 cursor 游标分批拉取 SourceData
  │    ├─ PortRequestProcessor / BatchPortRequestProcessor
  │    │    └─ 调用供应商接口（复用同步单笔的 HTTP 通道）
  │    ├─ PortResultConvertor 转换结果
  │    ├─ ResultBatchSaveProcessor 批量写入 TargetData
  │    └─ 更新游标 cursor / 分区状态
  │
  ▼
PlanSegmentPersistence                                 ← 持久化分段结果
  │
  ▼
PartitionsAggregation                                  ← 分区聚合
  │
  ├─ 全部分区完成后
  ├─ 更新 PlanExecRecord / PlanDetailExecRecord 状态为 SUBMIT
  │
  ▼
AsyncProcessor.afterProcess()                          ← 后续处理
  │
  ├─ 友盟：AsyncFileProcessor（文件上传 OSS、CSV 读取、批量计算）
  ├─ 更新执行记录状态
  └─ 事务保证（TransactionTemplate 编程式事务）
\```

### 数据库表流转

\```
tb_source_data ──分片──▶ tb_plan_exec_record ──▶ tb_plan_detail_exec_record
                              │                          │
                              ▼                          ▼
                   tb_plan_partition_task ◀──▶ tb_plan_detail_partition_task
                              │
                              ▼
                     tb_target_data（结果表）
                              │
                   tb_plan_file_record（文件记录，友盟异步）
                   tb_non_exist_data（不存在数据，布隆过滤）
                   tb_retry_data（重试数据）
\```

---

## 流程三：友盟文件批处理（异步增强）

\```
友盟供应商回调
  │
  ▼
AsyncTaskBatchFetchProcessor.process()                 ← exchange-ext-youmeng
  │
  ├─ 获取文件信息与解压密码
  ├─ 落库 PlanFileRecord
  │
  ▼
AsyncReadTrigger.planFileExecute()                     ← CSV 读取触发
  │
  ├─ CSVStreamReader 读取文件行
  ├─ YmLineDataProcessor 逐行处理
  ├─ 布隆过滤不存在数据（RedisBloomFilter）
  ├─ 批量写入 TargetData
  │
  ▼
YmAsyncFileProcessor                                   ← 文件后处理
  │
  ├─ BatchComputeHelper 批量计算
  ├─ OSS 文件上传
  ├─ TimeoutJudeEventHandler 超时判定
  └─ deleteFileSafely 清理本地文件
\```

---

## traceId 跨线程传播

\```
主线程
  │  @MDC(types={TIMER, LOG}) → MDCAspect 注入 traceId
  │
  ▼
ContextHolder / MDCTemplate
  │  捕获当前 traceId 上下文
  │
  ▼
子线程（BatchExecutorTemplate / InfraExecutorFactory）
  │  ContextHolder.runWithContext() 恢复 traceId
  │
  ▼
日志关联查询：",start,parentTraceId=" 或 ",start,preTraceId="
\```

3.6 docs/architecture/code-assets.md — 代码资产清单

定位

记录项目中所有可复用的基类、接口和工厂。AI Agent 在设计文档生成阶段（Step 3）会查询此文件，决定新增类应该继承哪个基类。

必须包含的内容
资产类型记录内容
基类/抽象类类名、所属模块、职责、关键方法、子类列表
接口接口名、所属模块、方法签名、实现类列表
工厂工厂名、产出物、注册方式
Manager 模式模式 A / 模式 B 的选择决策树
编写要点
  • 新建项目时此文件可能只有少量条目（甚至为空框架），随着代码积累逐步完善
  • 使用表格格式，便于 AI Agent 结构化解析
  • 每个 Manager 模式要给出选择依据（什么情况用模式 A，什么情况用模式 B）
实际示例
---
last_updated: 2026-06-24
status: active
owner: @zhangsan
---

# 代码资产清单

> **定位**：本文档列出项目中所有可复用的基类、接口、工厂和工具类，供 AI Agent 在技术设计阶段（prd-to-code Step 3）快速选择正确的继承/实现目标，避免临时探索代码。
> **维护规则**：新增基类/接口/工厂时必须同步更新本清单。

---

## 1. business/core — 核心接口与抽象类

### 1.1 供应商适配器基类

| 类型 | 名称 | 路径 | 用途 | 选择条件 |
|------|------|------|------|---------|
| 接口 | `HttpResultParser` | exchange-business/base/ | HTTP 响应解析 | 新增供应商需要解析 HTTP 响应时实现 |
| 接口 | `PortResultConvertor` | exchange-business/core/sync/ | 端口结果转换 | 新增供应商需要转换结果数据时实现 |
| 接口 | `SupplierConvertor` | exchange-business/core/sync/ | 供应商转换器 | 需要统一供应商转换逻辑时实现 |
| 接口 | `PortRequestProcessor` | exchange-business/core/sync/ | 端口请求处理器 | 需要自定义请求发送逻辑时实现 |
| 抽象类 | `InputConvertor` | exchange-business/ext/ | 请求参数转换 | 新增供应商需要构造请求参数时继承 |

### 1.2 同步流程组件

| 类型 | 名称 | 路径 | 用途 |
|------|------|------|------|
| 类 | `HttpHandler` | core/sync/ | HTTP 调用处理器（封装 OkHttp3 调用） |
| 类 | `BatchPortRequestProcessor` | core/sync/ | 批量端口请求处理器 |
| 类 | `SyncPlanSegmentProcessor` | core/sync/ | 同步计划分段处理器 |
| 类 | `SyncPlanSegmentPersistence` | core/sync/ | 同步计划分段持久化 |
| 类 | `SyncPlanPartitionTaskProcessor` | core/sync/ | 同步计划分区任务处理器 |
| 类 | `ResultBatchSaveProcessor` | core/sync/ | 结果批量保存处理器 |
| 类 | `DefaultPlanDetailInitProcessor` | core/sync/ | 默认计划详情初始化处理器 |

### 1.3 策略类

| 类型 | 名称 | 路径 | 用途 |
|------|------|------|------|
| 类 | `HttpResultParserStrategy` | base/ | HTTP 结果解析策略（按 beanName 查找实现） |
| 类 | `PortResultConvertStrategy` | core/sync/ | 端口结果转换策略（按 beanName 查找实现） |

### 1.4 工厂类

| 类型 | 名称 | 路径 | 用途 |
|------|------|------|------|
| 类 | `PortConfigFactory` | core/model/config/factory/ | 端口配置工厂（按 portId 获取 PortConfig） |
| 类 | `PlanConfigFactory` | core/model/config/factory/ | 计划配置工厂（按 planId 获取 PlanConfig） |
| 类 | `AppConfigFactory` | core/model/config/factory/ | 应用配置工厂 |
| 类 | `PortRequestFactory` | core/model/factory/ | 端口请求工厂 |
| 类 | `PlanContextFactory` | core/model/factory/ | 计划上下文工厂 |
| 类 | `ScanContextFactory` | core/model/factory/ | 扫描上下文工厂 |

---

## 2. business/base — 通用基础实现

| 类型 | 名称 | 路径 | 用途 |
|------|------|------|------|
| 类 | `HttpJsonPostRequestProcessor` | base/ | HTTP JSON POST 请求处理器（默认实现 PortRequestProcessor） |
| 类 | `HttpJsonPostReqConfig` | base/ | HTTP POST 请求配置 |
| 类 | `BeanUtils` | base/ | Bean 工具类（ApplicationContextAware） |
| 类 | `PhoneMd5Appender` | base/ | 手机号 MD5 追加器（实现 PlanRequestAppender） |

---

## 3. common/scheduler — 调度框架基类

| 类型 | 名称 | 路径 | 用途 | 选择条件 |
|------|------|------|------|---------|
| 抽象类 | `BaseSchedulerCxtFactory<E,T>` | common/scheduler/ | 调度上下文工厂基类 | 新增调度任务时继承，实现 construct() 和 parser() |
| 抽象类 | `BaseScheduleContext<T>` | common/scheduler/model/ | 调度上下文基类 | 新增调度上下文时继承 |
| 类 | `BaseSchedulerConfig` | common/scheduler/model/ | 调度配置基类 | 新增调度配置时继承 |
| 接口 | `Trigger` | common/scheduler/ | 触发器接口 | 新增触发器时实现 |
| 类 | `SchedulerFactory` | common/scheduler/ | 调度工厂（XXL-JOB 集成） | 自动注册，无需继承 |

---

## 4. common/trace — 链路追踪组件

| 类型 | 名称 | 路径 | 用途 |
|------|------|------|------|
| 类 | `MDCTemplate` | common/trace/ | MDC 操作模板（traceId 设置/清除/获取） |
| 类 | `ContextHolder` | common/trace/ | 线程上下文持有器（跨线程传递 traceId） |
| 类 | `ContextTaskDecorator` | common/trace/juc/ | 线程池任务装饰器（自动传递 traceId） |
| 类 | `DecoratorThreadPoolExecutor` | common/trace/juc/ | 装饰线程池（自动传递 traceId） |
| 类 | `MDCAspect` | common/trace/aspect/ | MDC 切面（@MDC 注解处理） |
| 类 | `TraceContextWrap` | common/trace/ | 追踪上下文包装器 |

---

## 5. common/juc — 线程池组件

| 类型 | 名称 | 路径 | 用途 |
|------|------|------|------|
| 类 | `BatchExecutorTemplate` | common/juc/ | 批量执行模板 |
| 类 | `ThreadPoolExecutorBuilder` | common/juc/ | 线程池构建器 |

---

## 6. dal — 数据访问层基类

### 6.1 Manager 接口

| 名称 | 用途 | 选择条件 |
|------|------|---------|
| `DalManager<T>` | 基础 Manager 接口（extends IService + BeanNameAware） | 所有 Manager 的根接口 |
| `TargetDataManager<T>` | 目标数据 Manager | 新增供应商目标数据表时实现 |
| `DefaultTargetDataManager` | 默认目标数据 Manager（TargetData 表） | 操作通用 tb_target_data 表时使用 |
| `SourceDataManager` | 源数据 Manager | 操作 tb_source_data 表时使用 |
| `PlanExecRecordManager` | 计划执行记录 Manager | 操作 tb_plan_exec_record 表时使用 |
| `PlanDetailExecRecordManager<T>` | 计划详情执行记录 Manager | 操作 tb_plan_detail_exec_record 表时使用 |
| `PlanPartitionTaskManager` | 计划分区任务 Manager | 操作 tb_plan_partition_task 表时使用 |
| `PlanDetailPartitionTaskManager` | 计划详情分区任务 Manager | 操作 tb_plan_detail_partition_task 表时使用 |
| `PlanFileRecordManager` | 计划文件记录 Manager | 操作 tb_plan_file_record 表时使用 |
| `NonExistDataManager` | 不存在数据 Manager | 操作 tb_non_exist_data 表时使用 |
| `RetryDataManager` | 重试数据 Manager | 操作 tb_retry_data 表时使用 |

### 6.2 Manager 实现模式

项目中存在两种 Manager 模式，根据是否需要 `DalManager.of(beanName)` 动态获取来选择：

#### 模式 A：DalManager（需动态获取时使用）

适用场景：计划执行、分区任务、目标数据等需要在 business 层通过 beanName 动态获取的 Manager。

\```
接口层: XxxManager extends DalManager<XxxEntity>
实现层: XxxManagerImpl extends BaseManager<XxxMapper, XxxEntity> implements XxxManager
获取方式: DalManager.of("xxxManagerImpl") 获取 Bean 实例
\```

实际使用：`PlanDetailPartitionTaskManager`、`PlanPartitionTaskManager`、`PlanDetailExecRecordManager`、`TargetDataManager`/`DefaultTargetDataManager`

#### 模式 B：IService（直接注入时使用）

适用场景：源数据、重试数据、文件记录等只需在固定代码中通过 @Resource 注入的简单 Manager。

\```
接口层: XxxManager extends IService<XxxEntity>
实现层: XxxManagerImpl extends ServiceImpl<XxxMapper, XxxEntity> implements XxxManager
获取方式: @Resource 注入
\```

实际使用：`SourceDataManager`、`RetryDataManager`、`PlanFileRecordManager`、`PlanExecRecordManager`、`NonExistDataManager`

#### 选择规则

| 条件 | 选择 |
|------|------|
| business 层需要通过 `DalManager.of("beanName")` 动态获取 | 模式 A（DalManager + BaseManager） |
| 仅需在固定代码中通过 `@Resource` 注入 | 模式 B（IService + ServiceImpl） |
| 不确定时默认 | 模式 B（更简单，后续如需动态获取再重构为模式 A） |

---

## 7. soa-service — SOA 服务基类

| 类型 | 名称 | 路径 | 用途 | 选择条件 |
|------|------|------|------|---------|
| 类 | `SyncSingleService` | soa-service/ | 同步单笔服务（实现 SyncSingleRequestProvider） | 新增同步单笔查询接口时参考 |
| 类 | `SyncSingleQueryService` | soa-service/ | 同步查询服务（实现 SyncSingleRequestYmProvider） | 新增高并发查询接口时参考 |
| 类 | `QueryRateLimitDelegate` | soa-service/ | 查询限流委托（extends BaseRateLimitTemplate） | 新增限流查询时继承 |
| 类 | `HttpJsonPostRateLimitDelegate` | soa-service/ | HTTP POST 限流委托（extends BaseRateLimitTemplate） | 新增限流 HTTP 调用时继承 |

### SOA Service 实现模式

\```
1. exchange-api 定义 Provider 接口 + RequestDTO/ResponseDTO
2. exchange-soa-service 创建 Service 类 implements Provider 接口
3. @Slf4j + @Component + @MDC 注解
4. 参数校验 → 上下文构造 → 限流委托 → HTTP 调用 → 结果封装
5. exchange-deploy-set 修改 spring/spring-dubbo-provider.xml 注册 Dubbo 服务
\```

---

## 8. ext — 供应商适配器参考实现

| 供应商 | 模块 | 关键类 | 参考场景 |
|--------|------|--------|---------|
| 天创 | exchange-ext-tianchuang | TCInputConvertor, TCHttpResultParser3605/3606, TCPortResultConvertor | 同步请求 + AES 加密 + MD5 签名 |
| 百行 | exchange-ext-baihang | BhInputConvertor, BhHttpResultParser, BhPortResultConvertor, BhTargetData | 征信数据 + 自有 Entity |
| 友盟 | exchange-ext-youmeng | YmContextRegister, YmPlanDetailInitProcessor, YmTaskFetchProcessor, YmAsyncFileProcessor | 异步文件批处理 + CSV + OSS |

### 新增供应商适配器选择条件

\```
PRD 要求同步请求 + 加密签名 → 参考 ext-tianchuang 模式
PRD 要求异步文件批处理     → 参考 ext-youmeng 模式
PRD 要求征信数据对接       → 参考 ext-baihang 模式
PRD 要求高并发实时查询     → 参考 SyncSingleQueryService + QueryRateLimitDelegate 模式
\```

---

## 9. 基类选择决策树

\```
PRD 需要新增什么？
│
├─ 新增数据库表/字段
│  └─ Entity extends BaseTargetData (或新建 Entity implements Serializable)
│     Mapper extends BaseMapper
│     Manager 接口:
│     ├─ 需 DalManager.of() 动态获取 → extends DalManager → Impl extends BaseManager (模式 A)
│     └─ 仅 @Resource 注入 → extends IService → Impl extends ServiceImpl (模式 B)
│     Mapper XML (如有自定义 SQL)
│
├─ 新增供应商适配器
│  ├─ 需要构造请求参数 → 继承 InputConvertor
│  ├─ 需要解析 HTTP 响应 → 实现 HttpResultParser
│  ├─ 需要转换结果数据 → 实现 PortResultConvertor
│  └─ 需要处理分区任务 → 实现 PlanPartitionTaskProcessor
│
├─ 新增 SOA 服务接口
│  ├─ 需要限流 → 继承 BaseRateLimitTemplate
│  ├─ 需要限流 + HTTP 调用 → 参考 HttpJsonPostRateLimitDelegate
│  └─ 需要限流 + 查询 → 参考 QueryRateLimitDelegate
│
├─ 新增调度任务
│  ├─ 上下文工厂 → 继承 BaseSchedulerCxtFactory
│  ├─ 调度上下文 → 继承 BaseScheduleContext
│  ├─ 调度配置 → 继承 BaseSchedulerConfig
│  └─ 触发器 → 实现 Trigger
│
├─ 新增 REST Controller
│  └─ 参考 add-api-endpoint.md 场景一
│
└─ 新增事件处理
   └─ 实现 EventHandler<C, E>
\```

4. 文档元信息规范

所有 .md 文件头部必须包含 YAML front matter：

---
last_updated: 2026-06-29
status: active          # active | deprecated | draft
owner: @zhangsan
---
字段说明为什么需要
last_updated最后更新日期，格式 YYYY-MM-DD文档健康度扫描时检测过期（>90天标记 stale）
statusactive / draft / deprecated区分生效中、草稿、已废弃的文档
owner文档负责人发现问题时知道找谁

过期检测规则（后续自动化层会用到）：

  • last_updated 距今 > 90 天 → 标记为 stale
  • last_updated 距今 > 180 天 → 标记为 critical
  • status: draft → 标记为待发布
  • owner 缺失 → 标记为 orphan（无主文档）

5. 完成验证清单

完成本步后，逐项检查：

  • AGENTS.md 存在，包含项目简介、技术栈基线（精确到版本号）、快速导航表、提交规范
  • README.md 存在，包含模块拓扑图和环境准备说明
  • docs/architecture/overview.md 存在，包含技术栈明细、模块全景、部署入口、核心流程
  • docs/architecture/boundaries.md 存在，包含依赖方向图、各模块职责（含禁止项）、跨模块约束
  • docs/architecture/data-flow.md 存在，包含每种核心流程的调用链路图
  • docs/architecture/code-assets.md 存在（可为框架结构，随代码积累完善）
  • 所有.md 文件头部包含 YAML front matter（last_updated / status / owner）
  • AGENTS.md 的快速导航表中已注册本步创建的所有文档路径

6. 与下一步的衔接

本步建立了架构基线，定义了"模块怎么分层"和"依赖方向是什么"。下一步需要在此基础上编写 Rules 层（硬性约束）——将架构边界转化为 AI Agent 必须遵守的规则。

Step 1（本步）                    Step 2（下一步）
┌─────────────────┐              ┌─────────────────┐
│ AGENTS.md       │    定义约束    │ always-on.md    │ ← 技术栈锁定
│ overview.md     │ ──────────▶   │ agent-workflow   │ ← 流程约束
│ boundaries.md  │    依赖方向    │ java-code-style │ ← 代码风格
│ data-flow.md   │    转化为规则   │ java-testing    │ ← 测试规则
└─────────────────┘              └─────────────────┘

衔接关系：

  • boundaries.md 中的依赖方向图 → always-on.md 第 2 节"模块依赖方向"
  • overview.md 中的技术栈 → always-on.md 第 1 节"技术栈锁定"
  • 各模块的"禁止"项 → always-on.md 中对应的硬性约束
  • 核心流程 → agent-workflow.md 中的强制流程顺序

7.说明

  • 实际示例的格式是markdown格式，在示例中出现\符号是因为整文是采用markdown编辑的，若不转译就会直接markdown格式断裂。使用时将\去掉即可
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

我用 NVIDIA SkillSpector 纯静态扫了一遍 GitHub 最火的 agent skills：能挖出多少注入？0 个

avatar 龙虾开发者社区
cover

周榜换血九成，Agent Skills 星数翻倍

avatar 龙虾开发者社区
cover

智能体从入门到精通：6个必学GitHub开源项目

avatar 龙虾开发者社区