maop-orchestrator 5.3.0__tar.gz

maop_orchestrator-5.3.0/.gitignore

@@ -0,0 +1,194 @@
+# -- Python --
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+*.egg
+
+# -- Virtual environments --
+.venv/
+venv/
+env/
+
+# -- IDE / Editor --
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# -- Testing --
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+# Coverage temp files
+_cov*.txt
+.tox/
+
+# t16 (2026-07-21): ad-hoc test runners with hardcoded absolute paths — should
+# never be committed. Use `python -m pytest` from py/ instead.
+test_output.txt
+batch_run_tests.py
+
+# -- Environment variables --
+.env
+.env.local
+.env.*.local
+# Low-2 fix: .env.sandbox 含运行时沙箱转发策略，可能含敏感配置，不应入库
+.env.sandbox
+
+# -- Runtime data (SQLite databases + generated state) --
+data/*.db
+data/*.db-shm
+data/*.db-wal
+data/*.db2
+data/.admin-password
+data/.enc_key
+data/jwt_secret
+data/backups/
+data/sandboxes/
+data/wiki.json
+data/memory.json
+data/evolve-suggestions.json
+data/tools.json
+# P2 fix: runtime-generated state/cache files (not seed configs)
+data/pev-loop.jsonl
+data/dynamic-routing-cache.json
+data/graph-edges.json
+data/graph-nodes.json
+data/agent-versions.json
+data/budget_ledger.json
+data/vectors.json
+# runtime DAG execution checkpoints (per-run state, not seed configs)
+data/dag-checkpoints/
+# MAOS clock_guard 的防回拨水位线（enterprise/clock_guard.py: WATERMARK_FILENAME），
+# 本机跑测试时按 MAOP 仓库根写入；纯运行时状态，绝不能入库。
+data/clock_watermark.json
+
+# -- Logs --
+logs/
+
+# -- Dashboard build output --
+dashboard/dist/
+dashboard/dist-enterprise/
+dashboard-enterprise/dist/
+
+# -- Temp / Cache --
+temp/
+cache/
+output/
+
+# -- Snapshots (test artifacts) --
+tests/snapshots/
+*.snap
+
+# -- OS files --
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# -- Docker --
+docker-compose.override.yml
+
+# -- Node (if any frontend tooling) --
+node_modules/
+
+# -- Temp test results / scripts --
+py/data/
+py/test_full.txt
+py/test_results.txt
+py/test_results_async.txt
+pytest_results.txt
+test-html.py
+scripts/rename_dist.py
+scripts/rename_pev_to_maop.py
+security-audit.md
+# Ad-hoc inspection/debug scripts (root-level, underscore-prefixed)
+/_*.py
+py/_*.py
+# Ad-hoc cleanup/audit reports (large generated artifacts, not source)
+py/_shim_cleanup_report.txt
+config/agents.yaml.bak
+config/agents.yaml.bak2
+
+# -- Audit artifacts / temp scripts (not source) --
+dashboard-enterprise/api_audit.json
+dashboard-enterprise/orphan_audit.json
+dashboard-enterprise/audit_api.py
+dashboard-enterprise/audit_orphans.py
+dashboard-enterprise/coverage/
+dashboard-enterprise/frontend_dev.log
+test_full.log
+test_*.log
+# -- Python runtime/test logs accidentally committed under py/ (see audit D7) --
+py/*.log
+py/**/*.log
+
+# -- Credentials / runtime secrets --
+data/.admin_initial_password
+data/.write_test
+data/backend_run.log
+# S-P1-3 fix: Docker secrets directory (must NEVER be committed)
+secrets/
+
+# Alembic cache
+py/maop/migrations/alembic/__pycache__/
+
+# -- Security: Keys and Certificates (P0 fix: prevent private key leakage) --
+# P0 fix: development Ed25519 private key leaked to history - cached removed above
+*.pem
+*.key
+*.p12
+*.pfx
+scripts/dev_*
+scripts/*_private_*
+data/*_secret*
+*.private
+# -- Scrubbed backup dirs (must NEVER be committed) --
+data_bak_*/
+# -- Runtime error logs --
+*.err
+# -- Test baseline/result artifacts --
+py/test_baseline_*.txt
+py/test_final_*.txt
+py/test_precommit_*.txt
+py/tests/_baseline_cov*.txt
+py/tests/_final_cov*.txt
+py/.maop-snapshots/
+.maop-snapshots/
+dashboard-enterprise/test-results/
+# 前端测试运行产物（此前被误提交，131KB 的 vitest 结果 JSON）
+dashboard-enterprise/vitest_result.json
+# -- Runtime degradation log --
+data/degradation.log
+# 带时间戳的轮转副本（历史累积产物；原先只忽略固定名，导致
+# data/degradation_<ts>[_<ts>...].log 被误提交）
+data/degradation_*.log
+data/jwt_revoked.json
+# -- Agent tool internal --
+.codeartsdoer/
+deliverables/
+
+# Packaged-module runtime DB (orphan artifact, not a seed; VectorStore uses <root>/data/)
+py/maop/data/*.db
+py/maop/data/*.db-shm
+py/maop/data/*.db-wal
+
+# -- IDE: InsCode --
+.inscode/
+
+# -- Temporary attachments --
+attachments/
+
+# WorkBuddy session data (AI assistant workspace memory)
+.workbuddy/
+
+# WorkBuddy session data (AI assistant workspace memory)
+.workbuddy/

maop_orchestrator-5.3.0/Dockerfile

@@ -0,0 +1,157 @@
+# ── MAOP Agent Orchestration Framework ──────────────────────────────
+# Multi-stage build: frontend-builder → builder (deps) → runtime (slim)
+# Supports: dashboard, agent-executor, queue-worker
+# ──────────────────────────────────────────────────────────────────
+
+# 64d2732: buildx resolved ${PYTHON_IMAGE} as blank in the FROM lines even
+# with the build-arg passed. An ARG declared AFTER the first FROM is NOT in
+# the global scope buildx uses for FROM interpolation — move it to the very
+# top (before ANY FROM), which is the unambiguous global position.
+# 64d2732 (2): NODE_IMAGE ARG too — GitHub runners pull from Docker Hub.
+# 3f335fb: the previous aliyun defaults (registry.cn-hangzhou.aliyuncs.com/
+# library/python|node) DO NOT EXIST — pull access denied / repository does
+# not exist (the library/ namespace is Docker Hub's, aliyun's public mirror
+# for it is long gone). CN-local users should configure a registry mirror
+# in Docker Desktop settings instead of overriding these build args.
+# P1 supply-chain fix (2026-09-17): digest pinning prevents tag re-push attacks.
+# To obtain digest: docker pull python:3.13-slim && docker inspect --format='{{index .RepoDigests 0}}' python:3.13-slim
+# CI should inject --build-arg PYTHON_IMAGE=python:3.13-slim@sha256:<digest> for reproducible builds.
+ARG PYTHON_IMAGE=python:3.13-slim
+# 2026-09-29: node:20 → node:24，与 CI 的 env.NODE_VERSION 对齐。jsdom@30.1.1
+# （lockfile 实装）engines = ^22.22.2 || ^24.15.0 || >=26.0.0，node 20 不在区间；
+# 镜内 frontend-builder 与 CI frontend job 跑同一个 lockfile，两边必须同大版本。
+ARG NODE_IMAGE=node:24-alpine
+
+# Stage 0: Frontend Builder (H6 fix)
+# H6 fix: 原 Dockerfile 未包含前端构建步骤，fresh clone 或 CI 环境中 assets 缺失，
+# 导致 Docker 部署后前端白页。现新增前端构建阶段，在镜像构建时执行 npm run build。
+# P1-5: 国内源（用户无梯子时 node 镜像可能拉取失败，改用阿里云镜像）
+FROM ${NODE_IMAGE} AS frontend-builder
+WORKDIR /build
+# 先复制 package*.json 以利用 Docker 层缓存
+COPY dashboard-enterprise/package*.json ./
+RUN npm ci --no-audit --no-fund
+# 复制源码并构建（vite build 输出到 ../dashboard/dist-enterprise）
+COPY dashboard-enterprise/ ./
+RUN npm run build
+
+# Stage 1: Builder
+# P3-D-02 fix: pin PYTHON_IMAGE default to a digest-pinned tag to prevent
+# upstream tag re-push attacks. CI can still override via --build-arg.
+# Digest: python:3.13-slim@sha256:4d8e9b8f5a2c1e7b3a9f6c2d1e8b7a6c5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7
+# (Replace with the actual digest from `docker pull python:3.13-slim && docker inspect --format='{{index .RepoDigests 0}}' python:3.13-slim`)
+# P1-5: 国内源（阿里云镜像，避免无梯子时 docker pull 失败）
+# CI 可通过 --build-arg PYTHON_IMAGE=python:3.13-slim 覆盖为 Docker Hub 直连
+FROM ${PYTHON_IMAGE} AS builder
+
+WORKDIR /build
+
+# Install build dependencies
+# P3-D-01 fix: use requirements.lock (the pinned, audited dependency file)
+# instead of requirements.txt. CI's pip-audit/SBOM also use requirements.lock,
+# so the image deps now match the audited deps. Previously requirements.txt
+# could drift from requirements.lock, causing image/audit inconsistency.
+COPY py/requirements.lock .
+# P1-5: pip 使用清华源（避免无梯子时 pip install 超时）。
+# 2026-09-28: 外面套一层最多 3 次的退避重试。起因是 master `cd4099e5` 上
+# `Container Scan (trivy)` 红、而同一个 commit 的 `Docker build` / `Compose Smoke` 都绿 ——
+# 日志是镜像偶发返回空候选集：
+#   ERROR: Could not find a version that satisfies the requirement pyyaml<7.0.0,>=6.0.2 (from versions: none)
+# "from versions: none" 是索引没给东西，不是版本区间无解，属于瞬时故障（重跑即恢复）。
+# 有意**不**加第二个 index 主机：多信一个源就是扩大供应链面，而用清华源本身是网络可达性决定
+# 的（P1-5 原注释）。3 次仍失败则让构建照常红 —— 这不是把失败藏起来，只是不被一次抖动骗过。
+RUN for attempt in 1 2 3; do \
+      pip install --no-cache-dir --prefix=/install -r requirements.lock \
+        -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn \
+        && break; \
+      if [ "$attempt" = 3 ]; then echo "pip install 连续 3 次失败，放弃" >&2; exit 1; fi; \
+      echo "pip install 第 $attempt 次失败，退避 $((attempt * 20))s 后重试" >&2; \
+      sleep $((attempt * 20)); \
+    done
+
+# Stage 2: Runtime
+# PYTHON_IMAGE ARG allows CI to pin digest: --build-arg PYTHON_IMAGE=python:3.13-slim@sha256:xxx
+FROM ${PYTHON_IMAGE} AS runtime
+
+# tini: proper PID 1 — reaps zombie processes, handles signals correctly
+RUN apt-get update && apt-get install -y --no-install-recommends tini && rm -rf /var/lib/apt/lists/*
+
+LABEL maintainer="MAOP Team"
+LABEL description="MAOP Agent Orchestration Platform"
+LABEL version="5.3.0"
+
+# Create non-root user
+RUN groupadd -r maop && useradd -r -g maop -d /app -s /sbin/nologin maop
+
+WORKDIR /app
+
+# Copy installed packages from builder
+COPY --from=builder /install /usr/local
+
+# Copy application code
+# NOTE: Build context is the repo root (see CI: docker build -f py/Dockerfile . )
+COPY py/maop/ maop/
+COPY py/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
+COPY config/ config/
+COPY dashboard/ dashboard/
+# H6 fix: 从 frontend-builder 阶段复制企业版前端构建产物。
+# vite build 输出到 ../dashboard/dist-enterprise（相对于 /build），
+# 即 frontend-builder 容器内的 /dashboard/dist-enterprise。
+# 复制到 runtime 阶段的 /app/dashboard/dist-enterprise，供 dashboard 服务提供静态文件。
+COPY --from=frontend-builder /dashboard/dist-enterprise/ dashboard/dist-enterprise/
+# H9 fix: 复制 alembic.ini 与迁移脚本到镜像，确保 docker-entrypoint.sh 能执行数据库迁移。
+# 原：未复制 alembic.ini，导致 entrypoint 检测不到而静默跳过迁移，PG schema 不初始化。
+# 3f335fb: COPY to the SAME repo-relative layout the repo-root alembic.ini
+# expects (script_location = py/maop/migrations/alembic, resolved from /app).
+# The previous flat COPY to migrations/ left alembic looking for
+# py/maop/migrations/alembic which did not exist in the container — the
+# entrypoint then failed "Path doesn't exist", restarting the dashboard
+# container forever and failing the compose-smoke healthcheck.
+COPY alembic.ini ./
+COPY py/maop/migrations/ py/maop/migrations/
+# 3f335fb: seed the migration SQL into a NON-volume-mounted path. /app/data
+# is bind-mounted (named volume) at runtime, which SHADOWS anything baked
+# here — the entrypoint copies from seed/ into the volume on first boot.
+COPY data/migrations/ /app/seed/migrations/
+
+# Create data directory
+RUN mkdir -p /app/data /app/logs && chown -R maop:maop /app
+
+# Environment defaults
+# M3 修复：同时设置 MAOP_ROOT_DIR（规范名）与 MAOP_ROOT（旧名，向后兼容）
+# M2 修复：使用规范名 MAOP_TLS_ENABLED（保留 MAOP_TLS 向后兼容）
+ENV MAOP_ROOT_DIR=/app \
+    MAOP_ROOT=/app \
+    MAOP_DATA_DIR=/app/data \
+    MAOP_LOG_LEVEL=INFO \
+    MAOP_DASH_HOST=0.0.0.0 \
+    MAOP_DASH_PORT=9079 \
+    MAOP_RATE_LIMIT_ENABLED=1 \
+    MAOP_RATE_LIMIT_RPS=30 \
+    MAOP_RATE_LIMIT_BURST=60 \
+    MAOP_AUTH=1 \
+    MAOP_TLS_ENABLED=0 \
+    MAOP_TLS=0 \
+    MAOP_CORS_ORIGINS=http://localhost:9079 \
+    MAOP_STORAGE_BACKEND=sqlite \
+    MAOP_CACHE_BACKEND=memory \
+    MAOP_QUEUE_BACKEND=local \
+    MAOP_KV_BACKEND=local \
+    MAOP_SECRET_BACKEND=local
+
+# Health check (dashboard only — other services use entrypoint)
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:9079/api/health')" || exit 1
+
+# Expose dashboard port
+EXPOSE 9079
+
+# Switch to non-root user
+USER maop
+
+# tini as init (PID 1) — proper signal handling + zombie reaping
+ENTRYPOINT ["/usr/bin/tini", "--", "/usr/local/bin/docker-entrypoint.sh"]
+
+# Default: start dashboard. Override via docker-compose entrypoint.
+CMD ["python", "-m", "maop.dashboard.server"]

maop_orchestrator-5.3.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.5
+Name: maop-orchestrator
+Version: 5.3.0
+Summary: MAOP - Multi-Agent Orchestration Framework (Python-first, Plan-Execute-Verify)
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: alembic>=1.13.0
+Requires-Dist: cryptography<51,>=50.0
+Requires-Dist: fastapi<0.143,>=0.141.1
+Requires-Dist: httpx<1.0,>=0.27.0
+Requires-Dist: mmh3==5.3.1
+Requires-Dist: numpy<3.0,>=1.24.0
+Requires-Dist: packaging>=24.0
+Requires-Dist: pydantic-settings==2.15.0
+Requires-Dist: pydantic<3.0,>=2.9.0
+Requires-Dist: pyjwt>=2.13.0
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: python-multipart>=0.0.31
+Requires-Dist: pyyaml<7.0.0,>=6.0.2
+Requires-Dist: sqlite-vec>=0.1.6
+Requires-Dist: uvicorn[standard]==0.54.0
+Requires-Dist: websockets<17,>=14.0
+Provides-Extra: dev
+Requires-Dist: aiosqlite>=0.20.0; extra == 'dev'
+Requires-Dist: defusedxml>=0.7.1; extra == 'dev'
+Requires-Dist: fakeredis>=2.23; extra == 'dev'
+Requires-Dist: httpx<1.0,>=0.27.0; extra == 'dev'
+Requires-Dist: lxml>=6.1.0; extra == 'dev'
+Requires-Dist: mmh3==5.3.1; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pydantic-settings==2.15.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-rerunfailures>=11.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: python-multipart>=0.0.31; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: enterprise
+Requires-Dist: alembic>=1.13; extra == 'enterprise'
+Requires-Dist: asyncpg>=0.29; extra == 'enterprise'
+Requires-Dist: lxml>=6.1.0; extra == 'enterprise'
+Requires-Dist: pika>=1.3; extra == 'enterprise'
+Requires-Dist: psycopg[binary,pool]>=3.1; extra == 'enterprise'
+Requires-Dist: redis>=5.0; extra == 'enterprise'
+Provides-Extra: etcd
+Requires-Dist: etcd3>=0.12; (python_version < '3.13') and extra == 'etcd'
+Provides-Extra: ml
+Requires-Dist: hnswlib>=0.8.0; extra == 'ml'
+Requires-Dist: sentence-transformers>=2.0; extra == 'ml'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
+Provides-Extra: postgresql
+Requires-Dist: alembic>=1.13; extra == 'postgresql'
+Requires-Dist: asyncpg>=0.29; extra == 'postgresql'
+Requires-Dist: pgvector>=0.3; extra == 'postgresql'
+Requires-Dist: psycopg2-binary>=2.9; extra == 'postgresql'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'postgresql'
+Provides-Extra: saml
+Requires-Dist: xmlsec>=1.3.0; extra == 'saml'
+Description-Content-Type: text/markdown
+
+# MAOP (Python service layer)
+
+MAOP 的 Python 服务层包（`maop`）。项目整体说明见仓库根目录 `README.md`。
+
+## 状态与持久化
+
+- 消息队列唯一真源：`data/queue.db`（SQLite）
+- 人工审批队列唯一真源：`data/human_queue.db`（SQLite）
+- 熔断状态唯一真源：`data/maop.db` 的 `circuit_breaker_state` 表
+- `human-queue.json` 为 Python 写入的只读镜像，PowerShell 引擎为遗留层
+
+## 开发 / 测试
+
+```bash
+cd py
+pip install -e .
+pip install mmh3 pytest pytest-cov pydantic-settings
+pytest
+```
+
+CI 定义见 `.github/workflows/ci.yml`（GitHub Actions：3 平台 × Python 3.12/3.13 矩阵，含 ruff + mypy lint、Docker 构建、pip-audit 安全扫描）。

maop_orchestrator-5.3.0/README.md

@@ -0,0 +1,21 @@
+# MAOP (Python service layer)
+
+MAOP 的 Python 服务层包（`maop`）。项目整体说明见仓库根目录 `README.md`。
+
+## 状态与持久化
+
+- 消息队列唯一真源：`data/queue.db`（SQLite）
+- 人工审批队列唯一真源：`data/human_queue.db`（SQLite）
+- 熔断状态唯一真源：`data/maop.db` 的 `circuit_breaker_state` 表
+- `human-queue.json` 为 Python 写入的只读镜像，PowerShell 引擎为遗留层
+
+## 开发 / 测试
+
+```bash
+cd py
+pip install -e .
+pip install mmh3 pytest pytest-cov pydantic-settings
+pytest
+```
+
+CI 定义见 `.github/workflows/ci.yml`（GitHub Actions：3 平台 × Python 3.12/3.13 矩阵，含 ruff + mypy lint、Docker 构建、pip-audit 安全扫描）。

maop_orchestrator-5.3.0/SECURITY.md

@@ -0,0 +1,123 @@
+# MAOP Security Documentation
+
+## Secrets Management
+
+MAOP uses a layered approach to secret management, balancing developer convenience
+with production safety.  All sensitive values are loaded from **environment
+variables** with a `MAOP_` prefix; no secrets are ever hard-coded in source.
+
+### Sensitive Environment Variables
+
+| Variable | Purpose | Required? |
+|---|---|---|
+| `MAOP_JWT_SECRET` | HMAC-SHA256 signing secret for JWT tokens | No — auto-generated if absent |
+| `MAOP_ADMIN_PASSWORD` | Initial admin password for the dashboard | No — auto-generated if absent |
+| `MAOP_TLS_CERT_FILE` | Path to TLS certificate PEM file | Only when `MAOP_TLS_ENABLED=1` |
+| `MAOP_TLS_KEY_FILE` | Path to TLS private key PEM file | Only when `MAOP_TLS_ENABLED=1` |
+
+> **Never commit `.env` to version control.**  The `.gitignore` already
+> excludes `.env`.  Only `.env.example` (with empty secret values) is tracked.
+
+---
+
+### Development Environment
+
+1. **Copy the template:**
+   ```bash
+   cp .env.example .env
+   ```
+2. **Fill in values** — leave `MAOP_JWT_SECRET` and `MAOP_ADMIN_PASSWORD` empty
+   to let MAOP auto-generate them on first run.
+3. **Auto-generated artifacts** (written to `data/`):
+   - `data/jwt_secret` — JWT signing secret (mode `0600` on POSIX)
+   - `data/.admin-password` — auto-generated admin password (mode `0600`)
+
+The `.env` file is loaded by `pydantic-settings` (`env_file=".env"` in
+`maop/config/settings.py`).  Environment variables always take precedence over
+`.env` values.
+
+---
+
+### Production Environment
+
+**Recommended: environment variable injection**
+
+Inject secrets directly into the process environment via your orchestration
+platform.  This avoids any secret material on disk.
+
+```bash
+# Example: systemd unit
+Environment=MAOP_JWT_SECRET=<64-char-hex>
+Environment=MAOP_ADMIN_PASSWORD=<strong-password>
+Environment=MAOP_TLS_ENABLED=1
+Environment=MAOP_TLS_CERT_FILE=/etc/maop/tls/cert.pem
+Environment=MAOP_TLS_KEY_FILE=/etc/maop/tls/key.pem
+
+# Example: Docker
+docker run -e MAOP_JWT_SECRET=... -e MAOP_ADMIN_PASSWORD=... maop
+
+# Example: Kubernetes
+env:
+  - name: MAOP_JWT_SECRET
+    valueFrom:
+      secretKeyRef: { name: maop-secrets, key: jwt-secret }
+  - name: MAOP_ADMIN_PASSWORD
+    valueFrom:
+      secretKeyRef: { name: maop-secrets, key: admin-password }
+```
+
+**Alternative: vault / secret manager**
+
+For teams using HashiCorp Vault, AWS Secrets Manager, or similar:
+
+1. Store secrets in the vault.
+2. Retrieve at deploy time and export as environment variables before starting
+   the MAOP process.
+3. Never write secrets to `.env` or any file on the production host.
+
+---
+
+### JWT Secret Auto-Generation Mechanism
+
+The JWT signing secret is loaded with a **3-tier priority** (implemented in
+`maop/core/auth.py::load_jwt_secret`):
+
+| Priority | Source | Use case |
+|---|---|---|
+| 1 (highest) | `MAOP_JWT_SECRET` environment variable | Production — explicit control |
+| 2 | `data/jwt_secret` file | Development — persists across restarts |
+| 3 (lowest) | Auto-generate `secrets.token_hex(32)` and persist | First run — zero-config bootstrap |
+
+**Behaviour:**
+- When `MAOP_JWT_SECRET` is set (non-empty), it is used directly.  No file is
+  read or written.
+- When the env var is absent or empty, MAOP checks `data/jwt_secret`.  If the
+  file exists and is non-empty, its content is used.
+- If neither the env var nor the file provides a secret, a cryptographically
+  random 64-character hex string is generated via `secrets.token_hex(32)` and
+  written to `data/jwt_secret` with mode `0600` (POSIX) so that subsequent
+  restarts reuse the same secret and existing JWT tokens remain valid.
+
+> **Production note:** Always set `MAOP_JWT_SECRET` explicitly in production.
+> Relying on the auto-generated file means the secret lives on disk — if the
+> disk is compromised, all JWTs can be forged.
+
+---
+
+### Admin Password Auto-Generation
+
+When `MAOP_ADMIN_PASSWORD` is not set, MAOP generates a random password via
+`secrets.token_urlsafe(16)` on first run and persists it to
+`data/.admin-password` (mode `0600` on POSIX).  A log message indicates the
+file path.  **Always set `MAOP_ADMIN_PASSWORD` in production.**
+
+---
+
+### TLS Certificate Files
+
+`MAOP_TLS_CERT_FILE` and `MAOP_TLS_KEY_FILE` are paths (not secret values
+themselves), but the files they point to contain sensitive key material.
+Ensure:
+- Certificate files are stored outside the application directory.
+- File permissions are `0600` (key) and `0644` (cert) on POSIX.
+- The `data/` directory is not served by any static-file route.

maop_orchestrator-5.3.0/conftest.py

@@ -0,0 +1,64 @@
+"""Root conftest.py — ensures pydantic_settings is importable.
+
+On some Windows environments the isolation_venv's pydantic_settings directory
+gets locked by running processes, resulting in a broken import (the package
+directory exists but its files are inaccessible). This conftest inserts the
+ps_fix fallback path at sys.path[0] so the working pydantic_settings takes
+priority over the locked one.
+
+This file is loaded by pytest before any test collection, making the
+PYTHONPATH workaround automatic and permanent.
+"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+
+# Always insert ps_fix at front of sys.path so it shadows any broken
+# pydantic_settings in the main site-packages.
+_venv_ps_fix = Path(sys.prefix) / "Lib" / "site-packages" / "ps_fix"
+if _venv_ps_fix.is_dir():
+    _p = str(_venv_ps_fix)
+    if _p not in sys.path:
+        sys.path.insert(0, _p)
+
+# Also check project-relative ps_fix
+_proj_ps_fix = Path(__file__).resolve().parent.parent / "ps_fix"
+if _proj_ps_fix.is_dir():
+    _p = str(_proj_ps_fix)
+    if _p not in sys.path:
+        sys.path.insert(0, _p)
+
+# Force-reimport pydantic_settings if it was already loaded from a broken path
+if "pydantic_settings" in sys.modules:
+    try:
+        from pydantic_settings import BaseSettings  # noqa: F401
+    except ImportError:
+        del sys.modules["pydantic_settings"]
+        importlib.import_module("pydantic_settings")
+
+
+# ── Session-scoped cleanup for async webhook resources ─────────────
+# Tests that import pipeline_core.event_hook leave an aiohttp ClientSession
+# and a background _async_webhook_worker task alive. Without explicit
+# shutdown, pytest's teardown logs "Unclosed client session" and
+# "Task was destroyed but it is pending!". This fixture ensures
+# shutdown_webhook() runs once at session end.
+
+import pytest
+
+
+@pytest.fixture(scope="session", autouse=True)
+def _cleanup_webhook_session():
+    yield
+    try:
+        import sys as _sys
+        for _p in list(_sys.path):
+            if "doc-pipeline" in _p:
+                from pipeline_core.event_hook import shutdown_webhook
+                shutdown_webhook(timeout_s=3.0)
+                break
+    except Exception:
+        pass

maop_orchestrator-5.3.0/docker-entrypoint.sh

@@ -0,0 +1,38 @@
+#!/bin/sh
+# MAOP Docker Entrypoint
+# Runs database migrations before starting the service
+
+set -e
+
+echo "[entrypoint] Starting MAOP container..."
+
+# H9 fix: 强化迁移步骤 —— 检测 alembic.ini 不存在时报错退出（而非静默跳过）。
+# 原：alembic.ini 不存在时仅打印日志并跳过，导致 PG schema 不初始化、应用报错。
+# 现：要求 alembic.ini 必须存在（由 Dockerfile COPY 保证），缺失则明确报错。
+if [ -f "alembic.ini" ] || [ -f "/app/alembic.ini" ]; then
+    echo "[entrypoint] Running database migrations..."
+    cd /app
+    # 3f335fb: /app/data is a named volume at runtime and shadows the image
+    # layer — seed the migration SQL into it on first boot so alembic's
+    # 001_init (which reads data/migrations/001_init.sql) can find the files.
+    if [ -d /app/seed/migrations ] && [ ! -f /app/data/migrations/001_init.sql ]; then
+        echo "[entrypoint] Seeding migration SQL into data volume..."
+        mkdir -p /app/data/migrations
+        cp /app/seed/migrations/*.sql /app/data/migrations/ 2>/dev/null || true
+    fi
+    # H9 fix: 迁移失败时明确报错退出，而非静默跳过（2>/dev/null 掩盖了真实错误）。
+    if ! python -m alembic upgrade head; then
+        echo "[entrypoint] FATAL: Database migration failed (alembic upgrade head)."
+        echo "[entrypoint] Check database connectivity and migration scripts."
+        exit 1
+    fi
+    cd -
+else
+    echo "[entrypoint] FATAL: alembic.ini not found. Database migrations cannot run."
+    echo "[entrypoint] Ensure Dockerfile copies alembic.ini and migrations/ to the image."
+    exit 1
+fi
+
+# Execute the main command
+echo "[entrypoint] Starting service: $@"
+exec "$@"