| name | artifact-writer |
| description | 当你需要写或修改 ai-flow action artifact 文件（actions/<n>-<type>.md）、 不确定该用什么 SDK 工具、参数怎么传、路径写哪、如何跟 submit_work 衔接、 或之前写失败过想看排查清单时——请 `read` 本 skill。任何「写 artifact」场景必读一次。 |
ai-flow Artifact 写入协议
一句话核心
写 / 创建 artifact 文件永远用 SDK 内置 write 工具、永远不要用 edit / write_file / create_file。
edit 工具签名是 { path, oldText, newText }、要求文件已存在、能找到 oldText。新建 artifact 时文件不存在、edit 一定失败、SDK 拒掉调用、模型 retry 还用 edit、几轮后整个 run status=error → workflow failed。这是实测踩过 N 次的 anti-pattern。
工具映射表
| 你想做的事 | 用哪个工具 | args 形状 |
|---|
| 创建新的 artifact 初稿 | write | { path: <绝对路径>, fileText: <完整 markdown> } |
| 修订已存在 artifact（用户 revise 后的小改） | edit | { path: <绝对路径>, oldText: <原段>, newText: <改后段> } |
| 整文件覆盖已存在 artifact | write | { path: <绝对路径>, fileText: <完整新 markdown> } |
| 删 artifact（不应该发生） | delete | { path } |
记忆口诀：「初稿 write、改段落 edit、整体覆盖也 write」。拿不准就用 write、永远是对的。
路径必须绝对（当前体系：actions/<n>-<type>.md）
artifact 相对任务目录的路径是 actions/<n>-<type>.md（无前导 0、n 从 1 起）：
- 相对路径例：
actions/1-plan.md、actions/2-build.md、actions/5-custom.md
- 绝对路径 =
<数据目录>/tasks/<taskId>/actions/<n>-<type>.md
- 也就是 super-prompt 顶部「Artifact 文件路径」段给的
{{actionArtifactsDir}}/<n>-<type>.md
- 例：
…/tasks/<task_id>/actions/1-plan.md
注意：
- artifact 不在 agent cwd 下——agent cwd 是用户业务仓库、artifact 在平台数据目录的
tasks/<taskId>/actions/ 下、两者不在同一棵目录树
- 必须用绝对路径——相对路径会写到 agent cwd 下、artifact 永远找不到、UI 也加载不出
- 路径直接抄 super-prompt 里的「Artifact 文件路径」/
[NEXT_ACTION] 头里的 artifact_path、不要自己拼、不要用旧的 artifacts/01-plan.md 那种前导 0 / phase 目录
submit_work 的 artifact_path 传相对路径（如 actions/3-build.md）、跟 write 用的绝对路径对应同一文件
写 artifact 的标准动作（按顺序）
每个 action 完成时按这 3 步走、不要省也不要乱序：
1. write artifact
tool_use: write
args: {
path: "<数据目录>/tasks/<task_id>/actions/<n>-<type>.md",
fileText: "<完整 markdown 内容、从 # 标题开始>"
}
fileText 是完整文件内容、不是补丁、不是「在末尾追加 X」。从一级标题开始、按该 action prompt 模板的章节顺序写完。
2. emit 一条简短 assistant_message
格式：「已写入 actions/-.md、请审阅」（一句话、不要总结全文）。也可按 super-prompt：先给用户 1-3 句简短结论。
禁说的话：
- 把整份 artifact 内容粘回 assistant_message（用户已经能在左侧看到、不要重复）
- 把 SDK 协议名（
submit_work / ask_user 等）告诉用户
3. 立刻调 submit_work 交卷
tool_use: submit_work
args: {
task_id: <顶部告诉过你的 task_id>,
action_id: <本 action 的 id>,
artifact_path: "actions/<n>-<type>.md"
}
交卷后正常结束本轮回复——不要再调已退役的 wait_for_user / curl 长轮询。用户的下一步（推进 / 再聊聊 / 回答提问）会作为新消息续同一会话。
收到用户 revise（改类反馈）时的写法
用户改类反馈走 ask_user 复述确认（主 prompt 里详述）。确认理解后改 artifact 时：
- 改局部段落 → 用
edit 工具 { path, oldText, newText }、不是 write 整文件覆盖（保留 git diff 干净）
- 结构性大改 → 用
write 整文件覆盖（一次写完）
判断标准：影响超过 3 段就走 write 整覆盖；3 段以内就 edit 局部。改完再调一次 submit_work（同 action_id、同 artifact_path）重新交卷。
排错清单（写失败时按这个序走）
错误：File does not exist / oldText not found
原因：你用了 edit 工具创建新 artifact。edit 只能改已存在的文件。
修法：改用 write 工具、参数从 { path, oldText, newText } 换成 { path, fileText }、fileText 是完整文件内容。
错误：Permission denied / EACCES
原因：路径不在 sandbox 允许范围。
修法：检查路径是不是 super-prompt 里给的 artifact 绝对路径、不要自己拼。如果路径正确但还是 denied、把错误内容写进下一次 assistant_message 让用户看到（这是平台 bug、不是你的锅）。
错误：path must be absolute
原因：你用了相对路径（如 ./actions/1-plan.md 或 data/tasks/.../1-plan.md）。
修法：从 super-prompt 顶部「Artifact 文件路径」段整段抄绝对路径过来、不要自己改前缀。
错误：写完了 UI 看不到 artifact
原因：路径写错地方了（写到 agent cwd 下、或仍用旧的 artifacts/0X-….md）。
修法：
- 在 agent cwd 下
read 你刚才写的路径、确认文件是不是被写到了 cwd 而不是绝对路径指定的位置
- 如果文件在 cwd 下、
delete 掉、用绝对路径重新 write 到 …/tasks/<taskId>/actions/<n>-<type>.md
- 用绝对路径
read 一次目标文件、确认内容到位、再调 submit_work
各 action 的 artifact 命名
- plan →
actions/<n>-plan.md（章节按 prompts/action-plan.md）
- build →
actions/<n>-build.md（除了写 artifact、还要 edit 业务代码）
- review →
actions/<n>-review.md（只读业务代码、不改）
- ship / custom / … →
actions/<n>-<type>.md（按对应 action prompt）
同一 task 内 n 单调递增、不按 type 分编号、不补前导 0。模板看对应 action prompt（super-prompt 里嵌入过）。
跟 build action 改业务代码的区别
build action 同时干两件事：
- 改业务代码：用
edit 改已存在的 .ts/.tsx/.vue 文件（业务代码本就存在）、新建文件用 write
- 写
actions/<n>-build.md artifact：用 write（artifact 是新建的）
不要混了——业务代码大部分用 edit、artifact 永远用 write。
跟 review action 的区别
review action 禁止改业务代码、只读 git diff + 上游 artifact、写 actions/<n>-review.md。所以 review 里你只会用一次 write（写本 action artifact）、不会有 edit 业务代码这个动作。
