项目入口为
main.py
，根据命令行模式协调快递检测、代码生成与服务端运行。核心业务代码集中在
core/
（API 客户端与配置加载）、
detection/
（图像分析管线）、
intelligence/
（智能代码生成工作流）与
utils/
（日志、时间与对比工具）。
config/config.yaml
保存默认运行参数，
baseline_images/
与
reference_images/
用于视觉比对样本，
cli/
与
execution/
存放便捷脚本。
intelligent_generated/
与
generated_programs_demo/
承载 LLM 产出示例，请在合并前审阅并筛选。
logs/
、
output.log
与
test_status/
存储运行记录，可在提交前清理无关大文件，
docs/
、
HOWTORUN.md
则给出架构与部署细节。Directory map reference:
core/
-> core services,
intelligence/
-> agent pipeline,
detection/
-> vision stack,
tests/
-> pytest harness,
docs/
-> knowledge base。
推荐创建虚拟环境并安装依赖：
python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt
。常用运行方式包括
python3 main.py delivery "今天如果门口有快递提醒我"
、
python3 main.py generate "每15分钟检查一次门口"
、
python3 main.py interactive --language zh
与
python3 main.py server --port 8080
。快速检查用
./quick_test.sh
，完整测试矩阵使用
./test.sh -a
、
./test.sh -l
或
python3 tests/run_tests.py --type functional
。针对特定用例可直接执行
python3 tests/functional/test-llm.py
，或运行
python3 tests/run_tests.py --type unit --test config-loader
聚焦单项。Example local loop:
pip install -r requirements.txt && python3 -m pytest tests/functional -k delivery && python3 main.py delivery "check front door package"
。
项目以 Python 3.10+ 与 asyncio 为主，统一使用四空格缩进、type hints 与清晰 docstring。模块、文件与函数采用 snake_case，类使用 PascalCase，常量使用全大写。尽量复用
SmartHomeAPI
、
monitor_utils.py
中的封装方法，通过 f-string 输出关键状态，并保持异常向上抛出时附带上下文。建议在提交前运行
python -m compileall core detection intelligence utils
或
python -m pytest tests/unit -k config
验证语法与关键路径。Prefer explicit imports, avoid wildcard
from module import *
, and consider
dataclasses.dataclass
when modeling structured payloads。
新增或修改功能时至少补充
tests/unit/
或
tests/functional/
中的
test-*.py
文件；覆盖图像对比逻辑时请更新
baseline_images/
并记录来源。运行
python3 tests/run_tests.py --list
可确认现有案例名称，命名遵循作用域前缀（如
test-delivery-optimized.py
、
test-minicpm-final.py
）。外部依赖（LLM、HomeAssistant、MiniCPM）需在测试说明中注明跳过条件，并使用守护逻辑防止网络异常导致失败。提交前请附上
./test.sh llm
或目标子集的终端输出摘要，方便复现路径追踪。Coverage reminder: keep functional scenarios green in CI by sharing
test_status/last_run.json
snapshots when regressions arise。
仓库历史使用近似 Conventional Commits（如
fix: 修复...
、
docs: 更新...
、
refactor: 智能...
），请保持
type: 简要中文描述
格式，并在消息体补充动机与风险。提交前确保相关测试通过并描述验证方式，必要时提供配置片段或伪数据。PR 描述需概述改动动机、影响范围与配置变更，关联 Issue 或任务编号；若改动涉及识别效果或前端交互，请附示例截图、关键日志或
generated_programs_demo/
中的更新文件，便于评审快速理解。When touching external services, add a short checklist covering staging verification, credential rotation plan, and rollback command references。
敏感凭据通过环境变量注入，示例见
HOWTORUN.md
与
tests/README.md
；请勿将实际密钥写入
config/config.yaml
或提交日志。调整
config.py
默认值时说明预期部署环境，若变更第三方端点，请同步更新
docs/
、
CONFIG-GUIDE.md
中的相关指南并通知运维团队。部署前校验
requirements.txt
与 GPU 依赖版本，确保与 Jetson Orin 驱动兼容；生产环境建议设置只读
baseline_images/
，避免被误写覆盖。Security quick check: audit
.env
files, rotate
LLM_API_KEY
regularly, and confirm HomeAssistant token scopes。
为保持上下游同步，请在
RESTRUCTURE_SUMMARY.md
或团队维基记录大的目录调整与管线升级。对自动生成的脚本或配置，优先附加注释说明生成来源与复现命令，例如
python3 intelligence/code_generator/main.py --dry-run
。遇到跨仓库依赖变更时，在 PR 评论中列出影响的仓库与联动验证清单，以降低回归风险。Knowledge base links: README.md, HOWTORUN.md, CONFIG-GUIDE.md, MANUAL_TEST_GUIDE.md, MVP-README.md。