@agentunion/fastaun 0.5.25 → 0.5.27

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

@@ -0,0 +1,410 @@
+# AUN SDK 0.5.27 开发与移植指南
+
+面向四 SDK 维护者与其它语言实现者，以 TS 接口说明协议、持久状态与适配边界。应用接线见[应用集成指南](0.5.27-SDK应用集成指南.md)，完整凭证契约见[凭证与组织服务移植专题](凭证与组织服务SDK开发与移植指南.md)。
+
+## 1. 版本基线与阅读方式
+
+目标为截至 2026-10-29 的 `0.5.27` 工作区，功能基线为 `0.5.25` 源码提交 `133067c80`，包含中间提交和当前工作区增量。`0.5.26` 仅记录 TS npm 包的 `files` 白名单补入 `src/certs/root.crt`；运行时变化统一归入 `0.5.27`。
+
+| 范围 | 本版对齐内容 |
+| --- | --- |
+| 凭证 | 普通结构化完整 Verify；语义／混合凭证、来源链、请求、证据与 Usage 材料 |
+| 运行时 | 撤销同步、状态恢复、Gateway 迁移、当前态时间容错与心跳 |
+| 实体与存储 | 组织首次名片／转让恢复、TS／Go／浏览器根证书初始化、IndexedDB 生命周期 |
+| 验证边界 | 以源码及对应回归入口为准；已执行批次见 [parity 0.5.27](../../python/CHANGES_FOR_PARITY.md#v0527--相对于-v0525-基线的变更未发布) |
+
+```mermaid
+flowchart LR
+    A[协议字节和签名域] --> B[签验与状态机]
+    B --> C[Facade 和 RPC 映射]
+    C --> D[身份存储与传输适配]
+    D --> E[语言回归与场景验收]
+```
+
+下文 TS 片段按出现顺序共用以下声明；相对导入指向仓库源码。`declare` 表示宿主注入的输入或端口，其类型来自真实 SDK；业务示例在[应用指南](0.5.27-SDK应用集成指南.md)中展开。
+
+```ts
+import type { AUNClient } from '../../ts/src/client.js';
+import type { CredentialSigner, CredentialVerificationContext } from '../../ts/src/org-protocol.js';
+import type { SemanticPackageVerificationContext } from '../../ts/src/semantic-facade.js';
+import type { EventPayload } from '../../ts/src/events.js';
+import * as protocol from '../../ts/src/semantic-protocol.js';
+declare const client: AUNClient;
+declare const signer: CredentialSigner;
+declare const trust: protocol.RecordVerificationContext;
+declare const semanticServiceAid: string;
+```
+
+## 2. 严格 JSON、签名字节与时间
+
+### 2.1 原件与规范摘要
+
+签名 JSON 使用 `SignedJsonBytes` 保留原字节；严格解析与结构校验拒绝重复键、不安全整数、孤立 surrogate 和非法字段。区分缺省与 `null`，保留数组顺序。语义 canonical JSON 按协议排序键、规范字符串及数字，摘要为 `sha256:<小写 hex>`。
+
+```mermaid
+flowchart LR
+    A[原始 JSON 字节] --> B[严格解析与结构校验]
+    B --> C[按对象规则生成签名字节]
+    C --> D[P-256 与 SHA-256 签验]
+    B --> E[规范摘要绑定原件与修订]
+    A --> F[保留 SignedJsonBytes]
+```
+
+```ts
+declare const sourceBytes: Uint8Array;
+const parsed = protocol.parseJsonStrict(sourceBytes);
+const canonical = protocol.canonicalJson(parsed);
+const objectHash = protocol.digest(parsed);
+const rawHash = protocol.bytesDigest(sourceBytes);
+const encodedCanonical = protocol.encodeSignedJson(parsed);
+```
+
+`objectHash` 是规范对象摘要，`rawHash` 是原字节摘要；`encodeSignedJson` 编码给定对象，保存外部原件时应直接保留收到的 `SignedJsonBytes`。普通 CAP 与组织外层 `client_signature` 的 canonical 规则分层沿用，见[共同密码学规则](凭证与组织服务SDK开发与移植指南.md#2-共同密码学和-json-规则)。
+
+### 2.2 签名域与证书端口
+
+十一签名域分别为 semantic-credential、registration-metadata、registration-receipt、credential-status、usage-allocation、allocation-status、semantic-crl、usage-transition、usage-checkpoint、usage-acceptance、ledger-abort。签名为 ECDSA P-256／SHA-256、标准 Base64 的 ASN.1 DER；浏览器 WebCrypto 适配负责签名格式转换。
+
+```ts
+declare const semanticDraft: Parameters<typeof client.credential.signCredential>[0];
+const signedOriginal = await client.credential.signCredential(semanticDraft, signer);
+const originalReport = await client.credential.verifyOriginal(signedOriginal, {
+  ...trust, expectedAid: signer.aid,
+});
+```
+
+证书 resolver 按指纹、AID 与签署时点取材料，trust verifier 校验可信链与身份。当前态资格使用 ±300 秒容错；历史签署时点、本地签名资格按证书原始有效期检查。声明最大生命周期、单调耗时与缓存 TTL 各自执行。
+
+```ts
+declare const nbf: number;
+declare const exp: number | null;
+const now = Math.trunc(Date.now() / 1000);
+protocol.validateWindow(nbf, exp, now);
+```
+
+## 3. 普通结构化凭证
+
+`aun-cap/1` 继续使用原创建、登记、状态、撤销及完整 Verify。根深度为 0，子凭证递增，最大委托深度 8；各层受众、时间、能力及约束收窄。混合来源链中的普通层通过可信 `legacyVerifier` 复用此路径。
+
+```mermaid
+flowchart TD
+    A[异步预载可信证书和当前状态] --> B[建立同步只读 resolver]
+    B --> C[结构与逐层签名及委托链]
+    C --> D[实际能力和约束]
+    D --> E[实际请求绑定]
+    E --> F[成员及代表的当前材料]
+    F --> G[重查有效窗口并返回结果]
+```
+
+```ts
+declare const ordinaryOptions: Parameters<typeof client.credential.create>[0];
+const ordinaryCredential = client.credential.create(ordinaryOptions, signer);
+declare const ordinaryContext: CredentialVerificationContext;
+const ordinarySignature = client.credential.verifySignature(
+  ordinaryCredential, ordinaryContext.resolveCertificate,
+  ordinaryContext.now, ordinaryContext.audience,
+);
+const ordinaryVerified = client.credential.verify(ordinaryCredential, ordinaryContext);
+```
+
+TS 的普通 `verify` 为同步调用。`ordinaryContext` 注入真实 audience、subject、能力与约束，以及 method／target／params／requestId／nonce／requestBinding。成员及代表场景还接当前成员、Ownership 与 actor 状态；异步网络取材在调用前完成。具体端口见[同步完整 Verify](凭证与组织服务SDK开发与移植指南.md#34-同步完整-verify-与约束端口)。
+
+```ts
+declare const ordinaryReceipt: unknown;
+declare const ordinaryRequest: Record<string, unknown>;
+declare const ordinaryServiceAid: string;
+client.credential.verifyRegistrationReceipt(
+  ordinaryReceipt, ordinaryCredential, ordinaryRequest,
+  ordinaryContext.resolveCertificate, ordinaryServiceAid, ordinaryContext.now,
+);
+```
+
+普通状态证明须验服务身份、签名、CID、当前态、窗口与请求挑战，再供同步 resolver 使用；CRL 验完整分页后原子保存事件与游标。适配见[普通状态证明](凭证与组织服务SDK开发与移植指南.md#65-普通状态证明的可信适配)、[普通 CRL](凭证与组织服务SDK开发与移植指南.md#66-普通-crl-分页与原子持久)。
+
+## 4. 语义与混合凭证
+
+### 4.1 模式与管理调用
+
+| 模式 | 授权材料 |
+| --- | --- |
+| 纯语义 `aun-cap/semantic-1`、`cap=[]` | 原件、确认元数据、正文及业务策略 |
+| 混合 `aun-cap/semantic-1`、非空 `cap` | 结构化能力与语义限制共同验收，逐层取交集 |
+| 混合来源链 | 普通层完整 Verify，加语义层原件／元数据／回执／当前态验证 |
+
+六个 RPC 为 `credential.semantic.register/get/status/revise/revoke/revocationList`。`client.credential` 平铺这些能力；普通同名方法按语义字段分流。跨域 TS／JS 使用第二参数 `{serviceAid}`，Python 使用 `target=`，Go 通过目标 Facade 与 context 调用。
+
+```mermaid
+flowchart LR
+    A[原件与确认元数据分别签名] --> B[Facade 生成管理 binding]
+    B --> C[六个 semantic RPC]
+    C --> D[逐项校验原件和修订及服务回执]
+    D --> E[按权威与受众保存观察状态]
+```
+
+```ts
+declare const registerInput: protocol.SemanticFacadeInput<protocol.SemanticRegisterParams>;
+const registered = await client.credential.register(registerInput, {
+  serviceAid: semanticServiceAid,
+});
+declare const reviseInput: protocol.SemanticFacadeInput<protocol.SemanticReviseParams>;
+const revised = await client.credential.revise(reviseInput, {
+  serviceAid: semanticServiceAid,
+});
+```
+
+Facade 输入省略 `request_binding`，由 SDK 绑定实际 method、target、参数摘要、CID、request_id、nonce 与时间。low-level 使用完整 wire；幂等重试沿原 request_id 和同一意图，错误保留 `data.error_code`、`retryable` 及状态材料。
+
+```ts
+const registerWire: protocol.SemanticRegisterParams = {
+  ...registerInput,
+  request_binding: protocol.buildManagementBinding(
+    'credential.semantic.register', semanticServiceAid, registerInput,
+  ),
+};
+```
+
+### 4.2 来源链、认证请求与业务决策
+
+```mermaid
+flowchart TD
+    A[根到叶的来源链] --> B[buildPackage 校验结构和上下界]
+    B --> C[verifyPackage 验签及当前态]
+    C --> D[verifyRequest 绑定认证 actor 与实际服务]
+    D --> E[逐层正文及结构化能力交集]
+    E --> F[事实和策略生成 DecisionInput]
+    F --> G[宿主完成业务接受及原子执行]
+```
+
+```ts
+declare const lineage: protocol.CredentialLineageEntry[];
+declare const packageContext: SemanticPackageVerificationContext;
+const grant = await client.credential.buildPackage(lineage);
+const packageReport = await client.credential.verifyPackage(grant, packageContext);
+```
+
+`packageContext` 提供真实 audience、签发者与可信 resolver；跨域以 `serviceFor(cid)` 指定各层权威，普通层提供 `legacyVerifier`。online 模式还传各 CID 的 query 及实际单调耗时。`checked` 与 `required` 分别列出已验项目和宿主待完成项目。
+
+```ts
+declare const requestInput: Parameters<typeof client.credential.buildRequest>[0];
+declare const authentication: protocol.AuthenticatedAUNContext;
+declare const requestOptions: Parameters<typeof client.credential.verifyRequest>[2];
+const request = await client.credential.buildRequest(requestInput);
+const requestReport = await client.credential.verifyRequest(
+  request, authentication, requestOptions,
+);
+```
+
+发送端请求有效期为当前时刻之后、最长 300 秒；接收端调用 SDK 时间校验。认证 actor、服务、subject 与代表关系取自当前认证和可信材料，参数与来源链摘要绑定同一请求。
+
+```ts
+declare const bodies: protocol.VerifiedBody[];
+declare const facts: protocol.JsonObject;
+declare const policy: protocol.PolicyRef;
+const decisionInput = await client.credential.buildDecisionInput(
+  request, bodies, facts, policy,
+);
+```
+
+模型返回 allow／deny／indeterminate；宿主按策略验引用、事实有效期、后置条件及额度，再形成执行回执。`verifyRequest` 与 `verifyPackage` 的验真结果分别供这些步骤使用。
+
+### 4.3 状态、CRL 与冷恢复
+
+online 状态及 allocation 查询的本地单调耗时严格小于 30 秒，绑定本次 request_hash／nonce；bounded 最大陈旧度为 300 秒。消费 TTL 直接比较单调耗时；当前态 ±300 秒容错不延长消费期限。
+
+```mermaid
+flowchart TD
+    A[按权威和 CID 及受众读取本地观察] --> B[查询绑定当前修订和策略]
+    B --> C[验签及 challenge 和时间]
+    C --> D[核对 state_seq 与已观察终态]
+    D --> E[原子保存状态或完整 CRL 页和游标]
+    E --> F[消费前再校验 TTL]
+```
+
+```ts
+declare const statusInput: protocol.SemanticFacadeInput<protocol.SemanticStatusParams>;
+const proof = await client.credential.status(statusInput, {
+  serviceAid: semanticServiceAid,
+});
+declare const crlInput: protocol.SemanticFacadeInput<protocol.SemanticRevocationListParams>;
+const crlPage = await client.credential.revocations(crlInput, {
+  serviceAid: semanticServiceAid,
+});
+```
+
+CRL 按 authority、CID、audience／scope 隔离，整页验真后保存事件与游标。普通分页以 `''` 结束，语义分页以 `null` 结束。普通长连接认证／重连后立即 fresh 同步撤销，之后按小时补拉；short 跳过后台扫描，Python fresh 贯通各页。
+
+| 持久项 | metadata key |
+| --- | --- |
+| 普通撤销快照 | `credential_revocations_v1` |
+| Python 语义状态 | `semantic_credential_state_v1` |
+| TS 语义状态 | `semantic_credentials_v1` |
+| JS 语义状态 | `semantic_credential_state_v1` |
+| Go 语义状态 | `semantic_revocations_v1` |
+
+保存已观察状态序号、撤销、scope 游标、请求／nonce 绑定与 allocation 状态。身份、设备、slot 及连接代际隔离异步结果；重建 Facade 后，旧证明须重新取得有效本地计时依据。移植时对应各端已有状态适配，不将单调计时起点当跨进程时间戳保存。
+
+### 4.4 消息证据
+
+```mermaid
+flowchart LR
+    A[原始加密信封和明文字节] --> B[归档与 EvidenceRef]
+    B --> C[原收件身份与密钥]
+    C --> D[历史发送者证书和签名]
+    D --> E[群 epoch 及收件 Merkle 证明]
+    E --> F[VerifiedBody 与正文摘要]
+```
+
+```ts
+declare const envelopeBytes: Uint8Array;
+declare const received: Parameters<typeof client.credential.archiveMessage>[1];
+const archive = await client.credential.archiveMessage(envelopeBytes, received);
+const envelopeRef = await client.credential.createEvidenceRef(
+  envelopeBytes, 'aun-e2ee-v2-envelope-raw/1',
+);
+declare const messageContext: protocol.SemanticMessageVerificationContext;
+const body = await client.credential.verifyMessageBody(signedOriginal, messageContext);
+```
+
+实时消息的 `_semantic_evidence` 保留原 envelope／payload 字节；`message_ref` 验证使用可信解析器、原签署时间和证书指纹、原收件身份及群收件证明。附件按原摘要解析，资源定位见[消息证据适配](凭证与组织服务SDK开发与移植指南.md#45-消息证据适配)。
+
+### 4.5 UsageRef 与账本协调
+
+```mermaid
+flowchart TD
+    A[已验凭证和 UsageContract] --> B[可信 allocation 与在线状态]
+    B --> C[宿主预留并执行]
+    C --> D{结果}
+    D -->|明确成功或失败| E[宿主原子结算]
+    D -->|unknown| F[按原 request_id 核对]
+    F --> E
+    E --> G[保存执行回执]
+```
+
+`prepareUsage/commitUsage/abortUsage` 分别映射 `revise` 的 usage_prepare／usage_commit／usage_abort，返回 `UsageTransitionReceipt`。候选修订、UsageRef、transition_id、fence、checkpoint、allocation closure 与 acceptance 保持同一协调关系。
+
+```ts
+declare const prepareInput: protocol.SemanticUsageInput<'usage_prepare'>;
+const prepared = await client.credential.prepareUsage(prepareInput, {
+  serviceAid: semanticServiceAid,
+});
+declare const commitInput: protocol.SemanticUsageInput<'usage_commit'>;
+const committed = await client.credential.commitUsage(commitInput, {
+  serviceAid: semanticServiceAid,
+});
+```
+
+中断后用原 transition_id 查询协调状态，按返回结果继续 commit／abort；业务效果、预留、Unknown 核对和账本原子性由宿主负责。完整材料与恢复契约见[额度与 UsageRef](凭证与组织服务SDK开发与移植指南.md#48-额度与-usageref-切换)。
+
+## 5. 组织实体、首次名片与转让恢复
+
+组织成员保留双签 binding、成员 CAP、登记授权和服务回执；成员及代表当前态接入普通完整 Verify。组织身份操作使用本端高层编排，保存 checkpoint 后再推进后续阶段。
+
+```mermaid
+flowchart TD
+    A[创建组织并保存本次 active 结果] --> B[读取名片 authority]
+    B -->|已有投影| C[按当前权威与 CAS 更新]
+    B -->|HTTP 404| D[核对本次组织及当前 owner]
+    D --> E[fresh 获取实体证书并比对指纹]
+    E --> F[按初始条件上传名片]
+    C --> G[上传完成后清 creation checkpoint]
+    F --> G
+```
+
+```ts
+import type { AIDStore } from '../../ts/src/aid-store.js';
+declare const aidStore: AIDStore;
+declare const orgCreateParams: Parameters<AUNClient['createOrg']>[0];
+const organization = await client.createOrg(orgCreateParams, { aidStore });
+declare const orgTransferParams: Parameters<AUNClient['completeOrgTransfer']>[0];
+const transferredOrganization = await client.completeOrgTransfer(orgTransferParams, { aidStore });
+```
+
+初始 fallback 仅用于 NS 明确缺少投影且本次 org_id／owner_aid／active 状态匹配。完成转让还核对本次 transfer_id，采用已确认的新 owner 上下文；两条路径均 fresh 获取当前组织证书并核对指纹。
+
+```mermaid
+flowchart LR
+    A[验证双方成员材料] --> B[保存新密钥并 rekey]
+    B --> C[导入证书并替换成员凭证]
+    C --> D[finalize 转让]
+    D --> E[更新新 owner 名片]
+    E --> F[保存 completed 并清临时密钥]
+```
+
+重试原 pending 名片时核对当前身份、owner 与原 CAS 条件。TS 首次群名片同样使用本次返回证书和 owner 上下文。既有 Ownership 继续采用文件／NS 当次执行流程，通用消息、凭证与组织的 checkpoint 按各自职责保留。
+
+## 6. Gateway 迁移与可靠交付
+
+### 6.1 迁移状态与恢复顺序
+
+协商 `gateway_migrate_v1` 后接收 `gateway.migrate`。通知核对 issuer、AID、device、slot、connection_id、递增 revision、migration_id，以及未来 300 秒内的有效期；目标为同 issuer 的 `wss:` 地址和 `/aun` 路径。
+
+```mermaid
+flowchart TD
+    A[ready 收到合法迁移通知] --> B[standby 并暂停新 RPC 与后台任务]
+    B --> C[最多排空 5 秒并保存已提交水位]
+    C --> D[关闭旧连接并清 inline ACK 状态]
+    D --> E[优先目标 Gateway 再认证]
+    E -->|失败且仍在期限内| F[fresh 发现并按配置退避]
+    F --> E
+    E -->|认证成功且连接有效| G[ready 解除门控]
+    G --> H[恢复后台任务和离线补拉]
+```
+
+```ts
+declare const observeMigration: (payload: EventPayload) => void;
+client.on('gateway.migrate', (payload) => {
+  observeMigration(payload);
+});
+```
+
+迁移由 SDK 驱动，应用订阅事件观察进度。显式 connect／disconnect／close 接管或终止迁移；旧 transport、reader 与重连回调按代际隔离。迁移中调用沿现有错误类型返回，业务写操作沿原幂等键核对结果。
+
+### 6.2 交付提交与心跳
+
+```mermaid
+flowchart LR
+    A[收页并验证覆盖证明] --> B[释放网络 Gate]
+    B --> C[解密和内部协议处理]
+    C --> D[等待应用处理器事务]
+    D --> E[复核身份代际并可靠保存水位]
+    E --> F[仅 ACK 已提交前缀]
+```
+
+```ts
+declare const commitBatch: (payload: EventPayload) => Promise<void>;
+client.on('message.batch', async (batch) => {
+  await commitBatch(batch);
+});
+```
+
+宿主事务须可重放；处理器 Promise 完成才推进提交水位。网络 Gate 按页释放，应用处理及退避独立；batch／single 每页固定，保留 peer namespace、容量、覆盖证明及已提交前缀契约，见[0.5.24 可靠交付](0.5.24-SDK开发与移植指南.md#3-peer-同步batch持久提交与退避)。
+
+Python、Node TS、Go 结合入站活跃度处理心跳。Node 每 30 秒 Ping，10 秒静默超时，连续三次静默超时终止连接；Pong 或普通消息清零，Ping 错误立即终止。浏览器依赖宿主 WebSocket 生命周期。
+
+## 7. 存储、信任根与语言适配
+
+| 端 | 0.5.27 实现要求 |
+| --- | --- |
+| TS Node | LocalIdentityStore／LocalTokenStore 初始化时排他补入缺失内置根，保留已有根；npm 打包白名单与运行时初始化分别验收 |
+| Go | AuthFlow 用内置根初始化空信任目录，保留已有本地根配置 |
+| JS 浏览器 | IndexedDB 初始化事务提交后发布 DB；versionchange／close 隔离旧 open promise；缺少时补内置根 |
+| JS 查询缓存 | 缓存键移除本地 signAs／sign_as，发往 loader 的参数保持原值 |
+| Python | 名片下载从持久 load_record 取得当前观察；普通撤销 fresh 标记贯通分页 |
+
+文件端采用路径与文件事务适配，浏览器采用 IndexedDB／WebCrypto；四端共享协议和 wire。公开异步约定保持 Python async、TS／JS Promise、Go context／error。外部地址使用 `{svc}.{issuer}`，如 `credential.agentid.cn`。
+
+## 8. 回归与场景对照
+
+按协议向量、Facade、持久恢复、真实场景顺序验收；执行测试首失败停止，修复后从该用例继续。以下为入口清单，实际通过范围以各批记录为准。
+
+| 契约 | 源码／回归入口 |
+| --- | --- |
+| 严格 JSON、签名及时间 | [TS 协议](../../ts/src/semantic-protocol.ts)、[协议测试](../../ts/tests/conformance/semantic_protocol.test.ts) |
+| 语义管理、状态及恢复 | [TS Facade](../../ts/src/semantic-facade.ts)、[Facade 测试](../../ts/tests/unit/semantic-facade.test.ts) |
+| 普通 Verify、成员及代表 | [org-protocol](../../ts/src/org-protocol.ts)、[组织测试](../../ts/tests/unit/org-facade.test.ts) |
+| 迁移、可靠交付及实体编排 | [client](../../ts/src/client.ts)、[client 测试](../../ts/tests/unit/client.test.ts)、[transport 测试](../../ts/tests/unit/transport.test.ts) |
+| 四端共同场景 | [场景清单](../../examples/semantic-credential/scenarios.json)、[示例说明](../../examples/semantic-credential/示例使用指南.md)、[跨 SDK 运行器](../../tests/cross-sdk/runner/run_cross_sdk_e2e.py) |
+| 宿主账本与 Unknown | [参考账本](../../examples/semantic-credential/reference-host/ledger.py)、[宿主实现](../../examples/semantic-credential/reference-host/host.py) |
+| CLI 与协议接口 | [CLI 专题](../cli/凭证与组织服务CLI开发与使用指南.md)、[凭证 RPC](09-凭证服务RPC手册.md)、[组织 RPC](09-组织服务RPC手册.md) |
+
+功能增量与各语言差异按 [parity 0.5.27](../../python/CHANGES_FOR_PARITY.md#v0527--相对于-v0525-基线的变更未发布)逐项对齐。本次专题整理采用静态文档与示例校验，发布包验收使用相应版本产物另记执行结果。

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` |