The open-source full-stack studio for Opus 5.5 motion video. Reverse engineering for any video. Code video with HTML: recreate, edit and render. BYOA + BYOK · Motion.md · Images, Video, Music & Voice.
TypeScript agent-skillsagentic-aiai-agentsai-videobyokclaude-codecodexdeepseek-harnessdsh-plugingenerative-ailocal-firstmcpmotionmotion-graphicsmultimodalopenmotionreverse-engineeringvideo-editingvideo-generationworkbuddy
docs(motion): record upstream sync and streamline contributor guidance (#176)
Tom Huangff26be350e5d
diff --git a/AGENTS.md b/AGENTS.mdindex dc421ec4..2dc3ff03 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -4,23 +4,23 @@ OpenMotion is a standalone npm application at the repository root. Run commandsBefore publishing a branch, run `npm ci`, `npm run check`, `npm run typecheck:studio`, `npm run build:studio`, affected deterministic tests and the applicable packaging/installation checks. Browser tests on shared machines use the existing browser-lock lanes. Distinguish CI, target-machine installation, model creation and human content acceptance. This feature migration must not merge or publish packages unless separately authorized.-## 持续维护产品文档+## Repository collaboration instructions-`docs/` 是仓库内持续维护的产品知识库。所有贡献者与 Agent 都应在交付需求时同步沉淀产品理解;代码、聊天记录或 PR 描述不能代替产品文档。+Keep persistent user instructions for repository work in this file, and keep `CLAUDE.md` aligned with this shared source so every Agent follows the same rules.-开始仓库需求前,先读 [文档入口与维护流程](docs/README.md)、[产品架构](docs/product/architecture.md) 和该需求涉及的专题。公开文档仅维护使用说明、技术契约和可复现验证。+1. All commit messages must be in English, including both the subject and body, as well as merge and revert messages.+2. All repository collaboration content you create or update must be in English: issue and pull request titles and descriptions, comments, review summaries, discussions, and release notes. This applies even when the user's request is in another language.+3. Before committing or submitting repository content, verify that it follows these English-language requirements.-每次需求交付(功能、体验优化、修复、重构、接入或文档建设)都必须:+## Product architecture review-1. 明确用户问题、服务人群、预期结果和验收方式。复用已有需求信息;缺失内容先标记假设,不编造客户、访谈、市场规模或收入数据。-2. 在同一提交或 PR 中更新受影响的产品架构、画像、商业化或工程专题文档。用户可见入口、行为、配置或限制变化时同步更新 README。-3. 在 [需求与决策记录](docs/product/changes.md) 新增或补充对应需求条目,记录问题、选择、影响、验证证据和后续待验证事项。对画像或商业化没有影响时,在该条目写明原因,无需改写无关章节。-4. 将“当前已实现”“已确认方向”“待验证假设”“候选方案”分开。商业化设想不写成已上线能力;界面截图、热度快照和技术测试不自动证明用户需求、留存或付费意愿。-5. 检查文档链接、源码路径和口径;替换过时结论时保留决策缘由与历史入口。PR 或交付说明给出更新的文档链接与实际验证结果。+For every change, review the entire [product architecture](docs/product/architecture.md) and decide whether it still accurately describes the product. Consider positioning, core user flows, module responsibilities, dependencies, data and API boundaries, implemented capabilities, and current limitations together.-每个需求 PR 或直接提交都应包含对应的文档变更。小需求可直接补充现有专题与一条需求记录;跨模块需求可使用 [需求文档模板](docs/templates/requirement.md)。按实际影响更新,不为凑文档创建空文件,也不把同一规则复制为多份互相矛盾的说明。现有授权范围内的文档维护随实现一起完成。+Update the architecture only when the change makes it incomplete, inaccurate, or internally inconsistent. Keep the document coherent as a whole, and adjust related usage or technical documentation only where needed for consistency. If the architecture remains accurate, leave it unchanged; documentation edits and per-change records are not required for every commit or PR.-`AGENTS.md` 是所有 Agent 的共同准则,`CLAUDE.md` 引用同一套规则。准则变化时同步两者的入口。可分发插件也应包含两份入口和 `docs/`。+Use the [documentation index](docs/README.md) for related topics. Distinguish implemented behavior, confirmed direction, hypotheses, and candidate designs. Preserve useful rationale and verification boundaries without inventing evidence. Check links and source references when editing documentation.++`AGENTS.md` is the shared source for all Agents; keep the `CLAUDE.md` entry aligned when these guidelines change. Distributable plugins include both entries and the approved documentation.## Video production entry pointsdiff --git a/CLAUDE.md b/CLAUDE.mdindex c10371ea..03d1fec2 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -2,13 +2,13 @@开始本仓库的工作前,读取并遵循 [AGENTS.md](AGENTS.md)。它是与 Codex 及其他 Agent 共用的仓库准则。-产品需求必须同步维护 [docs/](docs/README.md):+## Repository collaboration instructions-- 开始前读取 [产品架构](docs/product/architecture.md) 和相关专题。-- 每次需求交付在同一提交或 PR 中更新受影响文档,并补充 [需求与决策记录](docs/product/changes.md)。用户可见行为变化时更新 README。-- 说明服务谁、解决什么问题、为何这样做、如何验证,以及对画像和商业化的影响;无影响时记录原因。-- 明确区分现状、已确认方向、假设与候选方案,保留证据和未验证事项。不要把产品知识只留在聊天或 PR 中。-- 交付前检查文档链接和口径,列出实际更新的文档与验证结果。详细流程与 [需求模板](docs/templates/requirement.md) 以文档入口为准。+Follow the [shared repository collaboration instructions](AGENTS.md#repository-collaboration-instructions). All commit messages, including subjects and bodies, must be in English. All issue and pull request titles and descriptions, comments, review summaries, discussions, and release notes you create or update must also be in English, regardless of the user's request language. Verify this before committing or submitting. Keep persistent repository instructions in `AGENTS.md` and keep this entry aligned.++## Product documentation++Follow the [shared product architecture review guidance](AGENTS.md#product-architecture-review). For every change, review the entire [product architecture](docs/product/architecture.md) and assess whether it remains accurate and consistent. Update it only when needed, keeping related sections and supporting docs consistent. If it remains accurate, leave it unchanged; there is no automatic documentation update or mandatory per-change record. Use the [documentation index](docs/README.md) for related topics and verify links when editing.制作影片时按 AGENTS.md 根据本轮意图直接选择入口;原创/局部动作与声音重新设计、创作审片由 director 承接,既定决定下的工程操作由 production 承接。专业入口复用共享上下文,无需前置 production。模板路线已接入 motion-template-to-video,motion-recreate 已接入实际复刻流程及其自带的参考、测量脚本,边界与 MCP 调用见 [Skill 路由](docs/skills.md)。共享工程和成片验证继续适用。仓库代码与文档维护不需要启动影片制作问卷。diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex c0a3a787..27b468af 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -6,7 +6,7 @@ Work from the repository root; read [AGENTS.md](AGENTS.md) and the [architectureBefore opening a PR, run `npm run check`, `npm run typecheck:studio`, `npm run build:studio` and focused deterministic tests for the changed boundary. Studio unit tests use `npm run test:studio`. Use the shared browser-lock wrapper on shared machines; model creation and visual acceptance require separate evidence. Do not overwrite real user data or host configuration to test an installer.-Keep PRs focused and describe the user-visible behavior and actual validation. Open an issue first for substantial changes. Update affected public docs in the same PR. Preserve existing Git history and push follow-up commits during review; do not force-push a shared branch.+Keep PRs focused and describe the user-visible behavior and actual validation. Open an issue first for substantial changes. Review the entire product architecture for each change and update it only when needed, following the [shared guidance](AGENTS.md#product-architecture-review); documentation edits are not required in every PR. Preserve existing Git history and push follow-up commits during review; do not force-push a shared branch.Only deliberately public documentation belongs here. Do not commit credentials, internal links, private plans, workstation paths or user projects. Distribution uses the positive list in `scripts/distribution.ts`; newly shipped files require an explicit decision. Preserve all upstream attribution and license notices. Do not add telemetry or publish a package without a separate decision.diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.mdindex ca7f94bc..e5ad48cf 100644--- a/CONTRIBUTING.zh-CN.md+++ b/CONTRIBUTING.zh-CN.md@@ -6,7 +6,7 @@提交 PR 前运行 `npm run check`、`npm run typecheck:studio`、`npm run build:studio` 与受影响的确定性测试。Studio 单测用 `npm run test:studio`。共享机器的浏览器验收沿用 browser-lock;模型创作与人工视觉验收单独记录,不覆盖真实工程或日常宿主配置。-PR 聚焦一个问题,说明实际变化和验证结果,较大改动先建 issue。同批更新受影响的公开文档。保留历史,用后续提交响应评审,不强推共享分支。+PR 聚焦一个问题,说明实际变化和验证结果,较大改动先建 issue。每次变更整体审视产品架构,按[共同准则](AGENTS.md#product-architecture-review)判断是否需要更新,不要求每个 PR 修改文档。保留历史,用后续提交响应评审,不强推共享分支。不提交凭据、内部链接、私有计划、机器路径或用户工程。打包只使用 `scripts/distribution.ts` 的正向清单;新增分发文件需明确批准。保留上游许可与署名,不自行增加遥测或发布包。diff --git a/docs/README.md b/docs/README.mdindex ef769248..dff24ec3 100644--- a/docs/README.md+++ b/docs/README.md@@ -1,6 +1,6 @@# Motion 文档-这里维护公开的使用说明、技术契约和可复现检查。开始开发前阅读 [产品架构](product/architecture.md) 与相关专题;变更时同步更新对应说明、README 和 [公开变更记录](product/changes.md)。不将个人环境、客户资料、内部讨论或商业研究写入公开文档。+这里维护公开的使用说明、技术契约和可复现检查。每次变更时整体审视 [产品架构](product/architecture.md),判断定位、核心流程、模块职责、依赖、数据与接口边界、当前能力和限制是否仍准确一致;仅在需要时更新,并按需调整相关说明。架构仍准确时保持文档不变,不要求每次提交或 PR 修改文档或新增需求记录。不将个人环境、客户资料、内部讨论或商业研究写入公开文档。## 阅读入口@@ -20,7 +20,6 @@- [motion-extension-scope.md](motion-extension-scope.md)- [npm-installation.md](npm-installation.md)- [product/architecture.md](product/architecture.md)-- [product/changes.md](product/changes.md)- [product/media-generation-design.md](product/media-generation-design.md)- [project-workspace.md](project-workspace.md)- [repository-migration.md](repository-migration.md)diff --git a/docs/mcp-phase1-tools.md b/docs/mcp-phase1-tools.mdindex 2f2f7b3c..21c198cc 100644--- a/docs/mcp-phase1-tools.md+++ b/docs/mcp-phase1-tools.md@@ -106,7 +106,7 @@ action=record_review 要求 projectId/requestId/jobId/review;只能对本项已通过本地一期业务检查和真实运行闭环:创建/分页/请求去重、保存与 UTF-8 读取、v5→v3→v6、跨重启保留历史/媒体、失败与中断恢复保护、排队取消;真实 Studio 的原生历史、MCP 绑定与保存、运行中取消、320×180/10fps MP4 的自动技术验证。-合入最新主干后,后端完整回归124项通过;另含真实多MCP连接的项目隔离、并发冲突与断开续用;Studio类型检查通过,单元/DOM测试8098项通过,保留原有1个跳过文件/16项todo;check和后端类型检查通过。实际ZIP从独立目录启动、首次安装锁定运行时后,9项Tool均实际调用通过,含音轨MP4自动校验、运动帧变化、版本恢复、取消与历史结果读取。四宿主薄适配器已导出;安装配置的发现检查与完整模型体验分别验收。记录见 [变更记录](product/changes.md)。独立播放器听看、四宿主端到端模型任务、Windows 实机、CI、发布与业务验收均未据此宣布通过。+合入最新主干后,后端完整回归124项通过;另含真实多MCP连接的项目隔离、并发冲突与断开续用;Studio类型检查通过,单元/DOM测试8098项通过,保留原有1个跳过文件/16项todo;check和后端类型检查通过。实际ZIP从独立目录启动、首次安装锁定运行时后,9项Tool均实际调用通过,含音轨MP4自动校验、运动帧变化、版本恢复、取消与历史结果读取。四宿主薄适配器已导出;安装配置的发现检查与完整模型体验分别验收。上述历史结果应按对应提交解读。独立播放器听看、四宿主端到端模型任务、Windows 实机、CI、发布与业务验收均未据此宣布通过。## 源码定位与验证记录diff --git a/docs/model-gateway.md b/docs/model-gateway.mdindex e059eb83..bab33a3f 100644--- a/docs/model-gateway.md+++ b/docs/model-gateway.md@@ -1,6 +1,6 @@# Model Router / Gateway-更新:2026-11-04。关联需求:[变更记录](product/changes.md)。+更新:2026-11-04。本文维护当前能力、接口和运行限制。跨模块的产品目标、对象归属、D1–D11 设计取舍、时间轴交互和扩展准入条件见 [素材生成设计与架构决策](product/media-generation-design.md),整体分层见 [产品架构](product/architecture.md#职责分层与依赖方向)。diff --git a/docs/npm-installation.md b/docs/npm-installation.mdindex 33f105e6..ae85cd81 100644--- a/docs/npm-installation.md+++ b/docs/npm-installation.md@@ -73,6 +73,6 @@ npm 可以通过带 `os/cpu` 的平台包及安装脚本自动配置原生程序隔离设置四家各自的配置根,并通过 `--home`、`--skills-dir`、`--data-dir` 指定全新目录;不把测试安装进日常配置。验收最终 npm tgz、Skills 发现、宿主实际解析的 MCP 启动配置、首次原生下载、第二次缓存复用、Studio 以及一秒有声音和运动的导出。定向自动测试覆盖清单/路径校验、校验失败、锁、配置冲突、重复安装和失败回退。-安装成功、MCP 连接和技术导出不代替模型创作回合、独立播放器或其他操作系统实测。当前一期契约见 [9 Tool 说明](mcp-phase1-tools.md)。本轮按最新主干重新验证,实际结果记在 [需求记录](product/changes.md) 及交付日志;不把旧 28 Tool/旧四入口原型的验证当作当前一期验收。+安装成功、MCP 连接和技术导出不代替模型创作回合、独立播放器或其他操作系统实测。当前一期契约见 [9 Tool 说明](mcp-phase1-tools.md)。实际验证结果以对应提交的 PR 或交付日志为准;不把旧 28 Tool/旧四入口原型的验证当作当前一期验收。WorkBuddy 桌面对话/模型调用、Windows 实机和公网冷下载须分别验收。本渠道不改变系统支持范围,不新增发布、自动升级、账号或计费能力。diff --git a/docs/product/architecture.md b/docs/product/architecture.mdindex a1b0662d..ea22efe3 100644--- a/docs/product/architecture.md+++ b/docs/product/architecture.md@@ -6,7 +6,7 @@## 产品定位与目标-OpenDesign 的底层组织是通用 Agent 会话:会话拥有模式、需求与多个 Artifact,模式选择模板目录和 skill,Artifact Viewer 负责打开可编辑产物。完整与嵌入视图使用同一产物;`embed=1` 可只显示 Viewer,供 Codex 等宿主打开。当前一期只有 Motion 模式,制作与导出仍使用原生 Hyperframes。其他模式是已确认方向,未作为可执行模式上线。此前 OpenMotion 的品牌与「会话等于工程」决策由 [变更记录](changes.md) 取代。+OpenDesign 的底层组织是通用 Agent 会话:会话拥有模式、需求与多个 Artifact,模式选择模板目录和 skill,Artifact Viewer 负责打开可编辑产物。完整与嵌入视图使用同一产物;`embed=1` 可只显示 Viewer,供 Codex 等宿主打开。当前一期只有 Motion 模式,制作与导出仍使用原生 Hyperframes。其他模式是已确认方向,未作为可执行模式上线。会话的 Agent 推理与工具编排由用户已有的 MCP 客户端执行;本地网页保存需求、接收调用方写回的真实回复、管理产物与继续编辑,不包含内置聊天 Agent 运行器。自有 Agent、Codex 和其他 MCP 客户端共用先创建会话、后生成产物的生命周期。@@ -27,7 +27,7 @@ Model Gateway 是共用的素材生成服务,可由 Motion Viewer 或 MCP 调[Motion MD](../motion-md.md) 是本轮加入的 **v0.1 格式提案**,描述来源、品牌、叙事、节奏、运动、素材、可修改项与验收信息。当前仅供用户显式交给 Agent 作为创作上下文;没有自动发现、解析、校验或注册接口。它不改变 HTML/CSS/JS 原生工程,也不替换现有 motion-video-to-template 的单份 `TEMPLATE.md` 交付约定。-[Motion 资源索引](../collections/README.zh-CN.md) 已可使用,区分可观看参考与可编辑模板;OpenDesign 官网展示案例,公开的品牌/榜单专题集合站仍在规划。Motion Benchmark/Arena 为待讨论规划,无已发布榜单、排名或确定日期。详见[公开变更记录](changes.md)。+[Motion 资源索引](../collections/README.zh-CN.md) 已可使用,区分可观看参考与可编辑模板;OpenDesign 官网展示案例,公开的品牌/榜单专题集合站仍在规划。Motion Benchmark/Arena 为待讨论规划,无已发布榜单、排名或确定日期。## 目标场景与交付@@ -185,7 +185,7 @@ flowchart LR已确认方向是继续支持多 Agent 接入、可编辑工程与一个工作区内的发现/制作闭环。-任何演进都需要说明新增的人群和价值、影响的数据/API/工程格式、成本与可靠性变化,以及与现有工作流的兼容方式。重要选择和被替代的方案进入 [需求与决策记录](changes.md)。+每次变更整体审视本文,判断产品定位、核心流程、模块职责、依赖、数据与接口边界、当前能力和限制是否仍准确一致。确有变化时按需修订相关章节,保持全文一致并保留必要的决策理由;架构仍准确时无需修改文档或新增变更记录。通用会话 API、模式工厂、Viewer 注册与嵌入参数的技术细节见 [会话技术架构](../session-architecture.md)。diff --git a/docs/product/changes.md b/docs/product/changes.mddeleted file mode 100644index d73337af..00000000--- a/docs/product/changes.md+++ /dev/null@@ -1,36 +0,0 @@-# 公开变更记录--## REQ-20261107-001:素材浮层就近定位与空时间轴引导--- **问题与对象:** 现有创作者从空轨道、素材库或已有片段进入生成时,弹框远离触发位置;生成期间仍显示空轨道起步引导,干扰继续编辑。-- **选择与实现:** 操作栏读取片段、范围或标尺的实际锚点,生成面板继承该位置;按钮入口传入触发元素。共用浮层尺寸测量、视口限位、上下避让与滚动/尺寸监听。生成时隐藏空态引导并禁止交互,关闭且仍为空时恢复;插入后使用原生轨道,撤销至空轨道时恢复引导。-- **影响与边界:** 保留原生素材放置、撤销和工程归属;不改变模型路由、账户、费用规则或素材归属。本次改善既有剪辑流程,没有新增画像或商业化结论。-- **验证:** 定向测试覆盖定位、内容增长、滚动跟随、空态切换和原生放置;按本次公开 PR 的提交运行 Studio 类型检查、构建、仓库检查与真实浏览器交互,实际结果写在 PR。不沿用历史执行结果,也不将本地素材验证当作供应商生成或视频导出验收。-- **文档:** [English introduction](../../README.md)、[中文介绍](../README.zh-CN.md)、[使用手册](../usage.md)、[素材生成设计](media-generation-design.md#时间轴交互规则及原因)、[编辑器开发](../editor-fork.md)。-- **后续待验证:** 实际多轨创作中的遮挡、操作效率与目标系统差异;不因本次 UI 回归通过推断模型创作质量或发布状态。--## 2026-11-06:五个 Skill、界面与双语介绍同步--- **问题与对象:** 现有 Agent 用户、模板作者和仓库贡献者需要一致的 Skill 名称、安装包和使用说明,避免改名后引导失效或打包漏项。-- **选择与影响:** 一期同装 motion-production、motion-director、motion-template-to-video、motion-recreate、motion-video-to-template。MCP 短 workflow ID 保持兼容,专业任务可直接进入;production 承接既定创作决定下的工程操作。公开 Tools 仍为九个。-- **界面:** 同步 OpenDesign 双主题、字体、按钮、表单与浮层材质,不改变作品 iframe 的样式、工程格式与原有布局职责。-- **文档:** 新增中英文介绍、Motion MD v0.1 提案、示例与资源索引。Motion MD 由用户显式提供给 Agent,尚无自动导入器;主题集合站与 Arena 仍为规划。旧中文首页保留跳转,仓库仍以 feature/motion 开发,main 与 legacy 留档流程见迁移说明。-- **公开与分发:** 保留独立 npm、两套依赖锁、正向打包清单、Apache-2.0 和上游/字体许可,以及浏览器统计发送逻辑移除。五入口与所引用的公开文档、工作流发现模块一起进入 npm/ZIP;不导入私有历史、过程档案或发布配置。-- **验证:** 按本次 PR 的确切提交运行静态检查、Studio 类型/构建/回归、安装及适配器测试、五入口 npm/ZIP 清单与九 Tool E2E;实际结果写在 PR。目标机/宿主加载、模型创作、正常速度审听与视觉验收另列,不从旧结果推定。-- **画像与商业影响:** 改善现有本地创作及模板复用入口,不新增用户研究结论、账号、价格、付费能力或发布。--## 2026-11-06:安装后的模板 Skill 引导--- 接受首次体验的新用户进入现有的 `template-to-video`,替换已删除的 `motion-template` 名称;沿用 Product Promo 示例与既有同意规则,不扩大安装授权。-- 安装回归提取实际脚本中的 Skill 引用,确认对应 `SKILL.md` 存在且至少匹配一项;CI 执行这条检查。新增测试在旧脚本上失败,修正后运行对应回归。-- 英文与中文使用说明同步标明模板入口,中文源码安装地址指向当前仓库的 `feature/motion`,并说明该命令在分支存在期间即可使用,与 `install.sh` 默认检出分支一致。-- 保留独立 npm、原生依赖锁、公开内容清理、浏览器统计移除和正向打包清单;不增加账户、计费或商业化能力,不发布包。--## 2026-11-06:独立分发与复刻工作流--- Motion 源码位于仓库根目录;保持独立 npm lockfile、安装器、MCP 与 Skills,不依赖 OD 的应用私有代码或工作区链接。-- 复刻入口已实现:参考视频使用 motion-recreate,原生工程、重建与验收指引通过同一套 MCP resources 提供。区域测量脚本不把无效范围或测量失败写成成功;一期继续只有九个公开 Tool 和四个 Skills。-- npm 应用归档、插件 ZIP 与完整 ZIP 共用 `scripts/distribution.ts` 的正向清单。只分发运行所需源码、构建资源、指定使用文档、Skills 和许可证;不分发开发测试、Studio 源码、过程记录或发布辅助工具。新增文档和脚本必须显式加入清单。-- 删除上游浏览器统计密钥与网络发送实现,保留编辑器调用接口;自动实验分组关闭。引擎子进程继续使用 `HYPERFRAMES_NO_TELEMETRY=1`。本机编辑、预览、渲染与技术验证不依赖使用统计。-- 验证入口:`npm run check`、`npm run typecheck:studio`、打包与复刻单测、Studio 回归、独立 npm 安装和真实出片验收。具体结果绑定对应 PR 的提交及 CI;没有执行的目标平台或模型回合不记为通过。-- 当前工作流只构建和校验;npm 安装器保持 `private: true`,不发布 npm、Release 或存储对象。本次不增加账户、计费或托管服务。diff --git a/docs/product/media-generation-design.md b/docs/product/media-generation-design.mdindex bf174e8b..72c22df3 100644--- a/docs/product/media-generation-design.md+++ b/docs/product/media-generation-design.md@@ -177,4 +177,4 @@ stateDiagram-v2后续观察应记录用户在哪一步离开、失败原因、如何采用结果和是否继续编辑;不预设未经采集的转化率或阈值。供应商真实 Key 的跨模型验证、专用参数表单覆盖、长队列下的操作体验和参考图权属/传输说明,仍需在对应接入任务中补证据。-调用使用用户自有账户,产品没有统一收费或托管额度。产品架构、协议、实现和验收分别维护;后续变更应补充本页对应决策的替代理由,并更新 [需求记录](changes.md),保留历史依据。+调用使用用户自有账户,产品没有统一收费或托管额度。产品架构、协议、实现和验收分别维护;每次变更先整体审视 [产品架构](architecture.md);确有架构或决策变化时按需修订对应说明,保留必要依据。diff --git a/docs/project-workspace.md b/docs/project-workspace.mdindex 16336f1f..71b1162a 100644--- a/docs/project-workspace.md+++ b/docs/project-workspace.md@@ -67,6 +67,6 @@## 验收与待验证项-服务回归覆盖旧数据兼容、多产物归属、最后产物恢复、命名隔离、需求去重、MCP 身份与保存竞争。DOM 和状态测试覆盖保存等待与失败、相邻工程 Tab 切换、关闭/恢复两侧、最后 Tab、无效 URL、模板提交和窄屏可见性。浏览器实际检查结果记在[需求记录](product/changes.md)。+服务回归覆盖旧数据兼容、多产物归属、最后产物恢复、命名隔离、需求去重、MCP 身份与保存竞争。DOM 和状态测试覆盖保存等待与失败、相邻工程 Tab 切换、关闭/恢复两侧、最后 Tab、无效 URL、模板提交和窄屏可见性。浏览器实际检查结果以对应提交的 PR 或交付说明为准。待验证:真实创作中的会话查找效率、多个产物之间切换与模板二次剪辑的完成体验,以及之后其他模式的 skill、工具与产物协议。没有新增用户研究或付费证据;不改变当前账号、权限和商业化能力。diff --git a/docs/repository-migration.md b/docs/repository-migration.mdindex 3cec03f6..81f31823 100644--- a/docs/repository-migration.md+++ b/docs/repository-migration.md@@ -4,6 +4,19 @@ The `feature/motion` branch replaces the former HTML Anything application with ODaily Motion changes branch from the latest `feature/motion` and open PRs with that base. The previous application is preserved at [`legacy`](https://github.com/nexu-io/html-anything/tree/legacy). Switching `main`, renaming the repository and publishing remain separate decisions.+## Upstream synchronization checkpoint++On 2026-11-08, the OpenMotion source `main` snapshot `21c3e5aaef1af34b0f126f7db90a86927e2ef325` was compared with public `feature/motion` at `c5f6975cfde71b3a55c6b21921ed64260937c246`. The latest source change, media-popover positioning and empty-timeline guidance, is already included through [PR #172](https://github.com/nexu-io/html-anything/pull/172). All 13 implementation and test files changed by that source update have identical Git blobs in the public branch.++The complete tree comparison found 2,626 identical entries, three files differing only by a trailing blank line, and 72 remaining path differences. Those differences preserve the public migration contract described below:++- Public licenses, contribution guides, installation URLs, documentation and source attribution replace source-repository-specific instructions and internal material.+- GitHub CI and the positive distribution list retain standalone packaging checks and disabled publication; source-repository upload/release helpers are excluded.+- Browser telemetry and automatic experiment assignment remain disabled, with matching tests.+- Recreation guidance retains the npm native-cache instructions alongside the complete ZIP runtime paths.++No additional runtime change is needed for this source snapshot. Future synchronization should compare against this recorded snapshot and review incoming changes while retaining these public adaptations. Open pull requests are separate changes until they land in their source branch; this checkpoint does not include them or authorize merging or publishing.+## Runtime and independent npm distributionMotion retains its own `package.json`, `package-lock.json`, pinned native runtime manifest, editor, MCP and Skills. No OD monorepo package, workspace link or OD-private import is required.diff --git a/docs/session-architecture.md b/docs/session-architecture.mdindex 4b4973f3..541d9528 100644--- a/docs/session-architecture.md+++ b/docs/session-architecture.md@@ -1,6 +1,6 @@# 会话、模式与 Artifact Viewer 技术架构-更新:2026-11-05。需求与产品行为见 [会话与 Artifact 浏览器](project-workspace.md) 和 [变更记录](product/changes.md)。本文描述当前代码的扩展边界;一期只实现 Motion,不把网页原型等后续模式写成已上线功能。+更新:2026-11-05。需求与产品行为见 [会话与 Artifact 浏览器](project-workspace.md)。本文描述当前代码的扩展边界;一期只实现 Motion,不把网页原型等后续模式写成已上线功能。## 一套领域模型,多种调用入口@@ -131,4 +131,4 @@ macOS 的 `mcp.ts` 只负责 stdio 和连接选择,业务位于 `mcp-tools.ts`## 验收-测试覆盖先有空会话、生成失败保留、MCP/HTTP 共用数据、真实回复去重与角色、旧工程兼容、跨会话归属拒绝、保存与 revision 竞争、完整/嵌入 URL 身份一致、嵌入偏好隔离、空会话生成后的 Viewer 激活。实际运行证据与剩余产品假设记在[需求记录](product/changes.md)。+测试覆盖先有空会话、生成失败保留、MCP/HTTP 共用数据、真实回复去重与角色、旧工程兼容、跨会话归属拒绝、保存与 revision 竞争、完整/嵌入 URL 身份一致、嵌入偏好隔离、空会话生成后的 Viewer 激活。实际运行证据以对应提交的 PR 或交付说明为准;产品假设在相关架构说明中明确标注。diff --git a/docs/skills.md b/docs/skills.mdindex 94cb2b50..2048d619 100644--- a/docs/skills.md+++ b/docs/skills.md@@ -81,7 +81,6 @@ MCP 工具说明和领域执行位于 `mcp-tools.ts`;`mcp.ts` 保留初始化| --- | --- || AGENTS.md、CLAUDE.md、README.md | 保留 #26 的专业直达、五名称与分发说明;用 #28 实际复刻流程替换占位口径 || docs/mcp-phase1-tools.md、docs/motion-extension-scope.md、docs/product/architecture.md、docs/skills.md、docs/template-catalog.md | 保留五入口、九 Tool 指导与宿主能力边界;补齐 recreate ready、独立参考/脚本及 27/26 注册数量,不恢复旧目录查询 Tool |-| docs/product/changes.md | 完整保留 Skill 整合 013、E2E 012 与 RECREATE-005 三条记录,历史验证按各自版本解读 || mcp-tools.ts、mcp.ts | 保留共享发现文案,更新复刻状态;不调整 Schema、分发门禁或 Tool 执行函数 || shared/workflow.ts | 保留新模板目录、五路线分发与原短 ID;并入 #28 的 recreate ready/rebuild/verification 注册 || skills/motion-production/SKILL.md | 保留通用工程职责和专业导航;增加“只有成片、无可编辑工程”的复刻边界 |diff --git a/docs/templates/requirement.md b/docs/templates/requirement.mdindex 8fc8458e..26814b2e 100644--- a/docs/templates/requirement.md+++ b/docs/templates/requirement.md@@ -1,6 +1,6 @@# REQ-YYYYMMDD-NNN:需求名称-使用说明:这是编写需求文档的模板。复制到 `docs/requirements/YYYY-MM-DD-主题.md` 后填写实际内容,并由文档中心和需求记录链接。简单需求直接更新已有专题和需求记录即可;不要把未填写模板当作交付文档。+使用说明:这是按需使用的需求文档模板,不要求每次变更创建文档。先整体审视产品架构;确有独立需求说明的必要时,再复制到 `docs/requirements/YYYY-MM-DD-主题.md`,填写实际内容并由相关专题链接。不要把未填写模板当作交付文档。## 基本信息@@ -33,6 +33,6 @@列出实际运行的检查、结果、证据位置,以及未执行或待验证项。代码测试、实际体验、用户研究和商业实验分别记录其证明范围。-## 文档同步与后续+## 架构审视与后续-链接更新后的正式专题、README 和 `docs/product/changes.md` 需求条目。记录剩余问题与后续行动,避免让重要结论只存在于本需求文档。+整体审视产品架构是否仍准确一致;仅在需要时更新架构及相关专题,并链接实际修改的文档。记录剩余问题与后续行动,无需为每次需求另建变更记录。diff --git a/docs/usage.md b/docs/usage.mdindex 07a334b8..953c19cb 100644--- a/docs/usage.md+++ b/docs/usage.md@@ -51,7 +51,6 @@ openmotion 围绕已有 Agent 用户的产品演示、参考复刻、动态图| [会话与 Viewer 技术架构](session-architecture.md) | 共用生命周期、模式/模板/skill、HTTP/MCP、Codex 嵌入、扩展点与设计取舍 || [素材生成设计与架构决策](product/media-generation-design.md) | 为什么共享网关、先生成再采用;选区交互、关键取舍、故障与扩展约束 || [模型网关](model-gateway.md) | 当前配置与 API/MCP 合约、运行限制、真实验证及未验证范围 |-| [需求与决策记录](product/changes.md) | 每次需求的选择理由、产品影响、验证证据和后续事项 |文档区分当前能力、已确认方向、待验证假设和候选方案。公开文档维护当前行为和可复现验证。@@ -210,9 +209,9 @@ node --experimental-strip-types scripts/verify-export.ts /absolute/path/final.mp## 开发与验证-**每次需求交付都必须同时更新产品文档。** 所有贡献者提交功能、优化、修复、重构或文档需求时,在同一提交或 PR 中更新受影响专题,并新增或补充 [需求记录](product/changes.md)。说明服务人群、前后行为、决策理由、架构影响、画像/商业化影响和验证证据;无直接画像或商业化影响时记录原因。用户可见入口、行为或限制变化时同步更新项目首页与本手册。+每次变更都应整体审视 [产品架构](product/architecture.md),判断产品定位、核心流程、模块职责、依赖、数据与接口边界、当前能力和限制是否仍准确一致。仅在需要时更新架构及相关说明;无需为每次交付自动修改文档或新增需求记录。-执行步骤见 [文档维护流程](README.md);复杂需求可使用 [需求模板](templates/requirement.md)。产品知识应进入仓库正式文档,不能只留在聊天或 PR 描述中。+审视原则见 [文档维护说明](README.md);需要独立说明的复杂需求可使用 [需求模板](templates/requirement.md)。验证结果记录在对应 PR 或交付说明中。```shnpm run checkdiff --git a/scripts/distribution.ts b/scripts/distribution.tsindex 72d1bf2d..06f8258a 100644--- a/scripts/distribution.ts+++ b/scripts/distribution.ts@@ -8,7 +8,7 @@ const root = fileURLToPath(new URL('../', import.meta.url));// New documentation and developer scripts require an explicit distribution decision.export const distributionDocuments = ['README.md', 'README.zh-CN.md', 'CONTRIBUTING.md', 'CONTRIBUTING.zh-CN.md', 'AGENTS.md', 'CLAUDE.md', 'docs/README.md',- 'docs/product/architecture.md', 'docs/product/changes.md', 'docs/product/media-generation-design.md',+ 'docs/product/architecture.md', 'docs/product/media-generation-design.md','docs/agent-adapters.md', 'docs/browser-runtime.md', 'docs/design-system.md', 'docs/editor-fork.md','docs/hyperframes.md', 'docs/mcp-phase1-tools.md', 'docs/model-gateway.md', 'docs/motion-director.md','docs/motion-extension-scope.md', 'docs/npm-installation.md', 'docs/project-workspace.md',