v0.0.15

安装运行

Docker（推荐）

docker run -d --name agnes-platform -p 8080:8000 -v agnes-data:/app/data ghcr.io/wingkysky/agnes-ai-platform:v0.0.15

免 Docker 便携包（Windows / macOS Apple Silicon）

从下方 Assets 下载对应平台的 zip，解压后双击 start-windows.bat（或 macOS 的 start-macos.command）。
macOS 首次运行先在终端执行 xattr -cr <解压目录> 去除下载标记；详见包内 README-PORTABLE.txt。

打开 http://localhost:8080 （便携包为 8000），按首启向导完成管理员密码与 AI 服务配置即可使用。
更多方式（docker compose / 公网服务器反代与 HTTPS / 数据备份）见 docs/deployment.md。

---

3D 导演台：全屏工作台 + 运镜路径 + Agent 对话式调度

• 导演工作台第一批：场景挂载生成（生成页场景 chip + 提示词拼接「场景设定：」镜头语言 + 视频 camera_params 映射）、视口拍照（封面弹窗 + scene3d.cover_url）、16:9/9:16/1:1/2.35:1 画幅取景框（letterbox + 三分线，截图按画幅裁剪）、镜头跟随（移动相机自动朝向选中主体）
• 全屏工作台重构：导演台页藏侧栏/顶栏/页脚的全屏变体，顶栏/左栏场景树+场景库/中央视口/右栏属性+Shot 检查器/底部序列器/状态栏，面板全部可拖拽缩放折叠、F 一键全屏、布局 localStorage 记忆；SceneData v2（id 寻址 + 多机位 cameras[] + shots[] 景别 6 档/运镜 9 种/时长 fps/关键帧），后端严格 Pydantic 校验；视口内核重写（多机位拟物、漫游 PointerLockControls、镜头序列预演逐镜头截封面回写）；16 关节程序人偶 + 12 姿势预设即时切换
• 运镜路径：四种形状生成（直线/环绕/矩形/铅笔手绘）+ 沿径采样 2~24 帧成相机关键帧（朝行进前方/恒对准注视点），视口路径组可拖顶点编辑；Shot 检查器「运镜路径」区 + 主体「走位路径」区
• Agent 对话式场景调度：scene_read/scene_edit 工具组（分集合替换语义、整批原子校验、校验失败回 errors 供模型重试），导演台挂载注册数据桥；修改只作用编辑态、保存留顶栏确认
• Agent 宿主面板三态共存：small 小态（可图钉钉住）/ float 浮窗 / dock 右侧全高侧栏（页面挤窄让位），dock 档会话列表按需拉出浮层；Esc 分级回退

剪辑器：AI 协作闭环

• 选区引用：剪辑器页选中片段/轨道 → Agent 输入区「引用」按钮或 Ctrl/Cmd+Shift+L 生成编号引用卡（含片段缩略图），agent 收到精确 clipId/trackId 直接寻址；引用随消息落库、多轮对话可回溯
• Agent 写入冲突重放：agent 批量编辑撞上用户改动（409）时自动拉最新文档重放整批 ops 再保存（上限 3 次），用户编辑天然保留；重放失败报具体 op 与错误码，绝不部分写入
• 渲染质检：渲染成功后自动单 pass 检测黑场/冻结/静音，落在淡入淡出/黑场转场/图片静帧窗口的自动标「可能刻意」不误报；报告三口透出（顶栏徽标+详情弹窗 / 渲染状态 API / agent 工具结果摘要）
• I/O 点与区域引用：I/O 键设入出点（标尺括号+区间淡色带），引用一键捕获「时间段+片段」两张卡；质检弹窗「让 Agent 修复」一键发起修复→重渲闭环

剪辑器：导出能力

• 导出设置：分辨率预设（竖屏 1080×1920 短剧首选 / 720p / 1080p / 方形）+ 自定义 + 帧率 24/25/30/60（setDocumentMeta 命令入撤销栈，字幕字号随宽度自动缩放）
• 剪映草稿导出：一键导出剪映可直接打开的草稿包（draft_info.json + draft_meta_info.json + 素材），微秒帧对齐时间、PIP 半画布坐标、字幕走剪映原生字幕轨、变速/音量/转场/滤镜全映射
• GIF / 仅音频导出：成片后处理（GIF 调色板两遍，默认 480px/12fps，超 120s 守门；音频 aac 192k）
• 版本历史还原 UI：agent 写前快照列表 + 一键还原（来源标签：Agent 写入 / AI 粗剪 / 生成字幕）

剪辑器：时间线硬实力

• 多选与批量操作：Ctrl/Cmd 点选、轨道空白拖动框选（跨轨）、整组拖移（任一碰撞整批不动）、批量删除/静音，全部走单条历史（一次撤销回滚整批）
• 波纹删除 / 闭合同轨空隙：删片段后续自动左移补位；同轨空隙一键收紧（对话式剪辑同步可用）
• 时间线标记：M 键/工具栏打点，标尺菱形点击跳转、双击删除，随文档持久化
• 冻结帧：视频片段右键在播放头处截帧，split + 右移 + 插入 3s 静帧一次完成

画布 @节点引用

• Agent 对话输入 @ 触发画布节点弹层（分组类型徽标 + 缩略图 + 名称/类型过滤 + 键盘导航），选中插入 @名称 并生成引用卡；agent 收到精确 nodeId（媒体节点提示可 agent_read_image 读画面）；「引用选中」按钮/⌘⇧L 同键扩展到画布宿主；引用只是寻位，不改变任何生成确认门

修复

• 图片片段渲染全链不可用（存量）：图片素材归一化对单帧用 -ss/-t 输入选项产无流 mp4，终版合成绑定失败；改 -loop 1 循环铺满时长

• 片段右键菜单被轨道菜单覆盖（存量，事件冒泡）；点轨道后多选态残留；冻结帧批量命令漏移 split 右半与移位顺序错

• 场景快捷面板 popover 受控模式导致触发点击失效（存量）

• 测试 pytest 416 / vitest 763 / vue-tsc + 双端 lint + build 绿；导演台/剪辑器/画布关键链路浏览器实机冒烟全过（含真实渲染→质检命中→修复入口全链）

v0.0.14

安装运行

Docker（推荐）

docker run -d --name agnes-platform -p 8080:8000 -v agnes-data:/app/data ghcr.io/wingkysky/agnes-ai-platform:v0.0.14

免 Docker 便携包（Windows / macOS Apple Silicon）

从下方 Assets 下载对应平台的 zip，解压后双击 start-windows.bat（或 macOS 的 start-macos.command）。
macOS 首次运行先在终端执行 xattr -cr <解压目录> 去除下载标记；详见包内 README-PORTABLE.txt。

打开 http://localhost:8080 （便携包为 8000），按首启向导完成管理员密码与 AI 服务配置即可使用。
更多方式（docker compose / 公网服务器反代与 HTTPS / 数据备份）见 docs/deployment.md。

---

Provider 智能接入（声明式 HTTP 渠道：不写代码接长尾渠道）

• 声明式执行器：api_providers 新增 http_config JSON 列 + provider_type 新值 http_custom（前端新分组「声明式接入」），管理员以模板配置接入任意 HTTP 渠道，无需写代码。新 DeclarativeHttpClient 实现统一客户端四方法契约（list_models / create_image / create_video_task / poll_video_status），返回形状严格合成现有消费方硬契约——failover 路由、任务账本、积分、转存、出口记账全部零改动兼容
• 配置 schema（HttpConfigModel 严格校验 extra=forbid）：模型目录三模式（static 静态列表 / openai 兼容 /models / custom 自定义端点）、同步图片单 POST（url_path/b64_path 点路径响应映射）、视频两段式（提交拿 task_id + 轮询 status_map 状态归一，未知状态保守按 processing 续轮到超时）；请求体 {{prompt}}/{{model}}/{{size}}/{{images}}… 占位符模板（JSON 转义渲染），超时按动作区分；视频 create 与 poll 强制成对
• 健壮性：非 2xx 翻译为 UpstreamError（带 status_code/error_kind，与 error_taxonomy/failover 判定语义一致）、网络异常与 5xx 指数退避重试、success 但无有效视频 URL 判失败；保存前用样例值试渲染请求体模板（占位符漏写保存即报）；POST /api/providers/{id}/test-http 真实请求模型目录验证配置；http_config 变更自动重建渠道客户端。内网地址故意放行（自托管接本地 LiteLLM/one-api 代理是核心场景）
• AI 生成配置（纯前端零后端新增）：Provider 弹窗「AI 生成配置」区——粘贴渠道 API 文档片段或 cURL 示例 → 走现有 LLM 前端透传通道生成配置 JSON（内嵌 schema 说明与占位符清单）→ 剥代码围栏+括号配对解析+轻校验 → 一键填入表单可手动微调。实测生成质量：端点路径、嵌套响应映射（result.images.0）、数字占位不带引号均正确
• 管理端：Provider 弹窗三动作卡结构化表单（lib/provider-http-config.ts 纯函数双向转换）+「测试连接」按钮；任务状态响应与账本回退补齐 provider_name 实际渠道透出
• 测试 pytest 386（+24：模板渲染转义/点路径提取/图片与视频映射/轮询状态机/未知状态保守处理/非 2xx 翻译/重试/list_models 三模式/HttpConfigModel 校验/API 保存与 test-http）；vitest 676（+11：表单⇄配置双向转换/AI 输出解析围栏剥离）；vue-tsc + 双端 lint 绿

v0.0.13

安装运行

Docker（推荐）

docker run -d --name agnes-platform -p 8080:8000 -v agnes-data:/app/data ghcr.io/wingkysky/agnes-ai-platform:v0.0.13

免 Docker 便携包（Windows / macOS Apple Silicon）

从下方 Assets 下载对应平台的 zip，解压后双击 start-windows.bat（或 macOS 的 start-macos.command）。
macOS 首次运行先在终端执行 xattr -cr <解压目录> 去除下载标记；详见包内 README-PORTABLE.txt。

打开 http://localhost:8080 （便携包为 8000），按首启向导完成管理员密码与 AI 服务配置即可使用。
更多方式（docker compose / 公网服务器反代与 HTTPS / 数据备份）见 docs/deployment.md。

---

多渠道路由 failover（生成任务：主渠道失败自动切备用渠道）

• 数据模型：新表 model_routes（锚点模型 → 备用渠道裸对 (provider_id, model_id)，priority 越小越优先，启动 create_all 自动建；模型同步不触碰，删除锚点模型/渠道级联清理）——目标为裸对不要求存在定义行，同款渠道与等价模型均可作备用；api_providers 新增 billing_tier（free/paid，默认 paid，存量库手动 ALTER），仅用于配置时跨档警示不做硬闸（显式配置即授权，免费渠道永远不会被切到未配置的付费渠道）
• 路由与切换（新 services/model_routing.py）：路由链 = 锚点自身渠道恒链首 + 启用备用按 priority 升序；切换判定复用 error_taxonomy——rate_limited/network_transient/upstream_server/timeout/unknown 五类且未拿到上游凭据才切换，参数/审核/账户类直接抛，submission_uncertain 永不切换（防重复扣费红线）；视频提交阶段明确 HTTP 拒绝（429/5xx 无 task_id）按未接单可切、网络中断类保守不切（failover 局部语义，不改全局合同）；候选耗尽抛最后一个错误并归因真实类目
• 链路接入：图片 _gen_loop 与视频提交段替换为 failover 执行器（积分只预扣一次不变）；视频轮询锁定提交渠道（route_used 快照进账本 context，轮询期不重路由——顺带修掉存量「每轮 get_client_for_model 重路由」的多渠道隐患，无快照存量行回退旧行为）
• 留痕与透出：api_call_logs 补齐 provider_id/真实渠道名归因（原硬编码 "Agnes"，每渠道一行即尝试留痕）；失败消息附「已在 N 个渠道间尝试」；任务轮询响应新增 provider_name，TaskCard 成功态显示实际渠道
• 管理端与前端：GET/PUT /api/models/{model_id}/routes（管理员，401/403/200 三态测试锁死，校验锚点 404/渠道不存在/重复/目标类型一致均 400）；模型编辑弹窗「备用路由」区（候选选择/手填未同步模型/排序/启停/跨档黄条警示/一键加入同款其他渠道，lib/model-routes.ts 纯函数层）；Provider 弹窗「计费档位」；i18n 中英
• 测试 pytest 361（+32：路由链解析/failover 类目判定/执行器切换行为/图片视频链路集成含 route_used 落账本/轮询锁定与回退/CRUD 鉴权三态与校验/唯一约束/级联清理）；vitest 665（+8 路由编辑纯函数）；vue-tsc + build + 双端 lint 绿

v0.0.12

安装运行

Docker（推荐）

docker run -d --name agnes-platform -p 8080:8000 -v agnes-data:/app/data ghcr.io/wingkysky/agnes-ai-platform:v0.0.12

免 Docker 便携包（Windows / macOS Apple Silicon）

从下方 Assets 下载对应平台的 zip，解压后双击 start-windows.bat（或 macOS 的 start-macos.command）。
macOS 首次运行先在终端执行 xattr -cr <解压目录> 去除下载标记；详见包内 README-PORTABLE.txt。

打开 http://localhost:8080 （便携包为 8000），按首启向导完成管理员密码与 AI 服务配置即可使用。
更多方式（docker compose / 公网服务器反代与 HTTPS / 数据备份）见 docs/deployment.md。

---

修复 FRONTEND_ORIGINS 逗号分隔格式启动崩溃

• pydantic-settings 对 List 类型复杂字段做严格 JSON 预解码，.env/环境变量写逗号分隔格式（FRONTEND_ORIGINS=http://a,http://b）会在解码阶段直接抛 SettingsError（parse_origins validator 无机会运行）。frontend_origins 加 NoDecode 跳过预解码，交由既有 parse_origins 统一兼容 JSON 数组/逗号分隔两种格式；.env.example 注释同步。四场景实测：逗号分隔（环境变量/.env 文件）、JSON 数组、默认值全部正常，pytest 310 绿

诊断包导出（可靠性三件套 ③：管理员一键脱敏诊断 ZIP）

• 端点：GET /api/admin/diagnostics/export（显式挂 get_current_admin_user）→ 内存组装 ZIP 流式返回，agnes-diagnostics-YYYYMMDD-HHMMSS.zip（UTC 命名，ZIP 注释标注 sanitized）
• 九项内容（全部脱敏+封顶）：meta.txt（VERSION/Python/OS/进程运行时长/库引擎名——连接串打码只留 sqlite 文件名）；config_sanitized.json（系统配置全键值——键名含 password/secret/token/key 的值整段打码 ***<len>，.env 只列键名不列值，Provider 清单 api_key 只报已配置/未配置）；主日志尾 2000 行 + frontend.jsonl 1000 行 + errors.jsonl 500 行（文件尾 seek 读不整读大文件）；generations_recent.json 最近 100 条（任务账本口径含 pending/uncertain，prompt 截 200 字/错误截 500 字，不导 params/context/result_url）；api_calls_recent.json 最近 100 条（不导 endpoint/payload）；storage_summary.json（复用②概览）+ table_stats.json 核心表行数
• 脱敏红线：用户身份内容不入包（无用户名/邮箱，top_users 仅 user_id）；secret 整值打码；文本字段截断
• 前端：/admin/logs 工具栏新增「导出诊断包」按钮（复用 downloadViaProxy 带鉴权下载，loading 态，成功/失败提示），i18n 中英
• 测试 pytest 329（+2：鉴权三态 + ZIP 内容清单/打码断言含原文不入包/截断上限/meta 结构）；vitest 657 + vue-tsc + build 绿

存储配额（可靠性三件套 ②：台账记账 + 两阶段预留）

• 新表 storage_objects 用户存储台账（只增不删，storage_key 唯一索引幂等）：user_id/bytes/kind/source(upload/generation/render)/created_at；用量 = SUM(bytes) per user；S3 转存件不占本地账
• 两阶段预留：用户主动上传先预检（每用户总配额 + 滚动 24h 上传量，双维度）→ 落盘成功记账；预检不预占行，单实例并发同检的少量超卖可接受；超限 413（detail 区分「存储空间已满」/「24 小时上传上限」）
• 三路接入：save_upload_file 加 user_id/source 可选参（canvas 素材上传接线；preset-covers 官方目录不计）；生成产物归档 ingest_generation_asset（source=generation）与成片归档（source=render）；剪辑渲染成片落盘记账（软处理：记账失败仅告警，绝不阻断已扣积分的生成/渲染主链路）
• 配置：系统配置新增 storage_quota_mb（默认 5120）/daily_upload_quota_mb（默认 2048），0 = 不限制；v1 不做 per-user 覆盖
• 存量回填：ensure_storage_ledger 挂 lifespan ensure 链路（幂等），按 assets.storage_key 补台账（本地文件存在才计）；canvas 历史孤儿文件无法归属不回填
• 端点与前端：GET /api/storage/usage（登录级，used/quota + 24h 上传）+ GET /api/admin/storage/overview（管理员，平台总量 + top N 用户，显式挂鉴权）；个人资料页新增「存储用量」卡（总量/每日两行 + 进度条，quota 为 null 显示未启用）
• 测试 pytest 327（+8：预检三态/每日只计上传且滚动窗口/记账幂等与 S3 跳过/回填幂等/端点鉴权三态/canvas 超限 413 集成）；vitest 657 + vue-tsc + build 绿；坑：system_config 60s 内存缓存会跨测试泄漏配额值，测试后须清 _config_cache；Mimosa 新文件拦 db.execute 聚合 → 实体取回 Python 聚合（概览低频可承受）

任务恢复体系（可靠性三件套 ①：重启不丢任务、积分对账退款）

• generations 表升级为任务账本：提交即落 pending 行（新增 video_id 恢复凭据列——上游可能只返回 video_id 无 task_id、context 完整创作上下文列——恢复续轮询回填用；dev 库已 ALTER），终态由轮询器按 (user_id, task_id, type) 幂等 upsert 同一行（persist_generation/persist_generation_failure 改 fetch-or-create，重放不重复插行不重复退款）；pending 行保守初值 is_public=False+moderation_status='approved'（不泄漏进广场/审核队列）
• 启动恢复（lifespan，poller 就绪后）：扫账本未终态行——视频任务凭原 task_id/video_id 重注册续轮询（本地 task_id 不变，前端轮询无感）；超等待窗口（2×video_poll_timeout_sec）的视频行与全部图片行（同步接口无上游凭据）置 uncertain + 退预扣积分（不自动重提，submission_uncertain 类目天然阻断自动重试）
• 运行时对账兜底：周期协程（5 分钟）扫 pending/processing 超 age 上限的行 → uncertain + 退款，覆盖轮询协程异常死亡漏置终态的场景；退款复用 refund_credits 按 pending 流水过滤，重复对账幂等
• 轮询端点 DB 回退升级：图片/视频状态端点内存 miss 时回退账本行——进行中返回 pending/processing（elapsed 从 created_at 推算，前端持续轮询）、终态返回结果、uncertain 映射为 failed+类目（DB 留 uncertain 审计；前端终态集合 success/failed/cancelled，uncertain 不外泄防永久轮询）；视频回退凭据扩为 task_id OR video_id 双匹配
• 取消接账本：图片 _gen_loop CancelledError、视频上游 cancelled/CancelledError 分支同步把账本行置 cancelled
• 测试 pytest 319（+9：账本行保守初值/成功失败幂等 upsert/uncertain 对账+退款幂等/cancel 置位/恢复三态/空账本 noop/图片与视频端点回退）；vue-tsc + vitest 657 回归绿（前端零改动）；修 naive-UTC 时间戳 .timestamp() 被按本地时区解释导致 age 计算带时区偏移的坑（显式挂 UTC 后做差）

全局宿主头部新增「新建对话」按钮

• Agent 宿主面板头部按钮组最左新增新建对话钮（lucide MessageSquarePlus，title/aria 复用既有 agent.drawerNew 中英文案），点击与展开态会话侧栏的「新建」同入口（handleNewSession：画布页自动带当前工作区上下文标记）；@dblclick.stop 防连点误触头部的双击档位切换

对话编排端点退役（画布两处 LLM 调用迁前端透传通道，chat_service -1700 行）

• 历史归属改随节点存画布：text 节点多轮对话历史从后端 chat_sessions 表迁到节点 content.messages（user/assistant 条目，守卫式校验剔除坏行），随画布本地+云端持久化、跟着节点复制/删除/跨设备走；旧 chat_session_id 字段废弃（项目未上线不兼容）。宿主会话列表不再混入以节点名命名的「幽灵会话」，聊天表回归宿主单一职责
• 通用透传通道：lib/storyboard/transport.ts 扩展为通用 LLM 通道（分镜管线/text 节点对话/图片反推共用）——ChatMessage.content 支持 OpenAI 多模态 content parts（text/image_url）、ChatCallOptions 加 onDelta 增量回调，接口向后兼容
• text 节点对话重写（CanvasNodeComposer）：sseChatComplete 流式调用（模型走 getDefaultModel('chat') 偏好链，与宿主同链）+ 固定轻量 system（直接输出正文不寒暄，随请求前插不落存储）；捕获目标节点 id，切换节点不再把流式内容串写到别的节点（旧链路存量隐患顺带修复）
• 图片反推重写（CanvasView 悬停工具栏）：单次 sseChatComplete 调用（data: URI 与 http URL 同走 image_url 形状），反推指令抽 buildReversePromptMessages 纯函数（lib/canvas-generation）；不再建/删临时会话，流式双写两个节点的 UI 行为与原来一致
• 后端删除：POST /api/chat/sessions/{id}/messages 编排端点 + SendMessageRequest 退役；chat_service 从 2046 行减至 ~340 行（删 stream_reply/_reply_event_stream/chat_stream/_stream_chat_api/_execute_tool/_execute_generate_image/_execute_generate_video/build_history/validate_attachments 等整条服务端编排与工具执行链 + CHAT_TOOLS/SYSTEM_PROMPT），保留 open_completions_stream（透传）/summarize_session_title（宿主标题）/refresh_message_media_items（宿主历史恢复）；前端删 sendMessageStream 与孤儿类型（SendMessageRequest/SSEEvent/ToolResult）；GET messages（宿主恢复在用）与会话 CRUD 全保留
• 测试：pytest 310（+1：编排端点退役 404 + GET messages 存活双向锁死）；vitest 657（+6：transport 消息组装/多模态形状/onDelta 增量/空回复报错/非 200 报错 + 反推消息构造）；vue-tsc 0 错 + build 过

v0.0.11

安装运行

Docker（推荐）

docker run -d --name agnes-platform -p 8080:8000 -v agnes-data:/app/data ghcr.io/wingkysky/agnes-ai-platform:v0.0.11

免 Docker 便携包（Windows / macOS Apple Silicon）

从下方 Assets 下载对应平台的 zip，解压后双击 start-windows.bat（或 macOS 的 start-macos.command）。
macOS 首次运行先在终端执行 xattr -cr <解压目录> 去除下载标记；详见包内 README-PORTABLE.txt。

打开 http://localhost:8080 （便携包为 8000），按首启向导完成管理员密码与 AI 服务配置即可使用。
更多方式（docker compose / 公网服务器反代与 HTTPS / 数据备份）见 docs/deployment.md。

---

MCP 接入独立页（信息架构：个人资料页 → 侧边栏一等条目）

• 参照 Cherry Studio/LobeChat（MCP 一级条目）、Claude Desktop（Connectors）、GitHub（Developer settings）惯例，MCP/PAT 设置从「个人资料」页迁出为独立页面 /mcp：侧边栏「个人」分组新增「MCP 接入」菜单项（图标 Connection，顶栏不显示，菜单缓存版本 7→8）
• 页面三块：页头说明 + PAT 管理卡（清单/新建/一次性明文/吊销/复制即用指引/无明文快捷创建，逻辑自 ProfileView 整体迁入）+ 工具面简介卡（16 工具按画布/剪辑器/素材生成分组摘要，写类档位提示）
• ProfileView 回归纯身份信息（净 -426 行）；与管理员「MCP 服务器」（平台作为 client，/admin/mcp）靠命名区分；i18n 中英；vue-tsc 0 错 / vitest 651 / build 过

MCP 接入指引入口（产品内露出）

• 个人中心「API 访问令牌」卡片新增**「接入指引」弹窗**：按当前环境自动推导端点 URL（dev→后端 8000 直连，vite 不代理 /mcp；生产→同源；配 VITE_API_BASE_URL→用之）+ 三方式接入标签页（配置文件 JSON / 命令行一键添加 claude mcp add --transport http / 发给 Agent 自主添加的自然语言指令）+ 档位说明与工具面提示
• 创建令牌成功态：「复制接入配置」（真实令牌嵌入 JSON）+ 「复制指令」（整段 Agent 自主添加指令，粘贴给 agent 即自行完成配置与验证）
• 文案 i18n 中英同步；vue-tsc 0 错 / vitest 651 / build 过；docs/mcp-server-guide.md 同步三方式

平台 MCP Server 批次 2+3（编辑器与生成全量工具面 · 文档收尾）

• 编辑器七工具：editor_list_projects / editor_create_project / editor_get_document / editor_put_document（revision 乐观锁）/ editor_render_submit（client_operation_id 幂等）/ editor_render_status / editor_rough_cut_analyze——全部直调既有 project_service/render_service/rough_cut_service，零业务逻辑复制；AI 粗剪编排从路由体抽到 rough_cut_service.analyze_asset（HTTP 路由与 MCP 工具共用，顺带补上临时目录 finally 清理）
• 素材/生成五工具：asset_list（统一素材库清单）/ model_list（image/video/chat）/ image_generate / video_generate（直调既有路由函数，敏感链路零复制：内容审核/积分扣减/任务轮询注册/生成落库全继承）/ generation_get（image+video 任务通用批量状态查询，内存实时态→DB 完成态回退双继承）
• 工具面达 16 个（画布 4 + 编辑器 7 + 素材/生成 5），写类工具 readonly 档统一拦截
• 文档：docs/mcp-server-guide.md（PAT 创建/client 配置/工具清单/画布与剪辑闭环示例/边界说明）；API.md 新增第 23 章（PAT 三端点 + /mcp 协议）；README 新增 Documentation 入口
• 测试：pytest 309（+6：编辑器文档闭环与乐观锁 409/素材清单筛选/模型清单/生成请求映射 text2video↔image2video/generation_get 三分支/e2e 编辑器闭环+空时间线 fail-closed+readonly 四写类拦截）；vitest 651 不变

平台 MCP Server 批次 1（外部 Agent/CLI 经 PAT 接入 · 画布四工具）

• PAT（个人访问令牌）：新 pat_tokens 表（sha256 哈希落库、明文仅创建响应返回一次、软删吊销即时生效）；GET/POST /api/auth/pat + DELETE /api/auth/pat/{id} 登录级端点；个人中心新增「API 访问令牌」卡片（清单/新建/一次性明文复制/吊销确认）；两档权限 readonly/full
• /mcp streamable HTTP 端点：mcp SDK 2.x MCPServer 进程内挂主应用（零新进程/零部署概念）；PAT 鉴权在 ASGI 包裹层（401 + WWW-Authenticate），身份经 ContextVar 传入工具；stateless + JSON 响应模式（CLI 场景免会话保持）；挂载点置于路由表末尾且 /mcp 加入 SPA fallback 保留前缀（精确路径 307 陷阱 + GET fallback 劫持双坑规避）；主应用 lifespan 手动启停 session manager（挂载子应用 lifespan 不传播）
• 画布四工具（v1 纯服务端资源型工具面首批）：canvas_list / canvas_create / canvas_get_overview（游标分页与前端 overviewPage 对齐，连线只带当页相关）/ canvas_apply_ops（add_panel/add_connection，按名引用批内新建节点）；写类工具 readonly 档统一拦截，归属校验复用 user-scoped 查询
• 画布工作区逻辑收敛：list/create/归属校验/ops 应用从 canvas_workspace.py 路由内联抽到 canvas_workspace_service（HTTP 路由与 MCP 网关共用同一实现）
• 测试：pytest 303（+15：PAT 三态/明文一次性/吊销即时失效、overview 分页与 TS 对齐、工具 impl 归属与全部失败 400、进程内 uvicorn e2e——鉴权 401/协议握手/工具闭环/readonly 拦截）；vitest 651（+3 api 层）+ vue-tsc 0 错 + build 过；dev 服务真实冒烟（401/tools/call 读到真实画布）
• 设计档 .zcode/plans/2026-10-11-mcp-server-design.md（纯服务端 16 工具路线：批次 2 编辑器 7+素材/生成 5、批次 3 文档+冒烟）

AI 辅助粗剪（静音剔除 / 场景切分 → 一键草稿时间线）

• 检测层（纯 Python 零 CLI 依赖）：新 rough_cut_service——PyAV 解码 + numpy，规避生产镜像无 ffmpeg 可执行的存量假设（scenedetect pyav 后端有上游 bug 故自写）：silence=音频帧 RMS 阈值游程（帧级起止秒推进，不假设固定帧长）→ 有声段补集；scenes=降采样灰度帧相邻平均绝对差超阈值切开 → 碎镜头并入前段；统一 segments 合同（钳位/去重叠/剔碎段——合并条件严格 <，相邻切点不吞并）
• 端点：POST /api/editor/assets/{asset_id}/analyze（登录级 router + 归属 404/非媒体 400/非法 mode 400/超时 503）；阻塞解码经 asyncio.to_thread + 120s 超时；素材本地缺失时走既有 resolve_asset_local_file 远程收口；requirements 显式声明 numpy/av（PyAV 库的 PyPI 包名是 av——首版误写 PyAV 导致 CI/Docker 全量装包失败，发版后已修正）
• 剪辑器 UI：时间线工具栏「AI 粗剪」→ 弹窗（选视频/音频素材 + 模式 + 阈值滑条）→ 分析 → 段列表预览（保留占比）→ 落当前工程（同类型轨尾顺序排布，每段一条 addClip 独立可撤销）；素材媒体种类取 media_type（type 是容器类型 material/clip——实测抓出的错）
• Agent 工具 editor_ai_rough_cut：分析 + 默认新建「AI 粗剪 · 素材名」工程或落指定工程，回复段数/保留比/工程 uid + 后续动作指引；TOOL_LABELS 完整性测试同步
• 测试：pytest 288（+10：真实编码视频端到端三段切分/中段静音剔除、norm 合并钳位边界、三态鉴权/归属/非媒体/非法 mode）；vitest 648（+4：segmentsToClips 顺序排布/offset/碎段过滤/毫秒圆整）+ vue-tsc 0 错 + build 过
• 浏览器实测：真实成片场景切分 3 段 UI 预览落时间线、agent 一轮对话完成分析+建工程+落段（工程冒烟后清理）；设计档 .zcode/plans/2026-10-10-ai-rough-cut-design.md（引擎选型实施偏差：scenedetect→自写，已记录）

画布体验打磨（视频悬停预览 + 读工具上下文预算）

• 视频节点悬停预览：悬停 350ms 静音播放前 3 秒（到点暂停复位、移出即停复位），不点开就能看内容；全画布单例（新预览自动停旧）；用户 pointerdown（含原生 controls）立即交还播放权且停预览后恢复原静音态（预览不遗留 muted，用户后续点播放有声）；拖拽画布/框选经过不触发；lib/canvas-video-preview 单例启停 + CanvasNode 接线
• canvas_get_overview 上下文预算：新增 cursor/page_size（默认 60，钳 10~100）游标分页——大画布不再静默截断 80 条，响应带 next_cursor 续读指引；连线只返回两端至少一端在当页的（原全量连线是大画布上下文炸弹，当页做 target 的连线其后各页自然出现）；小画布（≤page_size）单页全量行为等价；工具描述教模型续读；纯函数 overviewPage/parseOverviewCursor（游标越界=画布收缩回第一页重读）vitest 直测
• 测试：vitest 新增 10 例（overview 分页/相关连线/execute 端到端两页 + 预览单例互斥/静音态恢复/play 拒绝兜底），644 绿 + vue-tsc 0 错 + build 过；浏览器实测：悬停静音播放/3 秒停复位/移出复位/点击接管/预览后原生播放有声，agent 实读画布正确报节点
• 时间线音波波形/视频缩略图已随 P3 素材条批次（4585737）上线，本层收口

冒烟清账修复（同日提交 33a57b2）

• MCP 工具确认门被宿主短路吞掉：chat 宿主内核的 authorizeTool 对「自带工具组」一律放行（仅 generation 组走门），MCP 外部工具（mcp__ 前缀）从此不再过 confirm 档门——补上独立分支：MCP 工具在宿主模式下同样走 'mcp' 组策略（readonly 拒绝 / confirm 每工具首次过门 / auto 直通）；回归测试锁死三档语义（3 例）
• 子代理内 MCP 工具双门死锁：子内核此前直接继承父 extraTools 且不过门；补门后子内核本地门与父内核 execute 层门（gateChildTool 前移）互相等待造成死锁（确认卡批准后永不执行）。修复：子内核标记 isChildKernel 一律跳过本地门，且父 extraTools 经 runSubagent 与宿主工具一起过 gateChildTool（子内核内不存在免门工具）；回归测试锁死（1 例）
• 内核池被 pinia action 的 this 二相性拆裂：poolOf 以 store 对象身份作 WeakMap 键，而 pinia action 的 this 在「代理对象/原始对象」间不一致（fn.apply(this && this.$id === $id ? this : store)）——同一池被拆成两份，确认卡 confirmPending 按池查内核永远落空（门批准后工具永不执行，冒烟实测卡死）。改为按 store $id 分桶（模块级 Map），并提供测试专用复位 _resetKernelPoolsForTest（模块级池跨用例共享）
• MCP 工具清单缺失 per_user 服务器：GET /api/mcp/tools 聚合时未传 user_id，per_user 服务器（记忆库/本地文件系统）抛「必须携带用户身份」被静默跳过，Agent 从未拿到这两家的工具——user_id 贯通到网关会话层
• 记忆库删除/清空假成功：新版 server-memory（2026.8.31）把 delete_observations 入参键从 observations 改为 deletions，旧载荷被工具静默拒绝；且 memory_service 未检查 is_error，工具报错也返回「已删除」。修正键名 + is_error 升级为 502 可读错误；pytest 补 is_error 抛错用例（278 绿）
• memory 服务器数据落进 npx 缓存：官方目录的 MEMORY_FILE_PATH 为相对路径，新版 server-memory 将其解析到自身模块目录（npx 缓存内）而非进程 CWD，写入 ENOENT 且升级即丢——网关对 {user_id} 模板替换后的 env 路径值转绝对路径
• 生成页错误类目透出（收尾批次 2 遗留 UI）：QueueTask 增加 errorCategory，轮询/提交失败捕获后端 error_category；失败卡（ImageView/VideoView）与任务卡（TaskCard）显示类目文案（errors.category_*）；自动重试按类目 can_retry 语义阻断（审核拒绝/额度不足/参数无效等不再白烧 3 次重试，重试执行时清空类目）；vitest 新增 4 例（634 绿）

冒烟（自动化浏览器实测，MCP 桥/市场/用户记忆库/子代理四件 2026-09-13 存量待验清账）

• 用户记忆库全链路：种偏好 → 摘要端点 → Agent 对话注入（凭记忆精准答出画幅/题材偏好）→ Agent 按守则自主 add_observations 写入 → 能力胶囊（角标/列表/单删/清空）与后端双向同步
• MCP 用户侧：Agent 调用 filesystem list_allowed_directories，confirm 档确认卡弹出 → 批准 → 网关执行 → 结果回显；管理页连接测试回显工具清单
• MCP 市场：官方三卡已安装标记；自建源（静态 manifest HTTP 服务）添加 → 刷新（整源替换）→ 一键安装（market_slug 溯源入库）→ 清理
• 子代理：agent_delegate 委派 → 步骤行实时进度（round 更新）→ MCP 工具门在父内核一次过 → 子任务结论摘要回传主对话，无死锁

v0.0.10

安装运行

Docker（推荐）

docker run -d --name agnes-platform -p 8080:8000 -v agnes-data:/app/data ghcr.io/wingkysky/agnes-ai-platform:v0.0.10

免 Docker 便携包（Windows / macOS Apple Silicon）

从下方 Assets 下载对应平台的 zip，解压后双击 start-windows.bat（或 macOS 的 start-macos.command）。
macOS 首次运行先在终端执行 xattr -cr <解压目录> 去除下载标记；详见包内 README-PORTABLE.txt。

打开 http://localhost:8080 （便携包为 8000），按首启向导完成管理员密码与 AI 服务配置即可使用。
更多方式（docker compose / 公网服务器反代与 HTTPS / 数据备份）见 docs/deployment.md。

---

修复

• 对话自动总结标题失效：done 触发条件 !session.title 为恒假（后端建会话默认 title='新对话'），首轮对话后自动总结从未被触发（10-07 后会话标题全部停留默认值）——条件改为「标题为空或仍为默认值」时总结，且不覆盖用户手动改过的标题；回归测试锁死两个方向（626 例绿）

Agent 宿主统一 · 批次 2（退役对话页与画布面板，全局宿主唯一化）

• 退役 ChatView 对话页：删 /chat 路由与组件、导航「AI 对话」菜单项（BUILT_IN_MENUS/DEFAULT_MENU_CONFIG）、keep-alive 缓存清单、路由守卫两处 return '/chat' 兜底改 /images；无独有功能损失（多会话侧栏/输入链/画布会话跳转已全部在全局宿主）
• 退役 CanvasAgentPanel 画布面板：删组件与 CanvasView 挂载（theme 传递/几何记忆一并清理）；画布工具栏 Agent 按钮语义改为唤出全局宿主（激活态跟随 agentDrawerOpen）；画布会话跳转 query（?session=）改为唤出全局宿主并切换会话
• Agent 宿主唯一化达成：全局 AgentHostPanel 成为唯一 Agent 界面（Alt+A/顶栏/画布工具栏三入口），能力此前已全量对齐（确认卡/三档/风格卡/会话侧栏）
• 测试：vitest 625 + vue-tsc 零错 + build 过；浏览器冒烟（画布工具栏唤出/宿主悬浮画布无遮罩//chat 失效/导航清理）通过；净删约 1,850 行

Agent 宿主统一 · 批次 1（全局宿主双形态 AgentHostPanel）

• 自绘浮层双形态：新全局宿主 AgentHostPanel（替代 el-drawer 抽屉）——小态右停靠 360px ⇄ 展开态居中 86%×86%（头部拖动 + 拉伸把手 + 双击切换 + 位置记忆），无遮罩：小态点外部收起（页面仍可交互）、展开态 Esc/按钮退出；Alt+A/顶栏按钮/agentDrawerOpen 状态语义不变
• Agent 特有件全量内置（自画布面板迁入，此前仅面板拥有）：三档权限胶囊、阶段/工具确认卡（对话页与抽屉发起确认操作时确认卡无处显示的缺口就此补齐）、风格卡片（step-extra 领域渲染）、能力清单（MCP/记忆）、展开态会话侧栏 + 画布会话跳转规则
• 发送链增补：useChatComposer 支持文本类文档解析（md/pdf/docx 等拼进输入框，与画布面板多模态能力对齐）；附件选择器放宽 accept；store toStepView 补 result 透传（宿主领域插槽用）
• 主题解耦：宿主主题 token 可选注入，缺省映射 agnes 全局变量（自动跟随深浅色）；几何纯函数抽 agent-host-geom.ts（钳位/预设/记忆，极小视口收敛有测试锁）
• 测试：vitest 新增几何模块 7 例（625 绿）+ vue-tsc 零错 + build 过；浏览器冒烟通过（双形态/点外收起/Esc 分级/三档菜单/位置记忆）

Agent 一级公民 · 批次 3（过程可视化）

• 对话流执行态标识：工具卡步骤行补执行来源小标签（本页执行 / 页面实时执行 / 服务端执行）——工具 execute 经 toolContext.noteToolRoute(callId, route) 按 callId 回填步骤行（并发安全），三分派各处接入（画布深度工具/结构 op 桥优先与离线回退/剪辑器写工具三路）；标记随步骤落库，历史会话回看仍可见
• 页面侧「Agent 正在操作」徽标：画布/剪辑器页新增底部居中浮动胶囊——本页被跨页 Agent 操作时亮起（spinner + 用户可读操作文案），回执后淡出熄灭；startBridgeClient 新增 onActivity 活动回调（真实分发执行才触发，内部计数器处理并发，demoted 与白名单兜底不触发）；本页直执行不亮（操作本身在眼前）
• 完成回执结果摘要：工具卡完成态下方新增一行用户可读摘要（结果 message + 白名单产物 URL 可点击「打开」，如配音 audio_url/成片 final_url）；message 缺失时（如桥上原生 agent_apply_ops 回执）按结构化字段合成「已新建 N 个节点、新建 N 条连线、N 条失败」；纯函数 stepSummaryOf 从结果 JSON 提取（data 一层内 message、url/audio_url/video_url/final_url 白名单 + http(s) 协议校验防注入），对话页与全局抽屉共用
• 顺带修复：桥客户端 demoted 存量缺口——后端顶替消息前端从未处理，被顶替的旧标签页仍会继续执行操作（双执行风险），现正确置位失能
• 测试：vitest 新增 onActivity 亮灭/并发计数/demoted、执行来源回填、routeLabel/stepSummaryOf（含结构化合成）、toStepView 投影共 12 例（618 绿）+ vue-tsc 零错 + build 过；后端零改动

Agent 一级公民 · 批次 2（通用反向控制桥）

• WS 中继通道：目标页面（画布/剪辑器）经 WS /api/agent/relay/ws 注册为 (user, host, target_id) 执行者（JWT 查询参认证、25s 心跳保活、断线指数退避重连、画布切工作区自动重注册）；同 target 多 tab 后注册顶替（旧连接收 demoted 静默失能）；chat 内核的画布/剪辑器写·深度工具调用经 POST /api/agent/relay/call 下发页面用页内同一份工具实现执行并回执——跨页操作过程实时可见
• 执行路由三分（能力按可达性组装）：本页 scope 直执行（快路径）/ 跨页桥中继 / 离线回退。canvas 深度工具（13 项，剔 agent_delegate）bridge 态注入（本页 scope 或桥上有画布页，/targets 20s 刷新）；画布结构 op（add_panels/connect）桥优先、离线回退服务端 canvas_ops（op 词表 TS/Python 本就锁一致）；editor 两个写工具（apply_ops/generate_subtitles）本地加载直执行+即时合并（免等 5s 轮询）、桥上中继页面执行、离线维持既有 HTTP 实现
• 落画布解析链插层：_resolveCanvasTarget 在「本页激活」之后、偏好之前插入「桥上画布页」级——用户开着画布页时，agent 生成落图/结构写入优先落到看得见的画布
• 安全与可靠性：中继前逐请求归属校验（工作区/工程非本人 403）+ 工具白名单硬编码（授权不靠提示词）；超时/断连绝不自动重试（写操作可能已执行防双执行），只有「确定未执行」（offline）才回退；超时分级 agent_run_generation 600s 其余 60s
• 测试：pytest 新增 relay 服务（注册/顶替/换目标迁移/回执分发/超时断连）+ 路由（离线路由/白名单 403/归属 404+403/三态鉴权/targets）+ WS 协议（坏 token 4401/register/ping/未知回执）共 14 例（277 绿）；vitest 新增 relayCall 路由语义/桥客户端收发分发重连/白名单一致性/深度工具三分派 13 例（606 绿）+ vue-tsc 零错 + build 过；dev 代理补 ws: true 透传 WS 升级
• API.md 22 章；设计文档 .zcode/plans/2026-10-07-agent-first-class-citizen-design.md（批次 2 节）

Agent 一级公民 · 批次 1（全局 Agent 宿主）

• 全局侧边抽屉 AgentDrawer：任意页面经顶栏按钮或 Alt+A 快捷键唤出（输入框聚焦同样生效），右侧 440px 抽屉内组合共享聊天组件（消息列表/输入条/技能清单/模型胶囊/待发附件预览），与对话页绑定同一 chat store——会话、流式输出、确认卡全量同源；首开兜底 init()（幂等）+ 滚底；画布型会话选中后跳画布续聊（同对话页规则）；登录后才渲染（与顶栏 auth gate 一致）
• 工具可达性模型重构：scope 注册制——canvasToolsActive 布尔升级为 agentScopes 注册表（registerAgentScope/unregisterAgentScope，幂等覆盖 + 热更池内全部内核的工具与系统提示）；CanvasView 迁移为注册/注销（行为等价），EditorView 新注册 editor scope（元数据，为批次 2 反向控制桥路由预留；editor_* 工具保持常驻）；系统提示段改为按 host 静态映射（HOST_CONTEXT_SECTIONS），注册方无需感知提示词内容
• 发送链路收口：ChatView 的附件粘贴/URL 识别/发送/"/" 技能逻辑抽为共享组合式 useChatComposer（对话页与抽屉双消费），待发附件预览抽为共享组件 ChatPendingAttachments；顺带修复：对话页 keep-alive 下全局粘贴监听在其他页面仍活跃的存量问题（enabled 守卫互斥：抽屉开着只收抽屉的，画布页粘贴图片不再被隐形收集）
• 测试：vitest 新增 scope 注册/幂等/editor 元数据不注入画布工具 3 例（593 绿）+ vue-tsc 零错 + build 过；设计文档 .zcode/plans/2026-10-07-agent-first-class-citizen-design.md（批次 2/3 见设计档总纲）

v0.0.8

安装运行

Docker（推荐）

docker run -d --name agnes-platform -p 8080:8000 -v agnes-data:/app/data ghcr.io/wingkysky/agnes-ai-platform:v0.0.8

免 Docker 便携包（Windows / macOS Apple Silicon）

从下方 Assets 下载对应平台的 zip，解压后双击 start-windows.bat（或 macOS 的 start-macos.command）。
macOS 首次运行先在终端执行 xattr -cr <解压目录> 去除下载标记；详见包内 README-PORTABLE.txt。

打开 http://localhost:8080 （便携包为 8000），按首启向导完成管理员密码与 AI 服务配置即可使用。
更多方式（docker compose / 公网服务器反代与 HTTPS / 数据备份）见 docs/deployment.md。

---

Agent 上游空响应自动重试（韧性加固）

• provider 层空响应韧性：上游网关偶发把空补全替换为占位文本（[System: Empty response is not allowed]）以 200 原样返回，对话会把它当助手回复展示并落库（2026-10-07 实测）。agentStreamFn 现包装了一层探测重试——首段文本按占位串前缀探测（正常回复只缓冲 1 个文本增量，流式体验不变），整轮命中占位或纯空补全（无文本/工具/思考）即丢弃本轮自动重试一次；重试仍异常按原样透传（优雅降级），上游 error/用户中止不重试
• 测试：vitest 新增重试语义 5 例（占位重试/空补全重试/正常直通单次调用/末次降级透传/error 不重试），562 绿 + build 过

Agent 对话式剪辑（批次 3A：剪辑器接入全局对话）

• 剪辑器工具组 editor_* 挂载全局 Agent（7 工具，与 canvas_* 同先例常驻 chat 内核）：editor_list_projects（列工程）/ editor_get_overview（时间线全貌 + assetId→素材映射 + 素材库摘要）/ editor_create_project（新建，asset_ids 按序自动排草稿）/ editor_apply_ops（单一批量写入口，17 op 全量，全部校验通过才保存）/ editor_generate_subtitles（whisper 转写音频轨 → 全量替换字幕轨）/ editor_render（提交渲染 + 内部轮询至完成 + 回复成片链接）/ editor_get_render_status。对话即可完成「选素材 → 排时间线 → 加字幕 → 渲染成片 → 落画布」全链路
• 前端工具层复用命令表（方案 A）：工具层 GET 文档 → lib/editor-commands 17 op 纯函数 fail-closed 校验 → PUT 单文档（base_revision 乐观锁），与 UI 编辑零分叉、零后端命令逻辑复制；任一 op 校验失败整体不落盘（原子）；写前快照 snapshot_reason 仅工具层携带
• 时长探测补真值：addClip 视频/音频片段缺时长时经 probeMediaDuration（mediabunny → 元素三级探测，元素探测下沉 editor-media.probeElementDuration 共用）自动补真实时长——duration=0 草稿占位片段会被渲染 Plan 剔除，agent 不开编辑器直接渲染的坑由此关闭；图片默认 3s 静帧；轨道/位置/片段 id 缺省自动补全（默认轨 + 轨尾放置）
• 快照兜底（新表 editor_snapshots，create_all 自动建）：agent 保存触发写前快照（5 分钟窗口 + 内容哈希去重）；快照列表/全量端点（GET /snapshots[/{id}]）；还原=拉快照 data 走正常保存链路（无独立还原端点，仿画布快照）；对话内恢复（模型反向调工具）优先，快照为整盘兜底
• 编辑器页远端轻轮询：镜像画布页先例——空闲（无未保存改动/未在保存/未播放/页面可见/非渲染中）每 5s 查 GET /{uid}/revision 新端点，远端领先则静默合入并提示；有脏改动不拉，交给既有 409 冲突副本（数据零丢弃）
• 宿主 generation 组确认门：HostTool 增可选 group 字段，chat 宿主工具组默认放行（与既有行为一致），仅声明 generation 组的耗时工具（editor_render）走门——readonly 档拒绝、confirm 档每工具首次过门（语义同 MCP 门，policy.resolveHostGenerationGate 纯函数）、auto 直通
• 成片交付：渲染成功回复可点成片链接；place_on_canvas 缺省按「生成后自动放入画布」偏好，落画布复用 canvas ops（成片已自动入资产库）
• 测试：pytest 新增快照写前/去重/跨工程隔离/三态鉴权/revision 端点等 4 例（255 绿）；vitest 新增工具层目标解析/原子校验/时长探测/渲染轮询落画布/宿主门三档等 12 例（557 绿）+ vue-tsc 零错 + build 过
• 设计文档 .zcode/plans/2026-10-07-batch3a-editor-agent-editing-design.md（取代 2026-10-04 项目制时代版本）

字幕转写依赖收编

• faster-whisper 收编为正式依赖（原为可选依赖、镜像默认缺席，自动字幕能力形同虚设）：进 requirements.txt（Docker 镜像双架构 wheel 均有），Dockerfile 设 HF_HOME=/app/data/hf 让首次转写自动下载的 whisper 模型（small，约 460MB）落入数据卷、升级/重启不重拉；transcribe_service 运行时可用性检查保留作兜底
• PyAV 19 兼容垫片：PyAV 19 移除 av.open 的 metadata_errors 参数，faster-whisper 1.2.1 decode_audio 直接 TypeError（真实冒烟撞出；上游最新仍为 1.2.1 无修复版）。transcribe_service 按大版本号挂垫片剥掉该入参——PyAV 19 新默认语义（metadata 一律 UTF-8+surrogateescape 字节级无损读取）与旧参数意图等价；av 不钉版跟随最新，上游适配发版后垫片自然空转。pip-audit 全量零漏洞

画布 Agent compose 字段口径修复（真实链路撞出：配音→合成误触发视频生成被 429）

• compose 就绪校验容错读：上游视频节点 URL 生成回写在 content、引入素材落库在 url，agent compose 校验与拼接入参只认 content——「已带成片 URL 的节点」被误报"尚未生成完成"，agent 据此误触发视频生成撞 Agnes 免费额度 429（api_call_logs 实锤）。统一 videoUrlOf 三兜底（content/videoUrl/url，与画布层读取同口径），CanvasView 手动 compose 同款修复
• agent compose 补 TTS 音轨混入：compose API 本就支持 audios，agent 版此前只拼视频——上游 tts 节点音轨（节点直写 / 结果节点两种形态）现自动混入，配音→合成闭环才真正成立
• agent_run_generation 防误烧门：已带成片的视频节点再触发生成默认拒绝（要求显式 force: true 覆盖重生成），杜绝"对已有素材的节点盲跑生成"白烧额度；工具 schema 与描述同步
• 测试：vitest 新增 url 节点拼接 / TTS 音轨混入 / 防误烧门 force 放行 3 例（565 绿）+ build 过

画布 Agent 配音链路修复（真实链路撞出：tts 节点走了图片生成）

• agent_run_generation 增加 tts kind（根因修复）：kind 推断原本 video/compose 之外一律按 image——agent 对 tts 节点触发生成实际跑的是图片生成，图片 URL 被当"配音"写进节点并入素材库（type=image），最终合成无声。新增执行体镜像画布手动执行：文案取上游 text 节点（或节点 content.text）→ generateCanvasTts（voice/speed 透传）→ 结果写独立配音音频节点（result_panel_id 回写，与 compose 音轨采集/画布播放双对齐）；无文案来源明确报错
• 音色目录结构化透出：agent_get_models 扩展返回 voices（复用后端既有 GET /api/canvas/voices 内置音色库：旁白男/女声、年轻/成熟、童声、老年声，带性别与适用场景）——agent 可按角色/场景挑音色，而非盲选；两个工具描述同步写明 tts 节点契约（连线只建立数据流，必须执行 agent_run_generation(kind=tts) 才生成、voice/speed 字段），apply_ops 描述顺带清掉已退役的 config 类型
• 下游自愈：假音频根因断掉后，compose 音轨混入（上批次已补）拿到真音频，"配音→合成"闭环成立；不加资产导入类型校验（YAGNI，项目未上线）
• 测试：vitest 新增 tts 执行/结果节点写入/无文案报错/voices 透出 4 处断言（567 绿）+ build 过

配音入工程链路补全（第二轮回测撞出：浏览器旧 bundle + 两个真实缺口）

• ⚠️ 环境坑（非代码）：修复后的第一轮回测（会话 83）agent 仍说「没有 TTS 生成能力」并对 tts 节点跑出图片（api_call_logs 三笔 image_create）——vite 服务端已是新代码，但浏览器页面没刷新，agent 内核工具集是页面加载时的快照；改完前端工具必须强刷页面再测
• runTts 自动入素材库：editor_apply_ops 的 addClip 只认素材库 assetId，此前 agent 生成的配音从不入库、永远进不了剪辑工程（结构性缺口）；现在生成后自动 createAsset(media_type=audio) 返回 asset_id 并写入结果节点，工具结果直接给出「addClip 引用该 asset_id」的下一步指引
• editor_apply_ops 补全累积 + 类型守卫：同批次 [addTrack, addClip] 时补全逻辑看不到新轨、跳过 id 补全导致命令表 invalid_payload（真实撞过）；现在 addTrack/removeTrack 效果累积进工作轨表；音频轨只收 audio、视频轨只收 video/image——图片假配音在入轨前被拦（清晰报错替代 invalid_payload）
• compose 音轨采集收口：只认结果音频节点；tts 节点直写 content 的兜底移除——历史直写数据全是假配音图片 URL，纯藏污点
• 测试：vitest 新增批次 addTrack+addClip 补全 / 音轨类型守卫 / 配音入库断言（569 绿）+ build 过

宿主级 generate_tts 工具（第三轮回测撞出：TTS 能力只在画布宿主）

• 结构性缺口：TTS 只存在于画布宿主的 agent_run_generation(kind=tts)，而剪辑工程/对话页宿主只挂 editor_* + 通用生成——用户在工程语境里要配音，agent 如实回答「没有 TTS 工具」（会话 84/85 实锤，工具集里确实没有）
• generate_tts 进全局 CHAT_TOOLS：文本 → Edge TTS（免费）→ 自动入素材库 → 返回 asset_id + addClip 指引，任何宿主可用；描述内联 8 个内置音色 id（旁白男/女声、年轻/成熟、童声、老年声）按角色/场景选；tool-labels 补 agent.actGenTts 标签（zh/en）且 agent_run_generation 的 kind 文案同步识别 tts
• 测试：vitest 新增宿主级配音生成/入库/空文本 3 断言（571 绿）+ build 过

v0.0.7

安装运行

Docker（推荐）

docker run -d --name agnes-platform -p 8080:8000 -v agnes-data:/app/data ghcr.io/wingkysky/agnes-ai-platform:v0.0.7

免 Docker 便携包（Windows / macOS Apple Silicon）

从下方 Assets 下载对应平台的 zip，解压后双击 start-windows.bat（或 macOS 的 start-macos.command）。
macOS 首次运行先在终端执行 xattr -cr <解压目录> 去除下载标记；详见包内 README-PORTABLE.txt。

打开 http://localhost:8080 （便携包为 8000），按首启向导完成管理员密码与 AI 服务配置即可使用。
更多方式（docker compose / 公网服务器反代与 HTTPS / 数据备份）见 docs/deployment.md。

---

视频剪辑器：全新独立剪辑实体

• 剪辑工程独立实体：新表 editing_projects（文档快照 + revision 乐观锁 + 渲染状态/进度/快照/幂等列），端点 /api/editor/projects 增删改查、文档保存 409 冲突副本、whisper 字幕预览；前端新增侧边栏「视频剪辑」入口与作品详情工程区 → /editor/:uid 宿主页（节流自动保存、冲突副本、草稿占位时长补正）；whisper 转写抽 services/media/transcribe_service 公共域复用
• 命令状态机：14 op 可序列化命令表（addClip/moveClip/trimClip/splitClip/removeClip/detachAudio/setClipProperty、字幕 3 op、轨道 4 op）纯函数 fail-closed（未知 op / 非法 payload 抛错不改状态，可安全回放），200 层结构共享快照撤销，vitest 黄金对表 + 重放一致性锁死
• 多轨时间线：视频/音频/字幕三类轨道、多视频轨画中画；最近点吸附（Shift 临时禁用 + 开关记忆）+ 碰撞拒绝 + 占用轨放置三级回退（同类型空闲轨 → 自动开新轨）；片段分割 / 复制 / 音画分离 / 接缝转场菜单（叠化/溶解/擦除）/ 淡入淡出包络 / 静音徽标 / 片段与轨道右键菜单；标尺 px↔秒换算收口根治 0 点错位类问题
• 片段素材条：视频片段缩略图条（mediabunny 按源时间网格取帧）/ 图片位图铺满 / 音频音波条（全量解码分桶），asset 级 LRU 缓存 + 失败负缓存 + 串行解码队列让位预览解码；SRT 导入（解析后全量替换字幕轨，撤销可回）与导出（按时间排序下载 {工程名}.srt）
• 预览双路径 + 全音频统一调度：WebCodecs 可用走 canvas 合成（mediabunny 帧迭代解码），否则 DOM 媒体元素降级；视频自带音频与音频轨统一解 PCM 挂 WebAudio（样本级音量/淡变增益），音频时钟主控推进播放头；时长探测三级化（容器元数据 → 元素 → 兜底）；画中画预览点选拖动 / 四角等比缩放直接操作（松手入撤销栈）；画面容器查询等比适配（信箱式留白）
• 标准传输控制条：三区布局——左「当前/总时长」时间码 HH:MM:SS.mmm（等宽数字防抖）+ 中 7 键图标组（首帧/退1秒/上一帧/播放暂停/下一帧/进1秒/尾帧，lucide 通用图标）+ 右占位；动作语义与键盘快捷键完全同源，播放头到边界自动禁用对应按钮，tooltip 标注快捷键
• 渲染管线：渲染 Plan 纯函数 lowering（转场压缩 render_start 的 xfade 链、PIP overlay 窗口、变速 atempo 保音高、多轨混音统一重采样 48k 立体声、ASS 字幕硬烧）→ 单条 ffmpeg；提交时文档快照 + client_operation_id 幂等 + asyncio 后台任务 + 启动 stale 复位；成片落 uploads/editor 并入库资产库、来源画布回写；真实工程端到端渲染验证通过（与预期画面 SSIM 0.969~0.985）
• 布局对齐剪映：上排=素材墙+预览+属性、下排=全宽时间线，上排高度与面板宽度分隔条全可拖拽 + localStorage 持久化；素材库 16:9 自适应缩略图墙（行列随面板尺寸适应）+ 素材卡单击浮层临时预览（退出零成本恢复）
• 升级注意：works/editing_projects/api_call_logs 为新表启动自动建；canvas_workspaces.work_id、assets 四列（storage_key/thumb_url/source/work_id）、generations.error_category/error_message、model_definitions.cost_multiplier 为存量库需手动 ALTER（见模型文件升级注释）；历史成功生成进资产库需管理员在资产库页点「同步历史资产」（幂等，可重复执行）
• 测试：vitest 530 绿 + vue-tsc 零错 + build 过；pytest 252 绿；浏览器多轮实测拖拽缩放/预览/渲染/落库

资产统一：单一素材池 + 历史任务视图（融合子批次 2a）

• 统一资产单池：assets 表升级为统一身份（数字 id + 懒迁移），存储收口层治理死链；生成结果全量自动入库（任务上下文透出作品归属）；/api/assets 用户级路由（媒体类型/来源/作品/关键词服务端筛选 + 分页 + 批量分享/删除/zip 下载 + PATCH 字段编辑）
• 单池入口统一：资产库页两区合并单池（卡片预览/用于生成/分享/编辑/删除，来源与作品标签）；画布素材库面板同源切 /api/assets（生成历史/我的素材双 tab + 本作品/全部范围切换 + 检索强化）；历史页重定位为任务视图（行式列表 + 状态筛选 + 复制提示词/查看资产/存为资产兜底/后期处理/删除）
• 存量补课：管理员「同步历史资产」按钮 + 幂等 backfill 端点（历史成功生成批量入库，写库失败单条跳过不阻塞）

剪辑器轨道交互升级：拖拽换轨 + 轨道选中 + 轨头四开关

• 轨道多开状态：轨道旗标由单值 flag（hidden/locked/muted 三选一）改为 flags 四开布尔（hidden/locked/muted/solo 可并存），命令 setTrackFlag 改为 setTrackFlags 部分合并语义；后端骨架校验同步改为 flags 字典白名单校验
• 轨头图标按钮：轨头左侧重做——拖拽手柄 + 类型名 + 删除钮一行，状态图标一行（隐藏 Eye/EyeOff、原声 Volume2/VolumeX、独奏 Headphones、锁定 Lock/LockOpen，lucide 图标按类型给开关集：音频无隐藏、字幕无声音开关），激活态分色（隐藏灰/静音红/独奏黄/锁定主题色）+ 悬停 tooltip；原两个 checkbox 退役
• 轨道拖拽换轨：轨头手柄拖拽在同类型轨内重排（新命令 moveTrack，order 重编号保持稠密、原位放置结构共享零入栈），拖动中显示主色插入指示线、被拖行半透明；后端渲染 Plan 同类型轨序即层叠序不受影响
• 轨道选中：点轨头/轨道空白处选中轨道（轨头主题色高亮 + 左侧色条 + lane 淡底），与片段选中互斥；Delete/Backspace 删除选中空轨（非空轨 toast 拒绝），Escape 清除选中
• 独奏监听语义：存在独奏轨时预览只出独奏轨的声音（音频引擎 audibleSpans 过滤、DOM 路径 el.muted 同步），不影响画面、不随成片导出（对齐常规剪辑软件的 solo 惯例）
• 渲染语义缺口修复：后端渲染 Plan 原先完全不读轨道开关——现 hidden 轨整轨剔除（画面/自带音频/字幕全不进成片）、muted 轨只剔声音保留画面、DOM 预览字幕层补上隐藏轨过滤；成片与预览语义对齐
• 测试：vitest 新增 moveTrack 重排/钳位/结构共享、setTrackFlags 合并与非法 payload、独奏过滤等用例（514 绿）+ vue-tsc 零错 + build 过；pytest 新增 flags 骨架校验、hidden/muted/solo 渲染 Plan 语义用例（252 绿）；浏览器实测轨头图标/选中/拖拽换位/删除保护/自动落库

作品容器 + 媒体域独立 + 画布轻成片（融合子批次 1）

• 作品容器：新表 works（一部剧一条作品，聚合集画布/剪辑工程/实体库），端点 /api/works 增删改查（用户自助，非本人 403 / 不存在 404）；canvas_workspaces 新增 work_id 列（存量库需手动 ALTER，见模型文件注释），画布创建可挂靠作品（非本人作品 403）、列表可按作品筛选，删除作品自动解绑名下画布为自由画布；前端新增侧边栏「作品」入口 → 列表页（/works，卡片 + 新建/删除）→ 详情页（/works/{id}，集画布管理：新建一集 / 进入画布 / 删除）
• 媒体域独立：TTS provider（内置音色库 + Edge TTS 调用）、字幕格式（SRT/ASS 构建 + 默认样式）、BGM 曲库从 services/project/ 抽至 services/media/ 公共域，画布对项目域的反向依赖归位；media_compose 新增 concat_with_xfade 转场链公共实现
• 画布轻成片增强：compose 节点新增「转场」（叠化/溶解/擦除/推入，非 none 多段走 xfade 重编码链）、「画幅」（16:9/9:16/1:1）、「背景音乐」三组参数 UI；多段配音按视频段顺序拼接成单轨后与 BGM 混音（audios 多段，旧单段 audio_url 兼容保留）；TTS 音色下拉接入音色库（GET /api/canvas/voices）；字幕节点「生成提示词」输入接通后端（按风格/节奏等要求拆分）；BGM 曲库端点 GET /api/canvas/bgms
• 测试：pytest 新增作品端点 401/403/200 三态、画布挂靠作品归属校验、删除解绑用例；全量回归 206 过；vitest 414 绿 + vue-tsc 零错 + build 过

生成错误归类 + 上游调用记账 + 模型倍率定价（可靠性三件套）

• 生成错误归类：新增 error_taxonomy 13 类目唯一出处（每类绑定「能否手动重试」语义；submission_uncertain 提交结果不确定，禁止原地重试防重复扣费）；上游错误统一包装为携带状态码/请求 ID 的结构化异常后归类；任务失败落库 generations.error_category/error_message（存量库需手动 ALTER，见模型文件升级注释），任务状态与历史接口透出，提交失败响应携带 category；GET /api/config 下发 error_categories 语义表；前端生成页提交失败展示类目文案（可重试类保持原样），画布节点与批量创作表行级重试在不可重试类目上拦截提示，中英文案齐备
• 上游调用记账：新表 api_call_logs 每次上游调用一行（渠道/模型/类型/端点/状态/类目/耗时/tokens），由上游调用客户端出口 best-effort 写入，写库失败不影响生成主流程；管理员端点 GET /api/admin/api-calls（分页筛选）+ /summary（按日×类目×渠道×模型聚合）；/admin/logs 新增第三 Tab「上游调用」：聚合卡 + 渠道/模型全量概览双汇总表（按调用量排序，点击模型行直接筛选下方明细列表）+ 明细筛选分页
• 模型倍率定价：model_definitions.cost_multiplier（默认 1.0；存量库需手动 ALTER），实扣积分 = 平台基准价 × 倍率（图片按张/视频按秒规则不变，模型缺失按 1.0，倍率下限 0.1），预估接口与实扣同一计价函数保证一致，退款按实扣原额退；管理端模型编辑「积分倍率」输入保存即生效，模型列表勾选多行「批量设倍率」一次请求批量生效（PUT /api/models/batch-cost-multiplier，单个编辑框保留微调）
• 测试：pytest 新增错误类目表驱动/UpstreamError/失败归因落库/倍率计价/批量倍率端点与调用记账端点鉴权三态等用例全绿；vitest 错误类目渲染与重试闸门前端回归全绿

批量创作表节点 + 提示词优化器 + 模型能力合同收敛

• 画布批量创作表节点：新增 table 类型节点，「N 行 × M 参考图列」矩阵批量生图；参考图入槽三通道（单元格点选文件 / 拖入图片文件 / 列头句柄拖线到图片节点按列自动填充并建血缘连线）；操作预设一键套用（批量换装 2 列 / 创意生图 3 列，含中文提示词模板）；全局提示词与行提示词自动拼接；提交前逐行校验（不合格行红框拦截、其余照常提交），每行独立图片任务、失败单行重试，行状态徽标实时回写；列数按所选模型的参考图上限自动收敛
• 提示词优化器：新增 POST /api/prompts/optimize，五种模式（扩展想法 / 精修提示词 / 强化风格 / 适配模型 / 结合参考素材）结构化返回正向+负向提示词、关键变化、假设声明与最多 2 个备选版本；「适配模型」内置主流模型提示词方言规则表；解析失败自动重试一次。入口四处：图片/视频生成页、画布节点 composer、批量创作表行内；五模式各自独立面板——首次切换自动生成、结果与编辑按面板缓存、来回切换即看，应用时回填对应输入框（视频页正/负向双回填）；输出语言钉死（中文输入全字段简体中文）
• 模型能力合同层：新增 capability_service 统一解析模型生成能力，三级优先（管理端显式 gen_params 逐键覆盖 > 按模型名自动画像 > 默认兜底），散落的模型特例判断收口到单一入口；前端统一经 getModelGenParams 消费；新模型接入继续零业务代码（类型/能力/约束均可管理端显式覆盖）

v0.0.6

安装运行

Docker（推荐）

docker run -d --name agnes-platform -p 8080:8000 -v agnes-data:/app/data ghcr.io/wingkysky/agnes-ai-platform:v0.0.6

免 Docker 便携包（Windows / macOS Apple Silicon）

从下方 Assets 下载对应平台的 zip，解压后双击 start-windows.bat（或 macOS 的 start-macos.command）。
macOS 首次运行先在终端执行 xattr -cr <解压目录> 去除下载标记；详见包内 README-PORTABLE.txt。

打开 http://localhost:8080 （便携包为 8000），按首启向导完成管理员密码与 AI 服务配置即可使用。
更多方式（docker compose / 公网服务器反代与 HTTPS / 数据备份）见 docs/deployment.md。

---

首启引导重设计：免登录创建管理员 + 模型配置闭环

• 免登录创建管理员：不再预置默认 admin/admin123 账号——实例无管理员时打开任意页面直接进入「初始化管理员」向导（自选用户名+密码，创建即登录），全程无需知道/手输默认凭据、无需再"改默认密码"；新增免登录端点 GET/POST /api/setup/bootstrap（仅管理员数为 0 时可创建，409 拒绝重复初始化，窗口同时是管理员被全删后的恢复路径；竞态下 409 自动转登录页）
• 模型配置闭环：向导 Provider 步提交后自动调用模型同步并展示「已同步 N 个模型（图片/视频/对话）」——修复旧向导只建 Provider 不拉模型、生成页无模型可用的断链；同步失败展示后端透出的中文错误并支持「重试同步」（Provider 已建，仅重拉）；接入方式收敛为两张预设卡（Agnes AI 官方默认 / OpenAI 协议兼容），其余厂商适配器仍在管理后台完整选择器中
• 未配置兜底指引：跳过或同步失败时完成页明确警示"生成功能不可用"，图片/视频生成页在模型列表为空时显示引导横幅（管理员可一键跳转模型配置页）
• 自动化部署兼容：ADMIN_USERNAME + ADMIN_PASSWORD 同时显式设置时仍走超管种子（不再强制改密），向导自动跳过创建步骤；.env.example 补 ADMIN_* 变量说明
• 移除 must_change_password：新流程无"默认密码"概念，字段与强制改密拦截整体移除（存量库升级需手动 ALTER TABLE users DROP COLUMN must_change_password，见模型文件升级注释）
• 依赖安全：PyJWT 下限抬至 2.15.0（2.13 存在多项 PYSEC 告警，JWT 为令牌签发核心；anyio/urllib3 随解析自动升级），pip-audit 复扫清零
• 测试：pytest 首启初始化 18 例（bootstrap 三态/种子条件化）+ vitest setup store 12 例（bootstrap 判定/缓存/重置）全绿 + 临时库 uvicorn 三环境冒烟；README/API.md 同步更新；Mimosa 深度复扫 35 条 business-logic 候选逐条人工核对全为已知盲区误报（new=0，结论入基线台账）

v0.0.5

安装运行

Docker（推荐）

docker run -d --name agnes-platform -p 8080:8000 -v agnes-data:/app/data ghcr.io/wingkysky/agnes-ai-platform:v0.0.5

免 Docker 便携包（Windows / macOS Apple Silicon）

从下方 Assets 下载对应平台的 zip，解压后双击 start-windows.bat（或 macOS 的 start-macos.command）。
macOS 首次运行先在终端执行 xattr -cr <解压目录> 去除下载标记；详见包内 README-PORTABLE.txt。

打开 http://localhost:8080 （便携包为 8000），按首启向导完成管理员密码与 AI 服务配置即可使用。
更多方式（docker compose / 公网服务器反代与 HTTPS / 数据备份）见 docs/deployment.md。

---

便携包启动器端口自动顺延

• start-macos.command / start-windows.bat 启动前探测 8000 是否被占（典型场景：开发服务在跑）——被占则自动顺延到下一个空闲端口，终端打印实际端口、浏览器打开正确地址；修复「包服务绑定 8000 失败静默退出、浏览器仍打开 8000 命中开发服务，看到的是开发环境数据与登录态」的问题（v0.0.3~0.0.4 受影响）；不同端口 = 不同 origin，数据与登录态天然隔离