# SotoGoal 接入指引（给 Agent）

SotoGoal（所及）的任务/知识/目标可经三条路读写，按你的能力选一条：

| 你的能力 | 走哪条 |
| --- | --- |
| 能执行 shell 命令、有 skills 目录（Claude Code 一类） | 装 skill：第 1–5 节 |
| 是支持远端 MCP 的客户端 | 填 MCP 地址：第 6 节 |
| 以上都不能，但能发 HTTP 请求 | 令牌 + REST：第 7 节 |

API 文档（REST 契约：端点、参数、错误码）是 `sotogoal` skill 的 SKILL.md：<https://sotogoal.com/skill/sotogoal/SKILL.md>。

## 装 skill

SotoGoal 提供三个 skill，装好后你就能替用户读写他的 SotoGoal 任务/知识/目标：

- `sotogoal` — 基础 REST API 契约 + 薄 CLI（其余两个 skill 依赖它）
- `sotogoal-report` — 日报/周报（从任务/目标/流转事件聚合）
- `sotogoal-interview` — 目标访谈（引导用户梳理目标，生成正文 + KR）

> 产品旧名 FlowOS，skill 旧名 `flowos` / `flowos-report` / `flowos-interview`。装过旧版的机器上那三个目录仍在、也仍能用 —— 见下面第 5 节。

## 1. 下载到 skills 目录

Claude Code 及兼容环境的 skills 目录：全局 `~/.claude/skills/`，或项目级 `.claude/skills/`。其他环境放到你的 skill 加载路径。

一键（默认装到 `~/.claude/skills/`，可用第一个参数改目录）：

```bash
curl -fsSL https://sotogoal.com/skill/install.sh | sh
```

或手动逐个下载：

```bash
BASE=https://sotogoal.com/skill
DEST=~/.claude/skills
mkdir -p $DEST/sotogoal $DEST/sotogoal-report $DEST/sotogoal-interview
curl -fsSL $BASE/sotogoal/SKILL.md              -o $DEST/sotogoal/SKILL.md
curl -fsSL $BASE/sotogoal/sotogoal.mjs          -o $DEST/sotogoal/sotogoal.mjs
curl -fsSL $BASE/sotogoal-report/SKILL.md       -o $DEST/sotogoal-report/SKILL.md
curl -fsSL $BASE/sotogoal-interview/SKILL.md    -o $DEST/sotogoal-interview/SKILL.md
```

## 2. 凭证

请用户在 SotoGoal 网页「账户设置 → API 令牌」创建令牌（scope 按需勾选；日常建议 `tasks`/`notes`/`goals` 的 read+write 加 `tags:read`，删除权限按需单独授予），然后设置环境变量：

```bash
export SOTOGOAL_TOKEN=fos_live_…
```

令牌只在创建时展示一次；缺凭证时向用户要，不要猜。

旧变量名 `FLOWOS_TOKEN` / `FLOWOS_BASE_URL` / `FLOWOS_NO_UPDATE_CHECK` 仍然可用：新名优先，新名未设置或为空时回落到旧名。已经写进 shell 配置或 CI secret 的不必急着改。

## 3. 验证

```bash
node ~/.claude/skills/sotogoal/sotogoal.mjs whoami
```

打印出本令牌的 scope、可达空间与默认空间即装好。

CLI 需要 Node 18+；**没有 node 的环境不用装 CLI**，直接调 REST，见第 7 节。

## 4. 更新

本地安装的 skill 是一次性快照，站点改了它不会跟。**更新 = 重跑第 1 步同一条命令**（幂等，覆盖全部文件）：

```bash
curl -fsSL https://sotogoal.com/skill/install.sh | sh -s -- <你的 skills 目录>
```

覆盖后 `sotogoal.mjs` 下一条命令即生效；`SKILL.md` 则要**重新读一遍**才会进入当前会话的上下文。

不必自己盯着：服务端会报出**它自己那份** skill 的版本，CLI 拿它跟本地这份比，需要更新时会往 stderr 打印一行更新提示（可通过 `SOTOGOAL_NO_UPDATE_CHECK=1` 关闭更新检测）。**不用 CLI 的调用方**（直接 curl API）没有这个自动提示，判断方法见 `sotogoal/SKILL.md` 中的「你手上这份是不是旧的」。

## 5. 从旧名升级

重装**不会**清掉旧目录：`flowos/` / `flowos-report/` / `flowos-interview/` 会原封不动留着，而且仍然可用（API 契约没变）。于是 skills 目录里并排两份描述几乎一样的 skill，agent 加载哪份看运气。

`install.sh` 检测到它们时会在末尾报出来并给一条现成的 `rm -rf`，但**不替你删**。确认没往那几个目录里放别的东西后自己执行即可。

旧站点路径 `/skill/flowos/…` 保留重定向到新路径，装着旧版的 CLI 印出来的那条 `SKILL.md` 链接仍然打得开。

## 6. MCP 客户端：填地址

请用户在客户端里添加一个远端 MCP 服务器（名称自定），地址：

```
https://sotogoal.com/mcp
```

授权按客户端能力二选一：

- **支持 MCP 的 OAuth 授权**：只填地址。首次连接时客户端会打开 SotoGoal 授权页，用户在那里登录、勾选权限与空间后授权。已授权的应用在「账户设置 → API 令牌 → 已授权的应用」查看与撤销。
- **不支持 OAuth、但能自定义请求头**：带 `Authorization: Bearer <API 令牌>`，令牌的创建见第 2 节。

工具列表由服务端下发，无需安装或更新。MCP 工具覆盖常用操作；MCP 未提供的操作走第 7 节的 REST。

## 7. 只能发 HTTP 请求：令牌 + REST

1. 请用户按第 2 节创建一枚 API 令牌并提供给你。
2. 每个请求带 `Authorization: Bearer <令牌>`，地址以 `https://sotogoal.com/api/` 开头。先调一次确认令牌可用：

   ```bash
   curl -s "https://sotogoal.com/api/me" -H "Authorization: Bearer <令牌>"
   ```

3. 端点、参数与错误码见开头的 API 文档。