文档：更新完整观测与可视化接入方案

记录 Global Data、Production 与 Pipeline 的当前接入状态、显式上报授权和完整采集模式。\n\n补充重复模块去除、业务可读投影、父子 Run 关联、数据边界及后续真实运行验证要求。

可视化接入.md

@@ -1,6 +1,6 @@
 # VideoImageProductionBuild 可视化接入
 
-> 文档状态：接入设计稿
+> 文档状态：Global Data 与 Production 0.7 观测代码已接入，真实 Production Run 待验证
 > 当前项目协议：Production 0.7
 > 当前验证日期：2026-07-29
 > 观测台地址：<http://8.147.104.190:8931/>
@@ -21,9 +21,13 @@
 - 失败降级、隐私、安全和并发注意事项；
 - 分阶段实施与验收方案。
 
-本文是接入方案，不代表业务代码已经完成接入。当前项目环境已安装并验证
-`obagent-sdk 0.5.2`，但源码中尚未加入 `configure()`、`observe.run()` 或
-`observe.module()`。
+当前项目已安装并锁定 `obagent-sdk 0.5.2`。Global Data 0.3 已接入
+`configure()`、`observe.run()`、8 个 Graph 节点的 `observe.module()` 和 SDK
+消息/工具采集；Production 0.7 已接入独立 `ProductionObservation`、13 个真实 Graph
+节点、完整 State/Run 记录投影和模型/工具采集。两者都关闭了 SDK 自动创建
+LangGraph 模块的能力，避免一个真实节点调用同时出现“自动实例”和“业务实例”。
+`run_pipeline.py` 另有一个很薄的 Pipeline 父 Run，只表达
+`Global Data → Production` 两阶段关系。
 
 ## 2. 两套“可视化”的职责边界
 
@@ -89,8 +93,7 @@ cd /Users/samlee/Documents/works/VideoImageProductionBuild
 
 ### 4.2 正式纳入项目依赖
 
-当前 SDK 只安装在本地 `.venv`，尚未写入 `pyproject.toml` 和锁文件。正式接入时应把
-SDK 纳入项目依赖并更新锁文件，建议先约束在兼容版本范围：
+SDK 已写入 `pyproject.toml` 和 `uv.lock`，当前约束在兼容版本范围：
 
 当前仓库使用 PEP 621 的 `project.dependencies` 数组，建议加入：
 
@@ -112,7 +115,8 @@ SDK 本身不会自动读取环境变量或 `.env`。以下变量是本项目适
 
 ```dotenv
 # 观测总开关。建议本地和测试环境先开启。
-OBAGENT_ENABLED=true
+# 不要写入 .env；仅在当前正式 Run 的命令前显式设置
+OBAGENT_REPORT_THIS_RUN=true
 
 # 当前已验证的观测台。
 OBAGENT_ENDPOINT=http://8.147.104.190:8931
@@ -124,6 +128,7 @@ OBAGENT_PROJECT=video_image_production_build
 OBAGENT_API_KEY=
 
 # 可选参数。
+OBAGENT_CAPTURE_MODE=full
 OBAGENT_TIMEOUT=10
 OBAGENT_BATCH_SIZE=200
 OBAGENT_FLUSH_INTERVAL=0.5
@@ -152,10 +157,10 @@ load_dotenv(PROJECT_ROOT / ".env", override=False)
 因此 `configure()` 必须在这一步之后、第一次 `observe.run()` 之前调用。不要在模块 import
 阶段读取 `.env` 并配置 SDK，否则运行时 `.env` 还没有加载。
 
-建议未来增加集中适配器：
+当前集中适配器位于：
 
 ```text
-production_build_agents/observability.py
+production_build_agents/observability/
 ```
 
 适配器负责：
@@ -164,7 +169,9 @@ production_build_agents/observability.py
 - 调用一次 `configure()`；
 - 生成稳定的 Run 参数；
 - 把 Pydantic Model、Path、Enum 转成可上报 JSON；
-- 对敏感字段和超大字段做裁剪；
+- 根据 `OBAGENT_CAPTURE_MODE` 选择完整采集或脱敏回退；
+- 完整模式读取 State 引用的正式 JSON/Markdown 记录；
+- 对超大文件和媒体二进制做边界控制；
 - 提供不抛异常的辅助函数；
 - 提供客户端 UID 到服务端 Run ID 的只读查询。
 
@@ -179,7 +186,7 @@ from obagent_sdk import configure
 
 
 def configure_observability() -> None:
-    enabled = os.getenv("OBAGENT_ENABLED", "true").lower() in {
+    enabled = os.getenv("OBAGENT_REPORT_THIS_RUN", "false").lower() in {
         "1", "true", "yes", "on",
     }
     configure(
@@ -253,7 +260,11 @@ with observe.run(
         "protocol_version": "0.7",
         "execution_mode": "fresh",
     },
-    auto_collect=True,
+    # 模块实例由业务适配器显式创建，SDK collector 单独以
+    # auto_module=False 启动，只采模型与工具事件。
+    auto_collect=False,
+    parent_run_id="<可选 Pipeline Run UID>",
+    parent_inst_id="<可选 Pipeline 阶段实例 UID>",
     round_anchor=None,
 ) as run_handle:
     result = run_production_graph(...)
@@ -274,7 +285,9 @@ with observe.run(
 | `model_name` | 主模型，用于成本归集 |
 | `payload` | 初始业务入参，原样 JSON 化保存 |
 | `meta` | thread ID、协议版本、环境、显示名等业务元数据 |
-| `auto_collect` | 是否自动采集当前上下文中的 LangChain 调用 |
+| `auto_collect` | 是否由 `observe.run()` 自动启动默认 collector；本项目固定为 `False`，再显式启动 `auto_module=False` 的 collector |
+| `parent_run_id` | 可选的 Pipeline 父 Run UID |
+| `parent_inst_id` | 可选的 Pipeline 阶段实例 UID |
 | `round_anchor` | 循环 Run 的轮次切分规则 |
 | `spec` | 外层 Workflow 结构定义 |
 
@@ -508,7 +521,7 @@ ProductionPlan、SegmentDelivery、ValidationReport、Artifact 等稳定合同
 ```mermaid
 flowchart TD
     CLI["run_production.py<br/>加载 .env 与 CLI 参数"]
-    OBS["production_build_agents/observability.py<br/>配置、脱敏、Run 参数"]
+    OBS["production_build_agents/observability/<br/>配置、完整采集/脱敏回退、Run 参数"]
     RUN["observe.run<br/>一次 Production 请求"]
     GRAPH["production_graph<br/>KIND_WORKFLOW + graph_spec"]
     PLAN["Production Planner<br/>INITIAL / ADAPT / REPLAN"]
@@ -756,11 +769,26 @@ with observe.module(...) as ctx:
 
 不要为了上报而新增捕获后返回成功的代码。
 
-## 10. 隐私、安全与数据量
+## 10. 内网完整采集与数据量
 
 ### 10.1 自动采集范围
 
-`auto_collect=True` 会自动采集当前上下文中的 LangChain/LangGraph：
+本项目不能直接使用默认的 `auto_collect=True`。默认 collector 会根据
+LangGraph 元数据自动创建节点模块，而项目代码已经用 `observe.module()` 明确申报了
+同一批业务节点，两者同时开启会让一个真实调用显示成两个实例。
+
+当前实现采用：
+
+```python
+with observe.run(..., auto_collect=False) as run_handle:
+    token = start_collector(run_handle, auto_module=False)
+    try:
+        run_graph()
+    finally:
+        stop_collector(token)
+```
+
+这样仍会采集当前上下文中的：
 
 - 模型输入消息；
 - system prompt；
@@ -770,7 +798,12 @@ with observe.module(...) as ctx:
 - token、耗时、模型信息；
 - 调用时序。
 
-这意味着接入前必须确认 Production 数据允许发送到该观测台。
+但不会再自动创建 `preprocess · step1`、`execute_task · stepN` 等第二套
+LangGraph 节点实例。页面只保留显式申报的业务实例；同一 Executor 模块因多个
+Task 或 Segment 被真实调用多次，仍会合理地出现多个实例。
+
+本项目已确认观测台位于可接受的内网边界，因此启用观测时默认
+`OBAGENT_CAPTURE_MODE=full`，上述内容按原文采集。
 
 ### 10.2 当前地址是 HTTP
 
@@ -780,35 +813,70 @@ with observe.module(...) as ctx:
 http://8.147.104.190:8931
 ```
 
-它不是 HTTPS。不要在未经授权的情况下上报：
+它不是 HTTPS。当前内网策略允许上报业务内容、内部 URL、Prompt、模型回复和工具
+参数/结果，但以下进程级秘密与无必要的大体积二进制仍不应进入观测事件：
 
 - API Key、Cookie、Token、密码；
-- 用户个人信息；
-- 未脱敏的内部 URL 查询参数；
 - Base64 媒体正文；
 - 本地 `.env` 内容；
-- 不必要的完整文件内容；
-- 第三方受限素材。
 
-生产环境正式启用前，应确认网络边界、访问控制、保留周期和鉴权配置。
+图片、视频和音频通过正式记录中的 URL 交给页面展示，不把二进制重复嵌入事件包。
 
-### 10.3 脱敏和裁剪
+### 10.3 完整模式与脱敏回退
 
-建议适配层统一提供：
+当前支持：
 
-```python
-jsonable_for_observation(value)
-redact_observation_value(value)
-compact_observation_value(value, max_chars=...)
+```dotenv
+# 默认不上报。正式 Run 必须在当前命令中显式授权：
+OBAGENT_REPORT_THIS_RUN=true python run_global_data.py ...
+
+# 开启后：上报真实 State、正式文本记录、模型消息和工具调用
+OBAGENT_CAPTURE_MODE=full
+
+# 需要临时退回旧的白名单摘要时
+OBAGENT_CAPTURE_MODE=redacted
 ```
 
 原则：
 
-- 正式合同保留关键 ID、状态、hash、版本和引用；
-- 超长正文给摘要和正式 Artifact/Record 引用；
+- `full` 保留完整业务字段、正文、URL、绝对路径和错误信息；
+- 自动采集保留模型输入、system prompt、输出、reasoning、tool args/result；
+- 正式 JSON/Markdown/TXT 记录按产生它的业务 Phase 投影，不再在每个节点
+  重复上报完整 State；
+- 单个文本记录超过 10 MiB 时只上报文件元信息；
 - 不重复上传媒体二进制；
 - 不修改业务对象本身；
-- 脱敏逻辑只作用于观测副本。
+- `redacted` 仅作为显式配置的回退模式。
+
+### 10.4 业务可读投影
+
+观测主卡片不是 Checkpoint 调试器。当前适配器通过 Phase Projector 注册表，
+为 Global Data 的 8 个节点和 Production 的 13 个节点分别声明输入、输出：
+
+- Prepare 输出 Package 或“全部任务已完成”；
+- Planner 输出正式 Plan；
+- Executor 输出 Candidate/Delivery/Artifact；
+- Validator 输出 ValidationReport、Evidence 和 verdict；
+- Assembly、Readiness、Finalize 输出各自正式合同。
+
+主输出禁止再使用以下通用技术外壳：
+
+```text
+node / update / state_after / records
+referenced_records / new_or_changed_run_records
+```
+
+完整正式合同仍可在对应字段的详情抽屉展开；模型的原始 LangChain 消息仍由 SDK
+独立保存，用于重放和审计。
+
+模型与工具过程也使用业务可读投影：
+
+- `模型决定调用：读取 Production Brief`；
+- `模型并行调用 3 个工具`；
+- `检查媒体技术信息 · 已返回`；
+- 工具参数和结果先显示 Task、Segment、verdict、状态、产物和错误等摘要；
+- 原始消息保留完整参数和结果，不在流程卡片上重复打印整块 JSON；
+- 工具产出的图片、视频和音频 URL 仍参与媒体扫描。
 
 ## 11. 健康检查、查询和排障
 
@@ -935,6 +1003,8 @@ with observe.run(
 
 ### 阶段 A：依赖与集中配置
 
+状态：Global Data 第一版已完成。
+
 改动范围：
 
 - 将 `obagent-sdk` 加入项目依赖和锁文件；
@@ -951,6 +1021,8 @@ with observe.run(
 
 ### 阶段 B：零申报 Run
 
+状态：Global Data 已完成，并进一步申报了 8 个真实 Graph 节点。
+
 只增加顶层 `observe.run()`，暂不增加大量业务模块申报。
 
 验收：
@@ -962,6 +1034,8 @@ with observe.run(
 
 ### 阶段 C：Production Graph
 
+状态：代码已完成，真实 Production Run 页面验证待执行。
+
 增加：
 
 - `production_graph` workflow；
@@ -976,8 +1050,31 @@ with observe.run(
 - Loop 次数与真实 Segment 推进一致；
 - Graph 节点没有被重复包装成两套模块。
 
+### 阶段 C.1：Pipeline 父子衔接
+
+状态：代码已完成，真实全链路页面验证待执行。
+
+`run_pipeline.py` 会创建一个 `agent="pipeline"` 的薄父 Run，结构固定为：
+
+```text
+Global Data → Production
+```
+
+- 父 Run 不复制两个子 Run 的模型、工具、State 或正式记录；
+- `Global Data` 和 `Production` 各有一个阶段实例；
+- 两个正式子 Run 分别通过 `parent_run_id` 和 `parent_inst_id` 挂到对应阶段；
+- 三个 Run 共享 `pipeline_round_id`，Production 另外记录
+  `upstream_global_data_thread_id`；
+- Global Data 未完成时不创建 Production 阶段运行实例；
+- 单独执行 `run_global_data.py` 或 `run_production.py` 时父 ID 为空，仍保持独立 Run；
+- Pipeline 不增加第三套 Checkpoint，也不改变两个正式 Run 的恢复语义。
+
+旧的已上报 Run 不会被追溯合并或删除；去重和父子衔接从修复后的新 Run 生效。
+
 ### 阶段 D：阶段 12 业务模块
 
+状态：Planner、Segment Loop、Progress Review 的完整采集代码已完成。
+
 优先接入：
 
 - Production Planner；
@@ -996,6 +1093,9 @@ with observe.run(
 
 ### 阶段 E：阶段 13、14
 
+状态：Assembly、Readiness、Production Validator、Finalize 的现有真实节点已接入；
+不预造当前 Graph 中不存在的节点。
+
 在真实实现稳定后接入：
 
 - Assembly；
@@ -1057,7 +1157,7 @@ with observe.run(
 - [ ] 现有 Agent Audit、Checkpoint、Journal 和 Artifact 不受影响。
 - [ ] 上报失败不改变业务返回值、异常、退出码或落盘文件。
 - [ ] 并发任务保持正确父子上下文。
-- [ ] 敏感数据、密钥和媒体正文没有被上报。
+- [ ] 业务数据按 `full` 原样上报；密钥、`.env` 和媒体二进制未被上报。
 - [ ] 页面模块、输入、过程、输出、分支和 Loop 与真实 Run 一致。
 - [ ] 浏览器控制台无 obagent 相关错误。
 - [ ] 本地 WAL 无非预期积压。