Skip to content

Commit 77af789

Browse files
benjinusbenjinus
committed
feat(phase-14): implement TA-P14-005 sdk parity convergence
1 parent 7b30ef9 commit 77af789

13 files changed

+414
-12
lines changed

‎docs/implementation/phase-14/README.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# TelAgent v1 Phase 14 执行产出（产品聚焦与缺陷收敛）
22

3-
- 文档版本：v1.2
3+
- 文档版本：v1.3
44
- 状态：Phase 14 执行中
55
- 最后更新：2026-03-03
66

@@ -19,7 +19,7 @@ Phase 14 回归 P2P 应用核心体验，聚焦“可用性、正确性、收敛
1919
| TA-P14-002 | DONE | 删除 Web 运维面板，保留核心聊天流程 |
2020
| TA-P14-003 | DONE | 消息拉取稳定游标改造（替代 offset 风险） |
2121
| TA-P14-004 | DONE | direct 会话参与方与访问约束强化 |
22-
| TA-P14-005 | TODO | TS/Python SDK 核心行为收敛与错误语义统一 |
22+
| TA-P14-005 | DONE | TS/Python SDK 核心行为收敛与错误语义统一 |
2323
| TA-P14-006 | TODO | 回归验证与 Gate 收口 |
2424

2525
## 3. 当前证据
@@ -28,6 +28,7 @@ Phase 14 回归 P2P 应用核心体验，聚焦“可用性、正确性、收敛
2828
- `ta-p14-002-web-ops-panel-removal-2026-03-03.md`
2929
- `ta-p14-003-stable-pull-cursor-2026-03-03.md`
3030
- `ta-p14-004-direct-session-acl-2026-03-03.md`
31+
- `ta-p14-005-sdk-parity-and-error-semantics-2026-03-03.md`
3132
- `logs/2026-03-03-p14-web-build.txt`
3233
- `logs/2026-03-03-p14-web-ops-removal-check.txt`
3334
- `logs/2026-03-03-p14-node-build.txt`
@@ -36,6 +37,10 @@ Phase 14 回归 P2P 应用核心体验，聚焦“可用性、正确性、收敛
3637
- `logs/2026-03-03-p14-node-build-ta-p14-004.txt`
3738
- `logs/2026-03-03-p14-node-test-ta-p14-004.txt`
3839
- `logs/2026-03-03-p14-direct-session-acl-check-run.txt`
40+
- `logs/2026-03-03-p14-sdk-ts-test.txt`
41+
- `logs/2026-03-03-p14-sdk-python-test.txt`
42+
- `logs/2026-03-03-p14-sdk-parity-check-run.txt`
3943
- `manifests/2026-03-03-p14-web-ops-removal-check.json`
4044
- `manifests/2026-03-03-p14-stable-pull-cursor-check.json`
4145
- `manifests/2026-03-03-p14-direct-session-acl-check.json`
46+
- `manifests/2026-03-03-p14-sdk-parity-check.json`

‎docs/implementation/phase-14/logs/2026-03-03-p14-sdk-parity-check-run.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
[TA-P14-005] coreMethodParityPass=true
2+
[TA-P14-005] apiPrefixParityPass=true
3+
[TA-P14-005] errorModelParityPass=true
4+
[TA-P14-005] identityEncodingParityPass=true
5+
[TA-P14-005] directAclErrorSemanticsParityPass=true
6+
[TA-P14-005] decision=PASS
7+
[TA-P14-005] output=/Users/xiasenhai/Workspace/OpenClaw/telagent/docs/implementation/phase-14/manifests/2026-03-03-p14-sdk-parity-check.json

‎docs/implementation/phase-14/logs/2026-03-03-p14-sdk-python-test.txt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
....
2+
----------------------------------------------------------------------
3+
Ran 4 tests in 2.116s
4+
5+
OK

‎docs/implementation/phase-14/logs/2026-03-03-p14-sdk-ts-test.txt‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
2+
> @telagent/sdk@0.1.0 pretest /Users/xiasenhai/Workspace/OpenClaw/telagent/packages/sdk
3+
> pnpm build
4+
5+
6+
> @telagent/sdk@0.1.0 build /Users/xiasenhai/Workspace/OpenClaw/telagent/packages/sdk
7+
> tsc -p tsconfig.json
8+
9+
10+
> @telagent/sdk@0.1.0 test /Users/xiasenhai/Workspace/OpenClaw/telagent/packages/sdk
11+
> node --test dist/**/*.test.js
12+
13+
✔ TA-P11-008 SDK quickstart covers create-group and send/pull message flow (44.873857ms)
14+
✔ TA-P11-008 SDK maps RFC7807 errors to TelagentSdkError (9.490601ms)
15+
✔ TA-P14-005 SDK getIdentity encodes DID path segment (4.819717ms)
16+
✔ TA-P14-005 SDK maps direct ACL FORBIDDEN RFC7807 to TelagentSdkError (5.411714ms)
17+
ℹ tests 4
18+
ℹ suites 0
19+
ℹ pass 4
20+
ℹ fail 0
21+
ℹ cancelled 0
22+
ℹ skipped 0
23+
ℹ todo 0
24+
ℹ duration_ms 206.989866

‎docs/implementation/phase-14/manifests/2026-03-03-p14-sdk-parity-check.json‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
{
2+
"phase": "Phase 14",
3+
"taskId": "TA-P14-005",
4+
"generatedAt": "2026-03-03T15:05:48.690Z",
5+
"summary": {
6+
"coreMethodParityPass": true,
7+
"apiPrefixParityPass": true,
8+
"errorModelParityPass": true,
9+
"identityEncodingParityPass": true,
10+
"directAclErrorSemanticsParityPass": true
11+
},
12+
"decision": "PASS",
13+
"details": {
14+
"files": {
15+
"tsSdkPath": "/Users/xiasenhai/Workspace/OpenClaw/telagent/packages/sdk/src/index.ts",
16+
"pySdkPath": "/Users/xiasenhai/Workspace/OpenClaw/telagent/packages/sdk-python/telagent_sdk/client.py",
17+
"tsTestPath": "/Users/xiasenhai/Workspace/OpenClaw/telagent/packages/sdk/src/index.test.ts",
18+
"pyTestPath": "/Users/xiasenhai/Workspace/OpenClaw/telagent/packages/sdk-python/tests/test_client.py"
19+
},
20+
"methodChecks": [
21+
{
22+
"ts": "getSelfIdentity",
23+
"py": "get_self_identity",
24+
"tsExists": true,
25+
"pyExists": true
26+
},
27+
{
28+
"ts": "getIdentity",
29+
"py": "get_identity",
30+
"tsExists": true,
31+
"pyExists": true
32+
},
33+
{
34+
"ts": "createGroup",
35+
"py": "create_group",
36+
"tsExists": true,
37+
"pyExists": true
38+
},
39+
{
40+
"ts": "sendMessage",
41+
"py": "send_message",
42+
"tsExists": true,
43+
"pyExists": true
44+
},
45+
{
46+
"ts": "pullMessages",
47+
"py": "pull_messages",
48+
"tsExists": true,
49+
"pyExists": true
50+
}
51+
],
52+
"apiPrefix": {
53+
"tsApiPrefixCount": 13,
54+
"pyApiPrefixCount": 5
55+
}
56+
}
57+
}

‎docs/implementation/phase-14/ta-p14-005-sdk-parity-and-error-semantics-2026-03-03.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# TA-P14-005 TS/Python SDK 行为收敛与错误语义统一（2026-03-03）
2+
3+
- Task ID：TA-P14-005
4+
- 阶段：Phase 14
5+
- 状态：DONE
6+
- 负责人角色：DX + Backend + QA
7+
8+
## 1. 目标
9+
10+
收敛 TypeScript 与 Python SDK 在核心行为和错误语义上的高优先级差异，确保 direct ACL 新能力上线后，两端 SDK 均能一致处理 `FORBIDDEN + RFC7807`。
11+
12+
## 2. 实现摘要
13+
14+
1. Python SDK 对齐 DID 路径编码语义：
15+
- `get_identity` 改为 URL 编码 DID path segment（与 TS `encodeURIComponent` 一致）。
16+
2. SDK 错误语义收敛：
17+
- TS/Python 测试均覆盖 direct ACL 场景下 `403 + application/problem+json + code=FORBIDDEN` 映射。
18+
3. parity 专项校验：
19+
- 新增 `run-phase14-sdk-parity-check.ts`；
20+
- 校验方法覆盖、`/api/v1/*` 前缀、错误模型、DID 编码一致性、direct ACL 错误语义一致性。
21+
22+
## 3. 变更文件
23+
24+
- `packages/sdk/src/index.test.ts`
25+
- `packages/sdk-python/telagent_sdk/client.py`
26+
- `packages/sdk-python/tests/test_client.py`
27+
- `packages/node/scripts/run-phase14-sdk-parity-check.ts`
28+
29+
## 4. 验证
30+
31+
1. TS SDK 测试：
32+
- `corepack pnpm --filter @telagent/sdk test`
33+
2. Python SDK 测试：
34+
- `python3 -m unittest packages/sdk-python/tests/test_client.py`
35+
3. 专项脚本：
36+
- `corepack pnpm --filter @telagent/node exec tsx scripts/run-phase14-sdk-parity-check.ts`
37+
38+
## 5. 证据
39+
40+
- TS 测试日志：`docs/implementation/phase-14/logs/2026-03-03-p14-sdk-ts-test.txt`
41+
- Python 测试日志：`docs/implementation/phase-14/logs/2026-03-03-p14-sdk-python-test.txt`
42+
- 专项检查日志：`docs/implementation/phase-14/logs/2026-03-03-p14-sdk-parity-check-run.txt`
43+
- 机读清单：`docs/implementation/phase-14/manifests/2026-03-03-p14-sdk-parity-check.json`

‎docs/implementation/telagent-v1-iteration-board.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -225,8 +225,9 @@
225225
- 已完成：`TA-P14-002`（默认 Web 运维面板下线，回归核心聊天流程）
226226
- 已完成：`TA-P14-003`（消息拉取稳定游标改造，修复 cleanup/retraction 导致分页跳项风险）
227227
- 已完成：`TA-P14-004`（direct 会话参与方访问控制，非参与方写入返回 RFC7807）
228+
- 已完成：`TA-P14-005`（TS/Python SDK 行为与错误语义收敛，覆盖 FORBIDDEN direct ACL 场景）
228229
- 已规划：`TA-P15-001`（WebApp 工业级规划总纲冻结）
229-
- 下一批 Ready：执行 `TA-P14-005`（SDK 行为收敛）与 `TA-P14-006`（Phase 14 Gate 收口）。
230+
- 下一批 Ready：执行 `TA-P14-006`（Phase 14 Gate 收口）。
230231

231232
## 4.2 Blockers（2026-03-03 更新）
232233

@@ -416,7 +417,7 @@
416417
- `TA-P14-002`：DONE（默认 Web 运维面板下线，见 `docs/implementation/phase-14/ta-p14-002-web-ops-panel-removal-2026-03-03.md`）。
417418
- `TA-P14-003`：DONE（消息拉取稳定游标改造，见 `docs/implementation/phase-14/ta-p14-003-stable-pull-cursor-2026-03-03.md`）。
418419
- `TA-P14-004`：DONE（direct 会话参与方访问控制，见 `docs/implementation/phase-14/ta-p14-004-direct-session-acl-2026-03-03.md`）。
419-
- `TA-P14-005`：TODO（TS/Python SDK 行为收敛）。
420+
- `TA-P14-005`：DONE（TS/Python SDK 行为收敛，见 `docs/implementation/phase-14/ta-p14-005-sdk-parity-and-error-semantics-2026-03-03.md`）。
420421
- `TA-P14-006`：TODO（Phase 14 Gate 收口）。
421422
- 阶段状态：Phase 14 执行中（产品核心能力与高优缺陷收敛）。
422423

‎docs/implementation/telagent-v1-task-breakdown.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -149,7 +149,7 @@ flowchart LR
149149
| TA-P14-002 | Phase 14 | 删除默认 Web 运维面板，保留核心聊天流程 | Frontend | 1 | TA-P14-001 | web app cleanup + build log | 默认界面仅保留核心链路入口，构建通过 | DONE |
150150
| TA-P14-003 | Phase 14 | 消息拉取稳定游标改造（替代 offset 风险） | Backend + QA | 1.5 | TA-P14-001 | pull cursor upgrade + tests | 清理/撤回场景下分页稳定无重复/跳项 | DONE |
151151
| TA-P14-004 | Phase 14 | direct 会话访问控制强化（参与方约束） | Backend + Security | 1.5 | TA-P14-001 | direct ACL guard + tests | 非参与方消息写入被拒绝并返回 RFC7807 | DONE |
152-
| TA-P14-005 | Phase 14 | TS/Python SDK 核心行为收敛 | DX + Backend + QA | 1 | TA-P14-003, TA-P14-004 | sdk parity extension + checks | 参数、错误语义、返回结构一致 | TODO |
152+
| TA-P14-005 | Phase 14 | TS/Python SDK 核心行为收敛 | DX + Backend + QA | 1 | TA-P14-003, TA-P14-004 | sdk parity extension + checks | 参数、错误语义、返回结构一致 | DONE |
153153
| TA-P14-006 | Phase 14 | Phase 14 Gate 评审与收口 | TL + QA | 0.5 | TA-P14-002, TA-P14-003, TA-P14-004, TA-P14-005 | gate 结论文档 | Phase 14 正式关闭 | TODO |
154154
| TA-P15-001 | Phase 15 | Web App 工业级规划总纲冻结 | TL + FE + BE + QA + DX | 1 | TA-P14-001 | industrial planning doc | 功能/架构/平台/质量主线冻结 | DONE |
155155
| TA-P15-002 | Phase 15 | 功能域与 IA 设计（会话/消息/群组/身份） | FE + Product + BE | 2 | TA-P15-001 | IA + feature matrix | 关键用户旅程与页面结构冻结 | TODO |
@@ -358,8 +358,8 @@ flowchart LR
358358
| TA-P14-002 | DONE | `docs/implementation/phase-14/ta-p14-002-web-ops-panel-removal-2026-03-03.md`, `packages/web/src/index.html`, `packages/web/src/main.js` | 无 | 进入 `TA-P14-003`（消息拉取稳定游标改造） |
359359
| TA-P14-003 | DONE | `docs/implementation/phase-14/ta-p14-003-stable-pull-cursor-2026-03-03.md`, `packages/node/src/services/message-service.ts`, `packages/node/src/storage/message-repository.ts`, `packages/node/src/storage/postgres-message-repository.ts`, `packages/node/src/services/message-service.test.ts`, `packages/node/src/phase4-e2e.test.ts`, `packages/node/scripts/run-phase14-stable-pull-cursor-check.ts`, `docs/implementation/phase-14/logs/2026-03-03-p14-node-build.txt`, `docs/implementation/phase-14/logs/2026-03-03-p14-node-test.txt`, `docs/implementation/phase-14/logs/2026-03-03-p14-stable-pull-cursor-check-run.txt`, `docs/implementation/phase-14/manifests/2026-03-03-p14-stable-pull-cursor-check.json` | 无 | 进入 `TA-P14-004`（direct 会话参与方访问控制） |
360360
| TA-P14-004 | DONE | `docs/implementation/phase-14/ta-p14-004-direct-session-acl-2026-03-03.md`, `packages/node/src/services/message-service.ts`, `packages/node/src/storage/message-repository.ts`, `packages/node/src/storage/postgres-message-repository.ts`, `packages/node/src/services/message-service.test.ts`, `packages/node/src/phase4-e2e.test.ts`, `packages/node/scripts/run-phase14-direct-session-acl-check.ts`, `docs/implementation/phase-14/logs/2026-03-03-p14-node-build-ta-p14-004.txt`, `docs/implementation/phase-14/logs/2026-03-03-p14-node-test-ta-p14-004.txt`, `docs/implementation/phase-14/logs/2026-03-03-p14-direct-session-acl-check-run.txt`, `docs/implementation/phase-14/manifests/2026-03-03-p14-direct-session-acl-check.json` | 无 | 进入 `TA-P14-005`（TS/Python SDK 行为收敛） |
361-
| TA-P14-005 | TODO | `docs/implementation/phase-14/README.md` | 无 | TS/Python SDK 行为与错误语义收敛并补齐专项校验 |
362-
| TA-P14-006 | TODO | `docs/implementation/phase-14/README.md` | 无 | 阶段回归与 Gate 收口 |
361+
| TA-P14-005 | DONE | `docs/implementation/phase-14/ta-p14-005-sdk-parity-and-error-semantics-2026-03-03.md`, `packages/sdk/src/index.test.ts`, `packages/sdk-python/telagent_sdk/client.py`, `packages/sdk-python/tests/test_client.py`, `packages/node/scripts/run-phase14-sdk-parity-check.ts`, `docs/implementation/phase-14/logs/2026-03-03-p14-sdk-ts-test.txt`, `docs/implementation/phase-14/logs/2026-03-03-p14-sdk-python-test.txt`, `docs/implementation/phase-14/logs/2026-03-03-p14-sdk-parity-check-run.txt`, `docs/implementation/phase-14/manifests/2026-03-03-p14-sdk-parity-check.json` | 无 | 进入 `TA-P14-006`（Phase 14 Gate 收口） |
362+
| TA-P14-006 | TODO | `docs/implementation/phase-14/README.md` | 无 | 执行 Phase 14 汇总回归与 Gate 文档收口 |
363363

364364
## 21. Phase 15 Web App 工业级设计与多平台建设（2026-03-03）
365365

‎docs/telagent-v1-complete-functional-summary-2026-03-03.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# TelAgent v1 完整功能总结与详细功能梳理
22

3-
- 文档版本：v1.4
3+
- 文档版本：v1.5
44
- 编写日期：2026-03-03
55
- 适用范围：TelAgent v1（Phase 0 ~ Phase 13 + Release）
66
- 当前总体状态：`Phase 0~13 全部 Gate=PASS`，`Phase 14=IN_PROGRESS`，`Phase 15=PLANNED`，`Release(v0.1.0)=PASS`
@@ -28,7 +28,7 @@ TelAgent v1 已完成从规范冻结、链上群组确权、链下消息投递
2828
| Phase 11 | PASS | 完成 v1.1 安全与运营增强（DomainProof 挑战、pinning、DLQ、密钥生命周期、SDK TS、Web v2） | `docs/implementation/gates/phase-11-gate.md` |
2929
| Phase 12 | PASS | 完成 v1.2 候选能力（审计快照、revoked DID 会话隔离、SLO 自动化、SDK Python、Web v2.1、多节点密钥轮换） | `docs/implementation/gates/phase-12-gate.md` |
3030
| Phase 13 | PASS | 完成 v0.2.0 稳定化与可运营增强（规模压测、灾备演练、审计归档签名、联邦重放保护、SDK 一致性） | `docs/implementation/gates/phase-13-gate.md` |
31-
| Phase 14 | IN_PROGRESS | 产品聚焦：默认 Web 界面下线运维面板，完成稳定游标改造与 direct 会话访问控制强化，继续高优缺陷收敛 | `docs/implementation/phase-14/README.md` |
31+
| Phase 14 | IN_PROGRESS | 产品聚焦：默认 Web 界面下线运维面板，完成稳定游标改造、direct 会话访问控制与 SDK 行为收敛，继续 Gate 收口 | `docs/implementation/phase-14/README.md` |
3232
| Phase 15 | PLANNED | Web App 工业级设计与多平台建设（功能、架构、质量、发布体系） | `docs/implementation/phase-15/README.md` |
3333

3434
## 3. 强约束落实情况（全局）
@@ -406,8 +406,9 @@ Node API 已形成完整资源域，统一在 `/api/v1/*`：
406406
- 默认 Web App 已移除运维面板，专注核心业务路径；
407407
- `TA-P14-003` 已完成：`messages/pull` 游标从 offset 语义升级为稳定 keyset 语义；
408408
- `TA-P14-004` 已完成：direct 会话仅允许参与方写入，非参与方返回 `FORBIDDEN + RFC7807`；
409+
- `TA-P14-005` 已完成：TS/Python SDK 在 DID 编码与 direct ACL 错误语义上完成收敛；
409410
- Web App 工业级与多平台能力整体转入 Phase 15 实施。
410411

411412
## 9. 最终结论
412413

413-
截至 2026-03-03，TelAgent v1 已具备可验收、可观测、可运维、可扩展的完整功能闭环，且所有阶段 Gate 与发布证据链完整可追溯；Phase 13 已关闭（PASS），Phase 14 已完成 `TA-P14-001~004` 并继续执行缺陷收敛，Phase 15 将承接 Web App 工业级与多平台建设。
414+
截至 2026-03-03，TelAgent v1 已具备可验收、可观测、可运维、可扩展的完整功能闭环，且所有阶段 Gate 与发布证据链完整可追溯；Phase 13 已关闭（PASS），Phase 14 已完成 `TA-P14-001~005` 并进入 Gate 收口准备，Phase 15 将承接 Web App 工业级与多平台建设。

0 commit comments

Comments
 (0)