@agentunion/fastaun 0.5.28 → 0.5.29

package/_packed_docs/cli//345/207/255/350/257/201/344/270/216/347/273/204/347/273/207/346/234/215/345/212/241CLI/345/274/200/345/217/221/344/270/216/344/275/277/347/224/250/346/214/207/345/215/227.md

@@ -0,0 +1,869 @@
+# 凭证与组织服务 CLI 开发与使用指南
+
+以当前仓库的 AUN CLI 为基准，示例统一使用 Node TS。CLI 实现位于 Python SDK；各节 CLI 与直接 SDK 示例是两种接入方式，选择其中一种执行。安装与 profile 配置见 [CLI 手册](CLI手册.md)。
+
+| 凭证模式 | 版本与验收 |
+| --- | --- |
+| 原结构化 | `aun-cap/1`；非空 cap，按能力与 constraints 确定性验收 |
+| 纯语义 | `aun-cap/semantic-1`；cap=[]，正文、确认元数据与业务复核 |
+| 混合 | `aun-cap/semantic-1`；非空 cap＋授权正文，两部分限制取交集 |
+
+三种模式保留各自原件与验证流程；普通结构化接入见 §4.1，语义接入见 §4.2—§7。
+
+## 1. 调用入口与材料
+
+```mermaid
+flowchart LR
+    A[TS 运行器：参数数组与材料文件] --> B[AUN CLI：profile、输入、输出]
+    B --> C[SDK：签名、请求准备、验真与持久恢复]
+    C --> D[Gateway service-plane]
+    D --> E[Credential／Org 服务]
+    F[直接集成的 TS 应用] --> G[TS SDK 的相同业务流程]
+    G --> D
+```
+
+| 准备项 | 本文约定 |
+| --- | --- |
+| 环境 | CN；服务为 `credential.agentid.cn`、`org.agentid.cn` |
+| 身份 | `cn-issuer` 签发，`cn-delegate` 受托签发，`cn-confirmer` 确认，`cn-owner` 管理组织，`cn-member` 入组，`cn-target` 接受转让；`cn` 为日常管理 profile |
+| 材料目录 | 每次流程使用独立工作目录，先保存输入，再调用；已保存输入用于原请求续跑 |
+| 可信输入 | authority、固定版本 policy、证书与根证书；验收端另从认证收件通道取得 authenticated 和业务事实 |
+| SDK 示例 | client／ownerClient／memberClient／targetClient 为对应角色已连接客户端；signer、持久 store 与业务端口由应用提供 |
+
+```ts
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readFile, writeFile } from 'node:fs/promises';
+import { randomBytes, randomUUID, X509Certificate } from 'node:crypto';
+import { semanticProtocol as sp } from '@agentunion/fastaun';
+const execFileAsync = promisify(execFile);
+const executable = process.platform === 'win32' ? 'aun.exe' : 'aun';
+const profile = 'cn';
+```
+
+```ts
+async function aun<T = unknown>(args: string[], selectedProfile = profile): Promise<T> {
+  const { stdout } = await execFileAsync(executable,
+    ['--profile', selectedProfile, '--json', ...args],
+    { encoding: 'utf8', shell: false, env: { ...process.env, PYTHONUTF8: '1' } });
+  return JSON.parse(stdout) as T;
+}
+async function saveJson(path: string, value: unknown): Promise<void> {
+  await writeFile(path, JSON.stringify(value), { encoding: 'utf8', flag: 'wx' });
+}
+```
+
+Windows 使用安装后的 `aun.exe`，Linux／macOS 使用 `aun`；也可将 executable 指向实际安装位置。帮助输出为文本，按文本读取。
+
+```ts
+const identity = await aun(['whoami']);
+const help = await execFileAsync(executable, ['credential', '--help'], { encoding: 'utf8' });
+console.log(help.stdout);
+```
+
+## 2. 参数、输出与原字节
+
+```mermaid
+flowchart LR
+    A[TS 对象] --> B[UTF-8 JSON 输入文件]
+    B --> C[params／context 使用 @文件]
+    C --> D{CLI 结果}
+    D -->|退出 0| E[stdout：原始结果 JSON]
+    D -->|非 0| F[stderr：结构化错误 JSON]
+    E --> G[保存结果与本阶段进度]
+```
+
+| 入口 | 参数规则 |
+| --- | --- |
+| `credential` | `--params` 可放命令组或具体命令后，内容为严格 JSON 对象 |
+| `credential --target <service-aid>` | 选择语义管理权威；放具体命令前，转交 SDK 的 target |
+| `credential … --context` | 验真上下文；支持 JSON 或 `@UTF-8文件` |
+| `org --params <JSON/@文件> …` | 放具体子命令前；用于完整业务材料、credentials 或已准备请求 |
+| `org --params` 含 request_binding／client_signature／signature | 按完整请求透传；必填命令行位置参数仍须填写，并与材料一致 |
+| `credential … --output <新文件>` | 独占创建；SignedJsonBytes 保存解码后的签名 JSON 原字节，其他结果保存 canonical JSON |
+
+stdout 中的签名结果仍是 `{bytes_base64}`。从签名原件文件恢复该包装：
+
+```ts
+const savedOriginal: sp.SignedJsonBytes = {
+  bytes_base64: (await readFile('original.json')).toString('base64'),
+};
+await saveJson('saved-original-wrapper.json', savedOriginal);
+```
+
+登记的 original／metadata 使用原字节包装；lineage 的 credential／metadata 使用解码后的对象。原件文件按原字节读取，后续摘要使用 SDK canonical 规则。
+
+## 3. 凭证命令地图
+
+以下 23 个命令均位于根级 `credential`；组织成员凭证管理位于 `org credential`。
+
+| 场景 | CLI 命令 | 对应 SDK 能力 |
+| --- | --- | --- |
+| 普通 CAP | `create`、`current` | 创建已签 CAP；读取本地管理记录及续期 successor |
+| 登记与状态 | `register`、`get`、`status`、`revoke` | 普通／语义按 SDK 字段分流；get 为语义修订读取 |
+| 修订与 CRL | `revise`、`revocations`、`revocation-list` | 语义 CAS／签名分页；revocation-list 同时保留普通列表入口 |
+| UsageRef 协调 | `usage-prepare`、`usage-commit`、`usage-abort` | prepareUsage／commitUsage／abortUsage |
+| 语义签名 | `sign`、`metadata-sign`、`allocation-sign`、`usage-record-sign` | signCredential／signMetadata／signAllocation／signUsageRecord |
+| 验真 | `verify` | 普通 structured 完整验收；语义原件、metadata、回执、状态、包或配套对象验真 |
+| 出示与验收 | `package`、`request`、`request-verify`、`decision-input` | 构包、业务请求、请求验真、模型输入 |
+| 消息证据 | `evidence-export`、`evidence-verify` | 原字节生成 EvidenceRef；从凭证验真正文 |
+
+| `verify --kind` | 参数补充 |
+| --- | --- |
+| `structured` | 普通 CAP＋实际请求 context；CLI 经 SDK 获取各层当前状态与可信证书，调用完整 Verify |
+| `original`／`metadata`／`receipt`／`status`／`package` | 对应语义对象与可信 context |
+| `allocation`／`allocation-status` | 对应签名域验真；业务消费另验分配关系、查询绑定与在线状态 |
+| `usage-record` | 另传 `--domain` |
+
+`usage-record-sign --kind` 与 `verify --kind usage-record --domain` 使用这些域：`usage-allocation`、`allocation-status`、`semantic-crl`、`usage-transition`、`usage-checkpoint`、`usage-acceptance`、`ledger-abort`。
+
+签名命令加载所选 profile 的真实私钥；非 online 的语义 verify 在 certificates＋trusted_roots 齐备时可免认证连接。structured Verify、create／current 及 package／request／evidence-export 使用 CLI 的认证会话。
+
+## 4. 凭证签发、登记与出示
+
+### 4.1 普通结构化凭证
+
+```mermaid
+flowchart LR
+    A[issuer 创建根 CAP 与非空约束] --> B[受托方签子 CAP，逐层收窄]
+    B --> C[register：完整原件与请求绑定]
+    C --> D[核对登记回执，交付 holder]
+    D --> E[真实业务请求与认证 actor]
+    E --> F[verify structured：强状态、签名、父链、能力与请求]
+    F --> G[幂等执行业务]
+    G --> H[撤销、CRL 同步与 current 恢复]
+```
+
+#### 4.1.1 根凭证、约束与委托收窄
+
+```ts
+const ordinaryServiceAid = 'credential.agentid.cn';
+await saveJson('cap-input.json', { sub: delegateAid, aud: [businessAid], delegate: true,
+  key_version: issuerSigner.certFingerprint, cap: [{ ns: 'files', action: 'read',
+    resource: '/reports', constraints: [{ type: 'max_value', field: 'rows', value: 100 }] }] });
+const cap = await aun<sp.StructuredCredential>(['credential', 'create', '--params', '@cap-input.json'], 'cn-issuer');
+await saveJson('cap.json', cap);
+```
+
+根凭证 sub 为受托签发者；子凭证由该身份签署，行数上限从 100 收窄为 10：
+
+```ts
+const childExpiry = Math.min(cap.exp,
+  Math.trunc(new Date(new X509Certificate(delegateSigner.certPem).validTo).getTime() / 1000));
+await saveJson('child-input.json', { sub: holderAid, aud: [businessAid],
+  parent: cap.cid, proof_chain: [cap], delegation_depth: 1, delegate: false,
+  nbf: Math.max(cap.nbf, Math.trunc(Date.now() / 1000)), exp: childExpiry,
+  key_version: delegateSigner.certFingerprint, cap: [{ ns: 'files', action: 'read',
+    resource: '/reports', constraints: [{ type: 'max_value', field: 'rows', value: 10 }] }] });
+const child = await aun<sp.StructuredCredential>([
+  'credential', 'create', '--params', '@child-input.json'], 'cn-delegate');
+await saveJson('child.json', child);
+```
+
+每层保持签发者＝父 holder，受众、期限、能力和约束逐层收窄，最大深度 8。成员角色 CAP 使用组织流程生成。
+
+#### 4.1.2 普通请求绑定、登记与回执
+
+以下使用仓库的真实绑定 helper；npm 应用可按 [SDK 移植指南 §5.4](../sdk/凭证与组织服务SDK开发与移植指南.md#54-credential-request-binding) 实现相同适配：
+
+```ts
+import { buildRequestBinding } from '../../ts/src/org-protocol.js';
+function ordinaryInput(method: string, target: string, credentialCid: string,
+  fields: Record<string, unknown>) {
+  const now = Math.trunc(Date.now() / 1000);
+  const input = { ...fields, request_id: randomUUID(), nonce: randomBytes(32).toString('base64url') };
+  return { ...input, request_binding: buildRequestBinding(method, target, input, credentialCid,
+    input.nonce, input.request_id, now, now + 300) };
+}
+```
+
+```ts
+const rootRegistration = ordinaryInput('credential.register', ordinaryServiceAid, cap.cid,
+  { registrar_aid: issuerAid, credential: cap });
+await saveJson('cap-registration.json', rootRegistration);
+const capRegistration = await aun<{ registrationReceipt: unknown }>([
+  'credential', 'register', '--params', '@cap-registration.json'], 'cn-issuer');
+await saveJson('cap-registration-result.json', capRegistration);
+```
+
+```ts
+const childRegistration = ordinaryInput('credential.register', ordinaryServiceAid, child.cid,
+  { registrar_aid: delegateAid, credential: child, proof_chain: [cap] });
+await saveJson('child-registration.json', childRegistration);
+const childRegistered = await aun<{ registrationReceipt: unknown }>([
+  'credential', 'register', '--params', '@child-registration.json'], 'cn-delegate');
+client.credential.verifyRegistrationReceipt(childRegistered.registrationReceipt, child,
+  childRegistration, resolveCertificate, ordinaryServiceAid);
+```
+
+resolveCertificate 来自已验信任的证书缓存。转交登记的 issuer 签名授权构造见 [SDK 应用指南 §3](../sdk/凭证与组织服务SDK应用集成指南.md#3-结构化凭证接入)。普通接口字段见 [RPC 手册](../sdk/09-凭证服务RPC手册.md#credentialregister)。
+
+#### 4.1.3 状态查询与完整 Verify
+
+```mermaid
+sequenceDiagram
+    participant B as 业务验收端／CLI
+    participant C as Credential 权威
+    participant V as SDK 完整 Verify
+    B->>C: 每层新 status 请求：CID、独立 ID／nonce 与绑定
+    C-->>B: 签名 proof：全文 hash、状态、原查询及时间窗
+    B->>B: 验服务信任、签名、响应 target＝查询者 AID
+    B->>V: 强 proof 缓存＋真实业务请求与 actor
+    V-->>B: 签名、父链、约束与请求全部通过
+```
+
+单独查询并保存普通 proof：
+
+```ts
+const ordinaryStatusInput = ordinaryInput('credential.status', ordinaryServiceAid, child.cid,
+  { credential_cid: child.cid, include_chain: true });
+await saveJson('ordinary-status-input.json', ordinaryStatusInput);
+const ordinaryProof = await aun(['credential', 'status', '--params', '@ordinary-status-input.json']);
+await saveJson('ordinary-status-proof.json', ordinaryProof);
+```
+
+业务验收端从实际认证请求生成 context；rows=5 满足子凭证上限 10：
+
+```ts
+const operation = ordinaryInput('files.read', businessAid, child.cid, { report: reportId, rows: 5 });
+await saveJson('ordinary-operation.json', operation);
+const structuredContext = { audience: businessAid, subject: holderAid, root_issuer: issuerAid,
+  actor: authentication.actor, ns: 'files', action: 'read', resource: '/reports',
+  method: 'files.read', target: businessAid, params: operation, request_id: operation.request_id,
+  nonce: operation.nonce, request_binding: operation.request_binding,
+  credential_services: { [cap.cid]: ordinaryServiceAid, [child.cid]: ordinaryServiceAid } };
+await saveJson('structured-context.json', structuredContext);
+```
+
+```ts
+const structuredReport = await aun(['credential', 'verify', '--kind', 'structured',
+  '--params', '@child.json', '--context', '@structured-context.json']);
+await saveJson('structured-verification-result.json', structuredReport);
+```
+
+`verify --kind structured` 使用认证会话，经 SDK 为每层重新获取当前强 proof 和可信历史证书，再同步执行普通完整 Verify。context 传普通 snake_case 字段，业务 actor 取认证通道；服务映射取本地可信配置。
+
+CLI 提供通用 CAP／委托链完整验真；成员当前状态、Ownership／actor 状态及 rate_limit 事务通过应用的 SDK 端口接入。完整 Verify 按所需端口校验。普通 proof 的签验和同步 resolver 适配见 [SDK 移植指南 §6](../sdk/凭证与组织服务SDK开发与移植指南.md#6-facade-和-rpc-映射)。
+
+#### 4.1.4 撤销、分页与持久进度
+
+```mermaid
+flowchart LR
+    A[issuer 按原 CID 与绑定 revoke] --> B[确认 revoked 与原请求结果]
+    B --> C[revocation-list：沿保存 cursor／since_event_seq]
+    C --> D[验权威签名、原查询与窗口]
+    D --> E[原子合并事件与进度]
+    E -->|next_cursor 非空| C
+    E -->|next_cursor 为空| F[保存连续事件水位]
+```
+
+```ts
+const ordinaryRevokeInput = ordinaryInput('credential.revoke', ordinaryServiceAid, child.cid,
+  { registrar_aid: delegateAid, credential_cid: child.cid, reason_code: 'grant_withdrawn' });
+await saveJson('ordinary-revoke-input.json', ordinaryRevokeInput);
+const ordinaryRevoked = await aun(['credential', 'revoke', '--params', '@ordinary-revoke-input.json'], 'cn-delegate');
+await saveJson('ordinary-revoke-result.json', ordinaryRevoked);
+```
+
+app.verifyOrdinaryCrl／commitOrdinaryCrl 按移植指南 §6 实现验签及原子合并；分页前恢复上次进度：
+
+```ts
+type OrdinaryCrlPage = { events: Array<{ event_seq: number; cid: string }>; next_cursor: string };
+let ordinaryCursor = restoredCrlCursor || String(ordinarySince);
+```
+
+```ts
+do {
+  const pageInput = ordinaryInput('credential.revocationList', ordinaryServiceAid, '',
+    { issuer_aid: delegateAid, since_event_seq: ordinarySince, cursor: ordinaryCursor, limit: 100 });
+  const inputFile = 'ordinary-crl-' + pageInput.request_id + '.json';
+  await saveJson(inputFile, pageInput);
+  const rawPage = await aun<OrdinaryCrlPage>(['credential', 'revocation-list', '--params', '@' + inputFile]);
+  const page = await app.verifyOrdinaryCrl(rawPage, pageInput, ordinaryServiceAid);
+  await app.commitOrdinaryCrl(page);
+  ordinaryCursor = page.next_cursor;
+} while (ordinaryCursor);
+```
+
+普通 CRL 的结束游标为空字符串；语义分页使用 null。记录保存 authority、issuer、事件最大序号、cursor 与完整签名材料，事件与进度同事务提交。
+
+#### 4.1.5 续期读取与恢复
+
+```ts
+await saveJson('current-input.json', { cid: cap.cid });
+const managed = await aun(['credential', 'current', '--params', '@current-input.json'], 'cn-issuer');
+```
+
+根示例省略 exp，SDK 按签署证书截止时间签发并管理。current 在相同 profile 的持久 store 中沿 successor_cid 读取最新记录。恢复使用已保存的原输入与阶段；成员续期见 §9.3，当前状态和业务约束在使用前重新验收。
+
+### 4.2 语义原件与确认
+
+```mermaid
+sequenceDiagram
+    participant A as 签发者 profile
+    participant K as 确认者 profile
+    participant R as 登记权威
+    A->>A: sign：正文与显式上限
+    A->>K: 原字节原件与确认依据
+    K->>K: metadata-sign：确定主体、受众、期限与次数
+    K->>R: register：原件、metadata、lineage_evidence、authority
+    R-->>K: audiences、revision、registration_receipt
+```
+
+原件与 metadata 字段的 TS 构造见 [SDK 应用指南 §4.2](../sdk/凭证与组织服务SDK应用集成指南.md#42-签发确认与登记e02e05e18)：纯语义 cap=[]，混合凭证附结构化 cap；有限次数同时提供 UsageContract。
+
+```ts
+await saveJson('original-input.json', textGrant);
+const original = await aun<sp.SignedJsonBytes>(['credential', 'sign',
+  '--params', '@original-input.json', '--output', 'original.json'], 'cn-issuer');
+await saveJson('metadata-input.json', metadataInput);
+const metadata = await aun<sp.SignedJsonBytes>(['credential', 'metadata-sign',
+  '--params', '@metadata-input.json', '--output', 'metadata.json'], 'cn-confirmer');
+```
+
+```ts
+const management = (credential_cid: string) => ({
+  request_id: randomUUID(), nonce: randomBytes(32).toString('base64url'),
+  credential_cid, authority,
+});
+await saveJson('registration.json', { ...management(cid), original,
+  metadata: [metadata], lineage_evidence: [] });
+const registered = await aun<sp.SemanticRegisterResult>([
+  'credential', 'register', '--params', '@registration.json']);
+await saveJson('registration-result.json', registered);
+```
+
+派生凭证的 lineage_evidence 按 root→直接 parent 保存完整材料；签发权与确认权使用各自固定依据。
+
+### 4.3 当前修订、状态与业务请求
+
+```mermaid
+flowchart LR
+    A[get 当前 head 与修订] --> B[status：bounded 初始快照]
+    B --> C[package：root 到 leaf]
+    C --> D[request：固定业务 hash]
+    D --> E[认证通道交付业务方]
+    E --> F[验收端刷新 online 状态]
+```
+
+```ts
+await saveJson('get-input.json', { ...management(cid), audience: businessAid });
+const current = await aun<sp.SemanticGetResult>(['credential', 'get', '--params', '@get-input.json']);
+if (current.kind !== 'revision' || current.head.state !== 'current') throw new Error('需要当前修订');
+await saveJson('status-input.json', { ...management(cid), audience: businessAid,
+  expected_revision: current.revision, policy: { mode: 'bounded', max_staleness_seconds: 60 } });
+const status = await aun<sp.CredentialStatusProof>(['credential', 'status', '--params', '@status-input.json']);
+```
+
+```ts
+const lineage: sp.CredentialLineageEntry[] = [{
+  credential: sp.decodeSignedJson(current.original) as sp.SemanticCredential,
+  metadata: sp.decodeSignedJson(current.metadata) as sp.RegistrationMetadata,
+  registration_receipt: current.registration_receipt, status,
+}];
+await saveJson('package-input.json', { lineage });
+const grant = await aun<sp.CredentialPackage>(['credential', 'package', '--params', '@package-input.json']);
+```
+
+```ts
+await saveJson('request-input.json', { request_id: randomUUID(),
+  nonce: randomBytes(32).toString('base64url'), actor: holderAid, sub: holderAid,
+  target: businessAid, aud: businessAid, ns: 'files', action: 'read',
+  resource: '/reports', params: { report: reportId },
+  expires_at: Math.trunc(Date.now() / 1000) + 300, grant });
+const request = await aun<sp.AuthorizationRequest>(['credential', 'request', '--params', '@request-input.json']);
+await saveJson('business-request.json', request);
+```
+
+多跳逐层取材料。旧根使用普通凭证完整验证及原权威强状态；代表出示中 actor 为实际发送者，sub 为叶 holder。
+
+## 5. 验真、online 与业务验收
+
+### 5.1 CLI context
+
+```mermaid
+flowchart TD
+    A[真实认证收件与可信配置] --> B[构造 context]
+    B --> C[request-verify]
+    C --> D[CLI 生成 query nonce 与单调起点]
+    D --> E[按各 CID 权威刷新 online status]
+    E --> F[验包、请求绑定与显式 cap]
+    F --> G[正文验真与 decision-input]
+    G --> H[业务三态决策、后置复核、额度与幂等执行]
+```
+
+| CLI context 字段 | 来源与键 |
+| --- | --- |
+| `authenticated` | `{actor,service_aid,authentication_ref}`，取真实收件认证结果 |
+| `credential_signers` | 完整原件 `digest(original)` → 原签署者 AID |
+| `credential_services` | CID → 可信登记服务 AID |
+| `certificates` | `signature.cert_fingerprint` → PEM，含各层历史签名者 |
+| `trusted_roots` | 本地信任根 PEM 数组 |
+| `audience`／`authority` | 业务受众及可信状态查询管理依据 |
+| `policy` | online，或 bounded＋max_staleness_seconds |
+
+以下为单层 context；多跳补齐全部签名者与服务映射：
+
+```ts
+const cliContext = { authenticated: authentication, audience: businessAid,
+  credential_signers: { [sp.digest(sp.decodeSignedJson(original))]: issuerAid },
+  credential_services: { [cid]: 'credential.agentid.cn' },
+  certificates, trusted_roots: trustedRoots, authority, policy: { mode: 'online' } };
+await saveJson('verification-context.json', cliContext);
+const requestReport = await aun(['credential', 'request-verify',
+  '--params', '@business-request.json', '--context', '@verification-context.json']);
+```
+
+online 的 query 与单调时间由当前 CLI 进程生成，状态绑定同一业务 request_hash。状态刷新保留同修订的业务 hash；绝对窗口及最大已观察 state_seq 仍需校验。bounded 使用 1—300 秒 TTL，跨进程恢复后重新取状态。
+
+```ts
+await saveJson('body-input.json', { credential: original, context: cliMessageContext });
+const body = await aun<sp.VerifiedBody>(['credential', 'evidence-verify', '--params', '@body-input.json']);
+const { credential_hash, body_hash, text, evidence_hashes, payload_hash } = body;
+await saveJson('decision-input.json', { request,
+  bodies: [{ credential_hash, body_hash, text, evidence_hashes, payload_hash }], facts, policy });
+const decisionInput = await aun<sp.DecisionInput>(['credential', 'decision-input',
+  '--params', '@decision-input.json', '--context', '@verification-context.json']);
+```
+
+多跳收集全部适用正文。cliMessageContext 为 Python CLI 的 JSON 上下文；message_ref 使用原收件 profile 及 SDK 已持久化的解密材料。远程证据 resolver 等应用回调通过 SDK 接入。
+
+### 5.2 TS 开发时的完整调用顺序
+
+```mermaid
+flowchart LR
+    A[verifyPackage] --> B[verifyRequest]
+    B --> C[逐层 verifyMessageBody]
+    C --> D[buildDecisionInput]
+    D --> E[模型 allow／deny／indeterminate]
+    E -->|allow| F[后置复核与新鲜状态]
+    F --> G[事务预留、幂等执行、持久结果]
+```
+
+直接 SDK 路径在本进程刷新状态，并保留查询计时；packageContext.serviceFor 提供每层可信权威：
+
+```ts
+const sdkRequest = structuredClone(request);
+const query = { request_hash: sdkRequest.request_binding.request_hash,
+  nonce: randomBytes(32).toString('base64url') };
+const queryStarted = performance.now();
+```
+
+```ts
+for (const entry of sdkRequest.grant.lineage) {
+  if (!('metadata' in entry)) continue;
+  const expectedRevision = { cid: entry.credential.cid, original_hash: entry.metadata.original_hash,
+    metadata_hash: sp.digest(entry.metadata), metadata_version: entry.metadata.version };
+  entry.status = await client.credential.status({ ...management(entry.credential.cid),
+    audience: sdkRequest.aud, expected_revision: expectedRevision, policy: { mode: 'online' }, query,
+  }, { serviceAid: await packageContext.serviceFor!(entry.credential.cid), verificationContext: trust });
+}
+```
+
+```ts
+await client.credential.verifyPackage(sdkRequest.grant, { ...packageContext,
+  statePolicy: { mode: 'online' }, elapsedSeconds: (performance.now() - queryStarted) / 1000,
+  queries: Object.fromEntries(sdkRequest.grant.lineage.map(entry => [entry.credential.cid, query])) });
+await client.credential.verifyRequest(sdkRequest, authentication, {
+  representedActor: app.verifyRepresentation,
+});
+```
+
+```ts
+const bodies: sp.VerifiedBody[] = [];
+for (const entry of sdkRequest.grant.lineage) {
+  if ('metadata' in entry) bodies.push(await client.credential.verifyMessageBody(
+    entry.credential, await app.messageContext(entry)));
+}
+const input = await client.credential.buildDecisionInput(sdkRequest, bodies, facts, policy);
+```
+
+TS verifyRequest 返回的 required 仍含包验真与业务接受职责；Python CLI request-verify 已组合包验真，decision-input 还会重新验请求及正文。应用完成签发／确认权、结构化范围、可信事实、模型三态、后置条件和额度账本检查，见 [SDK 应用指南 §4.6—§4.8](../sdk/凭证与组织服务SDK应用集成指南.md#46-业务验收与模型三态e16e18e23e25e34)。
+
+## 6. 消息证据与分配证明
+
+```mermaid
+flowchart LR
+    A[认证收件的原始 envelope 与 received] --> B[SDK archiveMessage 保存原字节]
+    B --> C[evidence-export 生成 inline／aun_ref]
+    C --> D[签署引用该证据的凭证]
+    D --> E[evidence-verify 取得 VerifiedBody]
+    E --> F[全部适用正文进入 DecisionInput]
+```
+
+```ts
+const archive = await client.credential.archiveMessage(rawEnvelope, received);
+await writeFile('envelope.bin', archive.envelope_bytes, { flag: 'wx' });
+await app.archive.put(archiveLocator, archive.envelope_bytes);
+await saveJson('evidence-input.json', { bytes_base64: (await readFile('envelope.bin')).toString('base64'),
+  profile: 'aun-e2ee-v2-envelope-raw/1', locator: archiveLocator });
+const evidence = await aun<sp.EvidenceRef>(['credential', 'evidence-export', '--params', '@evidence-input.json']);
+```
+
+locator 指向已保存的对象版本与 ACL；省略 locator 生成 inline。evidence-verify 输入凭证或 `{credential,context}`，输出正文验真结果。P2P、群收件集合／Merkle 证明、上下文及附件材料见 [SDK 消息流程](../sdk/凭证与组织服务SDK应用集成指南.md#43-消息正文与证据e06e11e15e32)。
+
+```ts
+await saveJson('allocation-input.json', unsignedAllocation);
+const signedAllocation = await aun<sp.SignedJsonBytes>(['credential', 'allocation-sign',
+  '--params', '@allocation-input.json'], 'cn-issuer');
+const allocation = sp.decodeSignedJson(signedAllocation) as sp.UsageAllocation;
+await client.credential.verifyAllocation(allocation, allocationContext);
+await client.credential.verifyAllocationStatus(allocationProof, allocationStatusContext);
+if (allocationProof.state === 'active') await app.reserveAllocatedUsage(request);
+```
+
+跨权威预留同时要求分配关系成立、在线查询绑定有效且 allocation 为 active；draining 结清在途，closed 返还容量。具体账本事务见 [SDK 额度流程](../sdk/凭证与组织服务SDK应用集成指南.md#48-额度分配与执行结果e27e30)。
+
+## 7. 修订、撤销与 UsageRef 续跑
+
+```mermaid
+flowchart TD
+    A[get 当前 head／transition] --> B{操作}
+    B -->|metadata| C[revise：逐受众 CAS]
+    B -->|整个 CID| D[revoke]
+    B -->|UsageRef| E[usage-prepare：固定 candidate 与 fence]
+    E --> F[账本冻结、结清 Unknown 与分配、签 checkpoint／acceptance]
+    F --> G{提交或取消}
+    G -->|提交| H[usage-commit]
+    G -->|取消| I[usage-abort，收集 ledger-abort]
+    C --> J[保存回执和进度]
+    D --> J
+    H --> J
+    I --> J
+```
+
+revisionInput／prepareInput／commitInput／abortInput 在调用前保存；字段构造见 [SDK 修订及协调示例](../sdk/凭证与组织服务SDK应用集成指南.md#47-受众修订历史读取与撤销e17e18e21e22)。
+
+```ts
+await saveJson('revision-input.json', revisionInput);
+const revised = await aun(['credential', 'revise', '--params', '@revision-input.json']);
+await saveJson('revoke-input.json', { ...management(cid), reason_code: 'grant_withdrawn' });
+const revoked = await aun(['credential', 'revoke', '--params', '@revoke-input.json']);
+```
+
+| 受众变更 | change 中的材料 |
+| --- | --- |
+| 替换／批量替换 | expected＋metadata |
+| 新增 | expected_absent＋metadata |
+| 撤下 | expected＋withdraw |
+| 重加 | expected_withdrawn 的 last_revision／state_seq＋metadata |
+
+```ts
+await saveJson('usage-prepare-input.json', prepareInput);
+const prepared = await aun(['credential', 'usage-prepare', '--params', '@usage-prepare-input.json']);
+await saveJson('usage-transition.json', prepared);
+await saveJson('usage-commit-input.json', commitInput);
+const committed = await aun(['credential', 'usage-commit', '--params', '@usage-commit-input.json']);
+```
+
+取消分支单独调用；保留 prepared 的同一 transition_id／fence／from_usage：
+
+```ts
+await saveJson('usage-abort-input.json', abortInput);
+const aborted = await aun(['credential', 'usage-abort', '--params', '@usage-abort-input.json']);
+```
+
+账本配套对象由对应权威 profile 签署：
+
+```ts
+await saveJson('checkpoint-input.json', checkpointInput);
+const checkpoint = await aun(['credential', 'usage-record-sign', '--kind', 'usage-checkpoint',
+  '--params', '@checkpoint-input.json'], 'cn-issuer');
+```
+
+```ts
+await saveJson('crl-input.json', { ...management(''), scope: { audiences: [businessAid] },
+  after_event_seq: afterEventSeq, cursor: savedCursor, limit: 100 });
+const page = await aun<sp.SemanticRevocationPage>(['credential', 'revocations', '--params', '@crl-input.json']);
+await saveJson('crl-page.json', page);
+```
+
+CRL 按 authority＋scope 保存进度，续页使用 next_cursor；next_cursor=null 才推进 upper_event_seq。丢响应后用原 transition_id 查询 get，按 prepared／committed／aborted 恢复；Unknown 保留预留并查询原执行器。
+
+跨域管理显式指定语义权威；包验真通过 credential_services 逐 CID 选择服务：
+
+```ts
+const remote = await aun(['credential', '--target', 'credential.aid.com',
+  'get', '--params', '@remote-get-input.json']);
+```
+
+remote-get-input 的 authority 使用该域的可信管理依据。普通列表使用 `credential revocation-list`，输入字段见 [普通 RPC](../sdk/09-凭证服务RPC手册.md#credentialrevocationlist)。
+
+## 8. 组织命令地图与创建
+
+| 场景 | CLI 命令 |
+| --- | --- |
+| 诊断 | `org health`、`org status` |
+| 生命周期 | `org create`、`list`、`info`、`update`、`suspend`、`resume`、`dissolve` |
+| 所有权 | `org transfer`、`transfer-accept` |
+| 申请／邀请 | `org join`、`join-approve`、`join-reject`、`invite`、`invite-accept`、`invite-reject` |
+| 成员与收尾 | `org members`、`member`、`leave`、`kick`、`freeze`、`unfreeze`、`ban`、`unban`、`offboard-status`、`offboard-confirm`、`offboard-cancel` |
+| 成员凭证 | `org credential info`、`renew`、`revocation-list` |
+| 审计 | `org audit query` |
+| 预留，返回 NOT_IMPLEMENTED | `org join-requests`／`invites`／`role`／`roles`；`org credential list`／`held`／`surrender`／`delegate`／`pending` |
+
+```mermaid
+flowchart LR
+    A[owner profile 与持久 AIDStore] --> B[org create：保存实体身份]
+    B --> C[SDK 准备 owner binding／CAP／登记授权]
+    C --> D[Org 验回执并创建组织]
+    D --> E[实体主签、owner token 上传名片]
+    E --> F[info／list 查询生命周期]
+```
+
+```ts
+const orgAid = 'team.agentid.cn';
+const orgServiceAid = 'org.agentid.cn';
+const creationInput = { org_id: orgAid, name: '协作组织', request_id: randomUUID(),
+  nonce: randomBytes(32).toString('base64url') };
+await saveJson('org-create-input.json', creationInput);
+const created = await aun(['org', '--params', '@org-create-input.json', 'create',
+  '--name', creationInput.name, '--org-id', orgAid], 'cn-owner');
+await saveJson('org-created.json', created);
+const info = await aun(['org', 'info', orgAid], 'cn-owner');
+```
+
+对应 TS 高层入口：
+
+```ts
+const sdkCreated = await ownerClient.createOrg({ org_id: orgAid, name: '协作组织' },
+  { aidStore: ownerStore });
+```
+
+org.update 的 patch／expected_version、暂停／恢复等授权材料可通过组级 `--params` 传入。health／status 用于诊断，成员资格使用签名成员状态。
+
+## 9. 入组、邀请与成员凭证
+
+### 9.1 申请与审批
+
+```mermaid
+sequenceDiagram
+    participant M as 成员 profile
+    participant O as owner／审批者 profile
+    participant G as Org 服务
+    M->>G: join：成员签 binding
+    G-->>M: join_request_id、application
+    M->>O: 完整 application 与条款
+    O->>G: join-approve --application：原 binding／terms＋当前审批资格
+    G->>G: 登记 CAP、验回执、最终化成员
+    G-->>M: active 与完整成员包
+```
+
+```ts
+await saveJson('terms.json', terms);
+const joined = await aun<{ join_request_id: string; application: unknown }>(['org', 'join',
+  orgAid, '--member-type', 'human', '--terms', '@terms.json'], 'cn-member');
+await saveJson('application.json', joined.application);
+await saveJson('owner-auth.json', { credentials: ownerCredentials });
+const approved = await aun(['org', '--params', '@owner-auth.json', 'join-approve', orgAid,
+  joined.join_request_id, '--application', '@application.json'], 'cn-owner');
+```
+
+审批者 signer 签 binding 的组织侧；本地组织实体 signer 签 CAP 和登记授权。CLI 自动取实体私钥时需相应 profile 的持久 AIDStore。
+
+```ts
+const binding = ownerClient.org.member.signBinding(applicationBinding, ownerSigner, 'org');
+const approval = ownerClient.org.prepareRequest('org.member.approveJoin', {
+  org_id: orgAid, join_request_id: joinRequestId, terms,
+  membership_binding: binding, credentials: ownerCredentials,
+}, orgServiceAid, ownerSigner, { orgSigner });
+await ownerClient.org.member.approveJoin(approval);
+```
+
+### 9.2 邀请、接受与拒绝
+
+```mermaid
+flowchart TD
+    A[owner invite：每个目标独立材料] --> B[保存 invites 中本目标条目及原 terms]
+    B --> C{目标成员选择}
+    C -->|接受| D[invite-accept --invitation：原 binding／CAP／登记授权]
+    D --> E[成员补签，登记并最终化]
+    C -->|拒绝| F[invite-reject --invitation：原组织签名 binding]
+    F --> G[独立操作 ID／nonce 签拒绝请求]
+```
+
+```ts
+const invitations = await aun<{ invites: sp.JsonObject[] }>(['org', '--params', '@owner-auth.json',
+  'invite', orgAid, '--targets', holderAid, '--terms', '@terms.json'], 'cn-owner');
+const invitation = invitations.invites.find(item => item.target_aid === holderAid)!;
+await saveJson('invitation.json', invitation);
+const accepted = await aun(['org', 'invite-accept', orgAid, String(invitation.invite_id),
+  '--invitation', '@invitation.json'], 'cn-member');
+```
+
+拒绝是另一条分支，使用对应原邀请：
+
+```ts
+const rejected = await aun(['org', 'invite-reject', orgAid, rejectedInviteId,
+  '--invitation', '@rejected-invitation.json', '--reason', '暂不加入'], 'cn-member');
+```
+
+邀请返回条目包含 membership_binding／credential_template／registration_authorization，条款原文由发起方保留。CLI 从 `--invitation` 读取已取得的原条目；首次 admission 固定 membership_id，由目标成员签名。代表操作使用 `--for` 与真实 representation proof，SDK 验当前代表依据。
+
+### 9.3 受保护读取、续期与收尾
+
+```mermaid
+flowchart LR
+    A[当前 credentials：binding 与 member／approval CAP] --> B[准备受保护读取／成员操作]
+    B --> C[member／members／credential info／revocation-list]
+    B --> D[renew：同关系、新 binding／CAP／登记授权、旧 CID＋版本 CAS]
+    D --> E[保存完整新包，current 读取本地最新记录]
+    B --> F[leave／kick，进入 offboarding]
+    F --> G[offboard-confirm，ended 与有权 CAP 撤销]
+```
+
+```ts
+await saveJson('member-auth.json', { credentials: memberCredentials });
+const member = await aun(['org', '--params', '@member-auth.json', 'member', orgAid, holderAid], 'cn-member');
+const orgCrl = await aun(['org', '--params', '@member-auth.json', 'credential',
+  'revocation-list', orgAid, '--since-event-seq', String(orgAfterEventSeq), '--limit', '100'], 'cn-member');
+```
+
+renewalMaterial 保留同一 membership_id，含双签 replacement binding、terms、新 CAP／登记授权及当前调用资格：
+
+```ts
+await saveJson('renewal.json', renewalMaterial);
+const renewed = await aun(['org', '--params', '@renewal.json', 'credential', 'renew',
+  oldCid, '--org-id', orgAid, '--expected-version', String(memberVersion)], 'cn-member');
+await saveJson('renewal-result.json', renewed);
+```
+
+freeze／unfreeze、ban／unban 与 kick 通过当前授权材料调用，并按 expected_version 处理冲突。签名 membership_status 决定当前成员状态；离职流程按 operation_id 和阶段结果续跑。
+
+## 10. 转让、换钥与解散
+
+```mermaid
+sequenceDiagram
+    participant O as 原 owner profile
+    participant N as 目标 owner profile
+    participant G as Org／CA
+    O->>G: transfer：目标成员与期限
+    G-->>O: transfer_id、原签名 proposal
+    O->>N: proposal 与双方替换材料
+    N->>N: SDK 验提案、保存新实体私钥与 checkpoint
+    N->>G: transfer-accept --proposal：rekey
+    G-->>N: pending_finalization 与新证书
+    N->>G: SDK 重签双方材料，finalize
+    G-->>N: 新 owner 与完整成员包
+    N->>N: 保存身份，上传新名片
+```
+
+```ts
+const transferInput = { org_id: orgAid, target_member_aid: targetOwnerAid,
+  expires_at: Math.trunc(Date.now() / 1000) + 300, credentials: ownerCredentials,
+  request_id: randomUUID(), nonce: randomBytes(32).toString('base64url') };
+await saveJson('transfer-input.json', transferInput);
+const transfer = await aun<{ transfer_id: string; proposal: unknown }>(['org',
+  '--params', '@transfer-input.json', 'transfer', orgAid, targetOwnerAid,
+  '--expires-at', String(transferInput.expires_at)], 'cn-owner');
+```
+
+```ts
+await saveJson('proposal.json', transfer.proposal);
+await saveJson('transfer-material.json', transferMaterial);
+const transferred = await aun(['org', '--params', '@transfer-material.json', 'transfer-accept',
+  orgAid, transfer.transfer_id, '--proposal', '@proposal.json'], 'cn-target');
+```
+
+`--proposal` 进入 SDK 完整 rekey→finalize 编排，自动生成并持久保存新实体密钥。transferMaterial 保存双方原关系及替换 binding／CAP／登记授权和当前资格。恢复沿用原 transfer、接受签名、阶段请求与私钥。
+
+```ts
+const acceptance = targetClient.org.lifecycle.signTransferAcceptance(proposal, targetSigner);
+const sdkTransferred = await targetClient.completeOrgTransfer({ ...transferMaterial, proposal,
+  org_id: orgAid, transfer_id: transfer.transfer_id, ...acceptance }, { aidStore: targetStore });
+```
+
+```mermaid
+flowchart LR
+    A[当前 owner 资格] --> B[dissolve]
+    B --> C{返回阶段}
+    C -->|dissolving| D[保存 operation_id，续查进度]
+    C -->|dissolved| E[SDK 失效本地实体身份并清恢复状态]
+    E --> F[保留归档与磁盘私钥]
+```
+
+解散使用当前 owner 的最新成员包；以下承接转让后的 cn-target，newOwnerCredentials 取已验真的新 owner 成员材料：
+
+```ts
+await saveJson('new-owner-auth.json', { credentials: newOwnerCredentials });
+const dissolved = await aun(['org', '--params', '@new-owner-auth.json', 'dissolve', orgAid], 'cn-target');
+```
+
+直接 TS SDK 入口：
+
+```ts
+const sdkDissolved = await targetClient.dissolveOrg({ org_id: orgAid, credentials: newOwnerCredentials },
+  { aidStore: targetStore });
+```
+
+## 11. CLI 开发、错误与验证
+
+### 11.1 胶水层职责
+
+```mermaid
+flowchart LR
+    A[Typer 命令与参数] --> B[严格 JSON／UTF-8 文件]
+    B --> C[CLISession 加载 profile 与身份]
+    C --> D[SDK facade／高层编排]
+    D --> E[原样 JSON、原字节文件、退出码]
+```
+
+| 代码位置 | 维护内容 |
+| --- | --- |
+| [main.py](../../python/src/aun_cli/main.py) | credential／org 命令注册、全局 profile／JSON／超时 |
+| [credential.py](../../python/src/aun_cli/commands/credential.py) | 参数映射、profile signer、语义 target、online 查询生命周期 |
+| [org.py](../../python/src/aun_cli/commands/org.py) | 原申请／邀请材料衔接、受保护读取准备、组织命令映射 |
+| [adapter.py](../../python/src/aun_cli/adapter.py)／[output.py](../../python/src/aun_cli/output.py) | 会话、配置、stdout／stderr 与错误退出 |
+| [org_facades.py](../../python/src/aun_core/org_facades.py)／[semantic_facades.py](../../python/src/aun_core/semantic_facades.py) | SDK 的普通／语义分流、签名验真、组织编排与持久状态 |
+| [TS facades](../../ts/src/facades.ts)／[semantic-facade.ts](../../ts/src/semantic-facade.ts) | TS 对照；位置参数、回调及异步约定 |
+
+| CLI JSON／材料 | TS SDK 对应形式 |
+| --- | --- |
+| verify structured 的实际请求 context | `credential.verify(cap,context)`；查询／信任校验先 await，可信 resolver 同步返回已验材料 |
+| package `{lineage}` | `buildPackage(lineage)` |
+| request 完整业务字段 | `buildRequest(input)`，显式 ID／nonce／expires_at |
+| request-verify 的 context.authenticated | `verifyRequest(request, authentication, options)`，另做包验真及业务检查 |
+| decision-input `{request,bodies,facts,policy}` | `buildDecisionInput(request,bodies,facts,policy)`，先验真正文 |
+| evidence-export `{bytes_base64,profile,locator?}` | `createEvidenceRef(bytes,profile,locator?)` |
+| credential_signers／credential_services 映射 | packageContext.originalSigner／serviceFor 回调 |
+| org 原业务材料＋credentials | `prepareRequest(method,params,target,signer,options)`，再调用 facade |
+
+### 11.2 错误与断点续跑
+
+| 退出码 | 含义 |
+| --- | --- |
+| 0 | 成功 |
+| 1 | 通用业务错误 |
+| 2 | 参数／格式／绑定 |
+| 3 | 认证／签名／身份 |
+| 4／5 | 连接／超时 |
+| 6／7 | 权限／不存在 |
+
+```ts
+try {
+  await aun(['credential', 'register', '--params', '@registration.json']);
+} catch (error) {
+  const failure = error as Error & { code: number; stderr: string };
+  if (!failure.stderr?.trim()) throw error;
+  const line = failure.stderr.trim().split(/\r?\n/).at(-1)!;
+  const detail = JSON.parse(line) as { message: string; error_code?: string; retryable?: boolean };
+  console.error(failure.code, detail.error_code, detail.message, detail.retryable);
+}
+```
+
+错误 JSON 保留 code、rpc_code、data、error_code 与 retryable。恢复使用保存的原输入；CAS 冲突先取当前 head，转让／UsageRef 先查原阶段，业务 Unknown 查询原执行结果。证书、签名与权限问题按具体错误修正材料。
+
+### 11.3 用例与 E2E 对照
+
+| 场景 | 本指南入口 | 进一步覆盖 |
+| --- | --- | --- |
+| E01 普通兼容 | §4.1 create／register／status／verify structured／revoke／revocation-list／current | 约束、委托收窄、请求绑定、强状态、回执与恢复 |
+| E02—E05、E18 签发／补确认 | §4.2 sign／metadata-sign／register | 确认权、UsageContract、补材料 |
+| E06—E11、E15、E32 消息证据 | §6 evidence-export／evidence-verify | 原收件、群证明、附件、归档 resolver |
+| E12—E16、E19—E26 出示与验收 | §4.3—§5 package／request／request-verify／decision-input | 多跳、代表、三态、状态与重传 |
+| E17、E21—E22 修订／撤销 | §7 revise／revoke／revocations | 多受众 CAS、历史版本、CRL 单调性 |
+| E27—E31、E33 额度／恢复 | §6—§7 allocation／usage-* | 账本事务、Unknown、切换及冷恢复 |
+| E34—E36 历史证书／双域／公开入口 | §5—§7 context／target | 跨域权威、历史信任、四 SDK 与浏览器 |
+| 组织业务 | §8—§10 | 创建、双签入组、邀请拒绝、受保护读取、续期、收尾、转让与解散 |
+
+CLI 本地用例：[test_cli_credential.py](../../python/tests/unit/test_cli_credential.py)、[test_cli_org.py](../../python/tests/unit/test_cli_org.py)。场景定义与真实运行入口：[scenarios.json](../../examples/semantic-credential/scenarios.json)、[CLI 场景运行器](../../examples/semantic-credential/cli/scenario.py)、[cross-SDK E2E runner](../../tests/cross-sdk/runner/run_cross_sdk_e2e.py)。实际环境证据范围见 [示例使用指南 §5](../../examples/semantic-credential/示例使用指南.md#5-本轮验证记录与边界)。