开发者
- 作者仓库星标 3,367
- 许可证 MIT
- 作者仓库 atopile
- 领域
- 工程开发
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 94 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @atopile · MIT
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 读取环境变量
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
source .venv/bin/activate
ato dev compile
ato dev test --llm -k solver
ato dev test --llm --view HEAD --open
ato dev test --reuse --baseline HEAD~1
ato dev flags
# Dev Module
This skill is written for LLMs working inside this repo. It focuses on the fastest, most reliable inner loop:
- rebuild Zig bindings when needed
- run the repo’s orchestrated test runner (`ato dev test --llm`, not raw test output)
- use the generated test reports (`artifacts/test-report.json`, `artifacts/test-report.html`, `artifacts/test-report.llm.json`)
- discover and use `ConfigFlag`s correctly (and inventory them repo-wide)
## Quick Start
```bash
source .venv/bin/activate
ato dev compile
ato dev test --llm -k solver
ato dev test --llm --view HEAD --open
ato dev test --reuse --baseline HEAD~1
ato dev flags
```
## Relevant Files
- CLI commands: `src/atopile/cli/dev.py`
- `ato dev compile` (triggers Zig build via `import faebryk.core.zig`)
- `ato dev test --llm` (runs `test/runner/main.py` with args; supports baseline/CI report helpers)
- Zig build-on-import glue: `src/faebryk/core/zig/__init__.py` (`ZIG_NORECOMPILE`, `ZIG_RELEASEMODE`)
- Config flags utility: `src/faebryk/libs/util.py` (`ConfigFlag`, `ConfigFlagInt`, …)
- Test runner + reports: `test/runner/main.py` (`artifacts/test-report.json`, `artifacts/test-report.html`, `artifacts/test-report.llm.json`)
- CI artifacts definition: `.github/workflows/pytest.yml` (`test-report.json`, `test-report.html`)
## Dependants (Call Sites)
- **CI/CD**: The `dev` commands are the primary interface for GitHub Actions workflows.
- **Local Development**: Developers use `ato dev compile` after modifying Zig code.
## How to Work With / Develop / Test
### Core Commands
- `ato dev compile`: compile native extensions (graph/typegraph/sexp bindings).
- `ato dev test --llm`: runs the orchestrated test runner (defaults to `-p test -p src`); supports:
- `-k` filter (`-- -k ...` also works via passthrough args)
- `--baseline` comparisons (commit hash or `HEAD~N` style)
- `--view` / `--open` to fetch and open the `test-report.html` artifact from GitHub Actions (requires `gh` CLI)
- `--ci` to apply the CI marker expression (`not not_in_ci and not regression and not slow`)
- `--direct -k <testname>` to run a single test via `test/runtest.py` (tight single-test loops)
### Test Reports (JSON as source of truth)
Local test runs write:
- `artifacts/test-report.json` (single source of truth; outcomes/durations/memory/baseline compare status + stdout/stderr/logs/tracebacks; see `tests[].output_full`)
- `artifacts/test-report.html` (human dashboard; derived from JSON; controlled by `FBRK_TEST_GENERATE_HTML=1`)
- `artifacts/test-report.llm.json` (LLM-friendly; derived from JSON; ANSI stripped logs)
CI uploads both artifacts (see `.github/workflows/pytest.yml`):
- `test-report.json`
- `test-report.html`
Notes for LLM debugging:
- Prefer `artifacts/test-report.json` or `artifacts/test-report.llm.json` over raw output; they include structured failures, logs, baseline compare, and collection errors.
- The HTML is best for quickly scanning long-running tests, worker crashes, and per-test output.
Remote/baseline behavior:
- `ato dev test --llm --baseline <commit>` uses the **CI `test-report.json` artifact** as the baseline (requires `gh` CLI).
- `ato dev test --llm --view <commit> --open` currently fetches/opens **only** the HTML artifact; for JSON, download the `test-report.json` artifact via `gh run download`.
- `ato dev test --reuse --baseline <commit>` rebuilds JSON/HTML/LLM against a baseline without rerunning tests.
- `ato dev test --keep-open` keeps the live report server running after tests finish.
Useful test-runner environment variables (see `test/runner/main.py`):
- `FBRK_TEST_REPORT_INTERVAL` (seconds; report refresh cadence)
- `FBRK_TEST_LONG_THRESHOLD` (seconds; “long test” threshold)
- `FBRK_TEST_WORKERS` (`0` = cpu count, negative scales workers)
- `FBRK_TEST_GENERATE_HTML` (`1/0`)
- `FBRK_TEST_PERIODIC_HTML` (`1/0`)
- `FBRK_TEST_OUTPUT_MAX_BYTES` (truncate preview output used by HTML; `tests[].output_full` remains complete)
- `FBRK_TEST_OUTPUT_TRUNCATE_MODE` (`head` or `tail`)
- `FBRK_TEST_BIND_HOST` (orchestrator bind host; default `0.0.0.0`)
- `FBRK_TEST_REPORT_HOST` (host used in printed report URL; default bind host)
- `FBRK_TEST_PERF_THRESHOLD_PERCENT` (default `0.30`)
- `FBRK_TEST_PERF_MIN_TIME_DIFF_S` (default `1.0`)
- `FBRK_TEST_PERF_MIN_MEMORY_DIFF_MB` (default `50.0`)
LLM quick usage:
- `artifacts/test-report.llm.json` is always generated (ANSI stripped, full tests + logs).
- `ato dev test --llm` prints a concise summary + schema + jq hints (stdout only).
- jq recipes are embedded in the report under `llm.jq_recipes`.
- Auto-LLM: `ato dev test` enables the summary automatically when running under claude-code/codex-cli/cursor.
- Force on/off via `FBRK_TEST_LLM=1` or `FBRK_TEST_LLM=0`.
### ConfigFlags (how to use + how to inventory)
`ConfigFlag` is the repo’s “toggle-by-env-var” mechanism. The environment variable name is the first argument to `ConfigFlag(...)`.
Usage:
```bash
export SOME_FLAG=1
```
Inventory all ConfigFlags in-tree (preferred over trying to maintain a manual list):
```bash
ato dev flags
```
Prefer using `ato dev flags` when you want the full picture (types/defaults/descriptions + callsite counts) in one place.
High-leverage flags you’ll use often:
- Zig build: `ZIG_NORECOMPILE`, `ZIG_RELEASEMODE`
- Solver debug: `SLOG`, `SVERBOSE_TABLE`, `SPRINT_START`, `SMAX_ITERATIONS`, `SSHOW_SS_IS`
- Logs: `COLOR_LOGS`, `LOG_TIME`, `LOG_FILEINFO`
### Development Workflow
1. **Zig Changes**: Edit files under `src/faebryk/core/zig/src/` -> Run `ato dev compile`.
2. **Profiling**: If something is slow, use `ato dev profile <command>` to generate a flamegraph or stats.
### Testing
- Main test entrypoint: `ato dev test --llm`.
- If you change CLI behavior, add/adjust tests under `test/` that exercise the command surface.
## Best Practices
- **Use ConfigFlags**: For experimental features or verbose debugging, use a `ConfigFlag` instead of commenting out code.
- **Compile often**: Zig errors won’t be caught by Python tooling.
章节与文件索引
按说明文件中的顺序排列。
相关文件
家属(呼叫站点)
核心命令
测试报告(JSON 作为事实来源)
ConfigFlags(如何使用+如何清点)
文件/命令 -> ato dev test --llm · artifacts/test-report.json · artifacts/test-report.html · artifacts/test-report.llm.json · ConfigFlag · src/atopile/cli/dev.py · ato dev compile · import faebryk.core.zig
内容校验值 -> 9b071861e237
当前原文的自动摘译,尚未人工审校。
相关文件
CLI 命令:
src/atopile/cli/dev.pyato dev compile(通过import faebryk.core.zig触发 Zig 构建)ato dev test --llm(使用参数运行test/runner/main.py;支持基线/CI 报告助手) Zig 导入粘合:src/faebryk/core/zig/__init__.py(ZIG_NORECOMPILE、ZIG_RELEASEMODE) 配置标志实用程序:src/faebryk/libs/util.py(ConfigFlag、ConfigFlagInt、……)家属(呼叫站点)
CI/CD:
dev命令是 GitHub Actions 工作流程的主要界面。本地开发:开发者修改Zig代码后使用ato dev compile。核心命令
ato dev compile:编译本机扩展(graph/typegraph/sexp 绑定)。ato dev test --llm:运行编排的测试运行器(默认为-p test -p src);支持:-k过滤器(-- -k ...也可以通过直通参数工作)--baseline比较(提交哈希或HEAD~N样式)--view/--open从 GitHub Actions 获取并打开test-report.html工件(需要gh命令行界面)测试报告(JSON 作为事实来源)
本地测试运行写入:
artifacts/test-report.json(单一事实来源;结果/持续时间/内存/基线比较状态+ stdout/stderr/日志/回溯;请参阅tests[].output_full)artifacts/test-report.html(人类仪表板;源自JSON;由FBRK_TEST_GENERATE_HTML=1控制)artifacts/test-report.llm.json(LLM友好;源自JSON;ANSI剥离日志)CI 上传两个工件(参见.github/workflows/pytest.yml):ConfigFlags(如何使用+如何清点)
ConfigFlag是存储库的“toggle-by-env-var”机制。环境变量名称是ConfigFlag(...)的第一个参数。用法:清点树中的所有 ConfigFlags(优先于尝试维护手动列表):当您想要在一个地方了解完整情况(类型/默认/描述 + 调用点计数)时,更喜欢使用ato dev flags。您将经常使用的高杠杆标志: