Feishu Codex Skills

README

# Feishu Codex Skills

基于官方 Feishu OpenClaw 插件移植的一组 Codex skills。

这个仓库的目标不是重写一个新插件，而是参考 `skill-creator`，把插件里的 skill 整理成**符合 Codex 规范、可直接通过官方 Skill Installer 安装**的仓库。

## 先看这个：安装后并不能直接用

用户要真正用起来，前置有两步：

1. 先安装 skill
2. 再配置应用级凭证：
   - `FEISHU_APP_ID`
   - `FEISHU_APP_SECRET`

只有在 app 凭证存在之后，第一次调用用户态能力时，才会触发一次用户授权。

换句话说：

- **不是只做一次 user auth 就够**
- **也不是只安装 skill 就够**
- 必须先有 `FEISHU_APP_ID` + `FEISHU_APP_SECRET`
- 然后首次使用时完成一次用户授权
- 完成后，多个 skill 复用同一份 token

## 仓库结构

这个仓库按官方 Skill Installer 的方式组织：

- skills 放在 `skills/.curated/<skill-name>`
- 每个可执行 skill 安装后仍然是单目录自包含
- repo 根目录只保留发布层内容，不往 skill 子目录塞额外发布文档

仓库包含：

- `internal/`：共享 runtime 真值源码
- `scripts/`：同步、校验、安装命令辅助脚本
- `skills/.curated/`：真正对外发布的 skill
- `README.md`、`LICENSE`

## 已包含的 Skills

- `feishu-bitable`
- `feishu-calendar`
- `feishu-channel-rules`
- `feishu-create-doc`
- `feishu-fetch-doc`
- `feishu-im-read`
- `feishu-task`
- `feishu-troubleshoot`
- `feishu-update-doc`

## 鉴权模型

### 1. 应用级凭证

必填：

- `FEISHU_APP_ID`
- `FEISHU_APP_SECRET`

可选：

- `FEISHU_BASE_URL`
- `FEISHU_OAUTH_STORE_DIR`

如果缺少 `FEISHU_APP_ID` 或 `FEISHU_APP_SECRET`，任何需要联网的 skill 都会直接返回 `missing_env`。

### 2. 用户授权

有了 app 凭证之后，第一次真正调用用户态能力时，会触发 Feishu Device Flow 用户授权。

如果想提前做一次完整预授权，可以使用 `feishu-troubleshoot`：

```bash
node ~/.codex/skills/feishu-troubleshoot/scripts/troubleshoot.js '{"action":"preauth_all"}'
```

### 3. token 持久化与复用

默认共享 store 路径：

```text
${CODEX_HOME:-~/.codex}/feishu-oauth/<appId>
```

这意味着：

- skill 可以独立安装
- 授权状态不独立
- 同一 `appId` 下多个 skill 共享同一份 token
- 不需要每个 skill 各授一次权

只有这些情况才会再次授权：

- 换了 `FEISHU_APP_ID`
- 改了 `FEISHU_OAUTH_STORE_DIR`
- refresh token 彻底过期
- 新 skill 需要此前未授权的新 scope

## 用官方 Skill Installer 安装

正式仓库：

```text
FakeGeek92/feishu-codex-skills
```

### 列出可安装 skills

```bash
python3 ~/.codex/skills/.system/skill-installer/scripts/list-skills.py \
  --repo FakeGeek92/feishu-codex-skills \
  --path skills/.curated
```

### 安装单个 skill

```bash
python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo FakeGeek92/feishu-codex-skills \
  --path skills/.curated/feishu-task
```

### 一次安装全部 9 个 skill

```bash
python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo FakeGeek92/feishu-codex-skills \
  --path \
  skills/.curated/feishu-bitable \
  skills/.curated/feishu-calendar \
  skills/.curated/feishu-channel-rules \
  skills/.curated/feishu-create-doc \
  skills/.curated/feishu-fetch-doc \
  skills/.curated/feishu-im-read \
  skills/.curated/feishu-task \
  skills/.curated/feishu-troubleshoot \
  skills/.curated/feishu-update-doc
```

安装完成后，重启 Codex 以加载新 skills。

### GitHub API 403

如果 `list-skills.py` 或 `install-skill-from-github.py` 返回 GitHub API `403`，按官方 installer 说明设置：

- `GITHUB_TOKEN`
- 或 `GH_TOKEN`

再重跑即可。

## 本地校验

```bash
npm run sync-runtime
python3 scripts/quick_validate.py skills/.curated/feishu-task
npm test
node scripts/validate-all.mjs
```

## 已验证的事情

- 官方 `list-skills.py` 已能从 GitHub 正式仓库列出全部 9 个 skill
- 官方 `install-skill-from-github.py` 已验证：
  - 安装单个 skill
  - 一次安装全部 9 个 skill
- 安装后的 skill 目录自包含，wrapper 不依赖 repo 外部路径
- 缺失 `FEISHU_APP_ID` / `FEISHU_APP_SECRET` 时，wrapper 会返回标准 `missing_env`
- 使用真实 app 凭证时，`feishu-troubleshoot doctor` 已成功拿到 tenant auth 和 bot 信息
- `preauth_all` 已验证会正常发起 Device Flow

## 仍需用户自己完成的一步

首次用户授权必须由真实用户自己在 Feishu 里确认，我不能替用户点击完成这一步。

因此当前“最难伪造”的最后验证是：

1. 用户手工完成一次 `preauth_all` 或首次用户态 skill 授权
2. 再调用第二个不同 skill
3. 确认没有再次要求授权
4. 重启 Codex 或新开会话后再调用，确认 token 仍被复用

代码和存储路径已经按这个模型实现，但最后这一步必须由真实用户交互完成。

## 说明

- 本仓库不会修改源插件目录 `extensions/feishu-openclaw-plugin`
- `SKILL.md` 正文尽量保持插件原文，Codex 适配只放在 frontmatter 和顶部薄说明层
- 上游文档中仍会提到 `feishu-doc-media`、`feishu-wiki-space-node` 等组合工具；本仓库当前不单独发布对应 standalone wrapper
- 临时验证仓库 `FakeGeek92/feishu-codex-skills-smoke` 只用于跑通 installer 通路，不是最终对外安装入口