shinnjyuu-echo-kit 0.1.0__tar.gz

shinnjyuu_echo_kit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,55 @@
+name: Publish
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
+        with:
+          version: '0.11.27'
+          python-version: '3.12'
+      - run: uv sync --locked
+      - run: uv run --no-sync pytest -q
+      - run: uv run --no-sync echo-kit --version
+
+  publish:
+    if: startsWith(github.ref, 'refs/tags/v') && github.event_name != 'pull_request'
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
+        with:
+          version: '0.11.27'
+          python-version: '3.12'
+      - name: Check release version
+        run: |
+          uv run --no-project python - <<'PY'
+          import os, tomllib, runpy
+          from pathlib import Path
+          version = tomllib.loads(Path('pyproject.toml').read_text())['project']['version']
+          assert os.environ['GITHUB_REF_NAME'] == 'v' + version, 'Tag/package version mismatch'
+          assert runpy.run_path('src/echo_kit/__init__.py')['__version__'] == version
+          PY
+      - run: uv build --no-sources
+      - name: Check package metadata
+        run: uvx --from twine twine check dist/*
+      - run: uv publish --trusted-publishing always

shinnjyuu_echo_kit-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+.echo-kit/
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+*.egg-info/

shinnjyuu_echo_kit-0.1.0/AGENTS.md

@@ -0,0 +1,7 @@
+# Echo Kit
+
+Single install, independent capabilities. Preserve project-owned adapters and external instances. Core must not import Magic Cube business modules or embed environment addresses or credentials.
+
+Run `uv run pytest` for targeted core checks. Real Docker and sample integration runs are separate evidence. Document platform and authentication limitations honestly. Do not publish, push, deploy or operate shared business environments without explicit task authorization.
+
+Skills are bundled in `src/echo_kit/skills`; public protocol lives in `docs/protocol.md` and is included with exported skills. Keep these copies synchronized.

shinnjyuu_echo_kit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 黄悦峰
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shinnjyuu_echo_kit-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.5
+Name: shinnjyuu-echo-kit
+Version: 0.1.0
+Summary: Reusable experiments and verification workflows for AI coding assistants
+Project-URL: Repository, https://github.com/shinnjyuu/echo-kit
+Project-URL: Issues, https://github.com/shinnjyuu/echo-kit/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: filelock<4,>=3.16
+Requires-Dist: keyring<26,>=25
+Requires-Dist: playwright==1.63.0
+Requires-Dist: psutil<8,>=6
+Description-Content-Type: text/markdown
+
+# Echo Kit
+
+让 AI 的实验、调试与验收成为团队可复用的工程能力。
+
+发布维护见 [PyPI 发布说明](docs/publishing.md)。首次正式发布完成后可使用 `uvx --from shinnjyuu-echo-kit@latest echo-kit --version` 获取当前版本，再通过 `uvx --from shinnjyuu-echo-kit@具体版本 echo-kit …` 固定一轮任务的执行版本。
+
+Python 3.11+。一个包提供 workspace、doctor、services、auth、browser、lab、verify、runs 和 Skill 导出。各能力按需使用，Lab 不要求 Docker 或服务启动。
+
+```powershell
+uv tool install .
+echo-kit --help
+echo-kit --workspace D:/my-project workspace init
+echo-kit skills export D:/my-project/.agents/skills
+```
+
+也可以 `uv tool install git+<仓库地址>` 或安装 `dist` 中的 wheel。不需要发布公共包。Skills 的安装目录遵循所用 AI 助手规则；导出不会改助手配置。
+
+## 独立演示
+
+```powershell
+uv sync --group dev
+uv run python examples/create_demo.py --output D:/echo-demo
+uv run echo-kit --workspace D:/echo-demo/qa --json workspace check
+uv run echo-kit --workspace D:/echo-demo/qa lab compare arithmetic --variants baseline double --repeat 3
+uv run echo-kit --workspace D:/echo-demo/qa verify run api
+uv run echo-kit --workspace D:/echo-demo/qa verify run page
+uv run echo-kit --workspace D:/echo-demo/qa services status
+uv run echo-kit --workspace D:/echo-demo/qa runs list
+```
+
+示例生成互不嵌套的 frontend、backend、qa 三个目录，均不依赖魔方。`page` 需要正在运行的 Docker，首次启动容器需下载固定 Playwright 镜像及 npm 包。
+
+## 配置与执行
+
+共享 `echo-kit.toml` 与 `echo/` 适配、用例入 Git；`.echo-kit/local.toml` 深度覆盖共享配置，environment 覆盖随后生效。所有 `.echo-kit/` 状态不提交。绝对路径放本机覆盖，命令数组中的 `{python}` 指 Kit 解释器；业务 Python 应改为项目实际解释器。
+
+命令必须使用数组，不隐式经过 Shell。`env_refs` 把指定环境变量传给适配器，敏感信息禁止写在 `command` 或 `env` 字面量。Kit 不记录全环境变量；项目脚本不得把秘密打印到 stdout 或写入证据。
+
+全局选项置于模块前：`echo-kit --workspace PATH --environment NAME --json lab run CASE`。退出码 0 为已执行范围成功，1 为检查失败，2 为受阻或未验证，130 为中断。`services status` 的成功表示查询成功，请检查各实例的 ready 字段。
+
+适配协议、认证和配置详见 [协议文档](docs/protocol.md)。业务依赖由项目管理，CLI 不导入业务模块。简单 `protocol="command"` 只核对退出码，不能证明语义正确。
+
+## 运行与安全边界
+
+托管服务持续运行；外部服务显式 `mode="external"`，不会停止。进程身份不匹配时不发送终止信号。运行存在 active.json 时阻止新用例与停服务，使用 `runs cleanup ID` 调用项目清理并核验终态，不能删除标记伪造收尾。
+
+认证协议通过内存管道传秘密。只向受支持的系统凭据后端持久化；不可用时只保留当前调用内状态。独立 auth login 在这种情况下不会为下一条命令保留状态；verify 同次调用仍可使用。
+
+报告只自动链接显式声明的产物。请求文件、适配输出、截图及 trace 可能包含业务数据，分享前审查。Kit 无法阻止恶意或错误适配器自行泄露数据；适配器是项目受信代码。
+
+## 验证与限制
+
+`uv run pytest` 运行核心测试；真实演示与 Docker 验收单独运行。具体证据见 `docs/validation.md`。macOS 未验证；不把单元模拟当成真实业务或平台验收。
+
+第一版不提供 IDE 插件、Agent 引擎、通用验证码绕过、后台自动恢复。回放为已有记录与 Playwright trace 查看，不承诺重跑结果一致。
+
+## 来源
+
+服务归属、就绪等待与持续复用的设计，及 Lab 的案例／候选／独立重复执行概念，源自既有 Magic Cube Workbench 和 Agent Lab。为跨项目子进程协议重新实现，不引入原业务依赖、服务名、模型配置或私有凭据。

shinnjyuu_echo_kit-0.1.0/README.md

@@ -0,0 +1,59 @@
+# Echo Kit
+
+让 AI 的实验、调试与验收成为团队可复用的工程能力。
+
+发布维护见 [PyPI 发布说明](docs/publishing.md)。首次正式发布完成后可使用 `uvx --from shinnjyuu-echo-kit@latest echo-kit --version` 获取当前版本，再通过 `uvx --from shinnjyuu-echo-kit@具体版本 echo-kit …` 固定一轮任务的执行版本。
+
+Python 3.11+。一个包提供 workspace、doctor、services、auth、browser、lab、verify、runs 和 Skill 导出。各能力按需使用，Lab 不要求 Docker 或服务启动。
+
+```powershell
+uv tool install .
+echo-kit --help
+echo-kit --workspace D:/my-project workspace init
+echo-kit skills export D:/my-project/.agents/skills
+```
+
+也可以 `uv tool install git+<仓库地址>` 或安装 `dist` 中的 wheel。不需要发布公共包。Skills 的安装目录遵循所用 AI 助手规则；导出不会改助手配置。
+
+## 独立演示
+
+```powershell
+uv sync --group dev
+uv run python examples/create_demo.py --output D:/echo-demo
+uv run echo-kit --workspace D:/echo-demo/qa --json workspace check
+uv run echo-kit --workspace D:/echo-demo/qa lab compare arithmetic --variants baseline double --repeat 3
+uv run echo-kit --workspace D:/echo-demo/qa verify run api
+uv run echo-kit --workspace D:/echo-demo/qa verify run page
+uv run echo-kit --workspace D:/echo-demo/qa services status
+uv run echo-kit --workspace D:/echo-demo/qa runs list
+```
+
+示例生成互不嵌套的 frontend、backend、qa 三个目录，均不依赖魔方。`page` 需要正在运行的 Docker，首次启动容器需下载固定 Playwright 镜像及 npm 包。
+
+## 配置与执行
+
+共享 `echo-kit.toml` 与 `echo/` 适配、用例入 Git；`.echo-kit/local.toml` 深度覆盖共享配置，environment 覆盖随后生效。所有 `.echo-kit/` 状态不提交。绝对路径放本机覆盖，命令数组中的 `{python}` 指 Kit 解释器；业务 Python 应改为项目实际解释器。
+
+命令必须使用数组，不隐式经过 Shell。`env_refs` 把指定环境变量传给适配器，敏感信息禁止写在 `command` 或 `env` 字面量。Kit 不记录全环境变量；项目脚本不得把秘密打印到 stdout 或写入证据。
+
+全局选项置于模块前：`echo-kit --workspace PATH --environment NAME --json lab run CASE`。退出码 0 为已执行范围成功，1 为检查失败，2 为受阻或未验证，130 为中断。`services status` 的成功表示查询成功，请检查各实例的 ready 字段。
+
+适配协议、认证和配置详见 [协议文档](docs/protocol.md)。业务依赖由项目管理，CLI 不导入业务模块。简单 `protocol="command"` 只核对退出码，不能证明语义正确。
+
+## 运行与安全边界
+
+托管服务持续运行；外部服务显式 `mode="external"`，不会停止。进程身份不匹配时不发送终止信号。运行存在 active.json 时阻止新用例与停服务，使用 `runs cleanup ID` 调用项目清理并核验终态，不能删除标记伪造收尾。
+
+认证协议通过内存管道传秘密。只向受支持的系统凭据后端持久化；不可用时只保留当前调用内状态。独立 auth login 在这种情况下不会为下一条命令保留状态；verify 同次调用仍可使用。
+
+报告只自动链接显式声明的产物。请求文件、适配输出、截图及 trace 可能包含业务数据，分享前审查。Kit 无法阻止恶意或错误适配器自行泄露数据；适配器是项目受信代码。
+
+## 验证与限制
+
+`uv run pytest` 运行核心测试；真实演示与 Docker 验收单独运行。具体证据见 `docs/validation.md`。macOS 未验证；不把单元模拟当成真实业务或平台验收。
+
+第一版不提供 IDE 插件、Agent 引擎、通用验证码绕过、后台自动恢复。回放为已有记录与 Playwright trace 查看，不承诺重跑结果一致。
+
+## 来源
+
+服务归属、就绪等待与持续复用的设计，及 Lab 的案例／候选／独立重复执行概念，源自既有 Magic Cube Workbench 和 Agent Lab。为跨项目子进程协议重新实现，不引入原业务依赖、服务名、模型配置或私有凭据。

shinnjyuu_echo_kit-0.1.0/docs/protocol.md

@@ -0,0 +1,43 @@
+# Echo Kit v1 adapter protocol
+
+## Configuration
+
+`schema_version=1`. Projects are `[projects.NAME] path="relative-or-absolute"`. `.echo-kit/local.toml` overrides shared values; `[environments.NAME]` overlays for explicit `--environment NAME`. Arrays replace, dictionaries merge. `output` overrides the default `.echo-kit/runs`.
+
+Services define `command=[...]`, optional `project`, `depends`, `port`, `timeout` and a `ready` table containing `url` plus expected `status`, or `host/port`, or `command/timeout`. `mode="external"` is check-only. `prepare` is an optional explicit build command table. No implicit framework detection at runtime. Startup versions describe owned launch snapshots, not unowned remote software.
+
+Commands execute without shell, with project cwd. `{python}` is the Kit interpreter for helpers; specify a project's interpreter for its business dependencies. `${ENV_NAME}` expansion is for non-secret command arguments. `env_refs` maps child variable names to parent variables. Secret arguments are forbidden because OS command lines and process state are observable.
+
+Cases use `[cases.NAME]`, `command`, `project`, `inputs`, `variants.NAME` input overrides, `timeout`, `required_checks`, and `mode` (unit/probe/integration or project-defined scope). `protocol="command"` records only exit-code success. Verify additionally accepts `services=[...]`, `auth="NAME"`, `browser=true`. Lab deliberately does not prepare these capabilities.
+
+## Experiment and verification subprocess
+
+Environment variables: ECHO_REQUEST (JSON input path), ECHO_RESULT (JSON output path), ECHO_RUN_DIR (artifact directory), ECHO_ACTIVE (parent run task state).
+
+Request: `protocol`, `run_id`, `environment`, `inputs`, `variant`, `iteration`, optional `browser.endpoint`, `active_file`. Credentials never belong in inputs. JSON stdin contains ephemeral private `auth` state. Read stdin once; never echo it.
+
+Result example:
+
+```json
+{"status":"passed","checks":[{"name":"download","status":"passed","detail":"bytes matched"}],"metrics":{"elapsed_ms":120},"artifacts":["download.txt"]}
+```
+
+Result statuses: passed, failed, blocked, unverified, interrupted. Checks additionally allow not_applicable; a required not_applicable check does not pass. Checks must have unique names. Artifacts must exist beneath ECHO_RUN_DIR. stdout is saved as a log: adapters are trusted project code and must redact private material.
+
+If the adapter starts remote/asynchronous work, set `creates_tasks=true`, immediately save IDs to ECHO_ACTIVE, retaining run_id. Successful result must include `terminal_confirmed=true`. Optional `[cases.NAME.cleanup]` defines a separate command that receives `{run_id, active}`; it must target only those IDs and return `status="passed", terminal_confirmed=true`. Cleanup runs after the case if configured, including timeout. Missing terminal evidence retains active.json. Later use `runs cleanup ID`; it preserves the original failure verdict.
+
+## Authentication subprocess
+
+Auth differs intentionally: no secret request/result files. `[auth.NAME]` has command, project, account, target, timeout and optional credentials mapping fields to environment variable names.
+
+stdin JSON: `{action, account, target, state, credentials}`. Actions: login, check, refresh, logout. stdout JSON: `{valid, account, target, state}`. No diagnostic text on stdout; stderr is private and not persisted by Kit. Returned identity and target must exactly match configuration. State is opaque JSON, passed to case stdin. Browser adapters can translate it to normal application storage or Playwright storage_state.
+
+Kit checks stored state, tries refresh, then login. Only system credential backends are used for persistence. Without one, the same verify invocation can use the state; another CLI invocation logs in again. This does not bypass user, organization or password checks. Demonstration credentials are fixtures only.
+
+## Browser and records
+
+Managed Docker browser is pinned to Playwright 1.63.0 and loopback host port 19323 (override `browser.port`). `browser.image` can select a registry mirror with the same version tag. External `browser.endpoint` is connect-only; Playwright handshake verifies compatible protocol. Browser project adapters can import `echo_kit.browser.session` when Echo is installed in their interpreter; otherwise use their own compatible Playwright client. Context traces are saved and closed in finally.
+
+Every run writes run.json, report.html, adapter request/result/stdout and declared artifacts. Active records block new business runs in that workspace. HTML is an escaped static view; trace.zip opens in Playwright Trace Viewer. Sharing raw traces and files requires business-data review.
+
+CLI code 0: executed scope passed; 1: check failure; 2: blocked/unverified/config/dependency error; 130: interrupted. Cancellation/cleanup never automatically resubmits the case. Initialization never overwrites existing configuration. macOS remains unverified until real validation.

shinnjyuu_echo_kit-0.1.0/docs/publishing.md

@@ -0,0 +1,25 @@
+# PyPI 发布
+
+仓库：`shinnjyuu/echo-kit`。包名：`shinnjyuu-echo-kit`。
+
+首次在 https://pypi.org/manage/account/publishing/ 添加 pending publisher：
+
+| 字段 | 值 |
+| --- | --- |
+| PyPI Project Name | shinnjyuu-echo-kit |
+| Owner | shinnjyuu |
+| Repository name | echo-kit |
+| Workflow name | publish.yml |
+| Environment name | pypi |
+
+启用账号双因素认证。首次上传成功才实际占用包名。无需保存长期 API Token。
+
+普通 main 推送仅运行 Windows/Linux 核心测试。推送 `v*` 标签时，通过测试后构建并使用 OIDC 发布；也可对已有标签手动重跑工作流。
+
+发布前同步修改 pyproject.toml 和 src/echo_kit/__init__.py 的版本，运行 `uv lock`、`uv run pytest`、`uv build --no-sources`。
+提交并推送后，创建与包版本一致的标签，例如 `v0.1.0`，并推送该标签。GitHub Release 可随后附加版本说明，不是此工作流的触发条件。
+
+发布后从仓库外验证 `uvx --from shinnjyuu-echo-kit@latest echo-kit --version` 和 `uvx --from shinnjyuu-echo-kit@0.1.0 echo-kit --help`。
+一轮验收开始时获取最新版，随后固定本轮版本。包更新不覆盖项目适配脚本、配置或已导出的 Skill 副本。
+
+已发布文件不能覆盖；修改内容需提升版本。未完成 PyPI 授权时不要推送发布标签。

shinnjyuu_echo_kit-0.1.0/docs/validation-results.json

@@ -0,0 +1,33 @@
+{
+  "date": "2026-09-30",
+  "package": "echo-kit",
+  "version": "0.1.0",
+  "windows": {"python": "3.12.6", "passed": 28, "skipped": 1, "skip_reason": "POSIX SIGINT transport test"},
+  "linux_container": {"distribution": "Ubuntu Noble", "python": "3.12.3", "passed": 29, "skipped": 0},
+  "macos": "unverified",
+  "wheel_clean_install": "passed",
+  "skill_export": "passed",
+  "real_examples": {
+    "lab_variants": "passed, baseline and double each repeated three times",
+    "api_login_download": "passed",
+    "windows_auth_reuse": "passed with system credential backend",
+    "linux_auth_ephemeral": "passed without persistence",
+    "docker_page_download": "passed",
+    "external_services": "passed using prestarted local demo instances",
+    "frontend_only": "passed after correctly refusing occupied port",
+    "clean_install_lab_run": "20260930-144131-187ca8c753",
+    "clean_install_page_run": "20260930-144132-152678fbf8"
+  },
+  "evidence_roots": [
+    "D:/Codex/echo-kit-v1-demo/qa/.echo-kit/runs",
+    "D:/Codex/echo-kit-installed-demo/qa/.echo-kit/runs",
+    "D:/Codex/echo-kit-failures/.echo-kit/runs"
+  ],
+  "limitations": [
+    "No production or Magic Cube integration claimed",
+    "Linux desktop keyring not exercised",
+    "No macOS runtime validation",
+    "Windows real console interrupt transport not exercised",
+    "External service demonstration is local network topology, not Internet deployment"
+  ]
+}

shinnjyuu_echo_kit-0.1.0/docs/validation.md

@@ -0,0 +1,51 @@
+# 第一版验证记录
+
+日期：2026-09-30。范围是 Echo Kit 自身与独立示例，没有访问或修改魔方业务环境。
+
+## 环境
+
+- Windows 本机，Python 3.12.6，Docker Desktop Linux engine。
+- Linux：Ubuntu Noble Playwright 容器，Python 3.12.3；这是 Linux 容器证据，不代表所有 Linux 桌面发行版。
+- Playwright Python 与浏览器服务器均固定 1.63.0。验证使用已有同版本镜像镜像源 `mcr.m.daocloud.io/playwright:v1.63.0-noble`；产品默认官方仓库。
+- macOS 未验证。Linux 容器没有系统凭据会话，验证了不明文落盘、同次调用使用登录态的退化路径；Linux 桌面安全存储未实测。
+
+## 真实用例
+
+独立前端、后端、QA 目录位于 `D:/Codex/echo-kit-v1-demo`。无 Git 历史的示例在报告中 commit 为 null，没有冒充真实版本。
+
+| 场景 | 结果与记录 |
+|---|---|
+| Lab baseline / double 各三次 | 6 次通过，指标分别 5 / 10；不需要 Docker 或业务服务 |
+| 正常登录与 API 文件下载 | 通过，`20260930-143555-617ee969fc` |
+| 第二次复用服务与登录态 | 通过，`20260930-143611-ceec4a7307`，reused=true，Windows 系统凭据库持久化 |
+| 托管前后端与 Docker 页面下载 | 通过，`20260930-143800-4c558f5e7a`，含截图、文件和 trace |
+| 全部业务服务外部连接 | 通过，`20260930-143831-892802b3e0`，没有接管进程 |
+| 前端占用冲突 | 按预期受阻，`20260930-143833-c2a8fa8893`；失败记录保留 |
+| 仅托管前端，连接已有 API | 停止本工具原前端后复验通过，`20260930-143843-feb6eb94f9` |
+| Linux Lab 与真实 API 验收 | 通过；临时登录态 current invocation only；停止服务成功 |
+| 干净环境 wheel 安装 | 通过，`D:/Codex/echo-kit-clean-install`，独立实验与三个 Skill 导出成功 |
+
+上述“远端连接”使用本机预先运行的示例实例模拟已部署目标，证明连接和归属行为；没有声称验证跨公网、反向代理或真实测试环境。
+
+## 测试覆盖
+
+pytest 覆盖初始化不覆盖、多目录覆盖、缺失环境变量、独立重复、必需证据缺失、HTML 转义、非法产物、超时、清理确认与失败、进程复用及身份不匹配、端口冲突、外部实例不停止、互斥、依赖环、部分启动失败、重启与状态重读、认证刷新与复用、认证身份拒绝、不可用安全存储、浏览器外部连接与所有权及版本校验。
+
+Linux 额外通过真实 SIGINT 中断测试；Windows 跳过 POSIX SIGINT 测试，使用受控 runner 中断检查，不将两者等同。
+
+受控失败脚本 `examples/validate_failures.py` 产生真实失败／超时／缺失证据／清理失败报告。它没有真实远端任务，后续通过清理协议确认本地 fixture 范围，不伪称验证了任意业务停止接口。
+
+## 明确限制
+
+- 示例登录使用公开测试凭据，证明正常 HTTP 认证适配；不证明企业 SSO、组织初始化、验证码或所有业务权限。
+- 当前元数据在适配器输出异常时保存失败，但未设计断电后自动恢复业务，也不会自动重发。
+- 系统凭据不可用时，独立 auth login 不能给下一条命令提供跨进程临时状态；verify 内可用。
+- 外部服务版本由项目检查提供；本机源码快照不能证明远端部署版本。
+- 适配器及页面 trace 可能含业务数据，分享前必须审查；HTML 报告不自动展示认证态与完整环境变量。
+- 原型没有图形管理后台、完整确定性回放或公共 PyPI 发布。
+
+## 复现
+
+运行 README 中的示例流程。`uv run pytest -q` 为自动化测试入口；`uv build` 后在独立虚拟环境安装 wheel 验证分发。
+
+最终测试数量和构建结果以同目录 `validation-results.json` 记录为准。

shinnjyuu_echo_kit-0.1.0/examples/create_demo.py

@@ -0,0 +1,96 @@
+"""Create three independent directories. Does not launch anything or overwrite."""
+import argparse
+import json
+import shutil
+import sys
+from pathlib import Path
+
+
+def create(root, api_port=18761, web_port=18762):
+    root = Path(root).resolve()
+    if root.exists() and any(root.iterdir()):
+        raise SystemExit('Output must be absent or empty')
+    for folder in ('backend', 'frontend', 'qa/echo'):
+        (root / folder).mkdir(parents=True, exist_ok=True)
+    source = Path(__file__).parent / 'templates'
+    for filename, dest in [('server.py', 'backend/server.py'), ('frontend.py', 'frontend/server.py'),
+                           ('adapter.py', 'qa/echo/adapter.py'), ('auth.py', 'qa/echo/auth.py')]:
+        shutil.copyfile(source / filename, root / dest)
+    python = json.dumps(sys.executable)
+    config = f'''schema_version = 1
+name = "echo-demo"
+default_environment = "local"
+[projects.api]
+path = "../backend"
+[projects.web]
+path = "../frontend"
+[projects.qa]
+path = "."
+[services.api]
+project = "api"
+command = [{python}, "server.py", "{api_port}"]
+port = {api_port}
+timeout = 10
+[services.api.ready]
+url = "http://127.0.0.1:{api_port}/health"
+[services.web]
+project = "web"
+command = [{python}, "server.py", "{web_port}", "{api_port}"]
+port = {web_port}
+timeout = 10
+[services.web.ready]
+url = "http://127.0.0.1:{web_port}/health"
+[auth.demo]
+project = "qa"
+command = [{python}, "echo/auth.py"]
+account = "demo"
+target = "http://127.0.0.1:{api_port}"
+[cases.arithmetic]
+project = "qa"
+command = [{python}, "echo/adapter.py", "math"]
+required_checks = ["sum"]
+mode = "unit"
+[cases.arithmetic.inputs]
+numbers = [2, 3]
+factor = 1
+[cases.arithmetic.variants.double]
+factor = 2
+[cases.api]
+project = "qa"
+command = [{python}, "echo/adapter.py", "api"]
+services = ["api"]
+auth = "demo"
+required_checks = ["download"]
+mode = "integration"
+[cases.api.inputs]
+url = "http://127.0.0.1:{api_port}"
+[cases.page]
+project = "qa"
+command = [{python}, "echo/adapter.py", "page"]
+services = ["api", "web"]
+auth = "demo"
+browser = true
+required_checks = ["download", "page"]
+mode = "integration"
+timeout = 90
+[cases.page.inputs]
+url = "http://host.docker.internal:{web_port}"
+[environments.external.services.api]
+mode = "external"
+[environments.external.services.web]
+mode = "external"
+[environments.frontend-only.services.api]
+mode = "external"
+'''
+    (root / 'qa/echo-kit.toml').write_text(config, encoding='utf-8')
+    (root / 'qa/.gitignore').write_text('.echo-kit/\n', encoding='utf-8')
+    return root / 'qa'
+
+
+if __name__ == '__main__':
+    p = argparse.ArgumentParser()
+    p.add_argument('--output', required=True)
+    p.add_argument('--api-port', type=int, default=18761)
+    p.add_argument('--web-port', type=int, default=18762)
+    a = p.parse_args()
+    print(create(a.output, a.api_port, a.web_port))

shinnjyuu_echo_kit-0.1.0/examples/templates/adapter.py

@@ -0,0 +1,37 @@
+import json
+import os
+import sys
+import urllib.request
+from pathlib import Path
+
+q = json.loads(Path(os.environ['ECHO_REQUEST']).read_text())
+secret = json.load(sys.stdin)
+out = Path(os.environ['ECHO_RUN_DIR'])
+checks, artifacts, metrics = [], [], {}
+mode = sys.argv[1]
+if mode == 'math':
+    answer = sum(q['inputs']['numbers']) * q['inputs'].get('factor', 1)
+    metrics['answer'] = answer
+    checks.append({'name': 'sum', 'status': 'passed' if answer == 5 * q['inputs'].get('factor', 1) else 'failed'})
+elif mode == 'api':
+    req = urllib.request.Request(q['inputs']['url'] + '/download', headers={'Authorization': 'Bearer ' + secret['auth']['token']})
+    with urllib.request.urlopen(req, timeout=5) as r:
+        data = r.read()
+    (out / 'echo.txt').write_bytes(data)
+    checks.append({'name': 'download', 'status': 'passed' if data == b'Echo demo verified\n' else 'failed'})
+    artifacts.append('echo.txt')
+else:
+    from echo_kit.browser import session
+    # The demo's normal auth endpoint yielded the token. Initialize the demo page's normal token slot.
+    with session(q['browser']['endpoint'], out) as context:
+        context.add_init_script('localStorage.token=' + json.dumps(secret['auth']['token']))
+        page = context.new_page()
+        page.goto(q['inputs']['url'])
+        checks.append({'name': 'page', 'status': 'passed' if page.title() == 'Echo demo' else 'failed'})
+        with page.expect_download() as download:
+            page.locator('#download').click()
+        download.value.save_as(out / 'echo.txt')
+        page.screenshot(path=str(out / 'page.png'))
+        checks.append({'name': 'download', 'status': 'passed' if (out / 'echo.txt').read_bytes() == b'Echo demo verified\n' else 'failed'})
+    artifacts.extend(['echo.txt', 'page.png', 'trace.zip'])
+Path(os.environ['ECHO_RESULT']).write_text(json.dumps({'status': 'passed', 'checks': checks, 'artifacts': artifacts, 'metrics': metrics}), encoding='utf-8')

shinnjyuu_echo_kit-0.1.0/examples/templates/auth.py

@@ -0,0 +1,18 @@
+"""Demo credentials are public fixture values, not a production login shortcut."""
+import json
+import sys
+import urllib.request
+import urllib.error
+
+q = json.load(sys.stdin)
+token = (q.get('state') or {}).get('token', '')
+action = q['action']
+url = q['target'] + ('/login' if action in ('login', 'refresh') else '/logout' if action == 'logout' else '/me')
+data = json.dumps({'account': q['account'], 'password': q.get('credentials', {}).get('password', 'demo-only')}).encode() if action in ('login', 'refresh', 'logout') else None
+req = urllib.request.Request(url, data=data, headers={'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json'})
+try:
+    with urllib.request.urlopen(req, timeout=5) as r:
+        value = json.load(r)
+    print(json.dumps({'valid': True, 'account': q['account'], 'target': q['target'], 'state': {'token': value.get('token', token)}}))
+except urllib.error.HTTPError:
+    print(json.dumps({'valid': False, 'account': q['account'], 'target': q['target']}))

shinnjyuu_echo_kit-0.1.0/examples/templates/frontend.py

@@ -0,0 +1,33 @@
+import sys
+import urllib.request
+import urllib.error
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+HTML = b'''<!doctype html><html><title>Echo demo</title><body><h1>Echo demo</h1>
+<button id="download">Download verified file</button><p id="status">Ready</p>
+<script>document.querySelector('button').onclick=async()=>{const r=await fetch('/api/download',{headers:{Authorization:'Bearer '+localStorage.token}});if(!r.ok){document.querySelector('#status').textContent='Failed';return;}const b=await r.blob();const a=document.createElement('a');a.href=URL.createObjectURL(b);a.download='echo.txt';a.click();document.querySelector('#status').textContent='Downloaded';};</script></body></html>'''
+
+
+class Handler(BaseHTTPRequestHandler):
+    def log_message(self, *_):
+        pass
+
+    def do_GET(self):
+        if self.path.startswith('/api/'):
+            req = urllib.request.Request('http://127.0.0.1:' + sys.argv[2] + self.path[4:], headers={'Authorization': self.headers.get('Authorization', '')})
+            try:
+                with urllib.request.urlopen(req) as r:
+                    status, data = r.status, r.read()
+            except urllib.error.HTTPError as e:
+                status, data = e.code, e.read()
+            self.send_response(status)
+            self.end_headers()
+            self.wfile.write(data)
+        else:
+            self.send_response(200)
+            self.send_header('Content-Type', 'text/html')
+            self.end_headers()
+            self.wfile.write(HTML)
+
+
+ThreadingHTTPServer(('0.0.0.0', int(sys.argv[1])), Handler).serve_forever()

shinnjyuu_echo_kit-0.1.0/examples/templates/server.py

@@ -0,0 +1,42 @@
+import json
+import secrets
+import sys
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+tokens = set()
+
+
+class Handler(BaseHTTPRequestHandler):
+    def log_message(self, *_):
+        pass
+
+    def reply(self, status, data, content='application/json'):
+        self.send_response(status)
+        self.send_header('Content-Type', content)
+        self.end_headers()
+        self.wfile.write(data if isinstance(data, bytes) else json.dumps(data).encode())
+
+    def do_GET(self):
+        if self.path == '/health':
+            return self.reply(200, {'ready': True})
+        if self.headers.get('Authorization', '').removeprefix('Bearer ') not in tokens:
+            return self.reply(401, {'error': 'unauthenticated'})
+        if self.path == '/me':
+            return self.reply(200, {'account': 'demo'})
+        if self.path == '/download':
+            return self.reply(200, b'Echo demo verified\n', 'text/plain')
+        return self.reply(404, {})
+
+    def do_POST(self):
+        body = json.loads(self.rfile.read(int(self.headers.get('Content-Length', '0'))) or '{}')
+        if self.path == '/login' and body == {'account': 'demo', 'password': 'demo-only'}:
+            token = secrets.token_hex(24)
+            tokens.add(token)
+            return self.reply(200, {'token': token})
+        if self.path == '/logout':
+            tokens.discard(self.headers.get('Authorization', '').removeprefix('Bearer '))
+            return self.reply(200, {})
+        return self.reply(401, {})
+
+
+ThreadingHTTPServer(('0.0.0.0', int(sys.argv[1])), Handler).serve_forever()