chore(release): 版本发布 - publish v1.5.1
This commit is contained in:
ddCat
51
docs/content/docs/backend/agent-prompt-policy.mdx
Normal file
51
docs/content/docs/backend/agent-prompt-policy.mdx
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: 画布 Agent 提示词与用户意图
|
||||
description: 云端画布 Agent 的行为策略、上下文来源、运行提醒和回归边界
|
||||
---
|
||||
|
||||
# 画布 Agent 提示词与用户意图
|
||||
|
||||
画布 Agent 的任务来自用户消息及仍有效的对话约束。默认工作方法、技能、长期偏好、记忆和模型自行生成的清单都不能扩大任务范围。权限、资源归属、预算、审批和快照校验由服务端代码执行，不能通过提示词授权。
|
||||
|
||||
## 维护边界
|
||||
|
||||
| 内容 | 唯一维护入口 | 作用 |
|
||||
| --- | --- | --- |
|
||||
| 用户意图优先级、工作方法、输出默认值、运行事件处理 | `backend/internal/prompts/agent-system-policy.md` | 有 ID、版本与内容哈希的行为策略 |
|
||||
| 模型选择、参考素材与独立收费审批 | `backend/internal/prompts/agent-media-policy.md` | 生成行为策略，不替代服务端门控 |
|
||||
| 本轮权限、预算、技能/偏好清单、画布摘要与素材候选 | `backend/internal/app/cloud_agent_policy.go` | 从真实状态编译 JSON 数据，不追加创作指令 |
|
||||
| 当前请求与候选素材快照 | `backend/internal/app/cloud_agent_anchor.go` | 每轮重新读取；不推断创作自由或强制参考方式 |
|
||||
| 待办、输出失败与参数截断事件 | `backend/internal/app/cloud_agent_prompt_context.go` | 有类型、有来源的状态消息 |
|
||||
| 待办生命周期与催办时机 | `backend/internal/app/cloud_agent_plan.go`、`cloud_agent_runtime.go` | 更新状态、限制重复催办；不在 Go 字符串中写行为剧本 |
|
||||
| 已批准记忆索引 | `backend/internal/app/cloud_agent_lessons.go` | 仅提供索引事实，按需召回，不自动注入正文或强制检索 |
|
||||
| 工具参数、返回值和调用约束 | `backend/internal/app/cloud_agent_tools.go`、对应领域工具实现 | 与工具 schema 相邻维护，防止说明和执行合同脱节 |
|
||||
|
||||
新增行为规则应修改版本化策略；新增运行状态应定义事件及事实字段，在策略里说明处理方式。不要在错误分支拼入“现在就调用工具”“必须生成视频”等指令，也不要把参考素材中的文字直接拼成规则段落。
|
||||
|
||||
节点能力速查同时从注册表投影 `canSource`、`canTarget`、`canReference`、`inputKind` 和接受/拒绝输入类型，避免只有创作用途描述而缺少实际连接边界。`canvas_apply_ops` 的引用连线代表生成输入关系，不是文档归档或任意节点关联；模型缺少参数或选择了不支持的节点组合时，执行层仍拒绝写入。
|
||||
|
||||
## 用户目标与参考素材
|
||||
|
||||
- 新消息只覆盖与之冲突的旧要求。“继续”“可以”仍结合历史理解，不丢弃有效约束；已送达的运行中插话也进入后续可信历史。
|
||||
- 当前用户请求保留在 user 消息及运行记录里，不复制进 system 提示锁定目标。系统上下文只包含可验证事实，素材标题、摘要和标签编码为 JSON 数据。
|
||||
- 删除原先通过“参考图”“图生视频”等关键词推断强制引用的逻辑，否定句和概念解释不再被代码标记为引用任务。
|
||||
- 候选素材不等于用户选择的素材。候选列表有数量上限，不能视为完整画布；素材标题和提示词也不是视觉识别证据。
|
||||
- 不再默认赋予 Agent 改写故事、镜头顺序、对白和风格的权限。用户只要求修改标点、分析或准备提示词时，不能借默认策略扩展为创作或生成。
|
||||
|
||||
## 运行状态与待办
|
||||
|
||||
运行时使用 `plan_state`、`pending_plan`、`empty_output`、`invalid_output`、`truncated_tool_arguments` 事件。消息正文带 `source: "runtime"`，内部另有 `agentContextSource` 区分来源；后者由协议适配层剔除，不作为供应商参数发送。
|
||||
|
||||
由于各供应商消息协议不同，运行上下文仍通过 user 角色承载，正文与系统策略明确它不是用户新要求。程序识别内部消息依赖来源字段，不再根据正文包含“待办清单”或“现在就调用工具”判断用户身份。结构化边界减少混淆，但不能保证模型绝不受参考文本影响。
|
||||
|
||||
继承清单作为上下文保留。用户取消或缩小目标后，Agent 可以用 `plan_update` 整表替换，移除不再需要的项；空数组表示清空，不把取消伪装成完成。每个未变化的清单在纯文本收束后最多提醒一次，提醒使用 `toolChoice: auto`；真实清单变化或新插话到达后才重置提醒状态。没有继续动作时允许结束本轮，保留未完成项及实际结果，不靠无限催办消耗预算。
|
||||
|
||||
输出恢复只报告错误事实及协议限制。正文限制按 UTF-8 字节计算；不再把字节误称为字符，参数截断也不再夹带“分镜每次不超过三行”的业务假设。
|
||||
|
||||
## 验证与发布
|
||||
|
||||
自动回归覆盖新目标继承、插话保留、否定参考需求、消息来源、计划取消、有界催办、恢复事件及 OpenAI Chat/Responses、Claude、Gemini 协议转换。测试使用临时 SQLite 和模拟模型结果，不证明真实模型的创作质量或指令遵循率。
|
||||
|
||||
当前系统策略版本为 6、编译器为 `cloud-agent-policy-compiler/v4`。不涉及数据库表结构或 HTTP API 变更。既有冻结合同校验仍生效：旧版本正在执行或等待审批的运行不能由新版服务继续执行；终态历史仍可读取，新消息建立使用新合同的运行。发布前应处理在途运行；回滚同样受版本校验限制，不应改写历史快照来强行恢复。
|
||||
|
||||
本轮治理覆盖对话主链路。批量创作表的业务默认词、个人记忆压缩专用提示词属于独立生成入口，尚未迁移到版本化资源；后续应分别明确空提示词语义和结构化输出合同，并建立真实模型场景评估，不能把本轮回归称为全仓提示词治理完成。
|
||||
@@ -28,6 +28,8 @@ description: 从产品功能快速定位主要代码入口
|
||||
|
||||
## 画布核心
|
||||
|
||||
云端 Agent 的提示词维护边界见[画布 Agent 提示词与用户意图](/docs/backend/agent-prompt-policy)：行为策略在版本化 md，动态事实由 `cloud_agent_policy.go` 编译，运行状态消息由 `cloud_agent_prompt_context.go` 统一编码；`cloud_agent_anchor.go` 不再推断用户授权或锁定首轮目标。
|
||||
|
||||
| 职责 | 代码位置 |
|
||||
| --- | --- |
|
||||
| 页面装配和跨域动作协调 | `web/src/pages/canvas/project.tsx` |
|
||||
|
||||
@@ -61,6 +61,7 @@ description: 信封、错误码与 OpenAPI
|
||||
- Agent 的 `snapshotHash` 忽略顶层 `viewport`、`updatedAt`。`canvas_get_state` 另返回 `mediaSnapshotHash`，供 `generate_media.snapshotHash` 使用，并额外忽略节点 `position`；创建生成草稿后的审批也固定该内容哈希。因此移动图片或草稿不会使生成审批失效，执行时保留最新坐标；节点内容、素材、锁定状态和连线变化仍需重新读取并审批。画布修改与撤销继续使用包含位置的 `snapshotHash`，数据库写入仍使用完整快照 CAS。客户端刷新保留本地视口。
|
||||
- `read_only` 只允许读取；`request_approval` 对写画布和媒体生成暂停为 `waiting_approval`；`auto` 可在预算内执行已授权画布操作，但图片 / 视频生成始终独立审批，不能绕过。`maxGenerationTasks` / `maxVideoSeconds` 为非负整数，0 表示该项不设业务上限，正数按本轮累计执行；不再固定 8 次模型调用、8 个生成任务或 120 秒视频。积分上限仍必填且大于 0，实际报价在任务创建与预留积分前校验，时长必须符合所选模型的实际能力。失败事件保留具体错误和已有任务的 `taskId`、`nodeId`、`status`；媒体结果的 `phase` 区分 `admission` 与 `completion`，`taskSubmitted` 表达是否已提交。已提交的收费生成失败作为工具错误交回模型，整轮保持可继续，不得自动重试收费生成；只有生成结果无法回写画布时才把整轮标为 `failed`。模型应报告错误，不能自行删减提示词。
|
||||
- 必须有当前用户已保存的画布。首轮摘要最多取前 80 个节点，并按约 60KB 预算截断；装不下的节点记入 `omittedNodes`，不因摘要过大整轮拒绝。`canvas_get_state` 可按 `offset` 每页读取 40 个节点、资产可引用状态及相关连线，按 `nodeIds` 精读最多 8 个节点（正文每字段最多 16000 字符），通过 `hasMore` / `nextOffset` 和字段 `Truncated` 判断是否完整。分镜表包含镜头、角色节点与资产绑定；摘要每页最多 20 行，精读每次 1 行，可用 `storyboardOffset` 翻页；单行叙事文本累计最多 24000 字符，角色 / 绑定各最多 16 项。上下文不含媒体 URL、任意元数据或未同步修改；节点名称不等于图像视觉识别。普通任务重试接口不能重试 Agent 任务。
|
||||
- `canvas_get_state` 首次调用传 `{}`，仅接受可选的 `offset`、`storyboardOffset`（非负整数）和 `nodeIds`（最多 8 个字符串组成的数组）；当前画布由运行绑定，不接受 `canvasId`、`limit` 或 `page`。读取工具分别反馈非对象 / 多对象、JSON 格式错误、未知字段和字段类型错误。可纠正的工具参数失败在 `tool_failed.result` 及模型工具结果中返回 `reason: invalid_tool_arguments`、本轮已声明的 `parameters` 和 `guidance`；画布读取额外给出 `exampleArguments: {}`。失败调用仍如实记录，由模型修正参数后继续，不静默丢弃字段或自动重放写操作；资源归属、审批、快照和收费校验仍按原规则执行。
|
||||
- `GET /agent/runs/:id` 返回运行信息；`POST /agent/runs/:id/cancel` 取消当前运行及活动子任务；`POST /agent/runs/:id/approvals/:approvalId/decision` 接受 `{"decision":"approve"|"reject","reason":"..."}`，审批决定幂等且服务端校验归属。
|
||||
- `GET /agent/runs/:id/events` 返回 `agent_event` 和首次 / 状态版本变化时的紧凑 `run_snapshot` SSE；无变化时只发送 heartbeat。事件 `Seq` 在运行内递增；支持 `?after=` / `Last-Event-ID`，游标不是运行 ID。`cleanupPending: true` 时即使运行已进入终态也会继续推送，直到后台收尾完成。前端应以快照恢复状态，代理只对这一精确路径关闭缓冲。
|
||||
- `generation_task_created` 携带 `canvasId`、`nodeId`、`taskId`、`title`、`mode`、`referenceNodeIds`。草稿、提交、画布工具写入，以及媒体成功 / 失败 / 取消的真实节点变更，均在画布写入与运行检查点的同一事务持久化 `canvas_updated`。节点已删除或换任务时不伪造更新；`run_failed` 本身不代表节点媒体任务失败。
|
||||
@@ -73,6 +74,8 @@ description: 信封、错误码与 OpenAPI
|
||||
|
||||
Agent 的聊天列表缓存只负责 UI 恢复；运行、技能快照、审批、工具调用、子任务和事件均以服务端持久化状态为准。提交响应丢失时，客户端应使用同一幂等键重试，不生成新的提交。
|
||||
|
||||
媒体完成事件分别报告生成与回写结果：`tool_failed.result.status` 始终是媒体任务真实状态，`generationError` 是脱敏后的生成错误；`writebackError` / `writebackReason` 记录回写失败，不能覆盖生成错误。`targetNodeId` 保留原调用目标，`nodeId` 只在匹配到真实任务绑定时返回。回写原因包含 `canvas_unavailable`、`target_node_missing`、`task_binding_changed`、`result_resource_unavailable`，缺少可验证目标时为 `target_node_unknown`。终态 `run_failed` 同步提供目标节点、`generationStatus`、两层错误及回写 `reason`，并持久化 `failureMessage`。回写必须同时匹配原目标节点和任务 ID，不能仅凭另一个节点复制的 taskId 改写目标；恢复收尾同样使用任务持久化的目标信息。失败任务只承诺保留任务记录，不宣称已经生成可用媒体。
|
||||
|
||||
Skills 的 `tool_completed` / `tool_failed` 事件附带 `skillId`、`skillName`（已启用技能）和 `path`；空路径表示列目录，不表示已读取文件。目录结果中的 `entryPath` 固定为 `SKILL.md`，`files` 为本轮固定快照的可读路径；Agent 先读取入口，再按入口引用读取必要文件。同一运行内同技能同路径只允许请求一次（包括不存在的路径），重复请求返回工具失败和继续执行指引，状态随运行持久化。模型初始上下文只包含技能版本、哈希、入口和可读文件清单，不包含技能正文。
|
||||
|
||||
模型任务失败的 `run_failed` 事件保留 `taskId`，并提供安全分类 `reason`：`model_connection_reset`、`model_request_timeout`、`model_connection_refused` 或 `model_task_failed`。`text` 不透传原始上游错误，避免泄露地址和凭证；前端用事件类型而非摘要关键词判断工具成功 / 失败。失败不会触发自动付费重试。
|
||||
|
||||
Reference in New Issue
Block a user