使用说明

A unified MCP control plane for local and remote services.

Clarity Runtime是一个轻量级的运行时+网关，用于从一个地方运行、注册和操作MCP服务。

它旨在与Clarity编译器工作流配对，因此服务入职可以成为一个命令：

clarityc start server.clarity

为什么选择Clarity Runtime？

MCP操作通常是分散的：

每个客户端都需要单独的MCP接线
本地和远程服务器的管理方式不同
运行状况、日志和界面可见性没有共享的状态表

Clarity Runtime将其集中到一个控制平面守护进程中(clarityd)以及一个操作员CLI(clarityctl).

这给了你什么

代理客户端的单一网关端点
确定性服务标识（无需手动命名）
持久服务注册表和生命周期管理
每个服务的界面快照（工具/资源/提示）
操作和调试状态页面
Codex和Claude的一次性客户端引导钩子

建筑

               +----------------------+
               |     clarityctl       |
               | add/start/stop/etc.  |
               +----------+-----------+
                          |
                          v
+-------------------------+--------------------------+
|                     clarityd                       |
|  registry | lifecycle supervisor | interface cache |
+-------------------------+--------------------------+
                          |
                  +-------+--------+
                  |   MCP Gateway  |
                  +-------+--------+
                          |
           +--------------+--------------+
           |                             |
           v                             v
   Local Clarity MCPs             Remote MCP Services
   (compiled to WASM)             (HTTP transports)

安装+启动

# 1) Install and build once
npm install
npm run build

# 2) Start the runtime
npx clarityd

# Optional: require auth token for all API/MCP calls
# export CLARITYD_AUTH_TOKEN=your-token
# npx clarityd --auth-token your-token

# 3) Add a local service from source (mcp1 -> ./mcp1.clarity)
npx clarityctl add mcp1

# Optional: add all .clarity services in a folder
npx clarityctl add-all ./examples --recursive

# 4) Inspect + wire clients once
npx clarityctl list
npx clarityctl bootstrap --clients codex,claude --transport http --endpoint http://localhost:4707/mcp --update-agents-md

打开控制层： http://localhost:4707/status

默认情况下，Bootstrap不是自动的。跑 clarityctl bootstrap --clients codex,claude --transport http --endpoint http://localhost:4707/mcp 一次（或保持 stdio 如果您更喜欢进程管理桥模式），或使用状态页面“客户端引导配置”部分配置和验证路径。添加 --update-agents-md 还可以在工作区中打乱幂等的受管Clarity默认块 AGENTS.md.

clarityctl add <name> 编译 <name>.clarity 到 .clarity/build/<name>.wasm，然后注册并启动它。

对于本地开发（没有构建工件），您仍然可以使用：

npm run dev:daemon
npm run dev:ctl -- list

启用身份验证后，传递 --auth-token <token> 到 clarityctl （或设置 CLARITYD_AUTH_TOKEN/CLARITY_API_TOKEN 在环境中）。

命令行界面

clarityctl add <service_or_source_path>
clarityctl add-all [dir] [--recursive]
clarityctl add-remote --endpoint <url> --module <name> [--transport streamable_http|sse_http] [--auth-ref <name>] [--timeout-ms <ms>] [--allow-tools <a,b,c>] [--max-payload-bytes <bytes>] [--max-concurrency <n>]
clarityctl list
clarityctl status
clarityctl start <service_id>
clarityctl stop <service_id>
clarityctl restart <service_id>
clarityctl introspect <service_id>
clarityctl remove <service_id> [--cleanup-artifacts]
clarityctl details <service_id> [--log-limit <n>] [--event-limit <n>] [--call-limit <n>]
clarityctl logs <service_id>
clarityctl auth providers
clarityctl auth validate <auth_ref>
clarityctl auth list-secrets
clarityctl auth set-secret <auth_ref> <secret>
clarityctl auth delete-secret <auth_ref>
clarityctl bootstrap --clients codex,claude [--transport stdio|http] [--endpoint <url>] [--update-agents-md]
clarityctl bootstrap-remove --clients codex,claude
clarityctl doctor

clarityctl doctor 现在验证守护进程连接、编译器可用性和本地构建工作区就绪性。

质量命令：

npm run lint
npm run format
npm run test
npm run test:coverage

当前状态

针对v0.9基线实施：

服务契约和清单模式(clarity.runtime/v1)
持久注册表(.clarity/runtime/registry.json)
后台程序HTTP API和状态页
添加/列出/启动/停止/重新启动/内省/删除流
网关 /mcp JSON-RPC端点(initialize, ping, tools/list, tools/call, resources/list, prompts/list)
内置运行时控制MCP工具(runtime__status_summary, runtime__list_services, runtime__get_service, runtime__get_logs, runtime__start_service, runtime__stop_service, runtime__restart_service, runtime__refresh_interface, runtime__unquarantine_service, runtime__remove_service, runtime__get_audit, runtime__get_agent_runs, runtime__get_agent_events, runtime__validate_auth_ref, runtime__auth_provider_health, runtime__list_auth_secrets, runtime__set_auth_secret, runtime__delete_auth_secret)
内置的Clarity辅助MCP工具(clarity__help, clarity__sources, clarity__project_structure, clarity__ensure_compiler, clarity__bootstrap_app)用于默认语言指导、源代码发现、应用程序脚手架、编译器准备/安装检查和一次调用引导
门控MCP自我配置工具(runtime__register_local, runtime__register_remote, runtime__register_via_url, runtime__apply_manifest)受到保护 CLARITY_ENABLE_MCP_PROVISIONING=1
stdio桥接模式 clarityctl gateway serve --stdio
编译器通过以下方式辅助入职 clarityctl add <service> （编译+注册+启动+反思）
本地服务的本地函数执行工具(<namespace>__fn__<exported_function>)
基线远程策略控制（超时+允许的工具+有效负载大小+并发清单策略+可选主机分配列表）
Codex/Claude配置文件的引导编写程序
持久运行时遥测存储(.clarity/runtime/telemetry.json)用于跨守护进程重启的事件+服务日志
代理编排可观察性(agent.* 事件， /api/agents/* API、UI Agents 选项卡）
脱视觉端点/工具，可选本地工件清理
端到端运行时集成测试，涵盖API/MCP注册/调用/移除生命周期

尚未实施：

远程身份验证/策略隔离强化，以实现更严格的多租户信任边界
运行时TypeScript聊天执行器桥的原生Clarity编排替换(RUNTIME-HITL-CLARITY-001)

路线图

[x] 运行时编译器路径(clarityctl add <service>)
[]本机编译器命令(clarityc start <file.clarity>)in LLM-lang
[x] 添加策略引擎基线（超时、分配列表、并发性、有效负载限制）
[]完成远程身份验证/策略隔离强化（提供程序后端+验证+文件秘密生命周期着陆）
[x] 添加MCP自我配置工具（LLM可以通过MCP注册/安装服务，并获得批准+策略门）
[x] 添加隔离/恢复和更丰富的健康诊断
[x] 添加界面差异和审计/事件时间线
[x] 添加代理可观察性（运行摘要+时间线+UI选项卡拆分）

进度快照

区域	状态	注释
注册表+生命周期	完成	持久服务记录、启动/停止/重新启动、健康状态
网关MCP传输	完成	`/mcp` 带列表/呼叫路由的JSON-RPC
作为MCP控制平面运行	完成	`runtime__*` 用于状态、服务操作、日志、审计、隔离恢复的工具
Stdio网关网桥	完成	`clarityctl gateway serve --stdio` 转发到守护进程网关
远程MCP代理	完成（基线）	初始化/自检/工具转发
编译器驱动的入职培训	正在进行中	运行时端已完成； `clarityc start` 存在于 `LLM-lang` 代表们 `clarityctl add`；保持跨回购合同/版本一致性
本地函数执行	完成（基线）	`<namespace>__fn__*` 从wasm导出中发现并通过编译器运行时执行的工具
进程中WASM主机执行	完成	本地函数工具在运行时通过WASM实例化/调用直接执行
身份验证/策略强化	进行中	超时/允许的工具/有效载荷大小/并发性/已实现主机分配列表基线；身份验证提供者后端(`legacy env`, `env`, `file`, `header_env`)+添加了验证/秘密生命周期工具；查询令牌身份验证路径现在仅限于本地SSE；隔离政策加强待定
MCP自我配置	完成（门控）	`runtime__register_local`, `runtime__register_remote`, `runtime__apply_manifest` 后面 `CLARITY_ENABLE_MCP_PROVISIONING=1`
持久审计/日志持久化	完成	事件+服务日志持久化到 `.clarity/runtime/telemetry.json` 并在守护进程启动时重新加载
代理可观察性	完成（基线）	`agent.` 事件持久性， `/api/agents/` API和状态UI `Agents` 运行/时间线可见性选项卡
删除+清理	完成	`DELETE /api/services/:id` 和 `clarityctl remove` 具有可选的本地工件清理功能
运行时集成测试	完成（基线）	注册/启动/内省/调用/移除的API/MCP测试结束

规格

运行时规范： docs/spec/v1/runtime-spec.md
清单架构： schemas/mcp-service-v1.schema.json
分层要求： docs/requirements/layered-runtime-requirements.md
共享语言要求摄入： ../LLM-lang/docs/runtime-cli-language-requirements.md
v0.9路线图： docs/roadmap/v0.9-roadmap.md

远程策略旋钮

add-remote --timeout-ms <ms>：设置每个服务的远程请求超时。
add-remote --transport <streamable_http|sse_http>：选择远程MCP传输，无需手动编辑清单。
add-remote --allow-tools <tool_a,tool_b>：限制可调用的远程工具。
add-remote --max-payload-bytes <bytes>：设置每个远程服务的最大请求/响应有效负载字节数。
add-remote --max-concurrency <n>：设置每个服务的最大并发飞行中远程请求数。
add-remote --auth-ref <ref>：远程身份验证引用（支持 legacy-name, env:ENV_VAR, file:relative/path, header_env:Header-Name:ENV_VAR).
CLARITY_REMOTE_ALLOWED_HOSTS=host1,host2：可选的全局远程主机分配列表。
CLARITY_REMOTE_DEFAULT_TIMEOUT_MS=20000：未设置清单超时时的默认超时。
CLARITY_REMOTE_MAX_PAYLOAD_BYTES=1048576：未设置清单值时的默认最大请求/响应有效负载字节数。
CLARITY_REMOTE_MAX_CONCURRENCY=8：未设置清单值时，每个服务的默认最大运行中远程请求数。
CLARITY_REMOTE_AUTH_FILE_ROOT=/absolute/path：可选的根目录 file: auth-refs（默认为 .clarity/secrets 在工作空间下）。
CLARITY_ENABLE_MCP_PROVISIONING=1：启用运行时MCP自我配置工具(runtime__register_*, runtime__apply_manifest).
CLARITY_ENABLE_COMPILER_INSTALL=1：允许 clarity__ensure_compiler 执行安装命令。
CLARITY_COMPILER_INSTALL_ALLOWLIST=brew,apt-get：可选的安装程序命令allowlist clarity__ensure_compiler.
CLARITY_AUDIT_INCLUDE_LIFECYCLE=1：在审核中包括服务生命周期事件(service.*).集 0 仅记录MCP工具调用。
CLARITY_A2A_MAX_MESSAGE_BYTES=65536：正式摄入A2A包膜的最大可接受体型 POST /api/a2a/messages.
运行时聊天调度：
- CLARITY_HITL_CHAT_MODE=auto|echo|disabled （全局默认）
- 清单中的每个代理覆盖： metadata.agent.chat (mode, handlerTool, historyEnabled, historyMaxTurns, historyMaxChars)
- 本地wasm-env/秘密注射： spec.origin.env[] 随着 value 或 secretRef （仅按服务执行上下文解析）
- 本地运行时聊天模型密钥覆盖： metadata.agent.chat.apiKeyEnv 因当地垃圾而受到表彰 call_model / call_model_system
- 显式直接HITL能力： metadata.agent.hitl=true
- 在 auto 模式运行时分派给代理拥有的处理程序工具（本地默认值 fn__receive_chat，远程默认 receive_chat)
- 运行时间总是过去的 contextVersion="context.v1" 和 context 聊天处理程序
- 提供者密钥/模型应由代理实现拥有，而不是运行时拥有
定时器时间表：
- 声明 metadata.agent.timer.schedules[] (scheduleId, scheduleExpr 随着 every <n> <unit>)
- 运行时发出规范定时器触发上下文(scheduleId, scheduleExpr, firedAt)并在服务运行时执行计时器运行

安全默认值

如果 CLARITYD_AUTH_TOKEN 设置后，受保护的控制端点需要通过以下方式获取令牌 Authorization: Bearer <token> 或 x-clarity-token.
如果没有设置令牌，则运行时API仅限于环回调用者。
查询令牌身份验证(?token=<token>)仅限于本地环回SSE端点(/events, /api/events)对于浏览器 EventSource 只有兼容性。
状态UI仍然可以通过打开 ?token=<token>；该页将令牌存储在本地存储中，将其从URL中删除，并对API调用使用头验证。

审计和事件

GET /api/audit?limit=200：最新运行时审计/事件。
GET /api/agents/registry：注册的代理服务和声明的功能。
GET /api/agents/runs?limit=100：代理运行摘要。
GET /api/agents/events?limit=200：最近的代理时间线事件。
GET /api/agents/runs/:runId/events?limit=200：一次运行代理时间线。
GET /api/a2a/capabilities：列出启用A2A的代理和协议配置文件。
POST /api/a2a/messages：摄入一个正式的A2A信封(clarity.a2a.v1)并标准化为规范 agent.* 事件。
POST /api/agents/events：摄入一个 agent.* 编排事件。
GET /api/events：实时运行时事件的SSE流。
状态页面现在包括单独的 MCP 和 Agents 选项卡。
遥测在守护进程重新启动后持续存在 .clarity/runtime/telemetry.json.
审计策略始终记录MCP工具调用(mcp.tool_called)，不包括秘密有效载荷，可以包括生命周期事件(service.*)via CLARITY_AUDIT_INCLUDE_LIFECYCLE=1 （默认启用）。
身份验证生命周期/验证API：
- GET /api/security/auth/providers
- GET|POST /api/security/auth/validate
- GET /api/security/auth/secrets
- POST /api/security/auth/secrets （要求 CLARITY_ENABLE_MCP_PROVISIONING=1)
- DELETE /api/security/auth/secrets （要求 CLARITY_ENABLE_MCP_PROVISIONING=1)
服务取消设置API：
DELETE /api/services/:serviceId 带可选车身 { "cleanup_artifacts": true }

许可证

存储库许可证：MIT（参见 LICENSE).
运行时分布式工件必须保留存储库许可证文本并声明与SPDX兼容的元数据(MIT)发布时在包/构建元数据中。

CI/CD和GitHub

公关CI： .github/workflows/build.yml （分支命名+构建+lint+格式+测试）。
每次合并/推送时进行快照打包 main: .github/workflows/snapshot.yml （包括覆盖门和上传快照工件）。
标记为发布管道： .github/workflows/release.yml （构建、测试、覆盖率、打包、校验和、GitHub Release资产）。
自动版本控制/变更日志PR： .github/workflows/release-please.yml (.release-please-*.json config）。
安全门：
- .github/workflows/dependency-review.yml
- .github/workflows/codeql.yml
- .github/workflows/secret-scan.yml
回购自动化：
- Dependabot： .github/dependabot.yml
- 代码所有者： .github/CODEOWNERS
- PR/问题模板： .github/pull_request_template.md, .github/ISSUE_TEMPLATE/*
- 标签同步+路径标签： .github/workflows/labels-sync.yml, .github/workflows/labeler.yml, .github/labeler.yml
- 可选项目自动添加： .github/workflows/project-automation.yml （套 GH_PROJECT_URL 变量和 ADD_TO_PROJECT_PAT 秘密）

所需GitHub设置（手动）

保护 main:
- 合并前需要拉取请求
- 合并前需要通过状态检查
- 要求分支机构在合并前保持最新状态
- 需要线性历史记录
合并策略：
- 启用壁球合并
- 禁用合并提交
可选硬化：
- 限制谁可以推送 main
- 需要代码所有者的审查

您可以将基线分支保护策略应用于：

./scripts/github/apply-branch-protection.sh <owner> <repo>

承诺/释放公约

使用传统的提交前缀，这样发布自动化就可以推断出版本差异：
- feat: ...
- fix: ...
- chore: ...
- docs: ...
- refactor: ...
使用 BREAKING CHANGE: 在提交重大颠簸的尸体中。

贡献

此仓库使用基于中继的开发：

保持 main 随时可发布。
分支机构从 main，保持分支短命，并迅速合并回来。
按预期结果（而非实施细节）命名每个分支：
- result/<outcome-kebab-case>
- hotfix/<outcome-kebab-case>
- codex/<outcome-kebab-case>
- （自动化例外） dependabot/*
打开PR main 带有行为/基本原理注释。
确保CI为绿色(.github/workflows/build.yml：分支名称检查+构建+lint+格式+测试）。

对于较大的架构更改，请先打开一个问题，以便在控制平面契约上对齐。

使用说明

为什么选择Clarity Runtime？

这给了你什么

建筑

安装+启动

命令行界面

当前状态

路线图

进度快照

规格

远程策略旋钮

安全默认值

审计和事件

许可证

CI/CD和GitHub

所需GitHub设置（手动）

承诺/释放公约

贡献

相关 MCP

浏览器自动化MCP服务

小红书MCP服务

Excel表格处理MCP服务

学术论文搜索与下载服务

文件与终端管理MCP服务

Zotero文献库搜索与阅读MCP服务