precision-dev-workflow

Precision Dev Workflow

一套平台无关、证据优先的开发工作流 Agent Skills。核心规则使用中文编写，可分发给 Cursor、OpenCode、腾讯 WorkBuddy、Codex，以及只能接收普通提示词的 Grok 等模型或宿主。

📖 新手请从 GUIDE.md 开始：3 分钟完成安装，含每个技能的触发说法与完整生命周期演示。

包含的 Skill

• precision-dev-workflow：把需求转成可验证的验收标准，执行最小必要修改并按风险验证。
• review-live-diff：只读审查 Git 当前 staged、unstaged 和 untracked 改动。
• write-commit-message：只根据当前选定 diff 生成一条可复制的 Conventional Commit。
• sync-related-repos：把 A 仓库意图按 B/C 各自架构、契约、生命周期和工具链做目标原生适配。

SKILL.md、引用文档和触发描述均可使用 UTF-8 中文。为了兼容各个平台，目录名、name 字段、CLI 参数和命令保留英文及 ASCII。

平台支持

腾讯 WorkBuddy 官方文档已明确支持“上传本地技能包”，但当前公开页面没有说明归档内部结构。因此本项目按通用 Agent Skills 约定生成根目录含 SKILL.md 的独立 ZIP；发布前必须在实际 WorkBuddy 客户端完成上传、识别和触发验证，未验证前不宣称完全兼容。

各宿主的实际验证范围、版本和日期记录在 COMPATIBILITY.md。安装路径或 ZIP 可生成不等于目标宿主已经识别并正确触发 Skill。

tests/trigger-cases.json 提供正向、边界和负向路由样例，但静态结构校验不代表模型触发已经通过；真实宿主评估方法见 tests/README.md。

仓库包含 GitHub Actions CI（.github/workflows/ci.yml），在 macOS、Linux、Windows 和 Node 18/20/22/24 矩阵上执行完整测试与消费者验证。

通过 npm 安装

安装到当前项目的共享目录（Cursor 与 OpenCode 均可识别）：

npx precision-dev-workflow install --platform agents

使用宿主原生目录：

npx precision-dev-workflow install --platform cursor
npx precision-dev-workflow install --platform opencode
npx precision-dev-workflow install --platform codex --scope user

先预览目标位置而不写入：

npx precision-dev-workflow install --platform agents --dry-run

已有同名 Skill 时安装会停止；确认要替换时显式传入 --force。

install、update、uninstall、list 默认 --platform agents、--scope project；-g 是 --scope user 的简写（与显式 --scope project 互斥）；export 默认 --platform all、输出到包内 dist 目录。

Windows 用户建议：PowerShell 中每次 npx 都要解析 shim，首次运行明显偏慢。推荐全局安装一次后直接使用裸命令，macOS 同样适用：

npm install -g precision-dev-workflow
precision-dev-workflow list

每个 Skill 的 SKILL.md frontmatter 都带有 version 字段，与 npm 包版本保持一致；各宿主对未知 frontmatter 字段的忽略行为已按官方文档确认。

更新现有安装

先预览更新范围（会显示每个 Skill 的版本变化，例如 0.3.0 → 0.4.0）：

npx precision-dev-workflow update --platform agents --dry-run

确认后更新：

npx precision-dev-workflow update --platform agents

目标中存在比当前包更新的同名 Skill 时，更新会判定为降级并停止；确认回退时显式传入 --force。upgrade 是 update 的别名，行为完全一致。

查看已装版本

只读盘点目标目录中各 Skill 与当前包的版本差异：

npx precision-dev-workflow list
npx precision-dev-workflow list -g

输出示例：

precision-dev-workflow@0.4.0
目标：/path/to/project/.agents/skills
- precision-dev-workflow：已装 0.4.0（最新）
- review-live-diff：已装 0.3.0（可更新到 0.4.0）
- sync-related-repos：未安装
- write-commit-message：同名目标无法识别

卸载

只删除包内的同名 Skill，不影响目标目录中的其他内容：

npx precision-dev-workflow uninstall --dry-run
npx precision-dev-workflow uninstall

update 使用与 install 相同的 --platform、--scope、-g 和 --destination 定位规则。它会更新已识别的同名 Skill，并补装当前版本新增的 Skill，但不会删除目标目录中的其他 Skill。目标中没有任何已安装 Skill 时会要求先执行 install；同名目标无法识别时会停止，只有明确传入 --force 才会替换。

安装和更新都会先完整暂存新内容，再替换目标；进程内发生错误时会回滚已经替换的 Skill。更新会替换已安装 Skill 目录中的本地修改，需要保留的自定义内容应先另行备份。不要在同一个目标目录上并行运行多个 install、update 或 uninstall：写入前的暂存目录清理会把并发进程的中间状态当作残留删除。

打包编译

npm run build

生成：

• dist/workbuddy/*.zip：每个 ZIP 是一个可单独上传的 Skill。
• dist/prompt/precision-dev-workflow.prompt.md：用于独立 Grok 或无 Skill 加载器的平台。

<output>/workbuddy 和 <output>/prompt 是生成产物目录。导出对应平台时会以当前精确产物集替换相应目录，从而清除旧版本残留；不要在其中存放手工文件。dist 根目录下的 *.tgz 是 npm pack 的手工产物，不受导出管理。

也可以单独导出：

precision-dev-workflow export --platform workbuddy --output dist
precision-dev-workflow export --platform prompt --output dist

质量定义

跨仓库同步为每个目标仓库独立建立兼容矩阵，覆盖入口、消费者、业务规则、API、状态、生命周期、异常、边界、重复操作、并发、平台边界、测试和工具链。矩阵项使用 Passed、Blocked、Not run、N/A 状态；只有全部适用项均为 Passed，且不存在 Blocked 或 Not run 时，才可以报告目标完成。

这不等于数学意义上的“永远零 Bug”。未实际执行的浏览器、Electron、真实后端、操作系统、基础设施或生产路径必须明确披露，不能伪装成已经验证。

校验、npm 打包与发布

npm test
npm run lint
npm run build
npm run test:consumer
npm run pack:check
npm pack

发布前也可以执行完整本地门禁：

npm run release:check

确认 npm 包名可用、WorkBuddy 实际导入结果和各平台冒烟用例后，可由维护者发布：

npm login
npm publish --access public

项目不会在构建或安装期间自动发布，也不使用 preinstall、postinstall 等生命周期脚本。

License

MIT