AI 工作流程模板
可发布 OpenCode 的 AI 工作流程启动器包 — 明确 synced, 版本管理, npm 分布式代理配置套件,并带有向量搜索内存.
安装
npm install --save-dev @abarcenas/ai-workflow-template
npx ai-workflow-setup
这个软件包是 CLI/ 脚手架, 不是运行时的库 没有 require编号 :import 切入点,所以导入时不支持设计. 安装它不会复制到您的工程中, 没有安装/ 船舶postinstall 钩; npx ai-workflow-setup 是唯一的设置路径,并进行所有文件同步,内存-银行脚手架和钩子安装.
升级到 2. 0
2.0.0 取消了安装时间 postinstall 同步,所以升级 不再复制任何东西到你的项目。 安装新版本后, 运行一次设置命令 :
npx ai-workflow-setup
20号节点的支持也被放弃(engines.node 现在 >=22),且该套件不再声明 main 入站点——是一个脚手架CLI,不是可导入的库.
Git Hook 设置
npx ai-workflow-setup
它会做什么
| 阶段 | 行动 |
|---|---|
| 发现 | 检测 git repo, 已存在的钩子, CI 模式 |
| 钩子 | 安装 pre-commit (版本起伏+验证)和 post-merge (元索引更新) |
| 准备 | 合并 "husky" 进入您的 package.json 准备脚本 |
| 胡斯基Init( 胡斯基公司) | 初始化 husky 和 设置 core.hooksPath |
| 同步 | 复制代理配置、技能和存储库脚手架 |
| 技能 | 从上游恢复固定技能(与 --skip-sync(中文(简体) ) |
| 知识库 | 将项目登记在中央知识库中(与 --skip-knowledgebase(中文(简体) ) |
选项
npx ai-workflow-setup --dry-run # Preview hooks/prepare/skills, skip sync
npx ai-workflow-setup --force # Overwrite existing hooks
npx ai-workflow-setup --skip-hooks # Skip hook installation
npx ai-workflow-setup --skip-sync # Skip file sync
npx ai-workflow-setup --knowledgebase # Run only the knowledgebase phase
npx ai-workflow-setup --help # Show all options
钩子合并
- 你的钩子永远不会被覆盖 ——新内容被附加在分隔符后
- 检测到管理下钩子 通过标记注释和更新单词
- 复杂的钩子 用手动合并指令触发警告
- CI 环境 自动滑翔钩配置
没有安装时间脚本 : npm 12+,pnpm 10+,以及Yarn 4 默认依赖生命周期脚本. 这个包裹没有
postinstall; 当您明确引用时, 一切都会运行npx ai-workflow-setup。 。 。 .
此套件会做什么
- 41个专业人工智能技能、框架指示和快速模板
.agents/(中文(简体) ) - 智能代理框架 - 计划模式、执行计划、研究
- 多剂管弦乐手 ——有10+个专用分剂的动态管线
- TDD 协奏曲 • 严格的RED-GREEN-REFACTOR/VERIFY管道(90%覆盖门)
- 记忆库 ——以 sqlite-vec 语义搜索为持续的项目背景
- 洞穴模式 - 超压缩通信,以达到象征性效率
- Playwright + 测试 ——E2E浏览器测试,单位测试有v8覆盖(%-90%)
- 版本自动跳出+自动发布 ——Husky管理;npm 合并后发布到
main - 关闭/ 公关出版 常规承诺 推动
gh pr create,从origin/HEAD,从不合并 - 图表化知识图 ——可查询代码级关系映射
维护者同步( 在此重播中)
npm run sync 是此寄存器中定义的维护者命令 package.json。它不运往消费者——消费者项目通过运行同步 npx ai-workflow-setup,它引用相同的同步引擎.
npm run sync -- --dry-run # Preview changes without applying
npm run sync -- --force # Force overwrite local changes
npm run sync # Normal sync
智能同步规则 :
- 自动复制新文件
- 从软件包中刷新未修改的文件
- 本地编辑的文件被保存( 默认跳过)
- 项目自有文件在创建后从未被覆盖或浏览过,以及
--force无法替换它们 - GitHub 动作工作流程被排除在消费者同步之外(
.github/workflows/(中文(简体) )
npx ai-workflow-setup --dry-run预览钩子,准备,和技能相位但跳过同步,因此没有复制或浏览文件,也没有创建脚手架文件. 对于同步本身的预览,请运行npm run sync -- --dry-run; 消费者同步到npx ai-workflow-setup。 。 。 .
项目拥有的文件
AGENTS.project.md 是用于特定项目代理规则的支持之家。 如果它没有被创建,然后作为项目所有:同步从不覆盖或刷新它, --force 无法替换, 删除它会在下次同步时重现 。 新项目装入 "instructions": ["AGENTS.project.md"] 内 opencode.json; 该条目存在之前创建的工程必须添加一次, 因为同步永远不会重写已有的 opencode.json。 。 。 .
同样的所有权规则保护 opencode.json, (中文(简体) ), .prettierignore,以及 .agents/instructions/learned-knowledge.instructions.md。 。 。 . .agents-sync-ignore 也保护不覆盖和删除,但同步 没有 阅读或尊重其内容——不要依赖它.
__project__/<file> 输入 .agents-sync-manifest.json 只在同步创建文件时报告元数据。 升级前就已经存在的文件是故意缺失的,因为同步对它们没有管理的基准.
货包船a .prettierignore 和脚手架,当它缺席。 新项目自动覆盖 .agents/, (中文(简体) ), .opencode/agents/, (中文(简体) ), .opencode/commands/, (中文(简体) ), AGENTS.md, (中文(简体) ), skills-lock.json,并且每个同步脚本;所运出的文件也忽略了 AGENTS.project.md,虽然该文件不是散列管理的。 现有项目保持原有水平 .prettierignore 未经更改( 它是项目拥有的), 因此如果它没有覆盖每个管理过的路径同步打印一个警告 :
[ai-workflow-template] Existing .prettierignore does not protect managed files; merge the patterns from node_modules/@abarcenas/ai-workflow-template/.prettierignore
手动合并这些模式——同步从不编辑文件 。 模板侧添加到 rootFiles 或者说 scriptsToSync 也要求在现有项目中有一个匹配的手动行;所运出的文件仅更新新项目的默认值. a formatter 运行在所管理的文件上重写了它们的散列,所以以后的每次同步都会跳过它们,消费者也不再收到模板更新.
如果同步警告 Skipped locally modified root file: AGENTS.md,移动这些本地规则 AGENTS.project.md,恢复管理的文件 node_modules/@abarcenas/ai-workflow-template/AGENTS.md,然后重新运行同步.
核心结构
安装后,您的项目接收到此结构:
.agents/
├── instructions/ # Framework, workflow, and security guidance
├── skills/ # 41 specialized AI skills
└── prompts/ # Reusable prompt templates
.opencode/
├── agents/ # Orchestrator + specialized sub-agents
├── commands/ # Slash commands (incl. /health, /setup-matt-pocock-skills)
└── plugins/ # graphify knowledge-graph plugin
memory-bank/ # Persistent project context (+ tasks/)
scripts/ # Sync, memory, and knowledgebase CLI helpers
AGENTS.md # Master instruction file with agent guidance
AGENTS.project.md # Project-owned rules (recreated if deleted, never overwritten)
opencode.json # OpenCode config (project-owned after creation)
.prettierignore # Formatter coverage for managed files (project-owned)
skills-lock.json # Pinned skill versions
.github/workflows/ # Repo-only — never synced to consumers
多剂管风琴
探员
| 探员 | 文件 | 作用 |
|---|---|---|
| 整形仪 | .opencode/agents/orchestrator/orchestrator.md | 大师——分析请求,建设管线,代表 |
| 范围 | .opencode/agents/scope.md | 对未指定请求的有条件前门——烤弹,然后是钉子道克 |
| 研究员 | .opencode/agents/researcher.md | 技术调查、图书馆评价 |
| 建筑师 | .opencode/agents/architect.md | 系统设计,组件结构 |
| 执行者 | .opencode/agents/implementer.md | 将设计转化为实施计划 |
| 设计师 | .opencode/agents/designer.md | UI/UX, 外观设计, 反应性设计 |
| 编码器 | .opencode/agents/coder.md | 生产守则的执行 |
| 单位测试器 | .opencode/agents/unit-tester.md | 单位和整合测试 |
| E2E 测试器 | .opencode/agents/e2e-tester.md | Playwright 浏览器测试 |
| 审查者 | .opencode/agents/reviewer.md | 守则审查、安全审计 |
| 部署人员 | .opencode/agents/deployer.md | CI/CD,部署脚本 |
| 跟踪器 | .opencode/agents/tracker.md | 文件记录器 |
如何使用
调用管弦乐手 @orchestrator 随后,你的任务:
@orchestrator Add a user login feature with email verification
@orchestrator full pipeline: refactor authentication to use JWT
@orchestrator fix the pagination bug in the search results component
- 运行流量 : 检查内在结构上下文(a)
test编号 :grep探测到docs/.architecture-context.md—— 建立管道 —— 依次执行代理(确认/冲出每个步骤,或允许自动确认) —— 跟踪文件docs/tracker-log.md——坚持新知识. - 范围步骤(有条件,先行): 只有在请求未得到充分说明时,才在管道前插入:
scope运行对文件草稿的烧烤回合, 写着docs/spike-<feature>.md,然后手拿开researcher或者说implementer。总是交互的(自动确认不能跳过),并且有 没有命令执行权限 - 原型机被下放给coder(逻辑)或designer(UI) (中文(简体) ). - 靴子( 有条件 ): 建筑-蓝印-生成者技能只在探测器退出时运行——
docs/.architecture-context.md缺少, 空白, 或只使用模板( 无)##),或缺少核心内存库文件。 写着docs/.architecture-context.md0号出口的探测器 完全跳过代表团 所以以后就永远无法到达了.
MCP 工具
一些代理需要配置在其中的 MCP 服务器 opencode.json (模式 : opencode.mcp.example.json:
| 探员 | 需要的 MCP 程序 | 目的 |
|---|---|---|
| 研究员 | ddg- 搜索, 背景7 | 网络搜索+文件查询 |
| E2E 测试器 | 剧作家 | 浏览器自动化 |
| 审查者 | GitHub 图像 | 公关和发行管理 |
| 部署人员 | GitHub 图像 | 发布,动作 |
Playwright MCP 为浏览器对等配置了两次: playwright (Google Chrome——美国) chrome 频道,哪个 @playwright/mcp 默认使用,因此必须安装Google Chrome)和 playwright-firefox (烟花, --browser firefox --isolated) (中文(简体) ). 每个服务器都需要自己的许可条目(playwright_*, (中文(简体) ), playwright-firefox_*Firefox 必须先安装 npx playwright install firefox 看到了吗 docs/playwright-mcp-configuration.md现有 opencode.json 文件从未通过同步重写, 因此升级工程必须添加 playwright-firefox 块及其手动许可.
TDD 整形仪
通过RED GREEN REFACTOR/VEIFY周期进行严格测试驱动开发:
implementer (PLAN) → unit-tester∥ (RED) → coder∥ (GREEN) → unit-tester (VERIFY) → reviewer → tracker
| 步骤 | 探员 | 阶段 | 说明 |
|---|---|---|---|
| 1个 | 执行者 | 计划 | 创建平行测试/代码批次表的实施计划 |
| 2个 | 单位测试器 | 红色 | 首先写入失败测试 —— 在代码存在之前定义预期行为 |
| 3个 | 编码器 | 绿色 | 写入最小生产代码以通过所有测试——没有额外特性 |
| 页:1 | 单位测试器 | 事实 | 运行全套套房, 强制实施“ 90%” 覆盖阈值 |
| 页:1 | 审查者 | 编辑 | 审计测试+执行质量、安全、模式 |
| 6个 | 跟踪器 | 文件 | 记录编审结果 docs/tracker-log.md |
关键规则 : 测试总是先写; 如果覆盖度为 < 90%, 循环回RED( 最多3个迭代) ; 每套套件在 memory-bank/tasks/;汲取的教训持续到 .agents/instructions/learned-knowledge.instructions.md。 。 。 .
如何援引:
@orchestrator Add user authentication with login/logout endpoints
TDD 管弦乐器使用 subagent_type "tdd-orchestrator" 并当请求更改可测试代码时自动选择严格的管道.
记忆库
整个大赦国际会议的持续项目背景。 语义向量搜索( S)sqlite-vec)让代理查询内存而不将所有文件装入上下文.
MCP 工具
| 工具 | 目的 |
|---|---|
memory_search | 语义搜索跨内存库 + docs( query + topK) |
memory_update | 递增同步——只更改文件(~2秒) |
memory_rebuild | 从平分文件完全重建( 很少—— 克隆/ 腐败) |
memory_get | 按名称读取特定内存文件 |
memory_stats | 指数统计(媒介计数,DB大小) |
文件结构
真理的来源是 git- 承诺的 Markdown; 矢量指数( =% 1)memory-bank/.index/memory.db)是可支配和可重建的.
projectbrief.md → productContext.md / systemPatterns.md / techContext.md → activeContext.md → progress.md / tasks/
| 文件 | 目的 |
|---|---|
memory-bank/projectbrief.md | 核心要求、目标和范围 |
memory-bank/productContext.md | 问题得到解决, UX 目标 |
memory-bank/systemPatterns.md | 建筑、设计模式、构件关系 |
memory-bank/techContext.md | 技术、设计、制约 |
memory-bank/activeContext.md | 当前的重点、最近的变化、下一步 |
memory-bank/progress.md | 什么工作,什么剩下的,已知的问题 |
memory-bank/tasks/ | 每个任务跟踪方式 _index.md |
文档Schema
所有内存库文件都使用 YAML 前事(id, (中文(简体) ), title, (中文(简体) ), updated, (中文(简体) ), tags, (中文(简体) ), entities, (中文(简体) ), category用于搜索索引;见 memory-bank/.vocabulary.json 用于控制词汇. npx ai-workflow-setup 运行 normalize-memory.js 添加前题; Husky 预承诺钩拒绝无效的前题。 任务命令 : add task, (中文(简体) ), update task [ID], (中文(简体) ), show tasks [filter]。 。 。 .
调试效率
| 方针 | 每届会议的托肯数 |
|---|---|
| 读取全部内存文件 | ~5 000 - 15 000+ (单位:千美元) |
| 语义搜索 | ~500–2,000(上3–5块) |
知识图 (绘图)
/graphify # Build a graph for the current directory
/graphify <path> # Build for a specific path
/graphify query "How does authentication work?"
先决条件
- Python 3.10+——所需运行时间
graphifyyPython 软件包 -pip install graphifyy或者说uv tool install graphifyy- 可选:双子座 API 密钥 (
GEMINI_API_KEY或者说GOOGLE_API_KEY) —— 语义提取速度快;没有它就回落到克洛德子剂上
GitHub: safishamsi/ 绘图 完整的文件、示例和资料来源
特长技能
- 特性范围界定:
grilling, (中文(简体) ),grill-me, (中文(简体) ),grill-with-docs, (中文(简体) ),domain-modeling, (中文(简体) ),prototype- 范围狭窄、规格不高的请求达到上限;GLOSSARY.md财务报告和审定财务报表docs/adr/地点来自.agents/config/domain.md - 工作流程自动化 :
architecture-blueprint-generator, (中文(简体) ),create-implementation-plan, (中文(简体) ),create-readme, (中文(简体) ),context-map, (中文(简体) ),graphify(全球技能),graphify-framework-aware - 开发工具:
playwright-explore-website, (中文(简体) ),playwright-generate-test, (中文(简体) ),github-issues, (中文(简体) ),gh-cli, (中文(简体) ),polygot-test-agent, (中文(简体) ),microsoft-docs - 调试效率( E) :
caveman, (中文(简体) ),caveman-compress, (中文(简体) ),compress, (中文(简体) ),caveman-commit, (中文(简体) ),cavecrew, (中文(简体) ),caveman-stats - 质量和安全性 :
agent-governance, (中文(简体) ),conventional-commit, (中文(简体) ),git-commit(OWASP指南.agents/instructions/security-owasp.instructions.md(中文(简体) )
版本
Husky 自动弹出版本关于每次犯罪:默认的次要(1.2.0 → 1.3.0),将每次凸起时的重排补丁为 0,并重置主要更改为 <major>.0.0。不需要手动版本管理。 设定 SKIP_BUMP=1 (例如:. SKIP_BUMP=1 git commit ...)跳过该承诺的凸起-对仅用于医生的更改有用.
发布流程
GitHub 动作在工作登陆时发布到 npm main 也就是当公关合并的时候 出版的版本是什么 package.json 在合并时表示( Husky 前承诺钩已经撞倒了小版本) :
git push origin feat/my-change
gh pr merge --merge # merging to main publishes that version
已经登入登记册的版本失败了运行, 而不是重印, 如此起伏 package.json 而不是针对同一版本重新运行。 重试失败的发布, 发送到 main 没有投入:
gh workflow run npm-publish.yml --ref main
推动 v* 标记不发布任何信息.
添加 NPM_TOKEN 到 GitHub 仓库中的秘密 :
- 仓库 设置 机密和变量 动作
- 新建寄存器密- 名称 :
NPM_TOKEN - 粘贴 npm 自动化符号
说明: 发布工作流程文件( E).github/workflows/为了防止冲突,将消费者同步排除在外.
地方发展
npm install # Install dependencies & activate Husky hooks
npm run sync -- --dry-run # Verify sync behavior (dry run)
npm pack --json # Test package creation
npm test # Playwright E2E tests
npm run test:unit # Unit tests (Vitest)
npm run test:unit:coverage # Unit tests with coverage (90% threshold)
npm run test:unit:watch # Watch mode for unit tests
npm run memory:rebuild # Build the vector index (one-time, ~8 min)
npm run memory:update # Incremental index update (seconds)
npm run memory:search "tdd orchestrator status"
npm run memory:normalize # Normalize frontmatter (also runs during npx ai-workflow-setup)
测试
| 类型 | 框架 | 命令 | 覆盖范围 |
|---|---|---|---|
| 欧2E | 剧作家 | npm test | —— 说 |
| 单位 | 维特 | npm run test:unit | npm run test:unit:coverage (≥90%) |
- E2E测试
tests/*.spec.ts– 通过 Playwright 实现浏览器自动化 - 单位测试
scripts/*.test.{js,ts}财务报告和审定财务报表tests/*.test.js——通过Vitest进行组件测试和跨文件谱检查,V8覆盖
更新模板
- 编辑文件
.agents/, (中文(简体) ),docs/,或scripts/ - 本地测试更改
- 提交( 触发自动转换凸起)
- 合并 PR 为
main(触发 npm 发布) - 消费者安装新版本, 然后重新运行
npx ai-workflow-setup要同步
重要说明
- 用途
INIT_CWD以消耗项目(而不是包目录)安装 - 除非
--force用于 - 项目自有文件( E)
AGENTS.project.md, (中文(简体) ),opencode.json, (中文(简体) ),.prettierignore如果不存在,并且从此以后就不再被覆盖或磨损,即使有--force - 不添加
AGENTS.project.md或者说opencode.json改为package.jsonfiles: 两者都是脚手架 创建- 如果- 不使用, 绝不能从包运 AGENTS.md主要指令文件代理应该读取- 软件包假定公共 npm 注册
- Playwright MCP 集成记录在
docs/playwright-mcp-configuration.md - 运行
npx ai-workflow-setup在安装后配置 git 钩子( npm v12+ 兼容)