托马斯智能体运行时 sl7187855-coder/harness-rs

🧠 Thomas — 智能体式 AI 助手

一个集成项目：智能体 + Harness-RS + HUD Web + Android

Thomas 是我们正在构建的智能体式助手。 Harness-RS 是 Rust 编写的执行内核；HUD 是 Web 界面；工具、上下文、记忆和任务为工作提供支撑；Thomas Mobile Agent 把一部分体验带到 Android。

🧭 总览 · 🖥️ HUD Web（代码） · 🦀 运行时 · 📱 Android · 🏗️ 架构 · 🤝 参与贡献

项目处于 early alpha：愿景是集成的，但部分集成仍需验证和开发。

🌐 一个集成系统

Thomas 不只是孤立的 Harness-RS。我们的想法是构建一个连贯的系统，让每个部分都有自己的角色：

| 部分 | 在系统中的角色 | 真实状态 |
| Thomas · 助手/智能体 | 接收目标、组织步骤、使用工具并验证结果 | 产品愿景；长时间自主运行仍在演进中 |
| Harness-RS | Rust 运行时、智能体循环、HTTP/SSE 网关、策略与工具调度 | 核心功能可用，处于 early alpha |
| HUD Web | Web 界面，用来对话并跟踪运行时的事件/状态 | 代码包含在 web/thomas-hud.html；网关在认证方面仍有缺口 |
| 上下文、记忆与任务 | 用 SQLite 和指令/技能文件保存历史与持久状态 | 基础已实现；高级功能与整合仍在开发中 |
| Thomas Mobile Agent | 与项目相关的 Android 应用、relay、命令行和 MCP 适配器 | 有测试版 APK；真机连接与安装需要重新验证 |
| 工具与扩展 | 文件、Bash、执行策略以及部分 MCP/LSP 集成 | 覆盖程度不一；请查看 PROJECT_STATUS.md |
如果你想从整体上理解这个产品，就从这里开始。要编译并运行核心，请按下面的 Quick Start 操作。想确切知道哪些能用、哪些还没做，请看项目状态。

🌟 Thomas 是什么？

Thomas 是一个个人助理智能体的愿景：它不只是回答问题，还能理解目标、把目标拆成步骤、使用工具、跟踪自己做过的事、检查结果，并继续处理耗时很长的任务。

Harness-RS 是我们为这个愿景搭建的执行基础。它把 Rust 运行时、面向 HUD 的 HTTP/SSE 网关、工具、上下文、技能、记忆、SQLite 中的持久化状态、任务与日程、审批策略，以及 Linux 上的子进程隔离整合在一起。

🎯 我们的目标： 一个有用且持久的智能体，能把任务推进得更远，保留之前尝试中的重要经验，并通过记录下来的结果和反馈不断改进——不掩盖错误、不编造成功、不跳过审批。

关于「学习」： 现阶段指的是用记忆、结果和反馈来指导后续行动。并不是说 AI 模型会自动训练自己的权重。高级记忆、记忆固化等长期能力仍在开发中。

🥔 我们的实验室：一台货真价实的土豆机

项目维护在一台老旧的 Positivo 机器上，属于上网本级别，资源非常紧张。下面这些规格是在准备仓库时直接从系统里读出来的：

| 真实机器 | 观察到的规格 |
| 报告的厂商 / 型号 | Positivo Informática · EC10IS1 |
| 处理器 | Intel Atom N2600 @ 1,60 GHz |
| CPU | 2 个物理核心 / 4 线程 |
| 检测到的内存 | 约 2 GiB（Linux 显示约 1,9 GiB） |
| 固件 / BIOS 报告的日期 | 04/11/2014 —— 这是固件字段，不是确认的生产日期 |
| 系统 | antiX / Debian 13 · Linux x86-64 |

这个平台对现代开发来说已经相当老旧。优化过的构建可能要跑很久，内存压力限制了并行测试，跑几个小时的测试也很难执行。我们背后没有什么隐藏的强力工作站；我们只能用手里这些资源去测量、测试和记录。

所以我们需要你。 有更强硬件、别的 Linux 发行版、能用来测试的 Android，或者在 Rust、安全、测试和智能体方面有经验的人，都能带来巨大的帮助。

🧭 我们希望 Thomas 能做到什么

- 处理长任务： 把目标拆成步骤，跟踪进度，恢复状态并继续推进，而不是依赖单次回答。
- 保持有用的上下文和记忆： 保存相关信息，调取之前的经验，减少重复劳动和上下文丢失。
- 从结果中学习： 识别失败，记录哪些做法有效，并基于记忆和反馈调整新的尝试。
- 使用工具和技能： 对文件、终端和集成进行操作，支持发现、schema 和权限规则。
- 有约束的自主性： 允许时自动执行，需要控制的动作请求批准。
- 可审计且安全： 限制权限，记录事件，关键控制不可用时安全失败。
- 通过扩展演进： 扩展模型/服务商集成、MCP、LSP、插件和移动智能体。
- 在低配硬件上运行： 降低内存占用，让开发在弱机器上也可行。

这些是开发目标，并不代表整个愿景已经完成。已知缺口见 PROJECT_STATUS.md。

🚦 当前状态：early alpha

GitHub CI 在最近验证的两个公开 job 上通过：Rust 测试、Clippy、Linux x86-64 release 构建、脚本/HUD 检查、relay/MCP 以及 Android 编译。这验证了那个 commit 和那些检查；不代表所有功能已在所有环境中测试过。

| 领域 | 当前情况 |
| 智能体运行时和服务商流式输出 | 已实现；还需扩大各服务商的覆盖 |
| HTTP/SSE 网关和 HUD | 已实现；网关认证/cookie 仍是重要缺口 |
| 工具目录 | 50 个名称；48 个可调度，2 个延期 |
| 文件工具 / Bash | 已实现，支持审批模式和受支持操作的快照 |
| Linux 沙箱 | 在受支持路径上使用 Landlock/seccomp；需要更多独立审查 |
| 上下文和技能 | 加载受支持的指令文件和本地技能 |
| 记忆和持久任务 | SQLite 存储消息、记忆、任务和日程 |
| 审计 | JSONL 记录，带 SHA-256 链式校验；无法防止管理员重写全部内容 |
| MCP | 通过 stdio 支持有限子集；并非协议完整覆盖 |
| LSP | JSON-RPC stdio 适配器已用模拟服务器测试；真实集成需要更多测试 |
| 完整 TypeScript/Cordis 宿主 | 尚未端到端实现 |
| PowerShell / RemoteTrigger | 此阶段延期 |

目录中的 50 个名称不代表 50 个经过独立认证的工具。 WebSearch 仍需验证有用的正向结果；WebFetch、子代理间 handoff、与真实服务器集成以及长时工作负载也存在缺口。项目不声称与 Codex CLI 或 Claude Code 完全对等。

详情：状态和优先级 · 一致性和证据 · 架构 · 安全 · 原始计划。

⚡ Quick Start — 安装并运行

注意： 在旧机器上首次构建可能相当慢。一次只跑一个步骤，只用你信任的工具，并让网关保持在回环地址。现在还不要把执行 API 暴露到公网。

1. 安装前置依赖

在基于 Debian/Ubuntu 的 Linux 上，安装基础工具：

~~~sh
sudo apt update
sudo apt install -y build-essential pkg-config curl git python3 nodejs npm

按照 rustup.rs 上的官方说明安装 Rust 稳定版。然后打开一个新终端，或者加载 Rust 环境，确认工具就绪：

~~~sh
rustup update stable
rustup component add rustfmt clippy
rustc --version
cargo --version

需要 Rust 1.88 或更高版本（edition 2024）。部分 Cargo 依赖可能还需要发行版特有的开发库。

2. 下载代码

~~~sh
git clone https://github.com/sl7187855-coder/harness-rs.git
cd harness-rs

3. 检查并编译

~~~sh
cargo fmt --check
CARGO_BUILD_JOBS=1 cargo test --locked --all-targets
CARGO_BUILD_JOBS=1 cargo build --locked --release

内存较小的机器上，保持 CARGO_BUILD_JOBS=1。要跑 CI 里那些额外检查：

~~~sh
CARGO_BUILD_JOBS=1 cargo clippy --locked --all-targets
python3 -m py_compile tests/e2e/*.py scripts/check_inline_js.py
bash -n scripts/deploy.sh
sh -n scripts/test.sh
python3 scripts/check_inline_js.py web/thomas-hud.html

4. 本地启动

在仓库根目录下，准备隔离的目录并运行 runtime：

~~~sh
mkdir -p .local-workspace .local-home/data
export HARNESS_HOME="$PWD/.local-home"
export HARNESS_DATA="$PWD/.local-home/data"
export HARNESS_WORKSPACE="$PWD/.local-workspace"
export HARNESS_BIND="127.0.0.1:1347"
export HARNESS_BRIDGE_BIND="127.0.0.1:3196"
export HARNESS_HUD_FILE="$PWD/web/thomas-hud.html"
export HARNESS_EXECUTION_MODE="ask"
cargo run --release

在本机打开 http://127.0.0.1:1347/。在支持的情况下，通过设置界面配置兼容的服务商；或者在启动 runtime 之前配置私有环境变量：

~~~sh
export HARNESS_API_BASE_URL="URL_BASE_DO_SEU_PROVEDOR"
export HARNESS_MODEL="ID_DO_MODELO"
read -r -s -p "API key: " HARNESS_API_KEY; printf '\n'
export HARNESS_API_KEY

把占位符换成你选的服务商对应的值。项目不会自动加载 .env。存放密钥的变量只能留在私有环境里：绝不要写进代码、shell 历史、截图、issue 或提交。验证集成时，只用一次性的测试凭据。

如果 runtime 没能按预期启动，请查阅 CONFIGURATION.md、PROJECT_STATUS.md，并提一个 附带复现步骤的 issue，注意不要包含任何密钥。

🏗️ 架构一览

~~~mermaid
flowchart TD
HUD["HUD / interface"] <-->|"HTTP + SSE"| GW["Gateway Rust"]
GW <--> AG["Loop do agente + provedor"]
AG --> TOOLS["Ferramentas e schemas"]
AG --> CTX["Contexto · skills · hooks"]
AG --> POLICY["Política e aprovação"]
POLICY --> SANDBOX["Execução isolada"]
SANDBOX --> OS["Arquivos · Bash · MCP · LSP"]
AG <--> DB["SQLite: memória · tarefas · histórico"]
SANDBOX --> AUDIT["Auditoria encadeada"]
AG <-->|"API compatível"| MODEL["Modelo configurado"]

📱 Thomas Mobile Agent — Android

仓库里包含 Android 应用、relay、命令行和 MCP 适配器。0.5.3（versionCode 12） 版本公开了源码，并提供带调试签名的测试 APK。

- 📲 下载 APK 0.5.3
- 🧾 Release、SHA-256 与说明
- 📖 移动端文档

Android 构建已通过 CI，但安装、登录和连通性还需要在真机上重新测试。APK 使用调试签名，不是生产版或 Play Store 版本。无障碍与截屏功能需要在设备上明确授权。

🔐 安全优先

- 在会话认证实现并通过独立审查之前，把 gateway 保持在 127.0.0.1 或可信的私有网络内。
- 不要把执行端点暴露到公网，也不要用公共隧道代替认证。
- 使用 ask 模式，不要在不可信 workspace 里以自动模式运行智能体。
- 把指令文件、技能、钩子、MCP/LSP 工具和外部返回结果都当作需要审查的输入。
- 永远不要把 .env、密钥、token、私有配置档、数据库、日志、证书或备份提交到版本库。
- 沙箱是一层防御，不是绝对保证。

报告漏洞之前，请先阅读 SECURITY.md。

🤝 贡献：我们一起把它做起来

我会继续为 Thomas 发布更新，修 bug，扩展智能体能力。但开发是在一台老旧的 Positivo 机器上进行的，Atom N2600，内存大约 2 GiB。这限制了我们能亲自验证的长时测试、集成和设备数量。

我们需要有人帮忙审查代码、在不同硬件上跑构建、测试 Android、覆盖集成、改进文档，以及开发已知的缺口。

🌱 适合上手的任务

- 查看所有 good first issue
- 查看面向贡献者的公开征集
- 提交新 issue 安装、测试和 PR 规则请见 CONTRIBUTING.md。小贡献也算数：复现 bug、在另一台机器上测试、修正示例、改进说明，都能帮上大忙。

🏆 致谢贡献者

感谢每一位花时间审阅、写文档、测试或改进 Thomas 的人。公开的姓名和贡献会由 GitHub 历史记录自动列出：

Contributors

查看贡献者图表 · 查看 pull requests

❤️ 一个野心勃勃的想法，一台破电脑，还有一大堆东西要造。

Thomas 想成为持久、好用、可靠的助手型智能体。帮我们走到那一步。

⭐ Harness-RS · 🤝 参与贡献 · 📱 Android 应用

Thomas Mobile Agent 0.5.3 APK 完整性

测试 APK 的 SHA-256：625a5a030981a61ca4a23503c3741b9e5cd0d2399950beeb1ea2e3a02af3333b。安装前请与 release 里的 .sha256 文件比对。