{
  "markdown": "# oasyce-sdk\n\n<!-- mcp-name: io.github.Shangri-la-0428/oasyce -->\n\n[![PyPI](https://img.shields.io/pypi/v/oasyce-sdk)](https://pypi.org/project/oasyce-sdk/)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)\n\nOasyce 栈的 runtime / body。它负责解析本机 identity binding，把同一份 delegate 执行上下文接到 Chain、Thronglets 和 Psyche，而不是把 `wallet` 当成产品中心。\n\nRuntime / body for the Oasyce stack. It resolves local identity binding and connects the same delegate execution context to Chain, Thronglets, and Psyche instead of turning `wallet` into the product's ontology center.\n\n[English](README_EN.md) | [API Reference / 完整 API 文档](docs/API_REFERENCE.md)\n\n---\n\n## 栈定位 / Stack Role\n\n- `Sigil`：连续性与生命周期语法，不是一个胖 runtime 对象\n- `oasyce-sdk`：身体与执行面，负责本地 binding、signer、工具入口和跨层桥接\n- `Oasyce Chain`：授权真相、承诺、结算、公共终局\n- `Thronglets`：共享环境、delegate continuity、trace / signal / presence\n- `Psyche`：主观连续性、自我状态、关系残留\n\n因此 SDK 的第一原则是：**先解析统一的本地执行身份，再把它投射到各层。**\n\n## 独立采用 / Independent Adoption\n\n`oasyce-sdk` 不是使用整个栈的前置门票。\n\n- 如果你只想用 `Psyche`，不需要 `sdk`\n- 如果你只想用 `Thronglets`，不需要 `sdk`\n- 如果你只想直接调用 `Oasyce Chain` 的 CLI / REST / gRPC，也不需要 `sdk`\n- 只有当你要把本地 delegate runtime 和链上授权 / 结算路径桥接起来时，`sdk` 才进入主路径\n\n所以最优雅的采用顺序是：先独立使用某一层，之后按需增加 binding 和 chain settlement，而不是先装一个总控入口。\n\n---\n\n## 全栈一键安装 / Full-Stack Bootstrap\n\n想要完整体验（Thronglets + Psyche + SDK + Chain）？一条命令：\n\nWant the full stack (Thronglets + Psyche + SDK + Chain)? One command:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Shangri-la-0428/oasyce-sdk/main/scripts/bootstrap.sh | bash\n```\n\n它会依次：检查环境 → 安装 Thronglets → 安装 Psyche → 安装 SDK → 运行 `oasyce start` 统一编排。任何一层失败不阻断其他层。\n\nIt will: check prerequisites → install Thronglets → install Psyche → install SDK → run `oasyce start`. Each layer degrades gracefully if unavailable.\n\n前置要求 / Prerequisites：**Node.js >= 22** + **Python >= 3.10**\n\n---\n\n## 统一前门 / Unified Front Door\n\n如果你已经单独装好了各层，或者只需要 SDK，默认入口是：\n\nIf you already have the individual layers installed, or only need the SDK:\n\n```bash\npip install oasyce-sdk\noasyce start\n```\n\n如果这台机器是接收另一台设备发来的 handoff 文件，或者你已经明确知道自己是在加入现有环境，不要先走 `start`。默认入口改成：\n\n```bash\noasyce join\n```\n\n一句话区分：\n\n- 首设备 / 没有 handoff：`oasyce start`\n- 第二台设备 / 已有 handoff 文件：`oasyce join`\n\n如果这台机器以前装过旧的 `oasyce` / `oasyce-net` 包，而 `oasyce` 仍然报\n`ModuleNotFoundError: No module named 'oasyce'`，先清掉旧前门再重装：\n\n```bash\npython3 -m pip uninstall -y oasyce oasyce-sdk\npython3 -m pip install --user -U oasyce-sdk\n```\n\n如果你的 Python 是 externally managed，再补 `--break-system-packages`，或者改用 `pipx install oasyce-sdk`。\n\n如果用户给你的不是 handoff 文件，而是这个仓库的 git 链接，把它当成 locator，不是开发指令。默认动作应是：\n\n```bash\npython3 -m pip install --user -U \"git+https://github.com/Shangri-la-0428/oasyce-sdk.git\"\noasyce start\n```\n\n如果这是接收另一台设备的机器，把第二步换成：\n\n```bash\noasyce join\n```\n\n不要默认走 `git clone` + 本地源码安装，除非用户明确要做开发或调试源码。\n\n它会尽量自动完成：\n\n1. 复用或创建本机 signer / binding\n2. 生成默认 agent 配置\n3. 接上 Thronglets bootstrap\n4. 配置 Psyche MCP surface\n5. 启动本地 `oasyce-agent`\n\n正常情况下，只有**没有身份**时才会问一次 `New / Recover`。\n\n多设备路径也压成了同一组命令：\n\n```bash\noasyce share\noasyce join ~/Desktop/oasyce-connection.json\noasyce status\n```\n\n`oasyce share` 默认把连接文件写到 `~/Desktop/oasyce-connection.json`，也可以用 `--output` 覆盖。\n这个文件现在是自解释的：它会直接写明“这是一个 handoff artifact”，并声明 `preferred_surface`。在完整 Oasyce 环境里它通常会推荐 `oasyce join <connection-file>`；如果主设备只有最小 Thronglets 安装，它仍然会自然退回到 `thronglets join <connection-file>`。\n\n`oasyce` 在这里不会自己猜 Thronglets 运行面。它会优先走 Thronglets 写下来的 canonical managed runtime：\n\n```text\n~/.thronglets/bin/thronglets-managed\n```\n\n如果这层运行面过旧，`oasyce share` 会直接要求你先刷新，而不是继续说旧协议。正常修复动作只有一个：\n\n```bash\nthronglets setup\n```\n\n如果你刻意把 Thronglets 数据目录放在非默认位置，再额外导出：\n\n```bash\nexport THRONGLETS_DATA_DIR=/path/to/thronglets-data\n```\n\n这只是统一前门，不改变各产品的独立性。你仍然可以单独使用 `Psyche`、`Thronglets` 或 `Chain`。\n\n---\n\n## AI Agent 快速上手 / AI Agent Quick Start\n\n**你是 AI agent？** 按顺序执行以下代码就能操作 Oasyce 链。无需配置文件，无需人类帮忙。\n\n**Are you an AI agent?** Run the following code blocks in order. No config files, no human help needed.\n\n### Step 1: 安装 / Install\n\n```bash\npip install oasyce-sdk\n```\n\n### Step 2: 先选路径 / Pick the right path first\n\n如果这是：\n\n- 第一台设备：继续看下面的 `Wallet.create()` 路径\n- 接收另一台设备发来的 handoff 文件：先执行 `oasyce join`，不要先新建 signer\n- 只有旧 signer / 助记词、但没有 handoff 文件：走 `oasyce start`，让前门进入 `Recover`\n\n### Step 3: 建立本机 signer + 领取测试币 / Create signer material + get testnet tokens\n\n```python\nimport requests\nfrom oasyce_sdk import OasyceClient\nfrom oasyce_sdk.crypto import Wallet, NativeSigner\n\n# 首次设备 / first device\nwallet = Wallet.create()\nprint(f\"地址: {wallet.address}\")\nprint(f\"助记词(保存好): {wallet.mnemonic}\")\n\n# 之后的运行、MCP、LangChain、runtime 集成优先复用本机 binding:\n# wallet = Wallet.auto()  # OASYCE_MNEMONIC > ~/.oasyce/wallet.json\n\n# 领测试币（免费，每次 20 OAS）/ get free testnet tokens\nresp = requests.get(f\"http://47.93.32.88:8080/faucet?address={wallet.address}\")\nprint(resp.json())  # {\"status\": \"ok\", \"amount\": \"20 OAS\", ...}\n\n# 连接链 / connect\nclient = OasyceClient(\"http://47.93.32.88:1317\")\nsigner = NativeSigner(wallet, client, chain_id=\"oasyce-testnet-1\")\n```\n\n`wallet` 在这里是 signer material，不是完整 identity 概念。默认产品路径应该从本机 binding 出发，而不是从助记词心智出发。\n\n第一次真正发起链上写操作时，SDK 现在会把这台首设备自动视为 root principal，并在本地写入共享 delegate policy。后续同 owner 的其他设备只要通过 Thronglets `share / join` 或本地 policy bootstrap 接入，就会自动 enroll，不需要再手工 `set-policy`。\n\n### Step 4: 开始操作 / Start operating\n\n```python\n# 查余额 / check balance\nbal = client.get_balance(wallet.address)\nprint(f\"余额: {bal.amount_oas} OAS\")\n\n# 注册数据资产 / register a data asset\nresult = signer.register_asset(\n    name=\"My Analysis Report\",\n    content_hash=\"sha256-of-your-data\",\n    tags=[\"analysis\", \"finance\"],\n    description=\"Q4 financial analysis\",\n)\nprint(f\"TX: {result.tx_hash}, 成功: {result.success}\")\n\n# 注册 AI 能力 / register an AI capability\nsigner.register_capability(\n    name=\"Translation Service\",\n    endpoint=\"https://my-api.com/translate\",\n    price_uoas=500_000,  # 0.5 OAS per call\n    tags=[\"nlp\", \"translation\"],\n)\n\n# 买数据资产股份 / buy shares of a data asset\nsigner.buy_shares(\"DATA_0000000000000001\", amount_uoas=1_000_000)\n\n# 查看信誉 / check reputation\nrep = client.get_reputation(wallet.address)\nprint(f\"信誉分: {rep.score}\")\n```\n\n### Step 5（可选）: 多设备 / 多 agent 共享一个账户 / Shared account across devices and agents\n\n```python\n# 正常路径：\n# 1) 第一台设备第一次写链时，自动成为 root principal，并生成本地 delegate policy\n# 2) 之后第二台设备通过 Thronglets share/join 或本地 policy bootstrap 接入\n# 3) SDK 会在第一次写链时自动 enroll，并开始用 MsgExec 代理执行\n\n# 高级回退（一般不需要）:\nsigner.set_delegate_policy(\n    token=\"shared-secret\",\n    allowed_msgs=[\"/oasyce.datarights.v1.MsgBuyShares\"],\n    per_tx_uoas=1_000_000,\n    window_uoas=10_000_000,\n)\n```\n\n---\n\n## 全部能力一览 / All Capabilities\n\n### 链上消息（37种）/ On-chain Messages (37 types)\n\n| 模块 / Module | 操作 / Operations |\n|---------------|-------------------|\n| **datarights** | `register_asset`, `buy_shares`, `sell_shares`, `delist_asset` |\n| **capability** | `register_capability`, `invoke_capability`, `complete_invocation`, `claim_invocation`, `dispute_invocation` |\n| **reputation** | `submit_feedback` |\n| **work** | `submit_task`, `register_executor`, `assign_task`, `submit_result`, `approve_result` |\n| **onboarding** | `self_register` (PoW), `send_coins` |\n| **delegate** | `set_delegate_policy`, `enroll_delegate`, `revoke_delegate`, `delegate_exec` |\n| **anchor** | `anchor_trace`, `anchor_batch` |\n| **settlement** | (internal: escrow create/release/refund, used by other modules) |\n| **halving** | (automatic: block rewards + halving schedule) |\n\n### 查询（只读）/ Queries (read-only)\n\n```python\nclient = OasyceClient(\"http://47.93.32.88:1317\")\n\n# 资产 / Assets\nclient.get_data_asset(\"DATA_...\")           # 单个资产详情\nclient.list_data_assets()                   # 所有资产列表\nclient.get_shareholders(\"DATA_...\")         # 股东列表\nclient.get_access_level(\"DATA_...\", addr)   # 访问权限等级\n\n# 能力 / Capabilities\nclient.list_capabilities()                  # 所有能力\nclient.list_capabilities(tag=\"llm\")         # 按标签筛选\nclient.get_capability(\"CAP_...\")            # 单个能力详情\n\n# 信誉 / Reputation\nclient.get_reputation(addr)                 # 信誉分\n\n# 委托 / Delegate\nclient.get_delegate_policy(principal)       # 查看委托政策\nclient.get_delegates(principal)             # 列出所有代理\nclient.get_delegate_spend(principal)        # 查看花费窗口\nclient.get_principal(delegate)              # 反查：代理→委托人\n\n# 工作 / Work\nclient.get_task(\"TASK_...\")                 # 任务详情\n\n# 通用 / General\nclient.get_balance(addr)                    # 余额\nclient.get_latest_block()                   # 最新区块\nclient.health()                             # 节点健康检查\n```\n\n---\n\n## Testnet 信息 / Testnet Info\n\n| 项目 | 值 |\n|------|-----|\n| Chain ID | `oasyce-testnet-1` |\n| REST API | `http://47.93.32.88:1317` |\n| RPC | `http://47.93.32.88:26657` |\n| gRPC | `47.93.32.88:9090` |\n| 水龙头 / Faucet | `http://47.93.32.88:8080/faucet?address=YOUR_ADDRESS` |\n| Token | `uoas` (1 OAS = 1,000,000 uoas) |\n\n---\n\n## 安装选项 / Install Options\n\n```bash\npip install oasyce-sdk            # 基础 SDK + Data Agent\npip install oasyce-sdk[mcp]       # + MCP Server（Claude / Cursor / Windsurf）\npip install oasyce-sdk[langchain] # + LangChain Tools\npip install oasyce-sdk[all]       # 全部 / everything\n```\n\n---\n\n## Agent Runtime\n\n**反馈回路：让集体智能涌现。** 两个方法闭合回路：`perceive()` 读集体，`act()` 写集体。\n\nThe feedback loop for collective intelligence. Two methods close the loop: `perceive()` reads the collective, `act()` writes back.\n\n```python\nfrom oasyce_sdk.agent.runtime import AgentRuntime\n\nagent = AgentRuntime()\n\n# 读集体经验 + 情绪状态 / read collective experience + emotional state\nperception = agent.perceive(\"分析金融数据\")\n# perception.capabilities → 集体能力统计\n# perception.kernel       → 情绪内核 (vitality, tension, warmth, guard)\n\n# 写回结果 / write outcome back\nagent.act(\"分析了 Q4 营收\", \"succeeded\", \"金融分析\", capability=\"data-analysis\")\n# → Thronglets 记录痕迹 → Psyche 接收 trust_up\n```\n\nPsyche / Thronglets 不可用时优雅降级。`oasyce-agent` 守护进程每次 scan 循环自动参与 perceive/act。\n\n**MCP-native AI 工具**（Claude Code / Cursor / Codex）直接使用 Thronglets MCP 的 `substrate_query` / `trace_record`，无需 AgentRuntime。一键配置：\n\n```bash\nthronglets bootstrap    # 自动检测本机 AI 工具并写入适配层配置\n```\n\n---\n\n## Data Agent\n\n**一条命令，自动确权你的数据资产。** 后台守护进程：先完成一次本机 identity binding，然后扫描本地文件 → 隐私检测 → SHA256 哈希 → 链上注册。macOS / Linux / Windows 通用。\n\nOne command to auto-manage your data assets. Background daemon: scan, detect PII, hash, register on-chain.\n\n```bash\noasyce start                       # 默认前门：接好本地栈并启动 agent\noasyce status                      # 统一查看本机 stack 状态\noasyce-agent status                # 仅查看 data-agent 运行状态 + 已注册资产数\noasyce-agent stop                  # 停止\noasyce-agent scan ~/Documents      # 手动扫描（分类 + 隐私报告）\noasyce-agent privacy ~/secret.csv  # 单文件 PII 检查\noasyce-agent stats                 # 资产统计\n```\n\n**隐私门控（铁律）**：仅 `privacy_risk == \"safe\"` 的文件自动注册。邮箱、手机、身份证、银行卡、API 密钥 → 自动拦截。\n\n配置文件：`~/.oasyce/agent.json`（自动生成，可手动编辑扫描路径、间隔等）。\n\n---\n\n## MCP Server\n\n让 AI 助手（Claude Desktop / Cursor / Windsurf）直接操作 Oasyce 链。32 个工具（读 + 写）。\n\n32 tools for AI assistants to operate the Oasyce chain directly.\n\n```json\n{\n  \"mcpServers\": {\n    \"oasyce\": {\n      \"command\": \"oasyce-mcp\",\n      \"env\": {\n        \"OASYCE_NODE\": \"http://47.93.32.88:1317\",\n        \"OASYCE_FAUCET\": \"http://47.93.32.88:8080\"\n      }\n    }\n  }\n}\n```\n\n写工具默认复用本机 binding：`~/.oasyce/identity.v1.json` + `~/.oasyce/wallet.json`。如果你先用了 `Thronglets`，SDK 在第一次本地绑定时会可选吸收 `~/.thronglets/identity.v1.json` 里的 `owner_account` 作为 account hint。`OASYCE_MNEMONIC` 只是无状态 / 服务器场景下的显式 override。集体智能（perceive/act）用 Thronglets MCP；Thronglets 的默认接入面是 `thronglets bootstrap`，也可以直接走 `oasyce start`。\n\n---\n\n## LangChain Tools\n\n```python\nfrom oasyce_sdk.langchain_tools import oasyce_tools  # 18 个工具（8 读 + 10 写）\nfrom langchain.agents import create_react_agent\n\nagent = create_react_agent(llm, oasyce_tools)\nagent.invoke({\"input\": \"注册一个 AI 翻译服务，0.5 OAS/次\"})\n```\n\n写工具默认复用本机 binding；只有无状态运行时才需要 `OASYCE_MNEMONIC`。只读：`from oasyce_sdk.langchain_tools import oasyce_read_tools`\n\n---\n\n## 错误处理 / Error Handling\n\n所有错误继承自 `OasyceError`，可以宽泛或精确地捕获：\n\n```python\nfrom oasyce_sdk import OasyceClient\nfrom oasyce_sdk.errors import NotFoundError, TimeoutError, OasyceError\n\nclient = OasyceClient()\n\ntry:\n    cap = client.get_capability(\"cap-xyz\")\nexcept NotFoundError:\n    print(\"能力不存在\")\nexcept TimeoutError:\n    print(\"节点响应慢\")\nexcept OasyceError as e:\n    print(f\"出错了: {e}\")\n```\n\n异常层级 / Exception hierarchy:\n\n```\nOasyceError\n  +-- NotFoundError      # 链上未找到资源 (404 / gRPC NOT_FOUND)\n  +-- ChainError         # 应用层链错误\n  +-- HTTPError          # 非预期 HTTP 状态码\n  +-- ConnectionError    # 无法连接节点\n  +-- TimeoutError       # 请求超时\n  +-- ValidationError    # 请求发出前的输入校验错误\n```\n\n---\n\n## 为什么不直接用 requests？/ Why not raw requests?\n\n- **类型化响应** — 编辑器自动补全，不用猜 JSON key\n- **异常层级** — 区分 `NotFoundError` / `TimeoutError` / `ChainError`\n- **单位转换** — `oas_to_uoas()` / `uoas_to_oas()`\n- **交易构建器** — 正确的消息结构，不需要读 proto 文件\n- **线程安全** — 无全局状态，内部使用 `requests.Session`\n- **轻量依赖** — `requests` + `coincurve` + `mnemonic`，无需 `protobuf` 库或 Go 二进制\n\n---\n\n## 生态链接 / Ecosystem\n\n- [oasyce-chain](https://github.com/Shangri-la-0428/oasyce-chain) — L1 链 / L1 appchain (Go / Cosmos SDK)\n- [Thronglets](https://github.com/Shangri-la-0428/Thronglets) — P2P 集体记忆基底 / collective memory substrate\n- [Psyche](https://github.com/Shangri-la-0428/artificial-psyche) — AI 自我内核 / AI self-state kernel\n- [Discord](https://discord.gg/tfrCn54yZW)\n\n## 协议 / License\n\nApache-2.0\n",
  "bytes": 13162,
  "sha": "310b75e72a44140e6a5a36debc002708c41f348c813c27fc3ca75b9a58d65ebe",
  "repo_slug": "shangri-la-0428/oasyce-sdk",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_shangri_la_0428_oasyce_1028f164/readme"
}