[RFC] Watch Management API (REST + ov CLI + MCP) #2104

t0saki · 2026-05-18T04:12:39Z

t0saki
May 18, 2026
Maintainer

RFC: Watch Management API（REST + ov CLI + MCP）

作者 / Author: zhengxiao.wu
状态 / Status: Draft
日期 / Date: 2026-05-18
范围 / Scope: 三个控制面（REST API / ov CLI / MCP）的 watch 管理接口设计

1. 摘要 / Executive Summary

add_resource 已支持通过 watch_interval 参数开启周期性自动刷新（由 WatchScheduler + WatchManager 实现，全量重拉模式）。但watch 任务一旦创建，三个控制面（REST / ov CLI / MCP）都缺乏对外的管理接口——

没有 list：用户/agent 无法盘点自己开了哪些 watch
没有独立的 pause / resume：只能通过 watch_interval <= 0 间接取消
没有 delete：同上
没有 trigger：手动刷新无入口
没有 update：改间隔/原因/指令只能重建

后端 WatchManager 实际上已具备所有必要能力。本 RFC 提议在 REST 层补齐 /watches 系列管理端点作为基础设施，ov CLI 做完整 parity 镜像作为 power user 工具，**MCP 仅暴露最小闭环（list + cancel）**以控制模型认知负担。三个面各自服务于不同用户群，零后端逻辑改动。

2. 动机 / Motivation

2.1 现状对照表（截至 main 当前状态）

控制面	创建 watch	列表	查询单个	暂停	删除	改间隔	手动触发
REST	✅ `POST /resources` 带 `watch_interval`	❌	❌	❌	⚠️ 间接（`watch_interval≤0`）	⚠️ 间接（重传）	❌
MCP	❌ 完全无 watch 参数	❌	❌	❌	❌	❌	❌
ov CLI	✅ `ov add-resource --watch-interval`	❌	❌	❌	⚠️ 间接	⚠️ 间接	❌

⚠️ 标记表示效果能达成，但需要重新触发完整 add_resource 流程（重新解析、分块、向量化），代价高且体验差。

MCP 现状特别说明：main 分支上 MCP 的 add_resource 工具完全没有 watch_interval 或等价参数，因此 MCP agent 无法创建任何 watch 任务。本 RFC 的 MCP 相关变更（§4.7）是净新增能力，不是对既有功能的改造。

2.2 真实用户故事

盘点：「我上个月给几个 GitHub repo 开了 watch，现在想看下还有哪些资源在自动同步」
临时停用：「这个项目最近不活跃了，watch 暂停几周，又不想丢失任务记录」
紧急刷新：「上游刚 release，我想立刻刷一次，不想等 24h」
改间隔：「日级太频繁，改成每周一次」
合规审计：管理员需要审视租户内所有自动同步任务，目前没有任何 API 能列出

2.3 安全/合规视角

用户在 OpenViking 上开了 watch 后，没有 API 可以盘点和停止——这从合规审计角度也站不住脚（数据自动同步任务必须可见、可控、可停）。

3. 目标与非目标 / Goals & Non-Goals

3.1 Goals

提供 REST API：list / get / patch / delete / trigger 五个端点
提供 ov CLI 子命令 ov watch *：与 REST 端点 1:1 镜像（power user 工具）
提供 MCP 工具：仅 list_watches + cancel_watch 两件套（最小闭环）
复用 WatchManager 已有的 public 方法，零业务逻辑新增
多租户隔离沿用 WatchManager._check_permission 现有规则（account_id / user_id / agent_id 三维）
持久化沿用现有 viking://resources/.watch_tasks.json 机制

3.2 Non-Goals（本 RFC 不涉及）

❌ 前端 Web UI（独立工单）
❌ Webhook / 事件总线推送 watch 执行结果（独立提案）
❌ 增量更新 / 差分刷新（这是 watch_scheduler 引擎级改造）
❌ 跨租户管理后台 / 配额面板（运维侧需求，独立提案）

4. 设计 / Design

4.1 REST API 端点

所有端点遵循 OpenViking 现有 router 约定（openviking/server/routers/resources.py 风格）。

方法	路径	行为	复用的后端方法
`GET`	`/watches`	列出当前 ctx 可见的 watch，支持 `?active_only=true` 过滤	`WatchManager.get_all_tasks`
`GET`	`/watches/{task_id}` 或 `/watches?to_uri=...`	查单个任务	`get_task` / `get_task_by_uri`
`PATCH`	`/watches/{task_id}` 或 `/watches?to_uri=...`	修改 `watch_interval` / `is_active` / `reason` / `instruction` 等	`update_task`
`DELETE`	`/watches/{task_id}` 或 `/watches?to_uri=...`	永久删除任务	`delete_task`
`POST`	`/watches/{task_id}/trigger` 或 `/watches/trigger?to_uri=...`	立即触发一次刷新	`WatchScheduler.schedule_task`

双键设计：`task_id` 与 `to_uri` 同时支持

事实基础：WatchManager 已维护两个索引（watch_manager.py:205,402）：

_tasks: dict[task_id → WatchTask] 主索引
_uri_to_task: dict[to_uri → task_id] 反向索引

两者都是 O(1)，双键支持无额外存储成本。

调用约定（每个单资源端点二选一）：

方式	语法	适用场景
Path 参数	`/watches/{task_id}`	程序化（已经知道 task_id，如刚从 list 拿到）
Query 参数	`/watches?to_uri=<URI>`	用户友好（记得 URI，不记得 UUID）

冲突规则：如果同时传入 {task_id} path 和 ?to_uri= query，返回 400（避免歧义；强制调用方明确意图）。

为什么不让 to_uri 直接作为路径参数：viking://resources/foo/bar 含 :// 和多级 /，需要双重 URL-encode 才能塞进路径，对人/工具/curl 都不友好。Query 参数能用浏览器原生 encoding，体验更顺。

4.2 统一响应 schema

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "to_uri": "viking://resources/volcengine/OpenViking",
  "path": "https://github.com/volcengine/OpenViking",
  "parent_uri": null,
  "watch_interval": 1440.0,
  "is_active": true,
  "reason": "Track upstream changes",
  "instruction": "",
  "created_at": "2026-05-15T10:23:45Z",
  "last_execution_time": "2026-05-17T10:23:45Z",
  "next_execution_time": "2026-05-18T10:23:45Z"
}

字段全部来自 WatchTask 数据类（openviking/resource/watch_manager.py:28-102），无需新增。

列表端点返回 {"tasks": [...], "total": N} 结构，留作未来加分页时不破坏 schema。

4.3 权限模型

完全复用 WatchManager._check_permission (watch_manager.py:273-308)：

ROOT：所有租户全部 watch
ADMIN：同 account 全部 watch
USER：仅自己 (account_id, user_id, agent_id) 创建的 watch

每个 endpoint 在调用 WatchManager 方法时传入当前 ctx，权限校验由后端自动处理，router 层无需重复实现。

4.4 PATCH 语义细节

PATCH /watches/{task_id} 请求体可包含任意子集：

{
  "watch_interval": 4320,   // 改间隔到 3 天
  "is_active": false,       // 同时暂停
  "reason": "Project archived",
  "instruction": ""
}

字段缺失 = 不变。watch_interval 与 is_active 是正交的：

watch_interval 控制频率
is_active 控制是否参与调度

这样可以"暂停但保留间隔配置"，恢复时 {"is_active": true} 一行搞定。

4.5 触发限流（Open Question 之一）

POST /watches/{task_id}/trigger 会强制开始一次全量重拉。是否要在 router 层限流（例如每个 task 每 5 分钟最多触发一次）？详见 §6。

4.6 ov CLI 子命令

设计原则：CLI 是 power user 工具，与 REST 端点全 parity。模型认知负担不是约束，功能完整性优先。

命令	映射的 REST 端点	备注
`ov watch ls [--active-only] [--to-uri=PAT] [--format=table\|json]`	`GET /watches`	默认 table，`--format=json` 给脚本管道
`ov watch show <task-id\|to-uri>`	`GET /watches/{id}`	支持双键
`ov watch rm <task-id\|to-uri> [--yes]`	`DELETE /watches/{id}`	`--yes` 跳过确认
`ov watch pause <task-id\|to-uri>`	`PATCH is_active=false`
`ov watch resume <task-id\|to-uri>`	`PATCH is_active=true`
`ov watch set-interval <task-id\|to-uri> <minutes>`	`PATCH watch_interval`
`ov watch trigger <task-id\|to-uri>`	`POST .../trigger`	立即刷新

双键参数设计：positional 参数自动识别——见到 viking:// 前缀按 URI 走 ?to_uri= 查找，否则当 task_id。CLI 用户记 URI 比记 UUID 容易。

输出格式：默认人类可读 table；--format=json 输出与 REST schema 一致的 JSON 数组，方便 jq 处理与脚本编排。

4.7 MCP 工具

设计原则：MCP 工具描述会进入模型 system prompt，每个工具都消耗上下文且增加决策成本。所以严格砍到"闭环最小集合"。

4.7.1 给 MCP `add_resource` 净新增 watch 能力

main 当前 MCP add_resource 仅有 path + description 两个参数，没有任何 watch 入口。本 RFC 新增两个参数：

watch_interval: float = 0：与 REST/CLI 命名完全一致，0 = 不开 watch，>0 触发周期性全量重拉
to: str = ""：当 watch_interval > 0 时必填（服务端硬约束，需要稳定 URI 作为刷新目标）

为什么用 watch_interval 而不是 watch: bool：

与 REST/CLI 三面术语统一，文档/记忆一份就够
让 agent 显式选间隔（默认 0 = 不 watch），避免"True/False 背后藏着隐式 24h"的暗坑
不在 MCP 层强制最小间隔；通过 docstring 引导 agent 选 >=1440 分钟，特殊场景由 agent 自决

async def add_resource(
    path: str,
    description: str = "",
    watch_interval: float = 0,   # 0 = 不开 watch；>0 触发周期性全量重拉
    to: str = "",                # watch_interval > 0 时必填
) -> str: ...

4.7.2 新增工具（仅两个）

工具	签名	用途
`list_watches()`	无参	列出当前 ctx 可见的 watch 摘要（to_uri, interval, next_run）
`cancel_watch(to_uri: str)`	单参	按 URI 删除 watch 任务

cancel_watch 用 to_uri 作主键（不暴露 task_id）：agent 记不住 UUID，URI 是它已经在用的标识符。

4.7.3 主动砍掉的 MCP 工具

砍掉的	替代路径	理由
`pause_watch / resume_watch`	cancel + 重新 `add_resource(watch_interval=N, to=...)`	"暂停几周再恢复"是人类用户需求，agent 几乎用不到；要做就走 CLI
`refresh_watch_now`	`add_resource(path=..., to=同 URI)` 自然触发全量重拉	没有强场景；"立刻刷新"的判断应该是人决定，不是 agent
`set_interval`	cancel + `add_resource(watch_interval=N, to=...)`	改间隔成本低，重建即可
`show_watch`	`list_watches` 已含全部字段	模型从列表里挑

闭环：add_resource(watch_interval>0) ↔ cancel_watch ↔ list_watches，三个动词构成"加—查—停"的对偶，认知模型最小。

4.8 三个面的职责分工

控制面	受众	设计取舍	完整性
REST API	集成方、CLI、MCP、未来 Web UI 的基础设施	完整、版本化、schema 严格、HTTP idiomatic	★★★★★ 全功能
ov CLI	开发者、运维、CI 脚本	全 REST parity 镜像；双键输入；JSON/table 双输出	★★★★★ 全功能
MCP	LLM agent	严格最小化（list + cancel + add 中的 watch_interval）；不暴露 task_id；零暗默认	★★★ 最小闭环

agent 想做"高级控制"（暂停、改间隔、立即触发）时，应在错误/帮助消息中明确引导用户走 ov CLI，避免诱导模型自行组合多步操作。

4.9 兼容性

POST /resources 的 watch_interval 参数保留，沿用现有语义（>0 创建/更新，≤0 取消）
新增 /watches 端点不破坏现有 Rust CLI 调用方
MCP 端：当前 add_resource 工具仅有 path + description，本 RFC 净新增 watch_interval + to 参数为 opt-in（默认 0，行为完全不变），现有 agent 代码无需改动
文档中推荐新代码使用 /watches 系列做管理；watch_interval 作为"一步开 watch"的便利写法
长期是否 deprecate POST /resources.watch_interval，留作 §6 Open Question

5. 实现拆分 / Implementation Phases

按依赖顺序拆分。每阶段独立 PR，CLI/MCP 依赖 REST 端点先就位。

阶段	内容	估算	依赖
P1	REST `GET /watches`、`GET /watches/{id}`、`DELETE /watches/{id}` + 单测	1 PR	—
P2	REST `PATCH /watches/{id}` + `POST /watches/{id}/trigger` + 单测	1 PR	P1
P3	MCP `add_resource` 新增 `watch_interval` + `to` 参数（净新增，main 当前 MCP 无 watch 能力）	1 PR	—
P4	MCP 新增 `list_watches` + `cancel_watch` 两个工具	1 PR	P1
P5	ov CLI `ov watch ls/show/rm/pause/resume/set-interval/trigger` 子命令组	1 PR	P1 + P2

备注：P3 可与 P1 并行，但应一起 release，避免 main 上 MCP 仍无 watch 能力的窗口期。

6. 未决问题 / Open Questions

双键冲突处理：当前提议同时支持 {task_id} path 和 ?to_uri= query，二选一；同传报 400。是否更宽松（query 覆盖 path 静默生效）会更友好？还是更严格（query 仅作 list 过滤，不在单资源端点出现）？
PATCH watch_interval=0 的语义：算暂停（is_active=false 但保留任务）还是删除？建议：暂停。删除明确走 DELETE
POST /resources.watch_interval 长期归宿：保留为便利接口 / 软弃用 / 硬弃用？
trigger 配额：全量重拉成本高，是否需要每 task / 每 user 限流？
列表分页：get_all_tasks 当前一次性返回所有任务，未来任务量大时是否需要 ?limit&offset 或 cursor？
批量操作：是否需要 POST /watches:batch_delete、POST /watches:batch_pause？还是逐个调用即可？
审计日志：所有变更操作是否要记录到 telemetry？（trigger 尤其值得追踪）

7. 备选方案 / Alternatives Considered

方案 A：在 `POST /resources` 上堆更多 watch 控制参数

即新增 watch_pause: bool、watch_trigger_now: bool 等。
否决：语义混乱，违背 REST 资源化原则，单个端点承载多重职责。

方案 B：完全废弃 `watch_interval`，只允许独立 `/watches`

要求所有"开 watch"都走"先 add → 再 POST /watches"两步。
否决：破坏现有 CLI / 插件 / 文档的向后兼容；两步流程对终端用户不友好。

方案 C（本 RFC 采纳）：并行存在

POST /resources 保留 watch_interval 作为"一步式"便利接口
/watches 作为正式的管理面
文档明确推荐：新代码用 /watches，但 watch_interval 不弃用

8. 风险与缓解 / Risks & Mitigations

风险	缓解
`DELETE /watches/{id}` 误删	后端 `delete_task` 已有权限校验；考虑加 `?confirm=true` 显式确认参数
`POST .../trigger` 被滥用导致算力浪费	§6 Open Question 4，按需引入限流
任务量大时 `GET /watches` 返回过大	§6 Open Question 5，留接口形状可演化为分页
多客户端竞态修改同一 task	`update_task` 当前是 last-write-wins；如有需要再加 ETag / version 字段

9. 验证 / Verification

实现完成后，至少覆盖：

单测：每个端点的正例 + 权限拒绝 + 404
集成测试：完整 lifecycle（add → list → patch interval → pause → resume → trigger → delete）
多租户隔离：USER A 看不到 USER B 的 watch
持久化：服务重启后 watch 任务从 viking://resources/.watch_tasks.json 恢复，新端点能正确读取

10. 参考资料 / References

后端实现：
- openviking/resource/watch_manager.py —— public API 及权限模型
- openviking/resource/watch_scheduler.py:113-140 —— schedule_task 立即触发
- openviking/resource/watch_storage.py —— VikingFS 持久化
现有触发点：
- openviking/server/routers/resources.py:84,180 —— AddResourceRequest.watch_interval
- openviking/service/resource_service.py:106-289 —— add_resource 中的 watch 处理
设计参考：
- bot/docs/rfc-openviking-cli-ov-chat.md —— 项目内 RFC 格式模板

欢迎评论。 重点欢迎对 §6 各 Open Question 的意见，以及 §7 中是否还有更优的备选方案被遗漏。

t0saki · 2026-05-18T10:16:08Z

t0saki
May 18, 2026
Maintainer Author

实施偏差备忘（v2 — 2026-05-18）

PR #2110 已合 5 个 phase 全量落地，过程中相对 RFC 正文产生 4 处设计调整，记录在此供后来读者对照。RFC 正文未改，以本评论 + PR 代码为准。

1. §4.1 双键设计：放宽为「不一致才 400」

原文："如果同时传入 {task_id} path 和 ?to_uri= query，返回 400"
实际：两键都给且指向同一任务 → 200（cross-key 校验通过）；指向不同任务 → 400
理由：作为「我同时有两份信息，帮我交叉校验防 stale id」的用例更有价值；无歧义的同源请求无需拒绝

2. §4.5 trigger 语义：明确为 fire-and-forget

原文没明说 trigger 是同步还是异步
实际：POST /watches/{id}/trigger 通过 asyncio.create_task 派发，HTTP 立刻返回 scheduled=true；后台任务持强引用（避免弱引用 GC），完成后回调 discard
理由：WatchScheduler.schedule_task 内部 await _execute_task(...) 实际阻塞到全量重拉完成，HTTP 不该陪绑

3. §4.6 ov CLI 命令树：嵌套到 `ov task` 下；`set-interval` → `update`

原文：ov watch ls/show/rm/pause/resume/set-interval/trigger（顶级）
实际：
- 顶级 Watch 移到 TaskCommands::Watch，所有命令变为 ov task watch *
- set-interval <key> <minutes> 替换为 update <key> [--interval N] [--active true|false] [--reason ...] [--instruction ...]，一统 PATCH 支持的全部可变字段
- pause / resume 作为高频快捷动词保留
理由：watch（订阅）与 task（执行记录）同属「后台异步活动」域，归一更清晰；update 一统避免每加字段就新增 set-X 动词

4. §5 实施拆分：合并为一个 PR

原文：P1-P5 各自一个 PR
实际：单个 PR feat: Watch Management API — REST + ov CLI + MCP (RFC #2104) #2110 涵盖 P1-P5，按 phase 分 commit
理由：用户偏好对相关改动避免过度拆分

未变化

§4.7 MCP 工具集（add_resource 新增 watch_interval + to、list_watches、cancel_watch）与原文完全一致。

§6 Open Questions 仍开放，等代码合入后另议。

0 replies

Navigation Menu

Uh oh!

[RFC] Watch Management API (REST + ov CLI + MCP) #2104

Uh oh!

{{title}}

Uh oh!

Replies: 1 comment

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

[RFC] Watch Management API (REST + ov CLI + MCP) #2104

Uh oh!

t0saki May 18, 2026 Maintainer

RFC: Watch Management API（REST + ov CLI + MCP）

1. 摘要 / Executive Summary

2. 动机 / Motivation

2.1 现状对照表（截至 main 当前状态）

2.2 真实用户故事

2.3 安全/合规视角

3. 目标与非目标 / Goals & Non-Goals

3.1 Goals

3.2 Non-Goals（本 RFC 不涉及）

4. 设计 / Design

4.1 REST API 端点

双键设计：task_id 与 to_uri 同时支持

4.2 统一响应 schema

4.3 权限模型

4.4 PATCH 语义细节

4.5 触发限流（Open Question 之一）

4.6 ov CLI 子命令

4.7 MCP 工具

4.7.1 给 MCP add_resource 净新增 watch 能力

4.7.2 新增工具（仅两个）

4.7.3 主动砍掉的 MCP 工具

4.8 三个面的职责分工

4.9 兼容性

5. 实现拆分 / Implementation Phases

6. 未决问题 / Open Questions

7. 备选方案 / Alternatives Considered

方案 A：在 POST /resources 上堆更多 watch 控制参数

方案 B：完全废弃 watch_interval，只允许独立 /watches

方案 C（本 RFC 采纳）：并行存在

8. 风险与缓解 / Risks & Mitigations

9. 验证 / Verification

10. 参考资料 / References

Replies: 1 comment

Uh oh!

t0saki May 18, 2026 Maintainer Author

实施偏差备忘（v2 — 2026-05-18）

1. §4.1 双键设计：放宽为「不一致才 400」

2. §4.5 trigger 语义：明确为 fire-and-forget

3. §4.6 ov CLI 命令树：嵌套到 ov task 下；set-interval → update

4. §5 实施拆分：合并为一个 PR

未变化

t0saki
May 18, 2026
Maintainer

双键设计：`task_id` 与 `to_uri` 同时支持

4.7.1 给 MCP `add_resource` 净新增 watch 能力

方案 A：在 `POST /resources` 上堆更多 watch 控制参数

方案 B：完全废弃 `watch_interval`，只允许独立 `/watches`

t0saki
May 18, 2026
Maintainer Author

3. §4.6 ov CLI 命令树：嵌套到 `ov task` 下；`set-interval` → `update`