epismo-basics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Epismo Basics

Epismo 基础

Shared reference for all Epismo skills. Covers connection, surface conventions, scope, share URL resolution, and error handling.

Skills that build on this:

Project Tracking — tasks, goals, notes, planning
Workflow Pack — workflow pack discovery and release
Context Pack — context packs, session handoff

所有Epismo skill的共享参考文档，涵盖连接方式、界面规范、范围、共享URL解析及错误处理。

基于此构建的Skills：

项目追踪 — 任务、目标、笔记、规划
工作流包 — 工作流包的发现与发布
上下文包 — 上下文包、会话移交

Connection

连接方式

CLI and MCP are two interfaces to the same Epismo service — same account, same data, same tools. There is one Epismo account; the difference is only how you connect.

When both are available, use CLI. If only MCP is available, use MCP. Never use both in the same session.

CLI和MCP是同一Epismo服务的两种接口——使用相同的账户、相同的数据、相同的工具。一个Epismo账户仅对应一套服务，二者的区别仅在于连接方式。

**若两种方式均可用，优先使用CLI。**若仅MCP可用，则使用MCP。切勿在同一会话中同时使用两者。

Auth

认证

CLI (preferred):

bash

epismo login --email you@example.com   # OTP flow (default, no browser)
epismo login --browser                  # browser-based flow
epismo whoami                           # verify

MCP: add

https://mcp.epismo.ai

as an MCP server in your client. Authentication is handled automatically via OAuth.

CLI（优先选择）：

bash

epismo login --email you@example.com   # OTP流程（默认，无需浏览器）
epismo login --browser                  # 基于浏览器的流程
epismo whoami                           # 验证登录状态

MCP：在客户端中添加

https://mcp.epismo.ai

作为MCP服务器。认证通过OAuth自动处理。

Surface Conventions

界面规范

Surface	Pattern	Example
`cli`	`epismo <resource> <action> [--flags]`	`epismo pack search --type context`
`mcp`	`epismo_<resource>_<action>` + JSON	`epismo_pack_search`

MCP tool name = CLI command with spaces and hyphens replaced by underscores. Conceptual payloads are the same across surfaces; CLI flags are mapped into the JSON shape used by API/MCP.

界面	模式	示例
`cli`	`epismo <resource> <action> [--flags]`	`epismo pack search --type context`
`mcp`	`epismo_<resource>_<action>` + JSON	`epismo_pack_search`

MCP工具名称 = 将CLI命令中的空格和连字符替换为下划线后的名称。不同界面的概念性负载相同；CLI标志会映射为API/MCP使用的JSON结构。

Pack Aliases

包别名

Packs can be fetched by a short alias instead of a full ID. Pass

--alias <name>

(or

alias

parameter in MCP) wherever

--id

is accepted on

get pack

. To create and manage aliases, see Pack Alias.

包可通过短别名而非完整ID获取。在

get pack

命令中，任何接受

--id

的位置都可传入

--alias <name>

（或MCP中的

alias

参数）。如需创建和管理别名，请查看包别名。

CLI Input Conventions

CLI输入规范

```
--input '<json>'
```
— inline JSON
```
--input @path/to/file.json
```
— from file
```
--input -
```
— from stdin
Explicit flags override fields in
```
--input
```
.

```
--input '<json>'
```
— 内联JSON
```
--input @path/to/file.json
```
— 从文件读取
```
--input -
```
— 从标准输入读取
显式标志会覆盖
```
--input
```
中的字段。

Workspace Selection

工作区选择

bash

epismo workspace list
epismo workspace use --workspace-id <workspace-id>   # save default
epismo workspace current                              # show saved default (no network)

Workspace selection is CLI-only. All CLI commands resolve workspace automatically from

EPISMO_TOKEN

, saved default, then personal space. In MCP, workspace scope is implicit in the OAuth token.

bash

epismo workspace list
epismo workspace use --workspace-id <workspace-id>   # 设置默认工作区
epismo workspace current                              # 查看已保存的默认工作区（无需网络）

工作区选择仅支持CLI。所有CLI命令会自动从

EPISMO_TOKEN

、已保存的默认工作区，再到个人空间解析工作区。在MCP中，工作区范围隐含在OAuth令牌中。

Scope Model

范围模型

```
workspace
```
— top-level access boundary. All operations run within the active workspace.
```
targets.projectIds[]
```
— narrows private search or write access to specific projects within the active workspace.
```
targets.userIds[]
```
/
```
targets.emails[]
```
— grant private write access to specific people on mutation calls.
```
targets.self
```
— for search, include private items that target the current user directly; defaults to
```
true
```
.
CLI search/write flags such as
```
--project-ids
```
,
```
--user-ids
```
,
```
--emails
```
, and
```
--self
```
are convenience flags that build the
```
targets
```
object.
For search, omitting
```
targets.projectIds
```
uses the default private scope for the current context;
```
targets.projectIds: []
```
explicitly disables project targets.

When the user refers to "my project", resolve both layers before writing:

Active workspace
Target project(s) via
```
targets.projectIds[]
```

```
workspace
```
— 顶级访问边界。所有操作均在活跃工作区内进行。
```
targets.projectIds[]
```
— 将私有搜索或写入权限缩小到活跃工作区内的特定项目。
```
targets.userIds[]
```
/
```
targets.emails[]
```
— 在变更调用中向特定人员授予私有写入权限。
```
targets.self
```
— 搜索时，包含直接针对当前用户的私有项；默认值为
```
true
```
。
CLI搜索/写入标志如
```
--project-ids
```
、
```
--user-ids
```
、
```
--emails
```
和
```
--self
```
是构建
```
targets
```
对象的便捷标志。
搜索时，若省略
```
targets.projectIds
```
，则使用当前上下文的默认私有范围；
```
targets.projectIds: []
```
会显式禁用项目目标。

当用户提及“我的项目”时，需先解析以下两层再进行写入：

活跃工作区
通过
```
targets.projectIds[]
```
指定的目标项目

Resolving Share URLs

共享URL解析

Share URLs resolve to a resource without credentials by following the HTTP redirect.

Public packs typically use
```
https://epismo.ai/share/{token}
```
.

Internal/private workspace packs may use

https://{workspace}.epismo.ai/share/{token}

Do not assume the host is always the root domain; preserve the original host from the share URL.

bash

undefined

共享URL通过HTTP重定向解析为无需凭证的资源。

公共包通常使用
```
https://epismo.ai/share/{token}
```
。

内部/私有工作区包可能使用

https://{workspace}.epismo.ai/share/{token}

。

不要假设主机始终是根域名；保留共享URL中的原始主机。

bash

undefined

curl

curl示例

curl -s -o /dev/null -w "%{redirect_url}" "https://epismo.ai/share/${TOKEN}"

→ https://epismo.ai/hub/workflows/{id}

→ https://epismo.ai/hub/contexts/{id}

internal/private packs may redirect from a workspace subdomain instead

内部/私有包可能从工作区子域名重定向

curl -s -o /dev/null -w "%{redirect_url}" "https://${WORKSPACE}.epismo.ai/share/${TOKEN}"

→ https://${WORKSPACE}.epismo.ai/hub/workflows/{id}

→ https://${WORKSPACE}.epismo.ai/hub/contexts/{id}


```typescript
// fetch (Node.js)
const shareUrl = new URL(process.argv[2]);
const res = await fetch(shareUrl, {
  redirect: "manual",
});
const location = res.headers.get("location") ?? "";

const workflowMatch = location.match(/\/hub\/workflows\/([^/?#]+)/);
const contextMatch = location.match(/\/hub\/contexts\/([^/?#]+)/);
// use whichever matches; id = decodeURIComponent(match[1])

Redirect path	Resource type
`/hub/workflows/{id}`	`workflow` pack
`/hub/contexts/{id}`	`context` pack

Use the resolved

id

with

get pack

on any surface. If the original share URL is on a workspace subdomain, keep using that host when handing the link back to the user.


```typescript
// fetch示例（Node.js）
const shareUrl = new URL(process.argv[2]);
const res = await fetch(shareUrl, {
  redirect: "manual",
});
const location = res.headers.get("location") ?? "";

const workflowMatch = location.match(/\/hub\/workflows\/([^/?#]+)/);
const contextMatch = location.match(/\/hub\/contexts\/([^/?#]+)/);
// 使用匹配到的结果；id = decodeURIComponent(match[1])

重定向路径	资源类型
`/hub/workflows/{id}`	`workflow` 包
`/hub/contexts/{id}`	`context` 包

使用解析后的

id

在任意界面执行

get pack

命令。若原始共享URL位于工作区子域名，则在将链接返回给用户时保留该主机。

Selective Fetch Pattern

选择性获取模式

search

always returns outline format (

id

title

, and brief metadata) — never full content blocks. Always scan titles first, then fetch only what you need — this keeps session context lean.

Scan —
```
search pack
```
or
```
search track
```
to get a title list.
Select — identify relevant items from the titles. Skip clearly unrelated ones.
Fetch —
```
get pack --full
```
or
```
get track
```
for each selected item to load full content.

get pack

has two modes:

Mode	Flag	Returns
Outline (default)	(none)	`id` , `title` , `view` , `contentIndex` — no content blocks
Full	`--full`	complete content including all blocks / steps

To load a single block or step instead of the full pack:

bash

undefined

search

始终返回大纲格式（

id

、

title

和简要元数据）——从不返回完整内容块。始终先扫描标题，再仅获取所需内容——这能保持会话上下文简洁。

扫描 — 使用
```
search pack
```
或
```
search track
```
获取标题列表。
选择 — 从标题中识别相关项，跳过明显无关的内容。
获取 — 对每个选中项执行
```
get pack --full
```
或
```
get track
```
以加载完整内容。

get pack

有两种模式：

模式	标志	返回内容
大纲（默认）	(无)	`id` 、 `title` 、 `view` 、 `contentIndex` — 无内容块
完整	`--full`	完整内容，包括所有块/步骤

若要加载单个块或步骤而非完整包：

bash

undefined

context pack — fetch one block

上下文包 — 获取单个块

epismo pack get --id <id> --block-id <block-id>

workflow pack — fetch specific steps

工作流包 — 获取特定步骤

epismo pack get --id <id> --step-id <step-id-1>,<step-id-2>

undefined

epismo pack get --id <id> --step-id <step-id-1>,<step-id-2>

undefined

Pack Reuse Scan Order

包重用扫描顺序

Before creating any new pack, scan in this order to avoid duplicating something that already exists:

```
visibility=["private"]
```
+
```
query=<topic>
```
— your own packs first
```
like="liked"
```
+
```
query=<topic>
```
— packs you bookmarked
```
visibility=["public"]
```
+
```
query=<topic>
```
— community packs

If a close match is found, prefer

get pack

over creating new.

创建任何新包之前，请按以下顺序扫描，避免重复已存在的内容：

```
visibility=["private"]
```
+
```
query=<topic>
```
— 先查看自己的包
```
like="liked"
```
+
```
query=<topic>
```
— 查看你已收藏的包
```
visibility=["public"]
```
+
```
query=<topic>
```
— 查看社区包

若找到匹配度高的包，优先使用

get pack

而非创建新包。

Pagination

分页

All

search

calls return page size 20. For large result sets, iterate

page=1, 2, 3...

and merge results.

bash

epismo pack search --type context --filter '{"visibility":["public"]}' --page 2
epismo track search --type task --filter '{"status":["todo"]}' --page 2

Stop iterating when a page returns fewer than 20 results.

所有

search

调用返回的页面大小为20。对于大型结果集，请迭代

page=1, 2, 3...

并合并结果。

bash

epismo pack search --type context --filter '{"visibility":["public"]}' --page 2
epismo track search --type task --filter '{"status":["todo"]}' --page 2

当某一页返回的结果少于20条时，停止迭代。

Error Handling

错误处理

Error	Action
`Payment Required: Insufficient credits`	Stop. Check balance and purchase credits — see Credit Purchase.
`Permission denied`	Re-check accessible projects and resource ownership.
`Unauthorized` / `403`	Re-authenticate: run `epismo login` (CLI) or reconnect via MCP OAuth. Verify active workspace and subscription.
`Not Found` / `404`	Confirm the resource ID. It may have been deleted or the share token may have expired.
Rate limit / `429`	Wait and retry with backoff. Inform user if persistent.
Timeout	Retry once. If persistent, reduce payload size or split the operation.

错误	操作
`Payment Required: Insufficient credits`	停止操作。检查余额并购买积分——查看积分购买。
`Permission denied`	重新检查可访问的项目和资源所有权。
`Unauthorized` / `403`	重新认证：执行 `epismo login` （CLI）或通过MCP OAuth重新连接。验证活跃工作区和订阅状态。
`Not Found` / `404`	确认资源ID。该资源可能已被删除，或共享令牌已过期。
Rate limit / `429`	等待后重试并使用退避策略。若问题持续，告知用户。
Timeout	重试一次。若问题持续，减小负载大小或拆分操作。

Source of Truth

权威来源

Repository:

https://github.com/epismoai/skills

仓库地址：

https://github.com/epismoai/skills