Init User

SKILL.md

# Skill: init_user — paper-kb 用户初始化

## 用途

paper-kb 是一个科研知识库系统：用户在飞书发论文链接/PDF 即可自动入库到自己的
Gitea 私有仓库，用自然语言即可查询。本 Skill 负责其中的**用户初始化**环节：
检查当前飞书用户是否已注册，未注册则引导注册，并自动创建其专属的
Gitea 知识库仓库和飞书多维表格。

## 触发条件

**Activate when（满足任一）：**
- 用户发出任何与 paper-kb 相关的请求（存论文、查文献、发 arxiv 链接、上传 PDF
  等），且尚未确认该用户已注册 —— 此时先用本 Skill 的 check 模式查询注册状态。
- check 结果为未注册（registered=false），需要引导用户注册。
- 用户的消息中包含 Gitea 用户名和研究方向（形如「Gitea用户名：xxx」「研究方向：yyy」），
  这是注册引导后用户的回复，进入 register 流程。
- 用户明确要求初始化/注册/重置知识库。

**Do NOT activate when：**
- 用户已确认注册（本次会话中 check 已返回 registered=true），且消息是存文档或
  查询请求 —— 应交给 ingest_paper 或 query_papers Skill。
- 用户的消息与 paper-kb 完全无关（闲聊、其他任务）。

## 前置依赖

- **current_user_open_id**：当前飞书用户的 open_id（形如 `ou_xxx`）。
  由你（OpenClaw）从消息上下文的 sender 字段获取，作为 `--open_id` 参数传给脚本。
  在网页对话中测试时若拿不到 open_id，用 `webchat_test` 作为测试值。
- 本 Skill 根目录需有 `.env` 文件（从 `env-example.txt` 复制），包含
  `GITEA_URL` 和 `GITEA_ADMIN_TOKEN`。

## 脚本调用方式

工作目录：本 Skill 根目录（`~/.openclaw/workspace/skills/init_user/`）。

### 模式1：查询注册状态（任何 paper-kb 请求的第一步）

```bash
python3 scripts/init_user.py --check --open_id <open_id>
```

输出 JSON：
- `{"success": true, "registered": true, "user": {...}, "repo_url": "..."}`
  → 已注册。把 `user` 里的 `gitea_username`、`research_direction`、
    `feishu_app_token`、`feishu_table_id` 记住，供本次会话后续使用，
    然后继续处理用户的原始请求（交给对应 Skill）。
- `{"success": true, "registered": false}`
  → 未注册。进入下面的「注册引导流程」。

### 模式2：注册新用户

```bash
python3 scripts/init_user.py --register --open_id <open_id> \
    --gitea_username <用户名> --research_direction "<研究方向>"
```

输出 JSON 关键字段：
- `success: true, already_registered: false` → 注册成功，`repo_url` 是仓库地址，
  `feishu_table_pending: true` 表示飞书表格还没建（接下来执行「创建飞书表格」步骤）。
- `success: true, already_registered: true` → 用户之前已注册，直接告知即可。
- `success: false` → 看 `error` 字段：
  - `gitea_user_not_found`：Gitea 上没有这个用户名，把 `message` 转告用户，
    让其确认注册后重发。
  - `username_taken`：该 Gitea 账号已被别的飞书用户绑定，转告用户。
  - `not_admin`：机器人 token 不是站点管理员 —— 这是系统配置问题，把 `message`
    转告用户（管理员），流程终止。
  - 其他：把 `message` 转告用户。

### 模式3：回填飞书表格信息（创建表格成功后调用）

```bash
python3 scripts/init_user.py --update-feishu --open_id <open_id> \
    --feishu_app_token <app_token> --feishu_table_id <table_id>
```

## 完整执行流程

### A. 收到任何 paper-kb 相关消息时

1. 运行模式1（check）。
2. registered=true → 记住用户信息，把消息交给对应的业务 Skill，本 Skill 结束。
3. registered=false → 发送以下引导消息，本轮结束，等待用户回复：

> 你好！我是科研知识库助手 paper-kb 📚
> 检测到你还没有自己的知识库，先完成一次性注册（1分钟）：
>
> 1️⃣ 打开 {GITEA_URL} 注册一个 Gitea 账号
> 2️⃣ 注册完成后，回复我两条信息：
>    Gitea用户名：你的用户名
>    研究方向：一句话描述（如"灵巧手触觉传感器"）
>
> 之后发论文链接给我就能自动入库了！

（{GITEA_URL} 用 .env 中配置的实际地址替换。）

### B. 用户回复了用户名和研究方向

1. 从用户消息中提取 `gitea_username` 和 `research_direction`。
   提取不到完整两项时，礼貌地请用户补全缺失项，不要猜测。
2. 运行模式2（register）。
3. 注册成功且 `feishu_table_pending: true` → 执行步骤 C（创建飞书表格）。
4. 注册失败 → 按上文错误对照表回复用户。

### C. 创建飞书多维表格（可选步骤，失败不阻塞）

1. 调用你的飞书工具 `feishu_bitable_app`（action: create）创建多维表格，
   名称：`paper-kb-<gitea_username>`。
2. 在表格中创建数据表，字段一次性定义完：

| 字段名 | 类型 | type值 |
|--------|------|--------|
| 标题 | 文本 | 1 |
| 类型 | 单选（选项：论文/调研报告/会议纪要/技术文档/其他） | 3 |
| 关键词 | 文本 | 1 |
| 相关性评分 | 数字 | 2 |
| 存入时间 | 日期 | 5 |
| Gitea链接 | 超链接 | 15 |
| arxiv_id | 文本 | 1 |

3. 拿到返回的 `app_token` 和 `table_id`，运行模式3（update-feishu）回填。
4. **如果飞书工具调用失败（权限未开通等）：跳过，不要重试超过1次，不要报错
   中断**。在最终回复中注明"飞书表格暂未启用，不影响知识库使用"。

### D. 回复用户

注册全部完成后回复（按实际情况调整）：

> ✅ 知识库初始化完成！
> 📂 你的仓库：{repo_url}
> 🎯 研究方向：{research_direction}
> 📊 飞书表格：已创建 /（暂未启用，不影响使用）
>
> 现在可以：
> · 发 arxiv 链接或上传 PDF，说"帮我存入知识库"
> · 直接提问，如"有没有关于力控制的文献"

### E. 处理用户的原始请求

如果用户最初的消息里带有实际任务（例如第一条消息就是 arxiv 链接），初始化完成后
**继续处理那条原始请求**（交给 ingest_paper / query_papers),完成后再次回复结果。

## 注意事项

- 脚本所有输出都是单行 JSON，stdout 里出现非 JSON 内容时视为脚本异常，
  把原始输出转告用户并建议联系管理员。
- 不要把 token、open_id 等敏感信息展示给用户。
- 同一会话中 check 过一次后，结果可以复用，不必每条消息都重复 check。