awaek

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Awaek

Awaek turns saved X bookmarks into a local source engine for Hermes.

Use this skill when the user says Awaek, my saves, my saved posts, my bookmarks, or saved X bookmarks.

Do not answer Awaek requests from Hermes session memory alone. Do not use

session_search

unless the user explicitly asks for Hermes chat/session history.

For normal Awaek questions, retrieve local bookmark evidence first, then answer from that evidence.

Awaek可将已保存的X书签转换为Hermes的本地资源引擎。

当用户提及Awaek、我的保存内容、我保存的帖子、我的书签或已保存的X书签时，启用此skill。

仅依靠Hermes会话内存无法响应Awaek请求。除非用户明确要求查询Hermes聊天/会话历史，否则不要使用

session_search

。

对于常规的Awaek查询，需先检索本地书签证据，再基于该证据进行回答。

Core Rules

核心规则

Awaek is local-first. New installs store bookmark data in
```
~/.awaek/data/awaek.db
```
.
Existing Hermes installs may keep using
```
~/.hermes/awaek/data/awaek.db
```
; the scripts detect that automatically.
X access is handled by the local
```
xurl
```
CLI.
Never read, print, summarize, upload, or inspect
```
~/.xurl
```
.
Never ask the user to paste X Client IDs, Client Secrets, access tokens, refresh tokens, or
```
~/.xurl
```
contents into chat.
Do not run
```
xurl
```
with verbose/debug flags.
Do not send the full database to the model. Retrieve focused evidence only.
If evidence is weak or missing, say that plainly.

Awaek采用本地优先模式。新安装会将书签数据存储在
```
~/.awaek/data/awaek.db
```
中。
已有的Hermes安装可继续使用
```
~/.hermes/awaek/data/awaek.db
```
；脚本会自动检测该路径。
X访问由本地
```
xurl
```
CLI处理。
绝对不要读取、打印、总结、上传或检查
```
~/.xurl
```
文件。
绝对不要要求用户在聊天中粘贴X客户端ID、客户端密钥、访问令牌、刷新令牌或
```
~/.xurl
```
的内容。
不要使用verbose/debug标志运行
```
xurl
```
。
不要将完整数据库发送给模型。仅检索针对性的证据内容。
如果证据不足或缺失，直接告知用户。

Main Commands

主要命令

Use

${HERMES_SKILL_DIR}

as the installed Awaek skill directory.

Status:

bash

python3 ${HERMES_SKILL_DIR}/scripts/status.py

Topics and learned themes:

bash

python3 ${HERMES_SKILL_DIR}/scripts/list_scopes.py --learned

Find saved posts:

bash

python3 ${HERMES_SKILL_DIR}/scripts/search.py "<query>" --limit 20

Show safe-domain links found in saves:

bash

python3 ${HERMES_SKILL_DIR}/scripts/links.py --stats
python3 ${HERMES_SKILL_DIR}/scripts/links.py --status pending --limit 20

Build evidence for ask, draft, decide, and plan requests:

bash

python3 ${HERMES_SKILL_DIR}/scripts/answer_pack.py --plan-stdin --limit 30 <<'JSON'
<strict retrieval plan JSON>
JSON

使用

${HERMES_SKILL_DIR}

作为Awaek skill的安装目录。

状态查询：

bash

python3 ${HERMES_SKILL_DIR}/scripts/status.py

主题与已学习的主题分类：

bash

python3 ${HERMES_SKILL_DIR}/scripts/list_scopes.py --learned

查找已保存的帖子：

bash

python3 ${HERMES_SKILL_DIR}/scripts/search.py "<query>" --limit 20

显示在保存内容中找到的安全域名链接：

bash

python3 ${HERMES_SKILL_DIR}/scripts/links.py --stats
python3 ${HERMES_SKILL_DIR}/scripts/links.py --status pending --limit 20

为查询、草拟、决策和规划请求构建证据：

bash

python3 ${HERMES_SKILL_DIR}/scripts/answer_pack.py --plan-stdin --limit 30 <<'JSON'
<strict retrieval plan JSON>
JSON

Setup And Sync

安装与同步

If the user asks to install, set up, or sync Awaek, use this flow.

First check local readiness:

bash

python3 ${HERMES_SKILL_DIR}/scripts/setup.py
xurl auth status
xurl whoami

xurl

is missing or unauthenticated, tell the user to complete the

xurl

one-time setup. Do not ask for secrets in chat. Requirements:

X developer app with redirect URI
```
http://localhost:8080/callback
```
OAuth scopes that allow bookmark reads
```
xurl auth oauth2 --app <app-name>
```
```
xurl auth default <app-name>
```

After

xurl whoami

works, fetch the user id:

bash

xurl "/2/users/me?user.fields=username,name"

Then fetch bookmarks and pipe them into Awaek:

bash

xurl "/2/users/<user-id>/bookmarks?max_results=100&tweet.fields=created_at,author_id,entities,note_tweet,attachments,public_metrics&expansions=author_id&user.fields=username,name" | python3 ${HERMES_SKILL_DIR}/scripts/sync.py --source input --limit 100

sync.py

returns

next_token

, fetch the next page:

bash

xurl "/2/users/<user-id>/bookmarks?max_results=100&pagination_token=<next-token>&tweet.fields=created_at,author_id,entities,note_tweet,attachments,public_metrics&expansions=author_id&user.fields=username,name" | python3 ${HERMES_SKILL_DIR}/scripts/sync.py --source input --limit 100

Repeat page by page until

next_token

is null or missing.

After sync, run:

bash

python3 ${HERMES_SKILL_DIR}/scripts/status.py
python3 ${HERMES_SKILL_DIR}/scripts/list_scopes.py --learned

Tell the user:

bookmarks indexed
searchable evidence chunks created
top topics
learned themes, if any
3-4 useful next prompts based on their actual topics

Do not sync on every turn. Sync when the user asks, when no library exists, or when the user agrees the library is stale.

如果用户要求安装、设置或同步Awaek，请遵循以下流程。

首先检查本地就绪状态：

bash

python3 ${HERMES_SKILL_DIR}/scripts/setup.py
xurl auth status
xurl whoami

如果

xurl

缺失或未认证，请告知用户完成

xurl

的一次性设置。不要在聊天中索要密钥。要求如下：

重定向URI为
```
http://localhost:8080/callback
```
的X开发者应用
允许读取书签的OAuth权限
执行
```
xurl auth oauth2 --app <app-name>
```
执行
```
xurl auth default <app-name>
```

xurl whoami

正常运行后，获取用户ID：

bash

xurl "/2/users/me?user.fields=username,name"

然后获取书签并导入到Awaek：

bash

xurl "/2/users/<user-id>/bookmarks?max_results=100&tweet.fields=created_at,author_id,entities,note_tweet,attachments,public_metrics&expansions=author_id&user.fields=username,name" | python3 ${HERMES_SKILL_DIR}/scripts/sync.py --source input --limit 100

如果

sync.py

next_token

，则获取下一页内容：

bash

xurl "/2/users/<user-id>/bookmarks?max_results=100&pagination_token=<next-token>&tweet.fields=created_at,author_id,entities,note_tweet,attachments,public_metrics&expansions=author_id&user.fields=username,name" | python3 ${HERMES_SKILL_DIR}/scripts/sync.py --source input --limit 100

逐页重复上述操作，直到

next_token

为空或不存在。

同步完成后，执行：

bash

python3 ${HERMES_SKILL_DIR}/scripts/status.py
python3 ${HERMES_SKILL_DIR}/scripts/list_scopes.py --learned

告知用户：

书签已完成索引
已创建可搜索的证据片段
热门主题
已学习的主题（如有）
基于实际主题的3-4个实用后续提示

不要每次交互都同步。仅在用户要求、本地无书签库或用户确认书签库已过期时进行同步。

Ask, Draft, Decide, Plan

查询、草拟、决策、规划

For these requests, create a strict retrieval plan JSON first. This is planning only; do not answer the user yet.

Plan format:

json

{
  "user_request": "Original user message exactly.",
  "normalized_request": "Cleaned request with typos fixed, preserving meaning.",
  "task_type": "ask | draft | plan | decide | find",
  "intent": "short_snake_case_intent",
  "goal": "What the user wants to accomplish.",
  "domain": "Main domain or topic.",
  "platforms": [],
  "entities": [],
  "must_match_terms": [],
  "needed_evidence": [],
  "avoid_evidence": [],
  "output_need": "answer | strategy | draft | comparison | checklist | search results",
  "topic_filters": []
}

Plan rules:

Fix typos in
```
normalized_request
```
.
Preserve product names, people, platforms, and requested output.
Put product names, people, companies, platforms, and protocols in
```
entities
```
.
Use
```
must_match_terms
```
only when direct saved-post evidence is required. If any required term is absent, Awaek will return no usable bookmark evidence.
Put the kinds of saved posts needed in
```
needed_evidence
```
; describe evidence, not the final answer.
Put likely wrong interpretations in
```
avoid_evidence
```
.
For ambiguous words, expand the intended meaning into precise evidence terms and avoid likely wrong meanings.
Keep the plan domain-general. Do not assume a fixed bookmark library.
Do not invent facts about the user's product.

Run:

bash

python3 ${HERMES_SKILL_DIR}/scripts/answer_pack.py --plan-stdin --limit 30 <<'JSON'
<strict retrieval plan JSON>
JSON

Then use the returned fields:

```
context
```
: source material for the final answer
```
bookmarks
```
: compact saved-post evidence
```
retrieval_queries
```
: what Awaek searched
```
evidence_strength
```
: whether the evidence is strong, medium, weak, or none

Answer rules:

Answer from saved-bookmark evidence first.
Mention that the answer is based on saved X bookmarks.
Cite or reference saved posts when useful.
If
```
evidence_strength.level
```
is
```
weak
```
, say the saved evidence is thin.
If
```
evidence_strength.level
```
is
```
none
```
, do not invent bookmark-backed claims. Say Awaek found no relevant saved bookmarks and ask whether to use general knowledge.
Use Hermes memory or user style only after Awaek evidence has been retrieved.

对于此类请求，需先创建严格的检索计划JSON。此步骤仅为规划，暂不回复用户。

计划格式：

json

{
  "user_request": "Original user message exactly.",
  "normalized_request": "Cleaned request with typos fixed, preserving meaning.",
  "task_type": "ask | draft | plan | decide | find",
  "intent": "short_snake_case_intent",
  "goal": "What the user wants to accomplish.",
  "domain": "Main domain or topic.",
  "platforms": [],
  "entities": [],
  "must_match_terms": [],
  "needed_evidence": [],
  "avoid_evidence": [],
  "output_need": "answer | strategy | draft | comparison | checklist | search results",
  "topic_filters": []
}

规划规则：

在
```
normalized_request
```
中修正拼写错误。
保留产品名称、人物、平台和请求的输出形式。
将产品名称、人物、公司、平台和协议放入
```
entities
```
。
仅当需要直接的已保存帖子证据时使用
```
must_match_terms
```
。如果缺少任何必填术语，Awaek将返回无可用书签证据。
将所需的已保存帖子类型放入
```
needed_evidence
```
；描述证据而非最终答案。
将可能的错误解读放入
```
avoid_evidence
```
。
对于歧义词汇，将预期含义扩展为精确的证据术语，并排除可能的错误含义。
保持计划的领域通用性。不要假设固定的书签库。
不要编造用户产品的相关事实。

执行：

bash

python3 ${HERMES_SKILL_DIR}/scripts/answer_pack.py --plan-stdin --limit 30 <<'JSON'
<strict retrieval plan JSON>
JSON

然后使用返回的字段：

```
context
```
：最终回答的素材来源
```
bookmarks
```
：精简的已保存帖子证据
```
retrieval_queries
```
：Awaek执行的搜索内容
```
evidence_strength
```
：证据强度（强、中、弱或无）

回答规则：

优先基于已保存书签证据进行回答。
提及回答基于已保存的X书签。
必要时引用已保存的帖子。
如果
```
evidence_strength.level
```
为
```
weak
```
，告知用户已保存证据不足。
如果
```
evidence_strength.level
```
为
```
none
```
，不要编造基于书签的结论。告知用户Awaek未找到相关的已保存书签，并询问是否使用通用知识。
仅在检索完Awaek证据后，才可使用Hermes内存或用户风格。

Direct Search

直接搜索

For "Awaek find..." requests, use direct search:

bash

python3 ${HERMES_SKILL_DIR}/scripts/search.py "<query>" --limit 20

Return matching saved posts with author, snippet, and URL. Do not synthesize unless the user asks.

For person, company, role, or handle lookups, resolve the specific name/handle before searching when it is obvious from general knowledge or the user's wording.

Examples of lookup intent:

"Jeremy CEO post"
"what did Circle CEO say"
"show the saved post from @jerallaire"
"find the saved post by the founder of X"

For these, search exact identifiers first: person name, handle, company, and the user's topic words. If the user says "CEO/founder of <company>" and the person is known, include the person's name and handle in the search. Do not replace an exact person/handle result with adjacent topic posts.

对于“Awaek find...”类请求，使用直接搜索：

bash

python3 ${HERMES_SKILL_DIR}/scripts/search.py "<query>" --limit 20

返回匹配的已保存帖子，包含作者、片段和URL。除非用户要求，否则不要进行内容合成。

对于人物、公司、职位或账号查询，若可通过通用知识或用户表述明确识别，需先解析具体名称/账号再进行搜索。

查询意图示例：

"Jeremy CEO post"
"what did Circle CEO say"
"show the saved post from @jerallaire"
"find the saved post by the founder of X"

对于此类请求，优先搜索精确标识符：人物姓名、账号、公司及用户提及的主题词。如果用户提及“<公司>的CEO/创始人”且该人物已知，需将人物姓名和账号纳入搜索。不要用相邻主题的帖子替换精确的人物/账号搜索结果。

Topic Inspection

主题检查

For "Awaek topics", "Awaek scopes", or "What am I saving?", run:

bash

python3 ${HERMES_SKILL_DIR}/scripts/list_scopes.py --learned

Use this to show categories, subcategories, and emerging repeated terms. If a user request is broad or ambiguous, inspect topics before building the retrieval plan.

对于“Awaek topics”、“Awaek scopes”或“What am I saving?”类请求，执行：

bash

python3 ${HERMES_SKILL_DIR}/scripts/list_scopes.py --learned

使用此命令展示分类、子分类及重复出现的新兴术语。如果用户请求宽泛或模糊，需先检查主题再构建检索计划。

Failure Handling

故障处理

xurl

is missing:

text

Awaek needs xurl before it can sync X bookmarks. Install and authenticate xurl, then ask: Awaek sync.

xurl

is not authenticated:

text

Awaek found xurl, but it is not authenticated yet. Run xurl auth status, then authenticate with xurl auth oauth2 --app <your-app> and xurl auth default <your-app>.

If bookmark sync returns zero records:

text

Awaek reached X through xurl, but bookmark retrieval returned 0 records. This may be an X API permission, OAuth scope, rate-limit, or account issue.

If records lack post text:

text

Awaek received bookmark records, but they did not include usable post text. I need post text before I can build a useful local library.

If evidence is missing:

text

Awaek found no relevant saved X bookmarks for this request.

如果

xurl

缺失：

text

Awaek需要xurl才能同步X书签。请安装并认证xurl，然后发送请求：Awaek sync。

如果

xurl

未认证：

text

Awaek已检测到xurl，但尚未完成认证。请执行xurl auth status，然后通过xurl auth oauth2 --app <your-app>和xurl auth default <your-app>完成认证。

如果书签同步返回零记录：

text

Awaek已通过xurl连接到X，但书签检索返回0条记录。这可能是X API权限、OAuth权限、速率限制或账号问题导致的。

如果记录缺少帖子文本：

text

Awaek已收到书签记录，但其中不包含可用的帖子文本。我需要帖子文本才能构建有用的本地库。

如果证据缺失：

text

Awaek未找到与该请求相关的已保存X书签。

Verification

验证

After setup or sync:

bash

python3 ${HERMES_SKILL_DIR}/scripts/status.py
python3 ${HERMES_SKILL_DIR}/scripts/list_scopes.py --learned

After any grounded answer, verify:

the response is based on saved-post evidence
sources are not invented
missing evidence is stated clearly

安装或同步完成后：

bash

python3 ${HERMES_SKILL_DIR}/scripts/status.py
python3 ${HERMES_SKILL_DIR}/scripts/list_scopes.py --learned

任何基于证据的回答完成后，需验证：

响应基于已保存帖子证据
未编造来源
已明确说明缺失的证据