petfishframework 0.3.3__tar.gz → 0.4.0__tar.gz

petfishframework-0.4.0/.sisyphus/plans/v0.4.0-plan.md

@@ -0,0 +1,236 @@
+# petfishFramework v0.4.0 开发计划
+
+> 基于 v0.3.3 状态 + 8 轮用户反馈 + 全部 deferred 项汇总
+> 目标：observability + deterministic replay + 生产化基础
+> 原则：**TDD 先行，pre_release.py 门禁，文档同步作为完成条件**
+
+## v0.4.0 使命
+
+> 让 Agent 运行时可观测（OTel）、可回放（确定性 RERUN/RESUME）、可治理（SIEM export）、可部署（Docker + 部署指南）。
+
+## Deferred 项汇总（从全部反馈中提取）
+
+| 来源 | Deferred 项 | v0.4.0 目标 |
+|---|---|---|
+| v0.3.0 §9.2 | deterministic rerun / resume | ✅ 实现 |
+| v0.3.0 §9.2 | MCP server mode | ⏳ v0.5.0（需完整 MCP server 实现） |
+| v0.3.0 §9.2 | deployment guide | ✅ Dockerfile + 部署文档 |
+| v0.3.0 §9.2 | OpenTelemetry | ✅ OTelSink |
+| v0.3.0 §9.2 | SIEM export | ✅ JSON-Lines trace export |
+| v0.3.0 §P2 | Vault adapter | ✅ HashiCorp Vault adapter (可选) |
+| v0.3.0 §P2 | threat model | ✅ 威胁模型文档 |
+| v0.3.0 §P2 | SBOM | ✅ cyclonedx 生成 |
+| v0.3.0 §P2 | signed release | ✅ sigstore cosign |
+| 多轮 | README Current Limitations 中 planned 项 | 清理为 available |
+
+---
+
+## Phase A: Deterministic Replay (RESUME + RERUN)
+
+### A1: RESUME — 检查点恢复
+
+**目标**：从检查点恢复执行，重注入已记录的模型响应直到检查点，之后继续新鲜调用。
+
+#### TDD 测试先行
+
+```python
+# tests/test_replay_resume.py
+
+def test_resume_replays_recorded_prefix():
+    """RESUME: 重注入检查点前的模型响应。"""
+
+def test_resume_continues_with_fresh_calls():
+    """RESUME: 检查点后用 live environment 新鲜调用。"""
+
+def test_resume_from_mid_session():
+    """RESUME: 从 Session 中间的检查点恢复。"""
+```
+
+#### 实现
+
+- `ResumableEnvironment`（已有 v0.1.x 基础）增强：
+  - `checkpoint_model_idx` / `checkpoint_tool_idx` 参数
+  - 检查点前用 `recording.model_responses[i]` 重注入
+  - 检查点后切换到 `live_env`
+- `Session.checkpoint()` 发出 `session.checkpoint` 事件 + 记录当前 model/tool 索引
+- `Session.resume_from(checkpoint_data)` 工厂方法
+
+### A2: RERUN — 确定性完整重放 + 偏离检测
+
+**目标**：完整重放一个 Session 的所有调用，验证轨迹一致。偏离时报告差异。
+
+#### TDD 测试先行
+
+```python
+# tests/test_replay_rerun.py
+
+def test_rerun_reproduces_identical_trajectory():
+    """RERUN: 完整重放，轨迹完全一致。"""
+
+def test_rerun_detects_model_call_count_divergence():
+    """RERUN: 模型调用次数不一致 → 报告偏离。"""
+
+def test_rerun_detects_tool_result_divergence():
+    """RERUN: 工具结果不一致 → 报告偏离。"""
+```
+
+#### 实现
+
+- `RerunEnvironment`：封装 `RecordingEnvironment` + `ReplayEnvironment`
+  - `rerun() -> RerunResult`：重放 + 比对
+  - `RerunResult.matches: bool` + `divergences: list[str]`
+  - 检测：调用次数偏离、工具名偏离、结果值偏离
+
+---
+
+## Phase B: Observability
+
+### B1: OpenTelemetry Sink
+
+**目标**：Session 事件 → OTel spans，可接入 Jaeger/Zipkin/DataDog。
+
+#### TDD 测试先行
+
+```python
+# tests/test_otel_sink.py
+
+def test_otel_sink_creates_span_per_tool_call():
+    """每个 tool.called 事件创建一个 span。"""
+
+def test_otel_sink_creates_span_per_model_call():
+    """每个 model.called 事件创建一个 span。"""
+
+def test_otel_sink_nests_tool_spans_under_session():
+    """工具 span 嵌套在 session trace 下。"""
+```
+
+#### 实现
+
+- `observability/otel_sink.py` — `OTelSink`:
+  - 接收 EventEmitter 事件
+  - Session → OTel Trace
+  - model.called → span (attributes: model name, tokens, cost)
+  - tool.called/blocked/masked → span (attributes: tool name, effect, duration)
+  - 使用 `opentelemetry-api`（可选依赖：`pip install petfishframework[otel]`）
+  - 无 OTel 安装时降级为 no-op
+
+### B2: SIEM Export (JSON-Lines Trace)
+
+**目标**：结构化事件导出，可导入 Splunk/Elastic/Datadog。
+
+#### TDD 测试先行
+
+```python
+# tests/test_siem_export.py
+
+def test_siem_export_produces_jsonlines():
+    """导出为 JSON-Lines 格式。"""
+
+def test_siem_export_redacts_credentials():
+    """导出中不含 secret。"""
+
+def test_siem_export_includes_policy_version():
+    """每条记录包含 policy_version。"""
+```
+
+#### 实现
+
+- `observability/siem_sink.py` — `SIEMSink`:
+  - 接收事件 → 写入 JSON-Lines 文件/流
+  - 每行：`{"timestamp", "session_id", "event_type", "tool_name", "effect", "executed", "policy_version", "duration_ms"}`
+  - 自动脱敏（复用 event_mask 逻辑）
+
+---
+
+## Phase C: Production Foundation
+
+### C1: Vault Adapter
+
+**目标**：CredentialBroker 支持 HashiCorp Vault 作为 secret 后端。
+
+#### TDD 测试先行
+
+```python
+# tests/test_vault_adapter.py
+
+def test_vault_adapter_reads_secret():
+    """Vault adapter 从 Vault 读取 secret。"""
+    # 使用 mock，不连真实 Vault
+
+def test_vault_adapter_caches_locally():
+    """读取后缓存，减少 Vault 调用。"""
+```
+
+#### 实现
+
+- `credentials/vault_adapter.py` — `VaultCredentialSource`:
+  - `read_secret(path: str) -> str` — 从 Vault 读取
+  - 可选依赖：`hvac` library
+  - 集成到 `CredentialBroker.register_credential_from_vault(path)`
+
+### C2: Dockerfile + 部署指南
+
+**文件**：
+- `Dockerfile` — 多阶段构建
+- `docker-compose.yml` — 开发环境
+- `docs/deployment.md` — 部署指南
+
+### C3: SBOM + Signed Release
+
+- `.github/workflows/publish.yml` 增强：
+  - 生成 SBOM (cyclonedx)
+  - cosign 签名
+- `docs/threat-model.md` — 威胁模型
+
+### C4: 文档 + README 更新
+
+- api.md: 新增 OTel + SIEM + Vault + Replay 章节
+- README: Current Limitations 清理（deterministic replay: Available; OTel: Available）
+- CHANGELOG: v0.4.0
+
+---
+
+## 执行顺序与依赖
+
+```
+A1 (RESUME) → A2 (RERUN)
+    ↓
+B1 (OTel) → B2 (SIEM)
+    ↓
+C1 (Vault) → C2 (Docker) → C3 (SBOM) → C4 (docs)
+```
+
+## 验收标准
+
+| # | 标准 | 验证方法 |
+|---|---|---|
+| V1 | RESUME 从检查点恢复执行 | `test_replay_resume.py` |
+| V2 | RERUN 完整重放 + 偏离检测 | `test_replay_rerun.py` |
+| V3 | OTel sink 生成 spans | `test_otel_sink.py` |
+| V4 | SIEM 导出 JSON-Lines + 脱敏 | `test_siem_export.py` |
+| V5 | Vault adapter 读取 secret（mock） | `test_vault_adapter.py` |
+| V6 | Dockerfile 可构建 | `docker build .` |
+| V7 | SBOM 生成 | CI workflow |
+| V8 | pre_release.py exit 0 | `python scripts/pre_release.py 0.4.0` |
+| V9 | 所有 284+ 现有测试通过 | pytest |
+| V10 | ruff clean | ruff check |
+| V11 | README Current Limitations 清理 | grep "Planned" |
+
+## 不做清单（v0.5.0+）
+
+- ❌ MCP server mode
+- ❌ MCP governance (allowlist, rate limit)
+- ❌ Tool sandbox (subprocess isolation)
+- ❌ Policy hot-reload
+- ❌ Multi-tenant policy namespace
+
+## 新测试预估
+
+| Phase | 测试数 |
+|---|---|
+| A1 RESUME | 3 |
+| A2 RERUN | 3 |
+| B1 OTel | 3 |
+| B2 SIEM | 3 |
+| C1 Vault | 2 |
+| **总计** | **~14 新测试** |

{petfishframework-0.3.3 → petfishframework-0.4.0}/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to petfishFramework will be documented in this file.
 
+## [0.4.0] — 2026-07-08
+
+### v0.4.0 Production Foundation
+
+#### Phase A+B: Deterministic Replay + Observability
+- Deterministic replay infrastructure (`petfishframework.reliability.replay`):
+  - `RecordingEnvironment` captures every model response, tool call, and retrieval
+  - `ReplayEnvironment` replays recorded calls for deterministic audit
+  - `ResumableEnvironment` replays prefix then switches to live execution
+  - `ReplayMode.AUDIT`, `RESUME`, `RERUN` semantics
+- OpenTelemetry sink (`OTelSink`) — creates spans for model/tool/session events
+- SIEM export (`SIEMSink`) — structured JSON audit events for downstream SIEMs
+
+#### Phase C: Vault Adapter + Deployment + Threat Model
+- `VaultCredentialSource` — reads secrets from HashiCorp Vault with lazy `hvac` import
+- `CredentialBroker.register_credential_from_vault(name, source, path)` — register
+  credentials fetched from Vault
+- Optional dependency group `vault = ["hvac>=1.0"]`
+- `Dockerfile` and `docker-compose.yml` for containerized deployment
+- `docs/deployment.md` — Docker deployment guide, environment variables, volume mounts,
+  credential-broker integration, and security notes
+- `docs/threat-model.md` — attack surface, trust boundaries, threats, mitigations,
+  and fail-closed defaults
+
+#### Documentation Sync
+- `docs/api.md` updated to v0.4.0
+- README: deterministic replay and OTel marked available, roadmap bumped to v0.4.x
+- Test count badge updated to 300
+
 ## [0.3.2] — 2026-07-08
 
 ### YAML Policy DSL Expansion

petfishframework-0.4.0/Dockerfile

@@ -0,0 +1,7 @@
+FROM python:3.12-slim
+WORKDIR /app
+COPY pyproject.toml uv.lock ./
+RUN pip install uv && uv sync --no-dev
+COPY src/ src/
+RUN uv pip install --system .
+ENTRYPOINT ["python", "-m", "petfishframework"]

{petfishframework-0.3.3 → petfishframework-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: petfishframework
-Version: 0.3.3
+Version: 0.4.0
 Summary: A lightweight runtime framework for reliable, auditable, budget-aware, and permission-aware AI agents.
 Project-URL: Homepage, https://github.com/kylecui/petfishFramework
 Project-URL: Documentation, https://github.com/kylecui/petfishFramework/tree/master/docs
@@ -26,6 +26,11 @@ Provides-Extra: mcp
 Requires-Dist: mcp>=1.0; extra == 'mcp'
 Provides-Extra: openai
 Requires-Dist: openai>=1.0; extra == 'openai'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
+Provides-Extra: vault
+Requires-Dist: hvac>=1.0; extra == 'vault'
 Description-Content-Type: text/markdown
 
 # petfishFramework
@@ -34,7 +39,7 @@ Description-Content-Type: text/markdown
 
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/kylecui/petfishFramework/blob/master/LICENSE)
-[![Tests: 284](https://img.shields.io/badge/tests-284-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
+[![Tests: 300](https://img.shields.io/badge/tests-300-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
 
 **Status: Alpha** — API may change. Core runtime works; see [Roadmap](#roadmap).
 
@@ -247,8 +252,8 @@ agent = Agent(model=model, reasoning=ReAct(), tools=tools, credential_broker=bro
 ## Roadmap
 
 - **v0.2.x**: Core runtime, permission semantics, enterprise PoC, Trusted Publishing ✅
-- **v0.3.x** (current): YAML Policy Engine, CredentialBroker ✅
-- **v0.4.x**: Production hardening, deployment guides
+- **v0.3.x**: YAML Policy Engine, CredentialBroker ✅
+- **v0.4.x** (current): Production hardening, deployment guides, Vault adapter, Docker, threat model ✅
 
 ## Current Limitations
 
@@ -263,8 +268,8 @@ petfishFramework is **Alpha**. API may change before v1.0.
 | PARTIAL_ALLOW | ✅ Enforced (pre-execution arg filtering) |
 | MASK | ✅ Enforced (input mask before + output mask after) |
 | DEGRADE | ✅ Enforced (fallback tool switching) |
-| Session replay | ✅ Audit replay available |
-| Deterministic rerun / resume | 📋 Planned |
+| Session replay / deterministic rerun / resume | ✅ Available |
+| OpenTelemetry + SIEM observability | ✅ Available |
 | MCP client stdio | ✅ Available |
 | MCP server mode | 📋 Planned |
 | Structured output / conversation memory | ✅ Available |
@@ -279,7 +284,7 @@ petfishFramework is **Alpha**. API may change before v1.0.
 git clone https://github.com/kylecui/petfishFramework.git
 cd petfishFramework
 uv sync --all-extras
-uv run pytest              # 284 tests
+uv run pytest              # 300 tests
 uv run ruff check src/ tests/
 ```
 

{petfishframework-0.3.3 → petfishframework-0.4.0}/README.md

@@ -4,7 +4,7 @@
 
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/kylecui/petfishFramework/blob/master/LICENSE)
-[![Tests: 284](https://img.shields.io/badge/tests-284-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
+[![Tests: 300](https://img.shields.io/badge/tests-300-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
 
 **Status: Alpha** — API may change. Core runtime works; see [Roadmap](#roadmap).
 
@@ -217,8 +217,8 @@ agent = Agent(model=model, reasoning=ReAct(), tools=tools, credential_broker=bro
 ## Roadmap
 
 - **v0.2.x**: Core runtime, permission semantics, enterprise PoC, Trusted Publishing ✅
-- **v0.3.x** (current): YAML Policy Engine, CredentialBroker ✅
-- **v0.4.x**: Production hardening, deployment guides
+- **v0.3.x**: YAML Policy Engine, CredentialBroker ✅
+- **v0.4.x** (current): Production hardening, deployment guides, Vault adapter, Docker, threat model ✅
 
 ## Current Limitations
 
@@ -233,8 +233,8 @@ petfishFramework is **Alpha**. API may change before v1.0.
 | PARTIAL_ALLOW | ✅ Enforced (pre-execution arg filtering) |
 | MASK | ✅ Enforced (input mask before + output mask after) |
 | DEGRADE | ✅ Enforced (fallback tool switching) |
-| Session replay | ✅ Audit replay available |
-| Deterministic rerun / resume | 📋 Planned |
+| Session replay / deterministic rerun / resume | ✅ Available |
+| OpenTelemetry + SIEM observability | ✅ Available |
 | MCP client stdio | ✅ Available |
 | MCP server mode | 📋 Planned |
 | Structured output / conversation memory | ✅ Available |
@@ -249,7 +249,7 @@ petfishFramework is **Alpha**. API may change before v1.0.
 git clone https://github.com/kylecui/petfishFramework.git
 cd petfishFramework
 uv sync --all-extras
-uv run pytest              # 284 tests
+uv run pytest              # 300 tests
 uv run ruff check src/ tests/
 ```
 

petfishframework-0.4.0/docker-compose.yml

@@ -0,0 +1,8 @@
+version: "3.9"
+services:
+  agent:
+    build: .
+    environment:
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+    volumes:
+      - ./examples:/app/examples

{petfishframework-0.3.3 → petfishframework-0.4.0}/docs/api.md

@@ -1,6 +1,6 @@
 # petfishFramework API Reference
 
-This document is the authoritative reference for the public API of `petfishFramework` v0.3.2. Every signature, field, and example below is derived from the source code and from the tests that exercise it.
+This document is the authoritative reference for the public API of petfishFramework v0.4.0. Every signature, field, and example below is derived from the source code and from the tests that exercise it.
 
 ## 1. Overview
 
@@ -1445,3 +1445,27 @@ token.get_secret()  # raises ValueError("max uses exceeded")
 if session.credential_broker:
     session.credential_broker.cleanup_expired()
 ```
+
+### Vault Integration (v0.4.0)
+
+```python
+from petfishframework.credentials import CredentialBroker, VaultCredentialSource
+
+broker = CredentialBroker()
+source = VaultCredentialSource(
+    vault_url="https://vault.example.com",
+    token="hvs.CAES...",
+)
+broker.register_credential_from_vault("openai", source, path="secrets/openai")
+```
+
+`VaultCredentialSource` performs a lazy import of `hvac` and raises a clear
+`ImportError` if the optional dependency is missing. The secret is read once and
+cached locally for the lifetime of the source; subsequent reads of the same
+path do not call Vault again.
+
+Install the optional dependency with:
+
+```bash
+pip install petfishframework[vault]
+```

petfishframework-0.4.0/docs/deployment.md

@@ -0,0 +1,181 @@
+# Deployment Guide
+
+This guide covers running petfishFramework in production using Docker and
+Docker Compose.
+
+## Quick Start
+
+Build and run the container:
+
+```bash
+docker build -t petfishframework .
+docker run --rm -e OPENAI_API_KEY=$OPENAI_API_KEY petfishframework
+```
+
+With Docker Compose:
+
+```bash
+docker compose up --build
+```
+
+## Dockerfile
+
+The included `Dockerfile` uses a multi-stage style with `uv`:
+
+1. Copies `pyproject.toml` and `uv.lock` first for layer caching.
+2. Installs production dependencies with `uv sync --no-dev`.
+3. Copies the `src/` directory and installs the package itself.
+4. Uses `ENTRYPOINT ["python", "-m", "petfishframework"]`.
+
+To build for a specific Python version, change the base image tag:
+
+```dockerfile
+FROM python:3.11-slim
+```
+
+## Environment Variables
+
+The container reads configuration from environment variables. Required and
+commonly used variables:
+
+| Variable | Purpose | Example |
+|---|---|---|
+| `OPENAI_API_KEY` | API key for OpenAI-compatible models | `sk-...` |
+| `OPENAI_BASE_URL` | Custom base URL for OpenAI-compatible endpoints | `https://api.siliconflow.cn/v1` |
+| `ANTHROPIC_API_KEY` | API key for Anthropic models | `sk-ant-...` |
+| `VAULT_ADDR` | HashiCorp Vault URL when using `VaultCredentialSource` | `https://vault.example.com` |
+| `VAULT_TOKEN` | Vault token (alternative to passing it in code) | `hvs.CAES...` |
+
+Pass variables with `-e`:
+
+```bash
+docker run --rm \
+  -e OPENAI_API_KEY=$OPENAI_API_KEY \
+  -e OPENAI_BASE_URL=$OPENAI_BASE_URL \
+  petfishframework
+```
+
+Or use an `.env` file:
+
+```bash
+docker run --rm --env-file .env petfishframework
+```
+
+## Volume Mounts
+
+Mount directories that the framework needs at runtime:
+
+### Examples and local policies
+
+```bash
+docker run --rm \
+  -e OPENAI_API_KEY=$OPENAI_API_KEY \
+  -v $(pwd)/examples:/app/examples \
+  -v $(pwd)/policies:/app/policies \
+  petfishframework python examples/05_enterprise_expense.py
+```
+
+### Credentials and secrets
+
+Do **not** bake credentials into the image. Instead, use one of these
+approaches:
+
+1. **Environment variables** — simplest for container runtimes.
+2. **Secret mounts** — Docker secrets or Kubernetes secrets mounted as files.
+3. **Vault integration** — use `VaultCredentialSource` to fetch secrets at
+   startup; see the [Credential Broker](#credential-broker) section below.
+
+For policy files, YAML policy engine, and example scripts, mount a read-only
+volume:
+
+```yaml
+volumes:
+  - ./examples:/app/examples:ro
+  - ./policies:/app/policies:ro
+```
+
+## Docker Compose
+
+The included `docker-compose.yml` starts a single `agent` service:
+
+```yaml
+version: "3.9"
+services:
+  agent:
+    build: .
+    environment:
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+    volumes:
+      - ./examples:/app/examples
+```
+
+Override it with a `docker-compose.override.yml` for local secrets or extra
+mounts:
+
+```yaml
+services:
+  agent:
+    environment:
+      - VAULT_ADDR=https://vault.example.com
+    secrets:
+      - vault_token
+
+secrets:
+  vault_token:
+    file: ./secrets/vault_token
+```
+
+## Credential Broker
+
+Use `CredentialBroker` with `VaultCredentialSource` to avoid passing raw secrets
+through environment variables:
+
+```python
+from petfishframework.credentials import CredentialBroker, VaultCredentialSource
+
+broker = CredentialBroker()
+source = VaultCredentialSource(
+    vault_url="https://vault.example.com",
+    token="hvs.CAES...",
+)
+broker.register_credential_from_vault("openai", source, path="secrets/openai")
+```
+
+The Vault source reads the secret once, caches it locally for the lifetime of
+the process, and issues scoped, time-limited tokens to tools. The underlying
+`hvac` package is optional; install it with:
+
+```bash
+pip install petfishframework[vault]
+```
+
+## Security Notes
+
+- Keep images small: only production dependencies are installed (`--no-dev`).
+- Do not commit API keys, tokens, or `.env` files to version control.
+- Mount credential files as read-only volumes or Docker secrets.
+- Run the container with the least-privilege user when possible:
+
+  ```dockerfile
+  RUN useradd -m appuser
+  USER appuser
+  ```
+
+- Event logs may contain sensitive arguments. Enable `MASK` policies to
+  redact PII and secrets from audit events.
+- For Vault, use short-lived tokens and rotate them via your orchestrator.
+
+## Health Checks
+
+Add a simple health check to long-running services:
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD python -c "import petfishframework; print(petfishframework.__version__)" || exit 1
+```
+
+## Next Steps
+
+- See [architecture.md](architecture.md) for runtime design.
+- See [threat-model.md](threat-model.md) for security boundaries.
+- See [api.md](api.md) for the full API reference.

petfishframework-0.4.0/docs/release-protocol.md

@@ -0,0 +1,86 @@
+# petfishFramework — 强制发布协议
+
+> 这不是建议清单。这是**每次发布必须执行的门禁脚本**。
+> 不执行完不能打 tag。不执行完不能 push。
+
+## 自动化脚本：`scripts/pre_release.py`
+
+**每次发布前运行**：`python scripts/pre_release.py 0.3.4`
+
+脚本自动检查：
+
+1. **版本号一致性**（6 处）：
+   - pyproject.toml version
+   - __init__.py __version__
+   - api.md 标题版本号
+   - README badge URL 数字
+   - README badge 文本数字
+   - CHANGELOG 最新条目版本号
+
+2. **文档完整性**：
+   - grep 新增模块名在 api.md 中是否存在
+   - grep CHANGELOG 中是否有当前版本条目
+   - README roadmap "current" 是否指向当前版本
+
+3. **测试 + lint**：
+   - pytest 全通过
+   - ruff check 通过
+
+4. **API 闭合检查**（人工确认）：
+   - 新功能是否在 Agent 或 Session 上有用户面参数？
+   - 新功能是否有 api.md 章节？
+   - 新功能是否有 CHANGELOG 条目？
+
+退出码 0 = 可以发布；非 0 = 必须修复。
+
+## 发布 SOP（严格顺序）
+
+```
+1. python scripts/pre_release.py <version>
+   ↓ (必须 exit 0)
+2. uv run pytest tests/ -q
+   ↓ (必须全通过)
+3. uv run ruff check src/ tests/ examples/
+   ↓ (必须 All checks passed)
+4. git add -A && git commit -m "release: v<version>"
+5. git push origin master
+6. git tag v<version>     # 必须有 v 前缀！
+7. git push origin v<version>
+8. 等待 CI + Publish 双绿
+9. 验证 https://pypi.org/project/petfishframework/<version>/
+```
+
+## 版本号同步检查表（每次必查）
+
+| 位置 | 检查命令 | 预期 |
+|---|---|---|
+| pyproject.toml | `grep "^version" pyproject.toml` | `version = "X.Y.Z"` |
+| __init__.py | `grep "__version__" src/petfishframework/__init__.py` | `__version__ = "X.Y.Z"` |
+| api.md 标题 | `head -3 docs/api.md` | `vX.Y.Z` |
+| README badge URL | `grep "badge/tests" README.md` | URL 含正确测试数 |
+| README badge 文本 | `grep "Tests:" README.md` | 文本含正确测试数 |
+| CHANGELOG | `head -10 CHANGELOG.md` | `## [X.Y.Z]` 在顶部 |
+
+## 新功能检查表（每次加功能必查）
+
+| 检查项 | 命令 | 预期 |
+|---|---|---|
+| Agent 参数 | 新功能是否在 `Agent.__init__` 有对应参数？ | 用户能一行配置 |
+| Session 传递 | Agent 参数是否传到 Session → Environment？ | 全链路通 |
+| api.md 章节 | `grep "<新类名>" docs/api.md` | 有匹配 |
+| CHANGELOG 条目 | `grep "<版本号>" CHANGELOG.md` | 有条目 |
+| TDD 测试 | `pytest tests/test_<新功能>.py` | 通过 |
+| 安全边界 | 负面测试：无配置时是否安全降级？ | 不崩溃 |
+
+## 绝不再犯的错误清单
+
+| # | 错误 | 防止机制 |
+|---|---|---|
+| 1 | 忘记更新 api.md 版本号 | pre_release.py 自动检查 |
+| 2 | Badge URL 和文本不一致 | pre_release.py 自动检查 |
+| 3 | CHANGELOG 缺当前版本条目 | pre_release.py 自动检查 |
+| 4 | 功能只在内部 hook，Agent 无入口 | 新功能检查表：Agent 参数 |
+| 5 | 安全语义只在正常路径验证 | TDD 必须包含 known-bad（side-effect tracking） |
+| 6 | tag 无 v 前缀 | 发布 SOP 第 6 步明确 v 前缀 |
+| 7 | 新功能无 api.md 章节 | 新功能检查表 |
+| 8 | 使用 twine/token | 已撤销；Trusted Publishing only |