symphlo

# Symphlo > 在 Apache License 2.0 下开源的本地 Alpha 版本。 [](https://github.com/huisezhiyin/symphlo/actions/workflows/ci.yml) [](LICENSE) [](#current-local-alpha-boundary) ## 一个用于持久 Agent 工作 的可滑动、可观察的外循环 Agent 擅长于循环：检查、推理、使用工具、修订和继续。 这种自主性正是它们有用的原因——也是在单个 Agent 会话中，工作难以操作的原因。 Symphlo 允许您将 Agent 内部循环的选定高级阶段**外部化**为持久的外循环。其任务粒度可以在一个广泛的 Agent 节点和多个可观察的边界之间滑动，当恢复、替换、维护或显式移交需要额外的协调时： ```text 一个自主 Agent 会话 一个 Symphlo 外循环 研究 研究 Agent 节点 计划 ↓ 接受的上下文 草稿 ───────────▶ Writer Agent 节点 审查 ↓ 接受的上下文 修订 Reviewer Agent 节点 交付 ↓ 接受的上下文 ... article.md 工件 ``` 粒度也是 Agent 自主性和流程编排之间的滑块： ```text 广泛的 Agent 节点 明确的语义边界 流程 -> [ 自主 Agent 循环 ] 流程 -> 研究 -> 草稿 -> 审查 Agent 拥有大部分迭代 流程拥有更多的移交 高 Agent 自主性 <--------------------------------> 高流程编排 ``` Symphlo 不会修改 Agent 以沿此频谱移动。它通过有界任务、接受的上下文、结果契约、效果、执行器选择和状态转换来塑造工作。 这不是思维链跟踪。当前的本地 Alpha 版本不会将 Agent 节点分成其私有模型调用、工具调用或回合。每个 Agent 节点都保留其正常、 opaque 的内部循环，并决定**如何**完成其任务。 `可滑动`并不意味着自动分解或运行时循环深度模式。它是一种设计和维护选择，关于有多少高级 Agent 循环值得外部化。每个外部化边界都保留了接受的输入、执行器、效果、事件、结果、移交和工件。 在刻意的细粒度极限下，Agent 流可以使用显式原子的模型推理和工具调用节点，以便流程拥有决策循环。那是一种不同的真实执行器契约，而不是检查或分解现有 Agent 的私有循环。通用原子 LLM 节点、分支循环和自动转换在本地 Alpha 版本中未实现。 外部化还开启了执行供应。每个边界都可以有意绑定正确的 Agent、HTTP 服务、MCP 工具、CLI、本地脚本或人类。因此，不同的 Agent 和功能可以通过明确的、可检查的移交进行协作，而不是让一个 opaque 的 Agent 会话来即兴整个链条。 这让用户可以理解步骤、实时状态、问题和交付成果。 它为开发者提供了版本化的契约、可替换的执行器和可比较的运行证据。Symphlo 拒绝基于希望的编排。它提供了可维护的控制，而不是简单地等待 Agent 或 LLM 来解决所有问题。 **流程控制 `什么 / 谁 / 何时 / 移交`。Agent 控制 `如何`。** ## 五分钟运行 您需要 Git、`make`、[`uv`](https://docs.astral.sh/uv/)、Python 3.12、Node.js 24 和 pnpm 11.6.0。不需要 Docker、模型账户或 API 密钥。`make desktop` 安装锁定依赖项、构建应用程序并打开一个具有自己的本地运行时的原生 Symphlo 窗口。 ```bash git clone https://github.com/huisezhiyin/symphlo.git cd symphlo make help make doctor make desktop ``` `make help` 是一个零依赖命令映射。`make doctor` 检查 Python、Node.js、pnpm、临时状态访问以及可选的 Codex/OpenCode 可执行文件是否可发现；缺少的 Agent 不会阻止离线演示。 `make desktop` 打开完整的本地产品作为独立的桌面应用程序。桌面进程拥有一个短暂的 IPv4 环回运行时，调用选定的确定性/Codex/OpenCode 执行器，并在应用程序退出时终止运行时。从首页开始。其零凭证的黄金流程是： ```text 计划 -> 在 worker_loop 中草稿 -> 审查作为持久外循环边界 -> 在同一个 worker_loop 会话中修订 -> article.md ``` 草稿和修订是分别由捆绑的虚构进程装置支持的 Agent 节点。运行证明它们共享一个不透明的会话引用，同时保持不同的回合引用和接受的上下文。该装置证明了真正的 `symphlo.agent-session.v1` 进程边界；它是确定性的，不声称模型质量或捆绑的 AI 提供商。 检查流程和画布，运行它，然后打开运行。选择草稿和修订以比较它们的会话证据，选择审查以查看它们之间的持久移交，并打开 `article.md`。每个运行都保留了接受的节点结果和工件，在存储库下方的应用程序用户数据目录中。 对于仅限 Web 的开发，`make app` 在 `http://127.0.0.1:8765` 处提供相同的控制台和运行时。这是一个开发配置文件，而不是不同的产品。 原生桌面验收目标目前是 Apple Silicon 上的 macOS。运行时、终端演示和 Web 应用程序使用可移植的契约，CI 目标是 Ubuntu 24.04，但 Windows 和原生 Linux 软件包尚未验证。`make desktop-package` 生成一个未签名的 macOS 应用程序；签名、公证、安装程序和自动更新在此 Alpha 版本之外。 想要一个终端演示来证明任务粒度和可重复性？`make demo` 运行一个平衡的确定性写作流程两次，并打印两个有用的本地 URL： ```text article=file:///.../artifacts/<run-id>/article.md report=file:///.../evidence/index.html ``` 使用 `make demo-open` 自动打开只读文件版本。其画布显示外部 Agent 循环，其时间线重放持久事件，其证据面板公开每个接受的输入、结果、执行器、效果、移交和工件，而不暴露私有 Agent 推理。创建只读文件报告的新运行需要 `make desktop` 或 `make app`，因为 `file://` 页面没有运行时主机。 对于第一次运行，检查四个事项： 1. 打开 `article` 以查看接受的交付成果； 2. 打开 `report`，按 **Replay**，并观察接受的运行跨画布移动； 3. 选择一个节点以检查其输入、效果、执行器、结果和事件； 4. 切换运行 1 和运行 2 以查看运行时拥有持久真相，而不是会话。 所有生成的 state 都保留在存储库外部的临时目录中。要保留它，请提供一个空目录： ```bash make demo STATE_DIR=/tmp/symphlo-demo ``` Symphlo 拒绝覆盖非空状态目录。 ## 滑动 Agent 任务粒度 相同的写作目标可以使用同一运行时和 `article.md` 契约的三个不可变的流程定义： | 配置文件 | 可观察的 Agent 角色节点 | 何时使用 | | --- | --- | --- | | `compact` | Writer | 一个执行器可以拥有整个内部循环 | | `balanced` | Planner → Writer → Editor | 计划和草稿是有用的移交边界 | | `fine` | Researcher → Planner → Writer → Reviewer → Reviser | 每个阶段都需要单独的证据、恢复或替换 | 试试它们： ```bash make demo GRANULARITY=compact make demo GRANULARITY=balanced make demo GRANULARITY=fine TOPIC="为什么需要持久状态的长期 Agent 工作" ``` 这是**滑动任务粒度**，而不是“节点越多越好”。当它改善观察、恢复、执行器替换或维护时，请添加边界。当额外移交只会增加仪式时，请将工作保留在 Agent 的内部循环中。 边界必须获得其协调成本。它创建了另一个契约、移交和故障表面，因此仅当其独立证据、恢复、替换或维护价值大于该成本时，才外部化一个阶段。 ## Symphlo 的优势 一个自主的 Agent 会话通常是开放式、探索性或一次性工作的最简单答案。一个 Skill 对于打包可重用的执行知识非常出色。两者都不是一种持久的操作模型，用于必须重复运行的任务。 当工作具有以下一个或多个属性时，Symphlo 变得有价值： - **固定编排** — 已知的阶段、审批、效果或交付成果； - **高重复** — 相同的工作必须一致地运行，并带有新的输入； - **长链** — 工作跨越许多步骤、执行器、故障或会话； - **重要的移交** — 接受的结果必须在下一阶段检查； - **维护压力** — 团队需要比较运行并替换不稳定的步骤。 在这些场景中，显式外部流程可以比松散的 Skill 调用或一个长自主 Agent 会话更具重用性和可操作性。用户入口仍然可以保持简单：自然语言目标或一个命令。 ### 重复办公工作的有界智能 许多有用的任务需要的自主性比通用 Agent 少，但比确定性脚本需要更多的判断：分类更改的电子邮件、从文档中提取字段、草拟回复、组装报告或标记异常。最佳形式通常是确定性流程骨架，带有边界 Agent 或能力节点，仅在解释有价值的地方。 普通操作员应该能够选择一个已证明的任务，提供材料，确认敏感效果，并接收熟悉的交付成果。流程作者和开发人员可以检查更深层次的契约和证据。目标不是更便宜的低质量 Agent；而是具有可预测边界的可重复智能工作。 ### 从外部调试 Agent 工作 Symphlo 还可以将一个现有的 Agent 作为一个广泛的黑盒，持久化其接受的输入和输出，然后将循环的故障点或审查点外部化为更窄的节点。上下文快照、执行器身份、事件、工件和可比较的运行使隔离不稳定的阶段、替换其 Agent 或工具并在不暴露私有推理的情况下衡量结果成为可能。 当前的 Alpha 版本提供了证据基础和跨运行比较。节点级分叉/重新运行、自动化评估、修复和完整的故障本地化仍然是未来的调试功能。 ### 选择正确操作模型 | 用途 | 最佳情况 | 拥有持久的跨步骤真相？ | | --- | --- | --- | | 一个 Agent | 工作是开放式的、探索性的或一次性的 | 通常没有 | | 一个 Skill | Agent 需要可重用的指令、工具和约定 | 没有；它改进了 `如何` | | 一个 Symphlo 流程 | 阶段重复、移交重要或工作必须在会话之间存活 | 是；流程、运行、上下文和工件 | 这些层可以组合。一个 Symphlo 节点可以在 Agent 的正常循环中调用一个 Skill。区别在于所有权：执行知识可以保留在节点内，而接受的任务状态保留在节点外部。 ## 没有剧场的 Multi-Agent Agent 是一个一流的节点执行器。不同的节点可以解析为不同的 Agent，也可以解析为同一个 Agent，但具有不同的任务契约。产品的证明不是 Agent 徽标的数量。它是持久的边界： - 接受的输入和上下文； - 声明的效果和授权； - 确切的执行器 ID 和版本； - 有序事件和终端状态； - 接受的结果和下游移交； - 可检查的工件和可比较的运行证据。 会话能力强的 Agent 适配器还可以将选定的节点绑定到一个明确的 `session_group`。然后运行时证明这些单独的任务边界使用了相同的 opaque 外部会话和不同的回合引用。没有组的节点是一次性的，而绑定到一次性执行器的分组节点会失败验证。会话连续性是执行器证据，而不是接受的上下文、运行状态或工件的替代品。 终端演示使用确定性角色模拟器，并为每个节点标记 `E1_DETERMINISTIC`。黄金流程还调用虚构的会话协议装置作为 `E2_REAL_EXECUTOR`；该标签证明了一个真正的进程边界，而不是真正的模型。两个路径都不能假装多个异构 Agent 合作。 ## 使用真正的 Agent CLI 运行 两个引用预设已经在本地完成平衡的 Planner → Writer → Editor 流程： ```bash # 需要已安装和认证的 Codex CLI。 make demo-codex # 需要已安装的 OpenCode CLI 和有效的提供程序。 make demo-opencode ``` 实时预设默认情况下只有一个运行，以保持时间和模型使用量 bounded。设置 `LIVE_RUNS=2` 以生成跨运行比较证据。Codex 默认使用 Codex CLI 0.133.0 上的已验证 `gpt-5.4` 模型；如果您的 CLI 支持不同的模型，请覆盖它： ```bash make demo-codex CODEX_MODEL=your-supported-model LIVE_RUNS=2 ``` Codex 预设是短暂的，并请求只读沙盒。OpenCode 预设使用 `--pure --format json`，并且只接受文本事件；OpenCode 仍然拥有其提供程序配置和会话数据。Symphlo 持久化每个接受的节点结果的确切 CLI 版本和命令指纹。 如果实时命令失败，请先运行 `make doctor`。它证明了可执行文件发现和离线路径，而不是提供程序身份验证或模型可用性。 ## 发现和绑定本地能力 在桌面应用程序中打开 **能力**，将本地执行供应转换为版本化的节点绑定： 1. 发现已安装的 Codex/OpenCode CLI 和用户本地 Agent 描述文件，或添加受信任的能力； 2. 验证和探测它而不保存； 3. 显式保存到用户本地能力目录； 4. 在画布上添加或选择一个节点，并绑定兼容的能力； 5. 保存并运行流程，然后在运行中检查执行器身份、效果、结果和事件。 一个可选的 `agent-cli-descriptors.json` 在本地应用程序的外部状态目录中，可以描述另一个已安装的 Agent，而无需将提供程序名称、路径或凭证添加到 Git 源代码树中。发现仅证明可执行身份和版本。保存后，**测试连接** 运行任何固定的非变异就绪探测，由描述文件声明。外部 Agent、帐户、守护进程和提供程序配置仍然是用户拥有的状态。 描述文件可以选择通过用户本地适配器加入提供程序中立的 `symphlo.agent-session.v1` 协议。该适配器通过标准输入接收有界的 JSON 请求，并返回最终文本和不透明的会话和回合引用。提供程序命令和凭证保留在公共源代码树之外。 本地 Alpha 支持四种类型： | 类型 | 节点 | 契约 | | --- | --- | --- | | `agent_cli` | `agent.task` | 标准输入上的有界提示或最终 argv | | `cli` | `capability.task` | 标准输入上的一个 JSON 请求；标准输出上的 JSON 或文本 | | `mcp_stdio` | `capability.task` | MCP 初始化、`tools/list`、`tools/call`、关闭 | | `http` | `capability.task` | 固定的 GET/POST URL 和有界的 JSON 响应 | 每个本地运行时还公开了一个无凭证的 `http.sample-json` 能力。它通过真正的环回 POST 发送接受的上下文，并返回确定性的 JSON，使其适合测试 HTTP 能力边界。它是一个传输样本，而不是文章质量或策略门。它的环回 URL 和样本指纹在桌面启动时刷新到一个新的临时端口；正常保存的能力指纹不会更改。 CLI 和 MCP 使用带有 no shell 的固定参数向量。保存的定义固定了一个不可变的指纹。秘密、自动安装、远程 MCP 和任意 shell 命令故意在此 Alpha 版本之外。引用的能力会阻止其删除的保存流程。 最重要的是，画布是可执行的，而不是装饰性的。Symphlo 编译确保存的线性流程和节点绑定到规范的运行时契约。不支持的分支或节点类型会失败验证，而不是静默地运行不同的内置流程。 存储库包含在 [`examples/capabilities/README.md`](examples/capabilities/README.md) 中记录的无凭证 CLI 和 MCP 固定装置，用于契约测试。 ### 绑定另一个命令执行器 可选的 E2 配置文件可以在每个 Agent 角色节点的运行一个用户安装的 Agent 命令。该命令从标准输入中读取一个有界的 UTF-8 任务提示，并将其接受的文本结果写入标准输出： ```bash make demo \ GRANULARITY=balanced \ AGENT_COMMAND='your-agent-command --read-prompt-from-stdin' ``` 使用 `AGENT_TIMEOUT=300` 来更改每个节点的超时时间。 Symphlo 将参数向量指纹转换为不可变的流程标识，使用 `shell=False` 执行它，并将接受的节点输出记录为 `E2_REAL_EXECUTOR`。它不会存储原始命令参数、标准错误内容、凭据或环境值。 存储库中包含一个确定性的外部进程夹具，以在不安装 Agent 的情况下验证标准输入/输出协议： ```bash make demo AGENT_COMMAND="$(uv python find 3.12) examples/agents/stdio_fixture_agent.py" ``` E2 表示一个真正的子进程产生了接受的输出。它本身并不证明命令是 AI 代理或其输出是高质量的。 **安全边界：** 命令继承当前环境，并在选定的工作区中运行。 Symphlo 不会对它进行沙盒隔离。因此，Agent 节点会声明广泛的 `execute_process`、本地/外部读取和本地/外部写入效果。仅绑定您信任的可执行文件，切勿直接在命令字符串中放置凭据。 ## 保存的内容 每个 demo 都会生成： ```text evidence.sqlite3 artifacts/<run-id>/article.md evidence/ flow.json run-<n>.json comparison.json index.html ``` 流程定义、运行状态、节点证据、上下文、事件和工件是任务的真实来源。对话和私有 Agent 会话是执行细节。 桌面和 Web 允许一个活动本地运行异步显示其实时步骤状态，并不断轮询持久证据。**停止** 首先记录 `cancel_requested`；在运行变为 `cancelled` 之前，会终止并回收进程支持的执行器，而未完成的 HTTP 调用仍受其超时限制。取消阻止了后续节点和未接受的结果继续进行 — 它不会撤销已经发生的外部影响。 ## 当前本地 Alpha 边界 已实现： - Python 3.12 干净的本地运行时； - 不变的线性流程和精确的执行器解析； - SQLite 运行、节点、上下文、事件和工件证据； - 异步实时运行受理、持久取消和进程边界清理； - 可选的相同运行 Agent 会话组，带有持久绑定/重用证据； - 紧凑、平衡和精细的多 Agent 编写配置文件； - 确定性离线执行器、实时验证的 Codex/OpenCode 预设和通用 E2 标准输入/输出命令； - 用户本地功能目录，带有 Agent CLI 发现和手动 CLI、MCP 标准输入/输出和 HTTP 绑定； - 应用拥有的 React 首页/流程/运行产品，带有版本化的环回本地 API； - ReactFlow 画布，其支持的保存线性图是精确运行时流程，以及用于运行切换、有序事件、上下文、节点结果和工件的真实证据工作区； - 零依赖命令帮助、安全就绪检查和简洁的预期错误输出； - 零凭据快速入门以及 Python 和严格 TypeScript 测试。 尚未实现：提供商 SDK 适配器、重试、恢复/修复、分支、并行性、批准、通用图形构建器、远程控制平面或服务器部署。通用原子 LLM 节点、自动粒度转换、节点级运行分叉/重跑和完整的 Agent 调试套件也超出了此 Alpha 范围。当前本地 API 是版本化的，但仅限于环回。画布是应用拥有的编辑器，用于支持的可移植流程合约的线性子集；持久流程 DSL 和运行时证据，而不是 React 状态，是真实来源。 在本地验证所有内容： ```bash make check ``` ## 下一步阅读 - [`docs/vision/observable-outer-agent-loop.md`](docs/vision/observable-outer-agent-loop.md) — 完整的观点。 - [为什么通用代理是个陷阱](https://github.com/huisezhiyin/sdd-riper/blob/main/docs/general-purpose-agents-are-a-trap.md) — 产品动机背后的中文背景论文。 - [`docs/demo/README.md`](docs/demo/README.md) — demo 和证据指南。 - [`PROJECT_SPEC.md`](PROJECT_SPEC.md) — 持久产品和架构合约。 - [`LICENSE`](LICENSE) — Apache License 2.0 条款。 - [`NOTICE`](NOTICE) — Symphlo 版权声明。 - [`PUBLIC_SOURCE_MANIFEST.md`](PUBLIC_SOURCE_MANIFEST.md) — 确切的公共源边界。 - [`THIRD_PARTY.md`](THIRD_PARTY.md) — 依赖和可选执行器清单。 - [`CONTRIBUTING.md`](CONTRIBUTING.md) — 贡献范围和验证。 - [`SECURITY.md`](SECURITY.md) — 漏洞报告和安全边界。 Symphlo 是 Apache-2.0 开源本地 Alpha。 通过 demo 和源代码检查证明测试的技术边界；它并不意味着稳定的 API、签名安装程序、生产支持或捆绑模型/提供商。