Cusimanse

状态：Beta — 研究框架与运行时工具包

Cusimanse 正在积极开发中。Fork 它、测试它、运行参考实验、报告 bug 并提交 pull request。 在 beta 期间，API、配方、文档和集成预计会不断演进。

AI 使用与负责任贡献： Cusimanse 在其研究框架、文档、分析工作流和工程流程中使用 AI 辅助开发和智能体 AI。AI 生成或 AI 辅助的输出并不自动具有权威性、安全性、正确性、原创性或适用于生产环境。贡献者有责任在提交前审查、测试和验证 AI 辅助的更改。不要将 AI 系统作为安全决策、授权、证据解读或安全关键操作的唯一权威。仅将 Cusimanse 用于授权研究，遵守适用法律和政策，保护凭据和敏感数据，并将执行限制在项目声明的策略和一次性计算边界内。贡献应适当明确标识重要的 AI 协助，保持人类问责制，并遵循仓库的测试、审查要求和负责任使用期望。

在一次性计算上进行声明式、智能体操作的安全研究。 研究人员声明意图和需求；智能体进行规划、选择和分​​析；Go 能力 API 和策略决定是否可以执行以及如何执行。

契约 → 需求 → 提示交接 → 智能体 → 能力解析 → Go 运行时 → 策略/审批 → Lima/QEMU → 插桩/工作负载 → 证据 → 分析 → 独立验证 → 报告 → 保存 → 销毁。

目录

• Cusimanse 是什么
• 架构与权限边界
• 研究人员工作流
• 提示库与智能体交接
• 主机工具与安装
• 网关
• 插桩
• 可观测性
• Lima/QEMU 与客户机工具
• Go 能力 API 与命令
• 角色、技能与学习循环
• 配置文件与需求
• 策略与安全
• 证据与可复现性
• 参考实验
• 验证与集成测试
• 致谢与开源社区
• 仓库结构

Cusimanse 是什么

层	职责	事实来源
契约	目的、授权、范围、验收	contracts/
需求	操作系统、隔离、工作负载、网络、插桩	recipes/experiments/
提示库	智能体中立交接	prompts/experiments/
操作员指南	轻量适配器交接	prompts/operators/
配置文件	可信可复用能力	recipes/profiles/
运行时	解析、策略、生命周期、执行边界	cmd/cusimanse/、internal/
策略	权限与审批	policies/、internal/policy/
隔离	一次性计算	recipes/lima/、Lima/QEMU
证据	观察、来源、验证	runs/<session-id>/

智能体无法创建可信配置文件、扩展策略、修改可信配方，或直接在主机上执行不受信任的工作负载。

架构与权限边界

1. 声明： 契约 + YAML 需求。
2. 交接： 共享实验提示加上可选的操作员指南。
3. 规划： Goose 是原生参考操作员；其他智能体使用适配器。
4. 解析： Go 根据已注册的配置文件解析需求，并在出现歧义时失败关闭。
5. 策略： Go 评估权限和审批门，并审计决策。
6. 执行： 能力操作 Lima/QEMU 和固定的工作负载处理器。
7. 证据： 收集、哈希、独立验证、报告、保存，然后销毁一次性计算。

边界规则： 智能体决定做什么研究；Cusimanse 决定是否可以执行以及如何执行。

研究人员工作流

1. 契约与需求

编写 contracts/<experiment>.md，包含研究问题、授权、范围、验收标准和安全约束。仅在 recipes/experiments/<experiment>.yaml 中声明需求。

示例：

requirements:
  execution: disposable
  os: linux
  workload: npm-threat
  network: localhost-only
  instrumentation: [process, syscall, filesystem, network]

2. 引导与确定性验证

./scripts/install.sh
export PATH="$HOME/.local/bin:$HOME/go/bin:$PATH"
cusimanse doctor
cusimanse validate
cusimanse preflight
cusimanse policy validate
cusimanse test
cusimanse integration-test

3. 验证并运行 Goose 配方

goose recipe validate recipes/npm-threat-001/recipe.yaml
goose recipe validate recipes/subrecipes/evidence-analysis.yaml
goose recipe validate recipes/subrecipes/verification.yaml
goose recipe validate recipes/subrecipes/report.yaml
goose run --recipe ./recipes/npm-threat-001/recipe.yaml --interactive

该配方明确声明了 summon 平台扩展。Summon 仅提供委托/编排；它不授权执行。

4. 解析与审批

cusimanse resolve npm-threat-001
cusimanse policy explain vm
cusimanse policy explain network
cusimanse policy check-all
cusimanse policy require vm --approved

5. 执行与完成

cusimanse --approved run npm-threat-001 <session-id>
cusimanse observability report <session-id>
cusimanse policy audit

生命周期：resolve → policy → provision → configure → instrument → execute → collect → verify → report → preserve → destroy。

提示库与智能体交接

提示是一种交接，不是权限层，也不是第二个配方。

prompts/experiments/<experiment>.md       共享研究交接
prompts/operators/<operator>.md           轻量操作员指南
recipes/experiments/<experiment>.yaml     需求事实来源
recipes/<experiment>/recipe.yaml          Goose/运行时配方
contracts/<experiment>.md                 授权/范围来源

对于 OpenCode、Hermes、Antigravity 或 Pi，提供相同的契约、实验 YAML、配方引用、共享提示和匹配的操作员指南。替代操作员可以使用其原生功能进行规划/委托/分析，但必须调用 Cusimanse 来执行能力。不支持的能力记录为 PARTIAL；适配器不能修改策略、配置文件或可信配方。

规范适配器配置：recipes/agents/adapter-matrix.yaml 和 docs/GOOSE-ADAPTERS.md。

主机工具与安装

权威清单：recipes/host/security-research.yaml。项目范围清单：manifest/TOOL-INVENTORY.yaml。详细主机访问/配置指南：docs/HOST-TOOLCHAIN.md。

./scripts/install.sh
cusimanse tools list
cusimanse tools versions
cusimanse tools config
cusimanse tools path

主机工具涵盖 Git、shell/引导实用程序、Python、Node/npm、Go、jq/yq、ripgrep 和 Goose。Lima/QEMU 提供一次性计算。客户机插桩在 docs/INSTRUMENTATION.md 中单独记录，并由 recipes/instrumentation/security-research.yaml 声明。

网关

recipes/gateway/mandatory.yaml 定义了仅限 localhost 的模型网关链。

组件	访问	数据 / UI	安装 / 配置
LiteLLM	127.0.0.1:4000；面向智能体的 OpenAI 兼容网关	模型请求、路由和规范化；无公共监听器	由 scripts/install.sh 安装到 Cusimanse Python 环境；配置位于 ~/.config/cusimanse/litellm.yaml
OmniRoute	127.0.0.1:20128；LiteLLM 的上游	提供商路由/回退；localhost API，无公共监听器	由安装程序使用固定 npm 包安装；环境位于 ~/.config/cusimanse/omniroute.env

流程：agent/Goose → LiteLLM :4000 → OmniRoute :20128 → configured provider。

密钥仅通过环境变量提供。网关是传输/模型路由组件，不是安全边界；Cusimanse 策略仍然是权威。使用 cusimanse tools config 检查配置位置而不打印密钥。

插桩

插桩在一次性 Linux 客户机内运行，由执行工作流拥有。权威清单和安装来源是 recipes/instrumentation/security-research.yaml 和 recipes/lima/security-research.yaml。

参见 docs/INSTRUMENTATION.md 获取完整工具表、访问模型、安装细节、VM 诊断命令和证据规则。

可观测性

Goose 观察智能体；Cusimanse 观察实验。

由 recipes/observability/mandatory.yaml 声明：

观察器	访问	数据/UI
Numbat	cusimanse tools numbat	~/.numbat/cusimanse.ndjson
Phoenix	浏览器	http://127.0.0.1:6006
OpenTelemetry	OTLP/HTTP	http://127.0.0.1:4318
ClawMetry	浏览器	http://127.0.0.1:8900
Aegis	cusimanse observability status	~/.local/share/cusimanse/aegis/

cusimanse observability status
cusimanse observability phoenix
cusimanse observability clawmetry
cusimanse observability report <session-id>

每次运行的快照位于 runs/<session-id>/observability/ 下，并带有必需的 experiment/session/run/agent/role/skill/capability/workload/trace 关联。

Lima/QEMU 与客户机工具

事实来源：recipes/lima/security-research.yaml。在正常操作中，Go 运行时和智能体管理 VM 生命周期。研究人员通常应调用 cusimanse --approved run；直接使用 Lima 命令仅用于诊断/冒烟测试。

# Diagnostic validation only
limactl validate recipes/lima/security-research.yaml

# Explicit disposable smoke VM
limactl start --name=cusimanse-smoke recipes/lima/security-research.yaml

# Access the guest for diagnostics
limactl shell cusimanse-smoke -- bash -lc 'go version && node --version && npm --version && strace -V'

# Destroy the disposable VM
limactl delete --force cusimanse-smoke

Go 运行时负责在正常执行周围强制执行实验生命周期、策略和证据门。不要向参考 VM 添加凭据、任意主机挂载或外部目标。

Go 能力 API 与命令

原生控制平面命令：