# BelleCode

**Repository Path**: ai-summers/belle-code

## Basic Information

- **Project Name**: BelleCode
- **Description**: BelleCode是一个专注高效代码实践的开源社区，提供高质量工具与框架，助力开发者提升编程效率与代码质量。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-08
- **Last Updated**: 2026-08-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BelleCode

**Superpowers 流程的图形化审核增强层**

BelleCode 在 Superpowers（AI 开发技能集）的 `writing-plans`（生成任务文档）与 `subagent-driven-development`（子代理实施）之间，插入一层可视化审核——把冗长的 Markdown 任务文档转换为结构化 JSON，通过图形界面让人直观审核、用备注下达修改指令，再同步回任务文档，保证实施结果与人的意图一致。

## 解决的问题

使用 Superpowers 开发时，任务文档又长又专业，人很难逐条确认注意点；任务边界写不清时，AI 子代理会自由发挥，产出与预期不符。BelleCode 让"注意点"结构化、图形化，审核时一眼可见：

- **人**：只审阅图形界面（结构/字段/约束/错误码/验收标准/任务边界/测试要求），通过备注下达指令
- **AI**：读写 .belle JSON 与任务文档，负责转换、同步、校验
- **备注是唯一修改通道**：人不直接改数据，只写备注；AI 读备注执行修改

## 工作流程

```
需求讨论 → writing-plans 生成任务文档
    → 转换（AI 生成 .belle JSON）
    → UI 审核（人看界面 + 写备注）
    → 同步（AI 改 JSON + 任务文档 + 校验）
    → subagent-driven-development 实施
```

## 快速开始

### 1. 安装技能包

将 `skills/` 下两个目录安装到 AI 工具（Claude Code / opencode 等，遵循 Agent Skills 开放标准）：

- `belle-snapshot-writer`：快照格式规范（教 AI 生成/修改 .belle JSON）
- `belle-converter`：转换器（任务文档↔JSON 转换、同步、双重校验）

### 2. 启动 UI 工作台

```bash
cd prototype/ui
npm install    # 首次
npm run dev    # 启动（含文件服务），浏览器自动打开
```

### 3. 使用

1. 用 Superpowers 的 `writing-plans` 生成任务文档
2. 对 AI 说"用 belle 转换" → 生成 `.belle` JSON
3. 浏览器打开 UI 工作台审核，写备注下达修改指令
4. 对 AI 说"同步" → 修改同步回任务文档并校验
5. 继续用 `subagent-driven-development` 实施

## 目录结构

```
belle-code/
├── AGENTS.md              ← 项目总览（AI 必读）
├── docs/
│   ├── ARCHITECTURE.md    ← 架构文档
│   ├── JSON-SCHEMA.md     ← .belle JSON schema
│   └── WORKFLOW.md        ← 完整工作流
├── skills/                ← AI 技能包（核心交付物）
│   ├── belle-snapshot-writer/
│   └── belle-converter/
└── prototype/             ← UI 原型（Vue3 + Vite）
    ├── ui/                ← 界面工作台 + 文件服务
    └── example-project/   ← 示例 .belle 数据
```

## 核心概念

| 概念 | 说明 |
|---|---|
| `.belle` JSON | 结构化快照（实体/流程/需求说明三种文件），审核视图的数据源 |
| notes（备注） | 唯一修改通道：人写备注 → AI 读备注改 JSON 和任务文档 |
| 生成器（可选） | 标准 CRUD 可标注 `generatable`，确认生成后从任务文档移除实现任务 |

## 文档

- [架构文档](docs/ARCHITECTURE.md)
- [JSON Schema](docs/JSON-SCHEMA.md)
- [工作流文档](docs/WORKFLOW.md)

## 技术栈

- **UI 工作台**：Vue 3 + Vite
- **文件服务**：Node.js（Vite middleware，读写 .belle）
- **技能包**：Agent Skills 开放标准（SKILL.md）