[RFC] Openviking支持 ov compile 知识编译命令

[fujiajie666]

TL;DR

• ov compile 是 OpenViking 新增的一条知识编译链路：一条命令，把散落的来源材料按用户指定的 Skill，整理成 OKF v0.1 规范的 LLM Wiki ，或 Skill 包、或.yaml/.json/.png 等 artifact。
• 目前的定位是：Skill 决定"整理成什么"， Renderer 决定"怎么落地"，Agent 出结构化草稿。 Agent 经 batch-write / add_skill 归档。
• 增量按 content hash 判定 created / updated / unchanged，未变的页面不写；不会脏写。
• 可以用 ov compile 实现 Skill 生成、论文导读、One-Page 、LLM Wiki等多种能力。
• 目前 ov compile 依赖 agent loop 实现，需要通过 openviking-server --with-bot 启动 vikingbot 后方可使用

可实践的例子如下

# 示例 1：把周报按月整理成一份团队 Wiki
ov compile --from viking://resources/周报 \
           --to   viking://resources/团队知识库 \
           --skill viking://agent/skills/my_wiki_skill_okr \
           --reason "按月整理团队的成本优化进展"

# 示例 2：多来源 → 同一目标 Wiki，走另一套 Skill
ov compile --from viking://resources/周报,viking://a/b/c \
           --to   viking://resources/团队知识库 \
           --skill viking://agent/skills/my_wiki_skill_ara \
           --reason "按月整理团队的成本优化进展"

# 示例 3：把周报 + 轨迹记忆编译成一个新 Skill 包
ov compile --from viking://resources/周报,viking://user/轨迹记忆 \
           --to   viking://agent/skills \
           --skill viking://agent/skills/my_self_envolve_to_skill \
           --reason "充分理解周会的周报，整理或更新一个写周报技能"

1. 为什么做 ov compile

把一批来源材料整理成一套可被 Agent 检索、可持续维护的知识页面，OpenViking 此前只有两条路径，都不够用：

• 人手工整理：跨来源的组织方式、页面结构、引用规范无法统一；来源更新后需要人工比对增量，成本随知识库规模线性上升。
• 让通用 Agent 直接写库：Agent 拿到写工具后可以任意增删 OpenViking 内容，权限边界模糊、易脏写、易改坏既有页面；产出格式随每次运行漂移，没有一道确定性关卡兜底，也无法可靠判断"这次到底改了什么"。

ov compile 想解决的是同一个诉求：用可复用的规则（Skill）把来源材料确定性地整理进目标目录，并且只在内容真正变化时才写入。 它不追求"更聪明的 Agent"，追求"更可控的整理流水线"。

2. 与"Agent 裸写"的关键差异

维度	通用 Agent 直接写库	ov compile
写入出口	Agent 持有多个 OV 写/删工具，路径分散	Agent 只通过 batch-write / add_skill 进行写入
格式一致性	随每次运行漂移，无统一 frontmatter / 引用规范	确定性 Renderer 统一生成 OKF frontmatter、Wiki 链接、Citations
增量语义	难以判断"本次改了什么"，容易重复覆盖	按 content hash 判定 created / updated / unchanged，未变不写
读写范围	默认可达整个命名空间	读范围仅 from / to / skill；写范围仅 to
失败可恢复性	部分写入后状态不确定	草稿校验失败回退重试

上表右列即 compile 的设计主线：把 Agent 的自由发挥约束在一个结构化草稿协议里，把对 OpenViking 的实际改动收敛到一条确定性、可校验、可增量的写入链路上。

3. 架构：Skill 驱动 + 确定性 Renderer + 增量写入

一次 compile 沿单向管线推进，各阶段职责单一、可独立观测：

ov CLI
  │  POST /bot/v1/compile { from[], to, skill, reason }
  ▼
Bot Proxy (认证 + 代理)
  │
  ▼
BotCompileService.create ──► 归一化请求 (URI 语法/canonical/读写权限/mkdir)
  │                          返回 { task_id, status=accepted }
  ▼
[loading_skill]        Skills API 取 Skill → 快照到 workspace → SkillsLoader 加载
  ▼
[collecting_context]   为每个来源构建 overview → 非 skill 目标做语义检索并生成目标 catalog
  ▼
[agent]                AgentLoop(stop_tool=submit_wiki_bundle)
  │                    Agent 用只读工具浏览来源与目标 → 产出 WikiBundleDraft
  ▼
[rendering]            WikiRenderer 校验路径/来源/链接 → OKF frontmatter → Citations
  │                    → 与旧内容对比 → 标记 created / updated / unchanged
  ▼
[writing / refreshing] resource/memory: batch-write 一次提交 (wait=true)
  │                    skills:          add_skill / update_skill
  │                    写后对生成 Wiki 文件 append ov.kind=wiki 搜索标签
  ▼
[completed]            保存任务结果 → 清理 task workspace

组件调用关系与写入出口收敛点：

主流程状态机：

三条设计主线要展开一句：

• Skill 驱动：--skill 决定要整理成什么。Skill 语义决定输出是 Wiki 页面（.md + OKF frontmatter）、Skill 包（<skill-name>/SKILL.md + 附属文件），还是普通 artifact（.yaml / .json / .png）。三种目标各自分流写入，.md 且含 type frontmatter 才参与 OKF 校验并打 ov.kind=wiki 标签。
• 确定性 Renderer：Renderer 是整条链路的一条确定性关卡，负责校验输入的wiki类型的草稿，输出可以直接落盘的文档，全程无随机性。OKF frontmatter、Wiki 链接、Citations、bare viking:// URI linkify、Related pages、created/updated/unchanged 判定，都由代码完成，不依赖模型。
• 增量写入：带 update_uri 的页面先读旧文件生成 sha256 作为 base_hash，与渲染后的新内容对比：一致 → unchanged 不写；不一致 → replace_if_hash(base_hash)；不存在 → create_if_absent。重试靠 hash 幂等收敛，不会覆盖并发写入。

4. 一条命令上手

ov compile \
  --from viking://resources/周报 \
  --to viking://resources/团队知识库 \
  --reason "按月整理团队的成本优化进展" \
  --skill viking://agent/skills/monthly_wiki \
  --wait

参数说明：

参数	说明
--from	必填，可重复或逗号分隔；每项必须是可读目录
--to	必填，目标目录（resource / memory / skills），不存在会自动 mkdir
--skill	必填，Skill 目录或其 SKILL.md 的 Viking URI
--reason	可选，本次整理任务的描述；为空时使用默认描述
--wait / --timeout	可选，--wait 等任务完成；--timeout 只限制 CLI 等待，不取消服务端任务
--output / --compact	可选，--output table|json 控制结果呈现

任务是异步的：POST /bot/v1/compile 立刻返回 task_id，GET /bot/v1/compile/{task_id} 查询进度。状态机是 accepted → running → committing → completed | failed，失败会终止在对应 stage 并携带错误码。

5. AgentLoop 输出协议

Agent 必须调用 submit_wiki_bundle 提交 WikiBundleDraft。

class WikiPageDraft(BaseModel):
    model_config = ConfigDict(extra="forbid")
    page_id: int
    title: str
    page_type: str
    summary: str
    body_markdown: str | None = None
    body_workspace_path: str | None = None
    source_ids: list[str]
    tags: list[str] = Field(default_factory=list)
    path_hint: str | None = None
    update_uri: str | None = None

class CompileFileDraft(BaseModel):
    model_config = ConfigDict(extra="forbid")
    path: str | None = None           
    update_uri: str | None = None
    workspace_path: str | None = None  

class WikiBundleDraft(BaseModel):
    model_config = ConfigDict(extra="forbid")
    pages: list[WikiPageDraft]
    files: list[CompileFileDraft]
    links: list[WikiLink]

PS:

• update_uri 必须来自 to 目录已有文件且保持原 URI，不能改名或移动。
• 校验失败时工具把错误返回给 Agent 并追加 "Reflect on the results and decide next steps." 触发重试；达到迭代上限仍未提交合法结果，任务 failed。

skills 目标是个特例：submit_wiki_bundle 只保留 files（去掉 pages / links），要求所有文件位于 <skill-name>/ 下、必须包含 <skill-name>/SKILL.md，并校验 Skill name 与目录名一致——这样一条链路既能编译 Wiki，也能编译出可运行的 Skill 包。

6. 端到端实测：四类真实产物

下面四个样例已跑通，分别验证 利用历史资源/记忆生成可复用skills 、利用开源高质量 Skill 完成论文导读、One Page生成、LLM Wiki四条产物路径。

6.1 生成 weekly-report-writer Skill

以周报样例 + trajectory memory 为来源，用一个"构建周报 Skill"的指导 Skill 编译出一个新的 weekly-report-writer Skill（--to viking://agent/skills，走 skills 目标分流）：

ov compile \
  --from viking://resources/compile-skill-demo/weekly-reports \
  --from viking://user/memories/trajectories/compile-skill-demo \
  --to viking://agent/skills \
  --skill viking://agent/skills/build-weekly-report-skill \
  --reason "创建或更新名为 weekly-report-writer 的 Skill：基于周报样例提炼稳定结构，结合 trajectory 中经过验证的写作流程与质检规则" \
  --wait --timeout 1800

产出：viking://agent/skills/weekly-report-writer/ 下生成含 SKILL.md 的完整 Skill 目录，校验 Skill name 与目录名一致。

---
name: weekly-report-writer
description: 指导Agent将零散的工作事实、项目数据、决策记录转化为结构清晰、信息可信、可落地执行的架构双周报/周报，适用于团队进度同步、风险对齐、工作复盘汇报等场景
---

# 周报/双周报写作指南

## 适用场景
当需要输出面向团队/管理层的结构化工作汇报，包含项目进展、风险同步、后续规划等可验证信息时使用本技能。

## 写作前置流程
1. 先对所有输入素材（发布记录、监控数据、会议纪要、进展反馈等）进行证据归类，将事实分别归入「目标、结果、证据、影响、风险、下一步」6个类别
2. 对每个结论匹配可验证的支撑证据：优先使用量化指标，无指标时使用明确的里程碑/验收结果
3. 合并同一目标下的多项活动，避免按人员/时间堆叠活动流水账
4. 无法确认的信息明确标记为「待确认」并说明缺失的证据，禁止主观猜测补全内容

## 报告标准结构
### 1. 头部信息
标注报告周期、所属团队，如：
> 周期：YYYY-MM-DD 至 YYYY-MM-DD
> 团队：[所属团队名称]

### 2. 一句话结论
开门见山给出本周期核心成果 + 最主要的风险/卡点，读者可在首屏快速判断周期产出与核心问题。

### 3. 本周期目标与结果
以表格形式呈现：
| 目标 | 结果 | 状态 |
| --- | --- | --- |
| [本周期原定目标描述] | [对应达成结果，优先附量化数据] | 已完成/进行中/延期 |

### 4. 关键进展
分模块说明核心动作及对应的业务价值/影响，每个模块包含「做了什么」+「带来什么变化」，避免无价值的活动堆叠。

### 5. 偏差与原因（可选，存在延期事项时必填）
对未按期完成的目标单独说明延期的客观事实原因，不添加辩解性表述，明确当前调整后的决策。

### 6. 关键决策
说明本周期做出的重要技术/项目决策，补充决策背景、原因及退出条件，方便后续追溯对齐。

### 7. 风险与阻塞
以表格形式呈现所有待解决的风险项：
| 风险 | 影响 | 当前措施 | 负责人 | 截止时间 |
| --- | --- | --- | --- | --- |
| [具体风险事件，禁止抽象描述如「稳定性问题」] | [风险发生带来的实际影响范围] | [当前正在推进的缓解措施] | [明确负责人姓名] | [YYYY-MM-DD格式截止时间] |

### 8. 下周期计划
分点列出下周期可验收的动作，每个计划包含明确的完成/退出条件，禁止使用「持续优化」「继续推进」等模糊表述。

## 最终质检规则
发布前必须完成以下校验：
1. **事实校验**：所有数字、时间、状态、负责人均有对应输入证据支撑，无编造内容
2. **一致性校验**：一句话结论、表格、正文对同一事项的表述完全一致
3. **措辞校验**：禁止使用「彻底解决」「完全稳定」等绝对表述，结论强度不超过证据的时间/样本/覆盖率范围
4. **可执行校验**：所有风险项、计划项均有明确的负责人、截止时间、验收标准，可直接用于后续跟踪

## 禁止规则
- 禁止编造不存在的事实或夸大成果
- 禁止将活动流水账作为结果输出
- 禁止隐藏延期事项，所有偏差必须明确说明

6.2 复用外部 ARA compiler Skill 编译论文

复用开源的 ARA compiler Skill，把一篇 ResNet 论文 PDF 编译为结构化研究产物：

ov skills add "$ARA_SKILL_URL" --wait
ov add-resource "$DEMO_DIR/input" --to "$SOURCE_URI" --wait --timeout 900
ov compile \
  --from "$SOURCE_URI" \
  --to "$TARGET_URI" \
  --skill <skill_url> \
  --wait --timeout 1800

产出：在 ara-resnet-output 下生成 ARA compiler Skill 规定形态的产物集合。本例验证的是 compile 对第三方 Skill 的兼容——只要 Skill 描述了想要的输出形态，Renderer 会按 Skill 规则渲染。

6.3 生成 One-Page 知识导航页

把一批企业知识库解析材料整理为一个面向产品 / 研发 / 运维的单页导航：

ov compile \
  --from viking://resources/knowledge-parsing-one-page-source \
  --to viking://resources/knowledge-parsing-one-page-wiki \
  --skill <skill-url> \
  --reason "把这批企业知识库文档解析材料整理成一个面向产品、研发和运维的 One-Page 知识导航页" \
  --wait --timeout 1800

产出：面向产品 / 研发 / 运维的单页导航 one-page，跨来源的入口在同一页可直达。

---
type: navigation_index
title: Atlas Parse 企业知识库文档解析服务 One-Page
description: 本导航页完整覆盖Atlas Parse企业知识库文档解析服务全链路核心参考资料，面向产品、研发、运维及业务对接人员，可快速定位服务接入、技术研发、项目落地、运维管理等场景所需的标准化参考内容。
tags: [Atlas Parse, 文档解析, 知识库建设, OCR, RAG, 私有化部署]
---

# Atlas Parse 企业知识库文档解析服务 One-Page

本导航页是Atlas Parse企业知识库文档解析服务的一站式参考资料入口，完整覆盖服务基础说明、智能解析技术、知识库建设、质量管控、工程落地、运维运营全链路核心内容。面向产品、研发、运维及相关业务对接人员，你可以根据自身需求快速定位到对应参考材料，无需遍历复杂文件夹结构。

## 内容索引

### 1. 基础信息与接入指南
本栏目提供服务基础能力说明与对接规范，适合需要快速了解服务定位、完成接入评估的产品、对接开发人员参考。
- [服务定位与边界说明](viking://resources/knowledge-parsing-one-page-source/01-foundation/01-product-scope/01-product-scope.md) — 明确Atlas Parse服务的能力范围、适用场景与边界限制
- [支持文件格式标准](viking://resources/knowledge-parsing-one-page-source/01-foundation/02-supported-formats/02-supported-formats.md) — 查阅服务支持的各类文档、图片格式及对应处理能力说明
- [API/SDK接入规范](viking://resources/knowledge-parsing-one-page-source/01-foundation/03-api-sdk-integration/03-api-sdk-integration.md) — 获取官方标准接入流程、接口定义与开发示例

### 2. 智能解析技术方案
本栏目提供各类复杂场景的文档解析技术方案，适合OCR开发、文档结构化研发、智能文档项目落地人员参考。
- [低质量扫描件OCR处理方案](viking://resources/knowledge-parsing-one-page-source/02-parsing/04-ocr-low-quality-scans/04-ocr-low-quality-scans.md) — 查看模糊、畸变、低清晰度扫描件的OCR优化处理规则
- [版面解析与阅读顺序恢复规范](viking://resources/knowledge-parsing-one-page-source/02-parsing/05-layout-reading-order/05-layout-reading-order.md) — 了解多栏、混排、复杂版面的内容顺序识别与还原方案
- [复杂表格恢复技术指引](viking://resources/knowledge-parsing-one-page-source/02-parsing/06-complex-table-recovery/06-complex-table-recovery.md) — 获取合并单元格、跨页、不规则表格的结构化恢复方案
- [公式与图表解析方案](viking://resources/knowledge-parsing-one-page-source/02-parsing/07-formulas-charts/07-formulas-charts.md) — 查阅数学公式、各类图表的识别与结构化输出规则

### 3. 知识库与RAG落地规范
本栏目提供知识库建设全流程操作标准，适合RAG研发、知识库建设从业者、数据处理人员使用。
- [语义分块规则规范](viking://resources/knowledge-parsing-one-page-source/03-knowledge/08-semantic-chunking/08-semantic-chunking.md) — 了解非结构化文档的语义分块标准、参数配置与优化方案
- [元数据与权限管控规范](viking://resources/knowledge-parsing-one-page-source/03-knowledge/09-metadata-permissions/09-metadata-permissions.md) — 获取知识元数据追溯、权限映射与合规管控操作指引
- [多模态素材管理规范](viking://resources/knowledge-parsing-one-page-source/03-knowledge/10-multimodal-assets/10-multimodal-assets.md) — 查看图片、图表等非文本素材的存储、关联与安全管理规则

### 4. 质量管控与可观测性
本栏目提供解析质量管控与服务稳定性保障方案，适合算法开发、测试、运维、业务负责人参考。
- [解析质量评测标准](viking://resources/knowledge-parsing-one-page-source/04-quality/11-quality-evaluation/11-quality-evaluation.md) — 获取解析效果评测指标、评测流程与验收标准
- [主流解析工具能力对比](viking://resources/knowledge-parsing-one-page-source/04-quality/12-competitor-comparison/12-competitor-comparison.md) — 查看不同OCR、解析工具的能力差异与选型参考
- [服务可观测性与SLO规范](viking://resources/knowledge-parsing-one-page-source/04-quality/13-observability-slo/13-observability-slo.md) — 了解线上服务监控指标、告警规则与服务等级目标定义

### 5. 工程落地指引
本栏目提供服务工程化落地相关指导，适合AI运维、系统开发、合规、技术实施人员使用。
- [性能与成本优化方案](viking://resources/knowledge-parsing-one-page-source/05-engineering/14-performance-cost/14-performance-cost.md) — 获取服务吞吐量提升、资源成本管控的优化方法
- [私有化部署实施指引](viking://resources/knowledge-parsing-one-page-source/05-engineering/15-private-deployment/15-private-deployment.md) — 查看离线环境部署流程、环境要求与配置规范
- [安全合规管控方案](viking://resources/knowledge-parsing-one-page-source/05-engineering/16-security-compliance/16-security-compliance.md) — 了解数据处理、存储全流程的安全合规要求与实现方案

### 6. 运维运营参考
本栏目提供日常运维与产品迭代相关信息，适合运维、技术支持、产品研发人员查阅。
- [故障排查实操手册](viking://resources/knowledge-parsing-one-page-source/06-operations/17-troubleshooting-runbook/17-troubleshooting-runbook.md) — 查看各类解析任务异常、服务故障的排查流程与解决方法
- [产品迭代路线图](viking://resources/knowledge-parsing-one-page-source/06-operations/18-roadmap/18-roadmap.md) — 了解Atlas Parse服务的中长期功能规划与版本迭代安排

# Citations

[1] [knowledge-parsing-one-page-source](viking://resources/knowledge-parsing-one-page-source)

6.4 LLM Wiki测试

把 Aurora 项目状态、关键决策与风险整理为两页 Wiki Pages，验证多页面 + 页面间链接：

ov compile \
  --from viking://resources/compile-source \
  --to viking://resources/compile-wiki \
  --skill viking://user/skills/compile-wiki \
  --reason "把 Aurora 项目状态、关键决策和风险整理为两页 Wiki" \
  --wait --timeout 1800

产出：项目概览.md 与 决策风险.md 两页，通过 links 建立 Wiki 链接。本例覆盖 pages + links 的完整渲染链路：OKF frontmatter、Citations、Related pages 与 created / updated 判定。

7. 边界与限制

ov compile 只新增"任务编排 + 领域规则"这一层，底层 Skill 加载、OpenViking 读写、AgentLoop 推理都复用现有实现。为了避免单任务拖垮 Bot，CompileLimits 给了一组默认上限：

维度	默认值	作用
source_roots	16	单次任务来源目录上限
skill_files / 单文件 / 总大小	128 / 8 MiB / 32 MiB	Skill 加载规模
target_inventory_entries / target_catalog_pages	2000 / 10	目标目录枚举 / 进 prompt 的候选页数
initial_prompt_chars	200,000	初始 prompt 字符上限
tool_uri_count / 单次结果 / 累计结果	32 / 1 MiB / 8 MiB	只读工具的 URI 数与结果预算
output_pages / output_files / 总大小	64 / 64 / 4 MiB	产物规模上限
concurrent_tasks / task_runtime	4 / 1800 s	全局并发 / 单任务运行时长

并发采用两层：同一 to 目录串行（target lock），叠加全局信号量 4（concurrent_tasks）。身份方面，Bot Proxy 认证 CLI 请求并把当前用户身份转交 VikingBot，VikingBot 用同一身份完成所有读写；任务查询会校验创建者身份，无权与不存在统一返回 NOT_FOUND。

不做的事情也讲清楚：

• compile 不追求生成"更聪明"的 Wiki，只把"整理"这件事流水线化。质量上限由 Skill 决定。
• compile 不保证语义正确性——如果 from 材料本身有错，产出会保留原始引用，需要靠 update_uri 增量更新来修正。
• compile 目前不覆盖跨任务的依赖调度（例如"周报编译完再触发月报编译"），这类需求还是走外部编排。

8. Roadmap 与 Feedback

接下来还想推进：

• 与 ov watch 联动的自动化：来源目录发生变化时自动 trigger compile。

欢迎在 OpenViking 上直接跑一遍：

• 用你手边的 Skill 编译一个小知识库，看输出是否符合预期；
• 让 compile 生成一个 Skill 包，直接被下游 Agent 加载运行；

任何 use case都欢迎在这个 discussion 下面 reply。