agentstore-oss 0.1.0__tar.gz

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 (29) hide show
  1. agentstore_oss-0.1.0/LICENSE +21 -0
  2. agentstore_oss-0.1.0/PKG-INFO +223 -0
  3. agentstore_oss-0.1.0/README.md +196 -0
  4. agentstore_oss-0.1.0/agentstore/__init__.py +3 -0
  5. agentstore_oss-0.1.0/agentstore/cli.py +168 -0
  6. agentstore_oss-0.1.0/agentstore/fixtures.py +27 -0
  7. agentstore_oss-0.1.0/agentstore/intake.py +224 -0
  8. agentstore_oss-0.1.0/agentstore/manifest.py +145 -0
  9. agentstore_oss-0.1.0/agentstore/meter.py +264 -0
  10. agentstore_oss-0.1.0/agentstore/quickstart.py +222 -0
  11. agentstore_oss-0.1.0/agentstore/registry.py +163 -0
  12. agentstore_oss-0.1.0/agentstore/runtime.py +161 -0
  13. agentstore_oss-0.1.0/agentstore_oss.egg-info/PKG-INFO +223 -0
  14. agentstore_oss-0.1.0/agentstore_oss.egg-info/SOURCES.txt +27 -0
  15. agentstore_oss-0.1.0/agentstore_oss.egg-info/dependency_links.txt +1 -0
  16. agentstore_oss-0.1.0/agentstore_oss.egg-info/entry_points.txt +2 -0
  17. agentstore_oss-0.1.0/agentstore_oss.egg-info/requires.txt +3 -0
  18. agentstore_oss-0.1.0/agentstore_oss.egg-info/top_level.txt +1 -0
  19. agentstore_oss-0.1.0/pyproject.toml +44 -0
  20. agentstore_oss-0.1.0/setup.cfg +4 -0
  21. agentstore_oss-0.1.0/tests/test_borrowed_idempotency.py +135 -0
  22. agentstore_oss-0.1.0/tests/test_borrowed_integrity.py +55 -0
  23. agentstore_oss-0.1.0/tests/test_intake.py +102 -0
  24. agentstore_oss-0.1.0/tests/test_quickstart.py +174 -0
  25. agentstore_oss-0.1.0/tests/test_review_p0.py +113 -0
  26. agentstore_oss-0.1.0/tests/test_review_p1.py +147 -0
  27. agentstore_oss-0.1.0/tests/test_review_r3.py +89 -0
  28. agentstore_oss-0.1.0/tests/test_statement_json.py +172 -0
  29. agentstore_oss-0.1.0/tests/test_store.py +132 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 clone-labs contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,223 @@
1
+ Metadata-Version: 2.4
2
+ Name: agentstore-oss
3
+ Version: 0.1.0
4
+ Summary: agent 应用商店的最小内核:清单、不可变版本、权限闸、计量与分成
5
+ License: MIT
6
+ Project-URL: Homepage, https://github.com/aidless/agentstore
7
+ Project-URL: Source, https://github.com/aidless/agentstore
8
+ Project-URL: Issues, https://github.com/aidless/agentstore/issues
9
+ Keywords: agent,marketplace,metering,idempotency,billing
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3 :: Only
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
21
+ Requires-Python: >=3.10
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Provides-Extra: dev
25
+ Requires-Dist: pytest>=8; extra == "dev"
26
+ Dynamic: license-file
27
+
28
+ # agentstore
29
+
30
+ 一个 agent 应用商店的最小内核:**清单(能力 + 价格)→ 不可变版本(内容摘要)→ 最小授权安装 →
31
+ 执行前权限闸 → 按用量计费 → 平台分成账单**。约 1400 行、零外部依赖、只用 Python 标准库与 SQLite,
32
+ 所以它适合用来读懂"商店到底难在哪",也可以作为你自己 agent 市场的计费骨架。
33
+ > 本文档里的可复算数字由 `scripts/check_readme.py` 机检:README 漂移即 fail build(`--selftest` 含必红 + 必绿反证)。
34
+
35
+
36
+ 它把商店最难的四条商业规则写成了代码与测试:
37
+
38
+ | 问题 | 天真做法 | 后果 | 这里的处理 |
39
+ | --- | --- | --- | --- |
40
+ | 卖家上架后偷偷改行为 | 版本号可以覆盖 | 买家装的和你审的不是一个东西 | `publish` 拒绝同版本重发,`digest` 内容哈希入表 |
41
+ | agent 悄悄读凭据 | 权限写在文档里 | 一次事故把平台告倒 | `KNOWN_PERMISSIONS` 白名单 + 安装时最小授权 + 执行前闸 |
42
+ | 被拦的请求也收费 | 请求进来就记一笔 | 账单争议拖垮客服 | `Runtime` **只在 handler 成功后写计量** |
43
+ | 客户端重投重复计费 | 每次请求都记 | 账单是实际调用的 3 倍 | `(buyer, request_id)` 是主键,第二次直接回放原记录 |
44
+
45
+ ## 安装
46
+
47
+ ```bash
48
+ pip install -e . # 只跑测试再加:pip install -e ".[dev]"
49
+ ```
50
+
51
+ 要求 Python 3.9+(CI 覆盖 3.9 / 3.10 / 3.11 / 3.12)。
52
+
53
+ ## 三分钟:跑出你自己的结果
54
+
55
+ ```bash
56
+ python3 -m agentstore.cli quickstart
57
+ ```
58
+
59
+ 在当前目录生成 `agentstore-quickstart/`,打完会打印接下来三条命令(真实输出):
60
+
61
+ ```
62
+ == quickstart: agentstore-quickstart(新建/覆盖 4 个,跳过 0 个)==
63
+ create agents/hello/agent.json
64
+ create agents/hello/handler.py
65
+ create README.md
66
+ create run.py
67
+
68
+ 接下来三条命令:
69
+ 1) cd agentstore-quickstart
70
+ 2) python3 run.py
71
+ 3) python3 -m agentstore.cli demo
72
+ ```
73
+
74
+ `python3 run.py` 走完发布 → 安装 → 带幂等键执行 → 同键重放 → 同键换载荷 → 账单(真实输出):
75
+
76
+ ```
77
+ [1 发布] hello@0.1.0 digest=c11b660ee771 开发者=you
78
+ [2 安装] you 只授予清单里的 ['fs.read'];越权的那份清单会被拒
79
+ [3 执行] ok=True id=demo-key-1 计费=5¢ 输出='HELLO AGENT STORE'
80
+ [4 重放] duplicate=True id=demo-key-1 计费=5¢ 输出='HELLO AGENT STORE'
81
+ [5 换载荷] ok=False error=idempotency_conflict: 该键已用于 hello@0.1.0,本次载荷不同
82
+ [6 账单]
83
+ # 账单 · you
84
+
85
+ | agent | 开发者 | 调用 | 计量单位 | 应付 | 平台分成 | 开发者应得 |
86
+ | --- | --- | ---: | ---: | ---: | ---: | ---: |
87
+ | hello | you | 1 | 1 | $0.05 | $0.01 | $0.04 |
88
+
89
+ 合计应付 **$0.05**(平台抽成 20%)
90
+
91
+ 库里的用量行数:1(重放与冲突都没有新增计费)
92
+ ```
93
+
94
+ 三行重点:`[3]` 第一次真跑并记一次账;`[4]` 同一个键回放**同一次执行**(`id` 相同、
95
+ `duplicate=True`)且不再执行 handler、不再计费;`[5]` 同一个键换了载荷直接拒。
96
+
97
+ 重复执行 `quickstart` 不会覆盖你改过的文件(存在则打印 `skip`);要重置加 `--force`。
98
+ 生成的 `agents/hello/handler.py` 只 import 标准库,`AGENTSTORE_INPUT="ship it" python3 run.py`
99
+ 就能换载荷,不用改代码。
100
+
101
+ ## 自己写代码时(与 quickstart 同一套 API)
102
+
103
+ ```python
104
+ from agentstore.manifest import load_manifest
105
+ from agentstore.meter import Ledger
106
+ from agentstore.registry import Registry
107
+ from agentstore.runtime import Runtime
108
+
109
+ manifest = load_manifest("agents/hello/agent.json") # 清单 + 校验
110
+ needs = tuple(manifest.needs) # 调用期真正要的权限,⊆ permissions
111
+
112
+ registry = Registry("store.db")
113
+ ledger = Ledger("store.db")
114
+ ledger.register(manifest) # 计量需要清单里的价格
115
+ registry.publish(manifest, "you") # 同版本重发会被拒
116
+ registry.install("you", manifest.agent_id, granted=needs) # 最小授权安装
117
+
118
+ runtime = Runtime(registry, ledger)
119
+ first = runtime.execute("you", manifest.agent_id, handler, "key-1", needs=needs)
120
+ again = runtime.execute("you", manifest.agent_id, handler, "key-1", needs=needs)
121
+ assert again.id == first.id and again.duplicate # 同键同载荷 → 回放同一次执行
122
+
123
+ bad = runtime.execute("you", manifest.agent_id, handler, "key-1", needs=needs, tokens=999)
124
+ assert bad.ok is False and bad.error.startswith("idempotency_conflict")
125
+ ```
126
+
127
+ `handler` 的契约是 `handler(request_id) -> (output, units)`:`units` 是计量单位数
128
+ (按次恒为 1;按 token 是 token 数;订阅被忽略)。
129
+
130
+ ## 计量与分成怎么读
131
+
132
+ | 计费方式 | 计量单位 | 舍入 | 适合 |
133
+ | --- | --- | --- | --- |
134
+ | `per_call` | 每次成功调用 | 精确到美分 | 确定性工具类 agent |
135
+ | `per_token` | 每 1k token | **向上取整**到 1k(不足 1k 按 1k) | 生成类 agent,成本主要是模型费 |
136
+ | `subscription` | 每周期 | 一次性 | 常驻/看板类 agent |
137
+
138
+ 分成规则:`platform = round(gross × fee%)`,**余数归开发者** —— 舍入误差不能让平台白赚钱,
139
+ 否则开发者对账永远差几分钱(`test_split_rounding_favours_developer` 钉住这条)。
140
+ `statement` 先按总额取整再逐行分配、末行兜底,保证 `platform + developer == gross` 逐行与合计都成立。
141
+
142
+ 出账有两个入口:人读的 Markdown 与 `--json`(金额单位是整数美分)。
143
+
144
+ ```bash
145
+ rm -f /tmp/agentstore.db # demo 每次都重新发布 3 个 agent,重跑前先删库
146
+ python3 -m agentstore.cli demo --db /tmp/agentstore.db
147
+ python3 -m agentstore.cli statement --db /tmp/agentstore.db --buyer acme \
148
+ --developer invoice-bot=northwind-labs --developer deck-research=quill-research \
149
+ --developer cfo-copilot=ledgerly --request-id st-2026-11 --json
150
+ ```
151
+
152
+ `--request-id` 是**出账**的幂等键(scope 到 buyer):同一个 id 再来原样回放首次快照,
153
+ 并把 `idempotent_replay` 置真 —— 回放连 `fee_pct` 一起回,所以拿到的可能是旧口径的数;
154
+ 要按新口径出账必须换新 id。没给 `--developer` 的 agent 记 `unknown`(`usage` 只记用量,不记归属)。
155
+ 退出码:`0` 跑通,`2` 用法错(缺 `--db`/`--buyer`、`--fee-pct` 不在 0..100、`--developer` 不是 `agent=dev`)。
156
+
157
+ ## 代码地图
158
+
159
+ ```
160
+ manifest.py AgentManifest / Pricing / 权限白名单 / canonical digest / semver / load_manifest
161
+ registry.py publish(不可覆盖)/ yank / latest / install(最小授权)/ granted
162
+ runtime.py resolve → status → gate(权限) → execute → meter(失败与拦截都不计费)
163
+ meter.py Ledger:request_id 幂等 + 指纹、三种定价、Statement 分账、出账快照
164
+ quickstart.py 生成 agentstore-quickstart/ 工作区(可重复执行,不覆盖用户改动)
165
+ fixtures.py invoice-bot(按次) / deck-research(按 token) / cfo-copilot(订阅)
166
+ cli.py quickstart / demo / statement
167
+ ```
168
+
169
+ ## 路线图
170
+
171
+ - [x] 清单 / 不可变版本 / 权限闸 / 幂等计量 / 分成账单 / quickstart
172
+ - [ ] 清单签名(Ed25519,公钥在商店侧),防止中间人替换 `agent.json`
173
+ - [ ] 执行隔离(子进程 + seccomp / 容器),当前 `handler` 是进程内回调
174
+ - [ ] 订阅周期结算(本版本把订阅当单次记账,缺少周期边界与按比例退款)
175
+ - [ ] 退款/争议流程(`usage` 表需要 `reversed_by` 与不可变审计链)
176
+ - [ ] 商店侧审核状态机(draft → in_review → published → yanked)
177
+
178
+ ## 已知边界
179
+
180
+ - **出账快照落成即冻结,`issued_at` 不是墙钟**:给了 `--request-id` 时,`gross/platform/developer/rows`
181
+ 连同 `fee_pct` 一起写进 `statements` 表(`meter.py:257`),此后同一 `(buyer, request_id)` 一律回放
182
+ (`meter.py:245`)—— 新增用量、新的 `--fee-pct` 都看不到;要重算必须换 id。`issued_at` 取 `Ledger._now`
183
+ (`meter.py:150`,默认硬编码 `2026-11-12T00:00:00Z`),是注入的测试时钟而非真实时间,接真系统时
184
+ 必须注入墙钟,否则所有快照的时间戳都相同。
185
+ - **金额用整数分,但账单只覆盖记进 `usage` 表的事件**:`Pricing.cents_per_unit` 与 `usage.cents` 都是整数(`manifest.py:32`、`meter.py:20`),展示时才用 `Decimal` 转美元(`meter.py:50`)。被权限闸拦下、handler 抛错、以及同 `(buyer, request_id)` 的重投都不会写 usage(`runtime.py:74`、`runtime.py:132`),所以账单里没有这些调用;反过来,绕过 `Runtime` 直接调 `Ledger.record` 的用量不受任何前置校验约束。整数分也做不了「$0.000003/token」这种粒度,真实系统应按 micro-cent 存整数。
186
+ - **版本归属以首次发布为准,不能转移**:`publish` 用 `INSERT OR IGNORE` 写入 `agents.developer`(`registry.py:77`),此后的发布者必须与首发布者一致(`registry.py:71`),没有转让或迁移归属的 API;`yank` 只改状态、不删版本(`registry.py:88`),买家已有安装仍保留记录。
187
+ - **分成先按总额取整、再逐行分配、末行兜底**:`statement` 先算 `target_fee`(`meter.py:226`),中间行各自取整并被夹在剩余额度内,最后一行拿走全部余额(`meter.py:229`),保证 `sum(platform) + sum(developer) == gross`。代价是每行金额依赖行顺序,不能对单行独立复算;抽成比例是账单参数(`statement(..., fee_pct=20)`)而不是合同。
188
+ - **registry 是单文件 SQLite,没有并发写保护**:`Registry` 直接 `sqlite3.connect(db_path)`(`registry.py:55`),默认 `:memory:`,未开 WAL、未设 `busy_timeout`、也没有进程内锁或重试;多进程/多线程同时 `publish`/`install` 会撞上 `database is locked` 或丢写。(`Ledger` 那边是另一套连接:`busy_timeout=5000` 且非 `:memory:` 开 WAL,`meter.py:130`。)
189
+ - **没有真实支付网络对接**:整个包没有任何网络请求或支付 SDK 调用。`payment.charge` 只是 `KNOWN_PERMISSIONS` 里的一个权限字符串(`manifest.py:19`),账单是本地 `usage` 表的聚合与 Markdown 渲染(`meter.py:118`),扣款、退款、对账、发票都留给外部系统。
190
+ - **digest 是内容哈希,不是签名**:`digest()` 只做 `sha256(canonical)`(`manifest.py:83`),能查出「同版本内容改了」,但证明不了「这份清单是开发者发的」;签名、执行隔离仍在路线图(`handler` 目前是进程内回调,`runtime.py:123`)。同理 `needs` 参与摘要只保证「装完之后要什么权限」没被偷改,不保证权限列表本身经过审核。
191
+ 另外:`needs` 是 0.1.0 之后加进 `canonical()` 的(`manifest.py:77`),所以**同一份清单的 digest
192
+ 与旧版不同**——摘要覆盖的字段变了。库里已有旧摘要的版本按「改内容就必须发新版本号」处理,
193
+ 不要在旧版本上原地覆盖。
194
+
195
+ ## 附:为什么要有权限声明(2026-11 的一次实测)
196
+
197
+ `scripts/fetch_mcp_servers.py` 从 GitHub 按 `mcp-server in:name` 取星标最高的仓库,
198
+ 拉 `package.json` 与 `README.md`,剔除 awesome-* 清单仓库后留下 **16 个真实 server**,
199
+ 再由 `scripts/real_manifests.py` 对每份跑入市审查。
200
+
201
+ | 指标 | 结果 |
202
+ |---|---|
203
+ | 清单里有任何权限字段(permissions/capabilities/scopes/mcp) | **0 / 16** |
204
+ | 文档/依赖显示需要 API 密钥 | 13 / 16 |
205
+ | 需要写文件 | 1 / 16 |
206
+ | 版本可固定(x.y.z) | 9 / 16 |
207
+
208
+ 零声明不是样本太少——这 16 个合计超过 10 万星标,含 GitHub、Cloudflare、Notion、Firecrawl
209
+ 的官方 server。买家装这些东西时,没有任何机器可读的东西告诉他这个 agent 能不能读文件、
210
+ 能不能拿 token。这条事实决定了商店该做什么:不是托管,而是**替买家把没写的东西补出来**,
211
+ 并让补出来的结论进入安装决策。同样这轮实测把「要写文件」从 9 份修到 1 份(`credits` 里的
212
+ `edit`、`actions/checkout` 两个假阳性),假阳性比漏报更贵。
213
+
214
+ 重跑:
215
+
216
+ ```bash
217
+ python3 scripts/fetch_mcp_servers.py 20 # 抓清单(写 data/raw/,已 gitignore)
218
+ python3 scripts/real_manifests.py # 审查 + 打印结论表
219
+ ```
220
+
221
+ ## 许可证
222
+
223
+ MIT,见 [LICENSE](LICENSE)。
@@ -0,0 +1,196 @@
1
+ # agentstore
2
+
3
+ 一个 agent 应用商店的最小内核:**清单(能力 + 价格)→ 不可变版本(内容摘要)→ 最小授权安装 →
4
+ 执行前权限闸 → 按用量计费 → 平台分成账单**。约 1400 行、零外部依赖、只用 Python 标准库与 SQLite,
5
+ 所以它适合用来读懂"商店到底难在哪",也可以作为你自己 agent 市场的计费骨架。
6
+ > 本文档里的可复算数字由 `scripts/check_readme.py` 机检:README 漂移即 fail build(`--selftest` 含必红 + 必绿反证)。
7
+
8
+
9
+ 它把商店最难的四条商业规则写成了代码与测试:
10
+
11
+ | 问题 | 天真做法 | 后果 | 这里的处理 |
12
+ | --- | --- | --- | --- |
13
+ | 卖家上架后偷偷改行为 | 版本号可以覆盖 | 买家装的和你审的不是一个东西 | `publish` 拒绝同版本重发,`digest` 内容哈希入表 |
14
+ | agent 悄悄读凭据 | 权限写在文档里 | 一次事故把平台告倒 | `KNOWN_PERMISSIONS` 白名单 + 安装时最小授权 + 执行前闸 |
15
+ | 被拦的请求也收费 | 请求进来就记一笔 | 账单争议拖垮客服 | `Runtime` **只在 handler 成功后写计量** |
16
+ | 客户端重投重复计费 | 每次请求都记 | 账单是实际调用的 3 倍 | `(buyer, request_id)` 是主键,第二次直接回放原记录 |
17
+
18
+ ## 安装
19
+
20
+ ```bash
21
+ pip install -e . # 只跑测试再加:pip install -e ".[dev]"
22
+ ```
23
+
24
+ 要求 Python 3.9+(CI 覆盖 3.9 / 3.10 / 3.11 / 3.12)。
25
+
26
+ ## 三分钟:跑出你自己的结果
27
+
28
+ ```bash
29
+ python3 -m agentstore.cli quickstart
30
+ ```
31
+
32
+ 在当前目录生成 `agentstore-quickstart/`,打完会打印接下来三条命令(真实输出):
33
+
34
+ ```
35
+ == quickstart: agentstore-quickstart(新建/覆盖 4 个,跳过 0 个)==
36
+ create agents/hello/agent.json
37
+ create agents/hello/handler.py
38
+ create README.md
39
+ create run.py
40
+
41
+ 接下来三条命令:
42
+ 1) cd agentstore-quickstart
43
+ 2) python3 run.py
44
+ 3) python3 -m agentstore.cli demo
45
+ ```
46
+
47
+ `python3 run.py` 走完发布 → 安装 → 带幂等键执行 → 同键重放 → 同键换载荷 → 账单(真实输出):
48
+
49
+ ```
50
+ [1 发布] hello@0.1.0 digest=c11b660ee771 开发者=you
51
+ [2 安装] you 只授予清单里的 ['fs.read'];越权的那份清单会被拒
52
+ [3 执行] ok=True id=demo-key-1 计费=5¢ 输出='HELLO AGENT STORE'
53
+ [4 重放] duplicate=True id=demo-key-1 计费=5¢ 输出='HELLO AGENT STORE'
54
+ [5 换载荷] ok=False error=idempotency_conflict: 该键已用于 hello@0.1.0,本次载荷不同
55
+ [6 账单]
56
+ # 账单 · you
57
+
58
+ | agent | 开发者 | 调用 | 计量单位 | 应付 | 平台分成 | 开发者应得 |
59
+ | --- | --- | ---: | ---: | ---: | ---: | ---: |
60
+ | hello | you | 1 | 1 | $0.05 | $0.01 | $0.04 |
61
+
62
+ 合计应付 **$0.05**(平台抽成 20%)
63
+
64
+ 库里的用量行数:1(重放与冲突都没有新增计费)
65
+ ```
66
+
67
+ 三行重点:`[3]` 第一次真跑并记一次账;`[4]` 同一个键回放**同一次执行**(`id` 相同、
68
+ `duplicate=True`)且不再执行 handler、不再计费;`[5]` 同一个键换了载荷直接拒。
69
+
70
+ 重复执行 `quickstart` 不会覆盖你改过的文件(存在则打印 `skip`);要重置加 `--force`。
71
+ 生成的 `agents/hello/handler.py` 只 import 标准库,`AGENTSTORE_INPUT="ship it" python3 run.py`
72
+ 就能换载荷,不用改代码。
73
+
74
+ ## 自己写代码时(与 quickstart 同一套 API)
75
+
76
+ ```python
77
+ from agentstore.manifest import load_manifest
78
+ from agentstore.meter import Ledger
79
+ from agentstore.registry import Registry
80
+ from agentstore.runtime import Runtime
81
+
82
+ manifest = load_manifest("agents/hello/agent.json") # 清单 + 校验
83
+ needs = tuple(manifest.needs) # 调用期真正要的权限,⊆ permissions
84
+
85
+ registry = Registry("store.db")
86
+ ledger = Ledger("store.db")
87
+ ledger.register(manifest) # 计量需要清单里的价格
88
+ registry.publish(manifest, "you") # 同版本重发会被拒
89
+ registry.install("you", manifest.agent_id, granted=needs) # 最小授权安装
90
+
91
+ runtime = Runtime(registry, ledger)
92
+ first = runtime.execute("you", manifest.agent_id, handler, "key-1", needs=needs)
93
+ again = runtime.execute("you", manifest.agent_id, handler, "key-1", needs=needs)
94
+ assert again.id == first.id and again.duplicate # 同键同载荷 → 回放同一次执行
95
+
96
+ bad = runtime.execute("you", manifest.agent_id, handler, "key-1", needs=needs, tokens=999)
97
+ assert bad.ok is False and bad.error.startswith("idempotency_conflict")
98
+ ```
99
+
100
+ `handler` 的契约是 `handler(request_id) -> (output, units)`:`units` 是计量单位数
101
+ (按次恒为 1;按 token 是 token 数;订阅被忽略)。
102
+
103
+ ## 计量与分成怎么读
104
+
105
+ | 计费方式 | 计量单位 | 舍入 | 适合 |
106
+ | --- | --- | --- | --- |
107
+ | `per_call` | 每次成功调用 | 精确到美分 | 确定性工具类 agent |
108
+ | `per_token` | 每 1k token | **向上取整**到 1k(不足 1k 按 1k) | 生成类 agent,成本主要是模型费 |
109
+ | `subscription` | 每周期 | 一次性 | 常驻/看板类 agent |
110
+
111
+ 分成规则:`platform = round(gross × fee%)`,**余数归开发者** —— 舍入误差不能让平台白赚钱,
112
+ 否则开发者对账永远差几分钱(`test_split_rounding_favours_developer` 钉住这条)。
113
+ `statement` 先按总额取整再逐行分配、末行兜底,保证 `platform + developer == gross` 逐行与合计都成立。
114
+
115
+ 出账有两个入口:人读的 Markdown 与 `--json`(金额单位是整数美分)。
116
+
117
+ ```bash
118
+ rm -f /tmp/agentstore.db # demo 每次都重新发布 3 个 agent,重跑前先删库
119
+ python3 -m agentstore.cli demo --db /tmp/agentstore.db
120
+ python3 -m agentstore.cli statement --db /tmp/agentstore.db --buyer acme \
121
+ --developer invoice-bot=northwind-labs --developer deck-research=quill-research \
122
+ --developer cfo-copilot=ledgerly --request-id st-2026-11 --json
123
+ ```
124
+
125
+ `--request-id` 是**出账**的幂等键(scope 到 buyer):同一个 id 再来原样回放首次快照,
126
+ 并把 `idempotent_replay` 置真 —— 回放连 `fee_pct` 一起回,所以拿到的可能是旧口径的数;
127
+ 要按新口径出账必须换新 id。没给 `--developer` 的 agent 记 `unknown`(`usage` 只记用量,不记归属)。
128
+ 退出码:`0` 跑通,`2` 用法错(缺 `--db`/`--buyer`、`--fee-pct` 不在 0..100、`--developer` 不是 `agent=dev`)。
129
+
130
+ ## 代码地图
131
+
132
+ ```
133
+ manifest.py AgentManifest / Pricing / 权限白名单 / canonical digest / semver / load_manifest
134
+ registry.py publish(不可覆盖)/ yank / latest / install(最小授权)/ granted
135
+ runtime.py resolve → status → gate(权限) → execute → meter(失败与拦截都不计费)
136
+ meter.py Ledger:request_id 幂等 + 指纹、三种定价、Statement 分账、出账快照
137
+ quickstart.py 生成 agentstore-quickstart/ 工作区(可重复执行,不覆盖用户改动)
138
+ fixtures.py invoice-bot(按次) / deck-research(按 token) / cfo-copilot(订阅)
139
+ cli.py quickstart / demo / statement
140
+ ```
141
+
142
+ ## 路线图
143
+
144
+ - [x] 清单 / 不可变版本 / 权限闸 / 幂等计量 / 分成账单 / quickstart
145
+ - [ ] 清单签名(Ed25519,公钥在商店侧),防止中间人替换 `agent.json`
146
+ - [ ] 执行隔离(子进程 + seccomp / 容器),当前 `handler` 是进程内回调
147
+ - [ ] 订阅周期结算(本版本把订阅当单次记账,缺少周期边界与按比例退款)
148
+ - [ ] 退款/争议流程(`usage` 表需要 `reversed_by` 与不可变审计链)
149
+ - [ ] 商店侧审核状态机(draft → in_review → published → yanked)
150
+
151
+ ## 已知边界
152
+
153
+ - **出账快照落成即冻结,`issued_at` 不是墙钟**:给了 `--request-id` 时,`gross/platform/developer/rows`
154
+ 连同 `fee_pct` 一起写进 `statements` 表(`meter.py:257`),此后同一 `(buyer, request_id)` 一律回放
155
+ (`meter.py:245`)—— 新增用量、新的 `--fee-pct` 都看不到;要重算必须换 id。`issued_at` 取 `Ledger._now`
156
+ (`meter.py:150`,默认硬编码 `2026-11-12T00:00:00Z`),是注入的测试时钟而非真实时间,接真系统时
157
+ 必须注入墙钟,否则所有快照的时间戳都相同。
158
+ - **金额用整数分,但账单只覆盖记进 `usage` 表的事件**:`Pricing.cents_per_unit` 与 `usage.cents` 都是整数(`manifest.py:32`、`meter.py:20`),展示时才用 `Decimal` 转美元(`meter.py:50`)。被权限闸拦下、handler 抛错、以及同 `(buyer, request_id)` 的重投都不会写 usage(`runtime.py:74`、`runtime.py:132`),所以账单里没有这些调用;反过来,绕过 `Runtime` 直接调 `Ledger.record` 的用量不受任何前置校验约束。整数分也做不了「$0.000003/token」这种粒度,真实系统应按 micro-cent 存整数。
159
+ - **版本归属以首次发布为准,不能转移**:`publish` 用 `INSERT OR IGNORE` 写入 `agents.developer`(`registry.py:77`),此后的发布者必须与首发布者一致(`registry.py:71`),没有转让或迁移归属的 API;`yank` 只改状态、不删版本(`registry.py:88`),买家已有安装仍保留记录。
160
+ - **分成先按总额取整、再逐行分配、末行兜底**:`statement` 先算 `target_fee`(`meter.py:226`),中间行各自取整并被夹在剩余额度内,最后一行拿走全部余额(`meter.py:229`),保证 `sum(platform) + sum(developer) == gross`。代价是每行金额依赖行顺序,不能对单行独立复算;抽成比例是账单参数(`statement(..., fee_pct=20)`)而不是合同。
161
+ - **registry 是单文件 SQLite,没有并发写保护**:`Registry` 直接 `sqlite3.connect(db_path)`(`registry.py:55`),默认 `:memory:`,未开 WAL、未设 `busy_timeout`、也没有进程内锁或重试;多进程/多线程同时 `publish`/`install` 会撞上 `database is locked` 或丢写。(`Ledger` 那边是另一套连接:`busy_timeout=5000` 且非 `:memory:` 开 WAL,`meter.py:130`。)
162
+ - **没有真实支付网络对接**:整个包没有任何网络请求或支付 SDK 调用。`payment.charge` 只是 `KNOWN_PERMISSIONS` 里的一个权限字符串(`manifest.py:19`),账单是本地 `usage` 表的聚合与 Markdown 渲染(`meter.py:118`),扣款、退款、对账、发票都留给外部系统。
163
+ - **digest 是内容哈希,不是签名**:`digest()` 只做 `sha256(canonical)`(`manifest.py:83`),能查出「同版本内容改了」,但证明不了「这份清单是开发者发的」;签名、执行隔离仍在路线图(`handler` 目前是进程内回调,`runtime.py:123`)。同理 `needs` 参与摘要只保证「装完之后要什么权限」没被偷改,不保证权限列表本身经过审核。
164
+ 另外:`needs` 是 0.1.0 之后加进 `canonical()` 的(`manifest.py:77`),所以**同一份清单的 digest
165
+ 与旧版不同**——摘要覆盖的字段变了。库里已有旧摘要的版本按「改内容就必须发新版本号」处理,
166
+ 不要在旧版本上原地覆盖。
167
+
168
+ ## 附:为什么要有权限声明(2026-11 的一次实测)
169
+
170
+ `scripts/fetch_mcp_servers.py` 从 GitHub 按 `mcp-server in:name` 取星标最高的仓库,
171
+ 拉 `package.json` 与 `README.md`,剔除 awesome-* 清单仓库后留下 **16 个真实 server**,
172
+ 再由 `scripts/real_manifests.py` 对每份跑入市审查。
173
+
174
+ | 指标 | 结果 |
175
+ |---|---|
176
+ | 清单里有任何权限字段(permissions/capabilities/scopes/mcp) | **0 / 16** |
177
+ | 文档/依赖显示需要 API 密钥 | 13 / 16 |
178
+ | 需要写文件 | 1 / 16 |
179
+ | 版本可固定(x.y.z) | 9 / 16 |
180
+
181
+ 零声明不是样本太少——这 16 个合计超过 10 万星标,含 GitHub、Cloudflare、Notion、Firecrawl
182
+ 的官方 server。买家装这些东西时,没有任何机器可读的东西告诉他这个 agent 能不能读文件、
183
+ 能不能拿 token。这条事实决定了商店该做什么:不是托管,而是**替买家把没写的东西补出来**,
184
+ 并让补出来的结论进入安装决策。同样这轮实测把「要写文件」从 9 份修到 1 份(`credits` 里的
185
+ `edit`、`actions/checkout` 两个假阳性),假阳性比漏报更贵。
186
+
187
+ 重跑:
188
+
189
+ ```bash
190
+ python3 scripts/fetch_mcp_servers.py 20 # 抓清单(写 data/raw/,已 gitignore)
191
+ python3 scripts/real_manifests.py # 审查 + 打印结论表
192
+ ```
193
+
194
+ ## 许可证
195
+
196
+ MIT,见 [LICENSE](LICENSE)。
@@ -0,0 +1,3 @@
1
+ """agentstore —— agent 应用商店的最小内核:清单 + 不可变版本 + 权限闸 + 计量 + 分成。"""
2
+
3
+ __version__ = "0.1.0"
@@ -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())
@@ -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
+ )