Skip to content

feat(local): support ZCode portable workflow adapter (#125) - #214

Open
wycocoyu wants to merge 4 commits into
Tencent:mainfrom
wycocoyu:feat/zcode-local
Open

wycocoyu wants to merge 4 commits into
Tencent:mainfrom
wycocoyu:feat/zcode-local

Conversation

@wycocoyu

Copy link
Copy Markdown
Contributor

Summary

Implements ZCode Local host integration for LoopForge Portable Edition (resolves #125 Local half).

Key Changes

  • Portable Host Integration: Adds zcode target to devflow_cli/targets/zcode.py and editions.py, installing portable skills under <project>/.zcode/skills/. Rejects Classic installation with an actionable hint to run loopforge skills install zcode.
  • Adapter & Disambiguation: Adds local/skills/devflow/adapters/zcode/adapter.md and manifest.json. Explicitly guides the agent to drive DevFlow via the workflow_state.py state machine, and guards against invoking ZCode built-in CreateWorkflow.
  • Runtime-Core Alignment: Resolves host adapter by host identity and base directory (.zcode/skills/devflow) rather than generic agent availability, avoiding false matches with Claude Code.
  • Documentation: Updates docs/local/compatibility.md, architecture.md, usage.md, local/README.md, and root README.md with ZCode entrypoint (/skill devflow "<task>").

Verification Evidence (Exit Code 0)

  1. Deterministic Test Suite:
    • python3 scripts/build-classic-hosts.py --check -> OK
    • bash scripts/validate.sh -> Validation passed (6/6 steps)
    • bash scripts/smoke-install.sh -> Smoke install passed (30 portable + 25 CLI tests)
    • bash scripts/e2e.sh -> 29 tests passed
    • bash scripts/test-observability.sh -> 393 tests passed (131 per host)
    • PYTHONPATH=src python3 -m unittest tests.test_installer -> 23 tests passed
  2. Live ZCode Sandbox Execution:
    • Executed zcode -p "/skill devflow ..." in /tmp/zcode-devflow-demo, completing PHASE-0 -> SOLO -> SUMMARY with 6 unit tests passed.
  3. ZCode Desktop App Live Verification:
    • Verified live in ZCode Desktop App (sess_343a27d6-9550-45fe-8213-90601358c52d) running on memex project; completed small route with 6/6 tests passed and artifacts validated.
  4. Independent Model Review:
    • Verified by independent review via OpenCode openai/gpt-6.1-sol#high (13 boundary tests passed); refined async wait semantics and timeout error handling in adapter.
中文说明

概述

实现 LoopForge 本地工作流对 ZCode 本地宿主的接入支持(解决 #125 本地宿主部分)。

核心变更

  • Portable 宿主接入:在 devflow_cli/targets/zcode.py 与 editions.py 中增加 zcode 目标,将 Portable 技能安装至 <project>/.zcode/skills/ 目录。Classic 安装执行拦截并输出可执行指引:loopforge skills install zcode。
  • 适配器与路由消歧:提供 local/skills/devflow/adapters/zcode/adapter.md 与 manifest.json,明确指导 Agent 使用 workflow_state.py 状态机,禁止调用 ZCode 内置的 CreateWorkflow。
  • 运行时核心对齐:按宿主身份与基础目录(.zcode/skills/devflow)选择适配器,而非仅凭是否存在 Agent 工具,避免与 Claude Code 产生误匹配。
  • 文档矩阵对齐:更新 docs/local/compatibility.md、architecture.md、usage.md、local/README.md 与根目录 README.md,增加 ZCode 调起入口(/skill devflow "<需求>")。

确证凭据(退出码 0)

  1. 确定性测试套件:
    • python3 scripts/build-classic-hosts.py --check:通过
    • bash scripts/validate.sh:通过(6/6 检查通过)
    • bash scripts/smoke-install.sh:通过(30 项 Portable + 25 项 CLI 测试)
    • bash scripts/e2e.sh:29 项测试全部通过
    • bash scripts/test-observability.sh:393 项测试全部通过(三宿主各 131 项)
    • PYTHONPATH=src python3 -m unittest tests.test_installer:23 项测试全部通过
  2. ZCode CLI 沙盒实跑:
    • 在 /tmp/zcode-devflow-demo 运行 zcode -p "/skill devflow ...",完整走通 PHASE-0 -> SOLO -> SUMMARY,6 项单测全绿。
  3. ZCode 桌面端真实会话复验:
    • 在 ZCode 桌面端实测会话(sess_343a27d6-9550-45fe-8213-90601358c52d)中跑通完整流程,6 项单测通过且产物通过双门禁校验。
  4. 异构模型独立审查:
    • 通过 OpenCode openai/gpt-6.1-sol#high 独立复审(13 项补充边界测试全部通过),并按审查意见补强了异步等待与超时错误恢复契约。

cocoyu added 3 commits November 12, 2026 02:02
Install ZCode as a Portable-only host under .zcode/skills, with a Pi-shaped adapter manifest and an Agent-based adapter guide that guards against the built-in CreateWorkflow tool.
Classic install is rejected with a skills install hint; runtime-core selects the adapter by host identity and Base directory rather than the mere presence of Agent.
@Robert0622

Copy link
Copy Markdown
Collaborator

LoopForge PR Review — head ad5efd9cfc406d1e3716fdd38b294d0180ff53c1

Verdict: ✅ Pass

  • Scope: 19 files, +129/-23, 3 commits. Implements ZCode Local host integration (resolves [Feature]: 支持 ZCode 与 Reasonix 作为执行器与本地宿主 #125 Local half): local/src/devflow_cli/targets/zcode.py + editions.py add the zcode target and portable-only skill install under <project>/.zcode/skills/ (rejects Classic install with an actionable hint); new local/skills/devflow/adapters/zcode/{adapter.md,manifest.json}; core.py resolves the host adapter by host identity + base dir rather than generic agent probing, avoiding a false-positive match with Claude Code; docs (docs/local/*, local/README.md, root README.md) updated; tests added/extended in local/tests/test_installer.py and local/tests/e2e/fake_agent.py. The last commit (ad5efd9) is a doc-only clarification of the adapter's wait() contract: distinguishes an explicit async transition (wait for <task-notification>) from a bare timeout/cancel/error, which now must go through error recovery/retry instead of assuming the background task is still running.
  • Verified this round in an isolated, credential-free sandbox: python3 scripts/build-classic-hosts.py --check → OK; PYTHONPATH=src python3 -m unittest tests.test_installer -v → 23/23 passed, including the new test_zcode_installs_project_skills_and_rejects_classic.
  • Not re-run this round (tooling/time budget — sandbox is missing rg and the Python yaml module, so scripts/validate.sh could not complete past step 1/6; smoke-install.sh/e2e.sh/test-observability.sh not attempted locally): relied on the PR's own reported results (exit 0 for all) plus CI, which is green across all 16 required/optional checks at this head SHA.
  • Reviewed the full diff: skill install path, Classic-rejection hint, and host-identity resolution logic match the PR description; no stray references to the old adapter-matching heuristic remain.
  • No blocking issues found; flagging the partially-local verification (validate.sh/e2e scripts) for anyone doing a follow-up deeper review.

Yanami-2K
Yanami-2K previously approved these changes Nov 14, 2026

@Yanami-2K Yanami-2K left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

核对了 #125 的 Local 部分:“至少支持一种安装路径”由 loopforge skills install zcode 提供,安装到 .zcode/skills/;Classic 安装会被拒绝并给出可执行的提示;不会修改 ~/.zcode。editions.py、core.py、targets/zcode.py 沿用了 codex/hermes 的现有模式。runtime-core.md 要求同时匹配宿主身份和 Base directory,避免与 Claude Code 的 Agent 工具误匹配。test_zcode_installs_project_skills_and_rejects_classic 断言了安装产物、入口、adapter manifest 和拒绝 Classic 时的提示文案,smoke-install 也覆盖了 zcode。CI 全绿,批准。

一个不阻塞的小问题:local/README.md 里“use skills install pi, skills install dsh, or skills install hermes, or skills install zcode”重复了 or,可以顺手改成“skills install pi, dsh, hermes, or zcode”。

@wycocoyu
wycocoyu dismissed stale reviews from Yanami-2K and ghost via fc42f54 November 15, 2026 09:49
@wycocoyu

Copy link
Copy Markdown
Contributor Author

@Yanami-2K Thanks for the review! Commit fc42f54 updated local/README.md line 22 to `skills install pi`, `dsh`, `hermes`, or `zcode` as suggested.

Regarding the 4 failing checks on fc42f54 (validate (3.8), e2e (ubuntu-latest, python 3.8, node 22), e2e-browser, and e2e-required):

Since pushing fc42f54 dismissed the previous approval, could you please re-approve #214 when convenient, and we can re-run CI / rebase once #886 lands?

中文说明

@Yanami-2K 感谢 Review!提交 fc42f54 已按建议将 local/README.md 第 22 行修改为 `skills install pi`, `dsh`, `hermes`, or `zcode`。

关于 fc42f54 上 4 项 CI 检查失败(validate (3.8)、e2e (ubuntu-latest, python 3.8, node 22)、e2e-browser 与 e2e-required)的说明:

由于推送 fc42f54 使之前的批准自动失效,方便时请帮忙对 #214 重新点一次 Approve,待 #886 合入后我们再重跑 CI 或做一次变基即可。

@Robert0622

Copy link
Copy Markdown
Collaborator

LoopForge PR Review Bot — reviewed commit fc42f542a5abc40d1d3479fe81e50e9d3a331363

Verdict: PASS ✅

What I checked

  • Diff: 19 files, +129/-23 — adds the zcode portable host target (local/src/devflow_cli/targets/zcode.py, editions.py, core.py host-routing changes, local/skills/devflow/adapters/zcode/manifest.json).
  • python3 -m unittest tests.test_installer -v — 23 tests OK
  • python3 scripts/build-classic-hosts.py --check — OK
  • bash scripts/smoke-install.sh — 30 portable + 25 CLI checks OK (an unrelated No module named pip warning at the very end is a sandbox packaging limitation, not caused by this change)
  • bash scripts/validate.sh could not run to completion in this sandbox (missing ripgrep / python3-yaml, and apt-get install is blocked by the sandbox's permission model) — a local environment limitation, not evidence against the PR.

CI note (not attributed to this PR): the 4 failing required checks on this head SHA — e2e-required, e2e-browser (dashboard in Chromium), validate (3.8), e2e (ubuntu-latest, python 3.8, node 22) — match exactly the checks broken by GitHub's ubuntu-latest runner upgrade (24.04→26.04) for Python 3.8 / older Playwright, which #886 is fixing repo-wide. This PR's diff never touches CI workflow files, so these failures are infrastructure-level, not introduced here. Suggest re-running CI (or rebasing) once #886 merges to get clean checks before merging this one.

No action needed from the author for this version; the CI red X should clear once #886 lands.

@Yanami-2K Yanami-2K left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

已读完 19 个文件的 diff。ZCode Portable 接入本身(editions.py 加 host/入口、core.py 把 zcode 安装到 .zcode/skills、Classic 拒绝提示、adapter.md/manifest.json、runtime-core.md 按 Base directory 消歧、test_zcode_installs_project_skills_and_rejects_classic 和 smoke-install 断言)没有发现正确性问题。阻塞项只有 CI:

  1. CI 失败(checksState=failure):head fc42f54 上 validate (3.8)、e2e (ubuntu-latest, python 3.8, node 22)、e2e-browser (dashboard in Chromium)、e2e-required 失败。这组失败与同期 #888/#902/#903 完全一致,大概率是 ubuntu-latest 切到 26.04 导致的 Python 3.8 / Playwright 安装问题(#885,修复在 #886),不是本 PR 引入。建议:等 #886 合入后 rebase 到最新 main 重跑 CI;如果 validate (3.8) 仍失败,请检查 local/src/devflow_cli 和 local/tests/test_installer.py 的新增代码是否用了 3.8 不支持的语法。

CI 全绿后可以重新请求审查。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: 支持 ZCode 与 Reasonix 作为执行器与本地宿主

3 participants