Gitea Repo Ingest

SKILL.md

---
name: gitea_repo_ingest
description: Ingest public Git repositories or repositories on the configured Gitea server into the Research KB. Use for Git/Gitea source scans that need OpenClaw code understanding, incremental commit comparison, code repository overview pages, concept pages, resource pages, related wiki page updates, source traceability manifests, and Gitea-backed catalog/index updates.
---

# gitea_repo_ingest

## 核心职责

把一个可读取的代码仓库沉淀为团队知识库里的代码知识图谱。OpenClaw 负责深度代码理解和页面写作；本 skill 自带 Python 工具负责确定性动作：读取仓库、判断增量、采样证据、读取现有 catalog、写回 Markdown 页面、登记代码仓库来源、维护 `catalog.json`、维护 `index.md`、输出后端可读 JSON。

支持范围：

- 用户输入的公开 Git 仓库。
- 用户输入的、部署在已配置 `GITEA_URL` 上且 bot token 可访问的 Gitea 仓库。
- 同一 Gitea 的 HTTPS URL、`ssh://git@host/owner/repo.git`、`git@host:owner/repo.git` 会尽量转换成 bot token 可访问的 HTTPS URL。
- Git 交互式凭据提示必须关闭；认证失败、仓库不存在、无权限或网络不可达时应快速失败并脱敏错误。
- 其他外部私有仓库可以失败，不需要绕过权限。

不要把完整源码仓库复制到知识库。知识库保存的是可复用理解：仓库用途、业务/科研目标、功能模块、工作流、领域概念、资源依赖、接口数据、运行部署、设计取舍、风险限制、版本变化和页面关系。

写 `pages.json` 前先私下做一次知识图谱规划：代码库主页面是实体入口；`concepts/` 用来沉淀跨模块、跨资料可复用的抽象知识；`resources/` 用来登记具体可复用对象；`overview/` 用来维护团队级导航、系统地图、项目/主题综合和资料入口。不要为了满足格式机械建概念页、资源页或 overview 页；但当仓库理解显示某个已有主题、项目、架构概念、外部资源或团队导航需要更新时，应主动更新并建立跳转关系。

## 必须使用的脚本流程

不要直接手写 Gitea API。按准备、校验、写回流程执行：

1. 准备上下文：

   ```bash
   python3 scripts/run_task.py prepare --input <payload.json> --context-output <context.json>
   ```

   如果输出 JSON 的 `mode` 是 `skip`，说明最新 commit 与上一轮 snapshot 一致。此时脚本已经可以写出 skip 结果；直接让最终回复指向 payload 中的 `resultFile`。

2. 基于 `<context.json>` 进行代码理解，先私下规划代码库页、概念页、资源页、overview/项目页和已有相关页之间的关系，再生成 `<pages.json>`。`pages.json` 必须是纯 JSON 对象，不允许包含 Markdown 解释、注释、尾随逗号或未转义反斜杠；正文里如果出现代码片段、Windows 路径、正则表达式、JSON 字符串或反引号，必须使用 JSON writer/serializer 写文件，或完整转义。`pages.json` 必须包含 `pages[]`，每个页面包含 `path`、`title`、`type`、`content`、`keywords`、`relatedConcepts`、`relatedResources`、`relatedCodePages`、`relatedPages`。

3. 校验 `<pages.json>`，不写入知识库：

   ```bash
   python3 scripts/run_task.py validate-pages --input <payload.json> --context <context.json> --pages <pages.json>
   ```

   如果校验失败，必须修正 `<pages.json>` 并重新运行 `validate-pages`。只有校验成功后才能执行 `apply`。不要把 `validate-pages` 的 `success=true` 当作最终结果；`validate-pages` 不写 `resultFile`，必须继续运行 `apply`。

4. 写回知识库：

   ```bash
   python3 scripts/run_task.py apply --input <payload.json> --context <context.json> --pages <pages.json>
   ```

   `apply` 会写入 OpenClaw 生成的正常 Wiki 页面，重建 frontmatter，写入 `source_files/gitea_repo/<sourceId>-<repo-slug>.md` 来源登记文件，更新 `catalog.json` 和 `index.md`，写回一个稳定 `itemKey` 的仓库级 `sourceItems[]` 资料项，并把后端需要的 JSON envelope 写到 payload 的 `resultFile`。

5. 最终只回复 JSON，例如：

   ```json
   {"success": true, "resultFile": "<result.json>"}
   ```

如果脚本报错，修正输入或页面 JSON 后重试。不要在未完成代码理解时写低质量占位总览。

## 输入约定

任务 payload 通常包含：

- `taskId`: 后端任务 ID。
- `payloadFile`: 后端写出的 payload 路径。
- `resultFile`: 需要写入的结果 JSON 路径。
- `skill`: `gitea_repo_ingest`。
- `source.id`、`source.name`、`source.type`: 资料源信息。
- `source.config.repoUrl`: 用户填写且后端已校验可读的仓库地址。
- `source.config.defaultBranch`: 后端尝试识别的默认分支，可为空。
- `source.config.verifiedLatestCommit`: 新增资料源时后端探测到的 HEAD commit。
- `source.lastSnapshot.latestCommit`: 上一次成功扫描的 commit。
- `team.kbRepo`: 团队知识库仓库名。
- `platform.giteaUrl`、`platform.giteaOwner`、`sharedDir`: 平台上下文。

环境变量包括 `GITEA_URL`、`GITEA_BOT_TOKEN`、`GITEA_BOT_USERNAME`、`GITEA_ORG`、`TEAM_KB_REPO`、`OPENCLAW_SHARED_DIR`。

## 上下文读取策略

`prepare` 会先用 `git ls-remote --symref` 判断远端 HEAD。若远端 commit 与上一轮 snapshot 相同，直接 skip，不 clone。若首次扫描或 commit 变化，才进行浅克隆和证据采样。

`prepare` 会给出：

- `repo.worktree`: 临时工作树路径，OpenClaw 可以继续读取其中源码。
- `repo.latestCommit`、`repo.previousCommit`、`repo.changedFiles`、`repo.changedModules`。
- `repo.importantFiles`: README、依赖、构建、配置、部署、CI 等关键文件。
- `samples[]`: 脚本预采样的 README、配置、入口、测试、变更文件和结构性源码。
- `existingKb`: 现有 catalog 相关页面和已有代码库页。

初次扫描要重点读 README、目录树、依赖、构建、配置、部署、CI、入口、路由/API/CLI、任务调度、数据模型、核心服务和测试。若 `analysisLimits.largeRepository=true` 或仓库文件较多，不要读取完整 worktree，不要按文件逐个总结；优先使用 `samples`、`importantFiles`、`topLevel`、`languageProfile`，只额外读取少量高信号入口、配置、核心模块、数据模型和测试文件，并控制 `pages.json` 大小。

增量扫描要重点读 `repo.previousCommit..repo.latestCommit` 的 `changedFiles`、`diffSummary`、受影响模块的现有页面章节，以及新增、删除、重命名、配置变更、接口变更、数据结构变更、权限变更。

页面可以整体重写，但必须显式说明本次变化影响了哪些知识结论。未受影响章节应保持连续性，表现为增量更新，而不是像第一次见到仓库。

## 页面与来源写入范围

代码仓库入库通常至少维护：

- `code/<repo-slug>.md`: 代码仓库总览页，是本资料源的主页面。
- `concepts/<concept-slug>.md`: 概念页，记录稳定抽象知识节点。
- `resources/<resource-slug>.md`: 资源页，记录具体可复用对象。
- `overview/<slug>.md`: 当仓库显著影响团队级导航、系统地图、项目集合、资料入口或研究主题综合时，创建或更新 overview 页；没有这种综合价值时不要硬建。

如果代码理解表明其他 Wiki 页面也需要同步更新，可以写入正常知识库页面，例如 `projects/`、`tech-notes/`、`experiments/`、`papers/`、`surveys/`、`notes/`、`qa/`、`meetings/`、`overview/`。

`source_files/` 的处理规则：

- 代码仓库需要有来源登记文件，用于保留可追踪性。
- `apply` 脚本会自动写入 `source_files/gitea_repo/<sourceId>-<repo-slug>.md`。
- 该文件记录仓库 URL、访问模式、分支、commit、扫描时间、文件数量、顶层目录、语言分布、变更文件、变更模块、重要文件和生成页面。
- 不要把代码仓库里的源码文件逐个上传到 `source_files/`。
- 不要让 OpenClaw 在 `pages.json` 里直接写 `source_files/`；来源登记由脚本统一生成。

不要通过 `pages.json` 写系统文件，例如 `.kb/`、`catalog.json`、`index.md`。`catalog.json` 和 `index.md` 由 `apply` 脚本统一维护。

## 实体识别规则

概念页适合架构范式、机制、算法、模型、评估概念、研究问题、业务流程模式、数据处理范式、任务调度机制、权限模型、状态流转，以及多个模块共享且有代码证据支撑的抽象知识。

资源页适合数据集、模型、工具、库、框架、仓库、API、网站、论文、benchmark、平台服务、外部系统、协议、数据库、消息队列、云服务等具体可复用对象。

不要为普通目录、普通文件、普通类名、普通函数名、临时变量、一次性实现细节、无证据的通用知识建页。

## 代码库页面模板

`code/<repo-slug>.md` 是面向团队成员的代码仓库解读页，不是 README 复述、源码清单或纯技术审计。读者应能通过它理解这个仓库为什么存在、解决什么问题、由哪些模块组成、关键流程如何运转、沉淀了哪些知识、如何运行维护。

必须包含：

1. `## 仓库定位`: 仓库用途、业务/科研/工程目标、面向的用户/系统/流程、团队项目角色。
2. `## 核心价值与使用场景`: 主要能力，每个场景说明输入、输出、价值。
3. `## 功能模块总览`: 按功能/业务视角拆模块，不只按目录拆。
4. `## 领域概念与关键对象`: 核心概念、状态、角色、数据对象、任务类型、文件类型、外部对象。
5. `## 业务流程与工作流`: 端到端流程、触发条件、参与模块、关键步骤、结果、异常分支。
6. `## 知识产出与页面关系`: 本仓库会维护哪些知识库内容，以及页面之间如何关联。
7. `## 知识关联`: 相关概念、相关资源、相关项目/页面，使用 `[[path|标题]]`。
8. `## 技术实现概览`: 技术栈、运行时、框架、关键依赖、构建、测试、部署。
9. `## 架构与代码结构`: 系统边界、组件/模块、关键目录和关键文件。
10. `## 接口、数据与协议`: API、CLI、事件、消息、数据库表、文件格式、配置 schema、外部协议和数据流。
11. `## 配置、环境与权限`: 环境变量、配置文件、端口、存储路径、日志、权限模型、外部服务账号。不要写真实 token。
12. `## 构建、运行、测试与部署`: 命令必须来自 README、构建文件、CI、配置或源码证据。
13. `## 设计取舍与约束`: 设计选择、业务约束、架构约束、兼容要求、技术取舍。
14. `## 风险、限制与待确认点`: 业务正确性、数据一致性、权限安全、任务可靠性、可维护性、性能、可观测性。
15. `## 版本变化与知识演化`: commit 范围、变更文件、受影响模块、行为变化、知识结论变化。
16. `## 源码阅读路线`: 从业务理解到源码阅读的推荐路径。
17. `## 来源与证据索引`: README、配置、构建、CI、关键源码、测试、commit、diff、扫描时间，并引用 `source_files/gitea_repo/<sourceId>-<repo-slug>.md` 来源登记文件。

概念页必须包含：`定义与解释`、`在本仓库中的体现`、`证据片段`、`关联页面`、`边界与容易混淆点`、`来源与追踪`。

资源页必须包含：`资源说明`、`使用位置`、`与仓库功能的关系`、`关联概念与页面`、`复用价值与注意事项`、`来源与追踪`。

## 链接与 catalog 规则

正文内部链接使用 `[[path-without-md|显示标题]]`，例如 `[[code/research-kb-v2|Research KB V2]]`、`[[concepts/task-snapshot|任务扫描水位]]`、`[[resources/sqlite|SQLite]]`。

关系维护规则：

- 代码库页通过 `relatedConcepts` 关联概念页，通过 `relatedResources` 关联资源页。
- 概念页通过 `relatedCodePages` 反向关联支撑它的代码库页，通过 `relatedResources` 关联支撑它的资源。
- 资源页通过 `relatedCodePages` 反向关联使用它的代码库页，通过 `relatedConcepts` 关联它支撑的概念。
- 其他普通 Wiki 页面如果与代码库有关，用 `relatedPages` 表达，例如 `overview/`、`projects/`、`papers/`、`surveys/`、`meetings/`、`experiments/`、`tech-notes/`、`notes/`、`qa/`。
- 创建前先看 `existingKb.relatedPages` 和 catalog，发现同义页面时更新已有页，不重复建页。

`apply` 脚本会合并 catalog 并补齐 catalog 层面的反向关系，但页面正文里的解释性链接仍需要 OpenClaw 写清楚。

## pages.json 格式

```json
{
  "pages": [
    {
      "path": "code/example-repo.md",
      "title": "代码库：example-repo",
      "type": "code",
      "content": "# 代码库：example-repo\n\n## 仓库定位\n...",
      "sourceIds": [1],
      "relatedConcepts": ["concepts/task-snapshot.md"],
      "relatedResources": ["resources/sqlite.md"],
      "relatedCodePages": [],
      "relatedPages": ["overview/research-kb-v2.md"],
      "keywords": ["repository", "task", "snapshot"],
      "sourceStatus": "active"
    }
  ]
}
```

## 输出格式

`apply` 写出的 result 必须是单个 JSON 对象，包含：

```json
{
  "success": true,
  "processedSources": ["https://example.com/repo.git"],
  "createdPages": [],
  "updatedPages": [],
  "archivedFiles": ["source_files/gitea_repo/1-example-repo.md"],
  "skippedSources": [],
  "errors": [],
  "commitId": "",
  "snapshot": {
    "repoUrl": "https://example.com/repo.git",
    "latestCommit": "",
    "defaultBranch": "main",
    "changedModules": []
  },
  "sourceItems": [
    {
      "itemKey": "gitea_repo:1",
      "title": "example-repo",
      "sourceKind": "gitea_repo",
      "kind": "repository",
      "status": "ingested",
      "sha256": "<latestCommit>",
      "originalPath": "https://example.com/repo.git",
      "archivedPath": "source_files/gitea_repo/1-example-repo.md",
      "url": "https://example.com/repo.git",
      "externalId": "<latestCommit>"
    }
  ]
}
```

失败时 `success=false`，`errors[]` 写清原因。认证失败、仓库不存在、网络不可达、默认分支不存在、Gitea 写入失败都要明确说明。