文档中心

向量数据库VikingDB

文件内容（File Contents）

write-写入文件内容

概述

/api/v1/content/write 接口用于创建、替换或追加文本内容，并触发相关语义与向量刷新。

mode 分为三种类型：replace 用于内容替换、append 用于内容追加、create 仅用于创建新文件，目标路径已存在时返回 409 Conflict。
create 只允许以下文本类扩展名：.md、.txt、.json、.yaml、.yml、.toml、.py、.js、.ts。父目录会自动创建。
不允许直接写入派生语义文件：.abstract.md、.overview.md
文件内容会在 API 返回前完成更新；wait 只控制是否等待语义/向量刷新完成。

前置条件

完成 "数据库访问使用说明" 页面的 API Key 获取后，可调用本接口写入内容。

请求接口

URI	/api/v1/content/write	统一资源标识符
请求方法	POST	客户端请求类型
请求头	Content-Type: application/json	请求消息类型
请求头	Authorization: Bearer {API Key}	Bearer Token 鉴权

请求参数

参数	类型	必选	默认值	备注
uri	string	是	—	完整文件 URI，例如 viking://resources/docs/api.md。目录不支持；缺失父目录会自动创建（仍受权限限制）。
content	string	是	—	文本内容。replace 为完整新正文，append 为追加片段，create 为新文件正文；不会自动添加换行。不接收二进制或 content_base64 字段。
mode	string	否	replace	replace、append 或 create。replace/append 在目标不存在时创建文件；create 仅创建，目标已存在返回 ALREADY_EXISTS（409）。详见下方内容写入模式。
processing_mode	string	否	semantic_and_vectors	semantic_and_vectors：按处理策略更新语义与向量；vectors_only：不重新生成目录语义摘要/概览，仅进行相关向量更新。
tags	array 或 null	否	null	检索标签数组，每项为 k=v。省略或 null 表示不修改既有标签；传 [] 与省略不同，具体行为由 tag_mode 决定。
tag_mode	string	否	replace	replace：以本次 tags 替换既有标签；append：按 key 合并，本次同 key 的新 value 覆盖旧 value。与内容 mode 相互独立。

内容写入模式

mode	目标存在	目标不存在
replace	用 content 替换正文。	创建文件并写入 content。
append	追加 content，不自动补换行。	从空文件开始创建并写入 content。
create	返回 ALREADY_EXISTS（409），不覆盖。	创建并写入；扩展名仅允许 .md、.txt、.json、.yaml、.yml、.toml、.py、.js、.ts。

标签格式和更新规则
每项标签包含且仅包含一个等号，等号两侧均非空，例如 team=platform、env=prod。服务端对整条标签去除首尾空白并转小写。

请求	既有标签示例	处理后的标签
不传 tags，或 tags=null	["team=platform", "env=dev"]	保持原标签。
tags=["env=prod"]，tag_mode=replace	["team=platform", "env=dev"]	["env=prod"]，不保留 team。
tags=["env=prod"]，tag_mode=append	["team=platform", "env=dev"]	["team=platform", "env=prod"]。
tags=[]，tag_mode=replace	["team=platform", "env=dev"]	[]，清空标签。
tags=[]，tag_mode=append	["team=platform", "env=dev"]	保持原标签。

响应消息

字段	类型	参数说明
status	string	ok 或 error。
result	object	成功时的写入及刷新结果。
result.uri	string	写入文件的 Viking URI。
result.root_uri	string	本次关联处理的资源/上下文根 URI，具体范围由目标位置确定。
result.context_type	string	上下文类型，例如 resource。
result.mode	string	请求的内容写入模式。replace/append 自动创建时仍保留请求模式。
result.written_bytes	int	本次 content 的 UTF-8 字节数；append 时不是追加后文件总大小。
result.content_updated	bool	正文已完成写入；成功结果为 true，不代表索引一定就绪。
result.semantic_status	string	语义处理状态：queued、complete、deferred、skipped 或 failed，取决于实际处理路径。
result.vector_status	string	向量处理状态：queued、complete、skipped 或 failed。
result.queue_status	object 或 null	等待后的相关队列结果；不等待时可为 null。包含 Semantic、Embedding 等处理子项，按实际结果返回。
result.queue_status.{子项}.processed / requeue_count / error_count / errors	int / int / int / array	处理数、重新排队数、错误数、错误详情；是任务统计，不等同于文件数。
error.code / message / details	string / string / object	失败时的错误码、说明与可选详情。成功时 error 可为空或省略。

常见错误码：

HTTP 状态码	error.code	说明与处理
401	UNAUTHENTICATED	缺少或无效 API Key。
403	PERMISSION_DENIED	目标无写入权限或路径不允许直接写入；检查权限或改用专用接口。
400	INVALID_ARGUMENT / INVALID_URI	目标为目录、模式不支持、create 扩展名不允许、试图创建派生摘要/概览、tag_mode 无效或请求体含未知字段等。
409	ALREADY_EXISTS	create 的目标已存在；更换 URI，或明确使用 replace/append。
409	CONFLICT / WRITE_CONFLICT	并发写入或锁冲突；回读当前状态后处理。
504	DEADLINE_EXCEEDED	等待处理超时，正文可能已更新；回读并核对后续处理，避免重复 append。
500	PROCESSING_ERROR / EMBEDDING_FAILED / VLM_FAILED / REFRESH_FAILED	后续处理失败，具体码以响应为准；先确认已写入正文及队列错误，再修复配置或重试刷新。

完整示例

示例一：替换或创建正文，并替换标签

curl -X POST "https://xxx/api/v1/content/write" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-key" \
  -d '{
    "uri": "viking://resources/docs/api.md",
    "content": "# API\n\nHello.\n",
    "mode": "replace",
    "tags": ["team=platform", "env=prod"],
    "tag_mode": "replace",
    "processing_mode": "semantic_and_vectors"
  }'

执行成功返回：

{
  "status": "ok",
  "result": {
    "uri": "viking://resources/docs/api.md",
    "root_uri": "viking://resources/docs",
    "context_type": "resource",
    "mode": "replace",
    "written_bytes": 14,
    "content_updated": true,
    "semantic_status": "complete",
    "vector_status": "complete",
    "queue_status": {
      "Semantic": {"processed": 1, "requeue_count": 0, "error_count": 0, "errors": []},
      "Embedding": {"processed": 1, "requeue_count": 0, "error_count": 0, "errors": []}
    }
  }
}

示例二：追加正文并按 key 合并标签

curl -X POST "https://xxx/api/v1/content/write" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-key" \
  -d '{
    "uri": "viking://resources/docs/api.md",
    "content": "\n## Changes\nUpdated.\n",
    "mode": "append",
    "tags": ["env=staging", "release=v0418"],
    "tag_mode": "append",
    "processing_mode": "vectors_only"
  }'

参数、示例与排错补充

可选参数缺少默认行为：timeout 仅在 wait=true 时生效；不传或为 null 时使用服务端默认等待时限，wait=false 时忽略。
数值边界限制缺失：timeout 单位为秒，取值范围 [0.1, 300]，且仅在 wait=true 时生效。
返回参数描述不完整：返回结构采用统一包装：status 为 string，result 为 object/array/null，telemetry 为 object/null，error 为 object/null；业务子字段的类型和层级与成功示例保持一致。
返回参数描述不完整：semantic_status 和 vector_status 取值为 pending、processing、complete 或 failed，分别表示等待、处理中、完成和失败。
请求示例与请求参数说明不符：请求示例统一使用 Authorization: Bearer <API_KEY>，与请求头参数表保持一致。
标识型参数缺少获取规则：uri 使用 viking://<namespace>/<path> 格式；从创建/导入资源响应的 result.uri，或 ls、tree、find、grep 的结果中复制。
自定义输入参数缺少格式限制：content 按 UTF-8 编码，单次请求最大 10 MiB；超过限制时应拆分文件或分批写入。
依赖或互斥参数说明不全：timeout 仅在 wait=true 时生效；等待超时时内容写入不会回滚，接口返回当前 semantic_status/vector_status，调用方可稍后查询状态。
错误码原因或处理建议缺失：错误处理建议：UNAUTHENTICATED：检查并重新生成 API Key；PERMISSION_DENIED：确认 Agent/账号对目标 URI 有权限；INVALID_ARGUMENT：按参数表检查类型、范围和必填项；NOT_FOUND：确认 URI 或资源 ID 存在；INTERNAL：记录 request ID 后重试，持续失败时提交工单。

最近更新时间：2026.09.22 22:12:21

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

示例一：替换或创建正文，并替换标签 #

示例二：追加正文并按 key 合并标签 #

参数、示例与排错补充 #

示例一：替换或创建正文，并替换标签

示例二：追加正文并按 key 合并标签

参数、示例与排错补充