simplicio-loop：AI Agent 工具实践指南

实际评估simplicio-loop时，我先确认它解决的具体问题： 在睡觉时完成所有积压的工作， AI 协调器，DOES 在 ANY LLM 上进行端到端工作 — 发现 → 实施 → 验证 → 合并 → 24/7 — 在安全门之后。对安全分析任务来说，授权边界、证据完整性和误报需要同时控制往往决定它能否落地，不能只用安装成功来判断。先在明确授权的样例或离线靶场中验证更稳妥；过程中要观察输入边界、证据链、误报率和安全中止机制，失败也应能解释原因。编辑判断上，具备授权环境和复核能力的安全人员可以优先研究它；其他团队不必为了热门标签勉强接入。

simplicio-loop — 通用循环 AI Orchestrator

TL;DR · 7 Skills · Source Adapters · 35 Runtimes · The Loop · Token Economy · Bench #17 · Capture Engine · Install

语言：

English | 葡萄牙语 | 西班牙语 | Français | Deutsch | Italiano | 日本語 | 한국어 | 简体中文 | Русский | Polski | 土耳其 | Nederlands | हिन्दी | العربية

新一代——用于验证代理工作的操作系统

simplicio-loop 的发展已经远远超出了重复直到完成的提示。 它现在将意图编译到冻结的任务合同中，映射存储库，安排依赖性感知工作，将执行分散到隔离的工作树中，收集结构化收据，独立验证，安全回滚，记住每次尝试，并通过交付保持记录源同步。

• 合同第一——验收标准、依赖关系、风险、源状态和完成预言在执行之前都是明确的。
• 并行且无损坏 — 就绪任务在隔离的 lanes/worktrees 中运行，并通过操作账本汇聚。
• 默认情况下自动扇出 — batch 为每个独立的、 授权任务；重叠、缺失证据或不可用的隔离会回落到 可见串行通道。请参见 docs/AUTO_FAN_OUT.md。
• 完成前的证明 — 测试、impact/flow 检查、观察者挑战、交付收据和 HBP 证据拒绝错误的完成状态。
• 改变行为的内存 - 日志、失速检测器、检查点和跨代理 wiki 可防止振荡并使切换持久。

Dependency-aware扇出：孤立的worker并发执行，返回证据，并汇聚成一个经过验证的delivery.

Every 阶段是显式的、有界的、可观察的，并且 reversible.

Evidence 和内存是执行路径的一部分 — 不是在 fact.

之后编写的报告

该架构让一个目标成为一个受管理的交付系统：从单个艰巨的任务到整个待办事项，跨会话和运行时间，本地优先的操作员和收据足够强大，可供人类、CI 或其他代理进行审核。

已发货：每个阶段背后的具体代理

实施状态： #422–#436——整个EPIC——自v3.37.0起关闭并发货，包括完整的强制性阶段报告门（#433）和多跟踪器接口（#436）。 v3.38.0 在顶部添加了多代理协调层（scripts/coordinator.py、scripts/pr_dod_review.py） — 请参阅 § 新功能。

便携式驱动程序向 intake/planning 分配一名负责代理，负责实施、安全、 交付、feedback/recovery 和最终竣工审核。审查扇出四名独立代理人 — security/correctness，代码质量、运行时再现和爆炸半径 — 之前 重新收敛。每个转换都会发出一个事件和收据；竣工审核员接受证据， 从来没有自我报告过信心。

工作项评论正策

flowchart LR
  SOURCE["Issue · task · queue"] --> COORD["Portable coordinator"]
  COORD --> PLAN["Intake + Planner agent"]
  PLAN --> BUILD["Implementation agent"]
  BUILD --> SAFE["Safety agent"]
  SAFE --> R1["Review agent · security"]
  SAFE --> R2["Review agent · quality"]
  SAFE --> R3["Review agent · runtime/E2E"]
  SAFE --> R4["Review agent · blast radius"]
  R1 --> DELIVER["Delivery agent"]
  R2 --> DELIVER
  R3 --> DELIVER
  R4 --> DELIVER
  DELIVER --> RECOVER["Feedback + Recovery agent"]
  RECOVER --> BUILD
  DELIVER --> AUDIT["Completion auditor"]
  AUDIT --> VERDICT{"COMPLETE · PARTIAL · BLOCKED · REGRESSED"}
  PLAN -. "events + receipts" .-> LEDGER["Append-only stage ledger"]
  BUILD -.-> LEDGER
  SAFE -.-> LEDGER
  DELIVER -.-> LEDGER
  AUDIT -.-> LEDGER
  LEDGER --> GH["GitHub comments · REQUIRED"]
  LEDGER -. "only if connected" .-> AZ["Azure DevOps comments"]
  LEDGER -. "only if connected" .-> JIRA["Jira comments"]
  LEDGER -. "only if connected" .-> ASANA["Asana comments"]
  LEDGER -. "only if connected" .-> TRELLO["Trello comments"]
  GH --> AUDIT

提供者中立的合约、能力探测、幂等标记、持久发件箱、恢复 规则、沙箱 E2E 矩阵和验收标准在 #436。可选的提供者永远不会 仅因为 CLI 存在而被视为已连接，并且从未发明过远程确认。

v3.38.0 的新功能 — 多代理协调版本

此版本涉及一个难题，该问题仅在多个代理会话正常工作后才会出现 一次相同的存储库：会话如何知道已经声明了什么，已经合并了什么 - 但是 - 不完整，如何利用自己的空闲时间而不是重复兄弟姐妹的工作？每个 下面的项目是根据该项目的实时、多会话状态构建、测试和交付的 回购——不是一个综合场景。

• scripts/coordinator.py — 决策核心。 鉴于今天的 GitHub 状态（未决问题声明 评论 + 合并 PRs），它会为每个问题返回一个确定性操作：OWN（没有声明任何内容） 还），CONTINUE_OWN（您已经是最新的索赔人），DEFER_ACTIVE_CLAIM（兄弟姐妹） 会话最近声明了它 - 不要重复），RECLAIM_STALE（该声明已冷落，可以安全地 拾取），或 VERIFY_PARTIAL（PR 已针对此问题合并，但它仍然打开 - 检查 在假设“什么也没发生”或“完成了”之前实际做了什么）。它还 当两个会话同时声明同一问题时，会引发 duplicate_risk 标志。 第一天就被捕捉到，现场直播：两个会议独立地为同一主题构建了一个调查结果收集器 问题在两个不同的文件名下。
• scripts/pr_dod_review.py — 空闲时间的审阅者。 当每个未解决的问题都已解决时 声称，会话中最高的举动不是等待 - 而是检查未平仓的 PRs 这个仓库自己的栏：完成的 7 维定义（实现，unit/integration/ system/regression 测试，性能基准，覆盖率≥85%）以及潜在问题的 冻结的验收标准清单。 check --post 发布了机械的、逐行的判决： PR 评论而不是基于氛围的批准。已针对真实的、已合并的“MVP 切片”进行了验证 PR：它正确地将父史诗的 17 个验收标准中的 17 个标记为仍未解决。
• scripts/finding_collector.py — 耐用、重复数据删除的缺陷内存（问题 #466，第 1 阶段）。 每个不同缺陷的 simplicio.finding/v1 记录，指纹识别，因此“相同”的潜在错误 - 任何代理、任何运行、任何时间戳都可以看到 - 折叠成一个带有出现次数的记录 而不是产生重复的噪音。还没有 GitHub 调用；那是下一阶段。 scripts/evolution.py（分类+优先级+重复数据删除）和scripts/workflow_topology.py（DAG） diff + 验证器）作为配套的 Continuous Evolution 的第一个 MVP 切片提供（#467） 和自适应架构（#468）史诗； scripts/agent_replication.py 对 Elastic 做了同样的事情 复制 (#469) — 投机性重复执行的准入控制和获胜者选择。
• references/multi-agent-coordination.md + references/background-verification.md — 两个新 记录的约定直接连接到 SKILL.md 的分类步骤：检查协调器所有权 在触及问题之前，请查看 PRs，而不是在所有内容都已声明后就闲置，然后启动 后台验证命令缓慢（tests/claims_audit.py），因此轮流不断进行 进度而不是观看进度条。
• 强制合并后清理（scripts/worktree_cleanup.py，#484） - 合并分支的本地 现在，工作树和分支引用会自动删除，而不是跨会话累积。
• CLI 合约添加 (WI-471) — preflight 子命令和 status 上的 --json 标志， 因此外部主管可以在准备运行之前通过机器检查准备情况。
• 连续发现布线（WI-466） - 完成门现在真正咨询发现 存储，并在同一通道中发现并修复了 store/repo 一致性错误。
• 在本次发布周期中，main 本身发现并修复了两个真实的回归 — PR 默默删除了一次合并的函数定义（破坏了loop_progress.py自己的自测）， 然后，一场壁球合并比赛再次将完全相同的损坏代码重新引入到 main 上。 两者都是通过实际运行受影响的脚本找到的，而不是通过信任绿色的 PR 描述 - coordinator.py 和 pr_dod_review.py 现在存在的全部原因。
• 继承自 v3.37.0 的便携式舞台特工史诗 (#422–#436) — 一个具体的、 每个阶段背后可独立验证的代理（intake/planner、实施、四向 审查小组、安全门、交付、feedback/recovery、竣工审核员）、便携式合同 共享 graph/receipt 模式、人类可读的代理身份和可选的验证器 simplicio-mapper 和 simplicio-dev-cli 的本机绑定。运行时行 是能力清单；运行时仅被视为由单独安装的通道执行 当其二进制和可执行适配器实际可用时。
• 测试套件库存是测量的，而不是硬编码的。 结帐和最新的本地入口 收据是文件和结果计数的真实来源。 scripts/test_categories.py 报告 适用的 unit/integration/system/regression 约定，包括任何未分类的 文件；在本周期的每次合并中，scripts/claims_audit.py 都保持在 14/14 状态。

具体而言，这对您意味着什么： 如果您在多个会话中运行 simplicio-loop 或机器针对相同的存储库，它现在可以主动保护您免受两种故障模式的影响 实际上在实践中发生了——两个代理悄悄地重做相同的工作，并且“完成”PR 合并了，但真正的问题只得到了部分解决。两者在过去都是不可见的。两者现在都是， 机械地，每次分类都通过。

完整列表请参见 CHANGELOG.md v3.38.0 发布 签名工件（wheel、sdist、SBOM、出处）。

⚡ TL;DR

simplicio-loop 是一个与运行时无关的 超级插件 — 一个自主循环 Orchestrator（调用为 /simplicio-loop）加上 六项卫星技能和五项 加速方案——可以将任何 强大的LLM（Claude、Codex、Copilot、Gemini、Cursor、本地型号）成为自动驾驶工作者。你 将其指向工作主体 — “完成所有未解决的问题”、“清除 CI 队列”、“清空 Jira 板” — 然后它 独立运行整个生命周期：

发现→理解→决定→行动→验证→纠正→记录→重复

它可以发现任何来源的工作（GitHub 问题、Jira、Azure DevOps、agentsview 会话和 更多），重复数据删除，自动将代理队列扩展到您的计算机，通过质量实施每个项目 运行代码（不仅仅是编译它）的循环，打开 PRs，解析 CI/review 反馈，合并， 并持续关注 24/7 的新作品 - 一切都在安全门和证据检查之后。

/simplicio-loop finish all open issues
→ identity + pre-flight (auth, watcher, STOP path)
→ discover 50 issues · dedup · build dependency DAG
→ autoscale fleet = 14 · pipeline implement→review→merge
→ each item: read body+ACs → orient code → plan → edit → run → verify → PR
→ merge · close with evidence · rollback if main breaks
→ keep looping every ~2 min until the queue is dry (evidence-gated, never a false "done")

三件事让它与众不同：它是一个专注技能的超级插件，它运行相同 35 个运行时上的协议，并且它通过积极、诚实的代币经济来完成所有这一切。

该技能安装独立：没有Runtime/MCP后端，并且没有强制 原生组件，使用 simplicio-loop。两个绑定运算符（simplicio-mapper， simplicio-dev-cli）是整个堆栈。

在 Simplicio 产品线中，此存储库也是 当前参考任务流程 公司工作：其有证据支持的 converge/drain 纪律、持久的尝试日志和员工 协调模式是其他 Simplicio 工具重用的模式。

视觉进步、诚实和便携

执行文本、Markdown、JSON 或 ANSI 动画。托达斯 simplicio.progress/v1 的表面信息，包括 etapa 图标、门 evidence/watcher/oracle，worker_claimed 的工作树和事件通道位于 delivery_reconciled。

simplicio-loop progress  --format text --once
simplicio-loop progress  --format markdown --once   # LLM/ch@t
simplicio-loop progress  --format json --once       # dashboard/adapters
simplicio-loop progress  --format text --ascii --no-animation  # log/PowerShell

100% 立即收到预言机收据 (COMPLETE/DRAINED)； uma fase done SEM 证明 最终结果是阻止者。咨询或完成合同 docs/PROGRESS_PROTOCOL.md.

Monorepo 包

该存储库包含三个包，每个包都有一个职责：

开发设置（可编辑 - 将所有三个安装到一个 venv 中）：bash scripts/dev_install.sh。本地 门：python3 scripts/check.py --package all（或--package mapper|开发-cli|循环，或 --changed 仅运行 diff 涉及的内容）。这里没有 GitHub 操作门 - 本地门户具有权威性。任何任务计数的交付流程都是两个命令： simplicio-loop ""（simplicio-loop turbo 的缩写）— Mapper 调查一次并打印一份申请 命令；调用模型使用heredoc中的计划运行它，Dev CLI应用它并且--verify运行 测试；没有提供程序，也没有 API 密钥（请参阅 零配置执行）。

LLM 前门

如果您是 agent/runtime 进入此回购协议，请首先阅读 llms.txt 的空头操作合约，然后阅读 AGENTS.md，然后阅读 .claude/skills/simplicio-loop/SKILL.md。

官方能力记录

simplicio-loop 所提供的完整官方名册 - 下面的每项功能都是真实的， 可运行，并由适用的本地网关测试。精确 collected/executed/skipped/deselected 计数属于该登机收据，而不是本文件。每项功能都与其深层相关 及其工人。

两种循环模式使终止明确：收敛（单个困难任务 - 结束于 证据门控 或失速升级）与 耗尽（队列 — 当源 重新查询保持空K轮）。两者仍然遵循通用出口（promise+evidence， max_iterations, STOP).

这条工作线的循环评分：7.5（强大的设计，未经证实）→9（尝试记忆+ 抗振荡）→ 9.5（可重现的本地证明）→ ~10（强制安全+完整循环 语义）。随着项目的发展，基础设施的验证现在可以捕捉到项目自身的回归。

7个技能+5个加速方案

Orchestrator核心+六颗卫星+五颗accelerators/integrations。每颗卫星都是 可选 - 加载后，编排器将委托给它（更丰富+更便宜）；当缺席时， 内联协议覆盖率100%。加速方案是自动检测 — 存在=已使用，不存在= LLM 后备。

每个技能都位于 .claude/skills/ 下；每个加速方案都有一个参考文档 .claude/skills/simplicio-loop/references/（视频制作人： video-evidence.md，工人 scripts/video_evidence.py).

源适配器

编排器通过可插拔适配器发现任何来源的工作。每个都暴露六个动词： list_ready, get_details, claim, update_status, attach_evidence, close.

请参阅 .claude/skills/simplicio-loop/references/ 下每个适配器的参考文档。

35 个运行时，一种协议 — 3 个保证 + 32 个尽力而为

一个通用技能核心+一组钩子驱动每个运行时。适配器很薄：它告诉 运行时在哪里加载技能和如何装备循环。 该技能没有运行时间；的 运行时检测技能。 此堆栈中没有 Runtime/MCP 后端 - 每个主机都运行 针对 simplicio-mapper 和 simplicio-dev-cli 的相同独立循环。

主机在 simplicio_loop/_catalog/harnesses.json 中列出一次： simpletibr/simplicio 的 32 个主机表面加上 Aider， DeepSeek 和 OpenClaw。 bash scripts/install.sh 安装每台 wired 主机； DeepSeek 是型号 提供者而不是主机，因此其适配器 README 列出了手动步骤。

第 1 层 — 有保证（每次提交都有门控）

完整流程——从需求到交付

协调器按顺序作用于每一层 - 从读取需求（问题、任务、分配）开始 交付合并的、经过验证的工作，然后循环 24/7 以获取更多信息。

flowchart LR
  IN["Intent: issue · task · queue"] --> CONTRACT["1 · Freeze task contract"]
  CONTRACT --> MAP["2 · Map source + normalize"]
  MAP --> COORD{"3 · Coordinator decide (multi-session)"}
  COORD -->|"OWN / CONTINUE_OWN / RECLAIM_STALE"| PLAN["4 · Dependency DAG + acceptance criteria"]
  COORD -->|"DEFER_ACTIVE_CLAIM (all issues)"| REVIEW["PR DoD/AC review — never idle"]
  COORD -->|"VERIFY_PARTIAL"| RECHECK["Verify what's actually merged before continuing"]
  RECHECK --> PLAN
  REVIEW --> IN
  PLAN --> ROUTE{"5 · Ready task?"}
  ROUTE -->|"solo / small"| SOLO["Targeted lane"]
  ROUTE -->|"parallel / medium+"| FAN["Bounded fan-out"]
  FAN --> A["Isolated worktree A"]
  FAN --> B["Isolated worktree B"]
  FAN --> C["Isolated worktree C"]
  SOLO --> VERIFY["6 · Test + impact/flow evidence"]
  A --> VERIFY
  B --> VERIFY
  C --> VERIFY
  VERIFY --> RECEIPT["Watcher challenge + evidence receipt"]
  RECEIPT --> ORACLE{"7 · Completion oracle"}
  ORACLE -->|"pending / blocked"| RECOVER["Journal · checkpoint · rollback · backlog-only maintenance"]
  RECOVER --> PLAN
  ORACLE -->|"verified / measured"| DELIVER["8 · Source sync · PR · merge"]
  DELIVER --> CLEANUP["Post-merge worktree/branch cleanup"]
  CLEANUP --> MEMORY["9 · Ledger · wiki · durable attempt memory"]
  MEMORY --> WATCH["10 · Re-feed · watcher · STOP path"]
  WATCH -->|"new work"| IN

多智能体协调（v3.38.0 中的新功能）。 步骤 3 是“是兄弟姐妹”的机械答案 会话已经在讨论这个了吗？” — scripts/coordinator.py 根据实时 GitHub 状态决定，绝不是猜测。 当每个候选问题都延迟返回时，循环不会闲置：它会针对未决的 PRs 进行审查 DoD + 验收标准 (scripts/pr_dod_review.py) 代替。完整细节： references/multi-agent-coordination.md.

规划门（问题 #284）。 上述步骤 1-3 不仅仅是指导 — simplicio_loop/planning_gate.py 使它们成为“声称”和“变异”之间的故障关闭机械屏障：每个真实的 arm_run() 自建一个 planning-receipt.json 绑定 run/attempt/contract/plan/lease/fence （以及，在 GitHub 源上，源快照哈希）转换为一次性 mutation_authority 令牌， execute_operator()/execute_operator_batch() 在没有匹配的情况下拒绝运行。两者都 门的一半（SIMPLICIO_REQUIRE_MUTATION_AUTHORITY、SIMPLICIO_LOOP_AUTO_PLANNING_RECEIPT） 默认情况下是强制性的 - 请参阅 .claude/skills/simplicio-loop/references/planning-gate.md 和 docs/adr/0004-planning-gate-rollout.md.

50 个扩展点

这些是主机可以绑定本机功能的指定位置。完整的合同， 包括两个必需的绑定（orient 上的 Mapper，deterministic_edit 上的 Dev CLI）， 是 .claude/skills/simplicio-loop/references/extension-points.md。 每次交付运行仍然通过相同的流程结束：定向、准备、每个编辑计划 任务，一项任务为 tick，两项或多项任务为 wave，然后验证。

orient · pattern_match · recall · normalize · deterministic_edit · autoscale · plan · execute · issue_factory · claim · worktree · diagnostics · validate · pr · watcher · savings_ledger · capability_rank · compress · trajectory · learn · human_gate · shell_exec · retry · convergence_policy · status · security · intake · dependency_graph · durable_workflow · work_queue · resource_governor · delivery_gate · action_gate · repo_conventions · pr_template · reuse_precedent · sibling_search · source_adapter · prompt_budget · model_route · model_preflight · toolchain_detect · checkpoint_restore · notify · endpoint_compare · web_verify · video_evidence · web_research · transform_guard · judge

循环

证据门控循环是核心机制。它每回合都会重新提供相同的目标，因此 代理看到自己之前的工作。退出是 ONLY 通过：

1. 证据门控 — 发出承诺 MUST 的回合也带有具体内容 证明（通过测试，合并PR，闭项重新查询）。没有证据的承诺=被忽视。
2. max_iterations 帽 — 硬质安全逆止器
3. STOP 信号 — .simplicio-loop/orchestrator/STOP 或通道命令

在回合之间，LMCache（如果可用）会缓存 KV 状态，因此重新馈送成本接近于零预填充。

尝试记忆+失速检测器（防振荡）

不记得任何振荡的重新进料循环 - 尝试 X，失败，再次尝试 X - 直到盖子烧毁。 simplicio-loop 保留一个持久的运行日志（.simplicio-loop/orchestrator/loop/journal.jsonl，仅附加： iteration · action · hypothesis · gate · error-fingerprint，加上可选的谱系，如 execution_state · stage_id · validator · decision · retry_count) 和 失速探测器 （scripts/loop_journal.py，确定性+无模型）：

• 错误指纹 — 失败的门输出被简化为带有行号的稳定散列， 路径、hex/uuids、时间戳和持续时间标准化，因此可以识别“相同”的错误 即使附带的文本不同，也会发生交叉。
• 失速 = 连续 K 个相同指纹失败（默认 K=3）。指纹的变化意味着 循环正在移动（PROGRESS）；相同的 K 次表示正在旋转（STALLED）。
• 在 STALLED 上，循环不会重新提供相同的目标 - 它将 死胡同 命名为 避免，然后切换策略或使用指纹升级到人门。
• loop_journal.py resume 在每个回合的顶部都会被读取，因此新的进程会继续进行，而无需 重新导出之前的尝试（真实的简历），并且永远不会重试已知的死胡同。
• 当循环进行提取、验证或受控重试时，record 还可以标记 --execution-state, --stage-id, --source-artifact, --chunk-id, --validator, --decision、--retry-count、--blocked-reason 和 --next-action，所以下一轮就知道了 不仅仅是“什么”失败了，还有“流程中的哪个环节”失败了。

loop_journal.py resume                       # what was tried + dead-ends to avoid
loop_journal.py record --iteration N --action "…" --gate fail --gate-output test.log \
  --execution-state planned --stage-id validate --validator pytest --decision retry
loop_journal.py stall --k 3 --exit-code      # PROGRESS → re-feed · STALLED → switch/escalate

导出其他运行时的合约 — simplicio.loop-execution/v1

simplicio-loop 是此 converge/drain 规则的参考实现。所以说 任何消费者都会重用这个语义而不是发明第二个， 不兼容的执行合约（#115），该规则被发布为版本化的、可测试的装置 contracts/loop-execution/v1/ 下：收敛成功， 失速+升级、空轮耗尽、STOP 路径、证据门控完成以及 最小的仅附加日志形状。 python3 scripts/check_loop_contract.py（连接到 scripts/check.py）根据 REAL 生产者（hooks/loop_stop.py， scripts/loop_journal.py），实际上是在一个独立的临时目录中运行它们——而不是一个 重新描述它们——因此实现自己的执行器的运行时可以将其行为与 每个灯具的 expected.json 而不是从散文中重新推导规则。参见 contracts/loop-execution/v1/SCHEMA.md 为完整 合约以及如何使用它。

视频证据 — 默认为剧作家，可根据要求提供超帧

该循环生成演示视频作为更改有效的证明 - 两个引擎，一个 video_evidence 扩展点（工人scripts/video_evidence.py，合同 references/video-evidence.md):

1. 默认 — 正常证据流程使用 Playwright。 UI 更改后，video_evidence 记录驱动屏幕的真实浏览器会话（剧作家本机视频 → .webm，→ .mp4 和 FFmpeg) — 最强的“有效，而不仅仅是编译”收据（步骤 4b）和有效的 证据门控 。

   python3 scripts/video_evidence.py verify --url http://localhost:3000/login \
       --name login-demo --expect "Sign in" --issue 42 [--upload --pr 42]
   

2. 根据要求 — 个性化讲解员使用超帧。 当可交付的 IS 为视频时 （“制作屏幕 X 的解释视频”），协调器呈现 确定性，标题为 web_verify 屏幕截图的幻灯片 超帧（作者：HeyGen —“相同的输入，相同的 帧，相同的输出”，CI-可重现，无 API 键，通过无头 Chrome + FFmpeg 进行本地渲染）。

   /simplicio-loop make an explainer video of the system login screen
   → detect: video-creation request → web_verify captures the screens
   → video_evidence verify --engine hyperframes → deterministic MP4 → attached to the PR
   

任一引擎：永远不会 recorded/rendered 产生 BLOCKED 的视频，永远不会出现假通行证。证据 始终是 文件路径 + 布尔判决 - 上下文中绝不是视频字节（代币经济）。

代币经济

节省仅依赖于经过验证的正确结果。基线=最便宜的明智的非精心策划 获得相同结果的路径。 储蓄报告是有证据的，不是强制性的：储蓄数字是 仅当转弯实际运行经济生产命令且数字追踪到 测量收据（夹紧 T 恤、签名读取、缓存命中、deterministic_edit、savings_ledger）。 没有可衡量的经济→没有储蓄额度；协调器从不编造基线或百分比。 此 README 中的大多数量化储蓄数字仍然是 UNVERIFIED（中没有收据快照） .simplicio-loop/orchestrator/savings/snapshots.jsonl) — 除了测量的比较台 下面。请参见 references/token-economy.md 和 scripts/claims_manifest.py。

测量基准（第 17 期）

任务： simplicio-agent#17 — Asolaria HRM + N-Nest-Prime，P0 切片在双臂中完成：Brown-Hilbert port.port.port 寻址 + Agent/Watcher 校正门（agent/asolaria_nest_contract.py + 单元测试，双臂绿色）。

武器（同一台机器，Windows）：

测量的堆栈： simplicio-loop 3.38.9 · mapper 0.26.0 · cli 0.18.0（历史运行；该堆栈仍然带有一个可选的加速方案操作符，但已被删除）。

阶段时间（秒）：

如何阅读：循环减少摄入量context/tokens硬（有利于多匝LLM成本）。 挂钟可以在冷操作员运行时更高（预检+映射器）。经过长时间的会议 代币减少通常主导计费成本；当 map/snapshot 温暖时，挂钟摊销。

注意事项（诚实）：

• 这里的“令牌”估计为 context_bytes / 4，而不是提供商计费的使用量。
• 两个分支中的实现代码都是相同的 P0 合约，因此比较是隔离的 survey/orchestration，不是完整史诗的两种不同实现。
• 不能替代令牌监视器（代理路由测量）。

运行 simplicio-loop ：经济性与测量性（每个运行时）

当您调用 simplicio-loop 时，会发生两种不同的情况，并且它们在每个运行时的行为都不同：

• 经济 — 压缩、输出钳位、仅签名读取、deterministic_edit — 适用于 所有 技能在任何运行时运行并加载 simplicio-orient / simplicio-compress 的时间。 这是 技能的行为加上钩子（钩子存在的地方最强：orient_clamp.py自动夹在克劳德和 光标；在其他地方它是指令驱动的）。
• 测量 - 令牌监视器的实时数字 - 仅计算流过的流量 捕获代理。

所以：每次运行时都会发生节省； 监视器会在 Simplicio Agent 上自动记录它们，并在 一次性路由步骤之后的 Claude/Codex (simplicio-cli wrap … / base-url → :8788)。无需路由， 经济仍然适用——监视器只是不会计算这些代币。 scripts/simplicio-economy.sh wire 在安装时为 OpenAI-compatible 客户端执行此路由。

Simplicio 代币坚控器

您在需要时打开的储蓄视图 - 只有捕获始终处于开启状态：

• 捕获代理 — 始终开启（一项自动启动的服务；有线客户端需要它 可达）。它在后台默默地捕获+测量Claude + Codex + Simplicio Agent。
• 网络仪表板 — http://127.0.0.1:9090 — 实时代币图表、储蓄表、LLMs/runtimes 以及我们拦截的提供者，实时代理日志。 首次安装时打开一次 所以你看到它有效，那么它就是按需 - 通过以下任何一种方式重新打开它：
  • simplicio-loop dashboard — 在 pip 安装后可以在任何地方使用（不需要存储库路径）； simplicio-loop dashboard --stop to close, --no-browser to just start the server.
  • bash scripts/simplicio-economy.sh monitor（回购结账）·… monitor stop 关闭。
  • 只需 询问代理 — “打开代币仪表板”。
• 菜单栏/托盘小部件 — 保存在系统托盘中的实时令牌（macOS rumps · Windows/Linux pystray）。 按需： bash scripts/simplicio-economy.sh tray · … tray stop。

安装自动启动仅捕获代理（macOS launchd · Linux systemd · Windows Startup）。的 仪表板在全新安装时打开一次（标记保护 - re-install/update 永远不会重新打开它；选择 与 SIMPLICIO_NO_DASHBOARD=1 一起出），并且托盘永远不会自行打开 - 没有任何东西被迫留下 打开。管理堆栈：scripts/simplicio-economy.sh {status|向上|监视器|托盘|线}。安装后， capture 运行而不调用循环 — 请参阅 references/token-capture.md。

e2e 储蓄演示 — 一项任务，四次跳跃，每一次都有一张收据

scripts/e2e_demo.py 是该程序的顶点验收测试：它通过驱动 ONE 任务 MAP → RECALL → EDIT → VERIFY 并在每跳写入 simplicio.savings-event/v1- 形状的收据， 从来不是一个纯粹的百分比。

python3 scripts/e2e_demo.py run         # live: real simplicio-mapper + task_anchor.py calls
python3 scripts/e2e_demo.py selftest    # offline: proves the receipt/report math, no external tools

run 写.simplicio-loop/orchestrator/savings/e2e-demo.md（报告），e2e-demo-events.jsonl（一张收据 每跳），并提供相同的 snapshots.jsonl 存储 savings_harness.py score 和 billing_aggregator.py collect/meter 已经读过 - 所以这个演示的数字汇总到 现有聚合，无需新代码。 MAP 和 VERIFY 调用真实的实时工具 (simplicio-mapper handoff, task_anchor.py 检查 --format json|香椿); RECALL 和 EDIT 诚实地标记本地替代品，其中上游依赖项（映射器的本机 --for-llm toon， dev-cli 的 SIMPLICIO_PROMPT_TOON）尚未发货 - 每个跃点的 note 都准确说明了具体情况。 selftest 完全离线（没有 simplicio-mapper/simplicio-cli 的子进程，没有网络，没有 API 密钥），并且是 scripts/check.py 运行的内容。

捕获引擎 — 一个本机模块，每个命令

engine/simplicio_engine.py 是本机 Simplicio 捕获引擎 （仅限 stdlib，失败打开）— 本机、透明捕获代理 + 确定性压缩引擎 没有外部依赖。运行任何 通过 scripts/simplicio-engine 包装器（e.g.simplicio-engine doctor）的命令：

设计支柱（详细）

四种机制维持编排能力：

安装和使用

快速路径：独立技能安装。 如果您只需要 simplicio-loop 技能包，则此 就足够了 - 不需要本机运行时依赖：

pip install simplicio-loop
simplicio-loop install            # current project
simplicio-loop install --global   # user-wide

仅安装技能+挂钩。如果您的运行时可以绑定本机助手，那么它们就是 可选加速，不是先决条件。 pip install simplicio-loop 是一个轮子：映射器和 dev-cli 内置于其中，因此它还提供了两个必需的运算符，simplicio-mapper （调查）和 simplicio-dev-cli （突变）——没有单独的 simplicio-mapper / 要安装的 simplicio-cli 软件包。

完整堆栈路径：repo 安装程序。 当您还需要更广泛的 Simplicio 本地堆栈时，请使用此路径 （操作员、捕获代理、仪表板、服务、运行时接线）：

git clone https://github.com/simpletibr/simplicio-loop
cd simplicio-loop

# install for your runtime (omit  to auto-detect)
bash scripts/install.sh  [--global] [--minimal]        # macOS / Linux
pwsh scripts/install.ps1  [-Global]                    # Windows
#  = a wired host of simplicio_loop/_catalog/harnesses.json (claude, codex, cursor, gemini, amp, cline, ...;
#            see adapters/MATRIX.md; hermes is still accepted as a legacy alias for simplicio_agent)

默认情况下，repo 安装程序是全栈的 - 它会安装所有内容。 一个命令即可设置整个堆栈： 运算符（simplicio-mapper 和 simplicio-dev-cli，内置于单个 simplicio-loop 中） 轮子并与其一起安装，自动处理 PEP 668 / 外部管理的 Python 和符号链接 二进制文件到 PATH），完整的 Python 堆栈（包本身）， 7 项技能 + 钩子，并连接了循环的 Stop 钩子，以及 始终在线的捕获代理 使用 Claude + Codex + Simplicio Agent 在后台进行路由和测量。 仪表板在 a 上打开一次 全新安装，然后按需安装（simplicio-loop dashboard / simplicio-economy.sh monitor）；的 菜单栏托盘永远不会自行打开 - 没有任何内容被迫保持打开状态。 仅通过 --minimal 为 headless/CI 跳过繁重的 deps + 机器服务。随时验证： bash scripts/simplicio-economy.sh status.

更新

python3 scripts/release_check.py check   # is a newer release published? — never auto-updates
bash scripts/update.sh []       # git pull → reinstall skills/hooks/operators → restart services
simplicio-loop update                    # pip-installed: latest GitHub release (--check: report only, --force: reinstall)

simplicio-loop update 安装最新的 GitHub 版本的 simpletibr/simplicio-loop 和 刷新全局技能。因为mapper和dev-cli是捆绑在wheel中的，所以它首先删除 任何 pre-monorepo 独立 simplicio-cli / simplicio-mapper 发行版（它们拥有相同的 文件）；可编辑的签出安装被告知 git pull 并重新运行 scripts/dev_install.sh。

release_check.py 将本地规范版本（pyproject.toml）与最新版本进行比较 GitHub 释放标签并打印明确的“MEASURED”|版本检查：有更新的版本可用......当您落后时，请在第 1 号线（10 号出口）处行驶 — 驾驶simplicio-loop 的 agent/LLM 的含义是 线路并运行更新本身，而不是默默地继续处理陈旧的结账。它从不应用 更新 - 检测到但拒绝的更新永远不会自动安装 - 并且打开失败（UNVERIFIED|, exit 0) 当 gh/network 不可用时，因此离线开发环境看起来永远不会损坏。 doctor` （如下）与其报告中的 OPTIONAL 行运行相同的检查。

update.sh 隐藏本地编辑，快进 main，从新源重新安装，重新启动 launchd/systemd 服务，以便他们运行新代码，并打印实时堆栈+节省。

CLI 命令图 — 每个命令的作用

所需的Mapper上下文和自动机器能力

每个循环执行工作流程都需要 Simplicio Mapper，包括独立的、 顺序执行和 Prism/wave 执行。集中准备上下文并 将工人绑定到当前的生成和摘要。 丢失或过时的映射器上下文会阻止工作，直到中央准备成功为止。

预期的工作人员默认设置是从可用机器自动物理准入 容量，保持前台响应能力。源更改删除固定 默认为 batch/tasks/fan-out 入口点；验证仍在进行中并且 这些编辑尚未包含在已安装的 3.43.10 版本中。

映射器上下文重用本身并不能证明提供者缓存命中。报告令牌和 成本节省仅来自可归因的提供商使用和通过质量关卡。 fastest/cheapest生产路线尚未建立。

主要的 simplicio-loop 入口点是面向用户的控制界面，用于规划、执行、验证和交付工作。使用最具体的 --help 来获取已安装版本中可用的确切选项。

独立设计。 Loop 使用自己的调度程序和钩子以及 Mapper 和 Dev CLI 运算符；没有 Runtime/MCP 后端。

零配置执行

默认入口点是 simplicio-loop ""（simplicio-loop turbo --repo . --task "" 的缩写）： 一项或多项任务的一个入口点。它不需要提供者，也不需要 API 密钥：调用技能的模型 计划和 simplicio-dev-cli 编辑，只需两个命令。命令 1 使用 Mapper 进行调查并打印 needs_plan 请求（任务、地图切片、其命名的文件的当前文本、计划格式和 确切的应用命令）。命令2是应用命令：模型将其JSON find/replace计划放入 Heredoc 主体，simplicio-dev-cli 应用它，--verify 运行您的测试（status、applied、failed 与 dev-cli 原因和文件摘录，verify）。无头自动化可以向 OpenRouter 询问计划； 参见 docs/CLI_COMMANDS.md。

simplicio-loop "Create pricing.py with order_total and fix the two bugs in inventory.py" --verify "python -m pytest -q"
# then run the printed command once, with the plan as its heredoc body (the plan can also come from a file: --apply plan.json):
simplicio-loop turbo --repo . --apply - --verify "python -m pytest -q" <<'PLAN'
{"operations":[{"path":"pricing.py","find":"","replace":"..."}]}
PLAN

来自 tasks.md（队列、批次、Prism）的受控运行使用 wave 流（具有自动协调屏障）：

# Preparar / Armar run a partir de especificação markdown:
simplicio-loop prepare --task task.md --repo .

# Executar via fluxo wave padrão (recomendado):
simplicio-loop wave 

# Uma tarefa usa tick; duas ou mais usam wave. As duas fecham com verify:
simplicio-loop tick  --repo . --task-index 1
simplicio-loop verify  --repo .

终止 run 的建议：请注意 simplicio-loop run 的终止和公共界面的专有性。如果使用（simplicio-loop run --task task.md 或 simplicio-loop run ），则可以自动拦截并重定向 simplicio-loop wave，保证执行完整和最大速度。

Operador Obrigatório： O ecossistema opera com simplicio-mapper estritamente obrigatório。 simplicio-mapper 确保存储库的集成和 LLM 的前缀缓存决定。

决策者 LLM / 代理人：Qual Fluxo escolher？

保证速度、经济和安全的最佳结果：

Dinâmica de Prompt Caching da LLM：是否可以大量缓存（10 vs 20 vs 30 tarefas）？

simplicio-loop com simplicio-mapper obrigatório, o prefixo de contexto (árvore do projeto, AST, regras e instruções do sistema) é fixo e canônico. LLM 的证明（通过 OpenRouter 或 Claude/Anthropic 进行 DeepSeek v4.1 Flash）应用程序 KV 缓存前缀匹配：

1. 冷启动摊销：
   • Na 1ª tarefa（冷启动）：O prefixo é viado e processado pela primeira vez。 LLM 严重或 KV- 缓存（cache_creation 或缓存未命中）。
   • 从第2个到第30个任务（缓存命中）：在提供者的缓存中找到相同的前缀（在5到10分钟的TTL窗口内）。仅任务的增量被处理为新的输入标记。
2. 命中率根据任务量变化：
   • 10 个任务：1 次冷启动 + 9 次缓存命中 = 90.0% 缓存重用。
   • 20 个任务：1 次冷启动 + 19 次缓存命中 = 95.0% 缓存重用。
   • 30 个任务：1 次冷启动 + 29 次缓存命中 = 96.7% 缓存重用。
3. 对成本和延迟的影响：
   • 命中缓存条目令牌的成本下降高达 90%（从 DeepSeek v4.1 闪存中的 $0.14/M 到 $0.014/M 令牌）。
   • 每个任务的延迟（第一个令牌的时间 - TTFT）急剧下降，因为 LLM 不会在每次迭代时重新计算整个存储库的嵌入或注意力。
   • 因此，“缓存随着每轮 30 个任务而增加”的实现在数学上是真实的，并且是 simplicio-mapper 架构的直接好处。

10 项任务的候选控制流程——尚未确定获胜者

有十个任务高于三任务直接并行阈值，因此循环通过 Prism wave 路由它们：隔离的工作树、租约、wave 屏障和序列化写入。执行始终是无人值守的 - 该堆栈中没有 Runtime/MCP 后端。

# 1. Inspect the profile before applying environment changes
simplicio-loop economy status --json

# 2. Block until the required operators and strict mutation policy are ready
simplicio-loop preflight --strict --json

# 3. Survey and enrich context through the bound operators
simplicio-mapper scan . --sync --json
simplicio-mapper inspect . --json
simplicio-mapper handoff . --task-file task.md --execution-context --json

# 4. Arm the drain scratchpad; this does NOT start workers
# The CLI resolves s=0 via its machine-capacity recommendation.
python3 scripts/arm_drain_prism.py --repo . --s 0 --batch-size 10 --json

# 5. Each task follows claim → implement → focused gate → evidence → PR/merge
#    The next wave starts only after reconcile-before-next.

不要将十个逻辑任务解释为十个不受限制的进程：物理 CPU/RAM/backpressure 限制仍然强制执行，并且写入按路径序列化。对于仅一到三个任务，请使用直接并行而不是 Prism。

棱镜的适用范围

公共命令 simplicio-loop prism 和 simplicio-loop wave 通过相同的受控批处理实现进行调度，具有类型化接收器和下一个屏障之前的屏障。 simplicio-prism skill/layer 对映射器、循环和开发工作以及组合 CLI 进行分类。混凝土排水波算子为scripts/arm_drain_prism.py。

在下一组被接纳之前，一波以协调 lease/result 结束。 武装是准备，而不是执行。映射器仍然是强制性的。请参阅 Prism/wave 接口详情。

重要的嵌套命令界面：

• queue: status, top, drain, resume, doctor, reclaim, migrate, gc, inspect, cancel.
• findings: list, report, reconcile, doctor, import.
• economy: status, print, apply.
• stack：lock，verify； extensions和ecc分别显示doctor。

典型的单任务命令：

simplicio-loop "" --verify ""   # default; you write the plan, Dev CLI applies it; no API key
simplicio-loop preflight --repo . --json
simplicio-loop orient --task "understand this repository" --repo .
simplicio-loop plan --task task.md --out contract.json
simplicio-loop prepare --task task.md --repo . --max-iterations 5
simplicio-loop wave 
simplicio-loop status --repo . --text
simplicio-loop progress --repo . --format markdown --once
simplicio-loop queue status
simplicio-loop verify 

完整的命令参考为docs/CLI_COMMANDS.md。命令界面可能因安装的软件包版本而异，因此请检查 simplicio-loop --version 和 simplicio-loop --help；当前存储库源是 3.43.11。

医生——验证+修复

python3 scripts/doctor.py            # report the whole stack (REQUIRED vs OPTIONAL)
python3 scripts/doctor.py --repair   # install/wire what's fixable; make everything operational
python3 scripts/preflight.py --json   # fail-closed mapper + dev-cli
# also: bash scripts/simplicio-economy.sh doctor [--repair]

doctor 分隔 REQUIRED （python3，循环包及其打包的 mapper/dev-cli bins， 7个技能，循环钩子，捕获代理 - --repair installs/wires 他们） OPTIONAL 加速方案（托盘依赖性）。 缺少可选件绝不是失败，而且 从不阻塞——Python引擎+确定性路径涵盖一切；退出代码为 0 作为 只要每一件 REQUIRED 商品都是健康的。

或者，在Claude Code/Cursor中，直接从最新版本的GitHub（市场上）安装：

gh release download --repo simpletibr/simplicio-loop --archive tar.gz
tar xzf simplicio-loop-*.tar.gz && cd simplicio-loop-*/
bash scripts/install.sh claude    # or: bash scripts/install.sh cursor

所以：

/simplicio-loop finish all the open issues

对于独立技能安装，唯一的要求是 PATH 上的 python3。对于回购协议 安装程序和源 GitHub-backed，您还需要 git + 经过身份验证的 gh。参见 INSTALL.md 和 adapters/MATRIX.md.

在无人值守的 24/7 运行之前： 确认源身份验证是持久的，保留不可逆操作 开启人门+秘密扫描，并确保配置可达的STOP/cancel路径。

安全（不可出售）

• 秘密扫描每个差异；击中时格挡。
• 人类端口操作 — 强制推送、历史重写、产品部署、data/schema 删除、 批量文件删除 → 停下来询问。无头+无审批者→消除破坏性能力。
• 强制执行，而不仅仅是承诺 - hooks/action_gate.py 是一个 失败关闭 PreToolUse / git-pre-push hook that mechanically blocks the above (and secret-laden commits) before they run. 即使模型忘记了安全契约，它仍然有效。 selftest 证明规则集（15/15）。
• 4 状态预执行判决 — 优化可能永远不会提高命令的风险等级。
• 加载前信任 — 感知塑造配置（钳位配置文件、抑制列表）是 在人类对其进行审查和哈希固定之前，它是不受信任的。
• 即时注入强化 - item/PR/comment 内容永远不能覆盖合约。
• 证据门控完成（绝不是错误的“完成”）； 失败打开钩子（永远不要困住特工 循环）；用于无人值守运行的显式 STOP/cancel 路径。

✅ 测试和本地检查（无付费 CI）

声明经过验证，而不仅仅是断言 - 并且门在本地运行，CI 成本为零：

python3 scripts/check.py             # complete local gate; runs only the tests the change can affect
python3 scripts/check.py --full      # every test file (run before a release tag)
python3 scripts/check.py --base REF  # diff against REF instead of origin/main
python3 scripts/check.py --core-gate # mandatory offline/bounded core; external lanes excluded
python3 scripts/impact_tests.py      # print the test files the change affects

默认测试选择是符号级（scripts/impact_tests.py）：它将工作树与 --base（默认origin/main），保留其源的顶级函数、类和赋值 更改，并选择命名此类符号并到达其模块的测试文件。名为 a 的测试 更改的非Python文件（例如SKILL.md）并且更改的测试文件也被选择；生成的 镜像（plugin/、simplicio_loop/_bundle/）被奇偶校验门覆盖。 --full 运行每个 测试文件； --core-gate 保持其固定的核心选择。

Monorepo（packages/mapper，packages/dev-cli）：bash scripts/dev_install.sh 设置一个 venv，其中所有三个包均可从其存储库内路径进行编辑，并且 python3 scripts/check.py --包映射器|开发-cli|循环|all (or --changed，范围是什么 you touch vs origin/main）从其仓库内位置运行一个包自己的快速门 - 请参阅 AGENTS.md § 开发。

这两个命令都需要可导入的 pytest；它的缺失是 pytest_unavailable，从来都不是 直接执行回退。核心门运行声明审计、镜像奇偶校验、核心 pytest 测试、 循环合约、清洁环境合约、token/repository 预算和便携式阶段合约 验证。它使用经过净化的子进程环境，禁用第三方 pytest 自动加载， 并将 loopback/AF_UNIX 套接字限制应用于继承的 pytest 和 Python 后代 大门环境；它不会对任意外部 CLIs 进行沙箱处理。它的全球截止日期为 600 秒，更短 每个阶段的最后期限，如果没有实际运行强制性测试，则会失败。已安装的运行时，实时 APIs， 同级存储库、发布版本和其他真正的外部集成都明确保留在其中 标记车道并报告为 unavailable/excluded — 从未默默提升为 PASS。

docs/SCRIPTS_INVENTORY.md 记录与门相关的核心 （环路驱动或此门所需）和卫星 (opt-in/advanced) 边界；是的 并非对 scripts/ 下的每个公用事业进行普查。当前结帐及其本地登机口收据 对于库存和执行计数具有权威性。以核心引领；将其余部分视为 当任务需要时，您可以选择使用高级的、选择加入的功能。

• 测试套件（tests/，需要 pytest） - 工作人员的确定性 selftests，加上循环的 e2e 驱动程序（hooks/loop_stop.py）：它证明了循环在证据上停止，忽略了一个裸露的 ，并且在上限上停止作为不同的出口 - 并且证据生产者 当他们的工具链不存在时，BLOCK（绝不假通）。各个遗留测试模块可能 保留开发者自运行程序，但 scripts/check.py 从未将部分机制视为 替代 pytest 集合。
• 索赔审核（scripts/claims_audit.py，失败关闭）-每个 scripts/*.py 文档 存在引用 · 所有文件的扩展点计数一致 · 每个引用的工作命令 实际运行 · 附带的 simplicio_loop/_bundle/ 技能与源字节相同。
• 影响审计 (scripts/impact_audit.py) — 对于任何代码任务，证明所声明的任务 表面覆盖局部爆炸半径：依赖性、反向依赖性和相关测试。

  python3 scripts/impact_audit.py audit . --file path/to/seed.py --cover path/to/seed.py --fail-on high
  

• 流程审核 (scripts/flow_audit.py) — 对于混合 front/back/service 存储库，生成 endpoint_compare 证据图和客观集成差距失败：

  python3 scripts/flow_audit.py audit . --fail-on high
  

• 将其连接为 git pre-push hook 以免费保持 main 的诚实：

  printf '#!/bin/sh\npython3 scripts/check.py\n' > .git/hooks/pre-push && chmod +x .git/hooks/pre-push
  

运行前安装开发额外（pip install "simplicio-loop[dev]"） scripts/check.py：pytest是必需的门依赖项。

跨运行时的工作项注释协调

simplicio-loop可以在Claude Code、Codex、Cursor、Gemini和Hermes中同时运行。当运行绑定到 GitHub 问题时，它会发布对该问题规范注释的幂等生命周期更新：声明、计划、进度、证据、PR 和关闭。不同机器上的代理可以通过相同的 GitHub 线程进行协调，而无需共享本地文件系统。

pwsh scripts/install.ps1 claude -Global
pwsh scripts/install.ps1 codex -Global
pwsh scripts/install.ps1 cursor -Global
pwsh scripts/install.ps1 gemini -Global
pwsh scripts/install.ps1 hermes -Global   # legacy alias for simplicio_agent

本地队列、租约、工作树、心跳和证据在每台机器上保持活动状态； GitHub 注释是已发布的共享协调投影。如今，不可用或未经身份验证的 GitHub 会记录同步失败，而无需发明远程确认。阶段代理路线图针对 GitHub-bound 运行加强了这一点：#433 使得在 COMPLETE 之前必须进行评论确认。 #436 仅当每个连接器都经过验证连接时，才会向 Azure DevOps、Jira、Asana 和 Trello 添加相同的投影；显式跳过断开连接的可选跟踪器。

不需要或不接受 GitHub 操作作为此存储库的验证证据；当地的 门是权威的。生命周期状态由本地运行时集成预测 配置；它可以管理simplicio:status:标签和 GitHub 项目 v2 状态字段。投影是运行时中立的：它接受 Claude、Codex、 Cursor、Gemini、Kiro、Antigravity、Hermes/Simplicio Agent、OpenClaw 以及未来的提供商。套装 这些存储库变量用于启用 Project v2 移动：

SIMPLICIO_PROJECT_NUMBER       # project number, for example 7
SIMPLICIO_PROJECT_OWNER        # optional; defaults to the repository owner
SIMPLICIO_PROJECT_OWNER_TYPE   # organization (default) or user
SIMPLICIO_PROJECT_STATUS_FIELD # optional; defaults to Status

当未配置项目时，标签仍会更新。人类的评论不会移动卡片；只有 标记的 Simplicio 生命周期注释、问题 open/close/reopen 事件或显式工作流程 调度可以改变状态。该工作流程使用 issues: write 和 repository-projects: write 并且永远不会发布第二条协调评论。

模型看到了什么

使用此存储库的代理会看到 AGENTS.md，即加载的 SKILL.md 文件， 以及由 simplicio-loop 打印的紧凑型 JSON（orient --brief、prepare、 apply、wave、verify）。源文件仅作为目标进入上下文 这些命令的名称永远不会作为完整树转储。

代币效应

该循环通过 Mapper 调查和确定性回答存储库事实 命令而不是模型读取，每个命令都会打印紧凑的 JSON。输入 因此，令牌随着任务目标的增长而增长，而不是随着存储库的大小而增长。

KV 缓存效果

每个合约都以不可变的标头开始，每个循环都会打印 JSON 首先是 schema 和稳定字段，其次是易失性字段（run_id、时间戳、 路径）最后。提示前缀在各个回合中保持字节相同，因此 提供商在第一次调用后从缓存中提供服务。基准测试运行失败 当稍后的调用读取没有缓存时（bench/llm_ab）。