SpecMgr

biz.dfch.SpecMgr

用于管理系统规范的制品管理器。

本项目是一个 MCP 服务，可用于管理不同的规范制品——完整的制品类型列表及其相互关系，请参阅概念；工具、资源和提示词参考，请参阅 MCP 服务 / docs/MCP.md。

MCP 服务（以及管理用的 CLI）均为可选项。可将它们作为“额外组件”安装（参见安装）。

目录

• 概念
• 安装
• CLI 用法
• UC → PlantUML 图表
• 引用关系图
• MCP 服务
• 用法
• 引用制品
• 开发
• 测试
• 发布版本
• 许可证

概念

每个工件在磁盘上都是一个包含 YAML frontmatter 块的纯 Markdown 文件——对 Git 友好、便于比较差异，也方便手动阅读和编辑。文件系统始终是事实来源；MCP 服务通过结构化且经过验证的读取、写入、列出和状态工具对其进行封装（参见用法）。

类型	用途
QA — 问答	结构化的引导式访谈（按 ISO/IEC 25010 特性组织），用于记录利益相关方的问答；通常是新规范工作的起点
GOL — 目标	高层业务目标——组织希望实现的目标，层级高于单个需求
PRB — 问题陈述	采用六西格玛风格的问题陈述，描述某个目标或需求所要解决的问题
REQ — 需求	单个系统需求（采用 EARS 风格表述），按 ISO/IEC 25010 特性分类
UC — 用例	描述特定使用场景的参与者与系统交互
RSK — 风险	风险登记项：原因／触发因素／后果、5x5 概率／影响评估（初始值和剩余值）、TARA 应对策略
DEC — 决策	通用决策记录（MADR 风格），不限于架构
ADR — 架构决策记录	特定于架构的决策记录；已弃用，请改用 DEC
TSK — 任务清单	实施任务检查清单，例如针对某项需求或功能
VCR — 验证案例记录	恰好验证一项 REQ 或 UC；包含一组 AC-NNN 验收标准（每项都附有一种 DTAIS 验证方法），以及一个总体覆盖结果（完整／部分／无）
SOP — 标准操作规程	分步骤的操作规程，包含 RASCI 职责分配和审批生命周期
FEAT — 功能	开发工作单元的计划／进度跟踪（.specmgr/feat/<id>/README.md）
SYSRS — 系统需求规范	通过交叉引用列表汇总 GOL/PRB/QA/UC/REQ/RSK/DEC-ADR/VCR，构成一份便于导航的规范；其结构遵循 ISO/IEC/IEEE 29148:2018（系统与软件工程——生命周期过程——需求工程），并包含少量仅供 specmgr 使用的补充内容（例如 ## Decisions、## Risks）

典型的规范工作从一次 QA 引导式访谈开始，访谈会梳理出 GOL（目标）和 PRB（问题）。这些内容为 REQ 和 UC 提供依据；随后对其进行风险评估（RSK）并由 DEC 决策支持，每项 REQ/UC 都通过一个 VCR 进行验证（每个 VCR 收集其验收标准），并通过 TSK 任务清单跟踪。SYSRS 将所有内容整合为一份遵循 ISO/IEC/IEEE 29148 结构的规范。SOP 和 FEAT 用于支持流程本身，而不属于这一链条。

QA -> GOL / PRB -> REQ / UC -> RSK / DEC -> TSK, VCR -> SYSRS (aggregates all)

安装

仅作为库使用（不包含 CLI 或 MCP 服务）：

pip install biz-dfch-specmgr

使用 CLI：

pip install "biz-dfch-specmgr[cli]"

使用 MCP 服务：

pip install "biz-dfch-specmgr[mcp]"

使用语义相似度搜索（find_related/find_similar_text，参见下文语义相似度搜索）时，请在 mcp 基础上添加 similarity extra：

pip install "biz-dfch-specmgr[mcp,similarity]"

或者使用 uv：

uv add "biz-dfch-specmgr[cli,mcp,similarity]"

CLI 用法

使用 CLI 可以生成 schema 和文档。我们会在 pre-commit 钩子和 ci.yml 中使用这些命令。

目前 CLI 尚无领域文档管理命令（创建／更新／状态等）——这些功能目前仅由 MCP 提供，参见 MCP 服务。CLI 包含 version、mcp（下文介绍）、一些跨领域／文档生成命令，以及图表命令——UC → PlantUML（参见 UC → PlantUML 图表）和引用关系图（参见引用关系图）（完整列表请运行 specmgr --help）。

specmgr version

UC → PlantUML 图表

Specmgr 可以将 UC 工件转换为 PlantUML 图表——确定性的用例图和包图，以及由 Agent 流程标注的时序图。

时序图（Agent 路径）。 generate_uc_sequence_diagram MCP 提示词（在 OpenCode 中：自触发的 uc-diagram 技能或 /uc-diagram <id> 命令）会运行冻结的规则手册流程：Agent 为每条 UNATTRIBUTED 消息标注归属（不确定时使用 question 工具提问），使用 validate_plantuml 验证，并以宿主原生方式写入 diagrams/uc/<id>.sequence.puml——specmgr 工具不会写入 .puml 文件。

确定性图表 + 工具（CLI，仅确定性操作——CLI 绝不会创建、覆盖或比较由 Agent 管理的 *.sequence.puml 文件）：

specmgr diagram uc <id>|all --out <dir> [--check]  # per-UC <id>.usecase.puml + package.puml; --check byte-diffs without writing (exit 0 ok / 1 diff / 2 usage-or-render error)
specmgr plantuml-check <path...>                   # validates any .puml through the chain (exit 0 valid / 1 invalid / 2 source misconfigured-or-unavailable / 3 inconclusive)
specmgr plantuml-encode <path|->                   # offline classic SoWkI… encoding

验证来源。 恰好有三个环境变量，按顺序，第一个已设置的变量是唯一使用的来源（不会回退、不会从 PATH 查找，也没有公共默认值）： SPECMGR_PLANTUML_JAR（plantuml.jar 路径）、SPECMGR_PLANTUML_BIN（符合 PlantUML CLI 契约的可执行文件）、SPECMGR_PLANTUML_URL（PlantUML 服务基础 URL）。全部未设置 ⇒ 仅进行离线结构验证。 除非设置该 URL，否则图表内容绝不会发送到 plantuml.com。

规范规则手册以 specmgr://uc/plantuml 资源的形式提供；完整的 MCP 接口见 docs/MCP.md。

参考关系图

Specmgr 可以将其工件之间确定性的交叉引用网络（list_references 工具背后的 <TYPE> <id> 标签词汇）渲染为 PlantUML 组件图：每个工件对应一个节点（标签 = 文档标题，截断至 SPECMGR_DIAGRAM_MAX_TITLE 限制，默认为 40）；每种工件类型对应一个构造型和一种颜色（固定的 14 项调色板）；节点按域分组到 component "TYPE" { … } 花括号组件组中；每条唯一引用对应一条无标签边（{src} --> {dst}）；所有位于环路上的边（自环和同一强连通分量中包含 ≥ 2 个节点的边）都使用红色无标签 -[#red]-> 箭头绘制；无法在磁盘上解析目标的引用会绘制为顶层 <<UNRESOLVED>> 节点。完全确定：相同的注册表和参数始终生成字节级完全相同的源文本。

MCP 工具。 get_reference_diagram(type, id, depth=1, reverse=False, include_feat=True, title=None) 渲染一个源文档的引用邻域（向前遍历至 depth 层，取值范围为 1..5；reverse=True 会额外添加直接指向该文档的引用，仅限直接引用）； get_reference_diagram_all(include_feat=True, title=None) 渲染整个注册表的关系图。两者都直接返回 PlantUML 源文本（不写入文件）；范围限定工具接受全部 13 个域（包括 adr），对于存在但有错误的源文件，会返回不抛出异常的 ParseFailureResult；全注册表工具不会因内容而抛出异常。

CLI（写入工件，仅限确定性模式）：

specmgr diagram refs <type> <id> [--depth N] [--reverse] [--no-feat] [--title T] [--out diagrams/refs] [--check]  # scoped → <id>.refs.puml
specmgr diagram refs all [--no-feat] [--title T] [--out diagrams/refs] [--check]                                   # registry-wide → reference-graph.puml

--no-feat 会移除所有 FEAT 节点，但显式指定的源除外（随后移除所有连接到已移除节点的边）。退出代码：0 已写入 / 无差异，1 存在 --check 差异（缺失文件也算差异）或缺少 mcp 扩展，2 用法或解析错误（type/id/depth 格式错误——不接受单独的 feat-NNN，请使用 list_feat 查找准确的 ID——源文件缺失、源文件存在但有错误，或 all 与源文件同时使用）。写入的工件不含仅用于结构检查的标头（按构造即可通过检查）。

验证。 specmgr plantuml-check <path...>（或通过源文本调用 validate_plantuml MCP 工具）会使用与 UC 图相同的严格验证链验证关系图（三个 SPECMGR_PLANTUML_* 源环境变量，参见 UC → PlantUML Diagrams；全部未设置时采用离线结构检查的最低要求）。

标签限制。 SPECMGR_DIAGRAM_MAX_TITLE（整数，默认值为 40）限制已解析节点的 H1 标签长度（按词边界截断并添加 …；若已设置但值无效，则回退至 40）；@startuml 图表标题会进行清理，但不会截断。该变量的已设置 / 有效 / 默认 / 已解析状态会通过 specmgr://config 资源的 diagram 部分报告（不会披露原始值）。

规范性规则手册作为 specmgr://reference-graph 资源提供；完整的 MCP 接口见 docs/MCP.md。

MCP 服务

需要 mcp 扩展。该服务提供用于文档管理的资源、工具和提示词，以及跨领域实用工具（例如 Markdown 格式化）。

所有资源、资源模板、工具和提示词的完整最新列表——包括参数、MIME 类型和说明——请参见 docs/MCP.md。 该文档由实时服务注册信息通过 specmgr mcp-docs 生成，并由 pre-commit 钩子和 CI 检查保持同步。

环境变量

每种文档类型都会将其 .md 文件存储在磁盘上的基础目录中——文件始终是唯一可信来源，每次调用工具时都会重新读取并解析，因此在两次调用之间手动编辑文件是安全的。

• ADR：基础目录默认为 docs/adr，可通过 SPECMGR_ADR_DIR 环境变量配置。此目录仅用于 ADR，不与其他文档类型共享。
• 需求（REQ）和未来的文档类型：共用一个根目录，可通过 SPECMGR_DOCS_DIR 环境变量配置（默认为 docs），系统会自动追加每种类型各自的子目录（例如，需求使用 docs/req）。
• 功能（FEAT）：基础目录默认为 .specmgr/feat，可通过 SPECMGR_FEAT_DIR 环境变量配置。与上面的 ADR 一样，此目录仅用于 FEAT，不通过 SPECMGR_DOCS_DIR 共享。
• PlantUML 验证来源（UC 图）：SPECMGR_PLANTUML_JAR（plantuml.jar 路径）、SPECMGR_PLANTUML_BIN（符合 PlantUML CLI 契约的可执行文件）和 SPECMGR_PLANTUML_URL（PlantUML 服务的基础 URL）——只使用第一个已设置的来源（不会回退到其他来源，不会搜索 PATH，也没有公共默认值）；若均未设置，则仅执行离线结构检查。使用方法请参阅 UC → PlantUML 图。
• 引用关系图的标签长度限制：SPECMGR_DIAGRAM_MAX_TITLE（整数，默认值为 40）——get_reference_diagram / get_reference_diagram_all PlantUML 图中，已解析节点的 H1 标签最大长度（在词边界处截断，并添加 …；图标题本身永不截断）。若该变量已设置但值无效（为空、非整数或小于 1），则回退到 40。specmgr://config 资源的 diagram 部分会报告该变量的设置状态、有效性、默认值和解析后的值（不会披露原始值）。

specmgr mcp 命令自身的传输设置同样由环境变量控制：SPECMGR_MCP_TRANSPORT 用于选择传输方式（默认为 stdio；允许的值为 stdio、sse 和 streamable-http）；SPECMGR_MCP_HOST（默认为 localhost）和 SPECMGR_MCP_PORT（默认为 8000）分别用于指定绑定地址和 TCP 端口，仅在 sse/streamable-http 模式下使用。命令的 --transport/--host/--port 标志优先于这些变量——选项表请参阅下文的 启动 MCP 服务。

设置 SPECMGR_SIMILARITY_DISABLED 环境变量（任意值；按是否存在判断）即可关闭 find_related/find_similar_text 工具（语义相似度搜索，需要安装 similarity 扩展）——完整行为（安装、服务启动时非阻塞的后台预热、模型缓存位置，以及功能已禁用或后端/模型加载失败时两个工具返回的结构化不可用结果）请参阅下文的 语义相似度搜索。

语义相似度功能的模型缓存目录由 FASTEMBED_CACHE_PATH 环境变量指定（这是第三方 fastembed 后端自身的变量，并非 SPECMGR_* 变量）：若未设置或值为空，则回退到 <tempdir>/fastembed_cache（例如，Linux 上为 /tmp/fastembed_cache）。解析后的目录会由 specmgr://config 资源的 similarity 部分报告——完整行为请参阅下文的 语义相似度搜索。

feat 域的两个后台缓存预热阶段（frontmatter 和 full-parse，由与相似度预热相同的统一服务启动预热线程运行）也可通过设置 SPECMGR_FEAT_WARMUP_DISABLED 环境变量关闭（任意值；按是否存在判断）——有关该线程的完整行为以及两个选择退出标志，请参阅下文 语义相似度搜索中的后台预热段落。

SPECMGR_TESTS_NO_DOTENV 是一个基于是否存在判断的测试/CI 哨兵变量（无默认值；测试运行之外绝不设置）：将其设为任意值，即可完全跳过 CLI 在模块级别默认加载 .env 的操作，这样测试运行就不会读取任何本地（被 git 忽略的）.env 配置，无论开发者的机器上设置了什么。 除非通过对应环境变量覆盖，否则上述所有基础目录都相对于 MCP 服务进程自身的当前工作目录解析；对于共享的 SPECMGR_DOCS_DIR 根目录，若服务是通过针对你的项目的 --directory/uv run --directory 启动，则不受此限制。如果该 CWD 与预期不符——例如，按照下文的 添加到 OpenCode 将 specmgr 添加到 MCP 宿主后——请读取 specmgr://config 资源，查看每个领域实际解析出的绝对基础目录，以及其环境变量是否已显式设置，无需访问服务所在主机的 shell。

语义相似度搜索

find_related 和 find_similar_text 工具使用本地句子嵌入按语义相似度对文档排序（推理时无需 API 密钥或网络）。find_related(type, id) 用于查找与现有文档最相关的文档；find_similar_text(query) 用于查找与自由格式查询最相似的文档，例如尚未保存的草稿，可用于创建前的去重和发现。无论该功能是否已安装或启用，这两个工具始终会显示在工具列表中：功能不可用时，每次调用都会返回结构化的 {available: false, reason, message} 结果，而不是抛出异常。

安装。 除 mcp 外，这些工具还需要可选的 similarity 扩展包，具体命令见安装（pip install "biz-dfch-specmgr[mcp,similarity]" 或 uv add "biz-dfch-specmgr[cli,mcp,similarity]"）。后端为运行 BAAI/bge-small-en-v1.5 的 fastembed（仅使用 CPU、ONNX Runtime、384 维）。

模型下载和缓存。 首次加载模型时，会从 Hugging Face Hub 下载一次（仅此时需要网络；之后推理完全离线）。如果设置了环境变量 $FASTEMBED_CACHE_PATH，模型会缓存在该路径下；否则会缓存在 <tempdir>/fastembed_cache 中（例如 Linux 上的 /tmp/fastembed_cache）。

服务启动时在后台预热。 除非同时设置了 SPECMGR_FEAT_WARMUP_DISABLED 和 SPECMGR_SIMILARITY_DISABLED，否则服务启动时会启动一个后台守护线程，按严格顺序执行三个预热阶段：feat 前置元数据阶段（开销低：仅处理前置元数据和 H1）、feat 完整解析阶段（开销高：处理完整的 feat 语料库），以及相似度阶段（将完整文档语料库嵌入内存缓存）。每个阶段都由各自的退出标志独立控制：设置 SPECMGR_FEAT_WARMUP_DISABLED（任意值；按是否存在判断）会跳过两个 feat 阶段；设置 SPECMGR_SIMILARITY_DISABLED（任意值；按是否存在判断）会跳过相似度阶段，无论是否安装了 similarity 扩展包。如果缺少该扩展包，或者模型加载失败，相似度阶段会在内部运行可用性检查，然后立即退出，不写入缓存（且不会抛出异常）。该线程不会阻塞服务启动，服务启动不会等待它完成（如需加载或下载模型，这些操作会在线程内执行，不会在启动流程中执行）；如果预热过程中途失败，会记录日志并吞掉异常，缓存则会保留部分预热结果。这样做是为了加快首次工具调用：缓存尚未预热时，list_feat 会在请求处理过程中扫描并重新解析整个 feat 语料库，而相似度工具则会按需嵌入该语料库——两者都可能耗费数分钟的 CPU 时间。

退出。 设置 SPECMGR_SIMILARITY_DISABLED（任意值；按是否存在判断）可在不卸载扩展包的情况下禁用该功能，例如完全跳过模型下载、在从未下载模型的主机上禁用该功能，或释放模型和缓存占用的内存。无论如何，这两个工具都会保持注册状态。设置 SPECMGR_FEAT_WARMUP_DISABLED（任意值；按是否存在判断）可跳过两个 feat 缓存预热阶段，不会产生其他影响，例如在很少调用 list_feat/get_feat 的主机上使用。设置这两个退出标志后，则完全不会启动预热线程。

信息查询。 读取 specmgr://config 资源可查看该功能的静态配置——其中的 similarity 部分会报告是否安装了 similarity 扩展包、是否设置了退出标志、模型名称以及解析后的缓存目录（仅静态信息；读取该资源不会加载模型或创建缓存目录）；其中的 feat_warmup_disabled 字段会报告是否设置了 feat 预热退出标志。读取 specmgr://version 资源可查看已安装的 fastembed 版本（未安装该扩展包时为 null）。

启动 MCP 服务

使用 mcp 命令启动服务：

specmgr mcp

默认情况下，它通过 stdio 运行，供将其作为子进程启动的 MCP 宿主使用（见下文的添加到 OpenCode）。它也可以通过 SSE/网络运行：

specmgr mcp --transport sse --host localhost --port 8000

或者通过当前规范中的 streamable-http 传输方式运行，该方式取代了用于 HTTP 部署的旧版/已弃用 sse 传输方式：

specmgr mcp --transport streamable-http --host localhost --port 8000

选项	环境变量	默认值	描述
--transport / -t	SPECMGR_MCP_TRANSPORT	stdio	传输模式：stdio、sse 或 streamable-http
--host / -h	SPECMGR_MCP_HOST	localhost	绑定地址（仅限 SSE/streamable-http 模式）
--port / -p	SPECMGR_MCP_PORT	8000	TCP 端口（仅限 SSE/streamable-http 模式）

添加到 OpenCode

要将 specmgr MCP 服务添加到 OpenCode 配置中：

1. 打开 OpenCode 配置文件（通常为 ~/.config/opencode/opencode.json 或 ~/.config/opencode/opencode.jsonc）

2. 在 mcp 部分添加配置（并通过 stdio 使用）。

   仅使用不带 --directory 且未设置 SPECMGR_*_DIR 环境变量的 uvx --from biz-dfch-specmgr[mcp] specmgr mcp 命令并不安全：服务会将每个基础目录（docs、docs/adr、.specmgr/feat……）解析为相对于其进程当前工作目录的路径，而 MCP 宿主可以从任意位置启动该进程，不一定是你的项目根目录。请从以下两个选项中选择一个，而不要使用上述命令：

   选项 A — 使用 --directory 固定工作目录（这是全局 uv/uvx 标志，因此必须放在 --from 之前）：

   "specmgr": {
     "type": "local",
     "enabled": true,
     "command": [
       "uvx",
       "--directory",
       "<path-to-your-project>",
       "--from",
       "biz-dfch-specmgr[mcp]",
       "specmgr",
       "mcp"
     ]
   }
   

若要同时启用语义相似度搜索功能（find_related/find_similar_text），请将上方 --from 值中的 [mcp] 改为 [mcp,similarity] — 安装和运行时激活的详情请参见该部分。

选项 B — 显式设置目录环境变量，以替代（或配合）--directory：

"specmgr": {
  "type": "local",
  "enabled": true,
  "command": [
    "uvx",
    "--from",
    "biz-dfch-specmgr[mcp]",
    "specmgr",
    "mcp"
  ],
  "environment": {
    "SPECMGR_DOCS_DIR": "<path-to-your-project>/docs",
    "SPECMGR_ADR_DIR": "<path-to-your-project>/docs/adr",
    "SPECMGR_FEAT_DIR": "<path-to-your-project>/.specmgr/feat"
  }
}

这里同样适用将 --from 值中的 [mcp] 改为 [mcp,similarity]，以启用语义相似度搜索。

两种选项（或同时使用）都能让解析出的基础目录不受 MCP 宿主实际启动服务的位置影响。无论选择哪种方式，都可以通过读取 specmgr://config 资源来确认是否生效；该资源会报告每个领域实际解析出的绝对基础目录，以及是否显式设置了对应的环境变量。

选项 C — 从本地源代码检出目录运行（开发）。 选项 A 和 B 都使用 uvx（uv tool run），它会从配置的索引（默认是 PyPI）将 biz-dfch-specmgr[...] 作为具名包解析到临时工具环境中 — 它们始终运行已发布版本，不会运行本地或尚未发布的更改。若要改为运行磁盘上的指定目录中的项目 — 直接使用其自身的 pyproject.toml、锁文件和源代码树，包括尚未发布的/dev 分支提交 — 请使用 uv run --directory <path-to-your-checkout>（不带 --from，也不使用 uvx）：

"specmgr": {
  "type": "local",
  "enabled": true,
  "command": [
    "uv",
    "run",
    "--directory",
    "<path-to-your-checkout>",
    "--extra",
    "mcp",
    "--extra",
    "similarity",
    "specmgr",
    "mcp"
  ]
}

贡献者/开发者可通过此方式让 OpenCode 指向自己的 git 检出目录，而不是已发布的包。可重复使用的 --extra 标志（或用于启用所有内容的 --all-extras）用于控制要同步到本地运行环境中的可选依赖项，与 PyPI 上发布的内容无关 — 如果不需要语义相似度搜索，可移除 --extra similarity。

3. 保存文件并重启 OpenCode

用法

连接后，你的 AI 助手会看到每个文档领域的两类工具：每个领域专属工具（create_<d>、get_<d>、list_<d>、parse_<d>，以及 get_<d>_example/get_<d>_template），还有通用分派工具。通用分派工具接受 type= 参数，在所有领域中的行为一致：update（编辑整个正文或指定行范围）、set_status、set_classification、delete 和 validate（ADR 是唯一例外，它早于此模式，因此使用自己的专用工具）。完整列表请参阅 docs/MCP.md。

服务还提供提示词（例如 create_req、update_req、implement_task）——这些是引导式、多轮的访谈流程，是以对话方式撰写文档的推荐方式，而非逐个调用工具。大多数 MCP 宿主会将其显示为斜杠命令或提示词选择器。

日常使用时，你完全不必了解任何工具名称——只需用日常语言向已连接的 AI 助手提出要求，例如：

• “创建一个减少客户入门用时的新目标。”
• “列出所有未解决的风险，并显示高严重性风险。”
• “为需求 <id> 起草任务列表。”

要解析制品中已有的交叉引用，请参阅 引用制品。

引用制品

specmgr 文档会通过结构化位置中的 <TYPE> <uuid> 行互相交叉引用（VCR 的 ## Verifies、SYSRS 的各节项目符号列表、DEC 的 ## Related Artifacts）；此外，在任意自由格式正文中，也可使用任何引用标签，包括携带某个功能自身 ID 的 FEAT 标签（完整的 feat-NNN-slug 或不带 slug 的 feat-NNN 编号；上述结构化位置仍仅使用 uuid）。list_references MCP 工具可解析这些引用：将任意制品（<type> <id>）交给你的助手，它便会列出制品正文中的所有交叉引用标签，并解析出被引用文档的类型、ID、标题（其 H1）和磁盘路径。结果与所有 list_* 工具一样采用分页；磁盘上无法解析的引用会作为带有 error 的行返回（不视为失败），其他自由格式或不符合规范的文本则会被忽略。

在 opencode 中，/refs <type> <id> 斜杠命令（.opencode/command/refs.md）封装了同一工具：它会委派给只读的 ref-finder 子 Agent（.opencode/agent/ref-finder.md），由该子 Agent 调用 list_references 并报告结果行，同时标记任何 NOT FOUND 引用。/refs 需要 opencode——该工具本身是纯 MCP 工具，可从任何 MCP 客户端直接调用。

同样在 opencode 中，项目本地的 specmgr-refs 技能（.opencode/skills/specmgr-refs/SKILL.md）是由 Agent 主动发起的入口：当任务符合引用检索相关表述时，它会自动加载，将单文档请求路由到 list_references 工具、ref-finder 子 Agent 或 /refs 命令，并规范 /refs 和 ref-finder 未覆盖的图谱、批量及反向工作流。

开发

安装开发依赖

uv sync --all-extras

安装 pre-commit 钩子（仅需一次）

uv run --frozen pre-commit install

uv sync 只会将 Python 依赖安装到虚拟环境中——它不会将 .pre-commit-config.yaml 中的钩子注册到 git，因此请在每次克隆后、首次提交前运行一次。

运行代码检查工具

uv run --frozen ruff format --check
uv run --frozen ruff check
uv run --frozen pylint $(git ls-files '*.py')

运行测试

uv run --frozen pytest -n auto --cov=src --cov-report=

测试

你可以通过 MCP Inspector 直接测试 MCP 服务，可使用其 CLI（可编写脚本）客户端，也可使用 TUI（交互式终端）客户端。

前提条件

• 已安装 mcp 额外组件（参见安装），这样就会有 .venv/bin/specmgr。
• npx（随 Node.js 一同提供， 版本为 22.19.0 或更高）——无需单独安装 Inspector；它会通过 npx @modelcontextprotocol/inspector 按需运行。

直接将 venv 中的 specmgr 二进制文件指定为 Inspector 的目标（而不是使用 uv run specmgr mcp），这样 uv run 自身的标志（例如 --frozen）就不会被误认为是 Inspector 标志：

npx @modelcontextprotocol/inspector --tui .venv/bin/specmgr mcp
npx @modelcontextprotocol/inspector --cli .venv/bin/specmgr mcp --method tools/list

CLI 示例

每次 CLI 调用都会建立连接、运行一次请求、打印结果，然后退出——适用于脚本编写或快速冒烟测试。

获取 specmgr://version 资源：

npx @modelcontextprotocol/inspector --cli .venv/bin/specmgr mcp \
  --method resources/read --uri specmgr://version

通过 list_tsk 工具列出任务列表：

npx @modelcontextprotocol/inspector --cli .venv/bin/specmgr mcp \
  --method tools/call --tool-name list_tsk

通过 get_tsk 工具获取一个任务列表（将 <id> 替换为上方 list_tsk 输出中的实际任务列表 ID）：

npx @modelcontextprotocol/inspector --cli .venv/bin/specmgr mcp \
  --method tools/call --tool-name get_tsk --tool-arg id=<id>

在上述任一命令中添加 --format json，即可获得机器可读的输出，例如通过管道传入 jq。

使用 TUI 连接

npx @modelcontextprotocol/inspector --tui .venv/bin/specmgr mcp

此命令会将服务作为临时 stdio 目标启动，并打开已预选该目标的终端 UI（与 CLI 不同，TUI 没有 --server <name> 标志——它会列出可用的服务，由你选择；不过只有一个临时目标时，也没有其他选项）。按 c 连接，然后使用选项卡进行探索：

• t — **Tools（工具）**选项卡：浏览并调用工具（例如 get_tsk），使用基于表单的输入。
• r — **Resources（资源）**选项卡：浏览并读取资源（例如 specmgr://version、specmgr://iso25010）。
• m — **Prompts（提示词）**选项卡：列出并呈现提示词。
• p — **Protocol（协议）**选项卡：原始 JSON-RPC 请求/响应历史记录，适用于调试。
• o — **Console（控制台）**选项卡：已连接的 specmgr mcp 进程的 stderr（回溯信息会显示在此处）。
• c / d — 连接 / 断开连接；Esc 或 Ctrl+C — 退出。

TUI 需要真实的 TTY（支持原始模式），无法在无头 CI 作业中运行——请改用 CLI 客户端。

发布

规范的发布流程是 SOP 执行 biz.dfch.SpecMgr 发布 （SOP 98537416）。如果本节、脚本或命令与 SOP 有任何不一致，以 SOP 为准。

使用 OpenCode 命令（推荐）

/release [X.Y.Z | patch | minor | major] [--dry-run]

该命令会运行分阶段脚本，并执行 SOP 中需要 Agent 判断的步骤：与您确认解析出的版本、整理变更日志的 [Unreleased] 部分、在将 dev 合并到 main 之前暂停等待合并关卡，并对失败进行分类处理，且绝不会自动重试。

直接使用脚本

SOP 中的每一步都对应一个确定且幂等的阶段（每一步的 SOP 中都附有手动备用命令）：

scripts/release.sh resolve minor         # print the target version (e.g. 0.15.0); no mutation
scripts/release.sh precheck 0.15.0       # fail-fast pre-release checks, incl. the feat closeout gate and the previous-release branch cleanup
scripts/release.sh bump 0.15.0           # pyproject.toml + uv.lock
scripts/release.sh changelog 0.15.0      # [Unreleased] -> dated section
scripts/release.sh commit-push 0.15.0    # 3-file release commit, push dev, wait for CI
scripts/release.sh pr-create 0.15.0      # dev->main release PR, wait for checks (no merge)
scripts/release.sh pr-merge 0.15.0       # ff-only merge (after maintainer go-ahead)
scripts/release.sh tag-push 0.15.0       # tag on main, push the tag, back to dev
scripts/release.sh publish-wait 0.15.0   # the four publish.yml jobs
scripts/release.sh release-notes 0.15.0  # verify the release + set the GH release notes
scripts/release.sh status 0.15.0         # where does this release stand?
scripts/release.sh all 0.15.0            # the whole chain, TTY only (interactive merge gate)

precheck 以 feat-233（问题 #233）新增的两个子项结束：feat 收尾关卡——当前发布窗口内（自上一个标签以来）发布的每个 .specmgr/feat/feat-*/ 文件夹，都必须在其 README frontmatter 中将状态收尾为 status: done；若不符合要求，预检将失败，并针对每个违规 feat 给出一条可执行的说明（处理方式：在 dev 上将指定 feat 收尾为 done，提交，然后重新运行 precheck）；以及上一版本分支清理——删除上一版本或更早版本遗留的 feat-*/fix/* 分支，包括本地和 origin 端；每次删除都必须由该分支已合并的 PR 证明，并通过四项风险检查（--dry-run 会使此子项仅报告结果：输出将删除/将保留的表格，不删除任何引用）。

变更日志的整理（SOP 第 3 步）是 Agent 或手动步骤：changelog 阶段只会将已整理好的 [Unreleased] 部分移入带日期的形式。

手动备用方案

按照 SOP 逐步操作——每个步骤都附有一段手动备用方案说明。要点：更新 pyproject.toml 中的 version，并将 CHANGELOG.md 的 [Unreleased] 部分移至新的带日期的 ## [x.y.z] - YYYY-MM-DD 部分；执行 uv lock；仅将 pyproject.toml、uv.lock 和 CHANGELOG.md 提交为 chore(release): bump version to vX.Y.Z，并推送到 dev；CI 通过后，创建 dev → main 拉取请求，并以仅快进方式合并（git merge --ff-only dev——绝不可创建合并提交或执行 squash：main 必须始终是 dev 的严格祖先）；然后在 main 上创建 git tag vX.Y.Z，推送标签，并等待发布工作流完成。

注意：推送上述标签后，.github/workflows/publish.yml 会自动处理发布的其余工作——它会通过 Trusted Publishing（OIDC，不使用存储的令牌）构建并将 sdist/wheel 发布到 TestPyPI，然后发布到 PyPI；创建附有构建产物的对应 GitHub Release；并通过 mcp-publisher/GitHub OIDC 将 server.json（仓库根目录中的 MCP Registry 发布者清单——参见 server.json 格式规范）发布到 MCP Registry。截至 v0.1.0，biz-dfch-specmgr 已在 PyPI 和 MCP Registry 上发布。

许可证

AGPL-3.0-or-later