用途 add-rules 是 OpenViking 的规则编译技能，目标是通过 POST /api/v1/rules/compile 将用户授权的持久性约束编译为 OpenViking Rules，并在编译后核验任务结果和已保存的规则。适用于用户要求添加规则，或要求导入某项策略的场景。它仅用于编译持久性约束，不用于将偏好、事实或一次性任务建议提升为规则。
主要能力与工作流 使用前先确认用户的规则文本或策略来源，以及目标 OpenViking 连接；上传、编译、任务轮询和核验需使用同一实例与身份。整个工作流只能选择一种调用模式：
- Python SDK 模式：适用于以 Python 运行且具备 OpenViking SDK 的 Agent，使用 SDK 方法完成来源上传、编译、任务轮询与读取。
- HTTP 模式：适用于其他语言或通用 Agent，使用 HTTP 端点完成同样步骤。
同一编译工作流中不得混用 SDK 调用与直接 HTTP 调用。
请求构建 请求包含顶层 instruction 与 sources，二者至少一个非空。需忠实保留来源中的义务、适用条件、例外、阈值和标识符，不得自行编造策略内容。
Python SDK 模式中，options 支持 sources，每个来源可为本地文件或目录路径、远程 URL、Resource URI 或高级来源字典，SDK 会自动上传本地路径。示例：
task = client.rule_compile( instruction="Compile the supplied policy into durable Rules.", options={ "sources": [ "/local/path/policy.md", "https://example.org/policy.md", "viking://resources/team-policy", ] }, ) task_id = task["task_id"]
随后通过 client.get_task(task_id) 轮询，通过 client.read_raw(uri) 读取已保存内容。
HTTP 模式没有 options 包装层，instruction 与 sources 直接放在 JSON 请求体中。来源可用 resource_uri 指向已有 Resource，用 path 指向远程文本来源，或用 POST /api/v1/resources/temp_upload 返回的 temp_file_id 表示本地内容。示例：
{ "instruction": "Compile the supplied policy into durable Rules.", "sources": [ {"resource_uri": "viking://resources/team-policy"}, {"path": "https://example.org/policy.md"}, {"temp_file_id": "tmp_xxx", "source_name": "policy.md"} ] }
将该请求体提交到 POST /api/v1/rules/compile。不得向该端点发送客户端本地路径。之后轮询 GET /api/v1/tasks/{task_id}，并通过 GET /api/v1/content/read?uri=...&raw=true 读取已保存内容。
任务与核验 需保存返回的 task_id；请求被接受不代表编译已完成。应使用选定模式轮询，直到任务状态为 completed、failed 或 cancelled，并查询已有任务而非重复提交请求。
结果需检查 result.operations、written_uris 和 write_result，区分已保存的 Rules 与 NOOP、UNCERTAIN、REJECT 结果；任务 completed 并不保证产生了新规则。随后读取有代表性的已保存 Rule 及其 Scenarios，核对策略文本与证据，并验证 rules/<scenario_id>/abstract.md 保存 Scenario 元数据，而 Rule 文件以 <atomic_id>.md 形式直接位于其旁。最终需报告任务 ID、实际变更、代表性 URI 和未决事项。
限制与边界
- 仅编译持久性约束，不提升偏好、事实或一次性建议。
- 优先使用来源支持且非空的 applies_when 条件；空 applies_when 表示除例外外适用于所有情况，而非未知。
- 仅在用户明确授权时请求生命周期变更；仅当用户明确要求删除、丢弃或移入回收站时使用 ARCHIVE；对暂停、禁用、停用、退役、停止适用或停止使用且无删除意图的请求使用 PAUSE。已归档规则为逻辑删除，不再是编译候选项，且无法通过规则编译恢复。
- 使用客户端连接配置，而非服务端模型凭据；不得为解决失败请求而切换实例或暴露凭据。
- API 最多接受 16 个来源和 64000 字符的 instruction；来源收集最多读取 128 个文件和 128000 字符。超量材料应拆分为包含条件与例外的自包含策略，而不是静默省略内容。
- 规则编译要求可读文本，不得提交图片、音频或视频来源。
- 请求失败或状态未知时，应先检查任务与已保存文件再重试；后续规则编译失败不会回滚此前已导入的 Resources。
- 不要将即时空搜索结果视为写入失败的证据，语义索引可能仍在处理中。