aaas-service 0.1.0__tar.gz

aaas_service-0.1.0/.env.example

@@ -0,0 +1,24 @@
+# 本文件只是变量清单，不含任何真实值；拷成 .env 后填自己的（.env 已被 gitignore）。
+# 优先级：命令行参数 > AAAS_* > 提供方约定变量 > 内置默认（见 aaas_service/providers.py）。
+
+# 提供方：openai | deepseek | dashscope | anthropic
+AAAS_PROVIDER=deepseek
+# 模型名。注意它是**进程级**的、不区分提供方：换 provider 前先清掉，否则会跨过去。
+AAAS_MODEL=
+# 自建网关 / 代理地址（需带 scheme）
+AAAS_BASE_URL=
+# 通用凭据兜底；也可以改用各提供方的约定变量
+AAAS_API_KEY=
+
+# 提供方约定变量（选一个填即可）
+DEEPSEEK_API_KEY=
+OPENAI_API_KEY=
+OPENAI_BASE_URL=
+DASHSCOPE_API_KEY=
+ANTHROPIC_API_KEY=
+
+# aaas SDK 源码目录（未 pip install 时必需；也可以写进 .aaas-src）
+AAAS_SRC=
+
+# 置 1 才跑会真花钱的 live 用例
+AAAS_LIVE=

aaas_service-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 the aaas-service authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

aaas_service-0.1.0/MANIFEST.in

@@ -0,0 +1,22 @@
+# sdist 里要有「跑得起来看」的东西；wheel 里只放包（见 pyproject 的 packages）。
+#
+# 为什么 tests 进 sdist：下游打包者（发行版、公司内镜像）跑测试是标准动作，而一份
+# 没有测试的源码包等于让他们只能靠读代码判断真伪。tests 依赖 conftest.py 与
+# srcpath.py，所以三者必须一起进 —— 只放 tests 会得到一个 import 就崩的测试目录。
+include LICENSE
+include README.md
+include README-IMPLEMENTATION.md
+include PROPOSAL-aaas-agentscope.md
+include REVIEW-jev.md
+include requirements.txt
+include requirements-dev.txt
+include pytest.ini
+include conftest.py
+include srcpath.py
+recursive-include tests *.py
+
+# 模板要进：它是唯一一处集中记录 AAAS_* 变量名的地方（里面没有任何真实值）。
+include .env.example
+
+# 反过来：运行期产物与本地配置永远不进包。
+global-exclude __pycache__ *.py[cod] .aaas-src .env

aaas_service-0.1.0/PKG-INFO

@@ -0,0 +1,309 @@
+Metadata-Version: 2.4
+Name: aaas-service
+Version: 0.1.0
+Summary: 用 AgentScope 驱动的 AaaS（Agent as a Service）协议服务端：模型在服务端，能力与副作用全部回到调用方进程
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/YY-Yifei/openagent-aaas
+Project-URL: Repository, https://github.com/YY-Yifei/openagent-aaas
+Project-URL: Issues, https://github.com/YY-Yifei/openagent-aaas/issues
+Project-URL: Specification, https://github.com/YY-Yifei/aaas/blob/main/PROTOCOL.md
+Keywords: aaas,agent-as-a-service,agentscope,llm,mcp,function-calling,websocket
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: agentscope<2.1,>=2.0.5
+Requires-Dist: aaas<0.3,>=0.2.1
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24; extra == "test"
+Requires-Dist: pydantic>=2; extra == "test"
+Dynamic: license-file
+
+# aaas-service
+
+用 [AgentScope](https://github.com/agentscope-ai/agentscope) 驱动的 **AaaS（Agent as a Service）协议**
+服务端参考实现。
+
+一句话概括它和其它 Agent 服务的区别：
+
+> **服务端没有内置能力。** 调用方声明什么函数，模型就只能伸到什么能力；
+> 而每一次伸手，都伸回**调用方自己的进程**去执行。
+
+所以模型、凭据、业务数据全在你的进程里，服务端只是一个「会思考但手无寸铁」的壳。
+
+---
+
+## 安装
+
+```bash
+pip install aaas-service
+```
+
+```bash
+set "DEEPSEEK_API_KEY=sk-..."   # bash: export DEEPSEEK_API_KEY=sk-...
+aaas-service                    # 等价于 python -m aaas_service，默认监听 127.0.0.1:8888
+aaas-service --print-config     # 不起服务、不联网、不要 key，只告诉你每个配置值来自哪
+```
+
+只需要 Python ≥ 3.11（下限由 `agentscope` 决定）。仓库在
+[github.com/YY-Yifei/openagent-aaas](https://github.com/YY-Yifei/openagent-aaas)；
+想改代码、跑测试，看下面「依赖」与「跑测试」。
+
+## 它做了什么
+
+| 能力 | 说明 |
+|---|---|
+| 单轮 ReAct 闭环 | `handler(ctx)` 一个函数里跑完「模型 → 工具 → 模型 → 收尾」 |
+| 反向 function calling | 工具调用经协议回到调用方执行，服务端不持有任何实现与凭据 |
+| 流式回复 | 文本 / 思考块 / 工具事件分段推送，`block_id` 直接映射 `message_id` |
+| stateless 会话 | 每轮由调用方重放 history，服务端零记忆（可切 `session` 模式） |
+| 用量上报 | token / 工具次数；**拿不到就不填，绝不写 0** |
+| 模型配置 | 提供方 / 模型名 / 地址 / 凭据四件事，一律从命令行 + 环境变量来 |
+
+```
+aaas_service/          服务端实现（**只有这个包进 wheel**）
+  app.py               装配 + 命令行入口（--print-config / --host / --port …）
+  handler.py           唯一的接缝：async def handler(ctx)
+  providers.py         提供方表 + 四个旋钮的解析（命令行 > AAAS_* > 约定变量 > 默认）
+  events.py            AgentScope 事件 → AaaS 协议的桥
+  tools.py             协议里的 JSON Schema → 可直接调用的工具
+  usage.py             token / 调用计数（未知 ≠ 0）
+  history.py           历史重放与裁剪
+  validate.py          入参校验
+pyproject.toml         打包元数据（PEP 621；版本真源 = aaas_service.__version__）
+scripts/
+  chat.py              交互式调用方（工具在你自己进程里执行）
+  service_ctl.py       起停 / 状态（真握手探活，不是裸端口探测）
+tests/                 单元 + 端到端（默认全离线，不联网不花钱）
+srcpath.py             定位 aaas SDK 源码（AAAS_SRC / .aaas-src）—— **开发用，不打包**
+README-IMPLEMENTATION.md   实施说明：每条设计决策背后的实测与坑
+PROPOSAL-aaas-agentscope.md 方案与两侧事实核对
+REVIEW-jev.md          关键判定的决策记录
+```
+
+`scripts/`、`tests/`、`srcpath.py` 都依赖仓库布局，所以**不进 wheel**：
+`pip install aaas-service` 只会装 `aaas_service` 一个包（`tests/test_packaging.py` 守着这条）。  app.py               装配 + 命令行入口（--print-config / --host / --port …）
+  handler.py           唯一的接缝：async def handler(ctx)
+  providers.py         提供方表 + 四个旋钮的解析（命令行 > AAAS_* > 约定变量 > 默认）
+  events.py            AgentScope 事件 → AaaS 协议的桥
+  tools.py             协议里的 JSON Schema → 可直接调用的工具
+  usage.py             token / 调用计数（未知 ≠ 0）
+  history.py           历史重放与裁剪
+  validate.py          入参校验
+scripts/
+  chat.py              交互式调用方（工具在你自己进程里执行）
+  service_ctl.py       起停 / 状态（真握手探活，不是裸端口探测）
+tests/                 单元 + 端到端（默认全离线，不联网不花钱）
+srcpath.py             定位 aaas SDK 源码（AAAS_SRC / .aaas-src）
+README-IMPLEMENTATION.md   实施说明：每条设计决策背后的实测与坑
+PROPOSAL-aaas-agentscope.md 方案与两侧事实核对
+REVIEW-jev.md          关键判定的决策记录
+```
+
+## 依赖
+
+- Python ≥ 3.11 —— 这是 `agentscope` 的要求；本仓库在 3.12 上实测（语法用
+  `ast.parse(feature_version=…)` 一路验到 3.9 都能解析，但下限由依赖说了算）
+- 一次装齐（`agentscope` + `aaas` + `pytest`）：`pip install -e ".[test]"`
+
+**aaas SDK 已发布到 PyPI**（[`aaas`](https://pypi.org/project/aaas/) 0.2.1），
+`pip install` 会一并装上，**不需要** `AAAS_SRC` 了。剩下的唯一用途是「我要改 aaas
+源码」——那时把它的 `src` 指过来，本项目的 `conftest.py` / `scripts` 会优先用它：
+
+```bash
+# 方式一：环境变量
+set "AAAS_SRC=D:\path\to\aaas\src"        # bash: export AAAS_SRC=/path/to/aaas/src
+# 方式二：仓库根写一行（已 gitignore，适合本地长期开发）
+echo D:\path\to\aaas\src > .aaas-src
+```
+
+代码里**不写死任何路径**：两条路都没有时，`conftest.py` 会明确告诉你缺什么，
+而不是去猜一个「我本机恰好有」的目录。
+
+## 快速开始
+
+```bash
+# 0) 让 Python 找得到 aaas 源码（未 pip install 时必需）。
+#    注意：.aaas-src 只被 conftest.py / scripts 里的入口读取 —— `python -m aaas_service`
+#    是标准模块入口，它只认 PYTHONPATH，不认那个文件（库不该偷偷改 sys.path）。
+set "AAAS_SRC=D:\path\to\aaas\src"
+set "PYTHONPATH=%AAAS_SRC%;."
+
+# 1) 起服务（需要真实凭据；默认监听 127.0.0.1:8888）
+set "DEEPSEEK_API_KEY=sk-..."
+python -m aaas_service
+
+# 2) 只想确认「这套环境最终会用什么」—— 不起服务、不联网、不要 key
+python -m aaas_service --print-config
+
+# 3) 交互式调用方（另开一个终端）
+python scripts/chat.py
+```
+
+变量清单见 [`.env.example`](.env.example)（只有变量名，没有任何真实值）。
+`--print-config` 的输出会把**每个值的来源**一起印出来（`--model` / `AAAS_MODEL` /
+`内置默认` …），凭据只报变量名与长度、永不报值：
+
+```
+配置   provider=deepseek（--provider） model=deepseek-flash（内置默认）
+       base_url=https://api.deepseek.com（内置默认） api_key=DEEPSEEK_API_KEY(len=35)
+```
+
+`python scripts/service_ctl.py start|status|stop|config` 是同一套装配的进程管理入口，
+`status` 做的是一次**真正的协议握手**（端口开着只证明有人 listen，握手成功才证明
+对端是 aaas 且宣告的能力都在）。
+
+## 模型配置从哪来
+
+四个旋钮在**进程启动时**解析一次，调用方永远影响不了它们。顺序是一条规则，没有例外：
+
+```
+命令行参数（--provider / --model / --base-url / --api-key）
+  > AAAS_PROVIDER / AAAS_MODEL / AAAS_BASE_URL / AAAS_API_KEY
+    > 提供方约定变量（OPENAI_API_KEY、OPENAI_BASE_URL、DEEPSEEK_API_KEY …）
+      > 内置默认
+```
+
+| 提供方 | 内置默认模型 | 默认地址 |
+|---|---|---|
+| `openai` | `gpt-4o-mini` | SDK 默认 |
+| `deepseek` | `deepseek-flash` | `https://api.deepseek.com` |
+| `dashscope` | `qwen-max` | dashscope 兼容端点 |
+| `anthropic` | `claude-sonnet-4-5` | SDK 默认 |
+
+**空值就是没设**：`set "VAR="` 留下的空变量不会顶掉默认值；`AAAS_SRC` 这类路径变量
+还会顺手剥掉误包的引号（`set VAR="C:\x"` 会把引号一起存进值里）。
+
+## 跑测试
+
+```bash
+pip install -e ".[test]"              # 含 agentscope / aaas / pytest / pytest-asyncio
+python -m pytest tests -q             # 全离线
+set "AAAS_LIVE=1" && python -m pytest tests -q   # 加上真调用的 live 用例（花钱）
+```
+
+**`pytest-asyncio` 不是可选项**：`pytest.ini` 里的 `asyncio_mode = auto` 只有它认。
+少了它，所有 `async def test_*` 只会得到一条 warning 然后被**跳过** —— 一片绿色里
+十几个用例其实一次都没执行。这是本项目被评审点名过的坑，别踩第二次。
+
+单元与端到端都不联网：模型用脚本化的假模型替身，协议层跑真 WebSocket。
+
+## 改代码的流程（本仓库的硬规矩）
+
+**任何代码改动都必须先过 `ocr`（open-code-review）再提交。** 它不是可选的唠叨，
+理由很实在：这个项目的坑大多长在「看起来没问题」的地方（未知 token 写成 0、
+`None` 与默认值混淆、GBK 下的编码崩溃），人工评审很容易顺着作者的想法走。
+
+```bash
+# 审「工作区改动」：staged + unstaged + untracked 全都要
+ocr review
+
+# 机器可读，便于逐条跟踪
+ocr review --format json -o .tmp/review.json
+
+# 没有 diff 也要审（例如初次引入一个模块）
+ocr scan --path aaas_service,tests
+```
+
+评审意见的处理约定：
+
+1. **每条都要有结论**：采纳就改；不采纳就在 PR / 提交说明里写清为什么不采纳。
+   「看到了但没管」不算结论。
+2. 改完**再跑一次**，直到没有阻塞项。
+3. `ocr` 的 LLM 配置属于个人环境（`ocr config`），**不进仓库**。
+
+## 发布
+
+版本号只有一个真源：`aaas_service/__init__.py` 的 `__version__`。
+`pyproject.toml` 里**不写** version，构建时由 `[tool.setuptools.dynamic]` 取那个属性
+（两份写死在早晚会漂移）。发布流程：
+
+```bash
+# 1) 改 aaas_service/__init__.py 的 __version__
+# 2) 改完代码先过 ocr（见下节），测试绿了再打包
+python -m pytest tests -q
+python -m build                       # 产出 dist/*.whl 与 dist/*.tar.gz
+python -m twine check dist/*          # 校验 README 能渲染、元数据完整
+python -m twine upload dist/*         # 需要 ~/.pypirc 里的 [pypi] token
+```
+
+两条硬规矩：
+
+- **PyPI 上的版本号不可覆盖、不可删除重发。** 发坏了只能发下一个版本 ——
+  所以 `twine check` 和「干净 venv 装一遍 wheel」不是可选项（这条我们真踩过）。
+- **凭据只从 `~/.pypirc` / 环境变量来**，永不进仓库、永不进日志
+  （`--print-config` 只报变量名与长度，不报值）。
+
+## 相关文档
+
+- [README-IMPLEMENTATION.md](README-IMPLEMENTATION.md) —— 实施细节、逐条实测、踩过的坑
+- [PROPOSAL-aaas-agentscope.md](PROPOSAL-aaas-agentscope.md) —— 方案与协议事实核对
+- [REVIEW-jev.md](REVIEW-jev.md) —— 关键设计判定的决策记录
+
+## License
+
+[Apache-2.0](LICENSE)
+
+## 评审流程（ocr）
+
+本仓库的规矩：**改代码 → 过 `ocr` → 每条意见都有结论 → 才提交。**
+不是「建议」，是提交前的必要条件 —— 因为这套代码里最贵的 bug 都不是写错的，
+而是「看起来对、在边角上静默做错事」的那种。
+
+### 工具
+
+[open-code-review](https://www.npmjs.com/package/open-code-review)（`ocr`，需要 Node）：
+
+```bash
+npm i -g open-code-review
+ocr llm test            # 先确认它自己能用（provider / model / key）
+ocr review --format json -o .tmp/review.json --audience agent
+```
+
+### 三步，顺序不能变
+
+```bash
+git add -A                                       # ① 评审读的是 **git index**
+ocr review --format json -o .tmp/review.json --audience agent   # ② 跑评审
+python -m pytest tests -q                        # ③ 改完必须仍然是绿的
+```
+
+**① 是这条流程里最容易白烧钱的一步。** `ocr review` 看的是 index 里那份快照：
+改完不 `git add -A`，它评的还是改之前的代码（我们照着做时白跑过一整轮，
+40 条意见里 32 条是上一轮的重复）。
+
+### 每条意见都要有结论
+
+两类结论都算「有结论」，但**必须写出来**：
+
+- **采纳** —— 改代码，并在 `tests/test_review_fixes.py` 里加一条回归测试
+  （每条测试的 docstring 点名它守的是哪个坑）。
+- **驳回** —— 写下实测理由。本项目驳回过的三类，都是「意见本身不成立」：
+  `__main__` 改名（dunder 是本项目的命令行入口约定，`main` 会凭空多一个空参数工具）、
+  `--provider` 标注（子进程**真的**收到了这个参数，标注准确）、
+  `ctx.error = int`（实测 `aaas.TurnContext.error` 的类型是 `AAASError | None`）。
+
+### 本仓库的实际记录
+
+| 轮次 | 意见数 | 最高级别 | 处理 |
+|---|---|---|---|
+| 1 | 39 | HIGH ×2 | 全采纳 |
+| 2 | 40 | MEDIUM | 8 条真新问题（其余是 index 未刷新） |
+| 3 | 19 | MEDIUM | 全采纳 |
+| 4 | 20 | MEDIUM | 全采纳 |
+| 5 | 17 | MEDIUM | 全采纳 |
+| 6 | 23 | MEDIUM | 采纳 22 / 驳回 3 |
+| 7 | 9 | HIGH ×1 | 全采纳（HIGH 是第 6 轮修复自己引入的回归） |
+| 8 | 10 | MEDIUM ×1 | 全采纳 |
+| 9 | 见下 | — | 发布准备（pyproject / 打包 / 发布流程） |
+
+一条经验：**第 7 轮那条 HIGH 是我自己修出来的**（引用了一个只存在于注释里的常量，
+于是诊断工具在「pid 文件过期」这种最常见的情况下自己崩了）。所以「改完就跑一遍」
+不是形式主义 —— 修复本身也会是新的 bug 源，而评审 + 回归测试是唯一能抓住它的东西。