@agentunion/fastaun 0.5.26 → 0.5.28

package/_packed_docs/cli/AUN-CLI/350/256/276/350/256/241/346/226/207/346/241/243.md

@@ -2,7 +2,7 @@
 
 ## 1. 定位
 
-AUN CLI 是 Python SDK 随包提供的命令行入口，用于在不编写业务代码的情况下完成身份管理、消息收发、群组操作、Storage / Group FS 文件操作、Collab 协作层操作、agent.md 管理、诊断和压测。
+AUN CLI 是 Python SDK 随包提供的命令行入口，用于在不编写业务代码的情况下完成身份管理、消息收发、群组操作、Storage / Group FS 文件操作、Collab 协作层操作、凭证／语义凭证、agent.md 管理、诊断和压测。
 
 当前实现位于：
 
@@ -32,6 +32,7 @@ aun CLI
       ├─ fs.py               # storage VFS POSIX 风格 fs 命令
       ├─ storage.py          # object storage 兼容命令
       ├─ collab.py           # collab 与 collab tag
+      ├─ credential.py       # 凭证／语义凭证签验、管理、包／请求及证据
       ├─ agentmd.py          # agent.md 上传、下载、检查
       ├─ keys.py             # 本地密钥与 seed 迁移
       ├─ diag.py             # status/ping/doctor/logs
@@ -97,13 +98,13 @@ output = "table"
 color = true
 timeout = 30
 
-[profiles.default]
-aid = "alice.agentid.pub"
-aun_path = "~/.aun/profiles/default"
-active_group = "10042.agentid.pub"
-```
-
-`active_group` 保存当前群的目标态 `group_aid`。旧格式 `group.{issuer}/{base}` 可作为兼容输入解析，但新配置应写 `{base}.{issuer}`。
+[profiles.default]
+aid = "alice.agentid.pub"
+aun_path = "~/.aun/profiles/default"
+active_group = "10042.agentid.pub"
+```
+
+`active_group` 保存当前群的目标态 `group_aid`。旧格式 `group.{issuer}/{base}` 可作为兼容输入解析，但新配置应写 `{base}.{issuer}`。
 
 有效 profile 解析顺序：
 
@@ -141,6 +142,8 @@ active_group = "10042.agentid.pub"
 | `storage` | `commands.storage` | 对象存储兼容命令 |
 | `fs` | `commands.fs` | Storage VFS / POSIX 风格命令 |
 | `collab` | `commands.collab` | 版本化协作层 |
+| `credential` | `commands.credential` | 平铺23个命令，调用统一SDK credential facade |
+| `org` | `commands.org` | 组织生命周期、成员及受保护凭证查询，复用SDK编排 |
 | `agentmd` | `commands.agentmd` | agent.md 管理 |
 | `keys` | `commands.keys` | 本地密钥与 seed 管理 |
 | `bench` | `commands.bench` | 消息发送压测 |
@@ -242,6 +245,14 @@ active_group = "10042.agentid.pub"
 
 当前没有 `keys export/import`、`group listen`、`config init`、`profile delete` 这些命令；需要新增时应先更新实现和本文档。
 
+### 7.9 凭证与语义凭证
+
+`commands/credential.py`将普通CAP创建／完整Verify／本地current／撤销列表、六语义管理入口、usage协调、签验、构包／请求、决策输入及消息证据映射至`client.credential`。23个命令和参数见[CLI手册](CLI手册.md#凭证与语义凭证)，流程图与TS示例见[CLI专题](凭证与组织服务CLI开发与使用指南.md)，wire契约见[RPC手册](../sdk/09-凭证服务RPC手册.md)。
+
+`--params`／`--context`严格解析JSON或UTF-8文件；签名从真实profile加载本地私钥，管理调用使用认证会话。`verify --kind structured`经认证会话逐层解析可信历史证书与强状态proof，以实际请求context调用普通完整Verify；JSON仅提供请求字段、proof_chain及credential_services，成员／Ownership／计数端口由应用集成。语义完整证书／可信根支持受策略约束的离线验真；online查询由当前CLI进程生成单调时间和独立查询绑定。输出保留结构化错误，`--output`拒绝覆盖，SignedJsonBytes按解码后的原字节保存；管理请求与业务请求分别固定幂等材料。
+
+组级`credential --target`仅向语义管理方法传递权威服务AID。`commands/org.py`复用SDK的请求准备与实体编排，提供health／status、受保护凭证撤销列表，以及`--application`／`--invitation`原材料衔接；转让使用SDK持久换钥与finalize流程。
+
 ## 8. 错误处理与退出码
 
 错误映射在 `adapter.handle_error()` 中：
@@ -257,7 +268,7 @@ active_group = "10042.agentid.pub"
 | 6 | 权限不足 |
 | 7 | 目标不存在 |
 
-JSON 模式下错误仍通过统一错误输出函数输出，便于脚本判断。
+JSON 模式下错误仍通过统一错误输出函数输出，便于脚本判断。credential命令另按`SEMANTIC_*`稳定码映射参数／绑定为2、签名／身份为3、权限为6、不存在为7、其他语义错误为1，并保留原RPC code、data和retryable，不解析message。
 
 ## 9. 当前实现边界
 

package/_packed_docs/cli/CLI/346/211/213/345/206/214.md

@@ -77,7 +77,7 @@ aun config list
 |------|------|
 | `aid` | 默认操作身份 |
 | `aun_path` | 本地身份、密钥、日志等数据目录 |
-| `active_group` | 默认群组；值使用目标态 `group_aid`，省略 `group_id` 兼容参数时使用 |
+| `active_group` | 默认群组；值使用目标态 `group_aid`，省略 `group_id` 兼容参数时使用 |
 | `debug` / `trace` / `timeout` | 调试、trace 和超时配置 |
 
 有效 profile 选择顺序：
@@ -113,7 +113,7 @@ aun identity check alice.agentid.pub
 | `aun send <target-aid> -` | 从 stdin 读取消息 |
 | `aun pull [--from aid] [--limit N] [--after-seq N]` | 拉取离线消息 |
 | `aun ack <sender-aid> --seq N` | 确认消息 seq |
-| `aun listen [--from aid] [--group group_id]` | 实时监听 P2P 和群消息；`group_id` 是兼容参数名，值使用 `group_aid` |
+| `aun listen [--from aid] [--group group_id]` | 实时监听 P2P 和群消息；`group_id` 是兼容参数名，值使用 `group_aid` |
 
 示例：
 
@@ -282,12 +282,12 @@ aun agentmd check bob.agentid.pub --max-unsynced-days 1
 密钥：
 
 ```powershell
-aun keys list
-aun keys rotate --type spk
-aun keys change-seed --old-seed "current-seed" --new-seed "new-seed"
-```
-
-SDK 正常启动和密钥读取只使用显式传入的 seed，不会自动读取 `.seed` 或回退到 `.seed.migrated.*`。显式执行 `change-seed` 时，`--old-seed` 可以直接提供当前 seed_password；传入 `.seed` 则明确要求迁移 `{aun_path}/.seed`，仅在迁移成功后归档旧文件。
+aun keys list
+aun keys rotate --type spk
+aun keys change-seed --old-seed "current-seed" --new-seed "new-seed"
+```
+
+SDK 正常启动和密钥读取只使用显式传入的 seed，不会自动读取 `.seed` 或回退到 `.seed.migrated.*`。显式执行 `change-seed` 时，`--old-seed` 可以直接提供当前 seed_password；传入 `.seed` 则明确要求迁移 `{aun_path}/.seed`，仅在迁移成功后归档旧文件。
 
 诊断：
 
@@ -302,13 +302,58 @@ aun logs --follow
 压测：
 
 ```powershell
-aun bench send bob.agentid.pub --count 100 --concurrency 4
-aun bench group-send 10042.agentid.pub --count 100 --concurrency 4
-aun bench group send --count 100
-```
+aun bench send bob.agentid.pub --count 100 --concurrency 4
+aun bench group-send 10042.agentid.pub --count 100 --concurrency 4
+aun bench group send --count 100
+```
 
 `aun bench group_send` 是 `aun bench group-send` 的公开兼容别名。
 
+## 凭证与语义凭证
+
+当前工作区 `aun credential` 平铺以下 23 个命令。流程图与 TS 调用示例见[凭证与组织服务 CLI 专题](凭证与组织服务CLI开发与使用指南.md)，字段见 [RPC 手册](../sdk/09-凭证服务RPC手册.md)、[SDK 集成指南 §3 结构化凭证](../sdk/凭证与组织服务SDK应用集成指南.md#3-结构化凭证接入)和 [§4 语义凭证](../sdk/凭证与组织服务SDK应用集成指南.md#4-语义凭证接入)。语义扩展是否已发布须核对使用的实际 SDK／服务版本。
+
+| 命令 | 对应能力 |
+| --- | --- |
+| create、current | 普通 CAP 创建；读取当前 profile 本地管理记录及续期 successor |
+| sign、metadata-sign、allocation-sign | 签署语义原件、确认元数据、额度分配 |
+| usage-record-sign | 按指定域签署配套记录 |
+| register、revise、get、status、revoke、revocations | 六个语义管理方法；register／status／revoke 也按 SDK 字段分流兼容普通凭证 |
+| revocation-list | 普通撤销列表；语义输入按 SDK 字段分流 |
+| usage-prepare、usage-commit、usage-abort | revise 的 usage 三分支，返回 transition |
+| verify | structured 完整 Verify；其他 kind 的语义单项／凭证包验真 |
+| package、request、request-verify、decision-input | 构包、构建固定业务请求、请求验真及决策输入 |
+| evidence-export、evidence-verify | 创建 EvidenceRef、验证消息正文依据；后者对应 verify_message_body |
+
+`--params` 接收严格 JSON 对象或 `@UTF-8文件`，可放在 credential 组或具体命令后。通用命令支持 `--context JSON/@文件`；上下文必须符合所调用方法的参数形状，不是任意附加参数。签名命令从当前 profile 加载真实身份及私钥；管理方法经已认证会话调用。
+
+以下示例假定 cn profile 和输入材料已准备好，不创建身份或启动环境：
+
+```powershell
+aun --profile cn --json credential --help
+aun --profile cn --json credential register --params @register.json
+aun --profile cn --json credential verify --kind package --params @package.json --context @verify-context.json
+aun --profile cn --json credential usage-record-sign --kind usage-checkpoint --params @checkpoint.json
+```
+
+verify 的 `--kind` 为 structured／original／metadata／receipt／status／package／allocation／allocation-status／usage-record；structured 经认证会话逐层取得可信历史证书和强状态 proof，再调用 SDK 完整 Verify。`--context` 提供实际请求的 audience／subject／root_issuer／ns／action／resource／method／target／params／request_id／nonce／request_binding，可附 proof_chain 和 credential_services；时间、resolve_* 与 check_rate_limit 由可信运行环境提供，成员／Ownership／计数端口由应用集成。只有 usage-record 另需 `--domain`。usage-record-sign 使用 `--kind` 指定签名域，允许 usage-allocation、allocation-status、semantic-crl、usage-transition、usage-checkpoint、usage-acceptance、ledger-abort。
+
+`--output/-o` 只写新文件，拒绝覆盖。返回 SignedJsonBytes 时输出文件保存解码后的原 JSON 字节，终端 JSON 仍返回 bytes_base64 包装；其他结果保存 canonical JSON。再次提交签名原件须按 RPC 契约包装。语义管理默认使用 profile 身份域，可在具体命令前传 `credential --target credential.aid.com` 选择权威；普通 RPC 继续按其原绑定契约调用。
+
+request 的输入不含 params_hash／request_binding。request-verify／decision-input 选择 online 时，CLI 以当前进程单调时钟生成查询上下文，并按可信 authority、audience、credential_services 刷新状态；不能从文件传入 query_started_monotonic／deadline_monotonic。有 certificates 与 trusted_roots 的完整离线验真上下文可避免网络查询，仍须满足 bounded 等所选策略，不代表业务授权已通过。
+
+管理输入省略 request_binding，由 facade 自动补齐；普通 `aun-cap/1` 兼容路径仍按旧契约提供绑定。固定保存 request_id、nonce、原件和协调材料，重试沿原幂等操作，状态冲突先读取当前 head／transition。使用相同配置与持久状态从首败续跑，真实四 SDK／CLI 编排见[示例指南](../../examples/semantic-credential/示例使用指南.md)。
+
+语义错误的结构化 JSON 保留 RPC code、data.error_code 和 retryable。FORMAT_INVALID／BINDING_INVALID 退出 2，SIGNATURE_INVALID／IDENTITY_INVALID 退出 3，PERMISSION_DENIED 退出 6，NOT_FOUND 退出 7，其他语义业务错误退出 1；STATE_UNAVAILABLE 的可重试标识仍在 data 中。
+
+## 组织服务
+
+`aun org` 覆盖 health／status、生命周期、申请／审批、邀请、成员状态及离职收尾、成员凭证状态／续期／撤销列表和审计。完整命令地图、流程图与 TS 示例见[CLI 专题 §8—§10](凭证与组织服务CLI开发与使用指南.md#8-组织命令地图与创建)。
+
+`org --params JSON/@文件` 放在具体子命令前，传当前 credentials 或完整已准备请求。`join-approve --application` 接收原申请的 application 对象；`invite-accept`／`invite-reject --invitation` 接收本目标的单个原邀请条目。受保护读取包含 `members`、`member`、`credential info` 和 `credential revocation-list`，复用 SDK 请求准备与当前 binding／CAP。
+
+`org credential revocation-list <org>` 支持 `--since-event-seq`／`--cursor`／`--limit`。创建、转让换钥与解散由 SDK 高层编排完成；`transfer-accept --proposal` 进入 rekey→finalize，保留持久 AIDStore 和原阶段材料用于恢复。
+
 ## 退出码
 
 | 退出码 | 含义 |

package/_packed_docs/sdk/0.5.22-SDK/345/274/200/345/217/221/344/270/216/347/247/273/346/244/215/346/214/207/345/215/227.md

@@ -91,7 +91,7 @@ NS 的 `ownership_pending` 与名片 CAS 一起持久化；pending 名片是当
 - 按 authority/CID 保留最大 `event_seq`，推送与分页并发合并，不覆盖新记录。
 - 异步验证／持久化前后核对身份和连接代次，丢弃旧结果；用于完整凭证和父证明链验证。
 
-四端使用 tokenstore／keystore 的 `credential_revocations_v1` metadata（浏览器 IndexedDB），按 authority 保存 CID 序号、分页 checkpoint 和证明时间窗。它不是 JSONL 流水，缺少 CID 不证明有效；结构见 [撤销快照](凭证与组织服务SDK开发与移植指南.md#54-撤销同步与持久快照0522)。
+四端使用 tokenstore／keystore 的 `credential_revocations_v1` metadata（浏览器 IndexedDB），按 authority 保存 CID 序号、分页 checkpoint 和证明时间窗。它不是 JSONL 流水，缺少 CID 不证明有效；结构见 [撤销快照](凭证与组织服务SDK开发与移植指南.md#64-撤销同步与持久快照0522)。
 
 ### 5.2 保持分页连续
 
@@ -114,7 +114,7 @@ NS 的 `ownership_pending` 与名片 CAS 一起持久化；pending 名片是当
 - 转让换钥前复核证书／公钥代际，新公钥用规范 DER Base64；已有 checkpoint 恢复原请求。
 - 原子保存新旧 owner 成员包与定向 `org.member.changed` 通知；失败通知保留待办并按组织轮转。SDK 仍验完整包，续期保存不依赖通知。
 
-详见 [Credential RPC](09-凭证服务RPC手册.md#credentialrevoke)、[Org RPC](09-组织服务RPC手册.md#组织生命周期)及 [服务实现要求](凭证与组织服务SDK开发与移植指南.md#7-服务端兼容实现要点)。
+详见 [Credential RPC](09-凭证服务RPC手册.md#credentialrevoke)、[Org RPC](09-组织服务RPC手册.md#组织生命周期)及 [服务实现要求](凭证与组织服务SDK开发与移植指南.md#8-服务端兼容实现要点)。
 
 ## 6. 默认读缓存、语言专项修复与版本
 

package/_packed_docs/sdk/06-API/346/211/213/345/206/214.md

@@ -476,7 +476,7 @@ headers = client.get_protected_headers()
 | 领域 | 当前入口 | 详细指南 |
 |------|----------|----------|
 | Ownership 2.1 | 七个关系业务Facade：`bindOwneraid`、`bindSubaid`、`releaseSubaid`、`transferSubaid`、`acceptOwnershipRequest`、`rejectOwnershipRequest`、`checkOwnershipConsensus`；无参数任务管理Facade `resetOwnershipTask()`（Python `reset_ownership_task()`、Go `ResetOwnershipTask(ctx)`），批量清理当前AID发起的未完成任务，返回`{reset_operation_ids:[],skipped_operation_ids:[]}`（其余为TS/JS命名） | [应用集成](Ownership2.1-SDK应用集成指南.md#4-七个-facade-的参数角色与结果)、[开发与移植](Ownership2.1-SDK开发与移植指南.md) |
-| Credential/Org | Python/TS/JS：`client.credential`、`client.org`；Go：`client.Credential()`、`client.Org()`；包含本地协议助手和业务 facade，服务端可用方法以 RPC 手册为准 | [应用集成](凭证与组织服务SDK应用集成指南.md)、[开发与移植](凭证与组织服务SDK开发与移植指南.md) |
+| Credential/Org | Python/TS/JS：`client.credential`、`client.org`；Go：`client.Credential()`、`client.Org()`；普通与语义凭证共用 credential 入口，无 semantic 子层；包含签验、包／请求、消息证据及额度协调工具 | [应用集成](凭证与组织服务SDK应用集成指南.md)、[开发与移植](凭证与组织服务SDK开发与移植指南.md) |
 
 Ownership 2.1 关系须检查当前双文件共识；Group/Org 使用专属生命周期，通用关系操作返回 `not_applicable`。Credential/Org 的本地验签不代替当前状态和请求授权检查。
 
@@ -1062,7 +1062,7 @@ JavaScript 浏览器 SDK 的 Worker 是网络隔离增强：`new Worker()` 同
 |------|------|----------|
 | 消息 | [09-message-rpc-manual.md](09-message-rpc-manual.md) | `message.send` / `message.pull` / `message.history` / `message.ack` / `message.read` / `message.read_state` / `message.thought.*` |
 | 群组 | [09-group-rpc-manual.md](09-group-rpc-manual.md) | `group.create` / `group.send` / `group.pull` / `group.history` / `group.read` / `group.read_state` / `group.v2.*` / `group.fs.*` |
-| 凭证 | [凭证服务 RPC 手册](09-凭证服务RPC手册.md) | `credential.register` / `credential.revoke` / `credential.status` / `credential.revocationList` |
+| 凭证 | [凭证服务 RPC 手册](09-凭证服务RPC手册.md) | 普通 `credential.register/revoke/status/revocationList`；语义 `credential.semantic.register/revise/get/status/revoke/revocationList`，本地工具与业务接入见专题 §10 |
 | 组织 | [组织服务 RPC 手册](09-组织服务RPC手册.md) | `org.lifecycle.*` / `org.member.*` / `org.credential.*` / `org.audit.query` / `org.authz.check`；内部及未实现方法见手册 |
 | 存储 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) | `storage.put_object` / `storage.fs.*` / `storage.volume.*` / ACL / token / share link |
 | 协作 | [09-collab-rpc-manual.md](09-collab-rpc-manual.md) | `collab.ls-files` / `collab.show` / `collab.commit` / `collab.merge` / `collab.log` / `collab.diff` / `collab.clone` / `collab.prune` / `collab.gc` / `collab.reflog` / `collab.revert` / `collab.tag.*` / `collab.ls-remote` / `collab.unregister` |

package/_packed_docs/sdk/09-/345/207/255/350/257/201/346/234/215/345/212/241RPC/346/211/213/345/206/214.md

@@ -1,73 +1,187 @@
-# 凭证服务 RPC 手册
-
-本文按 Credential Service 当前服务端 dispatcher 列出 RPC。`credential.health` 和不带凭证 CID 的 `credential.status` 用于控制面诊断；`credential.register/revoke`、带 CID 的 `credential.status` 和 `credential.revocationList` 是业务 RPC，经 Gateway service-plane 调用。
-
-## 方法索引
-
-| 方法 | 用途 |
-|------|------|
-| [credential.health](#credentialhealth) | 服务健康诊断 |
-| [credential.status](#credentialstatus) | 查询服务状态或凭证状态证明 |
-| [credential.register](#credentialregister) | 登记完整已签名凭证并取得回执 |
-| [credential.revoke](#credentialrevoke) | 吊销凭证 |
-| [credential.revocationList](#credentialrevocationlist) | 查询签名吊销事件增量 |
-
-## 通用约定
-
-凭证是 `aun-cap/1` 签名对象。服务端只接受完整已签名凭证，不提供 `credential.prepare` RPC。`credential.create`、`verifySignature`、`verify` 和 `verifyRegistrationReceipt` 是 SDK 本地 helper，不是服务端 RPC。
-
-业务请求使用 `request_id`、一次性 `nonce` 和 `request_binding`。绑定需匹配完整方法名、Credential Service target、业务参数摘要和有效时间窗；单凭证请求还绑定非空 `credential_cid`。只有 `credential.revocationList` 没有单一凭证目标，其绑定中的 `credential_cid` 固定为空字符串。请求不得把 `_auth.aid` 当作可由调用方自行声明的授权身份。
-
-## credential.health
-
-无业务参数。返回 `status`（`healthy` 或 `degraded`）、`implementation` 和 `details`，包含服务 AID、数据库、Kernel/Gateway 连接、签名身份就绪状态及运行时间。该方法用于诊断，不表示某个凭证有效。
-
-## credential.status
-
-不带 `credential_cid` 时返回服务状态摘要，包含 `module`、`status`、服务 AID、数据库连接、签名身份和运行时间；该形式是诊断入口。
-
-带 `credential_cid` 时执行凭证业务查询，必须提供 `request_id`、`nonce`、`request_binding`。可选 `include_chain: true` 返回父链状态。响应为 Credential Service 签名的 `aun-credential-status/1` proof，包含凭证 CID/hash、综合状态、叶凭证状态、issuer、subject、到期时间、事件序号、`asOf`、`proofExpiresAt`、responder、request ID、nonce、target 和签名；关联组织时还包含 `orgId`。
-
-`proofExpiresAt` 是状态证明的截止时间，`expiresAt` 是凭证自身到期时间。未知状态、过期 proof 或未知父链不能用于授权放行。
-
-## credential.register
-
-登记完整已签名凭证。转交登记时，`registration_authorization` 必须由凭证 issuer 签署；转交服务不会成为 registrar。
-
-| 参数 | 必需 | 说明 |
-|------|:---:|------|
-| `request_id`、`nonce` | 是 | 幂等请求标识和一次性随机数 |
-| `registrar_aid` | 是 | 必须等于 `credential.iss` |
-| `credential` | 是 | 完整 `aun-cap/1` 对象，含签名 |
-| `request_binding` | 是 | 绑定方法、服务 target、参数摘要、时间窗和 CID |
-| `registration_authorization` | 条件 | 认证调用者不是 issuer 时必需 |
-| `proof_chain` | 条件 | 有父凭证时提供；若凭证内也携带，二者必须一致 |
-
-成功返回 `credentialCid`、`status=active`、`registeredAt` 和 Credential Service 签名的 `registrationReceipt`。登记回执证明登记结果，不单独授予能力；Org 入组仍须由 Org Service 独立验凭证和回执并完成成员关系最终化。
-
-## credential.revoke
-
-吊销凭证；默认级联吊销子凭证。除参数绑定外，服务会核实调用身份是 issuer 或登记时记录的授权吊销主体。
-
-| 参数 | 必需 | 说明 |
-|------|:---:|------|
-| `request_id`、`nonce`、`request_binding` | 是 | 本次吊销请求及其目标、摘要和时间窗绑定 |
-| `registrar_aid`、`credential_cid`、`reason_code` | 是 | 吊销主体、目标 CID 和原因码 |
-| `reason` | 否 | 脱敏原因说明 |
-| `cascade` | 否 | 是否级联，默认 `true` |
-| `org_id`、`registration_request_id` | 条件 | 受限吊销授权要求时绑定组织和原登记操作 |
-| `registration_authorization` | 条件 | 补偿尚未登记的 CID 时提供原 issuer 授权 |
-
-成功返回 `credentialCid`、`status=revoked`、`revokedAt`、`eventSeq` 和 `cascadeCount`。同一 method、request ID 和参数摘要重试从持久去重记录返回原结果，进程重启后仍有效；同一 request ID 更换摘要返回 `CREDENTIAL_IDEMPOTENCY_KEY_REUSE`。持久结果必须匹配原 CID 和 revoked 状态；记录损坏或状态不明返回 `CREDENTIAL_STATUS_UNKNOWN`，不能当作补偿已完成。
-
-## credential.revocationList
-
-查询吊销事件增量。请求可提供 `issuer_aid`、`since_event_seq` 或 `cursor`、`limit`，并必须提供 `request_id`、`nonce`、`request_binding`。`limit` 默认 1000，最大 1000。
-
-响应包含 `events[]`、`next_cursor`、`as_of`、`expires_at`、`responder`、`request_id`、`nonce`、`target`、`issuer_aid` 和签名。每个事件包含 `event_seq`、`cid`、`reason_code`、`revoked_at`、`revoked_by_aid`，可选 `reason` 和 `cascade_root_cid`。客户端应验证服务签名与证明时间窗，并按序号续查。
-
-SDK 0.5.22 将已验签的 `credential.revoked`／`credential.revocationList` 推送和列表页持久合并，单条事件不推进分页位置，旧分页不能覆盖新撤销证据。后台兜底拉取在连接后一小时首次执行，此后每小时一次；这是 SDK 调度策略，不是 RPC 的限频或服务端分页契约。存储、身份隔离和 proof 要求见 [SDK 移植指南](凭证与组织服务SDK开发与移植指南.md#54-撤销同步与持久快照0522)。
-
-## 错误
-
-业务错误码位于 JSON-RPC `error.data.error_code`，包括 `CREDENTIAL_INVALID`、`CREDENTIAL_SIGNATURE_INVALID`、`CREDENTIAL_CHAIN_INVALID`、`CREDENTIAL_EXPIRED`、`CREDENTIAL_REVOKED`、`CREDENTIAL_REQUEST_BINDING_INVALID`、`CREDENTIAL_AUTHENTICATION_INVALID`、`CREDENTIAL_IDEMPOTENCY_KEY_REUSE`、`CREDENTIAL_NOT_FOUND` 和 `CREDENTIAL_STATUS_UNKNOWN`。状态未知或服务/数据库不可用不能按有效处理。未注册的方法返回 JSON-RPC `Method not found`。
+# 凭证服务 RPC 手册
+
+本文按 Credential Service 当前服务端 dispatcher 列出 RPC。`credential.health` 和不带凭证 CID 的 `credential.status` 用于控制面诊断；普通 `credential.register/revoke`、带 CID 的 `credential.status`、`credential.revocationList` 及六个 `credential.semantic.*` 均是业务 RPC，经已认证 Gateway service-plane 调用。本文对齐当前工作区实现，不据此声明发布包已具备扩展。
+
+## 方法索引
+
+| 方法 | 用途 |
+|------|------|
+| [credential.health](#credentialhealth) | 服务健康诊断 |
+| [credential.status](#credentialstatus) | 查询服务状态或凭证状态证明 |
+| [credential.register](#credentialregister) | 登记完整已签名凭证并取得回执 |
+| [credential.revoke](#credentialrevoke) | 吊销凭证 |
+| [credential.revocationList](#credentialrevocationlist) | 查询签名吊销事件增量 |
+| [credential.semantic.register](#credentialsemanticregister) | 登记语义原件、确认元数据及来源链 |
+| [credential.semantic.revise](#credentialsemanticrevise) | 修订受众元数据，或准备／提交／终止额度切换 |
+| [credential.semantic.get](#credentialsemanticget) | 读取当前／历史修订或协调恢复材料 |
+| [credential.semantic.status](#credentialsemanticstatus) | 查询绑定修订的当前状态证明 |
+| [credential.semantic.revoke](#credentialsemanticrevoke) | 撤销整个语义 CID |
+| [credential.semantic.revocationList](#credentialsemanticrevocationlist) | 按受众 scope 读取签名撤销快照及增量 |
+
+## 通用约定
+
+下列普通凭证接口使用 `aun-cap/1` 签名对象，语义 `aun-cap/semantic-1` 使用后文独立方法和存储。服务端只接受完整已签名凭证，不提供 `credential.prepare` RPC。`credential.create`、`verifySignature`、`verify` 和 `verifyRegistrationReceipt` 是 SDK 本地 helper，不是服务端 RPC。
+
+业务请求使用 `request_id`、一次性 `nonce` 和 `request_binding`。绑定需匹配完整方法名、Credential Service target、业务参数摘要和有效时间窗；单凭证请求还绑定非空 `credential_cid`。只有 `credential.revocationList` 没有单一凭证目标，其绑定中的 `credential_cid` 固定为空字符串。请求不得把 `_auth.aid` 当作可由调用方自行声明的授权身份。
+
+## credential.health
+
+无业务参数。返回 `status`（`healthy` 或 `degraded`）、`implementation` 和 `details`，包含服务 AID、数据库、Kernel/Gateway 连接、签名身份就绪状态及运行时间。该方法用于诊断，不表示某个凭证有效。
+
+## credential.status
+
+不带 `credential_cid` 时返回服务状态摘要，包含 `module`、`status`、服务 AID、数据库连接、签名身份和运行时间；该形式是诊断入口。
+
+带 `credential_cid` 时执行凭证业务查询，必须提供 `request_id`、`nonce`、`request_binding`。可选 `include_chain: true` 返回父链状态。响应为 Credential Service 签名的 `aun-credential-status/1` proof，包含凭证 CID/hash、综合状态、叶凭证状态、issuer、subject、到期时间、事件序号、`asOf`、`proofExpiresAt`、responder、request ID、nonce、target 和签名；关联组织时还包含 `orgId`。
+
+`proofExpiresAt` 是状态证明的截止时间，`expiresAt` 是凭证自身到期时间。未知状态、过期 proof 或未知父链不能用于授权放行。
+
+## credential.register
+
+登记完整已签名凭证。转交登记时，`registration_authorization` 必须由凭证 issuer 签署；转交服务不会成为 registrar。
+
+| 参数 | 必需 | 说明 |
+|------|:---:|------|
+| `request_id`、`nonce` | 是 | 幂等请求标识和一次性随机数 |
+| `registrar_aid` | 是 | 必须等于 `credential.iss` |
+| `credential` | 是 | 完整 `aun-cap/1` 对象，含签名 |
+| `request_binding` | 是 | 绑定方法、服务 target、参数摘要、时间窗和 CID |
+| `registration_authorization` | 条件 | 认证调用者不是 issuer 时必需 |
+| `proof_chain` | 条件 | 有父凭证时提供；若凭证内也携带，二者必须一致 |
+
+成功返回 `credentialCid`、`status=active`、`registeredAt` 和 Credential Service 签名的 `registrationReceipt`。登记回执证明登记结果，不单独授予能力；Org 入组仍须由 Org Service 独立验凭证和回执并完成成员关系最终化。
+
+## credential.revoke
+
+吊销凭证；默认级联吊销子凭证。除参数绑定外，服务会核实调用身份是 issuer 或登记时记录的授权吊销主体。
+
+| 参数 | 必需 | 说明 |
+|------|:---:|------|
+| `request_id`、`nonce`、`request_binding` | 是 | 本次吊销请求及其目标、摘要和时间窗绑定 |
+| `registrar_aid`、`credential_cid`、`reason_code` | 是 | 吊销主体、目标 CID 和原因码 |
+| `reason` | 否 | 脱敏原因说明 |
+| `cascade` | 否 | 是否级联，默认 `true` |
+| `org_id`、`registration_request_id` | 条件 | 受限吊销授权要求时绑定组织和原登记操作 |
+| `registration_authorization` | 条件 | 补偿尚未登记的 CID 时提供原 issuer 授权 |
+
+成功返回 `credentialCid`、`status=revoked`、`revokedAt`、`eventSeq` 和 `cascadeCount`。同一 method、request ID 和参数摘要重试从持久去重记录返回原结果，进程重启后仍有效；同一 request ID 更换摘要返回 `CREDENTIAL_IDEMPOTENCY_KEY_REUSE`。持久结果必须匹配原 CID 和 revoked 状态；记录损坏或状态不明返回 `CREDENTIAL_STATUS_UNKNOWN`，不能当作补偿已完成。
+
+## credential.revocationList
+
+查询吊销事件增量。请求可提供 `issuer_aid`、`since_event_seq` 或 `cursor`、`limit`，并必须提供 `request_id`、`nonce`、`request_binding`。`limit` 默认 1000，最大 1000。
+
+响应包含 `events[]`、`next_cursor`、`as_of`、`expires_at`、`responder`、`request_id`、`nonce`、`target`、`issuer_aid` 和签名。每个事件包含 `event_seq`、`cid`、`reason_code`、`revoked_at`、`revoked_by_aid`，可选 `reason` 和 `cascade_root_cid`。客户端应验证服务签名与证明时间窗，并按序号续查。
+
+SDK 0.5.22 将已验签的 `credential.revoked`／`credential.revocationList` 推送和列表页持久合并，单条事件不推进分页位置，旧分页不能覆盖新撤销证据。后台兜底拉取在连接后一小时首次执行，此后每小时一次；这是 SDK 调度策略，不是 RPC 的限频或服务端分页契约。存储、身份隔离和 proof 要求见 [SDK 移植指南](凭证与组织服务SDK开发与移植指南.md#64-撤销同步与持久快照0522)。
+
+## 错误
+
+业务错误码位于 JSON-RPC `error.data.error_code`，包括 `CREDENTIAL_INVALID`、`CREDENTIAL_SIGNATURE_INVALID`、`CREDENTIAL_CHAIN_INVALID`、`CREDENTIAL_EXPIRED`、`CREDENTIAL_REVOKED`、`CREDENTIAL_REQUEST_BINDING_INVALID`、`CREDENTIAL_AUTHENTICATION_INVALID`、`CREDENTIAL_IDEMPOTENCY_KEY_REUSE`、`CREDENTIAL_NOT_FOUND` 和 `CREDENTIAL_STATUS_UNKNOWN`。状态未知或服务/数据库不可用不能按有效处理。未注册的方法返回 JSON-RPC `Method not found`。
+
+## 语义凭证公共约定
+
+本节六方法的字段以[正式规范](../../../extensions/services/docs/org/0.8/语义凭证扩展规范.md)和[详细设计 §3](../../../extensions/services/docs/org/0.8/working/语义凭证扩展详细设计.md#3-凭证服务接口)为准。JSON-RPC 使用 `{jsonrpc,id,method,params}`，成功数据直接位于 result，不额外嵌套 data。未知字段、分支外字段和未显式允许的 null 拒绝；标识为非空字符串，时间／序号／epoch 为安全整数，集合按规范排序去重。
+
+| 六方法公共参数 | 约定 |
+| --- | --- |
+| request_id、nonce | 固定管理操作标识和至少 128 位的安全随机 nonce；重试保留原操作材料 |
+| credential_cid | 单凭证操作非空；只有 semantic.revocationList 固定为空字符串 |
+| request_binding | 八字段：request_id、nonce、target、method、params_hash、iat、exp、credential_cid |
+| authority | `{policy,evidence}`；policy 为固定版本／hash 的 PolicyRef，evidence 为权限依据数组，服务按可信策略和真实认证 actor 核对 |
+
+绑定的 target 为真实 `credential.{issuer}`，method 为完整 `credential.semantic.*`，ID／nonce／CID 与顶层一致。params_hash 使用扩展 canonical，排除根 request_binding 及服务注入认证字段，覆盖其余完整参数和所有嵌套签名。调用方不得提交 `_auth` 等服务认证上下文。声明期限满足 `0 < exp-iat <= 300`；首次验收窗口为 `iat-300 <= now <= exp+300`，含边界。nonce、幂等及既成结果的恢复仍按服务持久记录核对，不能靠回拨 iat 延长新操作期限。
+
+`SignedJsonBytes` 仅含 `bytes_base64`：带 padding 的标准 Base64，解码为严格 UTF-8 JSON 原字节。服务保留字节，在副本上计算完整 canonical 摘要；EvidenceRef 的 `data_base64` 不可替代此包装。metadata 签名省略 `confirmation.signature.signature`，其他扩展对象省略自身 `signature.signature`，均保留其余封套和嵌套签名。
+
+SDK facade 统一为 `client.credential`／Go `client.Credential()`，输入省略 request_binding，由 facade 按实际目标和当前 Unix 秒生成；low-level 必须提供完整绑定。Python 使用 `target=`；TS／JS 使用第二参数 `{serviceAid}`；Go 用 `NewCredentialFacade(client, serviceAID)` 指定跨域权威。旧同名方法按字段严格分流，见[移植指南 §4](凭证与组织服务SDK开发与移植指南.md#4-语义凭证移植契约)。
+
+## credential.semantic.register
+
+| 业务参数 | 说明 |
+| --- | --- |
+| original | 已签 `aun-cap/semantic-1` 原件的 SignedJsonBytes，CID 等于 credential_cid |
+| metadata | 非空 SignedJsonBytes 数组；original_hash 一致，各份 aud 不重叠，候选合起来覆盖完整初始受众 |
+| lineage_evidence | root→直接 parent 的完整来源链材料；根凭证为空数组 |
+
+返回 `{cid,original_hash,audiences}`；每项 audience 记录含 `{audience,revision,state_seq,registration_receipt}`，初始 state_seq=1。revision 绑定 CID、原件摘要及 metadata 版本／摘要；回执是服务签名的登记见证，不是业务授权。
+
+服务核对原件签署身份、K 的确认权、显式原件上限、全部来源链和登记权限，并在自身边界强查父状态。相同管理幂等键恢复原结果；已存在 CID 上的另一登记操作返回 REVISION_CONFLICT，不覆盖原件。
+
+## credential.semantic.revise
+
+kind 决定唯一分支，另含公共参数：
+
+| kind | 分支参数 | 行为及返回 |
+| --- | --- | --- |
+| metadata | change：expected、metadata；可选 expected_absent、withdraw、expected_withdrawn | 按受众 CAS 发布／撤下；返回 `{kind,cid,original_hash,audiences,withdrawn}` |
+| usage_prepare | transition_id、from_usage、to_usage、change、previous_abort_acks | 持久准备候选；返回 `{kind,transition}`，服务分配 fence 和 candidate_hash |
+| usage_commit | transition_id、fence、checkpoints、allocation_closures、acceptances | 核对全部权威材料，同事务发布新 UsageRef 与所有候选 aud；返回 `{kind,transition}` |
+| usage_abort | transition_id、fence、from_usage | 持久终止原转换；返回 `{kind,transition}` |
+
+metadata 变更的当前 aud 列入 expected，首次新增列入 expected_absent，撤下后的重加列入 expected_withdrawn；三者互斥。metadata／withdraw 至少一项非空，至少保留一个当前 aud；全终止用 revoke。变更共享确认字段必须列齐相关 aud；CID 内 metadata_version 不可换内容复用，state_seq 随受众变更递增。结果只含本次发布／撤下项，其他当前项通过 get 读取。
+
+usage_prepare 的 change 覆盖全部当前 aud 和完整候选元数据，to_usage.epoch=from_usage.epoch+1，hash 绑定完整候选契约。每 CID 至多一个 prepared，准备不发布候选。前次 aborted 时收齐原权威 LedgerAbortAck，否则 previous_abort_acks 可为空；客户端不得自造 fence／candidate_hash。
+
+commit 的 checkpoints／acceptances 非空，allocation_closures 包含检查点引用的全部 closed 分配证明。缺失、不连续或 fence 不符返回冲突。结果未知先 get 原 transition；普通 abort 的恢复资格与 CID 撤销导致的终止分别记录，不能自行解冻。SDK prepareUsage／commitUsage／abortUsage 是本方法快捷入口，只返回 transition，不是三个新增 RPC。
+
+## credential.semantic.get
+
+业务参数 audience 必填；metadata_version 与 transition_id 至多一个，均不传表示读取该 aud 当前修订。
+
+| 结果 kind | 返回字段 |
+| --- | --- |
+| revision | `{kind,original,metadata,revision,registration_receipt,head}` |
+| transition | `{kind,original,transition,change}` |
+
+original／metadata 保持 SignedJsonBytes。head 为 current（revision、state_seq）或 withdrawn（last_revision、state_seq），均绑定 audience。当前 aud 已撤下时不返回可当当前使用的历史修订；历史材料仍受读取 ACL 限制。transition 是已持久签名的协调记录，供原阶段恢复。
+
+## credential.semantic.status
+
+业务参数为 audience、expected_revision、policy；online 另含 query。
+
+| policy | 查询与时效 |
+| --- | --- |
+| `{mode:"online"}` | query 为 `{request_hash,nonce}`，绑定稳定业务摘要和独立查询随机数；本地单调时钟计时到验收小于 30 秒 |
+| `{mode:"bounded",max_staleness_seconds}` | max_staleness_seconds 为 1—300；不得提交 query，验真同时核对绝对窗口与本地首次观察后的 TTL |
+
+返回服务签名的 CredentialStatusProof，绑定 CID／原件 hash、aud、metadata 版本／hash、state_seq、状态、服务身份和证明时间；online 回显对应查询绑定。当前修订与 expected_revision 不一致、aud 已撤下时返回 REVISION_CONFLICT，不能拿历史回执代替当前状态。刷新同一修订的 status 不改变固定业务 request_hash。
+
+## credential.semantic.revoke
+
+业务参数 reason_code 必填、reason 可选。服务核对撤销权限后撤销整个 CID；成功返回 `{cid,original_hash,revoked_at,event_seq,affected}`，必要时含 transition。affected 绑定受影响受众的修订和序号。
+
+CID 重复撤销不新增撤销事件；相同管理幂等键返回原结果。prepared 转换在同一事务终止并记录不允许恢复的状态。未知结果不得按已撤销处理，先读取原操作结果。
+
+## credential.semantic.revocationList
+
+| 业务参数 | 说明 |
+| --- | --- |
+| scope | `{audiences:[...]}`，非空且为策略允许读取的完整受众集合 |
+| after_event_seq | 本 scope 已完整合并的上界；首次为 0，不能超过服务当前上界 |
+| cursor | 首页为 null，续页使用上次 next_cursor；不透明服务认证值 |
+| limit | 1—1000 安全整数，按匹配事件条数计 |
+
+返回 SemanticRevocationPage，含签名、service_aid、scope、query、upper_event_seq、cursor、事件、next_cursor、as_of／valid_until。query.params_hash 匹配本次管理绑定，query.nonce 匹配管理 nonce。
+
+首请求固定快照 upper_event_seq。续页保持 actor、服务、scope、after_event_seq、limit，使用新的管理 ID／nonce 和绑定；cursor 固定上述范围及扫描位置，不可自造。next_cursor=null（包括空页）才表示本快照结束；页签名及查询绑定验证成功后原子合并事件和进度，完成才推进增量上界。下一轮 cursor=null、after 为该上界；分页期间新增撤销由下一轮取得。
+
+scope 改变从 0 建独立进度，不能复用其他 scope 的 cursor 或上界。页时间过期用新管理请求取得同页；重放原管理幂等键仍得到原签名页。cursor 在 CRL 留存期内可用，没有另设隐含短 TTL。
+
+## 语义凭证错误
+
+六方法业务错误的 JSON-RPC `code=-32000`，程序分支使用 `error.data.error_code`，并保留 data／retryable；message 仅供人阅读。标准解析、认证、请求和方法错误保持原有错误码。
+
+| error.data.error_code | 处理 |
+| --- | --- |
+| SEMANTIC_FORMAT_INVALID | 核对版本、字段、类型、原字节、数值、集合及声明期限 |
+| SEMANTIC_SIGNATURE_INVALID | 取得原件／确认／证明的有效签名及正确签名域 |
+| SEMANTIC_IDENTITY_INVALID | 核对证书可信链、AID 及签署角色绑定 |
+| SEMANTIC_PERMISSION_DENIED | 核对认证 actor 和登记／确认／修订／撤销／读取权限 |
+| SEMANTIC_NOT_FOUND | 核对获准读取的 CID、metadata_version 或 transition_id |
+| SEMANTIC_REVISION_CONFLICT | 读取 current head，重新确认 CAS 前置条件与候选材料 |
+| SEMANTIC_TRANSITION_CONFLICT | 读取 transition／current_usage，核对 fence、阶段和完整连续材料 |
+| SEMANTIC_BINDING_INVALID | 核对实际目标、方法、CID、摘要、nonce、时间及 cursor 范围 |
+| SEMANTIC_IDEMPOTENCY_CONFLICT | 同 actor／method／request_id 已关联另一摘要；保持原操作，变更另建标识 |
+| SEMANTIC_STATE_UNAVAILABLE | 依赖／数据库／签名／可信策略暂不可用，保留原材料并退避重试 |
+
+仅 STATE_UNAVAILABLE 默认 retryable=true，其余为 false。data 可按原因和读取权限含 current、current_usage、transition、required 或 binding（server_time／clock_skew_seconds=300）；不要用空数组或 null 代替缺省。冲突不能靠更换材料反复重试原幂等键。应用流程见[SDK 集成指南 §4](凭证与组织服务SDK应用集成指南.md#4-语义凭证接入)，脚本入口见 [CLI 手册](../cli/CLI手册.md#凭证与语义凭证)。

package/_packed_docs/sdk/09-/347/273/204/347/273/207/346/234/215/345/212/241RPC/346/211/213/345/206/214.md

@@ -48,7 +48,7 @@
 
 ## 成员关系
 
-0.5.22 配套服务修复组织创建补偿与转让恢复：创建补偿遇到 `CREDENTIAL_IDEMPOTENCY_KEY_REUSE` 时保存冲突并停止自动补偿；转让开始换钥前复核当前证书／公钥代际，以规范 DER 公钥的 Base64 调用 CA，并将新旧 owner 的成员替换、完整成员包定向通知一起持久化。通知失败保留待办并按组织轮转；应用保留原任务、原请求及原密钥，不用更换 request ID 消除不确定结果。完整恢复要求见 [应用指南](凭证与组织服务SDK应用集成指南.md#6-所有权转让与实体材料)。
+0.5.22 配套服务修复组织创建补偿与转让恢复：创建补偿遇到 `CREDENTIAL_IDEMPOTENCY_KEY_REUSE` 时保存冲突并停止自动补偿；转让开始换钥前复核当前证书／公钥代际，以规范 DER 公钥的 Base64 调用 CA，并将新旧 owner 的成员替换、完整成员包定向通知一起持久化。通知失败保留待办并按组织轮转；应用保留原任务、原请求及原密钥，不用更换 request ID 消除不确定结果。完整恢复要求见 [应用指南](凭证与组织服务SDK应用集成指南.md#7-所有权转让与实体材料)。
 
 | 方法 | 主要业务参数 | 作用与结果 |
 |------|------|------|

package/_packed_docs/sdk/AUN_DOCS_GUIDE.md

@@ -41,7 +41,7 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 - Group RPC：成员 block/status、暂停群权限、两阶段群主转让、`group_aid` / `group_id` 兼容、`group.index` 签名索引与 CAS（见 `09-group-rpc-manual.md`、`06-API手册.md`）
 - 群文件系统：`group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` 上传下载、群自有区角色 ACL 与 `group_aid` 签名、`parents`、JS string 差异和 memberdata 服务端映射（见 `09-group-rpc-manual.md`）
 - 协作（collab）：`collab.*` 版本化文档、乐观锁 CAS commit、三方合并、标签、GC、reflog、revert（见 `09-collab-rpc-manual.md`）
-- Credential/Org：服务端实际注册的凭证与组织 RPC、受保护请求、内部接口及未实现占位（见 `09-凭证服务RPC手册.md`、`09-组织服务RPC手册.md`）
+- Credential/Org：普通及六语义RPC、受保护请求、CAS／额度协调、签名CRL和错误；语义接入／四SDK移植见两专题§3—§4，CN场景及验收边界见 `../../examples/semantic-credential/示例使用指南.md`
 - Service Proxy：`ServiceProxyClient`、`proxy.register_services`、proxy-server `register_services`
 - agent.md：Schema/frontmatter、Store.sign/verify 通用多签、显式 file/inPlace、multi-v1 表示协商、4 KiB/总尾区2048 字节限制、`AIDStore.register()` 默认自动上传、上传前完整校验、`agent_md_validation_v1`、`uploader_aid` / `uploaderAid`、`AIDStore.upload_agent_md()` / `download_agent_md()` / `check_agent_md()`、Gateway `_meta.agent_md_etags` 被动观察、`requester` / `peer` / `group` 角色
 - agent.md / group.index 的 ETag 权威来源、被动观察、下载触发、显式 pull 与 CAS → [ETag 观察与同步机制](agent.md与group.index的ETag观察与同步机制.md)
@@ -61,7 +61,7 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 | - | [0.5.22 SDK 开发与移植指南](0.5.22-SDK开发与移植指南.md) | 同步、Stage/CAS、撤销续期、缓存、服务依赖及 Rust 清单 |
 | - | [0.5.24 SDK 应用集成指南](0.5.24-SDK应用集成指南.md) | 当前消息接线、无任务 Ownership、两个 local 编排、缓存和凭证组织 |
 | - | [0.5.24 SDK 开发与移植指南](0.5.24-SDK开发与移植指南.md) | 消息提交、NS 事实和远端 CAS、local 身份隔离、缓存新鲜度与语言差异 |
-| - | 0.5.25 CHANGELOG：[Python](../../python/CHANGELOG.md)、[Go](../../go/CHANGELOG.md)、[TS](../../ts/CHANGELOG.md)、[JS](../../js/CHANGELOG.md) | 对照已提交 0.5.24 的消息、Ownership 缓存、名片下载及分域发现变更；实现差异与验证边界见 [parity](../../python/CHANGES_FOR_PARITY.md#v0525--已提交-v0524-基线变更未发布) |
+| - | [0.5.28 应用指南](0.5.28-SDK应用集成指南.md)、[开发与移植指南](0.5.28-SDK开发与移植指南.md)；[0.5.27 应用指南](0.5.27-SDK应用集成指南.md)、[开发与移植指南](0.5.27-SDK开发与移植指南.md) | 0.5.28 agent.md 上传／下载校验、共识 fresh、分类控制消息、Owner 通知与风控；四端实现和验证范围见 [parity](../../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布) |
 | - | [agent.md 与 group.index 的 ETag 观察与同步机制](agent.md与group.index的ETag观察与同步机制.md) | 服务端 ETag 来源、四 SDK 被动观察、agent.md 下载触发、group.index 显式 pull 与 CAS |
 | - | [CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) | **0.5.6 版本更新日志**：首次签名者回源、下载提交前验签、消息窗口、显式 change-seed 与语言能力边界 |
 | 01 | [快速开始](01-快速开始.md) | 安装、三主体模型、最小示例 |
@@ -76,9 +76,11 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 | - | [Ownership SDK集成指南（legacy）](Ownership-SDK集成指南.md) | TypeScript 快速接入、应用审批、状态查询及 SDK 编排流程图 |
 | - | [Ownership SDK实现指南（legacy）](Ownership-SDK实现指南.md) | SDK 移植入口、消息拦截、proof/escrow、metadata 和恢复验收 |
 | - | [Ownership协议定义（legacy）](../protocol/Ownership协议定义.md) | P2P/proof/agent.md schema、escrow、owner 授权头与现有 RPC |
-| - | [凭证与组织服务 SDK 应用集成指南](凭证与组织服务SDK应用集成指南.md) | TS 示例与凭证登记验证、成员申请／邀请、续期、撤销同步和组织转让图 |
-| - | [凭证与组织服务 SDK 开发与移植指南](凭证与组织服务SDK开发与移植指南.md) | TS 内部示例与 Verify、双层请求摘要、回执、撤销快照和实体 checkpoint 图 |
-| - | [凭证服务 RPC 手册](09-凭证服务RPC手册.md) | Credential Service 实际 RPC、参数和签名状态响应 |
+| - | [凭证与组织服务 SDK 应用集成指南](凭证与组织服务SDK应用集成指南.md) | 结构化§3 L21-304；语义§4 L305-763；组织§5—§7 L764-954 |
+| - | [凭证与组织服务 SDK 开发与移植指南](凭证与组织服务SDK开发与移植指南.md) | 结构化§3 L51-209；语义§4 L210-525；普通proof／CRL L651-894 |
+| - | [凭证与组织服务 CLI 开发与使用指南](../cli/凭证与组织服务CLI开发与使用指南.md) | TS运行器／23命令L5-121；凭证L122-591；组织L592-798；开发／错误／E2E L799-869 |
+| - | [凭证服务 RPC 手册](09-凭证服务RPC手册.md) | 旧版RPC及语义公共约定、六方法／CRL与十错误码L81-187 |
+| - | [语义凭证示例与验证](../../examples/semantic-credential/示例使用指南.md) | E01—E36、CN／本地aid.com、浏览器／普通凭证冷恢复及证据边界L3-94 |
 | - | [组织服务 RPC 手册](09-组织服务RPC手册.md) | Org Service 生命周期/成员 RPC、内部接口和未实现方法 |
 | 05 | [E2EE加密通信](05-E2EE加密通信.md) | E2EE V2、ProtectedHeaders、need_render、agent.md 版本提示、旧 SPK 保留 |
 | - | [ProtectedHeaders用法专题](ProtectedHeaders用法专题.md) | `protected_headers` 四端 API、实例级/单次调用、E2EE V2 HMAC 完整性和接收信任边界 |
@@ -101,7 +103,7 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 | 实现、移植或审查 0.5.22 SDK，查看 Stage/CAS、配套服务修复、读缓存及 Rust 验收清单 | [0.5.22 SDK 开发与移植指南](0.5.22-SDK开发与移植指南.md) |
 | 接入或升级 0.5.24，查看当前消息、无任务 Ownership、两个 local 场景、缓存及凭证组织 | [0.5.24 SDK 应用集成指南](0.5.24-SDK应用集成指南.md) |
 | 实现、移植或审查 0.5.24，核对提交／ACK、NS 事实、远端 CAS、local 身份隔离和缓存新鲜度 | [0.5.24 SDK 开发与移植指南](0.5.24-SDK开发与移植指南.md) |
-| 核查 0.5.25 的 Pull／volatile／群恢复、Ownership 缓存、名片下载退避与分域路由变更 | [parity 当前章节](../../python/CHANGES_FOR_PARITY.md#v0525--已提交-v0524-基线变更未发布)及各端 CHANGELOG；基线统一为已提交 0.5.24 |
+| 核查 0.5.28 的 schema、共识、控制消息、Owner 通知与风控；回看 0.5.27 的历史增量 | [0.5.28 应用指南](0.5.28-SDK应用集成指南.md)：接入与消息 §1—§3 L5-95、凭证／组织 §4—§5 L96-137、Storage／Ownership §6—§7 L138-186、通知 §8 L187-201、风控／升级 §9—§10 L202-228；[开发与移植指南](0.5.28-SDK开发与移植指南.md)：校验 §1 L7-36、共识 §2 L37-62、wire §3 L63-108、outbox §4 L109-121、风控 §5 L122-134、移植 §6 L135-146。 [parity 当前章节](../../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布) L15-99；历史 0.5.27 指南及 parity 保留原基线 |
 | 0.5.24 应用按主题读：身份、消息、resolve、Ownership、文件缓存、凭证组织和升级 | `0.5.24-SDK应用集成指南.md` §2 L21-75、§3 L76-132、§4 L133-168、§5 L169-298、§6 L299-321、§7 L322-366、§9 L386-401；local bind L227-245、local transfer L246-267 |
 | 0.5.24 移植按主题读：消息提交、名片、观察、Ownership、缓存、PKI、凭证组织及语言差异 | `0.5.24-SDK开发与移植指南.md` §3 L32-84、§4 L85-92、§5 L93-122、§6 L123-217、§7 L218-245、§8 L246-261、§9 L262-297、§10 L298-325；Rust §11 L326-339、验收 §12 L340-354 |
 | 首次使用 SDK | [01-快速开始](01-快速开始.md) |
@@ -113,9 +115,11 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 | Ownership 2.1 移植：NS 验收、条件发布、通用消息交付、本地编排和文件 CAS | [开发与移植指南](Ownership2.1-SDK开发与移植指南.md) |
 | Ownership 2.1 历史格式、reset、任务恢复及验证记录 | [审查报告第二十二节](../audit/Ownership2.1代码审查报告.md#二十二2026-10-18-恢复发布格式与历史兼容更正)、[旧编排第 8 节](Ownership-SDK编排指南2.1.md#8-崩溃与响应丢失后的恢复)；当前无任务／WAL，以两份现行指南为准 |
 | 当前双文件关系、release/清理/重绑版本、Header 投影及 Group/Org 名片 wire | [协议 2.1](../protocol/Ownership协议定义2.1.md) §3/§4.2/§6、§1.3/§2.5；旧 SDK RPC 隔离兼容见开篇/§3.2，旧 escrow/授权头 wire 查 legacy 协议 |
-| Credential/Org 应用：登记验证、入组、续期、撤销和转让图 | [应用集成指南](凭证与组织服务SDK应用集成指南.md) |
-| Credential/Org 移植：签验、双层摘要、快照和实体恢复 | [开发与移植指南](凭证与组织服务SDK开发与移植指南.md) |
-| 查 Credential Service RPC | [凭证服务 RPC 手册](09-凭证服务RPC手册.md) |
+| Credential/Org 应用：结构化完整链路与语义原件、包／请求和业务验收 | [应用集成指南](凭证与组织服务SDK应用集成指南.md)；结构化§3 L21-304／语义§4 L305-763／组织§5—§7 L764-954 |
+| Credential/Org 移植：结构化链／可信proof／CRL与语义四SDK契约 | [开发与移植指南](凭证与组织服务SDK开发与移植指南.md)；结构化§3 L51-209／语义§4 L210-525／普通proof与CRL §6.5—§6.6 L651-894 |
+| 查 Credential Service RPC：旧版及六语义方法／错误 | [凭证服务 RPC 手册](09-凭证服务RPC手册.md)；语义L81-187 |
+| 查语义凭证CN运行、E01—E36及真实验证边界／CLI | [示例指南](../../examples/semantic-credential/示例使用指南.md) L3-94；[CLI手册](../cli/CLI手册.md#凭证与语义凭证) L312-355 |
+| 凭证／组织CLI流程图、TS代码与SDK胶水开发 | [CLI专题](../cli/凭证与组织服务CLI开发与使用指南.md) §1—§3 L5-121；§4—§7 L122-591；§8—§10 L592-798；§11 L799-869 |
 | 查 Org Service RPC | [组织服务 RPC 手册](09-组织服务RPC手册.md) |
 | 自行发起 HTTP 数据面请求并获取当前 access token | [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、[Storage RPC 手册：数据面 HTTP 下载流程](09-storage-rpc-manual.md#数据面-http-下载流程) |
 | 发布、下载、检查或排查 agent.md（含 Schema/签名/大小限制）及远端 ETag | [当前协议 2.1](../protocol/Ownership协议定义2.1.md)、[04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)、[../agent.md/远程agent.md缓存与etag透传方案.md](../agent.md/远程agent.md缓存与etag透传方案.md) |