arclet-entariis a Python >=3.11 IM framework on the Satori protocol. The only published package isarclet/entari/([tool.pdm.build] includes = ["arclet"]).- Root-level scripts and fixtures are a manual test bed, not library code:
main*.py,exam*.py,sysmod_test.py,example_plugin*.py,example_plugins/,example*.yml,*.db,out_new.json. Most are untracked. Do not move, format, or commit them unless asked. - Version is dynamic, read from
arclet/entari/__init__.py:__version__. The release workflow only publishes av*tag whose version matches it.
- Lint:
ruff check ./arclet/entari. CI (.github/workflows/ruff.yml) runs ruff; config only includesarclet/**.py, with line length 120. - Format:
pdm run format=ruff check --select I --fix ./arclet/->black ./arclet/->ruff check ./arclet/.blackis not installed here;ruffis. - Tests: there is no
tests/directory.pdm run test(pytest -v -n auto -W ignore ./tests/) fails, and pytest is not a dev dependency. Verify changes with ruff plus a focused script/manual run; never claim tests passed. - PDM/WSL trap: this checkout may be opened from WSL while
.pdm-pythonpoints at a Windows venv (D:/.../.venv/Scripts/python.exe). If the venv layout does not match the host (e.g. WSL seesScripts/instead ofbin/), do not reuse it or let PDM recreate.venv—create a separate venv with a different directory name instead (python -m venv .venv-linuxthenpdm use .venv-linux/bin/python). Runningpdm run ...against the mismatched venv recreates.venv, destroying the Windows environment. - Line endings: the worktree is CRLF while the index is LF, so
git statusmarks every tracked file modified.git diff --ignore-space-at-eolis empty. Review with that flag and never commit whitespace-only churn.
- Entry point:
Entari(arclet/entari/core.py:304) wraps Satori'sApp.Entari.load(path)/Entari.from_config()readEntariConfig; default lookup is$ENTARI_CONFIG_FILE, then./.entari.json, then./entari.yml(config/file.py: EntariConfig.load). - Config uses a custom dataclass system, not pydantic:
BasicConfModel+model_field(config/models/default.py), with optional backends inconfig/models/{default,pyd,msgspec_}.pybehindConfigModelAction. Useconfig_model_validate/dump/keys/schemafromarclet.entari.configfor conversions. - Plugin system is the most intricate area:
plugin/module.py(imports, AST scanning, code swap),plugin/loader.py(load/reload/rebind),plugin/service.py(dependency graph and state),plugin/model.py(Plugin, metadata, dispatchers),plugin/swap.py(hot-reload function replacement). Public API is re-exported fromplugin/__init__.pyandarclet/entari/__init__.py; keep both in sync when adding exports. - Plugin name resolution (
config/file.py:_reload_plugins,plugin/module.py):::name->arclet.entari.builtins.name;.name-> core niches (.record_message,.scheduler,.commands); plainname->entari_plugin_name; dotted names are used verbatim;~namedisables,?namestores config without loading;$files,$prelude,$prefixare directives.basic.external_dirsare appended tosys.path. - Builtins live in
arclet/entari/builtins/. Other layers:event/(letoderea),command/(Alconna),filter/,session.py,scheduler.py,config/. - Optional dependencies are guarded imports: YAML (
ruamel-yaml), TOML (tomlkit), dotenv, watchfiles, croniter, rich, pydantic/msgspec. Keep new optional integrations import-guarded likeconfig/file.py. pyproject.tomlis the source of truth; updatepdm.lockwhen dependencies change.
- Format at 120 columns, target py311. Public re-exports use explicit
from x import y as y. - Add comments only for non-obvious invariants; hot-reload code uses Chinese docstrings—match local style there.