Skip to content

Commit e500400

Browse files
benjinusbenjinus
committed
feat(phase-16): implement TA-P16-001 web runtime shell baseline
1 parent 6b39098 commit e500400

17 files changed

+1807
-686
lines changed

‎docs/README.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,9 @@
2727
21. [Phase 13 执行产出（TA-P13-*）](./implementation/phase-13/README.md)
2828
22. [Phase 14 执行产出（TA-P14-*）](./implementation/phase-14/README.md)
2929
23. [Phase 15 规划产出（TA-P15-*）](./implementation/phase-15/README.md)
30-
24. [Phase Gate 模板与记录](./implementation/gates/README.md)
31-
25. [TL 广播模板（给所有 agent）](./implementation/telagent-v1-tl-broadcast-template.md)
30+
24. [Phase 16 执行产出（TA-P16-*）](./implementation/phase-16/README.md)
31+
25. [Phase Gate 模板与记录](./implementation/gates/README.md)
32+
26. [TL 广播模板（给所有 agent）](./implementation/telagent-v1-tl-broadcast-template.md)
3233

3334
## 2) 文档用途
3435

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

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# TelAgent v1 Phase 16 执行产出（Web App 实装冲刺）
2+
3+
- 文档版本：v1.0
4+
- 状态：IN_PROGRESS（`TA-P16-001` 已完成，Phase 16 持续执行中）
5+
- 最后更新：2026-03-03
6+
7+
## 1. 阶段定位
8+
9+
Phase 16 进入 Web App 实装阶段，目标是把 Phase 15 冻结的方案落为可运行、可验证、可迭代的客户端代码基线。
10+
11+
## 2. 任务清单
12+
13+
| Task ID | 状态 | 说明 |
14+
| --- | --- | --- |
15+
| TA-P16-001 | DONE | Web App 路由化壳层 + 统一 API 客户端 + RFC7807 错误处理 + Web 单测基线 |
16+
| TA-P16-002 | TODO | 会话域增强：游标拉取体验、消息列表稳定刷新、失败重试与状态提示 |
17+
| TA-P16-003 | TODO | 群组域增强：建群/邀请/接受流程校验与链状态联动视图 |
18+
| TA-P16-004 | TODO | 身份与节点诊断页增强：DID 解析、节点健康与版本信息可观测 |
19+
| TA-P16-005 | TODO | Web 端契约回归与场景化测试增强（含 RFC7807 异常分支） |
20+
| TA-P16-006 | TODO | 交付质量收口：构建产物校验、专项脚本与发布前检查 |
21+
| TA-P16-007 | TODO | Phase 16 Gate 评审与阶段收口 |
22+
23+
## 3. 当前证据目录
24+
25+
- 任务文档：
26+
- `ta-p16-001-web-app-runtime-shell-and-api-client-2026-03-03.md`
27+
- 日志：
28+
- `logs/2026-03-03-p16-web-build.txt`
29+
- `logs/2026-03-03-p16-web-test.txt`
30+
- `logs/2026-03-03-p16-web-runtime-shell-check-run.txt`
31+
- 机读清单：
32+
- `manifests/2026-03-03-p16-web-runtime-shell-check.json`
33+
34+
## 4. 当前进展
35+
36+
- `TA-P16-001`：DONE
37+
- `TA-P16-002`：TODO
38+
- `TA-P16-003`：TODO
39+
- `TA-P16-004`：TODO
40+
- `TA-P16-005`：TODO
41+
- `TA-P16-006`：TODO
42+
- `TA-P16-007`：TODO
43+
- 下一步：进入 `TA-P16-002`（会话域增强与交互稳定性补齐）。

‎docs/implementation/phase-16/logs/2026-03-03-p16-web-build.txt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
2+
> @telagent/web@0.1.0 build /Users/xiasenhai/Workspace/OpenClaw/telagent/packages/web
3+
> node scripts/build.mjs
4+
5+
web assets copied to dist

‎docs/implementation/phase-16/logs/2026-03-03-p16-web-runtime-shell-check-run.txt‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
[TA-P16-001] routeShellReady=true
2+
[TA-P16-001] apiPrefixGuardReady=true
3+
[TA-P16-001] didValidationReady=true
4+
[TA-P16-001] rfc7807HandlingReady=true
5+
[TA-P16-001] webTestsReady=true
6+
[TA-P16-001] requiredTokensChecked=22
7+
[TA-P16-001] decision=PASS
8+
[TA-P16-001] output=/Users/xiasenhai/Workspace/OpenClaw/telagent/docs/implementation/phase-16/manifests/2026-03-03-p16-web-runtime-shell-check.json

‎docs/implementation/phase-16/logs/2026-03-03-p16-web-test.txt‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
2+
> @telagent/web@0.1.0 test /Users/xiasenhai/Workspace/OpenClaw/telagent/packages/web
3+
> node --test test/**/*.test.js
4+
5+
✔ assertApiV1Path only accepts /api/v1/* (1.27709ms)
6+
✔ isDidClaw validates did:claw format (0.26948ms)
7+
✔ toCiphertextHex encodes utf8 text (0.306537ms)
8+
✔ createEnvelopeId builds deterministic prefix (0.423519ms)
9+
✔ request parses RFC7807 errors to ApiProblemError (22.929058ms)
10+
✔ getData/postData extract envelope data (1.447986ms)
11+
✔ sendMessage enforces did:claw sender (0.212857ms)
12+
ℹ tests 7
13+
ℹ suites 0
14+
ℹ pass 7
15+
ℹ fail 0
16+
ℹ cancelled 0
17+
ℹ skipped 0
18+
ℹ todo 0
19+
ℹ duration_ms 108.019469

‎docs/implementation/phase-16/manifests/2026-03-03-p16-web-runtime-shell-check.json‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
{
2+
"phase": "Phase 16",
3+
"taskId": "TA-P16-001",
4+
"generatedAt": "2026-03-03T16:10:35.894Z",
5+
"summary": {
6+
"routeShellReady": true,
7+
"apiPrefixGuardReady": true,
8+
"didValidationReady": true,
9+
"rfc7807HandlingReady": true,
10+
"webTestsReady": true,
11+
"requiredTokensChecked": 22
12+
},
13+
"decision": "PASS",
14+
"details": {
15+
"htmlChecks": [
16+
"<div id=\"app\"></div>",
17+
"<script type=\"module\" src=\"./main.js\"></script>"
18+
],
19+
"apiClientChecks": [
20+
"assertApiV1Path(path)",
21+
"path.startsWith('/api/v1/')",
22+
"application/problem+json",
23+
"did:claw:*",
24+
"class ApiProblemError extends Error"
25+
],
26+
"jsChecks": [
27+
"function parseRoute(hashValue)",
28+
"return { name: 'sessions' }",
29+
"async function pullMessages()",
30+
"async function sendMessage()",
31+
"async function createGroup()",
32+
"async function inviteMember()",
33+
"async function acceptInvite()",
34+
"async function resolveIdentity()"
35+
],
36+
"cssChecks": [
37+
".shell",
38+
".session-layout",
39+
".inspect-panel",
40+
"@media (max-width: 1180px)"
41+
],
42+
"testChecks": [
43+
"assertApiV1Path only accepts /api/v1/*",
44+
"request parses RFC7807 errors to ApiProblemError",
45+
"sendMessage enforces did:claw sender"
46+
]
47+
}
48+
}

‎docs/implementation/phase-16/ta-p16-001-web-app-runtime-shell-and-api-client-2026-03-03.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# TA-P16-001 Web App 路由化壳层与统一 API Client 落地（2026-03-03）
2+
3+
- Task ID：TA-P16-001
4+
- 阶段：Phase 16
5+
- 状态：DONE
6+
- 负责人角色：Frontend + QA
7+
8+
## 1. 目标
9+
10+
在 `packages/web` 启动第一批真实实现，替换原占位式页面与测试，形成可演进的 Web App 运行时基线：
11+
12+
1. 路由化界面壳层（sessions/groups/identity/settings）；
13+
2. 统一 API 客户端，强制 `/api/v1/*` 前缀；
14+
3. DID 输入仅接受 `did:claw:*`；
15+
4. RFC7807（`application/problem+json`）错误映射为统一异常对象；
16+
5. Web 包拥有可执行单测（非占位测试脚本）。
17+
18+
## 2. 实现摘要
19+
20+
1. 新增 `TelagentApiClient`：
21+
- 内置 `/api/v1/*` 路径前缀断言；
22+
- 内置 DID 格式校验（`did:claw:*`）；
23+
- 内置 RFC7807 错误解析（`ApiProblemError`）；
24+
- 提供 `getSelfIdentity/pullMessages/sendMessage/createGroup/inviteMember/acceptInvite/resolveIdentity/getNodeInfo` 等方法。
25+
2. 重构 Web 主入口：
26+
- 统一由 `#app` 挂载；
27+
- 会话、群组、身份、设置四个路由视图；
28+
- API 调用结果与错误统一进入 Inspector/Activity 日志。
29+
3. 重构样式：
30+
- 引入三栏壳层布局与移动端断点；
31+
- 提供会话列表、消息时间线、响应面板等基础视觉结构。
32+
4. 替换 Web 测试基线：
33+
- `@telagent/web` 从占位 `echo` 测试切到 `node --test`；
34+
- 新增 API 客户端专项单测，覆盖前缀约束、DID 校验、RFC7807 解析、数据提取等行为。
35+
36+
## 3. 变更文件
37+
38+
- `packages/web/src/core/api-client.js`
39+
- `packages/web/src/main.js`
40+
- `packages/web/src/index.html`
41+
- `packages/web/src/styles.css`
42+
- `packages/web/test/api-client.test.js`
43+
- `packages/web/package.json`
44+
- `packages/web/scripts/run-phase16-web-runtime-shell-check.mjs`
45+
46+
## 4. 验证
47+
48+
1. 构建：
49+
- `corepack pnpm --filter @telagent/web build`
50+
2. 测试：
51+
- `corepack pnpm --filter @telagent/web test`
52+
3. 专项脚本：
53+
- `node packages/web/scripts/run-phase16-web-runtime-shell-check.mjs`
54+
55+
## 5. 证据
56+
57+
- 构建日志：`docs/implementation/phase-16/logs/2026-03-03-p16-web-build.txt`
58+
- 测试日志：`docs/implementation/phase-16/logs/2026-03-03-p16-web-test.txt`
59+
- 专项检查日志：`docs/implementation/phase-16/logs/2026-03-03-p16-web-runtime-shell-check-run.txt`
60+
- 机读清单：`docs/implementation/phase-16/manifests/2026-03-03-p16-web-runtime-shell-check.json`

‎docs/implementation/telagent-v1-implementation-plan.md‎

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# TelAgent v1 实施计划
22

3-
- 文档版本：v1.1
3+
- 文档版本：v1.2
44
- 适用范围：TelAgent MVP（协议后端 + Web 管理台）
55
- 计划周期：11 周（Phase 0-5）+ 滚动迭代（Phase 6+）
66
- 最后更新：2026-03-03
@@ -40,6 +40,7 @@
4040
| Phase 13 | 滚动 | v0.2.0 稳定化与可运营增强 | 压测、灾备、审计归档、联邦重放保护、SDK 一致性全部通过 Gate |
4141
| Phase 14 | 滚动 | 产品聚焦与缺陷收敛 | 默认 Web 界面回归核心聊天流程，关键一致性缺陷进入收敛闭环 |
4242
| Phase 15 | 滚动 | Web App 工业级设计与多平台建设 | 功能域、架构、设计系统、多平台、质量门禁形成完整执行框架 |
43+
| Phase 16 | 滚动 | Web App 实装冲刺（核心交互与质量基线） | 路由化壳层、统一 API 客户端、RFC7807 错误链路、Web 自动化测试基线落地 |
4344

4445
## 5. 分阶段执行细节
4546

@@ -276,6 +277,32 @@
276277
- 风险项与依赖项完成归档并可追踪；
277278
- Phase 15 启动评审通过。
278279

280+
## 5.11 Phase 16（Web App 实装冲刺）
281+
282+
### 关键工作
283+
284+
1. 落地路由化 Web 壳层（会话/群组/身份/设置）与运行态面板（`TA-P16-001`）；
285+
2. 落地统一 API Client，强制 `/api/v1/*` 前缀并内建 RFC7807 解析；
286+
3. 在前端输入与 API 层统一 DID 约束（仅 `did:claw:*`）；
287+
4. 建立 Web 包可执行单测与专项检查脚本；
288+
5. 分批补齐会话、群组、身份、设置等功能域交互细节与质量门禁；
289+
6. 完成 Phase 16 Gate 收口（`TA-P16-007`）。
290+
291+
### 交付物
292+
293+
- Phase 16 任务与证据文档（`docs/implementation/phase-16/`）；
294+
- Web 端代码基线（`packages/web/src/*` + `packages/web/test/*`）；
295+
- Web 构建/测试日志与专项检查 manifest；
296+
- Phase 16 WBS 与迭代看板同步条目。
297+
298+
### Exit Criteria
299+
300+
- `TA-P16-001` ~ `TA-P16-007` 全部完成并具备可验证证据；
301+
- Web API 调用路径仅使用 `/api/v1/*`；
302+
- DID 输入校验仅接受 `did:claw:*`；
303+
- RFC7807 错误链路可在 Web 侧稳定识别并展示；
304+
- Phase 16 Gate 结论为 `PASS`。
305+
279306
## 6. 质量保障策略
280307

281308
### 6.1 测试金字塔

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

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
- 文档版本：v1.0
44
- 基线计划起始日：2026-03-02（周一）
55
- 基线计划结束日：2026-05-17（周日）
6-
- 适用范围：Phase 0 -> Phase 15（发布后改进 + 联邦灰度兼容 + 自动化回滚 + v1.1/v1.2/v0.2.0 + WebApp 工业化增强）
6+
- 适用范围：Phase 0 -> Phase 16（发布后改进 + 联邦灰度兼容 + 自动化回滚 + v1.1/v1.2/v0.2.0 + WebApp 工业化增强 + WebApp 实装冲刺）
77

88
## 1. 看板目的
99

@@ -227,8 +227,15 @@
227227
- 已完成：`TA-P14-004`（direct 会话参与方访问控制，非参与方写入返回 RFC7807）
228228
- 已完成：`TA-P14-005`（TS/Python SDK 行为与错误语义收敛，覆盖 FORBIDDEN direct ACL 场景）
229229
- 已完成：`TA-P14-006`（Phase 14 Gate 收口，阶段关闭）
230-
- 已规划：`TA-P15-001`（WebApp 工业级规划总纲冻结）
231-
- 下一批 Ready：等待下一阶段立项（建议先冻结 Phase 16 目标与验收口径）。
230+
- 已完成：`TA-P15-001`（WebApp 工业级规划总纲冻结）
231+
- 已完成：`TA-P15-002`（WebApp 功能域与 IA 冻结）
232+
- 已完成：`TA-P15-003`（WebApp 设计系统与组件规范冻结）
233+
- 已完成：`TA-P15-004`（WebApp 多平台架构冻结）
234+
- 已完成：`TA-P15-005`（WebApp 离线同步与冲突策略冻结）
235+
- 已完成：`TA-P15-006`（WebApp 客户端质量体系与发布门禁冻结）
236+
- 已完成：`TA-P15-007`（Phase 15 Gate 收口，阶段关闭）
237+
- 已完成：`TA-P16-001`（Web App 路由化壳层 + 统一 API Client + RFC7807 + Web 单测基线）
238+
- 下一批 Ready：`TA-P16-002`（会话域增强：稳定刷新、游标体验、失败重试状态）。
232239

233240
## 4.2 Blockers（2026-03-03 更新）
234241

@@ -433,6 +440,16 @@
433440
- `TA-P15-007`：DONE（Phase 15 Gate 收口，见 `docs/implementation/phase-15/ta-p15-007-phase15-gate-review-2026-03-03.md` 与 `docs/implementation/gates/phase-15-gate.md`）。
434441
- 阶段状态：Phase 15 已关闭（PASS）。
435442

443+
## 4.21 Phase 16 Web App 实装冲刺快照（2026-03-03）
444+
445+
- `TA-P16-001`：DONE（Web App 路由化壳层、统一 API 客户端、RFC7807 错误链路与 Web 单测基线已落地，见 `docs/implementation/phase-16/ta-p16-001-web-app-runtime-shell-and-api-client-2026-03-03.md`）。
446+
- `TA-P16-001` 机读清单：`docs/implementation/phase-16/manifests/2026-03-03-p16-web-runtime-shell-check.json`。
447+
- `TA-P16-001` 验证日志：
448+
- `docs/implementation/phase-16/logs/2026-03-03-p16-web-build.txt`
449+
- `docs/implementation/phase-16/logs/2026-03-03-p16-web-test.txt`
450+
- `docs/implementation/phase-16/logs/2026-03-03-p16-web-runtime-shell-check-run.txt`
451+
- 阶段状态：Phase 16 执行中，下一步进入 `TA-P16-002`。
452+
436453
## 5. 周会与 Gate 节奏建议
437454

438455
- 每周一：Iteration Planning（30 分钟）

0 commit comments

Comments
 (0)