为 Apify Actor 生成输出…

当需要为 Apify Actor 创建或更新 dataset_schema.json、output_schema.json、key_value_store_schema.json 并接入 actor.json 时使用。

适用场景

解决思路

1. 先创建包含所有阶段的 todo 列表，再定位包含 actor.json 的 .actor/ 目录并读取 actor.json 了解配置。
2. 检查 dataset_schema.json、output_schema.json、key_value_store_schema.json 是否已存在。
3. 在仓库中搜索其他 .actor/ 目录或 schema 文件（如 **/dataset_schema.json、**/output_schema.json、**/key_value_store_schema.json），学习并沿用其描述风格、字段命名、示例格式和整体结构。
4. 查找所有向 dataset 推送数据的位置：JavaScript/TypeScript 搜索 Actor.pushData(、dataset.pushData(、Dataset.pushData(；Python 搜索 Actor.push_data(、dataset.push_data(、Dataset.push_data(。
5. 查找所有写入 key-value store 的位置：JavaScript/TypeScript 搜索 Actor.setValue(、keyValueStore.setValue(、KeyValueStore.setValue(；Python 搜索 Actor.set_value(、key_value_store.set_value(、KeyValueStore.set_value(。
6. 查找输出类型定义并直接复用：TypeScript 查找 src/types/、src/types/output.ts 中的输出接口/类型；Python 查找 TypedDict、dataclass 或 Pydantic 模型，以现有字段名、类型和 docstring 为准，不要另建并行定义。
7. 检查代码库中已有的共享 schema 工具或辅助函数（用于 schema 生成或校验），复用而非新写逻辑。
8. 若 actor.json 中存在内联的 storages.dataset 或 storages.keyValueStore 配置，记录下来以便迁移。
9. 向用户展示发现结果：所有 dataset 输出字段、key-value store 键、类型及其来源。
10. 生成 dataset_schema.json：顶层包含 actorSpecification、fields（$schema 为 draft-07、type 为 object、properties 含全部输出字段、required 为空数组、additionalProperties 为 true）和 views。
11. fields.properties 必须包含 Actor 能输出的每一个字段，而不只是 overview 视图展示的字段；views 只是选取子集用于展示。
12. 每个字段都设置 "nullable": true，且每个带 nullable 的字段必须同时有 "type"（AJV 要求）。
13. 顶层 fields 对象以及 properties 中每个嵌套对象都必须同时包含 "additionalProperties": true 和 "required": []。
14. 每个字段都要有 "description" 和 "example"，示例值必须匿名化，不得使用真实用户 ID、用户名或个人信息。
15. 按字段类型套用模式：string、number、boolean、array（含 items）、嵌套 object（含 properties、required、additionalProperties）、enum、联合类型（如 type 为 ["object", "string"]）。
16. 示例值使用真实但通用的值并遵循平台 ID 格式约定：ID 匹配平台格式与长度，用户名用 exampleuser/sampleuser123，显示名用 Example Channel/Sample Author，URL 用平台标准格式加假 ID，日期用 ISO 8601（如 2025-01-15T12:00:00.000Z），文本用通用描述性文字。
17. views 中 transformation.fields 列出 8–12 个最重要字段（顺序即 UI 列顺序），display.properties 为每个 overview 字段配置 label 和 format，可用格式包括 text、number、date、link、boolean、image、array、object。
18. 若 Phase 1 未发现除默认 INPUT 之外的 setValue/set_value 调用，则跳过 key_value_store_schema.json 生成。
19. 生成 key_value_store_schema.json：包含 actorKeyValueStoreSchemaVersion、title、description 和 collections。
20. 按 key 模式对 setValue/set_value 调用分组识别 collections：固定键（如 RESULTS、summary）用 "key"，带前缀的动态键（如 screenshot-${id}、f"image-{name}"）用 "keyPrefix"，二者不可同时使用。
21. 每个 collection 可配置 title（必填）、description、key 或 keyPrefix、contentTypes（限制 MIME 类型，如 ["image/jpeg"]、["application/json"]）、jsonSchema（用于校验 application/json 内容的 draft-07 schema）。
22. 生成 output_schema.json：包含 actorOutputSchemaVersion、title、description 和 properties；dataset 属性使用 template "{{links.apiDefaultDatasetUrl}}/items"。
23. output_schema.json 中每个 property 必须包含 "type": "string"（Apify 约定，meta-validator 拒绝缺少 type 或使用 "type": "object"）。
24. 若生成了 key_value_store_schema.json，在 output_schema.json 中增加 files 属性，template 为 "{{links.apiDefaultKeyValueStoreUrl}}/keys"。
25. 可使用模板变量：{{links.apiDefaultDatasetUrl}}、{{links.apiDefaultKeyValueStoreUrl}}、{{links.publicRunUrl}}、{{links.consoleRunUrl}}、{{links.apiRunUrl}}、{{links.containerRunUrl}}、{{run.defaultDatasetId}}、{{run.defaultKeyValueStoreId}}。
26. 更新 actor.json：添加或更新 storages.dataset 为 "./dataset_schema.json"；若生成了 key-value store schema，添加 storages.keyValueStore 为 "./key_value_store_schema.json"；添加或更新 output 为 "./output_schema.json"。
27. 若 actor.json 原本有内联的 storages.dataset 或 storages.keyValueStore 对象，将其内容迁移到对应 schema 文件，并把内联对象替换为文件路径字符串。
28. 按检查清单校验：所有输出字段都在 fields.properties 中；每个字段有 nullable: true；顶层 fields 对象和每个嵌套对象都有 additionalProperties: true 和 required: []；每个字段有 description 和 example；示例已匿名化；带 nullable 的字段都有 type；views 列出 8–12 个字段且格式正确；output_schema.json 每个 property 有 "type": "string"；key-value store 的 collections 覆盖所有 setValue/set_value 调用且每个 collection 只用 key 或 keyPrefix 之一；actor.json 引用了所有生成的 schema 文件；字段名与代码中的实际键一致（camelCase/snake_case 一致）；遵循仓库已有 schema 约定；字段尽可能来自已有类型定义。
29. 在写入文件前把生成的 schema 展示给用户审阅。
30. 最后汇报：创建或更新的文件、dataset schema 字段数、key-value store collections 数（若生成）、overview 视图选中的字段、需要用户澄清的字段（类型模糊、可空性不明），以及建议的后续步骤（用 apify run --user-agent apify-agent-skills/apify-generate-output-schema 本地测试，在 Console 验证 output 标签页）。

适用边界 · 注意事项

• Actor 不使用 Apify 平台或不需要在 Apify Console 展示运行结果时。
• 无法访问 Actor 源码、无法确认实际 pushData/setValue 调用时（不应猜测字段）。