osovv/vv-opencode
GitHub: osovv/vv-opencode
一个便携的 OpenCode 工作流工具包，通过受管 agent 系统、spec-to-code 流水线和六大插件实现 AI 辅助开发的一键规范化编排。
Stars: 6 | Forks: 0
# @osovv/vv-opencode
**便携的 OpenCode 工作流工具包** —— 一条命令即可初始化受管 agent 生态系统、基于技能的 spec-to-code pipeline、安全与生产力插件，以及统一的 CLI。
/spec.xml
│ Grill-me interview (one question at a time)
│ Decision tree with recommended answers
│ Deep synthesis by expensive model (no sub-agent delegation)
│ Optionally creates .vvoc/specs//design-context.xml
│ for complex sessions (design memory, not requirements)
│
├── ① Spec review: requirements correct, complete, unambiguous?
│
▼ auto-trigger (after approval)
vv-plan ───────────────────────────────────────→ .vvoc/specs//plan.xml
│ Reads sibling design-context.xml when present (explanatory only)
│ Interface contracts with JSDoc behavior descriptions
│ Acceptance criteria per task (grep: ``)
│ Dependency ordering (grep: ``)
│ Three-layer review model: spec → plan → code
│
├── ② Plan review: every spec requirement → task? Contracts match spec?
│
▼ auto-trigger (after approval)
vv-implementer → vv-spec-reviewer → vv-code-reviewer
│ Workflow tracked loop with work items
│ Spec review checks: code matches spec?
│ Code review checks: implementation matches plan contracts?
│
├── ③ Code review: interfaces correct? All AC pass?
│
▼
Done
```
Specs 和 plans 使用顶层的生命周期状态：编写时为 `draft`，用户明确批准后为 `approved`，成功执行后为 `applied`。`vv-execute` 会将已应用的 artifact 包归档，方法是将整个 spec 包目录 `.vvoc/specs//` 移动到 `.vvoc/specs/archive/-/`。
### XML grep
Plans 和 specs 都是 XML 文档，这使得每个元素都可以被 grep：
```
# 从 plan 中提取 tasks
grep 'T-' .vvoc/specs/*/plan.xml
# 提取所有 acceptance criteria
grep '' .vvoc/specs/*/plan.xml
# 提取 dependency graph
grep '' .vvoc/specs/*/plan.xml
# 提取 method signatures
grep '/\*\*' .vvoc/specs/*/plan.xml
# 从 architecture 中提取所有 modules
grep '' .vvoc/specs/*/plan.xml
```
受管技能由 `vvoc` 安装。`vv-controller` 显式路由 `vv-spec`、`vv-plan` 和 `vv-review`；`vv-execute` 和 `vv-reflect` 作为受管技能提供，用于 plan 执行和持久化会话记忆。
## 为什么选择 vv-opencode？
为严肃的日常工作设置 OpenCode 意味着每次都要在每台机器上巧妙处理配置文件、agent prompt、插件连接、模型角色分配和权限规则。
**vv-opencode 将其简化为一次 `vvoc install`。** 它接管了所有的配置连接，因此你无需再手动处理：
- **六大插件，统一入口** —— 所有插件均从单个固定版本的 package 入口导出
- **受管 agent 与技能系统** —— `vv-controller` 路由 `vv-spec`、`vv-plan` 和 `vv-review`；内置的受管技能还包括 `vv-execute` 和 `vv-reflect`
- **模型角色与预设** —— 将模型分配给角色（`smart`、`fast`、`vision`……），并通过一条命令切换 provider 预设
- **安全第一** —— `guardian` agent 负责审查权限请求，发送给 LLM 的聊天内容中的敏感信息会被脱敏
- **陈旧行号防御** —— 基于 hashline 的 `edit` 可防止针对错误快照进行写入的 bug
## 功能
| 领域 | 你将获得什么 |
|---|---|
| **插件** | 固定版本 package 入口中的 6 个插件 —— 工作流编排、模型角色、guardian、hashline edit、系统上下文注入、secrets 脱敏 |
| **Agent 系统** | `vv-controller` 负责工作路由：小幅修改直接处理，bug 交由 `investigator`，高风险工作交由 implementer+reviewer 循环，大型功能交由 analyst+architect |
| **技能** | `vv-spec` 对你进行访谈并编写 XML spec；`vv-plan` 将 spec 映射到接口契约和验收标准；`vv-execute` 运行已批准的 plan；`vv-review` 运行仅供审查的工作流；`vv-reflect` 将可重用的会话发现保存为仓库记忆 |
| **Spec-to-Code Pipeline** | `vv-spec` → spec 审查 → `vv-plan` → plan 审查 → `vv-implementer` → 代码审查。三个独立的审查门控涵盖需求、契约和实现 |
| **一键安装** | `vvoc install` 或 `vvoc sync` 引导一切 —— 配置、agent、技能、prompt、预设 |
| **CLI 工具** | 16+ 命令：install、sync、launch、status、doctor、角色管理、预设、guardian 配置、shell 自动补全、upgrade |
| **安全性** | GuardianPlugin 审查 shell 权限请求；SecretsRedactionPlugin 在 LLM 请求前剥离 token；两者均可通过 `vvoc.json` 配置 |
| **模型角色** | 将 provider/model/variant 分配给角色（`default`、`smart`、`fast`、`vision`、自定义）；在 `vv-openai`、`vv-zai`、`vv-deepseek`、`vv-minimax` 预设之间切换 |
| **工作流跟踪** | 带有 open/list/close 的显式意图工作项，用于跟踪实现和仅供审查的 pipeline |
## 六大插件
| 插件 | 作用 |
|---|---|
| **WorkflowPlugin** | 围绕 `task` 为 subagent 进行受管编排；注册带有显式 `mode`（`implementation` 或 `review_only`）、`requiredReviewers`（`spec`、`code`）的 `work_item_open/list/close` 工具，收集所有 reviewer 轮次，状态机强制执行，以及实现重试轮次限制门控 |
| **ModelRolesPlugin** | 在启动时解析 OpenCode 配置中的 `vv-role:*` 引用；将 `:variant` 后缀转换为原生的 model+variant 字段 |
| **GuardianPlugin** | 使用受限的 guardian agent 和安全拒绝默认值审查 OpenCode 权限请求；可配置 model、timeout、risk threshold |
| **HashlineEditPlugin** | 用带有 hash 锚点的变体替换 OpenCode 的 `edit`；将 `read` 输出重写为 `line#hash` 格式；拒绝陈旧快照以防止漂移 bug |
| **SystemContextInjectionPlugin** | 将可重用的系统指导注入到主会话中，而不会污染 subagent 的 prompt；鼓励主动使用 `explore`；为 OpenCode 技能发现注册 vvoc 技能目录 |
| **SecretsRedactionPlugin** | 在 LLM 请求前对 secrets（token、key、电子邮件、UUID、IP）进行脱敏；之后恢复占位符；模式可配置 |
工作流工作项以显式意图打开。对于实现循环，controller 使用：
```
{
"items": [
{
"key": "implement-feature",
"title": "Implement feature",
"mode": "implementation",
"requiredReviewers": ["spec", "code"]
}
]
}
```
对于仅供审查的报告，使用 `"mode": "review_only"`。在 review-only 模式下，reviewer 的 `FAIL` 是一个已完成的发现结果：必需的 reviewer 会被独立收集，并行的 `spec` 和 `code` reviewer 可能都会返回 `FAIL`，并且除非用户明确要求修复，否则该项不会被路由到 `vv-implementer`。
## CLI 概览
| 命令 | 用途 |
|---|---|
| `vvoc init` | 交互式引导流程 |
| `vvoc install` | 非交互式设置和搭建 |
| `vvoc sync` | 刷新插件入口、agent、prompt、技能、配置 |
| `vvoc launch` | 使用确定性的 `OPENCODE_CONFIG` 和 `VVOC_CONFIG` 源启动 OpenCode |
| `vvoc status` | 显示当前安装状态 |
| `vvoc doctor` | 诊断设置问题（有问题时以非零状态退出） |
| `vvoc config validate` | 验证规范的 `vvoc.json` |
| `vvoc role list\|set\|unset` | 管理模型角色分配 |
| `vvoc preset list\|show\|` | 检查或应用命名预设 |
| `vvoc guardian config` | 打印或写入 guardian 部分 |
| `vvoc plugin list` | 列出 OpenCode 插件入口 |
| `vvoc plugin enable\|disable` | 打开或关闭 vvoc 管理的插件 |
| `vvoc patch-provider stepfun-ai\|zai\|openai` | 在全局或项目范围内修补 OpenCode provider 预设 |
| `vvoc completion` | 安装 shell 自动补全 |
| `vvoc upgrade` | 升级全局 package 并运行后续 sync |
| `vvoc version` | 打印已安装的版本 |
## 模型角色与预设
```
# 查看当前分配
vvoc role list
vvoc role list --scope effective
# 将 models 分配给 roles
vvoc role set default openai/gpt-5.4
vvoc role set team-review anthropic/claude-sonnet-4-5 --scope project
vvoc role set smart openai/vv-gpt-5.5-xhigh
vvoc role set fast openai/gpt-5.4-mini
# 切换 provider presets
vvoc preset vv-openai
vvoc preset vv-zai
vvoc preset vv-deepseek
vvoc preset vv-minimax
vvoc preset vv-osovv
```
内置角色 ID：`default`、`smart`、`fast`、`vision` + 任何自定义的小写连字符 ID。
预设是部分有效的 —— 应用一个预设只会更改其定义的角色。受管内置预设（`vv-*`）在每次 `vvoc install`/`vvoc sync` 时都会刷新；用户定义的预设则原样保留。
## 配置与数据布局
为了向后兼容，修改命令默认为全局作用域。添加 `--scope project` 可写入项目本地层。读取/诊断命令接受 `--scope global|project|effective`，其中 `effective` 按以下顺序解析：
1. 显式的环境变量覆盖（`VVOC_CONFIG` / `OPENCODE_CONFIG`）
2. 最近的项目层
3. 全局层
4. 当命令/运行时允许使用默认值时的内置默认值
规范的项目本地路径：
```
OpenCode config → ./.opencode/opencode.json(c)
vvoc config → ./.vvoc/vvoc.json
Managed agent prompts → ./.vvoc/agents/*.md
Managed skills → ./.vvoc/skills/*/SKILL.md
Spec package directory → ./.vvoc/specs//
spec.xml # normative spec document (required)
design-context.xml # curated design memory (optional)
plan.xml # implementation plan (created by vv-plan)
```
有意不将旧版根目录级别的 `./opencode.json` 和 `./opencode.jsonc` 用作 vvoc 项目层。
```
Global OpenCode config → $XDG_CONFIG_HOME/opencode/opencode.json
Global vvoc config → $XDG_CONFIG_HOME/vvoc/vvoc.json
Managed agent prompts → $XDG_CONFIG_HOME/vvoc/agents/*.md (global)
./.vvoc/agents/*.md (project)
Managed skills → $XDG_CONFIG_HOME/vvoc/skills/*/SKILL.md (global)
./.vvoc/skills/*/SKILL.md (project)
Spec documents → ./.vvoc/specs//spec.xml
Optional design context → ./.vvoc/specs//design-context.xml
Implementation plans → ./.vvoc/specs//plan.xml
Persisted data → $XDG_DATA_HOME/vvoc/
Repository memory → ./.vvoc/lessons/*.xml (lazy vv-reflect fallback)
./.vvoc/runbooks/*.xml (lazy vv-reflect fallback)
```
Schema 是带版本的，并与 package 一起发布 —— 源真相位于 `schemas/vvoc/v3.json`。
运行时插件在 OpenCode 启动期间加载一次有效的 `vvoc.json`，并在进程的生命周期内共享同一个不可变的配置快照。没有实时重载功能；更改 `vvoc.json` 后请重启 OpenCode。
### 确定性的本地启动
当你希望 vvoc 选定的配置文件成为 OpenCode 在本次运行中唯一能看到的文件时，请使用 `vvoc launch`：
```
vvoc install --scope project
vvoc launch --scope project -- run "hello"
```
`vvoc launch --scope project` 是严格且非修改性的：如果 `.opencode/opencode.json` 或 `.vvoc/vvoc.json` 缺失，它将失败并提示运行 `vvoc install --scope project`。`--scope effective` 遵循分层查找顺序，而 `--scope global` 使用全局配置路径。
## 受管 Agent
所有的 prompt 文件都由 `vvoc install` / `vvoc sync` 搭建：
| Agent | 角色 |
|---|---|
| `vv-controller` | 默认的主 agent —— 将工作路由到正确的 subagent |
| `enhancer` | prompt 增强 |
| `vv-implementer` | 带有验证的专注实现 |
| `vv-spec-reviewer` | 检查实现是否符合 spec |
| `vv-code-reviewer` | 针对 bug 和可维护性的工程审查 |
| `investigator` | 针对不明确 bug 的根因分析 |
| `guardian` | 权限请求审查（插件运行时） |
## 受管技能
五个工作流技能与 agent 一起被搭建：
| 技能 | 触发条件 | 输出 | 可 Grep |
|---|---|---|---|
| `vv-spec` | 创意/功能请求，且不存在 spec | `.vvoc/specs//spec.xml` + 可选的 `design-context.xml` | ``、``、`` |
| `vv-plan` | 存在已批准的 spec | `.vvoc/specs//plan.xml` | `T-`、``、``、`/**` JSDoc |
| `vv-execute` | 存在已批准的 plan | 应用并归档 spec/plan artifacts | ``、``、`` |
| `vv-review` | 审查请求 | 发现报告 | — |
| `vv-reflect` | 漫长的开发、调试、bugfix、运维或调查会话结束时 | 现有的仓库文档或 `.vvoc/lessons/*.xml` / `.vvoc/runbooks/*.xml` | XML 后备索引和条目标签 |
`vv-reflect` 仅在批准后备写入后才会延迟创建 `.vvoc/lessons` 和 `.vvoc/runbooks`。当存在高置信度匹配时，它优先使用现有的仓库文档规范。
技能在会话开始时由 OpenCode 通过 `config.skills.paths`（由 SystemContextInjectionPlugin 注册）加载。`vv-controller` agent 的 `` 确保在用户的请求符合其触发条件时自动调用它们。
## 本地开发
```
bun install # Install dependencies
bun run check # Typecheck + lint + format check + test
bun run fmt # Auto-format source files
bun run release:check # Verify package/schema release consistency
```
Git hooks 通过 `lefthook` 管理。
### 对构建的 CLI 进行冒烟测试
```
tmpdir="$(mktemp -d)"
bun run build
bun dist/cli.js install --config-dir "$tmpdir"
bun dist/cli.js status --config-dir "$tmpdir"
```
### 完整的发布验证
```
bun run release:check
bun run check
bun run pack:check
```
## 发布
发布流程通过本地包装器和基于 tag 门控的 GitHub Actions 作流实现自动化。
### 本地版本提升
```
bun run release:bump patch # or minor, major, prerelease, or explicit semver
```
这将：
1. 如果工作树不干净则拒绝执行
2. 通过 `npm version --no-git-tag-version` 提升 `package.json` 版本
3. 使用 `opencode --pure run` 生成所需的 AI 发布摘要
4. 将 `### Summary` 部分以及常规提交详细信息添加到 `CHANGELOG.md` 的开头
5. 将 `schemas/vvoc/v3.json` 的 `$id` 更新为新版本
6. 运行 `release:check` 以确保一致性
7. 创建发布提交和带注释的 tag `vX.Y.Z`
8. 将当前分支和创建的 tag 推送到 `origin`
本地发布的必要前提条件：
- 必须可以从 `PATH` 中使用 `opencode`。
- 摘要模型默认为 `deepseek/deepseek-v4-flash`。
- 使用 `VVOC_RELEASE_SUMMARY_MODEL=provider/model` 进行覆盖。
- 使用 `VVOC_RELEASE_SUMMARY_TIMEOUT_MS=120000` 覆盖每次尝试的超时时间。
在已检出且具有对 `origin` 推送权限的分支上运行 `release:bump`。tag 的推送才是触发发布工作流的原因。
GitHub Actions 工作流在推送 `v*` tag 时触发，验证 tag 是否与
`package.json` 匹配，运行完整的验证（typecheck、lint、fmt check、tests、
build、pack check、`release:check`），并使用 `--provenance` 发布到 npm。
### 手动检查一致性
```
bun run release:check
```
这将验证 `package.json` 的名称、版本以及 `schemas/vvoc/v3.json` 的 `$id` 和
配置格式版本是否全部一致。可随时独立运行它。
### CI 发布工作流
该工作流使用 npm provenance/trusted publishing（`id-token: write`），并且不会在正常的分支推送时发布。为此 GitHub 仓库/package 配置 npm trusted publishing，或者在需要基于 token 的发布时，调整发布步骤以使用 `NPM_TOKEN` secret。
## 可选：RTK
[RTK](https://github.com/rtk-ai/rtk) 是一个 CLI 代理，可减少常见开发者命令的 token 使用量。交互式的 `vvoc init` 流程会在设置后推荐它。
## 许可证
MIT —— 详见 [LICENSE](LICENSE)。
标签：Agent, AI编程助手, Bun, SOC Prime, 工作流, 开发工具, 文档结构分析, 暗色界面, 网络调试, 自动化, 自动化攻击