GitHub on 酒中仙

生活片段分享平台

Mon, 30 Mar 2026 18:40:25 -0800

生活片段分享平台

前言

去年夏天，我搭建了一个 Life-Moments 的平台用于分享自己的生活，但是因为数据存储的问题，这个工具没能成为我日常工具的一部分。

类似微信朋友圈的工具有很多，比如Moments、Memos 和 Ech0。

特性	Memos	Moments	Ech0
PWA 适配	✅ 支持	❌ 不支持	✅ 支持
标签系统	✅ 完善	✅ 完善	✅ 支持
S3 图床	✅ 支持	✅ 支持	✅ 支持
Meting 音乐	❌ 不支持	✅ 支持	✅ 支持
视频分享	✅ 支持	✅ 支持	✅ 支持
设计风格	功能导向，略显臃肿	功能全面，类似后台	简约美观，轻量
开发活跃度	非常活跃，API 易变	相对稳定	活跃，快速迭代
个人评价	功能强大，但更新太折腾，生态不稳定。	功能完美，但没 PWA 对我是减分项	界面戳我，功能追上来了，PWA 是加分项，目前的最爱

Ech0：自托管个人微博客

自托管个人微博客：你的时间线可以被分享、讨论，同时数据完全由你掌控。

GitHub——Ech0 – An open-source, self-hosted lightweight publishing platform for personal idea sharing.

Ech0 helps individuals publish thoughts, notes, and links with full data ownership, ultra-light footprint, and a focused writing experience.

Ech0 示例可以参考： https://mm.liushen.fun/

像 Memos 这样的工具非常适合快速记录想法。Ech0 更关注“记录之后”的阶段：把内容发布到个人时间线，让更多人可以持续关注和互动。你可以在自己的服务器上托管内容，保留完整控制权，同时通过可选评论与分享保持轻连接，而不是变成复杂社交平台。它保持轻量、易部署、完全开源。

适合你，如果你想：

搭建一个自己的公开或半公开动态站
用统一界面发布短文、链接与媒体卡片
兼顾数据主权，同时保留 RSS 与评论等能力
让个人内容具备轻社交连接能力，而不需要重型社交产品

不太适合你，如果你需要：

双链知识库式的笔记工作流（例如 Obsidian 风格）
团队优先的协作文档平台（例如 Notion 风格）
纯私密备忘且不关注发布/时间线场景

Memos：私有、轻量、开源、自托管的备忘录

Memos 是一种隐私优先的轻量级笔记解决方案，可让您轻松捕捉和分享您的想法。它开源且免费支持自部署。生态上支持第三方的手机端APP、浏览器插件等方式记录笔记，优势是生态够强，缺点是开发者每次更新大版本后之前的API可能就直接废弃了。

这是一个采用 React+Tailwind+TypeScript+Go 开发的备忘录中心，相当于极简的微博。支持私有/公开备忘录、标签、互动式日历等功能，以及 Docker 部署。

Memos 的官方文档： https://www.usememos.com/docs

开源地址： https://github.com/usememos/memos

特色介绍

隐私优先🏠：掌控你的数据。所有运行时数据都安全地存储在本地数据库中。
快速创建✍️：将内容保存为纯文本以便快速访问，并支持 Markdown 以实现快速格式化和轻松共享。
轻量但强大🤲：使用 Go、React.js 和紧凑的架构构建，我们的应用程序在轻量级的包中提供强大的性能。
可定制🧩：轻松自定义服务器名称、图标、描述、系统风格和执行脚本，使其独一无二。
开源🦦：Memos 拥抱开源的未来，所有代码在 GitHub 上可用，以实现透明度和协作。
免费使用💸：完全免费享受所有功能，任何内容都不会收取任何费用。

功能

支持Markdown语法
支持S3存储
支持多用户
支持评论
支持MYsql或者SQLite作为数据库
支持API

Memos 相关工具

Moe Memos - 适用于 iOS 和 Android 的第三方客户端
lmm214/memos-bber - Chrome 扩展
Rabithua/memos_wmp - 微信小程序
qazxcdswe123/telegramMemoBot - 电报机器人
eallion/memos.top - 使用 Memos API 呈现的静态页面
eindex/logseq-memos-sync - Logseq 插件
JakeLaoyu/memos-import-from-flomo - 导入数据。来自flomo、微信读书的支持
发送到备忘录- iOS 的快捷方式
备忘录 Raycast Extension - Raycast 扩展
Memos Desktop - 适用于 MacOS 和 Windows 的第三方客户端
MemosGallery - 使用 Memos API 呈现的静态图库

Moments - 极简朋友圈

moments 是一个极简设计的朋友圈社交平台，旨在为用户提供一个简洁而高效的分享空间。它允许用户轻松记录和分享生活中的点滴时刻、创意作品以及其他任何想要记录的内容。通过其直观的界面和一系列实用功能，moments 促进了用户之间的交流与互动。

GitHub——极简朋友圈

作者的 Demo：https://m.mblog.club/

功能说明

用户系统：

默认管理员：admin/a123456，登录后可在后台修改密码
多用户模式：可以在后台设置是否允许用户注册

Memo：

支持使用 Markdown 语法编写
支持修改发布时间，若发布时间晚于当前时间，则对游客不可见
支持添加标签，方便分类查找
支持上传图片、视频
支持引用外部音乐、外部视频、外部链接
支持引用豆瓣读书、豆瓣电影
支持点赞、评论，可在后台开启/关闭评论功能

文件上传：

上传到服务器时：

支持上传到服务器的 $UPLOAD_DIR 目录下
上传文件时，会先通过 SHA256 检查文件是否被上传过，若上传过则可以“秒传”
上传图片时，会自动创建图片的缩略图，在浏览 Memo 时默认加载缩略图
上传文件时，会和 Memo 产生关联，可以在设置中清理无用的文件，无用的文件将会被整理到 $UPLOAD_DIR/removed 目录下

上传到 S3 时：

支持上传到兼容 S3 的存储服务
开启 S3 时，可以设置图片压缩后缀，在浏览 Memo 时，会默认请求带后缀的图片加载缩略图

以下功能没有详细介绍，请自行探索：

友情链接
邮件通知
RSS 订阅
暗黑模式
数据库自动备份，当检测到启动的版本发生变化时，自动备份数据库文件到 $DB 目录下

项目部署

部署平台推荐 ClawCloud 和 Render 。

Render 是一家来自旧金山的云平台公司，目标是打造开发者友好的全托管部署平台，支持 Web 服务、静态站点、后端 API、数据库、Cron Job 等。用户可以使用 Dockerfile 部署自定义服务，或直接部署 Git 仓库。

官网：https://render.com
免费层：有免费 Web 服务（自动休眠）、PostgreSQL 数据库等

Clawcloud 是一个新兴的云平台，主打“简洁”、“极致性价比”、“对个人开发者友好”。在 2024 年底至 2025 年间快速崛起，因其不强制休眠的免费容器服务和极低的延迟部署时间受到好评。

官网：https://run.claw.cloud/
免费层：每日最多运行 12 小时的容器服务，月流量限制更宽松

两者对比：

对比项	Render 免费版	Clawcloud 免费版
运行时间限制	自动休眠（15 分钟无请求休眠，冷启动 30s 左右）	每天最多运行 12 小时（可配置时段），不强制休眠
支持 Docker	✅ 完全支持，需上传 Dockerfile	✅ 原生支持，直接上传镜像或 Dockerfile
自定义域名与 HTTPS	✅ 支持自动 HTTPS	✅ 支持自动 HTTPS，支持裸域
免费数据库	✅ PostgreSQL（256MB）	❌ 目前不提供数据库服务
月流量限制	~750 小时/月 + 100GB 出站流量	12 小时 * 30 天 + 100GB 出站流量（约等同）
并发容器数量	单服务 + 限资源（512MB RAM）	单实例 + 限资源（512MB RAM）

小结：

Clawcloud 更适合“轻量、全天候运行”的项目，例如个人博客、Webhook 服务、定时任务
Render 更适合“对数据库有需求”的项目，例如全栈应用、API 后端等
两者都限制资源，但对于轻量应用已足够使用

部署教程可以参考如下链接：

使用ClawCloud免费部署memos服务

参考资料

从Moments迁移到Ech0

使用ClawCloud免费部署memos服务

自建 Memos 服务：碎片化笔记 + 博客说说栏，一栈双用

利用 Claw Cloud Run 免费应用部署前端网页

Render vs Clawcloud：免费的 Docker 应用部署平台推荐（2025）

从头实现属于自己的 OpenClaw

Sun, 15 Mar 2026 12:34:25 -0800

从头实现属于自己的 OpenClaw

claw0 简介

项目链接

从零到一: 构建 AI Agent 网关

10 个渐进式章节, 每节都是可直接运行的 Python 文件. 3 种语言 (英语, 中文, 日语) – 代码 + 文档同目录.

相关项目：learn-claude-code – 姊妹教学仓库, 用 12 个递进课程从零构建一个智能体框架 (nano Claude Code)。claw0 聚焦于网关路由、多通道接入和主动行为, learn-claude-code 则深入智能体的内部设计: 结构化规划 (TodoManager + nag)、上下文压缩 (三层 compact)、基于文件的任务持久化与依赖图、团队协调 (JSONL 邮箱、关机/计划审批 FSM)、自治式自组织, 以及 git worktree 隔离的并行执行。如果你想理解一个生产级单元智能体的内部运作, 从那里开始。

这是什么?

大多数 Agent 教程停在"调一次 API"就结束了. 这个仓库从那个 while 循环开始, 一路带你到生产级网关.

逐章节构建一个最小化 AI Agent 网关. 10 个章节, 10 个核心概念, 约 7,000 行 Python. 每节只引入一个新概念, 前一节的代码原样保留. 学完全部 10 节, 你就能顺畅地阅读 OpenClaw 的生产代码.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


s01: Agent Loop -- 基础: while + stop_reason
s02: Tool Use -- 让模型能调工具: dispatch table
s03: Sessions & Context -- 会话持久化, 上下文溢出处理
s04: Channels -- Telegram + 飞书: 完整通道管线
s05: Gateway & Routing -- 5 级绑定, 会话隔离
s06: Intelligence -- 灵魂, 记忆, 技能, 提示词组装
s07: Heartbeat & Cron -- 主动型 Agent + 定时任务
s08: Delivery -- 可靠消息队列 + 退避
s09: Resilience -- 3 层重试洋葱 + 认证轮换
s10: Concurrency -- 命名队列车道序列化混沌

架构概览

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


+------------------- claw0 layers -------------------+
| |
| s10: Concurrency (命名车道, generation 追踪) |
| s09: Resilience (认证轮换, 溢出压缩) |
| s08: Delivery (预写队列, 退避) |
| s07: Heartbeat (Lane 锁, cron 调度) |
| s06: Intelligence (8 层提示词, 混合记忆检索) |
| s05: Gateway (WebSocket, 5 级路由) |
| s04: Channels (Telegram 管线, 飞书 webhook) |
| s03: Sessions (JSONL 持久化, 3 阶段重试) |
| s02: Tools (dispatch table, 4 个工具) |
| s01: Agent Loop (while True + stop_reason) |
| |
+-----------------------------------------------------+

章节依赖关系

1
2
3
4
5
6
7


s01 --> s02 --> s03 --> s04 --> s05
 | |
 v v
 s06 ----------> s07 --> s08
 | |
 v v
 s09 ----------> s10

s01-s02: 基础 (无依赖)
s03: 基于 s02 (为工具循环添加持久化)
s04: 基于 s03 (通道产生 InboundMessage 给会话)
s05: 基于 s04 (将通道消息路由到 Agent)
s06: 基于 s03 (使用会话做上下文, 添加提示词层)
s07: 基于 s06 (心跳使用灵魂/记忆构建提示词)
s08: 基于 s07 (心跳输出经由投递队列)
s09: 基于 s03+s06 (复用 ContextGuard 做溢出层, 模型配置)
s10: 基于 s07 (将单一 Lock 替换为命名车道系统)

快速开始

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 1. 克隆并进入目录
git clone https://github.com/anthropics/claw0.git && cd claw0

# 2. 安装依赖
pip install -r requirements.txt

# 3. 配置
cp .env.example .env
# 编辑 .env: 填入 ANTHROPIC_API_KEY 和 MODEL_ID

# 4. 运行任意章节 (选择你的语言)
python sessions/zh/s01_agent_loop.py # 中文
python sessions/en/s01_agent_loop.py # English
python sessions/ja/s01_agent_loop.py # Japanese

学习路径

每节只加一个新概念, 上一节的代码完整保留:

1
2
3
4
5
6
7


Phase 1: 基础 Phase 2: 连接 Phase 3: 智能 Phase 4: 自治 Phase 5: 生产
+----------------+ +-------------------+ +-----------------+ +-----------------+ +-----------------+
| s01: Loop | | s03: Sessions | | s06: Intelligence| | s07: Heartbeat | | s09: Resilience |
| s02: Tools | -> | s04: Channels | -> | 灵魂, 记忆, | -> | & Cron | -> | & Concurrency |
| | | s05: Gateway | | 技能, 提示词 | | s08: Delivery | | s10: Lanes |
+----------------+ +-------------------+ +-----------------+ +-----------------+ +-----------------+
 循环 + dispatch 持久化 + 路由 人格 + 回忆 主动行为 + 可靠投递 重试 + 序列化

章节详情

#	章节	核心概念	行数
01	Agent Loop	`while True` + `stop_reason` – 这就是一个 Agent	~175
02	Tool Use	工具 = schema dict + handler map. 模型选名字, 你查表执行	~445
03	Sessions	JSONL: 写入追加, 读取重放. 太大了? 总结旧消息	~890
04	Channels	每个平台都不同, 但最终都生产同一个 `InboundMessage`	~780
05	Gateway	绑定表将 (channel, peer) 映射到 agent. 最具体的匹配胜出	~625
06	Intelligence	系统提示词 = 磁盘上的文件. 换文件, 换人格, 不改代码	~750
07	Heartbeat & Cron	定时线程: “该不该跑?” + 和用户消息共用同一管线	~660
08	Delivery	先写磁盘, 再尝试发送. 崩溃也丢不了消息	~870
09	Resilience	3 层重试洋葱: 认证轮换, 溢出压缩, 工具循环	~1130
10	Concurrency	命名车道 + FIFO 队列, generation 追踪, Future 返回	~900

仓库结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


claw0/
 README.md English README
 README.zh.md Chinese README
 README.ja.md Japanese README
 .env.example 配置模板
 requirements.txt Python 依赖
 sessions/ 所有教学章节 (代码 + 文档)
 en/ English
 s01_agent_loop.py s01_agent_loop.md
 s02_tool_use.py s02_tool_use.md
 ... (10 .py + 10 .md)
 zh/ 中文
 s01_agent_loop.py s01_agent_loop.md
 ... (10 .py + 10 .md)
 ja/ Japanese
 s01_agent_loop.py s01_agent_loop.md
 ... (10 .py + 10 .md)
 workspace/ 共享工作区样例
 SOUL.md IDENTITY.md TOOLS.md USER.md
 HEARTBEAT.md BOOTSTRAP.md AGENTS.md MEMORY.md
 CRON.json
 skills/example-skill/SKILL.md

每个语言文件夹自包含: 可运行的 Python 代码 + 配套文档. 代码逻辑跨语言一致, 注释和文档因语言而异.

前置要求

Python 3.10+
Anthropic (或兼容服务商) 的 API key

依赖

1
2
3
4
5
6


anthropic>=0.39.0
python-dotenv>=1.0.0
websockets>=12.0
croniter>=2.0.0
python-telegram-bot>=21.0
httpx>=0.27.0

第 01 节: Agent 循环

Agent 就是 while True + stop_reason.

架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


 User Input
 |
 v
 messages[] <-- append {role: "user", ...}
 |
 v
 client.messages.create(model, system, messages)
 |
 v
 stop_reason?
 / \
 "end_turn" "tool_use"
 | |
 Print (第 02 节)
 |
 v
 messages[] <-- append {role: "assistant", ...}
 |
 +--- 回到循环, 等待下一次输入

后续所有功能 – 工具、会话、路由、投递 – 都是在这个循环之上叠加的层, 循环本身不会改变.

本节要点

messages[] 是唯一的状态. 每次 API 调用时, LLM 都会看到完整数组.
stop_reason 是每次 API 响应后的唯一决策点.
end_turn = “打印文本.” tool_use = “执行工具, 将结果反馈回去” (第 02 节).
循环结构永远不变. 后续章节围绕它添加功能.

核心代码走读

1. 完整的 agent 循环

每轮三个步骤: 收集输入, 调用 API, 根据 stop_reason 分支.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


def agent_loop() -> None:
 messages: list[dict] = []

 while True:
 try:
 user_input = input(colored_prompt()).strip()
 except (KeyboardInterrupt, EOFError):
 break

 if not user_input:
 continue
 if user_input.lower() in ("quit", "exit"):
 break

 messages.append({"role": "user", "content": user_input})

 try:
 response = client.messages.create(
 model=MODEL_ID,
 max_tokens=8096,
 system=SYSTEM_PROMPT,
 messages=messages,
 )
 except Exception as exc:
 print(f"API Error: {exc}")
 messages.pop() # 回滚, 让用户可以重试
 continue

 if response.stop_reason == "end_turn":
 assistant_text = ""
 for block in response.content:
 if hasattr(block, "text"):
 assistant_text += block.text
 print_assistant(assistant_text)

 messages.append({
 "role": "assistant",
 "content": response.content,
 })

2. stop_reason 分支

即使在第 01 节, 代码也预留了 tool_use 分支. 虽然还没有工具, 但这个脚手架意味着第 02 节不需要修改外层循环.

1
2
3


 elif response.stop_reason == "tool_use":
 print_info("[stop_reason=tool_use] No tools in this section.")
 messages.append({"role": "assistant", "content": response.content})

stop_reason	含义	动作
`"end_turn"`	模型完成了回复	打印, 继续循环
`"tool_use"`	模型想调用工具	执行, 反馈结果
`"max_tokens"`	回复被 token 限制截断	打印部分文本

试一试

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 确保 .env 中有你的密钥
echo 'ANTHROPIC_API_KEY=sk-ant-xxxxx' > .env
echo 'MODEL_ID=claude-sonnet-4-20250514' >> .env

# 运行 agent
python zh/s01_agent_loop.py

# 和它对话 -- 多轮对话有效, 因为 messages[] 会累积
# You > 法国的首都是哪里?
# You > 它的人口是多少?
# (模型记得上一轮提到的"法国".)

OpenClaw 中的对应实现

方面	claw0 (本文件)	OpenClaw 生产代码
循环位置	单文件中的 `agent_loop()`	`src/agent/` 中的 `AgentLoop` 类
消息存储	内存中的 `list[dict]`	JSONL 持久化的 SessionStore
stop_reason	相同的分支逻辑	相同逻辑 + 流式支持
错误处理	弹出最后一条消息, 继续	带退避的重试 + 上下文保护
系统提示词	硬编码字符串	8 层动态组装 (第 06 节)

第 02 节: 工具使用

工具 = 数据 (schema) + 处理函数映射表. 模型选一个名字, 你查表执行.

架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


 User Input
 |
 v
 messages[] --> LLM API (tools=TOOLS)
 |
 stop_reason?
 / \
 "end_turn" "tool_use"
 | |
 Print for each tool_use block:
 TOOL_HANDLERS[name](**input)
 |
 tool_result
 |
 messages[] <-- {role:"user", content:[tool_result]}
 |
 back to LLM --> may chain more tools
 or "end_turn" --> Print

外层 while True 与第 01 节完全相同. 唯一的新增是一个内层 while 循环, 在 stop_reason == "tool_use" 时持续调用 LLM.

本节要点

TOOLS: JSON schema 字典列表, 告诉模型有哪些工具可用.
TOOL_HANDLERS: dict[str, Callable], 将工具名映射到 Python 函数.
process_tool_call(): 字典查找 + **kwargs 分发.
内层循环: 模型可能连续调用多个工具, 然后才生成文本.
工具结果放在 user 消息中 (Anthropic API 的要求).

核心代码走读

1. Schema + 分发表

两个平行的数据结构. TOOLS 告诉模型, TOOL_HANDLERS 告诉你的代码.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


TOOLS = [
 {
 "name": "bash",
 "description": "Run a shell command and return its output.",
 "input_schema": {
 "type": "object",
 "properties": {
 "command": {"type": "string", "description": "The shell command."},
 "timeout": {"type": "integer", "description": "Timeout in seconds."},
 },
 "required": ["command"],
 },
 },
 # ... read_file, write_file, edit_file (相同模式)
]

TOOL_HANDLERS: dict[str, Any] = {
 "bash": tool_bash,
 "read_file": tool_read_file,
 "write_file": tool_write_file,
 "edit_file": tool_edit_file,
}

添加新工具 = 在 TOOLS 中加一项 + 在 TOOL_HANDLERS 中加一项. 循环本身不需要改动.

2. 分发函数

模型返回工具名和输入字典. 分发就是一次字典查找. 错误作为字符串返回 (而非抛出异常), 这样模型可以看到错误并自行修正.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


def process_tool_call(tool_name: str, tool_input: dict) -> str:
 handler = TOOL_HANDLERS.get(tool_name)
 if handler is None:
 return f"Error: Unknown tool '{tool_name}'"
 try:
 return handler(**tool_input)
 except TypeError as exc:
 return f"Error: Invalid arguments for {tool_name}: {exc}"
 except Exception as exc:
 return f"Error: {tool_name} failed: {exc}"

3. 内层工具调用循环

相比第 01 节唯一的结构变化. 模型可能连续调用多次工具, 最后才产生文本回复.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


while True:
 response = client.messages.create(
 model=MODEL_ID, max_tokens=8096,
 system=SYSTEM_PROMPT, tools=TOOLS, messages=messages,
 )
 messages.append({"role": "assistant", "content": response.content})

 if response.stop_reason == "end_turn":
 # 提取文本, 打印, break
 break

 elif response.stop_reason == "tool_use":
 tool_results = []
 for block in response.content:
 if block.type != "tool_use":
 continue
 result = process_tool_call(block.name, block.input)
 tool_results.append({
 "type": "tool_result",
 "tool_use_id": block.id,
 "content": result,
 })
 # 工具结果放在 user 消息中 (API 要求)
 messages.append({"role": "user", "content": tool_results})
 continue # 回到 LLM

试一试

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


python zh/s02_tool_use.py

# 让它执行命令
# You > 当前目录下有哪些文件?

# 让它读取文件
# You > 读取 en/s01_agent_loop.py 的内容

# 让它创建和编辑文件
# You > 创建一个名为 hello.txt 的文件, 内容是 "Hello World"
# You > 把 hello.txt 中的 "World" 改成 "claw0"

# 观察它链式调用工具 (读取 -> 编辑 -> 验证)
# You > 在 hello.txt 顶部添加一行注释

OpenClaw 中的对应实现

方面	claw0 (本文件)	OpenClaw 生产代码
工具定义	Python 字典列表	TypeBox schema, 自动校验
分发	`dict[str, Callable]` 查表	相同模式 + 中间件管线
安全性	`safe_path()` 阻止目录穿越	沙箱执行, 白名单
工具数量	4 个 (bash, read, write, edit)	20+ (网页搜索, 媒体, 日历等)
工具结果	返回纯字符串	带元数据的结构化结果

第 03 节: 会话与上下文保护

会话就是 JSONL 文件. 追加写入, 重放恢复, 太大就摘要压缩.

架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


 User Input
 |
 v
 SessionStore.load_session() --> rebuild messages[] from JSONL
 |
 v
 ContextGuard.guard_api_call()
 |
 +-- Attempt 0: normal call
 | |
 | overflow? --no--> success
 | |yes
 +-- Attempt 1: truncate oversized tool results
 | |
 | overflow? --no--> success
 | |yes
 +-- Attempt 2: compact history via LLM summary
 | |
 | overflow? --yes--> raise
 |
 SessionStore.save_turn() --> append to JSONL
 |
 v
 Print response

 File layout:
 workspace/.sessions/agents/{agent_id}/sessions/{session_id}.jsonl
 workspace/.sessions/agents/{agent_id}/sessions.json (index)

本节要点

SessionStore: JSONL 持久化. 写入时追加, 读取时重放.
_rebuild_history(): 将扁平的 JSONL 转换回 API 兼容的 messages[].
ContextGuard: 3 阶段溢出重试 (正常 -> 截断 -> 压缩 -> 失败).
compact_history(): LLM 生成摘要替换旧消息.
REPL 命令: /new, /switch, /context, /compact 用于会话管理.

核心代码走读

1. JSONL 追加与重放

每个会话是一个 .jsonl 文件 – 每行一条 JSON 记录. 追加写入是原子的 (不需要重写整个文件). 四种记录类型:

1
2
3
4


{"type": "user", "content": "Hello", "ts": 1234567890}
{"type": "assistant", "content": [{"type": "text", "text": "Hi!"}], "ts": ...}
{"type": "tool_use", "tool_use_id": "toolu_...", "name": "read_file", "input": {...}, "ts": ...}
{"type": "tool_result", "tool_use_id": "toolu_...", "content": "file contents", "ts": ...}

_rebuild_history() 方法将这些扁平记录转换回 Anthropic API 格式 (严格交替 user/assistant, tool_use 在 assistant 内, tool_result 在 user 内):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


def _rebuild_history(self, path: Path) -> list[dict]:
 messages: list[dict] = []
 for line in path.read_text(encoding="utf-8").strip().split("\n"):
 record = json.loads(line)
 rtype = record.get("type")

 if rtype == "user":
 messages.append({"role": "user", "content": record["content"]})
 elif rtype == "assistant":
 content = record["content"]
 if isinstance(content, str):
 content = [{"type": "text", "text": content}]
 messages.append({"role": "assistant", "content": content})
 elif rtype == "tool_use":
 # 合并到最后一条 assistant 消息
 block = {"type": "tool_use", "id": record["tool_use_id"],
 "name": record["name"], "input": record["input"]}
 if messages and messages[-1]["role"] == "assistant":
 messages[-1]["content"].append(block)
 else:
 messages.append({"role": "assistant", "content": [block]})
 elif rtype == "tool_result":
 # 将连续的结果合并到同一条 user 消息
 result_block = {"type": "tool_result",
 "tool_use_id": record["tool_use_id"],
 "content": record["content"]}
 if (messages and messages[-1]["role"] == "user"
 and isinstance(messages[-1]["content"], list)
 and messages[-1]["content"][0].get("type") == "tool_result"):
 messages[-1]["content"].append(result_block)
 else:
 messages.append({"role": "user", "content": [result_block]})
 return messages

2. 3 阶段保护

guard_api_call() 包裹每次 API 调用. 如果上下文溢出, 它会用越来越激进的策略重试:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


def guard_api_call(self, api_client, model, system, messages,
 tools=None, max_retries=2):
 current_messages = messages
 for attempt in range(max_retries + 1):
 try:
 result = api_client.messages.create(
 model=model, max_tokens=8096,
 system=system, messages=current_messages,
 **({"tools": tools} if tools else {}),
 )
 if current_messages is not messages:
 messages.clear()
 messages.extend(current_messages)
 return result
 except Exception as exc:
 error_str = str(exc).lower()
 is_overflow = ("context" in error_str or "token" in error_str)
 if not is_overflow or attempt >= max_retries:
 raise
 if attempt == 0:
 current_messages = self._truncate_large_tool_results(current_messages)
 elif attempt == 1:
 current_messages = self.compact_history(
 current_messages, api_client, model)

3. 历史压缩

将最早 50% 的消息序列化为纯文本, 让 LLM 生成摘要, 用摘要 + 近期消息替换:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


def compact_history(self, messages, api_client, model):
 keep_count = max(4, int(len(messages) * 0.2))
 compress_count = max(2, int(len(messages) * 0.5))
 compress_count = min(compress_count, len(messages) - keep_count)

 old_text = _serialize_messages_for_summary(messages[:compress_count])
 summary_resp = api_client.messages.create(
 model=model, max_tokens=2048,
 system="You are a conversation summarizer. Be concise and factual.",
 messages=[{"role": "user", "content": summary_prompt}],
 )
 # 用摘要 + "Understood" 对替换旧消息
 compacted = [
 {"role": "user", "content": "[Previous conversation summary]\n" + summary},
 {"role": "assistant", "content": [{"type": "text",
 "text": "Understood, I have the context."}]},
 ]
 compacted.extend(messages[compress_count:])
 return compacted

试一试

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


python zh/s03_sessions.py

# 创建会话并在会话之间切换
# You > /new my-project
# You > 给我讲讲 Python 生成器
# You > /new experiments
# You > 2+2 等于多少?
# You > /switch my-p (前缀匹配)

# 查看上下文使用情况
# You > /context
# Context usage: ~1,234 / 180,000 tokens
# [####--------------------------] 0.7%

# 上下文过大时手动压缩
# You > /compact

OpenClaw 中的对应实现

方面	claw0 (本文件)	OpenClaw 生产代码
存储格式	JSONL 文件, 每个会话一个	相同的 JSONL 格式
重放	`_rebuild_history()`	相同的重建逻辑
溢出处理	3 阶段保护	相同模式 + token 计数 API
压缩	LLM 摘要替换旧消息	相同方案, 自适应压缩
token 估算	`len(text) // 4` 启发式	API 提供的 token 计数

第 04 节: 通道

每个平台都不同, 但它们都产生相同的 InboundMessage.

架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


 Telegram ----. .---- sendMessage API
 Feishu -------+-- InboundMessage ---+---- im/v1/messages
 CLI (stdin) --' Agent Loop '---- print(stdout)
 (same brain)

 Telegram detail:
 getUpdates (long-poll, 30s)
 |
 offset persist (disk)
 |
 media_group_id? --yes--> buffer 500ms --> merge captions
 |no
 text buffer (1s silence) --> flush
 |
 InboundMessage --> allowed_chats filter --> agent turn

本节要点

InboundMessage: 一个 dataclass, 将所有平台的消息负载统一为同一格式.
Channel ABC: receive() + send() 就是全部接口契约.
TelegramChannel: 长轮询, offset 持久化, 媒体组缓冲, 文本合并.
FeishuChannel: 基于 webhook, token 认证, @提及检测, 多类型消息解析.
ChannelManager: 持有所有活跃通道的注册中心.

核心代码走读

1. InboundMessage – 统一的消息格式

每个通道都归一化为此格式. agent 循环只看到 InboundMessage, 永远不接触平台特定的负载.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


@dataclass
class InboundMessage:
 text: str
 sender_id: str
 channel: str = "" # "cli", "telegram", "feishu"
 account_id: str = "" # 接收消息的 bot
 peer_id: str = "" # DM=user_id, group=chat_id, topic=chat_id:topic:thread_id
 is_group: bool = False
 media: list = field(default_factory=list)
 raw: dict = field(default_factory=dict)

peer_id 编码了会话范围:

上下文	peer_id 格式
Telegram 私聊	`user_id`
Telegram 群组	`chat_id`
Telegram 话题	`chat_id:topic:thread_id`
飞书单聊	`user_id`
飞书群组	`chat_id`

2. Channel 抽象基类

添加新平台只需实现两个方法:

1
2
3
4
5
6
7
8


class Channel(ABC):
 name: str = "unknown"

 @abstractmethod
 def receive(self) -> InboundMessage | None: ...

 @abstractmethod
 def send(self, to: str, text: str, **kwargs: Any) -> bool: ...

CLIChannel 是最简单的实现 – receive() 包装 input(), send() 包装 print():

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


class CLIChannel(Channel):
 name = "cli"

 def receive(self) -> InboundMessage | None:
 text = input("You > ").strip()
 if not text:
 return None
 return InboundMessage(
 text=text, sender_id="cli-user", channel="cli",
 account_id="cli-local", peer_id="cli-user",
 )

 def send(self, to: str, text: str, **kwargs: Any) -> bool:
 print_assistant(text)
 return True

3. run_agent_turn – 与通道无关的处理逻辑

agent turn 函数接收一个 InboundMessage, 运行标准的工具循环, 然后通过来源通道发送回复:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


def run_agent_turn(inbound: InboundMessage, conversations: dict, mgr: ChannelManager):
 sk = build_session_key(inbound.channel, inbound.account_id, inbound.peer_id)
 if sk not in conversations:
 conversations[sk] = []
 messages = conversations[sk]
 messages.append({"role": "user", "content": inbound.text})

 # Telegram 的输入指示器
 if inbound.channel == "telegram":
 tg = mgr.get("telegram")
 if isinstance(tg, TelegramChannel):
 tg.send_typing(inbound.peer_id.split(":topic:")[0])

 while True:
 response = client.messages.create(
 model=MODEL_ID, max_tokens=8096,
 system=SYSTEM_PROMPT, tools=TOOLS, messages=messages,
 )
 messages.append({"role": "assistant", "content": response.content})

 if response.stop_reason == "end_turn":
 text = "".join(b.text for b in response.content if hasattr(b, "text"))
 ch = mgr.get(inbound.channel)
 if ch:
 ch.send(inbound.peer_id, text)
 break
 elif response.stop_reason == "tool_use":
 # 分发工具, 追加结果, 继续
 ...

试一试

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 仅 CLI (除了 API key 外不需要其他环境变量)
python zh/s04_channels.py

# 启用 Telegram -- 在 .env 中添加:
# TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
# TELEGRAM_ALLOWED_CHATS=12345,67890 (可选白名单)

# 启用飞书 -- 在 .env 中添加:
# FEISHU_APP_ID=cli_xxxxx
# FEISHU_APP_SECRET=xxxxx

# REPL 命令
# You > /channels (列出已注册的通道)
# You > /accounts (显示 bot 账号)

OpenClaw 中的对应实现

方面	claw0 (本文件)	OpenClaw 生产代码
Channel ABC	`receive()` + `send()`	相同接口 + 生命周期钩子
平台数量	CLI, Telegram, 飞书	10+ (Telegram, Discord, Slack 等)
并发模型	每个通道一个线程 + 共享队列	相同的线程模型 + 异步网关
消息格式	`InboundMessage` dataclass	相同的统一消息类型
Offset 存储	纯文本文件	带版本号的 JSON + 原子写入

第 05 节: 网关与路由

一张绑定表将 (channel, peer) 映射到 agent_id. 最具体的匹配优先.

架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


 Inbound Message (channel, account_id, peer_id, text)
 |
 +------v------+ +----------+
 | Gateway | <-- | WS/REPL | JSON-RPC 2.0
 +------+------+ +----------+
 |
 +------v------+
 | BindingTable | 5-tier resolution:
 +------+------+ T1: peer_id (most specific)
 | T2: guild_id
 | T3: account_id
 | T4: channel
 | T5: default (least specific)
 |
 (agent_id, binding)
 |
 +------v---------+
 | build_session_key() | dm_scope controls isolation
 +------+---------+
 |
 +------v------+
 | AgentManager | per-agent config / personality / sessions
 +------+------+
 |
 LLM API

本节要点

BindingTable: 排序的路由绑定列表. 从 tier 1 到 tier 5 遍历, 首次匹配即返回.
build_session_key(): dm_scope 控制会话隔离 (每用户、每通道等).
AgentManager: 多 agent 注册中心 – 每个 agent 有自己的性格和模型.
GatewayServer: 可选的 WebSocket 服务器, 使用 JSON-RPC 2.0 协议.
共享事件循环: daemon 线程中的 asyncio 循环, 信号量限制并发数为 4.

核心代码走读

1. BindingTable.resolve() – 路由核心

绑定按 (tier, -priority) 排序. 解析时线性遍历, 首次匹配即返回.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


@dataclass
class Binding:
 agent_id: str
 tier: int # 1-5, 越小越具体
 match_key: str # "peer_id" | "guild_id" | "account_id" | "channel" | "default"
 match_value: str # e.g. "telegram:12345", "discord", "*"
 priority: int = 0 # 同一 tier 内, 越高越优先

class BindingTable:
 def resolve(self, channel="", account_id="",
 guild_id="", peer_id="") -> tuple[str | None, Binding | None]:
 for b in self._bindings:
 if b.tier == 1 and b.match_key == "peer_id":
 if ":" in b.match_value:
 if b.match_value == f"{channel}:{peer_id}":
 return b.agent_id, b
 elif b.match_value == peer_id:
 return b.agent_id, b
 elif b.tier == 2 and b.match_key == "guild_id" and b.match_value == guild_id:
 return b.agent_id, b
 elif b.tier == 3 and b.match_key == "account_id" and b.match_value == account_id:
 return b.agent_id, b
 elif b.tier == 4 and b.match_key == "channel" and b.match_value == channel:
 return b.agent_id, b
 elif b.tier == 5 and b.match_key == "default":
 return b.agent_id, b
 return None, None

给定以下示例绑定:

1
2
3
4


bt.add(Binding(agent_id="luna", tier=5, match_key="default", match_value="*"))
bt.add(Binding(agent_id="sage", tier=4, match_key="channel", match_value="telegram"))
bt.add(Binding(agent_id="sage", tier=1, match_key="peer_id",
 match_value="discord:admin-001", priority=10))

输入	Tier	Agent
`channel=cli, peer=user1`	5	Luna
`channel=telegram, peer=user2`	4	Sage
`channel=discord, peer=admin-001`	1	Sage
`channel=discord, peer=user3`	5	Luna

2. 带 dm_scope 的会话 key

agent 解析完成后, agent 配置上的 dm_scope 控制会话隔离方式:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


def build_session_key(agent_id, channel="", account_id="",
 peer_id="", dm_scope="per-peer"):
 aid = normalize_agent_id(agent_id)
 if dm_scope == "per-account-channel-peer" and peer_id:
 return f"agent:{aid}:{channel}:{account_id}:direct:{peer_id}"
 if dm_scope == "per-channel-peer" and peer_id:
 return f"agent:{aid}:{channel}:direct:{peer_id}"
 if dm_scope == "per-peer" and peer_id:
 return f"agent:{aid}:direct:{peer_id}"
 return f"agent:{aid}:main"

dm_scope	Key 格式	效果
`main`	`agent:{id}:main`	所有人共享一个会话
`per-peer`	`agent:{id}:direct:{peer}`	每个用户隔离
`per-channel-peer`	`agent:{id}:{ch}:direct:{peer}`	每个平台的不同会话
`per-account-channel-peer`	`agent:{id}:{ch}:{acc}:direct:{peer}`	最大隔离度

3. AgentConfig – 每个 agent 的性格

每个 agent 携带自己的配置. 系统提示词从配置生成:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


@dataclass
class AgentConfig:
 id: str
 name: str
 personality: str = ""
 model: str = "" # 空 = 使用全局 MODEL_ID
 dm_scope: str = "per-peer"

 def system_prompt(self) -> str:
 parts = [f"You are {self.name}."]
 if self.personality:
 parts.append(f"Your personality: {self.personality}")
 parts.append("Answer questions helpfully and stay in character.")
 return " ".join(parts)

试一试

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


python zh/s05_gateway_routing.py

# 测试路由
# You > /bindings (查看所有路由绑定)
# You > /route cli user1 (通过 default 解析到 Luna)
# You > /route telegram user2 (通过 channel 绑定解析到 Sage)

# 强制指定 agent
# You > /switch sage
# You > Hello! (无论路由结果如何都和 Sage 对话)
# You > /switch off (恢复正常路由)

# 启动 WebSocket 网关
# You > /gateway
# Gateway running on ws://localhost:8765

OpenClaw 中的对应实现

方面	claw0 (本文件)	OpenClaw 生产代码
路由解析	5 层线性扫描	相同的层级系统 + 配置文件
会话 key	`dm_scope` 参数	相同的 dm_scope + 持久化会话
多 agent	内存中的 AgentConfig	每个 agent 独立的工作区目录
网关	WebSocket + JSON-RPC 2.0	相同协议 + HTTP API
并发控制	`asyncio.Semaphore(4)`	相同的信号量模式

第 06 节: 智能层

系统提示词从磁盘上的文件组装. 换文件, 换性格.

架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


 Startup Per-Turn
 ======= ========

 BootstrapLoader User Input
 load SOUL.md, IDENTITY.md, ... |
 truncate per file (20k) v
 cap total (150k) _auto_recall(user_input)
 | search memory by TF-IDF
 v |
 SkillsManager v
 scan directories for SKILL.md build_system_prompt()
 parse frontmatter assemble 8 layers:
 deduplicate by name 1. Identity
 | 2. Soul (personality)
 v 3. Tools guidance
 bootstrap_data + skills_block 4. Skills
 (cached for all turns) 5. Memory (evergreen + recalled)
 6. Bootstrap (remaining files)
 7. Runtime context
 8. Channel hints
 |
 v
 LLM API call

 Earlier layers = stronger influence on behavior.
 SOUL.md is at layer 2 for exactly this reason.

本节要点

BootstrapLoader: 从工作区加载最多 8 个 markdown 文件, 有单文件和总量上限.
SkillsManager: 扫描多个目录查找带 YAML frontmatter 的 SKILL.md 文件.
MemoryStore: 双层存储 (常驻 MEMORY.md + 每日 JSONL), TF-IDF 搜索.
_auto_recall(): 用用户消息搜索记忆, 将结果注入提示词.
build_system_prompt(): 将 8 个层组装为一个字符串, 每轮重新构建.

核心代码走读

1. build_system_prompt() – 8 层组装

这个函数是智能系统的核心. 它每轮都产生不同的系统提示词, 因为记忆可能已经被更新.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


def build_system_prompt(mode="full", bootstrap=None, skills_block="",
 memory_context="", agent_id="main", channel="terminal"):
 sections: list[str] = []

 # 第 1 层: 身份
 identity = bootstrap.get("IDENTITY.md", "").strip()
 sections.append(identity if identity else "You are a helpful AI assistant.")

 # 第 2 层: 灵魂 (性格) -- 越靠前 = 影响力越强
 if mode == "full":
 soul = bootstrap.get("SOUL.md", "").strip()
 if soul:
 sections.append(f"### Personality\n\n{soul}")

 # 第 3 层: 工具使用指南
 tools_md = bootstrap.get("TOOLS.md", "").strip()
 if tools_md:
 sections.append(f"### Tool Usage Guidelines\n\n{tools_md}")

 # 第 4 层: 技能
 if mode == "full" and skills_block:
 sections.append(skills_block)

 # 第 5 层: 记忆 (常驻 + 自动搜索的)
 if mode == "full":
 # ... 合并 MEMORY.md 和召回的记忆

 # 第 6 层: 引导上下文 (HEARTBEAT.md, BOOTSTRAP.md, AGENTS.md, USER.md)
 # 第 7 层: 运行时上下文 (agent ID, 模型, 通道, 时间)
 # 第 8 层: 通道提示 ("You are responding via Telegram.")

 return "\n\n".join(sections)

2. MemoryStore.search_memory() – TF-IDF 搜索

纯 Python 实现, 不需要外部向量数据库. 加载所有记忆片段, 计算 TF-IDF 向量, 按余弦相似度排序.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


def search_memory(self, query: str, top_k: int = 5) -> list[dict]:
 chunks = self._load_all_chunks() # MEMORY.md 段落 + 每日 JSONL 条目
 query_tokens = self._tokenize(query)
 chunk_tokens = [self._tokenize(c["text"]) for c in chunks]

 # 所有片段的文档频率
 df: dict[str, int] = {}
 for tokens in chunk_tokens:
 for t in set(tokens):
 df[t] = df.get(t, 0) + 1

 def tfidf(tokens):
 tf = {}
 for t in tokens:
 tf[t] = tf.get(t, 0) + 1
 return {t: c * (math.log((n + 1) / (df.get(t, 0) + 1)) + 1)
 for t, c in tf.items()}

 def cosine(a, b):
 common = set(a) & set(b)
 if not common:
 return 0.0
 dot = sum(a[k] * b[k] for k in common)
 na = math.sqrt(sum(v * v for v in a.values()))
 nb = math.sqrt(sum(v * v for v in b.values()))
 return dot / (na * nb) if na and nb else 0.0

 qvec = tfidf(query_tokens)
 scored = []
 for i, tokens in enumerate(chunk_tokens):
 score = cosine(qvec, tfidf(tokens))
 if score > 0.0:
 scored.append({"path": chunks[i]["path"], "score": score,
 "snippet": chunks[i]["text"][:200]})
 scored.sort(key=lambda x: x["score"], reverse=True)
 return scored[:top_k]

3. 混合搜索管道 – 向量 + 关键词 + MMR

完整的搜索管道串联五个阶段:

关键词搜索 (TF-IDF): 与上面相同的算法, 按余弦相似度返回 top-10
向量搜索 (哈希投影): 通过基于哈希的随机投影模拟嵌入向量, 返回 top-10
合并: 按文本前缀取并集, 加权组合 (vector_weight=0.7, text_weight=0.3)
时间衰减: score *= exp(-decay_rate * age_days), 越近的记忆得分越高
Maximal Marginal Relevance (a.k.a MMR) 算法重排序: MMR = lambda * relevance - (1-lambda) * max_similarity_to_selected, 用 token 集合的 Jaccard 相似度保证多样性

基于哈希的向量嵌入展示了双通道搜索的模式, 不需要外部嵌入 API.

4. _auto_recall() – 自动记忆注入

每次 LLM 调用之前, 自动搜索相关记忆并注入到系统提示词中. 用户不需要显式请求.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


def _auto_recall(user_message: str) -> str:
 results = memory_store.search_memory(user_message, top_k=3)
 if not results:
 return ""
 return "\n".join(f"- [{r['path']}] {r['snippet']}" for r in results)

# 在 agent 循环中, 每轮:
memory_context = _auto_recall(user_input)
system_prompt = build_system_prompt(
 mode="full", bootstrap=bootstrap_data,
 skills_block=skills_block, memory_context=memory_context,
)

试一试

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


python zh/s06_intelligence.py

# 创建工作区文件以体验完整系统:
# workspace/SOUL.md -- "You are warm, curious, and encouraging."
# workspace/IDENTITY.md -- "You are Luna, a personal AI companion."
# workspace/MEMORY.md -- "User prefers Python over JavaScript."

# 查看组装好的提示词
# You > /prompt

# 检查加载了哪些引导文件
# You > /bootstrap

# 搜索记忆
# You > /search python

# 告诉它一些信息, 然后过一会再问
# You > 我最喜欢的颜色是蓝色.
# You > 你知道我的偏好吗?
# (auto-recall 找到颜色记忆并注入提示词)

OpenClaw 中的对应实现

方面	claw0 (本文件)	OpenClaw 生产代码
提示词组装	8 层 `build_system_prompt`	相同的分层方案
引导文件	从工作区目录加载	相同的文件集 + 每个 agent 的覆盖配置
记忆搜索	混合管道 (TF-IDF + 向量 + MMR)	相同方案 + 可选的 embedding API
技能发现	扫描目录查找 SKILL.md	相同的扫描 + 插件系统
自动召回	每条用户消息都搜索	相同模式, top_k 可配置

第 07 节: 心跳与 Cron

一个定时器线程检查"该不该运行", 然后将任务排入与用户消息相同的队列.

架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


 Main Lane (user input):
 User Input --> lane_lock.acquire() -------> LLM --> Print
 (blocking: always wins)

 Heartbeat Lane (background thread, 1s poll):
 should_run()?
 |no --> sleep 1s
 |yes
 _execute():
 lane_lock.acquire(blocking=False)
 |fail --> yield (user has priority)
 |success
 build prompt from HEARTBEAT.md + SOUL.md + MEMORY.md
 |
 run_agent_single_turn()
 |
 parse: "HEARTBEAT_OK"? --> suppress
 meaningful text? --> duplicate? --> suppress
 |no
 output_queue.append()

 Cron Service (background thread, 1s tick):
 CRON.json --> load jobs --> tick() every 1s
 |
 for each job: enabled? --> due? --> _run_job()
 |
 error? --> consecutive_errors++ --> >=5? --> auto-disable
 |ok
 consecutive_errors = 0 --> log to cron-runs.jsonl

本节要点

Lane 互斥: threading.Lock 在用户和心跳之间共享. 用户总是赢 (阻塞获取); 心跳让步 (非阻塞获取).
should_run(): 每次心跳尝试前的 4 个前置条件检查.
HEARTBEAT_OK: agent 用来表示"没有需要报告的内容"的约定.
CronService: 3 种调度类型 (at, every, cron), 连续错误 5 次后自动禁用.
输出队列: 后台结果通过线程安全的列表输送到 REPL.

核心代码走读

1. Lane 互斥

最重要的设计原则: 用户消息始终优先.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


lane_lock = threading.Lock()

# Main lane: 阻塞获取. 用户始终能进入.
lane_lock.acquire()
try:
 # 处理用户消息, 调用 LLM
finally:
 lane_lock.release()

# Heartbeat lane: 非阻塞获取. 用户活跃时让步.
def _execute(self) -> None:
 acquired = self.lane_lock.acquire(blocking=False)
 if not acquired:
 return # 用户持有锁, 跳过本次心跳
 self.running = True
 try:
 instructions, sys_prompt = self._build_heartbeat_prompt()
 response = run_agent_single_turn(instructions, sys_prompt)
 meaningful = self._parse_response(response)
 if meaningful and meaningful.strip() != self._last_output:
 self._last_output = meaningful.strip()
 with self._queue_lock:
 self._output_queue.append(meaningful)
 finally:
 self.running = False
 self.last_run_at = time.time()
 self.lane_lock.release()

2. should_run() – 前置条件链

四个检查必须全部通过. 锁的检测在 _execute() 中单独进行, 以避免 TOCTOU（Time of Check to Time of Use）竞态条件.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


def should_run(self) -> tuple[bool, str]:
 if not self.heartbeat_path.exists():
 return False, "HEARTBEAT.md not found"
 if not self.heartbeat_path.read_text(encoding="utf-8").strip():
 return False, "HEARTBEAT.md is empty"

 elapsed = time.time() - self.last_run_at
 if elapsed < self.interval:
 return False, f"interval not elapsed ({self.interval - elapsed:.0f}s remaining)"

 hour = datetime.now().hour
 s, e = self.active_hours
 in_hours = (s <= hour < e) if s <= e else not (e <= hour < s)
 if not in_hours:
 return False, f"outside active hours ({s}:00-{e}:00)"

 if self.running:
 return False, "already running"
 return True, "all checks passed"

3. CronService – 3 种调度类型

任务定义在 CRON.json 中. 每个任务有一个 schedule.kind 和一个 payload:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


@dataclass
class CronJob:
 id: str
 name: str
 enabled: bool
 schedule_kind: str # "at" | "every" | "cron"
 schedule_config: dict
 payload: dict # {"kind": "agent_turn", "message": "..."}
 consecutive_errors: int = 0

def _compute_next(self, job, now):
 if job.schedule_kind == "at":
 ts = datetime.fromisoformat(cfg.get("at", "")).timestamp()
 return ts if ts > now else 0.0
 if job.schedule_kind == "every":
 every = cfg.get("every_seconds", 3600)
 # 对齐到锚点, 保证触发时间可预测
 steps = int((now - anchor) / every) + 1
 return anchor + steps * every
 if job.schedule_kind == "cron":
 return croniter(expr, datetime.fromtimestamp(now)).get_next(datetime).timestamp()

连续 5 次错误后自动禁用:

1
2
3
4
5
6


if status == "error":
 job.consecutive_errors += 1
 if job.consecutive_errors >= 5:
 job.enabled = False
else:
 job.consecutive_errors = 0

试一试

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


python zh/s07_heartbeat_cron.py

# 创建 workspace/HEARTBEAT.md 写入指令:
# "Check if there are any unread reminders. Reply HEARTBEAT_OK if nothing to report."

# 检查心跳状态
# You > /heartbeat

# 手动触发心跳
# You > /trigger

# 列出 cron 任务 (需要 workspace/CRON.json)
# You > /cron

# 检查 lane 锁状态
# You > /lanes
# main_locked: False heartbeat_running: False

CRON.json 示例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{
 "jobs": [
 {
 "id": "daily-check",
 "name": "Daily Check",
 "enabled": true,
 "schedule": {"kind": "cron", "expr": "0 9 * * *"},
 "payload": {"kind": "agent_turn", "message": "Generate a daily summary."}
 }
 ]
}

OpenClaw 中的对应实现

方面	claw0 (本文件)	OpenClaw 生产代码
Lane 互斥	`threading.Lock`, 非阻塞	相同的锁模式
心跳配置	工作区中的 `HEARTBEAT.md`	相同文件 + 环境变量覆盖
Cron 调度	`CRON.json`, 3 种类型	相同格式 + webhook 触发器
自动禁用	连续 5 次错误	相同阈值, 可配置
输出投递	内存队列, 排出到 REPL	投递队列 (第 08 节)

第 08 节: 消息投递

先写磁盘, 再尝试发送. 崩溃安全.

架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


 Agent Reply / Heartbeat / Cron
 |
 chunk_message() split by platform limits
 | (telegram=4096, discord=2000, etc.)
 v
 DeliveryQueue.enqueue()
 1. Generate unique ID
 2. Write to .tmp.{pid}.{id}.json
 3. fsync()
 4. os.replace() to {id}.json <-- WRITE-AHEAD
 |
 v
 DeliveryRunner (background thread, 1s scan)
 |
 deliver_fn(channel, to, text)
 / \
 success failure
 | |
 ack() fail()
 (delete (retry_count++, compute backoff,
 .json) update .json on disk)
 |
 retry_count >= 5?
 |yes
 move to failed/

 Backoff: [5s, 25s, 2min, 10min] with +/-20% jitter

本节要点

DeliveryQueue: 磁盘持久化的预写队列. 入队时先写磁盘, 再尝试投递.
原子写入: 临时文件 + os.fsync() + os.replace() – 崩溃时不会产生半写文件.
DeliveryRunner: 后台线程, 以指数退避处理待投递条目.
chunk_message(): 按平台大小限制分片文本, 尊重段落边界.
启动恢复扫描: 启动时自动重试上次崩溃前遗留的待投递条目.

核心代码走读

1. DeliveryQueue.enqueue() + 原子写入

基本规则: 先写磁盘, 再尝试投递. 如果进程在入队和投递之间崩溃, 消息仍然保存在磁盘上.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


def enqueue(self, channel: str, to: str, text: str) -> str:
 delivery_id = uuid.uuid4().hex[:12]
 entry = QueuedDelivery(
 id=delivery_id, channel=channel, to=to, text=text,
 enqueued_at=time.time(), next_retry_at=0.0,
 )
 self._write_entry(entry)
 return delivery_id

def _write_entry(self, entry: QueuedDelivery) -> None:
 final_path = self.queue_dir / f"{entry.id}.json"
 tmp_path = self.queue_dir / f".tmp.{os.getpid()}.{entry.id}.json"

 data = json.dumps(entry.to_dict(), indent=2, ensure_ascii=False)
 with open(tmp_path, "w", encoding="utf-8") as f:
 f.write(data)
 f.flush()
 os.fsync(f.fileno()) # 数据已落盘

 os.replace(str(tmp_path), str(final_path)) # POSIX 上的原子操作

三步保证:

第 1 步: 写入 .tmp.{pid}.{id}.json (崩溃 = 孤立的临时文件, 无害)
第 2 步: fsync() – 数据已落盘
第 3 步: os.replace() – 原子交换 (崩溃 = 旧文件或新文件, 绝不会是半写文件)

2. ack() / fail() – 重试生命周期

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


def ack(self, delivery_id: str) -> None:
 """投递成功. 删除队列文件."""
 (self.queue_dir / f"{delivery_id}.json").unlink()

def fail(self, delivery_id: str, error: str) -> None:
 """递增 retry_count, 计算下次重试时间, 或放弃."""
 entry = self._read_entry(delivery_id)
 entry.retry_count += 1
 entry.last_error = error
 if entry.retry_count >= MAX_RETRIES:
 self.move_to_failed(delivery_id)
 return
 backoff_ms = compute_backoff_ms(entry.retry_count)
 entry.next_retry_at = time.time() + backoff_ms / 1000.0
 self._write_entry(entry) # 将新的重试状态更新到磁盘

带抖动的退避, 防止雷群效应:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


BACKOFF_MS = [5_000, 25_000, 120_000, 600_000]
MAX_RETRIES = 5

def compute_backoff_ms(retry_count: int) -> int:
 if retry_count <= 0:
 return 0
 idx = min(retry_count - 1, len(BACKOFF_MS) - 1)
 base = BACKOFF_MS[idx]
 jitter = random.randint(-base // 5, base // 5) # +/- 20%
 return max(0, base + jitter)

3. DeliveryRunner – 后台循环

每秒扫描待投递条目. 只处理 next_retry_at 已到期的条目. 启动时执行恢复扫描, 处理上次崩溃遗留的条目.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


class DeliveryRunner:
 def start(self) -> None:
 self._recovery_scan()
 self._thread = threading.Thread(
 target=self._background_loop, daemon=True)
 self._thread.start()

 def _process_pending(self) -> None:
 pending = self.queue.load_pending()
 now = time.time()
 for entry in pending:
 if entry.next_retry_at > now:
 continue
 self.total_attempted += 1
 try:
 self.deliver_fn(entry.channel, entry.to, entry.text)
 self.queue.ack(entry.id)
 self.total_succeeded += 1
 except Exception as exc:
 self.queue.fail(entry.id, str(exc))
 self.total_failed += 1

试一试

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


python zh/s08_delivery.py

# 发送一条消息 -- 观察它被入队并投递
# You > Hello!

# 开启 50% 失败率
# You > /simulate-failure

# 再发一条消息 -- 观察带退避的重试
# You > 在失败模式下的测试消息

# 查看队列
# You > /queue
# You > /failed

# 恢复正常, 观察待投递条目被送出
# You > /simulate-failure

# 查看统计数据
# You > /stats

OpenClaw 中的对应实现

方面	claw0 (本文件)	OpenClaw 生产代码
队列存储	目录中的 JSON 文件	相同的每条目一个文件模式
原子写入	tmp + fsync + os.replace	相同方案
退避	[5s, 25s, 2min, 10min] + 抖动	相同的调度
消息分片	段落边界分割	相同 + 代码围栏感知
恢复	启动时扫描队列目录	相同的扫描 + 孤立文件清理

全系列总结

10 个章节, 构成一个 agent 网关的核心机制:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


 Section 01: while True + stop_reason (循环)
 Section 02: TOOLS + TOOL_HANDLERS (执行)
 Section 03: JSONL + ContextGuard (持久化)
 Section 04: Channel ABC + InboundMessage (通道)
 Section 05: BindingTable + session key (路由)
 Section 06: 8-layer prompt + hybrid search (智能)
 Section 07: Heartbeat + Cron (自治)
 Section 08: DeliveryQueue + backoff (可靠投递)
 Section 09: 3-layer retry onion + profiles (韧性)
 Section 10: Named lanes + generation track (并发)

第 01 节的 agent 循环在第 10 节的核心依然清晰可辨. AI agent 就是一个 while True 循环加上一张分发表, 外面包裹着持久化、路由、智能、调度、可靠性、韧性和并发控制的层层机制.

第 09 节: 弹性

一次调用失败, 轮换重试.

架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


 Profiles: [main-key, backup-key, emergency-key]
 |
 for each non-cooldown profile: LAYER 1: Auth Rotation
 |
 create client(profile.api_key)
 |
 for compact_attempt in 0..2: LAYER 2: Overflow Recovery
 |
 _run_attempt(client, model, ...) LAYER 3: Tool-Use Loop
 | |
 success exception
 | |
 mark_success classify_failure()
 return result |
 overflow? --> compact, retry Layer 2
 auth/rate? -> mark_failure, break to Layer 1
 timeout? --> mark_failure(60s), break to Layer 1
 |
 all profiles exhausted?
 |
 try fallback models
 |
 all fallbacks failed?
 |
 raise RuntimeError

本节要点

FailoverReason: 枚举, 将每个异常分类为六个类别之一 (rate_limit, auth, timeout, billing, overflow, unknown). 类别决定由哪一层重试处理.
AuthProfile: 数据类, 持有一个 API key 及其冷却状态. 跟踪 cooldown_until、failure_reason 和 last_good_at.
ProfileManager: 选择第一个未冷却的配置, 标记失败 (设置冷却), 标记成功 (清除失败状态).
ContextGuard: 轻量级上下文溢出保护. 截断过大的工具结果, 如果仍然溢出则通过 LLM 摘要压缩历史.
ResilienceRunner: 三层重试洋葱. Layer 1 轮换配置, Layer 2 处理溢出压缩, Layer 3 是标准的工具调用循环.
重试限制: BASE_RETRY=24, PER_PROFILE=8, 上限为 min(max(base + per_profile * N, 32), 160).
SimulatedFailure: 为下次 API 调用装备一个模拟错误, 让你无需真实故障即可观察各类失败的处理过程.

核心代码走读

1. classify_failure() – 将异常路由到正确的层

每个异常在重试洋葱决定处理方式之前都会经过分类. 分类器检查错误字符串中的已知模式:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


class FailoverReason(Enum):
 rate_limit = "rate_limit"
 auth = "auth"
 timeout = "timeout"
 billing = "billing"
 overflow = "overflow"
 unknown = "unknown"

def classify_failure(exc: Exception) -> FailoverReason:
 msg = str(exc).lower()
 if "rate" in msg or "429" in msg:
 return FailoverReason.rate_limit
 if "auth" in msg or "401" in msg or "key" in msg:
 return FailoverReason.auth
 if "timeout" in msg or "timed out" in msg:
 return FailoverReason.timeout
 if "billing" in msg or "quota" in msg or "402" in msg:
 return FailoverReason.billing
 if "context" in msg or "token" in msg or "overflow" in msg:
 return FailoverReason.overflow
 return FailoverReason.unknown

分类驱动不同的冷却时长:

auth / billing: 300s (坏 key, 不会很快自愈)
rate_limit: 120s (等待速率限制窗口重置)
timeout: 60s (瞬态故障, 短冷却)
overflow: 不冷却配置 – 改为压缩消息

2. ProfileManager – 冷却感知的 key 轮换

按顺序检查配置. 当冷却过期时配置可用. 失败后配置进入冷却; 成功后清除失败状态.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


class ProfileManager:
 def select_profile(self) -> AuthProfile | None:
 now = time.time()
 for profile in self.profiles:
 if now >= profile.cooldown_until:
 return profile
 return None

 def mark_failure(self, profile, reason, cooldown_seconds=300.0):
 profile.cooldown_until = time.time() + cooldown_seconds
 profile.failure_reason = reason.value

 def mark_success(self, profile):
 profile.failure_reason = None
 profile.last_good_at = time.time()

3. ResilienceRunner.run() – 三层洋葱

外层循环遍历配置 (Layer 1). 中间循环在压缩后重试溢出 (Layer 2). 内层调用运行工具调用循环 (Layer 3).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44


def run(self, system, messages, tools):
 # LAYER 1: Auth Rotation
 for _rotation in range(len(self.profile_manager.profiles)):
 profile = self.profile_manager.select_profile()
 if profile is None:
 break

 api_client = Anthropic(api_key=profile.api_key)

 # LAYER 2: Overflow Recovery
 layer2_messages = list(messages)
 for compact_attempt in range(MAX_OVERFLOW_COMPACTION):
 try:
 # LAYER 3: Tool-Use Loop
 result, layer2_messages = self._run_attempt(
 api_client, self.model_id, system,
 layer2_messages, tools,
 )
 self.profile_manager.mark_success(profile)
 return result, layer2_messages

 except Exception as exc:
 reason = classify_failure(exc)

 if reason == FailoverReason.overflow:
 # Compact and retry Layer 2
 layer2_messages = self.guard.truncate_tool_results(layer2_messages)
 layer2_messages = self.guard.compact_history(
 layer2_messages, api_client, self.model_id)
 continue

 elif reason in (FailoverReason.auth, FailoverReason.rate_limit):
 self.profile_manager.mark_failure(profile, reason)
 break # try next profile (Layer 1)

 elif reason == FailoverReason.timeout:
 self.profile_manager.mark_failure(profile, reason, 60)
 break # try next profile (Layer 1)

 # All profiles exhausted -- try fallback models
 for fallback_model in self.fallback_models:
 # ... try with first available profile ...

 raise RuntimeError("all profiles and fallbacks exhausted")

4. _run_attempt() – Layer 3 工具调用循环

最内层与第 01/02 节相同的 while True + stop_reason 分发. 在循环中运行工具调用, 直到模型返回 end_turn 或异常传播到外层.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


def _run_attempt(self, api_client, model, system, messages, tools):
 current_messages = list(messages)
 iteration = 0

 while iteration < self.max_iterations:
 iteration += 1
 response = api_client.messages.create(
 model=model, max_tokens=8096,
 system=system, tools=tools,
 messages=current_messages,
 )
 current_messages.append({"role": "assistant", "content": response.content})

 if response.stop_reason == "end_turn":
 return response, current_messages

 elif response.stop_reason == "tool_use":
 tool_results = []
 for block in response.content:
 if block.type != "tool_use":
 continue
 result = process_tool_call(block.name, block.input)
 tool_results.append({
 "type": "tool_result",
 "tool_use_id": block.id,
 "content": result,
 })
 current_messages.append({"role": "user", "content": tool_results})
 continue

 raise RuntimeError("Tool-use loop exceeded max iterations")

试一试

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


python zh/s09_resilience.py

# 正常对话 -- 观察单配置成功
# You > Hello!

# 查看配置状态
# You > /profiles

# 模拟速率限制失败 -- 观察配置轮换
# You > /simulate-failure rate_limit
# You > Tell me a joke

# 模拟认证失败
# You > /simulate-failure auth
# You > What time is it?

# 失败后检查冷却状态
# You > /cooldowns

# 查看备选模型链
# You > /fallback

# 查看弹性统计
# You > /stats

OpenClaw 中的对应实现

方面	claw0 (本文件)	OpenClaw 生产代码
配置轮换	3 个演示配置, 相同 key	跨提供商的多个真实 key
失败分类器	异常文本字符串匹配	相同模式, 加 HTTP 状态码检查
溢出恢复	截断工具结果 + LLM 摘要	相同的两阶段压缩
冷却追踪	内存中的浮点时间戳	相同的每配置内存追踪
备选模型	可配置的备选链	相同链, 通常为更小/更便宜的模型
重试限制	BASE_RETRY=24, PER_PROFILE=8, 上限=160	相同公式
模拟失败	/simulate-failure 命令用于测试	集成测试工具带故障注入

第 10 节: 并发

命名 lane 序列化混沌.

架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


 Incoming Work
 |
 CommandQueue.enqueue(lane, fn)
 |
 +---v---+ +--------+ +-----------+
 | main | | cron | | heartbeat |
 | max=1 | | max=1 | | max=1 |
 | FIFO | | FIFO | | FIFO |
 +---+---+ +---+----+ +-----+-----+
 | | |
 [active] [active] [active]
 | | |
 _task_done _task_done _task_done
 | | |
 _pump() _pump() _pump()
 (dequeue (dequeue (dequeue
 next if next if next if
 active<max) active<max) active<max)

每个 lane 是一个 LaneQueue: 由 threading.Condition 保护的 FIFO deque. 任务以普通 callable 进入, 通过 concurrent.futures.Future 返回结果. CommandQueue 按名称将工作分发到正确的 lane, 并管理完整的生命周期.

本节要点

命名 lane: 每个 lane 有一个名称 (如 "main", "cron", "heartbeat") 和独立的 FIFO 队列. Lane 在首次使用时惰性创建.
max_concurrency: 每个 lane 限制同时运行的任务数. 默认为 1 (串行执行). 增加以允许 lane 内的并行工作.
_pump() 循环: 每个任务完成后 (_task_done), lane 检查是否可以出队更多任务. 这种自泵送设计意味着不需要外部调度器.
基于 Future 的结果: 每次 enqueue() 返回一个 concurrent.futures.Future. 调用方可以通过 future.result() 阻塞等待, 或通过 add_done_callback() 附加回调.
Generation 追踪: 每个 lane 有一个整数 generation 计数器. reset_all() 时所有 generation 递增. 当过期任务完成时 (其 generation 与当前不匹配), 不调用 _pump() – 防止僵尸任务在重启后排空队列.
基于 Condition 的同步: threading.Condition 替代了第 07 节的原始 threading.Lock. 这使 wait_for_idle() 能高效地睡眠等待通知, 而非轮询.
用户优先: 用户输入进入 main lane 并阻塞等待结果. 后台工作 (心跳、cron) 进入独立的 lane, 永远不阻塞 REPL.

核心代码走读

1. LaneQueue – 核心原语

一个 lane 就是 deque + 条件变量 + 活跃计数器. _pump() 是引擎:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


class LaneQueue:
 def __init__(self, name: str, max_concurrency: int = 1) -> None:
 self.name = name
 self.max_concurrency = max(1, max_concurrency)
 self._deque = deque() # [(fn, future, generation), ...]
 self._condition = threading.Condition()
 self._active_count = 0
 self._generation = 0

 def enqueue(self, fn, generation=None):
 future = concurrent.futures.Future()
 with self._condition:
 gen = generation if generation is not None else self._generation
 self._deque.append((fn, future, gen))
 self._pump()
 return future

 def _pump(self):
 """Pop and start tasks while active < max_concurrency."""
 while self._active_count < self.max_concurrency and self._deque:
 fn, future, gen = self._deque.popleft()
 self._active_count += 1
 threading.Thread(
 target=self._run_task, args=(fn, future, gen), daemon=True
 ).start()

 def _task_done(self, gen):
 with self._condition:
 self._active_count -= 1
 if gen == self._generation: # stale tasks do not re-pump
 self._pump()
 self._condition.notify_all()

2. CommandQueue – 调度器

CommandQueue 持有 lane_name 到 LaneQueue 的字典. Lane 惰性创建:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


class CommandQueue:
 def __init__(self):
 self._lanes: dict[str, LaneQueue] = {}
 self._lock = threading.Lock()

 def get_or_create_lane(self, name, max_concurrency=1):
 with self._lock:
 if name not in self._lanes:
 self._lanes[name] = LaneQueue(name, max_concurrency)
 return self._lanes[name]

 def enqueue(self, lane_name, fn):
 lane = self.get_or_create_lane(lane_name)
 return lane.enqueue(fn)

 def reset_all(self):
 """Increment generation on all lanes for restart recovery."""
 with self._lock:
 for lane in self._lanes.values():
 with lane._condition:
 lane._generation += 1

3. Generation 追踪 – 重启恢复

generation 计数器解决了一个微妙的问题: 如果系统在任务进行中重启, 那些任务可能完成并尝试用过期状态泵送队列. 通过递增 generation, 所有旧回调变成无害的空操作:

1
2
3
4
5
6
7


def _task_done(self, gen):
 with self._condition:
 self._active_count -= 1
 if gen == self._generation:
 self._pump() # current generation: normal flow
 # else: stale task -- do NOT pump, let it die quietly
 self._condition.notify_all()

4. HeartbeatRunner – lane 感知的跳过

不再使用 lock.acquire(blocking=False), 心跳改为检查 lane 统计信息:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


def heartbeat_tick(self):
 ok, reason = self.should_run()
 if not ok:
 return

 lane_stats = self.command_queue.get_or_create_lane(LANE_HEARTBEAT).stats()
 if lane_stats["active"] > 0:
 return # lane is busy, skip this tick

 future = self.command_queue.enqueue(LANE_HEARTBEAT, _do_heartbeat)
 future.add_done_callback(_on_done)

这在功能上等同于非阻塞锁模式, 但以 lane 抽象来表达.

试一试

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


python zh/s10_concurrency.py

# 显示所有 lane 及其当前状态
# You > /lanes
# main active=[.] queued=0 max=1 gen=0
# cron active=[.] queued=0 max=1 gen=0
# heartbeat active=[.] queued=0 max=1 gen=0

# 手动将工作入队到命名 lane
# You > /enqueue main What is the capital of France?

# 创建自定义 lane 并入队工作
# You > /enqueue research Summarize recent AI developments

# 修改 lane 的 max_concurrency
# You > /concurrency research 3

# 显示 generation 计数器
# You > /generation

# 模拟重启 (递增所有 generation)
# You > /reset

# 显示每个 lane 的待处理条目
# You > /queue

OpenClaw 中的对应实现

方面	claw0 (本文件)	OpenClaw 生产代码
Lane 原语	`LaneQueue` + `threading.Condition`	相同模式, 带指标采集
调度器	`CommandQueue` lane 字典	相同的惰性创建调度器
并发控制	每 lane `max_concurrency`, 默认 1	相同, 可按部署配置
任务执行	每任务一个 `threading.Thread`	线程池 + 有界 worker
结果投递	`concurrent.futures.Future`	相同的基于 Future 的接口
Generation 追踪	整数计数器, 过期任务跳过泵送	相同的 generation 模式用于重启安全
空闲检测	`wait_for_idle()` + Condition.wait()	相同, 用于优雅关停
标准 lane	main, cron, heartbeat	相同默认值 + 插件定义的自定义 lane
用户优先	Main lane 阻塞等待结果	相同的阻塞语义用于用户输入

Python代码实现

合并后的 claw0

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297


"""
claw0 Full Integration - All-in-One Agent Gateway

This script combines all 10 sessions into a complete agent gateway:
- s01: Agent Loop (while + stop_reason)
- s02: Tool Use (dispatch table)
- s03: Sessions (JSONL persistence, context guard)
- s04: Channels (InboundMessage abstraction)
- s05: Gateway & Routing (5-tier binding)
- s06: Intelligence (soul, memory, skills, prompt assembly)
- s07: Heartbeat & Cron (proactive agent)
- s08: Delivery (message queue with backoff)
- s09: Resilience (retry, auth rotation)
- s10: Concurrency (named lanes)

Usage:
 cd claw0
 python sessions/en/claw0_full.py

Required .env config:
 ANTHROPIC_API_KEY=sk-ant-xxxxx
 MODEL_ID=claude-sonnet-4-20250514
"""

# ============================================================================
# Imports
# ============================================================================
import asyncio
import json
import math
import os
import queue
import re
import subprocess
import sys
import threading
import time
import uuid
from abc import ABC, abstractmethod
from concurrent.futures import Future
from dataclasses import dataclass, field
from datetime import datetime, timezone
from pathlib import Path
from typing import Any
from croniter import croniter

from dotenv import load_dotenv
from anthropic import Anthropic

# ============================================================================
# Configuration
# ============================================================================
load_dotenv(Path(__file__).resolve().parent.parent.parent / ".env", override=True)

MODEL_ID = os.getenv("MODEL_ID", "claude-sonnet-4-20250514")
client = Anthropic(
 api_key=os.getenv("ANTHROPIC_API_KEY"),
 base_url=os.getenv("ANTHROPIC_BASE_URL") or None,
)

WORKSPACE_DIR = Path(__file__).resolve().parent.parent.parent / "workspace"
SESSIONS_DIR = WORKSPACE_DIR / ".sessions"
AGENTS_DIR = WORKSPACE_DIR / ".agents"
STATE_DIR = WORKSPACE_DIR / ".state"
MEMORY_DIR = WORKSPACE_DIR / "memory"
DELIVERY_DIR = WORKSPACE_DIR / "delivery-queue"

WORKSPACE_DIR.mkdir(parents=True, exist_ok=True)
SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
AGENTS_DIR.mkdir(parents=True, exist_ok=True)
STATE_DIR.mkdir(parents=True, exist_ok=True)
MEMORY_DIR.mkdir(parents=True, exist_ok=True)
DELIVERY_DIR.mkdir(parents=True, exist_ok=True)

CONTEXT_SAFE_LIMIT = 180000
MAX_TOOL_OUTPUT = 50000

BOOTSTRAP_FILES = [
 "SOUL.md", "IDENTITY.md", "TOOLS.md", "USER.md",
 "HEARTBEAT.md", "BOOTSTRAP.md", "AGENTS.md", "MEMORY.md",
]

VALID_ID_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
INVALID_CHARS_RE = re.compile(r"[^a-z0-9_-]+")
DEFAULT_AGENT_ID = "main"

# ============================================================================
# ANSI Colors
# ============================================================================
CYAN = "\033[36m"
GREEN = "\033[32m"
YELLOW = "\033[33m"
RED = "\033[31m"
DIM = "\033[2m"
RESET = "\033[0m"
BOLD = "\033[1m"
MAGENTA = "\033[35m"
BLUE = "\033[34m"


def colored_prompt() -> str:
 return f"{CYAN}{BOLD}You > {RESET}"


def print_assistant(text: str) -> None:
 print(f"\n{GREEN}{BOLD}Assistant:{RESET} {text}\n")


def print_tool(name: str, detail: str) -> None:
 print(f" {DIM}[tool: {name}] {detail}{RESET}")


def print_info(text: str) -> None:
 print(f"{DIM}{text}{RESET}")


def print_warn(text: str) -> None:
 print(f"{YELLOW}{text}{RESET}")


def print_session(text: str) -> None:
 print(f"{MAGENTA}{text}{RESET}")


def print_channel(text: str) -> None:
 print(f"{BLUE}{text}{RESET}")


def print_lane(text: str) -> None:
 print(f"{CYAN}{text}{RESET}")


# ============================================================================
# Data Structures
# ============================================================================

@dataclass
class InboundMessage:
 """All channels normalize into this."""
 text: str
 sender_id: str
 channel: str = "cli"
 account_id: str = ""
 peer_id: str = ""
 is_group: bool = False
 media: list = field(default_factory=list)
 raw: dict = field(default_factory=dict)


@dataclass
class DeliveryMessage:
 """Message in the delivery queue."""
 id: str = ""
 agent_id: str = ""
 session_key: str = ""
 role: str = "user"
 content: Any = ""
 channel: str = "cli"
 created_at: float = field(default_factory=time.time)
 attempts: int = 0
 last_error: str = ""


# ============================================================================
# Agent ID Normalization
# ============================================================================

def normalize_agent_id(value: str) -> str:
 trimmed = value.strip()
 if not trimmed:
 return DEFAULT_AGENT_ID
 if VALID_ID_RE.match(trimmed):
 return trimmed.lower()
 cleaned = INVALID_CHARS_RE.sub("-", trimmed.lower()).strip("-")[:64]
 return cleaned or DEFAULT_AGENT_ID


# ============================================================================
# Safe Path Helper
# ============================================================================

def safe_path(raw: str, base: Path = WORKSPACE_DIR) -> Path:
 target = (base / raw).resolve()
 if not str(target).startswith(str(base.resolve())):
 raise ValueError(f"Path traversal blocked: {raw}")
 return target


def truncate(text: str, limit: int = MAX_TOOL_OUTPUT) -> str:
 if len(text) <= limit:
 return text
 return text[:limit] + f"\n... [truncated, {len(text)} total chars]"


# ============================================================================
# Tool Implementations
# ============================================================================

def tool_bash(command: str, timeout: int = 30) -> str:
 """Run a shell command."""
 dangerous = ["rm -rf /", "mkfs", "> /dev/sd", "dd if="]
 for pattern in dangerous:
 if pattern in command:
 return f"Error: Refused to run dangerous command"
 print_tool("bash", command)
 try:
 result = subprocess.run(
 command, shell=True, capture_output=True, text=True,
 timeout=timeout, cwd=str(WORKSPACE_DIR),
 )
 output = ""
 if result.stdout:
 output += result.stdout
 if result.stderr:
 output += ("\n--- stderr ---\n" + result.stderr) if output else result.stderr
 if result.returncode != 0:
 output += f"\n[exit code: {result.returncode}]"
 return truncate(output) if output else "[no output]"
 except subprocess.TimeoutExpired:
 return f"Error: Command timed out after {timeout}s"
 except Exception as exc:
 return f"Error: {exc}"


def tool_read_file(file_path: str) -> str:
 """Read file contents."""
 print_tool("read_file", file_path)
 try:
 target = safe_path(file_path)
 if not target.exists():
 return f"Error: File not found: {file_path}"
 if not target.is_file():
 return f"Error: Not a file: {file_path}"
 content = target.read_text(encoding="utf-8")
 return truncate(content)
 except ValueError as exc:
 return str(exc)
 except Exception as exc:
 return f"Error: {exc}"


def tool_write_file(file_path: str, content: str) -> str:
 """Write content to a file."""
 print_tool("write_file", file_path)
 try:
 target = safe_path(file_path)
 target.parent.mkdir(parents=True, exist_ok=True)
 target.write_text(content, encoding="utf-8")
 return f"Successfully wrote {len(content)} chars to {file_path}"
 except ValueError as exc:
 return str(exc)
 except Exception as exc:
 return f"Error: {exc}"


def tool_edit_file(file_path: str, old_string: str, new_string: str) -> str:
 """Edit a file with exact string replacement."""
 print_tool("edit_file", f"{file_path} ({len(old_string)} chars)")
 try:
 target = safe_path(file_path)
 if not target.exists():
 return f"Error: File not found: {file_path}"
 content = target.read_text(encoding="utf-8")
 count = content.count(old_string)
 if count == 0:
 return "Error: old_string not found"
 if count > 1:
 return f"Error: old_string found {count} times (must be unique)"
 new_content = content.replace(old_string, new_string, 1)
 target.write_text(new_content, encoding="utf-8")
 return f"Successfully edited {file_path}"
 except ValueError as exc:
 return str(exc)
 except Exception as exc:
 return f"Error: {exc}"


def tool_list_directory(directory: str = ".") -> str:
 """List directory contents."""
 print_tool("list_directory", directory)
 try:
 target = safe_path(directory)
 if not target.exists():
 return f"Error: Directory not found: {directory}"
 if not target.is_dir():
 return f"Error: Not a directory: {directory}"
 entries = sorted(target.iterdir())
 lines = []
 for entry in entries:
 prefix = "[dir] " if entry.is_dir() else "[file] "
 lines.append(prefix + entry.name)
 return "\n".join(lines) if lines else "[empty]"
 except ValueError as exc:
 return str(exc)
 except Exception as exc:
 return f"Error: {exc}"


def tool_get_current_time() -> str:
 """Get current UTC time."""
 print_tool("get_current_time", "")
 return datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")


def tool_memory_write(key: str, value: str) -> str:
 """Write to persistent memory."""
 print_tool("memory_write", f"{key}")
 try:
 mem_file = MEMORY_DIR / f"{key}.json"
 mem_file.write_text(
 json.dumps({"key": key, "value": value, "updated": time.time()}, ensure_ascii=False),
 encoding="utf-8"
 )
 return f"Memory saved: {key}"
 except Exception as exc:
 return f"Error: {exc}"


def tool_memory_read(key: str) -> str:
 """Read from persistent memory."""
 print_tool("memory_read", key)
 try:
 mem_file = MEMORY_DIR / f"{key}.json"
 if not mem_file.exists():
 return f"Memory not found: {key}"
 data = json.loads(mem_file.read_text(encoding="utf-8"))
 return data.get("value", "")
 except Exception as exc:
 return f"Error: {exc}"


def tool_memory_search(query: str) -> str:
 """Search memory for matching entries."""
 print_tool("memory_search", query)
 try:
 results = []
 for mem_file in MEMORY_DIR.glob("*.json"):
 try:
 data = json.loads(mem_file.read_text(encoding="utf-8"))
 if query.lower() in str(data.get("value", "")).lower():
 results.append(f"## {data.get('key')}\n{data.get('value')}")
 except:
 pass
 if not results:
 return "No matching memories found."
 return "\n\n---\n\n".join(results)
 except Exception as exc:
 return f"Error: {exc}"


# ============================================================================
# Tool Schema + Dispatch Table
# ============================================================================

TOOLS = [
 {
 "name": "bash",
 "description": "Run a shell command and return its output.",
 "input_schema": {
 "type": "object",
 "properties": {
 "command": {"type": "string", "description": "Shell command to execute."},
 "timeout": {"type": "integer", "description": "Timeout in seconds. Default 30.", "default": 30},
 },
 "required": ["command"],
 },
 },
 {
 "name": "read_file",
 "description": "Read file contents from workspace.",
 "input_schema": {
 "type": "object",
 "properties": {
 "file_path": {"type": "string", "description": "Path relative to workspace."},
 },
 "required": ["file_path"],
 },
 },
 {
 "name": "write_file",
 "description": "Write content to a file. Creates parent directories.",
 "input_schema": {
 "type": "object",
 "properties": {
 "file_path": {"type": "string", "description": "Path relative to workspace."},
 "content": {"type": "string", "description": "Content to write."},
 },
 "required": ["file_path", "content"],
 },
 },
 {
 "name": "edit_file",
 "description": "Replace exact string in file. old_string must be unique.",
 "input_schema": {
 "type": "object",
 "properties": {
 "file_path": {"type": "string", "description": "Path relative to workspace."},
 "old_string": {"type": "string", "description": "Exact text to find."},
 "new_string": {"type": "string", "description": "Replacement text."},
 },
 "required": ["file_path", "old_string", "new_string"],
 },
 },
 {
 "name": "list_directory",
 "description": "List files and directories.",
 "input_schema": {
 "type": "object",
 "properties": {
 "directory": {"type": "string", "description": "Path relative to workspace.", "default": "."},
 },
 "required": [],
 },
 },
 {
 "name": "get_current_time",
 "description": "Get current UTC date and time.",
 "input_schema": {
 "type": "object",
 "properties": {},
 "required": [],
 },
 },
 {
 "name": "memory_write",
 "description": "Write a persistent memory entry.",
 "input_schema": {
 "type": "object",
 "properties": {
 "key": {"type": "string", "description": "Memory key."},
 "value": {"type": "string", "description": "Memory value."},
 },
 "required": ["key", "value"],
 },
 },
 {
 "name": "memory_read",
 "description": "Read a persistent memory entry.",
 "input_schema": {
 "type": "object",
 "properties": {
 "key": {"type": "string", "description": "Memory key."},
 },
 "required": ["key"],
 },
 },
 {
 "name": "memory_search",
 "description": "Search memory for matching entries.",
 "input_schema": {
 "type": "object",
 "properties": {
 "query": {"type": "string", "description": "Search query."},
 },
 "required": ["query"],
 },
 },
]

TOOL_HANDLERS: dict[str, Any] = {
 "bash": tool_bash,
 "read_file": tool_read_file,
 "write_file": tool_write_file,
 "edit_file": tool_edit_file,
 "list_directory": tool_list_directory,
 "get_current_time": tool_get_current_time,
 "memory_write": tool_memory_write,
 "memory_read": tool_memory_read,
 "memory_search": tool_memory_search,
}


def process_tool_call(tool_name: str, tool_input: dict) -> str:
 handler = TOOL_HANDLERS.get(tool_name)
 if handler is None:
 return f"Error: Unknown tool '{tool_name}'"
 try:
 return handler(**tool_input)
 except TypeError as exc:
 return f"Error: Invalid arguments: {exc}"
 except Exception as exc:
 return f"Error: {tool_name} failed: {exc}"


# ============================================================================
# SessionStore (s03) - JSONL Persistence
# ============================================================================

class SessionStore:
 """Manages persistent JSONL-based conversation storage."""

 def __init__(self, agent_id: str = "default"):
 self.agent_id = agent_id
 self.base_dir = SESSIONS_DIR / "agents" / agent_id / "sessions"
 self.base_dir.mkdir(parents=True, exist_ok=True)
 self.index_path = self.base_dir.parent / "sessions.json"
 self._index: dict[str, dict] = self._load_index()
 self.current_session_id: str | None = None

 def _load_index(self) -> dict[str, dict]:
 if self.index_path.exists():
 try:
 return json.loads(self.index_path.read_text(encoding="utf-8"))
 except (json.JSONDecodeError, OSError):
 return {}
 return {}

 def _save_index(self) -> None:
 self.index_path.write_text(
 json.dumps(self._index, indent=2, ensure_ascii=False),
 encoding="utf-8",
 )

 def _session_path(self, session_id: str) -> Path:
 return self.base_dir / f"{session_id}.jsonl"

 def create_session(self, label: str = "") -> str:
 session_id = uuid.uuid4().hex[:12]
 now = datetime.now(timezone.utc).isoformat()
 self._index[session_id] = {
 "label": label, "created_at": now,
 "last_active": now, "message_count": 0,
 }
 self._save_index()
 self._session_path(session_id).touch()
 self.current_session_id = session_id
 return session_id

 def load_session(self, session_id: str) -> list[dict]:
 path = self._session_path(session_id)
 if not path.exists():
 return []
 self.current_session_id = session_id
 return self._rebuild_history(path)

 def save_turn(self, role: str, content: Any) -> None:
 if not self.current_session_id:
 return
 self.append_transcript(self.current_session_id, {
 "type": role, "content": content, "ts": time.time(),
 })

 def save_tool_result(self, tool_use_id: str, name: str,
 tool_input: dict, result: str) -> None:
 if not self.current_session_id:
 return
 ts = time.time()
 self.append_transcript(self.current_session_id, {
 "type": "tool_use", "tool_use_id": tool_use_id,
 "name": name, "input": tool_input, "ts": ts,
 })
 self.append_transcript(self.current_session_id, {
 "type": "tool_result", "tool_use_id": tool_use_id,
 "content": result, "ts": ts,
 })

 def append_transcript(self, session_id: str, record: dict) -> None:
 path = self._session_path(session_id)
 with open(path, "a", encoding="utf-8") as f:
 f.write(json.dumps(record, ensure_ascii=False) + "\n")
 if session_id in self._index:
 self._index[session_id]["last_active"] = datetime.now(timezone.utc).isoformat()
 self._index[session_id]["message_count"] += 1
 self._save_index()

 def _rebuild_history(self, path: Path) -> list[dict]:
 messages: list[dict] = []
 lines = path.read_text(encoding="utf-8").strip().split("\n")
 for line in lines:
 if not line.strip():
 continue
 try:
 record = json.loads(line)
 except json.JSONDecodeError:
 continue
 rtype = record.get("type")
 if rtype == "user":
 messages.append({"role": "user", "content": record["content"]})
 elif rtype == "assistant":
 content = record["content"]
 if isinstance(content, str):
 content = [{"type": "text", "text": content}]
 messages.append({"role": "assistant", "content": content})
 elif rtype == "tool_use":
 block = {"type": "tool_use", "id": record["tool_use_id"],
 "name": record["name"], "input": record["input"]}
 if messages and messages[-1]["role"] == "assistant":
 content = messages[-1]["content"]
 if isinstance(content, list):
 content.append(block)
 else:
 messages[-1]["content"] = [{"type": "text", "text": str(content)}, block]
 else:
 messages.append({"role": "assistant", "content": [block]})
 elif rtype == "tool_result":
 result_block = {"type": "tool_result", "tool_use_id": record["tool_use_id"],
 "content": record["content"]}
 if (messages and messages[-1]["role"] == "user"
 and isinstance(messages[-1]["content"], list)
 and messages[-1]["content"]
 and isinstance(messages[-1]["content"][0], dict)
 and messages[-1]["content"][0].get("type") == "tool_result"):
 messages[-1]["content"].append(result_block)
 else:
 messages.append({"role": "user", "content": [result_block]})
 return messages

 def list_sessions(self) -> list[tuple[str, dict]]:
 items = list(self._index.items())
 items.sort(key=lambda x: x[1].get("last_active", ""), reverse=True)
 return items


# ============================================================================
# ContextGuard (s03) - Overflow Protection
# ============================================================================

class ContextGuard:
 """Protect from context window overflow with 3-stage retry."""

 def __init__(self, max_tokens: int = CONTEXT_SAFE_LIMIT):
 self.max_tokens = max_tokens

 @staticmethod
 def estimate_tokens(text: str) -> int:
 return len(text) // 4

 def estimate_messages_tokens(self, messages: list[dict]) -> int:
 total = 0
 for msg in messages:
 content = msg.get("content", "")
 if isinstance(content, str):
 total += self.estimate_tokens(content)
 elif isinstance(content, list):
 for block in content:
 if isinstance(block, dict):
 if "text" in block:
 total += self.estimate_tokens(block["text"])
 elif block.get("type") == "tool_result":
 rc = block.get("content", "")
 if isinstance(rc, str):
 total += self.estimate_tokens(rc)
 elif block.get("type") == "tool_use":
 total += self.estimate_tokens(json.dumps(block.get("input", {})))
 elif hasattr(block, "text"):
 total += self.estimate_tokens(block.text)
 return total

 def truncate_tool_result(self, result: str, max_fraction: float = 0.3) -> str:
 max_chars = int(self.max_tokens * 4 * max_fraction)
 if len(result) <= max_chars:
 return result
 return result[:max_chars] + f"\n\n[... truncated ({len(result)} chars total) ...]"

 def _truncate_large_tool_results(self, messages: list[dict]) -> list[dict]:
 result = []
 for msg in messages:
 content = msg.get("content", "")
 if isinstance(content, list):
 new_blocks = []
 for block in content:
 if (isinstance(block, dict) and block.get("type") == "tool_result"
 and isinstance(block.get("content"), str)):
 block = dict(block)
 block["content"] = self.truncate_tool_result(block["content"])
 new_blocks.append(block)
 result.append({"role": msg["role"], "content": new_blocks})
 else:
 result.append(msg)
 return result

 def guard_api_call(
 self, api_client: Anthropic, model: str, system: str,
 messages: list[dict], tools: list[dict] | None = None, max_retries: int = 2,
 ) -> Any:
 current_messages = messages
 for attempt in range(max_retries + 1):
 try:
 kwargs: dict[str, Any] = {
 "model": model, "max_tokens": 8096,
 "system": system, "messages": current_messages,
 }
 if tools:
 kwargs["tools"] = tools
 result = api_client.messages.create(**kwargs)
 if current_messages is not messages:
 messages.clear()
 messages.extend(current_messages)
 return result
 except Exception as exc:
 error_str = str(exc).lower()
 is_overflow = "context" in error_str or "token" in error_str
 if not is_overflow or attempt >= max_retries:
 raise
 if attempt == 0:
 print_warn(" [guard] Truncating tool results...")
 current_messages = self._truncate_large_tool_results(current_messages)
 elif attempt == 1:
 print_warn(" [guard] Compact history...")
 current_messages = self._compact_history(current_messages, api_client, model)
 raise RuntimeError("guard_api_call: exhausted retries")

 def _compact_history(self, messages: list[dict], api_client: Anthropic, model: str) -> list[dict]:
 total = len(messages)
 if total <= 4:
 return messages
 keep_count = max(4, int(total * 0.2))
 compress_count = max(2, int(total * 0.5))
 compress_count = min(compress_count, total - keep_count)
 if compress_count < 2:
 return messages
 old_messages = messages[:compress_count]
 recent_messages = messages[compress_count:]
 parts = []
 for msg in old_messages:
 role = msg["role"]
 content = msg.get("content", "")
 if isinstance(content, str):
 parts.append(f"[{role}]: {content}")
 elif isinstance(content, list):
 for block in content:
 if isinstance(block, dict):
 if block.get("type") == "text":
 parts.append(f"[{role}]: {block['text']}")
 elif block.get("type") == "tool_use":
 parts.append(f"[{role}]: {json.dumps(block.get('input', {}))}")
 old_text = "\n".join(parts)
 try:
 summary_resp = api_client.messages.create(
 model=model, max_tokens=2048,
 system="Summarize conversation concisely.",
 messages=[{"role": "user", "content": f"Summarize:\n{old_text[:10000]}"}],
 )
 summary_text = "".join(b.text for b in summary_resp.content if hasattr(b, "text"))
 print_session(f" [compact] {len(old_messages)} -> summary ({len(summary_text)} chars)")
 except Exception as exc:
 print_warn(f" [compact] Failed: {exc}")
 return recent_messages
 compacted = [
 {"role": "user", "content": "[Previous conversation summary]\n" + summary_text},
 {"role": "assistant", "content": [{"type": "text", "text": "Understood."}]},
 ]
 compacted.extend(recent_messages)
 return compacted


# ============================================================================
# BootstrapLoader (s06) - Prompt Assembly
# ============================================================================

class BootstrapLoader:
 """Loads prompt components from workspace files."""

 def __init__(self, workspace: Path = WORKSPACE_DIR):
 self.workspace = workspace

 def load_file(self, name: str) -> str:
 path = self.workspace / name
 if not path.exists():
 return ""
 try:
 content = path.read_text(encoding="utf-8")
 if len(content) > MAX_TOOL_OUTPUT:
 content = content[:MAX_TOOL_OUTPUT] + "\n... [truncated]"
 return content
 except Exception:
 return ""

 def build_system_prompt(self, agent_id: str = "default") -> str:
 parts = []
 for fname in BOOTSTRAP_FILES:
 content = self.load_file(fname)
 if content:
 header = fname.replace(".md", "").replace("_", " ").title()
 parts.append(f"## {header}\n{content}")
 parts.append("\n## Available Tools\nYou have access to: bash, read_file, write_file, edit_file, list_directory, get_current_time, memory_write, memory_read, memory_search.")
 return "\n\n".join(parts)


# ============================================================================
# DeliveryQueue (s08) - Reliable Message Queue
# ============================================================================

class DeliveryQueue:
 """Write-ahead log message queue with retry."""

 def __init__(self, queue_dir: Path = DELIVERY_DIR):
 self.queue_dir = queue_dir
 self.queue_dir.mkdir(parents=True, exist_ok=True)
 self.pending: dict[str, DeliveryMessage] = {}
 self._load_pending()

 def _load_pending(self) -> None:
 for f in self.queue_dir.glob("*.json"):
 try:
 data = json.loads(f.read_text(encoding="utf-8"))
 msg = DeliveryMessage(**data)
 self.pending[msg.id] = msg
 except Exception:
 pass

 def enqueue(self, msg: DeliveryMessage) -> None:
 if not msg.id:
 msg.id = uuid.uuid4().hex[:12]
 path = self.queue_dir / f"{msg.id}.json"
 path.write_text(json.dumps({
 "id": msg.id, "agent_id": msg.agent_id, "session_key": msg.session_key,
 "role": msg.role, "content": msg.content, "channel": msg.channel,
 "created_at": msg.created_at, "attempts": msg.attempts, "last_error": msg.last_error,
 }, ensure_ascii=False), encoding="utf-8")
 self.pending[msg.id] = msg

 def dequeue(self, msg_id: str) -> DeliveryMessage | None:
 path = self.queue_dir / f"{msg_id}.json"
 if path.exists():
 try:
 path.unlink()
 except Exception:
 pass
 return self.pending.pop(msg_id, None)

 def retry_failed(self, max_attempts: int = 3) -> list[DeliveryMessage]:
 result = []
 for msg in list(self.pending.values()):
 if msg.attempts >= max_attempts:
 self.dequeue(msg.id)
 elif time.time() - msg.created_at > 300:
 msg.attempts += 1
 result.append(msg)
 self.enqueue(msg)
 return result


# ============================================================================
# NamedLanes (s10) - Concurrency Control
# ============================================================================

class NamedLanes:
 """Named lanes serialize messages per agent/session."""

 def __init__(self):
 self.lanes: dict[str, asyncio.Queue] = {}
 self.locks: dict[str, asyncio.Lock] = {}
 self.results: dict[str, Future] = {}

 def get_lane(self, name: str) -> str:
 return f"lane:{name}"

 def enqueue(self, lane_name: str, item: Any) -> None:
 if lane_name not in self.lanes:
 self.lanes[lane_name] = queue.Queue()
 self.lanes[lane_name].put(item)

 def dequeue(self, lane_name: str) -> Any | None:
 if lane_name not in self.lanes:
 return None
 try:
 return self.lanes[lane_name].get_nowait()
 except queue.Empty:
 return None


# ============================================================================
# Binding (s05) - 5-Tier Routing
# ============================================================================

@dataclass
class Binding:
 channel: str = ""
 account_id: str = ""
 peer_id: str = ""
 guild_id: str = ""
 agent_id: str = "main"
 session_label: str = ""


class BindingTable:
 """5-tier routing: peer > guild > account > channel > default."""

 def __init__(self):
 self.bindings: list[Binding] = []

 def add(self, binding: Binding) -> None:
 self.bindings.append(binding)

 def resolve(self, channel: str, account_id: str = "",
 peer_id: str = "", guild_id: str = "") -> tuple[str, str]:
 matches = []
 for b in self.bindings:
 score = 0
 if b.peer_id and b.peer_id == peer_id:
 score = 50
 elif b.guild_id and b.guild_id == guild_id:
 score = 40
 elif b.account_id and b.account_id == account_id:
 score = 30
 elif b.channel and b.channel == channel:
 score = 20
 elif not b.peer_id and not b.guild_id and not b.account_id and not b.channel:
 score = 10
 else:
 continue
 if score > 0:
 matches.append((score, b))
 if not matches:
 return DEFAULT_AGENT_ID, "default"
 matches.sort(key=lambda x: x[0], reverse=True)
 return matches[0][1].agent_id, matches[0][1].session_label or "default"


# ============================================================================
# Heartbeat & Cron (s07)
# ============================================================================

class Heartbeat:
 """Proactive agent with cron scheduling."""

 def __init__(self, agent_id: str, system_prompt: str,
 session_store: SessionStore, context_guard: ContextGuard):
 self.agent_id = agent_id
 self.system_prompt = system_prompt
 self.session_store = session_store
 self.context_guard = context_guard
 self.running = False
 self.thread: threading.Thread | None = None
 self.crons: list[tuple[str, str]] = []
 self.last_runs: dict[str, float] = {}

 def add_cron(self, cron_expr: str, action: str) -> None:
 self.crons.append((cron_expr, action))

 def start(self) -> None:
 self.running = True
 self.thread = threading.Thread(target=self._run, daemon=True)
 self.thread.start()
 print_info(f" [heartbeat] Started for agent {self.agent_id}")

 def stop(self) -> None:
 self.running = False
 if self.thread:
 self.thread.join(timeout=2)
 print_info(f" [heartbeat] Stopped for agent {self.agent_id}")

 def _run(self) -> None:
 while self.running:
 now = datetime.now(timezone.utc)
 for cron_expr, action in self.crons:
 try:
 cron = croniter(cron_expr, now)
 if cron.is_now() or (self.last_runs.get(action, 0) < cron.get_prev()):
 self.last_runs[time.time()] = time.time()
 self._execute_action(action)
 except Exception:
 pass
 time.sleep(10)

 def _execute_action(self, action: str) -> None:
 print_lane(f" [heartbeat] Executing: {action}")
 # In full version, would trigger agent action here


# ============================================================================
# Agent Manager
# ============================================================================

class AgentManager:
 """Manages multiple agents with routing."""

 def __init__(self):
 self.agents: dict[str, dict] = {}
 self.session_stores: dict[str, SessionStore] = {}
 self.context_guards: dict[str, ContextGuard] = {}
 self.heartbeats: dict[str, Heartbeat] = {}
 self.binding_table = BindingTable()
 self.bootstrap_loader = BootstrapLoader()
 self.delivery_queue = DeliveryQueue()
 self.named_lanes = NamedLanes()
 self._setup_default_agent()

 def _setup_default_agent(self) -> None:
 agent_id = DEFAULT_AGENT_ID
 self.agents[agent_id] = {
 "id": agent_id,
 "name": "default",
 "system_prompt": self.bootstrap_loader.build_system_prompt(agent_id),
 }
 self.session_stores[agent_id] = SessionStore(agent_id)
 self.context_guards[agent_id] = ContextGuard()
 self.binding_table.add(Binding(channel="", agent_id=agent_id))

 def get_agent_id(self, channel: str, account_id: str = "",
 peer_id: str = "", guild_id: str = "") -> str:
 return self.binding_table.resolve(channel, account_id, peer_id, guild_id)[0]

 def get_or_create_agent(self, agent_id: str) -> dict:
 if agent_id not in self.agents:
 agent_id = normalize_agent_id(agent_id)
 self.agents[agent_id] = {
 "id": agent_id,
 "name": agent_id,
 "system_prompt": self.bootstrap_loader.build_system_prompt(agent_id),
 }
 self.session_stores[agent_id] = SessionStore(agent_id)
 self.context_guards[agent_id] = ContextGuard()
 self.binding_table.add(Binding(agent_id=agent_id))
 return self.agents[agent_id]

 def create_agent(self, agent_id: str, name: str = "",
 soul: str = "", identity: str = "") -> None:
 agent_id = normalize_agent_id(agent_id)
 system_parts = []
 if soul:
 system_parts.append(f"## Soul\n{soul}")
 if identity:
 system_parts.append(f"## Identity\n{identity}")
 system_parts.append(self.bootstrap_loader.build_system_prompt(agent_id))
 self.agents[agent_id] = {
 "id": agent_id,
 "name": name or agent_id,
 "system_prompt": "\n\n".join(system_parts),
 }
 self.session_stores[agent_id] = SessionStore(agent_id)
 self.context_guards[agent_id] = ContextGuard()
 self.binding_table.add(Binding(agent_id=agent_id))
 print_info(f" Created agent: {agent_id}")


# ============================================================================
# REPL Commands
# ============================================================================

def handle_repl_command(
 command: str, agent_manager: AgentManager,
 agent_id: str, messages: list[dict],
) -> tuple[bool, list[dict], str]:
 """Handle /-prefixed commands."""
 parts = command.strip().split(maxsplit=2)
 cmd = parts[0].lower()
 arg1 = parts[1] if len(parts) > 1 else ""
 arg2 = parts[2] if len(parts) > 2 else ""

 store = agent_manager.session_stores[agent_id]
 guard = agent_manager.context_guards[agent_id]

 if cmd == "/new":
 label = arg1 or ""
 sid = store.create_session(label)
 print_session(f" Created session: {sid}" + (f" ({label})" if label else ""))
 return True, [], agent_id

 elif cmd == "/list":
 sessions = store.list_sessions()
 if not sessions:
 print_info(" No sessions.")
 else:
 print_info(" Sessions:")
 for sid, meta in sessions:
 active = " <-- current" if sid == store.current_session_id else ""
 count = meta.get("message_count", 0)
 print_info(f" {sid} msgs={count}{active}")
 return True, messages, agent_id

 elif cmd == "/switch":
 if not arg1:
 print_warn(" Usage: /switch <session_id>")
 return True, messages, agent_id
 matched = [sid for sid in store._index if sid.startswith(arg1)]
 if len(matched) == 0:
 print_warn(f" Not found: {arg1}")
 return True, messages, agent_id
 if len(matched) > 1:
 print_warn(f" Ambiguous: {', '.join(matched)}")
 return True, messages, agent_id
 new_messages = store.load_session(matched[0])
 print_session(f" Switched to: {matched[0]} ({len(new_messages)} messages)")
 return True, new_messages, agent_id

 elif cmd == "/agents":
 print_info(" Agents:")
 for aid, agent in agent_manager.agents.items():
 print_info(f" {aid}: {agent.get('name', aid)}")
 return True, messages, agent_id

 elif cmd == "/create":
 if not arg1:
 print_warn(" Usage: /create <agent_id> [name]")
 return True, messages, agent_id
 agent_manager.create_agent(arg1, arg2)
 return True, messages, arg1

 elif cmd == "/use":
 if not arg1:
 print_warn(" Usage: /use <agent_id>")
 return True, messages, agent_id
 if arg1 not in agent_manager.agents:
 print_warn(f" Unknown agent: {arg1}")
 return True, messages, agent_id
 print_info(f" Switched to agent: {arg1}")
 store = agent_manager.session_stores[arg1]
 sessions = store.list_sessions()
 if sessions:
 new_messages = store.load_session(sessions[0][0])
 else:
 store.create_session("default")
 new_messages = []
 return True, new_messages, arg1

 elif cmd == "/prompt":
 agent = agent_manager.agents[agent_id]
 print_info(f" System prompt ({len(agent['system_prompt'])} chars):")
 print(agent["system_prompt"][:500] + "..." if len(agent["system_prompt"]) > 500
 else agent["system_prompt"])
 return True, messages, agent_id

 elif cmd == "/reload":
 agent_manager.agents[agent_id]["system_prompt"] = (
 agent_manager.bootstrap_loader.build_system_prompt(agent_id)
 )
 print_info(" Reloaded system prompt from workspace files.")
 return True, messages, agent_id

 elif cmd == "/context":
 estimated = guard.estimate_messages_tokens(messages)
 pct = (estimated / guard.max_tokens) * 100
 bar_len = 30
 filled = int(bar_len * min(pct, 100) / 100)
 bar = "#" * filled + "-" * (bar_len - filled)
 color = GREEN if pct < 50 else (YELLOW if pct < 80 else RED)
 print_info(f" Context: ~{estimated:,} / {guard.max_tokens:,} tokens ({pct:.1f}%)")
 print(f" {color}[{bar}]{RESET}")
 return True, messages, agent_id

 elif cmd == "/queue":
 pending = agent_manager.delivery_queue.pending
 print_info(f" Pending messages: {len(pending)}")
 for msg_id, msg in list(pending.items())[:5]:
 print_info(f" {msg_id}: {msg.role} - {msg.attempts} attempts")
 return True, messages, agent_id

 elif cmd == "/help":
 print_info(" Commands:")
 print_info(" /new [label] New session")
 print_info(" /list List sessions")
 print_info(" /switch <id> Switch session")
 print_info(" /agents List agents")
 print_info(" /create <id> [n] Create agent")
 print_info(" /use <agent_id> Switch agent")
 print_info(" /prompt Show system prompt")
 print_info(" /reload Reload prompt from files")
 print_info(" /context Show context usage")
 print_info(" /queue Show delivery queue")
 print_info(" /help This help")
 print_info(" quit/exit Exit")
 return True, messages, agent_id

 return False, messages, agent_id


# ============================================================================
# Core: Agent Loop
# ============================================================================

def agent_loop() -> None:
 """Main agent loop with all features integrated."""

 agent_manager = AgentManager()
 agent_id = DEFAULT_AGENT_ID

 store = agent_manager.session_stores[agent_id]
 guard = agent_manager.context_guards[agent_id]

 # Resume or create session
 sessions = store.list_sessions()
 if sessions:
 sid = sessions[0][0]
 messages = store.load_session(sid)
 print_session(f" Resumed session: {sid}")
 else:
 sid = store.create_session("default")
 messages = []
 print_session(f" Created session: {sid}")

 print_info("=" * 60)
 print_info(" claw0 | Full Integration")
 print_info(f" Model: {MODEL_ID}")
 print_info(f" Agent: {agent_id}")
 print_info(f" Session: {store.current_session_id}")
 print_info(f" Tools: {', '.join(TOOL_HANDLERS.keys())}")
 print_info(" Type /help for commands, quit/exit to leave.")
 print_info("=" * 60)
 print()

 while True:
 try:
 user_input = input(colored_prompt()).strip()
 except (KeyboardInterrupt, EOFError):
 print(f"\n{DIM}Goodbye.{RESET}")
 break

 if not user_input:
 continue

 if user_input.lower() in ("quit", "exit"):
 print(f"{DIM}Goodbye.{RESET}")
 break

 # REPL commands
 if user_input.startswith("/"):
 handled, messages, agent_id = handle_repl_command(
 user_input, agent_manager, agent_id, messages
 )
 if handled:
 store = agent_manager.session_stores.get(agent_id, store)
 guard = agent_manager.context_guards.get(agent_id, guard)
 continue

 # Get agent config
 agent = agent_manager.agents[agent_id]
 system_prompt = agent["system_prompt"]

 # Append user message
 messages.append({"role": "user", "content": user_input})
 store.save_turn("user", user_input)

 # Tool call loop
 while True:
 try:
 response = guard.guard_api_call(
 api_client=client,
 model=MODEL_ID,
 system=system_prompt,
 messages=messages,
 tools=TOOLS,
 )
 except Exception as exc:
 print(f"\n{YELLOW}API Error: {exc}{RESET}\n")
 while messages and messages[-1]["role"] != "user":
 messages.pop()
 if messages:
 messages.pop()
 break

 # Save assistant response
 serialized_content = []
 for block in response.content:
 if hasattr(block, "text"):
 serialized_content.append({"type": "text", "text": block.text})
 elif block.type == "tool_use":
 serialized_content.append({
 "type": "tool_use", "id": block.id,
 "name": block.name, "input": block.input,
 })
 store.save_turn("assistant", serialized_content)

 if response.stop_reason == "end_turn":
 assistant_text = "".join(
 b.text for b in response.content if hasattr(b, "text")
 )
 if assistant_text:
 print_assistant(assistant_text)
 break

 elif response.stop_reason == "tool_use":
 tool_results = []
 for block in response.content:
 if block.type != "tool_use":
 continue
 result = process_tool_call(block.name, block.input)
 store.save_tool_result(block.id, block.name, block.input, result)
 tool_results.append({
 "type": "tool_result",
 "tool_use_id": block.id,
 "content": result,
 })
 messages.append({"role": "user", "content": tool_results})
 continue

 else:
 print_info(f"[stop_reason={response.stop_reason}]")
 break


# ============================================================================
# Entry Point
# ============================================================================

def main() -> None:
 if not os.getenv("ANTHROPIC_API_KEY"):
 print(f"{YELLOW}Error: ANTHROPIC_API_KEY not set.{RESET}")
 print(f"{DIM}Copy .env.example to .env and fill in your key.{RESET}")
 sys.exit(1)

 agent_loop()


if __name__ == "__main__":
 main()

新型信息源

Sat, 07 Mar 2026 12:34:25 -0800

新型信息源

前言

以后可以做定制化一个！

NewsNow - 一个开源的实时热门新闻程序

概述

NewsNow 是一个开源的实时热门新闻聚合程序，旨在为用户提供一个简洁的界面和流畅的阅读体验，以便随时掌握最新的全球资讯。该程序支持多种部署方式，包括 Cloudflare Pages、Vercel 以及 Docker，同时提供了灵活的配置和数据库支持。

功能特点

实时新闻更新：NewsNow 提供实时更新的热门新闻，让用户能够及时了解全球动态。
优雅界面：用户界面简洁优雅，提升阅读体验。
灵活部署：支持 Cloudflare Pages、Vercel 以及 Docker 等多种部署方式。
自定义配置：用户可以根据需要配置环境变量和数据库，以定制新闻阅读体验。
数据库支持：支持多种数据库，包括 Cloudflare D1 数据库。
开源项目：基于 MIT 许可证，用户可以自由使用和修改。

使用总结

NewsNow 的主要优势在于其简洁的界面设计和实时新闻更新能力。作为一个开源项目，它允许用户根据自己的需求进行定制和部署。以下是一些关键点：

部署简便：如果不需要登录和缓存功能，可以直接将 NewsNow 部署到 Cloudflare Pages 或 Vercel，只需 Fork 项目后在对应平台上导入即可。
登录功能：登录功能涉及到 GitHub OAuth。创建 GitHub App 后，将获得 Client ID 和 Client Secret，不同平台的环境变量设置位置不同，请参考 example.env.server 文件。
数据库部署：推荐使用 Cloudflare Pages 和 Docker 部署。对于 Vercel，需要自行解决数据库问题。支持的数据库可以在 db0 connectors 查看。
开源社区：NewsNow Labs 是 NewsNow 的研发部门，进行自然语言处理、机器学习、基础设施管理和软件开发工具等方面的前沿研究，并公开其研究成果。

项目地址

项目地址：https://github.com/ourongxing/newsnow
在线地址：https://newsnow.busiyi.world

代码解读

zhihu.ts 获取知乎热榜

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55



interface Res {
 data: {
 type: "hot_list_feed"
 style_type: "1"
 feed_specific: {
 answer_count: 411
 }
 target: {
 title_area: {
 text: string
 }
 excerpt_area: {
 text: string
 }
 image_area: {
 url: string
 }
 metrics_area: {
 text: string
 font_color: string
 background: string
 weight: string
 }
 label_area: {
 type: "trend"
 trend: number
 night_color: string
 normal_color: string
 }
 link: {
 url: string
 }
 }
 }[]
}

export default defineSource({
 zhihu: async () => {
 const url = "https://www.zhihu.com/api/v3/feed/topstory/hot-list-web?limit=20&desktop=true"
 const res: Res = await myFetch(url)
 return res.data
 .map((k) => {
 return {
 id: k.target.link.url.match(/(\d+)$/)?.[1] ?? k.target.link.url,
 title: k.target.title_area.text,
 extra: {
 info: k.target.metrics_area.text,
 hover: k.target.excerpt_area.text,
 },
 url: k.target.link.url,
 }
 })
 },
})

github.ts

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35



import * as cheerio from "cheerio"
import type { NewsItem } from "@shared/types"

const trending = defineSource(async () => {
 const baseURL = "https://github.com"
 const html: any = await myFetch("https://github.com/trending?spoken_language_code=")
 const $ = cheerio.load(html)
 const $main = $("main .Box div[data-hpc] > article")
 const news: NewsItem[] = []
 $main.each((_, el) => {
 const a = $(el).find(">h2 a")
 const title = a.text().replace(/\n+/g, "").trim()
 const url = a.attr("href")
 const star = $(el).find("[href$=stargazers]").text().replace(/\s+/g, "").trim()
 const desc = $(el).find(">p").text().replace(/\n+/g, "").trim()
 if (url && title) {
 news.push({
 url: `${baseURL}${url}`,
 title,
 id: url,
 extra: {
 info: `✰ ${star}`,
 hover: desc,
 },
 })
 }
 })
 return news
})

export default defineSource({
 "github": trending,
 "github-trending-today": trending,
})

hackernews.ts

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


import * as cheerio from "cheerio"
import type { NewsItem } from "@shared/types"

export default defineSource(async () => {
 const baseURL = "https://news.ycombinator.com"
 const html: any = await myFetch(baseURL)
 const $ = cheerio.load(html)
 const $main = $(".athing")
 const news: NewsItem[] = []
 $main.each((_, el) => {
 const a = $(el).find(".titleline a").first()
 // const url = a.attr("href")
 const title = a.text()
 const id = $(el).attr("id")
 const score = $(`#score_${id}`).text()
 const url = `${baseURL}/item?id=${id}`
 if (url && id && title) {
 news.push({
 url,
 title,
 id,
 extra: {
 info: score,
 },
 })
 }
 })
 return news
})

wallstreetcn.ts

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87


interface Item {
 uri: string
 id: number
 title?: string
 content_text: string
 content_short: string
 display_time: number
 type?: string
}
interface LiveRes {
 data: {
 items: Item[]
 }
}

interface NewsRes {
 data: {
 items: {
 // ad
 resource_type?: string
 resource: Item
 }[]
 }
}

interface HotRes {
 data: {
 day_items: Item[]
 }
}

// https://github.com/DIYgod/RSSHub/blob/master/lib/routes/wallstreetcn/live.ts
const live = defineSource(async () => {
 const apiUrl = `https://api-one.wallstcn.com/apiv1/content/lives?channel=global-channel&limit=30`

 const res: LiveRes = await myFetch(apiUrl)
 return res.data.items
 .map((k) => {
 return {
 id: k.id,
 title: k.title || k.content_text,
 extra: {
 date: k.display_time * 1000,
 },
 url: k.uri,
 }
 })
})

const news = defineSource(async () => {
 const apiUrl = `https://api-one.wallstcn.com/apiv1/content/information-flow?channel=global-channel&accept=article&limit=30`

 const res: NewsRes = await myFetch(apiUrl)
 return res.data.items
 .filter(k => k.resource_type !== "theme" && k.resource_type !== "ad" && k.resource.type !== "live" && k.resource.uri)
 .map(({ resource: h }) => {
 return {
 id: h.id,
 title: h.title || h.content_short,
 extra: {
 date: h.display_time * 1000,
 },
 url: h.uri,
 }
 })
})

const hot = defineSource(async () => {
 const apiUrl = `https://api-one.wallstcn.com/apiv1/content/articles/hot?period=all`

 const res: HotRes = await myFetch(apiUrl)
 return res.data.day_items
 .map((h) => {
 return {
 id: h.id,
 title: h.title!,
 url: h.uri,
 }
 })
})

export default defineSource({
 "wallstreetcn": live,
 "wallstreetcn-quick": live,
 "wallstreetcn-news": news,
 "wallstreetcn-hot": hot,
})

sspai.ts

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


interface Res {
 data: {
 id: number
 title: string
 }[]
}

export default defineSource(async () => {
 const timestamp = Date.now()
 const limit = 30
 const url = `https://sspai.com/api/v1/article/tag/page/get?limit=${limit}&offset=0&created_at=${timestamp}&tag=%E7%83%AD%E9%97%A8%E6%96%87%E7%AB%A0&released=false`
 const res: Res = await myFetch(url)
 return res.data.map((k) => {
 const url = `https://sspai.com/post/${k.id}`
 return {
 id: k.id,
 title: k.title,
 url,
 }
 })
})

AI 舆情监控助手与热点筛选工具——TrendRadar

⭐AI-driven public opinion & trend monitor with multi-platform aggregation, RSS, and smart alerts.🎯 告别信息过载，你的 AI 舆情监控助手与热点筛选工具！聚合多平台热点 + RSS 订阅，支持关键词精准筛选。AI 翻译 + AI 分析简报直推手机，也支持接入 MCP 架构，赋能 AI 自然语言对话分析、情感洞察与趋势预测等。支持 Docker ，数据本地/云端自持。集成微信/飞书/钉钉/Telegram/邮件/ntfy/bark/slack 等渠道智能推送。

sansan0.github.io/TrendRadar/

GitHub-Repo-TrendRadar

✨ 核心功能

全网热点聚合

知乎
抖音
bilibili 热搜
华尔街见闻
贴吧
百度热搜
财联社热门
澎湃新闻
凤凰网
今日头条
微博

默认监控 11 个主流平台，也可自行增加额外的平台。

RSS 订阅源支持（v4.5.0 新增）

支持 RSS/Atom 订阅源抓取，按关键词分组统计（与热榜格式一致）：

统一格式：RSS 与热榜使用相同的关键词匹配和显示格式
简单配置：直接在 config.yaml 中添加 RSS 源
合并推送：热榜和 RSS 合并为一条消息推送

💡 RSS 使用与热榜相同的 frequency_words.txt 进行关键词过滤

可视化配置编辑器

提供基于 Web 的图形化配置界面，无需手动编辑 YAML 文件，通过表单即可完成所有配置项的修改与导出。

👉 在线体验：https://sansan0.github.io/TrendRadar/

智能推送策略

三种推送模式：

模式	适用场景	推送特点
当日汇总 (daily)	企业管理者/普通用户	按时推送当日所有匹配新闻（会包含之前推送过的）
当前榜单 (current)	自媒体人/内容创作者	按时推送当前榜单匹配新闻（持续在榜的每次都出现）
增量监控 (incremental)	投资者/交易员	仅推送新增内容，零重复

💡 快速选择指南：

不想看到重复新闻 → 用 incremental（增量监控）

想看完整榜单趋势 → 用 current（当前榜单）

需要每日汇总报告 → 用 daily（当日汇总）

详细对比和配置教程见配置详解 - 推送模式详解

附加功能（可选）：

功能	说明	默认
调度系统	按周一到周日逐日编排：为每天分配不同时间段、推送模式和 AI 分析策略。内置 5 种预设（always_on / morning_evening / office_hours / night_owl / custom），也可自定义。支持工作日/周末差异化、跨午夜时段、per-period 去重（v6.0.0）	morning_evening
内容顺序配置	通过 `display.region_order` 调整各区域（热榜、新增热点、RSS、独立展示区、AI 分析）的显示顺序；通过 `display.regions` 控制各区域是否显示（v5.2.0）	见配置文件
显示模式切换	`keyword`=按关键词分组，`platform`=按平台分组（v4.6.0 新增）	keyword

💡 详细配置教程见推送内容怎么显示？和什么时候给我推送？

精准内容筛选

设置个人关键词（如：AI、比亚迪、教育政策），只推送相关热点，过滤无关信息

💡 基础配置教程：关键词配置 - 基础语法

💡 高级配置教程：关键词配置 - 高级配置

💡 也可以不做筛选，完整推送所有热点（将 frequency_words.txt 留空）

热点趋势分析

实时追踪新闻热度变化，让你不仅知道"什么在热搜"，更了解"热点如何演变"

时间轴追踪：记录每条新闻从首次出现到最后出现的完整时间跨度
热度变化：统计新闻在不同时间段的排名变化和出现频次
新增检测：实时识别新出现的热点话题，用🆕标记第一时间提醒
持续性分析：区分一次性热点话题和持续发酵的深度新闻
跨平台对比：同一新闻在不同平台的排名表现，看出媒体关注度差异

💡 推送格式说明见消息样式说明

个性化热点算法

不再被各个平台的算法牵着走，TrendRadar 会重新整理全网热搜

💡 三个比例可以调整，详见配置详解 - 热点权重调整

多渠道多账号推送

支持企业微信(+ 微信推送方案)、飞书、钉钉、Telegram、邮件、ntfy、Bark、Slack，消息直达手机和邮箱

💡 详细配置教程见推送到多个群/设备

AI 多语言翻译（v5.2.0 新增）

将推送内容翻译为任意语言，打破语言壁垒，无论是阅读国内热点还是通过 RSS 订阅海外资讯，都能以母语轻松获取

一键翻译：在 config.yaml 中设置 ai_translation.enabled: true 和目标语言即可
多语言支持：支持 English、Korean、Japanese、French 等任意语言
智能批量处理：自动批量翻译，减少 API 调用次数，节省成本
自定义风格：通过 ai_translation_prompt.txt 自定义翻译风格和术语
共享模型配置：与 AI 分析功能共用 ai 配置段的模型设置

1
2
3
4


# config.yaml 快速启用示例
ai_translation:
 enabled: true
 language: "English" # 翻译目标语言

💡 翻译功能与 AI 分析功能共享模型配置，只需配置一次 ai.api_key 即可同时使用两个功能

RSS 源参考：以下是一些 RSS 订阅源合集，可按需选用

awesome-tech-rss - 科技、创业、编程领域博客和媒体
awesome-rss-feeds - 世界各国主流新闻媒体 RSS 合集

⚠️ 部分海外媒体内容可能涉及敏感话题，AI 模型可能拒绝翻译，建议根据实际需求筛选订阅源

灵活存储架构（v4.0.0 重大更新）

多存储后端支持：

远程云存储：GitHub Actions 环境默认，支持 S3 兼容协议（R2/OSS/COS 等），数据存储在云端，不污染仓库
本地 SQLite 数据库：Docker/本地环境默认，数据完全可控
自动后端选择：根据运行环境智能切换存储方式

💡 详细说明见数据保存在哪里？

多端部署

GitHub Actions：定时自动爬取 + 远程云存储（需签到续期）
Docker 部署：支持多架构容器化运行，数据本地存储
本地运行：Windows/Mac/Linux 直接运行

AI 分析推送（v5.0.0 新增）

使用 AI 大模型对推送内容进行深度分析，自动生成热点洞察报告

智能分析：自动分析热点趋势、关键词热度、跨平台关联、潜在影响
多提供商：支持 DeepSeek、OpenAI、Gemini 及 OpenAI 兼容接口
灵活推送：可选仅原始内容、仅 AI 分析、或两者都推送
自定义提示词：通过 config/ai_analysis_prompt.txt 自定义分析角度

💡 详细配置教程见让 AI 帮我分析热点

独立展示区（v5.0.0 新增）

为指定平台提供完整热榜展示，不受关键词过滤影响

完整热榜：指定平台的热榜完整展示，适合想看完整排名的用户
RSS 独立展示：RSS 源内容可完整展示，不受关键词限制
AI 深度分析：可独立开启 AI 对完整热榜的趋势分析，无需在推送中展示
灵活配置：支持配置展示平台、RSS 源、最大条数

💡 详细配置教程见推送内容怎么显示？ - 独立展示区

AI 智能分析（v3.0.0 新增）

基于 MCP (Model Context Protocol) 协议的 AI 对话分析系统，让你用自然语言深度挖掘新闻数据

💡 使用提示：AI 功能需要本地新闻数据支持

项目自带测试数据，可立即体验功能

建议自行部署运行项目，获取更实时的数据

详见 AI 智能分析

网页部署

运行后根目录生成 index.html，即为完整的新闻报告页面。

部署方式：点击 Use this template 创建仓库，可部署到 Cloudflare Pages 或 GitHub Pages 等静态托管平台。

💡 提示：启用 GitHub Pages 可获得在线访问地址，进入仓库 Settings → Pages 即可开启。效果预览

⚠️ 原 GitHub Actions 自动存储功能已下线（该方案曾导致 GitHub 服务器负载过高，影响平台稳定性）。

减少 APP 依赖

从"被算法推荐绑架"变成"主动获取自己想要的信息"

适合人群： 投资者、自媒体人、企业公关、关心时事的普通用户

典型场景： 股市投资监控、品牌舆情追踪、行业动态关注、生活资讯获取

代码分析

crawler/fetcher.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184


# coding=utf-8
"""
数据获取器模块

负责从 NewsNow API 抓取新闻数据，支持：
- 单个平台数据获取
- 批量平台数据爬取
- 自动重试机制
- 代理支持
"""

import json
import random
import time
from typing import Dict, List, Tuple, Optional, Union

import requests


class DataFetcher:
 """数据获取器"""

 # 默认 API 地址
 DEFAULT_API_URL = "https://newsnow.busiyi.world/api/s"

 # 默认请求头
 DEFAULT_HEADERS = {
 "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
 "Accept": "application/json, text/plain, */*",
 "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
 "Connection": "keep-alive",
 "Cache-Control": "no-cache",
 }

 def __init__(
 self,
 proxy_url: Optional[str] = None,
 api_url: Optional[str] = None,
 ):
 """
 初始化数据获取器

 Args:
 proxy_url: 代理服务器 URL（可选）
 api_url: API 基础 URL（可选，默认使用 DEFAULT_API_URL）
 """
 self.proxy_url = proxy_url
 self.api_url = api_url or self.DEFAULT_API_URL

 def fetch_data(
 self,
 id_info: Union[str, Tuple[str, str]],
 max_retries: int = 2,
 min_retry_wait: int = 3,
 max_retry_wait: int = 5,
 ) -> Tuple[Optional[str], str, str]:
 """
 获取指定ID数据，支持重试

 Args:
 id_info: 平台ID 或 (平台ID, 别名) 元组
 max_retries: 最大重试次数
 min_retry_wait: 最小重试等待时间（秒）
 max_retry_wait: 最大重试等待时间（秒）

 Returns:
 (响应文本, 平台ID, 别名) 元组，失败时响应文本为 None
 """
 if isinstance(id_info, tuple):
 id_value, alias = id_info
 else:
 id_value = id_info
 alias = id_value

 url = f"{self.api_url}?id={id_value}&latest"

 proxies = None
 if self.proxy_url:
 proxies = {"http": self.proxy_url, "https": self.proxy_url}

 retries = 0
 while retries <= max_retries:
 try:
 response = requests.get(
 url,
 proxies=proxies,
 headers=self.DEFAULT_HEADERS,
 timeout=10,
 )
 response.raise_for_status()

 data_text = response.text
 data_json = json.loads(data_text)

 status = data_json.get("status", "未知")
 if status not in ["success", "cache"]:
 raise ValueError(f"响应状态异常: {status}")

 status_info = "最新数据" if status == "success" else "缓存数据"
 print(f"获取 {id_value} 成功（{status_info}）")
 return data_text, id_value, alias

 except Exception as e:
 retries += 1
 if retries <= max_retries:
 base_wait = random.uniform(min_retry_wait, max_retry_wait)
 additional_wait = (retries - 1) * random.uniform(1, 2)
 wait_time = base_wait + additional_wait
 print(f"请求 {id_value} 失败: {e}. {wait_time:.2f}秒后重试...")
 time.sleep(wait_time)
 else:
 print(f"请求 {id_value} 失败: {e}")
 return None, id_value, alias

 return None, id_value, alias

 def crawl_websites(
 self,
 ids_list: List[Union[str, Tuple[str, str]]],
 request_interval: int = 100,
 ) -> Tuple[Dict, Dict, List]:
 """
 爬取多个网站数据

 Args:
 ids_list: 平台ID列表，每个元素可以是字符串或 (平台ID, 别名) 元组
 request_interval: 请求间隔（毫秒）

 Returns:
 (结果字典, ID到名称的映射, 失败ID列表) 元组
 """
 results = {}
 id_to_name = {}
 failed_ids = []

 for i, id_info in enumerate(ids_list):
 if isinstance(id_info, tuple):
 id_value, name = id_info
 else:
 id_value = id_info
 name = id_value

 id_to_name[id_value] = name
 response, _, _ = self.fetch_data(id_info)

 if response:
 try:
 data = json.loads(response)
 results[id_value] = {}

 for index, item in enumerate(data.get("items", []), 1):
 title = item.get("title")
 # 跳过无效标题（None、float、空字符串）
 if title is None or isinstance(title, float) or not str(title).strip():
 continue
 title = str(title).strip()
 url = item.get("url", "")
 mobile_url = item.get("mobileUrl", "")

 if title in results[id_value]:
 results[id_value][title]["ranks"].append(index)
 else:
 results[id_value][title] = {
 "ranks": [index],
 "url": url,
 "mobileUrl": mobile_url,
 }
 except json.JSONDecodeError:
 print(f"解析 {id_value} 响应失败")
 failed_ids.append(id_value)
 except Exception as e:
 print(f"处理 {id_value} 数据出错: {e}")
 failed_ids.append(id_value)
 else:
 failed_ids.append(id_value)

 # 请求间隔（除了最后一个）
 if i < len(ids_list) - 1:
 actual_interval = request_interval + random.randint(-10, 20)
 actual_interval = max(50, actual_interval)
 time.sleep(actual_interval / 1000)

 print(f"成功: {list(results.keys())}, 失败: {failed_ids}")
 return results, id_to_name, failed_ids

WorldMonitor:开源的“全球战情室”软件，可追踪伊朗局势

Real-time global intelligence dashboard — AI-powered news aggregation, geopolitical monitoring, and infrastructure tracking in a unified situational awareness interface

worldmonitor.app

https://github.com/koala73/worldmonitor

World Monitor 是一个由独立开发者 koala73（Elie Habib）开发的实时全球情报仪表板。该项目旨在将原本分散在数十个独立工具中的地缘政治、军事、基础设施及金融数据整合至统一的态势感知界面（Single Pane of Glass）。截至 2026 年初，该项目在 GitHub 已获得超过 2.4 万个 Star，被广泛誉为“开源版彭博终端”或“平民版战情室”。

World Monitor：开源的全球情报监测仪表板

核心功能分析

World Monitor 的功能矩阵围绕可视化、实时性、AI 化三个维度展开：

多维数据图层（40+ Data Layers）：
军事与冲突： 实时追踪全球冲突热点、220+ 军事基地、核设施分布及 GPS 干扰区。
基础设施： 覆盖全球海底光缆、油气管道、主要港口及 AI 数据中心。
实时动态： 集成活体军机（ADS-B）、民用舰船（AIS）追踪及 NASA FIRMS 卫星火点监测。
AI 驱动的情报处理：
- 自动简报（World Brief）：调用 LLM（如 GPT-4, Claude 或本地 Ollama）对每日全球要闻进行结构化摘要。
- RAG 语义检索：内置 Headline Memory，支持对历史事件进行语义搜索，而非简单的关键词匹配。
- 不稳定指数（CII）：基于实时信号量化评估不同国家/地区的动荡风险。
交互式 3D 可视化：
- 基于 deck.gl 与 MapLibre GL JS 开发，支持丝滑的 3D 地球旋转与多层数据叠加，提供极佳的视觉感知力。
三大专业变体：
- World： 侧重地缘政治与军事安全。
- Tech： 侧重半导体供应链、AI 基础设施与科技趋势。
- Finance： 侧重全球 92 家交易所动态、央行政策及预测市场（如 Polymarket）。

使用方法指南

轻量化访问（PWA）：通过浏览器访问 https://worldmonitor.app ，可直接将其安装为 PWA 应用。其支持离线地图缓存，适合日常快速查阅。

World Monitor 核心入口：项目地址：https://github.com/koala73/worldmonitor在线体验（强烈建议立刻打开）： https://worldmonitor.app（世界版）， https://tech.worldmonitor.app （科技版）， https://finance.worldmonitor.app （金融版）

桌面端运行（Tauri）：下载适用于 Windows、macOS 或 Linux 的原生客户端。相比 Web 版，桌面端能更好地保护本地隐私，并支持系统级的实时通知推送。

界面实战操作指南

全方位监控：使用鼠标拖拽旋转 3D 地球，点击热点（如冲突区或舰艇图标）查看详细数据。
一键 AI 总结：在底部新闻面板中，点击单条新闻的 “Summarize” 按钮，AI 会快速给出核心解读。
快捷键助力：Cmd+K（或 Ctrl+K）可唤起全局搜索；面板支持自由拖拽和重组，适配超宽屏办公。
多语言支持：设置中可切换为简体/繁体中文，降低阅读障碍。
本地部署与隐私模式（Docker/Source）：
安装Ollama：登录Ollama 官网下载安装Ollama，建议下载一个推理能力较强且显存占用适中的模型（如 Llama 3.2 或 Qwen 2.5）。
World Monitor 端配置：在 World Monitor 中将 AI 引擎从默认的云端（如 OpenAI/Gemini）切换至本地 Ollama。World Monitor 通常通过 HTTP API 与 Ollama 通信。默认地址为：http://localhost:11434，即可实现情报的本地化分析，确保敏感搜索数据不上传至云端。

技术栈

前端: TypeScript + Vite + React
地图渲染: deck.gl (WebGL) + MapLibre GL JS
AI/ML: Groq (Llama 3.1) + OpenRouter + Transformers.js (浏览器端 NER/嵌入)
缓存: Redis (Upstash) + 三层缓存架构（内存 → Redis → 上游）
跨用户 AI 去重: 相同查询共享 LLM 结果，减少 API 调用

部署方式——零配置模式（推荐新手）

无需 API Key，基础功能正常运行。

自建部署

1
2
3
4
5


git clone https://github.com/koala73/worldmonitor.git
cd worldmonitor
pnpm install
pnpm build
pnpm preview --host 0.0.0.0 --port 8888

可选配置 (.env.local)

1
2
3
4
5
6
7


# AI/ML（可选）
VITE_GROQ_API_KEY=your_groq_key
VITE_OPENROUTER_API_KEY=your_openrouter_key

# 缓存（可选）
VITE_UPSTASH_REDIS_URL=your_redis_url
VITE_UPSTASH_REDIS_TOKEN=your_redis_token

优劣分析

优势（Value）：

效率革命： 极大降低了情报搜集的时间成本。原本需要数小时的跨平台监测，现在可在 10 分钟内通过仪表板完成。
门槛降低： 专业的 OSINT 工具以往多为付费或仅供机构使用，World Monitor 实现了专业能力的平民化。
高度可扩展： 作为开源项目，支持用户自定义 RSS 源与 API 接口，具有极强的生命力。

局限性（Limitations）：

移动端适配： 目前主打桌面端体验，屏幕尺寸小于 768px 时交互受限，不适合碎片化移动办公。
数据延迟： 依赖公开数据源（Open Source），部分极端敏感事件可能存在分钟级甚至小时级的滞后。
语言限制： 尽管 UI 支持中文，但部分深层专业图层的数据标签仍以英文为主。

使用建议

建立“早晚报”机制： 建议分析从业者利用其 AI Brief 功能，每天固定生成两份针对特定区域的简报，快速建立背景感知。
信号叠加分析： 当地图上某一区域同时出现“GPS 干扰”、“异常飞行轨迹”与“火点”时，应将其视为高等级预警信号。
结合本地 LLM： 建议使用 Llama 3 或类似参数量的模型进行推理，既能保证分析逻辑的严密性，又能规避在线 API 的额度限制。
资产监控： 投资者可利用 Finance 变体监控关键航运枢纽（如苏伊士运河）的船只密度，作为判断大宗商品走势的辅助指标。

代码解析

telegram-channels.json

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317


{
 "version": 1,
 "updatedAt": "2026-02-23T18:37:10Z",
 "note": "Product-managed curated list. Not user-configurable.",
 "channels": {
 "full": [
 {
 "handle": "VahidOnline",
 "label": "Vahid Online",
 "topic": "politics",
 "tier": 1,
 "enabled": true,
 "region": "iran",
 "maxMessages": 20
 },
 {
 "handle": "abualiexpress",
 "label": "Abu Ali Express",
 "topic": "middleeast",
 "tier": 2,
 "enabled": true,
 "region": "middleeast",
 "maxMessages": 25
 },
 {
 "handle": "AuroraIntel",
 "label": "Aurora Intel",
 "topic": "conflict",
 "tier": 2,
 "enabled": true,
 "region": "global",
 "maxMessages": 20
 },
 {
 "handle": "BNONews",
 "label": "BNO News",
 "topic": "breaking",
 "tier": 2,
 "enabled": true,
 "region": "global",
 "maxMessages": 25
 },
 {
 "handle": "ClashReport",
 "label": "Clash Report",
 "topic": "conflict",
 "tier": 2,
 "enabled": true,
 "region": "global",
 "maxMessages": 30
 },
 {
 "handle": "DeepStateUA",
 "label": "DeepState",
 "topic": "conflict",
 "tier": 2,
 "enabled": true,
 "region": "ukraine",
 "maxMessages": 20
 },
 {
 "handle": "DefenderDome",
 "label": "The Defender Dome",
 "topic": "conflict",
 "tier": 2,
 "enabled": true,
 "region": "global",
 "maxMessages": 25
 },
 {
 "handle": "englishabuali",
 "label": "Abu Ali Express EN",
 "topic": "middleeast",
 "tier": 2,
 "enabled": true,
 "region": "middleeast",
 "maxMessages": 25
 },
 {
 "handle": "iranintltv",
 "label": "Iran International",
 "topic": "politics",
 "tier": 2,
 "enabled": true,
 "region": "iran",
 "maxMessages": 20
 },
 {
 "handle": "kpszsu",
 "label": "Air Force of the Armed Forces of Ukraine",
 "topic": "alerts",
 "tier": 2,
 "enabled": true,
 "region": "ukraine",
 "maxMessages": 20
 },
 {
 "handle": "LiveUAMap",
 "label": "LiveUAMap",
 "topic": "breaking",
 "tier": 2,
 "enabled": true,
 "region": "global",
 "maxMessages": 25
 },
 {
 "handle": "OSINTdefender",
 "label": "OSINTdefender",
 "topic": "conflict",
 "tier": 2,
 "enabled": true,
 "region": "global",
 "maxMessages": 25
 },
 {
 "handle": "OsintUpdates",
 "label": "Osint Updates",
 "topic": "breaking",
 "tier": 2,
 "enabled": true,
 "region": "global",
 "maxMessages": 20
 },
 {
 "handle": "bellingcat",
 "label": "Bellingcat",
 "topic": "osint",
 "tier": 3,
 "enabled": true,
 "region": "global",
 "maxMessages": 10
 },
 {
 "handle": "CyberDetective",
 "label": "CyberDetective",
 "topic": "cyber",
 "tier": 3,
 "enabled": true,
 "region": "global",
 "maxMessages": 15
 },
 {
 "handle": "GeopoliticalCenter",
 "label": "GeopoliticalCenter",
 "topic": "geopolitics",
 "tier": 3,
 "enabled": true,
 "region": "global",
 "maxMessages": 20
 },
 {
 "handle": "Middle_East_Spectator",
 "label": "Middle East Spectator",
 "topic": "middleeast",
 "tier": 3,
 "enabled": true,
 "region": "middleeast",
 "maxMessages": 20
 },
 {
 "handle": "MiddleEastNow_Breaking",
 "label": "Middle East Now Breaking",
 "topic": "middleeast",
 "tier": 3,
 "enabled": true,
 "region": "middleeast",
 "maxMessages": 15
 },
 {
 "handle": "nexta_tv",
 "label": "NEXTA",
 "topic": "politics",
 "tier": 3,
 "enabled": true,
 "region": "europe",
 "maxMessages": 15
 },
 {
 "handle": "OSINTIndustries",
 "label": "OSINT Industries",
 "topic": "osint",
 "tier": 3,
 "enabled": true,
 "region": "global",
 "maxMessages": 15
 },
 {
 "handle": "Osintlatestnews",
 "label": "OSIntOps News",
 "topic": "osint",
 "tier": 3,
 "enabled": true,
 "region": "global",
 "maxMessages": 20
 },
 {
 "handle": "osintlive",
 "label": "OSINT Live",
 "topic": "osint",
 "tier": 3,
 "enabled": true,
 "region": "global",
 "maxMessages": 15
 },
 {
 "handle": "OsintTv",
 "label": "OsintTV",
 "topic": "geopolitics",
 "tier": 3,
 "enabled": true,
 "region": "global",
 "maxMessages": 15
 },
 {
 "handle": "spectatorindex",
 "label": "The Spectator Index",
 "topic": "breaking",
 "tier": 3,
 "enabled": true,
 "region": "global",
 "maxMessages": 15
 },
 {
 "handle": "wfwitness",
 "label": "Witness",
 "topic": "breaking",
 "tier": 3,
 "enabled": true,
 "region": "global",
 "maxMessages": 15
 },
 {
 "handle": "war_monitor",
 "label": "monitor",
 "topic": "alerts",
 "tier": 3,
 "enabled": true,
 "region": "ukraine",
 "maxMessages": 20
 },
 {
 "handle": "nayaforiraq",
 "label": "Naya for Iraq",
 "topic": "politics",
 "tier": 3,
 "enabled": true,
 "region": "middleeast",
 "maxMessages": 20
 },
 {
 "handle": "yediotnews25",
 "label": "Yedioth News",
 "topic": "breaking",
 "tier": 3,
 "enabled": true,
 "region": "middleeast",
 "maxMessages": 20
 },
 {
 "handle": "DDGeopolitics",
 "label": "DD Geopolitics",
 "topic": "geopolitics",
 "tier": 3,
 "enabled": true,
 "region": "global",
 "maxMessages": 20
 },
 {
 "handle": "FotrosResistancee",
 "label": "Fotros Resistance",
 "topic": "conflict",
 "tier": 3,
 "enabled": true,
 "region": "iran",
 "maxMessages": 20
 },
 {
 "handle": "RezistanceTrench1",
 "label": "Resistance Trench",
 "topic": "conflict",
 "tier": 3,
 "enabled": true,
 "region": "middleeast",
 "maxMessages": 20
 },
 {
 "handle": "geopolitics_prime",
 "label": "Geopolitics Prime",
 "topic": "geopolitics",
 "tier": 3,
 "enabled": true,
 "region": "global",
 "maxMessages": 20
 },
 {
 "handle": "thecradlemedia",
 "label": "The Cradle",
 "topic": "middleeast",
 "tier": 3,
 "enabled": true,
 "region": "middleeast",
 "maxMessages": 20
 },
 {
 "handle": "LebUpdate",
 "label": "Lebanon Update",
 "topic": "breaking",
 "tier": 3,
 "enabled": true,
 "region": "middleeast",
 "maxMessages": 20
 }
 ],
 "tech": [],
 "finance": []
 }
}

gamma-irradiators.json

The IAEA has recently published its updated Database on Industrial Irradiation Facilities (DIIF), featuring an interactive map with information on nearly 300 gamma irradiators and electron accelerators from around the world.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


{
 "source": "IAEA DIIF - Database on Industrial Irradiation Facilities",
 "tableauUrl": "https://public.tableau.com/app/profile/acceleratorknowledgeportal/viz/IrradiatorDatabase/Home",
 "extracted": "2026-01-09",
 "totalFacilities": 136,
 "note": "Gamma irradiator facilities worldwide. Coordinates extracted from Tableau Public visualization.",
 "facilities": [
 { "id": "gi-001", "city": "Vega Alta", "country": "Puerto Rico", "lat": 18.420295, "lon": -66.334995 },
 { "id": "gi-002", "city": "Northborough, MA", "country": "USA", "lat": 42.311091, "lon": -71.649221 },
 { "id": "gi-003", "city": "Chester, NY", "country": "USA", "lat": 41.323774, "lon": -74.289753 },
 { "id": "gi-136", "city": "Ibaraki", "country": "Japan", "lat": 5.677879, "lon": 140.48205 }
 ]
}

mirta-processed.json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45


{
 "metadata": {
 "source": "MIRTA - Military Installations, Ranges and Training Areas",
 "url": "https://geospatial-usace.opendata.arcgis.com/maps/fc0f38c5a19a46dbacd92f2fb823ef8c",
 "fetchedAt": "2026-02-27T20:15:03.751Z",
 "totalInstallations": 832,
 "fromPoints": 737,
 "fromBoundariesOnly": 95
 },
 "installations": [
 {
 "name": "1LT John A Fera USARC",
 "branch": "Army Reserve",
 "status": "Active",
 "state": "Massachusetts",
 "lat": 42.589288,
 "lon": -70.943131,
 "kind": "Installation",
 "component": "Reserve",
 "jointBase": false
 },
 {
 "name": "Yukon Weapons Range",
 "branch": "Air Force",
 "status": "Active",
 "state": "Alaska",
 "lat": 64.768855128,
 "lon": -146.894347173,
 "kind": "Installation",
 "component": "Active",
 "jointBase": false
 },
 {
 "name": "Yuma Proving Ground",
 "branch": "Army",
 "status": "Active",
 "state": "Arizona",
 "lat": 33.1700688670001,
 "lon": -114.353450857,
 "kind": "Installation",
 "component": "Active",
 "jointBase": false
 }
 ]
}

.env.example

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194


# ============================================
# World Monitor — Environment Variables
# ============================================
# Copy this file to .env.local and fill in the values you need.
# All keys are optional — the dashboard works without them,
# but the corresponding features will be disabled.
#
# cp .env.example .env.local
#
# ============================================


# ------ AI Summarization (Vercel) ------

# Groq API (primary — 14,400 req/day on free tier)
# Get yours at: https://console.groq.com/
GROQ_API_KEY=

# OpenRouter API (fallback — 50 req/day on free tier)
# Get yours at: https://openrouter.ai/
OPENROUTER_API_KEY=


# ------ Cross-User Cache (Vercel — Upstash Redis) ------

# Used to deduplicate AI calls and cache risk scores across visitors.
# Create a free Redis database at: https://upstash.com/
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=


# ------ Market Data (Vercel) ------

# Finnhub (primary stock quotes — free tier available)
# Register at: https://finnhub.io/
FINNHUB_API_KEY=


# ------ Energy Data (Vercel) ------

# U.S. Energy Information Administration (oil prices, production, inventory)
# Register at: https://www.eia.gov/opendata/
EIA_API_KEY=


# ------ Economic Data (Vercel) ------

# FRED (Federal Reserve Economic Data)
# Register at: https://fred.stlouisfed.org/docs/api/api_key.html
FRED_API_KEY=


# ------ Aviation Intelligence (Vercel) ------

# AviationStack (live flight data, airport flights, carrier ops)
# Register at: https://aviationstack.com/
AVIATIONSTACK_API=

# ICAO API (NOTAM airport closures — optional, MENA region)
# Register at: https://applications.icao.int/
ICAO_API_KEY=

# Travelpayouts (flight price search — optional, demo only)
# Register at: https://www.travelpayouts.com/
TRAVELPAYOUTS_API_TOKEN=


# ------ Aircraft Tracking (Vercel) ------

# Wingbits aircraft enrichment (owner, operator, type)
# Contact: https://wingbits.com/
WINGBITS_API_KEY=


# ------ Conflict & Protest Data (Vercel) ------

# ACLED (Armed Conflict Location & Event Data — free for researchers)
# Register at: https://acleddata.com/
ACLED_ACCESS_TOKEN=

# UCDP (Uppsala Conflict Data Program — access token required since 2025)
# Register at: https://ucdp.uu.se/apidocs/
UCDP_ACCESS_TOKEN=


# ------ Internet Outages (Vercel) ------

# Cloudflare Radar API (requires free Cloudflare account with Radar access)
CLOUDFLARE_API_TOKEN=


# ------ Satellite Fire Detection (Vercel) ------

# NASA FIRMS (Fire Information for Resource Management System)
# Register at: https://firms.modaps.eosdis.nasa.gov/
NASA_FIRMS_API_KEY=


# ------ Railway Relay (scripts/ais-relay.cjs) ------
# The relay server handles AIS vessel tracking + OpenSky aircraft data + RSS proxy.
# It can also run the Telegram OSINT poller (stateful MTProto) when configured.
# Deploy on Railway with: node scripts/ais-relay.cjs

# AISStream API key for live vessel positions
# Get yours at: https://aisstream.io/
AISSTREAM_API_KEY=

# OpenSky Network OAuth2 credentials (higher rate limits for cloud IPs)
# Register at: https://opensky-network.org/
OPENSKY_CLIENT_ID=
OPENSKY_CLIENT_SECRET=


# ------ Telegram OSINT (Railway relay) ------
# Telegram MTProto keys (free): https://my.telegram.org/apps
TELEGRAM_API_ID=
TELEGRAM_API_HASH=

# GramJS StringSession generated locally (see: scripts/telegram/session-auth.mjs)
TELEGRAM_SESSION=

# Which curated list bucket to ingest: full | tech | finance
TELEGRAM_CHANNEL_SET=full

# ------ Railway Relay Connection (Vercel → Railway) ------

# Server-side URL (https://) — used by Vercel edge functions to reach the relay
WS_RELAY_URL=

# Optional client-side URL (wss://) — local/dev fallback only
VITE_WS_RELAY_URL=

# Shared secret between Vercel and Railway relay.
# Must be set to the SAME value on both platforms in production.
RELAY_SHARED_SECRET=

# Header name used to send the relay secret (must match on both platforms)
RELAY_AUTH_HEADER=x-relay-key

# Emergency production override to allow unauthenticated relay traffic.
# Leave unset/false in production.
ALLOW_UNAUTHENTICATED_RELAY=false

# Rolling window size (seconds) used by relay /metrics endpoint.
RELAY_METRICS_WINDOW_SECONDS=60


# ------ Public Data Sources (no keys required) ------

# UNHCR (UN Refugee Agency) — public API, no auth (CC BY 4.0)
# Open-Meteo — public API, no auth (processes Copernicus ERA5)
# WorldPop — public API, no auth needed


# ------ Site Configuration ------

# Site variant: "full" (worldmonitor.app) or "tech" (tech.worldmonitor.app)
VITE_VARIANT=full

# API base URL for web redirect. When set, browser fetch calls to /api/*
# are redirected to this URL. Leave empty for same-domain API (local installs).
# Production: https://api.worldmonitor.app
VITE_WS_API_URL=

# Client-side Sentry DSN (optional). Leave empty to disable error reporting.
VITE_SENTRY_DSN=

# Map interaction mode:
# - "flat" keeps pitch/rotation disabled (2D interaction)
# - "3d" enables pitch/rotation interactions (default)
VITE_MAP_INTERACTION_MODE=3d

# Self-hosted map tiles (optional — PMTiles on Cloudflare R2 or any HTTP server)
# Leave empty to use free OpenFreeMap tiles. Set to your own PMTiles URL for self-hosted tiles.
# See: https://protomaps.com/docs/pmtiles for how to generate PMTiles files.
VITE_PMTILES_URL=
# Public CORS-enabled URL for the same PMTiles file (used by Tauri desktop app).
# If your VITE_PMTILES_URL is behind a reverse proxy without CORS, set this to the
# direct R2/S3 public URL. The desktop app uses this URL; the web app uses VITE_PMTILES_URL.
VITE_PMTILES_URL_PUBLIC=


# ------ Desktop Cloud Fallback (Vercel) ------

# Comma-separated list of valid API keys for desktop cloud fallback.
# Generate with: openssl rand -hex 24 | sed 's/^/wm_/'
WORLDMONITOR_VALID_KEYS=


# ------ Registration DB (Convex) ------

# Convex deployment URL for email registration storage.
# Set up at: https://dashboard.convex.dev/
CONVEX_URL=

Situation Monitor Dashboard

A geopolitics-focused news aggregation dashboard with 3D globe visualization, designed for monitoring global situations, US policy changes, and conflict zones.

其他

全球地缘政治事件时仪表盘工具汇总

链接： https://zhuanlan.zhihu.com/p/2012091361713730005

汇总一下提供全球新闻、市场和地缘政治事件的实时仪表盘类工具，方便跟踪当下的伊朗等国际地缘政治热点事件。

Pentagon Pizza Watch & Polyglobe

https://www.pizzint.watch/

五角大楼披萨指数，监测美国五角大楼周边披萨店指数，观察潜在的军事活动趋势

Polyglobe

https://www.pizzint.watch/polyglobe

https://www.pizzint.watch/about/polyglobe

Pentagon Pizza Watch 的 Polyglobe，用于可视化地缘政治预测市场的实时 Polymarket 地图

Liveuamap

https://www.liveuamap.com/

全球冲突事件实时地图

Glint

Glint - Real-time Prediction Market Intelligence

专为预测市场交易者设计的实时开源情报仪表盘，将突发新闻、社会媒体信号、开源情报和军事飞行数据实时映射到Polymarket等平台的合约赔率上

Situation Monitor

https://hipcityreg-situation-monitor.vercel.app/

https://github.com/hipcityreg/situation-monitor

开源监控全球新闻、市场和地缘政治事件的实时仪表盘

Watchtower

https://github.com/lajosdeme/watchtower

开源基于终端的全球情报仪表盘

Iran Monitor

https://www.iranmonitor.org/

一站式获取与伊朗有关可靠资讯的开源情报站，追踪伊朗局势、军事动态等信息的首选工具。

DeepStateMap

https://deepstatemap.live/

专注于俄乌战争前线动态的开源地图，目前公认对乌克兰前线局势更新最细致、最准确的地图之一

ACLED

https://acleddata.com/platform/explorer

全球冲突数据分析，提供全球政治暴力、示威和抗议事件的数据库，并提供交互式地图

UnderstandingWar

https://understandingwar.org/

提供深入战况分析报告、地缘政治解读和交互式地图产品

https://yeeach.com/2975/

知乎爬虫——ZhiZhu项目分析

Thu, 05 Mar 2026 12:34:25 -0800

知乎爬虫——ZhiZhu项目分析

简介

ZhiZhu (知蛛) ——爬取指定知乎用户的所有回答和所有文章，以高保真 Markdown 格式保存到本地。

“我们在互联网上留下的每一个字节，都是灵魂的碎片。是时候把它们找回来了。”

为什么是 ZhiZhu？

多年来，你在知乎上敲下的数万、数十万字，不仅仅是简单的问答。它们是你知识体系的疆界，是你价值观的投影，是你逻辑思维的演变轨迹，更是你在这个喧嚣世界中发出的独特声音。

然而，散落在互联网角落的数据是脆弱的，也是割裂的。

ZhiZhu (知蛛) 是一台时光穿梭机，也是一位数字考古学家。它致力于将你流落在知乎的精神财富，以最纯粹、最通用的 Markdown 格式完整带回本地。无论是精妙的 LaTeX 数学公式，还是承载记忆的图片，都力求高保真还原。

Archiving the past to compute the future.
归档过去，为了计算未来。

在 AI 时代，这不仅仅是备份

当你拥有了这份属于自己的全量数据，你就拥有了训练私人 AI 助理的基石。你可以将这些代表你 “人格（Personality）” 的文本投喂给 LLM，让 AI 成为你的镜子——

自我复盘 — 利用 AI 分析你过去数年的回答，生成你的「认知演变报告」
知识图谱 — 从散乱的回答中提取你的知识结构，重组为系统化的文章
风格克隆 — 让 AI 学习你的文风与逻辑，成为最懂你的写作助手
深度对话 — 与你的「数字孪生」对话，完成一次深度的自我探索与反省

把数据存成 Markdown，只是第一步；认识你自己，才是 ZhiZhu 的终极目标。

Don’t just leave it on the cloud. Own your thoughts.
别把思想只留在云端，拥有它。

核心能力

能力	说明
用户级全量爬取	输入用户 URL token，自动收集该用户的全部回答与文章
用户想法爬取	爬取指定用户的所有知乎想法（Pins）
问题级爬取	爬取指定问题下的全部或前 N 个回答
单回答爬取	精准爬取某个特定回答，可选附带完整评论区
评论区提取	通过知乎 API 获取全部根评论与子评论，格式化为 Markdown
浏览器指纹伪装	内置 WebGL、Canvas、AudioContext 等多维度反检测机制
智能延迟策略	请求间随机等待 10-20 秒（可自定义），以时间换安全
断点续传	自动记录进度，中断后重新运行即从上次位置继续
LaTeX 公式还原	完美转换知乎数学公式为标准 $...$ / `$$...$$` 语法
图片本地化	自动下载文章图片到本地，重写 Markdown 引用路径
内容去噪	自动去除广告卡片、视频占位符、知乎直答链接等干扰元素
持久化登录	登录一次，后续爬取无需重复登录

重要代码分析

main.py中argparse参数解析

1
2
3
4
5
6
7
8


def _add_common_args(parser: argparse.ArgumentParser):
 """为子命令添加公共参数。"""
 parser.add_argument(
 "--output", "-o",
 type=str,
 default=None,
 help="输出目录路径",
 )

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


 subparsers = parser.add_subparsers(dest="command", help="可用命令")

 # ── login 子命令 ──
 login_parser = subparsers.add_parser("login", help="登录知乎（手动登录，保存 Cookie）")
 login_parser.add_argument(
 "--timeout",
 type=int,
 default=300,
 help="等待登录的超时时间（秒），默认 300",
 )

webui.py中的通用流式日志生成器

将 fn() 产生的所有 print() 输出实时 yield 给 Gradio Textbox。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55


# ── stdout 重定向 ──────────────────────────────────────────────

class _QueueWriter:
 """将 print() 输出收集到 queue.Queue，供生成器逐行 yield 给 Gradio。"""

 def __init__(self, q: queue.Queue) -> None:
 self._q = q
 self._buf = ""

 def write(self, text: str) -> None:
 self._buf += text
 while "\n" in self._buf:
 line, self._buf = self._buf.split("\n", 1)
 self._q.put(line)

 def flush(self) -> None:
 if self._buf:
 self._q.put(self._buf)
 self._buf = ""

 def fileno(self) -> int:
 return sys.__stdout__.fileno()


def _run_in_thread(fn, q: queue.Queue) -> None:
 """在子线程中执行 fn()，完成后向队列推送 None（结束信号）。"""
 old_stdout = sys.stdout
 sys.stdout = _QueueWriter(q) # type: ignore[assignment]
 try:
 fn()
 except Exception as e:
 sys.stdout.write(f"\n[ERROR] {e}\n") # type: ignore[union-attr]
 finally:
 sys.stdout.flush() # type: ignore[union-attr]
 sys.stdout = old_stdout
 q.put(None) # 结束信号


def _stream_logs(fn) -> Generator[str, None, None]:
 """
 通用流式日志生成器。
 将 fn() 产生的所有 print() 输出实时 yield 给 Gradio Textbox。
 """
 q: queue.Queue = queue.Queue()
 t = threading.Thread(target=_run_in_thread, args=(fn, q), daemon=True)
 t.start()
 log_lines: list[str] = []
 while True:
 item = q.get()
 if item is None:
 break
 log_lines.append(item)
 yield "\n".join(log_lines)
 t.join()
 yield "\n".join(log_lines)

tui.py中的终端交互

提供基于 Textual 的 TUI 界面，覆盖 ZhiZhu 的全部功能。

不同面板对应不同的功能，使用stdout 重定向输出日志。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


# ── 任务分发 ───────────────────────────────────────────────────

def _dispatch(key: str, params: dict[str, Any]) -> None:
 """根据功能 key 调用对应的 scraper/merge 函数（在 Worker 线程中执行）。"""

 if key == "login":
 from scraper import login
 asyncio.run(login(**params))

 elif key == "scrape_user":
 from scraper import scrape_user
 asyncio.run(scrape_user(**params))

 elif key == "scrape_pins":
 from scraper import scrape_user_pins
 asyncio.run(scrape_user_pins(**params))

 elif key == "scrape_question":
 from scraper import scrape_question
 asyncio.run(scrape_question(**params))

 elif key == "scrape_answer":
 from scraper import scrape_single_answer
 asyncio.run(scrape_single_answer(**params))

 elif key == "merge":
 from merge_md import merge
 merge(**params)

merge_md.py中的文本预处理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


# ── 工具函数 ──────────────────────────────────────────────────

def collect_md_files(root: Path) -> list[Path]:
 """
 从指定根目录中收集所有 .md 文件。
 支持两种结构：
 - <root>/<子文件夹>/index.md
 - <root>/<文件>.md
 """
 files: list[Path] = []
 for path in root.rglob("*.md"):
 files.append(path)
 return files


def extract_date_from_header(text: str) -> str:
 """
 从 Markdown 文件头部的元信息中提取日期字符串（YYYY-MM-DD）。
 格式如：> **日期**: 2025-12-24
 找不到时返回空字符串。
 """
 m = re.search(r'>\s*\*\*日期\*\*:\s*(\d{4}-\d{2}-\d{2})', text[:600])
 return m.group(1) if m else ""


def sort_key_by_date(path: Path) -> tuple[str, str]:
 """按文件头部日期排序，日期相同时按文件路径排序。"""
 try:
 text = path.read_text(encoding="utf-8")
 except Exception:
 text = ""
 date = extract_date_from_header(text)
 return (date, str(path))


def sort_key_by_name(path: Path) -> str:
 """按文件路径字母顺序排序。"""
 return str(path)

stealth.py — 反检测 JavaScript 注入模块

参考 hg3386628/zhihu-scraper 和 yuchenzhu-research/zhihu-scraper 的反爬策略。

集成 WebGL、Canvas、AudioContext 指纹伪装以及 navigator.webdriver 覆盖。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93


STEALTH_JS = """
// 覆盖 navigator.webdriver
Object.defineProperty(navigator, 'webdriver', {
 get: () => undefined,
 configurable: true
});

// 添加 Chrome 浏览器特有属性
window.chrome = {
 runtime: {},
 loadTimes: function() {},
 csi: function() {},
 app: {}
};

// 覆盖 Permissions API
const originalQuery = window.navigator.permissions.query;
window.navigator.permissions.query = (parameters) => (
 parameters.name === 'notifications' ?
 Promise.resolve({state: Notification.permission}) :
 originalQuery(parameters)
);

// 伪造 WebGL 渲染器信息
const getParameter = WebGLRenderingContext.prototype.getParameter;
WebGLRenderingContext.prototype.getParameter = function(parameter) {
 if (parameter === 37445) return 'Intel Inc.';
 if (parameter === 37446) return 'Intel Iris OpenGL Engine';
 return getParameter.apply(this, [parameter]);
};

// 随机化 Canvas 指纹
const origToDataURL = HTMLCanvasElement.prototype.toDataURL;
HTMLCanvasElement.prototype.toDataURL = function(type) {
 if (type === 'image/png' && this.width === 16 && this.height === 16) {
 const canvas = document.createElement('canvas');
 canvas.width = this.width;
 canvas.height = this.height;
 const ctx = canvas.getContext('2d');
 ctx.drawImage(this, 0, 0);
 const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
 const data = imageData.data;
 for (let i = 0; i < data.length; i += 4) {
 data[i] = data[i] + Math.floor(Math.random() * 10) - 5;
 data[i+1] = data[i+1] + Math.floor(Math.random() * 10) - 5;
 data[i+2] = data[i+2] + Math.floor(Math.random() * 10) - 5;
 }
 ctx.putImageData(imageData, 0, 0);
 return origToDataURL.apply(canvas, arguments);
 }
 return origToDataURL.apply(this, arguments);
};

// 修改 AudioContext 指纹
const audioContext = window.AudioContext || window.webkitAudioContext;
if (audioContext) {
 const origGetChannelData = AudioBuffer.prototype.getChannelData;
 AudioBuffer.prototype.getChannelData = function() {
 const channelData = origGetChannelData.apply(this, arguments);
 if (channelData.length > 20) {
 const noise = 0.0001;
 for (let i = 0; i < Math.min(channelData.length, 500); i++) {
 channelData[i] = channelData[i] + (Math.random() * noise * 2 - noise);
 }
 }
 return channelData;
 };
}

// 随机化硬件并发数
Object.defineProperty(navigator, 'hardwareConcurrency', {
 get: () => 8 + Math.floor(Math.random() * 4),
 configurable: true
});

// 随机化设备内存
Object.defineProperty(navigator, 'deviceMemory', {
 get: () => 8,
 configurable: true
});

// 覆盖 plugins 长度（正常浏览器有 plugin）
Object.defineProperty(navigator, 'plugins', {
 get: () => [1, 2, 3, 4, 5],
 configurable: true
});

// 覆盖 languages
Object.defineProperty(navigator, 'languages', {
 get: () => ['zh-CN', 'zh', 'en-US', 'en'],
 configurable: true
});
"""

scraper.py — 知乎内容爬虫核心模块

功能：

使用 Playwright 持久化上下文登录知乎（手动登录，保存 Cookie）
爬取指定用户的所有回答和文章链接
爬取指定用户的所有想法（Pins）
爬取指定问题下的所有（或前 N 个）回答
爬取单个回答，可选附带评论区
逐个访问并提取内容，转为 Markdown 保存
内置反检测（stealth JS 注入、指纹伪装）
请求间隔随机延迟，降低被封风险

浏览器上下文管理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78


# ── 浏览器上下文管理 ─────────────────────────────────────────

async def create_browser_context(pw, headless=False) -> BrowserContext:
 """创建带有反检测的持久化浏览器上下文。"""
 USER_DATA_DIR.mkdir(parents=True, exist_ok=True)

 width = 1920 + random.randint(-100, 100)
 height = 1080 + random.randint(-50, 50)

 launch_args = [
 "--no-first-run",
 "--no-default-browser-check",
 "--disable-blink-features=AutomationControlled",
 "--disable-features=IsolateOrigins,site-per-process",
 "--disable-site-isolation-trials",
 "--disable-infobars",
 f"--window-size={width},{height}",
 ]

 context = await pw.chromium.launch_persistent_context(
 user_data_dir=str(USER_DATA_DIR),
 headless=headless,
 slow_mo=50,
 args=launch_args,
 viewport={"width": width, "height": height},
 user_agent=USER_AGENT,
 locale="zh-CN",
 timezone_id="Asia/Shanghai",
 java_script_enabled=True,
 )

 # 注入反检测脚本
 await context.add_init_script(STEALTH_JS)

 return context

# ── 登录 ─────────────────────────────────────────────────────

async def login(timeout: int = 300):
 """
 打开知乎登录页面，等待用户手动登录。
 登录状态会保存在 browser_data 目录中，后续爬取无需重复登录。

 Args:
 timeout: 等待登录的超时时间（秒），默认 300 秒
 """
 print("=" * 60)
 print("🔐 知乎登录")
 print("=" * 60)
 print(f"将打开浏览器，请在 {timeout} 秒内完成登录。")
 print("登录成功后，程序会自动检测并保存登录状态。\n")

 async with async_playwright() as pw:
 context = await create_browser_context(pw, headless=False)
 try:
 page = context.pages[0] if context.pages else await context.new_page()
 await page.goto("https://www.zhihu.com/signin", wait_until="domcontentloaded")

 print("⏳ 等待登录... 请在浏览器中完成登录操作。")

 # 等待用户登录成功（检测跳转到首页或出现用户头像）
 start_time = time.time()
 while time.time() - start_time < timeout:
 url = page.url
 # 登录成功后一般会跳转到首页
 if "signin" not in url and "signup" not in url:
 # 额外等待几秒确保 Cookie 完全写入
 await asyncio.sleep(3)
 print("✅ 登录成功！登录状态已保存。")
 print(f" 数据目录: {USER_DATA_DIR.resolve()}")
 return True
 await asyncio.sleep(2)

 print("❌ 登录超时，请重试。")
 return False

 finally:
 await context.close()

爬取回答对应的URL

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97


async def collect_question_answer_links(
 page: Page, question_id: str, max_answers: int | None = None
) -> list[str]:
 """
 在问题页面中滚动，收集回答链接。

 Args:
 page: Playwright 页面对象
 question_id: 知乎问题 ID
 max_answers: 最多收集的回答数量（None 表示全部）

 Returns:
 去重后的回答链接列表
 """
 url = f"https://www.zhihu.com/question/{question_id}"
 print(f"🌍 访问: {url}")
 await page.goto(url, wait_until="domcontentloaded")
 await asyncio.sleep(5)

 # 关闭可能的登录弹窗
 await _dismiss_popup(page)

 collected_links = set()
 no_new_count = 0
 max_no_new = 10
 scroll_count = 0
 prev_scroll_height = 0

 while no_new_count < max_no_new:
 # 使用 CSS 选择器提取回答链接
 link_elements = await page.query_selector_all('a[href*="/answer/"]')
 links = []
 for el in link_elements:
 href = await el.get_attribute("href")
 if href:
 if href.startswith("//"):
 href = "https:" + href
 elif href.startswith("/"):
 href = "https://www.zhihu.com" + href
 elif not href.startswith("http"):
 href = "https://www.zhihu.com/" + href
 if f"/question/{question_id}/answer/" in href:
 links.append(href.split("?")[0])

 prev_count = len(collected_links)
 collected_links.update(links)
 new_count = len(collected_links) - prev_count

 if new_count == 0:
 no_new_count += 1
 else:
 no_new_count = 0

 scroll_count += 1
 print(f" 📜 第 {scroll_count} 次滚动，已发现 {len(collected_links)} 个回答链接"
 + (f"（新增 {new_count}）" if new_count > 0 else "（无新增）"))

 # 检查是否已达到目标数量
 if max_answers and len(collected_links) >= max_answers:
 print(f" 📋 已达到目标数量 {max_answers}。")
 break

 # 检查页面是否包含明确的"到底"标识
 end_marker = await page.evaluate("""() => {
 const bodyText = document.body.innerText;
 return bodyText.includes('已显示全部') || bodyText.includes('没有更多了');
 }""")

 if end_marker and no_new_count >= 3:
 print(" 📋 已到达列表底部（页面提示已显示全部）。")
 break

 # 检查页面高度是否还在增长
 current_scroll_height = await page.evaluate("document.body.scrollHeight")
 height_changed = current_scroll_height != prev_scroll_height
 prev_scroll_height = current_scroll_height

 if not height_changed and no_new_count >= 5:
 print(" 📋 页面不再加载新内容，停止滚动。")
 break

 # 滚动 — 使用多种方式触发知乎的懒加载
 scroll_distance = random.randint(800, 1500)
 await page.keyboard.press("End")
 await asyncio.sleep(0.5)
 await page.evaluate(f"document.documentElement.scrollTop += {scroll_distance}")
 await asyncio.sleep(0.3)
 await page.keyboard.press("End")

 await asyncio.sleep(2.0 + random.random() * 2)
 if new_count == 0:
 await asyncio.sleep(2.0)

 result = sorted(collected_links)
 if max_answers:
 result = result[:max_answers]
 return result

处理评论

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97


async def collect_question_answer_links(
 page: Page, question_id: str, max_answers: int | None = None
) -> list[str]:
 """
 在问题页面中滚动，收集回答链接。

 Args:
 page: Playwright 页面对象
 question_id: 知乎问题 ID
 max_answers: 最多收集的回答数量（None 表示全部）

 Returns:
 去重后的回答链接列表
 """
 url = f"https://www.zhihu.com/question/{question_id}"
 print(f"🌍 访问: {url}")
 await page.goto(url, wait_until="domcontentloaded")
 await asyncio.sleep(5)

 # 关闭可能的登录弹窗
 await _dismiss_popup(page)

 collected_links = set()
 no_new_count = 0
 max_no_new = 10
 scroll_count = 0
 prev_scroll_height = 0

 while no_new_count < max_no_new:
 # 使用 CSS 选择器提取回答链接
 link_elements = await page.query_selector_all('a[href*="/answer/"]')
 links = []
 for el in link_elements:
 href = await el.get_attribute("href")
 if href:
 if href.startswith("//"):
 href = "https:" + href
 elif href.startswith("/"):
 href = "https://www.zhihu.com" + href
 elif not href.startswith("http"):
 href = "https://www.zhihu.com/" + href
 if f"/question/{question_id}/answer/" in href:
 links.append(href.split("?")[0])

 prev_count = len(collected_links)
 collected_links.update(links)
 new_count = len(collected_links) - prev_count

 if new_count == 0:
 no_new_count += 1
 else:
 no_new_count = 0

 scroll_count += 1
 print(f" 📜 第 {scroll_count} 次滚动，已发现 {len(collected_links)} 个回答链接"
 + (f"（新增 {new_count}）" if new_count > 0 else "（无新增）"))

 # 检查是否已达到目标数量
 if max_answers and len(collected_links) >= max_answers:
 print(f" 📋 已达到目标数量 {max_answers}。")
 break

 # 检查页面是否包含明确的"到底"标识
 end_marker = await page.evaluate("""() => {
 const bodyText = document.body.innerText;
 return bodyText.includes('已显示全部') || bodyText.includes('没有更多了');
 }""")

 if end_marker and no_new_count >= 3:
 print(" 📋 已到达列表底部（页面提示已显示全部）。")
 break

 # 检查页面高度是否还在增长
 current_scroll_height = await page.evaluate("document.body.scrollHeight")
 height_changed = current_scroll_height != prev_scroll_height
 prev_scroll_height = current_scroll_height

 if not height_changed and no_new_count >= 5:
 print(" 📋 页面不再加载新内容，停止滚动。")
 break

 # 滚动 — 使用多种方式触发知乎的懒加载
 scroll_distance = random.randint(800, 1500)
 await page.keyboard.press("End")
 await asyncio.sleep(0.5)
 await page.evaluate(f"document.documentElement.scrollTop += {scroll_distance}")
 await asyncio.sleep(0.3)
 await page.keyboard.press("End")

 await asyncio.sleep(2.0 + random.random() * 2)
 if new_count == 0:
 await asyncio.sleep(2.0)

 result = sorted(collected_links)
 if max_answers:
 result = result[:max_answers]
 return result

断点续传功能实现

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


def _scan_done_urls_from_disk(output_dir: Path) -> set[str]:
 """
 扫描输出目录中已存在的 Markdown 文件，从文件头部提取来源 URL。
 兼容两种结构：
 - 普通模式（有图片）：<type_dir>/<子文件夹>/index.md
 - --no-images 模式：<type_dir>/<日期_标题>.md（直接在类型目录中）
 """
 done = set()
 url_pattern = re.compile(r'>\s*\*\*来源\*\*:\s*\[([^\]]+)\]')
 for subdir in ("answers", "articles", "pins"):
 type_dir = output_dir / subdir
 if not type_dir.exists():
 continue
 # 兼容两种结构：递归匹配所有 .md 文件
 for md_file in type_dir.rglob("*.md"):
 try:
 text = md_file.read_text(encoding="utf-8")[:500]
 m = url_pattern.search(text)
 if m:
 done.add(m.group(1))
 except Exception:
 pass
 return done

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


# ── 保存链接列表（用于断点续传） ──
 links_file = output_dir / "links.json"
 links_data = [{"url": url, "type": t} for url, t in all_urls]
 links_file.write_text(
 json.dumps(links_data, ensure_ascii=False, indent=2), encoding="utf-8"
 )
 print(f"📋 链接列表已保存到: {links_file}\n")

 # ── 检查已爬取的内容（断点续传） ──
 progress_file = output_dir / "progress.json"
 done_urls = set()
 if progress_file.exists():
 try:
 done_data = json.loads(progress_file.read_text(encoding="utf-8"))
 done_urls = set(done_data.get("done", []))
 except Exception:
 pass

 # 扫描磁盘上已存在的文件，补充 progress.json 可能遗漏的记录
 disk_urls = _scan_done_urls_from_disk(output_dir)
 if disk_urls - done_urls:
 print(f"📂 从磁盘扫描发现 {len(disk_urls - done_urls)} 个已下载但未记录的内容")
 done_urls |= disk_urls

 if done_urls:
 # 只统计与当前链接列表匹配的数量
 matched = sum(1 for url, _ in all_urls if url in done_urls)
 print(f"📌 检测到之前的进度，已完成 {matched}/{total} 项，将跳过。\n")

 # 同步更新 progress.json
 progress_file.write_text(
 json.dumps({"done": list(done_urls)}, ensure_ascii=False),
 encoding="utf-8",
 )

converter.py——HTML → Markdown 转换模块

处理知乎特有的 LaTeX 公式、代码块、图片链接重写、垃圾内容清洗。

核心策略：在 BeautifulSoup 阶段用占位符保护公式，markdownify 转换后再还原为 $ / $$ 定界符。

参考 yuchenzhu-research/zhihu-scraper 的 converter.py 实现。

清理噪音（知乎直达）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69


# ── 预处理 HTML ──────────────────────────────────────────

 def _preprocess(self, html: str) -> str:
 """在交给 markdownify 之前做知乎特定的 HTML 清洗。"""
 soup = BeautifulSoup(html, "html.parser")

 # 1) 移除视频 / 卡片 / 按钮等干扰元素
 for selector in (
 "div.VideoCard, .RichText-video, .VideoCard-player",
 ".LinkCard, .RichText-LinkCard, .Card, .Reward",
 ".ContentItem-actions, .RichContent-actions",
 ".Post-SideActions, .BottomActions",
 ".css-1gomreu, .Voters",
 ):
 for tag in soup.select(selector):
 tag.decompose()

 # 2) 去除知乎直答链接（zhida.zhihu.com），只保留链接文本
 for a_tag in soup.find_all("a", href=True):
 if "zhida.zhihu.com" in a_tag["href"]:
 a_tag.replace_with(a_tag.get_text())

 # 3) 处理数学公式
 # 知乎 2024+ 格式: <span class="ztext-math" data-tex="...">
 for span in soup.find_all("span", class_="ztext-math"):
 tex = span.get("data-tex", "")
 if not tex:
 continue
 is_block = tex.startswith(r"\[") and tex.endswith(r"\]")
 if is_block:
 tex = tex[2:-2].strip()
 placeholder = self._store_math(tex, is_block)
 marker = soup.new_tag("var")
 marker.string = placeholder
 span.replace_with(marker)

 # 兼容旧版: <img class="ztext-math" data-formula="...">
 for img in soup.select("img.ztext-math"):
 formula = img.get("data-formula", "")
 if not formula:
 continue
 is_block = (
 img.parent
 and img.parent.name in ("p", "div", "figure")
 and len(img.parent.get_text(strip=True)) == 0
 )
 placeholder = self._store_math(formula, is_block)
 marker = soup.new_tag("var")
 marker.string = placeholder
 img.replace_with(marker)

 # 3) <code> 里的 <br> 换成换行符
 for code in soup.find_all("code"):
 for br in code.find_all("br"):
 br.replace_with("\n")

 # 4) 代码块语言标注
 for pre in soup.find_all("pre"):
 code = pre.find("code")
 if code:
 lang = ""
 for cls in code.get("class", []):
 if cls.startswith("language-"):
 lang = cls[len("language-"):]
 break
 if lang:
 code["class"] = [f"language-{lang}"]

 return str(soup)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


# ── 后处理 Markdown ────────────────────────────────────── 
def _postprocess(self, md: str) -> str:
 """清理噪音 + 还原公式占位符。"""
 # 去除知乎直答（zhida.zhihu.com）链接，只保留链接文本 
 md = re.sub(r'\[([^\]]*)\]\(https?://zhida\.zhihu\.com[^)]*\)', r'\1', md)
 # 压缩连续空行 
 md = re.sub(r"\n{3,}", "\n\n", md)
 # 清理行尾空白 
 md = "\n".join(line.rstrip() for line in md.splitlines())

 # 还原公式 (并做 KaTeX 兼容性处理) 
 for key, formula in self._math_store.items():
 fixed_formula = self._fix_katex_array(formula)
 if key.startswith(self._BLOCK_PH):
 md = md.replace(key, f"\n\n$$\n{fixed_formula}\n$$\n\n")
 elif key.startswith(self._INLINE_PH):
 md = md.replace(key, f"${fixed_formula}$")

 # 再次压缩 
 md = re.sub(r"\n{3,}", "\n\n", md)
 return md.strip() + "\n"

PDF转Markdown工具

Thu, 05 Feb 2026 14:34:25 -0800

PDF转Markdown工具

前言

在大语言模型（LLM）迅速发展的时代，文档处理和转换变得尤为重要。当我们需要将各种格式的文档（如 PDF、Word、PowerPoint 等）输入到 LLM 中进行分析或处理时，首先需要将这些文档转换为文本格式。然而，简单的文本转换往往会丢失文档的结构信息，如标题、列表、表格等重要元素。Microsoft 开源的 MarkItDown 项目就是为解决这一问题而诞生的。它能将各种格式的文档转换为 Markdown 格式，既保留了原文档的结构信息，又保证了输出内容的简洁性，特别适合与 LLM 配合使用。本文将深入探讨 MarkItDown 的功能特点、应用场景和使用方法，帮助开发者更好地利用这一强大工具。

markitdown

MarkItDown now offers an MCP (Model Context Protocol) server for integration with LLM applications like Claude Desktop. See markitdown-mcp for more information.

Python tool for converting files and office documents to Markdown.

主要功能

MarkItDown 的核心功能是将各种文件格式转换为 Markdown，特别强调在转换过程中保留文档结构和内容的完整性。与类似工具如 textract 相比，MarkItDown 更专注于保留文档中的以下结构元素：

标题层级
列表格式
表格结构
超链接
图像引用
文本格式（如粗体、斜体）

支持的文件格式

MarkItDown 支持的文件格式非常丰富，包括：

PDF 文档
PowerPoint 演示文稿
Word 文档
Excel 电子表格
图像文件（包括 EXIF 元数据提取和 OCR 文字识别）
音频文件（支持 EXIF 元数据提取和语音转文字）
HTML 网页
各种文本格式（CSV、JSON、XML 等）
ZIP 压缩文件（自动遍历内容）
YouTube 视频链接（提取字幕）
EPub 电子书
以及更多…

技术架构

MarkItDown 采用模块化设计，主要包含以下组件：

核心转换引擎：负责文件格式识别和转换协调
文件格式转换器：针对不同文件格式的专用转换模块
插件系统：支持第三方扩展功能
命令行接口：便于在终端中使用
Python API：方便集成到其他 Python 应用中

安装与使用

安装

MarkItDown 可以通过 pip 安装。为了获得完整功能，建议安装所有可选依赖：

1

pip install markitdown[all]

如果只需要部分功能，可以选择性安装依赖：

1
2


# 仅安装 PDF、Word 和 PowerPoint 支持
pip install markitdown[pdf,docx,pptx]

也可以从源代码安装：

1
2
3


git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

可选依赖包

MarkItDown 将依赖组织为可选特性组，当前支持的特性组包括：

[all]：安装所有可选依赖
[pptx]：PowerPoint 文件支持
[docx]：Word 文件支持
[xlsx]：Excel 文件支持
[xls]：旧版 Excel 文件支持
[pdf]：PDF 文件支持
[outlook]：Outlook 邮件支持
[az-doc-intel]：Azure Document Intelligence 支持
[audio-transcription]：音频转录支持（wav 和 mp3 文件）
[youtube-transcription]：YouTube 视频转录支持

命令行使用

最基本的命令行使用方式：

1
2
3
4
5
6
7
8


# 转换文件并输出到标准输出
markitdown path-to-file.pdf > document.md

# 指定输出文件
markitdown path-to-file.pdf -o document.md

# 从标准输入读取内容
cat path-to-file.pdf | markitdown

命令行方式

Python API 使用

基本使用：

1
2
3
4
5


from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False) # Set to True to enable plugins
result = md.convert("test.xlsx")
print(result.text_content)

集成文档智能：

1
2
3
4
5


from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("test.pdf")
print(result.text_content)

使用大语言模型生成图片描述（当前只适用于 pptx 和 image文件）需要提供 llm_client 和 llm_model:

1
2
3
4
5
6
7


from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o", llm_prompt="optional custom prompt")
result = md.convert("example.jpg")
print(result.text_content)

Azure AI 文档智能是一项基于云的Azure AI 服务，支持构建智能文档处理解决方案。在 Python 代码中使用 MarkItDown：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


from markitdown import MarkItDown

# 基本使用
md = MarkItDown(enable_plugins=False) # 设置为 True 启用插件
result = md.convert("test.xlsx")
print(result.text_content)

# 使用 Azure Document Intelligence
md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("test.pdf")
print(result.text_content)

pdf3md

PDF3MD 是一个现代化、用户友好的网络应用程序，旨在将 PDF 文档转换为干净、格式化的 Markdown 文本。它提供了高效的转换工具，支持多种文件格式之间的转换。

注意：不要用那种扫描的 pdf 文件，毕竟还不支持 ocr 功能

A modern, user-friendly web application that converts PDF documents to clean, formatted Markdown text.

主要特点

PDF 转 Markdown：能够将 PDF 文档转换为可读性强的 Markdown 格式，同时保留文档的结构元素。
Markdown 转 Word (DOCX)：支持将用户提供的 Markdown 文本转换为 DOCX 格式，使用 Pandoc 实现高质量输出。
多文件上传：支持同时上传和处理多个 PDF 文件，提升工作效率。
拖拽式界面：提供用户友好的文件上传方式，支持拖放或传统的文件选择。
实时进度跟踪：在转换过程中提供详细的状态更新，用户可以实时监控转换进度。
现代响应式用户界面：设计直观，适合各种设备使用。

应用场景

文档转换：适用于需要将 PDF 文档转换为 Markdown 的用户，例如技术文档编辑、博客撰写等。
内容编辑：方便用户在 Markdown 格式下进行内容编辑和格式化，然后可以轻松导出为 Word 文档。
批量处理：适合需要处理大量文档的场景，例如教育机构、出版社等。

PDF3MD 通过提供简化的文档转换流程，大大提升了用户的工作效率和体验。

gptpdf

gptpdf 是一个利用VLLM解析PDF为Markdown的工具，几乎完美支持数学公式、表格等。

GPTPDF 是一个使用视觉大模型（如 GPT-4o）将 PDF 文件解析成 Markdown 文件的工具。它主要用于高效地解析 PDF 文档中的排版、数学公式、表格、图片、图表等内容，并将这些内容转换为结构化的 Markdown 格式。其显著特点是简单且成本低，每页平均费用为 $0.013。

地址： https://github.com/CosmosShadow/gptpdf

marker

Marker是一款将PDF快速精准转换为Markdown的工具，支持多种文档格式和语言。

Marker是一款能够快速且准确地将PDF转换为Markdown的工具。它支持多种类型的文档（针对书籍和科学论文进行了优化），支持所有语言，并且能够去除页眉、页脚及其他杂乱信息。此外，它还能正确格式化表格和代码块，并提取图像保存为Markdown。同时，Marker将大多数的公式转换为LaTeX格式，适用于GPU、CPU或MPS环境。

地址： https://github.com/vikparuchuri/marker

PDF-Extract-Kit

PDF-Extract-Kit 提供高质量PDF内容提取，支持布局检测、公式识别和OCR功能

基本功能：

版面检测：使用 LayoutLMv3 模型进行区域检测，如检测图片、表格、标题、文本等。
公式检测：使用 YOLOv8 模型检测公式，包括行内公式和独立公式。
公式识别：使用 UniMERNet 进行公式识别。
光学字符识别 (OCR)：使用 PaddleOCR 进行文本识别。

地址： https://github.com/opendatalab/PDF-Extract-Kit

zeroX

Zerox OCR 是一种经济高效且准确的文档OCR工具，适用于AI数据处理。

Zerox OCR 是一种极其简便的方法，用于将文档进行光学字符识别（OCR）并方便人工智能进行后续处理。鉴于文档往往包含复杂布局、表格、图表等，视觉模型在处理这些内容时尤其有效。

基本逻辑如下：

提供一个 PDF 文件（URL 或文件缓冲区）。
将 PDF 转换成一系列图像。
将每个图像传给 GPT，让其生成 Markdown 格式的文本。
聚合所有响应，并返回 Markdown 格式的结果。

地址： https://github.com/getomni-ai/zeroX

omniparse

OmniParse是一个将各种非结构化数据转换为结构化、适用于生成式AI（LLM）应用的平台。

OmniParse 是一个数据解析平台，旨在将各种非结构化数据转换为适用于生成式AI（GenAI）应用的结构化数据。无论是文档、表格、图像、视频、音频文件，还是网页，OmniParse 都能对其进行处理，使其变得干净、结构化，并为诸如 RAG（Retrieval-Augmented Generation）和细调等AI应用做好准备。

特色：

完全本地化，无需外部API
支持多达 20 种文件类型
将文档、多媒体和网页转换为高质量的结构化 Markdown
支持表格提取、图像提取与标注、音频/视频转录、网页爬取
通过 Docker 和 Skypilot 轻松部署
兼容 Colab
交互式 UI 由 Gradio 提供支持

地址： https://github.com/adithya-s-k/omniparse

MinerU

MinerU 是一个开源的高质量数据提取工具，支持多种文件格式

MinerU 是一个一站式、开源的高质量数据提取工具，主要包括以下两个核心功能模块：

功能介绍：Magic-PDF 能将 PDF 文档转换为 Markdown 格式，可以处理本地存储或支持 S3 协议的对象存储中的文件。

主要特色：

支持多种前端模型输入
自动去除页眉、页脚、脚注和页码
保留文档原有的结构和格式，包括标题、段落、列表等
提取并显示图片和表格
将公式转换为 LaTeX 格式
自动检测和转换乱码 PDF 文档
兼容 CPU 和 GPU 环境
可在 Windows、Linux 和 macOS 平台上使用

地址： https://github.com/opendatalab/MinerU

参考资料

六个开源的PDF转Markdown项目

MarkItDown：微软开源的文档转 Markdown 工具及其在 LLM 时代的应用

PDF电子书制作工具

Thu, 05 Feb 2026 12:34:25 -0800

PDF电子书制作工具

前言

本文介绍一些PDF电子书制作工具。

MdBook-PDF

简介

用 Rust 编写的 mdBook 后端，基于headless chrome和Chrome开发工具协议生成PDF。

mdbook-pdf——中文说明

mdbook-theme

博客

安装和使用

由于它是 mdBook 的插件（后端），首先您应该确保 mdbook 可用。

如果您的计算机的架构为x86_64，或者ARM64版本的Linux，请检查成功的build GitHub Actions workflows/release，单击最新的一次运行记录，然后您可以从 Artifacts中获取二进制文件（包括 Windows、Linux、macOS）。

否则，确保 rust 编译环境可用，执行cargo install mdbook-pdf编译安装即可。

如果需要最新版的编译二进制文件，请确保 Rust 编译环境可用（cargo build），运行 cargo install --git https://github.com/HollowMan6/mdbook-pdf.git，或者，您可以克隆存储库并自行编译。（执行git clone https://github.com/HollowMan6/mdbook-pdf.git，在然后在克隆下来的文件夹中运行cargo build --release，在target/release/中获取可执行文件，并将其放入PATH）

为了使得程序能够正常运行，请确保计算机上在运行本程序之前已经安装了 Google Chrome / Chromium / Microsoft Edge，（安装在默认的位置，在当前的PATH中，或配置了二进制文件位置）。如果没有安装，并且程序启用了fetch功能(默认未开启，需使用cargo install mdbook-pdf --features fetch重新编译开启)，程序将会尝试自动下载 Chromium 浏览器并运行（注意：如在Linux中使用可能会存在chromium依赖不满足/非x86_64无法适配的问题）。

在Windows 10及以上该程序无需安装任何额外软件即可正常生成 PDF，因为 Microsoft Edge 是 Windows 系统自带的浏览器。当然如果考虑到对没有自带安装 Edge 的老版本Windows的支持，在电脑上安装一个 Google Chrome 即可。
在 macOS 中需要下载并安装 Google Chrome 或者 Microsoft Edge 或者 Chromium。
在 Linux 中安装Google Chrome / Chromium / Microsoft Edge 浏览器中的任意一个即可，推荐安装 Chromium，该软件包在您的发行版中一般名称为 chromium 或 chromium-browser（注意，在 Ubuntu 18.04 之后需要通过 snap 安装 chromium-browser）。

请确保您的book.toml中存在以下内容:

1
2
3


[output.html]

[output.pdf]

而且，[output.html.print]也没有被禁用（默认情况下应该是启用的，所以如果您的book.toml中没有出现以下行，请不要担心）。

1
2


[output.html.print]
enable = true

一个最简单的book.toml文件示例如下：

1
2
3
4
5
6


[book]
title = "An Example"

[output.html]

[output.pdf]

最后，您可以使用 mdbook build 命令生成书籍并获取PDF文件，您的PDF文件将被存放在book/pdf/output.put。

配置

支持自定义PDF纸张方向、页面缩放比例、纸张宽度和高度、页面边距、生成的PDF页面范围、是否显示页眉和页脚以及自定义其格式等。

示例配置文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


[book]
authors = ["Hollow Man"]
language = "en"
src = "src"
title = "An Example"

[output.html]

[output.pdf]
## Set for auto-retrying if failed to generate PDF.
# trying-times = 1
## Set the timeout in seconds.
# timeout = 600
## This backend only support latest Chromium based browsers, not Safari and Firefox currently.
## If needed, please specify the full path.
## If you specify the wrong binary, chances are that there will be a timeout error.
# browser-binary-path = ""
## Assign the static hosting site url so that relative links outside the book can be fixed.
# static_site_url = "https://rust-lang.github.io/mdBook"
## Set the theme to be applied for the generated PDF.
# theme = "ayu"
## Check Chrome Devtools Protocol Docs for the explanation of the following params:
## https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-printToPDF
landscape = false
display-header-footer = true
print-background = true
scale = 0.7
paper-width = 8
paper-height = 10
margin-top = 0.5
margin-bottom = 0.5
margin-left = 0.5
margin-right = 0.5
page-ranges = ""
ignore-invalid-page-ranges = false
header-template = "<h3 style='font-size:8px; margin-left: 48%' class='title'></h3>"
footer-template = "<p style='font-size:10px; margin-left: 48%'><span class='pageNumber'></span> / <span class='totalPages'></span></p>"
prefer-css-page-size = true
generate-document-outline = false
generate-tagged-pdf = true

[output.pdf-outline]
like-wkhtmltopdf = true

查看 book.toml 以了解 [output.pdf] 可用配置的详细信息。

具体参数详解：

trying-times

接受输入一个整型数，默认为1。其指定假如发生PDF生成失败的情况重试的次数。

browser-binary-path

接受输入一个字符串，默认为空''，程序自动判断路径。其指定浏览器可执行文件路径。

本程序支持最新的基于Chromium的浏览器，不支持Safari和Firefox。如果你需要指定，请指定完整的路径，比如说/usr/bin/foo。如果指定了错误的可执行文件，则很可能会出现超时错误或者直接报错。

static-site-url

接受输入一个字符串，默认为空''。其指定书的静态网站托管URL，从而修复书之外的相对链接，将其转换为绝对路径。

landscape

接受输入一个布尔值，默认为false。其指定PDF纸张方向，true为横向，false为纵向。

display-header-footer

接受输入一个布尔值，默认为false。其指定是否显示页眉和页脚，true为显示，false为不显示。

print-background

接受输入一个布尔值，默认为false。其指定是否在PDF中显示背景图片，true为显示，false为不显示。

theme

接受输入一个字符串。其指定用于打印书的主题。

scale

接受输入一个数字，默认为1。其指定缩放因子，例如指定值为1.25，则将页面缩放125%。

paper-width

接受输入一个数字，默认为8.5。其指定页面宽度的英尺数，如果需要使用A4纸请将此值设为8。

paper-height

接受输入一个数字，默认为11。其指定页面高度的英尺数，如果需要使用A4纸请将此值设为10。

margin-top

接受输入一个数字，默认为1。其指定页面上边距的厘米数。

margin-bottom

接受输入一个数字，默认为1。其指定页面下边距的厘米数。

margin-left

接受输入一个数字，默认为1。其指定页面左边距的厘米数。

margin-right

接受输入一个数字，默认为1。其指定页面右边距的厘米数。

page-range

接受输入一个字符串，默认为空''，即不截取PDF页面。其指定生成PDF文件页面截取范围，支持指定常见打印机格式页面范围，如'1-5, 8, 11-13'则是将第1到5页以及第8页和第11到13页截取出来生成。

ignore-invalid-page-ranges

接受输入一个布尔值，默认为false。其指定，如果上面指定的PDF文件页面截取范围格式正确，但是实际无法按照语义执行，是否忽略。true为忽略，生成全部PDF页面，false为进行报错，如在指定3-2这种情况下将会报错，PDF生成失败。

header-template

接受输入一个字符串。其指定PDF文件页眉的HTML模板。其值应该是一个有效的HTML标记，并使用以下类从而将对应值插入其中：

date: 格式化后的PDF生成日期
title: 书的标题
url: PDF文件存放路径
pageNumber: 当前页号
totalPages: 总共页数

例如，'<span class=title></span>' 将生成一个包含标题的页眉。

footer-template

接受输入一个字符串。其指定PDF文件页脚的HTML模板。其值的格式同header-template。

prefer-css-page-size

接受输入一个布尔值，默认为false。其指定是否使用 CSS 定义的页面大小。true为使用，false时页面将通过缩放来适应纸张大小。

generate-document-outline

接受输入一个布尔值，默认为true。其指定是否根据网页生成PDF目录。

generate-tagged-pdf

接受输入一个布尔值，默认为true。其指定是否根据网页生成PDF标记。

常见问题

让mdbook-pdf支持火狐！目前，尽管 Puppeteer 根据其文档，已经支持类似于Chrome 开发工具协议 Page.printToPDF的东西，rust-headless-chrome 并没有。
链接损坏！

我已经提交了一个 mdBook 的拉取请求，该拉取请求通过将打印页面 (print.html) 上的链接指向打印页面上的锚点来解决此问题，但尚未合并。您可以尝试我的拉取请求分支以使其正常工作。在最新的 mdbook (v0.5.0+) 中已经修复。

如果你的书中有书以外的相对路径链接，请提供静态网站托管URL以便修复。

~~可以像wkhtmltopdf支持的那样，在PDF中添加书签来反映目录吗？~~

这已经由 Chromium 实现，现在，在v0.1.11+中，您可以通过generate-document-outline选项控制。

[!NOTE] 如果您不喜欢 Chromium 的实现方案，我们还自己实现了对PDF文件书签/大纲的支持（mdbook-pdf-outline）。它是mdbook的另一个后端，用Python编写，应与mdbook-pdf 一起使用。

您可以通过pip install mdbook-pdf-outline安装此后端。

记住将以下内容放在book.toml的 末尾，[output.pdf]之后，并禁用generate-document-outline选项：
1
2
3
generate-document-outline = false

[output.pdf-outline]
如果您希望使PDF目录与wkhtmltopdf生成的目录相同（根据标题生成条目），则则无需进一步修改book.toml：

如果您想使PDF目录与print.html页面中显示的目录相同，可以通过在book.toml中禁用like-wkhtmltopdf选项（注意：此功能只在mdbook v0.5.0 之前修复了print.html中损坏链接的旧版mdbook版本可用，你可以通过 cargo install --git https://github.com/HollowMan6/mdBook mdbook安装。
1
2
3
4
generate-document-outline = false

[output.pdf-outline]
like-wkhtmltopdf = false
最后，您可以在book/pdfoutline/output.pdf中找到带有大纲/目录的版本。

在 mdbook-pdf 所遵循的 Markdown 源中强制分页！

参考#9，您可以使用以下语法在markdown源中强制分页：

1
2


<div style="page-break-before:always">&nbsp;</div>
<p></p>

无法在 mdbook-pdf 中将我的书呈现为 PDF！

如果您能将它报告给问题跟踪器，并提供mdbook-pdf渲染时产生的所有跟踪，以及book.toml配置文件，和书的仓库地址（如果有的话），将不胜感激。

1

RUST_BACKTRACE=full RUST_LOG=trace mdbook build

Typora

Typora-China指南

Typora 支持你将当前文档导出为 PDF、HTML、HTML（无样式）和图像格式。

更多的格式（如 Word、RTF 等）通过 pandoc (opens new window)，在你 install pandoc (opens new window)，这些格式都支持开箱即用。

你可以从 文件 → 导出 命令的菜单栏中访问导出命令。

使用wkhtmltopdf从HTML生成PDF

在本文中，我们将介绍如何使用wkhtmltopdf工具从HTML文件生成PDF文件。wkhtmltopdf是一个开源的命令行工具，它可以将HTML转换为PDF，并保留HTML文档的结构和样式。

安装wkhtmltopdf

要使用wkhtmltopdf工具，首先需要在您的系统上安装它。wkhtmltopdf是一个跨平台的工具，可以在Linux、Windows和MacOS上使用。

在Linux上安装wkhtmltopdf，您可以执行以下命令：

1

sudo apt-get install wkhtmltopdf

在Windows上安装wkhtmltopdf，您可以从官方网站下载可执行文件，并按照安装向导进行安装。

使用wkhtmltopdf生成PDF

安装完成后，您可以使用以下命令从HTML文件生成PDF文件：

1

wkhtmltopdf input.html output.pdf

您可以使用--page-size参数来指定生成的PDF文件的页面大小。以下是一些常用的页面大小：

A4
Letter
Legal
A5
A3

您可以使用--orientation参数来指定页面的方向。可以选择的方向有Landscape和Portrait。

例如，以下命令将生成一个A4大小、纵向排列的PDF文件：

1

wkhtmltopdf --page-size A4 --orientation Portrait input.html output.pdf

包含页眉和页脚

您可以使用--header-html和--footer-html参数来为PDF文件添加自定义的页眉和页脚。您可以指定一个HTML文件作为页眉和页脚的模板。

例如，以下命令将为PDF文件添加一个名为header.html的页眉模板和一个名为footer.html的页脚模板：

1

wkhtmltopdf --header-html header.html --footer-html footer.html input.html output.pdf

设置页面边距

您可以使用--margin-top、--margin-right、--margin-bottom和--margin-left参数来设置PDF文件的页面边距。

例如，以下命令将设置PDF文件的上、右、下和左边距为1英寸：

1

wkhtmltopdf --margin-top 1in --margin-right 1in --margin-bottom 1in --margin-left 1in input.html output.pdf

添加目录

您可以使用--toc参数来为PDF文件添加目录。

例如，以下命令将为PDF文件添加目录：

1

wkhtmltopdf --toc input.html output.pdf

在本文中，我们介绍了如何使用wkhtmltopdf工具从HTML文件生成PDF文件。您可以安装并使用这个开源工具来生成高质量的PDF文件，同时保留HTML文档的结构和样式。无论您是在Linux、Windows还是MacOS上工作，wkhtmltopdf都是一个强大而方便的工具。

中文古籍刻本風格直排電子書製作工具vRain

中文古籍刻本風格直排電子書製作工具 Chinese Ancient eBooks Generator

vRain is

vRain是该復刻計劃的主要工具，此外還有古籍印章製作工具 vYinn殷人、古棋譜製作工具 vQi 、古籍掃描圖像變形糾正工具vModou墨斗以及其他傳統文化文創工具，如天地人三才傳統曆法筆記本 v3Cai等。
vRain是一款面向讀者的中文古籍刻本風格直排電子書製作工具。
參考中文古籍雕版刻本製作過程，首先生成書葉背景圖，根據行數、每行字數形成一個自右向左、自上而下的位置數組，然後把文本逐字打印到對應位置，打滿一頁、新建一頁，直到所有文字處理完。
文本編輯準備和自動排版生成分離，使用者將主要精力用在文本編輯準備。
一個背景圖對應一個配置文件。一本書對應一個配置文件。
百萬字書籍十幾分鐘生成。
採用Perl語言開發，需安裝Image::Magick和PDF::Builder等模塊。
作者小紅書主頁：兀雨書屋。

基本功能

書葉背景圖的書房名、尺寸、列數、框線粗細及顏色均可配置。支持單雙、順對、黑白魚尾。
支持生成宣紙做舊風格、竹簡風格的背景圖。
支持批注文字小字雙排。正文、批注文字的字體、大小、顏色、位置可配置。
正文文字、批注文字、標點符號的上、下、左、右位置均可微調以達到最佳呈現效果。
一主多輔字體，主字體不支持時自動採用輔字體補字。某字符主字體不支持時，可嘗試簡繁轉換以改善支持情況，但可能產生與語境不符問題。
標點符號替換規則、過濾規則可配置。標點符號可歸一化為句號，僅用於句讀。常用標點符號可設置為不佔字符位置，頁面文字更緊湊，貼近古籍刻本風格。
書名號、單雙引號直排旋轉九十度。書名號可調整為側邊線。
根據文本序號自動生成PDF目錄，如第x回、卷x。
保留字符：’@‘代表空格，’【】‘內代表雙排批注文字，’%‘代表換葉符，’$‘代表換頁符（半葉），’&‘代表下行文字居葉末，文本行首’S+數字’代表整段縮幾個字符（需indentxt腳本做預處理）。

PPT转PDF并合并

Spire.Presentation for Python 是一个强大的 API，用于在 Python 应用中处理 PowerPoint 演示文稿。它使开发者能够创建、编辑、转换和保存演示文稿，而无需使用 Microsoft PowerPoint。Spire.Presentation for Python 提供幻灯片管理、文本和图像处理、图表创建和水印等功能，提供高效的演示处理综合工具包。

它支持流行的演示文件格式，如PPT、PPS、PPTX和ppsx，并且允许格式间的便捷转换。开发者可以将演示文稿导出为图片、PDF、HTML、XPS 和 SVG 文件。凭借用户友好的界面和丰富的功能，Spire.Python演示使开发者能够轻松提升Python应用中的PowerPoint演示能力。

转换示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


from spire.presentation import *
from spire.presentation.common import *

# Create an object of Presentation class
presentation = Presentation()

# Load a presentation file
presentation.LoadFromFile("Sample.pptx")

# Convert the presentation file to PDF and save it
presentation.SaveToFile("output/PresentationToPDF.pdf", FileFormat.PDF)
presentation.Dispose()

参考资料

https://github.com/Krasjet/pdf.tocgen

https://zhuanlan.zhihu.com/p/137469275

https://geek-docs.com/html/html-ask-answer/648_html_calling_wkhtmltopdf_to_generate_pdf_from_html.html

https://github.com/HollowMan6/mdbook-pdf/blob/main/README_CN.md

https://github.com/lookscanned/lookscanned.io

脑机接口资源汇总

Mon, 02 Feb 2026 12:34:25 -0800

脑机接口资源汇总

简介

脑机接口资源汇总

来源：https://www.zhuanzhi.ai/topic/2001714772134661/awesome

更新时间2022.2.14

涵盖脑机接口：白皮书、国内外技术报告、最新综述论文、关键技术最新论文、数据集、课程讲解PPT及视频等。

中文教程资料

Brduino脑机接口技术答疑——博客

白皮书

2021.7，《脑机接口技术在医疗健康领域应用白皮书》，73页，中国信息通信研究院，http://www.caict.ac.cn/kxyj/qwfb/ztbg/202107/t20210715_380509.htm 中国电子技术标准化研究院
2021.6，《脑机接口标准化白皮书》，118页，中国电子技术标准化研究院，http://nits.org.cn/UploadFile/xbw/File/%E8%84%91%E6%9C%BA%E6%8E%A5%E5%8F%A3%E6%A0%87%E5%87%86%E5%8C%96%E7%99%BD%E7%9A%AE%E4%B9%A6%EF%BC%882021%E7%89%88%EF%BC%89.pdf

技术标准

2020.2，“STANDARDS ROADMAP:NEUROTECHNOLOGIES FOR BRAIN-MACHINE INTERFACING”（脑机接口神经技术标准路线图），IEEE标准协会，100页，https://standards.ieee.org/wp-content/uploads/import/documents/presentations/ieee-neurotech-for-bmi-standards-roadmap.pdf

报告

【脑接机口入门介绍】不同可用技术的介绍，BCI所需的主要组件和步骤，安全和伦理问题，以及该领域未来的概述。http://learn.neurotechedu.com/introtobci/#references
74页脑机接口入门介绍PPT！及值得关注的20家商业公司介绍，“AN INTRODUCTION TO THE BRAIN-COMPUTER INTERFACE (BCI) AND COMPANIES WORKING ON IT”，https://www.uc.edu/content/dam/refresh/cont-ed-62/olli/olli_docs/brain-computer-interfaces.pdf
加州大学圣地亚哥分校，“Principles and Applications of Brain-Computer Interfaces”（脑机接口原理与应用），60页入门介绍PPT，https://cfmriweb.ucsd.edu/ttliu/be280a_12/BE280A12_BCI1.pdf
2021.5，中国电子学会，《2021年全球脑科学发展发展报告》，42页，对脑科学进行现状分析、路径总结和趋势研判。http://www.uthinktank.com/news/media/2021-06-09/2021BrainScience.pdf
2020.8.27，美国兰德公司，《脑机接口：美国军事应用及其含义的初步评估》，45页。该报告评估了BCI技术的军事用途及其对未来战士的潜在影响；探讨大范围部署BCI技术可能带来的机构漏洞，以及有效管理该技术的风险和政策考虑；分析美国防部开发和采用BCI技术的潜在道德和法律风险等。Brain-Computer Interfaces: U.S. Military Applications and Implications, An Initial Assessment
2021.11.23，美国兰德公司，《提高人类能力的技术途径》，111页。本报告对生成人类性能提升（HPE）的三种可能方式进行了综述：基因编辑、人工智能、身体互联网（IoB）方法，其中植入或佩戴在人体中的设备连接到网络。本报告所讨论的一些技术尚处于萌芽阶段，但发展速度难以预测，本报告提供了技术领域状态的预测。 https://www.rand.org/pubs/research_reports/RRA1482-2.html
2021.5.13，英国国防部，《人类增强-一个新的范例战略意义项目的黎明》（Human Augmentation – The Dawn of a New Paradigm Strategic Implications Project），阐述人类增强（HA）技术对未来的影响。https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/986301/Human_Augmentation_SIP_access2.pdf
2021.8.10，量子位智库，《脑机接口深度产业分析报告（精华版）》，12页，https://www.qbitai.com/2021/08/27535.html
2021.12，头豹科技，《2021中国脑机接口平台行业概览》，41页， https://pdf.dfcfw.com/pdf/H3_AP202201121539917091_1.pdf?1641976029000.pdf
2021.12，蛋壳研究院，《脑机接口+医疗健康行业研究报告》，55页， https://www.dx2025.com/wpcontent/uploads/2022/02/research_report_on_brain_computer_interface_medical_and_heal.pdf

学位论文

2007年，清华大学工学博士学位论文180页《基于节律调制的脑－机接口系统 —从离线到在线的跨越》，https://sccn.ucsd.edu/~yijun/pdfs/THESIS07.pdf

综述（入门）

基础理论

2021.10，中国医学科学院北京协和医学院生物医学工程研究所，“脑机接口技术发展新趋势——基于2019—2020年研究进展”,10页。摘要：概述了2019—2020年脑机接口领域在硬件、算法、范式、应用等方面取得的重要研究进展和发生的热点事件,展望了未来脑机接口技术的发展趋势。论文源链接：http://www.kjdb.org/CN/abstract/abstract16531.shtml
2021.2.25，澳大利亚阿德莱德大学、孟加拉国联合国际大学，Progress in Brain Computer Interface: Challenges and Potentials。摘要：这篇综述总结了过去几十年脑机接口领域的最新进展，并强调了关键挑战。论文源链接：https://www.frontiersin.org/articles/10.3389/fnsys.2021.578875/pdf
2021.1.19，澳大利亚塔斯马尼亚大学、华中科技大学等，Xiaotong Gu，Peng Xu等，EEG-based Brain-Computer Interfaces (BCIs): A Survey of Recent Studies on Signal Sensing Technologies and Computational Intelligence Approaches and Their Applications。摘要：综述了脑机接口应用中脑电信号传感技术和计算智能方法的最新文献，以弥补过去五年系统总结中的空白。具体而言，我们首先回顾了用于收集可靠EEG信号的BCI和信号传感技术的现状。然后，我们展示了最先进的计算智能技术，包括机器学习和深度学习算法中的模糊模型和转移学习，以检测、监控和维护人类认知状态和任务在各普遍应用中的性能。最后，我们介绍了一些创新的BCI启发的医疗保健应用，并讨论了基于EEG的BCI研究的未来研究方向。论文源链接：https://arxiv.org/pdf/2001.11337.pdf 数据集：https://bcmi.sjtu.edu.cn/home/seed/index.html
2021.6.26，印度巴特那国立理工学院，RakeshRanjan等，Ocular artifact elimination from electroencephalography signals: A systematic review。摘要：本文试图对消除最常见的伪影之一——眼部伪影的方法学进展作一粗略概述。期望通过对记录脑电信号的仿真模型验证，对现有的所有眼部伪影消除技术的研究有所启发。在未来的进展中，伪影消除技术中的标准规范有望在从无伪影脑电信号中获得正确信息后，通过证实临床诊断来减轻神经科医生的负荷。论文源链接：https://www.sciencedirect.com/science/article/abs/pii/S0208521621000838?via%3Dihub
2021.1.8，意大利马尔凯理工大学，Nibras Abo Alzahab等，Hybrid Deep Learning (hDL)-Based Brain-Computer Interface (BCI) Systems: A Systematic Review。摘要：综述了2015年至2020年间发表的47篇将hDL应用于 BCI系统的论文，以提取研究趋势并突出该主题的相关方面。调查表明，hDL被常用来处理脑电图（EEG）。EEG数据的信噪比（SNR）较低（因此必须对该数据进行预处理），但我们发现预处理仅有21.28%研究论文使用，这表明hDL似乎能够克服脑电图数据的这一固有缺点。时间特征似乎是最有效的，准确率为 93.94%，而时空特征的使用率最高，有33.33% 的研究论文使用。最常用的架构是卷积神经网络-循环神经网络 CNN-RNN，占47%。此外，50%的研究使用较少的层数来实现网络复杂性和计算效率之间的良好折衷。论文源链接：https://www.mdpi.com/2076-3425/11/1/75/htm
2021.5.28，韩国大学，Wonjun Ko等，A Survey on Deep Learning-Based Short/Zero-Calibration Approaches for EEG-Based Brain–Computer Interfaces。摘要：在这项研究中，我们回顾了基于DL的BCI短/零校准方法。此外，我们阐述了方法/算法趋势，突出了文献中有趣的方法，并讨论了进一步研究的方向。特别是，我们寻找基于生成模型和基于几何操作的DA方法。此外，我们将基于DL的BCI中的TL技术分为显式和隐式方法。我们系统化揭示了DA和TL方法的进步。在此处综述研究中，约45%的DA研究使用基于生成模型的技术，而约45%的TL研究使用显式知识转移策略。此外，根据我们的文献综述，我们为基于DL的BCI推荐了适当的DA策略，并讨论了基于DL的BCI中使用的TL的趋势。论文源链接：https://www.frontiersin.org/articles/10.3389/fnhum.2021.643386/full

民用

2021.8，孟加拉商业科技大学,M. F. Mridha等，Brain-Computer Interface: Advancement and Challenges。摘要：本研究对BCI领域进行了全面概述,阐述BCI的多个应用。然后，简明地解释了BCI系统的每个元素。此外，还附上了对BCI中使用的技术或硬件（主要是传感器）的简要概述。最后，本文调查了BCI的几个未解决的挑战，并用可能的解决方案解释了它们。论文源链接：https://www.mdpi.com/1424-8220/21/17/5746/htm
2021.10，印度拉贾斯坦邦理工学院，Varun Kohli, Vinay Chamola等，A Review on Virtual Reality and Augmented Reality Use-Cases of Brain Computer Interface Based Applications for Smart Cities。摘要：这篇综述深入研究了BCI和XR技术，并举例说明了它们的组合如何产生与上述应用有关的有希望的结果。它详细讨论了BCI、VR和AR技术的背景及其各自的应用。然后，讨论了将这些技术用于智慧城市中各种现实生活应用。此外，我们还介绍了使用BCI和XR技术组合的未来应用范围。论文源链接：https://www.researchgate.net/publication/355789243_A_Review_on_Virt ual_Reality_and_Augmented_Reality_Use-Cases_of_Brain_Computer_Interface_Based_Applications_for_Smart_Cities/link/617e3600eef53e51e10c535c/download
2021.9，美国范斯坦医学研究所，Historical perspectives, challenges, and future directions of implantable brain-computer interfaces for sensorimotor applications。摘要：探讨了脑机技术面临的挑战、历史观点以及临床研究参与者的显著成就。论文源链接：https://bioelecmed.biomedcentral.com/track/pdf/10.1186/s42234-021-00076-6.pdf
2021.7，伦敦帝国理工学院，Mind the gap: State-of-the-art technologies and applications for EEG-based brain–computer interfaces 摘要：在这篇文章中，回顾了可穿戴生物传感的最新技术，重点是开发用于长期和无创EEG监测的新型电极接口。对市售EEG平台进行了调查，并根据它们为eBCI开发提供的好处和局限性进行了比较分析。讨论了神经科学研究中的新兴应用以及与广泛实施eBCI用于医疗和非医疗用途相关的未来趋势。最后，对与这种日益普及的技术相关的伦理、社会和法律问题进行了评论，并提供了解决与主流消费者采用相关的关键问题的一般建议。论文源链接：https://aip.scitation.org/doi/pdf/10.1063/5.0047237
2021.6.24，哥伦比亚教育技术大学软件研究小组，Daniela Camargo-Vargas等，Brain-Computer Interfaces Systems for Upper and Lower Limb Rehabilitation: A Systematic Review。摘要：本文是对BCI用于人体上下肢康复的发展现状和机遇的系统综述。论文源链接：https://www.mdpi.com/1424-8220/21/13/4312
2021.1.15，爱尔兰都柏林三一学院，Simon Colin，Challenges and Opportunities for the Future of Brain-Computer Interface in Neurorehabilitation。摘要：我们提供了关于阻碍BCI可扩展性的因素的当代观点。此外，我们提供了技术优化设计的未来展望，以最好地利用其独特的潜力，以及研究和报告发现的最佳实践。论文源链接：https://www.frontiersin.org/articles/10.3389/fnins.2021.699428/full
2021.8.13，法国巴黎凯捷工程公司，Khalida Douibi等，Toward EEG-Based BCI Applications for Industry 4.0: Challenges and Possible Applications。摘要：在当前的研究中，我们进行了详细的文献回顾，以调查与未来工业4.0的BCI应用程序部署相关的主要挑战和提出的标准。论文源链接：https://www.ncbi.nlm.nih.gov/pmc/articles/PMC8414547/

军用

2021.3.30，波兰奥波莱工业大学，Adrian Czech，Brain-Computer Interface Use to Control Military Weapons and Tools。摘要：本文考虑了脑机接口（BCI）技术对建立军事利益的影响因素。BCI技术仍处于发展状态，本文主要提供对不久的将来的预测。论文源链接：https://link.springer.com/chapter/10.1007/978-3-030-72254-8_20
2021.2.18，丹麦皇家国防学院，Katrine Nørgaard，Cyborgs, Neuroweapons, and Network Command。摘要：本文将探索新兴军事神经技术领域及其挑战战争边界的方式。论文源链接：https://sjms.nu/articles/10.31374/sjms.86/

关键技术（进阶）

硬件

2021.2，韩国高等科学技术研究院，Netiwit Kaongoen等，Speech-imagery-based brain–computer interface system using ear-EEG，Journal of Neural Engineering（国际神经工程领域顶级期刊）。摘要：调查了以用户耳朵为中心的脑电图（ear-EEG）在基于语音图像的脑机接口（BCI）系统中的功效，开发了一种可穿戴式入耳式脑电图采集工具。实验结果表明，耳脑电图作为语音图像监测的头皮脑电图采集方法的替代方案具有巨大的潜力。所提议系统中语音图像和耳脑电图采集的优点和可行性将加速BCI系统在日常生活中的发展。这是第一项在基于语音图像的BCI中调查耳脑电图性能的研究，成果发表于国际神经工程领域顶级期刊Journal of Neural Engineering。论文源链接：https://iopscience.iop.org/article/10.1088/1741-2552/abd10e/meta

算法

2021.11.11，美国麻省理工学院、哈弗医学院，Maryam M Shanechi等，Neural population partitioning and a concurrent brain-machine interface for sequential motor function，（Nature Neuroscience）摘要：许多自然任务涉及复杂运动目标，需要在执行之前规划此类运动的完整序列，为此开发了一种脑机接口技术，可以在运动之前同时解码完整的运动序列脑信号，然后可以根据需要准确地执行动作。论文源链接：https://www.nature.com/articles/nn.3250
2020.1.24，天津大学，Enhance decoding of pre-movement EEG patterns for brain–computer interfaces（被英国物理学会出版社（IOP Publishing）授予“CHINA TOP cited paper award 2021”，旨在表彰发表的最具影响力的论文）。摘要：针对从脑电图中解码自愿手指预运动这一BCI挑战难题，在分析时域和频域中的运动前脑电图特征，设计了一种有效的方法来解码运动相关的模式。使用判别规范模式匹配（DCPM）和公共空间模式（CSP）提取运动相关皮层电位（MRCP）和事件相关去同步化（ERD）特征，然后分别用两个fisher判别分析分类器对这两类特征进行分类。实验结果表明，运动前的MRCP和ERD特征包含显着的判别信息，它们相互补充，因此可以用DCPM和CSP组合方法去很好地识别。本研究为运动前脑电图模式的解码提供了一种很有前景的方法，这对脑机接口的发展具有重要意义。论文源链接：https://pubmed.ncbi.nlm.nih.gov/31747642/
2021.11，芬兰图尔库大学、沙特阿拉伯埃法特大学，Abdulhamit Subasi，The Ensemble Machine Learning-Based Classification of Motor Imagery Tasks in Brain-Computer Interface。摘要：设计了一种新方法来自动识别运动图像（MI）任务。该方法基于多尺度主成分分析（MSPCA）、小波包分解（WPD）、子带统计特征提取和基于集成学习的分类器的有效混合，对 MI 任务进行分类。通过测试，集成学习方法分别产生了98.69%和94.83%的最高分类准确率。论文源链接：https://www.hindawi.com/journals/jhe/2021/1970769/
2021.10，英国布里斯托大学，Joseph Pemberton等，Cortico-cerebellar networks as decoupling neural interfaces。摘要：引入解耦神经接口（DNI）作为深度网络中前向和反馈锁定问题的解决方案。引入了一个系统级模型，其中循环皮层网络从小脑模块接收在线时间反馈预测。在许多已被证明依赖于小脑的感觉运动（线条和数字绘图）和认知任务（模式识别和字幕生成）上测试了这种皮质-小脑循环神经网络（ccRNN）模型。ccRNN 有助于学习，同时减少类似共济失调的行为。该工作为小脑作为一种全脑解耦机器提供了一个新的视角，用于有效的可信度赋值，并在深度学习和神经科学之间开辟了一条新途径。论文源链接：https://arxiv.org/pdf/2110.11501.pdf
2021.3，英国帝国理工学院，Pablo Ortega等，HemCNN: Deep Learning enables decoding of fNIRS cortical signals in hand grip motor tasks。摘要：使用数据驱动方法卷积神经网络架构HemCNN解决fNIRS左/右手力解码问题。通过测试HemCNN学会了检测哪只手以1Hz 的自然手部动作速度执行抓握，优于标准方法。由于HemCNN不需要基线校正，并且卷积操作对时间平移是不变的，因此该方法可以帮助为各种实时任务解锁fNIRS。移动脑成像和移动脑机接口可以从中受益。论文源链接：https://arxiv.org/pdf/2103.05338.pdf
2021.11，瑞士洛桑联邦理工学院，Semih Günel, Florian Aymanns等，Overcoming the Domain Gap in Contrastive Learning of Neural Action Representations。论文源链接：https://arxiv.org/pdf/2111.14595.pdf
2021.12，瑞士洛桑联邦理工学院，Semih Günel, Florian Aymanns等，Overcoming the Domain Gap in Neural Action Representations。【6、7】摘要：开发了一种识别神经动力学和行为之间的非线性关系以计算神经表征的自我监督方法。并采用多模式数据集进行验证，结果表明该方法有望加速自我监督学习方法在神经科学中的应用。这基础之上，进一步研究了不同物种个体之间的领域差距下通用模型训练这一难题，使用个体3D姿势数据来指导神经动作表征的编码，在训练期间，在似乎执行相似动作的动物之间交换神经和行为数据。通过在三个非常不同的多模式数据集上测试了方法：一个以苍蝇及其神经活动为特征，一个包含人类神经皮层电图（ECoG）数据，最后是从不同角度观察人类活动的RGB视频数据。论文源链接：https://arxiv.org/pdf/2112.01176.pdf
2021.6，美国斯坦福大学，Eric M. Trautmann, Daniel J. O’Shea等，Dendritic calcium signals in rhesus macaque motor cortex drive an optical brain-computer interface。摘要：展示了一种植入物和成像系统，能够对从事运动任务的猕猴神经元钙信号进行慢性、运动稳定的双光子成像。并基于此开发了一种由这些树突信号驱动的光学BCI（oBCI），它成功地在线解码了运动方向。这种方法为通过双光子成像研究运动控制和设计BCI创造了新的机会。论文源链接：https://www.nature.com/articles/s41467-021-23884-5.pdf 代码：https://github.com/djoshea/obci 数据集：https://datadryad.org/stash/dataset/doi:10.5061/dryad.cnp5hqc4k
2021.11，瑞士洛桑联邦理工学院，Vahid Salari, Serafim Rodrigues等，Are Brain-Computer Interfaces Feasible with Integrated Photonic Chips? 摘要：研究了一种全新的脑机接口（BCI）。光谱的可见光和近红外部分内或附近有一些来自神经元的超弱光子发射（UPE），其反映了细胞（和身体）的氧化状态，UPE强度与神经活动、EEG活动、脑血流量、脑能量代谢和谷氨酸释放之间存在直接关联。基于此作者提出了一种使用UPE的新型颅骨植入BCI。建议安装在头骨内表面的光子集成芯片可以实现从UPE信号中提取相关特征的新形式。在当前的技术格局中，光子技术因其独特的优势，例如小型化、高速、低热效应和大集成能力，可实现高产量，而迅速发展并有望超越许多电气技术，量产，成本更低。论文源链接：https://arxiv.org/pdf/2112.01249.pdf
2021.11，美国南加州大学，Shixian Wen等，Rapid adaptation of brain–computer interfaces to new neuronal ensembles or participants via generative modelling。摘要：针对神经信号映射到动作，训练数据缺失的问题，通过AI生成模型的开发和使用，从学习的数据分布中合成几乎无限数量的新数据，该模型进而通过学习手部运动学和相关神经尖峰序列之间的映射。该模型可以合成新的尖峰训练，加速训练并提高BCI解码器的泛化能力。该方法完全由数据驱动，因此适用于运动控制以外的BCI应用。论文源链接：https://www.nature.com/articles/s41551-021-00811-z 代码：https://github.com/shixianwen/Rapid-transfer-of-brain-machine-interfaces-to-new-neuronal-ensembles-or-participants 数据集：https://github.com/shixianwen/Rapid-transfer-of-brain-machine-interfaces-to-new-neuronal-ensembles-or-participants
2021.4，美国卡耐基梅隆大学、明尼苏达大学，James R. Stieger，Continuous sensorimotor rhythm based brain computer interface learning in a large population。摘要：发布了收集的大型纵向数据集，该数据集是迄今为止公开可用的最大和最复杂的SMR-BCI数据集之一，有助于开发新的 BCI 控制算法。论文源链接：https://www.nature.com/articles/s41597-021-00883-1.pdf 代码：https://github.com/bfinl/BCI_Data_Paper. 数据集：https://doi.org/10.6084/m9.figshare.13123148
2021.11，瑞士苏黎世理工学院，Ard Kastrati等，EEGEyeNet: a Simultaneous Electroencephalography and Eye-tracking Dataset and Benchmark for Eye Movement Prediction。摘要：提出了一个新的数据集和基准，可以帮助推进大脑活动和眼球运动交叉领域的研究。基于这个数据集，作者提出了一个基准来评估EEG测量的凝视预测。基准测试包括三个难度越来越高的任务：左右、角度幅度和绝对位置。该成果发表于AI顶会NeurIPS 2021。论文源链接：https://arxiv.org/pdf/2111.05100.pdf
2021.4，西交利物浦大学，Xuying Wang，A Hybrid Transfer Learning Approach for Motor Imagery Classification in Brain-Computer Interface。摘要：针对标记数据严重不足及受试者之间巨大个体差异，导致其他受试者的数据不能直接用于训练目标受试者的分类器这一问题，提出了一种基于数据对齐和深度迁移学习的迁移学习方法，并通过基于开放数据集的实验验证了该方法的有效性。论文源链接：https://ieeexplore.ieee.org/abstract/document/9391933 代码：https://github.com/ardkastrati/eegeyenet 数据集：https://paperswithcode.com/dataset/eegeyenet
2021.7，韩国科学技术研究院，Woo Seok Byun，Design Considerations of Linear Algebra Processor for Wearable Brain-Computer Interface System。摘要：研究了基于稳态视觉诱发电位（SSVEP）的可穿戴BCI，使瘫痪患者能够与他人交流。然而，可穿戴设备的目标识别准确率、信息传输率（ITR）等性能指标仍有待进一步提升。为此设计了基于线性代数执行目标识别算法的可穿戴脑机接口（BCI）。在目标识别算法的情况下，可以在基于单通道SSVEP的软件实现和硬件中的多通道SSVEP处理中分别考虑的信号二值化技术和候选减少技术，以降低计算复杂度。对于硬件架构设计，介绍了处理单元阵列的架构考虑，可以有效地执行各种线性代数运算。论文源链接：http://jicas.idec.or.kr/index.php/JICAS/article/view/62
2021.6，孟加拉国独立大学电气与电子工程系，Islam Md Kafiul，Probability Mapping Based Artifact Detection and Removal from Single-Channel EEG Signals for Brain-Computer Interface Applications。摘要：针对单通道脑电信号中伪迹的检测和去除问题，提出了一种新的基于四种不同统计量的伪迹检测方法：熵（一种不确定性度量）、峰度（一种峰度度量）、偏度（一种非对称性度量）和周期波形指数（一种周期性度量）。然后，提出了一种基于平稳小波变换的伪迹去除方法。该算法已应用于真实和合成数据的测试，并与其他自动化伪迹去除方法进行了比较。通过计算复杂度等多种性能指标验证了其优越的性能。论文源链接：https://www.sciencedirect.com/science/article/abs/pii/S016502702100 1849?via%3Dihub

范式

2021.6.22，日本香川大学、千叶大学，Akinari Onishi，Brain-computer interface with rapid serial multimodal presentation using artificial facial images and voice。摘要：多模态刺激引起的脑电图（EEG）信号可以驱动BCI，可以同时使用视觉和听觉刺激来提高BCI性能。日本香川大学Akinari Onishi等学者，提出了一种快速串行多模态呈现（RSMP）BCI，它结合了人工面部图像和人工语音刺激。结果表明，视听刺激提高了RSMP BCI的性能，并且P300有助于提高分类准确性。BCI在线准确率达到85.7±11.5%。论文源链接：https://arxiv.org/pdf/2102.03796.pdf
2021.3.27，希腊约阿尼纳大学，Evangelos Antoniou等，EEG-Based Eye Movement Recognition Using Brain–Computer Interface and Random Forests。摘要：提出了一种新系统，该系统利用脑机接口在眼球运动时捕获人类受试者的脑电图（EEG）信号，然后通过应用随机森林（RF）分类算法将其分为六类。所提出的随机森林脑机接口（RF-BCI）的类别是根据受试者眼睛的位置定义的：睁眼、闭眼、向左、向右、向上和向下。RF-BCI的目的是用作基于EEG的控制系统来驱动机电轮椅（康复设备）。实验结果表明，RF算法的性能优于其他方法，并且获得了6类分类的高准确率（85.39%）。论文源链接：https://www.mdpi.com/1424-8220/21/7/2339/htm
2021.6.28，伊利诺伊大学-香槟分校，Yao Li等，SSVEP-based Brain-computer Interface for Part-picking Robotic Co-worker。摘要：演示了一种基于稳态视觉诱发电位（SSVEP）的脑机接口，可以通过耳机直接将人类的认知传递给机器人。该BCI应用于一个零件采摘机器人，在操作者视觉检查零件质量的同时向机器人发送决策。输送机一侧的摄像头拍摄各部分的照片，并自动呈现给操作人员。操作者看照片时，通过BCI采集脑电图（EEG）。检查决策通过EEG中SSVEPs提取。当操作者识别出有缺陷的零件时，通过第二个摄像头将信号传达给定位有缺陷零件的机器人，并将其从输送机上取出。实验结果表明在识别和去除缺陷部分时准确率达到93% 论文源链接：https://asmedigitalcollection.asme.org/computingengineering/article-abstract/22/2/021001/1112312/SSVEP-Based-Brain-Computer-Interface-for-Part?redirectedFrom=fulltext

数据集

SEED：SJTU Emotion EEG Dataset (SEED) 是由卢宝亮教授领导的BCMI 实验室提供的脑电数据集集合。该名称继承自数据集的第一个版本，但现在我们不仅提供情感数据集，还提供警戒数据集。截至 2021 年 10 月，累计使用 SEED 的申请数量和研究机构数量分别达到 2600 多个和 770 个。 https://bcmi.sjtu.edu.cn/home/seed/index.html
DRYAD：The Dryad Digital Repository 是一个精心策划的资源，使研究数据可发现、自由重用和引用。Dryad为各种各样的数据类型提供了一个通用的家。https://datadryad.org/stash/our_mission
EEGEyeNet：EEEyeNet是一个数据集和基准，其目标是推进大脑活动和眼球运动交叉的研究。它由三个不同的实验范式中356个不同的被试的同步脑电图(EEG)和眼动(ET)记录组成。 https://paperswithcode.com/dataset/eegeyenet
BCI Competition Datasets：“脑机接口竞赛”的目标是验证脑机接口(BCI)的信号处理和分类方法。 https://paperswithcode.com/dataset/bci-competition-datasets

应用

民用

医疗健康方面

2021.6.18，美国布朗大学，John D. Simeral等，Home Use of a Percutaneous Wireless Intracortical Brain-Computer Interface by Individuals With Tetraplegia。摘要：展示了人类首次使用无线宽带iBCI，为患有肌萎缩侧索硬化、脊髓损伤或中风等神经系统疾病或损伤的个体实现了在屏幕上快速打字和点击控制平板电脑应用程序。这解决了传统需要有线电缆将神经信号从参与者大脑传输到放大器和解码计算机的弊端，iBCI可以在任何时间任何地点使用，且通信速率与有线相等。长时间无线多电极记录宽带神经信号为人类神经科学研究提供了一种宝贵的工具，并且是向瘫痪患者独立使用iBCI技术的实际部署迈出的重要一步。在家中按需访问高性能iBCI技术有望增强独立性并恢复严重运动障碍人士的沟通和行动能力。论文源链接：https://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=9390339
2021.5.21，美国匹兹堡大学、美国认知神经基础研究中心，Sharlene N. Flesher, John E Downey等，A brain-computer interface that evokes tactile sensations improves robotic arm control。摘要：用双向脑机接口诱发的触觉补充视觉，以让他们能有更接近健全人类能力的任务表现。该接口记录来自运动皮层的神经活动，并通过皮层内的体感皮层微刺激产生触觉。临床上肢评估的试验时间减少了一半，从 20.9 秒的中位时间缩短到 10.2 秒。该成果发表于Science期刊。论文源链接：https://www.science.org/doi/abs/10.1126/science.abd0380
2021，美国加利福尼亚大学，Daniel B. Silversmith, Reza Abiri, Nicholas F. Hardy等，Plug-and-play control of a brain–computer interface through neural map stabilization。摘要：研究了无需重新校准即可获得稳定性能的方法。使用了128通道慢性皮层电图（ECoG）植入物，从而可以稳定地监测患者脑信号。基于闭环解码器自适应（其中解码器权重在多天的会话中传播）实现了神经映射和“即插即用”控制的整合[48]。该成果发表于Nature Biotechnology。论文源链接：https://www.nature.com/articles/s41587-020-0662-5#author-information
2021.7.4，美国德雷塞尔大学，Mohammad Sahal等，Augmented Reality Integrated Brain Computer Interface for Smart Home Control。摘要：为患有肌萎缩侧索硬化症的人（严重的运动缺陷）设计开发了一种实用的、在家使用的BCI系统，以帮助他们进行通信。利用增强现实（AR）头戴式显示器作为提供BCI刺激和输出的解决方案。该方案有效解决了传统BCI使用存在的若干挑战，如屏幕定位、易用性、访问独立性和校准。论文源链接：https://link.springer.com/chapter/10.1007/978-3-030-80285-1_11
2021.8.10，印度皮拉尼的大学，Lizy Kanungo等，Wheelchair Automation by a Hybrid BCI System Using SSVEP and Eye Blinks。摘要：提出了一种混合脑机接口系统，用于残疾人轮椅的自动化。作者详细介绍了基于BCI的轮椅的工作原型，可以在典型的家庭环境中导航，同时不会给用户带来任何视觉障碍和不适。该原型基于稳态视觉诱发电位和眨眼的组合机制。轮椅由RaspberryPi通过WiFi控制。开发的原型展示了所有试验的平均 86.97% 成功率，每个命令执行时间为4.015秒。论文源链接：https://arxiv.org/ftp/arxiv/papers/2106/2106.11008.pdf
2021.5.12，美国斯坦福大学，Francis R. Willett等，High-performance brain-to-text communication via handwriting。摘要：开发了一种皮层内BCI，使用循环神经网络方法解码来自运动皮层神经活动的手写动作尝试，并可将其实时转换为文本。基于此BCI，手因脊髓损伤而瘫痪研究参与者的打字速度达到了每分钟90个字符，在线原始准确率为94.1%，离线准确率超过99%。该结果证明了瘫痪数年瘫患者实现快速、灵巧运动的可行性。该成果在Nature上发表。论文源链接：https://www.nature.com/articles/s41586-021-03506-2 代码：https://github.com/fwillett/handwritingBCI. 数据集：https://doi.org/10.5061/dryad.wh70rxwmv
2021.5.13，美国加利福尼亚大学，Sebastian Olsen等，An artificial intelligence that increases simulated brain–computer interface performance。摘要：介绍了一种新的基于AI技术的BCI架构（AI-BCI），可以改进对BCI计算机光标的控制，以便在虚拟键盘上打字，以帮助运动障碍患者有效沟通。其中利用用户在长时间（100秒前）和短时间（100毫秒前）的动作来修改BCI的轨迹。实验结果表明AI-BCI 提高了广泛控制质量范围内的性能，这提高 BCI 系统的临床可行性。论文源链接：https://pubmed.ncbi.nlm.nih.gov/33978599/
2021.3，浙江省脑机协同智能重点实验室，刘栋军, 孔万增等，“基于脑机协同智能的情绪识别”。摘要：提出一种基于脑机协同智能的情绪识别方法，并在中国面孔表情图片系统上进行了验证，发现对7 种情绪的平均识别准确率为88.51%，相比单纯基于图像的方法，提升了3%～5%。论文源链接：http://www.infocomm-journal.com/znkx/EN/article/downloadArticleFile.do?attachType=PDF&id=171216

其他民用方面

2021，捷克西波西米亚大学，Lukáš Vařeka等，Prediction of Navigational Decisions in the Real-World: A Visual P300 Event-Related Potentials Brain-Computer Interface。摘要：研究了视觉P300范式用于现实世界导航决策（行走中左转、右转等策略）制定，通过提取事件相关电位特征，预测他们的导航决策，结果显示单次试验分类准确率达到59.6%。论文源链接：https://www.tandfonline.com/doi/epub/10.1080/10447318.2021.188851 0?needAccess=true

军用

2020.12.22，美国加州州立大学，Devaj Parikh等，Quadcopter Control in Three-Dimensional Space Using SSVEP and Motor Imagery-Based Brain-Computer Interface。摘要：美国加州大学Devaj Parikh 采用BCI控制四轴飞行器，并在DJI飞行模拟器和Emotiv Epoc+耳机的帮助下进行验证。论文源链接：https://ieeexplore.ieee.org/abstract/document/9284924
2021.8.20，英国埃塞克斯大学，Saugat Bhattacharyya等，Anytime collaborative brain–computer interfaces for enhancing perceptual group decision-making。摘要：提出了协作脑机接口（cBCI）方法，并用两个军事相关场景对其测试，结果表明其显着提高感知群体决策的速度和准确性。这项工作的主要特点是：（1）cBCI结合了行为、生理和神经数据，以便能够在最快的团队成员投票后随时提供集体决策，但群体决策可以等待的时间越长，cBCI辅助决策的质量就越高；（2）将cBCI应用于两个与军事相关的现实场景（在黑暗的走廊巡逻和在夜间部署前哨，用户需要识别出现的任何身份不明的角色），其中决策是基于通过视频馈送传达的信息；（3）cBCI利用潜在威胁出现在大脑活动中引发的事件相关电位（ERP），但独特的是，出现时间是由系统自动估计的（而不是不切实际地提供给它）。由于这些因素，在两个测试环境中，与更传统的方式集成单个决策时相比，cBCI协助的小组做出更准确和更快的决策。论文源链接：https://www.nature.com/articles/s41598-021-96434-0.pdf
2021.8.16，韩国高丽大学，Dae-Hyeok Lee, Dong-Kyun Han, Sung-Jin Kim等，Subject-Independent Brain-Computer Interface for Decoding High-Level Visual Imagery Tasks。论文源链接：https://arxiv.org/pdf/2106.04026.pdf
2021.7.15，韩国高丽大学，Dae-Hyeok Lee, Dong-Kyun Han, Sung-Jin Kim等，DAL: Feature Learning from Overt Speech to Decode Imagined Speech-based EEG Signals with Convolutional Autoencoder。论文源链接：：https://arxiv.org/pdf/2107.07064.pdf
2020.12.13，韩国高丽大学，Dae-Hyeok Lee, Hyung-Ju Ahn, Ji-Hoon Jeong等，Design of an EEG-based Drone Swarm Control System using Endogenous BCI Paradigms。【3、4、5】摘要：针对BCI与无人机（群）控制的结合进行了深入研究，提出了多种新算法。提出了subepoch-wise特征编码器（SEFE），提高了任务的性能，并首次证明BCI在受试者之间的泛化可能性。首次尝试使用公开语音的EEG特征，通过自动编码器解码想象的基于语音的 EEG 信号，实验证明公开语音的EEG特征可以提高想象语音的解码性能。并基于此控制无人机群时，可以实现更直观地传递复杂的命令。设计了内生范式，即进行了专门用于无人机群控制的运动图像（MI）、视觉图像（VI）和语音图像（SI），以及与无人机群控制相关的基于EEG的各种任务分类。论文源链接：https://arxiv.org/pdf/2012.03507.pdf
2020.8.27，韩国韩东国际大学，Soram Kim等，P300 Brain–Computer Interface-Based Drone Control in Virtual and Augmented Reality。摘要：使用基于P300的BCI开发了一个基于开源的无人机控制应用程序，该应用程序可用于VR和AR。论文源链接：https://www.mdpi.com/1424-8220/21/17/5765/htm
2020.4.29，韩国高丽大学，Ji-Hoon Jeong等，Towards Brain-Computer Interfaces for Drone Swarm Control。摘要：介绍了将视觉图像范式用于各种场景的脑机接口系统的原型，通过实验确认了基于EEG信号的无人机群控制系统执行高级任务的可行性。论文源链接：https://arxiv.org/pdf/2002.00519.pdf
2020.9.14，印度圣约瑟夫工程技术学院，A.Franklin Alex Joseph ，Minimizing electrodes for effective brain computer interface。摘要：提出基于最近邻算法KNN的脑电信号分类器。论文源链接：https://www.sciencedirect.com/science/article/abs/pii/S17468094203033 72
2021.8.27，印度班纳里安曼理工学院，M.S. Prasath等，Mind-Controlled Unmanned Aerial Vehicle (UAV) Using Brain–Computer Interface (BCI)。摘要：对BCI 技术与无人机的集成进行了研究。论文源链接：https://onlinelibrary.wiley.com/doi/abs/10.1002/9781119769170.ch13
2020.3.28，西班牙格拉纳达大学、美国亚利桑那州立大学，Carolina Diaz-Piedra等，EEG Theta Power Activity Reflects Workload among Army Combat Drivers: An Experimental Study。摘要：基于脑电图数据，评估心里工作负荷变化对执行战斗和非战斗场景的陆军驾驶员大脑活动的影响，实验表明EEG活动可以以客观、公正的方式提供对心理工作量变化的相关洞察。对作战人员的持续监控不仅可以即时检测过载/欠载，还可以向系统（自动化设备或机组人员）提供在线反馈，以采取对策并防止致命错误。论文源链接：https://zaguan.unizar.es/record/89711/files/texto_completo.pdf?version=1
2021.9.5，孟加拉国军事科学技术学院计算机科学与工程系，Akib Zaman等，Intelli-Helmet: An Early Prototype of a Stress Monitoring System for Military Operations。摘要：为部署在军事行动中的士兵开发名为Inteli-Helmet的压力监测系统的早期原型，通过士兵的脑电波和生理数据，以测量他们的压力，并促进上级指挥官对士兵在（从）战场部署（或返回）做出最佳决策。研究发现贝叶斯网络算法在对士兵的压力状态进行分类时显示出更高的准确率，达到97.4%，其次是J48决策树算法，达到96.1%。论文源链接：https://link.springer.com/chapter/10.1007/978-3-030-86223-7_3
2020.8.4，阿联酋阿勒艾因大学，Fatima Ali Al-Nuaimi等，Mind Drone Chasing Using EEG-based Brain Computer Interface。摘要：提出了一种通过使用基于P300的脑机接口来控制无人机的新方法，该接口在军事领域可作为辅助技术。主要思想是无人机可以通过士兵的大脑活动使用脑电图（EEG）来控制无人机，以追逐其他无人机并发现隐藏的敌人区域。论文源链接：https://ieeexplore.ieee.org/abstract/document/9154926

教程课程

NeurotechEDU

（原链接：http://learn.neurotechedu.com/lessons/ ）

【BCI 101】这个模块提供了脑机接口的高级描述。在本课程中，将学习什么是BCI，一些例子，组成BCI的部分，如何制作BCI，以及一些为自己构建的项目。通过阅读脑机接口介绍模块开始本课程。如果对交互式教程感兴趣，并拥有android手机，可查看EEG 101应用程序。目录： ● Introduction to Brain Computer Interfaces ● What are some of the existing BCI’s applications? ● What are some of the headsets that I can purchase to make a BCI? ● What are some of the software tools I can use to build a Brain Computer interface? ● How do I do Signal Preprocessing ● How do I do Feature Extraction of Neural Oscillations? ● How do I do Feature Extraction of Event Related Potentials (ERP)? ● How can Machine Learning be used to recognize features? ● What are some BCI projects I can build for myself? ● New Emerging Technologies
【NEUROSCIENCE 101】神经科学导论是对我们所知道的大脑和神经系统其他部分的一个高层次的概述。 ● The Nervous System ● Cellular Components ● Neuroanatomy and Brain Organization ● Brain Diseases and Disorders
【NeuroTechEDU’s Awesome List of BCI-related Resources】 https://github.com/NeuroTechX/awesome-bci A. Software a. Stand Alone BCI Applications b. Matlab Toolboxes c. Python Toolboxes d. Android Toolboxes e. Brain Visualizations f. RaspberryPi Framework g. Communication Protocols B. Hardware a. EEG i. Consumer and DIY EEG Devices ii. Research EEG Devices iii. BCI Products iv. EEG Parts b. NIRS Devices c. Multimodal Neurotech d. Upcoming NeuroImaging Tech C. Brain Databases D. Consultants For Hire E. Tutorials and Project Ideas F. Communities and Blogs a. Blogs b. Forum G. Competitions a. Data Competitions b. Brain Controlled Competitions H. Conferences and Events I. Reading Material a. Papers b. Introductory Books c. Technical Books d. Signal Processing J. Other Resources

ISSCC 2021

本教程将重点介绍实现植入式BCI的关键挑战，如闭环操作、小型化和规模化。我们将首先介绍基本电路构建块及其与电极、信号和组织的相互作用。教程PPT：https://d3smihljt9218e.cloudfront.net/lecture/13728/slideshow/5927a14fe26dacd1900e46a45bf7c559.pdf 教程视频：https://underline.io/lecture/13728-t12---%EF%BB%BFbrain-computer-interfaces-fundamentals-to-future-technologies

MIT公开课

课程简介：探索包括脑机接口在内的感官恢复，恢复运动、触觉和视觉，包括基因治疗。课程视频链接：https://ocw.mit.edu/courses/brain-and-cognitive-sciences/9-13-the-human-brain-spring-2019/lecture-videos/brain-machine-interface/

SCCN（加州大学圣地亚哥分校斯沃茨计算神经科学中心）课程

课程简介：加州大学圣地亚哥分校斯沃茨计算神经科学中心《现代脑机界面设计导论》课程视频链接：https://www.youtube.com/playlist?list=PLbbCsk7MUIGcO_lZMbyymWU2UezVHNaMq

其他

基于深度学习的脑机接口教程(Deep-Learning for BCI) 教程主页：https://github.com/xiangzhang1015/Deep-Learning-for-BCI 教程数据集：https://github.com/xiangzhang1015/Deep-Learning-for-BCI/tree/master/dataset
BCI Project Code and Libraries 教程简介：介绍了脑机接口(BCI)项目中软件是如何工作的。教程PPT：https://docs.google.com/presentation/d/1uBB_7ZYPPjJvk_ZpMGcVdfXhiBBlWq9ArlWvfJFO_Eo/edit#slide=id.g801a61af19_0_0 教程代码：https://github.com/NeuroTech-UCSD/EEGFaceDetection 教程视频链接：https://www.youtube.com/watch?v=GmEW9Q_PxPU

开源工具

MATLAB Toolbox for Brain-Computer Interface Research 脑机接口研究的MATLAB工具箱这个软件是由加州大学圣地亚哥分校的Swartz计算神经科学中心编写的。这项工作由陆军研究实验室资助，合作协议编号为W911NF-10-2-0022，并由斯沃茨基金会(Old Field, NY)捐赠。biliab的设计受到了之前的工具箱(PhyPA工具箱)的启发，该工具箱是由C. Kothe在2006- 09年编写的，来自柏林理工学院人机系统部门的T. Zander的贡献。这个工具箱在2017年不再被积极开发。但是，仍然执行关键更新。 https://github.com/sccn/BCILAB

国家科技项目

科技创新 2030 —“脑科学与类脑研究”重大项目2021年度，https://service.most.gov.cn/u/cms/static/202109/%E9%99%84%E4%BB%B61-%E6%8C%87%E5%8D%97_20210916181751.pdf