@xgent-ai/skills 0.7.1 → 0.7.3

package/skills/portal-external-app/references/end-user-lifecycle.md

@@ -0,0 +1,343 @@
+# 终端用户账号生命周期、条款与隐私接口
+
+> 先读 [能力与归属](end-users.md)；登录与本人证明见 [认证协议](end-user-auth.md)。
+> 下列 `/api/v1/*` 是门户基座服务面，不是 `/svc/user-center`，也不走成员的跨 App 令牌交换。
+> 所有示例为占位；普通查询 DTO 脱敏，专门导出才可含明文标识和联系方式。
+
+## 1. 服务身份与最小权限
+
+App 后端用获得 client_credentials、租户 allowlist、正确 owner 绑定的服务账号换服务票：
+
+```http
+POST <portal-origin>/api/tokens/service
+Authorization: Basic <服务账号clientId:secret的base64>
+Content-Type: application/json
+
+{"grant_type":"client_credentials","tenant_id":"<租户UUID>","scope":"endusers.read"}
+```
+
+从成功 Envelope 的 data 取 `access_token`，再 Bearer 调管理接口。Basic 只用于换票/自省，
+管理接口不直接收 Basic，也不收成员或终端用户 access。tenant 来自 `tenant_id`，owner 来自 `azp`；
+一般接口 body 的 tenantId/ownerAppKey 不能扩大范围，siteKey 必须落在该 owner 的 realm 内。
+共享 user-center 通行证也必须使用平台明确绑定该 owner 的服务身份，不能自报 owner。
+
+| scope | 能力 |
+| --- | --- |
+| `endusers.read` | 身份/业务引用/完整标识查询、会话读取与解析、主体资格、realm 登记、处置日志、导出与清理状态 |
+| `endusers.manage` | 建号、设/重置凭据、迁移、同步命令、删除；也覆盖会话撤销及封禁解封 |
+| `endusers.sessions` | 只撤销会话、封禁/解封；不含建号、改密、删除、迁移或命令 |
+| `endusers.clients` | 客户端登记及回调治理；manage 不能代替它 |
+| `privacy.requests.read/manage/receipt` | 分别读参与请求进度、拉本 App 待办、交本 App 回执 |
+| `notification.external.contacts/send` | 分别管理本 App 外部联系依据、受理外部通知事件；不由成员 notification.send 替代 |
+
+这些是 SERVICE_ONLY scope，经 manifest `privilegedServiceScopes:[{scope,reason}]` 申请审批，
+不放入普通 serviceScopes 或成员 scopes；持 manage 不自动拥有 read/clients。
+只取实际需要的权限，不为集中下线功能授予能改密码的 manage。
+
+## 2. 身份管理 API
+
+以下路径均以 `/api/v1/end-users` 为前缀，R=read，M=manage，S=manage 或 sessions：
+
+| 方法与路径 | 权限 | 关键输入/用途 |
+| --- | --- | --- |
+| `POST` 空路径 | M | `siteKey,identifierKind,identifier`；可选 externalRef、credential、locale、mustChangePassword；新建或按业务引用幂等回读 |
+| `GET /<id>` | R | 读取脱敏身份；不存在 data:null |
+| `POST /lookup` | R | `{siteKey,externalRefs:[...]}`，最多 500 项，一批回读避免逐人请求 |
+| `POST /lookup-by-identifier` | R | `{siteKey,items:[{kind,identifier}]}`；完整标识精确查找，一次最多 10 条，按标识数限流 60 条/分钟/应用/租户 |
+| `POST /<id>/credential` | M | `credential`（8–200 字符）、可选 mustChangePassword；推进凭据版本、撤销全部会话 |
+| `POST /<id>/archive`、`/unarchive` | S | 归档/解封；不提供“顺便解除所有阻断” |
+| `POST /<id>/registration-ticket` | M | 可选 contactId，签发绑定该人邮箱联系方式的受限验证票；不能登录或拿文件 |
+| `GET /<id>/sessions` | R | 会话列表；包含呈现方式、设备、脱敏 IP、UA、时间与撤销状态 |
+| `POST /<id>/sessions/revoke-all` | S | 全部会话失效并递增凭据版本；包括托管浏览器登录 |
+| `POST /<id>/sessions/<sessionId>/revoke` | S | 只撤一条，不递增主体凭据版本；其他设备不受影响，已撤/不存在回 revoked:0 |
+| `POST /sessions/resolve` | R | 所属 App 后端将站点 cookie 会话解析为 owner/files 定向票，须同时匹配调用方及会话空间 |
+| `POST /subjects/check` | R | `id,siteKey`；返回存在/当前可用/空间的受限投影，不返回联系方式；资源服务器例外由平台限定 |
+| `GET /realm?siteKey=...` | R | 自己的 realm/profile/client 登记自检，未登记不是 404 |
+| `GET /<id>/export`、`/<id>/privacy-status` | R | 平台数据导出/异步清理状态 |
+| `DELETE /<id>` | M | 服务治理删除，返回 deleted、cleanup、quota；不是用户本人重新认证 |
+| `POST /clients` | clients | 客户端及回调登记，字段与示例见认证协议 |
+
+`identifierKind` 可为 username/email/phone。邮箱 trim 后转小写；手机号只接受完整 E.164，
+不猜国家码；用户名按平台规则归一。精确查找不支持前缀/后缀/模糊，不返回墓碑，
+输入任一项非法整批拒绝；审计只记数量，不记明文或可反查摘要。
+归档保留容量，解封不恢复会话；直接建号/改密/归档等对 command-only owner 会被拒。
+
+`GET /realm` 的 `realmAllows:false` 要区分没声明、已撤销、越界；允许但 profile:null 表示尚未登记。
+同一注册信息可在用户中心自检卡查看。返回配置不包含运行保留参数或 Apple 私钥。
+
+## 3. 跨库同步：五类普通命令与本人删除
+
+业务事实在 App 库、身份事实在平台库时，不能用本地事务包 HTTP 假装原子提交。
+本地持久化操作号、拟变更、业务修订与阶段，再执行：
+
+```text
+POST /api/v1/end-users/commands/<operationKey>/prepare
+  {siteKey,externalRef,action,sequence,payload}
+→ App 本地事务：重查前置条件，提交业务事实，记录 finalize_pending
+POST /api/v1/end-users/commands/<operationKey>/finalize
+  {siteKey}
+本地未提交且失败时：POST 同号 /abort {siteKey,reason?}
+丢回包先：GET /api/v1/end-users/commands/<operationKey>?siteKey=...
+```
+
+| 普通 action | payload |
+| --- | --- |
+| create_account | identifierKind、identifier、credential；可选 mustChangePassword、locale、status（active/archived） |
+| set_credential | credential，可选 mustChangePassword；恢复凭据时 expectedRecoveryRunId/expectedCredentialVersion 须成对 |
+| set_identifier | identifierKind、identifier |
+| set_status | status：active 或 archived |
+| revoke_sessions | 空对象 |
+
+operationKey 使用 1–128 位字母、数字、`._:-`；externalRef 为稳定业务引用。
+sequence 用于阻止迟到操作；同号同摘要回原命令，不同内容冲突，不能换号绕过。
+prepare 后现有身份即阻断、撤会话、推进凭据版本；新建仅预留候选 ID 和容量，不产生可登录账号。
+abort 不恢复已经撤销的会话；finalized 不能 abort，逆向变更须新补偿命令。
+`GET /api/v1/end-users/commands` 列未终结项，接入方应持久续跑，不靠用户投诉发现卡单。
+
+单条命令成功 Envelope 的 data：
+
+```text
+{operationKey,action,phase,sequence,externalRef,siteKey,
+ endUserId,candidateEndUserId,preparedAt,settledAt,resultSummary,portalCleanup?}
+phase = prepared | finalized | aborted
+```
+
+新建 prepare 的候选 ID 不等于已生效身份，endUserId/candidateEndUserId 可为 null；
+终结时间 settledAt 可为 null，不回显敏感 payload。GET 不存在回 data:null。
+resultSummary 是动作相关摘要，不用它替代 phase；删除的 portalCleanup 为 pending/done/failed。
+常见失败分别处理 CONFLICT、END_USER_SYNC_PENDING、END_USER_REAUTH_REQUIRED；
+未知业务错误保留失败状态，不按 HTTP 200 判定已经提交。
+
+批量（单次 ≤100，逐项结果、逐主体事务）：
+
+```text
+POST /commands/batch/prepare   {siteKey,items:[{operationKey,externalRef,action,sequence,payload}]}
+POST /commands/batch/finalize  {siteKey,items:[{operationKey}]}
+POST /commands/batch/abort     {siteKey,items:[{operationKey,reason?}]}
+→ data.items:[{operationKey,ok,command?,error?}]
+```
+
+以上仍以 `/api/v1/end-users` 为前缀。一项失败不代表整批失败，也不代表其余全部成功；
+逐项落阶段再续跑。同一批重复标识可能在 prepare 就冲突，不要改用并发逐人请求规避。
+
+第六类 `delete_account` **不是上面普通 payload 模式**。本人注销托管通行证：
+
+1. 由当前用户按认证协议取得 `purpose=delete_passport` 的近期证明，操作号持久保存。
+2. 服务后端持 manage 调同号 prepare，body **只允许**
+   `siteKey,action:"delete_account",endUserId,reauthToken,sequence?`，
+   不传 externalRef 或 payload。平台单次消费证明、阻断身份并撤销全部会话。
+3. App 持久提交自己的业务清理后，同号 finalize；未提交不可逆清理可 abort。
+   丢回包先回读，同号同摘要重试可返回原结果，不能复用证明创建另一操作。
+4. 回读 command 的 `portalCleanup` / 清理分项，区分 pending/done/failed；
+   它只说明平台清理，不证明所有业务资产已清除。confirm_action 证明不能用于此命令。
+
+清理分项通过 `GET /api/v1/end-users/<id>/privacy-status` 取得：
+data 含 `endUserId,status,privacyRevision,cleanup,jobs,operations?`。
+operations 的每项含 operationKey、commandPhase、identity（active/blocked/deleted）、
+sessions（revoked）、notificationCleanup、appleRevocation、portalCleanup、updatedAt；
+前两种供应商/通知清理状态还可为 not_required。不要把 not_required 当作发送或撤权失败。
+
+## 4. 存量迁移
+
+`POST /api/v1/end-users/migrations/import`（M）是唯一接收外部密码哈希的入口：
+输入 `siteKey,externalRef,identifierKind,identifier,passwordHash`，可选
+`mustChangePassword,lockedUntil,failedLoginCount,credentialVersion,locale,status`；
+接受 Argon2 / bcrypt，原归档状态可保留。联系方式导入不等于已经验证。
+
+同 externalRef 且原哈希/标识一致回 created:false，不重复占额；不一致则停止该行交由人确认，
+不得覆盖成静默改密；墓碑不复活。先备份、演练和核对，再切换入口，避免两边同时维护凭据。
+迁移后平台已改过的口令不能无损回流；回滚需要冻结写入、按事实对账并安排受控重设。
+
+## 5. 条款与接受证据
+
+使用平台托管条款时，由租户在用户中心发布，App 按接口读取当前版本。
+
+| 服务接口 | scope | 输入 |
+| --- | --- | --- |
+| `GET /api/v1/end-user-policies/current?siteKey=...` | read | 取当前生效各文档，含正文 |
+| `POST /api/v1/end-user-policies/acceptances` | manage | `endUserId,docId,requestId`；可选 context:"app"、contextRef |
+| `GET /api/v1/end-user-policies/acceptances` | read | `endUserId,docKey,at?`，查询某时刻之前已接受的版本 |
+
+这里 read/manage 指 endusers.read/manage。主体和文档须在本租户/owner/site 内，
+requestId 同号同内容幂等、异内容冲突。平台托管注册自动记录必选当前版本；
+App 自己展示后的接受由 App 服务后端代表用户记录，终端用户 token 不直接写接受接口。
+
+## 6. 个人数据请求、导出与保留
+
+租户 UI 受理 export/rectify/erase，冻结身份域、网站用途同意域及本租户当时已接入 App 的参与清单，
+并可补漏；不会自动发现所有历史外部系统。身份删除后请求仍可追踪。
+更正请求只协调处理，平台身份标识/联系方式须走验证流程，同意证据须由本人重新选择；
+不能把 rectify 当作管理员任意改资料的后门。
+参与方不另建登记表：本租户 App 仍 active，且有效服务账号获准 privacy.requests.manage、
+租户访问范围匹配，即可在新请求冻结清单时纳入；已有请求遗漏的参与方由有权操作人补入。
+当前没有服务态或终端用户态“发起个人数据请求”接口，受理入口是用户中心；
+App 可以提供自己的申请入口并安排转办，不能虚构一个平台 POST 端点。
+
+App 后端的协同接口：
+
+```text
+GET  /api/v1/privacy-requests/assignments?state=pending&limit=...
+     # privacy.requests.manage，拿自己的待办/期限/subjectRef
+POST /api/v1/privacy-requests/assignments/<assignmentId>/receipt
+     # privacy.requests.receipt
+     {receiptId,state,note?,receiptRef?,detail?}
+GET  /api/v1/privacy-requests/<requestId>
+     # privacy.requests.read，仅参与方可读，他方回执detail不公开
+```
+
+待办响应为 `data.items`，每项字段：
+
+```text
+{assignmentId,requestId,requestRef,action,subjectKind:"end_user",
+ subjectRef:"enduser:<主体UUID>",ownerAppKey,siteKey,policyVersion,dueAt,overdue,state,attempts}
+```
+
+requestId 是平台请求 UUID，用于读进度；requestRef 是受理来源单号，用于本人导出路径的 ref，
+不能把两种引用混用，也不能把 ref 当免鉴权凭据；拼进 URL 时编码。由待办取得 ref 后，只向经过本地授权的对应用户展示。
+不传 state 时默认拉 pending/unknown/failed，limit 最多 200；App 自己实现持久办理和续跑，
+不能只拉一次 pending 后忽略处理结果不明的项。
+
+receiptId 幂等；state 为 done/exception/unknown/failed。exception 必须写保留依据 note；
+pending/unknown/failed 仍令整体 open，全部 done 才 completed，含保留例外为
+completed_with_retention。超期待办会升级给租户 active 管理员。不要把“身份清理工作项人工重试”
+写成“所有 App 隐私待办都有管理员重试按钮”。
+
+平台持有数据的导出有两条路径：
+
+- owner 后端经 read 调 `GET /api/v1/end-users/<id>/export`。
+- 已受理的 export 请求，本人持当前有效终端用户 Bearer 调
+  `GET /api/public/privacy-requests/<ref>/export`，只到请求 dueAt，不能转发为免鉴权签名 URL。
+
+平台包包含身份、明文标识/联系方式、会话、认证事件和条款接受证据；跨系统本人包另含网站用途
+同意记录。无密码/哈希/验证码/token/HMAC/密文，也不打包 App 业务文件；业务数据由各参与 App
+自行交付。当前网站同意记录读取有限额，不承诺无限量历史全导出。用户中心只跟踪进度，没有下载按钮。
+
+用户中心可维护四类平台数据的保留期限、依据、责任方及法务保全，预演/执行到期清理；
+未配置的类别不会按猜测的期限清理，保全阻止到期清理。条款接受证据的期限从主体删除起算。
+保留依据会体现在请求完成状态；备份与外部副本不在平台这一次清理承诺内。
+各 App 仍需执行自己域的保留/清理，并如实回执。
+
+## 7. 处置事实、恢复与通知设备
+
+`GET /api/v1/end-users/journal?after=<cursor>&limit=<1到500>`（R）返回本 owner 的
+`items:[{cursor,action,endUserId,siteKey,scope,occurredAt}],nextAfter`。
+用于补拉平台删除、归档/解除、撤会话、凭据/标识失效、推送注销等事实。
+游标单调但不连续，未知 action 忽略；事实可长期补拉，不能因跳号报丢数据。
+满页 nextAfter 为末条游标、短页为 null；追平时仍持久保存最后已处理游标，不能重置成起点。
+scope 是动作相关对象，字段须按 action 解释；命令/基线变体可增加字段，不能要求每条都有全部字段。
+当前已知处置及消费含义：
+
+| action | 关键 scope 字段（按实际记录提供） | App 如何处理 |
+| --- | --- | --- |
+| subject_deleted | credentialVersion、privacyRevision；命令来源还带 commandId/operationKey | 主体已删，停止关联访问并按本域清理/保留策略办理 |
+| subject_archived / subject_unarchived | credentialVersion；命令来源可只有 commandId/action | 归档/解除归档事实；解除后仍重新检查当前资格，不复活旧会话 |
+| session_revoked | sessionId | 只失效对应设备的本地会话/缓存 |
+| sessions_revoked | credentialVersion，可有 revoked/commandId | 失效该主体全部本地登录判断，不只处理当前设备 |
+| credential_invalidated / identifier_invalidated | credentialVersion 或 commandId/action，可有 via | 失效旧身份/凭据缓存，重新取得当前身份事实，不据此推断新标识值 |
+| account_deletion_prepared / account_deletion_aborted | commandId、operationKey、sequence、credentialVersion | 对应注销开始阻断/中止；按持久命令续跑，中止不恢复旧会话 |
+| phone_binding_revoked | bindingId、reason，可有 keptReserved | 撤销旧手机登录绑定；reserved 不代表可短信登录 |
+| push_device_revoked | deviceId、reason、dispositionSeq | 使指定推送设备绑定失效 |
+| push_devices_invalidated | hostGeneration、reason、count | endUserId 为 null；只按该 siteKey 处理过时主域代次的推送订阅 |
+| apple_grant_received / apple_grant_revoked | profileId、configId | 供应商授权义务事实，endUserId 可为 null；不据此授予业务登录或把整站用户下线 |
+
+**endUserId:null 不自动代表整站处置**：必须先看 action；例如 Apple grant 事件不是全站撤权。
+这些是已发生事实，不能代替发送/授权前的当下资格自省；未知 action 跳过但推进已处理游标。
+它与隐私 assignments 互补：前者是已发生的事实，后者是要本 App 办理并回执的请求。
+
+灾备恢复后平台可用处置日志重施限制，并返回逐主体 recovery 信息；
+不能靠重新登录、解封或改一个状态解除恢复隔离。凭据重新证明的受控重设须匹配恢复代次和
+credentialVersion；具体环境的恢复流程由平台运维负责。
+
+终端用户 Web Push 使用**真实站点主域的本人 Cookie 会话**：
+
+```text
+POST /api/public/end-user-push/subscribe  {csrf,subscription}
+GET  /api/public/end-user-push/devices
+POST /api/public/end-user-push/revoke     {csrf,deviceId}
+```
+
+写操作需要同源与 CSRF；服务账号、成员 TDT、单独 owner access 不能替他人登记 endpoint。
+每人最多 20 台，绑定用户凭据代次及站点主域代次；改密、全量下线、删除、域名换代使旧订阅失效。
+撤订不受发送开关限制；同 endpoint 换人时更新归属。此处不是成员的 APNs/FCM `/api/me/devices`。
+已验证邮箱会关联平台交易通知联系依据，但营销同意必须另行取得；普通外部联系人也不天然是终端用户。
+
+独立 BFF 的托管登录不会自动创建上述站点 Cookie；不能用 owner token 换一个 Cookie 来绕过此闸。
+需要 Web Push 时先完成真实 Sites 主域的本人站点登录。这里没有终端 iOS APNs/FCM 登记合同，
+也不能直接套用成员设备接口。
+
+## 8. 外部通知：联系依据与发送接口
+
+外部通知使用自己的服务态 scope，不走成员 `notification.send`。
+manifest 的 `notificationEvents` 先登记事件/schema/模板，允许 external 受众及 transactional/marketing
+用途；用途由事件目录固定，发送时不能自报为交易用途。发送另需当前安装、租户权益、平台发送模式和
+真实渠道配置；off 不受理，shadow 只渲染抑制、不发送不占额，切 active 也不会补发旧 shadow 事件。
+
+最小邮件事件清单片段（key 是本 App 内的事件名，发送 eventType 使用同一值，不再加 listingKey 前缀）：
+
+```json
+{
+  "notificationEvents": [{
+    "key": "order.ready",
+    "schemaVersion": 1,
+    "name": "订单状态更新",
+    "payloadSchema": {
+      "type": "object",
+      "properties": { "orderRef": { "type": "string", "maxLength": 40 } },
+      "required": ["orderRef"],
+      "additionalProperties": false
+    },
+    "templateVariables": [
+      { "path": "orderRef", "type": "string", "exposure": "external_safe" }
+    ],
+    "supportedChannels": ["email"],
+    "defaultChannels": ["email"],
+    "sensitivity": "normal",
+    "defaultLane": "standard",
+    "allowedAudienceKinds": ["external"],
+    "purpose": "transactional",
+    "templates": {
+      "zh-CN": { "title": "订单 {{orderRef}} 状态已更新", "body": "请进入应用查看订单 {{orderRef}}。" }
+    }
+  }]
+}
+```
+
+提交 manifest 并完成治理审批后，发送时用 `eventType:"order.ready",schemaVersion:1`、
+`payload:{"orderRef":"ORDER-001"}`。sourceAppKey 来自服务身份，不在 body 冒认。
+定义的 key、schemaVersion、payloadSchema、模板变量、渠道、敏感等级、lane 和用途都影响接入；
+默认 audience/purpose 是 member/internal，外部事件必须显式改为 external 及交易/营销用途。
+模板只能引用已声明变量；邮件/锁屏变量按外部可展示性声明，不能塞入秘密或身份令牌。
+更改 schema 按新 schemaVersion 发布，省略已发布版本会使其弃用，历史受理不等于可以继续接收新事件。
+缺模板可能路由失败；定义及真实发件渠道就绪后再做投递验收。
+
+| 接口 | scope/输入 |
+| --- | --- |
+| `PUT /api/v1/external-notification-recipients/<externalRef>` | contacts；普通邮箱联系依据用 `{siteKey,email,locale?,expectedAddressVersion?,transactionBasis?,marketingConsent?}`，channel 缺省 email |
+| `POST /api/v1/external-notification-recipients/<id>/revoke` | contacts；`{purpose:"transactional"或"marketing",consentVersion?,reason?}` |
+| `DELETE /api/v1/external-notification-recipients/<id>` | contacts；`{expectedVersion?,reason?}`，清地址/渲染密文并取消排队项 |
+| `POST /api/v1/external-notification-events` | send；`{producerEventId,eventType,siteKey,recipientIds,payload,schemaVersion?,occurredAt?,validUntil?,siteId?,actionPath?}` |
+| `GET /api/v1/external-notification-events/<eventId>` | send；回读本 App 的脱敏事件及邮件投递结果 |
+
+这里 contacts/send 指 notification.external.contacts/send。登记联系依据返回 recipient DTO，
+其 id 才能放进 recipientIds；transactionBasis 为 `{ref,at?}`，marketingConsent 为
+`{version,evidenceRef?,evidenceDigest?}`，新营销授予须高于当前 consentVersion，不能由旧授予覆盖撤回。
+平台已托管的收件人地址/删除状态不能经此普通登记接口修改或复活。
+
+平台自动关联的终端联系人使用 `enduser:<endUserId>` 稳定引用，但普通 EndUser DTO 不返回通知 recipientId，
+事件接口也不接受 endUserId 代替 recipientIds。**当前无按 endUserId 回读通知 recipientId 的服务接口**；
+若调用方只有终端主体 ID，不能宣称已具备直接发送能力、猜 ID 或滥用数据导出来建立地址副本。
+普通 App 自有且已有合法联系依据的联系人，可按上面的登记响应保存 recipientId。
+共享通行证 owner 与业务通知来源不同，也不自动互享对方联系人，须先解决获准的来源/收件人映射。
+
+受理成功为 `{eventId,status:"accepted",duplicate,shadow}`；producerEventId 按同一业务事件稳定重试，
+accepted 不等于 delivered，更不等于 read。只用 recipientIds，不接受成员 audience 或任意绝对 link；
+营销须有已同意的收件人并绑定本 App 的真实 siteId；营销及带 actionPath 的交易事件还要求主域验证和
+路由就绪。actionPath 为站内相对路径，实际链接由平台按站点主域生成。
+事件查询、邮件送达证据、站点 Web Push 与用户阅读分别判断，不能把一个渠道的状态当作全部渠道已送达。
+
+## 9. 接入验收
+
+至少验证普通读取/最小scope、跨tenant/owner/site拒绝、重复与冲突登记、封禁与解封、单条/全部撤会话、
+批量部分失败及丢回包续跑、导入不一致拒绝、删除墓碑及额度释放、隐私三种完成状态、自己的处置流补拉。
+涉及本人删除时验证重新认证用途不能串用；涉及供应商、推送或灾备时另做实际环境验收。
+业务不存在与业务失败看 Envelope，不能用 HTTP 200 代替成功判断。

package/skills/portal-external-app/references/end-users.md

@@ -0,0 +1,124 @@
+# 租户终端用户：能力、管理入口与接入选择
+
+> 适用于顾客、学生、网站访客注册后的账号等 `kind=enduser` 主体。本文及同目录参考可随 skill 整体复制到独立 App 仓库，不需要门户源码。
+> 以下是平台实现的能力范围；目标环境的版本、安装、授权和渠道配置仍须实际核验。示例中的尖括号内容均为占位。
+
+## 按任务继续阅读
+
+- Web BFF / iOS 托管注册、登录、找回、PKCE、自省、刷新、本人重新认证：读 [终端用户认证协议](end-user-auth.md)。
+- App 后端建号、密码重置、客户端登记、批量同步、迁移、条款、隐私请求、处置日志、推送：读 [账号生命周期与隐私接口](end-user-lifecycle.md)。
+- 门户成员的原生客户端登录：读 [成员原生客户端](native-clients.md)。成员的 `/oauth/*`、`publicClient` 和 `redirectUrls` 不用于本文终端用户。
+
+## 1. 先确定身份与归属
+
+| 对象 | 身份与职责 |
+| --- | --- |
+| 门户成员 | `kind=user`，使用门户及其 iframe 微应用，拥有成员角色、组、PID/ACL，可能占 App 成员席位 |
+| 终端用户 | `kind=enduser`，不进入门户成员目录、不占成员席位、不能因此登录门户后台；身份与认证由平台托管，业务资料及业务权限归 App |
+| App 服务账号 | `kind=service`，代表后端管理获准命名空间，不是终端用户本人的认证证明 |
+
+终端身份命名空间固定为 `(tenantId, ownerAppKey, siteKey)`。同一邮箱在两个空间是两个主体；
+`endUserId` 是全局唯一、不会回收给另一人的稳定业务关联标识。删除保留 ID / `externalRef` 墓碑，
+释放旧登录标识符；同一个 `externalRef` 不能用重复登记静默复活。
+
+先与租户约定身份 owner：可以是声明了 realm 的业务 App，也可以使用平台内建的 `user-center`
+作为共享通行证 owner。多个客户端绑定同一个 profile 时可共用身份与认证域浏览器登录状态，
+但各自的应用会话、业务资料和权限不会自动互通。服务账号绑定的 owner 必须与所选身份空间一致；
+不能靠请求 body 冒充 `user-center` 或其他 owner。
+
+`user-center` 当前是有前端的仓内微应用，后端由门户 API 承担；没有独立
+`user-center-server` 或 `/svc/user-center`。不要在外部 App 清单里再声明一份用户中心。
+
+## 2. 启用条件与分工
+
+| 谁负责 | 配置或事实 |
+| --- | --- |
+| 平台管理员 | 认证域名白名单（精确 HTTPS origin）、独立于 `SESSION_SECRET` 的 `SETTINGS_ENC_KEY`、平台 SMTP、邮箱验证码运行参数、终端用户容量权益及服务账号授权 |
+| 身份 owner App | 自己的 manifest 声明 `endUserRealms`；需要服务管理时申请相应特权 scope |
+| 租户获授权的操作人 | 安装用户中心、分配用户中心权限；在用户中心登记 profile、运行策略、条款和 Apple 配置 |
+| 接入 App 后端 | 经服务接口登记自己的客户端和精确回调；保存应用会话、业务资料、业务授权，并办理本 App 的隐私待办 |
+
+身份 owner 必须已安装，租户须 active，realm 必须允许该 `siteKey`，且租户启用了
+`portal.end_users`。托管登录还需启用的 profile/client、已登记回调、可用认证域名与独立加密密钥。
+Apple 另需有效供应商配置；邮箱注册/找回另需平台 SMTP 与完整验证码配置。缺项应报告未就绪，
+不能回退到另一套宽松认证。已有密文的环境不能直接替换加密密钥。
+平台验证码固定使用平台发件身份，不借用租户或 App 的 SMTP 配置。
+
+若由业务 App 自己承载身份，manifest 可声明：
+
+```json
+{
+  "endUserRealms": { "mode": "dynamic" },
+  "privilegedServiceScopes": [
+    { "scope": "endusers.read", "reason": "读取本应用的终端身份与接入登记" },
+    { "scope": "endusers.clients", "reason": "登记本应用的认证客户端及精确回调" }
+  ]
+}
+```
+
+固定空间改用 `{"mode":"fixed","siteKeys":["customers"]}`。这里只声明范围，不创建 profile/client，
+也不授予额度。特权 scope 必须审批；不放进成员 `scopes` 或普通 `serviceScopes`。
+只做托管登录不必为此取得可改密码的 `endusers.manage`；按实际接口最小化申请。
+
+## 3. 租户管理界面：四个页面
+
+用户中心需要显式授予 landing / 页面 / 动作权限，租户 admin 的 ACL bypass 不生效。
+安装会建立预置“用户中心”角色，但不会自动发给全员。页面 PID 为
+`user-center:page:endusers`、`privacy`、`hosted`、`apple`（后三者同样使用 `user-center:page:` 前缀）。
+动作分为 `enduser.revoke`、`enduser.status.manage`、`enduser.privacy.retry`、
+`enduser.privacy.request`、`hosted.register`、`apple.manage`，使用 `user-center:action:` 前缀。
+管理 API `/api/v1/user-center/*` 另要求用户态 TDT 与 `user_center.read/write`；
+它不是给 App 后端使用的服务管理接口。
+
+| 页面/区块 | 可以做什么 | 关键边界 |
+| --- | --- | --- |
+| 终端用户列表 | 按 App、siteKey、active/locked/archived/deleted 筛选；每页 50 条继续加载；看脱敏账号、externalRef、在线会话数、最近登录 | 默认隐藏 deleted 墓碑；卸载后仍有数据的 owner 为只读 |
+| 精确定位与详情 | 完整邮箱/手机号精确查找；看标识类型、语言、创建/登录/锁定时间、主联系方式与验证状态、密码有无/首登改密要求 | UI 无用户名或模糊搜索；无业务姓名、订单、学籍等资料 |
+| 会话与封禁 | 查看浏览器/设备会话、设备 ID、脱敏 IP、UA、最近活动；单条/全部下线；封禁与解封 | 封禁即 archived，继续占额；解封不恢复会话、不解除登录失败锁或恢复隔离 |
+| 登记自检 | 区分没声明 realm、realm 撤销、siteKey 越界、允许但未登记 profile；查看认证域名、方法、注册开关、客户端与回调 | 只读，不在此卡片修改 |
+| 个人数据请求 | 受理 export/rectify/erase，填来源单号、期限、备注；按状态/主体引用查请求，追踪参与方、回执、逾期与保留说明，补遗漏方 | 只有三类动作，无独立 anonymize；更正不提供直接改身份资料表单 |
+| 清理工作项 | 在用户详情看清理进度、重试次数、错误、下次尝试、执行租约及人工记录；按权限重试 | 接收重试不等于完成；不抢正在执行的任务，不重试 done |
+| 保留策略 | 配置网站用途同意证据、认证事件、已办结请求、条款接受证据的期限、依据、责任方、法务保全；预演计数/执行清理 | 未配无统一默认期限；法务保全阻止清理；条款接受期限从主体删除起算 |
+| 托管登录/profile | 搜索、新建、编辑、启停；选择 owner/siteKey、名称、认证域名、password/apple、自助注册、Apple 配置；预览确认与修订冲突比较 | owner/siteKey 创建后不可改绑；域名只能选平台白名单；已有非空 Apple 配置引用不可原地改绑 |
+| 客户端 | 查看 ID、web_bff/ios 类型、名称、状态、协议、回调；改名、启停 | UI 不能新建或改回调；停用只阻止新登录，不撤销已有会话 |
+| 条款与政策 | terms/privacy/自定义 docKey；简中必填、英/繁可选；全文/摘要/版本查看；注册必选、立即/定时生效、继承上一版、预览发布 | 已发布不可编辑、删除、撤回，只能发新版；接受证据另经服务 API 查询 |
+| Apple 登录 | 配置团队、Key、Services ID、primaryAppId、subjectDomain、回调源、私钥及状态；轮换 Key、启停、预览确认 | 私钥加密、只进不出；已有身份坐标不可改绑；无删除配置 |
+
+profile 的高级参数使用明确值：
+
+- 保留期（秒）：`pendingRegistrationSeconds`、`terminalFlowSeconds`、`proofSeconds`、
+  `authEventSeconds`、`receiptSeconds`、`providerFailureSeconds`。
+- 限流（次/分钟）：`clientPerMinute`、`namespacePerMinute`。
+
+管理 UI 没有建号、批量导入、直接改标识/联系方式、设置/重置密码、解除失败锁定或直接删号按钮。
+页面删号通过 erase 请求受理；App 的对应服务能力见 [生命周期接口](end-user-lifecycle.md)。
+
+## 4. 容量与运维
+
+`portal.end_users` 是租户共享、无时间窗口的资源容量：每个新主体占 1 格，不按自然人去重。
+跨 App/siteKey 的不同主体分别计数；重复幂等登记不重复占额；archived 仍占额，deleted 归还。
+满容量只阻止新建，不踢已有用户。平台配置套餐/授予/增购，租户可看用量并设更严上限。
+不要用成员 `seatBased` 代替；业务资源的 `seatRoles` 是另一类配额，不能替代或重复结算平台身份容量。
+
+平台提供认证域名与邮箱验证码参数/就绪状态管理、按用户状态计数、清理 pending/failed/最旧积压巡检；
+跨租户清理项查询与重试另有运维 API。主体总行数包含墓碑，不等于容量用量。
+清理、处置日志归档验证和灾备重施属于平台运维；App 仍需消费自己的处置日志与隐私待办。
+
+## 5. 当前限制与验收
+
+- 托管方法是 password/apple；Google 未实现。`bind_apple`、`add_password`、`unlink_apple`
+  是保留用途，当前拒绝，不能仅凭字段存在实现绑定/解绑按钮。
+- Apple 按系统浏览器托管流程接入；当前未提供原生 Apple SDK 票据直接兑换终端会话的合同。
+  终端推送明确交付的契约是 Sites Web Push，不据成员能力推断终端 iOS APNs/FCM 可用。
+- 站点/设备面已有手机 OTP login/bind/recover、换号/解绑逻辑，但本仓当前没有生产短信 sender 注册，
+  会报 `channel_adapter_missing`；不是“填配置就能发短信”，也不是托管 profile 的登录方法。
+- 邮箱发送的是数字验证码，没有 magic-link 登录。验证邮箱只建立交易联系依据，不授予营销同意。
+- 删除是清身份凭据、撤销会话、释放容量并保留墓碑，再异步清通知与 Apple 授权；
+  身份已删、平台清理完成、跨系统请求办结分别判断。平台不承诺同步清空 App、备份或外部副本。
+- 对需跨库同步的 owner，直接写入受限；例如 `lms-school` 须走命令，用户中心不能直接封禁/解封。
+- 用户中心无本人注销、导出下载或 Web Push 设备管理按钮；这些通过本人/接入方接口提供。
+
+交付时实际验证：身份空间和客户端登记、注册/登录/找回/首改、错误 state/verifier/回调、
+刷新单飞与退出、单会话和全部撤销、封禁解封、跨租户/owner/site 拒绝、容量不足、
+隐私参与方回执与保留例外。若接入 Apple、短信、原生端或推送，分别验证真实供应商/设备/浏览器链路；
+源码能力和元数据不替代这些验收。

package/skills/portal-external-app/references/integration-contract.md

@@ -61,6 +61,8 @@ POST {PORTAL_INTROSPECT_URL}            # 如 http://portal-api:3000/api/tokens/
 
 **三种令牌来路 × 授权姿势**：
 
+以下表格描述成员/服务端点。若 App 还面向终端用户，按 §3.2 单独开放具名端点，不放宽这些后台闸。
+
 | 来路 | kind | user_id | 授权依据 |
 | --- | --- | --- | --- |
 | 自己前端（宿主注入 / callService） | user | 有 | scope + PID/ACL |
@@ -78,7 +80,7 @@ POST {PORTAL_INTROSPECT_URL}            # 如 http://portal-api:3000/api/tokens/
 | 建的人 | 平台管理员 / 你的 manifest 声明 | **租户自己的管理员**，不经平台 |
 | 典型用途 | 你的服务端调门户（files/notification/audit/seats…） | 该租户的采集器、脚本、CI **调你** |
 | 租户范围 | 由平台决定（可 `all`） | **恒 allowlist=[他自己那一个租户]**，请求体里出现别的租户 id 直接 `VALIDATION_FAILED` |
-| `azp` | manifest 里的 `serviceScopes.ownerAppKey` | = 租户选的那个已装 App 的 listingKey（**用户填不了、也不用填**） |
+| `azp` | 平台服务账号的 `ownerAppKey`；manifest 注册默认绑定自己的 `listingKey`（`serviceScopes` 是 scope 字符串数组） | = 租户选的那个已装 App 的 listingKey（**用户填不了、也不用填**） |
 | 可选 scope | `serviceScopes` / `privilegedServiceScopes`（可含 SERVICE_ONLY，走审批） | **只有 `scopes`（用户态那份清单）里、属于你自己命名空间的那些**；平台基础 scope 与 SERVICE_ONLY 一律不可选 |
 
 **⚠️ 对你的唯一要求，就在最后一行**：租户自助的 scope 池取的是**该租户安装你时那份 `apps.scopes`
@@ -104,6 +106,21 @@ POST {PORTAL_INTROSPECT_URL}            # 如 http://portal-api:3000/api/tokens/
 - **审计**落在该租户自己的审计日志里（创建/轮换/吊销/删除/每一次签发）。
 - 每租户有个数上限（默认 10）。
 
+### 3.2 终端用户端点：显式开放，使用本地业务授权
+
+平台另有 `kind=enduser` 身份，完整能力与接入见 [终端用户参考](end-users.md)。
+`@xgent/portal-server-sdk` 缺省只收 user/service；仅在顾客端点配置
+`acceptedPrincipalKinds:["enduser"]`、`acceptedCredentialTypes:["tdt"]`，校验 tenant、
+ownerAppKey、siteKey、目标 audience、endUserId 与本地业务权限。该主体没有成员
+user_id/role/groups/permissions，bypass/isPlatformAdmin 恒 false；不要套用成员管理员/PID 闸，
+也不要把整个后端都改成接收终端用户。
+
+HTTP 自省须保留 `end_user_id/session_id/owner_app_key/site_key/euv`；
+SDK 的 EndUserAuthContext 使用相应驼峰字段。终端用户正缓存上限 **50 秒**（不是上面的 55 秒），
+仍受 exp 截断，端到端撤销预算 60 秒；敏感操作可用 strictIntrospection。
+终端用户登录使用 `/api/public/end-user-auth/*`，不是成员 `/oauth/*`；
+业务资料留在 App，平台身份管理走专门的服务态权限。
+
 ## 4. 健康检查
 
 - **实现、出仓或发布镜像前必读 [health-contract.md](health-contract.md)**：有完整正确实现、错误示例与可执行验收命令。

package/skills/portal-external-app/references/native-clients.md

@@ -1,9 +1,12 @@
-# 原生客户端（iOS / Android / 桌面）接入
+# 门户成员的原生客户端（iOS / Android / 桌面）接入
 
 > 本文是可在 App 仓库独立使用的契约参考；能力以目标平台已发布版本和管理员配置为准。
 > `<portal-origin>` 指门户公开源（与 `PORTAL_BASE_URL` 相同，客户端用）；`<API_BASE_URL>` 是后端拿到的
 > 内部门户 API 地址（服务端调用用）；`<key>` 指你的 listingKey。
 
+本文只讲门户成员 `kind=user`。顾客、学生等 `kind=enduser` 使用独立的
+[终端用户认证协议](end-user-auth.md)，不能套用下面的成员 OAuth、席位、角色或推送设备接口。
+
 原生客户端是**你这个 App 的另一种前端**：它拿到的是和 iframe 前端同一种用户态 TDT，打你
 后端的 `/svc/<key>/…`，后端照常走四道闸（[integration-contract.md](integration-contract.md) §3）。
 区别只在**令牌怎么到手**：iframe 由宿主注入，原生客户端自己走 OAuth。
@@ -12,7 +15,7 @@
 
 | 问题 | 结论 |
 | --- | --- |
-| 推荐哪种登录方式？ | **授权码 + PKCE（S256），在系统浏览器里完成**，`publicClient: true`，不带任何密钥。门户只提供这一条用户登录路径 |
+| 推荐哪种登录方式？ | **授权码 + PKCE（S256），在系统浏览器里完成**，`publicClient: true`，不带任何密钥。这是本文门户成员的原生登录路径 |
 | 用户长期凭证能当设备凭证吗？ | **不能**。它是绑定「租户 + 用户 + 目标 App」的 bearer 密钥，没有设备绑定，换不出 TDT / 刷新令牌，资源端默认拒收。设备上的用户用授权码登录；无人值守设备用服务账号 |
 | 用户被移出 / 停用后 60 秒内失效？ | **成立，前提是后端按契约逐请求自省**（SDK 正缓存上限 55 s）。刷新令牌在下一次刷新时被拒并作废，所以客户端以后端 401 为准（§3） |
 | 有不依赖用户登录的成员查询 / 事件推送吗？ | **查询有，成员事件推送没有**。服务账号可逐租户列在职成员、实时查单个成员状态；门户不推送成员加入/移出/停用事件（§4） |
@@ -116,7 +119,7 @@ DELETE <portal-origin>/api/me/devices/:id   # 退出登录时调
 ## 2. 设备凭证：别拿用户长期凭证顶
 
 门户的**用户长期凭证**（`xuak_` 前缀，用户在门户个人资料的「用户凭证」页或经 App 委托签发）是为 CLI、MCP、
-个人自动化这类**机器入口**设计的：
+个人自动化这类**机器入口**设计的。接入时使用 [CLI 与用户访问密钥契约](cli-user-keys.md) 的受审 `cliAccess` 声明和标准绑定协议：
 
 - 绑定**租户 + 用户 + 目标 App**，是纯 bearer 密钥：没有设备字段、没有持有证明，谁拿到谁能用；
 - **换不出** TDT 或刷新令牌，不能顶替登录；

package/skills/portal-external-app/references/quota-and-seats.md

@@ -2,6 +2,10 @@
 
 > 有「每租户最多能建几个 X」这类诉求时读本文。App 声明角色和用量指标，平台管理员维护套餐数值；不需要访问门户源码。
 
+若管理的是**平台托管终端身份**，先读 [终端用户容量与边界](end-users.md)：使用租户共享的
+`portal.end_users`，创建占用、归档继续占用、删除归还，不按下面两种模型重新造一份身份计数。
+本文 seatBased 面向门户成员，seatRoles 面向 App 自管业务资源；两者与平台身份容量分开判断。
+
 ## 0. 红线
 
 **外部服务不自建配额/套餐/计费。** 配额的唯一事实源是平台的套餐矩阵。对方在自己库里存一份

package/skills/portal-external-app/references/registration-and-onebox.md

@@ -14,6 +14,9 @@
     `privilegedServiceScopes` 里的，租户面**一条也勾不到**（见 integration-contract.md §3.1）。
     `scopeLabels` 同时是那个勾选列表的正文——不写就只显示裸 scope 串。
 - 关系：`dependencies`、`exchangeTargets`、`serviceBaseUrl`（`/svc/<listingKey>`）
+- 终端身份：`endUserRealms:{"mode":"fixed","siteKeys":["customers"]}` 或 `{"mode":"dynamic"}`，
+  声明本 App 的身份空间范围；不创建托管 profile/client、不授额度，也不是成员的 publicClient。
+  顾客/学生认证与生命周期按 [终端用户接入](end-users.md) 配置；endusers.* 等服务权限经特权审批申请。
 - 服务态与计量：`usageReporter`（true ⇒ SA 得 `client_credentials` + `usage.report`）、`serviceScopes`（服务态 scope；SERVICE_ONLY **永拒**）、`privilegedServiceScopes`（SERVICE_ONLY 的**申请**：`[{scope, reason}]`，reason 必填，最高治理档、审批逐条确认后授予）、`usageMetrics`（用量指标声明：key 前缀必须=listingKey、金额单位不开放；治理档，批准后 ingest 才认这些 key）
 - 部署/运维：`requiredEnvNotes`（`{ 键名: 说明 }`，给 `requiredEnv` 里需要解释的键写一句给审批人看的话，≤200 字；纯展示、自动档）、`requiredEnv`（部署所需 env 的**键名**清单，值永远由平台配；元素可写 `{ key, renamedFrom }` 表达改名。键集合一变提案转入「发布审核」，且**批准前门户会比对 `descriptor.env ∪ envFile` 的键集合，缺了拒绝生效**（`REQUIRED_ENV_MISSING`，提案留 pending））、`deployDescriptor`（`image` 归自动档、`hostPort` 归平台不算变更，**其余一切属治理档**）、`deployRequirements`（后端要跑在**什么样的机器**上：`{region?, size?, gpu?, network?}`，只写**名字与档位**，网段/IP/URL 提交即拒；批准时按目标环境**当时**的资源池逐维匹配，不满足则拒绝生效、提案留待审，通过则把首次落点固定住；需要 `deployDescriptor`）、`requiredServices`（运行所需的**外部服务** `[{name, kind, note?}]`，身份是 `(kind, name)` 二元组；批准时比对本环境**已登记**的「已具备服务」，未登记或缺条目则拒绝生效 —— 登记表核对已有服务；支持自动供给的类型按选定档案建资源并注入约定键，不收 `envKey`）
 
@@ -42,6 +45,8 @@
 
 越界 → `VALIDATION_FAILED`。App 命名空间 scope 随清单入库，**不用改门户代码**。
 
+CLI / MCP / 个人自动化使用用户访问密钥时，还须声明独立的 `cliAccess`，不能把整份 `scopes` 当作用户密钥上限。新增、修改和撤回经过发布审批；绑定与发现按 [CLI 用户密钥契约](cli-user-keys.md)，无需在门户登记 App 专属权限分支。先确认目标门户已部署此能力。
+
 ⚠️ 规则 3 **读写不分**：背书的是整个命名空间，`files.write` 与 `files.read` 同一条待遇，
 没有「写要额外批一次」这回事。别人的 App 只声明了读，那是它自己的业务选择（它的写面不
 代表用户），不是平台对你的限制 —— 照抄别人的清单当规矩用，会把一个本来合法的功能砍掉。

package/skills/portal-micro-app/SKILL.md

@@ -7,6 +7,10 @@ description: '用于开发、修改或排查 XGENT Portal 的 iframe 微应用
 
 微应用是被 Portal 以沙箱 iframe 嵌入的普通 Web 页面：**不自己实现登录、不持有 App Secret**，身份由宿主经 postMessage 握手注入。本文件是工作流与红线；具体契约按需读 `references/`（可整目录拷到任何 App repo 使用）。
 
+这里的宿主身份是门户成员。若同一个产品另有面向顾客/学生的独立网站或原生客户端，
+终端身份的注册、登录、会话与隐私治理读 `portal-external-app` skill 的 `references/end-users.md`；
+不能把成员 SDK 握手、角色或成员 OAuth 直接当作终端用户认证。
+
 
 `/apps/<key>/` 是线上前端挂载 URL；本文的 `references/` 相对于本 skill 目录。
 

package/skills/prd/SKILL.md

@@ -242,6 +242,6 @@ R4  待拍板    → 依赖「是否面向全员」的决策,已问
 
 ## 项目状态回写
 
-若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
+若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按仓内协议更新受影响对象的当前状态与来源链接，必要时维护索引；v4 日常直接更新当前页，事件留存条件或旧版事件要求以仓内协议为准；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
 
 登记 PRD 的实际路径、版本、文档状态及已明确的需求/计划关联；不把已成文或 SPMS 已录入登记为已实施。

package/skills/resolve-blocked/SKILL.md

@@ -122,6 +122,6 @@ $resolve-blocked goal/LOGIN.md，B-03 的供应商答复已到：<答复要点>
 
 ## 项目状态回写
 
-若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
+若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按仓内协议更新受影响对象的当前状态与来源链接，必要时维护索引；v4 日常直接更新当前页，事件留存条件或旧版事件要求以仓内协议为准；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
 
 登记计划修订后的版本与就绪状态、决策记录路径及已解除/剩余阻塞；不把阻塞解除记成计划已实施。

package/skills/review-code/SKILL.md

@@ -95,6 +95,6 @@ $review-code BASE_SHA..FIXED_SHA，对照 goal/LOGIN.code-review.md 复审修复
 
 ## 项目状态回写
 
-若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
+若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按仓内协议更新受影响对象的当前状态与来源链接，必要时维护索引；v4 日常直接更新当前页，事件留存条件或旧版事件要求以仓内协议为准；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
 
 每次实际评审登记独立评审 ID、精确 base/target 或工作树指纹、范围、结论和报告路径；计划关联以实际输入为准，允许没有计划的评审。复审关联前轮，不覆盖旧结论；不把 patch is correct 登记为已验收、已合并或已发布。