fix(agent): 分镜绑定 - 明确连线方向并提供字段纠正提示

docs/content/docs/backend/http-api.mdx

@@ -5,6 +5,12 @@ description: 信封、错误码与 OpenAPI
 
 # HTTP API 合同
 
+## Agent 分镜连线参数反馈
+
+素材绑定使用“素材→分镜”和 `toHandleId: row:<rowId>`；镜头输出使用“分镜→图片/视频”和 `fromHandleId: row:<rowId>`。`rowId` 必须是读取工具返回的真实行 ID，不能用镜头编号代替。普通节点连线与镜头行连线按 handle 区分，已有整表连线不代表该行已经绑定。
+
+handle 放错端点、格式错误或行 ID 不存在时，工具错误回执提供具体 `field`（如 `ops[0].fromHandleId`）、`issue`、方向说明及连线参数模板，不再使用无关的新增节点示例。模板不会被自动执行，不自动交换端点或修改原调用。权限、快照和重复连线校验保持不变；工具契约版本为 v4，重启后端后新会话使用更新后的说明。
+
 ## 注册邮箱等价检查
 
 公开注册与邮箱绑定的唯一性检查将 `gmail.com` 和 `googlemail.com` 视为同一域，移除本地部分的点及 `+` 后缀。例如 `a.b+x@googlemail.com` 与 `ab@gmail.com` 不允许创建两个账号。其他域保留点和 `+`；现有域名白名单规则保持不变。

docs/content/docs/progress/pending-test.mdx

@@ -5,6 +5,13 @@ description: 当前项目已实现功能的手工验证清单与未确认边界
 
 # 待测试
 
+## Agent 分镜绑定参数引导
+
+- 已优化：工具说明区分素材输入和镜头输出的两个 JSON 示例；handle 错误明确字段、正确方向和真实 rowId 要求，并在回执附上对应连线模板。不放宽校验、不自动改线。
+- [x] 专项测试覆盖来源/目标 handle 放错节点、镜头编号误用、缺少 row 前缀、错误回执模板方向、普通连线与行绑定并存，以及重复行绑定仍拒绝；工具 schema 体积检查通过。
+- [x] 用户已在本地验证镜头绑定可用；自动化测试不调用外部模型，不修改实际创作画布。
+- [ ] 上游合并后验证新会话沿用正确绑定方向，错误调用不会被误报为成功。
+
 ## 复制生图节点后节点消失
 
 - 已修复：副本不再继承原节点的 `generationEffectKeys`，避免普通保存把它误判为未确认的生成结果。图片内容、提示词和参考字段仍保留，原节点不受影响。