# 让 Codex 连接七一记知识库

公开安装入口：**https://71j.cn/agent-setup**。本页无需登录，也不包含任何用户令牌。

把下面这句话发给你个人电脑上的 Codex：

> 请阅读 https://71j.cn/agent-setup（网页工具打不开时用本机终端读取同一链接），按说明在这台电脑安装并连接 AIKB 技能。完成自动配置后打开浏览器让我登录授权，再验证知识检索和待办查询。

Codex 会安装技能、选择本机空闲回调端口并发起登录。你只需在 **71j.cn** 登录并确认授权。不需要创建自己的应用、不需要填写 client_secret、不需要配置 8765 端口，也不需要自己搭服务。

## 给 Codex：安装并连接

此流程适用于用户要求在**个人电脑本机**安装 AIKB 技能。使用本机终端和本机浏览器；云端沙箱与 SSH 服务器的 127.0.0.1 不是用户电脑。先确认执行环境；如果当前工具只能在远程运行，请把本页安装步骤交给电脑上的 Codex 或本机终端，不能宣称已配置好用户电脑。

### 1. 检查环境和安装来源

网页抓取工具可能无法访问本域名。此时使用本机终端的 Python urllib.request 或现有 HTTP 下载工具读取同一个 HTTPS 链接，不要把网页工具失败当作站点不存在。仍保持 HTTPS 证书校验。

需要 Python **3.9+**（只使用标准库），macOS / Linux 通常使用 `python3`，Windows 可用 `py -3`。不要为了安装此技能更改 Codex 的模型、系统提示或全局权限设置。

下载并读取以下公开资源：

- 发布清单：https://71j.cn/integrations/aikb-agent.manifest.json
- 安装脚本：https://71j.cn/integrations/install-aikb-agent.py
- 技能包：https://71j.cn/integrations/aikb-agent.zip
- 技能说明：https://71j.cn/integrations/skills/aikb-agent/SKILL.md

先检查安装脚本内容，用清单里的 `installer_sha256` 校验其 SHA-256。脚本只从 `https://71j.cn` 下载清单与技能 ZIP，拒绝 HTTP 重定向，校验包和每个文件的 SHA-256，限定 ZIP 文件路径；不会访问用户凭证。下载或校验失败就停止，不运行未校验的文件。

然后用本机 Python 执行已下载的安装脚本。例如，保存到临时目录后的命令为：

```sh
python3 /临时目录/install-aikb-agent.py
```

安装器默认写入 `~/.agents/skills/aikb-agent/`，跨项目生效。重复安装相同版本直接返回 ready；升级或替换已有目录前，保留备份到 `~/.agents/skill-backups/`，不覆盖凭证。现有技能目录为符号链接时会停止，请检查来源，不要绕过。

### 2. 读取已安装技能并检查连接

读取安装器输出 `skill_path` 下的 `SKILL.md`。以后命令中的脚本路径均相对此目录，不要求用户切换项目目录；在命令行中正确引用绝对路径。

```sh
python3 ~/.agents/skills/aikb-agent/scripts/aikb.py call GET me
```

已授权时返回当前用户、权限和时区，直接进入第 4 步。未授权或授权过期时执行下一步。不输出 credentials.json、access/refresh token、PKCE verifier 或带 code 的回调 URL。

Codex 应自动发现新技能；暂未显示时，当前会话先直接读取安装的 SKILL.md 并使用脚本，不必等待技能列表刷新。后续重新启动 Codex 即可发现。

### 3. 发起用户登录授权

```sh
python3 ~/.agents/skills/aikb-agent/scripts/aikb.py login --no-browser --timeout 600
```

让此进程保持运行，在本机浏览器打开它输出的 **https://71j.cn/oauth.php?...** 授权链接。用户在生产站点登录并决定是否授予页面列出的知识与待办权限；不要代用户跳过同意页面，也不要用网页 Cookie、管理员会话或设备 Token 代替 OAuth。

没有浏览器工具时，向用户展示 HTTPS 授权链接让其在同一电脑打开。用户自己在本机终端运行 `login`（不加 `--no-browser`）可自动打开默认浏览器。

`127.0.0.1:随机端口/callback` 是本机短暂接收回调的地址。脚本会自动校验 state、使用 PKCE 换码、保存令牌并关闭监听；用户无需复制授权码。等待登录进程明确报告成功后，再运行 `call GET me`。取消或 10 分钟超时都可重新运行 login，不能把“已打开授权页”报告为“已连接成功”。

公共桌面应用标识固定为 `aikb_agent_desktop`，由管理员在生产注册一次。每位用户、每台电脑各有独立授权；无需分发或填写应用密钥。令牌默认保存到 `~/.config/aikb-agent/credentials.json`，在支持 POSIX 权限的系统上为 0600，Windows 使用当前用户配置目录并遵循其 ACL。可用 AIKB_CONFIG 指向自己的凭证文件。请勿复制令牌到另一台电脑。

### 4. 验证并开始使用

完成用户授权后，只做只读验证：

```sh
python3 ~/.agents/skills/aikb-agent/scripts/aikb.py call GET me
python3 ~/.agents/skills/aikb-agent/scripts/aikb.py call GET knowledge --query limit=1
python3 ~/.agents/skills/aikb-agent/scripts/aikb.py call GET knowledge/search --query q=用户提供的关键词 --query mode=keyword --query limit=1
python3 ~/.agents/skills/aikb-agent/scripts/aikb.py call GET todos --query status=open --query limit=1
```

没有用户提供的检索词时，先询问要找的内容；安装不依赖非空搜索结果。空知识库/空待办属于有效成功结果。验证中不要顺带创建、编辑、删除或展示无关的私人正文。确认响应 success=true 后，再报告技能路径、已连接账号和能做的操作，不回显令牌。

以后用户可以说：

- 用 $aikb-agent 查找项目部署方案。
- 把下面这段笔记保存到七一记，标签是“项目”。
- 修改这篇知识的标题，查看并恢复上一个版本。
- 查看回收站并恢复这篇知识。
- 列出今天到期的待办，把指定事项标为完成。

按技能规则处理用户请求：写操作使用幂等键，修改/删除先读取版本，发生版本冲突时重新读取并合并；永久删除知识不开放。API 参考：https://71j.cn/integrations/skills/aikb-agent/references/api.md

## 后续授权与问题处理

访问令牌 1 小时，脚本自动刷新，单次登录授权最长 90 天；到期重新登录即可。后台「应用接入 → AIKB Agent → 查看授权」可撤销单次登录的授权，其他电脑不受影响。技能默认提供知识检索、创建、编辑、标签、历史版本、回收站恢复，以及独立/关联待办管理。

- 提示尚未授权：运行 login，完成浏览器同意后再查询。
- 等待回调超时：确认浏览器和脚本在同一电脑；重新发起，不复用旧页面。
- 401 / invalid_grant：授权已过期、撤销或检测到刷新令牌重用，重新登录；不要复制旧凭证重试。
- 403 insufficient_scope：说明缺少的权限，按用户需要重新发起授权；不要用其他登录凭证绕过。
- 下载校验失败：可能发布尚未同步完成，稍后重试；安装器不会替换现有技能。
- 脚本无法访问网络：按本机 Codex 的网络权限流程处理；不要关闭 TLS 验证或扩大全局权限。

## 系统维护记录

本页权威源是仓库 `data/readme/AGENT_SKILL_SETUP.md`，生产 `/agent-setup` 与 `/connect.php?format=agent` 返回同一份内容。维护操作和应用注册见 `deploy/AGENT_API.md`；接口契约见 `docs/agent-openapi.json`。

修改技能、API 参考或安装器后，执行 `python3 scripts/build-agent-skill.py --version 发布版本` 生成 ZIP 和清单，执行 Python 回归与技能校验，再随代码发布。不要手工给 ZIP 加凭证、缓存或额外文件。分发文本由 .gitattributes 强制保持 LF，避免 Windows Git 换行转换破坏 SHA-256。生产管理员选择「AIKB 桌面技能」注册应用；无需给每位用户新建应用。

安装目录和发现方式依据 [OpenAI 官方技能文档](https://learn.chatgpt.com/docs/build-skills)；公共应用与临时本机回调依据 [RFC 8252](https://www.rfc-editor.org/rfc/rfc8252.html)。