From 6cbe2bd7d2fcaaaa1c04de87912ce6ec29d3ddfa Mon Sep 17 00:00:00 2001 From: Linghong Date: Mon, 3 Aug 2026 10:39:54 +0000 Subject: [PATCH] =?UTF-8?q?=E5=A4=96=E9=83=A8=20API=20skill=20=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E5=90=8C=E6=AD=A5=20style=20=E7=9A=84=E6=8F=90?= =?UTF-8?q?=E7=A4=BA=E8=AF=8D=E6=B3=A8=E5=85=A5=E8=AF=AD=E4=B9=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit requests-and-outputs.md 把 style 描述为只控制 deterministic post-processing， 缺了本分支加的另一半——pixelArt 会在发给 provider 的提示词末尾追加一行约束。 是文档漂移不是遗漏：OpenAPI 的两处 schema 一直是对的，连子句都写了；master 把 api-selection.md 拆成四篇时是从注入之前的版本重写的。我上轮合并只 grep 了 旧错误说法有没有复活，确认没有就收工——验证旧错误的缺席不等于验证新事实的在场。 改动限于三行，与 OpenAPI 对齐，不新造措辞。刻意不复制子句字面文本：Rust 常量 是真值源、OpenAPI 已复制一份，再抄第三份就是把同一事实摊到三处，这次漂移正是 这么发生的。文档改为指向 OpenAPI 并写明是刻意不复制。 Co-Authored-By: Claude Opus 5 --- .../references/requests-and-outputs.md | 6 +++--- docs/project-memory/shared-memory/decision-log.md | 10 ++++++++++ 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/.codex/skills/genarrative-external-editor-api/references/requests-and-outputs.md b/.codex/skills/genarrative-external-editor-api/references/requests-and-outputs.md index cbd26dfa7..fe62ee1ee 100644 --- a/.codex/skills/genarrative-external-editor-api/references/requests-and-outputs.md +++ b/.codex/skills/genarrative-external-editor-api/references/requests-and-outputs.md @@ -138,10 +138,10 @@ Carry the current art spec in `generationInputs.artSpec` and reflect important c } ``` -The top-level `style` field is not the art spec's visual-style prose. It controls deterministic post-processing: +The top-level `style` field is not the art spec's visual-style prose. It appends a short server-side clause to the prompt sent to the provider and enables deterministic post-processing: -- Omitted, `null`, empty string, or `"none"`: disable post-processing without warning. -- `"pixelArt"`: enable pixel-art snapping for ordinary image generation, `kind: "character"`, and icon spritesheet generation. +- Omitted, `null`, empty string, or `"none"`: no clause is appended and no post-processing runs, without warning. +- `"pixelArt"`: append one short pixel-art line to the end of the prompt sent to the provider, and enable pixel-art snapping, for ordinary image generation, `kind: "character"`, and icon spritesheet generation. The line is appended, not substituted — the rest of your prompt is unchanged. For the exact per-kind wording, read the `style` field description in the OpenAPI document; it is the contract, and this guide deliberately does not copy it. - Unknown strings, or `"pixelArt"` on unsupported kinds such as `spec`, `quick-edit`, `ui-design`, or `publication-material`: continue without style processing and return `warning.code: "unsupported-image-style"`. - Non-string JSON values: malformed request, HTTP `400`. diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 2f50a2e5b..4b8aa16d1 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -6126,3 +6126,13 @@ - 处置：撤回 `useMemo` + `useRef` 的改动，回到更简单的数组依赖版本——既然简单版本本来就正确，多出来的间接层没有收益。用例保留，但注释改写为它**实际证明**的性质：判定必须留在 effect 体里；将来若把它挪出去（例如只在定时器回调里判定），这条不变式才会真的失效，用例届时会变红。 - 记这一条是因为过程本身有价值：先假设、再写用例、用例证伪假设、据此撤回改动。若跳过验证直接保留那次「修复」，就会在没有缺陷的地方永久留下一层多余的间接。本次会话里同类错误（凭推断得出结论而不验证）已出现多次，这次是验证挡住了。 - 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。 + +## 2026-08-03 外部 API skill 文档同步 style 的提示词注入语义 + +- 缺陷：`references/requests-and-outputs.md` 把 `style` 描述为「只控制 deterministic post-processing」，缺了本分支给它加的另一半语义——`pixelArt` 会在发给 provider 的提示词末尾追加一行像素风约束。 +- 归因是文档漂移而非遗漏：`docs/openapi/genarrative-external-v1.openapi.json` 的两处 schema **一直是对的**，连具体子句都写了。master 的 `c00dd099e` 把 `api-selection.md` 拆成四篇新参考文档时是从注入之前的版本重写的，于是 skill 文档退回旧语义，而 OpenAPI 保持正确。 +- 我上一轮合并时的核查不到位：只 grep 了「`byte-for-byte` 那个错误说法有没有复活」，确认没有就收工。**验证旧错误的缺席不等于验证新事实的在场**，两者要分别查。 +- 决策：让 skill 文档与 OpenAPI 对齐，措辞不新造。改动限于三行——说明它同时追加提示词子句与启用后处理、`none` 一档不追加也不后处理、`pixelArt` 一档追加一行且是追加而非替换。 +- 刻意不复制子句字面文本：Rust 常量是真值源，OpenAPI 已复制一份，skill 文档再抄第三份就是把同一事实摊到三处——这次漂移正是这么发生的，只是方向相反。文档改为指向 OpenAPI 并写明「本指南刻意不复制」，让下一个读到的人知道那是有意为之而非遗漏。 +- 校验面已确认：这批文档由 `external_skill_api.rs` / `external_mcp.rs` 以 `include_str!` 编译期内联，SHA 在运行时从内容算出、测试只断言「算出的与返回的一致」，没有钉死具体摘要，改文档无需同步任何清单。api-server 700 通过 / 3 失败（`wallet_refund_outbox` 本机环境失败，与基线一致）。 +- 关联文档：`docs/openapi/genarrative-external-v1.openapi.json`。