From 4569724cec91af12a84ffb74b776ba4b51ed98d7 Mon Sep 17 00:00:00 2001
From: yuzhe <xxxxxx>
Date: Thu, 23 Jul 2026 13:55:00 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=20Agent=20=E4=B8=8A?=
 =?UTF-8?q?=E4=BC=A0=E4=B8=8E=E4=BC=98=E5=8C=96=E6=8E=A5=E5=8F=A3=E8=AF=B4?=
 =?UTF-8?q?=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/architecture.md      | 3 ++-
 docs/integration-guide.md | 6 ++++++
 docs/operator-runbook.md  | 2 ++
 3 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index 75d8653..2cd5a02 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -67,10 +67,11 @@ flowchart LR
 - 点击图片打开悬浮图片窗格；只有该窗格可以新增坐标批注，并支持原图查看、缩放和前后切换。点击窗格外会同时关闭图片窗格和验收协作面板。
 - 标题、正文和 Tag 批注保存 `start_offset`、`end_offset`、`selected_text` 及前后文，提交时校验选区仍与轮次快照一致。
 - `GET /api/works/:workId/annotations` 按轮次返回图片批注、文字批注、总体反馈和验收事件。
+- `GET /api/works/:workId/optimization-context?round=N` 聚合指定轮次的内容、图片和可执行反馈，默认排除已关闭或撤回记录，供外部内容优化流程只读使用。
 
 ## Agent 安全上传
 
-内置 Agent Skill 采用“发现目标 → 生成计划 → 人工确认 → 单次写入 → 读取核验”的两阶段流程。计划文件只保存目标 ID、待写内容和确认摘要，不保存 API Key，并写入已被 Git 忽略的 `tmp/` 目录。
+内置 Agent Skill 固定连接 `http://192.168.30.90:3010`，采用“发现目标 → 操作者确认运营组和项目 → 生成计划 → 操作者确认内容与确认码 → 单次写入 → 读取核验”的两阶段确认流程。计划文件只保存目标 ID、待写内容和确认摘要，不保存 API Key，并写入已被 Git 忽略的 `tmp/` 目录。
 
 新建作品以 `externalId` 保证幂等；新增验收轮次没有幂等键。轮次写入超时或响应不明确时，必须先重新读取作品状态，不能直接重试，以免重复创建轮次。
 
diff --git a/docs/integration-guide.md b/docs/integration-guide.md
index d43d4b7..d0de751 100644
--- a/docs/integration-guide.md
+++ b/docs/integration-guide.md
@@ -113,8 +113,14 @@ curl "http://localhost:3010/api/works/12?round=2" \
 # 按轮返回该作品全部反馈和验收事件
 curl http://localhost:3010/api/works/12/annotations \
   -H "Authorization: Bearer $DELIVERY_DESK_API_KEY"
+
+# 返回用于优化指定轮次内容与图片的精简上下文；默认只含未撤回的开放反馈
+curl "http://localhost:3010/api/works/12/optimization-context?round=2" \
+  -H "Authorization: Bearer $DELIVERY_DESK_API_KEY"
 ```
 
+`optimization-context` 返回项目、作品、轮次、标题、正文、Tag、图片元信息，以及图片批注、文字批注、总体反馈和回复。需要审计已关闭或已撤回的历史反馈时增加 `include_history=true`；该接口只读，不会修改作品。
+
 标题、正文和 Tag 选区批注使用：
 
 ```json
diff --git a/docs/operator-runbook.md b/docs/operator-runbook.md
index 1b69690..33f5a20 100644
--- a/docs/operator-runbook.md
+++ b/docs/operator-runbook.md
@@ -57,6 +57,8 @@ JSON URL 导入依赖活动 COS 配置。同一 COS/CDN 域名的图片直接使
 
 Agent 通过 API 新建作品或提交验收轮次时，使用 `.agents/skills/upload-delivery-desk-work`。API Key 只通过 `DELIVERY_DESK_API_KEY` 环境变量注入，不写入计划文件、文档或 Git。
 
+Skill 默认固定连接 `http://192.168.30.90:3010`，不读取环境变量覆盖服务地址。只有操作者明确要求迁移或测试其他环境时，才使用 `--base-url` 指定另一地址。
+
 Agent 可用 `--image-url` 提交公网图片，也可用 `--image-file` 将生成在运营电脑上的本地图片直接 multipart 上传；两种模式不混用，不把图片转换为 Base64。
 
 ```powershell