vod-devkit 0.5.0 → 0.5.2

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 (66) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/QUICKSTART.md +1 -1
  3. package/README.en.md +190 -57
  4. package/README.md +194 -75
  5. package/bin/vod-devkit +436 -426
  6. package/contract/tools.schema.json +78 -8
  7. package/integrations/codeartsdoer/host.json +11 -0
  8. package/package.json +4 -1
  9. package/plugins/vod-devkit/.codex-plugin/plugin.json +1 -1
  10. package/plugins/vod-devkit/build-info.json +3 -3
  11. package/plugins/vod-devkit/skills/vod-core/SKILL.md +12 -4
  12. package/plugins/vod-devkit/skills/vod-core/references/acceptance-criteria.md +9 -0
  13. package/plugins/vod-devkit/skills/vod-core/references/verification-method.md +29 -0
  14. package/plugins/vod-devkit/skills/vod-feedback-collect/SKILL.md +57 -11
  15. package/plugins/vod-devkit/skills/vod-feedback-collect/references/acceptance-criteria.md +28 -0
  16. package/plugins/vod-devkit/skills/vod-feedback-collect/references/verification-method.md +31 -0
  17. package/plugins/vod-devkit/skills/vod-problem-classification-rules/SKILL.md +3 -1
  18. package/plugins/vod-devkit/skills/vod-scoring-rules/SKILL.md +22 -1
  19. package/plugins/vod-devkit/vod_mcp/__init__.py +1 -1
  20. package/plugins/vod-devkit/vod_mcp/attribution.py +378 -0
  21. package/plugins/vod-devkit/vod_mcp/host_adapters/__init__.py +26 -0
  22. package/plugins/vod-devkit/vod_mcp/host_adapters/base.py +73 -0
  23. package/plugins/vod-devkit/vod_mcp/host_adapters/codearts.py +57 -0
  24. package/plugins/vod-devkit/vod_mcp/host_adapters/codex.py +209 -0
  25. package/plugins/vod-devkit/vod_mcp/host_adapters/dsh.py +176 -0
  26. package/plugins/vod-devkit/vod_mcp/host_adapters/generic.py +132 -0
  27. package/plugins/vod-devkit/vod_mcp/host_adapters/hermes.py +76 -0
  28. package/plugins/vod-devkit/vod_mcp/host_adapters/opencode.py +52 -0
  29. package/plugins/vod-devkit/vod_mcp/hosts.py +20 -0
  30. package/plugins/vod-devkit/vod_mcp/packs.py +3 -1
  31. package/plugins/vod-devkit/vod_mcp/payload.py +174 -0
  32. package/plugins/vod-devkit/vod_mcp/server.py +13 -1
  33. package/plugins/vod-devkit/vod_mcp/tools.py +399 -46
  34. package/plugins/vod-devkit/vod_mcp/update_check.py +31 -3
  35. package/skills/vod-core/SKILL.md +12 -4
  36. package/skills/vod-core/references/acceptance-criteria.md +9 -0
  37. package/skills/vod-core/references/verification-method.md +29 -0
  38. package/skills/vod-feedback-collect/SKILL.md +57 -11
  39. package/skills/vod-feedback-collect/references/acceptance-criteria.md +28 -0
  40. package/skills/vod-feedback-collect/references/verification-method.md +31 -0
  41. package/skills/vod-problem-classification-rules/SKILL.md +3 -1
  42. package/skills/vod-scoring-rules/SKILL.md +22 -1
  43. package/vod_mcp/__init__.py +1 -1
  44. package/vod_mcp/attribution.py +378 -0
  45. package/vod_mcp/host_adapters/__init__.py +26 -0
  46. package/vod_mcp/host_adapters/__pycache__/__init__.cpython-314.pyc +0 -0
  47. package/vod_mcp/host_adapters/__pycache__/base.cpython-314.pyc +0 -0
  48. package/vod_mcp/host_adapters/__pycache__/codearts.cpython-314.pyc +0 -0
  49. package/vod_mcp/host_adapters/__pycache__/codex.cpython-314.pyc +0 -0
  50. package/vod_mcp/host_adapters/__pycache__/dsh.cpython-314.pyc +0 -0
  51. package/vod_mcp/host_adapters/__pycache__/generic.cpython-314.pyc +0 -0
  52. package/vod_mcp/host_adapters/__pycache__/hermes.cpython-314.pyc +0 -0
  53. package/vod_mcp/host_adapters/__pycache__/opencode.cpython-314.pyc +0 -0
  54. package/vod_mcp/host_adapters/base.py +73 -0
  55. package/vod_mcp/host_adapters/codearts.py +57 -0
  56. package/vod_mcp/host_adapters/codex.py +209 -0
  57. package/vod_mcp/host_adapters/dsh.py +176 -0
  58. package/vod_mcp/host_adapters/generic.py +132 -0
  59. package/vod_mcp/host_adapters/hermes.py +76 -0
  60. package/vod_mcp/host_adapters/opencode.py +52 -0
  61. package/vod_mcp/hosts.py +20 -0
  62. package/vod_mcp/packs.py +3 -1
  63. package/vod_mcp/payload.py +174 -0
  64. package/vod_mcp/server.py +13 -1
  65. package/vod_mcp/tools.py +399 -46
  66. package/vod_mcp/update_check.py +31 -3
package/vod_mcp/hosts.py CHANGED
@@ -46,6 +46,26 @@ def _resolve(path_str, profile: str | None = None) -> Path:
46
46
  return Path(path_str)
47
47
 
48
48
 
49
+ def raw(host: str) -> dict:
50
+ """读原始 host.json(不解析路径、不代入 profile)——探测/展示用。
51
+
52
+ 动机(2026-11-11 实测):detect_targets 走 load() 时,dsh 的 configPath
53
+ 含 {profile} 必填占位符 → ValueError,--target auto 在装了 dsh 集成后直接
54
+ 崩。探测只需要 detectCLI/detectPath,不该被路径解析拖累。
55
+ """
56
+ p = INTEGRATIONS / host / "host.json"
57
+ if not p.exists():
58
+ raise KeyError(f"未知宿主 {host}")
59
+ data = json.loads(p.read_text(encoding="utf-8"))
60
+ detect = data.get("detect") or {}
61
+ # 只补探测所需的两键(与 load() 同名);configPath 等仍留原始串,不解析
62
+ # {profile}——探测不该依赖安装期才有的输入。
63
+ data["detectCLI"] = detect.get("cli")
64
+ data["detectPath"] = (_resolve(_pick(detect["path"]))
65
+ if detect.get("path") else None)
66
+ return data
67
+
68
+
49
69
  def load(host: str, profile: str | None = None) -> dict:
50
70
  """读一个宿主的适配数据并解析成绝对路径 → dict(键为契约的一部分)。
51
71
 
package/vod_mcp/packs.py CHANGED
@@ -8,7 +8,9 @@ import sys
8
8
  ALL_PACKS = ("core", "collect", "knowledge")
9
9
 
10
10
  PACK_TOOLS = {
11
- "core": ["vod_devkit_info", "vod_auth_status", "vod_check_update"],
11
+ # vod_search_products:问用户"是哪个产品"前给候选(只读,D-product-ask-1)
12
+ "core": ["vod_devkit_info", "vod_auth_status", "vod_check_update",
13
+ "vod_search_products"],
12
14
  # 两段式(D-token-approval-2 极简形态)随 collect 下发;codex 话术走 draft→commit
13
15
  "collect": ["vod_submit_voices", "vod_draft_voices", "vod_commit_voices", "vod_list_submitted"],
14
16
  # 领域规则技能披露(第二轨):知道有哪几本规则、按需取全文。
@@ -0,0 +1,174 @@
1
+ """安装载荷(payload):把 server 与技能拷到宿主 / 用户自己的稳定目录。
2
+
3
+ 动机(对标 huaweicloud-devkit 的 copyServerPayload,D-payload-1):
4
+ 本仓所有 MCP 入口此前指向 `<repo>/vod_mcp/server.py`。用 npx 安装时 repo 在
5
+ `~/.npm/_npx/<hash>/`,npm 一旦清缓存/换版本,入口指向已删除的路径 —— 宿主
6
+ 启动即 MCP 掉线,而用户看不到任何报错。
7
+
8
+ 载荷模型就是它那套:
9
+ ① 落一份稳定副本(默认 ~/.vod-devkit/payloads/<version>/)
10
+ ② 入口指向副本,不指向 npx 缓存
11
+ ③ 每次 install 覆盖 + prune 掉源里已不存在的旧条目(只删我们自己前缀的)
12
+ ④ 落 `.installed` 标记 = "载荷已换,重启即生效";server 启动时自己删掉
13
+ ⑤ payload.json 记录版本/commitSha/逐文件 sha256(doctor 与 verify 的依据)
14
+
15
+ 与 devkit 的差别:零第三方依赖 → 不需要它的 installRuntimeDeps(npm install
16
+ undici 那一段);我们只校验 Python 版本与文件指纹。
17
+ """
18
+ import hashlib
19
+ import json
20
+ import os
21
+ import shutil
22
+ import datetime
23
+ from pathlib import Path
24
+
25
+ ROOT = Path(__file__).resolve().parent.parent
26
+
27
+ def payload_home() -> Path:
28
+ """载荷根(用户级,多宿主共享;版本目录隔离)。
29
+
30
+ 每次读 env:测试用 VOD_PAYLOAD_HOME 重定向,进程内可随时改——
31
+ 常量在 import 期求值会把测试写进真实 ~/.vod-devkit(第一版实锤)。
32
+ """
33
+ return Path(os.environ.get("VOD_PAYLOAD_HOME") or (Path.home() / ".vod-devkit"))
34
+
35
+ # 我们拥有的顶层条目(prune 只在这个集合内动手,绝不碰用户文件)
36
+ OWNED = ("vod_mcp", "contract", "safety", "skills", "hermes-plugin",
37
+ "build-info.json", "payload.json", "package.json")
38
+
39
+ SKIP_DIRS = {"__pycache__"}
40
+ SKIP_FILES = {"runtime.json", "install-manifest.json", "payload.json"}
41
+ SKIP_SUFFIX = (".pyc", ".pyo", ".log")
42
+
43
+
44
+ def _sha256(path: Path) -> str:
45
+ h = hashlib.sha256()
46
+ with path.open("rb") as f:
47
+ for chunk in iter(lambda: f.read(1 << 20), b""):
48
+ h.update(chunk)
49
+ return h.hexdigest()
50
+
51
+
52
+ def _iter_files(src: Path):
53
+ for p in sorted(src.rglob("*")):
54
+ if p.is_dir():
55
+ continue
56
+ if any(part in SKIP_DIRS for part in p.parts):
57
+ continue
58
+ if p.name in SKIP_FILES or p.name.endswith(SKIP_SUFFIX):
59
+ continue
60
+ yield p
61
+
62
+
63
+ def payload_dir(version: str | None = None) -> Path:
64
+ from vod_mcp import __version__
65
+ return payload_home() / "payloads" / (version or __version__)
66
+
67
+
68
+ def marker_path() -> Path:
69
+ return payload_home() / ".installed"
70
+
71
+
72
+ def file_hashes(base: Path) -> dict:
73
+ out = {}
74
+ for p in _iter_files(base):
75
+ out[str(p.relative_to(base)).replace(os.sep, "/")] = _sha256(p)
76
+ return out
77
+
78
+
79
+ def prune_stale(dest: Path, src_names: set) -> list:
80
+ """删掉 dest 里我们拥有、但源里已不存在的顶层条目(升级不留残骸)。"""
81
+ removed = []
82
+ if not dest.exists():
83
+ return removed
84
+ for entry in sorted(dest.iterdir()):
85
+ if entry.name not in OWNED or entry.name in src_names:
86
+ continue
87
+ if entry.is_dir():
88
+ shutil.rmtree(entry)
89
+ else:
90
+ entry.unlink()
91
+ removed.append(entry.name)
92
+ return removed
93
+
94
+
95
+ def stage(version: str | None = None, quiet: bool = False) -> Path:
96
+ """把载荷拷进稳定目录(存在则原地刷新),返回载荷目录。"""
97
+ from vod_mcp import __version__
98
+ version = version or __version__
99
+ dest = payload_dir(version)
100
+ dest.mkdir(parents=True, exist_ok=True)
101
+
102
+ sources = {"vod_mcp": ROOT / "vod_mcp", "contract": ROOT / "contract",
103
+ "safety": ROOT / "safety", "skills": ROOT / "skills",
104
+ "hermes-plugin": ROOT / "hermes-plugin"}
105
+ for name, src in sources.items():
106
+ if not src.is_dir():
107
+ continue # hermes-plugin 可缺(非 hermes 宿主)
108
+ target = dest / name
109
+ target.mkdir(parents=True, exist_ok=True)
110
+ for f in _iter_files(src):
111
+ rel = f.relative_to(src)
112
+ out = target / rel
113
+ out.parent.mkdir(parents=True, exist_ok=True)
114
+ shutil.copyfile(f, out)
115
+
116
+ # 顶层单体文件
117
+ for name in ("build-info.json", "package.json"):
118
+ src = ROOT / name
119
+ if src.exists():
120
+ shutil.copyfile(src, dest / name)
121
+
122
+ removed = prune_stale(dest, set(sources) | {"build-info.json", "package.json",
123
+ "payload.json"})
124
+
125
+ info = json.loads((ROOT / "build-info.json").read_text(encoding="utf-8")) \
126
+ if (ROOT / "build-info.json").exists() else {}
127
+ manifest = {
128
+ "version": version,
129
+ "commitSha": info.get("commitSha"),
130
+ "stagedAt": datetime.datetime.now().isoformat(timespec="seconds"),
131
+ "files": file_hashes(dest),
132
+ }
133
+ (dest / "payload.json").write_text(
134
+ json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
135
+ marker_path().parent.mkdir(parents=True, exist_ok=True)
136
+ marker_path().write_text(datetime.datetime.now().isoformat(timespec="seconds"),
137
+ encoding="utf-8")
138
+ if not quiet:
139
+ print(f"载荷已就位:{dest}({len(manifest['files'])} 个文件"
140
+ + (f";清理旧条目 {removed}" if removed else "") + ")")
141
+ return dest
142
+
143
+
144
+ def consume_marker() -> None:
145
+ """server 启动时调用:标记只表示"换过载荷,该重启",被运行中的进程消费掉。"""
146
+ try:
147
+ marker_path().unlink(missing_ok=True)
148
+ except Exception:
149
+ pass
150
+
151
+
152
+ def verify(payload: Path) -> list:
153
+ """比对 payload.json 的逐文件 sha256,返回问题清单(空=OK)。"""
154
+ problems = []
155
+ pj = payload / "payload.json"
156
+ if not pj.exists():
157
+ return [f"载荷缺 payload.json:{payload}"]
158
+ data = json.loads(pj.read_text(encoding="utf-8"))
159
+ for rel, sha in (data.get("files") or {}).items():
160
+ f = payload / rel
161
+ if not f.exists():
162
+ problems.append(f"载荷文件缺失:{rel}")
163
+ elif _sha256(f) != sha:
164
+ problems.append(f"载荷文件被改:{rel}")
165
+ return problems
166
+
167
+
168
+ def residue() -> list:
169
+ """没有 payload.json 的载荷目录 = 残留(旧版本/手工拷贝),doctor 报出来。"""
170
+ base = payload_home() / "payloads"
171
+ if not base.is_dir():
172
+ return []
173
+ return [p for p in sorted(base.iterdir())
174
+ if p.is_dir() and not (p / "payload.json").exists()]
package/vod_mcp/server.py CHANGED
@@ -44,7 +44,9 @@ def handle(message: dict, client_info: dict | None = None) -> dict | None:
44
44
  "本产品的不满/建议/期望(触发词:慢/报错/体验差/希望支持/提单等)。"
45
45
  "提交前必须征得用户明确同意(用户抱怨本身不构成同意);提交回执"
46
46
  "echo.contents 必须逐条原样转述给用户(「已收录原话:<content>」),"
47
- "禁止改写、概括、增删字词。product 归因由安装绑定完成,禁止询问用户。"
47
+ "禁止改写、概括、增删字词。product 归因:原话唯一命中可直接用;"
48
+ "未命中或多产品歧义时必须问用户一次\"这条是哪个产品的反馈\","
49
+ "回答填 product;用户说不知道就告知他缺产品不能提交,不要猜。不许不填直接提交。"
48
50
  ),
49
51
  "serverInfo": {
50
52
  "name": "vod-devkit",
@@ -78,7 +80,17 @@ def handle(message: dict, client_info: dict | None = None) -> dict | None:
78
80
  return None
79
81
 
80
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
+
81
92
  def main():
93
+ _consume_payload_marker()
82
94
  import argparse
83
95
  ap = argparse.ArgumentParser(prog="vod-mcp-server",
84
96
  description="vod-devkit MCP server(默认 stdio)")