spineagent 0.0.1__tar.gz

spineagent-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+# spineagent CI —— push + PR 上跑 lint + 测试,Python 多版本矩阵。
+#
+# 关键约束:spineagent 依赖兄弟薄核 corespine,而 corespine 尚未发到 PyPI。所以 CI 里把
+# corespine【并排签出】到工作区,再【先于】spineagent path-install —— 复刻本地家族布局
+# (spineagent 的 uv path source 指向 ../corespine)。之后用 Makefile 跑与本地同一套门。
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  ci:
+    name: lint + test (py${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12"]
+    steps:
+      # 把 spineagent 自身签出到 ./spineagent,使其与 corespine 在工作区里【并排】。
+      - name: Checkout spineagent
+        uses: actions/checkout@v4
+        with:
+          path: spineagent
+
+      # corespine 还没上 PyPI(兄弟仓库),这里并排签出到 ./corespine。
+      # 从 ./spineagent 看过去就是 ../corespine —— Makefile 的 `uv pip install -e ../corespine`
+      # 与 pyproject 的 uv path source 都能原样命中。
+      #
+      # corespine 是公开兄弟仓库,直接并排签出,无需 token。
+      #   若将来转私有,补一行 `token: ${{ secrets.CORESPINE_CHECKOUT_TOKEN }}`
+      #   (一个对 corespine 有读权限的 PAT / deploy key)。
+      - name: Checkout corespine (sibling, not yet on PyPI)
+        uses: actions/checkout@v4
+        with:
+          repository: VoldemortGin/corespine
+          path: corespine
+          # ref: main                       # 需锁定分支/标签时取消注释
+
+      - name: Set up uv (+ Python ${{ matrix.python }})
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      # `make install` 建 venv 并先装 corespine、再装 spineagent[dev];`make ci` = lint + 测试。
+      - name: Install (corespine first, then spineagent[dev])
+        working-directory: spineagent
+        run: make install
+
+      - name: CI gate (lint + test)
+        working-directory: spineagent
+        run: make ci

spineagent-0.0.1/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+*.pyc
+.pytest_cache/

spineagent-0.0.1/CLAUDE.md

@@ -0,0 +1,64 @@
+# CLAUDE.md — spineagent(宪章)
+
+Spine 家族的 AI / 人类协作契约。先读家族 `../README.md` 与
+`../docs/adr/0001-spine-family-boundaries-and-dependency-direction.md`,本文件是 spineagent 的操作指南。
+
+## 这是什么
+
+**spineagent —— 通用多 agent 协作框架**(ADR 0001 D1)。agent / tool / 编排 + MCP / A2A 等
+agent 协议缝。它是家族里【演进最快】的成员,刻意单开独立包,**不**拖累薄核与兄弟包。它依赖薄核
+`corespine`,复用其缝元模式与 observability / config 形状,但**不**含任何 RAG 概念。
+
+## 宪章(不可违背)
+
+- **离线优先、import-clean、零重依赖默认路径。** 核心默认路径只用标准库 + `corespine`;真实协议
+  SDK(MCP / A2A 等)经**可选 extra 延迟 import**(`corespine.lazy_extra_import`),缺 extra 时给
+  「pip install spineagent[<extra>]」友好报错。**import spineagent 绝不拉入任何网络 SDK**
+  (有 `tests/test_import_clean.py` 把这条钉死)。
+- **每条缝长一个样**(家族统一元模式):**Protocol + 离线确定性默认 + Registry 工厂 + 参数化
+  conformance**。core 只 import Protocol,绝不 import SDK。
+- **机制借 corespine,保证本包自绑**(ADR 0001 D6)。corespine 只给 conformance 基座;具体不变量
+  (agent 步 provenance、步级 trace 隐私安全、tool 结果 provenance)由 `spineagent/conformance.py`
+  绑定,并用参数化 conformance 测试钉死。
+- **不在包层面依赖 ragspine。** 可在【运行时】把 ragspine 当一个 Tool / MCP server 组合调用
+  (ADR 0001 D4b),那是松耦合的可选组合,方向只能 spineagent→ragspine,绝不反向,也绝不写进
+  `dependencies`。
+- **隐私 trace。** 任何步级 / 编排级 trace 只记 code / 计数 / 耗时,绝不记任务或输出正文。
+
+## 模块地图(按文件夹定位)
+
+```
+src/spineagent/
+  agent/agent.py            Agent 协议 + LlmAgent(走 corespine LLMProvider)/ FunctionAgent(纯函数)
+  llm/provider.py           真实 LLM provider 适配器(对外统一 OpenAI chat-completions 形状):OpenAICompatProvider(openai SDK + base_url 吃下所有 OpenAI 兼容端点)+ AnthropicProvider(默认 claude-opus-4-8);llm_providers Registry。各走可选 extra 延迟 import,离线默认仍 MockProvider。
+  llm/cohere_provider.py    CohereProvider:Cohere v2 native → OpenAI ChatCompletion([cohere] extra)
+  llm/gemini_provider.py    GeminiProvider:Gemini generateContent native → OpenAI ChatCompletion([gemini] extra,同覆盖 Vertex Gemini)
+  llm/bedrock_provider.py   BedrockConverseProvider:AWS Bedrock Converse native → OpenAI ChatCompletion([bedrock] extra,Converse 跨模型同形)
+  agent/policy.py           ToolPolicy 缝:协议 + 离线确定性默认 SyntaxToolPolicy(`<tool>: <arg>` 语法路由,不假装 LLM 推理)+ tool_policies Registry
+  agent/tool_using.py       ToolUsingAgent:离线确定性多步循环(SyntaxToolPolicy 语法路由),带 max_steps 守卫;实现 Agent 协议
+  agent/function_calling.py FunctionCallingAgent:真 LLM function-calling 多步循环(FunctionTool schema → chat(tools=) → tool_calls → 执行 → OpenAI tool 角色喂回 → 再 chat);实现 Agent 协议,底层换任意 provider 不改一行
+  agent/as_tool.py          AgentTool:把 Agent 桥成 Tool(分层 / 督导式多 agent:督导 agent 通过工具调用派活给子 agent,可嵌套)
+  tools/tool.py             Tool 协议 + EchoTool / CalcTool + tool_registry(spec 选工具 + entry-point 第三方工具发现,group corespine.tool);注:运行时可把 ragspine RAG 插为 Tool
+  tools/function_tool.py    FunctionTool(带 JSON-schema、接 dict 参数,给真 function-calling 用)+ @function_tool 装饰器(从签名自动推 schema)
+  orchestration/coordinator.py  Coordinator:顺序 / 并行 / 流水线(output→input)跑多 agent、保序收集;弹性容错 resilient 把异常归一为 AgentResult.error,坏 agent 不炸整批
+  orchestration/chain.py        ChainAgent:把一串 agent 串成单个 Agent(流水线即一等可组合单元:可进 Coordinator / 当工具 / 套 chain)
+  protocol/mcp/seam.py      McpClient / McpServer 协议 + OfflineMcpStub(离线回环)+ McpClientTool(MCP 工具→Tool)+ 延迟真实 SDK
+  protocol/a2a/seam.py      A2AAgent 协议 + OfflineA2AStub(离线回环)+ A2AAgentAdapter(A2A→Agent)+ 延迟真实 SDK
+  conformance.py            本包绑定的不变量包(AGENT_INVARIANTS / TOOL_INVARIANTS / POLICY_INVARIANTS)
+```
+
+## 跑(始终从包根)
+
+```bash
+uv venv .venv
+VIRTUAL_ENV="$(pwd)/.venv" uv pip install -e ../corespine   # 本地兄弟包
+VIRTUAL_ENV="$(pwd)/.venv" uv pip install -e ".[dev]"
+.venv/bin/python -m pytest -q          # 期望 GREEN
+.venv/bin/python -c "import spineagent"  # 期望 import-clean(无网络 SDK)
+```
+
+## 约定
+
+- Python **3.10+** 类型注解;import 顺序 **stdlib > 三方 > 本地**;简体中文 docstring/注释,匹配家族风格。
+- **TDD**——测试即规格;**最小改动**——只改需求要求的部分。
+- **深层、按领域分组**的布局:文件路径先定位职责,再读文件名。

spineagent-0.0.1/Makefile

@@ -0,0 +1,49 @@
+# spineagent —— 一键开发 / CI 命令(始终从包根跑)。
+#
+# `make` 或 `make help` 列出全部目标。默认走包内 venv;可覆盖解释器:
+#   make test PYTHON=python3.12
+#
+# 跨平台:用 $(VENV)/$(PYTHON) 变量(对齐家族 ragspine 的写法)。
+
+.DEFAULT_GOAL := help
+PYTHON ?= .venv/bin/python
+VENV   ?= .venv
+
+# ---- 安装 --------------------------------------------------------------------------
+
+.PHONY: install
+install: ## 建 venv 并可编辑安装:先装兄弟薄核 corespine,再装 spineagent[dev]
+	uv venv $(VENV)
+	VIRTUAL_ENV="$(CURDIR)/$(VENV)" uv pip install -e ../corespine
+	VIRTUAL_ENV="$(CURDIR)/$(VENV)" uv pip install -e ".[dev]"
+
+# ---- 质量门 ------------------------------------------------------------------------
+
+.PHONY: ci
+ci: lint test ## 本地 CI 门:lint + 测试(与 CI 同一套门)
+
+.PHONY: test
+test: ## 跑测试套件(离线、确定性)
+	$(PYTHON) -m pytest -q
+
+.PHONY: lint
+lint: ## ruff 静态检查(风格 + import 序 + 死代码)
+	$(PYTHON) -m ruff check src/spineagent tests examples
+
+.PHONY: fmt
+fmt: ## ruff 自动格式化
+	$(PYTHON) -m ruff format src/spineagent tests examples
+
+# ---- demo --------------------------------------------------------------------------
+
+.PHONY: demo
+demo: ## 跑一键离线 demo(多 agent 顺序/并行 + 工具派发 + 隐私 trace,零网络)
+	$(PYTHON) examples/quickstart.py
+
+# ---- meta --------------------------------------------------------------------------
+
+.PHONY: help
+help: ## 列出可用目标
+	@grep -hE '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) \
+		| sort \
+		| awk 'BEGIN{FS=":.*?## "}{printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'

spineagent-0.0.1/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: spineagent
+Version: 0.0.1
+Summary: Spine 家族的通用多 agent 协作框架:agent / tool / 编排 + MCP / A2A 协议缝(离线优先,依赖 corespine)。
+Author: lin han
+License-Expression: Apache-2.0
+Keywords: a2a,agent,conformance,framework-free,mcp,multi-agent,offline,orchestration,seam
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: corespine
+Provides-Extra: a2a
+Requires-Dist: a2a-sdk; extra == 'a2a'
+Provides-Extra: anthropic
+Requires-Dist: anthropic; extra == 'anthropic'
+Provides-Extra: bedrock
+Requires-Dist: boto3; extra == 'bedrock'
+Provides-Extra: cohere
+Requires-Dist: cohere; extra == 'cohere'
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Provides-Extra: gemini
+Requires-Dist: google-genai; extra == 'gemini'
+Provides-Extra: mcp
+Requires-Dist: mcp; extra == 'mcp'
+Provides-Extra: openai
+Requires-Dist: openai; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# spineagent
+
+Spine 家族的**通用多 agent 协作框架**(见 [ADR 0001](../docs/adr/0001-spine-family-boundaries-and-dependency-direction.md))。
+agent / tool / 编排 + **MCP / A2A** 等 agent 协议缝。依赖薄核 `corespine`,复用其缝元模式与
+observability / config 形状;**默认路径离线可跑、import-clean、零网络 SDK**。
+
+> 通用 ≠ 地基。真正的核是更薄的 `corespine`,spineagent 是它的兄弟消费者,**不**含任何 RAG 概念。
+> 详见 [`CLAUDE.md`](CLAUDE.md) 宪章。
+
+## 缝的元模式(家族统一)
+
+每条缝都长一个样,核心 import 零 SDK、离线可跑:
+
+**Protocol + 离线确定性默认 + `Registry` 工厂 + 参数化 conformance**
+
+## 里面有什么
+
+| 模块 | 原语 |
+|---|---|
+| `agent/agent.py` | `Agent` 协议 + `LlmAgent`(走 corespine `LLMProvider`,离线用 `MockProvider`)/ `FunctionAgent`(纯函数节点);步级 trace 只记元数据 |
+| `llm/provider.py` 等 | 真实 LLM provider 适配器(挂在 corespine `LLMProvider` 缝后面;**对外统一 OpenAI chat-completions 形状**):`OpenAICompatProvider`(`openai` SDK + `base_url`,一个吃下 OpenAI/Azure/Together/Groq/DeepSeek/Mistral/xAI/Qwen/Moonshot/Ollama/vLLM/OpenRouter/LiteLLM… 全部 OpenAI 兼容端点)+ 非 OpenAI 原生适配器把 native 转成 OpenAI 形状:`AnthropicProvider`(默认 `claude-opus-4-8`)/ `CohereProvider` / `GeminiProvider` / `BedrockConverseProvider`。`llm_providers` Registry(mock/openai/anthropic/cohere/gemini/bedrock)。各走可选 extra 延迟 import,离线默认仍是 `MockProvider`,各用原生 SDK 不 shim |
+| `agent/policy.py` | `ToolPolicy` 协议 + 离线确定性默认 `SyntaxToolPolicy`(按 `<tool>: <arg>` 语法 + 工具名集合确定性路由,**不假装 LLM 推理**)+ `tool_policies` Registry(`llm` 位留真实推理式接入) |
+| `agent/tool_using.py` | `ToolUsingAgent`:**离线确定性**多步循环(`SyntaxToolPolicy` 按 `<tool>: <arg>` 语法路由),带 `max_steps` 守卫;实现 `Agent` 协议 |
+| `agent/function_calling.py` | `FunctionCallingAgent`:**真 LLM function-calling** 多步循环——把 `FunctionTool` schema 喂给 `chat(tools=)`,模型回 tool_calls → 执行 → 以 OpenAI tool 角色喂回 → 再 chat,直到出文本或触顶;底层换任意 provider 不改一行。实现 `Agent` 协议 |
+| `tools/function_tool.py` | `FunctionTool`(带 JSON-schema、接 dict 参数的结构化工具)+ `@function_tool` 装饰器(从签名/注解/docstring 自动推 schema) |
+| `agent/as_tool.py` | `AgentTool`:把一个 `Agent` 桥成 `Tool`,让督导 agent 通过工具调用把子任务派给专精子 agent(**分层 / 督导式多 agent**,可层层嵌套) |
+| `tools/tool.py` | `Tool` 协议 + `EchoTool` / `CalcTool`(安全算术求值);结果带 provenance。`tool_registry`:spec 选工具 + **entry-point 第三方工具自动发现**(group `corespine.tool`)。**运行时可把 ragspine RAG 插为一个 Tool**(见下) |
+| `orchestration/coordinator.py` | `Coordinator`:把多个 agent **顺序 / 并行 / 流水线**(output→input 链式)跑、保序收集 `AgentResult`;**弹性容错**(`resilient=True`)把单 agent 异常归一为家族错误 dict 塞进 `AgentResult.error`、一个坏 agent 不炸整批 |
+| `orchestration/chain.py` | `ChainAgent`:把一串 agent 串成**单个 `Agent`**(流水线即一等可组合单元),可再进 `Coordinator` / 被 `AgentTool` 当工具 / 套 chain |
+| `protocol/mcp/seam.py` | `McpClient` / `McpServer` 协议 + `OfflineMcpStub`(进程内回环)+ **`McpClientTool`(把 MCP 工具桥成 `Tool`)** + 真实 SDK 经 `[mcp]` extra 延迟 import |
+| `protocol/a2a/seam.py` | `A2AAgent` 协议 + `OfflineA2AStub`(进程内回环)+ **`A2AAgentAdapter`(把 A2A agent 桥成 `Agent`)** + 真实 `a2a-sdk` 经 `[a2a]` extra 延迟 import |
+| `conformance.py` | 本包绑定的不变量:`AGENT_INVARIANTS`(步产出 / provenance / 隐私 trace)、`TOOL_INVARIANTS`(结果 provenance)、`POLICY_INVARIANTS`(决策形状 / 不幻觉工具 / 可终止 / 纯函数) |
+
+## 运行时组合 ragspine(ADR 0001 D4b)
+
+spineagent **不**在包层面依赖 ragspine。但可在**运行时**把 ragspine 的 RAG 检索包成一个实现了
+`Tool`(或 MCP server)协议的适配器,插给某个 agent 调用——松耦合、可选,方向只能 spineagent→ragspine。
+本包 `dependencies` 永远不含 ragspine,也绝不在默认路径 import 它。
+
+第三方工具(含 ragspine RAG)还可经 entry-point 在 `corespine.tool` group 下注册工具工厂,即被
+`tool_registry.make / names` 自动发现、零改本包代码组合进 agent;而它们仍须过 `TOOL_INVARIANTS`
+conformance 才算数——「敢放手让第三方填广度,却让脊柱不变量烂不掉」。
+
+## 本地开发(始终从包根)
+
+```bash
+uv venv .venv
+VIRTUAL_ENV="$(pwd)/.venv" uv pip install -e ../corespine
+VIRTUAL_ENV="$(pwd)/.venv" uv pip install -e ".[dev]"
+.venv/bin/python -m pytest -q
+.venv/bin/python -c "import spineagent"
+```
+
+## 30 秒上手
+
+```python
+from corespine import MockProvider, InProcessPrivacyTraceSink
+from spineagent import LlmAgent, FunctionAgent, Coordinator, EchoTool, OfflineMcpStub
+from spineagent.protocol.mcp.seam import McpTool
+
+# 一个离线 agent:走 corespine 的确定性 MockProvider,跑单步
+agent = LlmAgent("planner", MockProvider())
+print(agent.step("列个计划").output)            # 确定性、可复现
+
+# 多 agent 编排:顺序 / 并行跑同一任务,保序收集
+coord = Coordinator([FunctionAgent("a", lambda t: f"a:{t}"),
+                     FunctionAgent("b", lambda t: f"b:{t}")])
+print([r.output for r in coord.run_parallel("go")])   # ['a:go', 'b:go']
+print([r.output for r in coord.run_pipeline("go")])   # ['a:go', 'b:a:go'](链式:上一个输出喂下一个)
+
+# 弹性容错:坏 agent 不炸整批,异常归一为结构化 error,批次照常跑完
+flaky = Coordinator([FunctionAgent("ok", lambda t: t),
+                     FunctionAgent("bad", lambda t: 1 / 0)])
+print([(r.agent, r.ok) for r in flaky.run_sequential("go", resilient=True)])  # [('ok', True), ('bad', False)]
+
+# 工具:带 provenance 的结果
+print(EchoTool().run("hi").tool)                # 'echo'
+
+# 工具缝注册表:按 spec 选工具(大小写/留白不敏感),第三方还能经 entry-point 自动发现
+from spineagent import tool_registry
+print(tool_registry.make("calc").run("6/2").output)   # '3'
+print("calc" in tool_registry.names())                # True
+
+# 会用工具的多步 agent:离线确定性 policy 按 `<tool>: <arg>` 语法路由,$prev 把上一步输出喂回
+from spineagent import ToolUsingAgent, SyntaxToolPolicy, CalcTool
+solver = ToolUsingAgent("solver", SyntaxToolPolicy(), [CalcTool()])
+print(solver.step("calc: 2 + 3\ncalc: $prev * 2").output)   # '10'(2+3=5,再 *2=10)
+
+# 分层督导式多 agent:把子 agent 用 AgentTool 暴露成工具,督导 agent 通过工具调用派活给它
+from spineagent import AgentTool
+calculator = ToolUsingAgent("calculator", SyntaxToolPolicy(), [CalcTool()])
+supervisor = ToolUsingAgent("supervisor", SyntaxToolPolicy(), [AgentTool(calculator)])
+print(supervisor.step("calculator: calc: 2+3").output)      # '5'(督导派给子 agent,子 agent 再用工具)
+
+# MCP 离线回环:注册 + 调用,零网络
+stub = OfflineMcpStub()
+stub.register_tool(McpTool("upper"), lambda a: {"result": a["s"].upper()})
+print(stub.call_tool("upper", {"s": "hi"}))     # {'result': 'HI'}
+
+# 跨缝组合:把上面那个 MCP 工具桥成 Tool,交给会用工具的 agent 在循环里驱动(零网络)
+from spineagent import McpClientTool
+shouter = ToolUsingAgent("shouter", SyntaxToolPolicy(), [McpClientTool("upper", stub, arg_key="s")])
+print(shouter.step("upper: hi").output)         # 'HI'
+
+# 隐私 trace:步级只记元数据;塞正文会被 corespine 的 sink 直接拒绝
+sink = InProcessPrivacyTraceSink()
+agent.step("敏感任务", trace=sink)               # 只记 agent 名 / 长度 / token 数
+```
+
+## 换上真实模型(可选 extra)
+
+**对外统一 OpenAI chat-completions 形状**(LiteLLM 模式):无论后端是谁,`chat(messages, tools)`
+都回 OpenAI 形状的 `ChatCompletion`(`choices[0].message.content/.tool_calls`、`finish_reason`、
+`usage.prompt_tokens`…)。`LlmAgent` 全程只认 corespine 的 `LLMProvider` 协议,把 `MockProvider`
+换成真实适配器即可,其余代码(agent / 编排 / 工具循环)一行不改:
+
+```bash
+pip install "spineagent[openai]"      # OpenAI 及一切「OpenAI 兼容」端点
+pip install "spineagent[anthropic]"   # 或 [cohere] / [gemini] / [bedrock]
+```
+
+```python
+from spineagent import OpenAICompatProvider, AnthropicProvider, GeminiProvider, LlmAgent
+
+# 一个适配器吃下所有 OpenAI 兼容端点:OpenAI / Azure / Together / Groq / DeepSeek / Mistral /
+# xAI / 通义 Qwen / Moonshot / Ollama / vLLM / OpenRouter / LiteLLM …(换 base_url + model 即可)
+gpt = LlmAgent("gpt", OpenAICompatProvider("gpt-4o"))
+local = LlmAgent("local", OpenAICompatProvider("llama3", base_url="http://localhost:11434/v1"))
+
+# 非 OpenAI 原生模型:原生适配器在内部转成 OpenAI 形状,用户无感
+claude = LlmAgent("claude", AnthropicProvider())                 # 默认 claude-opus-4-8
+gemini = LlmAgent("gemini", GeminiProvider(model="gemini-2.5-flash"))
+```
+
+> 覆盖:**OpenAI 兼容生态(约 85% 主流市场)走 `OpenAICompatProvider` 一把梭**;真正非 OpenAI 形状的
+> Anthropic / Cohere / Gemini / Bedrock 各有原生适配器,把 native 响应转成 OpenAI `ChatCompletion`
+> (绝不把它们套进 OpenAI 形状 = 不 shim)。默认离线路径仍是 `MockProvider`,`import spineagent`
+> 永远零网络 SDK(真实 SDK 仅在选用对应 extra 时延迟 import)。reasoning / citations 等扩展本期丢弃。

spineagent-0.0.1/README.md

@@ -0,0 +1,138 @@
+# spineagent
+
+Spine 家族的**通用多 agent 协作框架**(见 [ADR 0001](../docs/adr/0001-spine-family-boundaries-and-dependency-direction.md))。
+agent / tool / 编排 + **MCP / A2A** 等 agent 协议缝。依赖薄核 `corespine`,复用其缝元模式与
+observability / config 形状;**默认路径离线可跑、import-clean、零网络 SDK**。
+
+> 通用 ≠ 地基。真正的核是更薄的 `corespine`,spineagent 是它的兄弟消费者,**不**含任何 RAG 概念。
+> 详见 [`CLAUDE.md`](CLAUDE.md) 宪章。
+
+## 缝的元模式(家族统一)
+
+每条缝都长一个样,核心 import 零 SDK、离线可跑:
+
+**Protocol + 离线确定性默认 + `Registry` 工厂 + 参数化 conformance**
+
+## 里面有什么
+
+| 模块 | 原语 |
+|---|---|
+| `agent/agent.py` | `Agent` 协议 + `LlmAgent`(走 corespine `LLMProvider`,离线用 `MockProvider`)/ `FunctionAgent`(纯函数节点);步级 trace 只记元数据 |
+| `llm/provider.py` 等 | 真实 LLM provider 适配器(挂在 corespine `LLMProvider` 缝后面;**对外统一 OpenAI chat-completions 形状**):`OpenAICompatProvider`(`openai` SDK + `base_url`,一个吃下 OpenAI/Azure/Together/Groq/DeepSeek/Mistral/xAI/Qwen/Moonshot/Ollama/vLLM/OpenRouter/LiteLLM… 全部 OpenAI 兼容端点)+ 非 OpenAI 原生适配器把 native 转成 OpenAI 形状:`AnthropicProvider`(默认 `claude-opus-4-8`)/ `CohereProvider` / `GeminiProvider` / `BedrockConverseProvider`。`llm_providers` Registry(mock/openai/anthropic/cohere/gemini/bedrock)。各走可选 extra 延迟 import,离线默认仍是 `MockProvider`,各用原生 SDK 不 shim |
+| `agent/policy.py` | `ToolPolicy` 协议 + 离线确定性默认 `SyntaxToolPolicy`(按 `<tool>: <arg>` 语法 + 工具名集合确定性路由,**不假装 LLM 推理**)+ `tool_policies` Registry(`llm` 位留真实推理式接入) |
+| `agent/tool_using.py` | `ToolUsingAgent`:**离线确定性**多步循环(`SyntaxToolPolicy` 按 `<tool>: <arg>` 语法路由),带 `max_steps` 守卫;实现 `Agent` 协议 |
+| `agent/function_calling.py` | `FunctionCallingAgent`:**真 LLM function-calling** 多步循环——把 `FunctionTool` schema 喂给 `chat(tools=)`,模型回 tool_calls → 执行 → 以 OpenAI tool 角色喂回 → 再 chat,直到出文本或触顶;底层换任意 provider 不改一行。实现 `Agent` 协议 |
+| `tools/function_tool.py` | `FunctionTool`(带 JSON-schema、接 dict 参数的结构化工具)+ `@function_tool` 装饰器(从签名/注解/docstring 自动推 schema) |
+| `agent/as_tool.py` | `AgentTool`:把一个 `Agent` 桥成 `Tool`,让督导 agent 通过工具调用把子任务派给专精子 agent(**分层 / 督导式多 agent**,可层层嵌套) |
+| `tools/tool.py` | `Tool` 协议 + `EchoTool` / `CalcTool`(安全算术求值);结果带 provenance。`tool_registry`:spec 选工具 + **entry-point 第三方工具自动发现**(group `corespine.tool`)。**运行时可把 ragspine RAG 插为一个 Tool**(见下) |
+| `orchestration/coordinator.py` | `Coordinator`:把多个 agent **顺序 / 并行 / 流水线**(output→input 链式)跑、保序收集 `AgentResult`;**弹性容错**(`resilient=True`)把单 agent 异常归一为家族错误 dict 塞进 `AgentResult.error`、一个坏 agent 不炸整批 |
+| `orchestration/chain.py` | `ChainAgent`:把一串 agent 串成**单个 `Agent`**(流水线即一等可组合单元),可再进 `Coordinator` / 被 `AgentTool` 当工具 / 套 chain |
+| `protocol/mcp/seam.py` | `McpClient` / `McpServer` 协议 + `OfflineMcpStub`(进程内回环)+ **`McpClientTool`(把 MCP 工具桥成 `Tool`)** + 真实 SDK 经 `[mcp]` extra 延迟 import |
+| `protocol/a2a/seam.py` | `A2AAgent` 协议 + `OfflineA2AStub`(进程内回环)+ **`A2AAgentAdapter`(把 A2A agent 桥成 `Agent`)** + 真实 `a2a-sdk` 经 `[a2a]` extra 延迟 import |
+| `conformance.py` | 本包绑定的不变量:`AGENT_INVARIANTS`(步产出 / provenance / 隐私 trace)、`TOOL_INVARIANTS`(结果 provenance)、`POLICY_INVARIANTS`(决策形状 / 不幻觉工具 / 可终止 / 纯函数) |
+
+## 运行时组合 ragspine(ADR 0001 D4b)
+
+spineagent **不**在包层面依赖 ragspine。但可在**运行时**把 ragspine 的 RAG 检索包成一个实现了
+`Tool`(或 MCP server)协议的适配器,插给某个 agent 调用——松耦合、可选,方向只能 spineagent→ragspine。
+本包 `dependencies` 永远不含 ragspine,也绝不在默认路径 import 它。
+
+第三方工具(含 ragspine RAG)还可经 entry-point 在 `corespine.tool` group 下注册工具工厂,即被
+`tool_registry.make / names` 自动发现、零改本包代码组合进 agent;而它们仍须过 `TOOL_INVARIANTS`
+conformance 才算数——「敢放手让第三方填广度,却让脊柱不变量烂不掉」。
+
+## 本地开发(始终从包根)
+
+```bash
+uv venv .venv
+VIRTUAL_ENV="$(pwd)/.venv" uv pip install -e ../corespine
+VIRTUAL_ENV="$(pwd)/.venv" uv pip install -e ".[dev]"
+.venv/bin/python -m pytest -q
+.venv/bin/python -c "import spineagent"
+```
+
+## 30 秒上手
+
+```python
+from corespine import MockProvider, InProcessPrivacyTraceSink
+from spineagent import LlmAgent, FunctionAgent, Coordinator, EchoTool, OfflineMcpStub
+from spineagent.protocol.mcp.seam import McpTool
+
+# 一个离线 agent:走 corespine 的确定性 MockProvider,跑单步
+agent = LlmAgent("planner", MockProvider())
+print(agent.step("列个计划").output)            # 确定性、可复现
+
+# 多 agent 编排:顺序 / 并行跑同一任务,保序收集
+coord = Coordinator([FunctionAgent("a", lambda t: f"a:{t}"),
+                     FunctionAgent("b", lambda t: f"b:{t}")])
+print([r.output for r in coord.run_parallel("go")])   # ['a:go', 'b:go']
+print([r.output for r in coord.run_pipeline("go")])   # ['a:go', 'b:a:go'](链式:上一个输出喂下一个)
+
+# 弹性容错:坏 agent 不炸整批,异常归一为结构化 error,批次照常跑完
+flaky = Coordinator([FunctionAgent("ok", lambda t: t),
+                     FunctionAgent("bad", lambda t: 1 / 0)])
+print([(r.agent, r.ok) for r in flaky.run_sequential("go", resilient=True)])  # [('ok', True), ('bad', False)]
+
+# 工具:带 provenance 的结果
+print(EchoTool().run("hi").tool)                # 'echo'
+
+# 工具缝注册表:按 spec 选工具(大小写/留白不敏感),第三方还能经 entry-point 自动发现
+from spineagent import tool_registry
+print(tool_registry.make("calc").run("6/2").output)   # '3'
+print("calc" in tool_registry.names())                # True
+
+# 会用工具的多步 agent:离线确定性 policy 按 `<tool>: <arg>` 语法路由,$prev 把上一步输出喂回
+from spineagent import ToolUsingAgent, SyntaxToolPolicy, CalcTool
+solver = ToolUsingAgent("solver", SyntaxToolPolicy(), [CalcTool()])
+print(solver.step("calc: 2 + 3\ncalc: $prev * 2").output)   # '10'(2+3=5,再 *2=10)
+
+# 分层督导式多 agent:把子 agent 用 AgentTool 暴露成工具,督导 agent 通过工具调用派活给它
+from spineagent import AgentTool
+calculator = ToolUsingAgent("calculator", SyntaxToolPolicy(), [CalcTool()])
+supervisor = ToolUsingAgent("supervisor", SyntaxToolPolicy(), [AgentTool(calculator)])
+print(supervisor.step("calculator: calc: 2+3").output)      # '5'(督导派给子 agent,子 agent 再用工具)
+
+# MCP 离线回环:注册 + 调用,零网络
+stub = OfflineMcpStub()
+stub.register_tool(McpTool("upper"), lambda a: {"result": a["s"].upper()})
+print(stub.call_tool("upper", {"s": "hi"}))     # {'result': 'HI'}
+
+# 跨缝组合:把上面那个 MCP 工具桥成 Tool,交给会用工具的 agent 在循环里驱动(零网络)
+from spineagent import McpClientTool
+shouter = ToolUsingAgent("shouter", SyntaxToolPolicy(), [McpClientTool("upper", stub, arg_key="s")])
+print(shouter.step("upper: hi").output)         # 'HI'
+
+# 隐私 trace:步级只记元数据;塞正文会被 corespine 的 sink 直接拒绝
+sink = InProcessPrivacyTraceSink()
+agent.step("敏感任务", trace=sink)               # 只记 agent 名 / 长度 / token 数
+```
+
+## 换上真实模型(可选 extra)
+
+**对外统一 OpenAI chat-completions 形状**(LiteLLM 模式):无论后端是谁,`chat(messages, tools)`
+都回 OpenAI 形状的 `ChatCompletion`(`choices[0].message.content/.tool_calls`、`finish_reason`、
+`usage.prompt_tokens`…)。`LlmAgent` 全程只认 corespine 的 `LLMProvider` 协议,把 `MockProvider`
+换成真实适配器即可,其余代码(agent / 编排 / 工具循环)一行不改:
+
+```bash
+pip install "spineagent[openai]"      # OpenAI 及一切「OpenAI 兼容」端点
+pip install "spineagent[anthropic]"   # 或 [cohere] / [gemini] / [bedrock]
+```
+
+```python
+from spineagent import OpenAICompatProvider, AnthropicProvider, GeminiProvider, LlmAgent
+
+# 一个适配器吃下所有 OpenAI 兼容端点:OpenAI / Azure / Together / Groq / DeepSeek / Mistral /
+# xAI / 通义 Qwen / Moonshot / Ollama / vLLM / OpenRouter / LiteLLM …(换 base_url + model 即可)
+gpt = LlmAgent("gpt", OpenAICompatProvider("gpt-4o"))
+local = LlmAgent("local", OpenAICompatProvider("llama3", base_url="http://localhost:11434/v1"))
+
+# 非 OpenAI 原生模型:原生适配器在内部转成 OpenAI 形状,用户无感
+claude = LlmAgent("claude", AnthropicProvider())                 # 默认 claude-opus-4-8
+gemini = LlmAgent("gemini", GeminiProvider(model="gemini-2.5-flash"))
+```
+
+> 覆盖:**OpenAI 兼容生态(约 85% 主流市场)走 `OpenAICompatProvider` 一把梭**;真正非 OpenAI 形状的
+> Anthropic / Cohere / Gemini / Bedrock 各有原生适配器,把 native 响应转成 OpenAI `ChatCompletion`
+> (绝不把它们套进 OpenAI 形状 = 不 shim)。默认离线路径仍是 `MockProvider`,`import spineagent`
+> 永远零网络 SDK(真实 SDK 仅在选用对应 extra 时延迟 import)。reasoning / citations 等扩展本期丢弃。

spineagent-0.0.1/deploy/.dockerignore

@@ -0,0 +1,23 @@
+# 忽略规则 —— 注意 build context 是【家族根】 ~/workspace/spine,故下列路径相对家族根。
+#
+# BuildKit 的忽略文件解析顺序:先找 `<-f 指向的 Dockerfile>.dockerignore`,再找 context 根的
+# `.dockerignore`。用本文件名 `deploy/.dockerignore` 时,需让它对构建生效(二选一):
+#   1) 把它放/链到 context 根:  ln -sf spineagent/deploy/.dockerignore ~/workspace/spine/.dockerignore
+#   2) 或改名让 BuildKit 自动识别: spineagent/deploy/Dockerfile.dockerignore
+# 即便不忽略也能正确构建(镜像内是一次干净的 uv 安装,下列产物只是死重 / 拖慢上下文)。
+
+# 各包本地虚拟环境 / 缓存 / 构建产物(镜像内会重新安装,无需带入)。
+**/.venv/
+**/.git/
+**/__pycache__/
+**/*.pyc
+**/.pytest_cache/
+**/.ruff_cache/
+**/.mypy_cache/
+**/*.egg-info/
+**/build/
+**/dist/
+
+# 家族根的文档与说明,运行镜像用不到。
+docs/
+README.md

spineagent-0.0.1/deploy/Dockerfile

@@ -0,0 +1,30 @@
+# syntax=docker/dockerfile:1
+#
+# spineagent 容器镜像 —— 构建需要【两个】兄弟包:被依赖的薄核 corespine + spineagent 自身。
+# 因此 build context 必须是【家族根】 ~/workspace/spine(而非 spineagent 包根),这样才能
+# 同时把 corespine 与 spineagent COPY 进来,先装薄核、再装 spineagent。
+#
+# 构建(context = 家族根,-f 指向本文件):
+#   docker build -f spineagent/deploy/Dockerfile -t spineagent:latest ~/workspace/spine
+#
+# 运行(默认 CMD 跑离线 demo,零网络;退出码即健康信号):
+#   docker run --rm spineagent:latest
+#
+# 忽略规则见同目录 .dockerignore(详见 deploy/README.md 的 .dockerignore 说明)。
+
+# uv 官方镜像:自带 Python 3.11 + uv,贴合家族「uv 管环境」的约定。
+FROM ghcr.io/astral-sh/uv:python3.11-bookworm-slim
+
+WORKDIR /app
+
+# 先放被依赖的薄核 corespine,再放 spineagent(顺序与下面的安装顺序一致)。
+COPY corespine/ /app/corespine/
+COPY spineagent/ /app/spineagent/
+
+# 先装 corespine —— 这样装 spineagent 时它的 `corespine` 依赖已被满足(离线、无需 PyPI);
+# 再装 spineagent[dev]。--system 直接装进容器系统 Python,容器内无需再建 venv。
+RUN uv pip install --system -e /app/corespine \
+ && uv pip install --system -e "/app/spineagent[dev]"
+
+# 默认跑 spineagent 的一键离线 demo(零网络),成功打印 "spineagent OK"。
+CMD ["python", "/app/spineagent/examples/quickstart.py"]

spineagent-0.0.1/deploy/README.md

@@ -0,0 +1,43 @@
+# 部署 —— spineagent 容器镜像
+
+镜像构建需要【两个】兄弟包:被依赖的薄核 `corespine` + `spineagent` 自身。所以镜像的
+**build context 是家族根** `~/workspace/spine`(里面并排放着 `corespine/` 与 `spineagent/`),
+而 `-f` 指向本目录的 `Dockerfile`。镜像内先装 `corespine`、再装 `spineagent`,默认 `CMD`
+跑 spineagent 的一键离线 demo(零网络)。
+
+## 构建
+
+```bash
+# context = 家族根;-f 指向 spineagent 包内的 Dockerfile
+docker build -f spineagent/deploy/Dockerfile -t spineagent:latest ~/workspace/spine
+```
+
+## 运行
+
+```bash
+docker run --rm spineagent:latest   # 跑离线 demo,成功打印 "spineagent OK"
+```
+
+## 为什么 context 是家族根而不是包根
+
+`spineagent` 在 `dependencies` 里写着 `corespine`,但 `corespine` 还没发到 PyPI(本地是 uv
+path source 指向 `../corespine`)。Docker 的 `COPY` 只能取 **build context 内**的文件,而包根
+`spineagent/` 里看不到兄弟目录 `corespine/`。把 context 抬到家族根,镜像才能同时 `COPY` 进两个
+包,并按 `corespine → spineagent` 的顺序可编辑安装 —— 与本地 `make install` 完全一致。
+
+## 关于 `.dockerignore`
+
+忽略规则在 `deploy/.dockerignore`,其路径相对 **context 根(家族根)**。BuildKit 解析忽略文件的
+顺序是:先找 `<-f 指向的 Dockerfile>.dockerignore`,再找 context 根的 `.dockerignore` —— 因此
+放在 `deploy/` 下的这份默认不会被自动应用。要让它生效,二选一:
+
+```bash
+# 1) 链到 context 根(推荐,保持单一来源)
+ln -sf spineagent/deploy/.dockerignore ~/workspace/spine/.dockerignore
+
+# 2) 或改名让 BuildKit 按 Dockerfile 旁路自动识别
+cp spineagent/deploy/.dockerignore spineagent/deploy/Dockerfile.dockerignore
+```
+
+即便不应用忽略文件,构建结果依然正确:镜像内做的是一次干净的 `uv pip install`,COPY 进来的
+`.venv/`、缓存、构建产物都不会被使用,只是徒增上下文体积、拖慢构建。