--- name: zenstory description: "ZenStory(AI 辅助小说写作工作台)的 Agent API 使用说明:用 API Key 读取和管理用户在 ZenStory 中的小说项目、章节草稿、大纲、人物设定、世界观与素材,并提供关键词搜索与写作上下文。当用户提到 ZenStory、自己存放在 ZenStory 的小说项目,或需要读写其中的章节、大纲、人物、设定时使用。" metadata: display_name: "ZenStory 小说写作平台" version: "1.0.0" api_base: "https://api.zenstory.ai/api/v1" auth_method: "api_key" auth_header: "X-Agent-API-Key" auth_prefix: "eg_" rate_limit: "read=2000/hour, write=1000/hour, search=500/hour, context=500/hour" triggers: "写小说, 小说创作, 角色创建, 大纲规划, 世界观设定, write a novel, create characters, story outline, world building, draft chapters" capabilities: "project_management, file_crud, file_tree, version_history, keyword_search, writing_context" file_types: "outline, draft, character, lore, material" cli: "npx zenstory" --- # ZenStory 小说写作平台 AI 辅助的小说写作工作台,提供智能对话、文件管理、语义搜索等功能。 ## 推荐:使用 ZenStory 命令行工具(`zenstory`) 编程 Agent(Claude Code、Codex、OpenClaw 等)推荐直接使用官方 CLI 和标准 Agent Skill,无需手写 HTTP 请求: ```bash npx zenstory login # 出现 "Paste API key:" 时粘贴密钥(输入不回显,不会进入 shell 历史;本地以 0600 权限保存) npx zenstory skill install # 安装 Skill 到 Claude Code(--target codex|openclaw|<目录>) npx zenstory whoami # 检查登录状态与读写权限 ``` 请由用户本人在终端里运行登录命令并在提示时粘贴密钥,不要把密钥写在命令行参数里,也不要贴进 AI 对话。 如果密钥已经被贴进对话,请到「设置 → Agent」重新生成密钥后再登录。 ## 认证说明 所有 API 请求需要在请求头中携带有效的 API Key: ``` X-Agent-API-Key: eg_your_api_key_here ``` API Key 格式为 `eg_` 前缀加上 64 位十六进制字符。在平台设置中生成和管理 API Key。 **权限范围 (Scopes)**: - `read` - 读取项目和文件 - `write` - 创建和更新内容 ## API 端点列表 | 端点 | 方法 | 描述 | 所需权限 | |------|------|------|----------| | `/api/v1/agent/files/{file_id}` | DELETE | delete_file | write | | `/api/v1/agent/files/{file_id}` | GET | get_file | read | | `/api/v1/agent/files/{file_id}` | PUT | update_file | write | | `/api/v1/agent/files/{file_id}/move` | POST | move_file | write | | `/api/v1/agent/files/{file_id}/versions` | GET | list_file_versions | read | | `/api/v1/agent/files/{file_id}/versions/{version_number}` | GET | get_file_version | read | | `/api/v1/agent/files/{file_id}/versions/{version_number}/rollback` | POST | rollback_file_version | write | | `/api/v1/agent/projects` | GET | list_projects | read | | `/api/v1/agent/projects` | POST | create_project | write | | `/api/v1/agent/projects/{project_id}` | DELETE | delete_project | write | | `/api/v1/agent/projects/{project_id}` | GET | get_project | read | | `/api/v1/agent/projects/{project_id}` | PUT | update_project | write | | `/api/v1/agent/projects/{project_id}/files` | GET | list_files | read | | `/api/v1/agent/projects/{project_id}/files` | POST | create_file | write | | `/api/v1/agent/projects/{project_id}/writing-context` | GET | get_writing_context | read | | `/api/v1/agent/projects/{project_id}/search` | POST | search | read | ## 文件类型说明 | 类型 | 用途 | 关键字段 | |------|------|----------| | outline | 大纲,支持层级嵌套 | title, content, parent_id, metadata | | draft | 正文草稿 | title, content, parent_id, metadata | | character | 人物设定 | title, content, metadata(traits, relationships) | | lore | 世界观设定 | title, content, metadata(category) | | material | 写作素材 | title, content, metadata(source, tags) | ## 使用示例 ### 1. 获取项目列表 ```bash curl -H "X-Agent-API-Key: eg_your_key" \ "https://api.zenstory.ai/api/v1/agent/projects" ``` ### 2. 创建新项目 ```bash curl -X POST "https://api.zenstory.ai/api/v1/agent/projects" \ -H "X-Agent-API-Key: eg_your_key" \ -H "Content-Type: application/json" \ -d '{ "name": "我的科幻小说", "description": "一部关于星际旅行的科幻作品", "project_type": "novel" }' ``` ### 3. 创建章节草稿 ```bash curl -X POST "https://api.zenstory.ai/api/v1/agent/projects/{project_id}/files" \ -H "X-Agent-API-Key: eg_your_key" \ -H "Content-Type: application/json" \ -d '{ "title": "第一章:启程", "file_type": "draft", "content": "晨光透过窗帘的缝隙洒进房间..." }' ``` ### 4. 获取写作上下文 ```bash curl -H "X-Agent-API-Key: eg_your_key" \ "https://api.zenstory.ai/api/v1/agent/projects/{project_id}/writing-context?file_id={file_id}" ``` ### 5. 语义搜索 ```bash curl -X POST "https://api.zenstory.ai/api/v1/agent/projects/{project_id}/search" \ -H "X-Agent-API-Key: eg_your_key" \ -H "Content-Type: application/json" \ -d '{ "query": "主角的冒险经历", "top_k": 5 }' ``` ## 适用范围 **适用于:** 小说创作、短篇故事、剧本写作、人物设定、世界观构建、大纲规划 **不适用于:** 通用问答、代码生成、图像创作、非虚构写作、数据分析 ## 完整工作流示例 ### 工作流 1:创建新小说项目 ``` 1. POST /agent/projects → 创建新项目(响应 folders 字段列出自动创建的默认文件夹) 2. POST /agent/projects/{id}/files → 创建大纲文件 (file_type=outline, parent_id=大纲文件夹) 3. POST /agent/projects/{id}/files → 创建人物设定 (file_type=character, parent_id=角色文件夹) 4. POST /agent/projects/{id}/files → 创建世界观设定 (file_type=lore, parent_id=设定文件夹) 5. GET /agent/projects/{id}/writing-context → 获取写作上下文 6. POST /agent/projects/{id}/files → 创建章节 (file_type=draft, parent_id=正文文件夹, order=章节序号) ``` 默认文件夹 id 可预测:`{project_id}-lore-folder`、`-character-folder`、`-material-folder`、`-outline-folder`、 `-draft-folder`(剧本项目为 `-script-folder`)。已有文件可用 `POST /agent/files/{file_id}/move` 移入文件夹。 ### 工作流 2:续写已有章节 ``` 1. GET /agent/projects/{id}/files?file_type=draft&fields=id,title → 列出草稿 2. GET /agent/files/{file_id} → 读取当前内容 3. GET /agent/projects/{id}/writing-context?file_id={file_id} → 获取相关上下文 4. POST /agent/projects/{id}/search query="角色关系" → 搜索人物关系 5. PUT /agent/files/{file_id} → 更新草稿内容 ``` ### 工作流 3:撤销一次修改 ``` 1. GET /agent/files/{file_id}/versions → 版本历史(最新在前,不含正文) 2. GET /agent/files/{file_id}/versions/{n} → 查看第 n 版正文 3. POST /agent/files/{file_id}/versions/{n}/rollback → 恢复到第 n 版(历史不丢;版本额度未满时生成一个新版本) ``` ## 错误处理 API 返回标准化的错误响应格式: ```json { "detail": "错误描述信息", "error_code": "ERROR_CODE", "request_id": "req_xxx" } ``` 常见错误码: | 错误码 | HTTP 状态码 | 描述 | |--------|-------------|------| | `AUTH_UNAUTHORIZED` | 401 | 缺少认证信息 | | `AUTH_TOKEN_INVALID` | 401 | API Key 无效 | | `AUTH_TOKEN_EXPIRED` | 401 | API Key 已过期 | | `NOT_AUTHORIZED` | 403 | 权限不足 | | `NOT_FOUND` | 404 | 资源不存在 | | `VALIDATION_ERROR` | 422 | 请求参数验证失败 | | `RATE_LIMIT_EXCEEDED` | 429 | 请求频率超限 | ## 速率限制 按端点类型分级限速: | 类型 | 限制 | |------|------| | 读取 (read) | 2000/hour | | 写入 (write) | 1000/hour | | 搜索 (search) | 500/hour | | 上下文 (context) | 500/hour | --- 如有问题或建议,请联系技术支持或访问 API 文档:https://api.zenstory.ai/docs