Linux.do Agent 用户脚本介绍
📖 项目简介
Linux.do Agent 是一个功能强大的用户脚本（UserScript），专为 linux.do 论坛设计。它为论坛添加了一个基于 AI 的智能助手界面，能够通过兼容 OpenAI Chat Completions 格式的 API 与 Discourse 论坛 API 进行交互，提供丰富的论坛数据查询和分析功能。
✨ 核心特性
🤖 AI 助手集成
- OpenAI 兼容 API：支持配置自定义
baseUrl、model 和 API Key
- 灵活的模型配置：Temperature、maxTurns、maxContextChars 等参数可调
- 自定义 System Prompt：可完全自定义 AI 的行为模式
💬 会话管理
- 多会话支持：可创建、切换、重命名和删除多个独立会话
- 跨刷新持久化：所有会话数据自动保存，刷新页面后依然保留
- 会话过滤：支持按标题快速筛选会话
- 草稿保存：输入框内容自动保存，切换会话不丢失
🛠️ Discourse 工具集
脚本提供了 11 个强大的 Discourse API 工具：
- discourse.search - 搜索论坛内容
- discourse.getTopicAllPosts - 获取话题的所有帖子
- discourse.getUserRecent - 查询用户近期活动
- discourse.getCategories - 获取分类列表
- discourse.listLatestTopics - 列出最新话题
- discourse.listTopTopics - 列出热门话题（按周期）
- discourse.getTagTopics - 获取特定标签的话题
- discourse.getUserSummary - 获取用户详细概览（含热门帖子）
- discourse.getPost - 获取单个帖子详情
- discourse.getTopicPostFull - 按话题 ID 和楼层号完整抓取指定楼层（最多 10000 字符）
- discourse.listLatestPosts - 获取站点最新帖子列表
🎨 现代化 UI
Workbench 界面
- 三标签页设计：
- Chat：用户与 AI 的对话界面
- Tools：手动运行工具，不走模型
- Debug：查看工具调用日志和模型输出
主题支持
- 支持浅色、深色和自动三种主题模式
- 响应式设计，适配各种屏幕尺寸
- 优雅的渐变色和动画效果
交互特性
- 可拖动悬浮球：记忆位置，自动吸附边缘
- 折叠/展开长消息：自动检测并折叠过长内容
- 复制/引用功能：一键复制或引用消息内容
- Markdown 渲染：支持 Markdown 格式的消息显示
🔧 高级功能
Agent 引擎
- FSM 状态机：精确控制执行流程（IDLE → RUNNING → WAITING_MODEL → WAITING_TOOL → DONE/ERROR）
- 多轮工具调用：AI 可自主决定调用多个工具获取完整信息
- JSON 自动修复：自动修复模型输出的 JSON 格式错误（find/rfind）
- 停止控制：支持随时中止运行中的任务
工具结果优化
- 智能上下文压缩：将工具返回的大量数据压缩为精炼的上下文
- 分段显示：长话题自动提取"前 N 楼 + 后 M 楼"
- 引用链接：final 回答中的
refs 字段自动显示为可点击链接
数据导出
- 支持导出会话为 JSON 格式
- 包含完整的聊天记录、工具调用日志和状态信息
📦 安装方法
前置要求
安装浏览器扩展：
准备 OpenAI 兼容的 API：
- OpenAI 官方 API
- 或其他兼容 OpenAI Chat Completions 格式的 API 服务
安装步骤
- 复制
1.js 的全部内容
- 在浏览器扩展中创建新脚本
- 粘贴代码并保存
- 访问 linux.do 论坛即可看到悬浮球
🚀 快速开始
1. 基础配置
首次使用需要配置 API 信息：
- 点击右上角悬浮球打开界面
- 点击"设置"按钮
- 填写以下信息：
- Base URL：API 端点（如
https://api.openai.com/v1）
- Model：模型名称（如
gpt-4o-mini）
- API Key：你的 API 密钥
- Temperature：0-1 之间，控制回答随机性
- maxTurns：最大工具调用轮数（1-30）
- maxContextChars：最大上下文字符数（4000-80000）
2. 使用示例
搜索内容
帮我找一下关于 Docker 的教程
查看用户信息
查看 @username 的个人概览和热门帖子
获取话题详情
总结话题 12345 的内容
抓取特定楼层
帮我获取话题 12345 的第 10 楼完整内容
列出最新内容
列出最新的 20 个帖子
3. 手动工具模式
在 Tools 标签页中，你可以手动运行工具而不通过 AI：
- 选择工具名称
- 编辑参数 JSON
- 点击"运行工具"
- 查看结果后可选择：
- 加入上下文：将结果添加到当前会话上下文
- 发到聊天：直接显示在聊天界面
- 复制结果：复制到剪贴板
🔍 架构设计
核心模块
// 1. 配置存储
class ConfigStore {
- 管理 API 配置
- 持久化到 GM_getValue/GM_setValue
}
// 2. 会话存储
class SessionStore {
- 管理多个会话
- 每个会话包含 chat、agent、fsm、draft
- 跨刷新持久化
}
// 3. Discourse API
class DiscourseAPI {
- 11 个静态方法对应 11 个工具
- 统一的错误处理和信号控制
}
// 4. Agent 引擎
function runAgent() {
- FSM 状态机控制
- 多轮工具调用循环
- JSON 自动修复
}
// 5. UI 类
class UI {
- 三标签页界面渲染
- 事件绑定和交互逻辑
- 主题切换和响应式布局
}
数据流
用户输入 → runAgent()
↓
buildLLMMessages() → callOpenAIChat()
↓
parseModelJsonWithRepair()
↓
type="tool" → runTool() → toolResultToContext()
↓ ↓
回到 runAgent() ←───────────────┘
↓
type="final" → 显示回答 + refs
🎯 System Prompt 设计
脚本使用了精心设计的 System Prompt，将 AI 定位为"JSON 协议路由引擎"：
{
"type": "tool",
"name": "工具名称",
"args": { "参数": "值" }
}
或
{
"type": "final",
"answer": "回答内容（支持 Markdown）",
"refs": [
{ "title": "标题", "url": "链接" }
]
}
关键约束
- ❌ 禁止自然语言废话
- ❌ 禁止 Markdown 代码块包裹 JSON
- ✅ 二选一输出：tool 或 final
- ✅ refs 必须基于真实数据
- ✅ 积极进行多次工具调用
🛡️ 错误处理
JSON 修复机制
如果模型输出格式错误，脚本会自动：
- 使用
indexOf("{") 和 lastIndexOf("}") 查找边界
- 切片并重新解析
- 回写修复后的 JSON 到 history
取消机制
每个会话维护一个 cancelToken：
{
cancelled: boolean,
aborts: Function[] // 用于中止网络请求
}
点击"Stop"按钮会：
- 设置
cancelled = true
- 调用所有
aborts 函数
- 终止所有进行中的请求
📊 性能优化
上下文压缩
- 搜索结果：限制 12 条，摘要 420 字符
- 话题帖子：前 18 楼 + 后 8 楼
- 用户概览：热门/近期各 10-12 条
- 总上下文：< 22000 字符
批量请求
getTopicAllPosts 使用批量加载：
- 每次请求 18 个帖子 ID
- 间隔 160ms 避免触发限流
- 支持取消控制
🎨 UI 主题
CSS 变量系统
:root {
--a-bg: 背景渐变
--a-card: 卡片背景
--a-primary: 主色调渐变
--a-text: 文字颜色
/* ... */
}
响应式设计
- 宽屏：侧栏 300px
- 中屏：侧栏折叠按钮
- 小屏（<860px）：自动隐藏侧栏
🔐 隐私与安全
- 本地存储：所有数据存储在浏览器本地
- API Key 安全：使用 password 类型输入框
- 无第三方追踪：不包含任何分析或追踪代码
- CSRF 保护：Discourse API 调用自动附加 CSRF Token
📝 开发者信息
- 作者：Bytebender
- 版本：0.2.4
- 许可证：GPL-3.0-or-later
- 命名空间：https://example.com/linuxdo-agent
🤝 贡献指南
欢迎提交 Issue 和 Pull Request！
代码结构
- 第 0 节：常量和工具函数
- 第 1 节：配置存储
- 第 2 节：会话存储
- 第 3 节：Discourse API
- 第 4 节：工具注册表
- 第 5 节：OpenAI 客户端
- 第 6 节：JSON 修复
- 第 7 节：Agent 引擎
- 第 8 节：UI 实现
- 第 9 节：启动入口
📜 更新日志
v0.2.4（当前版本）
- ✅ 完整的 Workbench UI（Chat/Tools/Debug）
- ✅ 主题切换（light/dark/auto）
- ✅ FAB 可拖动并记忆位置
- ✅ final.refs 显示到 UI
- ✅ JSON 自动修复并回写 history
- ✅ 11 个 Discourse 工具
- ✅ 多会话跨刷新持久化
- ✅ Stop 按钮支持取消运行
🙏 致谢
📧 联系方式
如有问题或建议，欢迎在 linux.do 论坛联系作者或提交 Issue。
注意：使用本脚本需要自行准备兼容 OpenAI Chat Completions 格式的 API Key。请遵守相关服务条款和论坛规则。
