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

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

@@ -15,6 +15,11 @@ description: 信封、错误码与 OpenAPI
 Pi 模型桥在保存待执行调用之前，复用单步输出限制校验：一次回复最多 8 个工具调用，正文最多 32000 字节。超限时整批未执行，释放本步模型任务并附带 `invalid_output` 及具体上限要求模型分批纠正；与既有异常重试共用首次失败后最多 3 次的上限，不截取部分调用执行。纠正请求仍是正常计费的文本模型任务，不创建媒体任务。
 
 系统行为策略版本升至 14，明确工具调用数量与单个 `canvas_apply_ops` 操作数量的区别。已有会话保留其冻结策略快照；部署后用新会话验证新提示词，不修改历史检查点。
+## Agent 分镜连线参数反馈
+
+素材绑定使用“素材→分镜”和 `toHandleId: row:<rowId>`；镜头输出使用“分镜→图片/视频”和 `fromHandleId: row:<rowId>`。`rowId` 必须是读取工具返回的真实行 ID，不能用镜头编号代替。普通节点连线与镜头行连线按 handle 区分，已有整表连线不代表该行已经绑定。
+
+handle 放错端点、格式错误或行 ID 不存在时，工具错误回执提供具体 `field`（如 `ops[0].fromHandleId`）、`issue`、方向说明及连线参数模板，不再使用无关的新增节点示例。模板不会被自动执行，不自动交换端点或修改原调用。权限、快照和重复连线校验保持不变；工具契约版本为 v4，重启后端后新会话使用更新后的说明。
 
 ## 注册邮箱等价检查
 

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

@@ -18,6 +18,12 @@ description: 当前项目已实现功能的手工验证清单与未确认边界
 - [x] PostgreSQL 临时 schema 在修改前复现“工具调用游标无效”；修改后验证 8 个调用允许、9/31 个调用纠正后恢复、持续超限最多 3 次重试及超长正文纠正。策略文档专项测试通过；未调用真实供应商。
 - [ ] 部署后在新会话验证大型任务按批执行；观察文本模型纠正次数及费用，失败时不声称已执行。
 - 本项独立于画布大事件修复，不改变审批和画布写入流程。
+## Agent 分镜绑定参数引导
+
+- 已优化：工具说明区分素材输入和镜头输出的两个 JSON 示例；handle 错误明确字段、正确方向和真实 rowId 要求，并在回执附上对应连线模板。不放宽校验、不自动改线。
+- [x] 专项测试覆盖来源/目标 handle 放错节点、镜头编号误用、缺少 row 前缀、错误回执模板方向、普通连线与行绑定并存，以及重复行绑定仍拒绝；工具 schema 体积检查通过。
+- [x] 用户已在本地验证镜头绑定可用；自动化测试不调用外部模型，不修改实际创作画布。
+- [ ] 上游合并后验证新会话沿用正确绑定方向，错误调用不会被误报为成功。
 
 ## 复制生图节点后节点消失