jason-allen-oneal/Odinn

# Ódinn Forge  [](https://github.com/jason-allen-oneal/Odinn/actions/workflows/ci.yml) [](https://github.com/jason-allen-oneal/Odinn/actions/workflows/security.yml) [](https://github.com/jason-allen-oneal/Odinn/actions/workflows/package-integrity.yml) [](https://github.com/jason-allen-oneal/Odinn/actions/workflows/workflow-lint.yml) Ódinn Forge 是一个跨平台的 agent runtime，专为那些希望助手能做更多事情（而不仅仅是生成文本），同时又不想让机器处于无人看管的爆炸半径之内的人而设计。它在一个小型的 Node.js 工作区中提供了 kernel、策略层、model/provider 适配器、浏览器与 Web 功能、sessions、audit trails 以及一个聊天优先的本地控制台。 本项目是一个净室实现。它没有复制 OpenClaw、Hermes、OpenViking 或任何其他 agent 框架。它从这些项目所解决的问题中汲取了架构灵感，并实现了 Ódinn Forge 自己的契约、存储和安全模型。 ## Beta 状态 Ódinn Forge 是一个预发布 beta 版本。核心的本地工作流和发布 自动化已经过大量验证，但达到稳定的 `v0.4.0` 所需的完整外部证据尚不完备。 公共 beta 参与者应从[公共 beta 指南](docs/public-beta.md)开始。它定义了受支持的本地优先范围、已验证的发布安装、隐私边界、诊断以及提交 Bug 报告的路径。 ### 已验证的 Beta 行为 - 通过 API key、OAuth、导入的 OAuth 会话、本地服务器或 CLI 适配器与已配置的 model 进行聊天； - 跨 session 回忆持久的用户和项目上下文； - 搜索公共 Web 并抓取页面； - 为您手动登录的账户操作一个隔离的浏览器配置文件； - 在执行可能改变外部状态的浏览器操作之前请求批准； - 检查 session、memory、run、goals、改进、providers 和 audit 事件； - 通过一条经过 audit 的 kernel 路径运行确定性工具和有边界的 model/tool 循环。 这些行为在本地有回归测试覆盖，且发布流水线会在 Linux、macOS 和 Windows 上构建并测试干净的源码包。[artifact 级别的 Beta 4 UAT 记录](docs/uat/v0.4.0-beta.1.md)另外记录了干净的 Linux/macOS 安装、本地 Ollama 使用、重启/恢复以及安装程序回滚的证据。自动化的跨平台和合成 provider 检查并不能替代下方提到的外部稳定版发布证据。 默认 gateway 依然保持单用户且仅限本地回环。可选择启用的 multi-user host 可用于远程部署；它会终止 TLS 并将每个经过身份验证的用户路由到独立的 loopback gateway、状态根目录、工作区、audit ledger、OAuth 存储和浏览器配置文件中。远程托管是应用级的租户隔离，而不是针对恶意用户的操作系统隔离。 经验证的 beta 基础包括：重启安全的队列任务、forked gateway worker、持久的审批和浏览器恢复日志、provider 重试与使用量标准化、全局 audit 的进程/MCP 扩展执行、DNS 固定的公共 Web 抓取、防符号链接的工作区读取、仅限所有者的状态修复、带指针回滚的版本化原生安装程序、签名的 audit 密钥轮换、有边界的反事实执行、在一次性工作区中批准的完整 capsule 回放、自主且安全的回滚可靠性调优，以及带有应用级租户隔离的可选远程托管。请参阅 [Beta 3 表面矩阵](docs/BETA-3-SURFACE-MATRIX.md)和 [P0 beta ledger](docs/P0-BETA-GATES.md)了解边界和发布证据。 ### 稳定版仍需的外部证据 `v0.4.0` 稳定版仍被四个跟踪中的验证活动所阻塞： - [Windows artifact 验证](https://github.com/jason-allen-oneal/Odinn/issues/49)，涵盖在真实 Windows 主机上的安装、引导、重启/恢复和回滚； - [实时 provider 验证](https://github.com/jason-allen-oneal/Odinn/issues/50)，涵盖云端 OAuth 和 API-key 路径； - [三用户、多日验证](https://github.com/jason-allen-oneal/Odinn/issues/51)，涵盖 Projects、Sessions、Goals、Memory 和经过 audit 的工具执行； - [最终安全审查和 go/no-go](https://github.com/jason-allen-oneal/Odinn/issues/52)，涵盖最终候选版本的安全证据、P0/P1 audit 以及维护者的发布决策。 [Beta 4 稳定版退出计划](docs/BETA-4-STABLE-EXIT.md)是权威的 ledger。不能因为一项绿色的合成检查通过就推断出任何未经检查的外部门槛已通过，并且在稳定版的门控要求得到满足之前，新的 runtime 子系统仍将推迟发布。 有关权威的表面分类，请参阅 [Beta 3 表面矩阵](docs/BETA-3-SURFACE-MATRIX.md)。其标签为**已验证的本地行为**、**实验性且默认禁用**、**依赖于 provider 或平台**，以及**明确不支持**。三个硬性限制是： - Forked worker 是崩溃隔离区，而不是安全沙盒。 - 远程托管是应用级的租户隔离，而不是针对恶意用户的操作系统隔离。 - 外部影响和非确定性的 provider 行为不在完全重放/回滚的保证范围内。 ## 快速开始 要求：Node.js 24+ 和 Corepack。 ``` corepack enable pnpm install pnpm check pnpm odinn onboard ``` 打开 [http://127.0.0.1:18790/](http://127.0.0.1:18790/)。 安装某个发布版本后，常规路径会更短： ``` odinn onboard ``` 引导程序提供快速、向导、空白状态以及检测到的 OpenClaw/Hermes 导入路径。现有安装具有单独的打开、修复、更改 AI、审查功能、高级和确认的重置操作。更改在被提交之前会经过暂存、备份，并通过真实的 model 响应进行验证；除非明确更改，自定义的 capability 策略保持不变。在无头机器上请使用 `odinn start --no-open`。有关脚本化的 provider、本地 model 和故障排除示例，请参阅[入门指南](docs/getting-started.md)。 通过与 chat 使用的相同 runtime 路径，验证已配置的账户和 model： ``` pnpm odinn onboard --verify --non-interactive ``` 要进行确定性冒烟测试： ``` pnpm odinn run --tool text.echo --input-json '{"text":"ODINN_OK"}' pnpm odinn plan --file examples/local-smoke.plan.json pnpm odinn runs pnpm odinn audit ``` 打包的发布门控比本地 echo 冒烟测试更严格：CI 将 gateway 作为子进程启动，配置一个兼容本地 OpenAI 的 provider endpoint，通过 gateway 发送一次 model 请求，并验证助手响应是否已写入运行记录中。关于已实现的功能和刻意阻止的内容，请参阅 [P0 beta ledger](docs/P0-BETA-GATES.md)。 ### Phase 0 运行时 ledger 现在，每个 CLI 和 gateway 工具边界都可以写入一个持久的 SQLite 运行 ledger，其中包含有序的步骤、已脱敏的内容寻址 artifact、保守的工具安全元数据、实验性 feature flag 以及 SHA-256 事件链。无需读取原始 JSONL 即可检查一次运行： ``` pnpm --silent odinn run show --state .odinn pnpm --silent odinn run events --state .odinn pnpm --silent odinn run verify --state .odinn ``` 这是实验性 Proof、Rewind、Sentinel、Capsule、Darwin、Capability 和 Counterfactual 切片的共享基础。它们默认处于禁用状态，必须单独启用。合并后的 CLI 主页展示了每个门控、其安全的检查路径及其背后的真实命令： ``` pnpm odinn experimental status pnpm odinn experimental help proof pnpm odinn experimental enable proof --confirm-impact ``` 现有的 `config experimental` 和特定于功能的命令仍可用于脚本。本地控制台还提供了一个 **Experimental Lab**，用于实时查看门控状态、最近的 runtime-ledger 记录以及操作员通过相同的已验证 API 调用的操作；它绝不会静默启用任何功能。在启用它们之前，请阅读 [docs/features](docs/features/) 下的功能说明。请参阅 [event-ledger 架构说明](docs/architecture/event-ledger.md)。 ### 实验性 runtime 切片 - **Proof** 运行无 shell 的命令和文件接受断言，存储有边界的证据，并且是唯一可以将运行标记为“已验证”的路径。 - **Sentinel** 在操作之前评估确定性命令、文件系统根目录和审批不变量。 - **Capability Tokens** 将短暂的、一次性使用的权限绑定到特定的运行、步骤、工具和资源约束上。 - **Rewind** 对选定的本地文件进行快照，并默认以试运行的方式预览恢复。 - **Capsules** 导出经过脱敏处理的、兼容 ZIP 的运行包，并带有校验和验证和安全提取功能。 - **Counterfactual** 创建候选工作区的独立文件系统副本，并比较它们持久的运行记录；这些副本不是操作系统沙盒，候选执行和选择仍由操作员驱动。 - **Darwin** 根据记录的验证、可靠性、速度、成本和策略结果对 model 进行评分。 - **Self-improvement** 将重复的、经过 audit 的失败挖掘为可审查的提案。它不会重写代码、更改策略、安装技能或批准其自身的更改。 这些是初步的本地切片，并不声称任意远程影响都可以被逆转或完美重放。浏览器 session 和外部突变仅通过文档中规定的审批、恢复和出口边界提供支持。反事实执行是显式的，并由操作员驱动。Forked worker 是崩溃隔离区，而不是安全沙盒。远程托管是应用级的租户隔离，而不是针对恶意用户的操作系统隔离。外部影响和非确定性的 provider 行为不在完全重放/回滚的保证范围内。在启用实验性功能之前，请参阅 [Beta 3 表面矩阵](docs/BETA-3-SURFACE-MATRIX.md)。 经过身份验证的 gateway 通过 `/runtime/runs`、`/proof`、`/policy/evaluate`、`/capabilities/*`、`/checkpoints`、`/rewind/*`、`/capsules/*`、`/counterfactual/*` 和 `/routing/*` 暴露相同的实验性表面。在 `.odinn/config.json` 中启用其匹配的实验性标志之前，每个表面都将保持禁用状态。 ## Model provider 常规的 provider 路径特意设计得很短： ``` pnpm odinn onboard ``` 在向导设置中选择 OpenAI / ChatGPT 以通过浏览器登录。对于脚本化和高级安装，仍可使用 API-key 设置： ``` export OPENAI_API_KEY="..." pnpm odinn onboard --provider openai --auth api-key ``` 本地 model 无需云账户即可工作： ``` pnpm odinn onboard --provider ollama --model ``` Ódinn Forge 不假定使用特定的本地 model。只需传入由您的 Ollama 实例已提供的 model 名称即可。 Ódinn Forge 还包含针对以下平台的免 URL 预设：OpenRouter、Groq、Together、Mistral、DeepSeek、xAI、Moonshot、Fireworks、Cerebras、Cohere、DeepInfra、NVIDIA、Z.ai、Qianfan、Volcengine、Xiaomi、Hugging Face、Venice、Chutes、LiteLLM、vLLM、SGLang、LM Studio、GitHub Copilot、xAI device OAuth 和 Antigravity。 使用以下命令检查目录： ``` pnpm odinn config provider catalog ``` 重用现有的 OpenClaw OAuth 会话，无需再次登录： ``` pnpm odinn auth import openclaw --state .odinn ``` 框架状态和技能可以导入到一个隔离的状态目录中： ``` pnpm odinn import openclaw --state .odinn pnpm odinn import hermes --state .odinn ``` 密钥保存在 `config.json` 之外。OAuth token 存放在 `.odinn/oauth/` 中，并具有严格的权限限制。 Gateway API 客户端通过请求一次 `/` 来引导每个状态的 bearer token，这会设置一个 `HttpOnly` 的同站 cookie。浏览器客户端会自动使用该 cookie；脚本应发送 `Authorization: Bearer ` 或引导 cookie。该 token 以 `0600` 模式存储在 `.odinn/gateway.token` 中。变更请求还需要有效的同源请求。 ## Memory Ódinn Forge 的 memory 是一个原创的本地上下文系统，围绕仅追加日志和显式来源而构建。它不是专有数据库的克隆，也不依赖于封闭的 memory 服务。 当前的 memory 主干提供： - 针对偏好、人员、项目、决策、流程、artifact、更正和系统事实的持久化类型记录； - 带有主题、标签、置信度和近期度信号的排名词汇召回； - 分层 namespace，例如 `user/preferences`、`project/decisions` 和 `sessions/`； - 三个上下文层级：L0 摘要、L1 持久事实和 L2 支持性证据； - 自动召回，作为清晰标记的上下文注入到有边界的 agent 轮次中； - 自动提取强用户陈述，例如“记住……”、“我更喜欢……”和“我们决定了……”； - 一旦对话变得过长，会将 session 压缩为持久的 L0 摘要； - 通过 gateway、GUI 和 CLI 进行 namespace 浏览和记录检查； - 重复抑制、更正/取代和过期强制执行； - 显式的 `memory.recall`、`memory.remember`、`memory.search`、`memory.correct` 和 `memory.curate` 工具； - session 来源链接，将学到的事实追溯其原始轮次。 手动 memory 命令仍然可用： ``` pnpm odinn memory remember \ --kind preference \ --subject cli \ --text "Prefer exact runnable commands with concise context." \ --tags commands,ux pnpm odinn memory search --query "runnable commands" pnpm odinn memory recall --query "how should CLI output behave?" pnpm odinn memory browse --namespace user pnpm odinn memory open --id pnpm odinn memory compact --session pnpm odinn memory curate ``` memory 层是刻意透明的：检查日志、检查召回结果、更正错误记录以及 audit agent 路径。基于 的检索和可插拔的 vector index 是计划中的扩展功能，而不是假装今天已经存在的隐藏魔法。 ## Web、浏览器和真实世界的操作 通过 `web.search` 和 `web.fetch` 可进行公共 Web 访问。 私有账户访问使用 Ódinn Forge 隔离的持久化浏览器配置文件。用户需手动登录；Ódinn Forge 不会静默提取另一个浏览器的 cookie。Agent 可以进行浏览器读取，而点击、输入和按键默认需要批准。 安全控制是可配置的： ``` pnpm odinn config security show pnpm odinn config security set --surface web --allowed-domains docs.example.com pnpm odinn config security set --surface browser --require-approval false --confirm-impact ``` 最后一条命令削弱了默认的安全姿态。这是有意为之的：用户拥有危险决策权，而配置使该决策变得可见。 状态生命周期命令是显式且可恢复的： ``` pnpm odinn state backup --output /secure/path/odinn-backup pnpm odinn state restore --input /secure/path/odinn-backup --confirm ``` 扩展清单在被审查并使用显式授权启用之前，都处于未激活状态： ``` pnpm odinn extension install --manifest ./extension.json pnpm odinn extension enable --id example-tool --grant web.read --trust pnpm odinn extension run --id example-tool --capability web.read --input-json '{"query":"hello"}' pnpm odinn extension disable --id example-tool pnpm odinn extension rollback --id example-tool ``` 可执行扩展使用两种显式适配器之一。`container` 是第三方代码的默认适配器，要求提供完整不可变包的 SHA-256 摘要；它以只读模式运行，没有网络，具有 dropped capabilities、no-new-privileges、PID 限制、CPU/内存限制以及有边界的临时文件系统。`unconfined-process` 仅适用于具有已验证入口点摘要和明确的不安全沙盒确认的完全受信任的本地代码。两种适配器都接收有边界的 I/O，并跨越经过 audit 的 Sentinel/capability 边界。工具扩展使用 Ódinn Forge 的 JSONL 调用契约；MCP 扩展通过 JSONL 使用 JSON-RPC `tools/call`。 仅在启用明确选择 `unconfined-process` 的清单时才使用 `--allow-unsafe-sandbox`。默认的 container 适配器不需要此标志。 本地控制台包含 Projects、范围内的 Sessions 和 Goals、持久的 Memory、Usage、Cron Jobs、有意义的 proof/audit Tasks、分页的 Audit ledger、Agent SDK 包注册表以及受管的 Skill SDK。Agent 和 skill 包在安装时处于禁用状态；注册或发现操作不会执行或激活它们。有关这些视图背后的 API、持久化和安全边界，请参阅[操作员控制台](docs/operator-console.md)。 ## 架构 ``` chat / CLI / plans │ ▼ audited gateway or CLI │ ▼ policy-gated kernel ─── model/provider adapters │ ├─ API key │ ├─ OAuth / device OAuth │ ├─ local OpenAI-compatible servers │ └─ CLI adapters ├── web and isolated browser tools ├── durable projects, scoped sessions, goals, improvements ├── original memory journal and ranked recall ├── SQLite run ledger, artifacts, snapshots, and verification evidence ├── Proof, Sentinel, capabilities, rewind, capsules, branches, and routing └── append-only audit events ``` 仓库布局： ``` apps/cli/ user-facing CLI and TUI apps/gateway/ local HTTP gateway and web console packages/kernel/ policy-gated execution, providers, memory, sessions packages/policy/ capability and security policy evaluation packages/protocol/ shared request and audit contracts packages/store-file/ append-only local stores tests/ kernel, gateway, CLI, integration, and platform coverage ``` ## 本地状态 默认情况下，runtime 状态位于 `.odinn/` 下： - `config.json` — provider 和策略元数据； - `records.jsonl` — memory、project、session、goal 和改进记录； - `audit.jsonl` — 策略决策和执行事件； - `db/odinn.sqlite` 和 `artifacts/` — 持久运行 ledger 和内容寻址证据； - `jobs/`、`approvals.json` 和浏览器恢复记录 — 重启安全的执行状态； - `cron-jobs.json` 和 `agents.json` — 计划任务和 Agent SDK 包状态； - `skills/registry.json` 和 `skills/packages/` — 受管的 Skill SDK 状态和不可变的包版本； - `gateway.token` 和 audit 签名密钥 — 仅限所有者的本地控制平面密钥； - `oauth/` — 可刷新的 OAuth token； - `browser-profile/` — 隔离的 Chromium 配置文件； - `imports/` 和 `skills/imported/` — 已审查的框架导入。 此列表指出了主要存储，而不是每个内部迁移或恢复文件。切勿将 API key、bearer token 或私有账户导出放入计划、提交或 audit payload 中。 ## 开发 ``` pnpm install pnpm check pnpm test pnpm build ``` beta 版本目前以 Node.js 24 为目标，并通过平台层支持 Linux、macOS 和 Windows 路径。 发布包验证会解压这两个源码包，使用冻结的 lockfile 进行安装，在全新的状态目录中完成引导，并从解压后的目录树中执行真实的 CLI 工具。在本地运行它： ``` pnpm release:package pnpm release:soak pnpm release:checksums node scripts/release/verify.ts pnpm release:install-smoke pnpm storage:drill ``` 请从干净的、已提交的候选版本中运行此序列：打包程序归档的是 `HEAD`，而不是未提交的工作树更改。请在计算校验和之前运行 soak，以便将 `soak-report.json` 包含在最终的校验和集合中；如果之后任何发布 artifact 发生更改，请重新生成校验和并重新运行验证。 ## 安全 在启用远程访问、自主改进、禁用审批、允许私有网络或安装导入的技能之前，请阅读 [SECURITY.md](SECURITY.md)。切勿将单用户 gateway 公开绑定。远程部署必须使用具有 TLS 和显式用户配置的独立 multi-user host。 版本化安装和回滚： ``` ./scripts/install.sh --prefix "$HOME/.local/share/odinn" node scripts/install.ts upgrade --source . --prefix "$HOME/.local/share/odinn" node scripts/install.ts rollback --prefix "$HOME/.local/share/odinn" ``` 可选择启用的 multi-user host： ``` ODINN_HOST_STATE=/srv/odinn ODINN_USER_PASSWORD='use-a-password-manager' \ node apps/gateway/src/host.ts user-add --id alice --workspace /srv/workspaces/alice ODINN_CONFIRM_IMPACT=true ODINN_HOST=0.0.0.0 ODINN_PORT=443 ODINN_HOST_STATE=/srv/odinn \ ODINN_PUBLIC_ORIGIN=https://odinn.example.com \ ODINN_TLS_CERT=/etc/letsencrypt/live/odinn.example.com/fullchain.pem \ ODINN_TLS_KEY=/etc/letsencrypt/live/odinn.example.com/privkey.pem \ pnpm host:start ``` ## License MIT

标签：AI代理, GNU通用公共许可证, MITM代理, Node.js, 人工智能, 本地优先, 浏览器自动化, 用户模式Hook绕过, 自动化攻击