hierarchical-codex

hierarchical-codex 是面向原生 Codex 子代理的确定性 MCP 控制平面。Codex 仍然通过 spawn_agent 创建 UI 可见的 Sol → Terra → Luna 线程；本项目为这些线程提供持久状态、策略门控、预算、工件、证据工作流和恢复协议。

状态：工程 MVP。控制平面、Codex 项目集成、钩子、测试和运维文档均已实现。在每个目标 App/IDE 部署上验证模型可用性和确切的 Codex 核心版本。

设计选择

本项目遵循一条明确的路线：

模型驱动的生成；代码强制的约束。

Codex native execution plane
  spawn_agent / wait_agent / send_message / Subagents UI
                  |
                  | task_id in TaskEnvelope
                  v
TypeScript MCP control plane
  SQLite task ledger / leases / budgets / artifacts / evidence / audit
                  ^
                  |
Codex Skills + Profiles + Hooks
  orchestration policy / model-effort routing / spawn veto / stop checks

MCP 和钩子不会创建原生线程。Sol 或 Terra 模型调用原生 spawn_agent；代码验证并记录周边工作流。

Related MCP server: dingdawg-governance

已实现能力

• 带乐观版本的任务与子任务账本。

• 直接父级角色策略：Sol 主管 → Terra 协调者 → Luna 叶子节点。

• 模型/投入矩阵：

  • Sol：high、xhigh、max

  • Terra：xhigh、max

  • Luna：high、xhigh、max

• 感知依赖的就绪判断与有界子代理分配。

• 带过期时间的 worker 租约、心跳、释放与安全回收。

• 分层级的 token、成本、墙钟时间、工具调用与子代理数量预算。

• 内容寻址的工件存储，带有界读取。

• 候选 → 已检查 → 已验证 → 已提交的证据门控。

• 生产者/审查者分离。

• 基于请求哈希的幂等变更与仅追加的审计事件。

• 重启或上下文压缩后的恢复快照。

• 项目作用域的 Codex Skill、Agent 配置文件、MCP 配置与钩子。

要求

• Node.js 22.5 或更高版本。开发中使用 Node 26。

• Python 3.10 或更高版本，用于 Codex 生命周期钩子。

• Codex 0.148.0 或更高版本是推荐的生产基线，支持原生多代理工具、自定义代理、MCP 与钩子。

• 一个受信任的 Codex 项目，以便加载 .codex/config.toml 和项目钩子。

快速开始

cd "/mnt/tools/others/codes/web project/hierarchical-codex"
npm install
npm run check
npm run doctor

然后：

1. 在 Codex App、Codex CLI 或 Codex VS Code 扩展中打开本仓库根目录。npm run doctor 不会将 skill 安装到 ChatGPT；App 必须将此文件夹用作其工作区。

2. 在提示时信任该项目。未受信任的项目会隐藏 .codex skills。

3. 使用 gpt-5.6-sol 开始一个新的根对话（skills 在启动时加载）。

4. 输入 $ 并选择 prism，或调用 $prism <mission>。如果选择器为空，AGENTS.md 仍会指导根 Sol。

5. 在 Subagents UI 中查看原生子代理活动，并通过 MCP 工具查看持久状态。

要在 VS Code Codex 扩展或 CLI 中从其他文件夹使用完整技术栈，请在 npm run build 之后运行 npm run install:user。参见 docs/USER_INSTALL.md。不要将此仓库的 .codex/config.toml 复制到 ~/.codex；那会将 Sol 固定为默认模型并阻止普通子代理。

项目 MCP 配置以仓库根目录作为工作目录启动 node dist/cli.js。源代码更改后运行 npm run build。

开发命令

npm run dev          # Run the stdio MCP server from TypeScript
npm run doctor       # Validate runtime and Codex integration files
npm run test         # Unit and integration tests
npm run typecheck    # Strict TypeScript checks
npm run lint         # ESLint
npm run format       # Prettier
npm run build        # Compile dist/
npm run check          # Full local quality gate
npm run install:user   # Install skill, agents, hooks, and MCP into ~/.codex
npm run doctor:user    # Verify the user-global install
npm run uninstall:user # Remove the managed user-global files

MCP 服务器将协议消息写入 stdout。应用程序日志必须使用 stderr；stdout 日志会破坏 stdio MCP 传输。

运行时状态

默认情况下，状态是项目本地的，并被 Git 忽略：

.hierarchical-codex/
├── control-plane.sqlite
└── artifacts/
    └── <sha-prefix>/<sha256>

用户全局安装（npm run install:user）将账本存储在 ~/.local/share/hierarchical-codex/，以便 Codex MCP 沙箱可以写入。如果该目录不可写，服务器会回退到临时路径，并在 stderr 上记录所选的主目录。

配置环境变量：

• HIERARCHICAL_CODEX_HOME

• HIERARCHICAL_CODEX_DB

• HIERARCHICAL_CODEX_ARTIFACTS

• HIERARCHICAL_CODEX_MAX_ARTIFACT_BYTES

• HIERARCHICAL_CODEX_DEFAULT_LEASE_SECONDS

• HIERARCHICAL_CODEX_MAX_LEASE_SECONDS

• HIERARCHICAL_CODEX_EVENT_PAGE_SIZE

MCP 工具

任务：

• mission_create

• mission_get

• mission_close

子任务与租约：

• task_allocate

• task_get

• task_claim

• task_start

• task_heartbeat

• task_release

• task_block

• task_fail

• task_cancel

• task_supersede

• task_set_effort

• task_commit

工件与证据：

• artifact_put

• artifact_get

• result_submit_candidate

• result_check

• result_verify

核算与恢复：

• budget_report

• recovery_snapshot

有关契约，请参见 docs/API.md；有关编排顺序，请参见 docs/PROTOCOL.md。

仓库结构

.agents/skills/             Codex orchestration Skill
.codex/agents/              Sol/Terra/Luna custom profiles
.codex/hooks/               Python policy gates
.codex/config.toml          MCP and native agent configuration
src/domain/                 State and policy definitions
src/infra/                  SQLite repository and artifact storage
src/mcp/                    MCP tool registration
tests/                      Control-plane, policy, and hook tests
docs/                       Architecture, protocol, operations, ADRs, records

重要边界

• 外部 MCP 代码无法调用内部的原生 spawn_agent 注册表。

• 钩子可以拒绝、重写或添加上下文，但 SubagentStart 无法在子代理创建后阻止它。

• 原生 UI 状态仅用于观察；SQLite 是持久化工作流的数据源。

• 此 MVP 是单主机的。SQLite 将变更串行化，但并非分布式共识系统。

• token 使用量由代理/主机报告；MCP 服务器无法独立计量模型 token。

• 该仓库目前为 UNLICENSED；在对外分发之前请添加明确的许可证。

文档

• Architecture

• Protocol

• MCP API

• Codex integration

• User-global VS Code / CLI install

• Operations

• Security model

• Development guide

• Test strategy

• Roadmap

• Changelog

• Implementation record

• Architecture decisions