Ic Writer

infinite-creation 写入桥（harness → 项目文本内容）

外部 Agent 通过 HTTP API 把文本内容写进一个已在运行的 infinite-creation 实例。 只写文字：项目、小说原文、剧本、分镜、人物圣经/风格、素材提示词。既能写新项目，也能改已生成的 LLM 产物。 绝不触发生成（图片/视频/语音/音乐/导出），绝不删除项目，只经 HTTP API 读写（不直连 data/ic.db、不手改 data/ 与 config.json）。

铁律（先读完再动手）

1. 只写文本，不触发生成。不要调用任何生成/渲染/导出接口（清单见下节）。图片、视频、语音、音乐、成片导出全部由用户在应用界面里启动；你只负责把「写什么」落进去。
2. 绝不删除项目。整个流程里不要调用 DELETE /api/projects/:id。日志的唯一清理时机就是用户在界面手动删项目。回滚接口也会拒绝「回滚掉项目创建」。
3. 先读后写。每次写之前先 GET 现在的状态（章节标题、分镜 idx、已有内容），写完再 GET 回读校验。用户可能同时在界面上改；要覆盖已有内容时，先读回来确认自己要覆盖的就是它。
4. 长文本一律走文件，不要内联进命令行。Windows 上 cmd.exe 的 %* 会把裸换行当成命令结束，静默截断你传的小说。用 Node 读文件拼 JSON，或 curl --data-binary @body.json。
5. 分镜按章节整体写（PUT …/storyboard），不要一条条乱序插；整章一次调用 = 一个批次，写坏了整批回滚。
6. 一次写入就是一个批次。同一个 API 调用产生的所有变更共享 batch_id，可整批回滚。
7. 项目正在跑任务时不要写。先 GET /api/projects/:id 看 status：是 running 就等（或让用户先停任务）——运行中的任务正持着当前分镜行，删除类写入会被直接拒（409），内容类写入也可能被任务用旧数据覆盖，最后「成片与分镜表对不上」。
8. 写进去的分镜要能过应用的业务校验，否则接口直接 400：duration 1~15 秒；dialogue 字数 ≤ duration × 5.5（超速会被 TTS/H3 压成听不清的模糊声）；单个分镜说话人 ≤ 2（每说话人一段参考音色）；resolution ∈ 360P/480P/720P/768P/1080P/2K/4K/custom（空串 = 继承项目设置）；aspect_ratio ∈ 1:1/2:3/3:2/3:4/4:3/9:16/16:9/21:9；idx 从 1 起、同章内不重复。项目级同名两项（POST /api/projects、PATCH /api/projects/:id）用同一份枚举：分镜会继承项目设置，项目这一层写错会让整个项目在渲染阶段才炸，同样 400。
9. 只能走 HTTP API 读写，不许直连数据库/文件。项目数据一律通过 {base}/api/... 读和写：禁止打开 data/ic.db（node:sqlite/sqlite3/任何 DB 客户端，读也不许）、禁止直接改 data/ 下的文件或 config.json。绕过去就没有变更日志（不可回滚、source 记不上、批次不成立），详见下一节。

只走 API：不碰数据库、文件与配置

本技能的唯一读写通道是 {base}/api/...。即使 data/ic.db 就在手边，也不要打开它——绕过去等于把本技能赖以成立的三样东西一起毁掉：每次变更的原始行快照、source（这条改动是谁写的）、batch_id（整个操作可整批回滚）。

API 读不到、或改不了的 → 直接告诉用户缺什么，不要自己去库/文件里补（接口没提供的能力就不在本技能范围内，例如删除项目）。

禁止调用的接口（会把任务推进生成链路）

写文本时若发现「这个字段要等生成才有值」（如 shots.status、video_path），直接跳过——那是生成链路的产物，不是你要写的东西。

前置

• 服务地址：环境变量 IC_BASE_URL，默认 http://127.0.0.1:4600。
• 只对本机的 127.0.0.1 使用：该实例零鉴权，能读项目全文、改内容、回滚。用户若把 server.host 配成 0.0.0.0，它就是一台对局域网开放的写入端点——遇到这种配置先提醒用户改回本机。
• 探活：GET {base}/api/health 期望 {"ok":true}。
• 运行环境有 Node ≥ 22（本项目前置依赖），所以推荐用 node -e 发请求：跨 shell 一致、不用跟引号搏斗。

bashCopy code
# 探活
node -e "fetch(process.env.IC_BASE_URL||'http://127.0.0.1:4600'+'/api/health').then(r=>r.json()).then(o=>console.log(o))"

以下示例统一用这个辅助写法（PowerShell / cmd / bash 通用）：

bashCopy code
# 读：列项目
node -e "fetch('http://127.0.0.1:4600/api/projects').then(r=>r.json()).then(o=>console.log(JSON.stringify(o,null,2)))"

# 写：body 从文件读（长文本必用）
node -e "const fs=require('fs');fetch('http://127.0.0.1:4600/api/projects/PID/chapters',{method:'POST',headers:{'content-type':'application/json'},body:fs.readFileSync('body.json')}).then(async r=>console.log(r.status,JSON.stringify(await r.json())))"

接口速查

内容分层：别写错层

分镜可写字段（白名单外一律 400 报错）：

Copy code
chapter, idx, scene_name, camera, visual, dialogue, narration, sub_shots,
duration, resolution, aspect_ratio, video_prompt,
character_ids, scene_ids, prop_ids, costume_ids, age_ids, audio_ids, references

status / error / video_path / video_prompt_used / prompt_id / seed 是生成产物，不可写（防伪造「已生成」）。 seed 尤其别写：渲染链路从不读 shots.seed，每次渲染都现取一个随机种子回写，所以写进去的值下一次渲染就被覆盖，且它不进变更日志、回滚也恢复不了——写了等于没写。 resolution / aspect_ratio 只接受枚举值（见铁律 8）；duration / idx 有区间约束。 数组字段的元素必须是字符串：塞对象（[{id:'x'}]）会被 400 拒绝，不会静默变成 "[object Object]"。

改写已生成的 LLM 产物

同一个写入 API 也用于修正已经生成过的内容——正是本技能的常见用途：

注意两点：

• 改了要连带说明影响：分镜的 video_prompt 改过之后，应用下次跑渲染阶段会重出这条镜头（应用自己按 video_prompt_used 判定，不需要你触发）。这在预期内，但要在交付说明里告诉用户。
• 产物字段不可写：status / error / video_path / video_prompt_used / prompt_id / seed 一律 400 拒绝——它们是生成链路的结果，写不进去也伪造不出「已生成」；seed 还会被下一次渲染覆盖。

典型流程

bashCopy code
BASE=http://127.0.0.1:4600
# 0) 探活 + 建项目（记下返回的 id）
# 1) 写 3 章小说：chapters POST ×3（title 省略则自动「第N章」）
# 2) 写每章剧本：chapters/:cid PATCH {script:"..."}
# 3) 整章写分镜：chapters/:cid/storyboard PUT {shots:[{scene_name,camera,visual,dialogue,duration,...}]}
# 4) 回读校验：GET chapters → shotCount；GET shots → 逐条核对 idx/字段

分镜一条的示例：

jsonCopy code
{
  "scene_name": "雨夜巷口",
  "camera": "中景缓推",
  "visual": "少女撑黑伞立于巷口，霓虹倒映积水，雨丝斜落",
  "dialogue": "（低声）你终于来了。",
  "narration": "",
  "sub_shots": "0-3s 推近；3-5s 停住",
  "duration": 5,
  "character_ids": [],
  "video_prompt": ""
}

回滚

bashCopy code
# 看最近日志（谁改的、改了哪条、前后快照）
node -e "fetch('$BASE/api/projects/PID/logs?limit=20').then(r=>r.json()).then(o=>{for(const l of o.items)console.log(l.ts,l.source,l.entity,l.action,l.entity_id)})"

# 撤销一次调用：用那次的 batch_id 整批回滚
node -e "fetch('$BASE/api/projects/PID/logs/rollback',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({batch_id:'BATCH_ID'})}).then(async r=>console.log(r.status,await r.text()))"

• 目标三选一：log_id（单条）/ batch_id（整批）/ since_ts（该时刻含之后全部内容变更）。
  • 整批回滚用 batch_id：单条 log_id 只恢复那一条——回滚「删章节」时章节回来了，它的分镜不会（分镜各有自己的删除日志）。要「整个操作一起还原」就用那次的 batch_id。
  • since_ts 只覆盖内容变更，不会反转此前的回滚（要重做请显式回滚那条 action='rollback' 的日志）。
• 漂移保护：那条变更之后又被改过时，接口回 409 且不做任何改动，返回 conflicts（当前值 vs 期望值）。确认要覆盖新改动才加 force:true。
• 返回 skipped 里的 reason 会说明为什么某条没回滚（例如「项目创建不可回滚（禁止删项目）」）。
• 逆操作整批跑在一个事务里：中途失败 → 全部撤销，返回 applied: [] + rolled_back: true（不会留下「改了一半」的状态）。
• 回滚只恢复数据库行，不删磁盘上的图片/视频文件；图片文件要重传。
• 回滚本身也记日志，所以「再回滚一次」= 重做。

交付前自检

• 全程只用了 {base}/api/...：没打开过 data/ic.db（只读也不行），没改 data/ 下的文件与 config.json
• DELETE /api/projects/... 一次都没调用
• 没有调用任何生成/渲染/导出接口（run / stages / regenerate / generate / music / export）
• 写入前查过 GET /api/projects/:id，status 不是 running
• 每章 novel/script 都回读确认非空；被改写的内容与用户要求一致
• 分镜 shotCount 与预期一致，idx 连续、chapter 落在正确章节
• 所有写入都拿到了 2xx（400 说明有条分镜没过业务校验：时长/台词速度/说话人/枚举，已按铁律 8 修正）
• 需要时给用户一份「本次写入的 batch_id 列表」，方便一键回滚