插件与生态索引（v0.26.0）¶

phase-barrier 通过 Python 入口点（entry points）支持五类插件：

入口点组	作用	参考实现
`phase_barrier.languages`	自定义语言适配器	`examples/custom_adapter/`
`phase_barrier.validators`	自定义阶段校验器（覆盖内置）	`examples/plugin_rules/`
`phase_barrier.interceptors`	自定义拦截规则	`examples/plugin_rules/`
`phase_barrier.semantic_validators`	语义级校验器（需求追踪 / 变异测试 / spec 具体性 / 断言质量 / 实现追踪 / LLM 审查等，v0.49.0 起）	`examples/semantic_llm_check/`
`anti_shortcut.integrations`	Agent 集成插件（自动装回包装后的工具）	`examples/orchestrator_hooks/`

自动收录（v0.46.0）：索引数据由 plugins.json 承载、每周自动验证工作流维护，已收录插件的实时状态表见插件状态页。若希望你的插件被自动收录，请给仓库添加 phase-barrier-plugin 主题，并确保可通过 python -m anti_shortcut plugin-verify 验证（入口点全部通过）；详见下文「提交到索引 / 自动收录」与「自动发现脚本」。

5 分钟创建你的第一个插件¶

目标：从零做出一个能被 plugin-verify 验证、并能被索引自动收录的插件。四类入口点（语言适配器 / 校验器 / 拦截规则 / 集成插件）任选一类即可开始。

第 0 步 · 生成骨架（30 秒）

推荐用官方模板仓库一键生成：打开 phase-barrier-plugin-template，点右上角 Use this template 创建你自己的仓库（模板已内置四类入口点示例与 plugin-verify CI）。不想要模板也没关系——手写一个包目录 + pyproject.toml，下一步就是全部内容。

第 1 步 · 声明入口点（2 分钟）

# pyproject.toml
[project]
name = "my-phase-barrier-plugin"
version = "0.1.0"
dependencies = ["phase-barrier>=0.52"]

[project.entry-points."phase_barrier.languages"]
mylang = "my_plugin:MylangAdapter"

# my_plugin/__init__.py
from anti_shortcut import LanguageAdapter


class MylangAdapter(LanguageAdapter):
    name = "mylang"
    file_extensions = [".mylang"]
    source_file_patterns = ["*.mylang"]
    test_file_patterns = ["test_*.mylang"]

    def check_syntax(self, path):
        return True, "语法检查通过（示例插件）"

第 2 步 · 本地验证（1 分钟）

pip install -e .
python -m anti_shortcut plugin-verify --json     # 期望 "ok": true

plugin-verify 会扫描当前环境注册的全部入口点并逐个加载，失败时会直接指出是哪一类、哪个名字，比等到 Agent 跑起来才报错快得多。

第 3 步 · 让索引自动收录（1 分钟）

给插件仓库加 topic：Settings → Topics → phase-barrier-plugin；
在插件仓库 CI 里跑 python -m anti_shortcut plugin-verify（模板仓库已内置）；
等每周一 03:00 UTC 的 plugin-verification.yml 自动执行 git clone → pip install -e → plugin-verify，通过后即以 auto_discovered: true 写入 plugins.json 并同步到插件状态页。想立刻看到结果，可在主仓库 Actions 里手动 workflow_dispatch 触发一次。

不想打 topic 也可以走人工提交，见下文「提交到索引 / 自动收录」。

第 4 步 · 校验收录结果（30 秒）

plugins.json 中出现 "name": "<owner>/<repo>" 且 "status": "passed"；
插件状态页的表格新增一行；
之后每次向该仓库推新提交，下一个周期会用 git ls-remote 比对 last_commit_sha 做增量刷新（新增 / 变化的入口点也会同步）。

收录没成功？失败原因会写进 plugins.json 的 status: "failed" 与发现报告 artifact（plugin-discovery-report.json）。常见原因：入口点名字写错、 install 目标与包名不一致、干净环境下 pip install 失败。

开发模板¶

推荐：官方模板仓库 独立模板仓库 phase-barrier-plugin-template 点 GitHub 右上角 Use this template 一键生成插件仓库，内置五类入口点示例、 CI（plugin-verify + pytest）与冒烟测试；下文片段为最小示例，完整模板以该仓库为准。

最小语言适配器插件：

# pyproject.toml
[project.entry-points."phase_barrier.languages"]
my_language = "my_package:MyLanguageAdapter"

# my_package/__init__.py
from anti_shortcut import LanguageAdapter


class MyLanguageAdapter(LanguageAdapter):
    name = "my_language"
    file_extensions = [".xyz"]
    source_file_patterns = ["*.xyz"]
    test_file_patterns = ["test_*.xyz"]

    def check_syntax(self, path):
        return True, "语法检查通过（示例插件）"

安装插件包后，用 language: my_language 或 language_adapter: "my_package:MyLanguageAdapter" 启用。

自定义拦截规则插件：

[project.entry-points."phase_barrier.interceptors"]
my_rules = "my_package:rules"

# my_package/__init__.py
def deny_uploads(kind, target, config, stage, content=None):
    if kind == "write" and "uploads/" in str(target).replace("\\", "/"):
        return False, "禁止写入 uploads/（我的规则）"
    return None

rules = [deny_uploads]

自动验证（v0.29.0）¶

安装插件包后，python -m anti_shortcut plugin-verify 会自动加载并冒烟验证全部五类入口点：语言适配器（name + 必需方法）、校验器（映射 / 工厂）、拦截规则（可调用规则）、语义校验器（name + stages + check()）、集成插件（可调用 / install()）。返回码 0 = 全部通过。

pip install phase-barrier my-plugin
python -m anti_shortcut plugin-verify          # 全部通过时退出码 0
python -m anti_shortcut plugin-verify --json   # 结构化结果（CI 断言用）

插件 CI 模板（一键接入）¶

把下面工作流复制到插件仓库 .github/workflows/ci.yml，每次 push / PR 自动验证：

name: Plugin CI

on:
  push:
    branches: [main, master]
  pull_request:

jobs:
  plugin-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: Xuqing0415/phase-barrier/.github/actions/[email protected]
        with:
          plugin-path: .            # 插件包目录（包含 pyproject.toml）
          python-version: '3.12'
          phase-barrier-version: '' # 留空 = 最新发布版；可固定如 0.29.0

验证通过后可在 README 添加徽章：

[![Plugin CI](https://github.com/<owner>/<repo>/actions/workflows/ci.yml/badge.svg)](https://github.com/<owner>/<repo>/actions/workflows/ci.yml)

提交到索引 / 自动收录¶

第三方插件推荐走自动发现（v0.46.0）：不再依赖人工合并，满足条件即被每周 workflow 自动收录：

用官方模板仓库 phase-barrier-plugin-template 生成插件仓库（Use this template）。
给仓库添加 GitHub topic：phase-barrier-plugin。
接入上面的 插件 CI 模板，保证 python -m anti_shortcut plugin-verify 全绿（入口点可加载、类型与必需接口通过）。
等待周期自动发现（每周一 03:00 UTC，或提 workflow_dispatch 手动触发）；验证通过的插件以 auto_discovered: true 自动进入 plugins.json，并同步到「插件状态页」（见文末链接）。自动收录只校验入口点可用性，不审查代码质量（质量由社区 / Issue 反馈约束）。

不打 topic 的插件仍可走人工提交：

在 GitHub Issues 选择「插件提交（Plugin Submission）」模板，附上：包名 / 仓库链接、支持的入口点组、 CI 状态链接、一段使用示例。
维护者审核后合并到 plugins.json，并运行 python scripts/verify_plugins.py --update --sync-docs 刷新插件状态页。

官方模板仓库（非插件，用于生成插件）¶

phase-barrier-plugin-template：独立模板仓库，Use this template 即可生成；含四类入口点示例（.demo 语言适配器 / 阶段 1 校验器 / vendor 拦截规则 / 集成插件）与语义校验器参考实现（examples/semantic_llm_check/）、examples/demo.py 端到端演示、CI（plugin-verify + pytest）。

第一批索引（官方示例，v0.26.2）¶

以下为本仓库自带的官方示例插件，均可直接复用 / 作为提交模板：

插件	类型	作者	说明
`phase-barrier-foo-adapter`（`examples/custom_adapter/`）	`phase_barrier.languages`	phase-barrier 官方示例	虚构 `.foo` 语言适配器：文件识别 / 语法检查 / 测试统计 / 测试命令识别；演示打包与入口点注册，安装后 `language: foo` 直接启用
`phase-barrier-plugin-example`（`examples/plugin_rules/`）	`phase_barrier.validators` + `phase_barrier.interceptors`	phase-barrier 官方示例	自定义校验器（`strict_design`）+ 拦截规则（`deny_vendor_writes`），安装后自动参与门禁
编排器钩子集成（`examples/orchestrator_hooks/`）	`anti_shortcut.integrations`	phase-barrier 官方示例	任务启动 / 阶段切换钩子调用 `PhaseBarrier`，把包装后的工具装回 Agent

社区第三方插件¶

插件	类型	作者	说明
`Xuqing0415/phase-barrier-plugin-foo-adapter`	`phase_barrier.languages`	自动发现（种子插件，官方维护）	独立仓库形态的 `.foo` 语言适配器，用于演示/验证「打 topic -> 自动收录 -> 增量刷新」全链路
（等待自动发现 / 人工提交）			打 `phase-barrier-plugin` 主题或提 Issue，见「提交到索引 / 自动收录」

索引自动检查（v0.34.1）¶

主仓库新增 .github/workflows/plugin-check.yml：每周一 06:00 UTC 自动运行（也可手动 workflow_dispatch 触发），安装 examples/custom_adapter 与 examples/plugin_rules 两个官方示例插件后执行 python -m anti_shortcut plugin-verify --json，断言 foo（语言适配器）/ strict_design（校验器）/ deny_vendor（拦截规则）等入口点全部通过，并把 JSON 报告作为 artifact（plugin-check-report.json）上传供人工抽查。

说明：

该检查针对本仓库官方示例插件，防止示例随代码演进失效。
第三方插件 的收录（v0.46.0 起）优先走自动发现：GitHub topic phase-barrier-plugin + 插件 CI 全绿 -> plugin-verification.yml（每周一 03:00 UTC）自动 clone / 安装 / plugin-verify，通过即以 auto_discovered: true 写入 plugins.json 并同步插件状态页；不打 topic 的仍走 Issue 模板人工提交。

索引数据文件与自动验证（v0.45.0 / v0.46.0）¶

从 v0.45.0 起，索引不只靠文档表格人工维护，还新增了机器可读的 plugins.json（仓库根目录）与自动验证脚本，方便维护者周期核查已收录插件的兼容性；v0.46.0 起顶层改为容器结构并支持按 GitHub topic 自动发现新插件：

{
  "plugins": [
    {
      "name": "owner/repo",
      "repo": "https://github.com/owner/repo",
      "install": "git+https://github.com/owner/repo.git#egg=repo",
      "entry_points": { "phase_barrier.languages": ["my_language"] },
      "last_verified": "2026-09-05T00:00:00Z",
      "status": "passed",
      "auto_discovered": true,
      "last_commit_sha": "abc123..."
    }
  ],
  "auto_discovery": { "github_topic": "phase-barrier-plugin", "enabled": true }
}

plugins：条目列表（v0.45.x 的顶层数组旧格式仍可读取，写回时自动升级为容器）。
auto_discovery：自动发现开关与使用的 GitHub topic（置 enabled: false 可停用）。
name：插件标识（官方示例用包名，自动收录的第三方用 owner/repo）。
repo：仓库地址（本地示例用相对路径，第三方用 URL）。
install：可被 pip install -e 的目标（本地相对路径 / git+https URL）；缺省回退到 repo。无 install / repo 的占位条目不会自动判定状态。
entry_points：声明该插件应提供的入口点，{入口点组: [名称列表]}；也可用 ["phase_barrier.languages", ...] 简写（只断言组内有可用入口点）。
last_verified / status：最近一次自动验证时间与结果（passed / failed / unverified），由验证脚本按 --update 写回。
auto_discovered / last_commit_sha：是否由自动发现收录 / 收录时验证的提交 SHA（用于后续增量判断），官方示例为 false / null。

验证脚本¶

scripts/verify_plugins.py 负责“索引层”验证：逐个安装索引条目（新进程注册入口点），再在全新子进程中运行 python -m anti_shortcut plugin-verify --json，断言每个条目声明的入口点全部可用：

python scripts/verify_plugins.py                  # 验证并打印摘要（0 = 全通过）
python scripts/verify_plugins.py --update         # 把 status / last_verified 写回
python scripts/verify_plugins.py --update --sync-docs  # 写回状态并同步 docs/plugin-status.md 插件状态页
python scripts/verify_plugins.py --json           # 结构化报告（stdout）
python scripts/verify_plugins.py --no-install     # 跳过安装（插件须已安装）

自动发现脚本（auto_discover_plugins.py，v0.46.0）¶

scripts/auto_discover_plugins.py 负责“发现并收录”：按 GitHub topic 搜索（Search API，token 取 GH_TOKEN / GITHUB_TOKEN / --token），过滤已在 plugins.json 中的仓库；对候选执行 git clone --depth 1 -> pip install -e -> plugin-verify --json 全链路验证，通过则以 auto_discovered: true + last_commit_sha 收录并同步插件状态页；失败只记录原因、不收录（不审查代码）。 v0.47.0 起，已收录的自动条目还会用 git ls-remote 检测远端 HEAD，与 last_commit_sha 不一致时增量重新验证并更新入口点（含新增入口点）：

python scripts/auto_discover_plugins.py               # dry-run：搜索并打印候选
python scripts/auto_discover_plugins.py --update      # 验证候选 / 刷新自动条目并写回 + 同步状态页
python scripts/auto_discover_plugins.py --update --json   # 结构化摘要（stdout）

周期自动验证（plugin-verification.yml）¶

.github/workflows/plugin-verification.yml 每周一 03:00 UTC（可与周一 06:00 的 plugin-check.yml 区分）自动运行两步：

auto_discover_plugins.py --update：按 topic 自动发现并收录新第三方插件，并对已收录自动条目的新提交做增量刷新；
verify_plugins.py --update --sync-docs：全量安装并验证 plugins.json 全部条目（含新收录），刷新状态与插件状态页；

随后上传 JSON 报告 artifact（plugin-verification-report.json / plugin-discovery-report.json），有变更自动提交到 main。验证失败不会静默：失败状态写回 plugins.json 并随提交 / 报告暴露给维护者处置。

plugin-check.yml 继续保留，负责官方示例插件的固定断言；plugins.json 驱动的验证 + topic 自动发现是它的推广形态，第三方插件无需人工合并即可被周期收录（自动收录只校验入口点可用性）。

端到端轮询实证（v0.56.0，实测）：给插件仓库打上 phase-barrier-plugin topic 并通过插件 CI，下一周期即被自动收录 —— 该链路已在真实仓库上闭环验证： phase-barrier-plugin-foo-adapter 被自动发现收录（auto_discovered: true、status: passed）；随后向其推送新提交（ec2a992 -> 175b000）并触发 plugin-verification.yml（run 34477757527，success），机器人提交把索引里的 last_commit_sha 刷新为 175b0002。全程无需人工介入，即「上游新提交 -> git ls-remote 比对 -> 重新 clone / 安装 / 验证 -> 写回索引」。

仓库另内置了不依赖真实第三方的端到端演练：tests/fixtures/plugin_alpha/ （模拟插件）+ tests/test_auto_discover_e2e.py（真实 git 仓库下验证发现 / 增量刷新 / 失败重试）。

插件状态页（自动同步）¶

已收录插件（官方示例 + 自动发现第三方）的实时状态表见插件状态页：由 scripts/verify_plugins.py --sync-docs 从 plugins.json 自动渲染，随周期 workflow 提交更新，无需人工维护。