vod-devkit 0.4.4 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/CHANGELOG.md +42 -0
  2. package/QUICKSTART.md +1 -1
  3. package/README.en.md +190 -56
  4. package/README.md +210 -56
  5. package/bin/vod-devkit +502 -460
  6. package/contract/tools.schema.json +114 -7
  7. package/integrations/codeartsdoer/host.json +11 -0
  8. package/integrations/codex/host.json +20 -0
  9. package/integrations/dsh/host.json +15 -0
  10. package/integrations/hermes/host.json +20 -0
  11. package/integrations/opencode/command/vod-doctor.md +10 -0
  12. package/integrations/opencode/host.json +28 -0
  13. package/package.json +13 -10
  14. package/plugins/vod-devkit/.codex-plugin/plugin.json +1 -1
  15. package/plugins/vod-devkit/build-info.json +3 -3
  16. package/plugins/vod-devkit/skills/vod-core/SKILL.md +43 -15
  17. package/plugins/vod-devkit/skills/vod-core/references/acceptance-criteria.md +9 -0
  18. package/plugins/vod-devkit/skills/vod-core/references/verification-method.md +29 -0
  19. package/plugins/vod-devkit/skills/vod-feedback-collect/SKILL.md +57 -11
  20. package/plugins/vod-devkit/skills/vod-feedback-collect/references/acceptance-criteria.md +28 -0
  21. package/plugins/vod-devkit/skills/vod-feedback-collect/references/verification-method.md +31 -0
  22. package/plugins/vod-devkit/skills/vod-problem-classification-rules/SKILL.md +3 -1
  23. package/plugins/vod-devkit/skills/vod-scoring-rules/SKILL.md +22 -1
  24. package/plugins/vod-devkit/vod_mcp/__init__.py +1 -1
  25. package/plugins/vod-devkit/vod_mcp/attribution.py +378 -0
  26. package/plugins/vod-devkit/vod_mcp/config_forms.py +154 -0
  27. package/plugins/vod-devkit/vod_mcp/guardrails.py +25 -0
  28. package/plugins/vod-devkit/vod_mcp/host_adapters/__init__.py +26 -0
  29. package/plugins/vod-devkit/vod_mcp/host_adapters/base.py +73 -0
  30. package/plugins/vod-devkit/vod_mcp/host_adapters/codearts.py +57 -0
  31. package/plugins/vod-devkit/vod_mcp/host_adapters/codex.py +209 -0
  32. package/plugins/vod-devkit/vod_mcp/host_adapters/dsh.py +176 -0
  33. package/plugins/vod-devkit/vod_mcp/host_adapters/generic.py +132 -0
  34. package/plugins/vod-devkit/vod_mcp/host_adapters/hermes.py +76 -0
  35. package/plugins/vod-devkit/vod_mcp/host_adapters/opencode.py +52 -0
  36. package/plugins/vod-devkit/vod_mcp/hosts.py +100 -0
  37. package/plugins/vod-devkit/vod_mcp/packs.py +19 -3
  38. package/plugins/vod-devkit/vod_mcp/payload.py +174 -0
  39. package/plugins/vod-devkit/vod_mcp/remote_app.py +100 -0
  40. package/plugins/vod-devkit/vod_mcp/server.py +43 -16
  41. package/plugins/vod-devkit/vod_mcp/skills_registry.py +124 -0
  42. package/plugins/vod-devkit/vod_mcp/tools.py +455 -55
  43. package/plugins/vod-devkit/vod_mcp/transport_remote.py +289 -0
  44. package/plugins/vod-devkit/vod_mcp/update_check.py +133 -0
  45. package/skills/vod-core/SKILL.md +43 -15
  46. package/skills/vod-core/references/acceptance-criteria.md +9 -0
  47. package/skills/vod-core/references/verification-method.md +29 -0
  48. package/skills/vod-feedback-collect/SKILL.md +57 -11
  49. package/skills/vod-feedback-collect/references/acceptance-criteria.md +28 -0
  50. package/skills/vod-feedback-collect/references/verification-method.md +31 -0
  51. package/skills/vod-problem-classification-rules/SKILL.md +3 -1
  52. package/skills/vod-scoring-rules/SKILL.md +22 -1
  53. package/vod_mcp/__init__.py +1 -1
  54. package/vod_mcp/attribution.py +378 -0
  55. package/vod_mcp/config_forms.py +154 -0
  56. package/vod_mcp/guardrails.py +25 -0
  57. package/vod_mcp/host_adapters/__init__.py +26 -0
  58. package/vod_mcp/host_adapters/__pycache__/__init__.cpython-314.pyc +0 -0
  59. package/vod_mcp/host_adapters/__pycache__/base.cpython-314.pyc +0 -0
  60. package/vod_mcp/host_adapters/__pycache__/codearts.cpython-314.pyc +0 -0
  61. package/vod_mcp/host_adapters/__pycache__/codex.cpython-314.pyc +0 -0
  62. package/vod_mcp/host_adapters/__pycache__/dsh.cpython-314.pyc +0 -0
  63. package/vod_mcp/host_adapters/__pycache__/generic.cpython-314.pyc +0 -0
  64. package/vod_mcp/host_adapters/__pycache__/hermes.cpython-314.pyc +0 -0
  65. package/vod_mcp/host_adapters/__pycache__/opencode.cpython-314.pyc +0 -0
  66. package/vod_mcp/host_adapters/base.py +73 -0
  67. package/vod_mcp/host_adapters/codearts.py +57 -0
  68. package/vod_mcp/host_adapters/codex.py +209 -0
  69. package/vod_mcp/host_adapters/dsh.py +176 -0
  70. package/vod_mcp/host_adapters/generic.py +132 -0
  71. package/vod_mcp/host_adapters/hermes.py +76 -0
  72. package/vod_mcp/host_adapters/opencode.py +52 -0
  73. package/vod_mcp/hosts.py +100 -0
  74. package/vod_mcp/packs.py +19 -3
  75. package/vod_mcp/payload.py +174 -0
  76. package/vod_mcp/remote_app.py +100 -0
  77. package/vod_mcp/server.py +43 -16
  78. package/vod_mcp/skills_registry.py +124 -0
  79. package/vod_mcp/tools.py +455 -55
  80. package/vod_mcp/transport_remote.py +289 -0
  81. package/vod_mcp/update_check.py +133 -0
@@ -12,7 +12,7 @@ from pathlib import Path
12
12
  # Hermes 等宿主出于安全过滤环境变量,stdio 子进程只继承白名单)
13
13
  sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
14
14
 
15
- from vod_mcp import packs, policy as policy_mod, tools # noqa: E402
15
+ from vod_mcp import guardrails, packs, tools # noqa: E402
16
16
 
17
17
  _PROTOCOL_VERSION = "2025-06-18"
18
18
  _client_info = {}
@@ -26,12 +26,16 @@ def _error(req_id, code, message):
26
26
  return {"jsonrpc": "2.0", "id": req_id, "error": {"code": code, "message": message}}
27
27
 
28
28
 
29
- def handle(message: dict) -> dict | None:
29
+ def handle(message: dict, client_info: dict | None = None) -> dict | None:
30
+ """JSON-RPC 分派(两面共用:stdio 逐行调用;HTTP 面每请求调用一次)。
31
+
32
+ client_info 由传输层提供(HTTP 面=固定标识 + 认证形态,stdio 面=握手自报)。
33
+ """
30
34
  method = message.get("method", "")
31
35
  req_id = message.get("id")
32
36
  if method == "initialize":
33
37
  global _client_info
34
- _client_info = (message.get("params") or {}).get("clientInfo") or {}
38
+ _client_info = client_info or (message.get("params") or {}).get("clientInfo") or {}
35
39
  return _result(req_id, {
36
40
  "protocolVersion": _PROTOCOL_VERSION,
37
41
  "capabilities": {"tools": {}},
@@ -40,7 +44,9 @@ def handle(message: dict) -> dict | None:
40
44
  "本产品的不满/建议/期望(触发词:慢/报错/体验差/希望支持/提单等)。"
41
45
  "提交前必须征得用户明确同意(用户抱怨本身不构成同意);提交回执"
42
46
  "echo.contents 必须逐条原样转述给用户(「已收录原话:<content>」),"
43
- "禁止改写、概括、增删字词。product 归因由安装绑定完成,禁止询问用户。"
47
+ "禁止改写、概括、增删字词。product 归因:原话唯一命中可直接用;"
48
+ "未命中或多产品歧义时必须问用户一次\"这条是哪个产品的反馈\","
49
+ "回答填 product;用户说不知道就告知他缺产品不能提交,不要猜。不许不填直接提交。"
44
50
  ),
45
51
  "serverInfo": {
46
52
  "name": "vod-devkit",
@@ -57,18 +63,9 @@ def handle(message: dict) -> dict | None:
57
63
  params = message.get("params") or {}
58
64
  name = params.get("name") or ""
59
65
  args = params.get("arguments") or {}
60
- pol = policy_mod.load_policy()
61
- verdict, msg = policy_mod.decide(
62
- policy_mod.check_tool_call(pol, name, args) if name else [])
63
- if verdict == "deny":
64
- return _error(req_id, -32010, f"[guard:deny] {msg}")
65
- if verdict == "confirm":
66
- return _error(req_id, -32011, f"[guard:confirm] {msg}")
67
- text_hits = policy_mod.check_text(
68
- pol, json.dumps(policy_mod.guard_scope(args), ensure_ascii=False))
69
- if text_hits:
70
- return _error(req_id, -32010,
71
- f"[guard:deny] {policy_mod.decide(text_hits)[1]}")
66
+ verdict, msg, code = guardrails.check(name, args)
67
+ if verdict != "allow":
68
+ return _error(req_id, code, msg)
72
69
  try:
73
70
  out = tools.dispatch(name, args, _client_info)
74
71
  return _result(req_id, {
@@ -83,7 +80,27 @@ def handle(message: dict) -> dict | None:
83
80
  return None
84
81
 
85
82
 
83
+ def _consume_payload_marker() -> None:
84
+ """载荷标记:install 换完载荷写它=该重启;被真正跑起来的进程消费掉。"""
85
+ try:
86
+ from vod_mcp import payload as _payload
87
+ _payload.consume_marker()
88
+ except Exception:
89
+ pass
90
+
91
+
86
92
  def main():
93
+ _consume_payload_marker()
94
+ import argparse
95
+ ap = argparse.ArgumentParser(prog="vod-mcp-server",
96
+ description="vod-devkit MCP server(默认 stdio)")
97
+ ap.add_argument("--transport", choices=["stdio", "remote"], default="stdio",
98
+ help="stdio(默认,宿主拉起子进程);remote(Streamable HTTP,"
99
+ "一个进程服务多个 agent)")
100
+ ap.add_argument("--port", type=int, default=9528, help="remote 端口(默认 9528)")
101
+ ap.add_argument("--host", default="127.0.0.1", help="remote 绑定地址(默认回环)")
102
+ args, _unknown = ap.parse_known_args()
103
+
87
104
  # 启动自诊(排障:写 /tmp,宿主过滤环境变量时可观察实际 env)
88
105
  try:
89
106
  tools._ensure_first_boot() # D-key-guard-3①:首启标记+构建机残留清理(preset 兜底)
@@ -93,6 +110,16 @@ def main():
93
110
  f"VOD_PACKS={os.environ.get('VOD_PACKS')!r} "
94
111
  f"distribution={tools._distribution()} "
95
112
  f"cwd={os.getcwd()}")
113
+ if args.transport == "remote":
114
+ try:
115
+ from vod_mcp import transport_remote
116
+ except ImportError as e: # 零依赖红线:远程面才需要 SDK
117
+ print("[vod-devkit] 远程面需要官方 MCP SDK:\n"
118
+ " pip install 'vod-devkit[remote]' # 或 pip install 'mcp>=1.0'\n"
119
+ f"(stdio 形态不需要任何第三方依赖;导入失败:{e})", file=sys.stderr)
120
+ sys.exit(2)
121
+ sys.exit(transport_remote.serve(args.host, args.port))
122
+
96
123
  for line in sys.stdin:
97
124
  line = line.strip()
98
125
  if not line:
@@ -0,0 +1,124 @@
1
+ """领域技能披露(MCP 侧,devkit 双轨模型的第二轨)。
2
+
3
+ 为什么需要第二轨:领域规则技能(分类/评分)目前靠"安装器把 SKILL.md 拷进
4
+ 宿主的原生技能目录"分发,而各宿主目录是独立副本——本仓实锤过多次漂移
5
+ (skillHashes 只能事后发现,装完就分叉)。disclosure 让技能文本成为
6
+ **server data**:任何 MCP 宿主(包括没有原生技能目录的宿主,如 dsh headless)
7
+ 都能按需取到与包内完全一致的规则全文,且改规则不必碰四份宿主拷贝。
8
+
9
+ 分工(与 devkit 一致):
10
+ - 元技能(vod-core / vod-feedback-collect)仍原生安装——它们的价值在
11
+ 宿主侧自动激活(触发词命中),走工具调用会丢掉激活时机。
12
+ - 领域规则技能由本模块披露,归属 knowledge pack:pack 被裁剪时拒绝并
13
+ 给恢复指引,不静默返回空。
14
+ """
15
+ import re
16
+ from pathlib import Path
17
+
18
+ SKILLS_ROOT = Path(__file__).resolve().parent.parent / "skills"
19
+
20
+ # 技能 → 归属 pack(core 常驻;knowledge 可裁剪)
21
+ SKILL_PACK = {
22
+ "vod-problem-classification-rules": "knowledge",
23
+ "vod-scoring-rules": "knowledge",
24
+ }
25
+ META_SKILLS = ("vod-core", "vod-feedback-collect")
26
+
27
+ _BODY_CAP = 12000 # 单技能全文上限(超出截断并标注,不静默丢内容)
28
+
29
+ # 契约纪律:披露内容里的内部机制词不因"技能是内部文档"而豁免——
30
+ # 这些文本会进模型上下文并可能被复述给终端用户。
31
+ _INTERNAL_WORDS = re.compile(r"(t_vod_[a-z_]+|jdbc:|mysql://)")
32
+
33
+
34
+ class SkillError(Exception):
35
+ """披露失败(未知技能/未启用 pack)——调用方转成 MCP error 对象。"""
36
+
37
+ def __init__(self, message: str, code: int = -32010):
38
+ super().__init__(message)
39
+ self.code = code
40
+
41
+
42
+ def _frontmatter(text: str) -> dict:
43
+ """取 SKILL.md 的 YAML frontmatter 键值(只认一层,不引 yaml 依赖)。"""
44
+ out = {}
45
+ if not text.startswith("---"):
46
+ return out
47
+ body = text.split("---", 2)[1] if text.count("---") >= 2 else ""
48
+ for line in body.splitlines():
49
+ if ":" not in line:
50
+ continue
51
+ k, v = line.split(":", 1)
52
+ out[k.strip()] = v.strip().strip("'\"")
53
+ return out
54
+
55
+
56
+ def _skill_dirs() -> list:
57
+ if not SKILLS_ROOT.is_dir():
58
+ return []
59
+ return sorted(p for p in SKILLS_ROOT.iterdir()
60
+ if p.is_dir() and (p / "SKILL.md").exists())
61
+
62
+
63
+ def _server_face() -> bool:
64
+ from vod_mcp import tools
65
+ return bool(tools._SERVER_FACE.get())
66
+
67
+
68
+ def list_skills(params: dict) -> dict:
69
+ """列出可披露的技能(元技能一并列出,标出 pack 与是否原生安装)。"""
70
+ from vod_mcp import packs
71
+ enabled = set(packs.enabled_packs())
72
+ items = []
73
+ for d in _skill_dirs():
74
+ text = (d / "SKILL.md").read_text(encoding="utf-8")
75
+ meta = _frontmatter(text)
76
+ pack = SKILL_PACK.get(d.name, "core")
77
+ items.append({
78
+ "name": d.name,
79
+ "pack": pack,
80
+ "enabled": pack in enabled,
81
+ "native": d.name in META_SKILLS,
82
+ "description": meta.get("description", ""),
83
+ "chars": len(text),
84
+ })
85
+ return {"skills": items, "packs": sorted(enabled),
86
+ "note": "领域规则技能用 vod_retrieve_skill 取全文;元技能由宿主原生"
87
+ "加载,只在本工具里列名以便路由。"}
88
+
89
+
90
+ def retrieve_skill(params: dict) -> dict:
91
+ """按名取技能全文(含 frontmatter + 正文)。owner-pack 裁剪即拒绝。"""
92
+ from vod_mcp import packs
93
+ name = (params or {}).get("name") or ""
94
+ name = name.strip()
95
+ if not name:
96
+ raise SkillError("name 必填(先用 vod_list_skills 查名字)", -32602)
97
+ d = SKILLS_ROOT / name
98
+ if not re.fullmatch(r"[a-z0-9][a-z0-9-]{2,63}", name) or not (d / "SKILL.md").exists():
99
+ known = [p.name for p in _skill_dirs()]
100
+ raise SkillError(f"未知技能 {name!r};可用:{'、'.join(known)}", -32602)
101
+ pack = SKILL_PACK.get(name, "core")
102
+ enabled = set(packs.enabled_packs())
103
+ if pack not in enabled:
104
+ raise SkillError(
105
+ f"技能 {name} 属于 {pack} pack,当前安装未启用(VOD_PACKS="
106
+ f"{','.join(sorted(enabled))})——如需启用,重跑 install 并带上 "
107
+ f"--packs {','.join(sorted(enabled | {pack}))}", -32010)
108
+ text = (d / "SKILL.md").read_text(encoding="utf-8")
109
+ truncated = False
110
+ if len(text) > _BODY_CAP:
111
+ text = text[:_BODY_CAP]
112
+ truncated = True
113
+ if _INTERNAL_WORDS.search(text):
114
+ # 不拦内容(规则文本是内部资产),但给出复述纪律提醒
115
+ note = "注意:本技能含内部表名/连接串字样,向终端用户复述时不要照抄。"
116
+ else:
117
+ note = ""
118
+ out = {"name": name, "pack": pack, "chars": len(text), "truncated": truncated,
119
+ "content": text, "note": note}
120
+ # 服务面(HTTP)不发布服务器本机路径——对齐 devkit「remote 不给 skillRoot」:
121
+ # 未鉴权的远程面不该把自己的安装路径交出去。
122
+ if not _server_face():
123
+ out["path"] = str(d / "SKILL.md")
124
+ return out