feat(content-write): 支持 mode=create 创建新文件

[A0nameless0man]

Summary

为 POST /api/v1/content/write 新增 mode="create" 支持创建新文件，补齐 HTTP API 层的文件创建能力缺口。

背景：当前 content/write 端点要求目标文件已存在，不存在则返回 404。底层 VikingFS.write_file() 已支持创建（自动 _ensure_parent_dirs），但 HTTP 层未暴露。这阻塞了 MCP 插件 memwrite 等需要通过 API 创建新文件的消费方。

Changes

Python 服务层（openviking/storage/content_write.py）

• _validate_mode() 接受 "create" 值
• 新增 _CREATE_ALLOWED_EXTENSIONS 白名单（.md/.txt/.json/.yaml/.yml/.toml/.py/.js/.ts），防止创建二进制文件
• 新增 _validate_create_extension() 扩展名校验
• 新增 _create_and_write() 方法：自动创建父目录 → 写入文件 → 语义刷新
• write() 中 create 路径在 _safe_stat 之前分流，文件已存在时返回 HTTP 409

Rust CLI（crates/ov_cli/）

• ov write 新增 --mode 参数（replace | append | create），与 --append 互斥

测试

• 服务层 9 个 test_create_mode_* 测试（使用 FakeVikingFS 隔离）
• API 层 6 个测试：正常创建、文件已存在→409、非法扩展名→400、写后读验证等
• 0 个回归（4 个预存失败与本次变更无关）

Behavior Matrix

mode	文件存在	行为
replace（默认）	✅	覆写（不变）
replace	❌	404 NotFoundError（不变）
append	✅	追加（不变）
append	❌	404 NotFoundError（不变）
create	✅	409 AlreadyExistsError
create	❌	创建文件 + 语义刷新

Backward Compatibility

• mode 默认值仍为 "replace"，不传参行为完全不变
• 无 breaking change，纯增量扩展

Commits

• 83bb014 添加 mode=create 服务层和 HTTP API 测试（TDD Red）
• 133b5dd 实现 mode=create 文件创建功能
• 7f82b13 ov write 支持 --mode 参数
• 6142bdb 清理测试文件中的过时 TDD 注释
• eab0616 修复 _safe_stat 未正确处理 AGFSNotFoundError 的问题
• 5b41dff 添加 create mode 写后读集成测试

Related

• feat(opencode-plugin): add memwrite, memimport tools and viking:// URI interception hook #1474 — opencode memory plugin memwrite 工具（创建能力的消费方）
• RFC: dedicated agent content API for stable named memory carriers #1251 — RFC: dedicated agent content API
• feat(agent-content): add stable memory carrier API #1427 — agent-content 端点（agent scope only）
• feat(memory): add POST /api/v1/memories for direct memory creation #1577 — memories 端点（memory files only）
• feat(content): add POST /api/v1/content/write-batch for bulk memory writes #1461 — content/write-batch 批量写入

Closes #1585

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 4 🔵🔵🔵🔵⚪

🏅 Score: 85

🧪 PR contains tests

🔒 No security concerns identified

✅ No TODO sections

🔀 Multiple PR themes Sub-PR theme: Add mode=create to content write API Relevant files: openviking/server/routers/content.py openviking/storage/content_write.py tests/server/test_api_content_write.py tests/server/test_content_write_service.py Sub-PR theme: Add --mode flag to Rust CLI write command Relevant files: crates/ov_cli/src/commands/content.rs crates/ov_cli/src/handlers.rs crates/ov_cli/src/main.rs

⚡ Recommended focus areas for review Missing Import Missing import of 'os' module, which is used in _validate_create_extension(). This will cause a NameError when mode=create is used. from typing import Any, Dict, Optional

[github-actions]

PR Code Suggestions ✨

No code suggestions found for the PR.

[github-actions]

PR Code Suggestions ✨

No code suggestions found for the PR.

[A0nameless0man]

Closes #1585