agentstore-oss 0.1.0__py3-none-any.whl

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.
agentstore/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """agentstore —— agent 应用商店的最小内核:清单 + 不可变版本 + 权限闸 + 计量 + 分成。"""
2
+
3
+ __version__ = "0.1.0"
agentstore/cli.py ADDED
@@ -0,0 +1,168 @@
1
+ """demo:三个 agent 上架 → 一个买家按最小授权安装 → 五次调用(含被拦与重投)→ 出账单。"""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import json
7
+ import sys
8
+
9
+ from . import __version__
10
+ from .fixtures import CFO, INVOICE_BOT, RESEARCH
11
+ from .meter import Ledger
12
+ from .registry import Registry, RegistryError
13
+ from .runtime import Runtime
14
+
15
+
16
+ def _handler(name: str):
17
+ outs = {
18
+ "invoice-bot": ("匹配 12 张发票:10 张一致,2 张缺收货单", 1),
19
+ "deck-research": ("摘要已生成,引用 7 条(3 条来自 10-K)", 2400),
20
+ "cfo-copilot": ("本月毛利率 41.2%,环比 -1.8pt;现金可支撑 7.4 个月", 1),
21
+ }
22
+
23
+ def run(_rid: str):
24
+ return outs[name]
25
+
26
+ return run
27
+
28
+
29
+ def cmd_demo(args: argparse.Namespace) -> int:
30
+ reg = Registry(args.db)
31
+ ledger = Ledger(args.db)
32
+ for m, dev in ((INVOICE_BOT, "northwind-labs"), (RESEARCH, "quill-research"), (CFO, "ledgerly")):
33
+ reg.publish(m, dev)
34
+ ledger.register(m)
35
+ rt = Runtime(reg, ledger)
36
+
37
+ print("== 上架 ==")
38
+ for m, dev in ((INVOICE_BOT, "northwind-labs"), (RESEARCH, "quill-research"), (CFO, "ledgerly")):
39
+ print(f" {m.agent_id}@{m.version} {m.pricing.kind:<12} digest={m.digest()[:12]} by {dev}")
40
+
41
+ print("\n== 安装(最小授权)==")
42
+ reg.install("acme", "invoice-bot", granted=("fs.read",))
43
+ reg.install("acme", "deck-research", granted=("net.outbound",))
44
+ reg.install("acme", "cfo-copilot", granted=("fs.read", "fs.write"))
45
+ print(" acme 安装 3 个 agent,其中 deck-research 未授予 secrets.read")
46
+
47
+ print("\n== 调用 ==")
48
+ calls = [
49
+ ("invoice-bot", ("fs.read",), "req-1001"),
50
+ ("invoice-bot", ("fs.read",), "req-1002"),
51
+ ("deck-research", ("secrets.read",), "req-1003"), # 缺权限 → 拦
52
+ ("deck-research", ("net.outbound",), "req-1004"),
53
+ ("cfo-copilot", ("fs.read",), "req-1005"),
54
+ ("invoice-bot", ("fs.read",), "req-1001"), # 重投 → 不重复计费
55
+ ]
56
+ for agent_id, needs, rid in calls:
57
+ ex = rt.execute("acme", agent_id, _handler(agent_id), rid, needs=needs)
58
+ print(ex.render())
59
+
60
+ print("\n== 账单 ==")
61
+ devs = {"invoice-bot": "northwind-labs", "deck-research": "quill-research", "cfo-copilot": "ledgerly"}
62
+ print(ledger.statement("acme", devs, fee_pct=20).to_markdown(20))
63
+
64
+ print("== 反例:改内容不发新版本 ==")
65
+ try:
66
+ reg.publish(type(INVOICE_BOT)(**{**INVOICE_BOT.__dict__, "description": "偷偷加一个权限"}),
67
+ "northwind-labs")
68
+ except RegistryError as exc:
69
+ print(f" 已拒绝:{exc}")
70
+ return 0
71
+
72
+
73
+ def _developer(value: str) -> tuple[str, str]:
74
+ agent, sep, dev = value.partition("=")
75
+ if not sep or not agent or not dev:
76
+ raise argparse.ArgumentTypeError(f"--developer 要 agent=dev 形式,收到 {value!r}")
77
+ return agent, dev
78
+
79
+
80
+ def _fee_pct(value: str) -> int:
81
+ try:
82
+ n = int(value)
83
+ except ValueError:
84
+ raise argparse.ArgumentTypeError(f"--fee-pct 要整数,收到 {value!r}")
85
+ if not 0 <= n <= 100:
86
+ raise argparse.ArgumentTypeError(f"--fee-pct 必须在 0..100,收到 {n}")
87
+ return n
88
+
89
+
90
+ def cmd_statement(args: argparse.Namespace) -> int:
91
+ st = Ledger(args.db).issue_statement(
92
+ args.buyer, dict(args.developer or ()), fee_pct=args.fee_pct, request_id=args.request_id)
93
+ if args.json:
94
+ json.dump(st.to_dict(), sys.stdout, ensure_ascii=False)
95
+ sys.stdout.write("\n")
96
+ else:
97
+ print(st.to_markdown(st.fee_pct))
98
+ return 0
99
+
100
+
101
+ def cmd_quickstart(args: argparse.Namespace) -> int:
102
+ """在当前目录生成可直接跑的最小工作区,并打印接下来三条命令。"""
103
+ from pathlib import Path
104
+
105
+ from . import quickstart
106
+
107
+ dirname = args.dir or quickstart.WORKSPACE_DIRNAME
108
+ target = Path(dirname)
109
+ results = quickstart.write_workspace(target, force=args.force)
110
+
111
+ created = sum(1 for _, action in results if action != "skip")
112
+ print(f"== quickstart: {dirname}(新建/覆盖 {created} 个,跳过 "
113
+ f"{len(results) - created} 个)==")
114
+ for rel, action in results:
115
+ note = "(已存在,原样保留)" if action == "skip" else ""
116
+ print(f" {action:<9} {rel}{note}")
117
+
118
+ if created == 0:
119
+ print("\n所有文件都已存在,没有覆盖任何东西(要重置加 --force)。")
120
+
121
+ print("\n接下来三条命令:")
122
+ for i, command in enumerate(quickstart.NEXT_STEPS, 1):
123
+ print(f" {i}) {command.format(dirname=dirname)}")
124
+ print("\n第 2 条会打印发布 → 安装 → 执行 → 同键重放(duplicate=True)"
125
+ " → 同键换载荷(idempotency_conflict)→ 账单。")
126
+ return 0
127
+
128
+
129
+ def build_parser() -> argparse.ArgumentParser:
130
+ ap = argparse.ArgumentParser(
131
+ prog="agentstore",
132
+ description="agent 应用商店内核:上架 → 安装 → 调用 → 账单的零配置演示")
133
+ ap.add_argument("--version", action="version",
134
+ version=f"%(prog)s {__version__}")
135
+ sub = ap.add_subparsers(dest="cmd", title="子命令")
136
+ d = sub.add_parser("demo", help="跑完整演示(缺省子命令):3 个 agent 上架 → 6 次调用 → 出账单")
137
+ d.add_argument("--db", default=":memory:",
138
+ help="把发布与用量记进这个 sqlite 文件(默认 :memory:,跑完即弃)")
139
+ d.set_defaults(func=cmd_demo)
140
+
141
+ s = sub.add_parser("statement", help="出账:按 buyer 聚合 usage 并分账(--json 给机器读)")
142
+ s.add_argument("--db", required=True, help="商店库(sqlite 文件)")
143
+ s.add_argument("--buyer", required=True, help="买家 id")
144
+ s.add_argument("--fee-pct", type=_fee_pct, default=20, help="平台抽成百分比 0..100(默认 20)")
145
+ s.add_argument("--developer", action="append", type=_developer, metavar="AGENT=DEV",
146
+ help="agent→开发者归属,可重复;没给的记 unknown")
147
+ s.add_argument("--request-id", default=None,
148
+ help="出账幂等键(scope 为 buyer):重复时原样回放首次快照")
149
+ s.add_argument("--json", action="store_true", help="stdout 输出单个 JSON 对象")
150
+ s.set_defaults(func=cmd_statement)
151
+ q = sub.add_parser("quickstart", help="在当前目录生成一个三分钟能跑的最小工作区")
152
+ q.add_argument("--dir", default=None,
153
+ help="生成到哪个目录(默认 ./agentstore-quickstart)")
154
+ q.add_argument("--force", action="store_true",
155
+ help="覆盖已存在的文件(默认跳过,不碰用户改过的东西)")
156
+ q.set_defaults(func=cmd_quickstart)
157
+
158
+ ap.set_defaults(func=cmd_demo) # 不带子命令时保持旧行为:直接跑 demo
159
+ return ap
160
+
161
+
162
+ def main(argv: list[str] | None = None) -> int:
163
+ args = build_parser().parse_args(argv)
164
+ return args.func(args)
165
+
166
+
167
+ if __name__ == "__main__":
168
+ sys.exit(main())
agentstore/fixtures.py ADDED
@@ -0,0 +1,27 @@
1
+ """三个上架 agent:一个按次、一个按 token、一个订阅。"""
2
+
3
+ from .manifest import AgentManifest, Pricing
4
+
5
+ INVOICE_BOT = AgentManifest(
6
+ agent_id="invoice-bot", version="1.2.0", name="发票核对机器人",
7
+ entrypoint="handlers.invoice:run",
8
+ pricing=Pricing(kind="per_call", cents_per_unit=5),
9
+ permissions=("fs.read", "net.outbound"),
10
+ description="读邮箱里的发票 PDF,与账上应付做三方匹配。",
11
+ )
12
+
13
+ RESEARCH = AgentManifest(
14
+ agent_id="deck-research", version="0.4.1", name="投研摘要",
15
+ entrypoint="handlers.research:run",
16
+ pricing=Pricing(kind="per_token", cents_per_unit=30),
17
+ permissions=("net.outbound", "secrets.read"),
18
+ description="按问题检索公开披露文件并生成带引用的摘要。",
19
+ )
20
+
21
+ CFO = AgentManifest(
22
+ agent_id="cfo-copilot", version="2.0.0", name="CFO 助手",
23
+ entrypoint="handlers.cfo:run",
24
+ pricing=Pricing(kind="subscription", cents_per_unit=900, period="month"),
25
+ permissions=("fs.read", "fs.write", "net.outbound"),
26
+ description="月度经营分析、预算差异、现金预测。",
27
+ )
agentstore/intake.py ADDED
@@ -0,0 +1,224 @@
1
+ """入市审查:从清单文本里推断「这个 agent 大概要什么权限」,再对照它声明了什么。
2
+
3
+ 为什么需要这一层:`registry` 只能校验「授予的权限 ⊆ 声明的权限」,
4
+ 但真实世界的清单**根本不声明权限**。苹果 App Store 的隐私标签是人工填的,
5
+ 填错没人管——所以审核方必须自己能从代码/文档里推出它实际会干什么。
6
+
7
+ 这里的推断是关键词规则,不装成 AST 分析。它只做一件事:
8
+ 把「你没说的」和「你文档里写着的」摆到一起,让人判断。
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import json
14
+ import re
15
+ from dataclasses import dataclass, field
16
+
17
+ # 关键词 → 权限。故意粗:宁可多报(要求开发者解释),不可漏报(放过取密钥的)。
18
+ # 每一项都写清匹配理由,审核员要能反驳单条判断。
19
+ KEYWORD_PERMISSIONS: dict[str, tuple[str, ...]] = {
20
+ "net.outbound": ("http", "https", "api", "fetch", "web", "search", "crawl",
21
+ "url", "request", "endpoint", "graphql"),
22
+ "fs.read": ("read", "file", "filesystem", "directory", "parse", "excel",
23
+ "spreadsheet", "pdf", "csv", "local"),
24
+ "fs.write": ("write", "save file", "create file", "export file", "upload",
25
+ "edit file", "modify file", "write access"),
26
+ "secrets.read": ("api key", "apikey", "token", "credential", "secret",
27
+ "password", "auth", "bearer", "oauth"),
28
+ "email.send": ("send email", "email", "smtp", "mail", "inbox", "outlook"),
29
+ # 实测踩坑:原来把 "charge"/"invoice"/"purchase" 也当证据,
30
+ # 结果一个讲「charge 用户」的多模型代理被误判成要动钱。
31
+ # 只留真正指向资金动作的词。
32
+ "payment.charge": ("payment", "billing", "stripe", "credit card", "pay now"),
33
+ }
34
+
35
+ # 环境变量名本身就是证据:出现这个模式,说明它要拿一个凭据去调外部服务
36
+ ENV_SECRET_RE = re.compile(r"\b[A-Z][A-Z0-9_]{2,}(?:_API_KEY|_TOKEN|_SECRET|_KEY|_PASSWORD)\b")
37
+
38
+ # 权限字段的常见叫法。真实的 npm 包一个都没有,但审核方需要一个口径。
39
+ PERMISSION_FIELDS = ("permissions", "capabilities", "scopes", "mcp")
40
+
41
+ PINNED_RE = re.compile(r"^\d+\.\d+\.\d+$")
42
+
43
+ # 关键词必须按词边界匹配。踩过的坑:substring 匹配把 "credits" 里的 "edit"
44
+ # 当成写文件、把 "capital" 里的 "api" 当成联网、把 GitHub Actions 的
45
+ # "checkout" 当成收款。这类假阳性会让整个审查结论失去意义。
46
+ _ASCII_WORD_RE = {}
47
+
48
+
49
+ def _word_re(kw: str) -> re.Pattern:
50
+ if kw not in _ASCII_WORD_RE:
51
+ _ASCII_WORD_RE[kw] = re.compile(rf"(?<![a-z0-9]){re.escape(kw)}(?![a-z0-9])")
52
+ return _ASCII_WORD_RE[kw]
53
+
54
+
55
+ def _hits(words: tuple[str, ...], text: str) -> list[str]:
56
+ return [w for w in words if _word_re(w).search(text)]
57
+
58
+
59
+ @dataclass
60
+ class ServerFacts:
61
+ """一份清单能提供的全部证据。字段少而实,缺的就是缺的(不猜)。"""
62
+
63
+ repo: str
64
+ name: str = ""
65
+ version: str = ""
66
+ description: str = ""
67
+ readme: str = ""
68
+ deps: dict[str, str] = field(default_factory=dict)
69
+ declared: dict[str, list[str]] = field(default_factory=dict)
70
+
71
+ @property
72
+ def text(self) -> str:
73
+ """用于关键词推断的全文(描述 + README,小写)。"""
74
+ return f"{self.description}\n{self.readme}".lower()
75
+
76
+ def env_vars(self) -> list[str]:
77
+ return sorted(set(ENV_SECRET_RE.findall(f"{self.description}\n{self.readme}")))
78
+
79
+
80
+ def from_manifest(payload: dict) -> ServerFacts:
81
+ """把 fetch 下来的原始 JSON 变成审核用的证据对象。"""
82
+ pkg = payload.get("package_json") or {}
83
+ declared = {k: list(pkg[k]) for k in PERMISSION_FIELDS
84
+ if isinstance(pkg.get(k), list)}
85
+ return ServerFacts(
86
+ repo=payload.get("repo", "?"),
87
+ name=str(pkg.get("name") or payload.get("repo", "?")),
88
+ version=str(pkg.get("version") or ""),
89
+ description=str(pkg.get("description") or payload.get("description") or ""),
90
+ readme=str(payload.get("readme") or ""),
91
+ deps=dict(pkg.get("dependencies") or {}),
92
+ declared=declared,
93
+ )
94
+
95
+
96
+ def declared_permissions(facts: ServerFacts) -> set[str]:
97
+ """把各家的字段名统一成我们的权限词表。认不出的原样保留(不静默丢弃)。"""
98
+ out: set[str] = set()
99
+ for values in facts.declared.values():
100
+ for v in values:
101
+ if v.startswith("!"):
102
+ continue
103
+ out.add(str(v))
104
+ return out
105
+
106
+
107
+ def infer_permissions(facts: ServerFacts) -> dict[str, list[str]]:
108
+ """返回 {权限: [触发的关键词或环境变量]}。空 dict 表示没找到任何需求证据。"""
109
+ text = facts.text
110
+ found: dict[str, list[str]] = {}
111
+ for perm, words in KEYWORD_PERMISSIONS.items():
112
+ hits = _hits(words, text)
113
+ if hits:
114
+ found[perm] = hits
115
+ envs = facts.env_vars()
116
+ if envs:
117
+ # 环境变量是硬证据,比关键词强:写进 README 的 KEY 名就是要填的凭据
118
+ found.setdefault("secrets.read", []).extend(envs)
119
+ # 有外部依赖包(sdk/client)也说明要联网
120
+ if any(re.search(r"(sdk|client|api)", d.lower()) for d in facts.deps):
121
+ found.setdefault("net.outbound", []).append("dependency:*-sdk/client")
122
+ return found
123
+
124
+
125
+ @dataclass
126
+ class Finding:
127
+ rule: str
128
+ severity: str # high / medium / low
129
+ detail: str
130
+
131
+
132
+ # 这两类权限「存在任何环境变量名」本身就是硬证据:要拿凭据 = 要读密钥
133
+ _ENV_ITSELF_IS_PROOF = {"secrets.read"}
134
+
135
+
136
+ def _env_proves(perm: str, evidence: list[str], hard: set[str]) -> bool:
137
+ """判断环境变量名是否构成这条权限的硬证据。
138
+
139
+ 原实现 `any(env in e ...)` 方向反了:拿整个环境变量名去问「是否被证据词包含」,
140
+ 而证据词是 stripe/payment 这类短词 —— `"STRIPE_SECRET_KEY" in "stripe"` 恒假。
141
+ 于是只剩「环境变量名自己出现在证据列表里」这一种自证,结果任何 KEY 名都能把
142
+ *每一条* 敏感权限顶成 high(ANTHROPIC_API_KEY 也被当成动钱证据)。
143
+
144
+ 正确判据:证据词出现在环境变量名里(stripe ⊂ STRIPE_SECRET_KEY)。
145
+ """
146
+ if not hard:
147
+ return False
148
+ if perm in _ENV_ITSELF_IS_PROOF:
149
+ return True
150
+ for e in evidence:
151
+ token = e.lower().strip()
152
+ if not token:
153
+ continue
154
+ if any(token in env.lower() for env in hard):
155
+ return True
156
+ return False
157
+
158
+
159
+ def audit(facts: ServerFacts) -> list[Finding]:
160
+ """把「需要的」和「声明的」对起来,产出可读的入市结论。"""
161
+ need = infer_permissions(facts)
162
+ have = declared_permissions(facts)
163
+ out: list[Finding] = []
164
+
165
+ if need and not have:
166
+ # 等级定 medium 而不是 high:在真实 MCP 生态里「不声明」是 16/16 的普遍状态,
167
+ # 定成 high 会让每份清单都红,审查结论就失去区分度(全是 high = 没有 high)。
168
+ # high 留给真正危险且被具体证据钉住的情况。
169
+ out.append(Finding(
170
+ "no_permission_declaration", "medium",
171
+ f"清单没有任何权限声明,但文档/依赖显示需要 {sorted(need)}"))
172
+
173
+ hard = set(facts.env_vars())
174
+ for perm in sorted(set(need) - have):
175
+ if perm in ("secrets.read", "payment.charge", "email.send"):
176
+ # 证据强度分级:README 里出现具体 KEY 名 = 硬证据;
177
+ # 只有「token/secret」这类词 = 软证据,可能是讲别人的东西。
178
+ proven = _env_proves(perm, need[perm], hard)
179
+ out.append(Finding(
180
+ "undeclared_sensitive_permission", "high" if proven else "medium",
181
+ f"需要 {perm}(依据:{need[perm][:4]})却未声明"
182
+ f"{';环境变量名为硬证据' if proven else ';仅关键词推断'}"))
183
+ elif perm in ("fs.write",):
184
+ out.append(Finding(
185
+ "undeclared_write_permission", "medium",
186
+ f"需要 {perm}(依据:{need[perm][:4]})却未声明"))
187
+
188
+ if have and not (have <= set(need)):
189
+ extra = sorted(have - set(need))
190
+ out.append(Finding(
191
+ "over_requested_permission", "medium",
192
+ f"声明的权限在文档里找不到依据:{extra}"))
193
+
194
+ if not facts.version or not PINNED_RE.match(facts.version):
195
+ out.append(Finding(
196
+ "unpinned_version", "medium",
197
+ f"版本无法固定({facts.version or '缺失'}),买家装到的东西不可复现"))
198
+
199
+ if not facts.readme.strip():
200
+ out.append(Finding(
201
+ "no_documentation", "medium", "清单无 README,审核员无法判断它做什么"))
202
+
203
+ return out
204
+
205
+
206
+ def review(payload: dict) -> dict:
207
+ """一份清单的完整入市审查结果,便于脚本批量跑。"""
208
+ facts = from_manifest(payload)
209
+ findings = audit(facts)
210
+ worst = "clean"
211
+ for sev in ("high", "medium", "low"):
212
+ if any(f.severity == sev for f in findings):
213
+ worst = sev
214
+ break
215
+ return {"repo": facts.repo, "version": facts.version or "-",
216
+ "inferred": sorted(infer_permissions(facts)),
217
+ "declared": sorted(declared_permissions(facts)),
218
+ "findings": [f.__dict__ for f in findings], "worst": worst}
219
+
220
+
221
+ def load_dir(path: str) -> list[dict]:
222
+ from pathlib import Path
223
+
224
+ return [json.loads(p.read_text()) for p in sorted(Path(path).glob("*.json"))]
agentstore/manifest.py ADDED
@@ -0,0 +1,145 @@
1
+ """清单模型:一个 agent 上架必须先说清楚「它能碰什么、怎么收费」。"""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import json
7
+ import re
8
+ from dataclasses import asdict, dataclass, field
9
+
10
+ SEMVER_RE = re.compile(r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$")
11
+
12
+ # 权限是白名单式的,未知权限一律拒绝(新增权限必须改这里,不能靠字符串自由发挥)
13
+ KNOWN_PERMISSIONS = {
14
+ "net.outbound", # 允许出网
15
+ "fs.read", # 读工作目录
16
+ "fs.write", # 写工作目录
17
+ "secrets.read", # 读调用方注入的凭据
18
+ "email.send",
19
+ "payment.charge",
20
+ }
21
+
22
+
23
+ class ManifestError(ValueError):
24
+ pass
25
+
26
+
27
+ @dataclass(frozen=True)
28
+ class Pricing:
29
+ """计费方式三选一。价格单位:美分(整数),避免浮点误差。"""
30
+
31
+ kind: str # per_call | per_token | subscription
32
+ cents_per_unit: int = 0 # per_call: 每次调用;per_token: 每 1k token;subscription: 每周期
33
+ period: str = "month" # subscription 用
34
+
35
+ def validate(self) -> None:
36
+ if self.kind not in {"per_call", "per_token", "subscription"}:
37
+ raise ManifestError(f"未知计费方式: {self.kind}")
38
+ if self.cents_per_unit <= 0:
39
+ # 订阅也必须为正:负价等于平台倒贴(可被刷成负数账单),
40
+ # 0 价则「走计费通道但不收钱」,两种都该在入市时拒掉。
41
+ raise ManifestError("价格必须为正(美分)"
42
+ + (",按量计费" if self.kind != "subscription" else ",订阅同样如此"))
43
+ if self.kind == "subscription" and self.period not in {"month", "year"}:
44
+ raise ManifestError("订阅周期只能是 month/year")
45
+
46
+
47
+ @dataclass(frozen=True)
48
+ class AgentManifest:
49
+ agent_id: str
50
+ version: str
51
+ name: str
52
+ entrypoint: str
53
+ pricing: Pricing
54
+ permissions: tuple[str, ...] = field(default_factory=tuple)
55
+ description: str = ""
56
+ # 调用期实际会要求的权限,必须 ⊆ permissions。
57
+ # 放进清单而不是只写在文档里:否则「装完之后它要拿什么权限」可以绕过 digest 被改。
58
+ needs: tuple[str, ...] = field(default_factory=tuple)
59
+
60
+ def validate(self) -> None:
61
+ if not self.agent_id or not re.fullmatch(r"[a-z0-9][a-z0-9_.-]{1,63}", self.agent_id):
62
+ raise ManifestError(f"agent_id 不合法: {self.agent_id!r}")
63
+ if not SEMVER_RE.match(self.version):
64
+ raise ManifestError(f"version 必须是 x.y.z: {self.version!r}")
65
+ if not self.entrypoint:
66
+ raise ManifestError("缺少 entrypoint")
67
+ unknown = [p for p in tuple(self.permissions) + tuple(self.needs)
68
+ if p not in KNOWN_PERMISSIONS]
69
+ if unknown:
70
+ raise ManifestError(f"未知权限: {unknown}")
71
+ outside = [p for p in self.needs if p not in self.permissions]
72
+ if outside:
73
+ raise ManifestError(f"needs 里有清单未声明的权限: {outside}(needs 必须 ⊆ permissions)")
74
+ self.pricing.validate()
75
+
76
+ # ---- 不可变性 ------------------------------------------------
77
+ def canonical(self) -> dict:
78
+ d = asdict(self)
79
+ d["permissions"] = sorted(self.permissions)
80
+ d["needs"] = sorted(self.needs)
81
+ return d
82
+
83
+ def digest(self) -> str:
84
+ """内容哈希:上架后这个值一变就说明版本被改过(版本号不可覆盖)。"""
85
+ payload = json.dumps(self.canonical(), sort_keys=True, ensure_ascii=False)
86
+ return hashlib.sha256(payload.encode()).hexdigest()
87
+
88
+
89
+ def parse_version(v: str) -> tuple[int, int, int]:
90
+ if not SEMVER_RE.match(v):
91
+ raise ManifestError(f"version 必须是 x.y.z: {v!r}")
92
+ return tuple(int(x) for x in v.split(".")) # type: ignore[return-value]
93
+
94
+
95
+ def from_dict(data: dict) -> AgentManifest:
96
+ """把 agent.json 那种扁平字典变成清单(运行期加载入口)。
97
+
98
+ 接受两个人类友好别名:`id` → agent_id、`price` → pricing。
99
+ 任何字段问题一律归到 ManifestError,不让 KeyError/TypeError 漏给调用方。
100
+ """
101
+ if not isinstance(data, dict):
102
+ raise ManifestError("清单必须是 JSON 对象")
103
+ d = dict(data)
104
+ if "id" in d:
105
+ d.setdefault("agent_id", d.pop("id"))
106
+ if "price" in d:
107
+ d.setdefault("pricing", d.pop("price"))
108
+ pricing = d.get("pricing")
109
+ if isinstance(pricing, dict):
110
+ try:
111
+ d["pricing"] = Pricing(**pricing)
112
+ except TypeError as exc:
113
+ raise ManifestError(f"pricing 字段不认识: {exc}") from exc
114
+ d["permissions"] = tuple(d.get("permissions") or ())
115
+ d["needs"] = tuple(d.get("needs") or ())
116
+ d.setdefault("entrypoint", "handler:run")
117
+ try:
118
+ manifest = AgentManifest(**d)
119
+ except TypeError as exc:
120
+ raise ManifestError(f"清单字段不认识: {exc}") from exc
121
+ manifest.validate()
122
+ return manifest
123
+
124
+
125
+ def load_manifest(path) -> AgentManifest:
126
+ """读一份 agent.json 并校验,返回清单对象。"""
127
+ try:
128
+ with open(path, encoding="utf-8") as fh:
129
+ data = json.load(fh)
130
+ except OSError as exc:
131
+ raise ManifestError(f"读不到清单 {path}: {exc}") from exc
132
+ except json.JSONDecodeError as exc:
133
+ raise ManifestError(f"清单不是合法 JSON {path}: {exc}") from exc
134
+ return from_dict(data)
135
+
136
+
137
+ def bump(version: str, part: str = "patch") -> str:
138
+ major, minor, patch = parse_version(version)
139
+ if part == "major":
140
+ return f"{major + 1}.0.0"
141
+ if part == "minor":
142
+ return f"{major}.{minor + 1}.0"
143
+ if part == "patch":
144
+ return f"{major}.{minor}.{patch + 1}"
145
+ raise ManifestError(f"未知升级位: {part}")