wyndham-ARR/AGENT_INTEGRATION.md

ARR1 历史文档 — Open Agent API 对接说明

仅作兼容与迁移审计。ARR2.0 的生产行为以根目录 README 和 ADR-004 为准，不导入、配置或部署此集成。

更新时间：2026-07-29

1. 已完成范围

本项目新增 agent_integration/，用于调用 DeerFlow / NianxxAgent Agent Profile Open API：

• 为外部会话创建并复用 Agent Session；
• 以 SSE 流式发送消息；
• 非流式创建 Run，并查询或取消 Run；
• 使用 SQLite 保存 conversation_id -> session_id 映射；
• 以 JSONL 输出流事件，便于后续转发到 WebSocket、微信或 CRM；
• 所有密钥只从环境变量读取。

底层 agent_integration 只负责文本 Agent API。Opera XML 远程任务由独立 arr_processing 边界建模：ARR 代码上传源 XML，把 committed 对象设为 public-read，再向 Agent 发送含 ARR 生成的无签名 HTTPS URL、但不含密钥的 oss_attachments 描述对象，由 runtime 的 fetch_oss_file 取件；暂存与输出对象仍为 private。结果只接受经受信 runtime 签名的 path-free 回调。具体处理规则仍只在 arr-opera-daily-ingest 确定性 Skill 内。

2. 安装

建议使用项目隔离环境：

cd /path/to/wyndham-ARR
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

不要使用用户压缩包内的 Windows .venv，也不要复制其中的 .env。

3. 配置

参考 .env.example，在运行环境中设置：

export DEERFLOW_BASE_URL="https://superagent.nianxx.cn"
export DEERFLOW_OPEN_API_KEY="df_open_替换为新密钥"
export DEERFLOW_AUTH_MODE="bearer"
export DEERFLOW_SESSION_DB="runtime/agent_sessions.sqlite3"

代码不会自动读取 .env，避免开发目录中的凭据被意外加载。可由部署平台、容器 Secret 或进程管理器注入环境变量。

本机 ARR 部署使用 macOS Keychain account arr-web、service com.chillishark.arr.deerflow-open-api-key 保存 Agent key，由受控 launcher 在进程启动时映射为 DEERFLOW_OPEN_API_KEY。Keychain 不解决 XML 文件 Tool 或回调契约；它只是本机凭据保存方式。

原压缩包中的 Token 已经被打包传播，建议不要继续使用；请在 Ops 中撤销并生成新 Token。

4. 配置检查

.venv/bin/python -m agent_integration doctor

doctor 只做本地配置检查，不访问远端，也不会输出 Token。没有配置密钥时会返回状态 missing_api_key 和退出码 2。

5. 流式对话

.venv/bin/python -m agent_integration chat \
  --conversation-id "crm-conversation-001" \
  --external-subject-id "crm-customer-001" \
  --message-id "crm-message-001" \
  --message "你好，请介绍一下你能做什么" \
  --metadata '{"source":"crm"}'

默认每行输出一个经过过滤的公开 JSON 事件：

{"event":"message.delta","data":{"content":"你"}}

公开事件只包含 run.started、message.delta、message.completed、run.warning/run.error 和 run.end，不会转发 LangGraph 内部推理、服务器路径、标题中间件或跟踪 metadata。

ARR 生产任务另有受控诊断路径：请求 POST /api/open/agent-sessions/{session_id}/messages/stream?include_trace=true， 只把外层 trace 中的 run.started、task.updated、step.updated、运行终态 和 end 投影为脱敏运维事件。message.delta、message.final、原始 SSE、Prompt、 工具参数/结果都不落入任务日志。

调试终端可追加 --output text。只有排查协议问题且输出位置受控时才使用 --output raw-jsonl；原始流可能包含内部推理和服务器运行信息，不得直接转发给最终用户或写入普通业务日志。

conversation-id 和 external-subject-id 应使用稳定、不含姓名或证件信息的内部 ID。上游有消息 ID 时务必传 --message-id；同一个 ID 会生成同一个幂等键，便于安全重发。

注意：2026-07-29 的真实接口探针确认，/messages/stream?include_trace=true 对完全相同的消息幂等键仍会创建新的 run_id，不能把它当作历史回放或服务端 去重接口。生产代码只 POST 一次并继续消费同一条连接；拿到 run.started 后绝不 为了“补日志”再次提交。

6. 非流式 Run

.venv/bin/python -m agent_integration send \
  --conversation-id "crm-conversation-001" \
  --message-id "crm-message-002" \
  --message "执行一个非流式任务" \
  --poll

也可以单独查询或取消：

.venv/bin/python -m agent_integration get-run \
  --conversation-id "crm-conversation-001" \
  --run-id "run_xxx"

.venv/bin/python -m agent_integration cancel-run \
  --conversation-id "crm-conversation-001" \
  --run-id "run_xxx"

同一 Session 已有活跃 Run 时，服务可能返回 HTTP 409。CLI 会输出 active_run_conflict: true；调用方应等待、查询或取消旧 Run，不要盲目换 Session。

当前真实服务的非流式 Run 可以正常从 running 变为 success，但查询结果中的 final_content 仍可能为 null。此时 CLI 会输出 run_result_unavailable warning；Run 本身成功，退出码仍为0。需要取得答案时优先使用流式接口，或配置服务端 webhook。

真实服务可能在流中已经给出可见答案后仍发送 open_agent_final_content_missing，同时 Run 查询显示 success 但 final_content=null。接入层会在确有可见内容时把它降级为 run.warning；没有可见内容时仍按 run.error 和非零退出码处理。

7. 会话映射维护

首次发送消息会自动创建 Session。也可显式创建、查看或遗忘本地映射：

.venv/bin/python -m agent_integration ensure-session \
  --conversation-id "crm-conversation-001"

.venv/bin/python -m agent_integration show-session \
  --conversation-id "crm-conversation-001"

.venv/bin/python -m agent_integration forget-session \
  --conversation-id "crm-conversation-001"

只有确认远端 Session 已失效或绑定错误时才应遗忘映射。SQLite 文件属于运行状态，已被 .gitignore 排除。

默认 SQLite 适合本地开发或单实例服务。不同环境、不同外部应用应使用不同的 DEERFLOW_SESSION_DB。多实例部署应实现 SessionStore 协议，把映射迁移到共享数据库；Agent 客户端和 OpenAgentService 无需因此改写。

8. Python 调用

from agent_integration import AgentConfig, OpenAgentAPIClient, OpenAgentService, SQLiteSessionStore

config = AgentConfig.from_env()

with SQLiteSessionStore(config.session_db) as store:
    with OpenAgentAPIClient(
        base_url=config.base_url,
        api_key=config.api_key,
        auth_mode=config.auth_mode,
        timeout=config.timeout_seconds,
        connect_timeout=config.connect_timeout_seconds,
    ) as client:
        service = OpenAgentService(client, store)
        for event in service.stream_message(
            "crm-conversation-001",
            "你好",
            message_id="crm-message-001",
            metadata={"source": "crm"},
            include_trace=True,
        ):
            print(event.to_dict())

9. 文件链路与结果回写

当前 Open API 契约没有附件上传或文件登记接口。远端 Agent 无法访问调用机上的 /absolute/input.xml，所以不能把本地路径写进消息后假定 Agent 能读取。

当前已实现 arr_processing 的 job/run 关联、有界重试、直接 OSS 输入描述、runtime 结果发布、独立 HMAC 签名、OSS 输出重取、ARR 独立复验和 PostgreSQL 原子落库。输入 message 符合 arr_opera_daily_program_input.schema.json：含 bucket、public endpoint、精确 object key、ARR 生成的无签名 HTTPS URL、哈希、字节数与任务 ID，不含 OSS AccessKey、XML 正文或本机路径。fetch_oss_file 只接收该公网 URL 和文件名，不使用 OSS Provider。

结果不从 final_content、present_files 或 Agent 本地路径取回。受信 runtime adapter 把产物发布到私有 OSS 交换前缀，然后签名回调 ARR；ARR 从 OSS 重新下载并复验后才入库。回写接口、状态码、ID 对应和部署变量见 AGENT_WRITEBACK_CONTRACT.md；实现边界见 arr_processing/README.md。

10. 测试

.venv/bin/python -m unittest discover -s tests -p 'test_*.py' -v

Agent API 测试使用 httpx.MockTransport，不会访问真实服务。配置新密钥后，真实联调应先用虚构会话和无隐私测试消息验证 scopes、SSE 事件类型及 409 行为。

11. 当前真实联调状态

2026-07-27 已使用无个人信息的临时会话完成真实验证：

• Bearer 鉴权通过；
• Session 创建与复用通过；
• SSE 流式消息通过，并验证公开事件过滤；
• 非流式 Run 提交与状态查询通过；
• Run 取消通过，状态从 running 经 cancelling 进入 interrupted。

联调密钥未写入项目文件或 SQLite，测试本地状态已清理。当前仍存在服务端 final_content=null 聚合问题，处理原则见第6节。

2026-07-28 已完成结果回写开发：机器入口为 POST /api/integrations/super-agent/results，回调会验签、核对 job/attempt/remote run、从 OSS 重取并校验工件、独立重放业务规则，然后在 PostgreSQL 事务中写入 ingestion/finance 并最后切换 current version。远程测试库已通过合成 delivery 的幂等重放验证。

这仍不等于线上竖切已经接通。只有 Agent Profile 开启 Open API 并发布、实际 OSS/RAM、独立 HMAC、公网 HTTPS callback URL 和 runtime writeback hook 均注入，GET /api/health 返回 processing_ready=true 与 agent_writeback_ready=true，并成功提交一笔无隐私测试任务后，才可宣告 Super Agent 结果可实时回传落库。