[Shinku-Chen]

Description

中文说明

让手工 Markdown 创建接口在首次入库时同时保存自定义元数据，调用方可以一次提交正文和来源属性，减少一次后续属性更新请求。

接口

POST /api/v1/knowledge-bases/{id}/knowledge/manual

新增可选请求字段 custom_metadata，与正文一起写入同一条 Knowledge 的首次 INSERT：

{
  "title": "版本指南",
  "content": "完整的 Markdown 正文。",
  "status": "publish",
  "custom_metadata": {
    "source_id": "9007199254740993",
    "version": "1"
  }
}

行为与限制

• 复用现有自定义元数据校验：最多 20 个字段；字段名不能为空或纯空白，最多 64 字节；值只支持字符串、数字、布尔或 null，转换为字符串后最多 1000 字节；不接受嵌套对象或数组。
• 创建参数不合法时，在落库或任务入队之前返回 HTTP 400。
• 省略字段时保持既有行为；创建时显式传 null 归一为空对象。原始数字 JSON 保存时不重新编码；大整数业务 ID 建议使用字符串，避免后续文本渲染精度问题。
• draft/publish 的默认值和异步处理语义保持不变。需要直接处理时显式传 status: "publish"；HTTP 成功不等于索引已经完成。
• custom_metadata 与内部手工正文 metadata 分开保存，不拼入正文向量化输入；已有摘要和上下文使用元数据的行为保持不变。
• 本 PR 只扩展创建能力，现有 manual PUT 和通用属性 PUT 的行为保持不变，没有新增拒绝逻辑或元数据编辑行为。
• 同步创建 API 文档与 Swagger。不新增路由、表或迁移，不改 UI、模型配置及后台更新并发行为。

English

Manual Markdown creation previously ignored custom_metadata, requiring callers to create the knowledge first and send a separate property update. This change accepts optional custom metadata on POST /api/v1/knowledge-bases/{id}/knowledge/manual and stores it in the same initial Knowledge insert as the document body.

• Reuse the existing flat-metadata validation: at most 20 fields, nonblank keys up to 64 bytes, scalar values (string, number, boolean or null) whose string representation is at most 1000 bytes. Invalid creation input returns HTTP 400 before persistence or task enqueue.
• Omitted metadata preserves existing behavior; explicit null is normalized to an empty object on creation. Raw JSON numbers are stored without re-encoding; large identifiers should be strings for downstream text rendering.
• Draft/publish defaults and asynchronous processing remain unchanged. Custom metadata stays separate from internal Markdown metadata and embedding input; existing summary/context behavior is preserved.
• Existing manual body-update behavior and generic property-update validation/null semantics remain unchanged.
• Update the creation API documentation and Swagger schema. No new routes, migrations, UI, deployment or background-update concurrency changes.

Compatibility: this change only adds metadata persistence to manual creation. It introduces no new rejection or metadata-editing behavior on the existing update routes.

Example creation body:

{
  "title": "Release guide",
  "content": "# Guide\nFull document body",
  "status": "publish",
  "custom_metadata": {"source_id": "9007199254740993", "version": "1"}
}

Assisted-by: Cindy (https://cindy.app)

Type of Change

• 🐛 Bug fix
• ✨ New feature
• 💥 Breaking change
• 📚 Documentation update
• 🎨 Refactor
• ⚡ Performance improvement
• 🧪 Test
• 🔧 Configuration / Build / CI

Related Issue

N/A — no upstream issue is associated with this change.

Testing

中文验证摘要

已验证 HTTP JSON 绑定、非法参数在副作用前返回 400、字段数量/字节限制、省略/null/空对象、draft/publish 的 SQLite 落库与读回、大整数原始 JSON 保存，以及原有正文更新、通用元数据更新和索引内容边界。Swagger 契约测试及差异范围 lint 通过。单 PR 验证使用隔离 SQLite 和假队列，未调用真实模型或部署知识库；PostgreSQL 与完整 make 检查未执行，既有 Python 环境依赖用例显式排除。

English

Passed:

go test ./internal/types ./internal/application/repository \
  ./internal/application/service ./internal/handler ./docs \
  -skip '^TestSkillPythonVerifier$' -count=1
golangci-lint run --new-from-rev=origin/main \
  --max-issues-per-linter=0 --max-same-issues=0 ./...

Focused tests cover HTTP JSON binding and validation-error propagation, metadata limits (including multibyte byte limits), rejection before side effects, omitted/null/empty metadata, draft/publish SQLite persistence, raw large-number preservation, body-only update preservation, and existing metadata/index-content behavior. A separate regression locks down the generic property's existing null handling and invalid-input rejection contract. Publish tests use a fake queue; no models or deployed knowledge bases are invoked.

Swagger was generated with the repository-pinned swag v1.16.6. Only the new request property is retained, avoiding unrelated generator ordering changes; the Swagger contract tests pass. Changed Go files are formatted, and diff-scoped golangci-lint v2.12.2 reports zero new findings.

TestSkillPythonVerifier is the existing environment-dependent Python verifier excluded from the affected-package command. Full make fmt, make lint, make test, real PostgreSQL, provider calls and deployment are NOT_RUN. Validation is scoped to the changed feature and affected packages.

Checklist

• git diff --check origin/main...HEAD passes
• Changed source files are formatted
• Targeted tests for the changed packages/components pass
• Diff-scoped lint passes where applicable (for Go: golangci-lint run --new-from-rev=origin/main ./...)
• Full-repository checks were run, or any unrelated/environment-dependent failures are documented above
• Self-reviewed the code
• Added/updated tests covering the change
• Updated related documentation (README, website-docs/, Swagger annotations, etc.)
• Breaking changes are clearly called out in the description above

Screenshots / Recordings

N/A — no UI changes.