FOGA node

Finch OG Agent（FOGA）

FOGA 是一个参考自主 Agent，基于同一作者撰写的十二份以太坊 ERC 草案构建：

ERC	标题	在一个 cell 中的作用
ERC-8338	Token 绑定可执行技能	cell 能执行什么（经哈希验证的技能包）
ERC-8414	Token 绑定任务招标	cell 承接或提供的工作（托管招标）
ERC-8419	了解你的 Agent（KYA）框架	cell 如何证明自身相关事实（经证明和零知识证明的声明）
ERC-8434	Agent 身份（AID）	以地址为锚点的 cell 身份和存活状态
ERC-8436	Agent 集体决策框架（ACDF）	cell 如何共同决策（具有最终性的授权 K-of-N 决策）
ERC-8444	Agentic 资源链上发现（ARD）	如何发现 cell、技能和任务
ERC-8447	群体 AI 框架（SAI）	cell 如何组织成目标明确的群体
ERC-8454	AIFi 单元框架（AUF）	cell 或群体的经济边界和计量方式
ERC-8468	Agent 安全框架（ASF）	cell 采用的安全规范及其必须遵守的干预措施
ERC-8471	AI 争议解决框架（ADRF）	如何针对 cell 的行为提出主张、作出裁定并执行
ERC-8490	Agent 冥想机制（AMM）	cell 自身的维护：四层状态文档、状态版本，以及每层的时效性（docs/meditation.md）
ERC-8489	Agent 信息流范式（AIFP）	cell 的信息流：其自身频道、锚定的发布内容，以及由其身份获准进入的市场（docs/flows.md）

ERC-8004（无信任 Agent）是必需的依赖项：ERC-8419、ERC-8434 和 ERC-8447 绑定到其身份注册表。ERC-8490 和 ERC-8489 作为扩展引入（0.8.0、0.9.0；docs/extending.md），并从 1.0.0 起纳入基础集合：十二约约的 cell 正是 FOGA-Cell-v2 所描述的内容，它是 cell 安全规范的第二个版本（docs/specification.md）。

该项目通过一个内核交付三项内容：Finch OG Agent（第一个运行中的实例）、任何人都可以使用自己的身份、模型和钱包运行的 FOGA 节点软件，以及公共访问层（MCP、A2A、HTTP/CLI）。项目分阶段构建；本仓库已完成 Phase 2c：公链上的创世部署，建立在 Phase 2 创世阶段（T0–T9）和 Phase 1 世界层之上。

状态：1.0.7（4c，2026-11-11）——十二约约的 cell：FOGA-Cell-v2、ERC-8489 和 ERC-8490 纳入基础集合，foga.probe/2，创世阶段 T0–T9 对两项约约进行测试，医生第 5 层对十二项约约进行评判；4b（0.9.0–0.9.1，2026-11-09）——cell 的信息流（ERC-8489）作为扩展：其自身频道、锚定的发布内容、由身份获准进入市场，以及四值角色；OG 初始化了 Sepolia 的信息流（foga 家族、默认市场），打包后的 Sepolia 世界也包含这些信息流；4a（0.8.0–0.8.2，2026-11-09）——cell 自身的维护（ERC-8490）作为扩展：一个手动、可恢复、可重新计算的周期，随后是负责运行到期周期的监视器；3e-1（0.7.0，2026-11-06）——foga join：只需一条命令，cell 就能在公链上运行，并拥有自己的名片和链上工作；Phase 3 已完成（0.6.0，2026-11-05）——OG 已在 foga.finchip.ai 上线，MCP 注册表已收录，并与外部 Agent 在 Sepolia 上运行 Loop D；3d-2（钱包、签名调用方、链上文档、预检、A2A、Sourcify）、3d-1（快速入门、外部 Agent 的 Loop D）、3c（带模型的 Loop D）、3b（MCP 和 HTTP）、3a（作为节点的内核）均已完成

4c（1.0.0，2026-11-10）。 十二契约单元。ERC-8489 和 ERC-8490 是 0.8 和 0.9 中扩展的组成部分，现已纳入基础集合：FOGA_COVENANTS 列出十二项契约和 ERC-8004；缺少某项契约的 world 会明确说明（world.missing），本地和 Sepolia world 则包含全部内容。FOGA-Cell-v2 是该单元 ERC-8468 安全规范的第二版（docs/specification.md）：版本 1 的四项条款仍由账户像以前一样执行，另有三项由运行时执行——保留并维护的状态（ERC-8490）、锚定在单元自身通道中的自我描述（ERC-8489）、仅能通过账户按规则参与共享上下文，以及如实报告已获得的验证者结果。在 1.0.0 下创建的单元绑定到版本 2，且其账户的要求会注明该版本；更早创建的单元——其要求在部署时固定为版本 1——会通过账户采用版本 2 作为第二项由运行时强制执行的绑定（foga cell adopt）；账户继续通过其呈现的绑定执行版本 1，后继主体（foga cell migrate）则在自身绑定中固定版本 2；卡片、清单、spec_status 和预检都会说明账户执行的版本以及运行时采用的版本。foga.probe/2 在确定性探测中加入了这两项契约（主体拥有权威的通道、其锚点、其市场角色；其注册状态、状态版本以及每一层在该区块的及时性）；foga cell skill update 则会将持有的代币迁移到程序的新软件包（ERC-8338 updateSkill，重新提交记录，保留沿袭；从 1.0.2 起，已加入单元的自身软件包副本会从程序刷新，因此其代币也会迁移）。1.0.3 开始进行首次外部审查：FogaCellAccount 修订版 3 会先请求所有者，再请求操作员，因此单密钥单元可以迁移自身资产（cell migrate、identity_transfer）；模拟不会更改任何能力；探测工作进程会在 Node 25 上访问 RPC。1.0.4 和 1.0.5 开始进行首次 Windows 运行：技能工作进程可在 Windows 上启动（此前工作进程的路径是 URL 路径名），卡片注明 ERC-8004 注册表，创建时会写入其流程文档（此前通过按 / 拆分路径来获取文件名）。1.0.6 添加了发布检查（.github/workflows/release-check.yml）：作为用户安装并运行 tarball——在 Linux、macOS 和 Windows（PowerShell 和 Git Bash）上运行 demo --genesis T9、quickstart --exit，使用 Node 22、24 和 26，并可按需针对已发布版本运行（docs/mcp.md，“软件包”）。1.0.7 将 tender 的提交计数和条目作为一个整体读取（启用自动挖矿的 anvil 可能会在区块标签之前响应调用；遍历会从新的计数重新开始）。Genesis T0–T9 端到端测试两项契约——两个规范版本、每个单元的注册和通道、取代与事件周期、需求方获准后流程门的切换、停止信号传至维护任务和流程、后继单元重新注册并将其通道命名为前序单元的父项——共 197 项检查、215 项操作；医生的第 5 层根据这些证据评判全部十二项，没有任何一项标记为 NotTested（deployments/local.genesis.example.json、local.doctor.example.json）。137 项测试。 4a，第一阶段（0.8.0，2026-11-09）。 一个存续数月的 cell 会发生变化——程序、依赖项、技能、条款、工作、存储——而 ERC-8490（由同一作者撰写的 Agent Meditation Mechanism）为这种变化提供了注册后的形式：cell 保留的四层状态文档、登记在注册表中的承诺和状态版本，以及各层的时效性。它作为第十一个契约和一个扩展进入 FOGA（docs/extending.md 中的五个位置；docs/meditation.md）：注册表已纳入计划和本地世界（48 个合约），上游 Sepolia 实例已连接，World.covenants() 会在 world.extensions 下列出 ERC-8490，doctor 会检查第 1–3 层，并在第 5 层标记 NotTested，直到某个场景对其进行测试；基础集合保持不变。src/core/amm.ts 是内核对此的实现——哈希与 ERC 发布的向量逐字节一致（test/amm.test.ts）——而 foga meditate run 则是整个循环（src/node/meditation.ts、meditation-cycle.ts、src/tools/meditation.ts）：各项例程在本地运行（账户的角色和允许列表、技能包与其代币的匹配情况、存储的检查与压缩、进行中的投标以及文档与链上状态的核对、窗口的决策），四份文档根据 cell 的稳定状态重新构建，一份 report 通过账户的新增 maintenance 范围提交，只有承诺发生变化时版本才会递增；节点无法独自完成的事项会成为记录中的候选项，绝不会直接采纳。每个阶段都是一条事实记录，记录和报告都会被冻结，因此中断的循环恢复时会使用相同的 calldata；节点离线期间已挖出的报告会在新循环开始前完成协调；任何拿到记录和文档的人都能在链上重新推导每个哈希。内核现在能区分待处理和失败（OperationPending；catalog 会在 pending 阶段保持作业运行，并由同一请求继续执行），计划还能为自身预估费用储备（gasPerStep）。在包含注册表的 world 上诞生的 cell 会在出生时注册，并由 guardian 担任 controller；运行中的 cell 则可原地扩展——foga cell extend --covenants 8490 会将注册表加入其 world 文件、开放权限范围并完成注册，无需迁移。只有一条授权路径：账户的授权路径；单密钥 cell 的所有者配对仅为其自身开放，并会在角色分离时关闭。meditate_status 是一项公开读取操作，用于说明 FRESH 的含义——例程按时完成，而非一项认证。同日上线：OG 和一个加入的 cell 在 Sepolia 上原地扩展，其首轮循环已提交报告，并根据提供的记录重新计算（0.8.1 修正了显示内容）。第二阶段（0.8.2）是 watcher：开启 maintenance.auto 后，当必需层变为 DUE 或 OVERDUE（包括 controller 的要求），或运行时或 memory-skills 文档出现漂移时，节点会运行一个循环——仅针对这些层，因此每层都保持自己的节奏——并受检查频率限制，每次只运行一个循环，只有 OVERDUE 层才能通过冷却期限制，且受预算约束。调用方为 watcher，使用的仍是同一个 meditate_run 和同一组记录。尚未实现：十二契约基础集合（4c）。119 项测试。 4b（0.9.0，2026-11-09）。 一个单元会介绍自己并参与市场，而 ERC-8489（Agent 信息流范式，由同一位作者撰写）为两者提供了注册形态：一种范式（上下文的规则：载体、操作符、十三个维度，以及由哪个谓词获取哪个角色）、采用该范式的通道、角色绑定、四值检查、锚定和披露记录。它作为第十二项契约和第二个扩展（docs/flows.md）加入：七个上游合约和 FOGA 自有的 FogaIdentityVerifier（identity 谓词：主体的账户拥有 ERC-8004 身份，且其 ERC-8434 锚点处于 ACTIVE 状态——主体先完成绑定，注册表在部署时固定）已纳入计划和本地世界（56 个合约），上游 Sepolia 实例已接入，src/core/aifp.ts 是内核对此的视图（主体引用、JCS 范式 ID、谓词编码，以及依据 ERC 测试向量验证的描述符，见 test/aifp.test.ts）。FOGA 会在每个世界中注册 foga 家族的两种范式：foga:cell-source/v1（来源 + 存档：一个发布者、开放观察、主动拉取的不可变存档）和 foga:tender-market/v1（公共市场——不使用 intake 标签，因为提交内容是公开的；通过身份谓词执行 SUBMIT 和 RESPOND；以 TaskToken 的事件作为传输方式，不使用交付记录）。单元诞生时会以账户作为授权方打开自己的通道，并授予自己 SUBMIT；每次 docs_publish 都会锚定发布内容（先发布，再取代；相同内容绝不重复发布），并在有公开 URL 时记录向公众披露的情况；flow_admit 会预览身份谓词，并让单元进入市场，或根据注册表会得出的结果拒绝——NOT_SATISFIED、UNDETERMINABLE、VERIFIER_ERROR，绝不将它们混为一谈；tender_precheck 可以要求需求方拥有 SUBMIT 角色（flow 门控），并将历史角色与当前资格作为两项分别读取。监视器会锚定已发布的内容，并在符合资格后加入市场；foga cell extend --covenants 8489 可让正在运行的单元接入；foga flow bootstrap 是维护者在每条链上执行一次的操作（当注册表缺失时，它会将其加入单元的世界文件，并部署身份验证器）。尚未实现：十二契约基础集和 probe/2（4c）、市场的 ACDF 治理绑定、foga:direct/v1。127 项测试。0.9.1：Sepolia 引导设置已完成（OG 的账户控制 foga 家族，并作为市场 0x32643288… 的授权方；身份验证器位于 0x7d5301B3…），相关信息已记录在打包的世界中，因此加入 Sepolia 的单元会在诞生时打开通道，并获准进入市场；监视器还会记录此前已锚定、但当时尚无记录的发布内容的披露情况（绝不重复：会先读取通道记录）。 3e-1（0.7.0，2026-11-06）。 Phase 3 留下了一种情况：在公共链上诞生的单元，要经过四条命令和三个前置条件才能启动；而单命令路径（quickstart）启动的单元会随进程结束而消失。本次更新为持久运行的单元提供了单命令路径。foga join --chain sepolia（src/node/join.ts，docs/join.md）会创建或复用钱包，从包中获取该链的地址簿（现在随包附带 deployments/sepolia.example.json），等待身份获得资金（会打印地址、金额和水龙头；以太币到账后会自动继续），然后诞生单元、铸造并提供其技能、提交其文档，并启动节点；也可以使用存根运行（--run stub），这样单元无需模型或人员就能接下有资格承接的招标。每一步都由内核执行，因此同一条命令可从任何中断处恢复加入流程，且不会重复发送任何内容。单元位于 ~/.foga/cells/<network>/<name>，地址簿和技能包也会复制到其旁边，不受包安装位置影响。foga cell card（src/node/card.ts）是单元的自我描述，包含链、账户、Agent ID、带 Token ID 的技能、为其铸造招标的位置，以及它有公开入口时的访问入口；它以其他 Agent 所需的措辞呈现，且不调用链。become-a-cell 和新的资源 foga://docs/join 都以加入流程为主。工作由链上完成：test/join.test.ts 让一个陌生人针对使用存根运行的已加入单元铸造两份招标，两份都被接下、通过哈希锁验证器验收并完成结算，期间无人操作任何一方；两个单元之间不需要网络连接。链配置表（src/core/chains.ts）列出可加入的链；worlds/base-sepolia.json、optimism-sepolia.json 和 arbitrum-sepolia.json 是部署模板，同一密钥在每条链上对应同一地址。若 quickstart 和 join 的两个默认端口被占用，就会改用下一个空闲端口。docs/mcp.md 按客户端说明 HTTP 格式的入口配置（Claude Code 的 "type": "http"、Cursor 的 url、Windsurf 的 serverUrl，等等）。109 项测试。已于 0.7.4（2026-11-06）在真实环境中验证：一台机器上的单元使用 --run stub 加入，另一台机器上运行需求方，两者之间只有 Sepolia；文档技能（招标 47）和单元的自检探测（招标 51）都被接下、通过哈希锁验证器验收并获得付款。真实运行总结出的四项经验见 CHANGELOG 和 docs/loop-d.md 的“Two machines”，对应 0.7.1–0.7.4。

3d-3（0.6.0，2026-11-05）。 Phase 3 收尾时，参考单元已启动服务，并在公共链上完成最后一轮验收。OG 在 Sepolia 上通过任何单元都会使用的路径全新诞生（wallet new、cell new、cell init、docs publish、node serve——一个密钥，无需迁移；docs/og-deployment.md）：Agent 11261、已提供的技能、已上链的文档，以及通过 Sourcify 验证的 15 份合约；它以主机模式运行在 systemd 下，由 Caddy 代理，地址为 foga.finchip.ai，并已在 MCP 注册表中列为 io.github.garyyang-finchip/foga。与外部 Agent 一起在 Sepolia 上运行的 Loop D 已通过所有不变量检查项（docs/loop-d.md 的“On a public chain”）；本次发布记录了公共链带来的经验：工作目录对应一次运行，角色资金按带底价的方式计价，结算金额以招标自身的数据为准，日志扫描采用窗口范围。foga cell advise（src/node/advise.ts）会告诉运行中的单元接下来该做什么——首先将一个密钥分为所有者、操作员和监护人；quickstart、诞生和 serve 后都会打印建议项；首次运行有意保持精简。协定清单直接从 world 中读取（新增第 11 条协定无需修改代码），清单文件还增加了 services 槽位——维护者的目录，可拒绝；由参考单元在 /services.json 提供服务——详见 docs/extending.md。107 项测试。 3d-2（0.6.0-alpha.7，2026-11-03）。 3d 的第二个阶段，要解决的是一个细胞如何在其他 Agent 之间独立立足，遵循一个原则（docs/design-memo.md，第 10 节）：钱包是第一步，默认创建，绝不会成为停止的理由；身份属于自己；只有基因组会复制。foga wallet new（src/node/wallet.ts、docs/wallet.md）会在 Agent 自己的机器上生成密钥——默认是在 ~/.foga/wallet 下的 0600 文件中生成一个密钥——作为满足细胞所有角色需求的身份；--cell 用于彼此分离的所有者／操作者／监护人密钥组——绝不覆盖，不联网——而 foga quickstart 会在首次运行时创建默认钱包，并让此后创建的每个细胞都使用相同的密钥；每条 foga cell 和 foga node 命令上的 --wallet <dir> 都会从该目录读取相应角色的密钥。钱包也是一种凭证：Authorization: FOGA-EIP712 <envelope>（src/http/signed.ts、src/http/access.ts）是在细胞自身域中生成的 EIP-712 签名——绑定单个请求，只能使用一次；也可以是供客户端使用的、带静态请求头的会话——调用方是签名地址，其权限级别由 access.signers 授予（细胞自身的操作者或所有者、按地址或 ERC-8004 Agent ID 设置的允许列表、KYA 信誉阈值、默认权限）；/api、/mcp 和 /a2a 均接受此凭证，foga wallet sign 会输出凭证；每个细胞的 MCP 服务都包含提示词 become-a-cell 和资源 foga://docs/quickstart，供满足要求的 Agent 使用。foga cell docs build | publish | status（src/node/documents.ts、docs/documents.md）会根据单一配置生成细胞的文档——ERC-8004 注册信息、ERC-8434 AID 文档、ERC-8444 描述符、ERC-8454 单元、A2A Agent 卡片、server.json、带内容哈希的清单——并通过 /documents/* 和 /.well-known/* 提供这些文档，还会将它们作为操作者的密钥作业提交到链上（setAgentURI、setDocumentURI、updateDescriptor、publishVersion；只提交有变化的内容），再读回并交叉校验；docs_status 和 docs_publish 是目录中的第 30 和第 31 项能力。foga node preflight（src/node/preflight.ts）用于协调并检查就绪状态——世界、账户及其允许列表、预算、密钥、信誉、在工作进程中运行的技能、与链上记录比对的文档、公开 URL、模型——仅提供建议；用于 CI 时可加上 --strict。POST /a2a（src/a2a/、docs/a2a.md）是 A2A 1.0 的 JSON-RPC 绑定，卡片位于 /.well-known/agent-card.json：任何人都可以获取报价；具备行动级权限的调用方可以接受招标，将其作为一项任务执行目录中的作业；支持 GetTask、ListTasks、CancelTask，并按规范返回错误。foga world verify --sourcify（src/world/sourcify.ts、docs/world.md）会使用世界中每个由 FOGA 部署的合约各自编译时的标准 JSON 输入提交验证（forge build 现在会将 build-info 保存在制品旁边），并按运行时代码进行匹配；本地区块链上只进行试运行，CI 会对全部 47 个合约执行验证。OG 实例默认采用主机模式（foga node serve：所有入口、监控器，不含模型），需要时则可采用嵌入模式（foga node run：带模型的运行器）。七项新增的 Anvil 和离线测试（wallet、signed、documents、a2a、preflight、sourcify，以及扩展后的 quickstart）是发布门槛；现在，foga quickstart 最终会生成一个细胞，其文档已上链、卡片可以响应、A2A 入口可以报价。下一步是 3d-3：OG 部署运行手册、foga.finchip.ai、注册表列表、Sepolia Sourcify 验证、OG 细胞迁移至修订版 2，以及外部 Agent 在 Sepolia 上执行 Loop D。 3d-1（0.6.0-alpha.6，2026-11-02）。 这个包已发布到 npm，名称为 @finchip.ai/foga（0.6.0-alpha.4 和 alpha.5 已发布，后者修复了 Windows 启动器），因此 3d 的第一部分聚焦于两项功能，让你从零开始就能使用它。foga quickstart（src/demo/quickstart.ts、docs/quickstart.md）只需一条命令即可启动一个实时 cell：anvil、本地 world、一个新建的 cell（没有人持有它的密钥），以及它的两项技能；为它铸造两个 tender；启动节点服务（watchers、HTTP API、通过 Streamable HTTP 提供的 MCP）；检查两个接入方式（使用 act 级密钥通过 HTTP 完成握手并获取工具列表，以及使用 operator 密钥通过 stdio 完成同样的检查）；并打印和写入 MCP 客户端配置——Claude Desktop、Claude Code、Cursor，以及包含 URL 和 Bearer 密钥的 HTTP 配置——所有路径均已填写，存放在 ~/.foga/quickstart 下。Loop D 增加了 --model external（docs/loop-d.md）：启动节点服务而非运行节点，为提议者铸造 act 级密钥，协调器打印简报（接入方式、tender 的五个步骤、运行期间 Agent 周边会发生什么——不包含任何案例信息），然后等待 Agent 响应——可以是任何模型、任何运行时，也可以是使用 curl 的真人——并执行相同的恢复流程、相同的接入检查和相同的验收；证据会注明 Agent 名称，且不包含 runner ticks；doctor 会将 Agent 未处理的案例标记为 NotTested，而非 Fail；--compare 会跳过单次运行未触及的内容。test/loop-d-external.test.ts 通过 MCP 接入方式，让一个脚本化 Agent 驱动整个流程，所有判定均通过，其中也包括与保留的 stub 运行结果对比的模型无关性检查。其他改进：.gitattributes 确保所有文本文件使用 LF 换行符（包括启动器的 shebang）；prepare 脚本可编译直接从 git 安装的代码库；共享的 cell 创建逻辑（src/demo/birth.ts）和 anvil 辅助工具（src/demo/anvil.ts）为各个演示提供支持；文档中补充了 PowerShell 和 Windows 相关说明。3d 接下来的工作：foga node preflight、带有 setAgentURI 的 docs build/publish、A2A 卡片和入站映射、Sourcify，然后是 OG 部署操作手册、文档站点和注册表条目。 3c（0.6.0-alpha.4，2026-11-02）。 模型参与循环，验收检查记录，而非文字。src/node/runner.ts 是节点与模型协作的循环：每次迭代通过读取能力感知，将当前情况和工具目录交给模型，然后执行模型提出的操作——读取会立即执行；操作则通过 Catalog.invoke 执行，由三项检查作出决定，若遭到拒绝，会将拒绝结果返回给模型，让它再修订一次——并按哈希记录本次迭代（决策记录包含模型名称以及请求和回答的哈希；日志记录整份对话的哈希；绝不记录文本）。每次迭代都有上限（12 次工具调用、2 次操作），每日调用量也有限制（按存储中的记录统计模型调用次数）。两个适配器共用一个接口：anthropic（通过 fetch 调用 Messages API，密钥取自环境变量，模型名称在配置中指定）和 stub（确定性决策表，也会提出一次超出预算的投标，以展示证据如何证明关卡关闭）。foga node run 启动嵌入式节点——服务、监视器和运行器——且只使用操作员密钥。foga demo --loop-d（src/demo/loop-d.ts）是一次非脚本化运行：创建一个使用全新密钥的新单元；由独立的请求方进程按预先设定的顺序铸造案例 a–f（接受两份投标，在 skill、policy、verifier 处拒绝四份，并在 guardian 暂停期间遇到一份）；节点在首次提交后被终止并重启；除了运行器，还使用 HTTP 入口（同一请求只回答一次，同一作业使用另一个请求则发生冲突，同时铸造三个请求，其中第三个在发送任何内容前就因 budget 被拒绝）；最后生成一个证据文件，其中包含每条记录、各案例的结果，以及对操作员密钥签署的所有交易进行的扫描。foga doctor --loop-d 会与第 5 层一起评判运行结果：每项操作都必须经过允许的决策；拒绝时不广播任何内容；四本预算账目；操作员签署的交易均来自该账户且符合允许列表；案例结果符合预期；恢复过程和各入口均正常；并且——在运行两次的情况下——stub 和真实模型得出相同结果。该版本还修复了运行过程中暴露的一处竞态：目录的决策部分现在会让每个节点一次只执行一项操作，作业也会在作出决策时预留它将要转移的金额。test/loop-d.test.ts（anvil，不到一分钟）和 test/model.test.ts 是关卡测试；CI 会在运行创世过程所用的世界上运行 Loop D。docs/loop-d.md。 3b（0.6.0-alpha.3，2026-11-02）。 目录迎来第二和第三个入口。src/mcp/server.ts 使用官方 TypeScript SDK v2，根据目录为每个调用方构建一个 MCP 服务：工具列表定义调用方可以看到和执行的操作（一个写入能力最多包含三个工具，共用一个处理器——<name> 执行操作，<name>_simulate 运行所有检查但不发送任何内容，<name>_build 返回供调用方使用自己账户执行的调用——并带有静态注释）；结果是符合该能力输出架构的 structuredContent；被拒绝的操作会作为工具错误返回，其中包含 gate、原因和决策记录 ID；不符合条件的预检查则正常返回 eligible: false；提供世界、小区、策略、FOGA-Cell-v1 规范和兼容性矩阵的资源；以及一个提示词。两种协议版本都通过两种传输方式提供服务——以 2026-07-28 版（server/discover，无会话）为主要路径，同时以无状态形式支持 2025 年版本的 initialize 握手——而 foga node mcp 则通过 stdio 为本地客户端提供服务（持有密钥的操作员和构建级别的本地用户均可使用）。src/http/server.ts 是基于 node:http 的 HTTP 入口：通过 Streamable HTTP 提供 /mcp、POST /api/<capability>、健康状态和首页；无需凭据即可公开访问（读取和构建）；使用 Authorization: Bearer <key> 验证由操作员通过 foga node key new 创建的授权（仅存储其哈希）；边缘层检查 Host、Origin、请求体大小、内容类型和每个地址的速率限制，将权限拒绝映射为 403，将业务拒绝映射为 200 {ok: false, gate, reason, decisionId}。foga node serve 会在运行服务的同时运行这些监控器。本阶段的验收测试是 test/mcp.test.ts：在 anvil 上，使用固定为 2026-07-28 版的参考客户端，分别以旧版模式和自动模式，通过 HTTP 和 stdio 进行测试——包括公开用户的工具、密钥持有者从预检查到结算完成招标并使奖励到账户的全流程、线上的幂等性和冲突，以及所有边缘拒绝情形。scripts/pack-smoke.mjs（CI 步骤）会在干净目录中安装 npm tarball，并从该目录运行打包后的 CLI 和 MCP 服务；package.json 包含 mcpName，server.json 包含将在 3d 发布时使用的注册表清单。参见 docs/mcp.md。

3a-2（0.6.0-alpha.2，2026-11-02）。 内核成为其他 Agent 可以调用的节点。src/tools/ 是能力目录——包含 Loop D 路径上的 28 项能力，每项都声明其操作（读取、构建、执行、管理）、数据可见范围（公开、调用方、操作员）以及由谁执行操作——而 Catalog.invoke 是唯一的授权入口：调用权限、由策略引擎执行的业务授权（锚点和绑定、持有和提供的技能、奖励和截止时间、验收权限、预算），以及通过模拟账户自身的 gate 检查钱包权限；每次尝试执行操作，无论获准还是被拒，都会生成一条注明 gate 的决策记录。作业是业务单元，操作是其下的链上写入；同一作业只会应答一次，失败的作业会返回其失败信息，同一作业被用于另一个请求时则会产生冲突。src/node/ 是运行时：一个 cell.config.json、一个运行于内核之上且仅持有操作员密钥的节点、foga cell init（根据配置创建小区，单个小区的 T1）、foga cell migrate（迁移到新的 revision-2 账户，单个小区的 T9）以及监控器（心跳、招标发现、结算、安全）。CLI（foga cell …、foga node …）根据目录生成。本阶段的验收测试是 test/node-cli.test.ts：在 anvil 上，通过 CLI 且不使用 genesis 脚本创建一个小区，为其铸造技能，并通过七个 Loop D 案例——成功接取并结算两个招标，在正确的 gate 被拒绝五次（技能、策略、验证器、安全检查（暂停期间拒绝，恢复后允许）、预算）——然后迁移到新账户。参见 docs/node.md。 3a-1（0.6.0-alpha.1，2026-11-02）。 第 3 阶段将内核变成其他 Agent 可以调用的节点，而第一个切片为内核补上了公共服务所需、场景驱动器却不需要的能力：FogaCellAccount 修订版 2——操作员只能调用所有者加入允许列表的内容，绝不能调用转移资产的选择器；只有在启用且满足门控条件时，才会为账户签名；一个节点只持有一把密钥，即其 cell 的操作员，并拒绝使用可推导出任何其他角色的环境（foga keys export、foga keys check）；事务管理器会在记录中统计费用替换次数，因此即使重启也能维持限制，会对费用设上限，让同一签名者的操作一次只运行一个，并将密钥绑定到请求的哈希（同一密钥提交另一请求会产生冲突），而操作失败时会返回其失败结果，直到显式重试；作业与操作一同存储；技能工作进程在进程外、Node 的权限模型下运行这两个执行器。所有内容都通过针对进程内链的离线测试（test/tx-semantics.test.ts）以及在 anvil 上的 genesis 测试验证；现在 genesis 会自行开放每个 cell 的范围（193 项操作，166 项检查）。详情见 docs/kernel.md、docs/cell-account.md、docs/design-memo.md（第 9 节）和更新日志；备忘录中介绍了 3a-2 到 3d 会增加的内容。

Sepolia 运行（0.5.0，2026-11-01）。 世界 sepolia-11155111-20261101T043153Z：附加了 35 个上游参考部署，W 将套件中的 15 个合约添加进来；W 即官方 ERC-8004 注册表。Genesis T0–T9 从项目的 EC2 通过公共 RPC 运行：203 项操作，位于区块 12038641–12040082，诞生了三个 cell（ERC-8004 Agent 11255–11257）；A 铸造技能并为 B 的招标运行技能，群体组建并在由委员会裁决的招标中获得付款，托管合约退还了争议款项，守护者的停止命令在门控处生效，测量结果通过断言，A 的身份转移给 A-prime。完整世界的 doctor 检查结果：Pass 234、Fail 1（ARD fixture 注册表已知的较旧来源）、Unknown 2，第 5 层的全部 11 项标准均为 Pass。已提交三个文件：deployments/sepolia.example.json（世界）、deployments/sepolia.genesis.example.json（证据：检查、事实、每步证据、包含整个运行及其恢复过程的日志）和 deployments/sepolia.doctor.example.json。此次运行的经验——公共 RPC 集群中的节点在每个区块生成后会有一秒钟意见不一致，Sepolia 重新定价后的 gas 费用是 anvil 数据的 4.4 倍（世界和 genesis 共消耗 586 M gas），重放必须读取链的最新区块——记录在 docs/genesis.md（“Sepolia 运行”）、docs/kernel.md 和 0.5.0 更新日志中；现在各角色的 gas 预算采用实测的 Sepolia 数据并留有余量。

为 2c 构建（0.5.0-alpha.1 至 alpha.9）：

• 在公链上演练同一场景。 在 Sepolia 配置上运行 foga world deploy，会关联上游参考部署，并从同一捆部署中补充其记录在锁定版本下未提供的内容（在上游以版本 3 部署、无法绑定到版本 4 托管合约的 ERC-8471 栈，以及上游从未部署的两个 ERC-8447 资格模块），部署者为 W。Cell 在两个 ERC-8434 注册表中保持存续状态，world 会指定其中一个作为后备注册表（Sepolia 的 ARD Agent 类型锚定在 ARD 自己的 fixture 注册表上）。T7 会缩短锚点自身的存续窗口并等待，使其变为 STALE，在每条链上的操作方式都相同。
• 一个助记词生成十二个密钥，共用一个金库。 foga keys new 会在仓库外写入一个 BIP-39 助记词，并打印各角色的地址；只有 W 需要手动注资——每个步骤开始前，W 都会将每个角色的余额补至其下限的一半以上（这是按 Sepolia 上的 gas 预算、以该链当前费用计价），并在每个 Cell 创建时向其提供资本。foga genesis preflight 会打印计划、托管合约的管理员、证明材料和等待时间，但不会发送任何交易；foga world deploy 会在首次部署前检查部署者的余额。
• 公链交易处理。 公共端点每 4 秒轮询一次；如果交易在 120 秒收据等待后仍处于待处理状态，则会使用相同的 nonce 替换交易，费用提高三分之一，最多重试三次；恢复运行时，会识别某项操作中实际被挖出的任意一笔交易。每次状态读取都会固定在内核已见到的最高区块，因此，如果 RPC 集群中尚未导入最新区块的节点返回错误，系统会重试，而不会读取过期状态。
• 先演练，再运行。 CI 会在 anvil 上，从已部署的本地 world 构建一个 attach 模式的 world（scripts/attach-rehearsal.mjs：关联地址簿、通过 foga world deploy 添加 15 个合约、使用第二个 AIDRegistry 作为后备注册表），并在其上运行 preflight、genesis T0–T9 和 doctor：共 171 项检查，全部十一项标准均为 Pass。公共链计时配置文件（T5–T7 期间约等待五十分钟）和 Sepolia 操作手册见 docs/genesis.md 的“在公链上运行”。

自 2b（0.4.0-alpha.1）起：

• 谓词模式 ZK 路径。 FOGA 自有的电路 kya_predicate_count_v1（8 个记录槽，源集合深度为 16）可证明“在一个时间窗口内，至少有 K 条关于我的任务完成记录，由已承诺集合中的来源签名，且状态为 Accepted”，同时不泄露记录；Groth16PredicateKYAVerifierAdapter 将其作为方案 S_pred 接纳。A 在 T3 结束时证明其首次完成；适配器拒绝错误谓词（K = 2，但只有一次完成），验证器拒绝结果位被翻转的证明，注册表拒绝重放和过期 epoch。证明材料通过确定性的开发仪式在本地构建（npm run zk:predicate；CI 在缓存未命中时重新构建，并检查已提交的验证器是否与之匹配）。docs/zk.md。
• T6 — 争议。 C 通过世界的 ERC-8471 服务托管购买 A 的技能运行，该托管在 T0 绑定到 FOGA-Service-v1；A 发布 v2，并在承诺 v1 的条款下交付；C 提交申诉；声明版本验证器回答形式问题，FOGA-Council 则通过桥接层作出裁定；裁决为 Final Sustained，托管仅执行一次退款。一个承诺 v2 的对照调用完成结算并释放。
• T7 — 安全。 守护者暂停 A；绕过内核发送的交易在链上被账户的关卡拦截；允许列表中的降风险提现获准；运营者直接提交的交易被链接受，但无法归属到该单元；新的绑定无法绕过干预者持续有效的停止权限；resume 后 A 恢复工作；STALE 锚点会阻止承诺类调用，直到下一次心跳。
• T8 — 计量。 E 注册 foga.realized-net-cash-flow/1，并为单元 A 和蜂群声明观察收据：各自边界内已结算的流入计入，gas 计为成本，不可观测项目标记为缺失，绝不赋值；确定性解析器从链上重新计算这些数据，并拒绝将蜂群的招标金额计入 A 或引用未注册方法的收据。
• T9 — 继任。 A 通过其账户将 ERC-8004 Agent 转移给 A-prime：A 变为 STALE，A-prime 接管绑定，A 退役并指定其继任者，A-prime 发布新记录和文档，技能随之转移，其记录通过重新承诺再次获得采纳；持续有效状态、蜂群席位、单元和绑定均不继承。
• Doctor 第 5 层。 foga doctor --genesis <evidence.json> 将创世检查转化为逐标准判定；演示会在创世后运行该命令。
• 在 anvil 上约 100 秒内完成 187 项操作、166 项检查，全部通过（5 个 Groth16 证明）；每个步骤都能在注入崩溃后恢复，重放运行会重新检查仍然有效的内容，并将其余内容记录为已跳过。

来自 2a-2（0.3.0-alpha.1）：

• T4 — 组织。 W 发起一项待评审任务；B 组建一个与该任务绑定的群组（协调者和两名工作者，满足复合资格条件：已注册的 ERC-8004 Agent、ACTIVE 锚点、经证明的信誉 ≥ 2）；A 和 C 通过各自的账户加入；群组账户完成绑定；群组成了一个 AUF 单元，其中包含成员单元的固定版本。拒绝陌生人加入；遭撤销的声明会在质询时暂停成员资格，提交新的声明后即可恢复。
• T5 — 治理。 群组账户提交 finch-extract-verify 报告（基于固定测试夹具的确定性路径）；FOGA-Council（三名评审，两人即可作出决定）通过 FOGA 自己实例化的上游 ACDFTaskTenderAdapter 接受报告；工作者通过 SwarmDecisionAdapter 修订章程；第二个案例在未作出决定的情况下结束，等待期过后，由招标任务自身的 claimUnjudged 付款；群组以 ACHIEVED 状态结束。错误轮次的投票、非评审者的投票、过早执行或重复执行均会被拒绝。
• 凭证模式 ZK 路径。 A 的信誉也通过零知识方式证明：W 的证明者对 A 的承诺签署凭证，A 针对本注册表和纪元进行证明（Groth16，kya-public-v1），FOGA 自有的 Groth16KYAVerifierAdapter 将其作为记录中的签发者予以接纳。重放、重新指定目标以及纪元过期的证明均会被拒绝。证明器位于 prover/，是上游证明器的一个子包（npm run zk:install）。
• 125 项操作，89 项检查，在 anvil 上全部通过，耗时约 40 s；每一步都能在注入崩溃后恢复。

从 2a-1（0.2.0）开始：

• FogaCellAccount（contracts/src/FogaCellAccount.sol，15 项 Foundry 测试）。单元的主体：锚点、ERC-8004 所有者、资产持有者、履约者、采用者、主体和控制者均位于同一个合约账户中，并设有 ERC-8468 执行门（无绕过路径）、所有者／操作员／监护人／恢复角色、操作员权限范围（过期时间、每日价值上限）、用于承诺类选择器的 AID 状态门、ERC-1271 以及代币接收钩子。参阅 docs/cell-account.md。
• foga-core（src/core/）。每个 ERC 对应一个模块，包含视图、calldata 构建器和事件解码器；另有 RFC 8785 规范化，以及与上游向量验证一致的 ERC-8338 DAG-CBOR 打包器逐字节移植版本。
• foga-kernel（src/kernel/）。基于 node:sqlite 的操作存储；事务管理器对每个带键的操作只发送一次，并在崩溃后通过哈希和 nonce 恢复；通过各自账户驱动单元；覆盖所有 ABI 的事实、证据和 revert 解码器。参阅 docs/kernel.md。
• 创世阶段，T0–T3（src/genesis/，foga genesis run）。世界注册（两种 KYA 方案、FOGA-Cell-v1 安全规范）；创建三个单元，并为其配置绑定、ERC-8004 身份、AID 锚点和文档、经证明的信誉、ARD 记录及 AUF 单元；A 铸造两个真实技能包；B 发起哈希锁招标任务，A 发现任务、预先检查、在隔离工作者中履约、结算并收款。73 项操作，50 项检查，在 anvil 上全部通过；备忘录中的 loop-C 场景（提交后崩溃、广播前崩溃、重复运行、重置链）均在 CI 中重现。参阅 docs/genesis.md。

从 Phase 1 开始，实质内容保持不变：

• 已锁定的源码。 vendor/LOCK.json 通过提交记录固定了十个参考实现。foga vendor sync 会将它们具体化；后续不会修改这些源码。
• 单一构建产物包。 foga build 使用各自的编译器设置编译全部十个项目（五个使用 solc 0.8.24 配置，三个使用 solc 0.8.30 配置，两个 solc-js 仓库镜像到 0.8.28），生成 artifacts/bundle.json：包含 ABI、创建和运行时字节码、链接和不可变引用、编译器元数据，以及根据 AST 计算并与上游向量交叉核对的 ERC-165 ID（所有已发布的 ID 均匹配）。foga build --verify 会重新构建并验证哈希。
• 一条命令构建完整环境。 foga world deploy 按依赖顺序部署整个技术栈——共 56 个合约，包括外部库、ERC-8471 模块路由器、ERC-8490 注册表，以及配备 FOGA 身份验证器的 ERC-8489 注册表——注册四种 ARD 类型，并初始化 FOGA 的两个 ERC-8489 范式和默认招标市场。本地环境会使用 contracts/src/Identity8004Stub.sol 作为明确标注的 ERC-8004 身份注册表替代品；公共环境则会接入官方注册表。
• doctor。 foga doctor 会针对每个合约报告五个层面的检查结果——链和代码、接口、版本匹配、配置和权限、语义验证——并给出 Pass / Fail / Unknown / Not tested / Not applicable 判定。第 1–4 层会探测链；第 5 层会读取创世证据。doctor 运行结果可导出为 JSON-RPC 探测计划，并根据其他地方收集的结果重放，因此报告不受哪台机器能访问哪个 RPC 的影响。
• Sepolia 地址簿。 worlds/sepolia.json 记录了每个上游参考部署及其部署版本，包括清单中发现的三个衔接点（docs/version-lock.md）；已完成的环境及其 doctor 报告即为上述 2c 文件。

接下来：3d-3 将结束第 3 阶段——OG 实例迁移到具有公共端点（foga.finchip.ai）的 revision-2 账户，其文档和源码在 Sepolia 上通过验证，完成注册表上架，并由外部 Agent 在 Sepolia 上运行 Loop D；第 4 阶段将建设托管节点和支付功能。设计见 docs/design-memo.md。

快速开始

成为一个活生生的细胞 — 在 Sepolia 上，只需一条命令（Node 22.13+；无需 Foundry；参见 docs/join.md）：

npx -y @finchip.ai/foga join --chain sepolia

首次运行时，它会创建你的钱包（~/.foga/wallet：一个密钥、你的身份，以及在每条 EVM 链上都相同的地址），打印需要充值测试以太币的地址并等待到账，然后创建细胞（账户、ERC-8004 身份、锚点、记录、单元），铸造并提供它的两项技能，在链上提交其文档，启动节点，并打印细胞的名片 — 介绍它是什么以及如何联系它，供任何 Agent 查看。细胞会保存在 ~/.foga/cells/sepolia/<name>；再次运行同一命令即可恢复。--run stub 会让它自行接下符合条件的任务；--listen 0.0.0.0:8787 --public-url https://<host> 会向外界开放入口。工作通过链传递给细胞 — 需求方会为它提供的技能铸造 ERC-8414 任务 — 因此两个细胞之间无需网络连接；链就是握手。

本地试用 — 一条随进程结束的链，在其上运行一个细胞，整个过程只需 25 秒（需要 Foundry 的 anvil；参见 docs/quickstart.md）：

npx -y @finchip.ai/foga quickstart

@finchtech.ai/foga 是同一软件包的另一个作用域名称（alias/finchtech.ai：一个以相同版本运行 @finchip.ai/foga 的启动器），因此任一名称都可以运行任一命令。在 PowerShell 中，请将名称括起来：npx -y '@finchip.ai/foga' join --chain sepolia。

手动执行各个步骤，适用于形态不同的细胞（参见 docs/wallet.md、docs/node.md）：

npx -y @finchip.ai/foga wallet new                       # ~/.foga/wallet: one key (your identity, every role); prints the address to fund. --cell for the separated owner/operator/guardian set
foga cell new --wallet ~/.foga/wallet --name mine --world deployments/sepolia.example.json --store mine.sqlite --out mine.json --rpc <url>
foga cell init --config mine.json --wallet ~/.foga/wallet
foga node preflight --config mine.json --wallet ~/.foga/wallet
foga node serve --config mine.json --wallet ~/.foga/wallet
foga cell card --config mine.json                        # who you are, for any agent

在代码检出目录中，有三种方式可以开始，按要求从高到低排列：

# 1. Full reproduction (needs git, Node >= 22 and Foundry):
npm ci
npm run vendor:sync          # fetch the ten repositories at the locked commits
npm run bundle:verify        # rebuild artifacts/bundle.json and compare its hash
npm run test:contracts       # Foundry tests for FogaCellAccount and the ERC-8004 stand-in
npm run zk:install           # proving libraries for the ZK paths (prover/, separate from the kernel's dependencies)
npm run zk:predicate         # build FOGA's predicate circuit and its development proving key (10-60 min, once; optional)
npm run demo:genesis         # anvil + world deploy + doctor + genesis T0-T9 + doctor layer 5, all local

# 2. World and genesis only (Node >= 22 and Foundry's anvil, no Solidity build; the ZK paths are left out without their material):
npm ci && npm run demo:genesis

# 2b. The same show without a checkout, from the published package (Node >= 22.13 and anvil): a fresh chain, the 56 contracts,
#     the genesis T0-T9 operation by operation, then the doctor's per-standard verdicts — about half a minute
npx -y @finchip.ai/foga demo --genesis T9        # add --keep to leave the chain running afterwards

# 3. Containers (Docker with Compose):
docker compose up --build     # anvil + world + doctor + genesis; outputs land in ./deployments

针对运行中节点的创世流程，分步执行：

npm run foga -- world deploy --world worlds/local.json --rpc http://127.0.0.1:8545 --out deployments/local.json
npm run foga -- genesis run --world deployments/local.json --rpc http://127.0.0.1:8545 --until T9
npm run foga -- genesis status --world deployments/local.json         # the operation store
npm run foga -- doctor --world deployments/local.json --genesis deployments/local.genesis.json   # layer 5 from the evidence

中断后恢复（再次运行同一命令，会重放已完成的操作并继续）。demo --keep 会让其 anvil 在后台运行并返回：

npm run foga -- demo --keep --genesis T2                                                           # chain, world, doctor, T0-T2
npm run foga -- genesis run --world deployments/local.json --until T9 --crash-after T3.A.submit   # exits 75 after the submit is broadcast
npm run foga -- genesis run --world deployments/local.json --until T9                              # recovers the submit by hash, settles, carries on

针对运行中节点：

npm run foga -- world deploy --world worlds/local.json --rpc http://127.0.0.1:8545 --out deployments/local.json
npm run foga -- doctor --world deployments/local.json --rpc http://127.0.0.1:8545 --out deployments/local.doctor.json

针对 Sepolia（需要机器能够访问的 RPC）。对已连接的地址簿运行只读诊断：

FOGA_RPC_URL=$SEPOLIA_RPC_URL npm run foga -- doctor --world worlds/sepolia.json --attach --out deployments/sepolia.doctor.json

在该链上进行创世 — 用一个助记短语对应十二个角色，手动为 W 充值，从资源包补全世界，执行预检，然后运行（使用公开窗口需 1.5–2.5 小时；中断后再次运行同一命令即可恢复）：

npm run foga -- keys new                                   # writes ~/.foga/genesis.mnemonic, prints the addresses; fund W
export FOGA_MNEMONIC_FILE=~/.foga/genesis.mnemonic
npm run foga -- world deploy --world worlds/sepolia.json --rpc $SEPOLIA_RPC_URL
npm run foga -- genesis preflight --world deployments/sepolia.json --rpc $SEPOLIA_RPC_URL
npm run foga -- genesis run --world deployments/sepolia.json --rpc $SEPOLIA_RPC_URL --until T9
npm run foga -- doctor --world deployments/sepolia.json --rpc $SEPOLIA_RPC_URL --genesis deployments/sepolia.genesis.json

或者通过任何有 RPC 的中继分两步完成 — 在这里导出计划，在那里收集结果，随处进行评估：

npm run foga -- doctor --world worlds/sepolia.json --attach --export-probe sepolia.probe.json
node scripts/relay.mjs $SEPOLIA_RPC_URL sepolia.probe.json > sepolia.results.json
npm run foga -- doctor --world worlds/sepolia.json --attach --import-results sepolia.results.json --out deployments/sepolia.doctor.json

离线构建：如果机器无法访问 solc 二进制文件镜像，请使用 scripts/install-solc.sh 从 Solidity GitHub releases 下载三个静态二进制文件，并导出 FOGA_SOLC_DIR。

较旧的 Linux 版本（Amazon Linux 2 和 2023、CentOS 7、Debian 11 等）：常规 Foundry 二进制文件需要 glibc 2.35，因此会报错 version `GLIBC_2.35' not found。scripts/install-foundry.sh 会将固定版本（v1.7.1）的静态链接构建版本安装到 ~/.foga/foundry；为 foga demo 导出 FOGA_FOUNDRY_DIR=~/.foga/foundry，或者将该目录放在 PATH 最前面，以便在任何地方使用其中的 anvil、forge 和 cast。

目录结构

artifacts/           bundle.json (+ .sha256): the compiled ten-ERC stack and FOGA's contracts, committed and CI-verified
build/               build profiles per repository and the README-published interface ids
contracts/           FOGA's own contracts: FogaCellAccount, Identity8004Stub (local stand-in), FogaIdentityVerifier (the ERC-8489 identity predicate), zk/ (the predicate verifier and its KYA adapter), Foundry tests
deployments/         world files, doctor reports, genesis evidence (local outputs are gitignored; examples are kept)
prover/              the ZK proving sub-package: run.cjs bridge (credential and predicate proofs), build-predicate.mjs (the development ceremony), its own dependencies
zk/                  circuits/ (kya_predicate_count_v1.circom) and build/ (verification_key.json committed; the proving key is rebuilt locally)
docker/, docker-compose.yml
deploy/              the OG host assets: foga-og.service (systemd, host mode), Caddyfile, og.env.example (docs/og-deployment.md)
site/                 the documentation site for GitHub Pages (docs.foga.finchip.ai): index.html, llms.txt, CNAME
docs/                design memo, compatibility matrix, version lock, build, world, doctor, cell account, kernel, genesis, zk, node, mcp, loop-d, quickstart, join, wallet, documents, a2a, propagation, extending, meditation (ERC-8490), flows (ERC-8489), specification (FOGA-Cell-v1 and v2), og-deployment; examples/ (client configurations)
scenarios/skills/    the two ERC-8338 skill packages of the genesis: foga-probe, finch-extract-verify
scenarios/fixtures/  the pinned document finch-extract-verify works on in T5 and T7
scenarios/flows/     FOGA's two ERC-8489 paradigm descriptors: cell-source.v1 (the cell's self-description), tender-market.v1 (the public market, a template filled with the world's verifier and registry)
scripts/             install-solc.sh, install-foundry.sh, relay.mjs, pack-smoke.mjs (the npm tarball run from a clean install), release-smoke.mjs (the release check's assertions)
src/                 TypeScript: build/ (vendor + bundle), world/ (plan + deploy), doctor/ (probe + evaluate),
                     core/ (foga-core: one module per ERC incl. acdf, adrf, swarm, amm (ERC-8490), aifp and paradigms (ERC-8489), measure, canonicalization, DAG-CBOR packager),
                     kernel/ (store, transaction manager, cell, kernel), genesis/ (roles, operator scope, probe (foga.probe/2), extract, skill worker, zk, scenario T0-T3, t3-zk, t4..t9, twelve (ERC-8490 and ERC-8489 in the genesis), runner),
                     tools/ (the capability catalog: types, catalog, read, tenders, identity (skills), documents, meditation, flows, specification, admin), node/ (config, keys, wallet, node, policy, init, migrate, extend, watchers, documents, preflight, meditation, meditation-cycle, meditation-watch, flows, flows-watch),
                     mcp/ (the MCP server built from the catalog), http/ (the HTTP API, MCP over Streamable HTTP, API keys, signed callers), a2a/ (the A2A 1.0 binding and card),
                     node/runner.ts and node/model/ (the runner, the stub and anthropic adapters), demo/ (the Loop D demander, orchestration and evidence, quickstart), world/sourcify.ts,
                     cli.ts, cli-cell.ts (foga cell / foga node)
test/                unit tests: bytecode and interface ids, skill packages, canonicalization, operation store, transaction semantics against an in-process chain (mock-chain.ts), keys, policy gates, catalog, cell config, swarm/ACDF vectors, extractor, measurement resolver, doctor layer 5, sourcify; node-cli.test.ts (the Loop D cases through the CLI on anvil), mcp.test.ts (the entrances over MCP and HTTP on anvil; helpers/anvil-cell.ts births the cell), model.test.ts (the stub's table, the Anthropic adapter against a stand-in API, the Loop D verdicts), loop-d.test.ts (the unscripted run with the stub on anvil), loop-d-external.test.ts, quickstart.test.ts, wallet.test.ts, signed.test.ts, documents.test.ts, a2a.test.ts, preflight.test.ts (3d, on anvil); amm.test.ts (ERC-8490 hashing against the upstream vectors in fixtures/amm/, the catalog's pending semantics), meditation.test.ts (enrollment, cycles, demand, policy, the served documents, the extension in place, on anvil); aifp.test.ts (ERC-8489 identifiers, encodings and descriptors against the upstream vectors in fixtures/aifp/), flows.test.ts (the world's flows, a cell's channel, anchors, the market's admission, the flow gate, extension in place, served documents, on anvil); tenders-read.test.ts (a tender's submission count and entries read as one, the race scripted, offline)
vendor/              LOCK.json (sources are materialized here and gitignored)
worlds/              world configs: local.json (deploy), sepolia.json (attach)

命令

foga vendor sync | verify
foga build [--verify] [--solc-dir <dir>] [--only <repo,repo>]
foga bundle info
foga world deploy --world <config> [--rpc <url>] [--out <file>] [--resume] [--gas-multiplier <x>] [--allow-chain-mismatch] [--no-flows]
foga world attach --world <config> [--out <file>]
foga world verify --world <world.json> --sourcify [--dry-run] [--only <id,id>] [--server <url>] [--out <dir>] [--build-info <dir>]   source verification from the bundle's own compiler runs
foga doctor --world <world|config> [--attach] [--rpc <url>] [--out <report>] [--export-probe <file>] [--import-results <file>] [--genesis <evidence>]
foga probe relay-script
foga genesis run --world <world> [--rpc <url>] [--until T0..T9] [--store <file>] [--out <evidence>] [--zk auto|require|skip] [--crash-after <key>] [--crash-before <key>]
foga genesis status --world <world> [--store <file>]
foga keys new [--out <file>] | show | export --role <role> [--out <file>] | check
foga wallet new [--name <n> | --dir <dir>] [--cell] | show [--rpc <url>] | sign (--config <cfg> | --url <node> | --cell <acct> --chain-id <n>) [--role] [--ttl <s>] [--agent-id <id>] [--method --path [--body]]
                                                                          an agent's own key (the first step; --cell for the separated owner/operator/guardian set), and a signed Authorization header for a cell
foga demo [--port <n>] [--keep] [--genesis <T0..T9>]
foga cell list [--public] | schema <capability>
foga cell new --name <cell> --world <world.json> --store <ops.sqlite> --out <cell.config.json> (--wallet <dir> | --owner <addr> --operator <addr> --guardian <addr>)
foga cell init --config <cell.config.json> [--wallet <dir>] [--capital-wei <n>]          (owner key)
foga cell migrate --config <cell.config.json> --to <new.config.json> [--operator <addr>]   (owner key)
foga cell adopt --config <cell.config.json> [--wallet <dir>]         a cell born before FOGA-Cell-v2 adopts it as a runtime-enforced second binding (owner key); foga cell spec says which version a cell operates under
foga cell skill update --skill <name> --config <cell.config.json> [--wallet <dir>]   commit the program's new package of a held skill to its token (ERC-8338 updateSkill; operator key); a joined cell's own copy of the package is refreshed from the program's
foga cell extend --covenants 8490|8489 --config <cell.config.json> [--wallet <dir>] [--registry <addr> | --from <world.json>]   a running cell onto a covenant the program gained, in place (owner key)
foga cell docs build | publish | status --config <cell.config.json> [--wallet <dir>]     the cell's documents, served and committed on chain (publish: operator key)
foga cell <capability> --config <cell.config.json> [--wallet <dir>] [--mode simulate|build|act] [--<field> <value> ...] [--json '<input>']
foga node preflight --config <cell.config.json> [--wallet <dir>] [--no-executors] [--no-network] [--out <report.json>] [--strict]   the readiness reconciliation; sends nothing
foga node tick | watch --config <cell.config.json> [--interval <s>]      (operator key alone)
foga node mcp --config <cell.config.json>                                 MCP over stdio (= foga mcp; the operator with FOGA_OPERATOR_KEY[_FILE] or --wallet, reads and builds without)
foga node serve --config <cell.config.json> [--listen <host:port>] [--no-watch]   host mode: the HTTP API, /mcp, /a2a, the documents, /healthz, the watchers; no model
foga node key new --config <cell.config.json> --id <id> [--level read|build|act] [--visibility public|caller|operator] [--note <text>]
foga node run --config <cell.config.json> [--model stub|anthropic] [--listen <host:port> | --no-http] [--interval <s>] [--once | --ticks <n>] [--transcripts <dir>]
                                                                          the embedded node: server, watchers and the runner (operator key alone)
foga meditate status | run [--layers] [--trigger] [--dry-run] [--job-id] | enroll | policy | controller --to <addr> | demand | floor | pulse --config <cell.config.json> [--wallet <dir>]
                                                                          the cell's own maintenance, ERC-8490 (docs/meditation.md): status for anyone, a cycle with the operator key, the rest the owner's or the guardian's
foga flow status | roles --subject <addr> | open | admit | anchor | disclose | bootstrap --config <cell.config.json> [--wallet <dir>]
                                                                          the cell's information flows, ERC-8489 (docs/flows.md): the channel and the market for anyone, admission and anchors with the operator key, the opening and the maintainer's bootstrap the owner's
foga demo --loop-d [--model stub|anthropic|external] [--model-name <name>] [--seed <n>] [--no-recovery]   anvil, the world, then Loop D judged by the doctor
foga loop-d run --world <world.json> --rpc <url> [--dir <dir>] [--out <evidence.json>] [--model] [--model-name] [--seed] [--no-recovery] [--listen] [--wait <s>] [--idle <s>]
foga doctor [--world <world.json>] --loop-d <evidence.json> [--compare <evidence2.json>] [--out <report.json>]
foga quickstart [--dir <dir>] [--wallet <dir>] [--port <n>] [--listen <host:port> | --no-serve] [--name <cell>] [--no-tenders] [--exit]   one command to a live cell (the wallet first) and its client configuration

开发期间，CLI 使用 npm run foga -- <args> 从源代码运行；npm run build 会将其编译到 dist/，供 foga 二进制文件使用。

原则

• 十个参考实现均按原样使用。组合这些实现时发现的差距会作为独立更改提交回上游；FOGA 不保留任何分叉。
• FOGA 从不更改编译条件，只负责协调。资源包会记录编译器、设置、源代码哈希和构建输入，以便任何人都能重新构建。
• 世界文件会注明其链、资源包哈希、部署批次，以及分叉时的源区块，因此两个本地 chain-id-31337 世界不会混淆。
• 诊断工具所作的每项判断都会附带五种结论之一；绿色的 ERC-165 探测结果绝不会被描述为完全兼容。
• 细胞只能通过其账户行事，而账户只能通过其门控合约行事。内核只发送一次每项操作，先记录再广播，并在重试前询问链。

许可证

本仓库中的代码采用 Apache-2.0 许可证。artifacts/bundle.json 中的编译产物基于上游仓库构建，这些仓库采用 CC0-1.0 许可证（上游引入的 ARD 材料采用 Apache-2.0 许可证）；详见 NOTICE。