intent-plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Intent Plan

Intent 计划

Transform an approved Intent into a structured, executable development plan with strict TDD discipline.

Output is TaskSwarm-compatible: The generated plan.md can be directly executed by

/swarm run

将已获批的Intent转换为遵循严格TDD规范的结构化、可执行开发计划。

输出与TaskSwarm兼容：生成的plan.md可直接通过

/swarm run

执行。

Core Principles

核心原则

Test First, Always: Every implementation step starts with writing tests
Phased Execution: Break work into phases with clear deliverables (0-indexed)
Verification Gates: Each phase ends with e2e validation
Automation Priority: Prefer CLI/script testing over manual/browser testing
Checkbox Tracking: All tests use
```
- [ ]
```
format for progress tracking

始终测试先行：每个实现步骤都从编写测试开始
分阶段执行：将工作拆分为具有明确交付物的阶段（从0开始编号）
验证关卡：每个阶段结束时进行端到端（e2e）验证
优先自动化：优先使用CLI/脚本测试，而非手动/浏览器测试
复选框跟踪：所有测试均使用
```
- [ ]
```
格式跟踪进度

Plan Structure

计划结构

undefined

undefined

Phase 0: [Phase Name]

Phase 0: [阶段名称]

├── ### Description ├── ### Tests │ ├── #### Happy Path │ │ └── - [ ] test case 1 │ ├── #### Bad Path (详尽列举) │ │ └── - [ ] error case 1 │ ├── #### Edge Cases │ │ └── - [ ] boundary case 1 │ ├── #### Security │ │ └── - [ ] vulnerability test 1 │ ├── #### Data Leak │ │ └── - [ ] leak prevention test 1 │ └── #### Data Damage │ └── - [ ] integrity test 1 ├── ### E2E Gate │ └── CLI/Script 验证命令 └── ### Acceptance Criteria └── - [ ] criterion 1

├── ### 描述 ├── ### 测试 │ ├── #### 正常路径 │ │ └── - [ ] 测试用例1 │ ├── #### 异常路径（详尽列举） │ │ └── - [ ] 错误场景1 │ ├── #### 边界场景 │ │ └── - [ ] 边界用例1 │ ├── #### 安全 │ │ └── - [ ] 漏洞测试1 │ ├── #### 数据泄露 │ │ └── - [ ] 防泄露测试1 │ └── #### 数据损坏 │ └── - [ ] 完整性测试1 ├── ### E2E 验证关卡 │ └── CLI/脚本验证命令 └── ### 验收标准 └── - [ ] 验收条件1

Phase 1: [Phase Name]

Phase 1: [阶段名称]

└── ...

undefined

└── ...

undefined

Test Categories (6 Required)

测试类别（6类必填）

Every phase MUST include tests from ALL 6 categories:

Category	Description	Examples
Happy Path	Normal expected usage	Valid inputs, correct sequences
Bad Path	Invalid inputs, error conditions	Wrong types, missing required fields, invalid states
Edge Cases	Boundary conditions	Empty inputs, max values, concurrent access
Security	Vulnerability prevention	Injection attacks, auth bypass, privilege escalation
Data Leak	Information exposure	Sensitive data in logs, error messages, API responses
Data Damage	Data integrity protection	Partial writes, corruption, race conditions

Bad cases must be detailed and comprehensive. A good test suite has more failure tests than success tests.

每个阶段必须包含所有6类测试：

类别	描述	示例
正常路径（Happy Path）	预期的正常使用场景	有效输入、正确流程
异常路径（Bad Path）	无效输入、错误条件	错误类型、缺失必填字段、无效状态
边界场景（Edge Cases）	边界条件	空输入、最大值、并发访问
安全（Security）	漏洞防护	注入攻击、权限绕过、权限提升
数据泄露（Data Leak）	信息暴露	日志中的敏感数据、错误信息、API响应
数据损坏（Data Damage）	数据完整性保护	部分写入、数据损坏、竞态条件

异常场景必须详尽全面。优质的测试套件中，失败测试的数量应多于成功测试。

Test Writing Discipline

测试编写规范

Tests First: Write ALL tests before any implementation
Red-Green-Refactor: Run tests expecting failure, implement, verify pass
No Skip: Every category must have at least one test case

测试先行：在任何实现前编写所有测试
红-绿-重构：先运行测试预期失败，再实现功能，最后验证通过
无遗漏：每个类别至少包含一个测试用例

Phase Gates: E2E Verification (Required)

阶段关卡：端到端验证（必填）

Each phase MUST end with E2E verification. This is the gate that proves the phase is truly complete.

每个阶段必须以端到端验证结束。这是证明阶段真正完成的关键关卡。

E2E Gate Requirements

E2E验证关卡要求

Automatable: Must be runnable via CLI/script, no manual steps
Independent: Can run without human intervention
Reproducible: Same inputs produce same outputs
Fast Feedback: Fails quickly when something is wrong

可自动化：必须可通过CLI/脚本运行，无手动步骤
独立执行：无需人工干预即可运行
可复现：相同输入产生相同输出
快速反馈：出现问题时可快速失败

Preferred: CLI/Script Testing

首选：CLI/脚本测试

bash

undefined

bash

undefined

Example: API verification

示例：API验证

curl -X POST http://localhost:3000/api/resource
-H "Content-Type: application/json"
-d '{"field": "value"}' | jq .

Example: Database state check

示例：数据库状态检查

psql -c "SELECT * FROM table WHERE condition"

Example: File system verification

示例：文件系统验证

diff expected_output.json actual_output.json

Example: Unit test suite

示例：单元测试套件

pnpm test -- --coverage

undefined

pnpm test -- --coverage

undefined

For Web Projects: Automation-Friendly Design

Web项目：自动化友好设计

DO:
- Provide health check endpoints
- Return machine-parseable responses (JSON)
- Include test mode / seed data endpoints
- Design idempotent operations

DON'T:
- Require browser interaction for verification
- Depend on visual inspection
- Need manual clicking through UI

推荐做法：
- 提供健康检查端点
- 返回机器可解析的响应（JSON格式）
- 包含测试模式/种子数据端点
- 设计幂等操作

不推荐：
- 验证时需要浏览器交互
- 依赖视觉检查
- 需要手动点击UI

When Browser Testing is Unavoidable

当浏览器测试不可避免时

If browser/headless testing is truly necessary:

Use Playwright/Puppeteer with script automation
Create dedicated test endpoints
Prefer API calls over UI interaction

如果确实需要浏览器/无头测试：

使用Playwright/Puppeteer实现脚本自动化
创建专用测试端点
优先使用API调用而非UI交互

Pre-Plan Gates (Mandatory)

计划前置关卡（强制）

Before generating any plan, ALL gates must pass. No exceptions.

/intent-plan
    ↓
┌─────────────────────────────────────┐
│ Gate 1: Interview Check             │
│   ✗ → "先跑 /intent-interview"       │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ Gate 2: Critique Check              │
│   ✗ → "先跑 /intent-critique"        │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ Gate 3: Dependency Check            │
│   ✗ → "前置任务未完成，无法 plan"    │
└─────────────────────────────────────┘
    ↓
✓ All gates passed → Generate plan.md

在生成任何计划前，所有关卡必须通过，无例外。

/intent-plan
    ↓
┌─────────────────────────────────────┐
│ 关卡1：访谈检查                     │
│   ✗ → "先运行 /intent-interview"    │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ 关卡2：评审检查                     │
│   ✗ → "先运行 /intent-critique"     │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ 关卡3：依赖检查                     │
│   ✗ → "前置任务未完成，无法制定计划"│
└─────────────────────────────────────┘
    ↓
✓ 所有关卡通过 → 生成plan.md

Gate 1: Interview Check

关卡1：访谈检查

Verify the Intent has been properly interviewed:

Check	How to Verify	If Failed
INTENT.md exists	File exists in intent directory	Run `/intent-interview`
Structure complete	Has Responsibilities, Structure, API sections	Run `/intent-interview`
Not a stub	Content is substantial, not placeholder text	Run `/intent-interview`

Output if failed:

❌ Gate 1 Failed: Interview Incomplete

INTENT.md is missing or incomplete:
- [ ] Responsibilities section missing
- [ ] Structure diagram missing

Action required: Run /intent-interview first.

验证Intent已完成完整访谈：

检查项	验证方式	失败时操作
INTENT.md存在	检查intent目录下是否有该文件	运行 `/intent-interview`
结构完整	包含职责、架构、API章节	运行 `/intent-interview`
非占位内容	内容充实，非占位文本	运行 `/intent-interview`

失败时输出：

❌ 关卡1失败：访谈不完整

INTENT.md缺失或不完整：
- [ ] 缺少职责章节
- [ ] 缺少架构图

需执行操作：先运行/intent-interview。

Gate 2: Critique Check

关卡2：评审检查

Verify the Intent has been critiqued for over-engineering:

Check	How to Verify	If Failed
Critique done	Look for critique markers or changelog	Run `/intent-critique`
Post-modification	If INTENT.md modified after last critique	Run `/intent-critique` again
AI assessment	Ask AI if another critique round is needed	Run `/intent-critique` if yes

Critique markers to look for:

```

```
comment in INTENT.md
```
critique.md
```
or
```
CRITIQUE.md
```
in same directory
Changelog entry mentioning critique

Post-modification detection:

Compare INTENT.md mtime with critique marker date
If INTENT.md is newer AND has substantial changes → re-critique required

AI Assessment prompt:

"Based on this Intent, is there any sign of over-engineering, premature abstraction, or YAGNI violation that warrants another critique round?"

Output if failed:

❌ Gate 2 Failed: Critique Required

Intent has not been critiqued, or was modified after critique:
- Last critique: 2026-01-15
- INTENT.md modified: 2026-01-20 (substantial changes detected)

Action required: Run /intent-critique to review for over-engineering.

验证Intent已完成过度设计评审：

检查项	验证方式	失败时操作
已完成评审	查找评审标记或变更日志	运行 `/intent-critique`
评审后未修改	若INTENT.md在最后一次评审后被修改	重新运行 `/intent-critique`
AI评估	询问AI是否需要再次评审	若需要则运行 `/intent-critique`

需查找的评审标记：

INTENT.md中的
```

```
注释
同目录下的
```
critique.md
```
或
```
CRITIQUE.md
```
变更日志中提及评审的条目

评审后修改检测：

比较INTENT.md的修改时间与评审标记日期
若INTENT.md更新且有实质性变更 → 需要重新评审

AI评估提示词：

"基于此Intent，是否存在过度设计、过早抽象或违反YAGNI原则的迹象，需要再次评审？"

失败时输出：

❌ 关卡2失败：需要评审

Intent尚未评审，或评审后被修改：
- 最后一次评审：2026-01-15
- INTENT.md修改时间：2026-01-20（检测到实质性变更）

需执行操作：运行/intent-critique以评审过度设计问题。

Gate 3: Dependency Check

关卡3：依赖检查

Verify all prerequisites are satisfied:

Check	How to Verify	If Failed
Internal deps	Referenced intents have `status: done` in TASK.yaml	List blocking intents
External deps	Required packages/services exist	List missing dependencies
Environment	Required env vars, credentials, access	List missing setup

How to find dependencies:

Parse
```
## Prerequisites
```
or
```
## Dependencies
```
in INTENT.md
Look for
```
depends_on:
```
in TASK.yaml (if exists)
Scan for references like
```
intent/other-feature/
```
or
```
@package/name
```

Dependency states:

intent/auth/         → TASK.yaml status: done     ✓ OK
intent/database/     → TASK.yaml status: review   ✗ Blocked (not done)
intent/api/          → No TASK.yaml               ? Assume not started
@aigne/afs           → Check packages/ or deps    ✓/✗

Output if failed:

❌ Gate 3 Failed: Dependencies Not Ready

This Intent cannot be planned because prerequisites are incomplete:

Blocking Intents:
- intent/auth-module/ → status: in_progress (need: done)
- intent/database-setup/ → status: ready (need: done)

Missing External Dependencies:
- @aigne/session-protocol → not found in packages/

Action required: Complete blocking tasks first, or remove dependencies from INTENT.md if not actually needed.

验证所有前置条件已满足：

检查项	验证方式	失败时操作
内部依赖	引用的intent在TASK.yaml中 `status: done`	列出阻塞的intent
外部依赖	所需的包/服务已存在	列出缺失的依赖
环境配置	所需的环境变量、凭证、访问权限已就绪	列出缺失的配置

如何查找依赖：

解析INTENT.md中的
```
## 前置条件
```
或
```
## 依赖
```
章节
查找TASK.yaml中的
```
depends_on:
```
字段（若存在）
扫描类似
```
intent/other-feature/
```
或
```
@package/name
```
的引用

依赖状态示例：

intent/auth/         → TASK.yaml状态: done     ✓ 已就绪
intent/database/     → TASK.yaml状态: review   ✗ 阻塞（未完成）
intent/api/          → 无TASK.yaml               ? 假设未启动
@aigne/afs           → 检查packages/或依赖项     ✓/✗

失败时输出：

❌ 关卡3失败：依赖未就绪

无法为此Intent制定计划，因为前置条件未完成：

阻塞的Intent：
- intent/auth-module/ → 状态: in_progress（需要: done）
- intent/database-setup/ → 状态: ready（需要: done）

缺失的外部依赖：
- @aigne/session-protocol → 未在packages/中找到

需执行操作：先完成阻塞任务，或若实际不需要则从INTENT.md中移除依赖。

Gate Pass Output

关卡通过时输出

When all gates pass:

✓ Gate 1: Interview complete
✓ Gate 2: Critique done (2026-01-20), no re-critique needed
✓ Gate 3: All 2 dependencies satisfied

Proceeding to generate plan...

当所有关卡通过：

✓ 关卡1：访谈已完成
✓ 关卡2：评审已完成（2026-01-20），无需再次评审
✓ 关卡3：所有2项依赖已满足

开始生成计划...

Workflow

工作流程

/intent-plan
    ↓
Gate 1: Interview Check ──→ ✗ → Stop, require /intent-interview
    ↓ ✓
Gate 2: Critique Check ───→ ✗ → Stop, require /intent-critique
    ↓ ✓
Gate 3: Dependency Check ─→ ✗ → Stop, list blockers
    ↓ ✓
Read Intent file
    ↓
Analyze scope and complexity
    ↓
Identify logical phases (0-indexed)
    ↓
For each phase, define:
    - Description
    - Tests (6 categories)
    - E2E Gate
    - Acceptance Criteria
    ↓
Present plan for approval
    ↓
User confirms or adjusts
    ↓
Save to plan.md (same directory as INTENT.md)
    ↓
Create TASK.yaml (status: ready)

/intent-plan
    ↓
关卡1：访谈检查 ──→ ✗ → 停止，要求运行/intent-interview
    ↓ ✓
关卡2：评审检查 ───→ ✗ → 停止，要求运行/intent-critique
    ↓ ✓
关卡3：依赖检查 ─→ ✗ → 停止，列出阻塞项
    ↓ ✓
读取Intent文件
    ↓
分析范围与复杂度
    ↓
确定逻辑阶段（从0开始编号）
    ↓
为每个阶段定义：
    - 描述
    - 测试（6类）
    - E2E验证关卡
    - 验收标准
    ↓
提交计划待批准
    ↓
用户确认或调整
    ↓
保存至plan.md（与INTENT.md同目录）
    ↓
创建TASK.yaml（状态: ready）

Output Files

输出文件

1. plan.md (Required)

1. plan.md（必填）

markdown

undefined

markdown

undefined

Execution Plan: {task_name}

执行计划: {任务名称}

Overview

概述

简要说明这个任务要做什么。

Prerequisites

前置条件

前置条件
依赖的其他任务
需要的权限或资源

前置条件
依赖的其他任务
需要的权限或资源

Phase 0: {Phase Name}

Phase 0: {阶段名称}

Description

描述

这个阶段要完成什么，交付什么。

Tests

测试

Happy Path

正常路径

测试正常流程 1: {具体描述}
测试正常流程 2: {具体描述}

测试正常流程 1: {具体描述}
测试正常流程 2: {具体描述}

Bad Path

异常路径

无效输入: {具体场景}
缺失必填字段: {具体场景}
错误状态: {具体场景}
类型错误: {具体场景}

无效输入: {具体场景}
缺失必填字段: {具体场景}
错误状态: {具体场景}
类型错误: {具体场景}

Edge Cases

边界场景

Security

安全

注入攻击防护: {具体场景}
权限绕过防护: {具体场景}
输入验证: {具体场景}

注入攻击防护: {具体场景}
权限绕过防护: {具体场景}
输入验证: {具体场景}

Data Leak

数据泄露

错误信息不泄露敏感数据
日志不包含敏感信息
API 响应不过度暴露

错误信息不泄露敏感数据
日志不包含敏感信息
API响应不过度暴露

Data Damage

数据损坏

E2E Gate

E2E验证关卡

bash

undefined

bash

undefined

Phase 完成验证脚本

阶段完成验证脚本

{CLI commands to verify phase completion}

undefined

{验证阶段完成的CLI命令}

undefined

Acceptance Criteria

验收标准

Phase 1: {Phase Name}

Phase 1: {阶段名称}

Description

描述

下一阶段要完成什么。

Tests

测试

Happy Path

正常路径

测试正常流程

测试正常流程

Bad Path

异常路径

测试错误处理 1
测试错误处理 2

测试错误处理1
测试错误处理2

Edge Cases

边界场景

边界条件处理

边界条件处理

Security

安全

安全测试

安全测试

Data Leak

数据泄露

泄露防护测试

泄露防护测试

Data Damage

数据损坏

数据完整性测试

数据完整性测试

E2E Gate

E2E验证关卡

bash

undefined

bash

undefined

Phase 1 验证脚本

Phase 1验证脚本

undefined

undefined

Acceptance Criteria

验收标准

所有测试通过
E2E Gate 验证通过

所有测试通过
E2E验证关卡通过

Final E2E Verification

最终端到端验证

bash

undefined

bash

undefined

全系统端到端验证脚本

验证所有 Phase 的功能协同工作

验证所有阶段的功能协同工作

undefined

undefined

Risk Mitigation

风险缓解

Risk	Mitigation	Contingency
[风险 1]	[预防措施]	[发生时的应对]

风险	缓解措施	应急预案
[风险1]	[预防措施]	[发生时的应对]

References

参考资料

相关 Intent
详细规格 (如果存在)
设计文档 (如果存在)

undefined

相关Intent
详细规格（如果存在）
设计文档（如果存在）

undefined

2. TASK.yaml (Required)

2. TASK.yaml（必填）

yaml

status: ready
owner: null
assignee: null
phase: 0/{total_phases}
updated: {UTC_ISO_TIMESTAMP}
heartbeat: null

Important:

{total_phases}

is the number of phases in plan.md (0-indexed counting).

yaml

status: ready
owner: null
assignee: null
phase: 0/{总阶段数}
updated: {UTC_ISO_TIMESTAMP}
heartbeat: null

注意：

{总阶段数}

是plan.md中的阶段数量（按从0开始的计数方式）。

Integration with IDD & TaskSwarm

与IDD和TaskSwarm的集成

IDD Flow:
/intent-interview     # Create Intent (Gate 1 requirement)
    ↓
/intent-critique      # Review for over-engineering (Gate 2 requirement)
    ↓
/intent-review        # Approve Intent (optional but recommended)
    ↓
/intent-plan          # Gate checks → Generate plan.md + TASK.yaml (THIS SKILL)
    ↓
TaskSwarm Flow:
/swarm run            # Execute plan (TDD cycles)
    ↓
/swarm approve        # Human review
    ↓
/intent-sync          # Write back confirmed details

Gate enforcement ensures quality:

No plan without proper interview → avoids vague/incomplete specs
No plan without critique → avoids over-engineered designs
No plan with missing deps → avoids unexecutable plans

IDD流程：
/intent-interview     # 创建Intent（关卡1要求）
    ↓
/intent-critique      # 评审过度设计问题（关卡2要求）
    ↓
/intent-review        # 批准Intent（可选但推荐）
    ↓
/intent-plan          # 关卡检查 → 生成plan.md + TASK.yaml（本技能）
    ↓
TaskSwarm流程：
/swarm run            # 执行计划（TDD循环）
    ↓
/swarm approve        # 人工评审
    ↓
/intent-sync          # 写入已确认的细节

关卡强制保证质量：

无完整访谈则不生成计划 → 避免模糊/不完整的需求
无评审则不生成计划 → 避免过度设计的方案
依赖未就绪则不生成计划 → 避免无法执行的计划

Tips for Good Plans

优质计划的技巧

Format (TaskSwarm Compatible)

格式（兼容TaskSwarm）

0-indexed phases: Phase 0, Phase 1, Phase 2...
Checkbox format: All tests use
```
- [ ]
```
for progress tracking
E2E Gate per phase: Each phase must have runnable verification

阶段从0开始编号：Phase 0, Phase 1, Phase 2...
复选框格式：所有测试使用
```
- [ ]
```
跟踪进度
每个阶段设E2E验证关卡：每个阶段必须有可运行的验证步骤

Test Quality

测试质量

All 6 categories required: Happy/Bad/Edge/Security/Data Leak/Data Damage
Bad Path > Happy Path: More failure tests than success tests
Specific test cases: "Test error handling" ✗ → "returns 404 when resource not found" ✓
Security by default: Include even if not explicitly requested

必填所有6类测试：正常/异常/边界/安全/数据泄露/数据损坏
异常路径测试多于正常路径：失败测试数量多于成功测试
测试用例具体化："测试错误处理" ✗ → "资源不存在时返回404" ✓
默认包含安全测试：即使未明确要求也需包含

Phase Design

阶段设计

Right-size phases: Each phase completable in 1-3 days
Clear dependencies: Note when phases depend on previous phases
Automatable gates: E2E Gate must be runnable via CLI, no manual steps

阶段大小合适：每个阶段可在1-3天内完成
明确依赖关系：注明阶段是否依赖前序阶段
验证关卡可自动化：E2E验证关卡必须可通过CLI运行，无手动步骤

Example: Complete Output

示例：完整输出

For an Intent at

intent/session-protocol/INTENT.md

Creates:

intent/session-protocol/plan.md

markdown

undefined

对于位于

intent/session-protocol/INTENT.md

的Intent：

生成文件：

intent/session-protocol/plan.md

markdown

undefined

Execution Plan: session-protocol

执行计划: session-protocol

Overview

概述

实现 Session Protocol 的 Frame 编解码功能。

实现Session Protocol的Frame编解码功能。

Prerequisites

前置条件

@aigne/afs 包已存在
TypeScript 环境配置完成

@aigne/afs包已存在
TypeScript环境配置完成

Phase 0: Frame Encoding

Phase 0: Frame编码

Description

描述

实现 Frame 的编码函数，将结构化数据转换为二进制格式。

实现Frame的编码函数，将结构化数据转换为二进制格式。

Tests

测试

Happy Path

正常路径

encodes empty frame correctly
encodes frame with JSON payload
encodes frame with binary payload
preserves ReqId across encode/decode

正确编码空frame
编码带JSON负载的frame
编码带二进制负载的frame
编解码过程中保留ReqId

Bad Path

异常路径

Edge Cases

边界场景

handles empty string payload
handles maximum allowed payload size (64KB)
handles unicode in JSON payload
handles zero-length binary payload

处理空字符串负载
处理最大允许负载尺寸（64KB）
处理JSON负载中的Unicode字符
处理零长度二进制负载

Security

安全

rejects frames with potential injection patterns
validates frame type bounds (0-255)
sanitizes string inputs before encoding

拒绝包含潜在注入模式的frame
验证frame类型范围（0-255）
编码前清理字符串输入

Data Leak

数据泄露

error messages don't expose internal structure
stack traces not included in thrown errors

错误信息不暴露内部结构
抛出的错误不包含堆栈跟踪

Data Damage

数据损坏

atomic write: partial encode doesn't corrupt buffer
buffer overflow protection

原子写入：部分编码不会损坏缓冲区
缓冲区溢出防护

E2E Gate

E2E验证关卡

bash

undefined

bash

undefined

Verify encoding works end-to-end

端到端验证编码功能

pnpm test -- --grep "Frame Encoding" pnpm test:e2e -- --grep "encode"

undefined

pnpm test -- --grep "Frame Encoding" pnpm test:e2e -- --grep "encode"

undefined

Acceptance Criteria

验收标准

Phase 1: Frame Decoding

Phase 1: Frame解码

Description

描述

实现 Frame 的解码函数，将二进制数据解析为结构化对象。

实现Frame的解码函数，将二进制数据解析为结构化对象。

Tests

测试

Happy Path

正常路径

Bad Path

异常路径

throws on truncated frame
throws on corrupted header
throws on invalid magic bytes
throws on unsupported version

frame被截断时抛出错误
头部损坏时抛出错误
魔术字节无效时抛出错误
版本不支持时抛出错误

Edge Cases

边界场景

Security

安全

validates frame length before allocation
rejects oversized frames (DoS protection)

分配内存前验证frame长度
拒绝超大frame（防止DoS攻击）

Data Leak

数据泄露

doesn't expose raw bytes in error messages

错误信息不暴露原始字节

Data Damage

数据损坏

partial decode doesn't advance stream position
corrupted frame doesn't affect subsequent frames

部分解码不推进流位置
损坏的frame不影响后续frame

E2E Gate

E2E验证关卡

bash

undefined

bash

undefined

Verify full roundtrip

验证完整的编解码往返

pnpm test -- --grep "Frame" echo '{"test":1}' | node scripts/encode-decode-test.js

undefined

pnpm test -- --grep "Frame" echo '{"test":1}' | node scripts/encode-decode-test.js

undefined

Acceptance Criteria

验收标准

Final E2E Verification

最终端到端验证

bash

undefined

bash

undefined

Full integration test

全系统集成测试

pnpm test pnpm test:e2e

undefined

pnpm test pnpm test:e2e

undefined

References

参考资料

Intent
Spec


**Creates**: `intent/session-protocol/TASK.yaml`
```yaml
status: ready
owner: null
assignee: null
phase: 0/2
updated: 2026-01-27T10:00:00Z
heartbeat: null

Intent
规格文档


**生成文件**：`intent/session-protocol/TASK.yaml`
```yaml
status: ready
owner: null
assignee: null
phase: 0/2
updated: 2026-01-27T10:00:00Z
heartbeat: null