# ai-plan-project

**Repository Path**: memeafnc/ai-plan-project

## Basic Information

- **Project Name**: ai-plan-project
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-22
- **Last Updated**: 2026-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ecommerce-agent-platform · 企业级 Agent 工程骨架

> 定位：**不是 demo，是可落地的 Agent 平台骨架**。核心是手写的一套 Agent Harness（执行循环 / 工具网关 / 风控 / 状态机 / 可观测），上面跑电商客服场景。
> 与 `samples/w1-react-from-scratch`（W1 教学用的 200 行最小循环）的关系：那个是**原理教具**，这个是**工程载体**。12 周的任务全部落在这个工程的对应模块里。

## 目录导航

| 路径 | 内容 |
|---|---|
| **`docs/Agent-Harness转型最终版.md`** | **主文档（定稿 2026-09-22，唯一真源）**：Harness 学科范式 + 大厂五家打法 + 能力地图与短板自测 + 企业 Agent 运行时七层架构 + 电商客服-办事落地场景（含第二领域包 Listing 治理）+ 12 周计划 + 求职转化 + 阅读路线。**先读这个** |
| `docs/Agent-Harness转型最终版.html` | 主文档的**可打印版**：带侧边目录、勾选框、打印样式。浏览器打开 ⌘P 即得 PDF |
| `docs/Agent-Harness转型最终版.pdf` | 主文档的 PDF（41 页），便于分发与离线阅读 |
| `docs/架构图-企业Agent运行时.svg` | 七层运行时架构图（面试系统设计轮答题骨架，可直接放简历/README） |
| `docs/架构图-电商客服Agent.svg` | 电商客服领域包架构图（对应主文档 §5.6，阿里面试「设计电商客服 Agent」的默认题面） |
| `docs/tools/md2html.py` | 主文档 → HTML 的转换脚本（改完 Markdown 后重跑即可同步 HTML/PDF） |
| `samples/w1-react-from-scratch/` | W1 原理教具：纯 Java + HttpClient + Jackson 手写 ReAct 循环，零 AI 框架依赖 |
| `deploy/` | docker-compose（pgvector + Redis + OTel Collector + Jaeger）、建表 SQL、OTel 采集配置（含 prompt 脱敏） |
| 各 `agent-*` 模块 | 工程本体，见下方模块划分 |

文档改动后同步导出：

```bash
python3 docs/tools/md2html.py --input "docs/Agent-Harness转型最终版.md" \
  --output "docs/Agent-Harness转型最终版.html" --title "Java 工程师 · Agent Harness 转型计划（最终版）"
```

## 模块划分（依赖方向单向，无循环依赖）

```
agent-web          接口层：HTTP 入口 / 租户鉴权 / 装配 / 健康检查
   ↓
agent-tools        工具层：工具网关（白名单 → 风控 → 执行 → 审计）+ 电商工具
   ↓
agent-engine       Harness 核心：执行循环 / 工作流图 / 护栏 / 转人工 / 会话持久化
   ↓                ↘
agent-domain       agent-observability（Tracer 端口 + 成本归因）
领域模型（零依赖）    agent-knowledge（RAG 检索）
```

设计原则：**端口与适配器**。引擎只认 `LlmPort` / `ToolExecutor` / `SessionStore` / `Tracer` 四个接口，具体实现随时可换，业务代码零改动。

## 快速开始

```bash
# 1. 编译安装（JDK 17 + Maven）
mvn -DskipTests install

# 2. 离线跑通全链路（不配 API Key 时自动用桩模型，不烧钱）
java -jar agent-web/target/agent-web-1.0.0-SNAPSHOT.jar

curl -X POST http://localhost:8080/api/agent/chat \
  -H 'Content-Type: application/json' -H 'X-Tenant-Id: tenant-demo' \
  -d '{"text":"我的订单 20260830001 到哪了","confidence":0.9}'
```

```bash
# 3. 接真实模型
export LLM_API_KEY=sk-xxx
export LLM_BASE_URL=https://api.deepseek.com/v1   # 默认
export LLM_MODEL=deepseek-chat                    # 默认
# 重启即可，LlmPort 自动从桩实现切换到 HttpLlmPort
```

依赖中间件（W3/W4 启用）：`cd deploy && docker compose up -d`（Postgres+pgvector / Redis / OTel Collector / Jaeger）

## 企业级能力对照（这块才是"不是 demo"的地方）

| 能力 | 落点 | 状态 |
|---|---|---|
| 多租户隔离 | `TenantContext` + `TenantFilter`（缺失租户头直接 401） | ✅ 已实现 |
| 工具治理 | `ToolGateway`：白名单 → 风控 → 执行 → 审计四步 | ✅ 已实现 |
| 额度风控 | `RiskPolicy.QuotaRiskPolicy`（退款/赔付超额度拦截并转人工） | ✅ 已实现 |
| 审计不可变 | `AuditEvent` → `Slf4jSink`（生产换写库 `agent_audit_log`） | ✅ 已实现 |
| 转人工策略 | `HandoffPolicy`：低置信度 / 负面情绪 / 高客单价三触发 | ✅ 已实现 |
| HITL 挂起恢复 | 会话 `WAITING_HUMAN` + `/api/agent/resume`（W8 换 JDBC 持久化） | 🟡 内存态 |
| 防死循环 | 最大迭代 / 调用上限 / 同参重复检测 / 超时（四件套） | ✅ 已实现 |
| 上下文保护 | 窗口截断（W5 升级为摘要压缩 + 长期记忆） | 🟡 基础版 |
| 可观测 | `Tracer` 端口（W4 换 OtelTracer，接 SkyWalking） | 🟡 端口就绪 |
| 成本归因 | `CostCalculator` 按模型单价算到每次调用 | ✅ 已实现 |
| 评测与回归 | W3 建 50 条 → W10 AB 分流（表 `agent_eval_case` 已备） | ⬜ W3 起 |
| 编排 | `WorkflowGraph`（W5 落意图分类 → 三分支 → 兜底） | 🟡 骨架就绪 |

## 12 周任务落点（对应主文档 §6）

| 周次 | 新增模块/改哪个模块 | 做什么 | 落到哪一层 |
|---|---|---|---|
| **W0** | 环境 | 装 JDK 21，主链路升 Boot 4.1.1 + Spring AI 2.0.1，加 `SpringAiLlmPort` | 全栈基线 |
| W1–W2 | agent-engine | 手搓最小 Harness：loop + trace + 预算开关；对照 `ToolCallingAdvisor` 源码写笔记 | 3 运行时、7 可观测 |
| W3 | agent-knowledge | 缓存布局 + `cost_ledger`；分品类知识库与评测集 | 3 运行时 |
| W4 | agent-observability | 压缩与卸载（大结果落盘 → `result_ref`）+ OTel → SkyWalking | 3 运行时、6 存储、7 可观测 |
| W5 | agent-tools | 工具注册中心（typed + 版本 + 风险等级）+ 策略拦截链 + 转人工与防死循环 | 4 治理、5 集成 |
| W6 | agent-engine | 交接工件（`artifact`）+ 任务状态机（`agent_task`/`agent_run`） | 6 存储 |
| W7 | agent-engine | 客观终止信号 + JUnit/Testcontainers 反馈 + 断点续跑 + HITL 审批 | 3 运行时、4 治理 |
| W8 | 新模块 agent-eval | Evaluator Agent + Sprint Contract + `eval_result` | 7 评估 |
| W9 | agent-tools | 沙箱执行 + 凭证隔离 + 容器池 + MCP 网关（SDK 2.0.1） | 5 集成 |
| W10 | agent-observability | 成本看板 + 质量看板 + 电商规则库与引用强制 + 在线 AB | 7 可观测、领域包 |
| W11 | CI | eval 进 CI 门禁 + ArchUnit + 配置版本化与回滚 + AgentScope 2.0.2 对照实验 | 7 评估 |
| W12 | 全链路 | 灰度试点（1 个品类 / 100 工单）+ README + 简历 + 模拟面试 | 1 接入、2 编排 |

> Checkpoint 2 之后（约第 5–6 周）就可以开始投简历，边投边补剩下的编排与生产化部分。

## 升级路径（装好 JDK 21 后）

1. 父 pom：`java.version` / `maven.compiler.release` 改 21，`spring-boot.version` 改 4.1.1
2. 引入 `spring-ai-bom:2.0.1`，新增 `SpringAiLlmPort implements LlmPort`（替换 `HttpLlmPort`）
3. 其余模块不动——这就是先定义端口的价值