xiangsu-mcp-plus

像塑（Douyin AR，macOS）的 MCP 扩展：一个 MCP 服务同时提供像塑官方 MCP 的全部工具，以及官方 MCP 够不到的编辑器能力。

• 官方工具原样转发（get_scene、edit_by_dsl、capture_preview、save_project 等），像塑重启后自动重连，官方工具列表变化时通知客户端刷新。唯一的例外是 capture_preview：9.8.1 起官方截图是给窗口里的预览区域拍照，窗口最小化或不可见时是黑的，这时改为重置预览、等到重载后的画面，从预览的渲染结果截取并缩小到官方的 320×569（不含界面元素）；窗口可见时照旧转发，这时刚改完场景或换了预览视频可能还是旧画面（工具说明里写了这一点），要确认新画面用 preview_frames。

• 官方素材库：浏览、搜索、看封面、应用（脸部变形、美型、AI 实时变脸、美妆、滤镜、贴纸、画面特效等），流程与素材库面板相同；包括「素材广场」（其他创作者分享的现成 AI 图片、AI 妆容、自定义实时变脸、贴纸和素材包，应用时不重新生成、不扣额度）和自己的「收藏」。

• 「添加对象」菜单：工具栏美妆 / 美型 / AI 实时变脸里的全部官方功能项（美容、面部生成、表情生成、性别年龄、五官处理、身体换装等），可看示意图后按菜单项 ID 添加。

• AI 组合效果（用户拍照后在云端按工作流出图或出视频）：像 AI 效果窗口的「新建工作流」一样建工作流，交给官方工作流工具编辑，再像「应用」一样放进场景。

• 首页作品：浏览、搜索、看封面，下载完整工程到本地或直接在编辑器里打开（官方工程和已发布的作品），供 agent 读取场景、脚本和资源，学习别人的做法；下载的东西都有登记，用完即删，最长保留 24 小时。

• 交付：设置并上传图标、特效检测（和编辑器里点「特效检测」一样，云端检测）、填好提交窗口（名称、触发提示、摄像头方向、灵感、任务，一直走到「提交审核」页并等检测跑完；最后的「提交审核」由你来点）、手机预览二维码、把已领取的任务或创作灵感绑定到工程。

• 抖音音乐：按分类或关键词找歌，设为特效音乐。

• 灵感、任务、排行榜：首页「灵感」页签和活动中心的任务（征集任务、成长任务），以及像塑移动版才有的排行榜（年轻 / 男生 / 女生喜爱榜、每日投稿榜、热玩互动榜、跟拍榜，各榜按两级分类细分；热点榜；专题合集里两百多期主题特效榜和模板榜；创新计划月榜和官方精选）和成长之路（特效师等级、奖励和各目标进度），用编辑器里登录的账号读取；可收藏灵感、领取任务。

• 我的特效审核：自己提交过的特效和审核状态，审核不通过的具体原因和完整审核记录（编辑器里只显示「审核未通过」，原因原本只能在像塑移动版的审核记录页看到）。

• 塑型画笔（FaceWarpX）强度：官方能读不能写，这里按检查器滑块的方式改。

• 工程窗口：新建空白工程（首次保存到指定目录）、打开、关闭。

• 干净删除：删除对象时找出只被它使用的资源和它导入时带进来的素材包文件夹，确认后删除。

非官方项目，与字节跳动 / 抖音无关。依赖像塑编辑器的内部模块（9.7.2 实测），像塑升级后可能失效；ext_status 会逐项自检并列出缺失的接口。仓库不包含任何像塑的程序、代码或素材。

只用于学习和个人制作，禁止用来抄袭他人作品（详见协议与声明）。npm 包名 @muqian/xiangsu-mcp-plus。

工作方式

插件把 {pid, port, token, startedAt} 写到 ~/.xiangsu-mcp-ext/instances/<pid>.json（权限 600）。窗口崩溃或被强退时这份记录会留下来，所以只有该 pid 的进程还在、并且启动时间不晚于 startedAt 时才算开着的窗口；pid 被后来的进程复用时不算。插件日志在 ~/.xiangsu-mcp-ext/logs/plugin.log；MCP 服务每次工具调用（名称、耗时、报错、是否发了进度）和异常退出记在 ~/.xiangsu-mcp-ext/logs/server.log，超过 5 MB 时旧的移到 server.log.1；导入记录在 ~/.xiangsu-mcp-ext/imports/。

按工程找窗口时，同时询问各窗口开着哪个工程，卡住或正在关闭的窗口（5 秒没回应）不影响找到其它窗口，并记住每个工程上次所在的窗口，下次先问它。客户端请求带进度令牌时，工具调用期间每 5 秒发一次进度，避免长调用（连续截帧、等提交页检测）被当成空闲掐断。

Related MCP server: DC-COCO-MCP

工具

官方 MCP 的工具按原名提供。扩展工具都接受 project_path 或官方的 instance_id 指定工程（只开一个工程窗口时可省略）：

使用顺序示例：

• 套用官方素材：library_search → image_view 看 cover_ref → library_apply → capture_preview → save_project。

• 读别人的工程：works_search（或 works_list）→ image_view 看 cover_ref / gif_ref → works_download → 按返回的 outline.files 读 effect.dyehpj、Assets/ 下的场景和 Graph/ 下的脚本 → works_cleanup。

• 在编辑器里看别人的效果：works_open → get_scene / capture_preview → project_close（discard_changes=true）→ works_cleanup。

• 交付：icon_set → effect_check → mobile_preview 真机看 → save_project → submit_prepare（name、trigger_hint 等），检查返回的摘要和 next，在窗口里点「提交审核」。要参加任务的，tasks_list → task_receive → 再 tasks_list → task_bind，或者直接在 submit_prepare 里传 task。

• 找选题：rank_list（如 rank_type=1 年轻喜爱榜、categories=["人像美化","美妆"]、levels=["S","A+"]）看什么在火；rank_subjects（keyword="测一测" 或 kind="template"）看各期主题榜；rank_hotspots → 带 topic_id 看热点灵感 → inspiration_detail → image_view 看图；tasks_list → task_detail 看征集要求和奖项 → image_view 看内容块里的参考图。

• 看榜上特效的工程：rank_list → 把这页的 effect_id 和 name 交给 works_by_effect → status=found 的用返回的 template_id 走 works_download / works_open。

• 查审核结果：my_effects 看哪些没过、review.text 是原因 → 要看整条时间线用 my_effect_reviews；can_edit=true 的在编辑器「拍摄特效管理」里点「编辑」改完重新提交。

• 拆别人的妆：works_download → makeup_layers 看用了哪些部位、什么颜色、多浓；自己的工程 save_project 后同样用 makeup_layers 查缺了哪些部位。

• 做 AI 组合效果：ai_combine_new → 官方 get_workflow_capabilities（选生图基模）→ apply_workflow_patch（加生图节点、写 prompt、连「输入图 → 生图 → 效果组合」）→ 要看效果时官方 generate_workflow（扣额度）→ ai_combine_apply → save_project。别人的作品怎么搭的，用 works_download 下载「AI玩法」分类里的工程，看 Assets/AI 组合效果/*.oAICombineTextureJSA 里的 workflow 和 Graph/graph.json 里的 AI Graph。

相近工具的分工（每个工具只做一件事，这些也写进了工具说明；和官方工具重叠的，在官方工具的说明末尾补了一句指向这里）：

• 看场景：scene_tree 先摸清结构（紧凑文本，也能读下载的工程目录）→ inspect_many 一次看多个对象的参数；要完整 JSON 才用官方 get_scene / inspect。

• 删对象：只删对象用官方 edit_by_dsl；要知道删完哪些资源没人用了、连带清理，用 object_remove（→ resource_delete_unused）。

• 绑灵感：inspiration_bind 按 ID 写进工程，提交窗口自动带出；只在提交时选，给 submit_prepare 传 inspiration（在收藏的灵感和热点里按名称选）。

• 绑任务：task_bind 重开窗口把任务写进工程；只在提交时选，给 submit_prepare 传 task，不用重开窗口。

• 成长：tasks_list 的 kind=growth 是活动中心里一个个成长任务（参考工程、教程）；特效师等级和每级目标进度看 growth_route。

• 素材库：知道要找什么用 library_search；按面板和子分类浏览用 library_list。

几点约定：

• library_apply / library_images 只接受本会话里 library_list / library_search 返回过的 template_id；works_download / works_open 只接受本会话里 works_list / works_search / works_by_effect 返回过的作品（记录在 MCP 服务里，不受工程窗口开关影响，重启服务后需重新搜索）。

• 像塑最多同时开 2 个工程窗口（编辑器的 CHILD_PROCESS_LIMIT）。都占满时 project_open / project_new / works_open 返回 WINDOW_LIMIT（首页进程答复 reuseCurrent，工具不会把工程换进当前窗口），先 project_close 一个。

• 素材的 kind：package 素材包、ai_image AI 图片、ai_makeup AI 妆容（按部位建多个对象）、custom_gan 自定义实时变脸、foreground_sticker / face_sticker 图片贴纸、filter 滤镜。素材广场里没有可应用内容的卡片（编辑器点应用也没反应）不列出，只在 unsupported 里计数。素材广场单个关键词最多返回 1000 条。广场卡片是异步应用的，工具等对象出现在场景里（最长 60 秒）才返回；新建的渲染组（如「2D 前景」「AI 实时变脸 (1)」）会作为新增对象报告，删除它们用官方的 delete_render_group。

• 素材库的搜索接口只匹配标题，很多素材的名字里没有人们会搜的词（美妆 › 腮红里是「雾堇胭」「红玫瑰」，没有素材叫「滤镜」），所以 library_search 还会展开名字与搜索词相同的面板或子分类，以及「子分类 + 面板」组合（「复古滤镜」）；「面板 + 其它词」（「韩系滤镜」）只在该面板里按标题搜「韩系」。名字只是包含搜索词的子分类不展开，列在 related_categories。每个面板或子分类最多取 300 条（实测子分类 17–125 条）。什么都没匹配到时返回 hint。

• works_*、inspiration_*、task_*、rank_*、my_effects、my_effect_reviews、library_list / library_search / library_images、menu_list 与当前工程无关，任意一个工程窗口开着即可；不指定工程时由 pid 最小的窗口处理。

• 返回资料的方式：

  • 列表默认每页 20 条（服务端上限更小的按上限），只给挑选时要看的字段；要细节用对应的详情工具。

  • 列表里的图片、视频、音频不给地址，给短引用 *_ref / *_refs（img:12、video:3、audio:5），交给 image_view：一个签名 CDN 地址有几百字，实测占列表每条的 43%–93%。引用记在 MCP 服务里，这次运行期间有效（最多记 2 万个，超出时忘掉最久没用的）；详情工具（inspiration_detail、menu_list 的 details）给的是这个对象自己的图，仍给地址。

  • 我们自己的工具回答超过 3 万字时，全文写进 ~/.xiangsu-mcp-ext/outputs/（24 小时后删除），回答换成文件路径和结构概要（每个字段的值或条数，列表给每条有哪些字段），用读文件的工具按需读，或用分页参数分几次取。3 万是拍的：task_detail 原来一次回 4.8 万字，读不全。官方工具原样转发，不受影响。

  • 字段命名：投稿量统一叫 publish_*（publish_count、publish_peak、publish_total），跟拍量叫 follow_shoot，页面原样给的展示文字（如「1.2万」「¥50」）以 _text 结尾，换算过的金额以 _yuan 结尾；看不出单位的数（任务奖项的 money、award_amount）原样给，不换算。

• 灵感、任务、排行榜按编辑器首页活动中心的方式请求（编辑器的登录 Cookie 和签名请求头），读写的都是编辑器里登录的账号。排行榜和成长之路用的是像塑移动版的接口，榜单名和筛选项取值与移动版一致，后端改版时可能失效。灵感和任务详情的接口移动版和编辑器是同一个（2026-11-08 对照移动版 v17.7.0 安装包里的接口逐个实测，返回完全相同），移动版看到的内容都在工具的返回里；活动详情、热点内容流、任务筛选、每日任务、创新任务这几个移动版接口暂未接入（参数未知，或当前账号没有内容可核对）。

• 几处上限是在服务端实测的：rank_list 和 rank_subjects 每页最多 20、inspiration_list 每页最多 50（100 会报错）、专题榜详情一次最多 20。移动版的「特效优秀视频榜」接口对所有榜单都返回空，没有提供。

• 审核记录：编辑器的「拍摄特效管理」（/creator/v1/effect_list）只有状态码，原因在像塑移动版的审核记录页（站内信「点击查看未过审原因」打开的 effect.douyin.com/m/detail?showReviewList=1）。工具按那个页面的方式取：「上线审核」先读 review_nodes（review_type=1），没有记录再读 effect_reviews；「精选审核」读 review_nodes（review_type=2）。2026-11-07 实测，被驳回的特效 review_nodes 不返回记录，原因来自 effect_reviews，如「特效不符合规范：特效中可能含有涉及展示或宣扬不同群体攻击对立类内容」。正文里的 |<b>…<b>|、|<a><href>链接<href>文字<a>| 等标记按页面的规则去掉，链接放进 links。分条原因 refuse_reasons 的结构取自页面代码，实测的特效还没带过。别人的特效和不存在的 ID，服务端一律报 code=1301（「参数不正确，请正确访问」）。

• my_effects 翻页要把上一页返回的 sort 原样传回，next_cursor 就是它（传 cursor 或 offset 都只会拿到第一页，2026-11-07 实测）。服务端不给「还有没有」，工具按「这页满了就还有」判断，所以最后一页正好满页时 has_more 仍是 true，再翻一页得到空列表。每页上限 50 是拍的：每个未通过的特效要多一到两次请求。

• 只有作者分享到首页的特效才有工程可下载。排行榜的 effect_id 和首页作品的 effect_id 是同一套编号，works_by_effect 按 ID 精确匹配（与首页搜索框的「特效ID」搜索同一个接口，默认在「推荐」里查，首页在「官方工程」里不提供按 ID 搜）。按 ID 搜时「推荐」也能查到只出现在其它分类的作品（2026-11-07 实测 8 个全中，在它们自己的分类里按 ID 搜反而一个都查不到），所以不用跨分类查。

• 首页翻页除了 cursor 还要带上一页返回的 sortingPosition 和 version（编辑器首页就是这样翻的），只带 cursor 每一页都是第一页；works_list 的 next_cursor 把三者编在一起。按作品名搜索时，「推荐」翻到底只有约 300 条，「美化」「友友天地」等分类里还有它没有的（「头套」多 46 条、「美妆」多 87 条），所以 works_search 默认搜全部分类。服务端偶尔会提前结束一轮翻页（6 轮里有 1 轮停在 249 条），没到 300 条上限的分类会再翻一轮合并；服务端一直给同一页时停下，并把分类列在 incomplete。每个特效要一到两次请求（查不到 ID 且给了名字时再按名字搜一次），实测查一页 20 个用了约 10 秒。结果分三种：found 首页有这个特效的工程；same_name 首页没有它，只有同名作品，effect_id 不同，可能是别人的作品，不能当成同一个特效；not_on_homepage 作者没公开工程，没有正规途径能拿到（编辑器「我的特效」里的工程下载只对自己的特效开放）。2026-11-07 实测年轻喜爱榜第一页 20 个特效：10 个 found，1 个 same_name，9 个 not_on_homepage。

• 提交窗口是抖音特效平台的网页（effect.douyin.com/ac/submit-orion，每次在线加载，安装包里的离线版本较旧，字段也不同）。submit_prepare 按页面上的类名和文案找元素，页面改版后找不到时报 SUBMIT_PAGE_CHANGED，不会跳过。名称框会在页面的 aiName 配置请求回来时重新挂载，先填的内容会被清空（2026-11-07 实测，配置在表单出现约 1 秒后才回来），所以工具等这个请求完成再填，最后再用「提交审核」页的摘要核对一遍。灵感下拉只列当前账号收藏的灵感和热点，每次加载 10 条，不在列表里的用页面的搜索框找；选了和灵感所带任务不一致的任务时，页面会清掉灵感，工具会报 SUBMIT_BINDING_NOT_APPLIED。「特效发布设置」页上按账号出现的其它设置（活动、创新声明、作品授权）不填，列在 other_sections。

• works_download / works_open 走编辑器自己的下载流程，每次解压一份新的到像塑实例目录的 ProjectCreatedTmp/CreatedFromTemplate/<guid>/ 下。dest 副本不含 Library/ 缓存（编辑器打开时会重建）。

• 下载物不留痕：

  • 编辑器缓存在 ~/Library/Application Support/DouyinAR/Shared/Resources/LokiDownload/TemplateResources/ 的工程包，解压后立即删除（下载前已存在的视为你自己在首页用过的缓存，不动）。

  • 给了 dest 时，临时目录里那份随即删除。

  • 每份下载（临时目录或 dest）登记在 ~/.xiangsu-mcp-ext/works-downloads.json。works_cleanup 随时删除；没删的在 24 小时后由下一次下载自动清掉（这个时长是拍的：够一个工作日内学完，又不至于堆积，可按需调 src/works.mjs 的 DOWNLOAD_TTL_MS）。

  • 编辑器窗口正开着的下载不会被删；像塑关窗时不会自己删除这些目录，关窗后再调 works_cleanup。

• AI 组合效果在工程里由三部分组成：场景里的「AI 组合效果」图片对象、它绑定的组合效果纹理（Assets/AI 组合效果/*.oAICombineTextureJSA，存编译好的 workflow、上传后的 graphTosUri 和云端草稿 draftId），以及 Graph/graph.json 里的 AI Graph。「添加对象」菜单里的 AI 组合效果只建对象和一张 workflow 为 {} 的空纹理，编辑器自己也是先建空壳、再由「应用」填参数，所以 menu_add 仍然拒绝它，改用 ai_combine_new / ai_combine_apply。哪些步骤会连到云端（2026-11-08 读编辑器代码；ai_combine_new 和 ai_combine_apply 不建草稿是实测，官方 Patch 建草稿、预览视频上传只读了代码，没有实测）：ai_combine_new 和本地连线都不联网；官方 apply_workflow_patch 每次改完都会把工作流存成账号下的云端 AI 效果草稿（releaseAIEffect），此后 ai_combine_apply 返回的 draft_id 就是这个草稿；官方 generate_workflow 扣生图额度；ai_combine_apply 上传工作流文件，生成过预览视频时把视频一并上传供审核，自己不建草稿。场景里有变声组件时编辑器拒绝「应用」，工具报 AI_COMBINE_APPLY_NO_EFFECT。

• 预览重载有延迟，应用后用 interact_by_dsl 先 wait 2–3 秒再截图更稳。

• 资源删除不可撤销；对象删除可以在编辑器里撤销，但已删除的资源不会回来。

• 「孤儿资源」只按场景直接引用判断（资源的编辑器 guid 是否出现在场景序列化数据里）。只通过材质等间接引用的资源不会被判为孤儿。

• 素材放进场景时，编辑器会按对象名再建几个文件夹（如 复古清冷_滤镜、复古清冷_美妆），保存时对象还在才会写到磁盘。object_remove 把这类只在编辑器里的路径单独列在 editor_only_paths，对象删除后下次保存就会消失，不用删；unused_paths 只含磁盘上真实存在的路径，可以照着删（用 resource_delete_unused）。

安装（macOS）

需要 Node.js 24+ 和已安装的像塑。安装即表示你同意下面「协议与声明」里的用途限制：只用于学习和个人制作，不得用来抄袭他人作品。

从 npm 安装（必须全局安装：插件按绝对路径加载这份代码，npx 的临时缓存会被清理，安装命令在那里会直接拒绝）：

npm install -g @muqian/xiangsu-mcp-plus
xiangsu-mcp-ext-install   # 装到 ~/Library/Application Support/DouyinAR/Plugins/v<版本>/Local
echo "$(npm root -g)/@muqian/xiangsu-mcp-plus/src/server.mjs"   # MCP 配置里 args 用这个路径

或从源码安装：

git clone https://github.com/Muqian-Sun/xiangsu-mcp-plus.git
cd xiangsu-mcp-plus
npm ci
node scripts/install.mjs

在 MCP 客户端配置里加一个 stdio 服务（command 用 which node 的绝对路径，args 用上面的 server.mjs 路径或源码目录下的 src/server.mjs）：

{
  "mcpServers": {
    "xiangsu": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/src/server.mjs"]
    }
  }
}

它已经包含官方工具，不必再单独配置官方的 xiangsu-mcp-manager。如果你还在用像塑自带的 xiangsu-effect-editor skill，它要求客户端里存在名为 xiangsu-mcp-manager 的服务；这种情况下保留官方配置即可，两者可以并存。

插件只在安装后新打开的工程窗口里加载；已开着的窗口要保存后重开。插件直接 require 这份代码（源码目录或 npm 全局目录），安装后不要挪动；用 npm install -g 升级时路径不变，不用重新运行安装命令。

更新后怎么生效

• 改 editor-plugin/library.cjs 或 editor-plugin/features/*.cjs：插件在下次调用时按修改时间自动重载，不用重开窗口；改坏了返回 LIBRARY_RELOAD_FAILED，旧版本继续运行。新增插件方法写进对应 feature 的 METHODS。

• 改 editor-plugin/runtime.cjs：重开工程窗口。

• 改 src/：在 MCP 客户端里重启这个服务。

开发

• npm test：用模拟的编辑器模块测插件逻辑；用 jsdom 按线上结构搭的提交页测填写流程；用内存传输测 MCP 工具、官方转发、工程窗口编排。

• node scripts/mcp-call.mjs <tool> '<json>' [...]：新起一个服务按顺序调工具，图片写到 <临时目录>/xs-mcp-call/ 下每次运行一个子目录（一小时后清理）。scripts/official-call.mjs 直调官方 MCP，图片同样放在 xs-official-call/ 下。

• node scripts/call.mjs <method> '<json>' [--pid N]：直调插件。

• node scripts/e2e.mjs <工程路径> <关键词> [标题]：搜索 + 应用 + 未知 ID 报错的端到端检查（会真的导入素材，只对测试工程用）。

• config.local.json 里 devEval: true 时可用插件方法 dev_eval 在编辑器进程里执行探测代码（scripts/call.mjs dev_eval '{}' --code-file x.js，scripts/dump-source.js 可导出模块源码）。同一个开关也管 scripts/call.mjs 的 eval / describe；三者都在每次调用时读取开关，改回 false 在开着的窗口里立即失效。日常使用保持 false：它能在编辑器进程里执行任意代码。

• 环境变量 XIANGSU_MCP_EXT_STATE 可改状态目录（测试用），XIANGSU_MCP_URL 可改官方 MCP 地址。

依赖的编辑器内部接口

完整清单在 editor-plugin/features/assets.cjs 的 REQUIRED（按功能分组），ext_status 会逐项核对。主要有：

• 素材库：@orion/Business/AssetsLibrary/Core/Api/{getAssetCategory,getAssetList,search}、.../Control/AssetsLibraryNav/{util,const}、.../Control/util.downloadLokiFile

• 素材广场与收藏：.../Core/Api/{getAIAssetCategory,getAIAssetList,collect,getAssetSecondPanel,publishAsset}、.../Core/Control/AssetsLibrary 的 AssetsLibrary.getInstance()（其中的 AIAssets.applySquareAsset、AIAssetPictureCtx、AIAssetMakeupCtx、UGanManager 与 getAssetItemByQuery）、@orion/Business/API/ai_effect_api.getDYEHFileUrls

• 导入：@orion/orion-sdk/EditorFramework 的 Resource.AssetPackageManager.instance.import、UndoSystem、PreviewSyncer

• 菜单：@orion/orion-sdk/orionui 的 ExtensionManager / I18n，DynamicMenuConfigInfo，SceneOpsService.createEntity，HoverTipsMap

• AI 组合效果：AIEffectWindow/AICombinationToolPanel/Core/AIGraphProjectUtils.createAIGraph（「新建工作流」按钮用的同一个），.../Core/Manager/AIGraphManager 的 getInstance、addGraph、getGraphById、switchGraphbyGuid、editorPanelApply（「应用」；失败时不抛异常，而是在 BusinessEventManager 上发 AIEffectShowToast，工具监听它并以场景里出现新对象为准）

• 工程窗口：OpenProjectFromEditCommand + EditSender（与编辑器自己的 launchProject 同一请求，9.8.1 起首页进程只认它），closeProjectAndBackToHome

• 首页作品：@orion/Business/HomeWindow/TemplatesPanel/Request/{templatesPanel,templatesCategory}、.../Model/util.transformTemplate、.../Model/DownloadTemplateModel；打开作品用 OpenProjectFromEditCommand 的 openTemplate

• 交付：IconCreationNew/controller/IconPreviewManager、IconCreationNew/UI/BottomPanel/DYEHIconUploadHelper.uploadIcon（上传图标，写回 iconUri）、Submission/SubmissionExtension/EffectSubmissionExtension（提交接口 submit() 只做前置检查并打开提交窗口）、全局 App._windows（编辑器每次都新开提交窗口和特效检测窗口、不保存引用，按类名 DYEHEffectSubmissionWindow / DYEHPerfTestWebWindow 在这里找到它们；提交窗口和特效检测窗口都是网页窗口，网页里的脚本经 webview.evaluateJavascript 注入，结果经窗口的 JS bridge 以 orionJSB:// 查询传回）、PerfTest/PerfTestExtension、EditWindow/ToolBar/MobilePreview/backendHelper、effectExporter.exportEffectPackage

• 灵感、任务、排行榜：BusinessCommon/UrlConst 的 Domain.kBackendApiURL 与 DomainPath.{kActivityAPI,kTaskListAPI,kGrowthTaskList}、orion-sdk/orionui 的 CookieManager、BusinessCommon/Utils 的 PlatformUtils.genSignData / UserAgentUtils.userAgentGenerator、HomeWindow/ActivitiesCenter/Common/types（任务状态、getTypeName）、InspirationDetail/View/const 的收藏类型、Agent/AgentInspirationBridge

• 音乐：EditWindow/Inspector/MusicLibrary/{Model/MusicCategoryModel,Model/MusicListModel,Component/MusicListComponent/MusicSquareManager}

• 预览帧：Business/Preview/PreviewManager 的 cacheCurrentFrame / captureScreenshotToMemory（渲染结果；9.8.1 前官方截图也走这组调用）；重置用 PreviewSyncer.requestReloadSticker 加 PreviewReloaded 与 PreviewTextureUpdated 事件；后台帧率用 EditWindow/BackgroundModeManager.setRecordingMode；窗口是否可见看 EditWindow/EditWindowController 的窗口和 orionui.WindowState

协议与声明

代码以 MIT 协议 开源。另外请注意：

• 用途限制：本工具只用于学习和个人制作。禁止用它抄袭他人作品：不得把通过本工具看到、下载或套用的他人作品（首页作品工程、排行榜特效、素材广场里其他创作者分享的素材等）原样或稍作修改后发布、投稿、商用，或当作自己的原创。参考别人的做法学习思路可以，作品要自己做。MIT 协议针对的是本项目自己的代码，不改变他人作品的权利归属。

• 本项目是个人开发的非官方工具，与字节跳动、抖音、像塑没有任何关联，也未获其认可或支持。「像塑」「抖音」「Douyin AR」等名称和商标归各自权利人所有。

• 仓库只包含本项目自己的代码，不包含像塑的程序、源码或任何素材。通过本工具访问的官方素材、首页作品，其版权归像塑或原作者所有，使用须遵守像塑 / 抖音的用户协议和平台规则。

• 首页作品只用于学习参考：不要把下载的工程、素材放进公开仓库或转发给他人，学完用 works_cleanup 删除。

• 本工具调用的是编辑器内部接口，可能随像塑升级失效，也可能被平台限制。使用风险自负，作者不对因使用本工具造成的账号、数据或作品损失负责（详见 MIT 协议的免责条款）。

English

Unofficial MCP extension for Douyin AR (像塑) on macOS. One stdio MCP server proxies every tool of the editor's official MCP (with automatic reconnects) and adds what the official server cannot do: browse/search/preview/apply official library assets, browse/search/download or open the homepage works (official projects and published effects) as full projects an agent can read and learn from (rank-board effects are looked up there by effect id, though effects whose authors did not share them on the homepage have no downloadable project; every download is registered and deleted by works_cleanup or after 24 hours), add any item of the editor's "add object" menu (toolbar makeup / reshape / AI face effects), create AI combine workflows (the photo is sent to the cloud and generated from the workflow) and apply them to the scene the way the AI effect window does, leaving node editing and preview generation to the official workflow tools, list a project's makeup layers with the face part, colour and strength of each (from the layer's region and its texture's pixels when the name says nothing), set FaceWarpX brush intensity, prepare delivery (setting and uploading the icon, local and cloud effect checks, filling in the submit window — name, trigger hint, camera, inspiration, task — up to its final step, where pressing 提交审核 stays a user click, phone preview QR codes, binding received creator tasks or inspirations), read the signed-in account's inspirations and tasks (collect inspirations, receive tasks) and the mobile app's rank boards, list the account's submitted effects with their review status and, for rejected ones, the reviewer's reason and full review timeline, use Douyin music, open/create/close project windows, and remove objects together with resources only they used. It works through a small editor plugin that exposes a token-protected RPC on 127.0.0.1 inside each project window. Relies on editor internals (verified on 9.7.2); ext_status reports any missing internals. Install with npm install -g @muqian/xiangsu-mcp-plus && xiangsu-mcp-ext-install (a global install is required: the editor plugin loads this code by absolute path, so the npx cache is refused), or from source with npm ci && node scripts/install.mjs; then register node <package>/src/server.mjs as a stdio MCP server.

For learning and personal creation only. Do not use it to copy other creators' works: works you view, download or apply through this tool (homepage projects, ranked effects, assets other creators shared) must not be republished, submitted, used commercially or passed off as your own, as is or modified. Licensed under MIT, which covers this project's own code only. Not affiliated with or endorsed by ByteDance / Douyin; all product names and trademarks belong to their owners. The repository contains no editor code or assets. Official assets and homepage works accessed through this tool belong to 像塑 or their creators and are subject to the platform's terms; use downloaded works for learning only, delete them with works_cleanup when done, and do not redistribute them.