Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

docs(contributing): add maintainer routing map (#1519)

yeyitech8b3de1f3b12a
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 770ed2ae7..ff6df08b9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -289,6 +289,79 @@ Common fixtures are defined in `tests/conftest.py`, including `client` (initiali
---
+## Maintainer Routing and Contribution Entry
+
+### Contributor-Facing Module Map
+
+If you are not sure where your question, issue, or PR belongs, start with this table:
+
+| Domain | Area | Primary Contact |
+|--------|------|-----------------|
+| Integration | Bot | `@yeshion23333` |
+| Integration | OpenClaw Plugin | `@Mijamind719`, `@wlff123` |
+| Platform | Framework / Multi-tenant / Resources / Session | `@qin-ctx` |
+| Platform | Incremental / Scheduled Update | `@myysy` |
+| Knowledge | Memory | `@chenjw` |
+| Knowledge | Retrieval / Directory Semantics | `@zhoujh01` |
+| Storage & Security | Virtual FS / File Encryption | `@chuanbao666`, `@baojun-zhang` |
+
+If the area is still unclear, mention one of the cross-module maintainers listed below.
+
+### Maintainer Routing Map
+
+Use this table when routing issues, PRs, or design questions to a more specific owner:
+
+| Domain | Subarea | Representative Paths or Topics | Primary Contact | Backup / Cross-Module |
+|--------|---------|--------------------------------|-----------------|-----------------------|
+| Integration | Bot Runtime | `bot/vikingbot`, `bot/bridge`, deployment scripts, bot docs | `@yeshion23333` | `@chenjw` |
+| Integration | OpenClaw Plugin | `examples/openclaw-plugin`, installation, remote mode, compatibility | `@Mijamind719`, `@wlff123` | `@LinQiang391` |
+| Platform | Server & Multi-tenant | `openviking/server`, `openviking/service`, auth, identity, admin, tenant boundary | `@qin-ctx` | `@MaojiaSheng` |
+| Platform | Resource & Session Lifecycle | `openviking/resource`, `openviking/session`, resource ingestion, session lifecycle | `@qin-ctx` | `@MaojiaSheng` |
+| Platform | Incremental & Scheduled Update | `openviking/resource/watch_manager.py`, `openviking/resource/watch_scheduler.py` | `@myysy` | `@qin-ctx` |
+| Knowledge | Memory Engine | `openviking/session/memory`, `memory_extractor.py`, `memory_deduplicator.py` | `@chenjw` | `@qin-ctx` |
+| Knowledge | Retrieval & Directory Semantics | `openviking/retrieve`, intent analysis, hierarchical retrieval, directory semantics | `@zhoujh01` | `@qin-ctx` |
+| Storage & Security | VFS / AGFS Path Semantics | `openviking/storage`, `openviking/pyagfs`, filesystem behavior, path semantics | `@chuanbao666`, `@baojun-zhang` | `@zhoujh01` |
+| Storage & Security | Encryption & Data Safety | `openviking/crypto`, file encryption, storage safety | `@chuanbao666`, `@baojun-zhang` | `@zhoujh01` |
+
+For areas without a stable owner yet, cross-module maintainers will help route the request first.
+
+### Cross-Module Maintainers
+
+- `@MaojiaSheng`
+- `@qin-ctx`
+- `@zhoujh01`
+
+Cross-module maintainers help with issue routing, cross-cutting design questions, and fallback review support.
+
+### How to Ask for Help
+
+- If you already know the affected module, mention it in the issue or PR description.
+- If you are unsure about the module, describe the use case and affected behavior first.
+- If you want to work on an issue, leave a comment before starting, especially for cross-module changes.
+- If your PR spans multiple areas, call out the primary affected domain in the description.
+
+### Contribution Entry Labels
+
+Issue templates already classify reports such as `bug`, `enhancement`, and `question`. Maintainers may also use the following labels to make contribution entry clearer:
+
+| Label | Meaning |
+|-------|---------|
+| `good first issue` | Newcomer-friendly work with clear scope and acceptance criteria |
+| `help wanted` | Tasks that benefit from contributors who already know the codebase or review style |
+| `needs-design` | Work that needs maintainer clarification before implementation |
+| `needs-review` | Pull requests waiting for the first review round |
+
+### Contributor Growth Path
+
+The project uses a practical contribution path so contributors can see what “next step” looks like:
+
+| Stage | Typical Signals | Common Next Step |
+|-------|------------------|------------------|
+| New Contributor | First issue or first PR, often docs, tests, or scoped fixes | Start with `good first issue` items and get familiar with local workflow |
+| Active Contributor | One or more merged contributions | Pick up `help wanted` work in an area you already touched |
+| Module Contributor | Repeated contributions in the same subarea | Help with triage, reproduction, docs, or review comments in that area |
+| Backup Reviewer Candidate | Stable contribution record in one subarea | Help with first-pass review, routing, and contributor support |
+
## Contribution Workflow
### 1. Create a Branch
diff --git a/CONTRIBUTING_CN.md b/CONTRIBUTING_CN.md
index 2cb777f76..909f3d240 100644
--- a/CONTRIBUTING_CN.md
+++ b/CONTRIBUTING_CN.md
@@ -289,6 +289,79 @@ class TestAsyncOpenViking:
---
+## 维护者路由与贡献入口
+
+### 面向贡献者的模块地图
+
+如果你还不确定问题、issue 或 PR 属于哪个方向,可以先看这张表:
+
+| 领域 | 模块 | 主要联系人 |
+|------|------|------------|
+| Integration | Bot | `@yeshion23333` |
+| Integration | OpenClaw Plugin | `@Mijamind719`、`@wlff123` |
+| Platform | Framework / Multi-tenant / Resources / Session | `@qin-ctx` |
+| Platform | Incremental / Scheduled Update | `@myysy` |
+| Knowledge | Memory | `@chenjw` |
+| Knowledge | Retrieval / Directory Semantics | `@zhoujh01` |
+| Storage & Security | Virtual FS / File Encryption | `@chuanbao666`、`@baojun-zhang` |
+
+如果还是无法判断归属,可以直接 @ 下方的跨模块维护支持成员。
+
+### 面向维护者的路由表
+
+当需要把 issue、PR 或设计问题路由到更具体的 owner 时,可以参考下表:
+
+| 领域 | 子域 | 代表路径或主题 | 主要联系人 | 备援 / 跨模块支持 |
+|------|------|----------------|------------|-------------------|
+| Integration | Bot Runtime | `bot/vikingbot`、`bot/bridge`、部署脚本、bot 文档 | `@yeshion23333` | `@chenjw` |
+| Integration | OpenClaw Plugin | `examples/openclaw-plugin`、安装、remote mode、兼容性 | `@Mijamind719`、`@wlff123` | `@LinQiang391` |
+| Platform | Server & Multi-tenant | `openviking/server`、`openviking/service`、auth、identity、admin、租户边界 | `@qin-ctx` | `@MaojiaSheng` |
+| Platform | Resource & Session Lifecycle | `openviking/resource`、`openviking/session`、资源导入、session 生命周期 | `@qin-ctx` | `@MaojiaSheng` |
+| Platform | Incremental & Scheduled Update | `openviking/resource/watch_manager.py`、`openviking/resource/watch_scheduler.py` | `@myysy` | `@qin-ctx` |
+| Knowledge | Memory Engine | `openviking/session/memory`、`memory_extractor.py`、`memory_deduplicator.py` | `@chenjw` | `@qin-ctx` |
+| Knowledge | Retrieval & Directory Semantics | `openviking/retrieve`、意图分析、分层检索、目录语义 | `@zhoujh01` | `@qin-ctx` |
+| Storage & Security | VFS / AGFS Path Semantics | `openviking/storage`、`openviking/pyagfs`、文件系统行为、路径语义 | `@chuanbao666`、`@baojun-zhang` | `@zhoujh01` |
+| Storage & Security | Encryption & Data Safety | `openviking/crypto`、文件加密、存储安全 | `@chuanbao666`、`@baojun-zhang` | `@zhoujh01` |
+
+对于暂时还没有稳定 owner 的方向,先由跨模块维护支持成员协助路由。
+
+### 跨模块维护支持
+
+- `@MaojiaSheng`
+- `@qin-ctx`
+- `@zhoujh01`
+
+跨模块维护支持成员主要负责 issue 路由、跨模块设计问题,以及 owner 繁忙时的补位 review。
+
+### 如何获得帮助
+
+- 如果你已经知道受影响模块,请在 issue 或 PR 描述中直接写明。
+- 如果暂时无法判断模块归属,优先描述使用场景和受影响行为。
+- 如果你想认领某个 issue,建议先留言说明,尤其是跨模块改动。
+- 如果你的 PR 涉及多个模块,请在描述中标明主要影响域。
+
+### 贡献入口标签
+
+Issue 模板已经会对 `bug`、`enhancement`、`question` 等问题类型做基础分类。为了让贡献入口更清晰,维护者还可能补充以下标签:
+
+| 标签 | 含义 |
+|------|------|
+| `good first issue` | 适合新贡献者上手,范围清晰且验收标准明确 |
+| `help wanted` | 更适合已经熟悉仓库或 review 风格的贡献者参与 |
+| `needs-design` | 实现前需要维护者先澄清设计边界 |
+| `needs-review` | 正在等待首轮 review 的 PR |
+
+### 贡献成长路径
+
+我们希望贡献成长路径足够实际,让贡献者能清楚看到下一步可以怎么参与:
+
+| 阶段 | 常见信号 | 下一步建议 |
+|------|----------|------------|
+| 新贡献者 | 第一次提 issue 或 PR,通常从文档、测试或小范围修复开始 | 从 `good first issue` 入手,熟悉本地开发和提交流程 |
+| 活跃贡献者 | 已经有一个或多个合入贡献 | 在自己熟悉的模块下开始认领 `help wanted` |
+| 模块贡献者 | 在同一子域持续贡献 | 开始参与该模块的 issue 分流、问题复现、文档补充或 review 建议 |
+| 备援 Reviewer 候选 | 在某个子域形成稳定贡献记录 | 协助首轮 review、问题路由和贡献者支持 |
+
## 贡献流程
### 1. 创建分支