Skip to content

docs(filesystem): document write() mode=create (#1608)#1623

Merged
qin-ctx merged 2 commits intovolcengine:mainfrom
r266-tech:docs/content-write-mode-create-1608
Apr 22, 2026
Merged

docs(filesystem): document write() mode=create (#1608)#1623
qin-ctx merged 2 commits intovolcengine:mainfrom
r266-tech:docs/content-write-mode-create-1608

Conversation

@r266-tech
Copy link
Copy Markdown
Contributor

Summary

PR #1608 added mode=\"create\" to POST /api/v1/content/write (plus ov write --mode create CLI flag), with a .md/.txt/.json/.yaml/.yml/.toml/.py/.js/.ts extension whitelist and 409 Conflict on existing paths. docs/en/api/03-filesystem.md and docs/zh/api/03-filesystem.md still describe write() as strictly an update operation, so consumers reading the HTTP API reference cannot discover the new capability without reading openviking/storage/content_write.py.

Changes

Mirror edits in EN + ZH filesystem API docs, scoped to the write() section:

  • Section intro: mention mode=\"create\" as an alternative to updating.
  • Parameter table mode row: values extended to replace, append, or create.
  • Notes: replace the single "only existing files" bullet with a two-bullet pair — semantics split (replace/append need existing file, create returns 409 on existing) + the extension whitelist plus automatic parent-directory creation.

No CLI example changes (stays a replace example to avoid scope creep); the CLI section can be expanded in a follow-up if maintainers prefer. No code changes.

Verification

@github-actions
Copy link
Copy Markdown

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis ✅

1608 - Fully compliant

Compliant requirements:

  • Mirror edits in EN + ZH filesystem API docs for the write() section
  • Update section intro to mention mode="create"
  • Extend mode parameter values to include create
  • Add notes about mode semantics and create extension whitelist
⏱️ Estimated effort to review: 1 🔵⚪⚪⚪⚪
🏅 Score: 95
🧪 No relevant tests
🔒 No security concerns identified
✅ No TODO sections
🔀 No multiple PR themes
⚡ Recommended focus areas for review

Documentation Inconsistency

The uri parameter description still says "Existing file URI", which is incorrect for mode="create" where the file does not exist yet.

| uri | str | Yes | - | Existing file URI |
Documentation Inconsistency

The uri parameter description still says "已存在文件的 URI", which is incorrect for mode="create" where the file does not exist yet.

| uri | str || - | 已存在文件的 URI |

@github-actions
Copy link
Copy Markdown

PR Code Suggestions ✨

No code suggestions found for the PR.

@qin-ctx qin-ctx merged commit be0a0c9 into volcengine:main Apr 22, 2026
2 checks passed
@github-project-automation github-project-automation Bot moved this from Backlog to Done in OpenViking project Apr 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

2 participants