Open Spec Mesh

Node.js 工具集与 Quick / 人工推动的 SDD 研发规范。旧自动 SDD 生命周期已退出。

English

前置条件

• Node.js 22.0.0 及以上、兼容的 npm、Git。
• Linux/macOS 宿主配置路径；最低版本使用 Node 22.0.0 + npm 10 验证，不要求安装最新版 npm。
• 已安装 Codex、OpenCode、Claude Code 或 DeepSeek Harness (DSH)。本包不安装这些宿主，不提供模型账号或密钥。

从 npm 公共仓库安装

公共 npm 0.3.0 已发布；以下命令按该版本安装。若使用镜像遇到 E404，请核对 registry，不要把本地打包成功当成发布成功。

# 第一步：安装全局命令，不会自动改动宿主配置。
npm install -g [email protected] --registry=https://registry.npmjs.org/
open-spec-mesh --version

# 第二步：预览并显式配置 Codex。
open-spec-mesh install --host codex --skip-tools --dry-run
open-spec-mesh install --host codex --skip-tools

预期命令版本为 0.3.0。安装后新开宿主会话，让其读取最新 Rules、Role 和 Skill。

--skip-tools 只安装核心工具包，不额外安装 Research 工具，不宣称 Research MCP 可用，也不启用 System One。npm 安装没有擅改 Home 的 postinstall；全局命令安装与宿主配置安装是两步。

选择宿主与配置目录

# 默认分别使用 ~/.codex、~/.config/opencode、~/.claude、~/.dsh。
open-spec-mesh install --host codex --skip-tools
open-spec-mesh install --host opencode --skip-tools
open-spec-mesh install --host claude --skip-tools
open-spec-mesh install --host dsh --skip-tools

# 自定义配置根；有空格的路径必须加引号。
open-spec-mesh install --host codex --host-home "/path/to/codex home" --skip-tools

在 DeepSeek Harness (DSH) 中作为插件安装

open-spec-mesh 提供 DSH Bundle 预设，要求 DSH 0.2.1-rc.4 或更新版本（engines.dsh 为 >=0.2.1-rc.4）：预设挂载的 @deepseek-ai/dsh-tool-subagent-control/list-agents 子路径从该版本才提供。DSH 读取 engines.dsh，低于该范围会拒绝安装或激活插件。

# 把 Bundle 挂载到某个 profile。参数是 registry 包名或本地仓库路径，
# DSH 会把它转发给 profile 目录内的 pnpm。
dsh plugin --profile <profile> add open-spec-mesh
# 卸载挂载。
dsh plugin --profile <profile> remove open-spec-mesh

重启该 profile 后，在预设选择器中选择 「sdd」；该预设带 L0/L1/L2 自动定级与渐进式门控。

DSH 的两个入口分工不同、互不重叠：

命令	写入	不写入
dsh plugin --profile <profile> add open-spec-mesh	该 DSH profile 的插件集合，由此提供 「sdd」 预设	项目 AGENTS.md；$DSH_HOME/skills 下的技能
osm install --host dsh	目标项目 AGENTS.md 的受管章节；sdd-* 技能装到 $DSH_HOME/skills	agents/*.md（DSH 不读）；Research 工具（DSH 的 MCP 在 preset 内配置）；--with-laya 直接失败

角色路由：预设里的 osm:role-routes section 把 ~/.dsh/osm-models.json（$DSH_HOME 可覆盖基目录）渲染成「角色 → provider / model / reasoning_effort」表，模型派发时用原生 subagent 工具显式传这三项。osm models list|doctor|set|reset|export|import 统一管理该配置（支持通过 osm models export [filepath] 导出与 osm models import <filepath> [--force] 还原）；osm 自身不校验 allowlist，超出 DSH 会话允许范围的路由由 DSH 拒绝，而不是由 osm 拒绝。

默认目录同时支持 CODEX_HOME、OPENCODE_CONFIG_DIR、CLAUDE_CONFIG_DIR。Codex 兼容参数 --codex-home 保留。具体宿主启动方法见 运行指南。

不安装全局命令，直接运行

npm exec --yes --registry=https://registry.npmjs.org/ [email protected] -- \
  open-spec-mesh install --host codex --skip-tools

源码或本地打包安装

# 在仓库目录执行；全局命令链接源码目录，不要移除该目录。
npm ci
npm install -g .
open-spec-mesh install --host codex --skip-tools

# 或生成便携 tarball；依赖安装仍需 npm 网络或缓存。
npm pack
npm install -g ./open-spec-mesh-0.3.0.tgz
open-spec-mesh install --host codex --skip-tools

升级、卸载和常见问题

# 更新全局命令后，仍需显式升级宿主受管内容。
npm install -g open-spec-mesh@latest --registry=https://registry.npmjs.org/
open-spec-mesh install --host codex --skip-tools --dry-run
open-spec-mesh install --host codex --skip-tools

# 仅卸载全局命令；不会删除已配置的宿主资产。
npm uninstall -g open-spec-mesh

• 升级前备份受影响的受管路径与配置。安装失败会事务回滚，但成功后不会自动长期保留备份。
• 升级整体替换受管 Skill，清除旧 Python 脚本和缓存，应用已知旧 Skill/角色退役；已识别受管 Python MCP 改为 Node 并定向清理 helper/cache。
• 保全用户模型/provider、凭据、自定义 MCP、无关 Python 和未受管资产；同名未受管资产冲突时拒绝覆盖，不应删除整个 ~/.codex。
• 命令找不到时检查 npm 全局 bin 的 PATH，Linux/macOS 通常为 $(npm prefix -g)/bin。权限问题优先使用用户自有的 Node/global prefix，不自动用 sudo 改写宿主配置。
• 发布者操作见 npm 发布指南；登录、打包、dry-run、真实上传是不同状态。

osm 短命令（自 0.1.0 起随发布提供）

公共 npm 0.1.0 已同时提供 osm 与 open-spec-mesh。0.1.0 及以后的发布版本都带 osm，不需要本地源码安装；osm 是更短的等价入口，不是另一种 registry 升级。

osm --dry-run  # 默认 Codex 安装预览，不写 Home
osm            # 等价于 open-spec-mesh install --host codex --skip-tools
osm --help
osm --version
osm install --host opencode --skip-tools

不带参数的 osm 是用户显式触发的安装，不是 npm postinstall；原 open-spec-mesh 无参数仍显示帮助，完整命令兼容。真实 npm 发布需要明确的发布意图和目标版本；“发布 0.0.2”等自然语言指令会自动使用 $sdd-release，无需改写为技能口令。仅准备材料时不上传。

当前工作流程

• Quick：当前 Agent 连续调查、实现、测试、自审；陌生本地事实优先 Explorer，外部文档/版本优先 Librarian，减少主线程重复遍历。
• SDD：需求 → 整体设计 → 执行计划（任务拆分与任务设计）→ 实现 → 交付，每阶段人工确认；用户可明确一次授权多个阶段。
• 单任务或串行由当前 Agent 在当前工作区执行；只有用户确认并行时才使用 Worker 和独立 worktree。
• 设计不冻结文件、函数或编码步骤；执行者可处理必要局部调整，实质目标、验收、安全或重要公共方案变化才请用户确认。
• 新代理使用 role_desc，如 explorer_module_flow；配置角色 ID 保持不变。
• 文档/检查辅助人工评审，不自动推进阶段；真实测试和安全检查仍必须处理。

SDD 技能使用引导

选择 SDD 模式后，Main 会说明当前阶段、给出可直接使用的技能调用示例，并在阶段完成时提示下一步；不会因为技能执行成功自动推进。

阶段或需要	技能	示例
按需初始化文档骨架	$sdd-init	$sdd-init 为当前项目建立文档骨架
需求	$sdd-req	$sdd-req 为这个需求创建或完善 Change
整体设计	$sdd-design	$sdd-design 需求已确认，编写整体设计
执行计划：任务拆分与任务设计	$sdd-plan	$sdd-plan 整体设计已确认，编写执行计划，包含任务拆分和任务设计
实现与验证	$sdd-do	$sdd-do 执行计划已确认，按计划串行实现并验证
交付与确认后归档	$sdd-close	$sdd-close 汇总实现结果和验证，先供我确认

已有文档骨架无需重复初始化。旧结构迁移用 $sdd-migrate；持久化研究/长期 ADR 按需用 $sdd-research；执行诊断仅在用户要求时用 $sdd-diagnose；版本发布材料用 $sdd-release，真实上传需要明确发布意图及本次目标版本，自然语言同样有效。自然语言授权也有效，调用技能不等于确认所有后续阶段。若技能未安装或当前会话不可用，Main 应如实说明并引导安装或加载。

原 $sdd-change 已拆分，需求技能现名为 $sdd-req；sdd-change 与旧名 sdd-requirements 均不再作为受管技能安装，旧 sdd-change/scripts/ 入口已删除。升级时，已登记的旧目录先保存到 open-spec-mesh/retired-skills/ 下的私有 ZIP，再退出技能发现；归档包含本地修改，不自动清理。未登记的用户目录保留并提示，不按名称删除。

日常命令

open-spec-mesh --help
open-spec-mesh init-project --root /path/to/project
open-spec-mesh new-change feature --root /path/to/project
# 人工确认后再进入相应阶段：
open-spec-mesh ensure-design CHG-YYYYMMDD-feature --root /path/to/project
open-spec-mesh new-task CHG-YYYYMMDD-feature capability --root /path/to/project
open-spec-mesh validate-docs --root /path/to/project

new-change 只写需求；new-task 写宏观 Markdown 与人可读计划，不生成机器执行状态。observe/diagnose 只收集证据。发布辅助命令只写材料，不代替真实 npm 上传或部署。

可选服务与开发验证

Research 工具另需 CONTEXT7_API_KEY / TAVILY_API_KEY；在调用环境中导出自己的值，再去掉 --skip-tools 安装。npm 包不包含用户凭据，npm 安装不写入密钥。

System One 默认关闭；自托管 GPU 服务、专属 Python CI 与依赖已退出。仅保留 Node.js HTTP/MCP 客户端连接外部兼容推理服务，不下载模型、不启动本地推理、不调用 Python。受管 bridge 当前只支持 Codex。

在源码目录执行：

npm ci
npm run validate:core
npm run validate:full

full 另需真实宿主 CLI、Docker、Mermaid 与 Research 工具。缺失前置条件如实失败，core 全绿不等于外部宿主或推理服务已经全绿。第一方工具、测试和自动化均为 Node.js，Python 源文件审计坚持零例外。

更多说明见 工作约定、工具指南、文档规范 和 项目文档。

协作效率优化（自 0.0.3 起随发布提供）

保留完整文档结构，减少重复内容而非删除 C01/C02/C03、独立 Task 或 Delivery。委派先判断净收益，串行由 Main 连续完成；设计只约束稳定的行为、安全和公共契约，内部实现可自主调整。详见 协作边界。

# 源码目录：只读核对安装文件，不证明活动会话已加载
node bin/open-spec-mesh.js inspect-host --host codex --format json
# 六种场景及归一化动作检查，不调用模型或授权阶段
node bin/open-spec-mesh.js evaluate-collaboration --list
node bin/open-spec-mesh.js evaluate-collaboration --report PRIVATE_REPORT --scenario local-fix
# 可读报告；只有显式strict选项才让证据不完整退出3
node bin/open-spec-mesh.js evaluate-collaboration --report PRIVATE_REPORT --scenario local-fix --format md --fail-on-incomplete
# 维护共享规则副本；项目专用AGENTS内容不被替换
npm run check:workflow
npm run sync:workflow

人工流程没有历史 Graph 时，旧首轮通过/返工指标显示不适用或未知，不显示虚假零返工。用量包括已观测 Main/子会话，按 session/slice 去重，完整总量仅在覆盖完整时提供；金额和真实节省尚未验证。可选人工返工标注与固定基线对照见 评估方案。文件核验、trace检查、确定性fixture和真实模型评测不是同一层证据。这些文档自 0.0.3 起随发布包提供；安装或升级本包不会自动升级已有的 Host Home。

评估默认JSON并保持既有退出行为：incomplete也可能退出0；自动化可用 --fail-on-incomplete 令其退出3，动作检查失败为1、参数错误为2。即使 supported_checks_passed，语义质量与人工验收仍未验证。

新目标默认Quick，不因“端到端”或加载sdd-do升级SDD；Quick无正式Change/Task/Delivery链，直接交付摘要。保留完整结构只约束既有文档和明确SDD目标；单任务短写保留必要目标/约束/验收。按需迁移旧回退：node bin/open-spec-mesh.js install --host codex --migrate-legacy-agent-defaults（仅旧gpt-5.6-luna，不改Main或其他自定义模型）。本机真实模型验证：node scripts/verify_codex_live.js --run --output PRIVATE_DIR，可能计费，不是默认检查。