Kb Maintenance

SKILL.md

---
name: kb_maintenance
description: Maintain the Research KB team-level overview pages from the Gitea-backed knowledge base. Use for OpenClaw console cron/scheduled maintenance runs that should inspect the existing team KB, reason over recent or important wiki changes, incrementally update only the six overview pages, write hidden maintenance status files for frontend display, and avoid rewriting ordinary knowledge pages.
---

# kb_maintenance

## 职责边界

`kb_maintenance` 是一个由 OpenClaw 控制台 cron 直接触发的团队知识库维护 skill。它不依赖 Java 后端调度，也不要求后端传入 payload/resultFile。

OpenClaw 负责真正的维护判断：读取团队知识库、识别最近新增或更新的重要 wiki 页面、比较现有 overview 内容、分析团队知识库当前状态，然后增量编译 `overview/` 下的六个团队级页面：

- `overview/team-overview.md`
- `overview/research-map.md`
- `overview/recent-updates.md`
- `overview/source-summary.md`
- `overview/open-questions.md`
- `overview/roadmap.md`

脚本只提供可靠工具和护栏：列出 KB 页面、读取 OpenClaw 选择的页面、校验 overview 草稿只能写六个固定路径、写回 Gitea、维护 `catalog.json`/`index.md`、写隐藏状态文件。脚本不替 OpenClaw 决定哪些知识重要，也不生成 overview 正文。

本 skill 不扫描资料源、不拉取飞书/腾讯会议/Git 仓库、不入库新资料、不写 `projects/`、`papers/`、`code/`、`meetings/`、`concepts/`、`resources/` 或 `qa/` 普通知识页。它只根据已经存在的 KB 页面维护团队级 overview。

## 运行环境

OpenClaw cron 运行环境需要：

- `GITEA_URL`
- `GITEA_BOT_TOKEN`
- `GITEA_BOT_USERNAME`
- `TEAM_KB_REPO`

可选：

- `GITEA_ORG`
- `TEAM_NAME`
- `TEAM_RESEARCH_DIRECTION`
- `OPENCLAW_SHARED_DIR`

没有 payload 时，脚本从环境变量构造最小运行配置。若人工或后端传入 `--input payload.json`，脚本也兼容，但这不是本 skill 的默认模式。

## 推荐工作流

不要把最终回复强制写成 JSON，也不要把最终对话文本当作交付物。OpenClaw 可以正常用自然语言进行分析和草稿编写，但成功运行后的持久输出应只落在 wiki 页面和隐藏状态文件里。为了降低 JSON 转义和长 Markdown 字符串导致的问题，overview 正文应写成普通 Markdown 草稿文件，而不是塞进大 JSON。

建议 cron prompt 使用这个流程：

```bash
python3 scripts/run_task.py inspect --output maintenance-inspection.json --quiet
```

OpenClaw 阅读 `maintenance-inspection.json`，其中包含当前六个 overview 页面、`catalog.json` 页面元数据、页面类型分布、近期页面列表、上次维护状态、可读取页面路径清单。然后由 OpenClaw 决定需要进一步读取哪些页面：

```bash
python3 scripts/run_task.py read-pages --paths projects/a.md,meetings/b.md --output maintenance-evidence.json --quiet
```

OpenClaw 根据检查结果和证据，自行增量编写六个 overview 草稿到一个目录，例如：

```text
overview-drafts/
  overview/
    team-overview.md
    research-map.md
    recent-updates.md
    source-summary.md
    open-questions.md
    roadmap.md
```

最后运行：

```bash
python3 scripts/run_task.py validate-pages --draft-dir overview-drafts --quiet
python3 scripts/run_task.py apply --draft-dir overview-drafts --summary "本次维护摘要" --quiet
```

若 `inspect`、`read-pages`、草稿编写或 `validate-pages` 阶段失败，OpenClaw 应运行：

```bash
python3 scripts/run_task.py record-failure --summary "本次维护失败" --error "<错误原因>" --quiet
```

这样即使没有进入 `apply`，前端也能从隐藏状态文件看到失败，而不是继续显示上一次成功。

`apply` 会只写六个允许的 overview 页面，为页面补 frontmatter，正文 hash 未变化时跳过写入，更新 `catalog.json` 和 `index.md`，并写 `.kb/maintenance/kb_maintenance_status.json` 与 `.kb/maintenance/kb_maintenance_runs.json`。

## 可选 JSON 草稿

为了兼容脚本测试或特殊自动化，也支持：

```bash
python3 scripts/run_task.py validate-pages --pages overview-pages.json
python3 scripts/run_task.py apply --pages overview-pages.json --summary "本次维护摘要"
```

但 cron 中优先使用 Markdown 草稿目录。JSON 草稿只适合短内容或脚本生成内容，不建议让 OpenClaw 手写包含长 Markdown 正文的大 JSON。


## 输出原则

这个 cron skill 的实际输出不是一段对话文本，也不是给后端消费的 result JSON。成功运行后的持久产物只有：

- 六个 `overview/` wiki 页面被按需更新。
- `catalog.json` 和 `index.md` 被按需更新。
- `.kb/maintenance/kb_maintenance_status.json` 被更新为最近一次状态。
- `.kb/maintenance/kb_maintenance_runs.json` 被追加维护历史。

因此，OpenClaw 在 `apply` 成功后不要写解释性长回复。若控制台必须有最终消息，使用极简结束语即可，例如 `done`；不要把本次维护摘要、页面列表或 JSON 结果作为最终对话输出。成功摘要应进入隐藏状态文件的 `summary` 字段。脚本命令在 cron 中推荐加 `--quiet`，成功时不输出 stdout；失败时保留错误输出用于排查。
## 六个页面的写作目标

`team-overview.md`：团队 KB 的首页级说明。说明团队名称、研究方向、当前知识库主要内容、入口页面和阅读路径。不要把所有页面列表都塞进来。

`research-map.md`：研究方向、关键问题、项目、方法、概念、资源之间的地图。按主题组织，不按文件夹机械列目录。

`recent-updates.md`：近期重要新增或更新。基于 `catalog.updatedAt`、页面 `updatedAt`、最近页面内容和上次维护状态，只放真正值得团队注意的变化。

`source-summary.md`：资料来源覆盖情况。根据页面 `sources`、`sourceIds`、页面类型分布、source traces 归纳本地文件、Git/Gitea、腾讯会议、飞书等资料覆盖。没有证据时写缺口。

`open-questions.md`：当前知识库暴露出的研究问题、工程风险、资料缺口、待确认事项。必须来自页面中的开放问题、风险、不确定性或缺失信息，不要凭空发明。

`roadmap.md`：知识库维护路线。基于当前 KB 状态提出短期/中期/长期整理动作，例如补充资料、合并重复页、加强页面链接、完善来源追踪、更新项目页。避免空泛口号。

## 增量更新规则

更新每个 overview 页面前，先比较：

- 现有 overview 页面已经表达了什么。
- 上次维护状态文件记录了什么。
- `catalog.json` 中页面数量、类型分布、更新时间和关系字段发生了什么变化。
- 最近新增/更新的页面是否改变团队级理解。
- 项目、会议、代码、论文、实验、概念和资源页中是否出现新的风险、开放问题或路线变化。

写回时遵循：保留仍准确的旧段落，合并重复列表，用新证据替换过时结论，对证据不足处明确标注“待补充/待确认”，不凭空补外部常识，不把一次普通小更新夸大成团队路线变化。

## 隐藏状态文件

`apply` 成功时必须写以下文件；若维护在 `apply` 前失败，必须用 `record-failure` 写同一组文件，供后端从 Gitea 读取并在前端任务中心或设置页展示：

- `.kb/maintenance/kb_maintenance_status.json`
- `.kb/maintenance/kb_maintenance_runs.json`

状态字段包括：

```json
{
  "skill": "kb_maintenance",
  "status": "succeeded",
  "trigger": "openclaw_cron",
  "lastStartedAt": "2026-07-09T00:00:00Z",
  "lastFinishedAt": "2026-07-09T00:02:00Z",
  "changedPages": ["overview/research-map.md"],
  "unchangedPages": ["overview/team-overview.md"],
  "commitId": "git-commit",
  "summary": "本次维护摘要",
  "errors": []
}
```

后端不要直接读 OpenClaw 本地日志或 SQLite；读取这两个隐藏 JSON 文件即可得到最近一次维护状态和历史记录。

## 硬性规则

- 只允许创建或更新六个固定 `overview/*.md` 文件。
- OpenClaw 不要手写 `catalog.json`、`index.md` 或 `.kb/maintenance/*.json`；这些由 `apply` 写。
- 不要写 `source_files/`、`.kb/` 其他文件、`README.md`、`AGENTS.md` 或普通知识页正文。
- 不要写 token、密钥、完整本机绝对路径、临时共享目录路径或大段原文复制。
- 不要删除历史知识页；发现过时内容时在 overview 中说明状态或维护建议。
- 写库前必须运行 `validate-pages`，通过后再运行 `apply`。

## 完成前检查

- 已读取 inspection 和必要证据页，而不是只凭目录猜测。
- 六个 overview 草稿都在允许路径内。
- 每个页面都有清晰标题和正文。
- 页面内容基于 KB 证据，不凭空扩展项目进展。
- 没有修改普通知识页、source files 或系统说明文件。
- 成功路径已运行 `validate-pages` 和 `apply`；失败路径已运行 `record-failure`。
- 已确认 `apply` 成功写入隐藏状态文件；cron quiet 模式下不依赖 stdout 判断成功。