接口基本信息
- 名称：长文生成流水线 RPC 服务（LongFormGenRPC）
- 版本：v1.0.0
- 协议类型：JSON-RPC 2.0 over HTTPS（Content-Type: application/json）
- 统一端点：POST https://api.example.com/rpc
- 鉴权：HTTP Header Authorization: Bearer （OAuth2 或等效机制）
- 幂等策略：所有写操作支持 idempotency_key（字符串，最长 128 字符），服务在相同 key 与等价参数下返回同一结果；默认保留窗口 24 小时
- 时区与时间格式：ISO 8601（UTC），示例：2025-11-13T06:20:30Z
- 资源标识符：使用 UUIDv4（draft_id、version_id、job_id、segment_id、node_id 等）
通用数据结构（供各方法引用）
- instruction_set（对象）
- outline（数组[OutlineNode]）：文档结构树
- OutlineNode（对象）
- node_id（字符串，必填）：结构节点稳定 ID（UUID 或业务唯一）
- type（枚举，必填）：section|subsection|chapter|appendix|figure|table
- title（字符串，必填，1-200）
- children（数组[OutlineNode]，可选）
- requirements（对象，可选）：min_words（整数）、max_words（整数）、must_include_terms（数组[字符串]）
- tone（字符串，必填，1-100）：语气基调（示例：专业且清晰）
- persona（对象，必填）：role（字符串）、experience（字符串）、industry（字符串，可选）
- glossary（数组[对象]，可选）：term（字符串，必填）、definition（字符串，必填）
- banned_terms（数组[字符串]，可选）
- references（数组[对象]，可选）：label（字符串）、url（字符串，必须为 https://）、accessed_at（时间，可选）
- compliance_points（数组[对象]，可选）：code（字符串）、description（字符串）、severity（枚举：low|medium|high）
- generation_options（对象）
- language（枚举，必填）：zh-CN|en-US 等
- output_format（枚举，必填）：markdown|html|json-structure
- citation_style（枚举，必填）：numeric|author-year|footnote
- chart_placeholder_style（枚举，必填）：mermaid|alt-text|table-schema
- segment_strategy（对象，必填）
- type（枚举，必填）：by_outline_node|fixed_length
- max_tokens_per_segment（整数，必填，100-4000）
- fixed_length_chars（整数，可选，当 type=fixed_length）
- compliance_mode（枚举，必填）：strict|lenient
- on_violation（枚举，必填）：block|warn|auto_replace
- locator（对象）：内容片段定位器
- one_of：node_id（字符串）|path（字符串，JSONPath 风格，如 $.chapters[2].sections[0]）|anchor_label（字符串）
- selection（枚举，必填）：title|content|all
- range_end（对象，可选）：用于范围选取，结构同 locator
- citation（对象）：marker（字符串）、reference_label（字符串）、url（字符串）
- chart_placeholder（对象）：placeholder_id（字符串）、type（枚举：diagram|table|figure）、style（枚举同 chart_placeholder_style）、spec（字符串）
- compliance_violation（对象）：term（字符串）、location（locator）、severity（枚举）、suggestion（字符串）
- audit_entry（对象）：audit_id（字符串）、timestamp（时间）、actor（字符串）、operation（字符串）、status（枚举：success|failed）、request_id（字符串）、notes（字符串）、inputs_hash（字符串，SHA256）
方法一：draft.create（创建草稿）
请求参数定义表
- jsonrpc | 字符串 | 必填 | 固定值 "2.0" | "2.0"
- method | 字符串 | 必填 | 固定值 "draft.create" | "draft.create"
- id | 字符串 | 必填 | 请求唯一 ID | "req-20251113-001"
- params.idempotency_key | 字符串 | 必填 | 幂等键，最长 128 字符 | "idem-6f1e..."
- params.external_correlation_id | 字符串 | 可选 | 外部关联 ID（追踪用） | "release-2.4"
- params.instruction_set | 对象 | 必填 | 指令集（见通用结构） | 见示例
- params.generation_options | 对象 | 必填 | 生成选项 | 见示例
- params.segmentation_plan | 数组[对象] | 可选 | 自定义分段计划：{segment_id,node_id,order} | 省略表示由服务根据策略自动规划
响应参数定义表
- jsonrpc | 字符串 | 描述 | 固定值 "2.0" | "2.0"
- id | 字符串 | 描述 | 与请求 id 对应 | "req-20251113-001"
- result.draft_id | 字符串 | 草稿 ID（UUID） | "dr-b7a0..."
- result.version_id | 字符串 | 初始版本 ID | "v-0001"
- result.state | 枚举 | 草稿状态：initialized | "initialized"
- result.created_at | 时间 | 创建时间 | "2025-11-13T06:20:30Z"
- result.audit_id | 字符串 | 审计事件 ID | "au-9c3d..."
方法二：draft.validate（指令集预检）
请求参数定义表
- jsonrpc | 字符串 | 必填 | "2.0" | "2.0"
- method | 字符串 | 必填 | "draft.validate" | "draft.validate"
- id | 字符串 | 必填 | 请求 ID | "req-002"
- params.instruction_set | 对象 | 必填 | 指令集 | 见示例
响应参数定义表
- result.valid | 布尔 | 是否通过校验 | true
- result.issues | 数组[对象] | 校验问题列表 | [{"code":"BANNED_TERM","severity":"high","message":"含禁用词","path":"$.outline[0]","suggestion":"替换"}]
方法三：draft.generate_segments（增量生成/断点续写）
请求参数定义表
- jsonrpc | 字符串 | 必填 | "2.0" | "2.0"
- method | 字符串 | 必填 | "draft.generate_segments" | "draft.generate_segments"
- id | 字符串 | 必填 | 请求 ID | "req-003"
- params.idempotency_key | 字符串 | 必填 | 幂等键 | "idem-7e2a..."
- params.draft_id | 字符串 | 必填 | 草稿 ID | "dr-b7a0..."
- params.version_id | 字符串 | 可选 | 指定版本（缺省为当前编辑版本） | "v-0001"
- params.job_id | 字符串 | 可选 | 现有生成作业 ID（用于续写） | "job-91f3..."
- params.locators | 数组[locator] | 可选 | 指定节点/范围；为空时按 cursor 继续 | 见示例
- params.cursor | 对象 | 可选 | 断点游标：{checkpoint_id, next_node_id, offset} | {"checkpoint_id":"cp-..."}
- params.max_segments | 整数 | 可选 | 本次最多生成段数（1-50） | 10
- params.overwrite_strategy | 枚举 | 可选 | skip_existing|overwrite|merge | "skip_existing"
- params.audit_note | 字符串 | 可选 | 审计备注 | "生成第2章"
响应参数定义表
- result.job_id | 字符串 | 生成作业 ID | "job-91f3..."
- result.status | 枚举 | running|completed|partial|blocked | "partial"
- result.generated_segments | 数组[对象] | 已生成片段 | [{"segment_id":"seg-001","node_id":"n-2-1","version_id":"v-0001","content":"...","citations":[...],"chart_placeholders":[...],"compliance_violations":[...],"checksum":"sha256:...","created_at":"..."}]
- result.next_cursor | 对象 | 下一断点游标 | {"checkpoint_id":"cp-...","next_node_id":"n-2-2"}
- result.metrics | 对象 | 统计 | {"segments_generated":3,"tokens_used":5200}
- result.warnings | 数组[字符串] | 警告信息 | ["第3章存在禁用词候选"]
方法四：draft.get_content（获取内容/片段）
请求参数定义表
- jsonrpc | 字符串 | 必填 | "2.0" | "2.0"
- method | 字符串 | 必填 | "draft.get_content" | "draft.get_content"
- id | 字符串 | 必填 | 请求 ID | "req-004"
- params.draft_id | 字符串 | 必填 | 草稿 ID | "dr-b7a0..."
- params.version_id | 字符串 | 可选 | 指定版本；缺省最新 | "v-0002"
- params.format | 枚举 | 必填 | markdown|html|json-structure | "markdown"
- params.include_toc | 布尔 | 可选 | 是否包含目录 | true
- params.locator | 对象 | 可选 | 若提供则仅返回片段 | {"node_id":"n-2-1","selection":"content"}
响应参数定义表
- result.content | 字符串/对象 | 完整内容或片段内容 | "# 目录...\n## 第2章..."
- result.toc | 数组[对象] | 目录结构（title,node_id,level,page_estimate） | [{"title":"概述","node_id":"n-1","level":1}]
- result.structure_nodes | 数组[对象] | 结构节点摘要 | [{"node_id":"n-2-1","type":"section","title":"安装指南"}]
- result.fragment_info | 对象 | 当 locator 提供时返回片段元数据 | {"node_id":"n-2-1","segment_ids":["seg-001","seg-002"]}
- result.etag | 字符串 | 内容 ETag（用于并发控制） | "W/"v-0002:sha256-...""
方法五：draft.commit（提交版本）
请求参数定义表
- jsonrpc | 字符串 | 必填 | "2.0" | "2.0"
- method | 字符串 | 必填 | "draft.commit" | "draft.commit"
- id | 字符串 | 必填 | 请求 ID | "req-005"
- params.idempotency_key | 字符串 | 必填 | 幂等键 | "idem-3df0..."
- params.draft_id | 字符串 | 必填 | 草稿 ID | "dr-b7a0..."
- params.version_label | 字符串 | 可选 | 版本标签（例如 "release-2.4"） | "release-2.4"
- params.release_notes_summary | 字符串 | 可选 | 简要说明 | "新增第3章，修复术语"
响应参数定义表
- result.version_id | 字符串 | 提交后新版本 ID | "v-0003"
- result.status | 枚举 | committed | "committed"
- result.changelog | 数组[对象] | 变更摘要 | [{"node_id":"n-3","change":"added","segments":5}]
方法六：draft.rollback_version（版本回滚）
请求参数定义表
- jsonrpc | 字符串 | 必填 | "2.0" | "2.0"
- method | 字符串 | 必填 | "draft.rollback_version" | "draft.rollback_version"
- id | 字符串 | 必填 | 请求 ID | "req-006"
- params.idempotency_key | 字符串 | 必填 | 幂等键 | "idem-0a1b..."
- params.draft_id | 字符串 | 必填 | 草稿 ID | "dr-b7a0..."
- params.to_version_id | 字符串 | 必填 | 回滚目标版本 | "v-0002"
- params.reason | 字符串 | 必填 | 回滚原因 | "合规违规"
响应参数定义表
- result.version_id | 字符串 | 当前有效版本 ID（回滚后） | "v-0002"
- result.status | 枚举 | rolled_back | "rolled_back"
- result.diff_summary | 数组[对象] | 回滚差异摘要 | [{"node_id":"n-3","change":"removed","segments":5}]
- result.audit_id | 字符串 | 审计事件 ID | "au-1f2e..."
方法七：draft.list_versions（版本列表）
请求参数定义表
- jsonrpc | 字符串 | 必填 | "2.0" | "2.0"
- method | 字符串 | 必填 | "draft.list_versions" | "draft.list_versions"
- id | 字符串 | 必填 | 请求 ID | "req-007"
- params.draft_id | 字符串 | 必填 | 草稿 ID | "dr-b7a0..."
- params.page | 整数 | 可选 | 页码，从 1 开始 | 1
- params.size | 整数 | 可选 | 每页数量（1-100） | 20
响应参数定义表
- result.versions | 数组[对象] | 版本列表 | [{"version_id":"v-0001","label":"init","created_at":"...","state":"committed"}]
- result.page | 整数 | 页码 | 1
- result.size | 整数 | 每页数量 | 20
- result.total | 整数 | 总数 | 3
方法八：draft.get_audit_log（审计日志）
请求参数定义表
- jsonrpc | 字符串 | 必填 | "2.0" | "2.0"
- method | 字符串 | 必填 | "draft.get_audit_log" | "draft.get_audit_log"
- id | 字符串 | 必填 | 请求 ID | "req-008"
- params.draft_id | 字符串 | 必填 | 草稿 ID | "dr-b7a0..."
- params.filter | 对象 | 可选 | {operation,since,until,actor} | {"operation":"draft.generate_segments"}
响应参数定义表
- result.entries | 数组[audit_entry] | 审计条目列表 | 见示例
- result.count | 整数 | 返回条目数量 | 12
方法九：job.get_status（作业状态）
请求参数定义表
- jsonrpc | 字符串 | 必填 | "2.0" | "2.0"
- method | 字符串 | 必填 | "job.get_status" | "job.get_status"
- id | 字符串 | 必填 | 请求 ID | "req-009"
- params.draft_id | 字符串 | 必填 | 草稿 ID | "dr-b7a0..."
- params.job_id | 字符串 | 必填 | 作业 ID | "job-91f3..."
响应参数定义表
- result.job_id | 字符串 | 作业 ID | "job-91f3..."
- result.status | 枚举 | queued|running|completed|failed|canceled|blocked | "running"
- result.next_cursor | 对象 | 下一断点 | {"checkpoint_id":"cp-..."}
- result.metrics | 对象 | 统计 | {"segments_generated":7,"tokens_used":10400}
- result.last_error | 对象 | 最近错误（如有） | {"code":2001,"message":"模型限流","retriable":true,"retry_after":3}
方法十：job.resume（续写）
请求参数定义表
- jsonrpc | 字符串 | 必填 | "2.0" | "2.0"
- method | 字符串 | 必填 | "job.resume" | "job.resume"
- id | 字符串 | 必填 | 请求 ID | "req-010"
- params.idempotency_key | 字符串 | 必填 | 幂等键 | "idem-22ab..."
- params.draft_id | 字符串 | 必填 | 草稿 ID | "dr-b7a0..."
- params.job_id | 字符串 | 必填 | 作业 ID | "job-91f3..."
- params.max_segments | 整数 | 可选 | 本次续写最大段数 | 5
响应参数定义表
- result.job_id | 字符串 | 作业 ID | "job-91f3..."
- result.status | 枚举 | running|completed|blocked | "running"
- result.generated_segments | 数组[对象] | 新生成片段 | 见上方结构
- result.next_cursor | 对象 | 下一断点 | {"checkpoint_id":"cp-..."}
方法十一：job.cancel（取消作业）
请求参数定义表
- jsonrpc | 字符串 | 必填 | "2.0" | "2.0"
- method | 字符串 | 必填 | "job.cancel" | "job.cancel"
- id | 字符串 | 必填 | 请求 ID | "req-011"
- params.idempotency_key | 字符串 | 必填 | 幂等键 | "idem-0c9f..."
- params.draft_id | 字符串 | 必填 | 草稿 ID | "dr-b7a0..."
- params.job_id | 字符串 | 必填 | 作业 ID | "job-91f3..."
- params.reason | 字符串 | 必填 | 取消原因 | "用户中止"
响应参数定义表
- result.job_id | 字符串 | 作业 ID | "job-91f3..."
- result.status | 枚举 | canceled | "canceled"
- result.canceled_at | 时间 | 取消时间 | "2025-11-13T06:40:00Z"
方法十二：content.locate_fragment（片段定位）
请求参数定义表
- jsonrpc | 字符串 | 必填 | "2.0" | "2.0"
- method | 字符串 | 必填 | "content.locate_fragment" | "content.locate_fragment"
- id | 字符串 | 必填 | 请求 ID | "req-012"
- params.draft_id | 字符串 | 必填 | 草稿 ID | "dr-b7a0..."
- params.version_id | 字符串 | 可选 | 版本 ID | "v-0002"
- params.locator_query | 对象 | 必填 | {path|anchor_label|search_text, selection} | {"search_text":"安装要求","selection":"content"}
响应参数定义表
- result.locators | 数组[locator] | 命中的定位器 | [{"node_id":"n-2-1","selection":"content"}]
- result.count | 整数 | 命中数量 | 1
方法十三：content.replace_fragment（片段替换）
请求参数定义表
- jsonrpc | 字符串 | 必填 | "2.0" | "2.0"
- method | 字符串 | 必填 | "content.replace_fragment" | "content.replace_fragment"
- id | 字符串 | 必填 | 请求 ID | "req-013"
- params.idempotency_key | 字符串 | 必填 | 幂等键 | "idem-55df..."
- params.draft_id | 字符串 | 必填 | 草稿 ID | "dr-b7a0..."
- params.locator | 对象 | 必填 | 片段定位器 | {"node_id":"n-2-1","selection":"content"}
- params.replacement_content | 字符串 | 必填 | 替换后的内容 | "更新后的章节内容..."
- params.policy.fail_on_violation | 布尔 | 可选 | 含禁用词时是否失败 | true
响应参数定义表
- result.updated_segment_id | 字符串 | 更新的片段 ID | "seg-001"
- result.version_id | 字符串 | 新版本 ID（若产生新版本） | "v-0004"
- result.compliance_violations | 数组[对象] | 合规问题（如有） | [{"term":"免费","location":{...},"severity":"high"}]
错误码对照表
- -32700 | 解析错误（JSON-RPC 标准） | 修复请求 JSON 语法
- -32600 | 非法请求（JSON-RPC 标准） | 检查 jsonrpc、method、id 字段
- -32601 | 方法不存在（JSON-RPC 标准） | 校验 method 名称
- -32602 | 参数错误（JSON-RPC 标准） | 校验参数类型/必填项
- -32603 | 内部错误（JSON-RPC 标准） | 重试或联系支持
- 1000 | INVALID_PARAMS | 参数不符合规范 | 按校验提示修正
- 1001 | MISSING_REQUIRED_FIELD | 缺少必填字段 | 补齐必填项
- 1002 | UNSUPPORTED_FORMAT | 不支持的输出/引用格式 | 更换为支持的枚举
- 1003 | INVALID_LOCATOR | 定位器无效 | 修正 node_id/path/anchor
- 1004 | CONFLICT_ETAG_MISMATCH | ETag 不匹配（并发冲突） | 重新获取内容后再提交
- 1005 | DUPLICATE_IDEMPOTENCY_KEY | 幂等键重复但参数不一致 | 复用完全一致参数或更换键
- 1006 | VERSION_NOT_FOUND | 版本不存在 | 校验 version_id
- 1007 | DRAFT_NOT_FOUND | 草稿不存在 | 校验 draft_id
- 1008 | JOB_NOT_FOUND | 作业不存在 | 校验 job_id
- 1009 | OVERWRITE_POLICY_VIOLATION | 覆盖策略不允许 | 调整 overwrite_strategy
- 1010 | COMPLIANCE_BLOCKED | 合规策略阻断 | 修改内容或调整 on_violation
- 2000 | GENERATION_FAILED | 内容生成失败 | 查看 last_error，必要时重试
- 2001 | MODEL_RATE_LIMIT | 模型限流 | 间隔 retry_after 秒重试
- 2002 | CONTENT_TOO_LARGE | 内容过大 | 减少段数或优化结构
- 2003 | TOKEN_LIMIT_EXCEEDED | 超出令牌限制 | 调整 max_tokens_per_segment
- 2004 | SEGMENT_PLAN_INVALID | 分段计划非法 | 修正 segmentation_plan
- 2005 | CHECKPOINT_EXPIRED | 断点过期 | 重新开始生成或刷新 cursor
- 3000 | STATE_NOT_ALLOWED | 当前状态不允许操作 | 确认草稿/作业状态
- 3001 | LOCK_ACQUIRED_BY_ANOTHER | 资源被他人锁定 | 等待或释放锁
- 3002 | JOB_ALREADY_RUNNING | 作业已在运行 | 查询状态或取消后再发起
- 4000 | BANNED_TERM_DETECTED | 检测到禁用词 | 替换术语或开启 auto_replace
- 4001 | REFERENCE_UNREACHABLE | 参考链接不可达 | 更新为有效 https 链接
- 4002 | CITATION_FORMAT_ERROR | 引用格式错误 | 统一为指定 citation_style
- 5000 | INTERNAL_ERROR | 服务内部错误 | 重试或联系支持
- 5001 | SERVICE_UNAVAILABLE | 服务不可用 | 退避重试
接口调用示例
示例 1：创建草稿（draft.create）
请求示例
{
"jsonrpc": "2.0",
"method": "draft.create",
"id": "req-20251113-001",
"params": {
"idempotency_key": "idem-6f1e2c9a-01",
"external_correlation_id": "release-2.4",
"instruction_set": {
"outline": [
{"node_id": "n-1", "type": "chapter", "title": "概述", "children": [
{"node_id": "n-1-1", "type": "section", "title": "背景"}
]},
{"node_id": "n-2", "type": "chapter", "title": "安装与升级", "children": [
{"node_id": "n-2-1", "type": "section", "title": "系统要求", "requirements": {"min_words": 200}}
]}
],
"tone": "专业且清晰",
"persona": {"role": "运维工程师", "experience": "中级", "industry": "软件"},
"glossary": [{"term": "容器镜像", "definition": "可部署的软件包镜像"}],
"banned_terms": ["绝对保证", "免费"],
"references": [{"label": "发布票据", "url": "https://example.com/release/2.4"}],
"compliance_points": [{"code": "CN-ADS-01", "description": "禁止夸大承诺", "severity": "high"}]
},
"generation_options": {
"language": "zh-CN",
"output_format": "markdown",
"citation_style": "numeric",
"chart_placeholder_style": "mermaid",
"segment_strategy": {"type": "by_outline_node", "max_tokens_per_segment": 1200},
"compliance_mode": "strict",
"on_violation": "block"
}
}
}
响应示例
{
"jsonrpc": "2.0",
"id": "req-20251113-001",
"result": {
"draft_id": "dr-b7a0f3e4-9d1b-4c2c-8120-99c6f9d1f0a1",
"version_id": "v-0001",
"state": "initialized",
"created_at": "2025-11-13T06:20:30Z",
"audit_id": "au-9c3d5ea2"
}
}
示例 2：增量生成（draft.generate_segments）
请求示例
{
"jsonrpc": "2.0",
"method": "draft.generate_segments",
"id": "req-003",
"params": {
"idempotency_key": "idem-7e2a-02",
"draft_id": "dr-b7a0f3e4-9d1b-4c2c-8120-99c6f9d1f0a1",
"version_id": "v-0001",
"locators": [
{"node_id": "n-2-1", "selection": "content"}
],
"max_segments": 3,
"overwrite_strategy": "skip_existing",
"audit_note": "生成第2章系统要求"
}
}
响应示例
{
"jsonrpc": "2.0",
"id": "req-003",
"result": {
"job_id": "job-91f334d2",
"status": "partial",
"generated_segments": [
{
"segment_id": "seg-001",
"node_id": "n-2-1",
"version_id": "v-0001",
"content": "本章涵盖安装前的硬件与软件要求……",
"citations": [{"marker":"[1]","reference_label":"发布票据","url":"https://example.com/release/2.4"}],
"chart_placeholders": [{"placeholder_id":"cp-1","type":"diagram","style":"mermaid","spec":"flowchart TD; A-->B"}],
"compliance_violations": [],
"checksum": "sha256:ba1f...",
"created_at": "2025-11-13T06:25:00Z"
}
],
"next_cursor": {"checkpoint_id": "cp-7da2", "next_node_id": "n-2-1", "offset": 1},
"metrics": {"segments_generated": 1, "tokens_used": 1800},
"warnings": []
}
}
示例 3：获取片段（draft.get_content）
请求示例
{
"jsonrpc": "2.0",
"method": "draft.get_content",
"id": "req-004",
"params": {
"draft_id": "dr-b7a0f3e4-9d1b-4c2c-8120-99c6f9d1f0a1",
"version_id": "v-0001",
"format": "markdown",
"include_toc": true,
"locator": {"node_id": "n-2-1", "selection": "content"}
}
}
响应示例
{
"jsonrpc": "2.0",
"id": "req-004",
"result": {
"content": "## 系统要求\n- CPU：4核及以上…",
"toc": [{"title":"概述","node_id":"n-1","level":1}, {"title":"安装与升级","node_id":"n-2","level":1}],
"structure_nodes": [{"node_id":"n-2-1","type":"section","title":"系统要求"}],
"fragment_info": {"node_id":"n-2-1","segment_ids":["seg-001"]},
"etag": "W/"v-0001:sha256-2da3...""
}
}
示例 4：提交版本（draft.commit）
请求示例
{
"jsonrpc": "2.0",
"method": "draft.commit",
"id": "req-005",
"params": {
"idempotency_key": "idem-3df0-03",
"draft_id": "dr-b7a0f3e4-9d1b-4c2c-8120-99c6f9d1f0a1",
"version_label": "release-2.4",
"release_notes_summary": "新增系统要求章节，完善引用"
}
}
响应示例
{
"jsonrpc": "2.0",
"id": "req-005",
"result": {
"version_id": "v-0002",
"status": "committed",
"changelog": [{"node_id":"n-2-1","change":"added","segments":1}]
}
}
示例 5：版本回滚（draft.rollback_version）
请求示例
{
"jsonrpc": "2.0",
"method": "draft.rollback_version",
"id": "req-006",
"params": {
"idempotency_key": "idem-0a1b-04",
"draft_id": "dr-b7a0f3e4-9d1b-4c2c-8120-99c6f9d1f0a1",
"to_version_id": "v-0001",
"reason": "检测到禁用词"
}
}
响应示例
{
"jsonrpc": "2.0",
"id": "req-006",
"result": {
"version_id": "v-0001",
"status": "rolled_back",
"diff_summary": [{"node_id":"n-2-1","change":"removed","segments":1}],
"audit_id": "au-1f2e77a9"
}
}
注意事项
- 幂等重试：在网络重试或客户端重发时务必复用相同 idempotency_key 与完全一致参数；服务将返回同一结果或错误 1005（参数不一致）。
- 片段可定位：建议为每个 OutlineNode 分配稳定 node_id（不随标题变动而变化）；path 仅作为辅助。范围选取使用 locator.range_end。
- 合规策略：compliance_mode=strict 且 on_violation=block 时，检测到 banned_terms 或引用不可达将返回 1010/4000/4001，生成被阻断。
- 引文与图表：citation_style 与 chart_placeholder_style 应与输出格式兼容；例如 markdown 中图表占位以 mermaid 代码块或替代文字呈现。
- 断点续写：cursor.checkpoint_id 最大有效期 24 小时（过期返回 2005）；建议在长作业中周期性调用 job.get_status 获取最新游标。
- 并发控制：更新或替换片段前建议先 draft.get_content 获取最新 etag；若发生 1004，应重新拉取并重试。
- 版本管理：draft.commit 会创建不可变版本；content.replace_fragment 在 strict 模式下可能触发新版本（根据实现策略），请关注响应中的 version_id。
- 安全：references.url 必须为 https；服务会拒绝非安全链接（4001）。
- 大小限制：单片段内容建议不超过 10,000 字符；超过可能触发 2002。
版本变更记录
- v1.0.0（当前）
- 引入 JSON-RPC 2.0 接口
- 支持草稿创建、指令预检、增量生成与断点续写
- 提交、回滚、版本列表与审计日志
- 片段定位与替换
- 幂等与严格错误码体系
本规范旨在确保在操作手册与发布说明自动撰写场景下，实现可控、可审计、可恢复的长文生成流水线。
