# 智能体 agent

Python 3.12 + FastAPI。HTTP 默认 `8910`；Worker 另起进程。

## 基础框架自检

```text
set REDIS_BACKEND=memory
set CHECKPOINT_BACKEND=memory
python -m agent.foundation_selftest
python -m agent.runtime_db.migrate --list
```

PG 真迁移：配好 `PG_*` 后 `python -m agent.runtime_db.migrate`（禁止 `ytd_runtime`）。

消息账本：`MESSAGE_STORE_BACKEND=auto|memory|postgres`（有 DSN 时优先 PG inbox/outbox）。

## Redis 骨架

- 包：`agent/redis_coord/`（连接+前缀、Stream 入队/认领、短幂等、限流、token 缓存）。
- **db1 不是名字**：Redis 只有数字逻辑库（URL `…/1`），与现网 `…/0` 隔离；可读名是键前缀 **`inquiry_robot:`**。
- 自检：`set REDIS_BACKEND=memory` 后 `python -m agent.redis_coord.selftest`。
- 正式：`REDIS_URL=redis://…@host:6379/1` + `REDIS_KEY_PREFIX=inquiry_robot:`（禁止 `ytd:prod:`）。

## LangGraph 骨架

- 包：`agent/graph/`（状态、分文件空节点、interrupt 停点、PG/Memory checkpoint、start/resume/wake）。
- **无询价主逻辑**；节点只打日志。HTTP 回调禁止 `invoke` 整图。
- 自检：`set CHECKPOINT_BACKEND=memory` 后执行 `python -m agent.graph.selftest`。
- 正式：`CHECKPOINT_BACKEND=postgres` + `PG_*` 指向 `inquiry_robot_runtime`（禁止 `ytd_runtime`）。

## 本迭代骨架（路由 / PDF / 识别）

- DeepSeek A：`agent/routing/ordered_actions.py` + `deepseek_a.py`（strict `route_decision` tool；默认 stub，不开费）。
- 分发：`agent/routing/dispatch.py`；通道 inbox → route → handler 表。
- 真网开关：`LLM_DATA_USAGE_CONFIRMED=true` 且 `LLM_ALLOW_NETWORK=true`（Worker）才可能打模型。
- LibreOffice：`agent/jobs/libreoffice.py` + `stream:pdf`（仅 1 槽）；路径 `LIBREOFFICE_PATH`。
- 识别 / 存档：`stream:recognition` / `stream:archive` 入队壳。
- 字段合同：仓库 `contracts/*.json`；拉取备份在 `_ref/prod-pull/`（gitignore）。
- 本机密钥：仓库根 `.env`（gitignore）；新库口令来自服务器 `E:\wwwroot\ops\inquiry_robot_db_secrets.json`。
- 另：session/suspend/job/死信、LLM 各 mode 空模块、S3 壳、ledger API 签名壳、模板 registry、policy、AIBOT 长连接壳、Java TMS 空包、`deploy/nssm/SERVICES.md`。


链路：回调/注入 → inbox 入队（快回）→ echo handler → outbox → 企微 `message/send`。

### 并存期怎么测（重要）

公网 `https://ai.ytd-scm.com/wecom/callback` **切流前仍进现网**。不要改 Nginx、不要双连 AIBOT。

本机联调（推荐）：

1. 配置仓库根 `.env`（从 `.env.example` 复制，填 `WECOM_*`，对齐 `prompt/03`，**勿提交**）。
2. 启动：
   ```text
   cd agent
   .\.venv\Scripts\activate
   pip install -r requirements.txt
   python -m agent.http_app
   ```
3. 用你的企微 **userid** 注入一条模拟入站（会真发应用到你的企微）：
   ```text
   curl -X POST http://127.0.0.1:8910/internal/dev/inject-text -H "Content-Type: application/json" -d "{\"sender_id\":\"你的企微userid\",\"content\":\"你好\"}"
   ```
4. 手机/桌面企微应收到带 `[test]` 前缀的回复。

若返回企微 `60020 not allow to access from your ip`：当前出口 IP 未进企微应用可信 IP。请在**服务器白名单出口**上跑智能体，或把本机出口 IP 配进企微后台（与现网出口策略一致）。

真要从企微聊天窗口「发消息→新系统回」= **切流**（改 Nginx 反代到 8910 + 停现网对应进程），现网会短暂停收询价，需单独批准。

### 健康检查

`GET http://127.0.0.1:8910/health` 中 `wecom_send_ready` / `wecom_crypto_ready` 应为 true。