灵隙(synapse) v1.0.0 版本

This commit is contained in:
lychang
2026-06-29 02:12:44 +08:00
parent 2c59efe0ca
commit 65710a4536
27 changed files with 1819 additions and 760 deletions

View File

@@ -0,0 +1,452 @@
# 灵隙协议协作工作流程
> 版本:1.0.0
> 状态:生效
> 适用范围:docs/ 下所有协议文档的评审与修订
---
## 1. 文档角色体系
docs/ 下的文档按 **内容成熟度** 分为以下目录,每个目录有明确的角色边界:
```
docs/
├── v{数字}/ 协议规范 — 已定稿的协议定义,只增不改
├── 00-record/ 会议记录 — 协作过程中的决策记录
├── 01-draft/ 草案 — 待评审的技术方案提议
├── 02-guide/ 实现指南 — 已确认的实现参考和示例
└── 03-asset/ 资源附件 — 海报、图表等非文本资产
```
| 角色 | 目录 | 内容定位 | 可修改性 |
|------|------|---------|:--------:|
| **协议规范** | `v{数字}/` | 已确认的协议定义 | ❌ 锁定(仅通过新版本覆盖) |
| **会议记录** | `00-record/` | 协作中的决策记录 | ✅ 补充(不可推翻已确认条目) |
| **草案** | `01-draft/` | 待评审的技术提案 | ✅ 自由编辑 |
| **实现指南** | `02-guide/` | 参考实现的技术指南 | ✅ 更新 |
| **资源附件** | `03-asset/` | 海报、图表、图片等 | ✅ 更新 |
| **索引** | 各目录的 `00_index.md` | 目录清单和版本说明 | ✅ 同步更新 |
---
## 2. 文档版本独立规则
每一份文档独立维护版本号,不依赖目录版本:
### 2.1 版本号格式
```
{v1}.{v2}.{v3}
示例:
0.1 = 初始草案
0.2 = 草案修订
1.0.0 = 首次定稿
1.1.0 = 兼容性修订
2.0.0 = 不兼容修订
```
### 2.2 版本段含义
| 段位 | 含义 | 变更条件 |
|:---:|------|---------|
| **v1** | 主版本 | 不兼容的协议变更(如签名算法替换) |
| **v2** | 次版本 | 兼容的功能增补(如新增消息类型) |
| **v3** | 补丁 | 勘误、措辞澄清、格式调整 |
### 2.3 状态标签
每个文档元信息头必须有版本和状态:
```markdown
> 版本:0.3
> 状态:草案
```
```markdown
> 版本:1.0.0
> 状态:生效
```
```markdown
> 版本:1.0.0
> 状态:作废
> 作废原因:被 v2.0.0 替代
```
| 状态 | 说明 | 出现位置 |
|------|------|---------|
| `草案` | 待评审的内容 | `01-draft/` |
| `生效` | 已确认的规范 | `v{数字}/` |
| `作废` | 已被替代的旧版本 | `v{数字}/`(保留历史) |
### 2.4 版本与目录的对应关系
| 目录 | 文档版本范围 | 说明 |
|:----:|------------|------|
| `01-draft/` | `0.x` | 草案阶段,版本号从 0.1 起跳 |
| `v{数字}/` | `>= 1.0.0` | 定稿后从 1.0.0 开始,移入 v{数字} 目录 |
| `00-record/` | `1.0.0`(固定) | 会议记录不增量版本,日期区分 |
| `02-guide/` | `>= 1.0.0` | 实现指南跟随对应的协议版本 |
---
## 3. 协作场景
定义三种协作场景,覆盖不同粒度的决策:
### 3.1 方案讨论
| 项目 | 内容 |
|------|------|
| **触发条件** | 你对某个技术方向有想法,想讨论可行性 |
| **你的输入** | 一句话想法、一个疑问、一个未解决的问题 |
| **AI 产出** | 结构化分析(影响范围、可行方案、利弊对比) |
| **你的输出** | 决定方向:继续、换方案、搁置 |
### 3.2 草案评审
| 项目 | 内容 |
|------|------|
| **触发条件** | `01-draft/` 下有草案需要评审 |
| **AI 准备** | 提取草案的变更摘要、与现有规范的冲突点、待决议问题列表 |
| **你的输入** | 逐条拍板:通过 / 驳回(说明方向)/ 搁置 |
| **AI 产出** | 按决议更新草案、生成会议记录、更新索引 |
### 3.3 快速裁定
| 项目 | 内容 |
|------|------|
| **触发条件** | 发现现有规范中的歧义、矛盾或遗漏 |
| **AI 分析** | 指出问题所在、给出修正提案、标注影响范围 |
| **你的输入** | 一分钟内拍板 |
| **AI 产出** | 记录裁定到 `00-record/`,更新关联文档 |
---
## 4. 协作前准备
### 4.1 你需要准备的
| 场景 | 你需要提供 |
|------|-----------|
| **方案讨论** | 一句话描述你想讨论的方向或问题 |
| **草案评审** | 指定要评审的草案文件路径(`01-draft/` 下) |
| **快速裁定** | 指出有疑问的协议条款(文件+行号/章节) |
你不需要准备格式化的文档——AI 会将你的口语化表达转化为结构化内容。
### 4.2 AI 会准备的
根据你的输入,AI 自动准备以下内容:
| 场景 | AI 准备的内容 |
|------|-------------|
| **方案讨论** | 关联文档引用、影响范围分析、多个可选方案对比 |
| **草案评审** | 变更摘要(如是修订版)、与现有规范的冲突矩阵、待决议问题列表 |
| **快速裁定** | 问题定位、修正提案、受影响的文档列表 |
---
## 5. 协作流程
### 5.1 角色定义
整个协作中只有两个角色:
| 角色 | 你是谁 | 你的职责 |
|------|--------|---------|
| **你** | 决策者 | 提出方向、拍板决议、确认产出 |
| **AI 助理** | 执行者 | 分析方案、生成文档、记录决策、管理文件 |
AI 不做决策,只做**分析、建议和执行**。所有决议由你最终拍板。
### 5.2 标准交互流程
一次协作的通用交互步骤:
```
步骤 1 — 你提出问题
你说出想法、疑问或需求(可以是口语化的)
步骤 2 — AI 结构化回应
AI 提取关键信息,形成结构化内容供你评判:
├── □ 问题重述(确认理解正确)
├── □ 关联文档引用
├── □ 可选方案(如有)
├── □ 影响范围评估
└── □ 待确认事项(你需要拍板的问题)
步骤 3 — 你给出决议
你对 AI 提出的选项拍板,或提出修改方向
步骤 4 — AI 执行
AI 根据决议:
├── □ 更新或创建文档
├── □ 生成会议记录
└── □ 更新索引文件
步骤 5 — 你确认(可选)
你可以要求 AI 展示变更摘要,确认无误后结束
```
### 5.3 决议输入方式
你通过以下方式给出决议,AI 根据不同的输入方式执行相应操作:
| 你的输入 | AI 理解方式 | AI 执行 |
|---------|-----------|---------|
| 直接说结论(如"用方案一") | 明确选择 | 按选定方案执行 |
| 给出修改方向(如"把 X 改为 Y") | 指令式修改 | 执行具体修改 |
| 提供替代方案(如"试试这样...") | 新提议 | 分析后返回步骤 2 |
| 保留意见(如"先放一放") | 搁置 | 记录到待决议问题列表,不生成文件 |
| 要求更多信息(如"展开说说 DHT 的缺点") | 追问 | 深入分析后返回步骤 2 |
### 5.4 记录方式
每一轮交互结束后,AI 自动将决议记录到会议文件 `00-record/`,你不需要手动记录。
| AI 自动记录的内容 | 存放位置 |
|-------------------|---------|
| 决议结论 | `00-record/{日期}-{主题}.md` 的"决议事项"章节 |
| 决议理由 | 同上 |
| 影响范围 | 同上 |
| 后续行动项 | 同上 |
| 新生成/更新的草案 | `01-draft/{日期}-{草案名}-v{次}.md` |
### 5.5 一次协作中允许的操作
| 操作 | 规则 | 示例 |
|------|------|------|
| 切换话题 | 随时可以 | "不说签名了,聊聊 DHT" |
| 推翻之前的决议 | 可以,但需说明理由 | "刚才说的方案一我想了想还是不行,因为..." |
| 要求回滚 | 可以,AI 会从 git 历史恢复 | "把刚才生成的 draft 删掉" |
| 问多个问题 | 一个一个来,AI 会逐个回应 | 建议一个问题讨论完再提下一个 |
| 中途中断 | 随时可以,AI 会保存当前进度 | 下次继续时会提供断点摘要 |
---
## 6. 协作产出
### 6.1 AI 实时产出的文件
协作过程中,AI 实时生成以下文件,你无需等待:
```
产出文件清单:
├── □ 会议记录 → 00-record/{日期}-{主题}.md
├── □ 更新后的草案 → 01-draft/{日期}-{草案名}-v{次}.md
└── □ 索引更新 → 各目录的 00_index.md(如有变动)
```
### 6.2 会议记录模板
```markdown
# 会议记录:{主题}
> 日期:{YYYY-MM-DD}
> 类型:方案讨论 / 草案评审 / 快速裁定
---
## 议题
{一句话描述本次讨论的内容}
---
## 决议事项
### 决议一:{决议标题}
| 项目 | 内容 |
|------|------|
| **结论** | {结论简述} |
| **理由** | {决策理由} |
| **影响范围** | {影响的文档/模块列表} |
### 决议二:{决议标题}
...
---
## 补充讨论要点
{讨论中出现的值得记录的信息}
---
## 附录:关联文档
| 文档 | 说明 | 关系 |
|------|------|------|
| [{文档路径}](../path/to/doc.md) | {文档简述} | 本次讨论的基础/产出 |
---
## 后续行动
| 事项 | 目标版本 | 状态 |
|------|---------|:----:|
| {事项} | v{数字} | 待办 / 进行中 / 完成 |
```
### 6.3 文件命名规范
```
会议记录: {YYYY-MM-DD}-{英文短名}.md → 00-record/
草案: {YYYY-MM-DD}-{草案名}-v{次}.md → 01-draft/
协议规范文档: {编号}_{英文短名}.md → v{数字}/
实现指南文档: {英文短名}.md → 02-guide/
索引文件: 00_index.md → 各目录根目录
资源文件: {英文短名}.{后缀} → 03-asset/
```
---
## 7. 决议覆盖范围
在一次协作中,决议的影响范围按以下层次递进:
```
┌─────────────────────────────────────────┐
│ 单文件内的问题 │
│ 范围:措辞澄清 / 勘误 / 歧义裁定 │
│ 你的输入:一句拍板 │
│ AI 产出:修改文件 + 记录到 00-record │
└────────────────┬────────────────────────┘
│ 涉及跨文件/跨协议
▼
┌─────────────────────────────────────────┐
│ 跨文件的方案变更 │
│ 范围:涉及多个协议文档的技术决策 │
│ 你的输入:选择方案 + 确认影响范围 │
│ AI 产出:更新多份文档 + 更新/生成草案 │
└────────────────┬────────────────────────┘
│ 涉及版本范围/兼容性
▼
┌─────────────────────────────────────────┐
│ 版本级规划变更 │
│ 范围:决定 v1.0 / v1.1 / v2.0 的内容 │
│ 你的输入:指定版本范围和分工 │
│ AI 产出:更新 00_index.md + 记录到 00-record │
└─────────────────────────────────────────┘
```
你可以在任何层次上拍板,AI 会自动跟进所有下游影响。
---
## 8. 草案晋升路径
一份草案从创建到定稿的标准路径:
```
┌──────────┐
│ 想法 │
└────┬─────┘
│ 你说出想法,AI 写出草案
▼
┌───────────┐
│ 01-draft/ │ ←── 可任意修改
│ v0.1 │
└─────┬─────┘
│ 你评审 + 拍板修改方向
▼
┌───────────┐
│ 01-draft/ │ ←── 可修改
│ v0.2 │
└─────┬─────┘
│ 你确认定稿
▼
┌───────────┐
│ v{数字}/ │ ←── 锁定,只增不改
│ v1.0.0 │
└───────────┘
│ 后续修订
▼
┌───────────┐
│ v{数字}/ │
│ v2.0.0 │ ←── 不兼容修订另开新版本
└───────────┘
```
| 阶段 | 版本号范围 | 目录 | 修改权限 |
|:----:|:----------:|:----:|:--------:|
| 初始创建 | 0.1 | `01-draft/` | 自由编辑 |
| 修订中 | 0.2, 0.3... | `01-draft/` | 自由编辑 |
| 评审通过 | 1.0.0 | 移入 `v{数字}/` | 锁定 |
| 兼容修订 | 1.1.0, 1.2.0... | `v{数字}/` | 仅追加,不修改已有内容 |
| 不兼容修订 | 2.0.0 | 新建 `v{数字+1}/` | 旧版本作废,新版本重新锁定 |
---
## 9. 目录与文件命名规范
### 9.1 目录命名规则
| 规则 | 说明 |
|------|------|
| 协议规范目录 | 固定格式 `v{数字}`,数字表示协议主版本 |
| 其他内容目录 | 格式 `{两位数字}-{英文短名}`,数字按内容成熟度/使用频率排序 |
**已定义目录**:
```
docs/
├── v0/ v0 协议规范
├── v1/ v1 协议规范
├── 00-record/ 会议与决策记录
├── 01-draft/ 草案与方案提议
├── 02-guide/ 实现指南参考
└── 03-asset/ 资源附件(海报、图表等)
```
如需新增目录,新目录的编号插在末尾(当前为 03),待下次整理时统一重排。
### 9.2 文件命名规则
```
协议规范层(v{数字}/):
{两位数字}_{英文短名}.md
示例:01_raw-protocol.md
会议记录层(00-record/):
{YYYY-MM-DD}-{英文短名}.md
示例:2026-06-29-v1-draft-discussion.md
草案层(01-draft/):
{YYYY-MM-DD}-{草案名}-v{次}.md
示例:2026-06-29-identity-protocol-v2.md
实现指南层(02-guide/):
{英文短名}.md
示例:components.md
资源附件层(03-asset/):
{英文短名}.{后缀}
示例:poster.svg
索引文件:
00_index.md(各目录的根目录)
```
---
## 10. 免交互操作
以下情况不需要你开口,AI 直接执行:
| 场景 | AI 自行操作 | 例外 |
|------|-----------|------|
| 草案内的措辞修正 | 直接修改 `01-draft/` 文件 | 涉及技术含义的措辞变化需先问你 |
| 漏洞/矛盾自查 | 发现后指出并给出修复提案,等你确认后执行 | - |
| 会议记录遗漏补充 | 直接追加,标注 `[后补]` | 不能推翻已记录的决议 |
| 实现指南更新 | 直接修改 `02-guide/` 文件 | 引用到协议层规范时需通知你 |
| 索引文件同步 | 直接修改 `00_index.md` | 版本号变更必须与你确认一致 |
---
> *本文件本身遵循上述规范,如内容与实际操作不一致,以实际操作为准并及时修正本文件。*

View File

@@ -0,0 +1,111 @@
# 会议记录:v1 草案讨论会
> 日期:2026-06-29
> 时长:1 session
> 主题:灵隙 v1 版本身份协议草案讨论 & 版本规划
---
## 会议议题
围绕 [v1 身份协议草案](../v1/05_identity-protocol-draft.md) 的技术方案与版本规划进行讨论。
---
## 决议事项
### 决议一:签名机制统一为非对称签名
| 项目 | 内容 |
|------|------|
| **结论** | 直接统一到非对称签名体系 |
| **默认算法** | Ed25519(高效、安全) |
| **兼容算法** | ECDSA-P256(跨链互操作)、ECDSA-secp256k1(兼容以太坊系) |
| **HMAC 定位** | 降级为可信内网链路的可选优化,不作为协议层的签名方案 |
| **影响范围** | [Raw协议](../v1/01_raw-protocol.md) 第4章签名机制需重写,统一为公钥签名;`signature` 字段含义从 HMAC 变更为 Ed25519/ECDSA 签名值;`signature_algorithm` 字段保留,默认值改为 `Ed25519` |
### 决议二:区块链作为身份协议的核心组成部分
| 项目 | 内容 |
|------|------|
| **结论** | 区块链不是可选插件,而是身份协议的核心层 |
| **定位** | 三层发现架构中,区块链作为"最终一致性源"(Source of Truth) |
| **默认基础设施** | 每个 Synapse 网络应至少有一个链上注册表,作为 Agent 身份的最终存证 |
| **兼容性** | 支持多链:Ethereum(高价值)、Polygon(高频)、联盟链(企业) |
| **混合模式** | 本地缓存 + DHT 做快速查找,区块链做最终验证和仲裁 |
### 决议三:DHT 分阶段实现
| 阶段 | 范围 | 说明 |
|------|------|------|
| **Phase 1(v1.0)** | 广播查询 + 中心目录 | 小型网络(<100 Agent),用灵脉 Meridian 作为可选目录,无 DHT |
| **Phase 2(v1.1)** | 分层 DHT | 中等规模(100-10000 Agent),引入分层路由 |
| **Phase 3(v1.2)** | 完整 Kademlia + 隐私保护 + 密钥轮换 | 大规模网络(>10000 Agent),支持密钥轮换和隐私保护 |
### 决议四:七大组件实现推迟到 v1.1
| 项目 | 内容 |
|------|------|
| **结论** | v1 版本聚焦协议层定义(数据格式、消息类型、行为约束),不做具体落地实现 |
| **v1 范围** | Raw / A2A / A2N / P2A 四个协议规范 + 去中心化身份草案 |
| **v1.1 范围** | 七大组件(灵脉/灵玺/灵鉴/灵泊/灵瞰/灵衡/灵枢)的具体落地实现 |
| **v1.2 范围** | 完整 Kademlia DHT、隐私保护机制、密钥轮换、跨链互操作 |
---
## 补充讨论要点
### 1. 协议层与实现层的明确边界
v1 的身份草案目前包含部分实现细节(如 Solidity 合约代码),需要在 v2 版本中剥离:
- **协议层(v1)**:只定义 AgentID 格式、签名算法、消息类型、生命周期状态机
- **实现层(v1.1+)**:具体的区块链合约实现、DHT 协议栈、缓存策略
### 2. AgentID 命名空间治理
| 问题 | 方案 |
|------|------|
| namespace 的分配 | 官方保留 `synapse:` 前缀;企业自定义采用反向域名(如 `com.mycompany.agent:`) |
| alias 全局唯一性 | 不要求全局唯一,仅在本地或联盟内有效 |
| DID 兼容 | `did:synapse:` 独立成体系,与 `namespace:key_hash:alias` 格式并存 |
### 3. 签名算法选择理由
选择 Ed25519 作为默认算法的原因:
- 比 ECDSA-P256 快 2-3 倍
- 固定长度签名(64 字节),便于编码和存储
- 抗侧信道攻击,实现简单
- 所有主流语言均有成熟实现
### 4. 区块链选择建议
| 场景 | 推荐 | 理由 |
|------|------|------|
| 开发/测试 | 本地 Hardhat 私链 | 零成本、完全可控 |
| 企业联盟 | Hyperledger Fabric / 联盟链 | 隐私、可审计 |
| 公网生产 | Ethereum L2(Arbitrum/Optimism) | 低 Gas 成本、继承 L1 安全 |
| 高频场景 | Polygon / Solana | 确认快、成本低 |
---
## 附录:关联文档
| 文档 | 说明 | 关系 |
|------|------|------|
| [v1 身份草案](../v1/05_identity-protocol-draft.md) | 现有 v1 身份协议草案 | 本次讨论的基础文档 |
| [身份草案 v2](../01-draft/2026-06-29-identity-protocol-v2.md) | 根据本次决议更新的草案 | 基于本次决议生成 |
| [Raw协议](../v1/01_raw-protocol.md) | 原始协议定义 | 签名方案受影响需更新 |
| [v1 索引](../v1/00_index.md) | v1 版本索引 | 版本范围需更新 |
---
## 后续行动
| 事项 | 负责人 | 目标版本 | 状态 |
|------|--------|---------|------|
| 更新 Raw 协议签名方案 | - | v1.0 | 待办 |
| 更新身份草案为 v2 版本 | ✅ 已完成 | v1.0 | 完成 |
| 更新 v1 索引文件版本范围 | - | v1.0 | 待办 |
| 起草七大组件规范 | - | v1.1 | 待启动 |
| 起草 DHT 实现规范 | - | v1.1 | 待启动 |
| 链上合约实现 | - | v1.1 | 待启动 |