# z-harness

**Repository Path**: cpsoft13/z-harness

## Basic Information

- **Project Name**: z-harness
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-14
- **Last Updated**: 2026-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# agent-suite — 灵析智能体独立套件（F-257）

ZWMS 智能体（MOD-AI）的独立复刻版：**后端独立进程**（`agent-svc`）+ **前端可集成 npm 包**（`@lingxi/agent-react`）+ **演示宿主**（`demo`）。与 zwms 仓库完全解耦，zwms 原 agent 代码零改动。

```
agent-suite/
├── backend/                 # Cargo workspace（独立可编译）
│   ├── {common,report,ontology,lua_script,logsvc,agent}/   # 整拷自 zwms，字节一致
│   ├── agent-svc/           # ★ 独立进程二进制（本套件唯一新增后端代码）
│   └── migrations_mysql/    # 独立库迁移子集（0001/0002 新建 + zwms 子集裁剪）
├── migrations/              # zwms SQLite 迁移全量拷贝（拷入 crate 编译期 include_str! 需要）
├── frontend/
│   ├── agent-react/         # ★ npm 包 @lingxi/agent-react（Vite lib mode）
│   └── demo/                # 演示宿主（实现全部适配器，独立运行验证）
├── scripts/{run-dev.sh, smoke-test.sh, mock-llm.mjs}
└── docker-compose.yml       # 独立 MySQL 8（3308 → agent_suite 库）
```

## 快速开始

```bash
# 1. 独立 MySQL（3308；zwms 开发库在 3307，互不干扰）
docker compose up -d

# 2. 配置
cp .env.example .env    # 必填 JWT_SECRET（强随机）；AI_* 按需

# 3. 启动（logsvc 8091 可选 + agent-svc 8890）
./scripts/run-dev.sh [--mock-llm]      # --mock-llm：离线冒烟（AI_API_BASE 指向 :8099）

# 4. 冒烟
./scripts/smoke-test.sh

# 5. 前端 demo（另开终端）
cd frontend/demo && pnpm i && pnpm dev   # 登录页输入 AGENT_DEV_TOKEN 即可对话
```

## 关键决策

| 项 | 决策 | 理由 |
|---|---|---|
| 数据库 | **独立 MySQL 库 `agent_suite`**（不连 zwms 主库） | agent 生产面全链路 MySQL 类型（~70 处 pool 直用、NOW() 方言、free_query 硬性 MySQL）；SQLite 化需大改拷贝 crate，破坏「字节一致→可重拷同步」 |
| 鉴权 | 拷贝 gateway JWT 管线 + `POST /api/agent-suite/token`（X-Dev-Token → admin JWT） | admin 角色短路权限表查询；与 zwms 同 JWT_SECRET 时原系统令牌通用 |
| 业务工具 | **代码 100% 保留**，zwms 技能种子不随迁（`seed-reference/` 备份） | 空业务库下查询优雅降级（"Table doesn't exist" 错误回喂 LLM 自愈，已冒烟验证）；宿主通过技能管理注册指向本库表的技能 |
| 本体 | ont_* 表结构随迁，zwms 实体种子裁剪（`seed-reference/0300_ontology.sql.full`） | 空本体目录优雅降级（build_active_catalog → None），避免显示不存在的实体 |
| 日志 | logsvc 随仓（8091）；`LOG_SVC_URL` 未设 → 写侧静默跳过 | 零依赖微服务，整拷即用 |
| 前端 | npm 包 `@lingxi/agent-react`，适配器全部经 `AgentProvider` 注入 | apiBaseUrl / tokenProvider / onUnauthorized / navigate / executeTool / resolveEntity / linkify / configured / lang |

## 环境变量（.env.example 有完整注释）

核心：`DATABASE_URL`（3308 独立库）、`JWT_SECRET`（必填强随机）、`AGENT_PORT=8890`、`AGENT_DEV_TOKEN`、`AGENT_CORS_ORIGIN`、`LOG_SVC_*`、`AI_*`（OpenAI 兼容，本地模型允许空 key）、`AI_FREE_QUERY_ENABLED`（默认 true，查本库）。

## 与 zwms 的同步策略

- `backend/{common,report,ontology,lua_script,logsvc,agent}/` 与 `migrations/` 为**整拷**：zwms 侧 agent 变更 → 重新 rsync 覆盖即可（`rsync -a --delete zwms/backend/agent backend/`）。
- **本套件自有增量**（不在覆盖范围）：`agent-svc/`、`migrations_mysql/`（含 0001/0002 与 0300 裁剪）、`seed-reference/`、`scripts/`、`frontend/`、`docs/`、根文件。
- ⚠️ `migrations_mysql/` 已应用后不得改文件（sqlx checksum）；dev 逃生 = 重建数据库（`docker compose down -v`）。

### F-258 偏离清单（rsync 重拷后必须重放，见 ADR d007）

| 文件 | 偏离内容 |
|------|----------|
| `backend/report/src/llm.rs` | DeepSeek 官方协议升级（thinking/reasoning/usage/错误码/看门狗，主体） |
| `backend/agent/src/agent_loop.rs` | stream_decide 走 stream_chat_ext + AgentOutcome.usage + JSON 守卫 |
| `backend/agent/src/chat.rs` | usage SSE 事件 + error 细码 + webhook dispatch 点 |
| `backend/agent/src/llm.rs` | re-export 增 6 符号 |
| `backend/agent/src/task.rs` | webhook dispatch 点 |
| `backend/agent/src/prompt.rs` | F-258：身份句可配置（AGENT_IDENTITY，默认 zwms 原文） |
| `backend/agent/src/pending_ask.rs` | F-259：自由提问（无字段 ask）回复原文回灌 |
| `backend/agent/src/profile.rs` | F-259：settings_json.llm_params 存取（get/set_llm_params） |
| `backend/agent/src/tools/memory_tools.rs` | F-259：session_search created_at 改 NaiveDateTime 解码（独立库 DATETIME 兼容） |
| `backend/agent/src/tools/web.rs` | **新增文件**（rsync --delete 会删，须重放）：F-261 web_search/web_fetch（DeepSeek 原生检索） |
| `backend/agent/src/tools/mod.rs` | F-261：builtin 注册链加 web 工具 |
| `backend/agent/src/webhook.rs` | **新增文件**（rsync --delete 会删，须重放） |
| `backend/common/src/config.rs` | **零改动**（协议配置 env 直读） |

**重拷 SOP**：`rsync -a --delete zwms/backend/... backend/` 后，按清单重放上述 6 文件补丁
（从 git 取 F-258 提交），`cargo test --workspace` 全绿为验收。若 zwms 上游采纳本协议
升级，补丁可回迁（删除本清单对应行）。

## 验证记录（2026-08-14）

- `cargo build` 零错；`cargo test --workspace` 566 passed / 0 failed（与 zwms 同源）
- 冒烟 7 项全过：health / token 签发 / 401 拦截 / 会话 CRUD / SSE 全链路（phase→tool_call→result→token→done）/ 坏令牌拒绝
- 降级链路实证：LLM 调 `query_sql` → `Table 'agent_suite.biz_inbound_order' doesn't exist` → 观察回灌 → 自愈回答，无 panic
- logsvc 独立运行 + agent 审计日志入账实证