# 大龙虾（Big Lobster / zm-ai-server）

大龙虾是面向政务外网的组织级 AI 工作 Agent 平台。本仓库是其后端服务 `zm-ai-server`，基于 **zmeg_new 框架 + Java 8 + MySQL**。

本 README 仅为工程导读；完整设计文档请参见 [`/big-lobster-doc/prd`](../big-lobster-doc/prd/)。

## 模块总览

| 包 | 作用 |
|---|---|
| `com.gzzm.lobster.common` | 枚举、JSON/Token 工具、ID 生成、统一异常 |
| `com.gzzm.lobster.identity` | UserContext + UserContextHolder |
| `com.gzzm.lobster.thread` | ThreadRoom / ThreadMessage + DAO + ThreadService |
| `com.gzzm.lobster.run` | Run 观测实体 + DAO |
| `com.gzzm.lobster.workspace` | Workspace + WorkspaceResource + WorkspaceService |
| `com.gzzm.lobster.artifact` | Artifact 实体 + ArtifactService（通过 ContentStore 外置正文） |
| `com.gzzm.lobster.pending` | PendingRequest + Service |
| `com.gzzm.lobster.memory` | PersonalMemory + MemoryService（严格按 userId 隔离） |
| `com.gzzm.lobster.plan` | Plan + PlanItem + PlanService |
| `com.gzzm.lobster.skill` | SkillDefinition + SkillService（薄索引 + 激活） |
| `com.gzzm.lobster.prompt` | PromptTemplate + 稳定 system skeleton |
| `com.gzzm.lobster.audit` | AuditLog + ModelCallLog + AuditService |
| `com.gzzm.lobster.config` | AgentProfile + `LobsterConfig`（全局 tunables，由 `web/WEB-INF/config/lobster.xml` 初始化） |
| `com.gzzm.lobster.feedback` | UserFeedback |
| `com.gzzm.lobster.storage` | ContentStore 接口 + FileSystemContentStore |
| `com.gzzm.lobster.llm` | LobsterMessage / ToolCall / ToolSpec / LlmResponse；ModelRouter + LlmRuntime + Adapter |
| `com.gzzm.lobster.llm.adapter` | OpenAI / Ollama 适配器（HTTP 直连） |
| `com.gzzm.lobster.tool` | Tool 协议 + ToolRegistry + Dispatcher + Permission/RateLimiter/Audit |
| `com.gzzm.lobster.tool.builtin` | 6 层内置工具（Workspace / Memory / Skill / Interaction / OA / Plan） |
| `com.gzzm.lobster.tool.mcp` | MCP Server 配置 + 桥接 |
| `com.gzzm.lobster.oa` | OA 文件/知识库 Client 抽象 + 开发 stub |
| `com.gzzm.lobster.context` | ContextAssembler + 7 层上下文策略 |
| `com.gzzm.lobster.guardrails` | AgentLoopDetector / ClaimConsistencyChecker / ContentFilter / InternalInfoSanitizer |
| `com.gzzm.lobster.quota` | ConcurrencyGuard + CircuitBreakerRegistry + QuotaPolicy |
| `com.gzzm.lobster.runtime` | AgentRuntime（核心 RunLoop）+ StreamEmitter + RunRequest/Result |
| `com.gzzm.lobster.api` | REST + SSE 控制器（含 `HealthApi` 探活） |
| `com.gzzm.lobster.api.admin` | 后台 REST CRUD：工具 / Skill / 模型 / MCP Server（需 `ai_admin` 角色） |

另外在各实体包下提供 zmeg_new 框架 CRUD 类（继承 `BaseNormalCrud`），用于框架自带的后台界面：

| CRUD 类 | URL 前缀 | 实体 |
|---|---|---|
| `com.gzzm.lobster.tool.ToolDefinitionCrud` | `/ai/admin/tool` | `ToolDefinitionConfig` |
| `com.gzzm.lobster.skill.SkillDefinitionCrud` | `/ai/admin/skill` | `SkillDefinition` |
| `com.gzzm.lobster.llm.ModelProfileCrud` | `/ai/admin/model` | `ModelProfile` |
| `com.gzzm.lobster.bootstrap` | 内置工具注册引导 |

## 启动顺序

1. 配置 `/ai/model_profile`、`/ai/agent_profile`、`/ai/prompt_template` 的基础数据（入库，后续可通过 `/ai/api/admin/*` CRUD 管理）。
2. 按需修改 `web/WEB-INF/config/lobster.xml` 的全局 tunables（`LobsterConfig`）。
3. 启动容器，框架初始化 Bean 后由 `LobsterBootstrap.onStart()` 注册全部内置工具，并发现 MCP Server。
4. 调用 `/ai/api/*`：`UserContextHolder.get()` 会从 zmeg_new 框架的 `UserOnlineInfo.getUserOnlineInfo()` 自动桥接当前登录态（`isAdmin()=true` 的用户自动获得 `admin` + `ai_admin` 角色）。测试 / 定时任务等无框架登录态的场景可 `UserContextHolder.set(new UserContext(...))` 显式注入。
5. 探活：`GET /ai/api/health` 返回 `{status: "ok", ...}`。

## 测试

```bash
mvn test
```

自带 20+ JUnit 用例，覆盖核心闭环：
- Token 估算、JSON 工具、ID 生成器
- ContentStore 读写/路径安全
- ToolRegistry / Dispatcher 注册与执行
- SchemaBuilder 合法性
- Guardrails：Loop 检测、Claim 一致性、信息脱敏
- Quota：并发许可、熔断器状态机
- Context：预算策略、压缩策略、Workspace 索引
- LLM：消息抽象、ToolCall 等价判断
- Runtime：三条主路径（无 tool / 有 tool / pending）+ 循环熔断

## 进展文档

- [`docs/PROGRESS.md`](docs/PROGRESS.md)：工作进度
- [`docs/TECHNICAL-IMPL.md`](docs/TECHNICAL-IMPL.md)：详细技术实现方案
- [`docs/SANDBOX-SKILL-IMPL.md`](docs/SANDBOX-SKILL-IMPL.md)：`code_exec`、skill 加载、沙箱挂载与执行语义
- [`docs/SYSTEM-SKILLS.md`](docs/SYSTEM-SKILLS.md)：当前系统 skill 清单、类型和功能说明