pyobfus: Instructions file for Claude Code

pyobfus 开发约定

Modern Python Code Obfuscator - 基于 AST 的 Python 代码混淆器。

通用 agent 约定(build/test/lint、仓库结构、专利 gate 等)见根目录 AGENTS.md(规范源,工具无关)。本文件保留 Claude / 中文 / 专利申报相关的项目专属细节。

@AGENTS.md

⚡ Current pending work (cold-start 必读)

Single source of truth for current plan: docs/CURRENT_PLAN_ZH.md — 重启 session 第一份必读

docs/ROADMAP.md 和 docs/POST_V0.4_TODO.md 已归档为历史执行记录和细节来源。日常优先级、外部 blocker、下次工作建议都以 docs/CURRENT_PLAN_ZH.md 为准。

🟢 2026-09-06 — Core 0.5.22 + VS Code 0.4.2 已发布后的当前焦点

• Core 0.5.22（新发布）/ MCP 0.3.10 / VS Code 0.4.2（新发布）为最新公开版本。
• ✅ Core 0.5.22 已于 2026-09-06 发布（用户明确批准）= Python 3.14 remote-debug 硬化 advisory（触发条件方案 A：config.anti_debug 且目标 Python ≥ 3.14 → --check 加一条 compatibility_advisory 类别的 INFO advisory，提示 -X disable_remote_debug/PYTHON_DISABLE_REMOTE_DEBUG=1，诚实说明 anti-debug 注入无法关闭 PEP 768）。tag v0.5.22 经 OIDC + PEP 740 发到 PyPI （latest=0.5.22，wheel/sdist 两个 provenance endpoint 均 HTTP 200）， GitHub Release 已建，Release/CI 全矩阵/CodeQL/Pages 均绿，发布前三测试根 1253+93+7 全过。验证注意点：全新无许可 venv 跑 --check 看不到这条 advisory 是正确行为——anti_debug 是 Pro 功能，无许可时 level 降级为 community；改用直接调 PreflightChecker(protection_intent=True, target_python_min="3.14") 验证发布包，三种组合（3.14 触发 / 3.12 不触发 / 无保护意图不触发）均符合设计。详见 docs/REMOTE_DEBUG_HARDENING.md。
• ✅ vscode-extension 0.4.2 已于 2026-09-06 发布（Security： "Generate pyobfus.yaml" 现在对 CLI 返回的配置路径做 realpath 规范化，要求 文件名为 pyobfus.yaml 且必须落在工作区内，拒绝符号链接逃逸）。53 测试全过、 lint/typecheck/打包干净，tag vscode-v0.4.2 + GitHub Release（附 pyobfus-0.4.2.vsix）已建，且已核实该 tag 未误触发 PyPI Release workflow（08-04 tag-glob 修复仍有效）。Marketplace 手工上传已由用户完成，curl 核实公开 listing 已返回 "version":"0.4.2"。
• ⏸️ pyobfus-mcp 0.3.11 刻意未发：[Unreleased] 只有一条元数据 URL 修复， 无功能影响；而 Glama admin「Build steps」不会自动跟版，每发一版都要维护者手工 改一次，且其构建当前仍在连续失败。等下次 MCP 有实质改动再一起发。
• ✅ Core 0.5.21 已于 2026-09-04 发布（用户明确批准 push+tag）= SARIF preflight + 两个 cross-file/preset bug 修复。tag v0.5.21 经 OIDC + PEP 740 发到 PyPI（latest=0.5.21，两个 provenance endpoint HTTP 200），全新 venv 安装已核实带 --sarif，GitHub Release 已建，Release/CI 全矩阵/CodeQL 均绿。 SARIF pyobfus --check --sarif PATH 是纯 projection，不改 detection/severity/ exit code。两个 bug：默认 cross-file 目录模式此前静默丢弃全部内容级变换（含 commercial/library 等 Pro preset），以及 --level 默认值把 preset 的 pro level 覆盖回 community——均已修（统一到 pyobfus/core/content_transforms.py
  • --level 改 tri-state）。发布后 main CI 曾因一处脆弱测试断言在单个 Py3.14 job 红一次（numeric-obfuscation 目录模式用子串 = 42 检查被随机 XOR 分量前缀 误中），已改为 AST 断言（commit 1e62674）后转绿；发布 wheel 不受影响，未重发。 验收见 docs/V0.5.21_RELEASE_PLAN.md。 Community build marker 仍是已设计但 gated 的 P2，未随 0.5.21 发布。
• 本轮还重写了废弃的 docs/INTEGRATION_TESTING.md、修了两处文档死链、补录三个 已发布 Community flag（--numeric-obfuscation/--strip-ai-artifacts/ --incremental）到 README/llms/index。逐轮明细见 docs/CURRENT_PLAN_ZH.md。
• self-dogfooding 采用 audit/manual → N-1/N canary → wheel verification 的分阶段 路线；不把公开 Core/Pro wheel 自混淆。规范见 docs/SELF_DOGFOODING_BEST_PRACTICES.md。
• Canopii 已显示 publisher/maintainer verified；合理的 VS Code/Worker 安全加固 已完成并推送，monorepo scope、v0.3.10 stale scan 与 8 tools 未提取已报 canopii-cli#6。后续只按 CURRENT_PLAN P0 跟踪回复/重扫；14 天无回复 follow up 一次。MCP Trust Checker 登记仍待执行，Claude plugin 仍 pending。
• 下载数据当前只到 08-31；等 pypistats 覆盖至少 09-02 再评价 09-01 SEO 发版。无新需求信号，不拆 dependency_advisory、不刷 trust score。
• 冷启动先核实 git status、origin/main、Actions 与 #6 实时状态；不要依赖 下方历史段冻结的旧版本/commit/外部状态。