插件系统与项目护栏
插件提供仅靠提示词无法实现的运行时强制与工作流。以下全部随安装默认启用 —— 无需额外安装。
插件总览表
| 插件 | 对你的作用 |
|---|---|
project-profiler.ts | 启动时探测语言与激活的 MCP 后端，向系统提示词注入代码智能指引与检索铁律 |
design-token-guard.ts | 阻止写入硬编码的颜色/间距/圆角 —— 让前端代码坚守设计令牌 |
ai-slop-scanner.ts | 警告前端文件中的 AI 反模式（渐变汤、div 汤等） |
usage.ts | /usage TUI 命令打开宽度自适应的弹框，顶部常驻 tab 条：按会话（每会话一行 + 总计）、按 Agent、按模型 —— 展示非缓存输入/输出/缓存输入 token、费用、缓存命中率、占比条；1/2/3 或 ←→ 实时切换 tab，Enter 关闭；↑/↓ 滚动长表格（tab 条、警告、表头、总计与脚注固定不动）；/usage all|agent|model 直接打开对应维度；宿主无弹框 API 时降级为 toast（仅 TUI 会话） |
auto-format.ts | 文件编辑后自动运行项目选择的 dprint/Biome/Prettier/ESLint/Ruff/gofmt/rustfmt；dprint 与 Biome 均要求配置文件和项目本地二进制 |
auto-advisor-mode.ts | /auto-advisor 命令、协议注入、模式门控、red-team 抑制 |
deepseek-anchor.ts | /deepseek-anchor 命令 —— 基于锚点的推理协议与 DeepSeek 模型集成 |
adr.ts | /adr 命令族 —— ADR 工作台 + 按项目提交门禁（/adr guard） |
env-guard.ts | 按项目的密钥文件门控 |
e2e-adopt.ts | /e2e-adopt 命令 —— 将 E2E 红线政策采纳进项目文档（docs/e2e-redline.md + AGENTS.md 小节）；文档治理，无运行时闸门 |
project-manager.ts | /project 命令 + 提交纪律 |
project-memory.ts | /memory 命令 —— 项目级记忆：在 .ocp/memory/public.md（团队）或 private.md（gitignored）里记录经验教训，并在每次聊天请求时以 [PROJECT MEMORY] 注入。LLM 可通过 memory_note 工具主动记录；/memory-summarize skill 用于 session 总结 |
profile-wizard.ts、provider-wizard.ts、project-wizard.ts | /profile、/provider 与 /project TUI 弹窗向导；未配置现有 formatter 的新 Node 项目可明确选择配置项目本地 dprint |
md-to-pdf.ts | /md-to-pdf 命令与 md_to_pdf 工具 —— 将 Markdown 一键导出为高质量 A4 PDF（基于 Pandoc + Playwright） |
md-to-docx.ts | /md-to-docx 命令与 md_to_docx 工具 —— 将 Markdown 导出为出版级 Word (.docx) 文档（宋体/黑体排版、自动TOC、智能表格与代码美化） |
工作流命令不是插件。
/dev-quick、/dev-plan、/dev-review、/dev-ultra、/dev-prud、/dev-deep、/review-fix-loop、/improve-loop、/grill-me、/grill-with-docs、/goal、/handoff是 opencode 原生命令文件（commands/*.md）：薄发射器，按需从 L2 技能（skills/<name>/SKILL.md）加载协议正文——每次调用只付费一次，永不常驻。详见工作流斜杠命令与五档开发流。
ADR 铁律与活化架构治理（adr 与 /adr）
企业级架构决策记录（ADR）治理体系，由两大互补能力构成：
- 提交铁律门禁（
/adr guard） — 软/硬双层护栏，杜绝在feat/refactor提交中出现未记录的架构漂移。 - 分层活化架构引擎（
/adr） — 极简脚手架、决策生命周期流转、多层级拓扑与 Mermaid DAG 可视化。
开关与治理布局
提交门禁开关为项目级（存储于 .ocp/ocp.json）：
/adr guard on # 对本项目启用提交门禁拦截
/adr guard off # 关闭提交门禁
/adr guard # 状态报告（开关 + ADR 目录）分层治理布局通过 /adr layout 进行配置：
/adr layout # 查看当前布局 (auto | flat | hierarchical)
/adr layout flat # 极简纯扁平单层布局 (仅 docs/adr/)
/adr layout hierarchical # 严格分层布局 (强制 L1/L2/L3 多层划分)
/adr layout auto # 智能自适应布局 (默认: 单体项目保持扁平，出现子包时自动拓展)Slash 命令族（/adr）
| 命令 | 说明 | 示例 |
|---|---|---|
/adr [new] [layer/scope] <title> [--empty] | 自动计算序号生成 MADR 骨架并自动唤醒 AI 结合代码库起草正文（可省略 new，加 --empty 仅生成空骨架） | /adr "采用 PostgreSQL 作为主库" 或 /adr new "采用 PostgreSQL 作为主库" |
/adr supersede <old-id> <new-title> [--empty] | 原子化将旧 ADR 标记为 superseded，生成新决策并自动唤醒 AI 编写演进论证 | /adr supersede 0001 "从 RabbitMQ 迁移至 NATS" |
/adr migrate [h|f|a] [--confirm] | 预览或执行 ADR 架构目录结构双向自动化重构 | /adr migrate h |
/adr migrate --to nygard|madr [--dry-run|--confirm] | 显式样式转换：确定性 dry-run 报告（源/目标路径、记录 ID 映射、链接重写、内容丢弃警告）；未经 --confirm 绝不写入 | /adr migrate --to nygard |
/adr tree / /adr map | 生成 Markdown 决策层级树与 Mermaid DAG 依赖图 | /adr tree |
/adr tree --by path|layer|domain|iteration | 基于规范化记录的确定性逻辑视图（跨样式安全） | /adr tree --by domain |
/adr history <ADR-ID> | 遍历取代链（前驱 + 后继，跨样式安全） | /adr history ADR-0.2.54.01 |
/adr context <ADR-ID> / --domain <slug> / --iteration <id> | 有界上下文包：仅目标记录 + 直接父决策/取代链/同迭代关系，并披露检索路径 —— 绝不倾倒全量语料 | /adr context ADR-0003 |
/adr check / /adr lint | 审计引用完整性、父子决策断链及复杂度升级建议 | /adr check |
/adr check --report-style | 样式审计：列出每份文档的解析样式与 legacy 标记（无 style frontmatter 的文件按 MADR 解析）；仅报告，绝不写入 | /adr check --report-style |
渐进式披露：生成索引与上下文恢复
每个 ADR 目录都会自动生成与目录树镜像的 INDEX.md：本地索引仅列出本目录记录 + 子目录摘要（含父级链接），ADL 根索引优先展示全局/系统级记录。再生成是确定性的（字节稳定），且生成文件会声明“请勿手改”。使用路径为：读索引 → 筛选相关行 → 深入选中的正文 —— /adr context 以同一算法程序化执行，并报告它读取了哪些索引与记录。
1. 创建新决策（/adr 或 /adr new）
- 基础用法（自动 AI 起草，支持直接传需求标题）：text自动在
/adr "Use PostgreSQL as Primary Database" # 或： /adr new "Use PostgreSQL as Primary Database"docs/adr/创建下一个自增编号文件（如0003-use-postgresql-as-primary-database.md），填充标准 MADR 骨架，并自动更新INDEX.md索引表，随后自动触发 AI 调研代码库并编写完整决策正文。 - 纯骨架模式（仅生成占位模板，不调用 AI）：text
/adr "Use PostgreSQL as Primary Database" --empty - 分层用法（多包 / Monorepo）：text
/adr new system "Global Event Bus Standard" # L1 宏观决策（根目录 docs/adr/） /adr new domain/payment "Stripe Webhook Processing" # L2 领域决策（packages/payment/docs/adr/） /adr new component/auth "JWT Refresh Rotation" # L3 模块决策
2. 替代废弃旧决策（/adr supersede）
架构决策不可随意篡改历史，方案演进必须通过 supersede 记录演进原因：
/adr supersede 0001 "Migrate from RabbitMQ to NATS JetStream"系统原子化自动完成：
- 旧决策（
0001）状态更新为status: superseded by 0004并注明废弃原因； - 新决策（
0004）自动创建，Frontmatter 自动关联parent: docs/adr/0001-use-rabbitmq.md； - 自动同步刷新目录下的
INDEX.md； - 自动唤醒 AI 结合历史决策与代码上下文，编写新 ADR 的方案对比与替代理由（若加
--empty则仅生成骨架）。
3. 自动化重构与迁移（/adr migrate）
随着项目规模扩大，随时可以无痛双向重构 ADR 结构：
- 目录结构预览（Dry-Run）：
/adr migrate h（或/adr migrate hierarchical），输出文件移动映射表，不修改任何文件； - 目录结构执行：
/adr migrate h --confirm，自动迁移文件、重写 frontmatter 与相互引用，并刷新全仓索引。 - 样式转换：
/adr migrate --to nygard|madr逐条报告 —— 源路径、目标路径、永久冻结的记录 ID 映射、链接重写清单与不可转换内容警告（MADR 独有的 Considered Options 等章节在 Nygard 中无对应位置，将被丢弃；Nygard → MADR 无任何内容丢失）。默认为 dry-run；未经--confirm绝不写入，转换后的文档会校验其确实可按目标样式重新解析。ID、created、date、状态与引用均原样保留。
双模交互：自然语言与 Slash 命令
ADR 治理系统支持 Slash 命令（确定性脚手架 + AI 接力） 与 纯自然语言交互 双模并行：
| 场景 | 自然语言交互 | Slash 命令（确定性路径 + 索引保障） |
|---|---|---|
| 新建决策 | “帮我记录一个关于引入 Redis 做分布式锁的 ADR” → AI 调研背景、列出候选方案对比、填充论证并落盘 | /adr 引入 Redis 做分布式锁→ 秒级分配自增序号与索引，随后 AI 自动填充内容 |
| 仅生成模板 | “帮我生成一个 ADR 模板，我自己手写” | /adr 引入 Redis 做分布式锁 --empty |
| 废弃/替代 | “0001 号决策废弃掉，我们现在改用 Kafka 代替 RabbitMQ” | /adr supersede 1 "迁移至 Kafka" |
| 健康体检 | “帮我看看目前 ADR 依赖关系有没有断链，有没有缺失的字段” | /adr check |
| 架构重构 | “项目拆成 Monorepo 了，帮我把支付和用户相关的 ADR 移到各自子包” | /adr migrate h --confirm |
三层架构决策模型（从粗到细）
- L1: 宏观系统级 (
layer: system) — 根目录docs/adr/（全局技术栈、通信协议、系统安全体系）。 - L2: 领域子系统级 (
layer: domain) —packages/<name>/docs/adr/或apps/<name>/docs/adr/（业务服务边界、领域状态机、分库分表）。 - L3: 组件模块级 (
layer: component) — 模块内部docs/adr/（局部复杂算法、前端状态管理）。
密钥文件门控（env-guard）
按项目可选的门控机制，防止含敏感信息的 env 文件进入 LLM 上下文。开关为项目级，默认关闭：
/env-guard on # 对本项目启用（<project>/.ocp/ocp.json 中 "envGuard": "on"）
/env-guard off # 关闭
/env-guard # 状态报告启用后，在执行前阻断针对 .env、.env.local、.env.production 等敏感文件的文件读取工具及读取到输出的 shell 命令。
E2E 红线采纳（e2e-adopt）
把项目的 E2E 红线政策脚手架进项目自己的文档 —— baijiu-shop 式文档治理，无运行时开关与闸门（已退役的 e2e-guard 插件的继任者）：
/e2e-adopt # 检测 E2E 环境 → 写入 docs/e2e-redline.md + AGENTS.md 红线小节
/e2e-adopt dry # 仅预览检测结果与待填占位符，不写任何文件
/e2e-adopt status # 报告政策是否已采纳检测会预填模板（包管理器、e2e 脚本、spec 目录、runner 配置）；检测不到的值保留为 {{...}} 占位符，由手工补全。采纳的政策包含四个核心要素：风险分级三档（轻量 / 定向 / 全量）、确认环（任何 E2E 运行前先问用户；当轮明确要求视为已确认；拒绝则暂停提交）、触发纪律（仅在 commit/push 时点考虑 E2E）、覆盖强制（feat/API 改动须有相称的 E2E 覆盖并同批提交）。卸载 = 删除 docs/e2e-redline.md 和 AGENTS.md 中的 <!-- e2e-redline --> 小节。
项目记忆（project-memory）
轻量、按项目的"经验教训"记忆 —— 与 AGENTS.md（人工整理的项目事实，权威）和 opencode-mem（自动捕获的会话历史，更重、粒度不同）互补。存储在项目内 <projectDir>/.ocp/memory/ 下，跟 .ocp/handoffs/、.ocp/logs/、.ocp/recovery/ 同惯例。两个 scope，一个开关：
/memory note "<经验>" # 追加一条带日期条目到 public.md（默认，进 git）
/memory note --private "<笔记>" # 追加到 private.md（gitignored，仅当前用户可见）
/memory on | off # 切换是否把两个文件注入系统提示
/memory status # 开关状态 + public/private 条目计数
/memory show # 预览当前注入内容（条目 + 最后修改时间 + 过期提示）
/memory-summarize # LLM 扫描会话并提取值得记录的经验文件名直接体现可见性：
public.md—— 进 git，通过常规 PR 流程由团队把关（同 AGENTS.md 权威等级）。private.md—— gitignored，仅当前用户可见。首次捕获时自动写入.ocp/.gitignore。
默认 scope 是不对称的（ADR-2.0.2#01）。/memory note 命令默认 public —— 人手动敲这条命令是明确、可见的动作；而面向 agent 的 memory_note 工具默认 private，要进团队文件必须显式传 scope: "public"。取舍依据是代价：错判 private 只损失一条你自己也看不到的笔记，错判 public 则污染仓库、并被注入之后每一个 session。旧 rationale（"拿不准就 public，PR 会打回"）不成立 —— agent 写的文件当时根本不一定在任何 diff 里，没有任何环节会审它。public 条目是要进 git 的仓库内容：用英文写，一条一规则。
.gitignore 里一条宽规则可能悄悄让 public.md 不再共享（常见成因：仓库把整个 .ocp/ 目录排除了），因此 /memory status 会探测 git check-ignore，在公开条目永远出不了本机时给出警告。探测是三态的 —— git 缺失 / 非仓库等致命退出时保持沉默，不制造假警报。
无草稿 / 策展分层 —— 每条记录直接落地在 gate 注入的那个文件里。LLM 还有 memory_note 工具可以主动调用（发现 reusable rule 时），session 总结用 /memory-summarize skill（让模型挑选）。projectMemory 开启且任一文件非空时，其内容以 [PROJECT MEMORY] 块追加进系统提示（分 === Public === 和 === Private === 两段）—— 仅建议性质：冲突时以 AGENTS.md 为准。每段超过 16000 字符上限时，该段改为指针块、不注入正文，请及时精简。默认开启（文件为空时是 no-op，侧栏显示 ON · empty 提示去 /memory note）。设计文档：docs/plan/project-memory.md。
使用示例
用户命令（/memory note）：
# 1. 团队可见的规则 —— 发现一条，记下来
$ /memory note "this repo uses pnpm not npm — package.json has pnpm-lock.yaml"
[project-memory] Noted to /…/.ocp/memory/public.md — entry is live in memory (团队 scope)。
# 2. 个人笔记 —— 仅你需要
$ /memory note --private "VPN 慢，API 调用 timeout 设 60s"
[project-memory] Noted to /…/.ocp/memory/private.md — entry is live in memory (个人 scope)。
# 3. 调试其他提示词时临时关闭注入
$ /memory off
$ /memory on
# 4. 状态 —— 开关 + 两个 scope 的计数
$ /memory status
[project-memory] gate: on — public: 3 条, private: 1 条. 注入 ACTIVE.LLM 主动调用（memory_note 工具）—— 看到 reusable rule 时。scope 默认为 private，所以进团队文件是一次显式选择：
# 代码 session 进行中，LLM 调：
memory_note({ lesson: "use bun not node", scope: "public", confidence: "high" })
→ {
title: "Memory noted (public, high)",
path: "<projectDir>/.ocp/memory/public.md",
metadata: { path, scope: "public", confidence: "high", confidenceRank: 3, lesson }
}Session 总结（/memory-summarize skill）—— session 收尾时，可选带 focus：
# 整段 session 总结（两个 scope，所有主题）
$ /memory-summarize
## Memory summary
**Captured 3 lesson(s)**.
- public (2): this repo's CI needs --no-sandbox on Windows;
OpenCode plugin API requires client at registration time
- private (1): user prefers dark-mode editor
**Skipped** (counts only — no list):
- session-specific: 4
- already in AGENTS.md: 1
- speculative: 1
# 聚焦提取 —— 只挑 API 相关的，且只 team memory
$ /memory-summarize "API quirks" --public
## Memory summary
**Captured 2 lesson(s) [filter: public] [focus: "API quirks"]**.
- public (2): OpenCode plugin API requires client at registration time;
scopedForTool needs both sessionID and agent for subagent detection
**Skipped**:
- session-specific: 4
- off-topic for "API quirks": 3
- already in public.md: 1
# focus 没匹配上 —— 显式报告无匹配（不悄悄扩大范围）
$ /memory-summarize "error handling patterns"
## Memory summary
**No lessons matched focus "error handling patterns". Drop the focus to capture the full session.**与 scope flag 组合 —— focus 与 --public/--private 正交：
$ /memory-summarize "workflow lessons" --private # workflow 相关经验，只记个人笔记
$ /memory-summarize "gotchas we hit" # 匹配 focus 的所有主题，两个 scope 都可工具 gate 行为：
# title-generator utility session 尝试调用：
memory_note({ lesson: "x" }, ctx: { agent: "title-generator" })
→ {
title: "Memory note denied",
output: "memory_note is not available in this agent context (title-generator). …",
metadata: { denied: true, agent: "title-generator", … }
}
# （工具 gate 和 system-inject 都 deny。title 任务发现不了 reusable rule —— 拒绝以防污染。）
# advisor subagent 记下真实项目怪癖：
memory_note({ lesson: "auth middleware swallows JWT errors" }, ctx: { agent: "advisor", sessionID: "sub-1" })
→ 成功（subagent 确实学到了值得记的东西）超出上限（每段 16 000 字符）：
# public.md 超过 cap → 该段改为指针块：
# [PROJECT MEMORY]
# === Public ===
# /…/public.md is 18500 chars — over the 16000-char injection cap, so it is NOT in
# your context. Read /…/public.md when making decisions it could affect, and ask
# the user to prune/summarize stale entries.
# === Private ===
# (正常注入 —— private.md 较小)
# 逐段独立：private.md 涨爆不会让 public 沉默，反之亦然。提交纪律（project-manager）
按项目的提交规范强制机制，采用文件即开关：无状态文件、无 on/off 命令 —— docs/git-commits.md 存在即生效。
/project init # 迁移旧状态后生成基线文件（.ocp/ocp.json、docs/git-commits.md、AGENTS.md）
/project index # 手动刷新已有索引：codegraph sync、gitnexus analyze
/project sync # 按需重跑一次性旧状态迁移（幂等）docs/git-commits.md 存在期间：
- commit 首行须匹配
type(scope): summary（type 限 feat、fix、refactor、docs、test、chore、perf、ci、build、style、revert）且 ≤ 72 字符。
文档导出与排版渲染（md-to-pdf 与 /md-to-pdf）
将项目中的 Markdown 文档（API 规范、ADR 方案、调研报告）一键导出为出版级高保真 A4 PDF。
核心能力
- 自然语言直接驱动：在聊天框发送
@doc/api-v1.md 转PDF或帮我把 @README.md 导出为 PDF，智能体自动提取路径并调用md_to_pdf工具完成生成。 - Slash 命令确定性执行：text
/md-to-pdf README.md # 渲染为 README.pdf /md-to-pdf doc/api-v1.md dist/api-v1.pdf # 指定输出路径 /md-to-pdf --doctor # 环境与依赖健康检查 /md-to-pdf --install-deps # 自动修复/安装缺失依赖 - 工业级排版与隔离打印：
- Pandoc 引擎：生成符合 GFM 规范的 standalone HTML，内置代码高亮与资源内联。
- 优雅 A4 样式：A4 页面、页边距、现代化字体族、代码块及表格自适应边框。
- Playwright 无头打印：通过隔离 Node runner 驱动 Chromium 打印矢量 PDF，保证毫秒级生成。
Word 文档排版与导出（md-to-docx 与 /md-to-docx）
将项目中的 Markdown 文档（技术方案、PRD 需求、ADR 决策、会议纪要）一键导出为符合专业出版标准的行政级 Word (.docx) 文档。
核心能力
- 自然语言直接驱动：在聊天框发送
@docs/design.md 转word或将 @README.md 导出为 docx，智能体自动调用md_to_docx工具。 - Slash 命令交互：text
/md-to-docx README.md # 导出为 README.docx /md-to-docx docs/design.md dist/design.docx # 指定输出路径 /md-to-docx doc/whitepaper.md --style=custom-theme.css # 显式指定自定义样式表 /md-to-docx --doctor # 检查 Pandoc 与 Playwright 状态 /md-to-docx --install-deps # 自动补齐缺失依赖 - 纯 TypeScript 架构：彻底告别 Python 环境与脚本依赖，采用纯 TS / Node.js 实现 100% OpenXML 深度排版与美化。
- 100% 样式表驱动（CSS）：
- 支持通过 CSS 样式表（
:root变量与标准选择器）控制全部排版参数（版心几何、色彩体系、字号、行高、边框、斑马纹等）。 - 项目级专属配置：优先自动加载
.ocp/md-to-docx.css与.ocp/md-to-docx.docx模板。
- 支持通过 CSS 样式表（
- Mermaid 出版级图表系统：
- 离线秒级渲染：内嵌本地离线 Mermaid 引擎，零网络延迟与零外网依赖。
- 300+ DPI 视网膜高清：大视口 + 3x 设备像素比超高清生成，图片自动等比扩展为 100% 满版心宽度居中展示。
- 统一现代浅蓝商务风格：消除所有图表类型的黑块与黑条，统一实体浅蓝卡片（
#F0F7FF）、科技蓝连线与箭头（#2563EB）、曜石深黑文字（#0F172A）与白底圆角药丸标签。 - 全图表类型深度覆盖：全面统一架构图（Flowchart）、状态机（State Diagram）、时序图（Sequence Diagram）、实体关系图（ER Diagram）等。
- 100% 样式表完全化：所有图表颜色、字体与线条均由 CSS 变量（
--mermaid-*）动态驱动。
- 行政级出版排版体系：
- 中英文标准双字体：正文标准五号 10.5pt（西文 Times New Roman + 中文 宋体 SimSun）、标题（Segoe UI Semibold + 黑体 SimHei）、代码（Cascadia Code + 微软雅黑）。
- TOC 目录中文化：自动提取 1~2 级标题生成中文化居中目录，支持 Word 动态更新域与点线对齐。
- 顶级表格美化：100% 满宽自适应排版、字数自适应列宽、紧凑匀称表头高度（0.74cm）、清除单元格多余段前段后间距、皇家深海蓝表头（#1E3A8A）+ 偶数行浅冰蓝斑马纹（#F8FAFC）+ 细线边框。
- 代码块美化：等宽 Cascadia Code 字体 (9.5pt)、极淡冷灰底色 (#F8FAFC)、细边框与紧凑行距。
外部 NPM 插件与桥接生态
除了内置的 TypeScript 源码插件外，本项目还集成了经过严格兼容性验证的外部 NPM 插件体系。这些插件通过 install/options.jsonc 的 plugin 块声明（控制 opencode.jsonc 中 plugins 数组的成员资格）；v2 运行时在服务启动时立即加载已缓存的包插件，并在后台安装缺失的包。
| 插件名称 | 默认状态 | 说明与前置要求 |
|---|---|---|
opencode-qoder-bridge | 可选 (false) | Qoder 官方桥接：通过官方 @qoder-ai/qoder-agent-sdk 自动注入 qoder 服务商与全部模型（需 qoder login）。 |
opencode-mem@2.24.3 | 可选 (false) | 持久化向量记忆库：基于本地向量库记录项目历史背景（空闲时会发起额外的轻量 LLM 提炼调用）。 |
若需开启可选插件，只需在 install/options.jsonc 中将其设为 true 并重新运行安装脚本即可。